@smartmemory/compose 0.3.6-beta → 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';
@@ -75,6 +80,8 @@ import {
   recoverAdvancedConsumerArtifacts,
   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.
@@ -96,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.
 // ---------------------------------------------------------------------------
@@ -444,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 : {};
@@ -563,6 +682,11 @@ function isStaleOrDuplicateConsumerReportError(error) {
     || /\bstep is not awaiting a client result\b/i.test(message);
 }
 
+function responseReissuesStep(response, stepId) {
+  if (response?.status !== 'ready' || !Array.isArray(response.ready)) return false;
+  return response.ready.some((ready) => ready?.id === stepId && ready?.previousFailure);
+}
+
 async function reportConsumerStepDone({
   descriptor,
   flowId,
@@ -614,6 +738,7 @@ async function reportConsumerStepDone({
       itemIndex: descriptor.itemIndex,
       stage: descriptor.stage,
       generation: descriptor.generation,
+      lane: deriveConsumerLane(descriptor, flowId),
     });
     return { response, skipped: true };
   }
@@ -780,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',
@@ -794,6 +925,7 @@ export async function runConsumerIssuance({
     itemIndex: descriptor.itemIndex,
     stage: descriptor.stage,
     generation: descriptor.generation,
+    lane,
   });
 
   let mainResult;
@@ -803,27 +935,40 @@ 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,
       confidenceGate: reviewOpts.confidenceGate,
       lens: reviewOpts.lens,
-      // 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).
+      telemetry: {
+        site: context.gsd ? 'gsd' : 'consumer',
+        project_cwd: context.projectCwd ?? context.cwd,
+        build_id: context.build_id,
+        feature_code: context.featureCode,
+        step_id: descriptor.id,
+        ...(typeof descriptor.attempt === 'number' ? { attempt: descriptor.attempt } : {}),
+      },
+      // 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
@@ -832,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);
     }
