pan-wizard 3.34.0 → 3.36.0

package/README.md

@@ -101,7 +101,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 
 - **A human merges.** The Release squad prepares a squash-merge and surfaces an `always-ask` approval instead of merging; pair it with branch protection on your repo, which is what makes that unbypassable rather than merely instructed. Recovery is `git revert` or the previous tag, never a force-push.
 - **Isolated builders.** Each Build agent forks its own `army/<task>` branch + git worktree, so parallel agents never share a file.
-- **Caps.** Delegation-depth cap, per-cycle spawn + budget ceilings, and a `.planning/orchestration/abort` kill-switch, re-checked before every spawn by Mission Control's protocol (prompt-enforced; the MCP `pan_next_action` path enforces the cycle cap, the budget cap when `caps.enforceBudget` is set, an `aborted` flag the caller sets (it does not read the abort file) and the human gate in code — delegation depth is bounded by which agents hold the `Task` tool) — the same harness as hierarchical exec, at campaign scale.
+- **Caps.** Delegation-depth cap, per-cycle spawn + budget ceilings, and a `.planning/orchestration/abort` kill-switch, re-checked before every spawn by Mission Control's protocol (prompt-enforced; the MCP `pan_next_action` path applies the cycle cap, the budget cap (when `caps.enforceBudget` is set) and an `aborted` flag to the counts and caps the caller passes in — it tracks none of them and does not read the abort file; only the merge is gated independently of the caller, by `pan_confirm_merge`'s human approval token — delegation depth is bounded by which agents hold the `Task` tool) — the same harness as hierarchical exec, at campaign scale.
 
 **Run it over days.** `--schedule` arms a resumable campaign with a per-day budget that burns the backlog down across sessions (the per-day budget is advisory unless the schedule is armed with `--enforce-budget`, which pauses the day's run once spent — `campaign status` shows the day's spend — and an external scheduler triggers each `--continue`) — and *still* waits for you at every merge. **Autonomy runs up to the irreversible step; a human is at the step.**
 
@@ -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** — a failing (or non-running) suite forces the verdict to `gaps_found`; the must-have checks still run so the report is complete
+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
@@ -528,14 +531,15 @@ Every stage uses the same pattern: a thin orchestrator spawns specialized agents
 
 The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
 
-**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
+**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays small, because the work happens in fresh subagent contexts. Your session stays fast and responsive.
 
 ### Reasoning-Trace Handoff
 
 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`.
 
@@ -582,7 +586,7 @@ You're never locked in. The system adapts.
 | **Context rot prevention** | Phase-scoped fresh context windows (native sub-agents on Claude Code) | No — context degrades over time | No (Cline: condensing) | No |
 | **Multi-agent** | Specialized agents, parallel waves | Parallel agents in worktrees (Cursor) | Single agent (Cline: subagents) | Custom agents as subagents |
 | **Plan → Verify loop** | Research → plan → verify with iteration | Agent generates plan | Plan mode (Cline) | Plan step |
-| **Post-execution verification** | Auto verifier + human UAT | Iterative error-fix | Manual test runs | Auto-fix loop |
+| **Post-execution verification** | Auto verifier with a test-suite gate (UAT is a template no command runs) | Iterative error-fix | Manual test runs | Auto-fix loop |
 | **Session persistence** | state.md + pause/resume + handoff | Memory tool / transcripts | None / checkpoints (Cline) | Copilot Memory, CLI session recovery |
 | **Runtime support** | Claude Code, OpenCode, Gemini CLI, Codex, Copilot CLI | IDE-locked | Terminal / VS Code | VS Code + CLI |
 | **Zero dependencies** | Yes (Node builtins only) | No (Electron) | No (Python / Node) | No |
@@ -630,7 +634,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:army "<goal>"` | Campaign-scale delivery: Mission Control delegates a whole-project goal to architecture/build/quality/release squads with branch-per-agent worktrees, behind CI + a human merge gate; `--schedule`/`--continue` run it over time |
+| `/pan:army "<goal>"` | Campaign-scale delivery: Mission Control delegates a whole-project goal to architecture/build/quality/release squads with branch-per-agent worktrees, behind CI + a human merge gate (prompt-enforced on `/pan:army`; enforced in code on the MCP path); `--schedule`/`--continue` run it over time |
 
 ### Phase Management
 
