pan-wizard 3.35.0 → 3.37.0

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

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

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

@@ -4,7 +4,7 @@ Template for `.planning/phases/XX-name/discovery.md` - shallow research for libr
 
 **Purpose:** Answer "which library/option should we use" questions when a phase needs a quick option comparison before planning.
 
-For deep ecosystem research ("how do experts build this"), use `/pan:research-phase` which produces research.md.
+For deep ecosystem research ("how do experts build this"), use `/pan:plan-phase --research-only` which produces research.md.
 
 ---
 
@@ -142,5 +142,5 @@ Create `.planning/phases/XX-name/discovery.md`:
 - Niche/complex domains (3D, games, audio, shaders)
 - Need ecosystem knowledge, not just library choice
 - "How do experts build this" questions
-- Use `/pan:research-phase` for these
+- Use `/pan:plan-phase --research-only` for these
 </guidelines>

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

@@ -71,6 +71,13 @@ Output: [What artifacts will be created]
 ### Considered and rejected
 - R-1: [alternative]. Rejected because: [reason].
 
+<!-- A Locked decision that implements a design decision cites its id: "Source: design DD-2". -->
+
+## Review Focus
+<!-- At most five inputs or failure modes the requirements imply that no test exercises yet,
+     each pinned to the task that owns the code. If genuinely none: "None — [why]". -->
+- RF-1: [input or failure mode]. Test: Task [N] adds [test that fails if it is mishandled].
+
 <tasks>
 
 <task type="auto">

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

@@ -17,6 +17,9 @@ Requirements for initial release. Each maps to roadmap phases.
 ### Authentication
 
 - [ ] **AUTH-01**: User can sign up with email and password
+  - WHEN a visitor submits a new email and a valid password THE SYSTEM SHALL create the account
+  - IF the email is already registered THEN THE SYSTEM SHALL refuse the sign-up without revealing the account
+  - Test: tests/auth/signup.test.ts
 - [ ] **AUTH-02**: User receives email verification after signup
 - [ ] **AUTH-03**: User can reset password via email link
 - [ ] **AUTH-04**: User session persists across browser refresh
@@ -74,6 +77,12 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 </template>
 
+<ears_criteria>
+Each v1 requirement carries at least one acceptance criterion as an indented sub-bullet in an EARS form: `WHEN <trigger> THE SYSTEM SHALL <response>`, `WHILE <state> …`, `WHERE <feature> …`, `IF <unwanted condition> THEN THE SYSTEM SHALL …`, or `THE SYSTEM SHALL …`. `pan-tools verify requirements` fails a v1 requirement with none.
+
+The tests that check a requirement go in `Test:` sub-bullets as the plans add them. `pan-tools verify traceability` runs them. A criterion with no mapped test reads `not_checked`, never met, and `phase complete` ticks a requirement only when its mapped tests pass. A requirement with no criteria at all is treated as legacy and keeps the old tick.
+</ears_criteria>
+
 <guidelines>
 
 **Requirement Format:**

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

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

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

@@ -53,7 +53,7 @@ completed: YYYY-MM-DD
 - DT-1: Chose [option] for O-N. Reason: [rationale].
 
 ### Deviations (from plan; must explain)
-- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable].
+- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable]. Cost if wrong: [low | medium | high] — [what breaks].
 
 ### Open questions for verifier
 - Q-1: [question]. Why it matters: [stake].
@@ -64,6 +64,10 @@ completed: YYYY-MM-DD
 [Problems during planned work and resolutions — distinct from Deviations above:
  Issues = bugs/blockers fixed; Deviations = intentional departures from plan]
 
+## Concerns
+[What was finished but is not certain, or "None"]
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 ## Next Phase Readiness
 [What's ready for next phase]
 [Blockers or concerns]

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

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

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

@@ -49,7 +49,7 @@ completed: YYYY-MM-DD
 - DT-1: Chose [option] for O-N. Reason: [rationale].
 
 ### Deviations (from plan; must explain)
-- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable].
+- DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable]. Cost if wrong: [low | medium | high] — [what breaks].
 
 ### Open questions for verifier
 - Q-1: [question]. Why it matters: [stake].
