pan-wizard 3.35.0 → 3.37.0

package/{commands/pan → pan-wizard-core/workflows}/focus-drift-walking.md

@@ -1,19 +1,4 @@
----
-name: focus-drift-walking
-group: Focus
-description: Deep documentation-code drift detection, CLAUDE.md alignment, and auto-repair across all project directories
-argument-hint: "[--create] [--audit] [--repair] [--report] [--dir <path>] [--depth N] [--severity critical|high|medium|low|info] [--format markdown|json|checklist] [--quick]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - Agent
----
-
-# /pan:focus-drift-walking — Documentation-Code Drift Detection & Alignment
+# /pan:focus-auto --step drift — Documentation-Code Drift Detection & Alignment
 
 Walk every directory in the project, detect drift between documentation and code reality, create missing documentation, repair drifted files, and synchronize the truth hierarchy. $ARGUMENTS
 
@@ -23,7 +8,7 @@ Walk every directory in the project, detect drift between documentation and code
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command walks the **host project's directories and documentation** — NOT PAN Wizard's own infrastructure.
 
@@ -41,7 +26,7 @@ If a drift finding points to a file inside a PAN or build directory — DROP IT.
 
 ## MANDATORY: Execute ALL Phases Automatically
 
-When `/pan:focus-drift-walking` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete drift report at the end.
+When `/pan:focus-auto --step drift` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete drift report at the end.
 
 **Flags:**
 - `--create` — Create missing documentation files in directories that lack them

package/{commands/pan → pan-wizard-core/workflows}/focus-exec.md

@@ -1,19 +1,4 @@
----
-name: focus-exec
-group: Focus
-description: Automated batch execution pipeline with 6 stages, behavioral rules, 3 execution tiers
-argument-hint: "[--budget N] [--mode bugfix|balanced|features|full] [--priority P0-P6] [--dry-run] [--no-commit] [--continue] [--deep-review]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - Agent
----
-
-# /pan:focus-exec — Automated Batch Execution Pipeline
+# /pan:focus-auto --step exec — Automated Batch Execution Pipeline
 
 Execute items from the current focus batch with capacity-based sizing, full session lifecycle, and verification. $ARGUMENTS
 
@@ -36,7 +21,7 @@ Execution FAILS if: test baseline cannot be established (Stage 1), or test count
 ## Pipeline Overview
 
 ```
-/pan:focus-exec
+/pan:focus-auto --step exec
 
   Stage 1: SESSION START
     - Check project status, record baseline
@@ -95,7 +80,7 @@ This command executes work on the **host project's source code** — not on PAN
 
 ## Execute All Stages Sequentially
 
-When `/pan:focus-exec` is invoked, run all 6 stages in order. Do not skip stages or stop between them unless tests regress.
+When `/pan:focus-auto --step exec` is invoked, run all 6 stages in order. Do not skip stages or stop between them unless tests regress.
 
 <stage_dependencies>
 Stage 1 → Stage 2: Baseline MUST exist before batch loads (regression detection requires it)
@@ -106,7 +91,7 @@ Stage 5 → Stage 6: Docs MUST be updated before commit (commit captures the com
 
 HARD STOP conditions (do not proceed to next stage):
 - Stage 1: Test suite fails → fix tests before proceeding
-- Stage 2: No batch file found → tell user to run /pan:focus-plan
+- Stage 2: No batch file found → tell user to run /pan:focus-auto --step plan
 - Stage 4: Test count below baseline → revert last changes, re-verify
 </stage_dependencies>
 
@@ -235,7 +220,7 @@ baseline_commit: <current HEAD>
 
 ### 2.1 Find Active Batch
 Search for: `.planning/focus/batch-*.json`
-Pick the newest. If none exists, tell user to run `/pan:focus-plan` first.
+Pick the newest. If none exists, tell user to run `/pan:focus-auto --step plan` first.
 
 ### 2.2 Read and Validate the Batch
 Extract all items: ID, Title, Priority, Effort, Points, Tier, Files.
@@ -409,7 +394,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null
 ### 6.4 Final Report
 
 ```markdown
