@ai-dev-methodologies/rlp-desk 0.7.4 → 0.8.0

package/README.md

@@ -399,6 +399,64 @@ Per-US catches issues early before later stories build on broken foundations.
 
 Worker completes all stories, then a single verification checks all AC at once. Final verify still applies.
 
+## Autonomous Mode
+
+By default, Worker and Verifier stop and ask for human input when they encounter document conflicts (e.g., PRD says one thing, test-spec says another) or ambiguous instructions. This breaks unattended execution.
+
+**`--autonomous`** enables fully unattended campaigns:
+
+```bash
+/rlp-desk run my-feature --mode tmux --worker-model gpt-5.4:medium --autonomous --debug
+```
+
+### How it works
+
+When `--autonomous` is active:
+
+1. **PRD is the single source of truth.** Resolution priority: `PRD > test-spec > context > memory`
+2. **No stopping for questions.** Worker and Verifier make autonomous decisions based on the priority chain
+3. **All conflicts are logged.** Every decision is recorded in `conflict-log.jsonl` for post-campaign review
+
+### Conflict log
+
+Each conflict is logged as a JSONL entry in `logs/<slug>/conflict-log.jsonl`:
+
+```json
+{
+  "iteration": 1,
+  "us_id": "US-001",
+  "source_a": "worker-prompt",
+  "source_b": "prd",
+  "conflict": "US-00 is required by the iteration prompt but is not defined as a PRD user story.",
+  "resolution": "Followed PRD as source of truth."
+}
+```
+
+### When to use
+
+- **Long-running campaigns** that run overnight or while you're away
+- **High-iteration tasks** where stopping for every ambiguity wastes hours
+- **Well-defined PRDs** where the PRD is comprehensive and authoritative
+
+### When NOT to use
+
+- **Exploratory work** where you want to review each decision
+- **Ambiguous PRDs** where conflicts indicate real design gaps that need human judgment
+- **First run of a new project** — run without `--autonomous` first to catch PRD issues interactively
+
+### Post-campaign review
+
+After the campaign, review the conflict log to identify systemic issues:
+
+```bash
+cat .claude/ralph-desk/logs/<slug>/conflict-log.jsonl | jq .
+```
+
+Common patterns:
+- **Repeated PRD vs test-spec conflicts** — test-spec needs updating to match PRD
+- **Scope lock vs fix contract conflicts** — governance rules may need tuning
+- **Missing PRD definitions** — Worker created stories not in the PRD (add them or tighten the brainstorm)
+
 ## Project Structure
 
 After `init`, your project gets this scaffold:

package/docs/blueprints/blueprint-pivot-step.md

