@hecer/yoke 0.9.0 → 1.1.0

package/README.md

@@ -2,6 +2,11 @@
 
 # 🐂 Yoke
 
+<!-- yoke:version:start -->1.1.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->559<!-- yoke:tests:end -->
+<!-- yoke:skills:start -->29<!-- 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-559%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)
 
@@ -20,7 +25,13 @@
 
 </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>/`.
+> **TL;DR** — `yoke setup .` asks five questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it story by story behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. If any gate is red, nothing is committed. When a story is done, there's a photo of it in `.yoke/proof/<story>/`.
+
+Yoke 1.1 is safe-by-default: provider CLIs use autonomous sandbox profiles unless `--unsafe`
+is explicit; reviews require a schema-valid verdict and a different model unless
+`--allow-self-review` is explicit; commits enforce the human identity from project config or Git.
+See [the 1.1 migration guide](docs/MIGRATING-TO-1.1.md) for setup/decision parity and
+[the 1.0 guide](docs/MIGRATING-TO-1.0.md) for the earlier safety-policy changes.
 
 ---
 
@@ -33,7 +44,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 +72,7 @@ $ ls reading-app/.yoke/proof/STORY-2/
 home.png  list.png                            # photographic evidence, labelled per story
 ```
 
-Every claim in that transcript is enforced by code paths with tests behind them — 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 — 559 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
 
 ## 🚀 Quickstart
 
@@ -74,15 +85,14 @@ yoke new my-app --idea="a CLI that tracks reading lists"
 yoke loop on my-app && yoke loop run my-app --isolate
 
 # — or retrofit an existing project —
-yoke validate canon                                          # 1) sanity-check the canon
-yoke retrofit /path/to/project --agent=all                   # 2) install (non-destructive)
-yoke loop on /path/to/project                                # 3) optional: the autonomous loop
+yoke setup /path/to/project                                  # interactive: agents, graph, loop, runner, decisions
+yoke validate canon                                          # sanity-check the canon
 yoke loop run /path/to/project --isolate --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.
 
-### Or install the skills as a Claude Code plugin
+### Skills before the first setup
 
 The canon is also packaged as a Claude Code plugin — the repo is its own marketplace:
 
@@ -93,6 +103,12 @@ The canon is also packaged as a Claude Code plugin — the repo is its own marke
 
 That gives you all canon skills under the `yoke:` namespace (e.g. `yoke:tdd`, `yoke:review`) inside Claude Code — no retrofit needed. The `yoke` CLI (loop, gates, retrofit for Codex/Gemini) still comes from `npm i -g @hecer/yoke`. Gemini CLI users can likewise `gemini extensions install https://github.com/HECer/yoke`.
 
+For Codex, no preinstalled skill is required: run `npx @hecer/yoke setup .` in a terminal, or
+ask Codex to run the five-question Yoke setup flow. The retrofit writes native skills to
+`.agents/skills/`, including `yoke-retrofit` and `yoke-workflow`; start a fresh Codex task if an
+already-open task does not discover newly installed skills. The npm package also contains
+`.codex-plugin/plugin.json` for Codex plugin hosts.
+
 ### Staying up to date
 
 Yoke checks for new releases npm/gh-style: a **non-blocking background check** (at most once a day, detached, offline-safe) prints a one-line hint when a newer version exists — upgrading itself is always an explicit act:
@@ -114,11 +130,11 @@ Auto-upgrade is deliberately **not** the default: a gate harness shouldn't chang
 
 Yoke is meant to be operated *by* your coding agent — after a retrofit, the agent has the skills, the safety policy, and the routing, so it knows the methodology. Copy-paste prompts (identical wording works for Claude Code, Codex CLI, and Gemini CLI):
 
-> **Set it up** — *"Install the Yoke harness in this project: run `yoke retrofit . --agent=all`, pick the code-graph you'd recommend for this codebase, and leave the autonomous loop disabled for now. Then summarise what changed and commit it."*
+> **Set it up** — *"Set up Yoke in this project. Ask me the Yoke setup questions one at a time with your recommendation, then run `yoke setup . --yes` with the selected host, agents, code graph, loop, runner, and decision policy. Commit in my configured identity."*
 
 > **Work the disciplined way** — *"From now on follow the Yoke skills you just installed: brainstorm → spec → plan → TDD → review before merging. Use the `review` skill before any merge."*
 