-## /pan:focus-exec Complete
+## /pan:focus-auto --step exec Complete
 
 | Stage | Status |
 |-------|--------|
@@ -427,8 +412,8 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null
 - **Tests:** Before N -> After M (+K new)
 
 ### Resume
-Run `/pan:focus-exec --continue` for remaining items.
-Run `/pan:focus-scan` to regenerate the scan.
+Run `/pan:focus-auto --step exec --continue` for remaining items.
+Run `/pan:focus-auto --step scan` to regenerate the scan.
 ```
 
 ---

package/{commands/pan → pan-wizard-core/workflows}/focus-plan.md

@@ -1,18 +1,4 @@
----
-name: focus-plan
-group: Focus
-description: Create capacity-budgeted work batch with spec coverage verification and 4 execution modes
-argument-hint: "[--budget N] [--mode bugfix|balanced|features|full] [--priority P0-P6] [--lean] [--no-spec-check]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-  - Glob
----
-
-# /pan:focus-plan — Capacity-Budgeted Work Batch Planner with Spec Coverage Verification
+# /pan:focus-auto --step plan — Capacity-Budgeted Work Batch Planner with Spec Coverage Verification
 
 Create a capacity-budgeted work batch from focus-scan results **with mandatory verification that planned work covers all relevant spec and ADR requirements.** $ARGUMENTS
 
@@ -20,7 +6,7 @@ Create a capacity-budgeted work batch from focus-scan results **with mandatory v
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command plans work batches for the **host project** — NOT for PAN Wizard's own infrastructure.
 
@@ -34,7 +20,7 @@ If a scan item points to a PAN infrastructure file, DROP it from the batch. PAN'
 
 ## MANDATORY: Run focus-scan first
 
-If no recent scan exists, run `/pan:focus-scan` automatically before proceeding.
+If no recent scan exists, run `/pan:focus-auto --step scan` automatically before proceeding.
 
 **Flags:**
 - `--budget N` — Override capacity budget in points (default: 50, min: 5, max: 100)
@@ -215,13 +201,13 @@ For each success criterion in the batch, specify HOW it will be verified after e
 | SC-2 | Keywords >= 500 | `SELECT COUNT(*) FROM stx_keyword` | >= 500 |
 | SC-5 | No regression | `dotnet test` | All pass, count >= N |
 
-This becomes the post-execution checklist for `/pan:focus-exec`.
+This becomes the post-execution checklist for `/pan:focus-auto --step exec`.
 
 ---
 
 ## Phase 5: Output
 
-Write the batch to `.planning/focus/batch-<YYYY-MM-DD>.json` yourself — `{date, mode, budget, allocated, items: [...]}`, each item `{id, title, priority, effort, points, tier, files}` with `tier` one of `MICRO`, `STANDARD`, `FULL` (`focus exec` and `focus classify-stages` group items by it, and an item without it lands in no wave); `focus exec`, `focus classify-stages` and `/pan:focus-exec` read an `items` or `batch` array. Do not hand this step to `pan-tools focus plan`: it ignores the scan and the spec mapping, batches only incomplete roadmap phases, pending todos and `.planning/patterns.md` entries, and overwrites the day's batch file:
+Write the batch to `.planning/focus/batch-<YYYY-MM-DD>.json` yourself — `{date, mode, budget, allocated, items: [...]}`, each item `{id, title, priority, effort, points, tier, files}` with `tier` one of `MICRO`, `STANDARD`, `FULL` (`focus exec` and `focus classify-stages` group items by it, and an item without it lands in no wave); `focus exec`, `focus classify-stages` and `/pan:focus-auto --step exec` read an `items` or `batch` array. Do not hand this step to `pan-tools focus plan`: it ignores the scan and the spec mapping, batches only incomplete roadmap phases, pending todos and `.planning/patterns.md` entries, and overwrites the day's batch file:
 
 ```markdown
 ## Focus Batch — <date>
