pan-wizard 3.32.0 → 3.34.0

package/commands/pan/mcp-bridge.md

@@ -2,7 +2,7 @@
 name: pan:mcp-bridge
 group: External tools
 description: Discover available MCP tools and recommend which ones apply to a phase. Discovery-only; auto-invocation deferred.
-argument-hint: "list | recommend <phase> | cache [--servers <json>] [--runtime <name>]"
+argument-hint: "list | recommend <phase> [--max N] [--min-score N] | cache [--servers <json>] [--runtime <name>]"
 allowed-tools:
   - Read
   - Bash
@@ -12,7 +12,7 @@ allowed-tools:
 <objective>
 Surface Model Context Protocol (MCP) tools visible to the host runtime and recommend which ones might apply to a specific phase plan.
 
-Reduced scope from Spec B v1's X-7: **discovery and recommendation only**. Auto-injection of MCP tools into planner context and auto-invocation from executor agents are deliberately deferred (likely Wave 5+ or v3.5). This keeps v3.3 narrow and avoids coupling PAN to Claude Code's MCP schema stability.
+Reduced scope from Spec B v1's X-7: **discovery and recommendation only**. Auto-injection of MCP tools into planner context and auto-invocation from executor agents are deliberately deferred and still unscheduled (the v3.5 target passed without them). This kept v3.3 narrow and avoids coupling PAN to Claude Code's MCP schema stability.
 </objective>
 
 <execution_context>
@@ -44,7 +44,7 @@ Show cached MCP tools with server grouping and schemas.
 }
 ```
 
-When `source: "empty"`, either no MCP servers are configured or the host runtime hasn't populated the cache yet. See the `cache` subcommand for manual seeding.
+When `source: "empty"`, nothing has seeded the cache yet: no hook or host writes it, only `cache --servers` (or an external script). See the `cache` subcommand for manual seeding.
 
 ### `recommend <phase>`
 
@@ -85,20 +85,20 @@ Scoring is naive keyword frequency with word boundaries — not semantic embeddi
 Write or inspect the MCP tools cache at `.planning/bridge/available-tools.json`.
 
 ```
