pan-wizard 3.35.0 → 3.37.0

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

@@ -41,7 +41,8 @@
  *   phase next-decimal <phase>         Calculate next decimal phase number
  *   phase add <description>            Append new phase to roadmap + create dir
  *   phase insert <after> <description> Insert decimal phase after existing
- *   phase remove <phase> [--force]     Remove phase, renumber all subsequent
+ *   phase remove <phase> [--force] [--with-decimals]
+ *                                      Remove phase, renumber all subsequent
  *   phase complete <phase>             Mark phase done, update state + roadmap
  *
  * Roadmap Operations:
@@ -92,6 +93,26 @@
  *   verify commits <h1> [h2] ...      Batch verify commit hashes
  *   verify artifacts <plan-file>       Check must_haves.artifacts
  *   verify key-links <plan-file>       Check must_haves.key_links
+ *   verify red <phase>                 Each test the phase changed fails at the
+ *     [--timeout <ms>]                 phase's base and passes at HEAD (V4)
+ *   verify mutate --phase N            Mutation report on the phase's changed lines
+ *     [--max n] [--seed n]             (V5): which mutants the suite does not kill;
+ *     [--timeout <ms>]                 writes {NN}-mutation.json
+ *   verify review-focus <phase>        Every plan has a Review Focus: <=5 items,
+ *                                      each naming its task and test (P4)
+ *   verify decisions <phase>           Plans cite only DD-N ids the design records,
+ *                                      and every recorded one is cited (P2)
+ *   usage                              Local census: installed commands and agents
+ *                                      used, never used, unfinished (L9)
+ *   research lint <phase|path>         Claims table: source and date on every claim,
+ *     [--now YYYY-MM-DD]               stale ones per type window (P3)
+ *
+ * Test Gate (V2):
+ *   test run [--phase N] [--baseline]  Run the project's tests, any language; with
+ *     [--command "<cmd>"]              --phase, write {NN}-test-run.json (or the
+ *     [--timeout <ms>] [--rebaseline]  --baseline record) to the phase directory; an
+ *                                      existing baseline is kept unless --rebaseline
+ *   test detect                        The test command the gate would run, and why
  *
  * Template Fill:
  *   template fill summary --phase N    Create pre-filled summary.md
@@ -240,11 +261,14 @@ const findings = require('./lib/findings.cjs');
 const verifyPlanSet = require('./lib/verify-plan-set.cjs');
 const verifyIntegrity = require('./lib/verify-integrity.cjs');
 const phaseGate = require('./lib/phase-gate.cjs');
+const testGate = require('./lib/test-gate.cjs');
+const verifyRed = require('./lib/verify-red.cjs');
+const verifyScope = require('./lib/verify-scope.cjs');
+const mutate = require('./lib/mutate.cjs');
 const knowledge = require('./lib/knowledge.cjs');
 const skillAlign = require('./lib/skill-align.cjs');
 const hygiene = require('./lib/hygiene.cjs');
 const whatif = require('./lib/whatif.cjs');
-const bridge = require('./lib/bridge.cjs');
 const optimize = require('./lib/optimize.cjs');
 const git = require('./lib/git.cjs');
 const distill = require('./lib/distill.cjs');
