feat: publish paper-grounded automatic orchestration contract

.adr-config.yml

@@ -0,0 +1,6 @@
+project_slug: contextual-orchestrator
+owner: ContextualWisdomLab
+default_status: proposed
+decision_id_format: NNNN
+template_source: madr-v4
+last_decision_id: 0009

.github/dependabot.yml

@@ -7,6 +7,8 @@ updates:
       day: monday
       time: "04:00"
       timezone: Asia/Seoul
+    cooldown:
+      default-days: 7
     open-pull-requests-limit: 5
 
   - package-ecosystem: pip
@@ -16,4 +18,6 @@ updates:
       day: monday
       time: "04:30"
       timezone: Asia/Seoul
+    cooldown:
+      default-days: 7
     open-pull-requests-limit: 5

.github/workflows/fuzz.yml

@@ -53,10 +53,11 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python
-        # Atheris ships wheels/builds cleanly for 3.11 (Clang + libFuzzer).
+        # Atheris 3.1.0 dropped the cp311 wheel; use the same cp312-compatible
+        # pin that the central CPython 3.14 coverage-evidence image preflights.
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # actions/setup-python@v6
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Install Atheris
         # Hash-pinned per OpenSSF Scorecard Pinned-Dependencies. Sources:
@@ -72,16 +73,19 @@ jobs:
           fi
 
       - name: Fuzz request-body parser
-        run: python fuzz/fuzz_request_body.py -max_total_time=${FUZZ_SECONDS} -artifact_prefix=crash- fuzz/corpus/request_body
+        run: python fuzz/fuzz_request_body.py -max_total_time="${FUZZ_SECONDS}" -artifact_prefix=crash- fuzz/corpus/request_body
 
       - name: Fuzz agent-config parser
-        run: python fuzz/fuzz_agent_config.py -max_total_time=${FUZZ_SECONDS} -artifact_prefix=crash- fuzz/corpus/agent_config
+        run: python fuzz/fuzz_agent_config.py -max_total_time="${FUZZ_SECONDS}" -artifact_prefix=crash- fuzz/corpus/agent_config
 
       - name: Fuzz secret redaction
-        run: python fuzz/fuzz_redaction.py -max_total_time=${FUZZ_SECONDS} -artifact_prefix=crash- fuzz/corpus/redaction
+        run: python fuzz/fuzz_redaction.py -max_total_time="${FUZZ_SECONDS}" -artifact_prefix=crash- fuzz/corpus/redaction
 
       - name: Fuzz orchestration engine
-        run: python fuzz/fuzz_orchestration.py -max_total_time=${FUZZ_SECONDS} -artifact_prefix=crash- fuzz/corpus/orchestration
+        run: python fuzz/fuzz_orchestration.py -max_total_time="${FUZZ_SECONDS}" -artifact_prefix=crash- fuzz/corpus/orchestration
+
+      - name: Fuzz model-judge response parser
+        run: python fuzz/fuzz_model_judge.py -max_total_time="${FUZZ_SECONDS}" -artifact_prefix=crash- fuzz/corpus/judge
 
       - name: Upload crash artifacts
         if: failure()

AGENTS.md

@@ -71,8 +71,19 @@ push or open a PR.
 - Its `ModelClient` currently reads `os.environ.get(agent.api_key_env)` — this
   is the KV-principle deviation above. Resolve the API key (including the org
   `OPENAI_API_KEY`) from the **KV / credential registry**, not env.
-- The **OpenCode review pipeline is separate** and stays on **GitHub Models** —
-  do not change it.
+- **Policy change (2026-08-18, explicit org decision, supersedes the prior
+  "stays on GitHub Models" rule):** OpenCode, Noema, and Strix — the org's
+  three-stage CI review pipeline defined in `ContextualWisdomLab/.github`
+  (`opencode.jsonc`, `noema-review.yml`, `strix.yml`) — are being migrated to
+  use `contextual-orchestrator` as their shared backend, with
+  `BYTEZ_API_KEY`, `NVIDIA_NIM_API_KEY`, `NVIDIA_NIM_API_KEY_SUB`,
+  `OPENROUTER_API_KEY`, and `OPENAI_API_KEY` registered in this repo's KV so
+  it auto-discovers models across all five and auto-optimizes routing by
+  cost (see `contextual_orchestrator/model_discovery.py`, the
+  `discover-models` CLI subcommand, and `ModelAgent.auth_scheme` for
+  non-Bearer providers like Bytez). The provider-config change to the org
+  repo itself lands as a separate, human-reviewed PR — this repo does not
+  push or merge it automatically.
 
 ### This repo's role in the ecosystem
 
@@ -108,4 +119,27 @@ push or open a PR.
   cost-optimal LLM routing, upstream load balancing, and latency/throughput
   scheduling (e.g. LLM-cascade / model-routing and queueing/load-balancing
   papers).
