pan-wizard 3.36.0 → 3.37.0

package/commands/pan/autodev.md

@@ -0,0 +1,76 @@
+---
+name: pan:autodev
+group: Phase Lifecycle
+description: 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
+argument-hint: "[run | resume | status | report | replay] [--host claude|codex|gemini|opencode] [--max-usd N] [--max-usd-day N] [--max-turns N] [--worktrees] [--quality] [--ci [local] [--ci-rounds N] [--ci-push] [--ci-base B]] [--run <id>]"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<objective>
+Drive the project's roadmap with no model in the control loop. `pan-tools autodev` is a foreground Node process: each turn it reads `.planning/` from disk, asks the next-action router for the next unit (plan, execute or verify a phase, or complete a verified one), and runs it. Plan, execute and verify units each get a fresh headless session on the host; `phase complete` runs in the engine, so the phase gate decides.
+
+It stops in code, with one of these reasons:
+
+| Stop | Meaning |
+|------|---------|
+| `done` | Every phase is finished; the milestone audit is next |
+| `human_needed` | A verifier asked for a human check, or there is no roadmap |
+| `gate_failed` | The phase gate refused to complete a phase |
+| `ci_failed` | With `--ci`: the pull request checks (or, with `--ci local`, the project's own gate) still failed after the fix rounds |
+| `forecast_exceeded` | An execute unit cost more than the project's p90 forecast for it |
+| `budget_usd` | Spend reached `--max-usd` (the run) or `--max-usd-day` (today, across runs) |
+| `turns` | `--max-turns` units have run (20 when not given) |
+| `no_progress` | A unit ran and changed nothing on disk |
+
+Two options change how units run:
+
+- `--worktrees`: a phase with two or more plans runs each plan in its own git worktree and session (`/pan:exec-phase N --plan <id>`). Plans of a wave that share a file run one after the other. Before a group of plans is merged back, `pan-tools worktree preflight` merges them onto HEAD in a throwaway worktree and runs the tests: branches that pass alone but break together, or conflict, stop the run for a human.
+- `--ci`: after each completed phase, the pull request's checks (GitHub's `gh` CLI) are the oracle. A check that already fails on the base branch is ignored. A failure starts a fix round, a fresh session given the failing checks and log; after `--ci-rounds` rounds (3) the run stops with `ci_failed`. The checks must be for HEAD: push the branch yourself, or pass `--ci-push` to have autodev push after each phase.
+- `--ci local`: the same rounds with no pull request: the oracle is the project's own gate, run here after each completed phase — `npm run ci:local` when `package.json` has that script, else `npm test`. Its exit code decides, and its output is the fix round's feedback.
+
+A failed session is classified before anything else happens: a compile or assertion failure is retried with its error in the prompt, then once more at a higher tier; a timeout or an unknown failure is restarted once; a missing CLI or login, a merge conflict, the guard's deny or an undeclared file stops for a human.
+</objective>
+
+<process>
+1. **Check the subcommand** in `$ARGUMENTS`: `run` (the default), `resume`, `status`, `report` or `replay`.
+
+2. **Status** only reports the latest run (or `--run <id>`):
+
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs autodev status
+   ```
+
+3. **Run or resume.** Say what will happen first: which host runs the sessions (`--host`, Claude Code by default; Copilot CLI has no unattended adapter yet), and the spend and unit caps. Each session spends on that host, so a run needs a spend cap: `--max-usd`, or `budget.max_usd_run` in `.planning/config.json` (and optionally a day cap, `--max-usd-day` or `budget.max_usd_day`). Ask the user for the cap if neither is set; it is their approval. Then run it in the foreground and wait; a run can take hours:
+
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs autodev run --host claude --max-usd 20 --max-turns 12
+   ```
+
+   Add `--worktrees` or `--ci` only when the user asked for them; `--ci-push` pushes the branch, so name that before running it.
+
+   After an interrupted run, resume it: the unit that was in flight runs again first.
+
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs autodev resume
+   ```
+
+4. **Write the dossier** and check the record:
+
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs autodev report
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs autodev replay
+   ```
+
+   `report` writes `dossier.md` (a PR body) and `dossier.html` beside the ledger: per phase, the requirements, plans, units and commits, test gate, verdict, findings and cost. `replay` re-runs the stop logic over the recorded decisions and says whether it decides the same; `identical: false` means the record and the code disagree, so say so.
+
+5. **Report** the result: `stop.reason` and `stop.detail`, the units run, `spent_usd`, and the ledger path (`.planning/autodev/<run>/ledger.jsonl`, one `started` and one `finished` row per unit with its argv, exit, cost and commits). Then route on the reason:
+   - `done` → `/pan:milestone-audit`
+   - `human_needed` → show the phase's verification and the human checks it lists
+   - `ci_failed` → show the failing checks and the last fix round from the ledger
+   - `gate_failed` → show the gate's reasons (`pan-tools phase gate <N>`), then `/pan:plan-phase <N> --gaps`
+   - `budget_usd`, `turns` → offer `autodev resume` with a higher cap
+   - `forecast_exceeded` → show the unit's cost and forecast from the ledger; offer `autodev resume` once the user has looked
+   - `no_progress` → show the last unit's `stderr_tail` from the ledger; the session likely could not run the command
+</process>

