pan-wizard 3.31.0 → 3.33.0

package/agents/pan-planner.md

@@ -43,7 +43,7 @@ Before planning, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during planning
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Ensure plans account for project skill patterns and conventions
 
 This ensures task actions reference the correct patterns and libraries for this project.
@@ -131,15 +131,15 @@ Discovery is MANDATORY unless you can prove current context exists.
 
 **Level 1 - Quick Verification** (2-5 min)
 - Single known library, confirming syntax/version
-- Action: Context7 resolve-library-id + query-docs, no DISCOVERY.md needed
+- Action: Context7 resolve-library-id + query-docs, no discovery.md needed
 
 **Level 2 - Standard Research** (15-30 min)
 - Choosing between 2-3 options, new external integration
-- Action: Route to discovery workflow, produces DISCOVERY.md
+- Action: Follow the discovery template (`~/.claude/pan-wizard-core/templates/discovery.md`), produces discovery.md in the phase directory
 
 **Level 3 - Deep Dive** (1+ hour)
 - Architectural decision with long-term impact, novel problem
-- Action: Full research with DISCOVERY.md
+- Action: Full research with discovery.md
 
 **Depth indicators:**
 - Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description
@@ -187,7 +187,7 @@ Every task has four required fields:
 |------|---------|----------|
 | `auto` | Everything Claude can do independently | Fully autonomous |
 | `checkpoint:human-verify` | Visual/functional verification | Pauses for user |
-| `checkpoint:decision` | Implementation choices | Pauses for user |
+| `checkpoint:decision` | Implementation choices | Pauses for user; in auto mode takes `auto_select` if the task names one |
 | `checkpoint:human-action` | Truly unavoidable manual steps (rare) | Pauses for user |
 
 **Automation-first rule:** If Claude CAN do it via CLI/API, Claude MUST do it. Checkpoints verify AFTER automation, not replace it.
@@ -228,6 +228,15 @@ This prevents the "scavenger hunt" anti-pattern where executors explore the code
 
 **Test:** Could a different Claude instance execute without asking clarifying questions? If not, add specificity.
 
+## Decisions, Not Code
+
+A plan records the decisions an executor needs; it does not write the code for them. Specific means decided, not implemented.
+
+- **Put in the plan:** names, signatures and types the task introduces, values and limits (15-min expiry, 3-50 chars), library choices with the reason, the assertions the tests must make, and the verify command.
+- **Leave out:** function bodies, complete files, and any code block longer than a signature, a type or a short config snippet. `verify plan-structure` warns on a code block in an `<action>` over 20 lines.
+- **Planning is not building.** Write only plan files. Do not create or edit source files while planning, even to "try something out".
+- **Proportion check before you finish:** if a plan is longer than the code it describes would be, or holds code an executor could paste unchanged, cut it back to the decisions.
+
 ## TDD Detection
 
 **Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
@@ -716,7 +725,7 @@ Human makes implementation choice affecting direction.
 Use for: Technology selection, architecture decisions, design choices.
 
 ```xml
-<task type="checkpoint:decision" gate="blocking">
+<task type="checkpoint:decision" gate="blocking" auto_select="option-a">
   <decision>[What's being decided]</decision>
   <context>[Why this matters]</context>
   <options>
@@ -730,6 +739,8 @@ Use for: Technology selection, architecture decisions, design choices.
 </task>
 ```
 
+`auto_select` is the option auto mode takes, and only that. Set it to an option `id` when the choice is safe without the user (reversible, no new paid service, no credential, no data-model lock-in); leave it out when a human must decide, and auto mode stops there. Option order never decides anything.
+
 **checkpoint:human-action (1% - rare)**
 Action has NO CLI/API and requires human-only interaction.
 
@@ -1026,7 +1037,7 @@ ls .planning/phases/
 
 If multiple phases available, ask which to plan. If obvious (first incomplete), proceed.
 
-Read existing plan.md or DISCOVERY.md in phase directory.
+Read existing plan.md or discovery.md in phase directory.
 
 **If `--gaps` flag:** Switch to gap_closure_mode.
 </step>
