feat(optimize): add trace optimizer CLI for offline harness analysis

StackMemory Bot (CLI) · StackMemory Bot (CLI) · commit 66c8fc7df065 · 2026-05-02T19:02:52.000-04:00
Analyzes stored traces to detect repeated failure patterns (lint, test,
build, timeout, rate-limit), verification gaps, retry loops, and
context thrash. Generates actionable recommendations with confidence
scores and persists reports to .stackmemory/build/.
diff --git a/scripts/gepa/.before-optimize.md b/scripts/gepa/.before-optimize.md
@@ -102,7 +102,7 @@ Standalone Node.js `.mjs` automation — outreach, content, analytics, CRM sync.
 
 Scheduled via GitHub Actions cron. All scheduled workflows support `workflow_dispatch` for manual runs.
 
-**GitHub Actions limit:** `workflow_dispatch` allows max 25 `inputs`. `weekly-start.yml` has 22/25 inputs. Feedback is consolidated into a single JSON `feedback` input: `{"social":"...","aeo":"...","blog":"...","snitcher":"..."}`.
+**GitHub Actions limit:** `workflow_dispatch` allows max 25 `inputs`. `weekly-start.yml` has 21/25 inputs. Feedback is consolidated into a single JSON `feedback` input: `{"social":"...","aeo":"...","blog":"...","snitcher":"..."}`.
 
 ### Slack `/run` command
 When adding or renaming GitHub Actions workflows that should be triggerable via Slack, update the `WORKFLOWS` hash in `api/app/jobs/trigger_github_workflow_job.rb`. When deleting a workflow, remove it from the hash. The Slack `/run` command reads this mapping to dispatch workflows.
@@ -111,7 +111,7 @@ When adding or renaming GitHub Actions workflows that should be triggerable via
 
 | Workflow | Script path | Category |
 |---|---|---|
-| `weekly-start.yml` | `voyager/scripts/content-brief.mjs` + `voyager/scripts/content-audit.mjs` + `ops/fathom-social-content.mjs` + `ops/fathom-testimonial-scan.mjs` + `ops/perplexity-citation-audit.mjs` + `commit/profound-aeo-pulse.mjs` + `commit/citation-rank-tracker.mjs` + `diag/ranking-snapshot.mjs` + `voyager/scripts/generate-blog-scaffold.mjs` + `ops/ahrefs-firehose-digest.mjs` + `ops/export-dripify.mjs` + `commit/prospect-discovery.mjs` + `ops/repush-clay-leads.mjs` + `ops/snitcher-outreach.mjs` | GHA cron (Mon) |
+| `weekly-start.yml` | `voyager/scripts/content-brief.mjs` + `voyager/scripts/content-audit.mjs` + `ops/fathom-social-content.mjs` + `ops/fathom-testimonial-scan.mjs` + `ops/perplexity-citation-audit.mjs` + `commit/profound-aeo-pulse.mjs` + `commit/citation-rank-tracker.mjs` + `diag/ranking-snapshot.mjs` + `voyager/scripts/generate-blog-scaffold.mjs` + `ops/ahrefs-firehose-digest.mjs` + `ops/export-dripify.mjs` + `commit/prospect-discovery.mjs` + `commit/growth-signal-leads.mjs` + `ops/repush-clay-leads.mjs` + `ops/snitcher-outreach.mjs` | GHA cron (Mon) |
 | `weekly-end.yml` | `diag/fathom-demo-scorecard.mjs` + `commit/feedback/collect-*.mjs` + `commit/feedback/collect-ops-feedback.mjs` + `diag/weekly-retro.mjs` | GHA cron (Fri) |
 | `anneal-keywords.yml` | `commit/anneal-keywords.mjs` | GHA cron (Sun) |
 | `g2-review-monitor.yml` | `ops/g2-to-senja.mjs` | GHA cron (Daily) |
