@smartmemory/compose 0.1.7-beta → 0.1.9-beta

package/lib/mcp-enforcement.js

@@ -0,0 +1,173 @@
+/**
+ * mcp-enforcement.js — helpers for COMP-MCP-MIGRATION-1 build-time
+ * enforcement of typed MCP writers against `ROADMAP.md`, `CHANGELOG.md`,
+ * and `feature.json` files.
+ *
+ * Mode parsing: `enforcement.mcpForFeatureMgmt` in `.compose/data/settings.json`
+ *   true     → 'block' (prompt + scan rejects unauthorized edits)
+ *   'log'    → 'log'   (prompt + scan emits decision events but proceeds)
+ *   anything else → 'off' (no prompt, no scan)
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const GUARDED_FILES = new Set(['ROADMAP.md', 'CHANGELOG.md']);
+
+const TOOLS_FOR_ROADMAP = ['add_roadmap_entry', 'set_feature_status', 'propose_followup'];
+const TOOLS_FOR_CHANGELOG = ['add_changelog_entry'];
+const TOOLS_FOR_FEATURE_JSON = [
+  'add_roadmap_entry',
+  'set_feature_status',
+  'link_artifact',
+  'link_features',
+  'record_completion',
+  'propose_followup',
+];
+
+/**
+ * Read `enforcement.mcpForFeatureMgmt` and normalize to 'block' | 'log' | 'off'.
+ *
+ * @param {string} dataDir - The .compose/data directory containing settings.json.
+ * @returns {'block'|'log'|'off'}
+ */
+export function readEnforcementMode(dataDir) {
+  const settingsPath = join(dataDir, 'settings.json');
+  if (!existsSync(settingsPath)) return 'off';
+  try {
+    const s = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    const v = s?.enforcement?.mcpForFeatureMgmt;
+    if (v === true) return 'block';
+    if (v === 'log') return 'log';
+    return 'off';
+  } catch {
+    return 'off';
+  }
+}
+
+/**
+ * Filter a list of dirty repo-relative file paths down to the ones under
+ * MCP-enforcement governance.
+ *
+ * @param {string[]} dirtyFiles
+ * @param {string} featuresDir - Resolved features dir (e.g. 'docs/features').
+ * @returns {string[]}
+ */
+export function filterGuarded(dirtyFiles, featuresDir) {
+  return dirtyFiles.filter(p => isGuardedPath(p, featuresDir));
+}
+
+/**
+ * @param {string} path
+ * @param {string} featuresDir
+ */
+export function isGuardedPath(path, featuresDir) {
+  if (typeof path !== 'string') return false;
+  if (GUARDED_FILES.has(path)) return true;
+  // <featuresDir>/<CODE>/feature.json
+  const prefix = featuresDir.replace(/\/$/, '') + '/';
+  if (!path.startsWith(prefix)) return false;
+  return path.endsWith('/feature.json');
+}
+
+/**
+ * Return the typed MCP tool names that could legitimately produce the given
+ * guarded path. The pre-stage scan requires at least one event from this set
+ * to be present (with matching build_id) for the path to pass.
+ *
+ * @param {string} path
+ * @param {string} featuresDir
+ * @returns {string[]}
+ */
+export function expectedToolsForPath(path, featuresDir) {
+  if (path === 'ROADMAP.md') return [...TOOLS_FOR_ROADMAP];
+  if (path === 'CHANGELOG.md') return [...TOOLS_FOR_CHANGELOG];
+  const prefix = featuresDir.replace(/\/$/, '') + '/';
+  if (path.startsWith(prefix) && path.endsWith('/feature.json')) {
+    return [...TOOLS_FOR_FEATURE_JSON];
+  }
+  return [];
+}
+
+/**
+ * Extract the feature code from a feature.json path under featuresDir, or
+ * null if the path doesn't fit that shape.
+ *
+ * @param {string} path
+ * @param {string} featuresDir
+ * @returns {string|null}
+ */
+export function featureCodeFromPath(path, featuresDir) {
+  const prefix = featuresDir.replace(/\/$/, '') + '/';
+  if (!path.startsWith(prefix) || !path.endsWith('/feature.json')) return null;
+  const middle = path.slice(prefix.length, -'/feature.json'.length);
+  if (!middle || middle.includes('/')) return null;
+  return middle;
+}
+
+/**
+ * Run the pre-stage scan: for every guarded path in dirtyFiles, verify at
+ * least one matching audit event with the current build_id exists in the
+ * provided event window. For feature.json paths, the event must also be
+ * scoped to the same feature code (so an event for feature A can't bless a
+ * dirty edit to feature B's feature.json).
+ *
+ * @param {object} args
+ * @param {string[]} args.dirtyFiles
+ * @param {string}   args.featuresDir
+ * @param {string}   args.buildId       - current build's UUID
+ * @param {Array<object>} args.events   - events from feature-events.jsonl filtered to the build window
+ * @returns {{violations: Array<{path: string, expected: string[]}>}}
+ */
+export function scanGuarded({ dirtyFiles, featuresDir, buildId, events }) {
+  const guarded = filterGuarded(dirtyFiles, featuresDir);
+  const eventsForBuild = events.filter(e => e.build_id === buildId);
+  const violations = [];
+  for (const path of guarded) {
+    const expected = expectedToolsForPath(path, featuresDir);
+    if (expected.length === 0) continue;  // unknown guarded shape — skip
+
+    // For feature.json paths, require code-level correlation so a typed
+    // event for feature A can't bless a manual edit to feature B's
+    // feature.json. ROADMAP.md and CHANGELOG.md are project-scoped, so
+    // tool-name-only matching is sufficient.
+    const requiredCode = featureCodeFromPath(path, featuresDir);
+    const matched = eventsForBuild.some(e => {
+      if (!expected.includes(e.tool)) return false;
+      if (requiredCode === null) return true;
+      // Writers all stamp `code` with the feature being mutated. propose_followup
+      // stamps the new code (which is also the feature.json being scaffolded),
+      // and link_features stamps the from_code (the source feature).
+      return e.code === requiredCode;
+    });
+    if (!matched) violations.push({ path, expected });
+  }
+  return { violations };
+}
+
+/**
+ * Construct the typed error thrown by the build runner when block-mode enforcement fires.
+ *
+ * @param {Array<{path: string, expected: string[]}>} violations
+ */
+export function enforcementError(violations) {
+  const lines = violations.map(v =>
+    `  ${v.path} — required typed tool from: ${v.expected.join(', ')}`
+  ).join('\n');
+  const err = new Error(
+    `MCP enforcement violation (enforcement.mcpForFeatureMgmt: true). ` +
+    `The following dirty paths have no matching typed-tool event in this build:\n${lines}\n` +
+    `Either re-run the failing edits via the typed MCP tools, or set ` +
+    `enforcement.mcpForFeatureMgmt to false / 'log' to bypass.`
+  );
+  err.code = 'MCP_ENFORCEMENT_VIOLATION';
+  err.violations = violations;
+  return err;
+}
+
+export const _internals = {
+  GUARDED_FILES,
+  TOOLS_FOR_ROADMAP,
+  TOOLS_FOR_CHANGELOG,
+  TOOLS_FOR_FEATURE_JSON,
+};

