mandrel 2.23.0 → 2.25.0

package/.agents/scripts/lib/escomplex-ast-compat.js

@@ -0,0 +1,360 @@
+/**
+ * escomplex-ast-compat.js — reconcile the `typhonjs-escomplex` code generator
+ * with the Babel AST that `typhonjs-escomplex`'s own default parser emits.
+ *
+ * ## The upstream defect
+ *
+ * `typhonjs-escomplex` parses with `@typhonjs/babel-parser`, so every AST it
+ * analyses is a **Babel** AST. But `typhonjs-escomplex-commons`'
+ * `utils/ast/astSyntax.js` — the code generator that `ASTGenerator` drives —
+ * was written against **ESTree**. The two disagree on node names
+ * (`OptionalMemberExpression` vs a `MemberExpression` with `optional: true`)
+ * and on node shapes (Babel's `RegExpLiteral` carries `pattern`/`flags`
+ * directly; ESTree wraps them in a `regex` object on a `Literal`).
+ *
+ * That mismatch is invisible for most code because the metric traversal runs
+ * off the syntax plugin's trait tables, not off `astSyntax`. `astSyntax` is
+ * only reached where a trait re-serialises a **sub-AST** to synthesise a
+ * Halstead operand or a function signature — nine traits do this:
+ * `For`/`ForIn`/`ForOf` heads, `Function`/`FunctionExpression`/
+ * `ArrowFunctionExpression` parameter lists, `Class`/`ClassExpression`
+ * bodies, and `YieldExpression` arguments.
+ *
+ * Reach one of those with a Babel-only node and `analyzeModule()` throws —
+ * aborting the whole module, not just the sub-expression. The constructs that
+ * trip it are ordinary modern JavaScript:
+ *
+ * ```js
+ * for (const t of s.split(/[^a-z]+/)) {}   // TypeError: …reading 'pattern'
+ * for (const t of await xs()) {}           // …generator[node.type] is not a function
+ * for (const t of a?.b) {}                 // …generator[node.type] is not a function
+ * function f(a = () => import('x')) {}     // …this[node.callee.type] is not a function
+ * function f(a = { ...b }) {}              // TypeError: …reading 'type'
+ * function f(a = { m() {} }) {}            // TypeError: …reading 'generator'
+ * function f(a = class { m() {} }) {}      // …this[statement.type] is not a function
+ * ```
+ *
+ * The `{ ...b }` case is upstream issue #24, open and untouched since
+ * 2020-12-16 with a byte-identical stack trace. The package last published in
+ * June 2022 and the repo that holds the defective file has issues *disabled*,
+ * so waiting for an upstream release is not a plan. Consumers of this kernel
+ * previously absorbed the breakage as an allowlist of "unscorable" files that
+ * grew every time someone wrote a `?.` in a loop head.
+ *
+ * ## What this module does
+ *
+ * Installs the missing handlers and repairs the two shape assumptions, on the
+ * shared `astSyntax` table, once per process. Every patch is **conditional**:
+ * a handler is only installed where the table lacks one, and the two repairs
+ * wrap the original rather than replacing its behaviour. If a future kernel
+ * bump fixes any of this upstream, the corresponding patch silently stops
+ * applying and `install()` reports a shorter list — which
+ * `tests/lib/escomplex-ast-compat.test.js` asserts on, so the shrinkage is
+ * visible rather than silent.
+ *
+ * Nothing here changes the score of a file that already parses: the patched
+ * paths are exactly the paths that previously threw.
+ *
+ * @see https://github.com/typhonjs-node-escomplex/typhonjs-escomplex/issues/24
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+/** Marker set on every function this module installs, for idempotency. */
+const PATCH_MARKER = Symbol.for('mandrel.escomplexAstCompat');
+
+/** Memoised result of the one-time install. */
+let installResult = null;
+
+/**
+ * Resolve the shared `astSyntax` generator table.
+ *
+ * This is a deep import into a transitive dependency's `dist/`, which is
+ * exactly as fragile as it looks — hence the soft failure. If upstream ever
+ * restructures, `install()` reports `available: false` and the engine falls
+ * back to today's behaviour (unscorable files, now reported explicitly by
+ * the engine rather than silently scored 0).
+ *
+ * The patch must land on the *same* `typhonjs-escomplex-commons` instance the
+ * kernel loads, so `commons` is resolved **through `typhonjs-escomplex`'s own
+ * resolution** rather than from here. Resolving it directly would be a coin
+ * flip: under a hoisting installer it usually finds the same copy, but under
+ * pnpm's isolated layout — or as soon as anything declares `commons` directly —
+ * it can find a *different* physical copy, and the patch then lands on a table
+ * nobody reads while `install()` cheerfully reports success. Anchoring makes
+ * that failure mode unreachable.
+ *
+ * `requireFn` is the test seam: a cross-checkout verification harness passes
+ * its own `createRequire` so the anchor starts from that checkout's escomplex.
+ *
+ * @param {NodeJS.Require} [requireFn]
+ * @returns {Record<string, Function>|null}
+ */
+function resolveSyntaxTable(requireFn = require) {
+  try {
+    const fromKernel = createRequire(requireFn.resolve('typhonjs-escomplex'));
+    const mod = fromKernel(
+      'typhonjs-escomplex-commons/dist/utils/ast/astSyntax.js',
+    );
+    const table = mod?.default ?? mod;
+    if (!table || typeof table !== 'object') return null;
+    // Sanity-check that this is the table we think it is before mutating it.
+    if (typeof table.MemberExpression !== 'function') return null;
+    if (Object.isFrozen(table)) return null;
+    return table;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Tag a handler as ours so a second `install()` is a no-op.
+ *
+ * @template {Function} F
+ * @param {F} fn
+ * @returns {F}
+ */
+function mark(fn) {
+  fn[PATCH_MARKER] = true;
+  return fn;
+}
+
+/**
+ * Install `name` only if the table has no handler for it. Returns whether the
+ * install happened, so the caller can report the applied surface.
+ *
+ * @param {Record<string, Function>} table
+ * @param {string} name
+ * @param {Function} handler
+ * @returns {boolean}
+ */
+function addMissing(table, name, handler) {
+  if (typeof table[name] === 'function') return false;
+  table[name] = mark(handler);
+  return true;
+}
+
+/**
+ * Build an ESTree-shaped stand-in for a Babel `ObjectMethod` / `ClassMethod`,
+ * whose function bits sit on the node itself rather than under `value`.
+ * `MethodDefinition` reads `node.value.{generator,params,body}`, so handing it
+ * a synthesized `value` lets the original handler do the work unchanged.
+ *
+ * @param {object} node
+ * @returns {object}
+ */
+function asMethodDefinition(node) {
+  return {
+    ...node,
+    kind:
+      typeof node.kind === 'string' && node.kind.length > 0
+        ? node.kind
+        : 'init',
+    value: {
+      type: 'FunctionExpression',
+      generator: Boolean(node.generator),
+      async: Boolean(node.async),
+      params: node.params ?? [],
+      body: node.body,
+    },
+  };
+}
+
+/**
+ * Patch the shared `astSyntax` table. Idempotent; safe to call from every
+ * entry point that is about to run `analyzeModule`.
+ *
+ * @param {{ requireFn?: NodeJS.Require, memoise?: boolean }} [options] Test
+ *   seam only — see {@link resolveSyntaxTable}. Production callers pass
+ *   nothing.
+ * @returns {{ available: boolean, applied: string[] }} `available` is false
+ *   when the upstream internals could not be resolved. `applied` names each
+ *   patch that was actually needed, so an upstream fix shows up as a
+ *   shorter list.
+ */
+export function install(options = {}) {
+  const { requireFn, memoise = true } = options;
+  if (memoise && installResult !== null) return installResult;
+
+  const table = resolveSyntaxTable(requireFn);
+  if (table === null) {
+    const unavailable = { available: false, applied: [] };
+    if (memoise) installResult = unavailable;
+    return unavailable;
+  }
+
+  const applied = [];
+  const add = (name, handler) => {
+    if (addMissing(table, name, handler)) applied.push(name);
+  };
+
+  // ---- Repair 1: Babel's RegExpLiteral shape -------------------------------
+  // Upstream reads `node.regex.pattern`, which only exists on an ESTree
+  // `Literal`. Babel puts `pattern`/`flags` on the node. Wrapped rather than
+  // replaced so the ESTree delegate path (`Literal` → `RegExpLiteral`) keeps
+  // its exact original output.
+  if (
+    typeof table.RegExpLiteral === 'function' &&
+    !table.RegExpLiteral[PATCH_MARKER]
+  ) {
+    const original = table.RegExpLiteral;
+    table.RegExpLiteral = mark(function RegExpLiteral(node, state) {
+      if (node?.regex === undefined) {
+        state.output.write(
+          `new RegExp(${JSON.stringify(node?.pattern ?? '')}, ` +
+            `${JSON.stringify(node?.flags ?? '')})`,
+        );
+        return;
+      }
+      return original.call(this, node, state);
+    });
+    applied.push('RegExpLiteral');
+  }
+
+  // ---- Repair 2: ObjectExpression's hard `this.Property()` dispatch --------
+  // `ObjectExpression` calls `this.Property(el)` on every element regardless
+  // of the element's actual type. Two Babel shapes get mis-routed by that:
+  //
+  //   `{ ...b }`    → a `SpreadElement` lands in `Property`, which reads
+  //                   `node.key.type` and throws. Upstream issue #24.
+  //   `{ m() {} }`  → an `ObjectMethod` has `kind: 'method'`, so `Property`'s
+  //                   `node.kind[0] !== 'i'` test sends the raw Babel node to
+  //                   `MethodDefinition`, which reads `node.value.generator`
+  //                   and throws.
+  //
+  // Patching `Property` rather than `ObjectExpression` keeps the patch small
+  // and leaves the indentation-sensitive object serialisation untouched:
+  // anything arriving here that is not actually a property node gets
+  // re-dispatched on its real type.
+  //
+  // `Property` and `ObjectProperty` are excluded from re-dispatch because the
+  // table aliases `ObjectProperty` to `Property` — re-dispatching either would
+  // recurse into this wrapper forever.
+  if (typeof table.Property === 'function' && !table.Property[PATCH_MARKER]) {
+    const original = table.Property;
+    const PROPERTY_TYPES = new Set(['Property', 'ObjectProperty']);
+    table.Property = mark(function Property(node, state) {
+      const type = node?.type;
+      if (
+        typeof type === 'string' &&
+        !PROPERTY_TYPES.has(type) &&
+        typeof this[type] === 'function'
+      ) {
+        return this[type](node, state);
+      }
+      return original.call(this, node, state);
+    });
+    applied.push('Property');
+  }
+
+  // ---- Missing handlers: Babel-only node types ----------------------------
+
+  // `await x` — mirrors upstream's `YieldExpression`.
+  add('AwaitExpression', function AwaitExpression(node, state) {
+    const output = state.output;
+    output.write('await ');
+    output.operators.push('await');
+    if (node.argument) this[node.argument.type](node.argument, state);
+  });
+
+  // `a?.b` / `a?.[b]` — mirrors upstream's `MemberExpression`, with `?.`
+  // recorded as its own operator so optional access is not counted as plain
+  // member access.
+  add(
+    'OptionalMemberExpression',
+    function OptionalMemberExpression(node, state) {
+      const output = state.output;
+      this[node.object.type](node.object, state);
+      if (node.computed) {
+        output.write('?.[');
+        this[node.property.type](node.property, state);
+        output.write(']');
+        output.operators.push('?.[]');
+      } else {
+        output.write('?.');
+        output.operators.push('?.');
+        this[node.property.type](node.property, state);
+      }
+    },
+  );
+
+  // `a?.()` — mirrors upstream's `CallExpression`.
+  add('OptionalCallExpression', function OptionalCallExpression(node, state) {
+    this[node.callee.type](node.callee, state);
+    state.output.write('?.');
+    state.output.operators.push('?.()');
+    ASTUtil().formatSequence(node.arguments ?? [], state, this);
+  });
+
+  // The callee node of a dynamic `import(...)`. Babel models the `import`
+  // keyword as its own node type; ESTree has no equivalent.
+  add('Import', function Import(_node, state) {
+    state.output.write('import');
+    state.output.operators.push('import()');
+  });
+
+  // `{ m() {} }` / `{ get m() {} }` — Babel's ObjectMethod.
+  add('ObjectMethod', function ObjectMethod(node, state) {
+    return this.MethodDefinition(asMethodDefinition(node), state);
+  });
+
+  // `class { m() {} }` — Babel's ClassMethod (ESTree: MethodDefinition).
+  add('ClassMethod', function ClassMethod(node, state) {
+    return this.MethodDefinition(asMethodDefinition(node), state);
+  });
+
+  // `class { p = 1 }` — Babel's ClassProperty (ESTree: PropertyDefinition).
+  const classProperty = function ClassProperty(node, state) {
+    const output = state.output;
+    if (node.static) {
+      output.write('static ');
+      output.operators.push('static');
+    }
+    if (node.computed) {
+      output.write('[');
+      this[node.key.type](node.key, state);
+      output.write(']');
+    } else {
+      this[node.key.type](node.key, state);
+    }
+    if (node.value) {
+      output.write(' = ');
+      output.operators.push('=');
+      this[node.value.type](node.value, state);
+    }
+    output.write(';');
+  };
+  add('ClassProperty', classProperty);
+  add('PropertyDefinition', classProperty);
+
+  const result = { available: true, applied };
+  if (memoise) installResult = result;
+  return result;
+}
+
+/**
+ * `ASTUtil` is only needed by the `OptionalCallExpression` handler, and only at
+ * call time — resolving it lazily keeps `install()` free of a second deep
+ * import that could fail at module load. Anchored through the kernel for the
+ * same reason as {@link resolveSyntaxTable}.
+ *
+ * `formatSequence` is a pure helper that takes the traveler and state as
+ * arguments, so which copy answers is immaterial — but resolving it the same
+ * way keeps one rule in this file rather than two.
+ *
+ * @returns {{ formatSequence: Function }}
+ */
+function ASTUtil() {
+  const fromKernel = createRequire(require.resolve('typhonjs-escomplex'));
+  const mod = fromKernel(
+    'typhonjs-escomplex-commons/dist/utils/ast/ASTUtil.js',
+  );
+  return mod?.default ?? mod;
+}
+
+// A test that needs to re-run the install against the already-patched table
+// passes `{ memoise: false }` rather than resetting module state — the patches
+// are self-detecting via PATCH_MARKER, so a non-memoised re-run is exactly the
+// idempotency assertion worth making.

package/.agents/scripts/lib/findings/route-finding.js

@@ -30,6 +30,8 @@
 
 import crypto from 'node:crypto';
 
+import { fingerprintSeverity } from './severity.js';
+
 const SEP = '␟'; // unit separator — keeps fingerprint fields unambiguous
 const MARKER = 'audit-fingerprints:';
 const SEMANTIC_MARKER = 'audit-semantic-keys:';
@@ -65,6 +67,20 @@ function normaliseLabels(labels) {
 
 /**
  * Compute the stable identity payload for a finding.
+ *
+ * **Severity is projected, not raw (Story #4877).** The severity vocabulary was
+ * normalised onto the canonical five-level scale in the same change that wrote
+ * this comment, and severity is an identity field — so a naive
+ * `normaliseField(finding.severity)` here would have re-minted the fingerprint
+ * of every finding whose spelling the normalisation touched, silently breaking
+ * dedup against every Issue already filed. {@link fingerprintSeverity} is the
+ * projection that makes the hash **invariant** under that normalisation: it
+ * resolves aliases onto their canonical level, keeps an absent severity as the
+ * empty string (what the raw call produced), and passes an unrecognised value
+ * through verbatim. Labels are deliberately left on the raw
+ * lower-case/trim/sort path for the same reason — order- and case-insensitive
+ * already, and any further folding would move existing shas.
+ *
  * @param {object} finding
  * @returns {{ title: string, area: string, primaryFile: string, severity: string, labels: string }}
  */
@@ -73,7 +89,7 @@ function fingerprintComponents(finding) {
     title: normaliseField(finding?.title),
     area: normaliseField(finding?.area),
     primaryFile: normaliseField(finding?.primaryFile),
-    severity: normaliseField(finding?.severity),
+    severity: fingerprintSeverity(finding?.severity),
     labels: normaliseLabels(finding?.labels),
   };
 }
@@ -142,20 +158,18 @@ export function semanticKeyFooter(keys) {
 
 /**
  * Extract semantic keys from an Issue body carrying the semantic-key footer.
- * Internal — the audit filers stamp the footer via {@link semanticKeyFooter};
- * only the confirmation path here reads it back.
+ * The audit filers stamp the footer via {@link semanticKeyFooter}; the
+ * confirmation path here and {@link carryProvenanceFooters} read it back.
  *
  * @param {string} body
  * @returns {string[]}
  */
 function parseSemanticKeyFooter(body) {
-  if (typeof body !== 'string') return [];
-  const match = body.match(/<!--\s*audit-semantic-keys:\s*([^>]*?)\s*-->/);
-  if (!match) return [];
-  return match[1]
-    .split(',')
-    .map((s) => s.trim())
-    .filter((s) => s.length > 0);
+  return parseAllFooterValues(
+    body,
+    /<!--\s*audit-semantic-keys:\s*([^>]*?)\s*-->/g,
+    (s) => s.length > 0,
+  );
 }
 
 /**
@@ -190,13 +204,104 @@ export function fingerprintFooter(shas) {
  * @returns {string[]}
  */
 export function parseFingerprintFooter(body) {
-  if (typeof body !== 'string') return [];
-  const match = body.match(/<!--\s*audit-fingerprints:\s*([^>]+?)\s*-->/);
-  if (!match) return [];
-  return match[1]
-    .split(',')
-    .map((s) => s.trim())
-    .filter((s) => SHA1_RE.test(s));
+  return parseAllFooterValues(
+    body,
+    /<!--\s*audit-fingerprints:\s*([^>]+?)\s*-->/g,
+    (s) => SHA1_RE.test(s),
+  );
+}
+
+/**
+ * Collect the comma-separated values out of **every** occurrence of a footer
+ * marker in `text`, de-duplicated, in first-seen order.
+ *
+ * Scanning every occurrence rather than only the first matters for the
+ * provenance carry (Story #4877): the audit Single-plan seed stamps one footer
+ * pair per MVP Scope bullet, so a multi-group seed carries several. A
+ * first-match-only parse silently dropped every group but the first, which
+ * would have made the carry look wired while leaking most of the provenance.
+ * Reading all footers is also strictly more correct for issue-body confirmation
+ * — a body that accumulated two footer lines confirms against either.
+ *
+ * @param {unknown} text
+ * @param {RegExp} pattern — a global regex whose first capture group is the
+ *   comma-separated value list.
+ * @param {(value: string) => boolean} isValid
+ * @returns {string[]}
+ */
+function parseAllFooterValues(text, pattern, isValid) {
+  if (typeof text !== 'string') return [];
+  const out = [];
+  const seen = new Set();
+  for (const match of text.matchAll(pattern)) {
+    for (const raw of match[1].split(',')) {
+      const value = raw.trim();
+      if (!isValid(value) || seen.has(value)) continue;
+      seen.add(value);
+      out.push(value);
+    }
+  }
+  return out;
+}
+
+/**
+ * Carry audit dedup provenance from a source document into a target body
+ * (Story #4877).
+ *
+ * The audit sweep's Single-plan path emits a `/plan` seed whose MVP Scope
+ * bullets already carry the `audit-fingerprints` / `audit-semantic-keys`
+ * footers (Story #4626). Nothing then copied them into the Story `/plan`
+ * actually persisted, so the recommended path filed Stories that the next
+ * sweep could not recognise and re-filed as new. It was left to the authoring
+ * agent to notice HTML comments in a one-pager and hand-carry them — a
+ * remembered step, which is to say no step at all.
+ *
+ * This is that carry, as a function: harvest both footers out of `from`, and
+ * append whichever provenance `into` is missing. It is deliberately:
+ *
+ * - **Additive.** Shas and keys already present in `into` are never duplicated,
+ *   and a footer `into` already carries is left exactly as authored.
+ * - **Union-preserving.** When both sides carry footers the result carries the
+ *   union, so a hand-authored fingerprint is not dropped in favour of the seed's.
+ * - **Idempotent.** Re-running over its own output is a no-op, so a resumed
+ *   persist cannot stack footers.
+ * - **Silent on nothing-to-do.** No provenance in `from` returns `into`
+ *   unchanged with `carried: false`, so a non-audit plan run is untouched.
+ *
+ * @param {{ from?: string, into?: string }} args — `from` is the provenance
+ *   source (the seed markdown); `into` is the body being persisted.
+ * @returns {{ body: string, carried: boolean, fingerprints: string[], semanticKeys: string[] }}
+ *   `body` is the augmented text; `fingerprints` / `semanticKeys` are the values
+ *   newly carried (empty when there was nothing to carry).
+ */
+export function carryProvenanceFooters({ from = '', into = '' } = {}) {
+  const body = typeof into === 'string' ? into : '';
+  const source = typeof from === 'string' ? from : '';
+
+  const have = new Set(parseFingerprintFooter(body));
+  const haveKeys = new Set(parseSemanticKeyFooter(body));
+  const fingerprints = parseFingerprintFooter(source).filter(
+    (sha) => !have.has(sha),
+  );
+  const semanticKeys = parseSemanticKeyFooter(source).filter(
+    (key) => !haveKeys.has(key),
+  );
+
+  if (fingerprints.length === 0 && semanticKeys.length === 0) {
+    return { body, carried: false, fingerprints: [], semanticKeys: [] };
+  }
+
+  const appended = [];
+  if (fingerprints.length > 0) appended.push(fingerprintFooter(fingerprints));
+  if (semanticKeys.length > 0) appended.push(semanticKeyFooter(semanticKeys));
+
+  const separator = body.length === 0 || body.endsWith('\n') ? '' : '\n';
+  return {
+    body: `${body}${separator}\n${appended.join('\n')}\n`,
+    carried: true,
+    fingerprints,
+    semanticKeys,
+  };
 }
 
 /**
@@ -378,4 +483,5 @@ export const __testing = {
   confirmCandidates,
   decideFromConfirmed,
   issueCarriesSemanticKey,
+  parseSemanticKeyFooter,
 };

package/.agents/scripts/lib/findings/severity.js

@@ -40,10 +40,38 @@ export const SEVERITIES = Object.freeze([
  * malformed input — and because both the classify and promote paths share it,
  * malformed input still fingerprints identically across the two paths.
  */
-export const DEFAULT_SEVERITY = 'info';
+const DEFAULT_SEVERITY = 'info';
 
 const SEVERITY_SET = new Set(SEVERITIES);
 
+/**
+ * Non-canonical spellings that resolve onto a canonical level (Story #4877).
+ *
+ * The vocabulary drifted because four modules each carried their own partial
+ * copy of it: `audit-to-stories/parse-audit-md.js` recognised
+ * `critical|high|medium|mod|moderate|low` and nothing else, `audit-to-stories.js`
+ * ranked `critical|high|medium|low`, and `audit-to-stories/seed-from-findings.js`
+ * ordered the same four. None of them knew `info` — the canonical floor — so an
+ * `Info` / `Informational` finding parsed to `null`, tallied as `unknown`, and
+ * was dropped by EVERY severity-filtered run (including `--severity low`).
+ * Folding the alias table in here makes this module the only place the
+ * vocabulary is written down.
+ *
+ * Keys are already lower-cased and trimmed by {@link normalizeSeverity}.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const SEVERITY_ALIASES = Object.freeze({
+  blocker: 'critical',
+  major: 'high',
+  mod: 'medium',
+  moderate: 'medium',
+  minor: 'low',
+  informational: 'info',
+  nit: 'info',
+  trivial: 'info',
+});
+
 /**
  * Numeric rank for "highest severity wins" comparisons, derived from the
  * canonical order so the ranking has exactly one source. `critical` is the
@@ -74,7 +102,44 @@ export const SEVERITY_RANK = Object.freeze(
 export function normalizeSeverity(value, fallback = DEFAULT_SEVERITY) {
   if (typeof value !== 'string') return fallback;
   const normalized = value.trim().toLowerCase();
-  return SEVERITY_SET.has(normalized) ? normalized : fallback;
+  if (SEVERITY_SET.has(normalized)) return normalized;
+  return SEVERITY_ALIASES[normalized] ?? fallback;
+}
+
+/**
+ * The **identity projection** of a severity, for use inside a finding
+ * fingerprint — and nowhere else (Story #4877).
+ *
+ * `severity` is a `fingerprintFinding` identity field
+ * (`route-finding.js`), so whatever this returns is folded into the sha that
+ * deduplicates findings against already-filed Issues. That makes the severity
+ * pipeline and the severity *identity* two different jobs with two different
+ * failure modes:
+ *
+ * - {@link normalizeSeverity} resolves an absent or unrecognised severity to
+ *   `info` so downstream filtering and tallies have a level to work with.
+ * - This function must NOT. Folding `info` in where the previous
+ *   implementation folded the empty string would re-mint the fingerprint of
+ *   every finding that carries no severity, silently breaking dedup for all of
+ *   them. An absent severity therefore stays the empty string, exactly as the
+ *   raw `String(value).toLowerCase().trim()` it replaces produced.
+ *
+ * What it *does* change is alias resolution: `Informational` and `info` project
+ * onto the same `info`, so the fingerprint is **invariant** under the
+ * normalization this Story introduces — a finding hashes the same whether it is
+ * fingerprinted before or after {@link normalizeSeverity} has run over it. An
+ * unrecognised non-empty value is passed through verbatim rather than collapsed,
+ * again so no already-filed fingerprint moves.
+ *
+ * @param {unknown} value — the raw severity field off a finding.
+ * @returns {string} a canonical level, the empty string when absent, or the
+ *   lower-cased raw value when it is neither canonical nor a known alias.
+ */
+export function fingerprintSeverity(value) {
+  if (typeof value !== 'string') return '';
+  const raw = value.trim().toLowerCase();
+  if (raw.length === 0) return '';
+  return normalizeSeverity(raw, raw);
 }
 
 /**
@@ -99,3 +164,16 @@ export function highestSeverity(values) {
   }
   return best;
 }
+
+/**
+ * Internals reached by the unit tests only. The floor and the alias table are
+ * consumed exclusively by this module's own exported functions, so they are
+ * not public API — but the alias table carries a structural invariant (no
+ * alias shadows a canonical level, every target IS one) that cannot be proven
+ * through `normalizeSeverity` alone, since that function returns a canonical
+ * value by construction.
+ */
+export const __testing = {
+  DEFAULT_SEVERITY,
+  SEVERITY_ALIASES,
+};

package/.agents/scripts/lib/label-constants.js

@@ -111,6 +111,22 @@ export const META_LABELS = {
   CONSUMER_IMPROVEMENT: 'meta::consumer-improvement',
 };
 
+/**
+ * Risk-axis labels. Planning/audit metadata only — `risk::high` carries no
+ * runtime behaviour (the single runtime pause point is `agent::blocked`, see
+ * `.agents/instructions.md` § 1.J); it marks a ticket a human should look at
+ * first. Applied by the audit filer to a Story whose merge contains a Critical
+ * finding.
+ *
+ * Named here because it was a bare `'risk::high'` string literal in
+ * `audit-to-stories/build-story-body.js` and defined by no taxonomy at all —
+ * neither `LABEL_TAXONOMY` nor the audit bootstrap created it, so the audit
+ * filer generated a label the repo did not have (Story #4877).
+ */
+export const RISK_LABELS = {
+  HIGH: 'risk::high',
+};
+
 /**
  * Planning-axis labels (Epic #2880 F7). Currently scoped to the
  * `planning::healthcheck-waived` operator-applied waiver — a historical
@@ -147,6 +163,7 @@ export const PLANNING_HEALTHCHECK_WAIVED = 'planning::healthcheck-waived';
  */
 export const LABEL_COLORS = {
   TYPE: '#7057FF',
+  RISK_HIGH: '#B60205',
   AGENT: '#0E8A16',
   STATUS_BLOCKED: '#D93F0B',
   ACCEPTANCE: '#FBCA04',