@@ -57,5 +57,9 @@ completed: YYYY-MM-DD
 <!-- If none: replace ALL three buckets with:
      "No deviations or open questions — implementation followed plan exactly." -->
 
+## Concerns
+[What was finished but is not certain, or "None"]
+- C-1: [concern]. Why: [what makes it uncertain]. Cost if wrong: [low | medium | high] — [what breaks].
+
 ## Next Phase Readiness
 [What's ready for next phase]

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

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

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

@@ -60,13 +60,11 @@ Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
 <step name="update_project_state">
 Update state.md to reflect the new phase:
 
-1. Read `.planning/state.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {N} added: {description}
-   ```
+Append the entry under "## Accumulated Context" → "### Roadmap Evolution" (the engine creates the section when it is missing):
 
-If "Roadmap Evolution" section doesn't exist, create it.
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state section "Roadmap Evolution" --append "- Phase {N} added: {description}"
+```
 </step>
 
 <step name="completion">

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

@@ -1,7 +1,7 @@
 <purpose>
 Surface Claude's assumptions about a phase before planning, enabling users to correct misconceptions early.
 
-Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. No file output - purely conversational to prompt discussion.
+Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. The conversation ends with one file, `{phase_dir}/{phase_num}-assumptions.md`, holding the assumptions and the user's corrections, so discuss-phase and plan-phase start from them instead of losing them with the session.
 </purpose>
 
 <process>
@@ -145,6 +145,24 @@ This changes my understanding significantly. [Summarize new understanding]
 Assumptions validated.
 ```
 
+**Either way, save them.** Write `{phase_dir}/{phase_num}-assumptions.md` once, in full:
+
+```markdown
+# Phase {phase_num}: Assumptions
+
+**Reviewed:** {date}
+
+## Assumptions
+
+- {each assumption, as presented}
+
+## Corrections
+
+- {each correction, in the user's words; "None: the user confirmed the assumptions" when there were none}
+```
+
+`init phase-op` reports it as `assumptions_path`; discuss-phase and plan-phase read it. Commit it with the phase's docs when `commit_docs` is on.
+
 Continue to offer_next.
 </step>
 

package/pan-wizard-core/workflows/diagnose-issues.md

@@ -98,6 +98,8 @@ Template placeholders (see `debug-subagent-prompt.md`):
 - `{timeline}`: "Discovered during UAT"
 - `{true_or_false}`: `true` (symptoms are prefilled from the UAT gap)
 - `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
+
+Each gap gets its own reproduction, one per requirement or UAT truth it breaks (the debugger records `requirement:` beside the command). That command is the gap's closing check: the fix plan from `/pan:plan-phase --gaps` is done only when `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs debug repro <slug>` turns green.
 - `{slug}`: Generated from the issue summary
 </step>
 

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

@@ -116,7 +116,9 @@ Phase number from argument (required).
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE}")
 ```
 
-Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`.
+Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`, `assumptions_path`.
+
+**If `assumptions_path` is set**, read it first: it holds the assumptions `/pan:assumptions` surfaced and the user's corrections to them. Treat each correction as already decided; do not ask it again.
 
 **If `phase_found` is false:**
 ```
@@ -283,7 +285,7 @@ Analyze the phase to identify gray areas worth discussing.
 
 1. **Domain boundary** — What capability is this phase delivering? State it clearly.
 
-2. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation.
+2. **Gray areas by category**: scan the phase against the `<clarification_taxonomy>` in `references/questioning.md` (scope, users, behaviour, data, interfaces, errors and edge cases, non-functional, constraints, done), plus UI, UX, empty states and content for a user-facing phase. Identify the specific ambiguities that would change implementation, then keep to the `<question_budget>`: at most five questions, ranked by impact × uncertainty, and every ambiguity you do not ask about written into context.md as an `Assumed:` line the user can correct.
 
 3. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), the phase may not need discussion.
 

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

@@ -0,0 +1,69 @@
+<purpose>
+Execute a lean phase in this one session: you do the work the executor agent would do, then one reviewer pass and a verifier check it. Autodev runs this for a phase the engine sized lean (its requirements say precisely what to build, and the engine wrote and checked its plan), so the full exec-phase orchestration (an orchestrating session, a separate executor, test generation) is not needed. The reviewer stays: on the brief test (2026-10-25) a lean build and a bare host's build each carried one high-severity defect the hidden checks could not see, and the reviewer found both. The phase gate still decides when autodev runs `phase complete`.
+</purpose>
+
+<rules>
+- **The plan is the specification.** Do what each task's `<action>` says, nothing more. Do not widen scope; log anything else to `{phase_dir}/deferred-items.md`.
+- **Tests are the spec.** Test files the plan does not list in `files_modified` are read-only. Never delete, rename or skip a test, remove an assertion, or add one that cannot fail. A plan's `supersedes_tests` are the exception it declares: update their expectations to what the named requirements now require, and record each change as a deviation. A test you cannot satisfy without weakening it means stop and reply `## BLOCKED_SPEC_CONFLICT` with the test, the requirement and why both cannot hold.
+- **Commit each task** when its verify command passes: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "feat({padded}-{plan}): <what the task did>" --files <the files it changed>`.
+- **Unattended:** do not ask questions; take the recommended default and record what you assumed in the summary. Do not start another phase or command.
+</rules>
+
+<process>
+1. **Load the phase:**
+   ```bash
+   INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "{phase}")
+   ```
+   Read `phase_dir`, `phase_number`, `incomplete_plans`, `plan_check` and `verifier_enabled`. When `plan_check.status` is not `ok` or `disabled`, stop and reply `EXECUTION HALTED: plan check {status}`.
+
+2. **Record the test baseline** (what the suite does before this phase):
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs test run --phase "{phase_number}" --baseline > /dev/null
+   ```
+
+3. **Execute each incomplete plan, in order.** Read the plan. For each task: make the change, write or update the tests its action names, run its `<verify>` command until it passes (at most three fix attempts, then record the task as an issue and continue), and commit it. Then write `{phase_dir}/{padded}-{plan}-summary.md` from `~/.claude/pan-wizard-core/templates/summary.md`: what was built, the files, every deviation (including each superseded test expectation: file, what it asserted, what it asserts now, which requirement) and every assumption. Then record progress and commit the summary:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state advance-plan
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update-progress
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap update-plan-progress "{phase_number}"
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs requirements mark-complete {the plan's requirements}
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs({padded}-{plan}): complete plan" --files {phase_dir}/{padded}-{plan}-summary.md .planning/state.md .planning/roadmap.md .planning/requirements.md
+   ```
+
+4. **Review.** One pass of the code reviewer over what the phase changed; it looks for what the tests and the verifier do not (a save that is not crash-safe, unchecked arithmetic, state left wrong after an error). Collect the scope, then spawn it:
+   ```bash
+   REVIEW_SCOPE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "{phase_number}")
+   CHANGED_FILES_LIST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "{phase_number}" --raw)
+   ```
+   ```
+   Task(
+     subagent_type="pan-reviewer",
+     model="{reviewer_model from: node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-reviewer --raw}",
+     prompt="<objective>Review the code changed in phase {phase_number} for defects: behaviour that contradicts the requirements, data loss or corruption (including a crash mid-write), inputs that must throw and do not, state left wrong after an error, security problems. Real defects only, each with a concrete input that shows it.</objective> <files_to_read>./CLAUDE.md (if it exists); changed files: ${CHANGED_FILES_LIST}</files_to_read> <intent>${REVIEW_SCOPE}</intent> <executor_concerns>{what you finished but were not sure of, with why; empty when none}</executor_concerns>"
+   )
+   ```
+   Write its returned text, verbatim and in full with its `pan-verdict` block, to `{phase_dir}/{phase_number}-review.md` (the reviewer is read-only), then record it:
+   ```bash
+   REVIEW_VERDICT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase_number}" --agent pan-reviewer --file "{phase_dir}/{phase_number}-review.md" --raw)
+   ```
+   `PASS`: go on. `PASS_WITH_WARNINGS`: go on, recording that the phase continues past them:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "{phase_number}" --agent pan-reviewer --open --as deferred --reason "accepted at review: PASS_WITH_WARNINGS"
+   ```
+   `NEEDS_FIXES`: fix each ERROR finding (the tests stay the spec: a fix adds a test for the defect, never weakens one), commit the fixes as `fix({padded}): review findings`, and run the review once more. A second `NEEDS_FIXES` does not loop: record what stays open with `findings dispose ... --as deferred --reason "open after one fix round (unattended)"`, go on to verification, and name those findings in the reply. Never continue past findings silently: an open finding without a recorded reason is what the milestone audit cannot see.
+
+5. **Verify** (skip only when `verifier_enabled` is false, and say so). Spawn the verifier; it is a second pair of eyes, so give it paths, not your conclusions:
+   ```
+   Task(
+     subagent_type="pan-verifier",
+     model="{verifier_model from: node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-verifier --raw}",
+     prompt="Verify phase {phase_number} goal achievement. Phase directory: {phase_dir}. Check the plans' must_haves and requirement IDs against the code. Run the project's test suite as the test gate and record test_gate in the frontmatter. Create verification.md."
+   )
+   ```
+   Then record its verdict:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase_number}" --file "$(ls {phase_dir}/*-verification.md | head -1)" --raw
+   ```
+
+6. **Reply** in a few lines: the plans executed, the commits, the review verdict and any finding left open, the verification status, and any deviation, assumption or issue. Do not run `phase complete`: autodev runs it next and the phase gate decides.
+</process>

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

@@ -52,6 +52,14 @@ Parse JSON for: `executor_model`, `verifier_model`, `reviewer_model`, `commit_do
 
 **Drift.** For each `plan_drift` entry, tell the executor of that plan, in its prompt, which of its `files_modified` changed since it was planned (`files`), so it re-reads them before editing. An entry with `error` means its `planned_commit` is unknown: say so and continue.
 
+**Size the ceremony** (pass `--quality` or `--full` through when `$ARGUMENTS` has them):
+
+```bash
+SIZING=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs size phase "${PHASE_ARG}" [--quality] [--full])
+```
+
+Show `Ceremony: {path} ({reasons joined by "; "})`. When `SIZING.path` is `lean`, the phase runs without the test-generation agent (`generate_tests`); the executor's own tests, the engine's test gate, one code review pass (`code_review`) and the verifier (`verify_phase_goal`) still run, and the phase gate still decides.
+
 When `parallelization` is false, plans within a wave execute sequentially.
 
 **Circular optimization — start trace session for this exec:**
@@ -96,6 +104,8 @@ PLAN_INDEX=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase-plan-index "
 
 Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
 
+**One plan (`--plan <id>`).** Execute only that plan: skip every other plan, then stop after its summary and commits, with no code review, verification or phase routing. `pan-tools autodev run --worktrees` runs each plan this way in its own git worktree and merges the plans back behind a shadow-merge preflight; the phase-level steps run later on the merged result. If the plan already has a summary, say so and stop.
+
 **Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip plans whose frontmatter lacks `gap_closure: true` (`phase-plan-index` does not report it; `frontmatter get <plan> --field gap_closure` exits 1 when it is absent). If all filtered: "No matching incomplete plans" → exit.
 
 **If `--gaps-only`:** this run is the fix round after a verification found gaps — a second attempt at work that failed once. Resolve the executor for that attempt and use it in place of `executor_model` for every spawn in this run:
@@ -117,6 +127,14 @@ Report:
 | 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
 | 2 | 01-03 | ... |
 ```
+
+**Test baseline.** Before the first wave, record what the test suite does now, so the verifier can tell a failure this phase caused from one it inherited:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs test run --phase "${PHASE_NUMBER}" --baseline > /dev/null
+```
+
+A phase that already has a baseline keeps it (a resumed run or a `--gaps-only` round compares against the phase's start, not its half-built state); the command says `kept_existing: true` and runs nothing. A failing or empty baseline is not a reason to stop: it is what the phase starts from.
 </step>
 
 <step name="execute_waves">
@@ -178,6 +196,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
        - .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
        </files_to_read>
 
+       {Only when the plan's frontmatter has `supersedes_tests`, include:}
+       <superseded_tests>
+       This plan changes behaviour earlier phases built ({supersedes_requirements}). These test files assert the old behaviour and the plan declares them: {supersedes_tests}. Updating their expectations to what those requirements now require is part of the task, not a spec conflict. Record each changed expectation as a deviation in the summary (file, what it asserted, what it asserts now, which requirement). Deleting, skipping or weakening a test is still forbidden, and `verify test-integrity` still checks it.
+       </superseded_tests>
+
        If the plan's `<context>` names `@.planning/roadmap.md`, read `{slice_path}` in its place: it carries this phase's section, its dependencies' goals and its requirements, and the whole roadmap is the largest file in `.planning/` on a long project. Open the whole file only for something the slice leaves out.
 
        <success_criteria>
@@ -202,6 +225,8 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
 
+   **An executor that returned `## DONE_WITH_CONCERNS`** finished its plan: run the same spot-checks and treat it as complete. Keep its concerns (each with why and cost if wrong, also under `## Concerns` in its summary) for the wave report and the phase report. Do not stop the wave for them; a high-cost concern is something the review and the verifier should look at, and the phase report puts it in front of the user.
+
    **An executor that returned `## BLOCKED_SPEC_CONFLICT`** found a test it cannot satisfy without weakening it. It is not a failure to retry: show the user its Test, Requirement and Options and ask for a ruling. "Change the test" means a revised plan that declares the test file in `files_modified` (`/pan:plan-phase {N} --gaps` or an edit to the plan), then re-run that plan; "change the requirement" means updating the requirement and the plan. Never re-run the same plan unchanged: it would meet the same test. Declaring the file permits rewriting its expectations; deleting the test, skipping it or dropping assertions still fails `verify test-integrity`, so a ruling to do that also needs `phase complete --force --reason`.
 
    If pass:
@@ -211,7 +236,8 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    **{Plan ID}: {Plan Name}**
    {What was built — from summary.md}
-   {Notable deviations, if any}
+   {Notable deviations, if any, with their cost if wrong}
+   {Concerns, if it returned DONE_WITH_CONCERNS}
 
    {If more waves: what this enables for next wave}
    ---
@@ -229,6 +255,12 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
      2>/dev/null || true
    ```
 
+   Check the phase's spend against its budget (`cost.phase_budget_usd`, default $20; it only warns):
+   ```bash
+   BUDGET=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs cost budget --phase "${PHASE_NUMBER}" 2>/dev/null)
+   ```
+   When its `status` is `near` or `over`, add one line to the wave report: "Spend: ${spent_usd} of the ${budget_usd} phase budget (${pct}%)", and for `over`, "over budget: the phase keeps running; change the budget with /pan:settings". Do not stop, pause or ask: the budget warns, it never blocks. `ok` and `off` add nothing.
+
    - Bad: "Wave 2 complete. Proceeding to Wave 3."
    - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
 
@@ -323,13 +355,20 @@ After all waves:
 
 ### Issues Encountered
 [Aggregate from SUMMARYs, or "None"]
+
+### Concerns
+[Every concern from the plans that returned DONE_WITH_CONCERNS (and any `## Concerns` entry in a summary), high cost if wrong first:]
+- **03-02** C-1: [concern]. Why: [...]. Cost if wrong: high — [what breaks]
+[Or "None"]
 ```
+
+Concerns go into the review too: the code_review step passes them to the reviewer as `${EXECUTOR_CONCERNS}`, so a high-cost concern is checked rather than only reported.
 </step>
 
 <step name="generate_tests">
 **Auto-invoke test generation after execution completes.**
 
-**Skip if** `--skip-tests` or `--fast` flag is present in $ARGUMENTS.
+**Skip if** `--skip-tests` or `--fast` flag is present in $ARGUMENTS, or `SIZING.path` is `lean`.
 
 1. Record baseline test count:
 ```bash
@@ -339,12 +378,9 @@ TEST_BASELINE=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 2. Invoke phase-tests workflow for the completed phase:
 ```
 Task(
-  prompt="Generate tests for phase ${PHASE_NUMBER}.
+  prompt="Follow the phase-tests workflow (~/.claude/pan-wizard-core/workflows/phase-tests.md) for phase ${PHASE_NUMBER}.
 Phase directory: ${phase_dir}
-Read each summary.md to understand what was built.
-Generate unit and integration tests for the new code.
-Discover the project's existing test patterns, directories, frameworks, and helpers before writing tests.
-Follow whatever conventions the project already uses.",
+It classifies each changed file, discovers the project's test patterns, writes the tests the plan approves, and commits them.",
   subagent_type="general-purpose",
   model="{executor_model}",
 )
@@ -355,7 +391,13 @@ Alternatively, if the user's AI tool supports it, invoke the command directly:
 /pan:phase-tests ${PHASE_NUMBER}
 ```
 
-3. Record new test count:
+3. Prove the new tests catch something (V4). A test that passes without the phase's code is tautological:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify red "${PHASE_NUMBER}"
+```
+Rewrite or drop each test it reports as `not_red`; `not_checked` names a runner that cannot run one file and is reported, not failed.
+
+4. Record new test count:
 ```bash
 TEST_AFTER=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 ```
@@ -376,15 +418,14 @@ TEST_AFTER=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 <step name="code_review">
 **Spawn pan-reviewer agent to review changed files.**
 
-**Skip if** `--skip-review` or `--fast` flag is present in $ARGUMENTS.
+**Skip if** `--skip-review` or `--fast` flag is present in $ARGUMENTS. A lean phase (`SIZING.path`) keeps this step: the review finds what the tests and the verifier do not.
 
-1. Collect changed files from executor summaries:
+1. Collect the review scope: the files the phase's commits changed plus any uncommitted or untracked work, whether or not a summary lists them, and the intent to judge them against:
 ```bash
-# Read each summary.md and extract key-files.created + key-files.modified
-for summary in "$PHASE_DIR"/*-summary.md; do
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$summary" --fields key_files | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const k=JSON.parse(s).key_files||{};for(const f of [...(k.created||[]),...(k.modified||[])])console.log(f)})"
-done | sort -u > /tmp/review-files.txt
+REVIEW_SCOPE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "${PHASE_NUMBER}")
+CHANGED_FILES_LIST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "${PHASE_NUMBER}" --raw)
 ```
+`REVIEW_SCOPE` is JSON. Its `unlisted` array holds the changed files no summary's key-files names. Review them like the others: an executor that changed a file without listing it is exactly what a review must not miss. Its `intent` holds each plan's objective, `must_haves` and Review Focus, and the text of the requirements the plans claim.
 
 2. Collect the reviewer's earlier open findings on this phase (empty on a first review), then spawn pan-reviewer:
 ```bash
@@ -412,6 +453,19 @@ Task(
     Phase directory: ${phase_dir}
     </context>
 
+    <intent>
+    The plans' objectives, must_haves and Review Focus, the requirements they claim,
+    and the changed files no summary listed (review scope JSON):
+    ${REVIEW_SCOPE}
+    </intent>
+
+    <executor_concerns>
+    What the executors finished but were not sure of, each with why and its cost if
+    wrong (from DONE_WITH_CONCERNS returns and the summaries' ## Concerns). Check the
+    high-cost ones first. Empty when there were none:
+    ${EXECUTOR_CONCERNS}
+    </executor_concerns>
+
     <open_findings>
     ${OPEN_REVIEW_FINDINGS}
     </open_findings>
@@ -421,6 +475,16 @@ Task(
 
 3. **Save the report.** Use the Write tool to write the reviewer's returned text, verbatim and in full (including its closing `pan-verdict` block), to `{phase_dir}/{phase_number}-review.md`. The reviewer is read-only by design, so the orchestrator saves the report. `/pan:review-deep` and the findings ledger read this file.
 
+   **Lenses (opt-in).** Check the review mode first:
+   ```bash
+   REVIEW_MODE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.review_mode 2>/dev/null || echo single)
+   ```
+   When it is `lenses`, run step 2 three times instead of once. Each spawn's prompt carries one `<lens>` (`correctness`, `security`, `maintainability`), and each report is saved to `{phase_dir}/{phase_number}-review-{lens}.md`. Then merge them in code. A finding survives only when at least two of the three passes reported it, and the verdict is recomputed from what survives:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review vote --phase "${PHASE_NUMBER}" --out "{phase_dir}/{phase_number}-review.md" "{phase_dir}/{phase_number}-review-correctness.md" "{phase_dir}/{phase_number}-review-security.md" "{phase_dir}/{phase_number}-review-maintainability.md"
+   ```
+   Step 4 records the merged `{phase_number}-review.md` as usual. `single`, the default, is the one pass above.
+
 4. **Record the verdict, then act on it.** The record is what this step branches on. It also adds the findings to the ledger (`.planning/findings.jsonl`) and logs the verdict to the trace, so no separate trace call is needed:
 ```bash
 REVIEW_FILE="{phase_dir}/{phase_number}-review.md"
@@ -633,7 +697,7 @@ COMPLETION_EXIT=$?
 | Result | Action |
 |---|---|
 | exit 1, `error: phase_gate_refused` (`workflow.phase_gate: enforce`) | The phase was NOT marked complete. Show each `gate.reasons` entry (`code`: `detail`) with its fix, and stop: no commit, no auto-advance. The user may complete anyway with a reason (below) |
-| exit 0, `gate.ok` false (`warn`, the default) | The phase was marked complete. Show the reasons as warnings, run the rest of this step, and do NOT auto-advance (`offer_next` reads `GATE_OK`) |
+| exit 0, `gate.ok` false (`workflow.phase_gate: warn`) | The phase was marked complete. Show the reasons as warnings, run the rest of this step, and do NOT auto-advance (`offer_next` reads `GATE_OK`) |
 | exit 0, `gate.ok` true | Continue |
 
 **Completing past a refusal** is the user's decision, never yours, and needs their reason. It records a `decision` for every open finding the gate counted:

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

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

package/{commands/pan → pan-wizard-core/workflows}/focus-doc-audit.md

@@ -1,20 +1,4 @@
----
-name: focus-doc-audit
-group: Focus
-description: Multi-dimensional document audit — accuracy, freshness, links, cross-consistency, and structural quality
-argument-hint: "[file|directory] [--deep] [--links] [--fix] [--all] [--score-only] [--min-score N] [--format markdown|json|checklist]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - Agent
-  - WebFetch
----
-
-# /pan:focus-doc-audit — Deep Document Audit & Quality Assessment
+# /pan:focus-docs — Deep Document Audit & Quality Assessment
 
 Audit project documentation for accuracy, freshness, broken links, structural quality, cross-document consistency, and code alignment. $ARGUMENTS
 
@@ -24,7 +8,7 @@ Audit project documentation for accuracy, freshness, broken links, structural qu
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command audits the **host project's documentation** — NOT PAN Wizard's own infrastructure files.
 
@@ -41,20 +25,20 @@ If you find yourself auditing a PAN command file — STOP. Refocus on the projec
 
 ## MANDATORY: Execute ALL Phases Automatically
 
-When `/pan:focus-doc-audit` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete audit report at the end.
+When `/pan:focus-docs` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete audit report at the end.
 
 **Usage:**
 ```
-/pan:focus-doc-audit                     # Audit core docs (README, main docs)
-/pan:focus-doc-audit <file>              # Audit a specific file
-/pan:focus-doc-audit <directory>         # Audit all markdown files in directory
-/pan:focus-doc-audit --deep              # Deep audit: verify every claim against code
-/pan:focus-doc-audit --links             # Link validation pass only
-/pan:focus-doc-audit --fix               # Auto-fix simple issues (counts, versions, dates, links)
-/pan:focus-doc-audit --all               # Audit ALL documentation files project-wide
-/pan:focus-doc-audit --score-only        # Skip fix suggestions, just output scores
-/pan:focus-doc-audit --min-score <N>     # Only report files scoring below N% (default: 100 = report all)
-/pan:focus-doc-audit --format <type>     # Output: markdown (default), json, checklist
+/pan:focus-docs                     # Audit core docs (README, main docs)
+/pan:focus-docs <file>              # Audit a specific file
+/pan:focus-docs <directory>         # Audit all markdown files in directory
+/pan:focus-docs --deep              # Deep audit: verify every claim against code
+/pan:focus-docs --links             # Link validation pass only
+/pan:focus-docs --fix               # Auto-fix simple issues (counts, versions, dates, links)
+/pan:focus-docs --all               # Audit ALL documentation files project-wide
+/pan:focus-docs --score-only        # Skip fix suggestions, just output scores
+/pan:focus-docs --min-score <N>     # Only report files scoring below N% (default: 100 = report all)
+/pan:focus-docs --format <type>     # Output: markdown (default), json, checklist
 ```
 
 ---