@hecer/yoke 1.2.1 → 1.3.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.2.1",
+  "version": "1.3.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.2.1",
+  "version": "1.3.0",
   "description": "Cross-agent coding discipline, mechanical gates, and release workflows",
   "skills": "./canon/skills/",
   "hooks": "./hooks/hooks.json"

package/CHANGELOG.md

@@ -1,27 +1,47 @@
-# Changelog
-
-## 1.2.1 — 2026-08-02
-
-### Fixed
-- `yoke loop run` now executes every remaining planned story by default instead of stopping after an implicit 25-iteration batch. Use `--max=N` only when an intentional bounded batch is wanted.
-- Unlimited runs remain unlimited after a critical-decision answer/resume cycle, while explicit caps remain preserved and accept positive integers only.
-
-## 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
+# Changelog
+
+## 1.3.0 — 2026-08-09
+
+### Added
+- Teams can submit change requests at any time with `yoke change add` and inspect the append-only inbox with `yoke change status`; queued requests are planned at safe loop boundaries by Claude, Codex, or Gemini without interrupting active story work.
+- Acceptance criteria can carry stable IDs and executable verification commands, and Yoke records per-criterion evidence before a story can be marked complete.
+- Projects can configure an integrated completion command that proves the final system flow after all story-level gates pass.
+
+### Changed
+- New projects use strict criterion-proof requirements by default, while existing boolean-only criteria remain readable for compatibility.
+- PRD authoring, schemas, loop guidance, generated configuration, and provider instructions now treat completion as an ephemeral readiness state: new requests create more stories instead of prematurely forcing a release boundary.
+
+### Fixed
+- Broad green test suites can no longer satisfy unrelated structured acceptance criteria: proof commands must use an approved test runner, contain the criterion ID, and avoid shell operators.
+- Change-intake failures block safely; an independent coverage pass rejects omitted requested outcomes, crash recovery retains uncommitted requests, and concurrent PRD edits are detected instead of silently overwriting user work.
+- Integrated completion checks prevent locally finished stories from masking broken cross-component flows such as authentication callbacks or purchase-to-entitlement activation.
+
+### Security
+- Updated the transitive development dependency `nanoid` to a non-vulnerable release so the complete CI dependency audit is clean.
+- Restricted model-authored criterion proof to criterion-targeted test commands and blocked shell control operators and runner-prefix spoofing before host execution.
+
+## 1.2.1 — 2026-08-02
+
+### Fixed
+- `yoke loop run` now executes every remaining planned story by default instead of stopping after an implicit 25-iteration batch. Use `--max=N` only when an intentional bounded batch is wanted.
+- Unlimited runs remain unlimited after a critical-decision answer/resume cycle, while explicit caps remain preserved and accept positive integers only.
+
+## 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.2.1<!-- yoke:version:end -->
-<!-- yoke:tests:start -->582<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.3.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->657<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->29<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini<!-- yoke:agents:end -->
 