@@ -267,7 +253,7 @@ Write the batch to `.planning/focus/batch-<YYYY-MM-DD>.json` yourself — `{date
 Execution Order: MICRO first, then STANDARD, then FULL
 ```
 
-Ready for `/pan:focus-exec`.
+Ready for `/pan:focus-auto --step exec`.
 
 ---
 

package/{commands/pan → pan-wizard-core/workflows}/focus-scan.md

@@ -1,17 +1,4 @@
----
-name: focus-scan
-group: Focus
-description: Deep-dive strategic work scan with prioritized items and Reality Score filtering
-argument-hint: "[--focus <area>] [--quick] [--refresh] [--lean]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-  - Glob
----
-
-# /pan:focus-scan — Deep-Dive Strategic Work Scan
+# /pan:focus-auto --step scan — Deep-Dive Strategic Work Scan
 
 Survey the project for prioritized work items with evidence-based scoring. $ARGUMENTS
 
@@ -48,7 +35,7 @@ Do not read entire files when Grep can find the relevant lines. Do not use Bash
 
 ## Execute All Phases Automatically
 
-When `/pan:focus-scan` is invoked, execute all phases without stopping. Do not ask questions between phases or skip phases. The output is a prioritized work list with Reality Score filtering.
+When `/pan:focus-auto --step scan` is invoked, execute all phases without stopping. Do not ask questions between phases or skip phases. The output is a prioritized work list with Reality Score filtering.
 
 **Flags:**
 - `--focus <area>` — Weight items toward a specific area (e.g., `--focus commands`, `--focus hooks`, `--focus tests`)
@@ -237,7 +224,7 @@ Gather items from:
 ## Phase 5: Scan Assembly
 
 ### 5.1 Output
-Write the scan to `.planning/focus/scan-<YYYY-MM-DD>.md`, where `/pan:focus-plan` builds from it and `/pan:focus-exec` updates it (Stage 5.2). `pan-tools focus scan` does not take these items: it lists only incomplete roadmap phases that have a directory, pending todos and `.planning/patterns.md` entries.
+Write the scan to `.planning/focus/scan-<YYYY-MM-DD>.md`, where `/pan:focus-auto --step plan` builds from it and `/pan:focus-auto --step exec` updates it (Stage 5.2). `pan-tools focus scan` does not take these items: it lists only incomplete roadmap phases that have a directory, pending todos and `.planning/patterns.md` entries.
 
 ### 5.2 Document Structure
 

package/{commands/pan → pan-wizard-core/workflows}/focus-sync.md

@@ -1,18 +1,4 @@
----
-name: focus-sync
-group: Focus
-description: Synchronize documentation after changes — check staleness and update counts
-argument-hint: "[--readme | --docs | --arch | --all]"
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
-  - Edit
-  - Write
----
-
-# /pan:focus-sync — Documentation Synchronization
+# /pan:focus-docs --sync — Documentation Synchronization
 
 Synchronize project documentation across all files. $ARGUMENTS
 
@@ -20,7 +6,7 @@ Synchronize project documentation across all files. $ARGUMENTS
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command synchronizes the **host project's documentation** — NOT PAN Wizard's own infrastructure files.
 
@@ -35,11 +21,11 @@ This command synchronizes the **host project's documentation** — NOT PAN Wizar
 ## Usage
 
 ```
-/pan:focus-sync                  # Full sync check: report staleness
-/pan:focus-sync --readme         # Check README.md only
-/pan:focus-sync --docs           # Verify documentation matches implementations
-/pan:focus-sync --arch           # Verify architecture docs match actual structure
-/pan:focus-sync --all            # Full sync of everything + auto-fix
+/pan:focus-docs --sync                  # Full sync check: report staleness
+/pan:focus-docs --sync --readme         # Check README.md only
+/pan:focus-docs --sync --docs           # Verify documentation matches implementations
+/pan:focus-docs --sync --arch           # Verify architecture docs match actual structure
+/pan:focus-docs --sync --all            # Full sync of everything + auto-fix
 ```
 
 ---

package/pan-wizard-core/workflows/health.md

