pan-wizard 3.32.0 → 3.34.0

package/pan-wizard-core/templates/codebase/integrations.md

@@ -8,7 +8,7 @@ Template for `.planning/codebase/integrations.md` - captures external service de
 
 ## File Template
 
-```markdown
+~~~markdown
 # External Integrations
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -149,7 +149,7 @@ erDiagram
 
 *Integration audit: [date]*
 *Update when adding/removing external services*
-```
+~~~
 
 <good_examples>
 ```markdown
@@ -279,10 +279,10 @@ erDiagram
 
 **What does NOT belong here:**
 - Actual API keys or secrets (NEVER write these)
-- Internal architecture (that's ARCHITECTURE.md)
-- Code patterns (that's PATTERNS.md)
-- Technology choices (that's STACK.md)
-- Performance issues (that's CONCERNS.md)
+- Internal architecture (that's architecture.md)
+- Code patterns (that's conventions.md)
+- Technology choices (that's stack.md)
+- Performance issues (that's concerns.md)
 
 **When filling this template:**
 - Check .env.example or .env.template for required env vars

package/pan-wizard-core/templates/codebase/relationships.md

@@ -8,7 +8,7 @@ Template for `.planning/codebase/relationships.md` - maps module dependencies an
 
 ## File Template
 
-```markdown
+~~~markdown
 # Module Relationships
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -90,7 +90,7 @@ Imports that cross architectural boundaries:
 
 *Relationship analysis: [date]*
 *Update when module structure changes*
-```
+~~~
 
 <guidelines>
 **What belongs in relationships.md:**

package/pan-wizard-core/templates/codebase/stack.md

@@ -8,7 +8,7 @@ Template for `.planning/codebase/stack.md` - captures the technology foundation.
 
 ## File Template
 
-```markdown
+~~~markdown
 # Technology Stack
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -92,7 +92,7 @@ graph TD
 
 *Stack analysis: [date]*
 *Update after major dependency changes*
-```
+~~~
 
 <good_examples>
 ```markdown

package/pan-wizard-core/templates/codebase/structure.md

@@ -8,7 +8,7 @@ Template for `.planning/codebase/structure.md` - captures physical file organiza
 
 ## File Template
 
-```markdown
+~~~markdown
 # Codebase Structure
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -125,10 +125,10 @@ graph TD
 
 *Structure analysis: [date]*
 *Update when directory structure changes*
-```
+~~~
 
 <good_examples>
-```markdown
+~~~markdown
 # Codebase Structure
 
 **Analysis Date:** 2025-01-20
@@ -255,7 +255,7 @@ pan-wizard-core/
 
 *Structure analysis: 2025-01-20*
 *Update when directory structure changes*
-```
+~~~
 </good_examples>
 
 <guidelines>

package/pan-wizard-core/templates/codebase/testing.md

@@ -8,7 +8,7 @@ Template for `.planning/codebase/testing.md` - captures test framework and patte
 
 ## File Template
 
-```markdown
+~~~markdown
 # Testing Patterns
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -207,10 +207,10 @@ it('should reject on failure', async () => {
 
 *Testing analysis: [date]*
 *Update when test patterns change*
-```
+~~~
 
 <good_examples>
-```markdown
+~~~markdown
 # Testing Patterns
 
 **Analysis Date:** 2025-01-20
@@ -435,7 +435,7 @@ it('mocks file system', () => {
 
 *Testing analysis: 2025-01-20*
 *Update when test patterns change*
-```
+~~~
 </good_examples>
 
 <guidelines>

package/pan-wizard-core/templates/continue-here.md

@@ -74,5 +74,5 @@ Required YAML frontmatter:
 - Be specific enough that a fresh Claude instance understands immediately
 - Include WHY decisions were made, not just what
 - The `<next_action>` should be actionable without reading anything else
-- This file gets DELETED after resume - it's not permanent storage
+- It's not permanent storage, but resuming does not delete it: the transition workflow deletes a phase's handoffs once that phase is complete
 </guidelines>

