pan-wizard 3.33.0 → 3.34.0

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

@@ -59,7 +59,7 @@ 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. 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>

package/commands/pan/mcp-bridge.md

@@ -2,7 +2,7 @@
 name: pan:mcp-bridge
 group: External tools
 description: Discover available MCP tools and recommend which ones apply to a phase. Discovery-only; auto-invocation deferred.
-argument-hint: "list | recommend <phase> | cache [--servers <json>] [--runtime <name>]"
+argument-hint: "list | recommend <phase> [--max N] [--min-score N] | cache [--servers <json>] [--runtime <name>]"
 allowed-tools:
   - Read
   - Bash
@@ -12,7 +12,7 @@ allowed-tools:
 <objective>
 Surface Model Context Protocol (MCP) tools visible to the host runtime and recommend which ones might apply to a specific phase plan.
 
-Reduced scope from Spec B v1's X-7: **discovery and recommendation only**. Auto-injection of MCP tools into planner context and auto-invocation from executor agents are deliberately deferred (likely Wave 5+ or v3.5). This keeps v3.3 narrow and avoids coupling PAN to Claude Code's MCP schema stability.
+Reduced scope from Spec B v1's X-7: **discovery and recommendation only**. Auto-injection of MCP tools into planner context and auto-invocation from executor agents are deliberately deferred and still unscheduled (the v3.5 target passed without them). This kept v3.3 narrow and avoids coupling PAN to Claude Code's MCP schema stability.
 </objective>
 
 <execution_context>
@@ -44,7 +44,7 @@ Show cached MCP tools with server grouping and schemas.
 }
 ```
 
-When `source: "empty"`, either no MCP servers are configured or the host runtime hasn't populated the cache yet. See the `cache` subcommand for manual seeding.
+When `source: "empty"`, nothing has seeded the cache yet: no hook or host writes it, only `cache --servers` (or an external script). See the `cache` subcommand for manual seeding.
 
 ### `recommend <phase>`
 
@@ -85,20 +85,20 @@ Scoring is naive keyword frequency with word boundaries — not semantic embeddi
 Write or inspect the MCP tools cache at `.planning/bridge/available-tools.json`.
 
 ```
