pan-wizard 3.21.1 → 3.24.0

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

@@ -195,11 +195,16 @@ function cmdStateUpdate(cwd, field, value) {
       writeStateMd(statePath, content, cwd);
       output({ updated: true });
     } else {
-      output({ updated: false, reason: `Field "${field}" not found in state.md` });
+      // error key ⇒ exit 1: the caller asked for a field update that did not
+      // happen, so state.md does not say what the caller now believes it says.
+      output({ updated: false, reason: `Field "${field}" not found in state.md`, error: 'field_not_found' });
     }
   } catch {
     // state.md does not exist or is unreadable -- report gracefully
-    output({ updated: false, reason: 'state.md not found' });
+    // Same condition `state json` reports as {error:'state.md not found'} at exit 1.
+    // Reporting it as a bare `updated: false` was the identical defect wearing a
+    // different key — one file, one missing file, two exit codes.
+    output({ updated: false, reason: 'state.md not found', error: 'state_not_found' });
   }
 }
 
@@ -256,6 +261,9 @@ function cmdStateAdvancePlan(cwd, raw) {
     content = stateReplaceField(content, 'Status', 'Phase complete — ready for verification') || content;
     content = stateReplaceField(content, 'Last Activity', today) || content;
     writeStateMd(statePath, content, cwd);
+    // No error key, exit 0: `last_plan` is the NORMAL end-of-phase signal — the
+    // phase advanced to "ready for verification" and state.md was written. Gating on
+    // it would make every completed phase look like a failure.
     output({ advanced: false, reason: 'last_plan', current_plan: currentPlan, total_plans: totalPlans, status: 'ready_for_verification' }, raw, 'false');
   } else {
     const newPlan = currentPlan + 1;
@@ -303,7 +311,7 @@ function cmdStateRecordMetric(cwd, options, raw) {
     writeStateMd(statePath, content, cwd);
     output({ recorded: true, phase, plan, duration }, raw, 'true');
   } else {
-    output({ recorded: false, reason: 'Performance Metrics section not found in state.md' }, raw, 'false');
+    output({ recorded: false, reason: 'Performance Metrics section not found in state.md', error: 'metrics_section_missing' }, raw, 'false');
   }
 }
 
@@ -345,7 +353,7 @@ function cmdStateUpdateProgress(cwd, raw) {
     writeStateMd(statePath, content, cwd);
     output({ updated: true, percent, completed: totalSummaries, total: totalPlans, bar: progressStr }, raw, progressStr);
   } else {
-    output({ updated: false, reason: 'Progress field not found in state.md' }, raw, 'false');
+    output({ updated: false, reason: 'Progress field not found in state.md', error: 'progress_field_missing' }, raw, 'false');
   }
 }
 
@@ -369,7 +377,7 @@ function cmdStateAddDecision(cwd, options, raw) {
     summaryText = readTextArgOrFile(cwd, summary, summary_file, 'summary');
     rationaleText = readTextArgOrFile(cwd, rationale || '', rationale_file, 'rationale');
   } catch (err) {
-    output({ added: false, reason: err.message }, raw, 'false');
+    output({ added: false, reason: err.message, error: err.message || 'decision_read_failed' }, raw, 'false');
     return;
   }
 
@@ -389,7 +397,7 @@ function cmdStateAddDecision(cwd, options, raw) {
     writeStateMd(statePath, content, cwd);
     output({ added: true, decision: entry }, raw, 'true');
   } else {
-    output({ added: false, reason: 'Decisions section not found in state.md' }, raw, 'false');
+    output({ added: false, reason: 'Decisions section not found in state.md', error: 'decisions_section_missing' }, raw, 'false');
   }
 }
 
@@ -410,7 +418,7 @@ function cmdStateAddBlocker(cwd, text, raw) {
   try {
     blockerText = readTextArgOrFile(cwd, blockerOptions.text, blockerOptions.text_file, 'blocker');
   } catch (err) {
-    output({ added: false, reason: err.message }, raw, 'false');
+    output({ added: false, reason: err.message, error: err.message || 'blocker_read_failed' }, raw, 'false');
     return;
   }
 
@@ -428,7 +436,7 @@ function cmdStateAddBlocker(cwd, text, raw) {
     writeStateMd(statePath, content, cwd);
     output({ added: true, blocker: blockerText }, raw, 'true');
   } else {
-    output({ added: false, reason: 'Blockers section not found in state.md' }, raw, 'false');
+    output({ added: false, reason: 'Blockers section not found in state.md', error: 'blockers_section_missing' }, raw, 'false');
   }
 }
 
