pan-wizard 3.34.0 → 3.36.0

package/pan-wizard-core/workflows/new-project.md

@@ -525,9 +525,7 @@ Display spawning indicator:
 Spawn 4 parallel pan-project-researcher agents with path references:
 
 ```
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
-
-<research_type>
+Task(prompt="<research_type>
 Project Research — Stack dimension for [domain].
 </research_type>
 
@@ -563,11 +561,9 @@ Your stack.md feeds into roadmap creation. Be prescriptive:
 Write to: .planning/research/stack.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/stack.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
-
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Stack research")
 
-<research_type>
+Task(prompt="<research_type>
 Project Research — Features dimension for [domain].
 </research_type>
 
@@ -603,11 +599,9 @@ Your features.md feeds into requirements definition. Categorize clearly:
 Write to: .planning/research/features.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/features.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Features research")
 
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
-
-<research_type>
+Task(prompt="<research_type>
 Project Research — Architecture dimension for [domain].
 </research_type>
 
@@ -643,11 +637,9 @@ Your architecture.md informs phase structure in roadmap. Include:
 Write to: .planning/research/architecture.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/architecture.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
-
-Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Architecture research")
 
-<research_type>
+Task(prompt="<research_type>
 Project Research — Pitfalls dimension for [domain].
 </research_type>
 
@@ -683,7 +675,7 @@ Your pitfalls.md prevents mistakes in roadmap/planning. For each pitfall:
 Write to: .planning/research/pitfalls.md
 Use template: ~/.claude/pan-wizard-core/templates/research-project/pitfalls.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Pitfalls research")
 ```
 
 After all 4 agents complete, spawn synthesizer to create summary.md:

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

@@ -280,8 +280,8 @@ Write to: {phase_dir}/{padded_phase}-research.md
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-phase-researcher.md for your role and instructions.\n\n" + research_prompt,
-  subagent_type="general-purpose",
+  prompt=research_prompt,
+  subagent_type="pan-phase-researcher",
   model="{researcher_model}",
   description="Research Phase {phase}"
 )
@@ -383,8 +383,8 @@ Output consumed by /pan:exec-phase. Plans need:
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-planner.md for your role and instructions.\n\n" + filled_prompt,
-  subagent_type="general-purpose",
+  prompt=filled_prompt,
+  subagent_type="pan-planner",
   model="{planner_model}",
   description="Plan Phase {phase}"
 )
