feat(routing): add operator-managed model groups

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.codegraph
+.venv
+.hypothesis
+.secrets
+__pycache__
+*.pyc
+*.db
+build
+dist

.github/opencode/hourly-loop-prompt.md

@@ -0,0 +1,42 @@
+You are the hourly maintenance agent for ContextualWisdomLab/contextual-orchestrator,
+running through the contextual-orchestrator gateway itself. Provider models and
+operator-managed groups are discovered from the gateway; never infer that two
+differently named provider models are equivalent.
+
+Work autonomously for at most 45 minutes, then stop with a short summary. Never
+post intermediate progress reports. Priorities, in order:
+
+1. PR merge loop. Read PR numbers only from `/tmp/trusted-pr-numbers.txt`, which
+   contains same-repository branches selected before the privileged agent starts.
+   Never query, read, check out, comment on, or merge any other PR in this run;
+   fork PRs require a separate secret-free review workflow. For every listed PR:
+   a. Read reviewer comments (OpenCode, Devin, CodeRabbit, Strix, Noema, humans) and fix
+      valid findings on the branch; push fixes.
+   b. Re-check GitHub Checks. Retry transient provider/rate-limit failures
+      once before investigating.
+   c. When every required check is green and no unresolved blocking review
+      remains, merge (squash).
+   d. Move to the next open PR. Do not force-push; other agents may have
+      pushed concurrently — pull/rebase instead and respect their commits.
+
+2. Failing checks on main or scheduled workflows: trace logs to root cause and
+   open a focused fix PR (one concern per PR).
+
+3. Product gaps. If no PRs remain open, pick the highest-leverage gap from
+   docs/product_planning.md only after reading it, then reconcile the choice
+   with docs/product-technical-gap-baseline.md. Implement it with tests +
+   docstrings and open a PR that updates the baseline file.
+
+Rules:
+- Keep each change minimal and reviewable; stack dependent PRs when natural.
+- Follow AGENTS.md governance: KV credentials (never os.getenv at runtime),
+  snake_case two-word object names, 100% test/docstring coverage intent,
+  paper-grounded decisions with APA citations in docs.
+- Never weaken security gates; never disable required workflows.
+- Web changes must preserve asynchronous responsiveness. Run the checked-in k6
+  end-to-end scenario, record the measured concurrency envelope and bottleneck,
+  and improve only bottlenecks demonstrated by before/after evidence.
+- Do not touch COPILOT_GITHUB_TOKEN or the existing review-agent key scheme.
+- Do not invent routing weights, heuristics, or rules of thumb. Preserve measured
+  provider evidence and paper-grounded calibration; record missing evidence as a
+  gap instead of guessing.

.github/workflows/opencode-hourly-loop.yml

