pan-wizard 3.21.1 → 3.24.0

package/commands/pan/army.md

@@ -1,7 +1,7 @@
 ---
 name: army
 group: Army
-description: Bot-army campaign — Mission Control (Opus conductor) delegates a whole-project goal to squads (architecture / build / quality / release), each squad working branch-per-agent worktrees under a hard safety harness, gated by CI + a human merge, looping plan→delegate→execute→review→integrate→learn until the goal ships or a stop condition fires.
+description: Bot-army campaign — Mission Control (the reasoning-tier conductor) delegates a whole-project goal to squads (architecture / build / quality / release), each squad working branch-per-agent worktrees under a hard safety harness, gated by CI + a human merge, looping plan→delegate→execute→review→integrate→learn until the goal ships or a stop condition fires.
 allowed-tools:
   - Read
   - Write
@@ -15,24 +15,30 @@ allowed-tools:
 
 # /pan:army — Bot-Army Campaign (mission control → squads → ship)
 
-Run a whole-project delivery as a coordinated bot army (ADR-0032 squads · ADR-0033 campaign). **Mission Control** — the Opus `pan-conductor`, elevated to campaign scope — plans the mission, delegates to **squads** over the Agent toolset, and never writes code itself. Each squad owns its lifecycle role; the Build squad parallelizes by giving every builder its own `army/<task>` branch in an isolated git worktree. Nothing reaches a protected branch without green CI and a human's approval. $ARGUMENTS
+Run a whole-project delivery as a coordinated bot army (ADR-0032 squads · ADR-0033 campaign). **Mission Control** — the reasoning-tier `pan-conductor`, elevated to campaign scope — plans the mission and delegates to **squads** over the Agent toolset rather than implementing anything itself. Each squad owns its lifecycle role; the Build squad parallelizes by giving every builder its own `army/<task>` branch in an isolated git worktree. Nothing reaches a protected branch without green CI and a human's approval. $ARGUMENTS
 
 The army is the campaign-scale sibling of `/pan:exec-phase --hierarchical` (one phase) and `/pan:focus-auto` (a category/backlog loop). It composes both: the conductor harness bounds it, the focus-auto loop drives it, the squads structure it.
 
 ---
 
-## Tiers (from `pan-tools squad list`)
+## Tiers — the squad rows from `pan-tools squad list`, plus PAN's own hierarchy positions
 
-| Tier | Who | Model | Access |
-|------|-----|-------|--------|
-| 0 · Mission Control | `pan-conductor` | Opus 4.8 | delegation-only (Agent toolset) — never codes |
-| 1 · Architecture | roadmapper · planner · plan-checker · researchers | Sonnet (reasoning) | read-only |
-| 1 · Build | `pan-executor` | Sonnet (reasoning) | read / write / bash — one branch+worktree per agent |
-| 1 · Quality | reviewer · hardener · meta · verifier · integration · debugger | Sonnet/Haiku (mid) | read-only, adversarial |
-| 1 · Release | `pan-release` | Sonnet (mid) | always-ask — human gate |
-| 2 · Workers | document_code · distiller | Haiku (fast) | narrow, high-volume jobs |
+| Tier | Who | Model tier | Access |
+|------|-----|-----------|--------|
+| 0 · Mission Control | `pan-conductor` | `reasoning` (`mid` under `budget`) | delegation-first (Agent toolset) — instructed to route work, not write it |
+| 1 · Architecture | design + planning agents — `squad show architecture` lists them | `reasoning` | `read-only` |
+| 1 · Build | `pan-executor` | `reasoning` | `read-write-bash` — one branch+worktree per agent |
+| 1 · Quality | adversarial review + debug agents — `squad show quality` lists them | `mid` | `read-only`, adversarial |
+| 1 · Release | `pan-release` | `mid` | `always-ask` — human gate |
+| 2 · Workers | the agents `squad list` reports under `workers` | `reasoning`; `budget` down-tiers **per agent** (see below) | narrow, high-volume jobs |
 
-Resolve the roster at runtime — never hardcode it: `pan-tools squad list` and `pan-tools squad show <name>`.
+**Where each row comes from.** The tier-1 rows mirror the `squads[]` records `pan-tools squad list` prints — label, `tier`, `access` (their member names come from `squad show <name>`, since `squad list` reports only a count). The Tier 0 and Tier 2 rows are PAN's hierarchy positions: the same command names them under its `coordinator` and `workers` keys, but reports nothing else about them, so the Model-tier and Access values on those two rows are written here rather than returned by the command. Resolve the roster at runtime — never hardcode it: `pan-tools squad list` and `pan-tools squad show <name>`.
+
+**Reading the Model-tier column.** These are PAN *tiers*, not model names. `reasoning` resolves to `inherit` — the model you launched with — while `mid` and `fast` map to the provider's mid/fast models (Sonnet and Haiku on Anthropic).
+
+**Reading the Access column.** The backticked values on the tier-1 rows are the `access` labels `squad list` reports; tier 0 and tier 2 carry PAN's own. They are role contracts the conductor's prompt assigns when it delegates, not a sandbox: `squads.cjs` says of itself that it "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do — expect that, since several `read-only` squad members hold `Write` to emit planning or verification artifacts. The binding grant is each agent's own `tools:` frontmatter (`grep '^tools:' agents/*.md`), and Mission Control's includes `Write` and `Bash`: routing rather than coding is how it is instructed to behave, not something the runtime prevents. The rail those grants do enforce is delegation depth — `grep -l '^tools:.*Task' agents/*.md` names every agent able to spawn another (today, `pan-conductor`), so a squad agent cannot fan out further.
+
+**Squad tier is not profile tier.** The tier column above is a `squads.cjs` grouping attribute — what `pan-tools squad list` reports — and it is not what resolves an agent's model; that comes from the active `model_profile` (`quality` and `balanced` are `reasoning` for every agent, and `budget` is the only profile that down-tiers), plus any `model:` pin in an agent's own frontmatter. So the `mid` on the Quality and Release rows does not describe what those agents run under the default profile — under `quality` and `balanced` they resolve `reasoning` like everything else. The tier-1 values above are the squad groupings; the tier-0 and tier-2 values are per-agent profile tiers. **`budget` resolves per agent, not per row:** it sends some workers to `fast` and others to `mid`, so no single value is true of the Tier 2 row — `MODEL_PROFILES` in `pan-wizard-core/bin/lib/core.cjs` is the table, and it is the one to read rather than a tier written into a doc. For the agents that pin a model outright, `grep -l '^model: opus' agents/*.md` lists them — the pin applies on Claude Code only, since the installer strips it for the other runtimes.
 
 ---
 
