mandrel 1.93.0 → 1.94.0

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

@@ -84,8 +84,13 @@ performance ceiling. See `agentrc-reference.json`
 ### Sub-agent dispatch capability
 
 `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).
+their sub-agent definition and the parent's worktree context. With
+`delivery.routing.roleScopedAgents` on (the default, Epic #4478), a Story child
+boots on the role-scoped [`story-worker`](../../agents/story-worker.md)
+definition — its own system prompt, no `CLAUDE.md` @-closure — instead of the
+full-closure `general-purpose` definition the kill-switch (`roleScopedAgents:
+false`) falls back to. No `--dangerously-skip-permissions` (no subprocess is
+spawned).
 Per [`.agents/instructions.md` § 4](../../instructions.md)'s cost-aware
 spawning heuristic, this optional per-call `model:` is the escape hatch: if
 a specific call would run better on a cheaper or faster capability the host
@@ -143,9 +148,17 @@ The `--check-idle <minutes>` mode scans the per-Epic lifecycle ledger
 `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.*` event, notably the `story.heartbeat` records) against the
+threshold. **As of Epic #4476 (M5) those `story.heartbeat` records are
+emitted OFF the token stream by the PostToolUse hook** (a throttled
+heartbeat per tool call, keyed off the active-Story env) rather than by a
+per-transition `story-phase.js` LLM turn — the signal the watchdog reads is
+unchanged; only its emission mechanism moved. Single-delivery runs have no
+Story fan-out; their liveness signal is `slice.heartbeat` (same hook, keyed
+off the active-slice env), and the watchdog reads it via the additive
+`inFlightSlices` / `stalledSlices` envelope fields — a slice that has gone
+silent past the threshold with no recent commit on `epic-<id>` is flagged
+exactly as a stalled Story is. **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

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

@@ -0,0 +1,331 @@
+---
+description: >-
+  Single-delivery Epic path (invoked by /deliver when the route resolves to
+  `single`). Collapses a spec-only Epic — one that authored NO Story tickets —
+  into ONE guarded in-session slice walk on `epic/<id>`: prepare `--single`,
+  walk the Epic body's `## Delivery Slicing` table in order (implement + commit
+  each slice, flip its checkpoint marker), run per-AC-cluster acceptance
+  critics, then hand off to `deliver-epic.md` Phase 3 for the merge tail
+  (Phases 3–9 reused byte-for-byte). Not a second engine — deliver-epic with
+  Phases 1–2 replaced by the slice walk.
+---
+
+# helpers/deliver-epic-single — single-delivery Epic path (invoked by /deliver)
+
+> **Runtime core.** The single-delivery executor for Epic #4475. The
+> [`/deliver`](../deliver.md) router dispatches here when
+> [`resolveEpicDeliveryRoute`](../../scripts/lib/orchestration/deliver-route.js)
+> returns `single` (the Epic carries `delivery::single` or its
+> `epic-plan-state` checkpoint has `decompose.shape === "single"`), unless the
+> `delivery.routing.singleDelivery=false` kill-switch forces fan-out.
+
+## Overview
+
+A spec-only plan (authored by `/plan`'s single-delivery variant) creates **no
+Story tickets** — the Epic body's `## Delivery Slicing` table is the whole
+work breakdown and the audit trail. There is nothing to fan out, so this path
+does not run the [`deliver-epic.md`](deliver-epic.md) Phase 1–2 wave loop.
+Instead it walks the slicing table **in order** inside one guarded session on
+`epic/<id>`.
+
+The **least-surface insight** (adopted design): in `deliver-epic.md` only
+**Phases 1–2 are Story-tier-specific**. **Phases 3–9 are Epic-scope** — they
+operate on `epic/<id>` + the Epic body's `## Acceptance Table` and dereference
+**no** Story ticket (close-validation, epic-audit lens roster, code-review over
+the cumulative `main..epic/<id>` diff, retro, integration gate, finalize →
+reconcile → the merge machine). So:
+
+```text
+single-delivery = deliver-epic  with Phases 1–2 replaced by an in-session
+                  slice walk (S1/S2/S2a below), and Phases 3–9 reused
+                  byte-for-byte (S2b handoff).
+```
+
+```text
+/deliver <epicId>   (route: single)
+  → S1  Prepare        (epic-deliver-prepare.js --single — slice map, ONE worktree)
+  → S2  Slice walk     (walk ## Delivery Slicing in order; commit + flip each slice on epic/<id>)
+  → S2a Acceptance     (per-AC-cluster fresh-context critics over the cumulative diff)
+  → S2b Handoff        → deliver-epic.md Phase 3 … Phase 9 (merge tail, unchanged)
+```
+
+---
+
+## Contract
+
+- **One long guarded session.** No Story fan-out, no `Agent` dispatch for
+  implementation — you (the LLM running this helper) implement each slice
+  in-session on `epic/<id>`. The per-AC-cluster acceptance critics (S2a) are
+  the **only** `Agent` spawns, and they are read-only maker-blind critics.
+- **Idempotent by checkpoint.** The `epic-run-state` slice map
+  (`slices[id].status ∈ {pending, done, blocked, failed}`) is the resume
+  target: a re-run **skips `done` slices** — the work already sits on
+  `epic/<id>`, so it is never re-paid.
+- **Single pause point.** Only `agent::blocked` halts. If a slice or an
+  acceptance cluster cannot be satisfied, flip the Epic to `agent::blocked`,
+  post a friction comment, and park — never fall silent, never proceed to
+  close with an unmet AC.
+- **No Story-ticket dereference (audit receipt).** Nothing in this path reads,
+  enumerates, or transitions a `type::story` ticket. The leaf unit is a
+  `## Delivery Slicing` slice; the acceptance unit is an `## Acceptance Table`
+  AC cluster; the merge tail is Epic-scope. This is the load-bearing property
+  that lets Phases 3–9 be reused unchanged.
+- **Land or block (issue #4483).** The worktree / `epic/<id>` branch / PR path
+  is the ONLY sanctioned delivery mechanism. Executing slices inline in the
+  main checkout or committing to local `main` is forbidden regardless of how
+  the environment looks. Prepare surfaces `remoteVerified`; on `false` flip to
+  `agent::blocked` quoting `remoteProbe.detail` and halt.
+
+---
+
+## S1 — Prepare the single run
+
+```bash
+node .agents/scripts/epic-deliver-prepare.js --epic <epicId> --single [--steal] [--as <handle>]
+```
+
+`--single` short-circuits Story enumeration
+([`runEpicDeliverPrepareSingle`](../../scripts/epic-deliver-prepare.js)). It:
+
+1. **Refuses `acceptance::n-a`** (fail-closed front gate). Under single
+   delivery the non-waivable epic-level acceptance reconcile is the ONLY
+   acceptance gate, so an Epic declaring "no acceptance criteria" is
+   structurally incoherent — prepare throws. (The back gate is S2b's
+   reconcile; see [Non-waivable reconcile](#non-waivable-acceptance-reconcile).)
+2. Runs the same fail-closed preflight guards as the fan-out prepare
+   (checkout-safety + Epic lease).
+3. Seeds `epic/<id>` and materializes **ONE** worktree at
+   `.worktrees/epic-<epicId>/` on it.
+4. Parses the Epic body's `## Delivery Slicing` table and writes the
+   `epic-run-state` **slice map** (`deliveryShape: "single"`, `storyCount: 0`,
+   `concurrencyCap: 1`) — idempotent + resume-preserving (a re-run keeps every
+   already-`done` slice).
+5. Writes the per-Epic docs digest.
+
+Treat the printed JSON as `state`:
+`{ epicId, deliveryShape, storyCount: 0, sliceCount, slices, epicBranch, workCwd, worktreeCreated, checkpointInitializedAt, docsDigestPath }`.
+Flip the Epic to `agent::executing` (idempotent) after the CLI returns.
+
+> **`sliceCount === 0`.** A missing / unparseable `## Delivery Slicing` table
+> yields an empty slice map — there is nothing to walk. That is a plan-quality
+> defect: post a friction comment, flip to `agent::blocked`, and halt (do NOT
+> proceed to an empty close).
+
+### S2 — `cd` into the worktree (absolute-path discipline)
+
+```bash
+cd "<workCwd from S1>"
+```
+
+All subsequent commands run from this directory.
+
+> **Worktree scope is not just the Bash cwd.** `cd <workCwd>` steers the Bash
+> tool's cwd but does **not** scope the path-based Edit/Write/Read tools — you
+> MUST prefix every such path with the absolute `workCwd` root or risk
+> silently editing the main checkout (same discipline as
+> [`single-story-deliver.md`](single-story-deliver.md) Step 0.5).
+
+---
+
+## S2 — Walk the Delivery Slicing table in order
+
+Read the Epic body's `## Delivery Slicing` table. Walk it **strictly in
+order** as an in-session checklist. The ordered slicing **is** the audit trail
+(the plan authored no tickets), and the ordering encodes the dependency chain
+— never reorder or parallelize.
+
+For each slice `slice-<n>` (1-based, matching the checkpoint's slice-map keys),
+**skip it when `slices[slice-<n>].status === "done"`** (resume: the work is
+already on `epic/<id>`). Otherwise:
+
+1. **Announce the slice.** Emit `slice.start` on the ledger. This same
+   boundary call also exports the active-slice env
+   (`CC_EPIC_ID` / `CC_SLICE_ID`) into the worktree's `.env.local`, which
+   arms the PostToolUse hook to emit `slice.heartbeat` for the rest of this
+   slice (below):
+
+   ```bash
+   node <main-repo>/.agents/scripts/slice-phase.js \
+     --epic <epicId> --slice slice-<n> --event start --slice-index <n-1> --title "<slice label>"
+   ```
+
+2. **Implement the slice** on `epic/<id>` in the worktree. Apply the relevant
+   [skills](../../instructions.md) and local-lens concerns for the slice's
+   footprint. You do **NOT** run a per-step `slice.heartbeat` CLI (Epic
+   #4476): once `--event start` armed the active-slice env, the PostToolUse
+   hook emits a throttled `slice.heartbeat` off the token stream as a free
+   byproduct of every tool call, so the `/deliver` §2e Idle Watchdog can tell
+   this one long session from a dead one without a dedicated bookkeeping turn.
+   (The `slice-phase.js --event heartbeat` CLI remains available for an
+   explicit beat if you deliberately want one, e.g. a long non-tool wait.)
+
+3. **Commit** the slice to `epic/<id>` before the next slice
+   (conventional subject, `(refs #<epicId>)`). Run the advisory quick gates
+   (`lint`, `typecheck`) while iterating so drift surfaces early.
+
+4. **Flip the marker + close the slice.** After the commit lands, flip the
+   checkpoint marker `pending → done` and emit `slice.end`:
+
+   ```bash
+   node <main-repo>/.agents/scripts/slice-phase.js \
+     --epic <epicId> --slice slice-<n> --event end --outcome done --record done
+   ```
+
+   (`--record done` splices `slices[slice-<n>].status = "done"` via
+   [`recordSliceStatus`](../../scripts/lib/orchestration/epic-run-state-store.js)
+   so a resumed run skips this slice.)
+
+If a slice cannot be completed, emit `slice.end --outcome blocked
+--record blocked`, post a friction comment, flip the Epic to `agent::blocked`,
+and park.
+
+When every slice is `done`, proceed to S2a.
+
+---
+
+## S2a — Per-AC-cluster acceptance critics (the acceptance-dilution guard)
+
+**This is the load-bearing risk mitigation.** In the fan-out shape each Story
+ran its own fresh-context acceptance self-eval critic, so acceptance coverage
+was distributed across the Story tree for free. Collapsing to one session would
+degrade that to two redraft rounds scoring every AC at once — the "acceptance
+dilution" risk the design calls out as blocking. The fix restores the
+distributed critic count.
+
+1. **Cluster the ACs.** Parse the Epic body's `## Acceptance Table` AC ids
+   (`AC-<n>`), ordered by their associated Delivery-Slicing slice, then split
+   into clusters of at most `delivery.acceptanceEval.clusterCeiling` (default
+   **4**, hard-clamped to `[1, 8]`) via
+   [`clusterAcceptanceCriteria`](../../scripts/lib/orchestration/acceptance-clusters.js).
+   The result is **exactly `ceil(totalACs / clusterCeiling)`** clusters — the
+   fan-out width.
+
+2. **One maker-blind critic per cluster.** For **each** cluster author **one**
+   maker-blind verdict — NOT a continuation of your implementing turn, so the
+   critic does not grade its own homework. There MUST be
+   **exactly `ceil(totalACs / clusterCeiling)`** critic passes — **one per
+   cluster** — never a single critic over all ACs (that is the collapse this
+   guard forecloses). Each critic runs the shared
+   [`acceptance-self-eval.md`](acceptance-self-eval.md) mechanic scoped to its
+   cluster: it scores **that cluster's ACs** against the cumulative
+   `git diff main...epic/<epicId>` diff (plus any `verify[]` evidence the ACs
+   reference) and writes a verdict file under `temp/` conforming to
+   [`acceptance-eval-verdict.schema.json`](../../schemas/acceptance-eval-verdict.schema.json).
+
+   > **Fresh-vs-inline is risk-routed PER CLUSTER — the count is fixed
+   > (Epic #4478, M7-B).** Whether a given cluster's critic runs as a
+   > fresh-context spawn or inline is resolved per cluster by
+   > `resolveCeremonyForRisk`
+   > ([`ceremony-routing.js`](../../scripts/lib/orchestration/ceremony-routing.js))
+   > from the Epic's `planningRisk.overallLevel` and
+   > `delivery.routing.freshCriticSampleRate`: **`high`/`medium` → fresh spawn**,
+   > **`low` → inline** (except the sampling-floor fraction forced fresh),
+   > **missing/unknown → fresh + full ceremony**. This is **strictly** a
+   > fresh-vs-inline choice **per cluster**: the number of clusters — hence the
+   > number of critic passes and verdicts — stays **exactly**
+   > `ceil(totalACs / clusterCeiling)` under **every** risk level. Risk routing
+   > NEVER re-slices, merges, or drops a cluster.
+   >
+   > - **Fresh** → emit a **separate** `Agent` tool call
+   >   (`subagent_type: acceptance-critic` when
+   >   `delivery.routing.roleScopedAgents` is on — the default — else
+   >   `general-purpose`), maker-blind, scoped to that cluster's ACs.
+   > - **Inline** → author that cluster's verdict inline in a deliberately
+   >   scoped self-critical pass (re-read only the diff + that cluster's ACs,
+   >   treat the implementation reasoning as untrusted). The gate, schema, and
+   >   proceed/redraft/block decision are identical.
+   > - **Nesting-absent fallback.** If the host cannot spawn a nested `Agent` at
+   >   this depth at all, author **every** cluster's verdict inline regardless of
+   >   the risk verdict. Note the fallback in any block/friction comment.
+
+3. **Gate each cluster (Epic-scoped).** Run the gate per cluster:
+
+   ```bash
+   node <main-repo>/.agents/scripts/acceptance-eval.js \
+     --epic <epicId> --cluster <clusterId> --verdict <verdict-path>
+   ```
+
+   The Epic-scoped invocation (no `--story`) scopes the redraft-round count
+   **per cluster** off the Epic's `signals.ndjson`. It exits:
+   - **`proceed`** (every AC in the cluster `met`) → this cluster is clear.
+   - **`redraft`** (some `partial`/`unmet`, rounds remain) → redraft the
+     flagged ACs on `epic/<id>`, commit, and re-run this cluster's critic.
+   - **`block`** (round cap reached, ACs still unmet) → exit non-zero. **STOP
+     the whole run.** Flip the Epic to `agent::blocked` and post a friction
+     comment naming the unmet ACs (with their cluster) and their evidence.
+     **Never proceed to close (S2b) with any cluster blocked.**
+
+4. Only when **every** cluster returns `proceed` do you proceed to S2b.
+
+---
+
+## S2b — Hand off to deliver-epic.md Phase 3 (merge tail, reused unchanged)
+
+Everything downstream of the acceptance gate is Epic-scope and reused
+**byte-for-byte** — there is exactly one home for the merge machinery. Continue
+at [`deliver-epic.md`](deliver-epic.md) **Phase 3** and run **Phases 3–9
+verbatim**:
+
+- Phase 3 — close-validation (lint + test + ratchets on `epic/<id>`)
+- Phase 4 — epic-close lens roster
+- Phase 5 — code-review (the ONE maker-blind cumulative-diff review — the
+  north-star's "review is a fresh-context critic")
+- Phase 6 — retro
+- Phase 6.5 — integration gate
+- Phase 7 — finalize (branch-sync → `epic.close.end` → reconcile → open PR)
+- Phase 8 — watch-and-iterate to green CI
+- Phase 8.5 — auto-merge gate
+- Phase 9 — cleanup
+
+Do **not** copy those phases here. Read `deliver-epic.md` from Phase 3 and run
+them exactly as the fan-out route does — they never touch a Story ticket, so
+they compose unchanged over the slice-walked `epic/<id>` branch.
+
+### Non-waivable acceptance reconcile
+
+Phase 7's `epic.close.end` fires the bus-owned `AcceptanceReconciler`. Under
+single delivery this listener is **non-waivable** (design §2c, the back gate):
+[`acceptance-reconciler.js`](../../scripts/lib/orchestration/lifecycle/listeners/acceptance-reconciler.js)
+resolves the delivery shape (off `epic-run-state.deliveryShape` or the
+`delivery::single` label) and treats a `status: "waived"` reconcile as
+**`failed`** (`acceptance.reconcile.failed` → `epic.blocked`) instead of
+passing it through. Combined with the S1 front gate (prepare refusing
+`acceptance::n-a`), this structurally forecloses shipping a single Epic with
+its sole acceptance gate waived.
+
+---
+
+## Idempotence and resume
+
+Re-runs resume from the slice map: `done` slices are skipped, `pending` slices
+resume in order. The per-cluster acceptance signals on the Epic stream let a
+resumed run pick up the correct redraft round per cluster. The PR from Phase 7
+is updated in place. `slice.start` / `slice.end` / `slice.heartbeat` on the
+ledger give the resume path and the idle watchdog an inspectable forward-
+progress signal for the single long session.
+
+---
+
+## Constraints
+
+- **Never** fan out `Agent` calls for slice implementation — the slice walk is
+  in-session. The only `Agent` spawns are the S2a maker-blind acceptance
+  critics (read-only), and only for clusters the risk router sends `fresh`.
+- **Never** dereference, enumerate, or transition a `type::story` ticket —
+  this path has none.
+- **Never** collapse the S2a critics to fewer than
+  `ceil(totalACs / clusterCeiling)` **critic passes** — one maker-blind verdict
+  per cluster (fresh spawn or inline; the risk router chooses the mode, never
+  the count) — and **never** proceed to S2b with a blocked cluster.
+- **Never** merge `epic/<epicId>` to `main` outside Phase 8.5 — the merge tail
+  is `deliver-epic.md`'s, unchanged.
+- **Always** flip the slice marker `→ done` after each slice commits, and
+  **always** post a friction comment before any non-`complete` outcome.
+
+## See also
+
+- [`deliver.md`](../deliver.md) — the router that dispatches here.
+- [`deliver-epic.md`](deliver-epic.md) — the fan-out path; its Phases 3–9 are
+  this helper's merge tail.
+- [`acceptance-self-eval.md`](acceptance-self-eval.md) — the per-cluster critic
+  mechanic.

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

@@ -105,7 +105,9 @@ Every other runtime modifier is sourced from the Epic's labels or from
   clarifying questions — if stuck, flip to `agent::blocked`, post a
   friction comment, park.
 - **Flat Story dispatch by design.** Host LLM fans out per-Story Agent
-  calls directly with `subagent_type: general-purpose`. Keeping Story
+  calls directly — with `subagent_type: story-worker` when
+  `delivery.routing.roleScopedAgents` is on (the default; § 2b), else
+  `general-purpose`. Keeping Story
   dispatch flat — the host owns the single fan-out level — is a
   **design choice**, not a harness constraint: the wave aggregator, idle
   watchdog, and merge-lock all assume one host-owned dispatch level. As of
@@ -338,8 +340,18 @@ span-tree view.
 `helpers/epic-deliver-story` yourself. Emit **one `Agent` tool call per
 Story** in `nextAction.stories` (even when `length === 1` — the
 parent-child boundary keeps the return-parser uniform). The *children*
-run [`helpers/epic-deliver-story`](epic-deliver-story.md). Use
-`subagent_type: general-purpose`.
+run [`helpers/epic-deliver-story`](epic-deliver-story.md).
+
+**Sub-agent type (Epic #4478, M7-B).** When
+`delivery.routing.roleScopedAgents` is enabled (the **default**), each Story
+child is dispatched with `subagent_type: story-worker` — it boots on the
+role-scoped [`story-worker`](../../agents/story-worker.md) context (its own
+system prompt, no `CLAUDE.md` @-closure) that carries every load-bearing
+delivery MUST standalone, so the spawn stops re-paying the always-loaded
+context. When the kill-switch is **off**
+(`delivery.routing.roleScopedAgents: false`), fall back to
+`subagent_type: general-purpose` — the instant, code-rollback-free revert and
+the escape for hosts that ignore `.claude/agents/`.
 
 Emit **one assistant turn** with **N parallel `Agent` calls** where
 `N === nextAction.stories.length` (the ready set is already capped at
@@ -388,11 +400,15 @@ 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
+`story-phase.js` CLI upserts, not in a verbatim body dump, (5) remind the
+child that its `story.heartbeat` liveness signal is emitted **off the token
+stream** by the PostToolUse hook (Epic #4476) — a throttled heartbeat lands as
+a free byproduct of every tool call, keyed off the active-Story env
+`story-init.js` exported — so it does **not** run `story-phase.js` per step
+just to heartbeat (a `story-phase.js` call at a genuine Story-level phase
+transition still renders the snapshot and stamps an operator-bearing
+heartbeat), and if it cannot make progress it must 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
@@ -730,6 +746,33 @@ accessor (default `true`); do not read `delivery.ci.earlyPr` directly.
 In both modes the PR title/body contract (`feat: Epic #<epicId>` /
 `Closes #<epicId>`) is identical.
 
+**Drain the bookkeeping outbox (Epic #4476 M5).** When this run was invoked
+with `--yes` (headless), the mechanical bookkeeping — non-urgent
+structured-comment upserts and intermediate `agent::*` label flips — was
+**buffered to a local per-Epic outbox** instead of posting live per
+transition (see the box below). Reconcile it to GitHub once, now, after the PR
+is open:
+
+```bash
+node .agents/scripts/bookkeeping-reconcile.js --epic <epicId>
+```
+
+This drains `temp/epic-<epicId>/bookkeeping-outbox.ndjson` (FIFO,
+idempotent) so GitHub is the source of truth at rest. It exits non-zero and
+**retains** the outbox if any op fails (crash-recovery: a later reconcile
+re-drains the remainder). Attended runs buffered nothing, so this is a no-op.
+
+> **Headless buffering, not silence (§1.H / §1.J).** In `--yes` mode the
+> comment/label CLIs accept `--buffer --epic <epicId>` to enqueue a mutation
+> instead of a live round-trip
+> ([`post-structured-comment.js`](../../scripts/post-structured-comment.js),
+> [`update-ticket-state.js`](../../scripts/update-ticket-state.js)). The
+> `agent::blocked` HITL gate is **never** buffered — a genuine blocker flips
+> the label live and immediately, exactly as before, so the operator can see
+> and resume it. `agent::done` is also never buffered (its cascade runs live).
+> Attended runs pass no `--buffer` and behave byte-for-byte as they always
+> have.
+
 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

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

@@ -249,7 +249,17 @@ Each Agent call:
 4. Requests the child suppress per-phase chat relay and include its
    **terminal** `renderedBody` in the JSON return.
 
-Use `subagent_type: general-purpose`.
+**Sub-agent type (Epic #4478, M7-B).** When `delivery.routing.roleScopedAgents`
+is enabled (the **default**), dispatch each Story child with
+`subagent_type: story-worker` — it boots on the role-scoped
+[`story-worker`](../../agents/story-worker.md) context (its own system prompt,
+no `CLAUDE.md` @-closure) which carries every load-bearing delivery MUST
+standalone, so the spawn stops re-paying the always-loaded context. When the
+kill-switch is **off** (`delivery.routing.roleScopedAgents: false`), fall back
+to `subagent_type: general-purpose` — the instant, code-rollback-free revert and
+the universal escape for hosts that ignore `.claude/agents/`. The child still
+runs [`helpers/epic-deliver-story`](epic-deliver-story.md) either way; only the
+boot context differs.
 
 ### 2b′. Collect each return and re-tick
 
@@ -376,10 +386,10 @@ Story's suite is green and the close-validation gates already pass — and
 key is unset or `false`, story-deliver behaves exactly as documented above
 and this stage is skipped entirely.
 
-The stage adopts the [`refactorer`](../../personas/refactorer.md) persona and the
-[`core/refactoring-discipline`](../../skills/core/refactoring-discipline/SKILL.md)
-skill to drive a behaviour-preserving pass that lowers CRAP and removes
-duplication on the files the Story already touched:
+The stage applies the post-green refactor discipline in
+[`core/code-review-and-quality`](../../skills/core/code-review-and-quality/SKILL.md)
+(§ Post-Green Refactor Pass) to drive a behaviour-preserving pass that lowers
+CRAP and removes duplication on the files the Story already touched:
 
 - **Post-green only.** It runs after the suite is green and the gates pass —
   never from red, and never to make a failing test pass.

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

@@ -13,9 +13,10 @@ caller: epic-deliver.md
 
 > **Not a slash command.** This file lives in `helpers/` and is not projected
 > into the mandrel plugin command tree. It is invoked exclusively by the
-> [`/deliver`](deliver-epic.md) per-wave fan-out via an `Agent` tool
-> call (`subagent_type: general-purpose`). Run `/deliver <epicId>` from
-> the operator surface, not this helper directly.
+> [`/deliver`](deliver-epic.md) per-wave fan-out via an `Agent` tool call —
+> `subagent_type: story-worker` when `delivery.routing.roleScopedAgents` is on
+> (the default), else `subagent_type: general-purpose` (Epic #4478, M7-B). Run
+> `/deliver <epicId>` from the operator surface, not this helper directly.
 
 ## Overview
 
@@ -161,6 +162,14 @@ Run a single Story-implementation phase against the inline `acceptance[]`
      --phase implementing
    ```
 
+   > **Liveness between transitions is free (Epic #4476).** These
+   > `story-phase.js` calls fire only at genuine phase transitions (a few per
+   > Story) and each renders the snapshot + stamps an operator-bearing
+   > `story.heartbeat`. You do **not** add extra `story-phase.js` calls
+   > mid-`implementing` just to prove you are alive: the PostToolUse hook emits
+   > a throttled `story.heartbeat` off the token stream on every tool call, so
+   > the §2e Idle Watchdog sees continuous forward progress for free.
+
 2. Read the Story body's inline `acceptance[]` and `verify[]` arrays
    from the `story-init` structured comment (`context.acceptance`,
    `context.verify`). Treat the acceptance items as the contract and

package/.agents/workflows/helpers/mandrel-sync-config.md

@@ -55,7 +55,7 @@ keeps that file aligned with the schema and the runtime accessors so the
 > `applyDefaults`. Writing those defaults into `.agentrc.json` only bloats
 > the consumer repo's config diff without changing runtime behaviour.
 >
-> **Persona**: `devops-engineer` · **Skills**: `core/ci-cd-and-automation`,
+> **Persona**: `devops-engineer` · **Skills**: `core/gates-and-baselines`,
 > `core/documentation-and-adrs`
 
 ## Procedure

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

@@ -189,31 +189,33 @@ markdown joins the same batch). Never write them one-per-turn.
 
 ### Conditional critics (between authoring and gate #2)
 
-The evaluation is folded into `plan-persist.js` as a deterministic
-pre-write phase (#4496 fix 6) — the persist prints both verdicts, returns
-them on its result envelope, and ledger-logs every skip. **Attended runs**
-evaluate the dispatch conditions before gate #2 so the verdicts fold into
-its view — one git-local CLI call, zero GitHub reads, via the thin shim
-(kept one release over the shared evaluator):
-
-```bash
-node .agents/scripts/plan-critics.js --epic [Epic_ID]
-```
-
-(ideation: pass `--tech-spec`/`--risk-verdict`/`--tickets` explicitly). The
-verdict names each critic with `dispatch: true|false` and reasons. Dispatch
-a sub-agent ONLY for a critic with `dispatch: true`; surface each skip as a
-one-line note. Every skip decision is appended to the plan-metrics ledger
-(`kind: "critic-skip"`, with reasons) so under-firing is auditable — the
+The dispatch decision is a **deterministic** function of the authored
+artifacts, evaluated in exactly one place — the evaluation is
+folded into `plan-persist.js` as a deterministic pre-write phase
+(#4496 fix 6). The persist prints both verdicts, returns them on its
+result envelope, and ledger-logs every skip: that fold is the
+single authoritative record, headless or attended. **Attended runs**
+apply the same deterministic conditions (below) to the authored
+artifacts before gate #2 so a `dispatch: true` critic runs and its
+findings fold into the gate's view; the persist fold then re-checks
+and ledger-logs the identical verdict. No separate CLI turn and zero
+GitHub reads — the conditions are mechanical thresholds over
+`techspec.md` / `risk-verdict.json` / `tickets.json`, and are
+never judged inline as an opinion. The verdict names each critic
+with `dispatch: true|false` and reasons.
+
+For each critic whose conditions hold (`dispatch: true`), dispatch a
+sub-agent; surface each skip as a one-line note. Every skip decision
+is appended to the plan-metrics ledger (`kind: "critic-skip"`, with
+reasons) so under-firing is auditable — the
 persist validators remain unchanged hard gates either way.
 
-> **`--yes` (headless).** Do **not** run the standalone CLI and do **not**
-> dispatch critic sub-agents: the critics' findings would fold into a gate
-> that auto-proceeds, so a report nobody reviews is pure spend. The
-> persist's folded pre-write evaluation is the audit record — its verdicts
-> print in the persist output, a `dispatch: true` verdict surfaces as a
-> one-line advisory note in the run summary, and every skip still lands on
-> the plan-metrics ledger.
+> **`--yes` (headless).** Do **not** dispatch critic sub-agents: the
+> critics' findings would fold into a gate that auto-proceeds, so a report
+> nobody reviews is pure spend. The persist's folded pre-write evaluation is
+> the audit record — its verdicts print in the persist output, a
+> `dispatch: true` verdict surfaces as a one-line advisory note in the run
+> summary, and every skip still lands on the plan-metrics ledger.
 
 Both critics are **fresh-context sub-agents** (`Agent` tool,
 `subagent_type: general-purpose`) — never inline skill activations, so they

package/.agents/workflows/mandrel-update.md

@@ -32,7 +32,7 @@ generated `.claude/commands/` tree is
 the CLI's sync step.
 
 > **Persona**: `devops-engineer` · **Skills**:
-> `core/ci-cd-and-automation`, `core/documentation-and-adrs`
+> `core/gates-and-baselines`, `core/documentation-and-adrs`
 
 ## Step 0 — Detect the install state and pick the invocation form
 

package/docs/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.94.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.93.0...mandrel-v1.94.0) (2026-07-13)
+
+
+### Added
+
+* context diet — extract instructions core + inert role-agent scaffolding (refs [#4478](https://github.com/dsj1984/mandrel/issues/4478)) ([#4509](https://github.com/dsj1984/mandrel/issues/4509)) ([2796e57](https://github.com/dsj1984/mandrel/commit/2796e57b7a0fb0a0651b1e184d6945546b9da22c))
+* **deliver:** move bookkeeping off the token stream — hook heartbeats + buffered finalize sync ([#4476](https://github.com/dsj1984/mandrel/issues/4476)) ([#4508](https://github.com/dsj1984/mandrel/issues/4508)) ([378da81](https://github.com/dsj1984/mandrel/commit/378da818e18f4b09aa9380a4413b753748661aa2))
+* **deliver:** single-delivery executor as the live default (refs [#4475](https://github.com/dsj1984/mandrel/issues/4475)) ([#4503](https://github.com/dsj1984/mandrel/issues/4503)) ([c532d41](https://github.com/dsj1984/mandrel/commit/c532d412f785c212223a3ac9af08fce7dad284aa))
+* **deliver:** single-delivery routing + kill-switch + prepare --single (refs [#4475](https://github.com/dsj1984/mandrel/issues/4475)) ([#4501](https://github.com/dsj1984/mandrel/issues/4501)) ([b481caf](https://github.com/dsj1984/mandrel/commit/b481cafc618a78b80d099cf697e2c094544835b6))
+* flip role-scoped spawns behind kill-switch + risk-routed ceremony (refs [#4478](https://github.com/dsj1984/mandrel/issues/4478)) ([#4510](https://github.com/dsj1984/mandrel/issues/4510)) ([adb9d52](https://github.com/dsj1984/mandrel/commit/adb9d52d7c7be213d32afbe86ec2edad88e01619))
+
+
+### Fixed
+
+* **close-validate:** probe the check-baselines consumer contract before failing (refs [#4495](https://github.com/dsj1984/mandrel/issues/4495)) ([#4499](https://github.com/dsj1984/mandrel/issues/4499)) ([49b430f](https://github.com/dsj1984/mandrel/commit/49b430fe2811000b69e97201efc83bff64651726))
+
 ## [1.93.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.92.0...mandrel-v1.93.0) (2026-07-12)