pan-wizard 2.9.1 → 3.5.0

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

@@ -164,11 +164,27 @@
  *   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');
 const path = require('path');
-const { error, output } = require('./lib/core.cjs');
+const { error, output, buildCachedContext } = require('./lib/core.cjs');
 const state = require('./lib/state.cjs');
 const phase = require('./lib/phase.cjs');
 const roadmap = require('./lib/roadmap.cjs');
@@ -182,6 +198,17 @@ const frontmatter = require('./lib/frontmatter.cjs');
 const contextBudget = require('./lib/context-budget.cjs');
 const focus = require('./lib/focus.cjs');
 const codebase = require('./lib/codebase.cjs');
+const memory = require('./lib/memory.cjs');
+const bus = require('./lib/bus.cjs');
+const cost = require('./lib/cost.cjs');
+const preview = require('./lib/preview.cjs');
+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.
@@ -326,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');
@@ -684,8 +725,39 @@ async function main() {
         // design is a workflow-only command (no core function)
         // The AI reads commands/pan/focus-design.md directly
         output({ command: 'focus-design', type: 'workflow', message: 'Use /pan:focus-design to invoke the 10-phase investigation pipeline' }, raw);
+      } else if (subcommand === 'classify-stages') {
+        const useStdin = args.includes('--stdin');
+        let items;
+        if (useStdin) {
+          try {
+            items = JSON.parse(fs.readFileSync(0, 'utf-8'));
+          } catch (e) {
+            error(`Failed to parse stdin JSON: ${e.message}`);
+          }
+        } else {
+          const batch = focus.readLatestBatch(cwd);
+          if (!batch) {
+            output({ error: 'No batch file found. Run focus plan first.' }, raw);
+            break;
+          }
+          items = batch.batch || [];
+        }
+        output(focus.classifyStageDependencies(items), raw);
+      } else if (subcommand === 'reflection') {
+        let payload;
+        try {
+          payload = JSON.parse(fs.readFileSync(0, 'utf-8'));
+        } catch (e) {
+          error(`Failed to parse stdin JSON for focus reflection: ${e.message}`);
+        }
+        output(focus.determineContinuation(
+          payload.run || {},
+          payload.cycle || {},
+          payload.batch || [],
+          { tier: payload.tier }
+        ), raw);
       } else {
-        error('Unknown focus subcommand. Available: scan, plan, sync, exec, auto, design');
+        error('Unknown focus subcommand. Available: scan, plan, sync, exec, auto, design, classify-stages, reflection');
       }
       break;
     }
@@ -733,8 +805,202 @@ async function main() {
       break;
     }
 
