pan-wizard 3.35.0 → 3.36.0

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

@@ -27,6 +27,12 @@
  *   - IDEMPOTENCY: recording the same artifact twice is a no-op that returns the
  *     first verdict (record_sig). That is why exec-phase and verify-phase may both
  *     record one verification.md.
+ *   - LEARNED SUPPRESSIONS (R3): a dismissed finding is noise for its file as it was
+ *     when dismissed. The same judge raising it again (same signature, sameFinding)
+ *     is filtered, in the dismissal's phase (candidate) or, once dismissed in two
+ *     phases, in any phase (promoted). When the file changes the suppression retires
+ *     and the finding comes back open. Security and logic findings, and findings
+ *     with no file, are never suppressed: a re-report reopens them.
  */
 const fs = require('fs');
 const path = require('path');
@@ -40,6 +46,11 @@ const LEDGER_V = 1;
 const REASON_MAX = 300;
 const FINDING_ID_RE = /^f_[0-9a-f]{10}$/;
 const STATUSES = Object.freeze(['open', ...V.DISPOSITIONS]);
+// Logic findings are never suppressed (R3): what the code does wrong, or not at all.
+const LOGIC_CLASSES = Object.freeze(['defect', 'contradicts', 'missing', 'partial']);
+// Security findings are never suppressed either, whatever class a judge gave them.
+const SECURITY_RE = /secur|inject|xss|csrf|ssrf|secret|credential|password|authenticat|authoriz|\bauth\b|token|crypt|traversal|privilege|sanitiz|escap|cve-|owasp|\brce\b|deserializ/i;
+const SECURITY_AGENTS = Object.freeze(['pan-hardener']);
 
 function ledgerPath(cwd) {
   return planningPath(cwd, FINDINGS_FILE);
@@ -80,7 +91,7 @@ function foldFindings(rows) {
         id: r.id, phase: r.phase, milestone: r.milestone || null, agent: r.agent, class: r.class,
         severity: r.severity, where: r.where || null, summary: r.summary, first_seen: r.ts,
         first_verdict_id: r.verdict_id || null, reports: 0, last_reported: null, _reportedSeq: -1,
-        disposition: null, reason: null, disposed_at: null, auto: false, _disposedSeq: -1,
+        disposition: null, reason: null, disposed_at: null, auto: false, file_sha: null, _disposedSeq: -1, _returnedSeq: -1,
       });
     } else if (r.kind === 'verdict') {
       verdicts.push({ ...r, _seq: seq });
@@ -91,6 +102,11 @@ function foldFindings(rows) {
         f.last_reported = r.ts;
         f._reportedSeq = seq;
       }
+      // A dismissed finding raised again once its suppression no longer holds (R3).
+      for (const id of Array.isArray(r.returned_ids) ? r.returned_ids : []) {
+        const f = findings.get(id);
+        if (f) f._returnedSeq = seq;
+      }
     } else if (r.kind === 'disposition' && typeof r.id === 'string') {
       const f = findings.get(r.id);
       if (!f || !V.DISPOSITIONS.includes(r.disposition)) return;
@@ -98,12 +114,14 @@ function foldFindings(rows) {
       f.reason = r.reason || null;
       f.disposed_at = r.ts;
       f.auto = r.auto === true;
+      f.file_sha = r.file_sha || null;
       f._disposedSeq = seq;
     }
   });
   for (const f of findings.values()) {
     if (!f.disposition) f.status = 'open';
     else if (f.disposition === 'fixed' && f._reportedSeq > f._disposedSeq) f.status = 'open';
+    else if (f._returnedSeq > f._disposedSeq) f.status = 'open';
     else f.status = f.disposition;
   }
   return { verdicts, findings };
