@ai-dev-methodologies/rlp-desk 0.4.0 → 0.5.1

package/src/commands/rlp-desk.md

@@ -41,13 +41,44 @@ Ask about these items one by one (or in small groups):
    - 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. Suggest defaults (worker: sonnet, verifier: opus), ask if OK.
+7. **Worker / Verifier Model** — Evaluate PRD complexity using 5 factors (overall = highest factor), then recommend model.
+
+   **Complexity Evaluation Table**:
+
+   | Factor | LOW | MEDIUM | HIGH | CRITICAL |
+   |--------|-----|--------|------|----------|
+   | US count | 1-2 | 3-5 | 6-10 | 10+ |
+   | File change scope | single | 2-5 files | 6+ files | cross-repo |
+   | Logic complexity | simple | conditionals | algorithms | security |
+   | External dependencies | none | 1-2 | 3+ | distributed |
+   | Existing code impact | new only | modify | refactor | architecture |
+
+   **Model mapping** (Worker / Verifier):
+   - LOW → haiku / sonnet
+   - MEDIUM → sonnet / opus
+   - HIGH → opus / opus
+   - CRITICAL → opus / opus + require human review
+
+   Present complexity score with evidence to the user, e.g.: "I rate this MEDIUM because: US count=4 (MEDIUM), file scope=2 (MEDIUM), logic=conditionals (MEDIUM), deps=none (LOW), impact=modify (MEDIUM). Highest=MEDIUM → I suggest Worker: sonnet, Verifier: opus."
+
 8. **Engine & Model** — For each role (Worker, Verifier):
    - Engine: claude (default) or codex
    - If claude: suggest model (haiku/sonnet/opus) based on task complexity
    - If codex: suggest model (default: gpt-5.4) and reasoning effort (low/medium/high)
-   - AI should recommend: "For this task complexity, I suggest Worker: sonnet, Verifier: opus"
-   - If codex selected: "For codex Worker, I suggest gpt-5.4 with high reasoning"
+
+   **Codex Detection** — check if codex CLI is installed (`command -v codex`):
+
+   **If codex IS installed** — recommend cross-engine Worker:
+   - Suggest: `--worker-model gpt-5.4:high --verify-consensus` (cross-engine + consensus)
+   - Alternative: `--worker-model gpt-5.3-codex-spark:high` (spark preset — note: 100k output token limit per request, best for smaller scope PRDs)
+   - Say: "Codex is installed. I recommend it as Worker for cost savings (codex tokens are cheaper than claude tokens for bulk iteration) and cross-engine blind-spot coverage (claude Verifier catches issues codex Worker misses)."
+
+   **If codex is NOT installed** — recommend claude-only + install suggestion:
+   - Defaulting to claude-only Worker (sonnet).
+   - Say: "Codex is not installed. Defaulting to claude-only Worker. Note: without a second engine, your Verifier shares the same perspective as the Worker — there is a risk of blind spots where both Worker and Verifier miss the same issue. To unlock cross-engine coverage: `npm install -g @openai/codex`"
+
+   AI should recommend: "For this task complexity, I suggest Worker: sonnet, Verifier: opus"
+   If codex selected: "For codex Worker, I suggest gpt-5.4 with high reasoning"
 9. **Verify Mode** — per-us (default) or batch. Ask: "Verify after each user story (per-us, recommended) or only after all stories are done (batch)?" Default recommendation: per-us for 2+ stories.
 10. **Verify Consensus** — Ask: "Use cross-engine consensus verification? (Both claude and codex verify independently, both must pass.) Requires codex CLI." Default: no.
 11. **Consensus Scope** — If consensus enabled, ask: "Consensus on every verify (all, default) or only on final verify (final-only)?" Default: all.
@@ -83,33 +114,63 @@ If brainstorm was done, auto-fill PRD and test-spec with the results.
 Tell the user:
 1. The scaffold has been created — list the generated files
 2. Ask them to review/edit the PRD and test-spec if needed
-3. Present run options with explanations and ONE recommendation. The user MUST copy and paste the command themselves:
+3. Present run options with explanations and ONE recommendation. The user MUST copy and paste the command themselves.
 
-```
-Available run commands (copy the one you want):
+   Check if codex CLI is installed: run `command -v codex` in shell or check if the binary exists.
 
-# Recommended for most cases — agent mode, per-US verification, debug logging:
-/rlp-desk run <slug> --debug
+   **If codex IS installed** — show cross-engine presets first:
 
-# With self-verification campaign report (recommended for MEDIUM+ risk):
-/rlp-desk run <slug> --debug --with-self-verification
+   ```
+   Available run commands (copy the one you want):
 