+    case 'memory': {
+      const subcommand = args[1];
+      if (subcommand === 'read') {
+        memory.cmdMemoryRead(cwd, args[2], raw);
+      } else if (subcommand === 'append') {
+        memory.cmdMemoryAppend(cwd, args[2], args.slice(3).join(' '), raw);
+      } else if (subcommand === 'list') {
+        memory.cmdMemoryList(cwd, raw);
+      } else if (subcommand === 'compact') {
+        memory.cmdMemoryCompact(cwd, args[2], args[3], raw);
+      } else {
+        error('Unknown memory subcommand. Available: read, append, list, compact');
+      }
+      break;
+    }
+
+    case 'bridge': {
+      const subcommand = args[1];
+      if (subcommand === 'list') {
+        bridge.cmdBridgeList(cwd, raw);
+      } else if (subcommand === 'recommend') {
+        bridge.cmdBridgeRecommend(cwd, args[2], {
+          max_recommendations: Number(getArgValue(args, '--max') || 10),
+          min_score: Number(getArgValue(args, '--min-score') || 1),
+        }, raw);
+      } else if (subcommand === 'cache') {
+        bridge.cmdBridgeCache(cwd, getArgValue(args, '--servers'), getArgValue(args, '--runtime'), raw);
+      } else {
+        error('Unknown bridge subcommand. Available: list, recommend, cache');
+      }
+      break;
+    }
+
+    case 'whatif': {
+      const subcommand = args[1];
+      if (subcommand === 'prepare') {
+        const phaseNum = args[2];
+        const scenario = args.slice(3).filter(a => !a.startsWith('--')).join(' ');
+        whatif.cmdWhatifPrepare(cwd, phaseNum, scenario, raw);
+      } else if (subcommand === 'report') {
+        const phaseNum = args[2];
+        const scenarioParts = [];
+        for (let i = 3; i < args.length; i++) {
+          if (args[i] === '--comparison') break;
+          scenarioParts.push(args[i]);
+        }
+        const scenario = scenarioParts.join(' ');
+        const comparisonJson = getArgValue(args, '--comparison');
+        whatif.cmdWhatifReport(cwd, phaseNum, scenario, comparisonJson, raw);
+      } else if (subcommand === 'cleanup') {
+        whatif.cmdWhatifCleanup(
+          cwd,
+          getArgValue(args, '--worktree'),
+          getArgValue(args, '--branch'),
+          args.includes('--force'),
+          raw
+        );
+      } else {
+        error('Unknown whatif subcommand. Available: prepare, report, cleanup');
+      }
+      break;
+    }
+
+    case 'knowledge': {
+      const subcommand = args[1];
+      if (subcommand === 'ask') {
+        const question = args.slice(2).filter(a => !a.startsWith('--')).join(' ');
+        const maxSources = getArgValue(args, '--max-sources');
+        knowledge.cmdKnowledgeAsk(cwd, question, {
+          max_sources: maxSources ? Number(maxSources) : undefined,
+        }, raw);
+      } else if (subcommand === 'discuss') {
+        const phaseNum = args[2];
+        knowledge.cmdKnowledgeDiscuss(cwd, phaseNum, {
+          subcmd: getArgValue(args, '--subcmd'),
+          role: getArgValue(args, '--role'),
+          content: getArgValue(args, '--content'),
+          cites: getArgValue(args, '--cites'),
+        }, raw);
+      } else if (subcommand === 'playbook') {
+        knowledge.cmdKnowledgePlaybook(cwd, {
+          preview: args.includes('--preview'),
+        }, raw);
+      } else {
+        error('Unknown knowledge subcommand. Available: ask, discuss, playbook');
+      }
+      break;
+    }
+
+    case 'review-deep': {
+      const subcommand = args[1];
+      const phaseNum = args[2];
+      const opts = {
+        reviewerFile: getArgValue(args, '--reviewer-file'),
+        hardenerFile: getArgValue(args, '--hardener-file'),
+        metaFile: getArgValue(args, '--meta-file'),
+      };
+      if (subcommand === 'merge') {
+        reviewDeep.cmdReviewDeepMerge(cwd, phaseNum, opts, raw);
+      } else if (subcommand === 'analyze') {
+        reviewDeep.cmdReviewDeepAnalyze(cwd, phaseNum, opts, raw);
+      } else {
+        error('Unknown review-deep subcommand. Available: merge, analyze');
+      }
+      break;
+    }
+
+    case 'preview': {
+      const subcommand = args[1];
+      if (subcommand === 'phase') {
+        preview.cmdPreviewPhase(cwd, args[2], raw);
+      } else if (subcommand === 'phases') {
+        preview.cmdPreviewPhases(cwd, raw);
+      } else if (subcommand === 'milestone') {
+        preview.cmdPreviewMilestone(cwd, raw);
+      } else {
+        error('Unknown preview subcommand. Available: phase <N>, phases, milestone');
+      }
+      break;
+    }
+
+    case 'cost': {
+      const subcommand = args[1];
+      if (subcommand === 'report' || !subcommand) {
+        const format = getArgValue(args, '--format', 'json');
+        const since = getArgValue(args, '--since');
+        const until = getArgValue(args, '--until');
+        cost.cmdCostReport(cwd, { format, since, until }, raw);
+      } else if (subcommand === 'append') {
+        const rec = {
+          agent: getArgValue(args, '--agent'),
+          command: getArgValue(args, '--command'),
+          model: getArgValue(args, '--model'),
+          tier: getArgValue(args, '--tier'),
+          input_tokens: Number(getArgValue(args, '--input-tokens', 0)),
+          output_tokens: Number(getArgValue(args, '--output-tokens', 0)),
+          cache_read_tokens: Number(getArgValue(args, '--cache-read-tokens', 0)),
+          cache_write_tokens: Number(getArgValue(args, '--cache-write-tokens', 0)),
+          phase: getArgValue(args, '--phase'),
+          session: getArgValue(args, '--session'),
+        };
+        cost.cmdCostAppend(cwd, rec, raw);
+      } else if (subcommand === 'clear') {
+        cost.cmdCostClear(cwd, raw);
+      } else {
+        error('Unknown cost subcommand. Available: report, append, clear');
+      }
+      break;
+    }
+
+    case 'bus': {
+      const subcommand = args[1];
+      if (subcommand === 'publish') {
+        bus.cmdBusPublish(cwd, args[2], args[3], { source: getArgValue(args, '--source') }, raw);
+      } else if (subcommand === 'drain') {
+        const mode = getArgValue(args, '--mode', 'peek');
+        const limit = getArgValue(args, '--limit');
+        const offset = getArgValue(args, '--offset');
+        bus.cmdBusDrain(cwd, args[2], {
+          mode,
+          limit: limit ? Number(limit) : undefined,
+          offset: offset ? Number(offset) : undefined,
+        }, raw);
+      } else if (subcommand === 'list') {
+        bus.cmdBusList(cwd, raw);
+      } else {
+        error('Unknown bus subcommand. Available: publish, drain, list');
+      }
+      break;
+    }
+
+    case 'cache': {
+      const subcommand = args[1];
+      if (subcommand === 'prime') {
+        const result = buildCachedContext(cwd);
+        if (args.includes('--summary')) {
+          // Metadata-only form: hide full block content so agents can decide
+          // whether to request the full payload.
+          const summary = {
+            blocks: result.blocks.map(b => ({ path: b.path, bytes: Buffer.byteLength(b.content, 'utf-8'), cache: b.cache })),
+            total_bytes: result.total_bytes,
+            sha: result.sha,
+          };
+          output(summary, raw);
+        } else {
+          output(result, raw);
+        }
+      } else {
+        error('Unknown cache subcommand. Available: prime [--summary]');
+      }
+      break;
+    }
+
+
     case 'retro': {
-      verify.cmdRetro(cwd, raw);
+      verify.cmdRetro(cwd, raw, args);
       break;
     }
 
