pan-wizard 3.22.0 → 3.24.0

package/pan-wizard-core/references/git-integration.md

@@ -14,9 +14,9 @@ The git log should read like a changelog of what shipped, not a diary of plannin
 | Event                   | Commit? | Why                                              |
 | ----------------------- | ------- | ------------------------------------------------ |
 | BRIEF + ROADMAP created | YES     | Project initialization                           |
-| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
-| RESEARCH.md created     | NO      | Intermediate                                     |
-| DISCOVERY.md created    | NO      | Intermediate                                     |
+| plan.md created         | NO      | Intermediate - commit with plan completion       |
+| research.md created     | NO      | Intermediate                                     |
+| discovery.md created    | NO      | Intermediate                                     |
 | **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
 | **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
 | Handoff created         | YES     | WIP state preserved                              |
@@ -123,13 +123,13 @@ Tasks completed: [N]/[N]
 - [Task 2 name]
 - [Task 3 name]
 
-SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
+SUMMARY: .planning/phases/XX-name/{phase}-{plan}-summary.md
 ```
 
 What to commit:
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/state.md .planning/roadmap.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-plan.md .planning/phases/XX-name/{phase}-{plan}-summary.md .planning/state.md .planning/roadmap.md
 ```
 
 **Note:** Code files NOT included - already committed per-task.
@@ -205,9 +205,9 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 <anti_patterns>
 
 **Still don't commit (intermediate artifacts):**
-- PLAN.md creation (commit with plan completion)
-- RESEARCH.md (intermediate)
-- DISCOVERY.md (intermediate)
+- plan.md creation (commit with plan completion)
+- research.md (intermediate)
+- discovery.md (intermediate)
 - Minor planning tweaks
 - "Fixed typo in roadmap"
 
@@ -228,7 +228,7 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 - Git history becomes primary context source for future Claude sessions
 - `git log --grep="{phase}-{plan}"` shows all work for a plan
 - `git diff <hash>^..<hash>` shows exact changes per task
-- Less reliance on parsing SUMMARY.md = more context for actual work
+- Less reliance on parsing summary.md = more context for actual work
 
 **Failure recovery:**
 - Task 1 committed ✅, Task 2 failed ❌

package/pan-wizard-core/references/guardrails.md

@@ -13,7 +13,10 @@ phase — context compaction may have dropped earlier sections.
 | "Phase tests passed locally, /pan:verify-phase isn't needed" | One run isn't validation. verify-phase checks state consistency, doc sync, blockers, and the full suite — not just the phase's own tests. | Always run `/pan:verify-phase` before marking a phase complete. |
 | "I'll skip /pan:focus-scan and pick the next item myself" | Manual selection ignores priority/budget logic in `focus.cjs`. You'll bias toward easy items and miss higher-priority work. | Use `/pan:focus-scan` → `/pan:focus-plan` → `/pan:focus-exec`. |
 | "I'll bump the model / add a flag / refactor while I'm here" | Scope creep. The user asked for one change; surrounding cleanup belongs in a separate item. | Do only the requested change. Note unrelated cleanup as a TODO for a future focus-scan. |
-| "I'll mark this phase complete; the docs can lag behind" | Doc/state drift compounds. By the next session, the agent reads stale docs and proceeds on false assumptions. | Run `/pan:sync` (or the equivalent doc-sync step) before phase completion. CHANGELOG and version bumps are part of the phase, not after it. |
+| "I'll mark this phase complete; the docs can lag behind" | Doc/state drift compounds. By the next session, the agent reads stale docs and proceeds on false assumptions. | Run the doc-sync step (update CHANGELOG/state and commit via `pan-tools commit`) before phase completion. CHANGELOG and version bumps are part of the phase, not after it. |
+| "The tests pass, so the code is portable" | Tests run on one Node version on one OS. Modern Node auto-detects ESM syntax, so `import`/`export` in a project with no `package.json` passes locally and fails under `"type": "commonjs"` or older Node. | Declare the module type explicitly whenever you emit `import`/`export` or `require` — `"type"` in `package.json`, or `.mjs`/`.cjs` extensions. Never rely on syntax detection. |
+| "It rejects bad input — I wrapped the parser in try/catch" | That only rejects *unparseable* input. Valid JSON of the wrong shape passes through and surfaces as `undefined` in an unrelated caller. | Validate shape after parsing, not just parseability. Assert the expected type/keys and fall back or throw. See `references/verification-patterns.md` → Baseline Checks. |
+| "I'll write the doc now and refine it as I go" | Skeleton-then-refine never converges: field transcripts show planning files rewritten 12-19× and re-read 6-16× in a single step, and every in-flight version of state.md is one a later step can read (P-1808). | Compose the complete document in memory, then issue exactly ONE Write per file per step. Don't re-read a file you wrote this step. Post-write corrections are targeted Edits for a verified defect, never a rewrite. |
 
 ## Code Preservation Principle
 

