mandrel 2.11.0 → 2.13.0

package/.agents/docs/workflows.md

@@ -32,7 +32,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (24)
+## Commands (25)
 
 | Command | Description |
 | --- | --- |
@@ -53,6 +53,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --seed-file or opens standalone Stories. |
 | `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
 | `/deliver` | Unified delivery entry point. Takes a list of Story ids, resolves their dependency graph from live state, and delivers each via the single deliver-story engine — story-<id> → PR → main. |
+| `/deliver-light` | Single-session delivery for genuinely small work. Judges a prompt's predicted footprint, authors a receipt Story, then lands it through the same single-story-init / single-story-close engine — every close gate unchanged. |
 | `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
 | `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |

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/deliver-light.js

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+
+/**
+ * deliver-light.js — the `/deliver-light` entry point (Story #4740).
+ *
+ * A **thin entry point, not a second delivery engine.** It runs the
+ * suitability gate, authors a minimal receipt `type::story`, and then hands off
+ * to the SAME engine scripts `/deliver` uses:
+ *
+ *   suitability gate  →  inline receipt Story  →  single-story-init.js
+ *     →  (agent implements + self-evals)  →  diff backstop
+ *     →  single-story-close.js  (close-and-land, every gate byte-identical)
+ *
+ * Worktree, branch, lease, PR, and merge mechanics are **invoked, never
+ * reimplemented** — this file contains no parallel init/close logic
+ * ({@link buildNextCommands} references the engine scripts by name). The
+ * reusable decision core lives in
+ * {@link module:lib/orchestration/light-suitability}; this module is the CLI
+ * shell plus the receipt-authoring and diff-backstop wiring.
+ *
+ * Two modes:
+ *
+ *   - **gate** (default) — judge a prompt's predicted footprint. On
+ *     `proceed-light` it authors the receipt Story (via the plan-persist
+ *     `createStoryIssues` surface) and prints the init/close hand-off. On
+ *     over-scope it prints `ask-operator` (attended) or `escalate-plan`
+ *     (`--yes`), never landing silently.
+ *   - **backstop** (`--backstop --story <id>`) — re-check the ACTUAL diff of
+ *     the Story branch after implementation; exit non-zero when it exceeds the
+ *     light ceilings, so an over-scope diff is blocked rather than landed.
+ *
+ * Usage:
+ *   node .agents/scripts/deliver-light.js --prompt "<text>" \
+ *     --creates path,path --acceptance 1 --route lite --reason "<why>"
+ *   node .agents/scripts/deliver-light.js --prompt "<text>" --amends '#123' --route lite --reason "<why>"
+ *   node .agents/scripts/deliver-light.js --backstop --story 4741
+ *
+ * Exit codes: 0 ok (proceed / clean backstop), 1 usage error, 2 the gate did
+ * not proceed light (ask-operator / escalate-plan), 3 the diff backstop blocked.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
+import { computeChangeSet } from './lib/orchestration/change-set.js';
+import {
+  buildReceiptStoryTicket,
+  checkLightDiffBackstop,
+  deriveLightSuitability,
+  resolveLightGateOutcome,
+} from './lib/orchestration/light-suitability.js';
+import {
+  assemblePlanStories,
+  createStoryIssues,
+} from './lib/orchestration/plan-persist/story-ops.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const HELP = `\
+Usage:
+  deliver-light.js --prompt <text> [--creates csv] [--refactors csv]
+                   [--acceptance n] [--route lite|full] [--reason <text>]
+                   [--amends '#id'] [--yes]
+  deliver-light.js --backstop --story <id>
+
+The thin /deliver-light entry point: suitability gate → inline receipt Story →
+the same single-story-init.js / single-story-close.js engine /deliver uses.
+
+Gate options:
+  --prompt <text>    Operator prompt describing the change. Required for the gate.
+  --creates <csv>    Predicted NEW file paths (comma-separated).
+  --refactors <csv>  Predicted edited/existing file paths (comma-separated).
+  --acceptance <n>   Predicted acceptance-criteria count (default 1).
+  --route <r>        Ledgered model verdict route: lite | full.
+  --reason <text>    Recorded reason for a lite verdict (required for lite).
+  --amends <#id>     Mark this as an amendment of an existing issue.
+  --yes              Unattended: over-scope fails closed to /plan (no prompt).
+
+Backstop options:
+  --backstop         Re-check the ACTUAL diff after implementation.
+  --story <id>       Story issue number whose story-<id> branch to diff.
+
+  --pretty           Pretty-print the JSON envelope.
+  --help             Show this help.
+`;
+
+/** Exit code when the gate did not resolve to proceed-light. */
+const EXIT_NOT_PROCEED = 2;
+/** Exit code when the diff backstop blocked the land. */
+const EXIT_BACKSTOP_BLOCKED = 3;
+
+/**
+ * Split a comma-separated path list into trimmed, non-empty entries.
+ *
+ * @param {string|undefined} csv
+ * @returns {string[]}
+ */
+export function parseCsvPaths(csv) {
+  if (typeof csv !== 'string' || csv.trim() === '') return [];
+  return csv
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s !== '');
+}
+
+/**
+ * Assemble the predicted `changes[]` footprint from the declared creates /
+ * refactors lists — the input {@link deriveLightSuitability} shape-checks.
+ *
+ * @param {{ creates?: string[], refactors?: string[] }} args
+ * @returns {Array<{ path: string, assumption: string }>}
+ */
+export function buildPredictedChanges({ creates = [], refactors = [] } = {}) {
+  return [
+    ...creates.map((path) => ({ path, assumption: 'creates' })),
+    ...refactors.map((path) => ({ path, assumption: 'refactors-existing' })),
+  ];
+}
+
+/**
+ * Synthesize a predicted-acceptance array of the requested length — the shape
+ * gate reads the count, not the text, so placeholder strings suffice. A count
+ * below 1 yields a single-item array (a Story with no contract cannot be judged
+ * trivial, and the shape derivation rejects a zero-length acceptance anyway).
+ *
+ * @param {unknown} count
+ * @returns {string[]}
+ */
+export function synthesizeAcceptance(count) {
+  const n =
+    typeof count === 'number' && Number.isFinite(count) && count >= 1
+      ? Math.floor(count)
+      : 1;
+  return Array.from({ length: n }, (_v, i) => `AC-${i + 1}`);
+}
+
+/**
+ * Run the suitability gate purely — no I/O. Returns the outcome envelope the
+ * CLI serializes. The prompt text and `--amends` target are deliberately **not**
+ * inputs: routing is shape-checked identically whether or not the change is an
+ * amendment (Story #4740 R3), and the prompt's text carries no routing signal —
+ * the predicted footprint does. Both flow into the receipt Story instead.
+ *
+ * @param {{
+ *   creates?: string[],
+ *   refactors?: string[],
+ *   acceptance?: number,
+ *   route?: string,
+ *   reason?: string,
+ *   yes?: boolean,
+ *   injectedRules?: object,
+ * }} args
+ * @returns {{ action: string, suitability: object, outcome: object }}
+ */
+export function runLightGate({
+  creates = [],
+  refactors = [],
+  acceptance,
+  route,
+  reason,
+  yes = false,
+  injectedRules,
+} = {}) {
+  const predictedChanges = buildPredictedChanges({ creates, refactors });
+  const suitability = deriveLightSuitability({
+    predictedChanges,
+    predictedAcceptance: synthesizeAcceptance(acceptance),
+    verdict: { route, reason },
+    injectedRules,
+  });
+  const outcome = resolveLightGateOutcome({ suitability, yes });
+  return { action: outcome.action, suitability, outcome };
+}
+
+/**
+ * Author the receipt Story via the plan-persist creation surface (reused, not
+ * reimplemented). Injectable seams keep it unit-testable without a network.
+ *
+ * @param {{
+ *   provider: object,
+ *   prompt: string,
+ *   changedFiles?: string[],
+ *   amends?: string|number|null,
+ *   assembleFn?: typeof assemblePlanStories,
+ *   createFn?: typeof createStoryIssues,
+ * }} args
+ * @returns {Promise<{ storyId: number, url: string|undefined, title: string }>}
+ */
+export async function createLightReceipt({
+  provider,
+  prompt,
+  changedFiles = [],
+  amends = null,
+  assembleFn = assemblePlanStories,
+  createFn = createStoryIssues,
+} = {}) {
+  const ticket = buildReceiptStoryTicket({ prompt, changedFiles, amends });
+  const { stories } = assembleFn([ticket]);
+  const { created } = await createFn({ provider, stories });
+  const receipt = created[0];
+  if (!receipt || !Number.isInteger(receipt.id)) {
+    throw new Error(
+      '[deliver-light] receipt Story creation did not return a numeric id',
+    );
+  }
+  return { storyId: receipt.id, url: receipt.url, title: receipt.title };
+}
+
+/**
+ * The engine hand-off — the SAME scripts `/deliver` uses. Named here as
+ * commands, never reimplemented: this is the whole of deliver-light's
+ * relationship to worktree/branch/lease/PR/merge mechanics.
+ *
+ * @param {number} storyId
+ * @returns {{ init: string, close: string }}
+ */
+export function buildNextCommands(storyId) {
+  return {
+    init: `node .agents/scripts/single-story-init.js --story ${storyId}`,
+    close: `node .agents/scripts/single-story-close.js --story ${storyId} --cwd <main-repo>`,
+  };
+}
+
+/**
+ * Run the diff backstop against a Story branch's actual change set.
+ *
+ * @param {{
+ *   storyId: number,
+ *   baseRef?: string,
+ *   cwd?: string,
+ *   computeFn?: typeof computeChangeSet,
+ *   injectedRules?: object,
+ * }} args
+ * @returns {ReturnType<typeof checkLightDiffBackstop>}
+ */
+export function runDiffBackstop({
+  storyId,
+  baseRef = 'main',
+  cwd = process.cwd(),
+  computeFn = computeChangeSet,
+  injectedRules,
+} = {}) {
+  const { files } = computeFn({
+    baseRef,
+    headRef: `story-${storyId}`,
+    cwd,
+  });
+  return checkLightDiffBackstop({ changedFiles: files, injectedRules });
+}
+
+/**
+ * Emit a JSON envelope on stdout (the machine surface) so a headless caller can
+ * branch on it. Human-readable log lines stay on stderr.
+ *
+ * @param {object} envelope
+ * @param {boolean} pretty
+ */
+function emit(envelope, pretty) {
+  process.stdout.write(
+    pretty
+      ? `${JSON.stringify(envelope, null, 2)}\n`
+      : `${JSON.stringify(envelope)}\n`,
+  );
+}
+
+/**
+ * Backstop mode — re-check the actual diff.
+ *
+ * @param {{ story?: string, pretty: boolean }} values
+ * @returns {Promise<number>}
+ */
+async function runBackstopMode(values) {
+  const storyId = Number.parseInt(String(values.story ?? ''), 10);
+  if (!Number.isInteger(storyId) || storyId <= 0) {
+    process.stderr.write(HELP);
+    throw new Error('[deliver-light] --backstop requires --story <id>');
+  }
+  const result = runDiffBackstop({ storyId });
+  emit({ mode: 'backstop', storyId, ...result }, values.pretty);
+  if (result.blocked) {
+    Logger.warn(
+      `[deliver-light] diff backstop BLOCKED Story #${storyId}: ${result.reasons.join('; ')}`,
+    );
+    return EXIT_BACKSTOP_BLOCKED;
+  }
+  Logger.info(`[deliver-light] diff backstop clean for Story #${storyId}.`);
+  return 0;
+}
+
+/**
+ * Gate mode — judge the prompt and, on proceed, author the receipt Story.
+ *
+ * @param {object} values Parsed CLI values.
+ * @returns {Promise<number>}
+ */
+async function runGateMode(values) {
+  if (!values.prompt || String(values.prompt).trim() === '') {
+    process.stderr.write(HELP);
+    throw new Error('[deliver-light] --prompt <text> is required for the gate');
+  }
+
+  const gate = runLightGate({
+    creates: parseCsvPaths(values.creates),
+    refactors: parseCsvPaths(values.refactors),
+    acceptance: values.acceptance
+      ? Number.parseInt(String(values.acceptance), 10)
+      : 1,
+    route: values.route,
+    reason: values.reason,
+    yes: values.yes === true,
+  });
+
+  if (gate.action !== 'proceed-light') {
+    emit(
+      { mode: 'gate', action: gate.action, outcome: gate.outcome },
+      values.pretty,
+    );
+    Logger.warn(
+      `[deliver-light] gate did not proceed light (${gate.action}): ${gate.outcome.reasons.join('; ')}`,
+    );
+    return EXIT_NOT_PROCEED;
+  }
+
+  const provider = createProvider(resolveConfig());
+  const receipt = await createLightReceipt({
+    provider,
+    prompt: String(values.prompt),
+    changedFiles: [
+      ...parseCsvPaths(values.creates),
+      ...parseCsvPaths(values.refactors),
+    ],
+    amends: values.amends ?? null,
+  });
+  emit(
+    {
+      mode: 'gate',
+      action: 'proceed-light',
+      storyId: receipt.storyId,
+      url: receipt.url,
+      nextCommands: buildNextCommands(receipt.storyId),
+      outcome: gate.outcome,
+    },
+    values.pretty,
+  );
+  Logger.info(
+    `[deliver-light] receipt Story #${receipt.storyId} created — hand off to single-story-init.js.`,
+  );
+  return 0;
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      prompt: { type: 'string' },
+      creates: { type: 'string' },
+      refactors: { type: 'string' },
+      acceptance: { type: 'string' },
+      route: { type: 'string' },
+      reason: { type: 'string' },
+      amends: { type: 'string' },
+      yes: { type: 'boolean', default: false },
+      backstop: { type: 'boolean', default: false },
+      story: { type: 'string' },
+      pretty: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  // stdout is a JSON stream — keep human-readable output on stderr.
+  routeAllOutputToStderr();
+
+  return values.backstop ? runBackstopMode(values) : runGateMode(values);
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'deliver-light',
+  propagateExitCode: true,
+});

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
@@ -117,11 +120,14 @@ export const LITE_ROUTE_LABEL = 'route::lite';
  *                             surfaces is where trivial-looking work stops
  *                             being trivial.
  *
- * Module-private, exposed as the `ceilings` field on every
- * {@link deriveStoryShape} decision — so there is no test-only export to
- * leave production-dead.
+ * Exposed as the `ceilings` field on every {@link deriveStoryShape} decision
+ * and exported directly (Story #4740) so the `/deliver-light` suitability gate
+ * ({@link module:lib/orchestration/light-suitability}) judges a prompt's
+ * predicted footprint against the **same** ceilings the plan-time shape
+ * backstop applies — one source, so the light entry point and the plan path can
+ * never disagree about what shape is trivial.
  */
-const STORY_SHAPE_CEILINGS = Object.freeze({
+export const STORY_SHAPE_CEILINGS = Object.freeze({
   maxChanges: 2,
   maxAcceptance: 3,
   maxNonCreateChanges: 1,
@@ -561,37 +567,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 +640,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 {