@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/dispatch-ledger.js

@@ -0,0 +1,301 @@
+/**
+ * dispatch-ledger.js — closed, append-only telemetry events for agent dispatch.
+ *
+ * Ledger rows are addressed by an explicit project root so callers running in a
+ * worktree cannot accidentally split telemetry away from the build project.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+import { normalizeSince } from './feature-events.js';
+
+export const DISPATCH_LEDGER_RELATIVE_PATH = '.compose/data/dispatch-ledger.jsonl';
+
+/**
+ * Resolve the project root a dispatch connector should address its ledger by.
+ *
+ * Two paths write telemetry into the live compose checkout during a test run:
+ * an unattributed dispatch with no project_cwd falls back to process.cwd(), and
+ * a test that explicitly roots a build at process.cwd() threads that same live
+ * path through. Under NODE_TEST_CONTEXT, any ledger write addressed at the
+ * process cwd (the live checkout) is redirected to a hermetic tmpdir so
+ * full-suite runs never accrete fixture rows in the real .compose/data ledger.
+ * A test that threads its own tmpdir project root is addressed there, unchanged.
+ * Production paths never set NODE_TEST_CONTEXT, so they are unaffected.
+ *
+ * @param {string} [explicitCwd] the caller's project_cwd, when known
+ * @returns {string}
+ */
+export function resolveDispatchLedgerCwd(explicitCwd) {
+  const cwd = isString(explicitCwd) ? explicitCwd : process.cwd();
+  if (process.env.NODE_TEST_CONTEXT && resolve(cwd) === resolve(process.cwd())) {
+    return join(tmpdir(), 'compose-test-worktrees', 'dispatch-ledger');
+  }
+  return cwd;
+}
+
+export const DISPATCH_SITES = Object.freeze([
+  'build-step', 'consumer', 'review', 'review-repair', 'policy-revision', 'gsd',
+  'gate-qa', 'escalation', 'preflight', 'judge', 'design-chat', 'import',
+  'validation', 'new-project', 'unattributed',
+]);
+export const DISPATCH_OUTCOMES = Object.freeze(['ok', 'error', 'blocked']);
+export const SETTLEMENT_FAILURE_CLASSES = Object.freeze([
+  'ownership', 'vocabulary', 'normalization', 'agent', 'ensure-retry',
+]);
+export const ESTIMATE_LANES = Object.freeze(['trivial', 'standard', 'complex']);
+export const ESTIMATE_SOURCES = Object.freeze(['fresh', 'cached', 'escalated']);
+export const TRIAGE_CONFIDENCES = Object.freeze(['high', 'medium', 'low']);
+export const BUILD_TERMINAL_STATUSES = Object.freeze(['complete', 'failed', 'aborted']);
+export const BUILD_FILES_SOURCES = Object.freeze(['ship', 'accumulated']);
+
+const EVENT_FIELDS = {
+  dispatch: {
+    required: ['dispatch_id', 'site', 'agent', 'outcome'],
+    optional: [
+      'build_id', 'feature_code', 'step_id', 'attempt', 'model',
+      'effort_intended', 'effort_executed', 'tokens_in', 'tokens_out',
+      'tokens_total', 'usd', 'duration_ms', 'note',
+    ],
+  },
+  settlement: {
+    required: ['dispatch_id', 'accepted'],
+    optional: ['build_id', 'step_id', 'failure_class'],
+  },
+  'triage-estimate': {
+    required: ['build_id', 'feature_code', 'tier', 'lane', 'profile', 'estimate_source'],
+    optional: ['confidence'],
+  },
+  'build-actuals': {
+    required: [
+      'build_id', 'feature_code', 'terminal_status', 'files_changed_count',
+      'files_source', 'review_iterations', 'escalations', 'tokens_total', 'usd',
+    ],
+    optional: ['test_count', 'pass_rate'],
+  },
+};
+
+const countersByPath = new Map();
+
+function ledgerPath(projectCwd) {
+  return resolve(projectCwd, DISPATCH_LEDGER_RELATIVE_PATH);
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isNullableFiniteNumber(value) {
+  return value === null || isFiniteNumber(value);
+}
+
+function isNullableString(value) {
+  return value === null || isString(value);
+}
+
+function isEnum(value, values) {
+  return values.includes(value);
+}
+
+function invalid(message) {
+  throw new Error(`dispatch-ledger.appendEvent: ${message}`);
+}
+
+function validateEvent(event, { allowExtra = false } = {}) {
+  if (!isPlainObject(event)) invalid('event must be an object');
+  if (!isString(event.kind)) invalid('kind is required');
+  const shape = EVENT_FIELDS[event.kind];
+  if (!shape) invalid(`unknown kind "${event.kind}"`);
+
+  const allowed = new Set(['kind', ...shape.required, ...shape.optional]);
+  if (!allowExtra) {
+    for (const field of Object.keys(event)) {
+      if (!allowed.has(field)) invalid(`unknown field "${field}" for ${event.kind}`);
+    }
+  }
+  for (const field of shape.required) {
+    if (!Object.hasOwn(event, field) || event[field] === undefined) {
+      invalid(`required field "${field}" is missing for ${event.kind}`);
+    }
+  }
+
+  switch (event.kind) {
+    case 'dispatch':
+      requireString(event, 'dispatch_id');
+      requireEnum(event, 'site', DISPATCH_SITES);
+      requireString(event, 'agent');
+      requireEnum(event, 'outcome', DISPATCH_OUTCOMES);
+      optionalString(event, 'build_id');
+      optionalString(event, 'feature_code');
+      optionalString(event, 'step_id');
+      optionalNumber(event, 'attempt');
+      optionalNullableString(event, 'model');
+      optionalNullableString(event, 'effort_intended');
+      optionalNullableString(event, 'effort_executed');
+      for (const field of ['tokens_in', 'tokens_out', 'tokens_total', 'usd', 'duration_ms']) {
+        optionalNullableNumber(event, field);
+      }
+      optionalString(event, 'note');
+      break;
+    case 'settlement':
+      requireString(event, 'dispatch_id');
+      if (typeof event.accepted !== 'boolean') invalid('accepted must be a boolean');
+      optionalString(event, 'build_id');
+      optionalString(event, 'step_id');
+      optionalEnum(event, 'failure_class', SETTLEMENT_FAILURE_CLASSES);
+      break;
+    case 'triage-estimate':
+      requireString(event, 'build_id');
+      requireString(event, 'feature_code');
+      if (!Number.isInteger(event.tier) || event.tier < 0 || event.tier > 4) {
+        invalid('tier must be an integer 0-4');
+      }
+      requireEnum(event, 'lane', ESTIMATE_LANES);
+      if (!isPlainObject(event.profile)) invalid('profile must be a non-array object');
+      requireEnum(event, 'estimate_source', ESTIMATE_SOURCES);
+      if (Object.hasOwn(event, 'confidence') && event.confidence !== null && !isEnum(event.confidence, TRIAGE_CONFIDENCES)) {
+        invalid(`confidence must be one of ${TRIAGE_CONFIDENCES.join(', ')} or null`);
+      }
+      break;
+    case 'build-actuals':
+      requireString(event, 'build_id');
+      requireString(event, 'feature_code');
+      requireEnum(event, 'terminal_status', BUILD_TERMINAL_STATUSES);
+      requireNumber(event, 'files_changed_count');
+      requireEnum(event, 'files_source', BUILD_FILES_SOURCES);
+      requireNumber(event, 'review_iterations');
+      requireNumber(event, 'escalations');
+      requireNumber(event, 'tokens_total');
+      requireNumber(event, 'usd');
+      optionalNullableNumber(event, 'test_count');
+      optionalNullableNumber(event, 'pass_rate');
+      break;
+  }
+}
+
+function requireString(event, field) {
+  if (!isString(event[field])) invalid(`${field} must be a non-empty string`);
+}
+
+function requireNumber(event, field) {
+  if (!isFiniteNumber(event[field])) invalid(`${field} must be a number`);
+}
+
+function requireEnum(event, field, values) {
+  if (!isEnum(event[field], values)) invalid(`${field} must be one of ${values.join(', ')}`);
+}
+
+function optionalString(event, field) {
+  if (Object.hasOwn(event, field) && !isString(event[field])) invalid(`${field} must be a non-empty string`);
+}
+
+function optionalNullableString(event, field) {
+  if (Object.hasOwn(event, field) && !isNullableString(event[field])) invalid(`${field} must be a string or null`);
+}
+
+function optionalNumber(event, field) {
+  if (Object.hasOwn(event, field) && !isFiniteNumber(event[field])) invalid(`${field} must be a number`);
+}
+
+function optionalNullableNumber(event, field) {
+  if (Object.hasOwn(event, field) && !isNullableFiniteNumber(event[field])) invalid(`${field} must be a number or null`);
+}
+
+function optionalEnum(event, field, values) {
+  if (Object.hasOwn(event, field) && !isEnum(event[field], values)) {
+    invalid(`${field} must be one of ${values.join(', ')}`);
+  }
+}
+
+function isValidStoredRow(row) {
+  if (!isPlainObject(row) || row.v !== 1 || !isIsoTimestamp(row.ts) || !Number.isInteger(row._seq) || row._seq < 0) {
+    return false;
+  }
+  try {
+    validateEvent(row, { allowExtra: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isIsoTimestamp(value) {
+  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value) && !Number.isNaN(Date.parse(value));
+}
+
+function seedCounter(path) {
+  if (countersByPath.has(path)) return countersByPath.get(path);
+  let highest = 0;
+  if (existsSync(path)) {
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const row = JSON.parse(line);
+        if (isValidStoredRow(row)) highest = Math.max(highest, row._seq);
+      } catch {
+        // A torn JSONL row must not prevent later rows from being read.
+      }
+    }
+  }
+  countersByPath.set(path, highest);
+  return highest;
+}
+
+/**
+ * Append one closed dispatch-ledger event, stamping its immutable envelope.
+ *
+ * @param {string} projectCwd
+ * @param {object} event caller-supplied kind and closed payload only
+ * @returns {object} the row written to disk
+ */
+export function appendEvent(projectCwd, event) {
+  validateEvent(event);
+  const path = ledgerPath(projectCwd);
+  const nextSeq = seedCounter(path) + 1;
+  countersByPath.set(path, nextSeq);
+  const row = { v: 1, ts: new Date().toISOString(), _seq: nextSeq, ...event };
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, JSON.stringify(row) + '\n');
+  return row;
+}
+
+/**
+ * Tolerantly read valid, known ledger rows. Future fields are preserved.
+ *
+ * @param {string} projectCwd
+ * @param {object} [opts]
+ * @param {string} [opts.kind]
+ * @param {string|number|Date} [opts.since]
+ * @param {string} [opts.feature]
+ * @returns {Array<object>}
+ */
+export function readEvents(projectCwd, { kind, since, feature } = {}) {
+  const path = ledgerPath(projectCwd);
+  if (!existsSync(path)) return [];
+  const sinceMs = normalizeSince(since);
+  const rows = [];
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (!isValidStoredRow(row)) continue;
+      if (kind && row.kind !== kind) continue;
+      if (feature && row.feature_code !== feature) continue;
+      if (sinceMs !== null && Date.parse(row.ts) < sinceMs) continue;
+      rows.push(row);
+    } catch {
+      // Malformed rows are expected in an append-only JSONL file after a tear.
+    }
+  }
+  return rows;
+}

