@hecer/yoke 0.9.0 → 1.0.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "yoke",
+  "version": "1.0.0",
+  "description": "Cross-agent coding discipline, mechanical gates, and release workflows",
+  "skills": "./canon/skills/",
+  "hooks": "./hooks/hooks.json"
+}

package/CHANGELOG.md

@@ -1,149 +1,169 @@
-# Changelog
-
-## 0.9.0 — 2026-07-22
-
-### Added
-- **Performance budget gate** (`perf.command` in `.yoke/config.yaml`, optional `perf.retries`).
-  A benchmark command with the same contract as verify (exit 0 = within budget) runs **after
-  verify** on every story — new loop phase `perf`, `YOKE_STORY` exposed, worktree-aware in
-  `--isolate` mode. A red benchmark blocks the story
-  (`story S6 exceeded its performance budget: …`) no matter how clean the diff is. When the
-  gate is configured, the implementer prompt names the budget command so agents keep hot
-  paths efficient and never "simplify away" an optimization without re-running the benchmark.
-- **`performance` canon skill** (28 skills now): efficiency as a measured requirement —
-  clean-by-default with the decision ladder (minimal-code → measurable acceptance criterion →
-  project perf gate), profile-first, optimize leaves not boundaries, benchmarks committed as
-  tests, the *why* of every optimization versioned so future agents don't clean fast code
-  back to slow.
-- **`authoring-prd` guidance**: performance requirements belong in acceptance criteria as
-  numbers ("imports 1M rows in < 2s"), and every clarifying question belongs in the planning
-  round — a criterion still needing a decision is not loop-ready.
-
-## 0.8.0 — 2026-07-20
-
-### Added
-- **Live progress + ETA.** Story completions are now first-class events: the console shows
-  `✓ S6 done in 4m28s — 20/45 (44%) · ~1h40m left`, every status (file, NDJSON stream,
-  `yoke loop status`) carries `percent` and an `eta` block. The estimate averages the
-  durations of stories completed **in this run** (current velocity) and falls back to the
-  persisted history of previous runs (`.yoke/story-durations.json`, last 50, gitignored).
-  No data → no estimate, never an invented one.
-- **Ambiguity policy** (`loop.onAmbiguity` / `--on-ambiguity=<resolve|abort>`). The runner
-  prompt now always forbids asking questions (a loop run has nobody to answer). Default
-  `resolve`: the agent settles ambiguous criteria itself, states the interpretation, and the
-  loop never stops. Opt-in `abort`: the agent writes its open questions to
-  `.yoke/ambiguity.md` and stops; the loop consumes the file, skips verify (an unimplemented
-  story would otherwise pass on pre-existing green tests), and blocks with the question as
-  the reason. Companion principle: clarifying questions belong in the planning round, before
-  the loop starts.
-
-## 0.7.0 — 2026-07-17
-
-### Added
-- **Update check + `yoke upgrade`.** Every CLI invocation ends with a non-blocking
-  version hint (npm/gh-style): a detached background refresher caches the registry's
-  latest at most once a day; when it is newer, a one-line stderr hint suggests
-  `yoke upgrade` (which runs `npm install -g @hecer/yoke@latest`). Silent in CI,
-  `--json` runs, non-TTY pipes, and under `YOKE_NO_UPDATE_CHECK=1`.
-- **Opt-in auto-upgrade** (`update.auto: true` in `.yoke/config.yaml`): evaluated at
-  loop START only — never mid-run; the running process finishes on its version and
-  the upgrade applies from the next invocation. Deliberately NOT the default:
-  a gate harness must not change itself mid-project (determinism), and unreviewed
-  auto-installs are a supply-chain hazard.
-
-## 0.6.0 — 2026-07-17
-
-### Added
-- **Project-scoped orphan reaping.** The watchdog now records its pids in the project's
-  `.yoke/runner.pid` (main dir and per-story worktrees; removed on clean exit), and
-  `yoke loop cleanup` kills exactly those recorded process trees — and only while no
-  live loop holds the lock. Background: without a scoped mechanism, users and agents
-  resorted to machine-wide pattern kills (every process matching
-  `dangerously-skip-permissions`), which took down *healthy* runners of other projects
-  mid-story and stalled their loops. Never kill by pattern; `yoke loop cleanup` is the
-  safe path. `.yoke/runner.pid` is gitignored by retrofit.
-
-## 0.5.0 — 2026-07-17
-
-Root-cause fixes for the two "yoke keeps hanging" failure modes observed in the field
-(orphaned `claude.exe` runners piling up, healthy long stories dying at exactly the
-idle window):
-
-### Fixed
-- **Watchdog now kills the whole process tree on Windows** (`taskkill /T /F`).
-  Previously it killed only the spawned shell (`shell: true`), orphaning the actual
-  agent process — which kept writing to the worktree (dirty-tree blocks, failing
-  worktree removal) and kept burning API tokens. Observed in the field as ~10
-  zombie `claude.exe` per machine plus surviving dev servers.
-- **Claude runner always runs in stream-json mode.** Plain `-p` prints nothing until
-  the run finishes, so the idle watchdog mistook healthy >20-minute stories for dead
-  processes and killed them at exactly the idle timeout — while the user saw dead air.
-  The stream doubles as liveness; token usage is now reported on every run (not just
-  `--json` mode).
-
-### Changed
-- README: operating notes for driving the loop from inside an agent session
-  (background execution, small `--max` batches, `yoke loop cleanup` after interrupts) —
-  outer shell-tool timeouts killing a foreground `yoke loop run` were the third
-  observed "hang" pattern.
-
-## 0.4.0 — 2026-07-17
-
-### Added
-- **Hardened runner prompts** — distilled agent-harness patterns for headless runs:
-  scope discipline (nothing beyond the story), no unsolicited summary/plan/analysis
-  documents, root-cause fixes instead of gate bypasses, faithful outcome reporting,
-  bounded final messages (cuts output-token waste). Review prompts now ground verdicts
-  in observed evidence only and keep them brief.
-
-### Fixed
-- `.yoke/loop.pause` is now gitignored by retrofit. Previously the loop's own
-  `git add -A` story commit swept the pause control file into history in
-  un-retrofitted targets; removing it dirtied the tree and the clean-tree gate
-  blocked the resume run — the loop locked itself out.
-
-> Note: 0.3.0 was tagged and released on GitHub but never reached npm (2FA re-login
-> was pending), so for npm users 0.4.0 is the first release with the 0.3.0 changes below.
-
-## 0.3.0 — 2026-07-10
-
-### Added
-- **Claude Code plugin packaging** — the repo is now its own plugin marketplace
-  (`.claude-plugin/plugin.json` + `marketplace.json`): `/plugin marketplace add HECer/yoke`,
-  then `/plugin install yoke@yoke` installs the full canon under the `yoke:` skill namespace.
-- **Gemini CLI extension manifest** (`gemini-extension.json` + `GEMINI-EXTENSION.md`) —
-  installable via `gemini extensions install https://github.com/HECer/yoke`, listed in the
-  daily-crawled extensions gallery.
-- **Benchmark harness** (`bench/`) — reproducible cross-runner benchmark (tokens · speed ·
-  quality) with a fixed fixture, pre-written objective tests, and committed result data.
-- **Companion tool docs** — `canon/tools/claude-mem.md` (persistent memory; interactive
-  sessions only, explicitly kept out of loop runs) and `canon/tools/ui-ux-pro-max.md`
-  (design generation paired with Yoke's design verification gates).
-- **Multi-agent parallel loop design** — evaluation + phased design for distributing PRD
-  stories across parallel workers (`needs` dependency field, claim files, merge queue,
-  heterogeneous cross-agent dispatch): `docs/superpowers/specs/2026-07-10-multi-agent-parallel-loop-design.md`.
-
-### Fixed
-- Agent-availability probe timeout raised 5s → 20s: Gemini CLI cold-starts in ~6s on
-  Windows, so the loop misreported an installed `gemini` as "not found on PATH"
-  (found by the new benchmark harness).
-- Gemini runner invocation: dropped the bare `-p` flag — current Gemini CLI (0.33+)
-  requires a value after `-p` and errored with "Not enough arguments following: p".
-  Piped stdin selects headless mode by itself, so the runner now passes only `--yolo`
-  (also found by the benchmark harness).
-
-### Changed
-- README: npm install is now the primary quickstart path; documented plugin/extension
-  installs and optional companions.
-- npm package now ships `CHANGELOG.md`, `bench/` (harness + result data), and
-  `docs/superpowers/` (all specs and plans, including the multi-agent parallel loop design).
-
-## 0.2.0 — 2026-07-09
-
-- First npm release as `@hecer/yoke`.
-- Hyperflow integration surface: `yoke loop run --json` NDJSON stream, pause signal,
-  token-usage + model-id reporting for the claude runner.
-- `yoke new` greenfield bootstrap, `yoke prd draft`, cross-model `yoke review`,
-  `yoke flow-smoke` browser gate with proof artifacts, `yoke design-scan`.
-- Retrofit planners for Claude Code, Codex CLI, Gemini CLI; canon of 26 skills;
-  loop with worktree isolation, watchdog, single-flight lock, commit integrity.
+# Changelog
+
+## 1.0.0 — 2026-07-27
+
+### Added
+- Native Codex skills, project config, hooks, reusable agents, and plugin metadata.
+- Safe provider permission profiles and structured cross-provider telemetry.
+- Schema-validated independent review verdicts with explicit self-review opt-in.
+- Human-owned commit identity enforcement; AI co-author trailers default off.
+- `yoke audit` dependency, secret, and sensitive-diff gate with versioned suppressions.
+- PRD dependency graphs, collision areas, agent affinity, claims, FIFO merge queue, and bounded async dispatcher APIs.
+- Reproducible cross-runner benchmark schema and matrix launcher.
+
+### Changed
+- Dangerous permission bypass is opt-in via `--unsafe`.
+- Worktree cleanup is non-destructive unless `--remove-worktrees` is passed.
+- Reviews no longer trust process exit code alone.
+
+### Security
+- Vitest upgraded to 4.1.10; the dependency tree reports zero known vulnerabilities.
+
+
+## 0.9.0 — 2026-07-22
+
+### Added
+- **Performance budget gate** (`perf.command` in `.yoke/config.yaml`, optional `perf.retries`).
+  A benchmark command with the same contract as verify (exit 0 = within budget) runs **after
+  verify** on every story — new loop phase `perf`, `YOKE_STORY` exposed, worktree-aware in
+  `--isolate` mode. A red benchmark blocks the story
+  (`story S6 exceeded its performance budget: …`) no matter how clean the diff is. When the
+  gate is configured, the implementer prompt names the budget command so agents keep hot
+  paths efficient and never "simplify away" an optimization without re-running the benchmark.
+- **`performance` canon skill** (28 skills now): efficiency as a measured requirement —
+  clean-by-default with the decision ladder (minimal-code → measurable acceptance criterion →
+  project perf gate), profile-first, optimize leaves not boundaries, benchmarks committed as
+  tests, the *why* of every optimization versioned so future agents don't clean fast code
+  back to slow.
+- **`authoring-prd` guidance**: performance requirements belong in acceptance criteria as
+  numbers ("imports 1M rows in < 2s"), and every clarifying question belongs in the planning
+  round — a criterion still needing a decision is not loop-ready.
+
+## 0.8.0 — 2026-07-20
+
+### Added
+- **Live progress + ETA.** Story completions are now first-class events: the console shows
+  `✓ S6 done in 4m28s — 20/45 (44%) · ~1h40m left`, every status (file, NDJSON stream,
+  `yoke loop status`) carries `percent` and an `eta` block. The estimate averages the
+  durations of stories completed **in this run** (current velocity) and falls back to the
+  persisted history of previous runs (`.yoke/story-durations.json`, last 50, gitignored).
+  No data → no estimate, never an invented one.
+- **Ambiguity policy** (`loop.onAmbiguity` / `--on-ambiguity=<resolve|abort>`). The runner
+  prompt now always forbids asking questions (a loop run has nobody to answer). Default
+  `resolve`: the agent settles ambiguous criteria itself, states the interpretation, and the
+  loop never stops. Opt-in `abort`: the agent writes its open questions to
+  `.yoke/ambiguity.md` and stops; the loop consumes the file, skips verify (an unimplemented
+  story would otherwise pass on pre-existing green tests), and blocks with the question as
+  the reason. Companion principle: clarifying questions belong in the planning round, before
+  the loop starts.
+
+## 0.7.0 — 2026-07-17
+
+### Added
+- **Update check + `yoke upgrade`.** Every CLI invocation ends with a non-blocking
+  version hint (npm/gh-style): a detached background refresher caches the registry's
+  latest at most once a day; when it is newer, a one-line stderr hint suggests
+  `yoke upgrade` (which runs `npm install -g @hecer/yoke@latest`). Silent in CI,
+  `--json` runs, non-TTY pipes, and under `YOKE_NO_UPDATE_CHECK=1`.
+- **Opt-in auto-upgrade** (`update.auto: true` in `.yoke/config.yaml`): evaluated at
+  loop START only — never mid-run; the running process finishes on its version and
+  the upgrade applies from the next invocation. Deliberately NOT the default:
+  a gate harness must not change itself mid-project (determinism), and unreviewed
+  auto-installs are a supply-chain hazard.
+
+## 0.6.0 — 2026-07-17
+
+### Added
+- **Project-scoped orphan reaping.** The watchdog now records its pids in the project's
+  `.yoke/runner.pid` (main dir and per-story worktrees; removed on clean exit), and
+  `yoke loop cleanup` kills exactly those recorded process trees — and only while no
+  live loop holds the lock. Background: without a scoped mechanism, users and agents
+  resorted to machine-wide pattern kills (every process matching
+  `dangerously-skip-permissions`), which took down *healthy* runners of other projects
+  mid-story and stalled their loops. Never kill by pattern; `yoke loop cleanup` is the
+  safe path. `.yoke/runner.pid` is gitignored by retrofit.
+
+## 0.5.0 — 2026-07-17
+
+Root-cause fixes for the two "yoke keeps hanging" failure modes observed in the field
+(orphaned `claude.exe` runners piling up, healthy long stories dying at exactly the
+idle window):
+
+### Fixed
+- **Watchdog now kills the whole process tree on Windows** (`taskkill /T /F`).
+  Previously it killed only the spawned shell (`shell: true`), orphaning the actual
+  agent process — which kept writing to the worktree (dirty-tree blocks, failing
+  worktree removal) and kept burning API tokens. Observed in the field as ~10
+  zombie `claude.exe` per machine plus surviving dev servers.
+- **Claude runner always runs in stream-json mode.** Plain `-p` prints nothing until
+  the run finishes, so the idle watchdog mistook healthy >20-minute stories for dead
+  processes and killed them at exactly the idle timeout — while the user saw dead air.
+  The stream doubles as liveness; token usage is now reported on every run (not just
+  `--json` mode).
+
+### Changed
+- README: operating notes for driving the loop from inside an agent session
+  (background execution, small `--max` batches, `yoke loop cleanup` after interrupts) —
+  outer shell-tool timeouts killing a foreground `yoke loop run` were the third
+  observed "hang" pattern.
+
+## 0.4.0 — 2026-07-17
+
+### Added
+- **Hardened runner prompts** — distilled agent-harness patterns for headless runs:
+  scope discipline (nothing beyond the story), no unsolicited summary/plan/analysis
+  documents, root-cause fixes instead of gate bypasses, faithful outcome reporting,
+  bounded final messages (cuts output-token waste). Review prompts now ground verdicts
+  in observed evidence only and keep them brief.
+
+### Fixed
+- `.yoke/loop.pause` is now gitignored by retrofit. Previously the loop's own
+  `git add -A` story commit swept the pause control file into history in
+  un-retrofitted targets; removing it dirtied the tree and the clean-tree gate
+  blocked the resume run — the loop locked itself out.
+
+> Note: 0.3.0 was tagged and released on GitHub but never reached npm (2FA re-login
+> was pending), so for npm users 0.4.0 is the first release with the 0.3.0 changes below.
+
+## 0.3.0 — 2026-07-10
+
+### Added
+- **Claude Code plugin packaging** — the repo is now its own plugin marketplace
+  (`.claude-plugin/plugin.json` + `marketplace.json`): `/plugin marketplace add HECer/yoke`,
+  then `/plugin install yoke@yoke` installs the full canon under the `yoke:` skill namespace.
+- **Gemini CLI extension manifest** (`gemini-extension.json` + `GEMINI-EXTENSION.md`) —
+  installable via `gemini extensions install https://github.com/HECer/yoke`, listed in the
+  daily-crawled extensions gallery.
+- **Benchmark harness** (`bench/`) — reproducible cross-runner benchmark (tokens · speed ·
+  quality) with a fixed fixture, pre-written objective tests, and committed result data.
+- **Companion tool docs** — `canon/tools/claude-mem.md` (persistent memory; interactive
+  sessions only, explicitly kept out of loop runs) and `canon/tools/ui-ux-pro-max.md`
+  (design generation paired with Yoke's design verification gates).
+- **Multi-agent parallel loop design** — evaluation + phased design for distributing PRD
+  stories across parallel workers (`needs` dependency field, claim files, merge queue,
+  heterogeneous cross-agent dispatch): `docs/superpowers/specs/2026-07-10-multi-agent-parallel-loop-design.md`.
+
+### Fixed
+- Agent-availability probe timeout raised 5s → 20s: Gemini CLI cold-starts in ~6s on
+  Windows, so the loop misreported an installed `gemini` as "not found on PATH"
+  (found by the new benchmark harness).
+- Gemini runner invocation: dropped the bare `-p` flag — current Gemini CLI (0.33+)
+  requires a value after `-p` and errored with "Not enough arguments following: p".
+  Piped stdin selects headless mode by itself, so the runner now passes only `--yolo`
+  (also found by the benchmark harness).
+
+### Changed
+- README: npm install is now the primary quickstart path; documented plugin/extension
+  installs and optional companions.
+- npm package now ships `CHANGELOG.md`, `bench/` (harness + result data), and
+  `docs/superpowers/` (all specs and plans, including the multi-agent parallel loop design).
+
+## 0.2.0 — 2026-07-09
+
+- First npm release as `@hecer/yoke`.
+- Hyperflow integration surface: `yoke loop run --json` NDJSON stream, pause signal,
+  token-usage + model-id reporting for the claude runner.
+- `yoke new` greenfield bootstrap, `yoke prd draft`, cross-model `yoke review`,
+  `yoke flow-smoke` browser gate with proof artifacts, `yoke design-scan`.
+- Retrofit planners for Claude Code, Codex CLI, Gemini CLI; canon of 26 skills;
+  loop with worktree isolation, watchdog, single-flight lock, commit integrity.

package/README.md

@@ -2,6 +2,11 @@
 
 # 🐂 Yoke
 
+<!-- yoke:version:start -->1.0.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->500<!-- yoke:tests:end -->
+<!-- yoke:skills:start -->28<!-- yoke:skills:end -->
+<!-- yoke:agents:start -->Claude | Codex | Gemini<!-- yoke:agents:end -->
+
 ### One harness, three agents — and zero trust in "done."
 
 **Yoke** installs one curated canon of skills, **mechanical safety gates**, and tool wiring into any project — natively for **Claude Code, OpenAI Codex CLI, and Gemini CLI**. Then, when you want it, an opt-in autonomous loop ships your spec story-by-story: tested, cross-model-reviewed, committed — **with a screenshot to prove every story and a video for every failure**.
@@ -12,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-439%20passing-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-500%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)
 
@@ -22,6 +27,11 @@
 
 > **TL;DR** — `yoke new my-app --idea="..."` scaffolds a git repo, installs the harness for all three agents, and drafts a story backlog from your idea. `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.0 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
+`--allow-self-review` is explicit; commits enforce the human identity from project config or Git.
+See [the 1.0 migration guide](docs/MIGRATING-TO-1.0.md).
+
 ---
 
 ## Why Yoke exists
@@ -33,7 +43,7 @@ Agentic coding in 2026 fails in four well-documented ways. Yoke answers each one
 | 🎭 **The verification gap** — *"agent says done, but it isn't"* | Agents submit confidently on 100% of runs while resolving far fewer; "all tests pass" when they were never run ([silent-failures research](https://arxiv.org/pdf/2603.25764)) | The loop trusts **your verify command's exit code**, never the agent's word. A story is `passes: true` only after tests are green, the reviewer approved, and the commit landed — atomically. Plus: **screenshot proofs** per story. |
 | 🔀 **Three agents, three configs** | Teams hand-maintain `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, skills, and MCP wiring separately — copy-paste drift everywhere | **One canon → `yoke retrofit`** generates the idiomatic native artifacts for each agent. Change the canon once, re-retrofit everywhere. |
 | 🌀 **Overnight loops going off the rails** | Raw Ralph-loop users "wake up to broken codebases that don't compile" | Yoke is **"Ralph, but with gates"**: clean-worktree gate, acceptance-criteria gate, green-tests gate, review gate, per-story worktree isolation, idle-timeout watchdog, single-flight lock, commit integrity. |
-| 😵 **Review fatigue** | AI adoption nearly doubles PR volume and review time; humans start skimming | **`yoke review`**: a *second* model reviews the diff as a pass/fail exit-code gate — chainable into verify, pre-push, or CI. Cross-model review measurably catches what self-review misses. |
+| 😵 **Review fatigue** | AI adoption nearly doubles PR volume and review time; humans start skimming | **`yoke review`**: a second model writes a schema-validated pass/fail verdict — chainable into verify, pre-push, or CI. Cross-model review catches what self-review misses. |
 
 **Who it's for:** anyone driving Claude Code, Codex CLI, or Gemini CLI on real projects — especially if you use more than one, want autonomous runs you can trust, or are tired of "done" meaning "probably". Greenfield (`yoke new`) and brownfield (`yoke retrofit`) both work.
 
@@ -61,7 +71,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 — 439 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 — 500 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
 
 ## 🚀 Quickstart
 
@@ -136,10 +146,11 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 | `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, duplicate ids, empty acceptance) | `0` valid · `1` violations |
+| `yoke prd check [dir]` | PRD lint gate (schema, dependencies, cycles, duplicate ids, acceptance) | `0` valid · `1` violations |
 | `yoke context init\|status [dir]` | Durable context layer (`PROJECT/DECISIONS/KNOWLEDGE.md`) | `0` |
-| `yoke loop on\|off\|status\|run\|cleanup [dir]` | The autonomous loop (see below) | run: `0` complete · `1` blocked/cap · `2` not runnable / already locked · `3` paused |
-| `yoke review [dir] [--reviewer=] [--base=] [--focus=]` | A **second model** reviews your diff | `0` approved · `1` findings · `2` no reviewer CLI |
+| `yoke loop on\|off\|status\|run\|cleanup [dir]` | Autonomous loop; cleanup deletes worktrees only with `--remove-worktrees` | 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 |
 | `yoke flow-smoke [dir] [--url=] [--label=]` | Browser gate with screenshot/video proofs | `0` green · `1` failures · `2` not runnable |
 
@@ -156,7 +167,7 @@ Three excellent projects, three different jobs. Honest version:
 | **Enforcement** | Advisory — skills *describe* the discipline; following them is up to the agent | Skill-driven; browser QA is genuinely real | **Mechanical** — gates live in code: clean tree, acceptance criteria, green tests, review verdict, commit integrity |
 | **Autonomy** | Interactive sessions | Interactive slash-commands (`/qa`, `/ship`, …) | Opt-in **Ralph loop** with watchdog, worktree isolation, single-flight lock, per-story proofs |
 | **Visual QA** | — | **Best-in-class**: live browser daemon (Chromium/CDP) with deep interactive QA | Built-in `flow-smoke` gate: screenshots always, video on failure, labelled per story — lighter, but *enforced* and cross-agent |
-| **Cross-model review** | — | `/codex` second opinion (Codex-only direction) | `yoke review` — resolves **codex → gemini → claude**, exit-code gate, works in and outside the loop |
+| **Cross-model review** | — | `/codex` second opinion (Codex-only direction) | `yoke review` — resolves an independent provider and validates a structured verdict, inside or outside the loop |
 | **Footprint** | Markdown skills (plugin) | ~230 MB with browser runtime; hourly auto-update | Node CLI + markdown canon; Playwright only if you use flow-smoke, resolved **from your project** |
 | **License** | MIT | MIT | MIT |
 
@@ -189,10 +200,10 @@ Three layers — **Canon** (`yoke validate`) → **Retrofit** (`yoke retrofit`)
 | Agent | Artifacts |
 |---|---|
 | **Claude** | `.claude/skills/`, `AGENTS.md`, `CLAUDE.md`, `.mcp.json` (code-graph + Playwright), and an rtk `PreToolUse` hook when WSL is available |
-| **Codex** | `AGENTS.md` (native), `.codex/config.toml` (MCP servers), `RTK.md` |
+| **Codex** | `.agents/skills/`, `AGENTS.md`, `RTK.md`, `.codex/config.toml`, native hooks, reusable `.codex/agents/*.toml`, and package plugin metadata |
 | **Gemini** | `GEMINI.md`, `.gemini/commands/*.toml` (one per skill, full body), `.gemini/settings.json` (MCP + `AGENTS.md` context) |
 
-> **rtk asymmetry, handled:** Claude can rewrite commands transparently via a hook (needs WSL on Windows); Codex and Gemini have no such hook, so they get an instruction to prefix commands with `rtk` instead.
+> **rtk integration:** Claude receives its PreToolUse hook; Codex receives a native hook adapter around `rtk hook check`; Gemini retains instruction-mode fallback where its CLI has no equivalent command-rewrite lifecycle.
 
 > **Composes with gstack:** if [gstack](https://github.com/garrytan/gstack) is installed (repo-local or global), `yoke retrofit` adds a short "Composed tools" routing note to **CLAUDE.md only** — telling Claude to prefer gstack's skills for capabilities Yoke doesn't ship (live-browser QA `/qa`, security audit `/cso`, ship/deploy `/ship`). No bundling, no dependency; the note is never written to the Codex or Gemini artifacts.
 
@@ -587,17 +598,14 @@ docs/superpowers/ # the spec and every component's implementation plan
 
 ## 🗺️ Roadmap
 
-- **npm publish** (`@hecer/yoke`) — one-liner `npx` install (package prepared).
-- **Security gate** — a `cso`-style audit skill + `yoke audit` (deps, secrets, diff surface).
-- **Token-budget gate** — per-story budget with abort; cost transparency for loop runs.
-- **Multi-reviewer quorum** — N independent reviewers with distinct lenses (correctness / security / acceptance).
-- **Merge queue** — re-test against the latest main before integrating, for parallel/multi-agent loops.
-- **More agents** — the canon→retrofit pattern generalises; OpenCode and Copilot CLI are natural next targets.
+Yoke 1.0'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.
 
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (322 tests)
+npm test          # vitest (500 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/TODOS.md

@@ -0,0 +1,8 @@
+# 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/agents/docs.toml

@@ -0,0 +1,6 @@
+name = "docs"
+description = "Documentation specialist for release and API consistency."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Update only documentation required by the assigned change. Verify commands and version references against the repository.
+"""

package/agents/implementer.toml

@@ -0,0 +1,6 @@
+name = "implementer"
+description = "Implementation specialist for one scoped story."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Implement only the assigned scope. Use tests first, run verification, and do not review or commit your own work.
+"""

package/agents/reviewer.toml

@@ -0,0 +1,6 @@
+name = "reviewer"
+description = "Read-only reviewer for correctness and acceptance criteria."
+sandbox_mode = "read-only"
+developer_instructions = """
+Review observed diffs and test evidence. Do not modify files. Return only findings grounded in evidence.
+"""

package/agents/security.toml

@@ -0,0 +1,6 @@
+name = "security"
+description = "Read-only security reviewer for changed code."
+sandbox_mode = "read-only"
+developer_instructions = """
+Inspect changed code for exploitable security regressions. Do not modify files and avoid speculative findings.
+"""

package/bench/README.md

@@ -1,42 +1,45 @@
-# Yoke benchmark — tokens · speed · quality
-
-Reproducible cross-runner benchmark for the Yoke loop. One fixed fixture project, the same
-PRD for every runner, three measured dimensions:
-
-| Dimension | How it is measured |
-|---|---|
-| **Tokens** | The loop's own token hook (`.yoke/loop-status.json`, claude runner via `--output-format stream-json`; model id included). Gemini/Codex runners do not report usage yet — recorded as `null`, a documented gap. |
-| **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`)
-
-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.
-
-## Running it
-
-```bash
-npm run build
-node bench/run.mjs --runner=claude   # or gemini / codex
-```
-
-Each run copies the fixture to `bench/.runs/<runner>-<stamp>` (git-ignored), git-inits it,
-drives `yoke loop run --json --max=6 --timeout=10`, and writes a result JSON to
-`bench/results/`. Runs are billed against your own accounts for the agent CLIs involved.
-
-## Caveats (read before quoting numbers)
-
-- **N=1 per run.** Agent runs are stochastic; treat single runs as indicative, not
-  statistically robust. Re-run and compare.
-- Model identity matters more than CLI identity: `tokens.model` records what actually served
-  the run. Different default models per CLI make "claude vs gemini" really "model X vs model Y".
-- 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.
-
-Results live in [`results/`](results/) — one JSON per run, summarized in
-[`RESULTS.md`](RESULTS.md).
+# Yoke benchmark — tokens · speed · quality
+
+Reproducible cross-runner benchmark for the Yoke loop. One fixed fixture project, the same
+PRD for every runner, three measured dimensions:
+
+| Dimension | How it is measured |
+|---|---|
+| **Tokens** | The loop's own token hook (`.yoke/loop-status.json`, claude runner via `--output-format stream-json`; model id included). Gemini/Codex runners do not report usage yet — recorded as `null`, a documented gap. |
+| **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`)
+
+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.
+
+## Running it
+
+```bash
+npm run build
+node bench/run.mjs --runner=claude   # or gemini / codex
+node bench/run-matrix.mjs --label=release-1.0
+```
+
+Each run copies the fixture to `bench/.runs/<runner>-<stamp>` (git-ignored), git-inits it,
+drives `yoke loop run --json --max=6 --timeout=10`, and writes a result JSON to
+`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.
+
+## Caveats (read before quoting numbers)
+
+- **N=1 per run.** Agent runs are stochastic; treat single runs as indicative, not
+  statistically robust. Re-run and compare.
+- Model identity matters more than CLI identity: `tokens.model` records what actually served
+  the run. Different default models per CLI make "claude vs gemini" really "model X vs model Y".
+- 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.
+
+Results live in [`results/`](results/) — one JSON per run, summarized in
+[`RESULTS.md`](RESULTS.md).