mandrel 2.52.0 → 2.53.0

package/.agents/agents/story-worker.md

@@ -101,17 +101,16 @@ node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
   --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
 ```
 
-Dispatch it in the **background**: it routinely outruns the host's
-synchronous Bash ceiling, and its completion re-invokes you — that
-notification is the signal. Never spawn a task to poll or `sleep`-loop
+Dispatch it in the **background**: it routinely outruns the host's sync
+Bash ceiling, and its completion re-invokes you — that is the signal. Never spawn a task to poll or `sleep`-loop
 against it; a waiter whose condition is wrong outlives the agent. Share
 `lint` / `typecheck` evidence with close via `evidence-gate.js`; never
 stamp coverage / CRAP fresh any other way.
 
 **It can legitimately run nothing.** With nothing changed under the CRAP
 `targetDirs` it skips capture and exits 0. An exit code is never evidence a
-gate did work — its **output** is: no credit was deposited, so run the full
-suite yourself before handing off.
+gate did work — its **output** is: no credit was deposited. Run the scoped
+projects for the roots you changed plus `verify[]`, not the whole suite.
 
 Gate output that lies: [`known-tooling-behavior.md`](../rules/known-tooling-behavior.md).
 Waiter traps: [`parallel-tooling.md`](../workflows/helpers/parallel-tooling.md) Rule 2.

package/.agents/docs/agentrc-reference.json

@@ -16,6 +16,7 @@
     "commands": {
       "test": "npm test",
       "typecheck": null,
+      "lint": null,
       "formatCheck": "npx biome format .",
       "formatWrite": "npx biome format --write ."
     }
@@ -94,7 +95,8 @@
   "delivery": {
     "execution": {
       "timeoutMs": 600000,
-      "fullSuiteLock": true
+      "fullSuiteLock": true,
+      "requireCreditedCapture": false
     },
     "docsFreshness": {
       "paths": ["README.md"]

package/.agents/docs/configuration.md

@@ -87,6 +87,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
 | `commands` | No | `object` | — | Shell commands the close-validation chain spawns. Each is run from the repo root. |
 | `commands.test` | No | `string` | `"npm test"` | Full test-suite command run by the close-validation chain. |
 | `commands.typecheck` | No | `string` \| `null` | `null` | Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it. |
+| `commands.lint` | No | `string` \| `null` | `null` | Lint command run as a close-validation gate. `null` (the default) uses `npm run lint`; the gate is mandatory, so unlike `typecheck` this key cannot disable it. Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-linter pair in one npm script and name that. |
 | `commands.formatCheck` | No | `string` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. |
 | `commands.formatWrite` | No | `string` | `"npx biome format --write ."` | Mutating format command the close-time format-autofix step spawns. |
 
@@ -148,6 +149,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `execution` | No | `object` | — | Wall-clock bounds on the subprocesses delivery spawns. |
 | `execution.timeoutMs` | No | `integer` | `600000` | Per-command timeout (ms) for the long-running spawns delivery drives — the close-validation chain and the gate CLIs. |
 | `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
