mandrel 2.13.0 → 2.15.0

package/.agents/scripts/git-cleanup.js

@@ -129,4 +129,35 @@ async function main() {
   process.exit(exitCode);
 }
 
-runAsCli(import.meta.url, main, { source: 'git-cleanup' });
+runAsCli(import.meta.url, main, {
+  source: 'git-cleanup',
+  usage: {
+    invocation:
+      'node .agents/scripts/git-cleanup.js [--execute] [--yes] [--json] [phase flags] [filters]',
+    summary:
+      'Tidy the local checkout in four phases — fast-forward the base branch, prune stale remote refs, reap merged branches, triage stashes. Dry-run unless --execute.',
+    flags: [
+      ['--execute', 'Perform the mutations (default is a dry run).'],
+      ['--dry-run', 'Force a dry run even alongside --execute.'],
+      ['--yes', 'Skip the interactive confirmation prompts.'],
+      ['--json', 'Emit the plan/result envelope as JSON.'],
+      ['--remote', 'Also delete the matching remote branches.'],
+      ['--fast-forward-main', 'Run only the fast-forward-base phase.'],
+      ['--prune-remotes', 'Run only the prune-remotes phase.'],
+      ['--branches', 'Run only the merged-branch reap phase.'],
+      ['--stashes', 'Run only the stash-triage phase.'],
+      [
+        '--include <glob>',
+        'Only consider branches matching the glob (repeatable).',
+      ],
+      [
+        '--exclude <glob>',
+        'Never consider branches matching the glob (repeatable).',
+      ],
+      ['--drop-stashes <ref>', 'Stash ref approved for dropping (repeatable).'],
+      ['--base <branch>', 'Base branch (default: project.baseBranch).'],
+      ['--cwd <path>', 'Repository root (default: process cwd).'],
+    ],
+    notes: ['With no phase flag, every phase runs in order.'],
+  },
+});

package/.agents/scripts/lib/cli-usage.js