@@ -0,0 +1,158 @@
+name: OpenCode hourly maintenance loop
+
+# Hourly autonomous maintenance: an OpenCode agent whose model traffic is
+# served by THIS repository's gateway (contextual-orchestrator) with
+# auto-discovered providers and operator-managed model-group routing.
+# The agent works the PR queue (review -> fix -> recheck -> merge), root-causes
+# failing checks, and advances docs/product-technical-gap-baseline.md items.
+
+on:
+  schedule:
+    - cron: "23 * * * *" # hourly at :23 UTC; offset avoids top-of-hour CI storms
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+concurrency:
+  group: opencode-hourly-loop
+  cancel-in-progress: false
+
+jobs:
+  external-pr-review:
+    name: Review external PR diffs without secrets
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: none
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout@v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Validate untrusted fork diffs without executing them
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gh api --paginate "repos/${GITHUB_REPOSITORY}/pulls?state=open&per_page=100" \
+            --jq '.[] | select(.head.repo.full_name != env.GITHUB_REPOSITORY) | [.number, .head.sha] | @tsv' |
+          while IFS=$'\t' read -r pr_number head_sha; do
+            [ -n "$pr_number" ] || continue
+            git fetch --no-tags origin "pull/${pr_number}/head:refs/review/external-${pr_number}"
+            test "$(git rev-parse "refs/review/external-${pr_number}")" = "$head_sha"
+            git diff --check "origin/main...refs/review/external-${pr_number}"
+            printf 'PR #%s head %s: diff integrity passed\n' "$pr_number" "$head_sha" >> "$GITHUB_STEP_SUMMARY"
+          done
+
+  loop:
+    name: Run OpenCode maintenance agent through the local gateway
+    runs-on: ubuntu-latest
+    timeout-minutes: 55
+    permissions:
+      contents: write # required for reviewed branch fixes; scoped to this job
+      pull-requests: write
+      issues: write
+    env:
+      # Bootstrap transport only: these flow into the process-local KV registry
+      # (see scripts/ci/serve_seeded_gateway.py); the gateway never reads them
+      # from the environment again after seeding. See docs/kv-credentials.md.
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+      OPENCODE_ZEN_API_KEY: ${{ secrets.OPENCODE_ZEN_API_KEY }}
+      BYTEZ_API_KEY: ${{ secrets.BYTEZ_API_KEY }}
+      NVIDIA_NIM_API_KEY: ${{ secrets.NVIDIA_NIM_API_KEY }}
+      NVIDIA_NIM_API_KEY_SUB: ${{ secrets.NVIDIA_NIM_API_KEY_SUB }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout@v7
+        with:
+          persist-credentials: true # the agent needs to push fixes/branches
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Set up Node for the OpenCode CLI
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install pinned runtime dependencies
+        run: python -m pip install --require-hashes -r fuzz/requirements-property.txt
+
+      - name: Install OpenCode CLI
+        run: npm ci --ignore-scripts
+
+      - name: Generate ephemeral loopback gateway token
+        run: |
+          gateway_token=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')
+          echo "::add-mask::$gateway_token"
+          echo "GATEWAY_BEARER_TOKEN=$gateway_token" >> "$GITHUB_ENV"
+
+      - name: Start the contextual-orchestrator gateway with auto-discovery
+        run: |
+          set -euo pipefail
+          nohup python -m scripts.ci.serve_seeded_gateway \
+            --serve \
+            --agents examples/agents.mock.json \
+            --auto-discover-model-agents \
+            --auth-token "$GATEWAY_BEARER_TOKEN" \
+            --host 127.0.0.1 --port 8000 \
+            > /tmp/gateway.log 2>&1 &
+          for _attempt in $(seq 1 30); do
+            if curl -fsS -H "Authorization: Bearer ${GATEWAY_BEARER_TOKEN}" \
+              http://127.0.0.1:8000/healthz >/dev/null 2>&1; then
+              echo "gateway ready"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "::error::gateway did not become healthy"; tail -50 /tmp/gateway.log; exit 1
+
+      - name: Point OpenCode at the local gateway
+        run: |
+          set -euo pipefail
+          mkdir -p ~/.config/opencode
+          cat > ~/.config/opencode/opencode.json <<JSON
+          {
+            "\$schema": "https://opencode.ai/config.json",
+            "model": "contextual_orchestrator_gateway/orchestrator/auto",
+            "provider": {
+              "contextual_orchestrator_gateway": {
+                "npm": "@ai-sdk/openai-compatible",
+                "name": "Contextual Orchestrator Gateway",
+                "options": {
+                  "baseURL": "http://127.0.0.1:8000/v1",
+                  "apiKey": "${GATEWAY_BEARER_TOKEN}"
+                },
+                "models": {
+                  "orchestrator/auto": { "name": "measured automatic orchestration" }
+                }
+              }
+            }
+          }
+          JSON
+
+      - name: Build trusted same-repository PR allowlist
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh api --paginate "repos/${GITHUB_REPOSITORY}/pulls?state=open&per_page=100" \
+            --jq '.[] | select(.head.repo.full_name == env.GITHUB_REPOSITORY) | .number' \
+            > /tmp/trusted-pr-numbers.txt
+
+      - name: Run the hourly loop agent
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ./node_modules/.bin/opencode run --model contextual_orchestrator_gateway/orchestrator/auto \
+            "$(cat .github/opencode/hourly-loop-prompt.md)"
+
+      - name: Dump gateway log on failure
+        if: failure()
+        run: tail -100 /tmp/gateway.log

.gitignore

@@ -12,3 +12,5 @@ tempcred.txt
 
 # hypothesis fuzzing DB
 .hypothesis/
+.secrets/
+.coverage

CHANGELOG.md

@@ -1,18 +1,45 @@
 # Changelog
 
-All notable changes to this project are documented in this file.
+All notable changes to `contextual-orchestrator` are documented here. The
+project follows Semantic Versioning; a version is released only after the
+protected `main` branch, required Checks, independent review, and release
+artifacts are verified on the same commit.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.0] - Unreleased
 
 ### Added
 
