pan-wizard 3.22.0 → 3.25.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/lib/worktree.cjs

@@ -89,6 +89,91 @@ function listArmyWorktrees(cwd) {
   return out;
 }
 
+/**
+ * Sweep every army worktree and orphaned army/ branch (P-1815, PanLoop
+ * finding 13). The what-if subsystem always had this (`whatif cleanup`); the
+ * army path created worktrees that nothing removed — sibling `pan-army-*`
+ * directories and `army/*` branches accumulated after every campaign.
+ *
+ * Safety posture (the L3 lesson — never trade clutter for silent data loss):
+ * - A DIRTY worktree is kept unless `force` — git refuses, we surface why.
+ * - A branch is deleted only when its tip is reachable from HEAD (truly
+ *   integrated). Squash-merged and aborted branches are NOT reachable and may
+ *   hold the only copy of real work, so by default they are KEPT and listed
+ *   with the exact command to delete them; `force` sweeps them too.
+ *   (The per-task Phase 5 teardown — `worktree remove --branch` right after
+ *   the merge lands — deletes unconditionally; at that moment the deletion is
+ *   the documented intent. The sweeper is the abort/orphan tool, so it errs
+ *   the other way.)
+ * @param {string} cwd - main project root
+ * @param {Object} [opts] - { force: boolean }
+ * @returns {{removed_worktrees, deleted_branches, kept, pruned, clean}|{error}}
+ */
+function cleanupArmyWorktrees(cwd, opts) {
+  if (!isGitRepo(cwd)) return { error: 'Not a git repo' };
+  const force = opts?.force === true;
+  const removedWorktrees = [];
+  const deletedBranches = [];
+  const kept = [];
+
+  const branchIsIntegrated = (branch) =>
+    execGit(cwd, ['merge-base', '--is-ancestor', branch, 'HEAD']).exitCode === 0;
+
+  const deleteBranch = (branch, hadWorktree) => {
+    if (force || branchIsIntegrated(branch)) {
+      const del = execGit(cwd, ['branch', '-D', branch]);
+      if (del.exitCode === 0) deletedBranches.push(branch);
+      else kept.push({ branch, reason: `branch -D failed: ${del.stderr.trim()}` });
+    } else {
+      kept.push({
+        branch,
+        reason: `carries commits not reachable from HEAD (squash-merged or aborted work${hadWorktree ? '' : '; no worktree attached'}) — rerun with --force, or: git branch -D ${branch}`,
+      });
+    }
+  };
+
+  // 1. Registered army worktrees. Track every branch step 1 has already
+  //    decided on — deleted OR deliberately kept — so the orphan scan below
+  //    does not re-process (and double-report) it.
+  const handledBranches = new Set();
+  for (const t of listArmyWorktrees(cwd)) {
+    const rmArgs = ['worktree', 'remove'];
+    if (force) rmArgs.push('--force');
+    rmArgs.push(t.worktree);
+    const rm = execGit(cwd, rmArgs);
+    if (rm.exitCode !== 0) {
+      kept.push({ worktree: t.worktree, branch: t.branch, reason: `worktree remove refused: ${rm.stderr.trim()} — pass --force to discard uncommitted changes` });
+      if (t.branch) handledBranches.add(t.branch);
+      continue;
+    }
+    removedWorktrees.push(t.worktree);
+    if (t.branch) {
+      handledBranches.add(t.branch);
+      deleteBranch(t.branch, true);
+    }
+  }
+
+  // 2. Drop stale registrations (a manually deleted directory leaves one).
+  const pruned = execGit(cwd, ['worktree', 'prune']).exitCode === 0;
+
+  // 3. Orphaned army/ branches — a worktree removed without its branch.
+  const stillAttached = new Set(listArmyWorktrees(cwd).map(t => t.branch));
+  const ls = execGit(cwd, ['branch', '--list', `${ARMY_BRANCH_PREFIX}*`, '--format=%(refname:short)']);
+  if (ls.exitCode === 0) {
+    for (const branch of ls.stdout.split(/\r?\n/).map(s => s.trim()).filter(Boolean)) {
+      if (!stillAttached.has(branch) && !handledBranches.has(branch)) deleteBranch(branch, false);
+    }
+  }
+
+  return {
+    removed_worktrees: removedWorktrees,
+    deleted_branches: deletedBranches,
+    kept,
+    pruned,
+    clean: kept.length === 0,
+  };
+}
+
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
 function cmdWorktreeList(cwd, raw) {
@@ -112,12 +197,25 @@ function cmdWorktreeRemove(cwd, worktreePath, branch, raw, opts) {
   output(r, raw, r.warnings.length ? r.warnings.join('\n') : 'removed');
 }
 
+function cmdWorktreeCleanup(cwd, raw, opts) {
+  const r = cleanupArmyWorktrees(cwd, opts);
+  if (r.error) return error(r.error);
+  const lines = [
+    ...r.removed_worktrees.map(w => `removed worktree ${w}`),
+    ...r.deleted_branches.map(b => `deleted branch ${b}`),
+    ...r.kept.map(k => `KEPT ${k.worktree || k.branch}: ${k.reason}`),
+  ];
+  output(r, raw, lines.length ? lines.join('\n') : 'nothing to clean');
+}
+
 module.exports = {
   ARMY_BRANCH_PREFIX,
   createTaskWorktree,
   removeTaskWorktree,
   listArmyWorktrees,
+  cleanupArmyWorktrees,
   cmdWorktreeList,
   cmdWorktreeCreate,
   cmdWorktreeRemove,
+  cmdWorktreeCleanup,
 };

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;
     }
@@ -1169,8 +1191,10 @@ async function main() {
         worktree.cmdWorktreeCreate(cwd, args[2], raw, { base: getArgValue(args, '--base') });
       } else if (subcommand === 'remove') {
         worktree.cmdWorktreeRemove(cwd, args[2], getArgValue(args, '--branch'), raw, { force: args.includes('--force') });
+      } else if (subcommand === 'cleanup') {
+        worktree.cmdWorktreeCleanup(cwd, raw, { force: args.includes('--force') });
       } else {
-        error('Unknown worktree subcommand. Available: list, create, remove');
+        error('Unknown worktree subcommand. Available: list, create, remove, cleanup');
       }
       break;
     }
@@ -1295,6 +1319,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 +1331,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 +1406,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 +1420,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 +1430,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 +1452,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 +1475,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 +1490,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 +1529,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.