-# Inspect current cache (same as `list` but raw)
+# Inspect current cache (prints the same JSON as `list`)
 /pan:mcp-bridge cache
 
 # Seed cache from scripted discovery (for testing or external pipeline)
 /pan:mcp-bridge cache --runtime claude --servers '[{"name":"linear","tools":[{"name":"linear.updateTicket","description":"Update ticket"}]}]'
 ```
 
-Normally the host runtime writes this file. The CLI path exists for test fixtures and external-script integration.
+Nothing else writes this file: no hook or installer step populates it, so `list` and `recommend` see only what this command (or an external script) has recorded.
 
 </subcommands>
 
 <workflow>
 
-**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — each runtime keeps it somewhere different: Claude Code in `.mcp.json` at the project root (project scope) or `~/.claude.json` (user and local scopes), OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
+**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, nothing has seeded the cache: record each server with its tools, `/pan:mcp-bridge cache --servers '[{"name":"<server>","tools":[{"name":"<tool>","description":"…"}]}]'`, taking the tool names and descriptions from the MCP tools your session has loaded. A server recorded without `tools` adds no tool to `list` (only `server_count` counts it, and `source` then reads `cache`) and nothing to `recommend`, and the host runtime's MCP config names only the servers and how to start them. Each runtime keeps that config somewhere different: Claude Code in `.mcp.json` at the project root (project scope) or `~/.claude.json` (user and local scopes), OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
 
 **Planning a phase that might touch external systems?** Run `/pan:mcp-bridge recommend <phase>` to get a ranked shortlist. Copy relevant tool names into the phase plan's "External tools" section so the executor knows to invoke them.
 
@@ -108,11 +108,11 @@ Normally the host runtime writes this file. The CLI path exists for test fixture
 
 <caveats>
 
-**Discovery is a cache, not a live probe.** The host runtime owns populating `.planning/bridge/available-tools.json`. PAN does not query MCP servers directly — that would require runtime-specific HTTP or IPC integration this command deliberately avoids.
+**Discovery is a cache, not a live probe.** Only `cache --servers` (or an external script) populates `.planning/bridge/available-tools.json`; no hook or host writes it. PAN does not query MCP servers directly — that would require runtime-specific HTTP or IPC integration this command deliberately avoids.
 
 **Keyword scoring is crude.** "Postgres" and "PostgreSQL" are different tokens; `postgresql` in a plan won't match a `postgres.query` tool unless the plan also says "postgres." Tune your plan language or expand tool descriptions to improve matches.
 
-**Claude Code is the primary target.** MCP is a Claude-first protocol. Other runtimes may have their own tool-discovery mechanisms; the cache schema is intentionally generic so a future Codex/Gemini equivalent could populate the same file.
+**No runtime is special.** Each runtime PAN installs into reads MCP servers from its own config (see the workflow section above); the cache schema is generic, so whatever lists a runtime's servers can populate the same file.
 
 **No automatic invocation.** This command never calls MCP tools. It tells you what's available and what might apply. The actual invocation happens via the host runtime's normal tool-use flow (Claude Code's tool calls, etc.) when the executor agent decides to use a recommended tool.
 
@@ -122,23 +122,23 @@ Normally the host runtime writes this file. The CLI path exists for test fixture
 
 | Runtime | list | recommend | cache |
 |---------|------|-----------|-------|
-| Claude Code | Full | Full | Full (host-populated) |
-| OpenCode | Stub (empty cache returns gracefully) | Stub | CLI write works |
-| Gemini CLI | Stub | Stub | CLI write works |
-| Codex CLI | Stub | Stub | CLI write works |
-| Copilot CLI | Stub | Stub | CLI write works |
+| Claude Code | Full once seeded | Full once seeded | Full |
+| OpenCode | Full once seeded | Full once seeded | Full |
+| Gemini CLI | Full once seeded | Full once seeded | Full |
+| Codex CLI | Full once seeded | Full once seeded | Full |
+| Copilot CLI | Full once seeded | Full once seeded | Full |
 
-On non-Claude runtimes, the aggregator and recommendation logic still work — they just report zero tools until something populates the cache.
+On every runtime, `list` reports zero tools (`source: "empty"`) and `recommend` an empty `recommendations` list with a `reason` until `cache --servers` (or an external script) populates the cache; no host or hook writes it.
 
 </runtime_compatibility>
 
 <future_scope>
 
-Explicitly deferred from v3.3 (documented in ADR-0023 / Spec B v2 notes):
+Explicitly deferred from v3.3 (documented in ADR-0024 / Spec B v2 notes):
 
-1. **Auto-inject recommended tools into planner context** — requires a stable MCP schema contract and a plan-template extension. Candidate for v3.5.
-2. **Auto-invoke MCP tools from executor agent** — requires permission-gating and per-tool safety review. Candidate for v3.5+.
-3. **Cross-runtime tool discovery** — generic MCP-like protocol for non-Claude runtimes. No timeline; needs ecosystem signal.
+1. **Auto-inject recommended tools into planner context** — requires a stable MCP schema contract and a plan-template extension. Unscheduled.
+2. **Auto-invoke MCP tools from executor agent** — requires permission-gating and per-tool safety review. Unscheduled.
+3. **Cross-runtime tool discovery** — filling the cache automatically from each runtime's own MCP config and servers. No timeline; needs ecosystem signal.
 
 Until those land, this command is the minimum viable integration: you see what's there, you get suggestions, you decide manually.
 

package/commands/pan/milestone-done.md

@@ -46,6 +46,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
    - Look for `.planning/v{{version}}-milestone-audit.md`
    - If missing or stale: recommend `/pan:milestone-audit` first
    - If audit status is `gaps_found`: recommend `/pan:milestone-gaps` first
+   - If audit status is `tech_debt`: present the debt; proceed on the user's say-so (it becomes accepted debt), or recommend `/pan:milestone-gaps` for a cleanup phase
    - If audit status is `passed`: proceed to step 1
 
    ```markdown
@@ -87,6 +88,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
    - Create `.planning/milestones/v{{version}}-roadmap.md`
    - Extract full phase details from roadmap.md
    - Fill milestone-archive.md template
+   - Add this milestone's entry to `.planning/milestones.md` from @~/.claude/pan-wizard-core/templates/milestone.md (create the file with that template's header if it does not exist)
    - Update roadmap.md to one-line summary with link
 
 5. **Archive requirements:**
@@ -104,7 +106,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
 7. **Commit and tag:**
 
-   - Stage: milestones.md, project.md, roadmap.md, state.md, archive files
+   - Stage: milestones.md, project.md, roadmap.md, state.md, archive files, and the deleted requirements.md, and commit with `--force` (the user confirmed the milestone in step 1): `pan-tools commit` refuses any pending deletion, staged or not (`deleted_files_detected`), unless git pairs it with the archive as a rename
    - Commit: `chore: archive v{{version}} milestone`
    - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
    - Ask about pushing tag
@@ -116,10 +118,11 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
    ```bash
    node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null || true
-   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn 2>/dev/null || true
+   # trace end cleared the active-session pointer, so pool the recent sessions
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn --sessions 5 2>/dev/null || true
    ```
 
-   Present the optimization summary to the user and suggest `/pan:optimize apply` to write memory entries.
+   Present the optimization summary to the user and suggest `/pan:optimize apply` to record its suggestions, each naming where a person should make the change.
 
 </process>
 