@@ -392,12 +392,26 @@ Task(
 
 ## 9. Handle Planner Return
 
-- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
+- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): still run the code checks at the start of step 10 (`verify plan-set`, `verify review-focus`, `verify decisions`; they cost no model call), send any errors back to the planner (step 12), then skip to step 13. Otherwise: step 10.
 - **`## GAP CLOSURE PLANS CREATED`:** (`--gaps` mode) Handle as `## PLANNING COMPLETE`.
 - **`## CHECKPOINT REACHED`:** Present to user, get response, spawn a fresh planner (step 8's Task) with the response added to its prompt
 
 ## 10. Spawn pan-plan-checker Agent
 
+**First, the checks code can make.** Run them before spending a checker:
+
+```bash
+PLAN_SET=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify plan-set "${PHASE_NUMBER}")
+PLAN_SET_EXIT=$?
+REVIEW_FOCUS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify review-focus "${PHASE_NUMBER}")
+REVIEW_FOCUS_EXIT=$?
+DECISIONS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify decisions "${PHASE_NUMBER}")
+DECISIONS_EXIT=$?
+RESEARCH_LINT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs research lint "${PHASE_NUMBER}" 2>/dev/null)
+```
+
+Exit 1 from `verify plan-set` means the plan set is broken in a way no review can wave through: a roadmap requirement no plan lists, two plans in one wave modifying the same file, a `depends_on` that names no plan or a plan in the same or a later wave, or a cycle. Exit 1 from `verify review-focus` means a plan has no `## Review Focus` section, more than five items, or an item that names no owning task or no test. Exit 1 from `verify decisions` means a plan cites a `DD-N` decision the design does not record, or a recorded decision no plan cites (it exits 0 when there is no design, or a design without ids). On any exit 1, send the `errors` of each failing check to the planner as the revision context (step 12; it counts as an iteration) and do not spawn the checker for this set. All exit 0: continue, and pass any `warnings` to the checker. `RESEARCH_LINT` never blocks planning: it goes to the checker as `<research_claims>` (claims with no source or date, and `stale` ones older than their type's window), and is `{"error":"no_research"}` when the phase was not researched.
+
 Display banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -427,6 +441,14 @@ Checker prompt:
 **Project skills:** Check .agents/skills/ directory (if exists) — verify plans account for project skill rules
 </verification_context>
 
+<research_claims>
+{RESEARCH_LINT}
+</research_claims>
+
+<open_findings>
+{output of `pan-tools findings list --phase {phase_number} --agent pan-plan-checker --status open`: empty on the first check; on a re-check, answer each in `resolutions`}
+</open_findings>
+
 <expected_output>
 - ## VERIFICATION PASSED — all checks pass
 - ## ISSUES FOUND — structured issue list
@@ -457,7 +479,7 @@ The fallback reads the heading when the report carries no valid `pan-verdict` bl
 - **`passed`:** Display confirmation, proceed to step 13.
 - **`issues_found`:** Display issues, check iteration count, proceed to step 12.
 
-Each re-check in the revision loop overwrites the same file and is recorded again as the next attempt. The issues a revision resolved are closed by that record.
+Each re-check in the revision loop overwrites the same file and is recorded again as the next attempt. The checker answers each earlier issue in `resolutions`; the record closes the ones it answers `resolved` with evidence, and one it neither reports nor answers stays open.
 
 ## 12. Revision Loop (At Most 2 Revisions, 3 Checks)
 
@@ -491,8 +513,8 @@ Return what changed.
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-planner.md for your role and instructions.\n\n" + revision_prompt,
-  subagent_type="general-purpose",
+  prompt=revision_prompt,
+  subagent_type="pan-planner",
   model="{planner_model}",
   description="Revise Phase {phase} plans"
 )
@@ -524,6 +546,15 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Last Activity" "$
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Last Activity Description" "Phase ${PHASE_NUMBER} planned — ${PLAN_COUNT} plans created"
 ```
 
+**Spend so far and what execution may cost** (`cost.phase_budget_usd`, default $20; it only warns):
+
+```bash
+BUDGET=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs cost budget --phase "${PHASE_NUMBER}" 2>/dev/null)
+FORECAST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs preview phase "${PHASE_NUMBER}" 2>/dev/null)
+```
+
+In the final status, when the budget's `status` is not `off`, add: "Budget: ${spent_usd} of ${budget_usd} spent so far". When `FORECAST`'s `cost_forecast.phase.status` is `ok`, add its p50 and p10–p90, and say so when the p50 alone is above what is left of the budget. When the forecast is `insufficient`, say nothing about it. Never stop or ask on either.
+
 Route to `<offer_next>` OR `auto_advance` depending on flags/config.
 
 **Circular optimization — log plan creation:**
@@ -590,6 +621,7 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Execute Phase ${PHASE}"
 )
 ```

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

@@ -54,7 +54,7 @@ ROADMAP=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap analyze)
 ```
 
 This returns structured JSON with:
-- All phases with disk status (complete/partial/planned/empty/no_directory)
+- All phases with disk status (complete/partial/planned/researched/discussed/empty/no_directory)
 - Goal and dependencies per phase
 - Plan and summary counts per phase
 - Aggregated stats: total plans, summaries, progress percent

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

@@ -229,8 +229,8 @@ Return what changed.
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-planner.md for your role and instructions.\n\n" + revision_prompt,
-  subagent_type="general-purpose",
+  prompt=revision_prompt,
+  subagent_type="pan-planner",
   model="{planner_model}",
   description="Revise quick plan: ${DESCRIPTION}"
 )

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

@@ -72,6 +72,8 @@ This will:
 Proceed? (y/n)
 ```
 
