mandrel 2.25.0 → 2.26.0

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/deliver.md

@@ -35,12 +35,15 @@ you read:
 | `/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, sequence by the discovered graph via `stories-wave-tick.js`, dispatch sub-agents. |
+| `/deliver 4712 - 4716` | ids | A **range** — every id in the inclusive span. |
 | `/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. A ticket
-not `type::story`, or carrying an `Epic: #N` footer, is a hard error too.
+**The discriminator is lexical and total.** An argument matching `^#?\d+$` is an
+id, and `^#?\d+\s*[-–—]\s*#?\d+$` an inclusive **range** — pass one on as a
+single unspaced token, never hand-expanded (reference § Ranges). Either shape
+means ids; anything else means a prompt. A **mixed** invocation (ids *and*
+prose) is a **hard error** — refuse it and ask which was meant. A ticket not
+`type::story`, or carrying an `Epic: #N` footer, is a hard error too.
 
 ## Saying what you want
 
@@ -103,6 +106,12 @@ it to an operator or add it to an attended run.
    `node .agents/scripts/plan-run-epilogue.js --stories 101,102`. N=1 skips it
    ([reference § Per-run epilogue](helpers/deliver-reference.md)).
 
+5. **Correct what the change invalidated.** If a memory you recalled this
+   session is now wrong — a trap this landed, a budget it moved — fix that
+   entry now, while both the old belief and the new fact are in context, and
+   say so when you report. No memory substrate → skip silently. Sweeping the
+   whole pool is [`/memory-consolidate`](memory-consolidate.md), not this step.
+
 ## Closing what the workers hand back {#tail}
 
 **The tail is the orchestrator's, not the worker's.** A dispatched

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -40,8 +40,8 @@ mid-delivery, and evaluates the actual work product.
    `resolveCeremonyForRisk`). **Never run both**, and never run a
    preliminary self-assessment pass before dispatching the fresh critic —
    the redundant pre-pass buys no measurable quality and roughly triples
-   the acceptance-block cost. Step 2's gate is the deterministic **scorer**
-   of the one authored verdict, not a second (or third) pass over the
+   the acceptance-block cost. Step 3's gate is the deterministic **scorer**
+   of the one merged verdict, not a second (or third) pass over the
    criteria.
 
    > **Sub-agent type + derived-level ceremony.** When
@@ -134,20 +134,56 @@ mid-delivery, and evaluates the actual work product.
      fresh — a false-fresh coverage record without `coverage-final.json`
      silently weakens the floor. Limit the evidence-share to `lint` and
      `typecheck`.
-   - Emits a verdict file under `temp/` conforming to
+   - Emits a **cluster** verdict file under `temp/` conforming to
      [`acceptance-eval-verdict.schema.json`](../../schemas/acceptance-eval-verdict.schema.json):
      one `{ index, criterion, verdict: met|partial|unmet, evidence,
-     verifyEvidence[] }` record per acceptance item.
-2. **Decide.** Run the gate against the verdict (the caller's Step 1a names the
-   exact invocation — omit `--epic`). The gate **scores the single verdict
-   the round's owner authored** — schema validation, round cap, decision —
-   and never re-scores the criteria itself:
+     verifyEvidence[] }` record per acceptance item **in that cluster**, each
+     `index` being the item's position in the Story's full `acceptance[]`
+     array. A fresh critic **returns that path to you** rather than calling the
+     gate itself.
+2. **Dispatch the round's clusters in parallel, then merge into one verdict.**
+   The clusters of a round are independent, so dispatch **all** of the round's
+   fresh critics as N `Agent` calls **in a single assistant turn** —
+   [`parallel-tooling.md`](parallel-tooling.md) **Rule 3** — never serially,
+   and never one round per cluster. Clusters routed `inline` are authored in
+   the same round alongside them.
+
+   Then **merge** the cluster verdicts into **one** verdict file under `temp/`:
+   concatenate every cluster's `criteria[]` records and order the merged array
+   by `index`, so it holds exactly one record per `acceptance[]` item in
+   **acceptance-array order**, under a single top-level `storyId`,
+   `schemaVersion`, `round` and `commitSha`. The verdict schema deliberately
+   carries **no `clusterId`** — the round's artifact is the merged verdict, and
+   which critic scored which record is not part of the contract.
+
+   > **Why one gate call and not N.** The round counter is **Story-scoped** —
+   > derived by counting `acceptance-eval` signals in the Story's
+   > `signals.ndjson` — and each cluster verdict has a distinct fingerprint, so
+   > the replay guard never collapses them. A gate call per cluster would spend
+   > one of the (default 2) rounds *per cluster*, so a Story with more than 8
+   > acceptance criteria would exhaust its redraft budget on cluster arithmetic
+   > alone; N concurrent calls would also race that same ledger. Cluster-scoped
+   > round counting exists in
+   > [`acceptance-eval-decision.js`](../../scripts/lib/orchestration/acceptance-eval-decision.js)
+   > but requires an integer `epicId`, which v2 pins `null` — it is not a way
+   > around the merge.
+3. **Decide — exactly one gate call per round.** Run the gate against the
+   **merged** verdict (the caller's Step 1a names the exact invocation — omit
+   `--epic`). The gate **scores the single verdict the round produced** —
+   schema validation, round cap, decision — and never re-scores the criteria
+   itself:
 
    ```bash
    node <main-repo>/.agents/scripts/acceptance-eval.js \