@@ -1090,7 +1101,7 @@ Use `phase_dir` from init context (already loaded in load_project_state).
 ```bash
 cat "$phase_dir"/*-context.md 2>/dev/null   # From /pan:discuss-phase
 cat "$phase_dir"/*-research.md 2>/dev/null   # From /pan:research-phase
-cat "$phase_dir"/*-DISCOVERY.md 2>/dev/null  # From mandatory discovery
+cat "$phase_dir"/*discovery.md 2>/dev/null   # From mandatory discovery
 ```
 
 **If context.md exists (has_context=true from init):** Honor user's vision, prioritize essential features, respect boundaries. Locked decisions — do not revisit.
@@ -1202,8 +1213,10 @@ STRUCTURE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify plan-structu
 Returns JSON: `{ valid, errors, warnings, task_count, tasks }`
 
 **If errors exist:** Fix before committing:
-- Missing `<name>` in task → add name element
-- Missing `<action>` → add action element
+- Missing `<name>` in an auto task → add name element
+- Missing `<action>` in an auto task → add action element
+- A checkpoint missing its own elements (`<decision>` + `<options>`, `<what-built>` + `<how-to-verify>`, or `<action>`) → add them; checkpoints need no `<name>`/`<files>`/`<verify>`/`<done>`
+- `auto_select` names no option → name a real option `id`, or drop `auto_select` so a human decides
 - Checkpoint/autonomous mismatch → update `autonomous: false`
 </step>
 

package/agents/pan-project-researcher.md

@@ -23,12 +23,13 @@ Your files feed the roadmap:
 
 | File | How Roadmap Uses It |
 |------|---------------------|
-| `summary.md` | Phase structure recommendations, ordering rationale |
 | `stack.md` | Technology decisions for the project |
 | `features.md` | What to build in each phase |
 | `architecture.md` | System structure, component boundaries |
 | `pitfalls.md` | What phases need deeper research flags |
 
+The roadmapper reads them through `summary.md`, which pan-research-synthesizer writes from these files once every researcher has finished. You don't write it.
+
 **Be comprehensive but opinionated.** "Use X because Y" not "Options are X, Y, Z."
 </role>
 
@@ -178,58 +179,6 @@ Never present LOW confidence findings as authoritative.
 
 All files → `.planning/research/`
 
-## summary.md
-
-```markdown
-# Research Summary: [Project Name]
-
-**Domain:** [type of product]
-**Researched:** [date]
-**Overall confidence:** [HIGH/MEDIUM/LOW]
-
-## Executive Summary
-
-[3-4 paragraphs synthesizing all findings]
-
-## Key Findings
-
-**Stack:** [one-liner from stack.md]
-**Architecture:** [one-liner from architecture.md]
-**Critical pitfall:** [most important from pitfalls.md]
-
-## Implications for Roadmap
-
-Based on research, suggested phase structure:
-
-1. **[Phase name]** - [rationale]
-   - Addresses: [features from features.md]
-   - Avoids: [pitfall from pitfalls.md]
-
-2. **[Phase name]** - [rationale]
-   ...
-
-**Phase ordering rationale:**
-- [Why this order based on dependencies]
-
-**Research flags for phases:**
-- Phase [X]: Likely needs deeper research (reason)
-- Phase [Y]: Standard patterns, unlikely to need research
-
-## Confidence Assessment
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | [level] | [reason] |
-| Features | [level] | [reason] |
-| Architecture | [level] | [reason] |
-| Pitfalls | [level] | [reason] |
-
-## Gaps to Address
-
-- [Areas where research was inconclusive]
-- [Topics needing phase-specific research later]
-```
-
 ## stack.md
 
 ```markdown
@@ -550,14 +499,12 @@ Run pre-submission checklist (see verification_protocol).
 
 ## Step 5: Write Output Files
 
-In `.planning/research/`:
-1. **summary.md** — Always
-2. **stack.md** — Always
-3. **features.md** — Always
-4. **architecture.md** — If patterns discovered
-5. **pitfalls.md** — Always
-6. **comparison.md** — If comparison mode
-7. **feasibility.md** — If feasibility mode
+In `.planning/research/`, write only the file your prompt's `<output>` block names:
+1. **stack.md**, **features.md**, **architecture.md** or **pitfalls.md** — the dimension you were spawned for
+2. **comparison.md** — If comparison mode
+3. **feasibility.md** — If feasibility mode
+
+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.
 
 ## Step 6: Return Structured Result
 
@@ -584,11 +531,7 @@ In `.planning/research/`:
 
 | File | Purpose |
 |------|---------|
-| .planning/research/summary.md | Executive summary with roadmap implications |
-| .planning/research/stack.md | Technology recommendations |
-| .planning/research/features.md | Feature landscape |
-| .planning/research/architecture.md | Architecture patterns |
-| .planning/research/pitfalls.md | Domain pitfalls |
+| .planning/research/{file}.md | {dimension}: {what it covers} |
 
 ### Confidence Assessment
 
@@ -644,7 +587,7 @@ Research is complete when:
 - [ ] Source hierarchy followed (Context7 → Official → WebSearch)
 - [ ] All findings have confidence levels
 - [ ] Output files created in `.planning/research/`
-- [ ] summary.md includes roadmap implications
+- [ ] Roadmap implications included in the structured return
 - [ ] Files written (DO NOT commit — orchestrator handles this)
 - [ ] Structured return provided to orchestrator
 

package/agents/pan-reviewer.md

@@ -69,6 +69,10 @@ If a changed file path starts with any of these prefixes, **skip it silently**.
 | Duplicate code | > 10 identical lines across files | INFO |
 | TODO/FIXME/HACK | New instances added in this phase | INFO |
 
+## Scope (unrequested work)
+
+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>
 
 <output_format>
@@ -106,6 +110,21 @@ Return a structured review report:
 - **PASS**: Zero errors, zero warnings
 - **PASS_WITH_WARNINGS**: Zero errors, warnings present
 - **NEEDS_FIXES**: Any errors present
+
+**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`.
+- `where` is `file:line`.
+- A clean review has `"findings": []`.
+
+The orchestrator records this block. It is how your findings reach the phase's findings ledger and `/pan:review-deep`.
+
+````markdown
+```pan-verdict
+{"contract":"1.0","agent":"pan-reviewer","phase":"{phase_number}","verdict":"NEEDS_FIXES","outcome":"fail","findings":[{"class":"quality","severity":"high","where":"src/utils/parser.ts:42","summary":"Inconsistent naming — uses snake_case, project uses camelCase"}]}
+```
+````
 </output_format>
 
 <constraints>

