pan-wizard 3.8.0 → 3.12.0

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

@@ -0,0 +1,181 @@
+/**
+ * Verify / Deployment validation — manifest + settings integrity per runtime.
+ * Extracted from verify.cjs (IMPROVEMENT-TODO P2 module decomposition);
+ * verify.cjs re-exports everything here, so consumers are unaffected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output } = require('./core.cjs');
+
+/**
+ * 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;
+
+  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);
+    }
+  }
+
+  // Check settings integrity (hook paths resolve to real files).
+  // Copilot's user-editable settings moved to .github/copilot/settings.json
+  // (2026-06; .github/config.json was never a Copilot read path) and the file
+  // is optional — hooks live in .github/hooks/pan.json, so absence is fine.
+  const settingsIssues = [];
+  const settingsPath = runtime === 'copilot'
+    ? path.join(baseDir, 'copilot', 'settings.json')
+    : path.join(baseDir, 'settings.json');
+  const settingsOptional = runtime === 'codex' || runtime === 'opencode' || runtime === 'copilot';
+  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 runtimes where settings are optional
+    if (!settingsOptional) {
+      settingsIssues.push(`${path.basename(settingsPath)} 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'));
+}
+
+module.exports = {
+  detectInstalledRuntimes,
+  validateRuntimeInstall,
+  cmdValidateDeployment,
+};

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

@@ -0,0 +1,255 @@
+/**
+ * Verify / Drift detection — convention-drift scoring for changed files.
+ * Extracted from verify.cjs (IMPROVEMENT-TODO P2 module decomposition);
+ * verify.cjs re-exports everything here, so consumers are unaffected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, execGit, toPosix, output, error } = require('./core.cjs');
+const {
+  BUILTIN_DRIFT_RULES, DRIFT_VERDICTS, BINARY_EXTENSIONS, DRIFT_MAX_FILES, DRIFT_MAX_FILE_SIZE, DRIFT_SEVERITY_WEIGHTS,
+} = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+/**
+ * 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);
+}
+
+module.exports = {
+  runDriftCheck,
+  parseConventionRules,
+  checkFileConventions,
+  calculateDriftScore,
+  getChangedFiles,
+  cmdDriftCheck,
+};

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

@@ -0,0 +1,261 @@
+/**
+ * Verify / Pre-execution gates — preflight checks and dependency-graph validation.
+ * Extracted from verify.cjs (IMPROVEMENT-TODO P2 module decomposition);
+ * verify.cjs re-exports everything here, so consumers are unaffected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, execGit, findPhaseInternal, output } = require('./core.cjs');
+const { readStateSafe } = require('./state.cjs');
+const {
+  STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PATTERNS_FILE, PHASE_DIR_RE,
+} = require('./constants.cjs');
+const { planningPath, phasesPath, filterSummaryFiles, fileAccessible } = require('./utils.cjs');
+
+/**
+ * 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');
+}
+
+module.exports = {
+  cmdPreflight,
+  cmdDepsValidate,
+};