package/pan-wizard-core/templates/debug-subagent-prompt.md

@@ -23,7 +23,7 @@ timeline: {timeline}
 
 <mode>
 symptoms_prefilled: {true_or_false}
-goal: {find_root_cause_only | find_and_fix}
+goal: {goal}
 </mode>
 
 <debug_file>
@@ -44,7 +44,8 @@ Create: .planning/debug/{slug}.md
 | `{errors}` | From symptoms | `None in console` |
 | `{reproduction}` | From symptoms | `Open /auth page` |
 | `{timeline}` | From symptoms | `After recent deploy` |
-| `{goal}` | Orchestrator sets | `find_and_fix` |
+| `{true_or_false}` | Orchestrator sets (symptoms prefilled?) | `true` |
+| `{goal}` | Orchestrator sets: `find_root_cause_only` or `find_and_fix` | `find_and_fix` |
 | `{slug}` | Generated | `auth-screen-dark` |
 
 ---

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

@@ -8,7 +8,7 @@ Template for `.planning/debug/[slug].md` — active debug session tracking.
 
 ```markdown
 ---
-status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
+status: gathering | investigating | diagnosed | fixing | verifying | awaiting_human_verify | resolved
 trigger: "[verbatim user input]"
 created: [ISO timestamp]
 updated: [ISO timestamp]
@@ -31,6 +31,14 @@ errors: [error messages if any]
 reproduction: [how to trigger]
 started: [when it broke / always broken]
 
+## Reproduction
+<!-- Written before the first hypothesis; OVERWRITE only to shrink it -->
+
+command: [one command you have RUN that fails on the reported symptom, or "none"]
+fails_with: [the output that shows the symptom, secrets redacted]
+deterministic: [yes / rate N of M runs for a flaky bug]
+tried: [only when command is "none": what you tried and why it cannot be built]
+
 ## Eliminated
 <!-- APPEND only - prevents re-investigating after /clear -->
 
@@ -77,6 +85,12 @@ files_changed: []
 - Reference point for what we're trying to fix
 - Fields: expected, actual, errors, reproduction, started
 
+**Reproduction:**
+- Written before the first hypothesis: one command, already run, that fails on the reported symptom
+- OVERWRITE only to shrink it; the fix is verified when this command passes
+- `command: none` needs `tried:` (what was attempted and why it could not be built)
+- Fields: command, fails_with, deterministic, tried
+
 **Eliminated:**
 - APPEND only - never remove entries
 - Prevents re-investigating dead ends after context reset

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

@@ -30,7 +30,7 @@ Discover [topic] to inform [phase name] implementation.
 
 Purpose: [What decision/implementation this enables]
 Scope: [Boundaries]
-Output: DISCOVERY.md with recommendation
+Output: discovery.md with recommendation
 </discovery_objective>
 
 <discovery_scope>

package/pan-wizard-core/templates/milestone-archive.md

@@ -30,8 +30,8 @@ This template is used by the milestone-done workflow to create archive files in
 
 Plans:
 
-- [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
-- [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
+- [x] {{PHASE}}-01-plan.md — {{PLAN_DESCRIPTION}}
+- [x] {{PHASE}}-02-plan.md — {{PLAN_DESCRIPTION}}
       [... all plans ...]
 
 **Details:**
@@ -47,7 +47,7 @@ Plans:
 
 Plans:
 
-- [x] 02.1-01: Patch auth vulnerability
+- [x] 02.1-01-plan.md — Patch auth vulnerability
 
 **Details:**
 {{PHASE_DETAILS_FROM_ROADMAP}}
@@ -106,14 +106,14 @@ _For current project status, see .planning/roadmap.md_
 - Replace {{PLACEHOLDERS}} with actual values
 - Extract phase details from roadmap.md
 - Document decimal phases with (INSERTED) marker
-- Include key decisions from PROJECT-state.md or SUMMARY files
+- Include key decisions from project.md's Key Decisions table, state.md or the summary files
 - List issues resolved vs deferred
 - Capture technical debt for future reference
 
 **Archive location:**
 
-- Save to `.planning/milestones/v{VERSION}-{NAME}.md`
-- Example: `.planning/milestones/v1.0-mvp.md`
+- Save to `.planning/milestones/v{VERSION}-roadmap.md` (the file `/pan:milestone-done` creates)
+- Example: `.planning/milestones/v1.0-roadmap.md`
 
 **After archiving:**
 

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

@@ -51,7 +51,7 @@ If milestones.md doesn't exist, create it with header:
 - Minor bug fixes that don't constitute a release
 
 **Stats to include:**
-- Count modified files: `git diff --stat feat(XX-XX)..feat(YY-YY) | tail -1`
+- Count modified files: `FIRST=$(git log --reverse --format=%h --grep="feat(XX-XX)" | head -1); LAST=$(git log --format=%h --grep="feat(YY-YY)" | head -1); git diff --stat "${FIRST}^..${LAST}" | tail -1`
 - Count LOC: `find . -name "*.swift" -o -name "*.ts" | xargs wc -l` (or relevant extension)
 - Phase/plan/task counts from ROADMAP
 - Timeline from first phase commit to last phase commit

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

@@ -16,18 +16,18 @@ Template for `.planning/phases/XX-name/{phase}-{plan}-plan.md` - executable phas
 phase: XX-name
 plan: NN
 type: execute
-wave: N                     # Execution wave (1, 2, 3...). Pre-computed at plan time.
-depends_on: []              # Plan IDs this plan requires (e.g., ["01-01"]).
-files_modified: []          # Files this plan modifies.
-autonomous: true            # false if plan has checkpoints requiring user interaction
-requirements: []            # REQUIRED — Requirement IDs from ROADMAP this plan addresses. MUST NOT be empty.
-user_setup: []              # Human-required setup Claude cannot automate (see below)
-
-# Goal-backward verification (derived during planning, verified after execution)
+wave: N
+depends_on: []
+files_modified: []
+autonomous: true
+requirements: []
+user_setup: []
+
+# Goal-backward verification (derived during planning, verified after execution); the Frontmatter Fields table below explains each field
 must_haves:
-  truths: []                # Observable behaviors that must be true for goal achievement
-  artifacts: []             # Files that must exist with real implementation
-  key_links: []             # Critical connections between artifacts
+  truths: []
+  artifacts: []
+  key_links: []
 ---
 
 <objective>
@@ -46,7 +46,7 @@ Output: [What artifacts will be created]
 
 <context>
 @.planning/project.md
-@.planning/roadmap.md
+@.planning/phases/XX-name/{phase}-roadmap-slice.md
 @.planning/state.md
 
 # Only reference prior plan SUMMARYs if genuinely needed:
@@ -58,6 +58,18 @@ Output: [What artifacts will be created]
 @src/path/to/relevant.ts
 </context>
 
+## Plan Decisions
+<!-- Schema: @~/.claude/pan-wizard-core/references/handoff-decisions.md -->
+
+### Locked (executor MUST follow)
+- D-1: [statement]. Why: [rationale]. Source: [context.md REQ-X | research.md | architecture constraint].
+
+### Open (executor's discretion within constraints)
+- O-1: [decision space]. Constraints: [list]. Reason left open: [why planner did not lock].
+
+### Considered and rejected
+- R-1: [alternative]. Rejected because: [reason].
+
 <tasks>
 
 <task type="auto">
@@ -79,7 +91,8 @@ Output: [What artifacts will be created]
 <!-- For checkpoint task examples and patterns, see @~/.claude/pan-wizard-core/references/checkpoints.md -->
 <!-- Key rule: Claude starts dev server BEFORE human-verify checkpoints. User only visits URLs. -->
 
-<task type="checkpoint:decision" gate="blocking">
+<task type="checkpoint:decision" gate="blocking" auto_select="option-a">
+  <!-- auto_select: the option auto mode takes. Omit it when a human must choose. -->
   <decision>[What needs deciding]</decision>
   <context>[Why this decision matters]</context>
   <options>
@@ -193,7 +206,7 @@ Plan 02 in Wave 2 waits for Plan 01 in Wave 1 - genuine dependency on auth types
 wave: 3
 depends_on: ["01", "02"]
 files_modified: [src/components/Dashboard.tsx]
-autonomous: false  # Has checkpoint:human-verify
+autonomous: false
 ```
 
 Wave 3 runs after Waves 1 and 2. Pauses at checkpoint, orchestrator presents to user, resumes on approval.