@@ -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 |
@@ -662,7 +666,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` fixes the issues it marks repairable |
 | `/pan:hygiene [--apply] [--trace-age-days N] [--all-tracks]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat and stale or expired memory entries, poisoned cost ledgers, trace and report debris, cached-context bloat, fragment planning dirs) and Claude Code's own memory index (reported, never edited); `--apply` executes the safe fixes — poisoned ledgers are quarantined by rename (only the newest quarantine copy is kept), and settled `state.md` history, shipped roadmap phases and stale memory entries are archived rather than dropped |
 | `/pan:links [--strict] [--doc-root <dir>] [--source-root <dir>]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027). The default roots are PAN's own source layout, so pass your project's roots |
-| `/pan:phase-tests <N> [instructions]` | Generate tests for a completed phase based on UAT criteria |
+| `/pan:phase-tests <N> [instructions]` | Generate tests for a completed phase from its summaries, context decisions and verification report |
 | `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
 | `/pan:retro` | Milestone retrospective — estimation accuracy, verification patterns, gap analysis |
 | `/pan:patches` | Restore local modifications after a PAN update |
@@ -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-conductor.md

@@ -51,7 +51,7 @@ Given a phase plan, decompose into **sub-tasks** that correspond to sub-agents:
    - **Executor sub-agents (up to 6):** one per `-plan.md` file that's marked `autonomous: true` in frontmatter. Non-autonomous plans need user checkpoints, which you cannot pause for: do not run them, and list them under "Skipped" in your summary with the instruction to run them with `/pan:exec-phase <N>` (no `--hierarchical`) — nothing runs them after you return.
    - **Reviewer (1):** spawn a `pan-reviewer` after all executors complete, unless `--skip-review` or `--fast` was passed.
    - **Verifier (1):** spawn a `pan-verifier` after the reviewer, unless `workflow.verifier` is false.
-   - Optional hardener + meta-reviewer (2): only if `--deep-review` was also passed.
+   - Optional hardener + meta-reviewer (2): only if `--deep-review` was also passed and the reviewer ran — like exec-phase, skip the deep review under `--skip-review` or `--fast`, since its merge needs the reviewer's report.
 
 3. **Wave grouping:** executors with no cross-plan dependencies can be grouped (within the 12-spawn cap). Sequential executors when `depends_on:` frontmatter indicates.
 
