@hecer/yoke 0.2.0 → 0.8.0

package/docs/superpowers/specs/2026-06-27-forge-cross-agent-harness-design.md

@@ -0,0 +1,144 @@
+# Forge — Cross-Agent Coding Harness + Retrofit-Skill + Loop
+
+**Status:** Design approved 2026-06-27
+**Working name:** Forge (changeable)
+
+## Problem & Goal
+
+Build two deliverables on one shared foundation:
+
+1. **Harness** — a cross-agent coding harness runnable across **Claude Code + OpenAI Codex CLI + Gemini CLI**.
+2. **Retrofit-Skill** — a user-invocable skill that, run inside any existing project, rebuilds that project's harness for more **efficiency**, better **quality**, and more **autonomous** agent action.
+
+Both need an autonomous **Loop** variant (Ralph-loop pattern, per video `xBygL_fIK78` "Claude Code and Codex Don't Need You Anymore", Hunter Sneed).
+
+**Build principle:** one source-of-truth → idiomatic native artifacts per harness (wshobson/agents-style), NOT lowest-common-denominator translation. No drift.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Target environment | Cross-agent: Claude Code + Codex CLI + Gemini CLI |
+| Artifact model | One source-of-truth (Canon); the skill is the installer |
+| Packaging | Ansatz 1: Monorepo Canon + runtime-generating skill |
+| Build sequence | A (Canon) complete → B (Retrofit-Skill) → C (Loop) |
+| Generation | At runtime inside the skill (no Make; Windows-native) |
+| Loop autonomy | Aggressive-autonomous with hard mechanical gates |
+| Loop driver | Spec/PRD file with `passes:true` stories (Ralph standard) |
+| **Loop opt-in** | **Loop (C) is OPTIONAL & configurable.** Retrofit asks whether to enable it; toggle on/off any time via one simple command/flag. Default: OFF until explicitly enabled. |
+
+## Stack Decisions (researched, adversarially verified 2026-06-27)
+
+| Category | Tool | Verdict |
+|---|---|---|
+| Methodology spine | **superpowers** | KEEP — only one with native install paths for all 3 agents (Gemini-parity anchor) |
+| Role-team overlay | **gstack** | KEEP — Claude/Codex first-class, Gemini benchmark-only (issue #619) |
+| Token efficiency | **rtk** | KEEP — Windows caveat: auto-rewrite needs WSL else instruction-mode |
+| Code-graph | **graphify** | KEEP (user's informed choice) — MIT, multimodal; heuristic + static index tradeoff accepted |
+| — | jcodemunch | OUT — proprietary/paid license = showstopper for bundling/retrofitting |
+| Loop core | **gsd-pi** | KEEP as loop reference — milestones→slices→tasks, mechanical HITL blockers |
+| Safety/policy | **safe-agentic-workflow** | KEEP as policy layer — Stop-the-Line gates + role separation |
+| Browser/dogfood | **Playwright MCP** | ADD — only one native-MCP across all 3 agents; cleanest Windows story |
+| — | dogfood/agent-browser skill | OUT — Claude-only (MCP layer optional for token-tight cases) |
+| Instruction baseline | **AGENTS.md** | ADD — portable canon across 28+ agents |
+| Generator architecture | **wshobson/agents** pattern | ADOPT — source-of-truth → idiomatic per-harness |
+
+**Deferred (later swap notes):** Serena (LSP-accurate code-graph) if graphify's heuristic/staleness becomes limiting; sub-agents-skills (cross-model delegation); native plugin packaging (Ansatz 3).
+
+## Architecture — 3 layers
+
+```
+A: CANON (this repo, harness-agnostic source-of-truth)
+   → read by →
+B: RETROFIT-SKILL (runtime generator): detect → plan → generate → wire → report
+   → emits idiomatic artifacts into →
+   Claude Code | Codex CLI | Gemini CLI
+C: LOOP-ENGINE (autonomous Ralph mode, PRD-driven, hard gates) — usable by A and B
+```
+
+### Baustein A — The Canon
+
+```
+canon/
+  AGENTS.md              # portable baseline instructions (the spine)
+  skills/                # harness-agnostic SKILL.md (superpowers spine + gstack roles)
+    brainstorming/  test-driven-development/  investigate/  ...
+    ceo-review/  eng-review/  qa/  security/  ship/  ...
+  policy/
+    gates.md             # Stop-the-Line: DoD/Acceptance-Criteria required before implementation
+    roles.md             # role separation: implementer != merger != reviewer != security
+  loop/
+    loop-spec.md         # Ralph+GSD algorithm + stop condition
+    prd.schema.md        # PRD format (stories with passes:true)
+  tools/
+    rtk.md  graphify.md  playwright-mcp.md   # per-agent wiring manifests
+  manifest.yaml          # contents + versions + which artifacts emit per agent
+```
+
+The Canon contains NO agent-specific paths — those are produced only in B.
+
+### Baustein B — Retrofit-Skill (5 phases)
+
+1. **detect** — scan target project: which agents (`.claude/`, `.codex/`, `.gemini/`, `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`), existing skills, hooks, MCP configs. Also detect rtk WSL availability on Windows. Read existing `.forge/config.yaml` if present (preserve prior loop choice).
+2. **plan** — propose an **additive, non-destructive** retrofit (never overwrite without backup + consent); show diff preview. **Ask whether to enable the autonomous Loop (C)** — default OFF; the answer is recorded in `.forge/config.yaml`. The Canon's skills/policy install regardless; loop artifacts are only wired when enabled.
+3. **generate** — emit idiomatic per detected agent from the Canon:
+   - **Claude**: `.claude/skills/`, `settings.json` hooks (rtk PreToolUse), MCP servers, `CLAUDE.md`→`AGENTS.md` symlink
+   - **Codex**: `AGENTS.md`, `config.toml` (MCP), `RTK.md`, skills dir
+   - **Gemini**: `.gemini/commands/*.toml`, `GEMINI.md` (+ `AGENTS.md` via `context.fileName`), `settings.json` `mcpServers`, optional `gemini-extension.json`
+4. **wire** — connect cross-agent tools with caveats handled (see Cross-Agent section).
+5. **report** — summary + diff; everything reversible (backup directory).
+
+### Baustein C — Loop-Engine (aggressive-autonomous, hard gates) — OPTIONAL
+
+**Opt-in & toggle-able.** The loop is a separable layer: the harness (Canon skills/policy/tools) is fully usable without it. Enablement is a single config flag plus a one-word command.
+
+- **Config:** `.forge/config.yaml` → `loop.enabled: true|false` (default `false`). Set by the retrofit `plan` prompt, or any time later.
+- **Toggle command:** `forge loop on` / `forge loop off` (also exposed as a slash-command per agent, e.g. `/forge-loop on|off`). `on` wires the loop artifacts (driver, PRD scaffolding, gate hooks) for every detected agent; `off` unwires them and disables the driver — both non-destructive and reversible (no Canon/skill changes, only loop wiring).
+- **`forge loop status`** reports enabled/disabled + current PRD progress.
+- When disabled, no loop artifacts are active and no autonomous runs can start; re-enabling restores them without re-running a full retrofit.
+
+When enabled, the thin driver starts **fresh context per iteration**:
+
+```
+while not (all PRD stories passes:true):
+    pre-dispatch gates  → missing tools / dirty worktree / git conflict → "blocked"
+    pick highest-priority unfinished story
+    Stop-the-Line gate  → DoD/AC present? else blocked
+    spawn fresh agent (claude -p | codex exec | gemini) in a git worktree
+    implement ONE story → tests green? → review iteration (different role)
+    update PRD (passes:true) + atomic commit
+    iteration-cap reached? → stop
+```
+
+- **State outside context**: PRD file + git. **Stop**: all stories `passes:true`.
+- **Gates mechanically enforced** (not voluntary), **worktree-isolated** → always rollback-able.
+- **Cross-agent**: same loop invokes the chosen agent CLI non-interactively.
+
+## Cross-Agent Specifics & the Gemini Asymmetry
+
+| Tool | Claude | Codex | Gemini |
+|---|---|---|---|
+| **rtk** | PreToolUse hook (Windows: needs WSL, else instruction-mode) | `AGENTS.md`/`RTK.md` | **no hook** → MCP tool OR `GEMINI.md` instruction |
+| **graphify** | MCP server | MCP server | MCP server (`mcpServers`) |
+| **Playwright** | MCP server | MCP server | MCP server |
+| **Instructions** | `CLAUDE.md`→`AGENTS.md` | `AGENTS.md` native | `GEMINI.md` + `AGENTS.md` via `context.fileName` |
+| **Slash-commands** | `.claude/` | TOML | `.gemini/commands/*.toml` |
+
+**Central asymmetry:** Gemini has **no hook system** → rtk's transparent rewriting is not 1:1 reproducible; generator falls back to MCP tool or GEMINI.md instruction. Codex-only flags (`model_reasoning_effort`, `resume`) are abstracted/emulated by the generator.
+
+## Testing
+
+- **TDD** (superpowers spine).
+- **B** tested against **fixture target projects** (various agent setups) → asserts correct artifacts emitted, **idempotent**, **non-destructive**.
+- **C** tested with a tiny PRD fixture completing in 1–2 iterations against a mock agent.
+- **Windows-native**: no Make; generator logic in the skill (or Node/Python). rtk WSL-fallback detected in `detect`, applied in `wire`.
+
+## Out of Scope (YAGNI, first cut)
+
+Native plugin packages (Ansatz 3); sub-agents-skills cross-model delegation; Serena swap; benchmark-models. All retrofittable later.
+
+## Open Risks
+
+- **Gemini parity** is the largest technical risk (no hooks; no session-continuity equivalent to Codex `resume`).
+- rtk's 60–90% savings is self-reported; real savings vary per command and per agent.
+- graphify is young (v0.8.x), heuristic edges, static index can go stale.

package/docs/superpowers/specs/2026-06-28-baustein-e-context-layer-design.md

@@ -0,0 +1,146 @@
+# Baustein E — Context Layer (durable cross-session context)
+
+**Status:** Design approved 2026-06-28
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-project-goal]], [[harness-stack-decisions]], [[harness-loop-technique]]
+
+## Problem & Goal
+
+The dev.to article ("A Claude Code Skills Stack") frames a three-layer division of labor:
+**gstack decides → GSD stabilizes context → Superpowers executes.** Yoke today has the
+Decision layer (ported gstack roles) and a strong Execution layer (superpowers methodology +
+the Ralph loop), but it never built the **Context layer** — GSD's actual contribution:
+durable, cross-session artifacts that prevent specification drift.
+
+Concretely, the loop's [`buildClaudePrompt`](../../../src/loop/runner.ts) injects **only the
+current story + its acceptance criteria**. Every fresh-context iteration starts blind to the
+project's overall goal, the decisions already made, and the gotchas already learned. Over many
+iterations this is exactly where drift leaks in. The user's own auto-memory does this job by
+hand; the harness should give its users the same thing.
+
+**Goal:** a durable Context layer — three markdown files under `.yoke/context/` that the loop
+**reads before each iteration** and **writes decisions back to**, plus a skill so interactive
+(non-loop) sessions honor the same files. This closes the spec-drift hole and completes the
+third leg of the article's model.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Scope | Loop **and** interactive sessions (retrofit scaffolds for all 3 agents) |
+| Write-back | **Hybrid**: loop deterministically auto-logs decisions; agents enrich `DECISIONS`/`KNOWLEDGE` via the skill |
+| Files location | `.yoke/context/` (agent-agnostic shared state, like `.yoke/prd.yaml`) |
+| Config | None new — injection auto-on when files present; prompt bound is a constant |
+| Backwards-compat | No `.yoke/context/` → loop prompt is byte-identical to today |
+| Out of scope | Routing/priority fix (separate Baustein F), structured decision schema, cross-file linking |
+
+## The three files — `.yoke/context/`
+
+| File | Role | Writer |
+|------|------|--------|
+| `PROJECT.md` | North star: goal, constraints, **non-goals**, success criteria | Human/brainstorm authored; retrofit scaffolds a template. Read-only input. |
+| `DECISIONS.md` | Append-only ADR ledger | Loop auto-appends per completed+verified story; agents append in interactive work. |
+| `KNOWLEDGE.md` | Gotchas, conventions, reusable learnings | Agent/human maintained via the skill. |
+
+The files are plain markdown — no schema, no required structure beyond `DECISIONS.md`'s
+append format (so the loop can append unambiguously). Missing or partial files are valid:
+the layer degrades gracefully (an absent file contributes nothing to the prompt).
+
+## Architecture
+
+### New module — `src/context/context.ts`
+Pure and unit-testable, structured like `src/loop/prd.ts`:
+
+- `loadContext(dir): ProjectContext` — read the three files if present; missing → empty strings. Never throws on absence.
+- `formatForPrompt(ctx, maxChars): string` — render a "Project context" block, **tail-bounding** each file to `maxChars` (constant, ~2 KB) so a large ledger can't blow up the prompt. Returns `''` when all three are empty.
+- `appendDecision(dir, entry): { rollback: () => void }` — append a `DECISIONS.md` entry and return a rollback that restores the prior file content (captured before the write). Creates the file if absent.
+
+`ProjectContext = { project: string; decisions: string; knowledge: string }`.
+
+A decision entry is formatted as:
+```
+## <YYYY-MM-DD> — <story-id>: <title>
+<one-line summary>
+```
+The date comes from the Node runtime at loop time (the loop is normal Node, not a Workflow
+script — `Date` is available).
+
+### Loop read — `src/loop/runner.ts`
+`buildClaudePrompt(story, context?)` and `buildReviewPrompt(story, context?)` gain an optional
+pre-formatted `context` string. When present, a "Project context" section is inserted **ahead
+of** the story block. The reviewer gets the north star too (so it reviews against goals, not
+just acceptance criteria). When `context` is undefined/empty, the prompts are unchanged.
+
+The loop loads + formats context once per iteration (`.yoke/context/` resolved relative to
+`targetDir`) and threads it through the runner/review call.
+
+### Loop write-back — `src/loop/loop.ts`
+After verify (and optional review) passes, **before the commit**:
+
+1. `appendDecision(contextDir, { storyId, title, summary })` → keep the returned `rollback`.
+2. `savePrd(passes:true)`.
+3. `commitAll(...)` — now also stages `DECISIONS.md`, so the decision and the `passes:true`
+   flip land in the **same atomic commit**.
+
+If the commit throws, revert **both**: `savePrd(prior stories)` *and* `rollback()` for the
+decision file. This preserves the existing invariant — *`passes:true` never persists without a
+commit* — and extends it to the decision ledger (no orphan decision without a commit).
+
+In `--isolate` mode the append happens inside the worktree before the worktree commit, so
+`integrate` fast-forwards the decision back into the main tree along with the code.
+
+### Retrofit scaffolding — `src/retrofit/`
+A retrofit action writes `.yoke/context/{PROJECT,DECISIONS,KNOWLEDGE}.md` from
+`canon/context/*.md` templates **only if absent** (non-destructive + idempotent, the same rule
+as every other artifact). Agent-agnostic — one set under `.yoke/` serves claude/codex/gemini,
+so it is emitted once regardless of `--agent`. The report lists the scaffolded files.
+
+### Skill — `canon/skills/maintaining-context/SKILL.md`
+Agent-facing, flows to all three agents via the existing planners + `manifest.yaml`:
+> Before substantial work, read `.yoke/context/PROJECT.md` for the north star and
+> `KNOWLEDGE.md` for known gotchas. When you make a non-obvious decision, append it to
+> `DECISIONS.md`. When you learn a reusable fact or gotcha, append it to `KNOWLEDGE.md`.
+
+This is what extends drift-protection from the loop to interactive sessions.
+
+### CLI — `src/cli.ts`
+- `yoke context init` — scaffold the three files standalone (idempotent, non-destructive).
+- `yoke context status` — show presence, byte sizes, and the last decision heading.
+
+## Data flow (loop iteration)
+
+```
+load PRD ─► pick story ─► load+format .yoke/context ─► runner(prompt + context)
+   ─► verify ─► [review] ─► appendDecision() ─► savePrd(passes:true) ─► commitAll(+DECISIONS.md)
+                                   └── on commit failure: rollback() + savePrd(prior) ──► blocked
+```
+
+## Error handling
+
+- Missing/partial context files: treated as empty; no error, prompt simply omits that part.
+- Oversized files: tail-bounded to a constant per file; never unbounded.
+- `appendDecision` before commit + rollback on commit failure: no orphan decisions.
+- Isolate mode: decision written in the worktree, carried back only on successful integrate.
+- `yoke context init` over existing files: skips them (reports "exists"), never overwrites.
+
+## Testing (subagent-driven TDD, like A–D)
+
+**context.ts units:** load with all/none/partial files present; `formatForPrompt` bounding +
+empty-returns-`''`; `appendDecision` format correctness + rollback restores prior content +
+creates file when absent.
+
+**loop:** prompt includes the context block when `.yoke/context/` present; prompt unchanged
+when absent; decision appended on success; **not** appended on a blocked story; both PRD and
+decision reverted on commit failure; isolate path carries the decision back via integrate.
+
+**retrofit:** scaffolds the three files; idempotent on re-run; non-destructive over existing
+files; emitted once for `--agent=all`.
+
+**canon:** `maintaining-context` present in `manifest.yaml`; `yoke validate canon` stays green.
+
+## Non-goals (YAGNI)
+
+- No new config keys (injection is automatic; bound is a constant).
+- No structured/parsed decision schema — markdown append only.
+- No cross-file linking or decision superseding.
+- Routing/priority arbitration is **Baustein F**, not this spec.

