mandrel 2.31.0 → 2.33.0

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",

package/.agents/workflows/audit-documentation.md

@@ -7,10 +7,10 @@ description: Audit the repository's main documentation for staleness, semantic d
 You are a Staff Engineer & Documentation Steward verifying the repository's prose
 documentation is **up to date and complete**. Prose rots silently: commands get
 renamed, scripts move, workflows change shape, version/topology claims go stale.
-The deterministic gates (`check-doc-links.js`, `check-lifecycle-doc-drift.js`,
-`validate-docs-freshness.js`) catch broken links, generator drift, and
-per-delivery freshness — they cannot tell whether the prose still describes how
-the code actually behaves. That semantic verification is this lens's job. The
+The deterministic gates (`check-doc-links.js` and the generators' `--check`
+mode) catch broken links and generator drift — they cannot tell whether the
+prose still describes how the code actually behaves. That semantic
+verification is this lens's job. The
 shared lens machinery — read-only constraint, scope interpretation, report
 envelope + finding-block skeleton, severity scale, self-cross-check, and
 execution strategy — lives in
@@ -78,7 +78,6 @@ are cheap, exact, and de-duplicate the easy findings:
 
 ```bash
 node .agents/scripts/check-doc-links.js
-node .agents/scripts/check-lifecycle-doc-drift.js
 node .agents/scripts/generate-config-docs.js --check
 node .agents/scripts/generate-lifecycle-docs.js --check
 node .agents/scripts/generate-workflows-doc.js --check
@@ -87,7 +86,7 @@ node .agents/scripts/resolve-doc-tiers.js --json
 
 Fold the results in as findings:
 
-- **Checker failures** (broken links, lifecycle drift) become individual
+- **Checker failures** (broken links, generator drift) become individual
   findings with `Category: Link Integrity` (or `Generator Drift` for the
   lifecycle gate), citing the checker output verbatim.
 - **Generator dirtiness** (any `--check` reporting stale output, including

package/.agents/workflows/audit-to-stories.md

@@ -189,6 +189,32 @@ Labels applied:
   (cross-audit groups carry multiple).
 - `risk::high` — added when any finding in the group is Critical.
 
+### Phase 5c — Wire the cohort's declared ordering (**required**)
+
+Creating the Issues is only the first pass. `groupFindings` detects `edges[]`
+between groups, but at emit time no group has an issue number, so each body
+ships with an empty `depends_on` and the cohort has **no declared ordering
+at all**. Replay the numbers you just opened:
+
+```bash
+node .agents/scripts/audit-to-stories.js --wire-edges \
+  --plan temp/audits/audit-to-stories-plan.json \
+  --ids '{"<groupKey>": <issueNumber>, ...}' \
+  --out temp/audits/audit-to-stories-wired.json
+```
+
+Each entry in the emitted `--json` payload carries its own `groupKey` and
+`dependsOn`, so the map is a lookup, not a reconstruction. The pass re-renders
+every Story that has a resolvable blocker with a canonical
+`---` / `blocked by #N` footer **and** mirrors the same edges as native
+GitHub `blocked_by` relations. An edge whose target was never opened (deduped,
+ledger-suppressed) drops rather than becoming a `blocked by #undefined`.
+
+**Do not skip this.** `/deliver` has no other source for this cohort's order:
+its footprint guard ignores the shared provenance footers, so an unwired cohort
+is genuinely unordered and `/deliver` will co-dispatch Stories the edges say
+must follow one another.
+
 ## Phase 6 — Idempotency (folded into Phase 1 scan)
 
 The `--scan` step routes each group's findings through the shared
@@ -227,8 +253,8 @@ runs FIRST and widens the net across open + closed issues; the exact
 was reworded but whose *location* is unchanged still confirms against the Issue
 that already tracks that location, because the audit filers stamp a
 location-based `audit-semantic-keys` footer alongside the `audit-fingerprints`
-footer. Close-time filings from the
-[`audit-results-graduator`](../scripts/lib/feedback-loop/audit-results-graduator.js)
+footer. Filings from the
+[`retro-proposals-graduator`](../scripts/lib/feedback-loop/retro-proposals-graduator.js)
 carry the same canonical `audit-fingerprints` footer, so a sweep recognizes a
 graduator-filed issue and never re-files it.
 

