pan-wizard 2.9.1 → 3.4.1

package/commands/pan/cost.md

@@ -0,0 +1,132 @@
+---
+name: pan:cost
+group: Observability
+description: Show token usage and estimated cost across PAN commands and agents
+argument-hint: "[report|append|clear] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD]"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<objective>
+Report token usage and estimated cost across all PAN invocations in this project.
+
+Reads `.planning/metrics/tokens.jsonl` — an append-only log where each line is one call (agent or command) with token counts and model. Cost is computed from a built-in rate table (overridable via `.planning/config.json` → `cost.rates`).
+
+Default output is JSON for piping. Use `--format table` for human-readable tables or `--format chart` for an ASCII bar chart of daily spend.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/cost.cjs
+</execution_context>
+
+<subcommands>
+
+### `report` (default)
+
+Aggregate all records into totals + breakdowns by agent, command, tier, and day.
+
+```
+pan-tools cost report [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD]
+```
+
+**Flags:**
+- `--format` — `json` (default, for tools) | `table` (aligned text columns) | `chart` (per-day ASCII bars).
+- `--since` — ISO date lower bound (inclusive). Records without `ts` always pass.
+- `--until` — ISO date upper bound (inclusive).
+
+**JSON output shape:**
+```json
+{
+  "totals": {
+    "calls": 42,
+    "input_tokens": 123456,
+    "output_tokens": 4567,
+    "cache_read_tokens": 50000,
+    "cache_write_tokens": 5000,
+    "cost_usd": 2.1234,
+    "cost_unknown": 0
+  },
+  "cache_hit_rate_pct": 40.5,
+  "by_agent": { "pan-planner": { "calls": 8, "input": 50000, ... } },
+  "by_command": { ... },
+  "by_tier": { ... },
+  "by_day": { "2026-04-18": { ... } },
+  "window": { "since": null, "until": null }
+}
+```
+
+### `append`
+
+Append a single cost record. Normally called by instrumented agent spawns; users rarely invoke directly.
+
+```
+pan-tools cost append \
+  [--agent <name>] [--command <name>] [--model <id>] [--tier reasoning|mid|fast] \
+  [--input-tokens N] [--output-tokens N] \
+  [--cache-read-tokens N] [--cache-write-tokens N] \
+  [--phase <num>] [--session <id>]
+```
+
+Missing fields are stored as `null` / `0`. Cost is auto-computed when `model` or `tier` resolves to a known rate.
+
+### `clear`
+
+Delete the cost log. Useful at the start of a billing cycle.
+
+```
+pan-tools cost clear
+```
+
+</subcommands>
+
+<rate_table>
+Default rates (USD per million tokens) as of 2026-04. Override per-model in `.planning/config.json`:
+
+```json
+{
+  "cost": {
+    "rates": {
+      "claude-opus-4-7": { "input": 15.0, "output": 75.0, "cache_read": 1.5, "cache_write": 18.75 },
+      "my-custom-model": { "input": 1.0, "output": 2.0, "cache_read": 0.1, "cache_write": 1.25 }
+    }
+  }
+}
+```
+
+When a record has neither a known model nor a known tier, its cost is `null` and it counts toward `totals.cost_unknown`.
+</rate_table>
+
+<workflow>
+
+**Daily check:** run `/pan:cost --format chart` at the end of a working day to see the spend shape.
+
+**Before shipping:** run `/pan:cost --since 2026-04-01 --format table` to get a total for the billing period.
+
+**After an expensive run:** check `by_agent` and `by_command` to see which stage drove the spend.
+
+**To reconcile with provider bill:** providers report total tokens; PAN's log is append-only and in ISO-8601, so `--since / --until` should match the provider's billing window.
+
+</workflow>
+
+<instrumentation_note>
+
+Token records are written by any caller that knows its usage — typically the host runtime or a wrapper. PAN ships the log format + aggregator (this command); the capture hook itself is opt-in (Wave 5 of Spec B v2). Until then, records can be appended manually via `pan-tools cost append` or by external scripts reading the provider API.
+
+If `.planning/metrics/tokens.jsonl` is empty, `/pan:cost` returns zero totals — the feature is inert, not broken.
+
+</instrumentation_note>
+
+<runtime_compatibility>
+
+| Runtime | Support |
+|---------|---------|
+| Claude Code | Full — data format + aggregation + all output formats |
+| OpenCode | Full aggregator; token capture depends on OpenCode's own hooks |
+| Gemini | Full aggregator; token capture depends on Gemini CLI instrumentation |
+| Codex | Full aggregator; token capture via external script |
+| Copilot CLI | Full aggregator; Copilot doesn't currently expose per-call usage |
+
+The aggregator is runtime-agnostic. What varies across runtimes is how records *get into* `tokens.jsonl` in the first place.
+
+</runtime_compatibility>