package/agents/pan-roadmapper.md

@@ -24,7 +24,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Apply goal-backward thinking at phase level
 - Create success criteria (2-5 observable behaviors per phase)
 - Initialize state.md (project memory)
-- Return structured draft for user approval
+- Write the files, then return a structured summary; the orchestrator presents the roadmap to the user for approval
 </role>
 
 <downstream_consumer>
@@ -342,48 +342,6 @@ Key sections:
 - Accumulated Context (decisions, todos, blockers)
 - Session Continuity
 
-## Draft Presentation Format
-
-When presenting to user for approval:
-
-```markdown
-## ROADMAP DRAFT
-
-**Phases:** [N]
-**Depth:** [from config]
-**Coverage:** [X]/[Y] requirements mapped
-
-### Phase Structure
-
-| Phase | Goal | Requirements | Success Criteria |
-|-------|------|--------------|------------------|
-| 1 - Setup | [goal] | SETUP-01, SETUP-02 | 3 criteria |
-| 2 - Auth | [goal] | AUTH-01, AUTH-02, AUTH-03 | 4 criteria |
-| 3 - Content | [goal] | CONT-01, CONT-02 | 3 criteria |
-
-### Success Criteria Preview
-
-**Phase 1: Setup**
-1. [criterion]
-2. [criterion]
-
-**Phase 2: Auth**
-1. [criterion]
-2. [criterion]
-3. [criterion]
-
-[... abbreviated for longer roadmaps ...]
-
-### Coverage
-
-✓ All [X] v1 requirements mapped
-✓ No orphaned requirements
-
-### Awaiting
-
-Approve roadmap or provide feedback for revision.
-```
-
 </output_formats>
 
 <execution_flow>
@@ -446,7 +404,7 @@ Verify 100% requirement mapping:
 - Every v1 requirement → exactly one phase
 - No orphans, no duplicates
 
-If gaps found, include in draft for user decision.
+If gaps found, resolve them (see Coverage Validation) and list each gap with the resolution applied under Coverage Notes in your return; the user reviews them at the orchestrator's approval step.
 
 ## Step 7: Write Files — Once Each, Complete
 
@@ -470,7 +428,7 @@ Return `## ROADMAP CREATED` with summary of what was written.
 
 If orchestrator provides revision feedback:
 - Parse specific concerns
