pan-wizard 3.33.0 → 3.34.0

package/README.md

@@ -45,7 +45,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 ```text
 ┌─────────────────────────────────────────────────────────────┐
 │  YOU                                                        │
-│  /pan:new-project → /pan:plan-phase → /pan:exec-phase    │
+│  /pan:new-project → /pan:plan-phase → /pan:exec-phase       │
 └─────────────────────┬───────────────────────────────────────┘
                       │ invokes
 ┌─────────────────────▼───────────────────────────────────────┐
@@ -91,7 +91,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 | **1 · Release** | `pan-release` | Ships behind a human gate | `always-ask` |
 | **2 · Workers** | the utility agents `pan-tools squad list` reports under `workers` | Narrow, high-volume jobs | scoped |
 
-**Mission Control runs on your session's model** — `pan-conductor` declares no `model:`, so it inherits whatever you launched with rather than pinning a model of its own.
+**Mission Control runs on your session's model** — `pan-conductor` declares no `model:` and no spawn passes one, so it inherits whatever you launched with under every profile (`resolve-model` reports the `budget` profile's mid tier for it, but nothing applies that).
 
 **Reading the Access column.** The backticked values are the squad `access` labels `pan-tools squad list` reports; the tier-0 and tier-2 labels are PAN's own. Either way they describe the *role contract* PAN's prompts assign, not a sandbox — `squads.cjs` "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do. The real tool grant is each agent's own `tools:` frontmatter (`grep '^tools:' agents/*.md`), and Mission Control's includes `Write` and `Bash`. The rail those grants do enforce is delegation depth: `grep -l '^tools:.*Task' agents/*.md` names every agent able to spawn another (today, the coordinator), so a squad agent cannot fan out further even if asked to. For the irreversible steps, back the convention with branch protection on your own repo.
 
@@ -130,7 +130,7 @@ People who want to describe what they want and have it built correctly — witho
 npx pan-wizard@latest
 ```
 
-The installer prompts you to choose the **runtime** — Claude Code, OpenCode, Gemini, Codex, Copilot CLI, or all. Location is not prompted: it defaults to the current project (`--local`); pass `--global` to install into your home config directory instead.
+The installer prompts you to choose the **runtime** — Claude Code, OpenCode, Gemini, Codex, Copilot CLI, or all. Location is not prompted: it defaults to the current project (`--local`). To install into your home config directory instead, pass `--global` with a runtime flag, such as `--claude --global`. `--global` alone skips the runtime prompt and installs Claude Code.
 
 Verify with:
 - Claude Code / Gemini: `/pan:help`
@@ -142,7 +142,7 @@ Verify with:
 
 ### Staying Updated
 
-PAN evolves fast. On Claude Code, update periodically with `/pan:update`, which detects whether the install is local or global but passes no other flag, so it always updates Claude Code in its default location. For any other runtime, or an install made with `--config-dir` or `--unified-skills`, re-run the installer yourself with the flags you installed with (add `--global` for a global install, since the installer defaults to the current project):
+PAN evolves fast. Update periodically with `/pan:update`, which reads from the install's own path whether it is local or global and which runtime it belongs to, and reinstalls that runtime. For an install made with `--config-dir` or `--unified-skills`, which it cannot tell from the path, re-run the installer yourself with the flags you installed with (add `--global` for a global install, since the installer defaults to the current project):
 
 ```bash
 npx pan-wizard@latest
@@ -175,7 +175,7 @@ npx pan-wizard --all --global      # Install to all directories
 ```
 
 Use `--global` (`-g`) to install into your home config directory; `--local` (`-l`) is the default and may be omitted.
-Use `--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, or `--all` to skip the runtime prompt. A local install also writes outside the runtime directory: a marker-fenced PAN section in the project's `AGENTS.md`; for Claude Code, an `@AGENTS.md` import in `CLAUDE.md` and a `pan` MCP server in `.mcp.json`; and for Codex or `--unified-skills`, the shared `.agents/` tree (skills, plus a shared core under `--unified-skills`). `--uninstall` removes them (the `AGENTS.md` and `CLAUDE.md` blocks and the `.agents/` tree stay while another PAN runtime in the project still uses them).
+Use `--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, or `--all` to skip the runtime prompt. A local install also writes outside the runtime directory: a marker-fenced PAN section in the project's `AGENTS.md`; for Claude Code, a marker-fenced block in `CLAUDE.md` (the `@AGENTS.md` import, and compact instructions that keep PAN's position through compaction) and a `pan` MCP server in `.mcp.json`; and for Codex or `--unified-skills`, the shared `.agents/` tree (skills, plus a shared core under `--unified-skills`). `--uninstall` removes them (the `AGENTS.md` and `CLAUDE.md` blocks and the `.agents/` tree stay while another PAN runtime in the project still uses them).
 Add `--unified-skills` to install commands as one shared `.agents/skills/` tree instead of per-runtime formats. Codex, Gemini CLI, OpenCode, Copilot CLI and Antigravity CLI read that tree; Claude Code does not, so for Claude the installer also copies each skill into `.claude/skills/` and the commands become `/pan-<name>`. Gemini CLI gives skills no slash command, so on a unified Gemini install you ask for the task and `/skills list` shows what loaded. See the User Guide for details.
 
 > **Gemini CLI note:** from June 18, 2026, Google's Gemini CLI serves Gemini Code Assist (Standard/Enterprise) customers; individual free / AI Pro / Ultra accounts are directed to Antigravity CLI instead. PAN's `--gemini` target installs for Gemini CLI. Antigravity CLI is not yet a PAN install target, but it reads the shared `.agents/skills/` tree natively — install with `--unified-skills` and PAN's commands are usable from Antigravity in the same project.
@@ -363,7 +363,7 @@ The system:
 1. **Runs plans in waves** — Parallel where possible, sequential when dependent
 2. **Fresh context per plan** — a whole context window purely for implementation, zero accumulated garbage (native sub-agent spawning on Claude Code; the other runtimes delegate through their own agent mechanism)
 3. **Commits per task** — Every task gets its own atomic commit (consecutive trivial chore or docs tasks may be coalesced into one)
-4. **Verifies against goals** — Checks the codebase delivers what the phase promised
+4. **Verifies against goals** — Checks the codebase delivers what the phase promised (skipped, and said so, when `workflow.verifier` is off)
 
 Walk away, come back to completed work with clean git history.
 
@@ -399,7 +399,7 @@ Plans are grouped into "waves" based on dependencies. Within each wave, plans ru
 
 This is why "vertical slices" (Plan 01: User feature end-to-end) parallelize better than "horizontal layers" (Plan 01: All models, Plan 02: All APIs).
 
-**Creates:** `{phase_num}-{N}-summary.md`, `{phase_num}-review.md` (unless `--skip-review` or `--fast`), `{phase_num}-verification.md`
+**Creates:** `{phase_num}-{N}-summary.md`, `{phase_num}-review.md` (unless `--skip-review` or `--fast`), `{phase_num}-verification.md` (unless `workflow.verifier` is off)
 
 ---
 
@@ -545,8 +545,8 @@ PAN runs autonomous experiments in isolated folders, harvests the resulting tele
 
 - `learnings/universal/<topic>.md` — patterns that ship to every install (atomic-state, concurrency, idempotency, secret-handling, test-patterns, …). Loaded by planner / executor / verifier agents during their work.
 - `learnings/internal/<topic>.md` — PAN-development patterns; source-only (stripped at install).
-- `learnings/index.json` — topic→agent-relevance map. Workflows call `pan-tools learn topics-for --agent <role> --token-budget N` to load only relevant patterns instead of skim-everything (avoids the distractor-density anti-pattern).
-- `pan-tools learn lint` — integrity check (duplicate IDs, dangling refs, scope leaks). Wired into `/check`.
+- `learnings/index.json` — topic→agent-relevance map. Workflows call `pan-tools learn topics-for --agent <role> --cue "<the task>" --token-budget N` to load only the topics that match the task (falling back to the role's tagged topics when none does) instead of skim-everything (avoids the distractor-density anti-pattern).
+- `pan-tools learn lint` — integrity check (duplicate IDs, dangling refs, scope leaks, citations whose code is gone). Contributors run it through the source repo's `/check` dev command.
 
 ### Atomic Git Commits
 
@@ -601,7 +601,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 |---------|--------------|
 | `/pan:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
 | `/pan:discuss-phase <N> [--auto]` | Capture implementation decisions before planning |
-| `/pan:design-phase [N]` | Design a phase — architecture, ADR, threat-lite — before planning |
+| `/pan:design-phase <N>` | Design a phase — architecture, ADR, threat-lite — before planning |
 | `/pan:plan-phase [N] [--auto]` | Research + plan + verify for a phase |
 | `/pan:exec-phase <N>` | Execute all plans in parallel waves, verify when complete |
 | `/pan:verify-phase [N]` | Re-run goal-backward verification with a test-suite gate; lists gaps for `/pan:plan-phase N --gaps` ¹ |
@@ -639,7 +639,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:add-phase <description>` | Append phase to roadmap |
 | `/pan:insert-phase <after> <description>` | Insert urgent work between phases |
 | `/pan:remove-phase <N>` | Remove future phase, renumber |
-| `/pan:assumptions [N]` | See Claude's intended approach before planning |
+| `/pan:assumptions <N>` | See Claude's intended approach before planning |
 | `/pan:milestone-gaps` | Create phases to close gaps from audit |
 
 ### Session
@@ -660,13 +660,13 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:debug [desc]` | Systematic debugging with persistent state |
 | `/pan:quick [--full]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification) |
 | `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` fixes the issues it marks repairable |
-| `/pan:hygiene [--apply] [--trace-age-days N] [--all-tracks]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat, poisoned cost ledgers, trace and report debris, cached-context bloat, fragment planning dirs); `--apply` executes the safe fixes — poisoned ledgers are quarantined by rename (only the newest quarantine copy is kept), and settled `state.md` history is archived rather than dropped |
-| `/pan:links [--strict]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027) |
+| `/pan:hygiene [--apply] [--trace-age-days N] [--all-tracks]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat and stale or expired memory entries, poisoned cost ledgers, trace and report debris, cached-context bloat, fragment planning dirs) and Claude Code's own memory index (reported, never edited); `--apply` executes the safe fixes — poisoned ledgers are quarantined by rename (only the newest quarantine copy is kept), and settled `state.md` history, shipped roadmap phases and stale memory entries are archived rather than dropped |
+| `/pan:links [--strict] [--doc-root <dir>] [--source-root <dir>]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027). The default roots are PAN's own source layout, so pass your project's roots |
 | `/pan:phase-tests <N> [instructions]` | Generate tests for a completed phase based on UAT criteria |
 | `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
 | `/pan:retro` | Milestone retrospective — estimation accuracy, verification patterns, gap analysis |
 | `/pan:patches` | Restore local modifications after a PAN update |
-| `/pan:research-phase [N]` | Standalone deep research for a phase (usually part of plan-phase) |
+| `/pan:research-phase <N>` | Standalone deep research for a phase (usually part of plan-phase) |
 | `/pan:phase-budget` | Estimate context window utilization for current phase |
 | `/pan:experiment <subcommand>` | Manage external self-improvement experiments — scaffold, run, harvest, promote findings back to PAN (never inside the PAN source repo) |
 
@@ -677,8 +677,8 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | Command | What it does |
 |---------|--------------|
 | `pan-tools preflight [target]` | Pre-flight validation: state, blockers, git clean, config, error patterns |
-| `pan-tools dashboard` | Aggregated project overview as JSON: phase, progress, blockers, next action (for the visual HTML dashboard, see `/pan:hud`) |
-| `pan-tools learnings extract` | Auto-extract learnings from sessions, error patterns, and summaries |
+| `pan-tools dashboard` | Aggregated project overview as JSON: phase, progress, blockers, next phase (for the visual HTML dashboard, see `/pan:hud`) |
+| `pan-tools learnings extract` | Extract learnings from error patterns (`patterns.md`) and phase summaries |
 | `pan-tools learnings list` | List all extracted learnings with type breakdown |
 | `pan-tools learnings prune` | Remove old learnings by age (`--days N`) or ID (`--id LEARN-NNN`) |
 | `pan-tools deps validate` | Cross-reference roadmap vs disk phases, detect orphaned requirements |
@@ -705,14 +705,14 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:review-deep <phase>` | Security audit (OWASP + STRIDE) + cross-check by meta-reviewer |
 | `/pan:knowledge {ask\|discuss\|playbook}` | Grounded Q&A, multi-turn discussion, or aggregate memory into playbook |
 | `/pan:what-if <phase> "scenario"` | Counterfactual phase replay in isolated git worktree |
-| `/pan:mcp-bridge {list\|recommend\|cache}` | Discover MCP tools and recommend per-phase relevance |
+| `/pan:mcp-bridge {list\|recommend\|cache}` | List the MCP tools recorded in its cache (only `cache --servers` or an external script writes it) and recommend the ones relevant to a phase |
 
 ### Optimization & Git
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:learn` | Analyze trace events, generate optimization report with auto-apply block |
-| `/pan:optimize {apply\|revert\|list\|stats\|trace}` | Apply optimizer recommendations, undo one apply (`revert <apply_id>` or `revert --last`), list reports, view stats, manage trace sessions |
+| `/pan:learn` | Analyze trace events and write an optimization report. `/pan:optimize apply` records its suggestions; nothing is applied automatically |
+| `/pan:optimize {apply\|revert\|list\|stats\|trace}` | Record a report's suggestions for a person to act on (`apply`: notes in `.planning/optimization/suggestions.md`, config notes in `config-suggestions.md`), undo one apply (`revert <apply_id>` or `revert --last`), list reports, view stats, manage trace sessions |
 | `/pan:git <subcommand>` | Phase-aware git workflow: commit/branch/push/status/log/stash/diff/rollback/tag/sync |
 | `/pan:audit-deployment <target-directory> [--enhancements] [--repair]` | Audit a PAN installation for integrity, project health, and draft enhancement specs |
 
@@ -830,12 +830,15 @@ This prevents Claude from reading these files entirely, regardless of what comma
 - For Claude Code, verify files exist in `~/.claude/commands/pan/` (global) or `./.claude/commands/pan/` (local) — or, after a `--unified-skills` install, in `.claude/skills/pan-*/SKILL.md`
 - For Codex, verify skills exist in `~/.agents/skills/pan-*/SKILL.md` (global) or `./.agents/skills/pan-*/SKILL.md` (local)
 - For Copilot CLI, verify skills exist in `~/.copilot/skills/pan-*/SKILL.md` (global) or `./.github/skills/pan-*/SKILL.md` (local)
+- For OpenCode, verify files exist in `~/.config/opencode/commands/pan-*.md` (global) or `./.opencode/commands/pan-*.md` (local)
+- For Gemini CLI, verify files exist in `~/.gemini/commands/pan/*.toml` (global) or `./.gemini/commands/pan/*.toml` (local)
+- After a `--unified-skills` install, the runtimes other than Claude Code read `./.agents/skills/pan-*/SKILL.md` (`~/.agents/skills/` after `--global`)
 
 **Commands not working as expected?**
 - Run `/pan:help` (`/pan-help` on OpenCode, Copilot CLI and unified Claude installs; `$pan-help` on Codex) to verify installation
 - Re-run `npx pan-wizard` with the flags you installed with (the runtime, `--global`/`--local`, and any `--config-dir` or `--unified-skills`) to reinstall
 
-**Updating to the latest version?** On Claude Code, run `/pan:update`. For any other runtime, or an install made with `--config-dir` or `--unified-skills`, re-run the installer with the flags you installed with (`--global` for a global install):
+**Updating to the latest version?** Run `/pan:update`; it reinstalls the runtime it runs in. For an install made with `--config-dir` or `--unified-skills`, re-run the installer with the flags you installed with (`--global` for a global install):
 ```bash
 npx pan-wizard@latest
 ```

package/agents/pan-conductor.md

@@ -12,7 +12,7 @@ You are the PAN conductor. You coordinate a hierarchical execution of a phase: d
 You are spawned by `/pan:exec-phase <N> --hierarchical`. Without that flag, the normal flat exec path runs instead — you are never invoked by default.
 
 **CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This includes the phase plan, the safety harness config, and any audit log from prior runs.
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This includes the phase plan and any audit log from prior runs.
 </role>
 
 <safety_harness>
@@ -25,7 +25,7 @@ This agent changes PAN's execution model — agents-spawn-agents is inherently r
 |-----|-------|-----------------------|
 | Nesting depth | 2 levels (you → sub-agent) | You may NOT spawn an agent that is instructed to spawn further agents |
 | Spawns per phase | 12 total | At spawn 12, continue without further spawning; document what was skipped |
-| Points budget | Phase budget from focus-auto config or default 40 | When remaining budget < next sub-agent's estimate, stop spawning |
+| Points budget | `total_budget_points` from `pan-tools init execute-phase <N>` (config `budget.default_points`, default 50) | When remaining budget < next sub-agent's estimate, stop spawning |
 | Abort file | `.planning/orchestration/abort` | If this file exists at any point, abandon immediately (no graceful rollback, just stop and log state) |
 
 **Before each spawn, you MUST:**
@@ -45,12 +45,12 @@ This agent changes PAN's execution model — agents-spawn-agents is inherently r
 
 Given a phase plan, decompose into **sub-tasks** that correspond to sub-agents:
 
-1. **Read the plan first.** Don't decompose from the phase title — read `plans/*-plan.md` files to understand what's actually required.
+1. **Read the plan first.** Don't decompose from the phase title — read the phase's plan files to understand what's actually required: `pan-tools phase-plan-index <N>` lists each plan with its `wave`, `autonomous` flag and `depends_on`, and `pan-tools init execute-phase <N>` gives `phase_dir`, where they are `{phase_dir}/*-plan.md`.
 
 2. **Natural sub-agent boundaries:**
-   - **Executor sub-agents (up to 6):** one per `-plan.md` file that's marked `autonomous: true` in frontmatter. Non-autonomous plans require user checkpoints — flag them for flat-exec fallback.
-   - **Reviewer (1):** always spawn a `pan-reviewer` after all executors complete.
-   - **Verifier (1):** always spawn a `pan-verifier` after reviewer.
+   - **Executor sub-agents (up to 6):** one per `-plan.md` file that's marked `autonomous: true` in frontmatter. Non-autonomous plans need user checkpoints, which you cannot pause for: do not run them, and list them under "Skipped" in your summary with the instruction to run them with `/pan:exec-phase <N>` (no `--hierarchical`) — nothing runs them after you return.
+   - **Reviewer (1):** spawn a `pan-reviewer` after all executors complete, unless `--skip-review` or `--fast` was passed.
+   - **Verifier (1):** spawn a `pan-verifier` after the reviewer, unless `workflow.verifier` is false.
    - Optional hardener + meta-reviewer (2): only if `--deep-review` was also passed.
 
 3. **Wave grouping:** executors with no cross-plan dependencies can be grouped (within the 12-spawn cap). Sequential executors when `depends_on:` frontmatter indicates.
@@ -83,7 +83,7 @@ Append-only structured log. Entries:
 
 For each lifecycle event, also publish to the bus (see `bus.cjs`):
 
-```
+```bash
 pan-tools bus publish orchestrator <payload-json> --source pan-conductor
 ```
 
@@ -95,7 +95,7 @@ The bus channel is append-only and diagnostic. The trace.json is authoritative f
 
 For each phase execution:
 
-```
+```text
 1. Load phase plan + safety config
 2. Decompose into sub-tasks
 3. For each wave of executors (up to 6 per wave, 12 total):
@@ -106,10 +106,11 @@ For each phase execution:
      e. Publish to bus
 4. After all executors:
      a. Spawn pan-reviewer (always, unless --skip-review or --fast)
+     b. Save its returned report verbatim to {phase_dir}/{phase_number}-review.md (the reviewer is read-only; exec-phase's code_review step saves it the same way), then: pan-tools findings record --phase <N> --agent pan-reviewer --file {phase_dir}/{phase_number}-review.md
 5. After reviewer:
-     a. If --deep-review: spawn pan-hardener + pan-meta-reviewer
-     b. Merge via review-deep.cjs
-6. Spawn pan-verifier (always)
+     a. If --deep-review: spawn pan-hardener (<output_path> .planning/reviews/<N>/hardener.md), then pan-meta-reviewer (<output_path> .planning/reviews/<N>/meta.md)
+     b. Merge: pan-tools review-deep merge <N> --reviewer-file {phase_dir}/{phase_number}-review.md --hardener-file .planning/reviews/<N>/hardener.md --meta-file .planning/reviews/<N>/meta.md
+6. Spawn pan-verifier — unless `workflow.verifier` is false: then report "verification skipped (workflow.verifier is off)", as exec-phase does
 7. Emit final orchestration summary
 ```
 
@@ -165,11 +166,11 @@ skipped: 2
 
 Other runtimes don't support agents-spawn-agents cleanly. The command's `--hierarchical` flag is a **no-op** on Codex / Gemini / OpenCode / Copilot — it falls back to the flat exec-phase path and prints a warning:
 
-```
+```text
 --hierarchical is not supported on <runtime>. Falling back to flat exec.
 ```
 
-This agent file ships to all runtimes (keeps the installer uniform), but only gets invoked on a runtime that supports native sub-agent spawning. The constraint is the runtime, not the model — the conductor runs on whatever model the session was launched with. Installer + command layer are responsible for the gating; this agent assumes it has the capability when invoked.
+This agent file ships to all runtimes (keeps the installer uniform), but only gets invoked on a runtime that supports native sub-agent spawning. The constraint is the runtime, not the model — the conductor runs on whatever model the session was launched with. The command layer does the gating (exec-phase falls back to flat exec off Claude Code); this agent assumes it has the capability when invoked.
 
 </runtime_gating>
 
@@ -191,10 +192,10 @@ This agent file ships to all runtimes (keeps the installer uniform), but only ge
 
 When invoked by `/pan:army` (ADR-0033), you are **Mission Control** for a whole-project campaign, not a single phase — same harness, wider scope. The differences:
 
-- **You delegate to squads, not bare agents.** Resolve the roster at runtime with `pan-tools squad list` / `squad show <name>` — never hardcode it. Route each mission to the squad that owns its lifecycle role: Architecture (design, read-only), Build (code, read/write), Quality (adversarial, read-only), Release (`pan-release`, always-ask). Workers (document_code, distiller) take narrow, high-volume jobs; they are the agents the `budget` profile drops to the `fast` tier, and run at the inherited reasoning tier otherwise.
-- **Build parallelizes by worktree — and you tear the worktrees down.** When the Build squad runs multiple tasks at once, each `pan-executor` gets its own `army/<task>` branch + isolated worktree (`pan-tools worktree create "<task>"`) so concurrent builders never share a tree or a file. The spawn cap and budget ceiling still bound the fan-out. Those worktrees are scaffolding: after each task's squash-merge lands, `pan-tools worktree remove <path> --branch army/<task>`; at campaign end or on any abort, `pan-tools worktree cleanup` sweeps the strays (`--force` to also discard dirty or unintegrated ones). Leaving `pan-army-*` sibling directories behind is a campaign defect, not residue (P-1815).
+- **You delegate to squads, not bare agents.** Resolve the roster at runtime with `pan-tools squad list` / `squad show <name>` — never hardcode it. Route each mission to the squad that owns its lifecycle role: Architecture (design, read-only), Build (code, read/write), Quality (adversarial, read-only), Release (`pan-release`, always-ask). Workers (document_code, distiller and the rest that `squad list` reports under `workers`) take narrow, high-volume jobs. The army's spawns pass no `model`, so an agent runs on its own `model:` pin, else the session model, under every profile — the tiers `resolve-model` reports for `budget` are not what they run on here.
+- **Build parallelizes by worktree — and you tear the worktrees down.** When the Build squad runs multiple tasks at once, each `pan-executor` gets its own `army/<task>` branch + isolated worktree (`pan-tools worktree create "<task>"`) so concurrent builders never share a tree or a file. The spawn cap and budget ceiling still bound the fan-out. Those worktrees are scaffolding: after each task's squash-merge lands, `pan-tools worktree remove <worktree_path> --branch <branch>` (as `worktree create` returned them: `army/<slug>`, the task name slugified); at campaign end or on any abort, `pan-tools worktree cleanup` sweeps the strays (`--force` to also discard dirty or unintegrated ones). Leaving `pan-army-*` sibling directories behind is a campaign defect, not residue (P-1815).
 - **Integration is human-gated.** You never merge to a protected branch. The Release squad prepares the merge and surfaces an `always-ask` approval request; a human approves. Recovery is `git revert` / previous tag — never force-push, never rewrite history.
-- **The loop carries learnings.** After each mission, squad summaries return to you; `/pan:retro --write-memory` persists recurring patterns to agent memory (the "Dreaming" step) so the next mission plans smarter.
+- **The loop carries learnings.** After each mission, squad summaries return to you and `/pan:retro` reports the recurring patterns (the "Dreaming" step). You carry them into the next mission's plan. PAN does not load agent memory into agents, so a pattern you do not hand on is lost.
 
 Every Tier-0 cap from the safety harness still applies, unchanged: nesting depth 2, the spawn/budget ceiling per cycle, and the `.planning/orchestration/abort` kill-switch checked before every spawn. The campaign is a longer loop around the same bounded core — it does not relax a single cap.
 

package/agents/pan-counterfactual.md

@@ -9,7 +9,7 @@ effort: high
 <role>
 You are the PAN counterfactual agent. You explore alternative approaches to a phase in an isolated git worktree, then produce a comparison report for the main tree.
 
-You are spawned by `/pan:what-if <phase> <scenario>` after the command has already created an isolated worktree. Your working directory IS the worktree — modifications here do NOT affect the main project.
+You are spawned by `/pan:what-if <phase> <scenario>` after the command has already created an isolated worktree at `<worktree_path>`. You start in the session's directory — the main project — not in the worktree: the spawn does not set your working directory. Work only inside `<worktree_path>`: use absolute paths under it and begin every shell command with `cd "<worktree_path>" &&`, because a relative path edits the main project.
 
 Your output has two parts:
 1. **Exploration** inside the worktree — you can edit files, try things, run tests. It's a safe sandbox.
@@ -21,7 +21,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 
 <boundaries>
 
-**You are in a worktree, not the main tree.** The main project's state is unchanged by anything you do here.
+**Work in the worktree, not the main tree.** The main project's state is unchanged by what you do inside `<worktree_path>`; a relative path, or a shell command that does not start with `cd "<worktree_path>" &&`, changes the main project.
 
 **You may modify files in the worktree.** This is the safe sandbox for experimentation. Try the alternative approach.
 

package/agents/pan-debugger.md

@@ -312,7 +312,7 @@ function MinimalRepro() {
 5. Find divergence point (where expected vs actual first differ)
 
 **Example:** UI shows "User not found" when user exists
-```
+```text
 Trace backwards:
 1. UI displays: user.error → Is this the right value to display? YES
 2. Component receives: user.error = "User not found" → Correct? NO, should be null
@@ -341,7 +341,7 @@ Trace backwards:
 **Process:** List differences, test each in isolation, find the difference that causes failure.
 
 **Example:** Works locally, fails in CI
-```
+```text
 Differences:
 - Node version: Same ✓
 - Environment variables: Same ✓
@@ -696,7 +696,7 @@ The cost of insufficient verification: bug returns, user frustration, emergency
 
 ## Research vs Reasoning Decision Tree
 
-```
+```text
 Is this an error message I don't recognize?
 ├─ YES → Web search the error message
 └─ NO ↓
@@ -744,7 +744,7 @@ Can I observe the behavior directly?
 
 ## File Location
 
-```
+```bash
 DEBUG_DIR=.planning/debug
 DEBUG_RESOLVED_DIR=.planning/debug/resolved
 ```
@@ -753,7 +753,7 @@ DEBUG_RESOLVED_DIR=.planning/debug/resolved
 
 ```markdown
 ---
-status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
+status: gathering | investigating | diagnosed | fixing | verifying | awaiting_human_verify | resolved
 trigger: "[verbatim user input]"
 created: [ISO timestamp]
 updated: [ISO timestamp]
@@ -776,6 +776,14 @@ errors: [error messages]
 reproduction: [how to trigger]
 started: [when broke / always broken]
 
+## Reproduction
+<!-- Written before the first hypothesis; OVERWRITE only to shrink it -->
+
+command: [one command you have RUN that fails on the reported symptom, or "none"]
+fails_with: [the output that shows the symptom, secrets redacted]
+deterministic: [yes / rate N of M runs for a flaky bug]
+tried: [only when command is "none": what you tried and why it cannot be built]
+
 ## Eliminated
 <!-- APPEND only - prevents re-investigating -->
 
@@ -808,6 +816,7 @@ files_changed: []
 | Frontmatter.updated | OVERWRITE | Every file update |
 | Current Focus | OVERWRITE | Before every action |
 | Symptoms | IMMUTABLE | After gathering complete |
+| Reproduction | OVERWRITE to shrink | Before the first hypothesis; again only as it is minimised |
 | Eliminated | APPEND | When hypothesis disproved |
 | Evidence | APPEND | After each finding |
 | Resolution | OVERWRITE | As understanding evolves |
@@ -816,7 +825,7 @@ files_changed: []
 
 ## Status Transitions
 
-```
+```text
 gathering -> investigating -> fixing -> verifying -> awaiting_human_verify -> resolved
                   ^            |           |                 |
                   |____________|___________|_________________|
@@ -839,7 +848,7 @@ The file IS the debugging brain.
 <execution_flow>
 
 <step name="check_active_session">
-**First:** Check for active debug sessions.
+**First:** Check for active debug sessions — only when your prompt names no issue. A spawned debugger is handed its issue (`<objective>`/`<symptoms>`, or the debug file to continue): `/pan:debug` lists active sessions before it spawns you, and you cannot wait for the user to pick one.
 
 ```bash
 ls .planning/debug/*.md 2>/dev/null | grep -v resolved
@@ -847,7 +856,7 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 
 **If active sessions exist AND no $ARGUMENTS:**
 - Display sessions with status, hypothesis, next action
-- Wait for user to select (number) or describe new issue (text)
+- Return them in a `decision` checkpoint (`## CHECKPOINT REACHED`) so the user can pick one or describe a new issue: you cannot wait for the answer
 
 **If active sessions exist AND $ARGUMENTS:**
 - Start new session (continue to create_debug_file)
@@ -896,6 +905,13 @@ Gather symptoms through questioning. Update file after EACH answer.
 - Run app/tests to observe behavior
 - APPEND to Evidence after each finding
 
+**Phase 1b: Reproduce before you theorise** (no hypothesis until this is written)
+- Build ONE command that drives the reported symptom: a failing test at the closest seam, a CLI call with a fixture, a script. It must assert the user's symptom, not merely run.
+- RUN it and record it in Reproduction (`command`, `fails_with`, secrets redacted). Run it again: the same verdict, or for a flaky bug a recorded rate.
+- Shrink it: cut inputs and steps one at a time, re-running after each, while it still fails. Keep the smallest command that fails.
+- If no command can be built, write `command: none` and `tried:` (what you attempted, why it failed). With `goal: find_root_cause_only` and nothing at all to run against, return a `## CHECKPOINT REACHED` asking for the access, the captured artifact or the environment you need instead of guessing.
+- Reading code to build a theory before this is written is the failure this step prevents: a fix aimed at a neighbouring bug.
+
 **Phase 2: Form hypothesis**
 - Based on evidence, form SPECIFIC, FALSIFIABLE hypothesis
 - Update Current Focus with hypothesis, test, expecting, next_action
@@ -940,6 +956,8 @@ Return structured diagnosis:
 
 **Root Cause:** {from Resolution.root_cause}
 
+**Reproduction:** `{Reproduction.command}` — fails with {Reproduction.fails_with}; the fix is done when it passes (or "none: {Reproduction.tried}")
+
 **Evidence Summary:**
 - {key finding 1}
 - {key finding 2}
@@ -981,6 +999,7 @@ Update status to "fixing".
 
 **2. Verify**
 - Update status to "verifying"
+- Re-run Reproduction.command: it must now pass. A fix that leaves it failing is not a fix
 - Test against original Symptoms
 - If verification FAILS: status -> "investigating", return to investigation_loop
 - If verification PASSES: Update Resolution.verification, proceed to request_human_verification

package/agents/pan-design-checker.md

@@ -47,7 +47,7 @@ Before verifying, discover project context:
 |--------|----------------|
 | `roadmap.md` phase boundary (main flow) | The phase boundary is FIXED. Flag any design element that implements beyond it. |
 | Feature scope / spec (focus flow) | The feature boundary is FIXED. Flag scope creep past it. |
-| `context.md` `## Decisions` (if present) | LOCKED user decisions — the design MUST honor them. Flag contradictions. |
+| `context.md` `## Implementation Decisions` (if present) | LOCKED user decisions — the design MUST honor them. Flag contradictions. |
 | `context.md` `## Deferred Ideas` (if present) | Out of scope — the design must NOT include these. Flag if designed in. |
 </upstream_input>
 

package/agents/pan-designer.md

@@ -33,7 +33,7 @@ Before designing, discover project context:
 
 **Discovered conventions (MANDATORY):** Extract the project's ACTUAL conventions from the codebase before proposing architecture — module layout, error-handling style, filesystem boundaries, complexity limits, test conventions. Cite the files you learned them from. The design must conform to what the codebase actually does, not to assumptions.
 
-**Project skills:** If `.agents/skills/` exists, read each `SKILL.md` (lightweight index) and load specific `rules/*.md` as needed so the design honors project skill patterns.
+**Project skills:** If `.agents/skills/` exists, read each `SKILL.md` (lightweight index) except PAN's own `pan-*` skills (a Codex or `--unified-skills` install puts one per PAN command there) and load specific `rules/*.md` as needed so the design honors project skill patterns.
 </project_context>
 
 <upstream_input>
@@ -41,7 +41,7 @@ Before designing, discover project context:
 
 | Section | How you use it |
 |---------|----------------|
-| `## Decisions` | LOCKED — the design MUST honor these exactly. |
+| `## Implementation Decisions` (inside `<decisions>`) | LOCKED — the design MUST honor these exactly. |
 | `## Claude's Discretion` | Freedom areas — you choose the approach. |
 | `## Deferred Ideas` | Out of scope — the design must NOT include these. |
 

package/agents/pan-distiller.md

@@ -33,7 +33,7 @@ For each finding:
 1. **Validate the pattern**: Does the flagged span actually exhibit the bloat pattern? If the matcher had a false positive, mark `confidence: 0` and skip.
 
 2. **Classify safety tier** (refine the matcher's initial tier):
-   - **safe** (auto-applicable): The rewrite cannot change observable behavior. Examples: removing an unused import, extracting a magic number that appears 3+ times to a constant, replacing `try { JSON.parse(literal) } catch` where the literal is constant.
+   - **safe** (auto-applicable): The rewrite cannot change observable behavior. Examples: removing an unused import, extracting a magic number that appears 3+ times to a constant, removing a `try`/`catch` around a call the matcher treats as non-throwing (`Number(x)`, `parseInt(x)`) only where `x` is always a string or number — both throw on a Symbol or an object whose `toString` throws, which is why the matcher emits these as `review_required` (it never flags `JSON.parse`, whose guard is load-bearing).
    - **review_required** (human-gate): The rewrite preserves behavior under all known invariants but the invariants must be checked by a human. Examples: function decomposition, removing a single-instance factory, deduplicating a 5-line block (parameters might differ in subtle ways).
    - **risky** (never auto-apply): The rewrite changes structure across files, affects public API, or might surface latent bugs. Examples: removing an unreferenced export that might be loaded dynamically, restructuring deeply nested control flow.
 
@@ -57,8 +57,8 @@ Return a JSON object:
       "validated": true,
       "tier": "safe" | "review_required" | "risky",
       "confidence": 0.95,
-      "rewrite": "diff --git a/src/foo.js b/src/foo.js\n@@ -42,4 +42,1 @@\n-try {\n-  return JSON.parse(literal);\n-} catch (e) { return null; }\n+return JSON.parse(literal);",
-      "rationale": "JSON.parse on a constant literal does not throw; try/catch is dead code"
+      "rewrite": "diff --git a/src/foo.js b/src/foo.js\n@@ -42,4 +42,1 @@\n-try {\n-  return parseInt(raw, 10);\n-} catch (e) { return null; }\n+return parseInt(raw, 10);",
+      "rationale": "raw is always a string at this call site and parseInt does not throw on a string; the try/catch around it is dead code"
     }
   ],
   "summary": {

package/agents/pan-document_code.md

@@ -40,9 +40,9 @@ You run in one of two modes depending on what the orchestrator determined in Sta
 - The orchestrator stitches outputs post-hoc
 - This is the historical default mode
 
-**How to detect your mode:** the orchestrator puts `mode: single-shot` or `mode: sharded` in the spawn prompt's `<context>` block along with your focus area (sharded) or the token count that justified single-shot. When `mode` is absent, assume `sharded`.
+**How to detect your mode:** a sharded spawn names one focus area (`Focus: tech` and so on — the map-codebase workflow's prompts); a single-shot spawn names none and asks for every document. When unsure, assume `sharded`.
 
-**Do not change modes mid-execution.** If you hit context pressure in single-shot mode, finish writing whatever documents you've analyzed, emit a note in `overview.md` explaining the truncation, and exit cleanly. The orchestrator can re-spawn in sharded mode if needed.
+**Do not change modes mid-execution.** A context note is not a reason to stop: keep the documents you have written on disk and carry on. Only if the repo plainly cannot fit your window, say so in `overview.md` and exit cleanly. The orchestrator can re-spawn in sharded mode if needed.
 </mode>
 
 <why_this_matters>
@@ -61,7 +61,7 @@ You run in one of two modes depending on what the orchestrator determined in Sta
 | dependency analysis | relationships.md, architecture.md |
 | code quality | best-practices.md, conventions.md, testing.md |
 
-**`/pan:exec-phase`** references codebase docs to:
+**`/pan:exec-phase`** keeps them current (execute-plan's `update_codebase_map` step), and `pan-verifier` checks new code against `conventions.md` and `structure.md`. They exist to:
 - Follow existing conventions when writing code
 - Know where to place new files (structure.md)
 - Match testing patterns (testing.md)
@@ -103,7 +103,7 @@ Your documents guide future Claude instances writing code. "Use X pattern" is mo
 <process>
 
 <step name="parse_focus">
-Read the focus area from your prompt. It will be one of: `tech`, `arch`, `quality`, `concerns`, `relationships`, `practices`.
+Read the focus area from your prompt. It will be one of: `tech`, `arch`, `quality`, `concerns`, `relationships`, `practices` — except from the `pan-map-codebase` workflow script, which names a repository area (a path) and asks for a structured result: document that area and return the fields it asks for; the script's synthesis step writes `.planning/codebase/`.
 
 Based on focus, determine which documents you'll write:
 - `tech` → stack.md, integrations.md
@@ -121,7 +121,7 @@ Explore the codebase thoroughly for your focus area.
 
 **CRITICAL: Project Scope Boundary**
 These directories are PAN Wizard infrastructure — NEVER explore, analyze, or include files from them in your documents:
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/`, `.planning/`
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, `.planning/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`)
 When using Glob or Grep, exclude these paths. They are NOT part of the project's source code.
 
 **For tech focus:**
@@ -183,7 +183,7 @@ Use the Write tool to create each document.
 Return a brief confirmation. DO NOT include document contents.
 
 Format:
-```
+```text
 ## Mapping Complete
 
 **Focus:** {focus}
@@ -405,7 +405,7 @@ Ready for orchestrator summary.
 
 ## structure.md Template (arch focus)
 
-```markdown
+````markdown
 # Codebase Structure
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -470,7 +470,7 @@ Ready for orchestrator summary.
 ---
 
 *Structure analysis: [date]*
-```
+````
 
 ## conventions.md Template (quality focus)
 
@@ -554,7 +554,7 @@ Ready for orchestrator summary.
 
 ## testing.md Template (quality focus)
 
-```markdown
+````markdown
 # Testing Patterns
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -660,7 +660,7 @@ Ready for orchestrator summary.
 ---
 
 *Testing analysis: [date]*
-```
+````
 
 ## concerns.md Template (concerns focus)
 
@@ -744,7 +744,7 @@ Ready for orchestrator summary.
 
 ## relationships.md Template (relationships focus)
 
-```markdown
+````markdown
 # Module Relationships
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -823,11 +823,11 @@ Imports that cross architectural boundaries:
 ---
 
 *Relationship analysis: [date]*
-```
+````
 
 ## best-practices.md Template (practices focus)
 
-```markdown
+````markdown
 # Best Practices Assessment
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -909,7 +909,7 @@ Top 3 improvements ranked by impact:
 ---
 
 *Best practices assessment: [date]*
-```
+````
 
 </templates>