pan-wizard 3.33.0 → 3.35.0

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

@@ -35,10 +35,10 @@ See: .planning/project.md (updated [date])
 - Average duration: [X] min
 - Total execution time: [X.X] hours
 
-**By Phase:**
+**By Plan:** (one row per plan, written by `state record-metric`)
 
-| Phase | Plans | Total | Avg/Plan |
-|-------|-------|-------|----------|
+| Plan | Duration | Tasks | Files |
+|------|----------|-------|-------|
 | - | - | - | - |
 
 **Recent Trend:**
@@ -139,7 +139,7 @@ Progress calculation: (completed plans) / (total plans across all phases) × 100
 Track velocity to understand execution patterns:
 - Total plans completed
 - Average duration per plan
-- Per-phase breakdown
+- Per-plan rows (phase, plan, duration, tasks, files)
 - Recent trend (improving/stable/degrading)
 
 Updated after each plan completion.

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"]
 

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

@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase_num}-uat.md` — persistent UAT se
 
 ```markdown
 ---
-status: testing | complete | diagnosed
+status: testing | complete | diagnosed | resolved
 phase: XX-name
 source: [list of summary.md files tested]
 started: [ISO timestamp]
@@ -74,7 +74,7 @@ skipped: [N]
 <section_rules>
 
 **Frontmatter:**
-- `status`: OVERWRITE - "testing" or "complete"
+- `status`: OVERWRITE - "testing", "complete", "diagnosed" (after diagnosis) or "resolved" (exec-phase closes the gaps)
 - `phase`: IMMUTABLE - set on creation
 - `source`: IMMUTABLE - SUMMARY files being tested
 - `started`: IMMUTABLE - set on creation
@@ -106,7 +106,7 @@ skipped: [N]
 
 **After testing complete (status: complete), if gaps exist:**
 
-1. User runs diagnosis (from verify-phase offer or manually)
+1. User runs diagnosis (on Claude Code, the native `/pan-diagnose-issues <phase>`; no `/pan:` command or verify-phase step runs it)
 2. diagnose-issues workflow spawns parallel debug agents
 3. Each agent investigates one gap, returns root cause
 4. uat.md Gaps section updated with diagnosis:

package/pan-wizard-core/templates/user-setup.md

@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required c
 
 ## File Template
 
-```markdown
+~~~markdown
 # Phase {X}: User Setup Required
 
 **Generated:** [YYYY-MM-DD]
@@ -55,7 +55,7 @@ Expected results:
 ---
 
 **Once all items complete:** Mark status as "Complete" at top of file.
-```
+~~~
 
 ---
 
@@ -117,7 +117,7 @@ user_setup:
 ## Service-Specific Examples
 
 <stripe_example>
-```markdown
+~~~markdown
 # Phase 10: User Setup Required
 
 **Generated:** 2025-01-14
@@ -188,11 +188,11 @@ Expected: Build passes, webhook returns 400 (signature validation working).
 ---
 
 **Once all items complete:** Mark status as "Complete" at top of file.
-```
+~~~
 </stripe_example>
 
 <supabase_example>
-```markdown
+~~~markdown
 # Phase 2: User Setup Required
 
 **Generated:** 2025-01-14
@@ -242,11 +242,11 @@ npx supabase status
 ---
 
 **Once all items complete:** Mark status as "Complete" at top of file.
-```
+~~~
 </supabase_example>
 
 <sendgrid_example>
-```markdown
+~~~markdown
 # Phase 5: User Setup Required
 
 **Generated:** 2025-01-14
@@ -297,7 +297,7 @@ curl -X POST http://localhost:3000/api/test-email \
 ---
 
 **Once all items complete:** Mark status as "Complete" at top of file.
-```
+~~~
 </sendgrid_example>
 
 ---

package/pan-wizard-core/templates/verification-report.md

@@ -10,16 +10,34 @@ Template for `.planning/phases/XX-name/{phase_num}-verification.md` — phase go
 ---
 phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
-verified_commit: <sha> # git rev-parse HEAD before writing this file; `pan-tools verify stale` compares against it
+# verified_commit: git rev-parse HEAD before writing this file; `pan-tools verify stale` compares against it
+verified_commit: <sha>
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
 test_gate: passed | failed | skipped
