mandrel 2.11.0 → 2.13.0

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -21,6 +21,7 @@ import { readFile } from 'node:fs/promises';
 import { getLimits } from '../config-resolver.js';
 import { findSimilarOpenStories } from '../duplicate-search.js';
 import { Logger } from '../Logger.js';
+import { parse as parseStoryBody } from '../story-body/story-body.js';
 import {
   renderAcceptanceSpecSystemPrompt,
   renderTechSpecSystemPrompt,
@@ -353,6 +354,111 @@ function resolveRiskHeuristics(config = {}) {
   return [];
 }
 
+/**
+ * Ceilings a seed's advisory complexity signals must fit for the plan
+ * workflow to **suggest** `/deliver-light` at Gate #1 (Story #4741 R3 plan-side
+ * handshake). Framework constants, not operator knobs — mirroring the
+ * conservative intent of `complexity-gate.js`'s `STORY_SHAPE_CEILINGS`
+ * (small, mostly-additive, non-sensitive) but read against the *seed-time*
+ * signals rather than an authored Story shape.
+ *
+ * The suggestion is **advisory only and never an automatic reroute**: it
+ * surfaces at Gate #1 for the operator to decide, and under `--yes` it is
+ * recorded on the envelope while planning proceeds unchanged. `/deliver-light`
+ * is a sibling Story; these ceilings define the plan side of the routing
+ * handshake independently of it.
+ *
+ *   - `maxArtifacts`           — enumerated seed items (one artifact each).
+ *   - `maxRiskHeuristicHits`   — any risk-heuristic hit disqualifies: risk
+ *                                is exactly what a light path should not carry.
+ *   - `maxSensitivePathClasses`— any sensitive-path class disqualifies, the
+ *                                same taxonomy close applies to a landed diff.
+ */
+const DELIVER_LIGHT_SUGGESTION_CEILINGS = Object.freeze({
+  maxArtifacts: 2,
+  maxRiskHeuristicHits: 0,
+  maxSensitivePathClasses: 0,
+});
+
+/**
+ * Derive the advisory `/deliver-light` suggestion from a seed's complexity
+ * signals (Story #4741 AC-6). Pure and total: a malformed / missing signal
+ * bag fails conservative (not suggested), never throws.
+ *
+ * `automatic: false` is part of the contract — the suggestion is surfaced for
+ * the operator, never a silent reroute of a non-interactive run.
+ *
+ * @param {object|null|undefined} complexitySignals
+ * @returns {{
+ *   suggested: boolean,
+ *   automatic: false,
+ *   advisory: true,
+ *   ceilings: typeof DELIVER_LIGHT_SUGGESTION_CEILINGS,
+ *   reasons: string[],
+ * }}
+ */
+export function buildDeliverLightSuggestion(complexitySignals) {
+  const ceilings = DELIVER_LIGHT_SUGGESTION_CEILINGS;
+  const advisory = /** @type {const} */ (true);
+  const automatic = /** @type {const} */ (false);
+  const s = complexitySignals ?? {};
+  const artifactCount = Number.isInteger(s.artifactCount)
+    ? s.artifactCount
+    : Number.POSITIVE_INFINITY;
+  const riskHits = Array.isArray(s.riskHeuristicHits)
+    ? s.riskHeuristicHits.length
+    : Number.POSITIVE_INFINITY;
+  const sensitive = Array.isArray(s.sensitivePathClasses)
+    ? s.sensitivePathClasses.length
+    : Number.POSITIVE_INFINITY;
+
+  const reasons = [];
+  if (artifactCount > ceilings.maxArtifacts) {
+    reasons.push(
+      `seed enumerates ${artifactCount} artifacts (> ${ceilings.maxArtifacts})`,
+    );
+  }
+  if (riskHits > ceilings.maxRiskHeuristicHits) {
+    reasons.push(`seed hits ${riskHits} risk-heuristic phrase(s)`);
+  }
+  if (sensitive > ceilings.maxSensitivePathClasses) {
+    reasons.push(
+      `predicted footprint touches ${sensitive} sensitive-path class(es)`,
+    );
+  }
+
+  const suggested = reasons.length === 0;
+  return {
+    suggested,
+    automatic,
+    advisory,
+    ceilings,
+    reasons: suggested
+      ? [
+          `seed fits the /deliver-light ceilings (≤${ceilings.maxArtifacts} artifacts, ` +
+            'no risk-heuristic hits, no sensitive-path classes) — the operator ' +
+            'may prefer /deliver-light for this scope',
+        ]
+      : reasons,
+  };
+}
+
+/**
+ * Attach the advisory `/deliver-light` suggestion to a complexity-signals bag
+ * as a **nested** field (Story #4741). Nesting — rather than a new top-level
+ * envelope key — keeps every existing per-mode envelope key set byte-stable
+ * (AC-5): the suggestion is derived from the signals it rides on.
+ *
+ * @param {object} complexitySignals
+ * @returns {object} the same signals plus `deliverLightSuggestion`.
+ */
+function withDeliverLightSuggestion(complexitySignals) {
+  return {
+    ...complexitySignals,
+    deliverLightSuggestion: buildDeliverLightSuggestion(complexitySignals),
+  };
+}
+
 /**
  * Count top-level enumerated items (`- `, `* `, `1. `) under the first
  * scope-shaped `## ` heading (Scope / MVP Scope / Proposed Scope / Work
@@ -588,13 +694,17 @@ async function buildSeedFileModeEnvelope({
     seed: { path: seedFilePath ?? null, content },
     // Advisory complexity signals only (Story #4722): no route, no routing
     // authority. The planner authors the trivial-vs-standard verdict; persist
-    // validates a lite claim against the authored Story's shape.
-    complexitySignals: buildComplexitySignals({
-      seedText: content,
-      config,
-      riskHeuristics: heuristics,
-      cwd,
-    }),
+    // validates a lite claim against the authored Story's shape. The nested
+    // `deliverLightSuggestion` is the advisory plan-side routing handshake
+    // (Story #4741 AC-6) — never an automatic reroute.
+    complexitySignals: withDeliverLightSuggestion(
+      buildComplexitySignals({
+        seedText: content,
+        config,
+        riskHeuristics: heuristics,
+        cwd,
+      }),
+    ),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,
@@ -748,12 +858,14 @@ async function buildTicketsModeEnvelope({
     mode: 'tickets',
     sourceTickets,
     seed: { text: seed, path: null },
-    complexitySignals: buildComplexitySignals({
-      seedText: seed,
-      config,
-      riskHeuristics: heuristics,
-      cwd,
-    }),
+    complexitySignals: withDeliverLightSuggestion(
+      buildComplexitySignals({
+        seedText: seed,
+        config,
+        riskHeuristics: heuristics,
+        cwd,
+      }),
+    ),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,
@@ -779,6 +891,122 @@ async function buildTicketsModeEnvelope({
   };
 }
 
+/**
+ * Parse a prior Story body into its acceptance criteria and delivered file
+ * map. Total: an unparseable body degrades to empty lists (a delta envelope
+ * grounded on whatever survived), never a throw.
+ *
+ * @param {string} priorBody
+ * @returns {{ priorAcceptance: string[], deliveredFiles: string[] }}
+ */
+function extractPriorArtifacts(priorBody) {
+  let parsed;
+  try {
+    parsed = parseStoryBody(priorBody).body;
+  } catch {
+    return { priorAcceptance: [], deliveredFiles: [] };
+  }
+  const priorAcceptance = Array.isArray(parsed.acceptance)
+    ? parsed.acceptance.filter((a) => typeof a === 'string' && a.length > 0)
+    : [];
+  const deliveredFiles = Array.isArray(parsed.changes)
+    ? parsed.changes
+        .map((c) => (c && typeof c === 'object' ? c.path : c))
+        .filter((p) => typeof p === 'string' && p.length > 0)
+    : [];
+  return { priorAcceptance, deliveredFiles };
+}
+
+/**
+ * Build the amendment (delta) envelope — `plan-context --amends #<id>`
+ * (Story #4741 AC-4, R3-A). The heavy-amendment counterpart to routing a
+ * light amendment through `/deliver-light`: instead of re-interrogating the
+ * repo from scratch (`buildAuthoringContext`'s codebase snapshot and the BDD /
+ * memory / feedback probes), the envelope composes a DELTA from what already
+ * exists — the prior Story's body, its acceptance criteria (the real
+ * contract), and its delivered file map — so a follow-up change plans from the
+ * shape already shipped.
+ *
+ * The semantic steps that reach the ticket are preserved: the open-Story
+ * duplicate search (excluding the amended Story itself), the risk heuristics,
+ * and the authoring system prompts all still ride the envelope. What is
+ * dropped is only the from-scratch repo interrogation the prior artifacts
+ * already stand in for — that is the round-trip diet, not an amputation.
+ *
+ * @param {{
+ *   amendsId: number,
+ *   provider: object,
+ *   config: object,
+ *   settings: object,
+ *   cwd?: string,
+ * }} args
+ * @returns {Promise<object>}
+ */
+async function buildAmendmentModeEnvelope({
+  amendsId,
+  provider,
+  config,
+  settings: _settings,
+  cwd,
+}) {
+  if (!provider || typeof provider.getTicket !== 'function') {
+    throw new Error(
+      '[plan-context] --amends requires provider.getTicket() to load the prior Story.',
+    );
+  }
+  const prior = await provider.getTicket(amendsId);
+  if (!prior) {
+    throw new Error(
+      `[plan-context] --amends #${amendsId}: prior Story not found — nothing to amend.`,
+    );
+  }
+  const priorBody = typeof prior.body === 'string' ? prior.body : '';
+  const { priorAcceptance, deliveredFiles } = extractPriorArtifacts(priorBody);
+
+  const heuristics = resolveRiskHeuristics(config);
+  const limits = getLimits(config);
+  const duplicates = await searchStoryDuplicates({
+    seed: priorBody,
+    provider,
+    config,
+    excludeIds: [amendsId],
+  });
+
+  return {
+    mode: 'amends',
+    amends: {
+      id: Number(prior.id ?? prior.number ?? amendsId),
+      title: prior.title ?? '',
+      priorBody,
+      priorAcceptance,
+      deliveredFiles,
+    },
+    // The prior body is the seed the delta is authored against.
+    seed: { text: priorBody, path: null },
+    complexitySignals: withDeliverLightSuggestion(
+      buildComplexitySignals({
+        seedText: priorBody,
+        config,
+        riskHeuristics: heuristics,
+        cwd,
+      }),
+    ),
+    duplicates,
+    // No plan temp dir and no from-scratch repo interrogation — the prior
+    // artifacts are the grounding, so there is no docs digest to anchor.
+    docsContext: null,
+    ticketSchema: TICKET_SCHEMA_DESCRIPTOR,
+    maxTickets: limits.maxTickets,
+    riskHeuristics: heuristics,
+    systemPrompts: buildSystemPrompts({
+      heuristics,
+      maxTickets: limits.maxTickets,
+    }),
+    planState: null,
+    planProfile: 'story-amendment',
+  };
+}
+
 /**
  * Build the single planner-context envelope.
  *
@@ -787,11 +1015,12 @@ async function buildTicketsModeEnvelope({
  * bound it (see {@link assertPlanContextWithinCeiling}).
  *
  * @param {{
- *   mode: 'seed-file'|'seed'|'tickets',
+ *   mode: 'seed-file'|'seed'|'tickets'|'amends',
  *   seedFilePath?: string,
  *   seedFileContent?: string,
  *   seedText?: string,
  *   ticketIds?: number[],
+ *   amendsId?: number,
  *   provider: object,
  *   config: object,
  *   settings: object,
@@ -805,6 +1034,7 @@ export async function buildPlanContext({
   seedFileContent,
   seedText,
   ticketIds,
+  amendsId,
   provider,
   config = {},
   settings = {},
@@ -817,6 +1047,7 @@ export async function buildPlanContext({
       seedFileContent,
       seedText,
       ticketIds,
+      amendsId,
       provider,
       config,
       settings,
@@ -835,11 +1066,21 @@ async function buildPlanContextEnvelope({
   seedFileContent,
   seedText,
   ticketIds,
+  amendsId,
   provider,
   config,
   settings,
   cwd,
 }) {
+  if (mode === 'amends') {
+    return buildAmendmentModeEnvelope({
+      amendsId,
+      provider,
+      config,
+      settings,
+      cwd,
+    });
+  }
   if (mode === 'seed-file') {
     if (!seedFilePath && typeof seedFileContent !== 'string') {
       throw new Error(
@@ -875,6 +1116,6 @@ async function buildPlanContextEnvelope({
     });
   }
   throw new Error(
-    `[plan-context] unknown mode "${mode}" — expected "seed", "seed-file", or "tickets".`,
+    `[plan-context] unknown mode "${mode}" — expected "seed", "seed-file", "tickets", or "amends".`,
   );
 }

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -301,6 +301,7 @@ async function renderRunScopedPlanMetricsLine({
  *   stories: ReturnType<typeof assemblePlanStories>['stories'],
  *   routeDowngradeReason?: string|null,
  *   config?: object,
+ *   injectedRules?: object,
  * }} args
  * @returns {{
  *   route: 'lite'|'full',
@@ -313,6 +314,7 @@ function resolveEffectiveRoute({
   stories,
   routeDowngradeReason = null,
   config = {},
+  injectedRules,
 }) {
   const verdict = resolvePlannerRouteVerdict({ reason: routeDowngradeReason });
   if (verdict.route !== 'lite') return null;
@@ -339,6 +341,7 @@ function resolveEffectiveRoute({
     const derived = deriveStoryShape({
       changes: story.bodyObject?.changes,
       acceptance: story.acceptance,
+      injectedRules,
     });
     return {
       slug: story.slug,
@@ -455,6 +458,7 @@ export async function reapStalePlanDirs({
  *     sourceTicketOrigin?: 'flag'|'envelope'|'none',
  *     closeSuperseded?: boolean,
  *     routeDowngradeReason?: string|null,
+ *     injectedRules?: object,
  *   },
  * }} input
  */
@@ -483,6 +487,7 @@ export async function runPlanPersist({
     sourceTicketOrigin = 'none',
     closeSuperseded = true,
     routeDowngradeReason = null,
+    injectedRules = undefined,
   } = opts;
 
   // Boundary for the plan-metrics summary below: everything this invocation
@@ -566,6 +571,7 @@ export async function runPlanPersist({
     stories,
     routeDowngradeReason,
     config,
+    injectedRules,
   });
   const isLiteRoute = route?.route === 'lite';
   if (isLiteRoute) {

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -300,6 +300,9 @@ export async function readNativeBlockedBy({
  * @param {Map<number, number[]>} nativeEdges
  * @param {number[]} foreignDone Ids outside the set already satisfied.
  * @param {(msg: string) => void} [warn]
+ * @param {object} [injectedRules] Test seam forwarded to the shape
+ *   derivation — skips the `audit-rules.json` disk read. Production callers
+ *   omit it (the real manifest, memoized per process, is the default).
  * @returns {{ kind: string, stories: object[], dag: object[], done: number[] }}
  */
 export function buildStoriesEnvelope({
@@ -308,6 +311,7 @@ export function buildStoriesEnvelope({
   foreignDone = [],
   warn,
   config,
+  injectedRules,
 }) {
   const sorted = [...stories].sort((a, b) => a.id - b.id);
   const inSetDone = sorted.filter(isSatisfiedBlocker).map((s) => s.id);
@@ -321,13 +325,26 @@ export function buildStoriesEnvelope({
     // `route::lite` label is a human-visible hint only, never the control
     // signal: a lost label cannot misroute delivery. Model-side fan-out
     // only; close gates are untouched.
+    //
+    // `storyCount` (Story #4736) carries the run's topology into that same
+    // decision: a run resolving exactly ONE Story is inline whatever its
+    // shape, because the isolation a sub-agent buys only matters against a
+    // concurrently-dispatched sibling. It is the resolved set size — not the
+    // undelivered remainder — so the mode a caller reads for a given `--ids`
+    // list never changes as siblings land mid-run.
     stories: sorted.map(({ id, title, body, url, labels, state }) => ({
       id,
       title,
       url,
       labels,
       state,
-      dispatchMode: resolveStoryDispatchMode({ body, labels, config }).mode,
+      dispatchMode: resolveStoryDispatchMode({
+        body,
+        labels,
+        config,
+        storyCount: sorted.length,
+        injectedRules,
+      }).mode,
     })),
     dag: storiesToDag(sorted, nativeEdges, warn),
     done: [...new Set([...inSetDone, ...foreignDone])].sort((a, b) => a - b),

package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js

@@ -0,0 +1,186 @@
+/**
+ * single-story-close/gate-log.js — bounded gate output for the close path
+ * (Story #4736).
+ *
+ * ## Why
+ *
+ * `runCloseValidation` streams every child gate's stdout/stderr line through
+ * an injected `log`, and the close phase used to hand it `Logger.info` — whose
+ * default sink is `console.log`. A single successful close therefore wrote the
+ * whole of `npm test`, the linter, and the baseline checks onto the invoking
+ * agent's stdout: ~50KB, over the host's inline tool-result ceiling. The caller
+ * got a truncated preview, had to open the persisted file anyway, and re-ran
+ * close for a clean envelope — burning the run's most expensive stretch to
+ * re-derive output it already had.
+ *
+ * Story #4708 set the contract this restores compliance with (see
+ * `rules/orchestration-error-handling.md` § Output Contract): compact digest
+ * plus an on-disk artifact path, ≤ ~2KB on the **default success path**.
+ *
+ * ## The shape
+ *
+ * A sink captures every gate line to a log under the gitignored temp tree and
+ * emits nothing inline. What happens next depends on the outcome, because the
+ * two outcomes want opposite things:
+ *
+ *   - **success** — the caller wants the verdict, not the evidence.
+ *     {@link GateLogSink#digest} is one line: the pass count and the log path.
+ *   - **failure** — the evidence IS the point, and making the caller open a
+ *     file to see why a gate went red just moves the cost.
+ *     {@link GateLogSink#replay} puts the captured tail back inline.
+ *
+ * `AGENT_LOG_LEVEL=verbose` opts back into live inline streaming (the
+ * "existing log-level control"): the capture still happens, so the artifact is
+ * written either way.
+ *
+ * The sink never throws. A log directory that cannot be written degrades to
+ * inline streaming — losing the size bound is strictly better than losing the
+ * gate output that says why a close failed.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+import { Logger, resolveLevel } from '../../Logger.js';
+
+/**
+ * How many trailing captured lines {@link GateLogSink#replay} puts back
+ * inline. A failed gate's actionable evidence — the assertion, the stack, the
+ * summary counts — sits at the end of its output; the head is startup noise.
+ * The full text is always in the artifact regardless.
+ */
+export const REPLAY_TAIL_LINES = 200;
+
+/** Basename of the per-Story gate log inside the temp directory. */
+function logNameFor(storyId) {
+  return `close-gates-${storyId ?? 'unknown'}.log`;
+}
+
+/**
+ * A capturing sink for close-validation gate output.
+ *
+ * Not exported as a constructor — {@link createGateLogSink} owns the
+ * degradation decision, so every instance in the wild has already resolved
+ * whether it has a writable artifact.
+ */
+class GateLogSink {
+  /**
+   * @param {{ logPath: string|null, streamInline: boolean, write: (line: string) => void, emit: (line: string) => void }} args
+   */
+  constructor({ logPath, streamInline, write, emit }) {
+    /** Absolute path of the artifact, or `null` when capture is unavailable. */
+    this.logPath = logPath;
+    /** Whether lines are ALSO echoed inline as they arrive. */
+    this.streamInline = streamInline;
+    /** Number of lines captured so far. */
+    this.lineCount = 0;
+    this._write = write;
+    this._emit = emit;
+    this._tail = [];
+  }
+
+  /**
+   * The `log` callable handed to `runCloseValidation` / `buildDefaultGates`.
+   * Bound, because it is passed by reference into the gate machinery.
+   *
+   * @type {(message: string) => void}
+   */
+  get log() {
+    return (message) => {
+      const line = String(message ?? '');
+      this.lineCount += 1;
+      this._tail.push(line);
+      if (this._tail.length > REPLAY_TAIL_LINES) this._tail.shift();
+      this._write(line);
+      if (this.streamInline) this._emit(line);
+    };
+  }
+
+  /**
+   * The success-path digest: one line, no gate output. Names the artifact so
+   * the caller can open it on demand rather than carrying it all session.
+   *
+   * @returns {string}
+   */
+  digest() {
+    const where = this.logPath
+      ? `full gate output → ${this.logPath}`
+      : 'full gate output was streamed inline (no artifact could be written)';
+    return `${this.lineCount} line(s) of gate output captured; ${where}`;
+  }
+
+  /**
+   * Put the captured tail back inline — the failure path, where the evidence
+   * is what the caller came for. A no-op when the lines were already streamed
+   * inline (verbose, or degraded capture), so nothing is ever printed twice.
+   *
+   * @returns {number} Lines replayed.
+   */
+  replay() {
+    if (this.streamInline || this._tail.length === 0) return 0;
+    const dropped = this.lineCount - this._tail.length;
+    if (dropped > 0) {
+      this._emit(
+        `[close-validation] … ${dropped} earlier line(s) omitted; full output → ${this.logPath}`,
+      );
+    }
+    for (const line of this._tail) this._emit(line);
+    return this._tail.length;
+  }
+}
+
+/**
+ * Build the gate-output sink for one close run.
+ *
+ * @param {{
+ *   storyId: number|null,
+ *   cwd?: string,
+ *   logDir?: string,
+ *   fs?: typeof nodeFs,
+ *   logger?: { info: (m: string) => void },
+ *   level?: string,
+ * }} [args] `logDir` defaults to `<cwd>/temp/orchestration`; `level` defaults
+ *   to the live Logger level so `AGENT_LOG_LEVEL=verbose` restores streaming.
+ * @returns {GateLogSink}
+ */
+export function createGateLogSink({
+  storyId = null,
+  cwd = process.cwd(),
+  logDir,
+  fs = nodeFs,
+  logger = Logger,
+  level,
+} = {}) {
+  const emit = (line) => logger.info?.(line);
+  const verbose = (level ?? resolveLevel()) === 'verbose';
+  const dir = logDir ?? path.join(cwd, 'temp', 'orchestration');
+
+  let handle = null;
+  let logPath = null;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    logPath = path.join(dir, logNameFor(storyId));
+    // Truncate: each close run owns its artifact outright, so a re-run never
+    // hands the reader a file interleaving two runs' gates.
+    handle = fs.openSync(logPath, 'w');
+  } catch {
+    // No artifact — fall back to inline streaming rather than dropping the
+    // gate output on the floor.
+    return new GateLogSink({
+      logPath: null,
+      streamInline: true,
+      write: () => {},
+      emit,
+    });
+  }
+
+  const write = (line) => {
+    try {
+      fs.writeSync(handle, `${line}\n`);
+    } catch {
+      /* best-effort: a mid-run write failure must not abort the close */
+    }
+  };
+
+  return new GateLogSink({ logPath, streamInline: verbose, write, emit });
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -24,6 +24,15 @@
  * the same, with `baseBranch` as the diff anchor and the Story worktree as
  * the commit target.
  *
+ * Bounded gate output (Story #4736). Every gate line goes to the run's
+ * `gate-log.js` sink — an artifact under the gitignored temp tree — instead
+ * of straight to the agent's stdout, where a passing `npm test` alone once
+ * pushed a successful close past the host's inline tool-result ceiling. A
+ * clean run reports one digest line naming the artifact; a failing gate
+ * replays its captured tail inline, because that is exactly when the caller
+ * needs the evidence in front of them. `AGENT_LOG_LEVEL=verbose` restores
+ * live streaming.
+ *
  * `runCloseValidation`, `buildDefaultGates`, and `runScopedFormatAutofix`
  * are accepted as injected dependencies so the parent CLI's cache-busted
  * bindings win in tests that mock the upstream module URLs.
@@ -33,6 +42,7 @@ import { buildDefaultGates as defaultBuildDefaultGates } from '../../../close-va
 import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
 import { Logger } from '../../../Logger.js';
 import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
+import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
 
 /**
  * Run the close-validation gate chain. Throws on first gate failure.
@@ -60,6 +70,7 @@ import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../s
  *   runCloseValidation?: typeof defaultRunCloseValidation,
  *   buildDefaultGates?: typeof defaultBuildDefaultGates,
  *   runScopedFormatAutofix?: typeof defaultRunScopedFormatAutofix,
+ *   createGateLogSink?: typeof defaultCreateGateLogSink,
  * }} args
  */
 export async function runCloseValidationPhase({
@@ -73,6 +84,7 @@ export async function runCloseValidationPhase({
   runCloseValidation = defaultRunCloseValidation,
   buildDefaultGates = defaultBuildDefaultGates,
   runScopedFormatAutofix = defaultRunScopedFormatAutofix,
+  createGateLogSink = defaultCreateGateLogSink,
 }) {
   // Story #4250 — format-autofix self-heal before the check-only gates.
   // Mirrors the Epic path (story-close/phases/gates.js): the formatter is
@@ -122,6 +134,9 @@ export async function runCloseValidationPhase({
     'VALIDATE',
     `Running close-validation gates against baseline ${baseBranch}${worktreePath ? ` in ${worktreePath}` : ''}...`,
   );
+  // Story #4736 — one sink for both `log` seams (gate construction and gate
+  // execution), so nothing in the chain can route around the artifact.
+  const gateLog = createGateLogSink({ storyId, cwd });
   const validation = await runCloseValidation({
     cwd,
     worktreePath,
@@ -129,9 +144,9 @@ export async function runCloseValidationPhase({
       config,
       baseBranch,
       cwd: worktreePath || cwd,
-      log: (m) => Logger.info(m),
+      log: gateLog.log,
     }),
-    log: (m) => Logger.info(m),
+    log: gateLog.log,
     storyId,
     // Story #4250 — standalone storyId-anchored evidence keyspace. No
     // epicId; the standalone flag routes the cache to
@@ -141,10 +156,13 @@ export async function runCloseValidationPhase({
   if (!validation.ok) {
     const [first] = validation.failed;
     const { gate, status, cwd: gateCwd } = first;
+    // The evidence is the point on this path: replay the captured tail inline
+    // rather than making the caller open a file to learn why close stopped.
+    gateLog.replay();
     throw new Error(
       `[single-story-close] Gate failed: ${gate.name} (exit ${status})${gateCwd ? ` in ${gateCwd}` : ''}.` +
         (gate.hint ? ` ${gate.hint}` : ''),
     );
   }
-  progress('VALIDATE', '✅ All gates passed.');
+  progress('VALIDATE', `✅ All gates passed. ${gateLog.digest()}`);
 }