mandrel 2.54.0 → 2.55.0

package/.agents/scripts/stories-wave-tick.js

@@ -55,8 +55,8 @@
  *     inFlight: number,
  *     cycleError: string | null,
  *     wedged: { reason, stories: [{ id, unmetBlockers }] } | null,
- *     inFlightReservation: { available, withheld: [{ id, blockedBy, reason, source, paths }], note },
- *     footprintGuard: { mode, withheld: [{ id, blockedBy, scope, source, paths }], advisory, note }
+ *     inFlightReservation: { available, withheld: [{ id, blockedBy, reason, source, paths, attribution }], note },
+ *     footprintGuard: { mode, withheld: [{ id, blockedBy, scope, source, paths, attribution }], advisory, note }
  *   }
  *
  * `inFlightReservation` reports the cross-beat half of the co-dispatch guard
@@ -130,7 +130,10 @@ import { AGENT_LABELS } from './lib/label-constants.js';
 import { parseIds } from './lib/orchestration/resolve-stories.js';
 import { buildStoryAdjacency } from './lib/story-adjacency.js';
 import { expandIdList } from './lib/util/parse-id-list.js';
-import { OVERLAP_SOURCES } from './lib/wave-runner/footprint.js';
+import {
+  OVERLAP_SOURCES,
+  renderScrapeAttribution,
+} from './lib/wave-runner/footprint.js';
 import {
   createProbeContext,
   probeLiveState,
@@ -237,7 +240,10 @@ Output envelope:
           "blockedBy": 4949,
           "reason": "in-flight-earlier-beat",
           "source": "declared-overlap",
-          "paths": ["lib/shared.js"]
+          "paths": ["lib/shared.js"],
+          "attribution": [
+            { "path": "lib/shared.js", "declared": true, "fields": [] }
+          ]
         }
       ],
       "note": "..."
@@ -250,7 +256,14 @@ Output envelope:
           "blockedBy": 4951,
           "scope": "beat",
           "source": "scraped-overlap",
-          "paths": ["lib/other.js"]
+          "paths": ["lib/other.js"],
+          "attribution": [
+            {
+              "path": "lib/other.js",
+              "declared": false,
+              "fields": ["body:Verify"]
+            }
+          ]
         }
       ],
       "advisory": [],
@@ -268,7 +281,10 @@ footprintGuard names each Story withheld from THIS beat by a peer already
 admitted on it — the half that used to be an unreported skip — and every
 entry in either report carries the colliding paths plus a source tag
 (declared-overlap when both changes[] declarations named the path, else
-scraped-overlap from the text evidence). Its "mode" echoes
+scraped-overlap from the text evidence) and an "attribution" list naming, per
+path, the field the scrape read it from ("title", "spec", or "body:<section>"
+— so a path that reached the comparison only because every Story RUNS it in
+"## Verify" says so). Its "mode" echoes
 delivery.deliverRunner.footprintGuard: under "advisory" the collisions are
 detected and listed in "advisory" but never withhold, and dispatch follows the
 declared depends_on edges alone.