@@ -456,6 +464,17 @@ function cmdStateResolveBlocker(cwd, text, raw) {
       return !line.toLowerCase().includes(text.toLowerCase());
     });
 
+    // M27: if nothing was removed, no blocker matched the given text. Report
+    // resolved:false rather than falsely claiming a resolution (and skip the
+    // write entirely — the file is unchanged).
+    if (filtered.length === lines.length) {
+      // error key ⇒ exit 1. M27 stopped this from falsely claiming a resolution;
+      // the exit code finishes the job. The blocker is STILL OPEN and the caller
+      // that asked to clear it would otherwise carry on believing it is gone.
+      output({ resolved: false, reason: 'no matching blocker', blocker: text, error: 'blocker_not_matched' }, raw, 'false');
+      return;
+    }
+
     let newBody = filtered.join('\n');
     // If section is now empty, add placeholder
     if (!newBody.trim() || !newBody.includes('- ')) {
@@ -466,7 +485,7 @@ function cmdStateResolveBlocker(cwd, text, raw) {
     writeStateMd(statePath, content, cwd);
     output({ resolved: true, blocker: text }, raw, 'true');
   } else {
-    output({ resolved: false, reason: 'Blockers section not found in state.md' }, raw, 'false');
+    output({ resolved: false, reason: 'Blockers section not found in state.md', error: 'blockers_section_missing' }, raw, 'false');
   }
 }
 
@@ -510,7 +529,7 @@ function cmdStateRecordSession(cwd, options, raw) {
     try { require('./memory-optimize.cjs').maybeAutoOptimizeMemory(cwd); } catch { /* best-effort */ }
     output({ recorded: true, updated }, raw, 'true');
   } else {
-    output({ recorded: false, reason: 'No session fields found in state.md' }, raw, 'false');
+    output({ recorded: false, reason: 'No session fields found in state.md', error: 'session_fields_missing' }, raw, 'false');
   }
 }
 
@@ -1012,7 +1031,9 @@ function cmdDashboard(cwd, raw) {
     lines.push(`Blockers: ${blockerCount}`);
     if (lastActivity) lines.push(`Last Activity: ${lastActivity}${lastActivityDesc ? ' — ' + lastActivityDesc : ''}`);
     if (nextPhase) lines.push(`Next Phase: ${nextPhase.number} — ${nextPhase.name}`);
-    output(result, false, lines.join('\n'));
+    // raw=true so output() emits the human summary; passing false discarded it
+    // and printed JSON, making the whole lines[] block dead (M28, ADR audit 2026-08).
+    output(result, true, lines.join('\n'));
     return;
   }
 

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

@@ -9,7 +9,7 @@ const {
   SIMPLE_TASK_THRESHOLD, SIMPLE_FILE_THRESHOLD, COMPLEX_TASK_THRESHOLD, COMPLEX_FILE_THRESHOLD,
 } = require('./constants.cjs');
 const { planningPath, phasesPath } = require('./utils.cjs');
