pan-wizard 3.36.0 → 3.37.0

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

@@ -0,0 +1,149 @@
+'use strict';
+/**
+ * UAT through the engine (program L8): the walkthrough is a portable markdown workflow
+ * (workflows/uat-walkthrough.md, `/pan:verify-phase N --uat`), and what it records goes
+ * through these verbs, so every runtime leaves the same `{phase}-uat.md`:
+ *
+ *   uat record <phase> --test N --result pass|issue|skipped [--reported "…"] [--severity S] [--reason "…"]
+ *       sets one test's result, then rebuilds `## Summary` and `## Gaps` (the YAML list
+ *       diagnose-issues and `plan-phase --gaps` read). Diagnosis fields a gap already
+ *       carries (root_cause, artifacts, missing, debug_session) survive a re-record.
+ *       The session is `complete` when no test is pending.
+ *   uat status <phase>
+ *       counts and the gaps, for the walkthrough to decide whether to diagnose.
+ *
+ * The file shape is templates/uat.md.
+ */
+const fs = require('fs');
+const path = require('path');
+const { findPhaseInternal, output, error, toLf, dominantEol, withEol } = require('./core.cjs');
+
+const RESULTS = Object.freeze(['pass', 'issue', 'skipped']);
+const SEVERITIES = Object.freeze(['blocker', 'major', 'minor', 'cosmetic']);
+const KEEP_GAP_FIELDS = Object.freeze(['root_cause', 'artifacts', 'missing', 'debug_session']);
+
+const unquote = (s) => String(s || '').trim().replace(/^"(.*)"$/, '$1');
+const quote = (s) => `"${String(s || '').replace(/"/g, "'")}"`;
+
+function uatPath(cwd, phase) {
+  const info = findPhaseInternal(cwd, phase);
+  if (!info || !info.found) return null;
+  const dir = path.join(cwd, info.directory);
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => /-uat\.md$/i.test(f)); } catch { /* none */ }
+  return files.length ? path.join(dir, files[0]) : null;
+}
+
+/** Parse a uat.md: frontmatter status, the tests, and the gaps' extra fields by test number. */
+function parseUat(raw) {
+  const text = toLf(String(raw || ''));
+  const status = ((/^---\n[\s\S]*?^status:\s*(.+)$/m.exec(text) || [])[1] || '').trim();
+  const tests = [];
+  const testsSec = (/^## Tests\s*$([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(text) || [])[1] || '';
+  for (const block of testsSec.split(/^(?=### \d+\.)/m)) {
+    const h = /^### (\d+)\.\s*(.+)$/m.exec(block);
+    if (!h) continue;
+    const field = (k) => ((new RegExp(`^${k}:\\s*(.*)$`, 'm').exec(block) || [])[1] || '').trim();
+    let result = field('result').replace(/^\[|\]$/g, '') || 'pending';
+    tests.push({ number: Number(h[1]), name: h[2].trim(), expected: field('expected'), result, reported: unquote(field('reported')) || null, severity: field('severity') || null, reason: field('reason') || null });
+  }
+  const gapsSec = (/^## Gaps\s*$([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(text) || [])[1] || '';
+  const gapExtras = new Map();
+  for (const item of gapsSec.split(/^(?=- truth:)/m)) {
+    const n = /^\s+test:\s*(\d+)/m.exec(item);
+    if (!n) continue;
+    const extras = {};
+    for (const k of KEEP_GAP_FIELDS) {
+      const m = new RegExp(`^\\s+${k}:\\s*(.*)$`, 'm').exec(item);
+      if (m && m[1].trim() && m[1].trim() !== '""' && m[1].trim() !== '[]') extras[k] = m[1].trim();
+    }
+    gapExtras.set(Number(n[1]), extras);
+  }
+  return { status, tests, gapExtras };
+}
+
+function renderTest(t) {
+  const lines = [`### ${t.number}. ${t.name}`, `expected: ${t.expected}`, `result: ${t.result === 'pending' ? '[pending]' : t.result}`];
+  if (t.result === 'issue') {
+    lines.push(`reported: ${quote(t.reported)}`);
+    lines.push(`severity: ${t.severity || 'major'}`);
+  }
+  if (t.result === 'skipped' && t.reason) lines.push(`reason: ${t.reason}`);
+  return lines.join('\n');
+}
+
+function summaryOf(tests) {
+  const n = (r) => tests.filter((t) => t.result === r).length;
+  return { total: tests.length, passed: n('pass'), issues: n('issue'), pending: n('pending'), skipped: n('skipped') };
+}
+
+function gapsOf(tests, gapExtras) {
+  return tests.filter((t) => t.result === 'issue').map((t) => ({
+    truth: t.expected, status: 'failed', reason: `User reported: ${t.reported || ''}`.trim(), severity: t.severity || 'major', test: t.number,
+    ...(gapExtras.get(t.number) || {}),
+  }));
+}
+
+function renderGaps(gaps) {
+  return gaps.map((g) => {
+    const lines = [`- truth: ${quote(g.truth)}`, `  status: ${g.status}`, `  reason: ${quote(g.reason)}`, `  severity: ${g.severity}`, `  test: ${g.test}`];
+    for (const k of KEEP_GAP_FIELDS) if (g[k]) lines.push(`  ${k}: ${g[k]}`);
+    return lines.join('\n');
+  }).join('\n');
+}
+
+/** Set one test's result and rebuild the summary and the gaps. */
+function recordUatResult(cwd, phase, input) {
+  const file = uatPath(cwd, phase);
+  if (!file) return { error: 'uat_not_found', reason: `no {phase}-uat.md in phase ${phase} (create one with scaffold uat)` };
+  if (!RESULTS.includes(input.result)) return { error: 'invalid_result', reason: `result is one of ${RESULTS.join(', ')}` };
+  if (input.severity && !SEVERITIES.includes(input.severity)) return { error: 'invalid_severity', reason: `severity is one of ${SEVERITIES.join(', ')}` };
+  const raw = fs.readFileSync(file, 'utf8');
+  const eol = dominantEol(raw);
+  let text = toLf(raw);
+  const u = parseUat(text);
+  const t = u.tests.find((x) => x.number === Number(input.test));
+  if (!t) return { error: 'test_not_found', reason: `uat.md has no test ${input.test}` };
+  t.result = input.result;
+  t.reported = input.result === 'issue' ? (input.reported || t.reported || '') : null;
+  t.severity = input.result === 'issue' ? (input.severity || t.severity || 'major') : null;
+  t.reason = input.result === 'skipped' ? (input.reason || t.reason || null) : null;
+
+  const testsBody = '\n' + u.tests.map(renderTest).join('\n\n') + '\n\n';
+  text = text.replace(/^## Tests\s*$[\s\S]*?(?=^## |(?![\s\S]))/m, `## Tests\n${testsBody}`);
+  const s = summaryOf(u.tests);
+  const summary = `## Summary\n\ntotal: ${s.total}\npassed: ${s.passed}\nissues: ${s.issues}\npending: ${s.pending}\nskipped: ${s.skipped}\n\n`;
+  text = /^## Summary\s*$/m.test(text) ? text.replace(/^## Summary\s*$[\s\S]*?(?=^## |(?![\s\S]))/m, summary) : text + `\n${summary}`;
+  const gaps = gapsOf(u.tests, u.gapExtras);
+  const gapsBlock = `## Gaps\n\n<!-- YAML format for plan-phase --gaps consumption -->\n${gaps.length ? renderGaps(gaps) + '\n' : ''}`;
+  text = /^## Gaps\s*$/m.test(text) ? text.replace(/^## Gaps\s*$[\s\S]*?(?=^## |(?![\s\S]))/m, gapsBlock) : text + `\n${gapsBlock}`;
+  const now = new Date().toISOString();
+  text = text.replace(/^updated:.*$/m, `updated: ${now}`);
+  if (s.pending === 0) text = text.replace(/^status:\s*testing\s*$/m, 'status: complete');
+  fs.writeFileSync(file, withEol(text, eol));
+  return { recorded: true, test: t.number, result: t.result, ...s, complete: s.pending === 0, gaps: gaps.length };
+}
+
+function uatStatus(cwd, phase) {
+  const file = uatPath(cwd, phase);
+  if (!file) return { error: 'uat_not_found', reason: `no {phase}-uat.md in phase ${phase}` };
+  const u = parseUat(fs.readFileSync(file, 'utf8'));
+  const s = summaryOf(u.tests);
+  return { file: path.basename(file), status: u.status, ...s, complete: s.pending === 0, gaps: gapsOf(u.tests, u.gapExtras) };
+}
+
+function cmdUatRecord(cwd, phase, opts, raw) {
+  if (!phase || !opts.test || !opts.result) error('Usage: uat record <phase> --test N --result pass|issue|skipped [--reported "…"] [--severity S] [--reason "…"]');
+  const r = recordUatResult(cwd, phase, opts);
+  if (r.error) { output(r, raw, 'error', 1); return; }
+  output(r, raw, `${r.test}: ${r.result}`);
+}
+
+function cmdUatStatus(cwd, phase, raw) {
+  if (!phase) error('Usage: uat status <phase>');
+  const r = uatStatus(cwd, phase);
+  if (r.error) { output(r, raw, 'error', 1); return; }
+  output(r, raw, `${r.passed} passed, ${r.issues} issues, ${r.pending} pending`);
+}
+
+module.exports = { parseUat, recordUatResult, uatStatus, cmdUatRecord, cmdUatStatus };

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

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

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

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

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

@@ -103,11 +103,11 @@ function cmdPreflight(cwd, target, raw) {
           checks.push({ name: 'batch_exists', passed: true, detail: files[files.length - 1] });
         } else {
           checks.push({ name: 'batch_exists', passed: false, detail: 'no batch file found' });
-          blockers.push('No batch file — run /pan:focus-plan first');
+          blockers.push('No batch file — run /pan:focus-auto --step plan first');
         }
       } catch {
         checks.push({ name: 'batch_exists', passed: false, detail: 'focus/ directory not found' });
-        blockers.push('No focus/ directory — run /pan:focus-scan first');
+        blockers.push('No focus/ directory — run /pan:focus-auto --step scan first');
       }
     } else {
       // target is a phase number — check the phase directory exists

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

@@ -127,6 +127,42 @@ function checkRed(cwd, phase, opts = {}) {
   };
 }
 
+/**
+ * Prove a review finding with a catching test (program R5): the inverse of RED. The
+ * test shows the defect the phase introduced when it PASSES at the phase's base (the
+ * behaviour was right before) and FAILS at HEAD (the phase broke it).
+ *
+ *   confirmed       passes at the base, fails at HEAD
+ *   fails_at_base   fails before the phase too: not specific to the change
+ *   passes_at_head  the defect it claims is not there, or the test does not reach it
+ *   not_checked     no base, no command for the file, or the worktree failed (with why)
+ *
+ * @returns {{status, test, base?, command?, base_exit?, head_exit?, detail?}}
+ */
+function proveFinding(cwd, phase, testFile, opts = {}) {
+  const test = String(testFile || '').split(path.sep).join('/').split('\\').join('/');
+  if (!test || !fs.existsSync(path.join(cwd, test))) return { status: 'not_checked', test, detail: 'the test file does not exist' };
+  const info = findPhaseInternal(cwd, phase);
+  const b = phaseBase(cwd, (info && info.phase_number) || String(phase));
+  if (!b.base) return { status: 'not_checked', test, detail: b.reason };
+  const fc = TG.fileCommand(cwd, test);
+  if (!fc.command) return { status: 'not_checked', test, detail: fc.reason };
+  const timeoutMs = opts.timeoutMs || DEFAULT_FILE_TIMEOUT_MS;
+  let atBase = null;
+  const wt = withWorktree(cwd, b.base, (dir) => {
+    const dest = path.join(dir, test);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(cwd, test), dest);
+    atBase = TG.runCommand(dir, fc.command, timeoutMs);
+  });
+  if (wt.error) return { status: 'not_checked', test, base: b.base, detail: wt.error };
+  const atHead = TG.runCommand(cwd, fc.command, timeoutMs);
+  const status = atBase.exit !== 0 ? 'fails_at_base' : (atHead.exit === 0 ? 'passes_at_head' : 'confirmed');
+  const detail = status === 'fails_at_base' ? `fails before the phase too: ${tail(atBase.output)}`
+    : status === 'passes_at_head' ? 'passes at HEAD: it does not show the defect the finding claims' : null;
+  return { status, test, base: b.base, command: fc.command, base_exit: atBase.exit, head_exit: atHead.exit, ...(detail ? { detail } : {}) };
+}
+
 /** `pan-tools verify red <phase> [--timeout <ms>]`: exit 1 when a test is not_red or not_green. */
 function cmdVerifyRed(cwd, phase, raw, opts = {}) {
   if (!phase) error('Usage: verify red <phase> [--timeout <ms>]');
@@ -135,4 +171,4 @@ function cmdVerifyRed(cwd, phase, raw, opts = {}) {
   output(r, raw, !r.checked ? 'not_checked' : (r.ok ? 'caught' : 'not_caught'), r.ok ? 0 : 1);
 }
 
-module.exports = { checkRed, cmdVerifyRed, phaseBase, withWorktree };
+module.exports = { checkRed, cmdVerifyRed, phaseBase, withWorktree, proveFinding };

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

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

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

@@ -168,6 +168,36 @@ function checkCheckpointTask(type, attrs, body, errors, warnings) {
   return { name: label, type, auto_select: autoMatch ? autoMatch[1] : null };
 }
 
+// The elements a plan nests. A file that ends with one of them still open was cut
+// off: runtimes cap tool output, and a long plan has been truncated mid-tag while
+// the write reported success (market-ideas M47; gsd-core v1.18.0).
+const PLAN_TAGS = ['tasks', 'task', 'name', 'files', 'action', 'verify', 'done'];
+const TRUNCATION_MARKER = /\[\s*\.{0,3}\s*(?:output\s+)?truncated\b|<!--\s*(?:continue|continued|truncated)\b|\(output truncated\)|\bcontinued in next (?:message|write)\b/i;
+
+/**
+ * Signs that a plan file was cut off. Pure; tags inside fenced code blocks do not count.
+ * @param {string} content - plan file content
+ * @returns {string[]} one message per problem, empty when the file is whole
+ */
+function detectPlanTruncation(content) {
+  const text = String(content || '').replace(/\r\n/g, '\n').replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[ \t]*$/gm, '');
+  const out = [];
+  const open = [];
+  const tagRe = new RegExp(`<(/?)(${PLAN_TAGS.join('|')})\\b[^>]*?(/?)>`, 'g');
+  let m;
+  while ((m = tagRe.exec(text)) !== null) {
+    const [, closing, tag, selfClosing] = m;
+    if (selfClosing) continue;
+    if (!closing) { open.push(tag); continue; }
+    const at = open.lastIndexOf(tag);
+    if (at >= 0) open.splice(at);
+  }
+  if (open.length) out.push(`Plan looks truncated: the file ends with ${open.map((t) => `<${t}>`).join(' > ')} still open`);
+  const marker = text.match(TRUNCATION_MARKER);
+  if (marker) out.push(`Plan looks truncated: it contains a continuation marker ("${marker[0].trim()}")`);
+  return out;
+}
+
 /**
  * Validate a plan.md structure: required frontmatter, task elements, and consistency.
  * @param {string} cwd - Working directory path
@@ -180,11 +210,19 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
   const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
   const content = safeReadFile(fullPath);
   if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const r = planStructure(content);
+  output(r, raw, r.valid ? 'valid' : 'invalid');
+}
 
+/** A plan's structure check (cmdVerifyPlanStructure without the output). Pure. */
+function planStructure(content) {
   const fm = extractFrontmatter(content);
   const errors = [];
   const warnings = [];
 
+  // A cut-off plan first: its task count and fields would mislead (M47).
+  errors.push(...detectPlanTruncation(content));
+
   // Check required frontmatter fields
   const required = ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'];
   for (const field of required) {
@@ -246,14 +284,14 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     errors.push('Has checkpoint tasks but autonomous is not false');
   }
 
-  output({
+  return {
     valid: errors.length === 0,
     errors,
     warnings,
     task_count: tasks.length,
     tasks,
     frontmatter_fields: Object.keys(fm),
-  }, raw, errors.length === 0 ? 'valid' : 'invalid');
+  };
 }
 
 /**
@@ -584,6 +622,16 @@ function reconcilePhase(cwd, phaseNum) {
       contradictions.push(`verification status "${status}" but the engine's test run failed${why}`);
     }
   }
+  // V5G: in gate mode, a mutation score below the floor means the tests do not pin the
+  // code, so a passed verification is a contradiction until they do.
+  const mutFile = files.find((f) => /-mutation\.json$/.test(f));
+  if (claimsPass && mutFile) {
+    let mut = null;
+    try { mut = JSON.parse(safeReadFile(path.join(dir, mutFile)) || 'null'); } catch {}
+    if (mut && mut.mode === 'gate' && mut.gate && mut.gate.failed) {
+      contradictions.push(`verification status "${status}" but the mutation score ${mut.score} is below the floor ${mut.gate.floor} (workflow.mutation_gate: gate): ${mut.survived} of ${mut.sampled} mutants survived`);
+    }
+  }
   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,
@@ -1473,9 +1521,13 @@ function cmdValidateHealth(cwd, options, raw) {
   }
 
   // Perform repairs if requested and there are repairable issues
+  // L6a: health asks per repair class. Without --repair the result lists the classes;
+  // --only limits a repair to the ones the user chose.
+  const only = Array.isArray(options.only) && options.only.length ? new Set(options.only) : null;
+  const chosen = only ? repairs.filter((r) => only.has(r)) : repairs;
   let repairActions = [];
-  if (options.repair && repairs.length > 0) {
-    repairActions = repairIssues(cwd, repairs);
+  if (options.repair && chosen.length > 0) {
+    repairActions = repairIssues(cwd, chosen);
   }
 
   // Check 10 (optional): full validation — run tests and build
@@ -1548,6 +1600,7 @@ function cmdValidateHealth(cwd, options, raw) {
     warnings,
     info,
     repairable_count: repairableCount,
+    repairs_available: repairs.length > 0 ? [...new Set(repairs)] : undefined,
     repairs_performed: repairActions.length > 0 ? repairActions : undefined,
   };
   if (options.full) {
@@ -1623,8 +1676,10 @@ function runFullBuildCheck(cwd) {
 // ─── Deployment validation — extracted to verify-deploy.cjs (re-exported below)
 
 module.exports = {
+  planStructure,
   cmdVerifySummary,
   cmdVerifyPlanStructure,
+  detectPlanTruncation,
   cmdVerifyPhaseCompleteness,
   cmdVerifyReferences,
   cmdVerifyCommits,

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

@@ -208,7 +208,77 @@ function cmdWorktreeCleanup(cwd, raw, opts) {
   output(r, raw, lines.length ? lines.join('\n') : 'nothing to clean');
 }
 
+// ─── Shadow-merge preflight (program A3) ────────────────────────────────────
+// Branches that each pass the oracle can still break it together. Before merging a
+// sub-wave back, merge every branch onto the base in a throwaway worktree, in order,
+// and run the test command there. A conflict is named; a red result is bisected to
+// "each passes alone" (break_together) or the branches that fail on their own.
+
+const GIT_IDENTITY = ['-c', 'user.name=PAN preflight', '-c', 'user.email=preflight@pan.local', '-c', 'commit.gpgsign=false'];
+
+function runOracle(dir, test) {
+  const { spawnSync } = require('child_process');
+  const r = spawnSync(test, { cwd: dir, shell: true, encoding: 'utf8', timeout: 20 * 60 * 1000 });
+  return r.status === 0;
+}
+
+/**
+ * @param {string} cwd
+ * @param {{base?: string, branches: string[], test?: string}} opts
+ * @returns {{ok: boolean, verdict: 'clean'|'conflict'|'break_together'|'branch_fails'|'base_failing'|'no_test', ...}}
+ */
+function shadowMergePreflight(cwd, opts = {}) {
+  if (!isGitRepo(cwd)) return { error: 'not_git', reason: 'the preflight needs a git repository' };
+  const base = opts.base || 'HEAD';
+  const branches = (opts.branches || []).filter(Boolean);
+  let test = opts.test;
+  if (!test) {
+    try { test = require('./test-gate.cjs').detectTestCommand(cwd).command; } catch { test = null; }
+  }
+  if (!test) return { ok: false, verdict: 'no_test', base, branches, reason: 'no test command: pass --test or set one for the project' };
+  const os = require('os');
+  const fsx = require('fs');
+  const dir = fsx.mkdtempSync(path.join(os.tmpdir(), 'pan-preflight-'));
+  fsx.rmSync(dir, { recursive: true, force: true });
+  const add = execGit(cwd, ['worktree', 'add', '--detach', dir, base]);
+  if (add.exitCode !== 0) return { error: 'worktree_failed', reason: add.stderr.trim() };
+  const g = (args) => execGit(dir, [...GIT_IDENTITY, ...args]);
+  const result = { base, branches, test, merged: [], alone: {} };
+  try {
+    if (!runOracle(dir, test)) return { ...result, ok: false, verdict: 'base_failing', reason: 'the oracle already fails on the base: a merge cannot be judged' };
+    for (const b of branches) {
+      const m = g(['merge', '--no-ff', '--no-edit', b]);
+      if (m.exitCode !== 0) {
+        const files = g(['diff', '--name-only', '--diff-filter=U']).stdout.split('\n').map((x) => x.trim()).filter(Boolean);
+        g(['merge', '--abort']);
+        return { ...result, ok: false, verdict: 'conflict', conflict: { branch: b, files, after: [...result.merged] } };
+      }
+      result.merged.push(b);
+    }
+    if (runOracle(dir, test)) return { ...result, ok: true, verdict: 'clean' };
+    for (const b of branches) {
+      g(['reset', '--hard', '-q', base]);
+      result.alone[b] = g(['merge', '--no-ff', '--no-edit', b]).exitCode === 0 && runOracle(dir, test);
+    }
+    const failing = branches.filter((b) => !result.alone[b]);
+    return failing.length
+      ? { ...result, ok: false, verdict: 'branch_fails', failing }
+      : { ...result, ok: false, verdict: 'break_together', reason: 'each branch passes alone; merged together they fail' };
+  } finally {
+    execGit(cwd, ['worktree', 'remove', '--force', dir]);
+    try { fsx.rmSync(dir, { recursive: true, force: true }); } catch {}
+    execGit(cwd, ['worktree', 'prune']);
+  }
+}
+
+function cmdWorktreePreflight(cwd, opts, raw) {
+  const r = shadowMergePreflight(cwd, opts);
+  output(r, raw, r.verdict || r.error);
+}
+
 module.exports = {
+  shadowMergePreflight,
+  cmdWorktreePreflight,
   ARMY_BRANCH_PREFIX,
   createTaskWorktree,
   removeTaskWorktree,