pan-wizard 3.4.1 → 3.5.1

package/commands/pan/focus-auto.md

@@ -58,8 +58,10 @@ Which category should this auto campaign focus on?
 5. **docs** — Stale documentation, missing command descriptions (P5-P6)
 6. **optimize** — Performance bottlenecks, redundant computation, robustness hardening (P1-P4)
 7. **prompts** — Execute micro-prompt documents sequentially, or generate them from specs (P0-P6)
+8. **security** — OWASP Top 10 violations, STRIDE threats, auth/injection/crypto hardening (P0-P2)
+9. **distill** — AI code-bloat: phantom try/catch, unused imports, repeated blocks, premature abstraction, god functions (P1-P5)
 
-Reply with a number (1-7) or category name.
+Reply with a number (1-9) or category name.
 ```
 
 **After the user replies, map their response to a category name:**
@@ -70,6 +72,8 @@ Reply with a number (1-7) or category name.
 - "5" or "docs" → SELECTED_CATEGORY = docs
 - "6" or "optimize" → SELECTED_CATEGORY = optimize
 - "7" or "prompts" → SELECTED_CATEGORY = prompts
+- "8" or "security" → SELECTED_CATEGORY = security
+- "9" or "distill" → SELECTED_CATEGORY = distill
 
 Wait for the user's reply before proceeding. Do not guess or pick a default category.
 
@@ -85,11 +89,12 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 ```
 /pan:focus-auto [--category CAT] [--mode MODE] [--budget N] [--max-cycles N]
                 [--total-budget N] [--continue] [--stop] [--status] [--dry-run]
+                [--deep-review]
 ```
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--category` | null (all) | cleanup, tests, stability, features, docs, optimize, prompts |
+| `--category` | null (all) | cleanup, tests, stability, features, docs, optimize, prompts, security, distill |
 | `--mode` | category-dependent | bugfix, balanced, features, full |
 | `--budget` | category-dependent | Points per cycle (5-100) |
 | `--max-cycles` | 10 | Maximum iterations (1-50) |
@@ -98,6 +103,7 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 | `--stop` | — | Gracefully stop active run |
 | `--status` | — | Show current campaign progress |
 | `--dry-run` | — | Show plan without executing |
+| `--deep-review` | off | After every exec cycle, run inline OWASP security check on changed files. Verdict `block` or `review_required` stops the campaign (6th safety harness). Works with all categories. |
 
 ## Category Defaults
 
@@ -110,6 +116,7 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 | docs | P5-P6 | balanced | 30 |
 | optimize | P1-P4 | balanced | 50 |
 | prompts | P0-P6 | balanced | 100 |
+| security | P0-P2 | bugfix | 40 |
 
 ## Pipeline
 
@@ -173,6 +180,11 @@ Perform a deep codebase scan to find actionable work items with evidence.
   - **features:** roadmap items not yet implemented, README promises without backing code
   - **docs:** stale documentation, missing command descriptions
   - **optimize:** N+1 operations (file I/O / network calls inside loops), redundant re-computation (`JSON.parse`/`stringify` of same data), synchronous blocking in async modules (`readFileSync`/`execSync` alongside async exports), algorithmic complexity (nested `.find()`/`.filter()` in loops creating O(n²)+), unnecessary allocations in hot paths (spread in loops, string concat vs `join()`), regex construction inside loops (should be hoisted), unbounded collection growth (`.push()` without size limits), swallowed errors (`catch {}` / `catch { /* */ }`), suboptimal data structures (array `.includes()` where Set is better), dead assignments, unguarded property access on nullable values (`.length`/`.split()`/`.match()[0]` without null check)
