@smartmemory/compose 0.1.0 → 0.1.2-beta

package/server/compose-mcp-tools.js

@@ -10,8 +10,6 @@ import http from 'node:http';
 import path from 'node:path';
 import { ArtifactManager, ARTIFACT_SCHEMAS } from './artifact-manager.js';
 import { getTargetRoot, getDataDir, resolveProjectPath } from './project-root.js';
-import { ClaudeSDKConnector } from './connectors/claude-sdk-connector.js';
-import { CodexConnector } from './connectors/codex-connector.js';
 
 export const PROJECT_ROOT = getTargetRoot();
 export const VISION_FILE = path.join(getDataDir(), 'vision-state.json');
@@ -354,126 +352,3 @@ export function toolGetPendingGates({ itemId }) {
   return { count: pending.length, gates: pending };
 }
 
-// ---------------------------------------------------------------------------
-// Agent run — dispatch prompts to claude or codex
-// ---------------------------------------------------------------------------
-
-const VALID_AGENT_TYPES = new Set(['claude', 'codex']);
-
-/**
- * Build a context preamble for agent_run prompts.
- * The spawned agent (especially codex via opencode run) has no project context —
- * no CLAUDE.md, no feature folder awareness, no compose/stratum semantics.
- * This function reads project files and prepends them so the agent can do useful work.
- */
-function _buildContext({ featureCode }) {
-  const sections = [];
-
-  // Project instructions
-  const claudeMd = path.join(PROJECT_ROOT, 'CLAUDE.md');
-  if (fs.existsSync(claudeMd)) {
-    try {
-      const content = fs.readFileSync(claudeMd, 'utf-8');
-      sections.push(`## Project Instructions (CLAUDE.md)\n\n${content}`);
-    } catch { /* ignore read errors */ }
-  }
-
-  // Feature artifacts (if feature code detected)
-  // Cap total feature context to ~20KB to avoid exceeding model input limits.
-  // Prioritize design.md first, then most recent files by mtime.
-  const MAX_FEATURE_BYTES = 20_000;
-  if (featureCode) {
-    const featureRoot = resolveProjectPath('features');
-    const featureDir = path.join(featureRoot, featureCode);
-    if (fs.existsSync(featureDir)) {
-      const artifacts = [];
-      let totalBytes = 0;
-      try {
-        const files = fs.readdirSync(featureDir)
-          .filter(f => f.endsWith('.md') || f.endsWith('.json'))
-          .map(f => ({ name: f, path: path.join(featureDir, f), stat: fs.statSync(path.join(featureDir, f)) }))
-          .filter(f => f.stat.isFile())
-          // design.md first, then most recently modified
-          .sort((a, b) => {
-            if (a.name === 'design.md') return -1;
-            if (b.name === 'design.md') return 1;
-            return b.stat.mtimeMs - a.stat.mtimeMs;
-          });
-        for (const file of files) {
-          if (totalBytes >= MAX_FEATURE_BYTES) break;
-          try {
-            const content = fs.readFileSync(file.path, 'utf-8');
-            const trimmed = content.slice(0, MAX_FEATURE_BYTES - totalBytes);
-            artifacts.push(`### ${file.name}\n\n${trimmed}`);
-            totalBytes += trimmed.length;
-          } catch { /* skip unreadable files */ }
-        }
-      } catch { /* ignore readdir errors */ }
-      if (artifacts.length > 0) {
-        sections.push(`## Feature: ${featureCode}\n\n${artifacts.join('\n\n---\n\n')}`);
-      }
-    }
-  }
-
-  if (sections.length === 0) return '';
-  return `# Context\n\n${sections.join('\n\n---\n\n')}\n\n---\n\n`;
-}
-
-/**
- * Extract a feature code from the prompt if one is referenced.
- * Looks for common patterns like "FEAT-1", "AUTH-2", or feature folder paths.
- */
-function _extractFeatureCode(prompt) {
-  // Match uppercase CODE-N patterns (e.g. FEAT-1, AUTH-2, STRAT-COMP-3)
-  const codeMatch = prompt.match(/\b([A-Z][\w-]*-\d+)\b/);
-  if (codeMatch) return codeMatch[1];
-
-  // Match feature folder references
-  const pathMatch = prompt.match(/features\/([a-zA-Z][\w-]+)/);
-  if (pathMatch) return pathMatch[1];
-
-  return null;
-}
-
-export async function toolAgentRun({ type = 'claude', prompt, schema, modelID, cwd, featureCode }) {
-  if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
-    throw new Error('agent_run: prompt is required');
-  }
-  if (!VALID_AGENT_TYPES.has(type)) {
-    throw new Error(`agent_run: unknown type '${type}'. Valid: ${[...VALID_AGENT_TYPES].join(', ')}`);
-  }
-
-  // Resolve feature code from explicit param or prompt text
-  const resolvedFeature = featureCode || _extractFeatureCode(prompt);
-
-  // Build context preamble and prepend to prompt
-  const context = _buildContext({ featureCode: resolvedFeature });
-  const fullPrompt = context ? `${context}# Task\n\n${prompt}` : prompt;
-
-  const resolvedCwd = cwd || PROJECT_ROOT;
-  const connector = type === 'codex'
-    ? new CodexConnector({ modelID, cwd: resolvedCwd })
-    : new ClaudeSDKConnector({ model: modelID, cwd: resolvedCwd });
-
-  const parts = [];
-  for await (const event of connector.run(fullPrompt, { schema, modelID, cwd: resolvedCwd })) {
-    if (event.type === 'assistant' && event.content) {
-      parts.push(event.content);
-    } else if (event.type === 'error') {
-      throw new Error(`agent_run (${type}): ${event.message}`);
-    }
-  }
-
-  const text = parts.join('');
-
-  if (schema) {
-    try {
-      return { text, result: JSON.parse(text) };
-    } catch {
-      return { text, result: null, parseError: 'Response was not valid JSON' };
-    }
-  }
-
-  return { text };
-}
-