@@ -209,7 +222,7 @@ Wave 3 runs after Waves 1 and 2. Pauses at checkpoint, orchestrator presents to
 ```markdown
 <context>
 @.planning/project.md
-@.planning/roadmap.md
+@.planning/phases/XX-name/{phase}-roadmap-slice.md
 @.planning/state.md
 
 # Only include SUMMARY refs if genuinely needed:
@@ -288,7 +301,7 @@ See `~/.claude/pan-wizard-core/references/tdd.md` for TDD plan structure.
 - Agent returns with checkpoint details + agent_id
 - Orchestrator presents to user
 - User responds
-- Orchestrator resumes agent with `resume: agent_id`
+- Orchestrator spawns a fresh continuation agent with the user's response (exec-phase: a fresh agent, not a resume)
 
 ---
 
@@ -316,7 +329,7 @@ Output: User model, API endpoints, and UI components.
 
 <context>
 @.planning/project.md
-@.planning/roadmap.md
+@.planning/phases/03-features/03-roadmap-slice.md
 @.planning/state.md
 </context>
 
@@ -381,7 +394,7 @@ Output: Working dashboard component.
 
 <context>
 @.planning/project.md
-@.planning/roadmap.md
+@.planning/phases/03-features/03-roadmap-slice.md
 @.planning/phases/03-features/03-01-summary.md
 @.planning/phases/03-features/03-02-summary.md
 </context>

package/pan-wizard-core/templates/planner-subagent-prompt.md

@@ -15,11 +15,8 @@ Template for spawning pan-planner agent. The agent contains all planning experti
 **Project State:**
 @.planning/state.md
 
-**Roadmap:**
-@.planning/roadmap.md
-
-**Requirements (if exists):**
-@.planning/requirements.md
+**This phase's roadmap and requirements** (`pan-tools roadmap slice {phase_number} --write`; the whole roadmap.md and requirements.md only for something it leaves out):
+@.planning/phases/{phase_dir}/{phase_num}-roadmap-slice.md
 
 **Phase Context (if exists):**
 @.planning/phases/{phase_dir}/{phase_num}-context.md
@@ -62,6 +59,7 @@ Before returning PLANNING COMPLETE:
 | `{phase_number}` | From roadmap/arguments | `5` or `2.1` |
 | `{phase_dir}` | Phase directory name | `05-user-profiles` |
 | `{phase}` | Phase prefix | `05` |
+| `{phase_num}` | Padded phase number in file names | `05` |
 | `{standard \| gap_closure}` | Mode flag | `standard` |
 
 ---

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

@@ -1,10 +1,10 @@
 # Architecture Research Template
 
-Template for `.planning/research/ARCHITECTURE.md` — system structure patterns for the project domain.
+Template for `.planning/research/architecture.md` — system structure patterns for the project domain.
 
 <template>
 
-```markdown
+~~~markdown
 # Architecture Research
 
 **Domain:** [domain type]