-- Update files in place (Edit, not rewrite from scratch)
+- Rewrite each file the feedback changes with one Write (P-1808 above; your tools have no Edit), and leave the others alone
 - Re-validate coverage
 - Return `## ROADMAP REVISED` with changes made
 
@@ -629,9 +587,8 @@ Roadmap is complete when:
 - [ ] roadmap.md structure complete
 - [ ] state.md structure complete
 - [ ] requirements.md traceability update prepared
-- [ ] Draft presented for user approval
-- [ ] User feedback incorporated (if any)
-- [ ] Files written (after approval)
+- [ ] Files written before returning
+- [ ] Revision feedback incorporated (revision mode only)
 - [ ] Structured return provided to orchestrator
 
 Quality indicators:

package/agents/pan-verifier.md

@@ -26,7 +26,7 @@ Before verifying, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Apply skill rules when scanning for anti-patterns and verifying quality
 
 This ensures project-specific patterns, conventions, and best practices are applied during verification.
@@ -73,8 +73,10 @@ Set `is_re_verification = false`, proceed with Step 0b.
 If the current phase number > 1, check that the previous phase was verified:
 
 ```bash
-PREV_PHASE=$((PHASE_NUM - 1))
-ls .planning/phase-${PREV_PHASE}*/*-verification.md 2>/dev/null
+# 10# reads a zero-padded number like 08 as decimal (bash would read it as octal)
+PREV_PHASE=$((10#${PHASE_NUM%%[!0-9]*} - 1))
+PREV_DIR=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase "$PREV_PHASE" --raw 2>/dev/null)
+[ -n "$PREV_DIR" ] && ls "$PREV_DIR"/*-verification.md 2>/dev/null
 ```
 
 **If previous phase has no verification.md:**
@@ -101,12 +103,12 @@ Extract phase goal from roadmap.md — this is the outcome to verify, not the ta
 
 ## Step 1c: Repo-Norms-First Verification (P-RES-005)
 
-If `.planning/codebase/CONVENTIONS.md` exists (created by `/pan:map-codebase`), read it as a FIRST-CLASS verification input — not just advisory context. The empirical motivation: a 33K-PR audit of agent-generated PRs (arXiv:2601.15195, Jan 2026) found that the dominant rejection cause was **fit-against-repo-norms violation**, not buggy code. Code that compiles and tests still gets rejected when it ignores naming conventions, file organization, framework idioms, or prior-PR patterns.
+If `.planning/codebase/conventions.md` exists (created by `/pan:map-codebase`), read it as a FIRST-CLASS verification input — not just advisory context. The empirical motivation: a 33K-PR audit of agent-generated PRs (arXiv:2601.15195, Jan 2026) found that the dominant rejection cause was **fit-against-repo-norms violation**, not buggy code. Code that compiles and tests still gets rejected when it ignores naming conventions, file organization, framework idioms, or prior-PR patterns.
 
 ```bash
 # Read codebase conventions and structure if available
-[ -f .planning/codebase/CONVENTIONS.md ] && cat .planning/codebase/CONVENTIONS.md
-[ -f .planning/codebase/STRUCTURE.md ] && cat .planning/codebase/STRUCTURE.md
+[ -f .planning/codebase/conventions.md ] && cat .planning/codebase/conventions.md
+[ -f .planning/codebase/structure.md ] && cat .planning/codebase/structure.md
 ```
 
 **How to use this in verification:**
@@ -115,11 +117,11 @@ If `.planning/codebase/CONVENTIONS.md` exists (created by `/pan:map-codebase`),
 
 2. **File organization:** check new files landed in the directory the conventions doc names for that concern. Auth code in `lib/auth/` not `src/auth/` if conventions said `lib/`.
 
-3. **Framework idioms:** if CONVENTIONS.md names "we use X over Y because Z", check the executor didn't import Y. Generic correctness isn't enough — local idiom-fit matters.
+3. **Framework idioms:** if conventions.md names "we use X over Y because Z", check the executor didn't import Y. Generic correctness isn't enough — local idiom-fit matters.
 
-4. **Test patterns:** test files should match the testing patterns described in CONVENTIONS.md (test file naming, fixture organization, assertion style).
+4. **Test patterns:** test files should match the testing patterns described in conventions.md (test file naming, fixture organization, assertion style).
 
