pan-wizard 3.22.0 → 3.25.0

package/pan-wizard-core/learnings/universal/concurrency.md

@@ -18,7 +18,7 @@ patterns:
 
 ## P-1204 — O_EXCL lockfile + retry with bounded backoff is enough for multi-process file writes in Node — no flock needed
 
-**Evidence:** whoocache lock.js + atomic-write.js: parallel-process tests with two child processes each calling set() 1000 times completed with consistent index, zero lost writes. P-1402 (whoocache 02-02 summary): 'O_EXCL lockfile + Windows rename retry' shipped Phase 2.
+**Evidence:** whoocache lock.js + atomic-write.js: parallel-process tests with two child processes each calling set() 1000 times completed with consistent index, zero lost writes. The whoocache 02-02 summary records 'O_EXCL lockfile + Windows rename retry' shipped Phase 2.
 
 **Rule:** For multi-process safe writes (parallel CLI invocations sharing one cache/index/state file), use fs.openSync(lockPath, 'wx') as a 'try-acquire' (EEXIST means held). On failure, retry with random backoff 5-50ms, capped at ~10 attempts. Always wrap acquired work in try/finally and unlink the lockfile in finally. Cross-platform safe (no flock dependency). Combine with the atomic write-tmp-then-rename pattern (P-1201) so even if the lock holder is killed mid-write, recovery is automatic.
 

package/pan-wizard-core/references/design-methodology.md