-# Inspect current cache (same as `list` but raw)
+# Inspect current cache (prints the same JSON as `list`)
 /pan:mcp-bridge cache
 
 # Seed cache from scripted discovery (for testing or external pipeline)
 /pan:mcp-bridge cache --runtime claude --servers '[{"name":"linear","tools":[{"name":"linear.updateTicket","description":"Update ticket"}]}]'
 ```
 
-Normally the host runtime writes this file. The CLI path exists for test fixtures and external-script integration.
+Nothing else writes this file: no hook or installer step populates it, so `list` and `recommend` see only what this command (or an external script) has recorded.
 
 </subcommands>
 
 <workflow>
 
-**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — each runtime keeps it somewhere different: Claude Code in `settings.json` under its config dir, OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
+**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, nothing has seeded the cache: record each server with its tools, `/pan:mcp-bridge cache --servers '[{"name":"<server>","tools":[{"name":"<tool>","description":"…"}]}]'`, taking the tool names and descriptions from the MCP tools your session has loaded. A server recorded without `tools` adds no tool to `list` (only `server_count` counts it, and `source` then reads `cache`) and nothing to `recommend`, and the host runtime's MCP config names only the servers and how to start them. Each runtime keeps that config somewhere different: Claude Code in `.mcp.json` at the project root (project scope) or `~/.claude.json` (user and local scopes), OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
 
 **Planning a phase that might touch external systems?** Run `/pan:mcp-bridge recommend <phase>` to get a ranked shortlist. Copy relevant tool names into the phase plan's "External tools" section so the executor knows to invoke them.
 
@@ -108,11 +108,11 @@ Normally the host runtime writes this file. The CLI path exists for test fixture
 
 <caveats>
 
-**Discovery is a cache, not a live probe.** The host runtime owns populating `.planning/bridge/available-tools.json`. PAN does not query MCP servers directly — that would require runtime-specific HTTP or IPC integration this command deliberately avoids.
+**Discovery is a cache, not a live probe.** Only `cache --servers` (or an external script) populates `.planning/bridge/available-tools.json`; no hook or host writes it. PAN does not query MCP servers directly — that would require runtime-specific HTTP or IPC integration this command deliberately avoids.
 
 **Keyword scoring is crude.** "Postgres" and "PostgreSQL" are different tokens; `postgresql` in a plan won't match a `postgres.query` tool unless the plan also says "postgres." Tune your plan language or expand tool descriptions to improve matches.
 
-**Claude Code is the primary target.** MCP is a Claude-first protocol. Other runtimes may have their own tool-discovery mechanisms; the cache schema is intentionally generic so a future Codex/Gemini equivalent could populate the same file.
+**No runtime is special.** Each runtime PAN installs into reads MCP servers from its own config (see the workflow section above); the cache schema is generic, so whatever lists a runtime's servers can populate the same file.
 
 **No automatic invocation.** This command never calls MCP tools. It tells you what's available and what might apply. The actual invocation happens via the host runtime's normal tool-use flow (Claude Code's tool calls, etc.) when the executor agent decides to use a recommended tool.
 
@@ -122,23 +122,23 @@ Normally the host runtime writes this file. The CLI path exists for test fixture
 
 | Runtime | list | recommend | cache |
 |---------|------|-----------|-------|
-| Claude Code | Full | Full | Full (host-populated) |
-| OpenCode | Stub (empty cache returns gracefully) | Stub | CLI write works |
-| Gemini CLI | Stub | Stub | CLI write works |
-| Codex CLI | Stub | Stub | CLI write works |
-| Copilot CLI | Stub | Stub | CLI write works |
+| Claude Code | Full once seeded | Full once seeded | Full |
+| OpenCode | Full once seeded | Full once seeded | Full |
+| Gemini CLI | Full once seeded | Full once seeded | Full |
+| Codex CLI | Full once seeded | Full once seeded | Full |
+| Copilot CLI | Full once seeded | Full once seeded | Full |
 
-On non-Claude runtimes, the aggregator and recommendation logic still work — they just report zero tools until something populates the cache.
+On every runtime, `list` reports zero tools (`source: "empty"`) and `recommend` an empty `recommendations` list with a `reason` until `cache --servers` (or an external script) populates the cache; no host or hook writes it.
 
 </runtime_compatibility>
 
 <future_scope>
 
-Explicitly deferred from v3.3 (documented in ADR-0023 / Spec B v2 notes):
+Explicitly deferred from v3.3 (documented in ADR-0024 / Spec B v2 notes):
 
-1. **Auto-inject recommended tools into planner context** — requires a stable MCP schema contract and a plan-template extension. Candidate for v3.5.
-2. **Auto-invoke MCP tools from executor agent** — requires permission-gating and per-tool safety review. Candidate for v3.5+.
-3. **Cross-runtime tool discovery** — generic MCP-like protocol for non-Claude runtimes. No timeline; needs ecosystem signal.
+1. **Auto-inject recommended tools into planner context** — requires a stable MCP schema contract and a plan-template extension. Unscheduled.
+2. **Auto-invoke MCP tools from executor agent** — requires permission-gating and per-tool safety review. Unscheduled.
+3. **Cross-runtime tool discovery** — filling the cache automatically from each runtime's own MCP config and servers. No timeline; needs ecosystem signal.
 
 Until those land, this command is the minimum viable integration: you see what's there, you get suggestions, you decide manually.
 

package/commands/pan/milestone-done.md

@@ -34,7 +34,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
 **User input:**
 
-- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+- Version: $ARGUMENTS (e.g., "1.0", "1.1", "2.0"); `{{version}}` below stands for this value
   </context>
 
 <process>
@@ -46,6 +46,7 @@ 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 `passed`: proceed to step 1
 
    ```markdown
@@ -87,6 +88,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
    - Create `.planning/milestones/v{{version}}-roadmap.md`
    - Extract full phase details from roadmap.md
    - Fill milestone-archive.md template
+   - Add this milestone's entry to `.planning/milestones.md` from @~/.claude/pan-wizard-core/templates/milestone.md (create the file with that template's header if it does not exist)
    - Update roadmap.md to one-line summary with link
 
 5. **Archive requirements:**
@@ -104,7 +106,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
 7. **Commit and tag:**
 
-   - Stage: milestones.md, project.md, roadmap.md, state.md, archive files
+   - Stage: milestones.md, project.md, roadmap.md, state.md, archive files, and the deleted requirements.md, and commit with `--force` (the user confirmed the milestone in step 1): `pan-tools commit` refuses any pending deletion, staged or not (`deleted_files_detected`), unless git pairs it with the archive as a rename
    - Commit: `chore: archive v{{version}} milestone`
    - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
    - Ask about pushing tag