@@ -841,9 +990,11 @@ export async function runConsumerIssuance({
       mainResult = {
         result: { outcome: 'failed', summary: `Timed out after ${Math.round(error.durationMs / 1000)}s` },
         normalizationFailure: error.message,
+        dispatchIds: { primary: error.dispatchId ?? null, repair: null },
+        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
@@ -855,11 +1006,13 @@ export async function runConsumerIssuance({
       mainResult = {
         result: { outcome: 'failed', summary: `Agent error: ${reason}` },
         normalizationFailure: reason,
+        dispatchIds: { primary: error?.dispatchId ?? null, repair: null },
+        settlementFailureClass: 'agent',
         // F3: a failed run still consumed billable usage — the connector attaches
         // 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,
       };
     }
   }
@@ -868,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
@@ -899,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({
@@ -936,6 +1093,17 @@ export async function runConsumerIssuance({
   });
   if (report.skipped) return report.response;
   const { response } = report;
+  if (!context.gsd && typeof context?.settleDispatches === 'function') {
+    const isEnsureRetry = responseReissuesStep(response, descriptor.id);
+    context.settleDispatches({
+      stepId: descriptor.id,
+      dispatchIds: mainResult.dispatchIds,
+      accepted: !localFailure && !isEnsureRetry,
+      failureClass: mainResult.settlementFailureClass
+        ?? (normalizationFailure ? 'normalization' : (localFailure ? 'agent' : null)),
+      isEnsureRetry,
+    });
+  }
   if (typeof artifacts.hooks.afterStepDone === 'function') {
     await artifacts.hooks.afterStepDone({ descriptor, envelope, response });
   }
@@ -952,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;
 }
@@ -1037,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
@@ -1215,6 +1476,323 @@ function writeActiveBuild(dataDir, state) {
   renameSync(tmp, target);
 }
 
+// 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',
+  'feature_code',
+  'last_terminal',
+  'review_iterations',
+  'escalations',
+  'files_changed',
+  '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) {
+  if (typeof featureCode !== 'string' || featureCode.length === 0 || /[/\\]/.test(featureCode)) {
+    throw new Error('Build accumulator feature code must be a non-empty path-safe string');
+  }
+}
+
+export function buildAccumulatorPath(projectCwd, featureCode) {
+  assertFeatureCodeForAccumulator(featureCode);
+  return join(projectCwd, '.compose', 'data', 'build-accumulator', `${featureCode}.json`);
+}
+
+function validateBuildAccumulator(value, expectedFeatureCode = null) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Build accumulator is corrupt: expected an object');
+  }
+  for (const key of Object.keys(value)) {
+    if (!BUILD_ACCUMULATOR_FIELDS.has(key)) {
+      throw new Error(`Build accumulator is corrupt: unknown field "${key}"`);
+    }
+  }
+  for (const key of BUILD_ACCUMULATOR_FIELDS) {
+    if (!Object.hasOwn(value, key)) {
+      throw new Error(`Build accumulator is corrupt: missing field "${key}"`);
+    }
+  }
+  if (value.v !== BUILD_ACCUMULATOR_VERSION) {
+    throw new Error(`Build accumulator is corrupt: unsupported version ${value.v}`);
+  }
+  if (typeof value.build_id !== 'string' || !UUID_RE.test(value.build_id)) {
+    throw new Error('Build accumulator is corrupt: build_id must be a UUID');
+  }
+  if (typeof value.feature_code !== 'string' || value.feature_code.length === 0) {
+    throw new Error('Build accumulator is corrupt: feature_code must be a non-empty string');
+  }
+  if (expectedFeatureCode !== null && value.feature_code !== expectedFeatureCode) {
+    throw new Error(
+      `Build accumulator feature identity mismatch: expected ${expectedFeatureCode}, found ${value.feature_code}`,
+    );
+  }
+  if (![null, 'failed', 'complete', 'aborted'].includes(value.last_terminal)) {
+    throw new Error('Build accumulator is corrupt: invalid last_terminal');
+  }
+  for (const key of ['review_iterations', 'escalations']) {
+    if (!Number.isInteger(value[key]) || value[key] < 0) {
+      throw new Error(`Build accumulator is corrupt: ${key} must be a non-negative integer`);
+    }
+  }
+  if (!Array.isArray(value.files_changed) || !value.files_changed.every((file) => typeof file === 'string')) {
+    throw new Error('Build accumulator is corrupt: files_changed must be a string array');
+  }
+  if (value.ship_files_changed !== null
+    && (!Array.isArray(value.ship_files_changed)
+      || !value.ship_files_changed.every((file) => typeof file === 'string'))) {
+    throw new Error('Build accumulator is corrupt: ship_files_changed must be null or a string array');
+  }
+  for (const key of ['test_count', 'pass_rate']) {
+    if (value[key] !== null && (typeof value[key] !== 'number' || !Number.isFinite(value[key]))) {
+      throw new Error(`Build accumulator is corrupt: ${key} must be null or a finite number`);
+    }
+  }
+  for (const key of ['tokens_total', 'usd']) {
+    if (typeof value[key] !== 'number' || !Number.isFinite(value[key]) || value[key] < 0) {
+      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;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`Build accumulator is corrupt at ${path}: ${error.message}`);
+  }
+  return validateBuildAccumulator(migrateBuildAccumulator(parsed), featureCode);
+}
+
+export function writeBuildAccumulator(projectCwd, accumulator) {
+  validateBuildAccumulator(accumulator, accumulator?.feature_code ?? null);
+  const target = buildAccumulatorPath(projectCwd, accumulator.feature_code);
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, JSON.stringify(accumulator, null, 2));
+  renameSync(tmp, target);
+  return accumulator;
+}
+
+export function clearBuildAccumulator(projectCwd, featureCode) {
+  const path = buildAccumulatorPath(projectCwd, featureCode);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+export function newBuildAccumulatorRecord(featureCode) {
+  return {
+    v: BUILD_ACCUMULATOR_VERSION,
+    build_id: randomUUID(),
+    feature_code: featureCode,
+    last_terminal: null,
+    review_iterations: 0,
+    escalations: 0,
+    files_changed: [],
+    ship_files_changed: null,
+    test_count: null,
+    pass_rate: null,
+    tests_attested: 'no-signal',
+    evidence_root: null,
+    tokens_total: 0,
+    usd: 0,
+  };
+}
+
+export function createBuildAccumulator(projectCwd, featureCode) {
+  return writeBuildAccumulator(projectCwd, newBuildAccumulatorRecord(featureCode));
+}
+
+export function updateBuildAccumulator(projectCwd, featureCode, mutate) {
+  const current = readBuildAccumulator(projectCwd, featureCode);
+  if (!current) {
+    throw new Error(`Build accumulator not found for ${featureCode}`);
+  }
+  const next = typeof mutate === 'function' ? mutate({ ...current }) : { ...current, ...mutate };
+  validateBuildAccumulator(next, featureCode);
+  return writeBuildAccumulator(projectCwd, next);
+}
+
+export function selectBuildAccumulator(projectCwd, featureCode, { fresh = false } = {}) {
+  const existing = readBuildAccumulator(projectCwd, featureCode);
+  if (fresh || !existing || ['complete', 'aborted'].includes(existing.last_terminal)) {
+    // Candidate only — NOTHING persists until the caller owns the attempt. A
+    // concurrent live build may refuse this invocation, and persisting here
+    // (e.g. on --fresh) would clobber the live build's sidecar mid-run.
+    return { accumulator: newBuildAccumulatorRecord(featureCode), isNew: true };
+  }
+  return { accumulator: existing, isNew: false };
+}
+
+function ledgerEstimateSource(source) {
+  if (source === 'escalated') return 'escalated';
+  if (source === 'cached') return 'cached';
+  if (source === 'front' || source === 'refined' || source === 'fresh') return 'fresh';
+  throw new Error(`Unsupported triage estimate source "${source}"`);
+}
+
+export function emitTriageEstimate(projectCwd, estimate) {
+  return appendDispatchEvent(projectCwd, {
+    kind: 'triage-estimate',
+    build_id: estimate.build_id,
+    feature_code: estimate.feature_code,
+    tier: estimate.triageTier ?? estimate.tier,
+    lane: estimate.lane,
+    profile: estimate.profile,
+    estimate_source: ledgerEstimateSource(estimate.estimateSource ?? estimate.estimate_source),
+    confidence: estimate.triageConfidence ?? estimate.confidence ?? null,
+  });
+}
+
+export function emitBuildActuals(projectCwd, accumulator, terminalStatus) {
+  validateBuildAccumulator(accumulator, accumulator?.feature_code ?? null);
+  const persisted = readBuildAccumulator(projectCwd, accumulator.feature_code);
+  if (!persisted || persisted.build_id !== accumulator.build_id) {
+    throw new Error(`Build accumulator identity mismatch while finalizing ${accumulator.feature_code}`);
+  }
+  // COMP-TRIAGE-6-4: the ledger row is the durable, ACRR-consumed artifact —
+  // append it FIRST, then do the best-effort accumulator marker/clear. The row
+  // fields are all read from `persisted` (none depends on last_terminal), so
+  // this is byte-identical on the happy path. Row-first makes the two writes
+  // effectively atomic for every terminalization path (fresh, --fresh, resume,
+  // fresh-over-failed): a crash between them can leave a stale marker/sidecar
+  // (harmless — rotated away on the next build) but can NEVER lose a row or
+  // strand a `last_terminal='failed'` marker with no row behind it. Since
+  // emitBuildActuals is the ONLY writer of `last_terminal='failed'`, no other
+  // path can produce that orphan either.
+  const authoritativeShip = Array.isArray(persisted.ship_files_changed);
+  const files = authoritativeShip
+    ? persisted.ship_files_changed
+    : persisted.files_changed;
+  const row = appendDispatchEvent(projectCwd, {
+    kind: 'build-actuals',
+    build_id: persisted.build_id,
+    feature_code: persisted.feature_code,
+    terminal_status: terminalStatus,
+    files_changed_count: new Set(files).size,
+    files_source: authoritativeShip ? 'ship' : 'accumulated',
+    review_iterations: persisted.review_iterations,
+    escalations: persisted.escalations,
+    tokens_total: persisted.tokens_total,
+    usd: persisted.usd,
+    test_count: persisted.test_count,
+    pass_rate: persisted.pass_rate,
+  });
+  if (terminalStatus === 'failed') {
+    updateBuildAccumulator(projectCwd, persisted.feature_code, (current) => ({
+      ...current,
+      last_terminal: 'failed',
+    }));
+  } else if (terminalStatus === 'complete' || terminalStatus === 'aborted') {
+    clearBuildAccumulator(projectCwd, persisted.feature_code);
+  }
+  return row;
+}
+
+export function settleDispatches(projectCwd, buildId, stepId, {
+  dispatchIds,
+  accepted,
+  failureClass = null,
+  isEnsureRetry = false,
+  gsd = false,
+} = {}) {
+  if (gsd) return [];
+  const primary = dispatchIds?.primary;
+  const repair = dispatchIds?.repair;
+  // 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;
+    rows.push(appendDispatchEvent(projectCwd, {
+      kind: 'settlement',
+      dispatch_id: dispatchId,
+      accepted: isAccepted,
+      ...(typeof buildId === 'string' && buildId.length > 0 ? { build_id: buildId } : {}),
+      ...(typeof stepId === 'string' && stepId.length > 0 ? { step_id: stepId } : {}),
+      ...(!isAccepted ? { failure_class: rejectedClass ?? 'agent' } : {}),
+    }));
+  };
+
+  if (repair) {
+    appendSettlement(primary, false, 'normalization');
+    appendSettlement(
+      repair,
+      isEnsureRetry ? false : accepted === true,
+      isEnsureRetry ? 'ensure-retry' : failureClass,
+    );
+  } else {
+    appendSettlement(
+      primary,
+      isEnsureRetry ? false : accepted === true,
+      isEnsureRetry ? 'ensure-retry' : failureClass,
+    );
+  }
+
+  if (revision) {
+    appendSettlement(
+      revision,
+      isEnsureRetry ? false : accepted === true,
+      isEnsureRetry ? 'ensure-retry' : failureClass,
+    );
+  }
+  return rows;
+}
+
 /**
  * Decide how a compose build invocation should start.
  *
@@ -1379,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`;
@@ -1391,7 +1971,26 @@ function makeAskAgent(stratum, context, gateDispatch, gateExtras) {
       `${fileRef} this question concisely:\n\n` +
       `${question}\n\n` +
       `Keep your answer brief — 2-3 sentences max.`;
-    const text = await stratum.runAgentText('claude', qaPrompt, { cwd: context.cwd });
+    const text = await stratum.runAgentText('claude', qaPrompt, {
+      cwd: context.cwd,
+      telemetry: {
+        site: 'gate-qa',
+        project_cwd: context.projectCwd ?? context.cwd,
+        build_id: context.build_id,
+        feature_code: context.featureCode,
+        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)';
   };
 }
@@ -1441,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;
 }
 
@@ -1638,6 +2253,87 @@ export async function runBuild(featureCode, opts = {}) {
     return;
   }
 
+  const {
+    accumulator: selectedAccumulator,
+    isNew: isNewAccumulator,
+  } = selectBuildAccumulator(cwd, featureCode, { fresh: opts.fresh === true });
+  let build_id = selectedAccumulator.build_id;
+  // Tracks the record this attempt actually owns: the reused sidecar, the
+  // in-memory candidate (persisted at the ownership point after the start
+  // verdict), or the rotated record on a fresh-over-failed start.
+  let activeAccumulator = selectedAccumulator;
+  let accumulatorPersisted = !isNewAccumulator;
+  const buildStartedAt = new Date().toISOString();
+  let buildStatus = 'failed';
+  let attemptStarted = true;
+  let attemptFinalized = false;
+  // COMP-TRIAGE-6-4: function-scoped so finalizeBuildAttempt's ownership guard
+  // can read them (they are assigned/read from inside the main try below).
+  // accumulatorRotated flips true once a fresh-over-failed retry rotates to a
+  // new identity; isFreshStart defaults true until a resume verdict flips it.
+  let accumulatorRotated = false;
+  let isFreshStart = true;
+  let progress = null;
+  let stratum = null;
+  let streamWriter = null;
+  let signalHandler = null;
+  let runtimeResourcesFinalized = false;
+
+  const _priorBuildIdEnv = process.env.COMPOSE_BUILD_ID;
+  if (_priorBuildIdEnv !== undefined) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[build] COMPOSE_BUILD_ID was already set ("${_priorBuildIdEnv}") when runBuild started. ` +
+      `Overriding for this build; concurrent in-process builds will mis-stamp events.`
+    );
+  }
+  process.env.COMPOSE_BUILD_ID = build_id;
+  const _restoreBuildIdEnv = () => {
+    if (_priorBuildIdEnv === undefined) delete process.env.COMPOSE_BUILD_ID;
+    else process.env.COMPOSE_BUILD_ID = _priorBuildIdEnv;
+  };
+  const finalizeBuildAttempt = () => {
+    if (!attemptStarted || attemptFinalized) return;
+    const terminalStatus = buildStatus === 'complete'
+      ? 'complete'
+      : (buildStatus === 'killed' || buildStatus === 'aborted')
+        ? 'aborted'
+        : 'failed';
+    let accumulator = readBuildAccumulator(cwd, featureCode);
+    // A pre-ownership failure (e.g. missing lifecycle spec) dies before the
+    // candidate persists — write it now so the attempt still leaves a terminal
+    // actuals row. The build_id guard keeps a stale on-disk record from another
+    // identity from being finalized under this attempt's name.
+    if ((!accumulator || accumulator.build_id !== build_id) && !accumulatorPersisted) {
+      accumulator = writeBuildAccumulator(cwd, activeAccumulator);
+      accumulatorPersisted = true;
+    }
+    // A terminal complete/abort may already have cleared the sidecar if a nested
+    // terminalization path finalized first. The finalized flag is the primary
+    // guard; the missing-file/identity guard keeps cleanup idempotent.
+    //
+    // COMP-TRIAGE-6-4 ownership guard: a fresh (non-resume), not-yet-rotated
+    // attempt that reuses a prior record must not re-emit a terminal row that
+    // ALREADY EXISTS for this build_id. Without it, an attempt that dies before
+    // rotating to a fresh identity (rotateStaleAccumulatorForFreshStart) — e.g.
+    // the flow-audit probe throws while resolving the fresh/resume verdict —
+    // re-finalizes the reused failed record, double-counting in ACRR. The signal
+    // is the LEDGER itself, not the reused record's last_terminal: emitBuildActuals
+    // writes last_terminal and the row non-atomically, so a crash between them
+    // must cause neither a wrongful suppression (marker set, no row) nor a
+    // wrongful double-emit (row written, marker cleared). A genuine resume
+    // (isFreshStart=false) owns and continues the build (its second row under the
+    // same id is intended); a rotated/new identity owns a fresh, unemitted id.
+    const mayReemitReused = !isNewAccumulator && !accumulatorRotated && isFreshStart;
+    const alreadyEmitted = mayReemitReused
+      && readDispatchEvents(cwd, { kind: 'build-actuals' }).some((r) => r.build_id === build_id);
+    if (accumulator && accumulator.build_id === build_id && !alreadyEmitted) {
+      emitBuildActuals(cwd, accumulator, terminalStatus);
+    }
+    attemptFinalized = true;
+  };
+
+  try {
   // Single resolver — used at every site that previously hardcoded
   // `docs/features/<featureCode>/`. Callers must use this (not inline
   // string concatenation) so the bug-mode path stays in sync.
@@ -1660,29 +2356,6 @@ export async function runBuild(featureCode, opts = {}) {
     ? join(resolveFeaturesPath(cwd), code)
     : join(cwd, ...cfg.artifactRoot.split('/'), code);
 
-  // COMP-MCP-MIGRATION-1: per-build correlation ID stamped onto every audit
-  // row written during this run, so `executeShipStep`'s pre-stage scan can
-  // tell agent-emitted typed-tool events apart from anything else.
-  const build_id = randomUUID();
-  const buildStartedAt = new Date().toISOString();
-  const _priorBuildIdEnv = process.env.COMPOSE_BUILD_ID;
-  if (_priorBuildIdEnv !== undefined) {
-    // Concurrent in-process builds are not currently supported — env-based
-    // stamping cannot tell them apart. Warn loudly so the surrounding
-    // process tree picks it up; do not throw, since the prior env value
-    // may simply be inherited from the parent (CI, harness) and harmless.
-    // eslint-disable-next-line no-console
-    console.warn(
-      `[build] COMPOSE_BUILD_ID was already set ("${_priorBuildIdEnv}") when runBuild started. ` +
-      `Overriding for this build; concurrent in-process builds will mis-stamp events.`
-    );
-  }
-  process.env.COMPOSE_BUILD_ID = build_id;
-  const _restoreBuildIdEnv = () => {
-    if (_priorBuildIdEnv === undefined) delete process.env.COMPOSE_BUILD_ID;
-    else process.env.COMPOSE_BUILD_ID = _priorBuildIdEnv;
-  };
-
   const featureDir = resolveItemDir(featureCode);
 
   // Debug discipline (COMP-DEBUG-1)
@@ -1732,6 +2405,7 @@ export async function runBuild(featureCode, opts = {}) {
   // ---------------------------------------------------------------------------
   let buildProfile = null;
   let _buildTierLabel = '?'; // for skip_reason label in spec YAML mutation below
+  let triageEstimate = null;
   // Only modes that run feature triage do so — triage is feature-shaped (writes
   // feature.json, profile selection per complexity tiers). bug AND plan skip it.
   if (cfg.runsTriage && !opts.skipTriage && !opts.template) {
@@ -1746,6 +2420,15 @@ export async function runBuild(featureCode, opts = {}) {
       // Reuse cached profile
       buildProfile = cachedFeature.profile;
       _buildTierLabel = cachedFeature.complexity ?? '?';
+      triageEstimate = {
+        build_id,
+        feature_code: featureCode,
+        triageTier: cachedFeature.triageTier,
+        lane: cachedFeature.lane,
+        profile: cachedFeature.profile,
+        estimateSource: _escalated ? 'escalated' : 'cached',
+        triageConfidence: cachedFeature.triageConfidence ?? null,
+      };
       console.log(`[triage] Using ${_escalated ? 'escalated' : 'cached'} profile (tier ${_buildTierLabel}, lane ${cachedFeature.lane ?? '?'}): ${JSON.stringify(buildProfile)}`);
     } else {
       // COMP-TRIAGE-5 (E3 Estimate): derive the lane from the RAW REQUEST before
@@ -1763,10 +2446,21 @@ export async function runBuild(featureCode, opts = {}) {
       buildProfile = front.buildProfile;
       _buildTierLabel = front.tierLabel;
       cachedFeature = front.cachedFeature;
+      triageEstimate = {
+        build_id,
+        feature_code: featureCode,
+        triageTier: front.tier,
+        lane: front.lane,
+        profile: front.buildProfile,
+        estimateSource: 'fresh',
+        triageConfidence: front.confidence ?? null,
+      };
       console.log(`[triage] Front estimate lane=${front.lane} (tier ${front.tier}): ${front.rationale}`);
       console.log(`[triage] Profile: ${JSON.stringify(buildProfile)}`);
     }
   }
+  // Estimate emission is DEFERRED to the post-verdict ownership point: a
+  // refused/errored invocation must leave no orphan estimate (review r2).
 
   // Load lifecycle spec (template selection). The mode's defaultTemplate is the
   // fallback when no explicit --template is given (build → 'build', byte-identical
@@ -1782,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);
@@ -1883,11 +2586,14 @@ export async function runBuild(featureCode, opts = {}) {
   }
 
   // CLI progress renderer
-  const progress = new CliProgress();
+  progress = new CliProgress();
 
   // Stratum MCP client (test override permitted via opts.stratum)
-  const stratum = opts.stratum ?? new StratumMcpClient();
+  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).
@@ -1905,8 +2611,7 @@ export async function runBuild(featureCode, opts = {}) {
   }
 
   // Hoisted for finally-block visibility
-  let streamWriter = null;
-  let buildStatus = 'complete';
+  buildStatus = 'complete';
   let killedByGate = false;
   let terminalFailureReason = null;
   // I4: the last step the engine issued as `ready` (i.e. dispatched). When a flow
@@ -1924,17 +2629,25 @@ export async function runBuild(featureCode, opts = {}) {
   // and resets lenses_run, so the TRUE dirty lens (e.g. security) can be erased —
   // the gate persists from this, and only falls back to post-normalization findings.
   let lastReviewMergeDirtyLenses = [];
-  let signalHandler = null;
   let response;
   let stepHistory = [];
   const terminalHistoryWritten = { value: false };
   // COMP-OBS-COST: Accumulate token/cost totals across all steps (hoisted for finally-block)
   // On resume, seed from active-build.json to preserve pre-resume cost totals
-  const buildCostTotals = { input_tokens: 0, output_tokens: 0, cost_usd: 0 };
+  const buildCostTotals = {
+    input_tokens: 0,
+    output_tokens: selectedAccumulator.tokens_total,
+    cost_usd: selectedAccumulator.usd,
+  };
   // COMP-MODEL-AB: capture structured test counts from the ship step so they can
   // be persisted to build-history.jsonl for the metrics consumer (experiment-metrics.js).
   // Null when ship didn't run (failed/killed builds) or testSummary was unparsed.
-  let shipStepTestData = null;
+  let shipStepTestData = selectedAccumulator.test_count === null
+    ? null
+    : {
+        test_count: selectedAccumulator.test_count,
+        pass_rate: selectedAccumulator.pass_rate ?? 0,
+      };
 
   // COMP-OBS-GATES: accumulate tier pass/fail results for this build.
   // Keys are tier IDs (T0–T4), values are true (passed), false (failed), or null (not yet run).
@@ -1949,17 +2662,37 @@ export async function runBuild(featureCode, opts = {}) {
   // Accumulate contract compliance signal: array of { passed: bool } per ensure check
   const contractCompliance = [];
 
-  const priorActive = readActiveBuild(dataDir);
-  if (priorActive && priorActive.featureCode === featureCode && priorActive.status === 'running') {
-    if (typeof priorActive.total_input_tokens === 'number') buildCostTotals.input_tokens = priorActive.total_input_tokens;
-    if (typeof priorActive.total_output_tokens === 'number') buildCostTotals.output_tokens = priorActive.total_output_tokens;
-    if (typeof priorActive.cumulative_cost_usd === 'number') buildCostTotals.cost_usd = priorActive.cumulative_cost_usd;
-  }
+  // COMP-TRIAGE-6-4: on a fresh-over-failed retry the reused accumulator still
+  // carries the prior FAILED attempt's identity and counters. Rotate to a fresh
+  // record BEFORE the fallible startFresh (its plan() call can throw): otherwise
+  // a throw drops to finalizeBuildAttempt, which reads the OLD record still on
+  // disk under the reused build_id and emits a DUPLICATE build-actuals failed
+  // row with stale counters (double-count in ACRR). Rotating first means the
+  // throw finalizes the NEW record (distinct build_id, zeroed counters) instead.
+  // Idempotent: guarded so the post-startFresh ownership block cannot re-rotate.
+  // accumulatorRotated / isFreshStart are declared at function scope above so
+  // finalizeBuildAttempt's ownership guard can read them.
+  const rotateStaleAccumulatorForFreshStart = () => {
+    if (isNewAccumulator || accumulatorRotated) return;
+    activeAccumulator = createBuildAccumulator(cwd, featureCode);
+    accumulatorPersisted = true;
+    build_id = activeAccumulator.build_id;
+    process.env.COMPOSE_BUILD_ID = build_id;
+    buildCostTotals.input_tokens = 0;
+    buildCostTotals.output_tokens = 0;
+    buildCostTotals.cost_usd = 0;
+    shipStepTestData = null;
+    if (triageEstimate) {
+      triageEstimate.build_id = build_id;
+      emitTriageEstimate(cwd, triageEstimate);
+    }
+    accumulatorRotated = true;
+  };
 
   try {
     // Check for active build (resume)
     const active = readActiveBuild(dataDir);
-    let isFreshStart = true;
+    isFreshStart = true;
 
     // COMP-CODEX-IMPL: implementer/reviewer roles. A FRESH start derives them from
     // the flag (--codex flips Claude-implements/Codex-reviews → Codex/Claude); the
@@ -1991,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) => {
@@ -2083,8 +2836,13 @@ export async function runBuild(featureCode, opts = {}) {
         if (explicitResume) {
           throw new Error(`Nothing to resume for ${featureCode} (no in-progress or failed build found)`);
         }
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles, cwd);
+        // COMP-TRIAGE-6-4: claim fresh-ownership intent BEFORE rotating, so if
+        // rotation itself throws the finalize guard still treats this as a fresh
+        // start (isFreshStart=true) and suppresses re-finalizing the reused
+        // failed row. Rotation then swaps to a fresh identity before startFresh.
         isFreshStart = true;
+        rotateStaleAccumulatorForFreshStart();
+        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles, cwd);
       }
       if (!isFreshStart) {
         const stepId = response.ready?.[0]?.id;
@@ -2116,14 +2874,34 @@ export async function runBuild(featureCode, opts = {}) {
       }
     } else if (verdict.action === 'fresh') {
       if (activeForDecision?.flowId) console.log(`${verdict.reason}. Starting fresh.`);
+      // COMP-TRIAGE-6-4: rotate a reused failed identity before the fallible
+      // startFresh so a plan() throw cannot re-finalize the prior attempt.
+      rotateStaleAccumulatorForFreshStart();
       response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles, cwd);
     } else {
+      // A refused invocation never owned the accumulator — the ALIVE build does.
+      // Disown before throwing so the widened finally cannot finalize the other
+      // build's attempt as failed (spurious terminal row).
+      attemptStarted = false;
       const reason = verdict.reason.includes(featureCode)
         ? verdict.reason
         : verdict.reason.replace('Build already running', `Build already running for ${featureCode}`);
       throw new Error(reason);
     }
 
+    // Ownership point — the verdict resolved to resume or fresh (refuse/error
+    // threw above without persisting anything). The fresh-over-failed identity
+    // rotation now happens BEFORE startFresh (COMP-TRIAGE-6-4,
+    // rotateStaleAccumulatorForFreshStart), so only the brand-new candidate is
+    // persisted here. A new candidate is unaffected by that bug: a startFresh
+    // throw hits finalizeBuildAttempt's write-and-emit fallback under a distinct
+    // candidate id, never a duplicate row.
+    if (isNewAccumulator) {
+      writeBuildAccumulator(cwd, activeAccumulator);
+      accumulatorPersisted = true;
+      if (triageEstimate) emitTriageEstimate(cwd, triageEstimate);
+    }
+
     // COMP-CODEX-IMPL: verify Codex can write inside a detached git worktree (the
     // execute step's isolation primitive) before any step dispatches. Runs on the
     // EFFECTIVE role — after resume restoration above — so a resumed Codex build is
@@ -2132,9 +2910,15 @@ 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,
+        buildId: build_id,
+        featureCode,
         stratum,
         dataDir,
         ts: new Date().toISOString().replace(/[:.]/g, '-'),
@@ -2234,7 +3018,11 @@ export async function runBuild(featureCode, opts = {}) {
     })();
 
     const context = {
+      stratum,
+      flowId: response.runId,
+      receiptsMode,
       cwd: agentCwd,
+      projectCwd: cwd,
       featureCode,
       featureDir: resolveItemDir(featureCode),
       contextDir: contextDirPath,
@@ -2254,8 +3042,96 @@ export async function runBuild(featureCode, opts = {}) {
       // self-review suppression. Restored from active-build state on resume (above).
       implementerAgent,
       reviewerAgent,
+      filesChanged: [...activeAccumulator.files_changed],
       ...(isBugMode ? { bug_code: featureCode } : {}),
     };
+    context.recordBuildUsage = async (usage, meta) => {
+      if (!usage || typeof usage !== 'object') return;
+      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 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)
+        ? [...new Set(paths.filter((file) => typeof file === 'string' && file.length > 0))]
+        : [];
+      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+        ...accumulator,
+        ...(authoritativeShip
+          ? { ship_files_changed: normalized }
+          : { 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) => ({
+        ...accumulator,
+        test_count: metrics.test_count,
+        pass_rate: typeof metrics.pass_rate === 'number' ? metrics.pass_rate : 0,
+      }));
+    };
+    context.recordEscalation = () => {
+      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+        ...accumulator,
+        escalations: accumulator.escalations + 1,
+      }));
+    };
+    context.recordReviewIteration = () => {
+      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+        ...accumulator,
+        review_iterations: accumulator.review_iterations + 1,
+      }));
+    };
+    context.settleDispatches = ({ stepId, ...args } = {}) => settleDispatches(
+      cwd,
+      build_id,
+      stepId,
+      args,
+    );
+    context.onUsage = context.recordBuildUsage;
 
     let consumerArtifacts = null;
     const artifactsForRun = (runId, pins) => {
@@ -2287,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
@@ -2507,7 +3388,13 @@ export async function runBuild(featureCode, opts = {}) {
           // capture, shipStepTestData stays null for all real builds and appendBuildHistory
           // never persists test_count/pass_rate. Must mirror the generic path exactly.
           const _interceptedTestMetrics = _extractShipTestMetrics(shipResult);
-          if (_interceptedTestMetrics !== null) shipStepTestData = _interceptedTestMetrics;
+          if (Array.isArray(shipResult.filesChanged)) {
+            context.recordFilesChanged(shipResult.filesChanged, { authoritativeShip: true });
+          }
+          if (_interceptedTestMetrics !== null) {
+            shipStepTestData = _interceptedTestMetrics;
+            context.recordShipTestMetrics(_interceptedTestMetrics);
+          }
           stepHistory.push({
             stepId: 'ship',
             artifact: shipResult.artifact,
@@ -2582,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 }
@@ -2618,17 +3503,55 @@ export async function runBuild(featureCode, opts = {}) {
             `Fix step "${stepId}" — the previous attempt failed:\n` +
             `- ${failureReason}\n\nFix every issue, then return the step's expected result.`;
           try {
-            await runAndNormalize(undefined, fixPrompt, { ...stepDispatch, agent: fixAgent }, {
+            // The fixer's work is adjudicated by the retried step's own stepDone —
+            // no settlement here (its dispatch event still records the cost).
+            const fixResult = await runAndNormalize(undefined, fixPrompt, { ...stepDispatch, agent: fixAgent }, {
               progress,
               streamWriter,
               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,
+                build_id,
+                feature_code: featureCode,
+                step_id: stepId,
+                ...(typeof readyStep.attempt === 'number' ? { attempt: readyStep.attempt } : {}),
+              },
             });
+            if (fixResult?.usage && typeof context.recordBuildUsage === 'function') {
+              try {
+                await context.recordBuildUsage(usagePayload(fixResult.usage, fixResult.usages), {
+                  stepId,
+                  source: 'fixer',
+                  dispatchId: fixResult.dispatchIds?.primary,
+                });
+              } catch { /* fail-open */ }
+            }
           } catch (err) {
-            if (!(err instanceof AgentTimeoutError)) throw err;
-            console.warn(`\n⚠ Fix agent timed out on "${stepId}"`);
+            if (err?.usage && typeof context.recordBuildUsage === 'function') {
+              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}"`);
+            } else {
+              throw err;
+            }
           }
           progress.retry('build', stepId, readyStep.agent ?? response.agent ?? 'claude');
         }
