pan-wizard 3.35.0 → 3.36.0

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/summary-complex.md

@@ -53,7 +53,7 @@ completed: YYYY-MM-DD
 - 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].
 
 ### Open questions for verifier
 - Q-1: [question]. Why it matters: [stake].
@@ -64,6 +64,10 @@ completed: YYYY-MM-DD
 [Problems during planned work and resolutions — distinct from Deviations above:
  Issues = bugs/blockers fixed; Deviations = intentional departures from plan]
 
+## Concerns
+[What was finished but is not certain, or "None"]
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 ## Next Phase Readiness
 [What's ready for next phase]
 [Blockers or concerns]

package/pan-wizard-core/templates/summary-minimal.md

@@ -44,5 +44,9 @@ completed: YYYY-MM-DD
 [One line each, or this single line if none:
  "No deviations or open questions — implementation followed plan exactly."]
 
+## Concerns
+[What was finished but is not certain, or "None"]
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 ## Next Phase Readiness
 [Ready for next phase]

package/pan-wizard-core/templates/summary-standard.md

@@ -49,7 +49,7 @@ completed: YYYY-MM-DD
 - 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].
 
 ### Open questions for verifier
 - Q-1: [question]. Why it matters: [stake].
@@ -57,5 +57,9 @@ completed: YYYY-MM-DD
 <!-- If none: replace ALL three buckets with:
      "No deviations or open questions — implementation followed plan exactly." -->
 
+## Concerns
+[What was finished but is not certain, or "None"]
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 ## Next Phase Readiness
 [What's ready for next phase]

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

@@ -88,7 +88,7 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 - 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].
 
 ### Open questions for verifier
 - Q-1: [question]. Why it matters: [stake].
@@ -112,6 +112,7 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 - **Fix:** [What was done]
 - **Files modified:** [file paths]
 - **Verification:** [How it was verified]
+- **Cost if wrong:** [low | medium | high] — [what breaks, and for whom, if this call was wrong]
 - **Committed in:** [hash] (part of task commit)
 
 [... repeat for each auto-fix ...]
@@ -124,6 +125,12 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 ## Issues Encountered
 [Problems and how they were resolved, or "None"]
 
