pan-wizard 3.32.0 → 3.34.0

package/commands/pan/focus-exec.md

@@ -1,7 +1,8 @@
 ---
 name: focus-exec
 group: Focus
-description: Automated batch execution pipeline with 6 stages, 9 behavioral rules, 3 execution tiers
+description: Automated batch execution pipeline with 6 stages, behavioral rules, 3 execution tiers
+argument-hint: "[--budget N] [--mode bugfix|balanced|features|full] [--priority P0-P6] [--dry-run] [--no-commit] [--continue] [--deep-review]"
 allowed-tools:
   - Read
   - Write
@@ -85,7 +86,7 @@ Each stage has a restricted set of appropriate actions. Using the wrong tool at
 This command executes work on the **host project's source code** — not on PAN Wizard's own infrastructure.
 
 **Do not read, modify, or fix files in these PAN directories:**
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`) — PAN runtime directories
 - Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
 
 **These directories are PAN's own tooling installed into the project.** If a batch item targets a PAN infrastructure file, SKIP it with reason "PAN infrastructure — out of scope." Never modify PAN's agents, commands, core modules, or dispatcher as part of project work.
@@ -116,7 +117,7 @@ HARD STOP conditions (do not proceed to next stage):
 - `--dry-run` — Run Stages 1-2 only (show what WOULD be executed)
 - `--no-commit` — Skip the commit step in Stage 6
 - `--continue` — Resume a previously interrupted execution
-- `--deep-review` (v3.4+) — After each high-stakes item's execution, run `/pan:review-deep` for that item (pan-hardener + pan-meta-reviewer security + cross-check). Slows the campaign by roughly 3× per item that triggers the deep pass; use for batches touching auth/payment/migrations.
+- `--deep-review` (v3.4+) — After each high-stakes item's execution, run the deep pass on that item's changed files: spawn pan-hardener (`<output_path>` `.planning/reviews/<item-id>/hardener.md`), then pan-meta-reviewer on its report (`.planning/reviews/<item-id>/meta.md`), and merge with `pan-tools review-deep merge <item-id> --hardener-file … --meta-file …` (no first-pass review, so no `--reviewer-file`; `/pan:review-deep` itself needs a phase). Slows the campaign by roughly 3× per item that triggers the deep pass; use for batches touching auth/payment/migrations.
 
 ---
 
@@ -161,7 +162,7 @@ Every code change must be tested before moving to the next item.
 Test cadence by tier:
 - **MICRO (XS/S):** Run specific test after implementing. Batch up to 3 independent items before smoke.
 - **STANDARD (M):** Full test suite after each item.
-- **FULL (L/XL):** Build hooks + full test suite after each item.
+- **FULL (L/XL):** The project's build step (if it has one) + full test suite after each item.
 
 ### Rule 4: Don't Invent — Follow the Plan
 Implement exactly what the batch says. Do not:
@@ -210,8 +211,7 @@ This catches emergent interactions: 5 "add try-catch" fixes might reveal the mod
 1. **Check Project Status** — git status, recent commits
 2. **Test Baseline** — run test suite, record current counts
 3. **Create rollback snapshot** — git tag for safety
-4. **Prime prompt cache** — `pan-tools cache prime --summary` (once; all sub-agents in the next 5 min hit cached context)
-5. **Report** — Output session start summary
+4. **Report** — Output session start summary
 
 **Circular optimization — init trace:**
 ```bash
@@ -286,7 +286,7 @@ Display the execution batch to user, then continue automatically.
 3. DESIGN — outline approach before coding
 4. STATE INTENT — "I will modify [files]. Risk: [what could break]"
 5. IMPLEMENT in logical chunks
-6. BUILD — build hooks if hooks changed
+6. BUILD — run the project's build step if the item changed what it builds
 7. TEST — full test suite
 8. CONFIRM — all pass -> DONE | fail -> investigate (15 min max) -> REVERT -> FAILED
 ```

package/commands/pan/focus-plan.md

@@ -2,6 +2,7 @@
 name: focus-plan
 group: Focus
 description: Create capacity-budgeted work batch with spec coverage verification and 4 execution modes
+argument-hint: "[--budget N] [--mode bugfix|balanced|features|full] [--priority P0-P6] [--lean] [--no-spec-check]"
 allowed-tools:
   - Read
   - Write
@@ -24,7 +25,7 @@ Create a capacity-budgeted work batch from focus-scan results **with mandatory v
 This command plans work batches for the **host project** — NOT for PAN Wizard's own infrastructure.
 
 **NEVER include items targeting these PAN directories:**
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`) — PAN runtime directories
 - Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
 
 If a scan item points to a PAN infrastructure file, DROP it from the batch. PAN's files are not the project's responsibility.
