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

package/src/governance.md

@@ -373,28 +373,34 @@ Characteristics:
 ```
 .claude/ralph-desk/
 ├── prompts/
-│   ├── <slug>.worker.prompt.md      # Worker base prompt
-│   └── <slug>.verifier.prompt.md    # Verifier base prompt
+│   ├── <slug>.worker.prompt.md      # Worker base prompt (regenerated on re-execution)
+│   └── <slug>.verifier.prompt.md    # Verifier base prompt (regenerated on re-execution)
 ├── context/
-│   └── <slug>-latest.md             # Current frontier (Worker updates)
+│   └── <slug>-latest.md             # Current frontier; Worker updates (reset to template on re-execution)
 ├── 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>-escalation.md          # Architecture escalation report (tmux mode, §7¾)
-│   ├── <slug>-complete.md           # SENTINEL (Leader only)
-│   └── <slug>-blocked.md            # SENTINEL (Leader only)
+│   ├── <slug>-memory.md             # Campaign memory; Worker updates (reset to template on re-execution)
+│   ├── <slug>-done-claim.json       # Worker's completion claim (runtime; deleted on re-execution)
+│   ├── <slug>-iter-signal.json      # Worker's iteration signal (runtime; deleted on re-execution)
+│   ├── <slug>-verify-verdict.json   # Verifier's verdict (runtime; deleted on re-execution)
+│   ├── <slug>-escalation.md         # Architecture escalation report (tmux mode, §7¾; deleted on re-execution)
+│   ├── <slug>-complete.md           # SENTINEL (Leader only; deleted on re-execution)
+│   └── <slug>-blocked.md            # SENTINEL (Leader only; deleted on re-execution)
 ├── plans/
-│   ├── prd-<slug>.md                # PRD (shared contract)
-│   └── test-spec-<slug>.md          # Verification criteria
+│   ├── prd-<slug>.md                # PRD (in-place: --mode improve | deleted: --mode fresh)
+│   └── test-spec-<slug>.md          # Verification criteria (regenerated on re-execution)
 └── 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)
-    ├── self-verification-data.json              # Cumulative campaign data (--with-self-verification)
-    ├── self-verification-report-NNN.md          # Versioned campaign analysis report (--with-self-verification)
-    └── status.json                  # Leader's loop state
+    ├── debug.log                    # Debug output (versioned: debug-v{N}.log on re-execution)
+    ├── 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)
 ```
 
 ## 7. Leader Loop Protocol
@@ -443,8 +449,19 @@ for iteration in 1..max_iter:
        • fail + continue → go to ⑧
        • blocked → write BLOCKED sentinel, stop
 
+  ⑦d Archive iteration artifacts (after verdict read, before next prep)
+     - Archive done-claim.json → logs/<slug>/iter-NNN-done-claim.json
+     - Archive verify-verdict.json → logs/<slug>/iter-NNN-verify-verdict.json
+     (Preserved across clean; data source for Campaign Report and SV analysis)
+
   ⑧ Write iter-NNN.result.md to logs/<slug>/ (result status + git diff --stat)
      Update status.json, report to user, continue to next iteration
+
+After loop end (COMPLETE, BLOCKED, TIMEOUT):
+  ⑧½ Campaign Report (always — independent of --debug)
+     - Generate logs/<slug>/campaign-report.md with 8 sections
+     - Version existing report to campaign-report-v{N}.md before writing new
+     - Data: status.json (baseline_commit, per-iter), archived iter artifacts, PRD, git diff
 ```
 
 ## 7a. Per-US Verification
@@ -480,7 +497,7 @@ Worker completes US → signal verify
   → Codex Verifier runs (checks AC)
   → Both pass → proceed (next US or COMPLETE)
   → Either fails → combined issues → fix contract → Worker retry
-  → Max 3 consensus rounds per US → BLOCKED if still disagreeing
+  → Max 6 consensus rounds per US → BLOCKED if still disagreeing
 
 **NO ENGINE PRIORITY:** Claude and Codex have equal weight. If one passes and the other fails, the verdict is FAIL. No engine may be prioritized or dismissed. Infrastructure failure = CLI crash, timeout, or verdict file not generated — NOT a valid verdict with verdict=fail.
 ```
@@ -518,12 +535,12 @@ Every change must be justified by the issue it addresses.
 
 ## 7¾. Architecture Escalation
 
-Note: Circuit Breaker (§8) fires first at 2 consecutive failures (model upgrade + retry). If the retry also fails (3rd consecutive failure), Architecture Escalation applies. The CB retry counts toward the consecutive_failures counter.
+Note: Circuit Breaker (§8) fires first at 2 consecutive failures (model upgrade + retry — Path A: Agent-mode only; in tmux mode the shell CB triggers directly without model upgrade). If the retry also fails (`cb_threshold` reached), Architecture Escalation applies. The CB retry counts toward the consecutive_failures counter.
 
-If 3+ consecutive fix attempts fail for the same US:
+If `cb_threshold` or more consecutive fix attempts fail for the same US:
 
 1. **STOP fixing symptoms** — the problem is likely architectural, not a bug.