@@ -0,0 +1,137 @@
+# Blueprint: Pivot Step (⑤½)
+
+> Status: TODO — not yet implemented. Document for future development.
+
+## Summary
+
+Insert a Pivot Review step between Worker(⑤) and Verifier(⑦) in the Leader loop. Internalizes the core thinking framework from gstack's `plan-ceo-review` (premise challenge, forced alternatives, scope decisions) without depending on external skills.
+
+## Problem
+
+When a Worker repeatedly fails on the same US, the fix loop retries the same approach with progressively stronger models. This works for implementation bugs but fails for **wrong approach** problems. The current CB threshold → BLOCKED pattern wastes iterations before admitting the approach is wrong.
+
+## Proposed Solution
+
+### New CLI Flags
+
+```
+--pivot-mode off|every|on-fail    (default: off)
+--pivot-model MODEL               (default: opus)
+```
+
+- `off`: no pivot review (current behavior)
+- `every`: pivot review after every Worker iteration
+- `on-fail`: pivot review only after Verifier fail verdict
+
+### Leader Loop Change
+
+```
+Current:  ① → ② → ③ → ④ → ⑤ worker → ⑥ signal → ⑦ verifier → ⑧ result
+Proposed: ① → ② → ③ → ③½ PIVOT → ④ → ⑤ worker → ⑥ signal → ⑦ verifier → ⑧ result
+```
+
+Pivot runs BEFORE Worker — it decides direction, then Worker executes that direction.
+
+### Tmux Pane Layout (3 panes)
+
+```
++------------------+------------------+------------------+
+| Worker pane      | Pivot pane       | Verifier pane    |
+| claude/codex     | claude (opus)    | claude/codex     |
+| implements code  | direction review | verifies result  |
++------------------+------------------+------------------+
+```
+
+Pivot pane is reused each iteration (not persistent). Leader launches pivot → waits for memory update → launches Worker in Worker pane.
+
+### ③½ Pivot Review Step
+
+**Agent mode:**
+```
+Agent(
+  description="rlp-desk pivot review iter-NNN",
+  model=<pivot_model>,
+  mode="bypassPermissions",
+  prompt=<pivot_prompt>
+)
+```
+
+**Tmux mode:**
+- Dedicated pivot pane (3rd pane)
+- `DISABLE_OMC=1 claude --model opus --mcp-config '{"mcpServers":{}}' --strict-mcp-config -p "$(cat pivot-prompt.md)"`
+- After pivot completes, verify memory updated → build Worker prompt (④) → launch Worker (⑤)
+
+### Pivot Review Responsibilities
+
+1. **Analyze iteration result** — what did the Worker actually produce?
+2. **Premise challenge** — is the current approach correct? What assumptions are we making?
+3. **Forced alternatives** — propose minimum 2 alternative approaches
+4. **Scope decision** — EXPAND (add scope), HOLD (keep current), REDUCE (simplify)
+5. **Update campaign memory** — rewrite Next Iteration Contract if approach changes
+6. **Record rejected directions** — prevent future iterations from revisiting dead ends
+
+### Pivot Prompt Template (internalized from plan-ceo-review)
+
+```markdown
+# Pivot Review — Iteration {N}
+
+## Context
+- Campaign: {slug}
+- Current US: {us_id}
+- Worker result: {done-claim summary}
+- Consecutive failures on this US: {N}
+- Previous pivot decisions: {from memory}
+
+## Your Task
+
+### 1. Premise Check
+For each premise below, state whether evidence supports or contradicts it:
+{list premises from PRD/memory}
+
+### 2. Forced Alternatives
+Propose at least 2 alternative approaches to the current US.
+For each: summary, effort (S/M/L), risk, key tradeoff.
+
+### 3. Scope Decision
+Choose ONE: EXPAND | HOLD | REDUCE
+Justify with evidence from this iteration.
+
+### 4. Next Iteration Contract
+If HOLD: refine the current contract with specific fixes.
+If EXPAND/REDUCE: rewrite the contract for the new approach.
+
+### 5. Rejected Directions
+List approaches that should NOT be attempted again, with reason.
+
+## Output
+Update campaign memory at: {memory_path}
+- Update "Next Iteration Contract" section
+- Add to "Key Decisions" section
+- Add to "Rejected Directions" section (if any)
+```
+
+## Expected Benefits
+
+- **Breaks fix loops** — "same approach, stronger model" → "different approach"
+- **Research campaigns** — natural direction pivots without manual intervention
+- **Reuses proven framework** — plan-ceo-review's premise challenge + forced alternatives
+- **Both modes** — works in tmux and agent mode
+
+## Implementation Notes
+
+- `PIVOT_MODE` variable in `run_ralph_desk.zsh` (pattern: same as `AUTONOMOUS_MODE`)
+- CLI parser: `--pivot-mode`, `--pivot-model` (pattern: same as other model flags)
+- `write_pivot_prompt()` function in `run_ralph_desk.zsh` (pattern: same as `write_worker_trigger`)
+- Pivot review output → campaign memory update (same file, different section)
+- Status.json: add `pivot_decisions` array for tracking
+- Analytics: `campaign.jsonl` add `pivot_action` field per iteration
+
+## Dependencies
+
+- Requires `--autonomous` mode (pivot review must not stop for questions)
+- Works with any Worker engine (Claude or Codex)
+- Does not require gstack installation
+
+## Priority
+
+Medium — implement after v1.0 Node.js rewrite is stable. Current CB threshold + model upgrade handles most cases. Pivot step is for research/exploration campaigns where approach flexibility matters.

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@ai-dev-methodologies/rlp-desk",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "uninstall": "node scripts/uninstall.js"
   },
   "files": [
-    "src/",
+    "src/commands/",
+    "src/node/",
+    "src/governance.md",
+    "src/model-upgrade-table.md",
     "scripts/",
     "docs/",
     "examples/",

package/scripts/postinstall.js

@@ -4,41 +4,19 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execSync } = require("child_process");
+const pkg = require(path.join(__dirname, "..", "package.json"));
 
 const home = os.homedir();
 const claudeDir = path.join(home, ".claude");
 const commandsDir = path.join(claudeDir, "commands");
 const deskDir = path.join(claudeDir, "ralph-desk");
