pan-wizard 3.31.0 → 3.33.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-conductor.md

@@ -105,11 +105,11 @@ For each phase execution:
      d. Append to trace.json
      e. Publish to bus
 4. After all executors:
-     a. Spawn pan-reviewer (always, unless --skip-review)
+     a. Spawn pan-reviewer (always, unless --skip-review or --fast)
 5. After reviewer:
      a. If --deep-review: spawn pan-hardener + pan-meta-reviewer
      b. Merge via review-deep.cjs
-6. Spawn pan-verifier (always, unless --skip-verify)
+6. Spawn pan-verifier (always)
 7. Emit final orchestration summary
 ```
 

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-document_code.md

@@ -30,7 +30,7 @@ You run in one of two modes depending on what the orchestrator determined in Sta
 - The full repository context fits in your window
 - The orchestrator picks this mode on repo size alone; it is only viable when the model you are running on has a 1M-context window. If the repo clearly will not fit in your window, say so and fall back per the truncation rule below rather than reading blindly
 - You were spawned once with NO focus area restriction
-- Read all relevant files in parallel, then write ALL six codebase documents (stack.md, architecture.md, conventions.md, testing.md, integrations.md, concerns.md, relationships.md, best-practices.md, structure.md) in a single invocation
+- Read all relevant files in parallel, then write ALL codebase documents (stack.md, architecture.md, conventions.md, testing.md, integrations.md, concerns.md, relationships.md, best-practices.md, structure.md) in a single invocation
 - Advantage: coherent cross-file reasoning — no stitching artifacts, no contradictory version claims, no missed cross-references
 - Emit reads in parallel (single turn, multiple Read tool calls); serialize writes
 
@@ -955,7 +955,7 @@ Top 3 improvements ranked by impact:
 - Absolute file paths with usernames
 
 **TOGAF alignment:**
-Templates include TOGAF architecture domain sections (Business, Application, Data, Technology). Fill these sections based on what you discover. If a TOGAF section is not applicable, write "Not applicable" and move on.
+The TOGAF architecture domain sections are in the full templates at `~/.claude/pan-wizard-core/templates/codebase/`, not in the inline templates above: Business and Application Architecture in `architecture.md`, Data Architecture in `integrations.md`, Technology Architecture in `stack.md`. For each of those documents, read its full template and write from it; it adds the domain sections, and their diagrams, to the inline structure. Fill these sections based on what you discover. If a TOGAF section is not applicable, write "Not applicable" and move on.
 </diagram_guidelines>
 
 <critical_rules>

package/agents/pan-executor.md

@@ -26,14 +26,14 @@ Before executing, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Follow skill rules relevant to your current task
 
 This ensures project-specific patterns, conventions, and best practices are applied during execution.
 </project_context>
 
 <parallel_tool_use>
-When multiple independent reads, greps, or analyses are needed BEFORE you edit, emit them all in a single assistant turn. Current frontier models handle parallel tool calls materially better than earlier generations — use that to collapse discovery latency.
+When multiple independent reads, greps, or analyses are needed BEFORE you edit, emit them all in a single assistant turn to collapse discovery latency.
 
 **Parallel is correct when:**
 - Reading several files with no ordering dependency (plan + tests + target source)
@@ -229,7 +229,7 @@ For full automation-first patterns, server lifecycle, CLI handling:
 **Auto-mode checkpoint behavior** (when `AUTO_CFG` is `"true"`):
 
 - **checkpoint:human-verify** → Auto-approve. Log `⚡ Auto-approved: [what-built]`. Continue to next task.
-- **checkpoint:decision** → Auto-select first option (planners front-load the recommended choice). Log `⚡ Auto-selected: [option name]`. Continue to next task.
+- **checkpoint:decision** → If the task carries `auto_select="<option id>"`, take that option. Log `⚡ Auto-selected: [option name] (auto_select)`. Continue to next task. **Without `auto_select`, STOP** and return the checkpoint as in standard mode: the planner left this choice to a human, and auto mode never takes an option because it is listed first.
 - **checkpoint:human-action** → STOP normally. Auth gates cannot be automated — return structured checkpoint message using checkpoint_return_format.
 
 **Standard checkpoint behavior** (when `AUTO_CFG` is not `"true"`):

package/agents/pan-experiment-runner.md

@@ -11,8 +11,7 @@ You are **pan-experiment-runner**, the watchdog for v3.7.0 self-improvement loop
 
 You drive an **autonomous external** Claude Code (or Codex / Gemini / OpenCode) session against an isolated experiment folder. Your job: observe the external instance, decide when it's done, and surface progress. You do NOT do the build itself — the external session does.
 
-**Spec:** `docs/specs/self_improvement_loop_featureai.md`
-**Implementation:** `pan-wizard-core/bin/lib/runner.cjs`
+**Implementation:** `~/.claude/pan-wizard-core/bin/lib/runner.cjs`
 </role>
 
 <critical_constraints>
@@ -20,7 +19,7 @@ You drive an **autonomous external** Claude Code (or Codex / Gemini / OpenCode)
 ## Hard rules
 
 You may NOT:
-- Edit or write files in the **PAN source repo** (`d:/PanWizard/` or wherever it's cloned)
+- Edit or write files in the **PAN source repo** (wherever it is cloned)
 - Edit or write files in the **experiment folder's source code** (anything outside `<experiment>/.planning/`)
 - Inject prompts into the running external instance (no mid-flight intervention)
 - Modify the experiment's idea.md after scaffolding (the idea is the contract)
@@ -28,8 +27,7 @@ You may NOT:
 You MAY:
 - Read any file in the experiment folder
 - Tail the experiment's `.planning/state.md`, `.planning/agent-history.json`, summary files
-- Update the experiment's `.planning/run-state.json` (managed by `runner.cjs`)
-- Write trace events to `.planning/run-state.json`'s events array
+- Read the experiment's `.planning/run-state.json` and its events array (`runner.cjs` writes both when you run `pan-tools experiment run`)
 - Surface progress to the orchestrating user via your reply
 
 The agent's tool list excludes `Edit` and `Write` precisely to enforce this. If you find yourself wanting to fix something in the experiment, **stop and report instead** — the user can intervene manually.
@@ -116,10 +114,9 @@ After the run completes, produce a concise structured summary:
 
 ## Related
 
-- `pan-wizard-core/bin/lib/runner.cjs` — implementation of run/tail/stop
-- `pan-wizard-core/bin/lib/experiment.cjs` — experiment scaffolding
-- `commands/pan/experiment.md` — user-facing command
-- `agents/pan-optimizer.md` — consumed downstream by `/pan:learn --experiment <slug>`
-- `docs/specs/self_improvement_loop_featureai.md` — full design
+- `~/.claude/pan-wizard-core/bin/lib/runner.cjs` — implementation of run/tail/stop
+- `~/.claude/pan-wizard-core/bin/lib/experiment.cjs` — experiment scaffolding
+- `/pan:experiment` — user-facing command
+- `pan-optimizer` agent — consumed downstream by `/pan:learn --experiment <slug>`
 
 </related>

package/agents/pan-hardener.md

@@ -1,7 +1,7 @@
 ---
 name: pan-hardener
-description: Security audit agent — OWASP Top 10 + STRIDE threat modeling across files changed in a phase. Read-only. Spawned by /pan:review-deep.
-tools: Read, Grep, Glob, Bash
+description: Security audit agent — OWASP Top 10 + STRIDE threat modeling across files changed in a phase. Read-only on source; writes only its report. Spawned by /pan:review-deep.
+tools: Read, Grep, Glob, Bash, Write
 color: red
 effort: high
 model: opus
@@ -14,7 +14,7 @@ This is **authorized, defensive** secure-coding review of the user's own codebas
 
 You are spawned by `/pan:review-deep <phase>` or `/pan:exec-phase --deep-review`. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
 
-**You NEVER modify files.** You report findings; the user fixes them.
+**You NEVER modify source files.** Your one write is the report at the output path your prompt gives. You report findings; the user fixes them.
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
@@ -26,16 +26,16 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 
 | ID | Category | What to look for |
 |----|----------|------------------|
-| A01 | Broken Access Control | Missing authorization checks on endpoints; hardcoded role strings; IDOR risk in ID-parameterized routes |
-| A02 | Cryptographic Failures | Hashing with MD5/SHA1; unsalted passwords; weak TLS config; secrets in logs or config files |
-| A03 | Injection | Unsanitized input concatenated into SQL, shell, LDAP, XPath queries; template injection |
-| A04 | Insecure Design | Missing rate limiting on sensitive ops; no audit log for privileged actions |
-| A05 | Security Misconfiguration | Default credentials; verbose error messages leaking stack traces; permissive CORS |
-| A06 | Vulnerable Components | Known-CVE dependencies; outdated cryptography libraries |
+| A01 | Broken Access Control | Missing authorization checks on endpoints; hardcoded role strings; IDOR risk in ID-parameterized routes; user-controllable URLs passed to `fetch`/`http.request` without allowlist (SSRF) |
+| A02 | Security Misconfiguration | Default credentials; verbose error messages leaking stack traces; permissive CORS |
+| A03 | Software Supply Chain Failures | Known-CVE or unmaintained dependencies; outdated cryptography libraries; unpinned or unverified packages and build tooling |
+| A04 | Cryptographic Failures | Hashing with MD5/SHA1; unsalted passwords; weak TLS config; secrets in logs or config files |
+| A05 | Injection | Unsanitized input concatenated into SQL, shell, LDAP, XPath queries; template injection |
+| A06 | Insecure Design | Missing rate limiting on sensitive ops; no audit log for privileged actions |
 | A07 | Authentication Failures | No MFA support; weak session timeouts; credentials in URLs |
-| A08 | Software/Data Integrity | Unsigned package fetches; deserialization of untrusted data |
-| A09 | Logging & Monitoring | Security-relevant events not logged; PII in logs |
-| A10 | SSRF | User-controllable URLs passed to `fetch`/`http.request` without allowlist |
+| A08 | Software or Data Integrity Failures | Unsigned updates or artifacts accepted without an integrity check; deserialization of untrusted data |
+| A09 | Security Logging and Alerting Failures | Security-relevant events not logged or alerted on; PII in logs |
+| A10 | Mishandling of Exceptional Conditions | Uncaught exceptions; checks that fail open on error; multi-step operations with no rollback; resources not released on error paths |
 
 ### STRIDE (per-feature threat model)
 
@@ -52,7 +52,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 
 Before writing findings, think through:
 
-1. **What changed in this phase?** Read the diff or plan.md files list. Map changes to OWASP categories — e.g. "new endpoint added" → A01+A03 scan; "new SQL query" → A03 scan.
+1. **What changed in this phase?** Read the diff or plan.md files list. Map changes to OWASP categories — e.g. "new endpoint added" → A01+A05 scan; "new SQL query" → A05 scan.
 2. **Does this touch auth, data, or secrets?** These categories get the most thorough STRIDE pass. Changes to `logger.js` or docs don't.
 3. **How could this be reached and abused?** For every new surface, trace how it could be reached and what the impact would be, so you can prioritize the fix. If you can't identify a realistic path in 30 seconds, note the effort and move on — don't fabricate threats.
 4. **Cross-check: did the reviewer already flag this?** You'll be merged with their output. Duplicating their `use parameterized queries` finding is OK but prefer adding severity (reviewer says INFO, you say HIGH because it's in an auth path).
@@ -61,7 +61,7 @@ Before writing findings, think through:
 
 <output_contract>
 
-Your output path is provided in the prompt. Write to that file using this exact structure so `parseReviewFindings()` can extract findings:
+Your output path is provided in the prompt. Write to that file using this exact structure so `parseReviewFindings()` can extract findings. If the prompt gives no output path, write no file and return the report in your reply:
 
 ```markdown
 ---