package/commands/pan/exec-phase.md

@@ -2,7 +2,7 @@
 name: pan:exec-phase
 group: Phase Lifecycle
 description: Execute all plans in a phase with wave-based parallelization
-argument-hint: "<phase-number> [--gaps-only] [--skip-tests] [--skip-review] [--fast] [--deep-review] [--hierarchical] [--auto]"
+argument-hint: "<phase-number> [--plan <id>] [--gaps-only] [--skip-tests] [--skip-review] [--fast] [--deep-review] [--hierarchical] [--auto] [--quality]"
 allowed-tools:
   - Read
   - Write
@@ -89,9 +89,8 @@ Execute the execute-phase workflow from @~/.claude/pan-wizard-core/workflows/exe
 Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
 
 **Context Management Across Waves:**
-- KEEP: Phase goals, test baseline, current wave tasks, file paths being modified
-- SUMMARIZE: Completed wave results to one-line summaries
-- DISCARD: Raw tool output from previous waves
+- Carry forward: Phase goals, test baseline, current wave tasks, file paths being modified
+- Summarise: Completed wave results to one-line summaries
 
 **Attention Anchor — emit after each wave completes:**
 ```

package/commands/pan/focus-auto.md

@@ -2,7 +2,7 @@
 name: focus-auto
 group: Focus
 description: Continuous scan-plan-exec loop with purpose-driven categories and a layered safety harness
-argument-hint: "[--source scan|backlog] [--category CAT] [--mode MODE] [--budget N] [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F] [--continue] [--stop] [--status] [--dry-run] [--deep-review] [--parallel-research] [--parallel-verify] [--clean-seal]"
+argument-hint: "[--source scan|backlog] [--category CAT] [--mode MODE] [--budget N] [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F] [--continue] [--stop] [--status] [--dry-run] [--deep-review] [--parallel-research] [--parallel-verify] [--clean-seal] [--step scan|plan|exec|drift]"
 allowed-tools:
   - Read
   - Write
@@ -12,6 +12,14 @@ allowed-tools:
   - Glob
   - Agent
 ---
+<routes>
+These flags select another mode of this command. Each was a separate command, and its old name still runs this one as an alias. When one is present, follow the named workflow instead of the steps below, with the rest of the arguments as its `$ARGUMENTS`, and stop when it ends.
+
+- `--step scan` — one deep scan for prioritised work items, no loop: @~/.claude/pan-wizard-core/workflows/focus-scan.md (formerly `focus-scan`)
+- `--step plan` — one capacity-budgeted work batch from the scan: @~/.claude/pan-wizard-core/workflows/focus-plan.md (formerly `focus-plan`)
+- `--step exec` — execute the planned batch once: @~/.claude/pan-wizard-core/workflows/focus-exec.md (formerly `focus-exec`)
+- `--step drift` — documentation-code drift detection and repair: @~/.claude/pan-wizard-core/workflows/focus-drift-walking.md (formerly `focus-drift-walking`)
+</routes>
 
 # /pan:focus-auto — Continuous Autonomous Improvement Campaigns
 
@@ -197,7 +205,7 @@ HARD STOP conditions:
 
 **For each cycle (1 to max_cycles), execute Steps 2.1 through 2.5 without stopping:**
 
-#### Step 2.1: Scan (INLINE — do NOT invoke /pan:focus-scan)
+#### Step 2.1: Scan (INLINE — do NOT invoke /pan:focus-auto --step scan)
 
 Perform a deep codebase scan to find actionable work items with evidence.
 
@@ -254,7 +262,7 @@ Write scan results to `.planning/focus/scan-<YYYY-MM-DD>-<category>.md` with:
 - Items grouped by priority tier, each with: ID, title, symptom, root cause, fix guidance, file paths, effort size
 - Summary: item count by priority, total points
 
-#### Step 2.2: Plan (INLINE — do NOT invoke /pan:focus-plan)
+#### Step 2.2: Plan (INLINE — do NOT invoke /pan:focus-auto --step plan)
 
 Create a capacity-budgeted batch from the scan items found in Step 2.1.
 
@@ -277,7 +285,7 @@ Write batch to `.planning/focus/batch-<YYYY-MM-DD>-<category>.json`:
   "deferred": [{ "id": "...", "title": "...", "reason": "..." }] }
 ```
 
