mandrel 2.60.0 → 2.61.0

package/.agents/scripts/check-context-budget.js

@@ -1,74 +1,16 @@
 /**
- * CLI: ratchet-down gate for the always-loaded documentation context budget
- * (Story #4438, Epic #4430 — Context Economy).
+ * CLI: ratchet gate for documentation context bytes against
+ * `baselines/context-budget.json`. Measures `alwaysLoaded` (the `CLAUDE.md`
+ * `@`-import closure), `mandatoryRead` (`project.docsContextFiles`) and
+ * `workflow` (entry points + `mandatoryReads:` closure).
  *
- * Follows the standalone `check-arch-cycles.js` / `check-dead-exports.js`
- * precedent — a pure-Node, baseline-aware, sub-second checker wired into the
- * CI `baselines` job — rather than a `baselines/kinds/` metric. It measures the
- * live byte total of three documentation read-tiers against a single committed
- * budget in `baselines/context-budget.json`:
+ * Only `alwaysLoaded` gates — every session and subagent spawn pays it. Exit 1
+ * when it grows past `totalBytes + toleranceBytes` or a recorded row names a
+ * path it no longer contains; every other drift, and all shrinkage, is
+ * reported with exit 0 (the close writes a lower total back). An empty tier or
+ * a missing baseline is a no-op. Tolerance lives only in the baseline JSON.
  *
- *   - `alwaysLoaded`  — the `CLAUDE.md` `@`-import closure re-paid on every
- *                       session and every subagent spawn (instructions.md § 4).
- *   - `mandatoryRead` — the resolved `project.docsContextFiles` set.
- *   - `workflow`      — the workflow **mandatory closure** (Story #4752): every
- *                       `.agents/workflows/**` entry point plus the transitive
- *                       closure of its `mandatoryReads:` frontmatter edges. The
- *                       companion **reachable** closure (per entry point) is
- *                       recorded under the top-level `workflowClosure` key.
- *
- * **One tier gates: `alwaysLoaded`.** It is the only tier every session and
- * every subagent spawn pays unconditionally, so growth there is a real tax on
- * every future turn. The other tiers are measured, recorded and printed, and
- * never fail the command (Story #5340). Demoting them is what makes workflow
- * prose editable again: under the old rule a prose fix had to be paid for with
- * an unrelated trim in the same commit, and that is how three reference
- * sections came to describe mechanisms the code had already retired. The
- * measurement is still worth seeing on every change, so it is kept as a
- * report rather than deleted. See `docs/decisions.md`, ADR 20260917-5340.
- *
- * The role-scoped agent-boot tier (`.agents/agents/*.md`) is recorded the same
- * way. Its former per-file 8 KB ceiling and the row-vs-tree drift gate are
- * gone with the same ADR — nothing enforces a per-file ceiling or a minimum
- * headroom on a workflow or agent file any more.
- *
- * A read-tier that resolves **empty** is skipped silently (the `docsContextFiles`
- * half skips when unconfigured / its files are absent), so a repo with no
- * `CLAUDE.md` and no context docs is a clean no-op.
- *
- * Ratchet semantics (mirroring the sibling ratchets):
- *   - The `alwaysLoaded` tier grows beyond `baseline.tiers.alwaysLoaded
- *     .totalBytes + baseline.toleranceBytes` → exit 1, naming the tier and its
- *     delta. Growth in any other measured tier is printed and exits 0.
- *   - A measured tier shrinks below its baseline total → **exit 0**, reported
- *     as an informational `-` line (Story #5313). This deliberately reverses
- *     Story #4872's "shrink fails" rule: that rule made every trim a red gate
- *     whose only remedy was a hand-run `--update`, so the gain was paid for
- *     twice. The concern it answered — a stale total silently absorbing the
- *     next growth — is now met by the close's write-back seam
- *     (`story-close/context-budget-writeback.js`), which rewrites the lower
- *     total into `baselines/context-budget.json` on the Story branch so the
- *     gain locks in without a failing gate. Shrinkage stays zero-tolerance
- *     in the *report* (every byte under the total is listed) so a sub-
- *     tolerance gain is never discarded by the write-back either.
- *   - A recorded `alwaysLoaded` row naming a path the measured tier no longer
- *     contains → exit 1. The row describes a file that has been deleted or
- *     de-listed, so the bytes it contributes to the recorded total are fiction.
- *     The same drift in a report-only tier is printed, not failed.
- *   - Within tolerance / clean → exit 0.
- *   - Baseline file absent → warn + exit 0 (no-op; nothing to ratchet against).
- *
- * Tolerance lives in the baseline JSON (`toleranceBytes`) — there is **no**
- * `.agentrc.json` config key; this is a framework-internal dogfooding ratchet,
- * like arch-cycles.
- *
- * Flags:
- *   --baseline <path>  override the budget path (default
- *                      `baselines/context-budget.json`, resolved from cwd).
- *   --root <path>      resolve tiers against an explicit repo root (default cwd).
- *   --update           reseed the baseline from the current measurement (keeps
- *                      the existing `toleranceBytes`, or defaults it) and exit 0.
- *   --json             write the structured envelope to stdout.
+ * Flags: --baseline <path>, --root <path>, --update (keeps tolerance), --json.
  */
 
 import fs from 'node:fs';
