@smartmemory/compose 0.1.1-beta → 0.1.3-beta

package/lib/build.js

@@ -12,11 +12,11 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameS
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir } from 'node:os';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 
 import { StratumMcpClient, StratumError } from './stratum-mcp-client.js';
-import { runAndNormalize, AgentTimeoutError, UserInterruptError } from './result-normalizer.js';
+import { runAndNormalize, AgentTimeoutError, UserInterruptError, AgentError } from './result-normalizer.js';
 import { checkCapabilityViolation } from './capability-checker.js';
 import { buildStepPrompt, buildRetryPrompt, buildGateContext, clearAmbientContextCache } from './step-prompt.js';
 import { promptGate } from './gate-prompt.js';
@@ -26,15 +26,17 @@ import { probeServer } from './server-probe.js';
 import { CliProgress } from './cli-progress.js';
 import { BuildStreamWriter } from './build-stream-writer.js';
 import { resolveAgentConfig } from './agent-string.js';
+import { installFactoryShim } from './connector-factory-shim.js';
+import { emitSections as emitPlanSections, appendTrailers as appendSectionTrailers } from './sections.js';
 
 import YAML from 'yaml';
-import { ClaudeSDKConnector } from '../server/connectors/claude-sdk-connector.js';
-import { CodexConnector } from '../server/connectors/codex-connector.js';
 import { updateFeature, readFeature, writeFeature } from './feature-json.js';
 import { evaluatePolicy } from '../server/policy-evaluator.js';
 import { runTriage, isTriageStale } from './triage.js';
 import { shouldRunCrossModel, LENS_DEFINITIONS } from './review-lenses.js';
 import { injectCertInstructions } from './cert-inject.js';
+import { buildReviewPrompt } from './review-prompt.js';
+import { normalizeCrossModelResult } from './review-normalize.js';
 import { detectTestFramework, scaffoldTestFramework } from './test-bootstrap.js';
 import { classifyStepAsTier, evaluateTiers } from './gate-tiers.js';
 import { mapFilesToRoutes, classifyRoutes, isDocsOnlyDiff } from './qa-scoping.js';
@@ -42,6 +44,201 @@ import { computeCompositeScore } from './health-score.js';
 import { recordScore } from './health-history.js';
 import { FixChainDetector, AttemptCounter, DebugLedger, TraceValidator } from './debug-discipline.js';
 import { CrossLayerAudit, loadDebugConfig } from './cross-layer-audit.js';
+import { emitCheckpoint } from './bug-checkpoint.js';
+import { appendHypothesisEntry, readHypotheses } from './bug-ledger.js';
+import { tier1CodexReview, tier2FreshAgent } from './bug-escalation.js';
+
+// ---------------------------------------------------------------------------
+// COMP-FIX-HARD T5: per-step retries cap parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a Map<stepId, retriesCap> from a parsed Stratum spec.
+ *
+ * Each flow step has an optional `function` (defaults to step.id). Per-function
+ * `retries` is declared under top-level `functions:`. Per-step `retries`, if
+ * present on the flow step itself, takes precedence.
+ *
+ * Stratum's executor does not enforce `retries` (Phase 5 finding). Compose
+ * enforces it client-side: when a step's iteration count exceeds its cap,
+ * runBuild force-terminates the flow.
+ *
+ * @param {string} specYaml - The Stratum spec (post triage mutation).
+ * @returns {Map<string, number>} step.id -> max retries before force terminate.
+ */
+export function parseRetriesCap(specYaml) {
+  const cap = new Map();
+  let parsed;
+  try {
+    parsed = YAML.parse(specYaml);
+  } catch {
+    return cap;
+  }
+  const functions = parsed?.functions ?? {};
+  const flows = parsed?.flows ?? {};
+  for (const flow of Object.values(flows)) {
+    const steps = flow?.steps;
+    if (!Array.isArray(steps)) continue;
+    for (const step of steps) {
+      if (!step?.id) continue;
+      // Per-step retries wins; otherwise inherit from the linked function.
+      let r;
+      if (typeof step.retries === 'number') {
+        r = step.retries;
+      } else {
+        const fnName = step.function ?? step.id;
+        const fn = functions[fnName];
+        if (fn && typeof fn.retries === 'number') r = fn.retries;
+      }
+      if (typeof r === 'number') cap.set(step.id, r);
+    }
+  }
+  return cap;
+}
+
+// ---------------------------------------------------------------------------
+// COMP-FIX-HARD T6: hypothesis ledger append on diagnose success.
+// ---------------------------------------------------------------------------
+
+/**
+ * Append an `accepted` hypothesis ledger entry whenever a diagnose step
+ * completes successfully in bug mode. No-op outside bug mode or for any
+ * other step. Best-effort: ledger I/O failures are logged, never thrown.
+ *
+ * Called from BOTH the top-level execute_step success branch and the
+ * child-flow execute_step success branch in build.js — same helper, two
+ * call sites (mirroring Correction C from the COMP-FIX-HARD blueprint).
+ *
+ * @param {object} context  — execution context (must carry mode + bug_code + cwd)
+ * @param {object} response — Stratum response (uses response.step_id)
+ * @param {object} result   — agent result envelope (root_cause, trace_evidence)
+ */
+export function recordDiagnoseSuccessIfBugMode(context, response, result) {
+  if (!context || context.mode !== 'bug') return;
+  if (!context.bug_code || !context.cwd) return;
+  const stepId = response?.step_id;
+  if (stepId !== 'diagnose') return;
+
+  try {
+    const prior = readHypotheses(context.cwd, context.bug_code);
+    // Use max(prior.attempt) + 1 so escalation_tier_1 entries (which use the
+    // same length-based formula in bug-escalation.js) don't collide on a later
+    // accepted entry. Idempotency key is (attempt, ts) so dups would still
+    // append; this just keeps the rendered attempt sequence sane.
+    const maxAttempt = prior.reduce((acc, e) => Math.max(acc, Number(e.attempt) || 0), 0);
+    const attempt = maxAttempt + 1;
+    const entry = {
+      attempt,
+      ts: new Date().toISOString(),
+      hypothesis: result?.root_cause ?? '',
+      verdict: 'accepted',
+      evidence_for: Array.isArray(result?.trace_evidence) ? result.trace_evidence : [],
+    };
+    appendHypothesisEntry(context.cwd, context.bug_code, entry);
+  } catch (err) {
+    // Best-effort: ledger I/O must never abort a successful step.
+    // eslint-disable-next-line no-console
+    console.warn(`[bug-ledger] recordDiagnoseSuccessIfBugMode failed: ${err?.message || err}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// COMP-FIX-HARD T10: post-retro_check escalation gate (Tier 1 + Tier 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Prompt the user for a yes/no decision via readline. Returns true on
+ * approve/y/yes; false on skip/n/no/empty/EOF. Non-interactive (no TTY)
+ * answers default to skip so headless runs don't hang.
+ */
+async function _confirm(message) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ans = await new Promise(resolve => rl.question(`${message} `, resolve));
+    const v = String(ans ?? '').trim().toLowerCase();
+    return v === 'a' || v === 'approve' || v === 'y' || v === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * After retro_check completes in bug mode, check whether the per-bug
+ * attempt counter has reached the 'escalate' threshold. If so, gate the
+ * user for a Codex second opinion (Tier 1) and, if Codex surfaces a
+ * materially-new hypothesis, gate again for a fresh-agent worktree
+ * dispatch (Tier 2).
+ *
+ * Best-effort: any failure inside this helper is logged and swallowed —
+ * escalation is advisory and must never abort an otherwise-successful build.
+ */
+export async function maybeRunEscalation(stratum, context, progress, streamWriter, attemptCounter, dataDir) {
+  if (!context || context.mode !== 'bug' || !context.bug_code) return;
+  const intervention = attemptCounter.getInterventionForBug(context.bug_code);
+  if (intervention !== 'escalate') return;
+
+  const bugCode = context.bug_code;
+  try {
+    const approveTier1 = await _confirm(
+      `Bug ${bugCode} has escalated. Run Codex second opinion (~30s, read-only)? approve / skip:`,
+    );
+    if (!approveTier1) {
+      if (progress) progress.warn(`Escalation skipped for ${bugCode}.`);
+      return;
+    }
+
+    // Gather inputs for Tier 1.
+    const bugDir = join(context.cwd, 'docs', 'bugs', bugCode);
+    let bugDescription = '';
+    try { bugDescription = readFileSync(join(bugDir, 'description.md'), 'utf-8'); } catch { /* optional */ }
+    let reproTest = '';
+    try { reproTest = readFileSync(join(bugDir, 'repro.test.js'), 'utf-8'); } catch {
+      try { reproTest = readFileSync(join(bugDir, 'repro.md'), 'utf-8'); } catch { /* optional */ }
+    }
+    let currentDiff = '';
+    try {
+      currentDiff = execSync('git diff --no-color HEAD', {
+        cwd: context.cwd, encoding: 'utf-8', timeout: 10_000,
+      }).slice(0, 8000);
+    } catch { /* not a git repo or no diff */ }
+
+    const hypotheses = readHypotheses(context.cwd, bugCode);
+
+    if (streamWriter) streamWriter.write({ type: 'build_step_start', stepId: 'escalation_tier_1', stepNum: '?', totalSteps: '?', agent: 'codex', intent: 'Codex second-opinion review', flowId: null });
+    const review = await tier1CodexReview(stratum, context, bugDescription, reproTest, currentDiff, hypotheses);
+    if (progress) progress.warn(`Tier 1 (Codex) — ${review.summary}`);
+    if (streamWriter) streamWriter.write({ type: 'build_step_done', stepId: 'escalation_tier_1', summary: review.summary, retries: 0, violations: [], flowId: null });
+
+    // Tier 2 gate — only if Codex surfaced a must-fix or should-fix finding.
+    const blocking = (review.findings ?? []).filter(f => f.severity === 'must-fix' || f.severity === 'should-fix');
+    if (blocking.length === 0) {
+      if (progress) progress.warn('Codex returned no actionable findings — Tier 2 skipped.');
+      return;
+    }
+
+    const approveTier2 = await _confirm(
+      `Codex found a new angle. Dispatch fresh agent in worktree to draft a patch (no commits)? approve / skip:`,
+    );
+    if (!approveTier2) {
+      if (progress) progress.warn(`Tier 2 skipped for ${bugCode}.`);
+      return;
+    }
+
+    const checkpointPath = join(bugDir, 'checkpoint.md');
+    const tier2 = await tier2FreshAgent(stratum, context, review, hypotheses, existsSync(checkpointPath) ? checkpointPath : null);
+    if (tier2.skipped) {
+      if (progress) progress.warn(`Tier 2 skipped: ${tier2.reason}`);
+    } else {
+      if (progress) progress.warn(`Tier 2 patch artifact ready at ${tier2.patch_path}`);
+      if (streamWriter) streamWriter.write({ type: 'build_step_done', stepId: 'escalation_tier_2', summary: `Patch artifact at ${tier2.patch_path}`, retries: 0, violations: [], flowId: null });
+    }
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[bug-escalation] failed: ${err?.message || err}`);
+  }
+}
 
 // ---------------------------------------------------------------------------
 // STRAT-IMMUTABLE: pipeline and policy integrity helpers
