brain-dev 0.1.0

package/bin/lib/commands/verify.cjs

@@ -0,0 +1,504 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState, atomicWriteSync } = require('../state.cjs');
+const { loadTemplate, interpolate } = require('../templates.cjs');
+const { getAgent, resolveModel } = require('../agents.cjs');
+const { logEvent } = require('../logger.cjs');
+const { output, error, success } = require('../core.cjs');
+const antiPatterns = require('../anti-patterns.cjs');
+const { buildDebuggerSpawnInstructions } = require('./execute.cjs');
+
+/**
+ * Find a phase directory under .brain/phases/ matching a phase number.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null}
+ */
+function findPhaseDir(brainDir, phaseNumber) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  const padded = String(phaseNumber).padStart(2, '0');
+  const match = fs.readdirSync(phasesDir).find(d => d.startsWith(`${padded}-`));
+  return match ? path.join(phasesDir, match) : null;
+}
+
+/**
+ * Parse YAML-ish frontmatter from a plan file to extract must_haves.
+ * This is a lightweight parser -- not a full YAML parser.
+ * @param {string} content - Plan file content
+ * @returns {object} { truths: string[], artifacts: object[], key_links: object[] }
+ */
+function extractMustHaves(content) {
+  const result = { truths: [], artifacts: [], key_links: [] };
+
+  // Extract truths
+  const truthsMatch = content.match(/truths:\s*\n((?:\s+-\s+"[^"]*"\n?)*)/);
+  if (truthsMatch) {
+    const lines = truthsMatch[1].match(/"([^"]*)"/g);
+    if (lines) {
+      result.truths = lines.map(l => l.replace(/"/g, ''));
+    }
+  }
+
+  // Extract artifacts
+  const artifactsMatch = content.match(/artifacts:\s*\n((?:\s+-\s+(?:path|provides|exports).*\n?)*)/);
+  if (artifactsMatch) {
+    const paths = artifactsMatch[1].match(/path:\s*"([^"]*)"/g);
+    if (paths) {
+      result.artifacts = paths.map(p => ({
+        path: p.replace(/path:\s*"([^"]*)"/, '$1')
+      }));
+    }
+  }
+
+  // Extract key_links
+  const keyLinksMatch = content.match(/key_links:\s*\n((?:\s+-\s+(?:from|to|via|pattern).*\n?)*)/);
+  if (keyLinksMatch) {
+    const froms = keyLinksMatch[1].match(/from:\s*"([^"]*)"/g);
+    if (froms) {
+      result.key_links = froms.map(f => ({
+        from: f.replace(/from:\s*"([^"]*)"/, '$1')
+      }));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract phase-modified file paths from PLAN and SUMMARY frontmatter.
+ * @param {string[]} planFiles - Full paths to plan files
+ * @param {string[]} summaryFiles - Full paths to summary files
+ * @returns {string[]} Deduplicated array of file paths
+ */
+function extractPhaseFiles(planFiles, summaryFiles) {
+  const files = new Set();
+
+  for (const planPath of planFiles) {
+    const content = fs.readFileSync(planPath, 'utf8');
+    // Extract files_modified from frontmatter
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+      const fm = fmMatch[1];
+      const fmIdx = fm.indexOf('files_modified:');
+      if (fmIdx >= 0) {
+        const afterFm = fm.slice(fmIdx + 'files_modified:'.length);
+        const lines = afterFm.split('\n');
+        for (const line of lines) {
+          const itemMatch = line.match(/^\s+-\s+(.+)/);
+          if (itemMatch) {
+            files.add(itemMatch[1].trim());
+          } else if (line.trim() && !line.match(/^\s+-/) && !line.match(/^\s*$/)) {
+            break; // Hit next YAML key
+          }
+        }
+      }
+    }
+  }
+
+  for (const summaryPath of summaryFiles) {
+    let content;
+    try {
+      content = fs.readFileSync(summaryPath, 'utf8');
+    } catch {
+      continue;
+    }
+    // Extract key-files section from SUMMARY frontmatter
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+      const fm = fmMatch[1];
+      const kfIdx = fm.indexOf('key-files:');
+      if (kfIdx >= 0) {
+        const afterKf = fm.slice(kfIdx + 'key-files:'.length);
+        const lines = afterKf.split('\n');
+        for (const line of lines) {
+          const itemMatch = line.match(/^\s+-\s+(.+)/);
+          if (itemMatch) {
+            files.add(itemMatch[1].trim().replace(/^["']|["']$/g, ''));
+          } else if (line.trim() && !line.match(/^\s+-/) && !line.match(/^\s*$/) && !line.match(/^\s+\w+:/)) {
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  return [...files];
+}
+
+/**
+ * Format anti-pattern scan results for template interpolation.
+ * @param {{ findings: object[], blockers: object[], warnings: object[] }} results
+ * @returns {string} Formatted markdown string
+ */
+function formatAntiPatternResults(results) {
+  if (results.findings.length === 0) return 'No anti-patterns detected.';
+  const lines = ['### Anti-Pattern Scan Results', ''];
+  lines.push(`**Blockers:** ${results.blockers.length}`);
+  lines.push(`**Warnings:** ${results.warnings.length}`);
+  lines.push('');
+  for (const f of results.findings) {
+    lines.push(`- [${f.severity}] ${f.name} in ${f.file}:${f.line}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Run the verify command.
+ *
+ * Default: Generate verifier instructions for current phase.
+ * --phase N: Target specific phase.
+ * --save-results <json>: Save verification results and update state.
+ *
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir for testing)
+ * @returns {object} Structured result
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    error("No brain state found. Run 'brain-dev init' first.");
+    return { error: 'no-state' };
+  }
+
+  // Check for --log-recovery mode
+  const logRecoveryIdx = args.indexOf('--log-recovery');
+  if (logRecoveryIdx >= 0) {
+    return handleLogRecovery(args, logRecoveryIdx, brainDir, state);
+  }
+
+  // Check for --save-results mode
+  const saveIdx = args.indexOf('--save-results');
+  if (saveIdx >= 0) {
+    return handleSaveResults(args, saveIdx, brainDir, state);
+  }
+
+  // Parse --auto-recover flag
+  const autoRecover = args.includes('--auto-recover');
+
+  // Determine phase
+  const phaseIdx = args.indexOf('--phase');
+  const phaseNumber = phaseIdx >= 0
+    ? parseInt(args[phaseIdx + 1], 10)
+    : state.phase.current;
+
+  // Find phase directory
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  if (!phaseDir) {
+    error(`Phase ${phaseNumber} directory not found.`);
+    return { error: 'phase-not-found' };
+  }
+
+  // Scan for PLAN-*.md files and extract must_haves from each
+  const files = fs.readdirSync(phaseDir);
+  const planFiles = files.filter(f => /^PLAN-\d+\.md$/.test(f)).sort();
+
+  const combinedMustHaves = { truths: [], artifacts: [], key_links: [] };
+
+  for (const planFile of planFiles) {
+    const content = fs.readFileSync(path.join(phaseDir, planFile), 'utf8');
+    const mustHaves = extractMustHaves(content);
+    combinedMustHaves.truths.push(...mustHaves.truths);
+    combinedMustHaves.artifacts.push(...mustHaves.artifacts);
+    combinedMustHaves.key_links.push(...mustHaves.key_links);
+  }
+
+  // Scan for SUMMARY-*.md files for cross-referencing
+  const summaryFiles = files.filter(f => /^SUMMARY-\d+\.md$/.test(f)).sort();
+  const summaryPaths = summaryFiles.map(f => path.join(phaseDir, f));
+
+  // Extract phase-modified files for anti-pattern scanning
+  const planFullPaths = planFiles.map(f => path.join(phaseDir, f));
+  const phaseFiles = extractPhaseFiles(planFullPaths, summaryPaths);
+
+  // Run anti-pattern scan on phase files
+  const projectDir = path.dirname(brainDir);
+  const apResults = antiPatterns.scanFiles(projectDir, { files: phaseFiles });
+
+  // Build Nyquist section based on state config
+  const nyquistEnabled = state.workflow?.nyquist_validation ?? false;
+  const nyquistInstructions = [
+    'For each must_have truth, search test files for a matching test:',
+    '- Extract key words from the truth statement (ignore stop words: can, the, a, is, are, and, or, to, in, for, with)',
+    '- Search test file describe/it/test blocks for 60%+ keyword overlap',
+    '- Report coverage ratio: N truths with matching tests / M total truths'
+  ].join('\n');
+  const nyquistSection = nyquistEnabled ? nyquistInstructions : 'Nyquist validation not enabled.';
+
+  // Build verification output path
+  const outputPath = path.join(phaseDir, 'VERIFICATION.md');
+
+  // Get verifier agent metadata and resolve model
+  const verifierAgent = getAgent('verifier');
+  const model = resolveModel('verifier', state);
+
+  // Log spawn event
+  logEvent(brainDir, phaseNumber, {
+    type: 'spawn',
+    agent: 'verifier',
+    truths: combinedMustHaves.truths.length,
+    artifacts: combinedMustHaves.artifacts.length,
+    key_links: combinedMustHaves.key_links.length
+  });
+
+  // Load verifier template and interpolate
+  const template = loadTemplate('verifier');
+  const mustHavesFormatted = [
+    '**Truths:**',
+    ...combinedMustHaves.truths.map(t => `- ${t}`),
+    '',
+    '**Artifacts:**',
+    ...combinedMustHaves.artifacts.map(a => `- ${a.path}`),
+    '',
+    '**Key Links:**',
+    ...combinedMustHaves.key_links.map(k => `- ${k.from}`)
+  ].join('\n');
+
+  const prompt = interpolate(template, {
+    must_haves: mustHavesFormatted,
+    output_path: outputPath,
+    anti_pattern_results: formatAntiPatternResults(apResults),
+    nyquist_section: nyquistSection
+  });
+
+  // Read depth config from state (defaults to 'deep' for backward compatibility)
+  const depthConfig = state.depth || 'deep';
+  const depthLevelCount = depthConfig === 'shallow' ? 1 : depthConfig === 'standard' ? 2 : 3;
+
+  const depthLevelDescriptions = [
+    '- **Level 1 (Exists):** File exists and is non-empty',
+    '- **Level 2 (Substantive):** Contains real implementation, no stubs or TODO-only content',
+    '- **Level 3 (Wired):** Properly imported and consumed by dependent modules'
+  ];
+
+  // Append depth and scoring instructions
+  const depthInstruction = [
+    '',
+    `## Depth Levels (configured: ${depthConfig})`,
+    '',
+    `Apply ${depthLevelCount} verification depth level${depthLevelCount > 1 ? 's' : ''} to each artifact:`,
+    ...depthLevelDescriptions.slice(0, depthLevelCount),
+    '',
+    '## Scoring',
+    '',
+    'Report results as: must_haves_verified / must_haves_total',
+    'Status levels: passed (100%), gaps_found (<100%), human_needed (automated passed, human gate pending)'
+  ].join('\n');
+
+  // Append SUMMARY.md cross-reference paths
+  const summarySection = summaryPaths.length > 0
+    ? '\n\n## SUMMARY.md Cross-References\n\n' + summaryPaths.map(s => `- ${s}`).join('\n')
+    : '';
+
+  const fullPrompt = prompt + depthInstruction + summarySection;
+
+  // Update state to verifying
+  state.phase.status = 'verifying';
+  writeState(brainDir, state);
+
+  const result = {
+    action: 'verify-phase',
+    phase: phaseNumber,
+    must_haves: combinedMustHaves,
+    output_path: outputPath,
+    prompt: fullPrompt,
+    model,
+    depth_levels: depthLevelCount,
+    depth_config: depthConfig,
+    scoring: true,
+    summary_paths: summaryPaths,
+    anti_pattern_scan: apResults
+  };
+
+  // Add recovery instructions when --auto-recover is set
+  if (autoRecover) {
+    const recoveryInstructions = buildRecoveryInstructions(phaseNumber, brainDir, state);
+    result.recovery = {
+      enabled: true,
+      max_cycles: 3,
+      instructions: recoveryInstructions,
+      buildDebuggerForGap: (gapSlug, errorCtx, taskCtx) =>
+        buildDebuggerSpawnInstructions(gapSlug, errorCtx, taskCtx, '', state)
+    };
+
+    // Log recovery config event
+    logEvent(brainDir, phaseNumber, {
+      type: 'recovery_config',
+      auto_recover: true,
+      max_cycles: 3
+    });
+  }
+
+  const humanLines = [
+    `[brain] Verifier instructions generated for Phase ${phaseNumber}`,
+    `[brain] Truths: ${combinedMustHaves.truths.length}`,
+    `[brain] Artifacts: ${combinedMustHaves.artifacts.length}`,
+    `[brain] Model: ${model}`,
+    `[brain] Depth: ${depthConfig} (${depthLevelCount} level${depthLevelCount > 1 ? 's' : ''})`,
+    `[brain] Output: ${outputPath}`,
+    '',
+    fullPrompt
+  ];
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+/**
+ * Handle --save-results: write VERIFICATION.md and update state.
+ */
+function handleSaveResults(args, saveIdx, brainDir, state) {
+  const resultsJson = args[saveIdx + 1];
+  if (!resultsJson) {
+    error('--save-results requires a JSON argument');
+    return { error: 'missing-argument' };
+  }
+
+  let results;
+  try {
+    results = JSON.parse(resultsJson);
+  } catch {
+    error('Invalid JSON for --save-results');
+    return { error: 'invalid-json' };
+  }
+  if (!results || typeof results !== 'object') {
+    error('--save-results requires a JSON object');
+    return { error: 'invalid-json' };
+  }
+
+  // Determine phase dir
+  const phaseNumber = state.phase.current;
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+
+  if (phaseDir) {
+    // Write VERIFICATION.md
+    const lines = [
+      '# Verification Results',
+      '',
+      `Phase: ${phaseNumber}`,
+      `Overall: ${results.passed ? 'PASSED' : 'FAILED'}`,
+      '',
+      '## Checks',
+      ''
+    ];
+
+    if (Array.isArray(results.checks)) {
+      for (const check of results.checks) {
+        if (!check || typeof check !== 'object') continue;
+        lines.push(`- [${check.passed ? 'x' : ' '}] ${check.name || 'unknown'} (${check.level || '?'})`);
+      }
+    }
+
+    lines.push('');
+    atomicWriteSync(path.join(phaseDir, 'VERIFICATION.md'), lines.join('\n'));
+  }
+
+  // Update state
+  state.phase.status = results.passed ? 'verified' : 'verification-failed';
+  writeState(brainDir, state);
+
+  const msg = results.passed
+    ? 'Verification passed! Run /brain:complete to finalize.'
+    : 'Verification failed. Fix gaps and re-verify.';
+
+  const nextAction = results.passed ? '/brain:complete' : '/brain:execute';
+  output({ action: 'results-saved', passed: results.passed, nextAction }, `[brain] ${msg}`);
+  return { action: 'results-saved', passed: results.passed, nextAction };
+}
+
+/**
+ * Build recovery protocol instructions for the verifier agent.
+ * These instructions tell the orchestrator how to handle gaps with debugger agents.
+ *
+ * @param {number} phaseNumber
+ * @param {string} brainDir
+ * @param {object} state
+ * @returns {string} Markdown instruction block
+ */
+function buildRecoveryInstructions(phaseNumber, brainDir, state) {
+  return [
+    '## Recovery Protocol',
+    '',
+    'When verification finds gaps, enter autonomous recovery mode:',
+    '',
+    '### Recovery Loop (max 3 cycles)',
+    '',
+    'For each cycle (1 to 3):',
+    '1. Identify all unresolved gaps from verification results',
+    '2. For each gap, spawn a debugger agent using `brain-dev execute --spot-check` context:',
+    '   - Pass the gap description as error context',
+    '   - Pass the must_have truth/artifact as task context',
+    '   - The debugger will diagnose and fix the issue',
+    '3. After all debuggers complete, re-verify: `brain-dev verify --phase ' + phaseNumber + ' --save-results`',
+    '4. Log progress: `brain-dev verify --log-recovery \'{"type":"re_verify","cycle":N,"passed":false,"remaining_gaps":M}\'`',
+    '',
+    '### Non-Convergence Detection',
+    '',
+    'Track gap count between cycles. If the gap count is not decreasing between',
+    'cycle N and cycle N+1 (gaps stay same or increase), trigger early escalation',
+    'after cycle 2 instead of waiting for cycle 3.',
+    '',
+    '### Escalation',
+    '',
+    'After 3 failed cycles (or early escalation on non-convergence):',
+    '- Output remaining gaps with descriptions',
+    '- Suggest: "Run `/brain:plan --gaps` to create targeted fix plans for remaining gaps"',
+    '- Log: `brain-dev verify --log-recovery \'{"type":"recovery_escalated","cycles":N,"remaining_gaps":["gap-slug"]}\'`',
+    '',
+    '### JSONL Logging',
+    '',
+    'Log each recovery event via CLI:',
+    '- `brain-dev verify --log-recovery \'{"type":"recovery_start","cycle":1,"gaps":N}\'`',
+    '- `brain-dev verify --log-recovery \'{"type":"debugger_spawn","cycle":1,"gap":"gap-slug"}\'`',
+    '- `brain-dev verify --log-recovery \'{"type":"debugger_result","cycle":1,"gap":"gap-slug","status":"resolved"}\'`',
+    '- `brain-dev verify --log-recovery \'{"type":"re_verify","cycle":1,"passed":false,"remaining_gaps":N}\'`',
+    '- `brain-dev verify --log-recovery \'{"type":"recovery_complete","cycles":N,"final_status":"passed"}\'`'
+  ].join('\n');
+}
+
+/**
+ * Handle --log-recovery: log a recovery event to phase JSONL.
+ *
+ * @param {string[]} args
+ * @param {number} logRecoveryIdx
+ * @param {string} brainDir
+ * @param {object} state
+ * @returns {object}
+ */
+function handleLogRecovery(args, logRecoveryIdx, brainDir, state) {
+  const eventJson = args[logRecoveryIdx + 1];
+  if (!eventJson) {
+    error('--log-recovery requires a JSON argument');
+    return { error: 'missing-argument' };
+  }
+
+  let event;
+  try {
+    event = JSON.parse(eventJson);
+  } catch {
+    error('Invalid JSON for --log-recovery');
+    return { error: 'invalid-json' };
+  }
+
+  // Determine phase
+  const phaseIdx = args.indexOf('--phase');
+  const phaseNumber = phaseIdx >= 0
+    ? parseInt(args[phaseIdx + 1], 10)
+    : state.phase.current;
+
+  logEvent(brainDir, phaseNumber, event);
+
+  if (!event || typeof event !== 'object') {
+    error('--log-recovery requires a JSON object, not null/primitive');
+    return { error: 'invalid-json' };
+  }
+  output({ action: 'recovery-logged', event }, `[brain] Recovery event logged: ${event.type || 'unknown'}`);
+  return { action: 'recovery-logged', event };
+}
+
+module.exports = { run };