@smartmemory/compose 0.2.52-beta → 0.2.53-beta

package/lib/build.js

@@ -22,13 +22,14 @@ import { preflightCodexWorktreeProbe, codexProbeAbortMessage } from './codex-pre
 import { buildStepPrompt, buildRetryPrompt, buildGateContext, clearAmbientContextCache, formatBounceForPrompt } from './step-prompt.js';
 import { promptGate } from './gate-prompt.js';
 import { VisionWriter, ServerUnreachableError } from './vision-writer.js';
+import { readFlowRound } from './flow-state.js';
 import { resolvePort } from './resolve-port.js';
 import { probeServer } from './server-probe.js';
 import { CliProgress } from './cli-progress.js';
 import { BuildStreamWriter } from './build-stream-writer.js';
 import { appendBuildHistory, projectHistorySteps, stepOutcomeToStatus } from './build-history.js';
 import { KNOWN_VERSIONS } from './build-stream-schema.js';
-import { resolveAgentConfig } from './agent-string.js';
+import { resolveAgentConfig, parseAgentString } from './agent-string.js';
 import { installFactoryShim } from './connector-factory-shim.js';
 import { emitSections as emitPlanSections, appendTrailers as appendSectionTrailers, analyzeRollup, writeRollup } from './sections.js';
 import { SECTIONS_DIR } from './constants.js';
@@ -37,6 +38,7 @@ import { rtkPrefix } from './rtk.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 { vocabularyEnabled, injectVocabularyEnsure, tagVocabularyViolations } from './vocabulary-inject.js';
 
 // Lazy provider accessor — avoids circular import risk (factory → local-provider
@@ -114,6 +116,58 @@ export function parseRetriesCap(specYaml) {
   return cap;
 }
 