package/pan-wizard-core/references/model-profile-resolution.md

@@ -24,7 +24,7 @@ Task(
 )
 ```
 
-**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+**Note:** Reasoning-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific model versions.
 
 ## Usage
 

package/pan-wizard-core/references/model-profiles.md

@@ -10,7 +10,7 @@ PAN uses three abstract tiers instead of hardcoded model names:
 
 | Tier | Purpose | Anthropic | OpenAI | Google |
 |------|---------|-----------|--------|--------|
-| `reasoning` | Architecture, planning, complex decisions | inherit (Fable/Opus) | inherit | inherit |
+| `reasoning` | Architecture, planning, complex decisions | inherit (your session's top-tier model) | inherit | inherit |
 | `mid` | Execution, research, verification | Sonnet | mid | mid |
 | `fast` | Read-only extraction, budget tasks | Haiku | fast | fast |
 
@@ -28,55 +28,63 @@ For backward compatibility, legacy Anthropic model names still work:
 
 ---
 
-## Recommended Models (Claude)
+## Choosing a Reasoning-Tier Model (Claude)
 
-PAN never selects your host model — it recommends one. Because the `reasoning` tier is `inherit`, whichever top-tier model you configure in your runtime (Claude Code, etc.) runs every reasoning-tier agent (planner, conductor, executor, hardener…). `mid` and `fast` agents stay on Sonnet/Haiku regardless, so the whole fleet is never on one expensive model.
+PAN never selects your host model — it recommends a *class*. Because the `reasoning` tier is `inherit`, whichever top-tier model you configure in your runtime (Claude Code, etc.) runs the reasoning-tier agents (planner, conductor, executor…). Since the 2026-07 COST RESET that means *every* agent under `quality` and `balanced` (the default), except the ones that pin a model in their own frontmatter — `grep -l '^model: opus' agents/*.md` lists those, and the pin wins on Claude Code. Only the opt-in `budget` profile drops agents to `mid`/`fast`, which on Anthropic map to Sonnet/Haiku.
 
-| Model | Role in PAN | Context | Relative cost | Notes |
-|-------|-------------|---------|---------------|-------|
-| `claude-fable-5` | **Recommended flagship** — deepest long-horizon reasoning; best for the bot army's Mission Control + planning | 1M | ~2× Opus | Runs input safety classifiers (see caveat below); requires 30-day data retention |
-| `claude-opus-4-8` | **Cost-conscious default** — same 1M context + thinking, half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
+The IDs below are *examples* of what you can configure in each class — not an exhaustive or only-valid list. A newer release in the same class behaves the same way here.
 
-**Why Fable is the recommended flagship.** It is Anthropic's most capable widely released model for demanding, long-horizon agentic work — exactly what PAN's hierarchical bot army (Mission Control → squads → workers) asks of its reasoning tier. Select it in your host runtime and `inherit` routes the reasoning-tier agents to it automatically.
+At install time PAN also runs a **best-effort, advisory** capability check on the model ID you have configured (`detectModelCapabilities` in `bin/install-lib.cjs`). It recognizes the current Claude generations by name, and its forward threshold per family is the last reduced-capability release it records rather than the newest release it lists: any Claude ID newer than that boundary — a new major, or a later point release inside a major it already lists — inherits that family's modern profile instead of reporting no capabilities at all. "That family's profile" is the point: a newer Haiku inherits Haiku's, which is not a 1M-context/thinking profile. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. It is a name-matching heuristic, not a live probe of the model, so it can still be imprecise about something released after this table — read it as a hint, not a contract. Either way it decides one thing only: whether the installer prints a capability *warning*. No routing, mode-selection, or feature gate in PAN reads it, so a wrong guess costs you a misleading install-time line and nothing else.
 
-**Fable caveat — the cyber-classifier refusal, and how PAN handles it.** Fable is the only current Claude model that runs input safety classifiers targeting cybersecurity and biology content, and benign *defensive* security tooling can trigger false positives — a successful response with `stop_reason: "refusal"` and `stop_details.category: "cyber"`. In PAN this hits every security path: `/pan:review-deep`, `exec-phase --deep-review`, **and the `focus-auto`/army `security` category** (which was observed refusing in a real project). Two mitigations, in order of reliability:
+| Class | Example model IDs | Role in PAN | Context | Relative cost | Notes |
+|-------|-------------------|-------------|---------|---------------|-------|
+| Fable / Mythos | `claude-fable-5` | **Recommended flagship** — deepest long-horizon reasoning; best for the bot army's Mission Control + planning | 1M | ~2× Opus | Runs input safety classifiers (see caveat below); requires 30-day data retention |
+| Opus | `claude-opus-5`, `claude-opus-4-8` | **Cost-conscious pick** — same 1M context + thinking, about half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
 
-1. **Opus pin (the durable fix).** `pan-hardener`, `pan-reviewer`, and `pan-meta-reviewer` carry `model: opus` in their frontmatter, so on **Claude Code** they run on Opus 4.8 regardless of your session model and never reach Fable's classifier. The `focus-auto` security category routes its vulnerability *assessment* through the Opus-pinned `pan-hardener` for the same reason. This pin is **Claude-Code-only** — it is stripped from the Gemini/OpenCode/Codex/Copilot outputs by the installer, so on the other runtimes run security campaigns on a non-Fable model.
+**Why the Fable class is the recommended flagship.** It is Anthropic's deepest class for demanding, long-horizon agentic work — exactly what PAN's hierarchical bot army (Mission Control → squads → workers) asks of its reasoning tier. Select the current release in that class in your host runtime and `inherit` routes the reasoning-tier agents to it automatically.
+
+**Fable caveat — the cyber-classifier refusal, and how PAN handles it.** Fable-class models run input safety classifiers targeting cybersecurity and biology content, and benign *defensive* security tooling can trigger false positives — a successful response with `stop_reason: "refusal"` and `stop_details.category: "cyber"`. In PAN this hits every security path: `/pan:review-deep`, `exec-phase --deep-review`, **and the `focus-auto`/army `security` category** (which was observed refusing in a real project). Two mitigations, in order of reliability:
+
+1. **Opus pin (the durable fix).** PAN's security-review agents carry `model: opus` in their frontmatter — `grep -l '^model: opus' agents/*.md` lists the current set — so on **Claude Code** they run on the default Opus model regardless of your session model and never reach Fable's classifier. The `focus-auto` security category routes its vulnerability *assessment* through the Opus-pinned `pan-hardener` for the same reason. This pin is **Claude-Code-only** — it is stripped from the Gemini/OpenCode/Codex/Copilot outputs by the installer, so on the other runtimes run security campaigns on a non-Fable model.
 2. **Defensive framing.** Those agents and the `focus-auto` security prose are written as *authorized, defensive review* (no exploit-path narration), which lowers the trigger rate but cannot eliminate it — a security scanner must name injection, auth bypass, and RCE by definition. Framing is the backstop; the Opus pin is the fix.
 
 **Fable data-retention requirement.** Fable is not available under zero data retention; an org whose retention is below 30 days gets a hard `400` on every request. If Fable 400s on every call with an otherwise-valid request, check the org's retention setting before debugging anything else.
 
-**Prompting note for Fable.** Fable prefers *less-prescriptive* prompts than earlier models and runs longer per turn. PAN's autonomous-loop guidance (anti-overplanning, grounded progress claims, act-when-you-have-enough) already aligns with this; avoid piling on `CRITICAL: YOU MUST` scaffolding, which can reduce Fable's output quality.
+**Prompting note for Fable.** Fable-class models prefer *less-prescriptive* prompts than earlier generations and run longer per turn. PAN's autonomous-loop guidance (anti-overplanning, grounded progress claims, act-when-you-have-enough) already aligns with this; avoid piling on `CRITICAL: YOU MUST` scaffolding, which can reduce Fable's output quality.
 
 ---
 
 ## Profile Definitions
 
+Since the 2026-07 **COST RESET**, `quality` and `balanced` are identical — both route every agent to the `reasoning` tier. Only the opt-in `budget` profile steps agents below reasoning (to `mid`/`fast` per the last column). The table below is illustrative; `core.cjs` `MODEL_PROFILES` is the source of truth and covers the full agent roster.
+
 | Agent | `quality` | `balanced` | `budget` |
 |-------|-----------|------------|----------|
 | pan-planner | reasoning | reasoning | mid |
-| pan-roadmapper | reasoning | mid | mid |
-| pan-executor | reasoning | mid | mid |
-| pan-phase-researcher | reasoning | mid | fast |
-| pan-project-researcher | reasoning | mid | fast |
-| pan-research-synthesizer | reasoning | mid | fast |
-| pan-debugger | reasoning | mid | mid |
-| pan-document_code | reasoning | fast | fast |
-| pan-verifier | reasoning | mid | fast |
-| pan-plan-checker | reasoning | mid | fast |
-| pan-integration-checker | reasoning | mid | fast |
-| pan-reviewer | reasoning | fast | fast |
+| pan-roadmapper | reasoning | reasoning | mid |
+| pan-executor | reasoning | reasoning | mid |
+| pan-phase-researcher | reasoning | reasoning | fast |
+| pan-project-researcher | reasoning | reasoning | fast |
+| pan-research-synthesizer | reasoning | reasoning | fast |
+| pan-debugger | reasoning | reasoning | mid |
+| pan-document_code | reasoning | reasoning | fast |
+| pan-verifier | reasoning | reasoning | fast |
+| pan-plan-checker | reasoning | reasoning | fast |
+| pan-integration-checker | reasoning | reasoning | fast |
+| pan-reviewer | reasoning | reasoning | fast |
 
 ### Profile Philosophy
 
+Post-COST-RESET, `quality` and `balanced` are the same profile in practice — both give every agent the `reasoning` tier. Cost savings come only from opting into `budget`.
+
 **quality** — Maximum reasoning power
 - Reasoning tier for ALL agents. Use when quota is available, critical architecture work, or maximum quality is desired.
 
-**balanced** (default) — Smart allocation
-- Reasoning only for planning (where architecture decisions happen). Mid for execution. Fast for read-only tasks. Good balance of quality and cost.
+**balanced** (default) — Reasoning everywhere
+- Identical to `quality` since the COST RESET: reasoning tier for every agent. It remains the default so new projects get full reasoning power out of the box. Switch to `budget` when you need to cut token spend.
 
 **budget** — Minimal token spend
-- Mid for anything that writes code. Fast for research and verification. Use for high-volume work or less critical phases.
+- The only profile that steps agents below reasoning: mid for anything that writes code, fast for research and verification (see the `budget` column). Use for high-volume work or less critical phases.
 
 ### Cost Multipliers
 
@@ -246,17 +254,19 @@ Runtime: `/pan:profile <profile>`
 
 ## Design Rationale
 
-**Why reasoning for pan-planner?**
-Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
+Since the 2026-07 COST RESET, `quality` and `balanced` put every agent on the `reasoning` tier — so the notes below explain the tier each agent *steps down to* under `budget`, the only profile that now drops below reasoning.
+
+**Why reasoning for pan-planner (and every agent under quality/balanced)?**
+Planning involves architecture decisions, goal decomposition, and task design — where model quality has the highest impact. Post-COST-RESET the reasoning tier is inexpensive enough that every agent stays on it unless you opt into budget.
 
-**Why mid for pan-executor?**
-Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
+**Why mid for pan-executor under budget?**
+Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation, so `budget` can safely step them to mid.
 
-**Why mid (not fast) for verifiers in balanced?**
-Verification requires goal-backward reasoning — checking if code *delivers* what the phase promised, not just pattern matching.
+**Why fast for verifiers under budget?**
+Verification ideally uses goal-backward reasoning, but under `budget` the check degrades gracefully to fast pattern-matching to save tokens.
 
-**Why fast for pan-document_code?**
+**Why fast for pan-document_code under budget?**
 Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
 
-**Why fast for pan-reviewer in balanced?**
-Code review is pattern-matching against known conventions and security rules. Fast handles checklist-style verification efficiently.
+**Why fast for pan-reviewer under budget?**
+Code review is pattern-matching against known conventions and security rules. Fast handles checklist-style verification efficiently when budget is engaged.

package/pan-wizard-core/references/planning-config.md

@@ -101,7 +101,7 @@ To use uncommitted mode:
    git commit -m "chore: stop tracking planning docs"
    ```
 
-4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `milestone-done` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
 
 </setup_uncommitted_mode>
 
@@ -113,7 +113,7 @@ To use uncommitted mode:
 |----------|---------------------|--------------|-------------|
 | `none` | Never | N/A | N/A |
 | `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `milestone-done` |
 
 **When `git.branching_strategy: "none"` (default):**
 - All work commits to current branch
@@ -124,13 +124,13 @@ To use uncommitted mode:
 - Branch name from `phase_branch_template` (e.g., `pan/phase-03-authentication`)
 - All plan commits go to that branch
 - User merges branches manually after phase completion
-- `complete-milestone` offers to merge all phase branches
+- `milestone-done` offers to merge all phase branches
 
 **When `git.branching_strategy: "milestone"`:**
 - First `execute-phase` of milestone creates the milestone branch
 - Branch name from `milestone_branch_template` (e.g., `pan/v1.0-mvp`)
 - All phases in milestone commit to same branch
-- `complete-milestone` offers to merge milestone branch to main
+- `milestone-done` offers to merge milestone branch to main
 
 **Template variables:**
 
@@ -172,7 +172,7 @@ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
 fi
 ```
 
-**Merge options at complete-milestone:**
+**Merge options at milestone-done:**
 
 | Option | Git command | Result |
 |--------|-------------|--------|

package/pan-wizard-core/references/verification-patterns.md

@@ -556,6 +556,73 @@ Run these checks against each must-have artifact. Aggregate results into VERIFIC
 
 </automated_verification_script>
 
+<criteria_independent_baseline>
+
+## Baseline Checks That Ignore the Success Criteria
+
+Criterion-driven verification only sees what someone wrote down. A defect that sits
+outside a phase's stated success criteria is invisible to a verifier that walks the
+criteria list — the phase passes, and the bug ships. Run the checks below on every
+phase regardless of what the criteria say.
+
+### Module system is declared, not inferred
+
+Node 20.19+ and 22+ auto-detect ESM syntax in `.js` files with no `package.json`.
+Code that only runs because of that detection breaks under an explicit
+`"type": "commonjs"`, on older Node, and in any bundler that trusts the manifest:
+
+```
+SyntaxError: Cannot use import statement outside a module
+```
+
+Tests do not catch it — they run on the same forgiving Node that hid it.
+
+```bash
+# If any shipped source uses ESM syntax...
+grep -rlE '^\s*(import|export)\s' src/ --include='*.js'
+
+# ...then a package.json must exist and declare the module type.
+test -f package.json && grep -q '"type"' package.json || echo "FAIL: ESM emitted with no declared module type"
+```
+
+Verify the declaration matches the syntax in use: `"type": "module"` for
+`import`/`export`, `"type": "commonjs"` for `require`/`module.exports`, or the
+`.mjs`/`.cjs` extensions to opt individual files out. A project claiming
+cross-platform or multi-Node support has not met that claim until this is explicit.
+
+### Input validation checks shape, not just parseability
+
+"Rejects malformed input" is routinely implemented as a `try`/`catch` around a
+parser. That catches unparseable bytes and nothing else — valid JSON of the wrong
+shape passes straight through, and the caller gets `undefined` two frames later:
+
+```js
+// Passes a parseability test; returns [] for a file containing "[]",
+// leaving .todos undefined for every downstream caller.
+function load(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf-8')); }
+  catch { return { todos: [] }; }
+}
+```
+
+For every function that reads external input (file, network, env, CLI argument),
+confirm both halves:
+
+| Check | Weak version | What to require |
+|---|---|---|
+| Unparseable input | `try`/`catch` around the parser | Same — this half is usually right |
+| Wrong-shape input | *(absent)* | Assert the expected type/keys after parsing, then fall back or throw |
+
+```bash
+# Parsers that return their result unchecked are the pattern to look for
+grep -rnE 'JSON\.parse\([^)]*\)' src/ | grep -v -E 'typeof|Array\.isArray|schema|validate'
+```
+
+Fixture the wrong-shape case explicitly: feed the loader `[]`, `null`, `{}`, and
+`{"todos": "not-an-array"}`, and assert the caller still gets a usable value.
+
+</criteria_independent_baseline>
+
 <human_verification_triggers>
 
 ## Verifiable Signals Beat Prose Judgment (P-RES-006)

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

@@ -1,6 +1,6 @@
 # Architecture Template
 
-Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code organization.
+Template for `.planning/codebase/architecture.md` - captures conceptual code organization.
 
 **Purpose:** Document how the code is organized at a conceptual level. Complements STRUCTURE.md (which shows physical file locations).
 

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

@@ -1,6 +1,6 @@
 # Codebase Concerns Template
 
-Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas requiring care.
+Template for `.planning/codebase/concerns.md` - captures known issues and areas requiring care.
 
 **Purpose:** Surface actionable warnings about the codebase. Focused on "what to watch out for when making changes."
 

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

@@ -1,6 +1,6 @@
 # Coding Conventions Template
 
-Template for `.planning/codebase/CONVENTIONS.md` - captures coding style and patterns.
+Template for `.planning/codebase/conventions.md` - captures coding style and patterns.
 
 **Purpose:** Document how code is written in this codebase. Prescriptive guide for Claude to match existing style.
 

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

@@ -1,6 +1,6 @@
 # External Integrations Template
 
-Template for `.planning/codebase/INTEGRATIONS.md` - captures external service dependencies.
+Template for `.planning/codebase/integrations.md` - captures external service dependencies.
 
 **Purpose:** Document what external systems this codebase communicates with. Focused on "what lives outside our code that we depend on."
 

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

@@ -1,6 +1,6 @@
 # Technology Stack Template
 
-Template for `.planning/codebase/STACK.md` - captures the technology foundation.
+Template for `.planning/codebase/stack.md` - captures the technology foundation.
 
 **Purpose:** Document what technologies run this codebase. Focused on "what executes when you run the code."
 

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

@@ -1,6 +1,6 @@
 # Structure Template
 
-Template for `.planning/codebase/STRUCTURE.md` - captures physical file organization.
+Template for `.planning/codebase/structure.md` - captures physical file organization.
 
 **Purpose:** Document where things physically live in the codebase. Answers "where do I put X?"
 

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

@@ -1,6 +1,6 @@
 # Testing Patterns Template
 
-Template for `.planning/codebase/TESTING.md` - captures test framework and patterns.
+Template for `.planning/codebase/testing.md` - captures test framework and patterns.
 
 **Purpose:** Document how tests are written and run. Guide for adding tests that match existing patterns.
 

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: