@hecer/yoke 0.9.0 → 1.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "yoke",
+  "owner": { "name": "HECer" },
+  "metadata": { "description": "Yoke — cross-agent coding harness for Claude Code, Codex CLI, and Gemini CLI" },
+  "plugins": [
+    {
+      "name": "yoke",
+      "source": "./",
+      "description": "One curated skill canon plus mechanical safety gates and an autonomous loop (yoke CLI: npm i -g @hecer/yoke).",
+      "author": { "name": "HECer" },
+      "homepage": "https://github.com/HECer/yoke",
+      "repository": "https://github.com/HECer/yoke",
+      "license": "MIT",
+      "keywords": ["harness", "cross-agent", "tdd", "code-review", "codex", "gemini-cli"],
+      "category": "development"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "yoke",
+  "displayName": "Yoke",
+  "version": "1.1.0",
+  "description": "Cross-agent coding harness: one curated skill canon (TDD, brainstorming, plans, reviews, shipping, design verification) plus mechanical safety gates and an autonomous loop via the yoke CLI.",
+  "author": { "name": "HECer", "url": "https://github.com/HECer" },
+  "homepage": "https://github.com/HECer/yoke#readme",
+  "repository": "https://github.com/HECer/yoke",
+  "license": "MIT",
+  "keywords": ["harness", "cross-agent", "tdd", "code-review", "autonomous-loop", "codex", "gemini-cli"],
+  "skills": "./canon/skills/"
+}

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,149 +1,192 @@
-# 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.1.0 — 2026-07-30
+
+### Added
+- Shared five-question `yoke setup` wizard with provider-aware defaults for Claude, Codex, and Gemini.
+- Persisted default runner selection and `auto|critical` loop decision policies.
+- Provider-neutral `yoke-workflow` skill for planning questions, approved-plan PRD handoff, autonomous story execution, and critical-decision resume.
+- Structured critical-decision requests with `yoke loop decision` and `yoke loop answer`; answers are validated, committed under the configured human identity, and resume the same story.
+- Approved `.yoke/plan.md` context in PRD drafting and a lint gate for unresolved planning placeholders.
+
+### Fixed
+- Retrofit and loop on/off now preserve timeout, decision, runner, and permission settings.
+- Empty projects prefer the active agent host instead of silently installing Claude artifacts in Codex.
+- Loop and PRD runner selection now prefer an explicit flag, then the configured runner, then the active host.
+- Retrofit reports no longer label every provider as Claude Code.
+- Critical-decision resumes retain isolation, review, runner, permissions, timeout, JSON, policy, and iteration settings instead of falling back to an unreviewed default run.
+- Decision answers use an atomic owner-token lock and recoverable request journal, are checked against the active PRD story, bounded as untrusted data, and committed path-by-path so unrelated edits cannot enter the human-owned commit.
+- Decision recovery now binds the exact selected answer to its commit, rolls back only its own interrupted context append, namespaces resume state per project/worktree, and serializes cleanup with loop startup.
+- Active agent session markers now outrank globally configured provider home directories, and setup rejects partially invalid agent lists.
+
+### Changed
+- New setups enable the loop by default and choose `decisionPolicy: auto`; the wizard can select `critical` or disable the loop.
+- Legacy `loop.onAmbiguity` and `--on-ambiguity` remain compatibility aliases.
+
+## 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.