pan-wizard 3.34.0 → 3.36.0

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

@@ -0,0 +1,257 @@
+'use strict';
+/**
+ * Mutation report on a phase's diff (program V5): would a test fail if the code the phase
+ * wrote were wrong? Coverage says a line ran; a surviving mutant says no test pins what
+ * the line does.
+ *
+ *   lines     the lines the phase's plan commits changed (git diff from the phase's
+ *             base, the same base `verify red` uses), in source files that are not tests
+ *   mutants   blunt textual swaps per language (a comparison flipped, && for ||, a
+ *             boolean return inverted, + 1 for - 1), on a changed line only, outside a
+ *             comment or string; a seeded sample of them (`--max`, `--seed`)
+ *   where     a throwaway worktree at HEAD, never the user's tree
+ *   flake     the unmutated suite runs twice first; if it fails, or the two runs
+ *             disagree, nothing a mutant does could be read, so the report aborts
+ *   result    each mutant is killed (the suite fails or times out) or survives;
+ *             survivors are listed with file, line and the swap, and written to
+ *             `{NN}-mutation.json`
+ *
+ * `workflow.mutation_gate`: `off` · `report` (the default: a report, never a refusal) ·
+ * `gate` (reserved for V5G, which turns survivors into gaps). No coverage is collected:
+ * the full suite runs per mutant, so the sample is kept small.
+ *
+ * The operator table started as scripts/mutation-probe.cjs's, which PAN runs on itself;
+ * that probe now imports it from here.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execGit, findPhaseInternal, output, error, toPosix } = require('./core.cjs');
+
+const MODES = Object.freeze(['off', 'report', 'gate']);
+const DEFAULT_MAX = 8;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+const C_FAMILY_COMPARE = [
+  { id: 'gte→gt', find: ' >= ', replace: ' > ' },
+  { id: 'gt→gte', find: ' > ', replace: ' >= ' },
+  { id: 'lte→lt', find: ' <= ', replace: ' < ' },
+  { id: 'lt→lte', find: ' < ', replace: ' <= ' },
+];
+
+/** The operators, per language family. Each is a plain textual swap, first occurrence on a line. */
+const OPERATORS = Object.freeze({
+  js: [
+    ...C_FAMILY_COMPARE,
+    { id: 'eq→neq', find: ' === ', replace: ' !== ' },
+    { id: 'neq→eq', find: ' !== ', replace: ' === ' },
+    { id: 'and→or', find: ' && ', replace: ' || ' },
+    { id: 'or→and', find: ' || ', replace: ' && ' },
+    { id: 'true→false', find: 'return true', replace: 'return false' },
+    { id: 'false→true', find: 'return false', replace: 'return true' },
+    { id: 'plus→minus', find: ' + 1', replace: ' - 1' },
+  ],
+  c: [
+    ...C_FAMILY_COMPARE,
+    { id: 'eq→neq', find: ' == ', replace: ' != ' },
+    { id: 'neq→eq', find: ' != ', replace: ' == ' },
+    { id: 'and→or', find: ' && ', replace: ' || ' },
+    { id: 'or→and', find: ' || ', replace: ' && ' },
+    { id: 'true→false', find: 'return true', replace: 'return false' },
+    { id: 'false→true', find: 'return false', replace: 'return true' },
+    { id: 'plus→minus', find: ' + 1', replace: ' - 1' },
+  ],
+  py: [
+    ...C_FAMILY_COMPARE,
+    { id: 'eq→neq', find: ' == ', replace: ' != ' },
+    { id: 'neq→eq', find: ' != ', replace: ' == ' },
+    { id: 'and→or', find: ' and ', replace: ' or ' },
+    { id: 'or→and', find: ' or ', replace: ' and ' },
+    { id: 'true→false', find: 'return True', replace: 'return False' },
+    { id: 'false→true', find: 'return False', replace: 'return True' },
+    { id: 'plus→minus', find: ' + 1', replace: ' - 1' },
+  ],
+});
+
+const LANGUAGES = [
+  { family: 'js', re: /\.(c|m)?(j|t)sx?$/i, comments: ['//', '/*', '*'] },
+  { family: 'py', re: /\.py$/i, comments: ['#'] },
+  { family: 'c', re: /\.(go|rs|java|kt|kts|cs|c|cc|cpp|h|hpp|swift|scala)$/i, comments: ['//', '/*', '*'] },
+];
+
+/** The language family of a file, or null when PAN has no operators for it. */
+function languageOf(file) {
+  return LANGUAGES.find((l) => l.re.test(file)) || null;
+}
+
+/**
+ * Is this line worth mutating? Skips comments, and a line whose only occurrence of the
+ * token is inside a string: a mutated message changes nothing a test should pin. Crude
+ * but conservative: on a line with a quote, the token must come before the first quote.
+ */
+function mutableLine(line, token, comments = ['//', '/*', '*']) {
+  const trimmed = line.trim();
+  if (!trimmed || comments.some((c) => trimmed.startsWith(c))) return false;
+  const at = line.indexOf(token);
+  if (at === -1) return false;
+  const firstQuote = Math.min(...["'", '"', '`'].map((q) => { const i = line.indexOf(q); return i === -1 ? Infinity : i; }));
+  return at < firstQuote;
+}
+
+/**
+ * Every mutation in a source text: one per (line, operator), first occurrence on the line.
+ * @param {string} src
+ * @param {{family?: string, comments?: string[], lines?: Set<number>}} [opts] - `lines` limits it to those line numbers
+ */
+function mutationsFor(src, opts = {}) {
+  const ops = OPERATORS[opts.family || 'js'];
+  const out = [];
+  src.split(/\r?\n/).forEach((line, i) => {
+    if (opts.lines && !opts.lines.has(i + 1)) return;
+    for (const op of ops) {
+      if (!mutableLine(line, op.find, opts.comments)) continue;
+      out.push({ line: i + 1, op: op.id, before: line, after: line.replace(op.find, op.replace) });
+    }
+  });
+  return out;
+}
+
+/** Apply one mutation to a source string, by line number. Throws if the line moved. */
+function applyMutation(src, mutation) {
+  const eol = src.includes('\r\n') ? '\r\n' : '\n';
+  const lines = src.split(/\r?\n/);
+  if (lines[mutation.line - 1] !== mutation.before) throw new Error(`line ${mutation.line} is not what the mutation was built from`);
+  lines[mutation.line - 1] = mutation.after;
+  return lines.join(eol);
+}
+
+/** Deterministic shuffle-and-take, so a report is reproducible from its seed. */
+function sample(items, n, seed) {
+  let s = seed >>> 0;
+  const rand = () => { s = (s * 1664525 + 1013904223) >>> 0; return s / 0x100000000; };
+  const copy = items.slice();
+  for (let i = copy.length - 1; i > 0; i--) {
+    const j = Math.floor(rand() * (i + 1));
+    [copy[i], copy[j]] = [copy[j], copy[i]];
+  }
+  return copy.slice(0, n);
+}
+
+/**
+ * The line numbers each file gained or changed between two revisions (`git diff -U0`).
+ * @returns {Map<string, Set<number>>}
+ */
+function changedLines(cwd, base, head = 'HEAD') {
+  const r = execGit(cwd, ['-c', 'core.quotepath=off', 'diff', '-U0', '--no-color', '--relative', base, head]);
+  const out = new Map();
+  if (r.exitCode !== 0) return out;
+  let file = null;
+  for (const line of r.stdout.split('\n')) {
+    const f = line.match(/^\+\+\+ (?:b\/)?(.+)$/);
+    if (f) { file = f[1] === '/dev/null' ? null : f[1].trim(); continue; }
+    const h = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (h && file) {
+      const start = Number(h[1]);
+      const count = h[2] === undefined ? 1 : Number(h[2]);
+      if (!out.has(file)) out.set(file, new Set());
+      for (let n = start; n < start + count; n++) out.get(file).add(n);
+    }
+  }
+  return out;
+}
+
+/** `workflow.mutation_gate` from config.json; `report` unless set. */
+function mutationMode(cwd) {
+  const v = (require('./test-gate.cjs').rawConfig(cwd).workflow || {}).mutation_gate;
+  return MODES.includes(v) ? v : 'report';
+}
+
+/**
+ * The mutation report for one phase.
+ * @param {string} cwd
+ * @param {string} phase
+ * @param {{max?: number, seed?: number, timeoutMs?: number}} [opts]
+ */
+function mutatePhase(cwd, phase, opts = {}) {
+  const TG = require('./test-gate.cjs');
+  const { phaseBase, withWorktree } = require('./verify-red.cjs');
+  const { isTestFile } = require('./verify-integrity.cjs');
+  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 mode = mutationMode(cwd);
+  const seed = Number.isFinite(opts.seed) ? opts.seed : 1;
+  const max = opts.max || DEFAULT_MAX;
+  const base = { phase: phaseNumber, mode, seed, checked: false };
+  if (mode === 'off' && !opts.force) return { ...base, reason: 'workflow.mutation_gate is off' };
+  const b = phaseBase(cwd, phaseNumber);
+  if (!b.base) return { ...base, reason: b.reason };
+  const suite = TG.detectTestCommand(cwd);
+  if (!suite.command) return { ...base, base: b.base, reason: suite.reason };
+
+  // Candidates: changed lines of the phase's own source files, per language.
+  const changed = changedLines(cwd, b.base);
+  const candidates = [];
+  for (const [file, lines] of changed) {
+    const lang = languageOf(file);
+    if (!lang || isTestFile(file) || !b.files.has(file) || /^\.planning\//.test(file)) continue;
+    let src;
+    try { src = fs.readFileSync(path.join(cwd, file), 'utf8'); } catch { continue; }
+    for (const m of mutationsFor(src, { family: lang.family, comments: lang.comments, lines })) candidates.push({ file, ...m });
+  }
+  if (!candidates.length) return { ...base, base: b.base, command: suite.command, candidates: 0, reason: 'no mutable line in the source the phase changed' };
+  const picked = sample(candidates, max, seed);
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const killedBy = (r) => r.timed_out || r.exit !== 0;
+
+  const wt = withWorktree(cwd, 'HEAD', (dir) => {
+    // Flake pre-check: the unmutated suite must pass, twice, or no mutant can be read.
+    const first = TG.runCommand(dir, suite.command, timeoutMs);
+    const second = TG.runCommand(dir, suite.command, timeoutMs);
+    if (killedBy(first) || killedBy(second)) {
+      return { aborted: killedBy(first) !== killedBy(second) ? 'flaky' : 'suite_fails', reason: killedBy(first) !== killedBy(second) ? 'the unmutated suite passed once and failed once: a flaky suite would make every mutant unreadable' : 'the unmutated suite fails at HEAD: fix it before measuring its tests' };
+    }
+    const results = [];
+    for (const m of picked) {
+      const file = path.join(dir, m.file);
+      const original = fs.readFileSync(file, 'utf8');
+      let mutated;
+      try { mutated = applyMutation(original, m); } catch { continue; }
+      fs.writeFileSync(file, mutated);
+      try {
+        results.push({ ...m, killed: killedBy(TG.runCommand(dir, suite.command, timeoutMs)) });
+      } finally {
+        fs.writeFileSync(file, original);
+      }
+    }
+    return { results };
+  });
+  if (wt.error) return { ...base, base: b.base, reason: wt.error };
+  const head = (execGit(cwd, ['rev-parse', 'HEAD']).stdout || '').trim() || null;
+  if (wt.value.aborted) return { ...base, base: b.base, head, command: suite.command, candidates: candidates.length, aborted: wt.value.aborted, reason: wt.value.reason };
+  const results = wt.value.results;
+  const killed = results.filter((r) => r.killed).length;
+  const survivors = results.filter((r) => !r.killed).map(({ file, line, op, before, after }) => ({ file: toPosix(file), line, op, before: before.trim(), after: after.trim() }));
+  return {
+    ...base, checked: results.length > 0, base: b.base, head, command: suite.command,
+    candidates: candidates.length, sampled: results.length, killed, survived: survivors.length,
+    score: results.length ? Number((killed / results.length).toFixed(2)) : null, survivors,
+  };
+}
+
+/**
+ * `pan-tools verify mutate --phase N [--max n] [--seed n] [--timeout ms]`: writes
+ * `{NN}-mutation.json` and exits 0 (report mode; V5G adds the gate).
+ */
+function cmdVerifyMutate(cwd, opts, raw) {
+  if (!opts.phase) error('Usage: verify mutate --phase <N> [--max <n>] [--seed <n>] [--timeout <ms>]');
+  const r = mutatePhase(cwd, opts.phase, { max: opts.max ? Number(opts.max) : undefined, seed: opts.seed !== undefined && opts.seed !== null ? Number(opts.seed) : undefined, timeoutMs: opts.timeout ? Number(opts.timeout) : undefined });
+  if (r.error) error(r.reason);
+  const info = findPhaseInternal(cwd, opts.phase);
+  const prefix = String(info.phase_number).split('.').map((p, i) => (i === 0 ? p.padStart(2, '0') : p)).join('.');
+  const file = path.join(cwd, info.directory, `${prefix}-mutation.json`);
+  fs.writeFileSync(file, JSON.stringify(r, null, 2) + '\n');
+  r.record = toPosix(path.relative(cwd, file));
+  output(r, raw, r.aborted ? `aborted:${r.aborted}` : (r.checked ? `${r.killed}/${r.sampled} killed` : 'not_checked'));
+}
+
+module.exports = { OPERATORS, MODES, languageOf, mutableLine, mutationsFor, applyMutation, sample, changedLines, mutationMode, mutatePhase, cmdVerifyMutate };

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

@@ -1269,6 +1269,18 @@ function cmdOptimizeLearn(cwd, opts, raw) {
   }, raw);
 }
 