-#### Step 2.3: Execute (INLINE — do NOT invoke /pan:focus-exec)
+#### Step 2.3: Execute (INLINE — do NOT invoke /pan:focus-auto --step exec)
 
 Implement each item from the batch created in Step 2.2. Record `tests_before` by running the test suite first.
 
@@ -364,9 +372,8 @@ Check the response for stop conditions:
 #### Step 2.5: Inter-Cycle Context Management
 
 Between cycles, manage context to prevent quality degradation over long campaigns:
-- **KEEP:** Current cycle goals, test baseline, error states, active file paths
-- **SUMMARIZE:** Previous cycle results to a one-line summary each
-- **DISCARD:** Raw tool output from previous cycles, superseded scan results
+- **Carry forward:** Current cycle goals, test baseline, error states, active file paths
+- **Summarise:** Previous cycle results to a one-line summary each
 
 Display one-line cycle summary: `Cycle N/M | X/Y pts | Z items done | Tests: A -> B`
 

package/commands/pan/focus-design.md

@@ -27,7 +27,7 @@ Research, design, and specify a new feature with strategic analysis. $ARGUMENTS
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command investigates and designs features for the **host project** — NOT for PAN Wizard itself.
 
@@ -57,9 +57,8 @@ Prefer local evidence over web research. Start with the codebase, then broaden.
 ## Context Management Across Phases
 
 This pipeline spans 10+ phases. Manage context to maintain quality:
-- **KEEP:** Problem statement, success criteria, key architectural decisions, file paths being designed for
-- **SUMMARIZE:** Research findings (compress to key takeaways after each research phase), competitive analysis results
-- **DISCARD:** Raw web fetch content after extracting relevant data, superseded design drafts
+- **Carry forward:** Problem statement, success criteria, key architectural decisions, file paths being designed for
+- **Summarise:** Research findings (compress to key takeaways after each research phase), competitive analysis results
 - After Phase 3 (Strategic Analysis), summarize all findings from Phases 0-3 into a compact brief before entering design phases
 
 **Progressive context loading — load only what the current phase needs:**
@@ -1050,7 +1049,7 @@ Write ADR to: `docs/decisions/ADR-NNNN-<feature_name>.md`
 
 **ADR completeness gate:** Before saving, verify the ADR passes ALL checks from Phase 5.2. The ADR file must contain every section defined in Phase 5.1 with substantive content — no placeholder brackets, no skeleton sections, no missing tables. If any section would be empty, go back to the relevant phase and extract the content.
 
-**Independent verification gate:** The final artifact must have PASSED `pan-design-checker` in Phase 5.4 (or reached the 2-iteration cap with remaining gaps recorded as caveats). Re-run the checker here on the *saved* spec + ADR as a final gate — the independent pass, not just the 5.2 self-check, is what authorizes handing this design to `/pan:focus-plan`.
+**Independent verification gate:** The final artifact must have PASSED `pan-design-checker` in Phase 5.4 (or reached the 2-iteration cap with remaining gaps recorded as caveats). Re-run the checker here on the *saved* spec + ADR as a final gate — the independent pass, not just the 5.2 self-check, is what authorizes handing this design to `/pan:focus-auto --step plan`.
 
 **Minimum ADR size:** A proper ADR for a `--full` mode investigation should be 80-200+ lines. If the ADR is under 60 lines, it is almost certainly missing required sections. For `--internal` mode, minimum 60 lines. For `--outward` mode, minimum 70 lines.
 

package/commands/pan/focus-docs.md

@@ -0,0 +1,24 @@
+---
+name: focus-docs
+group: Focus
+description: Documentation audit and sync — accuracy, freshness, links, cross-consistency and structure; --sync updates stale docs after changes
+argument-hint: "[file|directory] [--deep] [--links] [--fix] [--all] [--score-only] [--min-score N] [--format markdown|json|checklist] | --sync [--readme | --docs | --arch | --all]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - WebFetch
+---
+
+# /pan:focus-docs — Documentation audit and sync
+
+One command for a project's documentation. $ARGUMENTS
+
+- **Default: audit.** Score documents for accuracy, freshness, links, cross-consistency and structure, and fix what `--fix` allows: follow @~/.claude/pan-wizard-core/workflows/focus-doc-audit.md.
+- **`--sync`: synchronise after changes.** Check staleness and update counts and references in README, docs and architecture: follow @~/.claude/pan-wizard-core/workflows/focus-sync.md with the rest of the arguments.
+
+The old `focus-doc-audit` and `focus-sync` names run this command as aliases.

package/commands/pan/learn.md

@@ -2,14 +2,21 @@
 name: pan:learn
 group: Self-Improvement
 description: Analyze trace sessions or harvested experiments via pan-optimizer; generate ranked optimization reports
