mandrel 2.31.0 → 2.33.0

package/.agents/scripts/bootstrap.js

@@ -726,19 +726,25 @@ function githubSubMutationsSucceeded(gh) {
   return true;
 }
 
-/** Phase groups whose mutations actually landed, for the install ledger. */
-function resolveAppliedGroups(approvedGroups, report) {
-  const applied = new Set();
-  for (const group of approvedGroups ?? []) {
-    if (group === PHASE_GROUPS.GITHUB_ADMIN) {
-      const gh = report?.github;
-      if (gh && !gh.error && !gh.skipped && githubSubMutationsSucceeded(gh)) {
-        applied.add(group);
-      }
-      continue;
-    }
-    applied.add(group);
-  }
+/**
+ * Phase groups whose mutations actually landed, for the install ledger.
+ *
+ * Every project-side group runs on every install (Story #3690 replaced the
+ * consent-first phased-approval install with a plain summary+confirm loop),
+ * so the only variable is whether the irreversible GitHub-admin mutations
+ * landed. Story #5007 collapsed the set-threading this used to carry down to
+ * that one boolean.
+ *
+ * @param {object|undefined} report — the live execution report.
+ * @returns {Set<string>}
+ */
+function resolveAppliedGroups(report) {
+  const applied = new Set(Object.values(PHASE_GROUPS));
+  const gh = report?.github;
+  const githubApplied = Boolean(
+    gh && !gh.error && !gh.skipped && githubSubMutationsSucceeded(gh),
+  );
+  if (!githubApplied) applied.delete(PHASE_GROUPS.GITHUB_ADMIN);
   return applied;
 }
 
@@ -1210,23 +1216,22 @@ export async function provisionResources(state, deps = {}) {
 }
 
 /**
- * Step 6a — Project-side bootstrap. With phased approval removed, all
- * project-side phase groups are treated as approved.
+ * Step 6a — Project-side bootstrap. Every project-side phase runs; the
+ * install ledger decides afterwards which phase groups actually landed
+ * ({@link resolveAppliedGroups}).
  */
 export async function executeBootstrap(state) {
   Logger.info(
     `[Bootstrap] Starting project bootstrap at ${state.projectRoot} (owner=${state.answers.owner} repo=${state.answers.repo} base=${state.answers.baseBranch})`,
   );
-  const approvedGroups = new Set(Object.values(PHASE_GROUPS));
   const report = await applyProjectBootstrap({
     projectRoot: state.projectRoot,
     agentRoot: state.agentRoot,
     answers: state.answers,
-    approvedGroups,
     withQuality: state.withQuality === true,
     withIssueForms: state.withIssueForms === true,
   });
-  return { ok: true, payload: { report, approvedGroups } };
+  return { ok: true, payload: { report } };
 }
 
 /**
@@ -1293,22 +1298,19 @@ export async function executeGithubBootstrap(state) {
 
 /** Step 6c — Record the install ledger for a future uninstall. */
 export function recordLedger(state) {
-  const appliedGroups = resolveAppliedGroups(
-    state.approvedGroups,
-    state.report,
-  );
+  const appliedGroups = resolveAppliedGroups(state.report);
   const manifestCtx = {
     answers: state.answers,
     skipGithub: Boolean(state.flags['skip-github']),
     withQuality: state.withQuality === true,
   };
+  // The manifest always carries the unconditional ide-wiring / repo-config
+  // entries and `appliedGroups` always contains those groups, so the filter
+  // never empties. (Story #5007 removed the phased-approval gate that was the
+  // only way to reach an empty set.)
   const entries = buildMutationManifest(manifestCtx).filter((e) =>
     appliedGroups.has(e.phaseGroup),
   );
-  if (entries.length === 0) {
-    state.report.ledger = { written: false, reason: 'no-mutations-applied' };
-    return { ok: true, payload: {} };
-  }
   const record = buildLedgerRecord({
     entries,
     approvedGroups: appliedGroups,

package/.agents/scripts/check-baseline-drift.js

@@ -13,13 +13,23 @@
 // directory through the same scorer that writes the baseline, prints a per-row
 // before/after table for everything that moved beyond the gate's tolerance,
 // and exits non-zero when it finds any — so a consumer can wire it as a
-// scheduled CI job without wrapping it in verdict-parsing glue. Wiring it is
-// deliberately consumer-side work; nothing in this repo schedules it.
+// scheduled CI job without wrapping it in verdict-parsing glue. This repo
+// schedules the maintainability kind in `.github/workflows/baseline-drift.yml`;
+// a consumer materializing `.agents/` still owns its own schedule.
+//
+// `--require-scored` exists because the default skip-is-green contract below
+// is a fail-open trap for exactly that scheduled use. Measured on this repo:
+// `check-baseline-drift.js --gate crap` with no `coverage/coverage-final.json`
+// present prints "✅ No baseline drift detected" and exits 0 — a nightly job
+// wired that way reports green while having measured nothing. The flag turns
+// every skip into exit 2, so a job that asked for a kind and did not get it
+// reds instead.
 //
 // Exit codes:
 //   0 — no drift (or every kind skipped: disabled gate, no baseline, no scorer)
 //   1 — drift detected in at least one kind
-//   2 — the check itself could not run
+//   2 — the check itself could not run (including: a requested kind was
+//       skipped and `--require-scored` was passed)
 
 // Fail-fast if the framework's runtime deps are not installed — must be the
 // first import so the check runs before any third-party-importing sibling
@@ -42,6 +52,10 @@ diff-scoped gates structurally cannot see.
 Options:
   --gate <kind>       Restrict to one kind (repeatable). Default: ${DRIFT_KINDS.join(', ')}.
   --tolerance <n>     Override the per-gate absolute tolerance.
+  --require-scored    Treat a skipped kind (gate disabled, no baseline, no
+                      scorer, nothing scored) as a failure rather than a pass.
+                      Use this in scheduled jobs: without it a kind that could
+                      not be scored at all reports green.
   --json              Emit the machine-readable report instead of the table.
   -h, --help          Show this help.
 
@@ -55,16 +69,21 @@ commit the result with a \`baseline-refresh:\` tagged subject (non-empty body).`
  * cannot silently widen a scheduled job's scope.
  *
  * @param {string[]} argv
- * @returns {{ kinds: string[], tolerance: number|null, json: boolean }}
+ * @returns {{ kinds: string[], tolerance: number|null, json: boolean, requireScored: boolean }}
  */
 export function parseArgs(argv = []) {
   const kinds = [];
   let tolerance = null;
   let json = false;
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--gate' && argv[i + 1]) {
-      const kind = argv[i + 1];
+  // Lifted out of the loop rather than added to its else-if chain: the chain
+  // is the file's most complex method already, and a valueless boolean flag
+  // needs no positional handling to be recognised.
+  const requireScored = argv.includes('--require-scored');
+  const rest = argv.filter((a) => a !== '--require-scored');
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--gate' && rest[i + 1]) {
+      const kind = rest[i + 1];
       if (!DRIFT_KINDS.includes(kind)) {
         throw new Error(
           `[drift] unknown --gate "${kind}"; expected one of ${DRIFT_KINDS.join(', ')}`,
@@ -72,11 +91,11 @@ export function parseArgs(argv = []) {
       }
       kinds.push(kind);
       i += 1;
-    } else if (arg === '--tolerance' && argv[i + 1]) {
-      const value = Number(argv[i + 1]);
+    } else if (arg === '--tolerance' && rest[i + 1]) {
+      const value = Number(rest[i + 1]);
       if (!Number.isFinite(value)) {
         throw new Error(
-          `[drift] --tolerance must be a number (got ${argv[i + 1]})`,
+          `[drift] --tolerance must be a number (got ${rest[i + 1]})`,
         );
       }
       tolerance = value;
@@ -91,9 +110,44 @@ export function parseArgs(argv = []) {
     kinds: kinds.length > 0 ? kinds : [...DRIFT_KINDS],
     tolerance,
     json,
+    requireScored,
   };
 }
 
+/**
+ * Render the `--require-scored` verdict for a completed run.
+ *
+ * A skip is the detector's honest answer to "I could not score this kind" —
+ * `{ ok: true, skipped: '<reason>' }` — and the default contract maps that to
+ * a pass so an ad-hoc run does not red because coverage happened to be absent.
+ * Under `--require-scored` the same answer is a failure: the caller named the
+ * kinds it wanted measured, and a kind that was not measured is a gap, not a
+ * clean bill of health.
+ *
+ * Returns `null` when the flag is off or nothing was skipped, so the caller
+ * keeps the run's own 0/1 verdict untouched. Both "off" and "nothing skipped"
+ * are answered here rather than at the call site: the caller is the file's
+ * ratcheted entry point, and this is the branch's natural home anyway.
+ *
+ * @param {{ results?: Array<{ kind: string, skipped?: string }> }} run
+ * @param {boolean} requireScored  Whether `--require-scored` was passed.
+ * @returns {string|null} the operator-facing failure note, or null.
+ */
+function requireScoredFailure(run, requireScored) {
+  if (!requireScored) return null;
+  const skipped = (run?.results ?? []).filter((r) => r?.skipped);
+  if (skipped.length === 0) return null;
+  const detail = skipped.map((r) => `${r.kind} (${r.skipped})`).join(', ');
+  return (
+    `[drift] ❌ --require-scored: ${skipped.length} requested kind(s) were ` +
+    `not scored — ${detail}. The verdict above covers only the kinds that ` +
+    'DID score, which is why it can read clean. A scheduled run that cannot ' +
+    'measure a kind is not a clean run; fix the cause (a missing coverage ' +
+    'artifact, a missing baseline, a disabled gate) or drop the kind from ' +
+    'the invocation.'
+  );
+}
+
 /**
  * Run the drift check and render it. Returns the process exit code rather
  * than exiting, so the whole path is unit-testable.
@@ -112,10 +166,16 @@ export async function runCheckBaselineDrift({
     cwd,
     tolerance: args.tolerance,
   });
-  const output = args.json
+  const base = args.json
     ? JSON.stringify({ schemaVersion: '1', ...run }, null, 2)
     : formatDriftReport(run);
-  return { exitCode: run.ok ? 0 : 1, output };
+  // The note is appended rather than substituted: the drift table is still the
+  // useful half of the report for whichever kinds DID score. A note present at
+  // all means a requested kind went unmeasured, which is exit 2 regardless of
+  // what the measured kinds reported.
+  const unscored = requireScoredFailure(run, args.requireScored);
+  if (unscored) return { exitCode: 2, output: `${base}\n${unscored}` };
+  return { exitCode: run.ok ? 0 : 1, output: base };
 }
 
 /**

package/.agents/scripts/check-baseline-scope.js

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+
+// .agents/scripts/check-baseline-scope.js — Story #5012.
+//
+// Assert that every committed baseline's ROW SET still describes the tree.
+//
+// `check-baselines.js` answers "did a measured value regress?" and answers it
+// well. Nothing answered the prior question: does this baseline still measure
+// the right files? A row can point at a file deleted months ago, and an
+// in-scope file can carry no row at all, while every gate stays green — a
+// ratchet is perfectly capable of being green over almost nothing.
+//
+// This gate is measurement-free by construction. It runs no scorer, needs no
+// coverage artifact and no test run: it walks the directories the gate's own
+// config names (`lib/baselines/scope-inventory.js`) and compares that set
+// against the committed rows in both directions
+// (`lib/baselines/scope-assert.js`). That is what makes it cheap enough to be
+// a required check, and what makes its companion —
+// `prune-baseline-orphans.js` — a one-command remedy rather than a full
+// re-score.
+//
+// Exit codes:
+//   0  no fatal divergence (inherited divergence may still be warned about)
+//   1  fatal divergence — attributable to this change set, or strict mode
+//   2  the check could not run (unreadable config, unusable repository)
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { _internals as readerInternals } from './lib/baselines/reader.js';
+import {
+  assertScope,
+  attributeDivergence,
+  resolveStrictness,
+} from './lib/baselines/scope-assert.js';
+import {
+  buildScopeInventory,
+  SCOPE_KINDS,
+} from './lib/baselines/scope-inventory.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { getQuality } from './lib/config/quality.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { gitSpawn } from './lib/git-utils.js';
+
+const EXIT_PASS = 0;
+const EXIT_DIVERGED = 1;
+const EXIT_CANNOT_RUN = 2;
+
+/**
+ * Files whose edit makes merge-base attribution untrustworthy: once a branch
+ * has rewritten the scope rules themselves, "which side of the merge-base
+ * introduced this row" is no longer a question the diff can answer.
+ */
+const SCOPE_CONFIG_PATHS = Object.freeze([
+  '.c8rc.cjs',
+  '.agentrc.json',
+  '.agentrc.local.json',
+]);
+
+const HELP = {
+  invocation:
+    'node .agents/scripts/check-baseline-scope.js [--kind <kind>] [--base <ref>] [--strict] [--json]',
+  summary:
+    "Assert each committed baseline's row set still describes the tree — in-scope files with no row, and rows whose file is gone or out of scope.",
+  flags: [
+    ['--kind <kind>', 'Check one kind only (repeatable). Default: all.'],
+    ['--base <ref>', 'Attribution base ref. Default: origin/<baseBranch>.'],
+    ['--strict', 'Treat every divergence as fatal, skipping attribution.'],
+    ['--json', 'Emit the report as JSON instead of text.'],
+    ['--cwd <dir>', 'Repository root to check. Default: process.cwd().'],
+  ],
+  notes: [
+    'Exit codes:\n  0  no fatal divergence\n  1  fatal divergence\n  2  the check could not run',
+    'Remedy for a stale row: node .agents/scripts/prune-baseline-orphans.js',
+  ],
+};
+
+/**
+ * Parse argv into an options bag. Unknown flags are a config error rather than
+ * a silent no-op — a typo'd `--kinds` must not read as "check everything".
+ *
+ * @param {string[]} argv
+ * @returns {{ kinds: string[], base: string | null, strict: boolean, json: boolean, cwd: string }}
+ */
+export function parseArgs(argv = []) {
+  const out = { kinds: [], base: null, strict: false, json: false, cwd: null };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    i += 1;
+    if (arg === '--strict') out.strict = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--kind') {
+      out.kinds.push(value);
+      i += 1;
+    } else if (arg === '--base') {
+      out.base = value;
+      i += 1;
+    } else if (arg === '--cwd') {
+      out.cwd = value;
+      i += 1;
+    } else throw new Error(`unknown flag "${arg}" (try --help)`);
+  }
+  const unknown = out.kinds.filter((k) => !SCOPE_KINDS.includes(k));
+  if (unknown.length > 0) {
+    throw new Error(
+      `unknown --kind ${unknown.join(', ')}; expected one of ${SCOPE_KINDS.join(', ')}`,
+    );
+  }
+  if (out.kinds.length === 0) out.kinds = [...SCOPE_KINDS];
+  out.cwd = out.cwd ?? process.cwd();
+  return out;
+}
+
+/**
+ * Resolve the merge base between HEAD and the requested base ref, preferring
+ * the remote-tracking ref so a stale local `main` cannot widen attribution.
+ *
+ * Returns `{ base: null }` when no candidate resolves — the strictness
+ * resolver treats that as a reason to fail towards strict, never as a licence
+ * to skip.
+ *
+ * @param {{ cwd: string, baseRef: string }} params
+ * @returns {{ base: string | null, aheadOfBase: boolean }}
+ */
+function resolveMergeBase({ cwd, baseRef }) {
+  for (const candidate of [`origin/${baseRef}`, baseRef]) {
+    const merged = gitSpawn(cwd, 'merge-base', candidate, 'HEAD');
+    if (merged.status !== 0 || merged.stdout.length === 0) continue;
+    const head = gitSpawn(cwd, 'rev-parse', 'HEAD');
+    return {
+      base: merged.stdout,
+      aheadOfBase: head.status === 0 && head.stdout !== merged.stdout,
+    };
+  }
+  return { base: null, aheadOfBase: false };
+}
+
+/**
+ * Enumerate what `<base>..HEAD` did to the tree, split into the two sets
+ * attribution needs. A rename contributes its old path to `removed` and its
+ * new path to `added`, which is exactly how a rename strands a row.
+ *
+ * @param {{ cwd: string, base: string | null }} params
+ * @returns {{ added: string[], removed: string[], changed: string[] }}
+ */
+function readChangeSet({ cwd, base }) {
+  const empty = { added: [], removed: [], changed: [] };
+  if (base === null) return empty;
+  const diff = gitSpawn(cwd, 'diff', '--name-status', '-M', `${base}..HEAD`);
+  if (diff.status !== 0) return empty;
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const line of diff.stdout.split('\n').filter(Boolean)) {
+    const [code, first, second] = line.split('\t');
+    const letter = code[0];
+    if (letter === 'R' || letter === 'C') {
+      removed.push(first);
+      added.push(second);
+      changed.push(first, second);
+      continue;
+    }
+    if (letter === 'A') added.push(first);
+    if (letter === 'D') removed.push(first);
+    changed.push(first);
+  }
+  return { added, removed, changed };
+}
+
+/**
+ * Repo-relative paths of every baseline file in play — the "did this change
+ * set edit a baseline?" input to the strictness resolver.
+ *
+ * @param {{ cwd: string, kinds: string[] }} params
+ * @returns {string[]}
+ */
+function baselinePathsFor({ cwd, kinds }) {
+  return kinds.map((kind) =>
+    path
+      .relative(cwd, readerInternals.resolveBaselinePath(kind, { cwd }))
+      .split(path.sep)
+      .join('/'),
+  );
+}
+
+/**
+ * Read a baseline's rows, or `null` when the kind ships no baseline in this
+ * repository. Deliberately does NOT go through `reader.load`: an envelope too
+ * stale to satisfy its schema is exactly the state this gate exists to report,
+ * and refusing to read it would turn the report into a crash.
+ *
+ * @param {{ cwd: string, kind: string }} params
+ * @returns {Array<object> | null}
+ */
+function readRows({ cwd, kind }) {
+  const abs = readerInternals.resolveBaselinePath(kind, { cwd });
+  try {
+    const parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    return Array.isArray(parsed?.rows) ? parsed.rows : [];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assess one kind: inventory → both-directions assertion → attribution.
+ *
+ * @param {object} params
+ * @returns {object} One entry of the report's `kinds` array.
+ */
+function assessKind({ kind, cwd, quality, strict, changeSet }) {
+  const rows = readRows({ cwd, kind });
+  if (rows === null) {
+    return { kind, present: false, skipped: true, reason: 'no baseline file' };
+  }
+  const inventory = buildScopeInventory({ kind, cwd, quality });
+  const found = assertScope({
+    inventory,
+    rows,
+    existsOnDisk: (rel) => fs.existsSync(path.resolve(cwd, rel)),
+  });
+  if (found.skipped) return { kind, present: true, ...found };
+  const attributed = attributeDivergence({
+    missing: found.missing,
+    extra: found.extra,
+    added: changeSet.added,
+    removed: changeSet.removed,
+    strict,
+  });
+  return {
+    kind,
+    present: true,
+    skipped: false,
+    reason: null,
+    inScopeCount: inventory.files.length,
+    rowCount: rows.length,
+    ...attributed,
+  };
+}
+
+/**
+ * Run the whole assessment and return a report plus its exit code.
+ *
+ * @param {{ argv?: string[] }} [params]
+ * @returns {{ report: object, exitCode: number }}
+ */
+export function runScopeCheck({ argv = [] } = {}) {
+  const opts = parseArgs(argv);
+  const cwd = opts.cwd;
+  const config = resolveConfig({ cwd });
+  const quality = getQuality(config) ?? { gates: {} };
+  const baseRef = opts.base ?? config?.project?.baseBranch ?? 'main';
+  const { base, aheadOfBase } = resolveMergeBase({ cwd, baseRef });
+  const changeSet = readChangeSet({ cwd, base });
+  const strictness = opts.strict
+    ? { strict: true, reason: 'operator requested --strict' }
+    : resolveStrictness({
+        base,
+        aheadOfBase,
+        changedFiles: changeSet.changed,
+        baselinePaths: baselinePathsFor({ cwd, kinds: opts.kinds }),
+        scopeConfigPaths: SCOPE_CONFIG_PATHS,
+      });
+  const kinds = opts.kinds.map((kind) =>
+    assessKind({ kind, cwd, quality, strict: strictness.strict, changeSet }),
+  );
+  const fatalCount = kinds.reduce((sum, k) => sum + (k.fatalCount ?? 0), 0);
+  const report = {
+    schemaVersion: '1',
+    base,
+    strict: strictness.strict,
+    strictReason: strictness.reason,
+    fatalCount,
+    warningCount: kinds.reduce((sum, k) => sum + (k.warningCount ?? 0), 0),
+    kinds,
+  };
+  return { report, exitCode: fatalCount > 0 ? EXIT_DIVERGED : EXIT_PASS };
+}
+
+/**
+ * Render one kind's findings as indented text lines.
+ *
+ * @param {object} entry
+ * @returns {string[]}
+ */
+function renderKind(entry) {
+  if (entry.skipped) return [`  - ${entry.kind}: skipped (${entry.reason})`];
+  const head =
+    `  - ${entry.kind}: ${entry.rowCount} row(s) over ${entry.inScopeCount} ` +
+    `in-scope file(s) — ${entry.fatalCount} fatal, ${entry.warningCount} inherited`;
+  const lines = [head];
+  for (const file of entry.fatal.missing) {
+    lines.push(`      ✗ missing row: ${file}`);
+  }
+  for (const row of entry.fatal.extra) {
+    lines.push(`      ✗ stale row (${row.reason}): ${row.path}`);
+  }
+  return lines;
+}
+
+/**
+ * Render the whole report as text.
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatReport(report) {
+  const mode = report.strict ? 'strict' : 'attributed';
+  const lines = [
+    `[check-baseline-scope] ${report.fatalCount} fatal, ${report.warningCount} inherited ` +
+      `(${mode}: ${report.strictReason})`,
+    ...report.kinds.flatMap(renderKind),
+  ];
+  if (report.fatalCount > 0) {
+    lines.push(
+      '',
+      'A baseline no longer describes the tree. Prune provably-inert rows with:',
+      '  node .agents/scripts/prune-baseline-orphans.js',
+      'A missing row means a file was added without being measured — run that',
+      "kind's producer (npm run coverage:update / maintainability:update).",
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * CLI entry point. Returns its exit code rather than calling `process.exit()`,
+ * so `runAsCli`'s `propagateExitCode` path settles it through `flushStdio` and
+ * an unbounded report is not truncated at a pipe boundary (Story #4783).
+ *
+ * @returns {Promise<number>}
+ */
+async function main() {
+  let result;
+  try {
+    result = runScopeCheck({ argv: process.argv.slice(2) });
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    process.stdout.write(
+      `${JSON.stringify({ schemaVersion: '1', error: message }, null, 2)}\n`,
+    );
+    return EXIT_CANNOT_RUN;
+  }
+  const opts = { json: process.argv.includes('--json') };
+  process.stdout.write(
+    opts.json
+      ? `${JSON.stringify(result.report, null, 2)}\n`
+      : `${formatReport(result.report)}\n`,
+  );
+  return result.exitCode;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'check-baseline-scope',
+  usage: HELP,
+  propagateExitCode: true,
+});

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

@@ -14,13 +14,21 @@
  * 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[]`.
+ *     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.