@@ -108,7 +108,7 @@ For each phase execution:
      a. Spawn pan-reviewer (always, unless --skip-review or --fast)
      b. Save its returned report verbatim to {phase_dir}/{phase_number}-review.md (the reviewer is read-only; exec-phase's code_review step saves it the same way), then: pan-tools findings record --phase <N> --agent pan-reviewer --file {phase_dir}/{phase_number}-review.md
 5. After reviewer:
-     a. If --deep-review: spawn pan-hardener (<output_path> .planning/reviews/<N>/hardener.md), then pan-meta-reviewer (<output_path> .planning/reviews/<N>/meta.md)
+     a. If --deep-review and the reviewer ran (not --skip-review/--fast): spawn pan-hardener (<output_path> .planning/reviews/<N>/hardener.md), then pan-meta-reviewer (<output_path> .planning/reviews/<N>/meta.md)
      b. Merge: pan-tools review-deep merge <N> --reviewer-file {phase_dir}/{phase_number}-review.md --hardener-file .planning/reviews/<N>/hardener.md --meta-file .planning/reviews/<N>/meta.md
 6. Spawn pan-verifier — unless `workflow.verifier` is false: then report "verification skipped (workflow.verifier is off)", as exec-phase does
 7. Emit final orchestration summary

package/agents/pan-debugger.md

@@ -830,6 +830,8 @@ gathering -> investigating -> fixing -> verifying -> awaiting_human_verify -> re
                   ^            |           |                 |
                   |____________|___________|_________________|
                   (if verification fails or user reports issue)
+
+goal: find_root_cause_only → gathering -> investigating -> diagnosed (stops there)
 ```
 
 ## Resume Behavior
@@ -1060,7 +1062,7 @@ mv .planning/debug/{slug}.md .planning/debug/resolved/
 
 ```bash
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
-# commit_docs is in the JSON output
+# commit_docs is at .config.commit_docs in the JSON output
 ```
 
 **Commit the fix:**

package/agents/pan-design-checker.md

@@ -90,6 +90,7 @@ contract is in `~/.claude/pan-wizard-core/references/verdict-contract.md`. How t
   `unrequested`, every other dimension → `partial`.
 - Each gap is `high`. A gap you report as a caveat on the final iteration is `medium`.
 - `where` is the design section.
+- **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 the block, so it must say what your verdict says.
 

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

@@ -183,6 +183,23 @@ Only auto-fix issues DIRECTLY caused by the current task's changes. Pre-existing
 - Do NOT fix them
 - Do NOT re-run builds hoping they resolve themselves
 
+**TESTS ARE THE SPEC, NOT AN OBSTACLE:**
+Test files your plan does not list in `files_modified` are read-only. In any test file, never delete or rename a test, add a skip or only marker (`.skip`, `.only`, `xit`, `{ skip: true }`, `@pytest.mark.skip`, `t.Skip`, `#[ignore]`, `@Disabled`), remove an assertion, rewrite an expectation or a snapshot to match what the code now does, or add an assertion that cannot fail. `pan-tools verify test-integrity <phase>` checks the phase's commits for these, and a violation fails the phase gate: exec-phase will not auto-advance, and under `workflow.phase_gate: enforce` the phase cannot be completed without an override.
+
+When a test and your task cannot both be satisfied (the test asserts behaviour the plan changes, or the task is impossible as specified), stop. Do not edit the test. Return:
+
+```markdown
+## BLOCKED_SPEC_CONFLICT
+
+**Plan:** {phase}-{plan}
+**Test:** {file}:{line} — what it asserts
+**Requirement:** the task or requirement it conflicts with
+**Why both cannot hold:** one or two sentences
+**Options:** change the test (needs a plan that declares it) · change the requirement · something else
+```
+
+A person rules on it. Commit the work you finished before stopping.
+
 **FIX ATTEMPT LIMIT:**
 Track auto-fix attempts per task. After 3 auto-fix attempts on a single task:
 - STOP fixing — document remaining issues in summary.md under "Deferred Issues"
@@ -386,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>
 
@@ -453,7 +475,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs requirements mark-complete ${RE
 **State command behaviors:**
 - `state advance-plan`: Increments Current Plan, detects last-plan edge case, sets status
 - `state update-progress`: Recalculates progress bar from summary.md counts on disk
-- `state record-metric`: Appends to Performance Metrics table
+- `state record-metric`: Appends a per-plan row to the Performance Metrics table
 - `state add-decision`: Adds to Decisions section, removes placeholders
 - `state record-session`: Updates Last session timestamp and Stopped At fields
 - `roadmap update-plan-progress`: Updates roadmap.md progress table row with PLAN vs SUMMARY counts
@@ -491,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-experiment-runner.md

@@ -105,7 +105,7 @@ After the run completes, produce a concise structured summary:
 - <e.g., "External session ran a tight 14-cycle focus-auto loop">
 
 ### Recommendation for /pan:learn
-- Run `/pan:learn --experiment <slug>` to extract patterns from the trace.
+- Run `/pan:experiment harvest <slug>`, then `/pan:learn --experiment <slug>` to extract patterns from the trace (learn reads the harvest folder, not the experiment folder).
 - Especially check: <areas of high event density / repeated failures>
 ```
 

package/agents/pan-hardener.md

@@ -12,7 +12,7 @@ You are the PAN hardener. You perform focused security review on files changed d
 
 This is **authorized, defensive** secure-coding review of the user's own codebase — the goal is to find and fix weaknesses before shipping. You report findings for the user to remediate; you never write exploit code, attack tooling, or step-by-step intrusion instructions.
 
-You are spawned by `/pan:review-deep <phase>` or `/pan:exec-phase --deep-review`. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
+You are spawned by `/pan:review-deep <phase>`, `/pan:exec-phase --deep-review`, `/pan:focus-exec --deep-review` (per item, output under `.planning/reviews/<item-id>/`) or `/pan:focus-auto` Pass 3. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
 
 **You NEVER modify source files.** Your one write is the report at the output path your prompt gives. You report findings; the user fixes them.
 
@@ -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-meta-reviewer.md

@@ -15,7 +15,7 @@ You are the PAN meta-reviewer. Your job is to check the first-pass reviewers (`p
 3. **Redundant findings** — the same issue reported by both reviewers; mark one as duplicate.
 4. **Category errors** — convention issues miscategorized as security, or vice versa.
 
-You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports. Your output is merged with theirs by `review-deep.cjs`.
+You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports, or by `/pan:focus-exec --deep-review` with the hardener's report alone (an item has no first-pass review: check the hardener against the diff, and skip the reviewer-side coverage and duplicate checks). Your output is merged with theirs by `review-deep.cjs`.
 
 **You NEVER modify source code.** You produce one findings file. This is authorized, defensive review of the user's own codebase — you adjudicate security findings for remediation; never produce exploit code.
 

package/agents/pan-phase-researcher.md

@@ -142,7 +142,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs websearch "your query" --limit
 
 **Options:**
 - `--limit N` — Number of results (default: 10)
-- `--freshness day|week|month` — Restrict to recent content
+- `--freshness day|week|month|year` — Restrict to recent content
 
 If `brave_search: false` (or not set), use built-in WebSearch tool instead.
 
@@ -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)
@@ -411,7 +417,7 @@ Also read `.planning/config.json` — if `workflow.nyquist_validation` is `true`
 
 Then read context.md if exists:
 ```bash
-cat "$phase_dir"/*-context.md 2>/dev/null
+cat "$PHASE_DIR"/*-context.md 2>/dev/null
 ```
 
 **If context.md exists**, it constrains research:
@@ -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**
@@ -246,8 +246,8 @@ issue:
 ```yaml
 issue:
   dimension: scope_sanity
-  severity: warning
-  description: "Plan 01 has 5 tasks - split recommended"
+  severity: blocker
+  description: "Plan 01 has 5 tasks - split required"
   plan: "01"
   metrics:
     tasks: 5
@@ -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>
@@ -541,11 +568,11 @@ Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
 Orchestrator provides context.md content in the verification prompt. If provided, parse for locked decisions, discretion areas, deferred ideas.
 
 ```bash
-ls "$phase_dir"/*-plan.md 2>/dev/null
+ls "$PHASE_DIR"/*-plan.md 2>/dev/null
 # Read research for Nyquist validation data
-cat "$phase_dir"/*-research.md 2>/dev/null
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$phase_number"
-cat "$phase_dir"/*-design.md 2>/dev/null   # approved design from /pan:design-phase (Design Conformance)
+cat "$PHASE_DIR"/*-research.md 2>/dev/null
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE"
+cat "$PHASE_DIR"/*-design.md 2>/dev/null   # approved design from /pan:design-phase (Design Conformance)
 ```
 
 **Extract:** Phase goal, requirements (decompose goal), locked decisions, deferred ideas.
@@ -660,7 +687,7 @@ Missing: No mention of fetch/API call → Issue: Key link not planned
 ## Step 8: Assess Scope
 
 ```bash
-for plan in "$phase_dir"/*-plan.md; do
+for plan in "$PHASE_DIR"/*-plan.md; do
   grep -cE "<task[ >]" "$plan"   # "<task" alone also counts the <tasks> wrapper; Step 2's task_count is the same number
   grep "files_modified:" "$plan"
 done
@@ -766,6 +793,7 @@ Return all issues as a structured `issues:` YAML list (see dimension examples fo
 - `verdict` is `passed` or `issues_found` (the status from Step 10), and `outcome` is `pass` or `fail`.
 - Add one finding per issue you list. Blocker → `high`, warning → `medium`, info → `info`. The class follows the dimension, as mapped in the reference.
 - `where` is the plan file, plus `#task-N` when the issue is about one task.
+- **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 the block, and the record is what it branches on. The block must say the same thing as your heading.
 
@@ -838,7 +866,7 @@ End it with one finding per listed issue:
 
 ````markdown
 ```pan-verdict
-{"contract":"1.0","agent":"pan-plan-checker","phase":"{phase}","verdict":"issues_found","outcome":"fail","findings":[{"class":"missing","severity":"high","where":"{phase}-01-plan.md","summary":"requirement AUTH-02 (password reset) has no covering task"},{"class":"risk","severity":"medium","where":"{phase}-02-plan.md","summary":"plan 02 modifies 12 files across 5 tasks; split it"}]}
+{"contract":"1.0","agent":"pan-plan-checker","phase":"{phase}","verdict":"issues_found","outcome":"fail","findings":[{"class":"missing","severity":"high","where":"{phase}-01-plan.md","summary":"requirement AUTH-02 (password reset) has no covering task"},{"class":"risk","severity":"high","where":"{phase}-02-plan.md","summary":"plan 02 modifies 12 files across 5 tasks; split it"}]}
 ```
 ````
 

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
@@ -422,6 +424,7 @@ files_modified: []
 autonomous: true
 requirements: []
 user_setup: []
+planned_commit: <sha>
 
 # Goal-backward verification; the Frontmatter Fields table below explains each field
 must_haves:
@@ -452,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
@@ -505,10 +516,11 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-summary.md`
 | `files_modified` | Yes | Files this plan touches |
 | `autonomous` | Yes | `true` if no checkpoints |
 | `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement ID MUST appear in at least one plan. |
+| `planned_commit` | Yes | The output of `git rev-parse HEAD` when you write the plan (omit it outside a git repository) |
 | `user_setup` | No | Human-required setup items |
 | `must_haves` | Yes | Goal-backward verification criteria |
 
-Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter.
+Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter. `pan-tools verify plan-set <phase>` checks the arithmetic before the plan checker runs: every roadmap requirement covered, no two plans in one wave modifying the same file, every `depends_on` naming a plan of this phase in an earlier wave, and no cycles.
 
 ## Interface Context for Executors
 

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

@@ -111,7 +111,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs websearch "your query" --limit
 
 **Options:**
 - `--limit N` — Number of results (default: 10)
-- `--freshness day|week|month` — Restrict to recent content
+- `--freshness day|week|month|year` — Restrict to recent content
 
 If `brave_search: false` (or not set), use built-in WebSearch tool instead.
 
@@ -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-research-synthesizer.md

@@ -59,7 +59,7 @@ cat .planning/research/features.md
 cat .planning/research/architecture.md
 cat .planning/research/pitfalls.md
 
-# Planning config loaded via pan-tools.cjs in commit step
+# The commit step loads the planning config through pan-tools
 ```
 
 Parse each file to extract:

package/agents/pan-reviewer.md

@@ -72,7 +72,7 @@ If a changed file path starts with any of these prefixes, **skip it silently**.
 ## Design smells (baseline)
 
 A fixed baseline that applies even when the project documents no standards (Fowler, *Refactoring*, ch. 3). Rules:
-- Each is a judgement call: always **INFO**, written as "possible <smell>", never a reason for a non-PASS verdict on its own.
+- Each is a judgement call: always **INFO**, written as "possible <smell>", never a reason for a non-PASS verdict on its own; its Category is `Design smell`.
 - **The project wins.** Where a documented project standard, or an established pattern in the code, endorses what a smell would flag, do not report it. Skip anything a linter or formatter already enforces.
 - Only for code this phase changed, and only with a file:line and the hunk that shows it.
 
@@ -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>
@@ -136,9 +140,11 @@ Return a structured review report:
 **Machine verdict (required).** End the report with a `pan-verdict` block. The contract is in `~/.claude/pan-wizard-core/references/verdict-contract.md`. How to fill it:
 - `verdict` is the word under `### Verdict`; `outcome` is `fail` for NEEDS_FIXES and `pass` otherwise.
 - Add one finding per table row. ERROR → `high`, WARNING → `medium`, INFO → `info`.
-- Category maps to class: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Unrequested → `unrequested`.
+- 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

@@ -59,7 +59,7 @@ cat "$PHASE_DIR"/*-verification.md 2>/dev/null
 1. Parse previous verification.md frontmatter
 2. Take `must_haves` (truths, artifacts, key_links) from the plans' frontmatter (Step 2, Option A): the verification frontmatter does not store them
 3. Extract `gaps` (items that failed)
-4. Set `is_re_verification = true`
+4. Set `is_re_verification = true`. In the frontmatter's `re_verification` block, list every earlier gap you re-checked and found closed under `gaps_closed`, by its truth (add `evidence:` under a truth when one line says what you saw), and every gap still failing under `gaps_remaining`. A gap you leave out of both stays open in the findings ledger: silence never closes a gap
 5. **Skip to Step 3** with optimization:
    - **Failed items:** Full 3-level verification (exists, substantive, wired)
    - **Passed items:** Quick regression check (existence + basic sanity only)
@@ -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