@@ -2637,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
@@ -2678,29 +3603,161 @@ export async function runBuild(featureCode, opts = {}) {
             reviewMode: isReviewMain,
             confidenceGate: confGateMain,
             lens: response.inputs?.lens_name ?? response.lens_name ?? 'general',
+            telemetry: {
+              site: isReviewMain ? 'review' : 'build-step',
+              project_cwd: cwd,
+              build_id,
+              feature_code: featureCode,
+              step_id: stepId,
+              ...(typeof readyStep?.attempt === 'number' ? { attempt: readyStep.attempt } : {}),
+            },
             // D6/V4: apply this ordinary step's compose-side profile (e.g.
             // blueprint → claude::critical, review_merge → claude:orchestrator),
             // normalizing scoped subflow ready ids to the bare step id.
             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` } };
+              mainResult = {
+                text: '',
+                // `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}"`);
-              mainResult = { text: '', result: { outcome: 'failed', summary: `Retry requested by user` } };
+              mainResult = {
+                text: '',
+                result: { outcome: 'failed', summary: 'Retry requested by user' },
+                dispatchIds: { primary: err.dispatchId ?? null, repair: null },
+                settlementFailureClass: 'agent',
+                ...failedUsage,
+              };
             }
           } else if (err instanceof AgentTimeoutError) {
             console.warn(`\n⚠ Agent timed out on step "${stepId}" after ${Math.round(err.durationMs / 1000)}s`);
             streamWriter.write({ type: 'build_error', message: err.message, stepId });
-            mainResult = { text: '', result: { outcome: 'failed', summary: `Timed out after ${Math.round(err.durationMs / 1000)}s` } };
+            mainResult = {
+              text: '',
+              result: { outcome: 'failed', summary: `Timed out after ${Math.round(err.durationMs / 1000)}s` },
+              dispatchIds: { primary: err.dispatchId ?? null, repair: null },
+              settlementFailureClass: 'agent',
+              ...failedUsage,
+            };
           } else {
+            // Fatal rethrow bypasses the post-stepDone usage fold — bill the
+            // attempt's real cost to the accumulator before crashing.
+            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
@@ -2791,6 +3848,7 @@ export async function runBuild(featureCode, opts = {}) {
               const existing = new Set(context.filesChanged ?? []);
               for (const f of files) existing.add(f);
               context.filesChanged = [...existing];
+              context.recordFilesChanged(context.filesChanged);
             }
           } catch { /* git not available or no repo — skip */ }
         }
