pan-wizard 3.35.0 → 3.36.0

package/README.md

@@ -364,6 +364,9 @@ The system:
 2. **Fresh context per plan** — a whole context window purely for implementation, zero accumulated garbage (native sub-agent spawning on Claude Code; the other runtimes delegate through their own agent mechanism)
 3. **Commits per task** — Every task gets its own atomic commit (consecutive trivial chore or docs tasks may be coalesced into one)
 4. **Verifies against goals** — Checks the codebase delivers what the phase promised (skipped, and said so, when `workflow.verifier` is off)
+5. **Gates completion** — `phase complete` refuses (the default `workflow.phase_gate: enforce`) when a check fails, such as a plan with no summary, a missing, failing or stale verification, or an open critical or high finding, and lists each reason. `pan-tools phase gate <N>` runs the check alone
+
+After each wave it also reports the phase's spend once it nears or reaches the phase budget (`cost.phase_budget_usd`, $20 by default; a warning, never a stop).
 
 Walk away, come back to completed work with clean git history.
 
@@ -415,7 +418,7 @@ Automated verification checks that code exists and tests pass. `/pan:verify-phas
 
 The system:
 
-1. **Gates on the test suite** — the verifier's protocol sets the verdict to `gaps_found` when the suite fails or cannot run, and the must-have checks still run so the report is complete; the recorder flags a failed gate filed under `passed` (`test_gate_failed_under_pass`) but does not overwrite the status
+1. **Gates on the test suite** — the engine runs the project's tests (`pan-tools test run`) and the verifier copies the result into `test_gate` rather than judging it; the must-have checks still run so the report is complete. A failed gate, in the verification or in the engine's test-run record, lowers a `passed` status to `gaps_found` when the verdict is recorded (`test_gate_failed_under_pass` names the first case); reconcile flags a `test_gate` that disagrees with the record, and the phase gate reports a failed test run as `test_failed`
 2. **Checks every must-have** — each phase promise is verified against the code, not the task list
 3. **Reports the gaps** — a verification report with a per-truth status and the recommended fix plans
 4. **Hands the gaps to the planner** — `/pan:plan-phase N --gaps` writes the fix plans (`gap_closure: true`); `/pan:exec-phase N --gaps-only` runs just those
@@ -535,7 +538,8 @@ The orchestrator never does heavy lifting. It spawns agents, waits, integrates r
 When agents hand work off via files, only OUTPUTS get passed by default — not the reasoning that produced them. Per Cognition's "Don't build multi-agents" research (June 2025), silent decisions force downstream agents to reconcile contradictions blindly. PAN passes the reasoning explicitly:
 
 - Plans carry a `## Plan Decisions` section (Locked / Open / Considered+rejected buckets) — the executor reads it before coding so it doesn't re-argue settled choices.
-- Summaries carry an `## Implementation Decisions` section — the verifier reads it to understand WHY the executor deviated from the plan, not just THAT it did.
+- Summaries carry an `## Implementation Decisions` section — the verifier reads it to understand WHY the executor deviated from the plan, not just THAT it did. An executor unsure of something it finished returns `## DONE_WITH_CONCERNS`, each concern with its cost if wrong, and the reviewer is told to check them.
+- Plans carry a `## Review Focus` section (the untested inputs and failure modes their requirements imply) and cite the design's `DD-N` decisions; `pan-tools verify review-focus` and `pan-tools verify decisions` check both in code, and the reviewer reads the phase's actual diff (`pan-tools review scope`) with that intent beside it.
 
 The plan-checker enforces this with dedicated dimensions for Spec Sufficiency for Handoff and Decision Trace Completeness. Schema lives in `pan-wizard-core/references/handoff-decisions.md`.
 
@@ -653,7 +657,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:settings` | Configure model profile and workflow agents |
+| `/pan:settings` | Configure model profile, workflow agents, branching and the phase budget |
 | `/pan:profile <profile>` | Switch model profile (quality/balanced/budget) |
 | `/pan:todo-add [desc]` | Capture idea for later |
 | `/pan:todo-check` | List pending todos |
@@ -700,8 +704,8 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:cost` | Token usage + estimated cost across PAN invocations (json/table/chart) |
-| `/pan:preview phase <N>\|phases\|milestone` | Read-only foresight: blast radius, dependency graph, milestone ETA |
+| `/pan:cost` | Token usage + estimated cost across PAN invocations (json/table/chart), and `budget`: a phase's spend against its budget (`cost.phase_budget_usd`, $20 by default, warn only; change it with `/pan:settings`); `pan-tools usage` is a local census of which installed commands and agents this project has used |
+| `/pan:preview phase <N>\|phases\|milestone` | Read-only foresight: blast radius, a p10/p50/p90 cost forecast from the project's own cost ledger, dependency graph, milestone ETA |
 | `/pan:review-deep <phase>` | Security audit (OWASP + STRIDE) + cross-check by meta-reviewer |
 | `/pan:knowledge {ask\|discuss\|playbook}` | Grounded Q&A, multi-turn discussion, or aggregate memory into playbook |
 | `/pan:what-if <phase> "scenario"` | Counterfactual phase replay in isolated git worktree |