-const { normalizePhaseName, findPhaseInternal, generateSlugInternal, toPosix, output, error } = require('./core.cjs');
+const { normalizePhaseName, findPhaseInternal, generateSlugInternal, toPosix, output, EXIT_OK, error } = require('./core.cjs');
 const { reconstructFrontmatter } = require('./frontmatter.cjs');
 
 /**
@@ -64,8 +64,13 @@ function cmdTemplateSelect(cwd, planPath, raw) {
     const result = { template, type, taskCount, fileCount, hasDecisions };
     output(result, raw, template);
   } catch (err) {
-    // Fallback to standard template on any read/parse error
-    output({ template: 'templates/summary-standard.md', type: 'standard', error: err.message }, raw, 'templates/summary-standard.md');
+    // Fallback to standard template on any read/parse error.
+    // EXIT_OK: this is a RESULT, not a failure — the command answered the question
+    // it was asked ("which summary template?") with the documented default, and
+    // `error` here is only the reason detection fell back. Callers use it as
+    // `TEMPLATE=$(pan-tools template select … --raw)`; exiting non-zero would
+    // report a failure for a command that produced a usable answer.
+    output({ template: 'templates/summary-standard.md', type: 'standard', error: err.message }, raw, 'templates/summary-standard.md', EXIT_OK);
   }
 }
 

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

@@ -90,8 +90,20 @@ function validateRuntimeInstall(cwd, configDir, runtime) {
     if (hooks && typeof hooks === 'object') {
       for (const hookArr of Object.values(hooks)) {
         if (!Array.isArray(hookArr)) continue;
-        for (const hook of hookArr) {
-          if (hook.command) hookCommands.push(hook.command);
+        // M29: PAN installs hooks in the nested Claude shape — each event maps to
+        // an array of GROUPS, and each group holds the real commands under
+        // group.hooks[]: { matcher, hooks: [{ type, command }] }. The old code
+        // only read group.command (undefined in that shape), so it validated
+        // nothing for PAN's own hooks. Collect both the flat group.command (other
+        // runtimes) AND every command nested in group.hooks[].
+        for (const group of hookArr) {
+          if (!group || typeof group !== 'object') continue;
+          if (group.command) hookCommands.push(group.command);
+          if (Array.isArray(group.hooks)) {
+            for (const h of group.hooks) {
+              if (h && h.command) hookCommands.push(h.command);
+            }
+          }
         }
       }
     }

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

@@ -135,7 +135,7 @@ function calculateDriftScore(violations, filesChecked, rulesCount) {
  * @param {string} [sinceRef] - Git ref to diff against (default: HEAD)
  * @returns {string[]} Array of relative file paths
  */
-function getChangedFiles(cwd, sinceRef) {
+function getChangedFiles(cwd, sinceRef, opts = {}) {
   const ref = sinceRef || 'HEAD';
   // Try staged + unstaged first, then diff against ref
   const result = execGit(cwd, ['diff', '--name-only', ref]);
@@ -150,6 +150,20 @@ function getChangedFiles(cwd, sinceRef) {
       if (line.trim()) allFiles.add(line.trim());
     }
   }
+  // Untracked files are OPT-IN because the two consumers want different things.
+  // Drift detection asks "what changed against the baseline", where an untracked
+  // scratch file is noise. The stub gate asks "is any code in this handoff a stub",
+  // and a brand-new file is precisely the normal shape of PAN execution — a plan
+  // creates files, a later step commits them — so during that window `git diff` lists
+  // nothing and a fully stubbed new module sailed through the gate.
+  if (opts.includeUntracked) {
+    const untracked = execGit(cwd, ['ls-files', '--others', '--exclude-standard']);
+    if (untracked.exitCode === 0) {
+      for (const line of untracked.stdout.split(/\r?\n/)) {
+        if (line.trim()) allFiles.add(line.trim());
+      }
+    }
+  }
   // Filter out binary extensions and limit
   const filtered = [];
   for (const f of allFiles) {

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

@@ -6,7 +6,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, execGit, findPhaseInternal, output } = require('./core.cjs');
+const { safeReadFile, execGit, findPhaseInternal, output, normalizePhaseName } = require('./core.cjs');
 const { readStateSafe } = require('./state.cjs');
 const {
   STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PATTERNS_FILE, PHASE_DIR_RE,
@@ -162,7 +162,13 @@ function cmdDepsValidate(cwd, raw) {
     const headerRe = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
     let match;
     while ((match = headerRe.exec(roadmapContent)) !== null) {
-      roadmapPhases.set(match[1], match[2].trim());
+      // Key both maps by the NORMALIZED number. Roadmap headings are unpadded
+      // ("Phase 1") and directory names are zero-padded ("01-foundation"), so
+      // keying on the raw values made every phase mismatch in BOTH directions:
+      // `deps validate` reported "in roadmap but no directory on disk" for phases
+      // whose directory was right there, plus an "orphaned directory" warning for
+      // the same phase — inventing errors on a roadmap in PAN's own template shape.
+      roadmapPhases.set(normalizePhaseName(match[1]), match[2].trim());
     }
   } else {
     issues.push({ type: 'warning', message: 'roadmap.md not found' });
@@ -176,7 +182,7 @@ function cmdDepsValidate(cwd, raw) {
       if (entry.isDirectory()) {
         const dirMatch = entry.name.match(PHASE_DIR_RE);
         if (dirMatch) {
-          diskPhases.set(dirMatch[1], entry.name);
+          diskPhases.set(normalizePhaseName(dirMatch[1]), entry.name);
         }
       }
     }

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, error, escapeRegex } = require('./core.cjs');
+const { safeReadFile, normalizePhaseName, comparePhaseNum, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, EXIT_OK, error, escapeRegex } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
 const {
@@ -362,7 +362,17 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
   if (!content) { output({ error: 'File not found', path: planFilePath }, raw); return; }
   const r = checkArtifacts(cwd, content);
   if (r.total === 0) {
-    output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw);
+    // EXIT_OK: "nothing declared to check" is a RESULT, not a failure. Two pieces of
+    // shipped evidence: (1) the plan template ships `must_haves: { truths: [],
+    // artifacts: [], key_links: [] }` (pan-wizard-core/templates/phase-prompt.md,
+    // template.cjs generatePlanTemplate), so an empty block is the documented default
+    // state of a scaffolded plan; presence of the block is enforced by
+    // `verify plan-structure`, not here. (2) parseMustHavesBlock currently matches the
+    // block header at 4-space indent while every shipped template and agent emits it at
+    // 2 — so this branch is reached for *every* plan authored in PAN's own format, and
+    // exiting non-zero would fail every real `verify artifacts` call. Reclassifying
+    // this as a failure requires fixing that indentation mismatch first.
+    output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw, undefined, EXIT_OK);
     return;
   }
   output(r, raw, r.all_passed ? 'valid' : 'invalid');
@@ -425,7 +435,10 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
   if (!content) { output({ error: 'File not found', path: planFilePath }, raw); return; }
   const r = checkKeyLinks(cwd, content);
   if (r.total === 0) {
-    output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw);
+    // EXIT_OK: same reasoning as cmdVerifyArtifacts above — an empty key_links block is
+    // the shipped template default, and the parseMustHavesBlock indent mismatch means
+    // this branch fires for every plan written in PAN's own format.
+    output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw, undefined, EXIT_OK);
     return;
   }
   output(r, raw, r.all_verified ? 'valid' : 'invalid');