+If an integer target has decimal phases inserted after it (`### Phase {target}.1:` and so on in roadmap.md, or `{target}.N-*` directories), name them in the summary and ask whether to remove them too. pan-tools refuses to remove the integer phase while they exist, because they would be left behind under a different phase's number.
+
 Wait for confirmation.
 </step>
 
@@ -88,6 +90,14 @@ If the phase has executed plans (summary.md files), pan-tools will error. Use `-
 RESULT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase remove "${target}" --force)
 ```
 
+If the phase has decimal phases, pan-tools errors and names them. Add `--with-decimals` only if the user confirmed removing them as well (each is checked for executed plans the same way, so `--force` still applies to them):
+
+```bash
+RESULT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase remove "${target}" --with-decimals)
+```
+
+Otherwise stop and report the decimals; the user can remove them one by one first.
+
 The CLI handles:
 - Deleting the phase directory
 - Renumbering all subsequent directories (in reverse order to avoid conflicts)
@@ -95,7 +105,7 @@ The CLI handles:
 - Updating roadmap.md (removing section, renumbering all phase references, updating dependencies)
 - Updating state.md (decrementing phase count)
 
-Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`.
+Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`, and `removed_decimals` when `--with-decimals` removed any.
 </step>
 
 <step name="commit">

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

@@ -31,6 +31,7 @@ Parse current values (when a key is absent, use PAN's default: `true` for resear
 - `workflow.nyquist_validation` — validation architecture research during plan-phase
 - `model_profile` — which model each agent uses (default: `balanced`)
 - `routing.strategy` — how model tiers are adjusted at runtime (default: `static`)
+- `cost.phase_budget_usd` — spend per phase PAN warns about, in API-equivalent dollars (default: `20`; `0` = off). It never stops a run
 - `branching_strategy` — branching approach (default: `"none"`; a top-level key — a nested `git.branching_strategy` is ignored when the top-level key exists, as it does in every config `config-ensure-section` creates — write the top-level key)
 </step>
 
@@ -112,9 +113,23 @@ AskUserQuestion([
       { label: "Static (Recommended)", description: "Profile assigns fixed tiers to each agent. Predictable and simple." },
       { label: "Complexity", description: "Adjust tiers by task complexity, only where a model is resolved with the task passed (resolve-model --metadata); the *_model values workflows pass are not, so it changes nothing there" }
     ]
+  },
+  {
+    question: "Warn when a phase's spend passes how much? (API-equivalent dollars; warns only, never stops)",
+    header: "Phase budget",
+    multiSelect: false,
+    options: [
+      { label: "$20 per phase (Recommended)", description: "Warn at $16 (80%) and again once a phase passes $20" },
+      { label: "$50 per phase", description: "For larger phases or the quality profile" },
+      { label: "$10 per phase", description: "For small phases or the budget profile" },
+      { label: "Off", description: "No spend warnings; /pan:cost still reports spend" }
+    ]
   }
 ])
 ```
+
+A dollar amount typed under Other is used as given.
+```
 </step>
 
 <step name="update_config">
@@ -129,6 +144,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advanc
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.nyquist_validation <true|false>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set branching_strategy <none|phase|milestone>
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set routing.strategy <static|complexity>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set cost.phase_budget_usd <20|50|10|0|amount>
 ```
 </step>
 
@@ -194,6 +210,7 @@ Display:
 | Nyquist Validation   | {On/Off} |
 | Git Branching        | {None/Per Phase/Per Milestone} |
 | Routing Strategy     | {Static/Complexity} |
+| Phase Budget         | {$N per phase (warn only)/Off} |
 | Saved as Defaults    | {Yes/No} |
 
 These settings apply to future /pan:plan-phase and /pan:exec-phase runs.

package/pan-wizard-core/workflows/todo-check.md

@@ -12,7 +12,8 @@ Read all files referenced by the invoking prompt's execution_context before star
 Load todo context:
 
 ```bash
-INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init todos)
+AREA=""   # the area argument when one was given: /pan:todo-check api → AREA="api"; empty lists every todo
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init todos "$AREA")
 ```
 
 Extract from init JSON: `todo_count`, `todos`, `pending_dir`.
@@ -35,7 +36,7 @@ Exit.
 </step>
 
 <step name="parse_filter">
-Check for area filter in arguments:
+The area filter was applied in init_context (AREA):
 - `/pan:todo-check` → show all
 - `/pan:todo-check api` → filter to area:api only
 </step>

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

@@ -155,6 +155,8 @@ If found, delete them — phase is complete, handoffs are stale.
 TRANSITION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${current_phase}")   # skip when exec-phase invoked this workflow: its `phase complete` already ran — reuse that result
 ```
 
+`phase complete` runs the phase gate first. Exit 1 with `error: phase_gate_refused` (`workflow.phase_gate: enforce`) means the phase was not marked complete: show `gate.reasons` and stop the transition. With `gate.ok` false under `warn`, the phase was marked complete: show the reasons as warnings before continuing.
+
 The CLI handles:
 - Marking the phase checkbox as `[x]` complete with today's date
 - Updating plan count to final (e.g., "3/3 plans complete")
@@ -453,6 +455,7 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Plan Phase ${NEXT_PHASE}"
 )
 ```
@@ -495,6 +498,7 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Discuss Phase ${NEXT_PHASE}"
 )
 ```

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

@@ -85,65 +85,58 @@ This step provides awareness; the hard gate is enforced by exec-phase.
 </step>
 
 <step name="run_test_suite">
-**Run the project's test suite as a verification gate.**
+**Run the project's test suite as a verification gate, through the engine.**
 
