mandrel 2.55.0 → 2.57.0

package/.agents/scripts/lib/audit-to-stories/issue-corpus.js

@@ -0,0 +1,162 @@
+/**
+ * lib/audit-to-stories/issue-corpus.js — where the dedup corpus comes from,
+ * and how a corpus that could not be fetched is described to the operator.
+ *
+ * Dedup needs exactly one thing from GitHub: the Issues carrying an `audit::*`
+ * label. Until Story #5301 the only source was the provider's list port, which
+ * spawns `gh`, so a host without a `gh` CLI — a Claude Code cloud sandbox,
+ * where `gh` is absent and direct API access is disabled while the GitHub MCP
+ * tools work fine — could not dedup at all: every group classified `create`
+ * and a scheduled sweep re-filed what it had already filed.
+ *
+ * Sourcing lives here rather than in `dedupe-against-github.js` so that module
+ * stays what its own header claims — pure routing of findings to verdicts —
+ * and so the empty-corpus and failed-fetch cases cannot diverge between call
+ * sites. Nothing here reaches the network or the filesystem: a caller that
+ * already holds the corpus passes the array in.
+ */
+
+import { auditLabelsForFindings } from './audit-lenses.js';
+import { buildIssueIndex } from './issue-index.js';
+
+/**
+ * Resolve the dedup corpus into an index, from whichever source is wired.
+ *
+ * A corpus the caller already holds (`issues`) wins: the host fetched it by
+ * whatever GitHub access path it has, which is what lets dedup run where there
+ * is no `gh` CLI. Otherwise the run's `audit::*` Issues are pre-fetched off the
+ * list port, once.
+ *
+ * Two results deliberately do NOT collapse to "no index", because a null index
+ * silently returns the run to the per-finding search — which on a
+ * provider-less host is no dedup at all, the failure this path exists to kill.
+ * An **empty** injected corpus is a legitimate first sweep and yields a real
+ * zero-row index. A **failed** pre-fetch hands back its `error` so the caller
+ * can say so in its own words: an operator who cannot see that the pre-fetch
+ * failed cannot tell a checked plan from an unchecked one.
+ *
+ * Module-internal: every caller reaches it through `prepareDedupRouting`, so
+ * the empty-corpus and failed-fetch cases cannot diverge between call sites.
+ *
+ * @param {{ listAuditIssues?: Function, groups?: Array<object>,
+ *   issues?: Array<object> }} params
+ * @returns {Promise<{ index: object|null, source: 'injected'|'prefetch'|'none',
+ *   error?: unknown }>}
+ */
+async function resolveIssueCorpus({ listAuditIssues, groups, issues }) {
+  if (Array.isArray(issues)) {
+    return { index: buildIssueIndex(issues), source: 'injected' };
+  }
+  const labels =
+    typeof listAuditIssues === 'function'
+      ? auditLabelsForFindings(
+          (groups ?? []).flatMap((group) => group?.findings ?? []),
+        )
+      : [];
+  if (labels.length === 0) return { index: null, source: 'none' };
+  try {
+    return {
+      index: buildIssueIndex(await listAuditIssues(labels)),
+      source: 'prefetch',
+    };
+  } catch (err) {
+    return { index: null, source: 'none', error: err };
+  }
+}
+
+/**
+ * Attach the index description to a seeded summary, when there is one to make.
+ *
+ * A run with neither an injected corpus nor a list port has no index to
+ * describe, and `{ source: 'none', size: 0 }` says nothing the field's absence
+ * does not — while inviting the reading "an index was consulted and it was
+ * empty", the exact confusion this whole path exists to remove. Omitting it
+ * also leaves the summary a pure per-finding-search run emits byte-identical
+ * to what it has always been.
+ *
+ * A failed pre-fetch is the one `none` that IS described: there the run ended
+ * *without* an index it expected to have, and the operator needs to see that.
+ *
+ * @param {object} summary — the seeded counters.
+ * @param {{ source: string, index: object|null, error?: unknown }} resolution
+ * @returns {object} the same summary, with `dedupIndex` when applicable.
+ */
+function withIndexDescription(summary, { source, index, error }) {
+  if (source === 'none' && !error) return summary;
+  return { ...summary, dedupIndex: { source, size: index?.size ?? 0 } };
+}
+
+/**
+ * Assemble everything routing needs from the caller's ports and corpus: the
+ * read ports, the resolved index, and the two facts the caller must report —
+ * what the corpus was and whether fetching it degraded.
+ *
+ * The provider port is validated here because this is where "is there a usable
+ * dedup source at all" is actually known. It is required only on the
+ * un-indexed path: once an index exists every exact lookup is answered from
+ * memory and `findIssuesByFingerprint` is never called, so demanding it there
+ * would be the one thing standing between a `gh`-less host and a real dedup
+ * run.
+ *
+ * @param {{ groups?: Array<object>, provider?: object,
+ *   searchCandidates?: Function, listAuditIssues?: Function,
+ *   issues?: Array<object> }} params
+ * The seeded `summary` comes back with it: the corpus is the only thing that
+ * knows what the index was, and returning the counters beside it keeps the
+ * caller from reconstructing a shape it does not own.
+ *
+ * @returns {Promise<{ routing: object, summary: object, error?: unknown }>}
+ * @throws {Error} when neither a provider read port nor a corpus is supplied.
+ */
+export async function prepareDedupRouting({
+  groups,
+  provider,
+  searchCandidates,
+  listAuditIssues,
+  issues,
+}) {
+  const hasProviderPort =
+    Boolean(provider) && typeof provider.findIssuesByFingerprint === 'function';
+  if (!hasProviderPort && !Array.isArray(issues)) {
+    throw new Error(
+      'classifyGroupsAgainstGitHub: provider.findIssuesByFingerprint is required ' +
+        'when no `issues` corpus is supplied',
+    );
+  }
+  const { index, source, error } = await resolveIssueCorpus({
+    listAuditIssues,
+    groups,
+    issues,
+  });
+  const semanticPort =
+    typeof searchCandidates === 'function' ? searchCandidates : undefined;
+  return {
+    routing: {
+      // routeFinding hands the port the sha it computed off the canonical
+      // projection, which equals the sha the group already carries.
+      searchIssues: hasProviderPort
+        ? (sha) => provider.findIssuesByFingerprint(sha)
+        : undefined,
+      semanticPort,
+      // An index carries the semantic-key map, so location-based confirmation
+      // costs nothing once one exists. Without this, confirmation would discard
+      // the `bySemanticKey` half of the pool the local lookup just built, and a
+      // provider-less run would be fingerprint-exact only — strictly weaker
+      // than the path it replaces.
+      routeOptions: {
+        semanticKeyConfirm: Boolean(semanticPort) || Boolean(index),
+      },
+      index,
+    },
+    summary: withIndexDescription(
+      {
+        create: 0,
+        skipOpen: 0,
+        skipReoccurring: 0,
+        dedupDegraded: { count: 0, groups: [] },
+      },
+      { source, index, error },
+    ),
+    error,
+  };
+}

