mandrel 2.30.0 → 2.32.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-02T11:35:53.522Z",
+  "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",
@@ -148,7 +138,7 @@
       "category": "qa",
       "path": ".agents/skills/stack/qa/playwright/SKILL.md",
       "description": "Robust E2E browser testing with Playwright. Use when writing browser-driven tests — leverage auto-waiting (no `waitForTimeout`), prefer user-visible locators (`getByRole`, `getByText`, `getByLabel`) over CSS/XPath, reuse `storageState` for auth, and enable trace-on-first-retry for CI debugging.",
-      "policyCapsuleBullets": 7,
+      "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": "playwright"
     },

package/.agents/skills/stack/qa/playwright/SKILL.md

@@ -19,3 +19,51 @@ vendor: playwright
 - Write tests independent of one another so they run in parallel; clean up shared state in fixtures, not afterwards.
 - Enable `trace: 'on-first-retry'` (or `'retain-on-failure'`) so CI failures are debuggable in the Trace Viewer.
 - Use a unique data set per test run, or tear down state explicitly, to prevent cross-test contamination.
+- Never let Playwright own the lifetime of a dev server it did not start: boot the server out-of-band, point the suite at the running origin, and set `reuseExistingServer` so `webServer` only probes readiness.
+
+## Running a `webServer`-backed suite outside CI
+
+Playwright's `webServer` block **watches the process it spawned**. That
+assumption holds for a dev server that stays in the foreground, and breaks for
+any manager that daemonizes one — the foreground process exits `0` while the
+server keeps serving, Playwright reads the exit as a crash, and the run aborts
+before a single test executes:
+
+```text
+Process from config.webServer exited early
+```
+
+Read that line as a **lifetime-ownership mismatch, not a flake**. It reproduces
+on every invocation, clean tree or not, and no amount of retrying, tree-cleaning
+or timeout-raising changes it. Agent sandboxes and IDE harnesses commonly manage
+dev servers this way (`Dev server already running at … (pid N)`), so an agent
+meets this far more often than a developer does.
+
+### Attach, don't boot
+
+Invert the ownership instead of fighting it — the manager owns the process,
+Playwright owns only the probe:
+
+1. **Boot the server out-of-band** through whatever manages it, and confirm it
+   is serving. Its lifetime is now the manager's concern, not the runner's.
+2. **Point the suite at the already-running origin** — set the config's
+   `baseURL` (or the `webServer.url` the block probes) to that origin, via the
+   project's own environment seam rather than an edit to committed config.
+3. **Set `reuseExistingServer: true`** so Playwright probes the URL, finds it
+   live, and never spawns or supervises a process of its own.
+
+This is the same convention the QA harness already encodes as
+`qa.environments[].baseUrl`: attach to a running origin, never boot one. A suite
+run this way exercises identical browser behavior — only the process supervision
+differs.
+
+### When no attachable origin exists
+
+Some apps genuinely cannot be reached this way — the server is unreachable from
+the sandbox, or the suite depends on a build step the sandbox cannot run. Do
+**not** burn a timebox rediscovering that. Record the observed signature, state
+which of the three steps above failed, and escalate on the first encounter:
+that evidence is exactly what the `unreproducible-tier` verdict in
+[`ci-remediation.md`](../../../../rules/ci-remediation.md) requires, and it is
+the only verdict that lets an unrunnable tier route somewhere other than a dead
+end.

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

@@ -227,8 +227,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

@@ -118,7 +118,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) —

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

@@ -139,19 +139,18 @@ and the `rules/security-baseline.md` MUSTs all run exactly as for a
 full-ceremony Story. The lite route's `preserves` field is the machine-readable
 record of those non-negotiables; there is no lite-specific gate bypass.
 
