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

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.5.0 — 2026-08-16
+
+### Added
+- Failed verify, executable-criterion, performance, configured custom-audit, and completion gates now produce deterministic byte-bounded previews and preserve large complete stdout/stderr in content-addressed `.yoke/artifacts/` files with SHA-256 references.
+- Projects can tune `output.previewBytes` and `output.artifactThresholdBytes`; existing projects use backward-compatible 2 KiB/8 KiB defaults.
+- A deterministic local benchmark verifies signal retention, preview bounds, compression measurement, and artifact digest round-trips without making provider-token claims.
+
+### Security
+- Output artifact paths sanitize story identifiers, stay below a project-local root, use user-only file modes where supported, and are excluded from Yoke's clean-tree and story-commit operations even in upgraded projects. Raw artifacts are never injected automatically and documentation warns that project commands may emit secrets or personal data.
+- Gate command capture is capped at 16 MiB per stdout/stderr stream. Quota overflow fails closed and labels retained evidence as truncated instead of risking unbounded memory or claiming partial output is complete.
+
+## 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

package/README.md

@@ -2,8 +2,8 @@
 
 # 🐂 Yoke
 
-<!-- yoke:version:start -->1.3.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->657<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.5.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->971<!-- 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-657%20passing-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-971%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,16 @@
 
 </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.5 keeps failed gate output compact without throwing evidence away: deterministic previews
+retain actionable failures and final summaries, while large complete stdout/stderr remains available
+in private, content-addressed local artifacts. Existing projects keep their serial behavior and use
+safe 2 KiB preview / 8 KiB artifact defaults unless configured otherwise.
+
+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 +81,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 — 657 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 — 971 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
 
 ## 🚀 Quickstart
 
@@ -87,7 +96,7 @@ 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 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.
@@ -156,7 +165,7 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 | `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 |
@@ -337,6 +346,7 @@ yoke loop run . \
   --runner=codex \               # implement with Codex…
   --reviewer=claude \            # …review with Claude (role separation)
   --isolate \                    # each story in a throwaway git worktree
+  --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
@@ -370,6 +380,49 @@ closes the mechanical false-done paths—targeted evidence, coverage review, cle
 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
@@ -393,6 +446,8 @@ 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
@@ -542,6 +597,41 @@ be fast" is a vibe the loop cannot enforce. Yoke makes it mechanical, at two lev
   method: profile first, optimize leaves not boundaries, commit benchmarks as tests, version
   the *why* of every optimization in `context/DECISIONS.md`.
 
+### Artifact-backed gate output: compact context, complete local evidence
+
+Failed verify, executable-criterion, performance, configured custom-audit, and completion commands can emit thousands of
+low-signal lines. Yoke keeps the model-visible failure summary deterministic and bounded while
+preserving large raw stdout/stderr below `.yoke/artifacts/`:
+
+```yaml
+output:
+  previewBytes: 2048             # default: maximum compact preview bytes
+  artifactThresholdBytes: 8192   # default: persist raw output only above this size
+```
+
+The preview prioritizes errors, warnings, adjacent context, and final test summaries. Above the
+artifact threshold it also includes a project-relative path, byte count, and full SHA-256 digest,
+for example:
+
+```text
+[full output: .yoke/artifacts/STORY-4/verify-0123abcd4567.log | 42810 bytes | sha256:0123...]
+```
+
+An agent can read that ordinary file when the preview is insufficient; nothing is injected into
+later stories automatically. Repeated identical failures reuse the same content-addressed path.
+Successful gate output is discarded as before. This affects only commands executed by Yoke's own
+gates. It does **not** intercept tool output generated internally by Claude Code, Codex, or Gemini,
+so benchmark ratios for this feature are not provider-token or billing claims.
+
+Command capture is capped at 16 MiB per stdout/stderr stream. Exceeding that quota fails the gate
+closed and stores the captured prefix with a `[truncated output: ...]` marker; Yoke never labels
+partial evidence as full output.
+
+Yoke treats `.yoke/artifacts/` as local, non-committable runtime state and excludes it from its
+clean-tree and story-commit operations; `yoke retrofit` also adds it to `.gitignore`. Raw command output is intentionally stored
+without redaction so it remains valid evidence and may therefore contain credentials, personal
+data, or other sensitive text emitted by project commands. Inspect artifacts before sharing them.
+
 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
@@ -549,7 +639,7 @@ self-heals while a real failure still blocks. Structured acceptance criteria are
 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/ambiguity.md`, `.yoke/artifacts/`, and the critical-decision request/answering files are runtime artifacts;
 `yoke retrofit` gitignores them (along with
 `.yoke/worktrees/`, `.yoke/backup/`, `.yoke/proof/`, and `.yoke/changes/`) so they never trip the clean-tree gate.
 