-# Tmux mode for long campaigns with real-time visibility:
-/rlp-desk run <slug> --mode tmux --debug
+   # Recommended: cross-engine + final-consensus (cost savings + blind-spot coverage):
+   /rlp-desk run <actual-slug> --worker-model gpt-5.4:high --final-consensus --debug
 
-# Cross-engine consensus (requires codex CLI installed):
-/rlp-desk run <slug> --debug --verify-consensus
+   # Spark Pro preset (fast codex worker, lower cost):
+   /rlp-desk run <actual-slug> --worker-model gpt-5.3-codex-spark:high --debug
 
-# Full options reference:
-#   --mode agent|tmux          Agent mode (default) or tmux shell leader
-#   --debug                    Always-on detailed logging (recommended)
-#   --with-self-verification   Post-campaign analysis report
-#   --verify-mode per-us|batch Per-US (default) or batch verification
-#   --verify-consensus         Both claude+codex must pass
-#   --worker-model MODEL       haiku/sonnet/opus (default: sonnet)
-#   --verifier-model MODEL     haiku/sonnet/opus (default: opus)
-#   --max-iter N               Max iterations (default: 100)
-```
+   # Claude-only:
+   /rlp-desk run <actual-slug> --debug
+
+   # Basic agent:
+   /rlp-desk run <actual-slug>
+
+   # Full options reference:
+   #   --mode agent|tmux                (default: agent)
+   #   --worker-model MODEL             haiku|sonnet|opus or gpt-5.4:low|medium|high (default: sonnet)
+   #   --verifier-model MODEL           haiku|sonnet|opus (default: opus)
+   #   --verify-consensus               both claude+codex must pass
+   #   --verify-mode per-us|batch       (default: per-us)
+   #   --max-iter N                     (default: 100)
+   #   --debug                          enable debug logging
+   #   --with-self-verification         post-campaign analysis report
+   ```
+
+   **If codex is NOT installed** — show claude-only presets + install recommendation:
+
+   ```
+   Available run commands (copy the one you want):
+
+   # Recommended: tmux mode + claude-only (real-time visibility):
+   /rlp-desk run <actual-slug> --mode tmux --debug
+
+   # Agent mode:
+   /rlp-desk run <actual-slug> --debug
+
+   # Install codex for cost savings + cross-engine blind-spot coverage:
+   npm install -g @openai/codex
+
+   # Full options reference:
+   #   --mode agent|tmux                (default: agent)
+   #   --worker-model MODEL             haiku|sonnet|opus (default: sonnet)
+   #   --verifier-model MODEL           haiku|sonnet|opus (default: opus)
+   #   --verify-mode per-us|batch       (default: per-us)
+   #   --max-iter N                     (default: 100)
+   #   --debug                          enable debug logging
+   #   --with-self-verification         post-campaign analysis report
+   ```
+
+   Replace `<actual-slug>` with the real slug from this init (e.g. `auth-refactor`).
 
 **CRITICAL: Do NOT offer to run for the user. Do NOT ask "shall I run?" or offer to execute. The user MUST type the run command themselves. Just present the options, recommend one, and STOP.**
 
@@ -138,10 +199,21 @@ Options (parse from `$ARGUMENTS`):
   - `all`: consensus runs on every verify (current behavior)
   - `final-only`: consensus only on final ALL verify
 - `--cb-threshold N` — circuit breaker threshold: consecutive failures before BLOCKED (default: 3). When `--verify-consensus` is active, effective threshold is automatically doubled (e.g., default becomes 6).
+- `--consensus-fail-fast` — skip second verifier if first verifier fails (saves time/tokens in consensus mode)
 - `--iter-timeout N` — per-iteration timeout in seconds (default: 600). Enforced in tmux mode only. Agent mode: not enforced (Agent() has no timeout API).
-- `--debug` — enable debug logging (writes to logs/<slug>/debug.log)
+- `--debug` — enable debug logging (writes to ~/.claude/ralph-desk/analytics/<slug>/debug.log)
 - `--with-self-verification` — enable campaign-level self-verification analysis. After COMPLETE, Leader analyzes all iteration records (done-claims + verdicts) and generates a campaign self-verification summary with patterns and recommendations for next planning cycle. (Note: execution_steps and reasoning are ALWAYS recorded per governance §1f — this flag adds post-campaign analysis.)
 
