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

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;
+}

package/src/node/polling/signal-poller.mjs

@@ -0,0 +1,106 @@
+import fs from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { setTimeout as delay } from 'node:timers/promises';
+
+const execFileAsync = promisify(execFile);
+const SHELL_COMMANDS = new Set(['', 'zsh', 'bash', 'sh']);
+
+export class TimeoutError extends Error {
+  constructor(message, options = {}) {
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.name = 'TimeoutError';
+  }
+}
+
+async function defaultReadFile(filePath) {
+  return fs.readFile(filePath, 'utf8');
+}
+
+async function defaultGetPaneCommand(paneId) {
+  const { stdout } = await execFileAsync('tmux', [
+    'display-message',
+    '-p',
+    '-t',
+    paneId,
+    '#{pane_current_command}',
+  ]);
+
+  return stdout.trim();
+}
+
+function isMissingFileError(error) {
+  return error?.code === 'ENOENT';
+}
+
+function isJsonParseError(error) {
+  return error instanceof SyntaxError;
+}
+
+function deadlineExceeded(deadline) {
+  return Date.now() >= deadline;
+}
+
+async function waitForPaneExit(paneId, { deadline, pollIntervalMs, getPaneCommand }) {
+  while (!deadlineExceeded(deadline)) {
+    try {
+      const currentCommand = await getPaneCommand(paneId);
+      if (SHELL_COMMANDS.has(currentCommand)) {
+        return;
+      }
+    } catch {
+      // Transient tmux lookup failures should not end the poll loop early.
+    }
+
+    if (deadlineExceeded(deadline)) {
+      break;
+    }
+
+    await delay(pollIntervalMs);
+  }
+
+  throw new TimeoutError(`Timed out waiting for pane ${paneId} to exit after signal detection`);
+}
+
+export async function pollForSignal(
+  signalFile,
+  {
+    mode = 'claude',
+    paneId = null,
+    pollIntervalMs = 100,
+    timeoutMs = 5000,
+    readFile = defaultReadFile,
+    getPaneCommand = defaultGetPaneCommand,
+  } = {},
+) {
+  const deadline = Date.now() + timeoutMs;
+
+  while (!deadlineExceeded(deadline)) {
+    try {
+      const rawContent = await readFile(signalFile);
+      const parsed = JSON.parse(rawContent);
+
+      if (mode === 'codex' && paneId) {
+        await waitForPaneExit(paneId, {
+          deadline,
+          pollIntervalMs,
+          getPaneCommand,
+        });
+      }
+
+      return parsed;
+    } catch (error) {
+      if (!isMissingFileError(error) && !isJsonParseError(error)) {
+        throw error;
+      }
+    }
+
+    if (deadlineExceeded(deadline)) {
+      break;
+    }
+
+    await delay(pollIntervalMs);
+  }
+
+  throw new TimeoutError(`Timed out waiting for valid JSON signal at ${signalFile}`);
+}

package/src/node/prompts/prompt-assembler.mjs