@@ -561,10 +651,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.
@@ -725,6 +816,7 @@ src/
   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
@@ -736,14 +828,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 (657 tests)
+npm test          # vitest (971 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.

package/bench/README.md

@@ -1,74 +1,83 @@
 # Yoke benchmark — tokens · speed · quality
 
-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.
+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 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. |
+| **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.
-
-## 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.
+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.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
+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
+node bench/output-compaction.mjs  # deterministic local gate-output benchmark; no provider call
 ```
 
-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
+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.
-
-`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.
+failures are stored as honest `unavailable`/`auth-failed` rows and never presented as quality measurements.
+
+### Gate-output compaction benchmark
+
+`output-compaction.mjs` exercises only Yoke's deterministic failure-preview and artifact path.
+It emits a fixed noisy gate failure, verifies that the early compiler error and final test summary
+remain visible, and checks the stored SHA-256 digest. Its byte/token approximation is not a provider
+bill and says nothing about tool output generated inside Claude Code, Codex, or Gemini. It makes no
+comparison to Aphrodite's corpus or published ratios.
+
+`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)
 
-- 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.
+- 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/output-compaction.mjs

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+async function runtimeModules() {
+  const builtCompact = new URL('../dist/output/compact.js', import.meta.url)
+  const builtArtifact = new URL('../dist/output/artifact.js', import.meta.url)
+  const useBuild = existsSync(fileURLToPath(builtCompact)) && existsSync(fileURLToPath(builtArtifact))
+  return Promise.all([
+    import(useBuild ? builtCompact.href : new URL('../src/output/compact.ts', import.meta.url).href),
+    import(useBuild ? builtArtifact.href : new URL('../src/output/artifact.ts', import.meta.url).href),
+  ])
+}
+
+function fixture() {
+  return [
+    '=== stdout ===',
+    'compiling application',
+    'src/core.ts:17: error TS2304: Cannot find name ImportantWidget',
+    'the failing call is part of the checkout flow',
+    ...Array.from({ length: 600 }, (_, index) => `progress shard=${index % 12} status=unchanged cache=hit`),
+    '=== stderr ===',
+    'Tests: 1 failed, 249 passed, 250 total',
+  ].join('\n')
+}
+
+export async function runOutputCompactionBenchmark() {
+  const [{ compactCommandOutput }, { writeOutputArtifact }] = await runtimeModules()
+  const raw = fixture()
+  const previewBudgetBytes = 512
+  const compacted = compactCommandOutput(raw, { previewBytes: previewBudgetBytes })
+  const dir = mkdtempSync(join(tmpdir(), 'yoke-output-bench-'))
+  try {
+    const artifact = writeOutputArtifact(dir, raw, { phase: 'verify', storyId: 'BENCH' })
+    const stored = readFileSync(join(dir, ...artifact.relativePath.split('/')))
+    const storedDigest = createHash('sha256').update(stored).digest('hex')
+    const previewBytes = Buffer.byteLength(compacted.preview)
+    const referencedBytes = previewBytes + Buffer.byteLength(artifact.marker)
+    return {
+      fixture: 'gate-output-v1',
+      rawBytes: Buffer.byteLength(raw),
+      rawApproxTokens: Math.ceil(Buffer.byteLength(raw) / 4),
+      previewBudgetBytes,
+      previewBytes,
+      previewApproxTokens: Math.ceil(previewBytes / 4),
+      referencedBytes,
+      compressionRatio: Number((Buffer.byteLength(raw) / referencedBytes).toFixed(2)),
+      earlyErrorRetained: compacted.preview.includes('error TS2304'),
+      finalSummaryRetained: compacted.preview.includes('Tests: 1 failed, 249 passed'),
+      digestRoundTrip: storedDigest === artifact.sha256,
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const result = await runOutputCompactionBenchmark()
+  console.log(JSON.stringify(result, null, 2))
+  if (!result.earlyErrorRetained || !result.finalSummaryRetained || !result.digestRoundTrip || result.previewBytes > result.previewBudgetBytes) {
+    process.exitCode = 1
+  }
+}

package/canon/loop/loop-spec.md

@@ -4,13 +4,21 @@ 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 loop run [--max=N] [--parallel=N] [--isolate] [--decision-policy=auto|critical] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=blocking|advisory] [--quality-unbounded] [--candidates=N]` — 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.
+a separate, schema-validated review. Pass `--parallel=N` to dispatch ready, non-colliding stories
+concurrently. Pass `--json` for NDJSON status on stdout.
+
+Stories may declare a reference, candidate artifact, rubric, and blocking/advisory quality policy.
+`--quality` runs a read-only blind critic plus bounded repair before review; every repair reruns the
+mechanical gates. `--candidates=N` requires quality declarations and dispatches multiple isolated
+implementations, rejects mechanically red candidates, selects one green candidate through opaque
+pairwise handles, and retains every candidate's terminal proof before cleanup. Parallel/candidate
+runs do not combine with adaptive routing.
 
 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