-not_checked: # Only for checks that could not run, with why — a skipped test gate is one
-  - check: "tests"
-    reason: "no test script in package.json"
-unrequested: # Only when the scope check (`pan-tools verify scope <phase>`) found work no plan asked for
-  - path: "src/admin/panel.tsx"
-    what: "An admin panel no plan or requirement asked for"
+# Only for checks that could not run, with why (a skipped test gate is one): write not_checked uncommented
+# not_checked:
+#   - check: "tests"
+#     reason: "no test script in package.json"
+# Only if status: gaps_found; read by `findings record` and /pan:plan-phase --gaps: write gaps uncommented
+# gaps:
+#   - truth: "Observable truth that failed"
+#     status: failed
+#     reason: "Why it failed"
+#     artifacts:
+#       - path: "src/path/to/file.tsx"
+#         issue: "What's wrong"
+#     missing:
+#       - "Specific thing to add/fix"
+# Only if status: human_needed: write human_verification uncommented
+# human_verification:
+#   - test: "What to do"
+#     expected: "What should happen"
+#     why_human: "Why it cannot be verified programmatically"
+# Only when the scope check (`pan-tools verify scope <phase>`) found work no plan asked for: write unrequested uncommented
+# unrequested:
+#   - path: "src/admin/panel.tsx"
+#     what: "An admin panel no plan or requirement asked for"
 ---
 
 # Phase {X}: {Name} Verification Report
@@ -212,8 +230,35 @@ Unrequested work is recorded, not blocking: the status does not change because o
 ---
 phase: 03-chat
 verified: 2025-01-15T14:30:00Z
+verified_commit: 4f2a9c1
 status: gaps_found
-score: 2/5 must-haves verified
+score: 1/5 must-haves verified
+test_gate: passed
+gaps:
+  - truth: "User can see existing messages"
+    status: failed
+    reason: "Chat.tsx renders a placeholder, not message data"
+    artifacts:
+      - path: "src/components/Chat.tsx"
+        issue: "Returns a placeholder div and fetches nothing"
+    missing:
+      - "Fetch from /api/chat and render the messages"
+  - truth: "User can send a message"
+    status: failed
+    reason: "The onSubmit handler only logs"
+    artifacts:
+      - path: "src/components/ChatInput.tsx"
+        issue: "onSubmit calls console.log, no fetch"
+    missing:
+      - "POST to /api/chat on submit"
+  - truth: "Sent message appears in list"
+    status: failed
+    reason: "No state update after send, and the API routes return hardcoded values"
+    artifacts:
+      - path: "src/app/api/chat/route.ts"
+        issue: "GET returns [], POST returns { ok: true }, no database call"
+    missing:
+      - "prisma.message.findMany and create in the route handlers, and a list refresh after send"
 ---
 
 # Phase 3: Chat Interface Verification Report

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

@@ -52,7 +52,7 @@ The CLI handles:
 - Calculating next phase number (max + 1)
 - Generating slug from description
 - Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
-- Inserting the phase entry into roadmap.md with Goal, Depends on, and Plans sections
+- Inserting the phase into roadmap.md: its checklist line, and a section with Goal, Requirements, Depends on and Plans lines
 
 Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
 </step>

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

@@ -24,7 +24,7 @@ Exit workflow.
 Validate phase exists in roadmap:
 
 ```bash
-cat .planning/roadmap.md | grep -i "Phase ${PHASE}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}"   # found, phase_name, goal, success_criteria, section
 ```
 
 **If phase not found:**

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

@@ -81,6 +81,7 @@ For each gap, fill the debug-subagent-prompt template and spawn:
 Task(
   prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-uat.md\n- .planning/state.md\n</files_to_read>",
   subagent_type="pan-debugger",
+  model="{debugger_model}",   # node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-debugger --raw
   description="Debug: {issue_summary_short}"
 )
 ```
@@ -181,11 +182,10 @@ Display:
 
 Debug sessions: ${DEBUG_DIR}/
 
-Proceeding to plan fixes...
+Next: /pan:plan-phase {phase_num} --gaps
 ```
 
-Return to verify-phase orchestrator for automatic planning.
-Do NOT offer manual next steps - verify-phase handles the rest.
+No command runs this workflow as a sub-step, so end by giving the user the next step: `/pan:plan-phase {phase_num} --gaps` (it reads the diagnosed uat.md).
 </step>
 
 </process>
@@ -217,5 +217,5 @@ Agents only diagnose—plan-phase --gaps handles fixes (no fix application).
 - [ ] Root causes collected from all agents
 - [ ] uat.md gaps updated with artifacts and missing
 - [ ] Debug sessions saved to ${DEBUG_DIR}/
-- [ ] Hand off to verify-phase for automatic planning
+- [ ] Next step shown: /pan:plan-phase {phase_num} --gaps
 </success_criteria>

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

@@ -130,7 +130,7 @@ Exit workflow.
 </step>
 
 <step name="auto_mode_bypass">
