mandrel 2.59.0 → 2.61.0

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,

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

@@ -1,12 +1,6 @@
 /**
- * read.js — tolerant, strictly read-only filesystem access for the baseline
- * hotspot engine (Story #4902).
- *
- * The engine's job is to *report on* the baseline surface, including the
- * parts of it that are missing or malformed. So no read here throws: a
- * missing file, an unreadable directory, or a JSON parse error is evidence
- * the envelope carries, not a crash. Nothing in this module opens a file for
- * writing — the read-only invariant over `baselines/` starts here.
+ * Tolerant, strictly read-only fs access: a missing or malformed file is
+ * evidence for the envelope, never a throw.
  *
  * @module lib/audit-baselines/read
  */
@@ -15,8 +9,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Read and parse a JSON file without throwing.
- *
  * @param {string} absolutePath
  * @returns {{ exists: boolean, parsed: object | null, parseError: string | null }}
  */
@@ -39,10 +31,6 @@ export function readJsonFile(absolutePath) {
 }
 
 /**
- * List every file under `rootDir` as a posix repo-relative path, skipping
- * `node_modules`, `.git`, and `.worktrees`. Returns `[]` for an absent or
- * unreadable root rather than throwing.
- *
  * @param {string} repoRoot
  * @param {string} rootDir repo-relative directory to walk
  * @returns {string[]} sorted repo-relative posix paths
@@ -72,8 +60,7 @@ export function listFilesUnder(repoRoot, rootDir) {
 }
 
 /**
- * Age in whole days between `generatedAt` and `now`. Null when the stamp is
- * absent or unparseable — the engine reports "unknown", never a fabricated 0.
+ * Whole days; `null` (unknown) rather than a fabricated 0.
  *
  * @param {unknown} generatedAt
  * @param {Date} now

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

@@ -1,17 +1,7 @@
 /**
- * staleness.js — the two clocks a baseline is stale against (Story #4962).
- *
- * Wall-clock age answers the wrong question on a busy repository.
- * `coverage.json` and `maintainability.json` both read `staleDays: 0` while
- * already predating merges that had rescored files they still carry rows for:
- * refreshed an hour ago, and behind already. The second clock is the one that
- * matters — how many commits have touched the **measured surface** since the
- * baseline was last committed. A baseline older than the surface it scores is
- * stale at zero wall-clock days.
- *
- * Read-only and degrading, like the rest of this engine: a shallow clone, an
- * untracked baseline, or a surface that is not path-keyed all report `null`.
- * Unknown is never rounded down to a reassuring 0.
+ * Baseline staleness on two clocks: wall-clock age, and commits touching the
+ * measured surface since the baseline was committed — a baseline behind its
+ * surface is stale at zero days. Unknown reports `null`, never a reassuring 0.
  *
  * @module lib/audit-baselines/staleness
  */
@@ -21,9 +11,7 @@ import { KIND_SPECS } from './kinds.js';
 import { ageInDays } from './read.js';
 
 /**
- * Run a git command under `cwd`, returning trimmed stdout, or `null` on any
- * failure or empty result. Buffer and shell policy come from the shared
- * child-process surface ([`child-exec.js`](../child-exec.js)).
+ * Trimmed stdout, or `null` on failure or empty output.
  *
  * @param {string[]} args
  * @param {{ cwd: string, run?: Function }} io
@@ -45,11 +33,8 @@ function git(args, { cwd, run }) {
 }
 
 /**
- * The repo-relative paths whose commits would invalidate this baseline: the
- * gate's declared `targetDirs` when it has them, else the baseline's own row
- * ids — which are file paths for every kind but `lighthouse` (routes) and
- * `bundle-size` (bundle names). Those two get an empty surface rather than a
- * route name handed to git as a pathspec.
+ * `targetDirs`, else path-keyed row ids; non-path kinds get an empty surface
+ * rather than a bundle name as a git pathspec.
  *
  * @param {{ kind: string, gateBlock: object | null, rows: Array<{id: string}> }} args
  * @returns {string[]}
@@ -64,9 +49,7 @@ function measuredSurfaceOf({ kind, gateBlock, rows }) {
 }
 
 /**
- * Commits touching `surfacePaths` since `relPath` was last committed. An
- * empty surface yields `null` too: nothing was checked, so nothing can be
- * claimed.
+ * Empty surface → `null`: nothing checked, nothing claimed.
  *
  * @param {{ relPath: string, surfacePaths: string[], io: object }} args
  * @returns {number | null}
@@ -84,8 +67,6 @@ function commitsSinceBaseline({ relPath, surfacePaths, io }) {
 }
 
 /**
- * The four staleness fields of one `gateSurface[]` entry, on both clocks.
- *
  * @param {{
  *   kind: string, gateBlock: object | null, rows: Array<{id: string}>,
  *   relPath: string, baseline: object | null, now: Date,

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

@@ -1,16 +1,6 @@
 /**
- * surface-entry.js — the health report for one measuring instrument
- * (Story #4902, split out in #4962).
- *
- * A baseline review that only reads the numbers cannot see the failure mode
- * that matters most: an instrument that is not measuring anything. A gate can
- * be unconfigured, its baseline file can be missing, it can be a **stub**
- * (committed with no rows and an all-zero rollup, so it passes every run
- * vacuously), it can be stale on either clock, and its `ignoreGlobs` can name
- * paths that no longer exist — each of which reads as "green" from the gate's
- * exit code. This module turns all of that into declarative fields for one
- * kind; [`gate-surface.js`](gate-surface.js) walks the kinds and
- * [`staleness.js`](staleness.js) owns the two clocks.
+ * Health of one measuring instrument: unconfigured, missing, stub, stale, or
+ * dead `ignoreGlobs` — each of which reads green from the gate's exit code.
  *
  * @module lib/audit-baselines/surface-entry
  */
