pan-wizard 3.4.1 → 3.5.1

package/pan-wizard-core/bin/pan-tools.cjs

@@ -164,6 +164,22 @@
  *   standards recommend                Recommend standards based on project.md
  *   standards phase-track <phase>      Show standards relevant to a phase
  *   standards tools [id]               List external scanning tools for standards
+ *
+ * Circular Optimization Loop:
+ *   optimize trace init                Start a new trace session
+ *     [--description "..."]
+ *   optimize trace end                 Finalize trace session + write summary
+ *   optimize trace current             Show active session ID
+ *   optimize trace list                List all sessions
+ *   optimize trace log                 Log a trace event to the active session
+ *     --type <type> --description "..." [--agent a] [--category c] [--impact i]
+ *   optimize learn [--session <id>]   Analyze session, write analysis JSON
+ *   optimize apply [--report <path>]  Apply safe recommendations from report
+ *   optimize list                     List optimization reports
+ *   optimize stats                    Cumulative optimization statistics
+ *
+ * Self-Learn:
+ *   learn [--session <id>]            Alias for optimize learn + invoke pan-optimizer
  */
 
 const fs = require('fs');
@@ -190,6 +206,9 @@ const reviewDeep = require('./lib/review-deep.cjs');
 const knowledge = require('./lib/knowledge.cjs');
 const whatif = require('./lib/whatif.cjs');
 const bridge = require('./lib/bridge.cjs');