@@ -97,7 +103,7 @@ Every cap the conductor enforces applies to the campaign, scaled up:
 ```
 /pan:army
   Phase 0  MUSTER   — squad list + roster validate · cache prime · baseline · loop-state · abort-file clear
-  Phase 1  PLAN     — Mission Control (Opus, extended thinking) decomposes the goal into dependency-ordered missions
+  Phase 1  PLAN     — Mission Control (session model, xhigh effort) decomposes the goal into dependency-ordered missions
   Phase 2  DELEGATE — pick the next item (focus-auto --source) · route to the owning squad over the Agent toolset
   Phase 3  EXECUTE  — Build squad: one army/<task> worktree per agent (parallel); Architecture/Quality research in parallel (read-only)
   Phase 4  REVIEW   — Quality squad on the built tree: reviewer + hardener + meta → verdict ladder; a block is a hard gate
@@ -161,7 +167,7 @@ The campaign is complete when ANY holds: `--max-cycles` reached · backlog empty
 - Integrate a mission that hasn't passed Quality green.
 
 ## ALWAYS DO
-- Plan on Opus, delegate over the Agent toolset, keep each squad's return a tight summary.
+- Plan on the session model Mission Control inherits, delegate over the Agent toolset, keep each squad's return a tight summary.
 - One worktree per Build agent; parallel research/verify; serial human-gated integrate.
 - Check the abort file + spawn/budget caps before every spawn.
 - Finish with the clean-build seal; write learnings back to memory.

package/commands/pan/audit-deployment.md

@@ -77,9 +77,12 @@ For the detected runtime config directory (CONFIG_DIR), audit ALL of the followi
 - [ ] `CONFIG_DIR/pan-wizard-core/references/` — non-empty, every manifest-listed reference present
 
 **1.4 Commands**
-- For Claude/Gemini: `CONFIG_DIR/commands/pan/` — every manifest-listed command `.md` present
-- For OpenCode: `CONFIG_DIR/command/` — every manifest-listed `pan-*.md` present
-- For Codex/Copilot: `CONFIG_DIR/skills/pan-*/SKILL.md` — every manifest-listed skill directory present
+- For Claude/Gemini: `CONFIG_DIR/commands/pan/` — every manifest-listed command file present
+- For OpenCode: `CONFIG_DIR/commands/` — every manifest-listed `pan-*.md` present (flat, one file per command)
+- For Copilot: `CONFIG_DIR/skills/pan-*/SKILL.md` — every manifest-listed skill directory present
+- For Codex: the SHARED skills tree, not `CONFIG_DIR` — `./.agents/skills/pan-*/SKILL.md` for a local
+  install, `~/.agents/skills/pan-*/SKILL.md` for a global one. Codex has no `skills/` of its own; if you
+  look under `.codex/` you will find no commands and wrongly report a broken install.
 
 **1.5 Agents**
 - [ ] `CONFIG_DIR/agents/` — every manifest-listed agent file present
@@ -111,18 +114,18 @@ Record all findings with severity: CRITICAL (missing core), WARNING (missing opt
 Check `.planning/` directory in the target:
 
 **2.1 Core Planning Files**
-- [ ] `.planning/config.json` — exists, valid JSON, has required keys (mode, depth, model_profile, workflow)
+- [ ] `.planning/config.json` — exists, valid JSON, has expected keys (`model_profile`, `commit_docs`, `workflow`, `budget`)
 - [ ] `.planning/project.md` — exists, has "What This Is", "Core Value", "Requirements" sections
 - [ ] `.planning/state.md` — exists, has "Current Position", "Performance Metrics" sections
 - [ ] `.planning/roadmap.md` — exists, has phase table
 - [ ] `.planning/requirements.md` — exists if project used requirements tracking
 
 **2.2 Phase Directories**
-- Scan for `phase_*` or `*-*` numbered directories
+- Scan `.planning/phases/` for numbered phase directories
 - For each phase directory:
-  - [ ] PLAN.md exists (phase summary)
-  - [ ] At least one plan_*.md file exists
-  - [ ] verification.md exists (phase was verified)
+  - [ ] At least one `*-plan.md` file exists (phase was planned)
+  - [ ] A matching `*-summary.md` file exists (phase was executed)
+  - [ ] A `*-verification.md` file exists (phase was verified)
 - Count: total phases, phases with plans, phases verified, phases with gaps
 
 **2.3 Research Artifacts** (if brownfield/research was enabled)
@@ -138,10 +141,10 @@ Check `.planning/` directory in the target:
 
 **2.5 Config Sanity**
 - Validate config.json values are within expected ranges
-- mode: "yolo" | "interactive"
-- depth: "quick" | "standard" | "comprehensive"
-- model_profile: "quality" | "balanced" | "budget"
-- workflow agents: all boolean
+- `model_profile`: "quality" | "balanced" | "budget"
+- `commit_docs`: boolean
+- `workflow.*` toggles (research, plan_check, verifier, ...): all boolean
+- `budget`: `default_points` numeric, `enforce` boolean
 </step>
 
 <step name="workflow_quality_audit">
@@ -150,7 +153,7 @@ Check `.planning/` directory in the target:
 Assess how well the project workflow was followed:
 
 **3.1 Planning Quality**
-For each phase with a PLAN.md:
+For each phase with plan files (`*-plan.md`, e.g. `01-01-plan.md`):
 - Does it have clear objectives?
 - Does it reference requirements?
 - Are plans sequential with dependencies noted?
@@ -226,7 +229,7 @@ Verification Coverage: <N>%
 - [P-W01] <description> — <suggestion>
 
 ### Phase Health
-| Phase | PLAN.md | Plans | Verified | Status |
+| Phase | Planned | Plans | Verified | Status |
 |-------|---------|-------|----------|--------|
 | 01    | ✓       | 3     | ✓        | Complete |
 | 02    | ✓       | 5     | ✗        | Unverified |

package/commands/pan/cost.md

@@ -81,13 +81,13 @@ pan-tools cost clear
 </subcommands>
 
 <rate_table>
-Default rates (USD per million tokens) as of 2026-04. Override per-model in `.planning/config.json`:
+PAN ships a built-in rate table (USD per million tokens) covering the current Claude, GPT and Gemini families, with a per-tier fallback for anything it doesn't recognize. Override it in `.planning/config.json` — key on a PAN tier (`reasoning` / `mid` / `fast`), on a model family (longest-prefix match, so a family key also covers the dated ids the hooks record), or on an exact model id:
 
 ```json
 {
   "cost": {
     "rates": {
-      "claude-opus-4-7": { "input": 15.0, "output": 75.0, "cache_read": 1.5, "cache_write": 18.75 },
+      "reasoning": { "input": 5.0, "output": 25.0, "cache_read": 0.5, "cache_write": 6.25 },
       "my-custom-model": { "input": 1.0, "output": 2.0, "cache_read": 0.1, "cache_write": 1.25 }
     }
   }

package/commands/pan/debug.md

@@ -15,7 +15,7 @@ Debug issues using scientific method with subagent isolation.
 
 **Orchestrator role:** Gather symptoms, spawn pan-debugger agent, handle checkpoints, spawn continuations.
 
-**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). A fresh context window per investigation. Main context stays lean for user interaction.
 </objective>
 
 <context>

