@ai-dev-methodologies/rlp-desk 0.0.1 → 0.1.0

package/examples/calculator/.claude/ralph-desk/logs/loop-test/session-config.json

@@ -0,0 +1,25 @@
+{
+  "session_name": "rlp-desk-loop-test-20260318-232859",
+  "slug": "loop-test",
+  "created_at": "2026-03-18T14:28:59Z",
+  "panes": {
+    "leader": "%99",
+    "worker": "%100",
+    "verifier": "%101"
+  },
+  "pid": 65962,
+  "root": "/Users/kyjin/dev/own/ai-dev-methodologies/rlp-desk/examples/calculator",
+  "models": {
+    "worker": "sonnet",
+    "verifier": "opus"
+  },
+  "config": {
+    "max_iter": 20,
+    "poll_interval": 5,
+    "iter_timeout": 600,
+    "heartbeat_stale_threshold": 120,
+    "max_restarts": 3,
+    "idle_nudge_threshold": 30,
+    "max_nudges": 3
+  }
+}

package/examples/calculator/.claude/ralph-desk/logs/loop-test/status.json

@@ -0,0 +1,10 @@
+{
+  "slug": "loop-test",
+  "iteration": 1,
+  "max_iter": 20,
+  "phase": "worker",
+  "worker_model": "sonnet",
+  "verifier_model": "opus",
+  "last_result": "running",
+  "updated_at_utc": "2026-03-18T14:28:59Z"
+}

package/examples/calculator/.claude/ralph-desk/logs/loop-test/worker-heartbeat.json

@@ -0,0 +1 @@
+{"ts":"2026-03-18T14:29:15Z","pid":66349}

package/examples/calculator/.claude/ralph-desk/memos/loop-test-memory.md

@@ -0,0 +1,17 @@
+# loop-test - Campaign Memory
+
+## Stop Status
+continue
+
+## Objective
+Implement a Python calculator module: calc.py (4 functions + type hints + ValueError) + test_calc.py (pytest, 8+ tests, all passed)
+
+## Current State
+Iteration 0 - not started
+
+## Next Iteration Contract
+Start from the beginning: read PRD and implement US-001 (calc.py with 4 functions).
+
+## Patterns Discovered
+## Learnings
+## Evidence Chain

package/examples/calculator/.claude/ralph-desk/prompts/loop-test.worker.prompt.md

@@ -18,7 +18,7 @@ Iteration rules:
 
 MANDATORY: When done, write the following signal file:
 - Path: .claude/ralph-desk/memos/loop-test-iter-signal.json
-- Format: {"iteration": N, "status": "continue|verify|blocked", "timestamp": "ISO"}
+- Format: {"iteration": N, "status": "continue|verify|blocked", "summary": "what was done", "timestamp": "ISO"}
 - Status values:
   - "continue" = current story done but other stories remain
   - "verify" = all stories complete + done-claim written

package/install.sh

@@ -35,19 +35,33 @@ echo "  Downloading init script..."
 curl -sSL "$REPO_URL/src/scripts/init_ralph_desk.zsh" -o "$DESK_DIR/init_ralph_desk.zsh"
 chmod +x "$DESK_DIR/init_ralph_desk.zsh"
 
+# Download tmux runner script
+echo "  Downloading tmux runner script..."
+curl -sSL "$REPO_URL/src/scripts/run_ralph_desk.zsh" -o "$DESK_DIR/run_ralph_desk.zsh"
+chmod +x "$DESK_DIR/run_ralph_desk.zsh"
+
 # Download governance protocol
 echo "  Downloading governance protocol..."
 curl -sSL "$REPO_URL/src/governance.md" -o "$DESK_DIR/governance.md"
 
+# Check tmux availability
+if ! command -v tmux &>/dev/null; then
+  echo ""
+  echo "  [warn] tmux not found. Tmux execution mode (--mode tmux) will not be available."
+  echo "         Install tmux to use lean mode: https://github.com/tmux/tmux/wiki/Installing"
+fi
+
 echo ""
 echo "  Done! Installed to:"
 echo ""
 echo "    Slash command:  $COMMANDS_DIR/rlp-desk.md"
 echo "    Init script:    $DESK_DIR/init_ralph_desk.zsh"