@@ -730,6 +734,8 @@ PAN stores project settings in `.planning/config.json`. Configure during `/pan:n
 |---------|---------|---------|------------------|
 | `mode` | `yolo`, `interactive` | chosen at `/pan:new-project` (`yolo` is the recommended answer; `--auto` always sets it) | Auto-approve vs confirm at each step |
 | `depth` | `quick`, `standard`, `comprehensive` | chosen at `/pan:new-project` (`--auto` uses `quick` unless the idea document's frontmatter sets `planning_depth`) | Planning thoroughness (phases × plans) |
+| `cost.phase_budget_usd` | dollars, `0` = off | `20` | Spend per phase PAN warns about (API-equivalent dollars): at 80% and once a phase reaches it. Warns only; never stops a run |
+| `workflow.phase_gate` | `enforce`, `warn` | `enforce` (also when the key is absent) | Whether `phase complete` refuses a phase that fails its gate. Override once with `phase complete <N> --force --reason "<why>"`; `warn` completes and reports the reasons |
 
 ### Model Profiles
 

package/agents/pan-designer.md

@@ -55,7 +55,7 @@ Produce `{phase}-design.md` from the template at the `phase` tier:
 
 1. **Problem & scope** — the phase's problem and its fixed boundary.
 2. **Success criteria** — 3–7, **at least 2 machine-checkable**, each naming its automated check.
-3. **Architecture & synthesis** — discovered conventions (cited), components/boundaries (no layer violations), a concrete interface contract, filesystem scope, and a design-decisions table (chosen vs rejected + rationale).
+3. **Architecture & synthesis** — discovered conventions (cited), components/boundaries (no layer violations), a concrete interface contract, filesystem scope, and a design-decisions table (chosen vs rejected + rationale). Record a decision only when it passes the three-question test: hard to reverse once code depends on it, a reasonable engineer could have chosen otherwise, and more than one task or plan depends on it. Give each one an id in the table's first column (`DD-1`, `DD-2` …); plans cite these ids, and `pan-tools verify decisions` flags a citation of an unrecorded id and a recorded decision no plan cites. Leave the rest to the planner.
 4. **Phase-scoped ADR** — context (problem, forces, current state, requirements traceability), decision (numbered sub-decisions with rationale), consequences (positive AND negative, every negative mitigated or explicitly accepted). No placeholder/skeleton sections.
 5. **Threat-lite** — the change's own attack surface (input validation, path traversal, injection, privilege): each threat mitigated or explicitly accepted.
 6. **Test hooks** — how each success criterion is verified; seed inputs for the machine-checkable ones.

package/agents/pan-executor.md

@@ -403,10 +403,15 @@ Write these into the summary's `## Implementation Decisions` section per the sch
 - **Fix:** [what was done]
 - **Files modified:** [files]
 - **Commit:** [hash]
+- **Cost if wrong:** [low | medium | high] — [what breaks, and for whom, if this call was the wrong one]
 ```
 
 Or: "None - plan executed exactly as written."
 
+Every deviation records why you made it and its cost if wrong, including the `DV-N` lines under `## Implementation Decisions`. A reviewer reads the high-cost ones first.
+
+**Concerns:** what you finished but are not sure of, such as an assumption you could not check, a path no test reaches, a deviation whose cost if wrong is high, or a requirement you met only in part. List each under the summary's `## Concerns` as `- C-1: <concern>. Why: <what makes you unsure>. Cost if wrong: <low | medium | high> — <what breaks>.`, or write "None". Do not hide a concern to return a clean result: a concern stated now costs a review, and one found later costs a fix round.
+
 **Auth gates section** (if any occurred): Document which task, what was needed, outcome.
 </summary_creation>
 
@@ -508,6 +513,26 @@ Separate from per-task commits — captures execution results only.
 ```
 
 Include ALL commits (previous + new if continuation agent).
+
+When every task is done but the summary's `## Concerns` lists at least one concern, return `## DONE_WITH_CONCERNS` instead of `## PLAN COMPLETE`. The plan is complete either way; this tells the orchestrator what to look at:
+
+```markdown
+## DONE_WITH_CONCERNS
+
+**Plan:** {phase}-{plan}
+**Tasks:** {completed}/{total}
+**SUMMARY:** {path to summary.md}
+
+**Commits:**
+- {hash}: {message}
+
+**Concerns:**
+- C-1: {concern}. Why: {what makes you unsure}. Cost if wrong: {low | medium | high} — {what breaks}
+
+**Duration:** {time}
+```
+
+A plan you could not finish is not this: return `## CHECKPOINT REACHED` or `## BLOCKED_SPEC_CONFLICT`.
 </completion_format>
 
 <success_criteria>

package/agents/pan-hardener.md

