pan-wizard 3.34.0 → 3.36.0

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

@@ -31,7 +31,7 @@
  *   findings record|list|dispose|debt  Judges' verdicts and their findings ledger (evidence loop)
  *   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]
+ *     [--limit N] [--freshness day|week|month|year]
  *
  * Phase Listing:
  *   phases list [--type plans|summaries]  List phases with optional type filter
@@ -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
@@ -237,6 +258,13 @@ const costRebuild = require('./lib/cost-rebuild.cjs');
 const preview = require('./lib/preview.cjs');
 const reviewDeep = require('./lib/review-deep.cjs');
 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');
@@ -362,7 +390,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, 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';
 
   if (!command) {
     error(USAGE);
@@ -627,6 +655,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') {
@@ -649,8 +695,25 @@ async function main() {
         verify.cmdVerifyScope(cwd, args[2], raw);
       } else if (subcommand === 'stale') {
         verify.cmdVerifyStale(cwd, args[2], raw);
+      } else if (subcommand === 'plan-set') {
+        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 === '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');
+        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');
       }
       break;
     }
@@ -762,13 +825,15 @@ 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');
-        phase.cmdPhaseComplete(cwd, args[2], raw, { noCommit });
+        phase.cmdPhaseComplete(cwd, args[2], raw, { noCommit, force: args.includes('--force'), reason: getArgValue(args, '--reason') });
+      } else if (subcommand === 'gate') {
+        phaseGate.cmdPhaseGate(cwd, args[2], raw, { mode: getArgValue(args, '--mode') || undefined });
       } else {
-        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete');
+        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete, gate');
       }
       break;
     }
@@ -1248,6 +1313,34 @@ 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 {
+        error('Unknown review subcommand. Available: scope');
+      }
+      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 {
+        error('Unknown research subcommand. Available: lint');
+      }
+      break;
+    }
+
     case 'review-deep': {
       const subcommand = args[1];
       const phaseNum = args[2];
@@ -1298,8 +1391,10 @@ 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 {
-        error('Unknown findings subcommand. Available: record, list, dispose, debt');
+        error('Unknown findings subcommand. Available: record, list, dispose, debt, suppressions');
       }
       break;
     }
@@ -1350,8 +1445,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;
     }

package/pan-wizard-core/mcp/merge-gate.cjs

