mandrel 1.82.0 → 1.83.0

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

@@ -12,6 +12,14 @@ description: >-
 
 # helpers/deliver-epic — Epic delivery path (invoked by /deliver)
 
+> **Runtime core.** This file is the always-ingested Epic-delivery path:
+> phase flow, commands, gate contracts, and return shapes. The recovery
+> procedures, historical rationale, and troubleshooting detail live in the
+> sibling [`deliver-epic-reference.md`](deliver-epic-reference.md); each
+> moved procedure keeps a one-line pointer at its trigger point below. The
+> reference is not projected to `.claude/commands/` — it is consulted on
+> demand.
+
 ## Overview
 
 This helper is the **Epic delivery path** behind `/deliver` — the router
@@ -65,11 +73,10 @@ spawned.
 - `--full-retro` — force the six-section retro regardless of manifest
   cleanliness. `--skip-retro` wins over `--full-retro`.
 - `--skip-integration-gate` — skip Phase 6.5 (log the override). The
-  explicit operator override for the post-wave integration gate, consistent
-  with `--skip-epic-audit`. Use only when the deliberately-global checks are
-  known to be irrelevant for this Epic (e.g., a docs-only Epic that adds no
-  surface). Skipping the gate is recorded as a manual intervention and
-  disqualifies auto-merge, exactly like the other `--skip-*` overrides.
+  explicit operator override for the post-wave integration gate,
+  consistent with `--skip-epic-audit`. Skipping the gate is recorded as a
+  manual intervention and disqualifies auto-merge, exactly like the other
+  `--skip-*` overrides.
 
 Every other runtime modifier is sourced from the Epic's labels or from
 `delivery.deliverRunner` in `.agentrc.json`.
@@ -97,10 +104,7 @@ Every other runtime modifier is sourced from the Epic's labels or from
   (`--event epic.close.end` / `--event epic.automerge.start` /
   `--event epic.merge.armed`); the matching listener chain runs the
   bus-driven side effects (acceptance reconcile, automerge-armer,
-  branch cleanup). PR open + planning-artifact close are
-  operator-/host-LLM-driven in the current wiring — see Phase 7.1 for
-  the canonical manual sequence and `finalizer.js` for the listener's
-  no-op disclaimer. The append-only NDJSON ledger at
+  branch cleanup). The append-only NDJSON ledger at
   `temp/epic-<id>/lifecycle.ndjson` is the resume target. See
   [`docs/LIFECYCLE.md`](../../../docs/LIFECYCLE.md) for the bus
   contract, event taxonomy, ledger format, and listener model.
@@ -152,9 +156,7 @@ run upserts the same comment in place.
 
 Threshold defaults live in `delivery.preflight.*` in `.agentrc.json`
 (all keys default to "no cap" — the gate is opt-in until an operator
-configures `maxStories` etc.). The CI-firehose mitigation
-(`delivery.ci.skipForStoryPushes: true`) and these threshold keys are
-the two operator-tunable knobs F13 ships.
+configures `maxStories` etc.).
 
 ### Phase 1 main — Seed the wave plan
 
@@ -167,10 +169,15 @@ Validates `type::epic`, enumerates `type::story` descendants, parses
 (to enumerate the open Story set), and upserts the `epic-run-state`
 checkpoint in the per-Story-status shape (a flat `stories` map seeded at
 `pending`, plus the global `concurrencyCap`). Treat the printed JSON as
-`state`: `{ epicId, storyCount, concurrencyCap, stories, checkpointInitializedAt }`.
+`state`: `{ epicId, storyCount, concurrencyCap, stories, checkpointInitializedAt, docsDigestPath }`.
 `stories` is the flat dispatch hint (`{ storyId, worktree, title }` per open
 Story); the ready-set `tick` (Phase 2) decides which to dispatch on each