@@ -359,7 +375,7 @@ const RESERVATION_REASONS = Object.freeze({
  * @param {object[]|null|undefined} inFlightRecords
  * @param {Array<{id: number, blockedBy: number, source?: string, paths?: string[]}>} withheld
  * @param {Iterable<number>} [foreignHeldIds] Ids held by a foreign lease.
- * @returns {{ available: boolean, withheld: Array<{id: number, blockedBy: number, reason: string, source: string, paths: string[]}>, note: string|null }}
+ * @returns {{ available: boolean, withheld: Array<{id: number, blockedBy: number, reason: string, source: string, paths: string[], attribution: object[]}>, note: string|null }}
  */
 export function buildReservationReport(
   inFlightRecords,
@@ -390,6 +406,7 @@ export function buildReservationReport(
       : RESERVATION_REASONS.EARLIER_BEAT,
     source: w.source ?? OVERLAP_SOURCES.DECLARED,
     paths: w.paths ?? [],
+    attribution: w.attribution ?? [],
   }));
   return {
     available: true,
@@ -421,12 +438,16 @@ export function buildReservationReport(
  */
 export function buildFootprintGuardReport(footprintWithholds, mode) {
   const ledger = Array.isArray(footprintWithholds) ? footprintWithholds : [];
-  const project = ({ id, blockedBy, scope, source, paths }) => ({
+  const project = ({ id, blockedBy, scope, source, paths, attribution }) => ({
     id,
     blockedBy,
     scope,
     source,
     paths,
+    // Story #5265: the per-path field attribution rides the entry itself, so
+    // a consumer reading the envelope never has to re-derive where a scraped
+    // path came from (and cannot get a different answer than the note did).
+    attribution: attribution ?? [],
   });
   const beat = ledger
     .filter((w) => w.scope === WITHHOLD_SCOPES.BEAT && w.enforced)
@@ -453,10 +474,11 @@ export function buildFootprintGuardReport(footprintWithholds, mode) {
 function footprintGuardNote(beat, advisory, mode) {
   const detail = (entries) =>
     entries
-      .map(
-        (w) =>
-          `#${w.id} ← #${w.blockedBy} on ${w.paths.join(', ')} (${w.source})`,
-      )
+      .map((w) => {
+        const scraped = renderScrapeAttribution(w.attribution);
+        const provenance = scraped ? `, scraped from ${scraped}` : '';
+        return `#${w.id} ← #${w.blockedBy} on ${w.paths.join(', ')} (${w.source}${provenance})`;
+      })
       .join('; ');
   if (beat.length > 0) {
     return (
@@ -465,7 +487,9 @@ function footprintGuardNote(beat, advisory, mode) {
       `Each is still eligible and re-admits on a later beat once its peer ` +
       `lands. A ${OVERLAP_SOURCES.SCRAPED} source means the collision came ` +
       `from path evidence in the Story text rather than from either ` +
-      `changes[] declaration.`
+      `changes[] declaration — the 'scraped from' clause names the field ` +
+      `each such path was read out of, so a path only cited in '## Verify' ` +
+      `is distinguishable from an unpredicted edit target.`
     );
   }
   if (advisory.length > 0) {

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

@@ -51,6 +51,17 @@ to that declared tally. A mismatch — or a missing tally line — means the rep
 is not trustworthy: a finding was malformed, a severity did not resolve onto the
 canonical scale, or the lens truncated its own output.
 
+The line is read **from the Executive Summary**, and a report declaring it more
+than once fails as `duplicate-tally` naming both lines rather than adopting
+whichever the scan reached first. Prose elsewhere in the report that quotes the
+tally format is a second declaration as far as the check is concerned; move it
+or reword it.
+
+A `###` heading with no severity axis and no field bullets is read as a
+**grouping header**, not as a finding — so a lens that emits `### Robust` with
+`_No findings._` under it contributes zero findings and still cross-checks
+against a zero tally.
+
 `--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
@@ -70,6 +81,10 @@ stop surprising you:
 node .agents/scripts/audit-to-stories.js --auto --dry-run
 ```
 
+`--severity` is validated against the canonical scale: a typo (`--severity Hgh`)
+exits non-zero naming the accepted levels rather than silently widening the run
+to every finding.
+
 `--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
@@ -94,11 +109,24 @@ 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
+1. refuses, naming its step, if HEAD is not the base branch or there is no
+   `origin` — before writing anything,
+2. creates `chore/audit-ledger-<YYYY-MM-DD>-<shortsha>` from `origin/<base>`,
+3. 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.
+4. pushes the branch,
+5. opens a PR against your base branch, and
+6. puts the checkout back on the branch it started from.
+
+It prints one line on stderr saying what happened: the branch and the PR URL on
+success, or the skip reason otherwise.
+
+**It is re-runnable.** The `<shortsha>` is the base commit, so a retry on the
+same day does not collide with the branch a failed run left behind — it
+recognises it. A ledger already committed on an **unpushed** ledger branch
+resumes at the push rather than reporting `ledger-unchanged` (the ledger file is
+clean: it is committed, just not pushed). Across a failed push and its retry you
+get exactly one PR.
 
 **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
@@ -123,8 +151,10 @@ 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
+Do not point `/mandrel-deliver` at a freshly-filed audit Story — and as of the
+label guard below, you cannot: `resolve-stories.js` refuses a Story carrying no
+`agent::*` label, naming this step, unless `--allow-unlabelled` is passed. 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
@@ -172,6 +202,10 @@ to mint labels no taxonomy defines.
 | --- | --- | --- |
 | 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 |
+| `--ledger-commit failed at step "..."` | git or `gh` failed at the named step | Fix the cause and re-run; a retry resumes rather than duplicating, and the summary above it is still valid |
+| `--ledger-commit failed at step "verify-base-branch"` | HEAD is on a feature branch | Check out the base branch and re-run; nothing was committed |
+| `[resolve-stories] ... carries no "agent::*" label` | An unenriched audit Story was named for delivery | Plan it (Step 5), or pass `--allow-unlabelled` deliberately |
+| `[audit-to-stories] --severity "..." is not a severity` | A typo in the floor | Use one of the canonical levels |
+| `duplicate-tally` in `summary.reportFailures[]` | The report declares the tally twice | Reword the prose copy; the Executive Summary line is the declaration |
 | 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-accessibility.md

@@ -82,9 +82,9 @@ the project is configured.** Before any detection:
 - **Design tokens:** the colour tokens (`tailwind.config.*`, CSS custom
   properties, a theme object) whose literal values you need to compute contrast
   ratios statically.
-- **Runtime target (optional):** the `qa.environments` map (see
-  [_Runtime verification mode_](#step-2-runtime-verification-mode-optional-corroboration))
-  and the navigability route SSOT.
+- **Runtime target (optional):** whatever the shared runtime scaffold in
+  [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md#runtime-pass)
+  resolves. Note only whether one exists; the scaffold owns how it is found.
 
 Record what exists. Every finding downstream is measured against _this
 discovered surface and config_, not a generic ideal. If **no** frontend surface
@@ -135,31 +135,16 @@ Cover every static WCAG dimension:
 
 ## Step 2: Runtime verification mode (optional corroboration)
 
-Static detection is the default and always runs. The runtime pass is
-**conditional** — it runs only when a live target is configured; its absence
-never blocks the static report.
-
-1. **Resolve the target from config — never a hardcoded URL.** Resolve the
-   target through the consumer's `qa.environments.<env>.baseUrl` (via
-   [`resolveQaEnvironment`](../scripts/lib/qa/resolve-qa-contract.js), the same
-   resolver `/qa-run` uses): an `<env>` argument resolves by exact name or
-   origin match; with no argument, enumerate `name → baseUrl` and let the
-   operator pick. If **no** `qa.environments` target is configured, **skip this
-   step** and note in the report that runtime corroboration was unavailable —
-   do not invent a URL and do not start an arbitrary dev server.
-2. **Sample routes from the navigability SSOT.** Draw the routes to exercise
-   from the consumer's route/nav registry (`planning.navigation.navRegistry` /
-   `routeGlobs` — the same SSOT [`/audit-navigability`](audit-navigability.md)
-   reads), sampling a representative set (key personas' landing routes plus any
-   route in the change-set scope) rather than a single hardcoded page.
-3. **Run an accessibility engine per sampled route.** Use the
-   `mcp__chrome-devtools__lighthouse_audit` tool's **Accessibility category**,
-   or run **axe** via the browser tooling, against each sampled `baseUrl`-rooted
-   route. Prefer a production-mode build.
-4. **Median-of-3 or provisional.** Any runtime score or metric is subject to
-   run-to-run variance: capture a **median-of-3** (three runs per route, report
-   the median) before treating a number as authoritative. A single-run value is
-   reported **provisional** and never drives a Critical/High verdict on its own.
+Run the shared runtime scaffold in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md#runtime-pass) — it
+owns target resolution, route sampling, median-of-3, and the two skip reasons
+(no configured target; browser tooling unavailable). This lens's probe is its
+step 3:
+
+- **Run an accessibility engine per sampled route.** Use the
+  `mcp__chrome-devtools__lighthouse_audit` tool's **Accessibility category**, or
+  run **axe** via the browser tooling, against each sampled `baseUrl`-rooted
+  route. Prefer a production-mode build.
 
 Corroborate static findings against the runtime results (a statically-flagged
 contrast defect confirmed by the engine graduates from provisional to
@@ -168,8 +153,8 @@ confirmed), and surface runtime-only violations the static pass could not see.
 ## Report additions
 
 Beyond the shared skeleton, the Executive Summary states the runtime mode's
-status (ran against `<env>` / skipped — no target configured), and the report
+status (ran against `<env>`, or the scaffold's skip reason), and the report
 ends with a **Runtime Verification** section: per-route median-of-3
-accessibility scores when the runtime mode ran, or "_Runtime corroboration
-unavailable — no `qa.environments` target configured._" Drop every claimed
+accessibility scores when the runtime mode ran, or that skip reason verbatim.
+Drop every claimed
 violation that names no concrete element and no specific WCAG success criterion.

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

@@ -88,9 +88,9 @@ what they declare:
   explicit `viewport`, a Cypress `viewportWidth`/`viewportHeight`, a
   visual-regression viewport list. This is the project's own statement of which
   form factors it holds itself to.
-- **Runtime target (optional):** the `qa.environments` map (see
-  [*Runtime viewport pass*](#step-3-runtime-viewport-pass-optional-corroboration))
-  and the navigability route SSOT.
+- **Runtime target (optional):** whatever the shared runtime scaffold in
+  [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md#runtime-pass)
+  resolves. Note only whether one exists; the scaffold owns how it is found.
 
 Record the breakpoints, the viewport contract, and the device matrix. Every
 finding downstream is measured against *this discovered baseline*. If the
@@ -192,37 +192,20 @@ fix is a new test, name the viewport and the assertion it should make, not just
 
 ## Step 3: Runtime viewport pass (optional corroboration)
 
-Static detection is the default and always runs. The runtime pass is
-**conditional** — it runs only when a live target is configured; its absence
-never blocks the static report.
-
-1. **Resolve the target from config — never a hardcoded URL.** Resolve the
-   target through the consumer's `qa.environments.<env>.baseUrl` (via
-   [`resolveQaEnvironment`](../scripts/lib/qa/resolve-qa-contract.js), the same
-   resolver `/qa-run` uses): an `<env>` argument resolves by exact name or
-   origin match; with no argument, enumerate `name → baseUrl` and let the
-   operator pick. If **no** `qa.environments` target is configured, **skip this
-   step** and note in the report that runtime corroboration was unavailable —
-   do not invent a URL and do not start an arbitrary dev server.
-2. **Sample routes from the navigability SSOT.** Draw the routes to exercise
-   from the consumer's route/nav registry (`planning.navigation.navRegistry` /
-   `routeGlobs` — the same SSOT [`/audit-navigability`](audit-navigability.md)
-   reads), sampling a representative set (key personas' landing routes plus any
-   route in the change-set scope) rather than a single hardcoded page.
-3. **Drive two form factors per route.** Emulate a **phone** and a **tablet**
-   viewport — `mcp__chrome-devtools__emulate` for a device profile, or
-   `resize_page` for an explicit width/height — then, per route and viewport:
-   take a screenshot, and evaluate the two observables static analysis cannot
-   resolve — whether `document.scrollingElement.scrollWidth` exceeds the
-   viewport width (horizontal overflow), and the rendered box of the
-   interactive controls Step 1 flagged as candidates. Reload after switching
-   form factor so load-time device gates re-run.
-4. **Median-of-3 or provisional.** Any runtime measurement is subject to
-   run-to-run variance: capture a **median-of-3** (three runs per route, report
-   the median) before treating a number as authoritative. A single-run value is
-   reported **provisional** and never drives a Critical/High verdict on its own.
-5. **Leave the viewport as you found it.** Reset the emulation before finishing
-   so a following lens or QA run does not inherit a phone viewport.
+Run the shared runtime scaffold in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md#runtime-pass) — it
+owns target resolution, route sampling, median-of-3, and the two skip reasons
+(no configured target; browser tooling unavailable). This lens's probe is its
+step 3:
+
+- **Drive two form factors per route.** Emulate a **phone** and a **tablet**
+  viewport — `mcp__chrome-devtools__emulate` for a device profile, or
+  `resize_page` for an explicit width/height — then, per route and viewport:
+  take a screenshot, and evaluate the two observables static analysis cannot
+  resolve — whether `document.scrollingElement.scrollWidth` exceeds the viewport
+  width (horizontal overflow), and the rendered box of the interactive controls
+  Step 1 flagged as candidates. Reload after switching form factor so load-time
+  device gates re-run.
 
 Corroborate static findings against the runtime observations (a statically
 flagged fixed width confirmed by a real horizontal overflow graduates from
@@ -233,10 +216,10 @@ that opens off-screen.
 ## Report additions
 
 Beyond the shared skeleton, the Executive Summary states the runtime mode's
-status (ran against `<env>` / skipped — no target configured) and names the
+status (ran against `<env>`, or the scaffold's skip reason) and names the
 narrowest breakpoint the project declares, so a reader can tell what "mobile"
 meant for this run. The report ends with a **Runtime Viewport Pass** section:
-per-route, per-form-factor observations when the runtime mode ran, or
-"*Runtime corroboration unavailable — no `qa.environments` target configured.*"
+per-route, per-form-factor observations when the runtime mode ran, or the
+scaffold's skip reason verbatim.
 Drop every claimed finding that names no concrete element, style rule, or test
 file.

package/.agents/workflows/git-cleanup.md

@@ -5,7 +5,7 @@ description: >-
   `git stash` entries — each step gated by operator confirmation.
 ---
 
-# /git-cleanup [--fast-forward-main] [--prune-remotes] [--branches] [--stashes] [--execute] [--remote] [--yes] [--drop-stashes <ref>] [--exclude <pattern>] [--json]
+# /git-cleanup [--fast-forward-main] [--prune-remotes] [--branches] [--stashes] [--execute] [--remote] [--yes] [--include-content-merged] [--drop-stashes <ref>] [--exclude <pattern>] [--json]
 
 `/git-cleanup` folds the four cleanup steps operators routinely run by hand
 after a busy session into a single pipeline with per-step confirmation. It is a
@@ -36,7 +36,7 @@ flags: `node .agents/scripts/git-cleanup.js --help`.
 | --- | --- | --- |
 | **fast-forward-main** | `git fetch origin <base>` then `git merge --ff-only origin/<base>`. | Skipped silently on a dirty tree or a non-fast-forward; otherwise prompts `Fast-forward main by N commit(s)?`. Checks out `<base>` first when HEAD is elsewhere and does **not** restore the prior branch. |
 | **prune-remotes** | `git fetch --prune origin` to drop `refs/remotes/origin/*` GitHub already deleted. | Prompts before pruning. Runs as its own phase regardless of `--remote`. |
-| **branches** | Reaps merged local branches (squash-aware: merged-PR, git-ancestry, and content-equivalence signals), removing an attached worktree first. Also enumerates **remote-only** merged branches. | Prints the candidate list, then prompts `Reap N merged branch(es)?`. `--remote` is required **on top of** `--execute` to delete any `origin/<branch>`. `content-merged` candidates carry a weaker-signal warning. |
+| **branches** | Reaps merged local branches (squash-aware: merged-PR, git-ancestry, and content-equivalence signals), removing an attached worktree first. Also enumerates **remote-only** merged branches. | Prints the candidate list, then prompts `Reap N merged branch(es)?`. `--remote` is required **on top of** `--execute` to delete any `origin/<branch>`. `content-merged` candidates carry a weaker-signal warning, and under `--yes` their **remote** ref is withheld unless `--include-content-merged` is passed (their local ref still goes — it is recoverable from the remote). |
 | **stashes** | Lists every stash and triages it. | Interactive: `drop / keep / quit` per entry (default `keep`). Under `--yes` / `--json`, drops require an explicit `--drop-stashes <ref>` allowlist (repeatable) — there is no "drop all". |
 
 ## Constraint
@@ -49,6 +49,14 @@ Two consequences the flag list alone does not carry: `--remote` deletions cannot
 be undone without re-pushing, and `--exclude '<pattern>'` is the **only** way to
 protect an in-scope merged-PR branch you want to keep.
 
+That irreversibility is why `--yes` and `content-merged` do not combine on their
+own. Content-equivalence says "applying this branch to the base changes nothing"
+— which is true of a squash-merged branch and equally true of one whose every
+change was reverted. An operator answering the prompt sees the weaker-signal
+note and decides; an unattended run has nobody to decide, so it withholds the
+remote delete and says so, and `--include-content-merged` is the decision made
+in advance.
+
 Do **not** run with `--execute` if there is unmerged work that needs saving. The
 fast-forward phase skips on a dirty tree (safe), but the branches phase reaps any
 merged-PR branch in scope unless `--exclude`d.
@@ -59,9 +67,15 @@ merged-PR branch in scope unless `--exclude`d.
 # Preview all four phases (no mutation).
 node .agents/scripts/git-cleanup.js
 
-# Run everything non-interactively, including origin refs.
+# Run everything non-interactively, including origin refs. Branches detected
+# only by content-equivalence keep their origin ref — see the note below.
 node .agents/scripts/git-cleanup.js --execute --remote --yes
 
+# Same, but also delete the origin refs of content-merged branches. Nobody is
+# watching, so opting in is the whole confirmation this delete ever gets.
+node .agents/scripts/git-cleanup.js --execute --remote --yes \
+  --include-content-merged
+
 # Only fast-forward main.
 node .agents/scripts/git-cleanup.js --fast-forward-main --execute
 

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

@@ -208,6 +208,51 @@ extracted and names any disagreement as a **report failure**
 report whose line is missing or wrong. A parse that silently drops findings is
 otherwise indistinguishable from a clean audit.
 
+## Runtime pass scaffold {#runtime-pass}
+
+Some lenses corroborate their static findings against a live target. Static
+detection is the default and always runs; the runtime pass is **conditional** —
+it runs only when a live target and the browser tooling are both available, and
+its absence never blocks the static report. The steps below are shared by every
+lens that has one, so a lens documents only its own probe.
+
+1. **Resolve the target from config — never a hardcoded URL.** Resolve through
+   the consumer's `qa.environments.<env>.baseUrl` (via
+   [`resolveQaEnvironment`](../../scripts/lib/qa/resolve-qa-contract.js), the
+   same resolver `/qa-run` uses): an `<env>` argument resolves by exact name or
+   origin match; with no argument, enumerate `name → baseUrl` and let the
+   operator pick.
+2. **Sample routes from the navigability SSOT.** Draw the routes to exercise
+   from the consumer's route/nav registry (`planning.navigation.navRegistry` /
+   `routeGlobs` — the same SSOT
+   [`/audit-navigability`](../audit-navigability.md) reads), sampling a
+   representative set (key personas' landing routes plus any route in the
+   change-set scope) rather than a single hardcoded page.
+3. **Run the lens's own probe** against each sampled route. That step, and only
+   that step, is the lens's to document.
+4. **Median-of-3 or provisional.** Any runtime measurement is subject to
+   run-to-run variance: capture a **median-of-3** (three runs per route, report
+   the median) before treating a number as authoritative. A single-run value is
+   reported **provisional** and never drives a Critical/High verdict on its own.
+5. **Leave the environment as you found it.** Reset any emulation — viewport,
+   device profile, colour scheme — before finishing, so a following lens or QA
+   run does not inherit it.
+
+**Skip reasons, and how to report them.** The pass is skipped, never faked, for
+either of two reasons, and the Executive Summary says which:
+
+| Condition | Reported as |
+| --- | --- |
+| No `qa.environments` target is configured | `skipped — no target configured` |
+| The browser tooling is unavailable in this runtime | `skipped — browser tooling unavailable` |
+
+The second is the one an unattended sweep meets: a scheduled run has no browser
+MCP server attached, so a lens that treated "cannot drive" as "nothing found"
+would report a clean runtime section it never ran. Do not invent a URL, do not
+start an arbitrary dev server, and do not fall back to a static-only claim
+dressed as a runtime one — name the skip and let the static findings stand on
+their own.
+
 ## Execution strategy {#execution-strategy}
 
 A lens is a self-contained, read-only unit of work — exactly the shape a

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

@@ -107,11 +107,12 @@ Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
 
 ## 5. The one creditable full-suite run
 
-**After the self-eval loop's last fix commit, immediately before the push** —
-the credit is keyed on the tree, so any later commit invalidates it. Redraft
-rounds run scoped tests; only this final run needs credit, and a bare
-`npm test` / `pnpm run test` deposits **none**, so close re-runs it. Shape it
-by what `close-validation/gates.js` runs:
+**After the self-eval loop's last fix commit, immediately after the push** —
+the credit is keyed on the tree, not push state: a later commit voids it, a
+push does not, and the backgrounded capture (below) ends the turn. Redraft
+rounds run scoped tests; only this run needs credit, and a bare `npm test` /
+`pnpm run test` deposits **none**, so close re-runs it. Shape it by what
+`close-validation/gates.js` runs:
 
 ```bash
 # CRAP gate on (default) + a `test:coverage` script — writes close's stamp:
@@ -127,7 +128,7 @@ Dispatch it in the **background**: it outruns the host's sync Bash ceiling, and
 Rule 2).
 
 Read the **output**, not the exit code: capture skips — no test run, no
-credit — when nothing changed under the CRAP `targetDirs`. Run the scoped
+credit — when nothing changed under CRAP `targetDirs`. Run the scoped
 projects for the roots you changed plus `verify[]`, not the whole suite.
 
 `verify[]` is scoped entries **plus** this one run: an entry that is itself a

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

@@ -49,6 +49,13 @@ 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.
 
+**A Story with no `agent::*` label is refused.** The audit sweep files Stories
+deliberately without one — their bodies are audit prose, not a scoped change
+with verifiable acceptance criteria — so resolving one means dispatching a
+worker at an unenriched body, after taking its lease. Route it through
+`/mandrel-plan` first, which applies `agent::ready` at the end of planning.
+`--allow-unlabelled` is the deliberate escape hatch.
+
 **The non-zero exit codes.** **2** — `cycleError`: the graph is
 self-referential; fix `depends_on`, do not retry. **3** — `wedged`: nothing
 dispatchable and nothing in flight, with the undone Stories and their unmet
@@ -292,10 +299,10 @@ 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` — **reports** which container Epics this run closed and which
-  are still pending. It derives nothing itself: every step here and the
-  per-Story land tail alike delegate to `epic-rollup.js`, so one rule decides
-  a container's state.
+- `epic-close` — **reports** which of the run's container Epics its land tails
+  left closed and which are still open. **Read-only** — it derives nothing:
+  every child state change is already a rollup edge, so the container was
+  derived from a complete child set by the last Story's own land tail.
 
 A single-Story run skips the epilogue — follow-ups are captured on merge
 confirm instead (`captureStoryFollowUps`).
@@ -304,9 +311,12 @@ confirm instead (`captureStoryFollowUps`).
 
 A container Epic is never delivered, so nothing used to write to it during
 the run it was the subject of. `epic-rollup.js` derives its state from its
-children at both per-Story lifecycle edges — the `agent::executing` flip in
-`single-story-init.js` and the post-land tail (reported as the tail's
-`epicRollup` step) — which is why it holds at **N=1**, where no epilogue runs.
+children at **every edge that changes a child's state** — the
+`agent::executing` flip in `single-story-init.js`, the post-land tail
+(reported as the tail's `epicRollup` step), and `plan-persist`'s supersede
+close (reported as `supersede.epicRollup`) — which is why it holds at **N=1**,
+where no epilogue runs, and why a cohort superseded by a re-plan no longer
+strands its container open above finished work.
 
 - **Status** follows the children's composition (`deriveParentState` mapped
   onto the board's three options): any **open** child executing or blocked →
@@ -319,13 +329,24 @@ children at both per-Story lifecycle edges — the `agent::executing` flip in
   ready list.
 - **Owner** — `github.operatorHandle` is added to the Epic while any child is
   in flight, through the additive assignees endpoint, and is never removed.
-- **Closure** is one-way: every child landed closes the container as
-  `completed`; a reopened child moves Status back to `In Progress` and does
-  **not** reopen it.
-- The parent lookup scans open `type::epic` issues, because linkage is
-  parent→child only, and reads children as the body checklist **union** the
-  native sub-issue edges — the same reader `/mandrel-deliver`'s expansion
-  uses, so an Epic can never be expandable but unclosable.
+- **Closure** is one-way: a container whose children are all finished closes,
+  as `completed` when at least one child landed and as `not_planned` when none
+  did (a cohort superseded by a re-plan is finished, but nothing merged). A
+  reopened child moves Status back to `In Progress` and does **not** reopen the
+  issue — which is why the lookup reads `state: 'all'`, since an open-only
+  listing cannot see the container it would have to correct.
+- The parent lookup resolves the native parent edge in **one** call
+  (`getParentIssue`), because linkage is parent→child only; it falls back to a
+  `type::epic` scan for a child linked by checklist alone. Children are read as
+  the body checklist **union** the native sub-issue edges — literally the same
+  reader `/mandrel-deliver`'s expansion uses, so an Epic can never be
+  expandable but unclosable — bounded at 5 concurrent reads.
+- A checklist row citing an id that resolves to nothing is **dropped with a
+  warning** when the native read succeeded: hand-edited prose can cite a
+  deleted or mistyped issue, and no re-run will make it resolve. An
+  unresolvable *native* edge still fails the read. An Epic-typed child is
+  refused by name (`epic-typed-child`) and neither blocks nor advances the
+  parent.
 - Every step is best-effort and never throws: a stale container costs
   tidiness, not a landed Story's envelope.
 

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

@@ -240,9 +240,10 @@ discovers them only after the whole close pipeline has run, at several times
 the cost of one full-suite run in the worktree.
 
 **Run it once, last, so close can credit it.** The run belongs **after** the
-self-eval loop's last fix commit and immediately **before** the hand-off push,
-so its stamp describes the tree that is pushed; redraft rounds run scoped
-tests. Close skips a gate that already passed at the current HEAD, but a bare
+self-eval loop's last fix commit and **after** the hand-off push — the credit
+is keyed on the tree, not on push state, so pushing first keeps the stamp and
+buys the ordering Step 2.5 needs (the capture is backgrounded, and its
+completion ends the turn); redraft rounds run scoped tests. Close skips a gate that already passed at the current HEAD, but a bare
 `npm test` deposits no such record — the suite then runs twice per delivery,
 once here and once in the close gate chain. Pick the invocation by the same
 predicate `close-validation/gates.js` uses to choose its test gate:
@@ -262,7 +263,9 @@ The credit expires the moment it stops describing the tree: evidence is keyed
 on HEAD, the capture stamp on a content digest of `crap.targetDirs`. A
 self-eval fix — or any commit — invalidates it and close re-runs the suite for
 real, so this never trades away the gate. That keying is exactly why the run
-comes last.
+comes last, and why the push before it is free. Close's own base-sync can
+spend the stamp too when it lands base commits; it now says so out loud rather
+than silently re-running the suite.
 
 **`verify[]` reuses the same stamp.** A `verify[]` entry that is itself a
 full-suite command is reported **credited** against that stamp rather than

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

@@ -93,18 +93,21 @@ 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.
 
-### Step 2.5 — The creditable full-suite run, then push and hand off
-
-Run the full suite **once**, after the self-eval loop's last fix commit and
-immediately **before** the push, in the shape close credits (**digest § 5**):
-the credit is keyed on the tree, so any later commit invalidates it, and a bare
-`npm test` deposits none. Red → fix, commit, re-run. An inline run makes the
-same run before Step 3.
-
-Then (sub-agent dispatch only) push `story-<storyId>` to `origin`, confirm the
-remote ref moved, and return the hand-off — Story id, `workCwd`, branch, pushed
-head SHA, self-eval verdict, `verify[]` evidence — then stop. Do not open the
-PR; do not compose a terminal envelope.
+### Step 2.5 — Push, then the creditable full-suite run, then hand off
+
+**Push first.** After the self-eval loop's last fix commit, push
+`story-<storyId>` to `origin`, confirming the remote ref moved: the capture
+below is backgrounded, so *its* completion ends the turn.
+
+Then run the full suite **once**, after the push, in the shape close credits
+(**digest § 5**): the credit is keyed on the tree, not on push state, so only
+a *later* commit invalidates it; a bare `npm test` deposits none. Red →
+fix, commit, push, re-capture.
+
+Then (sub-agent dispatch only) return the hand-off — Story id, `workCwd`,
+branch, pushed head SHA, self-eval verdict, `verify[]` evidence — and stop.
+Do not open the PR or compose a terminal envelope. An inline run captures
+before Step 3.
 
 ## Step 3 — Close and land (`single-story-close.js`)