mandrel 2.60.0 → 2.61.0

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,

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;
     }