mandrel 2.24.0 → 2.25.0

package/.agents/workflows/audit-architecture.md

@@ -1,5 +1,5 @@
 ---
-description: Audit architectural boundaries, module coupling, and layering violations; emit a structured findings report keyed to High/Medium/Low severity.
+description: Audit architectural boundaries, module coupling, layering violations, and shipped-but-uncalled seams; emit a structured findings report keyed to the canonical severity scale.
 ---
 
 # Architecture & Clean Code Audit
@@ -57,9 +57,14 @@ the failure mode this lens exists to prevent.
    node .agents/scripts/check-dead-exports.js
    ```
 
-   Each unreferenced export is a grounded candidate. **Cede it** to
-   audit-clean-code's Dead Code dimension rather than re-deriving it here (see
-   the deferral in Step 2). When the shipped checker is unavailable, fall back
+   Each unreferenced export is a grounded candidate. **Cede the
+   merely-unreferenced ones** to audit-clean-code's Dead Code dimension rather
+   than re-deriving them here (see the deferral in Step 2); keep the ones that
+   are dead *wiring* — a seam a delivery shipped that no live production path
+   reaches — for this lens's Shipped-But-Never-Wired dimension. Note that this
+   checker only sees unreferenced symbols, so it cannot surface the worst shape
+   (a writer with no reader, both fully referenced); that one you must trace by
+   hand. When the shipped checker is unavailable, fall back
    to `npx knip --production` — and heed the `!`-suffix entry-pattern caveat
    that [`audit-clean-code`](audit-clean-code.md) documents, since
    `knip --production` is a silent no-op without it.
@@ -116,21 +121,35 @@ legitimately have no layered architecture to guard.
 
 ## Step 2: Analysis Dimensions
 
-For every finding you surface, grade **Impact** on a High / Medium / Low axis
-reflecting the severity of the architectural risk (how much correctness,
-maintainability, or testability the gap erodes), independent of the
-**Category** effort axis — a Quick Win can still be High Impact, and a
-Structural Change can be Medium. As a loose default, Quick Wins typically land
-High (cheap to fix, real payoff) and Structural Changes Medium/High, but grade
-Impact on the risk itself rather than deriving it mechanically from Category.
+For every finding you surface, grade **Impact** on the **canonical severity
+scale** — `Critical | High | Medium | Low | Info`, defined in the core's
+[Severity scale](helpers/audit-lens-core.md#severity-scale) and owned by
+`lib/findings/severity.js`. This lens relabels the axis `Impact` (it reflects how
+much correctness, maintainability, or testability the gap erodes), but the
+*levels* are the shared five and nothing else: a narrower or invented vocabulary
+resolves to no severity and the finding is dropped from every severity-filtered
+run. In particular an architectural defect that is actively data-losing or
+release-blocking grades **Critical**, and a grounded observation that asks for no
+scheduled work grades **Info** — neither collapses into `High` or `Low`.
+
+Impact is independent of the **Category** effort axis — a Quick Win can still be
+High Impact, and a Structural Change can be Medium. As a loose default, Quick
+Wins typically land High (cheap to fix, real payoff) and Structural Changes
+Medium/High, but grade Impact on the risk itself rather than deriving it
+mechanically from Category.
 
 > **Boundary with `audit-clean-code`.** The clean-code-overlapping smells
 > (over-engineering & abstractions, cognitive load & nesting, dead code &
 > redundancy, naming & self-documentation, coupling & cohesion) are owned by
 > [`audit-clean-code`](audit-clean-code.md); the Step 0 dead-export candidates
 > flow into its Dead Code dimension. Do **not** duplicate them here. This lens
-> keeps only the two structural dimensions no other lens owns — the
-> testable-surface boundary and the automated-guardrail maturity.
+> keeps only the three structural dimensions no other lens owns — the
+> testable-surface boundary, the automated-guardrail maturity, and
+> shipped-but-never-wired seams. The split with clean-code's Dead Code dimension
+> is by *question asked*: clean-code asks whether a symbol is referenced at all,
+> this lens asks whether a **live production path** reaches it. An unreferenced
+> helper is clean-code's; a fully-referenced writer whose reader was never built
+> is this lens's.
 
 Evaluate the gathered context against the following architecture dimensions:
 
@@ -208,6 +227,43 @@ Evaluate the gathered context against the following architecture dimensions:
    full maturity assessment runs only in codebase-wide mode (when
    `{{changedFiles}}` renders as the literal substitution token).
 
+3. **Shipped-But-Never-Wired Seams (mandatory).** Report code this repository
+   ships that **no live production caller ever reaches**. This is the failure
+   mode the per-Story suite structurally cannot catch: every piece passes its own
+   unit tests, the diff looks complete, and the assembled path is dead — so it is
+   found only after delivery, if at all. A green suite is not evidence of a live
+   path; only a caller is.
+
+   Walk the seam **from the consumer backwards**, not from the producer forwards.
+   For each candidate, name the production entry point you traced to — or state
+   that you could not reach one, which is the finding. Cover at least:
+
+   - **A produced-but-never-consumed artifact.** Something the code computes,
+     stamps, writes, or returns that nothing downstream ever reads: an envelope
+     field no consumer parses, a file or log written and never opened, a
+     provenance marker stamped by the writer with no reader. Both halves must
+     exist for the feature to work, and shipping only the writer looks exactly
+     like shipping the feature.
+   - **An optional field nothing populates.** The mirror image: a parameter,
+     config key, or schema property a consumer reads and branches on that no
+     caller ever sets. The branch is unreachable, so the behaviour it guards has
+     never once run, and the default silently *is* the behaviour.
+   - **An exported seam with no in-tree caller** that the core's exclusion list
+     does not bless — not a test seam, not a CLI/`exports` entry point, not
+     dynamically reached. Cite the exclusion and drop it when it is one of those;
+     the Step 0 dead-export reading is the grounding instrument here, and the
+     candidates it surfaces that are genuinely dead **internal** wiring belong in
+     this dimension rather than ceded to clean-code's Dead Code dimension.
+
+   Grade Impact by what the dead wiring was supposed to do: a dead *guard, gate,
+   or enforcement path* is **High** or **Critical** — the protection it was
+   shipped to provide has never been in force, and the gate reads green because
+   it never runs. Dead reporting or convenience wiring is **Medium**. Each
+   finding's **Acceptance signal** must be the observable that proves the path is
+   live: a test that fails when the caller is removed, or a trace from the
+   production entry point to the seam. "Added a unit test for the seam" is not
+   that signal — the seam already had one.
+
 ### Maturity Rubric
 
 Use these definitions to classify the project's `Architecture Guardrail

