@ai-dev-methodologies/rlp-desk 0.7.5 → 0.9.0

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

@@ -23,6 +23,12 @@ Present your suggestion, then wait for the user's confirmation or change.
 Ask about these items one by one (or in small groups):
 1. **Slug** — short identifier (e.g., `auth-refactor`). Suggest one, ask if OK.
 2. **Objective** — what the loop achieves
+2.5. **Codebase Exploration** — Before proposing user stories, examine the project:
+   - Read the project's entry points, key modules, and test structure
+   - Identify architectural patterns in use (frameworks, conventions, test setup)
+   - Note constraints the Worker will encounter (dependencies, build system, existing code style)
+   - Present findings: "I explored the codebase and found: [patterns], [constraints], [existing tests]. This informs the US breakdown below."
+   - If the project is new/empty, skip this step and note "greenfield project."
 3. **User Stories** — discrete units with testable acceptance criteria. Propose a breakdown, ask the user to confirm/modify.
    - Apply INVEST criteria: each US must be Independent, Negotiable, Valuable, Estimable, Small, Testable.
    - **Task Sizing (governance §1c)**: Size each US within the Worker's comfortable zone — smaller than what the Worker can handle, not at its ceiling. Max 3-4 ACs, max 2 files. If a US feels "just barely doable" for the target model, split it further.
@@ -128,7 +134,10 @@ Do NOT auto-decide iteration unit — the user MUST explicitly choose.
 ## `init <slug> [objective]`
 
 Run: `~/.claude/ralph-desk/init_ralph_desk.zsh <slug> "<objective>" [--mode fresh|improve]`
-If brainstorm was done, auto-fill PRD and test-spec with the results.
+If brainstorm was done, auto-fill:
+- PRD and test-spec with the brainstorm results
+- Campaign memory "Key Decisions" with architectural decisions from brainstorm
+- Campaign memory "Patterns Discovered" with codebase exploration findings (from step 2.5)
 
 **After init completes, STOP. Do NOT auto-run the loop.**
 
@@ -372,7 +381,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 +441,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

@@ -214,7 +214,7 @@ 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`, `verify_existing`
+- Step types: `plan`, `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.
 
@@ -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,
+  };
+}

package/src/node/init/campaign-initializer.mjs

