@smartmemory/compose 0.2.2-beta → 0.2.4-beta

package/server/lifecycle-guard.js

@@ -0,0 +1,225 @@
+// 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 path from 'node:path';
+
+import {
+  guardRegister as _guardRegister,
+  guardTransition as _guardTransition,
+} from './stratum-client.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}`;
+}
+
+// ---------------------------------------------------------------------------
+// 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}`;
+}
+
+/**
+ * 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/session-routes.js

@@ -9,7 +9,13 @@
  *   GET  /api/session/current
  */
 
+import path from 'node:path';
 import { readSessionsByFeature } from './session-store.js';
+import { getTargetRoot, getDataDir } from './project-root.js';
+import { appendPhaseHistory } from './lifecycle-phase-history.js';
+import { reconcile } from '../lib/checkpoint/reconciler.js';
+import { checkpointConfig } from '../lib/checkpoint/checkpoint-writer.js';
+import { createCheckpointStore } from '../lib/checkpoint/store/index.js';
 
 /**
  * Attach session lifecycle routes to an Express app.
@@ -112,6 +118,65 @@ export function attachSessionRoutes(app, { sessionManager, scheduleBroadcast, br
     }
   });
 
+  // POST /api/session/bind/reconcile — COMP-RESUME: reconcile a build against
+  // ground-truth environment state and return the resume decision. reconcile()
+  // is deterministic and computes lifecycleMutations; THIS ROUTE persists them
+  // (store.updateLifecycle) and broadcasts — the persistence boundary (Codex #2).
+  app.post('/api/session/bind/reconcile', (req, res) => {
+    try {
+      const { featureCode } = req.body || {};
+      if (!featureCode) return res.status(400).json({ error: 'featureCode required' });
+      if (!/^[A-Za-z0-9_-]+$/.test(featureCode)) return res.status(400).json({ error: 'Invalid featureCode' });
+
+      const item = store.getItemByFeatureCode(featureCode);
+      if (!item) return res.status(404).json({ error: `No lifecycle item for feature code: ${featureCode}` });
+
+      const targetRoot = getTargetRoot();
+      const dataDir = getDataDir();
+      const cfg = checkpointConfig(targetRoot);
+      const cpStore = createCheckpointStore(cfg.backend, { dataDir });
+
+      const result = reconcile({
+        featureCode,
+        item,
+        cwd: targetRoot,
+        featureDir: path.join(targetRoot, 'docs', 'features', featureCode),
+        composeDir: path.join(targetRoot, '.compose'),
+        dataDir,
+        store: cpStore,
+        confidenceThreshold: cfg.confidenceThreshold,
+      });
+
+      // Apply the mutations reconcile computed (it does not persist itself).
+      // v1 reconcile only emits 'phaseHistory.append'; other mutation types
+      // (e.g. a future 'currentPhase.set' derived from active-build.json) would
+      // be added here together with the reconciler that emits them.
+      let mutated = false;
+      for (const m of result.lifecycleMutations ?? []) {
+        if (m.type === 'phaseHistory.append' && m.entry) {
+          appendPhaseHistory(item, m.entry);
+          mutated = true;
+        }
+      }
+      if (mutated) {
+        store.updateLifecycle(item.id, item.lifecycle);
+        broadcastMessage({
+          type: 'lifecycleReconciled',
+          itemId: item.id,
+          featureCode,
+          action: result.action,
+          drift: result.drift,
+          timestamp: new Date().toISOString(),
+        });
+        scheduleBroadcast();
+      }
+
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
   // GET /api/session/history — sessions bound to a feature
   app.get('/api/session/history', (req, res) => {
     try {

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

@@ -48,8 +48,13 @@ function getSchemaValidator() {
 
 import { randomUUID } from 'node:crypto';
 import { getTargetRoot, resolveProjectPath, loadProjectConfig } from './project-root.js';
+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,
+} from './lifecycle-guard.js';
 
 const PROJECT_ROOT = getTargetRoot();
 
@@ -57,9 +62,12 @@ 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;
   // GET /api/vision/items — full state (optional ?group= filter)
   app.get('/api/vision/items', (req, res) => {
     let state = store.getState();
@@ -152,21 +160,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 {
@@ -192,7 +189,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', async (req, res) => {
     try {
       const { featureCode } = req.body;
       if (!featureCode) return res.status(400).json({ error: 'featureCode is required' });
@@ -212,6 +209,14 @@ 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}`); }
+      }
       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 }));
@@ -259,7 +264,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', async (req, res) => {
     try {
       const { targetPhase, outcome } = req.body;
       const item = store.items.get(req.params.id);
@@ -269,6 +274,12 @@ 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();
@@ -281,6 +292,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
       // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (advance)
       emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+      // COMP-RESUME: best-effort anchor checkpoint at the phase boundary
+      anchorBoundary(getTargetRoot(), { item, trigger: 'phase-transition' });
       res.json({ from, to: targetPhase, outcome });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -288,7 +301,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', async (req, res) => {
     try {
       const { targetPhase, reason } = req.body;
       const item = store.items.get(req.params.id);
@@ -299,6 +312,12 @@ 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();
@@ -311,6 +330,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
       // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (skip)
       emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+      // COMP-RESUME: best-effort anchor checkpoint at the phase boundary
+      anchorBoundary(getTargetRoot(), { item, trigger: 'phase-transition' });
       res.json({ from, to: targetPhase, outcome: 'skipped', reason });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -318,7 +339,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', async (req, res) => {
     try {
       const { reason } = req.body;
       const item = store.items.get(req.params.id);
@@ -326,6 +347,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;
@@ -341,6 +371,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
       // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (kill)
       emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+      // COMP-RESUME: best-effort anchor checkpoint at the (terminal) phase boundary
+      anchorBoundary(getTargetRoot(), { item, trigger: 'phase-transition' });
       res.json({ phase: from, reason });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -356,6 +388,14 @@ 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: verdict-gate ship→complete (fail-closed). commit_sha is
+      // recorded in the ledger via artifacts; evidence-bound completion (real
+      // git/commit/test attestation) is Slice 3.
+      if (guardEnabled) {
+        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 +410,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
       // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (complete)
       emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+      // COMP-RESUME: best-effort anchor checkpoint at the (terminal) phase boundary
+      anchorBoundary(getTargetRoot(), { item, trigger: 'phase-transition' });
 
       // COMP-MCP-MIGRATION: reconcile cockpit complete with record_completion
       // (commit-bound completion writer). Best-effort: failures emit a decision
@@ -561,6 +603,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
           emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
           // COMP-OBS-STATUS: emit status snapshot after iteration complete
           emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+          // COMP-RESUME: best-effort anchor checkpoint at iteration-complete boundary
+          anchorBoundary(getTargetRoot(), { item, trigger: 'iteration-complete' });
         }
       } else {
         // per-attempt update: NO DecisionEvent (Decision 2 — would flood strip)
@@ -614,6 +658,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
         emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
         // COMP-OBS-STATUS: emit status snapshot after iteration abort
         emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+        // COMP-RESUME: best-effort anchor checkpoint at iteration-complete (abort) boundary
+        anchorBoundary(getTargetRoot(), { item, trigger: 'iteration-complete' });
       }
       res.json({ aborted: true });
     } catch (err) {
@@ -835,6 +881,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
           // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
           emitDriftAxes(broadcastMessage, store, resolvedItem, projectRoot, resolvedAt);
           emitStatusSnapshot(broadcastMessage, store, resolvedItem.lifecycle.featureCode, resolvedAt);
+          // COMP-RESUME: best-effort anchor checkpoint at gate-resolution boundary
+          anchorBoundary(getTargetRoot(), { item: resolvedItem, trigger: 'gate-resolution' });
         }
       }
       res.json({ gateId: req.params.id, gateOutcome: outcome });