-const pkgDir = path.join(__dirname, "..");
-const pkg = require(path.join(pkgDir, "package.json"));
-
-console.log("");
-console.log("  RLP Desk v" + pkg.version);
-console.log("  ================");
-console.log("");
-
-// Create directories
-fs.mkdirSync(commandsDir, { recursive: true });
-fs.mkdirSync(deskDir, { recursive: true });
-
-// Create docs subdirectories
 const docsDir = path.join(deskDir, "docs");
-const docsInternalDir = path.join(docsDir, "internal");
-const docsBlueprintsDir = path.join(docsDir, "blueprints");
-fs.mkdirSync(docsInternalDir, { recursive: true });
-fs.mkdirSync(docsBlueprintsDir, { recursive: true });
-
-// Copy files — must match CLAUDE.md "Local File Sync" section exactly
-const copies = [
-  // Runtime files
+const nodeDir = path.join(deskDir, "node");
+const pkgDir = path.join(__dirname, "..");
+const runtimeSources = [
   ["src/commands/rlp-desk.md", path.join(commandsDir, "rlp-desk.md")],
   ["src/governance.md", path.join(deskDir, "governance.md")],
   ["src/model-upgrade-table.md", path.join(deskDir, "model-upgrade-table.md")],
-  ["src/scripts/init_ralph_desk.zsh", path.join(deskDir, "init_ralph_desk.zsh")],
-  ["src/scripts/run_ralph_desk.zsh", path.join(deskDir, "run_ralph_desk.zsh")],
-  ["src/scripts/lib_ralph_desk.zsh", path.join(deskDir, "lib_ralph_desk.zsh")],
-  // Reference docs
   ["README.md", path.join(deskDir, "README.md")],
   ["install.sh", path.join(deskDir, "install.sh")],
   ["docs/architecture.md", path.join(docsDir, "architecture.md")],
@@ -46,42 +24,104 @@ const copies = [
   ["docs/protocol-reference.md", path.join(docsDir, "protocol-reference.md")],
   ["docs/TODO-verification-next.md", path.join(docsDir, "TODO-verification-next.md")],
 ];
+const legacyFiles = [
+  path.join(deskDir, "init_ralph_desk.zsh"),
+  path.join(deskDir, "run_ralph_desk.zsh"),
+  path.join(deskDir, "lib_ralph_desk.zsh"),
+];
+
+function getNodeVersion() {
+  return process.env.RLP_DESK_NODE_VERSION_OVERRIDE || process.version;
+}
+
+function isSupportedNodeVersion(version) {
+  const match = /^v(\d+)/.exec(version || "");
+  return Boolean(match) && Number(match[1]) >= 16;
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function removePath(targetPath) {
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+function copyFile(sourceRelativePath, targetPath) {
+  ensureDir(path.dirname(targetPath));
+  fs.copyFileSync(path.join(pkgDir, sourceRelativePath), targetPath);
+  console.log("  + " + targetPath);
+}
+
+function copyMarkdownDirectory(sourceRelativeDir, targetDir) {
+  const sourceDir = path.join(pkgDir, sourceRelativeDir);
+  if (!fs.existsSync(sourceDir)) {
+    return;
+  }
 
-// Copy docs/internal/* and docs/blueprints/* if they exist
-for (const subdir of [["docs/internal", docsInternalDir], ["docs/blueprints", docsBlueprintsDir]]) {
-  const srcDir = path.join(pkgDir, subdir[0]);
-  if (fs.existsSync(srcDir)) {
-    for (const file of fs.readdirSync(srcDir)) {
-      if (file.endsWith(".md")) {
-        copies.push([path.join(subdir[0], file), path.join(subdir[1], file)]);
-      }
+  ensureDir(targetDir);
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyMarkdownDirectory(path.join(sourceRelativeDir, entry.name), targetPath);
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      ensureDir(path.dirname(targetPath));
+      fs.copyFileSync(sourcePath, targetPath);
+      console.log("  + " + targetPath);
     }
   }
 }
 
-for (const [src, dest] of copies) {
-  fs.copyFileSync(path.join(pkgDir, src), dest);
-  console.log("  + " + dest);
-}
+function copyNodeRuntime(sourceDir, targetDir) {
+  removePath(targetDir);
+  ensureDir(targetDir);
 
-// Make scripts executable
-try {
-  fs.chmodSync(path.join(deskDir, "init_ralph_desk.zsh"), 0o755);
-  fs.chmodSync(path.join(deskDir, "run_ralph_desk.zsh"), 0o755);
-  fs.chmodSync(path.join(deskDir, "lib_ralph_desk.zsh"), 0o755);
-} catch (_) {
-  // chmod may fail on Windows — not critical
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyNodeRuntime(sourcePath, targetPath);
+      continue;
+    }
+    if (entry.isFile()) {
+      ensureDir(path.dirname(targetPath));
+      fs.copyFileSync(sourcePath, targetPath);
+      console.log("  + " + targetPath);
+    }
+  }
 }
 
-// Check tmux availability
-try {
-  execSync("which tmux", { stdio: "ignore" });
-} catch (_) {
-  console.log("  [warn] tmux not found. Tmux execution mode (--mode tmux) will not be available.");
-  console.log("         Install tmux to use lean mode: https://github.com/tmux/tmux/wiki/Installing");
+console.log("");
+console.log("  RLP Desk v" + pkg.version);
+console.log("  ================");
+console.log("");
+
+if (!isSupportedNodeVersion(getNodeVersion())) {
+  console.log("  [warn] RLP Desk requires Node.js >= 16 for the Node rewrite runtime.");
+  console.log("         Existing zsh installation was left unchanged.");
   console.log("");
+  process.exit(0);
 }
 
+ensureDir(commandsDir);
+ensureDir(deskDir);
+ensureDir(docsDir);
+
+for (const legacyFile of legacyFiles) {
+  removePath(legacyFile);
+}
+
+for (const [sourcePath, targetPath] of runtimeSources) {
+  copyFile(sourcePath, targetPath);
+}
+
+copyMarkdownDirectory("docs/internal", path.join(docsDir, "internal"));
+copyMarkdownDirectory("docs/blueprints", path.join(docsDir, "blueprints"));
+copyNodeRuntime(path.join(pkgDir, "src", "node"), nodeDir);
+
 console.log("");
 console.log("  Done! Open Claude Code and run:");
 console.log("    /rlp-desk brainstorm \"your task description\"");

package/scripts/uninstall.js

@@ -16,22 +16,31 @@ console.log("");
 
 const files = [
   path.join(commandsDir, "rlp-desk.md"),
-  path.join(deskDir, "init_ralph_desk.zsh"),
-  path.join(deskDir, "run_ralph_desk.zsh"),
-  path.join(deskDir, "lib_ralph_desk.zsh"),
   path.join(deskDir, "governance.md"),
+  path.join(deskDir, "model-upgrade-table.md"),
+  path.join(deskDir, "README.md"),
+  path.join(deskDir, "install.sh"),
 ];
 
-for (const f of files) {
+for (const targetPath of files) {
   try {
-    fs.unlinkSync(f);
-    console.log("  - " + f);
+    fs.rmSync(targetPath, { recursive: true, force: true });
+    console.log("  - " + targetPath);
   } catch (_) {
-    // File may not exist
+    // Ignore missing files.
+  }
+}
+
+for (const subdir of ["docs", "node"]) {
+  const targetPath = path.join(deskDir, subdir);
+  try {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+    console.log("  - " + targetPath);
+  } catch (_) {
+    // Ignore missing directories.
   }
 }
 
-// Remove ralph-desk dir if empty
 try {
   const remaining = fs.readdirSync(deskDir);
   if (remaining.length === 0) {
@@ -39,7 +48,7 @@ try {
     console.log("  - " + deskDir);
   }
 } catch (_) {
-  // Directory may not exist
+  // Directory may not exist.
 }
 
 console.log("");

package/src/commands/rlp-desk.md

@@ -372,7 +372,6 @@ If claude engine (default):
 ```
 Agent(
   description="rlp-desk worker iter-NNN",
-  subagent_type="executor",
   model=<worker_model>,
   mode="bypassPermissions",
   prompt=<full worker prompt text>
@@ -433,7 +432,6 @@ If claude engine (default):
 ```
 Agent(
   description="rlp-desk verifier iter-NNN (us_id)",
-  subagent_type="executor",
   model=<selected_verifier_model>,
   mode="bypassPermissions",
   prompt=<full verifier prompt text with US scope>

package/src/governance.md

@@ -267,6 +267,7 @@ Verifier records WHY each judgment was made in `verify-verdict.json`:
 - Runs commands directly to collect fresh evidence
 - Campaign Memory is for orientation only — not the source of truth
 - Writes verdict (`pass` | `fail` | `request_info`) — if uncertain, use `request_info` with specific questions; Leader decides
+- **Verdict output rule**: MUST write verdict JSON as a FILE (not stdout). Leader polls the file path — terminal output is lost. Evidence strings: include key metrics and exit codes only, do NOT quote full command output or logs verbatim.
 - Delegates deterministic checks (type hints, linting, security) to tools defined in test-spec
 - Focuses on AC verification, semantic review, and smoke tests
 - **Must NEVER modify code or write sentinel files**

package/src/node/cli/command-builder.mjs

@@ -0,0 +1,96 @@
+const CLAUDE_BIN = 'claude';
+const CODEX_BIN = 'codex';
+const CLAUDE_MODELS = new Set(['haiku', 'sonnet', 'opus']);
+
+function assertTuiMode(mode, builderName) {
+  if (mode !== 'tui') {
+    throw new Error(`${builderName} unknown mode '${mode}'`);
+  }
+}
+
+export function buildClaudeCmd(mode, model, options = {}) {
+  assertTuiMode(mode, 'buildClaudeCmd');
+
+  const parts = [
+    'DISABLE_OMC=1',
+    CLAUDE_BIN,
+    '--model',
+    model,
+    '--mcp-config',
+    '\'{"mcpServers":{}}\'',
+    '--strict-mcp-config',
+    '--dangerously-skip-permissions',
+  ];
+
+  if (options.effort !== undefined && options.effort !== '') {
+    parts.push('--effort', options.effort);
+  }
+
+  return parts.join(' ');
+}
+
+export function buildCodexCmd(mode, model, options = {}) {
+  assertTuiMode(mode, 'buildCodexCmd');
+
+  const parts = [
+    CODEX_BIN,
+    '-m',
+    model,
+  ];
+
+  if (options.reasoning !== undefined) {
+    parts.push('-c', `model_reasoning_effort="${options.reasoning}"`);
+  }
+
+  parts.push('--disable', 'plugins', '--dangerously-bypass-approvals-and-sandbox');
+
+  return parts.join(' ');
+}
+
+export function parseModelFlag(value, role = 'worker') {
+  const colonCount = [...value].filter((character) => character === ':').length;
+
+  if (colonCount > 1) {
+    throw new Error(
+      `invalid format for --${role}-model '${value}'. Use 'model:effort' (claude) or 'model:reasoning' (codex).`,
+    );
+  }
+
+  if (colonCount === 0) {
+    if (!value) {
+      throw new Error(`--${role}-model model is required`);
+    }
+
+    return {
+      engine: 'claude',
+      model: value,
+    };
+  }
+
+  const [model, level] = value.split(':');
+  if (!model) {
+    throw new Error(`--${role}-model model is required`);
+  }
+
+  if (CLAUDE_MODELS.has(model)) {
+    return {
+      engine: 'claude',
+      model,
+      effort: level,
+    };
+  }
+
+  if (model === 'spark') {
+    return {
+      engine: 'codex',
+      model: 'gpt-5.3-codex-spark',
+      reasoning: level,
+    };
+  }
+
+  return {
+    engine: 'codex',
+    model,
+    reasoning: level,
+  };
+}