+
+### Model and reasoning policy
+
+- Model selection, reasoning-effort allocation, orchestration topology, and
+  claims about quality/cost trade-offs must be grounded in cited academic
+  papers and current capability evidence. Do not introduce a model policy from
+  a vendor blog, benchmark marketing claim, or an implementation convention.
+  The governing decision is [ADR 0011](docs/planning/adrs/0011-paper-grounded-adaptive-reasoning-policy.md).
+- `auto` is an orchestrator policy, not a provider `reasoning_effort` value. It
+  may select a provider-supported value or an orchestrated multi-agent path,
+  but the trace must retain the requested policy and the effective strategy.
+- Provider values are capability-negotiated. Do not send `none`, `minimal`,
+  `low`, `medium`, `high`, or `xhigh` unless the selected provider advertises
+  that value; omit the field for a non-reasoning provider. Never infer support
+  from a model name.
+- `high` and `xhigh` may require multiple independent attempts, verification,
+  and synthesis when one worker cannot provide the requested capability. That
+  is an orchestrator strategy, not a claim that a non-reasoning worker became a
+  reasoning model.
+- MLX is not a public provider contract. Keep runtime-specific local model
+  behavior behind an authenticated provider-neutral gateway as specified by
+  ADR 0010; do not add direct `mlx://` configuration, transport, or model
+  selection logic.
 <!-- END cwl-agent-guidance -->

CLAUDE.md

@@ -8,7 +8,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 - **Security gate**: every PR to `main` runs the required Security workflow. A failing Trivy or pip-audit job is a real finding — remediate by bumping the dependency and regenerating `requirements.lock`; never weaken, `continue-on-error`, or disable the gate.
 - **KV, not env**: runtime config and provider secrets are resolved from the KV credential registry (`get_credential`), never `os.getenv` at request time. Env is only bootstrap transport into the KV (see `docs/kv-credentials.md`).
-- **Org role**: this repo is the org's LLM gateway (cost optimizer + sync/batch routing + upstream load balancing, LiteLLM-plus scope), consumed by `gyeot` and `scopeweave`. The OpenCode review pipeline is separate, stays on GitHub Models, and must not be changed.
+- **Org role**: this repo is the org's LLM gateway (cost optimizer + sync/batch routing + upstream load balancing, LiteLLM-plus scope), consumed by `gyeot` and `scopeweave`. As of 2026-08-18, OpenCode/Noema/Strix (the org's CI review pipeline in `ContextualWisdomLab/.github`) are being migrated onto this gateway as their shared backend — see AGENTS.md's "This repo: the org LLM gateway" section for the full policy and scope.
 - **Research grounding**: substantive feature/process PRs should attach the relevant papers (PDF when redistribution is permissible, otherwise cite + link + summary) under `docs/papers/` with full citations.
 
 This file complements AGENTS.md with commands and architecture; where they differ, AGENTS.md wins.
@@ -44,8 +44,9 @@ python fuzz/fuzz_request_body.py -max_total_time=60 fuzz/corpus/request_body
 python -m contextual_orchestrator "your prompt" --agents examples/agents.mock.json
 
 # Serve the OpenAI-compatible API + /admin console
-export CONTEXTUAL_ORCHESTRATOR_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
-python -m contextual_orchestrator --serve --agents examples/agents.mock.json --port 8000
+local_token="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+python -m contextual_orchestrator --serve --agents examples/agents.mock.json --port 8000 \
+  --auth-token "$local_token"
 
 # Loopback-only local dev server (auth disabled; loopback only)
 ./.superset/run.sh

Dockerfile

@@ -2,10 +2,11 @@
 # tree on a slim Python base. Runs the OpenAI-compatible server.
 #
 # Build:  docker build -t contextual-orchestrator .
-# Run  :  docker run --rm -p 8000:8000 \
-#           -e CONTEXTUAL_ORCHESTRATOR_TOKEN=change-me \
-#           -e OPENAI_API_KEY=sk-... \
-#           contextual-orchestrator
+# Run  :  seed CONTEXTUAL_ORCHESTRATOR_TOKEN and provider credentials into the KV
+#        registry first, then use:
+#        docker run --rm -p 8000:8000 contextual-orchestrator
+# Runtime secrets are never passed through the container environment or argv;
+# see docs/kv-credentials.md for the bootstrap flow.
 # Agents: defaults to the bundled mock pool; mount your own and set AGENTS_FILE:
 #           -v ./agents.json:/app/agents.json -e AGENTS_FILE=/app/agents.json
 # python:3.12-slim
@@ -26,4 +27,4 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
   CMD ["python", "-c", "import urllib.request,os;urllib.request.urlopen(f'http://127.0.0.1:{os.environ.get(\"PORT\",\"8000\")}/healthz', timeout=2)"]
 
 # --allow-public-bind: 컨테이너 내부 0.0.0.0 바인딩 필요(외부 노출은 호스트 포트 매핑이 결정)
-CMD ["sh", "-c", "python -m contextual_orchestrator --serve --agents \"$AGENTS_FILE\" --host 0.0.0.0 --port \"$PORT\" --allow-public-bind"]
+CMD ["sh", "-c", "python -m contextual_orchestrator --serve --agents \"$AGENTS_FILE\" --host 0.0.0.0 --port \"$PORT\" --allow-public-bind --auth-token-key CONTEXTUAL_ORCHESTRATOR_TOKEN"]