pan-wizard 3.36.0 → 3.37.0

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

@@ -269,7 +269,6 @@ 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');
@@ -390,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, test, review, 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, 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);
@@ -415,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) {
@@ -471,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;
     }
@@ -705,6 +727,16 @@ async function main() {
         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),
@@ -713,7 +745,7 @@ async function main() {
           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, red, mutate, review-focus, decisions');
+        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;
     }
@@ -871,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 {
@@ -880,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);
@@ -1036,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;
@@ -1196,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') {
@@ -1318,8 +1395,60 @@ async function main() {
       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 review subcommand. Available: scope');
+        error('Unknown debug subcommand. Available: repro, similar');
       }
       break;
     }
@@ -1335,8 +1464,11 @@ async function main() {
       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');
+        error('Unknown research subcommand. Available: lint, check');
       }
       break;
     }
@@ -1348,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);
@@ -1393,8 +1526,10 @@ async function main() {
         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, suppressions');
+        error('Unknown findings subcommand. Available: record, list, dispose, debt, suppressions, prove');
       }
       break;
     }
@@ -1487,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/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/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/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,7 +2,7 @@
   "mode": "interactive",
   "depth": "standard",
   "workflow": {
-    "research": true,
+    "research": false,
     "plan_check": true,
     "verifier": true,
     "auto_advance": false,
@@ -10,6 +10,10 @@
     "phase_record_compact": false,
     "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": {

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

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

@@ -4,7 +4,7 @@ Template for `.planning/phases/XX-name/discovery.md` - shallow research for libr
 
 **Purpose:** Answer "which library/option should we use" questions when a phase needs a quick option comparison before planning.
 
-For deep ecosystem research ("how do experts build this"), use `/pan:research-phase` which produces research.md.
+For deep ecosystem research ("how do experts build this"), use `/pan:plan-phase --research-only` which produces research.md.
 
 ---
 
@@ -142,5 +142,5 @@ Create `.planning/phases/XX-name/discovery.md`:
 - Niche/complex domains (3D, games, audio, shaders)
 - Need ecosystem knowledge, not just library choice
 - "How do experts build this" questions
-- Use `/pan:research-phase` for these
+- Use `/pan:plan-phase --research-only` for these
 </guidelines>

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

@@ -17,6 +17,9 @@ Requirements for initial release. Each maps to roadmap phases.
 ### Authentication
 
 - [ ] **AUTH-01**: User can sign up with email and password
+  - WHEN a visitor submits a new email and a valid password THE SYSTEM SHALL create the account
+  - IF the email is already registered THEN THE SYSTEM SHALL refuse the sign-up without revealing the account
+  - Test: tests/auth/signup.test.ts
 - [ ] **AUTH-02**: User receives email verification after signup
 - [ ] **AUTH-03**: User can reset password via email link
 - [ ] **AUTH-04**: User session persists across browser refresh
@@ -74,6 +77,12 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 </template>
 
+<ears_criteria>
+Each v1 requirement carries at least one acceptance criterion as an indented sub-bullet in an EARS form: `WHEN <trigger> THE SYSTEM SHALL <response>`, `WHILE <state> …`, `WHERE <feature> …`, `IF <unwanted condition> THEN THE SYSTEM SHALL …`, or `THE SYSTEM SHALL …`. `pan-tools verify requirements` fails a v1 requirement with none.
+
+The tests that check a requirement go in `Test:` sub-bullets as the plans add them. `pan-tools verify traceability` runs them. A criterion with no mapped test reads `not_checked`, never met, and `phase complete` ticks a requirement only when its mapped tests pass. A requirement with no criteria at all is treated as legacy and keeps the old tick.
+</ears_criteria>
+
 <guidelines>
 
 **Requirement Format:**

package/pan-wizard-core/workflows/add-phase.md

@@ -60,13 +60,11 @@ Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
 <step name="update_project_state">
 Update state.md to reflect the new phase:
 
-1. Read `.planning/state.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {N} added: {description}
-   ```
+Append the entry under "## Accumulated Context" → "### Roadmap Evolution" (the engine creates the section when it is missing):
 
-If "Roadmap Evolution" section doesn't exist, create it.
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state section "Roadmap Evolution" --append "- Phase {N} added: {description}"
+```
 </step>
 
 <step name="completion">

package/pan-wizard-core/workflows/assumptions.md

@@ -1,7 +1,7 @@
 <purpose>
 Surface Claude's assumptions about a phase before planning, enabling users to correct misconceptions early.
 
-Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. No file output - purely conversational to prompt discussion.
+Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. The conversation ends with one file, `{phase_dir}/{phase_num}-assumptions.md`, holding the assumptions and the user's corrections, so discuss-phase and plan-phase start from them instead of losing them with the session.
 </purpose>
 
 <process>
@@ -145,6 +145,24 @@ This changes my understanding significantly. [Summarize new understanding]
 Assumptions validated.
 ```
 
+**Either way, save them.** Write `{phase_dir}/{phase_num}-assumptions.md` once, in full:
+
+```markdown
+# Phase {phase_num}: Assumptions
+
+**Reviewed:** {date}
+
+## Assumptions
+
+- {each assumption, as presented}
+
+## Corrections
+
+- {each correction, in the user's words; "None: the user confirmed the assumptions" when there were none}
+```
+
+`init phase-op` reports it as `assumptions_path`; discuss-phase and plan-phase read it. Commit it with the phase's docs when `commit_docs` is on.
+
 Continue to offer_next.
 </step>
 

package/pan-wizard-core/workflows/diagnose-issues.md

@@ -98,6 +98,8 @@ Template placeholders (see `debug-subagent-prompt.md`):
 - `{timeline}`: "Discovered during UAT"
 - `{true_or_false}`: `true` (symptoms are prefilled from the UAT gap)
 - `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
+
+Each gap gets its own reproduction, one per requirement or UAT truth it breaks (the debugger records `requirement:` beside the command). That command is the gap's closing check: the fix plan from `/pan:plan-phase --gaps` is done only when `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs debug repro <slug>` turns green.
 - `{slug}`: Generated from the issue summary
 </step>
 

package/pan-wizard-core/workflows/discuss-phase.md

@@ -116,7 +116,9 @@ Phase number from argument (required).
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE}")
 ```
 
-Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`.
+Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`, `assumptions_path`.
+
+**If `assumptions_path` is set**, read it first: it holds the assumptions `/pan:assumptions` surfaced and the user's corrections to them. Treat each correction as already decided; do not ask it again.
 
 **If `phase_found` is false:**
 ```
@@ -283,7 +285,7 @@ Analyze the phase to identify gray areas worth discussing.
 
 1. **Domain boundary** — What capability is this phase delivering? State it clearly.
 
-2. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation.
+2. **Gray areas by category**: scan the phase against the `<clarification_taxonomy>` in `references/questioning.md` (scope, users, behaviour, data, interfaces, errors and edge cases, non-functional, constraints, done), plus UI, UX, empty states and content for a user-facing phase. Identify the specific ambiguities that would change implementation, then keep to the `<question_budget>`: at most five questions, ranked by impact × uncertainty, and every ambiguity you do not ask about written into context.md as an `Assumed:` line the user can correct.
 
 3. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), the phase may not need discussion.