@@ -365,7 +389,7 @@ async function main() {
     + '  --planning-dir <path>  act on an arbitrary project-relative planning tree\n'
     + '  --all-tracks           (hygiene) act on the root tree AND every discovered track\n'
     + '  env: PAN_TRACK, PAN_PLANNING_DIR (flags win)\n'
-    + '\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, findings, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links, version';
+    + '\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, test, review, debug, uat, merge, research, usage, 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, next-action, size, autodev, 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, whatif, knowledge, skills, hygiene, review-deep, findings, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links, version';
 
   if (!command) {
     error(USAGE);
@@ -390,6 +414,29 @@ async function main() {
         state.cmdStateUpdate(cwd, args[2], args[3]);
       } else if (subcommand === 'get') {
         state.cmdStateGet(cwd, args[2], raw);
+      } else if (subcommand === 'init' || subcommand === 'section' || subcommand === 'quick-task' || subcommand === 'apply') {
+        // A7b: the wholesale and by-section writers of state.md.
+        const sw = require('./lib/state-write.cjs');
+        if (subcommand === 'init') {
+          sw.cmdStateInit(cwd, {
+            coreValue: getArgValue(args, '--core-value'), focus: getArgValue(args, '--focus'),
+            phase: getArgValue(args, '--phase'), phaseName: getArgValue(args, '--phase-name'),
+            totalPhases: getArgValue(args, '--total-phases'), status: getArgValue(args, '--status'),
+            activity: getArgValue(args, '--activity'),
+            force: args.includes('--force'), keepContext: args.includes('--keep-context'),
+          }, raw);
+        } else if (subcommand === 'section') {
+          sw.cmdStateSection(cwd, args[2] && !args[2].startsWith('--') ? args[2] : null, {
+            append: getArgValue(args, '--append'), set: getArgValue(args, '--set'), under: getArgValue(args, '--under'),
+          }, raw);
+        } else if (subcommand === 'quick-task') {
+          sw.cmdStateQuickTask(cwd, {
+            description: getArgValue(args, '--description'), commit: getArgValue(args, '--commit'),
+            directory: getArgValue(args, '--directory'), status: getArgValue(args, '--status'), date: getArgValue(args, '--date'),
+          }, raw);
+        } else {
+          sw.cmdStateApply(cwd, getArgValue(args, '--json'), raw);
+        }
       } else if (subcommand === 'patch') {
         const patches = {};
         for (let i = 2; i < args.length; i += 2) {
@@ -446,7 +493,7 @@ async function main() {
       } else if (subcommand === 'load' || !subcommand) {
         state.cmdStateLoad(cwd, raw);
       } else {
-        error(`Unknown state subcommand: ${subcommand}. Available: json, update, get, patch, compact, advance-plan, record-metric, update-progress, add-decision, add-blocker, resolve-blocker, record-session, load, snapshot`);
+        error(`Unknown state subcommand: ${subcommand}. Available: json, update, get, patch, init, section, quick-task, apply, compact, advance-plan, record-metric, update-progress, add-decision, add-blocker, resolve-blocker, record-session, load, snapshot`);
       }
       break;
     }
@@ -630,6 +677,24 @@ async function main() {
       break;
     }
 
+    case 'test': {
+      const subcommand = args[1];
+      if (subcommand === 'run') {
+        testGate.cmdTestRun(cwd, {
+          phase: getArgValue(args, '--phase'),
+          baseline: args.includes('--baseline'),
+          rebaseline: args.includes('--rebaseline'),
+          command: getArgValue(args, '--command'),
+          timeout: getArgValue(args, '--timeout'),
+        }, raw);
+      } else if (subcommand === 'detect') {
+        testGate.cmdTestDetect(cwd, raw);
+      } else {
+        error('Unknown test subcommand. Available: run, detect');
+      }
+      break;
+    }
+
     case 'verify': {
       const subcommand = args[1];
       if (subcommand === 'plan-structure') {
@@ -656,8 +721,31 @@ async function main() {
         verifyPlanSet.cmdVerifyPlanSet(cwd, args[2], raw);
       } else if (subcommand === 'test-integrity') {
         verifyIntegrity.cmdVerifyTestIntegrity(cwd, args[2], raw);
+      } else if (subcommand === 'red') {
+        verifyRed.cmdVerifyRed(cwd, args[2], raw, { timeout: getArgValue(args, '--timeout') });
+      } else if (subcommand === 'review-focus') {
+        require('./lib/plan-lint.cjs').cmdVerifyReviewFocus(cwd, args[2], raw);
+      } else if (subcommand === 'decisions') {
+        require('./lib/plan-lint.cjs').cmdVerifyDecisions(cwd, args[2], raw);
+      } else if (subcommand === 'gates') {
+        require('./lib/plan-lint.cjs').cmdVerifyGates(cwd, args[2], raw);
+      } else if (subcommand === 'requirements') {
+        require('./lib/requirements-lint.cjs').cmdVerifyRequirements(cwd, raw);
+      } else if (subcommand === 'traceability') {
+        const named = args.slice(2).filter((a) => !a.startsWith('--'));
+        const ids = named.filter((a) => /^[A-Z][A-Z0-9]*-\d+$/.test(a));
+        // A misspelt id (auth-01) must not silently trace every requirement instead.
+        if (ids.length < named.length) error(`verify traceability: not a requirement id: ${named.filter((a) => !ids.includes(a)).join(', ')} (expected e.g. AUTH-01)`);
+        require('./lib/requirements-lint.cjs').cmdVerifyTrace(cwd, ids, raw);
+      } else if (subcommand === 'mutate') {
+        mutate.cmdVerifyMutate(cwd, {
+          phase: getArgValue(args, '--phase') || (args[2] && !args[2].startsWith('--') ? args[2] : null),
+          max: getArgValue(args, '--max'),
+          seed: getArgValue(args, '--seed'),
+          timeout: getArgValue(args, '--timeout'),
+        }, raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale, plan-set, test-integrity');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale, plan-set, test-integrity, red, mutate, review-focus, decisions, gates, requirements, traceability');
       }
       break;
     }
@@ -769,7 +857,7 @@ async function main() {
       } else if (subcommand === 'remove') {
         if (!args[2]) error('phase remove requires a phase number');
         const forceFlag = args.includes('--force');
-        phase.cmdPhaseRemove(cwd, args[2], { force: forceFlag }, raw);
+        phase.cmdPhaseRemove(cwd, args[2], { force: forceFlag, withDecimals: args.includes('--with-decimals') }, raw);
       } else if (subcommand === 'complete') {
         if (!args[2]) error('phase complete requires a phase number');
         const noCommit = args.includes('--no-commit');
@@ -815,7 +903,7 @@ async function main() {
         const fullFlag = args.includes('--full');
         const driftFlag = args.includes('--drift');
         const linksFlag = args.includes('--links');
-        verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag, links: linksFlag }, raw);
+        verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag, links: linksFlag, only: (getArgValue(args, '--only') || '').split(',').map((s) => s.trim()).filter(Boolean) }, raw);
       } else if (subcommand === 'deployment') {
         verify.cmdValidateDeployment(cwd, raw);
       } else {
@@ -824,6 +912,68 @@ async function main() {
       break;
     }
 
+    case 'autodev': {
+      // A1: the deterministic outer loop — a fresh host session per unit, stops in code.
+      require('./lib/autodev.cjs').cmdAutodev(cwd, args[1], {
+        host: getArgValue(args, '--host'), maxUsd: getArgValue(args, '--max-usd'), maxUsdDay: getArgValue(args, '--max-usd-day'),
+        maxTurns: getArgValue(args, '--max-turns'), run: getArgValue(args, '--run'), worktrees: args.includes('--worktrees'), quality: args.includes('--quality'),
+        ci: args.includes('--ci') ? (getArgValue(args, '--ci') === 'local' ? 'local' : 'pr') : false, ciRounds: getArgValue(args, '--ci-rounds'), ciPush: args.includes('--ci-push'), ciBase: getArgValue(args, '--ci-base'),
+      }, raw);
+      break;
+    }
+
+    case 'next-action': {
+      require('./lib/next-action.cjs').cmdNextAction(cwd, raw);
+      break;
+    }
+
+    case 'size': {
+      // Right-sized ceremony: lean or full for a phase or a quick task (sizing.cjs).
+      const S = require('./lib/sizing.cjs');
+      const subcommand = args[1];
+      const opts = { quality: args.includes('--quality'), full: args.includes('--full') };
+      if (subcommand === 'phase') {
+        if (!args[2] || args[2].startsWith('--')) error('Usage: size phase <N> [--quality] [--full]');
+        const r = S.sizePhase(cwd, args[2], opts);
+        output(r, raw, r.path);
+      } else if (subcommand === 'task') {
+        // --file <path>: size a document (new-project's idea or brief) instead of a description.
+        const file = getArgValue(args, '--file');
+        const text = file ? fs.readFileSync(require('path').resolve(cwd, file), 'utf8') : args.slice(2).filter((a) => a !== '--quality' && a !== '--full').join(' ');
+        if (!text.trim()) error('Usage: size task "<description>" | --file <path> [--quality] [--full]');
+        const r = S.sizeTask(cwd, text, opts);
+        output(r, raw, r.path);
+      } else if (subcommand === 'phase-plan') {
+        // size phase-plan <N>: the lean phase's plan, checked and recorded, with no planner.
+        if (!args[2] || args[2].startsWith('--')) error('Usage: size phase-plan <N> [--quality] [--full]');
+        const r = S.planLeanPhase(cwd, args[2], opts);
+        output(r, raw, r.ok ? r.path : (r.error || 'failed'), r.ok ? 0 : 1);
+      } else if (subcommand === 'quick-plan') {
+        // size quick-plan --out <file> --num <N> "<description>": the lean quick task's plan.
+        const out = getArgValue(args, '--out');
+        const num = getArgValue(args, '--num');
+        const skip = new Set(['--out', out, '--num', num]);
+        const text = args.slice(2).filter((a) => !skip.has(a)).join(' ');
+        if (!out || !text.trim()) error('Usage: size quick-plan --out <file> [--num N] "<description>"');
+        const outPath = require('path').resolve(cwd, out);
+        fs.mkdirSync(require('path').dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, S.leanQuickPlan(cwd, text, num));
+        output({ written: true, path: out }, raw, out);
+      } else if (subcommand === 'plan-check') {
+        if (!args[2] || args[2].startsWith('--')) error('Usage: size plan-check <N>');
+        const r = S.engineCheckPlans(cwd, args[2]);
+        if (r.ok) {
+          const rec = S.recordEngineCheck(cwd, args[2], r);
+          r.recorded = !rec.error;
+          if (rec.error) r.record_error = rec.reason || rec.error;
+        }
+        output(r, raw, r.ok ? 'passed' : 'failed', r.ok && r.recorded ? 0 : 1);
+      } else {
+        error('Unknown size subcommand. Available: phase, task, phase-plan, quick-plan, plan-check');
+      }
+      break;
+    }
+
     case 'progress': {
       const subcommand = args[1] || 'json';
       commands.cmdProgressRender(cwd, subcommand, raw);
@@ -980,7 +1130,7 @@ async function main() {
             break;
           }
           if (batch.error) {
-            // The newest batch is the one /pan:focus-exec runs; classifying another would
+            // The newest batch is the one /pan:focus-auto --step exec runs; classifying another would
             // hand it waves for the wrong items, so an unusable newest batch is an error.
             output({ error: batch.error }, raw);
             break;
@@ -1140,23 +1290,6 @@ async function main() {
       break;
     }
 
-    case 'bridge': {
-      const subcommand = args[1];
-      if (subcommand === 'list') {
-        bridge.cmdBridgeList(cwd, raw);
-      } else if (subcommand === 'recommend') {
-        bridge.cmdBridgeRecommend(cwd, args[2], {
-          max_recommendations: Number(getArgValue(args, '--max') || 10),
-          min_score: Number(getArgValue(args, '--min-score') || 1),
-        }, raw);
-      } else if (subcommand === 'cache') {
-        bridge.cmdBridgeCache(cwd, getArgValue(args, '--servers'), getArgValue(args, '--runtime'), raw);
-      } else {
-        error('Unknown bridge subcommand. Available: list, recommend, cache');
-      }
-      break;
-    }
-
     case 'whatif': {
       const subcommand = args[1];
       if (subcommand === 'prepare') {
@@ -1257,6 +1390,89 @@ async function main() {
       break;
     }
 
+    case 'review': {
+      // Program R1: the diff a reviewer reads, with the plans' intent beside it.
+      const subcommand = args[1];
+      if (subcommand === 'scope') {
+        verifyScope.cmdReviewScope(cwd, args[2], raw);
+      } else if (subcommand === 'vote') {
+        // R2: merge k reviewer passes; a finding survives only with a quorum of votes.
+        const valued = new Set(['--phase', '--quorum', '--out']);
+        const files = args.slice(2).filter((a, i, all) => !a.startsWith('--') && !valued.has(all[i - 1]));
+        require('./lib/review-vote.cjs').cmdReviewVote(cwd, { files, phase: getArgValue(args, '--phase'), quorum: getArgValue(args, '--quorum'), out: getArgValue(args, '--out') }, raw);
+      } else if (subcommand === 'cross-family') {
+        // R4: the review on another host's CLI, read-only; off unless the project opts in.
+        require('./lib/cross-family.cjs').cmdReviewCrossFamily(cwd, args[2], {
+          host: getArgValue(args, '--host'), reps: getArgValue(args, '--reps'), dryRun: args.includes('--dry-run'),
+        }, raw);
+      } else {
+        error('Unknown review subcommand. Available: scope, vote, cross-family');
+      }
+      break;
+    }
+
+    case 'merge': {
+      // L6a: the human merge gate on the CLI; confirm runs only in a person's terminal.
+      const subcommand = args[1];
+      const M = require('./lib/merge.cjs');
+      if (subcommand === 'request') {
+        M.cmdMergeRequest(cwd, args[2], { phase: getArgValue(args, '--phase'), ciGreen: args.includes('--ci-green') }, raw);
+      } else if (subcommand === 'confirm') {
+        M.cmdMergeConfirm(cwd, args[2], raw);
+      } else {
+        error('Unknown merge subcommand. Available: request, confirm');
+      }
+      break;
+    }
+
+    case 'uat': {
+      // L8: UAT results recorded through the engine, so every runtime leaves the same uat.md.
+      const subcommand = args[1];
+      const U = require('./lib/uat.cjs');
+      if (subcommand === 'record') {
+        U.cmdUatRecord(cwd, args[2], { test: getArgValue(args, '--test'), result: getArgValue(args, '--result'), reported: getArgValue(args, '--reported'), severity: getArgValue(args, '--severity'), reason: getArgValue(args, '--reason') }, raw);
+      } else if (subcommand === 'status') {
+        U.cmdUatStatus(cwd, args[2], raw);
+      } else {
+        error('Unknown uat subcommand. Available: record, status');
+      }
+      break;
+    }
+
+    case 'debug': {
+      // P5: a debug session's reproduction as the closing check, and the resolved case base.
+      const subcommand = args[1];
+      const D = require('./lib/debug-cases.cjs');
+      if (subcommand === 'repro') {
+        D.cmdDebugRepro(cwd, args[2], raw, { timeout: getArgValue(args, '--timeout') });
+      } else if (subcommand === 'similar') {
+        D.cmdDebugSimilar(cwd, args[2], raw, { limit: getArgValue(args, '--limit') });
+      } else {
+        error('Unknown debug subcommand. Available: repro, similar');
+      }
+      break;
+    }
+
+    case 'usage': {
+      // Program L9: which installed commands and agents this project used, from its own files.
+      require('./lib/usage.cjs').cmdUsage(cwd, raw);
+      break;
+    }
+
+    case 'research': {
+      // Program P3: research claims carry a source and a checked date.
+      const subcommand = args[1];
+      if (subcommand === 'lint') {
+        require('./lib/research-lint.cjs').cmdResearchLint(cwd, args[2], { now: getArgValue(args, '--now') }, raw);
+      } else if (subcommand === 'check') {
+        // Research answers at most five blocking questions, each with a source or an assumption.
+        require('./lib/research-lint.cjs').cmdResearchCheck(cwd, args[2], args[3], { market: args.includes('--market') }, raw);
+      } else {
+        error('Unknown research subcommand. Available: lint, check');
+      }
+      break;
+    }
+
     case 'review-deep': {
       const subcommand = args[1];
       const phaseNum = args[2];
@@ -1264,6 +1480,7 @@ async function main() {
         reviewerFile: getArgValue(args, '--reviewer-file'),
         hardenerFile: getArgValue(args, '--hardener-file'),
         metaFile: getArgValue(args, '--meta-file'),
+        crossFile: getArgValue(args, '--cross-file'),
       };
       if (subcommand === 'merge') {
         reviewDeep.cmdReviewDeepMerge(cwd, phaseNum, opts, raw);
@@ -1307,8 +1524,12 @@ async function main() {
         }, raw);
       } else if (subcommand === 'debt') {
         findings.cmdFindingsDebt(cwd, { milestone: filters.milestone }, raw);
+      } else if (subcommand === 'suppressions') {
+        findings.cmdFindingsSuppressions(cwd, { phase: filters.phase, agent: filters.agent }, raw);
+      } else if (subcommand === 'prove') {
+        findings.cmdFindingsProve(cwd, { id: findings.findingIdsIn(args.slice(2))[0], test: getArgValue(args, '--test'), timeout: getArgValue(args, '--timeout') }, raw);
       } else {
-        error('Unknown findings subcommand. Available: record, list, dispose, debt');
+        error('Unknown findings subcommand. Available: record, list, dispose, debt, suppressions, prove');
       }
       break;
     }
@@ -1359,8 +1580,10 @@ async function main() {
         }, raw);
       } else if (subcommand === 'limits') {
         cost.cmdCostLimits(cwd, raw);
+      } else if (subcommand === 'budget') {
+        cost.cmdCostBudget(cwd, getArgValue(args, '--phase') || (args[2] && !args[2].startsWith('--') ? args[2] : null), raw);
       } else {
-        error('Unknown cost subcommand. Available: report, append, clear, rebuild, limits');
+        error('Unknown cost subcommand. Available: report, append, clear, rebuild, limits, budget');
       }
       break;
     }
@@ -1399,8 +1622,14 @@ async function main() {
         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 if (subcommand === 'preflight') {
+        // A3: shadow-merge branches onto the base in a throwaway worktree and run the oracle.
+        worktree.cmdWorktreePreflight(cwd, {
+          base: getArgValue(args, '--base'), test: getArgValue(args, '--test'),
+          branches: String(getArgValue(args, '--branches') || '').split(',').map((b) => b.trim()).filter(Boolean),
+        }, raw);
       } else {
-        error('Unknown worktree subcommand. Available: list, create, remove, cleanup');
+        error('Unknown worktree subcommand. Available: list, create, remove, cleanup, preflight');
       }
       break;
     }

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

@@ -79,7 +79,7 @@ patterns:
 
 ## P-360 — Campaign telemetry must be both captured and trustworthy
 
-**Evidence:** Three production projects showed campaign telemetry failing in *both* directions. (1) **Absent** — a full 5-mission army campaign (the compliance project v1.1) produced **zero** cost/trace/bus records, although the hooks were installed, registered on `SubagentStop`, and verified working in isolation; a main-loop coordinator's work never fired `SubagentStop`, so nothing was captured. (2) **Corrupted** — two projects that *did* capture (a weeks-long focus-auto loop and a phase-exec project) logged physically-impossible figures: a single subagent record claiming billions of cache-read tokens, cache-hit pinned at 100%, and many byte-identical rows. Root cause: the transcript fallback summed `usage` across *every* assistant message in a transcript whose `session_id` is shared by all subagents — so each event re-summed the whole growing transcript, and `cache_read` (re-read every turn) multiplied by the turn count. Either way the HUD, `/pan:cost`, and `/pan:optimize` consumed nothing usable.
+**Evidence:** Three production projects showed campaign telemetry failing in *both* directions. (1) **Absent** — a full 5-mission army campaign (the compliance project v1.1) produced **zero** cost/trace/bus records, although the hooks were installed, registered on `SubagentStop`, and verified working in isolation; a main-loop coordinator's work never fired `SubagentStop`, so nothing was captured. (2) **Corrupted** — two projects that *did* capture (a weeks-long focus-auto loop and a phase-exec project) logged physically-impossible figures: a single subagent record claiming billions of cache-read tokens, cache-hit pinned at 100%, and many byte-identical rows. Root cause: the transcript fallback summed `usage` across *every* assistant message in a transcript whose `session_id` is shared by all subagents — so each event re-summed the whole growing transcript, and `cache_read` (re-read every turn) multiplied by the turn count. Either way the HUD, `/pan:cost`, and `/pan:learn --optimize` consumed nothing usable.
 
 **Rule:** For any long-running, multi-step autonomous campaign, telemetry must survive the spawn pattern *and* be numerically sane:
 
@@ -89,4 +89,4 @@ patterns:
 4. **Sanity-check before you trust the number.** A cache-hit pinned at 100%, or cache-read far exceeding input, is a miscount — not a triumph. Cap or flag implausible records instead of aggregating them.
 5. **Preflight a telemetry probe** at campaign start (write then read one record); treat empty *or* absurd telemetry as a defect, not a quiet state.
 
-**Applies in:** `/pan:army` Phase 0 + Learn step, `pan-conductor` campaign mode, `hooks/pan-cost-logger.js` + `pan-trace-logger.js`, the HUD telemetry panels, `/pan:cost`, `/pan:optimize`.
+**Applies in:** `/pan:army` Phase 0 + Learn step, `pan-conductor` campaign mode, `hooks/pan-cost-logger.js` + `pan-trace-logger.js`, the HUD telemetry panels, `/pan:cost`, `/pan:learn --optimize`.

package/pan-wizard-core/mcp/orchestrator.cjs

@@ -101,7 +101,10 @@ function normalizeStatus(status) {
 function isPhaseOpen(phase) {
   if (!phase || typeof phase !== 'object') return false;
   const status = normalizeStatus(phase.status);
-  if (status !== COMPLETE_STATUS) return true;
+  // The legacy `verified` alias stands for complete-and-verified: once merged, that phase
+  // is finished too. Without this a caller sending it got request_merge on every cycle,
+  // for a phase already merged (found by H7's nextAction fuzz).
+  if (status !== COMPLETE_STATUS) return !(PHASE_NEXT[status] === 'request_merge' && phase.merged === true);
   // Complete on disk, but the run facts decide whether it is actually finished.
   return !(phase.verified === true && phase.merged === true);
 }

package/pan-wizard-core/references/continuation-format.md

@@ -99,7 +99,7 @@ Add note that this is the last plan and what comes after:
 
 **Also available:**
 - `/pan:discuss-phase 2` — gather context first
-- `/pan:research-phase 2` — investigate unknowns
+- `/pan:plan-phase --research-only 2` — investigate unknowns
 - Review roadmap
 
 ---
@@ -128,7 +128,7 @@ Show completion status before next action:
 
 **Also available:**
 - `/pan:discuss-phase 3` — gather context first
-- `/pan:research-phase 3` — investigate unknowns
+- `/pan:plan-phase --research-only 3` — investigate unknowns
 - Review what Phase 2 built
 
 ---
@@ -149,7 +149,7 @@ When there's no clear primary action:
 
 **To discuss context first:** `/pan:discuss-phase 3`
 
-**To research unknowns:** `/pan:research-phase 3`
+**To research unknowns:** `/pan:plan-phase --research-only 3`
 
 <sub>`/clear` first → fresh context window</sub>
 

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

@@ -52,7 +52,7 @@ ordered; a tier makes a contiguous prefix (plus its named additions) mandatory.
 - **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.
+- **Design decisions** — each decision that passes the three-question test (hard to reverse, a reasonable engineer could choose otherwise, more than one task depends on it): its id (`DD-N`, which plans cite), 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).

package/pan-wizard-core/references/guardrails.md

@@ -11,7 +11,7 @@ phase — context compaction may have dropped earlier sections.
 |----------|--------------|----------------|
 | "User's request is clear, no need to clarify" | You're guessing at intent. Phase 0 catches misunderstandings before scaffolding. | Run the Phase 0 clarification check (see `new-project.md` / `plan-phase.md`). |
 | "Phase tests passed locally, /pan:verify-phase isn't needed" | One run isn't validation. verify-phase checks the phase goal against the code (must-haves, artifacts, wiring, requirements, anti-patterns) and runs the full test suite — not just the phase's own tests. | Always run `/pan:verify-phase` before marking a phase complete. |
-| "I'll skip /pan:focus-scan and pick the next item myself" | Manual selection ignores priority/budget logic in `focus.cjs`. You'll bias toward easy items and miss higher-priority work. | Use `/pan:focus-scan` → `/pan:focus-plan` → `/pan:focus-exec`. |
+| "I'll skip /pan:focus-auto --step scan and pick the next item myself" | Manual selection ignores priority/budget logic in `focus.cjs`. You'll bias toward easy items and miss higher-priority work. | Use `/pan:focus-auto --step scan` → `/pan:focus-auto --step plan` → `/pan:focus-auto --step exec`. |
 | "I'll bump the model / add a flag / refactor while I'm here" | Scope creep. The user asked for one change; surrounding cleanup belongs in a separate item. | Do only the requested change. Note unrelated cleanup as a TODO for a future focus-scan. |
 | "I'll mark this phase complete; the docs can lag behind" | Doc/state drift compounds. By the next session, the agent reads stale docs and proceeds on false assumptions. | Run the doc-sync step (update CHANGELOG/state and commit via `pan-tools commit`) before phase completion. CHANGELOG and version bumps are part of the phase, not after it. |
 | "The tests pass, so the code is portable" | Tests run on one Node version on one OS. Modern Node auto-detects ESM syntax, so `import`/`export` in a project with no `package.json` passes locally and fails under `"type": "commonjs"` or older Node. | Declare the module type explicitly whenever you emit `import`/`export` or `require` — `"type"` in `package.json`, or `.mjs`/`.cjs` extensions. Never rely on syntax detection. |

package/pan-wizard-core/references/handoff-decisions.md

@@ -83,7 +83,7 @@ Lives in `summary.md`, after `## Files Created/Modified`:
 - DT-1: Chose <option> for O-N. Reason: <rationale>.
 
 ### Deviations (from plan; must explain)
-- DV-1: Plan said <X>; I did <Y>. Reason: <rationale>. Verification: <how I confirmed Y is acceptable>.
+- DV-1: Plan said <X>; I did <Y>. Reason: <rationale>. Verification: <how I confirmed Y is acceptable>. Cost if wrong: <low | medium | high> — <what breaks if this call was wrong>.
 
 ### Open questions for verifier
 - Q-1: <question>. Why it matters: <stake>.

package/pan-wizard-core/references/model-profiles.md

@@ -65,7 +65,6 @@ Since the 2026-07 **COST RESET**, `quality` and `balanced` are identical — bot
 | pan-executor | reasoning | reasoning | mid |
 | pan-phase-researcher | reasoning | reasoning | fast |
 | pan-project-researcher | reasoning | reasoning | fast |
-| pan-research-synthesizer | reasoning | reasoning | fast |
 | pan-debugger | reasoning | reasoning | mid |
 | pan-document_code | reasoning | reasoning | fast |
 | pan-verifier | reasoning | reasoning | fast |
@@ -96,7 +95,7 @@ Relative cost per tier (fast = 1× baseline):
 | mid | 3× |
 | fast | 1× |
 
-Use `/pan:profile <profile>` to see estimated cost differences before switching.
+Use `/pan:settings --profile <profile>` to see estimated cost differences before switching.
 
 ---
 
@@ -242,7 +241,7 @@ Full routing config in `.planning/config.json`:
 
 ## Switching Profiles
 
-Runtime: `/pan:profile <profile>`
+Runtime: `/pan:settings --profile <profile>`
 
 ### Downgrade Confirmation
 

package/pan-wizard-core/references/questioning.md

@@ -142,4 +142,28 @@ Loop until "Create project.md" selected.
 
 </anti_patterns>
 
+<clarification_taxonomy>
+
+Before asking anything, scan the idea or the phase against these categories and note where it is ambiguous: where two reasonable readings would build different things. A category with no ambiguity needs no question.
+
+- **Scope**: what is in, what is explicitly out, where this ends
+- **Users** and roles: who acts, with what permissions, how many of them
+- **Behaviour** and flows: the main path, its order, what triggers it
+- **Data** and state: what is stored, its shape, its lifetime, who owns it
+- **Interfaces**: other systems, files, APIs and formats this touches
+- **Errors and edge cases**: empty, missing, duplicate, too large, offline, concurrent
+- **Non-functional**: speed, scale, security, accessibility, cost
+- **Constraints**: stack, platform, deadlines, compliance, what must not change
+- **Done**: how the user will know it works; what they would check first
+
+</clarification_taxonomy>
+
+<question_budget>
+
+Ask at most five clarifying questions in one questioning session (a new-project round, or one discuss-phase). Rank the ambiguities by impact × uncertainty: how much the build would differ between readings, times how unsure you are which reading the user means. Ask the top ones, one question per call unless two are independent and short.
+
+Everything you did not ask about is recorded, never silently guessed. Write it into the document you produce as a line the user can correct: `Assumed: <the reading you chose> (<category>)`. A wrong assumption in writing costs the user one correction; a wrong guess in code costs a rework.
+
+</question_budget>
+
 </questioning_guide>

package/pan-wizard-core/references/ui-brand.md

@@ -86,13 +86,11 @@ Plans: 3/5 complete
 ```
 ◆ Spawning researcher...
 
-◆ Spawning 4 researchers in parallel...
-  → Stack research
-  → Features research
-  → Architecture research
-  → Pitfalls research
+◆ Spawning 2 mappers in parallel...
+  → Tech mapper
+  → Architecture mapper
 
-✓ Researcher complete: STACK.md written
+✓ Researcher complete: 3 questions answered
 ```
 
 ---

package/pan-wizard-core/references/verdict-contract.md

@@ -25,8 +25,9 @@ A judging agent ends its report with one fenced `pan-verdict` block. The block i
 | `phase` | when you know it | the phase number you were asked about, e.g. `"03"` |
 | `verdict` | yes | your own verdict word (table below) |
 | `outcome` | yes | `pass`, `fail` or `needs_human` |
-| `findings` | yes (may be empty) | a list of `{class, severity, where, summary}` |
+| `findings` | yes (may be empty) | a list of `{class, severity, where, summary}`, plus `pre_existing: true` on a finding in code the change did not touch (recorded as deferred debt, never a blocker) |
 | `resolutions` | on a re-check | a list of `{id, status, evidence}` answering each earlier open finding you were given in `<open_findings>`: `status` is `resolved` (with `evidence`: what you checked and saw), `still_present` or `cannot_tell`. A finding you leave out stays open, and `resolved` without evidence is recorded as `cannot_tell` |
+| `declined` | when you set a behaviour aside | a list of `{behaviour, reason}`: something in scope you chose not to judge (outside your lens, outside the diff, no way to run it). It is recorded on the verdict, so silence about it is never read as a pass |
 | `not_checked` | when a check could not run | a list of `{check, reason}`: a check you were asked to make and could not run, and why (no test script, no browser, a file you could not read). Never fold it into `pass`: a verdict with entries here says what it did not see |
 
 | Agent | `verdict` → `outcome` |

package/pan-wizard-core/templates/config.json

@@ -2,15 +2,23 @@
   "mode": "interactive",
   "depth": "standard",
   "workflow": {
-    "research": true,
+    "research": false,
     "plan_check": true,
     "verifier": true,
     "auto_advance": false,
     "nyquist_validation": false,
     "phase_record_compact": false,
-    "phase_gate": "warn",
+    "phase_gate": "enforce",
+    "mutation_gate": "report",
+    "mutation_floor": 0.6,
+    "review_mode": "single",
+    "cross_family_review": "off",
+    "worktree_isolation": false,
     "phase_reports": { "enabled": false, "open": false, "theme": "auto", "index": true }
   },
+  "cost": {
+    "phase_budget_usd": 20
+  },
   "planning": {
     "commit_docs": true,
     "search_gitignored": false

package/pan-wizard-core/templates/debug.md

@@ -37,6 +37,7 @@ started: [when it broke / always broken]
 command: [one command you have RUN that fails on the reported symptom, or "none"]
 fails_with: [the output that shows the symptom, secrets redacted]
 deterministic: [yes / rate N of M runs for a flaky bug]
+requirement: [the requirement or UAT truth this reproduces, e.g. REQ-4, when there is one]
 tried: [only when command is "none": what you tried and why it cannot be built]
 
 ## Eliminated