pan-wizard 3.22.0 → 3.25.0

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

@@ -0,0 +1,146 @@
+# Design Artifact Template
+
+Template for `{scope}-design.md` — the design a change carries **before** it is
+planned or executed. Produced by `pan-designer` (per phase, via
+`/pan:design-phase`) or `focus-design` (per feature). Held to the quality bar in
+`references/design-methodology.md` and verified by `pan-design-checker`.
+
+**Purpose:** Capture the *how* (and, at deeper tiers, the *whether/what*) of a
+change — architecture, decisions, ADR, threats, and machine-checkable success
+criteria — so the planner builds against a verified design instead of improvising
+architecture inside the plan.
+
+**Depth tiers** select which sections are mandatory (see
+`references/design-methodology.md`): `spike` < `phase` < `feature` < `full`.
+Sections are labeled with the tier at which they become **required**; a shallower
+tier may omit them.
+
+**Downstream consumers:**
+- `pan-planner` — reads locked decisions, interface contract, and file scope to create tasks that implement the approved design (same way it reads `context.md`).
+- `pan-plan-checker` — verifies the plan conforms to this design (Design Conformance dimension).
+- `pan-design-checker` — verifies THIS artifact against the quality bar before it is handed off.
+
+---
+
+## File Template
+
+```markdown
+# [Scope]: [Name] — Design
+
+**Tier:** spike | phase | feature | full
+**Designed:** [date]
+**Status:** Draft | Verified (pan-design-checker) | Superseded
+
+<problem>
+## Problem & Scope        <!-- all tiers -->
+
+**Problem:** [What problem exists, why it matters, cost of inaction. Concrete.]
+
+**In scope:** [What this design covers]
+**Out of scope / boundary:** [The fixed boundary this must not exceed — phase boundary from roadmap.md, or feature boundary]
+</problem>
+
+<success_criteria>
+## Success Criteria        <!-- phase+ -->
+
+[3–7 criteria. At least 2 MUST be machine-checkable — name the automated check.]
+
+| # | Criterion | Machine-checkable? | Check |
+|---|-----------|--------------------|-------|
+| SC-1 | [criterion] | yes | [test / command that verifies it] |
+| SC-2 | [criterion] | yes | [test / command that verifies it] |
+| SC-3 | [criterion] | no  | [how confirmed] |
+</success_criteria>
+
+<architecture>
+## Architecture & Synthesis        <!-- phase+ -->
+
+**Discovered conventions:** [Actual conventions extracted from the codebase — module layout, error style, boundaries. Cite files. Do not assume.]
+
+**Components & boundaries:** [Modules added/touched; confirm no layer/boundary violation against the discovered conventions.]
+
+**Interface contract:** [Exact invocation + input/output schema + status/exit codes, per project convention.]
+
+**State & filesystem scope:**
+- Reads from: [paths — within project root]
+- Writes to: [paths — within .planning/ or project root]
+- Side effects: [git ops, dir creation, etc.]
+
+**Design decisions:**
+| Decision | Chosen | Alternative rejected | Rationale |
+|----------|--------|----------------------|-----------|
+| [point] | [what] | [alt] | [why] |
+</architecture>
+
+<adr>
+## ADR        <!-- phase+ (phase = inline; feature/full = standalone docs/decisions/ADR-NNNN) -->
+
+**Context:** [Problem, forces/constraints, current state, requirements traceability.]
+**Decision:** [Summary + numbered sub-decisions, each with rationale.]
+**Consequences:** [Positive AND negative. Every negative has a mitigation or explicit acceptance — no unmitigated costs, no placeholder sections.]
+</adr>
+
+<threats>
+## Threat Model        <!-- phase = lite (own surface); feature+ = full STRIDE-lite -->
+
+| Threat | Vector | Mitigation (or explicit acceptance) |
+|--------|--------|-------------------------------------|
+| [threat] | [how] | [mitigation] |
+</threats>
+
+<error_handling>
+## Error Handling & Diagnostics        <!-- feature+ -->
+
+| Condition | Output shape | Handling style |
+|-----------|-------------|----------------|
+| [error] | [output] | [validate-before-side-effect / safe-read-null / actionable message] |
+</error_handling>
+
+<test_plan>
+## Test Plan        <!-- phase = hooks; feature+ = full -->
+
+[How each success criterion is verified — unit vs scenario, and the seed inputs for the machine-checkable ones.]
+</test_plan>
+
+<strategy>
+## Demand & Strategy        <!-- feature (demand + ladder); full (+ competitive, ERRC, adoption) -->
+
+**Demand evidence:** [Evidence, or explicit "speculative — no demand evidence" flag.]
+**Feature ladder:** v0 (MVP) → v1 (complete) → v2 (enhanced).
+[full tier: competitive intelligence, ERRC strategic analysis, adoption analysis.]
+</strategy>
+
+<deferred>
+## Deferred Ideas        <!-- all tiers -->
+
+[Scope-expanding ideas that came up — captured so they're not lost, explicitly NOT designed in.]
+[If none: "None — design stayed within boundary."]
+</deferred>
+
+---
+
+*Scope: [phase XX-name | feature-name]*
+*Tier: [tier] · Designed: [date] · Verified: [date or "pending"]*
+```
+
+<guidelines>
+**This template captures a VERIFIED design for downstream agents.**
+
+The output should answer: "What is the architecture, what was decided and why,
+how do we know it's safe, and how will we prove it works?"
+
+**Good content (concrete, verifiable):**
+- "Add `resolveRate()` to cost.cjs; longest-prefix match so tier keys win — SC verified by tests/cost.test.cjs"
+- "Negative consequence: per-phase latency → mitigated by auto-skip + design.md caching"
+- "Threat: agent-supplied path escapes tmpdir → mitigated by tmpRoot prefix + basename check"
+
+**Bad content (vague, unverifiable):**
+- "Good architecture"
+- "Handles errors well"
+- "Secure by design"
+
+**After creation:**
+- Main flow: file lives in the phase directory as `{phase_num}-design.md`; `pan-planner` consumes it.
+- Focus flow: the ADR is written standalone to `docs/decisions/`; the spec to `docs/specs/`.
+- `pan-design-checker` must pass the artifact (or exhaust 2 reflexion iterations) before it is handed to planning.
+</guidelines>

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

