@ai-dev-methodologies/rlp-desk 0.15.2 → 0.15.3

package/docs/plans/pr-e-phase-c1-blocked-recovery-hygiene-v0.md

@@ -0,0 +1,233 @@
+# PR-E: Phase C1 — Blocked Sentinel Recovery Hygiene (Planner v0)
+
+> **Plan reference**: `docs/plans/v0.15-stabilization-plan.md` §5 Phase C
+> **Continuation of**: PR-A (Bug #10 phase=verify recovery, commit `95c0d4e`)
+> **Stop rule**: codex critic APPROVE (P0+P1=0) before merge
+> **Critic instruction**: approve unless P0 or P1 found
+
+---
+
+## 1. Problem
+
+After PR-A landed (`phase=verify` recovery honored), the next recovery surface is **operator-cleared BLOCKED**.
+
+Today, when operator clears `<slug>-blocked.md` to recover (the documented manual recovery for some BLOCKED reasons), `status.json` retains:
+- `phase: "blocked"` (stale)
+- `consecutive_failures` and `consecutive_blocks` counters at their pre-BLOCKED values
+- `last_block_reason` populated
+
+On leader relaunch:
+1. `readCurrentState` (`src/node/runner/campaign-main-loop.mjs:364`) preserves all of these
+2. Main loop iterates, tries to dispatch worker
+3. If worker fails for any reason, `consecutive_failures` increments from its stale base
+4. Circuit breaker may trip immediately even though operator's intent was "fresh start"
+5. Result: campaign re-BLOCKs on first failure, operator's recovery effort wasted
+
+This is the same class as Bug #10 (PR-A): operator's recovery intent silently discarded because leader doesn't recognize the recovery surface.
+
+---
+
+## 2. Principles (3)
+
+1. **Operator's recovery intent is the source of truth.** When BLOCKED sentinel is gone but status.json still says blocked + counters stale, the operator clearly meant to reset state. Leader must recognize and honor.
+2. **Recovery validation must be strict (mirror PR-A).** Auto-honoring without checks risks accidental honor of crashed-mid-write states. PR-A's 5-check pattern applied to the blocked-recovery context.
+3. **Defensive default — fall through, don't break.** If validation fails, log the reason and proceed with current behavior (no auto-reset). Recovery feature can never make existing flows worse.
+
+## 3. Decision drivers (top 3)
+
+| # | Driver | Why |
+|---|---|---|
+| D1 | **Operator recovery completeness** | PR-A covered phase=verify; phase=blocked is the most-common operator recovery (clear sentinel → relaunch). Closing this gap completes the pair. |
+| D2 | **Mirror PR-A pattern** | Same shape (entry-time validate + flag + audit log) reduces cognitive load for future readers. Both Node + zsh same way. |
+| D3 | **Counter reset honesty** | Operator clearing the sentinel implies intent to retry from clean state. Stale counters silently re-BLOCK = surprise. |
+
+---
+
+## 4. Viable options
+
+### Option A — Entry-time blocked-recovery branch (mirror of PR-A) **[recommended]**
+
+After `readCurrentState`, before main loop, add a second recovery branch:
+- IF `state.phase === 'blocked'` AND blocked sentinel does NOT exist (operator cleared) AND counters are non-zero → **operator-cleared recovery detected**
+- Validate (5 checks, see §7)
+- On pass: reset phase to 'worker', reset counters to 0, log audit line
+- On fail: fall through (current behavior — campaign continues with stale state, may immediately re-BLOCK)
+
+Pros: surgical (single branch, ~30 LOC each side), pattern matches PR-A exactly, defensive default.
+Cons: adds another entry-time check (small overhead).
+
+### Option B — Reset on every relaunch unless explicit "preserve counters" flag
+
+Always reset counters when relaunching with no BLOCKED sentinel. Add `--preserve-counters` flag for users who want stale-counter behavior.
+
+Pros: simpler logic.
+Cons: changes existing behavior for users who didn't experience this issue. Breaks back-compat for anyone relying on counter persistence across relaunches.
+
+→ **Rejected**: violates principle 3 (defensive default).
+
+### Option C — Document operator workaround instead of code change
+
+Add cookbook entry: "after clearing blocked sentinel, also `jq` zero out counters in status.json".
+
+Pros: zero code change.
+Cons: pushes burden to operator. Same class of failure as Bug #10's pre-PR-A state — the leader should recognize recovery, not require operator jq pipelines.
+
+→ **Rejected**: violates principle 1.
+
+**Recommendation: A.**
+
+---
+
+## 5. Scope
+
+### P0 — must land
+
+1. **Node leader entry-time blocked-recovery branch** (`src/node/runner/campaign-main-loop.mjs`):
+   - New helper `_validateBlockedRecovery({ paths, state })` — returns `{ ok: bool, reason: string }`. 5 checks (§7).
+   - Branch after readCurrentState (around line 1392, where PR-A branch sits) — if `phase === 'blocked'` and validator passes, reset phase + counters + log.
+
+2. **zsh runner mirror** (`src/scripts/run_ralph_desk.zsh`):
+   - Mirror helper `_validate_blocked_recovery` in `lib_ralph_desk.zsh`
+   - Mirror entry-time branch (similar location to PR-A's site at `:3047-3071` range)
+
+### P1 — must land
+
+3. **Tests**:
+   - `tests/node/test-blocked-recovery-hygiene.test.mjs` (NEW, 5 ACs):
+     - AC-BR1: phase=blocked + sentinel absent + counters non-zero + valid → reset + dispatch worker normally
+     - AC-BR2: phase=blocked + sentinel PRESENT → don't auto-recover, throw "Run clean first" (existing behavior preserved)
+     - AC-BR3: phase=blocked + sentinel absent + counters all zero → fall through (nothing to reset)
+     - AC-BR4: phase=verify + sentinel absent → defer to PR-A's branch (no double-handling)
+     - AC-BR5: phase=blocked + sentinel absent + last_block_reason indicates non-recoverable category (`mission_abort`) → fall through, log "non-recoverable category, manual review needed"
+   - `tests/test-blocked-recovery-zsh.sh` (NEW, 5 helper-level scenarios mirroring AC-BR1..5)
+
+### P2 — nice-to-have (deferred)
+
+- Cookbook entry in `docs/rlp-desk/getting-started.md` documenting the recovery flow now that leader honors it
+- Telemetry analytics — track how often operator-cleared recovery is detected (signal of campaign reliability)
+
+---
+
+## 6. Files to modify
+
+| File | Change | Risk |
+|---|---|---|
+| `src/node/runner/campaign-main-loop.mjs` | `_validateBlockedRecovery` helper + entry-time branch | LOW (pattern proven by PR-A) |
+| `src/scripts/lib_ralph_desk.zsh` | `_validate_blocked_recovery` helper | LOW |
+| `src/scripts/run_ralph_desk.zsh` | Entry-time branch (near `:3047-3071` range) | LOW |
+| `tests/node/test-blocked-recovery-hygiene.test.mjs` (NEW) | 5 ACs | LOW |
+| `tests/test-blocked-recovery-zsh.sh` (NEW) | 5 zsh scenarios | LOW |
+
+Total: 3 modified + 2 new = 5 files. Smaller surface than PR-A.
+
+---
+
+## 7. Validator: 4 checks (`_validateBlockedRecovery`) — Codex-revised v2
+
+Codex critic P1-1 finding: v1's Check 4 depended on `last_block_reason` field but **no code path persists that field to status.json**. Both Node `_emitBlockedSentinel` and zsh `write_blocked_sentinel` skip it. So the v1 validator would never block auto-recovery for mission_abort/repeat_axis — exactly the safety case it was designed for.
+
+**v2 fix**: detect non-recoverable categories from the **`<slug>-blocked.json` sidecar** (which `_emitBlockedSentinel` DOES write at L942-965, with `reason_category` + `recoverable` fields), not from status.json. The sidecar persists even when operator manually `rm <slug>-blocked.md` — they don't usually delete the sidecar.
+
+Returns `{ ok: bool, reason: string }`:
+
+1. `state.phase === 'blocked'` (precondition)
+2. Blocked sentinel `<slug>-blocked.md` does NOT exist (operator cleared)
+3. At least one of: `consecutive_failures > 0`, `consecutive_blocks > 0` (something to reset; if all counters zero, fall through — nothing to recover from)
+4. **Sidecar safety check**: if `<slug>-blocked.json` exists AND parses AND has `recoverable: false` → fall through with audit log "non-recoverable category <reason_category> from sidecar". If sidecar absent (e.g. user ran full `clean`) OR sidecar `recoverable: true` → proceed with auto-recovery. Mirrors `_classifyBlock` `recoverable` invariant; no new status field needed.
+
+(Check 5 from v0 — 30-day staleness — DROPPED. Architect-flagged as arbitrary.)
+
+On pass: caller resets `state.phase = 'worker'`, `state.consecutive_failures = 0`, `state.consecutive_blocks = 0`. Sidecar (if exists) is RENAMED to `<slug>-blocked.json.recovered-<iso>` for audit trail rather than deleted, so operator can inspect what was recovered from. Then logs:
+
+```
+[recovery] Operator-cleared BLOCKED detected (was: <last_block_reason>). Resetting counters and resuming as worker. iter=N us_id=<current_us>
+```
+
+On fail: log `[recovery] phase=blocked ignored: <reason>` and fall through to existing behavior.
+
+---
+
+## 8. Pre-mortem (3 scenarios)
+
+### S1 — Auto-recovery hides genuine problem
+Campaign keeps BLOCKING because of a real architectural issue. Operator clears sentinel each time. Auto-recovery resets counters → CB never trips → infinite loop of fail+clear.
+
+**Mitigation**: operator-cleared recovery is exactly that — operator chose to retry. If they keep clearing without fixing, the bug pattern is operator behavior, not leader's. Counters resetting is correct; CB still trips on the freshly-accumulated counters from current session. Leader doesn't enable infinite loops, operator does.
+
+**Residual risk**: low. If operator wants CB to persist across relaunches, they can leave the sentinel and use `clean` workflow instead.
+
+### S2 — Mid-write status.json read produces inconsistent state
+A previous leader instance crashed mid-`writeStatus`. Relaunch reads partial JSON.
+
+**Mitigation (corrected per Codex critic P2 backlog)**: `writeStatus` uses `writeJson` → `fs.writeFile` directly (NOT atomic rename). Partial writes are theoretically possible. If JSON is malformed, `readJsonIfExists` THROWS (not returns null) — leader fails fast at startup with parse error, surfacing the corruption to operator. Auto-recovery never proceeds because leader doesn't even reach the validator. This is acceptable: corrupted status.json is operator-visible immediately, not silently recovered. P2 backlog item: consider migrating writeStatus to atomic rename for crash safety, but that's a separate PR.
+
+### S3 — Race: operator clears sentinel while leader is starting
+Operator deletes blocked.md just as leader's `await exists(paths.blockedSentinel)` runs. Two outcomes:
+- Sentinel exists during check → existing "Run clean first" error throws (existing behavior, unchanged)
+- Sentinel missing during check → enters validator → if checks pass, recovery proceeds
+
+**Mitigation**: this is a benign race. Both outcomes are valid (operator either succeeded in clearing or didn't). No corruption possible.
+
+---
+
+## 9. Test plan
+
+### Unit (Node)
+
+`tests/node/test-blocked-recovery-hygiene.test.mjs`:
+
+Each AC sets up a fixture (status.json + memos/) per its scenario, runs the leader to first dispatch decision, asserts on dispatch behavior + log content.
+
+- AC-BR1 happy: setup phase=blocked, sentinel absent, consecutive_failures=3 → assert leader dispatches worker (not throw), assert state.consecutive_failures === 0 in next status write, assert audit log line matches
+- AC-BR2 sentinel present: setup phase=blocked, sentinel exists → assert leader throws "Run clean first" (existing behavior preserved)
+- AC-BR3 nothing to reset: phase=blocked, sentinel absent, all counters zero, last_block_reason empty → assert fall-through (no log line, no reset, normal worker dispatch)
+- AC-BR4 phase=verify defers: phase=verify, sentinel absent → assert PR-A logic runs (no blocked recovery handling)
+- AC-BR5 non-recoverable category: phase=blocked, sentinel absent, last_block_reason='mission_abort' → assert fall-through with log "non-recoverable category"
+
+### Integration (zsh)
+
+`tests/test-blocked-recovery-zsh.sh` (helper-level, mirrors `test-bug10-zsh-relaunch-hygiene.sh`):
+
+- Scenario BR-Z1: all 5 checks pass → `_validate_blocked_recovery` returns 0
+- Scenarios BR-Z2..BR-Z5: each check fails → returns 1 with reason matching expected substring
+
+### Regression
+
+- Full Node suite: 334/334 must remain green
+- Bug #10 PR-A tests (test-relaunch-phase-verify-hygiene.test.mjs) must remain green
+- Bug #7 zsh regression must remain green
+
+---
+
+## 10. Verification end-to-end
+
+1. `node --test tests/node/test-blocked-recovery-hygiene.test.mjs` → 5/5 PASS
+2. `bash tests/test-blocked-recovery-zsh.sh` → 5/5 PASS
+3. Full Node suite + Bug #7 regression unchanged green
+4. **`zsh tests/sv-gate-fast.sh` PASS** (governance §1g pre-merge gate, Codex critic P1-2)
+5. Manual sandbox: deliberately BLOCKED campaign → operator clears blocked.md → relaunch → leader logs `[recovery] Operator-cleared BLOCKED detected`, counters reset, worker dispatches, campaign continues. Repeat with `recoverable: false` sidecar → leader logs fall-through, no auto-recovery.
+6. **AC-BR5 fixture must use real `_emitBlockedSentinel` flow** (Codex critic P1-1) — write a sentinel via the actual code path, then test recovery against it. Not hand-authored status.json.
+
+**Release (NOT part of this PR's verification — per Codex critic P1-2 + CLAUDE.md absolute rules)**: any version bump, GitHub release, or npm publish is a SEPARATE user-approved action that follows merge. This PR's verification ends at items 1-6 above. Release decisions are not auto-flow.
+
+---
+
+## 11. ADR (preview)
+
+- **Decision**: extend PR-A's recovery-hygiene pattern to `phase=blocked` operator-cleared scenario
+- **Drivers**: D1 operator-recovery completeness, D2 mirror PR-A pattern, D3 counter reset honesty
+- **Alternatives considered**: B (always reset, breaks back-compat), C (doc-only, pushes burden to operator)
+- **Why chosen**: A surgical, pattern-proven, defensive default, completes Phase C1 without scope creep
+- **Consequences**: operator-cleared BLOCKED relaunches now work as intended; no need for jq counter-reset cookbook; logs add `[recovery]` lines visible via `/rlp-desk logs`
+- **Follow-ups**: Phase C2 (mid-iter crash recovery), Phase C3 (cross-mission queue recovery), Phase C4 (cookbook entry)
+
+---
+
+## 12. Round-by-round resolution log
+
+| Round | Reviewer | Verdict | Findings |
+|---|---|---|---|
+| 0 | — | Planner v0 | initial draft |
+| 1 | Architect (Claude inline) | ITERATE | 5 edits applied → v1: drop 30-day, add previous_block_reason, expand Check 4 prose, branch ordering, _skipNextWorkerDispatch comment |
+| 2 | Codex Critic | ITERATE — 0 P0, 2 P1 | P1-1: Check 4 redesigned to use `<slug>-blocked.json` sidecar `recoverable` field (status.json never persists `last_block_reason`). P1-2: §10.5 release auto-flow removed; SV gate + user approval explicit. P2: S2 mitigation prose corrected (writeJson is not atomic rename; readJsonIfExists throws not returns null). All applied → v2 (current). |
+| 3 | Codex Critic | **APPROVE** — 0 P0, 0 P1 | P1-1/P1-2 both closed. §7 sidecar-based gate validated. §10 sv-gate + user-approved release confirmed. **Loop terminated. Implementation can proceed.** |

package/docs/plans/v0.15-stabilization-phase-a-prep.md

@@ -0,0 +1,130 @@
+# Phase A — Empirical omc Baseline (Prep for Next Session)
+
+> **Plan reference**: `docs/plans/v0.15-stabilization-plan.md` §5 Phase A
+> **Goal**: measure omc /ralph + /team reliability empirically. Establishes the bar rlp-desk needs to reach.
+> **Output**: `docs/plans/v0.15-stabilization-omc-baseline.md` with per-test metrics.
+> **NOT a competition**: this is a measurement to set the stabilization target. omc is benchmark, not replacement.
+
+---
+
+## Why baseline measurement comes first
+
+Before changing rlp-desk's substrate (Phase B-F), we need to know what "omc-level reliability" actually looks like for our workload. Otherwise stabilization targets are guesswork.
+
+The 4 differentiators rlp-desk MUST preserve are not measured by omc — they're rlp-desk-only by design. So the baseline measurement focuses on what omc DOES have: per-iter Worker→Verifier, PRD-driven loop, multi-agent coordination, mandatory deslop, regression re-verification.
+
+## Three test campaigns
+
+### A1 — single-iter, single-story
+- **Workload**: small TypeScript fix in a sandbox repo (or BOS apps/web/ on a contained file)
+- **Tool**: `/oh-my-claudecode:ralph "Fix the unused variable warning in <specific-file>"`
+- **Measure**:
+  - operator-touch count (target = 0)
+  - total time (entry → completion)
+  - cost (token usage if available, otherwise rough estimate)
+  - did mandatory deslop pass run?
+  - did regression re-verification pass?
+
+### A2 — multi-iter, multi-story
+- **Workload**: synthetic PRD with 3 stories, each story trivial but distinct
+- **Tool**: `/oh-my-claudecode:ralph` with auto-generated prd.json refined to 3 stories
+- **Measure**:
+  - operator-touch count per story
+  - story completion order (sequential as PRD'd, or chosen by ralph?)
+  - failure recovery if a story blocks (does it advance to next or stop?)
+  - prd.json final state (all stories `passes: true`?)
+  - reviewer behavior (was each story actually verified against acceptance criteria?)
+
+### A3 — parallel team
+- **Workload**: 3-task synthetic spec where tasks are truly independent
+- **Tool**: `/oh-my-claudecode:team 3:executor "<spec>"`
+- **Measure**:
+  - parallelism (do 3 agents really run concurrently?)
+  - lock contention (any deadlocks on shared task list?)
+  - inter-agent messaging (any SendMessage between teammates?)
+  - completion time vs sequential estimate
+  - cleanup (does TeamDelete actually run on completion?)
+
+## Sandbox setup
+
+Recommend a throwaway test repo to avoid contaminating BOS or rlp-desk:
+
+```bash
+mkdir /tmp/omc-baseline-sandbox && cd /tmp/omc-baseline-sandbox
+git init
+# Add 1-2 simple TypeScript files with intentional issues for A1
+# Add a synthetic PRD for A2
+# Add a 3-task spec for A3
+```
+
+This isolates measurement from real product work and lets us reset between tests.
+
+## Output schema
+
+`docs/plans/v0.15-stabilization-omc-baseline.md`:
+
+```markdown
+# omc Baseline Measurement — Phase A Output
+
+## A1 (single-iter, single-story)
+- Workload: <description>
+- Result: PASS / PARTIAL / FAIL
+- Operator-touch: N
+- Time: Xm Ys
+- Cost: $X.XX
+- Deslop ran: YES/NO
+- Regression re-verify: PASS/FAIL/N-A
+- Subjective notes: ...
+
+## A2 (multi-iter, multi-story)
+- Workload: <description>
+- Result: PASS / PARTIAL / FAIL
+- Stories completed: N/3
+- Operator-touch: N per story
+- Failure recovery observed: YES/NO + behavior
+- Total time: Xm Ys
+- prd.json final state: ...
+- Reviewer per-story verification: YES/NO
+
+## A3 (parallel team)
+- Workload: <description>
+- Result: PASS / PARTIAL / FAIL
+- Parallelism observed: YES/NO + concurrent count
+- Lock contention: NONE/ONE/MULTIPLE
+- Total time vs sequential: Xm vs Ym
+- Cleanup: COMPLETE/PARTIAL/MANUAL
+
+## Synthesis — what is "omc-level reliability"?
+
+[1-2 paragraphs translating the metrics into a target for rlp-desk]
+
+## Phase B implications
+
+[which omc patterns should rlp-desk Phase B adopt for tmux/process lifecycle race?]
+```
+
+## Cost estimate
+
+3 small test campaigns: total ~$5-15. Sandbox runs are bounded (no real product blast radius).
+
+## How to run (next session)
+
+Open Claude Code in /tmp/omc-baseline-sandbox (after creating it per above):
+
+```
+/oh-my-claudecode:ralph "Fix the unused variable warning in src/index.ts"
+```
+
+Wait for completion. Record metrics. Reset sandbox. Repeat for A2 and A3 with the synthetic PRD/spec.
+
+After all three: write `docs/plans/v0.15-stabilization-omc-baseline.md` in rlp-desk repo with the synthesis.
+
+## What this enables
+
+Once Phase A is done, Phase B (tmux/process lifecycle race hardening) has a concrete target: "match omc /ralph's A1 behavior on operator-touch within ±20%, while preserving multi-engine consensus + multi-mission queue."
+
+Without Phase A, Phase B targets are imaginary.
+
+## Honest scope note
+
+This is preparation work. The Phase A run itself happens in a fresh session (sandbox cwd). This prep doc + the v0.15-stabilization-plan.md are the carry-over artifacts.

package/docs/plans/v0.16-real-llm-sv-gate-spec.md

@@ -0,0 +1,177 @@
+# Real-LLM SV Gate Framework — Spec (Phase F bootstrap)
+
+> **Status**: design + first scenario bootstrap. Active stabilization Phase F.
+> **Plan reference**: `docs/plans/v0.15-stabilization-plan.md` §5 Phase F.
+> **Goal**: replace today's grep+unit-test "SV gate theater" with a framework that ACTUALLY catches production failure modes by running real claude/codex agents against real campaigns.
+
+---
+
+## 1. The problem in one paragraph
+
+Today's SV gate (`tests/sv-self-verify-*.sh`, `tests/sv-gate-*.sh`) is grep-and-label theater. Each "scenario" is a shell command (grep, unit test, regression) labeled with five categories (`correctness | integration | security | perf | error-path`) and reported as "Worker → Verifier → PASS". **No real LLM agent runs**. None of the 10 production bugs (#1-#10, 2026-05-01..05-07) were caught by SV gate before shipping. Every Bug #N+1 will follow the same pattern unless the framework changes.
+
+## 2. Why current SV gate misses production failures
+
+Production failure modes that today's gate cannot reproduce:
+
+| Failure mode | Why grep+unit can't catch | Real-LLM gate can |
+|---|---|---|
+| Worker hang on `.claude/` self-modification gate (Bug #1) | LLM platform-level constraint, not testable in unit | YES (real claude worker writes sentinel, observes hang) |
+| tmux pane lifecycle race (Bug #5/#6/#7) | timing-dependent, requires real TUI lifecycle | YES (real worker + real pane + real reaper) |
+| Worker contract violation under non-determinism (Bug #3/#4/#8/#9) | LLM produces malformed/incomplete artifact non-deterministically | YES (run actual worker with real prompt; observe artifact shape over N runs) |
+| Recovery hygiene under partial state (Bug #10) | requires real campaign + real BLOCKED + real operator recovery | YES (real campaign brought to BLOCKED, real operator-style recovery, real relaunch) |
+
+The common thread: **production failures require production-like state**. Unit tests can't produce it; only real campaigns can.
+
+## 3. Framework requirements
+
+A real-LLM SV gate must:
+
+R1. **Run a complete real campaign** (1-3 iterations) per scenario, not isolated function calls.
+R2. **Use real claude or codex worker + verifier**, not stub/mock LLM responses.
+R3. **Run inside CI-like environment** (real tmux session + real Claude Code CLI / codex CLI).
+R4. **Be deterministic enough to gate a release**: same scenario produces same PASS/FAIL outcome >95% of the time.
+R5. **Stay within cost budget**: each scenario <$5; total nightly run <$50.
+R6. **Run on a schedule, not per-PR**: too expensive to gate every PR. Nightly is the target. Per-PR can run a subset (sub-$10).
+R7. **Capture failure provenance**: when scenario fails, the failure must be reproducible from the captured campaign artifacts (logs, status, sentinel state).
+R8. **Cover all 10 historical bug categories**: each merged PR adds at least one scenario covering the bug class it touched.
+
+## 4. Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ tests/sv-real-llm/                                              │
+│                                                                  │
+│   scenarios/                                                     │
+│     bug-01-claude-self-modification-gate.test.sh                 │
+│     bug-05-worker-dead-on-reuse.test.sh                          │
+│     bug-07-post-sentinel-race.test.sh                            │
+│     bug-10-relaunch-phase-verify-hygiene.test.sh                 │
+│     ...                                                          │
+│                                                                  │
+│   harness/                                                       │
+│     run-scenario.sh         (single scenario runner)             │
+│     run-all.sh              (nightly suite runner)               │
+│     budget-guard.sh         (cost budget enforcement)            │
+│     capture-artifacts.sh    (post-run forensic bundle)           │
+│                                                                  │
+│   fixtures/                                                      │
+│     minimal-prd-1us.md       (1 user story, deterministic)       │
+│     minimal-prd-3us.md       (3 user stories)                    │
+│                                                                  │
+│   results/                                                       │
+│     <date>-<scenario>.json   (per-run outcome + cost + time)     │
+│     <date>-<scenario>.bundle/ (full campaign artifacts)          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Each scenario is a self-contained shell test:
+- Sets up a sandbox campaign
+- Runs `node ~/.claude/ralph-desk/node/run.mjs run <slug>` or via slash command
+- Asserts on final state (sentinel + status + artifacts)
+- Reports PASS/FAIL with provenance
+
+## 5. Scenario authoring contract
+
+Every scenario must define:
+
+```bash
+# scenario header (machine-readable)
+SCENARIO_ID="bug-10-relaunch-phase-verify-hygiene"
+SCENARIO_DESCRIPTION="Relaunch with operator-written phase=verify artifacts honored"
+SCENARIO_BUG_CATEGORY="d-recovery-hygiene"
+SCENARIO_HISTORICAL_BUG="Bug #10 (BOS 2026-05-07)"
+SCENARIO_COST_BUDGET_USD="3"
+SCENARIO_TIMEOUT_SECONDS="600"
+SCENARIO_REQUIRES="claude_cli OR codex_cli; tmux; jq"
+
+# scenario body: 4 parts
+# 1. SETUP — sandbox dir, init campaign, prepare fixture state
+# 2. EXERCISE — run actual rlp-desk against the fixture
+# 3. ASSERT — check final state matches expected
+# 4. REPORT — emit JSON outcome + capture artifacts
+```
+
+The 4-part shape is non-negotiable. Scenarios that skip ASSERT or REPORT do not count toward gate coverage.
+
+## 6. Cost + time discipline
+
+- **Budget per scenario**: $5 default, $10 max. Scenarios exceeding budget must be marked `EXPENSIVE` and only run weekly, not nightly.
+- **Timeout per scenario**: 600s default, 1800s max. Scenarios exceeding timeout are FAIL automatically.
+- **Total nightly budget**: $50. Suite must fit within budget or be sharded across nights.
+- **Per-PR subset**: scenarios marked `LIGHT` (under $1, under 60s) run on every PR. Others run nightly.
+
+Cost tracking via `tests/sv-real-llm/harness/budget-guard.sh` — reads `cost-log.jsonl` from rlp-desk and aggregates pre-run/post-run deltas.
+
+## 7. First scenario (this PR's bootstrap deliverable)
+
+`tests/sv-real-llm/scenarios/bug-10-relaunch-phase-verify-hygiene.test.sh` — converts the existing PR-A test (Bug #10 fix) into a real-LLM scenario:
+
+1. SETUP: create sandbox campaign in `/tmp/sv-real-llm-bug-10/`. init with minimal PRD (1 US, "fix the typo in foo.txt" — deterministic). Run iter-1 normally to BLOCKED state (deliberately fail verifier). Operator-style recovery: write iter-signal.json + done-claim.json by hand, set status.phase=verify, remove blocked sentinel.
+2. EXERCISE: relaunch leader (`/oh-my-claudecode:autopilot` or `node run.mjs run`).
+3. ASSERT:
+   - Leader logs `[recovery] Resuming verify phase` (PR-A audit line)
+   - No new `iter-001.worker-prompt.md` written (worker dispatch skipped)
+   - Verifier dispatched and produces verdict
+   - Final state: complete sentinel OR continue to iter-2
+4. REPORT: write `<date>-bug-10.json` with `{outcome, time_seconds, cost_usd, log_path, captured_state_path}`.
+
+Cost estimate: $1-3 (single iter-2 with fast worker model + verifier).
+
+## 8. Scenario coverage roadmap
+
+| Scenario | Bug class | Status | Cost | Test type |
+|---|---|---|---|---|
+| bug-10-relaunch-phase-verify-hygiene | (d) recovery | ✅ landed PR #12 | $3 | real-LLM |
+| bug-10-blocked-recovery-counters | (d) recovery | ✅ landed (this PR set) | $2 | real-LLM |
+| bug-07-post-sentinel-race | (a) lifecycle | ✅ landed | $3 | real-LLM |
+| bug-08-worker-incomplete-leader-fallback | (b) contract | ✅ landed | $3 | real-LLM |
+| bug-01-claude-self-modification-gate | (c) LLM-runtime | ✅ landed | $3 | real-LLM |
+| bug-05-worker-dead-on-reuse | (a) lifecycle | ✅ landed | $2 | real-LLM |
+| bug-03-verifier-noprogress | (b) contract | ✅ landed | $0 | structural |
+| bug-04-verifier-noprogress-regression | (b) contract | ✅ landed | $0 | structural |
+| bug-06-claude-worker-idle-noprogress | (a) lifecycle | ✅ landed | $0 | structural |
+| bug-09-verified-us-persistence | (b) contract | ✅ landed | $0 | structural |
+
+**All 10 historical bugs (#1-#10) covered.** 6 scenarios are real-LLM (require campaigns) gated by `RLP_REAL_LLM_GATE=1`; 4 are structural (zero cost, regression-guard the fix code itself). Future PRs fixing new bug classes MUST add a scenario for that class.
+
+Real-LLM total budget: ~$16 for full nightly run (6 × ~$3). Structural scenarios contribute zero cost. Per-PR LIGHT subset: structural-only (4 scenarios, <60s, $0).
+
+## 9. Integration with existing SV gate
+
+The current `tests/sv-gate-fast.sh` becomes the LIGHT subset. New `tests/sv-gate-real-llm.sh` becomes the FULL nightly suite. Existing scenario format is preserved for grep/unit checks; real-LLM scenarios are additive, not a replacement.
+
+`tests/sv-self-verify-*.sh` pattern stays — those are per-PR scenarios. New scenarios under `tests/sv-real-llm/scenarios/` are the real-LLM additions.
+
+## 10. Out of scope (deferred)
+
+- **Continuous deployment**: nightly schedule + GHA workflow. Add after first 3 scenarios prove the harness works.
+- **Cost dashboard**: aggregate cost trends over time. Add after first $50 month spent.
+- **Cross-engine A/B**: same scenario claude vs codex. Add after baseline established.
+- **Stress scenarios**: high-load, concurrent campaigns. Add after Phase B-E stabilization complete.
+
+## 11. This PR's scope (bootstrap only)
+
+This PR ships:
+1. This spec doc
+2. `tests/sv-real-llm/harness/run-scenario.sh` — single-scenario runner skeleton
+3. `tests/sv-real-llm/scenarios/bug-10-relaunch-phase-verify-hygiene.test.sh` — first real-LLM scenario, **gated by `RLP_REAL_LLM_GATE=1`** environment variable. Default: NOT executed. Operator runs explicitly.
+4. `tests/sv-real-llm/README.md` — quick how-to-run
+
+NOT in this PR:
+- nightly schedule (deferred)
+- remaining 9 scenarios (deferred)
+- integration into `sv-gate-fast.sh` or any existing gate (deferred)
+
+The bootstrap is small ON PURPOSE. Establish the pattern, prove it works on one bug, then scale.
+
+## 12. Verification
+
+- `bash tests/sv-real-llm/scenarios/bug-10-relaunch-phase-verify-hygiene.test.sh` runs in dry-mode (env not set) and prints "SKIPPED — RLP_REAL_LLM_GATE=1 to enable". No cost.
+- With `RLP_REAL_LLM_GATE=1` AND claude CLI available: scenario runs end-to-end. PASS = audit log line present + worker prompt iter-001 NOT rewritten + verifier dispatched. Cost ~$1-3.
+- Existing sv-gate-fast: 48/48 PASS unchanged.
+- Full Node suite: 339/339 PASS unchanged.
+
+## 13. Plan integration
+
+This PR advances Phase F from §5 of `docs/plans/v0.15-stabilization-plan.md`. After this PR lands, Phase F state changes from "planned" to "bootstrap complete; coverage roadmap active". Each subsequent PR closing a Phase B/C/D/E bug-class fix MUST add the corresponding real-LLM scenario per §8 table.

package/package.json

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

package/src/node/runner/campaign-main-loop.mjs

@@ -492,6 +492,69 @@ async function _validateOperatorRecoveryArtifacts({ paths, state }) {
   return { ok: true, reason: 'all five checks passed' };
 }
 
+// PR-E (Phase C1, stabilization): operator-cleared BLOCKED recovery.
+// When operator manually deletes <slug>-blocked.md to recover (a documented
+// flow), counters in status.json (consecutive_failures / consecutive_blocks)
+// stay populated. Without this branch, leader relaunches with stale counters
+// and may immediately re-BLOCK on the first failure even though operator's
+// intent was a fresh start. Pair to PR-A (phase=verify recovery, Bug #10).
+//
+// 4-check validator. Returns { ok, reason }. On any failure, caller falls
+// through to existing behavior — defensive default, never auto-recovers
+// against ambiguous state.
+//
+// Check 4 reads <slug>-blocked.json sidecar (NOT status.json), because
+// status.json never persists `last_block_reason` (blocked-write code path
+// at L920-968 doesn't write that field). The sidecar DOES carry
+// `recoverable: bool` per _classifyBlock contract — that's the canonical
+// non-recoverable signal.
+async function _validateBlockedRecovery({ paths, state }) {
+  // Check 1: precondition
+  if (state.phase !== 'blocked') {
+    return { ok: false, reason: `state.phase is ${state.phase}, not 'blocked'` };
+  }
+  // Check 2: sentinel cleared by operator
+  if (await exists(paths.blockedSentinel)) {
+    return { ok: false, reason: 'blocked sentinel still present (operator did not clear)' };
+  }
+  // Check 3: counters non-zero (something to reset)
+  const failures = state.consecutive_failures ?? 0;
+  const blocks = state.consecutive_blocks ?? 0;
+  if (failures === 0 && blocks === 0) {
+    return { ok: false, reason: 'counters already zero, nothing to recover' };
+  }
+  // Check 4: sidecar safety check
+  const sidecarPath = paths.blockedSentinel.replace(/\.md$/, '.json');
+  let sidecar = null;
+  try {
+    sidecar = await readJsonIfExists(sidecarPath);
+  } catch (err) {
+    // Malformed sidecar — be defensive and fall through.
+    return { ok: false, reason: `blocked.json sidecar parse error: ${err?.message ?? err}` };
+  }
+  if (sidecar && sidecar.recoverable === false) {
+    return {
+      ok: false,
+      reason: `non-recoverable category ${sidecar.reason_category ?? 'unknown'} from sidecar (use clean to reset)`,
+    };
+  }
+  return { ok: true, reason: 'sidecar absent or recoverable=true; recovery permitted' };
+}
+
+// PR-E helper: rename the recovered sidecar so operator can audit what was
+// recovered from. Best-effort — failure here is non-fatal.
+async function _archiveRecoveredSidecar(paths) {
+  const sidecarPath = paths.blockedSentinel.replace(/\.md$/, '.json');
+  if (!(await exists(sidecarPath))) return;
+  const iso = new Date().toISOString().replace(/[:.]/g, '-');
+  const archivePath = `${sidecarPath}.recovered-${iso}`;
+  try {
+    await fs.rename(sidecarPath, archivePath);
+  } catch (err) {
+    console.error(`[recovery] failed to archive sidecar: ${err?.message ?? err}`);
+  }
+}
+
 async function appendIterationAnalytics(paths, state, usId, verdict, options) {
   await appendCampaignAnalytics(paths.analyticsFile, {
     iter: state.iteration,
@@ -1414,6 +1477,33 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
     }
   }
 
+  // PR-E (Phase C1, stabilization): operator-cleared BLOCKED recovery.
+  // Pair to PR-A above. PR-E runs AFTER PR-A so phase=verify takes precedence
+  // when both apply (defensive ordering: never auto-recover phase=blocked if
+  // the operator's actual intent was phase=verify hygiene). Does NOT use
+  // _skipNextWorkerDispatch — counters reset is enough; worker dispatches
+  // normally on the next iteration with a clean state.
+  if (state.phase === 'blocked' && !state._skipNextWorkerDispatch) {
+    const validation = await _validateBlockedRecovery({ paths, state });
+    if (validation.ok) {
+      const previousReason = state.last_block_reason ?? '';
+      console.error(
+        `[recovery] Operator-cleared BLOCKED detected (was: ${previousReason || 'unrecorded'}). Resetting counters and resuming as worker. iter=${state.iteration} us_id=${state.current_us}: ${validation.reason}`,
+      );
+      state.phase = 'worker';
+      state.consecutive_failures = 0;
+      state.consecutive_blocks = 0;
+      state.last_block_reason = '';
+      // Archive sidecar (rename, not delete) so operator can audit the
+      // recovered-from state. Best-effort.
+      await _archiveRecoveredSidecar(paths);
+    } else {
+      console.error(
+        `[recovery] phase=blocked ignored, falling through to existing behavior: ${validation.reason}`,
+      );
+    }
+  }
+
   // P1-E Lane Enforcement: snapshot lane mtimes before each iteration,
   // compare at the top of the next iteration. Drift on read-only artifacts
   // (PRD, test-spec, context) emits a lane_violation_warning event + audit

package/src/scripts/lib_ralph_desk.zsh

@@ -369,6 +369,81 @@ _validate_operator_recovery_artifacts() {
   return 0
 }
 
+# PR-E (Phase C1, stabilization) — operator-cleared BLOCKED recovery validator.
+# Pair to PR-A (_validate_operator_recovery_artifacts above). Together they
+# close two recovery surfaces: phase=verify (PR-A) and phase=blocked
+# sentinel-cleared (PR-E this helper).
+#
+# Returns 0 when all 4 checks pass; 1 otherwise. Sets BLOCKED_RECOVERY_FAIL_REASON
+# (global) on failure for caller logging. Mirrors Node `_validateBlockedRecovery`
+# in src/node/runner/campaign-main-loop.mjs.
+#
+# Args:
+#   $1  blocked sentinel path (.md)
+#   $2  blocked sidecar path (.json)
+#   $3  status.json path
+_validate_blocked_recovery() {
+  local sentinel_md="$1" sidecar_json="$2" status_file="$3"
+  BLOCKED_RECOVERY_FAIL_REASON=""
+
+  # Check 1: precondition — caller verified phase=blocked already
+  # (passed in via status read; no need to re-read here)
+
+  # Check 2: sentinel cleared by operator
+  if [[ -f "$sentinel_md" ]]; then
+    BLOCKED_RECOVERY_FAIL_REASON="blocked sentinel still present (operator did not clear)"
+    return 1
+  fi
+
+  # Check 3: status.json must exist + counters non-zero
+  if [[ ! -f "$status_file" ]]; then
+    BLOCKED_RECOVERY_FAIL_REASON="status.json missing"
+    return 1
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    BLOCKED_RECOVERY_FAIL_REASON="jq unavailable; cannot validate"
+    return 1
+  fi
+  local fails blocks
+  fails=$(jq -r '.consecutive_failures // 0' "$status_file" 2>/dev/null)
+  blocks=$(jq -r '.consecutive_blocks // 0' "$status_file" 2>/dev/null)
+  if [[ "$fails" == "0" && "$blocks" == "0" ]]; then
+    BLOCKED_RECOVERY_FAIL_REASON="counters already zero, nothing to recover"
+    return 1
+  fi
+
+  # Check 4: sidecar safety — if sidecar exists and recoverable=false, fall through
+  if [[ -f "$sidecar_json" ]]; then
+    if ! jq -e . "$sidecar_json" >/dev/null 2>&1; then
+      BLOCKED_RECOVERY_FAIL_REASON="blocked.json sidecar parse error"
+      return 1
+    fi
+    local recoverable category
+    recoverable=$(jq -r '.recoverable' "$sidecar_json" 2>/dev/null)
+    category=$(jq -r '.reason_category // "unknown"' "$sidecar_json" 2>/dev/null)
+    if [[ "$recoverable" == "false" ]]; then
+      BLOCKED_RECOVERY_FAIL_REASON="non-recoverable category $category from sidecar (use clean to reset)"
+      return 1
+    fi
+  fi
+
+  return 0
+}
+
+# PR-E helper: rename the recovered sidecar so operator can audit what was
+# recovered from. Best-effort — failure is non-fatal.
+#
+# Args:
+#   $1  blocked sidecar path (.json)
+_archive_recovered_sidecar() {
+  local sidecar_json="$1"
+  [[ -f "$sidecar_json" ]] || return 0
+  local iso
+  iso=$(date -u +%Y-%m-%dT%H-%M-%SZ)
+  mv "$sidecar_json" "${sidecar_json}.recovered-${iso}" 2>/dev/null || true
+  return 0
+}
+
 # PR-0b-narrow (Plan v6) — stamp leader handshake ack onto the sentinel.
 # Mirror of src/node/shared/fs.mjs::stampAckField. Best-effort, audit-only:
 # any failure is silently swallowed. Sequence:

package/src/scripts/run_ralph_desk.zsh

@@ -3069,6 +3069,32 @@ main() {
       fi
     fi
 
+    # PR-E (Phase C1, stabilization): operator-cleared BLOCKED recovery.
+    # Pair to PR-A above. Runs AFTER PR-A (so phase=verify wins) and skipped
+    # when SKIP_NEXT_WORKER=1 (PR-A already honored). Resets stale counters
+    # in status.json when operator manually deleted the BLOCKED sentinel.
+    # Mirrors Node `_validateBlockedRecovery` + branch in campaign-main-loop.mjs.
+    if [[ "$LAST_PHASE" == "blocked" && "$SKIP_NEXT_WORKER" -eq 0 ]]; then
+      local _blocked_sidecar="$MEMOS_DIR/${SLUG}-blocked.json"
+      if _validate_blocked_recovery \
+           "$BLOCKED_SENTINEL" "$_blocked_sidecar" "$STATUS_FILE"; then
+        local _prev_reason
+        _prev_reason=$(jq -r '.last_block_reason // ""' "$STATUS_FILE" 2>/dev/null)
+        log "[recovery] Operator-cleared BLOCKED detected (was: ${_prev_reason:-unrecorded}). Resetting counters and resuming as worker. iter=$ITERATION"
+        log_debug "[recovery] iter=$ITERATION blocked_recovery=applied reason=\"${BLOCKED_RECOVERY_FAIL_REASON:-sidecar absent or recoverable=true}\""
+        # Reset counters in-process. update_status writes fresh status when
+        # next phase transition fires. Operator's intent was a clean restart.
+        CONSECUTIVE_FAILURES=0
+        CONSECUTIVE_BLOCKS=0
+        LAST_BLOCK_REASON=""
+        # Archive sidecar (rename, not delete) for audit trail.
+        _archive_recovered_sidecar "$_blocked_sidecar"
+      else
+        log "[recovery] phase=blocked ignored: ${BLOCKED_RECOVERY_FAIL_REASON}"
+        log_debug "[recovery] iter=$ITERATION blocked_recovery=skipped reason=\"${BLOCKED_RECOVERY_FAIL_REASON}\""
+      fi
+    fi
+
     if (( ! SKIP_NEXT_WORKER )); then
       # --- governance.md s7 step 8 (cleanup): Clean previous iteration signals ---
       # Bug #7 Fix-R cleanup: unlock 0o444 sentinels written by the previous