@@ -79,34 +21,24 @@ import { resolveConfig } from './lib/config-resolver.js';
 import { resolveDocTiers, tierTotalBytes } from './lib/doc-tiers.js';
 
 /**
- * The tiers this command measures and records (in report order).
- * `digestVisible`, `onDemand` and `workflowOnDemand` are resolved by the tier
- * map for the lens, but the byte budget intentionally measures only the tiers
- * a session is *forced* to read.
+ * Measured tiers, in report order — only those a session is forced to read.
  * @type {Array<'alwaysLoaded' | 'mandatoryRead' | 'workflow'>}
  */
 export const MEASURED_TIERS = ['alwaysLoaded', 'mandatoryRead', 'workflow'];
 
 /**
- * The tiers whose drift fails the command (Story #5340). Only `alwaysLoaded`
- * is paid by every session and every subagent spawn unconditionally, so it is
- * the one tier where growth is a tax nobody opted into. Everything else in
- * {@link MEASURED_TIERS} is a report.
+ * Tiers whose drift fails the command; the rest are report-only.
  * @type {Array<'alwaysLoaded'>}
  */
 export const ENFORCED_TIERS = ['alwaysLoaded'];
 
 /**
- * Default tolerance (bytes) seeded into a fresh baseline by `--update` when the
- * existing baseline carries none.
+ * Seeded by `--update` when the baseline carries none.
  * @type {number}
  */
 export const DEFAULT_TOLERANCE_BYTES = 2048;
 
 /**
- * Parse argv for `--baseline <path>`, `--root <path>`, `--update`, `--json`.
- * Exported so unit tests can pin the parser.
- *
  * @param {string[]} argv
  * @returns {{ baselinePath: string|null, rootPath: string|null, update: boolean, json: boolean }}
  */