+/**
+ * `--report` as given resolves against the project (`--cwd`), not the shell's
+ * directory; a bare file name that is not there is looked up in the reports dir.
+ */
+function resolveReportPath(cwd, given) {
+  const abs = path.resolve(cwd, given);
+  if (fs.existsSync(abs)) return abs;
+  if (path.basename(given) !== given) return abs; // a path with directories is taken as given
+  const inReports = path.join(getReportsDir(cwd), given);
+  return fs.existsSync(inReports) ? inReports : abs;
+}
+
 function cmdOptimizeApply(cwd, opts, raw) {
   const reports = listOptimizationReports(cwd);
   if (reports.error || reports.count === 0) {
@@ -1276,7 +1288,7 @@ function cmdOptimizeApply(cwd, opts, raw) {
     return;
   }
 
-  const reportPath = opts.reportPath || reports.reports[0].path;
+  const reportPath = opts.reportPath ? resolveReportPath(cwd, opts.reportPath) : reports.reports[0].path;
   const result = applyReportRecommendations(cwd, reportPath);
   output({ report: path.basename(reportPath), ...result }, raw);
 }

package/pan-wizard-core/bin/lib/phase-gate.cjs

@@ -0,0 +1,180 @@
+'use strict';
+/**
+ * The phase gate (program V1): may this phase be marked complete?
+ *
+ * Every guarantee at the end of PAN's loop used to be a sentence in a workflow:
+ * "do not advance unless the verification passed", "reconcile before advancing".
+ * The model skipped one (exec-phase's `--no-transition` path never ran reconcile at
+ * all), and `phase complete` marked the phase done regardless. The gate puts those
+ * rules in code, in one function every caller uses: `phase complete`, the native
+ * exec-waves script, and the MCP merge request.
+ *
+ * Refusal reasons, one code per class:
+ *   no_plans · missing_summary · no_verification · verification_unreadable ·
+ *   verification_failed (V9 lowering included) · human_needed_unapproved ·
+ *   verification_stale · reconcile_contradiction · test_failed · open_findings ·
+ *   stubs_found · integrity_violation
+ *
+ * What the gate could not check is listed in `not_checked`, never refused on:
+ * a skipped test gate, an unknown freshness, no git, no plan commits, the verifier
+ * switched off. `workflow.phase_gate` is `enforce` (the default since V1E: refuse
+ * unless `--force --reason`, which records a decision) or `warn` (report and proceed).
+ */
+const fs = require('fs');
+const path = require('path');
+const { findPhaseInternal, safeReadFile, loadConfig, output, error } = require('./core.cjs');
+const { isVerificationFile } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const MODES = Object.freeze(['warn', 'enforce']);
+const SERIOUS = new Set(['critical', 'high']);
+
+/** `workflow.phase_gate` from config.json: `warn`, or (anything else, absent included) `enforce`. */
+function gateMode(cwd) {
+  let cfg = null;
+  try { cfg = JSON.parse(fs.readFileSync(planningPath(cwd, 'config.json'), 'utf-8')); } catch { /* defaults */ }
+  const v = cfg && cfg.workflow && cfg.workflow.phase_gate;
+  return MODES.includes(v) ? v : 'enforce';
+}
+
+/**
+ * @param {string} cwd
+ * @param {string|number} phase
+ * @param {{mode?: 'warn'|'enforce'}} [opts]
+ * @returns {{phase, mode, ok, reasons: Array<{code, detail}>, facts: Object, not_checked: Array<{check, reason}>}|{error, reason}}
+ */
+function phaseGate(cwd, phase, opts = {}) {
+  const info = findPhaseInternal(cwd, phase);
+  if (!info || !info.found) return { error: 'phase_not_found', reason: `no phase directory for phase ${phase}` };
+  const V = require('./verdict.cjs');
+  const F = require('./findings.cjs');
+  const { reconcilePhase, verificationFreshness, scanStubs } = require('./verify.cjs');
+  const { committedFiles } = require('./verify-scope.cjs');
+  const { checkTestIntegrity } = require('./verify-integrity.cjs');
+  const TG = require('./test-gate.cjs');
+
+  const mode = MODES.includes(opts.mode) ? opts.mode : gateMode(cwd);
+  const reasons = [];
+  const notChecked = [];
+  const facts = {};
+  const refuse = (code, detail, extra = {}) => reasons.push({ code, detail, ...extra });
+  const skip = (check, reason) => notChecked.push({ check, reason });
+  const phaseNumber = info.phase_number || String(phase);
+  const dir = path.join(cwd, info.directory);
+
+  // 1. Every plan has a summary.
+  const plans = info.plans || [];
+  const incomplete = info.incomplete_plans || [];
+  facts.plans = `${plans.length - incomplete.length}/${plans.length}`;
+  if (!plans.length) refuse('no_plans', 'the phase has no plans');
+  else if (incomplete.length) refuse('missing_summary', `${incomplete.length} plan(s) have no summary: ${incomplete.join(', ')}`, { plans: incomplete });
+
+  // 2. A passing verification (with code facts applied, V9).
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { /* unreadable reads as empty */ }
+  const verFile = names.filter(isVerificationFile).sort().pop();
+  const verifierOn = loadConfig(cwd).verifier !== false;
+  if (!verFile) {
+    if (verifierOn) refuse('no_verification', 'the phase has no verification; run /pan:verify-phase');
+    else skip('verification', 'workflow.verifier is off');
+  } else {
+    // The engine's test run (V2) is a code fact: a failed run lowers a written pass.
+    const run = TG.readTestRun(cwd, phaseNumber);
+    const parsed = V.parseVerdictText(safeReadFile(path.join(dir, verFile)) || '', { agent: 'pan-verifier', phase: phaseNumber, facts: TG.testRunFacts(cwd, phaseNumber) });
+    if (!parsed.ok) {
+      refuse('verification_unreadable', `${verFile}: ${parsed.reason}`);
+    } else {
+      const v = parsed.verdict;
+      const fm = V.verdictFromVerificationFrontmatter(safeReadFile(path.join(dir, verFile)) || '') || {};
+      facts.verification = v.verdict;
+      // The verification's own word, else the engine's record of the run.
+      const gate = fm.test_gate || (run && run.status) || null;
+      facts.test_gate = gate;
+      if (run) facts.test_run = run.status;
+      if (parsed.lowered_by && parsed.lowered_by.length) facts.lowered_by = parsed.lowered_by;
+      if (gate === 'failed') refuse('test_failed', fm.test_gate === 'failed' ? 'the verification records test_gate: failed' : `the engine's test run failed: ${run.reason || 'see the test-run record'}`);
+      else if (gate === 'skipped') skip('tests', fm.test_gate ? 'the test gate was skipped' : (run.reason || 'the test gate was skipped'));
+      else if (!gate) skip('tests', 'the verification does not record its test gate');
+      if (v.outcome === 'fail') {
+        refuse('verification_failed', `the verification is ${v.verdict}${v.agent_verdict ? ` (the verifier wrote ${v.agent_verdict})` : ''}`);
+      } else if (v.outcome === 'needs_human') {
+        const human = F.listFindings(cwd, { phase: phaseNumber, agent: 'pan-verifier', class: 'human' }).findings;
+        const unapproved = human.filter((f) => f.status !== 'decision');
+        if (unapproved.length || !human.length) {
+          refuse('human_needed_unapproved', `${unapproved.length || 'the'} human verification item(s) have no recorded approval; record it with \`findings dispose <id> --as decision --reason "<what was checked>"\``, { ids: unapproved.map((f) => f.id) });
+        }
+      }
+    }
+  }
+
+  // 3. The verification still describes the code.
+  if (verFile) {
+    const fresh = verificationFreshness(cwd, phaseNumber, info);
+    facts.freshness = fresh.state;
+    if (fresh.state === 'stale') refuse('verification_stale', `files changed since the verified commit: ${(fresh.changed_since || []).slice(0, 5).join(', ')}`, { changed_since: fresh.changed_since });
+    else if (fresh.state === 'unknown') skip('freshness', fresh.reason || 'unknown');
+  }
+
+  // 4. The written verdict agrees with the mechanical checks.
+  if (verFile) {
+    const rec = reconcilePhase(cwd, phaseNumber);
+    facts.reconciled = rec.reconciled;
+    if (!rec.reconciled) refuse('reconcile_contradiction', rec.contradictions.join('; '), { contradictions: rec.contradictions });
+  }
+
+  // 5. No critical or high finding left open without a disposition.
+  const open = F.listFindings(cwd, { phase: phaseNumber, status: 'open' }).findings
+    .filter((f) => SERIOUS.has(f.severity) && f.class !== 'human');
+  facts.open_serious_findings = open.length;
+  if (open.length) refuse('open_findings', `${open.length} critical/high finding(s) are open: dispose each (\`findings dispose <id> --as fixed|deferred|dismissed|decision --reason "…"\`) or fix it`, { ids: open.map((f) => f.id) });
+
+  // 6. No stub in the files the phase committed.
+  const committed = committedFiles(cwd, phaseNumber);
+  if (!committed.git) {
+    skip('stubs', 'git is unavailable');
+  } else {
+    const files = [...committed.files].filter((f) => fs.existsSync(path.join(cwd, f)));
+    const stubs = scanStubs(cwd, { files });
+    facts.stubs_blocking = stubs.blocking;
+    if (stubs.blocking) refuse('stubs_found', `${stubs.blocking} stub marker(s) in committed files: ${stubs.findings.filter((s) => s.severity === 'high').slice(0, 3).map((s) => `${s.file}:${s.line}`).join(', ')}`);
+  }
+
+  // 7. The phase did not weaken its own tests.
+  const integrity = checkTestIntegrity(cwd, phaseNumber);
+  if (integrity.error || !integrity.checked) {
+    skip('test_integrity', integrity.reason || integrity.error);
+  } else {
+    facts.test_integrity = integrity.ok ? 'clean' : 'violated';
+    if (!integrity.ok) refuse('integrity_violation', integrity.violations.slice(0, 3).map((x) => `${x.code} ${x.file}`).join('; '), { violations: integrity.violations });
+  }
+
+  return { phase: phaseNumber, mode, ok: reasons.length === 0, reasons, facts, not_checked: notChecked };
+}
+
+/**
+ * `--force --reason`: complete past the gate, on the record. Every open finding the
+ * gate counted gets a `decision` disposition with the reason, and the trace logs it.
+ */
+function recordGateOverride(cwd, gate, reason) {
+  const F = require('./findings.cjs');
+  const ids = [];
+  for (const r of gate.reasons) for (const id of r.ids || []) if (!ids.includes(id)) ids.push(id);
+  const disposed = ids.length ? F.disposeFindings(cwd, { ids, as: 'decision', reason: `phase completed past the gate: ${reason}` }) : { disposed: [] };
+  try {
+    require('./optimize.cjs').logTraceEvent(cwd, {
+      type: 'decision', category: 'phase_gate_forced', agent: 'orchestrator', phase: gate.phase,
+      description: `phase ${gate.phase} completed past the gate (${gate.reasons.map((r) => r.code).join(', ')}): ${reason}`,
+      impact: 'major', context: { reasons: gate.reasons.map((r) => r.code), reason },
+    });
+  } catch { /* telemetry is best effort */ }
+  return { reason, refused_by: gate.reasons.map((r) => r.code), disposed: disposed.disposed || [] };
+}
+
+function cmdPhaseGate(cwd, phase, raw, opts = {}) {
+  if (!phase) error('Usage: phase gate <N> [--mode warn|enforce]');
+  const r = phaseGate(cwd, phase, opts);
+  if (r.error) { output(r, raw); return; }
+  output(r, raw, r.ok ? 'pass' : 'refuse', r.ok ? 0 : 1);
+}
+
+module.exports = { phaseGate, recordGateOverride, gateMode, cmdPhaseGate, MODES };

package/pan-wizard-core/bin/lib/phase-remove.cjs

@@ -12,6 +12,21 @@ const { writeStateMd, readStateSafe } = require('./state.cjs');
 const { ROADMAP_FILE, STATE_FILE, isSummaryFile } = require('./constants.cjs');
 const { planningPath, phasesPath, fileAccessible } = require('./utils.cjs');
 
+/**
+ * A regex source matching a phase number as any roadmap writes it: `phase insert` writes
+ * padded decimals (`Phase 01.1`) and `phase add` unpadded integers (`Phase 3`), so "1.1"
+ * must match both `1.1` and `01.1` (found by H7's property test: removing 1.1 deleted its
+ * directory and left its roadmap section behind).
+ * @param {string} num - a phase number, padded or not ("1.1", "01.1", "3")
+ */
+function phaseNumPattern(num) {
+  const [int, ...rest] = String(num).split('.');
+  return `0*${escapeRegex(String(parseInt(int, 10)))}${rest.map((d) => `\\.${escapeRegex(d)}`).join('')}`;
+}
+
+/** Write `next` in the style `matched` was written in: padded to two digits, or not. */
+const samePadding = (matched, next) => (/^0\d/.test(matched) ? String(next).padStart(2, '0') : String(next));
+
 /**
  * Delete a phase directory from disk.
  * @param {string} phaseDir - Absolute path to the phase directory to remove
@@ -200,7 +215,7 @@ function removePhaseSection(content, phaseNum) {
       fenced.fill(true, top.open, i + 1);
     } else if (!top || f[2].trim()) stack.push({ fence: f[1], open: i });
   }
-  const headRe = new RegExp(`^(#{2,4})\\s*Phase\\s+${escapeRegex(phaseNum)}\\s*:`, 'i');
+  const headRe = new RegExp(`^(#{2,4})\\s*Phase\\s+${phaseNumPattern(phaseNum)}\\s*:`, 'i');
   const start = lines.findIndex((l, i) => !fenced[i] && headRe.test(l));
   if (start === -1) return content;
   const levelEndRe = new RegExp(`^#{1,${lines[start].match(headRe)[1].length}}\\s`);
@@ -258,7 +273,7 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
   } catch { return; }
 
   roadmapContent = removePhaseSection(roadmapContent, phaseNum);
-  const targetEscaped = escapeRegex(phaseNum);
+  const targetEscaped = phaseNumPattern(phaseNum);
 
   // Remove checkbox list items referencing this phase
   const checkboxPattern = new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${targetEscaped}[:\\s][^\\n]*`, 'gi');
@@ -291,14 +306,14 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
 
       // Phase headings: ## Phase 18: or ### Phase 18.1: -> ## Phase 17: / ### Phase 17.1:
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}((?:\\.\\d+)?\\s*:)`, 'gi'),
-        `$1${newStr}$2`
+        new RegExp(`(#{2,4}\\s*Phase\\s+)(0*)${oldStr}((?:\\.\\d+)?\\s*:)`, 'gi'),
+        (_, head, zeros, tail) => `${head}${samePadding(zeros + oldStr, newNum)}${tail}`
       );
 
       // Inline phase references: "Phase 18:", "Phase 18 " or "Phase 18.1:" -> "Phase 17..."
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(Phase\\s+)${oldStr}((?:\\.\\d+)?[:\\s])`, 'g'),
-        `$1${newStr}$2`
+        new RegExp(`(Phase\\s+)(0*)${oldStr}((?:\\.\\d+)?[:\\s])`, 'g'),
+        (_, head, zeros, tail) => `${head}${samePadding(zeros + oldStr, newNum)}${tail}`
       );
 
       // Plan references in padded form: 18-01 / 18.1-01 -> 17-01 / 17.1-01, never inside a date (2026-10-01)
@@ -309,26 +324,65 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
 
       // Progress table row numbers: | 18. or | 18.1. -> | 17. / | 17.1.
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(\\|\\s*)${oldStr}((?:\\.\\d+)?)\\.\\s`, 'g'),
-        `$1${newStr}$2. `
+        new RegExp(`(\\|\\s*)(0*)${oldStr}((?:\\.\\d+)?)\\.\\s`, 'g'),
+        (_, head, zeros, dec) => `${head}${samePadding(zeros + oldStr, newNum)}${dec}. `
       );
 
       // Depends-on references: "Depends on:** Phase 18" -> "Phase 17"
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'),
-        `$1${newStr}`
+        new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)(0*)${oldStr}\\b`, 'gi'),
+        (_, head, zeros) => `${head}${samePadding(zeros + oldStr, newNum)}`
       );
     }
+  } else {
+    // Decimal removal: the siblings above it move down one (06.3 -> 06.2), as their
+    // directories already did. Upward, so a renamed reference is never renamed twice.
+    const [baseStr, removedStr] = normalized.split('.');
+    const base = escapeRegex(String(parseInt(baseStr, 10)));
+    for (let dec = parseInt(removedStr, 10) + 1; dec <= 99; dec++) {
+      const was = `(0*${base})\\.${dec}`;
+      roadmapContent = roadmapContent
+        .replace(new RegExp(`(Phase\\s+)${was}([:\\s])`, 'gi'), (_, head, int, tail) => `${head}${int}.${dec - 1}${tail}`)
+        .replace(new RegExp(`(\\|\\s*)${was}\\.\\s`, 'g'), (_, head, int) => `${head}${int}.${dec - 1}. `)
+        .replace(new RegExp(`(?<![\\d.-])${was}-(\\d{2})(?!\\d)`, 'g'), (_, int, plan) => `${int}.${dec - 1}-${plan}`);
+    }
   }
 
   try { fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); } catch { /* best-effort */ }
 }
 