@@ -93,6 +93,8 @@ generated: <ISO timestamp>
 <optional: what you explicitly did NOT audit and why>
 ```
 
+Report every security finding, including ones the project dismissed before. The findings ledger never suppresses a security finding, whoever raised it, so a dismissal never excuses leaving one out.
+
 **Severity scale:**
 - `critical` — remotely reachable with no prerequisites; use sparingly, only when one misuse leads to data loss or remote code execution.
 - `high` — exploitable with typical user privileges; blocks merge by default.

package/agents/pan-phase-researcher.md

@@ -342,6 +342,12 @@ Verified patterns from official sources:
 
 *(If no gaps: "None — existing test infrastructure covers all phase requirements")*
 
+## Claims
+
+| Claim | Type | Source | Checked |
+|-------|------|--------|---------|
+| [what is true] | [version / api / pricing / security / practice / general] | [URL, doc section or Context7 id] | [YYYY-MM-DD] |
+
 ## Sources
 
 ### Primary (HIGH confidence)
@@ -501,6 +507,14 @@ Write to: `$PHASE_DIR/$PADDED_PHASE-research.md`
 
 ⚠️ `commit_docs` controls git only, NOT file writing. Always write first.
 
+**Claims with provenance.** Every fact a plan will rest on (a version, an API's behaviour, a price, a security advisory, a practice) gets a row in `## Claims` with its type, its source and the day you checked it. A claim you could not source is an open question, not a claim. Then lint the file:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs research lint "$PHASE_DIR/$PADDED_PHASE-research.md"
+```
+
+Exit 1 lists claims with no source or no date: fix them before you return. `stale` lists claims older than their type's window (30 days for versions, prices and security, 90 for APIs, 365 for practices): check them again, or say in Open Questions that they were not rechecked.
+
 ## Step 7: Commit Research (optional)
 
 ```bash

package/agents/pan-plan-checker.md

@@ -61,7 +61,7 @@ If context.md exists, add verification dimension: **Context Compliance**
 | Section | How You Use It |
 |---------|----------------|
 | Architecture & interface contract | Plans MUST implement this architecture. Flag if a plan invents a different one or contradicts the interface contract. |
-| Design decisions / ADR | LOCKED — plans must realize these decisions, not re-open them. |
+| Design decisions / ADR | LOCKED — plans must realize these decisions, not re-open them. Decisions carry ids (`DD-N`) that plans cite (Dimension 14). |
 | Success criteria (machine-checkable) | Every machine-checkable criterion must have a task that satisfies it, with its named check. |
 
 If design.md exists, add verification dimension: **Design Conformance**
@@ -525,6 +525,33 @@ issue:
   fix_hint: "Either fill at least one bucket OR replace with the single line 'No decisions worth documenting — plan is mechanical implementation of must_haves.'"
 ```
 
+## Dimension 13: Review Focus
+
+**Question:** Does each plan's `## Review Focus` name the inputs and failure modes its requirements imply that no test covers yet?
+
+The workflow ran `pan-tools verify review-focus` before spawning you, so the structure is already checked: the section exists, it has at most five items (or one `None — <reason>` line), and each item names an existing task and a test. Judge the content:
+
+- Is each item a real input or failure mode the requirements or must_haves imply (an empty list, a duplicate key, a timeout, a malformed file), not a restated task?
+- Does the named task own the code that input reaches, and would the named test fail if that input were mishandled?
+- Did the plan miss an obvious one, such as an error path a requirement names that no task's tests reach? → WARNING
+- Is `None — <reason>` credible for this plan? A plan that parses user input and claims none → WARNING
+
+## Dimension 14: Decision Spine (if design.md exists)
+
+**Question:** Does each plan rely only on decisions the design records?
+
+The workflow ran `pan-tools verify decisions` before spawning you. It already flags a plan citing a `DD-N` id the design does not record, and a recorded decision no plan cites. Judge what code cannot read: a plan that makes a design-level choice (a storage engine, a protocol, a public interface, a dependency) that is neither a recorded `DD-N` nor in context.md's locked decisions relies on an unrecorded decision → BLOCKER, with a fix_hint to cite the decision that covers it, or to send the choice back to `/pan:design-phase`. A choice local to one task is the planner's to make, not a design decision.
+
+## Dimension 15: Research Freshness
+
+**Question:** Do the plans rest on research claims that are unsourced or out of date?
+
+The prompt's `<research_claims>` block is `pan-tools research lint` over the phase's research: `errors` are claims with no source or no checked date, and `stale` lists claims older than their type's window (a version, price or security advisory after 30 days, an API after 90, a practice after 365). For each one a plan relies on (a pinned version, an API call, a price in a budget, a security setting):
+
+- unsourced or undated → WARNING, fix_hint: source it, or move it to Open Questions
+- stale, and the plan's correctness depends on it (a version pinned in a task, an API's behaviour a task assumes) → WARNING, fix_hint: recheck it before execution, or add a task that verifies it
+- stale but incidental to the plans → no issue
+
 </verification_dimensions>
 
 <verification_process>

package/agents/pan-planner.md

@@ -22,7 +22,9 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 
 **Read also:** `~/.claude/pan-wizard-core/references/guardrails.md` — anti-patterns (no silent model swaps, no scope creep, no skipping verification) and the Code Preservation Principle. Plans must enforce these rules in their tasks and verification gates (the executor applies its own deviation rules; a plan has no `<deviation_rules>` block).
 