@@ -0,0 +1,235 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const GITIGNORE_MARKER = '# RLP Desk runtime artifacts';
+const GITIGNORE_RULE = '.claude/ralph-desk/';
+
+export async function initCampaign(slug, objective, options = {}) {
+  const normalizedSlug = normalizeSlug(slug);
+  const normalizedObjective = objective?.trim() || 'TBD - fill in the objective';
+  const mode = options.mode ?? 'agent';
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const tmuxEnv = options.tmuxEnv ?? process.env.TMUX ?? '';
+  const deskRoot = path.join(rootDir, '.claude', 'ralph-desk');
+
+  if (mode === 'tmux' && !tmuxEnv) {
+    throw new Error('tmux required');
+  }
+
+  if (mode === 'fresh') {
+    await fs.rm(deskRoot, { recursive: true, force: true });
+  }
+
+  const paths = buildPaths(rootDir, normalizedSlug);
+  await ensureDirectories(paths);
+  await ensureGitignore(rootDir);
+
+  await writeIfMissing(paths.workerPrompt, buildWorkerPrompt(normalizedSlug, normalizedObjective));
+  await writeIfMissing(paths.verifierPrompt, buildVerifierPrompt(normalizedSlug));
+  await writeIfMissing(paths.contextFile, buildContext(normalizedSlug));
+  await writeIfMissing(paths.memoryFile, buildMemory(normalizedSlug, normalizedObjective));
+
+  const prdContent = options.prdContent ?? buildPrd(normalizedSlug, normalizedObjective);
+  await fs.writeFile(paths.prdFile, prdContent, 'utf8');
+  await writeIfMissing(paths.testSpecFile, buildTestSpec(normalizedSlug));
+  await splitPrdByUs(paths.plansDir, normalizedSlug, prdContent, normalizedObjective);
+
+  return {
+    slug: normalizedSlug,
+    paths,
+  };
+}
+
+export const init = initCampaign;
+
+function normalizeSlug(value) {
+  const slug = (value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (!slug) {
+    throw new Error('slug is required');
+  }
+
+  return slug;
+}
+
+function buildPaths(rootDir, slug) {
+  const deskRoot = path.join(rootDir, '.claude', 'ralph-desk');
+  const promptsDir = path.join(deskRoot, 'prompts');
+  const plansDir = path.join(deskRoot, 'plans');
+  const memosDir = path.join(deskRoot, 'memos');
+  const logsDir = path.join(deskRoot, 'logs');
+  const contextDir = path.join(deskRoot, 'context');
+
+  return {
+    deskRoot,
+    promptsDir,
+    plansDir,
+    memosDir,
+    logsDir,
+    contextDir,
+    workerPrompt: path.join(promptsDir, `${slug}.worker.prompt.md`),
+    verifierPrompt: path.join(promptsDir, `${slug}.verifier.prompt.md`),
+    contextFile: path.join(contextDir, `${slug}-latest.md`),
+    memoryFile: path.join(memosDir, `${slug}-memory.md`),
+    prdFile: path.join(plansDir, `prd-${slug}.md`),
+    testSpecFile: path.join(plansDir, `test-spec-${slug}.md`),
+    campaignLogDir: path.join(logsDir, slug),
+  };
+}
+
+async function ensureDirectories(paths) {
+  await Promise.all(
+    [
+      paths.promptsDir,
+      paths.plansDir,
+      paths.memosDir,
+      paths.logsDir,
+      paths.contextDir,
+      paths.campaignLogDir,
+    ].map((directory) => fs.mkdir(directory, { recursive: true })),
+  );
+}
+
+async function ensureGitignore(rootDir) {
+  const gitignorePath = path.join(rootDir, '.gitignore');
+  let content = '';
+
+  try {
+    content = await fs.readFile(gitignorePath, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  if (content.includes(GITIGNORE_MARKER) && content.includes(GITIGNORE_RULE)) {
+    return;
+  }
+
+  const prefix = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+  const block = `${prefix}${GITIGNORE_MARKER}\n${GITIGNORE_RULE}\n`;
+  await fs.writeFile(gitignorePath, `${content}${block}`, 'utf8');
+}
+
+async function writeIfMissing(targetPath, content) {
+  try {
+    await fs.access(targetPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+    await fs.writeFile(targetPath, content, 'utf8');
+  }
+}
+
+function buildWorkerPrompt(slug, objective) {
+  return `Execute the plan for ${slug}.\n\n## Objective\n${objective}\n`;
+}
+
+function buildVerifierPrompt(slug) {
+  return `Independent verifier for Ralph Desk: ${slug}\n`;
+}
+
+function buildContext(slug) {
+  return `# ${slug} - Latest Context\n`;
+}
+
+function buildMemory(slug, objective) {
+  return `# ${slug} - Campaign Memory\n\n## Stop Status\ncontinue\n\n## Objective\n${objective}\n`;
+}
+
+function buildPrd(slug, objective) {
+  return `# PRD: ${slug}\n\n## Objective\n${objective}\n`;
+}
+
+function buildTestSpec(slug) {
+  return `# Test Specification: ${slug}\n`;
+}
+
+async function splitPrdByUs(plansDir, slug, prdContent, fallbackObjective) {
+  const matches = extractUsSections(prdContent);
+  const objectiveBlock = extractObjectiveBlock(prdContent, fallbackObjective);
+
+  await removeExistingSplitFiles(plansDir, slug);
+
+  await Promise.all(
+    matches.map((section) => {
+      const usId = section.match(/^## (US-\d{3}):/m)?.[1];
+      if (!usId) {
+        return Promise.resolve();
+      }
+
+      const content = `# PRD: ${slug}\n\n${objectiveBlock}\n\n${section}\n`;
+      return fs.writeFile(path.join(plansDir, `prd-${slug}-${usId}.md`), content, 'utf8');
+    }),
+  );
+}
+
+async function removeExistingSplitFiles(plansDir, slug) {
+  const entries = await fs.readdir(plansDir, { withFileTypes: true });
+  const prefix = `prd-${slug}-US-`;
+
+  await Promise.all(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith('.md'))
+      .map((entry) => fs.rm(path.join(plansDir, entry.name), { force: true })),
+  );
+}
+
+function extractObjectiveBlock(prdContent, fallbackObjective) {
+  const lines = prdContent.split(/\r?\n/);
+  const collected = [];
+  let collecting = false;
+
+  for (const line of lines) {
+    if (/^## Objective\s*$/.test(line)) {
+      collecting = true;
+      collected.push('## Objective');
+      continue;
+    }
+
+    if (collecting && /^## US-\d{3}:/.test(line)) {
+      break;
+    }
+
+    if (collecting) {
+      collected.push(line);
+    }
+  }
+
+  const content = collected.join('\n').trim();
+  if (content) {
+    return content;
+  }
+
+  return `## Objective\n${fallbackObjective}`;
+}
+
+function extractUsSections(prdContent) {
+  const lines = prdContent.split(/\r?\n/);
+  const sections = [];
+  let current = [];
+
+  for (const line of lines) {
+    if (/^## US-\d{3}:/.test(line)) {
+      if (current.length > 0) {
+        sections.push(current.join('\n').trim());
+      }
+      current = [line];
+      continue;
+    }
+
+    if (current.length > 0) {
+      current.push(line);
+    }
+  }
+
+  if (current.length > 0) {
+    sections.push(current.join('\n').trim());
+  }
+
+  return sections;
+}