@smartmemory/compose 0.3.7 → 0.3.8

package/lib/build.js

@@ -16,8 +16,12 @@ import { createHash, randomUUID } from 'node:crypto';
 
 import { StratumMcpClient, StratumError, resolvePlanSpecValues, resolveStepProfile } from './stratum-mcp-client.js';
 import { resolveStratumMcpConnection } from './stratum-engine.js';
-import { runAndNormalize, AgentTimeoutError, AgentAbortedError, UserInterruptError, AgentError } from './result-normalizer.js';
+import { runAndNormalize, mergeUsage, AgentTimeoutError, AgentAbortedError, UserInterruptError, AgentError } from './result-normalizer.js';
 import { checkCapabilityViolation } from './capability-checker.js';
+import { getCatalog as getPolicyCatalog, getPolicyCheckConfig } from './policy-catalog.js';
+import {
+  resolveBuildUserMode, scanResponse, toViolationStrings, buildRevisionNotice, attachPolicyCount,
+} from './policy-check.js';
 import { preflightCodexWorktreeProbe, codexProbeAbortMessage } from './codex-preflight.js';
 import { buildStepPrompt, buildGateContext, clearAmbientContextCache } from './step-prompt.js';
 import { promptGate } from './gate-prompt.js';
@@ -33,11 +37,12 @@ import { resolveAgentConfig, parseAgentString } from './agent-string.js';
 import { emitSections as emitPlanSections, appendTrailers as appendSectionTrailers, analyzeRollup, writeRollup } from './sections.js';
 import { SECTIONS_DIR } from './constants.js';
 import { rtkPrefix } from './rtk.js';
+import { tsCompatibilityOf, quarantineMessage, INIT_PROVISIONED_SPECS } from './pipeline-compat.js';
 
 import YAML from 'yaml';
 // feature-json direct imports removed — mutations now go through TrackerProvider (T9)
 import { loadFeaturesDir, resolveContextPath, resolveRoadmapPath, resolveFeaturesPath } from './project-paths.js';
-import { getMode } from './lifecycle-modes.js';
+import { getMode, resolveMode } from './lifecycle-modes.js';
 import { vocabularyEnabled, tagVocabularyViolations, VOCABULARY_FILE } from './vocabulary-inject.js';
 import { vocabularyCompliance } from './vocabulary-compliance.js';
 
@@ -54,7 +59,7 @@ import { applyFrontTriage, maybeEscalateLane } from './lane-gate.js';
 import { LENS_DEFINITIONS } from './review-lenses.js';
 import { injectCertInstructions } from './cert-inject.js';
 import { buildReviewPrompt } from './review-prompt.js';
-import { detectTestFramework, scaffoldTestFramework, parseTestSummary, deriveTestsPass, isTestFile } from './test-bootstrap.js';
+import { detectTestFramework, scaffoldTestFramework, parseTestSummary, deriveTestsPass, deriveTestsAttested, isTestFile } from './test-bootstrap.js';
 import { classifyStepAsTier, evaluateTiers } from './gate-tiers.js';
 import { mapFilesToRoutes, classifyRoutes, isDocsOnlyDiff } from './qa-scoping.js';
 import { computeCompositeScore } from './health-score.js';
@@ -76,6 +81,7 @@ import {
   verifyConsumerRunRevision,
 } from './consumer-fanout.js';
 import { appendEvent as appendDispatchEvent, readEvents as readDispatchEvents } from './dispatch-ledger.js';
+import { appendEvent as appendFeatureEvent } from './feature-events.js';
 
 // ---------------------------------------------------------------------------
 // COMP-ROADMAP-PLAN S8: gate the `ship` interception by mode.
@@ -97,6 +103,85 @@ export function shouldInterceptShip(stepId, mode) {
   return stepId === 'ship' && mode !== 'plan';
 }
 