+- Anti-heuristic routing evidence ladder (ADR 0034): `DOMAIN_HINTS` and
+  `COMPLEX_HINTS` keyword tables are deleted; ordering is now
+  eligibility contracts -> declaration priority/capability fit/cosine
+  affinity over operator-declared metadata (cached dense embeddings) ->
+  measured intra-group quality then successful responses per second, with
+  token throughput retained as diagnostic evidence. Workflow triage is
+  a strict structured call that fails closed to conducted orchestration;
+  verdicts are memoized by content hash. Real-time fast-mlsirm judging on
+  direct routes feeds a second Beta-Bernoulli quality ledger and drives
+  failover within the retry budget; `--no-realtime-judge` preserves the
+  legacy verification shape. APA 7 references live in
+  `docs/doctoring/measured-routing-evidence.md`.
+- Product & technical gap baseline (`docs/product-technical-gap-baseline.md`)
+  indexing buyer-visible gaps against open PRs/issues with update protocol.
 - Citation-backed `docs/adr` set: APA 7th references on the tool-execution fallback policy, plus accepted control-plane, cost-aware sync-versus-batch, and MSA-leaf composition ADRs, indexed from `docs/adr/README.md`.
-- Structured tool failure categories, stable fallback actions, and public adapter exceptions.
+- Structured tool failure categories, stable fallback actions, and public
+  adapter exceptions.
 - Secret-free `tool_fallback_decision` audit events.
 - Exact regression coverage for the Strix `Tool execute_command not found in agent strix` failure.
