pan-wizard 2.8.1

package/pan-wizard-core/workflows/map-codebase.md

@@ -0,0 +1,401 @@
+<purpose>
+Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
+
+Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
+
+Output: .planning/codebase/ folder with 9 structured documents about the codebase state.
+</purpose>
+
+<philosophy>
+**Why dedicated mapper agents:**
+- Fresh context per domain (no token contamination)
+- Agents write documents directly (no context transfer back to orchestrator)
+- Orchestrator only summarizes what was created (minimal context usage)
+- Faster execution (agents run simultaneously)
+
+**Pre-computed analysis:**
+Before spawning agents, run `codebase analyze-imports` and `codebase detect-languages` to provide structured data to relationship and practices agents. This avoids expensive LLM re-scanning.
+
+**Document quality over length:**
+Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
+
+**Always include file paths:**
+Documents are reference material for Claude when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
+
+**Lowercase filenames:**
+All output documents use lowercase filenames (stack.md, not STACK.md) to align with PAN's .planning/ convention.
+</philosophy>
+
+<process>
+
+<step name="init_context" priority="first">
+Load codebase mapping context:
+
+```bash
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init map-codebase)
+```
+
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `supported_languages`, `file_count`, `focus_areas`.
+</step>
+
+<step name="pre_compute">
+Run pre-computed analysis for relationship and practices agents:
+
+```bash
+LANG_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs codebase detect-languages)
+IMPORT_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs codebase analyze-imports)
+PRACTICES_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs codebase best-practices)
+```
+
+These JSON results will be embedded in agent prompts to avoid redundant scanning.
+</step>
+
+<step name="check_existing">
+Check if .planning/codebase/ already exists using `has_maps` from init context.
+
+If `codebase_dir_exists` is true:
+```bash
+ls -la .planning/codebase/
+```
+
+**If exists:**
+
+```
+.planning/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Update - Keep existing, only update specific documents
+3. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .planning/codebase/, continue to create_structure
+If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .planning/codebase/ directory:
+
+```bash
+mkdir -p .planning/codebase
+```
+
+**Expected output files (all lowercase):**
+- stack.md (from tech mapper)
+- integrations.md (from tech mapper)
+- architecture.md (from arch mapper)
+- structure.md (from arch mapper)
+- conventions.md (from quality mapper)
+- testing.md (from quality mapper)
+- concerns.md (from concerns mapper)
+- relationships.md (from relationships mapper)
+- best-practices.md (from practices mapper)
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+Spawn 6 parallel pan-document_code agents.
+
+Use Task tool with `subagent_type="pan-document_code"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
+
+**CRITICAL:** Use the dedicated `pan-document_code` agent, NOT `Explore`. The mapper agent writes documents directly.
+
+**CRITICAL: Project Scope Boundary — include this line in EVERY agent prompt:**
+> SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+
+**Agent 1: Tech Focus**
+
+```
+Task(
+  subagent_type="pan-document_code",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase tech stack",
+  prompt="Focus: tech
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+
+Analyze this codebase for technology stack and external integrations.
+
+Write these documents to .planning/codebase/:
+- stack.md - Technology Architecture: languages, runtime, frameworks, dependencies, deployment topology diagram
+- integrations.md - Data Architecture: external APIs, databases, auth providers, webhooks, service map and ER diagrams
+
+Include Mermaid diagrams where the template specifies them. Fill TOGAF sections based on findings.
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 2: Architecture Focus**
+
+```
+Task(
+  subagent_type="pan-document_code",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase architecture",
+  prompt="Focus: arch
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+
+Analyze this codebase architecture and directory structure.
+
+Write these documents to .planning/codebase/:
+- architecture.md - Business & Application Architecture: pattern, layers, component relationship diagram, request lifecycle sequence diagram, data flow
+- structure.md - Directory layout with visual hierarchy diagram, key locations, naming conventions
+
+Include Mermaid diagrams where the template specifies them. Fill TOGAF sections based on findings.
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 3: Quality Focus**
+
+```
+Task(
+  subagent_type="pan-document_code",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase conventions",
+  prompt="Focus: quality
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+
+Analyze this codebase for coding conventions and testing patterns.
+
+Write these documents to .planning/codebase/:
+- conventions.md - Code style, naming, patterns, error handling
+- testing.md - Framework, structure, mocking, coverage
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 4: Concerns Focus**
+
+```
+Task(
+  subagent_type="pan-document_code",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase concerns",
+  prompt="Focus: concerns
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+Write this document to .planning/codebase/:
+- concerns.md - Risk overview with quadrant chart, tech debt, bugs, security, performance, fragile areas
+
+Include Mermaid risk quadrant chart where the template specifies it.
+Explore thoroughly. Write document directly using template. Return confirmation only."
+)
+```
+
+**Agent 5: Relationships Focus**
+
+```
+Task(
+  subagent_type="pan-document_code",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map module relationships",
+  prompt="Focus: relationships
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+
+Analyze module dependencies using pre-computed import analysis.
+
+Pre-computed data (from `codebase analyze-imports`):
+{IMPORT_DATA}
+
+Write this document to .planning/codebase/:
+- relationships.md - Module dependency graph (Mermaid), circular dependencies, high-coupling modules, orphan modules, entry points, layer boundaries and violations, import patterns
+
+Use the pre-computed dependency graph and circular dependency data. Enrich with your own exploration of the codebase to understand architectural layers and coupling patterns.
+Write document directly using template. Return confirmation only."
+)
+```
+
+**Agent 6: Practices Focus**
+
+```
+Task(
+  subagent_type="pan-document_code",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map best practices",
+  prompt="Focus: practices
+SCOPE: Only analyze project source code. EXCLUDE these PAN infrastructure directories: .claude/, .github/copilot-instructions.md, .opencode/, .gemini/, .codex/, .planning/
+
+Assess codebase best practices using pre-computed analysis.
+
+Pre-computed language data (from `codebase detect-languages`):
+{LANG_DATA}
+
+Pre-computed best practices scores (from `codebase best-practices`):
+{PRACTICES_DATA}
+
+Write this document to .planning/codebase/:
+- best-practices.md - Scored assessment across 5 categories (Error Handling, Testing, Naming Conventions, Security, Performance), detected patterns with code examples, recommendations
+
+Use the pre-computed scores as a starting point. Explore the codebase to find specific code examples for each category and provide actionable recommendations.
+Write document directly using template. Return confirmation only."
+)
+```
+
+Continue to collect_confirmations.
+</step>
+
+<step name="collect_confirmations">
+Wait for all 6 agents to complete.
+
+Read each agent's output file to collect confirmations.
+
+**Expected confirmation format from each agent:**
+```
+## Mapping Complete
+
+**Focus:** {focus}
+**Documents written:**
+- `.planning/codebase/{doc1}.md` ({N} lines)
+- `.planning/codebase/{doc2}.md` ({N} lines)
+
+Ready for orchestrator summary.
+```
+
+**What you receive:** Just file paths and line counts. NOT document contents.
+
+If any agent failed, note the failure and continue with successful documents.
+
+Continue to verify_output.
+</step>
+
+<step name="verify_output">
+Verify all documents created successfully:
+
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
+
+**Verification checklist:**
+- All 9 documents exist (lowercase filenames)
+- No empty documents (each should have >20 lines)
+
+If any documents missing or empty, note which agents may have failed.
+
+Continue to scan_for_secrets.
+</step>
+
+<step name="scan_for_secrets">
+**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
+
+Run secret pattern detection:
+
+```bash
+# Check for common API key patterns in generated docs
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**If SECRETS_FOUND=true:**
+
+```
+SECURITY ALERT: Potential secrets detected in codebase documents!
+
+Found patterns that look like API keys or tokens in:
+[show grep output]
+
+This would expose credentials if committed.
+
+**Action required:**
+1. Review the flagged content above
+2. If these are real secrets, they must be removed before committing
+3. Consider adding sensitive files to Claude Code "Deny" permissions
+
+Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
+```
+
+Wait for user confirmation before continuing to commit_codebase_map.
+
+**If SECRETS_FOUND=false:**
+
+Continue to commit_codebase_map.
+</step>
+
+<step name="commit_codebase_map">
+Commit the codebase map:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: map existing codebase" --files .planning/codebase/*.md
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps.
+
+**Get line counts:**
+```bash
+wc -l .planning/codebase/*.md
+```
+
+**Output format:**
+
+```
+Codebase mapping complete.
+
+Created .planning/codebase/:
+- stack.md ([N] lines) - Technologies and dependencies
+- architecture.md ([N] lines) - System design and patterns
+- structure.md ([N] lines) - Directory layout and organization
+- conventions.md ([N] lines) - Code style and patterns
+- testing.md ([N] lines) - Test structure and practices
+- integrations.md ([N] lines) - External services and APIs
+- concerns.md ([N] lines) - Technical debt and issues
+- relationships.md ([N] lines) - Module dependencies and coupling
+- best-practices.md ([N] lines) - Best practices assessment and scores
+
+
+---
+
+## Next Up
+
+**Initialize project** — use codebase context for planning
+
+`/pan:new-project`
+
+<sub>`/clear` first - fresh context window</sub>
+
+---
+
+**Also available:**
+- Re-run mapping: `/pan:map-codebase`
+- Review specific file: `cat .planning/codebase/stack.md`
+- Edit any document before proceeding
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .planning/codebase/ directory created
+- Pre-computed analysis run before agents spawn (detect-languages, analyze-imports, best-practices)
+- 6 parallel pan-document_code agents spawned with run_in_background=true
+- Agents write documents directly (orchestrator doesn't receive document contents)
+- Relationships agent receives pre-computed import/dependency data
+- Practices agent receives pre-computed language and best-practices data
+- Read agent output files to collect confirmations
+- All 9 codebase documents exist (lowercase filenames)
+- Clear completion summary with line counts
+- User offered clear next steps in PAN style
+</success_criteria>

package/pan-wizard-core/workflows/milestone-audit.md

@@ -0,0 +1,297 @@
+<purpose>
+Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing verification.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+## 0. Initialize Milestone Context
+
+```bash
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init milestone-op)
+```
+
+Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.
+
+Resolve integration checker model:
+```bash
+CHECKER_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-integration-checker --raw)
+```
+
+## 1. Determine Milestone Scope
+
+```bash
+# Get phases in milestone (sorted numerically, handles decimals)
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phases list
+```
+
+- Parse version from arguments or detect current from roadmap.md
+- Identify all phase directories in scope
+- Extract milestone definition of done from roadmap.md
+- Extract requirements mapped to this milestone from requirements.md
+
+## 2. Read All Phase Verifications
+
+For each phase directory, read the verification.md:
+
+```bash
+# For each phase, use find-phase to resolve the directory (handles archived phases)
+PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase 01 --raw)
+# Extract directory from JSON, then read verification.md from that directory
+# Repeat for each phase number from roadmap.md
+```
+
+From each verification.md, extract:
+- **Status:** passed | gaps_found
+- **Critical gaps:** (if any — these are blockers)
+- **Non-critical gaps:** tech debt, deferred items, warnings
+- **Anti-patterns found:** TODOs, stubs, placeholders
+- **Requirements coverage:** which requirements satisfied/blocked
+
+If a phase is missing verification.md, flag it as "unverified phase" — this is a blocker.
+
+## 3. Spawn Integration Checker
+
+With phase context collected:
+
+Extract `MILESTONE_REQ_IDS` from requirements.md traceability table — all REQ-IDs assigned to phases in this milestone.
+
+```
+Task(
+  prompt="Check cross-phase integration and E2E flows.
+
+Phases: {phase_dirs}
+Phase exports: {from SUMMARYs}
+API routes: {routes created}
+
+Milestone Requirements:
+{MILESTONE_REQ_IDS — list each REQ-ID with description and assigned phase}
+
+MUST map each integration finding to affected requirement IDs where applicable.
+
+Verify cross-phase wiring and E2E user flows.",
+  subagent_type="pan-integration-checker",
+  model="{integration_checker_model}"
+)
+```
+
+## 4. Collect Results
+
+Combine:
+- Phase-level gaps and tech debt (from step 2)
+- Integration checker's report (wiring gaps, broken flows)
+
+## 5. Check Requirements Coverage (3-Source Cross-Reference)
+
+MUST cross-reference three independent sources for each requirement:
+
+### 5a. Parse requirements.md Traceability Table
+
+Extract all REQ-IDs mapped to milestone phases from the traceability table:
+- Requirement ID, description, assigned phase, current status, checked-off state (`[x]` vs `[ ]`)
+
+### 5b. Parse Phase verification.md Requirements Tables
+
+For each phase's verification.md, extract the expanded requirements table:
+- Requirement | Source Plan | Description | Status | Evidence
+- Map each entry back to its REQ-ID
+
+### 5c. Extract summary.md Frontmatter Cross-Check
+
+For each phase's summary.md, extract `requirements-completed` from YAML frontmatter:
+```bash
+for summary in .planning/phases/*-*/*-summary.md; do
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed'
+done
+```
+
+### 5d. Status Determination Matrix
+
+For each REQ-ID, determine status using all three sources:
+
+| verification.md Status | SUMMARY Frontmatter | requirements.md | → Final Status |
+|------------------------|---------------------|-----------------|----------------|
+| passed                 | listed              | `[x]`           | **satisfied**  |
+| passed                 | listed              | `[ ]`           | **satisfied** (update checkbox) |
+| passed                 | missing             | any             | **partial** (verify manually) |
+| gaps_found             | any                 | any             | **unsatisfied** |
+| missing                | listed              | any             | **partial** (verification gap) |
+| missing                | missing             | any             | **unsatisfied** |
+
+### 5e. FAIL Gate and Orphan Detection
+
+**REQUIRED:** Any `unsatisfied` requirement MUST force `gaps_found` status on the milestone audit.
+
+**Orphan detection:** Requirements present in requirements.md traceability table but absent from ALL phase verification.md files MUST be flagged as orphaned. Orphaned requirements are treated as `unsatisfied` — they were assigned but never verified by any phase.
+
+## 6. Aggregate into v{version}-milestone-audit.md
+
+Create `.planning/v{version}-v{version}-milestone-audit.md` with:
+
+```yaml
+---
+milestone: {version}
+audited: {timestamp}
+status: passed | gaps_found | tech_debt
+scores:
+  requirements: N/M
+  phases: N/M
+  integration: N/M
+  flows: N/M
+gaps:  # Critical blockers
+  requirements:
+    - id: "{REQ-ID}"
+      status: "unsatisfied | partial | orphaned"
+      phase: "{assigned phase}"
+      claimed_by_plans: ["{plan files that reference this requirement}"]
+      completed_by_plans: ["{plan files whose SUMMARY marks it complete}"]
+      verification_status: "passed | gaps_found | missing | orphaned"
+      evidence: "{specific evidence or lack thereof}"
+  integration: [...]
+  flows: [...]
+tech_debt:  # Non-critical, deferred
+  - phase: 01-auth
+    items:
+      - "TODO: add rate limiting"
+      - "Warning: no password strength validation"
+  - phase: 03-dashboard
+    items:
+      - "Deferred: mobile responsive layout"
+---
+```
+
+Plus full markdown report with tables for requirements, phases, integration, tech debt.
+
+**Status values:**
+- `passed` — all requirements met, no critical gaps, minimal tech debt
+- `gaps_found` — critical blockers exist
+- `tech_debt` — no blockers but accumulated deferred items need review
+
+## 7. Present Results
+
+Route by status (see `<offer_next>`).
+
+</process>
+
+<offer_next>
+Output this markdown directly (not as a code block). Route based on status:
+
+---
+
+**If passed:**
+
+## ✓ Milestone {version} — Audit Passed
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-milestone-audit.md
+
+All requirements covered. Cross-phase integration verified. E2E flows complete.
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Complete milestone** — archive and tag
+
+/pan:milestone-done {version}
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**If gaps_found:**
+
+## ⚠ Milestone {version} — Gaps Found
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-milestone-audit.md
+
+### Unsatisfied Requirements
+
+{For each unsatisfied requirement:}
+- **{REQ-ID}: {description}** (Phase {X})
+  - {reason}
+
+### Cross-Phase Issues
+
+{For each integration gap:}
+- **{from} → {to}:** {issue}
+
+### Broken Flows
+
+{For each flow gap:}
+- **{flow name}:** breaks at {step}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan gap closure** — create phases to complete milestone
+
+/pan:milestone-gaps
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- cat .planning/v{version}-milestone-audit.md — see full report
+- /pan:milestone-done {version} — proceed anyway (accept tech debt)
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**If tech_debt (no blockers but accumulated debt):**
+
+## ⚡ Milestone {version} — Tech Debt Review
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-milestone-audit.md
+
+All requirements met. No critical blockers. Accumulated tech debt needs review.
+
+### Tech Debt by Phase
+
+{For each phase with debt:}
+**Phase {X}: {name}**
+- {item 1}
+- {item 2}
+
+### Total: {N} items across {M} phases
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Options
+
+**A. Complete milestone** — accept debt, track in backlog
+
+/pan:milestone-done {version}
+
+**B. Plan cleanup phase** — address debt before completing
+
+/pan:milestone-gaps
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+</offer_next>
+
+<success_criteria>
+- [ ] Milestone scope identified
+- [ ] All phase verification.md files read
+- [ ] summary.md `requirements-completed` frontmatter extracted for each phase
+- [ ] requirements.md traceability table parsed for all milestone REQ-IDs
+- [ ] 3-source cross-reference completed (VERIFICATION + SUMMARY + traceability)
+- [ ] Orphaned requirements detected (in traceability but absent from all VERIFICATIONs)
+- [ ] Tech debt and deferred gaps aggregated
+- [ ] Integration checker spawned with milestone requirement IDs
+- [ ] v{version}-milestone-audit.md created with structured requirement gap objects
+- [ ] FAIL gate enforced — any unsatisfied requirement forces gaps_found status
+- [ ] Results presented with actionable next steps
+</success_criteria>