@@ -111,7 +129,7 @@ function foldFindings(rows) {
 
 /** A finding as the CLI shows it (internal sequence fields removed). */
 function publicFinding(f) {
-  const { _reportedSeq, _disposedSeq, ...rest } = f;
+  const { _reportedSeq, _disposedSeq, _returnedSeq, ...rest } = f;
   return rest;
 }
 
@@ -168,6 +186,52 @@ function truncateReason(s) {
   return String(s).replace(/\s+/g, ' ').trim().slice(0, REASON_MAX);
 }
 
+// ─── Learned suppressions (R3) ──────────────────────────────────────────────
+
+/** Security and logic findings are always reported, dismissed or not. */
+function neverSuppressed(f, agent) {
+  return LOGIC_CLASSES.includes(f.class) || SECURITY_AGENTS.includes(agent) || SECURITY_RE.test(String(f.summary || ''));
+}
+
+/** The content hash of the project file a `where` names, or null (no file, outside the project, unreadable). */
+function fileSha(cwd, where) {
+  const file = fileOf(where);
+  if (!file || file.startsWith('code-fact:')) return null;
+  const abs = path.resolve(cwd, file);
+  const rel = path.relative(path.resolve(cwd), abs);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  try { return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex'); } catch { return null; }
+}
+
+/**
+ * Every learned suppression: a dismissed finding scoped to a file, of a kind that may
+ * be suppressed. `active` while the file is as it was when dismissed; `promoted` once
+ * the same judge dismissed the same signature in two phases (active ones only).
+ */
+function learnedSuppressions(cwd, fold) {
+  const shas = new Map();
+  const current = (where) => {
+    const k = fileOf(where);
+    if (!shas.has(k)) shas.set(k, fileSha(cwd, where));
+    return shas.get(k);
+  };
+  const all = [...fold.findings.values()]
+    .filter((f) => f.status === 'dismissed' && f.file_sha && !neverSuppressed(f, f.agent))
+    .map((f) => ({ f, active: current(f.where) === f.file_sha }));
+  return all.map((s) => {
+    const phases = new Set(all.filter((o) => o.active && o.f.agent === s.f.agent && sameFinding(o.f, s.f)).map((o) => V.comparablePhase(o.f.phase)));
+    return { ...s, scope: phases.size >= 2 ? 'promoted' : 'candidate' };
+  });
+}
+
+/** The suppression that filters this judge's finding in this phase, or null. */
+function suppressionFor(supps, agent, phase, f) {
+  if (neverSuppressed(f, agent)) return null;
+  const hits = supps.filter((s) => s.active && s.f.agent === agent && sameFinding(s.f, f)
+    && (s.scope === 'promoted' || samePhase(s.f.phase, phase)));
+  return hits.find((s) => samePhase(s.f.phase, phase)) || hits[0] || null;
+}
+
 /**
  * How stable a judge's findings are across its reports on one phase (V6): between
  * consecutive verdicts, how many ids appeared and how many disappeared. A judge whose
@@ -218,8 +282,14 @@ function recordVerdict(cwd, input) {
   const text = typeof input.text === 'string' ? input.text : '';
   if (!text.trim()) return { error: 'empty_input', reason: 'nothing to record' };
 
-  const parsed = V.parseVerdictText(text, { agent: input.agent, phase });
+  let parsed = V.parseVerdictText(text, { agent: input.agent, phase });
   if (!parsed.ok) return { error: parsed.error, reason: parsed.reason };
+  // A verification is read against the engine's test run (V2): a failed run is a code
+  // fact that lowers the verifier's pass, as a failed test_gate already does (V9).
+  if (parsed.verdict.agent === 'pan-verifier') {
+    const facts = require('./test-gate.cjs').testRunFacts(cwd, phase);
+    if (facts.length) parsed = V.parseVerdictText(text, { agent: input.agent, phase, facts });
+  }
   const verdict = parsed.verdict;
   const agent = verdict.agent;
   const recordSig = V.recordSig(text);
@@ -237,7 +307,7 @@ function recordVerdict(cwd, input) {
 
   const dup = fold.verdicts.find((r) => r.record_sig === recordSig && r.agent === agent && samePhase(r.phase, phase));
   if (dup) {
-    return { ...base, recorded: false, duplicate: true, verdict_id: dup.verdict_id, attempt: dup.attempt, phase, findings: (dup.finding_ids || []).length, new: 0, rematched: 0, resolved: 0, unaddressed: [], reopened: 0 };
+    return { ...base, recorded: false, duplicate: true, verdict_id: dup.verdict_id, attempt: dup.attempt, phase, findings: (dup.finding_ids || []).length, new: 0, rematched: 0, resolved: 0, unaddressed: [], reopened: 0, suppressed: dup.suppressed || [], returned: (dup.returned_ids || []).length };
   }
 
   const prior = fold.verdicts.filter((r) => r.agent === agent && samePhase(r.phase, phase));
@@ -251,6 +321,9 @@ function recordVerdict(cwd, input) {
   const newRows = [];
   const findingRows = [];
   const mine = [...fold.findings.values()].filter((e) => e.agent === agent && samePhase(e.phase, phase));
+  const supps = learnedSuppressions(cwd, fold);
+  const suppressed = [];
+  const returned = [];
   let rematched = 0;
   for (const f of verdict.findings) {
     let id = V.findingId(phase, agent, f);
@@ -261,6 +334,17 @@ function recordVerdict(cwd, input) {
       if (earlier) { id = earlier.id; rematched++; }
     }
     if (ids.includes(id)) continue; // the same finding twice in one report is one finding
+    // A learned suppression (R3) filters it; a dismissed finding no suppression
+    // covers any more comes back open.
+    const existing = fold.findings.get(id);
+    if (!existing || existing.status === 'dismissed') {
+      const s = suppressionFor(supps, agent, phase, f);
+      if (s) {
+        suppressed.push({ id: s.f.id, scope: s.scope, summary: f.summary });
+        continue;
+      }
+      if (existing) returned.push(id);
+    }
     ids.push(id);
     if (!fold.findings.has(id)) {
       findingRows.push({ v: LEDGER_V, kind: 'finding', ts, id, verdict_id: verdictId, phase, milestone, agent, class: f.class, severity: f.severity, where: f.where, summary: f.summary });
@@ -307,6 +391,8 @@ function recordVerdict(cwd, input) {
   newRows.push({
     v: LEDGER_V, kind: 'verdict', ts, verdict_id: verdictId, record_sig: recordSig, phase, milestone, agent,
     verdict: verdict.verdict, outcome: verdict.outcome, ...lowered, attempt, source, finding_ids: ids,
+    ...(returned.length ? { returned_ids: returned } : {}),
+    ...(suppressed.length ? { suppressed } : {}),
     by_severity: bySeverity, by_class: byClass, warnings: parsed.warnings,
     ...(notChecked.length ? { not_checked: notChecked } : {}),
     // A plan check is bound to the plans it checked (V7): exec-phase compares this
@@ -338,7 +424,7 @@ function recordVerdict(cwd, input) {
     });
   }
 
-  return { ...base, recorded: true, duplicate: false, verdict_id: verdictId, attempt, phase, findings: ids.length, new: findingRows.length, rematched, resolved: resolveRows.length, unaddressed, reopened, ledger: planningRel(FINDINGS_FILE) };
+  return { ...base, recorded: true, duplicate: false, verdict_id: verdictId, attempt, phase, findings: ids.length, new: findingRows.length, rematched, resolved: resolveRows.length, unaddressed, reopened, suppressed, returned: returned.length, ledger: planningRel(FINDINGS_FILE) };
 }
 
 /**
@@ -373,7 +459,10 @@ function disposeFindings(cwd, input) {
     const f = fold.findings.get(id);
     if (!f) { skipped.push({ id, why: 'unknown id' }); continue; }
     if (f.status === as) { skipped.push({ id, why: `already ${as}` }); continue; }
-    out.push({ v: LEDGER_V, kind: 'disposition', ts, id, disposition: as, reason: reason || null, auto: false });
+    // A dismissal remembers its file as it was (R3): it suppresses the finding only
+    // until that file changes.
+    const fsha = as === 'dismissed' ? fileSha(cwd, f.where) : null;
+    out.push({ v: LEDGER_V, kind: 'disposition', ts, id, disposition: as, reason: reason || null, auto: false, ...(fsha ? { file_sha: fsha } : {}) });
     disposed.push(id);
   }
   appendRows(cwd, out);
@@ -408,6 +497,19 @@ function listFindings(cwd, filters = {}) {
   };
 }
 
+/** Learned suppressions (R3), each with its scope and whether its file is unchanged. */
+function listSuppressions(cwd, filters = {}) {
+  const fold = foldFindings(readLedger(cwd).rows);
+  let list = learnedSuppressions(cwd, fold);
+  if (filters.agent) list = list.filter((s) => s.f.agent === filters.agent);
+  if (filters.phase) list = list.filter((s) => s.scope === 'promoted' || samePhase(s.f.phase, filters.phase));
+  const suppressions = list.map((s) => ({
+    id: s.f.id, agent: s.f.agent, phase: s.f.phase, class: s.f.class, file: fileOf(s.f.where), summary: s.f.summary,
+    reason: s.f.reason, scope: s.scope, active: s.active,
+  }));
+  return { contract: V.VERDICT_CONTRACT, suppressions, active: suppressions.filter((s) => s.active).length };
+}
+
 /**
  * Tech debt for a milestone audit: deferred findings (with the reason recorded at
  * the time) and findings nobody disposed, grouped by phase.
@@ -470,6 +572,11 @@ function cmdFindingsList(cwd, opts, raw) {
   output(r, raw, String(r.counts.total));
 }
 
+function cmdFindingsSuppressions(cwd, opts, raw) {
+  const r = listSuppressions(cwd, opts);
+  output(r, raw, String(r.active));
+}
+
 function cmdFindingsDebt(cwd, opts, raw) {
   const r = findingsDebt(cwd, opts);
   output(r, raw, `${r.deferred_count} deferred, ${r.open_count} open`);
@@ -488,6 +595,7 @@ module.exports = {
   recordVerdict,
   disposeFindings,
   listFindings,
+  listSuppressions,
   findingsDebt,
   findingsChurn,
   sameFinding,
@@ -496,4 +604,5 @@ module.exports = {
   cmdFindingsDispose,
   cmdFindingsList,
   cmdFindingsDebt,
+  cmdFindingsSuppressions,
 };

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

@@ -175,7 +175,7 @@ function cmdGitPush(cwd, opts, raw) {
 function cmdGitStatus(cwd, opts, raw) {
   if (!isGitRepo(cwd)) { _notGitRepo(raw); return; }
   const branch = getCurrentBranch(cwd);
-  const r = execGit(cwd, ['status', '--porcelain']);
+  const r = execGit(cwd, ['status', '--porcelain'], { keepLeading: true });
   if (r.exitCode !== 0) {
     output({ error: 'status_failed', detail: r.stderr }, raw, 'status failed');
     return;

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/phase-gate.cjs

@@ -17,8 +17,8 @@
  *
  * 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 `warn` (default: report and proceed) or
- * `enforce` (refuse unless `--force --reason`, which records a decision).
+ * 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');
@@ -29,12 +29,12 @@ const { planningPath } = require('./utils.cjs');
 const MODES = Object.freeze(['warn', 'enforce']);
 const SERIOUS = new Set(['critical', 'high']);
 
-/** `workflow.phase_gate` from config.json: `enforce` or (anything else) `warn`. */
+/** `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 : 'warn';
+  return MODES.includes(v) ? v : 'enforce';
 }
 
 /**
@@ -51,6 +51,7 @@ function phaseGate(cwd, phase, opts = {}) {
   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 = [];
@@ -77,18 +78,23 @@ function phaseGate(cwd, phase, opts = {}) {
     if (verifierOn) refuse('no_verification', 'the phase has no verification; run /pan:verify-phase');
     else skip('verification', 'workflow.verifier is off');
   } else {
-    const parsed = V.parseVerdictText(safeReadFile(path.join(dir, verFile)) || '', { agent: 'pan-verifier', phase: phaseNumber });
+    // 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;
-      facts.test_gate = fm.test_gate || null;
+      // 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 (fm.test_gate === 'failed') refuse('test_failed', 'the verification records test_gate: failed');
-      else if (fm.test_gate === 'skipped') skip('tests', 'the test gate was skipped');
-      else if (!fm.test_gate) skip('tests', 'the verification does not record its test gate');
+      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') {