@ai-dev-methodologies/rlp-desk 0.3.1 → 0.3.3

package/package.json

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

package/src/commands/rlp-desk.md

@@ -79,19 +79,35 @@ 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. Show the run command with available options:
+3. Present run options with explanations and ONE recommendation. The user MUST copy and paste the command themselves:
+
 ```
-/rlp-desk run <slug> [options]
-
-Options:
-  --mode agent|tmux
-  --worker-engine claude|codex
-  --verifier-engine claude|codex
-  --verify-mode per-us|batch
-  --verify-consensus
-  --consensus-scope all|final-only
+Available run commands (copy the one you want):
+
+# Recommended for most cases — agent mode, per-US verification, debug logging:
+/rlp-desk run <slug> --debug
+
+# With self-verification campaign report (recommended for MEDIUM+ risk):
+/rlp-desk run <slug> --debug --with-self-verification
+
+# Tmux mode for long campaigns with real-time visibility:
+/rlp-desk run <slug> --mode tmux --debug
+
+# Cross-engine consensus (requires codex CLI installed):
+/rlp-desk run <slug> --debug --verify-consensus
+
+# 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)
 ```
-4. Wait for the user to explicitly invoke `/rlp-desk run`
+
+**CRITICAL: Do NOT offer to run for the user. Do NOT ask "실행할까요?" or "shall I run?". The user MUST type the run command themselves. Just present the options, recommend one, and STOP.**
 
 ---
 
@@ -165,11 +181,18 @@ DEBUG=<1 if --debug, else 0> \
 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. If `--debug`: 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")`.
+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.
 
 ### 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.
+**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.
+
+**PLATFORM CONSTRAINT (Agent mode):** In Agent mode, the Leader is an LLM in Claude Code's turn-based model. A turn ENDS when the response contains no tool calls. This means:
+- **NEVER output plain text without an accompanying tool call.** Text-only output = turn ends = loop stops.
+- **Use `Bash("echo '...'")` for all status reports** instead of plain text. This keeps the tool-call chain alive.
+- **After every step result, IMMEDIATELY start the next step's tool call in the SAME response.** For example, after reading the verdict (⑦c), report via Bash("echo") AND start ⑧'s tool calls in one response.
+- If you output "Iter 1 complete, moving to iter 2" as plain text without a tool call, the turn terminates and the loop breaks. This is a platform constraint, not a compliance issue — no amount of "DO NOT STOP" text can override it.
 
 If `--debug`, at loop start debug_log: `[PLAN] slug=<slug> max_iter=<N> worker_engine=<engine> worker_model=<model> verifier_engine=<engine> verifier_model=<model> verify_mode=<mode> consensus=<0|1> consensus_scope=<scope>`
 
@@ -198,11 +221,14 @@ rm -f .claude/ralph-desk/memos/<slug>-verify-verdict.json
 - User specified → use that
 - If `--debug`: debug_log `[EXEC] iter=N phase=model_select worker_model=<model> reason=<reason>`
 
-**④ Build worker prompt**
-- Read `.claude/ralph-desk/prompts/<slug>.worker.prompt.md`
-- Combine with iteration number + memory contract
-- Write to `.claude/ralph-desk/logs/<slug>/iter-NNN.worker-prompt.md` (audit trail)
+**④ 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.
+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).
 - Note: Worker ALWAYS records execution_steps in done-claim.json per governance §1f. No flag needed.
+- **Rewriting paths from absolute to relative WILL break worktree campaigns. Only additions (WORKING_DIR header, iteration context) are allowed.**
 
 **④½ Contract review** (agent mode only)
 - Before dispatching Worker, spawn a lightweight review: "Is this iteration contract sufficient to achieve the US's AC? Any missing steps?"
