mandrel 2.39.0 → 2.40.0

package/.agents/templates/docs/audit-sweep-runbook.md

@@ -0,0 +1,169 @@
+# Audit sweep runbook
+
+> **Template generated by Mandrel.** Copy it into your own docs tree (e.g.
+> `docs/audit-sweep-runbook.md`), then localise every bracketed placeholder:
+> the cadence, the lens list, who reviews the ledger PR, and the label
+> conventions your repository actually uses. The steps themselves are the
+> contract — the values around them are yours.
+>
+> The workflow this runbook drives is
+> [`/audit-to-stories`](../../workflows/audit-to-stories.md); the CLI it calls
+> is [`audit-to-stories.js`](../../scripts/audit-to-stories.js). Run the CLI
+> with `--help` for the authoritative flag list.
+
+## What this runbook is for
+
+A maintenance **sweep** runs the `audit-*` lenses full-scope, folds their
+findings onto the cross-run ledger, and turns what is genuinely new into
+Stories. It is the unattended sibling of an interactive `/audit-to-stories`
+run: no HITL gates, so every judgement call the interactive path asks a human
+has to be settled here instead.
+
+| Setting | Value for this repository |
+| --- | --- |
+| Cadence | _e.g. weekly, Sunday 02:00_ |
+| Lenses in scope | _e.g. security, clean-code, quality, dependencies_ |
+| Severity floor | _`delivery.auditToStories.severityFloor`, default `high`_ |
+| Ledger reviewer | _e.g. @your-handle_ |
+| Story triage owner | _e.g. the on-call maintainer_ |
+
+## Step 1 — Run the lenses full-scope
+
+Run each `audit-*` workflow with **no** `--paths` and no change-set filter, so
+the whole target-set union is audited rather than whatever a recent branch
+happened to touch. Each lens writes its report to
+`temp/audits/audit-<lens>-results.md`.
+
+A sweep scoped to a change set is not a sweep: it re-reports the same recent
+files every cycle and never reaches the code nobody has touched in a year,
+which is exactly where audit findings accumulate.
+
+## Step 2 — Cross-check the severity tally
+
+Every lens report ends its executive summary with a machine-readable line:
+
+```text
+Severity tally: Critical 0 / High 3 / Medium 7 / Low 2
+```
+
+The CLI re-counts the `### Finding` blocks it actually parsed and compares them
+to that declared tally. A mismatch — or a missing tally line — means the report
+is not trustworthy: a finding was malformed, a severity did not resolve onto the
+canonical scale, or the lens truncated its own output.
+
+`--auto` **fails closed** on any such failure. It exits non-zero having opened
+no Issue and written no ledger, and names the offending report in
+`summary.reportFailures[]`. `--allow-missing-tally` is a `--scan` affordance
+only; `--auto` ignores it by design, because an unattended run has no operator
+to read a warning.
+
+**When the sweep goes red here, re-run the lens.** Do not reach for
+`--allow-missing-tally` and do not hand-edit the report to make the numbers
+agree — the tally is the only signal that the parse saw what the lens wrote.
+
+## Step 3 — Dry-run the first cycles
+
+Start every new sweep in report-only mode, and stay there until the tallies
+stop surprising you:
+
+```bash
+node .agents/scripts/audit-to-stories.js --auto --dry-run
+```
+
+`--dry-run` performs zero GitHub writes and skips the ledger write, printing
+only the run summary. Read `totals.create` before you let the sweep file
+anything: a first full-scope run over an un-audited repository can propose more
+Stories than your team can triage in a quarter. Raise `--severity` (or
+`delivery.auditToStories.severityFloor`) until the create count is a batch you
+would actually take on, then go live.
+
+## Step 4 — Go live, and persist the ledger
+
+```bash
+node .agents/scripts/audit-to-stories.js --auto --ledger-commit
+```
+
+The cross-run ledger (`baselines/audit-ledger.json`) is **consumer state, not
+scratch output**. It is what lets the next sweep tell a re-detection from a
+fresh finding, and a deliberately-rejected finding from an unseen one. A
+scheduled job normally runs on an ephemeral checkout, so unless the ledger is
+committed back it dies with the clone and every later sweep starts amnesiac —
+re-proposing findings already filed and re-surfacing findings a human already
+rejected.
+
+`--ledger-commit` closes that loop. After the run summary has printed, and only
+when the ledger actually changed, it:
+
+1. creates `chore/audit-ledger-<YYYY-MM-DD>` from the current HEAD,
+2. commits **only** the ledger file, subject
+   `chore(audit): reconcile audit ledger <date>`,
+3. pushes the branch, and
+4. opens a PR against your base branch.
+
+**Auto-merge is never requested.** The ledger records machine-derived lifecycle
+state, so a human glance before it lands is the point — nominate that reviewer
+in the table above. Review the PR for entries flipping to `accepted-risk` or
+`regressed`; those two are the ledger telling you something about your backlog,
+not about itself.
+
+Any git or `gh` failure in that sequence is fatal and names the step it broke
+on — but it happens _after_ the summary is printed, so a broken remote never
+costs you the sweep's findings.
+
+Without the flag, a run whose ledger changed on a checkout that cannot persist
+it — no `origin` remote, or HEAD parked off the base branch — sets
+`ledger.unpersisted: true` in the summary and warns on stderr naming the file.
+Treat that warning as a red sweep: the findings are fine, but the memory is
+about to be thrown away.
+
+## Step 5 — Enrich before you deliver
+
+`--emit-stories` renders `{ title, body, labels }` payloads from audit findings.
+Those bodies are **audit prose**, not delivery-ready Specs: they describe a
+symptom and a recommendation, not a scoped change with acceptance criteria a
+worker can verify against.
+
+Do not point `/mandrel-deliver` at a freshly-filed audit Story. Route it through
+`/mandrel-plan` first — the planning pass is where the finding becomes a
+capability slice with a `## Spec`, real `acceptance[]` items and runnable
+`verify[]` lines. Planning is deliberately not automated here: deciding what a
+finding is worth, and how far the fix should reach, is the judgement the sweep
+exists to surface rather than to make.
+
+The wiring pass is the exception — it _is_ mechanical and it is **required**.
+After opening the Issues, replay their numbers through `--wire-edges` so the
+cohort's declared ordering exists as `blocked by #N` footers and native
+`blocked_by` relations. An unwired cohort is genuinely unordered, and
+`/mandrel-deliver` will co-dispatch Stories the edges say must follow one
+another.
+
+## Step 6 — Label convention
+
+Audit-sourced Stories carry a closed label set, so they can be filtered out of
+(or into) ordinary planning at a glance:
+
+| Label | Meaning |
+| --- | --- |
+| `type::story` | Every emitted Story — the sweep never opens Epics or tasks. |
+| `agent::ready` | Filed and available for pickup. |
+| `audit::<lens>` | One per lens represented in the group; a cross-audit merge carries several. |
+| `risk::high` | Added when any finding in the group is Critical. |
+
+The lens labels are a **closed taxonomy**: only the canonical `audit::<lens>`
+names are valid, and the filer refuses to emit a label the repository has never
+created. Create them once with `audit-labels-bootstrap.js` before the first live
+sweep — a generated label that does not exist makes every Issue create fail.
+
+Do not invent per-finding labels. If you need another axis (a team, a
+component), add it in triage on top of this set rather than teaching the sweep
+to mint labels no taxonomy defines.
+
+## Failure triage
+
+| Symptom | Cause | Action |
+| --- | --- | --- |
+| Non-zero exit, `summary.reportFailures[]` populated | A lens report's tally is missing or disagrees with the parse | Re-run that lens; never downgrade with `--allow-missing-tally` |
+| `ledger.unpersisted: true` in the summary | No `origin`, or HEAD off the base branch | Re-run with `--ledger-commit`, or commit the ledger by hand |
+| `--ledger-commit failed at step "..."` | git or `gh` failed at the named step | Fix the remote/auth and re-run; the summary above it is still valid |
+| Same findings re-proposed every cycle | The ledger is not being committed | Adopt Step 4 |
+| `totals.create` far larger than the team can absorb | Severity floor too low for a first full-scope run | Raise `--severity` and re-dry-run |