@@ -72,6 +72,12 @@ Status: HEALTHY | DEGRADED | BROKEN
 Errors: N | Warnings: N | Info: N
 ```
 
+**Ask per repair class before repairing.** With `--repair`, run `validate health` without it first and read `repairs_available` (for example `resetConfig`, `regenerateState`, `syncRequirements`, `syncRoadmap`). Ask about each class on its own, saying what it rewrites (state.md is backed up before regeneration; config.json is reset to defaults). Then repair only the classes the user accepted:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs validate health --repair --only <class>,<class>
+```
+A class the user declines is not touched.
+
 **If repairs were performed:**
 ```
 ## Repairs Performed

package/pan-wizard-core/workflows/help.md

@@ -36,26 +36,26 @@ Best for: new projects, structured milestones, large multi-phase builds.
 Best for: existing projects, ongoing maintenance, iterative improvement, batch work sessions.
 
 ```
-/pan:focus-scan            # 1. SCAN — find all work items, prioritize, score
+/pan:focus-auto --step scan            # 1. SCAN — find all work items, prioritize, score
   /clear
-/pan:focus-plan            # 2. PLAN — budget items into a sized batch
+/pan:focus-auto --step plan            # 2. PLAN — budget items into a sized batch
   /clear
-/pan:focus-exec            # 3. EXEC — implement, test, verify, commit
+/pan:focus-auto --step exec            # 3. EXEC — implement, test, verify, commit
   /clear
-/pan:focus-sync            # 4. SYNC — update docs to match changes
+/pan:focus-docs --sync            # 4. SYNC — update docs to match changes
 ```
 
 **focus-design** is a standalone command for deep feature investigation:
 ```
 /pan:focus-design "Add webhook support"  # Research, design, spec, ADR
   /clear
-/pan:focus-scan                          # Re-scan to pick up new tasks
+/pan:focus-auto --step scan                          # Re-scan to pick up new tasks
 ```
 
 **Documentation quality commands:**
 ```
-/pan:focus-drift-walking                 # Walk project tree, detect doc-code drift
-/pan:focus-doc-audit                     # Deep document audit with quality scoring
+/pan:focus-auto --step drift                 # Walk project tree, detect doc-code drift
+/pan:focus-docs                     # Deep document audit with quality scoring
 ```
 
 ---
@@ -68,30 +68,30 @@ Already have a codebase? Here's how to get started:
 |-----------|---------|
 | Quick one-off fix or small feature | `/pan:quick "add logout button"` |
 | Need to design a feature first | `/pan:focus-design "Add webhook support"` |
-| Find and fix bugs, tech debt, gaps | `/pan:focus-scan` → `plan` → `exec` |
+| Find and fix bugs, tech debt, gaps | `/pan:focus-auto --step scan` → `plan` → `exec` |
 | Large feature needing multiple phases | `/pan:milestone-new` |
 | Continuous automated improvement | `/pan:focus-auto` |
 
 **Most common path — iterative improvement:**
 ```
-/pan:focus-scan       # 1. Find work items (bugs, TODOs, gaps, features)
+/pan:focus-auto --step scan       # 1. Find work items (bugs, TODOs, gaps, features)
   /clear
-/pan:focus-plan       # 2. Budget a batch (--mode features for feature work)
+/pan:focus-auto --step plan       # 2. Budget a batch (--mode features for feature work)
   /clear
-/pan:focus-exec       # 3. Implement, test, commit
+/pan:focus-auto --step exec       # 3. Implement, test, commit
   /clear
-/pan:focus-sync       # 4. Update docs to match
+/pan:focus-docs --sync       # 4. Update docs to match
 ```
 
 **Design-first path — new feature on existing codebase:**
 ```
 /pan:focus-design "Add webhook support"   # Research → spec → ADR
   /clear
-/pan:focus-scan                           # Picks up tasks from spec
+/pan:focus-auto --step scan                           # Picks up tasks from spec
   /clear
-/pan:focus-plan --mode features           # Budget toward feature work
+/pan:focus-auto --step plan --mode features           # Budget toward feature work
   /clear
