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

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

package/src/node/reporting/campaign-reporting.mjs

@@ -0,0 +1,257 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const REQUIRED_ANALYTICS_FIELDS = [
+  'iter',
+  'us_id',
+  'worker_model',
+  'worker_engine',
+  'verdict',
+  'duration',
+  'timestamp',
+];
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function asDate(value) {
+  if (value instanceof Date) {
+    return value;
+  }
+
+  return value ? new Date(value) : new Date();
+}
+
+function formatElapsedSeconds(from, to) {
+  const elapsedMs = Math.max(0, asDate(to).getTime() - asDate(from).getTime());
+  return `${Math.floor(elapsedMs / 1000)}s`;
+}
+
+function analyticsVersionPath(targetPath, version) {
+  return targetPath.replace(/\.jsonl$/u, `-v${version}.jsonl`);
+}
+
+function reportVersionPath(targetPath, version) {
+  return targetPath.replace(/\.md$/u, `-v${version}.md`);
+}
+
+async function versionFile(targetPath, nextPathForVersion) {
+  if (!(await exists(targetPath))) {
+    return null;
+  }
+
+  let version = 1;
+  while (await exists(nextPathForVersion(targetPath, version))) {
+    version += 1;
+  }
+
+  const versionedPath = nextPathForVersion(targetPath, version);
+  await fs.rename(targetPath, versionedPath);
+  return versionedPath;
+}
+
+async function readJsonIfExists(targetPath) {
+  if (!(await exists(targetPath))) {
+    return null;
+  }
+
+  return JSON.parse(await fs.readFile(targetPath, 'utf8'));
+}
+
+async function readAnalytics(analyticsFile) {
+  if (!(await exists(analyticsFile))) {
+    return [];
+  }
+
+  const content = await fs.readFile(analyticsFile, 'utf8');
+  return content
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function extractObjective(prdContent) {
+  const match = prdContent.match(/^## Objective\s*([\s\S]*?)(?:^## |\s*$)/m);
+  return match?.[1]?.trim() ?? '(PRD objective not found)';
+}
+
+function extractUsList(prdContent) {
+  return [...prdContent.matchAll(/^## (US-\d{3}):/gm)].map((match) => match[1]);
+}
+
+function summarizeUsStatus(usList, status) {
+  const verified = new Set(status.verified_us ?? []);
+  return usList.length === 0
+    ? ['- None']
+    : usList.map((usId) => `- ${usId}: ${verified.has(usId) ? 'verified' : 'pending'}`);
+}
+
+function summarizeVerificationResults(records) {
+  return records.length === 0
+    ? ['- None']
+    : records.map((record) => `- iter ${record.iter}: ${record.us_id} -> ${record.verdict}`);
+}
+
+async function summarizeIssues(reportDir) {
+  const entries = await fs.readdir(reportDir, { withFileTypes: true }).catch(() => []);
+  const fixContracts = entries
+    .filter((entry) => entry.isFile() && /^iter-\d+\.fix-contract\.md$/u.test(entry.name))
+    .map((entry) => `- ${entry.name}`)
+    .sort();
+
+  return fixContracts.length > 0 ? fixContracts : ['- None'];
+}
+
+function summarizeCost(records) {
+  if (records.length === 0) {
+    return ['- No cost data available', '- Total duration: 0s'];
+  }
+
+  const totalDuration = records.reduce((sum, record) => sum + Number(record.duration ?? 0), 0);
+  return [
+    `- Iteration records: ${records.length}`,
+    `- Total duration: ${totalDuration}s`,
+  ];
+}
+
+async function defaultGitDiffProvider({ cwd }) {
+  try {
+    const { stdout } = await execFileAsync('git', ['diff', '--stat', 'HEAD'], { cwd });
+    return stdout.trim();
+  } catch {
+    return '(git diff unavailable)';
+  }
+}
+
+export async function prepareCampaignAnalytics({ analyticsFile, statusFile }) {
+  await fs.mkdir(path.dirname(analyticsFile), { recursive: true });
+  if (!(await exists(analyticsFile))) {
+    return null;
+  }
+
+  if (await exists(statusFile)) {
+    return null;
+  }
+
+  return versionFile(analyticsFile, analyticsVersionPath);
+}
+
+export async function appendCampaignAnalytics(analyticsFile, record) {
+  for (const field of REQUIRED_ANALYTICS_FIELDS) {
+    if (record[field] === undefined || record[field] === null || record[field] === '') {
+      throw new Error(`analytics record is missing required field: ${field}`);
+    }
+  }
+
+  await fs.mkdir(path.dirname(analyticsFile), { recursive: true });
+  await fs.appendFile(analyticsFile, `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+export async function generateCampaignReport({
+  slug,
+  reportFile,
+  prdFile,
+  statusFile,
+  analyticsFile,
+  now = new Date(),
+  gitDiffProvider = defaultGitDiffProvider,
+  svSummary = 'N/A — --with-self-verification not enabled',
+}) {
+  await fs.mkdir(path.dirname(reportFile), { recursive: true });
+  await versionFile(reportFile, reportVersionPath);
+
+  const prdContent = (await fs.readFile(prdFile, 'utf8').catch(() => ''));
+  const status = (await readJsonIfExists(statusFile)) ?? {
+    slug,
+    iteration: 0,
+    max_iterations: 100,
+    phase: 'idle',
+    verified_us: [],
+    consecutive_failures: 0,
+  };
+  const records = await readAnalytics(analyticsFile);
+  const usList = extractUsList(prdContent);
+  const issues = await summarizeIssues(path.dirname(reportFile));
+  const filesChanged = await gitDiffProvider({ cwd: path.dirname(path.dirname(path.dirname(reportFile))) });
+  const terminalState = String(status.phase ?? 'timeout').toUpperCase();
+  const elapsed = status.started_at_utc
+    ? formatElapsedSeconds(status.started_at_utc, now)
+    : '0s';
+
+  const lines = [
+    `# Campaign Report: ${slug}`,
+    '',
+    `Generated: ${asDate(now).toISOString()} | Status: ${terminalState} | Iterations: ${status.iteration ?? 0}`,
+    '',
+    '## Objective',
+    extractObjective(prdContent),
+    '',
+    '## Execution Summary',
+    `- Terminal state: ${terminalState}`,
+    `- Iterations run: ${status.iteration ?? 0}`,
+    `- Elapsed: ${elapsed}`,
+    '',
+    '## US Status',
+    ...summarizeUsStatus(usList, status),
+    '',
+    '## Verification Results',
+    ...summarizeVerificationResults(records),
+    '',
+    '## Issues Encountered',
+    ...issues,
+    '',
+    '## Cost & Performance',
+    ...summarizeCost(records),
+    '',
+    '## SV Summary',
+    svSummary,
+    '',
+    '## Files Changed',
+    '```',
+    filesChanged || '(no changes)',
+    '```',
+    'Note: Files Changed may include pre-existing uncommitted changes if the campaign started in a dirty worktree.',
+    '',
+  ];
+
+  await fs.writeFile(reportFile, `${lines.join('\n')}\n`, 'utf8');
+}
+
+export async function readStatus(slug, options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const statusFile = path.join(rootDir, '.claude', 'ralph-desk', 'logs', slug, 'runtime', 'status.json');
+
+  if (!(await exists(statusFile))) {
+    return `No active campaign for ${slug}.`;
+  }
+
+  let status;
+  try {
+    status = JSON.parse(await fs.readFile(statusFile, 'utf8'));
+  } catch {
+    return `Campaign: ${slug}\nstatus.json is corrupt.`;
+  }
+
+  const updatedAt = status.updated_at_utc ?? status.started_at_utc ?? asDate(options.now).toISOString();
+  const elapsed = formatElapsedSeconds(updatedAt, options.now ?? new Date());
+  const verifiedUs = (status.verified_us ?? []).join(', ') || 'none';
+
+  return [
+    `Campaign: ${slug}`,
+    `Iteration: ${status.iteration ?? 0} / ${status.max_iterations ?? 100}`,
+    `Phase: ${status.phase ?? 'unknown'}`,
+    `Worker Model: ${status.worker_model ?? 'unknown'} | Verifier: ${status.verifier_model ?? 'unknown'} (per-US) / ${status.final_verifier_model ?? 'unknown'} (final)`,
+    `Verified US: ${verifiedUs}`,
+    `Consecutive Failures: ${status.consecutive_failures ?? 0}`,
+    `Updated: ${updatedAt} (elapsed: ${elapsed})`,
+  ].join('\n');
+}