@@ -17,7 +17,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Tests](https://img.shields.io/badge/tests-559%20passing-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-657%20passing-brightgreen.svg)
 ![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
@@ -25,7 +25,7 @@
 
 </div>
 
-> **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>/`.
+> **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
@@ -72,7 +72,7 @@ $ ls reading-app/.yoke/proof/STORY-2/
 home.png  list.png                            # photographic evidence, labelled per story
 ```
 
-Every claim in that transcript is enforced by code paths with tests behind them — 559 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
+Every claim in that transcript is enforced by code paths with tests behind them — 657 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
 
 ## 🚀 Quickstart
 
@@ -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, routing
+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 six-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:** `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.
+> ⚠️ **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,15 @@ 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] [--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 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 change add\|status [dir] [--idea=]` | Queue a change at any time; the loop turns it into append-only stories at the next safe boundary | `0` · `1` invalid inbox/request |
 | `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; `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 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 |
@@ -310,28 +311,34 @@ Opt-in; `yoke setup` recommends enabling it for new installs, while `retrofit` a
 
 ```mermaid
 flowchart LR
-    A[pick next PRD story] --> B{clean worktree?}
+    I[consume queued change<br/>as new stories] --> A[pick next PRD story]
+    A --> B{clean worktree?}
     B -- no --> X[blocked]
     B -- yes --> C{acceptance<br/>criteria?}
     C -- no --> X
     C -- yes --> D[agent implements<br/>one story]
-    D --> E{tests green?}
+    D --> E{suite + criterion<br/>proof green?}
     E -- no --> X
     E -- yes --> F{reviewer<br/>approves?}
     F -- no --> X
     F -- yes --> G[commit + mark passes:true<br/>+ proof in .yoke/proof/]
-    G --> A
+    G --> I
+    I --> H{all stories pass?}
+    H -- yes --> J{integrated system<br/>gate green?}
+    J -- no --> X
+    J -- yes --> K[current backlog ready]
 ```
 
 ```bash
 yoke loop on  .                 # enable (recorded in .yoke/config.yaml)
 yoke loop status .              # show state + PRD progress
+yoke change add . --idea="Add passkey login"  # safe while the loop runs
 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
-# Optional: add --max=20 only when this run should stop after a bounded batch.
+  --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
 ```
 
@@ -342,11 +349,32 @@ yoke loop off .                 # disable
   title: Add a health endpoint
   priority: 1                    # lower = higher priority
   acceptance:                    # Definition of Done (required, else blocked)
-    - GET /health returns 200
+    - id: health-returns-200
+      text: GET /health returns 200
+      verify: [npm run test:health-returns-200]
+    - id: health-rejects-post
+      text: POST /health returns 405
+      verify: [npm run test:health-rejects-post]
   passes: false                  # the loop sets this true only on green tests
 ```
 
-The loop stops when every story is `passes: true`. State lives **outside the model context** — the PRD file plus git — so each iteration is fresh. The PRD is re-read from disk at every story boundary, so new stories appended to `.yoke/prd.yaml` **while the loop is running** are picked up at the next iteration — no restart needed.
+New projects default to `verify.requireCriteria: true`: every story has 2–5 behavioral criteria.
+Each criterion ID must occur in its single, approved test command; shell operators and broad,
+untargeted suites are rejected. Yoke records each result in `.yoke/proof/<story>/evidence.json`. Configure optional
+`completion.command` for integrated journeys such as purchase → entitlement → relaunch or
+magic-link → callback → authenticated app. It runs whenever the current backlog has no open
+stories; this is readiness, not a release.
+
+No generic tool can infer whether arbitrary test code perfectly represents product meaning. Yoke
+closes the mechanical false-done paths—targeted evidence, coverage review, clean committed state,
+and integrated journeys—while the project still owns the correctness of its tests and production
+observability.
+
+State lives **outside the model context** — the PRD file plus git — so each iteration is fresh.
+Use `yoke change add` at any time. Its ignored append-only inbox is consumed at the next story
+boundary. A separate coverage pass must confirm that every requested outcome maps to behavioral
+criteria before Yoke appends and commits the new stories; existing stories are never rewritten and
+no restart is needed.
 
 ### Watching a run
 
@@ -370,9 +398,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.
-  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.
+  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
 
@@ -432,65 +460,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`.
-
-### 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
+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:
@@ -517,12 +545,13 @@ be fast" is a vibe the loop cannot enforce. Yoke makes it mechanical, at two lev
 The loop trusts **verify**, not the agent's exit code: a story whose tests are green is
 committed even if the agent process exited non-zero (a common Windows `.cmd`-wrapper ghost).
 A failing verify is retried up to `verify.retries` times (default 1) so a transient flake
-self-heals while a real failure still blocks.
+self-heals while a real failure still blocks. Structured acceptance criteria are then verified
+individually; an unrelated green suite cannot satisfy a criterion without its proof command.
 
 `.yoke/loop-status.json`, `.yoke/loop.log`, `.yoke/loop.lock`, its takeover/recovery leases, lock/decision temp files, `.yoke/story-durations.json`,
 `.yoke/ambiguity.md`, and the critical-decision request/answering files are runtime artifacts;
 `yoke retrofit` gitignores them (along with
-`.yoke/worktrees/`, `.yoke/backup/`, and `.yoke/proof/`) so they never trip the clean-tree gate.
+`.yoke/worktrees/`, `.yoke/backup/`, `.yoke/proof/`, and `.yoke/changes/`) so they never trip the clean-tree gate.
 
 ### Single-flight guard + cleanup
 
@@ -652,24 +681,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.)*
-
-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).
+- 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
 
@@ -693,6 +722,7 @@ canon/            # the source of truth — harness-agnostic
   AGENTS.md  skills/  policy/  loop/  tools/  manifest.yaml
 src/
   canon/          # manifest schema + validator (yoke validate)
+  change/         # append-only change inbox · planning · independent coverage review
   retrofit/       # detect · plan · apply · planners (claude/codex/gemini) · tools
   loop/           # prd · gates · runner · verify · git/worktree · loop · run-command · lock · cleanup
   new/            # yoke new — greenfield bootstrap
@@ -713,7 +743,7 @@ parallel dispatcher, broader benchmark samples, native output schemas, and relea
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (582 tests)
+npm test          # vitest (657 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/canon/loop/loop-spec.md

@@ -1,36 +1,51 @@
 # Loop Specification (Ralph + GSD)
 
