mandrel 2.24.0 → 2.26.0

package/.agents/scripts/acceptance-eval.js

@@ -41,16 +41,31 @@
  * tier along with the per-AC-cluster `--epic <id> --cluster <id>` mode that
  * scored an Epic `## Acceptance Table` against a `main..epic/<id>` diff.)
  *
+ * One gate call per round (Story #4951). A round may fan out into N parallel
+ * maker-blind cluster critics, but their per-cluster verdicts are merged by
+ * the caller into ONE verdict — `criteria[]` in acceptance-array order — and
+ * scored here exactly once. Invoking the gate per cluster instead would burn
+ * one Story-level round per cluster (distinct fingerprints defeat the replay
+ * guard) and race the `signals.ndjson` round ledger. `--expected-criteria`
+ * makes that contract enforceable: a partial (single-cluster) verdict is
+ * rejected before scoring, so the mistake costs no round.
+ *
  * CLI:
- *   --story <id>           Story ID (required).
- *   --verdict <path>       Path to the round's verdict JSON (required).
- *   --no-signal            Suppress the signal emit (tests).
+ *   --story <id>              Story ID (required).
+ *   --verdict <path>          Path to the round's verdict JSON (required).
+ *   --expected-criteria <n>   Reject a verdict not covering exactly n criteria.
+ *   --no-signal               Suppress the signal emit (tests).
  *
  * Stdout: a single JSON envelope
  *   { storyId, epicId, decision, round, cap, capReached, totalCriteria,
- *     metCount, unmetCriteria[], signalEmitted }
+ *     metCount, unmetCriteria[], signalEmitted, replay, verdictFingerprint }
  *   (`epicId` is retained as a always-null field for envelope stability.)
  *