package/commands/pan/design-phase.md

@@ -0,0 +1,77 @@
+---
+name: pan:design-phase
+group: Phase Lifecycle
+description: Design a roadmap phase before planning — architecture, ADR, threat-lite, machine-checkable criteria — verified by an independent checker
+argument-hint: "[phase] [--spike] [--skip-design] [--redesign]"
+agent: pan-designer
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - mcp__context7__*
+---
+<objective>
+Produce a verified design (`{phase}-design.md`) for a roadmap phase BEFORE it is planned, so `pan-planner` builds against an architecture instead of improvising one. This is the main flow's design step — the per-phase counterpart to the focus flow's `/pan:focus-design`, running the shared `phase` tier from `~/.claude/pan-wizard-core/references/design-methodology.md` (ADR-0042).
+
+**Lifecycle position:** `discuss → research → **design** → plan → verify`.
+
+**Orchestrator role:** parse arguments, validate phase, spawn `pan-designer` (tier `phase`), verify with `pan-design-checker`, iterate until pass or max iterations, write `{phase}-design.md`, present results.
+</objective>
+
+<altitude_boundary>
+Per-phase design covers **how** to build an already-scoped phase: architecture, design decisions, a phase-scoped ADR, a threat-lite pass, and machine-checkable success criteria. It does NOT re-open product questions — demand validation, competitive intelligence, and market/strategy belong to feature/milestone creation (`/pan:focus-design`, `/pan:milestone-new`), done once, not per phase. Keep this step at the phase altitude.
+</altitude_boundary>
+
+<routing_decision_tree>
+Evaluate top-to-bottom; take the FIRST match.
+
+```
+IF --skip-design:
+  → Skip design entirely. Note that plan-phase will proceed WITHOUT a design.md.
+
+ELSE IF {phase}-design.md exists AND --redesign NOT set:
+  → Reuse existing design. Offer: view / redesign / continue to plan.
+
+ELSE IF phase is trivial (auto-detect: single small task, no new module,
+        no new interface, no external surface):
+  → Auto-skip with a one-line rationale. A trivial phase does not need a
+    design artifact; recommend proceeding to plan-phase.
+  → --spike or an explicit invocation overrides auto-skip.
+
+ELSE (default):
+  → DESIGN (spawn pan-designer at tier `phase`, or `spike` if --spike)
+  → VERIFY (pan-design-checker reflexion loop)
+  → WRITE {phase}-design.md
+```
+</routing_decision_tree>
+
+<process>
+1. **Validate phase** — error if the phase number is missing or not in `roadmap.md`.
+2. **Prime context** — resolve the phase directory; gather `{phase}-context.md`, `{phase}-research.md`, and the phase boundary from `roadmap.md`.
+3. **Design** — spawn `pan-designer` with a `<files_to_read>` block (context, research, roadmap boundary, `CLAUDE.md`). It fills in `templates/design.md` at the `phase` tier (`spike` if `--spike`).
+4. **Verify (reflexion loop)** — spawn `pan-design-checker` with the drafted design + the boundary source:
+   - If it PASSES → done.
+   - If it finds gaps (iteration 1) → `pan-designer` revises (address genuine gaps only), re-check.
+   - If it finds gaps (iteration 2) → final revision, record remaining gaps as caveats.
+   - **Max 2 revision iterations** (design → check → revise → check → final) — the same guardrail `plan-phase` uses with `pan-plan-checker`.
+5. **Write** `{phase}-design.md` to the phase directory and commit via `pan-tools commit`.
+6. **Present** results + next step (`/pan:plan-phase` — which will consume this design.md).
+</process>
+
+<completion_contract>
+Design is complete when ALL conditions are met:
+1. `{phase}-design.md` created in the phase directory (unless `--skip-design` or an auto-skipped trivial phase — state which).
+2. `pan-design-checker` PASSED, or 2 revision iterations were exhausted with remaining gaps recorded as caveats.
+3. The artifact contains, at the `phase` tier: problem+scope, ≥2 machine-checkable success criteria, architecture (conventions cited, no layer violation), a phase-scoped ADR (every negative consequence mitigated/accepted, no placeholders), a threat-lite pass, and test hooks.
+4. User presented with results and the next-step option.
+
+Design FAILS if: phase not found in roadmap, or the designer returns empty/malformed output after retries.
+</completion_contract>
+
+<handoff>
+`{phase}-design.md` is an **optional upstream input** to `/pan:plan-phase`, consumed by `pan-planner` exactly as `{phase}-context.md` is. `pan-plan-checker` verifies the plan conforms to it (Design Conformance dimension). A phase without a design.md still plans — the design step strengthens planning, it does not gate it.
+</handoff>

