mandrel 2.24.0 → 2.26.0

package/.agents/skills/core/gates-and-baselines/SKILL.md

@@ -18,7 +18,7 @@ allowed_tools:
 - **No gate may be skipped.** Failing lint means fix lint, not disable the rule; a failing test means fix the code, not `.skip` or delete the test. Gates are ordered shift-left so cheap checks fail first, and CI failure output is fed back verbatim with the directive to reproduce and fix locally before re-pushing.
 - **Introducing a gate that asserts on pre-existing state** (doc-drift, lint-vocabulary, dependency-cycle, missing-coverage) MUST land green at merge: either advisory-first (report-only until the backlog is burned down) or with the populated baseline committed in the same change that turns the gate on. Never wire a gate into `requiredChecks` that lands red on latent findings nobody authored.
 - **Refresh a baseline only when the change is deliberate** — a rename/move, an operator-approved complexity bump, a signed-off perf delta, an intentional API-surface change. Never refresh to paper over an unintentional regression; fix the regression instead.
-- Run the kind-specific refresh (`npm run crap:update` / `npm run maintainability:update`; dead-exports and lighthouse have no npm script — regenerate the rows and edit `baselines/dead-exports*.json` / `baselines/lighthouse.json` directly) on the **Story branch**, not on `main`.
+- **Pick the refresh that matches why you are refreshing** — the two are different scopes, and the wrong one silently no-ops. `npm run <kind>:update` is **diff-scoped**: it re-scores only files changed in `origin/main..HEAD` and preserves every other row verbatim. That is what you want after changing code. `npm run <kind>:reanchor` is the same script with `--full-scope`: it re-scores every file in every target dir. That is what you want when the baseline is **stale** — a scorer-version bump, a coverage-shape change, accumulated drift — because a diff-scoped run would leave the stale rows exactly as they were and the staleness finding would re-fire. Kinds: `coverage`, `crap`, `maintainability`, `duplication`; dead-exports and lighthouse have no npm script — regenerate the rows and edit `baselines/dead-exports*.json` / `baselines/lighthouse.json` directly. Run either on the **Story branch**, not on `main`.
 - Verify the refresh diff is scoped to the relevant `baselines/<kind>.json` (plus cosmetic `package-lock.json` churn only). If unrelated files appear, STOP — the refresh is contaminated. Stage baseline files **explicitly** (`git add baselines/<kind>.json`); never `git add -A` in a refresh commit.
 - Commit-subject contract: a **Conventional-Commits** subject `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story that triggered it.
 - Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Story: #<storyId>` to the body whenever observability classification matters. Never pass `--no-verify`; the `commit-msg` hook (commitlint) MUST run and pass.
@@ -95,18 +95,24 @@ own as the parseable marker for any future reader.)
 
 ### Procedure
 
-| Kind            | Update command                   |
-| --------------- | -------------------------------- |
-| CRAP            | `npm run crap:update`            |
-| Maintainability | `npm run maintainability:update` |
-| Dead-exports    | edit `baselines/dead-exports.json` / `baselines/dead-exports-production.json` (rows are `(file, symbol)`; `check-dead-exports.js --json` prints the current rows) |
-| Lighthouse      | edit `baselines/lighthouse.json`  |
-
-1. **Run the matching update command** on the Story branch (HEAD must already be
-   the Story branch, not `main`).
+| Kind            | After a code change (diff-scoped)  | Stale baseline (full re-anchor)      |
+| --------------- | ---------------------------------- | ------------------------------------ |
+| CRAP            | `npm run crap:update`              | `npm run crap:reanchor`              |
+| Maintainability | `npm run maintainability:update`   | `npm run maintainability:reanchor`   |
+| Coverage        | `npm run coverage:update`          | `npm run coverage:reanchor`          |
+| Duplication     | `npm run duplication:update`       | `npm run duplication:reanchor`       |
+| Dead-exports    | edit `baselines/dead-exports.json` / `baselines/dead-exports-production.json` (rows are `(file, symbol)`; `check-dead-exports.js --json` prints the current rows) | same — no scope flag applies |
+| Lighthouse      | edit `baselines/lighthouse.json`   | same — no scope flag applies         |
+
+1. **Run the matching command for your reason** — left column after a code
+   change, right column for a stale baseline — on the Story branch (HEAD must
+   already be the Story branch, not `main`).
 2. **Verify the diff is scoped** to the relevant `baselines/<kind>.json` (and
    possibly cosmetic `package-lock.json` churn). Unrelated files → STOP, the