@@ -20,9 +10,7 @@ import { GATE_KINDS, KIND_SPECS, measuredTotalOf, rollupOf } from './kinds.js';
 import { stalenessOf } from './staleness.js';
 
 /**
- * True when every numeric leaf of the rollup is zero. A rollup with no
- * numeric leaves at all is not all-zero — it carries no measurement to call
- * zero, and treating it as such would flag shapes this engine cannot read.
+ * A rollup with no numeric leaves is not all-zero.
  *
  * @param {object | null} rollup
  * @returns {boolean}
@@ -34,10 +22,8 @@ function isAllZeroRollup(rollup) {
 }
 
 /**
- * A **stub instrument**: zero rows AND an all-zero rollup. Both halves are
- * required. Ratchet baselines carry no rollup, so a clean `arch-cycles`
- * allowlist — genuinely zero cycles, the success state — is never mistaken
- * for a dead instrument.
+ * Zero rows AND an all-zero rollup, so a clean ratchet (no rollup) is never
+ * called a stub.
  *
  * @param {{ rowCount: number, rollup: object | null }} args
  * @returns {boolean}
@@ -47,11 +33,9 @@ function isStubInstrument({ rowCount, rollup }) {
 }
 
 /**
- * Which of a gate's configured `ignoreGlobs` match zero files on disk.
- *
  * @param {string[]} ignoreGlobs
  * @param {string[]} files repo-relative posix paths
- * @returns {string[]}
+ * @returns {string[]} globs matching zero files
  */
 function findDeadIgnoreGlobs(ignoreGlobs, files) {
   const dead = [];
@@ -64,12 +48,7 @@ function findDeadIgnoreGlobs(ignoreGlobs, files) {
 }
 
 /**
- * Assemble one `gateSurface[]` entry from an already-read baseline.
- *
- * `rowCount` and `measured` both appear because they legitimately disagree:
- * rows are counted after the kind's per-file aggregation, while `measured` is
- * the quantity the instrument reports in its own unit — 589 dead-export
- * symbols sit in 187 files.
+ * `rowCount` (per-file) and `measured` (own unit) legitimately differ.
  *
  * @param {{
  *   kind: string, quality: object, read: object, relPath: string,

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

@@ -1,17 +1,7 @@
 /**
- * trend.js — per-kind rollup deltas read out of each baseline file's own git
- * history (Story #4902).
- *
- * A ratchet only tells you whether today is worse than yesterday. The
- * question a baseline review asks is the other one: which direction has this
- * number been moving, and is the ratchet actually ratcheting? That answer is
- * already committed — every baseline refresh is a commit against the same
- * path — so it is read with `git log` + `git show`, never recomputed by
- * re-running an instrument.
- *
- * Degradation: any git failure (shallow clone, no history for the path, not
- * a work tree) yields an empty `trend[]` and exit 0. A missing history is
- * missing evidence, not an error.
+ * Per-kind rollup direction of travel, read from each baseline's own git
+ * history — never recomputed. Any git failure yields no trend entry: missing
+ * history is missing evidence, not an error.
  *
  * @module lib/audit-baselines/trend
  */
@@ -20,7 +10,7 @@ import { execFileCapture } from '../child-exec.js';
 import { trendRollupOf } from './kinds.js';
 
 /**
- * List the most recent commits touching `relPath`, newest first.
+ * Newest first.
  *
  * @param {{ cwd: string, relPath: string, limit: number, run?: Function }} args
  * @returns {Array<{ sha: string, committedAt: string }>}
@@ -47,8 +37,6 @@ function listCommits({ cwd, relPath, limit, run }) {
 }
 
 /**
- * Read the comparable rollup of a baseline as it existed at `sha`.
- *
  * @param {{ cwd: string, kind: string, sha: string, relPath: string, run?: Function }} args
  * @returns {object | null}
  */
@@ -71,9 +59,8 @@ function rollupAt({ cwd, kind, sha, relPath, run }) {
 }
 
 /**
- * Numeric axis-by-axis difference `to - from`. Axes missing from either side
- * are omitted rather than defaulted — a rollup that gained an axis has no
- * delta on it, and inventing one would read as a regression.
+ * `to - from` per axis; an axis missing on either side is omitted, since an
+ * invented delta would read as a regression.
  *
  * @param {object} from
  * @param {object} to
@@ -91,7 +78,7 @@ function rollupDelta(from, to) {
 }
 
 /**
- * Build the `trend[]` section: newest-vs-previous rollup deltas per kind.
+ * Newest-vs-previous rollup deltas per kind.
  *
  * @param {{
  *   cwd: string, kinds: string[], pathFor: (kind: string) => string,