brain-dev 0.1.0

package/bin/lib/audit.cjs

@@ -0,0 +1,268 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseRequirements } = require('./requirements.cjs');
+const { atomicWriteSync } = require('./state.cjs');
+const { parseRoadmap } = require('./roadmap.cjs');
+const { output, error } = require('./core.cjs');
+
+/**
+ * Build a requirement matrix Map for the given scoped requirement IDs.
+ * Each entry: { required: true, verified: false, built: false }
+ * @param {string[]} scopedReqIds
+ * @returns {Map<string, {required: boolean, verified: boolean, built: boolean}>}
+ */
+function buildRequirementMatrix(scopedReqIds) {
+  const matrix = new Map();
+  for (const reqId of scopedReqIds) {
+    matrix.set(reqId, { required: true, verified: false, built: false });
+  }
+  return matrix;
+}
+
+/**
+ * Walk .brain/phases/VERIFICATION.md files and mark verified=true in matrix.
+ * Uses same regex as complete.cjs: /- \[x\] (\S+)/g
+ * @param {string} brainDir
+ * @param {Map} matrix
+ */
+function crossReferenceVerifications(brainDir, matrix) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return;
+
+  for (const dir of fs.readdirSync(phasesDir)) {
+    const verPath = path.join(phasesDir, dir, 'VERIFICATION.md');
+    if (!fs.existsSync(verPath)) continue;
+
+    const content = fs.readFileSync(verPath, 'utf8');
+    const regex = /- \[x\] (\S+)/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const reqId = match[1];
+      if (matrix.has(reqId)) {
+        matrix.get(reqId).verified = true;
+      }
+    }
+  }
+}
+
+/**
+ * Walk .brain/phases/SUMMARY-*.md files and mark built=true in matrix.
+ * Uses same regex as complete.cjs: /requirements-completed:\s*\[([^\]]*)\]/
+ * @param {string} brainDir
+ * @param {Map} matrix
+ */
+function crossReferenceSummaries(brainDir, matrix) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return;
+
+  for (const dir of fs.readdirSync(phasesDir)) {
+    const phaseDir = path.join(phasesDir, dir);
+    if (!fs.statSync(phaseDir).isDirectory()) continue;
+
+    for (const f of fs.readdirSync(phaseDir)) {
+      if (!/^SUMMARY-\d+\.md$/.test(f)) continue;
+
+      const content = fs.readFileSync(path.join(phaseDir, f), 'utf8');
+      const match = content.match(/requirements-completed:\s*\[([^\]]*)\]/);
+      if (!match) continue;
+
+      const reqIds = match[1].split(',').map(s => s.trim()).filter(Boolean);
+      for (const reqId of reqIds) {
+        if (matrix.has(reqId)) {
+          matrix.get(reqId).built = true;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Find discrepancies in the requirement matrix.
+ * @param {Map} matrix
+ * @returns {Array<{reqId: string, type: string, detail: string}>}
+ */
+function findDiscrepancies(matrix) {
+  const discrepancies = [];
+
+  for (const [reqId, entry] of matrix) {
+    if (entry.required && !entry.verified) {
+      discrepancies.push({
+        reqId,
+        type: 'not-verified',
+        detail: `Requirement ${reqId} exists but has no verification evidence`
+      });
+    }
+    if (entry.required && !entry.built) {
+      discrepancies.push({
+        reqId,
+        type: 'not-built',
+        detail: `Requirement ${reqId} exists but has no summary/build evidence`
+      });
+    }
+    if (!entry.required && entry.verified) {
+      discrepancies.push({
+        reqId,
+        type: 'orphan',
+        detail: `Verification found for ${reqId} but it is not a scoped requirement`
+      });
+    }
+  }
+
+  return discrepancies;
+}
+
+/**
+ * Generate a Markdown audit report.
+ * @param {Map} matrix
+ * @param {Array} discrepancies
+ * @param {string} version
+ * @returns {string}
+ */
+function generateReport(matrix, discrepancies, version) {
+  const total = [...matrix.values()].filter(e => e.required).length;
+  const verified = [...matrix.values()].filter(e => e.required && e.verified).length;
+  const built = [...matrix.values()].filter(e => e.required && e.built).length;
+  const date = new Date().toISOString().slice(0, 10);
+  const verdict = discrepancies.length === 0 ? 'PASS' : 'FAIL';
+
+  const lines = [
+    '---',
+    `version: ${version}`,
+    `date: ${date}`,
+    `total: ${total}`,
+    `verified: ${verified}`,
+    `built: ${built}`,
+    `discrepancy_count: ${discrepancies.length}`,
+    `verdict: ${verdict}`,
+    '---',
+    '',
+    `# Milestone Audit: ${version}`,
+    '',
+    '## Requirement Matrix',
+    '',
+    '| Req | Required | Verified | Built | Status |',
+    '|-----|----------|----------|-------|--------|'
+  ];
+
+  for (const [reqId, entry] of matrix) {
+    const status = entry.required && entry.verified && entry.built
+      ? 'OK'
+      : entry.required ? 'GAP' : 'ORPHAN';
+    lines.push(
+      `| ${reqId} | ${entry.required ? 'Yes' : 'No'} | ${entry.verified ? 'Yes' : 'No'} | ${entry.built ? 'Yes' : 'No'} | ${status} |`
+    );
+  }
+
+  lines.push('');
+
+  if (discrepancies.length > 0) {
+    lines.push('## Discrepancies');
+    lines.push('');
+    for (const d of discrepancies) {
+      lines.push(`- **${d.reqId}** (${d.type}): ${d.detail}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`Verdict: **${verdict}**`);
+  lines.push('');
+  if (verdict === 'PASS') {
+    lines.push('All scoped requirements have both verification and build evidence.');
+  } else {
+    lines.push(`${discrepancies.length} discrepancy(ies) found. Resolve gaps before milestone completion.`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Write audit report file to .brain/audits/.
+ * Creates directory if missing.
+ * @param {string} brainDir
+ * @param {string} version
+ * @param {string} report
+ */
+function writeAuditFile(brainDir, version, report) {
+  const auditsDir = path.join(brainDir, 'audits');
+  if (!fs.existsSync(auditsDir)) {
+    fs.mkdirSync(auditsDir, { recursive: true });
+  }
+  const filePath = path.join(auditsDir, `${version}-audit.md`);
+  atomicWriteSync(filePath, report);
+}
+
+/**
+ * Run the full audit flow.
+ * @param {string} brainDir
+ * @param {object} state - Brain state object
+ * @param {object} opts - Options
+ * @returns {{ action: string, discrepancies: Array, report_path: string, verifiedReqIds: string[] }}
+ */
+function runAudit(brainDir, state, opts = {}) {
+  // 1. Parse requirements
+  const { requirements } = parseRequirements(brainDir);
+  const allReqIds = requirements.map(r => r.id);
+
+  // 2. Scope to completed/verified phases (reuse logic from complete.cjs)
+  const completedPhaseReqs = new Set();
+  try {
+    const roadmap = parseRoadmap(brainDir);
+    for (const phase of roadmap.phases) {
+      if (['Complete', 'complete', 'Verified', 'verified'].includes(phase.status)) {
+        for (const req of phase.requirements) {
+          completedPhaseReqs.add(req);
+        }
+      }
+    }
+  } catch {
+    // If roadmap parse fails, use all requirements
+    allReqIds.forEach(r => completedPhaseReqs.add(r));
+  }
+
+  const scopedReqIds = allReqIds.filter(r => completedPhaseReqs.has(r));
+
+  // 3. Build matrix and cross-reference
+  const matrix = buildRequirementMatrix(scopedReqIds);
+  crossReferenceVerifications(brainDir, matrix);
+  crossReferenceSummaries(brainDir, matrix);
+
+  // 4. Find discrepancies
+  const discrepancies = findDiscrepancies(matrix);
+
+  // 5. Generate and write report
+  const version = state.milestone ? state.milestone.current : 'v1.0';
+  const report = generateReport(matrix, discrepancies, version);
+  writeAuditFile(brainDir, version, report);
+
+  // 6. Collect verifiedReqIds (both verified AND built)
+  const verifiedReqIds = [];
+  for (const [reqId, entry] of matrix) {
+    if (entry.required && entry.verified && entry.built) {
+      verifiedReqIds.push(reqId);
+    }
+  }
+
+  const reportPath = path.join(brainDir, 'audits', `${version}-audit.md`);
+
+  return {
+    action: 'audit-complete',
+    discrepancies,
+    report_path: reportPath,
+    verifiedReqIds
+  };
+}
+
+module.exports = {
+  buildRequirementMatrix,
+  crossReferenceVerifications,
+  crossReferenceSummaries,
+  findDiscrepancies,
+  generateReport,
+  writeAuditFile,
+  runAudit
+};

package/bin/lib/commands/adr.cjs

@@ -0,0 +1,126 @@
+'use strict';
+
+const path = require('node:path');
+const { output, error, success } = require('../core.cjs');
+const { createADR, listADRs, searchADRs } = require('../adr.cjs');
+
+/**
+ * Parse --key value pairs from args array.
+ * @param {string[]} args
+ * @returns {object} Parsed key-value pairs
+ */
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--') && i + 1 < args.length) {
+      const key = args[i].slice(2);
+      flags[key] = args[i + 1];
+      i++;
+    }
+  }
+  return flags;
+}
+
+/**
+ * Show ADR command usage.
+ */
+function showUsage() {
+  const text = [
+    'Usage: brain-dev adr <subcommand> [options]',
+    '',
+    'Subcommands:',
+    '  create              Create a new Architecture Decision Record',
+    '    --title <text>      Decision title (required)',
+    '    --context <text>    Why this decision came up',
+    '    --decision <text>   What was chosen',
+    '    --alternatives <t>  What was rejected',
+    '    --consequences <t>  Impact of the decision',
+    '    --phase <n>         Phase number',
+    '    --plan <n>          Plan number',
+    '',
+    '  list [--phase <n>]  List all ADRs (optionally filtered by phase)',
+    '',
+    '  search <keyword>    Search ADR content by keyword'
+  ].join('\n');
+  console.log(text);
+}
+
+/**
+ * Run the ADR command.
+ * @param {string[]} args - Command arguments
+ * @param {object} opts
+ * @param {string} opts.brainDir - Path to .brain/ directory
+ */
+function run(args = [], opts = {}) {
+  const brainDir = opts && opts.brainDir
+    ? opts.brainDir
+    : path.join(process.cwd(), '.brain');
+
+  const subcommand = args && args[0];
+
+  if (!subcommand || subcommand === 'help') {
+    showUsage();
+    return;
+  }
+
+  switch (subcommand) {
+    case 'create': {
+      const flags = parseFlags(args.slice(1));
+      if (!flags.title) {
+        error('--title is required for adr create');
+        return;
+      }
+      const result = createADR(brainDir, {
+        title: flags.title,
+        context: flags.context || '',
+        decision: flags.decision || '',
+        alternatives: flags.alternatives || '',
+        consequences: flags.consequences || '',
+        phase: flags.phase || '',
+        plan: flags.plan || '',
+        deciders: flags.deciders || 'agent'
+      });
+      output(result, `Created ${result.id} at ${result.path}`);
+      break;
+    }
+
+    case 'list': {
+      const flags = parseFlags(args.slice(1));
+      const adrs = listADRs(brainDir, flags.phase ? { phase: flags.phase } : undefined);
+      if (adrs.length === 0) {
+        output({ adrs: [] }, 'No ADRs found.');
+        return;
+      }
+      const lines = adrs.map(a =>
+        `${String(a.id).padStart(3, '0')}  ${a.status.padEnd(12)} ${a.title}`
+      );
+      output({ adrs }, lines.join('\n'));
+      break;
+    }
+
+    case 'search': {
+      const keyword = args[1];
+      if (!keyword) {
+        error('Usage: brain-dev adr search <keyword>');
+        return;
+      }
+      const results = searchADRs(brainDir, keyword);
+      if (results.length === 0) {
+        output({ results: [] }, `No ADRs matching "${keyword}".`);
+        return;
+      }
+      const lines = results.map(a =>
+        `${String(a.id).padStart(3, '0')}  ${a.status.padEnd(12)} ${a.title}`
+      );
+      output({ results }, lines.join('\n'));
+      break;
+    }
+
+    default:
+      error(`Unknown adr subcommand: '${subcommand}'. Use: create, list, search`);
+      showUsage();
+      break;
+  }
+}
+
+module.exports = { run };

package/bin/lib/commands/complete.cjs

@@ -0,0 +1,270 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState } = require('../state.cjs');
+const { parseRoadmap, writeRoadmap } = require('../roadmap.cjs');
+const { gitTag } = require('../git.cjs');
+const { output, error, success } = require('../core.cjs');
+const audit = require('../audit.cjs');
+const requirements = require('../requirements.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;
+}
+
+/**
+ * Scan phase directory for PLAN and SUMMARY files.
+ * @param {string} phaseDir
+ * @returns {{ plans: number[], summaries: number[] }}
+ */
+function scanPhaseArtifacts(phaseDir) {
+  if (!phaseDir || !fs.existsSync(phaseDir)) return { plans: [], summaries: [] };
+
+  const files = fs.readdirSync(phaseDir);
+  const plans = [];
+  const summaries = [];
+
+  for (const f of files) {
+    const planMatch = f.match(/^PLAN-(\d+)\.md$/);
+    if (planMatch) plans.push(parseInt(planMatch[1], 10));
+
+    const sumMatch = f.match(/^SUMMARY-(\d+)\.md$/);
+    if (sumMatch) summaries.push(parseInt(sumMatch[1], 10));
+  }
+
+  return { plans, summaries };
+}
+
+/**
+ * Extract requirements-completed from SUMMARY frontmatter.
+ * @param {string} content
+ * @returns {string[]}
+ */
+function extractCompletedReqs(content) {
+  const match = content.match(/requirements-completed:\s*\[([^\]]*)\]/);
+  if (!match) return [];
+  return match[1].split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Extract verified requirement IDs from VERIFICATION.md.
+ * @param {string} content
+ * @returns {string[]}
+ */
+function extractVerifiedReqs(content) {
+  const reqs = [];
+  const regex = /- \[x\] (\S+)/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    reqs.push(match[1]);
+  }
+  return reqs;
+}
+
+/**
+ * Extract all requirement IDs from REQUIREMENTS.md.
+ * Looks for ## REQ-ID: patterns.
+ * @param {string} content
+ * @returns {string[]}
+ */
+function extractAllReqIds(content) {
+  const ids = [];
+  const regex = /^## (\S+):/gm;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    ids.push(match[1]);
+  }
+  return ids;
+}
+
+/**
+ * Increment a semver-like version string.
+ * v1.0 -> v1.1, v1.9 -> v1.10
+ * @param {string} version
+ * @returns {string}
+ */
+function incrementVersion(version) {
+  const match = version.match(/^v?(\d+)\.(\d+)$/);
+  if (!match) return 'v1.1';
+  const major = parseInt(match[1], 10);
+  const minor = parseInt(match[2], 10);
+  return `v${major}.${minor + 1}`;
+}
+
+/**
+ * Run the complete command.
+ *
+ * Default (no flags): Perform 3-source audit for milestone completion.
+ * --phase N: Mark a single phase as complete.
+ *
+ * @param {string[]} args
+ * @param {object} [opts] - Options (brainDir, skipGitTag for testing)
+ * @returns {object}
+ */
+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' };
+  }
+
+  // --audit-only: run audit without triggering milestone completion
+  if (args.includes('--audit-only')) {
+    return audit.runAudit(brainDir, state, opts);
+  }
+
+  const phaseIdx = args.indexOf('--phase');
+  if (phaseIdx >= 0) {
+    return handlePhaseComplete(args, phaseIdx, brainDir, state);
+  }
+
+  return handleMilestoneComplete(brainDir, state, args, opts);
+}
+
+/**
+ * Handle --phase N: mark single phase as complete.
+ */
+function handlePhaseComplete(args, phaseIdx, brainDir, state) {
+  const phaseNumber = parseInt(args[phaseIdx + 1], 10);
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+
+  if (!phaseDir) {
+    error(`Phase ${phaseNumber} directory not found.`);
+    return { error: 'phase-not-found' };
+  }
+
+  const { plans, summaries } = scanPhaseArtifacts(phaseDir);
+
+  // Check all plans have summaries
+  const missingPlans = plans.filter(p => !summaries.includes(p));
+  if (missingPlans.length > 0) {
+    error(`Plans not yet executed: ${missingPlans.join(', ')}. Run /brain:execute first.`);
+    return { error: 'incomplete-plans', missing: missingPlans, nextAction: '/brain:execute' };
+  }
+
+  // Check verification was run (VERIFICATION.md should exist)
+  const verificationPath = path.join(phaseDir, 'VERIFICATION.md');
+  if (!fs.existsSync(verificationPath) && state.phase.status !== 'verified') {
+    error(`Phase ${phaseNumber} not verified. Run /brain:verify first.`);
+    return { error: 'not-verified', nextAction: '/brain:verify' };
+  }
+
+  // Mark phase as complete in state (handle both string and object formats)
+  if (Array.isArray(state.phase.phases)) {
+    const idx = state.phase.phases.findIndex(p =>
+      typeof p === 'object' ? p.number === phaseNumber : false
+    );
+    if (idx >= 0 && typeof state.phase.phases[idx] === 'object') {
+      state.phase.phases[idx].status = 'complete';
+    }
+  }
+
+  // Advance to next phase
+  const nextPhase = phaseNumber + 1;
+  const totalPhases = state.phase.total || (Array.isArray(state.phase.phases) ? state.phase.phases.length : 0);
+  const hasNextPhase = totalPhases > 0 && nextPhase <= totalPhases;
+  if (hasNextPhase) {
+    state.phase.current = nextPhase;
+    state.phase.status = 'pending';
+  } else {
+    state.phase.status = 'complete';
+  }
+  writeState(brainDir, state);
+
+  // Update roadmap
+  try {
+    const roadmap = parseRoadmap(brainDir);
+    const roadmapPhase = roadmap.phases.find(p => p.number === phaseNumber);
+    if (roadmapPhase) {
+      roadmapPhase.status = 'Complete';
+    }
+    writeRoadmap(brainDir, roadmap);
+  } catch (e) {
+    error(`Warning: Could not update roadmap: ${e.message}`);
+  }
+
+  const nextActionCmd = hasNextPhase ? '/brain:discuss' : '/brain:complete';
+  const msg = hasNextPhase
+    ? `Phase ${phaseNumber} complete. Next: Phase ${nextPhase}. Run ${nextActionCmd} to continue.`
+    : `Phase ${phaseNumber} complete. All phases done! Run /brain:complete for milestone completion.`;
+  output({ action: 'phase-complete', phase: phaseNumber, nextPhase: hasNextPhase ? nextPhase : null, nextAction: nextActionCmd }, `[brain] ${msg}`);
+  return { action: 'phase-complete', phase: phaseNumber, nextPhase: hasNextPhase ? nextPhase : null, nextAction: nextActionCmd };
+}
+
+/**
+ * Handle milestone completion with 3-source audit.
+ * Now delegates cross-referencing to audit.cjs and wires requirements status updates.
+ */
+function handleMilestoneComplete(brainDir, state, args = [], opts = {}) {
+  // Run the full audit
+  const auditResult = audit.runAudit(brainDir, state, opts);
+  const hasForce = args.includes('--force');
+
+  if (auditResult.discrepancies.length > 0 && !hasForce) {
+    const gaps = auditResult.discrepancies.map(d => d.reqId);
+    const uniqueGaps = [...new Set(gaps)];
+    const msg = [
+      `Gaps detected: ${uniqueGaps.length} requirement(s) not fully covered.`,
+      `Missing: ${uniqueGaps.join(', ')}`,
+      `Run gap closure: /brain:plan --gaps, then /brain:execute, then /brain:verify, then /brain:complete again.`,
+      `Or use --force to override.`
+    ].join('\n');
+
+    output({ action: 'gaps-found', gaps: uniqueGaps, audit: auditResult }, `[brain] ${msg}`);
+    return { action: 'gaps-found', gaps: uniqueGaps, audit: auditResult };
+  }
+
+  // No gaps (or --force override) - proceed with milestone completion
+
+  // Update requirements status for verified requirements
+  for (const reqId of auditResult.verifiedReqIds) {
+    try {
+      requirements.updateStatus(brainDir, reqId, true);
+      requirements.updateTraceability(brainDir, reqId, { status: 'Complete' });
+      output(`Updated requirement ${reqId} to Complete`);
+    } catch (e) {
+      error(`Warning: Could not update requirement ${reqId}: ${e.message}`);
+    }
+  }
+
+  const version = state.milestone.current;
+
+  // Create git tag (unless skipped for testing)
+  if (!opts.skipGitTag) {
+    const projectDir = path.dirname(brainDir);
+    gitTag(version, `Milestone: ${state.milestone.name || version}`, projectDir);
+  }
+
+  // Archive milestone
+  state.milestone.history.push({
+    version,
+    name: state.milestone.name,
+    completed: new Date().toISOString().slice(0, 10)
+  });
+  state.milestone.current = incrementVersion(version);
+  state.milestone.name = null;
+  writeState(brainDir, state);
+
+  const forceWarning = hasForce && auditResult.discrepancies.length > 0
+    ? ' (forced with discrepancies)'
+    : '';
+  const msg = `Milestone ${version} complete!${forceWarning}${opts.skipGitTag ? '' : ' Tagged in git.'}`;
+  output({ action: 'milestone-complete', version, audit: auditResult }, `[brain] ${msg}`);
+  return { action: 'milestone-complete', version, audit: auditResult };
+}
+
+module.exports = { run };