@@ -0,0 +1,213 @@
+import fs from 'node:fs/promises';
+
+export class FileNotFoundError extends Error {
+  constructor(message, filePath, options = {}) {
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.name = 'FileNotFoundError';
+    this.path = filePath;
+  }
+}
+
+async function readRequiredFile(filePath, label) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new FileNotFoundError(`${label} not found: ${filePath}`, filePath, {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}
+
+async function fileExists(filePath) {
+  if (!filePath) {
+    return false;
+  }
+
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readOptionalFile(filePath) {
+  if (!(await fileExists(filePath))) {
+    return null;
+  }
+
+  return fs.readFile(filePath, 'utf8');
+}
+
+function extractSectionValue(content, heading) {
+  if (!content) {
+    return '';
+  }
+
+  const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = content.match(new RegExp(`^## ${escapedHeading}\\s*$([\\s\\S]*?)(?=^## |\\Z)`, 'm'));
+  if (!match) {
+    return '';
+  }
+
+  return match[1]
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+function injectPerUsPrd(basePrompt, fullPrdPath, perUsPrdPath, hasPerUsPrd) {
+  if (!fullPrdPath || !perUsPrdPath || !hasPerUsPrd) {
+    return basePrompt;
+  }
+
+  return basePrompt.split(fullPrdPath).join(perUsPrdPath);
+}
+
+function formatVerifiedUs(verifiedUs) {
+  return verifiedUs.filter(Boolean).join(',');
+}
+
+function getNextUs(usList, verifiedUs) {
+  const verified = new Set(verifiedUs);
+  return usList.find((usId) => !verified.has(usId)) ?? '';
+}
+
+function appendAutonomousModeSection(lines, { conflictLogPath, verifier = false }) {
+  lines.push('');
+  lines.push('---');
+  lines.push('## AUTONOMOUS MODE');
+  lines.push('Do NOT stop or ask questions when encountering ambiguity or document conflicts.');
+  lines.push('**Resolution priority**: PRD > test-spec > context > memory');
+  lines.push(
+    verifier
+      ? 'If documents disagree, follow PRD and proceed. Log any conflict by'
+      : 'If documents disagree, follow PRD and proceed. Log any conflict you find by',
+  );
+  lines.push(`appending to \`${conflictLogPath}\` in format:`);
+  lines.push(
+    '  {"iteration":N,"us_id":"US-NNN","source_a":"prd","source_b":"test-spec","conflict":"description","resolution":"followed PRD"}',
+  );
+  lines.push(verifier ? 'Do NOT wait for human input. Keep verifying.' : 'Do NOT wait for human input. Keep working.');
+}
+
+export async function assembleWorkerPrompt({
+  promptBase,
+  memoryFile,
+  iteration,
+  verifyMode = 'per-us',
+  usList = [],
+  verifiedUs = [],
+  fullPrdPath = '',
+  perUsPrdPath = '',
+  fullTestSpecPath = '',
+  perUsTestSpecPath = '',
+  autonomousMode = false,
+  fixContractPath = '',
+  conflictLogPath = '',
+} = {}) {
+  const basePrompt = await readRequiredFile(promptBase, 'Worker prompt base file');
+  const memoryContent = await readOptionalFile(memoryFile);
+  const hasPerUsPrd = await fileExists(perUsPrdPath);
+  const hasPerUsTestSpec = await fileExists(perUsTestSpecPath);
+  const promptLines = [
+    injectPerUsPrd(basePrompt, fullPrdPath, perUsPrdPath, hasPerUsPrd),
+    '',
+    '---',
+    '## Iteration Context',
+    `- **Iteration**: ${iteration}`,
+    `- **Memory Stop Status**: ${extractSectionValue(memoryContent, 'Stop Status') || 'unknown'}`,
+    `- **Next Iteration Contract**: ${extractSectionValue(memoryContent, 'Next Iteration Contract') || 'Start from the beginning'}`,
+  ];
+
+  const fixContractContent = await readOptionalFile(fixContractPath);
+  if (fixContractContent !== null) {
+    promptLines.push('');
+    promptLines.push('---');
+    promptLines.push(`## IMPORTANT: Fix Contract from Verifier (iteration ${iteration - 1})`);
+    promptLines.push('The Verifier REJECTED your previous work. You MUST fix the issues below.');
+    promptLines.push('Do NOT just resubmit — actually change the code to address each issue.');
+    promptLines.push('');
+    promptLines.push(fixContractContent.trimEnd());
+  }
+
+  if (verifyMode === 'per-us' && usList.length > 0) {
+    const nextUs = getNextUs(usList, verifiedUs);
+    if (nextUs) {
+      promptLines.push('');
+      promptLines.push('---');
+      promptLines.push('## PER-US SCOPE LOCK (this iteration) — OVERRIDES memory contract');
+      promptLines.push("**IGNORE the 'Next Iteration Contract' from memory if it references a different story.**");
+      promptLines.push(`The Leader has determined that **${nextUs}** is the next unverified story.`);
+      promptLines.push(`You MUST implement ONLY **${nextUs}** in this iteration.`);
+      promptLines.push('Do NOT implement any other user stories.');
+      if (hasPerUsTestSpec) {
+        promptLines.push(`- **Test Spec**: Read ONLY \`${perUsTestSpecPath}\` (scoped to ${nextUs})`);
+      } else {
+        promptLines.push(`- **Test Spec**: Read \`${fullTestSpecPath}\` (full — find ${nextUs} section)`);
+      }
+      promptLines.push(`When done, signal verify with us_id="${nextUs}" (not "ALL").`);
+      promptLines.push(`Signal format: {"iteration": N, "status": "verify", "us_id": "${nextUs}", ...}`);
+      promptLines.push('');
+      promptLines.push(`**Update the campaign memory's 'Next Iteration Contract' to reflect ${nextUs}.**`);
+    } else if (verifiedUs.length > 0) {
+      promptLines.push('');
+      promptLines.push('---');
+      promptLines.push('## FINAL VERIFICATION ITERATION');
+      promptLines.push(`All individual US have been verified: ${formatVerifiedUs(verifiedUs)}`);
+      promptLines.push('Run all tests and verification commands to confirm everything works together.');
+      promptLines.push('Signal verify with us_id="ALL" for the final full verification.');
+    }
+  }
+
+  if (autonomousMode) {
+    appendAutonomousModeSection(promptLines, { conflictLogPath });
+  }
+
+  return `${promptLines.join('\n')}\n`;
+}
+
+export async function assembleVerifierPrompt({
+  promptBase,
+  iteration,
+  doneClaimFile,
+  verifyMode = 'per-us',
+  usId = '',
+  verifiedUs = [],
+  autonomousMode = false,
+  conflictLogPath = '',
+} = {}) {
+  const basePrompt = await readRequiredFile(promptBase, 'Verifier prompt base file');
+  const promptLines = [
+    basePrompt.trimEnd(),
+    '',
+    '---',
+    '## Verification Context',
+    `- **Iteration**: ${iteration}`,
+    `- **Done Claim**: ${doneClaimFile}`,
+    `- **Verify Mode**: ${verifyMode}`,
+  ];
+
+  if (usId) {
+    if (usId === 'ALL') {
+      promptLines.push('- **Scope**: FULL VERIFY — check ALL acceptance criteria from the PRD');
+    } else {
+      promptLines.push(`- **Scope**: Verify ONLY the acceptance criteria for **${usId}**`);
+    }
+
+    if (verifiedUs.length > 0) {
+      promptLines.push(`- **Previously verified US**: ${formatVerifiedUs(verifiedUs)}`);
+      promptLines.push('- **Note**: Skip re-verifying the above US. Focus on unverified stories.');
+    }
+  }
+
+  if (autonomousMode) {
+    appendAutonomousModeSection(promptLines, { conflictLogPath, verifier: true });
+  }
+
+  return `${promptLines.join('\n')}\n`;
+}