pan-wizard 3.35.0 → 3.37.0

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

@@ -0,0 +1,104 @@
+'use strict';
+/**
+ * Local usage census (program L9): `pan-tools usage`.
+ *
+ * Which of the installed commands and agents this project has used, from its own
+ * files only: the cost ledger (`.planning/metrics/tokens.jsonl`: `command` and `agent`
+ * per row) and the trace sessions (`.planning/optimization/traces/<sess>/session.json`:
+ * `command`, `ended_at`). It reports what was used (calls, last use), what was never
+ * used, and commands that were started but never finished: every trace session for
+ * the command stopped without ending, the newest more than UNFINISHED_AFTER_MS ago.
+ * Nothing leaves the machine.
+ */
+const fs = require('fs');
+const path = require('path');
+const { output } = require('./core.cjs');
+const { readRecords } = require('./cost.cjs');
+const { planningPath } = require('./utils.cjs');
+
+// A trace session still open after this long is not "running", it stopped.
+const UNFINISHED_AFTER_MS = 6 * 60 * 60 * 1000;
+// The install this engine ships in: <runtime dir>/pan-wizard-core/bin/lib → <runtime dir>.
+const DEFAULT_INVENTORY = path.resolve(__dirname, '..', '..', '..');
+
+/** A command name as the inventory spells it: `/pan:quick`, `pan-quick`, `pan:quick` → `quick`. */
+function commandName(s) {
+  return String(s || '').trim().replace(/^\//, '').replace(/^pan[:-]/, '');
+}
+
+/** The installed commands and agents: commands/pan/*.md or skills/pan-*, and agents/pan-*. */
+function readInventory(root) {
+  const list = (d, re) => { try { return fs.readdirSync(d).filter((f) => re.test(f)); } catch { return []; } };
+  const commands = new Set(list(path.join(root, 'commands', 'pan'), /\.md$/).map((f) => f.replace(/\.md$/, '')));
+  for (const d of list(path.join(root, 'skills'), /^pan-/)) commands.add(commandName(d));
+  const agents = new Set(list(path.join(root, 'agents'), /^pan-.*\.(md|toml)$/).map((f) => f.replace(/\.(md|toml)$/, '')));
+  return { commands: [...commands].sort(), agents: [...agents].sort() };
+}
+
+function readSessions(cwd) {
+  const dir = planningPath(cwd, 'optimization', 'traces');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.startsWith('sess_')); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    try { out.push(JSON.parse(fs.readFileSync(path.join(dir, n, 'session.json'), 'utf-8'))); } catch { /* unreadable session */ }
+  }
+  return out;
+}
+
+/**
+ * @param {string} cwd
+ * @param {{inventory?: string, now?: string}} [opts]
+ */
+function usageCensus(cwd, opts = {}) {
+  const inventory = readInventory(opts.inventory || DEFAULT_INVENTORY);
+  const now = opts.now ? Date.parse(opts.now) : Date.now();
+  const cmds = new Map(inventory.commands.map((n) => [n, { name: n, calls: 0, last_used: null, sessions: 0, finished: 0, _lastStart: null }]));
+  const agents = new Map(inventory.agents.map((n) => [n, { name: n, calls: 0, last_used: null }]));
+  const later = (a, b) => (!a || (b && b > a) ? b : a);
+
+  const rows = readRecords(cwd);
+  for (const r of rows) {
+    const c = cmds.get(commandName(r.command));
+    if (c) { c.calls++; c.last_used = later(c.last_used, r.ts || null); }
+    const a = agents.get(String(r.agent || ''));
+    if (a) { a.calls++; a.last_used = later(a.last_used, r.ts || null); }
+  }
+  const sessions = readSessions(cwd);
+  for (const s of sessions) {
+    const c = cmds.get(commandName(s.command));
+    if (!c) continue;
+    c.sessions++;
+    if (s.ended_at) c.finished++;
+    c._lastStart = later(c._lastStart, s.started_at || null);
+    c.last_used = later(c.last_used, s.ended_at || s.started_at || null);
+  }
+  const byUse = (a, b) => b.calls - a.calls || String(b.last_used).localeCompare(String(a.last_used)) || a.name.localeCompare(b.name);
+  const pub = ({ _lastStart, ...rest }) => rest;
+  const cmdList = [...cmds.values()];
+  const used = cmdList.filter((c) => c.calls > 0 || c.sessions > 0);
+  const unfinished = used.filter((c) => c.sessions > 0 && c.finished === 0 && c._lastStart && now - Date.parse(c._lastStart) > UNFINISHED_AFTER_MS);
+  const agentList = [...agents.values()];
+  return {
+    local_only: true,
+    commands: {
+      used: used.sort(byUse).map(pub),
+      never_used: cmdList.filter((c) => c.calls === 0 && c.sessions === 0).map((c) => c.name).sort(),
+      unfinished: unfinished.sort(byUse).map(pub),
+      installed: inventory.commands.length,
+    },
+    agents: {
+      used: agentList.filter((a) => a.calls > 0).sort(byUse),
+      never_used: agentList.filter((a) => a.calls === 0).map((a) => a.name).sort(),
+      installed: inventory.agents.length,
+    },
+    sources: { cost_rows: rows.length, trace_sessions: sessions.length },
+  };
+}
+
+function cmdUsage(cwd, raw) {
+  const r = usageCensus(cwd);
+  output(r, raw, `${r.commands.used.length} of ${r.commands.installed} commands used, ${r.commands.unfinished.length} unfinished; ${r.agents.used.length} of ${r.agents.installed} agents used`);
+}
+
+module.exports = { usageCensus, readInventory, commandName, cmdUsage, UNFINISHED_AFTER_MS };

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

