mandrel 2.23.0 → 2.25.0

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

@@ -27,7 +27,7 @@ caller: helpers/deliver-story.md
 
 Before any git mutation, init takes an exclusive, time-bounded **lease** on
 the Story ticket via the assignee-as-lease primitive
-(`lib/orchestration/ticket-lease.js`). The single assignee *is* the lease
+(`lib/orchestration/ticket-lease.js`). The single assignee _is_ the lease
 owner (resolved from `github.operatorHandle`). The standalone path has no
 Epic-scoped dispatch manifest to serialise two operators driving the same
 Story, so this lease is the only guard against a concurrent
@@ -38,7 +38,7 @@ has **no Epic-scoped lifecycle ledger** to read a per-owner
 `story.heartbeat` from, so there is no live-heartbeat source to decide
 whether a foreign claim is stale. Rather than silently reclaim every
 foreign assignee (which would leave the guard inert), the standalone lease
-**fails closed**: a foreign assignee is treated as a *live* claim. Outcomes:
+**fails closed**: a foreign assignee is treated as a _live_ claim. Outcomes:
 
 - **Unclaimed / self-held** → init proceeds (a self-held claim is
   re-affirmed without re-writing assignees).
@@ -80,9 +80,9 @@ The sweep applies two hardening layers:
     changes.
   - `ticket-not-done` — the parent Story ticket isn't closed and
     doesn't carry `agent::done`.