-     --story <storyId> --verdict <verdict-path>
+     --story <storyId> --verdict <merged-verdict-path> \
+     --expected-criteria <number of acceptance[] items>
    ```
 
+   Pass `--expected-criteria` from the `acceptance[]` count you already read
+   off the Story body: a verdict whose `criteria[]` length differs — a single
+   cluster's verdict handed over unmerged — is rejected **before scoring**,
+   with an error naming the merge contract and consuming **no round**.
+
    The gate validates the verdict against the schema, applies the round cap,
    emits the per-criterion `acceptance-eval` signal into the retro / feedback
    substrate, prints a JSON envelope, and exits with one of three decisions:
@@ -161,4 +197,5 @@ mid-delivery, and evaluates the actual work product.
      (transition to `agent::blocked`) and post a `friction` comment naming the
      unmet criteria and their evidence. Never silently proceed to close.
 
-Write the verdict files under `temp/` only — they are scratch artifacts.
+Write both the per-cluster verdicts and the merged verdict under `temp/` only —
+they are scratch artifacts.

package/.agents/workflows/helpers/code-quality-guardrails.md

@@ -35,8 +35,15 @@ thresholds, sourced from
 | CC range | Action |
 | --- | --- |
 | ≤ 8 | Pass — no annotation required. |
-| > 8 (default `cyclomaticFlag`) | **Flag** in review: explain why, or split. The function is allowed to land but the audit report names it. |
-| > 12 (default `cyclomaticMustFix`) | **Must-fix**: refactor before the Story commits. `quality:preview` reports it as a violation; the close-validation chain refuses the merge. |
+| > 8 (default `cyclomaticFlag`) | **Flag** — `quality:preview` counts the function in its `new-method count over c=<flag>` column. The function is allowed to land but the report names it. |
+| > 12 (default `cyclomaticMustFix`) | **Must-fix**: `check-cyclomatic.js` fails when a file gains a function above the ceiling, or when its worst function gets worse than the recorded baseline. |
+
+`check-cyclomatic.js` is a **ratchet**, not a cliff: `baselines/cyclomatic.json`
+records the over-ceiling functions a repository already carries, so adopting
+the gate never demands a mass refactor. Burning a recorded breach down is
+always allowed and re-records itself on the next `--update`; adding one is
+what fails. It runs in the same required-check slot as `check-arch-cycles.js`
+and `check-dead-exports.js`.
 
 A common refactor that pulls a 13-CC function under 8 is extracting the early-
 return guard chain into a named predicate, then collapsing the remaining

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

@@ -10,10 +10,9 @@ description: >-
 # Deliver digest (read once per session)
 
 > **Bundle, not a procedure.** [`deliver-story.md`](deliver-story.md) is still
-> the steps. This file is the material those steps referenced across five
-> separate files and a JSON schema — bundled so one read covers the whole happy
-> path. Situational material (lease preflight, recovery routers, merge-wait
-> budgets, CI remediation) stays on demand in
+> the steps; this file is the material they reference, bundled so one read
+> covers the happy path. Situational material (lease preflight, recovery
+> routers, merge-wait budgets, CI remediation) stays on demand in
 > [`deliver-story-reference.md`](deliver-story-reference.md) and
 > [`deliver-reference.md`](deliver-reference.md); read those **only** when an
 > envelope or a failure routes you there.
@@ -28,10 +27,10 @@ rule produces it:
    whatever its shape — sub-agent isolation is load-bearing only against a
    *concurrent* sibling racing the same checkout, and a one-Story run has none.
 2. **Every other run is `subagent`.** A multi-Story run dispatches every Story
-   as a sub-agent however trivial its shape: a lite body does not conjure a
-   second session for a sibling to run in, and the wave tick may hand you the
-   whole set on one beat. Shape still sets ceremony and is reported alongside;
-   the `route::lite` label is a human-visible hint, never the control signal.
+   as a sub-agent however trivial its shape — a lite body does not conjure a
+   second session for a sibling, and the wave tick may hand you the whole set
+   on one beat. Shape still sets ceremony; the `route::lite` label is a
+   human-visible hint, never the control signal.
 
 `inline` removes model-side fan-out only — no `story-worker` boot, no fresh
 acceptance-critic spawn. **`subagent` and `inline` run the same engine**: same
@@ -54,21 +53,32 @@ the only sanctioned landing. A silent local build is not a delivery.
 ## 3. Change set — computed once, handed to everyone
 
 One enumeration per Story. A critic that re-runs its own `git diff`
-can score a different set than the one that routed it:
+can score a different set than the one that routed it. Both routing calls take
+a single options object and are **total — they never throw**, so a wrong-shaped
+argument is silently absorbed into the `null` fail-safe:
 
 ```bash
 node --input-type=module -e '
