mandrel 2.12.0 → 2.14.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/schemas/story-deliver-terminal.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-deliver-terminal.schema.json",
   "title": "story-deliver-terminal",
-  "description": "The single terminal envelope every Story close-and-land invocation emits (Story #4543). Before this schema, the delivery tail had two divergent prose return contracts — one in .agents/workflows/helpers/deliver-story.md, a different one in .agents/agents/story-worker.md — and neither was validated by anything, so a caller could not tell a landed Story from a parked one without re-probing GitHub. This is the SSOT both now reference rather than restate. status is exactly one of landed | pending | blocked | failed; phase names where the run ended; tail carries per-step booleans so a partial-tail degradation is visible without failing an otherwise-landed merge; nextCommand names the single command that resumes or remediates the run, drawn from the same vocabulary deliver-recover.js prints.",
+  "description": "The single terminal envelope a Story delivery invocation emits (Story #4543). Before this schema, the delivery tail had two divergent prose return contracts — one in .agents/workflows/helpers/deliver-story.md, a different one in .agents/agents/story-worker.md — and neither was validated by anything, so a caller could not tell a landed Story from a parked one without re-probing GitHub. This is the SSOT both now reference rather than restate. status is exactly one of landed | pending | blocked | failed | escalated; phase names where the run ended; tail carries per-step booleans so a partial-tail degradation is visible without failing an otherwise-landed merge; nextCommand names the single command that resumes or remediates the run, drawn from the same vocabulary deliver-recover.js prints. escalated (Story #4746) is the one status emitted BEFORE a Story exists — /deliver-light's suitability gate refusing an over-scope prompt — which is why storyId is null exactly there and non-null everywhere else.",
   "type": "object",
   "required": [
     "kind",
@@ -14,16 +14,21 @@
   ],
   "properties": {
     "kind": { "type": "string", "const": "story-deliver-terminal" },
-    "storyId": { "type": "integer", "minimum": 1 },
+    "storyId": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "description": "The Story this envelope reports on. null ONLY for status escalated, where the run refused before authoring a receipt Story — the allOf below pins that correspondence in both directions, so an escalated envelope cannot name a Story it did not create and a landed one cannot omit the Story it landed."
+    },
     "status": {
       "type": "string",
-      "description": "landed — the PR merged, the Story is agent::done, and the post-land tail was attempted. pending — a bounded wait expired with the PR still in flight; NO label was mutated and no merge.unlanded event was emitted, so the run is resumable via nextCommand. blocked — a classified hard block; the Story carries agent::blocked and blocked.blockClass names the class. failed — a phase crashed; phase names which one.",
-      "enum": ["landed", "pending", "blocked", "failed"]
+      "description": "landed — the PR merged, the Story is agent::done, and the post-land tail was attempted. pending — a bounded wait expired with the PR still in flight; NO label was mutated and no merge.unlanded event was emitted, so the run is resumable via nextCommand. blocked — a classified hard block; the Story carries agent::blocked and blocked.blockClass names the class. failed — a phase crashed; phase names which one. escalated — the /deliver-light suitability gate refused an over-scope prompt under --yes; nothing was created and the session ENDS here, nextCommand naming the /plan invocation that owns the work instead.",
+      "enum": ["landed", "pending", "blocked", "failed", "escalated"]
     },
     "phase": {
       "type": "string",
-      "description": "The pipeline phase the run ended in. Mirrors the close pipeline's phase names so a terminal envelope is attributable to one step.",
+      "description": "The pipeline phase the run ended in. Mirrors the close pipeline's phase names so a terminal envelope is attributable to one step. suitability-gate precedes them all — it is the /deliver-light gate, the only phase that runs before a Story exists.",
       "enum": [
+        "suitability-gate",
         "init",
         "wrong-tree-guard",
         "close-validation",
@@ -130,9 +135,35 @@
       },
       "additionalProperties": false
     },
