@hecer/yoke 1.1.1 → 1.2.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "yoke",
   "displayName": "Yoke",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Cross-agent coding harness: one curated skill canon (TDD, brainstorming, plans, reviews, shipping, design verification) plus mechanical safety gates and an autonomous loop via the yoke CLI.",
   "author": { "name": "HECer", "url": "https://github.com/HECer" },
   "homepage": "https://github.com/HECer/yoke#readme",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Cross-agent coding discipline, mechanical gates, and release workflows",
   "skills": "./canon/skills/",
   "hooks": "./hooks/hooks.json"

package/CHANGELOG.md

@@ -1,6 +1,21 @@
-# Changelog
-
-## 1.1.0 — 2026-07-30
+# Changelog
+
+## 1.2.0 — 2026-08-02
+
+### Added
+- Opt-in adaptive model routing lets a strong parent orchestrate each bounded story while Yoke selects an available Claude, Codex, or Gemini worker by quality, speed, cost, or balanced strategy.
+- A concurrency-safe local evidence registry learns from independent verification results without sharing mutable state between simultaneous Yoke processes.
+- Routing telemetry, reproducible benchmark fixtures, and analysis tooling make worker selection, token use, timing, and gate outcomes auditable.
+
+### Changed
+- Setup keeps routing disabled unless explicitly enabled and validates provider/model worker pools before execution.
+- Internal provider contract tests cover Claude Code, Codex CLI, and Gemini CLI through the shared adapter. Codex-only authenticated trials completed all 12 stories and 36 hidden checks; median routed runs used 11.0% fewer fresh input tokens, 49.5% fewer output tokens, 78.2% fewer reasoning tokens, and 33.8% less wall time than routing off.
+
+### Fixed
+- Reviewer prompts now permit their required verdict file while continuing to forbid project changes.
+- Failed reviewer subprocesses retain bounded provider stderr in loop status, exposing authentication, quota, sandbox, and startup failures instead of a generic command error.
+
+## 1.1.0 — 2026-07-30
 
 ### Added
 - Shared five-question `yoke setup` wizard with provider-aware defaults for Claude, Codex, and Gemini.

package/README.md

@@ -2,8 +2,8 @@
 
 # 🐂 Yoke
 
-<!-- yoke:version:start -->1.1.1<!-- yoke:version:end -->
-<!-- yoke:tests:start -->559<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.2.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->582<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->29<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini<!-- yoke:agents:end -->
 
@@ -25,7 +25,7 @@
 
 </div>
 
-> **TL;DR** — `yoke setup .` asks five questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it story by story behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. If any gate is red, nothing is committed. When a story is done, there's a photo of it in `.yoke/proof/<story>/`.
+> **TL;DR** — `yoke setup .` asks six questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it story by story behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. If any gate is red, nothing is committed. When a story is done, there's a photo of it in `.yoke/proof/<story>/`.
 
 Yoke 1.1 is safe-by-default: provider CLIs use autonomous sandbox profiles unless `--unsafe`
 is explicit; reviews require a schema-valid verdict and a different model unless
@@ -85,7 +85,7 @@ yoke new my-app --idea="a CLI that tracks reading lists"
 yoke loop on my-app && yoke loop run my-app --isolate
 
 # — or retrofit an existing project —
-yoke setup /path/to/project                                  # interactive: agents, graph, loop, runner, decisions
+yoke setup /path/to/project                                  # interactive: agents, graph, loop, runner, decisions, routing
 yoke validate canon                                          # sanity-check the canon
 yoke loop run /path/to/project --isolate --reviewer=codex --max=20
 ```
@@ -104,7 +104,7 @@ The canon is also packaged as a Claude Code plugin — the repo is its own marke
 That gives you all canon skills under the `yoke:` namespace (e.g. `yoke:tdd`, `yoke:review`) inside Claude Code — no retrofit needed. The `yoke` CLI (loop, gates, retrofit for Codex/Gemini) still comes from `npm i -g @hecer/yoke`. Gemini CLI users can likewise `gemini extensions install https://github.com/HECer/yoke`.
 
 For Codex, no preinstalled skill is required: run `npx @hecer/yoke setup .` in a terminal, or
-ask Codex to run the five-question Yoke setup flow. The retrofit writes native skills to
+ask Codex to run the six-question Yoke setup flow. The retrofit writes native skills to
 `.agents/skills/`, including `yoke-retrofit` and `yoke-workflow`; start a fresh Codex task if an
 already-open task does not discover newly installed skills. The npm package also contains
 `.codex-plugin/plugin.json` for Codex plugin hosts.
@@ -138,7 +138,7 @@ Yoke is meant to be operated *by* your coding agent — after a retrofit, the ag
 
 > **Watch / unblock** — *"Run `yoke loop status .`. If it says BLOCKED, run the project's verify command, find the root cause, fix it without weakening tests, then continue the loop."*
 