package/.agents/workflows/audit-quality.md

@@ -107,6 +107,32 @@ Evaluate the gathered context against the following test quality dimensions:
    criteria to ensure they have corresponding and complete test coverage.
    Verify that the implementation found in the codebase correctly matches the
    architectural requirements and highlight any inconsistencies or gaps.
+7. **Unwired Seams — Coverage Without a Caller (mandatory).** Report code the
+   suite **covers** but no live production path **calls**. This is the blind spot
+   this dimension exists for, and it is a property of the suite, not of the code:
+   a seam with its own passing unit test reports as covered, contributes to the
+   coverage number, and is never exercised in assembly — so the suite reads green
+   over wiring that has never run once. High coverage is therefore not evidence
+   of a live path; it is what conceals a dead one. Cover at least:
+
+   - **A produced-but-never-consumed artifact** — a field, file, or marker the
+     code writes that no test and no consumer ever reads back. A writer test that
+     asserts on the writer's own output is not a reader.
+     `assert(written === expected)` proves the write, never the round-trip.
+   - **An optional field nothing populates** — a parameter or config key a
+     consumer branches on that only *tests* ever set. The suite covers both
+     branches; production has only ever taken the default.
+
+   For each, name the missing test rather than the missing caller: the gap is
+   that **no test would fail if the wiring were deleted**. That is the assertion
+   to recommend — an integration-tier test that drives the real production entry
+   point and fails when the seam is unwired. Grade a dead guard/gate **High** or
+   **Critical** (the enforcement has never been in force and the bar reads green
+   because it never runs), other dead wiring **Medium**. The core's exclusion
+   list still applies: a sanctioned test seam or a declared entry point is not a
+   finding here. Route the *architectural* framing of the same defect to
+   [`audit-architecture`](audit-architecture.md)'s Shipped-But-Never-Wired
+   dimension; this lens owns the **missing-test** framing.
 
 ## Constraint (lens-specific carve-out)
 

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