+### Analytics Directory (`~/.claude/ralph-desk/analytics/<slug>/`)
+When `--debug` or `--with-self-verification` is active, analytics data is written to a user-level directory for cross-project aggregation. Contents:
+- `metadata.json` — campaign metadata: slug, project_root, campaign_status, start_time, end_time
+- `debug.log` — debug output (versioned: `debug-v{N}.log` on re-execution)
+- `campaign.jsonl` — per-iteration structured data (versioned: `campaign-v{N}.jsonl` on re-execution). Schema: iter, us_id, worker_model, worker_engine, verifier_engine, claude_verdict, codex_verdict, consensus, duration_worker_s, duration_verifier_s, project_root, slug, timestamp
+- `self-verification-data.json` — cumulative SV records (agent-mode only, when `--with-self-verification`)
+- `self-verification-report-NNN.md` — versioned SV reports (when `--with-self-verification`)
+
+Cross-project aggregation: scan `~/.claude/ralph-desk/analytics/` and read each slug's `metadata.json` to discover project_root, campaign_status, and timestamps. Slug directories use `<slug>--<root_hash>` format to prevent collision across projects.
+
 ### Mode Selection
 
 Parse the `--mode` flag. If absent or `agent`, use the Agent() path below. If `tmux`, use the Tmux path.
@@ -181,22 +253,31 @@ WITH_SELF_VERIFICATION=<1 if --with-self-verification, else 0> \
 
 **IMPORTANT RULES:**
 - 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."
-- Do NOT run the script in background (`&`, `run_in_background`). The script must run in foreground so panes remain visible to the user. The user needs to see Worker/Verifier panes in real-time.
+- MUST launch the runner with `run_in_background: true` so `/rlp-desk` returns control immediately while preserving live tmux visibility.
+- Run-in-background is used so the shell can keep the command visible and keep the pane layout stable for status checks and completion flow.
 - Do NOT kill panes after completion. Panes stay alive for inspection. User cleans up with `/rlp-desk clean <slug> --kill-session`.
-- `--with-self-verification` is accepted in tmux mode but SV report generation is Agent-mode only (requires AI analysis). In tmux mode, the flag is recorded in session-config for post-hoc analysis. Use Agent mode for full SV report generation.
+- `--with-self-verification` is accepted in tmux mode. After campaign completion, `run_ralph_desk.zsh` spawns `claude CLI` to generate the SV report from campaign artifacts (done-claims, verify-verdicts, campaign-report). SV reports are written to `~/.claude/ralph-desk/analytics/<slug>/`. Requires `claude` CLI available in PATH; if not found, an error is appended to the campaign report.
+
+**tmux UX model (5 items):**
+- The session returns immediately after launch (`run_in_background: true`) so the command returns control to the parent CLI.
+- Worker/Verifier panes remain visible to the user during execution.
+- Users check progress with the **status command**: `/rlp-desk status <slug>`.
+- On completion, the command returns a completion notification before the loop ends.
+- Agent mode remains unchanged, and no tmux-specific behavior is mixed into Agent mode.
 
 #### Agent Mode (`--mode agent` or default)
 
 ### Preparation
 1. Validate scaffold: `.claude/ralph-desk/prompts/<slug>.worker.prompt.md` etc.
-2. Check sentinels (complete/blocked). Found → tell user `/rlp-desk clean <slug>`.
-3. Clean previous `done-claim.json`, `verify-verdict.json`.
-4. **Always**: write baseline log entry to `.claude/ralph-desk/logs/<slug>/baseline.log`: `[timestamp] iter=0 phase=start slug=<slug> worker_model=<model> verifier_model=<model>`. Baseline.log captures 1 line per iteration for lightweight post-mortem (always-on, no flag needed).
-5. If `--debug`: also create/clear `logs/<slug>/debug.log`. Define a helper: to "debug_log" means append a timestamped line to this file via `Bash("echo \"[$(date '+%Y-%m-%d %H:%M:%S')] $msg\" >> .claude/ralph-desk/logs/<slug>/debug.log")`. When `--debug` is active, debug.log contains all baseline.log fields plus detailed phase logs.
+2. **Codex CLI pre-validation**: If `--verify-consensus` is enabled OR `--worker-engine codex` / `--verifier-engine codex` is set, check that `codex` CLI exists in PATH. If codex CLI not found → STOP immediately, print install instructions (`npm install -g @openai/codex`), do not start the loop.
+3. Check sentinels (complete/blocked). Found → tell user `/rlp-desk clean <slug>`.
+4. Clean previous `done-claim.json`, `verify-verdict.json`.
+5. **Always**: write baseline log entry to `.claude/ralph-desk/logs/<slug>/baseline.log`: `[timestamp] iter=0 phase=start slug=<slug> worker_model=<model> verifier_model=<model>`. Baseline.log captures 1 line per iteration for lightweight post-mortem (always-on, no flag needed).
+6. If `--debug`: also create/clear `~/.claude/ralph-desk/analytics/<slug>/debug.log`. Define a helper: to "debug_log" means append a timestamped line to this file via `Bash("echo \"[$(date '+%Y-%m-%d %H:%M:%S')] $msg\" >> ~/.claude/ralph-desk/analytics/<slug>/debug.log")`. When `--debug` is active, debug.log contains all baseline.log fields plus detailed phase logs.
    - **4-category log system**: all debug_log entries use exactly one of: `[GOV]` (governance checks: IL enforcement, CB triggers, scope lock, verdict evaluation), `[DECIDE]` (leader decisions: model selection, fix contracts, escalation), `[OPTION]` (configuration snapshot at loop start: thresholds, modes, models), `[FLOW]` (execution progress: worker/verifier dispatch, signal reads, phase transitions)
    - **Re-execution versioning**: If `debug.log` already exists at `--debug` start, rename it to `debug-v{N}.log` (N = next available integer ≥ 1) before creating a fresh `debug.log`.
    - **baseline.log lifecycle**: baseline.log is deleted on re-execution (when `init --mode improve` or `init --mode fresh` is run).