@@ -85,7 +85,7 @@ generated: <ISO timestamp>
 ## Frameworks covered
 
 - [x] OWASP A01 Access Control — <what you checked>
-- [x] OWASP A03 Injection — <what you checked>
+- [x] OWASP A05 Injection — <what you checked>
 - [ ] OWASP A09 Logging — <skipped because no logging changes>
 
 ## Scope notes

package/agents/pan-knowledge.md

@@ -75,6 +75,6 @@ For all modes:
 
 **Don't pad.** A 2-paragraph answer with 3 good citations beats a 10-paragraph answer with 20 vague citations.
 
-**Multi-turn: remember context caches across turns.** The prompt cache has warmed for the session's stable files. You don't need to re-read them on every turn — the host runtime handles that.
+**Multi-turn: each turn starts fresh.** Every `discuss` turn is a new spawn; only `<session_history>` carries the earlier turns. Read again any file you cite this turn. Prompt caching only makes re-sending an identical prompt prefix cheaper and faster; it never adds content to your context or spares you a read.
 
 </calibration>

package/agents/pan-meta-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: pan-meta-reviewer
 description: Reviews the reviewer + hardener output. Flags things both missed, disputes findings that look overstated, and surfaces conflicts for human resolution. Spawned by /pan:review-deep.
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, Write
 color: magenta
 effort: medium
 model: opus