-   refresh is contaminated.
+   refresh is contaminated. Judge contamination by **which files** changed, not
+   how many rows moved inside the baseline: a `:reanchor` legitimately rewrites
+   most of its own file, so say in the commit body that the breadth is a
+   re-anchor and not a mass regression.
 3. **Author the commit.** Stage the baseline file(s) explicitly, then commit with
    the Conventional-Commits subject + body trailer above:
 

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-21T13:53:23.232Z",
+  "generatedAt": "2026-08-02T11:35:53.522Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -48,7 +48,7 @@
       "category": "core",
       "path": ".agents/skills/core/diagnose-friction/SKILL.md",
       "description": "Wrap a shell command with diagnostic capture. On failure, print static suggestions and append a structured `friction` record to the per-Story signals.ndjson stream. Use whenever a script in the orchestration loop invokes a tool whose failure shape we want the analyzer to attribute.",
-      "policyCapsuleBullets": 8,
+      "policyCapsuleBullets": 9,
       "allowedTools": ["Bash", "Read"],
       "vendor": null
     },

package/.agents/templates/single-story-body.md

@@ -1,17 +1,25 @@
 # {{title}}
 
-## Context
+## Goal
 
-{{context}}
+{{goal}}
 
-## Acceptance Criteria
+## Spec
 
-{{acceptanceCriteria}}
+{{spec}}
 
-## Out of Scope
+## Changes
 
-{{outOfScope}}
+{{changes}}
 
-## Notes
+## Non-Goals
 
-{{notes}}
+{{nonGoals}}
+
+<!--
+  `acceptance[]` and `verify[]` are the ticket's top-level machine contract.
+  Author each list ONCE, at the top level (`--acceptance` / `--verify`); do
+  NOT mirror them into this body — persist synthesizes the `## Acceptance`
+  and `## Verify` sections from those arrays so the issue still reads as a
+  complete executable document.
+-->

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-baselines.md