-6. Capture baseline commit: `Bash("git rev-parse HEAD 2>/dev/null || echo none")` → store as `BASELINE_COMMIT`. Include in the first `status.json` write as `baseline_commit` field.
+7. Capture baseline commit: `Bash("git rev-parse HEAD 2>/dev/null || echo none")` → store as `BASELINE_COMMIT`. Include in the first `status.json` write as `baseline_commit` field.
 
 ### Leader Loop
 
@@ -241,6 +322,11 @@ rm -f .claude/ralph-desk/memos/<slug>-verify-verdict.json
 **④ Build worker prompt (Prompt Assembly Protocol)**
 1. Capture `WORKING_DIR` once: use `$PWD` from when `/rlp-desk run` was invoked. Store for all prompt construction.
 2. Read `.claude/ralph-desk/prompts/<slug>.worker.prompt.md` — use its content **verbatim**. Do NOT rewrite, paraphrase, or regenerate paths. The prompt file contains correct absolute paths from init.
+2a. **Per-US PRD injection** (when targeting a specific `us_id`, not "ALL"):
+   - Check if `.claude/ralph-desk/plans/prd-<slug>-{us_id}.md` exists (created by init split)
+   - If yes: in the assembled prompt text, replace the full PRD reference (`prd-<slug>.md`) with the per-US file path (`prd-<slug>-{us_id}.md`) — so Worker reads only the relevant US section
+   - If no per-US file: fall back to full PRD (`prd-<slug>.md`) with no change needed
+   - Note: this absolute-path substitution is permitted — only absolute→relative rewrites are forbidden.
 3. Prepend meta comment: `## WORKING_DIR: {absolute path}` — Worker must use this as its working directory.
 4. Append iteration number + memory contract.
 5. Write to `.claude/ralph-desk/logs/<slug>/iter-NNN.worker-prompt.md` (audit trail).