@@ -170,7 +170,7 @@ src/
 ---
 *Architecture research for: [domain]*
 *Researched: [date]*
-```
+~~~
 
 </template>
 

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

@@ -1,6 +1,6 @@
 # Features Research Template
 
-Template for `.planning/research/FEATURES.md` — feature landscape for the project domain.
+Template for `.planning/research/features.md` — feature landscape for the project domain.
 
 <template>
 

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

@@ -1,6 +1,6 @@
 # Pitfalls Research Template
 
-Template for `.planning/research/PITFALLS.md` — common mistakes to avoid in the project domain.
+Template for `.planning/research/pitfalls.md` — common mistakes to avoid in the project domain.
 
 <template>
 

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

@@ -1,10 +1,10 @@
 # Stack Research Template
 
-Template for `.planning/research/STACK.md` — recommended technologies for the project domain.
+Template for `.planning/research/stack.md` — recommended technologies for the project domain.
 
 <template>
 
-```markdown
+~~~markdown
 # Stack Research
 
 **Domain:** [domain type]
@@ -88,7 +88,7 @@ npm install -D [packages]
 ---
 *Stack research for: [domain]*
 *Researched: [date]*
-```
+~~~
 
 </template>
 

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

@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase_num}-research.md` - comprehensive
 
 ## File Template
 