+| `execution.requireCreditedCapture` | No | `boolean` | `false` | Refuse a full-suite coverage capture that no committed stamp covers, instead of paying for it. Default false — the run is announced (a warning naming the crediting invocation, emitted before the spawn) and then executed, which is the pre-existing behaviour. Set true when the whole-suite cost is large enough that a close should stop at zero seconds rather than absorb it silently. |
 | `docsFreshness` | No | `object` | — | Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it. |
 | `docsFreshness.paths` | No | `array<string>` | `["README.md"]` | Repo-relative documentation paths the audit-documentation lens adds to its target set. |
 | `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path. |

package/.agents/schemas/agentrc.schema.json

@@ -94,6 +94,16 @@
               "description": "Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it.",
               "default": null
             },
+            "lint": {
+              "type": ["string", "null"],
+              "minLength": 1,
+              "not": {
+                "type": "string",
+                "pattern": "([;&|`]|\\$\\()"
+              },
+              "description": "Lint command run as a close-validation gate. `null` (the default) uses `npm run lint`; the gate is mandatory, so unlike `typecheck` this key cannot disable it. Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-linter pair in one npm script and name that.",
+              "default": null
+            },
             "formatCheck": {
               "type": "string",
               "not": {
@@ -475,6 +485,11 @@
               "type": "boolean",
               "description": "Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.",
               "default": true
+            },
+            "requireCreditedCapture": {
+              "type": "boolean",
+              "description": "Refuse a full-suite coverage capture that no committed stamp covers, instead of paying for it. Default false — the run is announced (a warning naming the crediting invocation, emitted before the spawn) and then executed, which is the pre-existing behaviour. Set true when the whole-suite cost is large enough that a close should stop at zero seconds rather than absorb it silently.",
+              "default": false
             }
           },
           "additionalProperties": false