-**Deliver derives the route from the Story body's shape — and the
-dispatch mode from the run.** Persist stamps a lite cohort's Stories with the
-`route::lite` label as a _human-visible hint only_ (and ledgers the authored
-verdict — recorded reason plus per-Story shape evidence — on the
-`story-plan-state` checkpoint); the label is never the control signal.
-`/deliver` computes the route from the fetched Story body via
-`resolveStoryDispatchMode` (`lib/orchestration/complexity-gate.js`) — the same
-shape taxonomy `deriveChangeLevel` applies to the landed diff at close:
-`changes[]` count, acceptance count, creates-vs-refactors mix, sensitive-path
-classes. A footprint intersecting a sensitive-path class derives `full` —
-sensitivity wins, and the Story keeps its fresh acceptance critic.
-
-That derived route sets ceremony. It does **not** set the dispatch mode,
+**Ceremony comes from the landed diff; the dispatch mode comes from the
+run.** Persist stamps a lite cohort's Stories with the `route::lite` label as a
+_human-visible hint only_ (and ledgers the authored verdict — recorded reason
+plus per-Story shape evidence — on the `story-plan-state` checkpoint); the
+label is never the control signal. Ceremony is resolved from the **derived
+change level** (`deriveChangeLevel` over the computed change set — digest § 3),
+not from a body-shape read: a footprint intersecting a sensitive-path class
+derives `high`, so the Story keeps its fresh acceptance critic. The light path
+is the one caller that reads the authored body's shape, through
+`deriveStoryShape` (`lib/orchestration/complexity-gate.js`).
+
+That derived level sets ceremony. It does **not** set the dispatch mode,
 because `inline` names one indivisible resource — the router's own session —
 and only run topology can say whether it is free: a **single-Story run**
 executes inline, and every Story of a multi-Story run dispatches as a
@@ -200,8 +199,8 @@ critic (the redundant pre-pass buys no measurable quality and roughly
 triples the acceptance-block cost). `acceptance-eval.js` is the
 deterministic **scorer** of that one authored verdict — schema validation,
 round cap, proceed / redraft / block — not an independent additional pass
-over the criteria. The M4-B floor holds: one verdict per cluster, the
-cluster count owned by `acceptance-clusters.js` alone.
+over the criteria. The M4-B floor holds: one verdict per cluster, with the
+cluster count owned by the dispatching caller and never by routing.
 
 **One round = N cluster critics → ONE merged verdict → ONE gate call.** The
 clusters are how a round is _authored_; they are not how it is _scored_.
@@ -279,7 +278,9 @@ floor forces `fresh`). Review depth reads the same derived level via
 `review-depth.js` inside close, so the two decisions cannot disagree.
 
 **Inline-dispatch override.** When the Story dispatches
-`inline` (`resolveStoryDispatchMode` → `inline`, i.e. a single-Story run), run
+`inline` (`resolveStoryDispatchMode` → `inline`, which is exactly a
+single-Story run — the function reads the resolved set size and nothing
+else), run
 every acceptance critic **inline** — do not spawn fresh-context critic
 sub-agents regardless of what the profile would otherwise resolve. The self-eval rigor
 (scoring each `acceptance[]` item against the one computed change set, with
@@ -393,6 +394,16 @@ judgment that help text cannot carry.
   wants the PR left at `agent::closing` for a human land (or a wrapper that
   will invoke `single-story-confirm-merge.js` itself). Reports `pending` —
   the work is not done, nothing is broken, and one named command finishes it.
+- `--override-review-block "<reason>"` — when the Story-scope review's
+  **critical** blocker is one you have read and judged wrong (a false positive,
+  or a finding the ratchet correctly exempts). It is the only sanctioned way
+  past that halt: reach for it instead of merging the PR by hand, because a
+  hand-merge bypasses the gate and records nothing. The reason is mandatory and
+  is written to three places (Story comment, PR comment, a
+  `review-block-overridden` friction signal), and the terminal envelope reports
+  `gates.codeReview: "overridden"` rather than `"passed"`. If you find yourself
+  reaching for it twice for the same shape of finding, the gate is
+  miscalibrated — fix the gate, not the run.
 - `--max-wait-seconds <n>` — from a headless caller with no host
   tool-invocation ceiling, to keep single-block semantics
   without editing the consumer's config.