@@ -2804,7 +3862,14 @@ export async function runBuild(featureCode, opts = {}) {
         // so both paths produce identical shipStepTestData shapes.
         if (stepId === 'ship') {
           const _genericTestMetrics = _extractShipTestMetrics(result);
-          if (_genericTestMetrics !== null) shipStepTestData = _genericTestMetrics;
+          const genericShipFiles = result?.filesChanged ?? result?.files_changed;
+          if (Array.isArray(genericShipFiles)) {
+            context.recordFilesChanged(genericShipFiles, { authoritativeShip: true });
+          }
+          if (_genericTestMetrics !== null) {
+            shipStepTestData = _genericTestMetrics;
+            context.recordShipTestMetrics(_genericTestMetrics);
+          }
         }
 
         // Note: scope-step BuildProfile persistence has been replaced by pre-build triage.
@@ -2847,20 +3912,59 @@ 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,
         );
+        {
+          const isEnsureRetry = responseReissuesStep(response, stepId);
+          const failureClass = ownershipFailure
+            ? 'ownership'
+            : vocabularyFailure
+              ? 'vocabulary'
+              : normalizationFailure || (stepDispatch.has_out_contract && result == null)
+                ? 'normalization'
+                : mainResult.settlementFailureClass
+                  ?? (result?.outcome === 'failed' ? 'agent' : null);
+          context.settleDispatches({
+            stepId,
+            dispatchIds: mainResult.dispatchIds,
+            accepted: !isEnsureRetry && !blockingFailure && !normalizationFailure
+              && result?.outcome !== 'failed'
+              && (!stepDispatch.has_out_contract || result != null),
+            failureClass,
+            isEnsureRetry,
+          });
+        }
         syncStepHistory(dataDir, stepHistory);
 
         // COMP-FIX-HARD T6: record accepted hypothesis on diagnose success (bug mode only).