@@ -298,7 +384,8 @@ Bash("codex exec --model <worker_codex_model> --reasoning-effort <worker_codex_r
   - Add that US to `verified_us` in status.json
   - If more US remain → Worker does next US → verify → ...
   - If all US individually passed → signal final full verify (us_id=ALL)
-  - After final full verify passes → COMPLETE
+  - **Sequential final verify** (timeout prevention): Instead of one big ALL verify, loop through each US individually with scoped verifier. After all per-US pass, run the project's test suite as a cross-US integration check. Only COMPLETE if both per-US checks and integration check pass.
+  - After sequential final verify passes → COMPLETE
 
 **Batch mode** (`--verify-mode batch`):
 - Legacy behavior: verify only when Worker signals all work is done
@@ -374,6 +461,7 @@ After reading the verdict, archive to `logs/<slug>/`:
 - Write `status.json`
 - Report via tool call: `Bash("echo 'Iter N | US-NNN | verdict | model | next_action'")` — NEVER plain text. This keeps the turn alive for the next iteration.
 - **Always**: append to baseline.log: `[timestamp] iter=N verdict=<pass|fail|continue> us=<us_id> model=<worker_model>`
+- **Always**: append JSONL to `~/.claude/ralph-desk/analytics/<slug>/campaign.jsonl`: `{"iter":N,"us_id":"US-NNN","verdict":"pass|fail","worker_model":"...","worker_engine":"...","verifier_model":"...","verifier_engine":"...","duration_worker_s":N,"duration_verifier_s":N,"timestamp":"ISO8601"}`
 - If `--debug`: debug_log `[FLOW] iter=N phase=result status=<result> consecutive_failures=<N> verified_us=<list>`
 
 At loop end (COMPLETE, BLOCKED, or TIMEOUT):
@@ -384,8 +472,8 @@ At loop end (COMPLETE, BLOCKED, or TIMEOUT):
 After the loop ends, the Leader performs post-campaign analysis:
 
 1. **Collect data**: Read all archived `iter-NNN.result.md`, done-claim.json (with execution_steps), and verify-verdict.json (with reasoning) from `logs/<slug>/`
-2. **Write cumulative data**: `logs/<slug>/self-verification-data.json` — normalized iteration records
-3. **Generate versioned report**: `logs/<slug>/self-verification-report-NNN.md` (NNN = auto-increment from existing reports)
+2. **Write cumulative data**: `~/.claude/ralph-desk/analytics/<slug>/self-verification-data.json` — normalized iteration records (agent-mode only artifact)
+3. **Generate versioned report**: `~/.claude/ralph-desk/analytics/<slug>/self-verification-report-NNN.md` (NNN = auto-increment from existing reports)
 4. **Report to user**: Display the full report content
 
 Report template (10 sections):
@@ -483,7 +571,22 @@ When `--verify-consensus` is enabled, also track in `status.json`:
 ---
 
 ## `status <slug>`
-Read `.claude/ralph-desk/logs/<slug>/status.json` and display.
+Read `.claude/ralph-desk/logs/<slug>/runtime/status.json` and display a detailed report:
+
+```
+Campaign: <slug>
+Iteration: <iteration> / <max_iter>
+Phase: <phase> | Last Result: <last_result>
+Worker Model: <worker_model> (<worker_engine>) | Verifier Model: <verifier_model> (<verifier_engine>)
+Verify Mode: <verify_mode> | Consensus: <verify_consensus>
+Consecutive Failures: <consecutive_failures>
+Verified US: <verified_us array, comma-separated>
+Updated: <updated_at_utc> (elapsed: now - updated_at)
+```
+
+If `status.json` does not exist, display "No active campaign for <slug>."
+If the campaign has a `complete` or `blocked` sentinel, show that status prominently.
+Read the last `verify-verdict.json` to show the most recent verdict summary and any failure issues.
 
 ## `logs <slug> [N]`
 - No N: show latest `iter-*.worker-prompt.md` summary
@@ -497,25 +600,64 @@ Remove:
 - `.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`
+- `.claude/ralph-desk/logs/<slug>/runtime/session-config.json`
+- `.claude/ralph-desk/logs/<slug>/runtime/worker-heartbeat.json`
+- `.claude/ralph-desk/logs/<slug>/runtime/verifier-heartbeat.json`
 - `.claude/ralph-desk/memos/<slug>-escalation.md`
-Note: `logs/<slug>/self-verification-data.json`, `self-verification-report-NNN.md`, `campaign-report.md`, `campaign-report-v{N}.md`, `iter-NNN-done-claim.json`, and `iter-NNN-verify-verdict.json` are intentionally preserved across clean for historical comparison.
+Note: `campaign-report.md`, `campaign-report-v{N}.md`, `iter-NNN-done-claim.json`, and `iter-NNN-verify-verdict.json` are intentionally preserved across clean for historical comparison. Analytics files (`debug.log`, `campaign.jsonl`, `self-verification-data.json`, `self-verification-report-NNN.md`) at `~/.claude/ralph-desk/analytics/<slug>/` are NOT affected by project-level clean.
 
-If `--kill-session` is passed, clean up ALL tmux artifacts:
+If `--kill-session` is passed, clean up Worker/Verifier tmux panes using session-config.json:
 ```bash
-# Kill rlp-desk tmux sessions
-tmux list-sessions -F '#{session_name}' 2>/dev/null | grep "^rlp-desk-<slug>-" | while read s; do tmux kill-session -t "$s"; done
+# Read pane IDs from session-config.json (safe — targets only Worker/Verifier panes)
+SESSION_CONFIG=".claude/ralph-desk/logs/<slug>/runtime/session-config.json"
+if [ -f "$SESSION_CONFIG" ] && command -v jq &>/dev/null; then
+  WORKER_PANE=$(jq -r '.panes.worker // empty' "$SESSION_CONFIG")
+  VERIFIER_PANE=$(jq -r '.panes.verifier // empty' "$SESSION_CONFIG")
+
+  for pane_id in "$WORKER_PANE" "$VERIFIER_PANE"; do
+    if [ -n "$pane_id" ]; then
+      tmux send-keys -t "$pane_id" C-c 2>/dev/null
+      tmux send-keys -t "$pane_id" "/exit" Enter 2>/dev/null
+    fi
+  done
+  sleep 2
+  for pane_id in "$WORKER_PANE" "$VERIFIER_PANE"; do
+    if [ -n "$pane_id" ]; then
+      tmux kill-pane -t "$pane_id" 2>/dev/null
+    fi
+  done
+else
+  echo "WARNING: session-config.json not found or jq not installed."
+  echo "Cannot safely identify Worker/Verifier panes. Kill them manually."
+fi
+```
+**CRITICAL: NEVER use `grep -i 'claude\|codex'` to find panes to kill.** The user's own Claude Code session matches those patterns. Always use the specific pane IDs from session-config.json.
+
+## `analytics [slug]`
+
+Cross-project analytics dashboard. Scans `~/.claude/ralph-desk/analytics/` for all campaign data.
+
+- No slug: show summary across all projects (total campaigns, pass/fail rate, average iterations, total cost)
+- With slug: show detailed analytics for that project (per-US pass rate, model upgrade frequency, iteration distribution, cost per US)
 
-# Kill split panes in current window (Worker/Verifier panes from --mode tmux)
-# Find panes running claude/codex for this slug and kill them
-for pane_id in $(tmux list-panes -F '#{pane_id}:#{pane_current_command}' 2>/dev/null | grep -i 'claude\|codex' | cut -d: -f1); do
-  tmux kill-pane -t "$pane_id" 2>/dev/null
-done
+Data sources:
+- `campaign.jsonl` — per-iteration structured records
+- `metadata.json` — project root, campaign status, timestamps
+- `self-verification-data.json` — campaign-level quality metrics
 
-# Kill any remaining claude/codex processes for this campaign
-ps aux | grep -E "claude.*<slug>|codex.*<slug>" | grep -v grep | awk '{print $2}' | xargs kill 2>/dev/null
+## `resume <slug>`
+
+Resume a previously interrupted campaign. Equivalent to `run <slug>` but explicitly restores state:
+
+1. Read `.claude/ralph-desk/logs/<slug>/runtime/status.json` for `verified_us`, `iteration`, `consecutive_failures`
+2. Read `.claude/ralph-desk/memos/<slug>-memory.md` for completed stories and next iteration contract
+3. Check for sentinels (`complete.md`, `blocked.md`) — if present, inform user and stop
+4. If no sentinels, invoke `run <slug>` with the same options from the previous session (stored in status.json fields: `worker_model`, `verifier_model`, `verify_mode`, `verify_consensus`)
+5. The runner automatically restores `verified_us` from memory or status.json on startup
+
+Example:
+```
+/rlp-desk resume my-feature
 ```
 
 ## No args or `help`
@@ -543,7 +685,7 @@ Run options:
   --consensus-scope SCOPE    When consensus runs: all|final-only (default: all)
   --cb-threshold N           CB threshold: consecutive failures before BLOCKED (default: 3)
   --iter-timeout N           Per-iteration timeout in seconds, tmux mode only (default: 600)
-  --debug                    Debug logging (logs/<slug>/debug.log)
+  --debug                    Debug logging (~/.claude/ralph-desk/analytics/<slug>/debug.log)
   --with-self-verification   Campaign self-verification analysis (post-loop report)
 ```
 

package/src/governance.md

@@ -11,6 +11,7 @@ The Leader orchestrates, while Worker/Verifier run in isolated fresh contexts ev
 - **Filesystem = memory**: State exists only on the filesystem (PRD, memory, context, memos).
 - **Worker claim ≠ complete**: A Worker's DONE is merely a claim. The Verifier must independently verify before it's confirmed.
 - **Worker scope is bounded**: Worker implements only the contracted US per iteration (Scope Lock). Out-of-scope changes are flagged by the Verifier.
+- **Worker must NEVER modify Claude Code settings** (settings.json, settings.local.json). Permission prompts must be reported as blocked, not bypassed by editing settings.
 - **Verifier is independent**: The Verifier judges based on evidence alone, without knowledge of the Worker's reasoning process.
 - **Sentinels are Leader-owned**: Only the Leader writes COMPLETE/BLOCKED sentinels.
 - **Supported engines**: claude (default; models: haiku, sonnet, opus) and codex (opt-in via `--worker-engine codex` / `--verifier-engine codex`).
@@ -184,7 +185,7 @@ Verification occurs at two boundaries, not as a single final event.
 ### Checkpoint 2: Release Readiness (us_id=ALL)
 - Trigger: all individual US pass Checkpoint 1 → Worker signals verify with us_id = "ALL"
 - Scope: all AC + L2 integration (if applicable) + L3 E2E Simulation + L4 deploy (if applicable) + mutation score (if CRITICAL, when mutation testing tool is configured in test-spec)
-- On fail: fix loop; escalation to user if 3 consecutive failures
+- On fail: fix loop; escalation to user if 6 consecutive failures (default cb_threshold)
 
 ### Relationship to Existing Flow
 - Checkpoint 1 = existing per-US verify (§7a). No change.
@@ -199,14 +200,27 @@ This is the default behavior, not an optional flag. Without it, IL-1 (Evidence M
 ### Worker: execution_steps in done-claim.json
 Worker records what was done, in what order, with command evidence in `done-claim.json`:
 - Each step includes: what action, which AC, command executed, exit code, summary
-- Step types: `write_test`, `verify_red`, `implement`, `verify_green`, `refactor`, `commit`, `verify`
+- Step types: `write_test`, `verify_red`, `implement`, `verify_green`, `refactor`, `commit`, `verify`, `verify_existing`
 - This proves the Worker followed test-first approach and did not skip steps
+- **Existing implementation rule**: When code already exists from a prior iteration/campaign, Worker MAY use `verify_existing` instead of `write_test → verify_red → implement → verify_green`. `verify_existing` requires: run all existing tests, record exit codes, confirm all AC are covered by passing tests. Worker MUST NOT skip recording evidence — `verify_existing` is evidence that existing code satisfies AC, not a shortcut to skip verification.
 
 ### Verifier: reasoning in verify-verdict.json
 Verifier records WHY each judgment was made in `verify-verdict.json`:
 - Each check includes: what was checked, decision (pass/fail), and the specific evidence basis
-- Checks include: IL-1 Evidence Gate, Layer Enforcement, Test Sufficiency, Anti-Gaming, Worker Process Audit
+- Checks include: IL-1 Evidence Gate, Layer Enforcement, Test Sufficiency, Anti-Gaming, Worker Process Audit, Test Coverage Audit
 - This proves the Verifier actually performed each check rather than rubber-stamping
+- **Test Coverage Audit (mandatory)**: Verifier MUST check that tests cover ALL code paths, not just happy paths. Specifically:
+  - Every branch in `case` statements must have a test (e.g., all model types in get_next_model)
+  - Every engine/model combination must be tested (claude, codex 5.4, spark — not just 1-2)
+  - Every ceiling/boundary must be tested (not just "opus ceiling" — also spark ceiling, 5.4 ceiling)
+  - If Worker's tests cover only 2 of 3 engine paths, verdict MUST be fail with "test coverage gap" issue
+  - "Tests pass" is NOT sufficient — "tests cover all code paths" is required
+- **Integration Test (mandatory when functions call other functions)**: Verifier MUST check that function call chains produce correct end-to-end results, not just that each function works in isolation. Specifically:
+  - If function A's output is function B's input, there MUST be a test that runs A→B together and verifies the result
+  - Example: `get_model_string()` returns "gpt-5.3-codex-spark:medium" — `get_next_model()` must accept that exact value and return the correct upgrade. A test must verify this chain.
+  - Unit tests (extract_fn + isolated run) are necessary but NOT sufficient for refactored code
+  - Structural tests (grep for function existence) are necessary but NOT sufficient
+  - "All unit tests pass" does NOT prove the system works — integration tests prove it
 
 ### Why This Is Default (Not Optional)
 - IL-1 says "no claims without evidence" — this applies to Worker AND Verifier
@@ -388,19 +402,23 @@ Characteristics:
 ├── plans/
 │   ├── prd-<slug>.md                # PRD (in-place: --mode improve | deleted: --mode fresh)
 │   └── test-spec-<slug>.md          # Verification criteria (regenerated on re-execution)
-└── logs/<slug>/
-    ├── debug.log                    # Debug output (versioned: debug-v{N}.log on re-execution)
+└── logs/<slug>/                          # Project-level operational data
     ├── campaign-report.md           # Campaign summary (versioned: campaign-report-v{N}.md on re-execution)
     ├── iter-NNN.worker-prompt.md    # Audit trail prompt copy (deleted on re-execution)
     ├── iter-NNN.verifier-prompt.md  # Audit trail prompt copy (deleted on re-execution)
     ├── iter-NNN.result.md           # Iteration result (deleted on re-execution)
     ├── iter-NNN-done-claim.json     # Archived done-claim per iteration (deleted on re-execution)
     ├── iter-NNN-verify-verdict.json # Archived verdict per iteration (deleted on re-execution)
-    ├── self-verification-data.json  # Cumulative SV data (--with-self-verification; deleted on re-execution)
-    ├── self-verification-report-NNN.md  # Versioned SV report (-NNN auto-increment; NOT versioned via version_file)
     ├── status.json                  # Leader's loop state (deleted on re-execution)
     ├── baseline.log                 # Baseline capture (deleted on re-execution)
     └── cost-log.jsonl               # Per-iteration cost log (deleted on re-execution)
+
+~/.claude/ralph-desk/analytics/<slug>--<root_hash>/  # User-level cross-project analytics
+    ├── metadata.json                # Campaign metadata (slug, project_root, status, times)
+    ├── debug.log                    # Debug output (versioned: debug-v{N}.log on re-execution)
+    ├── campaign.jsonl               # Per-iteration structured data (versioned: campaign-v{N}.jsonl)
+    ├── self-verification-data.json  # Cumulative SV data (agent-mode only, --with-self-verification)
+    └── self-verification-report-NNN.md  # Versioned SV report (--with-self-verification; NNN auto-increment)
 ```
 
 ## 7. Leader Loop Protocol
@@ -555,14 +573,14 @@ In tmux mode: Leader writes `<slug>-escalation.md` with the report and sets BLOC
 | Condition | Verdict |
 |-----------|---------|
 | context-latest.md unchanged for 3 consecutive iterations | BLOCKED |
-| Same acceptance criterion fails 2 consecutive iterations | Upgrade model, retry once; if still failing → Architecture Escalation (§7¾) → BLOCKED |
-| 3 consecutive **fail** verdicts on 3 unique criterion IDs | Upgrade to opus, retry once; if still failing → BLOCKED |
+| Same acceptance criterion fails 2 consecutive iterations | Upgrade model, retry once (Agent mode only; tmux: same model retry); if still failing → Architecture Escalation (§7¾) → BLOCKED |
+| `cb_threshold` (default: 6) consecutive **fail** verdicts on `cb_threshold` unique criterion IDs | Upgrade to opus, retry once; if still failing → BLOCKED (adjustable via `--cb-threshold`) |
 | 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.
+- "Diverse failures" = `cb_threshold` most recent `fail` verdicts each have a unique criterion ID.
 
 ## 9. Change Policy
 

package/src/model-upgrade-table.md

@@ -0,0 +1,50 @@
+# Model Upgrade Table
+
+Progressive Worker model upgrade on consecutive failure per US.
+CB default: 6. Override: `--cb-threshold N`. Worker only — Verifier fixed at campaign start.
+
+## Rules
+- Each row = 2-attempt window (same model for 2 consecutive fails)
+- Ceiling reached → repeat same model until CB
+- CB < table columns → BLOCKED at that column
+- CB > 6 → repeat ceiling model beyond column 6
+
+## GPT Pro (spark — separate token limit)
+
+| Complexity | 1-2 | 3-4 | 5-6 | 7+ |
+|------------|-----|-----|-----|-----|
+| LOW | spark:low | spark:medium | spark:high | BLOCKED |
+| MEDIUM | spark:medium | spark:high | spark:xhigh | BLOCKED |
+| HIGH | spark:high | spark:xhigh | spark:xhigh | BLOCKED |
+| CRITICAL | spark:xhigh | spark:xhigh | spark:xhigh | BLOCKED |
+
+## Non-Pro (gpt-5.4)
+
+| Complexity | 1-2 | 3-4 | 5-6 | 7+ |
+|------------|-----|-----|-----|-----|
+| LOW | 5.4:low | 5.4:medium | 5.4:high | BLOCKED |
+| MEDIUM | 5.4:medium | 5.4:high | 5.4:xhigh | BLOCKED |
+| HIGH | 5.4:high | 5.4:xhigh | 5.4:xhigh | BLOCKED |
+| CRITICAL | 5.4:xhigh | 5.4:xhigh | 5.4:xhigh | BLOCKED |
+
+## Claude-only
+
+| Complexity | 1-2 | 3-4 | 5-6 | 7+ |
+|------------|-----|-----|-----|-----|
+| LOW | haiku | sonnet | opus | BLOCKED |
+| MEDIUM | sonnet | opus | opus | BLOCKED |
+| HIGH | sonnet | opus | opus | BLOCKED |
+| CRITICAL | opus | opus | opus | BLOCKED |
+
+## Complexity Evaluation (brainstorm determines this)
+
+| Factor | LOW | MEDIUM | HIGH | CRITICAL |
+|--------|-----|--------|------|----------|
+| US count | 1-2 | 3-5 | 6-10 | 10+ |
+| File scope | single | 2-5 | 6+ | cross-repo |
+| Logic | simple CRUD | conditionals | algorithms | security/crypto |
+| Dependencies | none | 1-2 | 3+ API/DB | distributed |
+| Code impact | new only | modify existing | refactor | architecture change |
+
+Overall complexity = highest factor level.
+Campaign starting model = lowest US risk level (progressive upgrade handles harder US).