@@ -143,9 +143,24 @@ Chain into the existing planning entrypoint:
 
 (`/plan --seed "$(cat <path>)"` also works for small seeds). `/plan`
 then runs its author → persist path, as documented in its workflow.
-Each Story it spawns from the seed carries `context::audit:
-<reportLink>` and `audit-fingerprint: <sha>` in its body so future
-Phase 6 idempotency works on the next run.
+
+**Dedup provenance is carried mechanically — do not hand-copy it.** The seed's
+MVP Scope bullets carry each group's `audit-fingerprints` and
+`audit-semantic-keys` footers as HTML comments (invisible in the rendered
+one-pager). `plan-persist` harvests them out of the seed on the
+`plan-context.json` envelope and appends them to **every** Story body it
+persists, via `carryProvenanceFooters`
+([`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)).
+The carry is additive, union-preserving and idempotent, so a resumed persist
+cannot stack footers and a hand-authored fingerprint is never dropped.
+
+This is deliberately not an authoring step. It used to be: the footers reached
+the seed and stopped there, leaving the authoring agent to notice HTML comments
+in a one-pager and copy them forward — a remembered step, which is to say no
+step at all. Stories filed on the recommended path were therefore invisible to
+the next sweep's Phase 6 dedup, which re-filed work it had already planned. If
+you find yourself copying a footer by hand, the carry is broken — fix it there
+rather than papering over it in the body.
 
 ## Phase 5b — Standalone-Stories path
 
@@ -261,7 +276,18 @@ When the single-plan path ran, link the Story (or plan-run) the chained
   dedup/route implementation, shared with `qa-explore`.
 - **Always** stamp the fingerprint footer (via the helper's
   `fingerprintFooter`) in the body of every created Story. Without it,
-  the next run cannot dedupe.
+  the next run cannot dedupe. On the Single-plan path this is mechanical
+  (`carryProvenanceFooters`, Phase 5a) — never an authoring step.
+- **Never** re-mint a finding fingerprint while normalising a finding.
+  `severity` and `labels` are identity fields folded into the sha, so
+  normalising either without holding the hash stable silently breaks
+  dedup for every finding already filed. The projection that keeps the
+  fingerprint invariant under normalisation is
+  `severity.js#fingerprintSeverity`; the contract is pinned by
+  `tests/lib/findings/route-finding.contract.test.js`.
+- **Always** grade findings on the canonical five-level scale
+  (`lib/findings/severity.js`). A level outside it parses as no severity
+  and the finding is dropped by every severity-filtered run.
 - **Always** present the Phase 2, 3, and 4 HITL gates. Do not bypass —
   even when "obvious" — because the severity / grouping / mode picks
   are operator decisions that the workflow's UX contract relies on.

package/.agents/workflows/deliver.md

@@ -8,73 +8,64 @@ description:
 # /deliver
 
 > **Lean spine.** Happy path + gate list. Sequencing, dispatch mechanics,
-> intent phrases, ceremony, and the epilogue live in the on-demand
-> [`helpers/deliver-reference.md`](helpers/deliver-reference.md); the unplanned
-> path in [`helpers/deliver-light.md`](helpers/deliver-light.md). What every
-> delivery always needs is one read:
-> [`helpers/deliver-digest.md`](helpers/deliver-digest.md).
+> 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
+> [`helpers/deliver-digest.md`](helpers/deliver-digest.md) once.
 
 ## Role
 
-One delivery door. `/deliver` owns input resolution and sequencing only — every
-Story lands through [`helpers/deliver-story.md`](helpers/deliver-story.md).
+One delivery door. `/deliver` owns input resolution, sequencing and the
+close-and-land tail; Stories are implemented via
+[`helpers/deliver-story.md`](helpers/deliver-story.md).
 
-Nothing about the route is declared at the invocation; it is **derived, then
-announced, then acted on**. The dependency graph is **discovered, not
-declared** — `resolve-stories.js` reads it from live state (body edges ∪ native
-`blocked_by` edges, each blocker resolved against its real issue state), so
-there is no graph to hand it and no batch label, which is what lets you deliver
-Stories **across plan runs and over time**.
-`plan-run::<id>` is filter metadata, never a resolution input; `route::lite` is
-a body-derived hint only. Ahead of all of it, a **single-Story run runs the
-engine inline** whatever the shape — sub-agent isolation only earns its cost
-against a concurrent sibling.
+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.
 
 ## Inputs
 
-Classify what the operator typed **before** doing anything else, and say which
-shape you read it as:
+Classify what the operator typed **before** anything else, and say which shape
+you read:
 
 | Invocation | Shape | Behavior |
 | --- | --- | --- |
 | `/deliver` | bare | List the open `agent::ready` Stories and ask which to deliver. Deliver nothing until answered. |
 | `/deliver 4712` | ids | One Story via `helpers/deliver-story.md`, **inline in this session** — no `story-worker` spawn. |
-| `/deliver 4712 4713 …` | ids | Resolve the set, then sequence by the discovered graph via `stories-wave-tick.js`, dispatching role-scoped sub-agents. |
+| `/deliver 4712 4713 …` | ids | Resolve the set, sequence by the discovered graph via `stories-wave-tick.js`, dispatch sub-agents. |
 | `/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.** Every positional argument matching
 `^#?\d+$` means ids; anything else means a prompt. A **mixed** invocation (ids
-*and* prose) is a **hard error** — refuse it and ask which was meant, the way
-resolution refuses a whole set rather than under-delivering. A named ticket
-that is not `type::story`, or carries an `Epic: #N` footer, is a hard error too.
+*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.
 
 ## Saying what you want
 
-No flags to remember: state intent — *"…but I'll merge it myself"*, *"…take the
-lease"*, *"…one at a time"* — and announce what you read before acting.
-Phrasings and the flag each fills in:
-[`helpers/deliver-reference.md` § Intent phrases](helpers/deliver-reference.md).
+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 is what makes the
-unplanned path's over-scope stop fail closed to a terminal envelope instead of
-a question. Never offer it to an operator or add it to an attended run.
+`--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.
 
 ## Procedure
 
 0. **Classify and announce.** Read the invocation per § Inputs and state the
-   shape you derived. A prompt leaves for
-   [`helpers/deliver-light.md`](helpers/deliver-light.md); bare asks; ids
-   continue below.
-
-1. **Resolve the set.** One command, for one Story or many:
-   `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. You do **not** thread them into step 3 — the
-   tick re-resolves the graph itself every beat. Resolution hard-errors
-   (exit 1) on a named id that is not a Story, carries an `Epic: #N` footer, or
-   whose native edges cannot be read — a missing gate would co-dispatch against
-   an unlanded blocker.
+   shape. A prompt leaves for
+   [`helpers/deliver-light.md`](helpers/deliver-light.md); bare asks; ids go on.
+
+1. **Resolve the set.** One command, one Story or many:
+   `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.
 
 2. **Confirm (N>1).** Present the order; wait unless `--yes`.
 
@@ -87,74 +78,69 @@ a question. Never offer it to an operator or add it to an attended run.
    ```
 
    **Do not add `--concurrency` unless the operator explicitly asked for a
-   per-run cap** — an explicit value wins over config, so a filled-in literal
-   silently defeats a `.agentrc.local.json` override.
+   per-run cap** — an explicit value wins over config, so a literal defeats a
+   `.agentrc.local.json` override.
 
    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 — and cross-run
-   de-confliction via the assignee lease is automatic
-   ([`helpers/deliver-reference.md`](helpers/deliver-reference.md) §§ Sequencing
-   edge cases, Dispatch mechanics).
-
-   Branch on the exit code:
-   - **0** — dispatch each `ready` id (already capped and overlap-free). Empty
-     `ready` with work in flight means "waiting"; keep looping.
-     `epilogueDue: true` means every Story is done — go to step 4.
-   - **2** — `cycleError`: the graph is self-referential. Fix the `depends_on`
-     declarations; do not retry.
-   - **3** — `wedged`: nothing dispatchable, nothing in flight, undone Stories
-     waiting on unmet blockers — both named in the envelope. Land the blocker
-     or include it in `--ids`; do not retry unchanged.
-   - **4** — `blocked`: a Story carries `agent::blocked`, named in `blocked[]`
-     with `blockedReason` — the protocol's HITL pause
-     ([`instructions.md` § 1.J](../instructions.md)). **Stop the loop and
-     surface it; do not poll.** Read the friction comment
-     (`gh issue view <id> --comments`) and resume only once the operator
-     unblocks it (`update-ticket-state.js --ticket <id> --state agent::ready`).
-     Blocked outranks a wedge but not a cycle (fix the graph first).
-
-4. **Per-run epilogue (N>1).** Once step 3 reports `epilogueDue: true`, run
-   `node .agents/scripts/plan-run-epilogue.js --stories 101,102` — audit
-   roster, follow-up roll-up, sibling coherence. A single-Story run skips it
+   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:
+   - **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** — `cycleError`: the graph is self-referential; fix `depends_on`, do
+     not retry. **3** — `wedged`: nothing dispatchable, nothing in flight, the
+     undone Stories and their unmet blockers named; land a blocker or add it to
+     `--ids`. **4** — `blocked`: a Story carries `agent::blocked` with
+     `blockedReason`, the protocol's HITL pause
+     ([`instructions.md` § 1.J](../instructions.md)) — **stop the loop and
+     surface it; do not poll**, resuming once the operator unblocks it. Blocked
+     outranks a wedge, not a cycle.
+
+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)).
 