@@ -0,0 +1,289 @@
+---
+description: Audit the committed baseline surface — dead instruments, stale baselines, cross-gate hotspot clusters, trend drift, and floor-tightening headroom — and emit findings whose remediation burns the measured debt down and tightens the ratchet behind it.
+---
+
+# Baseline & Ratchet Audit
+
+You are a Principal Engineer and Quality-Systems Owner auditing this
+repository's **committed baseline surface**: the ratchet artifacts under
+`baselines/` and the gate floors under `delivery.quality.gates` in
+`.agentrc.json`. Those instruments only prevent **regression** — nothing owns
+the loop that burns the measured debt **down** and tightens the floors behind
+it, so a repo can hold a floor it cleared years ago and never notice. This lens
+is that loop's read-only entry point. The shared lens machinery — read-only
+constraint, scope interpretation, report envelope + finding-block skeleton,
+severity scale, self-cross-check, and execution strategy — lives in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
+`{{auditOutputDir}}/audit-baselines-results.md`. Dimension values:
+`Dead Instrument | Staleness | Hotspot Cluster | Trend Drift | Tightening Headroom`.
+
+> **Value-free titles (mandatory).** A finding title MUST NOT embed a measured
+> number — write ``### `baselines/crap.json` — crap floor holds unused slack``,
+> not ``… — crap floor 13 vs measured 8``. Every re-run re-measures, so a title
+> carrying the reading changes each pass, its fingerprint changes with it, and
+> `/audit-to-stories` files a duplicate instead of deduping against the open
+> Story. Numbers belong in Current State, never in the title.
+
+## Scope
+
+Interpret this lens's change-set fence per the core's Scope interpretation:
+
+```text
+{{changedFiles}}
+```
+
+When the fence resolves to a file list, keep only Hotspot Cluster findings
+whose cluster key is in that list. The other four dimensions are properties of
+the instrument set as a whole rather than of any changed file, so report them
+only in codebase-wide mode.
+
+## Constraint (lens-specific carve-out)
+
+This lens **refines** the core's read-only constraint; it never relaxes it.
+
+- The only command it runs is the read-only engine in Step 0. It never runs a
+  test, coverage, mutation, duplication, or lint suite.
+- It never writes under `baselines/` and never edits `.agentrc.json`. It never
+  invokes an `update-*-baseline` script. **Regeneration is a finding, never an
+  in-run step** — the remediation Story owns every write to the surface.
+- Reading committed baseline rows is explicitly permitted and required: citing
+  an already-computed metric is analysis, not measurement.
+
+## Execution strategy
+
+Run this lens as a single `subagent_type: auditor` dispatch returning the report
+path + Executive Summary; sequential inline execution is the fallback (see the
+core's Execution strategy).
+
+## Step 0: Run the engine (mandatory — measure before you judge)
+
+```bash
+node .agents/scripts/audit-baselines.js --out temp/audit-baselines/envelope.json
+```
+
+Optional flags: `--cwd` (repository root), `--top-n` (outlier rows per gate,
+default 20), `--hotspot-limit` (clusters emitted, default 50), `--trend-depth`
+(baseline commits sampled per kind, default 5). Exit 0 means evidence was
+assembled **including every degraded input**; exit 1 means the envelope could
+not be built or written — report that and stop, because no evidence base
+exists to author against.
+
+The envelope is validated against
+`.agents/schemas/baselines/audit-baselines-envelope.schema.json` and is this
+lens's sole evidence base. Cite its fields by name:
+
+| Section | Fields you cite |
+| --- | --- |
+| root | `generatedAt`, `cwd`, `topN`, `configError`, `degradations` |
+| `gateSurface[]` | `kind`, `surface`, `baselinePath`, `configured`, `baselineExists`, `stub`, `rowCount`, `measured` (`unit` plus `value`), `generatedAt`, `staleDays`, `staleCommits`, `surfaceStale`, `deadIgnoreGlobs`, `parseError` |
+| `hotspots[]` | `path`, `gates` (each `kind`, `metric`, `value`, `rowCount`, `severityWeight`), `gateKinds`, `gateCount`, `severityWeight`, `churnWeight`, `centralityWeight`, `frictionWeight`, `rank` |
+| `trend[]` | `kind`, `baselinePath`, `sampleCount`, `from`, `to` (each a `sha` plus `committedAt`), `deltas` |
+| `headroom[]` | `kind`, `axis`, `floor`, `measured`, `direction`, `headroom` |
+
+`surface` is `gate` (a closed `delivery.quality.gates` kind) or `ratchet` (an
+out-of-band baseline the CI baselines job owns). `direction` is `gte` or `lte`.
+`rowCount` counts rows **after** per-file aggregation; `measured` is the
+quantity the instrument reports, in its own unit. Cite `measured` when the two
+disagree — 589 dead-export symbols sit in 187 files.
+
+Two envelope-level reads come **before** any finding:
+
+- **`configError` non-null.** Floors, target directories, and ignore globs
+  were unavailable and the engine fell back to default baseline paths. Every
+  Tightening Headroom finding would be unfounded this run: file the config
+  failure itself as one `Dead Instrument` finding and skip that dimension.
+- **`degradations`.** Each of `gitHistory`, `importGraph`, `frictionLedger`
+  reading `true` collapsed its rank multiplier to exactly 1.0, so the hotspot
+  ordering is weaker evidence. Name the degraded inputs in the Executive
+  Summary; never present a degraded rank as a churn-informed one.
+
+## Step 1: Evaluation Dimensions
+
+1. **Dead Instruments.** An instrument that cannot fail is worse than none: it
+   reads green forever and the surface it names looks governed. Four shapes,
+   read straight off `gateSurface[]`:
+   - `stub` is `true` — zero rows **and** an all-zero rollup, so the gate
+     passes vacuously. The engine requires both halves, so a ratchet with
+     genuinely nothing to report is never mistaken for a dead one.
+   - `configured` is `false` on a `gate` row — a baseline is committed but no
+     `delivery.quality.gates` block enforces it, so nothing reads it.
+   - `baselineExists` is `false`, or `parseError` is non-null — the instrument
+     cannot be read at all.
+   - `deadIgnoreGlobs` is non-empty — a configured ignore pattern matches zero
+     files. It protects nothing today and silently exempts the next file that
+     happens to match it.
+
+   Grade a stub or unenforced gate **Medium**, a `parseError` on an enforced
+   gate **High** (delivery reads that file every run), a dead glob **Low**.
+
+2. **Staleness.** Two clocks. `staleDays` is whole days since the baseline's
+   own `generatedAt`; `staleCommits` is commits touching the measured surface
+   since the baseline was last committed, with `surfaceStale` its boolean. A
+   `null` on either is never a fabricated zero — the stamp is unreadable, git
+   cannot answer, or the rows are not file paths — and is itself the finding.
+   **`surfaceStale` with `staleDays: 0` is still stale:** refreshed recently in
+   wall time, already behind the surface it scores. Grade an enforced gate
+   stale beyond roughly a month or `surfaceStale` **Medium**, a `null` stamp
+   **Medium**, an unenforced kind **Low** or **Info**.
+
+   **Regeneration is the remediation, never an in-run step.** The Agent Prompt
+   names the matching script and its one-shot acknowledgment:
+
+   | Kind | Regeneration script | Acknowledgment |
+   | --- | --- | --- |
+   | `coverage` | `npm run coverage:reanchor` | `COVERAGE_REFRESH=1` |
+   | `crap` | `npm run crap:reanchor` | `CRAP_REFRESH=1` |
+   | `duplication` | `npm run duplication:reanchor` | `DUPLICATION_REFRESH=1` |
+   | `maintainability` | `npm run maintainability:reanchor` | `MAINTAINABILITY_REFRESH=1` |
+
+   **Prescribe the `:reanchor` script, never the bare `:update` one.** Every
+   updater defaults to a **diff-scoped** refresh — only files changed in
+   `origin/main..HEAD` are re-scored, and everything else is preserved
+   verbatim. That is the right default for "I changed code, re-score what I
+   touched", and it is exactly wrong here: a baseline is stale because the
+   *world* moved (a scorer bump, a coverage-shape change, months of unrelated
+   drift), so a diff-scoped run leaves almost every stale row untouched and
+   the staleness finding re-fires on the next sweep. `:reanchor` is the same
+   script with `--full-scope`, which re-scores every file in every target
+   dir. Confirm the flag on any kind you are unsure of with that script's
+   `--help`.
+
+   Expect a re-anchor to touch far more rows than a code change would — that
+   breadth is the point, but say so in the finding so a reviewer can tell a
+   re-anchor from a mass regression.
+
+   The acknowledgment is the kind upper-snaked. It demotes that kind's
+   head-vs-base regressions to unchanged **for one run only** — floors stay
+   enforced, so a genuine breach is still caught. The durable equivalent is a
+   commit in the compared range whose subject carries the gate's `refreshTag`
+   (default `baseline-refresh:`) **and** whose diff touches that kind's
+   baseline file. Confirm both against
+   `node .agents/scripts/check-baselines.js --help` before writing the prompt,
+   and never invent an acknowledgment for a kind that ships no regeneration
+   script — there, the remediation is to add one, not to hand-edit rows.
+
+3. **Hotspot Clusters.** `hotspots[]` is already the cross-gate join, one entry
+   per cluster key, ranked highest first. **Emit one finding per cluster —
+   never one per metric row.** A file that is a CRAP outlier and a
+   maintainability outlier is one debt item with two symptoms; splitting it
+   files two Stories that fight over the same refactor. The cluster key is a
+   repository file path for every kind except `lighthouse` (a route) and
+   `bundle-size` (a bundle name) — say which it is when it is not a file.
+
+   Quote `rank` with the four factors behind it — `severityWeight`,
+   `churnWeight`, `centralityWeight`, `frictionWeight` — and the per-gate rows
+   under `gates`. Grade by breadth first: three or more entries in `gateKinds`
+   is **High**, two is **Medium**, one is **Low** unless its `severityWeight`
+   alone is extreme.
+
+4. **Trend Drift.** `trend[]` carries newest-versus-previous rollup deltas per
+   kind, bracketed by the commits in `from` and `to`. A delta moving **away**
+   from the floor is the finding; one moving toward it is headroom the next
+   dimension owns. Read the axis's `direction` in `headroom[]` before assigning
+   a sign — lower is not universally better. An entry needs `sampleCount` of at
+   least 2 to mean anything, and an empty `trend[]` means no readable history:
+   record that as **Info** rather than inferring a flat trend from silence.
+   Each `deltas` key **names its unit** — `symbols`, `bytes`, `filesTracked` —
+   so quote the axis with the number, never a bare delta.
+
+5. **Tightening Headroom.** `headroom[]` is what this lens exists for. Positive
+   headroom is slack the floor could be tightened into; negative headroom means
+   the floor is already breached — grade that **High** and route it as a
+   regression, not an opportunity. File a tightening finding only when the
+   slack is **durable**: the same kind's trend is flat or improving. A one-run
+   dip tightened into a floor turns the next honest change red for no defect.
+   Grade durable multi-point slack **Medium**, marginal slack **Low**.
+
+## Step 2: Hotspot budget and the dropped log
+
+Cap the Detailed Findings at the **top 8 hotspot clusters by `rank`**. The
+engine emits up to `--hotspot-limit` clusters, and the point of the lens is a
+ranked actionable batch, not an exhaustive dump nobody schedules.
+
+A silent truncation reads as full coverage, so the report MUST carry a
+**Dropped Hotspots** section naming every cluster the cap excluded with its
+cluster key, `rank`, and `gateKinds`. Write `_None dropped._` when the cap did
+not bite; the section's absence is itself a defect. This budget log is separate
+from — and additional to — the core's self-cross-check `kept / dropped` line,
+which counts evidence-bar drops rather than budget drops. State the cap in the
+Executive Summary and change it only on an explicit operator instruction.
+
+## Step 3: The floor-tightening contract (mandatory)
+
+A remediation Story that only burns debt down leaves the floor where it was,
+and the reclaimed slack is silently re-spent by the next change — the loop
+runs and the ratchet never moves. So **every Hotspot Cluster and Tightening
+Headroom finding's Agent Prompt MUST** end the remediation with the ratchet
+tightened and gate-enforced:
+
+1. Lower the floor under `delivery.quality.gates` in `.agentrc.json` to the
+   newly measured level, **or** delete the burnt-down rows from that kind's
+   file under `baselines/`.
+2. Carry `node .agents/scripts/check-baselines.js --gate <kind>` in the
+   remediation Story's `verify[]`, so the tightened floor is enforced by the
+   gate that already exists at that Story's delivery time rather than by prose
+   nobody runs.
+
+Use these two Agent Prompt templates verbatim, substituting the envelope's own
+values for the angle-bracketed slots:
+
+- **Hotspot Cluster template:**
+  `Burn down the measured debt in <hotspots.path>, an outlier across <gateKinds>. Refactor and add tests until its rows leave that kind's file under baselines/, then regenerate that baseline with the matching update-*-baseline script in a commit whose subject carries the baseline-refresh: tag. Finish by TIGHTENING the ratchet in the same Story — lower the kind's floor under delivery.quality.gates in .agentrc.json to the new measured level, or delete the burnt-down rows — and carry node .agents/scripts/check-baselines.js --gate <kind> in this Story's verify[] so the tightened floor is enforced at delivery.`
+- **Tightening Headroom template:**
+  `The <kind> gate's <axis> floor sits at <floor> while the measured rollup is <measured> (headroom <headroom>, direction <direction>), and that kind's trend is flat or improving. Tighten it: set that axis under delivery.quality.gates in .agentrc.json to the measured level so no slack remains for the next change to re-spend, and carry node .agents/scripts/check-baselines.js --gate <kind> in this Story's verify[] so the new floor is enforced. Regenerate no baseline in this Story — the floor edit is the whole change.`
+
+Staleness, Dead Instrument, and Trend Drift findings do **not** carry the
+tightening clause: there is no measured slack to claim until the instrument is
+alive and current again.
+
+## Step 4: Cadence (host-owned — documented, never scheduled)
+
+This lens ships **no scheduler**, and building one is out of scope; cadence
+belongs to the host that invokes it. Document the intent and let the operator
+or the host's own timer drive it: **monthly** for a codebase-wide pass (long
+enough for `trend[]` to hold signal, short enough to catch a stale instrument
+before a release leans on it); **after a large refactor lands**, when headroom
+appears and is most likely to be silently re-spent; and **before any floor is
+raised**, so the raise is argued against measured headroom rather than
+convenience. Nothing here self-triggers.
+
+## Step 5: Hand off to `/audit-to-stories`
+
+The report is the deliverable. Hand it to the converter, which parses the
+shared finding skeleton, fingerprints each finding for dedupe, and groups the
+batch:
+
+```bash
+node .agents/scripts/audit-to-stories.js --scan --glob temp/audits/audit-baselines-results.md --out temp/audits/audit-to-stories-plan.json
+```
+
+Report the plan path and the group count; the converter owns everything
+downstream, including whether a finding becomes a Story at all.
+
+## Report additions
+
+Beyond the shared skeleton (Executive Summary + Detailed Findings from the
+core), this report carries its own title, a Gate Surface Health table, a
+Tightening Ledger, and the Dropped Hotspots budget log:
+
+```markdown
+# Baseline & Ratchet Audit Report
+
+## Gate Surface Health
+
+| Kind | Surface | Configured | Rows | Measured | Stale (days) | Stale (commits) | Verdict |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| [kind] | [gate / ratchet] | [yes / no] | [rowCount] | [measured.value measured.unit] | [staleDays or `null`] | [staleCommits or `null`] | [Live / Stub / Unenforced / Unreadable] |
+
+## Tightening Ledger
+
+| Kind | Axis | Floor | Measured | Headroom | Trend | Proposed floor |
+| --- | --- | --- | --- | --- | --- | --- |
+| [kind] | [axis] | [floor] | [measured] | [headroom] | [improving / flat / worsening] | [value] |
+
+## Dropped Hotspots
+
+| Cluster key | Rank | Gates |
+| --- | --- | --- |
+| [key] | [rank] | [gateKinds] |
+```

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

@@ -42,10 +42,11 @@ touched only one route file. Reachability is a global property: adding one
 route can orphan it, but removing or renaming a route elsewhere can also break
 a nav href that the change set never touched.
 
-Because of this, the navigability lens is registered in the **global-lens
-allowlist** (`GLOBAL_LENS_ALLOWLIST` in
-[`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js)) and is
-**exempt from the cross-epic-leak guard** that narrows every other lens's
+Because of this, the navigability lens declares `"scope": "global"` in
+[`audit-rules.json`](../schemas/audit-rules.json) — the single source of truth
+`resolveLensTier` in
+[`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js) reads —
+and is **exempt from the cross-epic-leak guard** that narrows every other lens's
 evidence to the change set's `changedFiles`. The exemption is scoped to this
 lens only — the guard is **not** weakened for any other lens, and it never lets
 a foreign change set leak into a scoped lens.

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.