feat(mcp): add trace event API + verification commands in harness

- Wire TraceEventStore into MCP server with query/stats/record handlers
- Add verification commands to multimodal harness (custom pass/fail checks)
- Deterministic critique now checks verification results
- Update MCP tool definitions + docs

Author: StackMemory Bot (CLI)

docs/mcp.md

@@ -3,29 +3,36 @@
 The `plan_and_code` MCP tool lets Claude Code trigger StackMemory’s multi‑agent flow silently and receive a single JSON result. It plans with Claude, implements with Codex or Claude, and critiques the result — with optional retry loops and context recording.
 
 ## What it does
+
 - Planner (Claude): generates a concise plan with acceptance criteria and risks.
 - Implementer (Codex/Claude): applies a focused change per step.
 - Critic (Claude): returns `{ approved, issues[], suggestions[] }` to gate retries.
+- Verification commands: optional task-specific repro/test commands run after each implementation attempt and included in the critic input.
 - Returns a single JSON payload: `{ plan, implementation, critique, iterations[] }`.
 
 ## Tool definition
+
 - name: `plan_and_code`
 - arguments:
   - `task` (string, required): short task description
   - `implementer` ("codex" | "claude", default: `codex`)
   - `maxIters` (number, default: `2`): retry loop iterations
   - `execute` (boolean, default: `false`): if `false`, implementer is dry‑run
+  - `verificationCommands` (string[], optional): repro/test commands that must pass after each implementation attempt
   - `record` (boolean, default: `false`): write plan/critique as simple context rows
   - `recordFrame` (boolean, default: `false`): write a real frame + anchors
 
 ## Environment defaults
+
 If not specified in arguments, the MCP handler reads these env vars:
+
 - `STACKMEMORY_MM_PLANNER_MODEL` (e.g., `claude-sonnet-4-20250514`)
 - `STACKMEMORY_MM_REVIEWER_MODEL` (defaults to planner model if unset)
 - `STACKMEMORY_MM_IMPLEMENTER` (`codex` or `claude`)
 - `STACKMEMORY_MM_MAX_ITERS` (e.g., `3`)
 
 ## Example (MCP request)
+
 ```json
 {
   "method": "tools/call",
@@ -36,13 +43,17 @@ If not specified in arguments, the MCP handler reads these env vars:
       "implementer": "codex",
       "maxIters": 2,
       "execute": true,
+      "verificationCommands": [
+        "npx vitest run src/orchestrators/multimodal/__tests__/determinism.test.ts --reporter=dot"
+      ],
       "recordFrame": true
     }
   }
 }
 ```
 
 Response content is a single `text` item containing a JSON string:
+
 ```json
 {
   "ok": true,
@@ -58,6 +69,7 @@ Response content is a single `text` item containing a JSON string:
 ```
 
 ## Recording behavior
+
 - `record: true` writes two entries into `.stackmemory/context.db` (simple `contexts` table):
   - `Plan: <summary>` (importance 0.8)
   - `Critique: approved|needs_changes` (importance 0.6)
@@ -68,18 +80,22 @@ Response content is a single `text` item containing a JSON string:
 - Both modes are best‑effort. If the DB isn’t ready, handler returns JSON without failing.
 
 ## Notes
+
 - Implementer `codex` calls `codex-sm` (must be on PATH). Use `--execute` in CLI, or `execute: true` in MCP, to actually run it; otherwise it’s a dry‑run.
 - Audit files are saved to `.stackmemory/build/spike-<timestamp>.json` to support review/debugging.
 - You can compare models:
   - Planner/critic: override with `STACKMEMORY_MM_PLANNER_MODEL` / `STACKMEMORY_MM_REVIEWER_MODEL`.
   - Implementer: set to `claude` to A/B against Codex, or keep `codex` (default).
 
 ## CLI equivalents (for quick checks)
+
 - Quiet JSON output:
   - `stackmemory build "Refactor config loader" --json`
   - `stackmemory skills spike --task "Refactor config loader" --json`
 - Execute implementer and record as frame:
   - `stackmemory skills spike --task "Refactor" --execute --max-iters 3 --json --record-frame`
+- Execute with a task-specific verification harness:
+  - `stackmemory build "Fix deterministic replay drift" --verify "npm run determinism:test" --execute`
 
 ---
 
