pan-wizard 2.8.1

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

@@ -0,0 +1,249 @@
+# Summary Template
+
+Template for `.planning/phases/XX-name/{phase}-{plan}-summary.md` - phase completion documentation.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category: auth, payments, ui, api, database, infra, testing, etc.]
+tags: [searchable tech: jwt, stripe, react, postgres, prisma]
+
+# Dependency graph
+requires:
+  - phase: [prior phase this depends on]
+    provides: [what that phase built that this uses]
+provides:
+  - [bullet list of what this phase built/delivered]
+affects: [list of phase names or keywords that will need this context]
+
+# Tech tracking
+tech-stack:
+  added: [libraries/tools added in this phase]
+  patterns: [architectural/code patterns established]
+
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+
+key-decisions:
+  - "Decision 1"
+  - "Decision 2"
+
+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]
+
+# Metrics
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary
+
+**[Substantive one-liner describing outcome - NOT "phase complete" or "implementation finished"]**
+
+## Performance
+
+- **Duration:** [time] (e.g., 23 min, 1h 15m)
+- **Started:** [ISO timestamp]
+- **Completed:** [ISO timestamp]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Most important outcome]
+- [Second key accomplishment]
+- [Third if applicable]
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: [task name]** - `abc123f` (feat/fix/test/refactor)
+2. **Task 2: [task name]** - `def456g` (feat/fix/test/refactor)
+3. **Task 3: [task name]** - `hij789k` (feat/fix/test/refactor)
+
+**Plan metadata:** `lmn012o` (docs: complete plan)
+
+_Note: TDD tasks may have multiple commits (test → feat → refactor)_
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+- `path/to/another.ts` - What it does
+
+## Decisions Made
+[Key decisions with brief rationale, or "None - followed plan as specified"]
+
+## Deviations from Plan
+
+[If no deviations: "None - plan executed exactly as written"]
+
+[If deviations occurred:]
+
+### Auto-fixed Issues
+
+**1. [Rule X - Category] Brief description**
+- **Found during:** Task [N] ([task name])
+- **Issue:** [What was wrong]
+- **Fix:** [What was done]
+- **Files modified:** [file paths]
+- **Verification:** [How it was verified]
+- **Committed in:** [hash] (part of task commit)
+
+[... repeat for each auto-fix ...]
+
+---
+
+**Total deviations:** [N] auto-fixed ([breakdown by rule])
+**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for correctness/security. No scope creep."]
+
+## Issues Encountered
+[Problems and how they were resolved, or "None"]
+
+[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
+
+[If USER-SETUP.md was generated:]
+**External services require manual configuration.** See [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md) for:
+- Environment variables to add
+- Dashboard configuration steps
+- Verification commands
+
+[If no USER-SETUP.md:]
+None - no external service configuration required.
+
+## Next Phase Readiness
+[What's ready for next phase]
+[Any blockers or concerns]
+
+---
+*Phase: XX-name*
+*Completed: [date]*
+```
+
+<frontmatter_guidance>
+**Purpose:** Enable automatic context assembly via dependency graph. Frontmatter makes summary metadata machine-readable so plan-phase can scan all summaries quickly and select relevant ones based on dependencies.
+
+**Fast scanning:** Frontmatter is first ~25 lines, cheap to scan across all summaries without reading full content.
+
+**Dependency graph:** `requires`/`provides`/`affects` create explicit links between phases, enabling transitive closure for context selection.
+
+**Subsystem:** Primary categorization (auth, payments, ui, api, database, infra, testing) for detecting related phases.
+
+**Tags:** Searchable technical keywords (libraries, frameworks, tools) for tech stack awareness.
+
+**Key-files:** Important files for @context references in plan.md.
+
+**Patterns:** Established conventions future phases should maintain.
+
+**Population:** Frontmatter is populated during summary creation in execute-plan.md. See `<step name="create_summary">` for field-by-field guidance.
+</frontmatter_guidance>
+
+<one_liner_rules>
+The one-liner MUST be substantive:
+
+**Good:**
+- "JWT auth with refresh rotation using jose library"
+- "Prisma schema with User, Session, and Product models"
+- "Dashboard with real-time metrics via Server-Sent Events"
+
+**Bad:**
+- "Phase complete"
+- "Authentication implemented"
+- "Foundation finished"
+- "All tasks done"
+
+The one-liner should tell someone what actually shipped.
+</one_liner_rules>
+
+<example>
+```markdown
+# Phase 1: Foundation Summary
+
+**JWT auth with refresh rotation using jose library, Prisma User model, and protected API middleware**
+
+## Performance
+
+- **Duration:** 28 min
+- **Started:** 2025-01-15T14:22:10Z
+- **Completed:** 2025-01-15T14:50:33Z
+- **Tasks:** 5
+- **Files modified:** 8
+
+## Accomplishments
+- User model with email/password auth
+- Login/logout endpoints with httpOnly JWT cookies
+- Protected route middleware checking token validity
+- Refresh token rotation on each request
+
+## Files Created/Modified
+- `prisma/schema.prisma` - User and Session models
+- `src/app/api/auth/login/route.ts` - Login endpoint
+- `src/app/api/auth/logout/route.ts` - Logout endpoint
+- `src/middleware.ts` - Protected route checks
+- `src/lib/auth.ts` - JWT helpers using jose
+
+## Decisions Made
+- Used jose instead of jsonwebtoken (ESM-native, Edge-compatible)
+- 15-min access tokens with 7-day refresh tokens
+- Storing refresh tokens in database for revocation capability
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 2 - Missing Critical] Added password hashing with bcrypt**
+- **Found during:** Task 2 (Login endpoint implementation)
+- **Issue:** Plan didn't specify password hashing - storing plaintext would be critical security flaw
+- **Fix:** Added bcrypt hashing on registration, comparison on login with salt rounds 10
+- **Files modified:** src/app/api/auth/login/route.ts, src/lib/auth.ts
+- **Verification:** Password hash test passes, plaintext never stored
+- **Committed in:** abc123f (Task 2 commit)
+
+**2. [Rule 3 - Blocking] Installed missing jose dependency**
+- **Found during:** Task 4 (JWT token generation)
+- **Issue:** jose package not in package.json, import failing
+- **Fix:** Ran `npm install jose`
+- **Files modified:** package.json, package-lock.json
+- **Verification:** Import succeeds, build passes
+- **Committed in:** def456g (Task 4 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (1 missing critical, 1 blocking)
+**Impact on plan:** Both auto-fixes essential for security and functionality. No scope creep.
+
+## Issues Encountered
+- jsonwebtoken CommonJS import failed in Edge runtime - switched to jose (planned library change, worked as expected)
+
+## Next Phase Readiness
+- Auth foundation complete, ready for feature development
+- User registration endpoint needed before public launch
+
+---
+*Phase: 01-foundation*
+*Completed: 2025-01-15*
+```
+</example>
+
+<guidelines>
+**Frontmatter:** MANDATORY - complete all fields. Enables automatic context assembly for future planning.
+
+**One-liner:** Must be substantive. "JWT auth with refresh rotation using jose library" not "Authentication implemented".
+
+**Decisions section:**
+- Key decisions made during execution with rationale
+- Extracted to state.md accumulated context
+- Use "None - followed plan as specified" if no deviations
+
+**After creation:** state.md updated with position, decisions, issues.
+</guidelines>

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

@@ -0,0 +1,247 @@
+# UAT Template
+
+Template for `.planning/phases/XX-name/{phase_num}-uat.md` — persistent UAT session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: testing | complete | diagnosed
+phase: XX-name
+source: [list of summary.md files tested]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Test
+<!-- OVERWRITE each test - shows where we are -->
+
+number: [N]
+name: [test name]
+expected: |
+  [what user should observe]
+awaiting: user response
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior - what user should see]
+result: [pending]
+
+### 2. [Test Name]
+expected: [observable behavior]
+result: pass
+
+### 3. [Test Name]
+expected: [observable behavior]
+result: issue
+reported: "[verbatim user response]"
+severity: major
+
+### 4. [Test Name]
+expected: [observable behavior]
+result: skipped
+reason: [why skipped]
+
+...
+
+## Summary
+
+total: [N]
+passed: [N]
+issues: [N]
+pending: [N]
+skipped: [N]
+
+## Gaps
+
+<!-- YAML format for plan-phase --gaps consumption -->
+- truth: "[expected behavior from test]"
+  status: failed
+  reason: "User reported: [verbatim response]"
+  severity: blocker | major | minor | cosmetic
+  test: [N]
+  root_cause: ""     # Filled by diagnosis
+  artifacts: []      # Filled by diagnosis
+  missing: []        # Filled by diagnosis
+  debug_session: ""  # Filled by diagnosis
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: OVERWRITE - "testing" or "complete"
+- `phase`: IMMUTABLE - set on creation
+- `source`: IMMUTABLE - SUMMARY files being tested
+- `started`: IMMUTABLE - set on creation
+- `updated`: OVERWRITE - update on every change
+
+**Current Test:**
+- OVERWRITE entirely on each test transition
+- Shows which test is active and what's awaited
+- On completion: "[testing complete]"
+
+**Tests:**
+- Each test: OVERWRITE result field when user responds
+- `result` values: [pending], pass, issue, skipped
+- If issue: add `reported` (verbatim) and `severity` (inferred)
+- If skipped: add `reason` if provided
+
+**Summary:**
+- OVERWRITE counts after each response
+- Tracks: total, passed, issues, pending, skipped
+
+**Gaps:**
+- APPEND only when issue found (YAML format)
+- After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
+- This section feeds directly into /pan:plan-phase --gaps
+
+</section_rules>
+
+<diagnosis_lifecycle>
+
+**After testing complete (status: complete), if gaps exist:**
+
+1. User runs diagnosis (from verify-work offer or manually)
+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:
+   - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled
+5. status → "diagnosed"
+6. Ready for /pan:plan-phase --gaps with root causes
+
+**After diagnosis:**
+```yaml
+## Gaps
+
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+
+</diagnosis_lifecycle>
+
+<lifecycle>
+
+**Creation:** When /pan:verify-phase starts new session
+- Extract tests from summary.md files
+- Set status to "testing"
+- Current Test points to test 1
+- All tests have result: [pending]
+
+**During testing:**
+- Present test from Current Test section
+- User responds with pass confirmation or issue description
+- Update test result (pass/issue/skipped)
+- Update Summary counts
+- If issue: append to Gaps section (YAML format), infer severity
+- Move Current Test to next pending test
+
+**On completion:**
+- status → "complete"
+- Current Test → "[testing complete]"
+- Commit file
+- Present summary with next steps
+
+**Resume after /clear:**
+1. Read frontmatter → know phase and status
+2. Read Current Test → know where we are
+3. Find first [pending] result → continue from there
+4. Summary shows progress so far
+
+</lifecycle>
+
+<severity_guide>
+
+Severity is INFERRED from user's natural language, never asked.
+
+| User describes | Infer |
+|----------------|-------|
+| Crash, error, exception, fails completely, unusable | blocker |
+| Doesn't work, nothing happens, wrong behavior, missing | major |
+| Works but..., slow, weird, minor, small issue | minor |
+| Color, font, spacing, alignment, visual, looks off | cosmetic |
+
+Default: **major** (safe default, user can clarify if wrong)
+
+</severity_guide>
+
+<good_example>
+```markdown
+---
+status: diagnosed
+phase: 04-comments
+source: 04-01-summary.md, 04-02-summary.md
+started: 2025-01-15T10:30:00Z
+updated: 2025-01-15T10:45:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. View Comments on Post
+expected: Comments section expands, shows count and comment list
+result: pass
+
+### 2. Create Top-Level Comment
+expected: Submit comment via rich text editor, appears in list with author info
+result: issue
+reported: "works but doesn't show until I refresh the page"
+severity: major
+
+### 3. Reply to a Comment
+expected: Click Reply, inline composer appears, submit shows nested reply
+result: pass
+
+### 4. Visual Nesting
+expected: 3+ level thread shows indentation, left borders, caps at reasonable depth
+result: pass
+
+### 5. Delete Own Comment
+expected: Click delete on own comment, removed or shows [deleted] if has replies
+result: pass
+
+### 6. Comment Count
+expected: Post shows accurate count, increments when adding comment
+result: pass
+
+## Summary
+
+total: 6
+passed: 5
+issues: 1
+pending: 0
+skipped: 0
+
+## Gaps
+
+- truth: "Comment appears immediately after submission in list"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+</good_example>