+    "escalation": {
+      "type": ["object", "null"],
+      "description": "Present iff status === \"escalated\" (Story #4746). The suitability gate's decision was already correct before this block existed — what was missing was an outcome a session could not walk past. reasons carries the gate's own words; created records, per artifact, that the run started nothing.",
+      "required": ["reasons", "created"],
+      "properties": {
+        "reasons": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 },
+          "description": "The gate's reasons verbatim — the same strings the ask-operator path prints, so attended and unattended over-scope explain themselves identically."
+        },
+        "created": {
+          "type": "object",
+          "description": "Per-artifact proof that an escalated run left nothing half-started for a later run to trip over. Deliberately three const-false booleans rather than one aggregate flag or a bare omission: an omitted field reads as \"not checked\", and an aggregate is exactly the shape that let the post-land tail once report an outcome it never verified. Every value is pinned false by the schema, so an escalated envelope claiming it authored a receipt Story, cut a branch, or materialized a worktree cannot be built at all.",
+          "required": ["receiptStory", "storyBranch", "worktree"],
+          "properties": {
+            "receiptStory": { "const": false },
+            "storyBranch": { "const": false },
+            "worktree": { "const": false }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "nextCommand": {
       "type": ["string", "null"],
-      "description": "The single command that advances this Story from where it stopped, or null when status === \"landed\" and nothing remains. Shares its vocabulary with deliver-recover.js so recovery and normal resumption speak one language."
+      "description": "The single command that advances this work from where it stopped, or null when status === \"landed\" and nothing remains. Shares its vocabulary with deliver-recover.js so recovery and normal resumption speak one language. For status escalated it is the /plan invocation the operator runs in a FRESH session — the one case where the command is a slash command rather than a script, because the work needs planning, not resumption.",
+      "minLength": 1
     },
     "elapsedSeconds": { "type": "number", "minimum": 0 },
     "waitBudget": {
@@ -148,5 +179,28 @@
     },
     "timestamp": { "type": "string", "format": "date-time" }
   },
+  "allOf": [
+    {
+      "description": "escalated is the pre-Story terminal, and the correspondence is pinned in BOTH directions. An escalated envelope MUST carry the escalation block, MUST have a null storyId (it created none), and MUST name the next command that owns the work — so a run cannot report escalation while pointing at a Story it started. Every other status MUST carry an integer storyId and MUST NOT carry an escalation block, so the new status cannot leak into the close path.",
+      "if": {
+        "properties": { "status": { "const": "escalated" } },
+        "required": ["status"]
+      },
+      "then": {
+        "required": ["escalation"],
+        "properties": {
+          "storyId": { "type": "null" },
+          "escalation": { "type": "object" },
+          "nextCommand": { "type": "string", "minLength": 1 }
+        }
+      },
+      "else": {
+        "properties": {
+          "storyId": { "type": "integer", "minimum": 1 },
+          "escalation": { "type": "null" }
+        }
+      }
+    }
+  ],
   "additionalProperties": false
 }

package/.agents/scripts/deliver-light.js

@@ -0,0 +1,446 @@
+#!/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 emits an `escalated`
+ *     terminal envelope (`--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.
+ *
+ * ## Escalation is terminal, not advisory (Story #4746)
+ *
+ * Over-scope under `--yes` emits a schema-validated `story-deliver-terminal`
+ * envelope with status `escalated` and **ends the session**. Before that it was
+ * an ordinary gate envelope plus exit 2 — a warning a caller could walk past,
+ * and one mandrel-bench 2.13.0 light-arm run did exactly that: it read the
+ * escalation, invoked `/plan` in the same session, and delivered. In-session
+ * planning under-decomposed (ONE Story against the scenario's 3-5 contract,
+ * where a fresh `/plan` session on the identical seed authored four), so
+ * escalation silently produced the outcome the guard exists to prevent.
+ * {@link module:lib/orchestration/story-deliver-terminal.buildEscalationTerminal}
+ * carries the guarantees the schema then enforces.
+ *
+ * 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, or an `escalated` terminal), 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 {
+  buildEscalationTerminal,
+  emitTerminalEnvelope,
+  exitCodeForTerminal,
+} from './lib/orchestration/story-deliver-terminal.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 emits an escalated terminal
+                     envelope and ENDS the session (no prompt, no fallback).
+
+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.
+ *
+ * The three outcomes are deliberately asymmetric in what they emit:
+ *
+ *   - **`escalate-plan`** returns a schema-validated `escalated` **terminal
+ *     envelope** and stops (Story #4746). It is placed **first**, above every
+ *     creation call site, so "nothing was started" is a property of the
+ *     control flow rather than a claim the envelope makes about itself.
+ *   - **`ask-operator`** is unchanged: the plain gate envelope and exit 2. It
+ *     is not terminal — the operator has a choice to make, and manufacturing a
+ *     terminal for it would end a session that is supposed to be waiting.
+ *   - **`proceed-light`** authors the receipt Story and prints the hand-off.
+ *
+ * The injectable seams exist so the no-side-effect guarantee is testable
+ * without a network: a test asserts the escalate path never reaches them.
+ *
+ * @param {object} values Parsed CLI values.
+ * @param {{
+ *   createProviderFn?: typeof createProvider,
+ *   resolveConfigFn?: typeof resolveConfig,
+ *   createReceiptFn?: typeof createLightReceipt,
+ *   emitFn?: typeof emit,
+ *   emitTerminalFn?: typeof emitTerminalEnvelope,
+ * }} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runGateMode(values, deps = {}) {
+  const {
+    createProviderFn = createProvider,
+    resolveConfigFn = resolveConfig,
+    createReceiptFn = createLightReceipt,
+    emitFn = emit,
+    emitTerminalFn = emitTerminalEnvelope,
+  } = deps;
+
+  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 === 'escalate-plan') {
+    const envelope = buildEscalationTerminal({
+      prompt: String(values.prompt),
+      reasons: gate.outcome.reasons,
+    });
+    emitTerminalFn(envelope);
+    Logger.warn(
+      `[deliver-light] ESCALATED to /plan — this session ENDS here; run ${envelope.nextCommand} in a FRESH session: ${gate.outcome.reasons.join('; ')}`,
+    );
+    return exitCodeForTerminal(envelope);
+  }
+
+  if (gate.action !== 'proceed-light') {
+    emitFn(
+      { 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 = createProviderFn(resolveConfigFn());
+  const receipt = await createReceiptFn({
+    provider,
+    prompt: String(values.prompt),
+    changedFiles: [
+      ...parseCsvPaths(values.creates),
+      ...parseCsvPaths(values.refactors),
+    ],
+    amends: values.amends ?? null,
+  });
+  emitFn(
+    {
+      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/orchestration/complexity-gate.js

@@ -120,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,