pan-wizard 3.31.0 → 3.32.0

package/README.md

@@ -105,16 +105,16 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 
 **Run it over days.** `--schedule` arms a resumable campaign with a per-day budget that burns the backlog down across sessions (the per-day budget is advisory unless the schedule is armed with `--enforce-budget`, which pauses the day's run once spent — `campaign status` shows the day's spend — and an external scheduler triggers each `--continue`) — and *still* waits for you at every merge. **Autonomy runs up to the irreversible step; a human is at the step.**
 
-**Watch it live.** `/pan:hud` renders a single self-contained HTML dashboard — Mission Control over the squads, in-flight worktrees, campaign budget, telemetry, and the safety harness — in one page.
+**See it.** `/pan:hud` renders a single self-contained HTML snapshot — Mission Control over the squads, in-flight worktrees, campaign budget, telemetry, and the safety harness — in one page. The page does not refresh itself; re-run the command for a fresh one.
 
 ```bash
 /pan:army "ship the v1 reporting module"     # plan → delegate → build → review → human-gated ship
 /pan:army "harden auth across the app" --schedule daily --daily-budget 200
 /pan:army --status        # where the campaign stands
-/pan:hud --open           # watch the army work, live
+/pan:hud --open           # snapshot of the army's current state
 ```
 