@@ -38,11 +39,11 @@ If no recent scan exists, run `/pan:focus-scan` automatically before proceeding.
 **Flags:**
 - `--budget N` — Override capacity budget in points (default: 50, min: 5, max: 100)
 - `--mode MODE` — Execution mode. Default: `balanced`
-  - `bugfix` — P0->P1->smallest-first, no feature work (40 pts)
+  - `bugfix` — one pass over P0-P4 in priority order, smallest-first within each; P5-P6 left out (40 pts)
   - `balanced` — **Default.** Mix of stability fixes + feature development, 60/40 split (50 pts)
-  - `features` — Feature-focused: 80% budget on P3-P5, P0 crashes still mandatory (50 pts)
-  - `full` — Full-spectrum: enhanced budget, all priorities equally weighted (60 pts)
-- `--priority P0-P6` — Only pick items from these priority tiers
+  - `features` — Feature-focused: P0 crashes mandatory, then 80% of what that leaves on P3-P5 (50 pts)
+  - `full` — Full-spectrum: one pass over every priority, P0 first and smallest-first within each; budget raised to at least 60 (60 pts)
+- `--priority PN` — Only pick items at priority PN or higher (P0 through PN), e.g. `--priority P2`
 - `--lean` — Apply RS filtering: exclude items with RS < 1.5
 - `--no-spec-check` — Skip spec coverage verification (NOT recommended — use only for pure bugfix batches)
 
@@ -133,13 +134,13 @@ This becomes the **spec gap backlog** — items that specs/ADRs promised but the
 ### `features` — Feature-Focused Sprint
 - **Budget:** 50 pts
 - **Mandatory pass:** All P0 items
-- **Feature pass (80%):** 40 pts for P3-P5
-- **Stability pass (20%):** 10 pts for P1-P2 quick wins
+- **Feature pass (80%):** 80% of what the P0 pass left, for P3-P5 (40 pts when there are no P0 items)
+- **Stability pass (20%):** the rest of it, for P1-P2 quick wins (10 pts when there are no P0 items)
 - **Spec coverage:** Feature items MUST map to spec requirements — reject unspecified feature work
 
 ### `full` — Full-Spectrum Marathon
 - **Budget:** 60 pts
-- **All priorities weighted equally, largest-impact-first**
+- **One pass over every priority in priority order, smallest-first within each**
 - **Spec coverage:** Full traceability — every item maps to a spec/ADR requirement or is flagged as unspecified
 
 ### Batch Selection Algorithm
@@ -220,7 +221,7 @@ This becomes the post-execution checklist for `/pan:focus-exec`.
 
 ## Phase 5: Output
 
-Produce a batch file at `.planning/focus/batch-<YYYY-MM-DD>.json` via `pan-tools focus plan`:
+Write the batch to `.planning/focus/batch-<YYYY-MM-DD>.json` yourself — `{date, mode, budget, allocated, items: [...]}`, each item `{id, title, priority, effort, points, tier, files}` with `tier` one of `MICRO`, `STANDARD`, `FULL` (`focus exec` and `focus classify-stages` group items by it, and an item without it lands in no wave); `focus exec`, `focus classify-stages` and `/pan:focus-exec` read an `items` or `batch` array. Do not hand this step to `pan-tools focus plan`: it ignores the scan and the spec mapping, batches only incomplete roadmap phases, pending todos and `.planning/patterns.md` entries, and overwrites the day's batch file:
 
 ```markdown
 ## Focus Batch — <date>
@@ -252,11 +253,11 @@ Produce a batch file at `.planning/focus/batch-<YYYY-MM-DD>.json` via `pan-tools
 | NCA affordability | ADR-0018 SC-4 | Blocked by SC-1, SC-2 | After this batch |
 
 ### Dependency Order
-```
+~~~
 #1 (P0 crash fix) → independent
 #3 (categories) → #4 (keywords) → #5 (match types)
 #2 (tests) → independent
-```
+~~~
 
 ### Post-Execution Verification Checklist
 - [ ] SC-1: Category count >= 65 → `SELECT COUNT(*) FROM stx_category`

package/commands/pan/focus-scan.md

@@ -2,8 +2,10 @@
 name: focus-scan
 group: Focus
 description: Deep-dive strategic work scan with prioritized items and Reality Score filtering
+argument-hint: "[--focus <area>] [--quick] [--refresh] [--lean]"
 allowed-tools:
   - Read
+  - Write
   - Bash
   - Grep
   - Glob