package/.agents/scripts/check-audit-attribution.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * CLI: attribute a red `npm audit` result to the diff or to the merge base.
+ *
+ * Runs from `ci.yml` immediately after the required "Dependency Vulnerability
+ * Audit (SCA)" step fails, and only on a pull request. It re-audits the merge
+ * base's committed lockfile and says, as the first line a reader sees,
+ * whether this branch caused the failure.
+ *
+ * The verdict never changes whether the branch may land — see
+ * `attributionExitCode` in `lib/audit-attribution.js`. It changes how long it
+ * takes to understand why it may not.
+ *
+ * Exit codes:
+ *   0 — the probe could not reach a verdict (`unknown`); the SCA step's own
+ *       failure stands unmodified.
+ *   1 — a verdict was reached: `pre-existing` or `introduced-by-this-diff`.
+ *       Both fail, because the advisory is real either way.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+import {
+  attributionExitCode,
+  deriveVerdict,
+  renderAttribution,
+  UNKNOWN,
+} from './lib/audit-attribution.js';
+import { execFileCapture, spawnCapture } from './lib/child-exec.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+
+/** The label the nightly sweep keys its reusable tracking issue on. */
+const TRACKING_LABEL = 'meta::dependency-advisory';
+
+const HELP = {
+  invocation:
+    'node .agents/scripts/check-audit-attribution.js --base <ref> [--cwd <dir>]',
+  summary:
+    'Say whether a red high-severity npm advisory came from this pull request or was already on its merge base.',
+  flags: [
+    ['--base <ref>', 'Base commit or ref to attribute against. Required.'],
+    ['--cwd <dir>', 'Repository root. Default: process.cwd().'],
+  ],
+  notes: [
+    'Run it only after the required SCA step has already failed — it re-audits\nthe base to attribute that failure, and reports `unknown` when the head\naudits clean.',
+    "Exit codes:\n  0  unknown — the probe degraded; the SCA step's own failure stands\n  1  a verdict was reached (pre-existing or introduced-by-this-diff)",
+    'Both real verdicts exit 1. A check that passed on `pre-existing` would let\nadvisories accumulate on `main` unnoticed, which is what the nightly sweep\n(.github/workflows/dependency-audit-cron.yml) exists to prevent.',
+  ],
+};
+
+export function parseArgs(argv) {
+  const out = { base: null, cwd: process.cwd() };
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--base') out.base = argv[++i] ?? null;
+    else if (a === '--cwd') out.cwd = argv[++i] ?? out.cwd;
+  }
+  return out;
+}
+
+/**
+ * Run `npm audit --audit-level=high` over a dependency manifest pair.
+ *
+ * `--package-lock-only` audits the committed lockfile without installing, so
+ * the probe never touches the job's own `node_modules`: an attribution
+ * mechanism that could disturb the tree it is reporting on would be a worse
+ * defect than the one it explains.
+ *
+ * @param {string} dir directory holding package.json + package-lock.json
+ * @returns {{ failed: boolean }}
+ */
+function auditDir(dir) {
+  const result = spawnCapture(
+    'npm',
+    ['audit', '--audit-level=high', '--package-lock-only'],
+    { cwd: dir },
+  );
+  if (result.status === 0) return { failed: false };
+  // npm exits non-zero for "advisories found" and for "could not audit"
+  // alike. Only a real audit verdict carries a report on stdout; anything
+  // else is a probe failure the caller must read as `unknown`.
+  if (/vulnerabilit/i.test(String(result.stdout ?? '')))
+    return { failed: true };
+  throw new Error(
+    `npm audit could not evaluate the base tree: ${String(result.stderr ?? '').slice(0, 200)}`,
+  );
+}
+
+/**
+ * Materialize the base commit's manifest pair into a scratch directory.
+ *
+ * Read out of git rather than from a checkout — the job's working tree is the
+ * head, and swapping files in it to run a probe is exactly the kind of side
+ * effect this must not have.
+ *
+ * @returns {string} the scratch directory (caller removes it)
+ */
+function materializeBase({ cwd, base, git }) {
+  const dir = mkdtempSync(path.join(tmpdir(), 'audit-attribution-'));
+  for (const file of ['package.json', 'package-lock.json']) {
+    writeFileSync(path.join(dir, file), git(cwd, 'show', `${base}:${file}`));
+  }
+  return dir;
+}
+
+// `execFileCapture` owns the stdout ceiling, `shell: false` and error
+// normalisation for the whole tree — a lockfile is large enough that a
+// re-forked local ceiling would be a real defect, not a style point.
+const defaultGit = (cwd, ...args) => execFileCapture('git', args, { cwd });
+
+/**
+ * The decision core, with every I/O collaborator injectable
+ * (`.agents/rules/test-seams.md` rules 1-2, 4) so the whole verdict table is
+ * reachable without a git history, a network, or an npm spawn.
+ *
+ * @returns {{ verdict: string, exitCode: number, lines: string[] }}
+ */
+export function runAttribution(argv = process.argv, deps = {}) {
+  const {
+    git = defaultGit,
+    auditHead = auditDir,
+    auditBase = auditDir,
+    materialize = materializeBase,
+    lookupTrackingIssue = defaultLookupTrackingIssue,
+    cleanup = (dir) => rmSync(dir, { recursive: true, force: true }),
+    logger = Logger,
+  } = deps;
+  const args = parseArgs(argv);
+
+  if (!args.base) {
+    const lines = renderAttribution({
+      verdict: UNKNOWN,
+      reason: 'no --base ref was supplied',
+    });
+    for (const line of lines) logger.info(line);
+    return { verdict: UNKNOWN, exitCode: 0, lines };
+  }
+
+  let headFailed;
+  try {
+    headFailed = auditHead(args.cwd).failed;
+  } catch (err) {
+    return report({ verdict: UNKNOWN, args, logger, reason: msg(err) });
+  }
+  if (!headFailed) {
+    return report({
+      verdict: UNKNOWN,
+      args,
+      logger,
+      reason: 'the head tree audits clean, so there is nothing to attribute',
+    });
+  }
+
+  let dir = null;
+  let baseAudit = null;
+  let reason = null;
+  try {
+    dir = materialize({ cwd: args.cwd, base: args.base, git });
+    baseAudit = auditBase(dir);
+  } catch (err) {
+    reason = msg(err);
+  } finally {
+    if (dir) {
+      try {
+        cleanup(dir);
+      } catch {
+        // A leaked scratch dir under the OS temp root is not worth failing a
+        // report over.
+      }
+    }
+  }
+
+  const verdict = deriveVerdict({ headFailed, baseAudit });
+  const trackingIssue =
+    verdict === UNKNOWN ? null : safeLookup(lookupTrackingIssue, args.cwd);
+  return report({ verdict, args, logger, reason, trackingIssue });
+}
+
+function msg(err) {
+  return String(err?.message ?? err).slice(0, 200);
+}
+
+function report({
+  verdict,
+  args,
+  logger,
+  reason = null,
+  trackingIssue = null,
+}) {
+  const lines = renderAttribution({
+    verdict,
+    baseRef: args.base,
+    trackingIssue,
+    reason,
+  });
+  for (const line of lines) logger.info(line);
+  return { verdict, exitCode: attributionExitCode(verdict), lines };
+}
+
+/**
+ * Look up the open tracking issue by LABEL, not a title search: GitHub's
+ * issue search index lags, and the nightly sweep keys the same issue the same
+ * way for the same reason.
+ */
+function defaultLookupTrackingIssue(cwd) {
+  const out = execFileCapture(
+    'gh',
+    [
+      'issue',
+      'list',
+      '--label',
+      TRACKING_LABEL,
+      '--state',
+      'open',
+      '--limit',
+      '1',
+      '--json',
+      'number',
+      '--jq',
+      '.[0].number // empty',
+    ],
+    { cwd },
+  ).trim();
+  return out ? Number(out) : null;
+}
+
+function safeLookup(lookup, cwd) {
+  try {
+    const n = lookup(cwd);
+    return Number.isInteger(n) ? n : null;
+  } catch {
+    // No token, no network, no `gh` — the verdict is still worth printing.
+    return null;
+  }
+}
+
+runAsCli(import.meta.url, async () => runAttribution().exitCode, {
+  source: 'audit-attribution',
+  propagateExitCode: true,
+  errorPrefix: '[audit-attribution] ❌ Fatal error',
+  usage: HELP,
+});