package/docs/superpowers/specs/2026-06-29-baustein-f-routing-design.md

@@ -0,0 +1,106 @@
+# Baustein F — Skill Routing/Precedence + Review-Family Consolidation
+
+**Status:** Design approved 2026-06-29
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-build-progress]], [[readme-always-update]]
+
+## Problem & Goal
+
+The dev.to skills-stack article's #1 warning is **auto-invocation chaos**: when superpowers
+(aggressive "1% chance → you MUST invoke") and gstack roles ("proactively suggest") are both
+installed, overlapping skills compete on the same triggers, causing random/redundant selection.
+Yoke's `canon/manifest.yaml` distinguishes `kind: methodology|role` but emits **no precedence or
+routing** — nothing tells an agent which skill is canonical when several match.
+
+The collision is concentrated in the review family. From the actual descriptions:
+
+| Skill | Phase / angle | Status |
+|---|---|---|
+| `plan-eng-review` | plan-time, architecture | distinct ✓ |
+| `plan-ceo-review` | plan-time, product/scope | distinct ✓ |
+| `review` | **pre-merge, diff safety/structure** | collides ⚠ |
+| `eng-review` (14-line stub) | **pre-merge, architecture/edge-cases/tests** | collides ⚠ |
+| `requesting-code-review` | protocol: request a review | distinct ✓ |
+| `receiving-code-review` | protocol: handle feedback | distinct ✓ |
+
+The one real overlap is `eng-review` ↔ `review` — both "review the change before merge."
+
+**Goal:** emit an explicit routing/precedence into every agent so auto-invocation resolves
+deterministically, and collapse the `eng-review`/`review` overlap into one canonical pre-merge
+review skill.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Routing location | Authored prose section in `canon/AGENTS.md` (injected verbatim into all 3 agents) — NOT a new manifest field or generator |
+| Precedence rule | Methodology (HOW) before role (perspective); process before implementation |
+| Review collision | Fold `eng-review`'s checklist into `review`; **remove `eng-review`**; `review` becomes the single canonical pre-merge code review |
+| Description hygiene | Sharpen the remaining review-family descriptions so triggers are phase-distinct, non-overlapping |
+| Skill count | Canon 25 → **24** |
+| README | Update the skills catalog (Roles 8→7, total 25→24) — **mandatory deliverable** |
+| Out of scope (YAGNI) | No NLP trigger-collision validator (too fragile); no `priority` manifest field + generator (the `kind` distinction + authored prose suffices) |
+
+## Architecture
+
+### 1. Routing section in `canon/AGENTS.md`
+A new "Skill routing & precedence" section appended to the baseline (which already covers
+quality-first/stop-the-line/role-separation). It states three things:
+
+1. **Precedence** — methodology skills decide *how* to work and take precedence over role skills
+   (which add a perspective). Process before implementation.
+2. **Canonical entrypoint per concern** — a small map, especially the review family:
+   - Plan-time architecture review → `plan-eng-review`
+   - Plan-time product/scope review → `plan-ceo-review`
+   - **Pre-merge code review → `review`** (the single canonical one)
+   - Requesting a review (dispatch a reviewer) → `requesting-code-review`
+   - Handling review feedback → `receiving-code-review`
+   - Build flow / order of operations → `workflow`
+3. **Arbitration rule** — "These skills declare their own triggers aggressively; when several
+   match the same task, this precedence + the most-specific-entrypoint rule decides. Don't run
+   two skills that serve the same concern."
+
+`canon/AGENTS.md` is copied verbatim by the Claude/Codex/Gemini planners and imported by the
+generated `CLAUDE.md`/`GEMINI.md`, so this reaches all three agents with no generator change.
+
+### 2. Review-family consolidation
+- **`review`** absorbs `eng-review`'s checklist: in addition to diff safety (SQL, trust
+  boundaries, side effects), it now also covers architecture fit, edge cases, test coverage, and
+  performance — the engineering-manager angle. One canonical pre-merge review.
+- **`eng-review` removed**: delete `canon/skills/eng-review/` and its `manifest.yaml` entry.
+- **Descriptions sharpened**: each review-family skill's description names its phase explicitly
+  so triggers don't overlap (plan-time vs pre-merge vs protocol).
+
+### 3. Manifest + validator
+- Remove the `eng-review` entry from `canon/manifest.yaml`.
+- `validateCanon` must stay green (it validates that each listed skill has a dir + frontmatter;
+  removing the entry + dir keeps it consistent). No validator code change required unless a test
+  hard-codes the skill list.
+
+### 4. README (mandatory)
+Update the skills catalog: remove the `eng-review` row, move its purpose into the `review` row,
+change the Roles count 8→7 and the total 25→24. Per the standing rule, the README must reflect
+what shipped.
+
+## Data flow (how routing reaches an agent)
+```
+canon/AGENTS.md (routing section)
+   └─ planClaude → AGENTS.md + CLAUDE.md (@AGENTS.md import)   → Claude reads precedence
+   └─ planCodex  → AGENTS.md (Codex reads it natively)          → Codex reads precedence
+   └─ planGemini → GEMINI.md + .gemini/settings (AGENTS.md ctx) → Gemini reads precedence
+```
+
+## Testing
+- `tests/canon/real-canon.test.ts`: assert `eng-review` is NOT in the manifest; assert
+  `canon/AGENTS.md` contains the routing section (e.g. a stable heading + the "Pre-merge code
+  review → `review`" line); `validateCanon('canon')` stays zero-error.
+- `tests/retrofit/plan-dispatch.test.ts` (or planners tests): the emitted skill set no longer
+  includes `eng-review`; total skill count reflects 24. Adjust any hard-coded count.
+- `review` skill still validates (frontmatter intact after the checklist merge).
+- Full suite green; `tsc` clean.
+
+## Non-goals (YAGNI)
+- No automated trigger-collision detection.
+- No new manifest `priority` field or routing generator.
+- No change to plan-ceo-review / plan-eng-review / requesting- / receiving-code-review bodies
+  beyond description sharpening.

package/docs/superpowers/specs/2026-06-29-baustein-g-loop-observability-design.md

@@ -0,0 +1,186 @@
+# Baustein G — Loop Observability (heartbeat, timeout, live feedback)
+
+**Status:** Design approved 2026-06-29
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-loop-technique]], [[harness-build-progress]]
+
+## Problem & Goal
+
+A real incident: the autonomous loop ran on a downstream project (NewMarket) and sat
+**blocked for ~5 hours, completely invisibly**. A story failed its verify gate, the loop
+correctly returned `blocked` and stopped — but that outcome was printed to the stdout of a
+detached background command and never surfaced. The user saw "running forever," couldn't tell
+progress from a hang, and `yoke loop status` only reported the PRD count (`18/45`), not *why*
+nothing was advancing.
+
+Two gaps caused this:
+1. **No durable, queryable run state.** `blocked` (and its reason) lived only in transient
+   stdout. There was no artifact to glance at.
+2. **No agent-run timeout.** A genuinely hung nested agent (`claude -p`) would wedge the loop
+   indefinitely — only `verify` had a timeout, not the implementation run.
+
+**Timeout must not punish slow-but-working agents.** A fixed *total-runtime* timeout cannot tell
+"hung" from "working, just slow" and would kill a legitimately long story. So G uses an
+**inactivity (idle) timeout**, not a wall-clock one: it measures time since the agent's *last
+sign of life* (its last output byte), not total duration. An agent that keeps emitting output
+runs for an unbounded time; only true silence is treated as a hang. The same output stream that
+gives the user live feedback IS the liveness signal — feedback and hang-detection are one.
+
+**Goal:** make the loop observable and self-limiting. The loop continuously reports where it
+is (which story, which phase, why blocked) through **token-free, harness-side channels**, and
+a per-iteration timeout breaks true hangs.
+
+**Design principle — maximize free feedback.** All feedback added here is produced by the loop
+driver (Node: console + local files), never by an agent. It costs **zero agent tokens**. The
+only token cost in the loop remains the nested agent runs themselves, which G does not change.
+So we deliberately make local feedback dense and frequent.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Scope | Heartbeat status file + `yoke loop status` upgrade + agent-run timeout + blocked-leftover reporting + live console narration + append log |
+| Timeout kind | **Idle (no-output) timeout**, NOT total runtime. Resets on every output byte; only true silence counts. Total runtime is unbounded while the agent keeps producing output. |
+| Timeout on expiry | Kill the child → treated as a normal failure → `blocked` → loop stops (consistent with runner-fail / verify-fail / review-reject). No silent skip. |
+| Timeout default | 20 minutes of **silence**; `--timeout=<minutes>` flag > `config.loop.timeoutMinutes` > default. `0` disables. |
+| Timeout mechanism | A small watchdog wrapper (`src/loop/watchdog.ts`) runs the agent as a child, forwards stdio (prompt in, output live out), and kills on idle expiry. Keeps `runLoop`/runner synchronous — no async ripple. |
+| Feedback channels | Console narration + `.yoke/loop-status.json` (current state) + `.yoke/loop.log` (append-only timeline). All Node-side, 0 tokens. |
+| Backwards-compat | No status file → `yoke loop status` behaves exactly as today. Reporter is injectable and defaults to a real impl; existing `runLoop` tests pass a no-op. |
+| Out of scope (YAGNI) | No token metering of nested agents (technically not exposable), no log streaming server, no web dashboard. |
+
+## Architecture
+
+All new surface lives in the `loop/` subsystem.
+
+### 1. `src/loop/reporter.ts` (new) — status types + reporter + reader
+```ts
+type LoopState = 'running' | 'blocked' | 'complete' | 'cap-reached'
+type LoopPhase = 'implementing' | 'verifying' | 'reviewing' | 'committing'
+
+interface LoopStatus {
+  state: LoopState
+  phase?: LoopPhase          // only meaningful while state === 'running'
+  story?: string
+  storyTitle?: string
+  reason?: string            // populated on 'blocked'
+  iteration: number
+  progress: { passed: number; total: number }
+  startedAt: string          // ISO — when the current story/iteration began
+  updatedAt: string          // ISO — last heartbeat write
+}
+
+interface LoopReporter {
+  storyStart(story, iteration, progress): void   // → state:running, phase:implementing
+  phase(phase: LoopPhase): void                  // → updates phase + updatedAt
+  blocked(reason: string): void                  // → state:blocked
+  complete(progress): void                       // → state:complete
+  capReached(progress): void                     // → state:cap-reached
+}
+
+makeReporter(dir, opts?: { quiet?: boolean }, now?: () => Date): LoopReporter
+readStatus(dir): LoopStatus | null
+```
+The default `makeReporter` writes three places on every event:
+- **`.yoke/loop-status.json`** — the single current `LoopStatus` (overwritten atomically: temp file + rename).
+- **`.yoke/loop.log`** — appends one line: `<ISO>  <state/phase>  <story>  <detail>`.
+- **console** — a human line (suppressed when `quiet`): e.g.
+  - `▶ S6-seed-rich (19/45) — implementing…`
+  - `  ✓ verified`  /  `  ✓ reviewed`  /  `  ✓ committed → 20/45`
+  - `■ blocked on S6-seed-rich: verify failed (working tree left dirty — clean before restart)`
+
+`now` is injectable for deterministic tests. Timestamps use the Node runtime (`Date`),
+which is available (the loop is not a Workflow script).
+
+### 2. `src/loop/loop.ts` — drive the reporter
+`runLoop` takes an optional `reporter: LoopReporter` in `LoopOptions` (default: a no-op so the
+existing tests are untouched; `run-command` injects the real one). At each boundary it calls:
+`storyStart` before dispatch → `phase('verifying')` before verify → `phase('reviewing')` before
+review → `phase('committing')` before commit → `complete`/`capReached`/`blocked` at terminal
+returns. The **blocked** call's reason is enriched: if the working tree is dirty
+(`opts.git.isClean(targetDir) === false`) after a block, append
+`" (working tree has uncommitted changes from the blocked story — review/clean before re-running)"`.
+This is the S5 leftover case made explicit.
+
+### 3. `src/loop/watchdog.ts` (new) — idle-timeout wrapper
+A tiny standalone CLI: `node watchdog.js --idle-ms=<N> -- <command> [args...]`.
+- Spawns `<command>` with piped stdio. Forwards its own stdin to the child (so the prompt still
+  reaches `claude -p`) and the child's stdout/stderr to its own (so live output still reaches
+  the user — the feedback channel).
+- Maintains an idle timer reset on **every** stdout/stderr chunk. On expiry it kills the child
+  (SIGTERM, then SIGKILL after a short grace; on win32 `taskkill /pid /t /f` for the tree) and
+  exits **124** (timeout convention). Otherwise it exits with the child's own exit code.
+- `--idle-ms=0` means no watchdog (spawn-through with no timer).
+All the async/stream complexity lives here, isolated and unit-testable. Nothing else in the
+loop becomes async.
+
+### 4. `src/loop/runner.ts` — run the agent through the watchdog
+`Invocation` gains an optional `idleTimeoutMs?: number`. When set (>0), `runCli` runs the agent
+**through the watchdog**: `node <dist>/loop/watchdog.js --idle-ms=<N> -- <command> <args...>`,
+with the prompt still piped via stdin. `execSync` blocks on the watchdog (runner stays
+synchronous). A watchdog exit of 124 (or any non-zero) is caught as today →
+`{ success: false, summary: 'no output for Nm — treated as hung' }` → the loop blocks. When
+`idleTimeoutMs` is unset/0, the agent runs directly as before. `makeRunner`/`makeReviewRunner`
+accept and thread `idleTimeoutMs`; the reviewer run uses the same budget.
+
+### 5. `src/loop/run-command.ts` — wire + upgrade `loop status`
+- `runLoopCommand` resolves the idle timeout (`--timeout` flag > `config.loop.timeoutMinutes` >
+  default 20 minutes; `0` disables), builds the real `makeReporter(targetDir)`, builds runners
+  with the resolved `idleTimeoutMs`, and passes the reporter into `runLoop`.
+- `loopStatus(targetDir)` reads `readStatus(targetDir)`. If present, it renders state + phase +
+  story + title + reason + iteration + a relative `updatedAt`, and — when `state==='running'`
+  and `updatedAt` is older than the timeout — a `possibly stuck (no update in Nm)` hint. If
+  absent, it falls back to today's `enabled + PRD progress` output verbatim.
+
+### 6. `src/retrofit/config.ts` — optional config field
+`loop.timeoutMinutes?: number` (idle minutes) added to the schema (optional, backwards-compatible).
+
+### 7. `src/cli.ts` — flag + gitignore note
+Parse `--timeout=<minutes>` on `yoke loop run`. `.yoke/loop-status.json` and `.yoke/loop.log`
+are runtime artifacts — ensure the retrofit gitignore covers them (or document that they are
+local-only). They must NOT block the clean-tree gate: the loop writes them under `.yoke/`,
+which retrofit already gitignores for `worktrees`/`backup`; extend that to these two files.
+
+## Data flow (one iteration)
+```
+storyStart(S6) ─► [console ▶ / status running:implementing / log]
+   runner(idle-watchdog) ─► phase(verifying) ─► verify ─► phase(reviewing) ─► [review]
+   ─► phase(committing) ─► appendDecision ─► savePrd(passes) ─► commitAll
+   ─► [console ✓ committed → 20/45]
+on any failure ─► blocked(reason + leftover-hint) ─► [console ■ / status blocked / log] ─► return
+```
+
+## Error handling
+- Status writes are best-effort and atomic (temp + rename); a write failure never aborts the
+  loop (wrapped, logged to console, swallowed) — observability must not break execution.
+- Timeout kills the child and surfaces as `blocked`; the clean-tree gate + leftover hint guard
+  the restart.
+- `readStatus` on a missing/corrupt file returns `null` → `loop status` falls back gracefully.
+
+## Testing (subagent-driven TDD, like A–F)
+- **reporter.ts:** status round-trip (write→read); missing file → null; each event sets the
+  right state/phase; `loop.log` appends one line per event; `quiet` suppresses console;
+  injected `now` makes timestamps deterministic; atomic write leaves no temp file behind.
+- **loop.ts:** reporter receives `storyStart`/`phase`/`complete` in order on success;
+  `blocked` with reason on a failed verify; leftover hint appended when `git.isClean` is false
+  on block; existing loop tests still pass with the default no-op reporter.
+- **watchdog.ts:** wrapping a child that keeps emitting output past the idle window is **not**
+  killed (proves slow-but-working survives); wrapping a silent child that outputs nothing is
+  killed after the idle window and exits 124; a fast child passes its exit code through; stdin
+  is forwarded to the child; `--idle-ms=0` never kills. (Use tiny `node -e` children with short
+  idle windows for deterministic, fast tests.)
+- **runner.ts:** when `idleTimeoutMs>0` the invocation runs through the watchdog wrapper (assert
+  the built command); when unset/0 it runs the agent directly; resolution order flag>config>20.
+- **run-command.ts:** `loopStatus` renders state+phase+reason when a status file exists; falls
+  back to PRD-only when absent; `--timeout` parsed and forwarded.
+- **config.ts:** `timeoutMinutes` accepted and optional.
+
+## What this would have done for the incident
+`yoke loop status .` →
+```
+Loop: BLOCKED on S5-segment-schemas "All 9 segment attribute schemas…"
+  phase: verifying · iteration 19 · 18/45 · last update 5h ago
+  reason: story did not verify (working tree has uncommitted changes — clean before restart)
+```
+…instead of `18/45`. And a true hang (no agent output at all) would self-terminate after 20
+minutes of silence as `blocked` — while a genuinely slow story that keeps streaming progress
+runs as long as it needs.