@@ -36,7 +36,7 @@ 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, not_checked: 20, check: 80 });
+const LIMITS = Object.freeze({ findings: 100, where: 200, summary: 300, verdict: 40, score: 40, not_checked: 20, check: 80, declined: 20 });
 // What the verifier's test gate can report (verify-phase.md, run_test_suite).
 const TEST_GATE_VALUES = Object.freeze(['passed', 'failed', 'skipped']);
 const RESOLUTION_STATUSES = Object.freeze(['resolved', 'still_present', 'cannot_tell']);
@@ -192,12 +192,15 @@ function validateVerdict(obj, opts = {}) {
       warnings.push(`summary_truncated: #${i}`);
     }
     const where = f.where == null || cleanText(f.where) === '' ? null : truncate(cleanText(f.where).replace(/\\/g, '/'), LIMITS.where);
-    findings.push({ class: cls, severity, where, summary });
+    // pre_existing (M52): the finding is in code the change did not touch. It is
+    // recorded as deferred debt, never a blocker; findings.cjs files it.
+    findings.push({ class: cls, severity, where, summary, ...(f.pre_existing === true ? { pre_existing: true } : {}) });
   });
 
   const notChecked = normaliseNotChecked(obj.not_checked, warnings);
   const resolutions = normaliseResolutions(obj.resolutions, warnings);
-  return { ok: true, verdict: { contract, agent, outcome, verdict, phase, score, findings, not_checked: notChecked, resolutions }, warnings };
+  const declined = normaliseDeclined(obj.declined, warnings);
+  return { ok: true, verdict: { contract, agent, outcome, verdict, phase, score, findings, not_checked: notChecked, resolutions, ...(declined.length ? { declined } : {}) }, warnings };
 }
 
 /**
@@ -234,6 +237,26 @@ function normaliseResolutions(value, warnings) {
   return out;
 }
 
+/**
+ * The behaviours a judge set aside, each `{behaviour, reason}` (MI-118, program R2).
+ * A review that names what it declined to judge says where its silence is not a pass.
+ * Accepts bare strings; drops entries that name nothing.
+ */
+function normaliseDeclined(value, warnings) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) { warnings.push('declined_not_an_array'); return []; }
+  const out = [];
+  for (const entry of value.slice(0, LIMITS.declined)) {
+    const obj = typeof entry === 'string' ? { behaviour: entry } : (entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : null);
+    const behaviour = obj ? truncate(cleanText(obj.behaviour ?? obj.behavior ?? ''), LIMITS.summary) : '';
+    if (!behaviour) continue;
+    const reason = obj.reason == null || cleanText(obj.reason) === '' ? null : truncate(cleanText(obj.reason), LIMITS.summary);
+    out.push({ behaviour, reason });
+  }
+  if (value.length > LIMITS.declined) warnings.push(`declined_truncated: ${value.length} reported, ${LIMITS.declined} kept`);
+  return out;
+}
+
 /**
  * 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

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

@@ -176,9 +176,38 @@ function checkPlanSet(cwd, phase) {
     }
   }
 
+  // 5. Property tasks (V10): a requirement whose EARS criterion is a validation rule
+  // (IF … THEN … SHALL, or a claim over any / every / all inputs, or a "never") is a
+  // claim over many inputs, which one example test cannot show. The plan that lists it
+  // must carry a property-test task: property="true" on the task, or "property test" /
+  // "property-based" in its name or action.
+  let reqText = '';
+  try { reqText = fs.readFileSync(planningPath(cwd, 'requirements.md'), 'utf-8'); } catch { /* none */ }
+  if (reqText && required.length) {
+    const RL = require('./requirements-lint.cjs');
+    const byId = new Map(RL.parseRequirements(reqText).map((r) => [key(r.id), r]));
+    for (const id of required) {
+      const r = byId.get(key(id));
+      if (!r || !r.criteria.some(isValidationRule)) continue;
+      const covering = plans.filter((p) => p.requirements.map(key).includes(key(id)));
+      const hasProperty = covering.some((p) => {
+        let text = '';
+        try { text = toLf(fs.readFileSync(path.join(pf.dir, p.file), 'utf-8')); } catch { /* unreadable */ }
+        return /<task\b[^>]*\bproperty=["']?true/i.test(text) || /property[- ]based|property test/i.test(text);
+      });
+      if (!hasProperty) errors.push({ code: 'missing_property_task', requirement: id, detail: `${id} states a validation rule ("${r.criteria.find(isValidationRule).slice(0, 80)}"): a plan covering it needs a property-test task, which checks the rule over generated inputs with the project's own property library` });
+    }
+  }
+
   return { phase: phaseNumber, ok: errors.length === 0, errors, warnings, plans: plans.length, plans_sha: plansSha(pf.dir, pf.planFiles) };
 }
 
+/** A validation-rule criterion (V10): unwanted-behaviour EARS, or a claim over all inputs. */
+function isValidationRule(criterion) {
+  const c = String(criterion || '');
+  return /^IF\b[\s\S]*\bTHEN\b/i.test(c) || /\b(any|every|all|each)\s+\w+/i.test(c) || /\bnever\b/i.test(c);
+}
+
 /**
  * Whether the plans exec-phase is about to run are the plans that passed a plan check.
  * @returns {{status: 'ok'|'stale'|'failed'|'missing'|'legacy'|'disabled', reason?: string, plans_sha?: string, checked_sha?: string, attempt?: number}}
@@ -227,4 +256,4 @@ function cmdVerifyPlanSet(cwd, phase, raw) {
   output(result, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
 }
 
-module.exports = { checkPlanSet, plansSha, plansShaFor, planCheckStatus, planDrift, cmdVerifyPlanSet, PLAN_CHECKER };
+module.exports = { isValidationRule, phaseFiles, checkPlanSet, plansSha, plansShaFor, planCheckStatus, planDrift, cmdVerifyPlanSet, PLAN_CHECKER };

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

@@ -103,11 +103,11 @@ function cmdPreflight(cwd, target, raw) {
           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');
+          blockers.push('No batch file — run /pan:focus-auto --step 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');
+        blockers.push('No focus/ directory — run /pan:focus-auto --step scan first');
       }
     } else {
       // target is a phase number — check the phase directory exists

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

@@ -0,0 +1,174 @@
+'use strict';
+/**
+ * RED and catch proof (program V4): does each test this phase wrote actually test what
+ * the phase built?
+ *
+ * A test that passes before the phase's code exists cannot have caught anything: it is
+ * tautological, or it tests something the phase did not change. So, independent of the
+ * order the commits landed in (Meta's "weak catch"):
+ *
+ *   base    the parent of the phase's oldest plan commit (`{type}({phase}-{plan}):`)
+ *   tests   the test files the phase's plan commits added or changed, as they are now
+ *   red     in a throwaway worktree at the base, with the test file copied in from HEAD,
+ *           the test must FAIL (a crash on a missing module counts: the code is not there)
+ *   green   at HEAD it must PASS
+ *
+ *   caught       red at the base, green at HEAD
+ *   not_red      passes without the phase's code: it cannot have caught a regression
+ *   not_green    fails at HEAD: the test gate reports that, not this check
+ *   not_checked  no command can run that one file (cargo, Maven, Gradle, make), with why
+ *
+ * Each file runs on its own (`workflow.test_file_command`, else derived from the suite's
+ * runner: test-gate.cjs `fileCommand`). The worktree links the project's node_modules,
+ * which git does not track, so a JS runner resolves the same at the base as at HEAD.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execGit, findPhaseInternal, output, error } = require('./core.cjs');
+const { committedFiles } = require('./verify-scope.cjs');
+const { isTestFile } = require('./verify-integrity.cjs');
+const TG = require('./test-gate.cjs');
+
+const DEFAULT_FILE_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * The commit the phase started from: the parent of its oldest plan commit.
+ * @returns {{base: string, files: Set<string>, commits: number}|{base: null, reason: string}}
+ */
+function phaseBase(cwd, phase) {
+  const c = committedFiles(cwd, phase);
+  if (!c.git) return { base: null, reason: 'git is unavailable' };
+  if (!c.commits) return { base: null, reason: 'the phase has no plan commits (subjects like feat(03-01): …)' };
+  const oldest = c.hashes[c.hashes.length - 1];
+  const r = execGit(cwd, ['rev-parse', '--verify', '-q', `${oldest}^`]);
+  if (r.exitCode !== 0 || !r.stdout) return { base: null, reason: 'the phase starts at the first commit of the repository: there is no base to run against' };
+  return { base: r.stdout.trim(), files: c.files, commits: c.commits };
+}
+
+/** Remove a directory link (a junction or a symlink) without touching what it points to. */
+function unlinkDir(p) {
+  try { fs.unlinkSync(p); } catch { try { fs.rmdirSync(p); } catch { /* already gone */ } }
+}
+
+/**
+ * Run `fn(dir)` in a detached worktree at `rev`, then remove the worktree. The project's
+ * node_modules is linked in (and unlinked before git removes the worktree, so the removal
+ * can never reach the real one).
+ * @returns {{value?: *, error?: string}}
+ */
+function withWorktree(cwd, rev, fn) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-wt-'));
+  const dir = path.join(root, 'wt');
+  const add = execGit(cwd, ['worktree', 'add', '--detach', '-q', dir, rev]);
+  if (add.exitCode !== 0) {
+    try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
+    return { error: `git worktree add failed: ${add.stderr || add.stdout}` };
+  }
+  const link = path.join(dir, 'node_modules');
+  let linked = false;
+  try {
+    const modules = path.join(cwd, 'node_modules');
+    if (fs.existsSync(modules) && !fs.existsSync(link)) {
+      try { fs.symlinkSync(modules, link, 'junction'); linked = true; } catch { /* runs without it */ }
+    }
+    return { value: fn(dir) };
+  } finally {
+    if (linked) unlinkDir(link);
+    execGit(cwd, ['worktree', 'remove', '--force', dir]);
+    execGit(cwd, ['worktree', 'prune']);
+    try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}
+
+const tail = (s) => TG.stripAnsi(String(s || '')).replace(/\r\n?/g, '\n').trim().split('\n').slice(-6).join('\n');
+
+/**
+ * The RED/catch proof for one phase.
+ * @param {string} cwd
+ * @param {string} phase
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Object} `{phase, checked, ok, base, files: [{file, verdict, command, base_exit, head_exit, detail}], reason?}` or `{error, reason}`
+ */
+function checkRed(cwd, phase, opts = {}) {
+  const info = findPhaseInternal(cwd, phase);
+  if (!info) return { error: 'phase_not_found', reason: `no phase directory for phase ${phase}` };
+  const phaseNumber = info.phase_number || String(phase);
+  const b = phaseBase(cwd, phaseNumber);
+  if (!b.base) return { phase: phaseNumber, checked: false, ok: true, files: [], reason: b.reason };
+  const tests = [...b.files].filter((f) => isTestFile(f) && fs.existsSync(path.join(cwd, f))).sort();
+  if (!tests.length) return { phase: phaseNumber, checked: false, ok: true, base: b.base, files: [], reason: 'the phase changed no test file' };
+  const timeoutMs = opts.timeoutMs || DEFAULT_FILE_TIMEOUT_MS;
+  const files = [];
+  const wt = withWorktree(cwd, b.base, (dir) => {
+    for (const file of tests) {
+      const fc = TG.fileCommand(cwd, file);
+      if (!fc.command) { files.push({ file, verdict: 'not_checked', detail: fc.reason }); continue; }
+      const dest = path.join(dir, file);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(path.join(cwd, file), dest);
+      const atBase = TG.runCommand(dir, fc.command, timeoutMs);
+      const atHead = TG.runCommand(cwd, fc.command, timeoutMs);
+      const red = atBase.exit !== 0;
+      const green = atHead.exit === 0;
+      const verdict = red && green ? 'caught' : (!red ? 'not_red' : 'not_green');
+      const detail = verdict === 'not_red'
+        ? 'passes without the phase\'s code: it is tautological, or tests something the phase did not change'
+        : verdict === 'not_green' ? `fails at HEAD: ${tail(atHead.output)}` : null;
+      files.push({ file, verdict, command: fc.command, base_exit: atBase.exit, head_exit: atHead.exit, ...(detail ? { detail } : {}) });
+    }
+  });
+  if (wt.error) return { phase: phaseNumber, checked: false, ok: true, base: b.base, files: [], reason: wt.error };
+  const ran = files.filter((f) => f.verdict !== 'not_checked');
+  return {
+    phase: phaseNumber, checked: ran.length > 0, ok: ran.every((f) => f.verdict === 'caught'), base: b.base,
+    caught: ran.filter((f) => f.verdict === 'caught').length, files,
+    ...(ran.length ? {} : { reason: 'no changed test file could be run on its own' }),
+  };
+}
+
+/**
+ * Prove a review finding with a catching test (program R5): the inverse of RED. The
+ * test shows the defect the phase introduced when it PASSES at the phase's base (the
+ * behaviour was right before) and FAILS at HEAD (the phase broke it).
+ *
+ *   confirmed       passes at the base, fails at HEAD
+ *   fails_at_base   fails before the phase too: not specific to the change
+ *   passes_at_head  the defect it claims is not there, or the test does not reach it
+ *   not_checked     no base, no command for the file, or the worktree failed (with why)
+ *
+ * @returns {{status, test, base?, command?, base_exit?, head_exit?, detail?}}
+ */
+function proveFinding(cwd, phase, testFile, opts = {}) {
+  const test = String(testFile || '').split(path.sep).join('/').split('\\').join('/');
+  if (!test || !fs.existsSync(path.join(cwd, test))) return { status: 'not_checked', test, detail: 'the test file does not exist' };
+  const info = findPhaseInternal(cwd, phase);
+  const b = phaseBase(cwd, (info && info.phase_number) || String(phase));
+  if (!b.base) return { status: 'not_checked', test, detail: b.reason };
+  const fc = TG.fileCommand(cwd, test);
+  if (!fc.command) return { status: 'not_checked', test, detail: fc.reason };
+  const timeoutMs = opts.timeoutMs || DEFAULT_FILE_TIMEOUT_MS;
+  let atBase = null;
+  const wt = withWorktree(cwd, b.base, (dir) => {
+    const dest = path.join(dir, test);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(cwd, test), dest);
+    atBase = TG.runCommand(dir, fc.command, timeoutMs);
+  });
+  if (wt.error) return { status: 'not_checked', test, base: b.base, detail: wt.error };
+  const atHead = TG.runCommand(cwd, fc.command, timeoutMs);
+  const status = atBase.exit !== 0 ? 'fails_at_base' : (atHead.exit === 0 ? 'passes_at_head' : 'confirmed');
+  const detail = status === 'fails_at_base' ? `fails before the phase too: ${tail(atBase.output)}`
+    : status === 'passes_at_head' ? 'passes at HEAD: it does not show the defect the finding claims' : null;
+  return { status, test, base: b.base, command: fc.command, base_exit: atBase.exit, head_exit: atHead.exit, ...(detail ? { detail } : {}) };
+}
+
+/** `pan-tools verify red <phase> [--timeout <ms>]`: exit 1 when a test is not_red or not_green. */
+function cmdVerifyRed(cwd, phase, raw, opts = {}) {
+  if (!phase) error('Usage: verify red <phase> [--timeout <ms>]');
+  const r = checkRed(cwd, phase, { timeoutMs: opts.timeout ? Number(opts.timeout) : undefined });
+  if (r.error) error(r.reason);
+  output(r, raw, !r.checked ? 'not_checked' : (r.ok ? 'caught' : 'not_caught'), r.ok ? 0 : 1);
+}
+
+module.exports = { checkRed, cmdVerifyRed, phaseBase, withWorktree, proveFinding };

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

@@ -38,9 +38,10 @@ function collectVerificationStats(phasesDir) {
       // 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+/));
+        // Bullets and numbered items both (L6b: numbered gap lists were dropped).
+        const lines = gapsMatch[0].split('\n').filter(l => l.match(/^(?:[-*]|\d+[.)])\s+/));
         for (const line of lines) {
-          const desc = line.replace(/^[-*]\s+/, '').trim();
+          const desc = line.replace(/^(?:[-*]|\d+[.)])\s+/, '').trim();
           if (desc) stats.gap_patterns.push(desc);
         }
       }

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

@@ -17,7 +17,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 { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { isPlanFile, isSummaryFile, isVerificationFile } = require('./constants.cjs');
 const { planningRel } = require('./utils.cjs');
 
@@ -151,6 +151,147 @@ function scopePhase(cwd, phase) {
   };
 }
 
+// ─── Review scope (program R1) ───────────────────────────────────────────────
+// The reviewer used to get the summaries' key-files: what the executor said it touched.
+// A file the executor changed and did not list was never reviewed. The review scope is
+// the diff instead (the phase's plan commits, plus work not yet committed), with the
+// intent the code is judged against: each plan's objective, must_haves and Review Focus,
+// and the text of the requirements the plans claim.
+
+/** Files modified, staged or untracked in the working tree, relative to cwd. */
+function workingTreeFiles(cwd) {
+  // Porcelain v2 with -z: each entry starts with its type (`1`, `2`, `u`, `?`), never a
+  // space, and paths come unquoted. v1 starts an unstaged edit with a space (" M a.js"),
+  // which execGit's trim() cut off the first line, and the path lost its first letter.
+  const r = execGit(cwd, ['status', '--porcelain=v2', '-z', '--untracked-files=all', '--', '.']);
+  if (r.exitCode !== 0) return { git: false, uncommitted: [], untracked: [] };
+  const top = execGit(cwd, ['rev-parse', '--show-prefix']);
+  const prefix = top.exitCode === 0 ? normalisePath(top.stdout.trim()) : '';
+  const rel = (p) => { const n = normalisePath(p); return prefix && n.startsWith(prefix) ? n.slice(prefix.length) : n; };
+  const uncommitted = [];
+  const untracked = [];
+  const entries = r.stdout.split('\0');
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (!e) continue;
+    const f = e.split(' ');
+    if (e[0] === '?') untracked.push(rel(e.slice(2)));
+    else if (e[0] === '1') { if (!f[1].includes('D')) uncommitted.push(rel(f.slice(8).join(' '))); }
+    else if (e[0] === '2') { if (!f[1].includes('D')) uncommitted.push(rel(f.slice(9).join(' '))); i++; } // the next entry is the old path
+    else if (e[0] === 'u') uncommitted.push(rel(f.slice(10).join(' ')));
+  }
+  return { git: true, uncommitted, untracked };
+}
+
+/** A markdown section's body, from its `## <title>` heading to the next heading of the same or higher level. */
+function sectionBody(text, title) {
+  const lines = String(text || '').replace(/\r\n/g, '\n').split('\n');
+  const re = new RegExp(`^(#{1,6})\\s+${escapeRegex(title)}\\s*$`, 'i');
+  const at = lines.findIndex((l) => re.test(l.trim()));
+  if (at === -1) return null;
+  const level = lines[at].trim().match(/^#+/)[0].length;
+  const out = [];
+  for (let i = at + 1; i < lines.length; i++) {
+    const h = lines[i].match(/^(#{1,6})\s/);
+    if (h && h[1].length <= level) break;
+    out.push(lines[i]);
+  }
+  const body = out.join('\n').trim();
+  return body || null;
+}
+
+/** The text between `<tag>` and `</tag>`, trimmed, or null. */
+function tagBody(text, tag) {
+  const m = String(text || '').match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
+  return m && m[1].trim() ? m[1].trim() : null;
+}
+
+/**
+ * What a reviewer of one phase reads: the diff and the intent.
+ * @returns {Object} `{phase, directory, base, files: [{path, sources, listed}], unlisted, excluded,
+ *   intent: {plans: [{plan, objective, must_haves, review_focus, requirements}], requirements: [{id, text}], missing_requirements}, git, commits}`
+ *   or `{error, reason}`. `sources` is any of commit · summary · uncommitted · untracked;
+ *   `listed` is whether a summary's key-files names it; `unlisted` lists the files that are not.
+ */
+function reviewScope(cwd, phase) {
+  const 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);
+  const sources = new Map();
+  const note = (file, source) => {
+    if (!file) return;
+    if (!sources.has(file)) sources.set(file, new Set());
+    sources.get(file).add(source);
+  };
+  const listed = new Set();
+  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)]) { const n = normalisePath(p); if (n) { listed.add(n); note(n, 'summary'); } }
+  }
+  const git = committedFiles(cwd, info.phase_number);
+  for (const p of git.files) note(p, 'commit');
+  const wt = workingTreeFiles(cwd);
+  for (const p of wt.uncommitted) note(p, 'uncommitted');
+  for (const p of wt.untracked) note(p, 'untracked');
+
+  const planningPrefix = normalisePath(planningRel());
+  const files = [];
+  const excluded = [];
+  for (const file of [...sources.keys()].sort()) {
+    const why = exclusionReason(file, planningPrefix);
+    if (why) { excluded.push({ path: file, reason: why }); continue; }
+    // A file deleted by the phase has nothing left to read.
+    if (!fs.existsSync(path.join(cwd, file))) continue;
+    files.push({ path: file, sources: [...sources.get(file)].sort(), listed: listed.has(file) });
+  }
+
+  const plans = [];
+  const reqIds = new Set();
+  for (const f of info.plans.filter(isPlanFile).sort()) {
+    const text = safeReadFile(path.join(dir, f)) || '';
+    const fm = extractFrontmatter(text);
+    const requirements = asList(fm.requirements).map((s) => s.trim()).filter(Boolean);
+    for (const id of requirements) reqIds.add(id);
+    const mh = fm.must_haves && typeof fm.must_haves === 'object' ? fm.must_haves : {};
+    plans.push({
+      plan: f,
+      objective: tagBody(text, 'objective'),
+      must_haves: { truths: asList(mh.truths), artifacts: parseMustHavesBlock(text, 'artifacts'), key_links: parseMustHavesBlock(text, 'key_links') },
+      review_focus: sectionBody(text, 'Review Focus'),
+      requirements,
+    });
+  }
+  const { requirementLines } = require('./roadmap.cjs');
+  const reqText = safeReadFile(path.join(cwd, planningRel(), 'requirements.md')) || '';
+  const ids = [...reqIds].sort();
+  const requirements = ids.map((id) => ({ id, text: requirementLines(reqText, [id]).lines.join('\n').trim() || null }));
+
+  let base = null;
+  if (git.hashes.length) {
+    const r = execGit(cwd, ['rev-parse', '--verify', '-q', `${git.hashes[git.hashes.length - 1]}^`]);
+    if (r.exitCode === 0 && r.stdout) base = r.stdout.trim();
+  }
+  return {
+    phase: info.phase_number,
+    directory: info.directory,
+    base,
+    files,
+    unlisted: files.filter((f) => !f.listed).map((f) => f.path),
+    excluded,
+    intent: { plans, requirements, missing_requirements: requirements.filter((r) => !r.text).map((r) => r.id) },
+    git: git.git,
+    commits: git.commits,
+  };
+}
+
+/** `pan-tools review scope <phase>`: the JSON scope; `--raw` prints the file paths, one per line. */
+function cmdReviewScope(cwd, phase, raw) {
+  if (!phase) { output({ error: 'phase_required', reason: 'Usage: review scope <phase>' }, raw); return; }
+  const r = reviewScope(cwd, phase);
+  output(r, raw, r.error ? undefined : r.files.map((f) => f.path).join('\n'));
+}
+
 function cmdVerifyScope(cwd, phase, raw) {
   if (!phase) { output({ error: 'phase_required', reason: 'Usage: verify scope <phase>' }, raw); return; }
   const r = scopePhase(cwd, phase);
@@ -224,4 +365,4 @@ function cmdVerifyStale(cwd, phase, raw) {
   output(r, raw, r.error ? undefined : r.state);
 }
 
-module.exports = { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale, coveredFiles, committedFiles, LOCKFILES, TEST_PATH_RE, TEST_FILE_RE };
+module.exports = { scopePhase, cmdVerifyScope, reviewScope, cmdReviewScope, workingTreeFiles, sectionBody, verificationFreshness, cmdVerifyStale, coveredFiles, committedFiles, LOCKFILES, TEST_PATH_RE, TEST_FILE_RE };