package/commands/pan/exec-phase.md

@@ -61,6 +61,8 @@ Phase: $ARGUMENTS
 - `--skip-tests` — Skip automatic test generation after execution completes.
 - `--skip-review` — Skip automatic code review after execution completes.
 - `--fast` — Skip both test generation and code review (implies `--skip-tests --skip-review`).
+- `--deep-review` (v3.4+) — After the normal reviewer step, also run `/pan:review-deep <phase>` (security audit via pan-hardener + cross-check via pan-meta-reviewer). Produces `.planning/reviews/<N>/deep-review.md`. Recommended for phases touching auth, payment, PII, migrations, or public APIs. Costs roughly 3× a normal review.
+- `--hierarchical` (v3.4+, Claude + Opus 4.7 only) — Spawn `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns executor/reviewer/verifier sub-agents in sequence. Bounded by safety harness: max 2 nesting levels, 12 spawns per phase, budget ceiling, `.planning/orchestration/abort` kill-switch. On non-Claude runtimes or older models, this flag is a no-op with a warning and falls back to flat exec. Use only for large phases (≥4 autonomous plans) where wall-clock reduction justifies the ~20-30% orchestration tax.
 
 Context files are resolved inside the workflow via `pan-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
 </context>
@@ -85,6 +87,19 @@ Each execution stage has a restricted set of appropriate actions. Using the wron
 - Wave commit: git operations only — all code changes must be done before committing
 </action_gating>
 
+<cache_priming>
+**Before Discovery, prime the prompt cache once per invocation.** All subagents spawned within the next 5 minutes will hit the cache instead of re-sending the full context.
+
+Run once:
+```
+pan-tools cache prime --summary
+```
+
+This returns `{blocks: [{path, bytes, cache}], total_bytes, sha}` for the cacheable set (project.md, requirements.md, roadmap.md, state.md, standards.md). The `sha` is stable across identical inputs, so repeated calls within the phase hit cached reads.
+
+When spawning subagents for wave execution, include the cacheable block paths in each agent's system-context so the host runtime (Claude Code with Opus 4.7) can mark them `cache_control: ephemeral`. On non-Claude runtimes or older models, this step is a no-op — nothing breaks, just no savings.
+</cache_priming>
+
 <process>
 Execute the execute-phase workflow from @~/.claude/pan-wizard-core/workflows/exec-phase.md end-to-end.
 Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).

package/commands/pan/focus-auto.md

@@ -293,6 +293,24 @@ Between cycles, manage context to prevent quality degradation over long campaign
 
 Display one-line cycle summary: `Cycle N/M | X/Y pts | Z items done | Tests: A -> B`
 