+  - **security:** Three-pass approach:
+    - **Pass 1 — Injection & crypto (inline grep):** Scan source files for `eval(`, `execSync`, `exec(`, string concatenation in SQL patterns (`` `SELECT...${`` / `"SELECT..."+`), `md5(`/`sha1(`/`createHash('md5'`/`createHash('sha1'`, hardcoded secrets (`password\s*=\s*['"]`, `api_key\s*=\s*['"]`, `secret\s*=\s*['"`), `Math.random()` used for security purposes.
+    - **Pass 2 — Auth & access control (inline grep):** Routes without auth middleware (look for `router.get/post/put/delete` without preceding `app.use(...auth...)`), `req.params.id` used directly without ownership check, `JSON.parse(` on `req.body` without schema validation, CORS `origin: '*'` or `Access-Control-Allow-Origin: *`, verbose errors that expose stack traces (`res.json({ stack:`).
+    - **Pass 3 — Semantic depth (Agent tool, optional):** For M/L items where grep found a suspicious pattern but fix guidance needs code-path tracing, use the Agent tool with Explore subagent to read the specific file and confirm exploitability before including in the batch.
+    - **Classification:** Map findings to priorities: OWASP critical/exploit-ready → P0, High/auth-bypass → P1, Medium/defense-in-depth → P2. Drop LOW/INFO — they don't meet the P0-P2 filter.
   - **prompts:** Two operational modes — detect which applies:
     - **Execute mode:** Find micro-prompt documents (`.md` files containing ordered prompt blocks, e.g., `## Prompt 1`, `## Prompt 2`, or numbered checklist items `- [ ] Prompt: ...`). Look in `.planning/`, project root, and `docs/` for files matching patterns: `*prompts*`, `*micro-prompt*`, `*prompt-plan*`, `*prompt-sequence*`. Each unchecked/incomplete prompt block is one work item.
     - **Generate mode:** Find specification documents (files matching `*spec*`, `*prd*`, `*requirements*`, `*feature*` in `.planning/`, `docs/specs/`, project root) that do NOT already have a corresponding micro-prompt document. Each spec needing decomposition is one work item.
@@ -271,6 +283,32 @@ A failed item never blocks subsequent items.
 5. Stage specific changed files (not `git add -A`) and commit with accurate message listing only verified items
 6. Count: `items_completed`, `items_failed`, `points_used`
 
+**If `--deep-review` flag is active (run after commit, before recording cycle):**
+
+Get changed files from this cycle's commit:
+```bash
+CHANGED=$(git diff HEAD~1 --name-only 2>/dev/null | grep -E '\.(js|ts|jsx|tsx|py|go|rb|java|php)$')
+```
+
+Run inline OWASP security check on changed files only:
+- Grep each changed file for critical patterns:
+  - Injection: `eval(`, `execSync(`, SQL string concat (`` `SELECT...${`` ), `child_process.exec(`
+  - Crypto: `createHash('md5'`, `createHash('sha1'`, `Math.random()` near auth/token/secret context
+  - Auth bypass: routes with no auth guard added, `req.params` used as DB key without ownership check
+  - Secrets: `password\s*=\s*['"]`, `apiKey\s*=\s*['"]`, `token\s*=\s*['"]` assigned to a literal value
+- Score findings by severity: critical (exploit-ready) → BLOCK; high (auth/injection surface) → WARN; medium/low → LOG
+
+**Handle deep-review verdict:**
+
+| Severity found | Verdict | Action |
+|---------------|---------|--------|
+| Critical pattern in changed file | `block` | STOP campaign — do NOT record cycle, revert last commit, present finding to user |
+| High pattern in changed file | `review_required` | STOP campaign — record cycle as completed, flag finding, recommend manual review |
+| Medium/low only | `ok_with_minor` | Continue — append findings to `.planning/focus/security-log-<date>.md` |
+| No patterns | `ok` | Continue silently |
+
+Write all non-ok findings to `.planning/focus/security-log-<date>.md` with file:line references.
+
 #### Step 2.4: Record Cycle
 
 Run: `pan-tools focus auto --update --items-completed N --items-failed N --points-used N --tests-before N --tests-after N --batch-file <path>`
@@ -282,6 +320,8 @@ Check the response for stop conditions:
 - `zero_completed`: No items completed in this cycle — go to Phase 3
 - `diminishing_returns`: Optimize only — cycle efficiency < 30% of previous cycle — go to Phase 3
 - `prompts_complete`: Prompts only — all prompts in document executed — go to Phase 3
+- `security_complete`: Security only — scan found no HIGH/CRITICAL items remaining — go to Phase 3
+- `deep_review_block`: `--deep-review` only — critical pattern detected in changed files — go to Phase 3 with warning
 - `null`: Continue to next cycle
 
 #### Step 2.5: Inter-Cycle Context Management
@@ -341,7 +381,7 @@ Then continue immediately to the next cycle (back to Step 2.1).
 
 3. Remove safety tag: `git tag -d focus-auto-baseline 2>/dev/null`
 
-## 5-Layer Safety Harness
+## 6-Layer Safety Harness
 
 | Layer | Mechanism | Action |
 |-------|-----------|--------|
@@ -350,6 +390,7 @@ Then continue immediately to the next cycle (back to Step 2.1).
 | Iteration limit | `--max-cycles N` | Hard stop on loop count |
 | Regression circuit breaker | tests_after < tests_before | Immediate stop, status=stopped |
 | Zero-completed guard | 0 items done in a cycle | Stop — further cycles won't help |
+| Security gate (`--deep-review`) | Critical/high OWASP pattern in changed files | Revert last commit (critical) or flag for manual review (high), stop campaign |
 
 ## 9 Behavioral Rules
 
@@ -448,6 +489,112 @@ When a specification document is found that doesn't have a matching micro-prompt
 
 **After generation:** The document is written and committed. The next cycle will detect it in execute mode and begin executing prompts sequentially.
 
+## Security Category — Execution Details
+
+The security category scans for OWASP Top 10 (2025) violations and STRIDE threats, then fixes them cycle by cycle until the scan returns zero HIGH/CRITICAL findings.
+
+### Scan approach (Step 2.1)
+
+Three passes per cycle:
+
+**Pass 1 — Fast grep scan (always runs):**
+
+| OWASP | Grep pattern | Priority |
+|-------|-------------|---------|
+| A03 Injection | `eval(`, `execSync(`, `` `SELECT.*\${ ``, `child_process.exec(` | P0 |
+| A02 Crypto | `createHash\(['"]md5\|sha1`, `Math\.random\(\)` near auth/token | P0 |
+| A01 Access | Route without auth middleware, IDOR (raw `req.params.id` to DB) | P1 |
+| A05 Misconfig | `origin:\s*['"]?\*`, `Access-Control-Allow-Origin: \*`, stack in response | P1 |
+| A07 Auth | No session expiry, credentials in URL params | P1 |
+| A04 Design | Missing rate-limit on auth/payment endpoints | P2 |
+| A09 Logging | Security events (`login`, `payment`, `admin`) with no log call nearby | P2 |
+
+**Pass 2 — Structural check (always runs):**
+- Read route files and check: does every mutating endpoint (POST/PUT/PATCH/DELETE) have auth middleware before the handler?
+- Check for hardcoded secrets: grep for `['"][A-Za-z0-9_]{20,}['"]` assigned to variables named `key`/`token`/`secret`/`password`/`apiKey`
+- Check for prototype pollution risk: `Object.assign(req.body)` or spread from untrusted input into a stored object
+
+**Pass 3 — Semantic depth (Agent tool, for M/L items only):**
+When a pattern match needs code-path confirmation, spawn an Explore subagent:
+> "Read [file]. Confirm whether [line N] is reachable from an unauthenticated request path and whether the input is sanitized before use."
+
+Use the confirmation to decide whether to include the item at P0/P1 or drop it as a false positive.
+
+### Item classification
+
+| Hardener severity | Focus priority | Example |
+|------------------|----------------|---------|
+| Critical | P0 | `eval(req.body.code)` — direct RCE |
+| High | P1 | Auth bypass on admin route |
+| Medium | P2 | Rate-limiting absent on login |
+| Low / Info | DROP | Missing security header on non-sensitive route |
+
+### Execution (Step 2.3)
+
+Treat each security item as a STANDARD or FULL item regardless of effort estimate:
+
+1. **State threat:** "This is [OWASP category]. The exploit path is: [attacker does X → Y → data/system compromised]."
+2. **Read the file** — confirm the pattern is real, not a false positive
+3. **Implement the fix** — use established patterns (parameterized queries, allowlists, bcrypt, rate-limit middleware)
+4. **Write or update the test** — every security fix MUST have a test that proves the vulnerability is closed (e.g., send the malicious payload, assert 400/403 not 200)
+5. **Run full test suite** — regression check before marking DONE
+
+### Stop condition
+
+`security_complete` fires when the scan finds zero P0/P1 items. P2 items (medium) may remain — they won't stop the campaign unless `zero_completed` fires (no items at all).
+
+A security campaign that ends with `security_complete` means: no critical or high OWASP violations found in the scanned files. Medium/low items can be addressed in subsequent targeted passes or documented as accepted risk.
+
+---
+
+## Distill Category — Execution Details
+
+The `distill` category targets **AI-generated code bloat** with a 5-pass pipeline based on the SOTA agentic-refactoring architecture (deterministic-first, LLM-on-narrow-spans).
+
+### Pipeline
+
+| Pass | What | Cost | Tier output |
+|------|------|------|-------------|
+| 1 | **Deterministic patterns** — phantom try/catch, unused imports, magic numbers, long functions, wide param lists | Free | safe / review |
+| 2 | **AST-style analysis** — single-instance factories, deep nesting | Free | review |
+| 3 | **Cross-file graph** — repeated 5+ line blocks, unreferenced exports | Free | review |
+| 4 | **LLM judgment** — pan-distiller agent receives ONLY flagged spans (max 50 lines context per finding); validates pattern, refines tier, proposes minimal rewrite | LLM tokens | safe / review / risky |
+| 5 | **Cross-session memory** — compares findings to `.planning/memory/distill-patterns.md`; flags **regressed** patterns ("we already fixed this") | Free | metadata |
+
+### Safety Tiers
+
+| Tier | Rule | Action |
+|------|------|--------|
+| `safe` | Deterministic, behavior-preserving (e.g., remove unused import) | Auto-applied |
+| `review_required` | Behavior preserved under invariants but human should verify | Surfaced to user |
+| `risky` | Cross-file impact or might surface latent bugs | Never auto-applied |
+
+A finding's confidence below 0.85 is automatically downgraded to `review_required` regardless of original tier.
+
+### Bloat Budget
+
+After each cycle, distill computes:
+- **touched_loc** — total LOC modified in cycle
+- **removable_loc** — sum of `loc_saved` across findings
+- **essential_loc** — touched_loc − removable_loc
+- **bloat ratio** — touched_loc / essential_loc
+
+Default threshold: **2.0x**. If a cycle's ratio exceeds threshold, the bloat budget gate flags it for review.
+
+### Stop condition
+
+`distill_complete` fires when the scan finds zero bloat findings. The codebase is fully distilled for the patterns the deterministic + AST + graph passes detect.
+
+### CLI
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs distill scan
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs distill analyze [--touched-loc N] [--bloat-threshold X]
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs distill report
+```
+
+`scan` returns findings. `analyze` adds bloat budget + regressed pattern detection. `report` writes findings to `.planning/memory/distill-patterns.md` for the next session.
+
 <failure_pattern_capture>
 When the same failure pattern appears in 2+ items within a campaign, capture it for future runs.
 

package/commands/pan/focus-exec.md

@@ -213,6 +213,12 @@ This catches emergent interactions: 5 "add try-catch" fixes might reveal the mod
 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
 
+**Circular optimization — init trace:**
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init \
+  --description "focus-exec session" --command "focus-exec" 2>/dev/null || true
+```
+
 **Record baseline:**
 ```
 baseline_version: <from package.json>
@@ -395,6 +401,11 @@ Unless `--no-commit`:
 - Record session summary (items completed, tests before/after, budget used)
 - Append error patterns if any failures occurred
 
+### 6.3.5 Circular optimization — end trace
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null || true
+```
+
 ### 6.4 Final Report
 
 ```markdown

package/commands/pan/focus-scan.md

@@ -58,6 +58,12 @@ When `/pan:focus-scan` is invoked, execute all phases without stopping. Do not a
 
 ## Phase 0: Orientation & Baseline Snapshot
 
+**Circular optimization — init trace:**
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init \
+  --description "focus-scan" --command "focus-scan" 2>/dev/null || true
+```
+
 ### 0.1 Read Current State
 Read these files to establish baseline:
 

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/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/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`