package/.agents/workflows/helpers/audit-lens-core.md

@@ -229,18 +229,17 @@ which path produced it.
 > stage before synthesising the report. It derives its per-dimension prompts
 > from the *lens* markdown at run time — the lens stays the single source of
 > truth. This is a performance optimization over path 1, **not** a separate
-> contract: strategy selection lives in
-> [`../../scripts/lib/dynamic-workflow/capability.js`](../../scripts/lib/dynamic-workflow/capability.js)
-> (`selectAuditStrategy`), and it is not covered by the No-Shim / hard-cutover
-> rule in [`../../rules/git-conventions.md`](../../rules/git-conventions.md)
-> because there is one report contract and only the execution strategy varies —
-> the same capability-degradation pattern the protocol endorses for live-docs
-> fallback. Force a path for testing with `MANDREL_AUDIT_STRATEGY=sequential`
-> or `MANDREL_AUDIT_STRATEGY=orchestrated`; exercise the real disable signals
-> with `CLAUDE_CODE_DISABLE_WORKFLOWS=1` or `disableWorkflows: true` in
-> `.claude/settings.json`. On the orchestrated path the analysis subagents are
-> granted only read/search tools (`Read`, `Grep`, `Glob`) — the single write is
-> the final report artifact.
+> contract, and it is not covered by the No-Shim / hard-cutover rule in
+> [`../../rules/git-conventions.md`](../../rules/git-conventions.md) because
+> there is one report contract and only the execution strategy varies — the
+> same capability-degradation pattern the protocol endorses for live-docs
+> fallback. **The host owns the choice.** Mandrel ships no in-repo strategy
+> selector and no force-override env var: Claude Code launches the saved
+> workflow when it can, and you get path 1 or 2 above when it cannot.
+> Suppress the orchestrated path with `CLAUDE_CODE_DISABLE_WORKFLOWS=1`
+> or `disableWorkflows: true` in `.claude/settings.json`. On the orchestrated
+> path the analysis subagents are granted only read/search tools (`Read`,
+> `Grep`, `Glob`) — the single write is the final report artifact.
 
 ## Parallel tooling {#parallel-tooling}
 

package/.agents/workflows/helpers/code-quality-guardrails.md

@@ -95,17 +95,18 @@ suppress the noise.
 
 ## When a number changes
 
-Update three places **in the same commit**:
-
-1. `delivery.quality.codingGuardrails.<key>` in
-   [`agentrc-reference.json`](../../docs/agentrc-reference.json).
-2. The matching schema bound in
-   [`schemas/agentrc.schema.json`](../../schemas/agentrc.schema.json) and the
-   AJV mirror in
-   [`scripts/lib/config-settings-schema.js`](../../scripts/lib/config-settings-schema.js).
-3. The threshold cell or sentence in this helper.
-
-The drift test (`tests/config-schema-mirror-drift.test.js`) catches schema
-divergence between the JSON mirror and the AJV runtime; the helper-prose
-drift is caught by `audit-clean-code` and `agent-protocol` linking back here
-rather than restating the numbers.
+Update two places **in the same commit**:
+
+1. `CODING_GUARDRAILS_DEFAULTS` in
+   [`scripts/lib/config/quality.js`](../../scripts/lib/config/quality.js).
+   The schema literal in
+   [`config-settings-schema-quality.js`](../../scripts/lib/config-settings-schema-quality.js)
+   imports it, and `npm run docs:gen` propagates the number into
+   [`agentrc-reference.json`](../../docs/agentrc-reference.json), the shipped
+   JSON-Schema mirror, and the `configuration.md` key table.
+2. The threshold cell or sentence in this helper.
+
+The generator-fidelity test (`tests/config-schema-mirror-drift.test.js`)
+catches a stale generated artifact; the helper-prose drift is caught by
+`audit-clean-code` and `agent-protocol` linking back here rather than
+restating the numbers.

package/.agents/workflows/helpers/code-review.md

@@ -293,14 +293,9 @@ For every finding, provide:
 
 Findings that Step 4.5 remediated on `[HEAD_REF]` MUST be rendered under a
 dedicated **`## Fixed on-branch`** heading, **not** in the severity groups