@@ -490,8 +503,11 @@ function reconcilePhase(cwd, phaseNum) {
 function cmdVerifyReconcile(cwd, phaseNum, raw) {
   if (!phaseNum) { error('Usage: verify reconcile <phase>'); }
   const r = reconcilePhase(cwd, phaseNum);
-  output(r, raw, r.reconciled ? 'valid' : 'invalid');
-  process.exit(r.reconciled ? 0 : 1);
+  // Exit non-zero on contradiction so exec-phase's auto-advance gate actually
+  // stops on a rubber-stamped verification. output() previously hard-coded
+  // exit 0, making the old trailing process.exit dead code (H3, ADR audit
+  // 2026-08); the exitCode arg restores the gate.
+  output(r, raw, r.reconciled ? 'valid' : 'invalid', r.reconciled ? 0 : 1);
 }
 
 // ─── Stub / fake-return scanner (ADR-0036 review — closes the hardcoded
@@ -516,7 +532,9 @@ const STUB_CODE_EXT = /\.(js|cjs|mjs|jsx|ts|tsx|py|go|rb|java|php|rs|c|cc|cpp|h|
  * @returns {{scanned, findings: Array, blocking: number, total: number}}
  */
 function scanStubs(cwd, opts = {}) {
-  let files = Array.isArray(opts.files) ? opts.files : getChangedFiles(cwd);
+  // includeUntracked: a stub gate that cannot see new files is not a gate. See the
+  // note in verify-drift.cjs getChangedFiles for why drift does not want the same.
+  let files = Array.isArray(opts.files) ? opts.files : getChangedFiles(cwd, null, { includeUntracked: true });
   files = (files || []).filter(f => STUB_CODE_EXT.test(f));
   const findings = [];
   for (const rel of files) {
@@ -538,8 +556,9 @@ function scanStubs(cwd, opts = {}) {
 
 function cmdVerifyStubs(cwd, opts = {}, raw) {
   const r = scanStubs(cwd, opts);
-  output(r, raw, r.blocking === 0 ? 'valid' : 'invalid');
-  if (opts.gate) process.exit(r.blocking > 0 ? 1 : 0);
+  // --gate must exit non-zero on blocking findings; output() used to hard-exit 0
+  // before the gate check, so the gate was dead (M30, ADR audit 2026-08).
+  output(r, raw, r.blocking === 0 ? 'valid' : 'invalid', opts.gate ? (r.blocking > 0 ? 1 : 0) : 0);
 }
 
 /**
@@ -757,8 +776,17 @@ function checkStateFile(cwd, addIssue, repairs) {
   if (stateContent === null) {
     // skip further state checks
   } else {
-    // Extract phase references (e.g. "Phase 3" or "phase 01") from state.md
-    const phaseRefs = [...stateContent.matchAll(/[Pp]hase\s+(\d+(?:\.\d+)*)/g)].map(match => match[1]);
+    // Extract phase references (e.g. "Phase 3" or "phase 01") from state.md,
+    // deduped by normalized phase number. A real state.md mentions the same phase
+    // several times -- a total, a progress line, a decisions note -- and one missing
+    // directory must produce one warning, not one per mention. Keying on the
+    // normalized form collapses "Phase 3" and "Phase 03"; the first spelling seen
+    // is kept so the message quotes what the file actually says.
+    const phaseRefs = new Map();
+    for (const match of stateContent.matchAll(/[Pp]hase\s+(\d+(?:\.\d+)*)/g)) {
+      const key = normalizePhaseName(match[1]);
+      if (!phaseRefs.has(key)) phaseRefs.set(key, match[1]);
+    }
     // Get disk phases for cross-reference
     const diskPhases = new Set();
     try {
@@ -773,7 +801,7 @@ function checkStateFile(cwd, addIssue, repairs) {
       // phases/ directory may not exist yet
     }
     // Check for invalid references -- only warn if there are phases on disk
-    for (const ref of phaseRefs) {
+    for (const ref of phaseRefs.values()) {
       const normalizedRef = String(parseInt(ref, 10)).padStart(2, '0');
       if (!diskPhases.has(ref) && !diskPhases.has(normalizedRef) && !diskPhases.has(String(parseInt(ref, 10)))) {
         if (diskPhases.size > 0) {
@@ -866,10 +894,28 @@ function crossCheckRoadmapDisk(cwd, phasesDirPath, addIssue) {
     }
   } catch { /* phases/ may not exist yet */ }
 
+  // A roadmap phase ahead of the current position has simply not been planned yet.
+  // PAN's own workflow creates the condition: /pan:new-project writes a roadmap
+  // declaring every phase up front, and /pan:plan-phase creates directories one at a
+  // time -- so warning on those would make `degraded` the permanent state of every
+  // multi-phase project and drain the verdict of signal. Only a phase at or behind
+  // the current position is genuinely suspect. With no readable current phase we
+  // cannot tell ahead from behind, so fall back to warning on everything.
+  let currentPhase = null;
+  try {
+    const stateContent = fs.readFileSync(path.join(planningPath(cwd), STATE_FILE), 'utf-8');
+    const m = stateContent.match(/\*\*Current Phase:\*\*\s*(\d+[A-Z]?(?:\.\d+)*)/i);
+    if (m) currentPhase = m[1];
+  } catch { /* no state.md -- checkStateFile reports that; stay conservative here */ }
+
   for (const p of roadmapPhases) {
     const padded = String(parseInt(p, 10)).padStart(2, '0');
-    if (!diskPhases.has(p) && !diskPhases.has(padded))
+    if (diskPhases.has(p) || diskPhases.has(padded)) continue;
+    if (currentPhase !== null && comparePhaseNum(p, currentPhase) > 0) {
+      addIssue('info', 'I002', `Phase ${p} in ${ROADMAP_FILE} is not planned yet (current phase: ${currentPhase})`, `Run /pan:plan-phase ${p} when you reach it`);
+    } else {
       addIssue('warning', 'W006', `Phase ${p} in ${ROADMAP_FILE} but no directory on disk`, 'Create phase directory or remove from roadmap');
+    }
   }
   for (const p of diskPhases) {
     const unpadded = String(parseInt(p, 10));
@@ -919,17 +965,13 @@ function repairIssues(cwd, repairs) {
       switch (repair) {
         case 'createConfig':
         case 'resetConfig': {
-          // Write a fresh config.json with sensible defaults
-          const defaults = {
-            model_profile: 'balanced',
-            commit_docs: true,
-            search_gitignored: false,
-            branching_strategy: 'none',
-            research: true,
-            plan_checker: true,
-            verifier: true,
-            parallelization: true,
-          };
+          // Write the canonical NESTED config via buildConfigDefaults. The old
+          // flat literal (research/plan_checker/verifier at top level) did NOT
+          // match the schema the gate reads (config.workflow.verifier), so
+          // --repair silently disabled the verification gate (M31, ADR audit
+          // 2026-08; note the flat form also drifted plan_checker vs plan_check).
+          const { buildConfigDefaults } = require('./config.cjs');
+          const defaults = buildConfigDefaults(false, {});
           fs.writeFileSync(configFullPath, JSON.stringify(defaults, null, 2), 'utf-8');
           repairActions.push({ action: repair, success: true, path: CONFIG_FILE });
           break;
@@ -970,7 +1012,7 @@ function repairIssues(cwd, repairs) {
       }
     } catch (err) {
       // Repair action failed -- record the error so callers can report it
-      repairActions.push({ action: repair, success: false, error: err.message });
+      repairActions.push({ action: repair, success: false, error: err.message || 'repair_failed' });
     }
   }
 
@@ -1111,7 +1153,7 @@ function syncRequirementCheckboxes(cwd) {
   }
 
   if (fixed > 0) {
-    try { fs.writeFileSync(reqPath, reqContent, 'utf-8'); } catch (e) { return { fixed: 0, error: e.message }; }
+    try { fs.writeFileSync(reqPath, reqContent, 'utf-8'); } catch (e) { return { fixed: 0, error: e.message || 'requirements_write_failed' }; }
   }
   return { fixed };
 }
@@ -1161,7 +1203,7 @@ function syncRoadmapPlanCheckboxes(cwd) {
   }
 
   if (fixed > 0) {
-    try { fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); } catch (e) { return { fixed: 0, error: e.message }; }
+    try { fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); } catch (e) { return { fixed: 0, error: e.message || 'roadmap_write_failed' }; }
   }
   return { fixed };
 }
@@ -1308,19 +1350,6 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   }
 
-  // Determine overall status from error/warning counts
-  let status;
-  if (errors.length > 0) {
-    status = HEALTH_STATUS.BROKEN;
-  } else if (warnings.length > 0) {
-    status = HEALTH_STATUS.DEGRADED;
-  } else {
-    status = HEALTH_STATUS.HEALTHY;
-  }
-
-  const repairableCount = errors.filter(e => e.repairable).length +
-                         warnings.filter(w => w.repairable).length;
-
   // Check 11 (optional): drift analysis
   let driftResult;
   if (options.drift) {
@@ -1352,6 +1381,22 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   }
 
+  // Determine overall status from error/warning counts. This must run after every
+  // check that can call addIssue -- computing it earlier left DRIFT_HIGH and
+  // LINKS_ERR sitting in `warnings` while the verdict still read `healthy`, which
+  // contradicts the documented behaviour of --links ("errors degrade health").
+  let status;
+  if (errors.length > 0) {
+    status = HEALTH_STATUS.BROKEN;
+  } else if (warnings.length > 0) {
+    status = HEALTH_STATUS.DEGRADED;
+  } else {
+    status = HEALTH_STATUS.HEALTHY;
+  }
+
+  const repairableCount = errors.filter(e => e.repairable).length +
+                         warnings.filter(w => w.repairable).length;
+
   const result = {
     status,
     errors,

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

@@ -79,7 +79,7 @@ function buildCounterfactualContext(cwd, phaseNum, scenario) {
 
   return {
     phase: String(phaseNum),
-    phase_name: phaseInfo.name || null,
+    phase_name: phaseInfo.phase_name || null,
     directory: toPosix(phaseInfo.directory),
     scenario,
     slug: scenarioSlug(scenario),
@@ -256,6 +256,13 @@ function cmdWhatifPrepare(cwd, phaseNum, scenario, raw) {
   const ctx = buildCounterfactualContext(cwd, phaseNum, scenario);
   if (ctx.error) { output(ctx, raw); return; }
   const wt = createWorktree(cwd, phaseNum, scenario);
+  // `worktree_error` (not `error`) because the payload also carries the context that
+  // WAS resolved, and `error` would read as "the context failed". It is still an
+  // error-family key, so output() derives exit 1 from it exactly as it does for the
+  // `ctx.error` guard one line above — which is the point: the two adjacent failures
+  // of the same command must not report different exit codes just because one of
+  // them renamed the key. Callers cannot proceed either way: what-if stage 2 spawns
+  // an agent INTO worktree_path, and there is no worktree.
   if (wt.error) { output({ ...ctx, worktree_error: wt.error }, raw); return; }
   output({ ...ctx, worktree: wt }, raw);
 }