@hecer/yoke 0.8.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,130 +1,169 @@
-# Changelog
-
-## 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,22 +2,36 @@
 
 # 🐂 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**.
 
+[![npm](https://img.shields.io/npm/v/%40hecer%2Fyoke?logo=npm&color=CB3837)](https://www.npmjs.com/package/@hecer/yoke)
+[![npm downloads](https://img.shields.io/npm/dm/%40hecer%2Fyoke?logo=npm)](https://www.npmjs.com/package/@hecer/yoke)
 [![CI](https://github.com/HECer/yoke/actions/workflows/ci.yml/badge.svg)](https://github.com/HECer/yoke/actions/workflows/ci.yml)
 [![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-322%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)
 
+**Install:** [`npm i -g @hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke)
+
 </div>
 
 > **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
@@ -29,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.
 
@@ -46,16 +60,18 @@ $ yoke prd check reading-app
 
 $ yoke loop on reading-app
 $ yoke loop run reading-app --isolate --review --max=10
-▶ STORY-1 (0/8) — implementing… · verifying… · reviewing… ✔ committed → 1/8
-▶ STORY-2 (1/8) — implementing… · verifying… ✔ committed → 2/8
-▶ STORY-3 (2/8) — implementing… · verifying… ✘ blocked: story did not verify (tests red)
+▶ STORY-1 (0/8 · 0%) — implementing… · verifying… · reviewing… · committing…
+✓ STORY-1 done in 3m12s — 1/8 (13%) · ~22m left
+▶ STORY-2 (1/8 · 13%) — implementing… · ~22m left (Ø 3m12s/story)
+✓ STORY-2 done in 2m48s — 2/8 (25%) · ~18m left
+▶ STORY-3 (2/8 · 25%) — implementing… ✘ blocked: story did not verify (tests red)
                                               # nothing was committed. fix, then re-run.
 
 $ 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 — 322 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
 
@@ -130,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 |
 
@@ -150,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 |
 
@@ -183,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.
 
@@ -197,7 +214,7 @@ Three layers — **Canon** (`yoke validate`) → **Retrofit** (`yoke retrofit`)
 > instructions (tech stack, workflow, `@`-includes) inside it. Works in any yoke-written file;
 > content *outside* the markers is still replaced (and backed up under `.yoke/backup/`).
 
-## 🧰 What's in the canon — 27 skills
+## 🧰 What's in the canon — 28 skills
 
 `yoke retrofit` installs all of these into each agent natively. Provenance is credited in [`canon/skills/ATTRIBUTION.md`](canon/skills/ATTRIBUTION.md).
 
@@ -233,13 +250,14 @@ To stop overlapping skills from auto-invoking against each other, `canon/AGENTS.
 | `retro` | Engineering retrospective from commit history |
 | `document-release` | Post-ship documentation sync (README / CHANGELOG / …) |
 
-**Yoke-native** — *authored or adapted for this harness (7)*
+**Yoke-native** — *authored or adapted for this harness (8)*
 
 | Skill | What it does |
 |---|---|
 | `yoke-retrofit` | Set up the Yoke harness in a project (detect → plan → apply) |
 | `authoring-prd` | Slice a product idea into loop-ready stories with testable acceptance criteria |
 | `minimal-code` | Write the least code that solves the task (YAGNI; ponytail-derived) |
+| `performance` | Efficiency as a measured requirement: benchmarks as tests, budgets as gates, optimizations local + documented |
 | `maintaining-context` | Keep `.yoke/context/` the durable source of truth (the Context layer) |
 | `workflow` | The default order of operations, from idea to deploy |
 | `unslop-ui` | Detect & remove AI-slop design tells (purple gradients, neon glow, emoji-icons…) |
@@ -302,6 +320,7 @@ yoke loop run . \
   --runner=codex \               # implement with Codex…
   --reviewer=claude \            # …review with Claude (role separation)
   --isolate \                    # each story in a throwaway git worktree
+  --on-ambiguity=abort \         # strict: stop on undecidable criteria instead of guessing
   --max=20
 yoke loop off .                 # disable
 ```
@@ -381,6 +400,30 @@ Enable strict mode per run with `yoke loop run . --on-ambiguity=abort` or per pr
 put every clarifying question into the PRD **before** the loop starts (`yoke prd draft`
 criteria must be testable and decision-free).
 
+### 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:
+
+- **Per story:** write the requirement as a **measurable acceptance criterion**
+  ("imports 1M rows in < 2s, asserted by the bench test") and let your verify tests measure
+  it — no new machinery needed.
+- **Per project:** wire a benchmark as a standing **perf gate** in `.yoke/config.yaml`:
+
+  ```yaml
+  perf:
+    command: node bench/check-budget.mjs   # exit 0 = within budget
+    retries: 1                             # benchmarks are noisy; same retry logic as verify
+  ```
+
+  The loop runs it **after verify** on every story (phase `perf`, with `YOKE_STORY` set); a
+  red benchmark blocks the story — `story S6 exceeded its performance budget: p95 62ms > budget 50ms` —
+  no matter how clean the diff was. The implementer prompt names the budget command, so the
+  agent knows not to trade hot-path efficiency for style and never "simplifies away" an
+  optimization without re-running the benchmark. The `performance` canon skill carries the
+  method: profile first, optimize leaves not boundaries, commit benchmarks as tests, version
+  the *why* of every optimization in `context/DECISIONS.md`.
+
 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
@@ -555,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.
+"""