-> **Run autonomously** — *"Write `.yoke/prd.yaml` with one story per task (each needs acceptance criteria — see the `authoring-prd` skill), set `verify.command` in `.yoke/config.yaml`, enable the loop with `yoke loop on .`, then run it in small visible batches: `yoke loop run . --max=5`. After each batch show me `yoke loop status .`."*
+> **Plan, then run autonomously** — *"Use the `yoke-workflow` skill. Ask only the planning questions that materially change the product, write the approved plan and loop-ready stories, then execute every approved story without routine follow-ups. Follow the configured `auto` or `critical` decision policy."*
 
 > **Watch / unblock** — *"Run `yoke loop status .`. If it says BLOCKED, run the project's verify command, find the root cause, fix it without weakening tests, then continue the loop."*
 
@@ -132,14 +148,16 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 
 | Command | What it does | Exit codes |
 |---|---|---|
+| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--decision-policy=] [--loop\|--no-loop]` | Shared five-question setup for Claude, Codex, and Gemini; `--yes` applies supplied/default choices non-interactively | `0` · `1` invalid setup |
 | `yoke validate [canonDir]` | Validate the canon (schema, frontmatter, templates) | `0` valid · `1` errors |
 | `yoke new <dir> [--idea=] [--agent=] [--runner=] [--loop]` | Greenfield bootstrap: git init → scaffold → retrofit → context → PRD (drafted from `--idea`) → committed | `0` · `1` usage / non-empty dir / draft failed (scaffold survives) · `2` draft agent unavailable |
 | `yoke retrofit [dir] [--agent=claude,codex,gemini\|all] [--code-graph=graphify\|serena] [--loop]` | Install/update the harness, non-destructively | `0` |
 | `yoke prd draft [dir] --idea= [--runner=] [--force]` | Idea → 5–12 stories with testable acceptance criteria | `0` · `1` invalid/guarded · `2` agent unavailable |
-| `yoke prd check [dir]` | PRD lint gate (schema, 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\|decision\|answer\|resume\|run\|cleanup [dir]` | Autonomous loop; `decision` shows a critical stop, `answer` records it and resumes, `resume` retries a failed restart with the preserved safety options; 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 +174,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 +207,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.
 
@@ -203,7 +221,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 — 28 skills
+## 🧰 What's in the canon — 29 skills
 
 `yoke retrofit` installs all of these into each agent natively. Provenance is credited in [`canon/skills/ATTRIBUTION.md`](canon/skills/ATTRIBUTION.md).
 
@@ -239,11 +257,12 @@ 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 (8)*
+**Yoke-native** — *authored or adapted for this harness (9)*
 
 | Skill | What it does |
 |---|---|
 | `yoke-retrofit` | Set up the Yoke harness in a project (detect → plan → apply) |
+| `yoke-workflow` | Provider-neutral planning questions → approved PRD → autonomous stories → critical-decision resume |
 | `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 |
@@ -267,7 +286,7 @@ existing projects), then: creates and `git init`s the directory, writes a minima
 **context layer** (with `--idea` seeded into `PROJECT.md` as the north star), writes a commented
 **PRD template** to `.yoke/prd.yaml`, and makes the initial commit — so `--isolate` works from
 iteration 1. With `--idea`, it then drafts the PRD from your idea via an agent (`--runner=`,
-default `claude`) and commits it as a second commit (`docs: draft PRD from idea`).
+the configured runner or active host) and commits it as a second commit (`docs: draft PRD from idea`).
 
 - **Exit codes** — `0` success; `1` usage / non-empty dir / draft failure (the scaffold survives —
   retry with `yoke prd draft`); `2` requested draft agent unavailable.
@@ -276,16 +295,18 @@ default `claude`) and commits it as a second commit (`docs: draft PRD from idea`
 stories with testable behavioral acceptance criteria (greenfield STORY-1 scaffolds the project
 skeleton + test suite and wires `verify.command`). An existing PRD with stories is never
 overwritten without `--force`; the untouched template doesn't trigger the guard. Runs through
-the same idle-timeout watchdog as the loop (`--timeout`).
+the same idle-timeout watchdog as the loop (`--timeout`). If `.yoke/plan.md` exists, its approved
+goals, non-goals, constraints, and decisions are injected as settled context instead of being
+reopened by the drafting agent.
 
 **`yoke prd check [dir]`** is the chainable pre-loop lint gate: schema validation plus
-duplicate-id, empty-acceptance, and zero-stories checks. Exits `0` with
+duplicate-id, empty-acceptance, unresolved-placeholder, and zero-stories checks. Exits `0` with
 `✓ PRD valid — N stories, M pass`, `1` on any violation. The `authoring-prd` canon skill
 teaches interactive sessions the same story-slicing discipline.
 
 ## 🤖 The autonomous loop
 
-Opt-in and off by default. Each iteration starts a **fresh agent** and passes through hard gates before anything is committed:
+Opt-in; `yoke setup` recommends enabling it for new installs, while `retrofit` alone keeps it off unless requested. Each iteration starts a **fresh agent** and passes through hard gates before anything is committed:
 
 ```mermaid
 flowchart LR