-argument-hint: "[--session <id> | --sessions <n> | --experiment <slug>] [--apply]"
+argument-hint: "[--session <id> | --sessions <n> | --experiment <slug>] [--apply] | --optimize <subcommand>"
 allowed-tools:
   - Read
   - Bash
   - Glob
   - Grep
   - Task
+  - Write
+  - Edit
 ---
+<routes>
+These flags select another mode of this command. Each was a separate command, and its old name still runs this one as an alias. When one is present, follow the named workflow instead of the steps below, with the rest of the arguments as its `$ARGUMENTS`, and stop when it ends.
+
+- `--optimize <apply|revert|list|stats|trace …>` — manage the optimisation loop: record a report's suggestions, undo them, list reports, view stats, manage trace sessions: @~/.claude/pan-wizard-core/workflows/optimize.md (formerly `optimize`)
+</routes>
 
 # /pan:learn
 
@@ -28,7 +35,7 @@ Analyze the most recent trace session and generate an optimization report.
 - `--session <id>` — analyze a specific session instead of the most recent
 - `--sessions <n>` — pool the last n sessions into one analysis, so recommendations rest on failures that recur across runs
 - `--experiment <slug>` *(v3.7.0+, W3)* — analyze a harvested experiment instead of the current project's traces: the workflow runs its `pan-tools` steps with `--cwd` set to the harvest folder (the `harvest_path` `/pan:experiment harvest <slug>` printed, `<source-repo>/experiments/<slug>/` by default), so the analysis and the optimizer's report land in that folder's `.planning/optimization/reports/`. Used by the self-improvement loop. Run `/pan:experiment harvest <slug>` first.
-- `--apply` — record the report's suggestions right after generating it (equivalent to running `/pan:optimize apply` immediately after)
+- `--apply` — record the report's suggestions right after generating it (equivalent to running `/pan:learn --optimize apply` immediately after)
 
 **What it does:**
 
@@ -36,11 +43,11 @@ Analyze the most recent trace session and generate an optimization report.
 2. Performs local analysis (error/gap/redundancy patterns, agent stats)
 3. Writes `.planning/optimization/reports/{session}-analysis.json`
 4. Invokes `pan-optimizer` agent to produce `.planning/optimization/reports/{session}-opt-report.md`
-5. If `--apply` flag: immediately runs `/pan:optimize apply` on the new report
+5. If `--apply` flag: immediately runs `/pan:learn --optimize apply` on the new report
 6. Prints the optimization summary
 
 **When to run:**
-- After any `/pan:exec-phase` or `/pan:focus-exec` that had a trace session active
+- After any `/pan:exec-phase` or `/pan:focus-auto --step exec` that had a trace session active
 - After a full build cycle to capture all decisions and errors
 - On demand to understand what PAN did and how to make it smarter
 
@@ -59,7 +66,7 @@ The optimization report in `.planning/optimization/reports/` contains:
 - Redundancy analysis with token waste estimates
 - Prompt improvement suggestions (require human review before applying)
 - Workflow gap suggestions (require human review)
-- An `## Auto-Apply Actions` JSON block, which `/pan:optimize apply` records in `.planning/optimization/suggestions.md`
+- An `## Auto-Apply Actions` JSON block, which `/pan:learn --optimize apply` records in `.planning/optimization/suggestions.md`
 - A circular optimization score (0–100)
 
 Nothing in the report reaches an agent until a person writes it where the agents read. PAN's workflows do not load `.planning/memory/` into agents.
