pan-wizard 2.9.0 → 3.4.1

package/commands/pan/assumptions.md

@@ -27,15 +27,50 @@ Phase number: $ARGUMENTS (required)
 Project state and roadmap are loaded in-workflow using targeted reads.
 </context>
 
+<investigate_before_claiming>
+Before surfacing any assumption, read the actual codebase first.
+- Read existing source files related to the phase's domain
+- Grep for relevant function names, imports, patterns
+- Base assumptions on what the code actually shows, not speculation
+Do not claim "the project uses X" without verifying it in the files.
+</investigate_before_claiming>
+
+<citation_requirement>
+Every assumption MUST cite the evidence that supports it.
+
+**Before presenting assumptions to the user, scan your draft for unsourced claims.** Any assumption without file:line evidence is speculation, not a grounded assumption.
+
+**Format:** "Assumption: [claim] — Evidence: [file:line or grep result]"
+
+**Grounding rules:**
+- Technical approach assumptions require: file:line showing the current pattern/framework in use
+- Dependency assumptions require: import/require evidence from the relevant module
+- Scope boundary assumptions require: file paths showing what exists vs what doesn't
+- Risk assumptions require: file:line showing the fragile pattern or grep showing the coupling
+
+**Anti-pattern:**
+```
+BAD:  "Assumption: The project uses Express for routing"
+      → Did you check? Maybe it uses Fastify, or has no server at all.
+GOOD: "Assumption: The project uses Express for routing — Evidence: require('express')
+       at src/server.ts:3, route definitions at src/routes/index.ts:12-45"
+```
+</citation_requirement>
+
 <process>
 1. Validate phase number argument (error if missing or invalid)
 2. Check if phase exists in roadmap
-3. Follow assumptions.md workflow:
+3. Read relevant source files to ground assumptions in evidence
+4. For each assumption, follow observe-think-conclude:
+   - OBSERVE: What does the code show?
+   - THINK: What does this imply for the phase approach?
+   - CONCLUDE: State the assumption with file:line evidence
+5. Follow assumptions.md workflow:
    - Analyze roadmap description
    - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
-   - Present assumptions clearly
+   - Present assumptions clearly with file:line references where applicable
    - Prompt "What do you think?"
-4. Gather feedback and offer next steps
+5. Gather feedback and offer next steps
 </process>
 
 <success_criteria>

package/commands/pan/audit-deployment.md

@@ -38,6 +38,12 @@ If no target directory is provided, ask the user:
 Validate the directory exists before proceeding.
 </step>
 
+<investigate_before_judging>
+Never report a file as missing, broken, or misconfigured without reading it first.
+For every audit check: read the actual file, verify its contents, then state the finding with evidence.
+Do not speculate about file contents based on filenames alone.
+</investigate_before_judging>
+
 <step name="installation_audit">
 **Phase 1 — Installation Integrity Audit**
 

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/debug.md

@@ -49,6 +49,30 @@ If active sessions exist AND no $ARGUMENTS:
 If $ARGUMENTS provided OR user describes new issue:
 - Continue to symptom gathering
 
+## Reasoning Protocol
+
+For each debugging step, follow the observe-think-act pattern:
+1. **OBSERVE** — State what you see (error message, unexpected output, file contents)
+2. **THINK** — Reason about what this means and what to investigate next
+3. **ACT** — Execute one targeted tool call based on the reasoning
+This prevents random exploration and keeps investigation systematic.
+
+## Meta-Prompting: Self-Generated Debug Strategy
+
+After gathering symptoms (step 2), generate your own investigation plan before spawning the debugger:
+
+```
+Given symptoms: "{summary}"
+My debug strategy:
+1. Most likely cause: {hypothesis} → Test by: {specific check}
+2. Second most likely: {hypothesis} → Test by: {specific check}
+3. Long shot: {hypothesis} → Test by: {specific check}
+4. Files to read first: {ordered list, most relevant first}
+5. What would DISPROVE each hypothesis: {falsification criteria}
+```
+
+This self-generated strategy is passed to the pan-debugger agent as part of the prompt, giving it a targeted investigation plan rather than open-ended exploration. The falsification criteria are critical — they prevent the agent from confirming a hypothesis by only looking for supporting evidence.
+
 ## 2. Gather Symptoms (if new issue)
 
 Use AskUserQuestion for each:
@@ -123,9 +147,47 @@ Task(
   - "Manual investigation" - done
   - "Add more context" - gather more symptoms, spawn again
 
+<debug_handoff_schema>
+Debug session files (`.planning/debug/{slug}.md`) MUST contain structured state for cross-agent handoff:
+
+```yaml
+# Required sections in debug session file
+session: "{slug}"
+status: "investigating | root-cause-found | fix-applied | resolved"
+created: "{ISO-8601}"
+updated: "{ISO-8601}"
+
+symptoms:
+  expected: "{what should happen}"
+  actual: "{what happens instead}"
+  errors: "{error messages}"
+  reproduction: "{steps to reproduce}"
+
+investigation:
+  hypotheses_tested:
+    - hypothesis: "{what we thought}"
+      result: "confirmed | eliminated"
+      evidence: "{file:line or command output}"
+  hypotheses_remaining:
+    - "{what still needs checking}"
+
+root_cause:                          # Populated when found
+  description: "{what's actually wrong}"
+  evidence: "{file:line proof}"
+  confidence: "high | medium | low"
+
+fix:                                 # Populated when applied
+  files_changed: ["{paths}"]
+  approach: "{what was done}"
+  tests_added: ["{test paths}"]
+```
+
+**Why structured:** Each continuation agent starts with 0 context. Without structured state, it re-reads the entire investigation log and may re-test eliminated hypotheses. With structured state, it reads `hypotheses_tested` (skip these), checks `hypotheses_remaining` (do these next), and picks up exactly where the previous agent stopped.
+</debug_handoff_schema>
+
 ## 5. Spawn Continuation Agent (After Checkpoint)
 
-When user responds to checkpoint, spawn fresh agent:
+When user responds to checkpoint, spawn fresh agent with the structured debug state:
 
 ```markdown
 <objective>
@@ -134,7 +196,7 @@ Continue debugging {slug}. Evidence is in the debug file.
 
 <prior_state>
 <files_to_read>
-- .planning/debug/{slug}.md (Debug session state)
+- .planning/debug/{slug}.md (Debug session state — parse structured sections)
 </files_to_read>
 </prior_state>
 
@@ -146,6 +208,13 @@ Continue debugging {slug}. Evidence is in the debug file.
 <mode>
 goal: find_and_fix
 </mode>
+
+<handoff_instructions>
+1. Parse the debug file's structured sections (symptoms, investigation, root_cause, fix)
+2. Do NOT re-test hypotheses marked "eliminated" — they are dead ends
+3. Start from hypotheses_remaining or the checkpoint's next action
+4. Update the debug file's structured sections as you progress
+</handoff_instructions>
 ```
 
 ```

package/commands/pan/exec-phase.md

@@ -27,6 +27,32 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 @~/.claude/pan-wizard-core/references/ui-brand.md
 </execution_context>
 
+<completion_contract>
+Execution is complete when ALL conditions are met:
+1. Every plan in the phase has been dispatched to a subagent
+2. All subagents have returned (success or failure)
+3. Full test suite passes with count >= pre-execution baseline
+4. All verified tasks committed with accurate commit messages
+5. state.md updated with phase progress
+6. Failed tasks (if any) logged with error classification and root cause
+
+Execution FAILS if: test count drops below baseline after all retries, or state corruption is detected.
+</completion_contract>
+
+<wave_dependencies>
+Discovery → Baseline: Test baseline MUST be captured before any wave executes (regression detection requires it)
+Baseline → Wave N: Each wave MUST wait for the previous wave to complete and pass verification
+Wave N → Commit N: Wave changes MUST pass tests before committing (don't commit broken code)
+All Waves → Final Verify: Full test suite MUST pass after all waves complete
+Final Verify → State Update: state.md MUST only be updated after verification passes
+
+HARD STOP conditions (do not proceed to next wave):
+- Baseline capture fails (test suite broken before we start) → STOP, report to user
+- Wave N test count drops below baseline after 3 retries → revert wave, mark all wave tasks FAILED, continue to next wave
+- State corruption detected (malformed state.md or plan files) → STOP execution entirely, report to user
+- All waves complete but final test count < baseline → revert last wave, re-verify
+</wave_dependencies>
+
 <context>
 Phase: $ARGUMENTS
 
@@ -35,11 +61,90 @@ 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>
 
+<action_gating>
+Each execution stage has a restricted set of appropriate actions. Using the wrong tool at the wrong stage causes regressions.
+
+| Stage | Read | Grep/Glob | Edit/Write | Bash (tests) | Bash (git) | Agent |
+|-------|------|-----------|------------|--------------|------------|-------|
+| Discovery (find plans) | YES | YES | NO | NO | NO | NO |
+| Baseline capture | YES | NO | NO | YES | YES | NO |
+| Wave execution | YES | YES | YES | YES | NO | YES |
+| Wave verification | YES | YES | NO | YES | NO | NO |
+| Wave commit | NO | NO | NO | NO | YES | NO |
+| Final verification | YES | YES | NO | YES | NO | NO |
+| State update | YES | NO | YES | NO | YES | NO |
+
+**Key constraints:**
+- Discovery: read-only — do not modify files while figuring out what to execute
+- Baseline: run tests + git status only — no code changes before baseline is captured
+- Wave verification: NO Edit/Write — you are checking work, not doing more work
+- 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).
+
+**Context Management Across Waves:**
+- KEEP: Phase goals, test baseline, current wave tasks, file paths being modified
+- SUMMARIZE: Completed wave results to one-line summaries
+- DISCARD: Raw tool output from previous waves
+
+**Attention Anchor — emit after each wave completes:**
+```
+Wave {N}/{total} complete | Tasks: {done}/{total} | Tests: {baseline} → {current}
+Remaining waves: {list of wave numbers with task counts}
+Next: Wave {N+1} — {task count} tasks [{task IDs}]
+```
+This prevents drift in multi-wave phases where the agent loses track of which waves remain and what the test baseline was.
+
+**State Intent Before Implementing (M+ tasks):**
+For each STANDARD or FULL task, state before coding: "I will modify [files], adding [what], to achieve [goal]. Risk: [what could break]."
+
+**Pre-Commit Verification Checklist — apply before each wave commit:**
+1. Every modified file was read before editing
+2. `git diff --stat` contains only files related to the current wave's tasks
+3. Test suite passes and count meets or exceeds pre-wave baseline
+4. Commit message lists only tasks that are verified (tests ran, tests passed)
+5. No secrets or credentials staged
+
+If any check fails: fix and re-verify before committing.
+
+**Error Recovery Classification — apply when any task fails:**
+- RECOVERABLE (retry up to 3 times): test failure after code change, build syntax error, file not found (search for moved path)
+- UNRECOVERABLE (mark task FAILED, continue to next): same failure after 3 retries, permission errors, state corruption, unrelated test regression
+Never let a failed task block the rest of the wave.
+
+**Anti-Overengineering:**
+Implement exactly what the plan says. Do not add features, refactor surrounding code, add comments to unchanged files, or create abstractions for one-time operations.
+
+**Common Anti-Patterns (avoid these):**
+```
+BAD:  Task says "add input validation" → you also refactor the error handler, add logging, and rename variables
+      → 3 unrelated changes pollute the diff, risk regressions in untested paths
+GOOD: Add validation only → commit → let the next task handle error handling if planned
+
+BAD:  Test fails → change the test's expected output to match the broken code
+      → Bug is now hidden, passes CI, breaks in production
+GOOD: Test fails → read the test intent → fix the code to match the expected behavior
+```
 </process>