-Resolve the live squad roster any time with `pan-tools squad list`.
+Resolve the live squad roster any time with `pan-tools squad list` (`pan-tools` is shorthand; see [Operations](#operations) for how to run it).
 
 ---
 
@@ -142,7 +142,7 @@ Verify with:
 
 ### Staying Updated
 
-PAN evolves fast. Update periodically:
+PAN evolves fast. On Claude Code, update periodically with `/pan:update`, which detects whether the install is local or global but passes no other flag, so it always updates Claude Code in its default location. For any other runtime, or an install made with `--config-dir` or `--unified-skills`, re-run the installer yourself with the flags you installed with (add `--global` for a global install, since the installer defaults to the current project):
 
 ```bash
 npx pan-wizard@latest
@@ -163,8 +163,8 @@ npx pan-wizard --opencode --global # Install to ~/.config/opencode/
 npx pan-wizard --gemini --global   # Install to ~/.gemini/
 
 # Codex (skills-first)
-npx pan-wizard --codex --global    # Skills to ~/.agents/skills/, core and hooks to ~/.codex/
-npx pan-wizard --codex --local     # Skills to ./.agents/skills/, core and hooks to ./.codex/
+npx pan-wizard --codex --global    # Skills to ~/.agents/skills/, core, agents and hooks to ~/.codex/
+npx pan-wizard --codex --local     # Skills to ./.agents/skills/, core, agents and hooks to ./.codex/
 
 # GitHub Copilot CLI (skills-first)
 npx pan-wizard --copilot --global  # Install to ~/.copilot/
@@ -175,7 +175,7 @@ npx pan-wizard --all --global      # Install to all directories
 ```
 
 Use `--global` (`-g`) to install into your home config directory; `--local` (`-l`) is the default and may be omitted.
-Use `--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, or `--all` to skip the runtime prompt.
+Use `--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, or `--all` to skip the runtime prompt. A local install also writes outside the runtime directory: a marker-fenced PAN section in the project's `AGENTS.md`; for Claude Code, an `@AGENTS.md` import in `CLAUDE.md` and a `pan` MCP server in `.mcp.json`; and for Codex or `--unified-skills`, the shared `.agents/` tree (skills, plus a shared core under `--unified-skills`). `--uninstall` removes them (the `AGENTS.md` and `CLAUDE.md` blocks and the `.agents/` tree stay while another PAN runtime in the project still uses them).
 Add `--unified-skills` to install commands as one shared `.agents/skills/` tree instead of per-runtime formats. Codex, Gemini CLI, OpenCode, Copilot CLI and Antigravity CLI read that tree; Claude Code does not, so for Claude the installer also copies each skill into `.claude/skills/` and the commands become `/pan-<name>`. Gemini CLI gives skills no slash command, so on a unified Gemini install you ask for the task and `/skills list` shows what loaded. See the User Guide for details.
 
 > **Gemini CLI note:** from June 18, 2026, Google's Gemini CLI serves Gemini Code Assist (Standard/Enterprise) customers; individual free / AI Pro / Ultra accounts are directed to Antigravity CLI instead. PAN's `--gemini` target installs for Gemini CLI. Antigravity CLI is not yet a PAN install target, but it reads the shared `.agents/skills/` tree natively — install with `--unified-skills` and PAN's commands are usable from Antigravity in the same project.
@@ -190,8 +190,10 @@ directory. The installer hard-refuses to install into its own source repo (a
 `PAN_SOURCE_ROOT` guard exits with an error), so point it at a different target:
 
 ```bash
-# 1. Get the source
+# 1. Get the source and build the hooks (hooks/dist/ is build output a clone lacks;
+#    the installer copies the hooks from there)
 git clone https://github.com/oharms/PanWizard.git
+cd PanWizard && npm run build:hooks
 
 # 2. Install into a DIFFERENT project directory (never the PanWizard source dir)
 cd /path/to/some-test-project
@@ -346,7 +348,7 @@ The system:
 
 Each plan is small enough to execute in a fresh context window. No degradation, no "I'll be more concise now."
 
-**Creates:** `{phase_num}-research.md`, `{phase_num}-{N}-plan.md`
+**Creates:** `{phase_num}-research.md`, `{phase_num}-{N}-plan.md`, `{phase_num}-plan-check.md` (the checker's report, when the checker runs)
 
 ---
 
@@ -397,7 +399,7 @@ Plans are grouped into "waves" based on dependencies. Within each wave, plans ru
 
 This is why "vertical slices" (Plan 01: User feature end-to-end) parallelize better than "horizontal layers" (Plan 01: All models, Plan 02: All APIs).
 
-**Creates:** `{phase_num}-{N}-summary.md`, `{phase_num}-verification.md`
+**Creates:** `{phase_num}-{N}-summary.md`, `{phase_num}-review.md` (unless `--skip-review` or `--fast`), `{phase_num}-verification.md`
 
 ---
 
@@ -481,7 +483,7 @@ PAN handles it for you:
 
 | File | What it does |
 |------|--------------|
-| `project.md` | Project vision, always loaded |
+| `project.md` | Project vision, read when PAN plans, researches or resumes work |
 | `research/` | Ecosystem knowledge (stack, features, architecture, pitfalls) |
 | `requirements.md` | Scoped v1/v2 requirements with phase traceability |
 | `roadmap.md` | Where you're going, what's done |
@@ -522,7 +524,7 @@ Every stage uses the same pattern: a thin orchestrator spawns specialized agents
 | Research | Coordinates, presents findings | Parallel researchers investigate stack, features, architecture and pitfalls |
 | Planning | Validates, manages iteration | Planner creates plans, checker verifies, up to three passes |
 | Execution | Groups into waves, tracks progress | Executors implement in parallel, each in a fresh context (native sub-agents on Claude Code, each runtime's own delegation elsewhere) |
-| Verification | Presents results, routes next | Verifier checks codebase against goals, debuggers diagnose failures |
+| Verification | Presents results, routes next | Verifier checks codebase against goals; on Claude Code, `/pan-diagnose-issues` sends one debugger per failed UAT truth |
 
 The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
 
@@ -613,7 +615,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 |---------|--------------|
 | `/pan:progress` | Where am I? What's next? |
 | `/pan:hud` (alias `/pan:dashboard`) | Render a self-contained HTML dashboard of project + bot-army state to `.planning/hud.html` (`--open`, `--out`, `--stdout`) |
-| `/pan:report phase <N> \| index \| all` | Self-contained HTML report for one phase, or a timeline index linking every phase report (`--out`, `--open`, `--stdout`; `--bundle` on `index` inlines every phase report into one file) |
+| `/pan:report phase <N> \| index \| all` | Self-contained HTML report for one phase, or a timeline index linking every phase report (`--out`, `--open`, `--stdout` on `phase` and `index`; `--bundle` on `index` inlines every phase report into one file; `all` regenerates every phase report plus the index and takes only `--open`) |
 | `/pan:help` | Show all commands and usage guide |
 | `/pan:update` | Update PAN with changelog preview |
 | `/pan:discord` | Join the PAN Discord community |
@@ -657,7 +659,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:todo-check` | List pending todos |
 | `/pan:debug [desc]` | Systematic debugging with persistent state |
 | `/pan:quick [--full]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification) |
-| `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` auto-fixes detected issues |
+| `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` fixes the issues it marks repairable |
 | `/pan:hygiene [--apply] [--trace-age-days N] [--all-tracks]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat, poisoned cost ledgers, trace and report debris, cached-context bloat, fragment planning dirs); `--apply` executes the safe fixes — poisoned ledgers are quarantined by rename (only the newest quarantine copy is kept), and settled `state.md` history is archived rather than dropped |
 | `/pan:links [--strict]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027) |
 | `/pan:phase-tests <N> [instructions]` | Generate tests for a completed phase based on UAT criteria |
@@ -670,6 +672,8 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 ### Operations
 
+`pan-tools` is shorthand for `node .claude/pan-wizard-core/bin/pan-tools.cjs`; the installer adds no `pan-tools` command to your PATH. Use your runtime's directory in place of `.claude` (`.codex`, `.gemini`, `.opencode`, `.github`), or its global config directory after a `--global` install.
+
 | Command | What it does |
 |---------|--------------|
 | `pan-tools preflight [target]` | Pre-flight validation: state, blockers, git clean, config, error patterns |
@@ -687,7 +691,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:focus-plan` | Create capacity-budgeted execution batch (modes: bugfix, balanced, features, full) |
 | `/pan:focus-exec` | Execute items from batch with tier-based test cadence |
 | `/pan:focus-auto` | Continuous scan→plan→exec loop with purpose-driven categories and a layered safety harness |
-| `/pan:focus-sync` | Detect and report stale documentation counts |
+| `/pan:focus-sync` | Detect stale documentation (counts, missing commands, outdated references); `--all` also fixes it |
 | `/pan:focus-design` | Multi-phase strategic feature investigation pipeline |
 | `/pan:focus-drift-walking` | Walk project tree, detect doc-code drift, score severity, auto-repair |
 | `/pan:focus-doc-audit` | Multi-dimensional document audit with a quality score per dimension |
@@ -697,7 +701,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | Command | What it does |
 |---------|--------------|
 | `/pan:cost` | Token usage + estimated cost across PAN invocations (json/table/chart) |
-| `/pan:preview <phase\|phases\|milestone>` | Read-only foresight: blast radius, dependency graph, milestone ETA |
+| `/pan:preview phase <N>\|phases\|milestone` | Read-only foresight: blast radius, dependency graph, milestone ETA |
 | `/pan:review-deep <phase>` | Security audit (OWASP + STRIDE) + cross-check by meta-reviewer |
 | `/pan:knowledge {ask\|discuss\|playbook}` | Grounded Q&A, multi-turn discussion, or aggregate memory into playbook |
 | `/pan:what-if <phase> "scenario"` | Counterfactual phase replay in isolated git worktree |
@@ -708,7 +712,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | Command | What it does |
 |---------|--------------|
 | `/pan:learn` | Analyze trace events, generate optimization report with auto-apply block |
-| `/pan:optimize {apply\|list\|stats\|trace}` | Apply optimizer recommendations, list reports, view stats, manage trace sessions |
+| `/pan:optimize {apply\|revert\|list\|stats\|trace}` | Apply optimizer recommendations, undo one apply (`revert <apply_id>` or `revert --last`), list reports, view stats, manage trace sessions |
 | `/pan:git <subcommand>` | Phase-aware git workflow: commit/branch/push/status/log/stash/diff/rollback/tag/sync |
 | `/pan:audit-deployment <target-directory> [--enhancements] [--repair]` | Audit a PAN installation for integrity, project health, and draft enhancement specs |
 
@@ -725,7 +729,7 @@ PAN stores project settings in `.planning/config.json`. Configure during `/pan:n
 | Setting | Options | Default | What it controls |
 |---------|---------|---------|------------------|
 | `mode` | `yolo`, `interactive` | chosen at `/pan:new-project` (`yolo` is the recommended answer; `--auto` always sets it) | Auto-approve vs confirm at each step |
-| `depth` | `quick`, `standard`, `comprehensive` | chosen at `/pan:new-project` (usually `standard`) | Planning thoroughness (phases × plans) |
+| `depth` | `quick`, `standard`, `comprehensive` | chosen at `/pan:new-project` (`--auto` uses `quick` unless the idea document's frontmatter sets `planning_depth`) | Planning thoroughness (phases × plans) |
 
 ### Model Profiles
 
@@ -766,7 +770,7 @@ Use `/pan:settings` to toggle these, or override per-invocation:
 
 | Setting | Default | What it controls |
 |---------|---------|------------------|
-| `parallelization.enabled` | `true` | Run independent plans simultaneously |
+| `parallelization` | `true` | Run independent plans simultaneously |
 | `commit_docs` | `true` | Track `.planning/` in git |
 
 ### Git Branching
@@ -781,7 +785,7 @@ Control how PAN handles branches during execution.
 
 **Strategies:**
 - **`none`** — Commits to current branch (default PAN behavior)
-- **`phase`** — Creates a branch per phase; you merge it yourself (PAN never merges)
+- **`phase`** — Creates a branch per phase; you merge it yourself (the phase workflows never merge it)
 - **`milestone`** — Creates one branch for the entire milestone; you merge it yourself
 
 At milestone completion you merge the milestone branch yourself (`git merge --squash` or `--no-ff`); `/pan:milestone-done <version>` archives and tags but does not merge.
@@ -829,20 +833,20 @@ This prevents Claude from reading these files entirely, regardless of what comma
 
 **Commands not working as expected?**
 - Run `/pan:help` (`/pan-help` on OpenCode, Copilot CLI and unified Claude installs; `$pan-help` on Codex) to verify installation
-- Re-run `npx pan-wizard` to reinstall
+- Re-run `npx pan-wizard` with the flags you installed with (the runtime, `--global`/`--local`, and any `--config-dir` or `--unified-skills`) to reinstall
 
-**Updating to the latest version?**
+**Updating to the latest version?** On Claude Code, run `/pan:update`. For any other runtime, or an install made with `--config-dir` or `--unified-skills`, re-run the installer with the flags you installed with (`--global` for a global install):
 ```bash
 npx pan-wizard@latest
 ```
 
 **Using Docker or containerized environments?**
 
-If file reads fail with tilde paths (`~/.claude/...`), set `CLAUDE_CONFIG_DIR` before installing:
+If Claude Code in the container reads its config from somewhere other than the installing user's `~/.claude`, set `CLAUDE_CONFIG_DIR` to that directory before installing (`--global --config-dir <path>` does the same):
 ```bash
 CLAUDE_CONFIG_DIR=/home/youruser/.claude npx pan-wizard --global
 ```
-This ensures absolute paths are used instead of `~` which may not expand correctly in containers.
+PAN then installs into that directory and writes its absolute path into the installed commands, agents and hook commands. A global install writes absolute paths whether or not the variable is set.
 
 ### Uninstalling
 

package/agents/pan-design-checker.md

@@ -80,4 +80,22 @@ asserting a gap that forces unnecessary rework.
 check → revise → check → final) — the same guardrail `plan-phase` uses with
 `pan-plan-checker`. On the final iteration, report remaining gaps as caveats
 rather than blocking indefinitely.
+
+**Machine verdict (required).** End the verdict with a `pan-verdict` block. The
+contract is in `~/.claude/pan-wizard-core/references/verdict-contract.md`. How to fill it:
+- `verdict` is `PASS` or `GAPS`, and `outcome` is `pass` or `fail`.
+- Add one finding per gap, in your ranked order.
+- The class follows the dimension: requirement coverage → `missing`, architecture
+  conformance → `contradicts`, threat coverage → `risk`, scope discipline →
+  `unrequested`, every other dimension → `partial`.
+- Each gap is `high`. A gap you report as a caveat on the final iteration is `medium`.
+- `where` is the design section.
+
+The orchestrator records the block, so it must say what your verdict says.
+
+````markdown
+```pan-verdict
+{"contract":"1.0","agent":"pan-design-checker","phase":"{phase}","verdict":"GAPS","outcome":"fail","findings":[{"class":"missing","severity":"high","where":"{phase}-design.md#requirements","summary":"REQ-12 (export to CSV) maps to no design element"}]}
+```
+````
 </output_contract>

package/agents/pan-optimizer.md

@@ -32,14 +32,18 @@ Read all inputs before producing the report.
 ### Step 1: Load the analysis JSON
 
 Read the `-analysis.json` file. It contains:
-- `summary` — total event counts by type
+- `summary` — total event counts by type, plus `tool_errors`, `spawns_with_tool_errors` / `spawns_measured`, `verdict_failures`, `verdict_retries`
 - `error_patterns` — recurring error categories (sorted by frequency)
+- `tool_error_patterns` — failed tool calls captured from the subagents' own transcripts, grouped by agent, tool, class (`exit_code`, `not_found`, `permission_denied`, …) and message. Each carries `occurrences`, `spawns` and `sessions`, ranked by `spawns`
+- `verdict_stats` — per judge (verifier, plan checker, reviewer, design checker): `pass`, `fail`, `needs_human`, `retries`, `resolved_by_retry`. The findings behind them are in `.planning/findings.jsonl` (`pan-tools findings list`)
 - `gap_patterns` — knowledge gaps the model had to infer
 - `memory_miss_patterns` — topics missing from memory
 - `agent_stats` — per-agent error rates
 - `critical_events` / `major_events` — highest-impact events
 - `raw_events` — the full event stream
 
+**Recurrence before memory.** A tool failure in one spawn is not a lesson: a test run expected to fail (a TDD red step) or a grep with no match exits non-zero on purpose. Write a memory entry only from a `tool_error_patterns` row with `spawns` of 2 or more, and prefer the ones that span `sessions`. The analysis may pool several sessions (`pooled_sessions`, from `pan-tools optimize learn --sessions <n>`); that window is where recurrence shows. A `permission_denied` pattern is an environment finding (the host's permission rules), not an agent's mistake: suggest a note, never a memory entry.
+
 ### Step 2: Read raw trace events
 
 Scan `trace.jsonl` for events. Look for:

package/agents/pan-plan-checker.md

@@ -756,6 +756,13 @@ Return all issues as a structured `issues:` YAML list (see dimension examples fo
 
 <structured_returns>
 
+**Every return ends with a `pan-verdict` block.** The contract is in `~/.claude/pan-wizard-core/references/verdict-contract.md`. How to fill it:
+- `verdict` is `passed` or `issues_found` (the status from Step 10), and `outcome` is `pass` or `fail`.
+- Add one finding per issue you list. Blocker → `high`, warning → `medium`, info → `info`. The class follows the dimension, as mapped in the reference.
+- `where` is the plan file, plus `#task-N` when the issue is about one task.
+
+The orchestrator records the block, and the record is what it branches on. The block must say the same thing as your heading.
+
 ## VERIFICATION PASSED
 
 ```markdown
@@ -782,6 +789,14 @@ Return all issues as a structured `issues:` YAML list (see dimension examples fo
 Plans verified. Run `/pan:exec-phase {phase}` to proceed.
 ```
 
+End it with:
+
+````markdown
+```pan-verdict
+{"contract":"1.0","agent":"pan-plan-checker","phase":"{phase}","verdict":"passed","outcome":"pass","findings":[]}
+```
+````
+
 ## ISSUES FOUND
 
 ```markdown
@@ -813,6 +828,14 @@ Plans verified. Run `/pan:exec-phase {phase}` to proceed.
 {N} blocker(s) require revision. Returning to planner with feedback.
 ```
 
+End it with one finding per listed issue:
+
+````markdown
+```pan-verdict
+{"contract":"1.0","agent":"pan-plan-checker","phase":"{phase}","verdict":"issues_found","outcome":"fail","findings":[{"class":"missing","severity":"high","where":"{phase}-01-plan.md","summary":"requirement AUTH-02 (password reset) has no covering task"},{"class":"risk","severity":"medium","where":"{phase}-02-plan.md","summary":"plan 02 modifies 12 files across 5 tasks; split it"}]}
+```
+````
+
 </structured_returns>
 
 <anti_patterns>

package/agents/pan-reviewer.md

@@ -69,6 +69,10 @@ If a changed file path starts with any of these prefixes, **skip it silently**.
 | Duplicate code | > 10 identical lines across files | INFO |
 | TODO/FIXME/HACK | New instances added in this phase | INFO |
 
+## Scope (unrequested work)
+
+Compare what the changed code does with what the phase's plans asked for (their tasks and `must_haves`). Code that adds behaviour no plan task or requirement mentions is a finding: a feature nobody asked for, an unrelated refactor folded into the change, or an option no requirement needs. Use category `Unrequested` at WARNING, or at ERROR when it changes existing behaviour without a plan saying so. Its class in the `pan-verdict` block is `unrequested`. Supporting code the tasks need (tests, types, wiring) is not a finding.
+
 </review_checks>
 
 <output_format>
@@ -106,6 +110,21 @@ Return a structured review report:
 - **PASS**: Zero errors, zero warnings
 - **PASS_WITH_WARNINGS**: Zero errors, warnings present
 - **NEEDS_FIXES**: Any errors present
+
+**Machine verdict (required).** End the report with a `pan-verdict` block. The contract is in `~/.claude/pan-wizard-core/references/verdict-contract.md`. How to fill it:
+- `verdict` is the word under `### Verdict`; `outcome` is `fail` for NEEDS_FIXES and `pass` otherwise.
+- Add one finding per table row. ERROR → `high`, WARNING → `medium`, INFO → `info`.
+- Category maps to class: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Unrequested → `unrequested`.
+- `where` is `file:line`.
+- A clean review has `"findings": []`.
+
+The orchestrator records this block. It is how your findings reach the phase's findings ledger and `/pan:review-deep`.
+
+````markdown
+```pan-verdict
+{"contract":"1.0","agent":"pan-reviewer","phase":"{phase_number}","verdict":"NEEDS_FIXES","outcome":"fail","findings":[{"class":"quality","severity":"high","where":"src/utils/parser.ts:42","summary":"Inconsistent naming — uses snake_case, project uses camelCase"}]}
+```
+````
 </output_format>
 
 <constraints>

package/agents/pan-verifier.md

@@ -450,6 +450,21 @@ Include in verification report under a "### Standards Compliance" section:
 
 This is advisory only — standards gaps do NOT block verification status. They appear as warnings/info in the report.
 
+## Step 7c: Check Scope — Unrequested Work
+
+Find what the phase changed that no plan asked for. The file list is mechanical; the judgement is yours:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify scope "$PHASE_NUM"
+```
+
+`candidates` are files the phase changed that no plan declared in `files_modified`. The changes come from the phase's plan commits and its summaries' key-files; the planning tree, lockfiles and PAN's own directories are already excluded. Judge each candidate:
+
+- **Supporting work** the declared tasks need is not a finding. That includes a test for a declared file (`hint: test_for_declared`), a fixture, a config entry the feature requires, and a type the declared code imports.
+- **Work the plans' intent does not cover** goes in the frontmatter as an `unrequested:` entry: `path` and `what` (what it adds that nobody asked for). Examples are a feature nobody asked for, an unrelated refactor, or a file outside the phase's purpose. Behaviour counts too: a declared file that also does something no requirement asked for is unrequested work in that file.
+
+Unrequested work never changes the status on its own; a phase can pass with it. Keeping it (a decision) or removing it is the user's call, and the recorded finding is how the call gets made.
+
 ## Step 8: Identify Human Verification Needs
 
 **Always needs human:** Visual appearance, user flow completion, real-time behavior, external service integration, performance feel, error message clarity.
@@ -536,6 +551,9 @@ human_verification: # Only if status: human_needed
   - test: "What to do"
     expected: "What should happen"
     why_human: "Why can't verify programmatically"
+unrequested: # Only if Step 7c found work no plan asked for
+  - path: "src/path/to/file.tsx"
+    what: "What it adds that no plan or requirement asked for"
 ---
 
 # Phase {X}: {Name} Verification Report
@@ -581,6 +599,10 @@ human_verification: # Only if status: human_needed
 
 {Items needing human testing — detailed format for user}
 
+### Unrequested Work
+
+{Files or behaviour no plan asked for (Step 7c), each with what it adds — or "None: every change traces to a plan."}
+
 ### Gaps Summary
 
 {Narrative summary of what's missing and why}
@@ -706,6 +728,7 @@ return <div>No messages</div>  // Always shows "no messages"
 - [ ] Requirements coverage assessed (if applicable)
 - [ ] Anti-patterns scanned and categorized
 - [ ] Human verification items identified
+- [ ] Scope checked with `verify scope`; unrequested work recorded in `unrequested:`
 - [ ] Overall status determined
 - [ ] Gaps structured in YAML frontmatter (if gaps_found)
 - [ ] Re-verification metadata included (if previous existed)

package/commands/pan/design-phase.md

@@ -58,6 +58,14 @@ ELSE (default):
    - If it finds gaps (iteration 1) → `pan-designer` revises (address genuine gaps only), re-check.
    - If it finds gaps (iteration 2) → final revision, record remaining gaps as caveats.
    - **Max 2 revision iterations** (design → check → revise → check → final) — the same guardrail `plan-phase` uses with `pan-plan-checker`.
+   - **Record each check.** Save the checker's returned text verbatim to `{phase_dir}/{padded_phase}-design-check.md` with the Write tool. Record it and branch on the verdict it prints (`PASS` or `GAPS`):
+     ```bash
+     node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase}" --agent pan-design-checker --file "{phase_dir}/{padded_phase}-design-check.md" --raw
+     ```
+     A re-check is the next attempt and closes the gaps it no longer reports. When the final iteration still has gaps, record them as the caveats they are before writing the design:
+     ```bash
+     node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "{phase}" --agent pan-design-checker --open --as deferred --reason "design caveat after 2 revision iterations"
+     ```
 5. **Write** `{phase}-design.md` to the phase directory and commit via `pan-tools commit`.
 6. **Present** results + next step (`/pan:plan-phase` — which will consume this design.md).
 </process>

package/commands/pan/exec-phase.md

@@ -61,7 +61,7 @@ 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.
+- `--deep-review` — After the normal code review, run the deep review inline: the `/pan:review-deep` process, a security audit by pan-hardener plus a cross-check by pan-meta-reviewer, merged into `.planning/reviews/<N>/deep-review.md`. It builds on the normal review, so it is skipped with `--skip-review` or `--fast`. Recommended for phases touching auth, payment, PII, migrations, or public APIs. Costs roughly 3× a normal review.
 - `--hierarchical` (v3.4+, Claude Code only — needs native sub-agent spawning) — Spawn `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns executor/reviewer/verifier sub-agents in sequence. `pan-conductor` runs on the reasoning tier under the default profile, which inherits the model you launched with (the `budget` profile drops it to mid). Bounded by safety harness: max 2 nesting levels, 12 spawns per phase, budget ceiling, `.planning/orchestration/abort` kill-switch. On runtimes that cannot spawn nested agents, 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.