@@ -22,13 +24,13 @@ Survey the project for prioritized work items with evidence-based scoring. $ARGU
 This command scans the **host project's source code** for work items — not PAN Wizard's own infrastructure.
 
 **Exclude these directories from scanning:**
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`) — PAN runtime directories
 - `.planning/` — PAN planning state (read for context, but never report PAN planning files as "issues")
 - Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
 
 **These directories are PAN's own tooling installed into the project.** Do not report TODO/FIXME items found in PAN files. Do not flag PAN files as lacking test coverage. Do not suggest improvements to PAN's agents, commands, or core modules.
 
-If a scan finding points to a file inside `.claude/`, `.github/`, `.opencode/`, `.gemini/`, or `.codex/` — DROP IT. It is not the project's responsibility.
+If a scan finding points to a file in one of the PAN paths listed above — DROP IT. It is not the project's responsibility.
 
 ---
 
@@ -73,10 +75,7 @@ Read these files to establish baseline:
 
 **Project Structure:**
 - All core modules in the project's source directories
-- All command definitions
-- All agent definitions
-- All workflow definitions
-- All hook source files
+- The project's own command, agent, workflow and hook definitions, if it has any (never PAN's, which the Project Scope Boundary excludes)
 
 **Planning State:**
 - `.planning/state.md` — Current state
@@ -95,9 +94,7 @@ In: source directories, hooks, tests
 Cross-reference found issues with documented items — flag any UNDOCUMENTED issues as new findings.
 
 ### 0.3 Check Test Results
-```bash
-npm test 2>&1
-```
+Run the project's test suite: the commands in `.planning/config.json → verification` when set, otherwise the test command discovered from `package.json` scripts, `Makefile`, or project docs.
 Record: total tests, passing, failing, suites.
 
 ### 0.4 Baseline Snapshot Table
@@ -240,7 +237,7 @@ Gather items from:
 ## Phase 5: Scan Assembly
 
 ### 5.1 Output
-Return JSON via `pan-tools focus scan` with all items, or write to `.planning/focus/` for persistence.
+Write the scan to `.planning/focus/scan-<YYYY-MM-DD>.md`, where `/pan:focus-plan` builds from it and `/pan:focus-exec` updates it (Stage 5.2). `pan-tools focus scan` does not take these items: it lists only incomplete roadmap phases that have a directory, pending todos and `.planning/patterns.md` entries.
 
 ### 5.2 Document Structure
 

package/commands/pan/focus-sync.md

@@ -2,6 +2,7 @@
 name: focus-sync
 group: Focus
 description: Synchronize documentation after changes — check staleness and update counts
+argument-hint: "[--readme | --docs | --arch | --all]"
 allowed-tools:
   - Read
   - Bash
@@ -24,7 +25,7 @@ Synchronize project documentation across all files. $ARGUMENTS
 This command synchronizes the **host project's documentation** — NOT PAN Wizard's own infrastructure files.
 
 **NEVER sync, modify, or report staleness in these PAN directories:**
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`) — PAN runtime directories
 - Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
 
 **These directories are PAN's own tooling.** Documentation sync applies to the project's README, docs, guides, and code comments — not to PAN's installed agents or command definitions.
@@ -91,7 +92,7 @@ CHANGELOG.md              <- Version history
 
 ## Report
 
-Output via `pan-tools focus sync`:
+Report in this shape (`pan-tools focus sync` itself returns only JSON — `actuals` (counts of commands, agents and modules), `stale` / `current` entries for those counts, any `--tests` / `--suites` counts, renamed `/pan:` commands and the package.json-vs-CHANGELOG version, plus `stale_count` and `needs_sync`):
 
 ```
 | Area | Status | Finding |

package/commands/pan/git.md

@@ -15,7 +15,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 (`pan-rollback-*`), which `pan-tools rollback-snapshot <phase>` creates; no workflow creates them for you.
 
-Works with any git repository — PAN installation not required.
+Works with any git repository — no PAN project (`.planning/`) needed, only the installed `pan-tools.cjs`.
 </objective>
 
 <subcommands>
@@ -59,19 +59,19 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git commit \
 ```
 
 **Options:**
-- `--type` — `feat | fix | docs | test | refactor | chore`
+- `--type` — `feat | fix | docs | test | refactor | perf | chore`
 - `--message` — Commit message body
 - `--all` — Stage all changes before committing
 - `--files f1 f2` — Stage specific files
 - `--amend` — Amend last commit (no message needed)
-- `--force` — Bypass deleted-file and sensitive-file blocks
+- `--force` — Bypass the deleted-file block (not the sensitive-file block)
 
 **Safety checks run automatically:**
 
 | Check | Blocks on | Override |
 |-------|-----------|---------|