-**Design input (if present):** If `{phase}-design.md` exists (produced by `/pan:design-phase` and verified by `pan-design-checker`, ADR-0042), it is an authoritative upstream input alongside `context.md`. Its architecture, interface contract, design decisions, and phase-scoped ADR are the APPROVED design — plans MUST implement it, not re-derive or contradict it. Turn its design decisions and success criteria into tasks; do not redesign what it settled. If no design.md exists, plan as before (it is optional, not a gate).
+**Design input (if present):** If `{phase}-design.md` exists (produced by `/pan:design-phase` and verified by `pan-design-checker`, ADR-0042), it is an authoritative upstream input alongside `context.md`. Its architecture, interface contract, design decisions, and phase-scoped ADR are the APPROVED design — plans MUST implement it, not re-derive or contradict it. Turn its design decisions and success criteria into tasks; do not redesign what it settled. Its decisions carry ids (`DD-1`, `DD-2` …): cite the id in each plan that implements one (in `## Plan Decisions`, "Source: design DD-2"). Every recorded decision must be cited by some plan, and a plan must not cite an id the design does not record; `pan-tools verify decisions` checks both. A design-level choice the design does not record (a storage engine, a protocol, a public interface, a new dependency) is not yours to make inside a plan: raise it as a checkpoint or send it back to `/pan:design-phase`. If no design.md exists, plan as before (it is optional, not a gate).
+
+**Review Focus (every plan).** Under `## Review Focus`, name at most five inputs or failure modes the requirements and must_haves imply that no test exercises yet (an empty list, a duplicate key, a timeout, a malformed file), each pinned to the task that owns the code and the test that task adds: `- RF-1: <input>. Test: Task 2 adds <test>.` A plan with none writes one line, `None — <why>`. `pan-tools verify review-focus` refuses a plan without the section, with more than five items, or with an item that names no task or no test. The reviewer reads this section as part of the plan's intent.
 
 **Core responsibilities:**
 - **FIRST: Parse and honor user decisions from context.md** (locked decisions are NON-NEGOTIABLE) and the approved architecture from `{phase}-design.md` if it exists
@@ -453,6 +455,14 @@ Output: [Artifacts created]
 
 <!-- If genuinely none: replace ALL three buckets with the single line:
      "No decisions worth documenting — plan is mechanical implementation of must_haves." -->
+<!-- A Locked decision that implements a design decision cites its id: "Source: design DD-2". -->
+
+## Review Focus
+
+- RF-1: [an input or failure mode the requirements imply that no test exercises yet]. Test: Task [N] adds [the test that would fail if it were mishandled].
+
+<!-- At most five items, each pinned to the task that owns the code. If genuinely none:
+     "None — [why every implied input already has a test]". -->
 
 <execution_context>
 @~/.claude/pan-wizard-core/workflows/execute-plan.md

package/agents/pan-previewer.md

@@ -25,6 +25,7 @@ Your mode is declared in the `<preview_input>` block's `mode` field:
 - `test_files_mentioned` — test files likely to run
 - `risk_signals` — boolean flags for destructive keywords (drop, delete, migrate, rename, breaking, auth)
 - `risk_score` — heuristic 1-10
+- `cost_forecast` — p10/p50/p90 dollars per plan (`per_plan`) and for the whole phase (`phase`), from this project's own cost ledger. Either can be `status: insufficient` with `n`: fewer than five past runs, so there is no forecast
 
 Your output should answer: *"If I run this phase today, what's the blast radius?"* Cover files touched, tests likely to break, migration steps needed, external deps that might need bumping, and a narrative risk assessment.
 
@@ -65,6 +66,7 @@ Write exactly one file at the path provided in your prompt. Use the template at
 - `## Migration steps` (if `risk_signals.migrate`)
 - `## External deps` (if any imports would need version bumps)
 - `## Risk assessment` (narrative — cite specific signals)