-/pan:focus-exec                           # Build it
+/pan:focus-auto --step exec                           # Build it
 ```
 
 **Large feature path — structured milestone on existing codebase:**
@@ -111,7 +111,7 @@ Already have a codebase? Here's how to get started:
 
 The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step feeds the next.
 
-### Step 1: `/pan:focus-scan`
+### Step 1: `/pan:focus-auto --step scan`
 
 **What it does:** Deep-dives into your entire codebase — reads every module, greps for TODOs/FIXMEs, runs tests, checks coverage gaps, reads your roadmap — then produces a prioritized work list.
 
@@ -119,7 +119,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Reality Score:** Every P3-P6 item gets scored: `RS = (User Value + Time Criticality + Risk Reduction) / Job Size`. Items below RS 3.0 get deferred, below 1.5 get dropped.
 
-**Output:** the prioritized work list, returned by `pan-tools focus scan` as JSON (`/pan:focus-plan` collects the items again itself).
+**Output:** the prioritized work list, returned by `pan-tools focus scan` as JSON (`/pan:focus-auto --step plan` collects the items again itself).
 
 **Flags:**
 - `--quick` — skip strategic analysis and validation phases
@@ -127,7 +127,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 - `--focus <area>` — weight items toward a specific area
 - `--refresh` — force re-read all files
 
-### Step 2: `/pan:focus-plan`
+### Step 2: `/pan:focus-auto --step plan`
 
 **What it does:** Reads the scan output and selects a right-sized batch of work items that fits within a point budget. Orders items for maximum impact with minimum risk.
 
@@ -143,14 +143,14 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Point system:** XS=1, S=2, M=4, L=10, XL=20 points.
 
-**Output:** `.planning/focus/batch-<date>.json` — the execution batch that `/pan:focus-exec` reads.
+**Output:** `.planning/focus/batch-<date>.json` — the execution batch that `/pan:focus-auto --step exec` reads.
 
 **Flags:**
 - `--mode <mode>` — select execution mode (default: balanced)
 - `--budget N` — override point budget (5-100)
 - `--lean` — exclude items with RS < 1.5
 
-### Step 3: `/pan:focus-exec`
+### Step 3: `/pan:focus-auto --step exec`
 
 **What it does:** One-command pipeline that implements every item in the batch. Runs 6 stages automatically:
 
@@ -175,7 +175,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 - `--continue` — resume a previously interrupted run
 - `--dry-run` — show stages 1-2 only
 
-### Step 4: `/pan:focus-sync`
+### Step 4: `/pan:focus-docs --sync`
 
 **What it does:** Checks all documentation for staleness and fixes it. Compares actual command counts, module counts, test counts against what docs claim.
 
@@ -209,81 +209,119 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 ## All Commands
 
-> This table is a **curated subset** of the most-used commands, not an exhaustive list. For the full, always-current command set, browse the `commands/pan/*.md` files in your install (each `.md` is one `/pan:<name>` command).
+Every shipped command, by group. This list is generated from each command's own description, so it is complete.
 
+<!-- generated:command-index:start (scripts/build-help.cjs --write) -->
 ### Getting Started
 | Command | Description |
 |---------|-------------|
-| `/pan:new-project` | Initialize new project — research, requirements, roadmap |
-| `/pan:map-codebase` | Analyze existing codebase with parallel agents |
+| `/pan:map-codebase` | Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents |
+| `/pan:new-project` | Initialize a new project with deep context gathering and project.md |
 
 ### Phase Lifecycle
 | Command | Description |
 |---------|-------------|
-| `/pan:discuss-phase <N>` | Shape implementation through targeted questions |
-| `/pan:plan-phase <N>` | Research + plan a phase with verification |
-| `/pan:exec-phase <N>` | Execute plans with wave-based parallelization |
-| `/pan:research-phase <N>` | Deep ecosystem research for specialized domains |
-| `/pan:verify-phase <N>` | Re-run goal-backward verification with a test-suite gate |
+| `/pan:autodev` | Run the roadmap unattended — a deterministic loop that plans, executes, verifies and completes phase after phase, each step in a fresh host session, and stops in code |
+| `/pan:design-phase` | Design a roadmap phase before planning — architecture, ADR, threat-lite, machine-checkable criteria — verified by an independent checker |
+| `/pan:discuss-phase` | Gather phase context through adaptive questioning before planning |
+| `/pan:exec-phase` | Execute all plans in a phase with wave-based parallelization |
+| `/pan:plan-phase` | Create detailed phase plan (plan.md) with verification loop |
+| `/pan:verify-phase` | Re-run goal-backward verification of a phase with a test-suite gate and list its gaps, or walk its UAT with --uat |
 
 ### Phase Management
 | Command | Description |
 |---------|-------------|
-| `/pan:add-phase <desc>` | Append new phase to roadmap |
-| `/pan:insert-phase <N> <desc>` | Insert urgent work between phases |
-| `/pan:remove-phase <N>` | Remove phase and renumber |
-| `/pan:assumptions <N>` | Surface approach assumptions before planning |
-| `/pan:phase-tests <N>` | Generate tests for completed phase |
-| `/pan:phase-budget` | Estimate context utilization for current phase |
+| `/pan:add-phase` | Add phase to end of current milestone in roadmap |
+| `/pan:assumptions` | Surface Claude's assumptions about a phase approach before planning |
+| `/pan:insert-phase` | Insert urgent work as decimal phase (e.g., 72.1) between existing phases |
+| `/pan:phase-budget` | Estimate context utilization and quality for the current phase |
+| `/pan:phase-tests` | Generate tests for a completed phase from its summaries, context decisions, verification report and implementation |
+| `/pan:remove-phase` | Remove a future phase from roadmap and renumber subsequent phases |
 
 ### Session & Progress
 | Command | Description |
 |---------|-------------|
-| `/pan:progress` | Check status and route to next action |
-| `/pan:quick <desc>` | Fast-path execution (skip optional agents) |
-| `/pan:pause` | Save context for later resumption |
-| `/pan:resume` | Restore previous session context |
-| `/pan:profile <name>` | Switch model profile (quality/balanced/budget) |
+| `/pan:pause` | Create context handoff when pausing work mid-phase |
+| `/pan:progress` | Check project progress, show context, and route to next action (execute or plan) |
+| `/pan:quick` | Execute a quick task with PAN guarantees (atomic commits, state tracking) but skip optional agents |
+| `/pan:resume` | Resume work from previous session with full context restoration |
 
 ### Milestone
 | Command | Description |
 |---------|-------------|
-| `/pan:milestone-new` | Start a new milestone cycle |
-| `/pan:milestone-done <v>` | Archive completed milestone |
-| `/pan:milestone-audit` | Audit completion against intent |
-| `/pan:milestone-gaps` | Create phases to close audit gaps |
-| `/pan:milestone-cleanup` | Archive accumulated phase directories |
-| `/pan:retro` | Milestone retrospective — estimation & verification analysis |
-
-### Focus (Strategic Project Management)
+| `/pan:milestone-audit` | Audit milestone completion against original intent before archiving |
+| `/pan:milestone-done` | Archive completed milestone and prepare for next version |
+| `/pan:milestone-new` | Start a new milestone cycle — update project.md and route to requirements |
+
+### Milestone Lifecycle
 | Command | Description |
 |---------|-------------|
-| `/pan:focus-scan` | Step 1: Find and prioritize all work items |
-| `/pan:focus-plan` | Step 2: Budget items into an execution batch |
-| `/pan:focus-exec` | Step 3: Implement, test, verify, commit |
-| `/pan:focus-sync` | Step 4: Synchronize documentation after changes |
-| `/pan:focus-auto` | Continuous scan→plan→exec loop with safety harness |
-| `/pan:focus-design <desc>` | Standalone: Deep feature investigation and spec |
-| `/pan:focus-drift-walking` | Walk project tree, detect doc-code drift, auto-repair |
-| `/pan:focus-doc-audit` | Deep document audit with quality scoring |
+| `/pan:retro` | Milestone retrospective — analyze estimation accuracy, verification patterns, and common gaps |
 
-### System
+### Focus
+| Command | Description |
+|---------|-------------|
+| `/pan:focus-auto` | Continuous scan-plan-exec loop with purpose-driven categories and a layered safety harness |
+| `/pan:focus-design` | Strategic 10-phase feature investigation, design, and specification pipeline |
+| `/pan:focus-docs` | Documentation audit and sync — accuracy, freshness, links, cross-consistency and structure; --sync updates stale docs after changes |
+
+### Foresight
+| Command | Description |
+|---------|-------------|
+| `/pan:preview` | Preview what will happen — phase blast radius, phase dependency graph, or milestone ETA |
+| `/pan:what-if` | Explore a phase's alternative approach in an isolated git worktree. Replays the scenario, compares to the original plan, writes a report. |
+
+### Review
+| Command | Description |
+|---------|-------------|
+| `/pan:review-deep` | Security audit + cross-reviewer check. OWASP/STRIDE pass by pan-hardener, then pan-meta-reviewer catches what the first pass missed. Writes consolidated deep-review.md. |
+
+### Validation
+| Command | Description |
+|---------|-------------|
+| `/pan:links` | Validate the doc-code link graph — inline wiki-style refs, source-comment anchors, and require-code-mention contracts (ADR-0027, v3.8.0+) |
+
+### Observability
 | Command | Description |
 |---------|-------------|
-| `/pan:help` | Show this reference |
-| `/pan:health` | Diagnose planning directory integrity |
-| `/pan:settings` | Configure workflow toggles |
-| `/pan:update` | Update PAN to latest version |
-| `/pan:debug` | Systematic debugging with persistent state |
-| `/pan:todo-add` | Capture idea as todo |
-| `/pan:todo-check` | List and select pending todos |
-| `/pan:audit-deployment <dir>` | Audit a PAN installation for integrity and health |
-
-### Community
+| `/pan:cost` | Show token usage and estimated cost across PAN commands and agents |
+| `/pan:hud` | Generate a single-page, self-contained HTML dashboard of the bot army and the project's current state |
+| `/pan:report` | Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report |
+
+### Knowledge
+| Command | Description |
+|---------|-------------|
+| `/pan:knowledge` | Grounded Q&A, multi-turn design discussion, and playbook generation. Three modes in one command. |
+
+### Self-Improvement
+| Command | Description |
+|---------|-------------|
+| `/pan:experiment` | Manage external experiments — scaffold, run, harvest, promote findings back to PAN |
+| `/pan:learn` | Analyze trace sessions or harvested experiments via pan-optimizer; generate ranked optimization reports |
+
+### Git Workflow
+| Command | Description |
+|---------|-------------|
+| `/pan:git` | Safe, phase-aware git workflow commands — commit, branch, push, status, log, stash, diff, rollback, tag, sync |
+
+### Army
+| Command | Description |
+|---------|-------------|
+| `/pan:army` | 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. |
+
+### System
 | Command | Description |
 |---------|-------------|
-| `/pan:discord` | Join the PAN Discord community |
-| `/pan:patches` | Reapply local modifications after update |
+| `/pan:debug` | Systematic debugging with persistent state across context resets |
+| `/pan:health` | Diagnose planning directory health and optionally repair issues |
+| `/pan:help` | Show available PAN commands and usage guide |
+| `/pan:hygiene` | Scan the project for PAN version drift and stale artifacts (legacy filenames, memory bloat and stale entries, poisoned ledgers, trace debris, oversized planning files) and apply safe cleanups |
+| `/pan:patches` | Reapply local modifications after a PAN update |
+| `/pan:settings` | Configure PAN workflow toggles and model profile |
+| `/pan:todo-add` | Capture idea or task as todo from current conversation context |
+| `/pan:todo-check` | List pending todos and select one to work on |
+| `/pan:update` | Update PAN to latest version with changelog display |
+<!-- generated:command-index:end -->
 
 ---
 
@@ -296,12 +334,12 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Existing project, iterative work:**
 ```
-/pan:focus-scan → /clear → /pan:focus-plan → /clear → /pan:focus-exec → /clear → /pan:focus-sync
+/pan:focus-auto --step scan → /clear → /pan:focus-auto --step plan → /clear → /pan:focus-auto --step exec → /clear → /pan:focus-docs --sync
 ```
 
 **Design a feature, then build it:**
 ```
-/pan:focus-design "feature" → /clear → /pan:focus-scan → /clear → /pan:focus-plan → /clear → /pan:focus-exec
+/pan:focus-design "feature" → /clear → /pan:focus-auto --step scan → /clear → /pan:focus-auto --step plan → /clear → /pan:focus-auto --step exec
 ```
 
 **Resume after a break:**
@@ -322,7 +360,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Complete a milestone:**
 ```
-/pan:milestone-audit → /pan:milestone-gaps → ... fix gaps ... → /pan:milestone-done 1.0.0
+/pan:milestone-audit → /pan:milestone-audit --gaps → ... fix gaps ... → /pan:milestone-done 1.0.0
 ```
 
 **Debug an issue (survives /clear):**
@@ -340,7 +378,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:discuss-phase <N>`** — Capture your vision for a phase before planning. Creates context.md.
 
-**`/pan:research-phase <N>`** — Deep ecosystem research for specialized domains (3D, ML, audio, etc.). Creates research.md.
+**`/pan:plan-phase --research-only <N>`** — Deep ecosystem research for specialized domains (3D, ML, audio, etc.). Creates research.md.
 
 **`/pan:assumptions <N>`** — See Claude's intended approach before it starts. Conversational only, no files created.
 
@@ -362,9 +400,9 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:milestone-audit`** — Reads verification.md files, checks requirements coverage, spawns integration checker. Creates milestone-audit.md.
 
-**`/pan:milestone-gaps`** — Reads audit, groups gaps into phases, adds to roadmap.md.
+**`/pan:milestone-audit --gaps`** — Reads audit, groups gaps into phases, adds to roadmap.md.
 
-**`/pan:milestone-cleanup`** — Moves completed phase directories to `milestones/v{X.Y}-phases/`.
+**`/pan:milestone-done --cleanup`** — Moves completed phase directories to `milestones/v{X.Y}-phases/`.
 
 **`/pan:retro`** — Milestone retrospective. Analyzes estimation accuracy, verification patterns, and common gap types. Run after `/pan:milestone-done` to reflect before the next milestone.
 
@@ -390,7 +428,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:settings`** — Toggle researcher, plan checker, verifier agents. Select model profile.
 
-**`/pan:profile <name>`** — Quick profile switch: `quality` and `balanced` (reasoning tier for every agent; `balanced` is the default), `budget` (mid tier for writing, fast tier for research/verification).
+**`/pan:settings --profile <name>`** — Quick profile switch: `quality` and `balanced` (reasoning tier for every agent; `balanced` is the default), `budget` (mid tier for writing, fast tier for research/verification).
 
 **Planning config** (`.planning/config.json`):
 - `commit_docs: true` — commit planning artifacts to git (set `false` + add `.planning/` to `.gitignore` for private planning)
@@ -437,5 +475,4 @@ Run `/pan:update` for version comparison and changelog preview before updating.
 - `/pan:progress` — see where you're at
 - `.planning/state.md` — current project context
 - `.planning/roadmap.md` — phase status
-- `/pan:discord` — community support
 </reference>

package/pan-wizard-core/workflows/insert-phase.md

@@ -64,13 +64,11 @@ Extract from result: `phase_number`, `after_phase`, `name`, `slug`, `directory`.
 <step name="update_project_state">
 Update state.md to reflect the inserted phase:
 
-1. Read `.planning/state.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
-   ```
+Append the entry under "## Accumulated Context" → "### Roadmap Evolution" (the engine creates the section when it is missing):
 
-If "Roadmap Evolution" section doesn't exist, create it.
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state section "Roadmap Evolution" --append "- Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)"
+```
 </step>
 
 <step name="completion">