@@ -746,8 +1012,10 @@ async function main() {
         codebase.cmdDetectLanguages(cwd, raw);
       } else if (subcommand === 'best-practices') {
         codebase.cmdBestPractices(cwd, raw);
+      } else if (subcommand === 'estimate-size') {
+        codebase.cmdEstimateRepoSize(cwd, raw, args);
       } else {
-        error('Unknown codebase subcommand. Available: analyze-imports, detect-languages, best-practices');
+        error('Unknown codebase subcommand. Available: analyze-imports, detect-languages, best-practices, estimate-size');
       }
       break;
     }
@@ -774,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/templates/playbook.md

@@ -0,0 +1,53 @@
+<!--
+Template for .planning/PLAYBOOK.md generated by `/pan:knowledge playbook`.
+Populated by knowledge.cjs buildPlaybook() + writePlaybook() from the
+accumulated lessons in `.planning/memory/*.md`.
+
+Categories (in order):
+  - Conventions        — preferred patterns / naming / style
+  - Gotchas            — edge cases and surprises
+  - Decisions          — architecture choices with rationale
+  - Tool choices       — library / framework picks
+  - Anti-patterns      — things to avoid
+  - Recurring gaps     — patterns that keep appearing in verification
+  - General            — uncategorized
+-->
+
+---
+type: playbook
+generated: {{generated_at}}
+source_agents: {{agent_count}}
+entries: {{entry_count}}
+---
+
+# PAN Playbook
+
+Accumulated lessons across {{agent_count}} agents and {{entry_count}} memory entries. Regenerated from `.planning/memory/*.md`.
+
+## Conventions
+
+- {{entry}} _— from `{{agent}}`_
+
+## Gotchas
+
+- {{entry}} _— from `{{agent}}`_
+
+## Decisions
+
+- {{entry}} _— from `{{agent}}`_
+
+## Tool choices
+
+- {{entry}} _— from `{{agent}}`_
+
+## Anti-patterns
+
+- {{entry}} _— from `{{agent}}`_
+
+## Recurring gaps
+
+- {{entry}} _— from `{{agent}}`_
+
+## General
+
+- {{entry}} _— from `{{agent}}`_

