pan-wizard 3.7.10 → 3.10.0

package/pan-wizard-core/bin/lib/verify.cjs

@@ -15,6 +15,12 @@ const {
   BUILTIN_DRIFT_RULES, DRIFT_VERDICTS, BINARY_EXTENSIONS, DRIFT_MAX_FILES, DRIFT_MAX_FILE_SIZE, DRIFT_SEVERITY_WEIGHTS,
 } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible } = require('./utils.cjs');
+// Drift detection lives in verify-drift.cjs; re-exported below so consumers of
+// verify.cjs are unaffected by the decomposition.
+const { runDriftCheck, parseConventionRules, checkFileConventions, calculateDriftScore, getChangedFiles, cmdDriftCheck } = require('./verify-drift.cjs');
+const { collectVerificationStats, countRoadmapPhases, groupGapPatterns, cmdRetro } = require('./verify-retro.cjs');
+const { detectInstalledRuntimes, validateRuntimeInstall, cmdValidateDeployment } = require('./verify-deploy.cjs');
+const { cmdPreflight, cmdDepsValidate } = require('./verify-preflight.cjs');
 
 /**
  * Spot-check files mentioned in summary content.
@@ -1215,6 +1221,26 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   }
 
+  // Check 12 (optional): doc-code link graph (ADR-0027)
+  let linkGraphResult;
+  if (options.links) {
+    const links = require('./links.cjs');
+    const r = links.validateAll(cwd);
+    linkGraphResult = {
+      status: r.summary.status,
+      errors: r.summary.errors,
+      warnings: r.summary.warnings,
+      doc_files_scanned: r.summary.doc_files_scanned,
+      source_files_scanned: r.summary.source_files_scanned,
+      anchors_found: r.summary.anchors_found,
+      forward_links_found: r.summary.forward_links_found,
+      backlink_contracts_checked: r.summary.backlink_contracts_checked,
+    };
+    if (r.summary.errors > 0) {
+      addIssue('warning', 'LINKS_ERR', `Link graph has ${r.summary.errors} errors (broken refs or uncovered backlink contracts)`, 'Run pan-tools links validate for details');
+    }
+  }
+
   const result = {
     status,
     errors,
@@ -1230,6 +1256,9 @@ function cmdValidateHealth(cwd, options, raw) {
   if (options.drift) {
     result.drift_status = driftResult;
   }
+  if (options.links) {
+    result.link_graph = linkGraphResult;
+  }
 
   output(result, raw);
 }
@@ -1290,805 +1319,12 @@ function runFullBuildCheck(cwd) {
   }
 }
 
-/**
- * Pre-flight validation: check execution prerequisites before starting work.
- * Validates state consistency, git cleanliness, blockers, and error patterns.
- * @param {string} cwd - Working directory path
- * @param {string|null} target - Optional target (phase number or 'batch')
- * @param {boolean} raw - If true, output raw value instead of JSON
- * @returns {void}
- */
-function cmdPreflight(cwd, target, raw) {
-  const checks = [];
-  const blockers = [];
-
-  // Check 1: .planning/ directory exists
-  const planDir = planningPath(cwd);
-  if (fileAccessible(planDir)) {
-    checks.push({ name: 'planning_dir', passed: true });
-  } else {
-    checks.push({ name: 'planning_dir', passed: false, detail: '.planning/ directory not found' });
-    blockers.push('.planning/ directory not found — run /pan:new-project');
-  }
-
-  // Check 2: state.md is parseable
-  const statePath = path.join(planDir, STATE_FILE);
-  const stateContent = readStateSafe(statePath);
-  if (stateContent) {
-    checks.push({ name: 'state_readable', passed: true });
-  } else {
-    checks.push({ name: 'state_readable', passed: false, detail: 'state.md not found or unreadable' });
-    blockers.push('state.md not found — run /pan:new-project');
-  }
-
-  // Check 3: no unresolved blockers in state.md
-  if (stateContent) {
-    const blockersMatch = stateContent.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
-    const activeBlockers = [];
-    if (blockersMatch) {
-      const items = blockersMatch[1].match(/^-\s+(.+)$/gm) || [];
-      for (const item of items) {
-        const text = item.replace(/^-\s+/, '').trim();
-        if (text && !/^none$/i.test(text)) {
-          activeBlockers.push(text);
-        }
-      }
-    }
-    if (activeBlockers.length === 0) {
-      checks.push({ name: 'no_blockers', passed: true });
-    } else {
-      checks.push({ name: 'no_blockers', passed: false, detail: activeBlockers.length + ' active blocker(s)' });
-      for (const b of activeBlockers) blockers.push('Blocker: ' + b);
-    }
-  }
-
-  // Check 4: git working tree is clean
-  const gitResult = execGit(cwd, ['status', '--porcelain']);
-  if (gitResult.exitCode !== 0) {
-    checks.push({ name: 'git_clean', passed: true, detail: 'not a git repo or git unavailable' });
-  } else {
-    const dirty = gitResult.stdout.split('\n').filter(l => l.trim()).length;
-    if (dirty === 0) {
-      checks.push({ name: 'git_clean', passed: true });
-    } else {
-      checks.push({ name: 'git_clean', passed: false, detail: dirty + ' uncommitted change(s)' });
-      blockers.push(dirty + ' uncommitted changes — commit or stash before executing');
-    }
-  }
-
-  // Check 5: no known error patterns (check patterns.md exists and has entries)
-  const patternsPath = path.join(planDir, PATTERNS_FILE);
-  let patternCount = 0;
-  try {
-    const patternsContent = fs.readFileSync(patternsPath, 'utf-8');
-    const patternMatches = patternsContent.match(/^### PAT-\d+:/gm);
-    patternCount = patternMatches ? patternMatches.length : 0;
-  } catch { /* no patterns file — that's fine */ }
-  checks.push({ name: 'error_patterns', passed: true, detail: patternCount + ' known pattern(s)' });
-
-  // Check 6: config.json exists
-  const configPath = path.join(planDir, CONFIG_FILE);
-  if (fileAccessible(configPath)) {
-    checks.push({ name: 'config_exists', passed: true });
-  } else {
-    checks.push({ name: 'config_exists', passed: false, detail: 'config.json not found' });
-  }
-
-  // Check 7: target-specific checks
-  if (target && stateContent) {
-    const currentPhaseMatch = stateContent.match(/\*\*Current Phase:\*\*\s*(\S+)/);
-    const currentPhase = currentPhaseMatch ? currentPhaseMatch[1] : null;
-    if (target === 'batch') {
-      // Check that a batch file exists
-      const focusDir = path.join(planDir, 'focus');
-      try {
-        const files = fs.readdirSync(focusDir).filter(f => f.startsWith('batch-') && f.endsWith('.json'));
-        if (files.length > 0) {
-          checks.push({ name: 'batch_exists', passed: true, detail: files[files.length - 1] });
-        } else {
-          checks.push({ name: 'batch_exists', passed: false, detail: 'no batch file found' });
-          blockers.push('No batch file — run /pan:focus-plan first');
-        }
-      } catch {
-        checks.push({ name: 'batch_exists', passed: false, detail: 'focus/ directory not found' });
-        blockers.push('No focus/ directory — run /pan:focus-scan first');
-      }
-    } else {
-      // target is a phase number — check the phase directory exists
-      const phaseResult = findPhaseInternal(cwd, target);
-      if (phaseResult) {
-        checks.push({ name: 'target_phase', passed: true, detail: 'Phase ' + target + ' found' });
-      } else {
-        checks.push({ name: 'target_phase', passed: false, detail: 'Phase ' + target + ' not found' });
-        blockers.push('Phase ' + target + ' directory not found');
-      }
-    }
-  }
-
-  const ready = blockers.length === 0;
-
-  output({
-    ready,
-    target: target || null,
-    checks,
-    blockers,
-    passed: checks.filter(c => c.passed).length,
-    total: checks.length,
-  }, raw, ready ? 'ready' : 'blocked');
-}
-
-/**
- * Dependency graph validation — cross-reference roadmap phases vs disk directories
- * and requirements vs phase summaries to detect drift.
- * @param {string} cwd - Working directory path
- * @param {boolean} raw - If true, output raw value instead of JSON
- * @returns {void}
- */
-function cmdDepsValidate(cwd, raw) {
-  const planDir = planningPath(cwd);
-  const issues = [];
-  const orphanedReqs = [];
-  const missingPhases = [];
-  const orphanedDirs = [];
-
-  // Step 1: Parse roadmap phases
-  const roadmapPath = path.join(planDir, ROADMAP_FILE);
-  const roadmapContent = safeReadFile(roadmapPath);
-  const roadmapPhases = new Map(); // number -> name
-  if (roadmapContent) {
-    const headerRe = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
-    let match;
-    while ((match = headerRe.exec(roadmapContent)) !== null) {
-      roadmapPhases.set(match[1], match[2].trim());
-    }
-  } else {
-    issues.push({ type: 'warning', message: 'roadmap.md not found' });
-  }
-
-  // Step 2: Scan disk phase directories
-  const diskPhases = new Map(); // number -> dirName
-  try {
-    const entries = fs.readdirSync(phasesPath(cwd), { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        const dirMatch = entry.name.match(PHASE_DIR_RE);
-        if (dirMatch) {
-          diskPhases.set(dirMatch[1], entry.name);
-        }
-      }
-    }
-  } catch { /* phases dir missing */ }
-
-  // Step 3: Cross-reference roadmap vs disk
-  for (const [num, name] of roadmapPhases) {
-    if (!diskPhases.has(num)) {
-      missingPhases.push({ number: num, name, source: 'roadmap' });
-      issues.push({ type: 'error', message: 'Phase ' + num + ' (' + name + ') in roadmap but no directory on disk' });
-    }
-  }
-  for (const [num, dirName] of diskPhases) {
-    if (!roadmapPhases.has(num)) {
-      orphanedDirs.push({ number: num, directory: dirName });
-      issues.push({ type: 'warning', message: 'Directory ' + dirName + ' exists on disk but Phase ' + num + ' not found in roadmap' });
-    }
-  }
-
-  // Step 4: Parse requirements
-  const reqPath = path.join(planDir, 'requirements.md');
-  const reqContent = safeReadFile(reqPath);
-  const allReqIds = [];
-  const completedReqIds = new Set();
-  if (reqContent) {
-    // Find all REQ-NN patterns in checkbox lines
-    const reqLines = reqContent.match(/^-\s*\[[ x]\]\s*\*\*([A-Z]+-\d+)\*\*/gmi) || [];
-    for (const line of reqLines) {
-      const idMatch = line.match(/\*\*([A-Z]+-\d+)\*\*/i);
-      if (idMatch) {
-        allReqIds.push(idMatch[1]);
-        if (/\[x\]/i.test(line)) {
-          completedReqIds.add(idMatch[1]);
-        }
-      }
-    }
-  }
-
-  // Step 5: Check requirements traceability — find REQ IDs mentioned in summaries
-  const tracedReqIds = new Set();
-  for (const [, dirName] of diskPhases) {
-    try {
-      const files = fs.readdirSync(path.join(phasesPath(cwd), dirName));
-      for (const file of filterSummaryFiles(files)) {
-        const summaryContent = safeReadFile(path.join(phasesPath(cwd), dirName, file));
-        if (summaryContent) {
-          const mentions = summaryContent.match(/[A-Z]+-\d+/g) || [];
-          for (const id of mentions) {
-            if (allReqIds.includes(id)) tracedReqIds.add(id);
-          }
-        }
-      }
-    } catch { /* unreadable dir */ }
-  }
-
-  // Find requirements that are neither completed nor traced in any summary
-  for (const reqId of allReqIds) {
-    if (!completedReqIds.has(reqId) && !tracedReqIds.has(reqId)) {
-      orphanedReqs.push(reqId);
-      issues.push({ type: 'info', message: 'Requirement ' + reqId + ' not marked complete and not referenced in any summary' });
-    }
-  }
-
-  const valid = issues.filter(i => i.type === 'error').length === 0;
-
-  output({
-    valid,
-    issues,
-    roadmap_phases: roadmapPhases.size,
-    disk_phases: diskPhases.size,
-    requirements_total: allReqIds.length,
-    requirements_completed: completedReqIds.size,
-    orphaned_reqs: orphanedReqs,
-    missing_phases: missingPhases,
-    orphaned_dirs: orphanedDirs,
-  }, raw, valid ? 'valid' : 'issues found');
-}
-
-// ─── Drift detection ─────────────────────────────────────────────────────────
-
-/**
- * Parse convention rules from CONVENTIONS.md markdown content.
- * Extracts anti-pattern rules from prose containing "instead of", "not", "never".
- * Run drift check internally and return result object (no output).
- * Used by cmdValidateHealth --drift.
- */
-function runDriftCheck(cwd) {
-  const conventionsPath = path.join(planningPath(cwd), 'codebase', 'CONVENTIONS.md');
-  const conventionsContent = safeReadFile(conventionsPath);
-  const claudeMdContent = safeReadFile(path.join(cwd, 'CLAUDE.md'));
-  const combined = [conventionsContent, claudeMdContent].filter(Boolean).join('\n');
-  const rules = parseConventionRules(combined || null);
-  const files = getChangedFiles(cwd);
-  const allViolations = [];
-  let filesChecked = 0;
-  for (const filePath of files) {
-    const fullPath = path.join(cwd, filePath);
-    try {
-      const stat = fs.statSync(fullPath);
-      if (stat.size > DRIFT_MAX_FILE_SIZE) continue;
-    } catch { continue; }
-    const content = safeReadFile(fullPath);
-    if (!content) continue;
-    filesChecked++;
-    allViolations.push(...checkFileConventions(filePath, content, rules));
-  }
-  const { score, verdict } = calculateDriftScore(allViolations, filesChecked, rules.length);
-  return { drift_score: score, verdict, violation_count: allViolations.length, files_checked: filesChecked };
-}
-
-/**
- * Always merges with BUILTIN_DRIFT_RULES.
- * @param {string|null} content - Markdown content from CONVENTIONS.md
- * @returns {Array} Array of rule objects {id, antiPattern, message, severity, fileGlob}
- */
-function parseConventionRules(content) {
-  const parsed = [];
-  if (content) {
-    // Match lines with inline code containing negation patterns
-    const lines = content.split(/\r?\n/);
-    for (const line of lines) {
-      // Pattern: "Use X instead of `Y`" or "Never use `Y`" or "Don't use `Y`"
-      const negMatch = line.match(/(?:instead of|never use|don'?t use|avoid|not)\s+`([^`]+)`/i);
-      if (negMatch) {
-        const raw = negMatch[1].trim();
-        try {
-          const antiPattern = new RegExp('\\b' + raw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b');
-          parsed.push({
-            id: 'conv-' + raw.replace(/[^a-zA-Z0-9]/g, '-').toLowerCase().slice(0, 30),
-            antiPattern,
-            message: line.trim().slice(0, 120),
-            severity: 'warning',
-            fileGlob: null,
-          });
-        } catch { /* invalid regex — skip */ }
-      }
-    }
-  }
-  // Merge: parsed + builtins, dedup by id (parsed takes priority)
-  const ids = new Set(parsed.map(r => r.id));
-  for (const rule of BUILTIN_DRIFT_RULES) {
-    if (!ids.has(rule.id)) parsed.push(rule);
-  }
-  return parsed;
-}
-
-/**
- * Check a single file's content against convention rules.
- * @param {string} filePath - Relative file path (for glob matching and output)
- * @param {string} content - File content
- * @param {Array} rules - Convention rules from parseConventionRules
- * @returns {Array} violations [{file, line, rule, message, severity}]
- */
-function checkFileConventions(filePath, content, rules) {
-  const violations = [];
-  const lines = content.split(/\r?\n/);
-  for (const rule of rules) {
-    // Check fileGlob match (simple endsWith check — zero-dep)
-    if (rule.fileGlob && !filePath.endsWith(rule.fileGlob)) continue;
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      // Skip comment-only lines
-      if (/^\s*(\/\/|\/?\*|\*)/.test(line)) continue;
-      if (rule.antiPattern.test(line)) {
-        violations.push({
-          file: toPosix(filePath),
-          line: i + 1,
-          rule: rule.id,
-          message: rule.message,
-          severity: rule.severity,
-        });
-      }
-    }
-  }
-  return violations;
-}
-
-/**
- * Calculate drift score from violations.
- * @param {Array} violations - All violations across checked files
- * @param {number} filesChecked - Number of files checked
- * @param {number} rulesCount - Total rules applied
- * @returns {{score: number, verdict: string}}
- */
-function calculateDriftScore(violations, filesChecked, rulesCount) {
-  if (filesChecked === 0 || rulesCount === 0) return { score: 0, verdict: 'clean' };
-  let weighted = 0;
-  for (const v of violations) {
-    weighted += DRIFT_SEVERITY_WEIGHTS[v.severity] || 0;
-  }
-  const ceiling = filesChecked * rulesCount * 0.3;
-  const score = Math.min(1.0, weighted / Math.max(ceiling, 1));
-  const rounded = Math.round(score * 100) / 100;
-  const verdict = DRIFT_VERDICTS.find(b => rounded <= b.max)?.verdict || 'high';
-  return { score: rounded, verdict };
-}
-
-/**
- * Get list of changed files from git diff.
- * @param {string} cwd - Working directory
- * @param {string} [sinceRef] - Git ref to diff against (default: HEAD)
- * @returns {string[]} Array of relative file paths
- */
-function getChangedFiles(cwd, sinceRef) {
-  const ref = sinceRef || 'HEAD';
-  // Try staged + unstaged first, then diff against ref
-  const result = execGit(cwd, ['diff', '--name-only', ref]);
-  if (result.exitCode !== 0) return [];
-  const stagedResult = execGit(cwd, ['diff', '--name-only', '--cached']);
-  const allFiles = new Set();
-  for (const line of result.stdout.split(/\r?\n/)) {
-    if (line.trim()) allFiles.add(line.trim());
-  }
-  if (stagedResult.exitCode === 0) {
-    for (const line of stagedResult.stdout.split(/\r?\n/)) {
-      if (line.trim()) allFiles.add(line.trim());
-    }
-  }
-  // Filter out binary extensions and limit
-  const filtered = [];
-  for (const f of allFiles) {
-    const ext = path.extname(f).toLowerCase();
-    if (BINARY_EXTENSIONS.has(ext)) continue;
-    filtered.push(f);
-    if (filtered.length >= DRIFT_MAX_FILES) break;
-  }
-  return filtered;
-}
-
-/**
- * Run drift check on changed files against project conventions.
- * @param {string} cwd - Working directory
- * @param {boolean} raw - Raw output mode
- * @param {string[]} args - CLI arguments
- */
-function cmdDriftCheck(cwd, raw, args) {
-  // Parse flags
-  let sinceRef = null;
-  let threshold = 0.5;
-  let specificFiles = null;
-  const verbose = process.env.PAN_VERBOSE === '1';
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--since' && args[i + 1]) { sinceRef = args[++i]; }
-    else if (args[i] === '--threshold' && args[i + 1]) {
-      const t = parseFloat(args[++i]);
-      if (isNaN(t) || t < 0 || t > 1) { error('threshold must be 0.0-1.0'); return; }
-      threshold = t;
-    }
-    else if (args[i] === '--files' && args[i + 1]) { specificFiles = args[++i].split(',').map(f => f.trim()); }
-  }
-
-  // Load convention rules
-  const conventionsPath = path.join(planningPath(cwd), 'codebase', 'CONVENTIONS.md');
-  const conventionsContent = safeReadFile(conventionsPath);
-  const claudeMdContent = safeReadFile(path.join(cwd, 'CLAUDE.md'));
-  const combined = [conventionsContent, claudeMdContent].filter(Boolean).join('\n');
-  const rules = parseConventionRules(combined || null);
-
-  // Get files to check
-  let files;
-  if (specificFiles) {
-    files = specificFiles;
-  } else {
-    files = getChangedFiles(cwd, sinceRef);
-  }
-
-  // Check each file
-  const allViolations = [];
-  let filesChecked = 0;
-  for (const filePath of files) {
-    const fullPath = path.join(cwd, filePath);
-    try {
-      const stat = fs.statSync(fullPath);
-      if (stat.size > DRIFT_MAX_FILE_SIZE) continue;
-    } catch { continue; }
-    const content = safeReadFile(fullPath);
-    if (!content) continue;
-    filesChecked++;
-    const violations = checkFileConventions(filePath, content, rules);
-    allViolations.push(...violations);
-  }
-
-  // Calculate score
-  const { score, verdict } = calculateDriftScore(allViolations, filesChecked, rules.length);
-  const passed = score <= threshold;
-  const summary = filesChecked === 0
-    ? 'no files changed'
-    : rules.length === 0
-      ? 'no conventions loaded'
-      : `drift: ${score} (${verdict}) — ${allViolations.length} violations in ${filesChecked} files`;
-
-  const result = {
-    drift_score: score,
-    verdict,
-    passed,
-    threshold,
-    violations: allViolations,
-    violation_count: allViolations.length,
-    files_checked: filesChecked,
-    conventions_loaded: rules.length,
-    summary,
-  };
-  if (verbose) {
-    const byFile = {};
-    for (const v of allViolations) {
-      if (!byFile[v.file]) byFile[v.file] = [];
-      byFile[v.file].push({ line: v.line, rule: v.rule, message: v.message, severity: v.severity });
-    }
-    result.per_file = byFile;
-  }
-  output(result, raw, summary);
-}
-
-// ─── Retrospective Analysis ─────────────────────────────────────────────────
-
-/**
- * Scan verification files in a phases directory and collect stats.
- * @param {string} phasesDir - Absolute path to phases directory
- * @returns {{ total: number, passed: number, gaps_found: number, human_needed: number, gap_patterns: string[] }}
- */
-function collectVerificationStats(phasesDir) {
-  const stats = { total: 0, passed: 0, gaps_found: 0, human_needed: 0, gap_patterns: [] };
-  let dirs;
-  try { dirs = fs.readdirSync(phasesDir, { withFileTypes: true }); } catch { return stats; }
-  for (const d of dirs) {
-    if (!d.isDirectory()) continue;
-    const phaseDir = path.join(phasesDir, d.name);
-    let files;
-    try { files = fs.readdirSync(phaseDir); } catch { continue; }
-    for (const f of files) {
-      if (!isVerificationFile(f)) continue;
-      stats.total++;
-      const content = safeReadFile(path.join(phaseDir, f));
-      if (!content) continue;
-      const fm = extractFrontmatter(content);
-      const status = (fm.status || '').toLowerCase();
-      if (status === 'passed') stats.passed++;
-      else if (status === 'gaps_found') stats.gaps_found++;
-      else if (status === 'human_needed') stats.human_needed++;
-      // Extract gap descriptions from ## Gaps section
-      const gapsMatch = content.match(/## Gaps[\s\S]*?(?=\n## |$)/);
-      if (gapsMatch) {
-        const lines = gapsMatch[0].split('\n').filter(l => l.match(/^[-*]\s+/));
-        for (const line of lines) {
-          const desc = line.replace(/^[-*]\s+/, '').trim();
-          if (desc) stats.gap_patterns.push(desc);
-        }
-      }
-    }
-  }
-  return stats;
-}
-
-/**
- * Count phases from roadmap: total planned, completed, and decimal (gap closure) phases.
- * @param {string} roadmapContent - Roadmap file content
- * @returns {{ planned: number, completed: number, decimal_phases: number }}
- */
-function countRoadmapPhases(roadmapContent) {
-  const result = { planned: 0, completed: 0, decimal_phases: 0 };
-  const checkboxRe = /- \[([ x])\]\s*(?:\*\*)?Phase\s+(\d+[A-Z]?(?:\.\d+)*)/gi;
-  let m;
-  while ((m = checkboxRe.exec(roadmapContent)) !== null) {
-    result.planned++;
-    if (m[1] === 'x') result.completed++;
-    if (m[2].includes('.')) result.decimal_phases++;
-  }
-  return result;
-}
-
-/**
- * Group gap patterns by similarity (simple keyword grouping).
- * @param {string[]} patterns - Raw gap descriptions
- * @returns {Array<{pattern: string, count: number}>}
- */
-function groupGapPatterns(patterns) {
-  const groups = {};
-  for (const p of patterns) {
-    const key = p.toLowerCase().replace(/[^a-z0-9\s]/g, '').trim();
-    const words = key.split(/\s+/).slice(0, 3).join(' ');
-    groups[words] = (groups[words] || 0) + 1;
-  }
-  return Object.entries(groups)
-    .map(([pattern, count]) => ({ pattern, count }))
-    .sort((a, b) => b.count - a.count)
-    .slice(0, 10);
-}
-
-/**
- * Milestone retrospective — analyze historical .planning/ data for process improvement.
- * @param {string} cwd - Working directory
- * @param {boolean} raw - Raw output flag
- */
-function cmdRetro(cwd, raw, args) {
-  const roadmapPath = path.join(planningPath(cwd), ROADMAP_FILE);
-  const roadmapContent = safeReadFile(roadmapPath);
-  if (!roadmapContent) {
-    return output({ error: 'roadmap.md not found' }, raw, 'roadmap.md not found');
-  }
-
-  const phases = countRoadmapPhases(roadmapContent);
-  const pDir = phasesPath(cwd);
-  const verification = collectVerificationStats(pDir);
-  const gapGroups = groupGapPatterns(verification.gap_patterns);
-
-  // Estimation accuracy: planned phases vs actual (including decimal gap closures)
-  const basePlanned = phases.planned - phases.decimal_phases;
-  const estimationAccuracy = basePlanned > 0
-    ? Math.round((basePlanned / phases.planned) * 100)
-    : 100;
-
-  const result = {
-    phases_planned: phases.planned,
-    phases_completed: phases.completed,
-    phases_decimal: phases.decimal_phases,
-    estimation_accuracy_pct: estimationAccuracy,
-    verifications_total: verification.total,
-    verifications_passed_first_try: verification.passed,
-    verifications_gaps_found: verification.gaps_found,
-    verifications_human_needed: verification.human_needed,
-    first_try_rate_pct: verification.total > 0
-      ? Math.round((verification.passed / verification.total) * 100)
-      : null,
-    common_gap_patterns: gapGroups,
-  };
-
-  // E-4: optional memory write. Top gap patterns become lessons for pan-planner
-  // (they surface what plans routinely miss). First-try rate deltas feed
-  // pan-verifier memory.
-  const argsList = Array.isArray(args) ? args : [];
-  if (argsList.includes('--write-memory')) {
-    const { appendMemory } = require('./memory.cjs');
-    const lessons_written = { 'pan-planner': 0, 'pan-verifier': 0 };
-    const maxIdx = argsList.indexOf('--max');
-    const maxLessons = maxIdx !== -1 && argsList[maxIdx + 1]
-      ? Math.max(1, Math.min(10, Number(argsList[maxIdx + 1]) || 3))
-      : 3;
-
-    // Top N gap patterns → planner memory as single-line lessons.
-    const top = gapGroups.slice(0, maxLessons);
-    for (const g of top) {
-      const lesson = `Recurring plan gap (${g.count}x across phases): "${g.pattern}" — factor into plan-checker inputs`;
-      const r = appendMemory(cwd, 'pan-planner', lesson);
-      if (r.appended) lessons_written['pan-planner'] += 1;
-    }
-
-    // Low first-try rate → verifier memory.
-    if (verification.total >= 3 && result.first_try_rate_pct != null && result.first_try_rate_pct < 60) {
-      const lesson = `First-try verification rate ${result.first_try_rate_pct}% over ${verification.total} runs — tighten verification criteria and pre-exec checks`;
-      const r = appendMemory(cwd, 'pan-verifier', lesson);
-      if (r.appended) lessons_written['pan-verifier'] += 1;
-    }
-
-    result.memory = { wrote: lessons_written, max: maxLessons };
-  }
-
-  const rawLines = [
-    `Phases: ${phases.completed}/${phases.planned} completed (${phases.decimal_phases} gap closures)`,
-    `Estimation accuracy: ${estimationAccuracy}%`,
-    `Verifications: ${verification.passed}/${verification.total} passed first try`,
-    `Gaps found: ${verification.gaps_found}, Human needed: ${verification.human_needed}`,
-  ];
-  if (gapGroups.length > 0) {
-    rawLines.push('Common gap patterns:');
-    for (const g of gapGroups) rawLines.push(`  - ${g.pattern} (${g.count}x)`);
-  }
-  if (result.memory) {
-    rawLines.push(`Memory: wrote ${result.memory.wrote['pan-planner']} planner + ${result.memory.wrote['pan-verifier']} verifier lessons`);
-  }
-
-  output(result, raw, rawLines.join('\n'));
-}
-
-// ─── Deployment Validation ──────────────────────────────────────────────────
-
-/**
- * Detect which PAN runtimes are installed in cwd.
- * @param {string} cwd
- * @returns {Array<{runtime: string, configDir: string}>}
- */
-function detectInstalledRuntimes(cwd) {
-  const RUNTIME_DIRS = [
-    { runtime: 'claude', configDir: '.claude' },
-    { runtime: 'opencode', configDir: '.opencode' },
-    { runtime: 'gemini', configDir: '.gemini' },
-    { runtime: 'codex', configDir: '.codex' },
-    { runtime: 'copilot', configDir: '.github' },
-  ];
-  const found = [];
-  for (const rt of RUNTIME_DIRS) {
-    const manifestPath = path.join(cwd, rt.configDir, 'pan-file-manifest.json');
-    try {
-      fs.accessSync(manifestPath);
-      found.push(rt);
-    } catch (_) { /* not installed */ }
-  }
-  return found;
-}
-
-/**
- * Validate a single PAN runtime installation.
- * Checks: manifest files exist, hashes match, settings integrity.
- * @param {string} cwd
- * @param {string} configDir - e.g. '.claude'
- * @param {string} runtime - e.g. 'claude'
- * @returns {{ status: string, version: string, total_files: number, missing: string[], modified: string[], orphaned: string[], settings_ok: boolean, settings_issues: string[] }}
- */
-function validateRuntimeInstall(cwd, configDir, runtime) {
-  const crypto = require('crypto');
-  const baseDir = path.join(cwd, configDir);
-  const manifestPath = path.join(baseDir, 'pan-file-manifest.json');
-
-  let manifest;
-  try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-  } catch (e) {
-    return { status: 'broken', version: null, error: `Cannot read manifest: ${e.message}`, total_files: 0, missing: [], modified: [], orphaned: [], settings_ok: false, settings_issues: ['manifest unreadable'] };
-  }
-
-  const missing = [];
-  const modified = [];
-  const files = manifest.files || {};
-  const totalFiles = Object.keys(files).length;
+// ─── Preflight + deps validation — extracted to verify-preflight.cjs (re-exported below)
 
-  for (const [relPath, expectedHash] of Object.entries(files)) {
-    const absPath = path.join(baseDir, relPath);
-    try {
-      const content = fs.readFileSync(absPath);
-      const actualHash = crypto.createHash('sha256').update(content).digest('hex');
-      if (actualHash !== expectedHash) {
-        modified.push(relPath);
-      }
-    } catch (_) {
-      missing.push(relPath);
-    }
-  }
+// ─── Drift detection — extracted to verify-drift.cjs (re-exported below) ─────
 
-  // Check settings integrity (hook paths resolve to real files)
-  const settingsIssues = [];
-  const settingsFile = runtime === 'copilot' ? 'config.json' : 'settings.json';
-  const settingsPath = path.join(baseDir, settingsFile);
-  let settingsOk = true;
-  try {
-    const settingsContent = fs.readFileSync(settingsPath, 'utf8');
-    const settings = JSON.parse(settingsContent);
-    // Check hook paths in settings
-    // Collect all hook command strings from settings
-    const hookCommands = [];
-    const hooks = settings.hooks;
-    if (hooks && typeof hooks === 'object') {
-      for (const hookArr of Object.values(hooks)) {
-        if (!Array.isArray(hookArr)) continue;
-        for (const hook of hookArr) {
-          if (hook.command) hookCommands.push(hook.command);
-        }
-      }
-    }
-    // Copilot/Gemini statusLine
-    if (settings.statusLine && settings.statusLine.command) {
-      hookCommands.push(settings.statusLine.command);
-    }
-    // Claude statusline
-    if (settings.statusline && settings.statusline.command) {
-      hookCommands.push(settings.statusline.command);
-    }
-    for (const cmd of hookCommands) {
-      const parts = cmd.split(/\s+/);
-      const hookFile = parts.find(p => p.endsWith('.js'));
-      if (hookFile) {
-        // Hook paths are relative to cwd, not to config dir
-        const resolvedPath = path.isAbsolute(hookFile) ? hookFile : path.join(cwd, hookFile);
-        try { fs.accessSync(resolvedPath); } catch (_) {
-          settingsIssues.push(`Hook path not found: ${hookFile}`);
-          settingsOk = false;
-        }
-      }
-    }
-  } catch (_) {
-    // No settings file is OK for some runtimes (codex, opencode)
-    if (runtime !== 'codex' && runtime !== 'opencode') {
-      settingsIssues.push(`${settingsFile} missing or unreadable`);
-      settingsOk = false;
-    }
-  }
-
-  const status = missing.length > 0 ? 'broken' : modified.length > 0 ? 'modified' : 'clean';
-
-  return {
-    status,
-    version: manifest.version || null,
-    total_files: totalFiles,
-    missing,
-    modified,
-    orphaned: [],
-    settings_ok: settingsOk,
-    settings_issues: settingsIssues,
-  };
-}
-
-/**
- * CLI command: validate deployment
- * Validates PAN installations in the current directory.
- * @param {string} cwd
- * @param {boolean} raw
- */
-function cmdValidateDeployment(cwd, raw) {
-  const runtimes = detectInstalledRuntimes(cwd);
-  if (runtimes.length === 0) {
-    output({ error: 'No PAN installations found in this directory' }, raw);
-    return;
-  }
-
-  const results = {};
-  let overallStatus = 'clean';
-
-  for (const { runtime, configDir } of runtimes) {
-    const result = validateRuntimeInstall(cwd, configDir, runtime);
-    results[runtime] = result;
-    if (result.status === 'broken') overallStatus = 'broken';
-    else if (result.status === 'modified' && overallStatus !== 'broken') overallStatus = 'modified';
-  }
-
-  const summary = {
-    status: overallStatus,
-    runtimes_found: runtimes.length,
-    runtimes: results,
-  };
-
-  const rawLines = [`Deployment status: ${overallStatus} (${runtimes.length} runtimes)`];
-  for (const [rt, r] of Object.entries(results)) {
-    rawLines.push(`  ${rt}: ${r.status} (${r.total_files} files, ${r.missing.length} missing, ${r.modified.length} modified)`);
-  }
-
-  output(summary, raw, rawLines.join('\n'));
-}
+// ─── Retrospective analysis — extracted to verify-retro.cjs (re-exported below)
+// ─── Deployment validation — extracted to verify-deploy.cjs (re-exported below)
 
 module.exports = {
   cmdVerifySummary,