@@ -21,7 +29,8 @@ 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.
+2. Pick the highest-priority ready unfinished story, or claim multiple dependency-ready stories
+   whose collision areas do not overlap when parallel dispatch is enabled.
 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.
@@ -30,16 +39,21 @@ For each story:
    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
+   `npm test`). Performance and audit follow when configured. If quality is enabled, collect the
+   declared artifact, run the blind critic, and repair within the configured round/time bounds.
+   Independent review follows. Any blocking failure stops the candidate.
+6. Parallel workers enqueue green candidate commits. The integrator applies one at a time and
+   reruns mechanical gates, fresh quality, and review against the integrated tree. Failed
+   integration reopens the story and retains proof.
+7. 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
+8. 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`.
+the dispatcher latches the signal, stops launching new workers, lets active workers reach safe
+terminal proof/cleanup, and exits with code `3` before another story is integrated.
 
 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

package/canon/manifest.yaml

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

package/dist/agents/contracts.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export const AgentSchema = z.enum(['claude', 'codex', 'gemini']);
+export const PermissionProfileSchema = z.enum(['safe', 'unsafe', 'read-only']);
+export const ModelSelectionSchema = z.object({
+    model: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/).optional(),
+    reasoningEffort: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/).optional(),
+    nativeMultiAgent: z.boolean().optional(),
+    bare: z.boolean().optional(),
+});
+export const AgentInvocationSchema = z.object({
+    command: z.string().min(1),
+    args: z.array(z.string()),
+    input: z.string(),
+    cwd: z.string().min(1),
+});
+const ProviderTokenUsageSchema = z.object({
+    inputTokens: z.number().nonnegative(),
+    cachedInputTokens: z.number().nonnegative().optional(),
+    cacheWriteInputTokens: z.number().nonnegative().optional(),
+    outputTokens: z.number().nonnegative(),
+    reasoningOutputTokens: z.number().nonnegative().optional(),
+    totalCostUsd: z.number().nonnegative().optional(),
+    model: z.string().min(1).optional(),
+});
+export const ProviderTelemetrySchema = z.object({
+    usageAvailable: z.boolean(),
+    tokens: ProviderTokenUsageSchema.optional(),
+}).superRefine((telemetry, ctx) => {
+    if (telemetry.usageAvailable && !telemetry.tokens) {
+        ctx.addIssue({ code: 'custom', path: ['tokens'], message: 'usageAvailable telemetry requires token totals' });
+    }
+});
+const MachineRoleSchema = z.enum([
+    'route',
+    'review',
+    'quality',
+    'decomposition',
+    'candidate-selection',
+    'telemetry',
+]);
+export const MachineEnvelopeSchema = z.object({
+    schemaVersion: z.literal(1),
+    provider: AgentSchema,
+    model: z.string().min(1).optional(),
+    role: MachineRoleSchema,
+    durationMs: z.number().int().nonnegative(),
+    permissions: PermissionProfileSchema,
+    usage: ProviderTokenUsageSchema.optional(),
+    raw: z.record(z.unknown()).optional(),
+});

package/dist/agents/process-incarnation.js

@@ -0,0 +1,15 @@
+import { execFileSync } from 'node:child_process';
+const queryProcessIdentity = (command, args, options) => execFileSync(command, args, { stdio: 'pipe', ...options }).toString();
+export function processIncarnation(pid, platform = process.platform, query = queryProcessIdentity) {
+    try {
+        if (platform === 'win32') {
+            const output = query('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', '(Get-CimInstance Win32_Process -Filter "ProcessId = $env:YOKE_PROCESS_PID").CreationDate'], { env: { ...process.env, YOKE_PROCESS_PID: String(pid) } }).trim();
+            return output ? `win32:${output}` : undefined;
+        }
+        const output = query('ps', ['-o', 'lstart=', '-p', String(pid)]).trim();
+        return output ? `posix:${output}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}