pan-wizard 3.32.0 → 3.34.0

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { loadConfig, getMilestoneInfo, escapeRegex, safeReadFile, output, error } = require('./core.cjs');
+const { loadConfig, getMilestoneInfo, escapeRegex, escapeTableCell, safeReadFile, output, error } = require('./core.cjs');
 const { extractFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
 const { withFileLock, writeFileAtomic } = require('./lock.cjs');
 const {
@@ -294,21 +294,22 @@ function cmdStateRecordMetric(cwd, options, raw) {
     return;
   }
 
-  // Find Performance Metrics section and its table
-  const metricsPattern = /(##\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n)([\s\S]*?)(?=\n##|\n$|$)/i;
+  // The Performance Metrics section's first table: its rows only, then an optional
+  // "None yet" line. Taking the rest of the section as the table body put every row
+  // below the template's "Recent Trend" and footer lines, outside the table. The
+  // separator is matched on one line: `[-|\s]+` ran on into a `| - | - |` row.
+  const metricsPattern = /(##\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[-|: \t]+\r?\n)((?:\|[^\n]*(?:\n|$))*)((?:[^\S\n]*None yet\.?[^\S\n]*(?:\n|$))?)/i;
   const metricsMatch = content.match(metricsPattern);
 
   if (metricsMatch) {
-    let tableBody = metricsMatch[2].trimEnd();
-    const newRow = `| Phase ${phase} P${plan} | ${duration} | ${tasks || '-'} tasks | ${files || '-'} files |`;
-
-    if (tableBody.trim() === '' || tableBody.includes('None yet')) {
-      tableBody = newRow;
-    } else {
-      tableBody = tableBody + '\n' + newRow;
-    }
-
-    content = content.replace(metricsPattern, (_match, header) => `${header}${tableBody}\n`);
+    const cell = escapeTableCell;
+    const newRow = `| Phase ${cell(phase)} P${cell(plan)} | ${cell(duration)} | ${cell(tasks || '-')} tasks | ${cell(files || '-')} files |`;
+    // A template placeholder row (`| - | - | - | - |`, `| None yet | | | |`) gives way.
+    const isPlaceholder = (row) => /None yet/i.test(row) || row.split('|').slice(1, -1).every((c) => /^\s*-?\s*$/.test(c));
+    const rows = metricsMatch[2].split('\n').map((r) => r.replace(/\r$/, '')).filter((r) => r.trim() && !isPlaceholder(r));
+    rows.push(newRow);
+
+    content = content.replace(metricsPattern, (_match, header) => `${header}${rows.join('\n')}\n`);
     writeStateMd(statePath, content, cwd);
     output({ recorded: true, phase, plan, duration }, raw, 'true');
   } else {
@@ -431,7 +432,8 @@ function cmdStateAddBlocker(cwd, text, raw) {
 
   if (match) {
     let sectionBody = match[2];
-    sectionBody = sectionBody.replace(/None\.?\s*\n?/gi, '').replace(/None yet\.?\s*\n?/gi, '');
+    // "None yet" first: stripping "None" first left a stray "yet." on the template.
+    sectionBody = sectionBody.replace(/None yet\.?\s*\n?/gi, '').replace(/None\.?\s*\n?/gi, '');
     sectionBody = sectionBody.trimEnd() + '\n' + entry + '\n';
     content = content.replace(sectionPattern, (_match, header) => `${header}${sectionBody}`);
     writeStateMd(statePath, content, cwd);
@@ -537,14 +539,23 @@ function cmdStateRecordSession(cwd, options, raw) {
 // --- Snapshot Parsers --------------------------------------------------------
 
 /**
- * Parse the Decisions Made table from state.md content.
- * Extracts rows from a markdown table under the "## Decisions Made" heading,
- * splitting each row into phase, summary, and rationale cells.
+ * Parse the decisions from state.md content: the `- [Phase N]: summary — rationale`
+ * bullets `state add-decision` appends under `### Decisions` (the template's
+ * heading), or else an older "## Decisions Made" table. Reading only the table
+ * left `decisions` empty on every state.md PAN itself writes.
  * @param {string} content - Full state.md content
  * @returns {Array<{phase: string, summary: string, rationale: string}>}
  */
 function parseDecisionsFromState(content) {
   const decisions = [];
+  const section = content.match(/###?\s*(?:Decisions|Decisions Made|Accumulated.*Decisions)\s*\n([\s\S]*?)(?=\n###?|\n##[^#]|$)/i);
+  for (const line of section ? section[1].split('\n') : []) {
+    const m = line.match(/^-\s+\[Phase\s+([^\]]*)\]:\s*(.+?)\s*$/i);
+    if (!m) continue;
+    const [summary, ...rest] = m[2].split(' — ');
+    decisions.push({ phase: m[1].trim(), summary: summary.trim(), rationale: rest.join(' — ').trim() });
+  }
+  if (decisions.length > 0) return decisions;
   // Match the decisions table body after header row and separator row
   const decisionsMatch = content.match(/##\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n([\s\S]*?)(?=\n##|\n$|$)/i);
   if (decisionsMatch) {
@@ -566,14 +577,15 @@ function parseDecisionsFromState(content) {
 
 /**
  * Parse the Blockers section from state.md content.
- * Extracts bullet-point items (lines starting with "- ") from under
- * the "## Blockers" heading.
+ * Extracts bullet-point items (lines starting with "- ") from under the heading
+ * `state add-blocker` writes to: `### Blockers/Concerns` in the template, or
+ * `Blockers` / `Concerns`. Matching only "## Blockers" left the list empty.
  * @param {string} content - Full state.md content
  * @returns {string[]} Array of blocker text strings
  */
 function parseBlockersFromState(content) {
   const blockers = [];
-  const blockersMatch = content.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
+  const blockersMatch = content.match(/###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n([\s\S]*?)(?=\n###?|\n##[^#]|$)/i);
   if (blockersMatch) {
     const blockersSection = blockersMatch[1];
     const items = blockersSection.match(/^-\s+(.+)$/gm) || [];
@@ -584,6 +596,18 @@ function parseBlockersFromState(content) {
   return blockers;
 }
 
+/**
+ * The blockers that are still open: the section's bullets minus a "None" placeholder.
+ * `preflight` and `dashboard` read a `## Blockers` heading of their own, which the
+ * state template never writes (it writes `### Blockers/Concerns`, where
+ * `state add-blocker` puts its bullets), so both reported no blockers with one open.
+ * @param {string} content - Full state.md content
+ * @returns {string[]}
+ */
+function activeBlockersFromState(content) {
+  return parseBlockersFromState(content).filter((b) => b && !/^none(\s+yet)?\.?$/i.test(b));
+}
+
 /**
  * Parse the Session section from state.md content.
  * Extracts **Last Date:**, **Stopped At:**, and **Resume File:** bold-field
@@ -1028,17 +1052,8 @@ function cmdDashboard(cwd, raw) {
     lastActivity = stateExtractField(stateContent, 'Last Activity');
     lastActivityDesc = stateExtractField(stateContent, 'Last Activity Description');
 
-    // Parse blockers
-    const blockersMatch = stateContent.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
-    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);
-        }
-      }
-    }
+    // Parse blockers (the template's `### Blockers/Concerns`, or a legacy `## Blockers`)
+    activeBlockers.push(...activeBlockersFromState(stateContent));
     blockerCount = activeBlockers.length;
   }
 
@@ -1110,6 +1125,7 @@ function cmdDashboard(cwd, raw) {
 
 module.exports = {
   readStateSafe: safeReadFile,
+  activeBlockersFromState,
   stateExtractField,
   stateReplaceField,
   writeStateMd,

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const {
-  PHASES_DIR, PLAN_SUFFIX, SUMMARY_SUFFIX, VERIFICATION_SUFFIX,
+  PHASES_DIR, PLAN_SUFFIX, SUMMARY_SUFFIX, VERIFICATION_SUFFIX, ROADMAP_SLICE_SUFFIX,
   SIMPLE_TASK_THRESHOLD, SIMPLE_FILE_THRESHOLD, COMPLEX_TASK_THRESHOLD, COMPLEX_FILE_THRESHOLD,
 } = require('./constants.cjs');
 const { planningPath, phasesPath } = require('./utils.cjs');
@@ -86,7 +86,7 @@ function cmdTemplateSelect(cwd, planPath, raw) {
  * @param {string} phaseName - Human-readable phase name
  * @param {string} phaseSlug - Phase slug for directory naming
  * @param {string} phaseNum - Raw phase number from options
- * @param {Object} options - Additional options (type, wave, fields)
+ * @param {Object} options - Additional options (type, wave, fields, slicePath)
  * @returns {{frontmatter: Object, body: string, fileName: string}}
  */
 function generatePlanTemplate(phaseId, planId, phaseName, phaseSlug, phaseNum, options) {
@@ -94,6 +94,10 @@ function generatePlanTemplate(phaseId, planId, phaseName, phaseSlug, phaseNum, o
   const wave = parseInt(options.wave, 10) || 1;
   const fields = options.fields || {};
   const padded = phaseId.split('-')[0]; // e.g., "01" from "01-setup-auth"
+  // The <context> names the phase's roadmap slice, as templates/phase-prompt.md
+  // does (O2): `@.planning/roadmap.md` handed every executor the whole roadmap.
+  // cmdTemplateFill passes the phase's real directory.
+  const slicePath = options.slicePath || `.planning/phases/${phaseId}/${padded}${ROADMAP_SLICE_SUFFIX}`;
 
   const frontmatter = {
     phase: phaseId,
@@ -121,7 +125,7 @@ function generatePlanTemplate(phaseId, planId, phaseName, phaseSlug, phaseNum, o
     '',
     '## Context',
     '@.planning/project.md',
-    '@.planning/roadmap.md',
+    `@${slicePath}`,
     '@.planning/state.md',
     '',
     '## Tasks',
@@ -286,7 +290,10 @@ function cmdTemplateFill(cwd, templateType, options, raw) {
       generated = generateSummaryTemplate(phaseId, planNum, phaseName, options.phase, fields);
       break;
     case 'plan':
-      generated = generatePlanTemplate(phaseId, planNum, phaseName, phaseSlug, options.phase, options);
+      generated = generatePlanTemplate(phaseId, planNum, phaseName, phaseSlug, options.phase, {
+        ...options,
+        slicePath: toPosix(path.join(phaseInfo.directory, `${padded}${ROADMAP_SLICE_SUFFIX}`)),
+      });
       break;
     case 'verification':
       generated = generateVerificationTemplate(phaseId, phaseName, options.phase, fields);

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

@@ -40,7 +40,9 @@ const KNOWN_VERDICTS = Object.freeze({
   'pan-design-checker': Object.freeze({ PASS: 'pass', GAPS: 'fail' }),
 });
 
-const LIMITS = Object.freeze({ findings: 100, where: 200, summary: 300, verdict: 40, score: 40 });
+const LIMITS = Object.freeze({ findings: 100, where: 200, summary: 300, verdict: 40, score: 40, not_checked: 20, check: 80 });
+// What the verifier's test gate can report (verify-phase.md, run_test_suite).
+const TEST_GATE_VALUES = Object.freeze(['passed', 'failed', 'skipped']);
 const AGENT_RE = /^[a-z][a-z0-9-]{0,63}$/;
 const OPEN_FENCE_RE = /^[ \t]*(`{3,}|~{3,})[ \t]*pan-verdict[ \t]*$/;
 const CLOSE_FENCE_RE = /^[ \t]*(`{3,}|~{3,})[ \t]*$/;
@@ -195,7 +197,32 @@ function validateVerdict(obj, opts = {}) {
     findings.push({ class: cls, severity, where, summary });
   });
 
-  return { ok: true, verdict: { contract, agent, outcome, verdict, phase, score, findings }, warnings };
+  const notChecked = normaliseNotChecked(obj.not_checked, warnings);
+  return { ok: true, verdict: { contract, agent, outcome, verdict, phase, score, findings, not_checked: notChecked }, warnings };
+}
+
+/**
+ * The checks a judge could not run, each `{check, reason}` (market-ideas M23).
+ * A verdict that carries them says what it did not see: a `pass` with tests that
+ * never ran is recorded as exactly that, never as a plain pass. Accepts bare
+ * strings as checks with no reason; drops entries with no check.
+ */
+function normaliseNotChecked(value, warnings) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    warnings.push('not_checked_not_an_array');
+    return [];
+  }
+  const out = [];
+  for (const entry of value.slice(0, LIMITS.not_checked)) {
+    const obj = typeof entry === 'string' ? { check: entry } : (entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : null);
+    const check = obj ? truncate(cleanText(obj.check ?? obj.gate ?? ''), LIMITS.check) : '';
+    if (!check) continue;
+    const reason = obj.reason == null || cleanText(obj.reason) === '' ? null : truncate(cleanText(obj.reason), LIMITS.summary);
+    out.push({ check, reason });
+  }
+  if (value.length > LIMITS.not_checked) warnings.push(`not_checked_truncated: ${value.length} reported, ${LIMITS.not_checked} kept`);
+  return out;
 }
 
 // ─── verification.md frontmatter adapter ─────────────────────────────────────
@@ -354,7 +381,23 @@ function verdictFromVerificationFrontmatter(text, agent = 'pan-verifier') {
     const summary = what || (path ? `unrequested change to ${path}` : '');
     if (summary) findings.push({ class: 'unrequested', severity: 'low', where: path, summary });
   }
-  return { contract: VERDICT_CONTRACT, agent, verdict: status, outcome, findings };
+  // The test gate (M23). `not_checked` lists what the verifier could not run; a
+  // `test_gate: skipped` with no tests entry there still counts as one, so a model
+  // that records the gate but forgets the list cannot turn it into a plain pass.
+  let notChecked = listOfMappings(yaml, 'not_checked').map((n) => ({ check: n.check || n.gate || '', reason: n.reason || null }));
+  const testGateRaw = frontmatterScalar(yaml, 'test_gate');
+  const testGate = testGateRaw ? String(testGateRaw).toLowerCase() : null;
+  const isTests = (n) => /test/i.test(String(n.check));
+  let contradicted = false;
+  if (testGate === 'skipped' && !notChecked.some(isTests)) {
+    notChecked.push({ check: 'tests', reason: frontmatterScalar(yaml, 'test_gate_reason') || 'the test gate was skipped' });
+  } else if ((testGate === 'passed' || testGate === 'failed') && notChecked.some(isTests)) {
+    // The gate ran, so a `tests` entry is the template's example copied over: the
+    // recorded gate is the measurement, and the entry goes.
+    notChecked = notChecked.filter((n) => !isTests(n));
+    contradicted = true;
+  }
+  return { contract: VERDICT_CONTRACT, agent, verdict: status, outcome, findings, not_checked: notChecked, test_gate: testGate, not_checked_contradicted: contradicted };
 }
 
 /**
@@ -383,7 +426,14 @@ function parseVerdictText(text, opts = {}) {
       return { ok: false, error: 'unknown_status', reason: `verification status "${adapted.verdict}" is not passed, gaps_found or human_needed` };
     }
     const r = validateVerdict(adapted, opts);
-    return r.ok ? { ...r, source_kind: 'frontmatter' } : r;
+    if (!r.ok) return r;
+    // Say when the verification does not record its test gate, or records a failed
+    // gate under a pass: both make "passed" claim more than the verifier checked.
+    if (!adapted.test_gate) r.warnings.push('test_gate_unrecorded: the verification does not say whether the test suite ran');
+    else if (!TEST_GATE_VALUES.includes(adapted.test_gate)) r.warnings.push(`test_gate_unknown: "${adapted.test_gate}" is not passed, failed or skipped`);
+    else if (adapted.test_gate === 'failed' && adapted.outcome === 'pass') r.warnings.push('test_gate_failed_under_pass: the test gate failed but the status is passed');
+    if (adapted.not_checked_contradicted) r.warnings.push(`not_checked_contradicted: test_gate is ${adapted.test_gate}, so the not_checked tests entry was dropped`);
+    return { ...r, source_kind: 'frontmatter' };
   }
   return { ok: false, error: 'no_verdict', reason: 'no pan-verdict block and no verification frontmatter status' };
 }

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

@@ -13,14 +13,24 @@ const {
 const { planningPath } = require('./utils.cjs');
 
 /**
- * Parse convention rules from CONVENTIONS.md markdown content.
+ * The codebase map's conventions document. map-codebase writes `conventions.md`;
+ * a map from an older PAN, or one written by hand, may be `CONVENTIONS.md`. Only a
+ * case-sensitive filesystem tells the two apart, which is why reading the uppercase
+ * name alone found nothing on Linux (prompt audit, market-ideas M34).
+ */
+function readConventions(cwd) {
+  const dir = path.join(planningPath(cwd), 'codebase');
+  return safeReadFile(path.join(dir, 'conventions.md')) || safeReadFile(path.join(dir, 'CONVENTIONS.md'));
+}
+
+/**
+ * Parse convention rules from the conventions document's 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 conventionsContent = readConventions(cwd);
   const claudeMdContent = safeReadFile(path.join(cwd, 'CLAUDE.md'));
   const combined = [conventionsContent, claudeMdContent].filter(Boolean).join('\n');
   const rules = parseConventionRules(combined || null);
@@ -198,8 +208,7 @@ function cmdDriftCheck(cwd, raw, args) {
   }
 
   // Load convention rules
-  const conventionsPath = path.join(planningPath(cwd), 'codebase', 'CONVENTIONS.md');
-  const conventionsContent = safeReadFile(conventionsPath);
+  const conventionsContent = readConventions(cwd);
   const claudeMdContent = safeReadFile(path.join(cwd, 'CLAUDE.md'));
   const combined = [conventionsContent, claudeMdContent].filter(Boolean).join('\n');
   const rules = parseConventionRules(combined || null);

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

@@ -7,7 +7,7 @@
 const fs = require('fs');
 const path = require('path');
 const { safeReadFile, execGit, findPhaseInternal, output, normalizePhaseName } = require('./core.cjs');
-const { readStateSafe } = require('./state.cjs');
+const { readStateSafe, activeBlockersFromState } = require('./state.cjs');
 const {
   STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PATTERNS_FILE, PHASE_DIR_RE,
 } = require('./constants.cjs');
@@ -44,19 +44,10 @@ function cmdPreflight(cwd, target, raw) {
     blockers.push('state.md not found — run /pan:new-project');
   }
 
-  // Check 3: no unresolved blockers in state.md
+  // Check 3: no unresolved blockers in state.md (the template's `### Blockers/Concerns`,
+  // where `state add-blocker` writes, or a legacy `## Blockers`)
   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);
-        }
-      }
-    }
+    const activeBlockers = activeBlockersFromState(stateContent);
     if (activeBlockers.length === 0) {
       checks.push({ name: 'no_blockers', passed: true });
     } else {

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

@@ -122,9 +122,11 @@ function cmdRetro(cwd, raw, args) {
     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.
+  // E-4: optional memory write. Top gap patterns become lessons in pan-planner's
+  // log (they surface what plans routinely miss), first-try rate deltas in
+  // pan-verifier's. Stored for /pan:knowledge: PAN's workflows no longer load agent
+  // memory into agents (ADR-0036, amended 2026-10-04), and /pan:army no longer
+  // passes the flag.
   const argsList = Array.isArray(args) ? args : [];
   if (argsList.includes('--write-memory')) {
     const { appendMemory } = require('./memory.cjs');

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

@@ -18,7 +18,7 @@ const fs = require('fs');
 const path = require('path');
 const { safeReadFile, execGit, findPhaseInternal, toPosix, output, escapeRegex } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
-const { isPlanFile, isSummaryFile } = require('./constants.cjs');
+const { isPlanFile, isSummaryFile, isVerificationFile } = require('./constants.cjs');
 const { planningRel } = require('./utils.cjs');
 
 const LOCKFILES = new Set([
@@ -27,8 +27,11 @@ const LOCKFILES = new Set([
 ]);
 // PAN's own installed trees: a phase commit that touches them is PAN bookkeeping,
 // never the project's scope (pan-reviewer skips them for the same reason).
-const PAN_OWNED_PREFIXES = ['.claude/', '.codex/', '.gemini/', '.opencode/', '.agents/', '.github/pan-wizard-core/', '.github/agents/', '.github/prompts/', '.github/skills/'];
-const PAN_OWNED_FILES = new Set(['.github/copilot-instructions.md', '.github/hooks/pan.json']);
+// A Copilot install shares `.github/` with the project: only what the installer writes as
+// its own is listed, so the project's workflows, hooks and Copilot instructions stay in scope,
+// and so do the files PAN merges into (`mcp.json`, `copilot/settings.json`).
+const PAN_OWNED_PREFIXES = ['.claude/', '.codex/', '.gemini/', '.opencode/', '.agents/', '.github/pan-wizard-core/', '.github/pan-local-patches/', '.github/agents/pan-', '.github/skills/pan-', '.github/hooks/pan-'];
+const PAN_OWNED_FILES = new Set(['.github/hooks/pan.json', '.github/package.json', '.github/pan-file-manifest.json']);
 const TEST_PATH_RE = /(^|\/)(tests?|__tests__|specs?)\//i;
 const TEST_FILE_RE = /\.(test|spec)\.[a-z0-9]+$/i;
 const COMMIT_SCAN_LIMIT = 2000;
@@ -153,4 +156,71 @@ function cmdVerifyScope(cwd, phase, raw) {
   output(r, raw, r.error ? undefined : String(r.candidates.length));
 }
 
-module.exports = { scopePhase, cmdVerifyScope, LOCKFILES };
+// ─── Stale verification (market-ideas M27) ───────────────────────────────────
+// A verification describes the code at one commit. Until 2026-10-03 nothing tied it
+// to that commit, so a phase edited after it passed still read as verified. The
+// verifier now records `verified_commit`; any file the phase covers that changed
+// since then, committed or not, makes the verification stale.
+
+const SHA_RE = /^[0-9a-f]{7,40}$/i;
+
+/**
+ * The files a phase's verification covered: the plans' declared `files_modified` and
+ * the summaries' `key-files`, minus the planning tree, lockfiles and PAN's runtime
+ * directories. No git log scan, so `progress` can afford it for every phase.
+ */
+function coveredFiles(cwd, info) {
+  const dir = path.join(cwd, info.directory);
+  const files = new Set();
+  for (const f of info.plans.filter(isPlanFile)) {
+    const fm = extractFrontmatter(safeReadFile(path.join(dir, f)) || '');
+    for (const p of asList(fm.files_modified || fm['files-modified'])) files.add(normalisePath(p));
+  }
+  for (const f of info.summaries.filter(isSummaryFile)) {
+    const fm = extractFrontmatter(safeReadFile(path.join(dir, f)) || '');
+    const kf = fm['key-files'] || fm.key_files || {};
+    for (const p of [...asList(kf.created), ...asList(kf.modified)]) files.add(normalisePath(p));
+  }
+  const planningPrefix = normalisePath(planningRel());
+  return [...files].filter((f) => f && !exclusionReason(f, planningPrefix)).sort();
+}
+
+/**
+ * Whether a phase's verification still describes the code.
+ * @param {string} cwd
+ * @param {string} phase
+ * @param {Object} [info] - findPhaseInternal's result, when the caller already has it
+ * @returns {Object} `{phase, state, verified_commit, verification, changed_since, reason?}` or `{error, reason}`.
+ *   state: `fresh` · `stale` (covered files changed since the verified commit) ·
+ *   `unverified` (no verification file) · `unknown` (no usable verified_commit, or no git)
+ */
+function verificationFreshness(cwd, phase, info) {
+  info = info || findPhaseInternal(cwd, phase);
+  if (!info) return { error: 'phase_not_found', reason: `no phase directory for phase ${phase}` };
+  const dir = path.join(cwd, info.directory);
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { /* unreadable: no verification */ }
+  const verification = names.filter(isVerificationFile).sort().pop() || null;
+  const base = { phase: info.phase_number, state: 'unverified', verified_commit: null, verification: verification ? toPosix(path.join(info.directory, verification)) : null, changed_since: [] };
+  if (!verification) return base;
+  const fm = extractFrontmatter(safeReadFile(path.join(dir, verification)) || '');
+  const sha = String(fm.verified_commit || '').trim();
+  if (!SHA_RE.test(sha)) return { ...base, state: 'unknown', reason: 'the verification records no verified_commit' };
+  const known = execGit(cwd, ['cat-file', '-e', `${sha}^{commit}`]);
+  if (known.exitCode !== 0) return { ...base, state: 'unknown', verified_commit: sha, reason: 'the verified commit is not in this repository (rebased, squashed, or no git)' };
+  const covered = coveredFiles(cwd, info);
+  if (!covered.length) return { ...base, state: 'unknown', verified_commit: sha, reason: 'the phase declares no files to compare' };
+  // Against the working tree, not HEAD: an uncommitted edit makes the pass stale too.
+  const diff = execGit(cwd, ['-c', 'core.quotepath=off', 'diff', '--name-only', '--relative', sha, '--', ...covered]);
+  if (diff.exitCode !== 0) return { ...base, state: 'unknown', verified_commit: sha, reason: 'git diff failed' };
+  const changed = diff.stdout.split('\n').map(normalisePath).filter(Boolean).sort();
+  return { ...base, state: changed.length ? 'stale' : 'fresh', verified_commit: sha, changed_since: changed };
+}
+
+function cmdVerifyStale(cwd, phase, raw) {
+  if (!phase) { output({ error: 'phase_required', reason: 'Usage: verify stale <phase>' }, raw); return; }
+  const r = verificationFreshness(cwd, phase);
+  output(r, raw, r.error ? undefined : r.state);
+}
+
+module.exports = { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale, coveredFiles, LOCKFILES };