@smartmemory/compose 0.2.3-beta → 0.2.5-beta

package/lib/feature-writer.js

@@ -311,7 +311,11 @@ export async function setFeatureStatus(cwd, args) {
     }
 
     const allowed = TRANSITIONS[from] ?? [];
-    if (!allowed.includes(to) && !args.force) {
+    // `derived: true` marks a lifecycle-authoritative projection (COMP-MCP-ENFORCE
+    // Slice 2, lifecycle-as-truth): the roadmap transition table is not the
+    // authority for lifecycle-driven status, so the table check is skipped — but
+    // the roundtrip fixed-point guard below still applies (this is NOT `force`).
+    if (!allowed.includes(to) && !args.force && !args.derived) {
       throw new Error(
         `feature-writer: invalid transition for ${args.code}: ${from} → ${to}. ` +
         `Allowed from ${from}: [${allowed.join(', ') || 'none'}]. ` +
@@ -353,6 +357,7 @@ export async function setFeatureStatus(cwd, args) {
     if (args.reason) event.reason = args.reason;
     if (args.commit_sha) event.commit_sha = args.commit_sha;
     if (args.force && !allowed.includes(to)) event.forced = true;
+    if (args.derived && !allowed.includes(to)) event.derived = true;
     await safeAppendEvent(cwd, event);
 
     return { code: args.code, from, to, ts: new Date().toISOString(), roundtrip };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.3-beta",
+  "version": "0.2.5-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/server/compose-mcp-tools.js

@@ -9,7 +9,108 @@ import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { ArtifactManager, ARTIFACT_SCHEMAS } from './artifact-manager.js';
-import { getTargetRoot, getDataDir, resolveProjectPath, switchProject, setCurrentWorkspaceId } from './project-root.js';
+import { getTargetRoot, getDataDir, resolveProjectPath, switchProject, setCurrentWorkspaceId, loadProjectConfig } from './project-root.js';
+
+/**
+ * COMP-MCP-ENFORCE Slice 3 — kill the `force` escape hatch at the MCP tool
+ * boundary. When capabilities.guard is on, a caller-supplied force:true on a
+ * status/roadmap mutation is the bypass STRAT-GUARD exists to close, so it is
+ * rejected unless it carries a valid out-of-band override token (the agent
+ * cannot mint it). Guard off → legacy behavior (no-op). Internal callers
+ * (recordCompletion → setFeatureStatus directly) never pass through here.
+ *
+ * @param {object} args tool args (may carry force / override_token)
+ * @param {string} toolName for the error message
+ * @param {{guard?: boolean}} [capsOverride] test seam; otherwise read from config
+ */
+/**
+ * COMP-MCP-ENFORCE Slice 3 — close the record_completion bypass. record_completion
+ * is a public MCP tool that flips status to COMPLETE; under capabilities.guard it
+ * must satisfy the SAME evidence as /lifecycle/complete (real commit + attested
+ * tests), else a rogue client could complete a feature without a guard verdict or
+ * evidence. Guard off → legacy behavior (no-op).
+ *
+ * @param {object} args record_completion args (commit_sha, tests_pass)
+ * @param {{guard?: boolean}} [capsOverride] test seam
+ * @param {string} [cwd]
+ */
+export async function assertCompletionEvidence(args, capsOverride, cwd = getTargetRoot()) {
+  let guardOn;
+  if (capsOverride && typeof capsOverride.guard === 'boolean') {
+    guardOn = capsOverride.guard;
+  } else {
+    try { guardOn = loadProjectConfig()?.capabilities?.guard === true; } catch { guardOn = false; }
+  }
+  if (!guardOn) return;
+  const { verifyCompletionEvidence, guardTestCommand } = await import('./lifecycle-guard.js');
+  const ev = await verifyCompletionEvidence({
+    commitSha: args?.commit_sha,
+    cwd,
+    testCommand: guardTestCommand(cwd),
+    testsPassClaim: args?.tests_pass,
+  });
+  if (!ev.ok) {
+    const e = new Error(
+      `record_completion: completion evidence not satisfied under capabilities.guard: ${ev.reasons.join('; ')}`,
+    );
+    e.code = 'COMPLETION_EVIDENCE_REQUIRED';
+    throw e;
+  }
+}
+
+/** Terminal statuses owned by the lifecycle (projected from phase, Slice 2). */
+const LIFECYCLE_OWNED_STATUS = new Set(['COMPLETE', 'KILLED']);
+
+function _guardOn(capsOverride) {
+  if (capsOverride && typeof capsOverride.guard === 'boolean') return capsOverride.guard;
+  try { return loadProjectConfig()?.capabilities?.guard === true; } catch { return false; }
+}
+
+/** True iff a valid, non-agent-mintable override token accompanies the call. */
+function _overrideOk(args) {
+  const expected = process.env.STRATUM_GUARD_OVERRIDE_TOKEN;
+  return !!expected && args?.override_token === expected;
+}
+
+export function assertForceAuthorized(args, toolName, capsOverride) {
+  if (!args?.force) return;
+  if (!_guardOn(capsOverride)) return;
+  if (!_overrideOk(args)) {
+    const e = new Error(
+      `${toolName}: force is disabled under capabilities.guard — supply a valid override_token ` +
+      `(out-of-band STRATUM_GUARD_OVERRIDE_TOKEN; not agent-mintable) to deviate, or drive the ` +
+      `change through the lifecycle.`,
+    );
+    e.code = 'FORCE_REQUIRES_OVERRIDE';
+    throw e;
+  }
+}
+
+/**
+ * COMP-MCP-ENFORCE Slice 3 — terminal statuses (COMPLETE/KILLED) are owned by the
+ * lifecycle (Slice 2: status is a projection of phase). Under capabilities.guard,
+ * a public MCP caller cannot set/mint them directly — that would bypass the
+ * evidence-gated /lifecycle/complete and the guarded /lifecycle/kill. The single
+ * authorized escape is an out-of-band override token. Guard off → legacy.
+ *
+ * @param {object} args carries `status` (set_feature_status / add_roadmap_entry)
+ * @param {string} toolName
+ * @param {{guard?: boolean}} [capsOverride] test seam
+ */
+export function assertTerminalStatusAuthorized(args, toolName, capsOverride) {
+  const status = args?.status;
+  if (!status || !LIFECYCLE_OWNED_STATUS.has(status)) return;
+  if (!_guardOn(capsOverride)) return;
+  if (!_overrideOk(args)) {
+    const e = new Error(
+      `${toolName}: status ${status} is lifecycle-owned under capabilities.guard — drive it through ` +
+      `/lifecycle (evidence-gated for complete, guarded for kill) instead of setting it directly, ` +
+      `or supply a valid override_token.`,
+    );
+    e.code = 'STATUS_OWNED_BY_LIFECYCLE';
+    throw e;
+  }
+}
 import { resolveWorkspace } from '../lib/resolve-workspace.js';
 import { discoverWorkspaces } from '../lib/discover-workspaces.js';
 
@@ -195,11 +296,15 @@ export async function toolGetCurrentSession({ featureCode } = {}) {
 // ---------------------------------------------------------------------------
 
 export async function toolAddRoadmapEntry(args) {
+  assertForceAuthorized(args, 'add_roadmap_entry');
+  assertTerminalStatusAuthorized(args, 'add_roadmap_entry');
   const { addRoadmapEntry } = await import('../lib/feature-writer.js');
   return addRoadmapEntry(getTargetRoot(), args);
 }
 
 export async function toolSetFeatureStatus(args) {
+  assertForceAuthorized(args, 'set_feature_status');
+  assertTerminalStatusAuthorized(args, 'set_feature_status');
   const { setFeatureStatus } = await import('../lib/feature-writer.js');
   return setFeatureStatus(getTargetRoot(), args);
 }
@@ -234,6 +339,9 @@ export async function toolGetFeatureLinks(args) {
 // ---------------------------------------------------------------------------
 
 export async function toolProposeFollowup(args) {
+  // propose_followup also accepts a caller-supplied `status` and routes to
+  // addRoadmapEntry — gate lifecycle-owned terminal statuses the same way.
+  assertTerminalStatusAuthorized(args, 'propose_followup');
   const { proposeFollowup } = await import('../lib/followup-writer.js');
   return proposeFollowup(getTargetRoot(), args);
 }
@@ -301,6 +409,7 @@ export async function toolGetJournalEntries(args) {
 // ---------------------------------------------------------------------------
 
 export async function toolRecordCompletion(args) {
+  await assertCompletionEvidence(args);
   const { recordCompletion } = await import('../lib/completion-writer.js');
   return recordCompletion(getTargetRoot(), args);
 }

package/server/lifecycle-guard.js

@@ -0,0 +1,337 @@
+// server/lifecycle-guard.js
+//
+// COMP-MCP-ENFORCE Slice 1 — compose-owned STRAT-GUARD policy.
+//
+// Compose owns the phase semantics (the graph + which evidence each edge
+// requires); stratum's STRAT-GUARD primitive enforces them. This module:
+//   - declares the canonical lifecycle phase graph as DATA (single source of
+//     truth, imported by vision-routes.js for its own legality check),
+//   - binds per-edge evidence predicates to server-read artifacts,
+//   - lazily + idempotently registers each feature as a guarded resource,
+//   - drives guarded transitions, fail-closed.
+//
+// See docs/features/COMP-MCP-ENFORCE/{design,blueprint,plan}.md.
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import {
+  guardRegister as _guardRegister,
+  guardTransition as _guardTransition,
+} from './stratum-client.js';
+import { setFeatureStatus as _setFeatureStatus } from '../lib/feature-writer.js';
+
+// ---------------------------------------------------------------------------
+// Canonical phase graph (compose-owned data — single source of truth)
+// ---------------------------------------------------------------------------
+
+/** Forward transitions between non-terminal lifecycle phases. */
+export const BASE_TRANSITIONS = {
+  explore_design: ['prd', 'architecture', 'blueprint'],
+  prd: ['architecture', 'blueprint'],
+  architecture: ['blueprint'],
+  blueprint: ['verification'],
+  verification: ['plan', 'blueprint'],
+  plan: ['execute'],
+  execute: ['report', 'docs'],
+  report: ['docs'],
+  docs: ['ship'],
+  ship: [],
+};
+
+/** Phases whose forward edge may be skipped (not killed). */
+export const SKIPPABLE = new Set(['prd', 'architecture', 'report']);
+
+/** Terminal phases — no outgoing edges. */
+export const TERMINAL = new Set(['complete', 'killed']);
+
+/**
+ * Assemble the FULL guarded graph the design requires: the forward
+ * `BASE_TRANSITIONS` PLUS the `ship → complete` edge and a `<any non-terminal>
+ * → killed` edge from every reachable non-terminal phase. The guard graph must
+ * be a superset of every edge vision-routes will legally request, or the guard
+ * would reject a transition the app considers valid.
+ */
+export function buildPhaseGraph(transitions = BASE_TRANSITIONS) {
+  const graph = {};
+  const nodes = new Set();
+  for (const [from, tos] of Object.entries(transitions)) {
+    graph[from] = [...tos];
+    nodes.add(from);
+    for (const t of tos) nodes.add(t);
+  }
+  // ship → complete (the highest-consequence edge; implemented separately in
+  // vision-routes at /lifecycle/complete, so absent from BASE_TRANSITIONS).
+  graph.ship = [...(graph.ship || []), 'complete'];
+  // Every non-terminal phase → killed (vision-routes /lifecycle/kill allows
+  // kill from any non-terminal phase, including ship).
+  for (const s of nodes) {
+    if (TERMINAL.has(s)) continue;
+    graph[s] = graph[s] || [];
+    if (!graph[s].includes('killed')) graph[s].push('killed');
+  }
+  graph.complete = [];
+  graph.killed = [];
+  return graph;
+}
+
+/**
+ * Per-edge `deterministic` (trusted, server-read) evidence predicates. Paths are
+ * RELATIVE to the guard's workspace_root and derived from the configured feature
+ * directory (never hardcoded `docs/features`). Edges not listed here carry no
+ * predicate — they still get graph-legality + per-resource serialization +
+ * tamper-evident ledgering. Evidence-bound `ship → complete` is Slice 3.
+ *
+ * @param {string} featureRelDir e.g. "docs/features/FEAT-1"
+ */
+export function edgePredicates(featureRelDir) {
+  const det = (id, file) => ({
+    id,
+    type: 'deterministic',
+    statement: `server_file_exists('${featureRelDir}/${file}')`,
+  });
+  return {
+    'explore_design->blueprint': [det('design_md', 'design.md')],
+    'blueprint->verification': [det('blueprint_md', 'blueprint.md')],
+    'plan->execute': [det('plan_md', 'plan.md')],
+  };
+}
+
+/**
+ * Project-scoped, opaque resource id. STRAT-GUARD state is stored globally keyed
+ * only by resource_id and workspace_root is NOT part of the checksum, so a bare
+ * `compose:<FC>` would let two compose projects sharing a feature code collide on
+ * one ledger/current-state. The project-path hash prevents that.
+ */
+export function resourceId(featureCode, workspaceRoot) {
+  const hash = createHash('sha256').update(path.resolve(workspaceRoot)).digest('hex').slice(0, 12);
+  return `compose:${hash}:${featureCode}`;
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle-as-truth: roadmap STATUS is a projection of lifecycle phase (Slice 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Project a lifecycle phase onto the roadmap STATUS enum. The lifecycle is the
+ * source of truth; STATUS is derived. `complete`/`killed` are terminal; every
+ * active phase (explore_design…ship) is IN_PROGRESS. PLANNED is the PRE-lifecycle
+ * state (no projection needed); BLOCKED/PARKED/PARTIAL/SUPERSEDED have no phase
+ * and stay set_feature_status's domain.
+ */
+export function phaseToStatus(phase) {
+  if (phase === 'complete') return 'COMPLETE';
+  if (phase === 'killed') return 'KILLED';
+  return 'IN_PROGRESS';
+}
+
+let _statusWriter = _setFeatureStatus;
+/** @internal test seam */
+export function _testOnly_setStatusWriter(fn) { _statusWriter = fn; }
+/** @internal test seam */
+export function _testOnly_resetStatusWriter() { _statusWriter = _setFeatureStatus; }
+
+/**
+ * Write the phase-projected STATUS through to feature.json (closes the
+ * COMP-PARITY-7 one-way-sync gap for the lifecycle-driven path). Best-effort:
+ * a missing feature or a writer error is captured and returned, never thrown —
+ * status projection must not roll back a lifecycle transition that already
+ * applied. setFeatureStatus is itself idempotent (from===to → noop), so calling
+ * it on every transition only writes on a real status change.
+ */
+export async function projectFeatureStatus({ featureCode, phase, cwd, commitSha }) {
+  if (!featureCode) return { skipped: true };
+  const status = phaseToStatus(phase);
+  try {
+    // derived:true — the lifecycle is authoritative, so the roadmap transition
+    // table does not gate this projection (e.g. PARKED→IN_PROGRESS on resume).
+    const args = { code: featureCode, status, reason: `lifecycle:${phase}`, derived: true };
+    if (commitSha) args.commit_sha = commitSha;
+    const result = await _statusWriter(cwd, args);
+    return { status, result };
+  } catch (e) {
+    return { status, error: e.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Evidence-bound completion (Slice 3)
+// ---------------------------------------------------------------------------
+
+/** True if `sha` resolves to a real commit object in the repo at `cwd`. */
+function gitCommitExists(sha, cwd) {
+  const r = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${sha}^{commit}`],
+    { cwd, encoding: 'utf8' });
+  return r.status === 0;
+}
+
+/**
+ * Verify the evidence required to complete a feature under the guard — the
+ * substrate confirms it, not a caller boolean (the design's "trusted evidence"
+ * principle, evaluated compose-side because compose owns the repo + test runner):
+ *   - `commit_sha` must exist as a real git commit (server-read, not syntax).
+ *   - tests must be ATTESTED: a configured `testCommand` exits 0 (real exit code),
+ *     OR `testsPassClaim` is explicitly true. There is NO silent default-to-true.
+ *
+ * @returns {Promise<{ok:boolean, reasons:string[], testsAttested:boolean}>}
+ */
+export async function verifyCompletionEvidence({ commitSha, cwd, testCommand, testsPassClaim }) {
+  const reasons = [];
+
+  if (!commitSha || typeof commitSha !== 'string' || !commitSha.trim()) {
+    reasons.push('commit_sha is required for evidence-bound completion');
+  } else if (!gitCommitExists(commitSha.trim(), cwd)) {
+    reasons.push(`commit ${commitSha.trim()} not found in repository (server-read git verification)`);
+  }
+
+  let testsAttested = false;
+  if (Array.isArray(testCommand) && testCommand.length > 0) {
+    const [bin, ...rest] = testCommand;
+    const r = spawnSync(bin, rest, { cwd, encoding: 'utf8' });
+    if (r.error) {
+      reasons.push(`test command failed to run: ${r.error.message}`);
+    } else if (r.status !== 0) {
+      reasons.push(`test command exited ${r.status} (not 0)`);
+    } else {
+      testsAttested = true;
+    }
+  } else if (testsPassClaim !== true) {
+    reasons.push('tests_pass must be explicitly true (no configured test command to attest test results)');
+  }
+
+  return { ok: reasons.length === 0, reasons, testsAttested };
+}
+
+// ---------------------------------------------------------------------------
+// Guard client (injectable for tests)
+// ---------------------------------------------------------------------------
+
+let _client = { register: _guardRegister, transition: _guardTransition };
+/** @internal test seam */
+export function _testOnly_setGuardClient(c) { _client = c; }
+
+// Per-process registration cache — register is idempotent server-side, but the
+// cache avoids a subprocess per request once a resource is known-registered.
+const _registered = new Set();
+/** @internal test seam */
+export function _testOnly_resetGuardCache() { _registered.clear(); }
+
+/**
+ * Resolve the feature directory RELATIVE to the served `workspaceRoot` — read
+ * from `<workspaceRoot>/.compose/compose.json` (NOT the process-global config,
+ * which is pinned to getTargetRoot() and would drift for a non-current project
+ * root). The relative dir is baked into the immutable guard registration, so it
+ * must reflect the tree the routes actually serve.
+ */
+function _featureRelDir(featureCode, workspaceRoot) {
+  let featuresRel = 'docs/features';
+  try {
+    const cfg = JSON.parse(readFileSync(path.join(workspaceRoot, '.compose', 'compose.json'), 'utf-8'));
+    featuresRel = cfg?.paths?.features || 'docs/features';
+  } catch { /* missing/invalid config → default */ }
+  return `${featuresRel}/${featureCode}`;
+}
+
+/**
+ * The configured evidence-bound-completion test command (array form, e.g.
+ * ["npm","test"]) from `<workspaceRoot>/.compose/compose.json` `guard.testCommand`,
+ * or null when unconfigured. When null, evidence-bound completion falls back to
+ * requiring an explicit tests_pass=true (still no silent default).
+ */
+export function guardTestCommand(workspaceRoot) {
+  try {
+    const cfg = JSON.parse(readFileSync(path.join(workspaceRoot, '.compose', 'compose.json'), 'utf-8'));
+    const cmd = cfg?.guard?.testCommand;
+    return Array.isArray(cmd) && cmd.length > 0 ? cmd : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Idempotently register the feature as a guarded resource, seeding `initial`
+ * from the item's CURRENT phase (so items already mid-lifecycle at rollout don't
+ * trip stale_from_state). Only the first registration ever seeds current_state;
+ * later calls (different `initial`) are no-ops because `initial` is not part of
+ * the policy checksum.
+ *
+ * @returns the register result, or {error} on guard failure.
+ */
+export async function ensureGuard(featureCode, currentPhase, workspaceRoot) {
+  const rid = resourceId(featureCode, workspaceRoot);
+  if (_registered.has(rid)) return { guard_id: rid, status: 'cached' };
+
+  let res;
+  try {
+    res = await _client.register({
+      resourceId: rid,
+      graph: buildPhaseGraph(),
+      edgePredicates: edgePredicates(_featureRelDir(featureCode, workspaceRoot)),
+      initial: currentPhase,
+      terminal: ['complete', 'killed'],
+      stakes: {},
+      workspaceRoot,
+    });
+  } catch (e) {
+    // A thrown spawn failure (e.g. stratum-mcp not installed) must NOT escape as
+    // a generic 500/400 — normalise to a fail-closed error result.
+    return { error: { code: 'GUARD_UNREACHABLE', message: e.message } };
+  }
+  if (res && (res.status === 'registered' || res.status === 'exists')) {
+    _registered.add(rid);
+  }
+  return res;
+}
+
+/**
+ * Attempt a guarded lifecycle transition. Registers (idempotently) then
+ * transitions. FAIL-CLOSED: any guard error (unreachable, illegal edge, error
+ * dict) yields `{applied:false, error}` — the caller must NOT mutate state.
+ *
+ * @returns {Promise<{applied:boolean, refused?:boolean, verdict?:object,
+ *   ledgerRef?:string, currentState?:string, error?:object}>}
+ */
+export async function guardedTransition({ featureCode, from, to, workspaceRoot, commitSha, resolvedBy = 'agent' }) {
+  const reg = await ensureGuard(featureCode, from, workspaceRoot);
+  if (reg && (reg.error || reg.status === 'error')) {
+    return { applied: false, error: reg.error || reg };
+  }
+
+  const rid = resourceId(featureCode, workspaceRoot);
+  const artifacts = commitSha ? { commit_sha: commitSha } : {};
+  // No idempotency_key: a refuse→fix→retry is a NEW logical attempt that must
+  // re-evaluate evidence, but it carries an identical (from,to,artifacts)
+  // payload — an idempotency_key would make the guard replay the prior refusal.
+  // Double-apply is already prevented server-side: once applied, current_state
+  // advances and a duplicate call fails the from_state == current_state check.
+  let res;
+  try {
+    res = await _client.transition({
+      resourceId: rid,
+      fromState: from,
+      toState: to,
+      artifacts,
+      resolvedBy,
+    });
+  } catch (e) {
+    // Fail-closed on a thrown spawn failure (see ensureGuard).
+    return { applied: false, error: { code: 'GUARD_UNREACHABLE', message: e.message } };
+  }
+
+  if (!res || res.error || res.status === 'error') {
+    return { applied: false, error: (res && (res.error || res)) || { code: 'UNKNOWN', message: 'no guard response' } };
+  }
+  if (res.status === 'applied') {
+    return { applied: true, verdict: res.verdict, ledgerRef: res.ledger_ref, currentState: res.current_state };
+  }
+  // refused | replayed
+  return {
+    applied: res.status === 'replayed' ? true : false,
+    refused: res.status === 'refused',
+    verdict: res.verdict,
+    ledgerRef: res.ledger_ref,
+    currentState: res.current_state,
+  };
+}

package/server/stratum-client.js

@@ -127,6 +127,78 @@ async function runMutation(args) {
   }
 }
 
+/**
+ * Spawn stratum-mcp with args and pipe `inputJson` (a string) on stdin.
+ * Used by the STRAT-GUARD adapter, whose CLI reads one JSON kwargs object from
+ * stdin. Same resolve contract as spawnStratum.
+ *
+ * @param {string[]} args
+ * @param {string}   inputJson
+ * @param {number}   timeoutMs
+ * @returns {Promise<{ stdout: string, stderr: string, code: number }>}
+ */
+function spawnStratumStdin(args, inputJson, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const proc = _execFile(STRATUM_BIN, args, { timeout: timeoutMs }, (err, out, err2) => {
+      const code = err?.code === 'ETIMEDOUT' ? -1
+        : (typeof err?.code === 'number' ? err.code : 0);
+      resolve({ stdout: out || '', stderr: err2 || '', code });
+    });
+
+    proc.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        reject(new Error(`stratum-mcp not found. Install with: pip install stratum-mcp`));
+      } else {
+        reject(err);
+      }
+    });
+
+    // Feed the JSON kwargs on stdin. The test mock supplies a fake stdin; a
+    // real child always has one. Guard so neither path throws.
+    if (proc.stdin) {
+      try {
+        proc.stdin.write(inputJson);
+        proc.stdin.end();
+      } catch { /* child already exited / stdin closed — execFile cb still fires */ }
+    }
+  });
+}
+
+/**
+ * Run a guard mutation: pipe `kwargs` as JSON on stdin, no retry (mutations are
+ * not safe to blindly retry). Maps exit codes like runMutation. A guard refusal
+ * is a NORMAL exit-0 result ({status:"refused"}), not an error.
+ *
+ * @returns {Promise<any>} parsed JSON result or { error }
+ */
+async function runGuard(action, kwargs, timeoutMs = MUTATION_TIMEOUT_MS) {
+  const result = await spawnStratumStdin(['guard', action], JSON.stringify(kwargs), timeoutMs);
+
+  if (result.code === -1) {
+    return { error: { code: 'TIMEOUT', message: 'stratum-mcp guard timed out', detail: '' } };
+  }
+  if (result.code !== 0) {
+    console.error('[stratum-client] guard error stderr:', result.stderr);
+    try {
+      return JSON.parse(result.stdout);   // canonical { status:"error", ... }
+    } catch {
+      return { error: { code: 'UNKNOWN', message: 'stratum-mcp guard failed', detail: '' } };
+    }
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return { error: { code: 'PARSE_ERROR', message: 'stratum-mcp returned invalid JSON', detail: '' } };
+  }
+}
+
+/** Strip undefined values so the JSON kwargs object stays minimal. */
+function _compact(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) if (v !== undefined) out[k] = v;
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -190,3 +262,71 @@ export async function gateRevise(flowId, stepId, note = '', resolvedBy = 'human'
   if (resolvedBy !== 'human') args.push('--resolved-by', resolvedBy);
   return runMutation(args);
 }
+
+// ---------------------------------------------------------------------------
+// STRAT-GUARD adapter (COMP-MCP-ENFORCE Slice 1)
+//
+// Reaches stratum's guarded-transition primitive over the same CLI-subprocess
+// seam. Each function translates camelCase params into the snake_case JSON
+// kwargs the `stratum-mcp guard <action>` CLI forwards verbatim to the guard
+// library, and pipes them on stdin.
+// ---------------------------------------------------------------------------
+
+/**
+ * Register (idempotently) a guarded resource. Re-registering an identical policy
+ * is a no-op ({status:"exists"}); a different policy is rejected (use migrate).
+ * @returns {Promise<{guard_id:string,checksum:string,status:string}|ErrorResult>}
+ */
+export async function guardRegister({ resourceId, graph, edgePredicates, initial, terminal, stakes, workspaceRoot }) {
+  return runGuard('register', _compact({
+    resource_id: resourceId,
+    graph,
+    edge_predicates: edgePredicates,
+    initial,
+    terminal,
+    stakes,
+    workspace_root: workspaceRoot,
+  }));
+}
+
+/**
+ * Attempt a guarded transition. Applies only if the edge is legal and its
+ * predicates verify server-side. A refusal is a normal result (status:"refused").
+ * @returns {Promise<{status:string,verdict:object,ledger_ref:string,current_state:string}|ErrorResult>}
+ */
+export async function guardTransition({ resourceId, fromState, toState, artifacts, modifiedFiles, idempotencyKey, resolvedBy }) {
+  return runGuard('transition', _compact({
+    resource_id: resourceId,
+    from_state: fromState,
+    to_state: toState,
+    artifacts,
+    modified_files: modifiedFiles,
+    idempotency_key: idempotencyKey,
+    resolved_by: resolvedBy,
+  }));
+}
+
+/**
+ * The single sanctioned bypass of predicate verification. Requires an
+ * out-of-band override token (server env STRATUM_GUARD_OVERRIDE_TOKEN), a human
+ * resolver, and a rationale. Records a 'deviation' ledger entry.
+ * @returns {Promise<{status:string,ledger_ref:string,current_state:string}|ErrorResult>}
+ */
+export async function guardOverride({ resourceId, fromState, toState, overrideToken, rationale, resolvedBy = 'human' }) {
+  return runGuard('override', _compact({
+    resource_id: resourceId,
+    from_state: fromState,
+    to_state: toState,
+    override_token: overrideToken,
+    rationale,
+    resolved_by: resolvedBy,
+  }));
+}
+
+/**
+ * Read a resource's current state + append-only, hash-chained transition ledger.
+ * @returns {Promise<{resource_id:string,current_state:string,ledger:object[]}|ErrorResult>}
+ */
+export async function guardHistory(resourceId) {
+  return runGuard('history', { resource_id: resourceId }, QUERY_TIMEOUT_MS);
+}

package/server/vision-routes.js

@@ -51,6 +51,12 @@ import { getTargetRoot, resolveProjectPath, loadProjectConfig } from './project-
 import { anchorBoundary } from '../lib/checkpoint/checkpoint-writer.js';
 import { appendGateLogEntry, readGateLog, mapResolveOutcomeToSchema } from './gate-log-store.js';
 import { addOpenLoop, resolveOpenLoop, listOpenLoops } from './open-loops-store.js';
+import {
+  BASE_TRANSITIONS, SKIPPABLE, TERMINAL,
+  guardedTransition, ensureGuard, projectFeatureStatus,
+  verifyCompletionEvidence, guardTestCommand,
+} from './lifecycle-guard.js';
+import { requireSensitiveToken } from './security.js';
 
 const PROJECT_ROOT = getTargetRoot();
 
@@ -58,9 +64,25 @@ const PROJECT_ROOT = getTargetRoot();
  * Attach vision CRUD and plan/parse REST routes to an Express app.
  *
  * @param {object} app — Express app
- * @param {{ store: object, scheduleBroadcast: function, broadcastMessage: function, projectRoot: string }} deps
+ * @param {{ store: object, scheduleBroadcast: function, broadcastMessage: function, projectRoot: string, settingsStore?: object, capabilities?: object }} deps
  */
-export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMessage, projectRoot = PROJECT_ROOT, settingsStore }) {
+export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMessage, projectRoot = PROJECT_ROOT, settingsStore, capabilities }) {
+  // COMP-MCP-ENFORCE: when enabled, lifecycle transitions are verdict-gated by
+  // stratum's STRAT-GUARD (fail-closed). Default OFF — legacy behavior intact.
+  const guardEnabled = capabilities?.guard === true;
+
+  // COMP-MCP-ENFORCE Slice 4: opt-in loopback REST auth on vision MUTATION
+  // endpoints (lifecycle transitions, iterations, gate resolve, item CRUD,
+  // branch-lineage). Default OFF (the cockpit does not yet send the token, so
+  // forcing it would break the UI) — defense-in-depth for headless/CI surfaces.
+  // Reads stay open. Fail-closed: when guardAuth is on, mutations require
+  // x-compose-token; if COMPOSE_API_TOKEN is NOT configured, requireSensitiveToken
+  // returns 503 (mutations disabled) rather than silently allowing them — enabling
+  // auth without a token is a misconfiguration, not an open door. Pass-through
+  // when off, so route wiring is unconditional.
+  const guardAuthEnabled = capabilities?.guardAuth === true;
+  const guardAuth = (req, res, next) =>
+    guardAuthEnabled ? requireSensitiveToken(req, res, next) : next();
   // GET /api/vision/items — full state (optional ?group= filter)
   app.get('/api/vision/items', (req, res) => {
     let state = store.getState();
@@ -71,7 +93,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   });
 
   // POST /api/vision/items — create item
-  app.post('/api/vision/items', (req, res) => {
+  app.post('/api/vision/items', guardAuth, (req, res) => {
     try {
       const item = store.createItem(req.body);
       scheduleBroadcast();
@@ -82,7 +104,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   });
 
   // PATCH /api/vision/items/:id — update item
-  app.patch('/api/vision/items/:id', (req, res) => {
+  app.patch('/api/vision/items/:id', guardAuth, (req, res) => {
     try {
       const item = store.updateItem(req.params.id, req.body);
       // If group changed, write back to docs/features/<code>/feature.json
@@ -103,7 +125,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   });
 
   // DELETE /api/vision/items/:id — delete item + connections
-  app.delete('/api/vision/items/:id', (req, res) => {
+  app.delete('/api/vision/items/:id', guardAuth, (req, res) => {
     try {
       store.deleteItem(req.params.id);
       scheduleBroadcast();
@@ -153,21 +175,10 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     ? path.join(projectRoot, loadProjectConfig().paths?.features || 'docs/features')
     : resolveProjectPath('features');
 
-  const TRANSITIONS = {
-    explore_design: ['prd', 'architecture', 'blueprint'],
-    prd: ['architecture', 'blueprint'],
-    architecture: ['blueprint'],
-    blueprint: ['verification'],
-    verification: ['plan', 'blueprint'],
-    plan: ['execute'],
-    execute: ['report', 'docs'],
-    report: ['docs'],
-    docs: ['ship'],
-    ship: [],
-  };
-  const SKIPPABLE = new Set(['prd', 'architecture', 'report']);
+  // Phase graph + SKIPPABLE + TERMINAL are owned by lifecycle-guard.js (single
+  // source of truth shared with the STRAT-GUARD graph) — see COMP-MCP-ENFORCE.
+  const TRANSITIONS = BASE_TRANSITIONS;
   const ITERATION_TYPES = new Set(['review', 'coverage']);
-  const TERMINAL = new Set(['complete', 'killed']);
 
   app.get('/api/vision/items/:id/lifecycle', (req, res) => {
     try {
@@ -193,7 +204,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/start', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/start', guardAuth, async (req, res) => {
     try {
       const { featureCode } = req.body;
       if (!featureCode) return res.status(400).json({ error: 'featureCode is required' });
@@ -213,6 +224,17 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // COMP-OBS-TIMELINE: populate phaseHistory before storing
       appendPhaseHistory({ lifecycle }, { from: null, to: 'explore_design', outcome: null, timestamp: now });
       store.updateLifecycle(req.params.id, lifecycle);
+      // COMP-MCP-ENFORCE: eager guard registration seeded at the genesis phase
+      // (the clean bootstrap path; backfill for pre-rollout items happens lazily
+      // on first transition). Best-effort — a registration hiccup must not block
+      // starting a lifecycle; the next guarded transition re-attempts ensureGuard.
+      if (guardEnabled) {
+        try { await ensureGuard(featureCode, 'explore_design', projectRoot); }
+        catch (e) { console.warn(`[lifecycle/start] guard register for ${featureCode} failed: ${e.message}`); }
+        // Slice 2: starting a lifecycle projects explore_design → IN_PROGRESS so
+        // the first active phase is not left stuck at PLANNED in feature.json.
+        await projectFeatureStatus({ featureCode, phase: 'explore_design', cwd: projectRoot });
+      }
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleStarted', itemId: req.params.id, phase: 'explore_design', featureCode, timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode, from: null, to: 'explore_design', outcome: null, timestamp: now }));
@@ -229,7 +251,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   });
 
   // COMP-OBS-BRANCH: accept BranchLineage payloads from the CC-session watcher.
-  app.post('/api/vision/items/:id/lifecycle/branch-lineage', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/branch-lineage', guardAuth, (req, res) => {
     try {
       const item = store.items.get(req.params.id);
       if (!item) return res.status(404).json({ error: `Item not found: ${req.params.id}` });
@@ -260,7 +282,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/advance', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/advance', guardAuth, async (req, res) => {
     try {
       const { targetPhase, outcome } = req.body;
       const item = store.items.get(req.params.id);
@@ -270,11 +292,20 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       const valid = TRANSITIONS[from];
       if (!valid?.includes(targetPhase)) return res.status(400).json({ error: `Invalid transition: ${from} → ${targetPhase}` });
 
+      // COMP-MCP-ENFORCE: verdict-gate the transition (fail-closed) before mutating.
+      if (guardEnabled) {
+        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent' });
+        if (!g.applied) return res.status(422).json({ error: 'transition refused by guard', from, to: targetPhase, verdict: g.verdict, guardError: g.error });
+      }
+
       item.lifecycle.currentPhase = targetPhase;
       // COMP-OBS-TIMELINE: populate phaseHistory + emit phase_transition DecisionEvent
       const now = new Date().toISOString();
       appendPhaseHistory(item, { from, to: targetPhase, outcome: outcome ?? null, timestamp: now });
       store.updateLifecycle(req.params.id, item.lifecycle);
+      // COMP-MCP-ENFORCE Slice 2 (lifecycle-as-truth): project the new phase onto
+      // feature.json STATUS (best-effort; idempotent — only writes on a real change).
+      if (guardEnabled) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: targetPhase, outcome, timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, outcome, timestamp: now }));
@@ -291,7 +322,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/skip', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/skip', guardAuth, async (req, res) => {
     try {
       const { targetPhase, reason } = req.body;
       const item = store.items.get(req.params.id);
@@ -302,11 +333,19 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       const valid = TRANSITIONS[from];
       if (!valid?.includes(targetPhase)) return res.status(400).json({ error: `Invalid transition: ${from} → ${targetPhase}` });
 
+      // COMP-MCP-ENFORCE: verdict-gate the skip (fail-closed) before mutating.
+      if (guardEnabled) {
+        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent' });
+        if (!g.applied) return res.status(422).json({ error: 'transition refused by guard', from, to: targetPhase, verdict: g.verdict, guardError: g.error });
+      }
+
       item.lifecycle.currentPhase = targetPhase;
       // COMP-OBS-TIMELINE: populate phaseHistory + emit phase_transition DecisionEvent
       const now = new Date().toISOString();
       appendPhaseHistory(item, { from, to: targetPhase, outcome: 'skipped', timestamp: now });
       store.updateLifecycle(req.params.id, item.lifecycle);
+      // COMP-MCP-ENFORCE Slice 2 (lifecycle-as-truth): project phase → STATUS.
+      if (guardEnabled) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: targetPhase, outcome: 'skipped', timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, outcome: 'skipped', timestamp: now }));
@@ -323,7 +362,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/kill', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/kill', guardAuth, async (req, res) => {
     try {
       const { reason } = req.body;
       const item = store.items.get(req.params.id);
@@ -331,6 +370,15 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       const from = item.lifecycle.currentPhase;
       if (TERMINAL.has(from)) return res.status(400).json({ error: `Cannot kill from terminal state: ${from}` });
 
+      // COMP-MCP-ENFORCE: record the kill in the tamper-evident ledger (fail-closed).
+      // The `<from>→killed` edge has no predicate, so it only fails if the guard
+      // is unreachable — consistent with advance/skip/complete. Authorized
+      // bypass remains stratum_guard_override (Slice 3).
+      if (guardEnabled) {
+        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: 'killed', workspaceRoot: projectRoot, resolvedBy: 'agent' });
+        if (!g.applied) return res.status(422).json({ error: 'kill refused by guard', from, to: 'killed', verdict: g.verdict, guardError: g.error });
+      }
+
       const now = new Date().toISOString();
       item.lifecycle.currentPhase = 'killed';
       item.lifecycle.killedAt = now;
@@ -339,6 +387,9 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       appendPhaseHistory(item, { from, to: 'killed', outcome: 'killed', timestamp: now });
       store.updateLifecycle(req.params.id, item.lifecycle);
       store.updateItem(req.params.id, { status: 'killed' });
+      // COMP-MCP-ENFORCE Slice 2: project kill → KILLED onto feature.json
+      // (closes the COMP-PARITY-7 gap — kill previously wrote vision-state only).
+      if (guardEnabled) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: 'killed', cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: 'killed', outcome: 'killed', timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: 'killed', outcome: 'killed', timestamp: now }));
@@ -355,7 +406,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/complete', async (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/complete', guardAuth, async (req, res) => {
     try {
       const item = store.items.get(req.params.id);
       if (!item?.lifecycle) return res.status(404).json({ error: 'No lifecycle on this item' });
@@ -363,6 +414,28 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
         return res.status(400).json({ error: `Can only complete from ship phase, currently in: ${item.lifecycle.currentPhase}` });
       }
 
+      // COMP-MCP-ENFORCE Slice 3: evidence-bound completion. Under the guard,
+      // ship→complete requires REAL evidence — the commit must exist (server-read
+      // git) and tests must be attested (configured test command exits 0, or
+      // tests_pass is explicitly true; never a silent default). Then the guard
+      // verdict gates the transition (fail-closed).
+      let verifiedTestsPass = req.body?.tests_pass;
+      if (guardEnabled) {
+        const ev = await verifyCompletionEvidence({
+          commitSha: req.body?.commit_sha,
+          cwd: projectRoot,
+          testCommand: guardTestCommand(projectRoot),
+          testsPassClaim: req.body?.tests_pass,
+        });
+        if (!ev.ok) {
+          return res.status(422).json({ error: 'completion evidence not satisfied', reasons: ev.reasons });
+        }
+        verifiedTestsPass = ev.testsAttested ? true : (req.body?.tests_pass === true);
+
+        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from: 'ship', to: 'complete', workspaceRoot: projectRoot, commitSha: req.body?.commit_sha, resolvedBy: 'agent' });
+        if (!g.applied) return res.status(422).json({ error: 'completion refused by guard', from: 'ship', to: 'complete', verdict: g.verdict, guardError: g.error });
+      }
+
       const now = new Date().toISOString();
       item.lifecycle.currentPhase = 'complete';
       item.lifecycle.completedAt = now;
@@ -370,6 +443,10 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       appendPhaseHistory(item, { from: 'ship', to: 'complete', outcome: 'approved', timestamp: now });
       store.updateLifecycle(req.params.id, item.lifecycle);
       store.updateItem(req.params.id, { status: 'complete' });
+      // COMP-MCP-ENFORCE Slice 2: status projection for the no-commit path is
+      // applied BELOW (in the `else` branch) so it does not pre-empt and mask the
+      // recordCompletion bridge, which is the authority + partial-write reporter
+      // on the commit_sha path.
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from: 'ship', to: 'complete', outcome: 'approved', timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from: 'ship', to: 'complete', outcome: 'approved', timestamp: now }));
@@ -393,7 +470,9 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
             await recordCompletion(projectRoot, {
               feature_code: featureCode,
               commit_sha,
-              tests_pass: tests_pass ?? true,
+              // Slice 3: under the guard, tests_pass reflects verified evidence
+              // (attested or explicit), NOT a silent default-to-true.
+              tests_pass: guardEnabled ? (verifiedTestsPass === true) : (tests_pass ?? true),
               files_changed: files_changed ?? [],
               notes: notes ?? `cockpit lifecycle: ${featureCode} complete`,
             });
@@ -425,6 +504,9 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
               reason: 'no_commit_sha',
             });
           } catch { /* decision event emit best-effort */ }
+          // No recordCompletion bridge ran — project complete → COMPLETE so
+          // lifecycle-as-truth still reaches feature.json (best-effort).
+          if (guardEnabled) await projectFeatureStatus({ featureCode, phase: 'complete', cwd: projectRoot });
         }
       }
 
@@ -437,7 +519,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
 
   // ── Iteration loop endpoints ──────────────────────────────────────────
 
-  app.post('/api/vision/items/:id/lifecycle/iteration/start', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/iteration/start', guardAuth, (req, res) => {
     try {
       const item = store.items.get(req.params.id);
       if (!item?.lifecycle) return res.status(404).json({ error: 'No lifecycle on this item' });
@@ -502,7 +584,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/iteration/report', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/iteration/report', guardAuth, (req, res) => {
     try {
       const item = store.items.get(req.params.id);
       if (!item?.lifecycle?.iterationState) return res.status(404).json({ error: 'No iteration loop active' });
@@ -589,7 +671,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/iteration/abort', (req, res) => {
+  app.post('/api/vision/items/:id/lifecycle/iteration/abort', guardAuth, (req, res) => {
     try {
       const item = store.items.get(req.params.id);
       if (!item?.lifecycle?.iterationState) return res.status(404).json({ error: 'No iteration loop active' });
@@ -765,7 +847,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/gates/:id/resolve', (req, res) => {
+  app.post('/api/vision/gates/:id/resolve', guardAuth, (req, res) => {
     try {
       const { outcome: rawOutcome, comment, resolvedBy } = req.body;
       if (!rawOutcome) return res.status(400).json({ error: 'outcome is required' });

package/server/vision-server.js

@@ -90,6 +90,8 @@ export class VisionServer {
       broadcastMessage: (msg) => this.broadcastMessage(msg),
       projectRoot: getTargetRoot(),
       settingsStore: this.settingsStore,
+      // COMP-MCP-ENFORCE: capabilities.guard gates STRAT-GUARD enforcement (default OFF).
+      capabilities: this._config.capabilities,
     });
 
     // ── Activity + error routes ─────────────────────────────────────────────