@@ -139,8 +71,7 @@ export function parseArgv(argv = []) {
 }
 
 /**
- * Read the committed budget envelope from disk. Returns the parsed object or
- * `null` when the file is missing or unparseable.
+ * `null` when missing or unparseable.
  *
  * @param {string} baselinePath
  * @returns {{ toleranceBytes?: number, tiers?: Record<string, { totalBytes: number, files?: Array<{ path: string, bytes: number }> }> } | null}
@@ -157,9 +88,6 @@ export function loadBaseline(baselinePath) {
 }
 
 /**
- * Build the committed-baseline envelope from a resolved tier map. Only the
- * measured tiers are recorded (each as `{ totalBytes, files }`).
- *
  * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
  * @param {number} toleranceBytes
  * @returns {object}
@@ -170,10 +98,7 @@ export function buildBaseline(tierMap, toleranceBytes) {
     const files = tierMap.tiers[name] ?? [];
     tiers[name] = { totalBytes: tierTotalBytes(files), files };
   }
-  // The agent-boot tier is recorded top-level (not under `tiers`) because it
-  // carries no recorded total to diff against — it is a per-file size record
-  // the audit instruments read as hotspot rows. Keeping it out of `tiers`
-  // keeps the ratchet diff loop unambiguous.
+  // Top-level, not under `tiers`: a per-file size record with no total to diff.
   const agentBootFiles = (tierMap.tiers.agentBoot ?? []).map((f) => ({
     path: f.path,
     bytes: f.bytes,
@@ -186,8 +111,7 @@ export function buildBaseline(tierMap, toleranceBytes) {
     agentBoot: {
       files: agentBootFiles,
     },
-    // Recorded, never gated (#4752): the total reachable closure per workflow
-    // entry point.
+    // Recorded, never gated.
     workflowClosure: {
       reachableTotalBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
       entryPoints: tierMap.workflowClosure?.entryPoints ?? [],
@@ -196,11 +120,8 @@ export function buildBaseline(tierMap, toleranceBytes) {
 }
 
 /**
- * Collect the recorded rows of one measured tier that name a path the measured
- * tier no longer contains (Story #4872). A deleted file drops out of the
- * resolved tier, and so does one that has been de-listed from the read set —
- * either way the row's bytes are counted into a recorded total that no live
- * file backs, so the row is drift and not a detail.
+ * Recorded rows naming a path the tier no longer contains (deleted or
+ * de-listed) — their bytes inflate the total against nothing.
  *
  * @param {string} tier
  * @param {Array<{ path: string, bytes: number }>} files live tier measurement
@@ -222,12 +143,7 @@ function absentRows(tier, files, baseTier) {
 }
 
 /**
- * Pure diff: compare the current tier map against the committed baseline. A
- * measured tier with no current files is skipped; a tier absent from the
- * baseline is skipped. `grown` and `absent` entries in an {@link
- * ENFORCED_TIERS} tier fail the gate; every other entry — and every `shrunk`
- * entry — is reported (Story #5340, Story #5313) and `shrunk` is what the
- * close writes back. See the ratchet semantics in the module header.
+ * Pure diff against the baseline; empty or unrecorded tiers are skipped.
  *
  * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
  * @param {{ toleranceBytes?: number, tiers?: Record<string, { totalBytes: number }> }} baseline
@@ -268,9 +184,7 @@ export function diffBudget(tierMap, baseline) {
         delta: current - baselineBytes,
       });
     } else if (current < baselineBytes) {
-      // Deliberately zero-tolerance in the report: `tolerance` guards against
-      // churn from a trivial *addition*; mirroring it downward would hide a
-      // gain from the write-back that locks it in (Story #5313).
+      // Zero-tolerance downward, so the write-back never misses a small gain.
       shrunk.push({
         tier,
         current,
@@ -284,8 +198,6 @@ export function diffBudget(tierMap, baseline) {
 }
 
 /**
- * True when a diff entry belongs to a tier whose drift still fails the gate.
- *
  * @param {{ tier?: string }} entry
  * @returns {boolean}
  */