-> ⚠️ **Long runs from inside an agent session:** a multi-story `yoke loop run` outlives most agents' shell-tool timeouts (Claude Code's Bash tool defaults to 2 minutes). If the outer tool call is killed mid-run, you get a stale lock and possibly half-finished state — which *looks* like a hang. Rules of thumb: run the loop **in the background** (e.g. Claude Code's `run_in_background`), keep batches small (`--max=3..5`), poll with `yoke loop status`, and after any interrupted run do `yoke loop cleanup` before the next one. A `running` status with no update for 20+ minutes on a claude runner is worth checking — since 0.5.0 the runner streams continuously, so prolonged true silence is no longer normal.
+> ⚠️ **Long runs from inside an agent session:** `yoke loop run` has no story cap by default; it continues until every planned story passes or a gate blocks. A multi-story run can therefore outlive most agents' shell-tool timeouts (Claude Code's Bash tool defaults to 2 minutes). If the outer tool call is killed mid-run, you get a stale lock and possibly half-finished state — which *looks* like a hang. Run the loop **in the background** (e.g. Claude Code's `run_in_background`), use `--max=3..5` only when you intentionally want a bounded batch, poll with `yoke loop status`, and after any interrupted run do `yoke loop cleanup` before the next one. A `running` status with no update for 20+ minutes on a claude runner is worth checking — since 0.5.0 the runner streams continuously, so prolonged true silence is no longer normal.
 
 > ⚠️ **Never kill agent processes by name or command-line pattern** (e.g. every process matching `dangerously-skip-permissions`): on a machine running several yoke projects, that takes down the *healthy* runners of the other projects mid-story — they stall and their loops block. `yoke loop cleanup` is the scoped alternative: each watchdog records its pids in the project's `.yoke/runner.pid`, and cleanup kills exactly those recorded trees — nothing else on the machine.
 
@@ -148,14 +148,14 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 
 | Command | What it does | Exit codes |
 |---|---|---|
-| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--decision-policy=] [--loop\|--no-loop]` | Shared five-question setup for Claude, Codex, and Gemini; `--yes` applies supplied/default choices non-interactively | `0` · `1` invalid setup |
+| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--decision-policy=] [--loop\|--no-loop] [--routing\|--no-routing]` | Shared six-question setup for Claude, Codex, and Gemini; adaptive routing is always an explicit opt-in | `0` · `1` invalid setup |
 | `yoke validate [canonDir]` | Validate the canon (schema, frontmatter, templates) | `0` valid · `1` errors |
 | `yoke new <dir> [--idea=] [--agent=] [--runner=] [--loop]` | Greenfield bootstrap: git init → scaffold → retrofit → context → PRD (drafted from `--idea`) → committed | `0` · `1` usage / non-empty dir / draft failed (scaffold survives) · `2` draft agent unavailable |
 | `yoke retrofit [dir] [--agent=claude,codex,gemini\|all] [--code-graph=graphify\|serena] [--loop]` | Install/update the harness, non-destructively | `0` |
 | `yoke prd draft [dir] --idea= [--runner=] [--force]` | Idea → 5–12 stories with testable acceptance criteria | `0` · `1` invalid/guarded · `2` agent unavailable |
 | `yoke prd check [dir]` | PRD lint gate (schema, dependencies, cycles, duplicate ids, acceptance) | `0` valid · `1` violations |
 | `yoke context init\|status [dir]` | Durable context layer (`PROJECT/DECISIONS/KNOWLEDGE.md`) | `0` |
-| `yoke loop on\|off\|status\|decision\|answer\|resume\|run\|cleanup [dir]` | Autonomous loop; `decision` shows a critical stop, `answer` records it and resumes, `resume` retries a failed restart with the preserved safety options; cleanup deletes worktrees only with `--remove-worktrees` | run: `0` complete · `1` blocked/cap · `2` not runnable / already locked · `3` paused |
+| `yoke loop on\|off\|status\|decision\|answer\|resume\|run\|cleanup [dir]` | Autonomous loop; `run` is unlimited by default and `--max=N` creates an intentional batch cap; `decision` shows a critical stop, `answer` records it and resumes, `resume` retries a failed restart with the preserved safety options | run: `0` complete · `1` blocked/cap · `2` not runnable / already locked · `3` paused |
 | `yoke review [dir] [--reviewer=] [--base=] [--focus=] [--json] [--allow-self-review]` | An independent model writes a schema-valid verdict | `0` approved · `1` findings/invalid verdict · `2` no independent reviewer |
 | `yoke audit [dir] [--json]` | Dependency, high-confidence secret, and sensitive-change audit | `0` green · `1` blocking findings · `2` not runnable |
 | `yoke design-scan [dir] [--max=N] [--report]` | Static AI-slop design gate | `0` within budget · `1` over |
@@ -330,8 +330,8 @@ yoke loop run . \
   --runner=codex \               # implement with Codex…
   --reviewer=claude \            # …review with Claude (role separation)
   --isolate \                    # each story in a throwaway git worktree