package/commands/pan/exec-phase.md

@@ -62,7 +62,7 @@ Phase: $ARGUMENTS
 - `--skip-review` — Skip automatic code review after execution completes.
 - `--fast` — Skip both test generation and code review (implies `--skip-tests --skip-review`).
 - `--deep-review` (v3.4+) — After the normal reviewer step, also run `/pan:review-deep <phase>` (security audit via pan-hardener + cross-check via pan-meta-reviewer). Produces `.planning/reviews/<N>/deep-review.md`. Recommended for phases touching auth, payment, PII, migrations, or public APIs. Costs roughly 3× a normal review.
-- `--hierarchical` (v3.4+, Claude + Opus 4.7 only) — Spawn `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns executor/reviewer/verifier sub-agents in sequence. Bounded by safety harness: max 2 nesting levels, 12 spawns per phase, budget ceiling, `.planning/orchestration/abort` kill-switch. On non-Claude runtimes or older models, this flag is a no-op with a warning and falls back to flat exec. Use only for large phases (≥4 autonomous plans) where wall-clock reduction justifies the ~20-30% orchestration tax.
+- `--hierarchical` (v3.4+, Claude Code only — needs native sub-agent spawning) — Spawn `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns executor/reviewer/verifier sub-agents in sequence. `pan-conductor` runs on the reasoning tier under the default profile, which inherits the model you launched with (the `budget` profile drops it to mid). Bounded by safety harness: max 2 nesting levels, 12 spawns per phase, budget ceiling, `.planning/orchestration/abort` kill-switch. On runtimes that cannot spawn nested agents, this flag is a no-op with a warning and falls back to flat exec. Use only for large phases (≥4 autonomous plans) where wall-clock reduction justifies the ~20-30% orchestration tax.
 
 Context files are resolved inside the workflow via `pan-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
 </context>
@@ -97,7 +97,7 @@ pan-tools cache prime --summary
 
 This returns `{blocks: [{path, bytes, cache}], total_bytes, sha}` for the cacheable set (project.md, requirements.md, roadmap.md, state.md, standards.md). The `sha` is stable across identical inputs, so repeated calls within the phase hit cached reads.
 
-When spawning subagents for wave execution, include the cacheable block paths in each agent's system-context so the host runtime (Claude Code with Opus 4.7) can mark them `cache_control: ephemeral`. On non-Claude runtimes or older models, this step is a no-op — nothing breaks, just no savings.
+When spawning subagents for wave execution, include the cacheable block paths in each agent's system-context so a host runtime that supports prompt caching (Claude Code does) can mark them `cache_control: ephemeral`. Where prompt caching is unavailable, this step is a no-op — nothing breaks, just no savings.
 </cache_priming>
 
 <process>

package/commands/pan/experiment.md

@@ -17,8 +17,8 @@ allowed-tools:
 > **Self-protection:** This command **scaffolds external project folders OUTSIDE the PAN source repo** to drive autonomous AI coding sessions against fresh ideas, then harvests the resulting telemetry back into `pan-wizard-core/learnings/`. It is a **PAN-development tool**, not a feature for end-users of PAN to invoke on their own projects.
 
 **Spec:** `docs/specs/self_improvement_loop_featureai.md`
-**ADR:** ADR-0026 (pending W4)
-**Status:** v3.7.0 W1+W2+W3 — scaffolding (`new`/`list`/`manifest`) + external runner (`run`/`status`/`stop`) + harvest (`harvest`/`prune`); W4 adds promote integration with `/pan:learn`.
+**ADR:** ADR-0026 (Accepted — shipped W1-W4 in v3.7.0)
+**Status:** v3.7.0 — scaffolding (`new`/`list`/`manifest`) + external runner (`run`/`status`/`stop`) + harvest (`harvest`/`prune`) + promote integration with `/pan:learn` (`learn promote`/`unpromote`/`list-promoted`).
 
 ---
 
@@ -31,7 +31,7 @@ allowed-tools:
 ## When NOT to use this
 
 - Building production user features. Use `/pan:new-project` and `/pan:exec-phase` directly.
-- Validating a single-file change. The experiment loop is heavy — use `npm test` and `/pan:check`.
+- Validating a single-file change. The experiment loop is heavy — use `npm test` and `/pan:quick`.
 - Inside the PAN source repo. The command **refuses** to scaffold experiments inside `d:\PanWizard\` (or wherever the source is cloned). The experiment root defaults to `~/pan-experiments/`.
 
 ---
@@ -97,7 +97,7 @@ Spawn the external AI runtime against the experiment folder. **Synchronous** —
 
 | Flag | Default | Purpose |
 |------|---------|---------|
-| `--timeout <sec>` | `1800` (30 min) | Hard timeout in seconds; runner sends SIGTERM at deadline |
+| `--timeout <sec>` | `3600` (60 min) | Hard timeout in seconds; runner sends SIGTERM at deadline |
 | `--prompt <text>` | `/pan:new-project --auto @.planning/idea.md` | Prompt passed to the external runtime |
 | `--root <path>` | `~/pan-experiments/` | Override the experiment root |
 
@@ -105,7 +105,7 @@ Spawn the external AI runtime against the experiment folder. **Synchronous** —
 
 **Runtime support:** claude / codex / gemini / opencode (via `RUNTIME_RUNNERS` adapter map in `runner.cjs`). GitHub Copilot CLI is **unsupported** for the `run` subcommand — no documented headless prompt mode. Copilot users can still scaffold and harvest manually.
 
-**Billing note (Claude runtime):** headless `claude -p` runs bill against the **Claude Agent SDK credit pool** — a monthly allotment separate from your interactive subscription limits (Anthropic split the two effective June 15, 2026). Experiment runs do not consume interactive-session quota, but heavy experimentation can exhaust the SDK pool independently. Captured metrics are tagged `billing_pool: "agent_sdk"` so you can reconcile experiment spend separately.
+**Billing note (Claude runtime):** headless `claude -p` runs bill against the **Claude Agent SDK credit pool** — a monthly allotment separate from your interactive subscription limits (Anthropic split the two effective June 15, 2026). Experiment runs do not consume interactive-session quota, but heavy experimentation can exhaust the SDK pool independently. Note: the CLI `experiment run` does not capture a metrics envelope — the `billing_pool: "agent_sdk"` tagging is produced only via the runner module's capture-metrics API, not from the command line, so CLI run-state has no `metrics` key to reconcile against.
 
 ### `/pan:experiment status <slug>`
 
@@ -113,7 +113,7 @@ Read the current `run-state.json` snapshot. Returns the full state object (`stat
 
 ### `/pan:experiment stop <slug>`
 