-## Branch model (authoritative)
+## Closing what the workers hand back {#tail}
 
-`story-<id>` → PR → `main` (squash + required checks), per digest § 2.
-Dependent Stories land sequentially so each builds on the previous merge.
-Ceremony depth (profiles + derived level via `ceremony-routing.js`, review
-depth reading the same level):
-[`helpers/deliver-reference.md` § Ceremony](helpers/deliver-reference.md).
+**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.
 
-## Reading a Story's outcome
+**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.
 
-Each Story ends in exactly one schema-validated terminal envelope — `landed` |
-`pending` | `blocked` | `failed`. Statuses, exits, and fields:
-[`helpers/deliver-digest.md`](helpers/deliver-digest.md) § 5.
+**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.
 
-`pending` is **not** a failure: the bounded wait expired with the PR healthy
-(or a human owns the merge), nothing was mutated, and `nextCommand` resumes it
-— run that rather than re-dispatching.
+**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.
 
-For a Story in an unclear state — including the merged-but-label-stale one a
-re-run refuses outright — probe it read-only with
-`node .agents/scripts/deliver-recover.js --story <storyId>`.
+**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.
 
 ## 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 the merge.
+- **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.
 - **`/deliver` never plans.** Planned tickets come from [`/plan`](plan.md), and
   an over-scope prompt **escalates and ends** — never invoke `/plan` in this
   session to rescue it ([`helpers/deliver-light.md`](helpers/deliver-light.md)
-  § Escalation is terminal). The router performs no git/label mutations;
-  `deliver-story` owns every script.
+  § Escalation is terminal).
 
 ## See also
 