@@ -2934,7 +4038,19 @@ export async function runBuild(featureCode, opts = {}) {
 
         // COMP-FIX-HARD T10: post-retro_check escalation gate (bug mode only).
         if (stepId === 'retro_check' && context.mode === 'bug' && context.bug_code) {
-          await maybeRunEscalation(stratum, context, progress, streamWriter, attemptCounter, dataDir);
+          await maybeRunEscalation(
+            stratum,
+            {
+              ...context,
+              projectCwd: cwd,
+              step_id: stepId,
+              ...(typeof readyStep?.attempt === 'number' ? { attempt: readyStep.attempt } : {}),
+            },
+            progress,
+            streamWriter,
+            attemptCounter,
+            dataDir,
+          );
         }
 
         // Stream: step done — read retries/violations from active-build state
@@ -2942,16 +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;
-            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);
           }
@@ -3097,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);
@@ -3113,12 +4231,12 @@ export async function runBuild(featureCode, opts = {}) {
                     const files = new Set(context.filesChanged ?? []);
                     for (const file of changed.split('\n').filter(Boolean)) files.add(file);
                     context.filesChanged = [...files];
+                    context.recordFilesChanged(context.filesChanged);
                   }
                 } catch { /* best-effort build context projection */ }
               } catch (error) {
                 if (!(error instanceof ConsumerMergeDecisionError)) throw error;
-                outcome = repairOutcome;
-                rationale = `${error.code}: ${error.message}`;
+                repairFor(error);
               }
             }
           }
