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

package/CHANGELOG.md

@@ -1,27 +1,69 @@
-# 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.4.0 — 2026-08-15
+
+### Added
+- `yoke loop run --parallel=N` now executes dependency-ready, non-colliding stories through real provider subprocess workers, isolated worktrees, leased claims, and a FIFO integration queue with fresh integrated-system gates.
+- Reference-driven quality declarations can collect screenshots, files, command output, or benchmark results and run a schema-validated blind critic with bounded repair rounds, elapsed-time limits, blocking or advisory policy, and retained proof.
+- `--candidates=N` can fan out up to five isolated implementations, discard mechanically red candidates, select one green candidate through identity-blind pairwise comparison, and preserve selected/loser evidence before cleanup.
+- Loop status now exposes dispatcher, worker, integrator, candidate lifecycle, worktree, queue, integration, reopen, quality-round, repair-budget, and trusted provider/model provenance data.
+
+### Changed
+- Provider subprocesses use explicit lifecycle contracts and incarnation-aware process records so worker cancellation and cleanup target only the process tree Yoke actually started.
+- Parallel and candidate runs disable adaptive routing, honor story-level provider affinity, latch pause requests across the whole dispatcher, and rerun quality plus review after integration.
+- `yoke loop cleanup` retains Yoke worktrees unless `--remove-worktrees` is explicit, while still reaping recorded orphan runners and stale locks safely.
+
+### Fixed
+- Expired claims, worker crashes, merge conflicts, pause races, and integration failures now release ownership deterministically, retain terminal proof, and reopen stories without leaking worktrees or marking false completion.
+- Quality repair fails closed on malformed critic output, reference drift, provider/model provenance mismatch, candidate identity leakage, unavailable critics, exhausted limits, and mechanically red repairs.
+- The watchdog resolves its TypeScript loader from both source and built npm layouts on Node 20+, and read-only Codex comparisons can run in disposable candidate worktrees without weakening normal repository checks.
+
+### Security
+- Blind comparison requests expose only opaque labels and digests while binding every verdict to the trusted judge provider, model, prompt, rubric, reference, and candidate provenance.
+- Cleanup and cancellation use project-scoped leases, owner tokens, PID birth/incarnation checks, and recorded process handles rather than machine-wide process-name matching.
+
+## 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.4.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->928<!-- 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-928%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,11 @@
 
 </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 behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. Add `--parallel=N` for dependency-aware workers, or declare a reference and add `--quality` for a bounded critic/repair gauntlet. If any blocking gate is red, nothing is committed. Proof lives in `.yoke/proof/<story>/`.
+
+Yoke 1.4 adds opt-in parallel workers and a bounded, reference-driven quality gauntlet without
+changing existing serial loop defaults. See [the 1.4 migration guide](docs/MIGRATING-TO-1.4.md)
+for the new flags, configuration, cleanup behavior, and review-verdict contract.
 
 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 +76,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 — 928 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
 
 ## 🚀 Quickstart
 
@@ -85,9 +89,9 @@ 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
+yoke loop run /path/to/project --isolate --parallel=3 --reviewer=codex --max=20
 ```
 
 > Requires Node ≥ 20 and git. No global install? `node /path/to/yoke/dist/cli.js …` or `npm --prefix /path/to/yoke run yoke -- …` work too. The MCP tools (rtk, graphify/Serena, Playwright MCP) are wired by Yoke but installed separately — the generated config is a clearly-labelled, adjustable template.
@@ -104,7 +108,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 +142,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 +152,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` supports `--parallel=N`, bounded reference-driven `--quality`, and blind `--candidates=N` selection; `--max=N` creates an intentional batch cap; `cleanup` retains worktrees unless `--remove-worktrees` is explicit | 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 +315,35 @@ 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.
+  --parallel=3 \                  # run dependency-ready, non-colliding stories concurrently
+  --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 +354,75 @@ 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.
+
+### Parallel workers and the quality gauntlet
+
+`--parallel=N` dispatches dependency-ready stories concurrently. Claims carry leases, workers use
+isolated worktrees, collision areas are serialized, and only a mechanically green candidate enters
+the FIFO integration queue. Integration repeats the project gates against the merged tree; a worker
+success can never bypass a red integrated result. `yoke loop status` reports the dispatcher,
+workers, providers, worktrees, lifecycle, queue, integrations, and reopened stories.
+
+Quality is reference-driven and opt-in. Declare what one story should match:
+
+```yaml
+quality:
+  reference: { name: approved-home, source: design/home.png, kind: file }
+  candidate: { kind: screenshots, paths: [.yoke/proof/STORY-1/home.png] }
+  rubric: Match the approved layout, hierarchy, spacing, and states.
+  policy: blocking                 # or advisory
+```
+
+Configure project defaults, then enable the gauntlet for a run:
+
+```yaml
+quality:
+  enabled: false                   # keep opt-in, or make it the project default
+  policy: blocking
+  maxRounds: 3
+  maxMinutes: 60
+  consistencyChecks: 2
+  maxParallelCandidates: 2
+  critic: { agent: codex, model: gpt-5.6-sol }  # model required for --candidates
+  repair: { agent: claude }
+```
+
+```bash
+yoke loop run . --quality --quality-rounds=3 --quality-minutes=60
+yoke loop run . --quality --candidates=2   # blind pairwise selection; stories need quality declarations
+```
+
+The critic compares opaque candidate/reference labels, writes schema-validated provenance, and
+cannot modify the project. Blocking findings enter a bounded repair loop and rerun every mechanical
+gate; advisory findings are retained without blocking. `--quality-policy=`, `--no-quality`, and
+`--quality-unbounded` override defaults for one run. Unbounded mode is explicit and warned because
+it removes repair limits, not Yoke's watchdog, isolation, verification, or commit safety.
+
+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
 