@@ -75,6 +82,6 @@ Nothing in the report reaches an agent until a person writes it where the agents
 → Needs review: 2 prompt improvements, 1 workflow gap
 ```
 
-**See also:** `/pan:optimize`, `/pan:exec-phase`, `/pan:experiment` (v3.7.0+ self-improvement loop)
+**See also:** `/pan:learn --optimize`, `/pan:exec-phase`, `/pan:experiment` (v3.7.0+ self-improvement loop)
 
 Follow the workflow at `~/.claude/pan-wizard-core/workflows/learn.md`.

package/commands/pan/milestone-audit.md

@@ -2,7 +2,7 @@
 name: pan:milestone-audit
 group: Milestone
 description: Audit milestone completion against original intent before archiving
-argument-hint: "[version] [--track <name>] [--all-tracks]"
+argument-hint: "[version] [--track <name>] [--all-tracks] [--gaps]"
 allowed-tools:
   - Read
   - Glob
@@ -10,7 +10,14 @@ allowed-tools:
   - Bash
   - Task
   - Write
+  - AskUserQuestion
 ---
+<routes>
+These flags select another mode of this command. Each was a separate command, and its old name still runs this one as an alias. When one is present, follow the named workflow instead of the steps below, with the rest of the arguments as its `$ARGUMENTS`, and stop when it ends.
+
+- `--gaps` — create the phases that close the gaps of the most recent audit (`.planning/v*-milestone-audit.md`), grouped, with your confirmation: @~/.claude/pan-wizard-core/workflows/milestone-gaps.md (formerly `milestone-gaps`)
+</routes>
+
 <objective>
 Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
 

package/commands/pan/milestone-done.md

@@ -3,12 +3,17 @@ type: prompt
 name: pan:milestone-done
 group: Milestone
 description: Archive completed milestone and prepare for next version
-argument-hint: <version>
+argument-hint: "<version> [--cleanup]"
 allowed-tools:
   - Read
   - Write
   - Bash
 ---
+<routes>
+These flags select another mode of this command. Each was a separate command, and its old name still runs this one as an alias. When one is present, follow the named workflow instead of the steps below, with the rest of the arguments as its `$ARGUMENTS`, and stop when it ends.
+
+- `--cleanup` — archive the phase directories of completed milestones into `.planning/milestones/v{X.Y}-phases/`, with a dry-run summary first: @~/.claude/pan-wizard-core/workflows/milestone-cleanup.md (formerly `milestone-cleanup`)
+</routes>
 
 <objective>
 Mark milestone {{version}} complete, archive to milestones/, and update roadmap.md and requirements.md.
@@ -45,8 +50,8 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
    - Look for `.planning/v{{version}}-milestone-audit.md`
    - If missing or stale: recommend `/pan:milestone-audit` first
-   - If audit status is `gaps_found`: recommend `/pan:milestone-gaps` first
-   - If audit status is `tech_debt`: present the debt; proceed on the user's say-so (it becomes accepted debt), or recommend `/pan:milestone-gaps` for a cleanup phase
+   - If audit status is `gaps_found`: recommend `/pan:milestone-audit --gaps` first
+   - If audit status is `tech_debt`: present the debt; proceed on the user's say-so (it becomes accepted debt), or recommend `/pan:milestone-audit --gaps` for a cleanup phase
    - If audit status is `passed`: proceed to step 1
 
    ```markdown
@@ -57,7 +62,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
    requirements coverage, cross-phase integration, and E2E flows.
 
    {If audit has gaps:}
-   ⚠ Milestone audit found gaps. Run `/pan:milestone-gaps` to create
+   ⚠ Milestone audit found gaps. Run `/pan:milestone-audit --gaps` to create
    phases that close the gaps, or proceed anyway to accept as tech debt.
 
    {If audit passed:}