package/lib/dispatch-metrics.js

@@ -0,0 +1,236 @@
+/**
+ * dispatch-metrics.js — read-only aggregation over the dispatch ledger.
+ *
+ * This module deliberately keeps the ledger's append-only observations intact:
+ * settlements and terminal actuals are reduced at read time by their `_seq`.
+ */
+
+import { readEvents } from './dispatch-ledger.js';
+
+const RETRY_NOTE = 'known undercount: child flows';
+const GSD_NOTE = 'not instrumented';
+
+function isNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function upperMiddle(values) {
+  const sorted = values.filter(isNumber).sort((a, b) => a - b);
+  return sorted.length ? sorted[Math.floor(sorted.length / 2)] : null;
+}
+
+function rate(numerator, denominator) {
+  return denominator > 0 ? numerator / denominator : null;
+}
+
+function highestBy(rows, key) {
+  const result = new Map();
+  for (const row of rows) {
+    const current = result.get(row[key]);
+    if (!current || row._seq > current._seq) result.set(row[key], row);
+  }
+  return result;
+}
+
+function compareNullable(a, b) {
+  if (a === b) return 0;
+  if (a === null || a === undefined) return -1;
+  if (b === null || b === undefined) return 1;
+  return String(a).localeCompare(String(b));
+}
+
+function collectRowStats(dispatches, settlements, { gsd = false } = {}) {
+  const tokenValues = dispatches.map((row) => row.tokens_total).filter(isNumber);
+  const durationValues = dispatches.map((row) => row.duration_ms).filter(isNumber);
+  const settled = dispatches
+    .map((row) => settlements.get(row.dispatch_id))
+    .filter(Boolean);
+  const accepted = settled.filter((row) => row.accepted).length;
+  const retryEligible = dispatches.filter((row) => isNumber(row.attempt));
+  const retries = retryEligible.filter((row) => row.attempt > 1).length;
+
+  return {
+    token_sample_count: tokenValues.length,
+    null_usage_count: dispatches.filter((row) => !isNumber(row.tokens_total)).length,
+    median_tokens: upperMiddle(tokenValues),
+    duration_sample_count: durationValues.length,
+    median_duration_ms: upperMiddle(durationValues),
+    completion: {
+      ok: dispatches.filter((row) => row.outcome === 'ok').length,
+      total: dispatches.length,
+      rate: rate(dispatches.filter((row) => row.outcome === 'ok').length, dispatches.length),
+    },
+    acceptance: {
+      accepted,
+      settled: settled.length,
+      rate: rate(accepted, settled.length),
+      note: gsd ? GSD_NOTE : null,
+    },
+    retry: {
+      retries,
+      eligible: retryEligible.length,
+      rate: rate(retries, retryEligible.length),
+      note: RETRY_NOTE,
+    },
+    usd_total: dispatches.reduce((total, row) => total + (isNumber(row.usd) ? row.usd : 0), 0),
+  };
+}
+
+function realizedLane(actual) {
+  if (actual.escalations >= 1 || actual.review_iterations >= 3 || actual.files_changed_count >= 6) return 'complex';
+  if (actual.files_changed_count <= 2 && actual.review_iterations <= 1 && actual.escalations === 0) return 'trivial';
+  return 'standard';
+}
+
+function acrrSummary(rows) {
+  const total = rows.length;
+  const matched = rows.filter((row) => row.matched).length;
+  return { matched, total, rate: rate(matched, total) };
+}
+
+/**
+ * Aggregate dispatch, settlement, estimate, and terminal actual rows without
+ * mutating the ledger.
+ *
+ * @param {string} projectCwd
+ * @param {{ since?: string|number|Date, feature?: string }} [opts]
+ * @returns {object}
+ */
+export function collectDispatchMetrics(projectCwd, { since, feature } = {}) {
+  // Settlements have no feature code. Read one since-filtered population first,
+  // then join them to the feature-filtered dispatches below.
+  const allRows = readEvents(projectCwd, { since });
+  const inFeature = (row) => !feature || row.feature_code === feature;
+  const dispatches = allRows.filter((row) => row.kind === 'dispatch' && inFeature(row));
+  const settlements = highestBy(allRows.filter((row) => row.kind === 'settlement'), 'dispatch_id');
+
+  const modelBuckets = new Map();
+  for (const row of dispatches) {
+    const executed = row.effort_executed ?? null;
+    const intendedWhenUnknown = executed === null ? (row.effort_intended ?? null) : null;
+    const values = [row.model ?? null, executed, intendedWhenUnknown];
+    const key = JSON.stringify(values);
+    if (!modelBuckets.has(key)) modelBuckets.set(key, { values, rows: [] });
+    modelBuckets.get(key).rows.push(row);
+  }
+  const model_effort = [...modelBuckets.values()]
+    .sort((a, b) => compareNullable(a.values[0], b.values[0]) || compareNullable(a.values[1], b.values[1]) || compareNullable(a.values[2], b.values[2]))
+    .map(({ values: [model, effort_executed, effort_intended_when_unknown], rows }) => {
+      const stats = collectRowStats(rows, settlements, { gsd: rows.every((row) => row.site === 'gsd') });
+      return {
+        model, effort_executed, effort_intended_when_unknown, dispatch_count: rows.length,
+        ...stats,
+      };
+    });
+
+  const siteBuckets = new Map();
+  for (const row of dispatches) {
+    if (!siteBuckets.has(row.site)) siteBuckets.set(row.site, []);
+    siteBuckets.get(row.site).push(row);
+  }
+  const sites = [...siteBuckets.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([site, rows]) => ({ site, dispatch_count: rows.length, ...collectRowStats(rows, settlements, { gsd: site === 'gsd' }) }));
+
+  const estimates = allRows.filter((row) => row.kind === 'triage-estimate' && inFeature(row));
+  const actualRows = allRows.filter((row) => row.kind === 'build-actuals' && inFeature(row));
+  const actuals = highestBy(actualRows, 'build_id');
+  const estimateBuildIds = new Set(estimates.map((row) => row.build_id));
+  const acrrRows = estimates
+    .map((estimate) => {
+      const actual = actuals.get(estimate.build_id) ?? null;
+      const eligible = actual?.terminal_status === 'complete';
+      const lane = eligible ? realizedLane(actual) : null;
+      return {
+        build_id: estimate.build_id,
+        feature_code: estimate.feature_code,
+        estimate_source: estimate.estimate_source,
+        confidence: estimate.confidence ?? null,
+        estimated_lane: estimate.lane,
+        terminal_status: actual?.terminal_status ?? null,
+        realized_lane: lane,
+        matched: eligible ? estimate.lane === lane : false,
+        files_changed_count: actual?.files_changed_count ?? null,
+        files_source: actual?.files_source ?? null,
+        review_iterations: actual?.review_iterations ?? null,
+        escalations: actual?.escalations ?? null,
+      };
+    })
+    .sort((a, b) => a.build_id.localeCompare(b.build_id));
+  const eligibleRows = acrrRows.filter((row) => row.terminal_status === 'complete' && row.estimate_source !== 'escalated');
+  const escalatedRows = acrrRows.filter((row) => row.terminal_status === 'complete' && row.estimate_source === 'escalated');
+  const failed_attempts = actualRows.filter((row) => row.terminal_status === 'failed').length;
+  const aborted_attempts = actualRows.filter((row) => row.terminal_status === 'aborted').length;
+
+  return {
+    v: 1,
+    filters: { since: since ?? null, feature: feature ?? null },
+    coverage: {
+      dispatch_count: dispatches.length,
+      unattributed_count: dispatches.filter((row) => row.site === 'unattributed').length,
+      null_usage_count: dispatches.filter((row) => !isNumber(row.tokens_total)).length,
+    },
+    model_effort,
+    sites,
+    acrr: {
+      eligible: acrrSummary(eligibleRows),
+      escalated: acrrSummary(escalatedRows),
+      attrition_count: failed_attempts + aborted_attempts,
+      failed_attempts,
+      aborted_attempts,
+      pending_count: acrrRows.filter((row) => row.terminal_status === null).length,
+      unpaired_count: [...actuals.keys()].filter((buildId) => !estimateBuildIds.has(buildId)).length,
+      rows: acrrRows,
+    },
+    known_limitations: { retry_rate: RETRY_NOTE, gsd_acceptance: GSD_NOTE },
+  };
+}
+
+function formatRate(value) {
+  return value === null ? 'n/a' : `${(value * 100).toFixed(1)}%`;
+}
+
+function formatMedian(value) {
+  return value === null ? 'n/a' : String(value);
+}
+
+function formatAcceptance(acceptance) {
+  return acceptance.note === GSD_NOTE ? 'n/a (not instrumented)' : formatRate(acceptance.rate);
+}
+
+/** Render a compact, stable human report for `compose metrics`. */
+export function renderDispatchMetrics(report) {
+  const lines = [
+    'Model × executed effort',
+    'model | executed | intended when unknown | dispatches | median tokens | median ms | completion | acceptance | retry | usd',
+  ];
+  for (const row of report.model_effort) {
+    lines.push([
+      row.model === null ? '(model: unknown)' : row.model,
+      row.effort_executed ?? 'unknown',
+      row.effort_intended_when_unknown ?? '—',
+      row.dispatch_count,
+      formatMedian(row.median_tokens),
+      formatMedian(row.median_duration_ms),
+      formatRate(row.completion.rate),
+      formatAcceptance(row.acceptance),
+      formatRate(row.retry.rate),
+      row.usd_total,
+    ].join(' | '));
+  }
+  lines.push('', 'Sites', 'site | dispatches | median tokens | median ms | completion | acceptance | retry | usd');
+  for (const row of report.sites) {
+    lines.push([
+      row.site, row.dispatch_count, formatMedian(row.median_tokens), formatMedian(row.median_duration_ms),
+      formatRate(row.completion.rate), formatAcceptance(row.acceptance), formatRate(row.retry.rate), row.usd_total,
+    ].join(' | '));
+  }
+  lines.push('', 'ACRR');
+  lines.push(`eligible: ${report.acrr.eligible.matched}/${report.acrr.eligible.total} (${formatRate(report.acrr.eligible.rate)})`);
+  lines.push(`escalated: ${report.acrr.escalated.matched}/${report.acrr.escalated.total} (${formatRate(report.acrr.escalated.rate)})`);
+  lines.push(`attrition: ${report.acrr.attrition_count} (failed attempts: ${report.acrr.failed_attempts}, aborted attempts: ${report.acrr.aborted_attempts}, pending: ${report.acrr.pending_count}, unpaired: ${report.acrr.unpaired_count})`);
+  lines.push('', 'Known limitations');
+  lines.push(`retry rate: ${report.known_limitations.retry_rate}`);
+  lines.push(`GSD acceptance: ${report.known_limitations.gsd_acceptance}`);
+  return `${lines.join('\n')}\n`;
+}