+echo "    Tmux runner:    $DESK_DIR/run_ralph_desk.zsh"
 echo "    Governance:     $DESK_DIR/governance.md"
 echo ""
 echo "  Usage:"
 echo "    1. Open Claude Code in your project directory"
 echo "    2. Run: /rlp-desk brainstorm \"your task description\""
 echo "    3. Run: /rlp-desk run <slug>"
+echo "    4. Run: /rlp-desk run <slug> --mode tmux  (lean mode)"
 echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-dev-methodologies/rlp-desk",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",

package/scripts/postinstall.js

@@ -4,15 +4,17 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const { execSync } = require("child_process");
 
 const home = os.homedir();
 const claudeDir = path.join(home, ".claude");
 const commandsDir = path.join(claudeDir, "commands");
 const deskDir = path.join(claudeDir, "ralph-desk");
 const pkgDir = path.join(__dirname, "..");
+const pkg = require(path.join(pkgDir, "package.json"));
 
 console.log("");
-console.log("  RLP Desk v0.0.1");
+console.log("  RLP Desk v" + pkg.version);
 console.log("  ================");
 console.log("");
 
@@ -27,6 +29,10 @@ const copies = [
     "src/scripts/init_ralph_desk.zsh",
     path.join(deskDir, "init_ralph_desk.zsh"),
   ],
+  [
+    "src/scripts/run_ralph_desk.zsh",
+    path.join(deskDir, "run_ralph_desk.zsh"),
+  ],
   ["src/governance.md", path.join(deskDir, "governance.md")],
 ];
 
