@smartmemory/compose 0.2.4-beta → 0.2.6-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.4-beta",
+  "version": "0.2.6-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

@@ -14,12 +14,14 @@
 
 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)
@@ -108,6 +110,100 @@ export function resourceId(featureCode, workspaceRoot) {
   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)
 // ---------------------------------------------------------------------------
@@ -138,6 +234,22 @@ function _featureRelDir(featureCode, workspaceRoot) {
   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

package/server/vision-routes.js

@@ -53,8 +53,10 @@ import { appendGateLogEntry, readGateLog, mapResolveOutcomeToSchema } from './ga
 import { addOpenLoop, resolveOpenLoop, listOpenLoops } from './open-loops-store.js';
 import {
   BASE_TRANSITIONS, SKIPPABLE, TERMINAL,
-  guardedTransition, ensureGuard,
+  guardedTransition, ensureGuard, projectFeatureStatus,
+  verifyCompletionEvidence, guardTestCommand,
 } from './lifecycle-guard.js';
+import { requireSensitiveToken } from './security.js';
 
 const PROJECT_ROOT = getTargetRoot();
 
@@ -68,6 +70,19 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   // 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();
@@ -78,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();
@@ -89,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
@@ -110,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();
@@ -189,7 +204,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/start', async (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' });
@@ -216,6 +231,9 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       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 });
@@ -233,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}` });
@@ -264,7 +282,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/advance', async (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);
@@ -285,6 +303,9 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       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 }));
@@ -301,7 +322,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/skip', async (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);
@@ -323,6 +344,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       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 }));
@@ -339,7 +362,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
-  app.post('/api/vision/items/:id/lifecycle/kill', async (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);
@@ -364,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 }));
@@ -380,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' });
@@ -388,10 +414,24 @@ 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.
+      // 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 });
       }
@@ -403,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 }));
@@ -426,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`,
             });
@@ -458,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 });
         }
       }
 
@@ -470,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' });
@@ -535,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' });
@@ -622,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' });
@@ -798,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' });