+- `## Cost` (the phase's p50 and p10–p90 range in dollars, and per plan; when `insufficient`, say how many runs it has and that five are needed. Never estimate a figure the forecast does not give)
 - `## Bottom line` (**bold one-sentence verdict**)
 
 **For `phases` mode**, output path is `.planning/architecture/dependency-graph.md`. Required sections:

package/agents/pan-project-researcher.md

@@ -506,6 +506,14 @@ In `.planning/research/`, write only the file your prompt's `<output>` block nam
 
 The other researchers write the other dimensions in parallel, and pan-research-synthesizer writes `summary.md` after they all finish. Writing either would overwrite their work.
 
+**Claims with provenance.** Every fact the roadmap or a plan will rest on (a version, an API's behaviour, a price, a security advisory, a practice) gets a row in the file's `## Claims` table with its type, its source and the day you checked it (YYYY-MM-DD). A claim you could not source is an open question, not a claim. Then lint the file you wrote:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs research lint .planning/research/{file}.md
+```
+
+Exit 1 lists claims with no source or no date: fix them before you return. `stale` lists claims older than their type's window: check them again, or name them in your return as not rechecked.
+
 ## Step 6: Return Structured Result
 
 **DO NOT commit.** Spawned in parallel with other researchers. pan-research-synthesizer commits `.planning/research/` after all complete.

package/agents/pan-reviewer.md

@@ -93,6 +93,10 @@ A fixed baseline that applies even when the project documents no standards (Fowl
 
 ## Scope (unrequested work)
 
+When the prompt carries an `<intent>` block (the `review scope` JSON), it is what you judge the change against: each plan's `objective`, `must_haves` and `review_focus` (the risk the planner asked a reviewer to check, so check it first and say what you found), and the text of the requirements the plans claim. Its `unlisted` array names changed files no summary's key-files lists: review them as closely as the rest, and say in the report that the summary did not list them.
+
+When the prompt carries an `<executor_concerns>` block, each entry is something an executor finished but was not sure of, with its cost if wrong. Check the high-cost ones against the code and report what you found: a concern that holds is a finding; one that does not, say so in a sentence.
+
 Compare what the changed code does with what the phase's plans asked for (their tasks and `must_haves`). Code that adds behaviour no plan task or requirement mentions is a finding: a feature nobody asked for, an unrelated refactor folded into the change, or an option no requirement needs. Use category `Unrequested` at WARNING, or at ERROR when it changes existing behaviour without a plan saying so. Its class in the `pan-verdict` block is `unrequested`. Supporting code the tasks need (tests, types, wiring) is not a finding.
 
 </review_checks>
@@ -139,6 +143,7 @@ Return a structured review report:
 - Category maps to class: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Design smell → `quality`, Unrequested → `unrequested`.
 - `where` is `file:line`.
 - A clean review has `"findings": []`.
+- **Dismissed findings are filtered by the recorder, not by you.** When the project dismissed a finding with a reason, recording filters the same finding again for as long as its file is unchanged, and lets it back in once the file changes. Security and logic findings are never filtered. So report everything you find; do not leave out a finding because you think it was dismissed before. To see what is being filtered: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings suppressions --phase {phase_number} --agent pan-reviewer`.
 - **On a re-check you are given `<open_findings>`:** your earlier open findings on this phase, each with its `id`. Answer every one in a `resolutions` list in the block: `{"id":"f_…","status":"resolved","evidence":"what you checked and saw"}` when it is fixed, `still_present` when it is not, `cannot_tell` when you could not check it. A finding you leave out stays open: silence never closes a finding, and `resolved` without evidence closes nothing.
 
 The orchestrator records this block. It is how your findings reach the phase's findings ledger and `/pan:review-deep`.

package/agents/pan-verifier.md

@@ -486,9 +486,9 @@ Unrequested work never changes the status on its own; a phase can pass with it.
 
 ## Step 8b: Run the Test Gate
 
-Run the project's test suite exactly as the verify-phase protocol's `run_test_suite` step says (`~/.claude/pan-wizard-core/workflows/verify-phase.md`): detect a test script first, then run it and judge the exit code before any count. Record the result in the frontmatter as `test_gate: passed | failed | skipped`. `skipped` is only for a project with no test script; a suite that exists and did not run is `failed`.
+Run the test suite through the engine, as the verify-phase protocol's `run_test_suite` step says (`~/.claude/pan-wizard-core/workflows/verify-phase.md`): `pan-tools test run --phase <N>` detects the project's test command in any language, runs it, compares it with the phase's baseline and writes the record. Copy its `status` into the frontmatter as `test_gate: passed | failed | skipped`; do not run the suite yourself and do not re-judge the result. A failed record lowers a `passed` verification whatever you write, and reconcile refuses a `test_gate` that disagrees with it.
 
-A gate you could not run goes in `not_checked` with the reason, e.g. `- check: "tests"` / `reason: "no test script in package.json"`. If the orchestrator already ran the suite and gave you the result, record that result rather than running it again.
+A `skipped` record goes in `not_checked` with the record's reason, e.g. `- check: "tests"` / `reason: "no test command: …"`. If the orchestrator already ran `test run` for this phase and gave you the result, record that result rather than running it again.
 
 ## Step 9: Determine Overall Status
 

package/commands/pan/cost.md

@@ -2,7 +2,7 @@
 name: pan:cost
 group: Observability
 description: Show token usage and estimated cost across PAN commands and agents
-argument-hint: "[report|append|clear|rebuild|limits] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
+argument-hint: "[report|append|clear|rebuild|limits|budget] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
 allowed-tools:
   - Read
   - Bash
@@ -77,6 +77,26 @@ Delete the cost log. Useful at the start of a billing cycle.
 pan-tools cost clear
 ```
 
+### `budget`
+
+A phase's spend against its budget: `cost.phase_budget_usd` in `.planning/config.json`, **20 dollars per phase by default**, `0` to turn it off. Change it with `/pan:settings` or `pan-tools config-set cost.phase_budget_usd 50`. It only warns: `near` from 80% of the budget, `over` once spend reaches it; nothing ever stops on it. exec-phase reports it after each wave and plan-phase in its final status. On a subscription the dollars are API-equivalent (the tokens priced at the rate table).
+
+```
+pan-tools cost budget --phase <N> [--raw]
+```
+
+Prints `{phase, budget_usd, spent_usd, pct, status, mode, warn_at_pct, unpriced}`; `status` is `off`, `ok`, `near` or `over`, and `--raw` prints it. `unpriced` counts the phase's rows with no known rate (not added to the spend).
+
+### `usage` (census)
+
+Which of the installed PAN commands and agents this project has used, from its own files only: the cost ledger and the trace sessions. Nothing is sent anywhere.
+
+```
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs usage [--raw]
+```
+
+Prints `{local_only, commands: {used, never_used, unfinished, installed}, agents: {used, never_used, installed}, sources}`. Each used entry has `calls` and `last_used`, and a command also has `sessions` and `finished`. `unfinished` lists commands that were started but never finished: every trace session for them stopped without ending, the newest more than six hours ago. `--raw` prints a one-line summary. Use it to see which parts of PAN this project actually runs.
+
 ### `limits`
 
 `pan-tools cost limits` shows Claude Code's 5-hour and 7-day usage windows as the status line last saw them, and whether the 7-day one has reached `cost.weekly_limit_stop_pct` (default 90%), where `/pan:focus-auto` and `/pan:army` stop. Interactive Claude Code sessions on a subscription only: headless runs and other runtimes have no reading.

package/commands/pan/preview.md

@@ -31,7 +31,7 @@ Consolidates Spec B v1's architect + simulate + predict-milestone into one entry
 ```
 
 **What it does:**
-1. `pan-tools preview phase <N>` returns `{files_mentioned, test_files_mentioned, risk_signals, risk_score, plans[], status}`.
+1. `pan-tools preview phase <N>` returns `{files_mentioned, test_files_mentioned, risk_signals, risk_score, plans[], status, cost_forecast}`. `cost_forecast` gives p10/p50/p90 dollars per plan (`per_plan`) and for the phase (`phase`) from this project's own cost ledger, or `status: insufficient` with `n` when fewer than five past runs back it.
 2. Spawn `pan-previewer` with the payload as `<preview_input>`.
 3. Agent writes `.planning/phases/<NN-slug>/preview.md` with files touched / tests at risk / migration steps / risk assessment / bottom line.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.35.0",
+  "version": "3.36.0",
   "description": "Command a bot army for your codebase: a reasoning-tier Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"

package/pan-wizard-core/bin/lib/config.cjs

@@ -53,8 +53,12 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       verifier: true,
       nyquist_validation: false,
       phase_record_compact: false,
-      // V1: the phase gate. `warn` reports refusals and completes; `enforce` refuses.
-      phase_gate: 'warn',
+      // V1: the phase gate. `enforce` (the default since V1E) refuses; `warn` reports
+      // refusals and completes.
+      phase_gate: 'enforce',
+      // V5: the mutation report on a phase's diff. `report` lists surviving mutants and
+      // never refuses; `off` skips it; `gate` is reserved for V5G.
+      mutation_gate: 'report',
       // M2: opt-in per-phase HTML reports at the verify→complete gate.
       phase_reports: { enabled: false, open: false, theme: 'auto', index: true },
     },
@@ -62,6 +66,8 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
     // A7: the pre-tool guard. `report` logs to <planning>/guard.jsonl; `enforce` also
     // denies a write that puts a credential in a file; `off` disables it.
     hooks: { guard: 'report' },
+    // Spend per phase, in API-equivalent dollars. It only warns (80% and over); 0 = off.
+    cost: { phase_budget_usd: 20 },
     brave_search: hasBraveSearch,
     budget: {
       default_points: 50,
@@ -102,6 +108,7 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
     ...userDefaults,
     workflow: { ...hardcoded.workflow, ...(userDefaults.workflow || {}) },
     budget: { ...hardcoded.budget, ...(userDefaults.budget || {}) },
+    cost: { ...hardcoded.cost, ...(userDefaults.cost || {}) },
     commit: { ...hardcoded.commit, ...(userDefaults.commit || {}) },
     execution: { ...hardcoded.execution, ...(userDefaults.execution || {}) },
     routing: { ...hardcoded.routing, ...(userDefaults.routing || {}) },
@@ -119,7 +126,7 @@ const CONFIG_KEYS_BEYOND_DEFAULTS = Object.freeze({
   top: Object.freeze(['research', 'plan_checker', 'verifier', 'nyquist_validation', 'mode', 'depth', 'planning', 'git',
     'focus', 'model_overrides', 'effort_overrides', 'cost', 'cache', 'build', 'verification', 'concurrency', 'memory']),
   sections: Object.freeze({
-    workflow: Object.freeze(['auto_advance', 'stop_guard']),
+    workflow: Object.freeze(['auto_advance', 'stop_guard', 'test_command', 'test_file_command']),
     planning: Object.freeze(['commit_docs', 'search_gitignored']),
     git: Object.freeze(['branching_strategy', 'phase_branch_template', 'milestone_branch_template']),
   }),

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

@@ -559,23 +559,28 @@ function isGitRepo(cwd) {
 }
 
 /**
- * Execute a git command safely with proper argument escaping.
+ * Execute a git command safely with proper argument escaping. stdout is trimmed;
+ * `keepLeading` trims only whitespace at its end, for output whose first column means
+ * something (`git status --porcelain` starts an unstaged edit with a space, which a
+ * full trim cuts off the first line).
  * @param {string} cwd - Working directory for git
  * @param {string[]} args - Git arguments (e.g., ['add', 'file.md'])
+ * @param {{keepLeading?: boolean}} [opts]
  * @returns {{exitCode: number, stdout: string, stderr: string}}
  */
-function execGit(cwd, args) {
+function execGit(cwd, args, opts = {}) {
+  const clean = (s) => (opts.keepLeading ? String(s).replace(/\s+$/, '') : String(s).trim());
   try {
     const stdout = execFileSync('git', args, {
       cwd,
       stdio: 'pipe',
       encoding: 'utf-8',
     });
-    return { exitCode: 0, stdout: stdout.trim(), stderr: '' };
+    return { exitCode: 0, stdout: clean(stdout), stderr: '' };
   } catch (err) {
     return {
       exitCode: err.status ?? 1,
-      stdout: (err.stdout ?? '').toString().trim(),
+      stdout: clean((err.stdout ?? '').toString()),
       stderr: (err.stderr ?? '').toString().trim(),
     };
   }

package/pan-wizard-core/bin/lib/cost.cjs

@@ -664,6 +664,146 @@ function aggregate(cwd, opts) {
   };
 }
 
+// ─── Per-phase budget ───────────────────────────────────────────────────────
+// `cost.phase_budget_usd` (default $20, `0`/`false` = off). It only WARNS: `near` from
+// PHASE_BUDGET_WARN_PCT of the budget, `over` once spend reaches it. No run stops on it.
+// On a subscription the dollars are API-equivalent: what the tokens would cost at the
+// configured rates.
+
+const DEFAULT_PHASE_BUDGET_USD = 20;
+const PHASE_BUDGET_WARN_PCT = 80;
+
+function phaseBudgetUsd(cwd) {
+  let v;
+  try { v = loadConfig(cwd)?.cost?.phase_budget_usd; } catch { /* defaults */ }
+  if (v === false || v === 0 || v === '0') return 0;
+  const n = Number(v);
+  return v != null && Number.isFinite(n) && n > 0 ? n : DEFAULT_PHASE_BUDGET_USD;
+}
+
+/**
+ * A phase's spend against its budget.
+ * @returns {{phase, budget_usd, spent_usd, pct, status: 'off'|'ok'|'near'|'over', mode: 'warn', warn_at_pct, unpriced}}
+ */
+function phaseBudget(cwd, phase) {
+  const budget = phaseBudgetUsd(cwd);
+  const rates = effectiveRates(loadConfig(cwd));
+  const key = samePhaseKey(phase);
+  let spent = 0;
+  let unpriced = 0;
+  for (const r of readRecords(cwd)) {
+    if (samePhaseKey(r.phase) !== key || isSuspectRecord(r) || isEmptyRecord(r)) continue;
+    const usd = typeof r.cost_usd === 'number' ? r.cost_usd : computeCost(r, rates);
+    if (typeof usd === 'number') spent += usd;
+    else unpriced++;
+  }
+  spent = round4(spent);
+  const pct = budget > 0 ? Math.round((spent / budget) * 1000) / 10 : null;
+  let status = 'off';
+  if (budget > 0) status = pct >= 100 ? 'over' : pct >= PHASE_BUDGET_WARN_PCT ? 'near' : 'ok';
+  return { phase: String(phase), budget_usd: budget, spent_usd: spent, pct, status, mode: 'warn', warn_at_pct: PHASE_BUDGET_WARN_PCT, unpriced };
+}
+
+function cmdCostBudget(cwd, phase, raw) {
+  if (!phase) error('Usage: cost budget --phase <N>');
+  const r = phaseBudget(cwd, phase);
+  output(r, raw, r.status);
+}
+
+// ─── Cost forecast (program P6) ─────────────────────────────────────────────
+// What a plan and a phase will cost, as p10/p50/p90 dollars, from what this project's
+// agents have cost so far. Fewer than FORECAST_MIN_SAMPLES observations is no
+// forecast: the result says `insufficient` rather than extrapolating from two runs.
+
+const FORECAST_MIN_SAMPLES = 5;
+const FORECAST_ITERATIONS = 2000;
+const PLAN_AGENT = 'pan-executor';
+
+const round4 = (x) => Math.round(x * 10000) / 10000;
+
+/** Linear interpolation between the closest ranks (R type 7). */
+function quantile(sorted, q) {
+  const h = (sorted.length - 1) * q;
+  const lo = Math.floor(h);
+  return sorted[lo] + (sorted[Math.min(lo + 1, sorted.length - 1)] - sorted[lo]) * (h - lo);
+}
+
+function quantiles(values) {
+  const s = [...values].sort((a, b) => a - b);
+  return { p10: round4(quantile(s, 0.1)), p50: round4(quantile(s, 0.5)), p90: round4(quantile(s, 0.9)) };
+}
+
+/** mulberry32: a seeded PRNG, so a forecast is reproducible. */
+function prng(seed) {
+  let a = (Number(seed) >>> 0) || 1;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const samePhaseKey = (p) => String(p == null ? '' : p).replace(/^0+(?=\d)/, '');
+
+/**
+ * Forecast a plan and a phase.
+ *
+ * - Per plan: the cost of each pan-executor call at one tier (the tier the latest
+ *   executor call ran at, unless `tier` is given). Tiers differ several-fold in price,
+ *   so they are never pooled.
+ * - Per phase: for each past phase, the cost of its other agents (planner, checkers,
+ *   verifier, reviewer …); a phase is resampled as one of those plus one executor
+ *   draw per plan, `FORECAST_ITERATIONS` times, seeded.
+ *
+ * @param {string} cwd
+ * @param {{plans?: number, tier?: string, excludePhase?: string, seed?: number}} [opts]
+ */
+function costForecast(cwd, opts = {}) {
+  const rates = effectiveRates(loadConfig(cwd));
+  const exclude = opts.excludePhase != null ? samePhaseKey(opts.excludePhase) : null;
+  const rows = [];
+  for (const r of readRecords(cwd)) {
+    if (isSuspectRecord(r) || isEmptyRecord(r)) continue;
+    if (exclude != null && samePhaseKey(r.phase) === exclude) continue;
+    const usd = typeof r.cost_usd === 'number' ? r.cost_usd : computeCost(r, rates);
+    if (typeof usd === 'number') rows.push({ ...r, usd });
+  }
+  const executor = rows.filter((r) => r.agent === PLAN_AGENT);
+  const tier = opts.tier || (executor.length ? executor[executor.length - 1].tier || null : null);
+  const planCosts = executor.filter((r) => (r.tier || null) === tier).map((r) => r.usd);
+  const parsedPlans = Number.parseInt(opts.plans, 10);
+  const plans = Number.isFinite(parsedPlans) && parsedPlans >= 0 ? parsedPlans : 1;
+  const insufficient = (n) => ({ status: 'insufficient', n, needed: FORECAST_MIN_SAMPLES });
+
+  const perPlan = planCosts.length >= FORECAST_MIN_SAMPLES ? { status: 'ok', n: planCosts.length, ...quantiles(planCosts) } : insufficient(planCosts.length);
+
+  // A past phase is one the executor ran in; its overhead is everything else it spent.
+  const ranIn = new Set(executor.filter((r) => r.phase != null).map((r) => samePhaseKey(r.phase)));
+  const overhead = new Map([...ranIn].map((p) => [p, 0]));
+  for (const r of rows) {
+    const p = samePhaseKey(r.phase);
+    if (r.agent !== PLAN_AGENT && overhead.has(p)) overhead.set(p, overhead.get(p) + r.usd);
+  }
+  const overheads = [...overhead.values()];
+  let phase;
+  if (perPlan.status !== 'ok') phase = { ...insufficient(planCosts.length), n_phases: overheads.length, reason: 'too few executor calls at this tier' };
+  else if (overheads.length < FORECAST_MIN_SAMPLES) phase = { ...insufficient(overheads.length), n_phases: overheads.length, reason: 'too few past phases' };
+  else {
+    const rand = prng(opts.seed == null ? 1 : opts.seed);
+    const pick = (arr) => arr[Math.floor(rand() * arr.length)];
+    const sims = [];
+    for (let i = 0; i < FORECAST_ITERATIONS; i++) {
+      let usd = pick(overheads);
+      for (let k = 0; k < plans; k++) usd += pick(planCosts);
+      sims.push(usd);
+    }
+    phase = { status: 'ok', n_phases: overheads.length, ...quantiles(sims) };
+  }
+  return { agent: PLAN_AGENT, tier, plans, min_samples: FORECAST_MIN_SAMPLES, per_plan: perPlan, phase };
+}
+
 /**
  * Render aggregation as a human-readable table.
  * @param {Object} agg - from aggregate()
@@ -900,6 +1040,12 @@ function cmdModelsCheck(raw) {
 
 module.exports = {
   computeCost,
+  phaseBudget,
+  cmdCostBudget,
+  DEFAULT_PHASE_BUDGET_USD,
+  costForecast,
+  quantiles,
+  FORECAST_MIN_SAMPLES,
   appendRecord,
   readRecords,
   aggregate,

package/pan-wizard-core/bin/lib/doc-lint.cjs

@@ -343,11 +343,13 @@ function scanDocFlags(cwd, opts = {}) {
   const docDirs = opts.docDirs || ['docs'];
   const collected = [];
   for (const d of docDirs) {
-    const abs = path.join(cwd, d);
+    const abs = path.resolve(cwd, d);
     if (!fs.existsSync(abs)) continue;
     for (const f of walkMarkdownFiles(abs)) {
       if (f.readError) continue;
-      collected.push({ rel: path.join(d, f.relativePath).replace(/\\/g, '/'), content: f.content });
+      // Relative to the project root whether --doc-dir was given relative or
+      // absolute, so the frozen-doc allowlist sees project segments only.
+      collected.push({ rel: path.relative(cwd, path.join(abs, f.relativePath)).replace(/\\/g, '/'), content: f.content });
     }
   }
   for (const rel of (opts.files || [])) {
@@ -379,7 +381,7 @@ function scanDocFlags(cwd, opts = {}) {
 
 function cmdDocLintFlags(cwd, opts = {}, raw) {
   for (const d of opts.docDirs || []) {
-    const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
+    const abs = path.resolve(cwd, d);
     if (fs.existsSync(abs)) requireDirectory(abs);
   }
   const r = scanDocFlags(cwd, opts);