pan-wizard 2.9.1 → 3.5.0

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>

package/commands/pan/profile.md

@@ -35,3 +35,40 @@ The workflow handles all logic including:
 5. Cost estimation display (relative cost multiplier per profile)
 6. Confirmation display
 </process>
+
+<tier_decision_tree>
+**Opus 4.7 capability-aware routing** (since 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.
+
+The decision order `resolveModel` applies after the baseline profile pick:
+
+```
+Baseline tier (from MODEL_PROFILES[agent][profile])
+        │
+        ▼
+┌─────────────────────────────────────────────┐
+│ context_estimate > 700K tokens?             │── yes ──▶ force reasoning (only 1M-ctx tier)
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+┌─────────────────────────────────────────────┐
+│ needs_thinking AND tier == fast?            │── yes ──▶ upgrade fast → mid
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+┌─────────────────────────────────────────────┐
+│ cache_warm AND !needs_thinking              │── yes ──▶ downgrade mid → fast
+│ AND context_estimate < 50K AND tier == mid  │
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+Final tier → provider-native model name
+```
+
+**Quick guide:**
+- Heavy verification (plan-checker, verifier, integration-checker, reviewer, debugger): `needs_thinking: true` — baseline upgrades fast→mid.
+- Map-codebase single-shot mode on Opus 4.7: `context_estimate > 700K` — forced to reasoning.
+- Routine exec tasks with project.md cached: `cache_warm + small ctx` — mid gets downgraded to fast for a cost win.
+- All rules are additive to the `quality` / `balanced` / `budget` profile you pick here — profile sets the floor, capability hints adjust upward or downward within that floor's band.
+
+**Inspecting routing:** use `pan-tools resolve-model <agent> --metadata '{"context_estimate":900000,"needs_thinking":true}'` to see what tier a given hint set resolves to.
+</tier_decision_tree>

package/commands/pan/review-deep.md

@@ -0,0 +1,128 @@
+---
+name: pan:review-deep
+group: Review
+description: Security audit + cross-reviewer check. OWASP/STRIDE pass by pan-hardener, then pan-meta-reviewer catches what the first pass missed. Writes consolidated deep-review.md.
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<objective>
+Run a deeper review pass on a phase than `pan-reviewer` alone provides. Two new agents:
+
+1. **pan-hardener** — OWASP Top 10 (2025) + STRIDE threat model on files changed in the phase.
+2. **pan-meta-reviewer** — reads both the reviewer's and hardener's output, flags things both missed, disputes overstated severities.
+
+Outputs are merged by `review-deep.cjs` into a single `.planning/reviews/<phase>/deep-review.md` with verdict, coverage stats, and conflict table. An audit entry is published to the `review-handoff` bus channel for traceability.
+
+Consolidates Spec B v1's X-4 (self-review) + X-12 (harden) into a single command.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/review-deep.cjs
+@~/.claude/pan-wizard-core/bin/lib/bus.cjs
+@~/.claude/agents/pan-hardener.md
+@~/.claude/agents/pan-meta-reviewer.md
+</execution_context>
+
+<invocation_modes>
+
+### Standalone
+
+```
+/pan:review-deep 07
+```
+
+Run after `/pan:exec-phase 07` completes. Requires `pan-reviewer` to have already written its review to `.planning/phases/07/review.md` (exec-phase does this automatically).
+
+### Integrated with exec-phase
+
+```
+/pan:exec-phase 07 --deep-review
+```
+
+Runs the normal exec → reviewer pipeline, then auto-invokes this command. Recommended for phases touching auth, payment, PII, migrations, or public APIs.
+
+### Integrated with focus-exec
+
+```
+/pan:focus-exec --deep-review
+```
+
+Per-item deep review during focus campaigns. Useful for high-stakes batches.
+
+</invocation_modes>
+
+<process>
+
+1. **Load reviewer output** — read `.planning/phases/<N>/review.md` written by the earlier `pan-reviewer` step. If missing, warn and offer to run `pan-reviewer` first.
+
+2. **Spawn pan-hardener** (parallel-safe with step 3 isolation below, but recommended sequential for audit clarity):
+   - Prompt includes: `<files_to_read>` with phase plan + diff + reviewer output; `<output_path>` = `.planning/reviews/<N>/hardener.md`; `<framework_scope>` block reminding of OWASP/STRIDE coverage.
+   - Agent writes its findings to the output path, returns confirmation.
+
+3. **Spawn pan-meta-reviewer**:
+   - Prompt includes: `<files_to_read>` with both reviewer.md AND hardener.md (and representative diff snippets); `<output_path>` = `.planning/reviews/<N>/meta.md`.
+   - Agent reads both first-pass reports, identifies missed patterns, disputes overstated severities, writes to output path.
+
+4. **Merge** — call:
+   ```
+   pan-tools review-deep merge <N> \
+     --reviewer-file .planning/phases/<N>/review.md \
+     --hardener-file .planning/reviews/<N>/hardener.md \
+     --meta-file .planning/reviews/<N>/meta.md
+   ```
+   The merger parses all three, sorts by severity, computes verdict (`ok` | `ok_with_minor` | `fix_before_merge` | `review_required` | `block`), writes `.planning/reviews/<N>/deep-review.md`, and publishes an audit record to the `review-handoff` bus channel.
+
+5. **Report back** — echo verdict + finding count + conflict count. If verdict is `block` or `review_required`, recommend the user review `deep-review.md` before proceeding.
+
+</process>
+
+<verdict_semantics>
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| `ok` | No findings at any severity | Merge freely |
+| `ok_with_minor` | Only low/info findings | Merge with noted follow-ups |
+| `fix_before_merge` | Medium findings present | Fix or document before merge |
+| `review_required` | High findings present | Human sign-off required |
+| `block` | At least one critical | Do not merge |
+
+Verdict is driven by the highest-severity finding across all three sources. Meta-reviewer disputes can downgrade severity on specific findings but don't change the headline verdict — the merger trusts the consensus of the explicit severity labels.
+
+</verdict_semantics>
+
+<output_files>
+
+- `.planning/phases/<N>/review.md` — pan-reviewer output (written earlier by exec-phase)
+- `.planning/reviews/<N>/hardener.md` — pan-hardener output (new)
+- `.planning/reviews/<N>/meta.md` — pan-meta-reviewer output (new)
+- `.planning/reviews/<N>/deep-review.md` — merged consolidated report (final deliverable)
+- `.planning/bus/review-handoff.jsonl` — audit trail entry (append-only)
+
+</output_files>
+
+<runtime_compatibility>
+
+| Runtime | hardener | meta-reviewer | merge |
+|---------|----------|---------------|-------|
+| Claude Code | Full, thinking enabled (6000/4000 budget) | Full | Full |
+| OpenCode | Prose "think step-by-step" preamble substitutes for thinking | Same | Full (runtime-agnostic CLI) |
+| Gemini | Same | Same | Full |
+| Codex | Same | Same | Full |
+| Copilot | Same | Same | Full |
+
+The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability — Opus 4.7 with extended thinking produces the richest findings.
+
+</runtime_compatibility>
+
+<calibration_note>
+
+Deep review is opt-in for a reason: it costs roughly 3× a normal review (hardener + meta + merge adds two agent spawns per phase). Use it for high-stakes phases, not every phase. `--deep-review` gating by phase tags is a v3.4 candidate enhancement.
+
+</calibration_note>

package/commands/pan/verify-phase.md

@@ -75,6 +75,17 @@ After initial verification of each requirement:
 This prevents premature FAIL verdicts from incomplete investigation.
 </reflexion_loop>
 
+<cache_priming>
+**Before the verifier agent runs**, prime the prompt cache once. The verifier reads project.md / requirements.md / roadmap.md every run; caching avoids ~15-50K input tokens per invocation.
+
+Run once:
+```
+pan-tools cache prime --summary
+```
+
+See [plan-phase.md](plan-phase.md) or [exec-phase.md](exec-phase.md) for the full explanation. No-op on non-Claude runtimes.
+</cache_priming>
+
 <process>
 Execute the verify-work workflow from @~/.claude/pan-wizard-core/workflows/verify-phase.md end-to-end.
 Preserve all workflow gates (session management, test presentation, diagnosis, fix planning, routing).

package/commands/pan/what-if.md

@@ -0,0 +1,146 @@
+---
+name: pan:what-if
+group: Foresight
+description: Explore a phase's alternative approach in an isolated git worktree. Replays the scenario, compares to the original plan, writes a report.
+argument-hint: "<phase-number> <scenario-text>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Safely explore "what if we had done X instead?" for a phase. Creates an isolated git worktree, spawns `pan-counterfactual` inside it, lets the agent experiment without touching the main tree, collects a structured comparison payload, writes `.planning/counterfactuals/<phase>-<slug>.md` in the main tree, and cleans up the worktree.
+
+Unchanged from Spec B v1's X-9. Already narrow enough to stand alone.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/whatif.cjs
+@~/.claude/agents/pan-counterfactual.md
+</execution_context>
+
+<invocation>
+
+```
+/pan:what-if 7 "Use Redis instead of Memcached"
+/pan:what-if 4 "Skip the migration step entirely"
+/pan:what-if 12 "What if we'd picked NoSQL at the start?"
+```
+
+**Requirements:**
+- Main project must be a git repository (worktrees require git).
+- Working tree can be dirty — worktree is based on current HEAD, your uncommitted changes stay in main.
+
+</invocation>
+
+<process>
+
+### Stage 1 — Prepare
+
+```
+pan-tools whatif prepare <phase> "<scenario text>"
+```
+
+The CLI:
+1. Validates the phase exists.
+2. Slugifies the scenario (lowercase, alphanumerics + hyphens, ≤50 chars).
+3. Creates a git worktree at `<parent-of-cwd>/pan-whatif-<phase>-<slug>-<ts>` on a fresh branch `pan-whatif/<phase>-<slug>-<ts>`.
+4. Returns `{phase, phase_name, scenario, slug, plans, summaries, has_executed, worktree: {worktree_path, branch, base}}`.
+
+If worktree creation fails (not a git repo, dirty tree blocking, etc.), abort with a clear error.
+
+### Stage 2 — Spawn pan-counterfactual
+
+Spawn the agent with its working directory set to `worktree_path`. Prompt includes:
+- `<files_to_read>` — the phase plan, any existing summary, the main project's `CLAUDE.md` so the agent understands conventions.
+- `<scenario>` — the user's scenario text verbatim.
+- `<worktree_path>` — so the agent knows the safe boundary.
+- `<time_budget>` — advisory (10-20 min of reasoning/file-ops).
+
+The agent explores, then returns a JSON payload with `{summary, differences, recommendations, risks, verdict}`.
+
+### Stage 3 — Write report in MAIN tree
+
+Run (from main tree, NOT worktree):
+
+```
+pan-tools whatif report <phase> "<scenario>" --comparison '<agent-json>'
+```
+
+This writes `.planning/counterfactuals/<phase>-<slug>.md`. The file belongs to the main tree and survives worktree cleanup.
+
+### Stage 4 — Cleanup
+
+```
+pan-tools whatif cleanup --worktree <path> --branch <name> --force
+```
+
+Removes the worktree directory and deletes the counterfactual branch. Best-effort: warnings are surfaced but don't block.
+
+### Stage 5 — Confirm
+
+Echo the report path and verdict to the user. Done.
+
+</process>
+
+<safety>
+
+**Worktree isolation is the safety mechanism.** The agent can edit files freely inside the worktree without affecting the main tree. Git treats worktrees as independent checkouts sharing the same object store.
+
+**The agent is instructed NOT to commit inside the worktree.** Commits would be wasted effort since the worktree is deleted after report generation. The agent contract calls this out explicitly.
+
+**The agent is instructed NOT to push or merge.** No remote-affecting git operations.
+
+**Cleanup is forced.** `--force` on worktree removal ensures even a worktree with uncommitted changes gets cleaned up. The report is the permanent artifact; the worktree is disposable.
+
+**If cleanup fails**, the worktree and branch remain. Re-run `pan-tools whatif cleanup` with the same args, or clean up manually:
+
+```
+git worktree remove --force <worktree_path>
+git branch -D <branch_name>
+```
+
+</safety>
+
+<output_paths>
+
+- `.planning/counterfactuals/<phase>-<slug>.md` — the comparison report (permanent)
+- `<parent>/pan-whatif-<phase>-<slug>-<ts>/` — the worktree (temporary, deleted after report)
+- branch `pan-whatif/<phase>-<slug>-<ts>` — the worktree's branch (deleted after report)
+
+Filename + branch include a timestamp so running what-if multiple times on the same phase+scenario produces distinct reports without overwriting.
+
+</output_paths>
+
+<runtime_compatibility>
+
+| Runtime | Support |
+|---------|---------|
+| Claude Code | Full — worktree + agent + report |
+| OpenCode | Partial — worktree + report work; agent spawn depends on runtime's task support |
+| Gemini CLI | Partial — same caveat |
+| Codex CLI | Partial — same caveat |
+| Copilot CLI | Partial — same caveat |
+
+The worktree and report layers are pure Node.js + git and work everywhere git is available. The agent orchestration varies by runtime's task-spawning capabilities. On any runtime that can't spawn an agent, the user can manually explore in the worktree and run `pan-tools whatif report` with a handwritten comparison JSON.
+
+</runtime_compatibility>
+
+<when_to_use>
+
+**Use `/pan:what-if` when:**
+- You're debating a decision mid-milestone and want to sample the alternative without rebuilding
+- A phase is complete and you want to retrospectively compare approaches
+- A reviewer asks "why not X?" and you want a structured answer
+
+**Skip `/pan:what-if` when:**
+- The alternative is trivially decidable from reading the plan (don't spawn an agent)
+- You're already committed and the exploration is sunk-cost sympathy
+- The main tree has massive uncommitted changes you don't want reflected in the worktree's base
+
+</when_to_use>

package/hooks/dist/pan-cost-logger.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// PAN cost logger — SubagentStop hook (v3.4+).
+//
+// Claude Code fires SubagentStop when a Task-spawned sub-agent finishes.
+// The hook receives JSON on stdin describing the session, transcript path,
+// and (when available) usage metadata.
+//
+// We append a minimal record to .planning/metrics/tokens.jsonl so
+// `/pan:cost` reports reflect real agent spawns, not just manually-appended
+// entries. Token counts are best-effort: if the hook input doesn't carry
+// them, we log a record with zeros + a `source: "hook"` flag so the
+// aggregator distinguishes these from fully-instrumented records.
+//
+// This hook NEVER blocks the main agent loop — all errors are swallowed.
+
+const fs = require('fs');
+const path = require('path');
+
+const METRICS_DIR = 'metrics';
+const TOKENS_FILE = 'tokens.jsonl';
+
+/**
+ * Extract what we can from the SubagentStop event payload.
+ * Pure function — safe to test without stdin.
+ *
+ * @param {Object} data - Parsed SubagentStop event JSON
+ * @param {string} cwd - Project cwd (for path resolution)
+ * @returns {Object|null} Cost record, or null if the event should be ignored
+ */
+function buildCostRecord(data, cwd) {
+  if (!data || typeof data !== 'object') return null;
+
+  // Only log actual subagent stops; ignore other Stop variants.
+  if (data.hook_event_name && data.hook_event_name !== 'SubagentStop') return null;
+
+  const record = {
+    ts: new Date().toISOString(),
+    agent: data.agent_type || data.subagent_type || null,
+    command: null,
+    model: data.model || null,
+    tier: null,
+    input_tokens: extractNumber(data.usage, 'input_tokens') || 0,
+    output_tokens: extractNumber(data.usage, 'output_tokens') || 0,
+    cache_read_tokens: extractNumber(data.usage, 'cache_read_input_tokens') || 0,
+    cache_write_tokens: extractNumber(data.usage, 'cache_creation_input_tokens') || 0,
+    cost_usd: null,
+    phase: data.phase || null,
+    session: data.session_id || null,
+    source: 'hook',
+  };
+
+  return record;
+}
+
+function extractNumber(obj, key) {
+  if (!obj || typeof obj !== 'object') return 0;
+  const v = obj[key];
+  return typeof v === 'number' ? v : 0;
+}
+
+/**
+ * Append record to .planning/metrics/tokens.jsonl. Silently succeeds
+ * even if the file or directory can't be written — hook must not block.
+ *
+ * @param {string} cwd - Working directory (project root)
+ * @param {Object} record - Cost record from buildCostRecord
+ * @returns {boolean} true if written, false otherwise
+ */
+function appendRecord(cwd, record) {
+  if (!record) return false;
+  try {
+    const dir = path.join(cwd, '.planning', METRICS_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, TOKENS_FILE), JSON.stringify(record) + '\n', 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Stdin driver ───────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => input += chunk);
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      // Prefer cwd from the event (Claude Code sends it in most hook payloads);
+      // fall back to process.cwd() which is the project root when Claude Code
+      // invokes the hook.
+      const cwd = data.cwd || data.workspace?.current_dir || process.cwd();
+      const record = buildCostRecord(data, cwd);
+      appendRecord(cwd, record);
+    } catch {
+      // Silent fail — don't block agent loop on hook errors.
+    }
+  });
+}
+
+module.exports = { buildCostRecord, appendRecord, METRICS_DIR, TOKENS_FILE };