pan-wizard 3.27.0 → 3.28.0

package/README.md

@@ -4,7 +4,7 @@
 
 # PanWizard
 
-**Command a bot army for your codebase** — a *Mission Control* agent delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.
+**Command a bot army for your codebase** — a *Mission Control* agent delegates whole-project goals to specialist squads and ships behind a human merge gate (the army runs on Claude Code; the planning pipeline runs on all five CLIs). Five AI CLIs, zero context rot.
 
 **Solves context rot** — the quality degradation that happens as the model fills its context window.
 
@@ -42,7 +42,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 
 ### Architecture
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
 │  YOU                                                        │
 │  /pan:new-project → /pan:plan-phase → /pan:exec-phase    │
@@ -76,7 +76,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 
 ## Bot Army
 
-> **Don't run one phase — run the whole project.** `/pan:army` turns PAN's agents into a coordinated army that delivers a goal end-to-end: a **Mission Control** agent plans the mission and delegates to specialist **squads**, parallel builders each work an isolated git worktree, and **nothing reaches your main branch without green checks and your explicit approval.**
+> **Don't run one phase — run the whole project.** `/pan:army` (Claude Code only — it needs native sub-agent spawning; the other runtimes run the flat pipeline) turns PAN's agents into a coordinated army that delivers a goal end-to-end: a **Mission Control** agent plans the mission and delegates to specialist **squads**, parallel builders each work an isolated git worktree, and **nothing reaches your main branch without green checks and your explicit approval.**
 
 <div align="center">
 <img src="https://cdn.jsdelivr.net/npm/pan-wizard@latest/assets/pan-orchestration.png" alt="PanWizard specialist agents orchestrated along a pipeline" width="340" />
@@ -101,9 +101,9 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 
 - **A human merges.** The Release squad prepares a squash-merge and surfaces an `always-ask` approval instead of merging; pair it with branch protection on your repo, which is what makes that unbypassable rather than merely instructed. Recovery is `git revert` or the previous tag, never a force-push.
 - **Isolated builders.** Each Build agent forks its own `army/<task>` branch + git worktree, so parallel agents never share a file.
-- **Caps.** Delegation-depth cap, per-cycle spawn + budget ceilings, and a `.planning/orchestration/abort` kill-switch, re-checked before every spawn — the same harness as hierarchical exec, at campaign scale.
+- **Caps.** Delegation-depth cap, per-cycle spawn + budget ceilings, and a `.planning/orchestration/abort` kill-switch, re-checked before every spawn by Mission Control's protocol (prompt-enforced; the MCP `pan_next_action` path enforces the cycle cap, the budget cap when `caps.enforceBudget` is set, the abort switch and the human gate in code — delegation depth is bounded by which agents hold the `Task` tool) — the same harness as hierarchical exec, at campaign scale.
 