package/.agents/scripts/check-pinned-override-notes.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * CLI: assert `package.json`'s pinned-override safety notes still describe
+ * the pins they document.
+ *
+ * The `"//"` notes on a pinned `overrides` entry are consulted at exactly one
+ * moment — when someone is deciding whether bumping it is safe. A note that
+ * quotes a version the pin has since moved past answers that question wrong,
+ * and nothing was checking. This gate makes the note unable to fall behind.
+ *
+ * Exit codes:
+ *   0 — every documented override matches its note and its direct range.
+ *   1 — drift: a stale note, a broken lockstep, or a note for a pin that is
+ *       gone.
+ *   2 — the check could not run (no readable `package.json`).
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+import { auditPinnedOverrideNotes } from './lib/pinned-override-notes.js';
+
+const EXIT_PASS = 0;
+const EXIT_DRIFT = 1;
+const EXIT_CANNOT_RUN = 2;
+
+const HELP = {
+  invocation:
+    'node .agents/scripts/check-pinned-override-notes.js [--cwd <dir>] [--json]',
+  summary:
+    'Assert every "//" note documenting a pinned npm override states the range that override actually carries, and that its direct dependency range matches.',
+  flags: [
+    ['--cwd <dir>', 'Repository root to check. Default: process.cwd().'],
+    ['--json', 'Emit the findings as JSON instead of text.'],
+  ],
+  notes: [
+    'Checks are derived from the "//" keys themselves — any `overrides.<name>`\nnote is covered, so a second pinned override is guarded by writing its note.',
+    'A note quoting no semver range at all is not scored: prose that names no\nversion cannot go stale.',
+    'Exit codes:\n  0  notes match their pins\n  1  drift (stale note, broken lockstep, or a note for a removed pin)\n  2  the check could not run',
+  ],
+};
+
+export function parseArgs(argv) {
+  const out = { cwd: process.cwd(), json: false };
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--cwd') out.cwd = argv[++i] ?? out.cwd;
+    else if (argv[i] === '--json') out.json = true;
+  }
+  return out;
+}
+
+/**
+ * @param {string[]} [argv]
+ * @param {{ readPackage?: (cwd: string) => object, logger?: object }} [deps]
+ * @returns {number} process exit code
+ */
+export function runCheck(argv = process.argv, deps = {}) {
+  const { readPackage = defaultReadPackage, logger = Logger } = deps;
+  const args = parseArgs(argv);
+
+  let pkg;
+  try {
+    pkg = readPackage(args.cwd);
+  } catch (err) {
+    logger.error(
+      `[pinned-override-notes] ✖ could not read package.json: ${String(err?.message ?? err)}`,
+    );
+    return EXIT_CANNOT_RUN;
+  }
+
+  const report = auditPinnedOverrideNotes(pkg);
+  if (args.json) {
+    logger.info(JSON.stringify(report, null, 2));
+    return report.findings.length > 0 ? EXIT_DRIFT : EXIT_PASS;
+  }
+
+  if (report.findings.length === 0) {
+    logger.info(
+      `[pinned-override-notes] ✅ ${report.checked.length} documented override pin(s) match their notes.`,
+    );
+    return EXIT_PASS;
+  }
+  for (const finding of report.findings) {
+    logger.error(
+      `[pinned-override-notes] ✖ ${finding.kind}: ${finding.detail}`,
+    );
+  }
+  return EXIT_DRIFT;
+}
+
+function defaultReadPackage(cwd) {
+  return JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+}
+
+runAsCli(import.meta.url, async () => runCheck(), {
+  source: 'pinned-override-notes',
+  propagateExitCode: true,
+  errorPrefix: '[pinned-override-notes] ❌ Fatal error',
+  usage: HELP,
+});

