mandrel 2.56.0 → 2.58.0

package/.agents/scripts/check-context-budget.js

@@ -47,15 +47,17 @@
  * Ratchet semantics (mirroring the sibling ratchets):
  *   - A gated tier grows beyond `baseline.tiers.<tier>.totalBytes +
  *     baseline.toleranceBytes` → exit 1, naming the tier and its delta.
- *   - A gated tier shrinks below its baseline total → exit 1 (Story #4872).
- *     A ratchet that only tightens in one direction lets every measured
- *     improvement evaporate: the recorded total keeps promising headroom the
- *     tree no longer spends, so the next growth is absorbed by stale slack
- *     instead of being reported. Shrinkage is therefore **actionable** —
- *     refresh the baseline down and the gain is locked in. Unlike growth this
- *     is deliberately **zero-tolerance**: `toleranceBytes` exists to keep a
- *     trivial addition from churning the file, and applying it downward would
- *     silently discard every sub-tolerance gain.
+ *   - A gated tier shrinks below its baseline total → **exit 0**, reported as
+ *     an informational `-` line (Story #5313). This deliberately reverses
+ *     Story #4872's "shrink fails" rule: that rule made every trim a red gate
+ *     whose only remedy was a hand-run `--update`, so the gain was paid for
+ *     twice. The concern it answered — a stale total silently absorbing the
+ *     next growth — is now met by the close's write-back seam
+ *     (`story-close/context-budget-writeback.js`), which rewrites the lower
+ *     total into `baselines/context-budget.json` on the Story branch so the
+ *     gain locks in without a failing gate. Shrinkage stays zero-tolerance
+ *     in the *report* (every byte under the total is listed) so a sub-
+ *     tolerance gain is never discarded by the write-back either.
  *   - A recorded row naming a path the measured tier no longer contains →
  *     exit 1. The row describes a file that has been deleted or de-listed, so
  *     the bytes it contributes to the recorded total are fiction.
@@ -341,9 +343,9 @@ function absentRows(tier, files, baseTier) {
 /**
  * Pure diff: compare the current tier map against the committed baseline. A
  * gated tier with no current files is skipped; a tier absent from the baseline
- * is skipped. `grown`, `shrunk` and `absent` entries all fail the gate — see
- * the ratchet semantics in the module header for why shrinkage is actionable
- * rather than informational (Story #4872).
+ * is skipped. `grown` and `absent` entries fail the gate; `shrunk` entries are
+ * reported and written back by the close (Story #5313) — see the ratchet
+ * semantics in the module header.
  *
  * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
  * @param {{ toleranceBytes?: number, tiers?: Record<string, { totalBytes: number }> }} baseline
@@ -384,9 +386,9 @@ export function diffBudget(tierMap, baseline) {
         delta: current - baselineBytes,
       });
     } else if (current < baselineBytes) {
-      // Deliberately zero-tolerance: `tolerance` guards against churn from a
-      // trivial *addition*; mirroring it downward would discard every gain
-      // smaller than the tolerance, which is the leak this branch closes.
+      // Deliberately zero-tolerance in the report: `tolerance` guards against
+      // churn from a trivial *addition*; mirroring it downward would hide a
+      // gain from the write-back that locks it in (Story #5313).
       shrunk.push({
         tier,
         current,
@@ -400,26 +402,24 @@ export function diffBudget(tierMap, baseline) {
 }
 
 /**
- * Count the drift entries that fail the gate. Every direction is actionable
- * (Story #4872), so this is the one place the failure set is defined and both
- * the summary tag and the exit code read it.
+ * Count the drift entries that fail the gate: growth past tolerance and a
+ * recorded row the tree no longer backs. Shrinkage is not in the set (Story
+ * #5313 — the close writes it back instead). This is the one place the
+ * failure set is defined and both the summary tag and the exit code read it.
  *
  * @param {ReturnType<typeof diffBudget>} diff
  * @returns {number}
  */
 export function budgetFailureCount(diff) {
-  return (
-    (diff?.grown?.length ?? 0) +
-    (diff?.shrunk?.length ?? 0) +
-    (diff?.absent?.length ?? 0)
-  );
+  return (diff?.grown?.length ?? 0) + (diff?.absent?.length ?? 0);
 }
 
 /**
  * Render the human-readable diff. `+` lines are tiers that grew beyond
- * tolerance; `-` lines are tiers that shrank below their recorded total or
- * rows naming a path the tree no longer carries. All three fail the gate. A
- * one-line summary always follows.
+ * tolerance; `-` lines are tiers that shrank below their recorded total
+ * (informational — the close writes the lower total back) or rows naming a
+ * path the tree no longer carries (a gate failure). A one-line summary
+ * always follows.
  *
  * @param {ReturnType<typeof diffBudget>} diff
  * @returns {string}
@@ -433,7 +433,7 @@ export function renderDiff(diff) {
   }
   for (const s of diff.shrunk) {
     lines.push(
-      `- ${s.tier}: ${s.current} bytes is under the recorded ${s.baseline} (delta -${s.delta}) — the ratchet is holding slack the tree no longer spends; refresh baselines/context-budget.json`,
+      `- ${s.tier}: ${s.current} bytes is under the recorded ${s.baseline} (delta -${s.delta}) — the close writes the lower total back to baselines/context-budget.json when this branch lands`,
     );
   }
   for (const a of diff.absent ?? []) {
@@ -479,7 +479,7 @@ export function renderReachable(tierMap, baseline) {
  *   stderr?: { write: (s: string) => void },
  * }} [opts]
  * @returns {Promise<number>} 0 = clean / within tolerance / shrink-only / no-op;
- *   1 = a gated tier grew beyond tolerance
+ *   1 = a gated tier grew beyond tolerance or a recorded row is unbacked
  */
 /**
  * Write a fresh budget, preserving the recorded tolerance so `--update` never
@@ -621,11 +621,6 @@ function renderFailureDiagnostics({ report, stderr }) {
       `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
     );
   }
-  if (diff.shrunk.length > 0) {
-    stderr.write(
-      `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
-    );
-  }
   if (diff.absent.length > 0) {
     stderr.write(
       `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,

package/.agents/scripts/check-cyclomatic.js

@@ -1,6 +1,7 @@
 /**
  * CLI: ratchet on cyclomatic complexity against
- * `delivery.quality.codingGuardrails.cyclomaticMustFix` (Story #4923).
+ * the fixed cyclomatic ceiling of 12 (Story #4923; the `cyclomaticMustFix`
+ * config key was retired in Story #5313).
  *
  * The must-fix ceiling was documented as blocking (`code-quality-guardrails.md`
  * promises "the close-validation chain refuses the merge") while being read by
@@ -158,7 +159,7 @@ function warnAboutBaseline({ baseline, mustFix, baselinePath, stderr }) {
   }
   if (typeof baseline.ceiling === 'number' && baseline.ceiling !== mustFix) {
     stderr.write(
-      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the configured cyclomaticMustFix is c=${mustFix} — re-run with --update\n`,
+      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the enforced ceiling is c=${mustFix} — re-run with --update\n`,
     );
   }
 }
@@ -265,7 +266,7 @@ runAsCli(import.meta.url, main, {
     invocation:
       'node .agents/scripts/check-cyclomatic.js [--baseline <path>] [--update] [--json]',
     summary:
-      'Ratchet on cyclomatic complexity: fail when a file gains a function above `delivery.quality.codingGuardrails.cyclomaticMustFix`, or when its worst function gets worse than the recorded baseline.',
+      'Ratchet on cyclomatic complexity: fail when a file gains a function above the fixed ceiling of 12, or when its worst function gets worse than the recorded baseline.',
     flags: [
       [
         '--baseline <path>',

package/.agents/scripts/deliver-light.js

@@ -22,12 +22,12 @@
  *
  *   - **gate** (default) — judge a prompt's predicted footprint. On
  *     `proceed-light` it authors the receipt Story (via the plan-persist
- *     `createStoryIssues` surface) and prints the init/close hand-off. On
- *     over-scope it prints `ask-operator` (attended) or emits an `escalated`
- *     terminal envelope (`--yes`), never landing silently. An attended
- *     `ask-operator` is answerable **either** way: `--operator-proceed-light`
- *     records the operator's proceed answer (Story #4815), which the gate
- *     applies only to a coarse size prediction and never to a risk rule.
+ *     `createStoryIssues` surface) and prints the init/close hand-off,
+ *     carrying any predicted-shape `warnings[]` (Story #5313: an over-ceiling
+ *     prediction warns, it no longer stops). An un-ledgered verdict or an
+ *     un-waivable risk rule emits an `escalated` terminal envelope, never
+ *     landing silently. The former attended stop-and-ask outcome and the
+ *     flag that answered it went with the gate they answered.
  *   - **backstop** (`--backstop --story <id>`) — re-check the ACTUAL diff of
  *     the Story branch after implementation; exit non-zero when it exceeds the
  *     light ceilings, so an over-scope diff is blocked rather than landed.
@@ -52,8 +52,7 @@
  *   node .agents/scripts/deliver-light.js --backstop --story 4741
  *
  * Exit codes: 0 ok (proceed / clean backstop), 1 usage error, 2 the gate did
- * not proceed light (ask-operator, or an `escalated` terminal), 3 the diff
- * backstop blocked.
+ * not proceed light (an `escalated` terminal), 3 the diff backstop blocked.
  */
 
 import { parseArgs } from 'node:util';
@@ -84,15 +83,17 @@ Usage:
   deliver-light.js --prompt <text> [--creates csv] [--refactors csv]
                    [--acceptance n] [--kinds csv] [--magnitude m]
                    [--uncertainty u] [--route lite|full] [--reason <text>]
-                   [--amends '#id'] [--operator-proceed-light <text>] [--yes]
+                   [--amends '#id'] [--yes]
   deliver-light.js --backstop --story <id>
 
 The thin /deliver-light entry point: suitability gate → inline receipt Story →
 the same single-story-init.js / single-story-close.js engine /mandrel-deliver uses.
 
 The gate judges EFFORT and RISK, not artifact counts: N instances of one
-mechanical edit is one kind at N sites. It rejects only clearly-epic work; the
---backstop pass enforces size against the actual diff.
+mechanical edit is one kind at N sites. A predicted shape past a light ceiling
+is a WARNING on the envelope, not a refusal (Story #5313); only an un-ledgered
+verdict or an un-waivable risk rule (sensitive path, migration span) escalates.
+The --backstop pass enforces size against the actual diff.
 
 Gate options:
   --prompt <text>    Operator prompt describing the change. Required for the gate.
@@ -108,17 +109,9 @@ Gate options:
   --route <r>        Ledgered model verdict route: lite | full.
   --reason <text>    Recorded reason for a lite verdict (required for lite).
   --amends <#id>     Mark this as an amendment of an existing issue.
-  --operator-proceed-light <text>
-                     Record the operator's "proceed light" answer to an
-                     ask-operator gate, with their reason. Attended-only:
-                     refused with --yes. Waives a coarse SIZE prediction
-                     (change kinds, magnitude, uncertainty, deployable span)
-                     only — sensitivity, migration span, and an unknown
-                     footprint stay non-negotiable, the ledgered --route lite
-                     verdict is still required, and the --backstop pass still
-                     bounds the actual diff. Recorded in the receipt Story.
-  --yes              Unattended: over-scope emits an escalated terminal
-                     envelope and ENDS the session (no prompt, no fallback).
+  --yes              Unattended marker. Escalation is terminal either way;
+                     the flag is accepted so unattended callers keep their
+                     invocation shape.
 
 Backstop options:
   --backstop         Re-check the ACTUAL diff after implementation. Bounds the
@@ -132,9 +125,6 @@ Backstop options:
   --help             Show this help.
 `;
 
-/** Exit code when the gate did not resolve to proceed-light. */
-const EXIT_NOT_PROCEED = 2;
-
 /**
  * Split a comma-separated path list into trimmed, non-empty entries.
  *
@@ -196,14 +186,10 @@ export function synthesizeAcceptance(count) {
  *   uncertainty?: string,
  *   route?: string,
  *   reason?: string,
- *   operatorProceedLight?: string,
- *   yes?: boolean,
  *   injectedRules?: object,
  * }} args `kinds` / `magnitude` / `uncertainty` are the declared effort-and-risk
  *   axes the gate judges (Story #4764); omitting them declares no signal, not a
- *   small one — an unrecognized bucket fails closed. `operatorProceedLight`
- *   carries the operator's recorded answer to an `ask-operator` outcome
- *   (Story #4815) and is adjudicated inside the gate, never applied here.
+ *   small one — an unrecognized bucket is reported as a warning (Story #5313).
  * @returns {{ action: string, suitability: object, outcome: object }}
  */
 export function runLightGate({
@@ -215,8 +201,6 @@ export function runLightGate({
   uncertainty,
   route,
   reason,
-  operatorProceedLight,
-  yes = false,
   injectedRules,
 } = {}) {
   const predictedChanges = buildPredictedChanges({ creates, refactors });
@@ -229,11 +213,7 @@ export function runLightGate({
     verdict: { route, reason },
     injectedRules,
   });
-  const outcome = resolveLightGateOutcome({
-    suitability,
-    yes,
-    operatorOverride: operatorProceedLight,
-  });
+  const outcome = resolveLightGateOutcome({ suitability });
   return { action: outcome.action, suitability, outcome };
 }
 
@@ -246,11 +226,9 @@ export function runLightGate({
  *   prompt: string,
  *   changedFiles?: string[],
  *   amends?: string|number|null,
- *   override?: object|null,
  *   assembleFn?: typeof assemblePlanStories,
  *   createFn?: typeof createStoryIssues,
- * }} args `override` is the applied operator scope override (Story #4815),
- *   recorded in the receipt body so the decision is auditable from the ticket.
+ * }} args
  * @returns {Promise<{ storyId: number, url: string|undefined, title: string }>}
  */
 export async function createLightReceipt({
@@ -258,7 +236,6 @@ export async function createLightReceipt({
   prompt,
   changedFiles = [],
   amends = null,
-  override = null,
   assembleFn = assemblePlanStories,
   createFn = createStoryIssues,
 } = {}) {
@@ -266,7 +243,6 @@ export async function createLightReceipt({
     prompt,
     changedFiles,
     amends,
-    override,
   });
   const { stories } = assembleFn([ticket]);
   const { created } = await createFn({ provider, stories });
@@ -294,19 +270,6 @@ export function buildNextCommands(storyId) {
   };
 }
 
-/**
- * Was a non-blank `--operator-proceed-light` supplied? The gate core decides
- * whether it *applies*; this only asks whether the operator typed one, so the
- * attended-only refusal can fire before any adjudication.
- *
- * @param {{ 'operator-proceed-light'?: unknown }} values Parsed CLI values.
- * @returns {boolean}
- */
-export function hasOperatorOverride(values = {}) {
-  const raw = values['operator-proceed-light'];
-  return typeof raw === 'string' && raw.trim() !== '';
-}
-
 /**
  * Emit a JSON envelope on stdout (the machine surface) so a headless caller can
  * branch on it. Human-readable log lines stay on stderr.
@@ -355,12 +318,12 @@ async function runBackstopMode(values, deps = {}) {
  *     envelope** and stops (Story #4746). It is placed **first**, above every
  *     creation call site, so "nothing was started" is a property of the
  *     control flow rather than a claim the envelope makes about itself.
- *   - **`ask-operator`** is unchanged: the plain gate envelope and exit 2. It
- *     is not terminal — the operator has a choice to make, and manufacturing a
- *     terminal for it would end a session that is supposed to be waiting. The
- *     operator's proceed answer comes back as `--operator-proceed-light`.
  *   - **`proceed-light`** authors the receipt Story and prints the hand-off,
- *     carrying any applied `override` into both the receipt and the envelope.
+ *     carrying the predicted-shape `warnings[]` (Story #5313) on the envelope
+ *     and on stderr, so an over-ceiling prediction is stated rather than
+ *     silently waved through. The former attended stop-and-ask outcome is
+ *     gone: the gate never had a question a human could answer that the diff
+ *     backstop does not answer better.
  *
  * The injectable seams exist so the no-side-effect guarantee is testable
  * without a network: a test asserts the escalate path never reaches them.
@@ -390,17 +353,6 @@ export async function runGateMode(values, deps = {}) {
     throw new Error('[deliver-light] --prompt <text> is required for the gate');
   }
 
-  // Attended-only, enforced loudly (Story #4815). Silently ignoring the flag
-  // under --yes would let an automated caller pass it as a hopeful no-op and
-  // read the resulting escalation as a bug; a usage error says which of the
-  // two the caller has to give up.
-  if (values.yes === true && hasOperatorOverride(values)) {
-    process.stderr.write(HELP);
-    throw new Error(
-      '[deliver-light] --operator-proceed-light is attended-only and cannot be combined with --yes: an unattended run has no operator whose answer this is, and over-scope must fail closed to /mandrel-plan',
-    );
-  }
-
   const gate = runLightGate({
     creates: parseCsvPaths(values.creates),
     refactors: parseCsvPaths(values.refactors),
@@ -412,35 +364,24 @@ export async function runGateMode(values, deps = {}) {
     uncertainty: values.uncertainty,
     route: values.route,
     reason: values.reason,
-    operatorProceedLight: values['operator-proceed-light'],
-    yes: values.yes === true,
   });
 
-  if (gate.action === 'escalate-plan') {
+  if (gate.action !== 'proceed-light') {
     const envelope = buildEscalationTerminal({
       prompt: String(values.prompt),
       reasons: gate.outcome.reasons,
     });
     emitTerminalFn(envelope);
+    // The refusal is still telemetered (Story #4856): the ceilings stay
+    // recalibratable from evidence even now that only risk rules refuse.
+    await recordRefusalFn({ gate, amends: values.amends });
     Logger.warn(
       `[deliver-light] ESCALATED to /mandrel-plan — this session ENDS here; run ${envelope.nextCommand} in a FRESH session: ${gate.outcome.reasons.join('; ')}`,
     );
     return exitCodeForTerminal(envelope);
   }
 
-  if (gate.action !== 'proceed-light') {
-    emitFn(
-      { mode: 'gate', action: gate.action, outcome: gate.outcome },
-      values.pretty,
-    );
-    await recordRefusalFn({ gate, amends: values.amends });
-    Logger.warn(
-      `[deliver-light] gate did not proceed light (${gate.action}): ${gate.outcome.reasons.join('; ')}`,
-    );
-    return EXIT_NOT_PROCEED;
-  }
-
-  const override = gate.outcome.override ?? null;
+  const warnings = gate.outcome.warnings ?? [];
   const provider = createProviderFn(resolveConfigFn());
   const receipt = await createReceiptFn({
     provider,
@@ -450,7 +391,6 @@ export async function runGateMode(values, deps = {}) {
       ...parseCsvPaths(values.refactors),
     ],
     amends: values.amends ?? null,
-    override,
   });
   emitFn(
     {
@@ -458,16 +398,14 @@ export async function runGateMode(values, deps = {}) {
       action: 'proceed-light',
       storyId: receipt.storyId,
       url: receipt.url,
-      ...(override === null ? {} : { override }),
+      warnings,
       nextCommands: buildNextCommands(receipt.storyId),
       outcome: gate.outcome,
     },
     values.pretty,
   );
-  if (override !== null) {
-    Logger.warn(
-      `[deliver-light] operator scope override recorded on Story #${receipt.storyId}: waived "${override.overriddenCode}" — ${override.recordedReason}`,
-    );
+  for (const warning of warnings) {
+    Logger.warn(`[deliver-light] ⚠ ${warning}`);
   }
   Logger.info(
     `[deliver-light] receipt Story #${receipt.storyId} created — hand off to single-story-init.js.`,
@@ -488,7 +426,6 @@ async function main() {
       route: { type: 'string' },
       reason: { type: 'string' },
       amends: { type: 'string' },
-      'operator-proceed-light': { type: 'string' },
       yes: { type: 'boolean', default: false },
       backstop: { type: 'boolean', default: false },
       story: { type: 'string' },

package/.agents/scripts/evidence-gate.js

@@ -269,7 +269,7 @@ runAsCli(import.meta.url, main, {
   source: 'evidence-gate',
   usage: {
     invocation:
-      'node .agents/scripts/evidence-gate.js --scope-id <id> --gate <name> [--standalone] [--no-evidence] [--cwd <path>] [--worktree <path>]',
+      'node .agents/scripts/evidence-gate.js --scope-id <id> --gate <name> [--standalone] [--no-evidence] [--cwd <path>] [--worktree <path>] -- <cmd> [args...]',
     summary:
       'Run one named gate, reusing a prior evidence stamp for the same HEAD instead of re-running it.',
     flags: [
@@ -282,6 +282,22 @@ runAsCli(import.meta.url, main, {
       ],
       ['--cwd <path>', 'Repository root (default: project root).'],
       ['--worktree <path>', 'Worktree the gate runs in.'],
+      [
+        '-- <cmd> [args...]',
+        'Required. The command this gate runs, passed through verbatim (never via a shell).',
+      ],
+    ],
+    notes: [
+      [
+        'Everything after the first `--` is the gate. The stamp therefore describes',
+        'what actually ran, whatever that is — which is how a project on any test',
+        'runner earns the close `test` credit:',
+        '',
+        '  node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 \\',
+        '    --gate lint --worktree .worktrees/story-4250 -- npm run lint',
+        '  node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 \\',
+        '    --gate test --worktree .worktrees/story-4250 -- npm test',
+      ].join('\n'),
     ],
   },
 });

package/.agents/scripts/lib/audit-suite/checklist-threading.js

@@ -41,16 +41,29 @@ import path from 'node:path';
 import { AUDIT_LENSES } from '../audit-to-stories/audit-lenses.js';
 import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
-import { estimateTokens } from '../orchestration/spec-spill.js';
 import {
   changeSetLacksSiblingTest,
   matchesAnyFilePattern,
   resolveLensTier,
 } from './selector.js';
 
+/**
+ * Rough token estimate: ~4 characters per token. Deliberately cheap and
+ * deterministic — this budget is the one surviving ceiling that speaks in
+ * tokens (Story #5312 deleted the plan-time sizing ceilings that shared the
+ * estimator), so the approximation matters far less than the payload and
+ * the cap agreeing on one number.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function estimateTokens(text) {
+  return Math.ceil(String(text ?? '').length / 4);
+}
+
 /**
  * Hard cap on the assembled checklist payload, in the ≈4-char/token estimate
- * shared with the rest of the hydrator ({@link estimateTokens}). Generous
+ * above ({@link estimateTokens}). Generous
  * relative to the real checklist sizes (each distilled lens checklist is
  * ~130–190 tokens, and at most the seven local lenses can match), so a normal
  * Story is never truncated — the cap is a safety ceiling against a pathological

package/.agents/scripts/lib/baselines/coverage-updater-cli.js

@@ -0,0 +1,110 @@
+/**
+ * lib/baselines/coverage-updater-cli.js — the `update-coverage-baseline` CLI's
+ * scope-flag reconciliation and its bespoke scorer.
+ *
+ * Story #5316: both lived inside `update-coverage-baseline.js#main`, which no
+ * test imports, so `main` scored CRAP 30 and the inlined scorer another 30 —
+ * two of the ten methods Story #5311's honest re-anchor made visible, both at
+ * 0% coverage.
+ *
+ * **Why this is NOT the `refresh-service.js` default scorer.** Story #4293's
+ * idiom — drop the bespoke scorer, let `refreshBaseline` resolve the canonical
+ * default — was the obvious move here, and `buildDefaultCoverageScorer` is
+ * behaviour-equivalent line for line. It was rejected for one reason: the
+ * default is silent where this one speaks. A missing or unreadable coverage
+ * artifact makes any scorer return `[]`, and `refresh-service.js` has no
+ * empty-rows guard, so a full-scope refresh then writes an emptied baseline at
+ * exit 0. This scorer's `[Coverage] ❌` line is currently the only signal an
+ * operator gets that it happened. Converging would have traded a CRAP row for
+ * a quieter failure. (The fail-open itself is real and wants its own Story —
+ * it changes `refreshBaseline` semantics for every caller.)
+ */
+
+import { Logger } from '../Logger.js';
+import { parseDiffScopeFlag } from './diff-scope-cli.js';
+
+/**
+ * Reconcile the two scope flags.
+ *
+ * Throws when both are present: they describe incompatible scopes, and
+ * silently preferring one would write a baseline the operator did not ask for.
+ *
+ * @param {string[]} [argv]
+ * @returns {{fullScope: boolean, diffScopeRef: string|null}}
+ */
+export function resolveCoverageUpdaterScope(argv = []) {
+  const diffScopeRef = parseDiffScopeFlag(argv);
+  const fullScope = argv.includes('--full-scope');
+  if (fullScope && diffScopeRef !== null) {
+    throw new Error(
+      '[Coverage] --full-scope is incompatible with --diff-scope; pick one',
+    );
+  }
+  return { fullScope, diffScopeRef };
+}
+
+/**
+ * Build the scorer `refreshBaseline` invokes.
+ *
+ * Reads `coverage-final.json`, narrows to the c8 include/exclude scope so the
+ * baseline records exactly the files coverage is measured over, and — in diff
+ * mode — narrows again to the service-resolved in-scope list so untouched rows
+ * are preserved rather than re-scored.
+ *
+ * The three collaborators are named seams (`rules/test-seams.md`) so a test
+ * drives the whole scorer with no coverage artifact and no `.c8rc.cjs` on
+ * disk.
+ *
+ * @param {string} cwd
+ * @param {{readCoverage: Function, loadScope: Function, buildScope: Function,
+ *   score: Function, logger?: object}} deps
+ * @returns {(files: string[], opts: object) => object[]}
+ */
+export function buildCoverageUpdaterScorer(
+  cwd,
+  { readCoverage, loadScope, buildScope, score, logger = Logger } = {},
+) {
+  return (files, opts) => {
+    const effectiveCwd = opts?.cwd ?? cwd;
+    let raw;
+    try {
+      raw = readCoverage(effectiveCwd);
+    } catch (err) {
+      // The only operator-facing signal that the refresh is about to record
+      // nothing — see this module's header.
+      logger.error(`[Coverage] ❌ ${err.message}`);
+      return [];
+    }
+
+    const c8Config = loadScope(effectiveCwd);
+    const scores = score({
+      raw,
+      cwd: effectiveCwd,
+      scope: buildScope({
+        include: c8Config.include ?? [],
+        exclude: c8Config.exclude ?? [],
+      }),
+    });
+
+    // In diff mode, further narrow to the service-resolved in-scope file list.
+    const inScope =
+      !opts?.fullScope && Array.isArray(files) && files.length > 0
+        ? new Set(files)
+        : null;
+
+    const rows = Object.entries(scores)
+      .filter(([relPath]) => inScope === null || inScope.has(relPath))
+      .map(([relPath, s]) => ({
+        path: relPath,
+        lines: s?.lines ?? 0,
+        branches: s?.branches ?? 0,
+        functions: s?.functions ?? 0,
+      }));
+
+    const fileCount = Object.keys(scores).length;
+    logger.info(
+      `[Coverage] Scored ${fileCount} file(s)${inScope ? ` (${rows.length} in scope)` : ''}.`,
+    );
+    return rows;
+  };
+}

package/.agents/scripts/lib/baselines/crap-preview-scan.js

@@ -16,6 +16,7 @@ import {
   resolveEscomplexVersion,
   scanAndScore,
 } from '../crap-utils.js';
+import { CYCLOMATIC_CEILING } from '../cyclomatic-ceiling.js';
 import { resolveCrapPreviewIncremental } from './crap-preview-incremental.js';
 import { resolveCrapEnvOverrides } from './env-overrides.js';
 import {
@@ -66,6 +67,26 @@ function hasCrapRegressions(result) {
  * }} opts
  * @returns {Promise<{ exitCode: number, envelope: object }>}
  */
+/**
+ * The scanned methods at or over the fixed cyclomatic ceiling (Story #5313),
+ * as advisories: `quality-preview.js` lists them and exits 0 on them, so the
+ * reading reaches the author without the preview ever refusing a commit on
+ * complexity alone. Pure.
+ *
+ * @param {Array<{ file: string, method: string, startLine: number, cyclomatic: number }>} rows
+ * @returns {Array<{ file: string, method: string, startLine: number, cyclomatic: number }>}
+ */
+export function listCyclomaticAdvisories(rows) {
+  return (Array.isArray(rows) ? rows : [])
+    .filter((r) => Number(r?.cyclomatic) >= CYCLOMATIC_CEILING)
+    .map(({ file, method, startLine, cyclomatic }) => ({
+      file,
+      method,
+      startLine,
+      cyclomatic,
+    }));
+}
+
 export async function computeCrapPreviewScan({
   crap,
   cwd,
@@ -120,6 +141,10 @@ export async function computeCrapPreviewScan({
     newMethodCeiling,
     scopeInfo: { scope, diffRef },
   });
+  // Story #5313: a method at or over the cyclomatic ceiling is an ADVISORY
+  // on the preview — reported, never a verdict. The ratchet in
+  // `check-cyclomatic.js` owns enforcement.
+  envelope.cyclomaticAdvisories = listCyclomaticAdvisories(scan.rows);
   // Story #4866 (AC-5): above the drifted-row ratio the basis is self-
   // evidently unsound and every per-method verdict below it is an artefact of
   // a mis-keyed join. Say so once, by name, and fail open.