pan-wizard 3.22.0 → 3.25.0

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

@@ -41,11 +41,19 @@ function cmdPhasesList(cwd, options, raw) {
     // Get all phase directories
     let dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name);
 
-    // Include archived phases if requested
+    // Include archived phases if requested. Archived entries are DECORATED
+    // display strings ("<name> [<milestone>]") that do not exist under
+    // phasesDir — their real location is getArchivedPhaseDirs()'s fullPath
+    // (under .planning/milestones/). M24: track that real path so a later
+    // --type read opens the archive dir instead of crashing with ENOENT on the
+    // decorated name joined to phasesDir.
+    const archivedPaths = new Map();
     if (includeArchived) {
       const archived = getArchivedPhaseDirs(cwd);
       for (const arch of archived) {
-        dirs.push(`${arch.name} [${arch.milestone}]`);
+        const decorated = `${arch.name} [${arch.milestone}]`;
+        dirs.push(decorated);
+        archivedPaths.set(decorated, arch.fullPath);
       }
     }
 
@@ -67,7 +75,7 @@ function cmdPhasesList(cwd, options, raw) {
     if (type) {
       const files = [];
       for (const dir of dirs) {
-        const dirPath = path.join(phasesDir, dir);
+        const dirPath = archivedPaths.get(dir) || path.join(phasesDir, dir);
         const dirFiles = fs.readdirSync(dirPath);
 
         let filtered;
@@ -347,6 +355,32 @@ function buildPlanIndex(phaseDir, planFiles, summaryFiles) {
   return { plans, waves, incomplete, hasCheckpoints };
 }
 
+/**
+ * Add a `- [ ] **Phase N: name**` entry to the roadmap's checklist, after the last
+ * existing entry.
+ *
+ * Returns the content unchanged when the roadmap has no checklist at all — some
+ * roadmaps only carry detail sections, and inventing a list there would be a bigger
+ * surprise than omitting one entry. Format matches templates/roadmap.md exactly, so
+ * the entry is picked up by the same parsers that read the template's own output.
+ *
+ * @param {string} content - Full roadmap.md content
+ * @param {string|number} phaseNum - Phase number as it should appear
+ * @param {string} name - Phase name/description
+ * @returns {string} Updated content
+ */
+function appendPhaseChecklistEntry(content, phaseNum, name) {
+  const lines = content.split('\n');
+  const isChecklistLine = (l) => /^\s*- \[[ x]\]\s*(?:\*\*)?Phase\s+\d/i.test(l);
+  let lastIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (isChecklistLine(lines[i])) lastIdx = i;
+  }
+  if (lastIdx === -1) return content; // no checklist to extend
+  lines.splice(lastIdx + 1, 0, `- [ ] **Phase ${phaseNum}: ${name}**`);
+  return lines.join('\n');
+}
+
 /**
  * Append a new phase to the end of the roadmap and create its directory.
  * @param {string} cwd - Working directory path
@@ -402,6 +436,13 @@ function cmdPhaseAdd(cwd, description, raw) {
     updatedContent = content + phaseEntry;
   }
 
+  // Also add the checklist entry. Only the detail section was written before, so a
+  // phase created by `phase add` was permanently absent from the roadmap's "## Phases"
+  // list — the surface users read, and the one preview/progress consumers parse. Worse,
+  // `phase complete` then reported roadmap_updated:true having changed nothing, because
+  // it ticks a checklist line that was never there.
+  updatedContent = appendPhaseChecklistEntry(updatedContent, newPhaseNum, description);
+
   try {
     fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
   } catch (e) {
@@ -501,7 +542,10 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
     insertIdx = content.length;
   }
 
-  const updatedContent = content.slice(0, insertIdx) + phaseEntry + content.slice(insertIdx);
+  // Insert the detail section, then the matching checklist entry — same reason as
+  // cmdPhaseAdd: without it the inserted phase never appears in the "## Phases" list.
+  const withEntry = content.slice(0, insertIdx) + phaseEntry + content.slice(insertIdx);
+  const updatedContent = appendPhaseChecklistEntry(withEntry, decimalPhase, description);
   try {
     fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
   } catch (e) {
@@ -542,20 +586,33 @@ function markPhaseCompleteInRoadmap(cwd, phaseNum, _phaseName, planCount, summar
   try {
     roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
   } catch {
-    return;
+    return { roadmap_warning: `${ROADMAP_FILE} unreadable — phase completion was not recorded in the roadmap` };
   }
 
+  // Match the phase number the way the roadmap spells it, not the way the
+  // caller spelled it. Callers pass "01" (the dir/state spelling) as often as
+  // "1", while the template checklist says "Phase 1:" — matching on the raw
+  // argument made the tick a silent no-op for padded calls: state advanced,
+  // checkbox stayed unticked (PanLoop finding 8). `0*` on the unpadded form
+  // accepts both spellings; decimals ("1.1") survive the strip.
+  const unpadded = String(phaseNum).replace(/^0+(?=\d)/, '');
+  const numPat = `0*${escapeRegex(unpadded)}`;
+
+  // A tick that silently misses is indistinguishable from one that landed, so
+  // detect up front whether ANY checklist entry (ticked or not) names this
+  // phase — if none does, say so instead of best-effort-ing past it.
+  const hasChecklistEntry = new RegExp(`-\\s*\\[[ xX]\\]\\s*.*Phase\\s+${numPat}[:\\s]`, 'i').test(roadmapContent);
+
   // Checkbox: - [ ] Phase N: -> - [x] Phase N: (...completed DATE)
   const checkboxPattern = new RegExp(
-    `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s][^\\n]*)`,
+    `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${numPat}[:\\s][^\\n]*)`,
     'i'
   );
   roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
 
   // Progress table: update Plans Complete, Status, and Date columns
-  const phaseEscaped = escapeRegex(phaseNum);
   const tablePattern = new RegExp(
-    `(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
+    `(\\|\\s*${numPat}\\.?\\s[^|]*\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
     'i'
   );
   roadmapContent = roadmapContent.replace(
@@ -565,7 +622,7 @@ function markPhaseCompleteInRoadmap(cwd, phaseNum, _phaseName, planCount, summar
 
   // Update plan count in phase section
   const planCountPattern = new RegExp(
-    `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?(?:\\*\\*Plans:\\*\\*|\\*\\*Plans\\*\\*:)\\s*)[^\\n]+`,
+    `(#{2,4}\\s*Phase\\s+${numPat}[\\s\\S]*?(?:\\*\\*Plans:\\*\\*|\\*\\*Plans\\*\\*:)\\s*)[^\\n]+`,
     'i'
   );
   roadmapContent = roadmapContent.replace(
@@ -573,14 +630,21 @@ function markPhaseCompleteInRoadmap(cwd, phaseNum, _phaseName, planCount, summar
     `$1${summaryCount}/${planCount} plans complete`
   );
 
+  let roadmapWarning = hasChecklistEntry
+    ? null
+    : `no roadmap checklist entry found for Phase ${phaseNum} — checkbox not ticked; check the "- [ ] **Phase N:" line in ${ROADMAP_FILE}`;
+
   try {
     fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
   } catch {
-    // Roadmap write is best-effort during phase completion
+    roadmapWarning = `${ROADMAP_FILE} could not be written — phase completion was not recorded in the roadmap`;
   }
 
   const reqResult = markRequirementsCompleteForPhase(cwd, phaseNum, roadmapContent);
-  return { requirements_warning: reqResult && reqResult.error ? reqResult.error : null };
+  return {
+    requirements_warning: reqResult && reqResult.error ? reqResult.error : null,
+    roadmap_warning: roadmapWarning,
+  };
 }
 
 /**
@@ -779,6 +843,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
   if (roadmapResult && roadmapResult.requirements_warning) {
     result.requirements_warning = roadmapResult.requirements_warning;
   }
+  if (roadmapResult && roadmapResult.roadmap_warning) {
+    // roadmap_updated previously meant "roadmap.md exists", which reads as
+    // "the tick landed" and masked a silently missed checkbox (finding 8).
+    // When the tick did not land, say so on both fields.
+    result.roadmap_warning = roadmapResult.roadmap_warning;
+    result.roadmap_updated = false;
+  }
 
   // Auto-commit .planning/ metadata unless --no-commit or not a git repo
   const noCommit = opts && opts.noCommit;

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

@@ -139,7 +139,7 @@ function buildPhasePreview(cwd, phaseNum) {
 
   return {
     phase: String(phaseNum),
-    phase_name: phaseInfo.name || (roadmapPhase && roadmapPhase.phase_name) || null,
+    phase_name: phaseInfo.phase_name || (roadmapPhase && roadmapPhase.phase_name) || null,
     directory: toPosix(phaseInfo.directory),
     status,
     plan_count: planFiles.length,
@@ -269,11 +269,30 @@ function buildPhaseDependencyGraph(cwd) {
   };
 }
 
+// Checklist entries come in two shapes. templates/roadmap.md prescribes the bold
+// one WITH a trailing description:
+//   - [ ] **Phase 1: Foundation** - Core scaffolding
+// and hand-written roadmaps often use the plain one:
+//   - [ ] Phase 1: Foundation
+//
+// A single regex handled these badly. The previous pattern
+// (`([^\n*]+?)(?:\*\*)?\s*$`) required the line to END at the closing `**`, so
+// every template-shaped line — the format PAN itself writes — failed to match and
+// `preview phases` reported a phase_count with an EMPTY phases array, contradicting
+// itself. Widening the name group to allow a trailing description then broke names
+// containing a hyphen, because the lazy match stopped at the first one.
+//
+// Matching bold-first is what resolves it: `[^*\n]+` cannot cross `*`, so it runs
+// to the closing `**` regardless of hyphens inside the name, and anything after it
+// is description we discard.
+const CHECKLIST_BOLD_RE = /^\s*- \[([ x])\]\s*\*\*Phase\s+(\d+(?:\.\d+)?)\s*[:\-—]?\s*([^*\n]+?)\s*\*\*/i;
+const CHECKLIST_PLAIN_RE = /^\s*- \[([ x])\]\s*Phase\s+(\d+(?:\.\d+)?)\s*[:\-—]?\s*([^\n]+?)\s*$/i;
+
 function extractPhaseListFromRoadmap(content) {
   const phases = [];
-  const re = /- \[([ x])\]\s*(?:\*\*)?Phase\s+(\d+(?:\.\d+)?)\s*[:\-—]?\s*([^\n*]+?)(?:\*\*)?\s*$/gim;
-  let m;
-  while ((m = re.exec(content)) !== null) {
+  for (const line of String(content).split('\n')) {
+    const m = line.match(CHECKLIST_BOLD_RE) || line.match(CHECKLIST_PLAIN_RE);
+    if (!m) continue;
     phases.push({
       num: m[2],
       name: m[3].trim(),

package/pan-wizard-core/bin/lib/review-deep.cjs

@@ -246,11 +246,19 @@ function writeDeepReview(cwd, phaseNum, payload, opts) {
 
 // ─── CLI wrappers ───────────────────────────────────────────────────────────
 
+// M25: input files must resolve against the passed cwd, not process.cwd().
+// A relative --reviewer-file/--hardener-file/--meta-file was read from the
+// process working directory, silently missing the file when --cwd differed.
+function resolveAgainstCwd(cwd, p) {
+  if (!p) return p;
+  return path.isAbsolute(p) ? p : path.join(cwd, p);
+}
+
 function cmdReviewDeepMerge(cwd, phaseNum, opts, raw) {
   if (!phaseNum) error('Usage: review-deep merge <phase> --reviewer-file X --hardener-file Y [--meta-file Z]');
-  const reviewerContent = opts.reviewerFile ? safeReadFile(opts.reviewerFile) : '';
-  const hardenerContent = opts.hardenerFile ? safeReadFile(opts.hardenerFile) : '';
-  const metaContent = opts.metaFile ? safeReadFile(opts.metaFile) : '';
+  const reviewerContent = opts.reviewerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.reviewerFile)) : '';
+  const hardenerContent = opts.hardenerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.hardenerFile)) : '';
+  const metaContent = opts.metaFile ? safeReadFile(resolveAgainstCwd(cwd, opts.metaFile)) : '';
   if (!reviewerContent && !hardenerContent && !metaContent) {
     output({ error: 'No input files provided or readable' }, raw);
     return;
@@ -264,9 +272,9 @@ function cmdReviewDeepMerge(cwd, phaseNum, opts, raw) {
 function cmdReviewDeepAnalyze(cwd, phaseNum, opts, raw) {
   // Returns the merged payload WITHOUT writing a file. Useful for piping.
   if (!phaseNum) error('Usage: review-deep analyze <phase> --reviewer-file X --hardener-file Y [--meta-file Z]');
-  const reviewerContent = opts.reviewerFile ? safeReadFile(opts.reviewerFile) : '';
-  const hardenerContent = opts.hardenerFile ? safeReadFile(opts.hardenerFile) : '';
-  const metaContent = opts.metaFile ? safeReadFile(opts.metaFile) : '';
+  const reviewerContent = opts.reviewerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.reviewerFile)) : '';
+  const hardenerContent = opts.hardenerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.hardenerFile)) : '';
+  const metaContent = opts.metaFile ? safeReadFile(resolveAgainstCwd(cwd, opts.metaFile)) : '';
   output(mergeReviews(reviewerContent, hardenerContent, metaContent), raw);
 }
 

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

@@ -336,6 +336,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   const summaryCount = phaseInfo.summaries.length;
 
   if (planCount === 0) {
+    // No error key, exit 0: a phase with no plans has nothing to sync. The roadmap
+    // already says what it should say.
     output({ updated: false, reason: 'No plans found', plan_count: 0, summary_count: 0 }, raw, 'no plans');
     return;
   }
@@ -348,7 +350,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   try {
     roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
   } catch {
-    output({ updated: false, reason: 'roadmap.md not found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
+    // error key => exit 1: there are plans to record and nowhere to record them.
+    output({ updated: false, reason: 'roadmap.md not found', error: 'roadmap_not_found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
     return;
   }
   const phaseEscaped = escapeRegex(phaseNum);
@@ -400,7 +403,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   try {
     fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
   } catch (err) {
-    output({ updated: false, reason: 'Failed to write roadmap.md: ' + err.message }, raw, 'write error');
+    // error key => exit 1: the write failed, so progress was computed and then lost.
+    output({ updated: false, reason: 'Failed to write roadmap.md: ' + err.message, error: err.message || 'roadmap_write_failed' }, raw, 'write error');
     return;
   }
 

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

@@ -13,7 +13,8 @@
  * Exports:
  *   - runExperiment(slug, opts)           — spawn + observe + return result
  *   - tailExperimentState(slug, opts)     — read run-state.json snapshot
- *   - stopExperiment(slug, opts)          — graceful halt of a running experiment
+ *   - stopExperiment(slug, opts)          — reconcile the run-state of an experiment
+ *                                           (see its doc for the spawnSync limitation)
  *   - RUNTIME_RUNNERS                     — adapter map (per-runtime headless invocation)
  */
 
@@ -170,7 +171,7 @@ function appendEvent(state, type, details) {
  * @param {string} [opts.root] - experiment root (default PAN_EXPERIMENTS_ROOT_DEFAULT)
  * @param {string} [opts.prompt] - prompt passed to the external runtime; default
  *   is `/pan:new-project --auto @.planning/idea.md`
- * @param {number} [opts.timeoutMs] - hard timeout (default 30 min)
+ * @param {number} [opts.timeoutMs] - hard timeout (default 60 min)
  * @param {object} [opts.runtimeOverride] - { bin, buildArgs } to bypass the manifest's
  *   runtime adapter (used by tests)
  * @param {function} [opts.onProgress] - callback invoked per line of stdout/stderr
@@ -415,13 +416,22 @@ function tailExperimentState(slug, opts = {}) {
 // ── stopExperiment ──────────────────────────────────────────────────────────
 
 /**
- * Stop a running experiment.
+ * Reconcile the run-state of an experiment.
  *
- * If the experiment is currently running (run-state.json shows status=running
- * and pid is alive), send SIGTERM. If still alive after a short grace period,
- * SIGKILL.
+ * IMPORTANT (M26): this CANNOT terminate a live, in-flight run. runExperiment()
+ * uses a synchronous spawnSync (see its comments — a real-time/async runner is
+ * deferred to W3), which blocks until the child exits and only learns the child
+ * pid FROM the return value. So while a run is in flight run-state.json still has
+ * pid=null, and by the time a pid is recorded the process has already exited.
+ * There is therefore no live child for this function to signal.
  *
- * If the experiment has already finished, return its current state (no error).
+ * Behavior:
+ *   - status != 'running'  → return the current state (already finished; no error).
+ *   - status == 'running' but no pid recorded → return an error explaining that
+ *     the synchronous runner does not expose a live pid to signal.
+ *   - status == 'running' with a (stale) pid → best-effort SIGTERM and mark the
+ *     run failed/manual. Note the pid is almost certainly already dead under the
+ *     spawnSync model; live termination lands with the W3 async runner.
  */
 function stopExperiment(slug, opts = {}) {
   const root = opts.root || PAN_EXPERIMENTS_ROOT_DEFAULT;

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

@@ -1,10 +1,31 @@
 /**
  * Squads — agent groupings for the bot-army model (ADR-0032).
  *
- * A squad is a named, tool-scoped, model-tiered grouping of existing PAN
- * agents under the pan-conductor coordinator. This module is a registry +
- * resolver only — it modifies no agent and changes no execution path. The
- * army campaign command (ADR-0033) consumes it; until then it is inert.
+ * A squad is a named grouping of existing PAN agents under the pan-conductor
+ * coordinator, labelled with an intended model tier and an intended access
+ * contract. This module is a registry + resolver only — it modifies no agent
+ * and changes no execution path. `/pan:army` (ADR-0033) and `hud.cjs` read it;
+ * `grep -rn "squads.cjs')" pan-wizard-core/` enumerates its consumers.
+ *
+ * BOTH LABELS BELOW ARE ADVISORY METADATA, NOT ENFORCEMENT. Read this before
+ * writing any doc sentence about them, because the live docs now quote this
+ * header as the authority for exactly that (`grep -rn 'changes no execution
+ * path' docs commands` finds them):
+ *
+ *  - `access` is the intended least-privilege contract the conductor's prompt is
+ *    told to honour when it delegates. Nothing here strips a tool from an agent
+ *    or narrows a grant at spawn time. The binding grant is each agent's own
+ *    `tools:` frontmatter (`grep '^tools:' agents/*.md`), and it can be wider
+ *    than the label: several members of a `read-only` squad hold `Write` so they
+ *    can emit planning or verification artifacts, and the coordinator itself
+ *    holds `Write` and `Bash`. So a squad agent doing more than its label says
+ *    is the expected case, not a bug in this file.
+ *  - `tier` is a squad grouping attribute, not the resolver of anybody's model.
+ *    The active `model_profile` plus any per-agent `model:` pin decides that.
+ *
+ * The one rail the grants do enforce is delegation depth: only an agent granted
+ * `Task` can spawn another (`grep -l '^tools:.*Task' agents/*.md`), so squad
+ * members cannot fan out further.
  */
 
 'use strict';
@@ -14,13 +35,21 @@ const { output, error } = require('./core.cjs');
 /**
  * Coordinator + worker/utility agents that are NOT squad members.
  * - coordinator: the top of the hierarchy (Tier 0).
- * - workers: cheap narrow-job agents (Tier 2) + standalone utility agents
+ * - workers: narrow-job agents (Tier 2) + standalone utility agents
  *   invoked directly by commands, not delegated through a squad.
+ *
+ * "Tier 2" is a hierarchy position, not a model tier. Post-COST-RESET (2026-07)
+ * every agent in MODEL_PROFILES resolves to `reasoning` under both quality and
+ * balanced (the default); `budget` is the only profile that down-tiers, and it is
+ * the profile — never this list — that decides what an agent drops to. Note it
+ * down-tiers per agent, not per group: `budget` sends some of the workers below
+ * to `fast` and others to `mid`. MODEL_PROFILES in core.cjs is the table; read it
+ * rather than assuming one tier covers a row of a doc.
  */
 const COORDINATOR = 'pan-conductor';
 const WORKERS = Object.freeze([
-  'pan-document_code',     // Haiku-tier codebase mapper
-  'pan-distiller',         // Haiku-tier code-bloat optimizer
+  'pan-document_code',     // codebase mapper
+  'pan-distiller',         // code-bloat optimizer
   'pan-optimizer',         // optimization loop
   'pan-experiment-runner', // self-improvement loop
   'pan-knowledge',         // retrieval/Q&A
@@ -29,9 +58,12 @@ const WORKERS = Object.freeze([
 ]);
 
 /**
- * The four squads, keyed by lifecycle role. `tier` is a PAN model tier
- * (resolve-model maps it to a provider model); `access` is the least-privilege
- * tool contract the conductor grants when delegating to the squad.
+ * The squads, keyed by lifecycle role — `squad list` enumerates them at runtime.
+ * `tier` is a PAN model tier label (resolve-model maps a tier to a provider
+ * model); `access` is the intended
+ * least-privilege contract the conductor is instructed to honour when delegating
+ * to the squad. Neither is applied by this module — see the advisory note in the
+ * file header before describing either one as a restriction.
  */
 const SQUADS = Object.freeze({
   architecture: Object.freeze({
@@ -40,7 +72,7 @@ const SQUADS = Object.freeze({
     access: 'read-only',
     summary: 'Designs the system before code — contract-first.',
     agents: Object.freeze([
-      'pan-roadmapper', 'pan-planner', 'pan-plan-checker',
+      'pan-roadmapper', 'pan-planner', 'pan-designer', 'pan-plan-checker', 'pan-design-checker',
       'pan-project-researcher', 'pan-phase-researcher', 'pan-research-synthesizer',
     ]),
   }),

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) {