package/pan-wizard-core/templates/preview-report.md

@@ -0,0 +1,93 @@
+<!--
+Template for pan-previewer output. Agent fills in sections based on mode
+(phase | phases | milestone). Not all sections apply to all modes — see
+commands/pan/preview.md for the per-mode contract.
+
+Placeholders:
+  {{mode}}          — "phase" | "phases" | "milestone"
+  {{title}}         — e.g. "Phase 7 — API Refactor" or "v3.1"
+  {{generated_at}}  — ISO timestamp
+  {{risk_score}}    — 1-10 (phase mode)
+  {{confidence}}    — 0-100 (milestone mode)
+-->
+
+---
+mode: {{mode}}
+generated_at: {{generated_at}}
+source: pan-previewer
+---
+
+# Preview: {{title}}
+
+## Summary
+
+{{one-paragraph-verdict}}
+
+## Files likely touched
+
+<!-- phase mode only; grouped by source/tests/docs -->
+- `{{file_path}}` — {{role}}
+
+## Tests at risk
+
+<!-- phase mode only -->
+- `{{test_path}}` — {{reason}}
+
+## Migration steps
+
+<!-- phase mode, only when risk_signals.migrate is true -->
+1. {{step}}
+
+## External deps
+
+<!-- phase mode, only when relevant -->
+- {{package}} — {{version_concern}}
+
+## Mermaid
+
+<!-- phases mode only; raw source from data layer inside a fenced mermaid block -->
+```mermaid
+{{mermaid_source}}
+```
+
+## Parallel batches
+
+<!-- phases mode only -->
+### Batch 1
+- Phase {{num}} — {{name}}
+
+## Hidden coupling
+
+<!-- phases mode only; may be "none found" -->
+- Phase {{from}} → Phase {{to}} — inferred from prose mention; consider promoting to `depends_on:` frontmatter.
+
+## Current state
+
+<!-- milestone mode only -->
+- Phases completed: {{completed}} / {{total}}
+- Velocity: {{phases_per_week}} phases/week (sample size {{sample_size}})
+
+## Projection
+
+<!-- milestone mode only -->
+- ETA: **{{eta_date}}**
+- Confidence: {{confidence}}%
+
+## Bottleneck
+
+<!-- milestone mode only -->
+- Phase {{phase_num}} — {{reason}}
+
+## Caveats
+
+<!-- milestone mode only -->
+- {{caveat}}
+
+## Risk assessment
+
+<!-- phase mode only; narrative, cites specific signals -->
+{{narrative}}
+
+## Bottom line
+
+**{{one-sentence-verdict}}**

package/pan-wizard-core/templates/roadmap.md

@@ -27,14 +27,14 @@ Decimal phases appear between their surrounding integers in numeric order.
 ## Phase Details
 
 ### Phase 1: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Nothing (first phase)
-**Requirements**: [REQ-01, REQ-02, REQ-03]  <!-- brackets optional, parser handles both formats -->
+**Goal:** [What this phase delivers]
+**Depends on:** Nothing (first phase)
+**Requirements:** [REQ-01, REQ-02, REQ-03]  <!-- brackets optional, parser handles both formats -->
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
   3. [Observable behavior from user perspective]