@@ -152,11 +168,13 @@ Response (content[0].text is a JSON string):
 ```
 
 Notes:
+
 - `recordFrame: true` creates a real StackMemory frame + anchors (plan summary, commands, issues, suggestions).
 - `execute: true` actually invokes the implementer; otherwise it’s a dry‑run.
 - Approval IDs are persisted to `.stackmemory/build/pending.json` so editor restarts don’t lose pending approvals.
 
 ### Optional helper tools
+
 - `plan_only`: Returns a plan JSON without running code.
 - `call_claude`: Calls Claude directly (prompt/model/system).
 - `call_codex`: Calls Codex via `codex-sm` (prompt/args/execute).

src/cli/commands/skills.ts

@@ -56,6 +56,13 @@ function getVersion(): string {
   return _version;
 }
 
+function collectRepeatedOption(
+  value: string,
+  previous: string[] = []
+): string[] {
+  return [...previous, value];
+}
+
 // Type-safe environment variable access
 function _getEnv(key: string, defaultValue?: string): string {
   const value = process.env[key];
@@ -408,6 +415,12 @@ export function createSkillsCommand(): Command {
       false
     )
     .option('--audit-dir <path>', 'Persist spike results to directory')
+    .option(
+      '--verify <cmd>',
+      'Verification command to run after each implementation attempt; repeatable',
+      collectRepeatedOption,
+      []
+    )
     .option('--record-frame', 'Record as real frame with anchors', false)
     .option(
       '--record',
@@ -435,6 +448,7 @@ export function createSkillsCommand(): Command {
             maxIters: parseInt(options.maxIters),
             dryRun: !options.execute,
             auditDir: options.auditDir,
+            verificationCommands: options.verify,
             recordFrame: Boolean(options.recordFrame),
             record: Boolean(options.record),
           }

src/integrations/mcp/server.ts

@@ -36,6 +36,8 @@ import { logger } from '../../core/monitoring/logger.js';
 import { isFeatureEnabled } from '../../core/config/feature-flags.js';
 import { ContentCache } from '../../core/cache/index.js';
 import type { CacheStats } from '../../core/cache/index.js';
+import { TraceEventStore } from '../../core/trace/trace-event-store.js';
+import type { TraceEvent } from '../../core/trace/trace-event.js';
 
 // Linear types - imported dynamically when needed
 type LinearTaskManager =
@@ -142,6 +144,8 @@ class LocalStackMemoryMCP {
   private crossSearchHandlers: CrossSearchHandlers;
   private pendingPlans: Map<string, any> = new Map();
   private contentCache: ContentCache;
+  private traceEventStore: TraceEventStore;
+  private sessionId: string;
   private sessionTokensSaved = 0;
   private sessionCacheHits = 0;
   private sessionCacheMisses = 0;
@@ -198,6 +202,10 @@ class LocalStackMemoryMCP {
     // Initialize content-hash cache for token deduplication
     this.contentCache = new ContentCache(this.db);
 
+    // Initialize ASI-shaped trace event store
+    this.traceEventStore = new TraceEventStore(this.db);
+    this.sessionId = uuidv4();
+
     // Initialize frame manager
     this.frameManager = new FrameManager(this.db, this.projectId);
 
@@ -343,6 +351,54 @@ class LocalStackMemoryMCP {
     };
   }
 
+  // ------------------------------------------------------------------
+  // Trace event handlers
+  // ------------------------------------------------------------------
+
+  private handleTraceEvents(args: Record<string, unknown>) {
+    const events = this.traceEventStore.query({
+      session_id: args.session_id as string | undefined,
+      operation: args.operation as string | undefined,
+      min_score: args.min_score as number | undefined,
+      has_feedback: args.has_feedback as boolean | undefined,
+      limit: (args.limit as number) ?? 50,
+    });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(events) }],
+      isError: false,
+    };
+  }
+
+  private handleTraceEventStats(args: Record<string, unknown>) {
+    const stats = this.traceEventStore.getStats({
+      session_id: args.session_id as string | undefined,
+    });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(stats) }],
+      isError: false,
+    };
+  }
+
+  private handleTraceEventAnnotate(args: Record<string, unknown>) {
+    const id = String(args.id ?? '');
+    if (!id) {
+      return {
+        content: [
+          { type: 'text', text: JSON.stringify({ error: 'id is required' }) },
+        ],
+        isError: true,
+      };
+    }
+    const ok = this.traceEventStore.annotate(id, {
+      score: args.score as number | undefined,
+      feedback: args.feedback as string | undefined,
+    });
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ ok, id }) }],
+      isError: false,
+    };
+  }
+
   private findProjectRoot(): string {
     let dir = process.cwd();
     while (dir !== '/') {
@@ -571,6 +627,12 @@ class LocalStackMemoryMCP {
                           description: 'Which agent implements code',
                         },
                         maxIters: { type: 'number', default: 2 },
+                        verificationCommands: {
+                          type: 'array',
+                          items: { type: 'string' },
+                          description:
+                            'Optional repro/test commands that must pass after implementation',
+                        },
                         recordFrame: { type: 'boolean', default: true },
                         execute: { type: 'boolean', default: true },
                       },
@@ -1424,6 +1486,50 @@ class LocalStackMemoryMCP {
                 required: ['content'],
               },
             },
+            // Trace event tools
+            {
+              name: 'trace_events',
+              description:
+                'Query ASI-shaped trace events. Filter by session, operation, min score, or feedback presence. Returns events with provenance, cost, and token data.',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  session_id: { type: 'string' },
+                  operation: { type: 'string' },
+                  min_score: { type: 'number' },
+                  has_feedback: { type: 'boolean' },
+                  limit: { type: 'number' },
+                },
+              },
+            },
+            {
+              name: 'trace_event_stats',
+              description:
+                'Get aggregate trace event statistics: total tokens, cost, operation counts, host distribution.',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  session_id: { type: 'string' },
+                },
+              },
+            },
+            {
+              name: 'trace_event_annotate',
+              description:
+                'Add a numeric score and/or textual feedback to a trace event. Used by GEPA-class optimizers.',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string', description: 'Trace event ID' },
+                  score: { type: 'number', description: 'Numeric score (0-1)' },
+                  feedback: {
+                    type: 'string',
+                    description: 'Textual ASI feedback',
+                  },
+                },
+                required: ['id'],
+              },
+            },
           ],
         };
       }
@@ -1791,6 +1897,19 @@ class LocalStackMemoryMCP {
               result = this.handleCacheLookup(args);
               break;
 
+            // Trace event tools
+            case 'trace_events':
+              result = this.handleTraceEvents(args);
+              break;
+
+            case 'trace_event_stats':
+              result = this.handleTraceEventStats(args);
+              break;
+
+            case 'trace_event_annotate':
+              result = this.handleTraceEventAnnotate(args);
+              break;
+
             default:
               throw new Error(`Unknown tool: ${name}`);
           }
@@ -1843,13 +1962,58 @@ class LocalStackMemoryMCP {
 
           // Add to trace detector
           this.traceDetector.addToolCall(toolCall);
+
+          // --- Record ASI-shaped trace event ---
+          try {
+            const traceEvent: TraceEvent = {
+              timestamp: new Date(startTime).toISOString(),
+              session_id: this.sessionId,
+              trace_id: callId,
+              tenant_id: 'local',
+              actor: {
+                host: process.env['STACKMEMORY_HOST'] || 'claude-code',
+                agent: 'stackmemory-mcp',
+                user: process.env['USER'] || 'anonymous',
+              },
+              operation: name,
+              inputs: args as Record<string, unknown>,
+              outputs: error
+                ? { error: error.message }
+                : ((result as Record<string, unknown>) ?? {}),
+              tokens_in: 0,
+              tokens_out: 0,
+              cost_usd: 0,
+              duration_ms: endTime - startTime,
+              error: error?.message,
+              provenance: {
+                sources: [{ type: 'tool', id: name }],
+                derivation: ['mcp-call'],
+                confidence: 1.0,
+              },
+            };
+            this.traceEventStore.record(traceEvent);
+          } catch {
+            // Trace recording is non-fatal
+          }
         }
 
         return result;
       }
     );
   }
 
+  private getVerificationCommands(args: any): string[] {
+    const commands = args.verificationCommands ?? args.verifyCommands;
+    if (Array.isArray(commands)) {
+      return commands.map((command) => String(command).trim()).filter(Boolean);
+    }
+    const single = args.verificationCommand ?? args.verifyCommand;
+    if (typeof single === 'string' && single.trim()) {
+      return [single.trim()];
+    }
+    return [];
+  }
+
   // Handle plan_and_code tool by invoking the mm harness
   private async handlePlanAndCode(args: any) {
     const { runSpike } =
@@ -1873,6 +2037,7 @@ class LocalStackMemoryMCP {
     const record = Boolean(args.record);
     const recordFrame = Boolean(args.recordFrame);
     const compact = Boolean(args.compact);
+    const verificationCommands = this.getVerificationCommands(args);
 
     const task = String(args.task || 'Plan and implement change');
 
@@ -1888,6 +2053,7 @@ class LocalStackMemoryMCP {
         maxIters: isFinite(maxIters) ? Math.max(1, maxIters) : 2,
         dryRun: !execute,
         auditDir: undefined,
+        verificationCommands,
         recordFrame,
       }
     );
@@ -2091,6 +2257,7 @@ class LocalStackMemoryMCP {
     );
     const recordFrame = args.recordFrame !== false; // default true
     const execute = args.execute !== false; // default true
+    const verificationCommands = this.getVerificationCommands(args);
 
     const result = await runSpike(
       { task: pending.task, repoPath: this.projectRoot },
@@ -2104,6 +2271,7 @@ class LocalStackMemoryMCP {
         implementer: implementer === 'claude' ? 'claude' : 'codex',
         maxIters: isFinite(maxIters) ? Math.max(1, maxIters) : 2,
         dryRun: !execute,
+        verificationCommands,
         recordFrame,
       }
     );