@@ -309,7 +330,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
+  --decision-policy=critical \   # pause only for high-impact decisions; routine choices stay autonomous
   --max=20
 yoke loop off .                 # disable
 ```
@@ -369,25 +390,51 @@ A per-iteration **idle timeout** guards against a genuinely hung agent: if the a
 output is **never** killed — the output stream *is* the liveness signal. Set a project default
 with `loop.timeoutMinutes` in `.yoke/config.yaml`.
 
-### Ambiguous stories: questions belong in planning
+### Decision policy: autonomous by default, interrupt only when configured
 
-A loop run has nobody to ask, so the runner prompt always forbids questions. What the agent
-does when an acceptance criterion is genuinely ambiguous is configurable:
+Planning questions happen before the loop. The provider-neutral `yoke-workflow` skill asks only
+questions whose answer materially changes product behavior, scope, architecture, security, data
+ownership, external cost, or an irreversible choice. It saves the approved brief in
+`.yoke/plan.md`; `yoke prd draft` consumes it, and `yoke prd check` rejects explicit unresolved
+placeholders such as `TBD`.
 
-- **Default (`resolve`) — never stop:** the agent picks the interpretation most consistent
-  with the other criteria and the existing code, states it in its final message, and the loop
-  keeps going.
-- **Strict (`abort`):** the agent must not guess — it writes its open question(s) to
-  `.yoke/ambiguity.md` and stops. The loop consumes that file, skips verify (an unimplemented
-  story would otherwise sail through on pre-existing green tests), and blocks with the
-  question in the reason, e.g.
-  `story S6 stopped: ambiguous acceptance criteria — Which auth provider should S6 use?`
-  Answer by sharpening the story's acceptance criteria, then re-run.
+The unattended loop then follows `loop.decisionPolicy`:
+
+```yaml
+loop:
+  enabled: true
+  decisionPolicy: critical  # or auto
+runner:
+  agent: codex              # setup chooses the current host by default
+```
+
+- **`auto` (default):** routine ambiguity and implementation details are resolved using the
+  approved plan, acceptance criteria, current code, and project conventions. The loop does not
+  ask follow-up questions.
+- **`critical`:** routine choices are still resolved automatically. Only high-impact decisions
+  involving public architecture, security/privacy, destructive migration or data loss, material
+  external cost, legal/compliance exposure, or another irreversible choice may pause the story.
+  The agent writes a schema-validated request; the loop blocks before verify and preserves it as
+  `.yoke/pending-decision.yaml`.
+
+Inspect and answer a critical stop:
+
+```bash
+yoke loop decision .
+yoke loop answer . --choice=A --rationale="Matches the existing identity model"
+```
 
-Enable strict mode per run with `yoke loop run . --on-ambiguity=abort` or per project with
-`loop.onAmbiguity: abort` in `.yoke/config.yaml`. Either way, the cheapest fix is upstream:
-put every clarifying question into the PRD **before** the loop starts (`yoke prd draft`
-criteria must be testable and decision-free).
+`answer` validates the choice against the still-open story, appends it to
+`.yoke/context/DECISIONS.md`, commits only that file using the configured human identity, clears
+the pending request, and resumes the same story with the original runner, isolation, review,
+permission, timeout, JSON, decision-policy, and iteration settings intact. Add
+`--no-resume` when a supervisor should restart the loop separately. If the automatic restart
+cannot begin because a provider/reviewer is unavailable or another process owns the lock, run
+`yoke loop resume .`; its request-bound options are retained under Git's private state directory
+until a loop actually runs. To intentionally abandon an orphaned or stale private resume state,
+use `yoke loop resume . --discard`; pending decisions are never deleted by that command. Existing
+`loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` remain supported as compatibility aliases;
+new projects should use `decisionPolicy: auto|critical`.
 
 ### Performance budgets: efficiency as a gate, not a style
 
@@ -418,21 +465,26 @@ committed even if the agent process exited non-zero (a common Windows `.cmd`-wra
 A failing verify is retried up to `verify.retries` times (default 1) so a transient flake
 self-heals while a real failure still blocks.
 
-`.yoke/loop-status.json`, `.yoke/loop.log`, `.yoke/loop.lock`, `.yoke/story-durations.json`,
-and `.yoke/ambiguity.md` are runtime artifacts; `yoke retrofit` gitignores them (along with
+`.yoke/loop-status.json`, `.yoke/loop.log`, `.yoke/loop.lock`, its takeover/recovery leases, lock/decision temp files, `.yoke/story-durations.json`,
+`.yoke/ambiguity.md`, and the critical-decision request/answering files are runtime artifacts;
+`yoke retrofit` gitignores them (along with
 `.yoke/worktrees/`, `.yoke/backup/`, and `.yoke/proof/`) so they never trip the clean-tree gate.
 
 ### Single-flight guard + cleanup
 
 Two concurrent `yoke loop run`s would race on the PRD and status files, so the loop takes a
-**lock** (`.yoke/loop.lock`) for the duration of a run. A second invocation exits `2` with
+**lock** (`.yoke/loop.lock`) for the duration of a run. Complete lock metadata is published atomically;
+stale takeover is serialized by `.yoke/loop.lock.takeover`. A second invocation exits `2` with
 `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.