-  --decision-policy=critical \   # pause only for high-impact decisions; routine choices stay autonomous
-  --max=20
+  --decision-policy=critical     # pause only for high-impact decisions; routine choices stay autonomous
+# Optional: add --max=20 only when this run should stop after a bounded batch.
 yoke loop off .                 # disable
 ```
 
@@ -370,11 +370,9 @@ Every iteration emits token-free, harness-side feedback (Node console + local fi
   NDJSON line on stdout (`{"type":"status","state":"running","phase":"verifying",…}` — the
   same shape as `loop-status.json`), the human narrative moves off stdout (the final summary
   goes to stderr), and a consumer can follow the stream line by line instead of polling the file.
-  With a **claude** runner, json mode also switches the agent to `--output-format stream-json`
-  and accounts its usage: statuses (file + stream) carry a cumulative
-  `tokens: { inputTokens, outputTokens, model? }` field for the whole run — `model` is the
-  last model id seen on the stream (e.g. `claude-opus-4-6-20260501`), omitted if the CLI
-  never reported one.
+  Provider JSON streams are also accounted: statuses (file + stream) carry cumulative input and
+  output tokens for the whole run plus provider-reported cache-read, cache-write, reasoning, model,
+  and cost fields when available. Missing values stay absent—Yoke does not estimate them.
 
 ### Pausing a run
 
@@ -434,9 +432,65 @@ cannot begin because a provider/reviewer is unavailable or another process owns
 until a loop actually runs. To intentionally abandon an orphaned or stale private resume state,
 use `yoke loop resume . --discard`; pending decisions are never deleted by that command. Existing
 `loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` remain supported as compatibility aliases;
-new projects should use `decisionPolicy: auto|critical`.
-
-### Performance budgets: efficiency as a gate, not a style
+new projects should use `decisionPolicy: auto|critical`.
+
+### Adaptive model routing (explicit opt-in)
+
+`yoke setup` asks before enabling routing; the default is **off**. When enabled, the selected
+parent remains the strong planner/controller. Before each bounded story it receives only the
+story, acceptance criteria, and at most three eligible worker profiles, then returns one
+machine-readable choice. The worker can be a cheaper/faster Claude, Codex, or Gemini profile;
+`SELF` keeps difficult work on the parent. Provider-native subagents are disabled for these
+runs so Yoke does not pay for two orchestration layers.
+
+**Provider support:** adaptive routing uses Yoke's shared provider adapter and works with Claude
+Code, Codex CLI, and Gemini CLI, including mixed-provider worker lists. Internal contract tests
+cover invocation and routing behavior for all three providers. The measured performance evidence
+below is intentionally **Codex-only**; it does not claim equivalent Claude or Gemini savings
+until authenticated, repeated in-the-wild runs exist for those providers.
+
+```yaml
+runner:
+  agent: codex
+  model: gpt-5.6-sol       # optional; provider model strings stay opaque to Yoke
+  reasoningEffort: high
+routing:
+  enabled: true            # setup defaults false; setup --routing opts in
+  strategy: balanced       # balanced | cost | speed | quality
+  maxCandidates: 3
+  workers:
+    - id: codex-light
+      agent: codex
+      reasoningEffort: low
+      costTier: medium
+      capabilities: [exploration, implementation, tests]
+    - id: claude-fast
+      agent: claude
+      model: haiku         # rolling alias; omit to use the provider's current default
+      reasoningEffort: low
+      costTier: low
+      capabilities: [mechanical-edits, tests]
+    - id: gemini-auto
+      agent: gemini        # omitted model means the account's current Auto/default route
+      costTier: low
+      capabilities: [large-context, implementation]
+```
+
+Use `yoke loop run . --routing` for a one-run opt-in or `--no-routing` for a controlled
+baseline. Routing control calls are read-only and deliberately tiny; malformed output or no
+eligible worker falls back to `SELF`. Yoke does not ship a universal, fast-aging
+"intelligence score". Candidate model IDs come from project configuration while setup defaults
+prefer rolling aliases or provider Auto/defaults. A per-user registry learns only from Yoke's
+independent verify/performance/audit/review gates, keyed by worker + provider + model/effort and expired
+after 30 days. It stores no prompts, source, or project paths—only a project hash and aggregate
+time/token/outcome evidence. Writes are immutable one-event files, so concurrent Yoke instances
+cannot overwrite a shared registry file.
+
+Routing is not free: it adds one controller call per story. It is most promising when a bounded
+worker saves more than that call costs; tiny stories may be slower. Keep it opt-in and measure it
+on your own backlog rather than assuming a win.
+
+### Performance budgets: efficiency as a gate, not a style
 
 Clean code is the default (the `minimal-code` skill) — but when efficiency matters, "should
 be fast" is a vibe the loop cannot enforce. Yoke makes it mechanical, at two levels:
@@ -598,12 +652,24 @@ Yoke's guardrails are **mechanical, not advisory** — the loop blocks on a dirt
 | Best for | rapid exploration / migration / onboarding | systematic refactoring in typed codebases |
 | Caveat | heuristic edges; static index can go stale | one language server per language |
 
-## 🪙 Token efficiency
+## 🪙 Token efficiency
 
 Yoke attacks tokens on two complementary surfaces:
 
 - **rtk** compresses noisy command/tool output before it enters context (wired as a hook/instruction per agent).
-- The **`minimal-code`** skill installs a YAGNI / "lazy senior dev" ladder so agents write the least code that solves the task — fewer output tokens, smaller review surface. *(Adapted from the MIT-licensed [ponytail](https://github.com/DietrichGebert/ponytail) ruleset.)*
+- The **`minimal-code`** skill installs a YAGNI / "lazy senior dev" ladder so agents write the least code that solves the task — fewer output tokens, smaller review surface. *(Adapted from the MIT-licensed [ponytail](https://github.com/DietrichGebert/ponytail) ruleset.)*
+
+A Codex-only full-repository study ran three alternating-order pairs per arm. The same Sol parent
+completed all 12 stories and all **36/36 hidden acceptance checks**; with routing enabled, a Sol
+controller selected Luna for every bounded implementation story. Including controller overhead,
+the routed median used **33.8% less wall time, 11.0% less fresh input, 49.5% fewer output tokens,
+and 78.2% fewer reasoning tokens**. All three pairs improved wall time and fresh input.
+
+The boundary matters: an earlier architecture/privacy task correctly stayed on `SELF` and paid
+controller overhead, so routing is an explicit opt-in rather than a universal win. Codex did not
+emit dollar cost for these plan-backed runs; Yoke reports the measured token breakdown instead of
+inventing a price. Method, ranges, controller cost, caveats, analyzer, and six raw JSON rows are in
+[`bench/RESULTS.md`](bench/RESULTS.md#codex-only-full-repository-routing-study-2026-08-02).
 
 ## 🧩 Optional companions
 
@@ -647,7 +713,7 @@ parallel dispatcher, broader benchmark samples, native output schemas, and relea
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (559 tests)
+npm test          # vitest (579 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/bench/README.md

@@ -1,42 +1,74 @@
 # Yoke benchmark — tokens · speed · quality
 
-Reproducible cross-runner benchmark for the Yoke loop. One fixed fixture project, the same
-PRD for every runner, three measured dimensions:
+Reproducible cross-runner and routing A/B benchmarks for the Yoke loop. Fixed fixture projects,
+the same PRD within each comparison, and three measured dimensions:
+
+Adaptive routing is implemented for Claude Code, Codex CLI, and Gemini CLI. The checked-in
+multi-run performance study currently measures Codex only; provider support tests are not treated
+as performance evidence for Claude or Gemini.
 
 | Dimension | How it is measured |
 |---|---|
-| **Tokens** | The loop's own token hook (`.yoke/loop-status.json`, claude runner via `--output-format stream-json`; model id included). Gemini/Codex runners do not report usage yet — recorded as `null`, a documented gap. |
+| **Tokens** | The loop's own provider telemetry in `.yoke/loop-status.json`, split into total input, cached input, fresh input (`input − cached`), output, and reasoning tokens when the provider reports them. Adaptive runs preserve one entry per orchestrator/worker call. Missing telemetry is `null`, never estimated. |
 | **Speed** | Wall-clock, measured by the harness from outside: total run + per-story (from `--json` NDJSON event timestamps). The loop itself stores no durations. |
 | **Quality** | Objective, not judged by any model: the fixture ships **pre-written tests** the agent never has to write (only satisfy). After the run, each story's test file is executed against the final tree. `srcLoc` (non-empty lines in `src/`) is a code-economy proxy. |
 
-## The fixture (`fixtures/string-kit`)
+## The fixture (`fixtures/string-kit`)
 
 A dependency-free ESM library with 3 stories (`slugify`, `truncate`, `titleCase`) and 16
 `node:test` assertions total. `bench-verify.mjs` is cumulative: story N runs the tests of
 stories 1…N (the loop exports `YOKE_STORY`), so later stories cannot break earlier work; the
 final quality check runs everything. No npm installs, so results measure the agent — not the
-network.
+network.
+
+## The routing fixture (`fixtures/routing-queue`)
+
+A dependency-free in-memory priority queue with two cumulative stories and 10 pre-written
+`node:test` cases covering idempotency, priority/FIFO ordering, leases, retry/backoff, dead
+letters, expired lease recovery, filters, and state statistics. It is intentionally substantial
+enough that a lower-cost worker can potentially repay one routing-controller call per story.
 
 ## Running it
 
 ```bash
 npm run build