-  import { computeChangeSet } from "<main-repo>/.agents/scripts/lib/orchestration/change-set.js";
+  const lib = "<main-repo>/.agents/scripts/lib/orchestration";
+  const { computeChangeSet } = await import(`${lib}/change-set.js`);
+  const { deriveChangeLevel } = await import(`${lib}/review-depth.js`);
+  const { resolveCeremonyForRisk } = await import(`${lib}/ceremony-routing.js`);
   const { files } = computeChangeSet({ baseRef: "main", headRef: "story-<storyId>" });
-  console.log(JSON.stringify(files));
+  // deriveChangeLevel({ changedFiles, injectedRules?, selectSensitivePathClassesFn? })
+  //   -> { level, classes } — an OBJECT, never a bare level.
+  const { level, classes } = deriveChangeLevel({ changedFiles: files });
+  // resolveCeremonyForRisk({ derivedLevel, clusterIndex?, freshCriticSampleRate?,
+  //   ceremonyProfile? }) -> { mode, reason, sampled, profile, verdictOwner }.
+  // derivedLevel is that level STRING. Handing it the object above matches no
+  // tier, so it routes to the null fail-safe: a fresh critic, silently.
+  const ceremony = resolveCeremonyForRisk({ derivedLevel: level, clusterIndex: 0 });
+  console.log(JSON.stringify({ files, level, classes, ...ceremony }));
 '
 ```
 
-Derive the level with `deriveChangeLevel`
-([`review-depth.js`](../../scripts/lib/orchestration/review-depth.js)) over
-that one list: a sensitive path registered in `audit-rules.json` → `high`, none
-→ `low`, an unenumerable diff (`files === null`) → `null`. Resolve
-fresh-vs-inline critics with `resolveCeremonyForRisk`
+Level rules ([`review-depth.js`](../../scripts/lib/orchestration/review-depth.js)):
+a sensitive path registered in `audit-rules.json` → `high`, none → `low`, an
+unenumerable diff (`files === null`) → `null`. Ceremony rules
 ([`ceremony-routing.js`](../../scripts/lib/orchestration/ceremony-routing.js)):
 `minimal` → always inline, `strict` → always fresh, `standard` → `high`/`null`
 → fresh and `low` → inline unless the `freshCriticSampleRate` floor forces
@@ -78,16 +88,26 @@ fresh. An `inline` dispatch mode overrides all of it to inline critics. Close's
 ## 4. Acceptance self-eval (Step 1a, required)
 
 **One verdict-owner per cluster** — the fresh critic *or* the inline
-self-eval, named by `verdictOwner`, never both and never a warm-up pass. It
-scores each `acceptance[]` item against the change set above, with `verify[]`
-output as evidence. Bounded by `delivery.acceptanceEval.maxRounds` (default 2).
-Then score the authored verdict:
+self-eval, named by `verdictOwner`, never both and never a warm-up pass. Each
+scores its cluster's `acceptance[]` items against the change set above, with
+`verify[]` output as evidence. Bounded by `delivery.acceptanceEval.maxRounds`
+(default 2).
+
+**One round = N cluster critics → ONE merged verdict → ONE gate call.** Merge
+every cluster's records into a single `criteria[]` in `acceptance[]` order, one
+per acceptance item, and score that once. A gate call per cluster spends a
+round *per cluster* and races the round ledger:
 
 ```bash
 node <main-repo>/.agents/scripts/acceptance-eval.js \
-  --story <storyId> --verdict <verdict-path>
+  --story <storyId> --verdict <merged-verdict-path> \
+  --expected-criteria <acceptance[] count>
 ```
 
+Pass `--expected-criteria` — **without it the coverage assertion is inert**, so
+an unmerged cluster verdict scores a fraction of the criteria and still reports
+`proceed`. A mismatch is rejected before scoring and costs no round.
+
 `proceed` → close. `redraft` → one more round inside the cap. `block` → **do
 not close**: post a `friction` comment and flip `agent::blocked`.
 Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).