package/.agents/scripts/lib/audit-to-stories/issues-file.js

@@ -0,0 +1,121 @@
+/**
+ * lib/audit-to-stories/issues-file.js — the issue corpus dedup checks against,
+ * and the one normaliser every source of it goes through.
+ *
+ * Dedup needs exactly one thing from GitHub: the list of Issues carrying an
+ * `audit::*` label. Until Story #5301 the only way to get it was the provider,
+ * which spawns `gh`, so a host without a `gh` CLI — a Claude Code cloud
+ * sandbox, where `gh` is absent and direct API access is disabled but the
+ * GitHub MCP tools work fine — could not dedup at all. Every group classified
+ * `create` and a scheduled sweep re-filed findings it had already filed.
+ *
+ * `--issues-file <path>` breaks that coupling: the host fetches the list by
+ * whatever access path it has and hands over a JSON array. Nothing here knows
+ * how it was fetched, so MCP, REST, and a cached dump are all equally valid.
+ *
+ * A file that cannot be read as an issue array is a **hard error**, never a
+ * degrade. Falling back would mean "dedup did not run" on precisely the
+ * invocation whose whole purpose is that it does — and a create-only plan the
+ * operator reads as checked is how the duplicate-filing loop starts.
+ */
+
+import fs from 'node:fs';
+
+/**
+ * Flatten one raw issue onto the `{ number, state, title, body }` shape the
+ * dedupe module reads, collapsing every closed-ish state spelling (`CLOSED`,
+ * `state_reason: not_planned`, …) onto `'closed'`.
+ *
+ * Shared by both corpus sources — the provider's `searchIssues` hits and the
+ * `--issues-file` array — so a host can hand over a raw `list_issues` result
+ * verbatim without knowing which spelling this repo's dedup expects.
+ *
+ * @param {object} hit
+ * @returns {{ number: number, state: 'open'|'closed', title: string, body: string }}
+ */
+export function normaliseIssueHit(hit) {
+  return {
+    number: hit.number,
+    state: (hit.state ?? hit.state_reason ?? 'open')
+      .toString()
+      .toLowerCase()
+      .includes('closed')
+      ? 'closed'
+      : 'open',
+    title: hit.title ?? '',
+    body: hit.body ?? '',
+  };
+}
+
+/**
+ * Read and normalise a host-supplied issue corpus.
+ *
+ * `state` is read from either `state` or `state_reason`, so a closed-as-
+ * not-planned issue is recognised however the host's API spelled it. Only
+ * `number` and `body` are load-bearing: the number identifies the match and
+ * the body carries the provenance footers dedup confirms identity against.
+ *
+ * @param {string} filePath — path to a JSON array of issues.
+ * @param {{ readFileSyncImpl?: typeof fs.readFileSync }} [seams]
+ * @returns {Array<{ number: number, state: string, title: string, body: string }>}
+ * @throws {Error} when the file is missing, unreadable, not JSON, or not an array.
+ */
+export function loadIssuesFile(
+  filePath,
+  { readFileSyncImpl = fs.readFileSync } = {},
+) {
+  let raw;
+  try {
+    raw = readFileSyncImpl(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `--issues-file: cannot read "${filePath}" (${err.message}). Dedup needs ` +
+        'the issue corpus to check against; running without it would classify ' +
+        'every group "create" and re-file findings already tracked.',
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `--issues-file: "${filePath}" is not valid JSON (${err.message}). ` +
+        'Expected a JSON array of issues, e.g. the result of listing every ' +
+        'issue labelled audit::* with state "all".',
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(
+      `--issues-file: "${filePath}" holds ${describeShape(parsed)}, not a JSON ` +
+        'array of issues. Pass the issue list itself, not the envelope wrapping it.',
+    );
+  }
+  return parsed.filter(isIssueLike).map(normaliseIssueHit);
+}
+
+/**
+ * Whether one array entry can possibly identify an issue. An entry without a
+ * numeric `number` can never confirm a match — exactly as it could not when it
+ * came back from a search — so it is dropped rather than indexed under nothing.
+ *
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+function isIssueLike(entry) {
+  return (
+    Boolean(entry) &&
+    typeof entry === 'object' &&
+    typeof entry.number === 'number'
+  );
+}
+
+/**
+ * Name what a non-array payload actually was, so the error points at the fix.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeShape(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `a JSON ${typeof value}`;
+}

package/.agents/scripts/lib/audit-to-stories/ledger-commit.js

@@ -28,9 +28,9 @@
  * complexity budget does not absorb a git driver.
  */
 
+import { DEFAULT_LEDGER_PATH } from '../findings/audit-ledger.js';
 import { gh as defaultGh } from '../gh-exec.js';
 import { gitSync } from '../git-utils.js';
-import { DEFAULT_LEDGER_PATH } from './ledger.js';
 import { openLedgerPullRequest, probeGit } from './ledger-pr.js';
 
 /** Fallback base branch when config carries no `project.baseBranch`. */

package/.agents/scripts/lib/audit-to-stories/ledger-record.js

@@ -0,0 +1,126 @@
+/**
+ * lib/audit-to-stories/ledger-record.js — record what a run actually filed.
+ *
+ * The cross-run ledger can only suppress an already-filed finding if something
+ * tells it the finding was filed. Until Story #5305 nothing did: the reconcile
+ * ran *during* the scan, before any Issue existed, and its `issueStates` were
+ * derived from `matchedIssues` — the Issues dedup FOUND. A group classified
+ * `create` has none, so a freshly opened Issue contributed nothing and its
+ * entry persisted as `status: "new", issue: null` forever. On a host where
+ * GitHub-search dedup works that is invisible; on one where it cannot run,
+ * nothing suppresses anything and every sweep re-files everything.
+ *
+ * The missing input is the `groupKey → issueNumber` map, which exists only
+ * after the Issues are opened. `--wire-edges` already takes exactly that map
+ * and is already a required pass, which is why the record rides along with it
+ * rather than arriving as a second command an operator must remember.
+ *
+ * Nothing here reaches the network: the caller hands over the map it already
+ * holds, and the only I/O is the ledger read/write this module delegates to
+ * `ledger.js`. That is what lets the record run BEFORE the provider is loaded,
+ * so a host whose provider cannot be constructed still records what it filed.
+ */
+
+import {
+  DEFAULT_LEDGER_PATH,
+  readLedger,
+  reconcileLedger,
+  writeLedger,
+} from '../findings/audit-ledger.js';
+import {
+  fingerprintAuditFinding,
+  toCanonicalFinding,
+} from './finding-adapter.js';
+
+/**
+ * Project the opened-issue map onto the `{ fingerprint → issueState }` shape
+ * `reconcileLedger` reads, and collect the findings those groups carry.
+ *
+ * Only groups present in the map contribute. A group the map does not mention
+ * was not opened — deduped, ledger-suppressed, or simply skipped — and
+ * inventing an Issue state for it is how a finding gets suppressed against an
+ * Issue that does not exist.
+ *
+ * Every recorded state is `open`: the map names Issues this run just created,
+ * and a just-created Issue is open. A later close is learned from the live
+ * lookup on the next run, where it outranks this record (`decideStatus` reads
+ * the closed-Issue branch first).
+ *
+ * @param {object} params
+ * @param {Array<object>} params.groups — the `create`-eligible groups.
+ * @param {Record<string, number>} params.issueByGroupKey — group key → issue number.
+ * Module-internal: `recordFiledIssues` is the only production entrypoint, and
+ * exporting this for tests alone trips the CI-only `dead-exports:production`
+ * gate. It is covered through `recordFiledIssues`, which is the seam that
+ * actually ships.
+ *
+ * @returns {{ findings: Array<object>, issueStates: Record<string, { state: string, number: number }>, groupsRecorded: number }}
+ */
+function issueStatesFromIssueMap({ groups, issueByGroupKey }) {
+  const findings = [];
+  const issueStates = {};
+  let groupsRecorded = 0;
+
+  for (const group of groups ?? []) {
+    const number = issueByGroupKey?.[group?.groupKey];
+    if (typeof number !== 'number') continue;
+    groupsRecorded += 1;
+    for (const finding of group.findings ?? []) {
+      findings.push(finding);
+      issueStates[fingerprintAuditFinding(finding).full] = {
+        state: 'open',
+        number,
+      };
+    }
+  }
+
+  return { findings, issueStates, groupsRecorded };
+}
+
+/**
+ * Fold the just-opened Issues onto the committed ledger.
+ *
+ * Only the mapped groups' findings are passed to `reconcileLedger`, so every
+ * other entry survives untouched — `reconcileLedger` copies the prior index
+ * forward and rewrites only what this scan hands it.
+ *
+ * @param {object} params
+ * @param {string} [params.ledgerPath]
+ * @param {Array<object>} params.groups — the `create`-eligible groups.
+ * @param {Record<string, number>} params.issueByGroupKey
+ * @param {boolean} [params.write=true] — `false` computes the record without
+ *   persisting it, which is what `--dry-run` needs.
+ * @param {{ readLedgerImpl?: Function, writeLedgerImpl?: Function }} [seams]
+ * @returns {{ path: string, written: boolean, groupsRecorded: number, findingsRecorded: number, filed: number }}
+ */
+export function recordFiledIssues(
+  { ledgerPath, groups, issueByGroupKey, write = true },
+  { readLedgerImpl = readLedger, writeLedgerImpl = writeLedger } = {},
+) {
+  const path = ledgerPath ?? DEFAULT_LEDGER_PATH;
+  const { findings, issueStates, groupsRecorded } = issueStatesFromIssueMap({
+    groups,
+    issueByGroupKey,
+  });
+
+  const { ledger: next, classifications } = reconcileLedger({
+    ledger: readLedgerImpl(path),
+    findings,
+    issueStates,
+    toCanonical: toCanonicalFinding,
+  });
+  // Nothing to record means nothing to write. The ledger is committed consumer
+  // state and `--ledger-commit` opens a PR only when it changed, so rewriting
+  // it with a fresh `generatedAt` and no new memory would manufacture a diff
+  // that says nothing.
+  const wrote = Boolean(write) && findings.length > 0;
+  if (wrote) writeLedgerImpl(path, next);
+
+  return {
+    path,
+    written: wrote,
+    groupsRecorded,
+    findingsRecorded: findings.length,
+    filed: classifications.filter((c) => c.status === 'filed').length,
+  };
+}

package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js

@@ -18,6 +18,7 @@
  */
 
 import { SEVERITIES } from '../findings/severity.js';
+import { auditLabelFooterForFindings } from './audit-label-taxonomy.js';
 import { formatEpicGrouping } from './epic-grouping-directive.js';
 import {
   renderFingerprintFooter,
@@ -107,6 +108,16 @@ function formatMVPScope(groups) {
       const footers = [
         renderFingerprintFooter(findings),
         renderSemanticKeyFooter(findings),
+        // ...and the `audit::*` labels the dedup corpus is listed by.
+        //
+        // Without them a Story the chained planning path files is absent from
+        // the pool an indexed sweep matches against, and with an index in play
+        // the exact lookup is answered from that pool without ever reaching
+        // the provider — so the fingerprint footer above cannot rescue it. The
+        // two footers are therefore a pair: one carries the identity, the
+        // other carries the reason the next sweep ever looks at this issue
+        // (Story #5307).
+        auditLabelFooterForFindings(findings),
       ]
         .map((f) => `   ${f}`)
         .join('\n');

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.