+ * Reading is free (Story #4874): re-invoking the gate over a verdict the
+ * ledger has already scored replays that round (`replay: true`,
+ * `signalEmitted: false`) instead of consuming one, so an unchanged verdict
+ * can never escalate from `redraft` to `block` by being looked at twice.
+ *
  * @see .agents/scripts/lib/orchestration/acceptance-eval-decision.js
  * @see .agents/schemas/acceptance-eval-verdict.schema.json
  */
@@ -69,8 +84,9 @@ import { Logger } from './lib/Logger.js';
 import { appendSignal } from './lib/observability/signals-writer.js';
 import {
   buildAcceptanceEvalSignal,
+  computeVerdictFingerprint,
   decideAcceptanceEval,
-  deriveAcceptanceEvalRound,
+  resolveAcceptanceEvalRound,
 } from './lib/orchestration/acceptance-eval-decision.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -137,6 +153,7 @@ function parseCliArgs(argv) {
     options: {
       story: { type: 'string' },
       verdict: { type: 'string' },
+      'expected-criteria': { type: 'string' },
       'no-signal': { type: 'boolean', default: false },
     },
     strict: false,
@@ -145,10 +162,69 @@ function parseCliArgs(argv) {
   return {
     storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
     verdictPath: values.verdict ?? null,
+    expectedCriteria: values['expected-criteria'] ?? null,
     emitSignal: values['no-signal'] !== true,
   };
 }
 
+/**
+ * The merge contract, stated once so both the flag error and the coverage
+ * error name the same shape the caller has to produce.
+ */
+const MERGE_CONTRACT =
+  'One round = N parallel cluster critics -> ONE merged verdict -> ONE gate call: ' +
+  "merge every cluster's records into a single criteria[] in acceptance[] order, " +
+  'one per acceptance item, before scoring.';
+
+/**
+ * Resolve the optional `--expected-criteria` flag to a positive integer, or
+ * `null` when the flag is absent (which preserves the pre-#4951 behaviour
+ * exactly — no coverage assertion is made).
+ *
+ * Exported for tests.
+ *
+ * @param {string|null|undefined} raw
+ * @returns {number|null}
+ */
+export function resolveExpectedCriteria(raw) {
+  if (raw === null || raw === undefined) return null;
+  // Digits only. `Number.parseInt` stops at the first non-digit, so `4abc`
+  // resolved to 4 — a guard whose entire job is to reject a wrong-sized
+  // verdict was itself accepting a malformed count, and a typo'd `--expected-
+  // criteria` would then wave through a verdict of the wrong length.
+  const text = String(raw).trim();
+  const expected = /^\d+$/.test(text) ? Number(text) : Number.NaN;
+  if (!Number.isInteger(expected) || expected < 1) {
+    throw new Error(
+      `acceptance-eval: --expected-criteria must be a positive integer (the Story's acceptance[] count). ${MERGE_CONTRACT}`,
+    );
+  }
+  return expected;
+}
+
+/**
+ * Reject a verdict that does not cover exactly `expectedCriteria` criteria.
+ *
+ * Called **before** `runAcceptanceEval`, which is where the round ledger is
+ * read and appended — so a partial cluster verdict handed to the gate by
+ * mistake costs no round and can never escalate a `redraft` into a `block`.
+ *
+ * Exported for tests.
+ *
+ * @param {object} verdict — schema-validated verdict.
+ * @param {number|null} expectedCriteria — `null` disables the assertion.
+ * @returns {void}
+ */
+export function assertCriteriaCoverage(verdict, expectedCriteria) {
+  if (expectedCriteria === null) return;
+  const actual = Array.isArray(verdict?.criteria) ? verdict.criteria.length : 0;
+  if (actual === expectedCriteria) return;
+  throw new Error(
+    `acceptance-eval: verdict covers ${actual} criteria but --expected-criteria is ${expectedCriteria}. ` +
+      `${MERGE_CONTRACT} No round was consumed.`,
+  );
+}
+
 /**
  * Compose the operator-facing envelope and emit the per-criterion signal.
  *
@@ -166,7 +242,8 @@ function parseCliArgs(argv) {
  *   self-reported `round` is never load-bearing for the cap.
  * @param {object} [deps]
  * @param {Function} [deps.appendSignalFn]
- * @param {Function} [deps.deriveRoundFn]
+ * @param {Function} [deps.resolveRoundFn]
+ * @param {Function} [deps.fingerprintFn]
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
 export async function runAcceptanceEval(
@@ -175,13 +252,23 @@ export async function runAcceptanceEval(
 ) {
   const {
     appendSignalFn = appendSignal,
-    deriveRoundFn = deriveAcceptanceEvalRound,
+    resolveRoundFn = resolveAcceptanceEvalRound,
+    fingerprintFn = computeVerdictFingerprint,
   } = deps;
   const { maxRounds } = getAcceptanceEval(config);
+  const verdictFingerprint = fingerprintFn(verdict);
+  // Story #4874: re-reading an already-scored verdict is a replay — it
+  // reports the round that verdict was scored under and appends nothing, so
+  // observation alone can never advance the counter or escalate a redraft.
+  const resolved = resolveRoundFn({
+    epicId: null,
+    storyId,
+    config,
+    verdictFingerprint,
+  });
+  const replay = resolved.replay === true;
   const resolvedRound =
-    Number.isInteger(round) && round >= 1
-      ? round
-      : deriveRoundFn({ epicId: null, storyId, config });
+    Number.isInteger(round) && round >= 1 ? round : resolved.round;
   const outcome = decideAcceptanceEval({
     verdict,
     maxRounds,
@@ -189,9 +276,14 @@ export async function runAcceptanceEval(
   });
 
   let signalEmitted = false;
-  if (emitSignal) {
+  if (emitSignal && !replay) {
     const signal = {
-      ...buildAcceptanceEvalSignal({ storyId, epicId: null, outcome }),
+      ...buildAcceptanceEvalSignal({
+        storyId,
+        epicId: null,
+        outcome,
+        verdictFingerprint,
+      }),
       ts: new Date().toISOString(),
     };
     try {
@@ -228,6 +320,10 @@ export async function runAcceptanceEval(
       evidence: c.evidence,
     })),
     signalEmitted,
+    // True when this invocation re-read a verdict the ledger had already
+    // scored: the round was replayed, not advanced, and nothing was appended.
+    replay,
+    verdictFingerprint,
   };
 
   // `block` is the only non-zero exit: the loop has exhausted its bounded
@@ -268,11 +364,13 @@ export async function runAcceptanceEvalCli(
     runAcceptanceEvalImpl = runAcceptanceEval,
     logger = Logger,
   } = deps;
-  const { storyId, verdictPath, emitSignal } = parseCliArgs(argv);
+  const { storyId, verdictPath, expectedCriteria, emitSignal } =
+    parseCliArgs(argv);
+  const expected = resolveExpectedCriteria(expectedCriteria);
 
   if (!storyId) {
     throw new Error(
-      'Usage: node acceptance-eval.js --story <id> --verdict <path> [--no-signal]',
+      'Usage: node acceptance-eval.js --story <id> --verdict <path> [--expected-criteria <n>] [--no-signal]',
     );
   }
   if (!verdictPath) {
@@ -303,6 +401,11 @@ export async function runAcceptanceEvalCli(
 
   const verdict = validateVerdictImpl(parsed);
 
+  // Story #4951: a merged verdict must cover every acceptance[] item. This
+  // runs before the round ledger is touched, so a partial cluster verdict is
+  // a free mistake.
+  assertCriteriaCoverage(verdict, expected);
+
   // A verdict whose embedded storyId disagrees with the CLI flag is a
   // wiring error worth failing on, not a silent mismatch.
   if (Number.isInteger(verdict.storyId) && verdict.storyId !== storyId) {
@@ -346,12 +449,18 @@ runAsCli(import.meta.url, main, {
   source: 'acceptance-eval',
   usage: {
     invocation:
-      'node .agents/scripts/acceptance-eval.js --story <id> --verdict <path> [--no-signal]',
+      'node .agents/scripts/acceptance-eval.js --story <id> --verdict <path> [--expected-criteria <n>] [--no-signal]',
     summary:
       "Score an authored acceptance verdict against the Story's acceptance[] criteria and emit the bounded loop's proceed / redraft / block decision.",
     flags: [
       ['--story <id>', 'GitHub issue number of the Story (required).'],
       ['--verdict <path>', 'Path to the authored verdict JSON (required).'],
+      [
+        '--expected-criteria <n>',
+        'Reject — before scoring, consuming no round — a verdict whose criteria[] ' +
+          "length is not n. Pass the Story's acceptance[] count so a partial " +
+          'cluster verdict cannot be scored as the round.',
+      ],
       [
         '--no-signal',
         "Skip appending the per-criterion signal to the Story's signals ledger.",

package/.agents/scripts/audit-baselines.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+/**
+ * CLI: baseline hotspot engine for the `/audit-baselines` lens (Story #4902).
+ *
+ * Turns the committed `baselines/` folder into ranked hotspot clusters,
+ * gate-surface health signals, trend deltas, and floor-tightening headroom —
+ * the deterministic evidence half of a baseline review, so the lens spends
+ * its judgment on findings instead of re-deriving the numbers by hand.
+ *
+ * Read-only by contract: nothing under `baselines/` is written, and no test,
+ * coverage, or mutation suite is run. The only file this process creates is
+ * the envelope at `--out`.
+ *
+ * Exit 0 whenever evidence was assembled — findings are evidence, not a gate.
+ * A missing git history, absent friction ledger, or unresolvable import graph
+ * are reported as degradations and still exit 0. Only an unwritable `--out`
+ * (or a missing one) is a failure.
+ *
+ * Usage:
+ *   node .agents/scripts/audit-baselines.js --out temp/audit-baselines/envelope.json
+ */
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  DEFAULT_HOTSPOT_LIMIT,
+  runEngine,
+  summarize,
+} from './lib/audit-baselines/engine.js';
+import { DEFAULT_TOP_N } from './lib/audit-baselines/outliers.js';
+import { buildBaselineSchemaAjv } from './lib/baseline-schema-registry.js';
+import { defineFlags } from './lib/cli-args.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+const ENVELOPE_SCHEMA_FILE = 'audit-baselines-envelope.schema.json';
+
+const FLAG_SPEC = {
+  out: { type: 'string' },
+  cwd: { type: 'string' },
+  'top-n': { type: 'integer' },
+  'hotspot-limit': { type: 'integer' },
+  'trend-depth': { type: 'integer' },
+};
+
+/**
+ * Validate the envelope against its shipped schema through the shared
+ * baseline schema registry. Throws with the AJV error list on mismatch —
+ * a malformed envelope is an engine bug, not evidence.
+ *
+ * @param {object} envelope
+ * @returns {void}
+ */
+export function assertEnvelope(envelope) {
+  const validate = buildBaselineSchemaAjv().getSchema(ENVELOPE_SCHEMA_FILE);
+  if (!validate) {
+    throw new Error(
+      `[audit-baselines] ${ENVELOPE_SCHEMA_FILE} is not registered in the baseline schema registry`,
+    );
+  }
+  if (validate(envelope)) return;
+  const detail = (validate.errors ?? [])
+    .map((e) => `${e.instancePath || '/'} ${e.message}`)
+    .join('; ');
+  throw new Error(
+    `[audit-baselines] envelope failed schema validation: ${detail}`,
+  );
+}
+
+/**
+ * Assemble the envelope, validate it, write it, and return the stdout
+ * summary. Exported so tests drive the whole pipeline without spawning.
+ *
+ * @param {{ argv?: string[], cwd?: string, stdout?: { write: (s: string) => void } }} [opts]
+ * @returns {Promise<number>} exit code
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+} = {}) {
+  const { values } = defineFlags(FLAG_SPEC, argv);
+  if (!values.out) {
+    throw new Error('[audit-baselines] --out <path> is required');
+  }
+  const repoRoot = path.resolve(values.cwd ?? cwd);
+  const outPath = path.resolve(repoRoot, values.out);
+
+  const envelope = runEngine({
+    cwd: repoRoot,
+    topN: values.topN ?? DEFAULT_TOP_N,
+    hotspotLimit: values.hotspotLimit ?? DEFAULT_HOTSPOT_LIMIT,
+    trendDepth: values.trendDepth ?? 5,
+  });
+  assertEnvelope(envelope);
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(envelope, null, 2)}\n`, 'utf8');
+
+  stdout.write(`${JSON.stringify(summarize(envelope, outPath), null, 2)}\n`);
+  return 0;
+}
+
+runAsCli(import.meta.url, async () => runCli(), {
+  source: 'audit-baselines',
+  propagateExitCode: true,
+  errorPrefix: '[audit-baselines] ❌ Fatal error',
+  usage: {
+    invocation:
+      'node .agents/scripts/audit-baselines.js --out <path> [--cwd <dir>] [--top-n <n>] [--hotspot-limit <n>] [--trend-depth <n>]',
+    summary:
+      'Read-only baseline hotspot engine: extract bounded per-gate outliers, cluster them per file, rank by severity x churn x import in-degree x friction, and report gate-surface health, trend deltas, and floor headroom.',
+    flags: [
+      ['--out <path>', 'Write the JSON envelope here (required).'],
+      ['--cwd <dir>', 'Repository root to analyse (default: cwd).'],
+      [
+        '--top-n <n>',
+        `Outlier rows extracted per gate (default: ${DEFAULT_TOP_N}).`,
+      ],
+      [
+        '--hotspot-limit <n>',
+        `Hotspot clusters emitted (default: ${DEFAULT_HOTSPOT_LIMIT}).`,
+      ],
+      ['--trend-depth <n>', 'Baseline commits sampled per kind (default: 5).'],
+    ],
+    notes: [
+      'Never writes under baselines/ and never runs a test, coverage, or mutation suite.',
+      'Exit codes:\n  0  evidence assembled (including every degraded input)\n  1  the envelope could not be built or written',
+    ],
+  },
+});

package/.agents/scripts/audit-labels-bootstrap.js

@@ -1,21 +1,20 @@
 /**
- * audit-labels-bootstrap.js — Idempotently create the `audit::<lens>`
- * label taxonomy in the configured GitHub repo.
+ * audit-labels-bootstrap.js — Idempotently create the audit label taxonomy in
+ * the configured GitHub repo.
  *
  * Run this once per repo before `/audit-to-stories` opens its first
  * Story. Re-runs are safe — existing labels are skipped, only missing
  * ones are created. Story #2583 acceptance criterion #6.
  *
- * The lens list is the shared SSOT `AUDIT_LENSES`
- * (`lib/audit-to-stories/audit-lenses.js`), one per `/audit-<lens>` workflow
- * under `.agents/workflows/`. Sourcing the list from the same module that
- * `build-story-body.js` derives `audit::<lens>` labels from guarantees the
- * label producer (this bootstrap) and the label deriver (story-body) cannot
- * drift — a finding from `audit-documentation-results.md` derives
- * `audit::documentation`, and this bootstrap creates exactly that label
- * (Story #4195). The per-lens colour/description metadata lives in
- * `LENS_META` below; adding a new `audit-*` workflow means adding its lens to
- * `AUDIT_LENSES` and (optionally) a `LENS_META` entry.
+ * This CLI is a thin creator over
+ * [`lib/audit-to-stories/audit-label-taxonomy.js`](lib/audit-to-stories/audit-label-taxonomy.js),
+ * which is the SSOT for **every** label an audit sweep creates or generates:
+ * the `audit::<lens>` set (derived from the shared `AUDIT_LENSES` list, one per
+ * `/audit-<lens>` workflow) plus the story-axis labels the filer applies. The
+ * creator and the generator (`build-story-body.js`) read that one list, so the
+ * bootstrap cannot fall behind the filer — the drift that left `risk::high`
+ * generated but defined nowhere (Story #4877), and that made `audit::<dimension>`
+ * labels mint from free-form prose before Story #4195.
  *
  * Delegates to `gh label create` so the script works without any
  * provider plumbing — `gh auth status` is the only prerequisite. Per
@@ -26,88 +25,11 @@
 import process from 'node:process';
 import { parseArgs } from 'node:util';
 
-import { AUDIT_LENSES } from './lib/audit-to-stories/audit-lenses.js';
+import { AUDIT_LABEL_TAXONOMY } from './lib/audit-to-stories/audit-label-taxonomy.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { gh as defaultGh, GhExecError } from './lib/gh-exec.js';
 
-/**
- * Per-lens label presentation. Keyed by canonical lens name. A lens absent
- * from this map falls back to {@link DEFAULT_LENS_META} so a newly-added
- * `AUDIT_LENSES` entry still gets a label without a hard requirement to
- * register colour/description here first.
- */
-const LENS_META = Object.freeze({
-  accessibility: {
-    color: 'c5def5',
-    description: 'Audit-sourced finding: WCAG accessibility conformance',
-  },
-  architecture: {
-    color: '6f42c1',
-    description: 'Audit-sourced finding: architectural concerns',
-  },
-  'clean-code': {
-    color: '0e8a16',
-    description: 'Audit-sourced finding: clean-code / maintainability',
-  },
-  dependencies: {
-    color: 'd4c5f9',
-    description: 'Audit-sourced finding: dependencies / supply chain',
-  },
-  devops: {
-    color: 'fbca04',
-    description: 'Audit-sourced finding: DevOps / CI / CD',
-  },
-  documentation: {
-    color: '1d76db',
-    description: 'Audit-sourced finding: documentation staleness / gaps',
-  },
-  navigability: {
-    color: 'bfdadc',
-    description: 'Audit-sourced finding: route / nav reachability',
-  },
-  performance: {
-    color: 'b60205',
-    description: 'Audit-sourced finding: performance / latency',
-  },
-  privacy: {
-    color: 'fef2c0',
-    description: 'Audit-sourced finding: privacy / data handling',
-  },
-  quality: {
-    color: '0052cc',
-    description: 'Audit-sourced finding: test quality / coverage gaps',
-  },
-  security: {
-    color: 'b60205',
-    description: 'Audit-sourced finding: security / OWASP',
-  },
-  seo: {
-    color: 'fbca04',
-    description: 'Audit-sourced finding: SEO / discoverability',
-  },
-  sre: {
-    color: '0052cc',
-    description: 'Audit-sourced finding: SRE / observability / reliability',
-  },
-  'ux-ui': {
-    color: 'd4c5f9',
-    description: 'Audit-sourced finding: UX / UI concerns',
-  },
-});
-
-const DEFAULT_LENS_META = Object.freeze({
-  color: 'ededed',
-  description: 'Audit-sourced finding',
-});
-
-const DIMENSIONS = Object.freeze(
-  AUDIT_LENSES.map((name) => ({
-    name,
-    ...(LENS_META[name] ?? DEFAULT_LENS_META),
-  })),
-);
-
 async function labelExists(gh, owner, repo, name) {
   try {
     const list = await gh.label.list(
@@ -166,9 +88,8 @@ export async function bootstrapAuditLabels({
   const skipped = [];
   const failed = [];
 
-  for (const dim of DIMENSIONS) {
-    const labelName = `audit::${dim.name}`;
-    const candidate = { ...dim, name: labelName };
+  for (const candidate of AUDIT_LABEL_TAXONOMY) {
+    const labelName = candidate.name;
 
     if (dryRun) {
       created.push(labelName);
@@ -190,7 +111,7 @@ export async function bootstrapAuditLabels({
     }
   }
 
-  return { created, skipped, failed, total: DIMENSIONS.length };
+  return { created, skipped, failed, total: AUDIT_LABEL_TAXONOMY.length };
 }
 
 /**
@@ -241,7 +162,7 @@ export function formatBootstrapReport(result) {
   };
 }
 
-export const __testing = { DIMENSIONS };
+export const __testing = { AUDIT_LABEL_TAXONOMY };
 
 async function main() {
   const { values } = parseArgs({

package/.agents/scripts/audit-to-stories.js

@@ -47,17 +47,34 @@ import { parseAuditReports } from './lib/audit-to-stories/parse-audit-md.js';
 import { buildPlanSeedMarkdown } from './lib/audit-to-stories/seed-from-findings.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { searchSemanticCandidates } from './lib/findings/semantic-issue-search.js';
+import { SEVERITIES, SEVERITY_RANK } from './lib/findings/severity.js';
 import { Logger } from './lib/Logger.js';
 import { parse as parseStoryBody } from './lib/story-body/story-body.js';
 
-const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
 const DEFAULT_GLOB = 'temp/audits/audit-*-results.md';
 const FAN_OUT_REPORT = 'audit-fan-out-results.md';
 
+/**
+ * Does `finding` clear the `threshold` severity floor?
+ *
+ * `SEVERITY_RANK` is imported from the canonical scale rather than declared
+ * here (Story #4877). The local copy this replaces ranked only four levels
+ * (`critical|high|medium|low`), so `info` — the canonical floor — ranked `0`,
+ * below even `--severity low`, and every informational finding was silently
+ * dropped from every filtered run. Sourcing the ranking from the SSOT means a
+ * level cannot exist in the vocabulary and be invisible to the filter.
+ *
+ * An unrecognised or absent severity still ranks below every real floor: it
+ * failed to parse, so it is not evidence that a threshold was met.
+ *
+ * @param {{ severity?: string }} finding
+ * @param {string} [threshold] — a canonical level, `'all'`, or falsy for no floor.
+ * @returns {boolean}
+ */
 function meetsSeverity(finding, threshold) {
   if (!threshold || threshold === 'all') return true;
   const minRank = SEVERITY_RANK[threshold] ?? 0;
-  const fRank = SEVERITY_RANK[finding.severity] ?? 0;
+  const fRank = SEVERITY_RANK[finding.severity] ?? -1;
   return fRank >= minRank;
 }
 
@@ -77,8 +94,21 @@ function readReports(paths) {
   }));
 }
 
+/**
+ * Count findings per severity bucket. The buckets are the canonical levels plus
+ * `unknown` for a finding whose severity did not parse — kept as a visible
+ * bucket so an unparseable severity is reported rather than absorbed into a
+ * real level. Derived from `SEVERITIES` so a new level appears in the tally
+ * automatically instead of falling into `unknown` (Story #4877).
+ *
+ * @param {Array<{ severity?: string }>} findings
+ * @returns {Record<string, number>}
+ */
 function tallyBySeverity(findings) {
-  const t = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
+  const t = {
+    ...Object.fromEntries(SEVERITIES.map((s) => [s, 0])),
+    unknown: 0,
+  };
   for (const f of findings) {
     if (Object.hasOwn(t, f.severity)) t[f.severity] += 1;
     else t.unknown += 1;