pan-wizard 3.22.0 → 3.24.0

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);
 }

package/pan-wizard-core/bin/pan-tools.cjs

@@ -27,13 +27,13 @@
  *   config-get <key>                   Get a config.json value
  *   history-digest                     Aggregate all summary.md data
  *   summary-extract <path> [--fields]  Extract structured data from summary.md
- *   state-snapshot                     Structured parse of state.md
+ *   state-snapshot                     Structured parse of state.md (alias: state snapshot)
  *   phase-plan-index <phase>           Index plans with waves and status
  *   websearch <query>                  Search web via Brave API (if configured)
  *     [--limit N] [--freshness day|week|month]
  *
  * Phase Listing:
- *   phases list [--type plan|summary]  List phases with optional type filter
+ *   phases list [--type plans|summaries]  List phases with optional type filter
  *     [--phase N] [--include-archived]
  *
  * Phase Operations:
@@ -282,8 +282,20 @@ async function main() {
 
   const command = args[0];
 
+  const USAGE = 'Usage: pan-tools <command> [args] [--raw] [--cwd <path>]\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links';
+
   if (!command) {
-    error('Usage: pan-tools <command> [args] [--raw] [--cwd <path>]\nCommands: state, state-snapshot, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, summary-extract, rollback-snapshot, websearch, focus, preflight, dashboard, learnings, deps, standards');
+    error(USAGE);
+  }
+
+  // P-1814 (PanLoop finding 11): `--help` was the single most frequent failed
+  // probe in field transcripts — 26 sightings across 10 command docs. It is
+  // the most predictable thing any agent or human tries, so it works: print
+  // the usage and exit 0. A missing command stays exit 1 (the error contract);
+  // an explicit request for help is a success.
+  if (command === '--help' || command === '-h' || command === 'help') {
+    console.log(USAGE);
+    process.exit(0);
   }
 
   switch (command) {
@@ -337,10 +349,16 @@ async function main() {
           stopped_at: getArgValue(args, '--stopped-at'),
           resume_file: getArgValue(args, '--resume-file', 'None'),
         }, raw);
+      } else if (subcommand === 'snapshot') {
+        // Alias for the top-level `state-snapshot` (P-1813). The hyphenated
+        // command reads exactly like a `state` subcommand, and a field agent
+        // guessed the spaced form by analogy (PanLoop finding 10). The guess
+        // is semantically right, so it lands on the real handler.
+        state.cmdStateSnapshot(cwd, raw);
       } else if (subcommand === 'load' || !subcommand) {
         state.cmdStateLoad(cwd, raw);
       } else {
-        error(`Unknown state subcommand: ${subcommand}. Available: json, update, get, patch, advance-plan, record-metric, update-progress, add-decision, add-blocker, resolve-blocker, record-session, load`);
+        error(`Unknown state subcommand: ${subcommand}. Available: json, update, get, patch, advance-plan, record-metric, update-progress, add-decision, add-blocker, resolve-blocker, record-session, load, snapshot`);
       }
       break;
     }
@@ -530,7 +548,7 @@ async function main() {
       } else if (subcommand === 'stubs') {
         verify.cmdVerifyStubs(cwd, { gate: args.includes('--gate') }, raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs');
       }
       break;
     }