-**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
+**Plans:** [Number of plans, e.g., "3 plans" or "TBD"]
 
 Plans:
 - [ ] 01-01: [Brief description of first plan]
@@ -42,50 +42,50 @@ Plans:
 - [ ] 01-03: [Brief description of third plan]
 
 ### Phase 2: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 1
-**Requirements**: [REQ-04, REQ-05]
+**Goal:** [What this phase delivers]
+**Depends on:** Phase 1
+**Requirements:** [REQ-04, REQ-05]
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
-**Plans**: [Number of plans]
+**Plans:** [Number of plans]
 
 Plans:
 - [ ] 02-01: [Brief description]
 - [ ] 02-02: [Brief description]
 
 ### Phase 2.1: Critical Fix (INSERTED)
-**Goal**: [Urgent work inserted between phases]
-**Depends on**: Phase 2
+**Goal:** [Urgent work inserted between phases]
+**Depends on:** Phase 2
 **Success Criteria** (what must be TRUE):
   1. [What the fix achieves]
-**Plans**: 1 plan
+**Plans:** 1 plan
 
 Plans:
 - [ ] 02.1-01: [Description]
 
 ### Phase 3: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 2
-**Requirements**: [REQ-06, REQ-07, REQ-08]
+**Goal:** [What this phase delivers]
+**Depends on:** Phase 2
+**Requirements:** [REQ-06, REQ-07, REQ-08]
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
   3. [Observable behavior from user perspective]
-**Plans**: [Number of plans]
+**Plans:** [Number of plans]
 
 Plans:
 - [ ] 03-01: [Brief description]
 - [ ] 03-02: [Brief description]
 
 ### Phase 4: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 3
-**Requirements**: [REQ-09, REQ-10]
+**Goal:** [What this phase delivers]
+**Depends on:** Phase 3
+**Requirements:** [REQ-09, REQ-10]
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
-**Plans**: [Number of plans]
+**Plans:** [Number of plans]
 
 Plans:
 - [ ] 04-01: [Brief description]
@@ -152,8 +152,8 @@ After completing first milestone, reorganize with milestone groupings:
 <summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
 
 ### Phase 1: [Name]
-**Goal**: [What this phase delivers]
-**Plans**: 3 plans
+**Goal:** [What this phase delivers]
+**Plans:** 3 plans
 
 Plans:
 - [x] 01-01: [Brief description]
@@ -169,9 +169,9 @@ Plans:
 **Milestone Goal:** [What v1.1 delivers]
 
 #### Phase 5: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 4
-**Plans**: 2 plans
+**Goal:** [What this phase delivers]
+**Depends on:** Phase 4
+**Plans:** 2 plans
 
 Plans:
 - [ ] 05-01: [Brief description]

package/pan-wizard-core/templates/state.md

@@ -18,12 +18,15 @@ See: .planning/project.md (updated [date])
 
 ## Current Position
 
-Phase: [X] of [Y] ([Phase name])
-Plan: [A] of [B] in current phase
-Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
-Last activity: [YYYY-MM-DD] — [What happened]
-
-Progress: [░░░░░░░░░░] 0%
+**Current Phase:** [X]
+**Current Phase Name:** [Phase name]
+**Current Plan:** [A]
+**Total Plans in Phase:** [B]
+**Total Phases:** [Y]
+**Status:** [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
+**Last Activity:** [YYYY-MM-DD]
+**Last Activity Description:** [What happened]
+**Progress:** [░░░░░░░░░░] 0%
 
 ## Performance Metrics
 
@@ -68,9 +71,9 @@ None yet.
 
 ## Session Continuity
 
-Last session: [YYYY-MM-DD HH:MM]
-Stopped at: [Description of last completed action]
-Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
+**Last session:** [YYYY-MM-DD HH:MM]
+**Stopped At:** [Description of last completed action]
+**Resume File:** [Path to .continue-here*.md if exists, otherwise "None"]
 ```
 
 <purpose>