package/commands/pan/git.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 
 <objective>
-Phase-aware git workflow with safety guardrails built in. Every subcommand that modifies history runs safety checks. Rollback uses PAN snapshot tags created by exec-phase.
+Phase-aware git workflow with safety guardrails built in. Every subcommand that modifies history runs safety checks. Rollback uses PAN snapshot tags (`pan-rollback-*`), which `pan-tools rollback-snapshot <phase>` creates; no workflow creates them for you.
 
 Works with any git repository — PAN installation not required.
 </objective>
@@ -185,7 +185,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback --tag pan-rollback
 ```
 
 **Rollback workflow:**
-1. Lists all `pan-rollback-*` tags (created by exec-phase before wave execution)
+1. Lists all `pan-rollback-*` tags (created with `pan-tools rollback-snapshot <phase>`)
 2. Verifies working tree is clean (blocks on dirty tree unless `--dry-run`)
 3. Runs `git reset --hard <tag>`
 

package/commands/pan/learn.md

@@ -18,12 +18,14 @@ Analyze the most recent trace session and generate an optimization report.
 ```
 /pan:learn
 /pan:learn --session <session-id>
+/pan:learn --sessions 3
 /pan:learn --experiment <slug>
 /pan:learn --apply
 ```
 
 **Flags:**
 - `--session <id>` — analyze a specific session instead of the most recent
+- `--sessions <n>` — pool the last n sessions into one analysis, so recommendations rest on failures that recur across runs
 - `--experiment <slug>` *(v3.7.0+, W3)* — analyze a harvested experiment instead of the current project's traces. Reads from `<source-repo>/experiments/<slug>/.planning/optimization/` and writes the report to `<source-repo>/experiments/<slug>/learnings/report-<timestamp>.md`. Used by the self-improvement loop. Run `/pan:experiment harvest <slug>` first.
 - `--apply` — automatically apply safe optimizations after generating the report (equivalent to running `/pan:optimize apply` immediately after)
 

package/commands/pan/optimize.md

@@ -19,6 +19,8 @@ Manage the circular optimization loop: apply recommendations, view stats, list r
 ```
 /pan:optimize apply
 /pan:optimize apply --report <filename>