@@ -3204,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);
             }
@@ -3219,6 +4347,7 @@ export async function runBuild(featureCode, opts = {}) {
             stepHistory.push({ stepId: gateStepId, artifact: null, summary: 'Review gate: clean', outcome: resolved.outcome });
             syncStepHistory(dataDir, stepHistory);
           } else {
+            context.recordReviewIteration();
             // Persist the dirty lens ids so the revised triage re-runs only those.
             // J2: prefer the PRE-normalization dirty lenses (normalization resets
             // lenses_run and stamps a missing finding lens as 'general', which would
@@ -3242,11 +4371,37 @@ export async function runBuild(featureCode, opts = {}) {
               + (reviewResult.summary ? `\nSummary: ${reviewResult.summary}\n` : '')
               + findings.map((f) => `- ${f.file ?? '?'}:${f.line ?? '?'} [${f.lens ?? f.severity ?? ''}] ${f.finding ?? f.summary ?? ''}`).join('\n');
             try {
-              await runAndNormalize(undefined, fixPrompt, { step_id: 'review_fix', agent: fixAgent, flow_id: flowId }, {
+              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,
+                  build_id,
+                  feature_code: featureCode,
+                  step_id: 'review_fix',
+                  ...(typeof gateDispatch.attempt === 'number' ? { attempt: gateDispatch.attempt } : {}),
+                },
               });
+              if (gateFixResult?.usage && typeof context.recordBuildUsage === 'function') {
+                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 {
+                  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');
             }
@@ -3412,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';
@@ -3419,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() });
@@ -3492,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)) {
@@ -3564,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
@@ -3691,6 +4952,13 @@ export async function runBuild(featureCode, opts = {}) {
     }
     throw err;
   } finally {
+    let actualsError = null;
+    try {
+      finalizeBuildAttempt();
+    } catch (error) {
+      actualsError = error;
+      attemptFinalized = true;
+    }
     // Close stream writer with appropriate status (idempotent — signal handler may have already closed)
     if (streamWriter) {
       streamWriter.close(buildStatus, buildCostTotals);
@@ -3701,9 +4969,31 @@ export async function runBuild(featureCode, opts = {}) {
     }
     progress.finish();
     await stratum.close();
-    // COMP-MCP-MIGRATION-1: restore COMPOSE_BUILD_ID env to its prior value
-    // (or unset) so subsequent processes / tests don't inherit a stale UUID.
-    _restoreBuildIdEnv();
+    runtimeResourcesFinalized = true;
+    if (actualsError) throw actualsError;
+  }
+  } finally {
+    try {
+      finalizeBuildAttempt();
+    } finally {
+      try {
+        if (!runtimeResourcesFinalized) {
+          if (streamWriter) streamWriter.close(buildStatus);
+          if (signalHandler) {
+            process.removeListener('SIGINT', signalHandler);
+            process.removeListener('SIGTERM', signalHandler);
+          }
+          progress?.finish();
+          if (stratum) await stratum.close();
+          runtimeResourcesFinalized = true;
+        }
+      } finally {
+        // COMP-MCP-MIGRATION-1: restore COMPOSE_BUILD_ID env to its prior value
+        // (or unset) so subsequent processes / tests don't inherit a stale UUID.
+        _restoreBuildIdEnv();
+        attemptStarted = false;
+      }
+    }
   }
 }
 
