mandrel 2.59.0 → 2.61.0

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

@@ -1,7 +1,7 @@
 ---
 description:
   Execute one Story end-to-end: story-<id> from main, implemented in a worktree
-  (optional ## Slicing checkpoints), derived-level ceremony, PR against main.
+  (optional ## Slicing checkpoints), profile-resolved ceremony, PR against main.
 mandatoryReads: [deliver-digest.md]
 ---
 
@@ -18,13 +18,12 @@ mandatoryReads: [deliver-digest.md]
 The **one** delivery engine in v2:
 
 ```text
-single-story-init.js → implement + commits → derived-level ceremony → push
+single-story-init.js → implement + commits → ceremony → push
   ──hand-off──▶ single-story-close.js (gates, PR → main, agent::closing)
   → CI watch + merge → single-story-confirm-merge.js (agent::done)
 ```
 
-An `Epic: #N` reference marks a v1 ticket — **stop** and re-plan. Engine
-traits and prerequisites: reference § Engine invariants.
+Engine traits and prerequisites: reference § Engine invariants.
 
 ## Who owns which step
 
@@ -33,8 +32,9 @@ that dispatched the work**, never to a spawned worker.
 
 - **Inline dispatch** (a one-Story run — digest § 1): one session is both
   roles and walks Steps 0→7, no hand-off.
-- **Sub-agent dispatch**: the `story-worker` stops at Step 2.5 with the branch
-  pushed and returns a hand-off; the dispatching `/mandrel-deliver` session runs Step 3
+- **Sub-agent dispatch**: the `story-worker` boots on the `promptPath`
+  `deliver-run.js` wrote for it, stops at Step 2.5 with the branch pushed and
+  returns a hand-off; the dispatching `/mandrel-deliver` session runs Step 3
   **in its own turn** and **serializes the tail — one close at a time across
   the run**, even though implementation ran in parallel (reference § Step 3).
 
@@ -84,22 +84,21 @@ live in [`acceptance-self-eval.md`](acceptance-self-eval.md). **`proceed`** →
 Step 2. **`block`** → **do not close**: post a `friction` comment and flip
 `agent::blocked` (reference § Step 1a).
 
-## Step 2 — Ceremony (profile + derived level)
+## Step 2 — Ceremony (the profile alone)
 
-Ceremony is `delivery.routing.ceremonyProfile` × the **derived change level**,
-never a planner-authored verdict. **Digest § 3** is the incantation (change set
-once, derive the level, resolve critics with `ceremony-routing.js`); edge cases
-are reference § Step 2. Hard gates always run in Step 3 — the derived level
-never disables them; do **not** pre-run the chain here — Step 2.5's credited
-suite run is the sole exception.
+The acceptance verdict owner comes from `delivery.routing.ceremonyProfile` and
+nothing else — not the diff, not the dispatch mode, never a planner-authored
+verdict. **Digest § 3** is the incantation (change set once, derive the level
+for review depth, resolve the owner with `ceremony-routing.js`) and the one
+home of the rule; edge cases are reference § Step 2. Hard gates always run in
+Step 3 — nothing here disables them; do **not** pre-run the chain here —
+Step 2.5's credited suite run is the sole exception.
 
 ### Step 2.5 — The one credited suite run, the push, then hand off
 
-After the self-eval loop's last fix commit, run the suite **once** in the
-worktree through the depositor — `evidence-gate.js … --gate test -- npm test`,
-spelled out in **digest § 5**. It runs whatever `npm test` resolves to and
-stamps that, so the `test` credit is earned on any runner and only a *later*
-commit invalidates it. Red → fix, commit, re-run.
+After the self-eval loop's last fix commit, run the one credited suite run
+in the worktree — **digest § 5** is its only home and carries the
+invocation. Red → fix, commit, re-run.
 
 Push `story-<storyId>` to `origin`, confirming the remote ref moved. Then
 (sub-agent dispatch only) return the hand-off — Story id, `workCwd`,

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

@@ -53,10 +53,7 @@ the first `createIssue`, and refuses any pair of same-wave siblings that both
 declare a path (or one of which declares a covering glob) — naming the pair,
 the paths and the two remedies (merge them, or order them with `depends_on`).
 Such a pair cannot be co-dispatched, so the split buys no parallelism and
-costs a delivery session per Story. It replaced the acceptance partition,
-which refused only byte-identical acceptance text across siblings — a shape
-model output does not produce — so it never fired on the fragmentation it was
-meant to catch. **N=1 can never trip the refusal.**
+costs a delivery session per Story. **N=1 can never trip the refusal.**
 
 A draft of more than one Story also stops at **Gate #2** for operator
 approval, `--force-review` or not: a split always earns eyes. `--yes`
@@ -65,8 +62,7 @@ auto-proceeds, as at every other gate.
 ## Unknown triage — AFK vs HITL
 
 Every open question interrogation surfaces is triaged by **who can resolve
-it**, not parked in one bucket (a shape borrowed from the Wayfinder skill's
-HITL/AFK ticket typing):
+it**, not parked in one bucket:
 
 - **AFK** (away from keyboard — the agent resolves it alone): the answer is a
   fact something already records — third-party docs, a dependency's API
@@ -106,7 +102,7 @@ not re-deriving which assumptions were really the agent's to make.
 
 Gate #1 stops for exactly two things — the sharpened plan intent and any HITL
 unknown — and everything else the envelope surfaced collapses to **one
-advisory line** beneath it (Story #5312). Nothing on that line stops the run,
+advisory line** beneath it. Nothing on that line stops the run,
 reroutes it, or is invoked by `/mandrel-plan`; each item names something the
 operator may prefer to do instead, and the run proceeds either way. Under
 `--yes` the line is recorded and planning continues — an unattended run has
@@ -128,8 +124,7 @@ The line names, in order, whichever of these the envelope carries:
   the same shape with a different owner.
 - **`memoryPoolAdvisory.recommend`** — name
   [`/memory-consolidate`](../memory-consolidate.md), quoting its
-  `reasons[]`. The one arm left measures the `MEMORY.md` index against the
-  harness's byte cap; a stale pool degrades recall, it does not make the plan
+  `reasons[]`. A stale pool degrades recall, it does not make the plan
   wrong.
 - **`complexitySignals.uiSurface`** — name [`/prototype`](../prototype.md)
   and stop there. The signal carries **no routing authority and adds no
@@ -138,8 +133,8 @@ The line names, in order, whichever of these the envelope carries:
   lenses gate on, and whether any predicted path matches a web lens
   `filePattern` in `audit-rules.json`; a project with no rendered frontend
   resolves falsey and the offer never fires. `/mandrel-plan` must never invoke
-  it — operator invocation is the entire design, because the value is a human
-  looking at a layout before its UI acceptance criteria are frozen. Under
+  it — the value is a human looking at a layout before its UI acceptance
+  criteria are frozen. Under
   `--yes` the offer is recorded and planning proceeds — no reroute, no
   prototype written, no gate raised.
 
@@ -149,11 +144,10 @@ The envelope's `complexitySignals` field carries the paths the seed predicts,
 their repo state (existing paths predict refactors; missing predict creates)
 and the `audit-rules.json` sensitive-path classes the footprint intersects —
 `routingAuthority: false`, no `route` field. They ground the authoring
-template's pre-resolved `changes[]` and the `/prototype` offer, nothing else.
-Story #5312 deleted the plan-side lite claim that used to read them
-(`--route-downgrade-reason`, the persist shape backstop, the `route::lite`
-hint): every Story lands through the same engine and the same close gates,
-and ceremony is derived from the landed diff at close.
+template's pre-resolved `changes[]` and the `/prototype` offer, nothing else:
+every Story lands through the same engine and the same close gates, and the
+acceptance verdict owner follows the operator's ceremony profile — never
+anything a plan authored.
 
 ## Correct-by-construction authoring template
 
@@ -162,22 +156,22 @@ and ceremony is derived from the landed diff at close.
 `complexitySignals` ran:
 
 - **`verify[]` entries are commands.** There is no tier suffix and no
-  `manual:<reason>` escape (Story #5312): write the exact command or test
+  `manual:<reason>` escape: write the exact command or test
   path the deliverer runs and the acceptance critic reads as evidence.
 - **`changes[]` names what the deliverer authors.** Generated artifacts —
   quality baselines, generated test indexes, migration journals, lockfiles —
   are omitted: the work regenerates them, the refresh is a close-gate concern,
   and a declared shared artifact path reserves a footprint that needlessly
   serializes sibling Stories at dispatch.
-- **`changes[]` arrive pre-resolved to creates-vs-refactors.** Every path
-  the seed predicted is probed against the repo: an existing path is
-  emitted with `assumption: "refactors-existing"`, a missing one with
-  `assumption: "creates"`. The persist gates stay authoritative — they probe
-  the base branch ref, not the working tree — but a `creates` on a path that
-  exists at base, or a `refactors-existing` on one that does not, is a
-  dry-run **warning**, not a rejection; only a `deletes` naming an absent
-  path is refused. A plain-string bullet or a trailing parenthetical is
-  repaired into the object form by probing base, and the repair is reported.
+- **`changes[]` entries are bare paths.** The skeleton emits each seed-predicted
+  path as a bare string and persist derives its assumption by probing the base
+  branch ref — present is a `refactors-existing`, absent a `creates` — and
+  reports each derivation on the dry-run's repair list. Pin
+  `{path, assumption}` only when the probe would get it wrong; a `creates` on
+  a path that exists at base, or a `refactors-existing` on one that does not,
+  is then a dry-run **warning**, not a rejection. `deletes` stays explicit —
+  a bare path can never express a removal — and a `deletes` naming a path
+  absent at base is the one `changes[]` shape still refused.
 - **Keep `## Spec` at contract-level prose** — interfaces, invariants,
   load-bearing constraints; no per-file behavior narration — and as long as
   the work needs. There is no word or token budget.
@@ -188,23 +182,22 @@ kept — passes the persist ticket validators with no round-trip.
 ### Authored entry shape
 
 Each `stories.json` entry: `slug` (`^[a-z0-9][a-z0-9-]*$`), `type: "story"`,
-`title`, `body` (`goal`, optional `spec`, `changes[{path, assumption}]` —
-`creates|refactors-existing|deletes`, `non_goals`, `reason_to_exist`),
-top-level `acceptance[]`, `verify[]` (each a **bare command** — there is no
-tier suffix), and `depends_on[]` (a sibling slug, or `#<id>` for an existing
-open Story).
+`title`, `body` (`goal`, optional `spec`, `changes[]` — a **bare path string**
+by default, or `{path, assumption}` with
+`creates|refactors-existing|deletes` to pin one, `non_goals`,
+`reason_to_exist`), top-level `acceptance[]`, `verify[]` (each a **bare
+command** — there is no tier suffix), and `depends_on[]` (a sibling slug, or
+`#<id>` for an existing open Story).
 
 Author `acceptance[]` **without** the `AC-<n>:` handle: the body renderer
 numbers each checkbox from its array position, so a carried handle renders
 doubled. Persist normalises one off rather than refusing, and names the strip
 on the dry-run's repair list.
 
-Nothing in that shape inventories the repo for the author. `changes[]` arrives
-pre-resolved against the working tree, and Phase 8's
-`validateStoryFileAssumptions` re-probes every `{path, assumption}` at persist
-as a hard error — so the grounding contract is the author's own targeted reads
-plus that gate. There is no pre-computed codebase snapshot to fall back on,
-and no manifest-derived replacement to build.
+Nothing in that shape inventories the repo for the author: the grounding
+contract is the author's own targeted reads plus Phase 8's
+`validateStoryFileAssumptions`, which re-probes every resolved
+`{path, assumption}` at persist.
 
 ### Per-Story audit provenance (`provenance`)
 
@@ -232,20 +225,16 @@ work this plan already tracked.
 | Present but empty (`{}`) | Nothing. "Owns no findings" is a real answer. |
 | **Absent** | The **whole seed's** footers (the union) — the recall-safe default. |
 
-**The union fallback is load-bearing, not legacy.** Leaving the authoring agent
-to hand-carry provenance out of the seed's HTML comments was measured to fail —
-a remembered step is no step at all — and the mechanical union carry is what
-closed it. Attribution is additive: it sharpens a plan that opts in and changes
-nothing for one that does not. Never remove the fallback to "finish the
-migration".
-
-Attribution is what makes the next sweep's dedup answerable rather than
-arbitrary. Under the union every sibling carried every key, so a finding
-confirming against several open Stories could only pick one at random, and a
-key whose owning Story had since **closed** was masked by any open neighbour —
-a genuine regression filed as a routine update. With ownership stamped, the
-issue carrying a finding's own fingerprint decides both the match and its
-state (`lib/findings/route-finding.js`).
+**The union fallback is load-bearing, not legacy** — hand-carrying provenance
+out of the seed's HTML comments is a step an author forgets. Attribution is
+additive: it sharpens a plan that opts in and changes nothing for one that
+does not. Never remove the fallback to "finish the migration".
+
+Attribution makes the next sweep's dedup answerable: under the union a finding
+confirming against several open Stories can only pick one, and a key whose
+owning Story has **closed** is masked by an open neighbour. With ownership
+stamped, the issue carrying a finding's own fingerprint decides both the match
+and its state (`lib/findings/route-finding.js`).
 
 The audit path authors this mechanically from the per-group footers the seed
 already carries — see [`audit-to-stories`](../audit-to-stories.md). A `--seed`
@@ -255,24 +244,17 @@ or `--tickets` plan has nothing to attribute and omits the field.
 
 The conflict passes run **twice**: once over the raw `stories.json` payload
 (alongside the freshness, file-assumption and sizing gates), and again over the
-**assembled, footer-stamped bodies** — the artifact persist actually posts.
-The second pass is not belt-and-braces. The canonical authoring shape carries
-`acceptance[]` / `verify[]` at the ticket's top level and assembly folds them
-into the body, so the passes that scan `body.acceptance` / `body.verify`
-saw two empty arrays on the real payload and emitted nothing; the two
-substring-match advisories that depended on it are retired, leaving
-`shared-editor` as the one conflict kind. Both passes complete before the first
-`createIssue`, so a refusal still costs no writes.
-
-`shared-editor` findings are rendered into the posted `plan-summary` comment,
-directly beneath the wave table: the table promises which Stories can run
-together, and a path two same-wave Stories both write is exactly where that
-promise breaks. Promise and caveat belong on one durable surface — previously
-the caveat was a stderr warning nobody kept.
-
-Every conflict class is advisory (Story #5312 retired the
-`planning.failOn*` / `requireExplicitCrossStoryDeps` upgrade knobs with the
-registry and fan-out findings): co-editing one file is routine and often
+**assembled, footer-stamped bodies** — the artifact persist actually posts,
+where top-level `acceptance[]` / `verify[]` have been folded in. `shared-editor`
+is the one conflict kind. Both passes complete before the first `createIssue`,
+so a refusal still costs no writes.
+
+`shared-editor` findings are rendered into the plan-summary section of every
+Story's posted `story-plan-state` comment, directly beneath the wave table: the
+table promises which Stories can run together, and a path two same-wave Stories
+both write is exactly where that promise breaks.
+
+Every conflict class is advisory: co-editing one file is routine and often
 correct — the delivery scheduler already serializes file-overlapping Stories —
 and a path reference matched by substring can read as a dependency a prose
 mention never meant. A finding names the Stories and the fix (a `depends_on`
@@ -282,10 +264,10 @@ edge, or folding the shared edit into one Story) for the operator to weigh.
 
 A `--tickets` envelope carries a third author prompt beside
 `systemPrompts.story` and `systemPrompts.storySplitRules`:
-**`systemPrompts.storyTicketsRules`**. It exists because a
-source ticket arrives already in Story shape — rendered `AC-<n>:` checkboxes,
-a `## Verify` list, a `## Changes` footprint — and an author reading it as a
-template carries that shape forward instead of re-deriving it. The addendum
+**`systemPrompts.storyTicketsRules`**. A source ticket arrives already in
+Story shape — rendered `AC-<n>:` checkboxes, a `## Verify` list, a
+`## Changes` footprint — and an author reading it as a template carries that
+shape forward instead of re-deriving it. The addendum
 binds the author to re-derive `acceptance[]` from the goal, to express
 mechanical checks (a refreshed baseline, a lint exiting 0, a regenerated
 index) as `verify[]` commands rather than acceptance items, and to take the
@@ -318,19 +300,19 @@ template-only prose.
 
 ### Supersede-map partition
 
-`plan-persist` refuses a partial supersede map **before** it creates any
-Story, the same fail-closed shape as the collision refusal: every id passed to
-`--tickets` must be claimed by **exactly one** Story, and no Story may
-claim an id that was not a source ticket. With N>1 the mapping is not
-total by default — an authored map is the only thing that can say
-`#11-#14 → #20` while `#15 → #21`, which a blanket "superseded by
-this plan-run" reference could not.
+`plan-persist` completes the supersede map **before** it creates any Story,
+splitting it by who can be right. **Refused, fail-closed:** a Story claiming
+an id that was never a source ticket, and two Stories claiming the same id —
+the first would close an issue nobody asked about, the second cannot say which
+Story replaced it. **Assigned with a warning:** a source id no Story claimed
+goes to the primary Story, because this plan is replacing it either way and
+only the bookkeeping was open. With N>1 an authored map is still the only
+thing that can say `#11-#14 → #20` while `#15 → #21`, so author one whenever
+the default is not what you mean.
 
 ## The pre-mortem critic — operator-invoked
 
-The maker-blind **pre-mortem** critic is not a step of the spine (Story #5312
-retired step 2.5 with the consolidation critic, whose one deterministic input
-was a `## Delivery Slicing` table no Story carries). Run it when the operator
+The maker-blind **pre-mortem** critic is not a step of the spine. Run it when the operator
 asks for it, after Author and before Persist — the last point a finding folds
 into a re-author:
 
@@ -369,30 +351,33 @@ a re-author round.
 
 ## What `--dry-run` actually gates
 
-`plan-persist.js --dry-run` is the same command with GitHub writes suppressed,
-and every gate runs before the first `createIssue` would fire. Since
-Story #5312 the gates split two ways, and the dry-run is where the second
-half is read:
+A bare `plan-persist.js` runs the whole gate list write-free and then, on a
+clean list, persists in the same invocation; `--dry-run` is that same first
+half with the second suppressed. Either way every gate runs before the first
+`createIssue` would fire. The gates split two ways, and the dry-run output is
+where the second half is read:
 
 **Hard — the run refuses:** a body that does not parse, a ticket that is not
-a Story, an empty `acceptance[]` or `verify[]`, an unknown or cyclic
-`depends_on`, the acceptance partition at N>1, the supersede partition, a
-forbidden commit-subject prefix, and a `deletes` entry naming a path absent
-at base.
+a Story, an empty `acceptance[]`, an unknown or cyclic `depends_on`, the
+same-wave collision refusal at N>1, a supersede claim on a non-source id or
+one claimed twice, and a `deletes` entry naming a path absent at base.
+Commit subjects are not scanned — the `commit-msg` hook and
+`normalize-pr-title.js` enforce them.
 
 **Warnings — listed, then the persist proceeds:** a `creates` on a path that
 exists at base or a `refactors-existing` on one that does not (including a
 path the base branch deleted or renamed, named with the removing commit), a
-goal or acceptance path absent at base, a `verify[]` command naming an absent
-test file, an `open-question` in a body (`Flag if…`, `TBD`, a trailing `?`),
-and a `pinned-identifier` in an acceptance item — a backticked bare symbol
+goal or acceptance path absent at base, an empty `verify[]`, a source id
+assigned to the primary Story by default, a `verify[]` command naming an
+absent test file, an `open-question` in a body (`Flag if…`, `TBD`, a trailing
+`?`), and a `pinned-identifier` in an acceptance item — a backticked bare symbol
 that is not a path, a label, a kebab token, a flag or a command, which the
 advisory `changes[]` is free to reshape out from under the criterion. The
 list also names every **repair** the run applied — a plain-string bullet or a
 trailing parenthetical rewritten into `{ path, assumption }` by probing base,
-and an `AC-<n>:` handle normalised off an acceptance item. The same list rides the result
-envelope as `warnings[]` and `repairs[]`, so a `--chain-on-clean` run loses
-nothing.
+and an `AC-<n>:` handle normalised off an acceptance item. The same list rides
+the result envelope as `warnings[]` and `repairs[]`, carried from the
+write-free pass onto the chained run's envelope.
 
 A dry run that comes back clean has paid for every deterministic refusal, so
 the real persist has nothing left to discover except network failure.
@@ -417,23 +402,17 @@ leave the common follow-up plan with nowhere to file itself. The three-Story
 threshold governs **creation** only, where it still holds: at two Stories a
 pair of ids is as easy to carry as one container id.
 
-On a yes, pass `--epic <id>`. Persist then:
-
-1. resolves the id **before the first create** (dry run included) — it must be
-   **open** and carry `type::epic`, or the run hard-errors having written
-   nothing;
-2. after the Stories exist, appends one `- [ ] #N` row per new Story to the
-   Epic's checklist via `appendEpicChildIds`, which is idempotent and preserves
-   existing rows' **checked state**, their order, and the fingerprint marker;
-3. mirrors a native sub-issue edge per child.
+On a yes, pass `--epic <id>`. Persist resolves it **before the first create**
+(dry run included) — it must be **open** and carry `type::epic`, or the run
+hard-errors having written nothing — then appends a `- [ ] #N` checklist row
+and a native sub-issue edge per new Story.
 
 The refusal posture is the **opposite** of creation's, deliberately. Creation
 degrades (an unensurable label just skips the container) because the operator
-never named one. Adoption cannot: the operator named a specific id, so silently
-not adopting it would leave them believing their Stories were filed somewhere
-they were not. Hence a hard error, raised while nothing has been written and
-the fix is free. Once the Stories are live the posture flips back — a failed
-checklist write or sub-issue edge only warns.
+never named one; adoption names a specific id, so silently not adopting it
+would misfile the Stories. Hence a hard error, raised while nothing has been
+written. Once the Stories are live the posture flips back — a failed checklist
+write or sub-issue edge only warns.
 
 **Only open Epics are adoptable.** A closed Epic is a finished body of work;
 joining one would reopen a container the epilogue deliberately closed and
@@ -446,11 +425,9 @@ raised before any I/O.
 ### Creating a new container (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.
+container. Confirmed, persist opens it **after** the Stories and links every
+created Story both ways: a `- [ ] #N` body checklist and a native GitHub
+sub-issue edge, which the delivery-side reader unions.
 
 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
@@ -458,18 +435,13 @@ 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`).
+Linkage runs parent→child only, which is why 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.
+entirely, while a failed sub-issue edge only warns. Either way the Stories are
+untouched and deliver by id. A resumed persist adopts an existing Epic whose
+fingerprint matches the title **and the exact child set**.
 
 ## Cross-plan `depends_on` (`#<id>`)
 
@@ -483,9 +455,8 @@ opened and never had to name.
 `complexitySignals.predictedPaths`, each carrying the `overlappingPaths[]` that
 matched. Overlap is computed on **declared footprints** and not on prose, using
 the same `storyFootprint` the wave runner uses to withhold colliding Stories at
-dispatch — so the planner sees the collision the runtime would later enforce,
-one layer earlier and while it is still cheap to order around. A seed naming no
-paths short-circuits to `[]` with no provider call at all.
+dispatch — the collision the runtime would later enforce, seen while it is
+still cheap to order around. A seed naming no paths short-circuits to `[]`.
 
 It stays advisory: two Stories can touch a shared barrel file with no real
 ordering between them, and only the operator knows.
@@ -495,9 +466,9 @@ a Story already open is not scheduled by this run, so it has no position in the
 topological sort and cannot close a cycle back into a Story that does not exist
 yet. They are validated **before any create** (dry run included): each must
 resolve to an **open `type::story`**, and a closed issue, a container Epic, a
-missing id or a non-Story hard-errors with every bad ref named in one pass. The
-strictness is the point — a blocker that can never be satisfied reads to the
-delivery engine as a permanent wedge rather than as an error worth reporting.
+missing id or a non-Story hard-errors with every bad ref named in one pass — a
+blocker that can never be satisfied would read to the delivery engine as a
+permanent wedge.
 
 Persist renders the entry unchanged as a `blocked by #<id>` footer line and
 mirrors the native `blocked_by` edge, which is the same pair of surfaces a
@@ -508,13 +479,13 @@ state.
 ## Ready means fully persisted
 
 `agent::ready` is the **terminal** step, not part of the creating POST.
-The order is: create unlabelled → upsert `story-plan-state` on
-every Story → upsert `plan-summary` on the primary → flip every Story to
-`agent::ready`.
+The order is: create unlabelled → upsert `story-plan-state` on every Story (one
+comment carrying the plan summary: story set, delivery order, deliver command)
+→ flip every Story to `agent::ready`.
 
 This is what lets `/mandrel-deliver` trust the label: a Story carrying
-`agent::ready` always has its persist receipt on the ticket, so nothing can
-pick it up mid-write and read a half-persisted plan.
+`agent::ready` always has the operator's delivery instructions on the ticket,
+so nothing can pick it up mid-write and act on a half-persisted plan.
 
 ## Resuming a failed persist
 
@@ -546,47 +517,34 @@ them **envelope-first**:
 
 | Channel | When it wins |
 | --- | --- |
-| Envelope `sourceTickets[]` | **The normal path.** Written by step 1's `--out`, then read from `--plan-context <file>` or auto-discovered at `<plan-dir>/plan-context.json`. No ids to re-type. |
+| Envelope `sourceTickets[]` | **The normal path.** Written by step 1 to `<tempRoot>/plan-<slug>/` (or wherever `--out` points), then read from `--plan-context <file>` or auto-discovered at `<plan-dir>/plan-context.json`. No ids to re-type. |
 | `--source-tickets <ids>` | Explicit **override** for hand-driven runs (no captured envelope, or deliberately narrowing the set). Wins over the envelope; a disagreement is warned about, not silently reconciled. |
 
 The result envelope's `supersede.sourceTicketOrigin` reports which channel was
-used (`envelope` \| `flag` \| `none`).
-
-Every path with no envelope is **audible** — persist cannot tell a legitimate
-`--seed` run from a `--tickets` run whose envelope was never captured, so it
-says so rather than deciding silently:
-
-| Situation | Behaviour |
-| --- | --- |
-| Neither `--plan-dir` nor `--plan-context` | **Warn** — nothing was read; only `--source-tickets` can supply ids. |
-| Auto-discovered `<plan-dir>/plan-context.json` absent | **Warn** — degrade to `--source-tickets`; a `--seed` run legitimately has none. |
-| Explicit `--plan-context` missing | **Fatal** — the operator named a file and meant it. |
-| Envelope present but unparseable | **Fatal** — a corrupt envelope is not "no source tickets"; treating it as such is how a `--tickets` run used to report success having superseded nothing. |
+used (`envelope` \| `flag` \| `none`). Every path with no envelope is
+**audible**: an absent envelope warns and degrades to `--source-tickets` (a
+`--seed` run legitimately has none), while an explicitly named but missing
+`--plan-context`, or an unparseable envelope, is **fatal**.
 
 Whichever channel supplies them, the supersede-map partition above still
-fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is now
-**caught** (`source ticket #N is not claimed by any Story`) instead of
-partitioning an empty set and passing vacuously.
+fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is
+**caught** (`source ticket #N is not claimed by any Story`).
 
 ## Closing superseded source tickets
 
 **Default on.** After the Stories exist, persist comments on each source
 issue naming the specific Story that claims it — plus that Story's optional
 per-supersede `note` — and closes it with reason **`not_planned`**
-(`state_reason`). Nothing has shipped at persist time and the issue will not
-be actioned in its own right, so `not_planned` is the honest reason;
-`completed` would be a lie. This is what keeps the tracker from asserting
-that already-planned work is still unowned, and it writes down the supersede
-link that makes the history readable.
-
-| Behaviour | Contract |
-| --- | --- |
-| Default | Comment + close every source ticket as `not_planned`, **clearing its `agent::*` label** in the same write — a retired ticket has no agent state, and `agent::done` would claim a delivery that never happened. |
-| `--no-close-superseded` | Skips all commenting and closing. Story creation is unchanged. Use it for a genuinely partial supersede — when the plan folded in only *part* of an issue and the remainder must stay open. |
-| `--dry-run` | Posts no comment and closes nothing; reports what it would have done. |
-| Re-run | Idempotent — the comment is keyed off a `superseded-by` structured-comment marker, and an already-closed source is skipped. |
-| Already closed / deleted / inaccessible | Skipped and reported. Never throws. |
-| Close-phase failure | **Never fails the run.** Stories stay created; the result envelope's `supersede` report names which tickets were and were not closed so the operator can finish by hand. |
+(`state_reason`) — nothing has shipped at persist time, so `completed` would
+be a lie.
+
+The default also **clears the source's `agent::*` label** in the same write — a
+retired ticket has no agent state. Pass **`--no-close-superseded`** for a
+genuinely partial supersede — when the plan folded in only *part* of an issue
+and the remainder must stay open. The phase is idempotent (keyed off a
+`superseded-by` marker), skips already-closed or inaccessible sources, and
+**never fails the run**: its `supersede` report names which tickets were and
+were not closed so the operator can finish by hand.
 
 `--seed` / `--seed-file` modes have no source tickets, so no close phase
 runs at all.

package/.agents/workflows/helpers/qa-core.md

@@ -110,6 +110,18 @@ ledger, conforming to [`qa-ledger.schema.json`](../../schemas/qa-ledger.schema.j
 session. This is the single findings channel across all three workflows — there
 is no per-workflow finding schema.
 
+## Coverage tiers and the missing test
+
+For the surface an item points at, gather the tests that exercise it and
+classify each by path per
+[`testing-standards.md` § The Three Tiers](../../rules/testing-standards.md#the-three-tiers)
+— a `.feature` file is **acceptance**, a path containing `/contract/` or
+`.contract.test.` is **contract**, and a path containing `.test.` or
+`__tests__/` is **unit**; a skipped test leaves its tier uncovered. Then take
+the lowest tier with no live test (unit → contract → acceptance) and write one
+concrete sentence describing the test that would close it — the item's
+`missingTest` (`null` when every tier is covered).
+
 ## Triage — classify → route → disposition → promote
 
 Route the ledger through the shared classify/route/dedup/promote core. The