package/server/compose-mcp.js

@@ -256,10 +256,8 @@ const TOOLS = [
       },
     },
   },
-  // Note: `agent_run` tool removed 2026-04-18 (STRAT-DEDUP-AGENTRUN v1).
-  // LLM-facing agent dispatch now goes through `mcp__stratum__stratum_agent_run`.
-  // `toolAgentRun` (and the Node connectors it uses) remain exported for Compose's
-  // internal callers (build.js, vision-server, pipelines).
+  // `agent_run` tool removed 2026-04-18 (STRAT-DEDUP-AGENTRUN v1); LLM-facing
+  // dispatch goes through `mcp__stratum__stratum_agent_run`.
 ];
 
 // ---------------------------------------------------------------------------

package/server/contract-diff.js

@@ -0,0 +1,192 @@
+/**
+ * contract-diff.js — COMP-OBS-DRIFT contract_drift axis helper.
+ *
+ * Compares JSON Schema files between an anchor git ref and the current working
+ * tree. Returns field-change counts (added / removed / retyped / total) for use
+ * by drift-axes.js in computing the contract_drift ratio.
+ *
+ * Field-walk strategy: recursively collect leaf property names from
+ * schema.properties, counting each as one "field". additionalProperties: false
+ * itself counts as a single field (stability signal). Combines all files so
+ * the denominator is global-per-feature, not per-file.
+ *
+ * All git invocations go through execSync; errors are caught and returned as
+ * empty field sets (axis falls back to threshold: null in the caller).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+/**
+ * Walk a JSON Schema object and return the set of "fields" it declares.
+ * Each property name is included; additionalProperties:false adds a sentinel
+ * '__additionalProperties_closed__' so it contributes to the count.
+ *
+ * @param {object} schema
+ * @param {string} [prefix]
+ * @returns {Set<string>}
+ */
+function walkSchema(schema, prefix = '') {
+  const fields = new Set();
+  if (!schema || typeof schema !== 'object') return fields;
+
+  if (schema.additionalProperties === false) {
+    fields.add(`${prefix}__additionalProperties_closed__`);
+  }
+
+  const props = schema.properties;
+  if (props && typeof props === 'object') {
+    for (const [key, value] of Object.entries(props)) {
+      const qualifiedKey = prefix ? `${prefix}.${key}` : key;
+      fields.add(qualifiedKey);
+      // Recurse into nested object schemas
+      if (value && typeof value === 'object') {
+        const nested = walkSchema(value, qualifiedKey);
+        for (const f of nested) fields.add(f);
+      }
+    }
+  }
+
+  // Walk allOf / anyOf / oneOf for completeness
+  for (const key of ['allOf', 'anyOf', 'oneOf']) {
+    if (Array.isArray(schema[key])) {
+      for (const sub of schema[key]) {
+        const nested = walkSchema(sub, prefix);
+        for (const f of nested) fields.add(f);
+      }
+    }
+  }
+
+  return fields;
+}
+
+/**
+ * Collect a Map<fullyQualifiedPath, typeString> for every field at any depth.
+ * Mirrors walkSchema's traversal so paths are comparable across versions.
+ *
+ * @param {object} schema
+ * @param {string} prefix
+ * @returns {Map<string, string>}
+ */
+function collectFieldTypes(schema, prefix = '') {
+  const types = new Map();
+  if (!schema || typeof schema !== 'object') return types;
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    for (const [key, value] of Object.entries(schema.properties)) {
+      const qualifiedKey = prefix ? `${prefix}.${key}` : key;
+      const t = JSON.stringify(value?.type ?? null);
+      types.set(qualifiedKey, t);
+      if (value && typeof value === 'object') {
+        const nested = collectFieldTypes(value, qualifiedKey);
+        for (const [k, v] of nested) types.set(k, v);
+      }
+    }
+  }
+
+  for (const key of ['allOf', 'anyOf', 'oneOf']) {
+    if (Array.isArray(schema[key])) {
+      for (const sub of schema[key]) {
+        const nested = collectFieldTypes(sub, prefix);
+        for (const [k, v] of nested) types.set(k, v);
+      }
+    }
+  }
+
+  return types;
+}
+
+/**
+ * Read a file at an anchor git ref via `git show <ref>:<path>`.
+ * Returns null if the file did not exist at that ref.
+ *
+ * @param {string} ref — git commit ref (sha1 or symbolic)
+ * @param {string} filePath — path relative to repo root
+ * @param {string} projectRoot — absolute path of the git repo root
+ * @returns {string|null}
+ */
+function gitShow(ref, filePath, projectRoot) {
+  // Normalize path separators to forward slashes for git
+  const gitPath = filePath.replace(/\\/g, '/');
+  try {
+    return execSync(`git show ${ref}:${gitPath}`, {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch {
+    return null; // file didn't exist at that ref — treat as empty schema
+  }
+}
+
+/**
+ * Diff contract files for a feature between an anchor ref and the current
+ * working tree.
+ *
+ * @param {string} anchorRef — git commit ref (result of git rev-list)
+ * @param {string[]} headPaths — absolute paths to current JSON schema files
+ * @param {string} projectRoot — absolute root of the git repo
+ * @returns {{ added: number, removed: number, retyped: number, total: number }}
+ *   Returns { added:0, removed:0, retyped:0, total:0 } on any parse failure.
+ */
+export function diffContracts(anchorRef, headPaths, projectRoot) {
+  let added = 0;
+  let removed = 0;
+  let retyped = 0;
+  let totalCurrentFields = 0;
+
+  for (const absPath of headPaths) {
+    // Read current (HEAD working-tree) version
+    let currentSchema;
+    try {
+      currentSchema = JSON.parse(fs.readFileSync(absPath, 'utf8'));
+    } catch {
+      continue; // unparseable — skip this file
+    }
+
+    // Compute path relative to projectRoot for git show
+    const relPath = path.relative(projectRoot, absPath);
+
+    // Read anchor version
+    const anchorContent = gitShow(anchorRef, relPath, projectRoot);
+    let anchorSchema = null;
+    if (anchorContent) {
+      try {
+        anchorSchema = JSON.parse(anchorContent);
+      } catch {
+        // anchor version unparseable — treat as if it didn't exist
+      }
+    }
+
+    const currentFields = walkSchema(currentSchema);
+    const anchorFields = anchorSchema ? walkSchema(anchorSchema) : new Set();
+
+    totalCurrentFields += currentFields.size;
+
+    for (const field of currentFields) {
+      if (!anchorFields.has(field)) added++;
+    }
+    for (const field of anchorFields) {
+      if (!currentFields.has(field)) removed++;
+    }
+
+    // "Retyped" detection: walk both schemas recursively and compare the JSON
+    // type of every fully-qualified field path that exists in both versions.
+    // This catches retypes nested inside object properties (where the path
+    // stays the same but the type changes), which a top-level-only diff
+    // would miss and silently undercount.
+    if (anchorSchema) {
+      const currentTypes = collectFieldTypes(currentSchema);
+      const anchorTypes = collectFieldTypes(anchorSchema);
+      for (const [path, curType] of currentTypes) {
+        if (anchorTypes.has(path)) {
+          const anType = anchorTypes.get(path);
+          if (curType !== anType) retyped++;
+        }
+      }
+    }
+  }
+
+  return { added, removed, retyped, total: totalCurrentFields };
+}

package/server/decision-event-emit.js

@@ -0,0 +1,175 @@
+/**
+ * decision-event-emit.js — Shared emit helper for COMP-OBS-TIMELINE.
+ *
+ * Central choke point for all DecisionEvent broadcasts. Builders produce
+ * contract-clean event shapes; emitDecisionEvent wraps them in the canonical
+ * envelope matching BRANCH's existing pattern (cc-session-watcher.js:151-166):
+ *   { type: 'decisionEvent', event: { id, feature_code, timestamp, kind, title, metadata, roles } }
+ *
+ * Outcome mapping for iteration.metadata.outcome:
+ *   server outcome     → schema enum
+ *   'clean'            → 'pass'
+ *   'max_reached'      → 'fail'
+ *   'aborted'          → 'fail'
+ *   'timeout'          → 'fail'
+ *   'action_limit'     → 'fail'
+ *   'retry' / null     → 'retry'
+ */
+
+import {
+  phaseTransitionDecisionEventId,
+  iterationDecisionEventId,
+  gateDecisionEventId,
+  driftThresholdDecisionEventId,
+} from './decision-event-id.js';
+import { mapResolveOutcomeToSchema } from './gate-log-store.js';
+
+// Map server-side iteration outcome strings to the schema enum {pass|fail|retry}
+function mapIterationOutcome(outcome) {
+  if (!outcome || outcome === 'retry') return 'retry';
+  if (outcome === 'clean' || outcome === 'pass') return 'pass';
+  // max_reached | aborted | timeout | action_limit → fail
+  return 'fail';
+}
+
+/**
+ * Emit a DecisionEvent over broadcastMessage using the canonical envelope.
+ * The envelope matches BRANCH's _buildForkEvent / broadcastMessage pattern.
+ */
+export function emitDecisionEvent(broadcastMessage, event) {
+  broadcastMessage({ type: 'decisionEvent', event });
+}
+
+/**
+ * Build a kind=phase_transition DecisionEvent.
+ *
+ * @param {{ featureCode, from, to, outcome, agent_id, timestamp }} params
+ *   - from: previous phase string, or null for the initial lifecycle start
+ *   - to: new phase string
+ *   - outcome: optional outcome string (for context)
+ *   - agent_id: optional operator/agent identifier
+ */
+export function buildPhaseTransitionEvent({ featureCode, from, to, outcome, agent_id, timestamp }) {
+  const now = timestamp || new Date().toISOString();
+  const fromStr = from == null ? 'null' : String(from);
+  const id = phaseTransitionDecisionEventId(featureCode, from, to, now);
+  return {
+    id,
+    feature_code: featureCode,
+    timestamp: now,
+    kind: 'phase_transition',
+    title: from == null
+      ? `Lifecycle started: ${to}`
+      : `Phase: ${from} → ${to}${outcome === 'skipped' ? ' (skipped)' : outcome === 'killed' ? ' (killed)' : ''}`,
+    metadata: {
+      from_phase: fromStr,
+      to_phase: String(to),
+    },
+    roles: [{ name: 'PRODUCER', agent_id: agent_id || null }],
+  };
+}
+
+/**
+ * Build a kind=iteration DecisionEvent.
+ * Only called at loop start and loop complete — NOT per-attempt.
+ *
+ * @param {{ featureCode, loopId, loopType, stage, attempt, outcome, timestamp }} params
+ *   - stage: 'start' | 'complete'
+ *   - loopType: 'review' | 'coverage' | other
+ *   - attempt: iteration count at the time of this event (0 for start)
+ *   - outcome: server outcome string (see mapping above)
+ */
+export function buildIterationEvent({ featureCode, loopId, loopType, stage, attempt, outcome, timestamp }) {
+  const now = timestamp || new Date().toISOString();
+  const id = iterationDecisionEventId(featureCode, loopId, stage);
+  const schemaOutcome = mapIterationOutcome(outcome);
+
+  // Role assignment per design Decision 5
+  let roles = [];
+  if (loopType === 'review') {
+    roles = [{ name: 'REVIEWER', agent_id: null }];
+  } else if (loopType === 'coverage') {
+    roles = [{ name: 'IMPLEMENTER', agent_id: null }];
+  }
+
+  // Title: descriptive for start vs complete
+  let title;
+  if (stage === 'start') {
+    title = `Iteration loop started — ${loopType}`;
+  } else {
+    const cnt = attempt != null ? ` (${attempt} attempt${attempt !== 1 ? 's' : ''})` : '';
+    title = `Iteration loop complete — ${loopType}${cnt}`;
+  }
+
+  const metadata = { iteration_id: loopId };
+  // attempt is schema-optional; schema requires minimum: 1 so only include when >= 1
+  if (attempt != null && attempt >= 1) metadata.attempt = attempt;
+  if (stage !== 'start') metadata.outcome = schemaOutcome;
+
+  return {
+    id,
+    feature_code: featureCode,
+    timestamp: now,
+    kind: 'iteration',
+    title,
+    metadata,
+    roles,
+  };
+}
+
+/**
+ * Build a kind=drift_threshold DecisionEvent.
+ *
+ * Called by emitDriftAxes on the rising edge (breached false → true).
+ * id and timestamp are taken from the persisted breach_event_id and
+ * breach_started_at — NOT recomputed — so live-emit and snapshot rehydration
+ * produce byte-for-byte identical events.
+ *
+ * @param {{ featureCode, axisId, ratio, threshold, breachStartedAt, breachEventId }} params
+ */
+export function buildDriftThresholdEvent({ featureCode, axisId, ratio, threshold, breachStartedAt, breachEventId }) {
+  // If caller omits breachEventId, derive it deterministically (fallback safety).
+  const id = breachEventId || driftThresholdDecisionEventId(featureCode, axisId, breachStartedAt);
+  return {
+    id,
+    feature_code: featureCode,
+    timestamp: breachStartedAt,
+    kind: 'drift_threshold',
+    title: `Drift threshold crossed: ${axisId} (${Math.round(ratio * 100)}% ≥ ${Math.round(threshold * 100)}%)`,
+    metadata: {
+      axis_id: axisId,
+      ratio,
+      threshold,
+    },
+    roles: [],
+  };
+}
+
+/**
+ * Build a kind=gate DecisionEvent.
+ *
+ * @param {{ featureCode, gateLogEntryId, gateId, decision, timestamp }} params
+ *   - decision: route outcome string (approve|revise|kill) — translated to schema enum internally
+ */
+export function buildGateEvent({ featureCode, gateLogEntryId, gateId, decision, timestamp }) {
+  const now = timestamp || new Date().toISOString();
+  const id = gateDecisionEventId(featureCode, gateLogEntryId);
+  const schemaDecision = mapResolveOutcomeToSchema(decision);
+
+  const outcomeLabels = { approve: 'approved', interrupt: 'interrupted', deny: 'denied' };
+  const label = outcomeLabels[schemaDecision] || schemaDecision;
+
+  return {
+    id,
+    feature_code: featureCode,
+    timestamp: now,
+    kind: 'gate',
+    title: `Gate ${label}: ${gateId}`,
+    metadata: {
+      gate_id: gateId,
+      decision: schemaDecision,
+      gate_log_entry_id: gateLogEntryId,
+    },
+    roles: [],
+  };
+}

package/server/decision-event-id.js

@@ -0,0 +1,64 @@
+import { v5 as uuidv5 } from 'uuid';
+
+const ROOT_NAMESPACE = '3a7c1b12-9c10-4d02-ae9e-5f0e8bf3b2e1';
+
+export function branchDecisionEventId(featureCode, branchId) {
+  const featureNs = uuidv5(String(featureCode), ROOT_NAMESPACE);
+  return uuidv5(`branch:${branchId}`, featureNs);
+}
+
+export function shouldEmit(eventId, emittedSet) {
+  if (!emittedSet) return true;
+  if (emittedSet instanceof Set) return !emittedSet.has(eventId);
+  if (Array.isArray(emittedSet)) return !emittedSet.includes(eventId);
+  return true;
+}
+
+/**
+ * Deterministic id for a phase_transition DecisionEvent.
+ * Unique per (featureCode, fromPhase, toPhase, timestamp).
+ */
+export function phaseTransitionDecisionEventId(featureCode, fromPhase, toPhase, timestamp) {
+  const featureNs = uuidv5(String(featureCode), ROOT_NAMESPACE);
+  const from = fromPhase == null ? 'null' : String(fromPhase);
+  return uuidv5(`phase_transition:${from}:${toPhase}:${timestamp}`, featureNs);
+}
+
+/**
+ * Deterministic id for an iteration DecisionEvent.
+ * stage ∈ 'start' | 'complete'
+ */
+export function iterationDecisionEventId(featureCode, loopId, stage) {
+  const featureNs = uuidv5(String(featureCode), ROOT_NAMESPACE);
+  return uuidv5(`iteration:${loopId}:${stage}`, featureNs);
+}
+
+/**
+ * Deterministic id for a gate DecisionEvent (kind='gate').
+ * Unique per (featureCode, gateLogEntryId).
+ * Once entry.id is fixed, the event id is fixed — enabling reconciliation.
+ *
+ * @param {string} featureCode
+ * @param {string} gateLogEntryId — UUID v4 of the GateLogEntry
+ * @returns {string} UUID v5
+ */
+export function gateDecisionEventId(featureCode, gateLogEntryId) {
+  const featureNs = uuidv5(String(featureCode), ROOT_NAMESPACE);
+  return uuidv5(`gate:${gateLogEntryId}`, featureNs);
+}
+
+/**
+ * Deterministic id for a drift_threshold DecisionEvent.
+ * Unique per (featureCode, axisId, breachStartedAt).
+ * Persisted on the DriftAxis as breach_event_id so rehydration produces the
+ * same id as the live emit without recomputing from current computed_at.
+ *
+ * @param {string} featureCode
+ * @param {string} axisId — 'path_drift' | 'contract_drift' | 'review_debt_drift'
+ * @param {string} breachStartedAtIso — ISO timestamp of the rising-edge breach
+ * @returns {string} UUID v5
+ */
+export function driftThresholdDecisionEventId(featureCode, axisId, breachStartedAtIso) {
+  const featureNs = uuidv5(String(featureCode), ROOT_NAMESPACE);
+  return uuidv5(`drift_threshold:${axisId}:${breachStartedAtIso}`, featureNs);
+}