-- [`/plan`](plan.md) — unified planning entry point.
-- [`helpers/deliver-story.md`](helpers/deliver-story.md) — the one engine.
-- [`helpers/deliver-light.md`](helpers/deliver-light.md) — the unplanned
-  prompt path, shared with `/plan` Gate #1.
+[`/plan`](plan.md), [`helpers/deliver-story.md`](helpers/deliver-story.md) (the
+engine), [`helpers/deliver-light.md`](helpers/deliver-light.md) (the unplanned
+prompt path, shared with `/plan` Gate #1).

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

@@ -76,7 +76,7 @@ the primary file the finding lives in:]
 ### `path/to/primary-file.ext` — [Short title of the issue]
 
 - **Dimension:** [the lens-specific dimension — see the lens's own list]
-- **Severity:** [Critical | High | Medium | Low]
+- **Severity:** [Critical | High | Medium | Low | Info]
 - **Location:** `path/to/primary-file.ext:line`
 - **Current State:** [the specific file/line/module and why it is problematic]
 - **Recommendation & Rationale:** [how to remediate and why it matters]
@@ -89,11 +89,18 @@ the primary file the finding lives in:]
 
 ## Severity scale {#severity-scale}
 
-Every finding grades its severity (labelled `Severity` or `Impact`) on this
-ordered scale. `parse-audit-md.js` recognizes every level, and a surviving
-**Critical** finding halts the delivery gate
+Every finding grades its severity (labelled `Severity` or `Impact`) on the
+ordered scale below. **The code owns this vocabulary**: it is defined in
+[`lib/findings/severity.js`](../../scripts/lib/findings/severity.js)
+(`SEVERITIES`), and every level here — including its accepted spellings — comes
+from that module. A surviving **Critical** finding halts the delivery gate
 (`lib/audit-suite/findings.js#hasSurvivingCritical`).
 