@@ -122,7 +127,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
    node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn --sessions 5 2>/dev/null || true
    ```
 
-   Present the optimization summary to the user and suggest `/pan:optimize apply` to record its suggestions, each naming where a person should make the change.
+   Present the optimization summary to the user and suggest `/pan:learn --optimize apply` to record its suggestions, each naming where a person should make the change.
 
 </process>
 

package/commands/pan/milestone-new.md

@@ -11,13 +11,13 @@ allowed-tools:
   - AskUserQuestion
 ---
 <objective>
-Start a new milestone: questioning → research (optional) → requirements → roadmap.
+Start a new milestone: questioning → research (opt-in, at most 5 open questions) → requirements → roadmap.
 
 Brownfield equivalent of new-project. Project exists, project.md has history. Gathers "what's next", updates project.md, then runs requirements → roadmap cycle.
 
 **Creates/Updates:**
 - `.planning/project.md` — updated with new milestone goals
-- `.planning/research/` — domain research (optional, NEW features only)
+- `.planning/research/` — answers to at most 5 open questions (only with research, NEW features only)
 - `.planning/requirements.md` — scoped requirements for this milestone
 - `.planning/roadmap.md` — phase structure (continues numbering)
 - `.planning/state.md` — reset for new milestone

package/commands/pan/new-project.md

@@ -2,7 +2,7 @@
 name: pan:new-project
 group: Getting Started
 description: Initialize a new project with deep context gathering and project.md
-argument-hint: "[--auto]"
+argument-hint: "[--auto] [--research [market]]"
 allowed-tools:
   - Read
   - Bash
@@ -12,16 +12,18 @@ allowed-tools:
 ---
 <context>
 **Flags:**
-- `--auto` — Automatic mode. Asks no questions: applies the auto-mode defaults (idea.md frontmatter can override them), then runs research → requirements → roadmap without interaction. Needs an idea document — an @ reference, or the idea pasted after the flag.
+- `--auto` — Automatic mode. Asks no questions: applies the auto-mode defaults (idea.md frontmatter can override them), then runs requirements → roadmap without interaction (research only when asked for). Needs an idea document — an @ reference, or the idea pasted after the flag.
+- `--research` — Research is off by default. With this flag the workflow lists at most 5 open questions that block building and one researcher answers them, each with a source or a recorded assumption; findings settle decisions and never add v1 scope. A precise brief skips research anyway.
+- `--research market` — Research, plus a comparison of at most 5 comparable products; what the brief does not cover becomes v2 candidates for you to accept.
 </context>
 
 <objective>
-Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
+Initialize a new project through unified flow: questioning → research (opt-in) → requirements → roadmap.
 
 **Creates:**
 - `.planning/project.md` — project context
 - `.planning/config.json` — workflow preferences
-- `.planning/research/` — domain research (optional)
+- `.planning/research/` — answers to at most 5 open questions (only with research)
 - `.planning/requirements.md` — scoped requirements
 - `.planning/roadmap.md` — phase structure
 - `.planning/state.md` — project memory
@@ -50,7 +52,7 @@ Load context in layers — do NOT read everything upfront. Each layer builds on
 - Entry points — main files, index files, server files
 - Test infrastructure — test framework, test directory
 
-**Layer 3: Hotspots (load during research, if research is enabled)**
+**Layer 3: Hotspots (brownfield only, when writing requirements)**
 - Most-changed files (git log --name-only) — where active work happens
 - Largest files — complexity centers
 - Import graph roots — most-depended-on modules
@@ -74,8 +76,8 @@ IF .planning/ already exists AND contains project.md:
 ELSE IF --auto flag AND an idea document provided (@ reference or pasted text):
   → ASK nothing: apply the auto-mode defaults (workflow step 2a; idea.md frontmatter can override them)
   → SKIP interactive questioning (use the document as project context)
-  → RUN research automatically
-  → GENERATE requirements from research + the document
+  → RESEARCH only with --research or frontmatter research_enabled: true (never for a precise brief)
+  → GENERATE requirements from the document (research settles decisions, never adds v1 scope)
   → GENERATE roadmap from requirements
   → No further interaction until complete
 
@@ -85,9 +87,9 @@ ELSE IF --auto flag WITHOUT an idea document:
 
 ELSE (interactive mode — default):
   → RUN questioning flow (freeform deep questioning — references/questioning.md)
-  → ASK: "Should I research the domain ecosystem?" (Y/N)
-    → IF Y: spawn researchers → synthesize → continue
-    → IF N: skip research → continue
+  → IF --research: research; ELSE ASK: "Research open questions?" (default: Skip research)
+    → IF research: write ≤5 blocking questions → one pan-project-researcher → research check → continue
+    → IF skip (or no question blocks building): continue
   → PRESENT requirements for approval
   → PRESENT roadmap for approval
   → COMMIT if commit_docs=true
@@ -95,8 +97,9 @@ ELSE (interactive mode — default):
 
 **Research routing:**
 ```