-  Protected candidates are skipped, listed in the sweep result envelope
-  under `protected[]`, and named in the `CLEANUP` log line so the
-  operator can see what was preserved.
+    Protected candidates are skipped, listed in the sweep result envelope
+    under `protected[]`, and named in the `CLEANUP` log line so the
+    operator can see what was preserved.
 - **Cross-session lock.** The sweep acquires a process-scoped lockfile
   at `<tempRoot>/single-story-sweep.lock` before planning. On
   contention (another `/deliver-story` already in the sweep
@@ -114,18 +114,24 @@ not a substitute for prefixing paths correctly.
 
 ## Engine invariants and the lite route
 
+**Prerequisites before Step 0.** A `type::story` issue, a clean
+`gh auth status`, and `project.baseBranch` present both locally and on
+`origin` — init seeds the Story branch from the base branch and probes the
+remote, so a missing or unauthenticated remote surfaces as a
+`remoteVerified: false` block rather than a useful error.
+
 The v2 engine's trait table:
 
-| Trait | v2 `/deliver-story` |
-| --- | --- |
-| Ticket type | `type::story` only |
-| Branch | `story-<id>` seeded from `project.baseBranch` (`main`) |
-| Merge target | `main` via PR (squash + required checks) |
-| Spec / slices | Folded `## Spec` + optional `## Slicing` checkpoints in-session |
-| Ceremony | Per-Story, routed off the derived change level via `ceremony-routing.js` |
+| Trait         | v2 `/deliver-story`                                                      |
+| ------------- | ------------------------------------------------------------------------ |
+| Ticket type   | `type::story` only                                                       |
+| Branch        | `story-<id>` seeded from `project.baseBranch` (`main`)                   |
+| Merge target  | `main` via PR (squash + required checks)                                 |
+| Spec / slices | Folded `## Spec` + optional `## Slicing` checkpoints in-session          |
+| Ceremony      | Per-Story, routed off the derived change level via `ceremony-routing.js` |
 
 **Ceremony-lite Stories still land through this engine unchanged.** A
-lite-routed Story collapses only the *advisory* plan/deliver
+lite-routed Story collapses only the _advisory_ plan/deliver
 ceremony — the fresh-critic / Tech-Spec authoring a one-artifact scope does
 not earn. It does **not** get a cheaper landing: the close-validation gates
 (lint / test / format / coverage / CRAP / maintainability), the PR to `main`,
@@ -135,7 +141,7 @@ record of those non-negotiables; there is no lite-specific gate bypass.
 
 **Deliver derives the route from the Story body's shape — and the
 dispatch mode from the run.** Persist stamps a lite cohort's Stories with the
-`route::lite` label as a *human-visible hint only* (and ledgers the authored
+`route::lite` label as a _human-visible hint only_ (and ledgers the authored
 verdict — recorded reason plus per-Story shape evidence — on the
 `story-plan-state` checkpoint); the label is never the control signal.
 `/deliver` computes the route from the fetched Story body via
@@ -261,6 +267,31 @@ removed. Hard gates are untouched.
 
 ## Step 3 — Merge wait, async mode, and flags
 
+**Step 3 is the orchestrator's, and it is serialized.** A dispatched
+`story-worker` ends its turn at a pushed branch (spine § Step 2.5); the session
+that dispatched it runs close. Two reasons, both measured rather than
+theoretical:
+
+1. **A sub-agent cannot resume itself.** It gets no notification when a
+   backgrounded close finishes, so a worker that backgrounds close and ends its
+   turn strands the envelope in a turn nobody reads — three of five workers in
+   one measured wave did exactly that despite an explicit foreground-close
+   instruction. Moving the seam removes the failure instead of re-wording the
+   prohibition. The parent, by contrast, is still live and _does_ observe and
+   retry its own close.
+2. **Closes contend; implementation does not.** Close syncs from
+   `origin/<baseBranch>`, pushes, opens a PR and arms auto-merge — two of those
+   in flight race on the base branch, the merge queue and the shared checkout.
+   So implementation may fan out across the wave, but the tail runs **one Story
+   at a time**: a worker that hands back while another close is running waits in
+   the orchestrator's queue.
+
+A worker therefore returns a hand-off report, not a terminal envelope, and that
+is the expected shape — only close mints an envelope. Never answer a missing
+envelope with a re-dispatch: `single-story-init.js` re-run under a live branch
+is how one Story ends up with two closes. Close the pushed branch, or probe with
+`deliver-recover.js` and run the one command it prints.
+
 **What close does internally.** The script runs the close-validation gates
 against `baseBranch`, syncs the Story branch from `origin/<baseBranch>`
 (the parallel-race defence), pushes `story-<id>`, opens (or
@@ -280,7 +311,7 @@ separate (`delivery.mergeWatch.*`):
   it when your host has no such ceiling and you want to land in one block.
 - **`maxBudgetSeconds`** (default 3600) bounds the **cumulative** wait across
   resumes, anchored at the PR's `createdAt` so resuming does not restart the
-  clock. Exhausting *this* is the genuine give-up → `blocked`.
+  clock. Exhausting _this_ is the genuine give-up → `blocked`.
 
 The wait probes the checks every poll: a red required check fails fast as
 `checks-failed` instead of burning the budget, and a PR that falls behind its
@@ -312,7 +343,7 @@ checks pass. Under `"strict"`, the close **does not arm auto-merge** — the
 PR opens and waits for an **operator merge**, exactly as `--no-auto-merge`
 does per-run.
 
-**When to reach for a close flag.** What each one *does* is in
+**When to reach for a close flag.** What each one _does_ is in
 `node .agents/scripts/single-story-close.js --help`; below is only the
 judgment that help text cannot carry.
 
@@ -346,7 +377,7 @@ The `single-story-close.js` script, in order:
    captured tail inline so the evidence is in front of you without opening a
    file. Read the artifact when you need the full text — or re-run under
    `AGENT_LOG_LEVEL=verbose` for live streaming.
-1a. **Syncs the Story branch from `origin/<baseBranch>`** before push.
+   1a. **Syncs the Story branch from `origin/<baseBranch>`** before push.
    Runs `git fetch origin <baseBranch>` followed by
    `git merge --no-edit origin/<baseBranch>` inside the worktree. This
    defends against the parallel-`/deliver-story` race: when
@@ -370,12 +401,13 @@ The `single-story-close.js` script, in order:
    defence against the parallel race. Without merge queue, the sync
    closes the PR-open-time race but a residual race remains between PR
    open and auto-merge fire.
+
 2. Pushes `story-<id>` to `origin`.
 3. Probes for an existing open PR with `head = story-<id>`. If none
    exists, opens one via `gh pr create --base <baseBranch>`. The PR
    body carries `Closes #<storyId>` so the GitHub merge auto-closes the
    issue.
-3a. **Enables GitHub native auto-merge by default** via
+   3a. **Enables GitHub native auto-merge by default** via
    `gh pr merge <prNumber> --auto --squash --delete-branch`. Once CI's
    required checks turn green, GitHub squash-merges the PR and deletes
    the source branch — the operator does not need to babysit the merge
@@ -385,7 +417,7 @@ The `single-story-close.js` script, in order:
    pre-merge eyeball.
 4. Flips the Story to **`agent::closing`** (NOT `agent::done`) and leaves
    the GitHub issue **OPEN**. Auto-merge completes
-   asynchronously *after* this script exits, so closing the issue here
+   asynchronously _after_ this script exits, so closing the issue here
    would strand a CLOSED issue with no merged work if the PR later failed
    CI, went `BEHIND` base, or was closed without merging. The Story rests
    at `agent::closing` while the PR is open with auto-merge armed; the
@@ -430,9 +462,10 @@ close-validation gates pass on the dev host's environment; CI runs on a
 different OS and concurrency, and coverage rounding, platform-conditional
 branches, and timing-sensitive tests routinely drift between the two.
 
-Fix the failure and push a new commit on `story-<storyId>` — auto-merge stays
-armed across retries, so you do not re-arm — then resume the land with the
-envelope's `nextCommand`.
+Fix the failure and push a new commit on `story-<storyId>` — the watcher
+**disarmed native auto-merge on the first red** and re-arms it
+only when the checks go green on a **new head SHA**, so the fix must be a real
+commit — then resume the land with the envelope's `nextCommand`.
 
 To watch the checks on the red path, drive `pr-watch-with-update.js` — the
 **single CI-watch mechanism**. It polls the required checks to a
@@ -444,29 +477,54 @@ node <agentRoot>/scripts/pr-watch-with-update.js --pr <prNumber> --story <storyI
 ```
 
 `--story` is what keys the red-path CI digest
-(`temp/story-<id>-ci-digest.{json,md}` — failing check name, run id, and a
-`gh run view --log-failed` tail). Omit it and a red check writes no digest.
+(`temp/story-<id>-ci-digest.{json,md}` — failing check name, the PR head SHA,
+run id + run link, and a `gh run view --log-failed` tail). Omit it and a red
+check writes no digest — and with no digest the no-rerun guard has nothing to
+adjudicate the next green against, so always pass it.
 Poll cadence and caps come from `delivery.ci.watch.*` (`pollIntervalMs`,
-`maxPolls`, `maxResumes`); pass `--poll-interval-ms`, `--max-polls`, or
-`--max-resumes` to override for one run.
+`maxPolls`, `maxResumes`, `attachWindowMs`); pass `--poll-interval-ms`,
+`--max-polls`, `--max-resumes`, or `--attach-window-ms` to override for one run.
+`attachWindowMs` (default 20 min) is how long the watch keeps re-resolving an
+**empty** required-check set before it stops waiting for a context to attach —
+a required context that is an aggregator job gated on every other tier is the
+last check to appear, measured at 16m52s on this repository.
+
+Add `--repo owner/repo` only when the cwd is not the target repository; it
+reaches `gh` as a real flag. There is no `<owner/repo>#<number>` ref form —
+`gh` parses that as a branch name.
 
 When the watch exits, branch on the exit code:
 
 - **Exit 0 (all checks ✓)** — auto-merge will fire (or has already). The Story
   is still at `agent::closing` with its issue OPEN. **Proceed to merge
-  confirmation (§ Step 5) within the same turn** — green CI is the *start* of
+  confirmation (§ Step 5) within the same turn** — green CI is the _start_ of
   the merge-confirm sequence, not a terminal state.
-- **Exit 1 (a check genuinely failed)** — diagnose, fix, and push a new commit
-  on `story-<storyId>`, then re-watch. Auto-merge stays enabled across retries;
-  no need to re-arm it. The Story stays at `agent::closing` throughout, so a
-  failed/abandoned PR never strands a CLOSED issue. If the same failure class
-  recurs, hand convergence off to a self-paced host loop (`/loop`) that re-runs
-  the failing check and applies the smallest fix until it exits green.
-- **Exit 2 (still-running — slow CI, not red)** — the poll cap fired with checks
-  still pending and the watcher exhausted its resume budget with nothing red.
-  This is **never** a failure. Hand the wait off to the host's interval loop
+- **Exit 1 (a check genuinely failed, the green was a forbidden re-run, or the
+  PR itself could not be read)** —
+  diagnose, fix at source, and push a new commit on `story-<storyId>`, then
+  re-watch: the watcher disarmed auto-merge on the red and re-arms it only for
+  a green on a **new head SHA**. The Story stays at `agent::closing`
+  throughout, so a failed/abandoned PR never strands a CLOSED issue. If the
+  same failure class recurs, hand convergence off to a self-paced host loop
+  (`/loop`) that applies the smallest fix and pushes a new commit each pass —
+  **never** a bare re-run of the failed job. A green the guard rejects as a
+  re-run of the same commit flips the Story to `agent::blocked` with a
+  `friction` comment; clear it per
+  [`ci-remediation.md`](../../rules/ci-remediation.md) § Verifier.
+- **Exit 2 (slow, not red)** — one of three slow conditions, **never** a
+  failure and never a green. Hand the wait off to the host's interval loop
   rather than ending your turn: `/loop 5m` polling `gh pr checks` until the
-  checks settle.
+  checks settle. The envelope names which:
+  - **still-running** — the poll cap fired with checks still pending and the
+    watcher exhausted its resume budget with nothing red.
+  - **not-yet-started** (`notYetStarted: true`) — the attach window was spent
+    and **no** required context ever attached, while the PR kept reading back
+    fine. CI has not started; there is no failing check and no CI digest to
+    read. Do **not** treat it as red — nothing needs fixing, and re-watching
+    (or raising `attachWindowMs`) is the whole remediation.
+  - **unresolved** (`reconciliation.reconciled: false`) — every observed
+    required check is green but the repository still refuses the merge, so the
+    green verdict is withheld.
 
 **Triage authority.** How to classify and remediate a red (or repeatedly slow)
 check — the root-cause-only decision tree for infra/transient and flaky failures
@@ -485,7 +543,7 @@ then ends its turn with **free-form prose** — e.g. "I'll wait for the
 background watch task to complete" or "the next event will be its completion
 notification" — leaving the merge unconfirmed and the Story stranded at
 `agent::closing`. **Do not do this.**
-`pr-watch-with-update.js --pr <prNumber>` *blocks the current turn* until CI
+`pr-watch-with-update.js --pr <prNumber>` _blocks the current turn_ until CI
 resolves — that is the mechanism by which you wait. You MUST keep your turn alive
 across the wait: watch → (fix + push + re-watch on red) → confirm the merge
 (Step 5) → flip `agent::done` → run the post-merge steps → and only then
@@ -551,12 +609,13 @@ the watch exits clean.
   `agent::blocked`, summarize the blocker on the PR, and yield to the
   operator.
 
-### Idempotence of the loop
+### Idempotence of the loop {#idempotence}
 
 - The PR stays open across retries; `gh pr create` is a one-shot at
   close, the loop only pushes new commits.
-- Auto-merge stays armed across retries — pushing a new commit does
-  not disarm `gh pr merge --auto`.
+- Auto-merge is disarmed by the watcher on the first red and re-armed
+  when the checks go green on a new head SHA; pushing a new commit is
+  what re-opens the merge path.
 - If the operator manually merges or disables auto-merge mid-loop,
   exit the loop and report.
 
@@ -612,7 +671,7 @@ no-op-safe (`no-project` / `not-on-project` exit 0).
 
 The GitHub Projects v2 built-in workflows `Pull request merged` and
 `Pull request linked to issue` are enabled by default on most boards
-and fire ~minutes *after* auto-merge lands. They overwrite the Status
+and fire ~minutes _after_ auto-merge lands. They overwrite the Status
 field as a side-effect, clobbering the `Done` value
 `single-story-confirm-merge.js` set at the `agent::done` flip in Step 5
 and leaving closed Stories stuck at `In Progress` on the board. The
@@ -680,7 +739,7 @@ GitHub deletes the **remote** branch on auto-merge (via the
 `--delete-branch` flag `single-story-close.js` passes to `gh pr merge`).
 The **local** `story-<storyId>` ref, however, lingers in the main
 checkout until something prunes it — `single-story-init.js` runs a
-merged-sweep at the start of every *subsequent* `/deliver-story`
+merged-sweep at the start of every _subsequent_ `/deliver-story`
 invocation, but that's next-run cleanup, not end-of-run cleanup. Stale
 local refs accumulate between sessions, clutter `git branch`, and shadow
 the lessons the sweep is meant to surface.
@@ -717,6 +776,27 @@ up").
 
 ---
 
+## Idempotence and the standing constraints
+
+Every script in the chain no-ops safely on re-run: `single-story-init.js`
+re-prints `workCwd` for an already-initialized Story; `single-story-close.js`
+and `single-story-confirm-merge.js` short-circuit on a closed or `agent::done`
+Story; the PR probe reuses an open PR rather than opening a second one. That is
+what makes the recovery router safe to walk more than once.
+
+The four constraints the spine states without arguing for them:
+
+- **Never push the Story branch directly to `main`.** The PR is the only merge
+  surface — a direct push bypasses required checks and the squash title
+  release-please parses.
+- **Always prefix path-based tools with the absolute `workCwd` root.** `cd`
+  scopes Bash, not Edit/Write/Read; close's wrong-tree guard is a backstop for
+  the mistake, not a licence to make it.
+- **Report state, not process.** Mirror the close envelope's fields; step
+  narration reads as progress while telling the caller nothing it can branch on.
+- **Drive every `agent::*` transition through `update-ticket-state.js`** so the
+  label, the Projects Status column and the lifecycle event stay in one motion.
+
 ## Step 7 — Return-contract detail
 
 The field-level contract is the shipped schema
@@ -724,7 +804,7 @@ The field-level contract is the shipped schema
 — not this file, and not
 [`agents/story-worker.md`](../../agents/story-worker.md). All three used to
 carry their own prose version; the schema is now the only definition. What
-follows is the *judgement* around it, which a schema cannot express.
+follows is the _judgement_ around it, which a schema cannot express.
 
 ### `pending` is a real status — and it is not a park
 
@@ -767,8 +847,9 @@ persists the validated envelope to
 - **It is best-effort.** A failed write returns null and changes nothing about
   the emitted envelope or the exit code — a landed PR must never become a
   crash because a temp directory was unwritable.
-- **It is a fallback, not a licence.** A worker still holds its turn until the
-  envelope arrives; see [`agents/story-worker.md`](../../agents/story-worker.md).
+- **It is a fallback, not a licence.** The orchestrator running close still
+  holds its turn until the envelope arrives; see § Step 3 above and
+  [`agents/story-worker.md`](../../agents/story-worker.md).
 
 `deliver-recover.js` reads the same artifact, plus the freshness of
 `close-gates-<storyId>.log`, to split the one genuinely ambiguous row of its

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

@@ -1,179 +1,164 @@
 ---
 description:
-  Execute one Story end-to-end. Creates story-<id> from main, implements in a
-  worktree (optional ## Slicing checkpoints), runs derived-level ceremony,
-  opens a PR against main, and lands.
+  Execute one Story end-to-end: story-<id> from main, implemented in a worktree
+  (optional ## Slicing checkpoints), derived-level ceremony, PR against main.
 mandatoryReads: [deliver-digest.md]
 ---
 
 # /deliver-story #[Story ID]
 
-> **Lean spine.** Happy path + gate list; edge-case, recovery, and
-> reference detail lives in
-> [`deliver-story-reference.md`](deliver-story-reference.md) ("reference"
-> below); consult on demand. Invoked by [`/deliver`](../deliver.md).
->
-> **Read [`deliver-digest.md`](deliver-digest.md) once, first.** It is the
-> one bundled read of what every delivery needs — dispatch decision, engine
-> invariants, the change-set/ceremony incantation, the acceptance-eval gate,
-> and the terminal-envelope contract — replacing the per-session re-reads of
-> the helper set and `story-deliver-terminal.schema.json`. The steps below
-> cite it as "digest § N" rather than restating it.
+> **Lean spine.** Happy path + gate list; edge-case, recovery and reference
+> detail lives in [`deliver-story-reference.md`](deliver-story-reference.md)
+> ("reference" below). Invoked by [`/deliver`](../deliver.md).
+> **Read [`deliver-digest.md`](deliver-digest.md) once, first** — the one
+> bundled read every delivery needs. Steps cite it as "digest § N".
 
 ## Overview
 
-The **one** delivery engine in v2 — every Story (a **one-Story** run
-goes inline with inline critics; engine, gates, envelope byte-identical):
+The **one** delivery engine in v2:
 
 ```text
-single-story-init.js → implement + commits → derived-level ceremony
-  → single-story-close.js (gates, push, PR → main, agent::closing)
+single-story-init.js → implement + commits → derived-level ceremony → push
+  ──hand-off──▶ single-story-close.js (gates, PR → main, agent::closing)
   → CI watch + merge → single-story-confirm-merge.js (agent::done)
 ```
 
-An `Epic: #N` reference marks a v1 ticket — **stop** and re-plan. The
-engine's trait table is reference § Engine invariants. Prerequisites: a
-`type::story` issue, clean `gh auth status`, and `project.baseBranch` on
-local and `origin`.
+An `Epic: #N` reference marks a v1 ticket — **stop** and re-plan. Engine
+traits and prerequisites: reference § Engine invariants.
+
+## Who owns which step
+
+Steps 0–2 belong to whoever implements. **Step 3 belongs to the orchestrator
+that dispatched the work**, never to a spawned worker.
+
+- **Inline dispatch** (a one-Story run — digest § 1): one session is both
+  roles and walks Steps 0→7, no hand-off.
+- **Sub-agent dispatch**: the `story-worker` stops at Step 2.5 with the branch
+  pushed and returns a hand-off; the dispatching `/deliver` session runs Step 3
+  **in its own turn** and **serializes the tail — one close at a time across
+  the run**, even though implementation ran in parallel (reference § Step 3).
+
+**A worker returning no terminal envelope is expected, not a failure.** Only
+Step 3 mints one, so a hand-off is the normal sub-agent return. Never
+re-dispatch the Story on it — the branch exists, and re-running Step 0 under
+live work is how one Story gets two closes. Resume per § Recovery instead.
 
 ## Step 0 — Initialize (`single-story-init.js`)
 
-From the **main checkout**, **synchronously** with the maximum Bash
-timeout — the per-tree install can take minutes; never `run_in_background`:
+From the **main checkout**, **synchronously** with the maximum Bash timeout —
+the per-tree install can take minutes; never `run_in_background`:
 
 ```bash
 node .agents/scripts/single-story-init.js --story <storyId>
 ```
 
 Every script below documents its own flags — run it with `--help`.
-It validates `type::story`, **acquires the Story lease**
-(fails closed on a foreign assignee), fetches `origin`, seeds `story-<id>`
-from `baseBranch` (idempotent reuse), materializes a worktree, runs a
-guarded merged-`story-*` sweep, and flips `agent::executing` (reference
-§ Step 0). Capture `workCwd` from the result envelope.
+It validates `type::story`, takes the Story lease, seeds `story-<id>` from
+`baseBranch`, materializes a worktree and flips `agent::executing` (reference
+§ Step 0). Capture `workCwd` from the envelope.
 
-**Land or block.** `remoteVerified: false` → flip
-`agent::blocked` quoting `remoteProbe.detail` and stop. Implementing outside
-the worktree/branch/PR path or committing to local `main` is forbidden —
-close's push is the only sanctioned landing.
+**Land or block.** `remoteVerified: false` → flip `agent::blocked` quoting
+`remoteProbe.detail` and stop. Implementing outside the worktree/branch/PR path,
+or committing to local `main`, is forbidden.
 
 **Step 0.5 — `cd "<workCwd>"`**, and prefix every path-based
-Edit/Write/Read with that absolute root — the `cd` alone does not scope
-those tools (reference § Worktree scope is not just the Bash cwd).
+Edit/Write/Read with that absolute worktree root — the `cd` alone does not
+scope those tools (reference § Worktree scope).
 
 ## Step 1 — Implementation
 
 One branch, one PR to `main`, commits against the inline `acceptance[]` /
-`verify[]` (and `## Spec`):
-
-1. Read the Story body; the acceptance criteria are the contract. Docs are
-   digest-first; read a caller-provided `checklistPath` before writing
-   (reference § Step 1).
-2. Implement. Walk any `## Slicing` rows as **intra-session checkpoints**
-   (commit + flip each row) — never sibling tickets.
-3. Commit on the Story branch; iterate with quick advisory gates
-   (`typecheck`, `lint`, scoped tests) — the full close chain runs in
-   Step 3.
-4. Run the **full test command** once in the worktree (`npm test`) **before
-   Step 1a** — repo-invariant guards outside the Story's scoped greps are
-   the failure class that bounces deliveries. Fix and commit first.
-5. Run the self-eval loop (Step 1a).
+`verify[]` and `## Spec`:
+
+1. Read the Story body; its acceptance criteria are the contract. Docs are
+   digest-first; read a caller-provided `checklistPath` first, and walk any
+   `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
+2. Implement and commit on the Story branch, iterating with quick advisory
+   gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3.
+3. Run `npm test` once in the worktree **before Step 1a**: repo-invariant
+   guards outside the Story's scoped greps are the failure class that bounces
+   deliveries. Fix and commit first, then run the self-eval loop.
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 
 Run the loop and score it with `acceptance-eval.js` — **digest § 4** carries
-the invocation and the proceed / redraft / block contract; per-round critic
-mechanics live in the single-homed include
-[`acceptance-self-eval.md`](acceptance-self-eval.md).
-
-**`proceed`** → Step 2 then Step 3. **`block`** → **do not close**: post a
-`friction` comment and flip `agent::blocked` — commands and the
-`evidence-gate.js --standalone` evidence-share mechanic: reference
-§ Step 1a.
+the invocation and the proceed / redraft / block contract; per-round mechanics
+live in [`acceptance-self-eval.md`](acceptance-self-eval.md). **`proceed`** →
+Step 2. **`block`** → **do not close**: post a `friction` comment and flip
+`agent::blocked` (reference § Step 1a).
 
 ## Step 2 — Ceremony (profile + derived level)
 
-Ceremony is `delivery.routing.ceremonyProfile` × the **derived change
-level** — never a planner-authored verdict. **Digest § 3** is the
-incantation: compute the change set once, derive the level, resolve
-fresh-vs-inline critics with `ceremony-routing.js`; a lite Story runs
-inline regardless (routing edge cases: reference § Step 2). Hard gates always
-run in Step 3 — the derived level never disables them; do **not** pre-run the
-close chain here.
+Ceremony is `delivery.routing.ceremonyProfile` × the **derived change level**,
+never a planner-authored verdict. **Digest § 3** is the incantation (change set
+once, derive the level, resolve critics with `ceremony-routing.js`); edge cases
+are reference § Step 2. Hard gates always run in Step 3 — the derived level
+never disables them; do **not** pre-run the chain here.
+
+### Step 2.5 — Push and hand off (sub-agent dispatch only)
+
+Push `story-<storyId>` to `origin` and confirm the remote ref moved. Return the
+hand-off — Story id, `workCwd`, branch, pushed head SHA, self-eval verdict,
+`verify[]` evidence — then stop. Do not open the PR; do not compose a terminal
+envelope. An inline run skips this.
 
 ## Step 3 — Close and land (`single-story-close.js`)
 
+**The orchestrator's step** (§ Who owns which step), run in the **foreground**,
+serialized against sibling Stories:
+
 ```bash
 node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo>
 ```
 
 **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
-post-land tail in one process. Run it and **branch on the terminal envelope's
-`status`** per the table in **digest § 5** (`landed` → Step 7; `pending` → run
-`nextCommand`; `blocked`/`checks-failed` → Step 4; `failed` → diagnose and
-re-run). Gate output is captured to
-`temp/orchestration/close-gates-<storyId>.log` — a clean run prints a digest
-line, a red gate replays its tail inline.
-
-Internals (gate order, base-sync, auto-merge arming), the merge-wait
-budgets, the slow-CI **async** confirm mode (launch the `pending`
-envelope's `nextCommand` as **background** Bash, never a foreground
-poll), the `autoMerge` policy, and every close flag: reference
-§ Step 3 — Merge wait, async mode, and flags.
-
-## Steps 4–6 — Recovery router (**recovery-only**)
-
-A `landed` envelope means everything ran — go straight to Step 7. Enter a
-recovery path **only** when the envelope routes you there:
-
-- **`blocked` / `checks-failed`** → fix, push a new commit (auto-merge stays
-  armed), resume via `nextCommand`; triage per
-  [`rules/ci-remediation.md`](../../rules/ci-remediation.md). The watch is
-  internally blocking — never end a turn with prose and an unconfirmed
-  merge. Reference § Step 4.
-- **`pending`** → run `nextCommand` (`single-story-confirm-merge.js`) until
-  resolved. Reference § Step 5.
-- **`tail.statusResync: false`** → reference § Step 5.5;
-  **`tail.refCleanup` / `tail.baseFastForward: false`** → reference § Step 6.
-
-## Step 7 — Return contract (**required as a sub-agent**) {#return-contract}
-
-End your turn by relaying the validated envelope close emits between its
+post-land tail in one process. Never background it, never delegate it to a
+child, and never end your turn while it is still running: "close is running"
+is not a return value. Branch on the envelope's `status` per **digest § 5**
+(`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
+→ Step 4; `failed` → diagnose, re-run). Gate output is captured.
+
+Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
+`autoMerge` policy and every close flag: reference § Step 3.
+
+## Step 7 — Return contract {#return-contract}
+
+Relay the validated envelope close emits between its
 `--- STORY DELIVER TERMINAL ---` markers — never free-form prose, never a
-hand-composed object. Statuses, exits, and required fields: **digest § 5**
-(whose SSOT is the shipped
-[schema](../../schemas/story-deliver-terminal.schema.json)).
-`pending` is the only sanctioned no-merge ending, returned only when your own
-budget is exhausted. Reference § Step 7.
+hand-composed object. Statuses, exits and fields: **digest § 5** (SSOT: the
+shipped [schema](../../schemas/story-deliver-terminal.schema.json)).
+`pending` is the only sanctioned no-merge ending.
 
-## Recovering a stranded Story {#recover}
+## Steps 4–6 — Recovery (**recovery-only**) {#recover}
+
+A `landed` envelope means everything ran — go to Step 7. Enter recovery **only**
+when the envelope routes you there; procedures are reference §§ Step 4–6.
+Two rules the spine keeps: a red **disarms auto-merge**,
+so only a green on a NEW head SHA re-arms it — a re-run is refused; fix at source
+and push ([`rules/ci-remediation.md`](../../rules/ci-remediation.md)). And a
+`tail.*: false` degrades the report, never the land.
+
+**Watch exit codes** — `pr-watch-with-update.js` exits 0 green, 1 only when a
+required check genuinely failed (or the PR is unreadable), 2 slow-but-not-red:
+still-running, unresolved, **or** `notYetStarted` — no required context attached
+inside `attachWindowMs`. Never route a 2 onto the red path; nothing is broken
+and no digest exists to read.
 
 **Lost envelope first: read it off disk.** Close persists each to
 `temp/orchestration/story-deliver-terminal-<storyId>.json`; branch on it per
-digest § 5. Otherwise (killed run, re-run refusal, merged-but-label-stale)
-do not guess — probe **read-only** with
+digest § 5. Otherwise do not guess — probe **read-only** with
 `node .agents/scripts/deliver-recover.js --story <storyId>`; it prints the
 **one** next command with its evidence, never a menu. A live close answers
 `close-in-flight`: wait, never re-init underneath it.
 
 ## Idempotence & constraints
 
-Every script no-ops safely on re-run (init re-prints `workCwd`; close and
-confirm-merge short-circuit on a closed / `agent::done` Story; the PR probe
-reuses an open PR).
-
-- **Never** push the Story branch directly to `main` — the PR is the only
-  merge surface.
-- **Always** prefix path-based tools with the absolute `workCwd` root
-  (Step 0.5); close's wrong-tree guard is a backstop.
-- **Report state, not process** — mirror the close envelope's fields; no
-  step narration.
-- Drive every `agent::*` transition through
-  `update-ticket-state.js --ticket <id> --state <state>`.
+Every script no-ops safely on re-run (reference § Idempotence). **Never** push
+the Story branch to `main` — the PR is the only merge surface. Report state,
+not process. Drive `agent::*` through
+`update-ticket-state.js --ticket <id> --state <state>`.
 
 ## See also
 
-- [`deliver-digest.md`](deliver-digest.md) — the one bundled framework read.
-- [`/deliver`](../deliver.md) — unified entry point.
-- [`deliver-story-reference.md`](deliver-story-reference.md) — all on-demand
-  detail.
+[`deliver-digest.md`](deliver-digest.md), [`/deliver`](../deliver.md),
+[`deliver-story-reference.md`](deliver-story-reference.md).