mandrel 2.31.0 → 2.32.0

package/.agents/scripts/run-test-profile.js

@@ -8,10 +8,10 @@
  * runner only — set SKIP_PREFLIGHT=0 to include preflight if desired.
  */
 
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnChild } from './lib/child-exec.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { buildWebhookSafeTestEnv } from './lib/test-env.js';
 import { parseTapOutput } from './lib/test-profile/parse-tap.js';
@@ -56,13 +56,14 @@ export function parseProfileArgv(argv) {
  * @param {object} [opts]
  * @param {string[]} [opts.argv]
  * @param {string} [opts.cwd]
- * @param {typeof spawnSync} [opts.spawn]
+ * @param {Function} [opts.spawn] - Injected child runner; defaults to the
+ *   shared surface's real `spawnSync`.
  * @param {typeof fs} [opts.fs]
  */
 export function runTestProfile({
   argv = process.argv.slice(2),
   cwd = ROOT,
-  spawn = spawnSync,
+  spawn,
   fs: fsLike = fs,
 } = {}) {
   const { outDir, topN, testArgv } = parseProfileArgv(argv);
@@ -75,7 +76,8 @@ export function runTestProfile({
   ];
 
   const started = Date.now();
-  const result = spawn(process.execPath, nodeArgs, {
+  const result = spawnChild(process.execPath, nodeArgs, {
+    run: spawn,
     cwd,
     encoding: 'utf8',
     env: {
@@ -84,8 +86,6 @@ export function runTestProfile({
       FORCE_COLOR: '0',
       NO_COLOR: '1',
     },
-    maxBuffer: 64 * 1024 * 1024,
-    shell: false,
   });
   const wallDurationMs = Date.now() - started;
 

package/.agents/scripts/run-verify.js

@@ -6,8 +6,8 @@
  * locally, without epic-scoped MI projection or push semantics.
  *
  * Order: audit (SCA) → lint (includes docs:check + the arch-cycles ratchet) →
- * full test suite → unified baselines → the dead-exports and context-budget
- * ratchets.
+ * full test suite → unified baselines → the standalone ratchets
+ * (dead-exports ×2, context-budget, cyclomatic, schema-references).
  *
  * The `audit` step runs `npm audit --audit-level=high`, matching CI's
  * "Dependency Vulnerability Audit (SCA)" gate so a local green no longer hides
@@ -27,42 +27,60 @@
  * full-tree scan in check-dead-exports.js) to a command that already carries
  * the full test suite.
  *
- * A handful of CI gates cannot be reproduced by this command (action pinning,
- * TruffleHog secret scan, the BASELINE_SCOPE=full push-scoped maintainability
- * run) — those are catalogued in docs/ci-contract.md.
+ * Story #5004 closed the last two mirror gaps that were pure omission.
+ * `check-cyclomatic.js` (#4923) and `check-schema-references.js` (#4938) were
+ * each added to the `baselines` job's standalone-ratchet slot without ever
+ * being added here, so a green `verify` still hid both. Like their neighbours
+ * they are pure-Node and cost milliseconds.
+ *
+ * Still NOT mirrored: `check-workflow-citations.js` and
+ * `check-baseline-scope.js` run in CI's `baselines` job only —
+ * `.agents/rules/known-tooling-behavior.md` entry 2 carries the current
+ * coverage table. (`prune-baseline-orphans.js --check` used to sit in that
+ * list; it no longer runs in CI at all — the un-attributed duplicate of the
+ * scope gate's `extra` direction reds every open PR on inherited rows.) Nor are the CI gates this command structurally cannot
+ * reproduce (action pinning, TruffleHog secret scan) — those are catalogued
+ * in docs/ci-contract.md. The nightly full-scope re-score
+ * (.github/workflows/baseline-drift.yml) is deliberately outside this
+ * mirror too: it re-scores the whole tree, which is the cost `verify` exists
+ * to avoid paying on every run.
  */
 
 import { spawnSync } from 'node:child_process';
 import { runAsCli } from './lib/cli-utils.js';
 
+/**
+ * A gate step: `node .agents/scripts/<script>` plus any extra args. Seven of
+ * the ten steps share exactly that shape, so spelling it once leaves the list
+ * below readable as what it actually is — a gate *order* — instead of a wall
+ * of spawn tuples.
+ *
+ * @param {string} label reported as `failedStep` when the gate exits non-zero
+ * @param {string} script basename under `.agents/scripts/`
+ * @param {...string} args extra CLI args
+ * @returns {{ label: string, cmd: string, args: string[] }}
+ */
+const gate = (label, script, ...args) => ({
+  label,
+  cmd: 'node',
+  args: [`.agents/scripts/${script}`, ...args],
+});
+
 const STEPS = [
-  {
-    label: 'audit',
-    cmd: 'npm',
-    args: ['audit', '--audit-level=high'],
-  },
+  { label: 'audit', cmd: 'npm', args: ['audit', '--audit-level=high'] },
   { label: 'lint', cmd: 'npm', args: ['run', 'lint'] },
   { label: 'test', cmd: 'npm', args: ['test'] },
-  {
-    label: 'baselines',
-    cmd: 'node',
-    args: ['.agents/scripts/check-baselines.js'],
-  },
-  {
-    label: 'dead-exports',
-    cmd: 'node',
-    args: ['.agents/scripts/check-dead-exports.js'],
-  },
-  {
-    label: 'dead-exports-production',
-    cmd: 'node',
-    args: ['.agents/scripts/check-dead-exports.js', '--production'],
-  },
-  {
-    label: 'context-budget',
-    cmd: 'node',
-    args: ['.agents/scripts/check-context-budget.js'],
-  },
+  gate('baselines', 'check-baselines.js'),
+  // Ordered ahead of the dead-exports pair deliberately. When a new CLI is
+  // missing from knip.json's entry list, both gates fail — but only this one
+  // names the cause. Seeing the ratchet's whole-file diff first is what made
+  // "accept the diff" look like the fix during Story #5012.
+  gate('knip-entries', 'check-knip-entries.js'),
+  gate('dead-exports', 'check-dead-exports.js'),
+  gate('dead-exports-production', 'check-dead-exports.js', '--production'),
+  gate('context-budget', 'check-context-budget.js'),
+  gate('cyclomatic', 'check-cyclomatic.js'),
+  gate('schema-references', 'check-schema-references.js'),
 ];
 
 export function runVerifySteps({

package/.agents/scripts/single-story-close.js

@@ -44,6 +44,18 @@
  *                              [--no-auto-merge]
  *                              [--wait-merge | --no-wait-merge]
  *                              [--merge-watch-mode <sync|async>]
+ *                              [--override-review-block <reason>]
+ *
+ * `--override-review-block <reason>` is the one sanctioned way
+ * past a code-review CRITICAL blocker. A critical finding halts this script
+ * before auto-merge, and until this flag existed there was no override at all —
+ * so an operator who had read a finding and judged it wrong could only land by
+ * running `gh pr merge` themselves, bypassing the gate with nothing written
+ * down. The flag does not weaken the gate; it moves that escape hatch into a
+ * mandatory-reason audit trail (Story comment + PR comment + a
+ * `review-block-overridden` friction signal) and reports
+ * `gates.codeReview: "overridden"` on the terminal envelope. A bare or
+ * too-short reason fails during option parsing, before any phase runs.
  *
  * `--merge-watch-mode` (Story #4949) overrides `delivery.mergeWatch.mode` for
  * one invocation, on the same explicit-wins-over-config precedence
@@ -217,6 +229,14 @@ runAsCli(import.meta.url, main, {
         '--merge-watch-mode <sync|async>',
         'Override delivery.mergeWatch.mode for this invocation only. `async` caps the merge wait to a short probe window and returns the resumable `pending` terminal instead of holding the foreground slot — pass it on every close of a multi-Story run. An invalid value exits non-zero before any phase runs.',
       ],
+      [
+        '--override-review-block <reason>',
+        // Deliberately does not spell the merge CLI invocation: the
+        // merge-lockout rule in `check-lifecycle-lint.js` forbids that literal
+        // in any string outside `phases/auto-merge.js`, and it is right to —
+        // the point of this flag is that arming stays on the one code path.
+        'Land despite a Story-scope code-review CRITICAL blocker you have reviewed and judged wrong. The reason is mandatory (≥12 chars) and is recorded on the Story, on the PR, and as a `review-block-overridden` friction signal; the terminal envelope reports `gates.codeReview: "overridden"`. Use this instead of merging the PR by hand with the GitHub CLI — a hand-merge bypasses the gate with no record at all.',
+      ],
       ['--no-evidence', 'Do not reuse or write gate evidence stamps.'],
       ['--dry-run', 'Report the plan; mutate nothing.'],
     ],

package/.agents/scripts/single-story-init.js

@@ -54,7 +54,6 @@ import {
 import { getStoryBranch, gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
 import { TYPE_LABELS } from './lib/label-constants.js';
-import { setActiveStoryEnv } from './lib/observability/active-story-env.js';
 import { emitTerseResult } from './lib/observability/terse-result.js';
 import {
   executeFastForward,
@@ -492,10 +491,9 @@ export function seedStoryBranch({ cwd, storyBranch, baseBranch, progress }) {
 }
 
 /**
- * Provision a worktree (or check out the branch in single-tree mode), then
- * record the active-story environment markers. Returns the resolved
- * `workCwd`, `worktreeCreated`, and `installStatus`. Exported for testing
- * (owns the worktree/single-tree routing + setActiveStoryEnv call).
+ * Provision a worktree (or check out the branch in single-tree mode).
+ * Returns the resolved `workCwd`, `worktreeCreated`, and `installStatus`.
+ * Exported for testing (owns the worktree/single-tree routing).
  *
  * @param {object} opts
  * @param {object} opts.runtime
@@ -541,23 +539,6 @@ export async function provisionWorktree({
     gitSync(cwd, 'checkout', storyBranch);
   }
 
-  try {
-    // v2 Stories are standalone — no parent Epic. The helper omits
-    // CC_EPIC_ID from env + file; the trace hook keys its standalone-trace
-    // branch on CC_EPIC_ID being absent.
-    setActiveStoryEnv({
-      storyId,
-      workCwd,
-      logger: {
-        warn: (m) => progress('ENV', `⚠️ ${m}`),
-      },
-    });
-  } catch (err) {
-    Logger.error(
-      `[single-story-init] ⚠️ Failed to set active-Story env: ${err?.message ?? err}`,
-    );
-  }
-
   return { workCwd, worktreeCreated, installStatus };
 }
 
@@ -572,13 +553,11 @@ export async function runSingleStoryInit({
   injectedConfig,
   injectedSweep,
   // Story #3483: lets tests drive the lease preflight deterministically.
-  // `injectedAcquireLease` swaps the guard; `leaseNow` injects the clock the
-  // fail-closed liveness check evaluates against (audit #3513). `steal`
-  // forcibly transfers a foreign claim — the standalone path has no Epic
-  // heartbeat ledger, so a foreign assignee blocks unless stolen.
+  // `injectedAcquireLease` swaps the guard. `steal` forcibly transfers a
+  // foreign claim — the lease fails closed (audit #3513), so a foreign
+  // assignee blocks unless stolen.
   injectedAcquireLease,
   steal = false,
-  leaseNow,
   injectedVerifyRemote,
   // Story #4620: swap the git-touching provisioning steps so the
   // early-flip-then-rollback ordering is unit-testable without a real worktree.
@@ -652,13 +631,12 @@ export async function runSingleStoryInit({
     `Standalone Story: "${story.title}" → branch ${storyBranch} from ${baseBranch}.`,
   );
 
-  // Story #3483 — lease preflight. Take an exclusive, time-bounded claim on
-  // the Story ticket before any git mutation so two concurrent standalone
-  // runs cannot both drive the same Story. The standalone path has no Epic
-  // heartbeat ledger, so the guard fails closed (audit #3513): a foreign
-  // assignee is treated as a live claim and aborts init (naming the current
-  // owner) unless --steal forcibly transfers it. Unclaimed / self-held claims
-  // proceed. Skipped under --dry-run (no assignee mutation).
+  // Story #3483 — lease preflight. Take an exclusive claim on the Story
+  // ticket before any git mutation so two concurrent standalone runs cannot
+  // both drive the same Story. The guard fails closed (audit #3513): a
+  // foreign assignee aborts init (naming the current owner) unless --steal
+  // forcibly transfers it. Unclaimed / self-held claims proceed. Skipped
+  // under --dry-run (no assignee mutation).
   let workCwd = cwd;
   let worktreeCreated = false;
   let installStatus = { status: 'skipped', reason: 'dry-run' };
@@ -670,7 +648,6 @@ export async function runSingleStoryInit({
       storyId,
       config,
       steal: stealRequested,
-      now: leaseNow,
     });
     progress(
       'LEASE',

package/.agents/scripts/update-dead-exports-baseline.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+/**
+ * update-dead-exports-baseline.js — the producer behind the dead-export
+ * ratchet (Story #5011).
+ *
+ * `check-dead-exports.js` has shipped since Story #1852 with no way to write
+ * the baseline it ratchets against. Every seed and every refresh was therefore
+ * a hand-edit: run the checker with `--json`, copy `currentRows` out of the
+ * report, re-sort them, and preserve `$schema` / `kernelVersion` / `mode` by
+ * hand. That is the gap this CLI closes — dead-exports now sits beside its four
+ * `update-*-baseline.js` siblings instead of being the one baseline an operator
+ * had to author in a text editor.
+ *
+ * **Fail closed, unlike the checker.** `check-dead-exports.js` treats a knip
+ * spawn or parse failure as advisory (exit 0 + a stderr warning) because it
+ * still holds a committed snapshot to compare against — a broken knip install
+ * must not redden CI on its own. The producer has no such fallback: the file it
+ * is about to write *is* the snapshot. An empty row set persisted from a failed
+ * run would silently grandfather every dead export in the repository and blind
+ * the ratchet permanently. So this CLI exits non-zero and writes **nothing**
+ * whenever knip cannot run, its report cannot be parsed, or the knip version
+ * cannot be resolved. That asymmetry with the checker is deliberate.
+ *
+ * **Envelope, not the shared writer.** Dead-exports does not route through
+ * `lib/baselines/writer.js`: that writer admits only the kinds registered in
+ * `lib/baselines/envelope.js` and requires a `*` rollup row, while dead-exports
+ * is an out-of-band ratchet kind (`lib/audit-baselines/kinds.js`) that carries
+ * no rollup. This CLI writes exactly the shape the checker already reads and
+ * both committed baselines already carry:
+ *
+ *   { $schema, kernelVersion, generatedAt, [mode], rows: [{ file, symbol }] }
+ *
+ * `kernelVersion` is knip's own installed version — knip is the scorer, so a
+ * knip upgrade is what invalidates the rows. `mode` is stamped on the
+ * `--production` pass only, matching the committed production baseline.
+ *
+ * Rows are de-duplicated and sorted by `(file, symbol)` with the same
+ * comparator `check-dead-exports.js` uses for its diff output, so a re-run
+ * against an unchanged tree differs only in `generatedAt` and review sees real
+ * movement rather than reordering noise.
+ *
+ * The pass is selected with `--production`, and the baseline/label/mode triple
+ * comes from `lib/dead-exports-mode.js` — the same resolver the checker uses.
+ * Resolving that pairing independently here is precisely how a producer would
+ * end up writing production rows over the default baseline.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  extractRowsFromKnip,
+  readKnipOutput,
+  runKnip,
+} from './lib/dead-exports-knip.js';
+import { resolveDeadExportsMode } from './lib/dead-exports-mode.js';
+
+/** `$schema` ref stamped into every dead-export baseline envelope. */
+export const DEAD_EXPORTS_SCHEMA_REF =
+  'https://mandrel.dev/baselines/dead-exports.schema.json';
+
+/**
+ * Parse argv for `--production`, `--baseline <path>` and `--knip-output
+ * <path>`. `--knip-output` is the test seam: it feeds a pre-captured knip JSON
+ * report instead of spawning knip, and mirrors the checker's flag of the same
+ * name so a captured report drives both sides of the ratchet.
+ *
+ * @param {string[]} argv
+ * @returns {{ baselinePath: string | null, knipOutputPath: string | null, production: boolean }}
+ */
+export function parseArgv(argv = []) {
+  const out = { baselinePath: null, knipOutputPath: null, production: false };
+  const valueFlags = {
+    '--baseline': 'baselinePath',
+    '--knip-output': 'knipOutputPath',
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--production') {
+      out.production = true;
+      continue;
+    }
+    const field = valueFlags[arg];
+    const next = argv[i + 1];
+    if (field && next && !next.startsWith('--')) {
+      out[field] = next;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve the knip version to stamp as `kernelVersion`, read from the
+ * installed package rather than recalled. Returns `null` when knip is not
+ * installed or its manifest is unreadable — the caller treats that as a
+ * fail-closed condition, because an unstamped baseline cannot signal to a
+ * later run that the scorer moved underneath it.
+ *
+ * @param {{ cwd?: string, readFileImpl?: typeof fs.readFileSync }} [opts]
+ * @returns {string | null}
+ */
+export function resolveKnipKernelVersion({
+  cwd = process.cwd(),
+  readFileImpl = fs.readFileSync,
+} = {}) {
+  try {
+    const manifest = path.resolve(cwd, 'node_modules', 'knip', 'package.json');
+    const version = JSON.parse(readFileImpl(manifest, 'utf-8'))?.version;
+    return typeof version === 'string' && version.length > 0 ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * De-duplicate and sort `{ file, symbol }` rows into the committed order.
+ *
+ * Identity is `(file, symbol)` — the same identity `diffRows` in
+ * `check-dead-exports.js` uses — so two knip issue records naming the same
+ * dead file collapse to one row. The comparator is that checker's comparator,
+ * which is why re-sorting an already-committed baseline is a no-op.
+ *
+ * @param {Array<{ file?: unknown, symbol?: unknown }>} rows
+ * @returns {Array<{ file: string, symbol: string }>}
+ */
+export function normalizeRows(rows) {
+  const seen = new Set();
+  const out = [];
+  for (const row of rows ?? []) {
+    if (typeof row?.file !== 'string' || typeof row?.symbol !== 'string')
+      continue;
+    const key = `${row.file}\0${row.symbol}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ file: row.file, symbol: row.symbol });
+  }
+  return out.sort(
+    (a, b) => a.file.localeCompare(b.file) || a.symbol.localeCompare(b.symbol),
+  );
+}
+
+/**
+ * Assemble the baseline envelope. `mode` is stamped on the production pass
+ * only: the default baseline has never carried the key, and adding it would
+ * churn the committed file for no signal.
+ *
+ * @param {{ kernelVersion: string, mode: string, rows: Array<object>, generatedAt: string }} args
+ * @returns {object}
+ */
+export function buildEnvelope({ kernelVersion, mode, rows, generatedAt }) {
+  const envelope = {
+    $schema: DEAD_EXPORTS_SCHEMA_REF,
+    kernelVersion,
+    generatedAt,
+  };
+  if (mode === 'production') envelope.mode = mode;
+  envelope.rows = rows;
+  return envelope;
+}
+
+/**
+ * Obtain a knip report, either from the `--knip-output` seam or by spawning
+ * knip for the requested pass. Never throws; a failure is reported as
+ * `{ ok: false, error }` so the caller can fail closed without a try/catch.
+ *
+ * @param {{
+ *   cwd: string,
+ *   production: boolean,
+ *   knipOutputPath: string | null,
+ *   runKnipImpl: typeof runKnip,
+ *   readKnipOutputImpl: typeof readKnipOutput,
+ * }} args
+ * @returns {{ ok: true, envelope: unknown } | { ok: false, error: string }}
+ */
+export function collectKnipReport({
+  cwd,
+  production,
+  knipOutputPath,
+  runKnipImpl,
+  readKnipOutputImpl,
+}) {
+  if (knipOutputPath) {
+    const envelope = readKnipOutputImpl(path.resolve(cwd, knipOutputPath));
+    return envelope == null
+      ? { ok: false, error: `could not read knip report at ${knipOutputPath}` }
+      : { ok: true, envelope };
+  }
+  return runKnipImpl({ cwd, production });
+}
+
+/**
+ * Reject a report the extractor cannot read. `extractRowsFromKnip` is total —
+ * it answers `[]` for any shape it does not recognise — which is the right
+ * posture for an advisory checker and the wrong one for a producer: an
+ * unrecognised report and a genuinely clean repository would persist the same
+ * empty row set. Returns an error string, or `null` when the report is usable.
+ *
+ * @param {unknown} envelope
+ * @returns {string | null}
+ */
+export function describeUnusableReport(envelope) {
+  if (!envelope || typeof envelope !== 'object')
+    return 'knip report is not a JSON object';
+  if (!Array.isArray(envelope.issues))
+    return 'knip report carries no `issues` array';
+  return null;
+}
+
+/**
+ * Top-level CLI entry, exported so tests drive the whole pipeline through
+ * injected hooks without spawning knip or touching a committed baseline.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ *   runKnipImpl?: typeof runKnip,
+ *   readKnipOutputImpl?: typeof readKnipOutput,
+ *   readFileImpl?: typeof fs.readFileSync,
+ *   writeFileImpl?: typeof fs.writeFileSync,
+ *   renameImpl?: typeof fs.renameSync,
+ *   now?: () => string,
+ * }} [opts]
+ * @returns {Promise<number>} 0 on a written baseline; 1 on any fail-closed path.
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  runKnipImpl = runKnip,
+  readKnipOutputImpl = readKnipOutput,
+  readFileImpl = fs.readFileSync,
+  writeFileImpl = fs.writeFileSync,
+  renameImpl = fs.renameSync,
+  now = () => new Date().toISOString(),
+} = {}) {
+  const { baselinePath, knipOutputPath, production } = parseArgv(argv);
+  const { mode, label, baseline } = resolveDeadExportsMode(production);
+  const target = path.resolve(cwd, baselinePath ?? baseline);
+
+  const kernelVersion = resolveKnipKernelVersion({ cwd, readFileImpl });
+  if (!kernelVersion) {
+    stderr.write(
+      `[${label}] ❌ cannot resolve knip's version from node_modules/knip/package.json — refusing to write ${target}\n`,
+    );
+    return 1;
+  }
+
+  const report = collectKnipReport({
+    cwd,
+    production,
+    knipOutputPath,
+    runKnipImpl,
+    readKnipOutputImpl,
+  });
+  const failure = report.ok
+    ? describeUnusableReport(report.envelope)
+    : report.error;
+  if (failure) {
+    stderr.write(
+      `[${label}] ❌ ${failure} — refusing to write ${target} (an empty baseline would grandfather every dead export)\n`,
+    );
+    return 1;
+  }
+
+  const rows = normalizeRows(extractRowsFromKnip(report.envelope));
+  const envelope = buildEnvelope({
+    kernelVersion,
+    mode,
+    rows,
+    generatedAt: now(),
+  });
+  // Write-then-rename, matching `lib/baselines/writer.js`: a crash or a full
+  // disk mid-write must not leave a truncated envelope behind. An unparseable
+  // baseline reads as empty to `check-dead-exports.js`, which would report
+  // every pre-existing row as newly added.
+  const tmpTarget = `${target}.tmp`;
+  writeFileImpl(tmpTarget, `${JSON.stringify(envelope, null, 2)}\n`, 'utf-8');
+  renameImpl(tmpTarget, target);
+  stdout.write(
+    `[${label}] ✅ wrote ${rows.length} row(s) to ${target} (kernelVersion=${kernelVersion}).\n`,
+  );
+  return 0;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'dead-exports-baseline',
+  propagateExitCode: true,
+  errorPrefix: '[dead-exports-baseline] ❌ Fatal error',
+  usage: {
+    invocation:
+      'node .agents/scripts/update-dead-exports-baseline.js [--production] [--baseline <path>] [--knip-output <path>]',
+    summary:
+      'Scan → write one dead-export baseline. Regenerates the rows `check-dead-exports.js` ratchets against, so the snapshot is produced rather than hand-edited.',
+    flags: [
+      [
+        '--production',
+        'Write the production-pass baseline (baselines/dead-exports-production.json) instead of the default one.',
+      ],
+      ['--baseline <path>', 'Write to this path instead of the mode default.'],
+      [
+        '--knip-output <path>',
+        'Read a saved knip JSON report instead of running knip.',
+      ],
+    ],
+    notes: [
+      'Fails closed: when knip cannot run or its report cannot be parsed, the CLI exits 1 and writes nothing — the checker is advisory on that failure, the producer must not be.',
+      'There is no scope flag: knip scores the whole graph, so a diff-scoped refresh is not expressible. Run `npm run dead-exports:update` to refresh both passes.',
+      'Exit codes:\n  0  baseline written\n  1  knip unavailable, unparseable, or version unresolvable',
+    ],
+  },
+});

package/.agents/skills/core/gates-and-baselines/SKILL.md

@@ -18,7 +18,7 @@ allowed_tools:
 - **No gate may be skipped.** Failing lint means fix lint, not disable the rule; a failing test means fix the code, not `.skip` or delete the test. Gates are ordered shift-left so cheap checks fail first, and CI failure output is fed back verbatim with the directive to reproduce and fix locally before re-pushing.
 - **Introducing a gate that asserts on pre-existing state** (doc-drift, lint-vocabulary, dependency-cycle, missing-coverage) MUST land green at merge: either advisory-first (report-only until the backlog is burned down) or with the populated baseline committed in the same change that turns the gate on. Never wire a gate into `requiredChecks` that lands red on latent findings nobody authored.
 - **Refresh a baseline only when the change is deliberate** — a rename/move, an operator-approved complexity bump, a signed-off perf delta, an intentional API-surface change. Never refresh to paper over an unintentional regression; fix the regression instead.
-- **Pick the refresh that matches why you are refreshing** — the two are different scopes, and the wrong one silently no-ops. `npm run <kind>:update` is **diff-scoped**: it re-scores only files changed in `origin/main..HEAD` and preserves every other row verbatim. That is what you want after changing code. `npm run <kind>:reanchor` is the same script with `--full-scope`: it re-scores every file in every target dir. That is what you want when the baseline is **stale** — a scorer-version bump, a coverage-shape change, accumulated drift — because a diff-scoped run would leave the stale rows exactly as they were and the staleness finding would re-fire. Kinds: `coverage`, `crap`, `maintainability`, `duplication`; dead-exports and lighthouse have no npm script — regenerate the rows and edit `baselines/dead-exports*.json` / `baselines/lighthouse.json` directly. Run either on the **Story branch**, not on `main`.
+- **Pick the refresh that matches why you are refreshing** — the two are different scopes, and the wrong one silently no-ops. `npm run <kind>:update` is **diff-scoped**: it re-scores only files changed in `origin/main..HEAD` and preserves every other row verbatim. That is what you want after changing code. `npm run <kind>:reanchor` is the same script with `--full-scope`: it re-scores every file in every target dir. That is what you want when the baseline is **stale** — a scorer-version bump, a coverage-shape change, accumulated drift — because a diff-scoped run would leave the stale rows exactly as they were and the staleness finding would re-fire. Kinds with both scopes: `coverage`, `crap`, `maintainability`, `duplication`. Dead-exports has a producer but no scope axis — knip scores the whole graph, so `npm run dead-exports:update` (both passes, via `.agents/scripts/update-dead-exports-baseline.js`) is the only sanctioned way to write `baselines/dead-exports.json` / `baselines/dead-exports-production.json`; never hand-edit those files. Lighthouse still has no producer — edit `baselines/lighthouse.json` directly. Run any of them on the **Story branch**, not on `main`.
 - Verify the refresh diff is scoped to the relevant `baselines/<kind>.json` (plus cosmetic `package-lock.json` churn only). If unrelated files appear, STOP — the refresh is contaminated. Stage baseline files **explicitly** (`git add baselines/<kind>.json`); never `git add -A` in a refresh commit.
 - Commit-subject contract: a **Conventional-Commits** subject `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story that triggered it.
 - Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Story: #<storyId>` to the body whenever observability classification matters. Never pass `--no-verify`; the `commit-msg` hook (commitlint) MUST run and pass.
@@ -101,7 +101,7 @@ own as the parseable marker for any future reader.)
 | Maintainability | `npm run maintainability:update`   | `npm run maintainability:reanchor`   |
 | Coverage        | `npm run coverage:update`          | `npm run coverage:reanchor`          |
 | Duplication     | `npm run duplication:update`       | `npm run duplication:reanchor`       |
-| Dead-exports    | edit `baselines/dead-exports.json` / `baselines/dead-exports-production.json` (rows are `(file, symbol)`; `check-dead-exports.js --json` prints the current rows) | same — no scope flag applies |
+| Dead-exports    | `npm run dead-exports:update` (regenerates both passes; never hand-edit the JSON) | same — no scope flag applies |
 | Lighthouse      | edit `baselines/lighthouse.json`   | same — no scope flag applies         |
 
 1. **Run the matching command for your reason** — left column after a code

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-05T00:59:17.768Z",
+  "generatedAt": "2026-08-06T10:26:18.702Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -42,16 +42,6 @@
       "allowedTools": null,
       "vendor": null
     },
-    {
-      "name": "diagnose-friction",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/diagnose-friction/SKILL.md",
-      "description": "Wrap a shell command with diagnostic capture. On failure, print static suggestions and append a structured `friction` record to the per-Story signals.ndjson stream. Use whenever a script in the orchestration loop invokes a tool whose failure shape we want the analyzer to attribute.",
-      "policyCapsuleBullets": 9,
-      "allowedTools": ["Bash", "Read"],
-      "vendor": null
-    },
     {
       "name": "documentation-and-adrs",
       "tier": "core",