@@ -1,8 +1,8 @@
 # Discovery Template
 
-Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for library/option decisions.
+Template for `.planning/phases/XX-name/discovery.md` - shallow research for library/option decisions.
 
-**Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase.
+**Purpose:** Answer "which library/option should we use" questions when a phase needs a quick option comparison before planning.
 
 For deep ecosystem research ("how do experts build this"), use `/pan:research-phase` which produces research.md.
 
@@ -71,7 +71,7 @@ Before completing discovery, verify:
 
 
 <output_structure>
-Create `.planning/phases/XX-name/DISCOVERY.md`:
+Create `.planning/phases/XX-name/discovery.md`:
 
 ```markdown
 # [Topic] Discovery

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

@@ -1,6 +1,6 @@
 # Milestone Archive Template
 
-This template is used by the complete-milestone workflow to create archive files in `.planning/milestones/`.
+This template is used by the milestone-done workflow to create archive files in `.planning/milestones/`.
 
 ---
 
@@ -98,7 +98,7 @@ _For current project status, see .planning/roadmap.md_
 <guidelines>
 **When to create milestone archives:**
 - After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.)
-- Triggered by complete-milestone workflow
+- Triggered by milestone-done workflow
 - Before planning next milestone work
 
 **How to fill template:**

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

@@ -1,5 +1,5 @@
 <!--
-Template for .planning/PLAYBOOK.md generated by `/pan:knowledge playbook`.
+Template for .planning/playbook.md generated by `/pan:knowledge playbook`.
 Populated by knowledge.cjs buildPlaybook() + writePlaybook() from the
 accumulated lessons in `.planning/memory/*.md`.
 

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

@@ -106,7 +106,7 @@ skipped: [N]
 
 **After testing complete (status: complete), if gaps exist:**
 
-1. User runs diagnosis (from verify-work offer or manually)
+1. User runs diagnosis (from verify-phase 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:

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

@@ -64,7 +64,7 @@ Spawning parallel debug agents to investigate root causes:
 | Delete removes comment | blocker |
 
 Each agent will:
-1. Create DEBUG-{slug}.md with symptoms pre-filled
+1. Create ${DEBUG_DIR}/{slug}.md with symptoms pre-filled
 2. Investigate autonomously (read code, form hypotheses, test)
 3. Return root cause
 
@@ -80,22 +80,24 @@ 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="general-purpose",
-  description="Debug: {truth_short}"
+  subagent_type="pan-debugger",
+  description="Debug: {issue_summary_short}"
 )
 ```
 
 **All agents spawn in single message** (parallel execution).
 
-Template placeholders:
-- `{truth}`: The expected behavior that failed
+Template placeholders (see `debug-subagent-prompt.md`):
+- `{issue_id}`: Stable id for the gap, e.g. `UAT-{test_num}`
+- `{issue_summary}`: The expected behavior that failed
 - `{expected}`: From UAT test
 - `{actual}`: Verbatim user description from reason field
 - `{errors}`: Any error messages from UAT (or "None reported")
 - `{reproduction}`: "Test {test_num} in UAT"
 - `{timeline}`: "Discovered during UAT"
+- `{true_or_false}`: `true` (symptoms are prefilled from the UAT gap)
 - `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
-- `{slug}`: Generated from truth
+- `{slug}`: Generated from the issue summary
 </step>
 
 <step name="collect_results">
@@ -200,7 +202,7 @@ Agents only diagnose—plan-phase --gaps handles fixes (no fix application).
 - Report incomplete diagnosis
 
 **Agent times out:**
-- Check DEBUG-{slug}.md for partial progress
+- Check ${DEBUG_DIR}/{slug}.md for partial progress
 - Can resume with /pan:debug
 
 **All agents fail:**

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

@@ -160,7 +160,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
 2. **Spawn executor agents:**
 
-   Pass paths only — executors read files themselves with their fresh 200k context.
+   Pass paths only — executors read files themselves in their own fresh context window.
    This keeps orchestrator context lean (~10-15%).
 
    ```
@@ -286,11 +286,23 @@ When executor returns a checkpoint AND `AUTO_CFG` is `"true"`:
    [Awaiting section from agent return]
    ```
 5. User responds: "approved"/"done" | issue description | decision selection
-6. **Spawn continuation agent (NOT resume)** using continuation-prompt.md template:
-   - `{completed_tasks_table}`: From checkpoint return
-   - `{resume_task_number}` + `{resume_task_name}`: Current task
-   - `{user_response}`: What user provided
-   - `{resume_instructions}`: Based on checkpoint type
+6. **Spawn continuation agent (NOT resume)** with a prompt built inline from this structure:
+   ```
+   Continue executing plan {plan_id}. A previous agent paused at a checkpoint.
+
+   ## Already completed
+   {completed_tasks_table}    ← the completed-tasks table from the checkpoint return
+
+   ## Resume point
+   Task {resume_task_number}: {resume_task_name}    ← the current (paused) task
+   User response to checkpoint: {user_response}      ← "approved"/"done", the chosen decision option, or the issue description the user typed
+
+   ## Instructions
+   {resume_instructions}      ← derived from the checkpoint type: human-verify → "resume the paused task";
+                                decision → "apply the selected option, then continue"; issue → "address the
+                                described issue first, then continue". Verify the previous commits before proceeding.
+   ```
+   All five placeholders are defined here — there is no separate template file to load.
 7. Continuation agent verifies previous commits, continues from resume point
 8. Repeat until plan completes or user stops
 
@@ -602,7 +614,7 @@ The CLI handles:
 
 Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
 
-**Phase reports (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the self-contained per-phase HTML report — and, when `workflow.phase_reports.index` is `true`, the project timeline index — at this verify→complete gate so they ship with the phase and ride the commit below. Disabled by default; phase-less projects are skipped automatically by `report`. Never opens a browser here (that's reserved for a manual `pan-tools report --open`).
+**Phase reports (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the self-contained per-phase HTML report — and, when `workflow.phase_reports.index` is `true`, the project timeline index — at this verify→complete gate so they ship with the phase and ride the commit below. Disabled by default; phase-less projects are skipped automatically by `report`. Never opens a browser here (that's reserved for a manual `pan-tools report index --open`).
 
 ```bash
 REPORT_FILES=""
@@ -704,6 +716,10 @@ STOP — do not auto-advance. Return to user.
    ```bash
    AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
    ```
+3. **If `--auto` flag present AND `AUTO_CFG` is not true — persist it** (same as discuss-phase's auto_advance step). The flag lives only in this invocation's arguments; the rest of the chain, and the P-1809 stop guard, can only see the run as autonomous if the disk says so (P-1810 — the guard missed a real boundary drop because a flag-driven run left config unarmed):
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance true
+   ```
 
 **If `--auto` flag present OR `AUTO_CFG` is true (AND verification passed with no gaps):**
 
@@ -718,6 +734,10 @@ Execute the transition workflow inline (do NOT use Task — orchestrator context
 
 Read and follow `~/.claude/pan-wizard-core/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.
 
+**Contract (P-1807):** transition.md's continuation gates key on the same trigger you just evaluated (`--auto` flag, `workflow.auto_advance`, or `mode: yolo`) — NOT on `mode` alone. Having announced AUTO-ADVANCING, the transition must end in a `Task(...)` spawn of the next phase (Route A) or reach the milestone boundary (Route B). If you find yourself printing a "Next Up" menu and stopping after the banner above, that is the P-1801/P-1807 regression, not a valid outcome.
+
+**Post-transition self-check (MANDATORY final action in auto mode):** after transition.md finishes, confirm one of its two valid terminal states actually happened: (a) a `Task(...)` spawn for the next phase was issued (Route A), or (b) the milestone boundary was reached (Route B). If neither — state was updated but no spawn went out — you are inside the P-1801/P-1807 failure right now: return to transition.md `offer_next_phase` Route A and issue the Task spawn before ending your turn.
+
 **If neither `--auto` nor `AUTO_CFG` is true:**
 
 The workflow ends. The user runs `/pan:progress` or invokes the transition workflow manually.
@@ -726,7 +746,7 @@ The workflow ends. The user runs `/pan:progress` or invokes the transition workf
 </process>
 
 <context_efficiency>
-Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task blocks). No context bleed.
+Orchestrator: ~10-15% context. Subagents: a fresh window each. No polling (Task blocks). No context bleed.
 </context_efficiency>
 
 <failure_handling>

package/pan-wizard-core/workflows/execute-plan.md

@@ -94,14 +94,13 @@ Fresh context per subagent preserves peak quality. Main context stays lean.
 if [ ! -f .planning/agent-history.json ]; then
   echo '{"version":"1.0","max_entries":50,"entries":[]}' > .planning/agent-history.json
 fi
-rm -f .planning/current-agent-id.txt
 if [ -f .planning/current-agent-id.txt ]; then
   INTERRUPTED_ID=$(cat .planning/current-agent-id.txt)
   echo "Found interrupted agent: $INTERRUPTED_ID"
 fi
 ```
 
-If interrupted: ask user to resume (Task `resume` parameter) or start fresh.
+If interrupted: ask user to resume (Task `resume` parameter) or start fresh. Only AFTER that decision (per the tracking protocol below — resume detection must see the stale id first) clear the marker with `rm -f .planning/current-agent-id.txt`.
 
 **Tracking protocol:** On spawn: write agent_id to `current-agent-id.txt`, append to agent-history.json: `{"agent_id":"[id]","task_description":"[desc]","phase":"[phase]","plan":"[plan]","segment":[num|null],"timestamp":"[ISO]","status":"spawned","completion_timestamp":null}`. On completion: status → "completed", set completion_timestamp, delete current-agent-id.txt. Prune: if entries > max_entries, remove oldest "completed" (never "spawned").
 
@@ -423,7 +422,7 @@ FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase
 git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
 ```
 
-Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes.
+Update only structural changes: new src/ dir → structure.md | deps → stack.md | file pattern → conventions.md | API client → integrations.md | config → stack.md | renamed → update paths. Skip code-only/bugfix/content changes.
 
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "" --files .planning/codebase/*.md --amend

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

@@ -157,9 +157,32 @@ Report final status.
 | W003 | warning | config.json not found | Yes |
 | W004 | warning | config.json invalid field value | No |
 | W005 | warning | Phase directory naming mismatch | No |
-| W006 | warning | Phase in ROADMAP but no directory | No |
+| W006 | warning | Phase in ROADMAP at or behind current phase, but no directory | No |
 | W007 | warning | Phase on disk but not in ROADMAP | No |
 | I001 | info | Plan without SUMMARY (may be in progress) | No |
+| I002 | info | Phase in ROADMAP ahead of current phase, not planned yet | No |
+| STATE_REQ_DRIFT | warning | state.md complete but REQUIREMENTS.md has unchecked boxes | Yes |
+| STATE_ROADMAP_DRIFT | warning | state.md complete but roadmap.md has unchecked plan boxes | Yes |
+| VERIFICATION_GATE_MISSING | warning | Phase has completed plans but no verification record | No |
+
+Flag-gated codes:
+
+| Code | Severity | Flag | Description | Repairable |
+|------|----------|------|-------------|------------|
+| TESTS_FAIL | error | --full | Test run exited non-zero | No |
+| BUILD_FAIL | error | --full | Build exited non-zero | No |
+| MEM_BUDGET | warning / info | --full | Memory injection over budget | No |
+| DRIFT_HIGH | warning | --drift | Drift verdict is high | No |
+| DRIFT_MEDIUM | info | --drift | Drift verdict is medium | No |
+| LINKS_ERR | warning | --links | Link graph has errors | No |
+| STD-000 | info | --standards | No standards.md found | No |
+| STD-001 | info | --standards | standards.md has no recognized standards | No |
+| STD-*id* | warning / info | --standards | Per-standard coverage (warning at 0%) | No |
+| STD-SUMMARY | info | --standards | Overall coverage across standards | No |
+
+**I002 vs W006:** a roadmap phase the project has not reached yet is normal progress,
+not a defect — it reports as info and does not degrade health. Only a missing phase at
+or behind the current position warns.
 
 </error_codes>
 

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

@@ -1,5 +1,5 @@
 <purpose>
-Display the complete PAN command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
+Display the PAN command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
 </purpose>
 
 <reference>
@@ -148,7 +148,6 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 **Flags:**
 - `--mode <mode>` — select execution mode (default: balanced)
 - `--budget N` — override point budget (5-100)
-- `--dry-run` — show what would be selected without writing
 - `--lean` — exclude items with RS < 1.5
 
 ### Step 3: `/pan:focus-exec`
@@ -208,7 +207,9 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 ---
 
-## All Commands (42)
+## All Commands
+
+> This table is a **curated subset** of the most-used commands, not an exhaustive list. For the full, always-current command set, browse the `commands/pan/*.md` files in your install (each `.md` is one `/pan:<name>` command).
 
 ### Getting Started
 | Command | Description |
@@ -389,7 +390,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:settings`** — Toggle researcher, plan checker, verifier agents. Select model profile.
 
-**`/pan:profile <name>`** — Quick profile switch: `quality` (Opus everywhere), `balanced` (Opus plan + Sonnet exec, default), `budget` (Sonnet + Haiku).
+**`/pan:profile <name>`** — Quick profile switch: `quality` and `balanced` (reasoning tier for every agent; `balanced` is the default), `budget` (mid tier for writing, fast tier for research/verification).
 
 **Planning config** (`.planning/config.json`):
 - `commit_docs: true` — commit planning artifacts to git (set `false` + add `.planning/` to `.gitignore` for private planning)

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

@@ -16,12 +16,12 @@ Analyze the most recent trace session and generate a circular optimization repor
 
 Run:
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
 ```
 
 If no active session, run:
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace list
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace list
 ```
 Use the most recent session unless `--session <id>` was specified.
 
@@ -31,7 +31,7 @@ If `--session <id>` was specified, use that session ID.
 
 Run:
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize learn [--session <id>]
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn [--session <id>]
 ```
 
 This produces `.planning/optimization/reports/{session}-analysis.json`.
@@ -67,7 +67,7 @@ Present to the user:
 
 If the `--apply` flag was passed, immediately run:
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize apply
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize apply
 ```
 
 Show what was applied and what still needs review.
@@ -82,7 +82,7 @@ After applying, tell the user what to watch in the next run:
 ## Edge cases
 
 **No events in trace:**
-- Tell the user the trace session is empty. They may need to ensure the `pan-trace-logger` hook is registered in `.claude/settings.json`.
+- Tell the user the trace session is empty. They may need to ensure the `pan-trace-logger` hook is registered in `~/.claude/settings.json`.
 
 **Too few events (< 5):**
 - The optimizer can still run but note the small sample size.

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

@@ -315,7 +315,7 @@ 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
+3. Consider adding sensitive files to your AI coding tool's deny/ignore list
 
 Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
 ```

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

@@ -129,7 +129,7 @@ For each REQ-ID, determine status using all three sources:
 
 ## 6. Aggregate into v{version}-milestone-audit.md
 
-Create `.planning/v{version}-v{version}-milestone-audit.md` with:
+Create `.planning/v{version}-milestone-audit.md` with:
 
 ```yaml
 ---

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

@@ -17,12 +17,12 @@ Read all files referenced by the invoking prompt's execution_context before star
 - Read project.md (existing project, validated requirements, decisions)
 - Read milestones.md (what shipped previously)
 - Read state.md (pending todos, blockers)
-- Check for MILESTONE-context.md (from /pan:discuss-milestone)
+- Check for MILESTONE-context.md (optional pre-seeded context, if the user prepared one)
 
 ## 2. Gather Milestone Goals
 
 **If MILESTONE-context.md exists:**
-- Use features and scope from discuss-milestone
+- Use features and scope from MILESTONE-context.md
 - Present summary for confirmation
 
 **If no context file:**
@@ -151,7 +151,7 @@ Use template: ~/.claude/pan-wizard-core/templates/research-project/{FILE}
 | QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
 | CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
 | GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
-| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
+| FILE | stack.md | features.md | architecture.md | pitfalls.md |
 
 After all 4 complete, spawn synthesizer:
 
@@ -195,7 +195,7 @@ Display key findings from summary.md:
 
 Read project.md: core value, current milestone goals, validated requirements (what exists).
 
-**If research exists:** Read FEATURES.md, extract feature categories.
+**If research exists:** Read features.md, extract feature categories.
 
 Present features by category:
 ```