-IF user says research: spawn pan-project-researcher agents
-IF user declines research: skip directly to requirements generation
+IF user asks for research: write at most 5 open questions, spawn ONE pan-project-researcher
+IF user declines research (the default): skip directly to requirements generation
+IF no question blocks building: no research, say so
 IF codebase already has substantial code: suggest skipping research (existing code IS the context)
 ```
 </routing_decision_tree>

package/commands/pan/plan-phase.md

@@ -2,7 +2,7 @@
 name: pan:plan-phase
 group: Phase Lifecycle
 description: Create detailed phase plan (plan.md) with verification loop
-argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>]"
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>] [--research-only] [--quality]"
 agent: pan-planner
 allowed-tools:
   - Read
@@ -14,14 +14,20 @@ allowed-tools:
   - WebFetch
   - mcp__context7__*
 ---
+<routes>
+These flags select another mode of this command. Each was a separate command, and its old name still runs this one as an alias. When one is present, follow the named workflow instead of the steps below, with the rest of the arguments as its `$ARGUMENTS`, and stop when it ends.
+
+- `--research-only <phase>` — research the phase without planning it (or re-research a planned one): @~/.claude/pan-wizard-core/workflows/research-phase.md, with the phase as its argument (formerly `research-phase`)
+</routes>
+
 <objective>
-Create executable phase prompts (plan.md files) for a roadmap phase with integrated research and verification.
+Create executable phase prompts (plan.md files) for a roadmap phase with verification, and research only when asked for.
 
-**Default flow:** Research (if needed) → Plan → Verify → Done
+**Default flow:** Plan → Verify → Done. Research is opt-in (`--research`, or `workflow.research: true`): it answers at most 5 open questions that block building, with one researcher, and never adds scope
 
 **Design input (ADR-0042):** if `{phase}-design.md` exists (from `/pan:design-phase`, verified by `pan-design-checker`), it is an authoritative upstream input — `pan-planner` implements its approved architecture/decisions and `pan-plan-checker` verifies conformance (Design Conformance dimension). It is optional: a phase without a design.md plans exactly as before. The plan-phase workflow does not list it in the planner's or checker's `<files_to_read>`, so they use it only when they find it in the phase directory themselves.
 
-**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn pan-planner, verify with pan-plan-checker, iterate until pass or max iterations, present results.
+**Orchestrator role:** Parse arguments, validate phase, answer open questions (only when research was asked for), spawn pan-planner, verify with pan-plan-checker, iterate until pass or max iterations, present results.
 </objective>
 
 <execution_context>
@@ -33,7 +39,7 @@ Create executable phase prompts (plan.md files) for a roadmap phase with integra
 Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
 
 **Flags:**
-- `--research` — Force re-research even if research.md exists
+- `--research` — Research this phase (off by default): write at most 5 blocking questions, one researcher answers them, `pan-tools research check` verifies; re-researches even if research.md exists
 - `--skip-research` — Skip research, go straight to planning
 - `--gaps` — Gap closure mode (reads verification.md, skips research)
 - `--skip-verify` — Skip verification loop
@@ -49,16 +55,16 @@ During the plan-checker verification iteration:
 2. For each identified gap: verify it is a genuine gap by re-reading the relevant requirement
 3. Do not blindly accept all critiques — some may be false positives from missing context
 4. Revise the plan to address genuine gaps only
-5. At most 2 revisions: the workflow checks up to three times (plan → check → revise → check → revise → check); after the third check the user chooses force proceed, guidance or abandon
+5. Bounded revisions: by default (sized ceremony) the workflow checks twice (plan → check → revise → check), and under the full ceremony (`quality`, `workflow.ceremony: full`, `--quality`) three times; after the last check the user chooses force proceed, guidance or abandon. A lean phase is planned and checked by the engine, with no planner or checker
 This prevents over-revision while ensuring real gaps are closed.
 </reflexion_loop>
 
 <completion_contract>
 Planning is complete when ALL conditions are met:
 1. At least one plan.md file created in the phase directory
-2. Plan-checker passed (or max 2 revision iterations exhausted with final approval)
+2. Plan-checker passed (or the revision limit reached, one by default and two under the full ceremony, with final approval), or the engine's plan check recorded for a lean phase
 3. Each plan contains: objective, task breakdown with estimates, dependency ordering, and key file links
-4. Research.md exists, unless research was skipped (`--skip-research`, `--gaps`, `workflow.research: false`, or the single-plan lightweight-phase bypass)
+4. Research.md exists only when research was asked for (`--research` or `workflow.research: true`) and a question blocked building
 5. User presented with results and next-step options
 
 Planning FAILS if: phase not found in roadmap, or planner agent returns empty/malformed output after retries.
@@ -123,7 +129,7 @@ ELSE:
   → IF checker PASSES: done
   → IF checker finds gaps (check 1 or 2): revise plan, re-check
   → IF checker finds gaps (check 3): stop revising; the user chooses force proceed (open issues recorded as deferred), guidance and retry, or abandon
-  → Max 2 revisions, so at most 3 checks
+  → One revision by default (two checks), two under the full ceremony (three checks)
 ```
 </routing_decision_tree>
 

package/commands/pan/quick.md

@@ -2,7 +2,7 @@
 name: pan:quick
 group: Session & Progress
 description: Execute a quick task with PAN guarantees (atomic commits, state tracking) but skip optional agents
-argument-hint: "[--full] [description]"
+argument-hint: "[--full] [--quality] [description]"
 allowed-tools:
   - Read
   - Write

package/commands/pan/review-deep.md

@@ -18,7 +18,7 @@ Run a deeper review pass on a phase than `pan-reviewer` alone provides. Two new
 1. **pan-hardener** — OWASP Top 10 (2025) + STRIDE threat model on files changed in the phase.
 2. **pan-meta-reviewer** — reads both the reviewer's and hardener's output, flags things both missed, disputes overstated severities.
 
-Outputs are merged by `review-deep.cjs` into a single `.planning/reviews/<phase>/deep-review.md` with verdict, coverage stats, and conflict table. An audit entry is published to the `review-handoff` bus channel for traceability.
+Outputs are merged by `review-deep.cjs` into a single `.planning/reviews/<phase>/deep-review.md` with verdict, coverage stats, and conflict table.
 
 Consolidates Spec B v1's X-4 (self-review) + X-12 (harden) into a single command.
 </objective>
@@ -49,7 +49,7 @@ Runs the normal exec → reviewer pipeline, then runs this command's process inl
 ### Integrated with focus-exec
 
 ```
-/pan:focus-exec --deep-review
+/pan:focus-auto --step exec --deep-review
 ```
 
 Per-item deep review during focus campaigns: focus-exec runs the hardener and meta-reviewer on the item's changed files and merges them under the item's id (`review-deep merge <item-id>` with no `--reviewer-file`), since an item has no phase or first-pass review. Useful for high-stakes batches.