-2. **Leader reports to user**: "3 consecutive fix attempts failed for US-{id}. This suggests an architectural issue, not a simple bug."
+2. **Leader reports to user**: "`cb_threshold` consecutive fix attempts failed for US-{id}. This suggests an architectural issue, not a simple bug."
 3. **Include in report**:
    - What was attempted in each fix
    - What specifically kept failing

package/src/scripts/init_ralph_desk.zsh

@@ -8,22 +8,150 @@ set -euo pipefail
 # Creates project-local scaffold in: .claude/ralph-desk/
 #
 # Usage:
-#   ~/.claude/ralph-desk/init_ralph_desk.zsh <slug> [objective]
+#   ~/.claude/ralph-desk/init_ralph_desk.zsh <slug> [objective] [--mode fresh|improve]
 # =============================================================================
 
-SLUG="${1:?Usage: $0 <slug> [objective]}"
-OBJECTIVE="${2:-TBD - fill in the objective}"
+SLUG="${1:?Usage: $0 <slug> [objective] [--mode fresh|improve]}"
+MODE=""
+OBJECTIVE="TBD - fill in the objective"
+
+# Parse remaining arguments: --mode fresh|improve + optional positional objective
+shift
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode)
+      MODE="${2:?--mode requires an argument: fresh|improve}"
+      shift 2
+      ;;
+    --mode=*)
+      MODE="${1#--mode=}"
+      shift
+      ;;
+    *)
+      OBJECTIVE="$1"
+      shift
+      ;;
+  esac
+done
+
 ROOT="${ROOT:-$PWD}"
 DESK="$ROOT/.claude/ralph-desk"
 RUNNER_DIR="$(cd "$(dirname "$0")" && pwd)"
 
+# --- Re-execution versioning helpers ---
+# Handles ONLY debug.log and campaign-report.md versioning.
+# SV reports use their own -NNN auto-increment pattern and are NOT handled here.
+
+detect_next_version() {
+  local file_path="$1"
+  local dir base ext n=1
+  dir="$(dirname "$file_path")"
+  base="$(basename "$file_path")"
+  if [[ "$base" == *.* ]]; then
+    ext=".${base##*.}"
+    base="${base%.*}"
+  else
+    ext=""
+  fi
+  while [[ -f "$dir/${base}-v${n}${ext}" ]]; do
+    (( n++ ))
+  done
+  echo "$n"
+}
+
+version_file() {
+  local file_path="$1"
+  if [[ -f "$file_path" ]]; then
+    local n dir base ext
+    n="$(detect_next_version "$file_path")"
+    dir="$(dirname "$file_path")"
+    base="$(basename "$file_path")"
+    if [[ "$base" == *.* ]]; then
+      ext=".${base##*.}"
+      base="${base%.*}"
+    else
+      ext=""
+    fi
+    mv "$file_path" "$dir/${base}-v${n}${ext}"
+    echo "  Versioned: $(basename "$file_path") → ${base}-v${n}${ext}"
+  fi
+  # Non-existent files silently skipped (no error)
+}
+
 echo "Initializing Ralph Desk: $SLUG"
 echo "  Root: $ROOT"
 echo "  Desk: $DESK"
+[[ -n "$MODE" ]] && echo "  Mode: $MODE"
 echo ""
 
 mkdir -p "$DESK/prompts" "$DESK/context" "$DESK/memos" "$DESK/plans" "$DESK/logs/$SLUG"
 