package/.agents/scripts/coverage-capture.js

@@ -12,10 +12,13 @@
  *   3. Test freshness: content digest of `crap.targetDirs` vs. the persisted
  *      capture stamp (`coverage/.capture-stamp.json`), falling back to the
  *      artifact-mtime heuristic when no stamp exists. Exit 0 when fresh.
- *   4. Otherwise spawn `npm run test:coverage` — serialized behind the
- *      host-level full-suite lock (Story #5173) so two concurrent runs on one
- *      checkout do not race — write a fresh capture stamp on success, and
- *      propagate the exit code.
+ *   4. Otherwise announce the uncredited full-suite run — naming the
+ *      invocation that would have deposited credit — and then spawn
+ *      `npm run test:coverage`, serialized behind the host-level full-suite
+ *      lock (Story #5173) so two concurrent runs on one checkout do not race;
+ *      write a fresh capture stamp on success and propagate the exit code.
+ *      With `delivery.execution.requireCreditedCapture` set, step 4 refuses
+ *      instead of spawning, so the cost is never paid unannounced.
  *
  * Step 3 is preceded by the changed-file skip when
  * `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` is on
@@ -24,15 +27,18 @@
  *
  * Exit codes:
  *   0 — coverage is fresh (or capture skipped/succeeded).
- *   1 — capture run failed (broken tests or coverage-threshold breach). The
- *       caller MUST surface this — silently passing here would defeat the
- *       CRAP gate's `requireCoverage: true` policy.
+ *   1 — capture run failed (broken tests or coverage-threshold breach), or
+ *       the run was refused because it carried no credit and
+ *       `delivery.execution.requireCreditedCapture` is set. The caller MUST
+ *       surface this — silently passing here would defeat the CRAP gate's
+ *       `requireCoverage: true` policy.
  */
 import { getChangedFiles } from './lib/changed-files.js';
 import { isDirectInvocation } from './lib/cli-utils.js';
 import { getQuality, resolveConfig } from './lib/config-resolver.js';
 import {
   computeContentDigest,
+  creditedCapture,
   filterFilesUnderTargets,
   isCoverageFresh,
   runCapture,
@@ -110,6 +116,11 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
   const args = parseArgs(argv);
   const config = resolveConfigImpl({ cwd: args.cwd });
   const { crap, coverage } = getQualityImpl(config);
+  // Read once here, where the config is already in scope, and thread it into
+  // whichever capture path reaches a spawn. Default false — an unconfigured
+  // consumer gets the announcement and the run, exactly as before.
+  const requireCreditedCapture =
+    config?.delivery?.execution?.requireCreditedCapture === true;
 
   if (crap.enabled === false) {
     logger.info('[coverage-capture] CRAP gate disabled — skipping capture.');
@@ -138,38 +149,42 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
   // knowing about it. `delivery.execution.fullSuiteLock: false` and
   // `MANDREL_FULL_SUITE_LOCK=0` each disable it; both hatches live in
   // `isFullSuiteLockEnabled`.
-  const capture = lockedCapture(runCaptureImpl, config);
+  // Two wrappers, composed outermost-first: the credit probe announces (or
+  // refuses) the run, and only a run that survives it reaches the host lock.
+  // Whichever capture path gets here spawns through both without knowing
+  // about either.
+  const capture = creditedCapture(lockedCapture(runCaptureImpl, config), {
+    requireCredited: requireCreditedCapture,
+    logger,
+  });
 
   // Story #4981/#5173 — the capture skip, gated by
   // `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` (on
   // by default). `null` means "not applicable" (switched off, or a
   // ref-resolution error) — fall through to the full-scope path below rather
   // than silently skipping capture.
-  const incrementalResult = tryIncrementalCapture({
+  // The two capture paths take the same collaborators bar one; naming that
+  // set once keeps a new seam from being threaded into one and forgotten on
+  // the other.
+  const shared = {
     crap,
     coverage,
     args,
     getChangedFilesImpl,
-    filterFilesUnderTargetsImpl,
     isCoverageFreshImpl,
     runCaptureImpl: capture,
     computeContentDigestImpl,
     writeCaptureStampImpl,
     logger,
+  };
+
+  const incrementalResult = tryIncrementalCapture({
+    ...shared,
+    filterFilesUnderTargetsImpl,
   });
   if (incrementalResult !== null) return incrementalResult;
 
-  return runFullScopeCapture({
-    crap,
-    coverage,
-    args,
-    getChangedFilesImpl,
-    isCoverageFreshImpl,
-    runCaptureImpl: capture,
-    computeContentDigestImpl,
-    writeCaptureStampImpl,
-    logger,
-  });
+  return runFullScopeCapture(shared);
 }
 
 // cli-opt-out: synchronous main returns an exit code that is forwarded via process.exit(code); runAsCli's async-main signature does not preserve the result code.

package/.agents/scripts/lib/audit-attribution.js

@@ -0,0 +1,112 @@
+/**
+ * audit-attribution.js — decide whose defect a red advisory check is.
+ *
+ * `npm audit` reports the advisories present in a dependency tree; it says
+ * nothing about who introduced them. Advisories are published against
+ * packages that are ALREADY installed, so `main` goes red between pull
+ * requests without anybody's diff causing it, and the first PR opened
+ * afterwards becomes the discovery mechanism — its author debugging a
+ * supply-chain advisory from inside a failing log that has nothing to do
+ * with their change.
+ *
+ * The nightly sweep (`.github/workflows/dependency-audit-cron.yml`) shrinks
+ * how often that happens; it cannot make the failure legible when it does.
+ * An advisory published after one night's sweep and before the next lands on
+ * whoever opens a PR in between. This module supplies the missing sentence:
+ * the same audit, evaluated against the pull request's merge base.
+ *
+ * It buys legibility, never permission — see `attributionExitCode`.
+ */
+
+// The verdict vocabulary. Only `UNKNOWN` is exported: the CLI branches on it
+// to decide whether to audit the base at all, while the other two are read by
+// callers out of the rendered report rather than compared as symbols. Their
+// STRING values are the contract — they appear verbatim in the CI log — so
+// the tests assert those literals rather than re-importing the constants,
+// which would let a rename silently change what an operator reads.
+/** The pull request's own diff introduced the advisory. */
+const INTRODUCED = 'introduced-by-this-diff';
+/** The merge base carries it too; the diff is innocent. */
+const PRE_EXISTING = 'pre-existing';
+/** The probe could not reach a verdict. Never an accusation. */
+export const UNKNOWN = 'unknown';
+
+/**
+ * Decide the verdict from the two audit outcomes.
+ *
+ * Pure — the caller owns running the audits. `baseAudit` is `null` when the
+ * base could not be audited at all, which is the `unknown` path: an
+ * attribution mechanism must never guess, because the guess it would make
+ * (`introduced-by-this-diff`) is an accusation against the author reading it.
+ *
+ * @param {{ headFailed: boolean, baseAudit: { failed: boolean } | null }} input
+ * @returns {string} one of INTRODUCED / PRE_EXISTING / UNKNOWN
+ */
+export function deriveVerdict({ headFailed, baseAudit }) {
+  if (!headFailed) return UNKNOWN;
+  if (!baseAudit || typeof baseAudit.failed !== 'boolean') return UNKNOWN;
+  return baseAudit.failed ? PRE_EXISTING : INTRODUCED;
+}
+
+/**
+ * The exit code a verdict earns.
+ *
+ * **Both real verdicts fail.** The advisory is genuine either way: a check
+ * that passed on `pre-existing` would let advisories accumulate on `main`
+ * unnoticed, which is the exact failure the nightly sweep exists to prevent.
+ * Attribution changes what the log says, never whether the branch may land.
+ *
+ * `unknown` exits 0 — the probe degraded, and the required `npm audit` step
+ * has already failed on its own account. A reporter that can turn a red into
+ * a second, unrelated red is worse than no reporter.
+ *
+ * @param {string} verdict
+ * @returns {number}
+ */
+export function attributionExitCode(verdict) {
+  return verdict === UNKNOWN ? 0 : 1;
+}
+
+/**
+ * Render the operator-facing report for a verdict.
+ *
+ * `trackingIssue` is the open `meta::dependency-advisory` issue number when
+ * the nightly sweep has already filed one, or `null`. Naming it is the point
+ * of the `pre-existing` branch: it turns "why is my unrelated PR red" into a
+ * link to the issue that already owns the fix.
+ *
+ * @param {{ verdict: string, baseRef?: string, trackingIssue?: number|null, reason?: string|null }} input
+ * @returns {string[]} lines, in emission order
+ */
+export function renderAttribution({
+  verdict,
+  baseRef = null,
+  trackingIssue = null,
+  reason = null,
+}) {
+  const at = baseRef ? ` (merge base ${baseRef})` : '';
+  if (verdict === PRE_EXISTING) {
+    const lines = [
+      `::warning::Advisory attribution: PRE-EXISTING${at}. The same high-severity advisory is already present on the merge base, so this pull request's diff did not introduce it.`,
+      'This check still fails, and deliberately: the advisory is real, and letting it pass here would let advisories accumulate on `main` unnoticed.',
+      "Fix it as a standalone `fix(deps)` PR against `main` rather than spending this Story's scope on it. Check the `overrides` block in package.json first — a pinned floor one patch below the patched release is the usual cause.",
+    ];
+    if (trackingIssue != null) {
+      lines.splice(
+        1,
+        0,
+        `The nightly sweep already filed the tracking issue: #${trackingIssue}.`,
+      );
+    }
+    return lines;
+  }
+  if (verdict === INTRODUCED) {
+    return [
+      `::error::Advisory attribution: INTRODUCED BY THIS DIFF${at}. The merge base audits clean at the high-severity threshold, so a dependency change on this branch brought the advisory in.`,
+      "Read the advisory's own version range before accepting a fix: `npm audit fix --force` often proposes a needless semver-major when the parent package's declared range already admits a patched version.",
+    ];
+  }
+  return [
+    `::warning::Advisory attribution: UNKNOWN${at}${reason ? ` — ${reason}` : ''}. The audit result above stands on its own; this probe adds nothing to it.`,
+  ];
+}