-The autonomous loop is OPTIONAL and toggle-able:
-
-- `yoke loop on` / `yoke loop off` — enable/disable (recorded in `.yoke/config.yaml`, default off).
-- `yoke loop status` — show enabled state + PRD progress.
-- `yoke loop run [--max=N] [--isolate] [--decision-policy=auto|critical]` — run the loop (default cap 25 iterations).
-- `yoke loop decision` / `yoke loop answer --choice=<id>` — inspect and answer a structured critical stop; answering records a human-owned, decision-file-only commit and resumes by default with the original runner, isolation, review, permission, timeout, and policy settings. `yoke loop resume` retries a restart that could not begin without weakening those settings.
-
-Pass `--isolate` to run each iteration in a fresh git worktree: the agent works on a throwaway checkout, and only a verified, committed story is fast-forwarded back into the main tree. A failed iteration never touches your working tree. Requires `.yoke/prd.yaml` to be committed to git, since the worktree is a checkout of HEAD.
-
-Pass `--review` (or `--reviewer=<claude|codex|gemini>` for a different agent) to add a role-separated review step: after the tests pass, an independent reviewer agent must approve the change before the story is committed and marked done. A rejection blocks the story (no commit). The reviewer is a fresh agent pass — the implementer never reviews its own work.
-
-Pass `--json` for machine mode: each status transition is emitted as one NDJSON line on stdout (the `.yoke/loop-status.json` shape, tagged `"type":"status"`) instead of the human narrative, so a supervisor can consume the stream instead of polling the file.
-
-When enabled and run, each iteration:
-
-1. Pre-dispatch gate: the git worktree must be clean, else `blocked`.
-2. Pick the highest-priority unfinished PRD story (`.yoke/prd.yaml`).
-3. Stop-the-Line gate: the story must have acceptance criteria, else `blocked`.
-4. Run a fresh agent to implement ONE story. Runner precedence is explicit `--runner`, configured `runner.agent`, active agent host, then the first configured agent. The loop refuses to start if that CLI is not installed.
-   With `decisionPolicy: auto`, routine ambiguity is resolved from the approved plan and project conventions. With `critical`, only high-impact architecture, security/privacy, destructive data, material-cost, compliance, or irreversible choices may produce `.yoke/decision-request.yaml`; the loop validates its bounded single-line fields, unique options, and active story ID, blocks before verify, and preserves it for `yoke loop answer`.
-5. Run the project's verify command (config `verify.command`, or detected `npm test`).
-   **Verify is the source of truth** — the agent's exit code is advisory, so a spurious
-   non-zero exit (e.g. a Windows `.cmd` wrapper) cannot block a story whose tests are green.
-   A failing verify is retried up to `verify.retries` times (default 1) so a transient flake
-   self-heals; a real failure still fails. Only if verify passes is the story marked
-   `passes: true`, committed atomically, and a decision logged. If verify fails: `blocked`.
-6. Stop when all stories `passes: true` (`complete`), or the iteration cap is reached (`cap-reached`).
-
-A supervisor can pause the loop by creating `.yoke/loop.pause`: at the next story boundary (before the next story is selected — the running story always finishes) the loop consumes the file, records `paused` in the status file and log, and exits with code `3`. Running `yoke loop run` again resumes.
-
-State lives outside the model context: the PRD file + git. The agent runner is pluggable. The PRD is re-read from disk at every story boundary, so stories appended to `.yoke/prd.yaml` mid-run are picked up at the next iteration without a restart.
+The autonomous loop is optional and toggle-able:
+
+- `yoke loop on` / `yoke loop off` — enable or disable it in `.yoke/config.yaml`.
+- `yoke loop status` — show enabled state and backlog progress.
+- `yoke loop run [--max=N] [--isolate] [--decision-policy=auto|critical]` — run until the current backlog is green or a gate blocks.
+- `yoke change add --idea="..."` — queue a product change at any time, including while the loop is running.
+- `yoke loop decision` / `yoke loop answer --choice=<id>` — inspect and answer a structured critical stop.
+
+Pass `--isolate` to implement each story in a fresh git worktree. Only a verified, committed
+story is fast-forwarded to the main tree. Pass `--review` or `--reviewer=<provider>` to require
+a separate, schema-validated review. Pass `--json` for NDJSON status on stdout.
+
+At every story boundary, Yoke consumes at most one queued change. The configured Claude,
+Codex, or Gemini provider may propose only new stories in a separate runtime file. A fresh
+coverage-review pass must account for every distinct requested outcome before Yoke validates
+strict criterion evidence, appends the stories itself, commits only the PRD, and leaves existing
+stories untouched. The request stays pending on any failure or uncovered outcome.
+
+For each story:
+
+1. Require a clean git worktree.
+2. Pick the highest-priority ready unfinished story.
+3. Stop the line if acceptance is empty. With `verify.requireCriteria: true`, every criterion
+   must be structured. Every structured criterion, including in compatible legacy projects,
+   must use a single approved test command containing its criterion ID and no shell operators.
+4. Run a fresh configured provider to implement exactly one story. Under the `critical`
+   decision policy, only high-impact architecture, security/privacy, destructive data,
+   material cost, compliance, or irreversible choices may pause for a human decision.
+5. Run every structured criterion's targeted commands and write
+   `.yoke/proof/<story>/evidence.json`. Then run project-wide `verify.command` (or detected
+   `npm test`). Performance, audit, and independent review gates follow when configured. Any
+   failure blocks, and no proof command runs after review.
+6. Only after all gates pass, mark the story `passes: true`, log the decision, and commit
+   atomically. A failed commit restores the PRD state.
+7. When all current stories pass, run optional `completion.command` against the integrated
+   system. Only a green result reports `complete`; otherwise the loop blocks. This readiness
+   result is ephemeral, not a release and not a freeze on future changes.
+
+A supervisor can pause the loop by creating `.yoke/loop.pause`. The running story finishes;
+the signal is consumed at the next story boundary and the process exits with code `3`.
+
+State lives outside model context: PRD, git, and the ignored `.yoke/changes/` inbox. All are
+re-read at story boundaries, so a request queued mid-run becomes additional stories without a
+restart.
 
 ## Limitations