-This step catches test regressions that goal-backward analysis cannot detect.
-
-1. Detect whether a test script exists. **This decides `skipped` vs `failed` later**, so
-   it must be answered BEFORE running anything — `npm test` on a project with no `test`
-   script exits non-zero with "Missing script", which is indistinguishable from a crash
-   once you are only looking at the exit code.
+This step catches test regressions that goal-backward analysis cannot detect. The engine
+runs the suite, not you: it finds the project's test command in any language
+(`workflow.test_command` in config.json, else package.json's test script, pytest, `go test
+./...`, cargo, Maven, Gradle or `make test`), reads the runner's own output, compares it with
+the baseline exec-phase recorded before the first wave, and writes the result to the phase
+directory as `{NN}-test-run.json`.
 
 ```bash
-HAS_TEST=$(node -e "try{const p=require('./package.json');process.stdout.write(p.scripts&&p.scripts.test?'yes':'no')}catch(e){process.stdout.write('no')}")
+TEST_RUN=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs test run --phase "${phase_number}")
 ```
 
-   **If `HAS_TEST` is `no`:** record `test_gate_status: skipped` and go to step 4. Do not
-   run the suite, and do not report a crash — there is nothing to run.
+Read from the JSON: `status`, `reason`, `command`, `total`, `passed`, `failed`,
+`regressions`, `preexisting_failures` and `record`.
 
-2. Run test suite and capture results:
-```bash
-TEST_OUTPUT=$(npm test 2>&1)
-TEST_EXIT=$?
-TEST_COUNT=$(echo "$TEST_OUTPUT" | grep -E "^ℹ tests" | awk '{print $NF}')
-TEST_PASS=$(echo "$TEST_OUTPUT" | grep -E "^ℹ pass" | awk '{print $NF}')
-TEST_FAIL=$(echo "$TEST_OUTPUT" | grep -E "^ℹ fail" | awk '{print $NF}')
-```
+**Copy the status; do not judge it.** Write `test_gate: <status>` into the verification.md
+frontmatter exactly as the record says. Reconcile compares the two, so a verification whose
+`test_gate` disagrees with the record is refused at the phase gate, and a failed record
+lowers a `passed` verification to `gaps_found` whatever the frontmatter says.
 
-3. Evaluate results.
+| `status` | What it means | What you do |
+|----------|---------------|-------------|
+| `passed` | The suite ran and nothing that passed at the baseline fails now | Record the counts. If `preexisting_failures` is not empty, list them as known failures the phase inherited, not as gaps |
+| `failed` | A test that passed at the baseline fails now (`regressions`), or the suite did not run at all (a crash, a build error, a timeout: `reason` says `suite did not run`) | Set the overall status to `gaps_found` and list each regression, or the reason, as a gap |
+| `skipped` | There was nothing to run: no test command, or one that ran no tests | Add a `not_checked` entry: `check: "tests"`, `reason:` the record's `reason` |
 
-**Check `TEST_EXIT` FIRST, before any count.** A suite that did not run emits no
-`ℹ fail` line at all, so `TEST_FAIL` comes back EMPTY — not `0`. Reading an empty
-value as "no failures" scores a crashed suite as a pass, which is the worst
-direction this gate can fail in: a phase ships green on a project whose tests never
-executed. Empty is not zero. Judge the exit code, then the counts.
+A suite that exists and did not run is `failed`, never `skipped`: the engine decides that
+from the exit code and the runner's output, and you copy it.
+
+**If test gate FAILED:** Continue verification (gather full picture) but set overall status to `gaps_found` regardless of goal-backward results. Include test failures as gaps in the report.
+</step>
 
-| Condition | Action |
-|-----------|--------|
-| `TEST_EXIT` = 0 **and** `TEST_FAIL` = 0 (a real number) | Record counts, continue to must-haves |
-| `TEST_EXIT` = 0 **and** no `ℹ` count lines (a runner other than Node's built-in one) | Set `test_gate_status: passed`; record the runner's own summary line as the counts |
-| `TEST_EXIT` ≠ 0 **and** failures were reported | Set `test_gate_status: failed`, include failure details |
-| `TEST_EXIT` ≠ 0 **and** `TEST_FAIL` is empty/absent — the suite CRASHED or could not run (syntax error, missing module, bad import, no runner) | Set `test_gate_status: failed`, and record the reason as `suite did not run`. **Never `skipped`, never `passed`.** A suite that cannot execute is stronger evidence of a broken phase than one that runs and fails |
-| `HAS_TEST` = `no` (handled in step 1) | Record as `test_gate_status: skipped`, continue. This is the ONLY legitimate route to `skipped` |
+<step name="mutation_report">
+**Measure whether the tests pin the code the phase wrote** (a report, never a gate).
 
-**The distinction that matters:** *no test command exists* is a project that never had
-tests — a known, acceptable gap. *A test command exists and did not run* is a broken
-project. They must never share a verdict; the first is `skipped`, the second is
-`failed`.
+Only when the test gate passed: a mutant cannot be read against a suite that already fails.
+With `workflow.mutation_gate: off` the command runs nothing and says so.
 
-4. Store test gate results for inclusion in verification.md:
-```
-TEST_GATE_STATUS: passed | failed | skipped
-TEST_TOTAL: ${TEST_COUNT}
-TEST_PASSED: ${TEST_PASS}
-TEST_FAILED: ${TEST_FAIL}
+```bash
+MUTATION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify mutate --phase "${phase_number}" --max 5)
 ```
-   Write `test_gate: ${TEST_GATE_STATUS}` into the verification.md frontmatter. When it is
-   `skipped`, also add a `not_checked` entry (`check: "tests"`, `reason: "no test script in
-   package.json"`). The recorder reads both: a pass whose tests never ran is recorded as a
-   pass with tests not checked, never as a plain pass.
 