@@ -116,10 +118,11 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
    ```bash
    node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null || true
-   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn 2>/dev/null || true
+   # trace end cleared the active-session pointer, so pool the recent sessions
+   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 write memory entries.
+   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.
 
 </process>
 
@@ -137,7 +140,6 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
 <critical_rules>
 
-- **Load workflow first:** Read milestone-done.md before executing
 - **Verify completion:** All phases must have summary.md files
 - **User confirmation:** Wait for approval at verification gates
 - **Archive before deleting:** Always create archive files before updating/deleting originals

package/commands/pan/milestone-new.md

@@ -22,7 +22,7 @@ Brownfield equivalent of new-project. Project exists, project.md has history. Ga
 - `.planning/roadmap.md` — phase structure (continues numbering)
 - `.planning/state.md` — reset for new milestone
 
-**After:** `/pan:design-phase [N]` → `/pan:plan-phase [N]` to design then plan the first phase.
+**After:** `/pan:discuss-phase [N]` (then, optionally, `/pan:design-phase [N]`) → `/pan:plan-phase [N]` for the first phase.
 
 **Design altitude (ADR-0042):** product/strategic design — demand validation, competitive intelligence, market positioning — belongs HERE at milestone creation (via the requirements/research cycle, or `/pan:focus-design` for a strategic feature), done ONCE. Per-phase architecture/ADR/threat design is `/pan:design-phase`, run per phase. Do not defer product questions to per-phase design, and do not re-open them there.
 </objective>

package/commands/pan/new-project.md

@@ -12,7 +12,7 @@ allowed-tools:
 ---
 <context>
 **Flags:**
-- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
+- `--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.
 </context>
 
 <objective>
