pan-wizard 3.4.1 → 3.5.1

package/pan-wizard-core/bin/lib/optimize.cjs

@@ -0,0 +1,653 @@
+'use strict';
+// optimize.cjs — Circular optimization loop: trace → learn → apply → repeat.
+//
+// Every agent spawn is logged to a trace session. After a build, /pan:learn
+// invokes pan-optimizer to analyze the trace. /pan:optimize apply writes memory
+// entries, config notes, and prompt suggestions back into the project, making
+// the next run smarter.
+
+const fs = require('fs');
+const path = require('path');
+const { output } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+
+// ─── Storage layout ──────────────────────────────────────────────────────────
+
+const OPTIMIZE_DIR = 'optimization';
+const TRACES_DIR = 'traces';
+const OPT_REPORTS_DIR = 'reports';
+const CURRENT_SESSION_FILE = 'current-session';
+const TRACE_EVENT_FILE = 'trace.jsonl';
+const OPT_SESSION_FILE = 'session.json';
+const APPLIED_LOG = 'applied.jsonl';
+
+// Event types the trace system recognizes
+const EVENT_TYPES = ['decision', 'error', 'gap', 'correction', 'redundancy', 'memory_hit', 'memory_miss', 'surprise'];
+// Impact levels
+const IMPACT_LEVELS = ['critical', 'major', 'minor', 'trivial'];
+
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+
+function getOptimizeDir(cwd) {
+  return path.join(cwd, PLANNING_DIR, OPTIMIZE_DIR);
+}
+
+function getTracesDir(cwd) {
+  return path.join(getOptimizeDir(cwd), TRACES_DIR);
+}
+
+function getReportsDir(cwd) {
+  return path.join(getOptimizeDir(cwd), OPT_REPORTS_DIR);
+}
+
+// ─── Session management ───────────────────────────────────────────────────────
+
+function generateSessionId() {
+  const now = new Date();
+  // sess_20260421T180000
+  return 'sess_' + now.toISOString().replace(/[-:.Z]/g, '').slice(0, 15);
+}
+
+function initTraceSession(cwd, opts = {}) {
+  const sessionId = opts.sessionId || generateSessionId();
+  const sessionDir = path.join(getTracesDir(cwd), sessionId);
+
+  try {
+    fs.mkdirSync(sessionDir, { recursive: true });
+
+    const meta = {
+      session_id: sessionId,
+      started_at: new Date().toISOString(),
+      description: opts.description || null,
+      command: opts.command || null,
+      phase: opts.phase || null,
+      agent_count: 0,
+      event_count: 0,
+      ended_at: null,
+    };
+
+    fs.writeFileSync(path.join(sessionDir, OPT_SESSION_FILE), JSON.stringify(meta, null, 2) + '\n');
+
+    // Record as active session
+    const optimizeDir = getOptimizeDir(cwd);
+    fs.mkdirSync(optimizeDir, { recursive: true });
+    fs.writeFileSync(path.join(optimizeDir, CURRENT_SESSION_FILE), sessionId + '\n');
+
+    return { session_id: sessionId, started_at: meta.started_at, directory: sessionDir };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+function getCurrentSessionId(cwd) {
+  try {
+    const content = fs.readFileSync(path.join(getOptimizeDir(cwd), CURRENT_SESSION_FILE), 'utf-8');
+    return content.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function logTraceEvent(cwd, event, sessionId) {
+  const sid = sessionId || getCurrentSessionId(cwd);
+  if (!sid) return false;
+
+  try {
+    const sessionDir = path.join(getTracesDir(cwd), sid);
+
+    // W3 fix: inherit session phase so per-phase filtering doesn't require session-join
+    let resolvedPhase = event.phase || null;
+    if (!resolvedPhase) {
+      try {
+        const meta = JSON.parse(fs.readFileSync(path.join(sessionDir, OPT_SESSION_FILE), 'utf-8'));
+        resolvedPhase = meta.phase || null;
+      } catch {}
+    }
+
+    const record = {
+      ts: new Date().toISOString(),
+      session: sid,
+      agent: event.agent || null,
+      phase: resolvedPhase,
+      type: EVENT_TYPES.includes(event.type) ? event.type : 'unknown',
+      category: event.category || null,
+      description: String(event.description || ''),
+      context: event.context || null,
+      impact: IMPACT_LEVELS.includes(event.impact) ? event.impact : 'minor',
+      correction: event.correction || null,
+      tokens_wasted: typeof event.tokens_wasted === 'number' ? event.tokens_wasted : null,
+    };
+
+    fs.mkdirSync(sessionDir, { recursive: true });
+    fs.appendFileSync(path.join(sessionDir, TRACE_EVENT_FILE), JSON.stringify(record) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function endTraceSession(cwd, sessionId) {
+  const sid = sessionId || getCurrentSessionId(cwd);
+  if (!sid) return { error: 'No active session' };
+
+  try {
+    const sessionDir = path.join(getTracesDir(cwd), sid);
+    const metaPath = path.join(sessionDir, OPT_SESSION_FILE);
+
+    let meta = {};
+    try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch {}
+
+    let eventCount = 0;
+    const agentNames = new Set();
+    const typeCounts = {};
+
+    try {
+      const raw = fs.readFileSync(path.join(sessionDir, TRACE_EVENT_FILE), 'utf-8');
+      raw.trim().split('\n').filter(Boolean).forEach(line => {
+        try {
+          const e = JSON.parse(line);
+          eventCount++;
+          if (e.agent) agentNames.add(e.agent);
+          typeCounts[e.type] = (typeCounts[e.type] || 0) + 1;
+        } catch {}
+      });
+    } catch {}
+
+    meta.ended_at = new Date().toISOString();
+    meta.event_count = eventCount;
+    meta.agent_count = agentNames.size;
+    meta.agents = Array.from(agentNames);
+    meta.type_counts = typeCounts;
+
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
+
+    return {
+      session_id: sid,
+      event_count: eventCount,
+      agent_count: agentNames.size,
+      type_counts: typeCounts,
+      ended_at: meta.ended_at,
+    };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+function readTraceSession(cwd, sessionId) {
+  try {
+    const sessionDir = path.join(getTracesDir(cwd), sessionId);
+
+    let metadata = {};
+    try {
+      metadata = JSON.parse(fs.readFileSync(path.join(sessionDir, OPT_SESSION_FILE), 'utf-8'));
+    } catch {}
+
+    const events = [];
+    try {
+      const raw = fs.readFileSync(path.join(sessionDir, TRACE_EVENT_FILE), 'utf-8');
+      raw.trim().split('\n').filter(Boolean).forEach(line => {
+        try { events.push(JSON.parse(line)); } catch {}
+      });
+    } catch {}
+
+    return { session_id: sessionId, metadata, events, event_count: events.length };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+function listTraceSessions(cwd) {
+  try {
+    const tracesDir = getTracesDir(cwd);
+    try { fs.accessSync(tracesDir); } catch { return { sessions: [], count: 0 }; }
+
+    const dirs = fs.readdirSync(tracesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name.startsWith('sess_'));
+
+    const sessions = dirs.map(e => {
+      const sessionDir = path.join(tracesDir, e.name);
+      let meta = { session_id: e.name };
+      try {
+        meta = JSON.parse(fs.readFileSync(path.join(sessionDir, OPT_SESSION_FILE), 'utf-8'));
+      } catch {}
+      return meta;
+    }).sort((a, b) => (b.started_at || '').localeCompare(a.started_at || ''));
+
+    return { sessions, count: sessions.length };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+// ─── Local analysis (no agent) ────────────────────────────────────────────────
+
+function analyzeEvents(events, sessionMeta) {
+  const errors = events.filter(e => e.type === 'error');
+  const gaps = events.filter(e => e.type === 'gap');
+  const redundancies = events.filter(e => e.type === 'redundancy');
+  const decisions = events.filter(e => e.type === 'decision');
+  const corrections = events.filter(e => e.type === 'correction');
+  const memoryMisses = events.filter(e => e.type === 'memory_miss');
+  const reviewerCorrections = events.filter(e => e.type === 'error' && e.category === 'reviewer_correction');
+  const memoryPrimed = events.filter(e => e.type === 'decision' && e.category === 'memory_primed');
+
+  function frequencyMap(arr) {
+    const map = {};
+    arr.forEach(e => {
+      const key = e.category || e.description.slice(0, 60);
+      map[key] = (map[key] || 0) + 1;
+    });
+    return Object.entries(map)
+      .map(([key, count]) => ({ pattern: key, count }))
+      .sort((a, b) => b.count - a.count);
+  }
+
+  const agentStats = {};
+  events.forEach(e => {
+    if (!e.agent) return;
+    if (!agentStats[e.agent]) agentStats[e.agent] = { total: 0, errors: 0, gaps: 0, corrections: 0 };
+    agentStats[e.agent].total++;
+    if (e.type === 'error') agentStats[e.agent].errors++;
+    if (e.type === 'gap') agentStats[e.agent].gaps++;
+    if (e.type === 'correction') agentStats[e.agent].corrections++;
+  });
+
+  Object.keys(agentStats).forEach(a => {
+    const s = agentStats[a];
+    s.error_rate = s.total > 0 ? Math.round((s.errors / s.total) * 100) / 100 : 0;
+  });
+
+  const wastedTokens = redundancies.reduce((sum, e) => sum + (e.tokens_wasted || 0), 0);
+
+  // ── Timing analysis from wall-clock timestamps ────────────────────────────
+  // Token data is unavailable (Claude Code SubagentStop doesn't populate usage).
+  // Use event timestamps + session start/end for meaningful timing analysis.
+  const timing = {};
+
+  // Session total duration
+  if (sessionMeta && sessionMeta.started_at && sessionMeta.ended_at) {
+    timing.session_duration_ms = new Date(sessionMeta.ended_at) - new Date(sessionMeta.started_at);
+    timing.session_duration_human = _msToHuman(timing.session_duration_ms);
+  }
+
+  // Per-agent intervals: time between consecutive events of the same agent
+  const agentIntervals = {};
+  const sorted = [...events].filter(e => e.ts).sort((a, b) => a.ts.localeCompare(b.ts));
+  for (let i = 1; i < sorted.length; i++) {
+    const gap = new Date(sorted[i].ts) - new Date(sorted[i - 1].ts);
+    const agent = sorted[i].agent || 'unknown';
+    if (!agentIntervals[agent]) agentIntervals[agent] = [];
+    agentIntervals[agent].push(gap);
+  }
+
+  // Slow-agent detection: flag agents whose avg interval exceeds 3 minutes
+  const slowAgents = [];
+  Object.entries(agentIntervals).forEach(([agent, intervals]) => {
+    const avg = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+    if (avg > 180000) slowAgents.push({ agent, avg_interval_ms: Math.round(avg), avg_human: _msToHuman(avg) });
+  });
+  if (slowAgents.length) timing.slow_agents = slowAgents;
+
+  // Wave timing from wave_complete events (have context.duration_ms when wired)
+  const waveEvents = events.filter(e => e.category === 'wave_complete');
+  if (waveEvents.length) {
+    timing.waves = waveEvents.map(e => ({
+      description: e.description,
+      duration_ms: e.context && e.context.duration_ms ? e.context.duration_ms : null,
+    }));
+  }
+
+  timing.token_data_available = events.some(e => e.context && (e.context.input_tokens || 0) > 0);
+
+  return {
+    summary: {
+      total_events: events.length,
+      errors: errors.length,
+      gaps: gaps.length,
+      redundancies: redundancies.length,
+      decisions: decisions.length,
+      corrections: corrections.length,
+      memory_misses: memoryMisses.length,
+      wasted_tokens: wastedTokens,
+      reviewer_corrections: reviewerCorrections.length,
+      memory_primed_count: memoryPrimed.length,
+    },
+    timing,
+    error_patterns: frequencyMap(errors),
+    gap_patterns: frequencyMap(gaps),
+    memory_miss_patterns: frequencyMap(memoryMisses),
+    agent_stats: agentStats,
+    critical_events: events.filter(e => e.impact === 'critical'),
+    major_events: events.filter(e => e.impact === 'major'),
+  };
+}
+
+function _msToHuman(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${Math.round(ms / 1000)}s`;
+  const m = Math.floor(ms / 60000);
+  const s = Math.round((ms % 60000) / 1000);
+  return s > 0 ? `${m}m${s}s` : `${m}m`;
+}
+
+function generateLocalReport(cwd, sessionId) {
+  const session = readTraceSession(cwd, sessionId);
+  if (session.error) return session;
+
+  return {
+    session_id: sessionId,
+    generated_at: new Date().toISOString(),
+    metadata: session.metadata,
+    ...analyzeEvents(session.events, session.metadata),
+    raw_events: session.events,
+  };
+}
+
+// ─── Report storage + parsing ─────────────────────────────────────────────────
+
+function listOptimizationReports(cwd) {
+  try {
+    const reportsDir = getReportsDir(cwd);
+    try { fs.accessSync(reportsDir); } catch { return { reports: [], count: 0 }; }
+
+    const reports = fs.readdirSync(reportsDir)
+      .filter(f => f.endsWith('.md') || f.endsWith('.json'))
+      .map(f => {
+        const p = path.join(reportsDir, f);
+        let stat;
+        try { stat = fs.statSync(p); } catch { return null; }
+        return { filename: f, path: p, size: stat.size, created_at: stat.birthtime.toISOString() };
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.created_at.localeCompare(a.created_at));
+
+    return { reports, count: reports.length };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+// Extracts the JSON block from the "## Auto-Apply Actions" section of an
+// optimizer markdown report.
+function parseAutoApplyBlock(reportContent) {
+  const match = reportContent.match(/##\s+Auto-Apply Actions[\s\S]*?```json\n([\s\S]*?)```/);
+  if (!match) return null;
+  try { return JSON.parse(match[1]); } catch { return null; }
+}
+
+// ─── Apply recommendations ────────────────────────────────────────────────────
+
+function applyReportRecommendations(cwd, reportPath) {
+  let reportContent;
+  try {
+    reportContent = fs.readFileSync(reportPath, 'utf-8');
+  } catch (e) {
+    return { error: `Cannot read report: ${e.message}` };
+  }
+
+  // Support both markdown reports (with auto-apply block) and JSON analysis files
+  let actions = parseAutoApplyBlock(reportContent);
+  if (!actions) {
+    // Try parsing as raw JSON analysis — generate basic memory entries from memory_miss patterns
+    try {
+      const analysis = JSON.parse(reportContent);
+      actions = deriveActionsFromAnalysis(analysis);
+    } catch {
+      return { applied: [], skipped: [], note: 'No auto-apply actions found in report' };
+    }
+  }
+
+  if (!Array.isArray(actions)) {
+    return { applied: [], skipped: [], note: 'Auto-apply block is not a valid array' };
+  }
+
+  const applied = [];
+  const skipped = [];
+
+  for (const action of actions) {
+    try {
+      if (action.type === 'memory') {
+        // Write new memory entry (skip if file exists to avoid overwriting manual edits)
+        const memPath = path.join(cwd, action.path);
+        try {
+          fs.accessSync(memPath);
+          skipped.push({ action, reason: 'File already exists — skipped to preserve manual edits' });
+        } catch {
+          fs.mkdirSync(path.dirname(memPath), { recursive: true });
+          fs.writeFileSync(memPath, action.content, 'utf-8');
+          applied.push({ action, result: `Written to ${action.path}` });
+        }
+      } else if (action.type === 'memory_append') {
+        // Append to existing memory file
+        const memPath = path.join(cwd, action.path);
+        fs.mkdirSync(path.dirname(memPath), { recursive: true });
+        fs.appendFileSync(memPath, '\n' + action.content, 'utf-8');
+        applied.push({ action, result: `Appended to ${action.path}` });
+      } else if (action.type === 'note') {
+        // Write a human-readable suggestion note
+        const notePath = path.join(getOptimizeDir(cwd), 'suggestions.md');
+        const entry = `\n## ${new Date().toISOString()}: ${action.description || 'Suggestion'}\n\n${action.content || action.suggestion || ''}\n\n**Target:** ${action.target || 'unspecified'}\n`;
+        fs.appendFileSync(notePath, entry);
+        applied.push({ action, result: 'Suggestion written to optimization/suggestions.md' });
+      } else if (action.type === 'planning_note') {
+        // Write optimization note into .planning/optimization/config-suggestions.md
+        const notePath = path.join(getOptimizeDir(cwd), 'config-suggestions.md');
+        const entry = `\n## ${new Date().toISOString()}\n${action.content}\n`;
+        fs.appendFileSync(notePath, entry);
+        applied.push({ action, result: 'Config suggestion recorded' });
+      } else {
+        skipped.push({ action, reason: `Unknown action type: ${action.type}` });
+      }
+    } catch (e) {
+      skipped.push({ action, reason: e.message });
+    }
+  }
+
+  // Log what was applied for cumulative stats
+  try {
+    const logEntry = {
+      ts: new Date().toISOString(),
+      report: path.basename(reportPath),
+      applied_count: applied.length,
+      skipped_count: skipped.length,
+      applied_types: applied.map(a => a.action.type),
+    };
+    fs.appendFileSync(path.join(getOptimizeDir(cwd), APPLIED_LOG), JSON.stringify(logEntry) + '\n');
+  } catch {}
+
+  return { applied, skipped };
+}
+
+// Derive basic memory actions from a raw JSON analysis when no optimizer agent
+// report is available (fallback for /pan:optimize apply on a JSON file).
+function deriveActionsFromAnalysis(analysis) {
+  const actions = [];
+  const { memory_miss_patterns, gap_patterns, summary } = analysis;
+
+  if (summary && summary.memory_misses > 0 && memory_miss_patterns) {
+    memory_miss_patterns.slice(0, 3).forEach(p => {
+      actions.push({
+        type: 'note',
+        description: `Memory miss: ${p.pattern}`,
+        content: `This topic was missing from memory ${p.count} time(s) during the traced session. Consider adding a memory entry for it.`,
+        target: '.planning/memory/',
+      });
+    });
+  }
+
+  if (gap_patterns && gap_patterns.length > 0) {
+    gap_patterns.slice(0, 3).forEach(p => {
+      actions.push({
+        type: 'note',
+        description: `Knowledge gap: ${p.pattern}`,
+        content: `The agent had to infer this ${p.count} time(s). Research and cache the answer.`,
+        target: '.planning/memory/',
+      });
+    });
+  }
+
+  return actions;
+}
+
+// ─── Cumulative stats ─────────────────────────────────────────────────────────
+
+function getOptimizeStats(cwd) {
+  try {
+    const sessions = listTraceSessions(cwd);
+    const reports = listOptimizationReports(cwd);
+
+    let totalEvents = 0;
+    let totalErrors = 0;
+    sessions.sessions && sessions.sessions.forEach(s => {
+      totalEvents += s.event_count || 0;
+      if (s.type_counts) totalErrors += s.type_counts.error || 0;
+    });
+
+    let totalApplied = 0;
+    let totalSkipped = 0;
+    let applyRuns = 0;
+    try {
+      const raw = fs.readFileSync(path.join(getOptimizeDir(cwd), APPLIED_LOG), 'utf-8');
+      raw.trim().split('\n').filter(Boolean).forEach(line => {
+        try {
+          const e = JSON.parse(line);
+          totalApplied += e.applied_count || 0;
+          totalSkipped += e.skipped_count || 0;
+          applyRuns++;
+        } catch {}
+      });
+    } catch {}
+
+    return {
+      trace_sessions: sessions.count || 0,
+      optimization_reports: reports.count || 0,
+      total_events_traced: totalEvents,
+      total_errors_traced: totalErrors,
+      total_optimizations_applied: totalApplied,
+      total_skipped: totalSkipped,
+      apply_runs: applyRuns,
+      current_session: getCurrentSessionId(cwd),
+    };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+// ─── CLI commands ─────────────────────────────────────────────────────────────
+
+function cmdOptimizeTrace(cwd, sub, opts, raw) {
+  if (sub === 'init') {
+    output(initTraceSession(cwd, opts), raw);
+  } else if (sub === 'log') {
+    const logged = logTraceEvent(cwd, opts);
+    output({ logged, session: getCurrentSessionId(cwd) }, raw);
+  } else if (sub === 'end') {
+    output(endTraceSession(cwd, opts.sessionId), raw);
+  } else if (sub === 'current') {
+    const sessionId = getCurrentSessionId(cwd);
+    output({ session_id: sessionId, active: !!sessionId }, raw);
+  } else if (sub === 'list') {
+    output(listTraceSessions(cwd), raw);
+  } else if (sub === 'show') {
+    if (!opts.sessionId) { output({ error: 'Session ID required (--session <id>)' }, raw); return; }
+    output(readTraceSession(cwd, opts.sessionId), raw);
+  } else {
+    output({ error: 'Unknown trace subcommand. Available: init, log, end, current, list, show' }, raw);
+  }
+}
+
+function cmdOptimizeLearn(cwd, opts, raw) {
+  const sessionId = opts.sessionId || getCurrentSessionId(cwd);
+  if (!sessionId) {
+    output({ error: 'No trace session active. Start one with: pan-tools optimize trace init' }, raw);
+    return;
+  }
+
+  const report = generateLocalReport(cwd, sessionId);
+  if (report.error) { output(report, raw); return; }
+
+  // Persist as JSON analysis for the optimizer agent to read
+  const reportsDir = getReportsDir(cwd);
+  try { fs.mkdirSync(reportsDir, { recursive: true }); } catch {}
+  const reportName = `${sessionId}-analysis.json`;
+  const reportPath = path.join(reportsDir, reportName);
+  try {
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2) + '\n');
+  } catch (e) {
+    output({ error: `Failed to write analysis: ${e.message}` }, raw);
+    return;
+  }
+
+  output({
+    session_id: sessionId,
+    analysis_path: path.join(PLANNING_DIR, OPTIMIZE_DIR, OPT_REPORTS_DIR, reportName).replace(/\\/g, '/'),
+    summary: report.summary,
+    top_error_patterns: report.error_patterns.slice(0, 5),
+    top_gap_patterns: report.gap_patterns.slice(0, 5),
+    top_memory_misses: report.memory_miss_patterns.slice(0, 5),
+    agent_stats: report.agent_stats,
+    next_step: 'Invoke pan-optimizer agent to generate optimization report from this analysis',
+  }, raw);
+}
+
+function cmdOptimizeApply(cwd, opts, raw) {
+  const reports = listOptimizationReports(cwd);
+  if (reports.error || reports.count === 0) {
+    output({ error: 'No optimization reports found. Run /pan:learn first.' }, raw);
+    return;
+  }
+
+  const reportPath = opts.reportPath || reports.reports[0].path;
+  const result = applyReportRecommendations(cwd, reportPath);
+  output({ report: path.basename(reportPath), ...result }, raw);
+}
+
+function cmdOptimizeStats(cwd, raw) {
+  output(getOptimizeStats(cwd), raw);
+}
+
+function cmdOptimizeList(cwd, raw) {
+  output(listOptimizationReports(cwd), raw);
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Session management
+  initTraceSession,
+  getCurrentSessionId,
+  logTraceEvent,
+  endTraceSession,
+  readTraceSession,
+  listTraceSessions,
+  // Analysis
+  analyzeEvents,
+  generateLocalReport,
+  // Reports
+  listOptimizationReports,
+  parseAutoApplyBlock,
+  applyReportRecommendations,
+  deriveActionsFromAnalysis,
+  // Stats
+  getOptimizeStats,
+  // Commands
+  cmdOptimizeTrace,
+  cmdOptimizeLearn,
+  cmdOptimizeApply,
+  cmdOptimizeStats,
+  cmdOptimizeList,
+  // Path helpers (used by hook)
+  getOptimizeDir,
+  getTracesDir,
+  getReportsDir,
+  // Constants (exported for hook + tests)
+  OPTIMIZE_DIR,
+  TRACES_DIR,
+  OPT_REPORTS_DIR,
+  APPLIED_LOG,
+  TRACE_EVENT_FILE,
+  OPT_SESSION_FILE,
+  CURRENT_SESSION_FILE,
+  EVENT_TYPES,
+  IMPACT_LEVELS,
+};