package/commands/pan/milestone-new.md

@@ -22,7 +22,7 @@ Brownfield equivalent of new-project. Project exists, project.md has history. Ga
 - `.planning/roadmap.md` — phase structure (continues numbering)
 - `.planning/state.md` — reset for new milestone
 
-**After:** `/pan:design-phase [N]` → `/pan:plan-phase [N]` to design then plan the first phase.
+**After:** `/pan:discuss-phase [N]` (then, optionally, `/pan:design-phase [N]`) → `/pan:plan-phase [N]` for the first phase.
 
 **Design altitude (ADR-0042):** product/strategic design — demand validation, competitive intelligence, market positioning — belongs HERE at milestone creation (via the requirements/research cycle, or `/pan:focus-design` for a strategic feature), done ONCE. Per-phase architecture/ADR/threat design is `/pan:design-phase`, run per phase. Do not defer product questions to per-phase design, and do not re-open them there.
 </objective>

package/commands/pan/new-project.md

@@ -12,7 +12,7 @@ allowed-tools:
 ---
 <context>
 **Flags:**
-- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
+- `--auto` — Automatic mode. Asks no questions: applies the auto-mode defaults (idea.md frontmatter can override them), then runs research → requirements → roadmap without interaction. Needs an idea document — an @ reference, or the idea pasted after the flag.
 </context>
 
 <objective>
@@ -26,7 +26,7 @@ Initialize a new project through unified flow: questioning → research (optiona
 - `.planning/roadmap.md` — phase structure
 - `.planning/state.md` — project memory
 
-**After this command:** Run `/pan:plan-phase 1` to start execution.
+**After this command:** Run `/pan:discuss-phase 1` to gather context, or `/pan:plan-phase 1` to plan directly. With `--auto` the workflow continues into `/pan:discuss-phase 1 --auto` itself.
 </objective>
 
 <execution_context>
@@ -68,23 +68,23 @@ Use this decision tree to select the correct path. Evaluate conditions top-to-bo
 
 ```
 IF .planning/ already exists AND contains project.md:
-  → WARN: "Project already initialized. Use /pan:resume to continue."
+  → WARN: "Project already initialized. Use /pan:progress to continue."
   → STOP (do not overwrite existing project)
 
-ELSE IF --auto flag AND @ reference document provided:
-  → ASK config questions only (commit_docs, model_profile)
-  → SKIP interactive questioning (use the @ document as project context)
+ELSE IF --auto flag AND an idea document provided (@ reference or pasted text):
+  → ASK nothing: apply the auto-mode defaults (workflow step 2a; idea.md frontmatter can override them)
+  → SKIP interactive questioning (use the document as project context)
   → RUN research automatically
-  → GENERATE requirements from research + @ document
+  → GENERATE requirements from research + the document
   → GENERATE roadmap from requirements
   → No further interaction until complete
 
-ELSE IF --auto flag WITHOUT @ reference:
-  → ERROR: "--auto requires an @ referenced idea document"
+ELSE IF --auto flag WITHOUT an idea document:
+  → ERROR: "--auto requires an idea document" (an @ reference, or the idea pasted after the flag)
   → STOP
 
 ELSE (interactive mode — default):
-  → RUN questioning flow (5-area deep questioning)
+  → RUN questioning flow (freeform deep questioning — references/questioning.md)
   → ASK: "Should I research the domain ecosystem?" (Y/N)
     → IF Y: spawn researchers → synthesize → continue
     → IF N: skip research → continue

package/commands/pan/optimize.md

@@ -1,7 +1,8 @@
 ---
 name: pan:optimize
 group: Self-Improvement
-description: Manage the circular optimization loop — apply recommendations, view stats, list reports, manage trace sessions
+description: Manage the circular optimization loop — record a report's suggestions, undo them, view stats, list reports, manage trace sessions
+argument-hint: "apply [--report <file>] | revert <apply_id> | revert --last | list | stats | trace init|end|current|list"
 allowed-tools:
   - Read
   - Write
@@ -13,7 +14,7 @@ allowed-tools:
 
 # /pan:optimize
 
-Manage the circular optimization loop: apply recommendations, view stats, list reports.
+Manage the circular optimization loop: record a report's suggestions, view stats, list reports.
 
 **Usage:**
 ```
@@ -32,14 +33,15 @@ Manage the circular optimization loop: apply recommendations, view stats, list r
 **Subcommands:**
 
 ### apply
-Apply safe optimizations from the most recent (or specified) optimization report.
+Record the suggestions from the most recent (or specified) optimization report.
 
-Auto-applied automatically:
-- New memory entries (`.planning/memory/*.md`) — skipped if file already exists
-- Suggestions appended to `.planning/optimization/suggestions.md`
+Recorded automatically:
+- Suggestions appended to `.planning/optimization/suggestions.md`: lessons, prompt changes and workflow changes, each naming where it belongs
 - Config notes appended to `.planning/optimization/config-suggestions.md`
+- An older report's memory actions (`memory_entry`, `memory`, `memory_append`) still write to `.planning/memory/`, a `memory_entry` only if it passes the checks of the `memory record` command. The result warns that PAN's workflows do not load that folder into agents
 
-Requires human review (never auto-applied):
+A person makes every change the suggestions describe (never auto-applied):
+- Lessons, written into the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, or a comment at the cited code
 - Agent prompt changes
 - Workflow step additions
 - Structural changes to commands
@@ -47,7 +49,7 @@ Requires human review (never auto-applied):
 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).