-| Deleted files | Staged deletions found | `--force` |
-| Sensitive files | `.env`, `.pem`, `.key`, `secret`, `password`, `token` | `--force` |
+| Deleted files | A deletion anywhere in the repository (`git status --porcelain`, staged or not) | `--force` |
+| Sensitive files | A staged path ending `.env`, `.pem` or `.key`, or containing `credentials`, `secret`, `password` or `token` (PAN's own `.planning/metrics/tokens.jsonl` is exempt) | None: narrow `commit.sensitive_patterns` in `.planning/config.json`, or commit the file yourself |
 
 **Output:** `{committed, hash, type, safety_checks}`
 
@@ -174,14 +174,14 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git diff --staged --file src/ap
 ### rollback — Revert to PAN Snapshot
 
 ```bash
-# Rollback to latest PAN snapshot tag (requires clean working tree)
+# Rollback to the last pan-rollback-* tag in name order — the newest only among one phase's snapshots (requires clean working tree)
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback
 
 # Preview — does NOT reset, shows what would happen
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback --dry-run
 
 # Rollback to specific tag
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback --tag pan-rollback-03-1714000000
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback --tag pan-rollback-3-20260415T101500
 ```
 
 **Rollback workflow:**
@@ -219,5 +219,5 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git sync --remote upstream --br
 </workflow>
 
 <runtime_note>
-All subcommands work with any git repository regardless of whether PAN is installed or `.planning/` exists. The only requirement is a valid git repo (`git init` or cloned).
+All subcommands work with any git repository, whether or not it holds a PAN project (`.planning/`); they run the installed `pan-tools.cjs`. The only requirement is a valid git repo (`git init` or cloned).
 </runtime_note>

package/commands/pan/health.md

@@ -2,7 +2,7 @@
 name: pan:health
 group: System
 description: Diagnose planning directory health and optionally repair issues
-argument-hint: "[--repair]"
+argument-hint: "[--repair] [--standards] [--full] [--drift] [--links]"
 allowed-tools:
   - Read
   - Bash
@@ -19,5 +19,5 @@ Validate `.planning/` directory integrity and report actionable issues. Checks f
 
 <process>
 Execute the health workflow from @~/.claude/pan-wizard-core/workflows/health.md end-to-end.
-Parse --repair flag from arguments and pass to workflow.
+Pass the arguments to the workflow, which forwards `--repair`, `--standards`, `--full`, `--drift` and `--links` to `validate health`.
 </process>

package/commands/pan/hud.md

@@ -34,10 +34,10 @@ pan-tools hud [--out <file>] [--open] [--stdout]
 **JSON result shape** (default, when not `--stdout`):
 ```json
 {
-  "path": ".planning/hud.html",
+  "path": "/abs/path/to/project/.planning/hud.html",
   "bytes": 18234,
   "army_active": true,
-  "sections": ["mission", "command-stack", "campaign", "safety-harness", "worktrees", "roadmap", "telemetry", "requirements-quality", "activity"],
+  "sections": ["mission", "now-building", "command-stack", "campaign", "safety-harness", "worktrees", "roadmap", "telemetry", "requirements-quality", "activity"],
   "opened": false
 }
 ```
@@ -51,6 +51,7 @@ Panels render only when they have data — a plain (non-army) project still gets
 | Panel | What it shows | Source |
 |-------|---------------|--------|
 | **Mission banner** | Project, core value, status, version/milestone + metric cards (progress, phase, requirements, spend) | `package.json`, `project.md`, `state.md`, phase scan, cost ledger |
+| **Now building** | Current phase on a phase stepper, its pipeline stage (research → plan → execute → verify), and the army tasks in flight or the phase's plan/summary counts | phases on disk + army worktrees |
 | **Command stack** *(army)* | Mission Control over the four squads with per-squad agent drill-down (active / idle, calls, tokens) | squad registry + cost ledger |
 | **Campaign** *(army)* | Cadence, next-due, daily-budget bar, last run, run history | `schedule.json` |
 | **Safety harness** *(army)* | Merge gate, abort switch (pause), active worktrees, daily budget, concurrency | config + pause file + worktrees + schedule |

package/commands/pan/hygiene.md

@@ -1,7 +1,7 @@
 ---
 name: pan:hygiene
 group: System
-description: Scan the project for PAN version drift and stale artifacts (legacy filenames, memory bloat, poisoned ledgers, trace debris) and apply safe cleanups
+description: Scan the project for PAN version drift and stale artifacts (legacy filenames, memory bloat and stale entries, poisoned ledgers, trace debris, oversized planning files) and apply safe cleanups
 argument-hint: "[--apply] [--trace-age-days N] [--all-tracks] [--track <name>]"
 allowed-tools:
   - Read
@@ -9,7 +9,14 @@ allowed-tools:
   - AskUserQuestion
 ---
 <objective>
-Keep a PAN-managed project aligned with the latest PAN version and free of accumulated history debris. Detects: outdated runtime installs (per-runtime manifest version vs latest), legacy uppercase planning filenames, orphaned atomic-write .tmp files, per-agent memory logs past the compaction cap, cost ledgers poisoned by pre-v3.12.4 telemetry, stale optimization trace sessions, and stray fragment `.planning/` directories.
+Keep a PAN-managed project aligned with the latest PAN version and free of accumulated history debris. Detects:
+- outdated runtime installs (per-runtime manifest version vs latest);
+- legacy uppercase planning filenames and orphaned atomic-write .tmp files;
+- per-agent memory logs past the compaction cap (`memory-bloat`), memory entries whose cited code is gone or that went unused past the expiry window (`memory-stale`), and files in `.planning/memory/` that are not read as memory (`memory-format`);
+- planning files past their budget (`cache-context`): state.md, which every agent call re-reads, and roadmap.md and requirements.md, which only the roadmapper and milestone work read whole (phase agents read `roadmap slice`); state.md's settled history and roadmap.md's shipped phases can be archived;
+- cost ledgers poisoned by pre-v3.12.4 telemetry, stale optimization trace sessions and reports, and stray fragment `.planning/` directories;
+- a planning tree another tool writes into too (`shared-planning-tree`) or owns (`foreign-planning-tree`);
+- Claude Code's own memory index past or near its load limit, or holding content where a one-line pointer belongs (`host-memory`). PAN only reports this one: it never writes the host's memory.
 </objective>
 
 <process>
@@ -28,7 +35,7 @@ Display the findings grouped by severity (critical → warn → info), labelling
 
 **Always state which trees were scanned** — read `roots_scanned[]` and name them. If `summary.total` is 0, report "Project is clean and aligned" *together with* the list of trees that were read. A clean verdict without its scope is what let stale debris hide in an unscanned track; never report one without the other.
 
-If any root has `planning_root_exists: false`, say so plainly — that is a mistyped `--track`, not a clean tree.
+If the top-level `planning_root_exists` is `false`, or a `roots_scanned[]` entry has `planning_exists: false`, say so plainly — that is a mistyped `--track`, not a clean tree.
 
 ## 2. Version drift (manual remediation)
 
@@ -36,7 +43,7 @@ If any `version-alignment` findings exist, list the outdated runtimes and show t
 
 ```
 Re-run the installer from the project root to align all runtimes:
-  node <pan-source>/bin/install.js --claude --codex --gemini --opencode --copilot --local
+  npx pan-wizard@latest --claude --codex --gemini --opencode --copilot --local
 (use the flags matching the runtimes reported in installs[])
 ```
 
@@ -58,11 +65,11 @@ Then ask the user (AskUserQuestion, header "Apply fixes", options: "Apply safe f
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean --all-tracks --apply
 ```
 
-Safe fixes are: lowercase renames of legacy planning filenames, deletion of aged .tmp orphans, memory-log compaction, poisoned-ledger quarantine (rename in place — never deleted), pruning of trace sessions **and optimization reports** past retention (newest 5 of each always kept), and **state.md compaction** (`compact-state`) — settled history is archived to `state-history.md` so it stops being re-read into every agent call. Nothing is deleted by any of these: the ledger is renamed, and state history is written to the archive before state.md is rewritten. Each fix is applied inside its own tree's scope, so a track's debris is cleaned in that track. Pass through `--trace-age-days N` and any `--track <name>` if provided.
+Safe fixes are: lowercase renames of legacy planning filenames, deletion of aged .tmp orphans, memory-log compaction, **memory pruning** (`prune-memory`: stale and expired entries move to `.planning/memory/archive/<agent>.md`), poisoned-ledger quarantine (renamed in place; only the newest quarantined copy is kept, older ones are deleted), pruning of trace sessions **and optimization reports** past retention (newest 5 of each always kept), **state.md compaction** (`compact-state`) — settled history is archived to `state-history.md` so it stops being re-read into every agent call — and **roadmap compaction** (`compact-roadmap`): shipped phases' sections move to `roadmap-history.md`, leaving a stub that `roadmap get-phase` reads back through. None of these deletes anything you wrote: the ledger is renamed, and each archive is written before the file it came from is rewritten. Each fix is applied inside its own tree's scope, so a track's debris is cleaned in that track. Pass through `--trace-age-days N` if provided. With `--track <name>`, use it **in place of** `--all-tracks` in both commands: given both, `--all-tracks` wins and every tree is cleaned.
 
 ## 4. Report
 
-Summarize: the trees scanned, fixes executed / failed / left manual (attributed per track), plus the installer command if version drift remains. If a `cache-context` finding appeared, state the per-call token cost it represents — that block is re-read on **every** agent call, so it is the project's largest recurring expense. Recommend re-running `/pan:hygiene` after the installer to confirm alignment.
+Summarize: the trees scanned, fixes executed / failed / left manual (attributed per track), plus the installer command if version drift remains. If a `cache-context` finding appeared, state the token cost its detail names and who pays it: state.md is re-read on **every** agent call, the project's largest recurring expense, while roadmap.md and requirements.md cost only when the roadmapper or milestone work reads them whole. If a `host-memory` finding appeared, name the index and the lines it flags so the user can tidy them: Claude Code loads only the head of that index, and PAN never edits it. Recommend re-running `/pan:hygiene` after the installer to confirm alignment.
 
 </process>
 
@@ -70,6 +77,6 @@ Summarize: the trees scanned, fixes executed / failed / left manual (attributed
 - [ ] Scan run and findings presented by severity
 - [ ] Version drift reported with the exact installer command (never auto-run)
 - [ ] Safe fixes applied only with --apply or explicit user confirmation
-- [ ] Nothing user-authored deleted — quarantine renames only
+- [ ] Nothing user-authored deleted — the ledger quarantine is a rename (older quarantined copies, PAN's own data, are removed), and memory compaction archives what it drops
 - [ ] Final summary states executed/failed/manual counts
 </success_criteria>

package/commands/pan/knowledge.md

@@ -16,7 +16,7 @@ allowed-tools:
 Retrieve, refine, or consolidate project knowledge. Three modes:
 
 - **ask** — answer a natural-language question with inline citations grounded in `.planning/` + `docs/`.
-- **discuss** — multi-turn refinement of a phase's context. Session state persists across invocations; prompt caching keeps turn 3 cheap.
+- **discuss** — multi-turn refinement of a phase's context. Session state persists across invocations.
 - **playbook** — aggregate all agents' memory (E-4 layer) into `.planning/playbook.md`, organized by category (Conventions / Gotchas / Decisions / Tool choices / Anti-patterns / Recurring gaps).
 
 Consolidates Spec B v1's X-3 converse + X-6 teach + X-10 explain into one command.
@@ -54,10 +54,10 @@ Consolidates Spec B v1's X-3 converse + X-6 teach + X-10 explain into one comman
 2. `pan-tools knowledge discuss <phase> --subcmd append --role user --content "<topic>"` persists the user turn.
 3. Spawn `pan-knowledge` with `<mode>discuss</mode>`, session history, phase context, and the new turn.
 4. Agent responds.
-5. `pan-tools knowledge discuss <phase> --subcmd append --role agent --content "<response>" --cites "a.md,b.md"` persists the response.
-6. If after ≥3 substantive turns the agent offered to emit `context.md`, user can follow up with another `/pan:knowledge discuss <phase>` invocation or run the commit subcommand the agent suggested.
+5. Write the agent's response to a file, then `pan-tools knowledge discuss <phase> --subcmd append --role agent --content "$(cat <response-file>)" --cites "a.md,b.md"` persists it — a reply pasted between the quotes breaks the shell line at its first `"`, `$` or backtick.
+6. If after ≥3 substantive turns the agent offered to emit `context.md`, the user accepts in another `/pan:knowledge discuss <phase>` turn and the agent writes it (there is no commit subcommand).
 
-**Session persistence:** `.planning/conversations/<phase>/session.json` — array of turns with ts/role/content/cites. Multi-turn cost is dominated by cache hits on stable `.planning/` files.
+**Session persistence:** `.planning/conversations/<phase>/session.json` — `{phase, turns: [...], created, last_updated}`, each turn with ts/role/content/cites.
 
 ### `playbook`
 
@@ -66,12 +66,12 @@ Consolidates Spec B v1's X-3 converse + X-6 teach + X-10 explain into one comman
 ```
 
 **Flow:**
-1. `pan-tools knowledge playbook` reads all agents' memory (`.planning/memory/*.md`), clusters entries by category, writes `.planning/playbook.md` directly.
+1. `pan-tools knowledge playbook` reads every agent log that `memory list` names in `.planning/memory/`, clusters entries by category, writes `.planning/playbook.md` directly.
 2. Optionally spawn `pan-knowledge` with `<mode>playbook</mode>` to polish (dedupe contradictions, consolidate similar entries). Skip the polish step if the draft looks clean.
 
 **Output:** `.planning/playbook.md` — team-readable summary of accumulated lessons.
 
-**Auto-invocation:** `/pan:milestone-done` can optionally run this (flag-gated, not default). Manual invocation any time.
+**Auto-invocation:** none — no workflow runs it (`/pan:milestone-done` has no playbook step). Run it by hand any time.
 
 </modes>
 
@@ -83,7 +83,7 @@ Consolidates Spec B v1's X-3 converse + X-6 teach + X-10 explain into one comman
 
 **Bug investigation:** `/pan:knowledge ask "why did we add the retry in phase 4?"` — faster than grepping for historical context.
 
-**Before milestone-done:** run `/pan:knowledge playbook` to capture what the team learned. Gives contributors something to reference when starting the next milestone.
+**Before milestone-done:** run `/pan:knowledge playbook` to collect the lessons the agent logs hold. PAN no longer writes those logs on its own (ADR-0036, amended `2026-10-04`): they hold what someone recorded with `memory append`, `memory record` or `/pan:retro` with `--write-memory`, or an older report applied, so on a project without such entries the playbook is empty.
 
 </workflow>
 
@@ -106,8 +106,8 @@ The agent should NEVER fabricate citations. The retrieval layer's `sources` list
 
 | Runtime | ask | discuss | playbook |
 |---------|-----|---------|----------|
-| Claude Code | Full, thinking enabled | Full, prompt caching bonus | Full |
-| OpenCode | Full | Full (no cache bonus) | Full |
+| Claude Code | Full, thinking enabled | Full | Full |
+| OpenCode | Full | Full | Full |
 | Gemini | Full | Full | Full |
 | Codex | Full | Full | Full |
 | Copilot | Full | Full | Full |

package/commands/pan/learn.md

@@ -2,6 +2,7 @@
 name: pan:learn
 group: Self-Improvement
 description: Analyze trace sessions or harvested experiments via pan-optimizer; generate ranked optimization reports
+argument-hint: "[--session <id> | --sessions <n> | --experiment <slug>] [--apply]"
 allowed-tools:
   - Read
   - Bash
@@ -26,8 +27,8 @@ Analyze the most recent trace session and generate an optimization report.
 **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)
+- `--experiment <slug>` *(v3.7.0+, W3)* — analyze a harvested experiment instead of the current project's traces: the workflow runs its `pan-tools` steps with `--cwd` set to the harvest folder (the `harvest_path` `/pan:experiment harvest <slug>` printed, `<source-repo>/experiments/<slug>/` by default), so the analysis and the optimizer's report land in that folder's `.planning/optimization/reports/`. Used by the self-improvement loop. Run `/pan:experiment harvest <slug>` first.
+- `--apply` — record the report's suggestions right after generating it (equivalent to running `/pan:optimize apply` immediately after)
 
 **What it does:**
 
@@ -47,28 +48,30 @@ Analyze the most recent trace session and generate an optimization report.
 - Tool failures and correction loops (error events)
 - Topics the model had to infer without context (gap events)
 - Repeated research on the same topic (redundancy events)
-- Memory cache misses (memory_miss events)
+- Missing knowledge an agent logged (memory_miss events)
 - Unexpected outcomes (surprise events)
 
 **Output:**
 
 The optimization report in `.planning/optimization/reports/` contains:
 - Ranked error patterns with fix recommendations
-- Memory gap findings with ready-to-apply memory entry content
+- Lessons the agents lacked, each with where it belongs: the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, or a comment at the cited code
 - Redundancy analysis with token waste estimates
 - Prompt improvement suggestions (require human review before applying)
 - Workflow gap suggestions (require human review)
-- An `## Auto-Apply Actions` JSON block for `/pan:optimize apply`
+- An `## Auto-Apply Actions` JSON block, which `/pan:optimize apply` records in `.planning/optimization/suggestions.md`
 - A circular optimization score (0–100)
 
+Nothing in the report reaches an agent until a person writes it where the agents read. PAN's workflows do not load `.planning/memory/` into agents.
+
 **Example:**
 ```
 /pan:learn
 → Session sess_20260421T180000: 47 events (8 errors, 12 gaps, 3 redundancies)
 → Report: .planning/optimization/reports/sess_20260421T180000-opt-report.md
 → Optimization score: 72/100
-→ Top finding: M1 — Express middleware order missing from memory (5 misses)
-→ Auto-applicable: 3 memory entries
+→ Top finding: L1 — Express middleware order inferred 5 times (belongs in CLAUDE.md)
+→ Lessons: 3
 → Needs review: 2 prompt improvements, 1 workflow gap
 ```
 

package/commands/pan/links.md

@@ -2,6 +2,7 @@
 name: pan:links
 group: Validation
 description: Validate the doc-code link graph — inline wiki-style refs, source-comment anchors, and require-code-mention contracts (ADR-0027, v3.8.0+)
+argument-hint: "[--strict] [--doc-root <path>]... [--source-root <path>]... [--raw]"
 allowed-tools:
   - Bash
   - Read
@@ -10,7 +11,7 @@ allowed-tools:
 
 # /pan:links
 
-Validate the doc-code link graph. Walks `docs/`, `pan-wizard-core/`, `commands/`, and `agents/` for inline `[[<id>]]` references and `// @pan: <id>` source-comment anchors. Reports broken refs, stale anchors, and uncovered backlink contracts.
+Validate the doc-code link graph. Walks `docs/`, `commands/`, `agents/` and `pan-wizard-core/`'s workflows, templates, references and learnings for inline `[[<id>]]` references, and `pan-wizard-core/`, `bin/`, `hooks/` and `scripts/` for `// @pan: <id>` source-comment anchors. Reports broken refs, stale anchors, and uncovered backlink contracts.
 
 > **User projects:** the default roots (`docs/`, `pan-wizard-core/`, `commands/`, `agents/`) are the **PAN source-repo** layout. A typical user project has none of these, so a bare `/pan:links` scans almost nothing and reports a hollow `pass`. In a user project you **must** point it at your own layout with `--doc-root` / `--source-root` (both repeatable), e.g. `/pan:links --doc-root docs --source-root src`. Treat any run where `doc_files_scanned` (or `source_files_scanned`) is `0` as a **warning that the roots are misconfigured**, not a clean pass.
 
@@ -28,6 +29,8 @@ Validate the doc-code link graph. Walks `docs/`, `pan-wizard-core/`, `commands/`
 - `--source-root <path>` — override default source roots. Repeatable.
 - `--raw` — human-readable output instead of JSON.
 
+**Run:** `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs links validate [--strict] [--doc-root <path>]... [--source-root <path>]... [--raw]` (`validate` may be left out when a flag comes first).
+
 **What it does:**
 
 Three sequential passes share one walk pair:

package/commands/pan/map-codebase.md

@@ -17,7 +17,7 @@ Analyze existing codebase using parallel pan-document_code agents to produce str
 
 Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
 
-Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+Output: .planning/codebase/ folder with structured documents about the codebase state.
 </objective>
 
 <execution_context>
@@ -59,9 +59,9 @@ The CLI returns `{mode, total_tokens, file_count, languages}`:
 - **`mode: "single-shot"`** — repo is small enough (≤700K tokens) for one agent with a 1M-context window to ingest the whole thing. Spawn a single `pan-document_code` agent with the full repo in context. This avoids the 6-way stitching artifacts of sharded mode (contradictory version claims, duplicated mentions, missed cross-file references).
 - **`mode: "sharded"`** — repo exceeds 700K tokens. Fall back to the default 6-way parallel sharding (tech, arch, quality, concerns, relationships, practices). Each shard is mapped by its own agent in its own context window, so no single agent has to hold the whole repo.
 
-Record the chosen mode + telemetry in the final `.planning/codebase/overview.md` so future runs can reason about drift.
+Record the chosen mode + telemetry in a `.planning/codebase/overview.md` you write yourself. The map-codebase workflow has no single-shot branch — it always spawns the sharded mappers and writes no overview.md — so in `single-shot` mode spawn the one agent in place of its spawn step.
 
-**The mode is decided by repo size alone** — `estimate-size` compares the token estimate to `--threshold` and applies no model check. So single-shot only pays off when the model you launched with actually has a 1M-context window (the default Opus and current Sonnet-class models do; legacy 200K-context models do not). On a 200K-context model, pass a threshold that matches your real window (e.g. `--threshold 150000`) so anything larger resolves to `sharded` instead of overflowing a single agent.
+**The mode is decided by repo size alone** — `estimate-size` compares the token estimate to `--threshold` and applies no model check. So single-shot only pays off when the model you launched with actually has a 1M-context window. On a model with a smaller window, pass a threshold that matches your real window (e.g. `--threshold 150000`) so anything larger resolves to `sharded` instead of overflowing a single agent.
 </stage_0_ingest_mode>
 
 <tool_priority>
@@ -99,14 +99,14 @@ The orchestrator loads context in layers — NOT everything upfront. Mapper agen
    - Agent 5: relationships focus → writes relationships.md
    - Agent 6: practices focus → writes best-practices.md
 4. Wait for agents to complete, collect confirmations (NOT document contents)
-5. Verify all 9 documents exist with line counts
+5. Verify all documents exist with line counts
 6. Commit codebase map
 7. Offer next steps (typically: /pan:new-project or /pan:plan-phase)
 </process>
 
 <success_criteria>
 - [ ] .planning/codebase/ directory created
-- [ ] All 7 codebase documents written by mapper agents
+- [ ] All codebase documents written by mapper agents
 - [ ] Documents follow template structure
 - [ ] Parallel agents completed without errors
 - [ ] User knows next steps