@@ -294,11 +206,7 @@ function isEnforced(entry) {
 }
 
 /**
- * Count the drift entries that fail the gate: growth past tolerance and a
- * recorded row the tree no longer backs, **in an {@link ENFORCED_TIERS} tier
- * only** (Story #5340). Shrinkage is not in the set (Story #5313 — the close
- * writes it back instead). This is the one place the failure set is defined
- * and both the summary tag and the exit code read it.
+ * The single definition of the failure set: enforced-tier `grown` + `absent`.
  *
  * @param {ReturnType<typeof diffBudget>} diff
  * @returns {number}
@@ -309,25 +217,11 @@ export function budgetFailureCount(diff) {
   return grown + absent;
 }
 
-/**
- * Render the human-readable diff. `+` lines are enforced tiers that grew
- * beyond tolerance; `-` lines are tiers that shrank below their recorded total
- * (informational — the close writes the lower total back) or rows naming a
- * path the tree no longer carries. Drift in a report-only tier is prefixed
- * with `~` and says so on the line, so a reader never has to cross-reference
- * {@link ENFORCED_TIERS} to know whether it broke the build. A one-line
- * summary always follows.
- *
- * @param {ReturnType<typeof diffBudget>} diff
- * @returns {string}
- */
 const REPORT_ONLY_NOTE = ' — reported, never gated';
 
 /**
- * Marker prefix and trailing note for one diff row. An enforced tier keeps the
- * caller's `+` / `-` marker and adds no note; a report-only tier is prefixed
- * with `~` and says so inline, so a reader never has to cross-reference
- * {@link ENFORCED_TIERS} to know whether the line broke the build.
+ * A report-only row is marked `~` with an inline note, so the line itself
+ * says whether it broke the build.
  *
  * @param {{ tier: string }} row
  * @param {string} enforcedPrefix
@@ -339,6 +233,10 @@ function gateMarks(row, enforcedPrefix) {
     : { prefix: '~', note: REPORT_ONLY_NOTE };
 }
 
+/**
+ * @param {ReturnType<typeof diffBudget>} diff
+ * @returns {string}
+ */
 export function renderDiff(diff) {
   const lines = [];
   for (const g of diff.grown) {
@@ -366,9 +264,7 @@ export function renderDiff(diff) {
 }
 
 /**
- * Render the workflow **reachable** closure line — recorded, never gated
- * (Story #4752). Returns `''` when there is no workflow tier to report, so the
- * caller can stay a one-liner.
+ * The workflow reachable-closure line, or `''`.
  *
  * @param {{ workflowClosure?: { reachableTotalBytes?: number, entryPoints?: unknown[] } }} tierMap
  * @param {{ workflowClosure?: { reachableTotalBytes?: number } } | null} [baseline]
@@ -385,11 +281,7 @@ export function renderReachable(tierMap, baseline) {
 }
 
 /**
- * Render the role-scoped agent-boot line — a pure size report since Story
- * #5340 removed the per-file ceiling. It names the largest boot context
- * because that is the number an author sizing a role-def edit wants, and the
- * total because that is what the whole role surface costs. Returns `''` when
- * the tree carries no role defs.
+ * The agent-boot size line (total and largest role def), or `''`.
  *
  * @param {{ tiers?: { agentBoot?: Array<{ path: string, bytes: number }> } }} tierMap
  * @returns {string}
@@ -402,23 +294,7 @@ function renderAgentBoot(tierMap) {
 }
 
 /**
- * Top-level CLI entry. Exported so tests can drive the full pipeline against a
- * tmpdir fixture with an injected config and sinks.
- *
- * @param {{
- *   argv?: string[],
- *   cwd?: string,
- *   config?: object,
- *   stdout?: { write: (s: string) => void },
- *   stderr?: { write: (s: string) => void },
- * }} [opts]
- * @returns {Promise<number>} 0 = clean / within tolerance / shrink-only / no-op;
- *   1 = the always-loaded tier grew beyond tolerance or one of its recorded
- *   rows is unbacked
- */
-/**
- * Write a fresh budget, preserving the recorded tolerance so `--update` never
- * silently widens the gate it is refreshing.
+ * Preserves the recorded tolerance so `--update` never widens the gate.
  *
  * @param {object} params
  * @returns {0}
@@ -447,9 +323,6 @@ function writeUpdatedBaseline({ tierMap, resolvedBaselinePath, json, stdout }) {
 }
 
 /**
- * An absent budget is a no-op, not a failure: a consumer that has never
- * recorded one has nothing to regress against.
- *
  * @param {object} params
  * @returns {0}
  */
@@ -473,9 +346,7 @@ function reportMissingBaseline({
 }
 
 /**
- * Score the tree against the recorded budget. Pure — every verdict the two
- * renderers below present is decided here, so they cannot disagree about what
- * failed or drift apart in which fields they surface.
+ * Every verdict is decided here, so the two renderers cannot disagree.
  *
  * @param {{ tierMap: object, baseline: object }} params
  * @returns {{ diff: object, exitCode: 0 | 1 }}
@@ -519,10 +390,7 @@ function renderJsonReport({
 }
 
 /**
- * Each failing condition gets its own remediation line: they are fixed
- * differently, so a single generic message would leave the author guessing
- * which applies. Only {@link ENFORCED_TIERS} drift speaks here — the report-
- * only lines are already marked `~` in the preview above.
+ * One remediation line per failing condition (each is fixed differently).
  *
  * @param {object} params
  * @returns {void}
@@ -542,14 +410,6 @@ function renderFailureDiagnostics({ report, stderr }) {
 }
 
 /**
- * @param {object} params
- * @returns {void}
- */
-/**
- * The optional closure lines, in print order, with the empty ones dropped.
- * Both renderers return `''` when they have nothing to say, so filtering here
- * keeps {@link renderTextReport} free of one branch per optional line.
- *
  * @param {{ tierMap: object, baseline: object | null }} params
  * @returns {string[]}
  */
@@ -559,6 +419,10 @@ function optionalReportLines({ tierMap, baseline }) {
   );
 }
 
+/**
+ * @param {object} params
+ * @returns {void}
+ */
 function renderTextReport({ tierMap, baseline, report, stdout, stderr }) {
   const { diff, exitCode } = report;
   stdout.write(`\n--- context-budget preview ---\n`);
@@ -569,6 +433,16 @@ function renderTextReport({ tierMap, baseline, report, stdout, stderr }) {
   if (exitCode === 1) renderFailureDiagnostics({ report, stderr });
 }
 
+/**
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   config?: object,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} 1 only for enforced-tier drift.
+ */
 export async function runCli({
   argv = process.argv.slice(2),
   cwd = process.cwd(),

package/.agents/scripts/check-cyclomatic.js

@@ -1,26 +1,9 @@
 /**
- * CLI: ratchet on cyclomatic complexity against
- * the fixed cyclomatic ceiling of 12 (Story #4923; the `cyclomaticMustFix`
- * config key was retired in Story #5313).
- *
- * The must-fix ceiling was documented as blocking (`code-quality-guardrails.md`
- * promises "the close-validation chain refuses the merge") while being read by
- * nothing. This is the consumer that makes the promise true. It joins the
- * standalone-ratchet family — `check-arch-cycles.js`, `check-dead-exports.js`,
- * `check-context-budget.js` — which the CI `baselines` job runs as a required
- * check, and it follows their contract exactly:
- *
- *   - Reads the committed breach baseline at `baselines/cyclomatic.json`
- *     (override with `--baseline <path>`).
- *   - Walks the maintainability gate's `targetDirs` / `ignoreGlobs` and scores
- *     every function with the in-repo escomplex kernel — no coverage artifact
- *     required, so the verdict is available on a cold checkout.
- *   - Exit 0 when clean, improved, or shrinking; exit 1 when a file gains an
- *     over-ceiling function or its worst function gets worse.
- *
- * `--update` rewrites the baseline from the current tree. That is the
- * sanctioned motion after a deliberate refactor lands, and the only way the
- * recorded breach count is allowed to rise.
+ * CLI: ratchet on the fixed cyclomatic ceiling of 12 against
+ * `baselines/cyclomatic.json`. Scores every function in the maintainability
+ * gate's `targetDirs` with the in-repo escomplex kernel — no coverage artifact,
+ * so it works on a cold checkout. Exit 1 when a file gains an over-ceiling
+ * function or its worst function worsens.
  */
 
 import fs from 'node:fs';
@@ -39,8 +22,6 @@ import {
 import { resolveScanScope } from './lib/cyclomatic-scope.js';
 
 /**
- * Parse `--baseline <path>`, `--json`, and `--update`.
- *
  * @param {string[]} argv
  * @returns {{ baselinePath: string | null, json: boolean, update: boolean }}
  */
@@ -66,10 +47,8 @@ function parseArgv(argv = []) {
 }
 
 /**
- * Read a breach baseline envelope from disk. Returns `null` when the file is
- * missing or unparseable — the caller treats that as an empty baseline, which
- * makes the very first run report every existing breach as `added` rather than
- * silently passing.
+ * `null` when missing or unparseable — treated as empty, so a first run
+ * reports every breach rather than silently passing.
  *
  * @param {string} baselinePath
  * @returns {{ ceiling?: number, rows?: Array<object> } | null}
@@ -85,9 +64,7 @@ function loadCyclomaticBaseline(baselinePath) {
 }
 
 /**
- * `--update`: rewrite the baseline from the current (whole-tree) scan. The
- * sanctioned motion after a deliberate refactor lands, and the only way the
- * recorded breach count is allowed to rise.
+ * `--update`: the only way the recorded breach count may rise.
  *
  * @param {{ scan: object, ceiling: number, baselinePath: string, writeFileImpl: Function, stdout: { write: (s: string) => void } }} args
  * @returns {number} Always 0 — writing a baseline cannot fail the ratchet.
@@ -108,8 +85,6 @@ function writeUpdatedBaseline({
 }
 
 /**
- * `--json`: the machine-readable comparison envelope.
- *
  * @param {{ policy: object, baseline: object|null, baselineRows: Array<object>, baselinePath: string, scan: object, diff: object, exitCode: number }} args
  * @returns {string}
  */
@@ -142,10 +117,8 @@ function renderJsonReport({
 }
 
 /**
- * Announce a baseline the comparison cannot fully trust: absent, or recorded
- * at a ceiling the config no longer uses. Both are warnings rather than
- * failures — the diff still runs, and staying silent is what would let an
- * operator read a meaningless verdict as a clean one.
+ * Warn (not fail) on an absent baseline or one recorded at another ceiling,
+ * so a meaningless verdict is never read as clean.
  *
  * @param {{ baseline: object|null, mustFix: number, baselinePath: string, stderr: { write: (s: string) => void } }} args
  * @returns {void}
@@ -165,9 +138,6 @@ function warnAboutBaseline({ baseline, mustFix, baselinePath, stderr }) {
 }
 
 /**
- * Top-level CLI entry. Exported so tests can drive the whole pipeline through
- * the injected seams below without spawning a process.
- *
  * @param {{
  *   argv?: string[],
  *   cwd?: string,
@@ -199,10 +169,8 @@ export async function runCli({
     baselinePath ?? DEFAULT_CYCLOMATIC_BASELINE,
   );
 
-  // Read the baseline before scanning: its rows are half the diff scope
-  // (Story #5109). `--update` rewrites the baseline from the whole tree, and
-  // `BASELINE_SCOPE=full` is the operator's explicit "re-derive everything",
-  // so both opt out of scoping entirely.
+  // Before scanning: baseline rows are half the scan scope. `--update` and
+  // `BASELINE_SCOPE=full` scan the whole tree.
   const baseline = loadBaselineImpl(resolvedBaselinePath);
   const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
   const scopeFiles = resolveScanScope({ cwd, config, update, baselineRows });

package/.agents/scripts/check-dead-exports.js

@@ -1,42 +1,13 @@
 /**
- * CLI: ratchet-down dead-export gate built on knip.
+ * CLI: ratchet-down dead-export gate built on knip. Diffs knip's unused
+ * exports — plus a `{ file, symbol: '*' }` row per module nothing imports —
+ * against `baselines/dead-exports.json` by `(file, symbol)`. Exit 1 only on an
+ * added row; a knip spawn/parse failure is advisory (exit 0 + warning) so a
+ * broken knip cannot block CI.
  *
- * Story #1852 (Epic #1831) shipped the advisory form. Story #3627 (Epic #3599)
- * converts it to a **ratchet-down gate**: exit 1 when `added.length > 0`
- * (new dead exports are not allowed), exit 0 when the diff is clean or when
- * only removals are detected (the baseline is shrinking, which is the success
- * signal). Knip spawn failures remain advisory (exit 0 + stderr warning) so a
- * misconfigured knip installation cannot block CI when we have no current
- * snapshot to compare against.
- *
- * Story #4575 adds the **production pass** (`--production`), the test-only-
- * importer discount: default mode counts a test as an importer, so
- * production-dead code hides behind its own tests. See
- * `lib/dead-exports-mode.js` for why the two passes carry separate baselines.
- *
- * Story #5001 widens what the ratchet can see: knip's `files` category (a
- * module nothing imports) now maps to a `{ file, symbol: '*' }` row alongside
- * the per-export rows, and `knip.json` lists `.agents/scripts/*.js` entry
- * points explicitly instead of by blanket glob — so a top-level CLI that
- * nothing invokes surfaces as dead instead of being declared live by the glob.
- *
- * Contract:
- *   - Reads the committed baseline at `baselines/dead-exports.json` — or
- *     `baselines/dead-exports-production.json` under `--production`
- *     (override either with `--baseline <path>`). Envelope shape:
- *       { $schema, kernelVersion, generatedAt, rows: [{ file, symbol }] }
- *   - Spawns `npx knip --reporter json --no-progress` (plus `--production`),
- *     parses stdout, extracts `{ file, symbol }` rows from `issues[].exports[]`
- *     **and** `issues[].files[]` — the latter as one `{ file, symbol: '*' }`
- *     whole-file row per module nothing imports (Story #5001).
- *   - Diffs current vs. baseline by `(file, symbol)` identity.
- *   - Prints `+ <file>: <symbol>` for each added dead export and
- *     `- <file>: <symbol>` for each removed one, then a summary line.
- *   - With `--json`: writes the structured envelope to stdout and skips the
- *     human summary. The envelope still includes `added`, `removed`,
- *     `baselineRows`, `currentRows`, and `exitCode`.
- *   - Exit codes: 0 = clean or removals-only; 1 = added exports detected.
- *     Knip spawn/parse failure exits 0 (advisory) with a stderr warning.
+ * `--production` discounts test-only importers (production-dead code hides
+ * behind its own tests) and uses its own baseline — see
+ * `lib/dead-exports-mode.js`.
  */
 
 import fs from 'node:fs';
@@ -51,9 +22,7 @@ import {
 import { resolveDeadExportsMode } from './lib/dead-exports-mode.js';
 
 /**
- * Parse argv for `--baseline <path>`, `--json`, `--knip-output <path>`, and
- * `--production`. `--knip-output` is a test seam: pass a pre-captured knip JSON
- * file instead of spawning knip. Exported so unit tests can pin the parser.
+ * `--knip-output` is a test seam: a pre-captured knip JSON instead of a spawn.
  *
  * @param {string[]} argv
  * @returns {{ baselinePath: string | null, json: boolean, knipOutputPath: string | null, production: boolean }}
@@ -87,9 +56,7 @@ export function parseArgv(argv = []) {
 }
 
 /**
- * Pure helper: read a baseline envelope from disk. Returns the parsed object
- * or `null` when the file is missing or unparseable. Exported for tests so
- * they can feed fixture paths.
+ * `null` when missing or unparseable.
  *
  * @param {string} baselinePath
  * @returns {{ kernelVersion?: string, generatedAt?: string, rows?: Array<{file: string, symbol: string}> } | null}
@@ -107,11 +74,7 @@ export function loadBaseline(baselinePath) {
 }
 
 /**
- * Pure helper: diff two `{ file, symbol }` row sets. Returns `added` (in
- * current but not baseline) and `removed` (in baseline but not current).
- * Identity is `<file>\0<symbol>`. Exported as the AC's "diff helper" — the
- * sibling test exercises both the added and removed branches against fixture
- * baselines without spawning knip.
+ * Diff two row sets by `(file, symbol)`, sorted for stable output.
  *
  * @param {Array<{ file: string, symbol: string }>} baselineRows
  * @param {Array<{ file: string, symbol: string }>} currentRows
@@ -126,7 +89,6 @@ export function diffRows(baselineRows, currentRows) {
   const currentSet = new Set((currentRows ?? []).map(key));
   const added = (currentRows ?? []).filter((r) => !baselineSet.has(key(r)));
   const removed = (baselineRows ?? []).filter((r) => !currentSet.has(key(r)));
-  // Sort deterministically so output is stable across runs.
   const sortFn = (a, b) =>
     a.file.localeCompare(b.file) || a.symbol.localeCompare(b.symbol);
   return {
@@ -136,15 +98,8 @@ export function diffRows(baselineRows, currentRows) {
 }
 
 /**
- * Pure helper: render the human-readable diff. Lines:
- *   `+ <file>: <symbol>` for added rows
- *   `- <file>: <symbol>` for removed rows
- * Followed by a one-line summary even on a clean diff so operators see the
- * "no drift" signal. When added rows are present the summary includes a
- * "(gate fail)" marker so the ratchet violation is visible in CI output.
- *
- * `label` distinguishes the two passes in CI logs, which run back to back and
- * would otherwise emit two identical-looking summaries.
+ * `+`/`-` rows then a summary line. `label` tells the two back-to-back passes
+ * apart in CI logs.
  *
  * @param {{ added: Array, removed: Array }} diff
  * @param {string} [label='dead-exports']
@@ -162,9 +117,6 @@ export function renderDiff(diff, label = 'dead-exports') {
 }
 
 /**
- * Top-level CLI entry. Exported so tests can drive the full pipeline through
- * injected hooks without spawning knip.
- *
  * @param {{
  *   argv?: string[],
  *   cwd?: string,
@@ -213,9 +165,6 @@ export async function runCli({
   const currentRows = extractRowsFromKnip(knipEnvelope);
   const diff = diffRows(baselineRows, currentRows);
 
-  // Ratchet-down gate: fail when new dead exports are introduced. Removals are
-  // the success signal (baseline shrinking). Knip spawn failures stay advisory
-  // so a misconfigured knip installation cannot block CI without a snapshot.
   const exitCode = knipError === null && diff.added.length > 0 ? 1 : 0;
 
   if (json) {