+/pan:optimize revert <apply_id>
+/pan:optimize revert --last
 /pan:optimize list
 /pan:optimize stats
 /pan:optimize trace init [--description "what you're building"]
@@ -42,7 +44,17 @@ Requires human review (never auto-applied):
 - Workflow step additions
 - Structural changes to commands
 
-After applying, the report lists what was applied and what still needs review.
+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).
+
+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.
+- It refuses a file that a later apply also wrote. Revert that later apply first.
+- It says which files it refused, and why.
+
+A CRLF file comes back CRLF. Applies logged before apply records existed cannot be reverted. After a revert, the same report can be applied again.
 
 ### list
 List all optimization reports in `.planning/optimization/reports/`, most recent first.
@@ -52,7 +64,7 @@ Show cumulative optimization statistics:
 - Total trace sessions run
 - Total events traced
 - Total errors/gaps/redundancies seen
-- Total optimizations applied across all runs
+- 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

package/commands/pan/review-deep.md

@@ -38,7 +38,7 @@ Consolidates Spec B v1's X-4 (self-review) + X-12 (harden) into a single command
 /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).
+Run after `/pan:exec-phase 07` completes. It reads the review that exec-phase's code-review step saved in the phase directory (`.planning/phases/07-<slug>/07-review.md`). The reviewer is read-only, so it is exec-phase that writes the review there.
 
 ### Integrated with exec-phase
 