-If CONVENTIONS.md does not exist, skip this step silently. This is brownfield-only signal. The verifier should NEVER invent conventions — only enforce ones that are explicitly documented.
+If conventions.md does not exist, skip this step silently. This is brownfield-only signal. The verifier should NEVER invent conventions — only enforce ones that are explicitly documented.
 
 ## Step 1b: Read the Reasoning Trace (P-RES-003)
 
@@ -450,6 +452,21 @@ Include in verification report under a "### Standards Compliance" section:
 
 This is advisory only — standards gaps do NOT block verification status. They appear as warnings/info in the report.
 
+## Step 7c: Check Scope — Unrequested Work
+
+Find what the phase changed that no plan asked for. The file list is mechanical; the judgement is yours:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify scope "$PHASE_NUM"
+```
+
+`candidates` are files the phase changed that no plan declared in `files_modified`. The changes come from the phase's plan commits and its summaries' key-files; the planning tree, lockfiles and PAN's own directories are already excluded. Judge each candidate:
+
+- **Supporting work** the declared tasks need is not a finding. That includes a test for a declared file (`hint: test_for_declared`), a fixture, a config entry the feature requires, and a type the declared code imports.
+- **Work the plans' intent does not cover** goes in the frontmatter as an `unrequested:` entry: `path` and `what` (what it adds that nobody asked for). Examples are a feature nobody asked for, an unrelated refactor, or a file outside the phase's purpose. Behaviour counts too: a declared file that also does something no requirement asked for is unrequested work in that file.
+
+Unrequested work never changes the status on its own; a phase can pass with it. Keeping it (a decision) or removing it is the user's call, and the recorded finding is how the call gets made.
+
 ## Step 8: Identify Human Verification Needs
 
 **Always needs human:** Visual appearance, user flow completion, real-time behavior, external service integration, performance feel, error message clarity.
@@ -466,11 +483,17 @@ This is advisory only — standards gaps do NOT block verification status. They
 **Why human:** {Why can't verify programmatically}
 ```
 
+## 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`.
+
+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.
+
 ## Step 9: Determine Overall Status
 
-**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
+**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns, and the test gate passed or was skipped. A skipped gate stays visible: it is listed in `not_checked`, so the pass says what it did not check.
 
-**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, or blocker anti-patterns found.
+**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, blocker anti-patterns found, or the test gate FAILED.
 
 **Status: human_needed** — All automated checks pass but items flagged for human verification.
 
@@ -508,14 +531,21 @@ gaps:
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
+Record `verified_commit` from `git rev-parse HEAD` before you write the file. It ties the verdict to the code you checked: `pan-tools verify stale <phase>` and `pan-tools progress` compare the phase's files against it, and a file changed since then marks this verification stale.
+
 Create `.planning/phases/{phase_dir}/{phase_num}-verification.md`:
 
 ```markdown
 ---
 phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
+verified_commit: <sha> # `git rev-parse HEAD` before you write this file: the code you verified
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+test_gate: passed | failed | skipped # Step 8b
+not_checked: # Only for checks that could not run — never count them as passed
+  - check: "tests"
+    reason: "no test script in package.json"
 re_verification: # Only if previous verification.md existed
   previous_status: gaps_found
   previous_score: 2/5
@@ -536,6 +566,9 @@ human_verification: # Only if status: human_needed
   - test: "What to do"
     expected: "What should happen"
     why_human: "Why can't verify programmatically"
+unrequested: # Only if Step 7c found work no plan asked for
+  - path: "src/path/to/file.tsx"
+    what: "What it adds that no plan or requirement asked for"
 ---
 
 # Phase {X}: {Name} Verification Report
@@ -581,6 +614,10 @@ human_verification: # Only if status: human_needed
 
 {Items needing human testing — detailed format for user}
 
+### Unrequested Work
+
+{Files or behaviour no plan asked for (Step 7c), each with what it adds — or "None: every change traces to a plan."}
+
 ### Gaps Summary
 
 {Narrative summary of what's missing and why}
@@ -706,6 +743,7 @@ return <div>No messages</div>  // Always shows "no messages"
 - [ ] Requirements coverage assessed (if applicable)
 - [ ] Anti-patterns scanned and categorized
 - [ ] Human verification items identified
+- [ ] Scope checked with `verify scope`; unrequested work recorded in `unrequested:`
 - [ ] Overall status determined
 - [ ] Gaps structured in YAML frontmatter (if gaps_found)
 - [ ] Re-verification metadata included (if previous existed)