-**Run it over days.** `--schedule` arms a self-resuming campaign with a per-day budget that burns the backlog down across sessions — and *still* waits for you at every merge. **Autonomy runs up to the irreversible step; a human is at the step.**
+**Run it over days.** `--schedule` arms a resumable campaign with a per-day budget that burns the backlog down across sessions (the per-day budget is advisory — `campaign status` shows the day's spend — and an external scheduler triggers each `--continue`) — and *still* waits for you at every merge. **Autonomy runs up to the irreversible step; a human is at the step.**
 
 **Watch it live.** `/pan:hud` renders a single self-contained HTML dashboard — Mission Control over the squads, in-flight worktrees, campaign budget, telemetry, and the safety harness — in one page.
 
@@ -130,9 +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:
-1. **Runtime** — Claude Code, OpenCode, Gemini, Codex, Copilot CLI, or all
-2. **Location** — Global (all projects) or local (current project only)
+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.
 
 Verify with:
 - Claude Code / Gemini: `/pan:help`
@@ -176,7 +174,7 @@ npx pan-wizard --copilot --local   # Install to ./.github/
 npx pan-wizard --all --global      # Install to all directories
 ```
 
-Use `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.
+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.
 Add `--unified-skills` to install commands as one shared `.agents/skills/` tree read natively by every runtime (and Antigravity CLI) instead of per-runtime formats — see the User Guide for details.
 
@@ -285,11 +283,11 @@ If you prefer not to use that flag, add this to your project's `.claude/settings
 
 ## How It Works
 
-> **Already have code?** Run `/pan:map-codebase` first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then `/pan:new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns.
+> **Already have code?** Run `/pan:map-codebase` first. It analyzes your stack, architecture, conventions, and concerns — single-shot with one agent for repositories under the sharding threshold, six-way sharded above it. Then `/pan:new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns.
 
 ### 1. Initialize Project
 
-```
+```text
 /pan:new-project
 ```
 
@@ -308,7 +306,7 @@ You approve the roadmap. Now you're ready to build.
 
 ### 2. Discuss Phase
 
-```
+```text
 /pan:discuss-phase 1
 ```
 
@@ -336,15 +334,15 @@ The deeper you go here, the more the system builds what you actually want. Skip
 
 ### 3. Plan Phase
 
-```
+```text
 /pan:plan-phase 1
 ```
 
 The system:
 
 1. **Researches** — Investigates how to implement this phase, guided by your context.md decisions
-2. **Plans** — Creates 2-3 atomic task plans with XML structure
-3. **Verifies** — Checks plans against requirements, loops until they pass
+2. **Plans** — Creates atomic plans of 2-3 tasks each, with XML structure
+3. **Verifies** — Checks plans against requirements; up to three checker passes (two revisions), then the remaining issues come to you
 
 Each plan is small enough to execute in a fresh context window. No degradation, no "I'll be more concise now."
 
@@ -354,15 +352,15 @@ Each plan is small enough to execute in a fresh context window. No degradation,
 
 ### 4. Execute Phase
 
-```
+```text
 /pan:exec-phase 1
 ```
 
 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
-3. **Commits per task** — Every task gets its own atomic commit
+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
 
 Walk away, come back to completed work with clean git history.
@@ -371,7 +369,7 @@ Walk away, come back to completed work with clean git history.
 
 Plans are grouped into "waves" based on dependencies. Within each wave, plans run in parallel. Waves run sequentially.
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────┐
 │  PHASE EXECUTION                                                     │
 ├─────────────────────────────────────────────────────────────────────┤
@@ -405,36 +403,36 @@ This is why "vertical slices" (Plan 01: User feature end-to-end) parallelize bet
 
 ### 5. Verify Work
 
-```
+```text
 /pan:verify-phase 1
 ```
 
 **This is where you confirm it actually works.**
 
-Automated verification checks that code exists and tests pass. But does the feature *work* the way you expected? This is your chance to use it.
+Automated verification checks that code exists and tests pass. `/pan:verify-phase` re-runs that check on demand, goal-backward: does the codebase deliver what the phase promised?
 
 The system:
 
-1. **Extracts testable deliverables** — What you should be able to do now
-2. **Walks you through one at a time** — "Can you log in with email?" Yes/no, or describe what's wrong
-3. **Diagnoses failures automatically** — Spawns debug agents to find root causes
-4. **Creates verified fix plans** — Ready for immediate re-execution
+1. **Gates on the test suite** — a failing (or non-running) suite forces the verdict to `gaps_found`; the must-have checks still run so the report is complete
+2. **Checks every must-have** — each phase promise is verified against the code, not the task list
+3. **Reports the gaps** — a verification report with a per-truth status and the recommended fix plans
+4. **Hands the gaps to the planner** — `/pan:plan-phase N --gaps` writes the fix plans (`gap_closure: true`); `/pan:exec-phase N --gaps-only` runs just those
 
-If everything passes, you move on. If something's broken, you don't manually debug — you just run `/pan:exec-phase` again with the fix plans it created.
+On Claude Code, `/pan-diagnose-issues <phase>` spawns one debugger per failed UAT truth to find root causes. Manual acceptance testing stays yours: use the feature and record what you find in the phase's UAT file.
 
-**Creates:** `{phase_num}-uat.md`, fix plans if issues found
+**Creates:** `{phase_num}-verification.md`; fix plans follow from `/pan:plan-phase N --gaps`
 
 ---
 
 ### 6. Repeat → Complete → Next Milestone
 
-```
+```text
 /pan:discuss-phase 2
 /pan:plan-phase 2
 /pan:exec-phase 2
 /pan:verify-phase 2
 ...
-/pan:milestone-done
+/pan:milestone-done 1.0
 /pan:milestone-new
 ```
 
@@ -450,7 +448,7 @@ Then `/pan:milestone-new` starts the next version — same flow as `new-project`
 
 ### Quick Mode
 
-```
+```text
 /pan:quick
 ```
 
@@ -464,12 +462,12 @@ Quick mode gives you PAN guarantees (atomic commits, state tracking) with a fast
 
 Use for: bug fixes, small features, config changes, one-off tasks.
 
-```
+```text
 /pan:quick
 > What do you want to do? "Add dark mode toggle to settings"
 ```
 
-**Creates:** `.planning/quick/001-add-dark-mode-toggle/plan.md`, `summary.md`
+**Creates:** `.planning/quick/001-add-dark-mode-toggle/001-plan.md`, `001-summary.md`
 
 ---
 
@@ -522,7 +520,7 @@ Every stage uses the same pattern: a thin orchestrator spawns specialized agents
 | Stage | Orchestrator does | Agents do |
 |-------|------------------|-----------|
 | Research | Coordinates, presents findings | 4 parallel researchers investigate stack, features, architecture, pitfalls |
-| Planning | Validates, manages iteration | Planner creates plans, checker verifies, loop until pass |
+| Planning | Validates, manages iteration | Planner creates plans, checker verifies, up to three passes |
 | Execution | Groups into waves, tracks progress | Executors implement in parallel, each with a fresh context window |
 | Verification | Presents results, routes next | Verifier checks codebase against goals, debuggers diagnose failures |
 
@@ -550,7 +548,7 @@ PAN runs autonomous experiments in isolated folders, harvests the resulting tele
 
 ### Atomic Git Commits
 
-Each task gets its own commit immediately after completion:
+Each task gets its own commit immediately after completion (consecutive trivial chore or docs tasks are coalesced):
 
 ```bash
 abc123f docs(08-02): complete user registration plan
@@ -604,9 +602,9 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/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]` | Manual user acceptance testing ¹ |
+| `/pan:verify-phase [N]` | Re-run goal-backward verification with a test-suite gate; lists gaps for `/pan:plan-phase N --gaps` ¹ |
 | `/pan:milestone-audit` | Verify milestone achieved its definition of done |
-| `/pan:milestone-done` | Archive milestone, tag release |
+| `/pan:milestone-done <version>` | Archive milestone, tag release |
 | `/pan:milestone-new [name]` | Start next version: questions → research → requirements → roadmap |
 
 ### Navigation
@@ -615,6 +613,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 |---------|--------------|
 | `/pan:progress` | Where am I? What's next? |
 | `/pan:hud` (alias `/pan:dashboard`) | Render a self-contained HTML dashboard of project + bot-army state to `.planning/hud.html` (`--open`, `--out`, `--stdout`) |
+| `/pan:report phase <N> \| index \| all` | Self-contained HTML report for one phase, or a timeline index linking every phase report (`--out`, `--open`, `--stdout`; `--bundle` on `index` inlines every phase report into one file) |
 | `/pan:help` | Show all commands and usage guide |
 | `/pan:update` | Update PAN with changelog preview |
 | `/pan:discord` | Join the PAN Discord community |
@@ -635,9 +634,9 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:add-phase` | Append phase to roadmap |
-| `/pan:insert-phase [N]` | Insert urgent work between phases |
-| `/pan:remove-phase [N]` | Remove future phase, renumber |
+| `/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:milestone-gaps` | Create phases to close gaps from audit |
 
@@ -659,14 +658,15 @@ 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` auto-fixes detected issues |
-| `/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 — ledgers are quarantined by rename, never deleted, and settled `state.md` history is archived rather than dropped |
+| `/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, v3.8.0+) |
-| `/pan:phase-tests [N]` | Generate tests for a completed phase based on UAT criteria |
+| `/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: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) |
 
 ### Operations
 
@@ -710,7 +710,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:learn` | Analyze trace events, generate optimization report with auto-apply block |
 | `/pan:optimize {apply\|list\|stats\|trace}` | Apply optimizer recommendations, 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` | Audit a PAN installation for integrity (manifest verification, drift detection) |
+| `/pan:audit-deployment <target-directory> [--enhancements] [--repair]` | Audit a PAN installation for integrity, project health, and draft enhancement specs |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
 
@@ -724,8 +724,8 @@ PAN stores project settings in `.planning/config.json`. Configure during `/pan:n
 
 | Setting | Options | Default | What it controls |
 |---------|---------|---------|------------------|