-Gracefully halt a running experiment. Reads pid from `run-state.json`, sends SIGTERM, writes `status: failed, stop_reason: manual` to the run state. Returns the updated state.
+Finalize and record a stopped experiment. This **cannot** terminate an already-running synchronous experiment: while a run is in flight the runner blocks and no pid is available to signal, so `stop` only reconciles the run-state after the fact. If a completed run left the state un-finalized, it records `status: failed, stop_reason: manual` and returns the updated state. If no pid is recorded (an in-flight run), it returns an error and writes nothing.
 
 If the experiment has already finished, returns the existing run state without error.
 
@@ -163,17 +163,21 @@ Remove the experiment folder after harvest.
 
 **Returns:** `{ pruned: <slug>, mode: "soft"|"hard", archive_path? }`.
 
-## Subcommands (W4 — coming soon)
+## Promote integration (shipped, W4)
 
-| Subcommand | Wave | Purpose |
-|------------|------|---------|
-| `archive <slug>` | W4 | Alias for `prune` (kept for clarity in scripts) |
-| `delete <slug> --confirm` | W4 | Alias for `prune --hard` with confirmation prompt |
-
-W4 also adds:
+The self-improvement loop closes via `/pan:learn` and the `learn` CLI:
 - `/pan:learn --experiment <slug>` — runs pan-optimizer over harvested data
 - `pan-tools learn promote --pattern <id> --scope universal --topic <name>` — extracts a finding into `pan-wizard-core/learnings/{universal,internal}/<topic>.md`
-- `pan-tools learn unpromote/list-promoted` — rollback and inventory
+- `pan-tools learn unpromote` / `learn list-promoted` — rollback and inventory
+
+## Not yet shipped
+
+| Subcommand | Purpose |
+|------------|---------|
+| `archive <slug>` | Alias for `prune` (kept for clarity in scripts) |
+| `delete <slug> --confirm` | Alias for `prune --hard` with confirmation prompt |
+
+Until these land, use `prune` / `prune --hard` directly.
 
 ---
 

package/commands/pan/focus-auto.md

@@ -364,21 +364,21 @@ Between cycles, manage context to prevent quality degradation over long campaign
 
 Display one-line cycle summary: `Cycle N/M | X/Y pts | Z items done | Tests: A -> B`
 
-#### Step 2.5a: Reflection Gate (Opus 4.7 thinking-capable models only)
+#### Step 2.5a: Reflection Gate (`reasoning` tier only)
 
-Before committing to the next cycle, call the reflection helper:
+Before committing to the next cycle, call the reflection helper, passing the tier the run actually resolved to (not a literal — `"reasoning"` below is just the enabling case):
 
 ```
-echo '{"run": <run-state>, "cycle": <just-completed-cycle>, "batch": <proposed-next-batch>, "tier": "reasoning"}' \
+echo '{"run": <run-state>, "cycle": <just-completed-cycle>, "batch": <proposed-next-batch>, "tier": "<resolved-tier>"}' \
   | pan-tools focus reflection
 ```
 
-The helper returns `{reflect: true, prompt: "..."}` when the current model tier supports extended thinking. If `reflect: true`, think through the prompt — which asks whether running another cycle is worthwhile given telemetry and remaining items — and respond with JSON: `{"continue": true|false, "rationale": "..."}`.
+The helper returns `{reflect: true, prompt: "..."}` only when the resolved tier is `reasoning` (`REFLECTION_THRESHOLD.enable_on_tiers`), or when the run state sets `reflection_enabled: true`, which overrides the tier check in both directions. Being *thinking-capable* is not enough on its own: a `mid`-tier Sonnet supports extended thinking but still gets `reflect: false` unless `reflection_enabled` is set. If `reflect: true`, think through the prompt — which asks whether running another cycle is worthwhile given telemetry and remaining items — and respond with JSON: `{"continue": true|false, "rationale": "..."}`.
 
 - If `continue: false`: stop the campaign and treat as a user-reason stop (preserve state, skip to Phase 3).
 - If `continue: true`: proceed to the next cycle.
 