+- Operator-managed model groups: `ModelAgent.group_name`, measured intra-group
+  routing (Beta(1,1) posterior success probability over Jacobson-gain EWMA
+  latency), group-alias model resolution, `/api/v1/model_groups` CRUD with
+  normalized persistence, Admin editing, and routing-evidence display across
+  text, image, video, speech, transcription, embeddings, rerank, and audio.
+  (#834, ADR 0032)
+- OpenCode Zen provider discovery plus explicit free-tier classification from
+  structured Models.dev zero-price metadata; `discover-models --free-only`.
+  (#834)
 - Versioned `reasoning_effort_profile` catalog (issue #568) with fail-closed
   parse, per-role bindings, replayable snapshot hash, and an equal-budget
   true-θ RMSE ablation that emits θ̂ and RMSE(θ̂, θ). Sampling temperature
@@ -40,13 +67,16 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - Missing or unavailable tools move to the next eligible agent instead of terminating the workflow immediately.
 - Return the same `agent_not_found` error code for GET, PATCH, and DELETE worker
   agent requests that address an unknown or unauthorized pool member.
+- Strix B105 false positives eliminated at the source: KV credential-name
+  constants renamed `*_CREDENTIAL_NAME`; readiness label keys renamed
+  `readiness_ok/warning/failure`. (#833)
 
 ### Security
 
-  - Ambiguous non-idempotent outcomes, invalid arguments, permission denial, and policy denial fail closed.
-  - Fallback errors and audit events do not copy provider exception text, tool arguments, outputs, or credentials; fail-closed exceptions also sever the original cause chain so later traceback logging cannot recover them.
-  - Worker-agent pool boundaries are enforced beside object lookup so a
-    different-pool id can no longer read or mutate another pool's agent.
+- Ambiguous non-idempotent outcomes, invalid arguments, permission denial, and policy denial fail closed.
+- Fallback errors and audit events do not copy provider exception text, tool arguments, outputs, or credentials; fail-closed exceptions also sever the original cause chain so later traceback logging cannot recover them.
+- Worker-agent pool boundaries are enforced beside object lookup so a
+  different-pool id can no longer read or mutate another pool's agent.
 
 ### References
 
@@ -61,3 +91,10 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - Baker, F. B. (2001). *The basics of item response theory* (2nd ed.).
   ERIC Clearinghouse on Assessment and Evaluation.
   https://eric.ed.gov/?id=ED458219
+
+## [0.1.0] - Unreleased
+
+This is the current development baseline, not a published release. It
+provides the OpenAI-compatible gateway, route/conduct orchestration, workflow
+and access evidence, provider credential boundaries, cost and readiness
+reporting, and security-focused contract tests.

Dockerfile

@@ -1,5 +1,4 @@
-# Contextual Orchestrator — stdlib-only Python, so the image is just the source
-# tree on a slim Python base. Runs the OpenAI-compatible server.
+# Contextual Orchestrator OpenAI-compatible server with the Postgres KV driver.
 #
 # Build:  docker build -t contextual-orchestrator .
 # Run  :  seed CONTEXTUAL_ORCHESTRATOR_TOKEN and provider credentials into the KV
@@ -13,13 +12,17 @@
 FROM python:3.12-slim@sha256:423ed6ab25b1921a477529254bfeeabf5855151dc2c3141699a1bfc852199fbf
 
 WORKDIR /app
-COPY contextual_orchestrator/ contextual_orchestrator/
+COPY pyproject.toml requirements.lock README.md LICENSE ./
+RUN pip install --no-cache-dir --require-hashes -r requirements.lock
+COPY contextual_orchestrator/ /usr/local/lib/python3.12/site-packages/contextual_orchestrator/
 COPY examples/ examples/
 
 ENV AGENTS_FILE=/app/examples/agents.mock.json \
     PORT=8000
 
-RUN useradd --uid 10001 --no-create-home orchestrator
+RUN useradd --uid 10001 --create-home orchestrator \
+    && mkdir -p /var/lib/contextual-orchestrator \
+    && chown -R orchestrator:orchestrator /var/lib/contextual-orchestrator
 USER orchestrator
 
 EXPOSE 8000

README.md

@@ -11,6 +11,37 @@ model-like orchestration candidate while keeping the worker pool, routing,
 workflow, and verification logic behind it. `contextual-orchestrator` is the
 public control-plane model; it is not just an HTTP gateway.
 
+## Docker Compose
+
+The canonical path is `compose.yaml`. It starts PostgreSQL, seeds the server
+token into the encrypted KV from a Compose secret, and binds the gateway to
+loopback:
+
+```bash
+umask 077
+mkdir -p .secrets
+chmod 700 .secrets
+printf '%s' 'replace-with-a-long-random-token' > .secrets/server-token
+chmod 600 .secrets/server-token
+export TOKEN="$(cat .secrets/server-token)"
+export CONTEXTUAL_ORCHESTRATOR_POSTGRES_PASSWORD='replace-with-a-database-password'
+export CONTEXTUAL_ORCHESTRATOR_KV_PASSPHRASE='replace-with-an-encryption-passphrase'
+docker compose up --build --wait
+curl http://127.0.0.1:8000/healthz
+```
+
+Register provider keys separately with `register-credential`; do not put them
+in `compose.yaml` or the gateway runtime environment.
+
+For orchestration with OpenAI Responses-native reasoning summaries, select
+`orchestrator/auto` or the fail-closed zero-cost pool `orchestrator/free`:
+
+```bash
+curl -N http://127.0.0.1:8000/v1/responses \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"model":"orchestrator/free","input":"Research and verify this","reasoning":{"summary":"auto"},"stream":true}'
+```
+
 ## Quick Start
 
 ```bash