@@ -42,7 +42,7 @@ Think through, in order:
 
 <output_contract>
 
-Write to the path provided in your prompt. Structure:
+Write to the path provided in your prompt. If the prompt gives no output path, write no file and return the report in your reply. Structure:
 
 ```markdown
 ---

package/agents/pan-optimizer.md

@@ -1,7 +1,7 @@
 ---
 name: pan-optimizer
 description: Circular optimization analyst. Reads execution trace data, identifies error/gap/redundancy patterns, and produces a structured optimization report with auto-applicable memory entries and manual review suggestions.
-tools: Read, Glob, Grep
+tools: Read, Glob, Grep, Write
 color: cyan
 effort: high
 ---
@@ -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:
@@ -116,7 +120,7 @@ For each memory gap and redundancy with known content, produce a JSON action in
 
 ## Output Format
 
-Write the report as a markdown file at `.planning/optimization/reports/{session}-opt-report.md`.
+Write the report as a markdown file at `.planning/optimization/reports/{session}-opt-report.md`. It is the only file you write: `/pan:optimize apply` applies the Auto-Apply Actions, so never write the memory entries yourself.
 
 ```markdown
 # Optimization Report — {session_id}

package/agents/pan-phase-researcher.md

@@ -47,7 +47,7 @@ Before researching, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during research
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Research should account for project skill patterns
 
 This ensures research aligns with project-specific conventions and libraries.