-node bench/run.mjs --runner=claude   # or gemini / codex
-node bench/run-matrix.mjs --label=release-1.0
+node bench/run.mjs --runner=claude   # or gemini / codex
+node bench/run.mjs --runner=codex --fixture=routing-queue --routing=off --unsafe --run-root=G:\NN-Developed\Yoke-Testground
+node bench/run.mjs --runner=codex --fixture=routing-queue --routing=on  --unsafe --run-root=G:\NN-Developed\Yoke-Testground
+node bench/run-large.mjs --seed=G:\NN-Developed\Yoke-Testground\yoke-large-seed-2026-08-02 --routing=off --run-root=G:\NN-Developed\Yoke-Testground
+node bench/run-large.mjs --seed=G:\NN-Developed\Yoke-Testground\yoke-large-seed-2026-08-02 --routing=on  --run-root=G:\NN-Developed\Yoke-Testground
+node bench/run-large.mjs --seed=G:\NN-Developed\Yoke-Testground\yoke-codex-study-seed-2026-08-02 --routing=on  --label=codex-only-pair1-on  --run-root=G:\NN-Developed\Yoke-Testground
+node bench/run-large.mjs --seed=G:\NN-Developed\Yoke-Testground\yoke-codex-study-seed-2026-08-02 --routing=off --label=codex-only-pair1-off --run-root=G:\NN-Developed\Yoke-Testground
+node bench/analyze-routing-study.mjs
+node bench/run-matrix.mjs --label=release-1.0
 ```
 
-Each run copies the fixture to `bench/.runs/<runner>-<stamp>` (git-ignored), git-inits it,
-drives `yoke loop run --json --max=6 --timeout=10`, and writes a result JSON to
+Each run copies the fixture to `bench/.runs/<fixture>-<runner>-<routing>-<stamp>` (or the
+explicit `--run-root`), git-inits it,
+drives `yoke loop run --json --max=6 --timeout=10`, and writes a result JSON to
 `bench/results/`. Runs are billed against your own accounts for the agent CLIs involved.
 The matrix is sequential to avoid cross-provider load distortion. Missing CLIs and authentication
-failures are stored as honest `unavailable`/`auth-failed` rows and never presented as quality measurements.
+failures are stored as honest `unavailable`/`auth-failed` rows and never presented as quality measurements.
+
+`run-large.mjs` accepts an external full-repository seed, starts each arm with a separate empty
+routing registry, junctions this checkout's dependencies, and replays the seed's original
+acceptance tests under fresh filenames after the agent run. This prevents an agent editing a
+visible test from turning into false benchmark evidence. A seed can provide `bench-acceptance.json`
+to declare its fixture identity and hidden-test files. `analyze-routing-study.mjs` validates and
+aggregates the checked-in three-pair Codex-only study.
 
 ## Caveats (read before quoting numbers)
 
-- **N=1 per run.** Agent runs are stochastic; treat single runs as indicative, not
-  statistically robust. Re-run and compare.
-- Model identity matters more than CLI identity: `tokens.model` records what actually served
-  the run. Different default models per CLI make "claude vs gemini" really "model X vs model Y".
+- Agent runs are stochastic. Older rows are N=1; the 2026-08-02 Codex-only study uses three
+  alternating-order pairs per arm. Re-run before setting broad policy defaults.
+- Compare routing on/off only when fixture, parent model/effort, permissions, native-subagent
+  policy, and host load are controlled. The checked-in routing fixture uses `runner.bare: true`
+  to exclude personal MCP/plugin startup from both sides.
+- Model identity matters more than CLI identity: `tokens.model` records what actually served
+  the run. Different default models per CLI make "claude vs gemini" really "model X vs model Y".
+- Codex input telemetry includes cache reads. Compare both total input and fresh input; do not
+  treat cached input as equivalent to newly processed input. Dollar cost is reported only when
+  the provider emits it—Yoke does not guess prices from a model name.
 - The fixture is deliberately small (a loop-overhead + basic-competence probe, minutes not
   hours). It does not measure large-context refactoring, UI work, or long-horizon planning.
 - Cumulative verify means a story's duration includes fixing any regressions it caused.

package/bench/RESULTS.md

@@ -17,9 +17,104 @@ Fixture `string-kit` (3 stories, 16 pre-written assertions). Methodology and cav
 | 2026-07-10 | gemini | — | ⛔ blocked: CLI not authenticated on the bench machine (headless needs `GEMINI_API_KEY` or configured OAuth) | — | — | — | — | — |
 | — | codex | — | ⛔ not installed on the bench machine | — | — | — | — | — |
 
-Per-story wall-clock (claude run): STORY-1 72 s · STORY-2 114 s · STORY-3 81 s. Every story
-passed verify on the first iteration; the final quality check (all 16 assertions on the final
-tree, outside the loop) is green.
+Per-story wall-clock (claude run): STORY-1 72 s · STORY-2 114 s · STORY-3 81 s. Every story
+passed verify on the first iteration; the final quality check (all 16 assertions on the final
+tree, outside the loop) is green.
+
+## Codex-only full-repository routing study (2026-08-02)
+
+This replaces the earlier single-run impression with three paired comparisons. Fixture
+`yoke-codex-study@1` is a full Yoke snapshot with 571 existing tests and two coupled telemetry
+implementation stories. Every arm used the same `gpt-5.6-sol` high-effort parent, Bare mode,
+disabled native Codex multi-agent, an isolated empty registry, and the same machine. Routing was
+the only policy change: the routed arm used a low-effort `gpt-5.6-sol` controller and selected
+`gpt-5.6-luna` for all six story executions. Pair order alternated on/off, off/on, on/off.
+
+All **6/6 runs**, **12/12 stories**, and **36/36 independently replayed hidden acceptance
+checks** passed. Each story completed in one iteration.
+
+| Metric (median of 3) | Routing off: Sol high | Routing on: Sol controller + Luna worker | Delta |
+|---|---:|---:|---:|
+| Wall-clock | 579.139 s (561.860–589.501) | 383.099 s (350.819–523.110) | **−196.040 s (−33.8%)** |
+| Input tokens, total | 2,279,164 | 1,561,371 | **−31.5%** |
+| Cached input tokens | 2,147,584 | 1,436,672 | **−33.1%** |
+| Fresh input (`input − cached`) | 140,130 (131,580–205,142) | 124,699 (110,541–127,507) | **−15,431 (−11.0%)** |
+| Output tokens | 16,008 | 8,080 | **−49.5%** |
+| Reasoning tokens | 6,536 | 1,426 | **−78.2%** |
+
+| Pair | Execution order | Wall-clock delta | Fresh-input delta |
+|---|---|---:|---:|
+| 1 | on → off | −31.8% | −39.2% |
+| 2 | off → on | −39.4% | −21.1% |
+| 3 | on → off | −11.3% | −3.1% |
+
+The routing controller is included in those numbers. Across the three routed runs its six calls
+used 82.251 s, 114,767 total input tokens (66,048 cached; 48,719 fresh), and 187 output tokens.
+All three pairs improved both wall-clock and fresh input, although the third pair shows meaningful
+latency variance. This is convincing evidence for **bounded, delegable repository work**, not a
+claim that every task should be routed.
+
+The Codex CLI did not report dollar cost for these plan-backed runs, so no USD value is invented.
+The evidence supports lower token/compute use; an exact currency saving still depends on the
+account's current Sol/Luna billing. Reproduce the aggregate with
+`node bench/analyze-routing-study.mjs`. Raw valid rows:
+[`pair 1 on`](results/yoke-codex-study-codex-routing-on-2026-08-02T07-51-59.json),
+[`pair 1 off`](results/yoke-codex-study-codex-routing-off-2026-08-02T07-58-56.json),
+[`pair 2 off`](results/yoke-codex-study-codex-routing-off-2026-08-02T08-08-48.json),
+[`pair 2 on`](results/yoke-codex-study-codex-routing-on-2026-08-02T08-18-59.json),
+[`pair 3 on`](results/yoke-codex-study-codex-routing-on-2026-08-02T08-25-25.json), and
+[`pair 3 off`](results/yoke-codex-study-codex-routing-off-2026-08-02T08-34-45.json).
+
+## Controlled adaptive-routing A/B (2026-08-01)
+
+Fixture `routing-queue@1`: two cumulative implementation stories, 10 pre-written assertions.
+Both arms used Codex as the `gpt-5.6-sol` high-effort parent, `runner.bare: true`, native Codex
+multi-agent disabled, the same isolated Testground host, unsafe permission mode, and one
+iteration per story. The routed arm chose `codex-light` (provider current/default model,
+low reasoning effort) for both stories; the high-effort parent made the routing decisions.
+
+| Routing | Quality | Wall-clock | Input tok | Output tok | Total tok | Story 1 | Story 2 |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| off | 2/2 stories; 10/10 tests | 299.787 s | 579,301 | 9,103 | 588,404 | 173.400 s | 125.693 s |
+| on | 2/2 stories; 10/10 tests | 283.134 s | 542,788 | 5,486 | 548,274 | 148.000 s | 122.288 s |
+| delta | same measured quality | **−16.653 s (−5.6%)** | **−36,513 (−6.3%)** | **−3,617 (−39.7%)** | **−40,130 (−6.8%)** | −25.400 s | −3.405 s |
+
+The two read-only controller calls account for 41.332 s and 38,169 tokens of the routed total.
+The worker savings exceeded that overhead in this sample. This is **N=1**, not a universal
+speed/cost claim; stochastic model output, provider pricing, cache accounting, and host/API load
+can move the result. Raw valid rows:
+[`routing off`](results/routing-queue-codex-routing-off-2026-08-01T21-44-00.json) and
+[`routing on`](results/routing-queue-codex-routing-on-2026-08-01T21-50-31.json).
+
+## Full-repository adaptive-routing A/B (2026-08-02)
+
+Fixture `yoke-large@1` is a snapshot of Yoke itself: 171 relevant files and 17,798 lines across
+source, tests, and canon. Two coupled stories added a privacy-safe registry status API/CLI and
+then circuit-breaker evidence plus automatic strong-parent fallback. Each story ran TypeScript
+build and the 571-test existing suite. Final trees passed 578 tests (routing off) and 579 tests
+(routing on), plus a separate replay of the **four original acceptance tests copied from the
+immutable seed** after the agents had finished.
+
+Both arms used the same `gpt-5.6-sol` high-effort parent, Bare mode, disabled native Codex
+multi-agent, isolated empty registries, unsafe permissions, dependency junction, and sequential
+host load.
+
+| Routing | Quality | Wall-clock | Input tok | Output tok | Total tok | Story 1 | Story 2 |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| off | 2/2; build + 578 + 4 hidden pass | 660.843 s | 1,971,273 | 16,850 | 1,988,123 | 333.022 s | 327.176 s |
+| on | 2/2; build + 579 + 4 hidden pass | 640.151 s | 2,035,962 | 15,483 | 2,051,445 | 322.735 s | 303.662 s |
+| delta | same acceptance quality | **−20.692 s (−3.1%)** | **+64,689 (+3.3%)** | −1,367 (−8.1%) | **+63,322 (+3.2%)** | −10.287 s | −23.514 s |
+
+The controller chose `SELF` for **both** stories. Its two calls cost 35.381 s and 38,457 tokens;
+no cheaper worker executed. The small wall-clock improvement therefore cannot be attributed to
+worker routing and is within the range where stochastic parent execution/API load is a plausible
+explanation. For this complex architecture workload, balanced routing preserved quality through
+a conservative decision but **did not meet the token-cost goal**. A useful next optimization is a
+zero-token deterministic SELF fast path for clearly high-risk architecture/privacy stories.
+
+This is again N=1. Raw valid rows:
+[`routing off`](results/yoke-large-codex-routing-off-2026-08-01T22-58-01.json) and
+[`routing on`](results/yoke-large-codex-routing-on-2026-08-01T23-09-39.json).
 
 The 2026-07-27 release matrix produced no quality measurement: Claude and Gemini exited
 before changing the fixture, and the Codex executable could not be probed in this Windows
@@ -36,11 +131,13 @@ Yoke bugs, both fixed in 0.3.0:
    `-p --yolo` died with "Not enough arguments following: p". The runner now relies on piped
    stdin (which selects headless mode) and passes only `--yolo`.
 
-## Reading the numbers
-
-- Tokens come from the loop's own hook (claude runner only — gemini/codex reporting is an
-  open gap, see the multi-agent design doc).
-- N=1: indicative, not statistics. Re-run with `node bench/run.mjs --runner=<agent>` and
-  compare rows.
-- ~53 k tokens / ~4.5 minutes for a 3-story micro-backlog is the current price of the full
-  gate pipeline (fresh headless session per story + verify + atomic commit) on this fixture.
+## Reading the numbers
+
+- Tokens come from provider telemetry when available; missing telemetry is recorded as missing,
+  never estimated. New Codex rows separate cache reads from fresh input; adaptive rows retain
+  controller/worker/parent call splits.
+- The two older A/B rows are N=1 diagnostics. The Codex-only study above is N=3 per arm with
+  alternating pair order; it is stronger evidence but still workload-specific.
+- Fixture size changes the outcome: the small queue delegated to a lower-effort worker and saved
+  tokens; the architecture/privacy task stayed on SELF and paid controller overhead; the newer
+  bounded full-repository telemetry task delegated consistently and saved fresh-input tokens.

package/bench/analyze-routing-study.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const resultsDir = join(dirname(fileURLToPath(import.meta.url)), 'results')
+const rows = readdirSync(resultsDir)
+  .filter(file => file.startsWith('yoke-codex-study-codex-routing-') && file.endsWith('.json'))
+  .map(file => ({ file, ...JSON.parse(readFileSync(join(resultsDir, file), 'utf8')) }))
+  .filter(row => /^codex-only-pair[1-3]-(on|off)$/.test(row.sampleLabel))
+
+const median = values => {
+  const sorted = [...values].sort((a, b) => a - b)
+  return sorted[Math.floor(sorted.length / 2)]
+}
+const pct = (from, to) => ((to - from) / from) * 100
+const metric = (group, read) => {
+  const values = group.map(read)
+  return { values, min: Math.min(...values), median: median(values), max: Math.max(...values) }
+}
+
+if (rows.length !== 6) throw new Error(`expected six codex-only study rows, found ${rows.length}`)
+for (const row of rows) {
+  if (row.verdict !== 'completed' || !row.finalTestsPass || row.iterations !== 2) throw new Error(`invalid study row: ${row.file}`)
+  if (row.finalVerification?.originalAcceptanceTestsExitCode !== 0 || row.finalVerification?.originalAcceptanceTestCount !== 6) {
+    throw new Error(`hidden acceptance replay failed: ${row.file}`)
+  }
+}
+
+const groups = Object.fromEntries(['off', 'on'].map(routing => {
+  const group = rows.filter(row => row.routing === routing).sort((a, b) => a.sampleLabel.localeCompare(b.sampleLabel))
+  return [routing, {
+    runs: group.map(row => row.file),
+    wallClockMs: metric(group, row => row.wallClockMs),
+    inputTokens: metric(group, row => row.tokenBreakdown.inputTokens),
+    cachedInputTokens: metric(group, row => row.tokenBreakdown.cachedInputTokens),
+    freshInputTokens: metric(group, row => row.tokenBreakdown.freshInputTokens),
+    outputTokens: metric(group, row => row.tokenBreakdown.outputTokens),
+    reasoningOutputTokens: metric(group, row => row.tokenBreakdown.reasoningOutputTokens),
+  }]
+}))
+
+const routed = rows.filter(row => row.routing === 'on')
+const controllerCalls = routed.flatMap(row => row.modelCalls.filter(call => call.role === 'orchestrator'))
+const workerCalls = routed.flatMap(row => row.modelCalls.filter(call => call.role === 'worker'))
+if (workerCalls.length !== 6 || workerCalls.some(call => call.profile !== 'codex-luna' || call.requestedModel !== 'gpt-5.6-luna')) {
+  throw new Error('not every routed story executed on codex-luna')
+}
+
+const deltas = {}
+for (const key of ['wallClockMs', 'inputTokens', 'cachedInputTokens', 'freshInputTokens', 'outputTokens', 'reasoningOutputTokens']) {
+  deltas[key] = {
+    absolute: groups.on[key].median - groups.off[key].median,
+    percent: pct(groups.off[key].median, groups.on[key].median),
+  }
+}
+
+const pairs = [1, 2, 3].map(pair => {
+  const off = rows.find(row => row.sampleLabel === `codex-only-pair${pair}-off`)
+  const on = rows.find(row => row.sampleLabel === `codex-only-pair${pair}-on`)
+  return {
+    pair,
+    order: pair === 2 ? ['off', 'on'] : ['on', 'off'],
+    wallClockMs: { off: off.wallClockMs, on: on.wallClockMs, percent: pct(off.wallClockMs, on.wallClockMs) },
+    freshInputTokens: { off: off.tokenBreakdown.freshInputTokens, on: on.tokenBreakdown.freshInputTokens, percent: pct(off.tokenBreakdown.freshInputTokens, on.tokenBreakdown.freshInputTokens) },
+  }
+})
+
+console.log(JSON.stringify({
+  schemaVersion: 1,
+  fixtureVersion: 'yoke-codex-study@1',
+  sampleCountPerArm: 3,
+  quality: {
+    completedRuns: 6,
+    completedStories: 12,
+    hiddenAcceptancePasses: 36,
+    hiddenAcceptanceChecks: 36,
+    iterationsPerStory: 1,
+  },
+  models: {
+    parent: { model: 'gpt-5.6-sol', reasoningEffort: 'high' },
+    orchestrator: { model: 'gpt-5.6-sol', reasoningEffort: 'low' },
+    worker: { model: 'gpt-5.6-luna', reasoningEffort: 'low' },
+  },
+  groups,
+  medianDeltas: deltas,
+  pairs,
+  controller: {
+    calls: controllerCalls.length,
+    totalDurationMs: controllerCalls.reduce((sum, call) => sum + call.durationMs, 0),
+    totalInputTokens: controllerCalls.reduce((sum, call) => sum + call.inputTokens, 0),
+    totalCachedInputTokens: controllerCalls.reduce((sum, call) => sum + (call.cachedInputTokens ?? 0), 0),
+    totalFreshInputTokens: controllerCalls.reduce((sum, call) => sum + call.inputTokens - (call.cachedInputTokens ?? 0), 0),
+    totalOutputTokens: controllerCalls.reduce((sum, call) => sum + call.outputTokens, 0),
+  },
+}, null, 2))

package/bench/fixtures/routing-queue/.yoke/config.yaml

@@ -0,0 +1,30 @@
+canonVersion: 1.2.0
+agents: [codex, claude, gemini]
+loop:
+  enabled: true
+runner:
+  agent: codex
+  model: gpt-5.6-sol
+  reasoningEffort: high
+  bare: true
+routing:
+  enabled: true
+  strategy: balanced
+  maxCandidates: 3
+  workers:
+    - id: codex-light
+      agent: codex
+      reasoningEffort: low
+      costTier: medium
+      capabilities: [exploration, implementation, tests]
+    - id: claude-fast
+      agent: claude
+      model: haiku
+      costTier: low
+      capabilities: [exploration, mechanical-edits, tests]
+    - id: gemini-auto
+      agent: gemini
+      costTier: low
+      capabilities: [large-context, implementation, tests]
+verify:
+  command: node bench-verify.mjs

package/bench/fixtures/routing-queue/.yoke/prd.yaml

@@ -0,0 +1,24 @@
+- id: STORY-1
+  title: "Priority task queue with idempotency and leases"
+  priority: 1
+  acceptance:
+    - "Export a TaskQueue class from src/task-queue.mjs; constructor accepts optional clock, maxAttempts, and baseDelayMs"
+    - "enqueue({type,payload,priority,idempotencyKey}) validates a non-empty type, defaults priority to 0, and returns an immutable task snapshot"
+    - "Repeated non-empty idempotencyKey returns the original task without adding another queue entry"
+    - "claim(workerId,{leaseMs}) returns the available queued task with highest priority and FIFO order for ties; it records workerId, leaseUntil, and increments attempts"
+    - "complete(taskId,workerId,result) only allows the current lease owner and returns an immutable completed snapshot"
+    - "get(taskId) and list() return snapshots that callers cannot use to mutate queue state"
+    - "node bench-verify.mjs exits 0"
+  passes: false
+- id: STORY-2
+  title: "Retry backoff, dead letters, expired leases, and statistics"
+  priority: 2
+  acceptance:
+    - "fail(taskId,workerId,error) only allows the lease owner; before maxAttempts it requeues with exponential delay baseDelayMs * 2^(attempts-1)"
+    - "A task is not claimable before availableAt; at maxAttempts failure moves it to dead status"
+    - "reapExpired() requeues active tasks whose lease has expired and returns the number requeued"
+    - "list({status,type}) filters without exposing mutable internal objects"
+    - "stats() returns total and counts for queued, active, completed, and dead tasks"
+    - "Invalid task ids, invalid worker ids, and invalid state transitions throw clear errors"
+    - "node bench-verify.mjs exits 0"
+  passes: false

package/bench/fixtures/routing-queue/bench-verify.mjs

@@ -0,0 +1,9 @@
+import { spawnSync } from 'node:child_process'
+
+const total = 2
+const story = process.env.YOKE_STORY
+const requested = story ? Number(story.split('-')[1]) : total
+const upTo = Number.isFinite(requested) && requested >= 1 && requested <= total ? requested : total
+const files = Array.from({ length: upTo }, (_, index) => `tests/STORY-${index + 1}.test.mjs`)
+const result = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit' })
+process.exit(result.status ?? 1)