+# --- Re-execution lifecycle (--mode handling) ---
+PRD_FILE="$DESK/plans/prd-$SLUG.md"
+LOGS_DIR="$DESK/logs/$SLUG"
+
+if [[ -n "$MODE" ]] && [[ -f "$PRD_FILE" ]]; then
+  echo "Re-execution mode: --mode $MODE"
+  echo ""
+
+  DELETED_COUNT=0
+
+  # Version debug.log and campaign-report.md (NOT self-verification-report — uses -NNN)
+  version_file "$LOGS_DIR/debug.log"
+  version_file "$LOGS_DIR/campaign-report.md"
+
+  # Delete iter-* artifacts (archived done-claims, verdicts, prompt logs, results)
+  for f in "$LOGS_DIR"/iter-*(N); do
+    [[ -f "$f" ]] && { rm "$f"; (( ++DELETED_COUNT )); }
+  done
+
+  # Delete runtime memos
+  for f in \
+    "$DESK/memos/$SLUG-done-claim.json" \
+    "$DESK/memos/$SLUG-iter-signal.json" \
+    "$DESK/memos/$SLUG-verify-verdict.json" \
+    "$DESK/memos/$SLUG-complete.md" \
+    "$DESK/memos/$SLUG-blocked.md"; do
+    [[ -f "$f" ]] && { rm "$f"; (( ++DELETED_COUNT )); }
+  done
+
+  # Delete status.json, baseline.log, cost-log.jsonl
+  for f in "$LOGS_DIR/status.json" "$LOGS_DIR/baseline.log" "$LOGS_DIR/cost-log.jsonl"; do
+    [[ -f "$f" ]] && { rm "$f"; (( ++DELETED_COUNT )); }
+  done
+
+  # Delete test-spec and current slug's prompts (will be regenerated below)
+  for f in \
+    "$DESK/plans/test-spec-$SLUG.md" \
+    "$DESK/prompts/$SLUG.worker.prompt.md" \
+    "$DESK/prompts/$SLUG.verifier.prompt.md"; do
+    [[ -f "$f" ]] && { rm "$f"; (( ++DELETED_COUNT )); }
+  done
+
+  # Reset memory and context to fresh templates (rm here; scaffold below regenerates them)
+  rm -f "$DESK/memos/$SLUG-memory.md" "$DESK/context/$SLUG-latest.md"
+
+  # PRD handling: --mode fresh deletes PRD; --mode improve preserves PRD in-place
+  if [[ "$MODE" == "fresh" ]]; then
+    [[ -f "$PRD_FILE" ]] && { rm "$PRD_FILE"; (( ++DELETED_COUNT )); echo "  Deleted: prd-$SLUG.md (--mode fresh: PRD deleted for fresh start)"; }
+  fi
+
+  # Re-execution summary
+  echo "  Re-execution summary:"
+  if [[ "$MODE" == "improve" ]]; then
+    echo "  Preserved: prd-$SLUG.md (--mode improve: PRD kept in-place)"
+  fi
+  echo "  Deleted:   $DELETED_COUNT runtime artifacts"
+  echo "  Reset:     memory.md + context.md (regenerating from templates)"
+  echo ""
+
+elif [[ -n "$MODE" ]] && [[ ! -f "$PRD_FILE" ]]; then
+  # Note: --mode provided but no PRD found for this slug — treating as first run
+  echo "  Note: --mode $MODE provided but no PRD found for '$SLUG' — treating as first run."
+  echo ""
+  MODE=""
+fi
+
 # --- Worker Prompt ---
 F="$DESK/prompts/$SLUG.worker.prompt.md"
 if [[ ! -f "$F" ]]; then
@@ -64,6 +192,7 @@ Read these files in order:
 - Do not say "I'm confident" — confidence is not evidence.
 - Do not say "existing code has no tests" — you are improving it, add tests.
 - Do not write code before tests — if you did, delete it and start with tests.
+- **NEVER modify rlp-desk infrastructure files** (~/.claude/ralph-desk/*, ~/.claude/commands/rlp-desk.md). If you discover a bug in rlp-desk itself, report it in done-claim.json with {"status": "blocked", "reason": "rlp-desk bug: <description>"} and signal blocked. Do NOT attempt to fix rlp-desk — it is the orchestration tool, not your project code.
 
 ## Iteration rules
 - Use fresh context only; do NOT depend on prior chat history.
@@ -169,6 +298,11 @@ Check the iter-signal.json "us_id" field:
    - Test-specific logic: no environment-detection patterns
    - "Code inspection" claims: Worker must run actual commands
    - Tautological tests: expected values that mirror implementation logic
+10½. **Worker Process Audit**:
+   - Test-first compliance: done-claim execution_steps must show write_test step before implement step for each AC
+   - RED phase evidence: at least one verify_red step with exit_code=1 per AC (proves tests were written before passing)
+   - Forbidden shortcuts: check done-claim claims and summary for forbidden phrases ("code inspection", "I'm confident", "too simple", "already manually tested", "partial check")
+   - Step completeness: each AC should have write_test → verify_red → implement → verify_green sequence in execution_steps
 11. **Reproducibility check**: verify lock file committed, clean install succeeds, security scan passes, env vars documented (per test-spec Reproducibility Gate). Skip if test-spec says "N/A."
 12. Write verdict JSON to: $DESK/memos/$SLUG-verify-verdict.json
 
@@ -185,7 +319,8 @@ Verdict JSON:
     {"check": "IL-1 Evidence Gate", "decision": "pass|fail", "basis": "what command was run, what output confirmed the decision"},
     {"check": "Layer Enforcement", "decision": "pass|fail", "basis": "which layers checked, any TODO found"},
     {"check": "Test Sufficiency", "decision": "pass|fail", "basis": "test count per AC, category coverage"},
-    {"check": "Anti-Gaming", "decision": "pass|fail", "basis": "what was checked, any suspicious patterns"}
+    {"check": "Anti-Gaming", "decision": "pass|fail", "basis": "what was checked, any suspicious patterns"},
+    {"check": "Worker Process Audit", "decision": "pass|fail", "basis": "test-first followed: verify_red present per AC, no forbidden shortcuts in claims, execution_steps complete"}
   ],
   "layer_status": {"L1":"pass|fail|todo|na","L2":"pass|fail|todo|na","L3":"pass|fail|todo|na","L4":"pass|fail|todo|na"},
   "test_quality": {"test_count":0,"ac_count":0,"sufficiency":"pass|fail","anti_patterns_found":[]},