@@ -365,14 +441,16 @@ Every iteration emits token-free, harness-side feedback (Node console + local fi
     implementing · iteration 20 · 19/45 (42%) · updated 30s ago
     ~1h44m remaining (Ø 4m/story)
   ```
+- **Parallel + quality detail** — active workers include provider, candidate ID, worktree,
+  lifecycle, phase, quality round, and repair budget; the integrator is shown separately.
 - **`.yoke/loop.log`** — an append-only timeline of every phase transition.
 - **`--json`** — machine mode for supervisors: every status write is *also* emitted as one
   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 +510,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 +595,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
 
@@ -532,10 +611,11 @@ stale takeover is serialized by `.yoke/loop.lock.takeover`. A second invocation
 `Another loop is already running here (pid …). If that is wrong, run: yoke loop cleanup`. A lock
 whose holder process is dead is taken over automatically (with a warning).
 
-**`yoke loop cleanup [dir]`** removes what a crashed loop leaves behind: every worktree under
-`.yoke/worktrees/` (via `git worktree remove --force` + `prune` — user-created worktrees are
-never touched) and a **stale** lock file. A live lock is reported and left alone. Exits `0`
-when everything cleaned, `1` if any removal failed. If a machine/process crash leaves the cleanup
+**`yoke loop cleanup [dir]`** reaps only runner process trees recorded by this project and removes
+a stale lock. Yoke-created worktrees are **retained by default** and listed in the output; pass
+`--remove-worktrees` to remove `.yoke/worktrees/*` with `git worktree remove --force` + `prune`.
+User-created worktrees are never touched. A live lock is reported and left alone. Exits `0` when
+cleanup succeeds, `1` if any requested removal fails. If a machine/process crash leaves the cleanup
 recovery lease itself behind, an operator can run
 `yoke loop cleanup . --discard-stale-recovery`; Yoke refuses while its recorded PID is alive, and
 the force flag must not be run concurrently.
@@ -652,24 +732,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,8 +773,10 @@ 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
+  quality/        # reference collection · blind critic · bounded repair · candidate comparison
   new/            # yoke new — greenfield bootstrap
   prd/            # yoke prd draft|check — idea → stories + lint gate
   review/         # yoke review — cross-model diff gate
@@ -706,14 +788,14 @@ docs/superpowers/ # the spec and every component's implementation plan
 
 ## 🗺️ Roadmap
 
-Yoke 1.1's completed release work moved to the changelog. Remaining, explicitly scoped work
-is tracked in [`TODOS.md`](TODOS.md), including provider subprocess wiring for the tested
-parallel dispatcher, broader benchmark samples, native output schemas, and release provenance.
+Completed release work lives in the changelog. Remaining, explicitly scoped work is tracked in
+[`TODOS.md`](TODOS.md), including broader benchmark samples, native output schemas, and signed
+release provenance.
 
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (582 tests)
+npm test          # vitest (928 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/TODOS.md

@@ -1,8 +1,5 @@
 # Yoke follow-up work
 
-- Wire the tested async parallel dispatcher to provider subprocess workers. Until then the CLI
-  rejects `--parallel=N` for `N > 1`; scheduler, claims, and merge queue APIs are available
-  without claiming a CLI speed-up.
 - Add provider-native output schemas when all three CLIs expose compatible stable APIs.
 - Expand benchmark fixtures and collect multiple authenticated samples per provider/model.
 - Add signed provenance and attestations to npm and GitHub releases.