@@ -26,7 +26,7 @@ Initialize a new project through unified flow: questioning → research (optiona
 - `.planning/roadmap.md` — phase structure
 - `.planning/state.md` — project memory
 
-**After this command:** Run `/pan:plan-phase 1` to start execution.
+**After this command:** Run `/pan:discuss-phase 1` to gather context, or `/pan:plan-phase 1` to plan directly. With `--auto` the workflow continues into `/pan:discuss-phase 1 --auto` itself.
 </objective>
 
 <execution_context>
@@ -68,23 +68,23 @@ Use this decision tree to select the correct path. Evaluate conditions top-to-bo
 
 ```
 IF .planning/ already exists AND contains project.md:
-  → WARN: "Project already initialized. Use /pan:resume to continue."
+  → WARN: "Project already initialized. Use /pan:progress to continue."
   → STOP (do not overwrite existing project)
 
-ELSE IF --auto flag AND @ reference document provided:
-  → ASK config questions only (commit_docs, model_profile)
-  → SKIP interactive questioning (use the @ document as project context)
+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 + @ document
+  → GENERATE requirements from research + the document
   → GENERATE roadmap from requirements
   → No further interaction until complete
 
-ELSE IF --auto flag WITHOUT @ reference:
-  → ERROR: "--auto requires an @ referenced idea document"
+ELSE IF --auto flag WITHOUT an idea document:
+  → ERROR: "--auto requires an idea document" (an @ reference, or the idea pasted after the flag)
   → STOP
 
 ELSE (interactive mode — default):
-  → RUN questioning flow (5-area deep questioning)
+  → 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

package/commands/pan/optimize.md

@@ -1,7 +1,8 @@
 ---
 name: pan:optimize
 group: Self-Improvement
-description: Manage the circular optimization loop — apply recommendations, view stats, list reports, manage trace sessions
+description: Manage the circular optimization loop — record a report's suggestions, undo them, view stats, list reports, manage trace sessions
+argument-hint: "apply [--report <file>] | revert <apply_id> | revert --last | list | stats | trace init|end|current|list"
 allowed-tools:
   - Read
   - Write
@@ -13,7 +14,7 @@ allowed-tools:
 
 # /pan:optimize
 
-Manage the circular optimization loop: apply recommendations, view stats, list reports.
+Manage the circular optimization loop: record a report's suggestions, view stats, list reports.
 
 **Usage:**
 ```
@@ -32,14 +33,15 @@ Manage the circular optimization loop: apply recommendations, view stats, list r
 **Subcommands:**
 
 ### apply
-Apply safe optimizations from the most recent (or specified) optimization report.
+Record the suggestions from the most recent (or specified) optimization report.
 
-Auto-applied automatically:
-- New memory entries (`.planning/memory/*.md`) — skipped if file already exists
-- Suggestions appended to `.planning/optimization/suggestions.md`
+Recorded automatically:
+- Suggestions appended to `.planning/optimization/suggestions.md`: lessons, prompt changes and workflow changes, each naming where it belongs
 - Config notes appended to `.planning/optimization/config-suggestions.md`
+- An older report's memory actions (`memory_entry`, `memory`, `memory_append`) still write to `.planning/memory/`, a `memory_entry` only if it passes the checks of the `memory record` command. The result warns that PAN's workflows do not load that folder into agents
 
-Requires human review (never auto-applied):
+A person makes every change the suggestions describe (never auto-applied):
+- Lessons, written into the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, or a comment at the cited code
 - Agent prompt changes
 - Workflow step additions
 - Structural changes to commands
@@ -47,7 +49,7 @@ Requires human review (never auto-applied):
 After applying, the report lists what was applied and what still needs review, plus the `apply_id` that undoes it. Every apply is recorded action by action in `.planning/optimization/applied.jsonl`: the path, whether the file was created or appended to, the exact text, and a hash of the file after the write. Applying the same report a second time writes nothing: each action names the apply that already wrote it.
 
 ### revert
-Undo one apply exactly: delete the memory files it created and cut the text it appended (`revert --last` for the newest).
+Undo one apply exactly: delete the files it created and cut the text it appended (`revert --last` for the newest).
 
 Revert never destroys work someone did since:
 - It refuses a file whose content changed after the apply. The comparison ignores line endings, so a CRLF checkout still matches.
@@ -63,12 +65,12 @@ List all optimization reports in `.planning/optimization/reports/`, most recent
 Show cumulative optimization statistics:
 - Total trace sessions run
 - Total events traced
-- Total errors/gaps/redundancies seen
+- Total errors seen (`total_errors_traced`; gaps and redundancies are not totalled)
 - Total optimizations applied across all runs, the apply runs, the reverted runs, and the last `apply_id`
 - Current active trace session (if any)
 
 ### trace init
-Start a new trace session before running a build. The hook fires automatically on SubagentStop, but calling `trace init` first lets you attach a description to the session.
+Start a trace session before running a build — or join the active one: `trace init` reuses an unended session started within the last hour (`reused: true`, keeping that session's description) instead of opening a new one. The hook fires automatically on SubagentStop, but calling `trace init` first lets you attach a description to a new session.
 
 ```
 /pan:optimize trace init --description "building express web server"
@@ -80,7 +82,7 @@ Start a new trace session before running a build. The hook fires automatically o
 Finalize the current trace session (writes summary stats to session.json).
 
 ### trace current
-Show the active trace session ID and event count.
+Show the active trace session ID (`optimize trace current` returns only `session_id` and `active`; `trace list` carries each session's event count).
 
 ### trace list
 List all trace sessions, most recent first.
@@ -98,14 +100,14 @@ List all trace sessions, most recent first.
 │         ↓                                          │
 │  /pan:learn           ← analyze + report           │
 │         ↓                                          │
-│  /pan:optimize apply  ← write memory entries       │
+│  /pan:optimize apply  ← record suggestions         │
 │         ↓                                          │
-│  Next run is smarter  ← memory populated           │
+│  You make the changes ← instructions, tests, code  │
 │         ↑                                          │
 │         └──────────────────────────────────────────┘
 └─────────────────────────────────────────────────────┘
 ```
 
-Each iteration improves the model's context: fewer memory misses, fewer repeated errors, better decisions.
+Each iteration puts what the last run lacked where the next run's agents read it: fewer repeated errors and gaps.
 
 **See also:** `/pan:learn`, `/pan:exec-phase`

package/commands/pan/patches.md

@@ -23,12 +23,8 @@ After a PAN update wipes and reinstalls files, this command merges user's previo
 Check for local patches directory:
 
 ```bash
-# Global install (path templated at install time)
+# This install's own dir — the installer templates ~/.claude/ to it, local or global
 PATCHES_DIR=~/.claude/pan-local-patches
-# Local install fallback
-if [ ! -d "$PATCHES_DIR" ]; then
-  PATCHES_DIR=~/.claude/pan-local-patches
-fi
 ```
 
 Read `backup-meta.json` from the patches directory.
@@ -61,7 +57,7 @@ Exit.
 
 For each file in `backup-meta.json`:
 
-1. **Read the backed-up version** (user's modified copy from `pan-local-patches/`)
+1. **Read the backed-up version** (user's modified copy from `pan-local-patches/<file>`; a file listed in `backup-meta.json`'s `external_files` — a Codex skill under `../.agents/skills/` — is at `pan-local-patches/` + the path that map gives)
 2. **Read the newly installed version** (current file after update)
 3. **Compare and merge:**
 

package/commands/pan/pause.md

@@ -74,7 +74,7 @@ context:
 The workflow handles all logic including:
 1. Phase directory detection
 2. State gathering with user clarifications
-3. Handoff file writing with timestamp — **using the schema from `<handoff_schema>`**
+3. Handoff file writing with timestamp — **using the schema from `<handoff_schema>`, in place of the format in the workflow's write step and `templates/continue-here.md`** (`/pan:resume` parses this schema's fields)
 4. Git commit
 5. Confirmation with resume instructions
 </process>

package/commands/pan/phase-tests.md

@@ -19,7 +19,7 @@ Generate unit and E2E tests for a completed phase, using its summary.md, context
 
 Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
 
-Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from phase-tests command`
 </objective>
 
 <execution_context>
@@ -30,10 +30,11 @@ Output: Test files committed with message `test(phase-{N}): add unit and E2E tes
 Phase: $ARGUMENTS
 
 @.planning/state.md
-@.planning/roadmap.md
+
+This phase's goal and requirements, if the workflow needs them: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice <phase> --raw`, with only the phase number from $ARGUMENTS, since the instructions after it are free text that can break a shell line (the whole roadmap.md only for something it leaves out).
 </context>
 
 <process>
-Execute the add-tests workflow from @~/.claude/pan-wizard-core/workflows/phase-tests.md end-to-end.
+Execute the phase-tests workflow from @~/.claude/pan-wizard-core/workflows/phase-tests.md end-to-end.
 Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
 </process>

package/commands/pan/plan-phase.md

@@ -19,7 +19,7 @@ Create executable phase prompts (plan.md files) for a roadmap phase with integra
 
 **Default flow:** Research (if needed) → Plan → Verify → Done
 
-**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.
+**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.
 </objective>
@@ -38,6 +38,7 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--gaps` — Gap closure mode (reads verification.md, skips research)
 - `--skip-verify` — Skip verification loop
 - `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into context.md automatically. Skips discuss-phase entirely.
+- `--auto` — Autonomous mode: sets `workflow.auto_advance` and asks nothing (with no context.md it plans from the project-level research, requirements and idea.md); after planning it runs `/pan:exec-phase N --auto --no-transition` and, once the phase completes, prints `Next: /pan:discuss-phase <next phase> --auto` and stops.
 
 Normalize phase input in step 2 before any directory lookups.
 </context>
@@ -48,7 +49,7 @@ 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. Maximum 2 revision iterations (plan → check → revise → check → final)
+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
 This prevents over-revision while ensuring real gaps are closed.
 </reflexion_loop>
 
@@ -57,7 +58,7 @@ 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)
 3. Each plan contains: objective, task breakdown with estimates, dependency ordering, and key file links
-4. Research.md exists (unless --skip-research was used)
+4. Research.md exists, unless research was skipped (`--skip-research`, `--gaps`, `workflow.research: false`, or the single-plan lightweight-phase bypass)
 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.
@@ -67,7 +68,7 @@ Planning FAILS if: phase not found in roadmap, or planner agent returns empty/ma
 Avoid these planning anti-patterns:
 ```
 BAD:  Plan has 25 tasks for a single phase → too granular, executor loses context
-GOOD: 5-8 tasks per plan, each with clear scope and testable outcome
+GOOD: 2-3 tasks per plan, each with clear scope and testable outcome (more work means more plans)
 
 BAD:  Task says "Implement the feature" with no file links or acceptance criteria
       → Executor guesses at scope, misses edge cases
@@ -92,7 +93,7 @@ IF --gaps flag is set:
 ELSE IF --prd <file> flag is set:
   → SKIP discuss-phase entirely
   → PARSE PRD file into context.md
-  → SKIP research (PRD provides requirements)
+  → RUN research as usual (step 3.5 writes context.md from the PRD, then continues to step 5)
   → PLAN from parsed requirements
   → VERIFY (unless --skip-verify)
 
@@ -120,23 +121,12 @@ IF --skip-verify:
 ELSE:
   → Spawn pan-plan-checker
   → IF checker PASSES: done
-  → IF checker finds gaps (iteration 1): revise plan, re-check
-  → IF checker finds gaps (iteration 2): final revision, present with caveats
-  → Max 2 revision iterations
+  → 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
 ```
 </routing_decision_tree>
 
-<cache_priming>
-**Before spawning research + planner agents, prime the prompt cache.** All sub-agents spawned within the next 5 minutes hit cached context instead of re-reading project.md / requirements.md / roadmap.md / state.md / standards.md.
-
-Run once per invocation:
-```
-pan-tools cache prime --summary
-```
-
-Returns `{blocks: [{path, bytes, cache}], total_bytes, sha}`. On a host runtime that supports prompt caching (Claude Code does), the host translates these block references into `cache_control: ephemeral`. Where prompt caching is unavailable this is a no-op — nothing breaks.
-</cache_priming>
-
 <process>
 Execute the plan-phase workflow from @~/.claude/pan-wizard-core/workflows/plan-phase.md end-to-end.
 Preserve all workflow gates (validation, research, planning, verification loop, routing).

package/commands/pan/preview.md

@@ -60,7 +60,7 @@ Consolidates Spec B v1's architect + simulate + predict-milestone into one entry
 ```
 
 **What it does:**
-1. `pan-tools preview milestone` returns `{phases_total, completed, remaining, avg_phase_duration_days, eta_date, confidence_pct, bottleneck, sample_size}`.
+1. `pan-tools preview milestone` returns `{current_milestone, phases_total, phases_completed, phases_remaining, avg_phase_duration_days, velocity_phases_per_week, eta_date, confidence_pct, bottleneck, sample_size}`.
 2. Spawn `pan-previewer` with `mode: milestone`.
 3. Agent writes `.planning/milestones/preview-<today>.md` with ETA + confidence + bottleneck + caveats + bottom line.
 

package/commands/pan/profile.md

@@ -10,9 +10,9 @@ allowed-tools:
 ---
 
 <objective>
-Switch the model profile used by PAN agents. Controls which Claude model each agent uses, balancing quality vs token spend.
+Switch the model profile used by PAN agents. Sets the model tier PAN's workflows pass when they spawn an agent (mapped to the detected provider's models), balancing quality vs token spend. `/pan:army` and `pan-conductor` spawn with no model, so the agents they run use their own `model:` pin, else the session model, under every profile.
 
-Routes to the set-profile workflow which handles:
+Routes to the profile workflow which handles:
 - Argument validation (quality/balanced/budget)
 - Downgrade confirmation (quality → balanced → budget requires 'yes')
 - Config file creation if missing
@@ -25,7 +25,7 @@ Routes to the set-profile workflow which handles:
 </execution_context>
 
 <process>
-**Follow the set-profile workflow** from `@~/.claude/pan-wizard-core/workflows/profile.md`.
+**Follow the profile workflow** from `@~/.claude/pan-wizard-core/workflows/profile.md`.
 
 The workflow handles all logic including:
 1. Profile argument validation
@@ -37,7 +37,7 @@ The workflow handles all logic including:
 </process>
 
 <tier_decision_tree>
-**Capability-aware routing** (shipped v2.10.0 — E-7). Even within a single profile, PAN picks a tier per-call based on three hints: context estimate, whether the task needs extended thinking, and whether prompt cache is warm.
+**Capability-aware routing** (shipped v2.10.0 — E-7). `resolveModel` can adjust the profile's tier per call from three hints — context estimate, whether the task needs extended thinking, and whether prompt cache is warm — but only when the caller passes them (`resolve-model <agent> --metadata '{…}'`). No shipped workflow, command or agent passes them, so the tree and the quick guide below describe what a caller's hints would do.
 
 The decision order `resolveModel` applies after the baseline profile pick:
 

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]"
+argument-hint: "[--full] [description]"
 allowed-tools:
   - Read
   - Write

package/commands/pan/remove-phase.md

@@ -28,5 +28,5 @@ Roadmap and state are resolved in-workflow via `init phase-op` and targeted read
 
 <process>
 Execute the remove-phase workflow from @~/.claude/pan-wizard-core/workflows/remove-phase.md end-to-end.
-Preserve all validation gates (future phase check, work check), renumbering logic, and commit.
+Preserve all validation gates (future phase check, work check), renumbering logic, and commit. The removal deletes tracked files, so commit with `--force` once the user has confirmed it: without it `pan-tools commit` refuses any pending deletion (`deleted_files_detected`).
 </process>

package/commands/pan/report.md

@@ -2,7 +2,7 @@
 name: pan:report
 group: Observability
 description: Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report
-argument-hint: "phase <N> | index [--bundle] | all [--out <file>] [--open] [--stdout]"
+argument-hint: "phase <N> [--out <file>] [--open] [--stdout] | index [--out <file>] [--open] [--stdout] [--bundle] | all [--open]"
 allowed-tools:
   - Read
   - Bash
@@ -48,7 +48,7 @@ pan-tools report all        [--open]
 {
   "action": "phase",
   "phase": "03",
-  "path": ".planning/phases/03-auth-sessions/03-report.html",
+  "path": "/abs/path/to/project/.planning/phases/03-auth-sessions/03-report.html",
   "bytes": 16183,
   "status": "complete",
   "written": true,

package/commands/pan/research-phase.md

@@ -2,7 +2,7 @@
 name: pan:research-phase
 group: Phase Lifecycle
 description: Research how to implement a phase (standalone - usually use /pan:plan-phase instead)
-argument-hint: "[phase]"
+argument-hint: "<phase>"
 allowed-tools:
   - Read
   - Bash
@@ -38,7 +38,7 @@ Normalize phase input in step 1 before any directory lookups.
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "$ARGUMENTS")
 ```
 
-Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
+Extract from init JSON: `phase_dir`, `padded_phase`, `phase_slug`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`. `phase_dir` is null when the phase is in the roadmap but has no directory yet: create it (`mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"`) and use that path as `phase_dir`, as discuss-phase does.
 
 Resolve researcher model:
 ```bash
@@ -55,18 +55,19 @@ PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase
 
 ## 2. Check Existing Research
 
-```bash
-ls .planning/phases/${PHASE}-*/research.md 2>/dev/null
-```
+Use `has_research` and `research_path` from INIT.
 
-**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
+**If exists:** Offer: 1) Update research, 2) View existing (`research_path`), 3) Skip. Wait for response.
 
 **If doesn't exist:** Continue.
 
 ## 3. Gather Phase Context
 
-Use paths from INIT (do not inline file contents in orchestrator context):
-- `requirements_path`
+Write this phase's roadmap slice (its section, its dependencies' goals and its requirement lines), then use paths from INIT (do not inline file contents in orchestrator context):
+```bash
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${phase_number}" --write --raw)
+```
+- `slice_path` (from the command above; `requirements_path` if it is empty)
 - `context_path`
 - `state_path`
 
@@ -74,7 +75,7 @@ Present summary with phase description and what files the researcher will load.
 
 ## 4. Spawn pan-phase-researcher Agent
 
-Research modes: ecosystem (default), feasibility, implementation, comparison.
+Research mode: the prompt below names `ecosystem`; pan-phase-researcher defines no modes, so treat it as context, not a switch.
 
 ```markdown
 <research_type>
@@ -100,7 +101,7 @@ Mode: ecosystem
 </objective>
 
 <files_to_read>
-- {requirements_path} (Requirements)
+- {slice_path} (This phase's roadmap and requirements)
 - {context_path} (Phase context from discuss-phase, if exists)
 - {state_path} (Prior project decisions and blockers)
 </files_to_read>
@@ -130,7 +131,7 @@ Before declaring complete, verify:
 </quality_gate>
 
 <output>
-Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-research.md
+Write to: {phase_dir}/{padded_phase}-research.md
 </output>
 ```
 
@@ -147,9 +148,7 @@ Task(
 
 **`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
 
-**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
-
-**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
+**`## RESEARCH BLOCKED`:** Show the blocker and what was attempted, offer: Provide context (then spawn a continuation, step 6), Skip research, Abort.
 
 ## 6. Spawn Continuation Agent
 
@@ -160,7 +159,7 @@ Continue research for Phase {phase_number}: {phase_name}
 
 <prior_state>
 <files_to_read>
-- .planning/phases/${PHASE}-{slug}/${PHASE}-research.md (Existing research)
+- {phase_dir}/{padded_phase}-research.md (Existing research)
 </files_to_read>
 </prior_state>