@@ -46,7 +46,7 @@ Run after `/pan:exec-phase 07` completes. Requires `pan-reviewer` to have alread
 /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.
+Runs the normal exec → reviewer pipeline, then runs this command's process inline, before the verifier. Recommended for phases touching auth, payment, PII, migrations, or public APIs.
 
 ### Integrated with focus-exec
 
@@ -60,7 +60,7 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
 
 <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.
+1. **Load reviewer output.** Resolve the phase with `pan-tools find-phase <N>`, then read `{directory}/{phase_number}-review.md`, which exec-phase's code-review step wrote. If it is missing, warn and offer to run `pan-reviewer` first. Its findings come from the report's closing `pan-verdict` block.
 
 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.
@@ -73,7 +73,7 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
 4. **Merge** — call:
    ```
    pan-tools review-deep merge <N> \
-     --reviewer-file .planning/phases/<N>/review.md \
+     --reviewer-file {directory}/{phase_number}-review.md \
      --hardener-file .planning/reviews/<N>/hardener.md \
      --meta-file .planning/reviews/<N>/meta.md
    ```
@@ -99,7 +99,7 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 
 <output_files>
 
-- `.planning/phases/<N>/review.md` — pan-reviewer output (written earlier by exec-phase)
+- `{phase_dir}/{phase_number}-review.md` — pan-reviewer output (written by exec-phase's code-review step)
 - `.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)

package/hooks/dist/pan-context-monitor.js

@@ -5,7 +5,7 @@
 // context limits (the statusline only shows the user).
 //
 // How it works:
-// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 1. The statusline hook writes metrics to <os tmpdir>/pan-hooks-<uid>/claude-ctx-{session_id}.json
 // 2. This hook reads those metrics after each tool use
 // 3. When remaining context drops below thresholds, it injects a warning
 //    as additionalContext, which the agent sees in its conversation