+/**
+ * The decimal phases inserted after an integer phase, from its directories and its
+ * roadmap headings (a phase can be in the roadmap before it has a directory).
+ * @param {string} phasesDir - the phases directory
+ * @param {string} roadmapPath - roadmap.md
+ * @param {number} baseInt - the integer phase
+ * @returns {{num: string, dir: string|null}[]} in numeric order, e.g. [{num: '3.1', dir: '03.1-fix'}]
+ */
+function findDecimalPhases(phasesDir, roadmapPath, baseInt) {
+  const found = new Map();
+  const dirRe = new RegExp(`^0*${baseInt}\\.(\\d+)(?:-|$)`);
+  try {
+    for (const entry of fs.readdirSync(phasesDir, { withFileTypes: true })) {
+      const m = entry.isDirectory() && entry.name.match(dirRe);
+      if (m) found.set(Number(m[1]), entry.name);
+    }
+  } catch { /* no phases directory: the roadmap alone decides */ }
+  let text = '';
+  try { text = fs.readFileSync(roadmapPath, 'utf8'); } catch { /* unreadable: directories alone */ }
+  for (const m of text.matchAll(new RegExp(`^#{2,4}\\s*Phase\\s+0*${baseInt}\\.(\\d+)\\s*:`, 'gim'))) {
+    if (!found.has(Number(m[1]))) found.set(Number(m[1]), null);
+  }
+  return [...found.entries()].sort((a, b) => a[0] - b[0]).map(([dec, dir]) => ({ num: `${baseInt}.${dec}`, dir }));
+}
+
 /**
  * Remove a phase directory, renumber subsequent phases, and update ROADMAP/STATE.
+ * An integer phase that still has decimal phases is refused unless `withDecimals`.
  * @param {string} cwd - Working directory path
  * @param {string} targetPhase - Phase number to remove
- * @param {Object} options - Options (force: skip executed-work check)
+ * @param {Object} options - Options (force: skip executed-work check; withDecimals: remove
+ *   the integer phase's decimal phases with it)
  * @param {boolean} raw - If true, output raw value instead of JSON
  * @returns {void}
  */