-If the helper returns `reflect: false` (tier doesn't support thinking, or `reflection_enabled: false` in run state, or no next batch): skip this step silently and continue to the next cycle.
+If the helper returns `reflect: false` (resolved tier is `mid`/`fast` and `reflection_enabled` is unset, or `reflection_enabled: false` in run state, or no next batch): skip this step silently and continue to the next cycle.
 
 The reflection gate catches "zero progress" or "wrong category" drift earlier than the automatic stop rules.
 

package/commands/pan/focus-design.md

@@ -22,7 +22,7 @@ Research, design, and specify a new feature with strategic analysis. $ARGUMENTS
 
 **Goal:** Produce a best-of-breed feature specification that (a) validates the problem with evidence, (b) maps the competitive landscape, (c) identifies strategic differentiation, (d) designs an architecturally sound implementation, (e) plans for error handling, security, and testability from day one, (f) defines an incremental delivery ladder, and (g) outputs a ready-to-implement spec with ADR, test plan, and implementation tasks.
 
-**Methodology:** Synthesizes Spec-Driven Development, Blue Ocean Strategy, Wardley Mapping, STRIDE-lite threat modeling, Architecture Decision Records, and structured workflow methodology into a single investigative pipeline.
+**Methodology:** Synthesizes Spec-Driven Development, Blue Ocean Strategy, Wardley Mapping, STRIDE-lite threat modeling, Architecture Decision Records, and structured workflow methodology into a single investigative pipeline. The design-quality bar and depth tiers are the shared ones in `~/.claude/pan-wizard-core/references/design-methodology.md` (this pipeline runs the `feature`/`full` tiers; the main flow's `/pan:design-phase` runs the `phase` tier) — and the same independent verifier, `pan-design-checker`, gates both (ADR-0042).
 
 ---
 
@@ -883,6 +883,16 @@ Before writing the ADR file, verify ALL of these:
 - **Straw-man options:** Including obviously bad alternatives just to make the chosen option look good
 - **Missing migration strategy:** Documenting breaking changes without explaining how to handle them
 
+### 5.4 Independent Verification (pan-design-checker)
+
+The self-check in 5.2 is necessary but not sufficient — an author is a poor judge of their own design. After the ADR and design synthesis are drafted, spawn **`pan-design-checker`** for an *independent, adversarial* pass (the same assurance model `/pan:plan-phase` gets from `pan-plan-checker`).
+
+- Pass the checker a `<files_to_read>` block: the drafted ADR + spec, the feature boundary/spec, and any `context.md`.
+- The checker verifies the seven dimensions in `~/.claude/pan-wizard-core/references/design-methodology.md` at the `feature`/`full` tier: requirement coverage, ≥2 machine-checkable criteria, architecture conformance (independently confirmed against the codebase — not the design's own claims), ADR honesty, threat coverage, testability, and scope discipline.
+- **Reflexion loop:** if the checker returns gaps, revise the affected phase output and re-check. Cap at **2 revision iterations** (design → check → revise → check → final); re-read each critique and fix only genuine gaps, not false positives from missing context. On the final iteration, record any remaining gaps as caveats rather than looping further.
+
+Do not proceed to Phase 10 output until the checker PASSES or the 2-iteration cap is reached.
+
 ---
 
 ## Phase 6: Error Handling & Diagnostics Design
@@ -1039,6 +1049,8 @@ Write ADR to: `docs/decisions/ADR-NNNN-<feature_name>.md`
 
 **ADR completeness gate:** Before saving, verify the ADR passes ALL checks from Phase 5.2. The ADR file must contain every section defined in Phase 5.1 with substantive content — no placeholder brackets, no skeleton sections, no missing tables. If any section would be empty, go back to the relevant phase and extract the content.
 
+**Independent verification gate:** The final artifact must have PASSED `pan-design-checker` in Phase 5.4 (or reached the 2-iteration cap with remaining gaps recorded as caveats). Re-run the checker here on the *saved* spec + ADR as a final gate — the independent pass, not just the 5.2 self-check, is what authorizes handing this design to `/pan:focus-plan`.
+
 **Minimum ADR size:** A proper ADR for a `--full` mode investigation should be 80-200+ lines. If the ADR is under 60 lines, it is almost certainly missing required sections. For `--internal` mode, minimum 60 lines. For `--outward` mode, minimum 70 lines.
 
 ### 10.3 Report Summary

package/commands/pan/focus-exec.md

@@ -255,7 +255,7 @@ Display the execution batch to user, then continue automatically.
    ```
    pan-tools focus classify-stages --raw
    ```
-   The CLI reads the latest batch and returns `{waves, parallelism_hint}`. When `parallelism_hint` is `emit-micro-in-parallel` or `emit-standard-in-parallel`, all reads and greps for items in the current wave SHOULD be emitted in a single assistant turn (parallel tool calls). Opus 4.7 is markedly better at emitting parallel tool calls than earlier models; use that to collapse Stage 3 latency on MICRO-heavy batches.
+   The CLI reads the latest batch and returns `{waves, parallelism_hint}`. When `parallelism_hint` is `emit-micro-in-parallel` or `emit-standard-in-parallel`, all reads and greps for items in the current wave SHOULD be emitted in a single assistant turn (parallel tool calls). Current frontier models are markedly better at emitting parallel tool calls than earlier generations; use that to collapse Stage 3 latency on MICRO-heavy batches.
 
    Serialize on `FULL` tier items — each is its own wave.
 

package/commands/pan/learn.md

@@ -72,4 +72,4 @@ The optimization report in `.planning/optimization/reports/` contains:
 
 **See also:** `/pan:optimize`, `/pan:exec-phase`, `/pan:experiment` (v3.7.0+ self-improvement loop)
 
-Follow the workflow at `.claude/workflows/learn.md` (or `pan-wizard-core/workflows/learn.md`).
+Follow the workflow at `~/.claude/pan-wizard-core/workflows/learn.md`.

package/commands/pan/links.md

@@ -12,6 +12,8 @@ allowed-tools:
 
 Validate the doc-code link graph. Walks `docs/`, `pan-wizard-core/`, `commands/`, and `agents/` for inline `[[<id>]]` references and `// @pan: <id>` source-comment anchors. Reports broken refs, stale anchors, and uncovered backlink contracts.
 
+> **User projects:** the default roots (`docs/`, `pan-wizard-core/`, `commands/`, `agents/`) are the **PAN source-repo** layout. A typical user project has none of these, so a bare `/pan:links` scans almost nothing and reports a hollow `pass`. In a user project you **must** point it at your own layout with `--doc-root` / `--source-root` (both repeatable), e.g. `/pan:links --doc-root docs --source-root src`. Treat any run where `doc_files_scanned` (or `source_files_scanned`) is `0` as a **warning that the roots are misconfigured**, not a clean pass.
+
 **Usage:**
 ```
 /pan:links
@@ -99,4 +101,4 @@ Anchors cluster at the top of a file under a single banner; comment leader must
 - ADR-0027 — Doc–Code Link Graph
 - `docs/specs/doc_code_link_graph_featureai.md` — wire-level spec
 - `pan-tools doc-lint` — frontmatter schema validator (orthogonal concern)
-- `pan-tools verify-key-links` — legacy frontmatter-only link verifier (subsumed; both still ship)
+- `pan-tools verify key-links` — legacy frontmatter-only link verifier (subsumed; both still ship)

package/commands/pan/map-codebase.md

@@ -56,12 +56,12 @@ Run: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs codebase estimate-size --
 
 The CLI returns `{mode, total_tokens, file_count, languages}`:
 
-- **`mode: "single-shot"`** — repo is small enough (≤700K tokens) for one Opus 4.7 agent to ingest the whole thing. Spawn a single `pan-document_code` agent with the full repo in context. This avoids the 6-way stitching artifacts of sharded mode (contradictory version claims, duplicated mentions, missed cross-file references).
-- **`mode: "sharded"`** — repo exceeds 700K tokens. Fall back to the default 6-way parallel sharding (tech, arch, quality, concerns, relationships, practices). Each shard gets a 200K budget.
+- **`mode: "single-shot"`** — repo is small enough (≤700K tokens) for one agent with a 1M-context window to ingest the whole thing. Spawn a single `pan-document_code` agent with the full repo in context. This avoids the 6-way stitching artifacts of sharded mode (contradictory version claims, duplicated mentions, missed cross-file references).
+- **`mode: "sharded"`** — repo exceeds 700K tokens. Fall back to the default 6-way parallel sharding (tech, arch, quality, concerns, relationships, practices). Each shard is mapped by its own agent in its own context window, so no single agent has to hold the whole repo.
 
 Record the chosen mode + telemetry in the final `.planning/codebase/overview.md` so future runs can reason about drift.
 
-Opus 4.7 is required for single-shot mode (only model with a 1M context window). Other models always take the sharded path regardless of size.
+**The mode is decided by repo size alone** — `estimate-size` compares the token estimate to `--threshold` and applies no model check. So single-shot only pays off when the model you launched with actually has a 1M-context window (the default Opus and current Sonnet-class models do; legacy 200K-context models do not). On a 200K-context model, pass a threshold that matches your real window (e.g. `--threshold 150000`) so anything larger resolves to `sharded` instead of overflowing a single agent.
 </stage_0_ingest_mode>
 
 <tool_priority>
@@ -85,7 +85,7 @@ The orchestrator loads context in layers — NOT everything upfront. Mapper agen
 - Each agent discovers its own details via Glob/Grep/Read within its focus area
 - Agents do NOT receive other agents' output (parallel, independent)
 
-**Why:** Loading the entire codebase into the orchestrator before spawning agents wastes orchestrator context. Each agent has a fresh 200k window — let them explore independently. The orchestrator only needs enough context to spawn correctly and verify outputs exist.
+**Why:** Loading the entire codebase into the orchestrator before spawning agents wastes orchestrator context. Each agent has a fresh window — let them explore independently. The orchestrator only needs enough context to spawn correctly and verify outputs exist.
 </progressive_context>
 
 <process>

package/commands/pan/mcp-bridge.md

@@ -98,7 +98,7 @@ Normally the host runtime writes this file. The CLI path exists for test fixture
 
 <workflow>
 
-**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — `.claude/settings.json` for Claude Code, or the runtime's equivalent.
+**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — each runtime keeps it somewhere different: Claude Code in `settings.json` under its config dir, OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
 
 **Planning a phase that might touch external systems?** Run `/pan:mcp-bridge recommend <phase>` to get a ranked shortlist. Copy relevant tool names into the phase plan's "External tools" section so the executor knows to invoke them.
 

package/commands/pan/milestone-new.md

@@ -22,7 +22,9 @@ Brownfield equivalent of new-project. Project exists, project.md has history. Ga
 - `.planning/roadmap.md` — phase structure (continues numbering)
 - `.planning/state.md` — reset for new milestone
 
-**After:** `/pan:plan-phase [N]` to start execution.
+**After:** `/pan:design-phase [N]` → `/pan:plan-phase [N]` to design then plan the first phase.
+
+**Design altitude (ADR-0042):** product/strategic design — demand validation, competitive intelligence, market positioning — belongs HERE at milestone creation (via the requirements/research cycle, or `/pan:focus-design` for a strategic feature), done ONCE. Per-phase architecture/ADR/threat design is `/pan:design-phase`, run per phase. Do not defer product questions to per-phase design, and do not re-open them there.
 </objective>
 
 <execution_context>

package/commands/pan/optimize.md

@@ -23,7 +23,7 @@ Manage the circular optimization loop: apply recommendations, view stats, list r
 /pan:optimize stats
 /pan:optimize trace init [--description "what you're building"]
 /pan:optimize trace end
-/pan:optimize trace status
+/pan:optimize trace current
 /pan:optimize trace list
 ```
 
@@ -67,7 +67,7 @@ Start a new trace session before running a build. The hook fires automatically o
 ### trace end
 Finalize the current trace session (writes summary stats to session.json).
 
-### trace status
+### trace current
 Show the active trace session ID and event count.
 
 ### trace list

package/commands/pan/patches.md

@@ -27,7 +27,7 @@ Check for local patches directory:
 PATCHES_DIR=~/.claude/pan-local-patches
 # Local install fallback
 if [ ! -d "$PATCHES_DIR" ]; then
-  PATCHES_DIR=./.claude/pan-local-patches
+  PATCHES_DIR=~/.claude/pan-local-patches
 fi
 ```
 

package/commands/pan/plan-phase.md

@@ -19,6 +19,8 @@ Create executable phase prompts (plan.md files) for a roadmap phase with integra
 
 **Default flow:** Research (if needed) → Plan → Verify → Done
 
+**Design input (ADR-0042):** if `{phase}-design.md` exists (from `/pan:design-phase`, verified by `pan-design-checker`), it is an authoritative upstream input — `pan-planner` implements its approved architecture/decisions and `pan-plan-checker` verifies conformance (Design Conformance dimension). It is optional: a phase without a design.md plans exactly as before.
+
 **Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn pan-planner, verify with pan-plan-checker, iterate until pass or max iterations, present results.
 </objective>
 
@@ -132,7 +134,7 @@ Run once per invocation:
 pan-tools cache prime --summary
 ```
 
-Returns `{blocks: [{path, bytes, cache}], total_bytes, sha}`. On Claude Code with Opus 4.7, the host runtime translates these block references into `cache_control: ephemeral`. On non-Claude runtimes or older models this is a no-op — nothing breaks.
+Returns `{blocks: [{path, bytes, cache}], total_bytes, sha}`. On a host runtime that supports prompt caching (Claude Code does), the host translates these block references into `cache_control: ephemeral`. Where prompt caching is unavailable this is a no-op — nothing breaks.
 </cache_priming>
 
 <process>

package/commands/pan/preview.md

@@ -51,7 +51,7 @@ Consolidates Spec B v1's architect + simulate + predict-milestone into one entry
 
 **Output:** `.planning/architecture/dependency-graph.md`
 
-**Opus 4.7 1M-context bonus:** when the full repo fits in a single agent window, the agent cross-references plan text with actual source imports to catch coupling the frontmatter missed. On smaller-context models, the agent relies on data-layer output alone.
+**1M-context bonus:** when the full repo fits in a single agent window — which needs a model with a 1M-context window — the agent cross-references plan text with actual source imports to catch coupling the frontmatter missed. On smaller-context models, the agent relies on data-layer output alone.
 
 ### `milestone` — Completion ETA
 
@@ -103,12 +103,12 @@ The command returns the path to the generated preview document. Never paste the
 
 | Runtime | phase | phases | milestone |
 |---------|-------|--------|-----------|
-| Claude Code | Full, thinking enabled | Full, 1M-ctx bonus on Opus 4.7 | Full |
+| Claude Code | Full, thinking enabled | Full, plus 1M-ctx bonus when the window allows | Full |
 | OpenCode | Full | Data-layer + simple report | Full |
 | Gemini CLI | Full | Data-layer + simple report | Full |
 | Codex CLI | Full | Data-layer + simple report | Full |
 | Copilot CLI | Full | Data-layer + simple report | Full |
 
-The data layer (`pan-tools preview …`) works identically on all runtimes. What varies is the quality of the agent's synthesis — Opus 4.7 with thinking catches subtler risks than smaller models.
+The data layer (`pan-tools preview …`) works identically on all runtimes. What varies is the quality of the agent's synthesis — a thinking-capable Opus-class model catches subtler risks than smaller ones.
 
 </runtime_compatibility>

package/commands/pan/profile.md

@@ -37,7 +37,7 @@ The workflow handles all logic including:
 </process>
 
 <tier_decision_tree>
-**Opus 4.7 capability-aware routing** (since v2.10.0 — E-7). Even within a single profile, PAN picks a tier per-call based on three hints: context estimate, whether the task needs extended thinking, and whether prompt cache is warm.
+**Capability-aware routing** (shipped v2.10.0 — E-7). Even within a single profile, PAN picks a tier per-call based on three hints: context estimate, whether the task needs extended thinking, and whether prompt cache is warm.
 
 The decision order `resolveModel` applies after the baseline profile pick:
 
@@ -46,7 +46,7 @@ Baseline tier (from MODEL_PROFILES[agent][profile])
         │
         ▼
 ┌─────────────────────────────────────────────┐
-│ context_estimate > 700K tokens?             │── yes ──▶ force reasoning (only 1M-ctx tier)
+│ context_estimate > 700K tokens?             │── yes ──▶ force reasoning (widest ctx tier)
 └─────────────────────────────────────────────┘
         │ no
         ▼
@@ -66,7 +66,7 @@ Final tier → provider-native model name
 
 **Quick guide:**
 - Heavy verification (plan-checker, verifier, integration-checker, reviewer, debugger): `needs_thinking: true` — baseline upgrades fast→mid.
-- Map-codebase single-shot mode on Opus 4.7: `context_estimate > 700K` — forced to reasoning.
+- Whole-repo context estimates above the large-context threshold (`context_estimate > 700K` tokens — `LARGE_CONTEXT_TOKEN_THRESHOLD`): forced to reasoning, which inherits the model you launched with. Note the direction: `/pan:map-codebase` picks `single-shot` **at or below** 700K and `sharded` above it, so the repos that trip this rule are the ones the mapper is already sharding.
 - Routine exec tasks with project.md cached: `cache_warm + small ctx` — mid gets downgraded to fast for a cost win.
 - All rules are additive to the `quality` / `balanced` / `budget` profile you pick here — profile sets the floor, capability hints adjust upward or downward within that floor's band.