@@ -0,0 +1,94 @@
+# Design Methodology (shared)
+
+Single source of truth for how PAN designs a change **before** it is planned or
+executed. Cited by `pan-designer` (main flow, via `/pan:design-phase`) and by
+`focus-design` (the `/featureAI` feature pipeline). Both flows use the *same*
+method at different **depth tiers** so design quality can't drift between them.
+
+This reference defines: the depth tiers, what each tier must produce, and the
+quality bar every design artifact is held to (the same bar `pan-design-checker`
+verifies against). It does not prescribe a runtime — agents apply it with
+whatever tools they have.
+
+---
+
+## Depth tiers
+
+A tier selects which sections of the design artifact (`templates/design.md`) are
+**mandatory**. Deeper tiers are supersets of shallower ones. Pick the shallowest
+tier that fits the altitude of the work.
+
+| Tier | Altitude | Mandatory sections | Skips | Typical entry point |
+|------|----------|--------------------|-------|---------------------|
+| `spike` | Throwaway PoC / trivial change | Problem · Scope · Minimal architecture | Everything else — flag as speculative | `/pan:design-phase --spike`, `focus-design --spike` |
+| `phase` | One roadmap phase | Problem · Success criteria (≥2 machine-checkable) · Architecture assessment · Design synthesis · Phase-scoped ADR · Threat-lite · Test hooks | Demand validation, competitive intel, market/strategy | **`/pan:design-phase` (main-flow default)** |
+| `feature` | A whole feature (internal) | `phase` + Demand validation · Error-handling design · Full STRIDE-lite threat model · Test plan · Feature ladder | Competitive intel, strategic (Blue Ocean/Wardley) | `focus-design --internal` |
+| `full` | A market-facing feature | `feature` + Competitive intelligence · Strategic analysis (ERRC) · Adoption analysis | — (nothing) | `focus-design --full` (DEFAULT) |
+
+**Altitude rule (why the tiers exist):** product/strategic design — *whether*
+and *what* to build, with demand and competitive evidence — is decided **once**
+at feature/milestone creation (`focus-design`, or the product-design pass in
+`milestone-new`). Per-phase design (`phase` tier) covers only *how* to build an
+already-scoped phase: architecture, ADR, threat, synthesis. This keeps the
+frequently-run per-phase path cheap and stops the main flow re-litigating product
+questions on every phase.
+
+---
+
+## What every tier produces
+
+The artifact is `{scope}-design.md` from `templates/design.md`. Sections below are
+ordered; a tier makes a contiguous prefix (plus its named additions) mandatory.
+
+### 1. Problem & scope (all tiers)
+- **Problem statement** — what problem exists, why it matters, cost of inaction. Concrete, not a vague generality.
+- **Scope** — in-scope / out-of-scope, and the fixed boundary this design must not exceed (a phase boundary from `roadmap.md`, or a feature boundary).
+
+### 2. Success criteria (`phase`+)
+- 3–7 criteria, **at least 2 machine-checkable** (verifiable by an automated test, not manual inspection). State the check for each machine-checkable one.
+
+### 3. Architecture assessment & synthesis (`phase`+)
+- **Conventions** — extract the project's actual conventions (module layout, error style, boundaries) from the codebase; do not assume.
+- **Components & boundaries** — what modules are added/touched; confirm the design honors the discovered boundaries (no layer violations).
+- **Interface contract** — exact invocation + input/output schema + status/exit codes, per project convention.
+- **State & filesystem scope** — reads from / writes to (must stay within project root / `.planning/`), state mutations, side effects.
+- **Design decisions** — each significant decision: what was decided, why, alternatives rejected.
+
+### 4. ADR (`phase`+)
+- A right-sized Architecture Decision Record: Status · Date · Context (problem, forces, current state, requirements traceability) · Decision (summary + numbered sub-decisions with rationale + integration) · Consequences (positive **and** negative, every negative with a mitigation or explicit acceptance).
+- `phase` tier: phase-scoped ADR (may be a section in `design.md`). `feature`/`full`: a standalone `docs/decisions/ADR-NNNN-*.md`.
+
+### 5. Threat model (`phase` = lite, `feature`+ = full)
+- STRIDE-lite: for each realistic threat, its vector and its mitigation (or explicit acceptance). `phase` tier covers the change's own surface; `feature`+ covers the full feature.
+
+### 6. Error handling & diagnostics (`feature`+)
+- Every error condition → output shape + handling style (validate args before side effects; safe reads return null; actionable messages).
+
+### 7. Test plan (`phase` = hooks, `feature`+ = full)
+- How each success criterion is verified; which are unit vs scenario; the seed inputs for the machine-checkable ones.
+
+### 8. Demand & strategy (`feature`+ / `full`)
+- `feature`: demand evidence (or an explicit "speculative" flag), feature ladder (v0 MVP → v1 → v2).
+- `full`: competitive intelligence, strategic analysis (ERRC: eliminate/reduce/raise/create), adoption analysis.
+
+---
+
+## Quality bar (what `pan-design-checker` enforces)
+
+A design artifact **passes** only when all of these hold at its tier. This is the
+same checklist the independent checker verifies — designers should self-check
+against it before handing off, but passing is decided by the checker, not the
+author.
+
+1. **Requirement coverage** — every stated requirement maps to a design element; nothing is silently dropped.
+2. **Machine-checkable criteria** — ≥2 success criteria are automatable, and each names its check (`phase`+).
+3. **Architecture conformance** — the design matches conventions *discovered* from the codebase, and introduces no layer/boundary violation.
+4. **ADR honesty** — alternatives are real (not strawmen); every negative consequence has a mitigation or is explicitly accepted; no placeholder/skeleton sections (`phase`+).
+5. **Threat coverage** — each identified threat is mitigated or explicitly accepted; none is left open (`phase` lite / `feature`+ full).
+6. **Testability** — the test plan/hooks map to the success criteria (`phase`+).
+7. **Scope discipline** — the design stays within the fixed boundary; scope-expanding ideas are captured as "deferred", never designed in.
+
+If any dimension fails, the checker returns structured gaps and the designer
+revises. The reflexion loop is capped at **2 revision iterations** (design →
+check → revise → check → final) to prevent over-revision — the same guardrail
+`plan-phase` uses with `pan-plan-checker`.

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.