@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/auto-test.cjs

@@ -0,0 +1,1365 @@
+/**
+ * Auto-Test — Test command collection and execution engine
+ *
+ * Collection: Parses two source formats:
+ * - VALIDATION.md: ```auto-test:suite/quick/task fenced code blocks
+ * - PLAN.md: <verify><automated> XML blocks within <task> elements
+ * Deduplicates across sources (VALIDATION.md wins on exact match).
+ *
+ * Execution: Runs collected commands with timeout protection, false positive
+ * detection, failure classification (infrastructure vs code), and orchestrated
+ * suite execution with abort-on-timeout semantics.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { safeReadFile, findPhaseInternal, output, error } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+
+// ─── Parsers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parse VALIDATION.md content for auto-test:* fenced code blocks.
+ *
+ * @param {string|null} content - Markdown content
+ * @returns {Array<{command: string, source: string, tier: string, label: string}>}
+ */
+function parseValidationMd(content) {
+  if (!content) return [];
+
+  const commands = [];
+  const blockPattern = /```auto-test:(suite|quick|task)\n([\s\S]*?)```/g;
+  let match;
+
+  while ((match = blockPattern.exec(content)) !== null) {
+    const tier = match[1];
+    const blockContent = match[2];
+
+    const lines = blockContent.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      // Skip blank lines and comment lines
+      if (!trimmed || trimmed.startsWith('#')) continue;
+
+      commands.push({
+        command: trimmed,
+        source: 'VALIDATION.md',
+        tier: tier,
+        label: tier === 'suite' ? 'full suite'
+             : tier === 'quick' ? 'quick run'
+             : 'task verify',
+      });
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Parse PLAN.md content for <verify><automated> XML blocks.
+ *
+ * @param {string|null} content - PLAN.md content
+ * @param {string} planId - Plan identifier (e.g., "71-01")
+ * @returns {Array<{command: string, source: string, tier: string, label: string}>}
+ */
+function parsePlanVerifyBlocks(content, planId) {
+  if (!content) return [];
+
+  const commands = [];
+  const taskPattern = /<task[^>]*>([\s\S]*?)<\/task>/g;
+  let taskMatch;
+  let taskIndex = 0;
+
+  while ((taskMatch = taskPattern.exec(content)) !== null) {
+    taskIndex++;
+    const taskContent = taskMatch[1];
+
+    // Extract task name for labeling
+    const nameMatch = taskContent.match(/<name>([\s\S]*?)<\/name>/);
+    const taskName = nameMatch ? nameMatch[1].trim() : `task ${taskIndex}`;
+
+    // Extract <automated> content from within <verify>
+    const autoMatch = taskContent.match(/<automated>([\s\S]*?)<\/automated>/);
+    if (autoMatch) {
+      const cmdStr = autoMatch[1].trim();
+      // Skip empty commands and MISSING placeholders
+      if (cmdStr && !cmdStr.startsWith('MISSING')) {
+        commands.push({
+          command: cmdStr,
+          source: 'PLAN.md',
+          tier: 'task',
+          label: `${planId} ${taskName}`,
+        });
+      }
+    }
+  }
+
+  return commands;
+}
+
+// ─── Deduplication ───────────────────────────────────────────────────────────
+
+/**
+ * Deduplicate commands across sources. VALIDATION.md commands always win.
+ *
+ * @param {Array} validationCmds - Commands from VALIDATION.md
+ * @param {Array} planCmds - Commands from PLAN.md files
+ * @returns {{commands: Array, duplicatesRemoved: number}}
+ */
+function deduplicateCommands(validationCmds, planCmds) {
+  const seen = new Set();
+  const result = [];
+  let dupCount = 0;
+
+  // VALIDATION.md commands go first (they win on conflicts)
+  for (const cmd of validationCmds) {
+    seen.add(cmd.command);
+    result.push(cmd);
+  }
+
+  // PLAN.md commands -- skip exact duplicates
+  for (const cmd of planCmds) {
+    if (seen.has(cmd.command)) {
+      dupCount++;
+      continue;
+    }
+    seen.add(cmd.command);
+    result.push(cmd);
+  }
+
+  return { commands: result, duplicatesRemoved: dupCount };
+}
+
+// ─── Collection ──────────────────────────────────────────────────────────────
+
+/**
+ * Collect all test commands from a phase directory.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phaseDir - Phase directory relative to cwd
+ * @returns {{commands: Array, summary: Object, empty: boolean}}
+ */
+function collectTestCommands(cwd, phaseDir) {
+  const phaseDirFull = path.join(cwd, phaseDir);
+
+  // Read VALIDATION.md (may not exist -- find by pattern)
+  let validationCmds = [];
+  try {
+    const files = fs.readdirSync(phaseDirFull);
+    const validationFile = files.find(f => /-VALIDATION\.md$/i.test(f) || f === 'VALIDATION.md');
+    if (validationFile) {
+      const validationContent = safeReadFile(path.join(phaseDirFull, validationFile));
+      validationCmds = parseValidationMd(validationContent);
+    }
+  } catch { /* directory may not exist */ }
+
+  // Read all PLAN.md files, sorted alphabetically
+  let planCmds = [];
+  try {
+    const files = fs.readdirSync(phaseDirFull);
+    const planFiles = files.filter(f => f.endsWith('-PLAN.md')).sort();
+    for (const planFile of planFiles) {
+      const planId = planFile.replace('-PLAN.md', '');
+      const content = safeReadFile(path.join(phaseDirFull, planFile));
+      planCmds = planCmds.concat(parsePlanVerifyBlocks(content, planId));
+    }
+  } catch { /* no plan files */ }
+
+  // Deduplicate
+  const { commands, duplicatesRemoved } = deduplicateCommands(validationCmds, planCmds);
+
+  return {
+    commands,
+    summary: {
+      total: commands.length,
+      from_validation: validationCmds.length,
+      from_plans: commands.length - validationCmds.length,
+      duplicates_removed: duplicatesRemoved,
+    },
+    empty: commands.length === 0,
+  };
+}
+
+// ─── CLI Command ─────────────────────────────────────────────────────────────
+
+/**
+ * CLI wrapper for collectTestCommands.
+ * Resolves phase via findPhaseInternal, calls collectTestCommands, outputs JSON.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phase - Phase number/identifier
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdCollectTestCommands(cwd, phase, raw) {
+  if (!phase) {
+    error('phase required');
+  }
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  if (!phaseInfo || !phaseInfo.found) {
+    output({ error: 'Phase not found', phase }, raw);
+    return;
+  }
+  const result = collectTestCommands(cwd, phaseInfo.directory);
+  output(result, raw);
+}
+
+// --- Execution Engine --------------------------------------------------------
+
+/**
+ * Run a single shell command and capture structured results.
+ *
+ * @param {string} command - Shell command to execute
+ * @param {Object} [options] - Execution options
+ * @param {number} [options.timeout_ms=120000] - Timeout in milliseconds
+ * @param {string} [options.cwd=process.cwd()] - Working directory
+ * @returns {{exit_code: number, stdout: string, stderr: string, timed_out: boolean, duration_ms: number}}
+ */
+function runCommand(command, options = {}) {
+  const timeout_ms = options.timeout_ms ?? 120000;
+  const cwd = options.cwd ?? process.cwd();
+
+  const start = Date.now();
+  const result = spawnSync('sh', ['-c', command], {
+    timeout: timeout_ms,
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  const duration_ms = Date.now() - start;
+
+  const timed_out = !!(result.signal === 'SIGTERM' || (result.error && /ETIMEDOUT|TIMEOUT|timed out/i.test(result.error.message)));
+  const stdout = result.stdout || '';
+  const stderr = result.stderr || '';
+  const exit_code = result.status != null ? result.status : (timed_out ? 1 : 1);
+
+  return { exit_code, stdout, stderr, timed_out, duration_ms };
+}
+
+/**
+ * Check if command stdout indicates a false positive (exit 0 but no tests actually ran).
+ *
+ * @param {string|null} stdout - Command stdout
+ * @returns {boolean} true if false positive detected
+ */
+function checkFalsePositive(stdout) {
+  if (!stdout) return false;
+  return /(?:0 tests ran|no tests found)/i.test(stdout);
+}
+
+/**
+ * Check if a passing result is suspect (exit 0 but no evidence of test execution).
+ *
+ * Two heuristics:
+ * 1. Empty stdout on a "passing" test -- nothing was actually tested
+ * 2. stdout has content but no test framework assertion markers -- output
+ *    may be informational (e.g., build output, help text) not test results
+ *
+ * Suspect results are distinct from false_positive (which catches "0 tests ran").
+ * A suspect result requires human review rather than being auto-classified.
+ *
+ * @param {{exit_code: number, stdout: string}} result - runCommand result
+ * @returns {boolean} true if result is suspect
+ */
+function checkSuspect(result) {
+  // Only applies to exit code 0 (would-be passes)
+  if (result.exit_code !== 0) return false;
+
+  const stdout = (result.stdout || '').trim();
+
+  // Heuristic 1: Empty stdout on a "passing" test
+  if (!stdout) return true;
+
+  // Heuristic 2: stdout has content but no test framework markers
+  const assertionPatterns = [
+    /\bpass(?:ed|ing)?\b/i,
+    /\bok\b/i,
+    /\bfail(?:ed|ing|ure)?\b/i,
+    /\btests?\s+\d+/i,
+    /\d+\s+(?:passing|failing|pending|skipped)/i,
+    /# tests \d+/,           // Node test runner
+    /Tests:\s+\d+/,          // Jest
+    /[✓✗✕●]/,               // Framework symbols
+    /\bassert/i,
+  ];
+
+  const hasAssertionEvidence = assertionPatterns.some(p => p.test(stdout));
+  if (!hasAssertionEvidence) return true;
+
+  return false;
+}
+
+/**
+ * Check if a task-tier command is covered by a passing suite-tier command.
+ *
+ * Conservative heuristic: only skips when ALL suite commands passed AND the
+ * task command references a file under a directory covered by a suite glob.
+ * When in doubt, returns false (run the test).
+ *
+ * @param {string} taskCmd - The task-tier command string
+ * @param {string[]} suiteCmds - Array of suite-tier command strings
+ * @param {Array<{passed: boolean}>} suiteResults - Results of suite commands (parallel arrays with suiteCmds)
+ * @returns {boolean} true if the task command is covered and can be skipped
+ */
+function isCommandCovered(taskCmd, suiteCmds, suiteResults) {
+  // Only skip if all suite commands passed
+  if (!suiteResults.length) return false;
+  const suiteAllPassed = suiteResults.every(r => r.passed);
+  if (!suiteAllPassed) return false;
+
+  // Extract test file/directory from task command
+  // Matches patterns like: "node --test tests/foo.test.cjs" or "npx jest tests/foo.test.js"
+  const taskFileMatch = taskCmd.match(/(?:--test|jest|vitest|mocha)\s+(\S+)/);
+  if (!taskFileMatch) return false;
+  const taskFile = taskFileMatch[1];
+
+  // Check if any suite command uses a glob that covers this file's directory
+  for (const suiteCmd of suiteCmds) {
+    const suiteGlobMatch = suiteCmd.match(/(?:--test|jest|vitest|mocha)\s+(\S+)/);
+    if (!suiteGlobMatch) continue;
+    const suiteGlob = suiteGlobMatch[1];
+
+    // Simple coverage: if suite uses a glob (contains *) and task file starts with same dir prefix
+    if (suiteGlob.includes('*')) {
+      const suiteDir = suiteGlob.split('*')[0];
+      if (suiteDir && taskFile.startsWith(suiteDir)) return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Classify a command failure as infrastructure or code.
+ *
+ * Infrastructure: environment/setup problems (command not found, permissions, connections, etc.)
+ * Code: test assertion failures, syntax errors, type errors, and other code-level problems.
+ *
+ * @param {{exit_code: number, stderr: string, timed_out: boolean}} result - runCommand result
+ * @returns {'infrastructure'|'code'} Failure classification
+ */
+function classifyFailure(result) {
+  // Timeout is always infrastructure
+  if (result.timed_out) return 'infrastructure';
+
+  // Exit code 127 = command not found
+  if (result.exit_code === 127) return 'infrastructure';
+
+  // Check stderr for infrastructure signals (case-insensitive)
+  const stderr = (result.stderr || '').toLowerCase();
+  const infraPatterns = [
+    'permission denied', 'eacces',
+    'econnrefused', 'connection refused',
+    'enoent', 'file not found', 'no such file',
+    'cannot find module',
+    'out of memory', 'enomem',
+    'enospc', 'disk full', 'no space left',
+    'docker', 'container',
+    'npm err! missing', 'npm err! code e404',
+  ];
+
+  for (const pattern of infraPatterns) {
+    if (stderr.includes(pattern)) return 'infrastructure';
+  }
+
+  // Default: code failure
+  return 'code';
+}
+
+/**
+ * Execute a suite of collected test commands in order with timeout abort semantics.
+ *
+ * Execution order: suite tier first, then quick tier, then task tier.
+ * If any command times out, remaining commands are aborted.
+ * Each result is augmented with passed, failure_type, and false_positive fields.
+ *
+ * @param {Array<{command: string, source: string, tier: string, label: string}>} commands
+ * @param {Object} [options] - Execution options
+ * @param {number} [options.timeout_ms=120000] - Timeout in milliseconds
+ * @param {string} [options.cwd=process.cwd()] - Working directory
+ * @returns {{results: Array, summary: {total: number, passed: number, failed: number, timed_out: number, aborted: number, false_positives: number}}}
+ */
+function executeTestSuite(commands, options = {}) {
+  const timeout_ms = options.timeout_ms ?? 120000;
+  const cwd = options.cwd ?? process.cwd();
+
+  // Sort: suite first, then quick, then task (preserve order within same tier)
+  const tierOrder = { suite: 0, quick: 1, task: 2 };
+  const sorted = commands.slice().sort((a, b) => {
+    const orderA = tierOrder[a.tier] ?? 2;
+    const orderB = tierOrder[b.tier] ?? 2;
+    return orderA - orderB;
+  });
+
+  // Track suite commands and their results for covered-duplicate detection
+  const suiteCmds = sorted.filter(c => c.tier === 'suite');
+  const suiteCommands = suiteCmds.map(c => c.command);
+  const suiteResults = [];
+
+  const results = [];
+  let abortRemaining = false;
+
+  for (const cmd of sorted) {
+    if (abortRemaining) {
+      results.push({
+        command: cmd.command,
+        exit_code: null,
+        stdout: '',
+        stderr: '',
+        timed_out: false,
+        duration_ms: 0,
+        passed: false,
+        failure_type: 'infrastructure',
+        false_positive: false,
+        suspect: false,
+        skipped_covered: false,
+        aborted: true,
+        aborted_reason: 'previous command timed out',
+      });
+      continue;
+    }
+
+    // Check if task-tier command is covered by a passing suite
+    if (cmd.tier === 'task' && isCommandCovered(cmd.command, suiteCommands, suiteResults)) {
+      results.push({
+        command: cmd.command,
+        exit_code: null,
+        stdout: '',
+        stderr: '',
+        timed_out: false,
+        duration_ms: 0,
+        passed: true,
+        failure_type: null,
+        false_positive: false,
+        suspect: false,
+        skipped_covered: true,
+        skipped_reason: 'covered by passing suite command',
+      });
+      continue;
+    }
+
+    const raw = runCommand(cmd.command, { timeout_ms, cwd });
+    const false_positive = raw.exit_code === 0 && checkFalsePositive(raw.stdout);
+    const suspect = !false_positive && checkSuspect(raw);
+    const passed = raw.exit_code === 0 && !false_positive && !suspect;
+    const failure_type = passed ? null : classifyFailure(raw);
+
+    const resultEntry = {
+      command: cmd.command,
+      exit_code: raw.exit_code,
+      stdout: raw.stdout,
+      stderr: raw.stderr,
+      timed_out: raw.timed_out,
+      duration_ms: raw.duration_ms,
+      passed,
+      failure_type,
+      false_positive,
+      suspect,
+      skipped_covered: false,
+      framework_output: parseFrameworkOutput(raw.stdout),
+    };
+
+    results.push(resultEntry);
+
+    // Track suite results for covered-duplicate detection
+    if (cmd.tier === 'suite') {
+      suiteResults.push({ passed: resultEntry.passed });
+    }
+
+    if (raw.timed_out) {
+      abortRemaining = true;
+    }
+  }
+
+  // Build summary
+  const summary = {
+    total: results.length,
+    passed: results.filter(r => r.passed).length,
+    failed: results.filter(r => !r.passed).length,
+    timed_out: results.filter(r => r.timed_out).length,
+    aborted: results.filter(r => r.aborted).length,
+    false_positives: results.filter(r => r.false_positive).length,
+    suspects: results.filter(r => r.suspect).length,
+    skipped_covered: results.filter(r => r.skipped_covered).length,
+  };
+
+  return { results, summary };
+}
+
+// --- Framework Output Parsing ------------------------------------------------
+
+/**
+ * Parse test framework stdout to extract granular pass/fail/skip counts.
+ *
+ * Detection order: Jest, Vitest, Mocha, Node.js test runner, fallback.
+ * Returns null counts for unrecognized or empty output.
+ *
+ * @param {string|null} stdout - Command stdout
+ * @returns {{framework: string|null, passed: number|null, failed: number|null, skipped: number|null, total: number|null}}
+ */
+function parseFrameworkOutput(stdout) {
+  const nullResult = { framework: null, passed: null, failed: null, skipped: null, total: null };
+  if (!stdout) return nullResult;
+
+  // 1. Jest: "Tests:  3 passed, 1 failed, 4 total"
+  const jestMatch = stdout.match(/^Tests:\s+(.+)$/m);
+  if (jestMatch) {
+    const line = jestMatch[1];
+    const passed = parseInt((line.match(/(\d+) passed/) || [])[1], 10) || 0;
+    const failed = parseInt((line.match(/(\d+) failed/) || [])[1], 10) || 0;
+    const skipped = parseInt((line.match(/(\d+) skipped/) || [])[1], 10) || 0;
+    const total = parseInt((line.match(/(\d+) total/) || [])[1], 10) || 0;
+    return { framework: 'jest', passed, failed, skipped, total };
+  }
+
+  // 2. Vitest: " Tests  2 failed | 3 passed (5)"
+  const vitestMatch = stdout.match(/^\s*Tests\s+(.+)\((\d+)\)\s*$/m);
+  if (vitestMatch) {
+    const line = vitestMatch[1];
+    const total = parseInt(vitestMatch[2], 10);
+    const passed = parseInt((line.match(/(\d+) passed/) || [])[1], 10) || 0;
+    const failed = parseInt((line.match(/(\d+) failed/) || [])[1], 10) || 0;
+    const skipped = parseInt((line.match(/(\d+) skipped/) || [])[1], 10) || 0;
+    return { framework: 'vitest', passed, failed, skipped, total };
+  }
+
+  // 3. Mocha: "  3 passing (42ms)" / "  1 failing" / "  2 pending"
+  const mochaPassMatch = stdout.match(/^\s*(\d+) passing/m);
+  if (mochaPassMatch) {
+    const passed = parseInt(mochaPassMatch[1], 10);
+    const failMatch = stdout.match(/^\s*(\d+) failing/m);
+    const pendMatch = stdout.match(/^\s*(\d+) pending/m);
+    const failed = failMatch ? parseInt(failMatch[1], 10) : 0;
+    const skipped = pendMatch ? parseInt(pendMatch[1], 10) : 0;
+    const total = passed + failed + skipped;
+    return { framework: 'mocha', passed, failed, skipped, total };
+  }
+
+  // 4. Node.js test runner: "# tests 19", "# pass 19", "# fail 0"
+  const nodeTestsMatch = stdout.match(/^# tests (\d+)/m);
+  const nodePassMatch = stdout.match(/^# pass (\d+)/m);
+  const nodeFailMatch = stdout.match(/^# fail (\d+)/m);
+  if (nodeTestsMatch && nodePassMatch && nodeFailMatch) {
+    const total = parseInt(nodeTestsMatch[1], 10);
+    const passed = parseInt(nodePassMatch[1], 10);
+    const failed = parseInt(nodeFailMatch[1], 10);
+    const nodeSkipMatch = stdout.match(/^# skip (\d+)/m);
+    const skipped = nodeSkipMatch ? parseInt(nodeSkipMatch[1], 10) : 0;
+    return { framework: 'node', passed, failed, skipped, total };
+  }
+
+  // 5. Fallback: unrecognized
+  return nullResult;
+}
+
+// --- CLI: Run Test Suite -----------------------------------------------------
+
+/**
+ * CLI wrapper for executeTestSuite.
+ * Collects test commands then executes them.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phase - Phase number/identifier
+ * @param {boolean} raw - Raw output mode
+ * @param {Object} [options] - Execution options
+ * @param {number} [options.timeout_ms] - Per-command timeout in milliseconds
+ */
+function cmdRunTestSuite(cwd, phase, raw, options = {}) {
+  if (!phase) {
+    error('phase required');
+  }
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  if (!phaseInfo || !phaseInfo.found) {
+    output({ error: 'Phase not found', phase }, raw);
+    return;
+  }
+  const collected = collectTestCommands(cwd, phaseInfo.directory);
+  if (collected.empty) {
+    output({ results: [], summary: { total: 0, passed: 0, failed: 0, timed_out: 0, aborted: 0, false_positives: 0 }, collection: collected.summary }, raw);
+    return;
+  }
+  const execOptions = { cwd: options.testCwd || cwd };
+  if (options.timeout_ms) execOptions.timeout_ms = options.timeout_ms;
+  const result = executeTestSuite(collected.commands, execOptions);
+  result.collection = collected.summary;
+  output(result, raw);
+}
+
+// --- Result Mapping Engine ----------------------------------------------------
+
+/**
+ * Infer gap severity from failure output.
+ *
+ * Priority order:
+ * 1. Infrastructure failure_type or timed_out → blocker
+ * 2. Compilation/syntax patterns in stderr → blocker
+ * 3. Warning-only patterns (no assertion/error patterns) → minor
+ * 4. Assertion patterns in stderr → major
+ * 5. Default → major
+ *
+ * @param {{exit_code: number, stdout: string, stderr: string, failure_type: string|null, false_positive: boolean, timed_out: boolean}} result
+ * @returns {'blocker'|'major'|'minor'}
+ */
+function inferSeverity(result) {
+  // 1. Infrastructure failures are always blockers
+  if (result.failure_type === 'infrastructure') return 'blocker';
+
+  // 2. Timeout is always a blocker
+  if (result.timed_out === true) return 'blocker';
+
+  const stderr = result.stderr || '';
+
+  // 3. Compilation/syntax patterns → blocker
+  const blockerPatterns = [
+    /SyntaxError/i,
+    /TypeError/i,
+    /ReferenceError/i,
+    /error TS/i,
+    /cannot find module/i,
+    /compilation failed/i,
+    /Build failed/i,
+  ];
+  for (const pattern of blockerPatterns) {
+    if (pattern.test(stderr)) return 'blocker';
+  }
+
+  // 4. Warning-only patterns (no assertion/error signals) → minor
+  const warningPatterns = /warning:|DeprecationWarning/i;
+  const assertionPatterns = /AssertionError|Expected.*but received|assert\.|FAIL |✕|✗/i;
+  if (warningPatterns.test(stderr) && !assertionPatterns.test(stderr)) {
+    return 'minor';
+  }
+
+  // 5. Assertion patterns → major
+  if (assertionPatterns.test(stderr)) return 'major';
+
+  // 6. Default
+  return 'major';
+}
+
+/**
+ * Parse manual verification items from VALIDATION.md and PLAN.md files.
+ *
+ * From PLAN.md: Extracts <manual> blocks within <task><verify> elements.
+ * From VALIDATION.md: Extracts rows from "## Manual-Only Verifications" table.
+ *
+ * @param {string|null} validationContent - VALIDATION.md content
+ * @param {Array<{content: string|null, planId: string}>} planContents - Array of plan content objects
+ * @returns {Array<{description: string, source: string, label: string}>}
+ */
+function collectManualVerifications(validationContent, planContents) {
+  const items = [];
+
+  // Parse PLAN.md files for <manual> blocks
+  if (Array.isArray(planContents)) {
+    for (const plan of planContents) {
+      if (!plan.content) continue;
+
+      const taskPattern = /<task[^>]*>([\s\S]*?)<\/task>/g;
+      let taskMatch;
+      let taskIndex = 0;
+
+      while ((taskMatch = taskPattern.exec(plan.content)) !== null) {
+        taskIndex++;
+        const taskContent = taskMatch[1];
+
+        // Extract task name
+        const nameMatch = taskContent.match(/<name>([\s\S]*?)<\/name>/);
+        const taskName = nameMatch ? nameMatch[1].trim() : `task ${taskIndex}`;
+
+        // Check for <manual> inside <verify>
+        const manualMatch = taskContent.match(/<manual>([\s\S]*?)<\/manual>/);
+        if (manualMatch) {
+          items.push({
+            description: manualMatch[1].trim(),
+            source: 'PLAN.md',
+            label: `${plan.planId} ${taskName}`,
+          });
+        }
+      }
+    }
+  }
+
+  // Parse VALIDATION.md for Manual-Only Verifications table
+  if (validationContent) {
+    const sectionMatch = validationContent.match(/## Manual-Only Verifications\s*\n([\s\S]*?)(?=\n## |\n$|$)/);
+    if (sectionMatch) {
+      const sectionContent = sectionMatch[1];
+      // Parse markdown table rows (skip header and separator)
+      const lines = sectionContent.split('\n');
+      let headerParsed = false;
+      let separatorParsed = false;
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith('|')) continue;
+
+        if (!headerParsed) {
+          headerParsed = true;
+          continue;
+        }
+        if (!separatorParsed) {
+          separatorParsed = true;
+          continue;
+        }
+
+        // Parse data row: | # | Behavior | Context | Test Instructions |
+        const cells = trimmed.split('|').filter(c => c.trim() !== '');
+        if (cells.length >= 4) {
+          const behavior = cells[1].trim();
+          const instructions = cells[3].trim();
+          items.push({
+            description: `${behavior}: ${instructions}`,
+            source: 'VALIDATION.md',
+            label: 'manual-only',
+          });
+        }
+      }
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Generate full UAT file content string from execution results and manual verifications.
+ *
+ * @param {{results: Array, summary: Object}} executionResult - From executeTestSuite
+ * @param {Array<{description: string, source: string, label: string}>} manualVerifications - From collectManualVerifications
+ * @param {{phase: string, phaseDir: string, sourceFiles: string[]}} phaseInfo - Phase metadata
+ * @returns {string} UAT markdown file content
+ */
+function mapResultsToUat(executionResult, manualVerifications, phaseInfo) {
+  const results = executionResult.results || [];
+  const manual = manualVerifications || [];
+
+  const passedCount = results.filter(r => r.passed).length;
+  const actualFailedCount = results.filter(r => !r.passed && !r.suspect && !r.skipped_covered).length;
+  const failedCount = results.filter(r => !r.passed).length;
+  const suspectCount = results.filter(r => r.suspect).length;
+  const skippedCount = results.filter(r => r.skipped_covered).length;
+  const humanCount = manual.length;
+  const totalCount = results.length + humanCount;
+  const allAutomatedPassed = actualFailedCount === 0;
+  const status = allAutomatedPassed ? 'complete' : 'gaps_found';
+  const now = new Date().toISOString();
+
+  const lines = [];
+
+  // --- Frontmatter ---
+  lines.push('---');
+  lines.push(`status: ${status}`);
+  lines.push(`phase: ${phaseInfo.phase}`);
+  lines.push('mode: auto-test');
+  lines.push('ai_verified: true');
+  if (phaseInfo.sourceFiles && phaseInfo.sourceFiles.length > 0) {
+    lines.push(`source: ${phaseInfo.sourceFiles.join(', ')}`);
+  }
+  lines.push(`started: ${now}`);
+  lines.push(`updated: ${now}`);
+  lines.push('---');
+  lines.push('');
+
+  // --- Current Test ---
+  lines.push('## Current Test');
+  lines.push('');
+  lines.push('[testing complete]');
+  lines.push('');
+
+  // --- Tests Section ---
+  lines.push('## Tests');
+  lines.push('');
+
+  let testNum = 0;
+
+  // Automated results
+  for (const r of results) {
+    testNum++;
+    const cmdTruncated = r.command.length > 60 ? r.command.substring(0, 60) + '...' : r.command;
+    lines.push(`### ${testNum}. ${cmdTruncated}`);
+    lines.push('expected: Command exits with code 0');
+
+    if (r.passed && !r.skipped_covered) {
+      lines.push('result: pass');
+    } else if (r.skipped_covered) {
+      lines.push('result: pass');
+      lines.push('note: covered by passing suite command — skipped');
+    } else if (r.suspect) {
+      lines.push('result: suspect');
+      lines.push('note: "Exit code 0 but output lacks test framework assertion markers — requires human review"');
+      lines.push('severity: minor');
+    } else {
+      const severity = inferSeverity(r);
+      lines.push('result: issue');
+      lines.push(`severity: ${severity}`);
+      const stderrTrunc = (r.stderr || '').substring(0, 500);
+      lines.push(`reported: "Exit code ${r.exit_code}: ${stderrTrunc}"`);
+    }
+    lines.push(`command: ${r.command}`);
+    lines.push('');
+  }
+
+  // Manual verification entries
+  for (const m of manual) {
+    testNum++;
+    const descTruncated = m.description.length > 60 ? m.description.substring(0, 60) + '...' : m.description;
+    lines.push(`### ${testNum}. ${descTruncated}`);
+    lines.push(`expected: ${m.description}`);
+    lines.push('result: human_needed');
+    lines.push(`source: ${m.source}`);
+    lines.push(`label: ${m.label}`);
+    lines.push('');
+  }
+
+  // --- Summary Section ---
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`total: ${totalCount}`);
+  lines.push(`passed: ${passedCount}`);
+  lines.push(`issues: ${actualFailedCount}`);
+  lines.push(`suspect: ${suspectCount}`);
+  lines.push(`human_needed: ${humanCount}`);
+  lines.push('pending: 0');
+  lines.push(`skipped: ${skippedCount}`);
+  lines.push('');
+
+  // --- Gaps Section ---
+  lines.push('## Gaps');
+  lines.push('');
+
+  // Only actual failures appear in Gaps (not suspect or skipped_covered)
+  let gapTestNum = 0;
+  for (const r of results) {
+    gapTestNum++;
+    if (r.passed || r.suspect || r.skipped_covered) continue;
+
+    const severity = inferSeverity(r);
+    const gapType = r.failure_type === 'infrastructure' ? 'infrastructure_gap' : 'code_gap';
+    const stderrTrunc = (r.stderr || '').substring(0, 500);
+
+    lines.push(`- truth: "Command '${r.command}' passes"`);
+    lines.push('  status: failed');
+    lines.push(`  reason: "Exit code ${r.exit_code}: ${stderrTrunc}"`);
+    lines.push(`  severity: ${severity}`);
+    lines.push(`  gap_type: ${gapType}`);
+    lines.push(`  command: "${r.command}"`);
+    lines.push(`  test: ${gapTestNum}`);
+    lines.push(`  exit_code: ${r.exit_code}`);
+    lines.push(`  stderr: "${stderrTrunc}"`);
+    lines.push('  artifacts: []');
+    lines.push('  missing: []');
+  }
+
+  return lines.join('\n');
+}
+
+// --- CLI: Map Results to UAT -------------------------------------------------
+
+/**
+ * CLI wrapper that orchestrates the full auto-test pipeline:
+ * collect commands, execute tests, collect manual verifications,
+ * generate UAT file, and write to disk.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phase - Phase number/identifier
+ * @param {boolean} raw - Raw output mode
+ * @param {Object} [options] - Execution options
+ * @param {number} [options.timeout_ms] - Per-command timeout in milliseconds
+ */
+function cmdMapResults(cwd, phase, raw, options = {}) {
+  if (!phase) {
+    error('phase required');
+  }
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  if (!phaseInfo || !phaseInfo.found) {
+    output({ error: 'Phase not found', phase }, raw);
+    return;
+  }
+
+  const phaseDir = phaseInfo.directory;
+  const phaseDirFull = path.join(cwd, phaseDir);
+
+  // 1. Collect and execute
+  const collected = collectTestCommands(cwd, phaseDir);
+  let executionResult;
+  if (collected.empty) {
+    executionResult = { results: [], summary: { total: 0, passed: 0, failed: 0, timed_out: 0, aborted: 0, false_positives: 0 } };
+  } else {
+    const execOptions = { cwd: options.testCwd || cwd };
+    if (options.timeout_ms) execOptions.timeout_ms = options.timeout_ms;
+    executionResult = executeTestSuite(collected.commands, execOptions);
+  }
+
+  // 2. Collect manual verifications
+  const files = fs.readdirSync(phaseDirFull);
+  let validationContent = null;
+  const validationFile = files.find(f => /-VALIDATION\.md$/i.test(f) || f === 'VALIDATION.md');
+  if (validationFile) {
+    validationContent = safeReadFile(path.join(phaseDirFull, validationFile));
+  }
+  const planContents = [];
+  const planFiles = files.filter(f => f.endsWith('-PLAN.md')).sort();
+  for (const planFile of planFiles) {
+    const planId = planFile.replace('-PLAN.md', '');
+    const content = safeReadFile(path.join(phaseDirFull, planFile));
+    planContents.push({ content, planId });
+  }
+  const manualVerifications = collectManualVerifications(validationContent, planContents);
+
+  // 3. Build phase info
+  const sourceFiles = files.filter(f => f.endsWith('-SUMMARY.md'));
+  const mapPhaseInfo = {
+    phase: phaseInfo.name || phaseDir.split('/').pop(),
+    phaseDir: phaseDir,
+    sourceFiles: sourceFiles,
+  };
+
+  // 4. Generate UAT content and write
+  const uatContent = mapResultsToUat(executionResult, manualVerifications, mapPhaseInfo);
+  const phaseNum = phaseDir.split('/').pop().match(/^(\d+)/)?.[1] || phase;
+  const uatPath = path.join(phaseDirFull, `${phaseNum}-UAT.md`);
+  fs.writeFileSync(uatPath, uatContent, 'utf-8');
+
+  // 4b. Generate and write test log
+  const logContent = generateTestLog(executionResult);
+  const logPath = path.join(phaseDirFull, `${phaseNum}-UAT-LOG.md`);
+  fs.writeFileSync(logPath, logContent, 'utf-8');
+
+  // 5. Output result
+  output({
+    uat_path: path.relative(cwd, uatPath),
+    log_path: path.relative(cwd, logPath),
+    summary: executionResult.summary,
+    manual_count: manualVerifications.length,
+    status: executionResult.summary.failed > 0 ? 'gaps_found' : 'complete',
+  }, raw);
+}
+
+// --- Diagnosis Check ---------------------------------------------------------
+
+/**
+ * Check if a UAT file needs diagnosis (has gaps_found status and actual gap entries).
+ *
+ * @param {string|null} uatContent - UAT file content
+ * @returns {boolean} true if UAT has status: gaps_found and non-empty gaps
+ */
+function checkNeedsDiagnosis(uatContent) {
+  if (!uatContent) return false;
+  // Check frontmatter for status: diagnosed
+  const statusMatch = uatContent.match(/^status:\s*gaps_found\s*$/m);
+  if (!statusMatch) return false;
+  // Check for actual gap entries (not just "[none yet]")
+  const gapsSection = uatContent.match(/## Gaps\s*\n([\s\S]*?)(?=\n## |$)/);
+  if (!gapsSection) return false;
+  const gapsContent = gapsSection[1].trim();
+  if (!gapsContent || gapsContent === '[none yet]' || gapsContent === '[none]') return false;
+  // Must have at least one "- truth:" entry
+  return /- truth:/.test(gapsContent);
+}
+
+// --- Test Log Generation -----------------------------------------------------
+
+/**
+ * Generate a test log string with full stdout/stderr for every command.
+ *
+ * Each command's output is delimited by command name and timestamp for
+ * easy post-hoc debugging. The log preserves complete output that the
+ * UAT file truncates.
+ *
+ * @param {{results: Array<{command: string, exit_code: number|null, stdout: string, stderr: string, timed_out: boolean, duration_ms: number}>}} executionResult
+ * @returns {string} Delimited log file content
+ */
+function generateTestLog(executionResult) {
+  const results = executionResult.results || [];
+  const lines = [];
+
+  // Header
+  lines.push('# Auto-Test Log');
+  lines.push(`# Generated: ${new Date().toISOString()}`);
+  lines.push('');
+
+  for (const r of results) {
+    lines.push(`=== COMMAND: ${r.command} ===`);
+    lines.push(`=== TIMESTAMP: ${new Date().toISOString()} ===`);
+    lines.push(`=== EXIT CODE: ${r.exit_code} ===`);
+    lines.push(`=== DURATION: ${r.duration_ms}ms ===`);
+    lines.push('');
+    lines.push('--- stdout ---');
+    lines.push(r.stdout || '(empty)');
+    lines.push('--- stderr ---');
+    lines.push(r.stderr || '(empty)');
+    lines.push('');
+    lines.push(`=== END: ${r.command} ===`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// --- Rerun Pipeline ----------------------------------------------------------
+
+/**
+ * Parse an auto-test UAT file to extract commands for failed tests only.
+ *
+ * Only processes UAT files with `mode: auto-test` in frontmatter.
+ * Only extracts commands from entries with `result: issue`.
+ * Entries with `result: pass` or `result: human_needed` are excluded.
+ *
+ * @param {string|null} uatContent - UAT file content
+ * @returns {string[]} Array of command strings from failed tests
+ */
+function parseUatForFailedCommands(uatContent) {
+  if (!uatContent) return [];
+
+  // Check frontmatter for mode: auto-test
+  if (!/^mode:\s*auto-test\s*$/m.test(uatContent)) return [];
+
+  // Split into test blocks by ### N. headers
+  const blocks = uatContent.split(/(?=^### \d+\.)/m);
+  const commands = [];
+
+  for (const block of blocks) {
+    // Must be a test block (starts with ### N.)
+    if (!/^### \d+\./.test(block)) continue;
+
+    // Check if result is issue (not pass, not human_needed)
+    if (!/^result:\s*issue\s*$/m.test(block)) continue;
+
+    // Extract command field value
+    const cmdMatch = block.match(/^command:\s*(.+)$/m);
+    if (cmdMatch) {
+      commands.push(cmdMatch[1].trim());
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Extract structural gap entries from a UAT file.
+ * Structural gaps are identified by source: structural_verification and result: issue.
+ * Used by --rerun-failed to pass the gap list to the verifier for targeted re-check.
+ * @param {string} uatContent - Raw UAT file content
+ * @returns {Array<{description: string, reported: string, severity: string}>}
+ */
+function parseUatForStructuralGaps(uatContent) {
+  if (!uatContent) return [];
+  if (!/^mode:\s*auto-test\s*$/m.test(uatContent)) return [];
+
+  const blocks = uatContent.split(/(?=^### \d+\.)/m);
+  const gaps = [];
+
+  for (const block of blocks) {
+    if (!/^### \d+\./.test(block)) continue;
+    if (!/^result:\s*issue\s*$/m.test(block)) continue;
+    if (!/^source:\s*structural_verification\s*$/m.test(block)) continue;
+
+    const headerMatch = block.match(/^### \d+\.\s*\[STRUCTURAL\]\s*(.+)$/m);
+    const reportedMatch = block.match(/^reported:\s*"?(.+?)"?\s*$/m);
+    const severityMatch = block.match(/^severity:\s*(\w+)\s*$/m);
+
+    if (headerMatch) {
+      gaps.push({
+        description: headerMatch[1].trim(),
+        reported: reportedMatch ? reportedMatch[1].trim() : '',
+        severity: severityMatch ? severityMatch[1].trim() : 'major',
+      });
+    }
+  }
+
+  return gaps;
+}
+
+/**
+ * Re-execute a list of previously-failed test commands.
+ *
+ * Uses the existing runCommand infrastructure for execution,
+ * checkFalsePositive for false positive detection, classifyFailure
+ * for failure type, and parseFrameworkOutput for framework metadata.
+ *
+ * @param {string[]} failedCommands - Array of command strings to re-execute
+ * @param {Object} [options] - Execution options
+ * @param {string} [options.cwd=process.cwd()] - Working directory
+ * @param {number} [options.timeout_ms=120000] - Timeout in milliseconds
+ * @returns {{rerun_count: number, all_passed: boolean, results: Array}}
+ */
+function rerunFailedTests(failedCommands, options = {}) {
+  if (failedCommands.length === 0) {
+    return { rerun_count: 0, all_passed: true, results: [] };
+  }
+
+  const cwd = options.cwd ?? process.cwd();
+  const timeout_ms = options.timeout_ms ?? 120000;
+  const results = [];
+
+  for (const cmd of failedCommands) {
+    const raw = runCommand(cmd, { cwd, timeout_ms });
+    const false_positive = raw.exit_code === 0 && checkFalsePositive(raw.stdout);
+    const passed = raw.exit_code === 0 && !false_positive;
+    const failure_type = passed ? null : classifyFailure(raw);
+
+    results.push({
+      command: cmd,
+      exit_code: raw.exit_code,
+      stdout: raw.stdout,
+      stderr: raw.stderr,
+      timed_out: raw.timed_out,
+      duration_ms: raw.duration_ms,
+      passed,
+      failure_type,
+      false_positive,
+      framework_output: parseFrameworkOutput(raw.stdout),
+    });
+  }
+
+  const allPassed = results.every(r => r.passed);
+  return { rerun_count: results.length, all_passed: allPassed, results };
+}
+
+/**
+ * CLI wrapper that orchestrates the full rerun-failed pipeline:
+ * reads existing UAT, extracts failed commands, re-executes them,
+ * merges results with original passes, regenerates full UAT.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phase - Phase number/identifier
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdRerunFailed(cwd, phase, raw, options = {}) {
+  if (!phase) {
+    error('phase required');
+  }
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  if (!phaseInfo || !phaseInfo.found) {
+    output({ error: 'Phase not found', phase }, raw);
+    return;
+  }
+
+  const phaseDir = phaseInfo.directory;
+  const phaseDirFull = path.join(cwd, phaseDir);
+  const phaseNum = phaseDir.split('/').pop().match(/^(\d+)/)?.[1] || phase;
+  const uatPath = path.join(phaseDirFull, `${phaseNum}-UAT.md`);
+  const uatContent = safeReadFile(uatPath);
+
+  if (!uatContent) {
+    output({ error: 'No UAT file found for phase', phase }, raw);
+    return;
+  }
+
+  // Extract failed commands
+  const failedCommands = parseUatForFailedCommands(uatContent);
+  if (failedCommands.length === 0) {
+    output({ rerun_count: 0, all_passed: true, status: 'complete', message: 'No failed tests to rerun' }, raw);
+    return;
+  }
+
+  // Re-execute failed commands
+  const rerunResult = rerunFailedTests(failedCommands, { cwd: options.testCwd || cwd });
+
+  // Collect original passing results from UAT
+  const blocks = uatContent.split(/(?=^### \d+\.)/m);
+  const originalPassResults = [];
+  for (const block of blocks) {
+    if (!/^### \d+\./.test(block)) continue;
+    if (!/^result:\s*pass\s*$/m.test(block)) continue;
+    const cmdMatch = block.match(/^command:\s*(.+)$/m);
+    if (cmdMatch) {
+      const cmd = cmdMatch[1].trim();
+      originalPassResults.push({
+        command: cmd,
+        exit_code: 0,
+        stdout: '',
+        stderr: '',
+        timed_out: false,
+        duration_ms: 0,
+        passed: true,
+        failure_type: null,
+        false_positive: false,
+        framework_output: { framework: null, passed: null, failed: null, skipped: null, total: null },
+      });
+    }
+  }
+
+  // Merge: original pass results + rerun results
+  const mergedResults = [...originalPassResults, ...rerunResult.results];
+  const mergedExecutionResult = {
+    results: mergedResults,
+    summary: {
+      total: mergedResults.length,
+      passed: mergedResults.filter(r => r.passed).length,
+      failed: mergedResults.filter(r => !r.passed).length,
+      timed_out: mergedResults.filter(r => r.timed_out).length,
+      aborted: mergedResults.filter(r => r.aborted).length,
+      false_positives: mergedResults.filter(r => r.false_positive).length,
+    },
+  };
+
+  // Collect manual verifications (same pattern as cmdMapResults)
+  const files = fs.readdirSync(phaseDirFull);
+  let validationContent = null;
+  const validationFile = files.find(f => /-VALIDATION\.md$/i.test(f) || f === 'VALIDATION.md');
+  if (validationFile) {
+    validationContent = safeReadFile(path.join(phaseDirFull, validationFile));
+  }
+  const planContents = [];
+  const planFiles = files.filter(f => f.endsWith('-PLAN.md')).sort();
+  for (const planFile of planFiles) {
+    const planId = planFile.replace('-PLAN.md', '');
+    const content = safeReadFile(path.join(phaseDirFull, planFile));
+    planContents.push({ content, planId });
+  }
+  const manualVerifications = collectManualVerifications(validationContent, planContents);
+
+  // Build phase info (same pattern as cmdMapResults)
+  const sourceFiles = files.filter(f => f.endsWith('-SUMMARY.md'));
+  const mapPhaseInfo = {
+    phase: phaseInfo.name || phaseDir.split('/').pop(),
+    phaseDir: phaseDir,
+    sourceFiles: sourceFiles,
+  };
+
+  // Regenerate full UAT with merged results
+  const newUatContent = mapResultsToUat(mergedExecutionResult, manualVerifications, mapPhaseInfo);
+  fs.writeFileSync(uatPath, newUatContent, 'utf-8');
+
+  // Generate test log for the rerun only (not merged)
+  const rerunExecutionResult = {
+    results: rerunResult.results,
+    summary: {
+      total: rerunResult.results.length,
+      passed: rerunResult.results.filter(r => r.passed).length,
+      failed: rerunResult.results.filter(r => !r.passed).length,
+      timed_out: rerunResult.results.filter(r => r.timed_out).length,
+      aborted: 0,
+      false_positives: rerunResult.results.filter(r => r.false_positive).length,
+    },
+  };
+  const logContent = generateTestLog(rerunExecutionResult);
+  const logPath = path.join(phaseDirFull, `${phaseNum}-UAT-LOG.md`);
+  fs.writeFileSync(logPath, logContent, 'utf-8');
+
+  // Determine status
+  const allPassed = rerunResult.all_passed;
+  const status = allPassed ? 'complete' : 'gaps_found';
+  const passedRerun = rerunResult.results.filter(r => r.passed).length;
+  const failedRerun = rerunResult.results.filter(r => !r.passed).length;
+
+  // Extract structural gaps for the workflow to pass to the verifier
+  const structuralGaps = parseUatForStructuralGaps(uatContent);
+
+  output({
+    uat_path: path.relative(cwd, uatPath),
+    log_path: path.relative(cwd, logPath),
+    rerun_count: rerunResult.rerun_count,
+    all_passed: allPassed,
+    status,
+    summary: `${passedRerun} passed, ${failedRerun} failed (of ${rerunResult.rerun_count} rerun)`,
+    structural_gaps: structuralGaps,
+    structural_gap_count: structuralGaps.length,
+  }, raw);
+}
+
+// --- CLI: Check Diagnosis ----------------------------------------------------
+
+/**
+ * CLI wrapper that reads the UAT file for a phase and checks if diagnosis is needed.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phase - Phase number/identifier
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdCheckDiagnosis(cwd, phase, raw) {
+  if (!phase) {
+    error('phase required');
+  }
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  if (!phaseInfo || !phaseInfo.found) {
+    output({ error: 'Phase not found', phase }, raw);
+    return;
+  }
+  const phaseDirFull = path.join(cwd, phaseInfo.directory);
+  const phaseNum = phaseInfo.directory.split('/').pop().match(/^(\d+)/)?.[1] || phase;
+  const uatPath = path.join(phaseDirFull, `${phaseNum}-UAT.md`);
+  const uatContent = safeReadFile(uatPath);
+  if (!uatContent) {
+    output({ needs_diagnosis: false, reason: 'No UAT file found', uat_path: null }, raw);
+    return;
+  }
+  const needsDiag = checkNeedsDiagnosis(uatContent);
+  output({
+    needs_diagnosis: needsDiag,
+    uat_path: path.relative(cwd, uatPath),
+    status: needsDiag ? 'gaps_found' : 'complete',
+  }, raw);
+}
+
+/**
+ * CLI wrapper that reads a phase's UAT file and returns structured JSON status.
+ * Enables the job orchestrator to check phase audit status programmatically.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phase - Phase number/identifier
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdPhaseUatStatus(cwd, phase, raw) {
+  if (!phase) {
+    error('phase required');
+  }
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  if (!phaseInfo || !phaseInfo.found) {
+    output({ error: 'Phase not found', phase }, raw);
+    return;
+  }
+  const phaseDirFull = path.join(cwd, phaseInfo.directory);
+  const phaseNum = phaseInfo.directory.split('/').pop().match(/^(\d+)/)?.[1] || phase;
+  const uatPath = path.join(phaseDirFull, `${phaseNum}-UAT.md`);
+  const uatContent = safeReadFile(uatPath);
+  if (!uatContent) {
+    output({ status: null, uat_path: null, phase: phaseNum, reason: 'no_uat_file' }, raw);
+    return;
+  }
+  const fm = extractFrontmatter(uatContent);
+  const summary = {};
+  const countFields = ['total', 'passed', 'issues', 'human_needed', 'pending', 'skipped'];
+  for (const field of countFields) {
+    const match = uatContent.match(new RegExp(`^${field}:\\s*(\\d+)`, 'm'));
+    summary[field] = match ? parseInt(match[1], 10) : 0;
+  }
+  output({
+    status: fm.status || null,
+    phase: phaseNum,
+    uat_path: path.relative(cwd, uatPath),
+    mode: fm.mode || null,
+    ai_verified: fm.ai_verified === 'true' || fm.ai_verified === true || false,
+    summary,
+  }, raw);
+}
+
+module.exports = {
+  parseValidationMd,
+  parsePlanVerifyBlocks,
+  deduplicateCommands,
+  collectTestCommands,
+  cmdCollectTestCommands,
+  runCommand,
+  checkFalsePositive,
+  checkSuspect,
+  isCommandCovered,
+  classifyFailure,
+  executeTestSuite,
+  parseFrameworkOutput,
+  cmdRunTestSuite,
+  cmdMapResults,
+  inferSeverity,
+  collectManualVerifications,
+  mapResultsToUat,
+  checkNeedsDiagnosis,
+  cmdCheckDiagnosis,
+  cmdPhaseUatStatus,
+  generateTestLog,
+  parseUatForFailedCommands,
+  parseUatForStructuralGaps,
+  rerunFailedTests,
+  cmdRerunFailed,
+};