-| `mode` | `yolo`, `interactive` | `interactive` | Auto-approve vs confirm at each step |
-| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness (phases × plans) |
+| `mode` | `yolo`, `interactive` | chosen at `/pan:new-project` (usually `interactive`) | Auto-approve vs confirm at each step |
+| `depth` | `quick`, `standard`, `comprehensive` | chosen at `/pan:new-project` (usually `standard`) | Planning thoroughness (phases × plans) |
 
 ### Model Profiles
 
@@ -737,10 +737,10 @@ Control which Claude model each agent uses. Balance quality vs token spend.
 | `balanced` (default) | reasoning | reasoning | reasoning |
 | `budget` | Sonnet | Sonnet | Haiku |
 
-> `reasoning` = the session model (inherit) — every agent runs on the model you launched the session with. Both `quality` and `balanced` resolve this way; only `budget` steps down to a Sonnet/Haiku mix. Actual assignment varies by agent role — see [User Guide](docs/USER-GUIDE.md#model-profiles-per-agent-breakdown) for the full per-agent breakdown.
+> `reasoning` = the session model (inherit) — every agent runs on the model you launched the session with, except the reviewer-class agents (reviewer, hardener, meta-reviewer), which pin a reasoning-tier model. Both `quality` and `balanced` resolve this way; only `budget` steps down to a Sonnet/Haiku mix. Actual assignment varies by agent role — see [User Guide](docs/USER-GUIDE.md#model-profiles-per-agent-breakdown) for the full per-agent breakdown.
 
 Switch profiles:
-```
+```text
 /pan:profile budget
 ```
 
@@ -784,7 +784,7 @@ Control how PAN handles branches during execution.
 - **`phase`** — Creates a branch per phase, merges at phase completion
 - **`milestone`** — Creates one branch for entire milestone, merges at completion
 
-At milestone completion, PAN Wizard offers squash merge (recommended) or merge with history.
+At milestone completion you merge the milestone branch yourself (`git merge --squash` or `--no-ff`); `/pan:milestone-done <version>` archives and tags but does not merge.
 
 ---
 
@@ -883,7 +883,7 @@ This removes all PAN commands, agents, hooks, and settings while preserving your
 | [Development Guide](docs/DEVELOPMENT.md) | Contributors | Setup, how to add commands/agents/tests, cross-platform pitfalls |
 | [CLI Reference](docs/CLI-REFERENCE.md) | Contributors | Every pan-tools.cjs subcommand with args, flags, and JSON output |
 | [Agent System](docs/AGENTS.md) | Contributors | Agent inventory, lifecycle, model profiles, collaboration patterns |
-| [Hook System](docs/HOOKS.md) | Contributors | 5 built-in hooks, bridge file architecture, custom hook development |
+| [Hook System](docs/HOOKS.md) | Contributors | The built-in hooks, bridge file architecture, custom hook development |
 | [Internals](docs/INTERNALS.md) | Power Users | Checkpoint system, TDD, verification patterns, model profiles |
 | [Troubleshooting](docs/TROUBLESHOOTING.md) | Users | Deep-dive diagnostics for execution, state, git, and verification issues |
 | [Contributing](CONTRIBUTING.md) | Contributors | Project structure, code style, PR process |

package/agents/pan-previewer.md

@@ -57,7 +57,7 @@ Before writing the report, think through:
 
 Write exactly one file at the path provided in your prompt. Use the template at `~/.claude/pan-wizard-core/templates/preview-report.md` as the skeleton.
 
-**For `phase` mode**, output path is `.planning/phases/<N>/preview.md`. Required sections:
+**For `phase` mode**, output path is `.planning/phases/<NN-slug>/preview.md`. Required sections:
 - `# Phase Preview: Phase N — <name>`
 - `## Summary` (one paragraph — what this phase changes + risk verdict)
 - `## Files likely touched` (bulleted, grouped by source/tests/docs)