pan-wizard 3.36.0 → 3.37.0

package/README.md

@@ -175,7 +175,7 @@ npx pan-wizard --all --global      # Install to all directories
 ```
 
 Use `--global` (`-g`) to install into your home config directory; `--local` (`-l`) is the default and may be omitted.
-Use `--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, or `--all` to skip the runtime prompt. A local install also writes outside the runtime directory: a marker-fenced PAN section in the project's `AGENTS.md`; for Claude Code, a marker-fenced block in `CLAUDE.md` (the `@AGENTS.md` import, and compact instructions that keep PAN's position through compaction) and a `pan` MCP server in `.mcp.json`; and for Codex or `--unified-skills`, the shared `.agents/` tree (skills, plus a shared core under `--unified-skills`). `--uninstall` removes them (the `AGENTS.md` and `CLAUDE.md` blocks and the `.agents/` tree stay while another PAN runtime in the project still uses them).
+Use `--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, or `--all` to skip the runtime prompt. A local install also writes outside the runtime directory: a marker-fenced PAN section in the project's `AGENTS.md`; for Claude Code, a marker-fenced block in `CLAUDE.md` (the `@AGENTS.md` import, and compact instructions that keep PAN's position through compaction) and a `pan` MCP server in `.mcp.json`; and for Codex or `--unified-skills`, the shared `.agents/` tree (skills, plus a shared core under `--unified-skills`). An update rewrites those blocks only while they hold PAN's own text: once your project edits one, PAN keeps your version and says so. `--uninstall` removes them (the `AGENTS.md` and `CLAUDE.md` blocks and the `.agents/` tree stay while another PAN runtime in the project still uses them).
 Add `--unified-skills` to install commands as one shared `.agents/skills/` tree instead of per-runtime formats. Codex, Gemini CLI, OpenCode, Copilot CLI and Antigravity CLI read that tree; Claude Code does not, so for Claude the installer also copies each skill into `.claude/skills/` and the commands become `/pan-<name>`. Gemini CLI gives skills no slash command, so on a unified Gemini install you ask for the task and `/skills list` shows what loaded. See the User Guide for details.
 
 > **Gemini CLI note:** from June 18, 2026, Google's Gemini CLI serves Gemini Code Assist (Standard/Enterprise) customers; individual free / AI Pro / Ultra accounts are directed to Antigravity CLI instead. PAN's `--gemini` target installs for Gemini CLI. Antigravity CLI is not yet a PAN install target, but it reads the shared `.agents/skills/` tree natively — install with `--unified-skills` and PAN's commands are usable from Antigravity in the same project.
@@ -296,13 +296,13 @@ If you prefer not to use that flag, add this to your project's `.claude/settings
 One command, one flow. The system:
 
 1. **Questions** — Asks until it understands your idea completely (goals, constraints, tech preferences, edge cases)
-2. **Research** — Spawns parallel agents to investigate the domain (optional but recommended)
+2. **Research** — Off by default. With `--research`, one agent answers the few open questions that block building, each with a source; `--research market` also compares a handful of comparable products
 3. **Requirements** — Extracts what's v1, v2, and out of scope
 4. **Roadmap** — Creates phases mapped to requirements
 
 You approve the roadmap. Now you're ready to build.
 
-**Creates:** `project.md`, `requirements.md`, `roadmap.md`, `state.md`, `.planning/research/`
+**Creates:** `project.md`, `requirements.md`, `roadmap.md`, `state.md`, and `.planning/research/` when research was asked for
 
 ---
 
@@ -325,7 +325,7 @@ The system analyzes the phase and identifies gray areas based on what's being bu
 
 For each area you select, it asks until you're satisfied. The output — `context.md` — feeds directly into the next two steps:
 
-1. **Researcher reads it** — Knows what patterns to investigate ("user wants card layout" → research card component libraries)
+1. **Researcher reads it** (when research is on) — Knows what patterns to investigate ("user wants card layout" → research card component libraries)
 2. **Planner reads it** — Knows what decisions are locked ("infinite scroll decided" → plan includes scroll handling)
 
 The deeper you go here, the more the system builds what you actually want. Skip it and you get reasonable defaults. Use it and you get *your* vision.
@@ -342,13 +342,13 @@ The deeper you go here, the more the system builds what you actually want. Skip
 
 The system:
 
