pan-wizard 2.9.1 → 3.5.0

package/commands/pan/git.md

@@ -0,0 +1,223 @@
+---
+name: pan:git
+group: Git Workflow
+description: Safe, phase-aware git workflow commands — commit, branch, push, status, log, stash, diff, rollback, tag, sync
+argument-hint: "<subcommand> [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+---
+
+<objective>
+Phase-aware git workflow with safety guardrails built in. Every subcommand that modifies history runs safety checks. Rollback uses PAN snapshot tags created by exec-phase.
+
+Works with any git repository — PAN installation not required.
+</objective>
+
+<subcommands>
+
+## Subcommands
+
+| Subcommand | Usage | What it does |
+|------------|-------|--------------|
+| `commit` | `git commit --type feat --message "add X"` | Safe commit: checks deleted files + secrets, conventional type prefix |
+| `branch` | `git branch create --phase 3` | Create / switch / list / delete branches; phase-aware naming |
+| `push` | `git push [--remote origin] [--branch main]` | Push with remote validation; requires `--force` for force-push |
+| `status` | `git status` | Branch + staged/unstaged/untracked counts |
+| `log` | `git log [--count 20]` | Formatted history, default 10 entries |
+| `stash` | `git stash save --name "WIP auth"` | Named stash save / pop / list / drop |
+| `diff` | `git diff [--staged] [--file path]` | Diff with line counts |
+| `rollback` | `git rollback [--tag pan-rollback-X] [--dry-run]` | Reset to PAN snapshot tag |
+| `tag` | `git tag list [--pattern v*]` | List / create / delete tags |
+| `sync` | `git sync [--rebase]` | Fetch + pull from origin |
+
+</subcommands>
+
+<workflow>
+
+## Execution
+
+Run the appropriate subcommand via pan-tools:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git <subcommand> [opts]
+```
+
+Or invoke directly in conversation: `/pan:git <subcommand> [opts]`
+
+---
+
+### commit — Safe Commit
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git commit \
+  --type feat --message "implement user auth"
+```
+
+**Options:**
+- `--type` — `feat | fix | docs | test | refactor | 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
+
+**Safety checks run automatically:**
+
+| Check | Blocks on | Override |
+|-------|-----------|---------|
+| Deleted files | Staged deletions found | `--force` |
+| Sensitive files | `.env`, `.pem`, `.key`, `secret`, `password`, `token` | `--force` |
+
+**Output:** `{committed, hash, type, safety_checks}`
+
+---
+
+### branch — Branch Management
+
+```bash
+# Phase-aware branch (names as pan/phase-3)
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch create --phase 3
+
+# Custom name
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch create --name feature/auth
+
+# Switch
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch switch --name main
+
+# List all branches
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch list
+
+# Delete (safe — merged only)
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch delete --name feature/old
+
+# Delete unmerged (force)
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch delete --name feature/old --force
+
+# Current branch
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch current
+```
+
+**Phase naming convention:** `pan/phase-{N}` — matches `phase_branch_template` in `.planning/config.json`
+
+---
+
+### push — Safe Push
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git push
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git push --remote upstream --branch main
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git push --force  # requires explicit flag
+```
+
+**Output:** `{pushed, remote, branch, force}`
+
+---
+
+### status — Phase-Aware Status
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git status
+```
+
+**Output:** `{branch, clean, staged_count, unstaged_count, untracked_count, files}`
+
+---
+
+### log — Commit History
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git log --count 20
+```
+
+**Output:** `{commits: [{hash, message}], total}`
+
+---
+
+### stash — Named Stash
+
+```bash
+# Save
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git stash save --name "WIP: auth refactor"
+
+# List all stashes
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git stash list
+
+# Pop latest
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git stash pop
+
+# Pop by index
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git stash pop --index 1
+
+# Drop
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git stash drop --index 0
+```
+
+---
+
+### diff — Staged/Unstaged Diff
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git diff
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git diff --staged
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git diff --staged --file src/api.js
+```
+
+**Output:** `{diff, lines_added, lines_removed, files_changed}`
+
+---
+
+### rollback — Revert to PAN Snapshot
+
+```bash
+# Rollback to latest PAN snapshot tag (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
+```
+
+**Rollback workflow:**
+1. Lists all `pan-rollback-*` tags (created by exec-phase before wave execution)
+2. Verifies working tree is clean (blocks on dirty tree unless `--dry-run`)
+3. Runs `git reset --hard <tag>`
+
+**Output:** `{rolled_back, tag, hash, dry_run}`
+
+---
+
+### tag — Tag Management
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git tag list
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git tag list --pattern "v*"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git tag create --name v3.6.0 --message "Release 3.6.0"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git tag delete --name v3.6.0-rc1
+```
+
+**Output:** `{tags, count}` / `{created, tag}` / `{deleted, tag}`
+
+---
+
+### sync — Pull from Upstream
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git sync
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git sync --rebase
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git sync --remote upstream --branch main
+```
+
+**Output:** `{synced, remote, branch, rebase, commits_received}`
+
+</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).
+</runtime_note>

package/commands/pan/knowledge.md

@@ -0,0 +1,129 @@
+---
+name: pan:knowledge
+group: Knowledge
+description: Grounded Q&A, multi-turn design discussion, and playbook generation. Three modes in one command.
+argument-hint: "ask <question> | discuss <phase> <topic> | playbook"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+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.
+- **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.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/knowledge.cjs
+@~/.claude/agents/pan-knowledge.md
+@~/.claude/pan-wizard-core/templates/playbook.md
+</execution_context>
+
+<modes>
+
+### `ask <question>`
+
+```
+/pan:knowledge ask "why does phase 4 have a race condition fix?"
+```
+
+**Flow:**
+1. `pan-tools knowledge ask "<question>"` returns a ranked list of candidate files.
+2. Spawn `pan-knowledge` with `<mode>ask</mode>`, the question, and the top sources as `<files_to_read>`.
+3. Agent reads sources, answers with citations, returns the answer to stdout. No file is written.
+
+**Output:** inline markdown answer with `[file.md:LINE]` and `[ADR-NNNN]` citations.
+
+### `discuss <phase> <topic-or-question>`
+
+```
+/pan:knowledge discuss 12 "should we use Redis or Memcached?"
+```
+
+**Flow:**
+1. `pan-tools knowledge discuss <phase> --subcmd read` loads session state from `.planning/conversations/<phase>/session.json` (empty for new phase).
+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.
+
+**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.
+
+### `playbook`
+
+```
+/pan:knowledge playbook
+```
+
+**Flow:**
+1. `pan-tools knowledge playbook` reads all agents' memory (`.planning/memory/*.md`), 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.
+
+</modes>
+
+<workflow>
+
+**Onboarding a new team member:** have them run `/pan:knowledge playbook` then `/pan:knowledge ask "what conventions matter in this codebase?"`.
+
+**Design debate:** run `/pan:knowledge discuss <phase> "<question>"` iteratively. The agent refines as the debate narrows. After convergence, accept the proposed `context.md` update.
+
+**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.
+
+</workflow>
+
+<citation_format>
+
+Agent output uses bracketed citations that link to files. Supported forms:
+
+| Form | Example | Renders as |
+|------|---------|-----------|
+| Plain file | `[README.md]` | markdown link to the file |
+| File + line | `[docs/ARCHITECTURE.md:200]` | link to line 200 |
+| ADR | `[ADR-0015]` | link to ADR file |
+| Phase artifact | `[phase-4/summary.md]` | link to phase summary |
+
+The agent should NEVER fabricate citations. The retrieval layer's `sources` list is the allowlist.
+
+</citation_format>
+
+<runtime_compatibility>
+
+| Runtime | ask | discuss | playbook |
+|---------|-----|---------|----------|
+| Claude Code | Full, thinking enabled | Full, prompt caching bonus | Full |
+| OpenCode | Full | Full (no cache bonus) | Full |
+| Gemini | Full | Full | Full |
+| Codex | Full | Full | Full |
+| Copilot | Full | Full | Full |
+
+The data layer (retrieval, session state, playbook clustering) is pure Node.js and runtime-agnostic. Only answer synthesis quality varies with model capability.
+
+</runtime_compatibility>
+
+<privacy_note>
+
+`session.json` is persisted to disk and committed unless `.planning/conversations/` is gitignored. For sensitive design discussions, consider:
+
+```
+echo '.planning/conversations/' >> .gitignore
+```
+
+before starting a `discuss` session. Session turns are not auto-encrypted.
+
+</privacy_note>

package/commands/pan/learn.md

@@ -0,0 +1,61 @@
+# /pan:learn
+
+Analyze the most recent trace session and generate an optimization report.
+
+**Usage:**
+```
+/pan:learn
+/pan:learn --session <session-id>
+/pan:learn --apply
+```
+
+**Flags:**
+- `--session <id>` — analyze a specific session instead of the most recent
+- `--apply` — automatically apply safe optimizations after generating the report (equivalent to running `/pan:optimize apply` immediately after)
+
+**What it does:**
+
+1. Reads trace events from `.planning/optimization/traces/{session}/trace.jsonl`
+2. Performs local analysis (error/gap/redundancy patterns, agent stats)
+3. Writes `.planning/optimization/reports/{session}-analysis.json`
+4. Invokes `pan-optimizer` agent to produce `.planning/optimization/reports/{session}-opt-report.md`
+5. If `--apply` flag: immediately runs `/pan:optimize apply` on the new report
+6. Prints the optimization summary
+
+**When to run:**
+- After any `/pan:exec-phase` or `/pan:focus-exec` that had a trace session active
+- After a full build cycle to capture all decisions and errors
+- On demand to understand what PAN did and how to make it smarter
+
+**What it learns from:**
+- 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)
+- 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
+- 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`
+- A circular optimization score (0–100)
+
+**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
+→ Needs review: 2 prompt improvements, 1 workflow gap
+```
+
+**See also:** `/pan:optimize`, `/pan:exec-phase`
+
+Follow the workflow at `.claude/workflows/learn.md` (or `pan-wizard-core/workflows/learn.md`).

package/commands/pan/map-codebase.md

@@ -49,6 +49,21 @@ Check for .planning/state.md - loads context if project already initialized
 - Trivial codebases (<5 files)
 </when_to_use>
 
+<stage_0_ingest_mode>
+**Before spawning mapper agents**, determine whether the repo fits in a single 1M-context window.
+
+Run: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs codebase estimate-size --threshold 700000`
+
+The CLI returns `{mode, total_tokens, file_count, languages}`:
+
+- **`mode: "single-shot"`** — repo is small enough (≤700K tokens) for one Opus 4.7 agent 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 gets a 200K budget.
+
+Record the chosen mode + telemetry in the final `.planning/codebase/overview.md` so future runs can reason about drift.
+
+Opus 4.7 is required for single-shot mode (only model with a 1M context window). Other models always take the sharded path regardless of size.
+</stage_0_ingest_mode>
+
 <tool_priority>
 Each mapper agent should use the simplest sufficient tool:
 1. Glob — discover files by pattern (find all .ts files, config files, test files)

package/commands/pan/mcp-bridge.md

@@ -0,0 +1,145 @@
+---
+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>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<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.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/bridge.cjs
+</execution_context>
+
+<subcommands>
+
+### `list`
+
+Show cached MCP tools with server grouping and schemas.
+
+```
+/pan:mcp-bridge list
+```
+
+**Output (JSON):**
+```json
+{
+  "cached_at": "2026-04-18T12:34:56Z",
+  "runtime": "claude",
+  "server_count": 3,
+  "tool_count": 12,
+  "tools": [
+    { "server": "linear", "name": "linear.updateTicket", "description": "...", "schema": {...} },
+    ...
+  ],
+  "source": "cache" | "empty"
+}
+```
+
+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.
+
+### `recommend <phase>`
+
+Given a phase number, match cached MCP tools against the phase's plan text and return tools ranked by keyword relevance.
+
+```
+/pan:mcp-bridge recommend 7
+/pan:mcp-bridge recommend 12 --max 5 --min-score 2
+```
+
+**Flags:**
+- `--max N` — cap recommendations (default 10)
+- `--min-score N` — minimum keyword hit count (default 1)
+
+**Output (JSON):**
+```json
+{
+  "phase": "7",
+  "phase_name": "API refactor",
+  "runtime": "claude",
+  "total_candidates": 12,
+  "recommendations": [
+    {
+      "server": "linear",
+      "name": "linear.updateTicket",
+      "description": "Update a Linear issue",
+      "score": 3,
+      "hits": ["linear", "ticket", "update"]
+    }
+  ]
+}
+```
+
+Scoring is naive keyword frequency with word boundaries — not semantic embeddings. A tool's name and description are tokenized into keywords (≥3 chars); each match in the phase plan text scores 1 point.
+
+### `cache`
+
+Write or inspect the MCP tools cache at `.planning/bridge/available-tools.json`.
+
+```
+# Inspect current cache (same as `list` but raw)
+/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.
+
+</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 — `.claude/settings.json` for Claude Code, or the runtime's equivalent.
+
+**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.
+
+**Pre-milestone review:** walk through each remaining phase with `/pan:mcp-bridge recommend` to catch "we should have automated this via Linear/Slack/etc." realizations before shipping.
+
+</workflow>
+
+<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.
+
+**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 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.
+
+</caveats>
+
+<runtime_compatibility>
+
+| 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 |
+
+On non-Claude runtimes, the aggregator and recommendation logic still work — they just report zero tools until something populates the cache.
+
+</runtime_compatibility>
+
+<future_scope>
+
+Explicitly deferred from v3.3 (documented in ADR-0023 / 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.
+
+Until those land, this command is the minimum viable integration: you see what's there, you get suggestions, you decide manually.
+
+</future_scope>

package/commands/pan/milestone-done.md

@@ -111,6 +111,15 @@ Output: Milestone archived (roadmap + requirements), project.md evolved, git tag
 8. **Offer next steps:**
    - `/pan:milestone-new` — start next milestone (questioning → research → requirements → roadmap)
 
+9. **Circular optimization — summarize what was learned this milestone:**
+
+   ```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
+   ```
+
+   Present the optimization summary to the user and suggest `/pan:optimize apply` to write memory entries.
+
 </process>
 
 <success_criteria>

package/commands/pan/optimize.md

@@ -0,0 +1,86 @@
+# /pan:optimize
+
+Manage the circular optimization loop: apply recommendations, view stats, list reports.
+
+**Usage:**
+```
+/pan:optimize apply
+/pan:optimize apply --report <filename>
+/pan:optimize list
+/pan:optimize stats
+/pan:optimize trace init [--description "what you're building"]
+/pan:optimize trace end
+/pan:optimize trace status
+/pan:optimize trace list
+```
+
+**Subcommands:**
+
+### apply
+Apply safe optimizations 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`
+- Config notes appended to `.planning/optimization/config-suggestions.md`
+
+Requires human review (never auto-applied):
+- Agent prompt changes
+- Workflow step additions
+- Structural changes to commands
+
+After applying, the report lists what was applied and what still needs review.
+
+### list
+List all optimization reports in `.planning/optimization/reports/`, most recent first.
+
+### stats
+Show cumulative optimization statistics:
+- Total trace sessions run
+- Total events traced
+- Total errors/gaps/redundancies seen
+- Total optimizations applied across all runs
+- 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.
+
+```
+/pan:optimize trace init --description "building express web server"
+/pan:exec-phase 1
+/pan:learn
+```
+
+### trace end
+Finalize the current trace session (writes summary stats to session.json).
+
+### trace status
+Show the active trace session ID and event count.
+
+### trace list
+List all trace sessions, most recent first.
+
+---
+
+**The circular loop:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│                                                     │
+│  /pan:optimize trace init                           │
+│         ↓                                          │
+│  /pan:exec-phase N    ← agents run, hook traces    │
+│         ↓                                          │
+│  /pan:learn           ← analyze + report           │
+│         ↓                                          │
+│  /pan:optimize apply  ← write memory entries       │
+│         ↓                                          │
+│  Next run is smarter  ← memory populated           │
+│         ↑                                          │
+│         └──────────────────────────────────────────┘
+└─────────────────────────────────────────────────────┘
+```
+
+Each iteration improves the model's context: fewer memory misses, fewer repeated errors, better decisions.
+
+**See also:** `/pan:learn`, `/pan:exec-phase`