@@ -86,7 +86,7 @@ Your research.md is consumed by `pan-planner`:
 
 ## Claude's Training as Hypothesis
 
-Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
+Training data may be out of date, so verify versions and APIs against current sources. Treat pre-existing knowledge as hypothesis, not fact.
 
 **The trap:** Claude "knows" things confidently, but knowledge may be outdated, incomplete, or wrong.
 

package/agents/pan-plan-checker.md

@@ -36,7 +36,7 @@ Before verifying, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Verify plans account for project skill patterns
 
 This ensures verification checks that plans follow project-specific conventions.
@@ -240,6 +240,7 @@ issue:
 - Plan with 15+ file modifications
 - Single task with 10+ files
 - Complex work (auth, payments) crammed into one plan
+- **Code instead of decisions:** a task `<action>` holding an implementation body (a function, a whole file) rather than names, signatures, values, assertions and the verify command. `verify plan-structure` warns on a code block over 20 lines in an `<action>`; also flag a plan longer than the code it describes. Severity: warning; the executor writes the code
 
 **Example issue:**
 ```yaml
@@ -561,13 +562,16 @@ for plan in "$PHASE_DIR"/*-plan.md; do
 done
 ```
 
-Parse JSON result: `{ valid, errors, warnings, task_count, tasks: [{name, hasFiles, hasAction, hasVerify, hasDone}], frontmatter_fields }`
+Parse JSON result: `{ valid, errors, warnings, task_count, tasks: [{name, type, hasFiles, hasAction, hasVerify, hasDone}], frontmatter_fields }`. A checkpoint task's entry is `{name, type}`, plus `auto_select` on a decision.
 
 Map errors/warnings to verification dimensions:
 - Missing frontmatter field → `task_completeness` or `must_haves_derivation`
 - Task missing elements → `task_completeness`
 - Wave/depends_on inconsistency → `dependency_correctness`
 - Checkpoint/autonomous mismatch → `task_completeness`
+- Decision `auto_select` names no option (error) → `task_completeness`, blocker
+- Decision without `auto_select` (warning) → no issue by itself: auto mode stops there for a human. Raise it as a warning only when the decision is reversible and low-stakes, so a default would let an unattended run continue
+- Task embeds a long code block in `<action>` (warning) → `scope_sanity`, warning: plans record decisions, not code
 
 ## Step 3: Parse must_haves
 
@@ -756,6 +760,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 +793,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 +832,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>