-```markdown
+~~~markdown
 # Phase [X]: [Name] - Research
 
 **Researched:** [date]
@@ -21,7 +21,7 @@ Template for `.planning/phases/XX-name/{phase_num}-research.md` - comprehensive
 **CRITICAL:** If context.md exists from /pan:discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
 
 ### Locked Decisions
-[Copy from context.md `## Decisions` section - these are NON-NEGOTIABLE]
+[Copy from context.md `## Implementation Decisions` section (inside `<decisions>`) - these are NON-NEGOTIABLE]
 - [Decision 1]
 - [Decision 2]
 
@@ -242,13 +242,13 @@ Things that couldn't be fully resolved:
 *Phase: XX-name*
 *Research completed: [date]*
 *Ready for planning: [yes/no]*
-```
+~~~
 
 ---
 
 ## Good Example
 
-```markdown
+~~~markdown
 # Phase 3: 3D City Driving - Research
 
 **Researched:** 2025-01-20
@@ -516,7 +516,7 @@ function useVehicleControls(rigidBodyRef) {
 *Phase: 03-city-driving*
 *Research completed: 2025-01-20*
 *Ready for planning: yes*
-```
+~~~
 
 ---
 

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

@@ -28,7 +28,7 @@
 2. {Another lesson}
 
 ### Cost Observations
-- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku
+- Model mix: {X}% reasoning tier, {Y}% mid, {Z}% fast
 - Sessions: {count}
 - Notable: {efficiency observation}
 

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

@@ -29,7 +29,7 @@ Decimal phases appear between their surrounding integers in numeric order.
 ### Phase 1: [Name]
 **Goal:** [What this phase delivers]
 **Depends on:** Nothing (first phase)
-**Requirements:** [REQ-01, REQ-02, REQ-03]  <!-- brackets optional, parser handles both formats -->
+**Requirements:** [REQ-01, REQ-02, REQ-03]
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
@@ -37,9 +37,9 @@ Decimal phases appear between their surrounding integers in numeric order.
 **Plans:** [Number of plans, e.g., "3 plans" or "TBD"]
 
 Plans:
-- [ ] 01-01: [Brief description of first plan]
-- [ ] 01-02: [Brief description of second plan]
-- [ ] 01-03: [Brief description of third plan]
+- [ ] 01-01-plan.md — [Brief description of first plan]
+- [ ] 01-02-plan.md — [Brief description of second plan]
+- [ ] 01-03-plan.md — [Brief description of third plan]
 
 ### Phase 2: [Name]
 **Goal:** [What this phase delivers]
@@ -51,8 +51,8 @@ Plans:
 **Plans:** [Number of plans]
 
 Plans:
-- [ ] 02-01: [Brief description]
-- [ ] 02-02: [Brief description]
+- [ ] 02-01-plan.md — [Brief description]
+- [ ] 02-02-plan.md — [Brief description]
 
 ### Phase 2.1: Critical Fix (INSERTED)
 **Goal:** [Urgent work inserted between phases]
@@ -62,7 +62,7 @@ Plans:
 **Plans:** 1 plan
 
 Plans:
-- [ ] 02.1-01: [Description]
+- [ ] 02.1-01-plan.md — [Description]
 
 ### Phase 3: [Name]
 **Goal:** [What this phase delivers]
@@ -75,8 +75,8 @@ Plans:
 **Plans:** [Number of plans]
 
 Plans:
-- [ ] 03-01: [Brief description]
-- [ ] 03-02: [Brief description]
+- [ ] 03-01-plan.md — [Brief description]
+- [ ] 03-02-plan.md — [Brief description]
 
 ### Phase 4: [Name]
 **Goal:** [What this phase delivers]
@@ -88,7 +88,7 @@ Plans:
 **Plans:** [Number of plans]
 
 Plans:
-- [ ] 04-01: [Brief description]
+- [ ] 04-01-plan.md — [Brief description]
 
 ## Progress
 
@@ -156,9 +156,9 @@ After completing first milestone, reorganize with milestone groupings:
 **Plans:** 3 plans
 
 Plans:
-- [x] 01-01: [Brief description]
-- [x] 01-02: [Brief description]
-- [x] 01-03: [Brief description]
+- [x] 01-01-plan.md — [Brief description]
+- [x] 01-02-plan.md — [Brief description]
+- [x] 01-03-plan.md — [Brief description]
 
 [... remaining v1.0 phases ...]
 
@@ -174,8 +174,8 @@ Plans:
 **Plans:** 2 plans
 
 Plans:
-- [ ] 05-01: [Brief description]
-- [ ] 05-02: [Brief description]
+- [ ] 05-01-plan.md — [Brief description]
+- [ ] 05-02-plan.md — [Brief description]
 
 [... remaining v1.1 phases ...]
 

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

@@ -19,6 +19,7 @@ key-decisions:
   - "Decision 1"
 patterns-established:
   - "Pattern 1: description"
+requirements-completed: []
 duration: Xmin
 completed: YYYY-MM-DD
 ---

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

@@ -13,6 +13,7 @@ key-files:
   created: [important files created]
   modified: [important files modified]
 key-decisions: []
+requirements-completed: []
 duration: Xmin
 completed: YYYY-MM-DD
 ---

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

@@ -6,7 +6,8 @@ tags: [searchable tech]
 provides:
   - [bullet list of what was built/delivered]
 affects: [list of phase names or keywords]
-test-tiers: []  # Optional — Test tiers exercised: [unit, integration, e2e, visual]
+requirements-completed: []
+test-tiers: []
 tech-stack:
   added: [libraries/tools]
   patterns: [architectural/code patterns]

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

@@ -38,8 +38,10 @@ patterns-established:
   - "Pattern 1: description"
   - "Pattern 2: description"
 
-requirements-completed: []  # REQUIRED — Copy ALL requirement IDs from this plan's `requirements` frontmatter field.
-test-tiers: []  # Optional — Test tiers exercised in this plan: [unit, integration, e2e, visual]
+# requirements-completed: REQUIRED — copy ALL requirement IDs from this plan's `requirements` frontmatter field
+requirements-completed: []
+# test-tiers: optional — the test tiers this plan exercised (unit, integration, e2e, visual)
+test-tiers: []
 
 # Metrics
 duration: Xmin
@@ -79,6 +81,20 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 - `path/to/file.ts` - What it does
 - `path/to/another.ts` - What it does
 
+## Implementation Decisions
+<!-- Schema: @~/.claude/pan-wizard-core/references/handoff-decisions.md -->
+
+### Taken (within plan's discretion)
+- 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].
+
+### Open questions for verifier
+- Q-1: [question]. Why it matters: [stake].
+
+<!-- If none: replace ALL three buckets with "No deviations or open questions — implementation followed plan exactly." -->
+
 ## Decisions Made
 [Key decisions with brief rationale, or "None - followed plan as specified"]