package/.agents/workflows/audit-to-stories.md

@@ -44,10 +44,12 @@ They remain read-only emitters of audit reports.
 ## Phase 1 — Discover & parse
 
 Run the CLI in `--scan` mode against the resolved glob. It parses every
-`### Finding` block, normalises the fields (`Severity` / `Impact` are
+finding block, normalises the fields (`Severity` / `Impact` are
 both recognised; `Dimension` / `Category` likewise), and extracts file
-paths mentioned in the body. It then stamps each finding with a stable
-sha1 fingerprint via the shared
+paths mentioned in the body. A `###` heading that carries no severity axis and
+holds `####` blocks is read as a **grouping header**: its `####` children are
+the findings, and the header itself never becomes one. It then stamps each
+finding with a stable sha1 fingerprint via the shared
 [`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)
 helper (`fingerprintFinding`) — the single dedup/route implementation
 shared with `qa-explore`. The workflow carries **no** separate inline
@@ -64,6 +66,19 @@ The emitted plan envelope carries `findings`, `groups`, `edges`,
 `classifications`, and `summary`. Subsequent phases consume the file
 rather than re-parsing the reports.
 
+**The tally cross-check is automatic.** Every report declares
+`Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>` in its
+Executive Summary; the scan compares that line with what it parsed and carries
+each disagreement on `summary.reportFailures[]` as
+`{ sourceReport, kind, reported, parsed }`. The kinds are `missing-tally` (no
+line), `tally-mismatch` (line and parse disagree), and `unresolved-severity` (a
+finding whose severity did not resolve — dropped from grouping, never filed as
+an `unknown` group). They print to stderr before `--scan` returns its plan, so
+a mis-parsed report is never read as a clean audit: re-run the lens rather than
+file from it. Over older reports predating the mandate,
+`--scan --allow-missing-tally` downgrades **only** `missing-tally` to a
+warning.
+
 ## Phase 2 — HITL: severity gate
 
 Read the plan envelope's `summary.tally`. Present the operator with the
@@ -117,6 +132,11 @@ Ask:
 >   default-single policy.
 > - **Individual standalone Stories** — opens one GitHub Issue per
 >   group directly (no plan ceremony).
+>
+> Either way, if the sweep proposes **more than 2** Stories they are grouped
+> under a **container Epic** by default — a title, a one-paragraph goal and a
+> child checklist, carrying nothing a child does not already carry. Say so if
+> you would rather file them flat.
 
 **STOP** until the operator picks.
 
@@ -133,7 +153,14 @@ node .agents/scripts/audit-to-stories.js --emit-plan-seed \
 The seed renders the canonical one-pager sections — Problem Statement,
 Recommended Direction, Key Assumptions (with links to every source
 report), MVP Scope (the M proposed Stories), Key Files (so `/mandrel-plan`'s
-authoring step has concrete anchors), Not Doing.
+authoring step has concrete anchors), Grouping, Not Doing.
+
+**Grouping is the container-Epic directive.** Above 2 proposed Stories the
+seed instructs `/mandrel-plan` to group them under one Epic — a sweep is the
+clearest case for a container, since every Story shares a provenance and an
+operator usually delivers them together. It is a directive in the text, not an
+automatic write: Phase 4 above is where an operator declines it. Below the
+threshold the section says so and asks for nothing.
 
 Chain into the existing planning entrypoint:
 
@@ -215,6 +242,14 @@ its footprint guard ignores the shared provenance footers, so an unwired cohort
 is genuinely unordered and `/mandrel-deliver` will co-dispatch Stories the edges say
 must follow one another.
 
+**Preconditions.** The pass writes through the configured provider, so it needs
+`github.owner` **and** `github.repo` in `.agentrc.json` plus working `gh` auth
+(`GH_TOKEN`/`gh auth status`) — the same two things Phase 1's dedup needs. When
+either is missing the command refuses and names which one; fix that and re-run
+the exact command above. Do not transcribe the footers by hand: `/mandrel-deliver`
+reads them, but the native `blocked_by` relations only exist if this pass wrote
+them.
+
 ## Phase 6 — Idempotency (folded into Phase 1 scan)
 
 The `--scan` step routes each group's findings through the shared
@@ -289,6 +324,8 @@ summarising the run:
 
 When the single-plan path ran, link the Story (or plan-run) the chained
 `/mandrel-plan` opened. When the Standalone-Stories path ran, list every Issue URL.
+Either way, name the container Epic if one was created — it is the single id
+that delivers the whole sweep (`/mandrel-deliver <epicId>`).
 
 ## Constraints
 
@@ -330,18 +367,59 @@ writing their `temp/audits/audit-*-results.md` reports, then (2) invokes the
 CLI's **`--auto` mode** over those results:
 
 ```bash
-node .agents/scripts/audit-to-stories.js --auto [--dry-run] \
+node .agents/scripts/audit-to-stories.js --auto [--dry-run] [--ledger-commit] \
   [--glob "temp/audits/audit-*-results.md"] [--severity <floor>]
 ```
 
+The routine shape is **lenses full-scope → dry-run → live with a ledger PR**:
+
+1. Run the `audit-*` lenses with no `--paths` and no change-set filter. A
+   sweep scoped to a change set re-reports the same recent files every cycle
+   and never reaches the untouched code where findings accumulate.
+2. `--auto --dry-run` for the first cycles — zero writes, summary only. Read
+   `totals.create` and raise the severity floor until it is a batch the team
+   would actually take on.
+3. `--auto --ledger-commit` once the tallies stop surprising you.
+
 `--auto` runs with **no interactive gates**: it resolves the severity floor
 from `delivery.auditToStories.severityFloor` (default `high`, overridable with
 `--severity`), applies the two-stage dedup, reconciles the cross-run ledger,
 and prints a run-summary JSON (create / skip-open / skip-reoccurring /
 suppressed-by-ledger tallies, plus the re-detected open Issue numbers an
 operator may want a "re-detected" comment on). `--dry-run` performs zero GitHub
-writes and skips the ledger write, emitting only the summary. The host
-scheduler owns the cadence; this workflow owns the routing.
+writes and skips the ledger write, emitting only the summary.
+
+`--auto` **fails closed on any `summary.reportFailures[]` entry** (Phase 1): an
+unattended sweep has no operator to read a warning, so a missing or mismatched
+`Severity tally:` line — or a finding whose severity did not resolve — exits
+non-zero having opened no Issue and written no ledger. `--allow-missing-tally`
+is a `--scan` affordance that `--auto` ignores. A red sweep means the report is
+untrustworthy: re-run the lens. The host scheduler owns the cadence; this
+workflow owns the routing.
+
+### The ledger is consumer state — commit it
+
+`baselines/audit-ledger.json` is **committed consumer state, not scratch
+output**. A scheduled sweep normally runs on an ephemeral checkout, so unless
+the reconciled ledger is committed back it dies with the clone: every later
+sweep starts amnesiac, re-proposing findings already filed and re-surfacing
+findings a human already rejected.
+
+`--ledger-commit` closes that loop. After the summary prints — and only when
+the ledger changed — it creates `chore/audit-ledger-<YYYY-MM-DD>` from HEAD,
+commits **only** the ledger file, pushes it, and opens a PR against
+`project.baseBranch`. **Auto-merge is never requested**: a human glance at the
+`accepted-risk` / `regressed` flips before it lands is the point. A git or `gh`
+failure is fatal and names its step, but only after the summary is printed, so
+a broken remote never costs the operator the run's findings. `--dry-run` skips
+the tail. Without the flag, a changed ledger on a checkout that cannot persist
+it — no `origin`, or HEAD off the base branch — sets `ledger.unpersisted: true`
+in the summary and warns on stderr naming the file.
+
+The full sweep procedure — tally cross-check, the ledger PR, the
+enrich-before-deliver step and the label convention — ships as a
+consumer-copyable template at
+[`templates/docs/audit-sweep-runbook.md`](../templates/docs/audit-sweep-runbook.md).
 
 ## See also
 

package/.agents/workflows/helpers/audit-lens-core.md

@@ -51,7 +51,8 @@ path). The report MUST include every section its lens template mandates — writ
 `_No findings._` rather than omitting a section — and always an
 `## Executive Summary` and a `## Detailed Findings` section. The Executive
 Summary carries the self-cross-check `kept <k> / dropped <d>` line
-([below](#self-cross-check)).
+([below](#self-cross-check)) and, beside it, the machine-readable severity
+tally ([below](#severity-tally)).
 
 Every finding under `## Detailed Findings` uses the shared 7-field skeleton
 below. A lens may **add** fields (e.g. a WCAG success criterion, a CWE ID, a
@@ -64,9 +65,11 @@ drops or renames a shared field.
 ```markdown
 ## Executive Summary
 
-[The lens's headline read plus the self-cross-check `kept <k> / dropped <d>`
-line. A lens may mandate additional report sections between here and the
-findings — its own body names them.]
+[The lens's headline read, the self-cross-check `kept <k> / dropped <d>` line,
+and the severity tally line below. A lens may mandate additional report
+sections between here and the findings — its own body names them.]
+
+Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
 
 ## Detailed Findings
 
@@ -188,6 +191,23 @@ that rests on one of them:
 A lens that keeps every finding still records `dropped 0` — the line's absence
 is itself a defect (it means the pass did not run).
 
+## Severity tally (mandatory, machine-readable) {#severity-tally}
+
+The Executive Summary MUST also carry exactly one tally line, counting the
+findings you kept:
+
+```text
+Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
+```
+
+Write every bucket, zeros included, and never count `Info` — the scale already
+excludes it from scheduled work. This line is the report's own checksum:
+`audit-to-stories --scan` cross-checks it against the findings its parser
+extracted and names any disagreement as a **report failure**
+(`summary.reportFailures[]`), and `--auto` refuses to file anything from a
+report whose line is missing or wrong. A parse that silently drops findings is
+otherwise indistinguishable from a clean audit.
+
 ## Execution strategy {#execution-strategy}
 
 A lens is a self-contained, read-only unit of work — exactly the shape a

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

@@ -292,6 +292,14 @@ This executes, in order:
   (files issues when auto-file is on; posts `follow-ups`).
 - `sibling-coherence` — Spec/Acceptance coherence check across sibling bodies
   (`plan-run-sibling-coherence`).
+- `epic-close` — closes a container Epic once **every** child Story is
+  `agent::done`, as `completed`. This is the only completion cascade v2 has:
+  it closes the container and nothing else — no child status roll-up, no label
+  inheritance, no reopening. Because linkage is parent→child only, the parent
+  is found by scanning open `type::epic` issues, and only an Epic containing
+  one of *this run's* Stories is considered, so an unrelated container is
+  never swept. An Epic with an outstanding child is reported `pending` and
+  left open.
 
 A single-Story run skips the epilogue — follow-ups are captured on merge
 confirm instead (`captureStoryFollowUps`).

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

@@ -414,6 +414,34 @@ That is the whole point of running it first: a dry run that comes back clean
 has already paid for every deterministic refusal, so the real persist has
 nothing left to discover except network failure.
 
+## The container Epic (Gate #3, N>2)
+
+Above two Stories, `/mandrel-plan` offers to group them under one `type::epic`
+container. Confirmed, persist opens it **after** the Stories — its body embeds
+their issue numbers and its sub-issue edges need their database ids — and
+links every created Story both ways it can: a `- [ ] #N` body checklist and a
+native GitHub sub-issue edge. Both are written because each survives what the
+other does not; the delivery-side reader unions them.
+
+What the Epic must never carry: an `agent::*` label (that absence keeps it out
+of the bare `/mandrel-deliver` ready list and outside the `type::story`-scoped
+body lint), a `## Spec`, an `acceptance[]` / `verify[]`, or any path, finding
+or rationale a child does not already hold. It is a container; unique content
+here is content no delivering agent reads.
+
+What the **Stories** never gain is an `Epic: #N` footer. Linkage is
+parent→child only, which is exactly why every existing refusal of that footer
+still stands and each Story stays independently deliverable (ADR
+`20260905-5139`).
+
+Degradation is deliberate: an unensurable `type::epic` label skips the Epic
+entirely (an unlabelled container is not a container), while a failed
+sub-issue edge only warns — the checklist still lists every child. Either way
+the Stories are untouched and deliver by id. A resumed persist adopts an
+existing Epic carrying the same fingerprint, which is keyed on the title **and
+the exact child set**, so a run grouping different Stories never adopts the
+wrong container.
+
 ## Ready means fully persisted
 
 `agent::ready` is the **terminal** step, not part of the creating POST.

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

@@ -7,8 +7,8 @@ description:
 
 # /mandrel-deliver
 
-> **Lean spine.** Happy path + gate list. Sequencing, dispatch mechanics,
-> intent phrases, ceremony and the epilogue live in on-demand
+> **Lean spine.** Happy path + gate list. Sequencing, dispatch mechanics, intent
+> phrases, ceremony and the epilogue live in on-demand
 > [`helpers/deliver-reference.md`](helpers/deliver-reference.md) ("reference"
 > below); the unplanned path in
 > [`helpers/deliver-light.md`](helpers/deliver-light.md). Every delivery reads
@@ -21,9 +21,8 @@ close-and-land tail; Stories are implemented via
 [`helpers/deliver-story.md`](helpers/deliver-story.md).
 
 The dependency graph is **discovered, not declared** — `resolve-stories.js`
-reads it from live state, so you can deliver Stories **across plan runs and
-over time**. `plan-run::<id>` is filter metadata, never a resolution input;
-`route::lite` a body-derived hint only.
+reads it from live state, so you can deliver Stories **across plan runs and over
+time**. `plan-run::<id>` is filter metadata, never a resolution input.
 
 ## Inputs
 
@@ -36,25 +35,28 @@ you read:
 | `/mandrel-deliver 4712` | ids | One Story via `helpers/deliver-story.md`, **inline in this session** — no `story-worker` spawn. |
 | `/mandrel-deliver 4712 4713 …` | ids | Resolve the set, sequence by the discovered graph via `stories-wave-tick.js`, dispatch sub-agents. |
 | `/mandrel-deliver 4712 - 4716` | ids | A **range** — every id in the inclusive span. |
+| `/mandrel-deliver 4700` (a `type::epic`) | ids | The Epic's **open** child Stories. Mixes with Story ids. |
 | `/mandrel-deliver add a --json flag to doctor` | prompt | Unplanned work: gate, author a receipt Story, land it — [`helpers/deliver-light.md`](helpers/deliver-light.md). |
 
 **The discriminator is lexical and total.** An argument matching `^#?\d+$` is an
 id, and `^#?\d+\s*[-–—]\s*#?\d+$` an inclusive **range** — pass one on as a
-single unspaced token, never hand-expanded (reference § Ranges). Either shape
+single unspaced token, never hand-expanded (reference). Either shape
 means ids; anything else means a prompt. A **mixed** invocation (ids *and*
-prose) is a **hard error** — refuse it and ask which was meant. A ticket not
-`type::story`, or carrying an `Epic: #N` footer, is a hard error too.
+prose) is a **hard error** — refuse it and ask which was meant. A ticket that
+is neither `type::story` nor `type::epic`, or that carries an `Epic: #N`
+footer, is a hard error too — container Epics link parent→child only, so that
+footer stays refused.
 
 ## Saying what you want
 
-No flags to remember: state intent — *"…but I'll merge it myself"*, *"…one at
-a time"* — and announce what you read. Phrasings and the flags they fill in:
+No flags to remember: state intent — *"…but I'll merge it myself"*, *"…one at a
+time"* — and announce what you read. Phrasings and the flags they fill in:
 reference § Intent phrases.
 
 `--yes` is **runner-set, never operator-typed**: cron, `/loop` and headless
 dispatch set it to mean *nobody is at the keyboard*, which fails the unplanned
-path's over-scope stop closed to an envelope instead of a question. Never offer
-it to an operator or add it to an attended run.
+path's over-scope stop closed to an envelope instead of a question. Never add it
+to an attended run.
 
 ## Procedure
 
@@ -66,9 +68,11 @@ it to an operator or add it to an attended run.
    `node .agents/scripts/resolve-stories.js --ids <id,id,...>`. It validates the
    set and shows what will run: read `stories[]`, `dag[]` and `done[]` to
    present the order in step 2, but do **not** thread them into step 3 — the
-   tick re-resolves the graph every beat. It hard-errors (exit 1) on an id that
-   is not a Story, carries an `Epic: #N` footer, or whose edges cannot be
-   read — a missing gate would co-dispatch against an unlanded blocker.
+   tick re-resolves the graph every beat. An Epic id expands to its open child
+   Stories first — **announce it**. It hard-errors (exit 1) on an id that is
+   neither a Story nor an Epic, on an `Epic: #N` footer, on an Epic with no
+   open children, or on edges it cannot read — a missing gate would co-dispatch
+   against an unlanded blocker.
 
 2. **Confirm (N>1).** Present the order; wait unless `--yes`.
 
@@ -87,62 +91,62 @@ it to an operator or add it to an attended run.
    Each beat re-probes live state to derive done / in-flight itself; you never
    compute them. `--dispatched` is the one thing you must supply — the
    append-only list of every id you spawned this run. Cross-run de-confliction
-   via the assignee lease is automatic (reference §§ Sequencing edge cases,
-   Dispatch mechanics). Branch on the exit code:
+   via the assignee lease is automatic. Branch on the exit code:
    - **0** — dispatch each `ready` id (already capped and overlap-free); an
      empty `ready` with work in flight means "waiting", so keep looping;
      `epilogueDue: true` means every Story is done — step 4.
    - **2 / 3 / 4** — `cycleError` / `wedged` / `blocked`: stop the loop and
-     route per reference § Sequencing edge cases. **4** is the protocol's HITL
-     pause ([`instructions.md` § 1.J](../instructions.md)) — surface it and
-     wait for the operator; never poll.
+     route per reference. **4** is the protocol's HITL pause
+     ([`instructions.md` § 1.J](../instructions.md)) — surface it and wait for
+     the operator; never poll.
 
 4. **Close each hand-off** (§ Closing what the workers hand back), then, with
    every Story landed, run the **per-run epilogue (N>1)**:
-   `node .agents/scripts/plan-run-epilogue.js --stories 101,102`. N=1 skips it
-   ([reference § Per-run epilogue](helpers/deliver-reference.md)).
+   `node .agents/scripts/plan-run-epilogue.js --stories 101,102`, which also
+   closes a container Epic whose children all landed. N=1 skips it
+   ([reference](helpers/deliver-reference.md)).
 
 5. **Correct what the change invalidated.** If a memory you recalled this
-   session is now wrong — a trap this landed, a budget it moved — fix that
-   entry now, while both the old belief and the new fact are in context, and
-   say so when you report. No memory substrate → skip silently. Sweeping the
-   whole pool is [`/memory-consolidate`](memory-consolidate.md), not this step.
+   session is now wrong — a trap this landed, a budget it moved — fix that entry
+   now, while both the old belief and the new fact are in context, and say so
+   when you report. No memory substrate → skip silently. Sweeping the whole pool
+   is [`/memory-consolidate`](memory-consolidate.md), not this step.
 
 ## Closing what the workers hand back {#tail}
 
 **The tail is the orchestrator's, not the worker's.** A dispatched
 `story-worker` stops at a pushed branch and returns a hand-off; **you** run
 [`helpers/deliver-story.md`](helpers/deliver-story.md) Step 3
-(`single-story-close.js`) for it, foreground, and relay the envelope.
+(`single-story-close.js`) for it, foreground, and relay its envelope.
 
-**Serialize the tail.** Implementation runs in parallel; closing does not. Close
-one Story at a time — closes contend on the base branch, the merge queue and
-the checkout. A worker handing back mid-close waits its turn.
+**Serialize the tail.** Implementation runs in parallel; closing does not.
+Close one Story at a time — closes contend on the base branch, the merge queue
+and the checkout. A worker handing back mid-close waits its turn.
 
-**A worker returning no terminal envelope is the expected shape**, not a failure
-to answer with a re-dispatch: only close mints one. Close the pushed branch, or
-probe read-only with `node .agents/scripts/deliver-recover.js --story <storyId>`
-and resume the worker or close it names.
+**A worker returning no terminal envelope is expected**, not a failure to answer
+with a re-dispatch: only close mints one. Close the pushed branch, or probe
+read-only with `node .agents/scripts/deliver-recover.js --story <storyId>` and
+resume what it names.
 
 **Reading the outcome.** Each close ends the Story in one schema-validated
 envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
-fields are digest § 5. `pending` is **not** a failure — `nextCommand` resumes
-it; run that, do not re-dispatch.
+fields are digest § 5. `pending` is **not** a failure — run its `nextCommand`.
 
 **Branch model (authoritative).** `story-<id>` → PR → `main` (squash +
 required checks), per digest § 2; dependent Stories land sequentially. Ceremony
-depth (profiles + derived level via `ceremony-routing.js`, review depth reading
-it): reference § Ceremony.
+depth (profiles + the derived level via `ceremony-routing.js`, which review
+depth reads): reference § Ceremony.
 
 ## Constraints
 
 - **Land or block — never a silent local build** (digest § 2). Attended delivers
   default to close-and-land (`delivery.routing.closeAndLand: true`); rest at
-  `agent::closing` only when a human owns it.
-- **`/mandrel-deliver` never plans.** Planned tickets come from [`/mandrel-plan`](mandrel-plan.md), and
-  an over-scope prompt **escalates and ends** — never invoke `/mandrel-plan` in this
-  session to rescue it ([`helpers/deliver-light.md`](helpers/deliver-light.md)
-  § Escalation is terminal).
+  `agent::closing` only when a human owns the merge.
+- **`/mandrel-deliver` never plans.** Planned tickets come from
+  [`/mandrel-plan`](mandrel-plan.md), and an over-scope prompt **escalates and
+  ends** — never invoke `/mandrel-plan` in this session to rescue it
+  ([`helpers/deliver-light.md`](helpers/deliver-light.md) § Escalation is
+  terminal).
 
 ## See also