@@ -146,14 +343,9 @@ function extractFilesChanged(response) {
 }
 
 // ---------------------------------------------------------------------------
-// Agent registry
+// Per-step timeouts
 // ---------------------------------------------------------------------------
 
-const DEFAULT_AGENTS = new Map([
-  ['claude', (opts) => new ClaudeSDKConnector(opts)],
-  ['codex', (opts) => new CodexConnector(opts)],
-]);
-
 // Per-step timeout in ms. Steps not listed get the default.
 // These are circuit breakers — generous enough for real work, tight enough to stop spiraling.
 const STEP_TIMEOUT_MS = {
@@ -176,41 +368,9 @@ const STEP_TIMEOUT_MS = {
 };
 const DEFAULT_TIMEOUT_MS = 30 * 60_000; // 30 min fallback
 
-/**
- * Default connector factory.
- * Accepts either a bare provider name ("claude") or a full agent string
- * ("claude:read-only-reviewer"). Resolves capability restrictions from the
- * template and passes them to the connector constructor.
- *
- * @param {string} agentString  Full agent string, e.g. "claude:read-only-reviewer" or "claude"
- * @param {object} opts         Additional connector options (cwd, model, etc.)
- */
-function defaultConnectorFactory(agentString, opts) {
-  const { provider, allowedTools, disallowedTools, modelID, thinking, effort } = resolveAgentConfig(agentString);
-  const factory = DEFAULT_AGENTS.get(provider);
-  if (!factory) {
-    throw new Error(
-      `compose build: step requires agent "${provider}" but no connector is registered.\n` +
-      `Known agents: ${[...DEFAULT_AGENTS.keys()].join(', ')}\n` +
-      `Check your .stratum.yaml spec or install the agent.`
-    );
-  }
-  // Pass tool restrictions only when they are defined (avoids overriding connector defaults)
-  const connectorOpts = { ...opts };
-  if (allowedTools !== null) connectorOpts.allowedTools = allowedTools;
-  if (disallowedTools !== null) connectorOpts.disallowedTools = disallowedTools;
-  // Pass resolved model ID when a tier was specified — connector uses its own default otherwise
-  // Both keys for cross-connector compatibility: ClaudeSDKConnector uses `model`,
-  // CodexConnector/AgentConnector base class uses `modelID`
-  if (modelID !== null) {
-    connectorOpts.model = modelID;
-    connectorOpts.modelID = modelID;
-  }
-  // Tier-default thinking/effort; caller (opts) can override.
-  if (thinking !== null && connectorOpts.thinking === undefined) connectorOpts.thinking = thinking;
-  if (effort   !== null && connectorOpts.effort   === undefined) connectorOpts.effort   = effort;
-  return factory(connectorOpts);
-}
+// STRAT-DEDUP-AGENTRUN-V3: connectors now live in stratum-mcp (Python). The
+// `runAndNormalize` helper resolves the agent tier internally and dispatches
+// via `stratum.agentRun(...)`, so there is no JS connector factory.
 
 // ---------------------------------------------------------------------------
 // Active build state (resume/abort)
@@ -281,16 +441,15 @@ function isProcessAlive(pid) {
 /**
  * Build an askAgent helper that answers gate questions with full workflow context.
  *
- * @param {Function} getConnector - Connector factory
- * @param {object}   context      - Execution context (cwd, featureCode, featureDir, stepHistory, filesChanged)
- * @param {object}   gateDispatch - Stratum gate dispatch (step_id, on_approve, on_revise, on_kill)
- * @param {object}   [gateExtras] - Optional enrichment (fromPhase, toPhase, summary)
+ * @param {object} stratum      - StratumMcpClient (provides runAgentText)
+ * @param {object} context      - Execution context (cwd, featureCode, featureDir, stepHistory, filesChanged)
+ * @param {object} gateDispatch - Stratum gate dispatch (step_id, on_approve, on_revise, on_kill)
+ * @param {object} [gateExtras] - Optional enrichment (fromPhase, toPhase, summary)
  */
-function makeAskAgent(getConnector, context, gateDispatch, gateExtras) {
+function makeAskAgent(stratum, context, gateDispatch, gateExtras) {
   const preamble = buildGateContext(gateDispatch, context, gateExtras);
 
   return async function askAgent(question, artifactPath) {
-    const connector = getConnector('claude', { cwd: context.cwd });
     const fileRef = artifactPath && !artifactPath.endsWith('/')
       ? `Read the file "${artifactPath}" and answer`
       : `Look at the project files in the working directory and answer`;
@@ -299,12 +458,8 @@ function makeAskAgent(getConnector, context, gateDispatch, gateExtras) {
       `${fileRef} this question concisely:\n\n` +
       `${question}\n\n` +
       `Keep your answer brief — 2-3 sentences max.`;
-    const parts = [];
-    for await (const event of connector.run(qaPrompt, {})) {
-      if (event.type === 'assistant' && event.content) parts.push(event.content);
-      if (event.type === 'result' && event.content && parts.length === 0) parts.push(event.content);
-    }
-    return parts.join('') || '(no answer)';
+    const text = await stratum.runAgentText('claude', qaPrompt, { cwd: context.cwd });
+    return text || '(no answer)';
   };
 }
 
@@ -366,7 +521,6 @@ export function resolveTemplatePath(name, cwd) {
  *                                             the project root (e.g. parent dir for cross-repo features).
  * @param {boolean}  [opts.abort]            - Abort active build instead of running
  * @param {string}   [opts.description]      - Feature description override
- * @param {Function} [opts.connectorFactory] - Override agent connector creation (for testing)
  * @param {object}   [opts.gateOpts]         - Options for gate prompt (input/output streams)
  * @param {string}   [opts.template]         - Pipeline template name (default: 'build').
  *                                             Resolves to pipelines/${template}.stratum.yaml.
@@ -376,7 +530,14 @@ export function resolveTemplatePath(name, cwd) {
 export async function runBuild(featureCode, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const agentCwd = opts.workingDirectory ?? cwd;
-  const getConnector = opts.connectorFactory ?? defaultConnectorFactory;
+
+  // COMP-FIX-HARD T4: bug-mode branch.
+  //   mode === 'feature' (default): legacy behavior — docs/features/<code>/,
+  //                                  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';
+  const isBugMode = mode === 'bug';
 
   // Resolve project paths
   const composeDir = join(cwd, '.compose');
@@ -388,7 +549,14 @@ export async function runBuild(featureCode, opts = {}) {
     return;
   }
 
-  const featureDir = join(cwd, 'docs', 'features', featureCode);
+  // 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.
+  const resolveItemDir = (code) => isBugMode
+    ? join(cwd, 'docs', 'bugs', code)
+    : join(cwd, 'docs', 'features', code);
+
+  const featureDir = resolveItemDir(featureCode);
 
   // Debug discipline (COMP-DEBUG-1)
   const debugStatePath = join(composeDir, 'debug-state.json');
@@ -427,7 +595,9 @@ export async function runBuild(featureCode, opts = {}) {
   //   - opts.template is explicitly set (user chose a specific template)
   // ---------------------------------------------------------------------------
   let buildProfile = null;
-  if (!opts.skipTriage && !opts.template) {
+  // 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) {
     let cachedFeature = readFeature(cwd, featureCode);
     if (cachedFeature?.profile && !isTriageStale(cwd, featureCode)) {
       // Reuse cached profile
@@ -504,8 +674,14 @@ export async function runBuild(featureCode, opts = {}) {
     }
   }
 
-  // Build description from feature folder
-  const description = opts.description ?? loadFeatureDescription(featureDir, featureCode);
+  // COMP-FIX-HARD T5: build per-step retries cap from finalized spec.
+  // 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
+    ? loadBugDescription(featureDir, featureCode)
+    : loadFeatureDescription(featureDir, featureCode));
 
   // Vision writer
   const visionWriter = new VisionWriter(dataDir);
@@ -534,12 +710,23 @@ export async function runBuild(featureCode, opts = {}) {
   // CLI progress renderer
   const progress = new CliProgress();
 
-  // Stratum MCP client
-  const stratum = new StratumMcpClient();
-  await stratum.connect({ cwd });
+  // Stratum MCP client (test override permitted via opts.stratum)
+  const stratum = opts.stratum ?? new StratumMcpClient();
+  if (!opts.stratum) await stratum.connect({ cwd });
 
-  // Update feature.json status to IN_PROGRESS
-  updateFeature(cwd, featureCode, { status: 'IN_PROGRESS' });
+  // Backward-compat shim: tests pass `connectorFactory` (legacy) to inject
+  // mock connectors. Adapt the factory's `connector.run(prompt)` event stream
+  // into BuildStreamEvent envelopes dispatched through the same onEvent
+  // pathway as the live producer, so runAndNormalize sees identical wire shape.
+  if (opts.connectorFactory && !opts.stratum) {
+    installFactoryShim(stratum, opts.connectorFactory, agentCwd);
+  }
+
+  // Update feature.json status to IN_PROGRESS (feature mode only;
+  // bug mode does not use feature.json).
+  if (!isBugMode) {
+    updateFeature(cwd, featureCode, { status: 'IN_PROGRESS' });
+  }
 
   // Hoisted for finally-block visibility
   let streamWriter = null;
@@ -575,11 +762,62 @@ export async function runBuild(featureCode, opts = {}) {
     let response;
     let isFreshStart = true;
 
-    if (active && active.featureCode === featureCode && active.flowId) {
+    // 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.`
+        );
+      }
+      console.log(`Resuming flow ${opts.resumeFlowId} for ${featureCode}...`);
+      response = await stratum.resume(opts.resumeFlowId);
+      isFreshStart = false;
+      // 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(),
+      });
+    } else if (active && active.featureCode === featureCode && active.flowId) {
       // Same feature — try to resume or start fresh
-      if (active.status && active.status !== 'running') {
+      // 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);
+      } else if (active.status && active.status !== 'running') {
         console.log(`Previous build ${active.status}. Starting fresh.`);
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName);
+        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
       } else if (active.pid && active.pid !== process.pid && isProcessAlive(active.pid)) {
         // Same feature, different live process — block
         throw new Error(
@@ -592,7 +830,7 @@ export async function runBuild(featureCode, opts = {}) {
           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);
+            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
           } else {
             console.log(`Resuming from step: ${response.step_id}`);
             isFreshStart = false;
@@ -603,7 +841,7 @@ export async function runBuild(featureCode, opts = {}) {
             || 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);
+            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
           } else {
             throw err;
           }
@@ -613,7 +851,7 @@ export async function runBuild(featureCode, opts = {}) {
       // 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.
-      response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName);
+      response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
     }
 
     // Update vision state
@@ -644,9 +882,11 @@ export async function runBuild(featureCode, opts = {}) {
     const context = {
       cwd: agentCwd,
       featureCode,
-      featureDir: join(cwd, 'docs', 'features', featureCode),
+      featureDir: resolveItemDir(featureCode),
       contextDir: contextDirPath,
       stepHistory,
+      mode,
+      ...(isBugMode ? { bug_code: featureCode } : {}),
     };
 
 
@@ -694,6 +934,29 @@ export async function runBuild(featureCode, opts = {}) {
             break;
           }
           progress.stepDone(stepId);
+          // COMP-PLAN-SECTIONS T7: append "What Was Built" trailers to all
+          // section files after a successful ship. No-op if sections/ doesn't
+          // exist. Wrapped so trailer-append failure never fails the ship.
+          try {
+            if (shipResult.commit) {
+              const trailerResult = appendSectionTrailers({
+                featureDir,
+                commit: shipResult.commit,
+                filesChanged: shipResult.filesChanged ?? [],
+                cwd: agentCwd,
+              });
+              if (trailerResult.trailed?.length > 0) {
+                streamWriter.write({
+                  type: 'build_sections_trailed',
+                  featureCode,
+                  count: trailerResult.trailed.length,
+                  sections: trailerResult.trailed,
+                });
+              }
+            }
+          } catch (err) {
+            try { streamWriter.write({ type: 'build_error', message: `sections trailer append failed: ${err.message}`, stepId: 'ship' }); } catch { /* ignore */ }
+          }
           // COMP-HEALTH: collect plan_completion signal from ship result (if present)
           if (shipResult.planCompletionPct != null || shipResult.plan_completion_pct != null) {
             buildSignals.plan_completion = {
@@ -712,10 +975,33 @@ export async function runBuild(featureCode, opts = {}) {
         // Build prompt and dispatch to agent
         const stepStartMs = Date.now();
         const agentType = response.agent ?? 'claude';
-        const prompt = buildStepPrompt(response, context);
-        const connector = getConnector(agentType, { cwd: agentCwd });
+        const basePrompt = buildStepPrompt(response, context);
         const maxDurationMs = STEP_TIMEOUT_MS[stepId] ?? DEFAULT_TIMEOUT_MS;
 
+        // MF-1/SF-4: Prepend shared review scaffold when this is a review step.
+        // Also covers the merge step (output_contract=ReviewResult) so its output
+        // is normalized via normalizeReviewResult.
+        // SF-NEW-1: reduce_mode steps (merge) get normalization but NOT scaffold framing.
+        // They are reducers, not reviewers — prepending "Review the {lens} for..." is wrong.
+        const isReviewMain = response.review_mode === true
+          || response.inputs?.review_mode === 'true'
+          || response.output_contract === 'ReviewResult';
+        const isReduceMain = response.inputs?.reduce_mode === 'true';
+        const isReviewScaffoldMain = isReviewMain && !isReduceMain;
+        const confGateMain = Number(response.inputs?.confidence_gate ?? response.confidence_gate ?? 7);
+        let prompt = basePrompt;
+        if (isReviewScaffoldMain) {
+          prompt = buildReviewPrompt({
+            agentType,
+            lens: 'general',
+            lensFocus: '',
+            exclusions: '',
+            confidenceGate: confGateMain,
+            taskDescription: response.inputs?.task ?? '',
+            blueprint: response.inputs?.blueprint ?? '',
+          }) + '\n\n' + basePrompt;
+        }
+
         // Collect tool_use events for post-step capability audit (Item 193/195)
         const observedTools = [];
         const onToolUse = ({ tool, input, timestamp }) => {
@@ -724,7 +1010,12 @@ export async function runBuild(featureCode, opts = {}) {
 
         let mainResult;
         try {
-          mainResult = await runAndNormalize(connector, prompt, response, { progress, streamWriter, maxDurationMs, onToolUse });
+          mainResult = await runAndNormalize(null, prompt, response, {
+            progress, streamWriter, maxDurationMs, onToolUse, stratum, cwd: agentCwd,
+            reviewMode: isReviewMain,
+            confidenceGate: confGateMain,
+            lens: response.inputs?.lens_name ?? response.lens_name ?? 'general',
+          });
         } catch (err) {
           if (err instanceof UserInterruptError) {
             if (err.action === 'skip') {
@@ -787,7 +1078,7 @@ export async function runBuild(featureCode, opts = {}) {
               capViolations.push({ tool, severity: check.severity, reason: check.reason });
               // Emit capability_violation event to build stream
               const { template: tpl } = resolveAgentConfig(agentType);
-              streamWriter.writeViolation(stepId, agentType, tpl ?? 'unknown', check.reason);
+              streamWriter.writeViolation(stepId, agentType, tpl ?? 'unknown', check.reason, check.severity);
               // Console log (always, even in block mode — for visibility)
               console.log(`  [caps] ${tool} used by ${agentType} — violates ${tpl ?? 'unknown'} profile`);
             }
@@ -855,11 +1146,20 @@ export async function runBuild(featureCode, opts = {}) {
         response = await stratum.stepDone(flowId, stepId, result ?? { summary: 'Step complete' });
         syncStepHistory(dataDir, stepHistory);
 
+        // COMP-FIX-HARD T6: record accepted hypothesis on diagnose success (bug mode only).
+        recordDiagnoseSuccessIfBugMode(context, { step_id: stepId }, result);
+
         // Debug discipline enforcement (COMP-DEBUG-1)
         if (stepId === 'fix' || stepId === 'diagnose') {
           const filesChanged = extractFilesChanged({ result });
-          fixChainDetector.recordIteration(filesChanged);
-          attemptCounter.record({ filesChanged });
+          // COMP-FIX-HARD T9: per-bug keying when running in bug mode.
+          if (context.mode === 'bug' && context.bug_code) {
+            fixChainDetector.recordIterationForBug(context.bug_code, filesChanged);
+            attemptCounter.recordForBug(context.bug_code, { filesChanged });
+          } else {
+            fixChainDetector.recordIteration(filesChanged);
+            attemptCounter.record({ filesChanged });
+          }
 
           // Validate trace evidence on diagnose results
           if (stepId === 'diagnose' && result) {
@@ -877,21 +1177,33 @@ export async function runBuild(featureCode, opts = {}) {
             }
           }
 
-          const chains = fixChainDetector.detect();
-          const intervention = attemptCounter.getIntervention();
+          const isBugMode = context.mode === 'bug' && !!context.bug_code;
+          const chains = isBugMode
+            ? fixChainDetector.detectForBug(context.bug_code)
+            : fixChainDetector.detect();
+          const intervention = isBugMode
+            ? attemptCounter.getInterventionForBug(context.bug_code)
+            : attemptCounter.getIntervention();
+          // COMP-FIX-HARD T10: read attempt counters via the per-bug API in bug mode.
+          const attemptCount = isBugMode
+            ? attemptCounter.getCountForBug(context.bug_code)
+            : attemptCounter.count;
+          const attemptIsVisual = isBugMode
+            ? (attemptCounter.byBug.get(context.bug_code)?.isVisual ?? false)
+            : attemptCounter.isVisual;
 
           if (chains.length > 0) {
             debugLedger.record({ type: 'fix_chain_detected', chains });
           }
 
           if (intervention === 'escalate') {
-            debugLedger.record({ type: 'escalation', attempt: attemptCounter.count, isVisual: attemptCounter.isVisual });
-            if (streamWriter) streamWriter.write({ type: 'build_error', message: `Debug discipline: escalating after ${attemptCounter.count} attempts. Dispatching to cross-agent review.` });
+            debugLedger.record({ type: 'escalation', attempt: attemptCount, isVisual: attemptIsVisual });
+            if (streamWriter) streamWriter.write({ type: 'build_error', message: `Debug discipline: escalating after ${attemptCount} attempts. Dispatching to cross-agent review.` });
           } else if (intervention === 'trace_refresh') {
-            debugLedger.record({ type: 'trace_refresh_required', attempt: attemptCounter.count });
-            if (progress) progress.warn(`Debug discipline: ${attemptCounter.count} attempts — fresh trace evidence required before next fix`);
+            debugLedger.record({ type: 'trace_refresh_required', attempt: attemptCount });
+            if (progress) progress.warn(`Debug discipline: ${attemptCount} attempts — fresh trace evidence required before next fix`);
           } else if (intervention === 'trace_reminder') {
-            if (progress) progress.warn(`Debug discipline: ${attemptCounter.count} attempts on same target — verify trace evidence is current`);
+            if (progress) progress.warn(`Debug discipline: ${attemptCount} attempts on same target — verify trace evidence is current`);
           }
 
           // Persist debug state
@@ -903,6 +1215,11 @@ export async function runBuild(featureCode, opts = {}) {
           } catch { /* best-effort */ }
         }
 
+        // 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);
+        }
+
         // Stream: step done — read retries/violations from active-build state
         // (syncStepHistory has already written them above)
         {
@@ -990,6 +1307,8 @@ export async function runBuild(featureCode, opts = {}) {
             type: 'build_gate_resolved',
             stepId, outcome: 'approve', rationale: policy.reason, flowId, policyMode: 'skip',
           });
+          // COMP-PLAN-SECTIONS T6: emit sections after plan_gate auto-approve
+          maybeEmitSectionsAfterPlanGate(stepId, featureDir, { streamWriter, featureCode });
           stepHistory.push({ stepId, artifact: null, summary: `Gate skip: ${policy.reason}`, outcome: 'approve' });
           syncStepHistory(dataDir, stepHistory);
 
@@ -1001,6 +1320,8 @@ export async function runBuild(featureCode, opts = {}) {
             type: 'build_gate_resolved',
             stepId, outcome: 'approve', rationale: policy.reason, flowId, policyMode: 'flag',
           });
+          // COMP-PLAN-SECTIONS T6: emit sections after plan_gate auto-approve
+          maybeEmitSectionsAfterPlanGate(stepId, featureDir, { streamWriter, featureCode });
           stepHistory.push({ stepId, artifact: null, summary: `Gate flag: ${policy.reason}`, outcome: 'approve' });
           syncStepHistory(dataDir, stepHistory);
 
@@ -1016,7 +1337,7 @@ export async function runBuild(featureCode, opts = {}) {
           progress.pause();
           console.log(`\nGate: ${stepId}`);
 
-          const askAgent = makeAskAgent(getConnector, context, response, gateExtras);
+          const askAgent = makeAskAgent(stratum, context, response, gateExtras);
           const serverUp = await probeServer();
           let outcome, rationale;
 
@@ -1066,6 +1387,10 @@ export async function runBuild(featureCode, opts = {}) {
           clearAmbientContextCache(contextDirPath);
 
           response = await stratum.gateResolve(flowId, stepId, outcome, rationale, 'human');
+          // COMP-PLAN-SECTIONS T6: emit sections after plan_gate human approve
+          if (outcome === 'approve') {
+            maybeEmitSectionsAfterPlanGate(stepId, featureDir, { streamWriter, featureCode });
+          }
           progress.resume();
 
           // COMP-UX-3c: concise gate resolution narration
@@ -1170,7 +1495,7 @@ export async function runBuild(featureCode, opts = {}) {
         }
 
         let childResult = await executeChildFlow(
-          response, stratum, getConnector, context,
+          response, stratum, context,
           visionWriter, itemId, dataDir, opts.gateOpts ?? {}, progress,
           streamWriter
         );
@@ -1183,7 +1508,7 @@ export async function runBuild(featureCode, opts = {}) {
             mergedResult,
             context.filesChanged ?? [],
             agentCwd,
-            getConnector,
+            stratum,
             streamWriter,
             opts
           );
@@ -1228,12 +1553,31 @@ export async function runBuild(featureCode, opts = {}) {
 
           // COMP-UX-3c: 1-line iteration summary
           const iterN = ((currentState?.retries) || 0) + 1;
-          const maxIter = 3; // stratum default max retries
+          // COMP-FIX-HARD T5: read cap from YAML; default to 3 when unspecified.
+          const capStepId = response.step_id ?? stepId;
+          const maxIter = retriesCap.get(capStepId) ?? 3;
           const topViolation = violationList[0] ?? 'postcondition failed';
           const iterSummary = typeof topViolation === 'string'
             ? topViolation
             : (topViolation.message ?? topViolation.text ?? JSON.stringify(topViolation));
-          console.log(`  Iteration ${iterN}/${maxIter} (${response.step_id ?? stepId}): ${iterSummary.slice(0, 80)}`);
+          console.log(`  Iteration ${iterN}/${maxIter} (${capStepId}): ${iterSummary.slice(0, 80)}`);
+
+          // COMP-FIX-HARD T5: force-terminate when cap exceeded.
+          // Stratum's `retries` field is declarative-only; Compose enforces it here.
+          if (iterN > maxIter) {
+            console.log(`  Retry cap exceeded for ${capStepId} (${iterN} > ${maxIter}). Terminating.`);
+            // In bug mode for diagnostic/fix/test steps, emit a checkpoint
+            // so the user can resume with full context.
+            if (context.mode === 'bug' && (capStepId === 'test' || capStepId === 'fix' || capStepId === 'diagnose')) {
+              try {
+                await emitCheckpoint(context, capStepId, response);
+              } catch (err) {
+                console.warn(`[retry-cap] emitCheckpoint failed: ${err?.message || err}`);
+              }
+            }
+            buildStatus = 'failed';
+            break;
+          }
         }
         progress.retry('build', stepId, response.agent);
         const violations = response.violations ?? [];
@@ -1248,12 +1592,38 @@ export async function runBuild(featureCode, opts = {}) {
         }
         const retryStepId = response.step_id ?? stepId;
         const agentType = response.agent ?? 'claude';
-        const prompt = buildRetryPrompt(response, violations, context, response.conflicts);
-        const connector = getConnector(agentType, { cwd: agentCwd });
+        const baseRetryPrompt = buildRetryPrompt(response, violations, context, response.conflicts);
         const retryTimeout = STEP_TIMEOUT_MS[retryStepId] ?? DEFAULT_TIMEOUT_MS;
+
+        // MF-1/SF-4: Prepend shared review scaffold on retries when this is a review step.
+        // SF-1 (iter 3): mirror main-path reduce_mode gating so merge-step retries don't get reviewer framing.
+        const isReviewRetry = response.review_mode === true
+          || response.inputs?.review_mode === 'true'
+          || response.output_contract === 'ReviewResult';
+        const isReduceRetry = response.inputs?.reduce_mode === 'true';
+        const isReviewScaffoldRetry = isReviewRetry && !isReduceRetry;
+        const confGateRetry = Number(response.inputs?.confidence_gate ?? response.confidence_gate ?? 7);
+        let prompt = baseRetryPrompt;
+        if (isReviewScaffoldRetry) {
+          prompt = buildReviewPrompt({
+            agentType,
+            lens: 'general',
+            lensFocus: '',
+            exclusions: '',
+            confidenceGate: confGateRetry,
+            taskDescription: response.inputs?.task ?? '',
+            blueprint: response.inputs?.blueprint ?? '',
+          }) + '\n\n' + baseRetryPrompt;
+        }
+
         let retryResult;
         try {
-          retryResult = await runAndNormalize(connector, prompt, response, { progress, streamWriter, maxDurationMs: retryTimeout });
+          retryResult = await runAndNormalize(null, prompt, response, {
+            progress, streamWriter, maxDurationMs: retryTimeout, stratum, cwd: agentCwd,
+            reviewMode: isReviewRetry,
+            confidenceGate: confGateRetry,
+            lens: response.inputs?.lens_name ?? response.lens_name ?? 'general',
+          });
         } catch (err) {
           if (err instanceof AgentTimeoutError) {
             console.warn(`\n⚠ Agent timed out on retry "${retryStepId}" after ${Math.round(err.durationMs / 1000)}s`);
@@ -1291,8 +1661,14 @@ export async function runBuild(featureCode, opts = {}) {
         // Debug discipline enforcement on retry (COMP-DEBUG-1)
         if (retryStepId === 'fix' || retryStepId === 'diagnose') {
           const filesChanged = extractFilesChanged({ result });
-          fixChainDetector.recordIteration(filesChanged);
-          attemptCounter.record({ filesChanged });
+          // COMP-FIX-HARD T9: per-bug keying when running in bug mode.
+          if (context.mode === 'bug' && context.bug_code) {
+            fixChainDetector.recordIterationForBug(context.bug_code, filesChanged);
+            attemptCounter.recordForBug(context.bug_code, { filesChanged });
+          } else {
+            fixChainDetector.recordIteration(filesChanged);
+            attemptCounter.record({ filesChanged });
+          }
 
           // Validate trace evidence on diagnose retries
           if (retryStepId === 'diagnose' && result) {
@@ -1308,21 +1684,32 @@ export async function runBuild(featureCode, opts = {}) {
             }
           }
 
-          const chains = fixChainDetector.detect();
-          const intervention = attemptCounter.getIntervention();
+          const isBugMode = context.mode === 'bug' && !!context.bug_code;
+          const chains = isBugMode
+            ? fixChainDetector.detectForBug(context.bug_code)
+            : fixChainDetector.detect();
+          const intervention = isBugMode
+            ? attemptCounter.getInterventionForBug(context.bug_code)
+            : attemptCounter.getIntervention();
+          const attemptCount = isBugMode
+            ? attemptCounter.getCountForBug(context.bug_code)
+            : attemptCounter.count;
+          const attemptIsVisual = isBugMode
+            ? (attemptCounter.byBug.get(context.bug_code)?.isVisual ?? false)
+            : attemptCounter.isVisual;
 
           if (chains.length > 0) {
             debugLedger.record({ type: 'fix_chain_detected', chains });
           }
 
           if (intervention === 'escalate') {
-            debugLedger.record({ type: 'escalation', attempt: attemptCounter.count, isVisual: attemptCounter.isVisual });
-            if (streamWriter) streamWriter.write({ type: 'build_error', message: `Debug discipline: escalating after ${attemptCounter.count} attempts. Dispatching to cross-agent review.` });
+            debugLedger.record({ type: 'escalation', attempt: attemptCount, isVisual: attemptIsVisual });
+            if (streamWriter) streamWriter.write({ type: 'build_error', message: `Debug discipline: escalating after ${attemptCount} attempts. Dispatching to cross-agent review.` });
           } else if (intervention === 'trace_refresh') {
-            debugLedger.record({ type: 'trace_refresh_required', attempt: attemptCounter.count });
-            if (progress) progress.warn(`Debug discipline: ${attemptCounter.count} attempts — fresh trace evidence required before next fix`);
+            debugLedger.record({ type: 'trace_refresh_required', attempt: attemptCount });
+            if (progress) progress.warn(`Debug discipline: ${attemptCount} attempts — fresh trace evidence required before next fix`);
           } else if (intervention === 'trace_reminder') {
-            if (progress) progress.warn(`Debug discipline: ${attemptCounter.count} attempts on same target — verify trace evidence is current`);
+            if (progress) progress.warn(`Debug discipline: ${attemptCount} attempts on same target — verify trace evidence is current`);
           }
 
           // Persist debug state
@@ -1344,7 +1731,6 @@ export async function runBuild(featureCode, opts = {}) {
           response = await executeParallelDispatch(
             response,
             stratum,
-            getConnector,
             context,
             progress,
             streamWriter,
@@ -1370,8 +1756,11 @@ export async function runBuild(featureCode, opts = {}) {
     if (response.status === 'complete' && buildStatus === 'complete') {
       console.log('\nBuild complete.');
       await visionWriter.updateItemStatus(itemId, 'complete');
-      // COMP-QA: persist filesChanged so `compose qa-scope` can read them post-build
-      updateFeature(cwd, featureCode, { status: 'COMPLETE', filesChanged: context.filesChanged ?? [] });
+      // 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) {
+        updateFeature(cwd, featureCode, { status: 'COMPLETE', filesChanged: context.filesChanged ?? [] });
+      }
       const termState = readActiveBuild(dataDir);
       if (termState) {
         writeActiveBuild(dataDir, { ...termState, status: 'complete', completedAt: new Date().toISOString() });
@@ -1381,7 +1770,7 @@ export async function runBuild(featureCode, opts = {}) {
       buildStatus = 'killed';
       console.log('\nBuild killed.');
       await visionWriter.updateItemStatus(itemId, 'killed');
-      updateFeature(cwd, featureCode, { status: 'PLANNED' });
+      if (!isBugMode) updateFeature(cwd, featureCode, { status: 'PLANNED' });
       const termState = readActiveBuild(dataDir);
       if (termState) {
         writeActiveBuild(dataDir, { ...termState, status: 'aborted', completedAt: new Date().toISOString() });
@@ -1390,7 +1779,7 @@ export async function runBuild(featureCode, opts = {}) {
       // Ship failure or other explicit failure — write terminal state
       console.log('\nBuild failed.');
       await visionWriter.updateItemStatus(itemId, 'failed');
-      updateFeature(cwd, featureCode, { status: 'PLANNED' });
+      if (!isBugMode) updateFeature(cwd, featureCode, { status: 'PLANNED' });
       const termState = readActiveBuild(dataDir);
       if (termState) {
         writeActiveBuild(dataDir, { ...termState, status: 'failed', completedAt: new Date().toISOString() });
@@ -1515,7 +1904,7 @@ export async function runBuild(featureCode, opts = {}) {
           join(featureDir, 'audit.json'),
           JSON.stringify(response, null, 2)
         );
-        console.log(`Audit trace written to docs/features/${featureCode}/audit.json`);
+        console.log(`Audit trace written to ${isBugMode ? 'docs/bugs' : 'docs/features'}/${featureCode}/audit.json`);
       } catch (err) {
         console.warn(`Warning: could not write audit trace: ${err.message}`);
       }
@@ -1528,7 +1917,7 @@ export async function runBuild(featureCode, opts = {}) {
           join(featureDir, 'audit.json'),
           JSON.stringify(audit, null, 2)
         );
-        console.log(`Audit trace written to docs/features/${featureCode}/audit.json`);
+        console.log(`Audit trace written to ${isBugMode ? 'docs/bugs' : 'docs/features'}/${featureCode}/audit.json`);
       } catch (err) {
         console.warn(`Warning: could not write audit trace: ${err.message}`);
       }
@@ -1554,6 +1943,47 @@ export async function runBuild(featureCode, opts = {}) {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * COMP-PLAN-SECTIONS T6 — emit per-task section files after a plan_gate approve.
+ *
+ * Called from each of the three plan_gate approve branches (skip / flag / human).
+ * No-op for any other gate. No-op if the plan is below the threshold (the
+ * underlying emitSections handles that). On success, emits a build_sections_emitted
+ * stream event with the created/skipped lists.
+ *
+ * @param {string} stepId — the gate stepId (must be 'plan_gate' to fire)
+ * @param {string} featureDir — absolute feature directory
+ * @param {object} opts
+ * @param {object} [opts.streamWriter] — build stream writer
+ * @param {string} [opts.featureCode] — feature code, included in event
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function maybeEmitSectionsAfterPlanGate(stepId, featureDir, opts = {}) {
+  const empty = { created: [], skipped: [] };
+  if (stepId !== 'plan_gate' || !featureDir) return empty;
+  let result = empty;
+  try {
+    result = emitPlanSections(featureDir);
+  } catch (err) {
+    // Section emission must never break the build.
+    if (opts.streamWriter) {
+      try { opts.streamWriter.write({ type: 'build_error', message: `sections emit failed: ${err.message}`, stepId }); } catch { /* ignore */ }
+    }
+    return empty;
+  }
+  if (result.created.length > 0 && opts.streamWriter) {
+    try {
+      opts.streamWriter.write({
+        type: 'build_sections_emitted',
+        featureCode: opts.featureCode ?? null,
+        created: result.created,
+        skipped: result.skipped,
+      });
+    } catch { /* ignore */ }
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Ship step — runs git commit in-process (not via agent)
 // ---------------------------------------------------------------------------
@@ -1562,8 +1992,11 @@ export async function runBuild(featureCode, opts = {}) {
  * Execute the ship step: run tests, stage feature files, commit.
  * Returns a PhaseResult-shaped object.
  */
-async function executeShipStep(featureCode, agentCwd, cwd, context, description, progress) {
-  const featureDir = `docs/features/${featureCode}`;
+export async function executeShipStep(featureCode, agentCwd, cwd, context, description, progress) {
+  // COMP-FIX-HARD T4: bug mode stages docs/bugs/<code>/ instead of docs/features/<code>/
+  const featureDir = context?.mode === 'bug'
+    ? `docs/bugs/${featureCode}`
+    : `docs/features/${featureCode}`;
 
   try {
     // 0. Check if we're in a git repository — if not, skip git operations
@@ -1638,7 +2071,7 @@ async function executeShipStep(featureCode, agentCwd, cwd, context, description,
     if (progress) progress.toolUse('ship', `Staging ${featureFiles.length} files...`);
     for (const f of featureFiles) {
       try {
-        execSync(`git add "${f}"`, { cwd: agentCwd, encoding: 'utf-8', timeout: 5000 });
+        execFileSync('git', ['add', '--', f], { cwd: agentCwd, encoding: 'utf-8', timeout: 5000 });
       } catch { /* file might not exist or already staged */ }
     }
 
@@ -1662,23 +2095,49 @@ async function executeShipStep(featureCode, agentCwd, cwd, context, description,
 
     // 6. Commit
     if (progress) progress.toolUse('ship', 'Committing...');
-    execSync(`git commit -m "${commitMsg.replace(/"/g, '\\"')}"`, {
+    execFileSync('git', ['commit', '-m', commitMsg], {
       cwd: agentCwd, encoding: 'utf-8', timeout: 30_000,
     });
 
-    // 7. Get the commit SHA
-    const sha = execSync('git rev-parse HEAD', {
-      cwd: agentCwd, encoding: 'utf-8', timeout: 5000,
-    }).trim();
-
+    // 7. Best-effort post-commit metadata collection.
+    // Each call is wrapped in its own try/catch — metadata failures must NEVER
+    // downgrade the ship outcome from 'complete' to 'failed'. Empty fields
+    // (commit:null, filesChanged:[]) are acceptable.
     const stagedFiles = staged.split('\n').filter(Boolean);
-    if (progress) progress.toolUse('ship', `Committed ${sha.slice(0, 8)} (${stagedFiles.length} files)`);
+
+    let sha = null;
+    try {
+      sha = execSync('git rev-parse HEAD', {
+        cwd: agentCwd, encoding: 'utf-8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'],
+      }).trim() || null;
+    } catch { /* metadata best-effort */ }
+
+    if (progress) {
+      progress.toolUse('ship', sha
+        ? `Committed ${sha.slice(0, 8)} (${stagedFiles.length} files)`
+        : `Committed (${stagedFiles.length} files)`);
+    }
+
+    // COMP-PLAN-SECTIONS T5: filesChanged from `git show --name-only`. Best-effort.
+    let filesChanged = [];
+    try {
+      const namesOnly = execSync('git show --name-only --pretty=format: HEAD', {
+        cwd: agentCwd, encoding: 'utf-8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'],
+      }).trim();
+      filesChanged = namesOnly.split('\n').map(s => s.trim()).filter(Boolean);
+    } 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;
 
     return {
       phase: 'ship',
-      artifact: sha,
+      artifact: sha ?? '',
       outcome: 'complete',
-      summary: `Committed ${sha.slice(0, 8)}: ${commitMsg} (${stagedFiles.length} files)`,
+      summary: sha
+        ? `Committed ${sha.slice(0, 8)}: ${commitMsg} (${stagedFiles.length} files)`
+        : `Committed: ${commitMsg} (${stagedFiles.length} files)`,
+      commit: sha,
+      filesChanged,
     };
 
   } catch (err) {
@@ -1696,22 +2155,24 @@ async function executeShipStep(featureCode, agentCwd, cwd, context, description,
 // ---------------------------------------------------------------------------
 
 /**
- * Run Codex review of the diff and synthesize findings with Claude's MergedReviewResult.
+ * Run Codex review of the diff and synthesize findings with Claude's ReviewResult.
  *
  * Opt-out: pass opts.skipCrossModel=true or set COMPOSE_CROSS_MODEL=0 env var.
- * Graceful skip: if CodexConnector construction fails (opencode not installed).
  *
- * @param {object} mergedResult       - MergedReviewResult from the parallel_review child flow
+ * Synthesis output is a CrossModelReviewResult — a canonical ReviewResult extended with
+ * consensus/claude_only/codex_only arrays of canonical finding items (STRAT-XMODEL-PARITY).
+ *
+ * @param {object} mergedResult       - ReviewResult from the parallel_review child flow
  * @param {string[]} filesChanged     - list of changed file paths
  * @param {string} cwd                - working directory
- * @param {object} getConnector       - connector factory
+ * @param {object} stratum            - StratumMcpClient
  * @param {BuildStreamWriter|null} streamWriter
  * @param {object} opts
  * @param {boolean} [opts.skipCrossModel]  - explicit opt-out
- * @returns {Promise<object>} updated MergedReviewResult with crossModelSynthesis field,
+ * @returns {Promise<object>} updated ReviewResult with crossModelSynthesis field,
  *                            or original mergedResult if skipped
  */
-async function runCrossModelReview(mergedResult, filesChanged, cwd, getConnector, streamWriter, opts = {}) {
+async function runCrossModelReview(mergedResult, filesChanged, cwd, stratum, streamWriter, opts = {}) {
   // --- Opt-out checks ---
   if (opts.skipCrossModel) {
     if (streamWriter) streamWriter.write({ type: 'cross_model_review', status: 'skipped', reason: 'skipCrossModel flag set' });
@@ -1725,17 +2186,6 @@ async function runCrossModelReview(mergedResult, filesChanged, cwd, getConnector
     return mergedResult; // small/medium diff — skip silently
   }
 
-  // --- Codex availability check ---
-  let codexConnector;
-  try {
-    codexConnector = new CodexConnector({ cwd });
-  } catch (err) {
-    const msg = `cross-model review skipped: Codex unavailable (${err.message})`;
-    console.warn(`  [cross-model] ${msg}`);
-    if (streamWriter) streamWriter.write({ type: 'cross_model_review', status: 'skipped', reason: msg });
-    return mergedResult;
-  }
-
   if (streamWriter) {
     streamWriter.write({ type: 'cross_model_review', status: 'started', filesChanged: filesChanged.length });
   }
@@ -1756,10 +2206,12 @@ async function runCrossModelReview(mergedResult, filesChanged, cwd, getConnector
   let codexFindings = [];
   try {
     const codexTimeout = STEP_TIMEOUT_MS.codex_review ?? 10 * 60_000;
-    const syntheticStep = { step_id: 'codex_review', ensure: [], output_fields: {} };
-    const { text: codexText } = await runAndNormalize(codexConnector, codexPrompt, syntheticStep, {
+    const syntheticStep = { step_id: 'codex_review', agent: 'codex', ensure: [], output_fields: {} };
+    const { text: codexText } = await runAndNormalize(null, codexPrompt, syntheticStep, {
       streamWriter,
       maxDurationMs: codexTimeout,
+      stratum,
+      cwd,
     });
 
     // Parse findings: look for a JSON array in the response text
@@ -1791,7 +2243,7 @@ async function runCrossModelReview(mergedResult, filesChanged, cwd, getConnector
   const claudeFindings = mergedResult.findings ?? [];
   const synthesisPrompt =
     `You are synthesizing code review findings from two models.\n\n` +
-    `## Claude findings (structured LensFinding objects)\n` +
+    `## Claude findings (ReviewResult finding items — {lens, file, line, severity, finding, confidence, applied_gate})\n` +
     JSON.stringify(claudeFindings, null, 2) +
     `\n\n## Codex findings (plain strings)\n` +
     JSON.stringify(codexFindings, null, 2) +
@@ -1800,49 +2252,60 @@ async function runCrossModelReview(mergedResult, filesChanged, cwd, getConnector
     `- CONSENSUS: both models flagged the same issue (same file, similar concern)\n` +
     `- CLAUDE_ONLY: only Claude found it\n` +
     `- CODEX_ONLY: only Codex found it\n\n` +
-    `Return a JSON object with this exact shape:\n` +
+    `Return a JSON object matching the CrossModelReviewResult schema with this exact shape:\n` +
     `{\n` +
-    `  "consensus": [<LensFinding objects from Claude, with codexNote field added>],\n` +
-    `  "claude_only": [<LensFinding objects>],\n` +
-    `  "codex_only": [{"file":"?","line":0,"severity":"medium","finding":"<codex text>","confidence":70,"source":"codex"}]\n` +
+    `  "summary": "<1-3 sentence narrative>",\n` +
+    `  "consensus": [<canonical finding items from Claude, severity in {must-fix,should-fix,nit}, confidence 1-10, applied_gate 1-10>],\n` +
+    `  "claude_only": [<canonical finding items, same shape>],\n` +
+    `  "codex_only": [{"lens":"general","file":null,"line":null,"severity":"should-fix","finding":"<codex text>","confidence":7,"applied_gate":7}]\n` +
     `}\n\n` +
-    `For CODEX_ONLY findings, create LensFinding-shaped objects with file="" if the file is not clear.\n` +
+    `Each finding item MUST have: lens (string), file (string|null), line (integer|null), ` +
+    `severity ("must-fix"|"should-fix"|"nit"), finding (string), confidence (1-10 integer), applied_gate (1-10 integer).\n` +
+    `For CODEX_ONLY findings, create canonical finding-shaped objects with file=null if the file is not clear.\n` +
     `Output ONLY the JSON object, no prose.`;
 
-  // Fallback preserves Codex findings as codex_only so they're never silently dropped
-  const codexAsFallback = codexFindings.map(f => ({ file: '', line: 0, severity: 'medium', finding: f, confidence: 60, source: 'codex' }));
-  let synthesis = { consensus: [], claude_only: claudeFindings, codex_only: codexAsFallback };
+  // Fallback preserves Codex findings as codex_only so they're never silently dropped.
+  // Emits canonical ReviewResult finding shape (severity ∈ {must-fix,should-fix,nit}, confidence 1-10, applied_gate).
+  const codexAsFallback = codexFindings.map(f => ({
+    lens: 'general',
+    file: null,
+    line: null,
+    severity: 'should-fix',
+    finding: typeof f === 'string' ? f : (f?.finding ?? String(f)),
+    confidence: 7,  // at gate — guarantees fallback findings survive confidence filtering
+    applied_gate: 7,
+    source: 'codex',
+  }));
+
+  let synthText = '';
   try {
-    const claudeConnector = getConnector('claude', { cwd });
-    const syntheticStep = { step_id: 'synthesis', ensure: [], output_fields: {} };
-    const { text: synthText } = await runAndNormalize(claudeConnector, synthesisPrompt, syntheticStep, {
+    const syntheticStep = { step_id: 'synthesis', agent: 'claude', ensure: [], output_fields: {} };
+    const result = await runAndNormalize(null, synthesisPrompt, syntheticStep, {
       streamWriter,
       maxDurationMs: 3 * 60_000,
+      stratum,
+      cwd,
     });
-
-    const synthMatch = synthText.match(/\{[\s\S]*\}/);
-    if (synthMatch) {
-      try {
-        const parsed = JSON.parse(synthMatch[0]);
-        if (parsed && typeof parsed === 'object') {
-          synthesis = {
-            consensus:    Array.isArray(parsed.consensus)    ? parsed.consensus    : [],
-            claude_only:  Array.isArray(parsed.claude_only)  ? parsed.claude_only  : claudeFindings,
-            codex_only:   Array.isArray(parsed.codex_only)   ? parsed.codex_only   : codexAsFallback,
-          };
-        }
-      } catch { /* keep fallback */ }
-    }
+    synthText = result.text;
   } catch (err) {
     console.warn(`  [cross-model] synthesis error: ${err.message}`);
-    // Fall through with default synthesis
+    // Fall through — normalizeCrossModelResult will use the fallback arrays
   }
 
-  const allFindings = [
-    ...synthesis.consensus,
-    ...synthesis.claude_only,
-    ...synthesis.codex_only,
-  ];
+  // Route synthesis output through canonical normalizer (STRAT-XMODEL-PARITY).
+  // Wire repairFn so malformed synthesis JSON gets one repair-retry before degrading to fallback.
+  const synthesis = await normalizeCrossModelResult(synthText, {
+    confidenceGate: 7,
+    claudeFindingsFallback: claudeFindings,
+    codexFindingsFallback: codexAsFallback,
+    repairFn: async (repairPrompt) => {
+      const { text } = await runAndNormalize(null, repairPrompt, {
+        step_id: 'synthesis_repair', agent: 'claude', ensure: [], output_fields: {},
+      }, { stratum, cwd, maxDurationMs: 90_000 });
+      return text;
+    },
+  });
+
   const consensusCount  = synthesis.consensus.length;
   const claudeOnlyCount = synthesis.claude_only.length;
   const codexOnlyCount  = synthesis.codex_only.length;
@@ -1859,10 +2322,14 @@ async function runCrossModelReview(mergedResult, filesChanged, cwd, getConnector
 
   return {
     ...mergedResult,
-    clean: allFindings.length === 0,
-    summary: `Cross-model synthesis: ${consensusCount} consensus, ${claudeOnlyCount} Claude-only, ${codexOnlyCount} Codex-only`,
-    findings: allFindings,
-    crossModelSynthesis: synthesis,
+    clean:    synthesis.clean,
+    summary:  synthesis.summary,
+    findings: synthesis.findings,
+    crossModelSynthesis: {
+      consensus:  synthesis.consensus,
+      claude_only: synthesis.claude_only,
+      codex_only:  synthesis.codex_only,
+    },
   };
 }
 
@@ -1872,7 +2339,7 @@ async function runCrossModelReview(mergedResult, filesChanged, cwd, getConnector
  * including nested execute_flow (recursive).
  */
 async function executeChildFlow(
-  flowDispatch, stratum, getConnector, context,
+  flowDispatch, stratum, context,
   visionWriter, itemId, dataDir, gateOpts, progress,
   streamWriter
 ) {
@@ -1906,14 +2373,13 @@ async function executeChildFlow(
 
       const agentType = resp.agent ?? 'claude';
       const prompt = buildStepPrompt(resp, context);
-      const connector = getConnector(agentType, { cwd: context.cwd });
       const childStepTimeout = STEP_TIMEOUT_MS[resp.step_id] ?? DEFAULT_TIMEOUT_MS;
       // COMP-CAPS-ENFORCE: tap tool_use events in child flow steps too
       const childObservedTools = [];
       const childOnToolUse = (ev) => childObservedTools.push(ev);
       let childMainResult;
       try {
-        childMainResult = await runAndNormalize(connector, prompt, resp, { progress, streamWriter, maxDurationMs: childStepTimeout, onToolUse: childOnToolUse });
+        childMainResult = await runAndNormalize(null, prompt, resp, { progress, streamWriter, maxDurationMs: childStepTimeout, onToolUse: childOnToolUse, stratum, cwd: context.cwd });
       } catch (err) {
         if (err instanceof UserInterruptError) {
           if (err.action === 'skip') {
@@ -1936,19 +2402,42 @@ async function executeChildFlow(
       const completedStepId = resp.step_id;
 
       // Emit capability_profile event for child step (informational, never blocking)
-      if (streamWriter) {
+      {
         const { template: childTemplate, allowedTools: childAllowed, disallowedTools: childDisallowed } = resolveAgentConfig(agentType);
-        if (childTemplate) {
+        if (streamWriter && childTemplate) {
           streamWriter.writeCapabilityProfile(completedStepId, agentType, childTemplate, childAllowed, childDisallowed);
         }
-        // COMP-CAPS-ENFORCE: check child step tool_use events against template
+
+        // COMP-CAPS-ENFORCE + COMP-AGENT-CAPS-6: check child step tool_use events against
+        // template and enforce block mode — mirrors the main-path enforcement block (lines 763-794).
+        const childCapViolations = [];
         for (const ev of childObservedTools) {
           const check = checkCapabilityViolation(ev.tool, agentType);
           if (check.violation) {
-            streamWriter.writeViolation(completedStepId, agentType, childTemplate, `${ev.tool}: ${check.reason}`);
+            childCapViolations.push({ tool: ev.tool, severity: check.severity, reason: check.reason });
+            if (streamWriter) {
+              streamWriter.writeViolation(completedStepId, agentType, childTemplate, `${ev.tool}: ${check.reason}`, check.severity);
+            }
             console.log(`  [caps] ${ev.tool} used by ${agentType} — violates ${childTemplate} profile`);
           }
         }
+
+        // COMP-AGENT-CAPS-6: enforce block mode for child-flow steps (was log-only before).
+        const childEnforcement = (() => {
+          try {
+            const childSettingsPath = join(dataDir, 'settings.json');
+            if (existsSync(childSettingsPath)) {
+              const s = JSON.parse(readFileSync(childSettingsPath, 'utf-8'));
+              return s?.capabilities?.enforcement ?? 'log';
+            }
+          } catch { /* degraded — default to log */ }
+          return 'log';
+        })();
+        if (childEnforcement === 'block' && childCapViolations.length > 0) {
+          const tools = childCapViolations.map(v => v.tool).join(', ');
+          throw new StratumError('CAPABILITY_VIOLATION',
+            `Child step "${completedStepId}" used disallowed tools: ${tools}`, completedStepId);
+        }
       }
 
       // Accumulate child step results into shared stepHistory
@@ -1966,6 +2455,10 @@ async function executeChildFlow(
         result ?? { summary: 'Step complete' }
       );
 
+      // COMP-FIX-HARD T6: record accepted hypothesis on diagnose success (bug mode only).
+      // Child-flow call site, paired with the top-level call site near `:989`.
+      recordDiagnoseSuccessIfBugMode(context, { step_id: completedStepId }, result);
+
       // Stream: child step done
       if (streamWriter) {
         streamWriter.write({
@@ -1996,7 +2489,7 @@ async function executeChildFlow(
       if (progress) progress.pause();
       console.log(`  [${childFlowName}] Gate: ${resp.step_id}`);
       const gateId = await visionWriter.createGate(childFlowId, resp.step_id, itemId);
-      const childAskAgent = makeAskAgent(getConnector, context, resp, null);
+      const childAskAgent = makeAskAgent(stratum, context, resp, null);
 
       const childGateExtras = {
         fromPhase: resp.from_phase ?? null,
@@ -2068,10 +2561,10 @@ async function executeChildFlow(
         violations.map(v => `- ${v}`).join('\n') + '\n\n' +
         `Fix every issue. Do not skip any.\n\n` +
         `## Context\nWorking directory: ${context.cwd}\nFeature: ${context.featureCode}`;
-      const fixConnector = getConnector(fixAgent, { cwd: context.cwd });
       const fixTimeout = STEP_TIMEOUT_MS[resp.step_id] ?? DEFAULT_TIMEOUT_MS;
+      const fixDispatch = { ...resp, agent: fixAgent };
       try {
-        await runAndNormalize(fixConnector, fixPrompt, resp, { progress, streamWriter, maxDurationMs: fixTimeout });
+        await runAndNormalize(null, fixPrompt, fixDispatch, { progress, streamWriter, maxDurationMs: fixTimeout, stratum, cwd: context.cwd });
       } catch (err) {
         if (!(err instanceof AgentTimeoutError)) throw err;
         console.warn(`\n⚠ Fix agent timed out on "${resp.step_id}"`);
@@ -2083,10 +2576,9 @@ async function executeChildFlow(
         console.log(`  [${childFlowName}] ↻ Retrying ${resp.step_id} (${stepAgent})`);
       }
       const prompt = buildRetryPrompt(resp, violations, context, resp.conflicts);
-      const connector = getConnector(stepAgent, { cwd: context.cwd });
       let childRetryResult;
       try {
-        childRetryResult = await runAndNormalize(connector, prompt, resp, { progress, streamWriter, maxDurationMs: fixTimeout });
+        childRetryResult = await runAndNormalize(null, prompt, resp, { progress, streamWriter, maxDurationMs: fixTimeout, stratum, cwd: context.cwd });
       } catch (err) {
         if (err instanceof AgentTimeoutError) {
           console.warn(`\n⚠ Retry agent timed out on "${resp.step_id}"`);
@@ -2105,7 +2597,7 @@ async function executeChildFlow(
       const nestedParentFlowId = resp.parent_flow_id;
       const nestedParentStepId = resp.parent_step_id;
       const nestedResult = await executeChildFlow(
-        resp, stratum, getConnector, context,
+        resp, stratum, context,
         visionWriter, itemId, dataDir, gateOpts, progress,
         streamWriter
       );
@@ -2118,7 +2610,6 @@ async function executeChildFlow(
       resp = await executeParallelDispatch(
         resp,
         stratum,
-        getConnector,
         context,
         progress,
         streamWriter,
@@ -2235,87 +2726,76 @@ export async function executeParallelDispatchServer(
     );
   }
 
-  // Poll until outcome is present (NOT can_advance — see design §3)
-  let pollResult;
-  const intervalMs = SERVER_DISPATCH_POLL_MS();
-  while (true) {
-    pollResult = await stratum.parallelPoll(flowId, stepId);
-    if (pollResult?.error) {
-      throw new Error(
-        `stratum_parallel_poll failed: ${pollResult.error}: ${pollResult.message || ''}`,
-      );
-    }
-    emitPerTaskProgress(streamWriter, pollResult, emittedStates);
-    if (pollResult.outcome != null) break;
-    await new Promise((resolve) => setTimeout(resolve, intervalMs));
-  }
-
-  if (pollResult.outcome.status === 'already_advanced') {
-    throw new Error(
-      `stratum_parallel_poll returned already_advanced for step ${stepId} — ` +
-      `flow state desync. Aggregate: ${JSON.stringify(pollResult.outcome.aggregate)}`,
-    );
+  // STRAT-PAR-STREAM: subscribe to push events for this scope before polling.
+  // Push events are best-effort transient narration; poll remains the canonical
+  // state-machine driver. Forward valid events through streamWriter so the
+  // bridge rebroadcasts them via SSE under the buildStreamEvent wrapper.
+  let unsubscribePush = null;
+  if (typeof stratum.onEvent === 'function' && streamWriter) {
+    unsubscribePush = stratum.onEvent(flowId, stepId, (event) => {
+      if (!event || event.schema_version !== '0.2.5') return;
+      try {
+        streamWriter.write({ type: 'build_stream_event', event });
+      } catch (err) {
+        console.error('[build] failed to forward stream event:', err);
+      }
+    });
   }
 
-  // T2-F5-CONSUMER-MERGE-STATUS-COMPOSE: branch on defer-advance sentinel.
-  // hasServerMerge is true only when the spec declared both isolation:worktree AND capture_diff:true.
-  const isolation = dispatchResponse.isolation ?? 'worktree';
-  const hasServerMerge = isolation === 'worktree' && dispatchResponse.capture_diff === true;
-
-  // Defensive: spec declared defer_advance:true but misses the companions
-  // (isolation:worktree + capture_diff:true). The poll still returns the sentinel
-  // but we have nothing to merge. Call advance with 'clean' to unblock the flow
-  // before any worktree-merge block runs.
-  if (pollResult.outcome?.status === 'awaiting_consumer_advance' && !hasServerMerge) {
-    if (streamWriter) {
-      streamWriter.write({
-        type: 'build_error', stepId,
-        message:
-          `Spec declared defer_advance:true without (isolation:worktree + capture_diff:true); ` +
-          `no diffs to merge. Calling parallelAdvance with merge_status='clean' to unblock the flow.`,
-      });
+  try {
+    // Poll until outcome is present (NOT can_advance — see design §3)
+    let pollResult;
+    const intervalMs = SERVER_DISPATCH_POLL_MS();
+    while (true) {
+      pollResult = await stratum.parallelPoll(flowId, stepId);
+      if (pollResult?.error) {
+        throw new Error(
+          `stratum_parallel_poll failed: ${pollResult.error}: ${pollResult.message || ''}`,
+        );
+      }
+      emitPerTaskProgress(streamWriter, pollResult, emittedStates);
+      if (pollResult.outcome != null) break;
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
-    const advanceResult = await stratum.parallelAdvance(flowId, stepId, 'clean');
-    if (advanceResult?.error) {
+
+    if (pollResult.outcome.status === 'already_advanced') {
       throw new Error(
-        `stratum_parallel_advance failed: ${advanceResult.error}: ${advanceResult.message || ''}`,
+        `stratum_parallel_poll returned already_advanced for step ${stepId} — ` +
+        `flow state desync. Aggregate: ${JSON.stringify(pollResult.outcome.aggregate)}`,
       );
     }
-    pollResult.outcome = advanceResult;
-  }
 
-  if (hasServerMerge) {
-    if (pollResult.outcome?.status === 'awaiting_consumer_advance') {
-      // DEFER PATH: merge locally, report merge_status, let flow advance with truth.
-      const { mergeStatus, conflictedTaskId, conflictError } = applyServerDispatchDiffsCore(
-        dispatchResponse.tasks ?? [],
-        pollResult.tasks,
-        baseCwd,
-        streamWriter,
-        stepId,
-        context,
-      );
+    // T2-F5-CONSUMER-MERGE-STATUS-COMPOSE: branch on defer-advance sentinel.
+    // hasServerMerge is true only when the spec declared both isolation:worktree AND capture_diff:true.
+    const isolation = dispatchResponse.isolation ?? 'worktree';
+    const hasServerMerge = isolation === 'worktree' && dispatchResponse.capture_diff === true;
 
-      if (mergeStatus === 'conflict' && streamWriter) {
+    // Defensive: spec declared defer_advance:true but misses the companions
+    // (isolation:worktree + capture_diff:true). The poll still returns the sentinel
+    // but we have nothing to merge. Call advance with 'clean' to unblock the flow
+    // before any worktree-merge block runs.
+    if (pollResult.outcome?.status === 'awaiting_consumer_advance' && !hasServerMerge) {
+      if (streamWriter) {
         streamWriter.write({
           type: 'build_error', stepId,
           message:
-            `Client-side merge conflict on task ${conflictedTaskId}: ${conflictError}. ` +
-            `Reporting merge_status='conflict' to Stratum; flow will route through its failure handler.`,
+            `Spec declared defer_advance:true without (isolation:worktree + capture_diff:true); ` +
+            `no diffs to merge. Calling parallelAdvance with merge_status='clean' to unblock the flow.`,
         });
       }
-
-      const advanceResult = await stratum.parallelAdvance(flowId, stepId, mergeStatus);
+      const advanceResult = await stratum.parallelAdvance(flowId, stepId, 'clean');
       if (advanceResult?.error) {
         throw new Error(
           `stratum_parallel_advance failed: ${advanceResult.error}: ${advanceResult.message || ''}`,
         );
       }
       pollResult.outcome = advanceResult;
-    } else {
-      // LEGACY PATH: non-deferred spec. Throwing wrapper preserves pre-defer behavior.
-      try {
-        applyServerDispatchDiffs(
+    }
+
+    if (hasServerMerge) {
+      if (pollResult.outcome?.status === 'awaiting_consumer_advance') {
+        // DEFER PATH: merge locally, report merge_status, let flow advance with truth.
+        const { mergeStatus, conflictedTaskId, conflictError } = applyServerDispatchDiffsCore(
           dispatchResponse.tasks ?? [],
           pollResult.tasks,
           baseCwd,
@@ -2323,29 +2803,60 @@ export async function executeParallelDispatchServer(
           stepId,
           context,
         );
-      } catch (err) {
-        if (streamWriter) {
+
+        if (mergeStatus === 'conflict' && streamWriter) {
           streamWriter.write({
-            type: 'build_step_done', stepId,
-            parallel: true,
-            summary: { ...pollResult.summary, merge_status: 'conflict' },
-            flowId,
+            type: 'build_error', stepId,
+            message:
+              `Client-side merge conflict on task ${conflictedTaskId}: ${conflictError}. ` +
+              `Reporting merge_status='conflict' to Stratum; flow will route through its failure handler.`,
           });
         }
-        throw err;
+
+        const advanceResult = await stratum.parallelAdvance(flowId, stepId, mergeStatus);
+        if (advanceResult?.error) {
+          throw new Error(
+            `stratum_parallel_advance failed: ${advanceResult.error}: ${advanceResult.message || ''}`,
+          );
+        }
+        pollResult.outcome = advanceResult;
+      } else {
+        // LEGACY PATH: non-deferred spec. Throwing wrapper preserves pre-defer behavior.
+        try {
+          applyServerDispatchDiffs(
+            dispatchResponse.tasks ?? [],
+            pollResult.tasks,
+            baseCwd,
+            streamWriter,
+            stepId,
+            context,
+          );
+        } catch (err) {
+          if (streamWriter) {
+            streamWriter.write({
+              type: 'build_step_done', stepId,
+              parallel: true,
+              summary: { ...pollResult.summary, merge_status: 'conflict' },
+              flowId,
+            });
+          }
+          throw err;
+        }
       }
     }
-  }
 
-  if (streamWriter) {
-    streamWriter.write({
-      type: 'build_step_done', stepId,
-      parallel: true,
-      summary: pollResult.summary, flowId,
-    });
-  }
+    if (streamWriter) {
+      streamWriter.write({
+        type: 'build_step_done', stepId,
+        parallel: true,
+        summary: pollResult.summary, flowId,
+      });
+    }
 
-  return pollResult.outcome;
+    return pollResult.outcome;
+  } finally {
+    if (unsubscribePush) { try { unsubscribePush(); } catch { /* ignore */ } }
+  }
 }
 
 /**
@@ -2543,7 +3054,6 @@ function applyServerDispatchDiffs(taskList, pollTasks, baseCwd, streamWriter, st
 async function executeParallelDispatch(
   dispatchResponse,
   stratum,
-  getConnector,
   context,
   progress,
   streamWriter,
@@ -2638,13 +3148,10 @@ async function executeParallelDispatch(
         .replace(/\{confidence_gate\}/g, String(task.confidence_gate ?? ''))
         .replace(/\{exclusions\}/g, task.exclusions ?? '');
 
-      // STRAT-CERT: inject reasoning template for Claude-family agents (CERT-WIRE-1/7)
-      if (agentType.startsWith('claude') && task.lens_name) {
-        const lensDef = LENS_DEFINITIONS[task.lens_name];
-        if (lensDef?.reasoning_template) {
-          taskIntent = injectCertInstructions(taskIntent, lensDef.reasoning_template);
-        }
-      }
+      // STRAT-CERT / SF-NEW-3: cert (reasoning_template) injection for Claude lens tasks
+      // is done on the review scaffold below (line ~2720), NOT here.  Injecting here AND
+      // on the scaffold produced two "## Premises / ## Trace / ## Conclusion" blocks.
+      // The scaffold-side injection is the single source of truth for lens tasks.
 
       const syntheticDispatch = {
         step_id: taskId,
@@ -2670,10 +3177,46 @@ async function executeParallelDispatch(
       }
 
       try {
-        const prompt = buildStepPrompt(syntheticDispatch, context);
-        const connector = getConnector(agentType, { cwd: taskCwd });
+        const baseTaskPrompt = buildStepPrompt(syntheticDispatch, context);
         const taskTimeout = STEP_TIMEOUT_MS[dispStepId] ?? DEFAULT_TIMEOUT_MS;
-        const taskResult = await runAndNormalize(connector, prompt, syntheticDispatch, { progress, streamWriter, maxDurationMs: taskTimeout });
+        // review_mode is passed via inputs (as string "true") since top-level step props are Stratum-validated.
+        // Fallback: parallel_dispatch steps with output_contract=ReviewResult are review by definition.
+        const isReview = dispatchResponse.review_mode === true
+          || dispatchResponse.inputs?.review_mode === 'true'
+          || dispatchResponse.output_contract === 'ReviewResult'
+          || task.lens_name != null;
+        const confGateTask = task.confidence_gate ?? 7;
+
+        // MF-1: Prepend shared review scaffold when this is a review (lens) task.
+        // SF-6: cert (reasoning template) injection is done here at the call site,
+        // not inside buildReviewPrompt — matches the pattern at the taskIntent injection above.
+        let prompt = baseTaskPrompt;
+        if (isReview) {
+          let reviewScaffold = buildReviewPrompt({
+            agentType,
+            lens: task.lens_name ?? 'general',
+            lensFocus: task.lens_focus ?? '',
+            exclusions: task.exclusions ?? '',
+            confidenceGate: confGateTask,
+            taskDescription: response.inputs?.task ?? '',
+            blueprint: response.inputs?.blueprint ?? '',
+          });
+          // SF-6: append cert reasoning template for Claude-family agents (same as taskIntent path above)
+          if (agentType.startsWith('claude') && task.lens_name) {
+            const lensDef = LENS_DEFINITIONS[task.lens_name];
+            if (lensDef?.reasoning_template) {
+              reviewScaffold = injectCertInstructions(reviewScaffold, lensDef.reasoning_template);
+            }
+          }
+          prompt = reviewScaffold + '\n\n' + baseTaskPrompt;
+        }
+
+        const taskResult = await runAndNormalize(null, prompt, syntheticDispatch, {
+          progress, streamWriter, maxDurationMs: taskTimeout, stratum, cwd: taskCwd,
+          reviewMode: isReview,
+          confidenceGate: confGateTask,
+          lens: task.lens_name ?? 'general',
+        });
 
         if (worktreeIsolation && worktreePaths.has(taskId)) {
           const diskQuotaMB = dispatchResponse.diskQuotaMB ?? 500;
@@ -2782,15 +3325,23 @@ async function executeParallelDispatch(
   return stratum.parallelDone(dispFlowId, dispStepId, taskResults, mergeStatus);
 }
 
-async function startFresh(stratum, specYaml, featureCode, description, dataDir, templateName) {
+async function startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode = 'feature') {
   const flowName = extractFlowName(specYaml, templateName);
   console.log(`Starting ${flowName} for ${featureCode}...`);
-  const response = await stratum.plan(specYaml, flowName, { featureCode, description });
+  // COMP-FIX-HARD T4: bug-mode flows take input as { task: <description> }
+  // because pipelines/bug-fix.stratum.yaml's flow input contract uses `task`,
+  // not the feature flow's `{ featureCode, description }`.
+  const planInputs = mode === 'bug'
+    ? { task: description }
+    : { featureCode, description };
+  const response = await stratum.plan(specYaml, flowName, planInputs);
 
   writeActiveBuild(dataDir, {
     featureCode,
     flowId: response.flow_id,
     pipeline: flowName,
+    mode,
+    pid: process.pid,
     currentStepId: response.step_id,
     specPath: `pipelines/${templateName}.stratum.yaml`,
     stepNum: response.step_number ?? 1,
@@ -2929,6 +3480,25 @@ function appendDecisionEntry(contextDir, featureCode, stepId, outcome, rationale
   }
 }
 
+/**
+ * Load bug description from docs/bugs/<bugCode>/description.md (bug mode).
+ *
+ * Bug mode has no JSON file (feature.json equivalent); description.md is
+ * the sole source. If absent, fall back to the bug code so callers don't
+ * crash — `bin/compose.js` is responsible for prompting the user to write
+ * description.md before invoking runBuild.
+ */
+function loadBugDescription(bugDir, bugCode) {
+  const p = join(bugDir, 'description.md');
+  if (existsSync(p)) {
+    const content = readFileSync(p, 'utf-8');
+    // First non-blank, non-heading line; fall back to whole file if none.
+    const firstLine = content.split('\n').find(l => l.trim() && !l.startsWith('#'));
+    return (firstLine?.trim()) || content.trim() || bugCode;
+  }
+  return bugCode;
+}
+
 function loadFeatureDescription(featureDir, featureCode) {
   // Try design.md, then spec.md, then fall back to feature code
   for (const name of ['design.md', 'spec.md']) {