@@ -393,6 +447,21 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     }
   }
 
+  // An integer phase's decimal phases (3.1, 3.2 …) were inserted after it. Removing the
+  // integer alone orphaned them: they stayed on disk and in the roadmap and, once the
+  // phases above were renumbered, read as decimals of a different phase, listed before
+  // their new base. So they go with it only when asked; otherwise refuse, naming them.
+  const decimals = isDecimal ? [] : findDecimalPhases(phasesDir, roadmapPath, parseInt(normalized, 10));
+  if (decimals.length && !options.withDecimals) {
+    error(`Phase ${targetPhase} has decimal phases ${decimals.map((d) => d.num).join(', ')} inserted after it. Remove them first, or pass --with-decimals to remove them with it.`);
+  }
+  if (!force) {
+    for (const d of decimals) {
+      const executed = d.dir ? fs.readdirSync(path.join(phasesDir, d.dir)).filter(isSummaryFile).length : 0;
+      if (executed) error(`Phase ${d.num} has ${executed} executed plan(s). Use --force to remove anyway.`);
+    }
+  }
+
   // Check for executed work (summary.md files)
   if (targetDir && !force) {
     const targetPath = path.join(phasesDir, targetDir);
@@ -403,6 +472,16 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     }
   }
 
+  // --with-decimals: every check has passed, so remove the decimals first, highest first,
+  // which leaves no sibling above any of them to renumber.
+  const removedDecimals = [];
+  for (const d of decimals.slice().reverse()) {
+    if (d.dir) removePhaseFromDisk(path.join(phasesDir, d.dir));
+    updateRoadmapAfterRemoval(cwd, d.num, true, normalizePhaseName(d.num));
+    updateStateAfterPhaseRemoval(cwd);
+    removedDecimals.unshift(d.num);
+  }
+
   // Delete target directory
   let removeWarning = null;
   if (targetDir) {
@@ -449,6 +528,7 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     roadmap_updated: true,
     state_updated: stateUpdated,
   };
+  if (removedDecimals.length) result.removed_decimals = removedDecimals;
   if (renameError) result.rename_warning = renameError;
   if (removeWarning) result.remove_warning = removeWarning;