+// ---------------------------------------------------------------------------
+// COMP-ROADMAP-PLAN S8: gate the `ship` interception by mode.
+// ---------------------------------------------------------------------------
+
+/**
+ * The `ship` step interception runs executeShipStep (git stage/commit/audit),
+ * which is build/fix-specific. It must run for build AND bug (bug-fix depends on
+ * it) but NOT for plan — plan's `ship` is a handoff/verify agent step.
+ *
+ * Gate on `mode !== 'plan'`, NOT on cfg.tracksFeatureJson: fix mode is
+ * tracksFeatureJson:false yet still needs the ship path (COMP-ROADMAP-PLAN C12).
+ *
+ * @param {string} stepId — the current pipeline step id
+ * @param {string} mode   — runtime mode token (feature | bug | plan)
+ * @returns {boolean} true when the ship interception should run
+ */
+export function shouldInterceptShip(stepId, mode) {
+  return stepId === 'ship' && mode !== 'plan';
+}
+
+// ---------------------------------------------------------------------------
+// COMP-ROADMAP-PLAN S5: ratify a plan-authored design instead of clobbering it.
+// ---------------------------------------------------------------------------
+
+/**
+ * When a feature was authored by the `plan` lifecycle (feature.json.plannedBy is
+ * set), rewrite the build pipeline's `explore_design` step so it RATIFIES the
+ * existing plan-approved design.md rather than writing one from scratch (which
+ * would clobber the plan output). Mutates `specObj` in place; returns true if it
+ * rewrote a step. Pure and testable — no I/O.
+ *
+ * @param {object} specObj   — parsed Stratum spec
+ * @param {string} flowName  — the flow Stratum will run (from extractFlowName)
+ * @param {string|null} plannedBy — the originating plan session code, or null
+ * @returns {boolean} true when the explore_design intent was rewritten
+ */
+export function applyPlannedByRatify(specObj, flowName, plannedBy) {
+  if (!plannedBy) return false;
+  const flows = specObj?.flows ?? {};
+  const flowKey = Object.keys(flows).includes(flowName) ? flowName : Object.keys(flows)[0];
+  const steps = flows?.[flowKey]?.steps ?? [];
+  const step = steps.find((s) => s && s.id === 'explore_design');
+  if (!step) return false;
+  step.intent =
+    `A plan-approved design already exists at docs/features/{featureCode}/design.md ` +
+    `(authored by plan session ${plannedBy}). READ it fully FIRST, then RATIFY it: ` +
+    `refine only if something is missing, wrong, or unimplementable; otherwise keep it ` +
+    `as-is. Do NOT rewrite the design from scratch and do NOT discard the plan's intent. ` +
+    `Return the design path (docs/features/{featureCode}/design.md) in the "artifact" field.`;
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // COMP-FIX-HARD T6: hypothesis ledger append on diagnose success.
 // ---------------------------------------------------------------------------
@@ -421,6 +475,70 @@ function writeActiveBuild(dataDir, state) {
   renameSync(tmp, target);
 }
 
+/**
+ * Decide how a compose build invocation should start.
+ *
+ * Pure decision table for COMP-BUILD-RESUME. The caller is responsible for all
+ * I/O inputs: active-build state, pid liveness, flow terminality, and mode match.
+ *
+ * @param {object} params
+ * @param {object|null} params.active
+ * @param {object} params.opts
+ * @param {boolean} params.pidAlive
+ * @param {boolean} params.flowTerminal
+ * @param {boolean} params.sameMode
+ * @returns {{ action: 'resume'|'fresh'|'refuse'|'error', flowId?: string, reason: string }}
+ */
+export function decideBuildStart({ active, opts = {}, pidAlive = false, flowTerminal = false, sameMode = true } = {}) {
+  const wantsResume = Boolean(opts.resume || opts.resumeFlowId);
+  const wantsFresh = Boolean(opts.fresh);
+  const flowId = opts.resumeFlowId ?? active?.flowId;
+
+  if (wantsResume && wantsFresh) {
+    return { action: 'error', reason: '--resume and --fresh are mutually exclusive' };
+  }
+
+  // COMP-BUILD-RESUME: a BARE programmatic flow id (resumeFlowId without the
+  // `--resume` flag) is a self-sufficient resume target — the fix pipeline and
+  // crash recovery pass it directly. It does NOT depend on active-build.json:
+  // the caller resumes that exact flow and handles a terminal flow post-resume.
+  // The `--resume` *flag* (opts.resume) is the guard-subject path below: it
+  // discovers the flow from active-build state and errors if nothing is
+  // resumable. When BOTH are set (flag + explicit id) the flag wins and the
+  // guards apply, with resumeFlowId only supplying the id. So short-circuit
+  // here (after the mutual-exclusion guard) ONLY for the bare-id case.
+  if (opts.resumeFlowId && !opts.resume) {
+    return { action: 'resume', flowId: opts.resumeFlowId, reason: 'Resuming specified flow' };
+  }
+
+  if (!active || !flowId || flowTerminal) {
+    if (wantsResume) {
+      return { action: 'error', reason: 'Nothing to resume (no in-progress or failed build found)' };
+    }
+    return { action: 'fresh', reason: 'No resumable build found' };
+  }
+
+  if (!sameMode) {
+    if (wantsResume) {
+      return { action: 'error', reason: 'Nothing to resume for this mode (active build mode differs)' };
+    }
+    return { action: 'fresh', reason: 'Previous build mode differs' };
+  }
+
+  if (active.status === 'running' && pidAlive) {
+    return {
+      action: 'refuse',
+      reason: `Build already running${active.pid ? ` (pid ${active.pid})` : ''}. Use 'compose build --abort' to cancel it.`,
+    };
+  }
+
+  if (wantsFresh) {
+    return { action: 'fresh', reason: 'Fresh build requested' };
+  }
+
+  return { action: 'resume', flowId, reason: 'Resuming previous build' };
+}
+
 /**
  * COMP-MOBILE-1-1: persist a COMP-HEALTH gate downgrade back to
  * active-build.json. The terminal write happens BEFORE the health gate runs,
@@ -524,8 +642,12 @@ function isProcessAlive(pid) {
   try {
     process.kill(pid, 0); // signal 0 = existence check, no actual signal
     return true;
-  } catch {
-    return false;
+  } catch (err) {
+    // EPERM => the process exists but belongs to a different uid (e.g. a prior
+    // run under sudo) — it is alive. Returning false here let the concurrent-
+    // build guard treat a live process as dead and stomp active-build.json.
+    // Matches the authoritative pidAlive() in gsd-state.js.
+    return err.code === 'EPERM';
   }
 }
 
@@ -576,6 +698,13 @@ function isTerminalFlow(status) {
   return status === 'complete' || status === 'killed';
 }
 
+function isRecoverableFlowProbeError(err) {
+  return err?.code === 'flow_not_found'
+    || err?.code === 'STRATUM_ERROR'
+    || err?.message?.includes('No active flow')
+    || err?.message?.includes('flow_not_found');
+}
+
 // ---------------------------------------------------------------------------
 // Template resolution
 // ---------------------------------------------------------------------------
@@ -605,6 +734,101 @@ export function resolveTemplatePath(name, cwd) {
 // Main entry point
 // ---------------------------------------------------------------------------
 
+function buildFailureReason({ buildStatus = 'failed', stepHistory = [], healthDowngradeReason = null, fallback = null } = {}) {
+  if (fallback) return fallback;
+  if (buildStatus === 'complete') return null;
+  const lastFailedStep = [...stepHistory].reverse().find(s => s.outcome === 'failed');
+  return lastFailedStep?.summary ?? healthDowngradeReason ?? `Build ${buildStatus}`;
+}
+
+async function writeFailedBuildTerminalState({
+  cwd,
+  dataDir,
+  cfg,
+  visionWriter,
+  itemId,
+  featureCode,
+  flowId = null,
+  failureReason,
+}) {
+  const termState = readActiveBuild(dataDir);
+  if (termState) {
+    const sameFlow = !flowId || !termState.flowId || termState.flowId === flowId;
+    const sameFeature = !termState.featureCode || termState.featureCode === featureCode;
+    if (sameFlow && sameFeature) {
+      writeActiveBuild(dataDir, {
+        ...termState,
+        status: 'failed',
+        failureReason: termState.failureReason ?? failureReason,
+        completedAt: termState.completedAt ?? new Date().toISOString(),
+      });
+    }
+  }
+  if (cfg.tracksFeatureJson) {
+    const _bp = await getBuildProvider(cwd);
+    const _feat = await _bp.getFeature(featureCode);
+    if (_feat) {
+      // Raw write back to PLANNED — no transition policy, no events, no renderRoadmap.
+      // Matches original updateFeature semantics; keeps teardown side-effect-free.
+      await _bp.persistFeatureRaw(featureCode, { ..._feat, status: 'PLANNED' });
+    }
+  }
+  try {
+    await visionWriter.updateItemStatus(itemId, 'blocked');
+  } catch {
+    // Best-effort UI projection only; durable build/feature state is already written.
+  }
+}
+
+async function terminalizeThrownBuild({
+  cwd,
+  dataDir,
+  cfg,
+  visionWriter,
+  itemId,
+  featureCode,
+  mode,
+  response,
+  buildStartedAt,
+  buildCostTotals,
+  stepHistory,
+  failureReason,
+  historyWritten,
+}) {
+  const flowId = response?.flow_id ?? null;
+  if (!flowId) return false;
+  await writeFailedBuildTerminalState({
+    cwd,
+    dataDir,
+    cfg,
+    visionWriter,
+    itemId,
+    featureCode,
+    flowId,
+    failureReason,
+  });
+  if (!historyWritten.value) {
+    appendBuildHistory(dataDir, {
+      featureCode,
+      flowId,
+      mode,
+      status: 'failed',
+      startedAt: buildStartedAt,
+      completedAt: new Date().toISOString(),
+      durationMs: Date.now() - new Date(buildStartedAt).getTime(),
+      cost_usd: buildCostTotals.cost_usd,
+      input_tokens: buildCostTotals.input_tokens,
+      output_tokens: buildCostTotals.output_tokens,
+      stepCount: stepHistory.length,
+      failureReason,
+      itemId,
+      steps: projectHistorySteps(stepHistory),
+    });
+    historyWritten.value = true;
+  }
+  return true;
+}
+
 /**
  * Run a feature through the Stratum lifecycle.
  *
@@ -631,8 +855,14 @@ export async function runBuild(featureCode, opts = {}) {
   //                                  feature-json updates, plan with {featureCode, description}.
   //   mode === 'bug':                docs/bugs/<code>/, no feature-json updates,
   //                                  plan with {task: description}.
-  const mode = opts.mode === 'bug' ? 'bug' : 'feature';
+  // COMP-ROADMAP-MODES: 3-valued runner mode. The runtime token stays
+  // feature|bug|plan (byte-identical persistence in active-build.json and the
+  // resume guard); `cfg` is the registry's per-mode behavioral switches
+  // (getMode normalizes feature→build, bug→fix, plan→plan). isBugMode is kept as
+  // a derived flag so the bug-SPECIFIC positive checks downstream are untouched.
+  const mode = opts.mode === 'bug' ? 'bug' : (opts.mode === 'plan' ? 'plan' : 'feature');
   const isBugMode = mode === 'bug';
+  const cfg = getMode(mode).runner;
 
   // Resolve project paths
   const composeDir = join(cwd, '.compose');
@@ -658,9 +888,13 @@ export async function runBuild(featureCode, opts = {}) {
   //  - `resolveItemDir` resolves the actual FILESYSTEM dir via
   //    resolveFeaturesPath (absolute — handles absolute/../-escaping config).
   const featuresDir = loadFeaturesDir(cwd);
-  const resolveItemDir = (code) => isBugMode
-    ? join(cwd, 'docs', 'bugs', code)
-    : join(resolveFeaturesPath(cwd), code);
+  // The artifact dir is driven by the mode's `artifactRoot` token: 'features'
+  // resolves the (absolute, override-aware) features path; any other token is a
+  // literal repo-relative dir (bug → docs/bugs, plan → docs/plans). Byte-identical
+  // to the prior feature/bug ternary for those two modes.
+  const resolveItemDir = (code) => cfg.artifactRoot === 'features'
+    ? 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
@@ -734,9 +968,9 @@ export async function runBuild(featureCode, opts = {}) {
   // ---------------------------------------------------------------------------
   let buildProfile = null;
   let _buildTierLabel = '?'; // for skip_reason label in spec YAML mutation below
-  // Bug mode skips pre-build triage entirely — triage is feature-shaped
-  // (writes feature.json, profile selection per feature complexity tiers).
-  if (!isBugMode && !opts.skipTriage && !opts.template) {
+  // 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) {
     const _buildProvider = await getBuildProvider(cwd);
     let cachedFeature = await _buildProvider.getFeature(featureCode);
     if (cachedFeature?.profile && !isTriageStale(cwd, featureCode, featuresDir)) {
@@ -777,9 +1011,11 @@ export async function runBuild(featureCode, opts = {}) {
     }
   }
 
-  // Load lifecycle spec (template selection)
-  const templateName = opts.template ?? 'build';
-  const specPath = resolveTemplatePath(opts.template, cwd);
+  // Load lifecycle spec (template selection). The mode's defaultTemplate is the
+  // fallback when no explicit --template is given (build → 'build', byte-identical
+  // since resolveTemplatePath also defaults undefined→'build'; plan → 'new').
+  const templateName = opts.template ?? cfg.defaultTemplate;
+  const specPath = resolveTemplatePath(templateName, cwd);
   if (!existsSync(specPath)) {
     throw new Error(`Lifecycle spec not found: ${specPath}`);
   }
@@ -795,7 +1031,18 @@ export async function runBuild(featureCode, opts = {}) {
   // so in-memory edits here don't trip verifyPipelineIntegrity (same pattern the
   // triage profile already relied on).
   const vocabOn = vocabularyEnabled(cwd, composeConfig);
-  if (buildProfile || vocabOn) {
+  // COMP-ROADMAP-PLAN S5: a plan-authored feature (feature.json.plannedBy) makes
+  // explore_design ratify the existing design instead of rewriting it. Read it
+  // independently of the triage block (whose provider is block-scoped) so the
+  // ratify fires even on --skip-triage / explicit-template builds.
+  let plannedBy = null;
+  if (mode === 'feature') {
+    try {
+      const _ratifyProvider = await getBuildProvider(cwd);
+      plannedBy = (await _ratifyProvider.getFeature(featureCode))?.plannedBy ?? null;
+    } catch { /* best-effort — no ratify if unreadable */ }
+  }
+  if (buildProfile || vocabOn || plannedBy) {
     try {
       const specObj = YAML.parse(specYaml);
       if (buildProfile) {
@@ -821,6 +1068,7 @@ export async function runBuild(featureCode, opts = {}) {
       // STRAT-VOCAB-3: append vocabulary_compliance to the EXECUTED flow's review
       // step (extractFlowName resolves the same flow Stratum will run).
       if (vocabOn) injectVocabularyEnsure(specObj, extractFlowName(specYaml, templateName));
+      if (plannedBy) applyPlannedByRatify(specObj, extractFlowName(specYaml, templateName), plannedBy);
       specYaml = YAML.stringify(specObj);
     } catch (err) {
       // Non-fatal — fall back to unmodified spec
@@ -832,14 +1080,15 @@ export async function runBuild(featureCode, opts = {}) {
   // Stratum doesn't enforce `retries`; Compose force-terminates when iterN exceeds the cap.
   const retriesCap = parseRetriesCap(specYaml);
 
-  // Build description from feature/bug folder
-  const description = opts.description ?? (isBugMode
+  // Build description from the mode's folder. The bug loader reads docs/bugs;
+  // every other mode uses the feature loader (byte-identical for feature/bug).
+  const description = opts.description ?? (cfg.descriptionLoader === 'bug'
     ? loadBugDescription(featureDir, featureCode)
     : loadFeatureDescription(featureDir, featureCode));
 
   // Vision writer — thread mode so a UI-created bug item binds as type:bug
   // (and a brand-new fallback item is created with the right type) (#31).
-  const visionWriter = new VisionWriter(dataDir);
+  const visionWriter = opts.visionWriter ?? new VisionWriter(dataDir);
   const itemId = await visionWriter.ensureFeatureItem(featureCode, featureCode, mode);
 
   // Load policy settings (lazy from disk — works for all callers)
@@ -877,9 +1126,9 @@ export async function runBuild(featureCode, opts = {}) {
     installFactoryShim(stratum, opts.connectorFactory, agentCwd);
   }
 
-  // Update feature.json status to IN_PROGRESS (feature mode only;
-  // bug mode does not use feature.json).
-  if (!isBugMode) {
+  // Update feature.json status to IN_PROGRESS (only modes that track
+  // feature.json lifecycle status; bug AND plan do not).
+  if (cfg.tracksFeatureJson) {
     const _bp = await getBuildProvider(cwd);
     // Guard: feature.json may not exist if triage was skipped AND no prior
     // createFeature ran (e.g. test harnesses that only create the folder).
@@ -896,9 +1145,16 @@ export async function runBuild(featureCode, opts = {}) {
   let streamWriter = null;
   let buildStatus = 'complete';
   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 };
+  // 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;
 
   // 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).
@@ -923,7 +1179,6 @@ export async function runBuild(featureCode, opts = {}) {
   try {
     // Check for active build (resume)
     const active = readActiveBuild(dataDir);
-    let response;
     let isFreshStart = true;
 
     // COMP-CODEX-IMPL: implementer/reviewer roles. A FRESH start derives them from
@@ -939,6 +1194,23 @@ export async function runBuild(featureCode, opts = {}) {
     // (Codex impl-review finding #1).
     let implementerAgent = opts.codex ? 'codex' : 'claude';
     let reviewerAgent = opts.codex ? 'claude' : 'codex';
+    // COMP-MODEL-AB: explicit --implementer/--reviewer override --codex-derived defaults.
+    // Validated in bin/compose.js before reaching here; validate again for programmatic
+    // callers that bypass the CLI (unknown provider = hard error).
+    if (opts.implementer != null) {
+      const { provider } = parseAgentString(opts.implementer);
+      if (!['claude', 'codex'].includes(provider)) {
+        throw new Error(`Invalid implementer agent string "${opts.implementer}": unknown provider "${provider}"`);
+      }
+      implementerAgent = opts.implementer;
+    }
+    if (opts.reviewer != null) {
+      const { provider } = parseAgentString(opts.reviewer);
+      if (!['claude', 'codex'].includes(provider)) {
+        throw new Error(`Invalid reviewer agent string "${opts.reviewer}": unknown provider "${provider}"`);
+      }
+      reviewerAgent = opts.reviewer;
+    }
     const roles = { implementerAgent, reviewerAgent };
     // Restore persisted roles when (and only when) a resume actually happens.
     const restoreRolesFromActive = (src) => {
@@ -953,104 +1225,91 @@ export async function runBuild(featureCode, opts = {}) {
       reviewerAgent = src.reviewerAgent ?? reviewerAgent;
     };
 
-    // COMP-FIX-HARD T8: explicit `--resume` flag (compose fix <code> --resume).
-    // When opts.resumeFlowId is set, skip stratum.plan entirely and resume the
-    // given flow. CLI validates the flowId belongs to this code before calling.
-    if (opts.resumeFlowId) {
-      // Re-read active state to verify ownership before clobbering — prevents
-      // two concurrent `compose fix --resume` invocations from racing on
-      // active-build.json. If another live process owns it, refuse to resume.
-      const activeNow = readActiveBuild(dataDir);
-      if (activeNow && activeNow.pid && activeNow.pid !== process.pid && isProcessAlive(activeNow.pid)) {
-        throw new Error(
-          `Cannot --resume: another live process (pid ${activeNow.pid}) owns the build for ${featureCode}.`
-        );
-      }
-      // Verify the active build matches the mode the caller asserts. Without
-      // this check, `compose fix CODE --resume` against a feature build with
-      // the same code would silently resume a feature flow as a bug flow.
-      if (activeNow && activeNow.mode && activeNow.mode !== mode) {
-        throw new Error(
-          `Cannot --resume: active build is in ${activeNow.mode} mode, but caller invoked ${mode} mode.`
-        );
+    const activeForDecision = active && active.featureCode === featureCode ? active : null;
+    const pidAlive = Boolean(
+      activeForDecision?.status === 'running'
+      && activeForDecision.pid
+      && activeForDecision.pid !== process.pid
+      && isProcessAlive(activeForDecision.pid)
+    );
+    const sameMode = !activeForDecision?.mode || activeForDecision.mode === mode;
+    let flowTerminal = !activeForDecision?.flowId;
+    if (activeForDecision?.flowId && ['complete', 'aborted', 'killed'].includes(activeForDecision.status)) {
+      flowTerminal = true;
+    } else if (activeForDecision?.flowId && !pidAlive) {
+      try {
+        const audit = await stratum.audit(activeForDecision.flowId);
+        flowTerminal = isTerminalFlow(audit?.status);
+      } catch (err) {
+        if (isRecoverableFlowProbeError(err)) {
+          flowTerminal = true;
+        } else {
+          throw err;
+        }
       }
-      console.log(`Resuming flow ${opts.resumeFlowId} for ${featureCode}...`);
-      response = await stratum.resume(opts.resumeFlowId);
-      isFreshStart = false;
-      // COMP-CODEX-IMPL: this is a real resume — restore roles from persisted state
-      // (the refresh-write below then persists the restored roles, not flag-derived).
-      restoreRolesFromActive(activeNow);
-      // Refresh active-build.json so streaming/UI sees this as the live build.
-      const flowName = extractFlowName(specYaml, templateName);
-      writeActiveBuild(dataDir, {
-        featureCode,
-        flowId: response.flow_id ?? opts.resumeFlowId,
-        pipeline: flowName,
-        mode,
-        pid: process.pid,
-        currentStepId: response.step_id,
-        specPath: `pipelines/${templateName}.stratum.yaml`,
-        stepNum: response.step_number ?? 1,
-        totalSteps: response.total_steps ?? null,
-        retries: 0,
-        violations: [],
-        status: 'running',
-        resumedAt: new Date().toISOString(),
-        // COMP-CODEX-IMPL: carry the (restored or default) roles forward on resume-refresh.
-        implementerAgent,
-        reviewerAgent,
-      });
-    } else if (active && active.featureCode === featureCode && active.flowId) {
-      // Same feature — try to resume or start fresh
-      // Refuse implicit resume across modes: a stale bug-mode active-build
-      // with the same code as a feature build (or vice versa) would otherwise
-      // resume the wrong flow shape. Only blocks when active.mode is set
-      // (legacy active-build.json files predate the field).
-      if (active.mode && active.mode !== mode) {
-        console.log(
-          `Previous build for ${featureCode} was in ${active.mode} mode, ` +
-          `current invocation is ${mode} mode. Starting fresh.`
-        );
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
-      } else if (active.status && active.status !== 'running') {
-        console.log(`Previous build ${active.status}. Starting fresh.`);
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
-      } else if (active.pid && active.pid !== process.pid && isProcessAlive(active.pid)) {
-        // Same feature, different live process — block
-        throw new Error(
-          `Build already running for ${featureCode} (pid ${active.pid}). ` +
-          `Use 'compose build --abort' to cancel it.`
-        );
-      } else {
-        console.log(`Found previous build for ${featureCode} (flow: ${active.flowId})`);
-        try {
-          response = await stratum.resume(active.flowId);
-          if (isTerminalFlow(response.status)) {
-            console.log(`Previous build already ${response.status}. Starting fresh.`);
-            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
-          } else {
-            console.log(`Resuming from step: ${response.step_id}`);
-            isFreshStart = false;
-            // COMP-CODEX-IMPL: real resume — restore roles from the persisted build.
-            restoreRolesFromActive(active);
-          }
-        } catch (err) {
-          const recoverable = err?.code === 'flow_not_found'
-            || err?.code === 'STRATUM_ERROR'
-            || err?.message?.includes('No active flow');
-          if (recoverable) {
-            console.log('Previous flow not found. Starting fresh.');
-            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
-          } else {
-            throw err;
-          }
+    }
+
+    const verdict = decideBuildStart({
+      active: activeForDecision,
+      opts,
+      pidAlive,
+      flowTerminal,
+      sameMode,
+    });
+    isFreshStart = verdict.action === 'fresh';
+
+    if (verdict.action === 'resume') {
+      const flowId = verdict.flowId;
+      console.log(`Resuming flow ${flowId} for ${featureCode}...`);
+      response = await stratum.resume(flowId);
+      // A BARE programmatic resumeFlowId (no --resume flag) resumes the named
+      // flow as-is and proceeds — exactly as pre-COMP-BUILD-RESUME, which had no
+      // post-resume terminal check on this path. Only the --resume flag /
+      // auto-resume path re-evaluates terminality: a terminal resume response
+      // there means "nothing to resume" (flag → error, auto → start fresh).
+      const bareFlowResume = Boolean(opts.resumeFlowId && !opts.resume);
+      if (!bareFlowResume && isTerminalFlow(response.status)) {
+        const explicitResume = Boolean(opts.resume || opts.resumeFlowId);
+        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);
+        isFreshStart = true;
       }
-    } else {
-      // Different feature or no active build — start fresh.
-      // active-build.json is last-writer-wins: concurrent builds for
-      // different features are allowed; the UI shows the most recent.
+      if (!isFreshStart) {
+        console.log(`Resuming from step: ${response.step_id}`);
+        // COMP-CODEX-IMPL: this is a real resume — restore roles from persisted state
+        // (the refresh-write below then persists the restored roles, not flag-derived).
+        restoreRolesFromActive(activeForDecision);
+        // Refresh active-build.json so streaming/UI sees this as the live build.
+        const flowName = extractFlowName(specYaml, templateName);
+        writeActiveBuild(dataDir, {
+          featureCode,
+          flowId: response.flow_id ?? flowId,
+          pipeline: flowName,
+          mode,
+          pid: process.pid,
+          currentStepId: response.step_id,
+          specPath: `pipelines/${templateName}.stratum.yaml`,
+          stepNum: response.step_number ?? 1,
+          totalSteps: response.total_steps ?? null,
+          retries: 0,
+          violations: [],
+          status: 'running',
+          resumedAt: new Date().toISOString(),
+          // COMP-CODEX-IMPL: carry the (restored or default) roles forward on resume-refresh.
+          implementerAgent,
+          reviewerAgent,
+        });
+      }
+    } else if (verdict.action === 'fresh') {
+      if (activeForDecision?.flowId) console.log(`${verdict.reason}. Starting fresh.`);
       response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
+    } else {
+      const reason = verdict.reason.includes(featureCode)
+        ? verdict.reason
+        : verdict.reason.replace('Build already running', `Build already running for ${featureCode}`);
+      throw new Error(reason);
     }
 
     // COMP-CODEX-IMPL: verify Codex can write inside a detached git worktree (the
@@ -1074,7 +1333,7 @@ export async function runBuild(featureCode, opts = {}) {
         // terminal handlers run, so roll BOTH back here (mirrors the killed/failed
         // teardown) — otherwise a build that never dispatched a step strands stale
         // state (Codex impl-review findings).
-        if (!isBugMode) {
+        if (cfg.tracksFeatureJson) {
           try {
             const _bp = await getBuildProvider(cwd);
             const _feat = await _bp.getFeature(featureCode);
@@ -1127,7 +1386,7 @@ export async function runBuild(featureCode, opts = {}) {
 
     // Dispatch loop — agents operate in agentCwd (which may differ from cwd for cross-repo builds)
     // stepHistory accumulates context across steps so downstream steps don't re-explore
-    const stepHistory = [];
+    stepHistory = [];
     // COMP-MCP-MIGRATION: read enforcement.mcpForFeatureMgmt from settings.
     // When true, step-prompt.js injects a hard instruction telling the agent
     // to use typed MCP tools instead of free-text Edit/Write for ROADMAP /
@@ -1164,6 +1423,13 @@ export async function runBuild(featureCode, opts = {}) {
     };
 
 
+    // COMP-PLAN-GATE-LOOP: per-step gate re-entry counter. A `revise` that
+    // routes back through earlier steps re-enters the same gate; the round-aware
+    // gate id (below) keeps each re-entry a fresh pending gate, but this counter
+    // 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();
+
     while (response.status !== 'complete' && response.status !== 'killed') {
       const stepId = response.step_id;
       const flowId = response.flow_id;
@@ -1189,8 +1455,16 @@ export async function runBuild(featureCode, opts = {}) {
         // Ship step: run git commit in-process instead of delegating to a sandboxed agent.
         // The agent can't git commit (sandbox blocks it), so we do it here where we have
         // full shell access. This turns a 10+ minute spiral into a <5 second operation.
-        if (stepId === 'ship') {
+        // COMP-ROADMAP-PLAN S8: build/fix only — plan's `ship` falls through to the
+        // normal agent step (handoff/verify), never executeShipStep.
+        if (shouldInterceptShip(stepId, mode)) {
           const shipResult = await executeShipStep(featureCode, agentCwd, cwd, context, description, progress);
+          // COMP-MODEL-AB fix B: capture test counts here, in the interception branch that
+          // `continue`s before the generic step-completion path at ~1703. Without this
+          // 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;
           stepHistory.push({
             stepId: 'ship',
             artifact: shipResult.artifact,
@@ -1432,6 +1706,15 @@ export async function runBuild(featureCode, opts = {}) {
         stepHistory.push(entry);
         progress.stepDone(stepId);
 
+        // COMP-MODEL-AB: capture test counts from ship step for build-history persistence.
+        // Generic path (non-intercepted ship / plan mode ship-as-agent). Mirrors the
+        // ship-interception capture above; uses the same _extractShipTestMetrics helper
+        // so both paths produce identical shipStepTestData shapes.
+        if (stepId === 'ship') {
+          const _genericTestMetrics = _extractShipTestMetrics(result);
+          if (_genericTestMetrics !== null) shipStepTestData = _genericTestMetrics;
+        }
+
         // Note: scope-step BuildProfile persistence has been replaced by pre-build triage.
         // runTriage() runs before stratum_plan() and populates feature.json directly.
 
@@ -1584,6 +1867,12 @@ export async function runBuild(featureCode, opts = {}) {
       } else if (response.status === 'await_gate') {
         updateActiveBuildStep(dataDir, stepId);
 
+        // COMP-PLAN-GATE-LOOP: trip the backstop before doing any gate work if
+        // this step has re-entered its gate too many times without converging.
+        const gateReentryCount = (gateReentries.get(stepId) ?? 0) + 1;
+        gateReentries.set(stepId, gateReentryCount);
+        assertGateReentryWithinCap(gateReentryCount, stepId);
+
         // Gate enrichment extras for STRAT-COMP-6
         const gateExtras = {
           fromPhase: response.from_phase ?? null,
@@ -1642,8 +1931,16 @@ export async function runBuild(featureCode, opts = {}) {
           const serverUp = await probeServer();
           let outcome, rationale;
 
+          // COMP-PLAN-GATE-LOOP: thread Stratum's current round into the gate id
+          // so a `revise` re-entry mints a fresh `<flowId>:<stepId>:<round>` gate
+          // (pending) instead of colliding with the prior resolved gate and
+          // replaying its stale outcome. Stratum tracks the round in the flow
+          // state but omits it from the await_gate dispatch, so read it from the
+          // persisted flow file (fail-open to round 1 if unreadable).
+          const round = readFlowRound(flowId);
+
           if (serverUp) {
-            const gateId = await visionWriter.createGate(flowId, stepId, itemId, { ...gateExtras, policyMode: 'gate' });
+            const gateId = await visionWriter.createGate(flowId, stepId, itemId, { ...gateExtras, policyMode: 'gate', round });
             console.log('Gate delegated to web UI. Waiting for resolution...');
             const resolved = await pollGateResolution(visionWriter, gateId);
             if (resolved) {
@@ -1662,7 +1959,7 @@ export async function runBuild(featureCode, opts = {}) {
               try { await visionWriter._restResolveGate(gateId, outcome); } catch { /* ignore */ }
             }
           } else {
-            const gateId = await visionWriter.createGate(flowId, stepId, itemId, { ...gateExtras, policyMode: 'gate' });
+            const gateId = await visionWriter.createGate(flowId, stepId, itemId, { ...gateExtras, policyMode: 'gate', round });
             const result = await promptGate(response, {
               ...(opts.gateOpts ?? {}),
               artifact: context.cwd,
@@ -2127,7 +2424,7 @@ export async function runBuild(featureCode, opts = {}) {
       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 (!isBugMode) {
+      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.
@@ -2147,7 +2444,7 @@ export async function runBuild(featureCode, opts = {}) {
       buildStatus = 'killed';
       console.log('\nBuild killed.');
       await visionWriter.updateItemStatus(itemId, 'killed');
-      if (!isBugMode) {
+      if (cfg.tracksFeatureJson) {
         const _bp = await getBuildProvider(cwd);
         const _feat = await _bp.getFeature(featureCode);
         if (_feat) {
@@ -2163,20 +2460,16 @@ export async function runBuild(featureCode, opts = {}) {
     } else if (buildStatus === 'failed') {
       // Ship failure or other explicit failure — write terminal state
       console.log('\nBuild failed.');
-      await visionWriter.updateItemStatus(itemId, 'failed');
-      if (!isBugMode) {
-        const _bp = await getBuildProvider(cwd);
-        const _feat = await _bp.getFeature(featureCode);
-        if (_feat) {
-          // Raw write back to PLANNED — no transition policy, no events, no renderRoadmap.
-          // Matches original updateFeature semantics; keeps teardown side-effect-free.
-          await _bp.persistFeatureRaw(featureCode, { ..._feat, status: 'PLANNED' });
-        }
-      }
-      const termState = readActiveBuild(dataDir);
-      if (termState) {
-        writeActiveBuild(dataDir, { ...termState, status: 'failed', completedAt: new Date().toISOString() });
-      }
+      await writeFailedBuildTerminalState({
+        cwd,
+        dataDir,
+        cfg,
+        visionWriter,
+        itemId,
+        featureCode,
+        flowId: response?.flow_id ?? null,
+        failureReason: buildFailureReason({ buildStatus, stepHistory }),
+      });
     } else {
       buildStatus = 'failed';
     }
@@ -2272,10 +2565,7 @@ export async function runBuild(featureCode, opts = {}) {
     // Assembled from the in-memory build context for THIS run (never re-read
     // active-build.json, which is last-writer-wins across concurrent builds).
     if (['complete', 'aborted', 'failed', 'killed'].includes(buildStatus)) {
-      const lastFailedStep = [...stepHistory].reverse().find(s => s.outcome === 'failed');
-      const failureReason = buildStatus === 'complete'
-        ? null
-        : (lastFailedStep?.summary ?? healthDowngradeReason ?? `Build ${buildStatus}`);
+      const failureReason = buildFailureReason({ buildStatus, stepHistory, healthDowngradeReason });
       appendBuildHistory(dataDir, {
         featureCode,
         flowId: response?.flow_id ?? null,
@@ -2293,7 +2583,11 @@ export async function runBuild(featureCode, opts = {}) {
         // COMP-MOBILE-1-1: compact per-step results so history consumers can
         // render which-step-failed without the live active-build state.
         steps: projectHistorySteps(stepHistory),
+        // COMP-MODEL-AB: structured test counts from ship step — present only when
+        // the build ran tests and the framework output was parseable.
+        ...(shipStepTestData !== null ? shipStepTestData : {}),
       });
+      terminalHistoryWritten.value = true;
     }
 
     // COMP-OBS-GATES: emit gate_tier_summary and persist savings on build completion
@@ -2343,7 +2637,7 @@ export async function runBuild(featureCode, opts = {}) {
           join(featureDir, 'audit.json'),
           JSON.stringify(response, null, 2)
         );
-        console.log(`Audit trace written to ${isBugMode ? 'docs/bugs' : 'docs/features'}/${featureCode}/audit.json`);
+        console.log(`Audit trace written to ${cfg.artifactRoot === 'features' ? 'docs/features' : cfg.artifactRoot}/${featureCode}/audit.json`);
       } catch (err) {
         console.warn(`Warning: could not write audit trace: ${err.message}`);
       }
@@ -2356,7 +2650,7 @@ export async function runBuild(featureCode, opts = {}) {
           join(featureDir, 'audit.json'),
           JSON.stringify(audit, null, 2)
         );
-        console.log(`Audit trace written to ${isBugMode ? 'docs/bugs' : 'docs/features'}/${featureCode}/audit.json`);
+        console.log(`Audit trace written to ${cfg.artifactRoot === 'features' ? 'docs/features' : cfg.artifactRoot}/${featureCode}/audit.json`);
       } catch (err) {
         console.warn(`Warning: could not write audit trace: ${err.message}`);
       }
@@ -2364,6 +2658,29 @@ export async function runBuild(featureCode, opts = {}) {
 
     // File retained on disk per STRAT-COMP-4 — overwritten on next build start
 
+  } catch (err) {
+    buildStatus = 'failed';
+    const failureReason = err?.message ?? 'Build failed';
+    try {
+      await terminalizeThrownBuild({
+        cwd,
+        dataDir,
+        cfg,
+        visionWriter,
+        itemId,
+        featureCode,
+        mode,
+        response,
+        buildStartedAt,
+        buildCostTotals,
+        stepHistory,
+        failureReason,
+        historyWritten: terminalHistoryWritten,
+      });
+    } catch (terminalErr) {
+      console.warn(`[build] Failed to terminalize crashed build: ${terminalErr.message}`);
+    }
+    throw err;
   } finally {
     // Close stream writer with appropriate status (idempotent — signal handler may have already closed)
     if (streamWriter) {
@@ -2467,6 +2784,25 @@ function noticeExternalArtifacts(cwd, featureCode, buildToplevel) {
   } catch { /* notice is best-effort */ }
 }
 
+/**
+ * Extract structured test counts from a ship step result for build-history persistence.
+ * Exported so tests can assert the capture logic without running a full build loop.
+ *
+ * Called in BOTH the ship-interception branch (shouldInterceptShip path) and the
+ * generic step-completion path so both code paths produce the same history record.
+ *
+ * Returns null when testSummary was unparsed (test_count absent or not a number).
+ * The `?? 0` on pass_rate is defensive — parseTestSummary always sets it when
+ * parsed=true, but this prevents a null from silently reaching the history record.
+ *
+ * @param {object|null} shipResult  Return value from executeShipStep
+ * @returns {{ test_count: number, pass_rate: number }|null}
+ */
+export function _extractShipTestMetrics(shipResult) {
+  if (typeof shipResult?.test_count !== 'number') return null;
+  return { test_count: shipResult.test_count, pass_rate: shipResult.pass_rate ?? 0 };
+}
+
 /**
  * Execute the ship step: run tests, stage feature files, commit.
  * Returns a PhaseResult-shaped object.
@@ -2475,9 +2811,13 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
   // COMP-FIX-HARD T4: bug mode stages docs/bugs/<code>/ instead of <featuresDir>/<code>/
   // COMP-MCP-MIGRATION-2: feature mode honors paths.features override.
   const featuresDir = loadFeaturesDir(cwd);
-  const featureDir = context?.mode === 'bug'
-    ? `docs/bugs/${featureCode}`
-    : `${featuresDir}/${featureCode}`;
+  // RELATIVE staging dir, driven by the mode's artifactRoot (the relative form is
+  // load-bearing for the MCP-enforcement git-status guard). Byte-identical to the
+  // prior feature/bug branch: 'features' → <featuresDir>, else the literal token.
+  const shipCfg = getMode(context?.mode).runner;
+  const featureDir = shipCfg.artifactRoot === 'features'
+    ? `${featuresDir}/${featureCode}`
+    : `${shipCfg.artifactRoot}/${featureCode}`;
 
   // COMP-BUILD-QUICK-1: when a feature was built via the trimmed quick lifecycle
   // (which omits the report phase by design), stamp built_via onto feature.json so
@@ -2758,6 +3098,10 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
         : `Committed: ${commitMsg} (${stagedFiles.length} files)`,
       commit: sha,
       filesChanged,
+      // 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 } : {}),
     };
 
@@ -3154,7 +3498,8 @@ export async function executeChildFlow(
 
       if (progress) progress.pause();
       console.log(`  [${childFlowName}] Gate: ${resp.step_id}`);
-      const gateId = await visionWriter.createGate(childFlowId, resp.step_id, itemId);
+      // COMP-PLAN-GATE-LOOP: round-aware gate id (child flow has its own round).
+      const gateId = await visionWriter.createGate(childFlowId, resp.step_id, itemId, { round: readFlowRound(childFlowId) });
       const childAskAgent = makeAskAgent(stratum, context, resp, null);
 
       const childGateExtras = {
@@ -3357,6 +3702,15 @@ export function shouldUseServerDispatch(dispatchResponse) {
 const SERVER_DISPATCH_POLL_MS = () =>
   Number(process.env.COMPOSE_SERVER_DISPATCH_POLL_MS) || 500;
 
+// COMP-PLAN-GATE-LOOP (F3): wall-clock ceiling for a single parallel-dispatch
+// step's poll loop. The loop exits on an outcome, a stuck verdict (GSD only),
+// or a poll error — but if Stratum ever leaves tasks 'running' forever with
+// fresh heartbeats and no error, none fire and the loop is unbounded. No single
+// parallel step legitimately runs 6h, so this turns a silent hang into a
+// diagnostic failure. Env-overridable.
+const MAX_PARALLEL_DISPATCH_MS = () =>
+  Number(process.env.COMPOSE_MAX_PARALLEL_DISPATCH_MS) || 6 * 60 * 60 * 1000;
+
 /**
  * Emit per-task state-transition events. Uses build_task_start/done subtypes
  * (distinct from build_step_start/done) to avoid stepId key collisions in
@@ -3483,7 +3837,17 @@ export async function executeParallelDispatchServer(
     let pollResult;
     let stuckVerdict = null;
     const intervalMs = SERVER_DISPATCH_POLL_MS();
+    const pollDeadline = Date.now() + MAX_PARALLEL_DISPATCH_MS();
     while (true) {
+      // F3: guard against an unbounded poll if Stratum never delivers an
+      // outcome (tasks stuck 'running' with fresh heartbeats, no error).
+      if (Date.now() > pollDeadline) {
+        throw new Error(
+          `executeParallelDispatchServer: parallel step '${stepId}' exceeded the ` +
+          `${Math.round(MAX_PARALLEL_DISPATCH_MS() / 3_600_000)}h dispatch ceiling without an outcome ` +
+          `(last task states: ${JSON.stringify(pollResult?.tasks ?? {})}). Aborting to avoid an unbounded hang.`
+        );
+      }
       pollResult = await stratum.parallelPoll(flowId, stepId);
       if (pollResult?.error) {
         throw new Error(
@@ -4629,9 +4993,15 @@ export async function startFresh(stratum, specYaml, featureCode, description, da
   // Defaults reproduce today's behavior (claude implements, codex reviews) byte-identically.
   const implementerAgent = roles?.implementerAgent ?? 'claude';
   const reviewerAgent = roles?.reviewerAgent ?? 'codex';
-  const planInputs = mode === 'bug'
+  // The plan-input envelope is the mode's flow input contract. bug → { task };
+  // plan → { projectName, intent } (the new.stratum.yaml shape); feature → the
+  // full feature envelope. Byte-identical to the prior bug/feature ternary.
+  const planCfg = getMode(mode).runner;
+  const planInputs = planCfg.planInputs === 'bug'
     ? { task: description }
-    : { featureCode, description, implementer_agent: implementerAgent, reviewer_agent: reviewerAgent, ...(preMergeGate !== undefined ? { pre_merge_gate: preMergeGate } : {}) };
+    : planCfg.planInputs === 'plan'
+      ? { projectName: featureCode, intent: description }
+      : { featureCode, description, implementer_agent: implementerAgent, reviewer_agent: reviewerAgent, ...(preMergeGate !== undefined ? { pre_merge_gate: preMergeGate } : {}) };
   const response = await stratum.plan(specYaml, flowName, planInputs);
 
   writeActiveBuild(dataDir, {
@@ -4747,6 +5117,30 @@ async function pollGateResolution(visionWriter, gateId, intervalMs = 2000) {
   }
 }
 
+/**
+ * COMP-PLAN-GATE-LOOP: backstop cap on how many times a single step may
+ * re-enter its gate within one build. With the round-aware gate id this should
+ * never trip (each re-entry blocks for a real decision), but if the round can't
+ * be threaded the gate would otherwise spin forever (the observed 52-round
+ * loop). Trip loudly instead — the Stratum flow state is preserved, so the
+ * gate can be resolved and the build resumed.
+ *
+ * @param {number} count - re-entry count for this step (1 on first entry)
+ * @param {string} stepId
+ * @param {number} [cap=MAX_GATE_REENTRIES]
+ */
+export const MAX_GATE_REENTRIES = 20;
+
+export function assertGateReentryWithinCap(count, stepId, cap = MAX_GATE_REENTRIES) {
+  if (count > cap) {
+    throw new Error(
+      `Gate "${stepId}" re-entered ${count} times without converging (cap ${cap}). ` +
+      `Aborting to avoid an infinite gate loop. The Stratum flow state is preserved — ` +
+      `resolve the gate (e.g. approve it) and re-run with --resume to continue.`
+    );
+  }
+}
+
 /**
  * Append a decision log entry to docs/context/decisions.md.
  * Only writes if the file already exists (created by `compose init`).