mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/audit-baselines/weights.js

@@ -1,17 +1,7 @@
 /**
- * weights.js — the three ranking multipliers, and their degradations
- * (Story #4902).
- *
- * A hotspot's severity says how bad the code measures. These three say how
- * much that badness costs: how often the file changes (churn), how much of
- * the repository depends on it (import in-degree), and how often agents have
- * actually tripped over it (friction signals).
- *
- * All three are **optional inputs**. A shallow clone has no git history, a
- * fresh checkout has no friction ledger, and a consumer whose sources live
- * outside the scanned roots has no resolvable import graph. Each degrades to
- * a neutral multiplier of exactly 1.0 — never 0 (which would erase the
- * hotspot) and never a guess. The engine exits 0 in every degraded case.
+ * Hotspot ranking multipliers — churn, import in-degree, friction signals.
+ * Each input is optional and degrades to exactly 1.0: never 0 (which would
+ * erase the hotspot), never a guess.
  *
  * @module lib/audit-baselines/weights
  */
@@ -21,14 +11,11 @@ import path from 'node:path';
 import { execFileCapture } from '../child-exec.js';
 import { computeInDegree, resolveRepoGraph } from '../import-graph.js';
 
-/** Neutral multiplier every degraded weight collapses to. */
 const NEUTRAL_WEIGHT = 1.0;
 
 /**
- * Saturating count → multiplier in `[1, 2)`. Zero observations gives exactly
- * `NEUTRAL_WEIGHT`, so "no signal" and "signal says nothing notable" are the
- * same number — the degradation is indistinguishable from an honest zero,
- * which is the point: neither should move the ranking.
+ * Saturating count → `[1, 2)`; zero equals the degraded weight, so neither
+ * moves the ranking.
  *
  * @param {number} count
  * @param {number} half count at which the multiplier reaches 1.5
@@ -40,12 +27,10 @@ function saturate(count, half) {
 }
 
 /**
- * Count commits touching each file in the recent history window.
+ * Commits per file in the window; `degraded` when git cannot answer at all.
  *
  * @param {{ cwd: string, windowDays?: number, run?: Function }} args
  * @returns {{ counts: Map<string, number>, degraded: boolean }}
- *   `degraded` is true when git could not answer at all — not a git work
- *   tree, no commits yet, or the binary is unavailable.
  */
 export function readChurn({ cwd, windowDays = 180, run }) {
   let stdout;
@@ -62,8 +47,7 @@ export function readChurn({ cwd, windowDays = 180, run }) {
       {
         run,
         cwd,
-        // git narrates "not a git repository" on stderr; the degradation is
-        // reported in the envelope, not shouted at the operator.
+        // Degradation is reported in the envelope, not on stderr.
         stdio: ['ignore', 'pipe', 'ignore'],
       },
     );
@@ -80,8 +64,6 @@ export function readChurn({ cwd, windowDays = 180, run }) {
 }
 
 /**
- * Import in-degree per module, keyed by repo-relative posix path.
- *
  * @param {{ cwd: string, graph?: Map<string, string[]> | null }} args
  * @returns {{ degrees: Map<string, number>, degraded: boolean }}
  */
@@ -91,12 +73,9 @@ export function readCentrality({ cwd, graph }) {
   return { degrees: computeInDegree(resolved), degraded: false };
 }
 
-/** Path tokens that look like repository files, harvested from signal text. */
 const PATH_TOKEN_RE = /[\w@][\w./@-]*\.(?:js|mjs|cjs|ts|tsx|json|md)\b/g;
 
 /**
- * Collect every `signals.ndjson` under `tempRoot`. Absent tree → empty list.
- *
  * @param {string} tempRootAbs
  * @returns {string[]} absolute paths
  */
@@ -121,12 +100,8 @@ function findSignalStreams(tempRootAbs) {
 }
 
 /**
- * Count friction signals blaming each file.
- *
- * Signal records carry no dedicated path field — the blamed file surfaces
- * inside free-form `details` / `emitter.command` text — so paths are
- * harvested by token scan over each record's serialized form. A malformed
- * line is skipped, never fatal.
+ * Friction signals per blamed file. Records have no path field, so paths are
+ * token-scanned from `details` / `emitter.command`; bad lines are skipped.
  *
  * @param {{ tempRootAbs: string, kinds?: Set<string> }} args
  * @returns {{ counts: Map<string, number>, degraded: boolean, streams: number }}
@@ -167,9 +142,6 @@ export function readFriction({
 }
 
 /**
- * Bundle the three weight lookups into one resolver the hotspot builder can
- * call per cluster id, plus the degradation flags the envelope reports.
- *
  * @param {{
  *   churn: { counts: Map<string, number>, degraded: boolean },
  *   centrality: { degrees: Map<string, number>, degraded: boolean },

package/.agents/scripts/lib/audit-suite/audit-rules-reader.js

@@ -1,31 +1,16 @@
 /**
- * lib/audit-suite/audit-rules-reader.js — the one synchronous reader of the
- * `audit-rules.json` manifest, memoized for the process lifetime.
- *
- * The manifest is shipped framework configuration resolved from one fixed
- * path per process, and the shape-derivation path reads it once per Story at
- * resolve AND persist — an un-memoized read is pure repeated I/O (measured
- * 221 µs/op raw vs 5.5 µs seamed on the run adhoc-4722-4723 audit). Only a
- * successful parse is cached: a read failure stays a per-call throw so a
- * caller can observe a manifest that becomes readable later. Tests never
- * reach this read — they inject fixture rules through the callers'
- * `injectedRules` seam.
+ * The one synchronous `audit-rules.json` reader, memoized per process. Only a
+ * successful parse is cached, so a failure stays a per-call throw and a
+ * manifest that later becomes readable is seen.
  */
 
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
 
-/** Process-lifetime memo of the parsed manifest (successful parses only). */
 let auditRulesCache = null;
 
 /**
- * Read and parse the `audit-rules.json` manifest synchronously from the
- * project's configured `schemasRoot`. Shared by the synchronous, ticket-free
- * readers (`resolveLensTier`, `selectLocalLenses`,
- * `selectSensitivePathClasses`) so the path resolution and read-failure
- * handling live in one place rather than being duplicated per reader.
- *
  * @returns {{ audits?: Record<string, object> }} Parsed manifest.
  * @throws {Error} When the manifest cannot be read or parsed.
  */

package/.agents/scripts/lib/audit-suite/checklist-threading.js

@@ -1,39 +1,7 @@
 /**
- * lib/audit-suite/checklist-threading.js — write-time local-lens checklist
- * threading (Epic #4405, Story #4410).
- *
- * Given a Story's predicted footprint (its `changes[]` / `references[]` path
- * list), select the distilled authoring checklists for the **footprint-matched
- * LOCAL lenses only** and assemble them into one payload the dispatch/hydrator
- * seam threads into the Story maker prompt. This moves each local-lens concern
- * to the innermost, write-time tier so makers author against it on fresh
- * context instead of paying an Epic-close remediation loop on stale context.
- *
- * Matching is the **light** path, deliberately NOT `selectAudits`:
- *   - tier gate  — a lens is in scope only when `resolveLensTier(lens) ===
- *                  'local'` (the pure `scope`-field read; cumulative/global
- *                  lenses are owned by the Epic-close tier, never threaded
- *                  here).
- *   - file gate  — the pure `matchesAnyFilePattern` matcher runs the lens's
- *                  own `triggers.filePatterns` (from `audit-rules.json`)
- *                  against the predicted footprint.
- *
- * `selectAudits` is the wrong tool here: it is gate-aware and provider-backed
- * (it reads the ticket through an `ITicketingProvider` and diffs the working
- * tree via `git`). The write-time path has a *predicted* footprint, not a git
- * diff, and no ticket to fetch — so this module reaches for the two pure
- * primitives directly and never touches a provider or `git`. That purity is
- * load-bearing (asserted by the test): the threading path must be a pure
- * function of the footprint and the on-disk manifest/checklists.
- *
- * A hard token budget caps the assembled payload. When the matched lenses'
- * checklists together exceed the budget, the payload is truncated
- * deterministically (a stable prefix in {@link AUDIT_LENSES} order is kept;
- * the overflowing tail is dropped) and every dropped lens is logged so the
- * elision is never silent.
- *
- * Pure (modulo the default disk reads for `audit-rules.json` and the checklist
- * artifacts, both injectable seams). No git, no provider, no network.
+ * Write-time checklists for LOCAL lenses matching a predicted footprint,
+ * under a token budget. Not `selectAudits`: this must stay a pure function of
+ * footprint + on-disk files — no git, provider, or network (tested).
  */
 
 import fs from 'node:fs';
@@ -48,11 +16,7 @@ import {
 } from './selector.js';
 
 /**
- * Rough token estimate: ~4 characters per token. Deliberately cheap and
- * deterministic — this budget is the one surviving ceiling that speaks in
- * tokens (Story #5312 deleted the plan-time sizing ceilings that shared the
- * estimator), so the approximation matters far less than the payload and
- * the cap agreeing on one number.
+ * ~4 chars per token; what matters is that payload and cap agree on one number.
  *
  * @param {string} text
  * @returns {number}
@@ -62,24 +26,14 @@ function estimateTokens(text) {
 }
 
 /**
- * Hard cap on the assembled checklist payload, in the ≈4-char/token estimate
- * above ({@link estimateTokens}). Generous
- * relative to the real checklist sizes (each distilled lens checklist is
- * ~130–190 tokens, and at most the seven local lenses can match), so a normal
- * Story is never truncated — the cap is a safety ceiling against a pathological
- * footprint that matches every local lens, not a routine squeeze. Callers may
- * override per-invocation via `tokenBudget`.
+ * Safety ceiling, not a routine squeeze: all seven local lenses together fit.
  */
 export const DEFAULT_CHECKLIST_TOKEN_BUDGET = 4000;
 
-/** Separator between concatenated per-lens checklist sections. */
 const SECTION_SEPARATOR = '\n\n';
 
 /**
- * The `audit-rules.json` / `resolveLensTier` lens key for a canonical lens
- * name. The taxonomy in {@link AUDIT_LENSES} carries bare names (`clean-code`);
- * the manifest and the tier resolver key off the `audit-`-prefixed form
- * (`audit-clean-code`).
+ * Manifest key for a bare taxonomy lens name (`clean-code` → `audit-clean-code`).
  *
  * @param {string} lens
  * @returns {string}
@@ -89,13 +43,9 @@ function lensKeyFor(lens) {
 }
 
 /**
- * Absolute path to the committed distilled-checklist directory. Mirrors the
- * SSOT the generator writes to (`generate-lens-checklists.js` →
- * `<agentRoot>/audit-checklists/<lens>.md`), resolved through the same
- * `agentRoot` the rest of the config surface uses so a consumer that relocates
- * `.agents` reads its checklists from the relocated tree.
+ * `<agentRoot>/audit-checklists`, honouring a relocated agent root.
  *
- * @param {object} [config] resolved config wrapper (defaults to a fresh read).
+ * @param {object} [config]
  * @returns {string}
  */
 function checklistsDir(config = resolveConfig()) {
@@ -107,12 +57,9 @@ function checklistsDir(config = resolveConfig()) {
 }
 
 /**
- * Read and parse `audit-rules.json` (the same manifest {@link selectAudits}
- * and {@link resolveLensTier} consume), resolved through the configured
- * `schemasRoot`. Synchronous — this is a pure-ish read with no git and no
- * provider.
+ * Parse `audit-rules.json` from the configured `schemasRoot`.
  *
- * @param {object} [config] resolved config wrapper (defaults to a fresh read).
+ * @param {object} [config]
  * @returns {{ audits?: Record<string, { triggers?: { filePatterns?: string[] } }> }}
  */
 export function readAuditRules(config = resolveConfig()) {
@@ -125,12 +72,6 @@ export function readAuditRules(config = resolveConfig()) {
 }
 
 /**
- * The `triggers.filePatterns` a lens declares in the manifest, or `[]` when
- * the lens declares none. (`audit-clean-code` carries the universal
- * match-everything glob, so it footprint-matches every non-empty change
- * set — the selector.js twin comment documents the same post-#4405
- * follow-up fix.)
- *
  * @param {object} rules parsed `audit-rules.json`.
  * @param {string} lens canonical lens name.
  * @returns {string[]}
@@ -140,9 +81,6 @@ function filePatternsFor(rules, lens) {
 }
 
 /**
- * The full `triggers` block a lens declares in the manifest (or `undefined`).
- * Used to read non-glob trigger fields (e.g. `sourceWithoutSiblingTest`).
- *
  * @param {object} rules parsed `audit-rules.json`.
  * @param {string} lens canonical lens name.
  * @returns {object|undefined}
@@ -152,10 +90,6 @@ function triggerFor(rules, lens) {
 }
 
 /**
- * Normalize a predicted footprint into a clean path list. Accepts a plain
- * `string[]` (the shape the caller derives from a Story's `changes[]` /
- * `references[]` entries); drops empty and non-string entries.
- *
  * @param {unknown} footprint
  * @returns {string[]}
  */
@@ -168,21 +102,13 @@ function normalizeFootprint(footprint) {
 }
 
 /**
- * Select, in stable {@link AUDIT_LENSES} order, the LOCAL lenses whose
- * `filePatterns` match the predicted footprint. This is the whole matching
- * contract — `resolveLensTier(lens) === 'local'` for the tier gate plus the
- * pure `matchesAnyFilePattern` matcher for the file gate — with no provider and
- * no git diff.
- *
- * A lens whose tier cannot be resolved (not registered / malformed scope) is
- * skipped rather than allowed to throw the whole selection; the generator and
- * schema keep the manifest well-formed, so this only guards against drift.
+ * LOCAL lenses matching the footprint, in {@link AUDIT_LENSES} order. A lens
+ * whose tier cannot be resolved is skipped rather than failing the selection.
  *
  * @param {object} params
  * @param {string[]} params.footprint predicted footprint path list.
- * @param {object} [params.rules] parsed `audit-rules.json` (injectable seam).
- * @param {(lens: string) => string} [params.resolveTier] tier resolver
- *   (injectable seam; defaults to {@link resolveLensTier}).
+ * @param {object} [params.rules] parsed `audit-rules.json`.
+ * @param {(lens: string) => string} [params.resolveTier]
  * @returns {string[]} matched local lens names, in taxonomy order.
  */
 export function matchLocalLenses({
@@ -206,9 +132,8 @@ export function matchLocalLenses({
     const patterns = filePatternsFor(rules, lens);
     const fileMatch =
       patterns.length > 0 && matchesAnyFilePattern(patterns, paths);
-    // Coverage-gap routing (#4628): thread the quality checklist at write-time
-    // on the same sibling-test predicate the selector uses, so a source change
-    // that ships without a test is reminded of the quality lens up front.
+    // Same sibling-test predicate as the selector: a source change without a
+    // test gets the quality checklist up front.
     const siblingMatch =
       triggerFor(rules, lens)?.sourceWithoutSiblingTest === true &&
       changeSetLacksSiblingTest(paths);
@@ -218,13 +143,9 @@ export function matchLocalLenses({
 }
 
 /**
- * Default checklist reader: read `<agentRoot>/audit-checklists/<lens>.md`.
- * Returns `null` when the artifact is absent (a matched lens with no committed
- * checklist), so the caller skips it rather than crashing.
- *
  * @param {string} lens
  * @param {object} [config]
- * @returns {string|null}
+ * @returns {string|null} `null` when the checklist artifact is absent
  */
 function readChecklistFile(lens, config = resolveConfig()) {
   const file = path.join(checklistsDir(config), `${lens}.md`);
@@ -236,31 +157,16 @@ function readChecklistFile(lens, config = resolveConfig()) {
 }
 
 /**
- * Build the write-time checklist payload for a Story's predicted footprint.
- *
- * Returns the assembled payload string plus the accounting the caller (and the
- * test) asserts against: which lenses were included, which were dropped by the
- * budget, the full matched set, and the payload's estimated token count.
- *
- * Truncation is deterministic prefix truncation: lenses are considered in
- * stable {@link AUDIT_LENSES} order and appended while the running payload
- * estimate stays within `tokenBudget`; the first lens that would overflow — and
- * every remaining matched lens — is dropped, and the drop is logged. The
- * returned `payload` therefore always satisfies
- * `estimateTokens(payload) <= tokenBudget`.
+ * Prefix truncation: the first overflowing lens and all later ones are
+ * dropped and logged.
  *
  * @param {object} params
- * @param {string[]} params.footprint predicted footprint (`changes[]` /
- *   `references[]` path list).
- * @param {number} [params.tokenBudget] hard cap (defaults to
- *   {@link DEFAULT_CHECKLIST_TOKEN_BUDGET}).
- * @param {object} [params.rules] parsed `audit-rules.json` (injectable seam).
- * @param {(lens: string) => string} [params.resolveTier] tier resolver
- *   (injectable seam).
- * @param {(lens: string) => (string|null)} [params.readChecklist] checklist
- *   reader (injectable seam; defaults to the on-disk reader).
- * @param {{ warn?: (msg: string) => void }} [params.logger] logger for the drop
- *   record (defaults to {@link Logger}).
+ * @param {string[]} params.footprint predicted footprint path list.
+ * @param {number} [params.tokenBudget]
+ * @param {object} [params.rules] parsed `audit-rules.json`.
+ * @param {(lens: string) => string} [params.resolveTier]
+ * @param {(lens: string) => (string|null)} [params.readChecklist]
+ * @param {{ warn?: (msg: string) => void }} [params.logger]
  * @returns {{
  *   payload: string,
  *   includedLenses: string[],
@@ -294,9 +200,7 @@ export function buildChecklistPayload({
     const lens = matchedLenses[i];
     const content = readChecklist(lens);
     if (content == null) {
-      // Matched a lens with no committed checklist artifact — skip it (never a
-      // budget drop). The generator keeps every lens's checklist in tree, so
-      // this only trips on drift, which we surface rather than swallow.
+      // Missing artifact is drift, not a budget drop: surface and skip.
       logger?.warn?.(
         `[checklist-threading] no checklist artifact for matched local lens '${lens}' — skipping`,
       );
@@ -306,8 +210,6 @@ export function buildChecklistPayload({
     const trimmed = content.trim();
     const candidate = [...sections, trimmed].join(SECTION_SEPARATOR);
     if (estimateTokens(candidate) > tokenBudget) {
-      // Deterministic prefix truncation: this lens and every remaining matched
-      // lens are dropped, keeping the payload within budget.
       droppedLenses.push(...matchedLenses.slice(i));
       break;
     }

package/.agents/scripts/lib/audit-suite/dispatch-checklist.js

@@ -1,21 +1,8 @@
 /**
- * lib/audit-suite/dispatch-checklist.js — the deliver-dispatch call site for
- * write-time checklist threading (Story #4627, activating Epic #4405's
- * Story #4410 machinery).
- *
- * `checklist-threading.js#buildChecklistPayload` was built and unit-tested but
- * had **zero production call sites**: nothing derived a footprint, assembled
- * the payload, or handed a `checklistPath` to the spawned Story worker. This
- * module is that call site. Given a Story's predicted footprint (its
- * `changes[]` / `references[]` path entries), it assembles the footprint-matched
- * local-lens checklist payload, writes it to the run's temp dir, and returns
- * the `checklistPath` the deliver-story spawn threads into the maker's prompt
- * (the same way the docs digest reaches the worker as `docsDigestPath`).
- *
- * Pure modulo the single file write, which is an injectable seam
- * (`writeFileFn`) so the builder is unit-testable without touching disk. No
- * git, no provider, no network — the footprint is the planner's *prediction*,
- * not a diff, so no repository read is involved.
+ * Deliver-dispatch call site for checklist threading: builds the payload from
+ * a Story's predicted `changes[]` + `references[]` footprint, writes it to
+ * the run temp dir, and returns the `checklistPath` the worker spawn threads.
+ * The footprint is a prediction, not a diff: no git, provider, or network.
  */
 
 import fs from 'node:fs';
@@ -23,9 +10,7 @@ import path from 'node:path';
 import { buildChecklistPayload } from './checklist-threading.js';
 
 /**
- * Extract clean path strings from a Story's `changes[]` / `references[]`
- * entries. Accepts both the parsed `{ path, assumption }` PathEntry shape and a
- * bare `string`, dropping empty / non-string entries.
+ * Accepts `{ path }` entries or bare strings.
  *
  * @param {unknown} entries
  * @returns {string[]}
@@ -39,13 +24,7 @@ function footprintFromEntries(entries) {
 }
 
 /**
- * Derive the predicted footprint the checklist matcher reads: the union of a
- * Story's `changes[]` and `references[]` path entries, in that order.
- *
- * Module-local: a detail of {@link buildDispatchChecklist}, exercised through
- * that public entry point (assert the footprint the injected payload builder
- * received) rather than imported directly, so it adds no test-only public
- * export the dead-export ratchet would flag.
+ * Module-local so it adds no test-only export for the dead-export ratchet.
  *
  * @param {{ changes?: unknown, references?: unknown }} [args]
  * @returns {string[]}
@@ -58,8 +37,6 @@ function deriveDispatchFootprint({ changes, references } = {}) {
 }
 
 /**
- * Default file writer: ensure the parent dir exists, then write the payload.
- *
  * @param {string} filePath
  * @param {string} content
  * @returns {void}
@@ -70,24 +47,16 @@ function defaultWriteFile(filePath, content) {
 }
 
 /**
- * Build the write-time checklist payload for a Story and write it to the run's
- * temp dir, returning the `checklistPath` the deliver-story spawn threads.
- *
- * When the footprint matches no local lens (the common case for a
- * docs-only or infra-only Story), nothing is written and `checklistPath` is
- * `null` — the worker then runs with no write-time checklist, exactly as it
- * does today, and lens-aware coverage still runs maker-blind at Story-scope
- * close.
+ * No matched lens → nothing written, `checklistPath: null`.
  *
  * @param {object} args
- * @param {number|string} args.storyId — names the payload file.
- * @param {unknown} [args.changes] — the Story's `changes[]` path entries.
- * @param {unknown} [args.references] — the Story's `references[]` path entries.
- * @param {string} args.runTempDir — the run temp dir the payload is written to.
- * @param {number} [args.tokenBudget] — override the payload cap.
- * @param {typeof buildChecklistPayload} [args.buildPayloadFn] — injectable seam.
- * @param {(filePath: string, content: string) => void} [args.writeFileFn] —
- *   injectable write seam (defaults to the on-disk writer).
+ * @param {number|string} args.storyId
+ * @param {unknown} [args.changes]
+ * @param {unknown} [args.references]
+ * @param {string} args.runTempDir
+ * @param {number} [args.tokenBudget]
+ * @param {typeof buildChecklistPayload} [args.buildPayloadFn]
+ * @param {(filePath: string, content: string) => void} [args.writeFileFn]
  * @returns {{
  *   checklistPath: string|null,
  *   skipped: boolean,

package/.agents/scripts/lib/audit-suite/findings.js

@@ -1,26 +1,13 @@
 /**
- * lib/audit-suite/findings.js — Findings histogram + baseline delta emitters.
- *
- * `aggregateSummary` (Story #963, Epic #946) populates the `metadata.summary`
- * block of the audit-suite envelope with a severity histogram.
- *
- * `aggregateBaselineDelta` (Task #1920, Epic #1786) reports per-component
- * rollup deltas between two committed baseline envelopes loaded via
- * `lib/baselines/reader.js`. It supersedes the prior row-by-row diff —
- * row-level deltas surfaced noise from churn that did not move any
- * component's rollup, drowning out the regressions that actually mattered.
- *
- * The delta function is **pure**: it takes the two `{ rollup, rows }`
- * envelopes returned by the reader plus the resolved components map and
- * returns a deterministic per-component delta. No filesystem I/O.
+ * Findings severity histogram and per-component baseline rollup deltas.
+ * Deltas are per rollup, not per row: row churn that moves no rollup is noise.
+ * Pure, no I/O.
  */
 
 import { groupRows, resolveComponents } from '../baselines/components.js';
 
 /**
- * Pure: count findings into a {critical,high,medium,low} histogram. Findings
- * with severities outside that set are ignored, keeping the rendered summary
- * truthful even if upstream callers append non-standard severities.
+ * Non-standard severities are ignored.
  *
  * @param {Array<{ severity?: string }>|null|undefined} findings
  * @returns {{ critical: number, high: number, medium: number, low: number }}
@@ -36,20 +23,10 @@ export function aggregateSummary(findings) {
 }
 
 /**
- * The single halting rule for the unified `verification-results` findings
- * contract (Story #4411, Epic #4405): a **surviving** (unfixed) Critical
- * finding halts the delivery gate. Every code consumer of the contract —
- * the in-process code-review producer (`runCodeReview`) and the auto-merge
- * integration gate (`evaluateAutoMergePredicate`) — routes its
- * halt-on-critical decision through this one predicate so the rule has a
- * single definition rather than a re-derived `critical > 0` expression at
- * each site.
- *
- * Accepts either the severity **count object** produced by
- * `countBySeverity` / {@link aggregateSummary} (`{ critical: n, ... }`) or a
- * raw `Finding[]`. A non-numeric / absent `critical` count (e.g. the
- * auto-merge gate's "unparseable body" sentinel `null`) is **not** a halt —
- * the caller owns that fail-open path separately. Pure; never throws.
+ * The single halting rule: a surviving Critical finding halts delivery. Every
+ * consumer routes through this rather than re-deriving `critical > 0`.
+ * Accepts a severity count object or a `Finding[]`; a non-numeric `critical`
+ * (e.g. an unparseable-body `null`) is not a halt — the caller owns that path.
  *
  * @param {{ critical?: unknown }|Array<{ severity?: string }>|null|undefined} input
  * @returns {boolean} `true` when at least one surviving Critical is present.
@@ -63,11 +40,7 @@ export function hasSurvivingCritical(input) {
 }
 
 /**
- * Resolve the per-component rollup map for an envelope. When the envelope
- * already carries a `rollup` block (every writer-produced baseline does), we
- * trust it as the source of truth. When `rollup` is absent (raw test
- * fixtures, hand-written cases) we recompute from rows via the supplied
- * `recompute` callback so the function stays useful in both shapes.
+ * The envelope's own `rollup` when present, else recomputed from rows.
  *
  * @param {{ rollup?: object, rows?: Array<object> }} envelope
  * @param {Record<string, string[]>} components
@@ -89,13 +62,8 @@ function resolveRollup(envelope, components, keyField, recompute) {
 }
 
 /**
- * Compare two component rollup objects (`{ axis: value }`) and emit one
- * delta entry per axis that differs. Pure.
- *
- * The direction is informational only — the audit emitter does not enforce
- * pass/fail policy; floor enforcement happens in `check-baselines.js`. We
- * report `before`, `after`, and the signed delta so a reviewer can read the
- * sign in context (lint count up = bad; coverage % down = bad).
+ * One entry per differing axis. Informational only — floors are enforced by
+ * `check-baselines.js`.
  *
  * @param {Record<string, number>|null|undefined} before
  * @param {Record<string, number>|null|undefined} after
@@ -120,12 +88,6 @@ function diffAxes(before, after) {
 }
 
 /**
- * Compute per-component rollup deltas between two baseline envelopes.
- *
- * Inputs are the shapes returned by `lib/baselines/reader.js#load(kind)`.
- * The function is pure — disk reads happen in the caller so the audit
- * emitter (and its tests) can drive synthetic before/after pairs.
- *
  * @param {{
  *   before: { rollup?: object, rows?: Array<object> },
  *   after:  { rollup?: object, rows?: Array<object> },
@@ -137,9 +99,7 @@ function diffAxes(before, after) {
  *   component: string,
  *   axes: Array<{ axis: string, before: number|null, after: number|null, delta: number|null }>
  * }>}
- *   One entry per component whose rollup changed. `*` always sorts first;
- *   the remainder is alpha. Components with no axis changes are omitted so
- *   an unchanged baseline yields `[]`.
+ *   Changed components only, `*` first then alpha.
  */
 export function aggregateBaselineDelta(params = {}) {
   const before = params.before ?? { rollup: {}, rows: [] };