@@ -0,0 +1,174 @@
+/**
+ * `.agents/scripts/lib/cli-usage.js` — the one implementation of `--help` for
+ * every top-level script under `.agents/scripts/`.
+ *
+ * ## Why
+ *
+ * A script's flag contract used to live in the workflow prose that invoked it
+ * (`deliver-story.md` Step 0 restating `single-story-init.js`'s `--dry-run` /
+ * `--steal`, and so on). Two homes for one contract is a drift class: the
+ * script changes, the prose does not, and the next agent runs a flag that no
+ * longer exists. Moving the enumeration into the script's own `--help` gives
+ * the contract a single home that ships with the code that implements it.
+ *
+ * ## Contract
+ *
+ * `--help` (or `-h`) is a **query**, never an error path:
+ *
+ *   - writes non-empty text to **stdout** and exits **0**;
+ *   - performs no GitHub write, acquires no lease, mutates no working tree.
+ *
+ * stdout — not `Logger.info` — because help output must survive
+ * `AGENT_LOG_LEVEL=silent` and carry no `[Orchestrator]` decoration; this is
+ * the same `process.stdout.write` carve-out that machine-parsable envelopes
+ * use (see `tests/enforcement/no-console.test.js`).
+ *
+ * The short-circuit itself lives in `runAsCli` (`lib/cli-utils.js`), which
+ * fires this module **before** the script's `main` runs — so the "no side
+ * effects" half of the contract holds structurally rather than by each
+ * script remembering to check first.
+ *
+ * ## Usage
+ *
+ *   runAsCli(import.meta.url, main, {
+ *     source: 'my-script',
+ *     usage: {
+ *       invocation: 'node .agents/scripts/my-script.js --story <id> [--json]',
+ *       summary: 'One line on what the script does.',
+ *       flags: [
+ *         ['--story <id>', 'GitHub issue number of the Story (required).'],
+ *         ['--json', 'Emit the envelope as JSON instead of prose.'],
+ *       ],
+ *     },
+ *   });
+ *
+ * A pre-rendered string is accepted too, so a script that already shipped a
+ * hand-written `HELP` block adopts the shared gate without its observable
+ * text changing (`usage: HELP`).
+ */
+
+/** Tokens that request help. */
+export const HELP_FLAGS = Object.freeze(['--help', '-h']);
+
+/** Left column width for the flag table; longer flags wrap to their own line. */
+const FLAG_COLUMN = 22;
+
+/**
+ * Did the caller ask for help? Scans up to the `--` end-of-flags separator so
+ * a positional literally named `--help` after `--` is not mistaken for a
+ * request.
+ *
+ * @param {string[]} argv Argument vector without the node/script entries.
+ * @returns {boolean}
+ */
+export function wantsHelp(argv = []) {
+  if (!Array.isArray(argv)) return false;
+  for (const token of argv) {
+    if (token === '--') return false;
+    if (HELP_FLAGS.includes(token)) return true;
+  }
+  return false;
+}
+
+/**
+ * Normalize one flag entry into `{ flag, description }`. Accepts a
+ * `[flag, description]` pair or an object, so call sites can use whichever
+ * reads better next to their option table.
+ *
+ * @param {[string, string]|{flag: string, description?: string}} entry
+ * @returns {{ flag: string, description: string }}
+ */
+function normalizeFlag(entry) {
+  if (Array.isArray(entry)) {
+    return {
+      flag: String(entry[0] ?? ''),
+      description: String(entry[1] ?? ''),
+    };
+  }
+  return {
+    flag: String(entry?.flag ?? ''),
+    description: String(entry?.description ?? ''),
+  };
+}
+
+/**
+ * Render one `  --flag   description` row, wrapping onto a second line when
+ * the flag itself is wider than the column.
+ *
+ * @param {{ flag: string, description: string }} row
+ * @returns {string}
+ */
+function renderFlagRow({ flag, description }) {
+  if (!description) return `  ${flag}`;
+  if (flag.length >= FLAG_COLUMN) {
+    return `  ${flag}\n  ${' '.repeat(FLAG_COLUMN)}${description}`;
+  }
+  return `  ${flag.padEnd(FLAG_COLUMN)}${description}`;
+}
+
+/**
+ * Append the `--help` row unless the spec already documents it, so every
+ * rendered block is self-describing without each call site repeating it.
+ *
+ * @param {Array<{ flag: string, description: string }>} rows
+ * @returns {Array<{ flag: string, description: string }>}
+ */
+function withHelpRow(rows) {
+  const documented = rows.some((r) => r.flag.split(/[\s,]/)[0] === '--help');
+  if (documented) return rows;
+  return [...rows, { flag: '--help', description: 'Show this message.' }];
+}
+
+/**
+ * Render a usage spec into the text `--help` prints.
+ *
+ * @param {{
+ *   invocation: string,
+ *   summary?: string,
+ *   flags?: Array<[string, string]|{flag: string, description?: string}>,
+ *   notes?: string[],
+ * }} spec
+ * @returns {string} Text block, newline-terminated.
+ */
+export function formatUsage(spec) {
+  const rows = withHelpRow((spec?.flags ?? []).map(normalizeFlag));
+  const blocks = [`Usage: ${spec?.invocation ?? ''}`.trim()];
+  if (spec?.summary) blocks.push(spec.summary);
+  blocks.push(['Flags:', ...rows.map(renderFlagRow)].join('\n'));
+  for (const note of spec?.notes ?? []) blocks.push(note);
+  return `${blocks.join('\n\n')}\n`;
+}
+
+/**
+ * Coerce either accepted `usage` shape — a spec object or a pre-rendered
+ * string — into the text to print.
+ *
+ * @param {object|string} usage
+ * @returns {string}
+ */
+export function renderUsage(usage) {
+  if (typeof usage === 'string') {
+    return usage.endsWith('\n') ? usage : `${usage}\n`;
+  }
+  return formatUsage(usage);
+}
+
+/**
+ * Answer a help request. Returns `true` when help was requested (and printed),
+ * `false` when the caller should carry on with its normal path.
+ *
+ * Never throws on a missing/blank `usage`: a script whose spec renders empty
+ * still owes the contract non-empty stdout, so a minimal line is emitted
+ * rather than a silent exit that reads as a broken CLI.
+ *
+ * @param {string[]} argv
+ * @param {object|string} usage
+ * @param {{ write: (s: string) => void }} [out] Defaults to `process.stdout`.
+ * @returns {boolean}
+ */
+export function respondToHelp(argv, usage, out = process.stdout) {
+  if (!wantsHelp(argv)) return false;
+  const text = renderUsage(usage ?? '');
+  out.write(text.trim().length > 0 ? text : 'Usage: (no flags documented)\n');
+  return true;
+}