@@ -3812,6 +5102,78 @@ export function _extractShipTestMetrics(shipResult) {
   return { test_count: shipResult.test_count, pass_rate: shipResult.pass_rate ?? 0 };
 }
 
+/** The guarded namespace — must equal the verifier's and the hook's (R2). */
+const JUDGMENT_TREE = 'docs/judgment';
+
+/**
+ * Run a git command and return its non-empty output lines.
+ *
+ * Deliberately does NOT swallow failures: this feeds the pre-commit judgment
+ * gate, where an unreadable git state must fail CLOSED. The caller's catch turns
+ * a throw into "verification errored; refusing to commit".
+ */
+function gitLines(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf-8', timeout: 5000 })
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function judgmentCanonDriftError({ treeDrift, projectionDrift, recordDrift }) {
+  const tiers = [
+    ['Tree drift', treeDrift],
+    ['Projection drift', projectionDrift],
+    // R1: records are covered by drift detection, not claimed as enforced.
+    ['Record drift detection', recordDrift],
+  ];
+  const sections = tiers
+    .filter(([, drift]) => drift.length > 0)
+    .map(([label, drift]) => {
+      const paths = drift.map((item) => {
+        if (typeof item === 'string') return `  - ${item}`;
+        return `  - ${item.path} [${item.kind}]`;
+      });
+      return `${label}:\n${paths.join('\n')}`;
+    });
+  const err = new Error(
+    `Judgment canon drift detected; refusing to commit.\n${sections.join('\n')}`,
+  );
+  err.code = 'JUDGMENT_CANON_DRIFT';
+  err.treeDrift = treeDrift;
+  err.projectionDrift = projectionDrift;
+  err.recordDrift = 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.
@@ -3834,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' });
@@ -3843,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 —
@@ -3906,6 +5260,7 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
         // the real feature dir even when opts.cwd differs from process.cwd().
         const _esc = await maybeEscalateLane({ featureCode, provider: _escProvider, featureDir: resolve(cwd, featureDir) });
         if (_esc.action === 'escalate') {
+          context.recordEscalation?.();
           console.warn(`[triage] Test gate failed on lane '${_esc.from}' — escalated to '${_esc.to}'. Re-run to execute the heavier phases.`);
         } else if (_esc.action === 'stop') {
           console.warn(`[triage] Test gate failed and escalation bound reached (lane '${_esc.lane}') — see escalation-checkpoint.md; human review needed.`);
@@ -4032,6 +5387,49 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
       } catch { /* file might not exist or already staged */ }
     }
 
+    // COMP-CANON-GUARD S5 T5: this verifier is deliberately build-independent
+    // and runs after staging so pre-staged judgment edits cannot slip through.
+    // This is a hard pre-commit gate: unlike best-effort metadata collection,
+    // unexpected verifier failures are rethrown and block the commit because
+    // silently passing would allow an unverified canon to ship.
+    //
+    // Scope boundary (whole-branch review): the canon verified is the WORKSPACE's
+    // (`cwd`). For a cross-repo build (`agentCwd !== cwd`) the commit lands in
+    // another repo, and that repo's own judgment canon — if it has one — is not
+    // verified here. The staged-divergence check below does run in `agentCwd`,
+    // against the tree actually being committed.
+    try {
+      // The verifier reads the WORKING TREE; `git commit` ships the INDEX. A canon
+      // file staged and then restored in the worktree therefore verifies GREEN while
+      // forged bytes go into the commit — a false GREEN, which is the one failure
+      // mode this whole slice exists to prevent. So before trusting the verdict,
+      // require that every STAGED guarded path matches the bytes about to be
+      // verified. A guarded path modified but NOT staged is not this case: it is not
+      // being committed, and worktree drift is what the verifier already covers.
+      const stagedGuarded = new Set(gitLines(['diff', '--cached', '--name-only', '--', JUDGMENT_TREE], agentCwd));
+      const worktreeGuarded = gitLines(['diff', '--name-only', '--', JUDGMENT_TREE], agentCwd);
+      const divergent = worktreeGuarded.filter((p) => stagedGuarded.has(p));
+      if (divergent.length > 0) {
+        throw judgmentCanonDriftError({
+          treeDrift: divergent.map((path) => ({ path, kind: 'staged-differs-from-worktree' })),
+          projectionDrift: [],
+          recordDrift: [],
+        });
+      }
+
+      const { verifyJudgmentCanon } = await import('./judgment-verify.js');
+      const verification = await verifyJudgmentCanon(cwd);
+      if (!verification.ok) throw judgmentCanonDriftError(verification);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(
+        err?.code === 'JUDGMENT_CANON_DRIFT'
+          ? `[ship] ${err.message}`
+          : `[ship] Judgment canon verification errored; refusing to commit: ${err.message}`,
+      );
+      throw err;
+    }
+
     // 4. Check if there's anything to commit
     const staged = execSync('git diff --cached --name-only', {
       cwd: agentCwd, encoding: 'utf-8', timeout: 5000,
@@ -4085,34 +5483,25 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
     } catch { /* metadata best-effort — leave [] */ }
     // If we got nothing from show, fall back to the staged list (still best-effort).
     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
@@ -4128,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) {
@@ -4141,6 +5530,7 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
       artifact: '',
       outcome: 'failed',
       summary: `Ship failed: ${err.message}`,
+      ...(typeof err?.code === 'string' ? { error_code: err.code } : {}),
     };
   }
 }
@@ -4304,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(
@@ -4417,5 +5836,15 @@ export async function abortBuild(dataDir, featureCode, cwd, opts = {}) {
 
   // Write terminal state (file retained per STRAT-COMP-4 contract)
   writeActiveBuild(dataDir, { ...active, status: 'aborted', completedAt: new Date().toISOString() });
+  const accumulator = readBuildAccumulator(cwd, active.featureCode);
+  if (accumulator) {
+    emitBuildActuals(cwd, accumulator, 'aborted');
+  }
   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);
+}