-beat. Flip the Epic to `agent::executing` (idempotent) after the CLI returns.
+beat. `docsDigestPath` is the repo-relative path to the per-Epic docs digest
+(`temp/epic-<epicId>/docs-digest.md`) that prepare writes from
+`project.docsContextFiles` — thread it into every child prompt (§ 2b, item 6).
+It is `null` when the project configured no `docsContextFiles` (no digest is
+written). Flip the Epic to `agent::executing` (idempotent) after the CLI
+returns.
 
 **No spec-ticket linkage to resolve (Story #4324).** The Tech Spec lives
 as managed sections of the Epic body itself — there is no separate
@@ -179,52 +186,14 @@ into the per-Story `story-init.js` invocations. Story agents receive the
 Tech Spec via context hydration, which embeds the Epic body (with the
 `## Acceptance Table` section stripped) directly into each Story prompt.
 
-> **Preflight guards (Story #3482 / F-workflow-guards).** Before the
-> snapshot phase runs — and before any worktree is created — prepare runs
-> two **fail-closed** guards
-> ([`lib/orchestration/epic-deliver-lease-guard.js`](../../scripts/lib/orchestration/epic-deliver-lease-guard.js)):
->
-> 1. **Checkout safety.** Prepare refuses to start when the working tree is
->    dirty or HEAD is on a branch other than the expected one (`epic/<id>`
->    on a resume, or the project base branch on a fresh run). It will
->    **not** check `epic/<id>` out over your work — the historic
->    HEAD-yank footgun. Remediation: commit/stash/clean the tree, or
->    switch to the expected branch, then re-run.
-> 2. **Epic lease.** Prepare acquires the assignee-as-lease on the Epic
->    ticket (`ticket-lease.acquireLease`). On a **live foreign claim**
->    (a teammate's run with a fresh `story.heartbeat` within
->    `delivery.lease.ttlMs`) it exits non-zero and names the current owner;
->    a **stale** claim is silently reclaimed. The operator identity is
->    resolved from `--as <handle>` → `github.operatorHandle` →
->    `git config user.email`. Pass `--steal` to forcibly transfer a live
->    foreign claim (the takeover is logged for auditability). The committed
->    `github.operatorHandle` is the non-personal `@[USERNAME]` placeholder,
->    which resolves to null — so when none of the three sources yields a real
->    identity the guard **fails closed** (throws after the checkout guard
->    runs) rather than driving an ownerless, unguarded delivery. Set your own
->    handle in `.agentrc.local.json`, pass `--as <handle>`, or configure
->    `git user.email`. The lease is the cross-clone coordination layer, while
->    `epic-merge-lock.js` continues to serialize same-machine sessions.
->
-> Both guards throw on failure, which `runAsCli` maps to `process.exit(1)`
-> per [`orchestration-error-handling.md`](../../rules/orchestration-error-handling.md).
-
-Once the preflight guards pass, the snapshot phase applies one more gate:
-
-> **Acceptance-table start gate.** Before the wave loop fans out, the
-> snapshot phase
-> ([`lib/orchestration/epic-runner/phases/snapshot.js`](../../scripts/lib/orchestration/epic-runner/phases/snapshot.js))
-> asserts that the Epic either carries the `acceptance::n-a` waiver
-> label **or** has a `## Acceptance Table` managed section in its
-> body — section presence is sufficient.
-> The reviewer's OK during `/plan` Phase 7 is the approval
-> signal. Neither condition met →
-> the snapshot throws a clear error
-> (`[epic-deliver] Epic #<id> cannot launch: …` — naming the missing
-> `## Acceptance Table` section and the absent waiver) and `runAsCli`
-> maps it to `process.exit(1)`. Operator remediation: either run
-> `/plan` Phase 7 to author the acceptance table, or apply the
-> `acceptance::n-a` label to opt out.
+> **Preflight guards + acceptance-table start gate.** Before the snapshot
+> phase runs — and before any worktree is created — prepare runs two
+> **fail-closed** guards (checkout safety + Epic lease), then the snapshot
+> phase asserts the Epic carries an `acceptance::n-a` waiver or a
+> `## Acceptance Table` section. Both throw on failure. See
+> [`deliver-epic-reference.md` § Phase 1 — Preflight guards](deliver-epic-reference.md#phase-1--preflight-guards-story-3482--f-workflow-guards)
+> for the remediation detail (dirty-tree recovery, `--steal`, waiver
+> options).
 
 ---
 
@@ -284,11 +253,10 @@ spans). The [`signals` helper](signals.md)
 (`node .agents/scripts/signals-view.js`) renders the forensics signals in the
 span-tree view.
 
-> **Fail-closed on an old-shape checkpoint.** If the Epic still carries a
-> pre-ready-set (`plan` / `currentWave` / `totalWaves`) `epic-run-state`
-> checkpoint, the tick **refuses to run** and throws an explicit operator
-> message — re-run `epic-deliver-prepare.js --epic <id>` to re-seed the
-> checkpoint in the per-Story-status shape, then re-run `/deliver`.
+> **Old-shape checkpoint → fail-closed.** A pre-ready-set
+> (`plan` / `currentWave` / `totalWaves`) checkpoint makes the tick refuse
+> to run and throw; re-seed via `epic-deliver-prepare.js`. See
+> [`deliver-epic-reference.md` § Fail-closed on an old-shape checkpoint](deliver-epic-reference.md#fail-closed-on-an-old-shape-checkpoint).
 
 ### 2b. Dispatch — fan out per-Story Agent calls
 
@@ -306,15 +274,12 @@ Dispatch the ready set as background calls (`run_in_background: true`) and,
 as each child returns, record it (§ 2c) and **re-tick** (§ 2a) to pull the
 next ready set — never wait for the whole set before refilling.
 
-> **Throughput tradeoff.** The default `concurrencyCap` of 3 is the GLOBAL
-> in-flight cap, intentionally conservative — it keeps host-quota
-> consumption low and avoids flooding the GitHub API. For Epics with wide
-> dependency-free fronts where the host has adequate parallel-agent quota,
-> raising `delivery.deliverRunner.concurrencyCap` in `.agentrc.json` reduces
-> wall-clock time proportionally to the extra concurrency. The safe default
-> is left in place; this is a deliberate operator-tuning knob, not a hidden
-> performance ceiling. See `agentrc-reference.json`
-> `delivery.deliverRunner.concurrencyCap` for the configuration surface.
+> **Throughput + capability tuning.** The default `concurrencyCap` of 3 is
+> a deliberate operator-tuning knob (raise
+> `delivery.deliverRunner.concurrencyCap`), and the optional per-call
+> `model:` escape hatch lets mechanical Stories run on a cheaper capability.
+> See [`deliver-epic-reference.md` § Throughput tradeoff](deliver-epic-reference.md#throughput-tradeoff)
+> and [§ Sub-agent dispatch capability](deliver-epic-reference.md#sub-agent-dispatch-capability).
 
 **Ledger the dispatch BEFORE the Agent call.** Immediately before each
 per-Story `Agent` tool call (one shell-out per Story, every attempt —
@@ -345,13 +310,24 @@ Each Agent call's prompt must (1) name the Story + Epic ids, (2)
 instruct the child to invoke `helpers/epic-deliver-story <storyId>`
 (whose Step 4 defines the child's return shape), (3) remind the child
 of the **non-interactive contract** (no clarifying questions;
-transition to `agent::blocked` and exit if stuck), (4) ask the child to
-suppress per-Story chat relay, and (5) require the child to emit a
-`story.heartbeat` lifecycle event at least once per Story-level phase
-transition via `node .agents/scripts/story-phase.js` (or whenever it
-stalls on a long-running step), and if it cannot make progress to
-transition to `agent::blocked` rather than fall silent. The pairing of
-`story.heartbeat` and `agent::blocked` is what lets the §2e Idle
+transition to `agent::blocked` and exit if stuck), (4) tell the child to
+suppress per-Story chat relay and instead relay **one line per phase
+transition** (e.g. `Story #<id>: implementing → closing`) — the child's
+authoritative progress lands in the `story-run-progress` snapshot the
+`story-phase.js` CLI upserts, not in a verbatim body dump, (5) require the
+child to emit a `story.heartbeat` lifecycle event at least once per
+Story-level phase transition via `node .agents/scripts/story-phase.js` (or
+whenever it stalls on a long-running step), and if it cannot make progress
+to transition to `agent::blocked` rather than fall silent, and (6) pass the
+**docs digest path** — the `docsDigestPath` field from the
+`epic-deliver-prepare.js` envelope (§ Phase 1 main), which points at
+`temp/epic-<epicId>/docs-digest.md`. Instruct the child to read that
+digest instead of re-reading the full `project.docsContextFiles` set,
+and to pull individual docs files on demand (per
+[`.agents/instructions.md` § 3](../../instructions.md)). When
+`docsDigestPath` is null (the project configured no `docsContextFiles`),
+say so — the child then has no per-Story docs mandate. The pairing of
+`story.heartbeat` and `agent::blocked` is what lets the § 2d Idle
 Watchdog distinguish a working child from a dead one; a silent child
 with no recent heartbeat and no blocker label is the failure mode the
 watchdog is built to catch.
@@ -362,13 +338,6 @@ to enforce. GitHub state is the contract: `epic-execute-record-wave.js`
 hint and reconciles any unparseable, empty, or missing return directly
 from the Story's live labels and comments.
 
-**Sub-agent dispatch.** `Agent` calls emit no `model:` argument by
-default — children inherit from the `general-purpose` sub-agent
-definition and the parent's worktree context. No
-`--dangerously-skip-permissions` (no subprocess is spawned). If a
-specific call needs to override the inherited model, pass `model:` as a
-per-call literal at the `Agent(...)` site.
-
 ### 2c. Record the Story outcomes
 
 As dispatched Stories return (record them as they land — you need not wait
@@ -397,14 +366,11 @@ Print `renderedBody` verbatim, then optionally append a short **Notable**
 section (0–5 bullets on newly blocked / failed / slow Stories, friction,
 elapsed-time surprises).
 
-> **Crash recovery.** If the host crashed *after* a child finished but
-> *before* its return was recorded, the next `tick` re-derives that Story's
-> state directly from its live label (the tick reads labels every beat), so a
-> done-but-unrecorded Story is recognised as done and never re-dispatched —
-> there is no falsely-`complete` empty wave to recover from. If you want to
-> reconcile a known-completed Story whose return text was lost, re-record it
-> from its live state by passing `--results '[{"storyId":<n>,"status":"done"}]'`
-> (verification re-checks the live label before recording `done`).
+> **Crash recovery.** A child that finished but was never recorded is
+> re-derived from its live label on the next `tick` and never
+> re-dispatched. See
+> [`deliver-epic-reference.md` § Crash recovery (record step)](deliver-epic-reference.md#crash-recovery-record-step)
+> for the manual re-record command.
 
 ### 2d. Loop on `nextAction`
 
@@ -430,69 +396,14 @@ After `2c`, re-run `wave-tick.js`. Branch on the new envelope:
   the done count equals the in-scope Story count — a stuck Story surfaces
   as `halt`, not a false `epic-complete`.)
 
-### 2e. Idle Watchdog
-
-A Story's implementation loop can run for many minutes between
-`story.dispatch.start` and the post-merge `story.merged` record. While
-`observe` keeps the host LLM polling the Epic, it does **not** flag a
-sub-agent that has gone silent (host crash, mid-Story stall, lost
-return). The Idle Watchdog closes that gap.
-
-**Cadence.** While any Story is in flight (i.e. `nextAction.kind` is
-`observe` or the most recent dispatch's `in-flight` list is non-empty),
-re-tick every **30 minutes** with the watchdog flag:
-
-```bash
-node .agents/scripts/wave-tick.js --epic <epicId> --check-idle 30
-```
-
-> **Why 30, not 10 (Story #3900).** Heartbeats fire only at Story-level
-> phase transitions, and `implementing → closing` routinely exceeds 10
-> minutes for a healthy Story. A 10-minute threshold therefore tripped the
-> watchdog on every long-running Story, whose prescribed remediation —
-> re-dispatch — put two agents on one `story-<id>` branch (the worst
-> failure mode in the system). The threshold is widened to 30 minutes and
-> the staleness test now also consults a deterministic branch-commit
-> signal (below), so a Story still gaining commits is never flagged.
-
-The `--check-idle <minutes>` mode scans the per-Epic lifecycle ledger
-(`temp/epic-<epicId>/lifecycle.ndjson`) for Stories that carry a
-`story.dispatch.start` without a matching `story.dispatch.end` (the
-canonical in-flight list — see § 2a's `nextAction['in-flight']`), and
-compares each in-flight Story's most recent ledger event (any
-`story.*` event, notably the `story.heartbeat` records emitted by
-`story-phase.js` at each Story-level phase transition) against the
-threshold. **Before flagging a stall, it also checks the last commit on
-`story-<id>` via `git log` (Story #3900): a Story whose branch carries a
-commit newer than the threshold is making forward progress and is left
-in-flight, never stalled — deterministic protection against the
-false-positive re-dispatch hazard even when no heartbeat has landed.**
-The CLI emits one envelope on stdout and exits non-zero when at least
-one in-flight Story has been silent for ≥ the threshold:
-
-```json
-{
-  "kind": "wave-stall",
-  "epicId": <n>,
-  "thresholdMinutes": <n>,
-  "checkedAt": "<ISO-8601>",
-  "stalled": [{ "storyId": <n>, "lastEventAt": "<ISO-8601>", "idleMinutes": <n> }],
-  "inFlight": [<storyId>, ...]
-}
-```
-
-**On a stall.** When the watchdog exits non-zero, post the envelope
-verbatim as a `wave-stall` structured comment on the Epic (use
-[`post-structured-comment.js`](../../scripts/post-structured-comment.js)
-with `--kind wave-stall`), then re-evaluate the affected Stories: if a
-child sub-agent has crashed (no `story.dispatch.end`, no recent
-heartbeat, no commit on `story-<id>`), re-dispatch the Story per § 2b
-incrementing the `--attempt` counter; if the child is alive but
-genuinely blocked, flip the Story to `agent::blocked` and proceed per
-§ 2d's `observe` branch.
-
-Stop the watchdog cadence once `wave-tick.js` returns `epic-complete` —
-there are no in-flight Stories left to monitor.
+> **Idle Watchdog.** While any Story is in flight, re-tick every 30 minutes
+> with `wave-tick.js --epic <epicId> --check-idle 30` so a silent child
+> (crashed host, lost return) is surfaced as a `wave-stall` and
+> re-dispatched or blocked. The full cadence, staleness test (heartbeat +
+> deterministic branch-commit signal), stall envelope, and the "why 30 not
+> 10" rationale are in
+> [`deliver-epic-reference.md` § 2e. Idle Watchdog](deliver-epic-reference.md#2e-idle-watchdog).
+> Stop the cadence once the tick returns `epic-complete`.
 
 ---
 
@@ -593,219 +504,91 @@ canonical compose-and-post surface at
 Propagate `--full-retro` to bypass the compact-path heuristic.
 
 Retro fires here (before the PR opens) so it stays in the operator's
-local session with full env access (env vars, credentials, MCP).
-
-After the GitHub upsert succeeds, the retro body is also **mirrored
-locally** to the per-Epic temp tree at `temp/epic-<epicId>/retro.md`
-(path resolved via
+local session with full env access (env vars, credentials, MCP). After
+the GitHub upsert succeeds, the retro body is also **mirrored locally** to
+`temp/epic-<epicId>/retro.md` (path resolved via
 [`lib/config/temp-paths.js`](../../scripts/lib/config/temp-paths.js)'s
-`epicRetroMirrorPath`, which honours `project.paths.tempRoot`).
-Operators can read the retro without re-fetching from GitHub. GitHub
-remains the source of truth — a mirror-write failure only logs a warn
-and never fails the phase.
+`epicRetroMirrorPath`). GitHub remains the source of truth — a
+mirror-write failure only logs a warn and never fails the phase.
 
 ---
 
 ## Phase 6.5 — Post-wave integration gate (Epic #4131, F1/F4)
 
 This phase runs **after** the Phase 2 wave loop reports `epic-complete` and
-**before** the Phase 7 finalize emit opens the PR to `main`. Where every gate
-before it (`selectAudits`, the cross-epic-leak guard `#3362`, diff-against-base,
-the file-assumption gate) is **change-set-scoped** — it narrows its evidence to
-the Epic's `changedFiles` — this is the one **deliberately-global** gate: its
-evidence spans the **whole product**, not just the change set. The disease it
-catches is the surface that each Story shipped correctly in isolation yet that
-the assembled product cannot reach: a route nobody can navigate to, or a
-persona journey that the integrated waves silently broke. A change-set lens
-never sees that, because no single Story's diff contains the orphan.
+**before** the Phase 7 finalize emit opens the PR to `main`. It is the one
+**deliberately-global** gate — its evidence spans the whole product, not just
+the Epic's change set — so it catches the surface each Story shipped correctly
+in isolation yet the assembled product cannot reach (an unnavigable route, a
+broken persona journey).
 
 Skip when `--skip-integration-gate` (log the override; record a manual
-intervention per [§ Recording manual interventions](#recording-manual-interventions)).
-The gate is otherwise **always evaluated**, but it is a **silent no-op when
-unconfigured** (see *No-op when unconfigured* below) so consumers who ship no
-nav config and no journey suite are unaffected.
-
-### 6.5a — Whole-product navigability (reuses the Phase 4 lens)
-
-Run the `navigability` lens
-([`audit-navigability.md`](../audit-navigability.md), the deliberately-global
-lens delivered in this Epic's wave 0) in **whole-route mode** against the
-integrated `epic/<epicId>` tip. Unlike its Phase 4 change-set-routed invocation,
-here it is driven explicitly over the consumer's **entire** route tree + nav
-registry — it is on the global-lens allowlist (`GLOBAL_LENS_ALLOWLIST` in
-[`lib/audit-suite/selector.js`](../../scripts/lib/audit-suite/selector.js)) and
-exempt from the cross-epic-leak guard `#3362`, so a route orphaned anywhere in
-the product is in scope even when no Story in this Epic touched it.
-
-The lens reads the consumer's navigability config (resolved from `.agentrc.json`):
-
-- `delivery.quality.navigability.routeGlobs` — the route-tree SSOT the lens
-  enumerates.
-- `delivery.quality.navigability.navRegistry` — the nav-registry SSOT the lens
-  cross-checks every route against.
-
-A whole-product finding is a **hard failure**: an **orphaned route** (a route
-with no nav door for any entitled persona) or a **dead nav href** (a nav door
-pointing at a route that no longer exists). On a hard failure the gate **blocks
-finalize** and names the orphaned surface (route identifier / nav-door
-identifier only — never the route body or persona PII, per
-`security-baseline.md`). Do **not** proceed to Phase 7.
-
-### 6.5b — Consumer journey suite
-
-Run the consumer's per-persona journey suite — the integrated, cross-Epic
-persona-journey verification — over the `epic/<epicId>` tip:
-
-- `delivery.quality.navigability.journeySuite` — path/command for the journey
-  suite. Absent ⇒ this sub-step is skipped (no-op).
-
-A failing journey (a persona cannot complete an end-to-end journey through the
-assembled product) is a **hard failure**: block finalize and name the broken
-journey. This is the runtime complement to 6.5a's static reachability check —
-6.5a proves a door exists; the journey suite proves the door, and everything
-behind it, actually works when the waves are integrated.
-
-### 6.5c — `@pending` ≠ green for surface-adding Epics (F4)
-
-The Phase 7 finalize chain runs the acceptance-spec reconciler
-([`acceptance-spec-reconciler.js`](../../scripts/acceptance-spec-reconciler.js)),
-which classifies every AC ID into `satisfied` (covered by a non-pending
-scenario), `pending` (covered **only** by scenarios tagged `@pending`), or
-`missing`. For a **surface-adding Epic** — one whose risk verdict carries a
-surface-adding signal (a route-adding change set, the `navigability` lens routed
-in Phase 4, or a configured `routeGlobs` match) — this phase tightens that
-contract: an AC whose coverage is **only `@pending`** is treated as
-**unsatisfied**, not green. A surface-adding Epic whose acceptance coverage is
-**only `@pending`** therefore **fails the close gate** instead of passing —
-shipping a new surface behind a deferred-forever `@pending` scenario is exactly
-the late-gate gap this Epic exists to close.
-
-This is **purely additive** and **scoped to surface-adding Epics**:
-refactor-only and docs-only Epics (no surface-adding signal) are **unaffected** —
-their `@pending` handling is exactly as before, and the existing
-`satisfied` / `missing` reconciliation is **not** de-scoped for any Epic.
-
-### No-op when unconfigured
-
-With **no** navigability config (`routeGlobs` / `navRegistry`) and **no**
-`journeySuite` present in `.agentrc.json`, this entire phase degrades to a
-**silent no-op**: 6.5a and 6.5b skip (nothing to enumerate or run) and 6.5c's
-surface-adding signal cannot fire without route globs, so the `@pending`
-tightening never engages. The gate adds **zero** behaviour to an unconfigured
-consumer — it neither blocks finalize nor changes the existing change-set-scoped
-gates. The override flag `--skip-integration-gate` is the explicit operator
-escape hatch (consistent with `--skip-epic-audit`) for a configured consumer who
-wants to bypass the gate for a specific run.
-
-### Fail safe and loud
-
-Per the Tech Spec's security note, this gate sits on the **critical path** to
-finalize. It MUST fail **safe and loud**: a hard failure **blocks** finalize and
-**names the cause** (the orphaned route, dead href, broken journey, or
-`@pending`-only AC), never silently passes. A genuinely unconfigured consumer is
-the **only** silent path, and that path **passes** (it is a no-op, not a block).
-On a hard failure, post a friction structured comment naming the surface, flip
-the Epic to `agent::blocked`, and park for the operator — do **not** open the PR.
+intervention per
+[`deliver-epic-reference.md` § Recording manual interventions](deliver-epic-reference.md#recording-manual-interventions)).
+The gate is otherwise **always evaluated** but a **silent no-op when
+unconfigured** (no `routeGlobs` / `navRegistry` / `journeySuite` in
+`.agentrc.json`).
+
+Sub-steps and hard-failure semantics:
+
+- **6.5a — Whole-product navigability**: run the `navigability` lens in
+  whole-route mode over the `epic/<epicId>` tip. An **orphaned** route (no
+  nav door for any entitled persona) or a dead nav href is a hard failure
+  that **blocks finalize** and names the surface.
+- **6.5b — Consumer journey suite**: run
+  `delivery.quality.navigability.journeySuite` over the tip. A failing
+  persona journey is a hard failure that **blocks finalize** and names the
+  broken journey.
+- **6.5c — `@pending` ≠ green for surface-adding Epics (F4)**: for a
+  **surface-adding** Epic, an AC covered **only** by `@pending` scenarios is
+  treated as unsatisfied and **fails the close gate** instead of passing
+  green. This is **purely additive** and scoped to surface-adding Epics —
+  refactor-only and docs-only Epics are **unaffected** and the existing
+  `satisfied` / `missing` reconciliation is **not de-scoped** for any Epic.
+
+On any hard failure, post a friction structured comment naming the surface
+(route / nav-door identifier only — never route bodies or persona PII per
+`security-baseline.md`), flip the Epic to `agent::blocked`, and **do not**
+open the PR — the gate fails safe and loud. See
+[`deliver-epic-reference.md` § Phase 6.5](deliver-epic-reference.md#phase-65--post-wave-integration-gate-epic-4131-f1f4)
+for the full lens config, the surface-adding-signal derivation, the no-op
+degradation contract, and the fail-safe-and-loud security note.
 
 ---
 
 ## Phase 7 — Finalize (open PR to main)
 
-### 7.0 — Sync Epic branch from `main` (Story #2580)
-
-Before firing the close-tail emit, sync the Epic branch with
-`origin/main` so the PR opens with the latest base commits already
-integrated. The Epic branch may be behind `main` if other PRs merged
-during the wave loop; without this step, the Epic→`main` PR opens
-"behind base" and (with branch-protection's `up-to-date branch` rule)
-stalls at the merge gate.
+Before the close-tail emit, sync the Epic branch with `origin/main` so the
+PR opens with the latest base commits already integrated (a stale base
+stalls at branch-protection's `up-to-date branch` rule):
 
 ```bash
 git checkout epic/<epicId>
 node .agents/scripts/sync-branch-from-base.js \
   --branch epic/<epicId> --base main
+git push origin epic/<epicId>
 ```
 
-Outcomes:
-
-- **`fast-forward` / `merge-commit` / `noop-already-current`** → push
-  the resulting tip and continue to Phase 7.1: `git push origin epic/<epicId>`.
-- **`conflict`** → resolve in the Epic checkout (`git merge --no-edit
-  origin/main`, fix conflicts, `git commit --no-edit`), then re-run the
-  sync command. Once it exits 0, continue. Operator-recoverable; not an
-  agent loop.
-- **`fetch-failed`** → re-check network / `origin` access and re-run.
-
-This is a workflow-level step (operator-driven), not part of the
-close-tail listener chain. The sync runs from the main checkout so
-the resulting tip lands on `epic/<epicId>` before Phase 7.1 fires
-the bus-driven close-tail.
-
-### 7.1 — Fire the close-tail emit
+Then fire the close-tail emit:
 
 ```bash
 node .agents/scripts/lifecycle-emit.js --epic <epicId> --event epic.close.end
 ```
 
-Emits `epic.close.end` onto the lifecycle bus. **Every close-time
-responsibility below runs inside the listener chain — the operator
-shells nothing manually. The `Finalizer` listener (Story #2894 —
-bus-owned finalize) composes three helpers under
-`.agents/scripts/lib/orchestration/finalize/` and emits the canonical
-chain.** Treat this section as a runtime contract — `/deliver`
-just fires the emit and reads the resulting ledger.
-
-1. **Acceptance-table reconciliation — bus-driven.** The
-   `AcceptanceReconciler` listener invokes
-   [`acceptance-spec-reconciler.js`](../../scripts/acceptance-spec-reconciler.js)
-   to diff the AC IDs declared in the Epic body's `## Acceptance Table`
-   section against `@ac-*` / `@pending` tags in `tests/features/**`,
-   recording each row's verification outcome
-   (`satisfied` / `pending` / `missing`) into the table's Disposition
-   column via a section-scoped upsert of the Epic body. A
-   non-OK reconciliation throws (per
-   [`rules/orchestration-error-handling.md`](../../rules/orchestration-error-handling.md)),
-   aborting finalize **before** any PR is opened — so the Epic stays
-   unfinalized until the AC coverage gap is fixed. The reconciler returns
-   `status: 'waived'` without scanning features when the Epic carries
-   `acceptance::n-a`, and defends against direct CLI invocation by
-   refusing to run when the body has no `## Acceptance Table` section
-   and no waiver is set (the
-   start gate in Phase 1 would normally catch that first).
-2. **PR open — bus-driven (Story #2894).** On
-   `acceptance.reconcile.ok` the `Finalizer` listener invokes
-   [`openOrLocatePr`](../../scripts/lib/orchestration/finalize/open-or-locate-pr.js)
-   with `{ epicId, headBranch: 'epic/<id>', baseBranch: 'main' }`.
-   The helper probes for an existing open PR on the head branch
-   first (idempotent locate path — a re-run of `/deliver`
-   on the same branch short-circuits without opening a duplicate)
-   and only opens a new PR when none exists. The listener then
-   emits `pr.created` → `epic.finalize.end` and **stops** (Story
-   #3367). It does **not** emit `epic.merge.ready`: that event is
-   the sole `AutomergeArmer` trigger, and emitting it from finalize
-   would cascade `epic.close.end` synchronously through the arm →
-   `MergeWatcher` → `Cleaner` → `BranchCleaner` reap, deleting the
-   `epic/<id>` branch before the PR merged and bypassing the
-   `AutomergePredicate` disqualification gate. The auto-merge arm is
-   driven later from the gated watch path (`pr.created` → `Watcher`
-   → `epic.watch.end` → `AutomergePredicate` → `epic.merge.ready` →
-   `AutomergeArmer`) re-entered in Phase 8.5. The merge-lockout rule
-   in [`check-lifecycle-lint.js`](../../scripts/check-lifecycle-lint.js)
-   keeps `gh pr merge --auto --squash --delete-branch` confined to
-   `AutomergeArmer` — Phase 7 never shells the merge command.
-3. **Hand-off — bus-driven (Story #2894).** After `openOrLocatePr`
-   returns, the `Finalizer` chains
-   [`postHandoffComment`](../../scripts/lib/orchestration/finalize/post-handoff-comment.js)
-   to upsert the canonical `epic-handoff` structured comment naming
-   the PR URL. The helper is idempotent — the handoff comment is
-   edited in place via `upsertStructuredComment` rather than
-   appending a duplicate. There is **no planning-ticket close sweep**
-   (Story #4324): the planning artifacts live as sections of the Epic
-   body itself, so there are no context tickets to close and nothing
-   blocks the Epic's `Closes #<id>` auto-close path.
-
-Branch cleanup is out-of-band (Phase 9 reaps local refs after merge; the
-rare "scrap and reset" case for an unmerged Epic is handled manually).
+`epic.close.end` drives the bus-owned `Finalizer` chain: acceptance-table
+reconciliation (throws and aborts finalize on a coverage gap, `waived` under
+`acceptance::n-a`), idempotent PR open/locate against `main`, and the
+`epic-handoff` comment naming the PR URL. The chain emits `pr.created` →
+`epic.finalize.end` and **stops** — it never emits `epic.merge.ready` (the
+auto-merge arm is driven later from the Phase 8.5 gated watch path). The
+operator shells nothing beyond the sync and the single emit.
+
+See
+[`deliver-epic-reference.md` § Phase 7 — Finalize](deliver-epic-reference.md#phase-7--finalize-close-tail-listener-chain)
+for the branch-sync outcome table (conflict / fetch-failed recovery) and the
+full three-step listener contract (why finalize must not emit
+`epic.merge.ready`, the merge-lockout lint rule, the no planning-ticket close
+sweep).
 
 ---
 
@@ -828,43 +611,13 @@ node <agentRoot>/scripts/pr-watch-with-update.js --pr <prNumber>
 calls per session and `--poll-interval-ms MS` (default 10000) to
 override the polling cadence.
 
-Exit 0 → proceed to Phase 8.5. Non-zero → remediate (below) and re-run
-the helper. Auto-merge stays armed across retries; the
-`epic.automerge.start` emit in Phase 8.5 re-runs the `AutomergeArmer`
-listener, which re-checks `mergeStateStatus` before firing merge, so a
-second BEHIND that arrives between the helper exiting clean and Phase
-8.5 starting is also caught.
-
-### 8.1 Remediation
-
-For each failed required check: fetch the log
-(`gh run view <runId> --log-failed`), classify and fix:
-
-- **lint / format** → `npm run lint` + `npx biome check --apply` (or
-  `format --write`); commit, push.
-- **maintainability / crap baseline drift** → re-run the ratcheted
-  script. Refresh the baseline only when drift is justified by the
-  diff; otherwise fix at source.
-- **test failure** → reproduce with `npm test`, fix source or test.
-- **coverage threshold** → add tests (preferred); refresh baseline only
-  when the diff demonstrably can't be covered.
-- **anything else** → read the log, fix at source.
-
-Push to `epic/<epicId>` and re-run
-`node <agentRoot>/scripts/pr-watch-with-update.js --pr <prNumber>`.
+Exit 0 → proceed to Phase 8.5. Non-zero → remediate and re-run the helper
+(push fixes to `epic/<epicId>`; auto-merge stays armed across retries).
 
-### 8.2 When to halt
-
-Three consecutive iterations on the same failure class without
-convergence → friction comment, flip to `agent::blocked`, park. Unknown
-failure class on first encounter → attempt source-level fix; log
-friction if diagnosis takes more than one round.
-
-### 8.3 Hard prohibitions
-
-**Never** `gh pr merge` from Phase 8 (Phase 8.5 is the only merge
-site). **Never** force-push to `main`. **Never** push empty commits or
-refresh baselines to dodge a red check.
+> **Remediation + hard prohibitions.** For the per-check fix table (lint,
+> baseline drift, test, coverage), the three-strikes halt rule, and the
+> never-merge / never-force-push / never-dodge prohibitions, see
+> [`deliver-epic-reference.md` § Phase 8 — Watch-and-iterate remediation](deliver-epic-reference.md#phase-8--watch-and-iterate-remediation).
 
 ---
 
@@ -878,57 +631,29 @@ node .agents/scripts/lifecycle-emit.js --epic <epicId> \
   --event epic.automerge.start --pr-url <prUrl>
 ```
 
-`AutomergePredicate` subscribes to `epic.automerge.start` (Story #3901 —
-before that this event had **zero** subscribers and the entire Phase 8.5
-gate was a dead wire). It evaluates the structured-signal verdict and
-emits `epic.merge.ready` on a clean verdict or `epic.merge.blocked`
-otherwise. The CI-freshness gate is skipped on this event because Phase 8
-already polled every required check to green — `epic.automerge.start`
-carries `prUrl` but no `checkOutcomes`.
-
-The `AutomergeArmer` listener subscribes to the downstream
-`epic.merge.ready` outcome and fires `gh pr merge --auto --squash
---delete-branch` only when `clean: true`. `clean: true` requires
-**all** of:
-
-- `state.manualInterventions[]` is empty;
-- every wave's `status === "complete"`;
-- no story envelope carries a `blockerCommentId` or non-`done` status;
-- code-review reports `0` 🔴 + `0` 🟠 findings;
-- the retro's machine-readable `automerge-verdict` trailer reports
-  `cleanSprint: true` (Story #3901 — the predicate reads the parsed JSON
-  trailer `retro-run.js` writes into the retro body, **not** an emoji
-  string-match on the human-facing "🟢 Clean sprint" prose).
-
-When clean, the listener fires `gh pr merge --squash --delete-branch`.
-Otherwise the listener records disqualifying reasons via
-`epic.merge.blocked` and exits without merging — operator merges
-manually.
-
-Close the phase wrapper by emitting `epic.automerge.end` (records the
-arm outcome on the ledger; `merged: true` once GitHub completes the
-squash, `merged: false` with a reason for predicate-blocked or
-armed-but-pending):
+`AutomergePredicate` evaluates the structured-signal verdict and emits
+`epic.merge.ready` on a clean verdict or `epic.merge.blocked` otherwise. The
+downstream `AutomergeArmer` fires `gh pr merge --auto --squash
+--delete-branch` **only** when `clean: true` (empty manual-interventions,
+every wave complete, no story blocked, `0` 🔴 + `0` 🟠 review findings, and
+the retro's `automerge-verdict` trailer reports `cleanSprint: true`).
+Otherwise it records disqualifying reasons and exits without merging — the
+operator merges manually.
+
+Close the phase wrapper by emitting `epic.automerge.end` (records the arm
+outcome on the ledger; `merged: true` once GitHub completes the squash,
+`merged: false` with a reason otherwise):
 
 ```bash
 node .agents/scripts/lifecycle-emit.js --epic <epicId> \
   --event epic.automerge.end --pr-url <prUrl> --merged <true|false>
 ```
 
-### Recording manual interventions
-
-Whenever you step outside the happy path during a delivery, record it
-(each entry disqualifies auto-merge):
-
-```bash
-node .agents/scripts/epic-deliver-note-intervention.js \
-  --epic <epicId> --reason "<one-line description>"
-```
-
-Triggers: `AskUserQuestion` mid-run; `git restore`/`reset` against the
-tree; child-reported `--no-ff` recovery, stash dance, or out-of-band
-merge surgery; child closes via `--skipValidation`; force-pushing or
-empty-committing to dodge CI diagnosis.
+> **Predicate wiring + manual-intervention recording.** For the full
+> `clean: true` predicate contract (Story #3901 — the trailer read, the
+> CI-freshness skip) and the `epic-deliver-note-intervention.js` command +
+> its trigger list, see
+> [`deliver-epic-reference.md` § Phase 8.5 — Auto-merge predicate detail](deliver-epic-reference.md#phase-85--auto-merge-predicate-detail).
 
 ---
 
@@ -936,54 +661,24 @@ empty-committing to dodge CI diagnosis.
 
 Phase 9 runs **automatically** inside the lifecycle bus once auto-merge
 arms: the `BranchCleaner` listener subscribes to `epic.cleanup.start`
-and reaps local refs before `Cleaner` archives the `temp/epic-<id>/`
-tree. No operator step is required on the auto-merge path.
-
-What gets reaped (in order, all in-process):
-
-1. The main checkout is switched off `epic/<id>` to `baseBranch` when
-   needed (otherwise `git branch -D epic/<id>` is refused).
-2. Every `story-<id>` listed in the `epic-run-state` checkpoint, plus
-   `epic/<id>`. Attached worktrees are removed with the standard
-   `git worktree remove` → `--force` → filesystem-rm fallback (the
-   last step covers Windows file-locks).
-3. `git remote prune <remote>` drops stale `<remote>/...` tracking
-   refs left behind by `gh pr merge --delete-branch`.
-4. The `wt-branch` scratch ref left by `story-close.js`'s internal
-   merge worktree is deleted when no worktree still points at it.
-
-Per-branch failures aggregate into the listener's classification log
-(`reaped` / `failed` / `no-state` / `skipped-duplicate`) and are
-visible in `temp/epic-<id>/lifecycle.ndjson`. They do not block the
-rest of cleanup.
+and reaps local refs (the `epic/<id>` branch, every `story-<id>` in the
+checkpoint, attached worktrees, and stale tracking refs) before `Cleaner`
+archives the `temp/epic-<id>/` tree. No operator step is required on the
+auto-merge path.
 
 For out-of-band cleanup re-entry (resume after a crash, or operator
-override), fire `epic.merge.armed` via the lifecycle-emit helper:
+override), fire `epic.merge.armed`:
 
 ```bash
 node .agents/scripts/lifecycle-emit.js --epic <epicId> \
   --event epic.merge.armed --pr-url <prUrl>
 ```
 
-If Phase 8.5 fell back to the operator-merges-button path (`gh pr
-merge --auto` was declined), the `epic.merge.armed` event never fires
-inside this run and Phase 9 will not run automatically. After the
-operator merges the PR, `epic/<epicId>` and each `story-<id>` ref can
-be reaped manually:
-
-```bash
-git checkout main
-git pull --ff-only origin main
-git branch -D epic/<epicId>
-git branch -D story-<id1> story-<id2> ...
-git remote prune origin
-```
-
-Note that `git-cleanup.js` alone will not catch `story-<id>` refs in
-this case because the epic PR squash-merges break the `git branch
---merged main` signal and the stories never had their own PRs. Wiring
-a CLI surface that drives the BranchCleaner listener for this
-fallback is tracked as follow-up to Story #2398.
+> **Reap order + operator-merges fallback.** For the full in-process reap
+> order, the per-branch classification log, and the manual reap sequence
+> when Phase 8.5 fell back to the operator-merges-button path (auto-merge
+> declined, `epic.merge.armed` never fired), see
+> [`deliver-epic-reference.md` § Phase 9 — Local branch cleanup detail](deliver-epic-reference.md#phase-9--local-branch-cleanup-detail).
 
 ---
 
@@ -999,8 +694,8 @@ the `epic-run-progress` structured comment.
 ## Constraints
 
 - **Never** merge `epic/<epicId>` to `main` outside Phase 8.5.
-- **Never** dispatch more than one wave at a time; concurrency lives
-  inside a single wave's fan-out, capped at `concurrencyCap`.
+- **Never** dispatch more than the global `concurrencyCap` allows;
+  concurrency lives inside the ready-set fan-out.
 - **Never** flip Story-level labels from this skill; **never** invoke
   `helpers/epic-deliver-story` yourself (children run it via Agent fan-out,
   even for single-Story waves); **never** spawn a subprocess for dispatch.