@hecer/yoke 1.6.0 → 1.6.1

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

@@ -1,186 +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.
+# 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.

package/docs/superpowers/specs/2026-06-29-baustein-h-loop-robustness-design.md

@@ -1,113 +1,113 @@
-# Baustein H — Loop Robustness (verify-as-truth + flaky-tolerant verify)
-
-**Status:** Design approved 2026-06-29
-**Component:** Yoke (🐂)
-**Relates to:** [[harness-build-progress]], [[harness-loop-technique]]
-
-## Problem & Goal
-
-Evidence from a real autonomous run (NewMarket, 52/57 stories): the loop blocked and needed
-human intervention on a handful of stories. Two of those block causes are **harness defects**,
-not project defects, and both are cheap to fix:
-
-1. **Runner exit-code is treated as ground truth (SE5).** The story was implemented and the full
-   suite was green (769/769), but the `claude` `.cmd` wrapper on Windows exited **127**. The loop
-   checks `result.success` *before* running verify, so it **blocked a successful story** on a
-   spurious exit code and didn't auto-commit. This contradicts the loop's own stated philosophy
-   (Baustein C2): *"independent verification is the source of truth, not the agent's exit code."*
-
-2. **No flaky-test tolerance (T4).** Under autonomous load, a heavy background task caused an
-   async test to time out — a **false** red, not a real defect. The single-shot verify gate
-   blocked the story. The user had to manually add `retry: 2` to the project's `vitest.config`.
-   That resilience belongs in the harness.
-
-**Goal:** make the loop trust **verify**, not the agent's exit code, and tolerate transient
-flakes — closing two real block causes without weakening the gate.
-
-**Out of scope (deferred):** cross-story regression repair (S5/S6 — a later story breaking an
-earlier story's tests). That needs its own design; this spec does not address it.
-
-## Key Decisions (locked)
-
-| Decision | Choice |
-|---|---|
-| Verify authority | The **implementer** runner's `success` flag is advisory; **verify decides**. Run verify regardless of runner exit, block only on verify failure. |
-| Runner-fail + verify-pass | Proceed (commit) — the exit code was a ghost. Note it via the reporter / summary. |
-| Runner-fail + verify-fail | Block, with a reason naming both signals. |
-| Reviewer runner | **Unchanged** — its non-zero exit *is* the reject verdict (there is no separate verify for the review). |
-| Flaky tolerance | `retryingVerifier(inner, retries)` re-runs a failing verify up to `retries` times; first pass wins. |
-| Retry default | `config.verify.retries` default **1** (one retry). `0` = strict/no-retry. A real failure still fails (twice). |
-| Out of scope | Cross-story regression repair; changing the reviewer's exit-code semantics. |
-
-## Architecture
-
-### 1. `src/loop/verify.ts` — `retryingVerifier`
-```ts
-export function retryingVerifier(inner: Verifier, retries: number): Verifier {
-  return (targetDir) => {
-    let last = inner(targetDir)
-    let attempt = 0
-    while (!last.passed && attempt < retries) {
-      attempt++
-      last = inner(targetDir)
-    }
-    if (last.passed && attempt > 0) {
-      return { passed: true, summary: `${last.summary} (passed on retry ${attempt})` }
-    }
-    return attempt > 0 && !last.passed
-      ? { passed: false, summary: `${last.summary} (still failing after ${attempt} retr${attempt === 1 ? 'y' : 'ies'})` }
-      : last
-  }
-}
-```
-Pure, injectable `inner` for tests (no real command needed).
-
-### 2. `src/loop/loop.ts` — verify is the gate
-In **both** the isolate and non-isolate paths, restructure the implementer step so verify always
-runs:
-
-- Run the implementer runner (keep `result` for its summary).
-- `reporter.phase('verifying')`; run `opts.verify(dir)`.
-- If verify **fails**: block. Reason = verify summary, and if the runner *also* reported failure,
-  prepend that (`runner reported failure (<summary>); verify also red: <verify summary>`).
-- If verify **passes**: proceed to review/commit even if `result.success` was false. When the
-  runner had reported failure, the committed decision/summary notes
-  `(runner exited non-zero but verify is green)` so the ghost is auditable.
-
-The reviewer step is untouched: `if (!reviewResult.success) → block` stays (exit = verdict).
-
-The Baustein-E invariant (no `passes:true` without a commit; decision rollback on commit failure)
-and the leftover-hint are preserved exactly — only the implementer-failure gate moves from
-"before verify" to "verify decides".
-
-### 3. `src/retrofit/config.ts` — `verify.retries`
-Extend the `verify` config object: `verify: { command: string; retries?: number }`.
-Backwards-compatible (optional).
-
-### 4. `src/loop/run-command.ts` — wire the retry
-When building the verifier from config, wrap it:
-`verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1)`.
-The injected-verifier test path (`opts.verify`) is unchanged.
-
-### 5. README + loop-spec
-Document: verify is the source of truth (a spurious agent exit code can't block a green story),
-and `verify.retries` (default 1) for flaky suites. Update `canon/loop/loop-spec.md` step 5.
-
-## Testing (subagent-driven TDD)
-- **verify.ts:** `retryingVerifier` passes immediately when inner passes (no retry); passes on
-  retry N when inner fails then passes; fails after exhausting retries; `retries: 0` = single
-  shot; summary notes the retry/exhaustion. Inner is a stub Verifier.
-- **loop.ts:** runner-fail + verify-pass → story is committed + `passes:true` (the SE5 case);
-  runner-fail + verify-fail → blocked with a combined reason; runner-pass + verify-fail →
-  blocked (unchanged); the reviewer still blocks on its own failure; existing invariant tests
-  (commit-failure revert, leftover hint) stay green; applies to both isolate and non-isolate.
-- **config.ts:** `verify.retries` accepted + optional.
-- **run-command.ts:** the built verifier is wrapped with the resolved retry count (assert via a
-  small seam or by config round-trip).
-- Full suite green; `tsc` clean.
-
-## What this would have done for the run
-- **SE5:** runner exits 127 but suite is 769/769 green → verify passes → story auto-commits. No
-  manual finalize.
-- **T4:** the load-flake fails once, the retry passes → story proceeds. No manual `vitest.config`
-  patch, no false block.
+# Baustein H — Loop Robustness (verify-as-truth + flaky-tolerant verify)
+
+**Status:** Design approved 2026-06-29
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-build-progress]], [[harness-loop-technique]]
+
+## Problem & Goal
+
+Evidence from a real autonomous run (NewMarket, 52/57 stories): the loop blocked and needed
+human intervention on a handful of stories. Two of those block causes are **harness defects**,
+not project defects, and both are cheap to fix:
+
+1. **Runner exit-code is treated as ground truth (SE5).** The story was implemented and the full
+   suite was green (769/769), but the `claude` `.cmd` wrapper on Windows exited **127**. The loop
+   checks `result.success` *before* running verify, so it **blocked a successful story** on a
+   spurious exit code and didn't auto-commit. This contradicts the loop's own stated philosophy
+   (Baustein C2): *"independent verification is the source of truth, not the agent's exit code."*
+
+2. **No flaky-test tolerance (T4).** Under autonomous load, a heavy background task caused an
+   async test to time out — a **false** red, not a real defect. The single-shot verify gate
+   blocked the story. The user had to manually add `retry: 2` to the project's `vitest.config`.
+   That resilience belongs in the harness.
+
+**Goal:** make the loop trust **verify**, not the agent's exit code, and tolerate transient
+flakes — closing two real block causes without weakening the gate.
+
+**Out of scope (deferred):** cross-story regression repair (S5/S6 — a later story breaking an
+earlier story's tests). That needs its own design; this spec does not address it.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Verify authority | The **implementer** runner's `success` flag is advisory; **verify decides**. Run verify regardless of runner exit, block only on verify failure. |
+| Runner-fail + verify-pass | Proceed (commit) — the exit code was a ghost. Note it via the reporter / summary. |
+| Runner-fail + verify-fail | Block, with a reason naming both signals. |
+| Reviewer runner | **Unchanged** — its non-zero exit *is* the reject verdict (there is no separate verify for the review). |
+| Flaky tolerance | `retryingVerifier(inner, retries)` re-runs a failing verify up to `retries` times; first pass wins. |
+| Retry default | `config.verify.retries` default **1** (one retry). `0` = strict/no-retry. A real failure still fails (twice). |
+| Out of scope | Cross-story regression repair; changing the reviewer's exit-code semantics. |
+
+## Architecture
+
+### 1. `src/loop/verify.ts` — `retryingVerifier`
+```ts
+export function retryingVerifier(inner: Verifier, retries: number): Verifier {
+  return (targetDir) => {
+    let last = inner(targetDir)
+    let attempt = 0
+    while (!last.passed && attempt < retries) {
+      attempt++
+      last = inner(targetDir)
+    }
+    if (last.passed && attempt > 0) {
+      return { passed: true, summary: `${last.summary} (passed on retry ${attempt})` }
+    }
+    return attempt > 0 && !last.passed
+      ? { passed: false, summary: `${last.summary} (still failing after ${attempt} retr${attempt === 1 ? 'y' : 'ies'})` }
+      : last
+  }
+}
+```
+Pure, injectable `inner` for tests (no real command needed).
+
+### 2. `src/loop/loop.ts` — verify is the gate
+In **both** the isolate and non-isolate paths, restructure the implementer step so verify always
+runs:
+
+- Run the implementer runner (keep `result` for its summary).
+- `reporter.phase('verifying')`; run `opts.verify(dir)`.
+- If verify **fails**: block. Reason = verify summary, and if the runner *also* reported failure,
+  prepend that (`runner reported failure (<summary>); verify also red: <verify summary>`).
+- If verify **passes**: proceed to review/commit even if `result.success` was false. When the
+  runner had reported failure, the committed decision/summary notes
+  `(runner exited non-zero but verify is green)` so the ghost is auditable.
+
+The reviewer step is untouched: `if (!reviewResult.success) → block` stays (exit = verdict).
+
+The Baustein-E invariant (no `passes:true` without a commit; decision rollback on commit failure)
+and the leftover-hint are preserved exactly — only the implementer-failure gate moves from
+"before verify" to "verify decides".
+
+### 3. `src/retrofit/config.ts` — `verify.retries`
+Extend the `verify` config object: `verify: { command: string; retries?: number }`.
+Backwards-compatible (optional).
+
+### 4. `src/loop/run-command.ts` — wire the retry
+When building the verifier from config, wrap it:
+`verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1)`.
+The injected-verifier test path (`opts.verify`) is unchanged.
+
+### 5. README + loop-spec
+Document: verify is the source of truth (a spurious agent exit code can't block a green story),
+and `verify.retries` (default 1) for flaky suites. Update `canon/loop/loop-spec.md` step 5.
+
+## Testing (subagent-driven TDD)
+- **verify.ts:** `retryingVerifier` passes immediately when inner passes (no retry); passes on
+  retry N when inner fails then passes; fails after exhausting retries; `retries: 0` = single
+  shot; summary notes the retry/exhaustion. Inner is a stub Verifier.
+- **loop.ts:** runner-fail + verify-pass → story is committed + `passes:true` (the SE5 case);
+  runner-fail + verify-fail → blocked with a combined reason; runner-pass + verify-fail →
+  blocked (unchanged); the reviewer still blocks on its own failure; existing invariant tests
+  (commit-failure revert, leftover hint) stay green; applies to both isolate and non-isolate.
+- **config.ts:** `verify.retries` accepted + optional.
+- **run-command.ts:** the built verifier is wrapped with the resolved retry count (assert via a
+  small seam or by config round-trip).
+- Full suite green; `tsc` clean.
+
+## What this would have done for the run
+- **SE5:** runner exits 127 but suite is 769/769 green → verify passes → story auto-commits. No
+  manual finalize.
+- **T4:** the load-flake fails once, the retry passes → story proceeds. No manual `vitest.config`
+  patch, no false block.