pan-wizard 3.8.0 → 3.10.0

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,
+};

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

@@ -0,0 +1,177 @@
+/**
+ * Verify / Retrospective analysis — milestone retro over historical .planning/ data.
+ * 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, output } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { ROADMAP_FILE, isVerificationFile } = require('./constants.cjs');
+const { planningPath, phasesPath } = require('./utils.cjs');
+
+/**
+ * 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'));
+}
+
+module.exports = {
+  collectVerificationStats,
+  countRoadmapPhases,
+  groupGapPatterns,
+  cmdRetro,
+};