-**P-1803 fix (v3.7.8):** When `--auto` is set or `workflow.auto_advance: true`, **skip the entire question-driven discussion** and synthesize a minimal `context.md` directly from upstream artifacts. The 6 unguarded `AskUserQuestion` calls in this workflow (lines ~140, 156, 208, 261, 264, 278) all stall headless `claude -p` sessions immediately. Surfaced by the wookie autonomous build (v3.7.7): retry attempts via `/pan:discuss-phase 3 --auto` exited in 75s with $0.42 cost and zero commits before plan-phase auto-mode was patched to bypass discuss-phase entirely. This step makes discuss-phase itself auto-mode-safe, so it can be re-introduced into the auto pipeline cleanly.
+**P-1803 fix (v3.7.8):** When `--auto` is set or `workflow.auto_advance: true`, **skip the entire question-driven discussion** and synthesize a minimal `context.md` directly from upstream artifacts. The unguarded `AskUserQuestion` calls in `check_existing`, `present_gray_areas` and `discuss_areas` all stall headless `claude -p` sessions immediately. Surfaced by the wookie autonomous build (v3.7.7): retry attempts via `/pan:discuss-phase 3 --auto` exited in 75s with 42 cents of cost and zero commits before plan-phase auto-mode was patched to bypass discuss-phase entirely. This step makes discuss-phase itself auto-mode-safe, so it can be re-introduced into the auto pipeline cleanly.
 
 Detect auto mode:
 
@@ -152,7 +152,7 @@ Skip the interactive flow. Generate `context.md` from the roadmap goal + idea.md
 
 2. Read inputs:
 ```bash
-ROADMAP_GOAL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" --raw | sed -n '/^Goal:/,/^$/p')
+PHASE_JSON=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}")   # JSON: goal, success_criteria, section
 IDEA_PATH=".planning/idea.md"
 PROJECT_PATH=".planning/project.md"
 REQ_PATH=".planning/requirements.md"
@@ -170,7 +170,7 @@ REQ_PATH=".planning/requirements.md"
 <domain>
 ## Phase Boundary
 
-[Goal extracted verbatim from roadmap.md]
+[The `goal` from PHASE_JSON, verbatim]
 
 </domain>
 
@@ -181,7 +181,7 @@ REQ_PATH=".planning/requirements.md"
 [For each item in idea.md "Constraints" / "Scope" / "Notes for the planner" sections that mentions Phase ${PHASE} or its domain keywords (e.g., "image pipeline" for Phase 3) — extract as a locked decision, prefixed with the domain name]
 
 ### From requirements.md
-[For each requirement marked Active that maps to Phase ${PHASE} via `requirements.md`'s phase column — list as a locked decision]
+[For each requirement the phase's slice lists under "Its requirements" (`pan-tools roadmap slice ${PHASE} --raw`) — list as a locked decision]
 
 ### Claude's Discretion
 - Implementation patterns within the constraints above (the planner decides specific libraries / file layouts / function shapes)
@@ -213,7 +213,8 @@ None — auto-mode synthesis honors the original idea.md scope.
 
 Write the file:
 ```bash
-mkdir -p "${phase_dir}"
+# phase_dir is null when the phase has no directory yet: create it (the printed path is phase_dir)
+case "{phase_dir}" in ""|null) node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold phase-dir --phase "${PHASE}" --name "{phase_name}" --raw ;; esac
 # Use Write tool (NOT heredoc) to create ${phase_dir}/${PADDED_PHASE}-context.md
 ```
 
@@ -278,7 +279,7 @@ If "Cancel": Exit workflow.
 <step name="analyze_phase">
 Analyze the phase to identify gray areas worth discussing.
 
-**Read the phase description from roadmap.md and determine:**
+**Read the phase's section (`roadmap get-phase "${PHASE}"`: `goal`, `success_criteria`, `section`) and determine:**
 
 1. **Domain boundary** — What capability is this phase delivering? State it clearly.
 
@@ -416,9 +417,9 @@ Create context.md capturing decisions made.
 
 Use values from init: `phase_dir`, `phase_slug`, `padded_phase`.
 
-If `phase_dir` is null (phase exists in roadmap but no directory):
+If `phase_dir` is null (phase exists in roadmap but no directory), create it and use the printed path as `phase_dir`:
 ```bash
-mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold phase-dir --phase "${PHASE}" --name "{phase_name}" --raw
 ```
 
 **File location:** `${phase_dir}/${padded_phase}-context.md`
@@ -598,6 +599,7 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Plan Phase ${PHASE}"
 )
 ```