@@ -68,14 +68,21 @@ Per-item deep review during focus campaigns: focus-exec runs the hardener and me
    - Prompt includes: `<files_to_read>` with both `{directory}/{phase_number}-review.md` AND `.planning/reviews/<N>/hardener.md` (and representative diff snippets); `<output_path>` = `.planning/reviews/<N>/meta.md`.
    - Agent reads both first-pass reports, identifies missed patterns, disputes overstated severities, writes to output path.
 
+3b. **Cross-family lane (only when the project turned it on).** A reviewer from the author's own model family shares its blind spots. Run:
+   ```
+   pan-tools review cross-family <N>
+   ```
+   With `workflow.cross_family_review: off` (the default) it returns `enabled: false` and runs nothing: skip to the merge. With a host set, it runs the review on that host's CLI, read-only, and writes `.planning/reviews/<N>/cross-family-<host>.md`; pass that file to the merge as `--cross-file`. If the host's CLI is missing or fails, say so and merge without it.
+
 4. **Merge** — call:
    ```
    pan-tools review-deep merge <N> \
      --reviewer-file {directory}/{phase_number}-review.md \
      --hardener-file .planning/reviews/<N>/hardener.md \
-     --meta-file .planning/reviews/<N>/meta.md
+     --meta-file .planning/reviews/<N>/meta.md \
+     [--cross-file .planning/reviews/<N>/cross-family-<host>.md]
    ```
-   The merger parses all three, sorts by severity, computes verdict (`ok` | `ok_with_minor` | `fix_before_merge` | `review_required` | `block`), writes `.planning/reviews/<N>/deep-review.md`, and publishes an audit record to the `review-handoff` bus channel.
+   The merger parses every input, sorts by severity, computes verdict (`ok` | `ok_with_minor` | `fix_before_merge` | `review_required` | `block`), and writes `.planning/reviews/<N>/deep-review.md`.
 
 5. **Report back** — echo verdict + finding count + conflict count. If verdict is `block` or `review_required`, recommend the user review `deep-review.md` before proceeding.
 
@@ -101,7 +108,6 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 - `.planning/reviews/<N>/hardener.md` — pan-hardener output (new)
 - `.planning/reviews/<N>/meta.md` — pan-meta-reviewer output (new)
 - `.planning/reviews/<N>/deep-review.md` — merged consolidated report (final deliverable)
-- `.planning/bus/review-handoff.jsonl` — audit trail entry (append-only)
 
 </output_files>
 

package/commands/pan/settings.md

@@ -2,12 +2,18 @@
 name: pan:settings
 group: System
 description: Configure PAN workflow toggles and model profile
+argument-hint: "[--profile <quality|balanced|budget>]"
 allowed-tools:
   - Read
   - Write
   - Bash
   - AskUserQuestion
 ---
+<routes>
+These flags select another mode of this command. Each was a separate command, and its old name still runs this one as an alias. When one is present, follow the named workflow instead of the steps below, with the rest of the arguments as its `$ARGUMENTS`, and stop when it ends.
+
+- `--profile <quality|balanced|budget>` — switch the model profile only: @~/.claude/pan-wizard-core/workflows/profile.md (formerly `profile`)
+</routes>
 
 <objective>
 Interactive configuration of PAN workflow agents and model profile via multi-question prompt.

package/commands/pan/verify-phase.md

@@ -1,8 +1,8 @@
 ---
 name: pan:verify-phase
 group: Phase Lifecycle
-description: Re-run goal-backward verification of a phase with a test-suite gate and list its gaps
-argument-hint: "[phase number, e.g., '4']"
+description: Re-run goal-backward verification of a phase with a test-suite gate and list its gaps, or walk its UAT with --uat
+argument-hint: "[phase number, e.g., '4'] [--uat]"
 allowed-tools:
   - Read
   - Bash
@@ -24,6 +24,10 @@ Output: {phase_num}-verification.md with a status (passed, gaps_found or human_n
 @~/.claude/pan-wizard-core/workflows/verify-phase.md
 </execution_context>
 
+<uat_mode>
+With `--uat` in $ARGUMENTS, run the user acceptance walkthrough instead of the goal-backward verification: @~/.claude/pan-wizard-core/workflows/uat-walkthrough.md. It works on every runtime, records each answer through `pan-tools uat record`, and ends by diagnosing any issues for `/pan:plan-phase N --gaps`.
+</uat_mode>
+
 <context>
 Phase: $ARGUMENTS (optional)
 - If provided: Test specific phase (e.g., "4")