+// ---------------------------------------------------------------------------
+// COMP-POLICY-CHECK: pre-response policy check (adherence enforcement).
+// ---------------------------------------------------------------------------
+
+/**
+ * Does this step declare a gate? A gate step is SKILL_GATED by construction —
+ * asking the user for a decision is the point of the step, so policy matches on
+ * its response are suppressed rather than flagged.
+ *
+ * @param {object} spec      the local pipeline spec
+ * @param {string} flowName  active flow
+ * @param {string} stepId    ready-step id (scoped ids resolve to their bare tail)
+ * @returns {boolean}
+ */
+export function isGateStep(spec, flowName, stepId) {
+  const bare = String(stepId ?? '').split('/').pop();
+  const steps = spec?.flows?.[flowName]?.steps;
+  if (!Array.isArray(steps)) return false;
+  return steps.some(st => st?.id === bare && !!st.gate);
+}
+
+/**
+ * COMP-POLICY-CHECK-2/3: scan one step response against the local catalog.
+ * Total — a broken catalog or scan degrades to "no findings" with a WARNING and
+ * never fails the step.
+ *
+ * The user mode is EXPLICIT here, never inferred: a build has no user turns to
+ * classify (see `resolveBuildUserMode`). Config override → gate step → default.
+ *
+ * @param {{cwd: string, text: string, skillGated: boolean}} args
+ * @returns {{records: object[], violations: string[], userMode: string}}
+ */
+export function policyScanForStep({ cwd, text, skillGated }) {
+  const empty = { records: [], violations: [], userMode: 'AUTONOMOUS' };
+  try {
+    const config = getPolicyCheckConfig(cwd);
+    const catalog = getPolicyCatalog(cwd);
+    if (catalog.length === 0) return empty;
+    const userMode = resolveBuildUserMode(config.userMode, { skillGated });
+    const records = scanResponse(text ?? '', catalog, userMode);
+    return { records, violations: toViolationStrings(records), userMode };
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[policy-check] scan skipped: ${err.message}`);
+    return empty;
+  }
+}
+
+/**
+ * COMP-POLICY-CHECK-5: trace every match (flagged AND suppressed) to the
+ * append-only feature-events bus — which syncs into SmartMemory, closing the
+ * measurement loop — plus the build stream for live cockpit visibility.
+ *
+ * @param {object} args
+ * @param {string} args.pass 'initial' | 'policy_revision'
+ */
+export function recordPolicyScan({ cwd, streamWriter, stepId, records, userMode, featureCode, buildId, pass = 'initial' }) {
+  for (const record of records ?? []) {
+    try {
+      appendFeatureEvent(cwd, {
+        tool: 'policy_check',
+        build_id: buildId ?? null,
+        step_id: stepId,
+        rule: record.rule,
+        matched: record.matched,
+        suppressed: record.suppressed,
+        user_mode: userMode,
+        pass,
+      });
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(`[policy-check] trace append failed: ${err.message}`);
+    }
+    try {
+      streamWriter?.writePolicyViolation(stepId, record, userMode, featureCode ?? null, buildId ?? null);
+    } catch { /* stream emit is best-effort */ }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // COMP-ROADMAP-PLAN S5: ratify a plan-authored design instead of clobbering it.
 // ---------------------------------------------------------------------------
@@ -445,6 +530,39 @@ export function deriveOrdinaryReviewScaffold({ contractName = null, stepId = '',
   return { isReviewMain, isReduceMain, isReviewScaffoldMain: isReviewMain && !isReduceMain };
 }
 
+// COMP-AGENT-LANES: one lane per parallel worker slot. Identity is
+// flowId:stepId:itemIndex (stepId/itemIndex RECUR across builds, so flowId is
+// load-bearing); version is the ordered tuple (generation, attempt) — the UI
+// resets a lane on a higher version and rejects lower (stale) events. The
+// label is the human mandate: the review lens id when the item is a review,
+// else the step intent truncated.
+const LANE_LABEL_MAX = 80;
+
+export function buildLaneEnvelope(descriptor, flowId, { lens = null } = {}) {
+  const rawLabel = (typeof lens === 'string' && lens)
+    || (typeof descriptor?.do === 'string' && descriptor.do)
+    || String(descriptor?.id ?? '');
+  const label = rawLabel.length > LANE_LABEL_MAX
+    ? `${rawLabel.slice(0, LANE_LABEL_MAX - 1)}…`
+    : rawLabel;
+  return {
+    flowId,
+    stepId: descriptor.id,
+    itemIndex: descriptor.itemIndex,
+    generation: descriptor.generation ?? 0,
+    attempt: descriptor.attempt ?? 1,
+    label,
+    agent: descriptor.agent ?? 'claude',
+  };
+}
+
+function deriveConsumerLane(descriptor, flowId) {
+  const reviewOpts = deriveConsumerReviewOptions(descriptor);
+  return buildLaneEnvelope(descriptor, flowId, {
+    lens: reviewOpts.reviewMode ? reviewOpts.lens : null,
+  });
+}
+
 export function deriveConsumerReviewOptions(descriptor) {
   const reviewMode = descriptor?.contract?.root === 'ReviewResult';
   const item = (descriptor?.item && typeof descriptor.item === 'object') ? descriptor.item : {};
@@ -620,6 +738,7 @@ async function reportConsumerStepDone({
       itemIndex: descriptor.itemIndex,
       stage: descriptor.stage,
       generation: descriptor.generation,
+      lane: deriveConsumerLane(descriptor, flowId),
     });
     return { response, skipped: true };
   }
@@ -786,6 +905,12 @@ export async function runConsumerIssuance({
   // contract the python parallel-dispatch path emitted — otherwise the fanout runs
   // invisibly and the parallel progress bar never appears.
   const parallelStepNum = `∥${descriptor.itemIndex}`;
+  // COMP-AGENT-LANES: the same lane envelope rides every lifecycle write for
+  // this item AND (via runAndNormalize opts) every relayed output write, so the
+  // cockpit can attribute each event to its worker slot.
+  const lane = buildLaneEnvelope(descriptor, flowId, {
+    lens: reviewOpts.reviewMode ? reviewOpts.lens : null,
+  });
   progress.stepStart(parallelStepNum, '?', descriptor.id);
   streamWriter.write({
     type: 'build_step_start',
@@ -800,6 +925,7 @@ export async function runConsumerIssuance({
     itemIndex: descriptor.itemIndex,
     stage: descriptor.stage,
     generation: descriptor.generation,
+    lane,
   });
 
   let mainResult;
@@ -809,7 +935,9 @@ export async function runConsumerIssuance({
       streamWriter,
       maxDurationMs,
       stratum,
+      lane,
       cwd: recovery.worktree,
+      sandboxMode: descriptor.policy?.isolation === 'worktree' ? 'workspace-write' : 'read-only',
       onAgentEvent,
       profile,
       reviewMode: reviewOpts.reviewMode,
@@ -823,21 +951,24 @@ export async function runConsumerIssuance({
         step_id: descriptor.id,
         ...(typeof descriptor.attempt === 'number' ? { attempt: descriptor.attempt } : {}),
       },
-      // V2/V3: the isolation:none review fanout is the safety-critical controlled
-      // execution — a claude review item runs via the compose-local connector so
-      // its read-only tool restrictions actually BIND (the engine's sync
-      // agent_run can't carry claude allowlists and its sandboxMode binds only
-      // codex) and its per-item timeout / stuck abort truly INTERRUPTS it. Write
-      // (worktree) items keep the engine seam: their per-item timeout still fails
-      // the item, but interrupting an in-flight workspace-write run needs a
-      // stratum follow-up (background mode is codex+read-only-only). Codex review
-      // items also fall back to the sync seam (compose has no codex SDK).
+      // Local Claude owns its SDK process group for review fanout and drains
+      // graceful teardown before timeout/interrupt returns, as MCP does.
       localExecution: descriptor.policy?.isolation === 'none',
     });
   } catch (error) {
-    // User interrupts and injected crashes are control-flow signals, not item
-    // failures — they must propagate and abort the pump.
-    if (error instanceof UserInterruptError || error?.code === 'INJECTED_CONSUMER_CRASH') {
+    const failedUsage = failureUsageFields(error);
+    // Control failures do not settle the item, so record known dispatch usage
+    // before aborting the pump. Never retry work with uncertain termination.
+    if (error instanceof UserInterruptError || ['INJECTED_CONSUMER_CRASH', 'CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(error?.code)) {
+      if (failedUsage.usage && typeof context?.onUsage === 'function') {
+        try {
+          await context.onUsage(usagePayload(failedUsage.usage, failedUsage.usages), {
+            dispatchId: error.dispatchId, stepId: descriptor.step ?? descriptor.id, source: 'consumer',
+          });
+        } catch (usageError) {
+          console.warn(`[consumer] Could not record cancelled usage: ${usageError?.message ?? usageError}`);
+        }
+      }
       throw error;
     }
     // D3: a stuck verdict halts the whole GSD run (not a per-item retry) — the
@@ -846,8 +977,12 @@ export async function runConsumerIssuance({
       // G3: no step_done envelope is sent on the stuck/abort path (the run halts),
       // so the billable usage the aborted run consumed would be lost. Record it
       // into compose's cumulative ledger before converting to the stuck signal.
-      if (error.usage && typeof context?.onUsage === 'function') {
-        context.onUsage(error.usage, descriptor);
+      if (failedUsage.usage && typeof context?.onUsage === 'function') {
+        await context.onUsage(usagePayload(failedUsage.usage, failedUsage.usages), {
+          dispatchId: error.dispatchId,
+          stepId: descriptor.step ?? descriptor.id,
+          source: 'consumer',
+        });
       }
       throw new ConsumerStuckError(stuckTaskId, error.reason);
     }
@@ -859,7 +994,7 @@ export async function runConsumerIssuance({
         settlementFailureClass: 'agent',
         // G3: a timed-out run still consumed billable usage — forward it so the
         // failure envelope debits the engine ledger (same mechanism as F3).
-        ...(error && typeof error === 'object' && error.usage ? { usage: error.usage } : {}),
+        ...failedUsage,
       };
     } else {
       // A non-timeout agent/connector error must fail ONLY this item, not abort
@@ -877,7 +1012,7 @@ export async function runConsumerIssuance({
         // it to the error. Forward it so the failure envelope (and compose's
         // cumulative ledger) debit the attempt instead of letting failures evade
         // budget exhaustion.
-        ...(error && typeof error === 'object' && error.usage ? { usage: error.usage } : {}),
+        ...failedUsage,
       };
     }
   }
@@ -886,7 +1021,11 @@ export async function runConsumerIssuance({
   // D2(b): forward the item's agent usage so GSD can debit the cumulative
   // budget ledger. Build mode passes no onUsage sink → byte-identical no-op.
   if (typeof context?.onUsage === 'function' && mainResult?.usage) {
-    context.onUsage(mainResult.usage, descriptor);
+    await context.onUsage(usagePayload(mainResult.usage, mainResult.usages), {
+      dispatchId: mainResult.dispatchIds?.primary,
+      stepId: descriptor.step ?? descriptor.id,
+      source: 'fanout',
+    });
   }
   const finalStage = isFinalConsumerStage(localSpec, descriptor);
   let localFailure = normalizationFailure
@@ -917,7 +1056,7 @@ export async function runConsumerIssuance({
   // succeeded, so usage rides both the success and failure envelope. Compose's
   // cumulative ledger (context.onUsage) is separate, compose-side accounting.
   const engineUsage = toEngineUsage(mainResult?.usage);
-  if (engineUsage) envelope.usage = engineUsage;
+  if (engineUsage && !context?.receiptsMode) envelope.usage = engineUsage;
 
   if (typeof artifacts.hooks.afterAgentMutationBeforePrepared === 'function') {
     await artifacts.hooks.afterAgentMutationBeforePrepared({
@@ -981,6 +1120,14 @@ export async function runConsumerIssuance({
     // H6: matches the item's start stepId so the UI decrements the same task
     // (AgentStream keys the per-task done on parallel:true + a known stepId).
     parallel: true,
+    // COMP-AGENT-LANES (C4): terminal status is explicit at source — the UI
+    // must not infer "complete" from the done event's existence.
+    status: localFailure ? 'failed' : 'succeeded',
+    outcome: result?.outcome ?? (localFailure ? 'failed' : 'succeeded'),
+    itemIndex: descriptor.itemIndex,
+    stage: descriptor.stage,
+    generation: descriptor.generation,
+    lane,
   });
   return response;
 }
@@ -1066,6 +1213,91 @@ export function toEngineUsage(usage) {
   return Object.keys(out).length > 0 ? out : null;
 }
 
+// A repair failure can carry two dispatch records. Keep those records for
+// receipts and aggregate both for the legacy step_done budget envelope.
+function failureUsageFields(error) {
+  const usages = Array.isArray(error?.usages) ? error.usages : null;
+  if (!usages?.length) return error?.usage ? { usage: error.usage } : {};
+  if (usages.length === 1 && error?.usage) return { usage: error.usage, usages };
+  const usage = {
+    input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0,
+    cache_read_input_tokens: 0, cost_usd: 0, duration_ms: 0, model: null,
+  };
+  for (const entry of usages) {
+    if (!entry || typeof entry !== 'object') continue;
+    usage.input_tokens += entry.input_tokens ?? 0;
+    usage.output_tokens += entry.output_tokens ?? 0;
+    usage.cache_creation_input_tokens += entry.cache_creation ?? entry.cache_creation_input_tokens ?? 0;
+    usage.cache_read_input_tokens += entry.cache_read ?? entry.cache_read_input_tokens ?? 0;
+    usage.cost_usd += entry.cost_usd ?? 0;
+    usage.duration_ms += entry.duration_ms ?? 0;
+    usage.model = entry.model ?? usage.model;
+  }
+  return { usage, usages };
+}
+
+function usagePayload(usage, usages) {
+  if (!usage || typeof usage !== 'object') return usage;
+  return Array.isArray(usages) ? { ...usage, usages } : usage;
+}
+
+/** Send one surface-15 receipt per underlying model dispatch. */
+export async function reportUsageReceipts(context, usage, meta = {}) {
+  if (!context?.receiptsMode || !context.flowId || typeof context.stratum?.usageReport !== 'function') {
+    return [];
+  }
+  const entries = Array.isArray(usage)
+    ? usage
+    : (Array.isArray(usage?.usages) ? usage.usages : (usage ? [usage] : []));
+  const responses = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue;
+    const engineUsage = toEngineUsage(entry);
+    if (!engineUsage) continue;
+    // Surface 15 requires explicit USD provenance. Normalized UsageRecords carry
+    // `usd_source`; raw engine usage ({tokens, usd, ms}) does not. Preserve raw
+    // token/time usage, but fail closed on an unlabelled dollar value instead of
+    // manufacturing "reported" provenance.
+    const usdSource = ['reported', 'estimated'].includes(entry.usd_source)
+      ? entry.usd_source
+      : null;
+    if (Object.hasOwn(engineUsage, 'usd') && !usdSource) delete engineUsage.usd;
+    if (Object.keys(engineUsage).length === 0) continue;
+    const input = entry.input_tokens;
+    const output = entry.output_tokens;
+    const receipt = {
+      dispatchId: entry.dispatch_id ?? meta.dispatchId ?? randomUUID(),
+      ...(meta.stepId ? { stepId: meta.stepId } : {}),
+      source: meta.source ?? 'main',
+      usage: engineUsage,
+      telemetry: {
+        model: typeof entry.model === 'string' && entry.model.length > 0 ? entry.model : 'unknown',
+        ...(typeof entry.effort === 'string' && entry.effort.length > 0 ? { effort: entry.effort } : {}),
+        durationMs: entry.duration_ms ?? entry.ms ?? 0,
+      },
+      ...(typeof input === 'number' || typeof output === 'number'
+        ? { split: {
+            input: input ?? 0,
+            output: output ?? 0,
+            ...(typeof (entry.cache_read ?? entry.cache_read_input_tokens) === 'number'
+              ? { cacheRead: entry.cache_read ?? entry.cache_read_input_tokens }
+              : {}),
+            ...(typeof (entry.cache_creation ?? entry.cache_creation_input_tokens) === 'number'
+              ? { cacheCreation: entry.cache_creation ?? entry.cache_creation_input_tokens }
+              : {}),
+          } }
+        : {}),
+      ...(Object.hasOwn(engineUsage, 'usd') ? { usdSource } : {}),
+    };
+    try {
+      responses.push(await context.stratum.usageReport(context.flowId, receipt));
+    } catch (error) {
+      console.warn(`[usage-receipt] failed for ${receipt.dispatchId}: ${error?.message ?? error}`);
+    }
+  }
+  return responses;
+}
+
 /**
  * F5: deterministic v1 vocabulary enforcement, evaluated compose-side at the
  * review_merge step (the step the now-dropped judged ensure was attached to). The
@@ -1244,7 +1476,20 @@ function writeActiveBuild(dataDir, state) {
   renameSync(tmp, target);
 }
 
-const BUILD_ACCUMULATOR_VERSION = 1;
+// COMP-COMPLETION-GATE slice 2: v2 adds the completion evidence the gate needs
+// at terminalization — `tests_attested` (tri-state) and `evidence_root`.
+//
+// `test_count`/`pass_rate` were already here but are metrics, not attestation:
+// they are only populated when the output PARSED, so their absence is ambiguous
+// between "no tests" and "could not read the output". The gate cannot act on an
+// ambiguous signal, hence an explicit tri-state.
+//
+// `evidence_root` is persisted because a cross-repo build runs git and tests in
+// the agent's tree while feature metadata lives in the project tree — and
+// `runBuild` reconstructs that root from the CURRENT invocation, so a resumed
+// cross-repo build would otherwise fall back to the project root and verify the
+// wrong repository's HEAD.
+const BUILD_ACCUMULATOR_VERSION = 2;
 const BUILD_ACCUMULATOR_FIELDS = new Set([
   'v',
   'build_id',
@@ -1256,9 +1501,13 @@ const BUILD_ACCUMULATOR_FIELDS = new Set([
   'ship_files_changed',
   'test_count',
   'pass_rate',
+  'tests_attested',
+  'evidence_root',
   'tokens_total',
   'usd',
 ]);
+/** The only values `tests_attested` may hold. See deriveTestsAttested. */
+const TESTS_ATTESTED_VALUES = new Set(['passed', 'failed', 'no-signal']);
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 function assertFeatureCodeForAccumulator(featureCode) {
@@ -1326,9 +1575,35 @@ function validateBuildAccumulator(value, expectedFeatureCode = null) {
       throw new Error(`Build accumulator is corrupt: ${key} must be a non-negative finite number`);
     }
   }
+  if (!TESTS_ATTESTED_VALUES.has(value.tests_attested)) {
+    throw new Error(
+      `Build accumulator is corrupt: tests_attested must be one of ${[...TESTS_ATTESTED_VALUES].join('|')}`,
+    );
+  }
+  if (value.evidence_root !== null && typeof value.evidence_root !== 'string') {
+    throw new Error('Build accumulator is corrupt: evidence_root must be null or a string');
+  }
   return value;
 }
 
+/**
+ * Bring a v1 accumulator forward. A v1 record predates completion evidence, so
+ * it cannot say anything about whether tests were attested — and the honest value
+ * for "we do not know" is `no-signal`, which the completion gate REFUSES. A build
+ * resumed across this upgrade therefore has to re-attest rather than inheriting a
+ * pass it never recorded. That is the intended direction: absence of signal is
+ * never attestation.
+ */
+function migrateBuildAccumulator(value) {
+  if (!value || typeof value !== 'object' || value.v !== 1) return value;
+  return {
+    ...value,
+    v: BUILD_ACCUMULATOR_VERSION,
+    tests_attested: 'no-signal',
+    evidence_root: null,
+  };
+}
+
 export function readBuildAccumulator(projectCwd, featureCode) {
   const path = buildAccumulatorPath(projectCwd, featureCode);
   if (!existsSync(path)) return null;
@@ -1338,7 +1613,7 @@ export function readBuildAccumulator(projectCwd, featureCode) {
   } catch (error) {
     throw new Error(`Build accumulator is corrupt at ${path}: ${error.message}`);
   }
-  return validateBuildAccumulator(parsed, featureCode);
+  return validateBuildAccumulator(migrateBuildAccumulator(parsed), featureCode);
 }
 
 export function writeBuildAccumulator(projectCwd, accumulator) {
@@ -1368,6 +1643,8 @@ export function newBuildAccumulatorRecord(featureCode) {
     ship_files_changed: null,
     test_count: null,
     pass_rate: null,
+    tests_attested: 'no-signal',
+    evidence_root: null,
     tokens_total: 0,
     usd: 0,
   };
@@ -1473,7 +1750,11 @@ export function settleDispatches(projectCwd, buildId, stepId, {
   if (gsd) return [];
   const primary = dispatchIds?.primary;
   const repair = dispatchIds?.repair;
-  if (!primary && !repair) return [];
+  // COMP-POLICY-CHECK-4: a policy revision is a second dispatch whose output
+  // replaced the primary's. It settles on the same verdict as the run it
+  // replaced — same path, one more id, no parallel settlement loop.
+  const revision = dispatchIds?.revision;
+  if (!primary && !repair && !revision) return [];
   const rows = [];
   const appendSettlement = (dispatchId, isAccepted, rejectedClass) => {
     if (typeof dispatchId !== 'string' || dispatchId.length === 0) return;
@@ -1501,6 +1782,14 @@ export function settleDispatches(projectCwd, buildId, stepId, {
       isEnsureRetry ? 'ensure-retry' : failureClass,
     );
   }
+
+  if (revision) {
+    appendSettlement(
+      revision,
+      isEnsureRetry ? false : accepted === true,
+      isEnsureRetry ? 'ensure-retry' : failureClass,
+    );
+  }
   return rows;
 }
 
@@ -1668,10 +1957,12 @@ function isProcessAlive(pid) {
  * @param {object} gateDispatch - Stratum gate dispatch (step_id, on_approve, on_revise, on_kill)
  * @param {object} [gateExtras] - Optional enrichment (fromPhase, toPhase, summary)
  */
-function makeAskAgent(stratum, context, gateDispatch, gateExtras) {
+export function makeAskAgent(stratum, context, gateDispatch, gateExtras) {
   const preamble = buildGateContext(gateDispatch, context, gateExtras);
+  let budgetExhausted = false;
 
   return async function askAgent(question, artifactPath) {
+    if (budgetExhausted) return '(budget exhausted)';
     const fileRef = artifactPath && !artifactPath.endsWith('/')
       ? `Read the file "${artifactPath}" and answer`
       : `Look at the project files in the working directory and answer`;
@@ -1690,6 +1981,15 @@ function makeAskAgent(stratum, context, gateDispatch, gateExtras) {
         step_id: gateDispatch.step_id ?? gateDispatch.id,
         ...(typeof gateDispatch.attempt === 'number' ? { attempt: gateDispatch.attempt } : {}),
       },
+      onUsage: async (usages) => {
+        const results = await context.recordBuildUsage?.(usages, {
+          stepId: gateDispatch.step_id ?? gateDispatch.id,
+          source: 'gate_qa',
+        });
+        if (results?.some((result) => ['flow_exhausted', 'flow_exhausted_after_terminal'].includes(result?.budget))) {
+          budgetExhausted = true;
+        }
+      },
     });
     return text || '(no answer)';
   };
@@ -1740,6 +2040,22 @@ export function resolveTemplatePath(name, cwd) {
   const presetsPath = join(packageDir, '..', 'presets', `${templateName}.stratum.yaml`);
   if (existsSync(presetsPath)) return presetsPath;
 
+  // COMP-PIPELINE-QUARANTINE follow-up: fall back to the BUNDLED pipelines too,
+  // not just presets. `compose init` seeds a curated few specs, so every other
+  // shipped pipeline (content, coverage-sweep, refactor, research, review-fix)
+  // was unreachable from a workspace no matter how it was invoked — the resolver
+  // simply had no path to them. Project-local still wins, so a workspace that
+  // customizes a spec keeps its own copy.
+  //
+  // NOT for the init-provisioned specs: if `build` is missing, the workspace was
+  // never initialized, and answering with our bundled copy would silently run
+  // Compose's own pipeline against an uninitialized project instead of raising
+  // "Lifecycle spec not found".
+  if (!INIT_PROVISIONED_SPECS.includes(templateName)) {
+    const bundledPath = join(packageDir, '..', 'pipelines', `${templateName}.stratum.yaml`);
+    if (existsSync(bundledPath)) return bundledPath;
+  }
+
   return projectPath;
 }
 
@@ -2160,6 +2476,15 @@ export async function runBuild(featureCode, opts = {}) {
   const stepProfiles = loadPipelineProfiles(specPath);
   let specYaml = readFileSync(specPath, 'utf-8');
 
+  // COMP-PIPELINE-QUARANTINE: refuse a retired-dialect spec HERE, at the one
+  // seam every template passes through (build, fix, plan, --quick, --template,
+  // bundled presets), rather than letting the engine answer with a bare
+  // `-32602: spec validation failed` that names neither the file nor the cause.
+  const specCompat = tsCompatibilityOf(specYaml);
+  if (!specCompat.compatible) {
+    throw new Error(quarantineMessage(specPath, specCompat));
+  }
+
   // STRAT-IMMUTABLE: hash the on-disk spec BEFORE triage mutation for tamper detection.
   // verifyPipelineIntegrity() re-reads from disk, so we must compare against the original file content.
   const specFileHash = _sha256(specYaml);
@@ -2266,6 +2591,9 @@ export async function runBuild(featureCode, opts = {}) {
   // Stratum MCP client (test override permitted via opts.stratum)
   stratum = opts.stratum ?? new StratumMcpClient();
   if (!opts.stratum) await stratum.connect(resolveStratumMcpConnection(cwd));
+  const receiptsMode = typeof stratum.hasTool === 'function'
+    ? await stratum.hasTool('stratum_usage_report')
+    : false;
 
   // Update feature.json status to IN_PROGRESS (only modes that track
   // feature.json lifecycle status; bug AND plan do not).
@@ -2396,6 +2724,26 @@ export async function runBuild(featureCode, opts = {}) {
       }
       reviewerAgent = opts.reviewer;
     }
+    // COMP-PIPELINE-QUARANTINE round 3: keep the two roles on DIFFERENT providers
+    // unless the caller asked for both explicitly. `--implementer codex` alone
+    // leaves the reviewer at its codex default, so cross-model review silently
+    // becomes Codex reviewing its own work — which is exactly the defect the
+    // review-fix pipeline was corrected for, reintroduced one layer down. When
+    // only one role is overridden, the other flips to the opposite provider.
+    // Setting both to the same provider stays possible, but only deliberately.
+    if (parseAgentString(implementerAgent).provider === parseAgentString(reviewerAgent).provider) {
+      const bothExplicit = opts.implementer != null && opts.reviewer != null;
+      if (!bothExplicit) {
+        const flipped = parseAgentString(implementerAgent).provider === 'codex' ? 'claude' : 'codex';
+        if (opts.reviewer == null) reviewerAgent = flipped;
+        else implementerAgent = flipped;
+      } else {
+        console.warn(
+          `⚠ implementer and reviewer are both ${parseAgentString(implementerAgent).provider}; ` +
+          'cross-model review is disabled for this run.'
+        );
+      }
+    }
     const roles = { implementerAgent, reviewerAgent };
     // Restore persisted roles when (and only when) a resume actually happens.
     const restoreRolesFromActive = (src) => {
@@ -2562,7 +2910,10 @@ export async function runBuild(featureCode, opts = {}) {
     // The plan/resume above only created the flow object; no agent/worktree work has
     // happened yet, so aborting here still means we never reach `execute` (Codex
     // review finding #2). Cached + skippable via COMPOSE_SKIP_CODEX_PROBE.
-    if (implementerAgent === 'codex') {
+    // Compare the PROVIDER, not the raw string: `codex:orchestrator` and
+    // `codex::critical` are Codex implementers too, and an exact-string check let
+    // them skip the mandatory worktree probe entirely (round 4 review).
+    if (parseAgentString(implementerAgent).provider === 'codex') {
       const probe = await preflightCodexWorktreeProbe({
         cwd: agentCwd,
         projectCwd: cwd,
@@ -2667,6 +3018,9 @@ export async function runBuild(featureCode, opts = {}) {
     })();
 
     const context = {
+      stratum,
+      flowId: response.runId,
+      receiptsMode,
       cwd: agentCwd,
       projectCwd: cwd,
       featureCode,
@@ -2691,24 +3045,33 @@ export async function runBuild(featureCode, opts = {}) {
       filesChanged: [...activeAccumulator.files_changed],
       ...(isBugMode ? { bug_code: featureCode } : {}),
     };
-    context.recordBuildUsage = (usage) => {
+    context.recordBuildUsage = async (usage, meta) => {
       if (!usage || typeof usage !== 'object') return;
-      const componentTokens = (typeof usage.input_tokens === 'number' ? usage.input_tokens : 0)
-        + (typeof usage.output_tokens === 'number' ? usage.output_tokens : 0);
+      const accumulatorUsage = Array.isArray(usage)
+        ? usage.reduce((sum, entry) => ({
+            input_tokens: sum.input_tokens + (entry?.input_tokens ?? 0),
+            output_tokens: sum.output_tokens + (entry?.output_tokens ?? entry?.tokens ?? 0),
+            cost_usd: sum.cost_usd + (entry?.cost_usd ?? entry?.usd ?? 0),
+          }), { input_tokens: 0, output_tokens: 0, cost_usd: 0 })
+        : usage;
+      const componentTokens = (typeof accumulatorUsage.input_tokens === 'number' ? accumulatorUsage.input_tokens : 0)
+        + (typeof accumulatorUsage.output_tokens === 'number' ? accumulatorUsage.output_tokens : 0);
       const tokens = componentTokens > 0
         ? componentTokens
-        : (typeof usage.tokens_total === 'number'
-            ? usage.tokens_total
-            : (typeof usage.tokens === 'number' ? usage.tokens : 0));
-      const usd = typeof usage.cost_usd === 'number'
-        ? usage.cost_usd
-        : (typeof usage.usd === 'number' ? usage.usd : 0);
-      if (tokens === 0 && usd === 0) return;
-      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
-        ...accumulator,
-        tokens_total: accumulator.tokens_total + tokens,
-        usd: accumulator.usd + usd,
-      }));
+        : (typeof accumulatorUsage.tokens_total === 'number'
+            ? accumulatorUsage.tokens_total
+            : (typeof accumulatorUsage.tokens === 'number' ? accumulatorUsage.tokens : 0));
+      const usd = typeof accumulatorUsage.cost_usd === 'number'
+        ? accumulatorUsage.cost_usd
+        : (typeof accumulatorUsage.usd === 'number' ? accumulatorUsage.usd : 0);
+      if (tokens !== 0 || usd !== 0) {
+        updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+          ...accumulator,
+          tokens_total: accumulator.tokens_total + tokens,
+          usd: accumulator.usd + usd,
+        }));
+      }
+      return reportUsageReceipts(context, usage, meta);
     };
     context.recordFilesChanged = (paths, { authoritativeShip = false } = {}) => {
       const normalized = Array.isArray(paths)
@@ -2721,6 +3084,27 @@ export async function runBuild(featureCode, opts = {}) {
           : { files_changed: [...new Set([...accumulator.files_changed, ...normalized])] }),
       }));
     };
+    // COMP-COMPLETION-GATE slice 2: the ship step's completion evidence, carried
+    // to terminalization (where completion now happens, after the health gate).
+    //
+    // `tests_attested` and `evidence_root` are PERSISTED because they cannot be
+    // re-derived later: re-running the suite at terminalization would be a second
+    // run with a different result, and `runBuild` rebuilds the agent cwd from the
+    // current invocation — so a resumed cross-repo build would otherwise verify
+    // the wrong repository. The commit SHA is deliberately NOT persisted; it is
+    // resolved from HEAD at terminalization, where it is verifiable.
+    context.completionEvidence = null;
+    context.recordCompletionEvidence = (evidence = {}) => {
+      context.completionEvidence = { ...(context.completionEvidence || {}), ...evidence };
+      const attested = evidence.testsAttested;
+      if (attested !== undefined) {
+        updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+          ...accumulator,
+          tests_attested: attested,
+          evidence_root: agentCwd,
+        }));
+      }
+    };
     context.recordShipTestMetrics = (metrics) => {
       if (!metrics || typeof metrics.test_count !== 'number') return;
       updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
@@ -2779,6 +3163,11 @@ export async function runBuild(featureCode, opts = {}) {
     // is the backstop — if the round can't be threaded for any reason, it trips
     // instead of letting the gate spin unbounded (the 52-round loop).
     const gateReentries = new Map();
+    // Last consumer-merge preparation/apply failure per merge gate. A failure
+    // that repeats byte-identically means the fan-out re-produced the same
+    // conflict; revising again only re-dispatches every lane for the same result
+    // (observed 2026-08-30: 4 paid rounds on one MERGE_WITNESS_PRECOMPUTE_FAILED).
+    const consumerMergeFailures = new Map();
 
     // The run's effective-spec digest, carried on plan/resume responses only
     // (step_done responses omit it). Captured so the merge-gate path can pin the
@@ -3080,14 +3469,12 @@ export async function runBuild(featureCode, opts = {}) {
             };
           }
           verifyPipelineIntegrity(specPath, specFileHash);
+          // `plan_items` is declared by build.stratum.yaml's PhaseResult but NOT
+          // by gsd's, so it stays at this call site rather than in the shared
+          // narrowing helper.
           const tsShipOutput = {
-            phase: shipResult.phase,
-            artifact: shipResult.artifact,
-            outcome: shipResult.outcome,
-            summary: shipResult.summary,
+            ...toPhaseResultOutput(shipResult),
             ...(Array.isArray(shipResult.plan_items) ? { plan_items: shipResult.plan_items } : {}),
-            ...(Array.isArray(shipResult.filesChanged) ? { files_changed: shipResult.filesChanged } : {}),
-            ...(typeof shipResult.commit === 'string' ? { commit_hash: shipResult.commit } : {}),
           };
           const shipStepResult = response.status === 'ready'
             ? { output: tsShipOutput }
@@ -3124,7 +3511,14 @@ export async function runBuild(featureCode, opts = {}) {
               maxDurationMs: STEP_TIMEOUT_MS[stepId] ?? DEFAULT_TIMEOUT_MS,
               stratum,
               cwd: agentCwd,
-              profile: resolveStepProfile(context.stepProfiles, stepId),
+              // C9: the sidecar's `fix` profile carries the fixer's tool
+              // restrictions and model tier. Passing the bare agent literal
+              // here handed the fixer an unrestricted profile; the sibling
+              // review-repair site keys off `fix` the same way. Identity still
+              // comes from the dispatch (`agent: fixAgent`).
+              profile: resolveStepProfile(context.stepProfiles, 'fix')
+                ?? resolveStepProfile(context.stepProfiles, stepId),
+              sandboxMode: 'workspace-write',
               telemetry: {
                 site: 'review-repair',
                 project_cwd: cwd,
@@ -3135,11 +3529,23 @@ export async function runBuild(featureCode, opts = {}) {
               },
             });
             if (fixResult?.usage && typeof context.recordBuildUsage === 'function') {
-              try { context.recordBuildUsage(fixResult.usage); } catch { /* fail-open */ }
+              try {
+                await context.recordBuildUsage(usagePayload(fixResult.usage, fixResult.usages), {
+                  stepId,
+                  source: 'fixer',
+                  dispatchId: fixResult.dispatchIds?.primary,
+                });
+              } catch { /* fail-open */ }
             }
           } catch (err) {
             if (err?.usage && typeof context.recordBuildUsage === 'function') {
-              try { context.recordBuildUsage(err.usage); } catch { /* fail-open */ }
+              try {
+                await context.recordBuildUsage(usagePayload(err.usage, err.usages), {
+                  stepId,
+                  source: 'fixer',
+                  dispatchId: err.dispatchId,
+                });
+              } catch { /* fail-open */ }
             }
             if (err instanceof AgentTimeoutError) {
               console.warn(`\n⚠ Fix agent timed out on "${stepId}"`);
@@ -3154,7 +3560,9 @@ export async function runBuild(featureCode, opts = {}) {
         const stepStartMs = Date.now();
         const agentType = readyStep?.agent ?? response.agent ?? 'claude';
         const basePrompt = buildStepPrompt(stepDispatch, context);
-        const maxDurationMs = STEP_TIMEOUT_MS[stepId] ?? DEFAULT_TIMEOUT_MS;
+        const maxDurationMs = process.env.NODE_ENV === 'test' && Number.isFinite(opts.stepTimeoutMs)
+          ? opts.stepTimeoutMs
+          : (STEP_TIMEOUT_MS[stepId] ?? DEFAULT_TIMEOUT_MS);
 
         // MF-1/SF-4: Prepend shared review scaffold when this is a review step.
         // Also covers a ReviewResult merge step so its output is normalized via
@@ -3209,14 +3617,19 @@ export async function runBuild(featureCode, opts = {}) {
             profile: resolveStepProfile(effectiveProfiles, stepId),
           });
         } catch (err) {
+          const failedUsage = failureUsageFields(err);
           if (err instanceof UserInterruptError) {
             if (err.action === 'skip') {
               if (progress) progress.info(`  ⏭ Skipped step "${stepId}"`);
               mainResult = {
                 text: '',
-                result: { outcome: 'skipped', summary: 'Skipped by user' },
+                // `phase` is carried because every pipeline's result contract
+                // declares it and engine contracts are strict — without it a
+                // user-initiated skip fails the step it was meant to bypass.
+                result: { phase: stepId, outcome: 'skipped', summary: 'Skipped by user' },
                 dispatchIds: { primary: err.dispatchId ?? null, repair: null },
                 settlementFailureClass: 'agent',
+                ...failedUsage,
               };
             } else {
               if (progress) progress.info(`  ↻ Retrying step "${stepId}"`);
@@ -3225,6 +3638,7 @@ export async function runBuild(featureCode, opts = {}) {
                 result: { outcome: 'failed', summary: 'Retry requested by user' },
                 dispatchIds: { primary: err.dispatchId ?? null, repair: null },
                 settlementFailureClass: 'agent',
+                ...failedUsage,
               };
             }
           } else if (err instanceof AgentTimeoutError) {
@@ -3235,18 +3649,115 @@ export async function runBuild(featureCode, opts = {}) {
               result: { outcome: 'failed', summary: `Timed out after ${Math.round(err.durationMs / 1000)}s` },
               dispatchIds: { primary: err.dispatchId ?? null, repair: null },
               settlementFailureClass: 'agent',
-              ...(err.usage ? { usage: err.usage } : {}),
+              ...failedUsage,
             };
           } else {
             // Fatal rethrow bypasses the post-stepDone usage fold — bill the
             // attempt's real cost to the accumulator before crashing.
-            if (err?.usage && typeof context.recordBuildUsage === 'function') {
-              try { context.recordBuildUsage(err.usage); } catch { /* fail-open */ }
+            if (failedUsage.usage && typeof context.recordBuildUsage === 'function') {
+              try {
+                await context.recordBuildUsage(usagePayload(failedUsage.usage, failedUsage.usages), {
+                  stepId,
+                  source: 'main',
+                  dispatchId: err.dispatchId,
+                });
+              } catch { /* fail-open */ }
             }
             streamWriter.write({ type: 'build_error', message: err.message, stepId });
             throw err;
           }
         }
+        // COMP-POLICY-CHECK-3/4: scan the candidate response against the local
+        // adherence catalog before it is accepted, then allow the agent exactly
+        // one revision pass. Never hard-blocks (design: "surfaces violations for
+        // revision; it does not refuse to emit") and never rewrites the draft.
+        let policyViolationStrings = [];
+        let policyUnsuppressedCount = 0;
+        {
+          const skillGated = isGateStep(localSpec, localFlowName, stepId);
+          const traceArgs = { cwd, streamWriter, stepId, featureCode, buildId: build_id };
+
+          let scan = policyScanForStep({ cwd, text: mainResult?.text, skillGated });
+          recordPolicyScan({ ...traceArgs, records: scan.records, userMode: scan.userMode, pass: 'initial' });
+
+          if (scan.violations.length > 0) {
+            if (progress) progress.warn(`Policy check: ${scan.violations.length} unsuppressed violation(s) — requesting one revision`);
+            try {
+              const revised = await runAndNormalize(
+                null,
+                `${prompt}\n\n${buildRevisionNotice(scan.records)}`,
+                stepDispatch,
+                {
+                  progress, streamWriter, maxDurationMs, stratum, cwd: agentCwd,
+                  reviewMode: isReviewMain,
+                  confidenceGate: confGateMain,
+                  profile: resolveStepProfile(effectiveProfiles, stepId),
+                  telemetry: {
+                    site: 'policy-revision',
+                    project_cwd: cwd,
+                    build_id,
+                    feature_code: featureCode,
+                    step_id: stepId,
+                    ...(typeof readyStep?.attempt === 'number' ? { attempt: readyStep.attempt } : {}),
+                  },
+                },
+              );
+              const replaces = revised && !revised.normalizationFailure && revised.result?.outcome !== 'failed';
+              if (!replaces && revised?.usage && typeof context.recordBuildUsage === 'function') {
+                // Rejected revision: its cost still happened, and no merged
+                // usage will carry it, so bill it like the review fixer's.
+                try {
+                  await context.recordBuildUsage(usagePayload(revised.usage, revised.usages), {
+                    stepId,
+                    source: 'policy_revision',
+                    dispatchId: revised.dispatchIds?.primary,
+                  });
+                } catch { /* fail-open */ }
+              }
+              if (replaces) {
+                await reportUsageReceipts(
+                  context,
+                  usagePayload(revised.usage, revised.usages),
+                  { stepId, source: 'policy_revision', dispatchId: revised.dispatchIds?.primary },
+                );
+                // The replacement carries BOTH dispatch ids (so settlement
+                // settles both) and the summed usage (so step_usage, build
+                // totals, and build-history include the revision's cost — the
+                // step_usage block below is the single accumulator call).
+                mainResult = {
+                  ...mainResult,
+                  text: revised.text ?? mainResult.text,
+                  result: revised.result ?? mainResult.result,
+                  usage: mergeUsage(mainResult.usage, revised.usage),
+                  dispatchIds: {
+                    ...(mainResult.dispatchIds ?? {}),
+                    revision: revised.dispatchIds?.primary ?? null,
+                  },
+                };
+                scan = policyScanForStep({ cwd, text: mainResult.text, skillGated });
+                recordPolicyScan({ ...traceArgs, records: scan.records, userMode: scan.userMode, pass: 'policy_revision' });
+              }
+              // The second result stands either way — no further passes.
+            } catch (err) {
+              if (err?.usage && typeof context.recordBuildUsage === 'function') {
+                try {
+                  await context.recordBuildUsage(usagePayload(err.usage, err.usages), {
+                    stepId,
+                    source: 'policy_revision',
+                    dispatchId: err.dispatchId,
+                  });
+                } catch { /* fail-open */ }
+              }
+              if (policyRevisionMustStop(err)) throw err;
+              // eslint-disable-next-line no-console
+              console.warn(`[policy-check] revision pass failed on "${stepId}" — keeping the original draft: ${err.message}`);
+            }
+          }
+
+          policyViolationStrings = scan.violations;
+          policyUnsuppressedCount = scan.violations.length;
+        }
+
         const { result, text: stepText, usage: stepUsage, normalizationFailure } = mainResult;
 
         // Scan agent output for "we should X" / "we could X" patterns that don't map
@@ -3401,17 +3912,36 @@ export async function runBuild(featureCode, opts = {}) {
           // lens rather than a normalization-stamped 'general'.
           lastReviewMergeDirtyLenses = extractDirtyLenses(stepText ?? result);
         }
+        // COMP-POLICY-CHECK-6: expose the unsuppressed count on the step result
+        // so a spec can declare `ensure: ['result.unsuppressed_violations == 0']`.
+        // Engine contracts are strict, so the field is attached only where it is
+        // declared (or where the step has no out contract).
+        const policyResult = attachPolicyCount(result, policyUnsuppressedCount, stepDispatch);
         const stepDoneResult = readyStep
           ? blockingFailure
             ? { failure: blockingFailure }
             : normalizationFailure || result?.outcome === 'failed'
               ? { failure: String(normalizationFailure ?? result?.summary ?? `Step "${stepId}" did not produce structured output`) }
               : stepDispatch.has_out_contract
-                ? result != null
-                  ? { output: result }
+                ? policyResult != null
+                  ? { output: policyResult }
                   : { failure: `Step "${stepId}" did not produce structured output` }
                 : {}
-          : result ?? { summary: 'Step complete' };
+          : policyResult ?? { summary: 'Step complete' };
+        // Report each model dispatch before the outcome it funded. The merged
+        // step usage remains the accumulator/build-stream shape used by existing
+        // callers; receipts use mainResult.usages to preserve per-dispatch data.
+        if (toEngineUsage(stepUsage)) {
+          buildCostTotals.input_tokens += stepUsage.input_tokens ?? 0;
+          buildCostTotals.output_tokens += stepUsage.output_tokens ?? 0;
+          buildCostTotals.cost_usd += stepUsage.cost_usd ?? 0;
+          await context.recordBuildUsage(usagePayload(stepUsage, mainResult.usages), {
+            stepId,
+            source: 'main',
+            dispatchId: mainResult.dispatchIds?.primary,
+          });
+          streamWriter.writeUsage(stepId, stepUsage);
+        }
         response = await stratum.stepDone(
           flowId, stepId, stepDoneResult, readyStep?.dispatchToken,
         );
@@ -3528,17 +4058,10 @@ export async function runBuild(featureCode, opts = {}) {
         {
           const buildState = readActiveBuild(dataDir);
           const stepState = buildState?.steps?.find(s => s.id === stepId) ?? {};
-          // COMP-OBS-COST: accumulate step usage and emit step_usage event
-          if (stepUsage && (stepUsage.input_tokens > 0 || stepUsage.output_tokens > 0 || stepUsage.cost_usd > 0)) {
-            buildCostTotals.input_tokens += stepUsage.input_tokens ?? 0;
-            buildCostTotals.output_tokens += stepUsage.output_tokens ?? 0;
-            buildCostTotals.cost_usd += stepUsage.cost_usd ?? 0;
-            context.recordBuildUsage(stepUsage);
-            streamWriter.writeUsage(stepId, stepUsage);
-          }
-
-          // COMP-HEALTH: collect runtime violations for health score signal
-          const stepViolations = stepState.violations ?? [];
+          // COMP-HEALTH: collect runtime violations for health score signal.
+          // COMP-POLICY-CHECK-3: unsuppressed policy violations join the same
+          // stream — ViolationDetail renders them with zero UI changes.
+          const stepViolations = [...(stepState.violations ?? []), ...policyViolationStrings];
           if (stepViolations.length > 0) {
             allViolations.push(...stepViolations);
           }
@@ -3684,10 +4207,18 @@ export async function runBuild(featureCode, opts = {}) {
               ) ?? null;
             }
           }
+          const repairFor = (error) => {
+            const failure = `${error.code}: ${error.message}`;
+            const decision = decideMergeRepairOutcome(
+              consumerMergeFailures.get(stepId), failure, repairOutcome,
+            );
+            consumerMergeFailures.set(stepId, failure);
+            outcome = decision.outcome;
+            rationale = decision.rationale;
+          };
           if (consumerMergeArtifacts && outcome === 'approve') {
             if (consumerMergePreparationError) {
-              outcome = repairOutcome;
-              rationale = `${consumerMergePreparationError.code}: ${consumerMergePreparationError.message}`;
+              repairFor(consumerMergePreparationError);
             } else {
               try {
                 await consumerMergeArtifacts.applyMerge(consumerMergeTransaction);
@@ -3705,8 +4236,7 @@ export async function runBuild(featureCode, opts = {}) {
                 } catch { /* best-effort build context projection */ }
               } catch (error) {
                 if (!(error instanceof ConsumerMergeDecisionError)) throw error;
-                outcome = repairOutcome;
-                rationale = `${error.code}: ${error.message}`;
+                repairFor(error);
               }
             }
           }
@@ -3792,8 +4322,18 @@ export async function runBuild(featureCode, opts = {}) {
           let reviewResult = lastReviewMergeResult;
           let rawDirtyLenses = lastReviewMergeDirtyLenses;
           if (!reviewResult) {
-            const auditedOutput = gateAudit?.steps?.review_merge?.output ?? null;
-            if (auditedOutput && typeof auditedOutput === 'object') {
+            // COMP-PIPELINE-QUARANTINE follow-up: the re-derive used to read
+            // `steps.review_merge.output` by that literal name, so any pipeline
+            // whose reducer is called something else (team-review's `merge`,
+            // review-fix's `review`) silently got a null stash on resume and had
+            // its clean review treated as dirty. The stash above is already keyed
+            // on the sidecar's _reduceSteps; this now matches it, with the
+            // canonical id kept as the fallback.
+            const reducerIds = [...reduceSteps, 'review_merge'];
+            const auditedOutput = reducerIds
+              .map((id) => gateAudit?.steps?.[id]?.output ?? null)
+              .find((out) => out && typeof out === 'object') ?? null;
+            if (auditedOutput) {
               reviewResult = auditedOutput;
               rawDirtyLenses = extractDirtyLenses(auditedOutput);
             }
@@ -3833,7 +4373,7 @@ export async function runBuild(featureCode, opts = {}) {
             try {
               const gateFixResult = await runAndNormalize(undefined, fixPrompt, { step_id: 'review_fix', agent: fixAgent, flow_id: flowId }, {
                 progress, streamWriter, maxDurationMs: STEP_TIMEOUT_MS.review_merge ?? DEFAULT_TIMEOUT_MS,
-                stratum, cwd: agentCwd, profile: resolveStepProfile(effectiveProfiles, 'fix'),
+                stratum, cwd: agentCwd, sandboxMode: 'workspace-write', profile: resolveStepProfile(effectiveProfiles, 'fix'),
                 telemetry: {
                   site: 'review-repair',
                   project_cwd: cwd,
@@ -3844,11 +4384,23 @@ export async function runBuild(featureCode, opts = {}) {
                 },
               });
               if (gateFixResult?.usage && typeof context.recordBuildUsage === 'function') {
-                try { context.recordBuildUsage(gateFixResult.usage); } catch { /* fail-open */ }
+                try {
+                  await context.recordBuildUsage(usagePayload(gateFixResult.usage, gateFixResult.usages), {
+                    stepId: gateStepId,
+                    source: 'gate_fixer',
+                    dispatchId: gateFixResult.dispatchIds?.primary,
+                  });
+                } catch { /* fail-open */ }
               }
             } catch (err) {
               if (err?.usage && typeof context.recordBuildUsage === 'function') {
-                try { context.recordBuildUsage(err.usage); } catch { /* fail-open */ }
+                try {
+                  await context.recordBuildUsage(usagePayload(err.usage, err.usages), {
+                    stepId: gateStepId,
+                    source: 'gate_fixer',
+                    dispatchId: err.dispatchId,
+                  });
+                } catch { /* fail-open */ }
               }
               if (!(err instanceof AgentTimeoutError)) throw err;
               console.warn('\n⚠ Review fixer timed out');
@@ -4015,6 +4567,9 @@ export async function runBuild(featureCode, opts = {}) {
     }
 
     // Flow complete — write terminal state (file retained per STRAT-COMP-4 contract).
+    // COMP-COMPLETION-GATE slice 2: set when the flow completed and the feature is
+    // eligible to be completed — the actual completion runs after the health gate.
+    let pendingCompletion = null;
     if (response.status === 'completed') buildStatus = 'complete';
     if ((response.status === 'failed' || response.status === 'budget_exhausted') && !killedByGate) {
       buildStatus = 'failed';
@@ -4022,20 +4577,19 @@ export async function runBuild(featureCode, opts = {}) {
     }
     if (response.status === 'completed' && buildStatus === 'complete') {
       console.log('\nBuild complete.');
-      await visionWriter.updateItemStatus(itemId, 'complete');
-      // COMP-QA: persist filesChanged so `compose qa-scope` can read them post-build.
-      // Bug mode skips feature-json — bugs don't have feature.json (COMP-FIX-HARD T4).
-      if (cfg.tracksFeatureJson) {
-        const _bp = await getBuildProvider(cwd);
-        // Guard: feature.json may not exist when triage was skipped (test harnesses).
-        // Original updateFeature silently no-oped when feature was missing.
-        // Single atomic raw write (status + filesChanged together) — restores original
-        // updateFeature atomicity. persistFeatureRaw: no policy, no events, no roadmap.
-        const _feat = await _bp.getFeature(featureCode);
-        if (_feat) {
-          await _bp.persistFeatureRaw(featureCode, { ..._feat, status: 'COMPLETE', filesChanged: context.filesChanged ?? [] });
-        }
-      }
+      // COMP-COMPLETION-GATE slice 2: the COMPLETION does not happen here.
+      //
+      // This block used to flip the vision item and feature.json to COMPLETE
+      // immediately — but the health gate below can still downgrade the build to
+      // `failed`, and the guard ledger is append-only. Completing here meant a
+      // health-rejected build was left marked COMPLETE, and (once gated) the very
+      // first thing the ledger would ever durably attest would be a build the
+      // system itself then judged a failure.
+      //
+      // The health verdict is a PRECONDITION of completion, not its successor, so
+      // the completion is deferred to the gated block below, which runs after the
+      // health gate. See COMP-COMPLETION-GATE design §2.3c.
+      pendingCompletion = { itemId, featureCode };
       const termState = readActiveBuild(dataDir);
       if (termState) {
         writeActiveBuild(dataDir, { ...termState, status: 'complete', completedAt: new Date().toISOString() });
@@ -4095,16 +4649,29 @@ export async function runBuild(featureCode, opts = {}) {
           buildSignals.runtime_errors = [];
         }
 
-        // Doc freshness — check staleness of feature artifacts
+        // Doc freshness — derivation-based staleness (COMP-PROV-LINEAGE). An
+        // artifact is stale when an upstream it wasDerivedFrom is newer than it.
+        // This replaced the old phase-marker staleness reader (now removed),
+        // which read a `<!-- phase: -->` marker that no production writer ever
+        // emitted (a dead signal). findStaleArtifacts works off the canonical
+        // chain + mtimes, so it needs no marker to be written first.
         try {
-          const { checkStaleness } = await import('./staleness.js');
-          const currentPhase = stepHistory.length > 0
-            ? stepHistory[stepHistory.length - 1].stepId
-            : 'build';
-          const stalenessResults = checkStaleness(resolveItemDir(featureCode), currentPhase);
-          buildSignals.doc_freshness = stalenessResults;
+          const { findStaleArtifacts } = await import('./lineage.js');
+          buildSignals.doc_freshness = findStaleArtifacts(resolveItemDir(featureCode));
         } catch { /* staleness check is optional — skip on error */ }
 
+        // COMP-PROV-LINEAGE — populate PROV-O lineage markers on the canonical
+        // artifacts that now exist. This runs once per build, in the finalization
+        // pass after the dispatch loop, when the artifact set is complete. Build
+        // is the single writer here, so the read/write/utimes in stampFeatureLineage
+        // is uncontended. Idempotent and mtime-preserving, so it never resets the
+        // derivation clock that staleness reachability depends on. This is the
+        // lifecycle-writer surface that materialises wasGeneratedBy/wasDerivedFrom.
+        try {
+          const { stampFeatureLineage } = await import('./lineage.js');
+          stampFeatureLineage(resolveItemDir(featureCode));
+        } catch { /* lineage stamping is optional — skip on error */ }
+
         const healthSettings = (() => {
           try {
             if (existsSync(settingsPath)) {
@@ -4167,6 +4734,97 @@ export async function runBuild(featureCode, opts = {}) {
       }
     }
 
+    // ---------------------------------------------------------------------
+    // COMP-COMPLETION-GATE slice 2 — THE completion, and the only one.
+    //
+    // Runs here, after the health gate above may have downgraded buildStatus, so
+    // a health-rejected build completes nothing: no completion record, no
+    // COMPLETE status, no vision completion, no guard transition.
+    // ---------------------------------------------------------------------
+    if (pendingCompletion && buildStatus === 'complete') {
+      const ev = context.completionEvidence || {};
+      const acc = readBuildAccumulator(cwd, featureCode);
+      // Persisted, because it survives a resume; the in-memory value wins when
+      // this process ran the ship step itself.
+      const testsAttested = ev.testsAttested ?? acc?.tests_attested ?? 'no-signal';
+      const evidenceRoot = acc?.evidence_root || agentCwd;
+
+      // The SHA is resolved here rather than carried: at terminalization HEAD is
+      // the commit the build produced (or, on the already-committed path, found),
+      // and resolving it at the point of use keeps it verifiable instead of a
+      // stale claim threaded across a resume boundary.
+      let commitSha = ev.commitSha ?? null;
+      if (!commitSha) {
+        try {
+          commitSha = execSync('git rev-parse HEAD', {
+            cwd: evidenceRoot, encoding: 'utf-8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'],
+          }).trim() || null;
+        } catch { /* no repo — the no-repo exemption applies below */ }
+      }
+
+      if (cfg.tracksFeatureJson) {
+        const { completionGate, guardEnabled } = await import('./completion-gate.js');
+        // `capabilities.guard: false` is a deliberate opt-OUT, and the gate itself
+        // honors it (completion-gate.js §"Evidence, BEFORE the lock" / AC-5). This
+        // refusal has to sit INSIDE the same regime: enforcing attestation on an
+        // opted-out project would break every one of them — including non-git
+        // workspaces, where the evidence can never pass at all — which is exactly
+        // the reversal already made once during slice 1. An opted-out project keeps
+        // `deriveTestsPass`'s degrade contract: 'no-signal' reads as true there.
+        const guarded = guardEnabled(cwd);
+
+        // `no-signal` is not an attestation. Refusing here is the whole point of
+        // the tri-state: an unreadable test run must not become a passing claim
+        // on a permanent record.
+        if (guarded && testsAttested === 'no-signal') {
+          console.warn(
+            `[completion-gate] ${featureCode}: tests could not be attested (test output was ` +
+            `unreadable). Configure guard.testCommand in .compose/compose.json so the test run ` +
+            `itself attests, or record the completion explicitly. Build is complete; the feature ` +
+            `is NOT marked COMPLETE.`,
+          );
+        } else {
+          const gated = await completionGate({
+            featureCode,
+            commitSha,
+            testsPass: guarded ? testsAttested === 'passed' : testsAttested !== 'failed',
+            filesChanged: ev.filesChanged ?? context.filesChanged ?? [],
+            notes: ev.notes,
+            builtVia: ev.builtVia,
+            workspaceRoot: cwd,
+            evidenceRoot,
+            mode: resolveMode(mode),
+            // Slice 3: the gate owns the vision projection (§2.3a step 4) through
+            // the self-verifying seam; `updateItemStatus(…, 'complete')` refuses
+            // managed build items now (AC-16).
+            visionItemId: pendingCompletion.itemId,
+            visionProjector: ({ featureCode: fc, commitSha: sha, ledgerRef }) =>
+              visionWriter.completeItem(pendingCompletion.itemId, { featureCode: fc, cwd, commitSha: sha, ledgerRef }),
+          });
+          if (gated.ok) {
+            if (gated.partial) {
+              console.warn(
+                `[completion-gate] ${featureCode}: completed, but a projection failed — ` +
+                gated.failures.map(f => `${f.step}: ${f.message} (recover: ${f.recover})`).join('; '),
+              );
+            }
+          } else {
+            // Do NOT fail the build: the work is committed and the flow finished.
+            // But do not claim completion either — say plainly what was refused.
+            console.warn(
+              `[completion-gate] ${featureCode}: completion refused at ${gated.refusedAt} — ` +
+              `${(gated.reasons || []).join('; ')}. The build finished and the commit stands; ` +
+              `the feature is NOT marked COMPLETE.`,
+            );
+          }
+        }
+      } else {
+        // Bug/plan modes have no feature.json to gate on (COMP-FIX-HARD T4), and
+        // slice 1/2 are scoped to build mode — their completion path is unchanged.
+        await visionWriter.updateItemStatus(pendingCompletion.itemId, 'complete');
+      }
+    }
+
     // COMP-COCKPIT-3: archive the run to build-history.jsonl ONCE, here — after
     // the COMP-HEALTH gate above may have downgraded buildStatus to 'failed'.
     // Assembled from the in-memory build context for THIS run (never re-read
@@ -4487,6 +5145,35 @@ function judgmentCanonDriftError({ treeDrift, projectionDrift, recordDrift }) {
   return err;
 }
 
+/**
+ * Narrow an executeShipStep return value to the fields the TS engine's
+ * PhaseResult contract declares.
+ *
+ * COMP-SHIP-CONTRACT: engine contracts are STRICT Zod objects — any key the
+ * contract does not declare fails the step. executeShipStep's return carries
+ * caller-facing extras (`commit`, `filesChanged`, `testsAttested`,
+ * `test_count`/`pass_rate`, `error_code`) that Compose's own code consumes but
+ * PhaseResult never declared, so the raw object must NEVER be handed to
+ * stepDone as an `output`. Both sites that do so (runBuild, runGsd) go through
+ * here. Note runBuild's non-`ready` branch passes shipResult as the whole
+ * envelope rather than as `{output}` — a legacy shape that never reaches
+ * contract validation, deliberately left untouched.
+ *
+ * @param {object} shipResult  Return value from executeShipStep
+ * @returns {object}           `{phase, artifact, outcome, summary}` plus
+ *                             `files_changed`/`commit_hash` when present
+ */
+export function toPhaseResultOutput(shipResult) {
+  return {
+    phase: shipResult.phase,
+    artifact: shipResult.artifact,
+    outcome: shipResult.outcome,
+    summary: shipResult.summary,
+    ...(Array.isArray(shipResult.filesChanged) ? { files_changed: shipResult.filesChanged } : {}),
+    ...(typeof shipResult.commit === 'string' ? { commit_hash: shipResult.commit } : {}),
+  };
+}
+
 /**
  * Execute the ship step: run tests, stage feature files, commit.
  * Returns a PhaseResult-shaped object.
@@ -4509,7 +5196,35 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
   const builtVia = context?.templateName === 'build-quick' ? 'build-quick' : null;
 
   try {
-    // 0. Check if we're in a git repository — if not, skip git operations
+    // 0. Run tests FIRST — before the git-availability branch.
+    //
+    // COMP-COMPLETION-GATE slice 2: this used to live below, after the non-git
+    // branch had already returned. That meant a non-git build never ran tests at
+    // all and hard-coded `tests_pass: true` on its completion record. With the
+    // gate refusing an unattested completion, every non-git build would have been
+    // refused — and "no repo" is a reason to skip the COMMIT, never a reason to
+    // skip the tests. Both paths now attest identically.
+    if (progress) progress.toolUse('ship', 'Running tests...');
+    let testSummary = { test_count: 0, pass_rate: 0, parsed: false };
+    try {
+      // COMP-TEST-BOOTSTRAP item 128: use the detected test command, not a hard-coded `npm test`.
+      const testFramework = detectTestFramework(agentCwd);
+      const testCommand = testFramework?.command ?? 'npm test';
+      const testOutput = execSync(`${testCommand} 2>&1 || true`, { cwd: agentCwd, encoding: 'utf-8', timeout: 120_000 });
+      testSummary = parseTestSummary(testFramework?.framework, testOutput);
+    } catch { /* test runner unavailable or timed out — testSummary stays unparsed */ }
+    const testsPass = deriveTestsPass(testSummary);
+    // The gate's input: 'passed' | 'failed' | 'no-signal'. Unlike testsPass, an
+    // unreadable run does NOT become an attestation here.
+    const testsAttested = deriveTestsAttested(testSummary);
+    if (progress && testSummary.parsed) {
+      progress.toolUse('ship', `Tests: ${testSummary.test_count} run, ${testSummary.pass_rate}% passing`);
+    }
+    // Hand the evidence to terminalization, which is where completion now happens
+    // (after the health gate). The ship step no longer completes anything itself.
+    context.recordCompletionEvidence?.({ testsAttested, testSummary });
+
+    // 1. Check if we're in a git repository — if not, skip git operations
     let isGitRepo = false;
     try {
       execSync('git rev-parse --is-inside-work-tree', { cwd: agentCwd, encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
@@ -4518,56 +5233,20 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
 
     if (!isGitRepo) {
       // COMP-PATHS-EXTERNAL D6b: there is no repo to commit into (e.g. a
-      // forge-top-shaped workspace), but the lifecycle must still advance —
-      // record a commit-less completion (null-SHA) so status flips to COMPLETE.
-      // Best-effort: a completion failure must not fail ship.
-      let completionWarning = null;
-      if (featureCode) {
-        try {
-          const { recordCompletion } = await import('./completion-writer.js');
-          await recordCompletion(cwd, {
-            feature_code: featureCode,
-            // commit_sha omitted — non-git workspace, stamped with the null-SHA
-            // COMP-TEST-BOOTSTRAP-4: this path returns before the test run, so
-            // there is no parsed signal — degrade to true (no block).
-            tests_pass: true,
-            files_changed: [],
-            notes: description.split('\n')[0].slice(0, 72),
-            ...(builtVia ? { built_via: builtVia } : {}),
-          });
-        } catch (err) {
-          completionWarning = `completion record failed (${err.code || 'UNKNOWN'}): ${err.message}`;
-          // eslint-disable-next-line no-console
-          console.warn(`[build/ship] ${featureCode}: ${completionWarning}`);
-        }
-      }
+      // forge-top-shaped workspace). The lifecycle still advances, but the
+      // completion is now written at terminalization by the completion gate,
+      // AFTER the health verdict — not here. See COMP-COMPLETION-GATE §2.3c.
       return {
         phase: 'ship',
         artifact: 'no-git',
         outcome: 'complete',
-        summary: 'No git repository — wrote artifacts, recorded completion (commit skipped)',
+        summary: 'No git repository — wrote artifacts (commit skipped)',
         commit: null,
-        ...(completionWarning ? { completionWarning } : {}),
+        noRepo: true,
+        testsAttested,
       };
     }
 
-    // 1. Run feature-relevant tests (best-effort — don't block ship on test infra issues)
-    if (progress) progress.toolUse('ship', 'Running tests...');
-    // COMP-TEST-BOOTSTRAP-4: parse the run output into a structured signal and
-    // derive a real tests_pass for the completion attestation. Degrades to
-    // `true` (no block) whenever the output can't be parsed — see deriveTestsPass.
-    let testSummary = { test_count: 0, pass_rate: 0, parsed: false };
-    try {
-      // COMP-TEST-BOOTSTRAP item 128: use detected test command instead of hard-coded npm test
-      const testFramework = detectTestFramework(agentCwd);
-      const testCommand = testFramework?.command ?? 'npm test';
-      const testOutput = execSync(`${testCommand} 2>&1 || true`, { cwd: agentCwd, encoding: 'utf-8', timeout: 120_000 });
-      testSummary = parseTestSummary(testFramework?.framework, testOutput);
-    } catch { /* test runner not available or timed out — proceed (testSummary stays unparsed) */ }
-    const testsPass = deriveTestsPass(testSummary);
-    if (progress && testSummary.parsed) {
-      progress.toolUse('ship', `Tests: ${testSummary.test_count} run, ${testSummary.pass_rate}% passing`);
-    }
 
     // COMP-TRIAGE-5 (E3 Expand): if a lane-triaged feature fails its ship-time
     // test gate, escalate the lane so the NEXT build runs wider. Best-effort —
@@ -4806,33 +5485,23 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
     if (filesChanged.length === 0 && sha) filesChanged = stagedFiles;
     context.recordFilesChanged?.(filesChanged, { authoritativeShip: true });
 
-    // COMP-MCP-MIGRATION: write a commit-bound completion record via the
-    // typed writer. The writer flips feature.status to COMPLETE atomically
-    // and regenerates ROADMAP.md. Best-effort: completion failures must not
-    // downgrade the ship outcome since the commit itself succeeded.
-    let completionWarning = null;
-    if (sha && featureCode) {
-      try {
-        const { recordCompletion } = await import('./completion-writer.js');
-        await recordCompletion(cwd, {
-          feature_code: featureCode,
-          commit_sha: sha,
-          // COMP-TEST-BOOTSTRAP-4: derived from the parsed test run above
-          // (true when unparseable — never a false block).
-          tests_pass: testsPass,
-          files_changed: filesChanged,
-          notes: shortDesc,
-          ...(builtVia ? { built_via: builtVia } : {}),
-        });
-        if (progress) progress.toolUse('ship', `Recorded completion for ${featureCode}`);
-      } catch (err) {
-        completionWarning = err.code === 'STATUS_FLIP_AFTER_COMPLETION_RECORDED'
-          ? `completion recorded but status flip failed: ${err.message}`
-          : `completion record failed (${err.code || 'UNKNOWN'}): ${err.message}`;
-        // eslint-disable-next-line no-console
-        console.warn(`[build/ship] ${featureCode}: ${completionWarning}`);
-      }
-    }
+    // COMP-COMPLETION-GATE slice 2: the ship step no longer completes the feature.
+    //
+    // It used to call recordCompletion here, catch ANY failure, and still return
+    // a successful ship outcome — so a completion could fail silently and the
+    // build marched on regardless. Worse, the terminal block then wrote COMPLETE
+    // again independently, and the health gate that can fail the build runs AFTER
+    // both. A health-rejected build was left marked COMPLETE.
+    //
+    // Ship now collects evidence and stops. Exactly one completion happens, at
+    // terminalization, through the gate, after health. See §2.3, §2.3c.
+    context.recordCompletionEvidence?.({
+      commitSha: sha,
+      filesChanged,
+      notes: shortDesc,
+      builtVia,
+      testsAttested,
+    });
 
     // COMP-PATHS-EXTERNAL D6a: if ROADMAP / the feature folder resolved into a
     // DIFFERENT git repo, they were written but not committed here — tell the
@@ -4848,11 +5517,11 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
         : `Committed: ${commitMsg} (${stagedFiles.length} files)`,
       commit: sha,
       filesChanged,
+      testsAttested,
       // COMP-MODEL-AB: thread structured test counts into the step result so the
       // main loop can persist them to build-history.jsonl for metrics consumers.
       // Only present when testSummary.parsed=true (framework detected + output parsed).
       ...(testSummary.parsed ? { test_count: testSummary.test_count, pass_rate: testSummary.pass_rate } : {}),
-      ...(completionWarning ? { completionWarning } : {}),
     };
 
   } catch (err) {
@@ -5025,6 +5694,35 @@ async function pollGateResolution(visionWriter, gateId, intervalMs = 2000) {
  */
 export const MAX_GATE_REENTRIES = 20;
 
+/**
+ * Decide how a merge gate answers a consumer-merge failure.
+ *
+ * The first failure routes to the gate's repair path (`on_revise`, else kill).
+ * A failure that repeats BYTE-IDENTICALLY for the same gate is not going to be
+ * fixed by re-running the fan-out — the lanes reproduced the same conflict —
+ * so the gate kills instead of paying for another round. Anything different
+ * (a new code, a different file) is genuine progress and revises as before.
+ *
+ * @param {string|undefined} previousFailure - `${code}: ${message}` of the last failure at this gate
+ * @param {string} failure - this round's `${code}: ${message}`
+ * @param {'revise'|'kill'} repairOutcome - the gate's configured repair route
+ * @returns {{ outcome: 'revise'|'kill', rationale: string, repeated: boolean }}
+ */
+export function decideMergeRepairOutcome(previousFailure, failure, repairOutcome) {
+  const repeated = previousFailure !== undefined && previousFailure === failure;
+  if (repairOutcome === 'revise' && repeated) {
+    return {
+      outcome: 'kill',
+      repeated,
+      rationale: `${failure} — identical to the previous round's failure at this gate; `
+        + 'the fan-out reproduces the same conflict, so revising would only re-dispatch every '
+        + 'lane for the same result. Killed to stop spending. A killed build is not resumable: '
+        + 'fix the conflict (usually lanes editing the same file), then re-run with --fresh.',
+    };
+  }
+  return { outcome: repairOutcome, repeated, rationale: failure };
+}
+
 export function assertGateReentryWithinCap(count, stepId, cap = MAX_GATE_REENTRIES) {
   if (count > cap) {
     throw new Error(
@@ -5144,3 +5842,9 @@ export async function abortBuild(dataDir, featureCode, cwd, opts = {}) {
   }
   console.log('Build aborted.');
 }
+
+/** Optional revision failures keep the draft; only user control or uncertain teardown stops the build. */
+export function policyRevisionMustStop(error) {
+  return error instanceof UserInterruptError
+    || ['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(error?.code);
+}