package/lib/experiment-judge.js

@@ -121,6 +121,7 @@ export async function judge({ diff, goal, judgeModel, stratum, cwd }) {
   try {
     const prompt = buildJudgePrompt(diff, goal);
     const { provider, modelID, thinking, effort } = resolveAgentConfig(judgeModel);
+    const telemetry = { site: 'judge', project_cwd: cwd };
 
     let text;
     if (typeof stratum.agentRun === 'function') {
@@ -130,11 +131,15 @@ export async function judge({ diff, goal, judgeModel, stratum, cwd }) {
         thinking: thinking ?? undefined,
         effort:   effort   ?? undefined,
         cwd:      cwd      ?? undefined,
+        telemetry,
       });
       text = result?.text ?? '';
     } else {
       // Fallback: runAgentText (no model pinning — test harnesses may use this).
-      text = await stratum.runAgentText(provider, prompt, { cwd: cwd ?? undefined });
+      text = await stratum.runAgentText(provider, prompt, {
+        cwd: cwd ?? undefined,
+        telemetry,
+      });
     }
 
     return extractJudgeResult(text);

package/lib/feature-json.js

@@ -18,7 +18,7 @@ import { resolvePathValue } from './paths-core.js';
  * Identical to join(cwd, featuresDir) for plain relative dirs.
  * @returns {string} absolute features dir
  */
-function featuresBase(cwd, featuresDir) {
+export function featuresBase(cwd, featuresDir) {
   return resolvePathValue(cwd, featuresDir, 'features');
 }
 

package/lib/feature-reconciler.js

@@ -239,6 +239,14 @@ async function applyEntry(cwd, entry) {
       const writer = new VisionWriter(join(cwd, '.compose', 'data'));
       const item = await writer.findFeatureItem(entry.feature_code);
       if (!item) return { changed: false };
+      if (entry._visStatus === 'complete') {
+        // COMP-COMPLETION-GATE slice 3 (AC-16a): repair is a projection of
+        // canonical truth, so it routes through the self-verifying seam rather
+        // than a carve-out. completeItem re-reads feature.json (and the guard
+        // ledger when a resource exists) before writing, and stamps the tier.
+        await writer.completeItem(item.id, { featureCode: entry.feature_code, cwd });
+        return { changed: true };
+      }
       await writer.updateItemStatus(item.id, entry._visStatus);
       return { changed: true };
     }

package/lib/feature-validator.js

@@ -24,6 +24,16 @@
  *   - XREF_URL_UNCHECKED    (info)    url + reserved url-class providers
  *                                     (jira|linear|notion|obsidian) — recorded,
  *                                     not resolved
+ * Plus the 5 COMP-COVERAGE-GATE project-scope kinds, which describe Compose's
+ * OWN MCP tool surface rather than the workspace (see lib/coverage-gate.js):
+ *   - MISSING_EFFECT        (error)   tool definition declares no `effect`
+ *   - UNGATED_MUTATION      (warning) mutating tool named by no profile list
+ *   - ORPHAN_REGISTRY_TOOL  (warning) canon entry names a tool that is gone
+ *   - UNCOVERED_WRITE       (info)    declared canon write absent from that
+ *                                     entry's tool list (deny-message honesty)
+ *   - COVERAGE_CHECK_SKIPPED (warning) the check itself errored — never aborts
+ * These appear in `findings` AND, structured, under `result.coverage`.
+ *
  * Full catalog + trigger/degrade/gating contract:
  *   docs/features/COMP-MCP-VALIDATE/design.md
  */
@@ -46,6 +56,14 @@ import { SchemaValidator } from '../server/schema-validator.js';
 import {
   resolveRoadmapPathFromConfig, resolveFeaturesPathFromConfig, resolveJournalPathFromConfig,
 } from './project-paths.js';
+// COMP-COVERAGE-GATE slice 2. Imported from server/mcp-tool-defs.js, NEVER from
+// server/compose-mcp.js — the latter connects a StdioServerTransport at module
+// load and hangs any importer.
+import { TOOLS as MCP_TOOL_DEFS } from '../server/mcp-tool-defs.js';
+import { loadToolInventory } from './tool-inventory.js';
+import { canonEntries } from './canon-registry.js';
+import { PROFILE_POLICY, PHASE_REFINEMENT } from '../server/mcp-tool-policy.js';
+import { checkAuthorizationCoverage } from './coverage-gate.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -1130,6 +1148,44 @@ async function runExternalRefChecks(ctx, findings, options = {}) {
   }
 }
 