-above. This is the contract seam that keeps remediated findings from
-spawning ghost follow-up issues: the
-[audit-results graduator](../../scripts/lib/feedback-loop/audit-results-graduator.js)
-(the sole canonical reader of the unified comment)
-skips every entry inside this section (both because a fixed entry is
-rendered with a **✅ prefix** — so it carries no leading severity emoji the
-parser would match — and because the parser has an explicit
-Fixed-on-branch section guard).
+above. This keeps a remediated finding legible as remediated to every reader
+of the unified comment — human or downstream — rather than reading as an
+outstanding severity-grouped finding.
 
 Render each fixed finding as a `✅`-prefixed line naming its original
 severity, the file path in backticks, and the remediating commit SHA, e.g.:

package/.agents/workflows/helpers/deliver-reference.md

@@ -94,7 +94,7 @@ probe logs a warning and leans on init's lease refusal alone.
 **Overlapping footprints are reserved across beats, not just within one.** A
 Story sharing a **concrete** path with a still-implementing Story is withheld
 and named in `inFlightReservation: { available, withheld: [{ id, blockedBy,
-reason }], note }`, where `reason` is `in-flight-earlier-beat` or
+reason, source, paths }], note }`, where `reason` is `in-flight-earlier-beat` or
 `foreign-lease`. Like `foreignHeld` this is neither a failure nor a wedge — the
 Story re-admits automatically once its blocker leaves the in-flight set — and
 it exists so an unfilled slot is explained rather than mysterious. A **glob**
@@ -103,6 +103,33 @@ across beats; it still serializes its own beat. Reservation needs the in-flight
 Stories' footprints, so it is a `--probe-live` capability: under `--dag` the
 report is `available: false` and selection de-conflicts within the beat only.
 
+**Beat-local skips are reported too**, in `footprintGuard: { mode, withheld,
+advisory, note }`. They used to be an unreported skip, so a Story simply
+vanished from `ready[]` and an unfilled slot read exactly like a cap that was
+never reached. Every entry in **either** report carries the colliding `paths`
+and a `source` tag:
+
+- `declared-overlap` — both Stories' `changes[]` named the path (or a declared
+  glob). Intended serialization; two Stories rewriting the same generated
+  baseline must not co-dispatch.
+- `scraped-overlap` — only the text evidence produced it. Real signal — a
+  declaration is only a lower bound — but the class where a false positive is
+  possible.
+
+**The evidence scrape excludes exactly three token sources**, each structurally
+incapable of naming an edit target: `audit-fingerprints` /
+`audit-semantic-keys` provenance footers, paths under `project.paths.tempRoot`,
+and markdown-link URL interiors. Nothing else is stripped — a
+`<!-- DECOMPOSITION -->` block's paths are genuine intent
+([`instructions.md` § 7](../../instructions.md)) and still count.
+
+**`delivery.deliverRunner.footprintGuard`** selects what a collision does:
+
+| Mode | Effect |
+| --- | --- |
+| `enforce` (default) | A collision withholds the Story. Keep this unless you have a reason — the guard encodes delivery-time-only knowledge (open implementation windows, foreign leases, ground moved since planning) no `depends_on` edge can carry. |
+| `advisory` | Collisions are still **detected** and listed in `footprintGuard.advisory`, but never withhold; dispatch follows the declared `depends_on` edges alone. A throughput trade for a run whose ordering is fully declared. |
+
 ## Dispatch mechanics (role-scoped by default)
 
 **A single-Story run executes inline.** Sub-agent isolation is
@@ -118,7 +145,8 @@ engine runs, never what runs — gates, PR, and terminal envelope are identical.
 **Read the mode; never infer it from shape.** Before spawning
 anything, read the Story's `dispatchMode` from the resolver envelope
 (`stories[].dispatchMode`, produced by `resolveStoryDispatchMode` in
-`lib/orchestration/complexity-gate.js`). A Story with `dispatchMode: "inline"`
+`lib/orchestration/complexity-gate.js`, which decides on the resolved set size
+alone — it does not read the Story body). A Story with `dispatchMode: "inline"`
 executes [`deliver-story.md`](deliver-story.md) **inline in this session** — no
 `story-worker` sub-agent boot and no fresh acceptance-critic sub-agents
 (sub-agent boots are the dominant deliver-phase token cost at trivial scope) —