pan-wizard 2.9.1 → 3.5.0

package/pan-wizard-core/bin/lib/review-deep.cjs

@@ -0,0 +1,280 @@
+/**
+ * Review-Deep — security + cross-check review data layer (Spec B v2 Y-2, v3.2).
+ *
+ * Orchestration sequence:
+ *   1. pan-reviewer (already shipped)   — convention/style findings
+ *   2. pan-hardener  (new, this wave)   — OWASP Top 10 + STRIDE audit
+ *   3. pan-meta-reviewer (new)          — flags things (1) and (2) missed
+ *
+ * This module provides the DATA LAYER only:
+ *   - parseReviewFindings(markdown) — extract structured findings from
+ *     either a reviewer/hardener/meta-reviewer markdown output
+ *   - mergeReviews(reviewer, hardener, meta) — merge the three findings
+ *     sets into one consolidated list + conflict table
+ *   - writeDeepReview(cwd, phaseNum, payload) — serialize the merged output
+ *     to .planning/reviews/<N>/deep-review.md
+ *
+ * Agents publish to `review-handoff` channel via bus.cjs for audit trail.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, toPosix } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+const { publish } = require('./bus.cjs');
+
+const REVIEWS_DIR = 'reviews';
+const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+const SEVERITY_WEIGHT = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+
+function reviewsDir(cwd) {
+  return path.join(planningPath(cwd), REVIEWS_DIR);
+}
+
+/**
+ * Parse structured findings from reviewer/hardener/meta-reviewer markdown.
+ *
+ * Expected format: each finding is a bullet under a `## Findings` heading
+ * with the shape:
+ *   - **[SEVERITY] category** — description. File: `path:line` — rationale.
+ *
+ * Recognized severities (case-insensitive): critical, high, medium, low, info.
+ * Missing severity defaults to `info`.
+ *
+ * @param {string} content - Full markdown content
+ * @param {string} source - Label for finding.source (e.g. "reviewer", "hardener")
+ * @returns {Array<Object>}
+ */
+function parseReviewFindings(content, source) {
+  if (typeof content !== 'string' || !content) return [];
+  const findings = [];
+  const lines = content.split('\n');
+  let inFindings = false;
+  for (const line of lines) {
+    if (/^##\s+Findings\s*$/i.test(line)) { inFindings = true; continue; }
+    if (inFindings && /^##\s+/.test(line)) { inFindings = false; continue; }
+    if (!inFindings) continue;
+
+    const m = line.match(/^-\s+(?:\*\*\[(critical|high|medium|low|info)\]\s*([^*]*?)\*\*\s*[-—:]\s*)?(.+)$/i);
+    if (!m) continue;
+    const severity = (m[1] || 'info').toLowerCase();
+    const category = (m[2] || 'general').trim();
+    const rest = m[3].trim();
+
+    // Optional `File: path:line — rationale.`
+    const fileMatch = rest.match(/File:\s*`?([^:`\s]+)(?::(\d+))?`?\s*[-—]?\s*(.*)$/i);
+    const description = fileMatch ? rest.slice(0, fileMatch.index).trim().replace(/[.\s]+$/, '') : rest;
+    const file = fileMatch ? fileMatch[1] : null;
+    const lineNum = fileMatch && fileMatch[2] ? Number(fileMatch[2]) : null;
+    const rationale = fileMatch ? (fileMatch[3] || null) : null;
+
+    findings.push({
+      source,
+      severity,
+      category,
+      description,
+      file,
+      line: lineNum,
+      rationale,
+    });
+  }
+  return findings;
+}
+
+/**
+ * Merge findings from the three reviewers into a consolidated list plus
+ * a conflict table. A "conflict" is when the meta-reviewer explicitly
+ * disputes a reviewer/hardener finding (meta source mentions `dispute` or
+ * `overstated`) or adds a finding that reviewer/hardener missed.
+ *
+ * @param {Array|string} reviewer - reviewer findings array OR markdown content
+ * @param {Array|string} hardener - hardener findings array OR markdown content
+ * @param {Array|string} [meta]   - optional meta-reviewer findings
+ * @returns {Object} Merged payload
+ */
+function mergeReviews(reviewer, hardener, meta) {
+  const r = Array.isArray(reviewer) ? reviewer : parseReviewFindings(reviewer || '', 'reviewer');
+  const h = Array.isArray(hardener) ? hardener : parseReviewFindings(hardener || '', 'hardener');
+  const m = Array.isArray(meta) ? meta : parseReviewFindings(meta || '', 'meta-reviewer');
+
+  const findings = [...r, ...h, ...m].sort((a, b) => {
+    const wa = SEVERITY_WEIGHT[a.severity] ?? 0;
+    const wb = SEVERITY_WEIGHT[b.severity] ?? 0;
+    if (wa !== wb) return wb - wa;
+    return (a.file || '').localeCompare(b.file || '');
+  });
+
+  // Conflicts: any meta-reviewer finding whose description contains keywords
+  // suggesting disagreement, OR any meta finding on a file+line the other
+  // sources didn't flag.
+  const conflicts = [];
+  for (const mf of m) {
+    // "missed" is genuinely ambiguous — a meta describing a finding as
+    // "missed issue" is an addition, not a dispute. Restrict dispute keywords
+    // to ones that explicitly signal disagreement with a prior finding.
+    const kw = /\b(dispute|overstated|incorrectly|false\s*positive|overrated|underrated)\b/i;
+    if (kw.test(mf.description)) {
+      conflicts.push({
+        type: 'meta_dispute',
+        finding: mf,
+      });
+      continue;
+    }
+    // Missed: meta raises something reviewer+hardener didn't on same file.
+    if (mf.file) {
+      const othersFoundThisFile = [...r, ...h].some(x => x.file === mf.file && x.line === mf.line);
+      if (!othersFoundThisFile) {
+        conflicts.push({
+          type: 'meta_addition',
+          finding: mf,
+        });
+      }
+    }
+  }
+
+  const coverage = {
+    total: findings.length,
+    by_source: {
+      reviewer: r.length,
+      hardener: h.length,
+      meta_reviewer: m.length,
+    },
+    by_severity: SEVERITIES.reduce((acc, s) => { acc[s] = findings.filter(f => f.severity === s).length; return acc; }, {}),
+  };
+
+  // Verdict: highest-severity finding drives the verdict.
+  let verdict;
+  if (coverage.by_severity.critical > 0) verdict = 'block';
+  else if (coverage.by_severity.high > 0) verdict = 'review_required';
+  else if (coverage.by_severity.medium > 0) verdict = 'fix_before_merge';
+  else if (coverage.by_severity.low > 0) verdict = 'ok_with_minor';
+  else verdict = 'ok';
+
+  return { findings, conflicts, coverage, verdict };
+}
+
+/**
+ * Write the merged deep-review report to .planning/reviews/<phase>/deep-review.md.
+ * Returns the written path.
+ *
+ * @param {string} cwd - Project root
+ * @param {string} phaseNum - Phase number (e.g. "07")
+ * @param {Object} payload - mergeReviews() output
+ * @param {Object} [opts] - {timestamp, audit_channel}
+ * @returns {{written: true, file: string}|{error: string}}
+ */
+function writeDeepReview(cwd, phaseNum, payload, opts) {
+  if (!phaseNum) return { error: 'phaseNum required' };
+  const targetDir = path.join(reviewsDir(cwd), String(phaseNum));
+  try {
+    fs.mkdirSync(targetDir, { recursive: true });
+  } catch (e) {
+    return { error: `Failed to create ${targetDir}: ${e.message}` };
+  }
+
+  const lines = [];
+  lines.push('---');
+  lines.push('type: deep-review');
+  lines.push(`phase: ${phaseNum}`);
+  lines.push(`generated: ${opts?.timestamp || new Date().toISOString()}`);
+  lines.push(`verdict: ${payload.verdict}`);
+  lines.push('---');
+  lines.push('');
+  lines.push(`# Deep Review — Phase ${phaseNum}`);
+  lines.push('');
+  lines.push(`**Verdict:** ${payload.verdict}`);
+  lines.push('');
+  lines.push('## Coverage');
+  lines.push(`- Total findings: ${payload.coverage.total}`);
+  lines.push(`- By source: reviewer=${payload.coverage.by_source.reviewer}, hardener=${payload.coverage.by_source.hardener}, meta=${payload.coverage.by_source.meta_reviewer}`);
+  lines.push(`- By severity: ${SEVERITIES.map(s => `${s}=${payload.coverage.by_severity[s]}`).join(', ')}`);
+  lines.push('');
+
+  if (payload.findings.length > 0) {
+    lines.push('## Findings');
+    lines.push('');
+    lines.push('| Severity | Source | Category | Description | File |');
+    lines.push('|----------|--------|----------|-------------|------|');
+    for (const f of payload.findings) {
+      const loc = f.file ? `\`${f.file}${f.line ? `:${f.line}` : ''}\`` : '—';
+      const desc = f.description.replace(/\|/g, '\\|');
+      lines.push(`| ${f.severity} | ${f.source} | ${f.category} | ${desc} | ${loc} |`);
+    }
+    lines.push('');
+  } else {
+    lines.push('## Findings');
+    lines.push('');
+    lines.push('_No findings — all three reviewers returned clean._');
+    lines.push('');
+  }
+
+  if (payload.conflicts.length > 0) {
+    lines.push('## Conflicts & additions from meta-reviewer');
+    lines.push('');
+    for (const c of payload.conflicts) {
+      const locLine = c.finding.file ? ` at \`${c.finding.file}${c.finding.line ? `:${c.finding.line}` : ''}\`` : '';
+      lines.push(`- **${c.type}** — ${c.finding.description}${locLine}`);
+    }
+    lines.push('');
+  }
+
+  const file = path.join(targetDir, 'deep-review.md');
+  try {
+    fs.writeFileSync(file, lines.join('\n'), 'utf-8');
+  } catch (e) {
+    return { error: `Failed to write ${file}: ${e.message}` };
+  }
+
+  // Audit trail on the review-handoff bus channel (best-effort).
+  if (opts?.audit_channel !== false) {
+    try {
+      publish(cwd, 'review-handoff', {
+        phase: phaseNum,
+        verdict: payload.verdict,
+        finding_count: payload.coverage.total,
+        conflict_count: payload.conflicts.length,
+        file: toPosix(path.relative(cwd, file)),
+      }, { source: 'pan-meta-reviewer' });
+    } catch { /* non-blocking */ }
+  }
+
+  return { written: true, file: toPosix(path.relative(cwd, file)) };
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function cmdReviewDeepMerge(cwd, phaseNum, opts, raw) {
+  if (!phaseNum) error('Usage: review-deep merge <phase> --reviewer-file X --hardener-file Y [--meta-file Z]');
+  const reviewerContent = opts.reviewerFile ? safeReadFile(opts.reviewerFile) : '';
+  const hardenerContent = opts.hardenerFile ? safeReadFile(opts.hardenerFile) : '';
+  const metaContent = opts.metaFile ? safeReadFile(opts.metaFile) : '';
+  if (!reviewerContent && !hardenerContent && !metaContent) {
+    output({ error: 'No input files provided or readable' }, raw);
+    return;
+  }
+  const payload = mergeReviews(reviewerContent, hardenerContent, metaContent);
+  const result = writeDeepReview(cwd, phaseNum, payload);
+  if (result.error) { output(result, raw); return; }
+  output({ ...result, verdict: payload.verdict, coverage: payload.coverage, conflicts: payload.conflicts.length }, raw);
+}
+
+function cmdReviewDeepAnalyze(cwd, phaseNum, opts, raw) {
+  // Returns the merged payload WITHOUT writing a file. Useful for piping.
+  if (!phaseNum) error('Usage: review-deep analyze <phase> --reviewer-file X --hardener-file Y [--meta-file Z]');
+  const reviewerContent = opts.reviewerFile ? safeReadFile(opts.reviewerFile) : '';
+  const hardenerContent = opts.hardenerFile ? safeReadFile(opts.hardenerFile) : '';
+  const metaContent = opts.metaFile ? safeReadFile(opts.metaFile) : '';
+  output(mergeReviews(reviewerContent, hardenerContent, metaContent), raw);
+}
+
+module.exports = {
+  parseReviewFindings,
+  mergeReviews,
+  writeDeepReview,
+  cmdReviewDeepMerge,
+  cmdReviewDeepAnalyze,
+  SEVERITIES,
+  SEVERITY_WEIGHT,
+  REVIEWS_DIR,
+};

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

@@ -68,7 +68,7 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
     const section = content.slice(headerIndex, sectionEnd).trim();
 
     // Extract goal if present
-    const goalMatch = section.match(/\*\*Goal:\*\*\s*([^\n]+)/i);
+    const goalMatch = section.match(/(?:\*\*Goal:\*\*|\*\*Goal\*\*:)\s*([^\n]+)/i);
     const goal = goalMatch ? goalMatch[1].trim() : null;
 
     // Extract success criteria as structured array
@@ -122,11 +122,11 @@ function enumerateRoadmapPhases(content) {
     const section = content.slice(sectionStart, sectionEnd);
 
     // Extract goal from the section
-    const goalMatch = section.match(/\*\*Goal:\*\*\s*([^\n]+)/i);
+    const goalMatch = section.match(/(?:\*\*Goal:\*\*|\*\*Goal\*\*:)\s*([^\n]+)/i);
     const goal = goalMatch ? goalMatch[1].trim() : null;
 
     // Extract dependency info from the section
-    const dependsMatch = section.match(/\*\*Depends on:\*\*\s*([^\n]+)/i);
+    const dependsMatch = section.match(/(?:\*\*Depends on:\*\*|\*\*Depends on\*\*:)\s*([^\n]+)/i);
     const dependsOn = dependsMatch ? dependsMatch[1].trim() : null;
 
     phases.push({
@@ -366,7 +366,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
 
   // Update plan count in phase detail section
   const planCountPattern = new RegExp(
-    `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
+    `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?(?:\\*\\*Plans:\\*\\*|\\*\\*Plans\\*\\*:)\\s*)[^\\n]+`,
     'i'
   );
   const planCountText = isComplete

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

@@ -574,10 +574,10 @@ function parseSessionFromState(content) {
     resume_file: null,
   };
 
-  const sessionMatch = content.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
+  const sessionMatch = content.match(/##\s*Session[^\n]*\n([\s\S]*?)(?=\n##|$)/i);
   if (sessionMatch) {
     const sessionSection = sessionMatch[1];
-    const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i);
+    const lastDateMatch = sessionSection.match(/\*\*(?:Last Date|Last session):\*\*\s*(.+)/i);
     const stoppedAtMatch = sessionSection.match(/\*\*Stopped At:\*\*\s*(.+)/i);
     const resumeFileMatch = sessionSection.match(/\*\*Resume File:\*\*\s*(.+)/i);
 

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

@@ -1847,7 +1847,7 @@ function groupGapPatterns(patterns) {
  * @param {string} cwd - Working directory
  * @param {boolean} raw - Raw output flag
  */
-function cmdRetro(cwd, raw) {
+function cmdRetro(cwd, raw, args) {
   const roadmapPath = path.join(planningPath(cwd), ROADMAP_FILE);
   const roadmapContent = safeReadFile(roadmapPath);
   if (!roadmapContent) {
@@ -1880,6 +1880,36 @@ function cmdRetro(cwd, raw) {
     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}%`,
@@ -1890,6 +1920,9 @@ function cmdRetro(cwd, raw) {
     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'));
 }

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

@@ -0,0 +1,289 @@
+/**
+ * Whatif — counterfactual phase exploration (Spec B v2 Y-4, v3.3).
+ *
+ * Creates an isolated git worktree, lets an agent replay a phase with a
+ * different premise, emits a comparison report, and cleans up.
+ *
+ * The module has two concerns:
+ *   1. **Data layer** (pure, testable without git): context gathering,
+ *      report generation, scenario normalization.
+ *   2. **Worktree lifecycle** (shell-out): createWorktree, cleanupWorktree.
+ *      Exercised only on real git repos; testable via scenario tests that
+ *      git-init a temp project.
+ *
+ * Default worktree location: `<cwd>/../pan-whatif-<phase>-<scenario-slug>-<ts>`
+ * (sibling of the main repo, not inside, to avoid `.gitignore` games).
+ * Override via opts.worktree_root.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, isGitRepo, execGit, toPosix, findPhaseInternal } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const COUNTERFACTUALS_DIR = 'counterfactuals';
+const BRANCH_PREFIX = 'pan-whatif/';
+const SCENARIO_SLUG_MAX = 50;
+
+// ─── Data layer ─────────────────────────────────────────────────────────────
+
+/**
+ * Turn a free-text scenario into a filesystem/branch-safe slug.
+ * Lowercase, alphanumerics + hyphens only, bounded length.
+ *
+ * @param {string} scenario
+ * @returns {string}
+ */
+function scenarioSlug(scenario) {
+  if (typeof scenario !== 'string') return 'scenario';
+  const slug = scenario
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SCENARIO_SLUG_MAX);
+  return slug || 'scenario';
+}
+
+/**
+ * Gather context the counterfactual agent needs: phase plan, goal, the
+ * stated alternative scenario, and (optional) the completed summary so
+ * the agent can compare "what actually happened" vs "what would have happened".
+ *
+ * @param {string} cwd - Project root
+ * @param {string|number} phaseNum - Phase identifier
+ * @param {string} scenario - Free-text alternative premise
+ * @returns {Object} Context payload
+ */
+function buildCounterfactualContext(cwd, phaseNum, scenario) {
+  if (!scenario || !scenario.trim()) {
+    return { error: 'scenario required (free-text alternative premise)' };
+  }
+  const phaseInfo = findPhaseInternal(cwd, phaseNum);
+  if (!phaseInfo || !phaseInfo.found) {
+    return { error: `Phase ${phaseNum} not found in .planning/phases/` };
+  }
+
+  const phaseDir = path.join(cwd, phaseInfo.directory);
+  const plans = (phaseInfo.plans || []).sort();
+  const summaries = (phaseInfo.summaries || []).sort();
+
+  const planTexts = plans.map(f => ({
+    file: f,
+    bytes: Buffer.byteLength(safeReadFile(path.join(phaseDir, f)) || '', 'utf-8'),
+  }));
+  const summaryTexts = summaries.map(f => ({
+    file: f,
+    bytes: Buffer.byteLength(safeReadFile(path.join(phaseDir, f)) || '', 'utf-8'),
+  }));
+
+  return {
+    phase: String(phaseNum),
+    phase_name: phaseInfo.name || null,
+    directory: toPosix(phaseInfo.directory),
+    scenario,
+    slug: scenarioSlug(scenario),
+    plans: planTexts,
+    summaries: summaryTexts,
+    has_executed: summaries.length > 0,
+  };
+}
+
+/**
+ * Serialize a counterfactual comparison to a markdown report.
+ *
+ * @param {string} cwd - Project root
+ * @param {string} phaseNum - Phase number
+ * @param {string} scenario - Original scenario text
+ * @param {Object} comparison - {summary, differences, recommendations, risks}
+ * @param {Object} [opts] - {timestamp}
+ * @returns {{written: true, file: string}|{error: string}}
+ */
+function writeCounterfactualReport(cwd, phaseNum, scenario, comparison, opts) {
+  if (!phaseNum) return { error: 'phaseNum required' };
+  if (!scenario || !scenario.trim()) return { error: 'scenario required' };
+
+  const dir = path.join(planningPath(cwd), COUNTERFACTUALS_DIR);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (e) {
+    return { error: `Failed to create ${dir}: ${e.message}` };
+  }
+
+  const slug = scenarioSlug(scenario);
+  const filename = `${phaseNum}-${slug}.md`;
+  const file = path.join(dir, filename);
+
+  const lines = [];
+  lines.push('---');
+  lines.push('type: counterfactual');
+  lines.push(`phase: ${phaseNum}`);
+  lines.push(`scenario_slug: ${slug}`);
+  lines.push(`generated: ${opts?.timestamp || new Date().toISOString()}`);
+  lines.push('---');
+  lines.push('');
+  lines.push(`# What-if: Phase ${phaseNum} — ${scenario}`);
+  lines.push('');
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(comparison?.summary || '_(agent did not produce a summary)_');
+  lines.push('');
+
+  if (Array.isArray(comparison?.differences) && comparison.differences.length > 0) {
+    lines.push('## Differences from actual plan');
+    lines.push('');
+    for (const d of comparison.differences) {
+      lines.push(`- ${d}`);
+    }
+    lines.push('');
+  }
+
+  if (Array.isArray(comparison?.recommendations) && comparison.recommendations.length > 0) {
+    lines.push('## Recommendations');
+    lines.push('');
+    for (const r of comparison.recommendations) {
+      lines.push(`- ${r}`);
+    }
+    lines.push('');
+  }
+
+  if (Array.isArray(comparison?.risks) && comparison.risks.length > 0) {
+    lines.push('## Risks');
+    lines.push('');
+    for (const risk of comparison.risks) {
+      lines.push(`- ${risk}`);
+    }
+    lines.push('');
+  }
+
+  if (comparison?.verdict) {
+    lines.push('## Bottom line');
+    lines.push('');
+    lines.push(`**${comparison.verdict}**`);
+    lines.push('');
+  }
+
+  try {
+    fs.writeFileSync(file, lines.join('\n'), 'utf-8');
+  } catch (e) {
+    return { error: `Failed to write ${file}: ${e.message}` };
+  }
+
+  return { written: true, file: toPosix(path.relative(cwd, file)) };
+}
+
+// ─── Worktree lifecycle (git shell-out) ────────────────────────────────────
+
+/**
+ * Create an isolated git worktree for counterfactual replay.
+ *
+ * @param {string} cwd - Main project root
+ * @param {string} phaseNum - Phase number (used in branch name)
+ * @param {string} scenario - Free-text scenario (slugified for paths)
+ * @param {Object} [opts] - {worktree_root, base}
+ * @returns {{worktree_path: string, branch: string, base: string}|{error: string}}
+ */
+function createWorktree(cwd, phaseNum, scenario, opts) {
+  if (!isGitRepo(cwd)) {
+    return { error: 'Not a git repo — what-if requires git worktree support' };
+  }
+  const slug = scenarioSlug(scenario);
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const branch = `${BRANCH_PREFIX}${phaseNum}-${slug}-${ts.slice(0, 15)}`;
+  const worktreeRoot = opts?.worktree_root
+    || path.join(path.dirname(cwd), `pan-whatif-${phaseNum}-${slug}-${ts.slice(0, 15)}`);
+
+  // Base ref: current HEAD by default. Callers can override (e.g. to branch
+  // off main for a clean comparison).
+  const base = opts?.base || 'HEAD';
+
+  const result = execGit(cwd, ['worktree', 'add', '-b', branch, worktreeRoot, base]);
+  if (result.exitCode !== 0) {
+    return { error: `git worktree add failed: ${result.stderr}` };
+  }
+
+  return {
+    worktree_path: toPosix(worktreeRoot),
+    branch,
+    base,
+  };
+}
+
+/**
+ * Remove a worktree + its branch. Best-effort: errors are surfaced but
+ * don't block subsequent cleanups.
+ *
+ * @param {string} cwd - Main project root (for the cleanup git call)
+ * @param {string} worktreePath - Path returned by createWorktree
+ * @param {string} branch - Branch name returned by createWorktree
+ * @param {Object} [opts] - {force: boolean}
+ * @returns {{removed: true, warnings: string[]}|{error: string}}
+ */
+function cleanupWorktree(cwd, worktreePath, branch, opts) {
+  if (!isGitRepo(cwd)) {
+    return { error: 'Not a git repo' };
+  }
+  const warnings = [];
+  const force = opts?.force === true;
+
+  const rmArgs = ['worktree', 'remove'];
+  if (force) rmArgs.push('--force');
+  rmArgs.push(worktreePath);
+  const removeResult = execGit(cwd, rmArgs);
+  if (removeResult.exitCode !== 0) {
+    warnings.push(`worktree remove: ${removeResult.stderr}`);
+  }
+
+  // Branch cleanup — only if branch still exists.
+  if (branch) {
+    const branchCheck = execGit(cwd, ['branch', '--list', branch]);
+    if (branchCheck.exitCode === 0 && branchCheck.stdout.trim()) {
+      const deleteResult = execGit(cwd, ['branch', '-D', branch]);
+      if (deleteResult.exitCode !== 0) {
+        warnings.push(`branch delete: ${deleteResult.stderr}`);
+      }
+    }
+  }
+
+  return { removed: true, warnings };
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function cmdWhatifPrepare(cwd, phaseNum, scenario, raw) {
+  // Returns context + creates worktree. Called before spawning agent.
+  if (!scenario) error('Usage: whatif prepare <phase> <scenario>');
+  const ctx = buildCounterfactualContext(cwd, phaseNum, scenario);
+  if (ctx.error) { output(ctx, raw); return; }
+  const wt = createWorktree(cwd, phaseNum, scenario);
+  if (wt.error) { output({ ...ctx, worktree_error: wt.error }, raw); return; }
+  output({ ...ctx, worktree: wt }, raw);
+}
+
+function cmdWhatifReport(cwd, phaseNum, scenario, comparisonJson, raw) {
+  if (!scenario) error('Usage: whatif report <phase> <scenario> --comparison <json>');
+  let comparison = {};
+  if (comparisonJson) {
+    try { comparison = JSON.parse(comparisonJson); }
+    catch (e) { error(`Invalid --comparison JSON: ${e.message}`); }
+  }
+  output(writeCounterfactualReport(cwd, phaseNum, scenario, comparison), raw);
+}
+
+function cmdWhatifCleanup(cwd, worktreePath, branch, force, raw) {
+  if (!worktreePath) error('Usage: whatif cleanup --worktree <path> --branch <name> [--force]');
+  output(cleanupWorktree(cwd, worktreePath, branch, { force: Boolean(force) }), raw);
+}
+
+module.exports = {
+  scenarioSlug,
+  buildCounterfactualContext,
+  writeCounterfactualReport,
+  createWorktree,
+  cleanupWorktree,
+  cmdWhatifPrepare,
+  cmdWhatifReport,
+  cmdWhatifCleanup,
+  COUNTERFACTUALS_DIR,
+  BRANCH_PREFIX,
+};