+Undo one apply exactly: delete the 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.
@@ -63,12 +65,12 @@ List all optimization reports in `.planning/optimization/reports/`, most recent
 Show cumulative optimization statistics:
 - Total trace sessions run
 - Total events traced
-- Total errors/gaps/redundancies seen
+- Total errors seen (`total_errors_traced`; gaps and redundancies are not totalled)
 - 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
-Start a new trace session before running a build. The hook fires automatically on SubagentStop, but calling `trace init` first lets you attach a description to the session.
+Start a trace session before running a build — or join the active one: `trace init` reuses an unended session started within the last hour (`reused: true`, keeping that session's description) instead of opening a new one. The hook fires automatically on SubagentStop, but calling `trace init` first lets you attach a description to a new session.
 
 ```
 /pan:optimize trace init --description "building express web server"
@@ -80,7 +82,7 @@ Start a new trace session before running a build. The hook fires automatically o
 Finalize the current trace session (writes summary stats to session.json).
 
 ### trace current
-Show the active trace session ID and event count.
+Show the active trace session ID (`optimize trace current` returns only `session_id` and `active`; `trace list` carries each session's event count).
 
 ### trace list
 List all trace sessions, most recent first.
@@ -98,14 +100,14 @@ List all trace sessions, most recent first.
 │         ↓                                          │
 │  /pan:learn           ← analyze + report           │
 │         ↓                                          │
-│  /pan:optimize apply  ← write memory entries       │
+│  /pan:optimize apply  ← record suggestions         │
 │         ↓                                          │
-│  Next run is smarter  ← memory populated           │
+│  You make the changes ← instructions, tests, code  │
 │         ↑                                          │
 │         └──────────────────────────────────────────┘
 └─────────────────────────────────────────────────────┘
 ```
 
-Each iteration improves the model's context: fewer memory misses, fewer repeated errors, better decisions.
+Each iteration puts what the last run lacked where the next run's agents read it: fewer repeated errors and gaps.
 
 **See also:** `/pan:learn`, `/pan:exec-phase`

package/commands/pan/patches.md

@@ -23,12 +23,8 @@ After a PAN update wipes and reinstalls files, this command merges user's previo
 Check for local patches directory:
 
 ```bash
-# Global install (path templated at install time)
+# This install's own dir — the installer templates ~/.claude/ to it, local or global
 PATCHES_DIR=~/.claude/pan-local-patches
-# Local install fallback
-if [ ! -d "$PATCHES_DIR" ]; then
-  PATCHES_DIR=~/.claude/pan-local-patches
-fi
 ```
 
 Read `backup-meta.json` from the patches directory.
@@ -61,7 +57,7 @@ Exit.
 
 For each file in `backup-meta.json`:
 
-1. **Read the backed-up version** (user's modified copy from `pan-local-patches/`)
+1. **Read the backed-up version** (user's modified copy from `pan-local-patches/<file>`; a file listed in `backup-meta.json`'s `external_files` — a Codex skill under `../.agents/skills/` — is at `pan-local-patches/` + the path that map gives)
 2. **Read the newly installed version** (current file after update)
 3. **Compare and merge:**
 

package/commands/pan/pause.md

@@ -74,7 +74,7 @@ context:
 The workflow handles all logic including:
 1. Phase directory detection
 2. State gathering with user clarifications
-3. Handoff file writing with timestamp — **using the schema from `<handoff_schema>`**
+3. Handoff file writing with timestamp — **using the schema from `<handoff_schema>`, in place of the format in the workflow's write step and `templates/continue-here.md`** (`/pan:resume` parses this schema's fields)
 4. Git commit
 5. Confirmation with resume instructions
 </process>

package/commands/pan/phase-tests.md

@@ -30,7 +30,8 @@ Output: Test files committed with message `test(phase-{N}): add unit and E2E tes
 Phase: $ARGUMENTS
 
 @.planning/state.md
-@.planning/roadmap.md
+
+This phase's goal and requirements, if the workflow needs them: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice <phase> --raw`, with only the phase number from $ARGUMENTS, since the instructions after it are free text that can break a shell line (the whole roadmap.md only for something it leaves out).
 </context>
 
 <process>