package/.agents/scripts/lib/cli-utils.js

@@ -16,6 +16,7 @@
 
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { respondToHelp } from './cli-usage.js';
 import { formatCliError } from './error-redactor.js';
 
 /**
@@ -37,12 +38,21 @@ export function isDirectInvocation(importMetaUrl) {
  * `main` is funnelled through either the caller-supplied `onError` callback
  * or the default handler (prefixed stderr line + `process.exit(exitCode)`).
  *
+ * A `usage` option makes the script self-describing: when the argv carries
+ * `--help` / `-h`, the rendered usage block goes to stdout and `main` is
+ * **never invoked**. That ordering is the whole point — it makes "`--help`
+ * performs no GitHub write, acquires no lease, and mutates no working tree"
+ * structurally true for every adopting script, rather than something each
+ * `main` has to remember to check before its first side effect.
+ *
  * @param {string} importMetaUrl        Caller's `import.meta.url`.
  * @param {() => Promise<unknown>} main The CLI's main function.
  * @param {object} [options]
  * @param {string} [options.source='CLI']           Prefix used in the default error message.
  * @param {number} [options.exitCode=1]             Exit code used by the default error handler.
  * @param {(err: Error) => void} [options.onError]  Full override of the error handler.
+ * @param {object|string} [options.usage]           Usage spec (or pre-rendered
+ *   text) printed for `--help`; see `lib/cli-usage.js`.
  */
 export function runAsCli(importMetaUrl, main, options = {}) {
   if (!isDirectInvocation(importMetaUrl)) return;
@@ -52,7 +62,9 @@ export function runAsCli(importMetaUrl, main, options = {}) {
     onError,
     propagateExitCode = false,
     errorPrefix,
+    usage,
   } = options;
+  if (usage && respondToHelp(process.argv.slice(2), usage)) return;
   const promise = main();
   if (propagateExitCode) {
     promise.then((code) => process.exit(code ?? 0));

package/.agents/scripts/lib/doc-tiers.js

@@ -29,11 +29,19 @@
  *                       converted spawn boots on **instead of** the always-loaded
  *                       closure, so it is budgeted independently (per-file ≤8KB
  *                       ceiling gated by `check-context-budget.js`).
+ *   - `workflow` /    — the `.agents/workflows/**` read-tier (Story #4752),
+ *     `workflowOnDemand` resolved as each entry point's transitive
+ *                       markdown-link closure by
+ *                       [`workflow-closure.js`](workflow-closure.js): the files
+ *                       an entry point's `mandatoryReads:` frontmatter forces
+ *                       you to read (`workflow`, gated) versus the reachable
+ *                       remainder (`workflowOnDemand`, recorded only).
  *
  * A file that could appear in more than one tier is kept in its **highest**
  * tier only (alwaysLoaded > mandatoryRead > digestVisible > onDemand), so the
  * arrays partition the doc set with no double-counting. `agentBoot` is disjoint
- * from the read-tiers (it lives under `.agents/agents/`, not the doc/rules set).
+ * from the read-tiers (it lives under `.agents/agents/`, not the doc/rules set),
+ * and so are the workflow tiers (confined to `.agents/workflows/`).
  *
  * The closure is discovered by parsing `@`-import references and following
  * them recursively (cycle-safe via a visited set). A candidate `@`-token only
@@ -47,6 +55,7 @@
 
 import nodeFs from 'node:fs';
 import path from 'node:path';
+import { resolveWorkflowClosures } from './workflow-closure.js';
 
 /**
  * Basename of the always-loaded entry document (the root of the closure).
@@ -212,18 +221,31 @@ export function docsContextPaths(config) {
 }
 
 /**
- * Resolve the four documentation read-tiers, each entry `{ path, bytes }`,
+ * Resolve the documentation read-tiers, each entry `{ path, bytes }`,
  * partitioned so no path appears in more than one tier (highest tier wins).
+ * `workflowClosure` rides alongside the tiers as the per-entry-point workflow
+ * measurement (Story #4752) — its `reachableTotalBytes` is a recorded drift
+ * signal, never a gate.
  *
  * @param {object} config resolved config (`resolveConfig()` output)
  * @param {{ root?: string, fs?: FsLike }} [opts]
- * @returns {{ tiers: {
- *   alwaysLoaded: Array<{ path: string, bytes: number }>,
- *   mandatoryRead: Array<{ path: string, bytes: number }>,
- *   digestVisible: Array<{ path: string, bytes: number }>,
- *   onDemand: Array<{ path: string, bytes: number }>,
- *   agentBoot: Array<{ path: string, bytes: number }>,
- * } }}
+ * @returns {{
+ *   tiers: {
+ *     alwaysLoaded: Array<{ path: string, bytes: number }>,
+ *     mandatoryRead: Array<{ path: string, bytes: number }>,
+ *     digestVisible: Array<{ path: string, bytes: number }>,
+ *     onDemand: Array<{ path: string, bytes: number }>,
+ *     agentBoot: Array<{ path: string, bytes: number }>,
+ *     workflow: Array<{ path: string, bytes: number }>,
+ *     workflowOnDemand: Array<{ path: string, bytes: number }>,
+ *   },
+ *   workflowClosure: {
+ *     mandatoryTotalBytes: number,
+ *     reachableTotalBytes: number,
+ *     entryPoints: Array<{ path: string, mandatoryBytes: number, reachableBytes: number }>,
+ *   },
+ * }}
+ * @throws {Error} on an unresolvable `mandatoryReads` entry or a mandatory cycle
  */
 export function resolveDocTiers(
   config,
@@ -265,8 +287,29 @@ export function resolveDocTiers(
   //    are standalone system prompts, disjoint from the doc read-tiers.
   const agentBoot = collect(listAgentDefs(root, fs));
 
+  // 6. workflow: each entry point's transitive markdown-link closure (#4752),
+  //    split into the gated mandatory set and the recorded on-demand remainder.
+  //    The walk is confined to `.agents/workflows/**`, and `collect` still
+  //    de-dupes, so no path is counted against two tiers.
+  const closure = resolveWorkflowClosures(root, { fs });
+  const workflow = collect(closure.mandatoryFiles.map((e) => e.path));
+  const workflowOnDemand = collect(closure.onDemandFiles.map((e) => e.path));
+
   return {
-    tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand, agentBoot },
+    tiers: {
+      alwaysLoaded,
+      mandatoryRead,
+      digestVisible,
+      onDemand,
+      agentBoot,
+      workflow,
+      workflowOnDemand,
+    },
+    workflowClosure: {
+      mandatoryTotalBytes: closure.mandatoryTotalBytes,
+      reachableTotalBytes: closure.reachableTotalBytes,
+      entryPoints: closure.entryPoints,
+    },
   };
 }
 

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

@@ -356,7 +356,7 @@ function resolveRiskHeuristics(config = {}) {
 
 /**
  * Ceilings a seed's advisory complexity signals must fit for the plan
- * workflow to **suggest** `/deliver-light` at Gate #1 (Story #4741 R3 plan-side
+ * workflow to **suggest** the light path at Gate #1 (Story #4741 R3 plan-side
  * handshake). Framework constants, not operator knobs — mirroring the
  * conservative intent of `complexity-gate.js`'s `STORY_SHAPE_CEILINGS`
  * (small, mostly-additive, non-sensitive) but read against the *seed-time*
@@ -364,9 +364,14 @@ function resolveRiskHeuristics(config = {}) {
  *
  * The suggestion is **advisory only and never an automatic reroute**: it
  * surfaces at Gate #1 for the operator to decide, and under `--yes` it is
- * recorded on the envelope while planning proceeds unchanged. `/deliver-light`
- * is a sibling Story; these ceilings define the plan side of the routing
- * handshake independently of it.
+ * recorded on the envelope while planning proceeds unchanged.
+ *
+ * These ceilings are deliberately NOT the ones the light path itself applies
+ * (Story #4760). A confirmed suggestion routes into
+ * `workflows/helpers/deliver-light.md`, whose gate re-judges the *predicted
+ * shape* against `STORY_SHAPE_CEILINGS`. Two checks at two different stages:
+ * this one screens a seed, that one decides. Collapsing them would make a
+ * confirm a bypass.
  *
  *   - `maxArtifacts`           — enumerated seed items (one artifact each).
  *   - `maxRiskHeuristicHits`   — any risk-heuristic hit disqualifies: risk
@@ -381,9 +386,9 @@ const DELIVER_LIGHT_SUGGESTION_CEILINGS = Object.freeze({
 });
 
 /**
- * Derive the advisory `/deliver-light` suggestion from a seed's complexity
- * signals (Story #4741 AC-6). Pure and total: a malformed / missing signal
- * bag fails conservative (not suggested), never throws.
+ * Derive the advisory light-path suggestion from a seed's complexity signals
+ * (Story #4741 AC-6). Pure and total: a malformed / missing signal bag fails
+ * conservative (not suggested), never throws.
  *
  * `automatic: false` is part of the contract — the suggestion is surfaced for
  * the operator, never a silent reroute of a non-interactive run.
@@ -435,16 +440,16 @@ export function buildDeliverLightSuggestion(complexitySignals) {
     ceilings,
     reasons: suggested
       ? [
-          `seed fits the /deliver-light ceilings (≤${ceilings.maxArtifacts} artifacts, ` +
+          `seed fits the light-path ceilings (≤${ceilings.maxArtifacts} artifacts, ` +
             'no risk-heuristic hits, no sensitive-path classes) — the operator ' +
-            'may prefer /deliver-light for this scope',
+            'may prefer /deliver for this scope',
         ]
       : reasons,
   };
 }
 
 /**
- * Attach the advisory `/deliver-light` suggestion to a complexity-signals bag
+ * Attach the advisory light-path suggestion to a complexity-signals bag
  * as a **nested** field (Story #4741). Nesting — rather than a new top-level
  * envelope key — keeps every existing per-mode envelope key set byte-stable
  * (AC-5): the suggestion is derived from the signals it rides on.
@@ -920,7 +925,7 @@ function extractPriorArtifacts(priorBody) {
 /**
  * Build the amendment (delta) envelope — `plan-context --amends #<id>`
  * (Story #4741 AC-4, R3-A). The heavy-amendment counterpart to routing a
- * light amendment through `/deliver-light`: instead of re-interrogating the
+ * light amendment through the light path: instead of re-interrogating the
  * repo from scratch (`buildAuthoringContext`'s codebase snapshot and the BDD /
  * memory / feedback probes), the envelope composes a DELTA from what already
  * exists — the prior Story's body, its acceptance criteria (the real

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -61,6 +61,15 @@ export const TERMINAL_EXIT_CODES = Object.freeze({
   pending: 3,
   blocked: 1,
   failed: 1,
+  /**
+   * `escalated` reuses **2**, the code `/deliver-light` already documents for
+   * "the gate did not proceed light" — the escalation is that outcome made
+   * terminal, not a new one, so giving it a fresh code would fork a vocabulary
+   * callers already branch on. It stays distinct from `landed` (nothing was
+   * delivered) and from `blocked`/`failed` (nothing is wrong — the work simply
+   * belongs to `/plan`).
+   */
+  escalated: 2,
 });
 
 export const TERMINAL_STATUSES = Object.freeze([
@@ -68,13 +77,38 @@ export const TERMINAL_STATUSES = Object.freeze([
   'pending',
   'blocked',
   'failed',
+  'escalated',
 ]);
 
+/** Cap on the prompt echoed into an escalation's `/plan` next command. */
+const PLAN_PROMPT_MAX = 200;
+
+/**
+ * Render an operator prompt safe to sit inside the double quotes of the
+ * `/plan "<prompt>"` next command: collapse newlines (a next command is one
+ * line by contract), escape backslashes and double quotes so the quoting
+ * cannot be broken out of, and cap the length so a long prompt does not turn
+ * the envelope into a transcript. Total — a non-string yields the empty
+ * string, which the escalation builder rejects rather than emitting.
+ *
+ * @param {unknown} prompt
+ * @returns {string}
+ */
+function quoteForPlan(prompt) {
+  const text =
+    typeof prompt === 'string' ? prompt.replace(/\s+/g, ' ').trim() : '';
+  const capped =
+    text.length > PLAN_PROMPT_MAX
+      ? `${text.slice(0, PLAN_PROMPT_MAX - 1).trimEnd()}…`
+      : text;
+  return capped.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
 /**
  * The shared next-command vocabulary. Every producer of a "what now?"
- * answer — the `pending` terminal envelope and `deliver-recover.js` —
- * builds its command from here, so the two surfaces never drift into
- * naming different commands for the same observed state.
+ * answer — the `pending` terminal envelope, an `escalated` one, and
+ * `deliver-recover.js` — builds its command from here, so the surfaces never
+ * drift into naming different commands for the same observed state.
  */
 export const NEXT_COMMANDS = Object.freeze({
   /**
@@ -104,6 +138,18 @@ export const NEXT_COMMANDS = Object.freeze({
   /** Probe a stranded Story and print its single next command. */
   recover: (storyId) =>
     `node .agents/scripts/deliver-recover.js --story ${storyId}`,
+  /**
+   * Hand over-scope work to `/plan` — the next command of an `escalated`
+   * terminal (Story #4746).
+   *
+   * The only entry here that is a slash command rather than a script, and
+   * deliberately so: the other entries resume a Story that exists, while this
+   * one names work that has no Story yet and needs planning before it can have
+   * one. It is quoted for a shell but addressed to a **fresh session** — see
+   * the workflow's escalation section for why running it in the escalating
+   * session is forbidden.
+   */
+  escalateToPlan: (prompt) => `/plan "${quoteForPlan(prompt)}"`,
 });
 
 /** @type {Function|null} */
@@ -165,8 +211,9 @@ function compact(obj) {
  * this replaces.
  *
  * @param {object} args
- * @param {number} args.storyId
- * @param {'landed'|'pending'|'blocked'|'failed'} args.status
+ * @param {number|null} args.storyId `null` only for an `escalated` terminal,
+ *   which by construction never authored a Story.
+ * @param {'landed'|'pending'|'blocked'|'failed'|'escalated'} args.status
  * @param {string} args.phase
  * @param {string} [args.storyBranch]
  * @param {string} [args.baseBranch]
@@ -175,6 +222,7 @@ function compact(obj) {
  * @param {object|null} [args.tail]
  * @param {object|null} [args.blocked]
  * @param {object|null} [args.failure]
+ * @param {object|null} [args.escalation]
  * @param {string|null} [args.nextCommand]
  * @param {number} args.elapsedSeconds
  * @param {object|null} [args.waitBudget]
@@ -192,6 +240,7 @@ export function buildTerminalEnvelope({
   tail,
   blocked,
   failure,
+  escalation,
   nextCommand,
   elapsedSeconds = 0,
   waitBudget,
@@ -199,7 +248,10 @@ export function buildTerminalEnvelope({
 }) {
   const envelope = compact({
     kind: TERMINAL_ENVELOPE_KIND,
-    storyId: Number(storyId),
+    // `Number(null)` is 0, which would quietly satisfy nothing and confuse
+    // everything — a nullish storyId stays null and lets the schema decide
+    // whether this status is allowed to omit one.
+    storyId: storyId === null || storyId === undefined ? null : Number(storyId),
     status,
     phase,
     storyBranch: storyBranch ?? null,
@@ -209,6 +261,7 @@ export function buildTerminalEnvelope({
     tail: tail ?? null,
     blocked: blocked ?? null,
     failure: failure ?? null,
+    escalation: escalation ?? null,
     nextCommand: nextCommand ?? null,
     elapsedSeconds: Math.max(0, Number(elapsedSeconds) || 0),
     waitBudget: waitBudget ?? null,
@@ -225,6 +278,69 @@ export function buildTerminalEnvelope({
   return envelope;
 }
 
+/**
+ * Build the `escalated` terminal — the one envelope emitted before a Story
+ * exists (Story #4746).
+ *
+ * `/deliver-light`'s suitability gate already decided correctly when it
+ * overrode a `lite` self-verdict on shape; what it lacked was an outcome a
+ * session could not walk past. A mandrel-bench 2.13.0 light-arm run did
+ * exactly that — it read the gate's `escalate-plan`, then invoked `/plan`
+ * in the same session and delivered. The continuation was not harmless:
+ * planning inside a session already framed as small work authored ONE Story
+ * against the scenario's 3-5 contract, where a fresh `/plan` session on the
+ * identical seed authored four. Escalation silently produced the very
+ * under-decomposition the guard exists to prevent.
+ *
+ * So the outcome is a validated envelope with its own exit code, naming the
+ * `/plan` command that owns the work, and asserting per artifact that nothing
+ * was started. Every guarantee here is enforced by the schema rather than by
+ * prose: `storyId` must be null, `escalation.created.*` are pinned `false`.
+ *
+ * @param {{
+ *   prompt: string,
+ *   reasons?: string[],
+ *   elapsedSeconds?: number,
+ *   timestamp?: string,
+ * }} args
+ * @returns {object} The validated `escalated` envelope.
+ */
+export function buildEscalationTerminal({
+  prompt,
+  reasons,
+  elapsedSeconds = 0,
+  timestamp,
+}) {
+  const quoted = quoteForPlan(prompt);
+  if (quoted === '') {
+    // An escalation whose next command is `/plan ""` hands the operator
+    // nothing — the same walk-past-able non-outcome in envelope clothing.
+    throw new TypeError(
+      'buildEscalationTerminal: a non-empty prompt is required — the escalated terminal exists to name the /plan invocation that owns the work',
+    );
+  }
+  const recorded = (Array.isArray(reasons) ? reasons : []).filter(
+    (r) => typeof r === 'string' && r.trim() !== '',
+  );
+  return buildTerminalEnvelope({
+    storyId: null,
+    status: 'escalated',
+    phase: 'suitability-gate',
+    escalation: {
+      reasons:
+        recorded.length > 0
+          ? recorded
+          : ['predicted scope exceeds the light ceilings — escalate to /plan'],
+      // Not computed from anything: the escalation path returns before the
+      // receipt/init call sites, so these are the assertion that it did.
+      created: { receiptStory: false, storyBranch: false, worktree: false },
+    },
+    nextCommand: NEXT_COMMANDS.escalateToPlan(prompt),
+    elapsedSeconds,
+    ...(timestamp === undefined ? {} : { timestamp }),
+  });
+}
+
 /**
  * Resolve the process exit code for a terminal envelope.
  *