+## Concerns
+
+[What was finished but is not certain, or "None". Any entry here means the executor returned DONE_WITH_CONCERNS.]
+
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 [Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
 
 ## User Setup Required

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

@@ -117,6 +117,14 @@ Report:
 | 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
 | 2 | 01-03 | ... |
 ```
+
+**Test baseline.** Before the first wave, record what the test suite does now, so the verifier can tell a failure this phase caused from one it inherited:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs test run --phase "${PHASE_NUMBER}" --baseline > /dev/null
+```
+
+A phase that already has a baseline keeps it (a resumed run or a `--gaps-only` round compares against the phase's start, not its half-built state); the command says `kept_existing: true` and runs nothing. A failing or empty baseline is not a reason to stop: it is what the phase starts from.
 </step>
 
 <step name="execute_waves">
@@ -202,6 +210,8 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
 
+   **An executor that returned `## DONE_WITH_CONCERNS`** finished its plan: run the same spot-checks and treat it as complete. Keep its concerns (each with why and cost if wrong, also under `## Concerns` in its summary) for the wave report and the phase report. Do not stop the wave for them; a high-cost concern is something the review and the verifier should look at, and the phase report puts it in front of the user.
+
    **An executor that returned `## BLOCKED_SPEC_CONFLICT`** found a test it cannot satisfy without weakening it. It is not a failure to retry: show the user its Test, Requirement and Options and ask for a ruling. "Change the test" means a revised plan that declares the test file in `files_modified` (`/pan:plan-phase {N} --gaps` or an edit to the plan), then re-run that plan; "change the requirement" means updating the requirement and the plan. Never re-run the same plan unchanged: it would meet the same test. Declaring the file permits rewriting its expectations; deleting the test, skipping it or dropping assertions still fails `verify test-integrity`, so a ruling to do that also needs `phase complete --force --reason`.
 
    If pass:
@@ -211,7 +221,8 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    **{Plan ID}: {Plan Name}**
    {What was built — from summary.md}
-   {Notable deviations, if any}
+   {Notable deviations, if any, with their cost if wrong}
+   {Concerns, if it returned DONE_WITH_CONCERNS}
 
    {If more waves: what this enables for next wave}
    ---
@@ -229,6 +240,12 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
      2>/dev/null || true
    ```
 
+   Check the phase's spend against its budget (`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)
+   ```
+   When its `status` is `near` or `over`, add one line to the wave report: "Spend: ${spent_usd} of the ${budget_usd} phase budget (${pct}%)", and for `over`, "over budget: the phase keeps running; change the budget with /pan:settings". Do not stop, pause or ask: the budget warns, it never blocks. `ok` and `off` add nothing.
+
    - Bad: "Wave 2 complete. Proceeding to Wave 3."
    - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
 
@@ -323,7 +340,14 @@ After all waves:
 
 ### Issues Encountered
 [Aggregate from SUMMARYs, or "None"]
+
+### Concerns
+[Every concern from the plans that returned DONE_WITH_CONCERNS (and any `## Concerns` entry in a summary), high cost if wrong first:]
+- **03-02** C-1: [concern]. Why: [...]. Cost if wrong: high — [what breaks]
+[Or "None"]
 ```
+
+Concerns go into the review too: the code_review step passes them to the reviewer as `${EXECUTOR_CONCERNS}`, so a high-cost concern is checked rather than only reported.
 </step>
 
 <step name="generate_tests">
@@ -378,13 +402,12 @@ TEST_AFTER=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 
 **Skip if** `--skip-review` or `--fast` flag is present in $ARGUMENTS.
 
-1. Collect changed files from executor summaries:
+1. Collect the review scope: the files the phase's commits changed plus any uncommitted or untracked work, whether or not a summary lists them, and the intent to judge them against:
 ```bash
-# Read each summary.md and extract key-files.created + key-files.modified
-for summary in "$PHASE_DIR"/*-summary.md; do
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$summary" --fields key_files | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const k=JSON.parse(s).key_files||{};for(const f of [...(k.created||[]),...(k.modified||[])])console.log(f)})"
-done | sort -u > /tmp/review-files.txt
+REVIEW_SCOPE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "${PHASE_NUMBER}")
+CHANGED_FILES_LIST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "${PHASE_NUMBER}" --raw)
 ```
+`REVIEW_SCOPE` is JSON. Its `unlisted` array holds the changed files no summary's key-files names. Review them like the others: an executor that changed a file without listing it is exactly what a review must not miss. Its `intent` holds each plan's objective, `must_haves` and Review Focus, and the text of the requirements the plans claim.
 
 2. Collect the reviewer's earlier open findings on this phase (empty on a first review), then spawn pan-reviewer:
 ```bash
@@ -412,6 +435,19 @@ Task(
     Phase directory: ${phase_dir}
     </context>
 
+    <intent>
+    The plans' objectives, must_haves and Review Focus, the requirements they claim,
+    and the changed files no summary listed (review scope JSON):
+    ${REVIEW_SCOPE}
+    </intent>
+
+    <executor_concerns>
+    What the executors finished but were not sure of, each with why and its cost if
+    wrong (from DONE_WITH_CONCERNS returns and the summaries' ## Concerns). Check the
+    high-cost ones first. Empty when there were none:
+    ${EXECUTOR_CONCERNS}
+    </executor_concerns>
+
     <open_findings>
     ${OPEN_REVIEW_FINDINGS}
     </open_findings>
@@ -633,7 +669,7 @@ COMPLETION_EXIT=$?
 | Result | Action |
 |---|---|
 | exit 1, `error: phase_gate_refused` (`workflow.phase_gate: enforce`) | The phase was NOT marked complete. Show each `gate.reasons` entry (`code`: `detail`) with its fix, and stop: no commit, no auto-advance. The user may complete anyway with a reason (below) |
-| exit 0, `gate.ok` false (`warn`, the default) | The phase was marked complete. Show the reasons as warnings, run the rest of this step, and do NOT auto-advance (`offer_next` reads `GATE_OK`) |
+| exit 0, `gate.ok` false (`workflow.phase_gate: warn`) | The phase was marked complete. Show the reasons as warnings, run the rest of this step, and do NOT auto-advance (`offer_next` reads `GATE_OK`) |
 | exit 0, `gate.ok` true | Continue |
 
 **Completing past a refusal** is the user's decision, never yours, and needs their reason. It records a `decision` for every open finding the gate counted:

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

@@ -218,10 +218,12 @@ Proceed with proposed change? (yes / different approach / defer)
 
 Summary MUST include deviations section. None? → `## Deviations from Plan\n\nNone - plan executed exactly as written.`
 
-Per deviation: **[Rule N - Category] Title** — Found during: Task X | Issue | Fix | Files modified | Verification | Commit hash
+Per deviation: **[Rule N - Category] Title** — Found during: Task X | Issue | Fix | Files modified | Verification | Cost if wrong (low, medium or high, and what breaks) | Commit hash
 
 End with: **Total deviations:** N auto-fixed (breakdown). **Impact:** assessment.
 
+Then `## Concerns`: what was finished but is not certain, each as `- C-1: <concern>. Why: <…>. Cost if wrong: <…>.`, or "None". A plan with concerns returns `## DONE_WITH_CONCERNS` (see the executor's completion format).
+
 </deviation_documentation>
 
 <tdd_plan_execution>

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

@@ -209,81 +209,140 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 ## All Commands
 
-> This table is a **curated subset** of the most-used commands, not an exhaustive list. For the full, always-current command set, browse the `commands/pan/*.md` files in your install (each `.md` is one `/pan:<name>` command).
+Every shipped command, by group. This list is generated from each command's own description, so it is complete.
 
+<!-- generated:command-index:start (scripts/build-help.cjs --write) -->
 ### Getting Started
 | Command | Description |
 |---------|-------------|
-| `/pan:new-project` | Initialize new project — research, requirements, roadmap |
-| `/pan:map-codebase` | Analyze existing codebase with parallel agents |
+| `/pan:map-codebase` | Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents |
+| `/pan:new-project` | Initialize a new project with deep context gathering and project.md |
 
 ### Phase Lifecycle
 | Command | Description |
 |---------|-------------|
-| `/pan:discuss-phase <N>` | Shape implementation through targeted questions |
-| `/pan:plan-phase <N>` | Research + plan a phase with verification |
-| `/pan:exec-phase <N>` | Execute plans with wave-based parallelization |
-| `/pan:research-phase <N>` | Deep ecosystem research for specialized domains |
-| `/pan:verify-phase <N>` | Re-run goal-backward verification with a test-suite gate |
+| `/pan:design-phase` | Design a roadmap phase before planning — architecture, ADR, threat-lite, machine-checkable criteria — verified by an independent checker |
+| `/pan:discuss-phase` | Gather phase context through adaptive questioning before planning |
+| `/pan:exec-phase` | Execute all plans in a phase with wave-based parallelization |
+| `/pan:plan-phase` | Create detailed phase plan (plan.md) with verification loop |
+| `/pan:research-phase` | Research how to implement a phase (standalone - usually use /pan:plan-phase instead) |
+| `/pan:verify-phase` | Re-run goal-backward verification of a phase with a test-suite gate and list its gaps |
 
 ### Phase Management
 | Command | Description |
 |---------|-------------|
-| `/pan:add-phase <desc>` | Append new phase to roadmap |
-| `/pan:insert-phase <N> <desc>` | Insert urgent work between phases |
-| `/pan:remove-phase <N>` | Remove phase and renumber |
-| `/pan:assumptions <N>` | Surface approach assumptions before planning |
-| `/pan:phase-tests <N>` | Generate tests for completed phase |
-| `/pan:phase-budget` | Estimate context utilization for current phase |
+| `/pan:add-phase` | Add phase to end of current milestone in roadmap |
+| `/pan:assumptions` | Surface Claude's assumptions about a phase approach before planning |
+| `/pan:insert-phase` | Insert urgent work as decimal phase (e.g., 72.1) between existing phases |
+| `/pan:phase-budget` | Estimate context utilization and quality for the current phase |
+| `/pan:phase-tests` | Generate tests for a completed phase from its summaries, context decisions, verification report and implementation |
+| `/pan:remove-phase` | Remove a future phase from roadmap and renumber subsequent phases |
 
 ### Session & Progress
 | Command | Description |
 |---------|-------------|
-| `/pan:progress` | Check status and route to next action |
-| `/pan:quick <desc>` | Fast-path execution (skip optional agents) |
-| `/pan:pause` | Save context for later resumption |
-| `/pan:resume` | Restore previous session context |
-| `/pan:profile <name>` | Switch model profile (quality/balanced/budget) |
+| `/pan:pause` | Create context handoff when pausing work mid-phase |
+| `/pan:profile` | Switch model profile for PAN agents (quality/balanced/budget) |
+| `/pan:progress` | Check project progress, show context, and route to next action (execute or plan) |
+| `/pan:quick` | Execute a quick task with PAN guarantees (atomic commits, state tracking) but skip optional agents |
+| `/pan:resume` | Resume work from previous session with full context restoration |
 
 ### Milestone
 | Command | Description |
 |---------|-------------|
-| `/pan:milestone-new` | Start a new milestone cycle |
-| `/pan:milestone-done <v>` | Archive completed milestone |
-| `/pan:milestone-audit` | Audit completion against intent |
-| `/pan:milestone-gaps` | Create phases to close audit gaps |
-| `/pan:milestone-cleanup` | Archive accumulated phase directories |
-| `/pan:retro` | Milestone retrospective — estimation & verification analysis |
-
-### Focus (Strategic Project Management)
+| `/pan:milestone-audit` | Audit milestone completion against original intent before archiving |
+| `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
+| `/pan:milestone-done` | Archive completed milestone and prepare for next version |
+| `/pan:milestone-gaps` | Create phases to close all gaps identified by milestone audit |
+| `/pan:milestone-new` | Start a new milestone cycle — update project.md and route to requirements |
+
+### Milestone Lifecycle
+| Command | Description |
+|---------|-------------|
+| `/pan:retro` | Milestone retrospective — analyze estimation accuracy, verification patterns, and common gaps |
+
+### Focus
+| Command | Description |
+|---------|-------------|
+| `/pan:focus-auto` | Continuous scan-plan-exec loop with purpose-driven categories and a layered safety harness |
+| `/pan:focus-design` | Strategic 10-phase feature investigation, design, and specification pipeline |
+| `/pan:focus-doc-audit` | Multi-dimensional document audit — accuracy, freshness, links, cross-consistency, and structural quality |
+| `/pan:focus-drift-walking` | Deep documentation-code drift detection, CLAUDE.md alignment, and auto-repair across all project directories |
+| `/pan:focus-exec` | Automated batch execution pipeline with 6 stages, behavioral rules, 3 execution tiers |
+| `/pan:focus-plan` | Create capacity-budgeted work batch with spec coverage verification and 4 execution modes |
+| `/pan:focus-scan` | Deep-dive strategic work scan with prioritized items and Reality Score filtering |
+| `/pan:focus-sync` | Synchronize documentation after changes — check staleness and update counts |
+
+### Foresight
+| Command | Description |
+|---------|-------------|
+| `/pan:preview` | Preview what will happen — phase blast radius, phase dependency graph, or milestone ETA |
+| `/pan:what-if` | Explore a phase's alternative approach in an isolated git worktree. Replays the scenario, compares to the original plan, writes a report. |
+
+### Review
+| Command | Description |
+|---------|-------------|
+| `/pan:review-deep` | Security audit + cross-reviewer check. OWASP/STRIDE pass by pan-hardener, then pan-meta-reviewer catches what the first pass missed. Writes consolidated deep-review.md. |
+
+### Validation
+| Command | Description |
+|---------|-------------|
+| `/pan:links` | Validate the doc-code link graph — inline wiki-style refs, source-comment anchors, and require-code-mention contracts (ADR-0027, v3.8.0+) |
+
+### Observability
+| Command | Description |
+|---------|-------------|
+| `/pan:cost` | Show token usage and estimated cost across PAN commands and agents |
+| `/pan:dashboard` | Alias for /pan:hud — generate the single-page HTML dashboard of the bot army and project |
+| `/pan:hud` | Generate a single-page, self-contained HTML dashboard of the bot army and the project's current state |
+| `/pan:report` | Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report |
+
+### Knowledge
+| Command | Description |
+|---------|-------------|
+| `/pan:knowledge` | Grounded Q&A, multi-turn design discussion, and playbook generation. Three modes in one command. |
+
+### Self-Improvement
+| Command | Description |
+|---------|-------------|
+| `/pan:experiment` | Manage external experiments — scaffold, run, harvest, promote findings back to PAN |
+| `/pan:learn` | Analyze trace sessions or harvested experiments via pan-optimizer; generate ranked optimization reports |
+| `/pan:optimize` | Manage the circular optimization loop — record a report's suggestions, undo them, view stats, list reports, manage trace sessions |
+
+### Git Workflow
+| Command | Description |
+|---------|-------------|
+| `/pan:git` | Safe, phase-aware git workflow commands — commit, branch, push, status, log, stash, diff, rollback, tag, sync |
+
+### Army
+| Command | Description |
+|---------|-------------|
+| `/pan:army` | Bot-army campaign — Mission Control (the reasoning-tier conductor) delegates a whole-project goal to squads (architecture / build / quality / release), each squad working branch-per-agent worktrees under a hard safety harness, gated by CI + a human merge, looping plan→delegate→execute→review→integrate→learn until the goal ships or a stop condition fires. |
+
+### External tools
 | Command | Description |
 |---------|-------------|
-| `/pan:focus-scan` | Step 1: Find and prioritize all work items |
-| `/pan:focus-plan` | Step 2: Budget items into an execution batch |
-| `/pan:focus-exec` | Step 3: Implement, test, verify, commit |
-| `/pan:focus-sync` | Step 4: Synchronize documentation after changes |
-| `/pan:focus-auto` | Continuous scan→plan→exec loop with safety harness |
-| `/pan:focus-design <desc>` | Standalone: Deep feature investigation and spec |
-| `/pan:focus-drift-walking` | Walk project tree, detect doc-code drift, auto-repair |
-| `/pan:focus-doc-audit` | Deep document audit with quality scoring |
+| `/pan:mcp-bridge` | Discover available MCP tools and recommend which ones apply to a phase. Discovery-only; auto-invocation deferred. |
 
 ### System
 | Command | Description |
 |---------|-------------|
-| `/pan:help` | Show this reference |
-| `/pan:health` | Diagnose planning directory integrity |
-| `/pan:settings` | Configure workflow toggles |
-| `/pan:update` | Update PAN to latest version |
-| `/pan:debug` | Systematic debugging with persistent state |
-| `/pan:todo-add` | Capture idea as todo |
-| `/pan:todo-check` | List and select pending todos |
-| `/pan:audit-deployment <dir>` | Audit a PAN installation for integrity and health |
+| `/pan:audit-deployment` | Audit a PAN Wizard deployment — verify installation integrity, project health, and draft enhancement specs |
+| `/pan:debug` | Systematic debugging with persistent state across context resets |
+| `/pan:health` | Diagnose planning directory health and optionally repair issues |
+| `/pan:help` | Show available PAN commands and usage guide |
+| `/pan:hygiene` | Scan the project for PAN version drift and stale artifacts (legacy filenames, memory bloat and stale entries, poisoned ledgers, trace debris, oversized planning files) and apply safe cleanups |
+| `/pan:patches` | Reapply local modifications after a PAN update |
+| `/pan:settings` | Configure PAN workflow toggles and model profile |
+| `/pan:todo-add` | Capture idea or task as todo from current conversation context |
+| `/pan:todo-check` | List pending todos and select one to work on |
+| `/pan:update` | Update PAN to latest version with changelog display |
 
 ### Community
 | Command | Description |
 |---------|-------------|
 | `/pan:discord` | Join the PAN Discord community |
-| `/pan:patches` | Reapply local modifications after update |
+<!-- generated:command-index:end -->
 
 ---
 

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

@@ -392,7 +392,7 @@ Task(
 
 ## 9. Handle Planner Return
 
-- **`## 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`; they cost no model call), send any errors back to the planner (step 12), then 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
 
@@ -403,9 +403,14 @@ Task(
 ```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 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. Send `PLAN_SET`'s `errors` to the planner as the revision context (step 12; it counts as an iteration) and do not spawn the checker for this set. Exit 0: continue, and pass any `warnings` to the checker.
+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:
 ```
@@ -436,6 +441,10 @@ 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>
@@ -537,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:**

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.