+#### Step 2.5a: Reflection Gate (Opus 4.7 thinking-capable models only)
+
+Before committing to the next cycle, call the reflection helper:
+
+```
+echo '{"run": <run-state>, "cycle": <just-completed-cycle>, "batch": <proposed-next-batch>, "tier": "reasoning"}' \
+  | pan-tools focus reflection
+```
+
+The helper returns `{reflect: true, prompt: "..."}` when the current model tier supports extended thinking. If `reflect: true`, think through the prompt — which asks whether running another cycle is worthwhile given telemetry and remaining items — and respond with JSON: `{"continue": true|false, "rationale": "..."}`.
+
+- If `continue: false`: stop the campaign and treat as a user-reason stop (preserve state, skip to Phase 3).
+- If `continue: true`: proceed to the next cycle.
+
+If the helper returns `reflect: false` (tier doesn't support thinking, or `reflection_enabled: false` in run state, or no next batch): skip this step silently and continue to the next cycle.
+
+The reflection gate catches "zero progress" or "wrong category" drift earlier than the automatic stop rules.
+
 **Attention anchor — emit after every cycle summary:**
 ```
 Remaining: {cycles_left} cycles | {budget_remaining}/{total_budget} pts | Safety: {active_harness_warnings}

package/commands/pan/focus-exec.md

@@ -116,6 +116,7 @@ HARD STOP conditions (do not proceed to next stage):
 - `--dry-run` — Run Stages 1-2 only (show what WOULD be executed)
 - `--no-commit` — Skip the commit step in Stage 6
 - `--continue` — Resume a previously interrupted execution
+- `--deep-review` (v3.4+) — After each high-stakes item's execution, run `/pan:review-deep` for that item (pan-hardener + pan-meta-reviewer security + cross-check). Slows the campaign by roughly 3× per item that triggers the deep pass; use for batches touching auth/payment/migrations.
 
 ---
 
@@ -209,7 +210,8 @@ This catches emergent interactions: 5 "add try-catch" fixes might reveal the mod
 1. **Check Project Status** — git status, recent commits
 2. **Test Baseline** — run test suite, record current counts
 3. **Create rollback snapshot** — git tag for safety
-4. **Report** — Output session start summary
+4. **Prime prompt cache** — `pan-tools cache prime --summary` (once; all sub-agents in the next 5 min hit cached context)
+5. **Report** — Output session start summary
 
 **Record baseline:**
 ```
@@ -243,6 +245,13 @@ Display the execution batch to user, then continue automatically.
 ### 3.0 Pre-Execution Setup
 1. Cache project facts — do NOT re-read later
 2. Create/update progress tracker with the batch table
+3. Classify stages for parallel tool use:
+   ```
+   pan-tools focus classify-stages --raw
+   ```
+   The CLI reads the latest batch and returns `{waves, parallelism_hint}`. When `parallelism_hint` is `emit-micro-in-parallel` or `emit-standard-in-parallel`, all reads and greps for items in the current wave SHOULD be emitted in a single assistant turn (parallel tool calls). Opus 4.7 is markedly better at emitting parallel tool calls than earlier models; use that to collapse Stage 3 latency on MICRO-heavy batches.
+
+   Serialize on `FULL` tier items — each is its own wave.
 
 ### 3.1 Process Items by Tier
 

package/commands/pan/knowledge.md

@@ -0,0 +1,129 @@
+---
+name: pan:knowledge
+group: Knowledge
+description: Grounded Q&A, multi-turn design discussion, and playbook generation. Three modes in one command.
+argument-hint: "ask <question> | discuss <phase> <topic> | playbook"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Retrieve, refine, or consolidate project knowledge. Three modes:
+
+- **ask** — answer a natural-language question with inline citations grounded in `.planning/` + `docs/`.
+- **discuss** — multi-turn refinement of a phase's context. Session state persists across invocations; prompt caching keeps turn 3 cheap.
+- **playbook** — aggregate all agents' memory (E-4 layer) into `.planning/playbook.md`, organized by category (Conventions / Gotchas / Decisions / Tool choices / Anti-patterns / Recurring gaps).
+
+Consolidates Spec B v1's X-3 converse + X-6 teach + X-10 explain into one command.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/knowledge.cjs
+@~/.claude/agents/pan-knowledge.md
+@~/.claude/pan-wizard-core/templates/playbook.md
+</execution_context>
+
+<modes>
+
+### `ask <question>`
+
+```
+/pan:knowledge ask "why does phase 4 have a race condition fix?"
+```
+
+**Flow:**
+1. `pan-tools knowledge ask "<question>"` returns a ranked list of candidate files.
+2. Spawn `pan-knowledge` with `<mode>ask</mode>`, the question, and the top sources as `<files_to_read>`.
+3. Agent reads sources, answers with citations, returns the answer to stdout. No file is written.
+
+**Output:** inline markdown answer with `[file.md:LINE]` and `[ADR-NNNN]` citations.
+
+### `discuss <phase> <topic-or-question>`
+
+```
+/pan:knowledge discuss 12 "should we use Redis or Memcached?"
+```
+
+**Flow:**
+1. `pan-tools knowledge discuss <phase> --subcmd read` loads session state from `.planning/conversations/<phase>/session.json` (empty for new phase).
+2. `pan-tools knowledge discuss <phase> --subcmd append --role user --content "<topic>"` persists the user turn.
+3. Spawn `pan-knowledge` with `<mode>discuss</mode>`, session history, phase context, and the new turn.
+4. Agent responds.
+5. `pan-tools knowledge discuss <phase> --subcmd append --role agent --content "<response>" --cites "a.md,b.md"` persists the response.
+6. If after ≥3 substantive turns the agent offered to emit `context.md`, user can follow up with another `/pan:knowledge discuss <phase>` invocation or run the commit subcommand the agent suggested.
+
+**Session persistence:** `.planning/conversations/<phase>/session.json` — array of turns with ts/role/content/cites. Multi-turn cost is dominated by cache hits on stable `.planning/` files.
+
+### `playbook`
+
+```
+/pan:knowledge playbook
+```
+
+**Flow:**
+1. `pan-tools knowledge playbook` reads all agents' memory (`.planning/memory/*.md`), clusters entries by category, writes `.planning/playbook.md` directly.
+2. Optionally spawn `pan-knowledge` with `<mode>playbook</mode>` to polish (dedupe contradictions, consolidate similar entries). Skip the polish step if the draft looks clean.
+
+**Output:** `.planning/playbook.md` — team-readable summary of accumulated lessons.
+
+**Auto-invocation:** `/pan:milestone-done` can optionally run this (flag-gated, not default). Manual invocation any time.
+
+</modes>
+
+<workflow>
+
+**Onboarding a new team member:** have them run `/pan:knowledge playbook` then `/pan:knowledge ask "what conventions matter in this codebase?"`.
+
+**Design debate:** run `/pan:knowledge discuss <phase> "<question>"` iteratively. The agent refines as the debate narrows. After convergence, accept the proposed `context.md` update.
+
+**Bug investigation:** `/pan:knowledge ask "why did we add the retry in phase 4?"` — faster than grepping for historical context.
+
+**Before milestone-done:** run `/pan:knowledge playbook` to capture what the team learned. Gives contributors something to reference when starting the next milestone.
+
+</workflow>
+
+<citation_format>
+
+Agent output uses bracketed citations that link to files. Supported forms:
+
+| Form | Example | Renders as |
+|------|---------|-----------|
+| Plain file | `[README.md]` | markdown link to the file |
+| File + line | `[docs/ARCHITECTURE.md:200]` | link to line 200 |
+| ADR | `[ADR-0015]` | link to ADR file |
+| Phase artifact | `[phase-4/summary.md]` | link to phase summary |
+
+The agent should NEVER fabricate citations. The retrieval layer's `sources` list is the allowlist.
+
+</citation_format>
+
+<runtime_compatibility>
+
+| Runtime | ask | discuss | playbook |
+|---------|-----|---------|----------|
+| Claude Code | Full, thinking enabled | Full, prompt caching bonus | Full |
+| OpenCode | Full | Full (no cache bonus) | Full |
+| Gemini | Full | Full | Full |
+| Codex | Full | Full | Full |
+| Copilot | Full | Full | Full |
+
+The data layer (retrieval, session state, playbook clustering) is pure Node.js and runtime-agnostic. Only answer synthesis quality varies with model capability.
+
+</runtime_compatibility>
+
+<privacy_note>
+
+`session.json` is persisted to disk and committed unless `.planning/conversations/` is gitignored. For sensitive design discussions, consider:
+
+```
+echo '.planning/conversations/' >> .gitignore
+```
+
+before starting a `discuss` session. Session turns are not auto-encrypted.
+
+</privacy_note>

package/commands/pan/map-codebase.md

@@ -49,6 +49,21 @@ Check for .planning/state.md - loads context if project already initialized
 - Trivial codebases (<5 files)
 </when_to_use>
 
+<stage_0_ingest_mode>
+**Before spawning mapper agents**, determine whether the repo fits in a single 1M-context window.
+
+Run: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs codebase estimate-size --threshold 700000`
+
+The CLI returns `{mode, total_tokens, file_count, languages}`:
+
+- **`mode: "single-shot"`** — repo is small enough (≤700K tokens) for one Opus 4.7 agent to ingest the whole thing. Spawn a single `pan-document_code` agent with the full repo in context. This avoids the 6-way stitching artifacts of sharded mode (contradictory version claims, duplicated mentions, missed cross-file references).
+- **`mode: "sharded"`** — repo exceeds 700K tokens. Fall back to the default 6-way parallel sharding (tech, arch, quality, concerns, relationships, practices). Each shard gets a 200K budget.
+
+Record the chosen mode + telemetry in the final `.planning/codebase/overview.md` so future runs can reason about drift.
+
+Opus 4.7 is required for single-shot mode (only model with a 1M context window). Other models always take the sharded path regardless of size.
+</stage_0_ingest_mode>
+
 <tool_priority>
 Each mapper agent should use the simplest sufficient tool:
 1. Glob — discover files by pattern (find all .ts files, config files, test files)

package/commands/pan/mcp-bridge.md

@@ -0,0 +1,145 @@
+---
+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>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<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.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/bridge.cjs
+</execution_context>
+
+<subcommands>
+
+### `list`
+
+Show cached MCP tools with server grouping and schemas.
+
+```
+/pan:mcp-bridge list
+```
+
+**Output (JSON):**
+```json
+{
+  "cached_at": "2026-04-18T12:34:56Z",
+  "runtime": "claude",
+  "server_count": 3,
+  "tool_count": 12,
+  "tools": [
+    { "server": "linear", "name": "linear.updateTicket", "description": "...", "schema": {...} },
+    ...
+  ],
+  "source": "cache" | "empty"
+}
+```
+
+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.
+
+### `recommend <phase>`
+
+Given a phase number, match cached MCP tools against the phase's plan text and return tools ranked by keyword relevance.
+
+```
+/pan:mcp-bridge recommend 7
+/pan:mcp-bridge recommend 12 --max 5 --min-score 2
+```
+
+**Flags:**
+- `--max N` — cap recommendations (default 10)
+- `--min-score N` — minimum keyword hit count (default 1)
+
+**Output (JSON):**
+```json
+{
+  "phase": "7",
+  "phase_name": "API refactor",
+  "runtime": "claude",
+  "total_candidates": 12,
+  "recommendations": [
+    {
+      "server": "linear",
+      "name": "linear.updateTicket",
+      "description": "Update a Linear issue",
+      "score": 3,
+      "hits": ["linear", "ticket", "update"]
+    }
+  ]
+}
+```
+
+Scoring is naive keyword frequency with word boundaries — not semantic embeddings. A tool's name and description are tokenized into keywords (≥3 chars); each match in the phase plan text scores 1 point.
+
+### `cache`
+
+Write or inspect the MCP tools cache at `.planning/bridge/available-tools.json`.
+
+```
+# Inspect current cache (same as `list` but raw)
+/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.
+
+</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 — `.claude/settings.json` for Claude Code, or the runtime's equivalent.
+
+**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.
+
+**Pre-milestone review:** walk through each remaining phase with `/pan:mcp-bridge recommend` to catch "we should have automated this via Linear/Slack/etc." realizations before shipping.
+
+</workflow>
+
+<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.
+
+**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 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.
+
+</caveats>
+
+<runtime_compatibility>
+
+| 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 |
+
+On non-Claude runtimes, the aggregator and recommendation logic still work — they just report zero tools until something populates the cache.
+
+</runtime_compatibility>
+
+<future_scope>
+
+Explicitly deferred from v3.3 (documented in ADR-0023 / 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.
+
+Until those land, this command is the minimum viable integration: you see what's there, you get suggestions, you decide manually.
+
+</future_scope>

package/commands/pan/plan-phase.md

@@ -124,6 +124,17 @@ ELSE:
 ```
 </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 Claude Code with Opus 4.7, the host runtime translates these block references into `cache_control: ephemeral`. On non-Claude runtimes or older models 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

@@ -0,0 +1,114 @@
+---
+name: pan:preview
+group: Foresight
+description: Preview what will happen — phase blast radius, phase dependency graph, or milestone ETA
+argument-hint: "phase <N> | phases | milestone"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Read-only foresight. Given a phase, a set of phases, or a milestone, produce a structured forecast: what files get touched, which tests might break, which phases can parallelize, when the milestone will actually finish.
+
+Consolidates Spec B v1's architect + simulate + predict-milestone into one entry point with three modes. The data layer (`pan-tools preview …`) extracts structured inputs from `.planning/`; the `pan-previewer` agent analyzes and writes the report. No source code is modified.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/preview.cjs
+@~/.claude/pan-wizard-core/templates/preview-report.md
+</execution_context>
+
+<modes>
+
+### `phase <N>` — Blast radius of one phase
+
+```
+/pan:preview phase 7
+```
+
+**What it does:**
+1. `pan-tools preview phase <N>` returns `{files_mentioned, test_files_mentioned, risk_signals, risk_score, plans[], status}`.
+2. Spawn `pan-previewer` with the payload as `<preview_input>`.
+3. Agent writes `.planning/phases/<N>/preview.md` with files touched / tests at risk / migration steps / risk assessment / bottom line.
+
+**Output:** `.planning/phases/<N>/preview.md`
+
+### `phases` — Cross-phase dependency graph
+
+```
+/pan:preview phases
+```
+
+**What it does:**
+1. `pan-tools preview phases` returns `{phases[], parallel_batches, mermaid, hidden_coupling_count}`.
+2. Spawn `pan-previewer` with `mode: phases` in the payload.
+3. Agent writes `.planning/architecture/dependency-graph.md` with mermaid DAG + parallel batches + hidden-coupling flags.
+
+**Output:** `.planning/architecture/dependency-graph.md`
+
+**Opus 4.7 1M-context bonus:** when the full repo fits in a single agent window, the agent cross-references plan text with actual source imports to catch coupling the frontmatter missed. On smaller-context models, the agent relies on data-layer output alone.
+
+### `milestone` — Completion ETA
+
+```
+/pan:preview milestone
+```
+
+**What it does:**
+1. `pan-tools preview milestone` returns `{phases_total, completed, remaining, avg_phase_duration_days, 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.
+
+**Output:** `.planning/milestones/preview-YYYY-MM-DD.md`
+
+</modes>
+
+<workflow>
+
+**Before committing to a phase:** run `/pan:preview phase <N>` to see blast radius. A `risk_score ≥ 7` or a migration signal on auth files should prompt a review before `/pan:exec-phase`.
+
+**Before committing to a milestone date externally:** run `/pan:preview milestone`. Look at `confidence_pct` and `sample_size`. If sample is <3, don't promise a date.
+
+**Before running phases in parallel:** run `/pan:preview phases`. Parallel batches from the data layer are based on declared `depends_on` only; `hidden_coupling_count > 0` means there are cross-phase references the author should promote to explicit deps before parallelizing.
+
+</workflow>
+
+<process>
+
+For all modes:
+
+1. Run the corresponding `pan-tools preview <mode>` subcommand.
+2. Parse its JSON output.
+3. Spawn `pan-previewer` with a prompt that includes:
+   - `<preview_input>` block carrying the full JSON payload (mode field set explicitly)
+   - `<output_path>` block with the target file path
+   - `<files_to_read>` block with any phase context files the agent should load
+4. Agent writes the report file and returns a short confirmation.
+5. Echo the output path to the user.
+
+The agent does not need workflow context beyond what the data layer provides. Keep spawned-agent prompts lean — the agent's context budget is for reasoning about the structured input, not for loading the whole project.
+
+</process>
+
+<output_contract>
+The command returns the path to the generated preview document. Never paste the report back into conversation output — the file is the deliverable; reference it by path.
+</output_contract>
+
+<runtime_compatibility>
+
+| Runtime | phase | phases | milestone |
+|---------|-------|--------|-----------|
+| Claude Code | Full, thinking enabled | Full, 1M-ctx bonus on Opus 4.7 | Full |
+| OpenCode | Full | Data-layer + simple report | Full |
+| Gemini CLI | Full | Data-layer + simple report | Full |
+| Codex CLI | Full | Data-layer + simple report | Full |
+| Copilot CLI | Full | Data-layer + simple report | Full |
+
+The data layer (`pan-tools preview …`) works identically on all runtimes. What varies is the quality of the agent's synthesis — Opus 4.7 with thinking catches subtler risks than smaller models.
+
+</runtime_compatibility>