package/lib/migrate-roadmap.js

@@ -9,6 +9,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { parseRoadmap } from './roadmap-parser.js';
 import { readFeature, writeFeature } from './feature-json.js';
+import { loadFeaturesDir } from './project-paths.js';
 
 /**
  * Migrate ROADMAP.md entries to feature.json files.
@@ -21,7 +22,9 @@ import { readFeature, writeFeature } from './feature-json.js';
  * @returns {{ created: string[], skipped: string[], updated: string[] }}
  */
 export function migrateRoadmap(cwd, opts = {}) {
-  const featuresDir = opts.featuresDir ?? 'docs/features';
+  // COMP-MCP-MIGRATION-2-1: honor `paths.features` override so backfill
+  // writes under the configured root rather than the hardcoded default.
+  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
   const roadmapPath = join(cwd, 'ROADMAP.md');
 
   if (!existsSync(roadmapPath)) {

package/lib/project-paths.js

@@ -0,0 +1,36 @@
+/**
+ * project-paths.js — read .compose/compose.json `paths.features` override
+ * for lib-side writers.
+ *
+ * Server-side code uses `server/project-root.js`'s cached `loadProjectConfig`,
+ * but lib code may run outside the server process (CLI, tests, MCP stdio)
+ * and shouldn't share that cache. This is a tiny per-call read; the file is
+ * a few hundred bytes.
+ *
+ * Introduced by COMP-MCP-MIGRATION-2.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_FEATURES_DIR = 'docs/features';
+
+/**
+ * Resolve the project's features directory, respecting `.compose/compose.json`'s
+ * `paths.features` override. Returns the relative path (joined onto cwd by callers).
+ *
+ * @param {string} cwd
+ * @returns {string} Relative features dir, e.g. 'docs/features' or 'specs/features'.
+ */
+export function loadFeaturesDir(cwd) {
+  const cfgPath = join(cwd, '.compose', 'compose.json');
+  if (!existsSync(cfgPath)) return DEFAULT_FEATURES_DIR;
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+    const rel = cfg?.paths?.features;
+    return (typeof rel === 'string' && rel.length > 0) ? rel : DEFAULT_FEATURES_DIR;
+  } catch {
+    return DEFAULT_FEATURES_DIR;
+  }
+}
+
+export const _internals = { DEFAULT_FEATURES_DIR };

package/lib/resolve-workspace.js

@@ -0,0 +1,166 @@
+/**
+ * resolve-workspace.js — single resolver chain for compose workspaces.
+ *
+ * Precedence:
+ *   1. explicit hint.workspaceId  (cheap upward walk first; falls back to discovery)
+ *   2. COMPOSE_TARGET env         (absolute path bypasses discovery; id routes through it)
+ *   3. hint.getBinding() (MCP binding)
+ *   4. discovery (auto-pick when exactly one candidate; throws otherwise)
+ *
+ * Throws structured errors with `.code`: WorkspaceUnknown, WorkspaceAmbiguous,
+ * WorkspaceIdCollision, WorkspaceUnset. The CLI's dieOnWorkspaceError consumes them.
+ *
+ * Design intent: explicit-flag path uses findWorkspaceById (cheap upward walk)
+ * BEFORE invoking discoverWorkspaces — this lets users escape WorkspaceDiscoveryTooBroad
+ * by passing --workspace=<ancestor-id>. A descendant id still routes through discovery.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { discoverWorkspaces, deriveId } from './discover-workspaces.js';
+
+export class WorkspaceUnknown extends Error {
+  constructor(id) {
+    super(`Unknown workspaceId: ${id}`);
+    this.code = 'WorkspaceUnknown';
+    this.id = id;
+  }
+}
+
+export class WorkspaceAmbiguous extends Error {
+  constructor(candidates) {
+    super('Multiple workspaces match cwd');
+    this.code = 'WorkspaceAmbiguous';
+    this.candidates = candidates;
+  }
+}
+
+export class WorkspaceIdCollision extends Error {
+  constructor(id, roots) {
+    super(`workspaceId "${id}" used by multiple roots`);
+    this.code = 'WorkspaceIdCollision';
+    this.id = id;
+    this.roots = roots;
+  }
+}
+
+export class WorkspaceUnset extends Error {
+  constructor() {
+    super('No workspace resolved');
+    this.code = 'WorkspaceUnset';
+  }
+}
+
+/**
+ * Resolve a workspace from hints + env + cwd.
+ *
+ * @param {object} hint
+ * @param {string} [hint.cwd]          — defaults to process.cwd()
+ * @param {string} [hint.workspaceId]  — explicit --workspace=<id>
+ * @param {() => string|null} [hint.getBinding] — MCP binding accessor
+ * @returns {{id: string, root: string, configPath: string, source: string}}
+ */
+export function resolveWorkspace(hint = {}) {
+  const cwd = hint.cwd ?? process.cwd();
+
+  // 1. Explicit flag — authoritative. Cheap upward walk first; fall back to
+  //    discovery (which may throw TooBroad for pathological trees).
+  if (hint.workspaceId) {
+    const found = findWorkspaceById(cwd, hint.workspaceId);
+    if (found) return { ...found, source: 'explicit-flag' };
+    const { candidates } = discoverWorkspaces(cwd);
+    return resolveByIdScopedCollisionCheck(hint.workspaceId, candidates, 'explicit-flag');
+  }
+
+  // 2. COMPOSE_TARGET — absolute path is authoritative without discovery.
+  if (process.env.COMPOSE_TARGET) {
+    const t = process.env.COMPOSE_TARGET;
+    if (path.isAbsolute(t)) {
+      if (!fs.existsSync(t)) {
+        const e = new Error(`COMPOSE_TARGET=${t} does not exist`);
+        e.code = 'WorkspaceUnknown';
+        e.id = t;
+        throw e;
+      }
+      return { ...deriveId({ root: t }), source: 'env' };
+    }
+    const { candidates } = discoverWorkspaces(cwd);
+    return resolveByIdScopedCollisionCheck(t, candidates, 'env');
+  }
+
+  // 3. MCP binding — scoped collision check on the bound id.
+  if (hint.getBinding) {
+    const id = hint.getBinding();
+    if (id) {
+      const { candidates } = discoverWorkspaces(cwd);
+      return resolveByIdScopedCollisionCheck(id, candidates, 'mcp-binding');
+    }
+  }
+
+  // 4. Discovery — collisions matter because we're auto-picking.
+  const { candidates } = discoverWorkspaces(cwd);
+  detectCollisions(candidates);
+  if (candidates.length === 0) throw new WorkspaceUnset();
+  if (candidates.length === 1) return { ...candidates[0], source: 'discovery' };
+  throw new WorkspaceAmbiguous(candidates.map(({ id, root }) => ({ id, root })));
+}
+
+/**
+ * Cheap upward-only lookup: walk ancestors from startDir, return the first
+ * `.compose/` directory whose derived id matches targetId. Lets users bypass
+ * descendant-cap entirely via `--workspace=<ancestor-id>`.
+ */
+function findWorkspaceById(startDir, targetId) {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.compose'))) {
+      const candidate = deriveId({ root: dir });
+      if (candidate.id === targetId) return candidate;
+    }
+    if (dir === root) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function resolveByIdScopedCollisionCheck(id, candidates, source) {
+  const matching = candidates.filter((c) => c.id === id);
+  if (matching.length === 0) throw new WorkspaceUnknown(id);
+  if (matching.length > 1) {
+    throw new WorkspaceIdCollision(id, matching.map((m) => m.root));
+  }
+  return { ...matching[0], source };
+}
+
+function detectCollisions(candidates) {
+  const byId = new Map();
+  for (const c of candidates) {
+    if (!byId.has(c.id)) byId.set(c.id, []);
+    byId.get(c.id).push(c.root);
+  }
+  for (const [id, roots] of byId) {
+    if (roots.length > 1) throw new WorkspaceIdCollision(id, roots);
+  }
+}
+
+/**
+ * Pull --workspace=<id> or --workspace <id> out of args, mutating in place.
+ * Returns the id, or null if absent.
+ */
+export function getWorkspaceFlag(args) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--workspace' && i + 1 < args.length) {
+      const id = args[i + 1];
+      args.splice(i, 2);
+      return id;
+    }
+    if (typeof a === 'string' && a.startsWith('--workspace=')) {
+      const id = a.slice('--workspace='.length);
+      args.splice(i, 1);
+      return id;
+    }
+  }
+  return null;
+}