+const optimize = require('./lib/optimize.cjs');
+const git = require('./lib/git.cjs');
+const distill = require('./lib/distill.cjs');
 
 /**
  * Get the value following a flag in the args array.
@@ -334,6 +353,20 @@ async function main() {
       break;
     }
 
+    case 'git': {
+      const subcommand = args[1];
+      if (!subcommand) { error('git subcommand required. Available: commit, branch, push, status, log, stash, diff, rollback, tag, sync'); }
+      git.cmdGit(cwd, subcommand, args.slice(1), raw);
+      break;
+    }
+
+    case 'distill': {
+      const subcommand = args[1];
+      if (!subcommand) { error('distill subcommand required. Available: scan, analyze, report'); }
+      distill.cmdDistill(cwd, subcommand, args.slice(1), raw);
+      break;
+    }
+
     case 'commit': {
       const amend = args.includes('--amend');
       const force = args.includes('--force');
@@ -1009,6 +1042,51 @@ async function main() {
       break;
     }
 
+    case 'optimize': {
+      const subcommand = args[1];
+      if (subcommand === 'trace') {
+        const traceSub = args[2];
+        optimize.cmdOptimizeTrace(cwd, traceSub, {
+          sessionId: getArgValue(args, '--session'),
+          description: getArgValue(args, '--description'),
+          command: getArgValue(args, '--command'),
+          phase: getArgValue(args, '--phase'),
+          // trace log opts
+          agent: getArgValue(args, '--agent'),
+          type: getArgValue(args, '--type'),
+          category: getArgValue(args, '--category'),
+          impact: getArgValue(args, '--impact'),
+          description: getArgValue(args, '--description'),
+          correction: getArgValue(args, '--correction'),
+          tokens_wasted: getArgValue(args, '--tokens-wasted') ? Number(getArgValue(args, '--tokens-wasted')) : null,
+          context: (() => { const v = getArgValue(args, '--context'); if (!v) return null; try { return JSON.parse(v); } catch { return null; } })(),
+        }, raw);
+      } else if (subcommand === 'learn') {
+        optimize.cmdOptimizeLearn(cwd, {
+          sessionId: getArgValue(args, '--session'),
+        }, raw);
+      } else if (subcommand === 'apply') {
+        optimize.cmdOptimizeApply(cwd, {
+          reportPath: getArgValue(args, '--report'),
+        }, raw);
+      } else if (subcommand === 'list') {
+        optimize.cmdOptimizeList(cwd, raw);
+      } else if (subcommand === 'stats') {
+        optimize.cmdOptimizeStats(cwd, raw);
+      } else {
+        error('Unknown optimize subcommand. Available: trace, learn, apply, list, stats');
+      }
+      break;
+    }
+
+    case 'learn': {
+      // Convenience alias: pan-tools learn = optimize learn
+      optimize.cmdOptimizeLearn(cwd, {
+        sessionId: getArgValue(args, '--session'),
+      }, raw);
+      break;
+    }
+
     default:
       error(`Unknown command: ${command}. Run pan-tools without arguments to see available commands.`);
   }

package/pan-wizard-core/workflows/exec-phase.md

@@ -26,6 +26,14 @@ Parse JSON for: `executor_model`, `verifier_model`, `reviewer_model`, `commit_do
 **If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
 
 When `parallelization` is false, plans within a wave execute sequentially.
+
+**Circular optimization — start trace session for this exec:**
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init \
+  --description "exec-phase ${PHASE_ARG}" \
+  --command "exec-phase" \
+  --phase "${PHASE_ARG}" 2>/dev/null || true
+```
 </step>
 
 <step name="handle_branching">
@@ -47,6 +55,33 @@ From init JSON: `phase_dir`, `plan_count`, `incomplete_count`.
 Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)"
 </step>
 
+<step name="load_phase_memory">
+**Load project memory before dispatching executors — prevents re-learning patterns already solved.**
+
+```bash
+ls .planning/memory/*.md 2>/dev/null
+```
+
+If `.planning/memory/` exists and contains `.md` files:
+1. **Read every file** using the Read tool
+2. Condense each entry to its rule(s) — 1–3 lines per file
+3. Store as `MEMORY_RULES` block for injection into executor prompts in execute_waves
+4. **Log memory priming to trace:**
+```bash
+MEMORY_COUNT=$(ls .planning/memory/*.md 2>/dev/null | wc -l | tr -d ' ')
+if [ "$MEMORY_COUNT" -gt "0" ]; then
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+    --type decision --category memory_primed \
+    --description "Loaded ${MEMORY_COUNT} memory entries before Wave 1 dispatch" \
+    --agent orchestrator --impact minor \
+    --context "{\"memory_count\":${MEMORY_COUNT}}" \
+    2>/dev/null || true
+fi
+```
+
+If no memory files exist: skip (no trace event needed).
+</step>
+
 <step name="discover_and_group_plans">
 Load plan inventory with wave grouping in one call:
 
@@ -76,6 +111,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
 **For each wave:**
 
+0. **Record wave start time for duration tracking:**
+   ```bash
+   WAVE_START_MS=$(node -e "console.log(Date.now())")
+   ```
+
 1. **Describe what's being built (BEFORE spawning):**
 
    Read each plan's `<objective>`. Extract what's being built and why.
@@ -125,6 +165,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
        - .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
        </files_to_read>
 
+       <project_memory>
+       {MEMORY_RULES — insert condensed content of all .planning/memory/*.md files read in load_phase_memory step. If no memory files exist, omit this block entirely.}
+       Apply every rule in this block without exception. These are lessons from previous phases that the reviewer has already verified.
+       </project_memory>
+
        <success_criteria>
        - [ ] All tasks executed
        - [ ] Each task committed individually
@@ -160,6 +205,18 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    ---
    ```
 
+   Log wave completion to trace (include wall-clock duration):
+   ```bash
+   WAVE_END_MS=$(node -e "console.log(Date.now())")
+   WAVE_DURATION_MS=$((WAVE_END_MS - WAVE_START_MS))
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+     --type decision --category wave_complete \
+     --description "Wave ${WAVE_NUM} complete: ${PLAN_IDS}" \
+     --agent pan-executor --impact trivial \
+     --context "{\"wave\":${WAVE_NUM},\"plans\":\"${PLAN_IDS}\",\"duration_ms\":${WAVE_DURATION_MS}}" \
+     2>/dev/null || true
+   ```
+
    - Bad: "Wave 2 complete. Proceeding to Wave 3."
    - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
 
@@ -342,6 +399,33 @@ Task(
 ```
 
 **If user chooses "Continue anyway":** Proceed to verification. Review findings are informational, not blocking.
+
+4. **Circular optimization — log reviewer corrections to trace bus (W1 fix):**
+
+   When verdict is `NEEDS_FIXES`, write a `reviewer_correction` event so the optimizer can see the primary quality signal:
+   ```bash
+   # Extract error count from review output (parse "Errors: N" line)
+   REVIEW_ERROR_COUNT=$(echo "$REVIEW_OUTPUT" | grep -E "^- Errors: [0-9]+" | grep -oE "[0-9]+" | head -1)
+   REVIEW_ERROR_COUNT=${REVIEW_ERROR_COUNT:-1}
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+     --type error --category reviewer_correction \
+     --description "Phase ${PHASE_NUMBER} reviewer: NEEDS_FIXES — ${REVIEW_ERROR_COUNT} error(s) found" \
+     --agent pan-reviewer --impact major \
+     --context "{\"phase\":\"${PHASE_NUMBER}\",\"verdict\":\"NEEDS_FIXES\",\"error_count\":${REVIEW_ERROR_COUNT}}" \
+     2>/dev/null || true
+   ```
+
+   When verdict is `PASS_WITH_WARNINGS`, log a softer signal:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+     --type decision --category reviewer_warnings \
+     --description "Phase ${PHASE_NUMBER} reviewer: PASS_WITH_WARNINGS — warnings present" \
+     --agent pan-reviewer --impact trivial \
+     --context "{\"phase\":\"${PHASE_NUMBER}\",\"verdict\":\"PASS_WITH_WARNINGS\"}" \
+     2>/dev/null || true
+   ```
+
+   When verdict is `PASS`, no trace event needed — clean passes are the expected baseline.
 </step>
 
 <step name="close_parent_artifacts">
@@ -476,6 +560,19 @@ Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/roadmap.md .planning/state.md .planning/requirements.md {phase_dir}/*-verification.md
 ```
+
+**Circular optimization — finalize trace session:**
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null || true
+```
+
+Log phase completion event:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+  --type decision --category phase_complete \
+  --description "Phase ${PHASE_NUMBER} execution complete (${VERIFICATION_STATUS:-verified})" \
+  --agent orchestrator --impact minor 2>/dev/null || true
+```
 </step>
 
 <step name="offer_next">

package/pan-wizard-core/workflows/learn.md

@@ -0,0 +1,91 @@
+# Workflow: /pan:learn
+
+Analyze the most recent trace session and generate a circular optimization report.
+
+## Prerequisites
+
+- A trace session must exist in `.planning/optimization/traces/`
+- If no session exists, instruct the user to start one first:
+  ```
+  /pan:optimize trace init --description "what you're building"
+  [run your build: /pan:exec-phase N or /pan:focus-exec]
+  /pan:learn
+  ```
+
+## Step 1 — Identify the session
+
+Run:
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
+```
+
+If no active session, run:
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace list
+```
+Use the most recent session unless `--session <id>` was specified.
+
+If `--session <id>` was specified, use that session ID.
+
+## Step 2 — Generate local analysis
+
+Run:
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize learn [--session <id>]
+```
+
+This produces `.planning/optimization/reports/{session}-analysis.json`.
+
+Read the output and note:
+- `summary.errors` — how many error events
+- `summary.gaps` — how many gap events
+- `summary.memory_misses` — how many memory miss events
+- `summary.wasted_tokens` — tokens wasted on redundancies
+- `top_error_patterns` — most frequent error categories
+- `top_memory_misses` — most frequent memory miss topics
+
+## Step 3 — Invoke pan-optimizer agent
+
+Spawn the `pan-optimizer` agent with this instruction:
+
+> Read the analysis at `.planning/optimization/reports/{session}-analysis.json` and the raw trace at `.planning/optimization/traces/{session}/trace.jsonl`. Also read any existing memory at `.planning/memory/*.md` to understand what's already known. Produce a full optimization report at `.planning/optimization/reports/{session}-opt-report.md` following the format in your agent definition.
+
+Wait for the agent to complete. It will write the report to `.planning/optimization/reports/`.
+
+## Step 4 — Present the summary
+
+Read `.planning/optimization/reports/{session}-opt-report.md`.
+
+Present to the user:
+1. **Score** — the circular optimization score (0–100)
+2. **Top 3 findings** — the most impactful recommendations
+3. **Auto-applicable count** — how many items `/pan:optimize apply` can handle automatically
+4. **Review required count** — how many prompt/workflow suggestions need human review
+5. **Next step** — suggest running `/pan:optimize apply` to apply safe optimizations
+
+## Step 5 — Auto-apply (if --apply flag)
+
+If the `--apply` flag was passed, immediately run:
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize apply
+```
+
+Show what was applied and what still needs review.
+
+## Step 6 — Update the circular score baseline
+
+After applying, tell the user what to watch in the next run:
+- Which memory gaps were filled (will reduce `memory_miss` events)
+- Which error patterns were documented (will reduce repeat errors if agent reads memory)
+- Prompt/workflow changes to consider applying manually
+
+## Edge cases
+
+**No events in trace:**
+- Tell the user the trace session is empty. They may need to ensure the `pan-trace-logger` hook is registered in `.claude/settings.json`.
+
+**Too few events (< 5):**
+- The optimizer can still run but note the small sample size.
+
+**Analysis fails:**
+- Check that `.planning/optimization/traces/{session}/trace.jsonl` exists and is valid JSONL.

package/pan-wizard-core/workflows/optimize.md

@@ -0,0 +1,139 @@
+# Workflow: /pan:optimize
+
+Manage the circular optimization loop — apply reports, check stats, control trace sessions.
+
+## Subcommand routing
+
+| Subcommand | Action |
+|------------|--------|
+| `apply` | Apply safe recommendations from most recent report |
+| `apply --report <file>` | Apply from a specific report |
+| `list` | List all reports |
+| `stats` | Show cumulative stats |
+| `trace init` | Start a new trace session |
+| `trace end` | Finalize current session |
+| `trace status` | Show active session |
+| `trace list` | List all sessions |
+
+---
+
+## apply
+
+### Step 1 — Identify the report
+
+Run:
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize list
+```
+
+Use the most recent `.md` report (the full opt-report, not the `-analysis.json`).
+
+If `--report <filename>` was specified, use that file from `.planning/optimization/reports/`.
+
+### Step 2 — Run apply
+
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize apply [--report <path>]
+```
+
+### Step 3 — Present results
+
+Show the user:
+- **Applied** — each item that was written (memory entries, notes)
+- **Skipped** — items that already exist or had unknown types
+- **Still needs review** — prompt/workflow suggestions in `suggestions.md`
+
+If memory entries were written, tell the user:
+> Memory entries have been added to `.planning/memory/`. They will be loaded on the next agent run, reducing future memory misses for these topics.
+
+### Step 4 — Point to manual review items
+
+If `.planning/optimization/suggestions.md` exists, tell the user to review it for:
+- Agent prompt improvements (apply by editing `agents/pan-*.md`)
+- Workflow step additions (apply by editing `pan-wizard-core/workflows/*.md`)
+
+---
+
+## trace init
+
+### Step 1 — Extract description
+
+If `--description "..."` was provided, extract it from the args.
+
+### Step 2 — Initialize session
+
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init [--description "..."]
+```
+
+Show the user the session ID and confirm that:
+- The hook will automatically log agent completions to this session
+- To log a specific decision/error manually: `pan-tools optimize trace log --type <type> --description "..."` 
+- To end the session explicitly: `/pan:optimize trace end`
+
+---
+
+## trace end
+
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end
+```
+
+Show: session ID, event count, agent count, type breakdown.
+
+---
+
+## trace status
+
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
+```
+
+If active: show session ID and instruct how to view events.
+If none: tell user to run `/pan:optimize trace init` before their next build.
+
+---
+
+## stats
+
+```
+node .claude/pan-wizard-core/bin/pan-tools.cjs optimize stats
+```
+
+Present as a summary table:
+
+```
+Trace sessions:         N
+Optimization reports:   N
+Total events traced:    N
+Total errors traced:    N
+Optimizations applied:  N
+Active session:         sess_... (or none)
+```
+
+If `total_optimizations_applied` > 0, note:
+> {N} optimizations have been applied across {apply_runs} apply runs. Each applied memory entry reduces future knowledge gaps.
+
+---
+
+## The circular optimization loop explained
+
+When explaining the system to users:
+
+```
+Every agent spawn → hook logs completion event
+                          ↓
+              .planning/optimization/traces/{session}/trace.jsonl
+                          ↓
+             /pan:learn → pan-optimizer reads trace
+                          ↓
+              .planning/optimization/reports/{session}-opt-report.md
+                          ↓
+             /pan:optimize apply → writes memory entries
+                          ↓
+         Next build has better context → fewer errors/gaps
+                          ↓
+                  (repeat, improving each time)
+```
+
+The key insight: each apply run populates `.planning/memory/` with cached knowledge. Future agent runs load this memory and skip the research/inference that caused gaps. The error rate trends down. The optimization score trends up.

package/pan-wizard-core/workflows/plan-phase.md

@@ -24,6 +24,13 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_
 
 **If `planning_exists` is false:** Error — run `/pan:new-project` first.
 
+**Circular optimization — ensure trace session active:**
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init \
+  --description "plan-phase ${PHASE}" \
+  --command "plan-phase" --phase "${PHASE}" 2>/dev/null || true
+```
+
 ## 2. Parse and Normalize Arguments
 
 Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd <filepath>`).
@@ -383,7 +390,19 @@ Task(
 ## 11. Handle Checker Return
 
 - **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
+  ```bash
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+    --type decision --category plan_verified \
+    --description "Plan-checker passed for phase ${PHASE_NUMBER}" \
+    --agent pan-plan-checker --impact trivial 2>/dev/null || true
+  ```
 - **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
+  ```bash
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+    --type error --category plan_checker_issues \
+    --description "Plan-checker found issues in phase ${PHASE_NUMBER} plans" \
+    --agent pan-plan-checker --impact minor 2>/dev/null || true
+  ```
 
 ## 12. Revision Loop (Max 3 Iterations)
 
@@ -436,6 +455,14 @@ Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
 Route to `<offer_next>` OR `auto_advance` depending on flags/config.
 
+**Circular optimization — log plan creation:**
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+  --type decision --category plans_created \
+  --description "Plan-phase complete for phase ${PHASE_NUMBER}: ${PLAN_COUNT} plans created" \
+  --agent pan-planner --impact minor 2>/dev/null || true
+```
+
 ## 14. Auto-Advance Check
 
 Check for auto-advance trigger:

package/pan-wizard-core/workflows/quick.md

@@ -52,6 +52,13 @@ Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_mo
 
 Quick tasks can run mid-phase - validation only checks roadmap.md exists, not phase status.
 
+**Circular optimization — ensure trace session active:**
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init \
+  --description "quick: ${DESCRIPTION}" \
+  --command "quick" 2>/dev/null || true
+```
+
 ---
 
 **Step 3: Create task directory**

package/pan-wizard-core/workflows/verify-phase.md

@@ -282,6 +282,22 @@ If gaps_found: list gaps + recommended fix plan names.
 If human_needed: list items requiring human testing.
 
 Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
+
+**Circular optimization — log verification outcome:**
+```bash
+# Map status to impact and event type
+if [ "${STATUS}" = "passed" ]; then
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+    --type decision --category verification_passed \
+    --description "Phase ${PHASE_NUMBER} verification passed (score: ${SCORE})" \
+    --agent pan-verifier --impact minor 2>/dev/null || true
+elif [ "${STATUS}" = "gaps_found" ]; then
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+    --type error --category verification_gaps \
+    --description "Phase ${PHASE_NUMBER} verification found gaps (score: ${SCORE})" \
+    --agent pan-verifier --impact major 2>/dev/null || true
+fi
+```
 </step>
 
 </process>

package/scripts/build-hooks.js

@@ -14,7 +14,8 @@ const HOOKS_TO_COPY = [
   'pan-check-update.js',
   'pan-context-monitor.js',
   'pan-statusline.js',
-  'pan-cost-logger.js'
+  'pan-cost-logger.js',
+  'pan-trace-logger.js'
 ];
 
 function build() {