+/**
+ * COMP-COVERAGE-GATE slice 2 — authorization coverage of Compose's OWN MCP tool
+ * surface.
+ *
+ * Project-scoped, not feature-scoped: it is a property of the installation, not
+ * of any one feature, so it is deliberately absent from validateFeature.
+ *
+ * Pushes its findings into the main `findings` array (so the CLI exit code,
+ * --block-on and the REST severity rollup all pick them up with no fork) AND
+ * returns the structured section for callers that want the codes and
+ * remediations without re-parsing prose.
+ *
+ * Never throws: a coverage bug must not take down a validate run that is mostly
+ * about the workspace.
+ *
+ * @param {Array} findings — mutated in place
+ * @returns {{ findings: Array }}
+ */
+function runCoverageCheck(findings) {
+  try {
+    const inventory = loadToolInventory(MCP_TOOL_DEFS);
+    const result = checkAuthorizationCoverage({
+      inventory,
+      registry: canonEntries(),
+      policy: { PROFILE_POLICY, PHASE_REFINEMENT },
+    });
+    for (const f of result.findings) {
+      findings.push(finding(f.severity, f.code, null, f.remediation, 'coverage'));
+    }
+    return result;
+  } catch (e) {
+    findings.push(finding('warning', 'COVERAGE_CHECK_SKIPPED', null,
+      `authorization coverage check skipped (unexpected error): ${e && e.message ? e.message : e}`,
+      'coverage'));
+    return { findings: [] };
+  }
+}
+
 export async function validateProject(cwd, options = {}) {
   const ctx = loadValidationContext(cwd, options);
   const findings = [];
@@ -1234,5 +1290,12 @@ export async function validateProject(cwd, options = {}) {
   // false positive. Strip them in one place (robust against new such checks) and
   // record the skip as a single info finding. feature.json↔vision drift is left
   // intact — it doesn't involve the roadmap.
-  return { scope: 'project', validated_at: nowIso(), findings: applyNarrativeSuppression(findings, ctx) };
+  const coverage = runCoverageCheck(findings);
+
+  return {
+    scope: 'project',
+    validated_at: nowIso(),
+    findings: applyNarrativeSuppression(findings, ctx),
+    coverage,
+  };
 }