@@ -38,10 +44,20 @@ for (const [src, dest] of copies) {
 // Make scripts executable
 try {
   fs.chmodSync(path.join(deskDir, "init_ralph_desk.zsh"), 0o755);
+  fs.chmodSync(path.join(deskDir, "run_ralph_desk.zsh"), 0o755);
 } catch (_) {
   // chmod may fail on Windows — not critical
 }
 
+// Check tmux availability
+try {
+  execSync("which tmux", { stdio: "ignore" });
+} catch (_) {
+  console.log("  [warn] tmux not found. Tmux execution mode (--mode tmux) will not be available.");
+  console.log("         Install tmux to use lean mode: https://github.com/tmux/tmux/wiki/Installing");
+  console.log("");
+}
+
 console.log("");
 console.log("  Done! Open Claude Code and run:");
 console.log("    /rlp-desk brainstorm \"your task description\"");

package/scripts/uninstall.js

@@ -17,6 +17,7 @@ console.log("");
 const files = [
   path.join(commandsDir, "rlp-desk.md"),
   path.join(deskDir, "init_ralph_desk.zsh"),
+  path.join(deskDir, "run_ralph_desk.zsh"),
   path.join(deskDir, "governance.md"),
 ];
 

package/src/commands/rlp-desk.md

@@ -15,20 +15,28 @@ Parse the first word of `$ARGUMENTS` as the subcommand.
 
 ## `brainstorm <description>`
 
-Planning phase BEFORE init. Interactively define the contract with the user.
+Planning phase BEFORE init. Interactively define the contract **with the user**.
 
-Determine all of the following:
-1. **Slug** — short identifier (e.g., `auth-refactor`)
+You MUST ask the user about each item below. Do NOT decide for them.
+Present your suggestion, then wait for the user's confirmation or change.
+
+Ask about these items one by one (or in small groups):
+1. **Slug** — short identifier (e.g., `auth-refactor`). Suggest one, ask if OK.
 2. **Objective** — what the loop achieves
-3. **User Stories** — discrete units with testable acceptance criteria
-4. **Iteration Unit** — one worker does per iteration (default: one user story)
+3. **User Stories** — discrete units with testable acceptance criteria. Propose a breakdown, ask the user to confirm/modify.
+4. **Iteration Unit** — what one worker does per iteration. Explicitly ask:
+   - "One US per iteration (bounded, incremental verification)?"
+   - "All stories at once (faster, single verification)?"
+   - Default recommendation: one US per iteration for 3+ stories.
 5. **Verification Commands** — build, test, lint commands
 6. **Completion / Blocked Criteria**
-7. **Worker / Verifier Model** — haiku, sonnet, opus
-8. **Max Iterations**
+7. **Worker / Verifier Model** — haiku, sonnet, opus. Suggest defaults (worker: sonnet, verifier: opus), ask if OK.
+8. **Max Iterations** — suggest based on story count, ask if OK.
 
-Present the contract summary. On approval, offer to run `init`.
+After all items are confirmed, present the full contract summary.
+On approval, offer to run `init`.
 Do NOT create files during brainstorm.
+Do NOT auto-decide iteration unit — the user MUST explicitly choose.
 
 ---
 
@@ -44,9 +52,40 @@ If brainstorm was done, auto-fill PRD and test-spec with the results.
 **YOU are the leader. Do NOT delegate leadership.**
 
 Options (parse from `$ARGUMENTS`):
+- `--mode agent|tmux` (default: `agent`) — execution mode
 - `--max-iter N` (default: 100)
 - `--worker-model MODEL` (default: sonnet)
-- `--verifier-model MODEL` (default: sonnet)
+- `--verifier-model MODEL` (default: opus)
+- `--debug` — enable debug logging (tmux mode only, writes to logs/<slug>/debug.log)
+
+### Mode Selection
+
+Parse the `--mode` flag. If absent or `agent`, use the Agent() path below. If `tmux`, use the Tmux path.
+
+#### Tmux Mode (`--mode tmux`)
+
+When `--mode tmux` is specified:
+
+1. **Validate scaffold** — same as Agent() mode: check `.claude/ralph-desk/prompts/<slug>.worker.prompt.md` etc.
+2. **Check sentinels** — same as Agent() mode.
+3. **Check prerequisites** — verify `tmux` and `jq` are installed. If not, report what is missing and stop.
+4. **Locate runner script** — find `run_ralph_desk.zsh` at `~/.claude/ralph-desk/run_ralph_desk.zsh`. If not found, tell the user to reinstall (`npm install` or `install.sh`).
+5. **Launch** — shell out to the runner script with env vars derived from flags:
+```bash
+LOOP_NAME="<slug>" \
+ROOT="$PWD" \
+MAX_ITER=<--max-iter value> \
+WORKER_MODEL=<--worker-model value> \
+VERIFIER_MODEL=<--verifier-model value> \
+DEBUG=<1 if --debug, else 0> \
+  zsh ~/.claude/ralph-desk/run_ralph_desk.zsh
+```
+6. **If the script exits with error (exit code 1)** — report the error to the user and STOP. Do NOT attempt to work around it. Do NOT create tmux sessions yourself. Do NOT re-launch the script in a different way. Just tell the user what went wrong and suggest using Agent mode instead.
+7. **If successful** — tell the user the tmux session has been started. The shell script takes over as the deterministic Leader. No Agent() calls are made in tmux mode.
+
+**IMPORTANT:** Tmux mode requires the user to already be inside a tmux session. If the runner script rejects because $TMUX is not set, do NOT try to create a tmux session yourself. Tell the user: "Start tmux first, then retry."
+
+#### Agent Mode (`--mode agent` or default)
 
 ### Preparation
 1. Validate scaffold: `.claude/ralph-desk/prompts/<slug>.worker.prompt.md` etc.
@@ -55,6 +94,8 @@ Options (parse from `$ARGUMENTS`):
 
 ### Leader Loop
 
+**CRITICAL: DO NOT STOP between iterations.** You MUST continue the loop automatically until a sentinel is written (COMPLETE or BLOCKED) or max_iter is reached. Do NOT pause to ask the user. Do NOT wait for confirmation. The loop is fully autonomous — just report each iteration result briefly and immediately proceed to the next iteration.
+
 For each iteration (1 to max_iter):
 
 **① Check sentinels**
@@ -63,7 +104,15 @@ test -f .claude/ralph-desk/memos/<slug>-complete.md  # → done
 test -f .claude/ralph-desk/memos/<slug>-blocked.md   # → stop
 ```
 
+**①½ Prep-stage cleanup**
+```bash
+rm -f .claude/ralph-desk/memos/<slug>-done-claim.json
+rm -f .claude/ralph-desk/memos/<slug>-verify-verdict.json
+```
+
 **② Read memory.md** → Stop Status, Next Iteration Contract
+- Also read **Completed Stories** → verified work so far
+- Also read **Key Decisions** → settled architectural choices
 
 **③ Decide model** (§4 of governance.md)
 - Previous iteration failed → upgrade model
@@ -106,19 +155,31 @@ Agent(
 ```
 - Read `verify-verdict.json`:
   - `pass` + `complete` → write COMPLETE sentinel, report done!
-  - `fail` + `continue` → go to ⑧
+  - `fail` + `continue` → **run Fix Loop** (governance.md §7½):
+    1. Read `issues` array, sort by severity (`critical` → `major` → `minor`)
+    2. Build structured fix contract with traceability rule
+    3. Include `fix_hint` values labeled `(suggestion, non-authoritative)` if present
+    4. Increment `consecutive_failures` in `status.json`
+    5. Go to ⑧ with fix contract as next Worker contract
+  - `request_info` → Leader reads Verifier's questions, decides outcome (or relays to Worker in next contract) → go to ⑧
   - `blocked` → write BLOCKED sentinel, stop
 
-**⑧ Report iteration result to user, continue loop**
+**⑧ Write result log and report to user, continue loop**
+- Write `logs/<slug>/iter-NNN.result.md`:
+  - Result status `[leader-measured]`
+  - Files changed via `git diff --stat HEAD~1 HEAD` `[git-measured]`
+  - Verifier verdict `[leader-measured]`
 - Write `status.json`
 - Report: iteration N, phase, model used, result
-- Clean `done-claim.json`, `verify-verdict.json` for next iteration
 
 ### Circuit Breaker
 - context-latest.md unchanged 3 iterations → BLOCKED
-- Same error 2x → upgrade model, retry once, then BLOCKED
+- Same acceptance criterion fails 2 consecutive iterations → upgrade model, retry once, then BLOCKED
+- 3 consecutive **fail** verdicts on 3 unique criterion IDs → upgrade to opus, retry once, then BLOCKED
 - max_iter reached → TIMEOUT, report to user
 
+Track `consecutive_failures` in `status.json` (increment on `fail`, reset on `pass`, unchanged by `request_info`). Only **fail** verdicts count for CB chains — `request_info` does not break or contribute.
+
 ### Important Rules
 - Each Agent() = new process = fresh context
 - YOU track iteration count
@@ -134,27 +195,38 @@ Read `.claude/ralph-desk/logs/<slug>/status.json` and display.
 - No N: show latest `iter-*.worker-prompt.md` summary
 - With N: read `iter-N.worker-prompt.md` and `iter-N.verifier-prompt.md`
 
-## `clean <slug>`
+## `clean <slug> [--kill-session]`
 Remove:
 - `.claude/ralph-desk/memos/<slug>-complete.md`
 - `.claude/ralph-desk/memos/<slug>-blocked.md`
 - `.claude/ralph-desk/memos/<slug>-done-claim.json`
 - `.claude/ralph-desk/memos/<slug>-verify-verdict.json`
+- `.claude/ralph-desk/memos/<slug>-iter-signal.json`
 - `.claude/ralph-desk/logs/<slug>/circuit-breaker.json`
+- `.claude/ralph-desk/logs/<slug>/session-config.json`
+- `.claude/ralph-desk/logs/<slug>/worker-heartbeat.json`
+- `.claude/ralph-desk/logs/<slug>/verifier-heartbeat.json`
+
+If `--kill-session` is passed, also kill any tmux session matching `rlp-desk-<slug>-*`:
+```bash
+tmux list-sessions -F '#{session_name}' 2>/dev/null | grep "^rlp-desk-<slug>-" | while read s; do tmux kill-session -t "$s"; done
+```
 
 ## No args or `help`
 ```
-/rlp-desk brainstorm <description>     Plan before init (interactive)
-/rlp-desk init  <slug> [objective]     Create project scaffold
-/rlp-desk run   <slug> [--opts]        Run loop (this session = leader)
-/rlp-desk status <slug>                Show loop status
-/rlp-desk logs  <slug> [N]             Show iteration log
-/rlp-desk clean <slug>                 Reset for re-run
+/rlp-desk brainstorm <description>          Plan before init (interactive)
+/rlp-desk init  <slug> [objective]          Create project scaffold
+/rlp-desk run   <slug> [--mode agent|tmux]  Run loop (agent=LLM leader, tmux=shell leader)
+/rlp-desk status <slug>                     Show loop status
+/rlp-desk logs  <slug> [N]                  Show iteration log
+/rlp-desk clean <slug> [--kill-session]     Reset for re-run (--kill-session kills tmux)
 ```
 
 ## Architecture
+
+### Agent Mode (default: `--mode agent`)
 ```
-[This session = LEADER]
+[This session = LEADER (LLM)]
         │
   Agent()├──▶ [Worker: executor (fresh context)]
         │     └── reads desk files, implements, updates memory
@@ -162,3 +234,22 @@ Remove:
   Agent()└──▶ [Verifier: executor (fresh context)]
               └── reads done-claim, runs checks, writes verdict
 ```
+
+### Tmux Mode (`--mode tmux`)
+```
+[tmux session: rlp-desk-<slug>-<timestamp>]
++-------------------------------------+
+| Leader pane (shell loop)            |
+| - writes prompts to files           |
+| - sends short triggers via send-keys|
+| - polls iter-signal.json            |
+| - monitors heartbeat files          |
+| - writes sentinels                  |
++------------------+------------------+
+| Worker pane      | Verifier pane    |
+| bash trigger.sh  | bash trigger.sh  |
+| -> claude -p ... | -> claude -p ... |
+| heartbeat writer | heartbeat writer |
+| (fresh context)  | (fresh context)  |
++------------------+------------------+
+```

package/src/governance.md

@@ -29,9 +29,13 @@ The Leader orchestrates, while Worker/Verifier run in isolated fresh contexts ev
 
 ### Verifier (fresh context)
 - Independently verifies Worker's done claim
+- Identifies scope via `git diff --name-only` — reads changed files and related imports only
 - Runs commands directly to collect fresh evidence
-- Writes verdict (pass/fail/blocked)
-- **Must NEVER modify code**
+- Campaign Memory is for orientation only — not the source of truth
+- Writes verdict (`pass` | `fail` | `request_info`) — if uncertain, use `request_info` with specific questions; Leader decides
+- Delegates deterministic checks (type hints, linting, security) to tools defined in test-spec
+- Focuses on AC verification, semantic review, and smoke tests
+- **Must NEVER modify code or write sentinel files**
 
 ## 3. State Flow
 
@@ -46,15 +50,15 @@ RUNNING → DONE_CLAIMED → VERIFYING → COMPLETE | CONTINUE | BLOCKED
 | Worker (simple) | haiku | Single file, clear change |
 | Worker (standard) | sonnet | Most tasks (default) |
 | Worker (complex) | opus | Architecture changes, multi-file, prior iteration failure |
-| Verifier | sonnet | Sufficient for most cases |
-| Verifier (strict) | opus | Security/critical logic verification |
+| Verifier | opus | Independent verification requires thoroughness |
+| Verifier (lightweight) | sonnet | Simple, well-defined checks only |
 
 The Leader decides each iteration. Decision criteria:
 - Previous iteration failed → upgrade model
 - Simple repetitive task → downgrade model
 - User explicitly specified → use as given
 
-## 5. Execution: Unified Agent() Approach
+## 5a. Execution: Agent() Approach (default) — "Smart Mode"
 
 All environments (Claude Code, OpenCode) use the same Agent tool.
 
@@ -83,6 +87,46 @@ Characteristics:
 - No tmux required.
 - Monitor in real-time via ctrl+o (Claude Code UI).
 - Prompts are still logged to logs/ for audit trail.
+- Leader is an LLM — can dynamically route models, reason about context, and adapt.
+
+## 5b. Execution: Tmux Runner (alternative) — "Lean Mode"
+
+For long campaigns, observability, headless/CI execution, or when zero-token orchestration is preferred.
+
+```bash
+# Launched via slash command:
+/rlp-desk run <slug> --mode tmux
+
+# Or directly:
+LOOP_NAME=<slug> ROOT=$(pwd) ~/.claude/ralph-desk/run_ralph_desk.zsh
+```
+
+The tmux runner (`run_ralph_desk.zsh`) creates a tmux session with three panes:
+- **Leader pane** — deterministic shell loop (no LLM)
+- **Worker pane** — receives `claude -p` invocations via trigger scripts
+- **Verifier pane** — receives `claude -p` invocations via trigger scripts
+
+All `claude` CLI calls use `--dangerously-skip-permissions`:
+```bash
+claude -p "$(cat /path/to/prompt.md)" \
+  --model sonnet \
+  --dangerously-skip-permissions
+```
+
+**Security implication:** `--dangerously-skip-permissions` allows the CLI to execute code without user confirmation. The tmux runner requires this because there is no interactive user to approve each action. Only run tmux mode in trusted environments with trusted prompts.
+
+Characteristics:
+- Leader is a shell script, not an LLM — zero tokens consumed for orchestration.
+- Leader reads ONLY `iter-signal.json` and `verify-verdict.json` for control flow (structured JSON via `jq`). No markdown parsing.
+- Model routing is static via environment variables (`WORKER_MODEL`, `VERIFIER_MODEL`). This is an explicit trade-off vs Agent() mode's dynamic routing.
+- **Write-then-notify:** All prompts and payloads are written to files first. Only short trigger commands (`bash /path/to/trigger.sh`) are sent via `tmux send-keys`.
+- **Pane IDs (`%N` format):** Captured at pane creation, stored in `session-config.json`. Never uses positional indices.
+- **Copy-mode guard:** Checks `#{pane_in_mode}` before every `send-keys` to avoid sending into scrollback.
+- **Heartbeat monitoring:** Trigger scripts write heartbeat files; Leader checks freshness.
+- **Atomic file writes:** All file writes use `{path}.tmp.{pid}` + `mv` for crash safety.
+- Can run detached (`tmux detach`) for overnight/CI campaigns.
+- User can watch Worker/Verifier execution in real-time via tmux panes.
+- Traceability: governance section 7 step numbers appear as comments throughout the shell script.
 
 ## 6. File Structure
 
@@ -105,6 +149,7 @@ Characteristics:
 ├── memos/
 │   ├── <slug>-memory.md             # Campaign memory (Worker updates)
 │   ├── <slug>-done-claim.json       # Worker's completion claim (runtime)
+│   ├── <slug>-iter-signal.json      # Worker's iteration signal (runtime)
 │   ├── <slug>-verify-verdict.json   # Verifier's verdict (runtime)
 │   ├── <slug>-complete.md           # SENTINEL (Leader only)
 │   └── <slug>-blocked.md            # SENTINEL (Leader only)
@@ -114,6 +159,7 @@ Characteristics:
 └── logs/<slug>/
     ├── iter-NNN.worker-prompt.md    # Audit trail prompt copy
     ├── iter-NNN.verifier-prompt.md  # Audit trail prompt copy
+    ├── iter-NNN.result.md           # Iteration result (leader-measured + git-measured)
     └── status.json                  # Leader's loop state
 ```
 
@@ -126,7 +172,13 @@ for iteration in 1..max_iter:
      - complete.md exists → stop
      - blocked.md exists → stop
 
+  ①½ Prep-stage cleanup
+     - Delete done-claim.json if exists
+     - Delete verify-verdict.json if exists
+
   ② Read memory.md → check Stop Status, Next Iteration Contract
+     - Also parse Completed Stories (verified work so far)
+     - Also parse Key Decisions (settled architectural choices)
 
   ③ Select model
      - Default or situational decision (see §4)
@@ -143,6 +195,9 @@ for iteration in 1..max_iter:
      - "continue" → go to ⑧
      - "verify"   → go to ⑦
      - "blocked"  → write BLOCKED sentinel, stop
+     Note: In tmux mode, the Leader polls `<slug>-iter-signal.json` instead of
+     parsing memory.md. In Agent() mode, the Leader MAY read iter-signal.json
+     as a structured alternative to parsing the Stop Status from memory.md.
 
   ⑦ Execute Verifier
      - Build prompt → log to logs/<slug>/iter-NNN.verifier-prompt.md
@@ -152,7 +207,31 @@ for iteration in 1..max_iter:
        • fail + continue → go to ⑧
        • blocked → write BLOCKED sentinel, stop
 
-  ⑧ Update status.json, report to user, continue to next iteration
+  ⑧ Write iter-NNN.result.md to logs/<slug>/ (result status + git diff --stat)
+     Update status.json, report to user, continue to next iteration
+```
+
+## 7½. Fix Loop Protocol
+
+When the Verifier returns `fail`, the Leader runs the Fix Loop before issuing the next Worker contract:
+
+1. **Read issues** from `verify-verdict.json` — sort by severity (`critical` → `major` → `minor`)
+2. **Build fix contract** — include each issue as a numbered task with criterion reference
+   - `fix_hint` (if present) is passed as `(suggestion, non-authoritative)` — Worker may ignore
+3. **Traceability rule**: "Only changes that resolve a listed issue are allowed — every change must be justified by the issue it addresses"
+4. **Update status.json** — increment `consecutive_failures`; reset to 0 on any `pass`
+
+The `consecutive_failures` counter is maintained by the Leader in `status.json`.
+
+**Fix contract format:**
+```
+Fix issues from Verifier verdict (iter-NNN):
+
+1. [critical] US-002 AC3: <description> — fix_hint: (suggestion, non-authoritative) <hint>
+2. [major] US-001 AC1: <description>
+
+Traceability: only changes that resolve a listed issue are allowed.
+Every change must be justified by the issue it addresses.
 ```
 
 ## 8. Circuit Breaker
@@ -160,9 +239,15 @@ for iteration in 1..max_iter:
 | Condition | Verdict |
 |-----------|---------|
 | context-latest.md unchanged for 3 consecutive iterations | BLOCKED |
-| Worker repeats the same error twice | Upgrade model, retry once; if still failing → BLOCKED |
+| Same acceptance criterion fails 2 consecutive iterations | Upgrade model, retry once; if still failing → BLOCKED |
+| 3 consecutive **fail** verdicts on 3 unique criterion IDs | Upgrade to opus, retry once; if still failing → BLOCKED |
 | max_iter reached | TIMEOUT (report to user) |
 
+The Leader tracks `consecutive_failures` in `status.json`:
+- Increments on `fail`, resets on `pass`, **unchanged by `request_info`**.
+- "Same error" = same acceptance criterion ID in two consecutive **fail** verdicts (`request_info` does not break or contribute to this chain).
+- "Diverse failures" = 3 most recent `fail` verdicts each have a unique criterion ID.
+
 ## 9. Change Policy
 
 - Changes to the shared workflow → modify this document