-1. **Researches** — Investigates how to implement this phase, guided by your context.md decisions
+1. **Researches (opt-in)** — With `--research` or `workflow.research: true`, answers the open questions that block planning this phase, guided by your context.md decisions
 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
+3. **Verifies** — Checks plans against requirements: two checker passes (one revision) by default, three (two revisions) under the `quality` profile, `workflow.ceremony: full` or `--quality`; then the remaining issues come to you. A small phase whose requirements each say precisely what to build is planned and checked by the engine instead, with no planner or checker
 
 Each plan is small enough to execute in a fresh context window. No degradation, no "I'll be more concise now."
 
-**Creates:** `{phase_num}-research.md`, `{phase_num}-{N}-plan.md`, `{phase_num}-plan-check.md` (the checker's report, when the checker runs)
+**Creates:** `{phase_num}-{N}-plan.md`, `{phase_num}-plan-check.md` (the checker's report, when the checker runs), `{phase_num}-research.md` (only with `--research` or `workflow.research: true`)
 
 ---
 
@@ -423,7 +423,7 @@ The system:
 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
 
-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.
+Manual acceptance testing stays yours, and `/pan:verify-phase 1 --uat` walks you through it on every runtime: one acceptance test at a time, each answer recorded through the engine into the phase's UAT file, and the issues you report diagnosed (one debugger per failed truth; on Claude Code the native `/pan-diagnose-issues <phase>` script does the same in parallel) for `/pan:plan-phase N --gaps`.
 
 **Creates:** `{phase_num}-verification.md`; fix plans follow from `/pan:plan-phase N --gaps`
 
@@ -443,11 +443,11 @@ On Claude Code, `/pan-diagnose-issues <phase>` spawns one debugger per failed UA
 
 Loop **discuss → plan → execute → verify** until milestone complete.
 
-Each phase gets your input (discuss), proper research (plan), clean execution (execute), and goal-backward verification (verify). Context stays fresh. Quality stays high.
+Each phase gets your input (discuss), a checked plan (plan; research only when you ask for it), clean execution (execute), and goal-backward verification (verify). Context stays fresh. Quality stays high.
 
 When all phases are done, `/pan:milestone-done` archives the milestone and tags the release.
 
-Then `/pan:milestone-new` starts the next version — same flow as `new-project` but for your existing codebase. You describe what you want to build next, the system researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
+Then `/pan:milestone-new` starts the next version — same flow as `new-project` but for your existing codebase. You describe what you want to build next, the system answers any open questions if you ask it to research, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
 
 ---
 
@@ -461,8 +461,8 @@ Then `/pan:milestone-new` starts the next version — same flow as `new-project`
 
 Quick mode gives you PAN guarantees (atomic commits, state tracking) with a faster path:
 
-- **Same agents** — Planner + executor, same quality
-- **Skips optional steps** — No research, no plan checker, no verifier
+- **Same agents** — Planner + executor, same quality; a task whose description already says precisely what to build gets its one-task plan from the engine, with no planner
+- **Skips optional steps** — No research, no plan checker, no verifier (`--full` adds the plan checker and the verifier)
 - **Separate tracking** — Lives in `.planning/quick/`, not phases
 
 Use for: bug fixes, small features, config changes, one-off tasks.
@@ -487,7 +487,7 @@ PAN handles it for you:
 | File | What it does |
 |------|--------------|
 | `project.md` | Project vision, read when PAN plans, researches or resumes work |
-| `research/` | Ecosystem knowledge (stack, features, architecture, pitfalls) |
+| `research/` | Answers to the open questions that blocked building (only with `--research`) |
 | `requirements.md` | Scoped v1/v2 requirements with phase traceability |
 | `roadmap.md` | Where you're going, what's done |
 | `state.md` | Decisions, blockers, position — memory across sessions |
@@ -524,14 +524,14 @@ Every stage uses the same pattern: a thin orchestrator spawns specialized agents
 
 | Stage | Orchestrator does | Agents do |
 |-------|------------------|-----------|
-| Research | Coordinates, presents findings | Parallel researchers investigate stack, features, architecture and pitfalls |
-| Planning | Validates, manages iteration | Planner creates plans, checker verifies, up to three passes |
+| Research (opt-in) | Writes the open questions, checks the answers | One researcher answers each question with a source, or records an assumption |
+| Planning | Validates, manages iteration | Planner creates plans, checker verifies (one revision on the sized ceremony; up to three passes under `quality` or `--quality`); a precisely specified small phase is planned and checked by the engine instead |
 | Execution | Groups into waves, tracks progress | Executors implement in parallel, each in a fresh context (native sub-agents on Claude Code, each runtime's own delegation elsewhere) |
 | Verification | Presents results, routes next | Verifier checks codebase against goals; on Claude Code, `/pan-diagnose-issues` sends one debugger per failed UAT truth |
 
 The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
 
-**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays small, because the work happens in fresh subagent contexts. Your session stays fast and responsive.
+**The result:** You can run an entire phase — research when you ask for it, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays small, because the work happens in fresh subagent contexts. Your session stays fast and responsive.
 
 ### Reasoning-Trace Handoff
 
@@ -585,13 +585,13 @@ You're never locked in. The system adapts.
 |---|---|---|---|---|
 | **Context rot prevention** | Phase-scoped fresh context windows (native sub-agents on Claude Code) | No — context degrades over time | No (Cline: condensing) | No |
 | **Multi-agent** | Specialized agents, parallel waves | Parallel agents in worktrees (Cursor) | Single agent (Cline: subagents) | Custom agents as subagents |
-| **Plan → Verify loop** | Research → plan → verify with iteration | Agent generates plan | Plan mode (Cline) | Plan step |
-| **Post-execution verification** | Auto verifier with a test-suite gate (UAT is a template no command runs) | Iterative error-fix | Manual test runs | Auto-fix loop |
+| **Plan → Verify loop** | Plan → verify with iteration (research opt-in), right-sized in code: a precisely specified phase is planned and checked by the engine | Agent generates plan | Plan mode (Cline) | Plan step |
+| **Post-execution verification** | Auto verifier with a test-suite gate, plus a UAT walkthrough (`/pan:verify-phase N --uat`) | Iterative error-fix | Manual test runs | Auto-fix loop |
 | **Session persistence** | state.md + pause/resume + handoff | Memory tool / transcripts | None / checkpoints (Cline) | Copilot Memory, CLI session recovery |
 | **Runtime support** | Claude Code, OpenCode, Gemini CLI, Codex, Copilot CLI | IDE-locked | Terminal / VS Code | VS Code + CLI |
 | **Zero dependencies** | Yes (Node builtins only) | No (Electron) | No (Python / Node) | No |
 
-PAN is not a replacement for your IDE or AI agent — it's the orchestration layer that handles everything *around* them: breaking work into context-safe chunks, researching before planning, verifying after execution, and maintaining state across sessions.
+PAN is not a replacement for your IDE or AI agent — it's the orchestration layer that handles everything *around* them: breaking work into context-safe chunks, answering the open questions before planning when you ask it to, verifying after execution, and maintaining state across sessions.
 
 > For the full comparison across the major AI coding tools and many dimensions, see [COMPARISON.md](docs/COMPARISON.md).
 
@@ -603,26 +603,26 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
+| `/pan:new-project [--auto] [--research [market]]` | Full initialization: questions → research (opt-in) → requirements → roadmap |
 | `/pan:discuss-phase <N> [--auto]` | Capture implementation decisions before planning |
 | `/pan:design-phase <N>` | Design a phase — architecture, ADR, threat-lite — before planning |
-| `/pan:plan-phase [N] [--auto]` | Research + plan + verify for a phase |
+| `/pan:plan-phase [N] [--auto]` | Plan + verify for a phase (research with `--research`); `--research-only <N>` runs the research step alone |
 | `/pan:exec-phase <N>` | Execute all plans in parallel waves, verify when complete |
-| `/pan:verify-phase [N]` | Re-run goal-backward verification with a test-suite gate; lists gaps for `/pan:plan-phase N --gaps` ¹ |
-| `/pan:milestone-audit` | Verify milestone achieved its definition of done |
-| `/pan:milestone-done <version>` | Archive milestone, tag release |
-| `/pan:milestone-new [name]` | Start next version: questions → research → requirements → roadmap |
+| `/pan:verify-phase [N] [--uat]` | Re-run goal-backward verification with a test-suite gate; lists gaps for `/pan:plan-phase N --gaps` ¹. `--uat` walks you through the phase's acceptance tests instead, on every runtime |
+| `/pan:autodev [run\|resume\|status]` | Run the roadmap unattended: a deterministic loop plans, executes, verifies and completes each phase, each step in a fresh host session (a lean phase is planned by the engine and built, reviewed and verified in one session), and stops in code (done, human needed, gate failed, CI failed, forecast exceeded, budget, turns, no progress) |
+| `/pan:milestone-audit` | Verify milestone achieved its definition of done; `--gaps` creates phases to close the gaps the audit found |
+| `/pan:milestone-done <version>` | Archive milestone, tag release; `--cleanup` archives accumulated phase directories from completed milestones |
+| `/pan:milestone-new [name]` | Start next version: questions → research (opt-in) → requirements → roadmap |
 
 ### Navigation
 
 | Command | What it does |
 |---------|--------------|
 | `/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:hud` | Render a self-contained HTML dashboard of project + bot-army state to `.planning/hud.html` (`--open`, `--out`, `--stdout`); the old name `/pan:dashboard` still works |
 | `/pan:report phase <N> \| index \| all` | Self-contained HTML report for one phase, or a timeline index linking every phase report (`--out`, `--open`, `--stdout` on `phase` and `index`; `--bundle` on `index` inlines every phase report into one file; `all` regenerates every phase report plus the index and takes only `--open`) |
 | `/pan:help` | Show all commands and usage guide |
 | `/pan:update` | Update PAN with changelog preview |
-| `/pan:discord` | Join the PAN Discord community |
 
 ### Brownfield
 
@@ -644,7 +644,6 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/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 |
 
 ### Session
 
@@ -657,20 +656,17 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:settings` | Configure model profile, workflow agents, branching and the phase budget |
-| `/pan:profile <profile>` | Switch model profile (quality/balanced/budget) |
+| `/pan:settings` | Configure model profile, workflow agents, branching and the phase budget; `--profile <profile>` switches the model profile (quality/balanced/budget) directly |
 | `/pan:todo-add [desc]` | Capture idea for later |
 | `/pan:todo-check` | List pending todos |
 | `/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:quick [--full] [--quality]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification; `--quality` gives one run the full ceremony, with a planner even for a precisely described task) |
 | `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` fixes the issues it marks repairable |
 | `/pan:hygiene [--apply] [--trace-age-days N] [--all-tracks]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat and stale or expired memory entries, poisoned cost ledgers, trace and report debris, cached-context bloat, fragment planning dirs) and Claude Code's own memory index (reported, never edited); `--apply` executes the safe fixes — poisoned ledgers are quarantined by rename (only the newest quarantine copy is kept), and settled `state.md` history, shipped roadmap phases and stale memory entries are archived rather than dropped |
 | `/pan:links [--strict] [--doc-root <dir>] [--source-root <dir>]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027). The default roots are PAN's own source layout, so pass your project's roots |
 | `/pan:phase-tests <N> [instructions]` | Generate tests for a completed phase from its summaries, context decisions and verification report |
-| `/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) |
 
@@ -691,14 +687,9 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:focus-scan` | Collect, classify, and prioritize all work items with Reality Score |
-| `/pan:focus-plan` | Create capacity-budgeted execution batch (modes: bugfix, balanced, features, full) |
-| `/pan:focus-exec` | Execute items from batch with tier-based test cadence |
-| `/pan:focus-auto` | Continuous scan→plan→exec loop with purpose-driven categories and a layered safety harness |
-| `/pan:focus-sync` | Detect stale documentation (counts, missing commands, outdated references); `--all` also fixes it |
+| `/pan:focus-auto` | Continuous scan→plan→exec loop with purpose-driven categories and a layered safety harness; `--step scan\|plan\|exec\|drift` runs one stage: scan collects and prioritizes work items with a Reality Score, plan builds a capacity-budgeted batch (modes: bugfix, balanced, features, full), exec runs the batch with tier-based test cadence, drift walks the tree to find and repair doc-code drift |
 | `/pan:focus-design` | Multi-phase strategic feature investigation pipeline |
-| `/pan:focus-drift-walking` | Walk project tree, detect doc-code drift, score severity, auto-repair |
-| `/pan:focus-doc-audit` | Multi-dimensional document audit with a quality score per dimension |
+| `/pan:focus-docs` | Multi-dimensional document audit with a quality score per dimension; `--sync` detects stale documentation (counts, missing commands, outdated references), and `--sync --all` also fixes it |
 
 ### Cost, Foresight & Review
 
@@ -709,16 +700,13 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:review-deep <phase>` | Security audit (OWASP + STRIDE) + cross-check by meta-reviewer |
 | `/pan:knowledge {ask\|discuss\|playbook}` | Grounded Q&A, multi-turn discussion, or aggregate memory into playbook |
 | `/pan:what-if <phase> "scenario"` | Counterfactual phase replay in isolated git worktree |
-| `/pan:mcp-bridge {list\|recommend\|cache}` | List the MCP tools recorded in its cache (only `cache --servers` or an external script writes it) and recommend the ones relevant to a phase |
 
 ### Optimization & Git
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:learn` | Analyze trace events and write an optimization report. `/pan:optimize apply` records its suggestions; nothing is applied automatically |
-| `/pan:optimize {apply\|revert\|list\|stats\|trace}` | Record a report's suggestions for a person to act on (`apply`: notes in `.planning/optimization/suggestions.md`, config notes in `config-suggestions.md`), undo one apply (`revert <apply_id>` or `revert --last`), list reports, view stats, manage trace sessions |
+| `/pan:learn` | Analyze trace events and write an optimization report; nothing is applied automatically. `--optimize {apply\|revert\|list\|stats\|trace}` records a report's suggestions for a person to act on (`apply`: notes in `.planning/optimization/suggestions.md`, config notes in `config-suggestions.md`), undoes one apply (`revert <apply_id>` or `revert --last`), lists reports, shows stats and manages trace sessions |
 | `/pan:git <subcommand>` | Phase-aware git workflow: commit/branch/push/status/log/stash/diff/rollback/tag/sync |
-| `/pan:audit-deployment <target-directory> [--enhancements] [--repair]` | Audit a PAN installation for integrity, project health, and draft enhancement specs |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
 
@@ -744,14 +732,14 @@ Control which Claude model each agent uses. Balance quality vs token spend.
 | Profile | Planning | Execution | Verification |
 |---------|----------|-----------|--------------|
 | `quality` | reasoning | reasoning | reasoning |
-| `balanced` (default) | reasoning | reasoning | reasoning |
+| `balanced` (default) | reasoning (planner); Sonnet for the plan-checker and the researchers | reasoning | reasoning |
 | `budget` | Sonnet | Sonnet | Haiku |
 
-> `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 on Claude Code. The other runtimes' agent files drop the pin, so there those agents inherit the session model too. Both `quality` and `balanced` resolve this way; only `budget` steps down — to a Sonnet/Haiku mix on Claude Code, and to the provider's own mid and fast models where PAN detects OpenAI (Codex) or Google (Gemini CLI) — under OpenCode, as `provider/model` ids for the provider of OpenCode's configured `model`, or, when that names none PAN routes for, the provider the runtime directories suggest (`.opencode/` alone counts as OpenAI); `pan-tools resolve-model <agent>` prints the id. 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) — the 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 on Claude Code. The other runtimes' agent files drop the pin, so there those agents inherit the session model too. `quality` resolves every agent this way and runs the full ceremony on every phase; `balanced` moves only the plan-checker and the two researchers to the mid tier and sizes the ceremony (a precisely specified phase is planned and checked by the engine); `budget` steps every agent down — to a Sonnet/Haiku mix on Claude Code, and to the provider's own mid and fast models where PAN detects OpenAI (Codex) or Google (Gemini CLI) — under OpenCode, as `provider/model` ids for the provider of OpenCode's configured `model`, or, when that names none PAN routes for, the provider the runtime directories suggest (`.opencode/` alone counts as OpenAI); `pan-tools resolve-model <agent>` prints the id. 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
+/pan:settings --profile budget
 ```
 
 Or configure via `/pan:settings`.
@@ -762,7 +750,7 @@ These spawn additional agents during planning/execution. They improve quality bu
 
 | Setting | Default | What it does |
 |---------|---------|--------------|
-| `workflow.research` | `true` | Researches domain before planning each phase |
+| `workflow.research` | `false` | Research before planning each phase (opt-in: one researcher answers at most five open questions that block building); `/pan:plan-phase N --research` researches one phase |
 | `workflow.plan_check` | `true` | Verifies plans achieve phase goals before execution |
 | `workflow.verifier` | `true` | Confirms must-haves were delivered after execution |
 | `workflow.auto_advance` | `false` | Auto-chain discuss → plan → execute without stopping |

package/agents/pan-conductor.md

@@ -11,8 +11,7 @@ You are the PAN conductor. You coordinate a hierarchical execution of a phase: d
 
 You are spawned by `/pan:exec-phase <N> --hierarchical`. Without that flag, the normal flat exec path runs instead — you are never invoked by default.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This includes the phase plan and any audit log from prior runs.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This includes the phase plan and any audit log from prior runs.
 </role>
 
 <safety_harness>
@@ -123,7 +122,7 @@ For each phase execution:
 
 <output_contract>
 
-On completion (success, partial, or abort), write `.planning/orchestration/summary.md`:
+On completion (success, partial, or abort), write `.planning/orchestration/orchestration-summary.md` (not `summary.md`: Claude Code refuses a subagent's write to a file of that name):
 
 ```markdown
 ---

package/agents/pan-counterfactual.md

@@ -15,8 +15,7 @@ Your output has two parts:
 1. **Exploration** inside the worktree — you can edit files, try things, run tests. It's a safe sandbox.
 2. **Report** back to the main tree — one structured JSON payload that the command uses to write `.planning/counterfactuals/<phase>-<slug>.md`.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This typically includes the phase's plan, any existing summary, and the scenario text.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This typically includes the phase's plan, any existing summary, and the scenario text.
 </role>
 
 <boundaries>

package/agents/pan-debugger.md

@@ -16,8 +16,7 @@ You are spawned by:
 
 Your job: Find the root cause through hypothesis testing, maintain debug file state, optionally fix and verify (depending on mode).
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context.
 
 **Core responsibilities:**
 - Investigate autonomously (user reports symptoms, you find cause)
@@ -782,6 +781,7 @@ started: [when broke / always broken]
 command: [one command you have RUN that fails on the reported symptom, or "none"]
 fails_with: [the output that shows the symptom, secrets redacted]
 deterministic: [yes / rate N of M runs for a flaky bug]
+requirement: [the requirement or UAT truth this reproduces, e.g. REQ-4, when there is one]
 tried: [only when command is "none": what you tried and why it cannot be built]
 
 ## Eliminated
@@ -907,9 +907,14 @@ Gather symptoms through questioning. Update file after EACH answer.
 - Run app/tests to observe behavior
 - APPEND to Evidence after each finding
 
+**Phase 1a: Check the case base.** Before forming any theory, look for a resolved session with the same symptoms. A recurring bug starts from the root cause and fix that worked before. Treat a match as a lead to test, not a conclusion:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs debug similar "<expected vs actual, in the user's words>"
+```
+
 **Phase 1b: Reproduce before you theorise** (no hypothesis until this is written)
 - Build ONE command that drives the reported symptom: a failing test at the closest seam, a CLI call with a fixture, a script. It must assert the user's symptom, not merely run.
-- RUN it and record it in Reproduction (`command`, `fails_with`, secrets redacted). Run it again: the same verdict, or for a flaky bug a recorded rate.
+- RUN it and record it in Reproduction (`command`, `fails_with`, secrets redacted, and `requirement:` naming the requirement or UAT truth it stands for, when there is one; a gap that breaks two requirements gets one reproduction each). Run it again: the same verdict, or for a flaky bug a recorded rate.
 - Shrink it: cut inputs and steps one at a time, re-running after each, while it still fails. Keep the smallest command that fails.
 - If no command can be built, write `command: none` and `tried:` (what you attempted, why it failed). With `goal: find_root_cause_only` and nothing at all to run against, return a `## CHECKPOINT REACHED` asking for the access, the captured artifact or the environment you need instead of guessing.
 - Reading code to build a theory before this is written is the failure this step prevents: a fix aimed at a neighbouring bug.
@@ -1010,6 +1015,12 @@ Update status to "fixing".
 <step name="request_human_verification">
 **Require user confirmation before marking resolved.**
 
+First the engine runs your reproduction. It must turn green, or the session is not done, whatever the fix looks like:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs debug repro "{slug}"
+```
+`red` means the fix did not fix the reported symptom, so go back to investigating. `none` (no command could be built) leaves the closing to the human check below.
+
 Update status to "awaiting_human_verify".
 
 Return:

package/agents/pan-design-checker.md

@@ -15,8 +15,7 @@ Spawned by:
 
 Goal-backward verification of DESIGNS before planning or execution burns context. Start from what the change SHOULD deliver and prove the design addresses it — with a real architecture, honest trade-offs, covered threats, and machine-checkable success.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context (the design artifact, the boundary it must respect, and any spec/roadmap it derives from).
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context (the design artifact, the boundary it must respect, and any spec/roadmap it derives from).
 
 **Critical mindset:** A design describes intent. You verify it holds up. A design can have every section filled in and still fail if:
 - A stated requirement has no design element (silent drop)

package/agents/pan-designer.md

@@ -15,8 +15,7 @@ Spawned by:
 
 Your job: produce a `{phase}-design.md` (from `templates/design.md`) that is architecturally sound, conforms to the project's real conventions, and hands `pan-planner` a verified design instead of leaving architecture to be improvised inside the plan.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context (the phase boundary from `roadmap.md`, any `{phase}-context.md`, and `{phase}-research.md` if present).
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context (the phase boundary from `roadmap.md`, any `{phase}-context.md`, and `{phase}-research.md` if present).
 
 **Read also:**
 - `~/.claude/pan-wizard-core/references/design-methodology.md` — the shared method and depth tiers. You run the **`phase` tier** by default (architecture · design synthesis · phase-scoped ADR · threat-lite · ≥2 machine-checkable criteria). `--spike` drops to the `spike` tier.

package/agents/pan-document_code.md

@@ -19,8 +19,7 @@ You are spawned by `/pan:map-codebase` with one of six focus areas:
 
 Your job: Explore thoroughly, then write document(s) directly. Return confirmation only.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context.
 </role>
 
 <mode>

package/agents/pan-hardener.md

@@ -12,12 +12,11 @@ You are the PAN hardener. You perform focused security review on files changed d
 
 This is **authorized, defensive** secure-coding review of the user's own codebase — the goal is to find and fix weaknesses before shipping. You report findings for the user to remediate; you never write exploit code, attack tooling, or step-by-step intrusion instructions.
 
-You are spawned by `/pan:review-deep <phase>`, `/pan:exec-phase --deep-review`, `/pan:focus-exec --deep-review` (per item, output under `.planning/reviews/<item-id>/`) or `/pan:focus-auto` Pass 3. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
+You are spawned by `/pan:review-deep <phase>`, `/pan:exec-phase --deep-review`, `/pan:focus-auto --step exec --deep-review` (per item, output under `.planning/reviews/<item-id>/`) or `/pan:focus-auto` Pass 3. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
 
 **You NEVER modify source files.** Your one write is the report at the output path your prompt gives. You report findings; the user fixes them.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context.
 </role>
 
 <frameworks>

package/agents/pan-integration-checker.md

@@ -11,8 +11,7 @@ You are an integration checker. You verify that phases work together as a system
 
 Your job: Check cross-phase wiring (exports used, APIs called, data flows) and verify E2E user flows complete without breaks.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. This is your primary context.
 
 **Critical mindset:** Individual phases can pass while the system fails. A component can exist without being imported. An API can exist without being called. Focus on connections, not existence.
 </role>

package/agents/pan-knowledge.md

@@ -9,8 +9,7 @@ effort: medium
 <role>
 You are the PAN knowledge agent. You help users retrieve, refine, and consolidate project context. You are spawned by `/pan:knowledge {ask | discuss | playbook}` and branch behavior based on the `<mode>` field in the prompt.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. For `ask` mode, these files are the top-ranked candidates from the knowledge retriever. For `discuss` mode, they're the session history + phase context. For `playbook` mode, they're the aggregated memory entries.
+**Initial read.** If the prompt contains a `<files_to_read>` block, read every file it lists before doing anything else. For `ask` mode, these files are the top-ranked candidates from the knowledge retriever. For `discuss` mode, they're the session history + phase context. For `playbook` mode, they're the aggregated memory entries.
 </role>
 
 <mode>

package/agents/pan-meta-reviewer.md

@@ -15,12 +15,11 @@ You are the PAN meta-reviewer. Your job is to check the first-pass reviewers (`p
 3. **Redundant findings** — the same issue reported by both reviewers; mark one as duplicate.
 4. **Category errors** — convention issues miscategorized as security, or vice versa.
 
-You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports, or by `/pan:focus-exec --deep-review` with the hardener's report alone (an item has no first-pass review: check the hardener against the diff, and skip the reviewer-side coverage and duplicate checks). Your output is merged with theirs by `review-deep.cjs`.
+You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports, or by `/pan:focus-auto --step exec --deep-review` with the hardener's report alone (an item has no first-pass review: check the hardener against the diff, and skip the reviewer-side coverage and duplicate checks). Your output is merged with theirs by `review-deep.cjs`.
 
 **You NEVER modify source code.** You produce one findings file. This is authorized, defensive review of the user's own codebase — you adjudicate security findings for remediation; never produce exploit code.
 
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block (it will contain the reviewer and hardener outputs + representative diff snippets), you MUST use the `Read` tool to load every file listed there before performing any other actions.
+**Initial read.** If the prompt contains a `<files_to_read>` block (it will contain the reviewer and hardener outputs + representative diff snippets), read every file it lists before doing anything else.
 </role>
 
 <reasoning_protocol>
@@ -37,6 +36,7 @@ Think through, in order:
    - Public API changes without changelog entries
    - Documentation that got updated but now contradicts the code
 5. **Be specific.** Every finding you add or dispute needs a file:line citation.
+6. **Prove the serious defects.** A critical or high defect finding is a `candidate` until a catching test proves it. A catching test passes at the phase's base and fails at HEAD, so it shows the defect the phase introduced. For each such finding with a ledger id (`node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings list --phase <N> --status open`), write the smallest test that would catch it under `.planning/reviews/<N>/proofs/`, never in the source tree. Then run `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings prove <f_id> --test <that file>`. Report each result as `confirmed` or `candidate` with the proof's status. A finding you cannot write a test for stays a candidate; say why.
 
 </reasoning_protocol>
 

package/agents/pan-optimizer.md

@@ -16,7 +16,7 @@ Transform raw execution traces into concrete, ranked improvements. Every recomme
 1. **Specific** — name the file, agent, or workflow step to change
 2. **Actionable** — tell the implementer exactly what to add/change/remove
 3. **Prioritized** — critical/major/minor based on frequency × impact
-4. **Placed** — name where the fix belongs, so the next run's agents read it: the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, a comment at the cited code, an agent prompt, or a workflow step. A person makes the change; `/pan:optimize apply` only records your suggestions
+4. **Placed** — name where the fix belongs, so the next run's agents read it: the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, a comment at the cited code, an agent prompt, or a workflow step. A person makes the change; `/pan:learn --optimize apply` only records your suggestions
 
 ## Inputs
 
@@ -92,7 +92,7 @@ Produce ranked recommendations in these categories:
 
 ### Step 5: Derive Auto-Apply Actions
 
-Each recommendation becomes a `note` action in the `## Auto-Apply Actions` block; a config change is a `planning_note`. `/pan:optimize apply` records notes in `.planning/optimization/suggestions.md` and config notes in `config-suggestions.md`. Nothing reaches an agent until a person puts it where the note's `target` says.
+Each recommendation becomes a `note` action in the `## Auto-Apply Actions` block; a config change is a `planning_note`. `/pan:learn --optimize apply` records notes in `.planning/optimization/suggestions.md` and config notes in `config-suggestions.md`. Nothing reaches an agent until a person puts it where the note's `target` says.
 
 ```json
 [
@@ -115,7 +115,7 @@ Each recommendation becomes a `note` action in the `## Auto-Apply Actions` block
 
 ## Output Format
 
-Write the report as a markdown file at `.planning/optimization/reports/{session}-opt-report.md`. It is the only file you write: `/pan:optimize apply` records the Auto-Apply Actions, so never write `suggestions.md` or a project file yourself.
+Write the report as a markdown file at `.planning/optimization/reports/{session}-opt-report.md`. It is the only file you write: `/pan:learn --optimize apply` records the Auto-Apply Actions, so never write `suggestions.md` or a project file yourself.
 
 ````markdown
 # Optimization Report — {session_id}
@@ -198,7 +198,7 @@ Write the report as a markdown file at `.planning/optimization/reports/{session}
 
 ## Auto-Apply Actions
 
-`/pan:optimize apply` records the following actions as suggestions for a person; none of them changes what an agent is told:
+`/pan:learn --optimize apply` records the following actions as suggestions for a person; none of them changes what an agent is told:
 
 ```json
 [