+when everything cleaned, `1` if any removal failed. 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.
 
 ## 🔍 Cross-model review (`yoke review`)
 
@@ -516,7 +568,8 @@ Yoke keeps durable, cross-session context so a fresh-context agent is never blin
 
 `yoke retrofit` scaffolds these files (non-destructively — your edits are never overwritten).
 The loop reads them into every agent + reviewer prompt and logs decisions back on each story's
-commit. Manage them directly with `yoke context init` and `yoke context status`. The
+commit. Decision history is explicitly delimited as untrusted reference data, so stored text is
+never treated as fresh instructions. Manage the files directly with `yoke context init` and `yoke context status`. The
 `maintaining-context` skill teaches agents to honour the same files during interactive work.
 
 > Commit `.yoke/context/` to git. The `--isolate` loop runs each iteration in a worktree
@@ -587,17 +640,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.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.
 
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (322 tests)
+npm test          # vitest (559 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).

package/bench/RESULTS.md

@@ -1,36 +1,46 @@
-# Benchmark results
-
-Fixture `string-kit` (3 stories, 16 pre-written assertions). Methodology and caveats:
-[README.md](README.md). One row per run — raw JSON in [`results/`](results/).
-
-## Runs
-
-| Date | Runner | Model (reported) | Result | Wall-clock | Input tok | Output tok | First-pass stories | src LOC |
-|---|---|---|---|---|---|---|---|---|
-| 2026-07-10 | claude | claude-opus-4-8 | ✅ 3/3 complete | 4 m 28 s | 42 957 | 9 817 | 3/3 (1 iteration each) | 39 |
-| 2026-07-10 | gemini | — | ⛔ blocked: CLI not authenticated on the bench machine (headless needs `GEMINI_API_KEY` or configured OAuth) | — | — | — | — | — |
-| — | codex | — | ⛔ not installed on the bench machine | — | — | — | — | — |
-
-Per-story wall-clock (claude run): STORY-1 72 s · STORY-2 114 s · STORY-3 81 s. Every story
-passed verify on the first iteration; the final quality check (all 16 assertions on the final
-tree, outside the loop) is green.
-
-## What the harness caught before producing a single number
-
-Building an honest benchmark is itself a verification pass. The first runs found two real
-Yoke bugs, both fixed in 0.3.0:
-
-1. **Availability-probe timeout** — `gemini --version` cold-starts in ~5.8 s on Windows; the
-   5 s probe timeout misreported an installed CLI as "not found on PATH". Now 20 s.
-2. **Gemini invocation** — Gemini CLI 0.33+ requires a value after `-p`; the runner's bare
-   `-p --yolo` died with "Not enough arguments following: p". The runner now relies on piped
-   stdin (which selects headless mode) and passes only `--yolo`.
-
-## Reading the numbers
-
-- Tokens come from the loop's own hook (claude runner only — gemini/codex reporting is an
-  open gap, see the multi-agent design doc).
-- N=1: indicative, not statistics. Re-run with `node bench/run.mjs --runner=<agent>` and
-  compare rows.
-- ~53 k tokens / ~4.5 minutes for a 3-story micro-backlog is the current price of the full
-  gate pipeline (fresh headless session per story + verify + atomic commit) on this fixture.
+# Benchmark results
+
+Result schema v1 records fixture version, sample label, permission profile, telemetry/model
+availability, verdict/blocker, conflicts, wall time, iterations, and final fixture-test status.
+
+Fixture `string-kit` (3 stories, 16 pre-written assertions). Methodology and caveats:
+[README.md](README.md). One row per run — raw JSON in [`results/`](results/).
+
+## Runs
+
+| Date | Runner | Model (reported) | Result | Wall-clock | Input tok | Output tok | First-pass stories | src LOC |
+|---|---|---|---|---|---|---|---|---|
+| 2026-07-27 | claude | unavailable | ⛔ blocked before implementation; zero synthetic usage is not counted | 11 s | — | — | 0/3 | 3 |
+| 2026-07-27 | codex | unavailable | ⛔ CLI probe failed on Windows with access denied | — | — | — | — | — |
+| 2026-07-27 | gemini | unavailable | ⛔ runner exited before implementation | 14 s | — | — | 0/3 | 3 |
+| 2026-07-10 | claude | claude-opus-4-8 | ✅ 3/3 complete | 4 m 28 s | 42 957 | 9 817 | 3/3 (1 iteration each) | 39 |
+| 2026-07-10 | gemini | — | ⛔ blocked: CLI not authenticated on the bench machine (headless needs `GEMINI_API_KEY` or configured OAuth) | — | — | — | — | — |
+| — | codex | — | ⛔ not installed on the bench machine | — | — | — | — | — |
+
+Per-story wall-clock (claude run): STORY-1 72 s · STORY-2 114 s · STORY-3 81 s. Every story
+passed verify on the first iteration; the final quality check (all 16 assertions on the final
+tree, outside the loop) is green.
+
+The 2026-07-27 release matrix produced no quality measurement: Claude and Gemini exited
+before changing the fixture, and the Codex executable could not be probed in this Windows
+environment. Raw rows preserve the exact runner diagnostics; no scores were inferred.
+
+## What the harness caught before producing a single number
+
+Building an honest benchmark is itself a verification pass. The first runs found two real
+Yoke bugs, both fixed in 0.3.0:
+
+1. **Availability-probe timeout** — `gemini --version` cold-starts in ~5.8 s on Windows; the
+   5 s probe timeout misreported an installed CLI as "not found on PATH". Now 20 s.
+2. **Gemini invocation** — Gemini CLI 0.33+ requires a value after `-p`; the runner's bare
+   `-p --yolo` died with "Not enough arguments following: p". The runner now relies on piped
+   stdin (which selects headless mode) and passes only `--yolo`.
+
+## Reading the numbers
+
+- Tokens come from the loop's own hook (claude runner only — gemini/codex reporting is an
+  open gap, see the multi-agent design doc).
+- N=1: indicative, not statistics. Re-run with `node bench/run.mjs --runner=<agent>` and
+  compare rows.
+- ~53 k tokens / ~4.5 minutes for a 3-story micro-backlog is the current price of the full
+  gate pipeline (fresh headless session per story + verify + atomic commit) on this fixture.

package/bench/result-schema.mjs

@@ -0,0 +1,12 @@
+export const requiredResultFields = [
+  'schemaVersion', 'fixtureVersion', 'runner', 'sampleLabel', 'permissionProfile',
+  'usageAvailable', 'modelAvailable', 'verdict', 'conflicts', 'wallClockMs',
+  'iterations', 'finalTestsPass',
+]
+
+export function validateResult(result) {
+  const missing = requiredResultFields.filter(key => !(key in result))
+  if (missing.length) throw new Error(`benchmark result missing: ${missing.join(', ')}`)
+  if (!['completed', 'blocked', 'unavailable', 'auth-failed'].includes(result.verdict)) throw new Error(`invalid verdict: ${result.verdict}`)
+  return result
+}