@@ -133,7 +133,7 @@ When adding or renaming GitHub Actions workflows that should be triggerable via
 In `actions/github-script@v7`, `github.rest.issues.createComment` posts plain issue comments on PRs (PRs are issues in GitHub's API). For inline code suggestions on specific files/lines, use `github.rest.pulls.createReview` or `github.rest.pulls.createReviewComment` instead.
 
 ### Scheduled (cron)
-- `weekly-start.yml` — Mon 9am ET (content review, social content, testimonial scan, Perplexity audit, AEO pulse → blog scaffold, Ahrefs digest, Dripify export, prospect discovery → snitcher outreach)
+- `weekly-start.yml` — Mon 9am ET (content review, social content, testimonial scan, Perplexity audit, AEO pulse → blog scaffold, Ahrefs digest, Dripify export, prospect discovery, growth-signal leads → snitcher outreach)
 - `weekly-end.yml` — Fri 9am ET (demo scorecard + pipeline health)
 - `anneal-keywords.yml` — Sun 11am ET (keyword annealing + kill pattern updates)
 - `g2-review-monitor.yml` — Daily 10am ET
@@ -169,7 +169,6 @@ Key patterns:
 ### Commits
 - Plain imperative sentences, no conventional commit prefixes
 - Short and direct — describe what, not why
-- **NEVER push directly to master.** Always create a feature branch and open a PR.
 
 ### Code
 - Read before writing. Edit over rewrite. No docs unless asked.
diff --git a/src/cli/commands/optimize.ts b/src/cli/commands/optimize.ts
@@ -0,0 +1,133 @@
+import { Command } from 'commander';
+import Database from 'better-sqlite3';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { TraceStore } from '../../core/trace/trace-store.js';
+import { TraceOptimizer } from '../../core/optimization/trace-optimizer.js';
+
+export function createOptimizeCommand(): Command {
+  const optimize = new Command('optimize').description(
+    'Offline optimizers for harnesses, traces, and prompts'
+  );
+
+  optimize
+    .command('traces')
+    .description(
+      'Analyze stored traces and generate HALO-like offline optimizer recommendations'
+    )
+    .option('-d, --days <n>', 'Only analyze traces from the last N days', '30')
+    .option(
+      '-m, --min-occurrences <n>',
+      'Minimum repeated occurrences before surfacing a pattern',
+      '2'
+    )
+    .option('--json', 'Print machine-readable JSON')
+    .option(
+      '--no-write',
+      'Do not persist report files under .stackmemory/build'
+    )
+    .action(async (options) => {
+      const projectRoot = process.cwd();
+      const dbPath = join(projectRoot, '.stackmemory', 'context.db');
+
+      if (!existsSync(dbPath)) {
+        console.log(
+          chalk.red('StackMemory not initialized in this directory.')
+        );
+        console.log(chalk.gray('Run "stackmemory init" first.'));
+        return;
+      }
+
+      const db = new Database(dbPath);
+      try {
+        const traceStore = new TraceStore(db);
+        const optimizer = new TraceOptimizer(traceStore);
+        const report = optimizer.analyze({
+          lookbackDays: parseInt(options.days, 10) || 30,
+          minOccurrences: parseInt(options.minOccurrences, 10) || 2,
+        });
+
+        const persisted = options.write
+          ? optimizer.persistReport(projectRoot, report)
+          : null;
+
+        if (options.json) {
+          console.log(
+            JSON.stringify(
+              {
+                ...report,
+                persisted,
+              },
+              null,
+              2
+            )
+          );
+          return;
+        }
+
+        console.log(chalk.blue('\nTrace Optimizer Report\n'));
+        console.log(`Lookback window: ${report.lookbackDays} day(s)`);
+        console.log(`Traces analyzed: ${report.totalTracesAnalyzed}`);
+        console.log(`Traces with errors: ${report.tracesWithErrors}`);
+        console.log(`Causal traces: ${report.causalTraces}`);
+        console.log(
+          `Average tools/trace: ${report.averageToolsPerTrace.toFixed(2)}`
+        );
+        console.log(
+          `Average trace score: ${report.averageTraceScore.toFixed(2)}`
+        );
+
+        if (report.recommendations.length === 0) {
+          console.log(
+            chalk.yellow(
+              '\nNo repeated patterns crossed the threshold. Lower --min-occurrences or collect more traces.'
+            )
+          );
+        } else {
+          console.log(chalk.blue('\nRecommendations:\n'));
+          for (const recommendation of report.recommendations) {
+            const badge =
+              recommendation.priority === 'high'
+                ? chalk.red('[high]')
+                : chalk.yellow('[medium]');
+            console.log(
+              `${badge} ${chalk.white(recommendation.title)} (${recommendation.confidence.toFixed(2)} confidence)`
+            );
+            console.log(`  ${recommendation.summary}`);
+            console.log(`  Targets: ${recommendation.targetAreas.join(', ')}`);
+            console.log(`  Actions: ${recommendation.actions.join(' | ')}`);
+            console.log(
+              `  Validate: ${recommendation.validations.join(' | ')}`
+            );
+            console.log('');
+          }
+        }
+
+        if (report.clusters.length > 0) {
+          console.log(chalk.blue('Detected clusters:\n'));
+          for (const cluster of report.clusters) {
+            console.log(
+              `- ${cluster.label} (${cluster.occurrences} traces, ${cluster.kind})`
+            );
+            if (cluster.toolPatterns.length > 0) {
+              console.log(`  Tools: ${cluster.toolPatterns.join(', ')}`);
+            }
+            if (cluster.sampleSummaries.length > 0) {
+              console.log(`  Examples: ${cluster.sampleSummaries.join(' | ')}`);
+            }
+          }
+          console.log('');
+        }
+
+        if (persisted) {
+          console.log(chalk.gray(`Saved JSON: ${persisted.jsonPath}`));
+          console.log(chalk.gray(`Saved Markdown: ${persisted.markdownPath}`));
+        }
+      } finally {
+        db.close();
+      }
+    });
+
+  return optimize;
+}
diff --git a/src/cli/index.ts b/src/cli/index.ts
@@ -66,6 +66,7 @@ import { createPingCommand } from './commands/ping.js';
 import { createAuditCommand } from './commands/audit.js';
 import { createStatsCommand } from './commands/stats.js';
 import { createBenchCommand } from './commands/bench.js';
+import { createOptimizeCommand } from './commands/optimize.js';
 import { createStateCommand } from './commands/state.js';
 import { createDigestCommands } from './commands/digest.js';
 import { createDesiresCommands } from './commands/desires.js';
@@ -806,6 +807,7 @@ program.addCommand(createModelCommand());
 program.addCommand(createAuditCommand());
 program.addCommand(createStatsCommand());
 program.addCommand(createBenchCommand());
+program.addCommand(createOptimizeCommand());
 program.addCommand(createStateCommand());
 program.addCommand(createDigestCommands());
 program.addCommand(createDesiresCommands());
diff --git a/src/core/optimization/__tests__/trace-optimizer.test.ts b/src/core/optimization/__tests__/trace-optimizer.test.ts
@@ -0,0 +1,174 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import Database from 'better-sqlite3';
+import { v4 as uuidv4 } from 'uuid';
+import { TraceStore } from '../../trace/trace-store.js';
+import { TraceType, type ToolCall, type Trace } from '../../trace/types.js';
+import { TraceOptimizer } from '../trace-optimizer.js';
+
+function makeTool(tool: string, overrides: Partial<ToolCall> = {}): ToolCall {
+  return {
+    id: uuidv4(),
+    tool,
+    timestamp: Date.now(),
+    ...overrides,
+  };
+}
+
+function makeTrace(overrides: Partial<Trace> = {}): Trace {
+  const now = Date.now();
+  return {
+    id: uuidv4(),
+    type: TraceType.ERROR_RECOVERY,
+    tools: [
+      makeTool('edit'),
+      makeTool('lint', { error: 'ESLint failed on touched file' }),
+    ],
+    score: 0.7,
+    summary: 'Recovered from lint failure',
+    metadata: {
+      startTime: now - 5_000,
+      endTime: now,
+      filesModified: ['src/example.ts'],
+      errorsEncountered: ['ESLint failed on touched file'],
+      decisionsRecorded: [],
+      causalChain: true,
+    },
+    ...overrides,
+  };
+}
+
+describe('TraceOptimizer', () => {
+  let db: Database.Database;
+  let traceStore: TraceStore;
+
+  beforeEach(() => {
+    db = new Database(':memory:');
+    traceStore = new TraceStore(db);
+  });
+
+  it('finds repeated lint failures and suggests earlier gating', () => {
+    traceStore.saveTrace(makeTrace());
+    traceStore.saveTrace(
+      makeTrace({
+        summary: 'Second lint failure',
+        tools: [
+          makeTool('write'),
+          makeTool('lint', { error: 'Prettier lint error' }),
+        ],
+        metadata: {
+          startTime: Date.now() - 6_000,
+          endTime: Date.now(),
+          filesModified: ['src/another.ts'],
+          errorsEncountered: ['Prettier lint error'],
+          decisionsRecorded: [],
+          causalChain: true,
+        },
+      })
+    );
+
+    const report = new TraceOptimizer(traceStore).analyze({
+      minOccurrences: 2,
+    });
+
+    expect(report.clusters.some((c) => c.id === 'error:lint_failure')).toBe(
+      true
+    );
+    expect(
+      report.recommendations.some((r) =>
+        r.title.includes('Lint failures recur')
+      )
+    ).toBe(true);
+  });
+
+  it('finds verification gaps after mutations', () => {
+    traceStore.saveTrace(
+      makeTrace({
+        type: TraceType.FEATURE_IMPLEMENTATION,
+        summary: 'Implemented change without validation',
+        tools: [makeTool('search'), makeTool('edit')],
+        metadata: {
+          startTime: Date.now() - 6_000,
+          endTime: Date.now(),
+          filesModified: ['src/feature.ts'],
+          errorsEncountered: [],
+          decisionsRecorded: [],
+          causalChain: false,
+        },
+      })
+    );
+    traceStore.saveTrace(
+      makeTrace({
+        type: TraceType.REFACTORING,
+        summary: 'Refactored helper without running tests',
+        tools: [makeTool('read'), makeTool('edit')],
+        metadata: {
+          startTime: Date.now() - 7_000,
+          endTime: Date.now(),
+          filesModified: ['src/helper.ts'],
+          errorsEncountered: [],
+          decisionsRecorded: [],
+          causalChain: false,
+        },
+      })
+    );
+
+    const report = new TraceOptimizer(traceStore).analyze({
+      minOccurrences: 2,
+    });
+
+    const cluster = report.clusters.find((c) => c.id === 'verification_gap');
+    expect(cluster).toBeDefined();
+    expect(cluster?.targetAreas).toContain('hooks');
+  });
+
+  it('finds search-heavy context thrash patterns', () => {
+    traceStore.saveTrace(
+      makeTrace({
+        type: TraceType.EXPLORATION,
+        summary: 'Searched around repeatedly',
+        tools: [
+          makeTool('search'),
+          makeTool('grep'),
+          makeTool('read'),
+          makeTool('search'),
+          makeTool('read'),
+        ],
+        metadata: {
+          startTime: Date.now() - 8_000,
+          endTime: Date.now(),
+          filesModified: [],
+          errorsEncountered: [],
+          decisionsRecorded: [],
+          causalChain: false,
+        },
+      })
+    );
+    traceStore.saveTrace(
+      makeTrace({
+        type: TraceType.EXPLORATION,
+        summary: 'More repeated searching',
+        tools: [
+          makeTool('grep'),
+          makeTool('search'),
+          makeTool('read'),
+          makeTool('glob'),
+          makeTool('read'),
+        ],
+        metadata: {
+          startTime: Date.now() - 9_000,
+          endTime: Date.now(),
+          filesModified: [],
+          errorsEncountered: [],
+          decisionsRecorded: [],
+          causalChain: false,
+        },
+      })
+    );
+
+    const report = new TraceOptimizer(traceStore).analyze({
+      minOccurrences: 2,
+    });
+
+    expect(report.clusters.some((c) => c.id === 'context_thrash')).toBe(true);
+  });
+});
diff --git a/src/core/optimization/trace-optimizer.ts b/src/core/optimization/trace-optimizer.ts