@@ -241,6 +267,8 @@ Bash("codex exec --model <worker_codex_model> --reasoning-effort <worker_codex_r
 - Also read `iter-signal.json` for `us_id` field (which US was just completed)
 - If `--debug`: debug_log `[EXEC] iter=N phase=worker_signal status=<stop_status> us_id=<us_id>`
 
+**CRITICAL: Immediately proceed to ⑦. Do NOT pause, do NOT ask the user, do NOT wait for confirmation. The loop is autonomous.**
+
 **⑦ Execute Verifier**
 
 **Per-US mode** (default, `--verify-mode per-us`):
@@ -262,6 +290,7 @@ Bash("codex exec --model <worker_codex_model> --reasoning-effort <worker_codex_r
 
 **⑦a Dispatch Verifier**
 - Note: Verifier ALWAYS records reasoning in verify-verdict.json per governance §1f. No flag needed.
+- **Prompt Assembly Protocol (same as ④)**: Read verifier prompt file verbatim. Prepend `## WORKING_DIR: {absolute path}`. Do NOT rewrite paths.
 - If `--debug`: debug_log `[EXEC] iter=N phase=verifier engine=<engine> model=<model> scope=<us_id> dispatched=true`
 
 If `--verifier-engine claude` (default):
@@ -309,13 +338,16 @@ After the primary verifier runs, run a second verifier with the OTHER engine:
 - If `--debug`: debug_log `[EXEC] iter=N phase=checkpoint level=<1|2> evidence=<summary>`
 - If `--debug` and consensus: debug_log `[EXEC] iter=N phase=consensus claude=<verdict> codex=<verdict> round=<N>`
 
+**CRITICAL: Immediately proceed to ⑧. Do NOT pause, do NOT ask the user. Continue the 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
+- 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>`
 - If `--debug`: debug_log `[EXEC] iter=N phase=result status=<result> consecutive_failures=<N> verified_us=<list>`
 
 At loop end (COMPLETE, BLOCKED, or TIMEOUT):
@@ -346,7 +378,7 @@ Per failure: Worker steps → Verifier reasoning → Root cause → Resolution
 ## 3. Worker Process Quality (§1f audit)
 Table: Iter | US | Steps | verify_red? | RED exit≠0? | verify_green? | Test-First? | E2E? | AC linked?
 Aggregate: TDD compliance %, RED confirmation %, E2E evidence %, step completeness %
-Audit: each step must have type from §1f vocabulary + ac_id + command + exit_code
+Audit: each step object must have "step" field with value from §1f vocabulary (write_test, verify_red, implement, verify_green, refactor, verify_e2e, commit, verify) + ac_id + command + exit_code
 
 ## 4. Verifier Judgment Quality (§1f audit)
 Table: Iter | US | Checks | All Basis? | Independent? | IL-1? | Layer? | Sufficiency? | Anti-Gaming? | Worker Audit?

package/src/scripts/init_ralph_desk.zsh

@@ -472,6 +472,27 @@ GIEOF
   echo "  + .gitignore (created with rlp-desk rules)"
 fi
 
+# --- Post-init validation gate ---
+INIT_FAIL=0
+for REQUIRED_FILE in \
+  "$DESK/prompts/$SLUG.worker.prompt.md" \
+  "$DESK/prompts/$SLUG.verifier.prompt.md" \
+  "$DESK/context/$SLUG-latest.md" \
+  "$DESK/memos/$SLUG-memory.md" \
+  "$DESK/plans/prd-$SLUG.md" \
+  "$DESK/plans/test-spec-$SLUG.md"; do
+  if [[ ! -f "$REQUIRED_FILE" ]]; then
+    echo "  ✗ MISSING: $REQUIRED_FILE"
+    INIT_FAIL=1
+  fi
+done
+if [[ $INIT_FAIL -eq 1 ]]; then
+  echo ""
+  echo "ERROR: Scaffold incomplete. Some required files were not created."
+  echo "Re-run init or check filesystem permissions."
+  exit 1
+fi
+
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "Scaffold ready: $SLUG"