-- The loop verifies via the project's test command and an optional agent review; it has no formal merge-queue or multi-reviewer quorum.
+
+Yoke cannot infer the correct end-to-end journey command. Projects that need integrated
+readiness must configure `completion.command`, for example a Playwright journey suite.

package/canon/loop/prd.schema.md

@@ -1,6 +1,6 @@
 # PRD Schema
 
-The loop is driven by a versioned PRD file. Each story:
+The loop is driven by a continuous PRD backlog. Each story:
 
 ```yaml
 - id: STORY-1
@@ -9,11 +9,35 @@ The loop is driven by a versioned PRD file. Each story:
   needs: []              # optional dependency IDs; no unknown IDs, self-links, or cycles
   area: api              # optional collision domain for parallel scheduling
   agent: codex           # optional claude|codex|gemini affinity
-  acceptance:            # Definition of Done (required before implementation)
-    - The endpoint returns 200 for a valid request.
-  passes: false          # set true only when acceptance is met and tests are green
+  acceptance:
+    - id: valid-request-returns-200
+      text: The endpoint returns 200 for a valid request.
+      verify: [npm run test:valid-request-returns-200]
+    - id: invalid-request-returns-400
+      text: The endpoint returns 400 for an invalid request.
+      verify: [npm run test:invalid-request-returns-400]
+  passes: false          # Yoke-owned; true only after all gates pass and the commit lands
 ```
 
-Stop condition: every story has `passes: true`.
+Each new story has 2–5 acceptance criteria. Every criterion has a stable `id`, observable
+behavioral `text`, and one or more executable `verify` commands. Each entry is one approved test
+command, contains the normalized criterion ID, and contains no shell control operator. Yoke runs and records each criterion separately in
+`.yoke/proof/<story>/evidence.json`; a broad green suite cannot stand in for an untested
+criterion. Legacy string criteria remain readable, but `verify.requireCriteria: true` blocks
+them.
 
-Stories without `needs`, `area`, or `agent` retain the serial pre-1.0 behavior. A story is ready only when every ID in `needs` passes. The scheduler orders ready work by priority, avoids simultaneously active areas, and uses `agent` as an affinity hint.
+The binding is deliberately mechanical, not an oracle for product meaning: Yoke can require a
+criterion-targeted test command and a separate coverage review, but it cannot prove that arbitrary
+test code faithfully models the real world. Critical cross-component behavior therefore also
+belongs in a trusted `completion.command` journey suite.
+
+`sourceChange` is an optional Yoke-owned request ID. The change inbox uses it to append new
+stories idempotently; authors normally omit it.
+
+Stories without `needs`, `area`, or `agent` retain serial behavior. A story is ready only when
+every ID in `needs` passes. The scheduler orders ready work by priority, avoids simultaneously
+active areas, and uses `agent` as an affinity hint.
+
+The backlog is continuous, not a release object. A momentary stop condition is every story
+having `passes: true`; if configured, `completion.command` must then prove the integrated
+system before the loop reports `complete`.

package/canon/manifest.yaml

@@ -1,5 +1,5 @@
 name: yoke-canon
-version: 1.1.0
+version: 1.2.0
 agents: [claude, codex, gemini]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology }