pan-wizard 3.35.0 → 3.36.0

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

@@ -0,0 +1,138 @@
+'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' }),
+  };
+}
+
+/** `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 };

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

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

@@ -572,8 +572,21 @@ function reconcilePhase(cwd, phaseNum) {
       contradictions.push(`verification status "${status}" but ${keyLinks.total - keyLinks.verified}/${keyLinks.total} key-link(s) UNWIRED`);
     }
   }
+  // The engine's test run (V2) is the record the verifier copies its test gate from: a
+  // verification that says otherwise, or passes over a failed run, contradicts it.
+  const testRun = require('./test-gate.cjs').readTestRun(cwd, phaseNum);
+  const writtenGate = (verRaw.match(/^test_gate:\s*([A-Za-z_]+)/m) || [])[1] || null;
+  if (testRun && testRun.status) {
+    const why = testRun.reason ? ` (${testRun.reason})` : '';
+    if (writtenGate && writtenGate.toLowerCase() !== testRun.status) {
+      contradictions.push(`verification test_gate "${writtenGate}" but the engine's test run recorded "${testRun.status}"${why}`);
+    } else if (!writtenGate && claimsPass && testRun.status === 'failed') {
+      contradictions.push(`verification status "${status}" but the engine's test run failed${why}`);
+    }
+  }
   return {
     phase: String(phaseNum), found: true, verification_status: status, claims_pass: claimsPass,
+    test_run: testRun ? { status: testRun.status, head: testRun.head || null, regressions: (testRun.regressions || []).length } : undefined,
     mechanical_signals: signals, artifacts, key_links: keyLinks, contradictions,
     reconciled: contradictions.length === 0,
     note: signals === 0 ? 'no must_haves declared — mechanical reconciliation unavailable; verdict trusted' : undefined,
@@ -1557,35 +1570,22 @@ function cmdValidateHealth(cwd, options, raw) {
 }
 
 /**
- * Run node --test and capture result.
+ * Run the project's tests through the engine's test gate (V2): any language, the
+ * project's own command, and a crash reads failed. `pass` is null when there was nothing
+ * to run (no test command, or one that ran no tests).
  */
 function runFullTestCheck(cwd) {
-  try {
-    const result = execFileSync('node', ['--test'], {
-      cwd,
-      timeout: 120000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      encoding: 'utf-8',
-    });
-    // Match both TAP ("# tests N") and spec-reporter ("ℹ tests N") summaries —
-    // modern node --test defaults to the spec reporter, which the old "# "-only
-    // regex silently missed (returning tests: null).
-    const testMatch = result.match(/[#ℹ]\s*tests\s+(\d+)/);
-    const passMatch = result.match(/[#ℹ]\s*pass\s+(\d+)/);
-    return {
-      pass: true,
-      exitCode: 0,
-      tests: testMatch ? parseInt(testMatch[1], 10) : null,
-      passing: passMatch ? parseInt(passMatch[1], 10) : null,
-    };
-  } catch (err) {
-    return {
-      pass: false,
-      exitCode: err.status || 1,
-      tests: null,
-      passing: null,
-    };
-  }
+  const rec = require('./test-gate.cjs').runTests(cwd, { timeoutMs: 120000 });
+  return {
+    pass: rec.status === 'passed' ? true : (rec.status === 'failed' ? false : null),
+    exitCode: rec.exit,
+    tests: rec.total,
+    passing: rec.passed,
+    status: rec.status,
+    command: rec.command,
+    reason: rec.reason || undefined,
+    failing: rec.failing && rec.failing.length ? rec.failing.slice(0, 20) : undefined,
+  };
 }
 
 /**

package/pan-wizard-core/bin/pan-tools.cjs

@@ -41,7 +41,8 @@
  *   phase next-decimal <phase>         Calculate next decimal phase number
  *   phase add <description>            Append new phase to roadmap + create dir
  *   phase insert <after> <description> Insert decimal phase after existing
- *   phase remove <phase> [--force]     Remove phase, renumber all subsequent
+ *   phase remove <phase> [--force] [--with-decimals]
+ *                                      Remove phase, renumber all subsequent
  *   phase complete <phase>             Mark phase done, update state + roadmap
  *
  * Roadmap Operations:
@@ -92,6 +93,26 @@
  *   verify commits <h1> [h2] ...      Batch verify commit hashes
  *   verify artifacts <plan-file>       Check must_haves.artifacts
  *   verify key-links <plan-file>       Check must_haves.key_links
+ *   verify red <phase>                 Each test the phase changed fails at the
+ *     [--timeout <ms>]                 phase's base and passes at HEAD (V4)
+ *   verify mutate --phase N            Mutation report on the phase's changed lines
+ *     [--max n] [--seed n]             (V5): which mutants the suite does not kill;
+ *     [--timeout <ms>]                 writes {NN}-mutation.json
+ *   verify review-focus <phase>        Every plan has a Review Focus: <=5 items,
+ *                                      each naming its task and test (P4)
+ *   verify decisions <phase>           Plans cite only DD-N ids the design records,
+ *                                      and every recorded one is cited (P2)
+ *   usage                              Local census: installed commands and agents
+ *                                      used, never used, unfinished (L9)
+ *   research lint <phase|path>         Claims table: source and date on every claim,
+ *     [--now YYYY-MM-DD]               stale ones per type window (P3)
+ *
+ * Test Gate (V2):
+ *   test run [--phase N] [--baseline]  Run the project's tests, any language; with
+ *     [--command "<cmd>"]              --phase, write {NN}-test-run.json (or the
+ *     [--timeout <ms>] [--rebaseline]  --baseline record) to the phase directory; an
+ *                                      existing baseline is kept unless --rebaseline
+ *   test detect                        The test command the gate would run, and why
  *
  * Template Fill:
  *   template fill summary --phase N    Create pre-filled summary.md
@@ -240,6 +261,10 @@ const findings = require('./lib/findings.cjs');
 const verifyPlanSet = require('./lib/verify-plan-set.cjs');
 const verifyIntegrity = require('./lib/verify-integrity.cjs');
 const phaseGate = require('./lib/phase-gate.cjs');
+const testGate = require('./lib/test-gate.cjs');
+const verifyRed = require('./lib/verify-red.cjs');
+const verifyScope = require('./lib/verify-scope.cjs');
+const mutate = require('./lib/mutate.cjs');
 const knowledge = require('./lib/knowledge.cjs');
 const skillAlign = require('./lib/skill-align.cjs');
 const hygiene = require('./lib/hygiene.cjs');
@@ -365,7 +390,7 @@ async function main() {
     + '  --planning-dir <path>  act on an arbitrary project-relative planning tree\n'
     + '  --all-tracks           (hygiene) act on the root tree AND every discovered track\n'
     + '  env: PAN_TRACK, PAN_PLANNING_DIR (flags win)\n'
-    + '\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, findings, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links, version';
+    + '\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, test, review, research, usage, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, findings, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links, version';
 
   if (!command) {
     error(USAGE);
@@ -630,6 +655,24 @@ async function main() {
       break;
     }
 
+    case 'test': {
+      const subcommand = args[1];
+      if (subcommand === 'run') {
+        testGate.cmdTestRun(cwd, {
+          phase: getArgValue(args, '--phase'),
+          baseline: args.includes('--baseline'),
+          rebaseline: args.includes('--rebaseline'),
+          command: getArgValue(args, '--command'),
+          timeout: getArgValue(args, '--timeout'),
+        }, raw);
+      } else if (subcommand === 'detect') {
+        testGate.cmdTestDetect(cwd, raw);
+      } else {
+        error('Unknown test subcommand. Available: run, detect');
+      }
+      break;
+    }
+
     case 'verify': {
       const subcommand = args[1];
       if (subcommand === 'plan-structure') {
@@ -656,8 +699,21 @@ async function main() {
         verifyPlanSet.cmdVerifyPlanSet(cwd, args[2], raw);
       } else if (subcommand === 'test-integrity') {
         verifyIntegrity.cmdVerifyTestIntegrity(cwd, args[2], raw);
+      } else if (subcommand === 'red') {
+        verifyRed.cmdVerifyRed(cwd, args[2], raw, { timeout: getArgValue(args, '--timeout') });
+      } else if (subcommand === 'review-focus') {
+        require('./lib/plan-lint.cjs').cmdVerifyReviewFocus(cwd, args[2], raw);
+      } else if (subcommand === 'decisions') {
+        require('./lib/plan-lint.cjs').cmdVerifyDecisions(cwd, args[2], raw);
+      } else if (subcommand === 'mutate') {
+        mutate.cmdVerifyMutate(cwd, {
+          phase: getArgValue(args, '--phase') || (args[2] && !args[2].startsWith('--') ? args[2] : null),
+          max: getArgValue(args, '--max'),
+          seed: getArgValue(args, '--seed'),
+          timeout: getArgValue(args, '--timeout'),
+        }, raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale, plan-set, test-integrity');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale, plan-set, test-integrity, red, mutate, review-focus, decisions');
       }
       break;
     }
@@ -769,7 +825,7 @@ async function main() {
       } else if (subcommand === 'remove') {
         if (!args[2]) error('phase remove requires a phase number');
         const forceFlag = args.includes('--force');
-        phase.cmdPhaseRemove(cwd, args[2], { force: forceFlag }, raw);
+        phase.cmdPhaseRemove(cwd, args[2], { force: forceFlag, withDecimals: args.includes('--with-decimals') }, raw);
       } else if (subcommand === 'complete') {
         if (!args[2]) error('phase complete requires a phase number');
         const noCommit = args.includes('--no-commit');
@@ -1257,6 +1313,34 @@ async function main() {
       break;
     }
 
+    case 'review': {
+      // Program R1: the diff a reviewer reads, with the plans' intent beside it.
+      const subcommand = args[1];
+      if (subcommand === 'scope') {
+        verifyScope.cmdReviewScope(cwd, args[2], raw);
+      } else {
+        error('Unknown review subcommand. Available: scope');
+      }
+      break;
+    }
+
+    case 'usage': {
+      // Program L9: which installed commands and agents this project used, from its own files.
+      require('./lib/usage.cjs').cmdUsage(cwd, raw);
+      break;
+    }
+
+    case 'research': {
+      // Program P3: research claims carry a source and a checked date.
+      const subcommand = args[1];
+      if (subcommand === 'lint') {
+        require('./lib/research-lint.cjs').cmdResearchLint(cwd, args[2], { now: getArgValue(args, '--now') }, raw);
+      } else {
+        error('Unknown research subcommand. Available: lint');
+      }
+      break;
+    }
+
     case 'review-deep': {
       const subcommand = args[1];
       const phaseNum = args[2];
@@ -1307,8 +1391,10 @@ async function main() {
         }, raw);
       } else if (subcommand === 'debt') {
         findings.cmdFindingsDebt(cwd, { milestone: filters.milestone }, raw);
+      } else if (subcommand === 'suppressions') {
+        findings.cmdFindingsSuppressions(cwd, { phase: filters.phase, agent: filters.agent }, raw);
       } else {
-        error('Unknown findings subcommand. Available: record, list, dispose, debt');
+        error('Unknown findings subcommand. Available: record, list, dispose, debt, suppressions');
       }
       break;
     }
@@ -1359,8 +1445,10 @@ async function main() {
         }, raw);
       } else if (subcommand === 'limits') {
         cost.cmdCostLimits(cwd, raw);
+      } else if (subcommand === 'budget') {
+        cost.cmdCostBudget(cwd, getArgValue(args, '--phase') || (args[2] && !args[2].startsWith('--') ? args[2] : null), raw);
       } else {
-        error('Unknown cost subcommand. Available: report, append, clear, rebuild, limits');
+        error('Unknown cost subcommand. Available: report, append, clear, rebuild, limits, budget');
       }
       break;
     }

package/pan-wizard-core/mcp/orchestrator.cjs

@@ -101,7 +101,10 @@ function normalizeStatus(status) {
 function isPhaseOpen(phase) {
   if (!phase || typeof phase !== 'object') return false;
   const status = normalizeStatus(phase.status);
-  if (status !== COMPLETE_STATUS) return true;
+  // The legacy `verified` alias stands for complete-and-verified: once merged, that phase
+  // is finished too. Without this a caller sending it got request_merge on every cycle,
+  // for a phase already merged (found by H7's nextAction fuzz).
+  if (status !== COMPLETE_STATUS) return !(PHASE_NEXT[status] === 'request_merge' && phase.merged === true);
   // Complete on disk, but the run facts decide whether it is actually finished.
   return !(phase.verified === true && phase.merged === true);
 }

package/pan-wizard-core/references/design-methodology.md

@@ -52,7 +52,7 @@ ordered; a tier makes a contiguous prefix (plus its named additions) mandatory.
 - **Components & boundaries** — what modules are added/touched; confirm the design honors the discovered boundaries (no layer violations).
 - **Interface contract** — exact invocation + input/output schema + status/exit codes, per project convention.
 - **State & filesystem scope** — reads from / writes to (must stay within project root / `.planning/`), state mutations, side effects.
-- **Design decisions** — each significant decision: what was decided, why, alternatives rejected.
+- **Design decisions** — each decision that passes the three-question test (hard to reverse, a reasonable engineer could choose otherwise, more than one task depends on it): its id (`DD-N`, which plans cite), what was decided, why, alternatives rejected.
 
 ### 4. ADR (`phase`+)
 - A right-sized Architecture Decision Record: Status · Date · Context (problem, forces, current state, requirements traceability) · Decision (summary + numbered sub-decisions with rationale + integration) · Consequences (positive **and** negative, every negative with a mitigation or explicit acceptance).

package/pan-wizard-core/references/handoff-decisions.md

@@ -83,7 +83,7 @@ Lives in `summary.md`, after `## Files Created/Modified`:
 - DT-1: Chose <option> for O-N. Reason: <rationale>.
 
 ### Deviations (from plan; must explain)
-- DV-1: Plan said <X>; I did <Y>. Reason: <rationale>. Verification: <how I confirmed Y is acceptable>.
+- DV-1: Plan said <X>; I did <Y>. Reason: <rationale>. Verification: <how I confirmed Y is acceptable>. Cost if wrong: <low | medium | high> — <what breaks if this call was wrong>.
 
 ### Open questions for verifier
 - Q-1: <question>. Why it matters: <stake>.

package/pan-wizard-core/templates/config.json

@@ -8,9 +8,13 @@
     "auto_advance": false,
     "nyquist_validation": false,
     "phase_record_compact": false,
-    "phase_gate": "warn",
+    "phase_gate": "enforce",
+    "mutation_gate": "report",
     "phase_reports": { "enabled": false, "open": false, "theme": "auto", "index": true }
   },
+  "cost": {
+    "phase_budget_usd": 20
+  },
   "planning": {
     "commit_docs": true,
     "search_gitignored": false

package/pan-wizard-core/templates/design.md

@@ -66,10 +66,11 @@ tier may omit them.
 - Writes to: [paths — within .planning/ or project root]
 - Side effects: [git ops, dir creation, etc.]
 
-**Design decisions:**
-| Decision | Chosen | Alternative rejected | Rationale |
-|----------|--------|----------------------|-----------|
-| [point] | [what] | [alt] | [why] |
+**Design decisions:** record a decision here only when it passes all three questions: (1) is it hard to reverse once code depends on it? (2) could a reasonable engineer have chosen otherwise? (3) does more than one task or plan depend on it? A choice that fails any of them is the planner's to make, not a design decision. Each recorded decision gets an id (`DD-1`, `DD-2` …) that the plans implementing it cite; `pan-tools verify decisions` flags a plan citing an id not recorded here and a decision no plan cites.
+
+| ID | Decision | Chosen | Alternative rejected | Rationale |
+|----|----------|--------|----------------------|-----------|
+| DD-1 | [point] | [what] | [alt] | [why] |
 </architecture>
 
 <adr>

package/pan-wizard-core/templates/phase-prompt.md

@@ -71,6 +71,13 @@ Output: [What artifacts will be created]
 ### Considered and rejected
 - R-1: [alternative]. Rejected because: [reason].
 
+<!-- A Locked decision that implements a design decision cites its id: "Source: design DD-2". -->
+
+## Review Focus
+<!-- At most five inputs or failure modes the requirements imply that no test exercises yet,
+     each pinned to the task that owns the code. If genuinely none: "None — [why]". -->
+- RF-1: [input or failure mode]. Test: Task [N] adds [test that fails if it is mishandled].
+
 <tasks>
 
 <task type="auto">

package/pan-wizard-core/templates/research-project/architecture.md

@@ -161,6 +161,12 @@ src/
 |----------|---------------|-------|
 | [module A ↔ module B] | [API/events/direct] | [considerations] |
 
+## Claims
+
+| Claim | Type | Source | Checked |
+|-------|------|--------|---------|
+| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
+
 ## Sources
 
 - [Architecture references]

package/pan-wizard-core/templates/research-project/features.md

@@ -104,6 +104,12 @@ Features to defer until product-market fit is established.
 | [feature] | [how they do it] | [how they do it] | [our plan] |
 | [feature] | [how they do it] | [how they do it] | [our plan] |
 
+## Claims
+
+| Claim | Type | Source | Checked |
+|-------|------|--------|---------|
+| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
+
 ## Sources
 
 - [Competitor products analyzed]