@@ -786,8 +804,12 @@ async function main() {
 
     case 'batch-commit': {
       const itemsJson = args[1];
-      let items = [];
-      try { items = JSON.parse(itemsJson); } catch { /* empty */ }
+      // Report a malformed payload rather than silently reporting 'no_items':
+      // a caller whose JSON was garbled (e.g. shell-stripped quotes) must not be
+      // told there was nothing to commit. Absent arg → genuine empty batch.
+      const items = itemsJson === undefined || itemsJson === ''
+        ? []
+        : parseJsonOrError(itemsJson, 'batch-commit');
       commands.cmdBatchCommit(cwd, items, raw);
       break;
     }
@@ -1295,6 +1317,7 @@ async function main() {
       const subcommand = args[1];
       if (subcommand === 'trace') {
         const traceSub = args[2];
+        const tokensWasted = getArgValue(args, '--tokens-wasted');
         optimize.cmdOptimizeTrace(cwd, traceSub, {
           sessionId: getArgValue(args, '--session'),
           all: args.includes('--all'),
@@ -1306,9 +1329,8 @@ async function main() {
           type: getArgValue(args, '--type'),
           category: getArgValue(args, '--category'),
           impact: getArgValue(args, '--impact'),
-          description: getArgValue(args, '--description'),
           correction: getArgValue(args, '--correction'),
-          tokens_wasted: getArgValue(args, '--tokens-wasted') ? Number(getArgValue(args, '--tokens-wasted')) : null,
+          tokens_wasted: tokensWasted ? Number(tokensWasted) : null,
           context: (() => { const v = getArgValue(args, '--context'); if (!v) return null; try { return JSON.parse(v); } catch { return null; } })(),
         }, raw);
       } else if (subcommand === 'learn') {
@@ -1382,7 +1404,7 @@ async function main() {
         const sourceExperiments = sourceExpsCsv
           ? sourceExpsCsv.split(',').map(s => s.trim()).filter(Boolean)
           : [];
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
 
         const result = optimize.promotePattern(
           { id: patternId, summary, evidence, rule, applies_in: appliesIn, source_experiments: sourceExperiments },
@@ -1396,7 +1418,7 @@ async function main() {
         const patternId = getArgValue(args, '--pattern');
         const scope = getArgValue(args, '--scope');
         const topic = getArgValue(args, '--topic');
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         if (!patternId || !scope || !topic) {
           error('learn unpromote requires --pattern <id> --scope <s> --topic <t>');
         }
@@ -1406,14 +1428,14 @@ async function main() {
       }
 
       if (subcommand === 'list-promoted') {
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         const result = optimize.listPromotedPatterns({ sourceRoot });
         output(result, raw);
         break;
       }
 
       if (subcommand === 'build-index') {
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         const result = learnIndex.cmdBuildIndex(sourceRoot);
         if (raw) {
           output(result, true,
@@ -1428,7 +1450,7 @@ async function main() {
       }
 
       if (subcommand === 'topics-for') {
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         const agent = getArgValue(args, '--agent');
         if (!agent) { error('learn topics-for requires --agent <name>'); }
         const minRelevance = getArgValue(args, '--min-relevance', 'medium');
@@ -1451,7 +1473,7 @@ async function main() {
       }
 
       if (subcommand === 'lint') {
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         const scope = getArgValue(args, '--scope');
         const strict = args.includes('--strict');
         const result = learnLint.cmdLearnLint(sourceRoot, { scope, strict });
@@ -1466,11 +1488,12 @@ async function main() {
           for (const v of result.violations) {
             lines.push(`[${v.severity.toUpperCase()}] ${v.code} ${v.pattern_id}: ${v.message}`);
           }
-          output(result, true, lines.join('\n'));
+          output(result, true, lines.join('\n'), result.summary.status === 'fail' ? 1 : 0);
         } else {
-          output(result, false);
+          output(result, false, undefined, result.summary.status === 'fail' ? 1 : 0);
         }
-        if (result.summary.status === 'fail') process.exit(1);
+        // exit code carried through output() above (it used to hard-exit 0
+        // before this check, so `learn lint` never gated — M32, ADR audit 2026-08).
         break;
       }
 
@@ -1504,7 +1527,7 @@ async function main() {
     }
 
     default:
-      error(`Unknown command: ${command}. Run pan-tools without arguments to see available commands.`);
+      error(`Unknown command: ${command}. Run pan-tools --help to see available commands.`);
   }
 }
 

package/pan-wizard-core/learnings/index.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "generated_at": "2026-07-09T15:40:55.203Z",
+  "generated_at": "2026-08-07T13:36:47.532Z",
   "topics": [
     {
       "name": "experiment-runner",
@@ -152,8 +152,8 @@
         "P-350",
         "P-360"
       ],
-      "size_bytes": 10667,
-      "size_tokens_est": 2667,
+      "size_bytes": 11837,
+      "size_tokens_est": 2960,
       "agent_relevance": {
         "planner": "low",
         "executor": "medium",
@@ -218,8 +218,8 @@
         "P-1204",
         "P-NPRS-003"
       ],
-      "size_bytes": 3400,
-      "size_tokens_est": 850,
+      "size_bytes": 3402,
+      "size_tokens_est": 851,
       "agent_relevance": {
         "planner": "medium",
         "executor": "high",
@@ -804,7 +804,7 @@
   "totals": {
     "topics": 47,
     "patterns": 93,
-    "size_bytes": 148954,
-    "size_tokens_est": 37255
+    "size_bytes": 150126,
+    "size_tokens_est": 37549
   }
 }

package/pan-wizard-core/learnings/universal/autonomous-loop.md

@@ -37,12 +37,14 @@ patterns:
 
 ## P-330 — Scale agents into a coordinated army with squads, worktree isolation, and a human-gated ship
 
-**Evidence:** The bot-army model (ADR-0032/0033) showed the durable shape for running a whole-project goal across many agents: a delegation-only coordinator (never codes) fans work to role-scoped *squads* (architecture/build/quality/release), the build squad parallelizes by giving each agent its own branch + git worktree (so concurrent builders never touch the same file), quality is adversarial and read-only, and the path to a protected branch is a human-approved gate, not a bot merge.
+**Evidence:** The bot-army model (ADR-0032/0033) showed the durable shape for running a whole-project goal across many agents: a coordinator that routes rather than implements fans work to role-scoped *squads* (architecture/build/quality/release), the build squad parallelizes by giving each agent its own branch + git worktree (which is why concurrent builders cannot land in the same working file), quality is adversarial and reads more than it writes, and the path to a protected branch is a human-approved gate, not a bot merge.
+
+**Where the enforcement actually lives, and where it does not.** Worktree isolation is real isolation — separate directories, separate branches, enforced by git. The *role* labels are not: a coordinator that can spawn agents generally also holds file and shell tools, and a squad's `read-only` label is a contract its prompt is told to honour rather than a sandbox the runtime imposes. Both were written as absolutes here ("delegation-only", "never codes") and both were wrong; the guidance below survived the correction unchanged, because instructing the split is still right — claiming it is enforced is what was not.
 
 **Rule:** When scaling beyond a single agent:
 
-1. **Coordinator delegates, never codes** — its tools are delegation-only; it plans, decomposes, and routes to squads, then aggregates tight summaries.
-2. **Group agents into role-scoped squads with least-privilege tools** — design read-only, build read/write, quality read-only/adversarial, release always-ask. Resolve the roster from data, not hardcoded prompt lists.
+1. **Instruct the coordinator to delegate rather than implement** — it plans, decomposes, and routes to squads, then aggregates tight summaries. Treat that as prompt discipline and verify the grant instead of assuming it: read the coordinator's own `tools:` frontmatter, and if it holds write or shell tools, the split is instructed, not enforced. Say which of the two your prompt is relying on wherever you describe the design to a user.
+2. **Group agents into role-scoped squads with a declared least-privilege contract** — design read-only, build read/write, quality read-only/adversarial, release always-ask. Resolve the roster from data, not hardcoded prompt lists. A label is a contract until a per-agent grant matches it; a registry that maps agents to role labels changes no execution path on its own, so publish those labels as advisory rather than as guarantees.
 3. **Parallelize by isolation, not by hope** — one branch + worktree per concurrent builder; never two agents in one tree. Serialize builds only where the build tree corrupts under concurrency (a per-project opt-in).
 4. **The mutating boundary is human-gated** — merging to a protected branch is `always-ask`; recovery is revert / previous tag, never force-push or history rewrite.
 5. **The harness scales with the army, not after it** — depth caps, spawn/budget ceilings, and an abort kill-switch checked before every spawn are mandatory; a longer loop must not relax a single cap. Power and safety are the same investment.

package/pan-wizard-core/learnings/universal/concurrency.md

@@ -18,7 +18,7 @@ patterns:
 
 ## P-1204 — O_EXCL lockfile + retry with bounded backoff is enough for multi-process file writes in Node — no flock needed
 
-**Evidence:** whoocache lock.js + atomic-write.js: parallel-process tests with two child processes each calling set() 1000 times completed with consistent index, zero lost writes. P-1402 (whoocache 02-02 summary): 'O_EXCL lockfile + Windows rename retry' shipped Phase 2.
+**Evidence:** whoocache lock.js + atomic-write.js: parallel-process tests with two child processes each calling set() 1000 times completed with consistent index, zero lost writes. The whoocache 02-02 summary records 'O_EXCL lockfile + Windows rename retry' shipped Phase 2.
 
 **Rule:** For multi-process safe writes (parallel CLI invocations sharing one cache/index/state file), use fs.openSync(lockPath, 'wx') as a 'try-acquire' (EEXIST means held). On failure, retry with random backoff 5-50ms, capped at ~10 attempts. Always wrap acquired work in try/finally and unlink the lockfile in finally. Cross-platform safe (no flock dependency). Combine with the atomic write-tmp-then-rename pattern (P-1201) so even if the lock holder is killed mid-write, recovery is automatic.
 

package/pan-wizard-core/references/design-methodology.md

@@ -0,0 +1,94 @@
+# Design Methodology (shared)
+
+Single source of truth for how PAN designs a change **before** it is planned or
+executed. Cited by `pan-designer` (main flow, via `/pan:design-phase`) and by
+`focus-design` (the `/featureAI` feature pipeline). Both flows use the *same*
+method at different **depth tiers** so design quality can't drift between them.
+
+This reference defines: the depth tiers, what each tier must produce, and the
+quality bar every design artifact is held to (the same bar `pan-design-checker`
+verifies against). It does not prescribe a runtime — agents apply it with
+whatever tools they have.
+
+---
+
+## Depth tiers
+
+A tier selects which sections of the design artifact (`templates/design.md`) are
+**mandatory**. Deeper tiers are supersets of shallower ones. Pick the shallowest
+tier that fits the altitude of the work.
+
+| Tier | Altitude | Mandatory sections | Skips | Typical entry point |
+|------|----------|--------------------|-------|---------------------|
+| `spike` | Throwaway PoC / trivial change | Problem · Scope · Minimal architecture | Everything else — flag as speculative | `/pan:design-phase --spike`, `focus-design --spike` |
+| `phase` | One roadmap phase | Problem · Success criteria (≥2 machine-checkable) · Architecture assessment · Design synthesis · Phase-scoped ADR · Threat-lite · Test hooks | Demand validation, competitive intel, market/strategy | **`/pan:design-phase` (main-flow default)** |
+| `feature` | A whole feature (internal) | `phase` + Demand validation · Error-handling design · Full STRIDE-lite threat model · Test plan · Feature ladder | Competitive intel, strategic (Blue Ocean/Wardley) | `focus-design --internal` |
+| `full` | A market-facing feature | `feature` + Competitive intelligence · Strategic analysis (ERRC) · Adoption analysis | — (nothing) | `focus-design --full` (DEFAULT) |
+
+**Altitude rule (why the tiers exist):** product/strategic design — *whether*
+and *what* to build, with demand and competitive evidence — is decided **once**
+at feature/milestone creation (`focus-design`, or the product-design pass in
+`milestone-new`). Per-phase design (`phase` tier) covers only *how* to build an
+already-scoped phase: architecture, ADR, threat, synthesis. This keeps the
+frequently-run per-phase path cheap and stops the main flow re-litigating product
+questions on every phase.
+
+---
+
+## What every tier produces
+
+The artifact is `{scope}-design.md` from `templates/design.md`. Sections below are
+ordered; a tier makes a contiguous prefix (plus its named additions) mandatory.
+
+### 1. Problem & scope (all tiers)
+- **Problem statement** — what problem exists, why it matters, cost of inaction. Concrete, not a vague generality.
+- **Scope** — in-scope / out-of-scope, and the fixed boundary this design must not exceed (a phase boundary from `roadmap.md`, or a feature boundary).
+
+### 2. Success criteria (`phase`+)
+- 3–7 criteria, **at least 2 machine-checkable** (verifiable by an automated test, not manual inspection). State the check for each machine-checkable one.
+
+### 3. Architecture assessment & synthesis (`phase`+)
+- **Conventions** — extract the project's actual conventions (module layout, error style, boundaries) from the codebase; do not assume.
+- **Components & boundaries** — what modules are added/touched; confirm the design honors the discovered boundaries (no layer violations).
+- **Interface contract** — exact invocation + input/output schema + status/exit codes, per project convention.
+- **State & filesystem scope** — reads from / writes to (must stay within project root / `.planning/`), state mutations, side effects.
+- **Design decisions** — each significant decision: what was decided, why, alternatives rejected.
+
+### 4. ADR (`phase`+)
+- A right-sized Architecture Decision Record: Status · Date · Context (problem, forces, current state, requirements traceability) · Decision (summary + numbered sub-decisions with rationale + integration) · Consequences (positive **and** negative, every negative with a mitigation or explicit acceptance).
+- `phase` tier: phase-scoped ADR (may be a section in `design.md`). `feature`/`full`: a standalone `docs/decisions/ADR-NNNN-*.md`.
+
+### 5. Threat model (`phase` = lite, `feature`+ = full)
+- STRIDE-lite: for each realistic threat, its vector and its mitigation (or explicit acceptance). `phase` tier covers the change's own surface; `feature`+ covers the full feature.
+
+### 6. Error handling & diagnostics (`feature`+)
+- Every error condition → output shape + handling style (validate args before side effects; safe reads return null; actionable messages).
+
+### 7. Test plan (`phase` = hooks, `feature`+ = full)
+- How each success criterion is verified; which are unit vs scenario; the seed inputs for the machine-checkable ones.
+
+### 8. Demand & strategy (`feature`+ / `full`)
+- `feature`: demand evidence (or an explicit "speculative" flag), feature ladder (v0 MVP → v1 → v2).
+- `full`: competitive intelligence, strategic analysis (ERRC: eliminate/reduce/raise/create), adoption analysis.
+
+---
+
+## Quality bar (what `pan-design-checker` enforces)
+
+A design artifact **passes** only when all of these hold at its tier. This is the
+same checklist the independent checker verifies — designers should self-check
+against it before handing off, but passing is decided by the checker, not the
+author.
+
+1. **Requirement coverage** — every stated requirement maps to a design element; nothing is silently dropped.
+2. **Machine-checkable criteria** — ≥2 success criteria are automatable, and each names its check (`phase`+).
+3. **Architecture conformance** — the design matches conventions *discovered* from the codebase, and introduces no layer/boundary violation.
+4. **ADR honesty** — alternatives are real (not strawmen); every negative consequence has a mitigation or is explicitly accepted; no placeholder/skeleton sections (`phase`+).
+5. **Threat coverage** — each identified threat is mitigated or explicitly accepted; none is left open (`phase` lite / `feature`+ full).
+6. **Testability** — the test plan/hooks map to the success criteria (`phase`+).
+7. **Scope discipline** — the design stays within the fixed boundary; scope-expanding ideas are captured as "deferred", never designed in.
+
+If any dimension fails, the checker returns structured gaps and the designer
+revises. The reflexion loop is capped at **2 revision iterations** (design →
+check → revise → check → final) to prevent over-revision — the same guardrail
+`plan-phase` uses with `pan-plan-checker`.