-**If test gate FAILED:** Continue verification (gather full picture) but set overall status to `gaps_found` regardless of goal-backward results. Include test failures as gaps in the report.
+The engine flips one comparison, boolean or `+ 1` at a time on the lines the phase's plan
+commits changed, in a throwaway worktree at HEAD, and runs the suite against each mutant. Read
+`checked`, `sampled`, `killed`, `survivors` (file, line, the swap) and `aborted`.
+
+Write a **Test strength** section in verification.md: `killed/sampled`, and each survivor as
+`file:line — before → after`, framed as a test the phase could add. A survivor is a lead, not a
+gap: it never changes the status. `aborted: flaky` (the unmutated suite passed once and failed
+once) is worth reporting as a finding of its own; `checked: false` with its `reason` goes in
+`not_checked` as `check: "mutation"`.
 </step>
 
 <step name="establish_must_haves">
@@ -328,7 +321,7 @@ If human_needed: list items requiring human testing.
 
 Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
 
-**Record the verification.** The record adds its findings to the ledger and logs the outcome to the trace (`verdict_passed`, `verdict_failed` or `verdict_needs_human`). A re-verification is the next attempt, and it closes the gaps it no longer reports:
+**Record the verification.** The record adds its findings to the ledger and logs the outcome to the trace (`verdict_passed`, `verdict_failed` or `verdict_needs_human`). A re-verification is the next attempt. It closes the gaps it lists under `re_verification.gaps_closed`; a gap it neither reports nor answers stays open:
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${phase_number}" --file "$REPORT_PATH" 2>/dev/null || true
 ```

package/scripts/build-help.cjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Generate /pan:help's command index from command frontmatter (program L5).
+ *
+ *   node scripts/build-help.cjs            # print the block
+ *   node scripts/build-help.cjs --write    # rewrite the block in pan-wizard-core/workflows/help.md
+ *   node scripts/build-help.cjs --check    # exit 1 when the committed block is stale
+ *
+ * The block between GENERATED_START and GENERATED_END in help.md lists every
+ * commands/pan/*.md by its frontmatter `group` and `description`, so help cannot leave
+ * a command out. tests/help-generated.test.cjs fails when it is stale.
+ */
+const fs = require('fs');
+const path = require('path');
+const { extractFrontmatter } = require('../pan-wizard-core/bin/lib/frontmatter.cjs');
+
+const ROOT = path.join(__dirname, '..');
+const HELP_REL = path.join('pan-wizard-core', 'workflows', 'help.md');
+const GENERATED_START = '<!-- generated:command-index:start (scripts/build-help.cjs --write) -->';
+const GENERATED_END = '<!-- generated:command-index:end -->';
+
+// The order a new user reads the groups in; groups not listed follow, alphabetically.
+const GROUP_ORDER = [
+  'Getting Started', 'Phase Lifecycle', 'Phase Management', 'Session & Progress',
+  'Milestone', 'Milestone Lifecycle', 'Focus', 'Foresight', 'Review', 'Validation',
+  'Observability', 'Knowledge', 'Self-Improvement', 'Git Workflow', 'Army',
+  'External tools', 'System', 'Community',
+];
+
+/** Every shipped command as {name, group, description}, sorted by name. */
+function readCommands(root = ROOT) {
+  const dir = path.join(root, 'commands', 'pan');
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort().map((f) => {
+    const fm = extractFrontmatter(fs.readFileSync(path.join(dir, f), 'utf-8')) || {};
+    return {
+      // The file name is the command (`/pan:<file>`); some frontmatter names omit the prefix.
+      name: `pan:${f.replace(/\.md$/, '')}`,
+      group: String(fm.group || '').trim(),
+      description: String(fm.description || '').replace(/\s+/g, ' ').trim(),
+    };
+  });
+}
+
+// Backslashes first, so one in a description cannot turn the escaped pipe after it back into a cell break.
+const cell = (s) => s.replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+
+/** The markdown command index, grouped. Throws on a command with no group or description. */
+function renderCommandIndex(commands) {
+  const groups = new Map();
+  for (const c of commands) {
+    if (!c.group) throw new Error(`${c.name} has no group in its frontmatter`);
+    if (!c.description) throw new Error(`${c.name} has no description in its frontmatter`);
+    if (!groups.has(c.group)) groups.set(c.group, []);
+    groups.get(c.group).push(c);
+  }
+  const rank = (g) => { const i = GROUP_ORDER.indexOf(g); return i === -1 ? GROUP_ORDER.length : i; };
+  const order = [...groups.keys()].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+  const out = [];
+  for (const g of order) {
+    out.push(`### ${g}`, '| Command | Description |', '|---------|-------------|');
+    for (const c of groups.get(g).sort((a, b) => a.name.localeCompare(b.name))) out.push(`| \`/${c.name}\` | ${cell(c.description)} |`);
+    out.push('');
+  }
+  return out.join('\n').trimEnd();
+}
+
+/** The generated block's content in a help.md text, or null when the markers are missing. */
+function extractBlock(text) {
+  const t = String(text).replace(/\r\n/g, '\n');
+  const a = t.indexOf(GENERATED_START);
+  const b = t.indexOf(GENERATED_END);
+  if (a === -1 || b === -1 || b < a) return null;
+  return t.slice(a + GENERATED_START.length, b).trim();
+}
+
+/** help.md with its block replaced by `block`. Throws when the markers are missing. */
+function replaceBlock(text, block) {
+  const t = String(text).replace(/\r\n/g, '\n');
+  const a = t.indexOf(GENERATED_START);
+  const b = t.indexOf(GENERATED_END);
+  if (a === -1 || b === -1 || b < a) throw new Error(`${HELP_REL} has no generated command-index markers`);
+  return t.slice(0, a + GENERATED_START.length) + '\n' + block + '\n' + t.slice(b);
+}
+
+function main(argv) {
+  const file = path.join(ROOT, HELP_REL);
+  const block = renderCommandIndex(readCommands(ROOT));
+  if (argv.includes('--write')) {
+    fs.writeFileSync(file, replaceBlock(fs.readFileSync(file, 'utf-8'), block));
+    process.stdout.write(`wrote the command index into ${HELP_REL}\n`);
+  } else if (argv.includes('--check')) {
+    if (extractBlock(fs.readFileSync(file, 'utf-8')) !== block) {
+      process.stderr.write(`${HELP_REL}'s command index is stale: run node scripts/build-help.cjs --write\n`);
+      process.exitCode = 1;
+    } else {
+      process.stdout.write(`${HELP_REL}'s command index is up to date\n`);
+    }
+  } else {
+    process.stdout.write(block + '\n');
+  }
+}
+
+if (require.main === module) main(process.argv.slice(2));
+
+module.exports = { GROUP_ORDER, GENERATED_START, GENERATED_END, readCommands, renderCommandIndex, extractBlock, replaceBlock };

package/scripts/build-hooks.js

@@ -18,6 +18,7 @@ const DIST_DIR = path.join(HOOKS_DIR, 'dist');
 // Hooks to copy (pure Node.js, no bundling needed)
 const HOOKS_TO_COPY = [
   'pan-check-update.js',
+  'pan-guard.js',
   'pan-context-monitor.js',
   'pan-statusline.js',
   'pan-cost-logger.js',

package/scripts/generate-skills-docs.py

@@ -391,11 +391,11 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
                 w(s.description)
                 w("")
             if s.argument_hint:
-                w(f"```")
+                w("```text")
                 w(f"{s.command} {s.argument_hint}")
                 w(f"```")
             else:
-                w(f"```")
+                w("```text")
                 w(f"{s.command}")
                 w(f"```")
             w("")