package/lib/review-lenses.js

@@ -112,27 +112,42 @@ const FRAMEWORK_PATTERNS = [
 // ---------------------------------------------------------------------------
 
 /**
- * Classify a diff by number of changed files.
+ * Classify a diff by changed-file count, optionally promoted by line count.
+ *
+ * Rules (the larger of the two classifications wins):
+ *   File count: ≤2 → small, ≤8 → medium, ≥9 → large
+ *   Line count: <50 → small, <200 → medium, ≥200 → large
+ *
+ * The line-count gate (STRAT-REV-FU-1) catches single-file mega-refactors that
+ * the original file-count-only rule under-classified. The original design called
+ * for >200 lines as the trigger — this restores parity while keeping the cheap,
+ * already-shipped file-count gate as the primary signal.
  *
  * @param {string[]} filesChanged - list of changed file paths
+ * @param {number|null} [lineCount] - optional total changed line count from `git diff --shortstat`
  * @returns {'small'|'medium'|'large'}
  */
-export function classifyDiffSize(filesChanged) {
+export function classifyDiffSize(filesChanged, lineCount = null) {
   const count = Array.isArray(filesChanged) ? filesChanged.length : 0;
-  if (count <= 2) return 'small';
-  if (count <= 8) return 'medium';
-  return 'large';
+  const fileClass = count <= 2 ? 'small' : count <= 8 ? 'medium' : 'large';
+
+  if (typeof lineCount !== 'number' || lineCount < 0) return fileClass;
+
+  const lineClass = lineCount < 50 ? 'small' : lineCount < 200 ? 'medium' : 'large';
+  const rank = { small: 0, medium: 1, large: 2 };
+  return rank[fileClass] >= rank[lineClass] ? fileClass : lineClass;
 }
 
 /**
  * Whether cross-model (Codex) review should run for this diff.
- * Only triggers for large diffs (≥9 files).
+ * Triggers for large diffs (≥9 files OR ≥200 changed lines).
  *
  * @param {string[]} filesChanged - list of changed file paths
+ * @param {number|null} [lineCount] - optional total changed line count
  * @returns {boolean}
  */
-export function shouldRunCrossModel(filesChanged) {
-  return classifyDiffSize(filesChanged) === 'large';
+export function shouldRunCrossModel(filesChanged, lineCount = null) {
+  return classifyDiffSize(filesChanged, lineCount) === 'large';
 }
 
 // ---------------------------------------------------------------------------

package/lib/review-normalize.js

@@ -282,9 +282,12 @@ export async function normalizeCrossModelResult(rawText, {
     && Array.isArray(parsed.claude_only)
     && Array.isArray(parsed.codex_only);
   if (!hasAllArrays) {
+    // STRAT-REV-FU-3: defensively promote fallback confidence so caller-supplied findings
+    // can't silently drop below the gate filter (regression: codexAsFallback shipped at
+    // confidence=6 with gate=7, dropping all fallback findings on synthesis parse failure).
     consensusRaw  = [];
-    claudeOnlyRaw = claudeFindingsFallback;
-    codexOnlyRaw  = codexFindingsFallback;
+    claudeOnlyRaw = claudeFindingsFallback.map(f => promoteFallbackConfidence(f, confidenceGate));
+    codexOnlyRaw  = codexFindingsFallback.map(f => promoteFallbackConfidence(f, confidenceGate));
   } else {
     consensusRaw  = parsed.consensus;
     claudeOnlyRaw = parsed.claude_only;
@@ -306,11 +309,12 @@ export async function normalizeCrossModelResult(rawText, {
     };
   };
 
-  const consensus  = consensusRaw.map(normalizeFinding).filter(f => f.confidence >= f.applied_gate);
+  const consensus  = consensusRaw.map(normalizeFinding).filter(f => f.confidence >= f.applied_gate).map(promoteConsensusFinding);
   const claude_only = claudeOnlyRaw.map(normalizeFinding).filter(f => f.confidence >= f.applied_gate);
   const codex_only  = codexOnlyRaw.map(normalizeFinding).filter(f => f.confidence >= f.applied_gate);
 
   // Step 4: Merge all findings into top-level findings array
+  // (consensus stamp + boost flow through unchanged so cockpit can highlight high-conviction issues)
   const findings = [...consensus, ...claude_only, ...codex_only];
 
   // Step 5: Compute clean across all three arrays
@@ -397,6 +401,41 @@ function buildCrossModelRepairPrompt(badText) {
   );
 }
 
+/**
+ * STRAT-REV-FU-2: promote a consensus finding — stamp consensus:true and boost
+ * confidence by 2 (capped at 10). Two independent models agreeing is materially
+ * stronger evidence than either alone, so the cockpit treats these as high-conviction.
+ *
+ * @param {object} f
+ * @returns {object}
+ */
+const CONSENSUS_BOOST = 2;
+const MAX_CONFIDENCE = 10;
+function promoteConsensusFinding(f) {
+  return {
+    ...f,
+    consensus: true,
+    confidence: Math.min(MAX_CONFIDENCE, f.confidence + CONSENSUS_BOOST),
+  };
+}
+
+/**
+ * STRAT-REV-FU-3: clone a fallback finding and promote its confidence to applied_gate
+ * if it's under-stamped. The fallback path is the only place we trust the caller's
+ * intent over the model's confidence — these findings come from prior model output that
+ * already passed its own gate, so suppressing them via gate-filter is silent data loss.
+ *
+ * @param {object} f
+ * @param {number} confidenceGate
+ * @returns {object}
+ */
+function promoteFallbackConfidence(f, confidenceGate) {
+  const gate = typeof f.applied_gate === 'number' ? f.applied_gate : confidenceGate;
+  const conf = typeof f.confidence === 'number' ? f.confidence : 5;
+  if (conf >= gate) return f;
+  return { ...f, confidence: gate };
+}
+
 /**
  * Normalize severity strings to canonical values.
  * Accepts: must-fix, must_fix, MUST-FIX, should-fix, should_fix, nit, etc.

package/lib/roadmap-drift.js

@@ -0,0 +1,54 @@
+/**
+ * Drift detection for ROADMAP.md typed-writer regen.
+ *
+ * COMP-MCP-MIGRATION-2-1-1 T2 (Option A).
+ *
+ * When a phase heading carries a curated status override (e.g. `PARTIAL
+ * (1a–1d COMPLETE, 2 PLANNED)`) that diverges from the rollup-computed
+ * status from feature.json, the writer keeps the override (per Decision 2)
+ * and emits a `roadmap_drift` event so the divergence is visible.
+ *
+ * Dedupe is at read time inside emitDrift() — appendEvent() does not
+ * enforce idempotency_key, so we read recent events and short-circuit
+ * if the same drift triple was already recorded.
+ */
+
+import { appendEvent, readEvents } from './feature-events.js';
+
+const DEDUPE_WINDOW_MS = 24 * 60 * 60 * 1000; // 24h
+
+/**
+ * Emit a roadmap drift event with read-side dedupe.
+ *
+ * Always writes a stderr warning. Only writes a new event if the same
+ * (phaseId, override, computed) triple hasn't been recorded in the last
+ * 24h.
+ *
+ * @param {string} cwd
+ * @param {{phaseId: string, override: string, computed: string}} info
+ */
+export function emitDrift(cwd, { phaseId, override, computed }) {
+  process.stderr.write(
+    `WARN: phase "${phaseId}" override "${override}" diverges from rollup "${computed}". Edit ROADMAP.md to acknowledge.\n`
+  );
+
+  const recent = readEvents(cwd, { since: Date.now() - DEDUPE_WINDOW_MS });
+  for (const ev of recent) {
+    if (
+      ev.tool === 'roadmap_drift' &&
+      ev.code === phaseId &&
+      ev.from === computed &&
+      ev.to === override
+    ) {
+      return; // already recorded within window
+    }
+  }
+
+  appendEvent(cwd, {
+    tool: 'roadmap_drift',
+    code: phaseId,
+    from: computed,
+    to: override,
+    reason: 'override-vs-rollup-divergence',
+  });
+}