+Grade on **exactly** these five levels. A level of your own invention does not
+parse: it resolves to no severity, tallies as `unknown`, and the finding is
+dropped by every severity-filtered run — including the most permissive one. A
+dropped finding is indistinguishable from a finding you never wrote.
+
 - **Critical** — an active, exploitable, or data-losing defect that must be
   fixed before the change can ship (e.g. a leaked secret, an auth bypass, a
   guaranteed production outage or data-loss path).
@@ -102,6 +109,11 @@ ordered scale. `parse-audit-md.js` recognizes every level, and a surviving
 - **Medium** — a real problem worth scheduling; contained blast radius, or a
   reasonable workaround exists.
 - **Low** — minor or cosmetic; fix opportunistically.
+- **Info** — the canonical floor: a real, grounded observation worth recording
+  that asks for no scheduled work (a documented deviation worth noting, a
+  measurement that is fine today and worth watching). Accepts `Informational`.
+  Use it instead of inventing a below-`Low` word of your own; a finding that
+  cannot clear the evidence bar below is **dropped**, not filed as `Info`.
 
 ## Self-cross-check (mandatory — filter false positives before you finalize) {#self-cross-check}
 
@@ -149,6 +161,15 @@ that rests on one of them:
 - **Style-only nits already enforced by a formatter/linter** — do not
   re-litigate what the committed tooling already governs.
 
+> **Boundary with the dead-wiring mandate.** The architecture and quality lenses
+> are required to report shipped seams with no live production caller (their own
+> bodies carry the mandate). The exclusions above **bound** that mandate rather
+> than cancelling it: a test seam, a CLI entry point, a declared `exports`
+> surface, or a dynamically-reached symbol is still never a finding. What the
+> mandate targets is the case none of those cover — an **internal** seam that a
+> delivery shipped and nothing in production ever calls. When a candidate is
+> genuinely one of the exclusions, cite the exclusion and drop it.
+
 ### Final re-open-and-drop pass (mandatory)
 
 1. Walk your Detailed Findings once more, applying the bar and the exclusion

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

@@ -14,6 +14,20 @@ it is the mechanics an operator consults when the matching lever is engaged.
 
 ## Sequencing edge cases (`stories-wave-tick.js`)
 
+**What "discovered, not declared" means concretely.** `resolve-stories.js` reads
+the graph from live state as the union of the Story bodies' `depends_on` edges
+and GitHub's native `blocked_by` edges, resolving each blocker against its real
+issue state rather than against anything you hand it. That is why there is no
+batch label to pass and why a blocker that landed in an unrelated run is simply
+seen as done.
+
+**Resuming an exit-4 `blocked`.** Read the friction comment with
+`gh issue view <id> --comments`, and resume only once the operator has
+unblocked it:
+`node .agents/scripts/update-ticket-state.js --ticket <id> --state agent::ready`.
+Do not poll the label yourself while waiting — the HITL pause is the operator's
+turn, not a slow beat.
+
 Each beat re-probes live state: it re-resolves the graph, classifies **done**
 (`agent::done` or a closed issue — including foreign blockers that landed in
 another run), and derives **in-flight** from live `agent::executing` /
@@ -88,9 +102,10 @@ exposes agent dispatch, spawn each ready Story as its own
 `subagent_type: story-worker` sub-agent — it boots on the role-scoped
 [`story-worker`](../../agents/story-worker.md) context (its own system prompt, no
 `CLAUDE.md` @-closure) carrying the load-bearing delivery MUSTs standalone. The
-sub-agent executes [`deliver-story.md`](deliver-story.md) end to end
-(init → implement → acceptance self-eval → close-and-land). Thread into its
-prompt: `storyId`; `docsDigestPath` (the per-run docs digest, null when
+sub-agent executes [`deliver-story.md`](deliver-story.md) Steps 0–2.5
+(init → implement → acceptance self-eval → **push**) and stops there; **you**
+own Step 3, serialized — see `/deliver` § Closing what the workers hand back.
+Thread into its prompt: `storyId`; `docsDigestPath` (the per-run docs digest, null when
 `project.docsContextFiles` is unset); `checklistPath` (the footprint-matched
 write-time audit checklist, produced at dispatch, below); and the
 **change-set discipline** — the worker computes the change set once with