mandrel 2.11.0 → 2.13.0

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

@@ -17,6 +17,12 @@
  *   --tickets 123[,456…]      Analyze existing issue(s) into proper
  *                             Stories. Envelope carries `sourceTickets[]`.
  *
+ *   --amends 123 | #123       Amendment (delta) planning. Composes a DELTA
+ *                             envelope from the prior Story's body, its
+ *                             acceptance criteria, and its delivered file map
+ *                             instead of re-interrogating the repo from
+ *                             scratch (Story #4741). Envelope carries `amends`.
+ *
  * Flags:
  *   --out <path>     Write the envelope to <path> (parent dirs created).
  *                    `/plan` points this at `<plan-dir>/plan-context.json`,
@@ -83,6 +89,25 @@ export function parseTicketIds(raw) {
   return [...new Set(ids)];
 }
 
+/**
+ * Parse a single `--amends` id, tolerating a leading `#` (`#123` or `123`).
+ *
+ * @param {string} raw
+ * @returns {number}
+ */
+export function parseAmendsId(raw) {
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new Error('--amends requires a single prior Story id.');
+  }
+  const id = Number(raw.trim().replace(/^#/, ''));
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(
+      `--amends expects a positive integer Story id; got ${JSON.stringify(raw)}`,
+    );
+  }
+  return id;
+}
+
 /**
  * Build the envelope and write it to `stdout` as a single JSON line
  * (or pretty-printed with --pretty). Exported for tests.
@@ -96,6 +121,7 @@ export async function emitPlanContext({
   seedFileContent,
   seedText,
   ticketIds,
+  amendsId,
   provider,
   config,
   settings,
@@ -110,6 +136,7 @@ export async function emitPlanContext({
     seedFileContent,
     seedText,
     ticketIds,
+    amendsId,
     provider,
     config,
     settings,
@@ -139,14 +166,19 @@ export async function emitPlanContext({
       duplicates: (envelope.duplicates ?? []).length,
       // Advisory only (Story #4722): signals, no route — the planner owns
       // the trivial-vs-standard verdict and persist validates it by shape.
+      // The nested `deliverLightSuggestion` is the recorded plan-side routing
+      // handshake (Story #4741 AC-6) — advisory, never an automatic reroute.
       complexitySignals: envelope.complexitySignals
         ? {
             artifactCount: envelope.complexitySignals.artifactCount,
             riskHeuristicHits: envelope.complexitySignals.riskHeuristicHits,
             sensitivePathClasses:
               envelope.complexitySignals.sensitivePathClasses,
+            deliverLightSuggestion:
+              envelope.complexitySignals.deliverLightSuggestion ?? null,
           }
         : null,
+      amends: envelope.amends ? { id: envelope.amends.id } : null,
     };
     stdout.write(`${JSON.stringify(digest)}\n`);
   } else {
@@ -221,6 +253,7 @@ async function main() {
       seed: { type: 'string' },
       'seed-file': { type: 'string' },
       tickets: { type: 'string' },
+      amends: { type: 'string' },
       out: { type: 'string' },
       pretty: { type: 'boolean', default: false },
     },
@@ -234,16 +267,24 @@ async function main() {
     typeof seedFilePath === 'string' && seedFilePath.length > 0;
   const hasTickets =
     typeof values.tickets === 'string' && values.tickets.trim().length > 0;
-  const entryForms = [hasSeed, hasSeedFile, hasTickets].filter(Boolean).length;
+  const hasAmends =
+    typeof values.amends === 'string' && values.amends.trim().length > 0;
+  const entryForms = [hasSeed, hasSeedFile, hasTickets, hasAmends].filter(
+    Boolean,
+  ).length;
   if (entryForms !== 1) {
     throw new Error(
-      'Pass exactly one of --seed "<text>", --seed-file <path>, or --tickets <ids>.',
+      'Pass exactly one of --seed "<text>", --seed-file <path>, --tickets <ids>, or --amends <id>.',
     );
   }
 
   let mode;
   let ticketIds;
-  if (hasTickets) {
+  let amendsId;
+  if (hasAmends) {
+    mode = 'amends';
+    amendsId = parseAmendsId(values.amends);
+  } else if (hasTickets) {
     mode = 'tickets';
     ticketIds = parseTicketIds(values.tickets);
   } else if (hasSeedFile) {
@@ -288,6 +329,7 @@ async function main() {
         seedFilePath: hasSeedFile ? seedFilePath : undefined,
         seedText: hasSeed ? seedText : undefined,
         ticketIds,
+        amendsId,
         provider,
         config,
         settings,

package/.agents/scripts/plan-persist.js

@@ -44,6 +44,15 @@
  *   --no-close-superseded     Keep the source tickets open (no comment, no
  *                             close) — for a genuinely partial supersede
  *   --dry-run                 Assemble + validate without GitHub writes
+ *   --chain-on-clean          Plan-diet fast path (Story #4741): run the
+ *                             write-free dry-run first, and — only when it
+ *                             passes clean AND the plan resolves to the `lite`
+ *                             route — chain straight into the real persist in
+ *                             the SAME invocation, collapsing the two operator
+ *                             round-trips into one. A dry-run failure stops
+ *                             before any createIssue; a full-route plan keeps
+ *                             its review round-trip (the chain declines, no
+ *                             writes). Ignored when `--dry-run` is also set
  *   --force-review            Operator-forced review stop before persist lands
  *   --allow-over-budget / --allow-large-fan-out
  *
@@ -111,6 +120,7 @@ const CLI_OPTIONS = {
   'close-superseded': { type: 'boolean', default: true },
   'no-close-superseded': { type: 'boolean', default: false },
   'dry-run': { type: 'boolean', default: false },
+  'chain-on-clean': { type: 'boolean', default: false },
   'force-review': { type: 'boolean', default: false },
   'allow-over-budget': { type: 'boolean', default: false },
   'allow-large-fan-out': { type: 'boolean', default: false },
@@ -122,7 +132,7 @@ const USAGE =
   '[--plan-acceptance <file>] ' +
   '[--source-tickets <ids>] [--no-close-superseded] ' +
   '[--route-downgrade-reason <text>] ' +
-  '[--dry-run] [--force-review] ' +
+  '[--dry-run] [--chain-on-clean] [--force-review] ' +
   '[--allow-over-budget] [--allow-large-fan-out]';
 
 async function readOptional(filePath, { required }) {
@@ -229,8 +239,11 @@ async function runPersistInvocation({
   provider,
   artifacts,
   metricsSince,
+  dryRun,
 }) {
   const paths = resolveInputPaths(values);
+  const effectiveDryRun =
+    typeof dryRun === 'boolean' ? dryRun : values['dry-run'] === true;
   const settings = {
     baseBranch: config.project?.baseBranch,
     paths: config.project?.paths,
@@ -241,7 +254,7 @@ async function runPersistInvocation({
   return recordPlanInvocation(
     {
       cli: 'plan-persist',
-      mode: values['dry-run'] ? 'dry-run' : 'persist',
+      mode: effectiveDryRun ? 'dry-run' : 'persist',
       config,
     },
     () =>
@@ -252,12 +265,83 @@ async function runPersistInvocation({
         settings,
         opts: {
           ...buildPersistOptions(values, paths, artifacts.planContextEnvelope),
+          dryRun: effectiveDryRun,
+          skipCleanup: effectiveDryRun,
           metricsSince,
         },
       }),
   );
 }
 
+/**
+ * Plan-diet fast path (Story #4741 AC-1/AC-3): chain the lite dry-run into the
+ * real persist in ONE operator invocation.
+ *
+ * Two passes over the **same** loaded artifacts:
+ *
+ *   1. A write-free dry-run. Every gate runs before any `createIssue` can
+ *      happen, so a validation failure — which throws or returns reachability
+ *      orphans — stops here, before a single issue exists (AC-3).
+ *   2. The real write, run **only** when the dry-run passed clean AND resolved
+ *      to the `lite` route. Because it replays the identical artifacts, the
+ *      persisted output is byte-identical to what the dry-run validated
+ *      (AC-1). A full-route plan keeps its review round-trip: the chain
+ *      declines and returns the dry-run result, mutating nothing.
+ *
+ * Exported for tests — this is where the round-trip collapse and its
+ * fail-closed guard live, so a regression here silently re-opens the second
+ * operator round-trip (or worse, persists a plan the dry-run never gated).
+ *
+ * @param {{ values: object, config: object, provider: object,
+ *   artifacts: object, metricsSince: string }} args
+ * @returns {Promise<object>} the persist result, plus a `chain` receipt.
+ */
+export async function runPersistChain({
+  values,
+  config,
+  provider,
+  artifacts,
+  metricsSince,
+}) {
+  const dryResult = await runPersistInvocation({
+    values,
+    config,
+    provider,
+    artifacts,
+    metricsSince,
+    dryRun: true,
+  });
+
+  if (dryResult.route?.route !== 'lite') {
+    dryResult.chain = {
+      attempted: true,
+      persisted: false,
+      reason: 'route-not-lite',
+    };
+    Logger.info(
+      '[plan-persist] --chain-on-clean: dry-run clean but the plan did not ' +
+        'resolve to the lite route — declining the auto-persist; run persist ' +
+        'explicitly after review.',
+    );
+    return dryResult;
+  }
+
+  const persistResult = await runPersistInvocation({
+    values,
+    config,
+    provider,
+    artifacts,
+    metricsSince,
+    dryRun: false,
+  });
+  persistResult.chain = {
+    attempted: true,
+    persisted: true,
+    reason: 'lite-dry-run-clean',
+  };
+  return persistResult;
+}
+
 /**
  * Attach the plan-metrics roll-up for **this** invocation.
  *
@@ -318,15 +402,28 @@ async function main() {
   const paths = resolveInputPaths(values);
   const artifacts = await loadArtifacts(paths);
 
+  // `--chain-on-clean` collapses the dry-run + persist operator round-trips
+  // (Story #4741). `--dry-run` always wins — an explicit dry-run never writes.
+  const useChain =
+    values['chain-on-clean'] === true && values['dry-run'] !== true;
+
   let result;
   try {
-    result = await runPersistInvocation({
-      values,
-      config,
-      provider,
-      artifacts,
-      metricsSince,
-    });
+    result = useChain
+      ? await runPersistChain({
+          values,
+          config,
+          provider,
+          artifacts,
+          metricsSince,
+        })
+      : await runPersistInvocation({
+          values,
+          config,
+          provider,
+          artifacts,
+          metricsSince,
+        });
   } catch (err) {
     if (err?.code === 'PLAN_REACHABILITY_ORPHANS') {
       process.stdout.write(`${err.message}\n`);

package/.agents/workflows/deliver-light.md

@@ -0,0 +1,117 @@
+---
+description:
+  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.
+---
+
+# /deliver-light "<prompt>" | --amends '#<id>' "<prompt>"
+
+> **Thin entry point, not a second engine.** `/deliver-light` removes the
+> `/plan` session for small work — nothing else. It runs a suitability gate,
+> authors a minimal receipt Story, then hands off to the SAME scripts
+> [`/deliver`](deliver.md) uses. Read
+> [`helpers/deliver-digest.md`](helpers/deliver-digest.md) once first — the
+> engine invariants, gates, and terminal-envelope contract below are its.
+
+## Role
+
+For a genuinely trivial change — a one-file fix, a small addition, a small
+amendment — the multi-session plan→deliver ceremony buys nothing the bare model
+lacks except **gates and landing**. `/deliver-light` keeps exactly those: one
+session straight to execution from an operator prompt, landing through the
+unchanged close path. It never relaxes a close gate, never bypasses the PR to
+`main`, and never lands over-scope work silently.
+
+## Four invariants (do not skip one)
+
+1. **Suitability gate.** The prompt's predicted footprint is judged by the
+   shared shape machinery (`deriveStoryShape` / `deriveChangeLevel`) **and** a
+   ledgered model verdict with a recorded reason. Both must agree on `lite`.
+2. **Over-scope stops — it never hard-fails.** An over-ceiling prompt STOPS and
+   asks the operator to escalate to `/plan` or proceed light. Under `--yes` it
+   fails closed to recommending `/plan`.
+3. **Diff-derived backstop.** After implementation the ACTUAL change set is
+   re-checked — the diff is the real scope signal — and an over-ceiling diff is
+   blocked rather than landed.
+4. **Minimal receipt Story.** A `type::story` is authored inline so `refs #`,
+   history, telemetry, and the `agent::executing → agent::done` state machine
+   all survive.
+
+## Procedure
+
+1. **Predict + gate.** Form the predicted footprint (new files, edited files,
+   acceptance count) and your ledgered verdict (a recorded reason for `lite`),
+   then run the gate:
+
+   ```bash
+   node .agents/scripts/deliver-light.js --prompt "<prompt>" \
+     --creates <csv> --refactors <csv> --acceptance <n> \
+     --route lite --reason "<why this is trivial>" [--amends '#<id>'] [--yes]
+   ```
+
+   Branch on `action` in the JSON envelope:
+   - **`proceed-light`** — the receipt Story is authored; read `storyId` and
+     `nextCommands`. Continue to step 2.
+   - **`ask-operator`** — predicted scope exceeds the light ceilings. STOP and
+     ask the operator to escalate to `/plan` or proceed light. Do not proceed
+     on your own.
+   - **`escalate-plan`** — over-scope under `--yes`: recommend `/plan` and stop.
+     `/deliver-light` never lands over-scope work.
+
+   `--amends '#<id>'` is the canonical light case — shape-checked identically; a
+   heavy amendment escalates to `/plan` like any other over-scope prompt.
+
+2. **Init (same engine).** From the main checkout, synchronously, with the
+   maximum Bash timeout:
+
+   ```bash
+   node .agents/scripts/single-story-init.js --story <storyId>
+   ```
+
+   Capture `workCwd`; `remoteVerified: false` → flip `agent::blocked` and stop.
+   This is [`/deliver`](deliver.md)'s worktree/branch/lease/label engine,
+   invoked, not reimplemented.
+
+3. **Implement + self-eval.** `cd` into `workCwd`, implement the change, run
+   `npm test` once in the worktree, then run the bounded acceptance self-eval
+   loop ([`helpers/deliver-story.md`](helpers/deliver-story.md) Step 1a). Commit
+   on `story-<id>` with `(refs #<storyId>)`.
+
+4. **Diff backstop.** Before close, re-check the ACTUAL diff:
+
+   ```bash
+   node .agents/scripts/deliver-light.js --backstop --story <storyId>
+   ```
+
+   Exit `3` (`blocked: true`) means the landed diff exceeds the light ceilings
+   (file count or a sensitive-path class). STOP, flip `agent::blocked`, and
+   escalate to `/plan` — do not land.
+
+5. **Close and land (same engine).** Exactly [`/deliver`](deliver.md)'s close:
+
+   ```bash
+   node .agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo>
+   ```
+
+   Branch on the terminal envelope's `status` per
+   [`helpers/deliver-digest.md`](helpers/deliver-digest.md) § 5 — every close
+   gate runs byte-identical to the full path.
+
+## Constraints
+
+- **Land or block — never a silent local build.** The close push is the only
+  sanctioned landing.
+- **No parallel engine.** `/deliver-light` invokes `single-story-init.js` and
+  `single-story-close.js`; it never reimplements worktree, branch, PR, or merge
+  mechanics.
+- **State only via `update-ticket-state.js`.** Drive every `agent::*`
+  transition through the script; report state, not process.
+
+## See also
+
+- [`/deliver`](deliver.md) — the multi-Story / planned delivery entry point.
+- [`helpers/deliver-story.md`](helpers/deliver-story.md) — the one Story
+  delivery engine both entry points share.
+- [`helpers/deliver-digest.md`](helpers/deliver-digest.md) — engine invariants,
+  gates, and the terminal-envelope contract.

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).