mandrel 2.11.0 → 2.12.0

package/.agents/rules/orchestration-error-handling.md

@@ -46,8 +46,16 @@ success output is a per-turn tax on the whole session — not a one-time cost.
   their drivers — emit them single-line (`JSON.stringify(x)`), never
   pretty-printed (`null, 2` only adds resident bytes). Pretty output is
   reserved for explicit opt-in flags (`--pretty`).
+- **Streamed child output counts too (Story #4736).** A script that pipes a
+  child process's stdout/stderr through to the caller is emitting that output
+  as its own. `single-story-close.js` streamed every close-validation gate —
+  the whole of `npm test` included — and blew the budget by ~25× on a *passing*
+  close. Capture it to an artifact instead
+  ([`single-story-close/gate-log.js`](../scripts/lib/orchestration/single-story-close/gate-log.js)),
+  emit the digest, and **replay the tail inline on failure** — the bound is a
+  success-path bound, and a red gate's evidence belongs in front of the caller.
 - **Escape hatch.** `MANDREL_RESULT_DETAIL=inline` restores inline full
   detail for interactive debugging; scripts using `emitTerseResult` honor it
-  automatically.
+  automatically. `AGENT_LOG_LEVEL=verbose` restores live gate streaming.
 - **stdout purity is unchanged.** Scripts whose stdout is a machine contract
   (Story #2278) keep logs on stderr; the digest is the *only* stdout line.

package/.agents/scripts/lib/audit-suite/audit-rules-reader.js

@@ -0,0 +1,48 @@
+/**
+ * lib/audit-suite/audit-rules-reader.js — the one synchronous reader of the
+ * `audit-rules.json` manifest, memoized for the process lifetime.
+ *
+ * The manifest is shipped framework configuration resolved from one fixed
+ * path per process, and the shape-derivation path reads it once per Story at
+ * resolve AND persist — an un-memoized read is pure repeated I/O (measured
+ * 221 µs/op raw vs 5.5 µs seamed on the run adhoc-4722-4723 audit). Only a
+ * successful parse is cached: a read failure stays a per-call throw so a
+ * caller can observe a manifest that becomes readable later. Tests never
+ * reach this read — they inject fixture rules through the callers'
+ * `injectedRules` seam.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
+
+/** Process-lifetime memo of the parsed manifest (successful parses only). */
+let auditRulesCache = null;
+
+/**
+ * Read and parse the `audit-rules.json` manifest synchronously from the
+ * project's configured `schemasRoot`. Shared by the synchronous, ticket-free
+ * readers (`resolveLensTier`, `selectLocalLenses`,
+ * `selectSensitivePathClasses`) so the path resolution and read-failure
+ * handling live in one place rather than being duplicated per reader.
+ *
+ * @returns {{ audits?: Record<string, object> }} Parsed manifest.
+ * @throws {Error} When the manifest cannot be read or parsed.
+ */
+export function readAuditRulesSync() {
+  if (auditRulesCache !== null) return auditRulesCache;
+  const config = resolveConfig();
+  const rulesPath = path.join(
+    PROJECT_ROOT,
+    getPaths(config).schemasRoot,
+    'audit-rules.json',
+  );
+  try {
+    auditRulesCache = JSON.parse(readFileSync(rulesPath, 'utf8'));
+    return auditRulesCache;
+  } catch (err) {
+    throw new Error(
+      `audit-suite: failed to read audit-rules from ${rulesPath}: ${err.message}`,
+    );
+  }
+}

package/.agents/scripts/lib/audit-suite/selector.js

@@ -26,6 +26,7 @@ import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
 import { softFailOrThrow } from '../degraded-mode.js';
 import { gitSpawn } from '../git-utils.js';
 import { withTimeout } from '../util/with-timeout.js';
+import { readAuditRulesSync } from './audit-rules-reader.js';
 
 const DEFAULT_GIT_TIMEOUT_MS = 30000;
 
@@ -101,32 +102,6 @@ export const LENS_TIERS = Object.freeze(['local', 'cumulative', 'global']);
  *   manifest cannot be read, or the registered entry carries a scope outside
  *   {@link LENS_TIERS}.
  */
-/**
- * Read and parse the `audit-rules.json` manifest synchronously from the
- * project's configured `schemasRoot`. Shared by the synchronous, ticket-free
- * readers ({@link resolveLensTier}, {@link selectLocalLenses}) so the path
- * resolution and read-failure handling live in one place rather than being
- * duplicated per reader.
- *
- * @returns {{ audits?: Record<string, object> }} Parsed manifest.
- * @throws {Error} When the manifest cannot be read or parsed.
- */
-function readAuditRulesSync() {
-  const config = resolveConfig();
-  const rulesPath = path.join(
-    PROJECT_ROOT,
-    getPaths(config).schemasRoot,
-    'audit-rules.json',
-  );
-  try {
-    return JSON.parse(readFileSync(rulesPath, 'utf8'));
-  } catch (err) {
-    throw new Error(
-      `audit-suite: failed to read audit-rules from ${rulesPath}: ${err.message}`,
-    );
-  }
-}
-
 export function resolveLensTier(lens) {
   const rulesData = readAuditRulesSync();
 

package/.agents/scripts/lib/orchestration/complexity-gate.js

@@ -35,7 +35,10 @@
  *      acceptance-critic dispatch — while every `single-story-close.js` gate
  *      runs unchanged. The `route::lite` label is a **human-visible hint
  *      only**, never the control signal: a lost label or an unread marker can
- *      no longer misroute delivery.
+ *      no longer misroute delivery. Ahead of the shape read sits one
+ *      shape-independent rule (Story #4736): a **single-Story run** is inline
+ *      whatever its shape, because sub-agent isolation buys nothing when
+ *      there is no concurrent sibling to isolate from.
  *
  * The shape taxonomy is deliberately the one `review-depth.js` already
  * applies to the landed diff at close (`deriveChangeLevel` over the
@@ -561,37 +564,68 @@ function deriveStoryRouteFromBody(body, opts = {}) {
 }
 
 /**
- * Decide how `/deliver` executes a Story — **from the Story body's own
- * shape**, never from the `route::lite` label (Story #4722 AC-4/AC-5).
- *
- * A lite-shaped Story executes **inline** in the deliver session — no
- * story-worker sub-agent boot and no fresh acceptance-critic dispatch
- * (sub-agent boots are the dominant deliver-phase token cost at trivial
- * scope). Everything else — a full-shaped body, a missing/unparseable body,
- * or the gate disabled via `planning.complexityGate.enabled=false` —
- * dispatches as a sub-agent: the conservative default.
+ * Best-effort route derivation for reporting, when the *mode* is already
+ * pinned by run topology and only `route` remains to be filled in. A body
+ * that will not parse yields `null` rather than throwing — the caller is not
+ * asking the shape to decide anything.
+ *
+ * @param {unknown} body
+ * @param {{ injectedRules?: object, selectSensitivePathClassesFn?: Function }} opts
+ * @returns {ReturnType<typeof deriveStoryShape>|null}
+ */
+function routeForReporting(body, opts) {
+  if (typeof body !== 'string' || body.trim() === '') return null;
+  return deriveStoryRouteFromBody(body, opts);
+}
+
+/**
+ * Decide how `/deliver` executes a Story.
+ *
+ * Two independent premises, checked in this order:
+ *
+ * 1. **Run topology (Story #4736).** A run delivering a *single* Story
+ *    executes **inline**, whatever its shape. Sub-agent isolation is
+ *    load-bearing only for CONCURRENT dispatch — two workers sharing a
+ *    checkout would race on worktrees and branch refs — and a one-Story run
+ *    has no sibling to race. It therefore pays the spawn premium (a boot is
+ *    a cache WRITE at full rate, where an inline continuation is a cache read
+ *    at ~10%; ~$1.43/M vs ~$1.07/M on comparable bench work) for nothing.
+ *    This is a fact about the run, not about the work, so the shape gate's
+ *    `enabled` switch — which governs *shape derivation* — does not reach it.
+ * 2. **Shape (Story #4722 AC-4/AC-5).** For a multi-Story run, the decision
+ *    comes **from the Story body's own shape**, never from the `route::lite`
+ *    label: a lite-shaped Story executes inline; everything else — a
+ *    full-shaped body, a missing/unparseable body, or the gate disabled via
+ *    `planning.complexityGate.enabled=false` — dispatches as a sub-agent,
+ *    the conservative default.
  *
  * The label is read only to report hint consistency in `reasons`: with the
  * label absent (or its write failed) a lite-shaped Story still runs inline,
  * and with the label present on a full-shaped Story the shape wins.
  *
- * Inline execution removes model-side fan-out only. Every deterministic
- * `single-story-close.js` gate runs unchanged regardless of mode — see the
+ * Inline execution removes model-side fan-out only — it changes **where** the
+ * engine runs, never **what** runs. Every deterministic
+ * `single-story-close.js` gate, the PR to `main`, and the
+ * `story-deliver-terminal` envelope are identical in both modes; see the
  * module header's non-negotiables.
  *
  * @param {{
  *   body?: unknown,
  *   labels?: unknown,
  *   config?: object,
+ *   storyCount?: unknown,
  *   injectedRules?: object,
  *   selectSensitivePathClassesFn?: Function,
- * }} [args]
+ * }} [args] `storyCount` is the number of Stories the invoking `/deliver` run
+ *   resolved. Omitted (or not a positive integer) means "unknown run size",
+ *   which falls through to the shape decision — never to an assumed 1.
  * @returns {{ mode: 'inline'|'subagent', reasons: string[], route: ReturnType<typeof deriveStoryShape>|null }}
  */
 export function resolveStoryDispatchMode({
   body,
   labels,
   config,
+  storyCount,
   injectedRules,
   selectSensitivePathClassesFn,
 } = {}) {
@@ -603,6 +637,20 @@ export function resolveStoryDispatchMode({
     ? `the ${LITE_ROUTE_LABEL} label is present (hint only — the derived shape is the control signal)`
     : `the ${LITE_ROUTE_LABEL} label is absent (hint only — the derived shape is the control signal)`;
 
+  if (storyCount === 1) {
+    return {
+      mode: 'inline',
+      reasons: [
+        'single-Story run — execute deliver-story inline; sub-agent isolation is load-bearing only for concurrent dispatch, and a one-Story run has no sibling to race (close gates, PR, and terminal envelope unchanged)',
+        hintNote,
+      ],
+      route: routeForReporting(body, {
+        injectedRules,
+        selectSensitivePathClassesFn,
+      }),
+    };
+  }
+
   const gate = resolveComplexityGate(config);
   if (!gate.enabled) {
     return {

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()}`);
 }

package/.agents/workflows/deliver.md

@@ -10,7 +10,9 @@ description:
 > **Lean spine.** Happy path + gate list. Sequencing edge cases, dispatch
 > mechanics, lite-route inline execution, checklist threading, ceremony, and
 > the per-run epilogue live in the on-demand
-> [`helpers/deliver-reference.md`](helpers/deliver-reference.md).
+> [`helpers/deliver-reference.md`](helpers/deliver-reference.md). What every
+> delivery always needs is bundled into one read:
+> [`helpers/deliver-digest.md`](helpers/deliver-digest.md) (Story #4736).
 
 ## Role
 
@@ -20,20 +22,22 @@ owns input resolution and sequencing only — every Story runs through
 `epic/<id>` integration branch, no `--no-ff` wave merges.
 
 The dependency graph is **discovered, not declared**: `resolve-stories.js`
-reads it from live state (body edges ∪ native GitHub `blocked_by` edges, every
-blocker resolved against its real issue state). You never hand it a graph, and
+reads it from live state (body edges ∪ native GitHub `blocked_by` edges, each
+blocker resolved against its real issue state). You never hand it a graph and
 there is no batch label — which is what lets you deliver Stories **across plan
-runs and over time**. The `plan-run::<id>` grouping label is filter metadata
-only — never a resolution input (there is no `--run` or `--dep` axis).
+runs and over time**. `plan-run::<id>` is filter metadata, never a resolution
+input.
 Per-Story routes are **body-derived** too (#4722); `route::lite` is a hint
-only.
+only. Ahead of that: a **single-Story run runs the engine inline** whatever the
+shape (#4736) — sub-agent isolation only earns its cost against a concurrent
+sibling.
 
 ## Inputs
 
 | Invocation | Behavior |
 | --- | --- |
-| `/deliver <storyId>` | Deliver one Story via `helpers/deliver-story.md`. |
-| `/deliver <storyId> <storyId> ...` | Resolve the set with `resolve-stories.js`, then sequence by the discovered graph via `stories-wave-tick.js`. Default concurrency is **3**. |
+| `/deliver <storyId>` | Deliver one Story via `helpers/deliver-story.md`, executed **inline in this session** — no `story-worker` spawn. |
+| `/deliver <storyId> <storyId> ...` | Resolve the set with `resolve-stories.js`, then sequence by the discovered graph via `stories-wave-tick.js`, dispatching role-scoped sub-agents. Default concurrency is **3**. |
 
 Any named ticket that is not `type::story`, or still carrying an `Epic: #N`
 footer, is a **hard error** naming the id and the fix (close or re-plan as a v2
@@ -43,18 +47,16 @@ Story). Resolution refuses the whole set rather than silently under-delivering.
 
 | Flag | Meaning |
 | --- | --- |
-| `--concurrency <n>` | **Optional** per-run override of the fan-out cap. Omit it to honor `delivery.deliverRunner.concurrencyCap` (config default **3**, including any `.agentrc.local.json` override); pass it **only** for a one-run cap. `1` = sequential. |
+| `--concurrency <n>` | **Optional** per-run override of the fan-out cap. Omit it to honor `delivery.deliverRunner.concurrencyCap` (config default **3**, incl. any `.agentrc.local.json` override); pass **only** for a one-run cap. `1` = sequential. |
 | `--yes` | Suppress the multi-Story confirmation gate. |
 | `--steal` | Forwarded to `single-story-init.js` / lease steal. |
 | `--wait-merge` | Force close-and-land (the default; `delivery.routing.closeAndLand`). |
 | `--no-wait-merge` | Opt out; stop at `agent::closing` for a human land. |
 
 **Operator-merge implies no-wait.** `--no-auto-merge` and
-`delivery.ci.autoMerge: "strict"` leave the PR un-armed: the Story rests at
-`agent::closing` for the human merge and is **not** flipped to `agent::blocked`
-(`--wait-merge` does not override this). A genuine *arm failure* differs — it
-still waits and still blocks, because that is a fault to report, not an operator
-decision to respect.
+`delivery.ci.autoMerge: "strict"` rest the Story at `agent::closing`, not
+`agent::blocked` — a genuine *arm failure* still waits and still blocks
+([`helpers/deliver-reference.md` § Operator-merge](helpers/deliver-reference.md)).
 
 ## Procedure
 
@@ -64,8 +66,8 @@ decision to respect.
    present the order in step 2. You do **not** thread them into step 3 — the
    tick re-resolves the graph itself every beat. Resolution hard-errors
    (exit 1) on a named id that is not a Story, carries an `Epic: #N` footer, or
-   whose native edges cannot be read — a missing gate would co-dispatch a Story
-   against an unlanded blocker.
+   whose native edges cannot be read — a missing gate would co-dispatch against
+   an unlanded blocker.
 
 2. **Confirm (N>1).** Present the order; wait unless `--yes`.
 
@@ -78,10 +80,8 @@ decision to respect.
    ```
 
    **Do not add `--concurrency` unless the operator explicitly asked for a
-   per-run cap.** Omitting it lets the tick resolve the cap from
-   `delivery.deliverRunner.concurrencyCap` — including a `.agentrc.local.json`
-   override. An explicit `--concurrency <n>` wins over config for that run, so a
-   filled-in literal (e.g. `3`) silently defeats the operator's override.
+   per-run cap** — an explicit value wins over config, so a filled-in literal
+   silently defeats a `.agentrc.local.json` override (see Flags).
 
    Each beat re-probes live state to derive done / in-flight itself; you never
    compute them (Story #4594). `--dispatched` is the one thing you must supply —
@@ -129,10 +129,10 @@ review depth reading the same level) and the mechanism table:
 
 ## Reading a Story's outcome
 
-Each Story's delivery ends in exactly one schema-validated terminal envelope
-([`story-deliver-terminal.schema.json`](../schemas/story-deliver-terminal.schema.json),
-Story #4543) — `landed` | `pending` | `blocked` | `failed`, the SSOT for the
-shape; this workflow does not restate its fields.
+Each Story's delivery ends in exactly one schema-validated terminal envelope —
+`landed` | `pending` | `blocked` | `failed`. Statuses, exits, and fields:
+[`helpers/deliver-digest.md`](helpers/deliver-digest.md) § 5, over the shipped
+[schema](../schemas/story-deliver-terminal.schema.json) (Story #4543).
 
 `pending` is **not** a failure: the bounded merge wait expired with the PR
 healthy (or a human owns the merge), nothing was mutated, and the
@@ -146,11 +146,9 @@ For a Story in an unclear state — including the merged-but-label-stale one a
 
 ## Constraints
 
-- **Land or block — never a silent local build.** Worktrees, `story-<id>`
-  branches, close-validation, and PR-to-`main` are the only sanctioned delivery
-  mechanism. Attended delivers default to close-and-land
-  (`delivery.routing.closeAndLand: true`); use `--no-wait-merge` only when a
-  human lands the PR.
+- **Land or block — never a silent local build** (digest § 2). Attended
+  delivers default to close-and-land (`delivery.routing.closeAndLand: true`);
+  use `--no-wait-merge` only when a human lands the PR.
 - `/deliver` never plans — tickets come from [`/plan`](plan.md). The router
   performs no git/label mutations; `deliver-story` owns every script.
 

package/.agents/workflows/helpers/deliver-digest.md

@@ -0,0 +1,126 @@
+---
+description: >-
+  The deliver path's one bundled framework read (Story #4736). Carries what
+  every Story delivery always needs — dispatch decision, engine invariants,
+  the change-set/ceremony incantation, the acceptance-eval gate, and the
+  terminal envelope contract — so the engine reads one file instead of
+  re-reading the helper/schema set each session.
+---
+
+# Deliver digest (read once per session)
+
+> **Bundle, not a procedure.** [`deliver-story.md`](deliver-story.md) is still
+> the steps. This file is the material those steps referenced across five
+> separate files and a JSON schema — bundled so one read covers the whole happy
+> path. Situational material (lease preflight, recovery routers, merge-wait
+> budgets, CI remediation) stays on demand in
+> [`deliver-story-reference.md`](deliver-story-reference.md) and
+> [`deliver-reference.md`](deliver-reference.md); read those **only** when an
+> envelope or a failure routes you there.
+
+## 1. Dispatch — where the engine runs
+
+Read `stories[].dispatchMode` from the `resolve-stories.js` envelope. Two
+rules produce it, in order:
+
+1. **Run topology (#4736).** A run resolving **one** Story is `inline`
+   whatever its shape — sub-agent isolation is load-bearing only against a
+   *concurrent* sibling racing the same checkout, and a one-Story run has none.
+2. **Body shape (#4722).** In a multi-Story run, a lite-shaped body is
+   `inline`; a full-shaped body, an unparseable one, or a footprint touching a
+   sensitive-path class is `subagent`. The `route::lite` label is a
+   human-visible hint, never the control signal.
+
+`inline` removes model-side fan-out only — no `story-worker` boot, no fresh
+acceptance-critic spawn. **`subagent` and `inline` run the same engine**: same
+gates, same PR to `main`, same terminal envelope, byte for byte.
+
+## 2. Engine invariants
+
+| Trait | Contract |
+| --- | --- |
+| Ticket type | `type::story` only; an `Epic: #N` footer means **stop and re-plan** |
+| Branch | `story-<id>`, seeded from `project.baseBranch` (`main`) |
+| Merge target | `main` via PR (squash + required checks) — never a direct push |
+| Integration branch | **None** — no `epic/<id>`, no `--no-ff` wave merge |
+| Gates | Every close gate runs regardless of route; no route bypasses one |
+| State | Only via `update-ticket-state.js --ticket <id> --state <state>` |
+| Paths | Prefix every path-based tool with the absolute `workCwd` — `cd` does not scope them |
+
+**Land or block.** Worktree → `story-<id>` → close-validation → PR to `main` is
+the only sanctioned landing. A silent local build is not a delivery.
+
+## 3. Change set — computed once, handed to everyone
+
+One enumeration per Story (#4593). A critic that re-runs its own `git diff`
+can score a different set than the one that routed it:
+
+```bash
+node --input-type=module -e '
+  import { computeChangeSet } from "<main-repo>/.agents/scripts/lib/orchestration/change-set.js";
+  const { files } = computeChangeSet({ baseRef: "main", headRef: "story-<storyId>" });
+  console.log(JSON.stringify(files));
+'
+```
+
+Derive the level with `deriveChangeLevel`
+([`review-depth.js`](../../scripts/lib/orchestration/review-depth.js)) over
+that one list: a sensitive path registered in `audit-rules.json` → `high`, none
+→ `low`, an unenumerable diff (`files === null`) → `null`. Resolve
+fresh-vs-inline critics with `resolveCeremonyForRisk`
+([`ceremony-routing.js`](../../scripts/lib/orchestration/ceremony-routing.js)):
+`minimal` → always inline, `strict` → always fresh, `standard` → `high`/`null`
+→ fresh and `low` → inline unless the `freshCriticSampleRate` floor forces
+fresh. An `inline` dispatch mode overrides all of it to inline critics. Close's
+`review-depth.js` reads the same derived level, so the two cannot disagree.
+
+## 4. Acceptance self-eval (Step 1a, required)
+
+**One verdict-owner per cluster** (#4723) — the fresh critic *or* the inline
+self-eval, named by `verdictOwner`, never both and never a warm-up pass. It
+scores each `acceptance[]` item against the change set above, with `verify[]`
+output as evidence. Bounded by `delivery.acceptanceEval.maxRounds` (default 2).
+Then score the authored verdict:
+
+```bash
+node <main-repo>/.agents/scripts/acceptance-eval.js \
+  --story <storyId> --verdict <verdict-path>
+```
+
+`proceed` → close. `redraft` → one more round inside the cap. `block` → **do
+not close**: post a `friction` comment and flip `agent::blocked`.
+Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
+
+## 5. Terminal envelope — the return contract
+
+`single-story-close.js` emits exactly one envelope on stdout between
+`--- STORY DELIVER TERMINAL ---` markers, schema-validated against
+[`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
+(#4543 — the SSOT; read the JSON only when you need a field this table omits).
+Relay it verbatim; never hand-compose one, never substitute prose.
+
+| `status` | Exit | Meaning | You do |
+| --- | --- | --- | --- |
+| `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land) | Relay it. Done. |
+| `pending` | 3 | **Resumable, not a failure** — the bounded wait expired healthy, or a human owns the merge. Nothing was mutated. | Run `nextCommand`. |
+| `blocked` | 1 | Hard block; `blocked.blockClass` names it | `checks-failed` → fix + resume; else relay |
+| `failed` | 1 | A phase crashed; `phase` names which | Diagnose, fix, re-run close |
+
+Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
+`phase`, `elapsedSeconds`, `nextCommand`. `phase` is one of `init`,
+`wrong-tree-guard`, `close-validation`, `base-sync`, `push`, `pull-request`,
+`code-review`, `auto-merge`, `confirm-merge`, `post-land`, `done`. `gates`
+reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
+reported, never omitted, so a missing gate is never read as a passing one.
+
+**Gate output is captured, not streamed (#4736).** Close writes gate lines to
+`temp/orchestration/close-gates-<storyId>.log` and reports a one-line digest on
+success; a failed gate replays its tail inline. `AGENT_LOG_LEVEL=verbose`
+restores live streaming.
+
+## 6. When to leave this file
+
+- Unclear state / a re-run refusal → `deliver-recover.js --story <id>` (read-only).
+- Lease, sweep, worktree-scope detail → [`deliver-story-reference.md`](deliver-story-reference.md).
+- CI red after the PR opens → [`rules/ci-remediation.md`](../../rules/ci-remediation.md).
+- Sequencing, epilogue, checklist threading → [`deliver-reference.md`](deliver-reference.md).

package/.agents/workflows/helpers/deliver-reference.md

@@ -51,6 +51,16 @@ probe logs a warning and leans on init's lease refusal alone.
 
 ## Dispatch mechanics (role-scoped by default)
 
+**A single-Story run executes inline (Story #4736).** Sub-agent isolation is
+load-bearing only for **concurrent** dispatch — two workers sharing a checkout
+would race on worktrees and branch refs — so a run resolving exactly one Story
+has no sibling to isolate from and pays the spawn premium for nothing (a boot is
+a cache write at full rate; an inline continuation is a cache read at ~10%).
+`resolve-stories.js` already reports it: a one-id run comes back with
+`dispatchMode: "inline"` whatever the Story's shape. Role-scoped spawning is
+retained in full for multi-Story waves, and the rule changes **where** the
+engine runs, never what runs — gates, PR, and terminal envelope are identical.
+
 **Lite-shaped Stories execute inline (Story #4722).** Before spawning anything,
 read the Story's `dispatchMode` from the resolver envelope
 (`stories[].dispatchMode`, derived by `resolveStoryDispatchMode` in
@@ -114,6 +124,17 @@ execute it directly, in this turn, threading the same `docsDigestPath` /
 content, execute directly without a re-read turn. The engine, gates, and
 terminal envelope are identical either way — only the isolation differs.
 
+## Operator-merge implies no-wait
+
+`--no-auto-merge` and `delivery.ci.autoMerge: "strict"` leave the PR
+deliberately un-armed: there is nothing for close to land, so the Story rests
+at `agent::closing` for the human merge and is **not** flipped to
+`agent::blocked` — `--wait-merge` does not override this, because the operator
+owning the merge is a decision to respect, not a fault to report. A genuine
+*arm failure* is the opposite case: nobody chose it, so close still waits and
+still blocks. That asymmetry is what keeps the must-land contract intact
+without misfiling deliberate human merges as blocks.
+
 ## Per-run epilogue (N>1)
 
 Once the sequence reports `epilogueDue: true` (every Story done), keyed on the

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -341,6 +341,12 @@ The `single-story-close.js` script, in order:
 
 1. Runs the close-validation gates against `baseBranch` as the baseline.
    On any gate failure it throws — the operator fixes and re-runs close.
+   **Gate output is captured, not streamed (Story #4736).** Every gate line
+   goes to `temp/orchestration/close-gates-<storyId>.log`; a clean run reports
+   one digest line naming that artifact, and a **failed** gate replays its
+   captured tail inline so the evidence is in front of you without opening a
+   file. Read the artifact when you need the full text — or re-run under
+   `AGENT_LOG_LEVEL=verbose` for live streaming.
 1a. **Syncs the Story branch from `origin/<baseBranch>`** before push
    (Story #2580). Runs `git fetch origin <baseBranch>` followed by
    `git merge --no-edit origin/<baseBranch>` inside the worktree. This

package/.agents/workflows/helpers/deliver-story.md

@@ -11,6 +11,13 @@ description:
 > reference detail lives in
 > [`deliver-story-reference.md`](deliver-story-reference.md) ("reference"
 > below); consult on demand. Invoked by [`/deliver`](../deliver.md).
+>
+> **Read [`deliver-digest.md`](deliver-digest.md) once, first.** It is the
+> one bundled read of what every delivery needs — dispatch decision, engine
+> invariants, the change-set/ceremony incantation, the acceptance-eval gate,
+> and the terminal-envelope contract — replacing the per-session re-reads of
+> the helper set and `story-deliver-terminal.schema.json` (Story #4736). The
+> steps below cite it as "digest § N" rather than restating it.
 
 ## Overview
 
@@ -74,15 +81,10 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 
-Follow the single-homed include
-[`acceptance-self-eval.md`](acceptance-self-eval.md) (single verdict-owner,
-`verify[]`-as-evidence, proceed / redraft / block). Gate invocation (omit
-`--epic`):
-
-```bash
-node <main-repo>/.agents/scripts/acceptance-eval.js \
-  --story <storyId> --verdict <verdict-path>
-```
+Run the loop and score it with `acceptance-eval.js` — **digest § 4** carries
+the invocation and the proceed / redraft / block contract; per-round critic
+mechanics live in the single-homed include
+[`acceptance-self-eval.md`](acceptance-self-eval.md).
 
 **`proceed`** → Step 2 then Step 3. **`block`** → **do not close**: post a
 `friction` comment and flip `agent::blocked` — commands and the
@@ -92,16 +94,12 @@ node <main-repo>/.agents/scripts/acceptance-eval.js \
 ## Step 2 — Ceremony (profile + derived level)
 
 Ceremony is `delivery.routing.ceremonyProfile` × the **derived change
-level** — never a planner-authored verdict (Story #4542).
-**Compute the change set once** (Story #4593) with the shared enumerator
-[`computeChangeSet`](../../scripts/lib/orchestration/change-set.js) — the
-same module close uses — and hand that one list to every critic. Derive the
-level with `deriveChangeLevel`, resolve fresh-vs-inline critics with
-`resolveCeremonyForRisk` (`ceremony-routing.js`); a lite Story runs inline
-regardless (exact incantation and routing rules: reference § Step 2).
-Hard gates (lint / test / format / coverage / CRAP / maintainability)
-always run in Step 3 — the derived level never disables them; do **not**
-pre-run the full close chain here.
+level** — never a planner-authored verdict (Story #4542). **Digest § 3** is
+the incantation: compute the change set once (Story #4593), derive the level,
+resolve fresh-vs-inline critics with `ceremony-routing.js`; a lite Story runs
+inline regardless (routing edge cases: reference § Step 2). Hard gates always
+run in Step 3 — the derived level never disables them; do **not** pre-run the
+close chain here.
 
 ## Step 3 — Close and land (`single-story-close.js`)
 
@@ -110,15 +108,12 @@ node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <
 ```
 
 **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
-post-land tail in one process. Run it and **branch on the terminal
-envelope's `status`** (Story #4543):
-
-| `status` | Exit | Meaning | You do |
-| --- | --- | --- | --- |
-| `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land). | Relay the envelope (Step 7). |
-| `pending` | 3 | **Resumable, not a failure** — wait expired healthy, or a human owns the merge. | Run `nextCommand` until resolved. |
-| `blocked` | 1 | Hard block; `blocked.blockClass` names it. | `checks-failed` → Step 4; else relay. |
-| `failed` | 1 | A phase crashed; `phase` names which. | Diagnose, fix, re-run close. |
+post-land tail in one process. Run it and **branch on the terminal envelope's
+`status`** per the table in **digest § 5** (`landed` → Step 7; `pending` → run
+`nextCommand`; `blocked`/`checks-failed` → Step 4; `failed` → diagnose and
+re-run). Gate output is captured to
+`temp/orchestration/close-gates-<storyId>.log` — a clean run prints a digest
+line, a red gate replays its tail inline (Story #4736).
 
 Internals (gate order, base-sync, auto-merge arming), the merge-wait
 budgets, the slow-CI **async** confirm mode (Story #4698 — launch the
@@ -143,13 +138,13 @@ recovery path **only** when the envelope routes you there:
 
 ## Step 7 — Return contract (**required as a sub-agent**) {#return-contract}
 
-The contract is the shipped schema
-[`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
-— the SSOT for every field (Story #4543). End your turn by relaying the
-validated envelope close emits between its `--- STORY DELIVER TERMINAL ---`
-markers — never free-form prose, never a hand-composed object. `pending` is
-the only sanctioned no-merge ending, returned only when your own budget is
-exhausted (Story #1553). Reference § Step 7.
+End your turn by relaying the validated envelope close emits between its
+`--- STORY DELIVER TERMINAL ---` markers — never free-form prose, never a
+hand-composed object. Statuses, exits, and required fields: **digest § 5**
+(whose SSOT is the shipped
+[schema](../../schemas/story-deliver-terminal.schema.json), Story #4543).
+`pending` is the only sanctioned no-merge ending, returned only when your own
+budget is exhausted (Story #1553). Reference § Step 7.
 
 ## Recovering a stranded Story {#recover}
 
@@ -175,6 +170,7 @@ reuses an open PR).
 
 ## See also
 
+- [`deliver-digest.md`](deliver-digest.md) — the one bundled framework read.
 - [`/deliver`](../deliver.md) — unified entry point.
 - [`deliver-story-reference.md`](deliver-story-reference.md) — all on-demand
   detail.

package/docs/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.12.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.11.0...mandrel-v2.12.0) (2026-07-24)
+
+
+### Performance
+
+* **orchestration:** cut deliver-path cost — inline single-Story dispatch, bounded close output, bundled reads (refs [#4736](https://github.com/dsj1984/mandrel/issues/4736)) ([#4737](https://github.com/dsj1984/mandrel/issues/4737)) ([81e62a8](https://github.com/dsj1984/mandrel/commit/81e62a87ca49add2aeb5b5a6b9ac11014edc3374))
+
+
+### Changed
+
+* **orchestration:** thread injectedRules seam through route composition layers ([#4734](https://github.com/dsj1984/mandrel/issues/4734)) ([6e1daad](https://github.com/dsj1984/mandrel/commit/6e1daadbc24210fdb34e4892c0077256f2ccd051))
+
 ## [2.11.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.10.0...mandrel-v2.11.0) (2026-07-23)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",