@@ -52,17 +52,28 @@ function writeJson(p, obj) { fs.mkdirSync(path.dirname(p), { recursive: true });
  * Stage a merge request. Mints a fresh per-request approval token (nonce), records the
  * exact branch + the (caller-attested) CI/verify flags, marks it awaiting_approval, and
  * returns the record. Does NOT merge. The operator sets PAN_MERGE_APPROVAL to
- * `record.approval_token` after reviewing. (ci_green/verify_pass are agent-attested
- * advisory context for the human's decision; the token is the sole unfakeable anchor.)
+ * `record.approval_token` after reviewing. ci_green is agent-attested advisory context.
+ * verify_pass is too, unless the request names a `phase`: then it is the phase gate's
+ * verdict (program V1), computed here, and the caller's flag is ignored. The token is
+ * the sole unfakeable anchor either way.
  */
 function requestMerge(cwd, opts = {}) {
   const branch = validateBranch(opts.branch);
+  let verifyPass = !!opts.verify_pass;
+  let gate = null;
+  if (opts.phase != null && String(opts.phase).trim() !== '') {
+    const g = require('../bin/lib/phase-gate.cjs').phaseGate(cwd, String(opts.phase).trim());
+    gate = g.error ? { phase: String(opts.phase), error: g.error } : { phase: g.phase, ok: g.ok, reasons: g.reasons.map((r) => r.code) };
+    verifyPass = !g.error && g.ok;
+  }
   const record = {
     id: slugify(branch),
     branch,
     approval_token: crypto.randomBytes(9).toString('hex'),
     ci_green: !!opts.ci_green,
-    verify_pass: !!opts.verify_pass,
+    verify_pass: verifyPass,
+    verify_source: gate ? 'phase_gate' : 'caller',
+    ...(gate ? { gate } : {}),
     status: 'awaiting_approval',
     requested_at: opts.now || null,
   };

package/pan-wizard-core/mcp/native-tools.cjs

@@ -126,14 +126,14 @@ const NATIVE_TOOLS = [
   {
     name: 'pan_request_merge',
     title: 'Request a gated merge',
-    description: 'Stage a squash-merge request for a branch and mark it awaiting human approval. Records intent only — does NOT merge.',
+    description: 'Stage a squash-merge request for a branch and mark it awaiting human approval. Records intent only — does NOT merge. Name the phase the branch delivers: verify_pass is then the phase gate\'s verdict, not the caller\'s flag.',
     readOnly: false, destructive: false,
     inputSchema: {
       type: 'object', additionalProperties: false, required: ['branch'],
-      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' } },
+      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' }, phase: { type: 'string' } },
     },
     handler: ({ cwd, input }) => ({
-      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass }),
+      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass, phase: input.phase }),
     }),
   },
   {

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/opencode/pan-wizard.js

@@ -11,8 +11,9 @@
 // hooks/pan-state-reinject.js after compaction.
 //
 // Installed by the PAN installer as <opencode config dir>/plugins/pan-wizard.js,
-// beside the `{"type":"commonjs"}` package.json PAN writes there, so this file is
-// CommonJS and exports the plugin module shape `{ id, server }`.
+// below the `{"type":"commonjs"}` package.json PAN writes in the config dir, so this file is
+// CommonJS and exports one object both loaders accept: `{ id, server, setup }`
+// (OpenCode 1 calls server(), OpenCode 2 calls setup()).
 //
 // Inert unless the project is a PAN project with work in flight (a state.md naming
 // a current phase and a roadmap.md with an unticked phase). Never writes anything.
@@ -96,16 +97,43 @@ function compactionContext(directory) {
   return block.length > BLOCK_MAX ? block.slice(0, BLOCK_MAX - 1) + '…' : block;
 }
 
+function directoryOf(ctx) {
+  return (ctx && (ctx.directory || ctx.worktree)) || process.cwd();
+}
+
+/** Push PAN's block onto the first array target; fail-open, inert outside work in flight. */
+function pushBlock(directory, target) {
+  try {
+    if (!Array.isArray(target)) return;
+    const block = compactionContext(directory);
+    if (block) target.push(block);
+  } catch { /* fail open: a compaction without PAN's block beats a broken one */ }
+}
+
+// OpenCode 1: the loader calls server() and reads its hook map.
 async function server(ctx) {
-  const directory = (ctx && (ctx.directory || ctx.worktree)) || process.cwd();
+  const directory = directoryOf(ctx);
   return {
     'experimental.session.compacting': async (input, output) => {
-      try {
-        const block = compactionContext(directory);
-        if (block && output && Array.isArray(output.context)) output.context.push(block);
-      } catch { /* fail open: a compaction without PAN's block beats a broken one */ }
+      pushBlock(directory, output && output.context);
     },
   };
 }
 
-module.exports = { id: 'pan-wizard', server };
+// OpenCode 2: the loader requires `setup` (or `effect`) and hooks register through
+// `ctx.session.hook(name, fn)` (opencode.ai/v2/docs/build/plugins, migrate-v1). The
+// compaction event's prompt parts are `system` (read from the 2.0 binary); `context`
+// is the documented v1 name and the fallback.
+function setup(ctx) {
+  try {
+    const directory = directoryOf(ctx);
+    const session = ctx && ctx.session;
+    if (!session || typeof session.hook !== 'function') return;
+    session.hook('compaction', async (event) => {
+      if (!event) return;
+      pushBlock(directory, Array.isArray(event.system) ? event.system : event.context);
+    });
+  } catch { /* fail open: a plugin that cannot register leaves the session as it was */ }
+}
+
+module.exports = { id: 'pan-wizard', server, setup };

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/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

@@ -34,7 +34,7 @@ PAN never selects your host model — it recommends a *class*. Because the `reas
 
 The IDs below are *examples* of what you can configure in each class — not an exhaustive or only-valid list. A newer release in the same class behaves the same way here.
 
-At install time PAN also runs a **best-effort, advisory** capability check on the model ID you have configured (`detectModelCapabilities` in `bin/install-lib.cjs`). It recognizes the current Claude generations by name, and its forward threshold per family is the last reduced-capability release it records rather than the newest release it lists: any Claude ID newer than that boundary — a new major, or a later point release inside a major it already lists — inherits that family's modern profile instead of reporting no capabilities at all. "That family's profile" is the point: a newer Haiku inherits Haiku's, which is not a 1M-context/thinking profile. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. It is a name-matching heuristic, not a live probe of the model, so it can still be imprecise about something released after this table — read it as a hint, not a contract. Either way it decides one thing only: whether the installer prints a capability *warning*. No routing, mode-selection, or feature gate in PAN reads it, so a wrong guess costs you a misleading install-time line and nothing else.
+At install time PAN also runs a **best-effort, advisory** capability check on the model ID you have configured (`detectModelCapabilities` in `bin/install-lib.cjs`). It recognizes the current Claude generations by name, and its forward threshold per family is the last reduced-capability release it records rather than the newest release it lists: any Claude ID newer than that boundary — a new major, or a later point release inside a major it already lists — inherits that family's modern profile instead of reporting no capabilities at all. "That family's profile" is the point: a newer Haiku inherits the newest Haiku profile the table records (1M context and thinking, at the fast tier), not Opus's. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. It is a name-matching heuristic, not a live probe of the model, so it can still be imprecise about something released after this table — read it as a hint, not a contract. Either way it decides one thing only: whether the installer prints a capability *warning*. No routing, mode-selection, or feature gate in PAN reads it, so a wrong guess costs you a misleading install-time line and nothing else.
 
 | Class | Example model IDs | Role in PAN | Context | Relative cost | Notes |
 |-------|-------------------|-------------|---------|---------------|-------|

package/pan-wizard-core/references/planning-config.md

@@ -42,7 +42,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: update state" --f
 
 # Load config via state load (returns JSON):
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
-# commit_docs is available in the JSON output
+# commit_docs is at .config.commit_docs in the JSON output
 
 # Or use init commands which include commit_docs:
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "1")
@@ -147,7 +147,7 @@ INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "1")
 Or use `state load` for the config values:
 ```bash
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
-# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
+# Parse .config.branching_strategy, .config.phase_branch_template, .config.milestone_branch_template from JSON
 ```
 
 **Branch creation:**
@@ -168,7 +168,7 @@ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
 fi
 ```
 
-**Merge options at milestone-done:**
+**Merge options after milestone-done (it does not merge — run one yourself):**
 
 | Option | Git command | Result |
 |--------|-------------|--------|

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

@@ -26,6 +26,7 @@ A judging agent ends its report with one fenced `pan-verdict` block. The block i
 | `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}` |
+| `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` |
 | `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` |
@@ -36,6 +37,10 @@ A judging agent ends its report with one fenced `pan-verdict` block. The block i
 
 The verifier does not emit this block. Its verification.md frontmatter (`status`, `gaps`, `human_verification`, `unrequested`, `test_gate`, `not_checked`) is its machine contract, and the recorder reads that directly. `test_gate` is `passed`, `failed` or `skipped`. A skipped gate is recorded as a `tests` entry in `not_checked` even when the list leaves it out, and a verification that does not record `test_gate` at all is recorded with a `test_gate_unrecorded` warning.
 
+**Findings close on evidence, never on silence.** An earlier finding closes only when the judge answers it `resolved` with evidence (a `resolutions` entry, or a truth in the verifier's `re_verification.gaps_closed`), or, for a `code-fact:` finding, when that fact passes. A finding the new report neither repeats nor answers stays open and is listed as `unaddressed`. A reworded report of an earlier finding (same class family, where `missing` and `partial` count as one; same file; same truth or a similar summary) keeps the earlier id.
+
+**Code facts only lower a verdict (two-key verdict).** A fact the engine measures can turn a judge's `pass` or `needs_human` into a fail, never the reverse. `test_gate: failed` under `status: passed` records as `gaps_found`: the record keeps the judge's own word as `agent_verdict`, names the fact in `lowered_by`, and adds a high finding at `code-fact:test_gate` for the gap round to close. `findings record --raw` prints the lowered word, so the workflow routes to gap closure.
+
 ## `class`: what kind of finding
 
 | Class | Use when |
@@ -67,7 +72,7 @@ The verifier does not emit this block. Its verification.md frontmatter (`status`
 - `where`: `NN-MM-plan.md` or `NN-MM-plan.md#task-N`.
 
 **pan-reviewer.**
-- Classes by category: Convention → `quality`, Security → `risk`, Code Quality → `defect`, work no plan asked for → `unrequested`.
+- Classes by category: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Design smell → `quality`, work no plan asked for → `unrequested`.
 - Severity: ERROR → `high`, WARNING → `medium`, INFO → `info`.
 - `where`: `path:line`.
 

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

@@ -8,19 +8,19 @@
     "auto_advance": false,
     "nyquist_validation": false,
     "phase_record_compact": false,
+    "phase_gate": "enforce",
+    "mutation_gate": "report",
     "phase_reports": { "enabled": false, "open": false, "theme": "auto", "index": true }
   },
+  "cost": {
+    "phase_budget_usd": 20
+  },
   "planning": {
     "commit_docs": true,
     "search_gitignored": false
   },
   "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "task_level": false,
-    "skip_checkpoints": true,
-    "max_concurrent_agents": 3,
-    "min_plans_for_parallel": 2
+    "enabled": true
   },
   "gates": {
     "confirm_project": true,

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

@@ -57,13 +57,14 @@ Create: .planning/debug/{slug}.md
 Task(
   prompt=filled_template,
   subagent_type="pan-debugger",
+  model="{debugger_model}",
   description="Debug {slug}"
 )
 ```
 
 **From diagnose-issues (UAT):**
 ```python
-Task(prompt=template, subagent_type="pan-debugger", description="Debug UAT-001")
+Task(prompt=template, subagent_type="pan-debugger", model="{debugger_model}", description="Debug UAT-001")
 ```
 
 ---

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

@@ -66,10 +66,11 @@ tier may omit them.
 - Writes to: [paths — within .planning/ or project root]
 - Side effects: [git ops, dir creation, etc.]
 
-**Design decisions:**
-| Decision | Chosen | Alternative rejected | Rationale |
-|----------|--------|----------------------|-----------|
-| [point] | [what] | [alt] | [why] |
+**Design decisions:** record a decision here only when it passes all three questions: (1) is it hard to reverse once code depends on it? (2) could a reasonable engineer have chosen otherwise? (3) does more than one task or plan depend on it? A choice that fails any of them is the planner's to make, not a design decision. Each recorded decision gets an id (`DD-1`, `DD-2` …) that the plans implementing it cite; `pan-tools verify decisions` flags a plan citing an id not recorded here and a decision no plan cites.
+
+| ID | Decision | Chosen | Alternative rejected | Rationale |
+|----|----------|--------|----------------------|-----------|
+| DD-1 | [point] | [what] | [alt] | [why] |
 </architecture>
 
 <adr>

package/pan-wizard-core/templates/phase-prompt.md

@@ -22,6 +22,7 @@ files_modified: []
 autonomous: true
 requirements: []
 user_setup: []
+planned_commit: <sha>
 
 # Goal-backward verification (derived during planning, verified after execution); the Frontmatter Fields table below explains each field
 must_haves:
@@ -70,6 +71,13 @@ Output: [What artifacts will be created]
 ### Considered and rejected
 - R-1: [alternative]. Rejected because: [reason].
 
+<!-- A Locked decision that implements a design decision cites its id: "Source: design DD-2". -->
+
+## Review Focus
+<!-- At most five inputs or failure modes the requirements imply that no test exercises yet,
+     each pinned to the task that owns the code. If genuinely none: "None — [why]". -->
+- RF-1: [input or failure mode]. Test: Task [N] adds [test that fails if it is mishandled].
+
 <tasks>
 
 <task type="auto">
@@ -144,6 +152,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-summary.md`
 | `files_modified` | Yes | Files this plan touches. |
 | `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
 | `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement MUST appear in at least one plan. |
+| `planned_commit` | Yes | `git rev-parse HEAD` when the plan is written. exec-phase lists the `files_modified` that changed on the branch since then, so an executor knows its plan's picture of the code may be out of date. |
 | `user_setup` | No | Array of human-required setup items (external services) |
 | `must_haves` | Yes | Goal-backward verification criteria (see below) |
 

package/pan-wizard-core/templates/planner-subagent-prompt.md

@@ -71,6 +71,7 @@ Before returning PLANNING COMPLETE:
 Task(
   prompt=filled_template,
   subagent_type="pan-planner",
+  model="{planner_model}",
   description="Plan Phase {phase}"
 )
 ```
@@ -80,6 +81,7 @@ Task(
 Task(
   prompt=filled_template,  # with mode: gap_closure
   subagent_type="pan-planner",
+  model="{planner_model}",
   description="Plan gaps for Phase {phase}"
 )
 ```

package/pan-wizard-core/templates/preview-report.md

@@ -59,7 +59,7 @@ source: pan-previewer
 ## Hidden coupling
 
 <!-- phases mode only; may be "none found" -->
-- Phase {{from}} → Phase {{to}} — inferred from prose mention; consider promoting to `depends_on:` frontmatter.
+- Phase {{from}} → Phase {{to}} — inferred from prose mention; consider adding it to Phase {{to}}'s `**Depends on:**` line in the roadmap.
 
 ## Current state
 

package/pan-wizard-core/templates/research-project/architecture.md

@@ -161,6 +161,12 @@ src/
 |----------|---------------|-------|
 | [module A ↔ module B] | [API/events/direct] | [considerations] |
 
+## Claims
+
+| Claim | Type | Source | Checked |
+|-------|------|--------|---------|
+| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
+
 ## Sources
 
 - [Architecture references]

package/pan-wizard-core/templates/research-project/features.md

@@ -104,6 +104,12 @@ Features to defer until product-market fit is established.
 | [feature] | [how they do it] | [how they do it] | [our plan] |
 | [feature] | [how they do it] | [how they do it] | [our plan] |
 
+## Claims
+
+| Claim | Type | Source | Checked |
+|-------|------|--------|---------|
+| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
+
 ## Sources
 
 - [Competitor products analyzed]

package/pan-wizard-core/templates/research-project/pitfalls.md

@@ -151,6 +151,12 @@ How roadmap phases should address these pitfalls.
 | [pitfall] | Phase [X] | [how to verify prevention worked] |
 | [pitfall] | Phase [X] | [how to verify prevention worked] |
 
+## Claims
+
+| Claim | Type | Source | Checked |
+|-------|------|--------|---------|
+| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
+
 ## Sources
 
 - [Post-mortems referenced]

package/pan-wizard-core/templates/research-project/stack.md

@@ -79,6 +79,12 @@ npm install -D [packages]
 |-----------|-----------------|-------|
 | [package@version] | [package@version] | [compatibility notes] |
 
+## Claims
+
+| Claim | Type | Source | Checked |
+|-------|------|--------|---------|
+| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
+
 ## Sources
 
 - [Context7 library ID] — [topics fetched]

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

@@ -204,6 +204,16 @@ Things that couldn't be fully resolved:
    - Recommendation: [how to handle]
 </open_questions>
 
+<claims>
+## Claims
+
+Every claim a plan will rest on: a version, an API's behaviour, a price, a security advisory, a practice. One row each, with where it came from and the day it was checked (YYYY-MM-DD). `pan-tools research lint` refuses a claim with no source or no date, and lists as stale a claim older than its type's window (version, pricing, security: 30 days; api: 90; general: 180; practice: 365).
+
+| Claim | Type | Source | Checked |
+|-------|------|--------|---------|
+| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
+</claims>
+
 <sources>
 ## Sources
 

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

@@ -35,10 +35,10 @@ See: .planning/project.md (updated [date])
 - Average duration: [X] min
 - Total execution time: [X.X] hours
 
-**By Phase:**
+**By Plan:** (one row per plan, written by `state record-metric`)
 
-| Phase | Plans | Total | Avg/Plan |
-|-------|-------|-------|----------|
+| Plan | Duration | Tasks | Files |
+|------|----------|-------|-------|
 | - | - | - | - |
 
 **Recent Trend:**
@@ -139,7 +139,7 @@ Progress calculation: (completed plans) / (total plans across all phases) × 100
 Track velocity to understand execution patterns:
 - Total plans completed
 - Average duration per plan
-- Per-phase breakdown
+- Per-plan rows (phase, plan, duration, tasks, files)
 - Recent trend (improving/stable/degrading)
 
 Updated after each plan completion.