mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/Logger.js

@@ -1,52 +1,24 @@
 /**
- * Logger conventions (see `docs/patterns.md` → "Error Handling Convention"):
- *
- *   - `debug`:  verbose trace; only emitted when the logger level is `verbose`.
- *   - `info`:   normal progress.
- *   - `warn`:   recoverable issue the operator should notice.
- *   - `error`:  non-fatal failure; caller continues. Use when `throw` would
- *               be too loud (e.g. best-effort cleanup paths).
- *   - `fatal`:  unrecoverable; exits the process. Use only at CLI
- *               boundaries, never inside library code.
- *
- * Level is resolved **lazily on every emit** from `AGENT_LOG_LEVEL` (or a
- * `setLevel` override). Resolving per emit — rather than once at module
- * load — lets tests exercise every level branch in-process via `setLevel`
- * or a live `AGENT_LOG_LEVEL` flip, without spawning a child process per
- * level (Story #3329):
- *
- *   - `silent`   → only `fatal` emits.
- *   - `info`     → default. Emits `info` and above; suppresses `debug`.
- *   - `verbose`  → emits everything (including `debug`).
+ * `error` is non-fatal (the caller continues); `fatal` exits and belongs only
+ * at CLI boundaries. The level (`silent` = fatal only, `info` default,
+ * `verbose` adds debug) is resolved from `AGENT_LOG_LEVEL` on every emit, not
+ * at load, so tests can flip it in-process.
  */
 /**
- * Recognized log levels, lowest-noise first. Anything outside this set
- * resolves to `info`.
+ * Anything else resolves to `info`.
  *
  * @type {ReadonlySet<string>}
  */
 const VALID_LEVELS = Object.freeze(new Set(['silent', 'info', 'verbose']));
 
 /**
- * Process-wide level override. `null` means "no explicit override — read
- * `AGENT_LOG_LEVEL` from the environment on each resolve". `setLevel`
- * pins this so tests (and embedders) can exercise every level branch
- * in-process without spawning a child whose module-load reads a different
- * env var. `setLevel(null)` clears the pin and restores env-driven
- * resolution.
+ * `null` means read `AGENT_LOG_LEVEL` on each resolve.
  *
  * @type {string|null}
  */
 let levelOverride = null;
 
 /**
- * Resolve the active log level lazily. Honors an explicit `setLevel`
- * override first, otherwise reads `AGENT_LOG_LEVEL` from the environment
- * on every call. Resolving per emit (rather than once at module load)
- * means a test can flip `AGENT_LOG_LEVEL` — or call `setLevel` — and see
- * the level branches react in-process, without a child process per level
- * (Story #3329).
- *
  * @returns {'silent'|'info'|'verbose'}
  */
 export function resolveLevel() {
@@ -59,11 +31,8 @@ export function resolveLevel() {
 }
 
 /**
- * Pin the process-wide log level, bypassing `AGENT_LOG_LEVEL`. Pass a
- * recognized level (`silent` / `info` / `verbose`) to force it,
- * or `null` to clear the pin and restore env-driven resolution. An
- * unrecognized non-null value throws so callers cannot silently pin a
- * level that resolves to `info`.
+ * Pin the level (`null` clears it). An unrecognized value throws rather than
+ * silently pinning `info`.
  *
  * @param {('silent'|'info'|'verbose')|null} level
  * @returns {void}
@@ -89,24 +58,12 @@ function infoEnabled() {
   return resolveLevel() === 'info' || debugEnabled();
 }
 
-// Mutable sinks for `info` (defaults to stdout via console.log) and the
-// stdout branch of `createProgress` (defaults to console.log). `warn` already
-// uses console.warn which Node routes to stderr, but we expose a sink for it
-// too so a single `routeAllOutputToStderr()` call gives a uniform guarantee
-// to callers that "no Logger output lands on stdout" (Story #2278).
+// Swappable so `routeAllOutputToStderr()` can guarantee nothing hits stdout.
 let infoSink = (msg) => console.log(msg);
 let warnSink = (msg) => console.warn(msg);
 let progressStdoutSink = (msg) => console.log(msg);
 
-/**
- * Flip every Logger output that can land on stdout (`info`, `warn`, and the
- * stdout branch of `createProgress`) to stderr for the lifetime of the
- * process. Idempotent. Use when stdout is reserved for a structured payload
- * — for example the JSON envelope emitted by
- * `plan-context.js`, where any interleaved
- * `[Orchestrator] ℹ️ …` log line corrupts the captured file
- * (Story #2278).
- */
+/** For processes whose stdout is a structured payload. Idempotent. */
 export function routeAllOutputToStderr() {
   infoSink = (msg) => console.error(msg);
   warnSink = (msg) => console.error(msg);
@@ -114,11 +71,7 @@ export function routeAllOutputToStderr() {
 }
 
 export const Logger = {
-  /**
-   * The currently-resolved level. A getter (not a frozen snapshot) so it
-   * reflects `setLevel` overrides and live `AGENT_LOG_LEVEL` changes —
-   * reading `Logger.level` always returns what the next emit will use.
-   */
+  /** A getter, so it always reports what the next emit will use. */
   get level() {
     return resolveLevel();
   },
@@ -155,16 +108,8 @@ export const Logger = {
 };
 
 /**
- * Frozen no-op logger shaped like the public `Logger` surface (minus `fatal`,
- * which must never be silenced — silencing process-exit is a footgun). Use
- * this as the default-argument value when a function accepts an optional
- * logger; consumers that don't pass one get a uniform shape without each
- * call site re-declaring its own inline literal.
- *
- * Deliberately omits `fatal` so that any code path tempted to call
- * `logger.fatal(...)` against the no-op fails loudly rather than silently
- * skipping a process-exit that would otherwise have surfaced an
- * unrecoverable error.
+ * Default for an optional logger. Omits `fatal` deliberately: a silenced
+ * process-exit would hide an unrecoverable error, so calling it throws.
  */
 export const NOOP_LOGGER = Object.freeze({
   silent: true,
@@ -174,14 +119,7 @@ export const NOOP_LOGGER = Object.freeze({
   error() {},
 });
 
-/**
- * Frozen logger that routes every level to **stderr**. Use this when a
- * caller's stdout is a structured payload (e.g. the authoring-context JSON
- * envelope from `plan-context.js`) and any
- * progress/telemetry log must not interleave with the payload. Mirrors the
- * `{ info, warn, error, debug }` shape that the orchestration helpers
- * accept via optional `logger` arguments.
- */
+/** Every level to stderr, for callers whose stdout is a structured payload. */
 export const STDERR_LOGGER = Object.freeze({
   debug: (message) => console.error(message),
   info: (message) => console.error(message),

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

@@ -1,16 +1,7 @@
 /**
- * engine.js — assemble the `/audit-baselines` evidence envelope
- * (Story #4902).
- *
- * Strictly read-only and strictly offline: it reads committed baselines, the
- * resolved config, git history, the static import graph, and any friction
- * ledger it finds. It never writes under `baselines/`, never refreshes a
- * baseline, and never runs a test, coverage, or mutation suite — the whole
- * point is that a baseline review costs a file read, not a CI run.
- *
- * Findings are evidence, not a verdict: assembling the envelope is success,
- * however alarming its contents, so the CLI exits 0 whenever it got this far.
- * Judgment belongs to the lens that reads the envelope.
+ * Assembles the `/audit-baselines` evidence envelope. Read-only and offline:
+ * never writes baselines or runs a suite — a review costs a file read, not a
+ * CI run. Evidence, not a verdict: assembling it is success (exit 0).
  *
  * @module lib/audit-baselines/engine
  */
@@ -31,19 +22,16 @@ import {
   readFriction,
 } from './weights.js';
 
-/** Envelope `kind` discriminator; matches the shipped schema's const. */
+/** Matches the shipped schema's const. */
 const ENVELOPE_KIND = 'audit-baselines-envelope';
 
-/** Envelope schema version — bumped on any breaking shape change. */
+/** Bump on any breaking shape change. */
 const ENVELOPE_SCHEMA_VERSION = '1';
 
-/** Cap on emitted hotspot clusters, independent of the per-gate `topN`. */
 export const DEFAULT_HOTSPOT_LIMIT = 50;
 
 /**
- * Resolve the repository config without letting a broken `.agentrc.json`
- * abort the run — an unreadable config still leaves the baseline files
- * themselves readable at their default paths.
+ * A broken `.agentrc.json` must not abort: default baseline paths still read.
  *
  * @param {string} cwd
  * @returns {{ quality: object, configError: string | null }}
@@ -57,11 +45,8 @@ function resolveQualityBlock(cwd) {
 }
 
 /**
- * Absolute temp root the friction ledger is searched under, anchored to the
- * **analysed** repository rather than the process cwd. `resolvedTempRoot()`
- * anchors to whichever checkout the current process sits in, which is the
- * right answer for a writer and the wrong one here: an engine pointed at
- * another repo with `--cwd` must read that repo's ledger, not this one's.
+ * Anchored to the analysed repo (`--cwd`), not the process's checkout as
+ * `resolvedTempRoot()` would be.
  *
  * @param {string} cwd
  * @returns {string}
@@ -71,17 +56,13 @@ function tempRootFor(cwd) {
   try {
     relative = tempRootFrom(resolveConfig({ cwd }));
   } catch {
-    // Unreadable config — the framework default root is still worth probing.
+    // Unreadable config: probe the default root.
   }
   if (path.isAbsolute(relative)) return relative;
   return path.join(mainCheckoutRoot(cwd) ?? cwd, relative);
 }
 
 /**
- * Run the engine and return the envelope object. Pure with respect to the
- * filesystem apart from the reads named in the module docstring — writing
- * the result is the caller's job.
- *
  * @param {{
  *   cwd: string,
  *   topN?: number,
@@ -138,11 +119,10 @@ export function runEngine({
 }
 
 /**
- * Condense an envelope into the pure-JSON stdout summary. Small enough to
- * read in a terminal, and never carrying a row set.
+ * Terminal-sized stdout summary; never carries a row set.
  *
  * @param {object} envelope
- * @param {string} outPath absolute path the full envelope was written to
+ * @param {string} outPath
  * @returns {object}
  */
 export function summarize(envelope, outPath) {

package/.agents/scripts/lib/audit-baselines/gate-surface.js

@@ -1,11 +1,5 @@
 /**
- * gate-surface.js — walk both halves of the baseline surface (Story #4902).
- *
- * The closed `delivery.quality.gates` kinds and the out-of-band ratchet
- * baselines are one surface, and an engine that walks only the first silently
- * drops the second. This module owns that walk and the file universe an
- * `ignoreGlobs` entry is checked against; [`surface-entry.js`](surface-entry.js)
- * turns each kind into its health report.
+ * Walks both halves of the baseline surface (gates and ratchets).
  *
  * @module lib/audit-baselines/gate-surface
  */
@@ -16,9 +10,7 @@ import { listFilesUnder, readJsonFile } from './read.js';
 import { surfaceEntryFor } from './surface-entry.js';
 
 /**
- * Every `targetDirs` entry declared by any gate, deduplicated. This is the
- * file universe an `ignoreGlobs` entry is checked against — a glob that
- * matches nothing inside the dirs its own gate scans is dead weight.
+ * The file universe `ignoreGlobs` are checked against.
  *
  * @param {object | null | undefined} quality
  * @returns {string[]}
@@ -34,15 +26,9 @@ function declaredTargetDirs(quality) {
 }
 
 /**
- * Walk both halves of the gate surface — the closed `delivery.quality.gates`
- * kinds and the out-of-band ratchet baselines — and report each instrument's
- * health.
- *
  * @param {{ cwd: string, quality: object, now?: Date, run?: Function }} args
- *   `run` overrides the git spawn; `staleness.js` owns the real default.
  * @returns {{ entries: object[], baselines: Map<string, object|null> }}
- *   `baselines` carries each parsed envelope forward so the hotspot, trend,
- *   and headroom sections never re-read a 650KB file off disk.
+ *   `baselines` is carried forward so later sections never re-read from disk.
  */
 export function buildGateSurface({ cwd, quality, now = new Date(), run }) {
   const files = declaredTargetDirs(quality).flatMap((dir) =>

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

@@ -1,18 +1,7 @@
 /**
- * headroom.js — how much slack sits between each configured floor and the
- * number actually measured (Story #4902).
- *
- * A floor set far from reality is a gate that cannot fail. Headroom is the
- * distance the measurement could still drift before the gate notices, and it
- * is the direct input to the only remediation this lens ever recommends:
- * tighten the floor to what the repo already achieves.
- *
- * Both sides come from the repository, never from this module: the floor
- * from `resolveQuality()` over `.agentrc.json` (so a consumer's own floors
- * are the ones reported), and the measurement from the committed baseline's
- * whole-repo rollup. Polarity comes from `axisDirection` in the gate's own
- * floors phase, so "better" always means the same thing here as it does when
- * `check-baselines.js` decides pass or fail.
+ * Slack between each configured floor and the measured rollup — a floor far
+ * from reality is a gate that cannot fail. Polarity comes from the gate's own
+ * `axisDirection`, so "better" means what `check-baselines.js` means.
  *
  * @module lib/audit-baselines/headroom
  */
@@ -21,8 +10,7 @@ import { axisDirection } from '../orchestration/check-baselines/phases/floors.js
 import { rollupOf } from './kinds.js';
 
 /**
- * Signed distance from the floor, positive when the measurement sits on the
- * good side of it. Null when the baseline carries no value for the axis.
+ * Positive on the good side of the floor, negative when breached.
  *
  * @param {number | undefined} measured
  * @param {number} floor
@@ -35,8 +23,6 @@ function headroomFor(measured, floor, direction) {
 }
 
 /**
- * Build the `headroom[]` section across every configured gate kind.
- *
  * @param {{
  *   kinds: string[],
  *   quality: object,
@@ -60,8 +46,6 @@ export function buildHeadroom({ kinds, quality, baselines }) {
         floor,
         measured: typeof measured === 'number' ? measured : null,
         direction,
-        // Positive headroom = the measurement is on the good side of the
-        // floor by this much; negative = the floor is already breached.
         headroom: headroomFor(measured, floor, direction),
       });
     }

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

@@ -1,24 +1,12 @@
 /**
- * hotspots.js — join per-gate outliers into ranked, per-file clusters
- * (Story #4902).
- *
- * The signal a baseline review is looking for is *convergence*: the file that
- * is simultaneously a CRAP outlier, a maintainability outlier, and a
- * duplication outlier is a different kind of problem from three unrelated
- * files each bad at one thing. Reading the baselines one at a time cannot see
- * it, because each gate's own top-20 is a different list.
- *
- * So severity **adds across gate memberships** and the three cost
- * multipliers apply to the sum. Two gate memberships of severity s therefore
- * outrank one membership of severity s at equal churn, centrality, and
- * friction — which is the ranking property this section exists to provide.
+ * Per-file clusters of per-gate outliers. Severity adds across gate
+ * memberships before the cost multipliers apply, so convergence (one file bad
+ * on several gates) outranks a single membership.
  *
  * @module lib/audit-baselines/hotspots
  */
 
 /**
- * Group per-gate outlier rows by cluster id and rank them.
- *
  * @param {{
  *   outliers: Array<object>,
  *   weightsFor: (id: string) => {

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

@@ -1,31 +1,18 @@
 /**
- * kinds.js — the two halves of the gate surface, and how to read a row out
- * of each (Story #4902).
- *
- * Mandrel's baseline surface is not one list. `delivery.quality.gates` is a
- * **closed** AJV schema of eight kinds, enforced by `check-baselines.js`.
- * Alongside it sit out-of-band **ratchet** baselines — dead exports (two
- * passes), import cycles, context budget — which no gate block declares and
- * only the CI baselines job runs. An engine that walks one half and calls it
- * "the baselines" silently drops the other; both halves are enumerated here.
- *
- * `GATE_KINDS` is derived from `GATES_SCHEMA` rather than re-typed, so a
- * ninth gate kind landing in the schema reaches this engine automatically.
+ * Both halves of the baseline surface (gate kinds and out-of-band ratchets)
+ * and how to read rows from each.
  *
  * @module lib/audit-baselines/kinds
  */
 
 import { GATES_SCHEMA } from '../config/gates/index.js';
 
-/** The closed `delivery.quality.gates` kind set, in stable order. */
+/** Derived from the schema so a new gate kind arrives automatically. */
 export const GATE_KINDS = Object.freeze(
   Object.keys(GATES_SCHEMA.properties).sort(),
 );
 
-/**
- * Out-of-band ratchet baselines: committed under `baselines/` and enforced
- * only by the CI baselines job, never by `check-baselines.js`.
- */
+/** Enforced only by the CI baselines job, never by `check-baselines.js`. */
 const RATCHET_KINDS = Object.freeze([
   'arch-cycles',
   'context-budget',
@@ -34,13 +21,10 @@ const RATCHET_KINDS = Object.freeze([
   'dead-exports-production',
 ]);
 
-/** Every kind the engine walks, gates first then ratchets. */
 export const ALL_KINDS = Object.freeze([...GATE_KINDS, ...RATCHET_KINDS]);
 
 /**
- * Resolve a kind's baseline path from config, falling back to the framework
- * default layout. Never hardcodes a consumer's location: a repo that moved
- * `baselines/crap.json` via `gates.crap.baselinePath` is followed.
+ * Honours `gates.<kind>.baselinePath`, else `baselines/<kind>.json`.
  *
  * @param {string} kind
  * @param {object | null | undefined} quality resolved `delivery.quality`
@@ -55,9 +39,8 @@ export function baselinePathFor(kind, quality) {
 }
 
 /**
- * Flatten `context-budget.json` into `{ id, value }` rows. Its three
- * sections all measure the same axis (bytes of context a file costs) under
- * different keys, so they fold into one row set rather than three.
+ * All three `context-budget.json` sections measure bytes, so they fold into
+ * one row set.
  *
  * @param {object} baseline
  * @returns {Array<{ id: string, value: number }>}
@@ -79,8 +62,7 @@ function contextBudgetRows(baseline) {
 }
 
 /**
- * Count how many allowlisted cycles each module participates in. A module in
- * three cycles is a worse architectural hotspot than one in a single cycle.
+ * Allowlisted-cycle memberships per module.
  *
  * @param {object} baseline
  * @returns {Array<{ id: string, value: number }>}
@@ -96,8 +78,7 @@ function archCycleRows(baseline) {
 }
 
 /**
- * Count dead exports per file. The row grain is `{ file, symbol }`; the
- * hotspot grain is the file.
+ * Dead exports per file (rows are per symbol).
  *
  * @param {object} baseline
  * @returns {Array<{ id: string, value: number }>}
@@ -112,10 +93,8 @@ function deadExportRows(baseline) {
 }
 
 /**
- * Build the `{ id, value }` extractor for an envelope-shaped gate kind.
- *
- * @param {string} idKey row property carrying the cluster identity
- * @param {string} metric row property carrying the measured value
+ * @param {string} idKey
+ * @param {string} metric
  * @returns {(baseline: object) => Array<{ id: string, value: number }>}
  */
 function envelopeRows(idKey, metric) {
@@ -126,36 +105,21 @@ function envelopeRows(idKey, metric) {
 }
 
 /**
- * Fold `{ id, value }` rows into one whole-repo number.
- *
- * `TOTAL` is for **additive** metrics — dead-export symbols, context bytes,
- * lint errors — where the sum is the quantity the instrument measures.
- * `TALLY` is for **non-additive** ones — percentages, indices, scores — where
- * summing per-file values would fabricate a statistic; the honest whole-repo
- * number is how many rows are tracked, and the unit name says so.
+ * `TOTAL` sums additive metrics; `TALLY` counts rows for non-additive ones
+ * (percentages, indices), where a sum would fabricate a statistic.
  */
 const TOTAL = (rows) => rows.reduce((sum, row) => sum + row.value, 0);
 const TALLY = (rows) => rows.length;
 
 /**
- * `[unit, fold]` per kind: the unit each kind's whole-repo total is
- * denominated in, and how its rows fold into it.
- *
- * This is the fix for the roll-up that counted **files** for every kind
- * (Story #4962). `dead-exports-production` moving 590 → 589 *symbols* across
- * 187 files on both sides read as a delta of 0, and a 421-byte context-budget
- * growth read as 0 too, because the fallback counted rows — a grain finer than
- * the file for dead exports and coarser than the byte for context budget.
- * Naming the unit is half the fix: an axis called `symbols` or `bytes` cannot
- * be re-read as a file count the way a bare `rowCount` was.
+ * `[unit, fold]` per kind. The named unit keeps a whole-repo total from being
+ * misread as a file count.
  */
 const TREND_UNITS = Object.freeze({
   'bundle-size': ['rawKb', TOTAL],
   coverage: ['filesTracked', TALLY],
   crap: ['filesTracked', TALLY],
   duplication: ['filesTracked', TALLY],
-  lighthouse: ['routesTracked', TALLY],
-  lint: ['errorCount', TOTAL],
   maintainability: ['filesTracked', TALLY],
   mutation: ['filesTracked', TALLY],
   'arch-cycles': ['cycleMemberships', TOTAL],
@@ -166,16 +130,8 @@ const TREND_UNITS = Object.freeze({
 });
 
 /**
- * Per-kind row spec.
- *
- * - `metric`  — the axis a hotspot is measured on.
- * - `worse`   — which end of that axis is the bad end.
- * - `rows`    — baseline → `{ id, value }` pairs, already aggregated where
- *               the on-disk grain is finer than the file (dead exports,
- *               cycles).
- * - `idKind`  — what the cluster key names. Every kind but `lighthouse`
- *               (routes) and `bundle-size` (bundle names) keys on a
- *               repository file path.
+ * Per-kind row spec: hotspot `metric`, which end is `worse`, `rows`
+ * extractor (aggregated to file grain), and what the `idKind` key names.
  */
 export const KIND_SPECS = Object.freeze({
   'bundle-size': {
@@ -202,18 +158,6 @@ export const KIND_SPECS = Object.freeze({
     idKind: 'path',
     rows: envelopeRows('path', 'percentage'),
   },
-  lighthouse: {
-    metric: 'performance',
-    worse: 'lower',
-    idKind: 'route',
-    rows: envelopeRows('route', 'performance'),
-  },
-  lint: {
-    metric: 'errorCount',
-    worse: 'higher',
-    idKind: 'path',
-    rows: envelopeRows('path', 'errorCount'),
-  },
   maintainability: {
     metric: 'mi',
     worse: 'lower',
@@ -259,10 +203,8 @@ export const KIND_SPECS = Object.freeze({
 });
 
 /**
- * The whole-repo rollup for a kind, or `null` when the kind does not carry
- * one. Ratchet baselines have no rollup — which is why stub detection asks
- * for an all-zero rollup rather than merely empty rows: an `arch-cycles`
- * baseline with zero cycles is a passing gate, not a dead instrument.
+ * The `*` rollup, or `null` (ratchets carry none — a zero-cycle `arch-cycles`
+ * is a passing gate, not a stub).
  *
  * @param {object | null} baseline
  * @returns {object | null}
@@ -273,12 +215,8 @@ export function rollupOf(baseline) {
 }
 
 /**
- * The whole-repo quantity a kind measures, in the unit it measures it in —
- * `{ unit, value }`, or `null` when the kind or the baseline is unreadable.
- *
- * This sits beside `rowCount` in `gateSurface[]` precisely because the two
- * disagree: `dead-exports-production` carries 589 rows across 187 files, so a
- * lone `rowCount: 187` reads as a symbol count and is not one.
+ * Whole-repo quantity in its own unit; differs from `rowCount` whenever the
+ * row grain is not the unit.
  *
  * @param {string} kind
  * @param {object | null} baseline
@@ -293,12 +231,8 @@ export function measuredTotalOf(kind, baseline) {
 }
 
 /**
- * The rollup a trend sample compares on. Gate kinds carry their own, already
- * axis-named; ratchet baselines carry none, so the whole-repo total stands in
- * under its own unit — "dead exports went 590 → 589 **symbols**" is exactly
- * the direction-of-travel question trend answers, and skipping the ratchet
- * half here would leave it visible in `gateSurface[]` but invisible in
- * `trend[]`.
+ * Trend comparison rollup: the declared one, else (ratchets) the measured
+ * total under its unit, so ratchets appear in `trend[]` too.
  *
  * @param {string} kind
  * @param {object | null} baseline

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

@@ -1,31 +1,18 @@
 /**
- * outliers.js — bounded top-N outlier extraction per gate (Story #4902).
- *
- * `baselines/crap.json` alone is ~650KB of per-method rows. The engine must
- * never embed a whole baseline in its envelope, so every kind is narrowed to
- * at most `topN` rows here, before anything downstream sees them.
- *
- * Narrowing happens in two steps:
- *
- *   1. **Aggregate to the cluster grain.** Baseline rows are per-method
- *      (crap) or per-symbol (dead exports); hotspots are per-file. Each id
- *      keeps its single worst value, plus how many rows it contributed.
- *   2. **Score, then cut.** `severityWeight` is the row's position in its
- *      own kind's distribution, from 0 (the best value present) to 1 (the
- *      worst). Scoring within the kind is what makes CRAP 29 and MI 74
- *      comparable at all — the two axes share no unit, and the whole point
- *      of a cluster is to add them up.
+ * Bounded top-N outliers per gate, so no whole baseline enters the envelope.
+ * Rows fold to the file grain (worst value kept), then `severityWeight` is
+ * the position in the kind's own distribution (0 best … 1 worst) — which is
+ * what makes unit-less axes like CRAP and MI summable in a cluster.
  *
  * @module lib/audit-baselines/outliers
  */
 
 import { KIND_SPECS } from './kinds.js';
 
-/** Default bound on rows extracted per gate. */
 export const DEFAULT_TOP_N = 20;
 
 /**
- * Fold `{ id, value }` rows to one entry per id, keeping the worst value.
+ * One entry per id, worst value kept.
  *
  * @param {Array<{ id: string, value: number }>} rows
  * @param {'higher' | 'lower'} worse
@@ -48,9 +35,7 @@ function aggregateById(rows, worse) {
 }
 
 /**
- * Position of `value` in `[min, max]` normalized so 1 is always the worst
- * end. A degenerate distribution (every value identical) scores 1 for every
- * row: they are all equally the worst, and equally the best.
+ * 1 is always the worst end; a degenerate distribution scores all 1.
  *
  * @param {number} value
  * @param {number} min
@@ -65,8 +50,6 @@ function normalizeSeverity(value, min, max, worse) {
 }
 
 /**
- * Extract the bounded worst-N rows for one kind.
- *
  * @param {{ kind: string, baseline: object | null, topN?: number }} args
  * @returns {Array<{
  *   kind: string, id: string, metric: string, value: number,