mandrel 2.24.0 → 2.26.0

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

@@ -0,0 +1,193 @@
+/**
+ * weights.js — the three ranking multipliers, and their degradations
+ * (Story #4902).
+ *
+ * A hotspot's severity says how bad the code measures. These three say how
+ * much that badness costs: how often the file changes (churn), how much of
+ * the repository depends on it (import in-degree), and how often agents have
+ * actually tripped over it (friction signals).
+ *
+ * All three are **optional inputs**. A shallow clone has no git history, a
+ * fresh checkout has no friction ledger, and a consumer whose sources live
+ * outside the scanned roots has no resolvable import graph. Each degrades to
+ * a neutral multiplier of exactly 1.0 — never 0 (which would erase the
+ * hotspot) and never a guess. The engine exits 0 in every degraded case.
+ *
+ * @module lib/audit-baselines/weights
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { computeInDegree, resolveRepoGraph } from '../import-graph.js';
+
+/** Neutral multiplier every degraded weight collapses to. */
+const NEUTRAL_WEIGHT = 1.0;
+
+/**
+ * Saturating count → multiplier in `[1, 2)`. Zero observations gives exactly
+ * `NEUTRAL_WEIGHT`, so "no signal" and "signal says nothing notable" are the
+ * same number — the degradation is indistinguishable from an honest zero,
+ * which is the point: neither should move the ranking.
+ *
+ * @param {number} count
+ * @param {number} half count at which the multiplier reaches 1.5
+ * @returns {number}
+ */
+function saturate(count, half) {
+  if (!Number.isFinite(count) || count <= 0) return NEUTRAL_WEIGHT;
+  return NEUTRAL_WEIGHT + count / (count + half);
+}
+
+/**
+ * Count commits touching each file in the recent history window.
+ *
+ * @param {{ cwd: string, windowDays?: number, run?: Function }} args
+ * @returns {{ counts: Map<string, number>, degraded: boolean }}
+ *   `degraded` is true when git could not answer at all — not a git work
+ *   tree, no commits yet, or the binary is unavailable.
+ */
+export function readChurn({ cwd, windowDays = 180, run = execFileSync }) {
+  let stdout;
+  try {
+    stdout = run(
+      'git',
+      [
+        'log',
+        `--since=${windowDays}.days.ago`,
+        '--name-only',
+        '--pretty=format:',
+        '--no-renames',
+      ],
+      {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        // git narrates "not a git repository" on stderr; the degradation is
+        // reported in the envelope, not shouted at the operator.
+        stdio: ['ignore', 'pipe', 'ignore'],
+      },
+    );
+  } catch {
+    return { counts: new Map(), degraded: true };
+  }
+  const counts = new Map();
+  for (const line of String(stdout).split('\n')) {
+    const file = line.trim();
+    if (file.length === 0) continue;
+    counts.set(file, (counts.get(file) ?? 0) + 1);
+  }
+  return { counts, degraded: false };
+}
+
+/**
+ * Import in-degree per module, keyed by repo-relative posix path.
+ *
+ * @param {{ cwd: string, graph?: Map<string, string[]> | null }} args
+ * @returns {{ degrees: Map<string, number>, degraded: boolean }}
+ */
+export function readCentrality({ cwd, graph }) {
+  const resolved = graph === undefined ? resolveRepoGraph(cwd) : graph;
+  if (!resolved) return { degrees: new Map(), degraded: true };
+  return { degrees: computeInDegree(resolved), degraded: false };
+}
+
+/** Path tokens that look like repository files, harvested from signal text. */
+const PATH_TOKEN_RE = /[\w@][\w./@-]*\.(?:js|mjs|cjs|ts|tsx|json|md)\b/g;
+
+/**
+ * Collect every `signals.ndjson` under `tempRoot`. Absent tree → empty list.
+ *
+ * @param {string} tempRootAbs
+ * @returns {string[]} absolute paths
+ */
+function findSignalStreams(tempRootAbs) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(child, depth + 1);
+      else if (entry.name === 'signals.ndjson') out.push(child);
+    }
+  };
+  walk(tempRootAbs, 0);
+  return out.sort();
+}
+
+/**
+ * Count friction signals blaming each file.
+ *
+ * Signal records carry no dedicated path field — the blamed file surfaces
+ * inside free-form `details` / `emitter.command` text — so paths are
+ * harvested by token scan over each record's serialized form. A malformed
+ * line is skipped, never fatal.
+ *
+ * @param {{ tempRootAbs: string, kinds?: Set<string> }} args
+ * @returns {{ counts: Map<string, number>, degraded: boolean, streams: number }}
+ */
+export function readFriction({
+  tempRootAbs,
+  kinds = new Set(['friction', 'hotspot', 'rework', 'churn', 'retry']),
+}) {
+  const streams = findSignalStreams(tempRootAbs);
+  if (streams.length === 0) {
+    return { counts: new Map(), degraded: true, streams: 0 };
+  }
+  const counts = new Map();
+  for (const stream of streams) {
+    let raw;
+    try {
+      raw = fs.readFileSync(stream, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of raw.split('\n')) {
+      if (line.trim().length === 0) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!kinds.has(record?.kind)) continue;
+      const text =
+        JSON.stringify(record.details ?? {}) + (record?.emitter?.command ?? '');
+      for (const token of text.match(PATH_TOKEN_RE) ?? []) {
+        counts.set(token, (counts.get(token) ?? 0) + 1);
+      }
+    }
+  }
+  return { counts, degraded: false, streams: streams.length };
+}
+
+/**
+ * Bundle the three weight lookups into one resolver the hotspot builder can
+ * call per cluster id, plus the degradation flags the envelope reports.
+ *
+ * @param {{
+ *   churn: { counts: Map<string, number>, degraded: boolean },
+ *   centrality: { degrees: Map<string, number>, degraded: boolean },
+ *   friction: { counts: Map<string, number>, degraded: boolean },
+ * }} sources
+ * @returns {(id: string) => { churnWeight: number, centralityWeight: number, frictionWeight: number }}
+ */
+export function makeWeightResolver({ churn, centrality, friction }) {
+  return (id) => ({
+    churnWeight: churn.degraded
+      ? NEUTRAL_WEIGHT
+      : saturate(churn.counts.get(id) ?? 0, 12),
+    centralityWeight: centrality.degraded
+      ? NEUTRAL_WEIGHT
+      : saturate(centrality.degrees.get(id) ?? 0, 8),
+    frictionWeight: friction.degraded
+      ? NEUTRAL_WEIGHT
+      : saturate(friction.counts.get(id) ?? 0, 4),
+  });
+}

package/.agents/scripts/lib/audit-suite/index.js

@@ -27,15 +27,10 @@ export {
 } from './lens-diff-floor.js';
 export { runAuditSuite } from './runner.js';
 export {
-  GLOBAL_LENS_ALLOWLIST,
-  isGlobalLens,
   LENS_TIERS,
   matchesAnyFilePattern,
   matchesFilePattern,
-  NAVIGABILITY_LENS,
   resolveLensTier,
-  resolveNavigabilityRouteGlobs,
-  routesNavigabilityLens,
   selectAudits,
   selectLocalLenses,
 } from './selector.js';

package/.agents/scripts/lib/audit-suite/selector.js

@@ -30,42 +30,6 @@ import { readAuditRulesSync } from './audit-rules-reader.js';
 
 const DEFAULT_GIT_TIMEOUT_MS = 30000;
 
-/**
- * The audit-lens identifier for the navigability lens (Epic #4131, F2/F3).
- * Authored as `.agents/workflows/audit-navigability.md`; registered here so the
- * roster, the global-lens allowlist, and the route-added routing seam all
- * reference one symbol rather than a hard-coded string.
- */
-export const NAVIGABILITY_LENS = 'audit-navigability';
-
-/**
- * The **global-lens allowlist** — lenses that evaluate a property of the
- * **whole** product (not just the Epic's change set) and are therefore exempt
- * from the cross-epic-leak guard (`#3362`) that narrows every other lens's
- * evidence to the Epic's `changedFiles`. A lens in this set still runs through
- * the SAME `runAuditSuite` / `selectAuditStrategy` engine; only the
- * change-set narrowing is bypassed, and only for the listed lenses. The guard
- * is **not** weakened for any lens absent from this set.
- *
- * Navigability is the founding member: reachability is a global property — a
- * change can orphan a route it never touched — so the lens must read the whole
- * route tree + nav registry regardless of which file triggered it.
- */
-export const GLOBAL_LENS_ALLOWLIST = Object.freeze([NAVIGABILITY_LENS]);
-
-/**
- * True when `lens` is on the global-lens allowlist and is therefore exempt
- * from the cross-epic-leak guard's change-set narrowing. Pure; the single
- * read-side of {@link GLOBAL_LENS_ALLOWLIST} so callers never hard-code the
- * membership test.
- *
- * @param {string} lens
- * @returns {boolean}
- */
-export function isGlobalLens(lens) {
-  return GLOBAL_LENS_ALLOWLIST.includes(lens);
-}
-
 /**
  * The canonical concern-ownership tiers a lens can declare via its
  * `scope` field in [`audit-rules.json`](../../../schemas/audit-rules.json).
@@ -222,40 +186,23 @@ export function selectSensitivePathClasses({
 /**
  * Resolve the consumer's navigability route globs from the resolved config.
  * Reads `delivery.quality.navigability.routeGlobs` — the route-tree SSOT the
- * navigability lens enumerates and the route-added routing predicate matches
- * against. Returns an empty array when the block (or any ancestor) is absent,
- * so an unconfigured consumer routes nothing and the lens degrades to a silent
- * no-op (Epic #4131 — "no-op when unconfigured").
+ * navigability lens enumerates. Returns an empty array when the block (or any
+ * ancestor) is absent, so an unconfigured consumer contributes no web-surface
+ * evidence (Epic #4131 — "no-op when unconfigured").
+ *
+ * Module-local: the sole reader is {@link hasWebSurface}. It was previously
+ * exported alongside a route-added routing seam that Story #4926 removed —
+ * lens routing is decided by the `scope` field in `audit-rules.json`, never by
+ * a second predicate here.
  *
  * @param {object|null|undefined} config Resolved `.agentrc.json` wrapper.
  * @returns {string[]} Route globs, or `[]` when unconfigured.
  */
-export function resolveNavigabilityRouteGlobs(config) {
+function resolveNavigabilityRouteGlobs(config) {
   const globs = config?.delivery?.quality?.navigability?.routeGlobs;
   return Array.isArray(globs) ? globs.filter((g) => typeof g === 'string') : [];
 }
 
-/**
- * Decide whether a change set routes the navigability lens. The lens is routed
- * when any `changedFiles` entry matches a consumer-configured route glob
- * (`delivery.quality.navigability.routeGlobs`) — i.e. the change set adds or
- * touches a route file. When no route globs are configured, this returns
- * `false` (the unconfigured no-op), so the existing change-set-scoped lens
- * selection is unchanged.
- *
- * A pure predicate over a change set — the same input {@link selectAudits} and
- * {@link selectLocalLenses} already match against. The caller unions its result
- * into the lens roster it is assembling; no new routing machinery is added.
- *
- * @param {{ changedFiles?: string[], config?: object|null }} params
- * @returns {boolean}
- */
-export function routesNavigabilityLens({ changedFiles, config } = {}) {
-  const globs = resolveNavigabilityRouteGlobs(config);
-  if (globs.length === 0) return false;
-  return matchesAnyFilePattern(globs, changedFiles ?? []);
-}
-
 /**
  * Package names (or scope/name segments of them) that declare a **web
  * rendering surface**. Matched against the consumer's root `package.json`

package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js

@@ -0,0 +1,177 @@
+/**
+ * lib/audit-to-stories/audit-label-taxonomy.js — the closed set of GitHub
+ * labels an audit sweep may create or generate (Story #4877).
+ *
+ * There are two sides to a label axis and they used to be written down in
+ * different places, which is how they drifted:
+ *
+ *   - the **creator** — `audit-labels-bootstrap.js`, which ran `gh label create`
+ *     over the `audit::<lens>` list and nothing else;
+ *   - the **generator** — `audit-to-stories/build-story-body.js`, which emitted
+ *     `type::story`, `agent::ready`, `audit::<lens>` and — as a bare string
+ *     literal — `risk::high`.
+ *
+ * `risk::high` was therefore generated by the filer and defined by **no**
+ * taxonomy: not `LABEL_TAXONOMY` (the repo-wide bootstrap), not the audit
+ * bootstrap. A generated label the repository has never created is the exact
+ * failure shape that made every `gh issue create` in the feedback loop fail in
+ * Story #4828. This module is the one list both sides read, so the creator
+ * cannot fall behind the generator again.
+ *
+ * It lives under `lib/` rather than inside the bootstrap CLI so the generator
+ * can import it without a lib → top-level-script edge (and without dragging the
+ * CLI's config/`gh` dependencies into a pure body builder).
+ *
+ * Label *names* come from `lib/label-constants.js` — the repo-wide SSOT for
+ * label spelling — so a rename still lands in one place.
+ */
+
+import {
+  AGENT_LABELS,
+  LABEL_COLORS,
+  RISK_LABELS,
+  TYPE_LABELS,
+} from '../label-constants.js';
+import { AUDIT_LENSES } from './audit-lenses.js';
+
+/**
+ * Per-lens label presentation, keyed by canonical lens name. A lens absent from
+ * this map falls back to {@link DEFAULT_LENS_META}, so adding an `audit-*`
+ * workflow to `AUDIT_LENSES` still yields a label without registering
+ * 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',
+});
+
+/** `gh label create --color` wants a bare hex triplet, not a CSS `#rrggbb`. */
+function hex(color) {
+  return String(color).replace('#', '');
+}
+
+/**
+ * The `audit::<lens>` half of the taxonomy, one per `/audit-<lens>` workflow.
+ * Derived from the same `AUDIT_LENSES` SSOT that `build-story-body.js` derives
+ * its labels from, so the creator and the deriver cannot drift (Story #4195).
+ */
+const AUDIT_LENS_LABELS = Object.freeze(
+  AUDIT_LENSES.map((name) => ({
+    name: `audit::${name}`,
+    ...(LENS_META[name] ?? DEFAULT_LENS_META),
+  })),
+);
+
+/**
+ * The story-axis labels an audit-generated Story carries alongside its
+ * `audit::<lens>` labels.
+ *
+ * The `type::` / `agent::` entries are also in `LABEL_TAXONOMY` (the repo-wide
+ * bootstrap). Creating a label twice is a no-op, so the overlap costs nothing
+ * and means an audit sweep does not silently depend on the repo-wide bootstrap
+ * having run first.
+ */
+const AUDIT_STORY_AXIS_LABELS = Object.freeze([
+  {
+    name: TYPE_LABELS.STORY,
+    color: hex(LABEL_COLORS.TYPE),
+    description: 'Story work item',
+  },
+  {
+    name: AGENT_LABELS.READY,
+    color: hex(LABEL_COLORS.AGENT),
+    description:
+      'Parking state — frozen dispatch manifest exists; awaiting local /deliver',
+  },
+  {
+    name: RISK_LABELS.HIGH,
+    color: hex(LABEL_COLORS.RISK_HIGH),
+    description:
+      'Planning/audit metadata: review this first (Critical finding present)',
+  },
+]);
+
+/**
+ * Every label the audit sweep defines — the closed set the bootstrap creates
+ * and {@link definesAuditLabel} answers against.
+ */
+export const AUDIT_LABEL_TAXONOMY = Object.freeze([
+  ...AUDIT_LENS_LABELS,
+  ...AUDIT_STORY_AXIS_LABELS,
+]);
+
+const DEFINED_NAMES = new Set(AUDIT_LABEL_TAXONOMY.map((l) => l.name));
+
+/**
+ * True when `name` is a label this taxonomy defines.
+ *
+ * The enforcement point is the label **generator** (`build-story-body.js`),
+ * which routes every label it derives through this predicate and refuses to
+ * emit one the taxonomy does not define — closing the drift in the direction it
+ * actually happened: a generator inventing names the bootstrap never created.
+ *
+ * @param {unknown} name
+ * @returns {boolean}
+ */
+export function definesAuditLabel(name) {
+  return typeof name === 'string' && DEFINED_NAMES.has(name);
+}

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

@@ -27,6 +27,7 @@
 export const AUDIT_LENSES = Object.freeze([
   'accessibility',
   'architecture',
+  'baselines',
   'clean-code',
   'data-model',
   'dependencies',

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -22,14 +22,16 @@
  * structured contract.
  */
 
+import { AGENT_LABELS, RISK_LABELS, TYPE_LABELS } from '../label-constants.js';
 import { serialize } from '../story-body/story-body.js';
+import { definesAuditLabel } from './audit-label-taxonomy.js';
 import { auditLabelsForFindings } from './audit-lenses.js';
 import {
   renderFingerprintFooter,
   renderSemanticKeyFooter,
 } from './finding-adapter.js';
 
-const STATIC_LABELS = Object.freeze(['type::story', 'agent::ready']);
+const STATIC_LABELS = Object.freeze([TYPE_LABELS.STORY, AGENT_LABELS.READY]);
 
 // The verify[] contract every generated audit Story carries. These commands
 // exist in this repo's harness (package.json scripts) so the Story satisfies
@@ -183,8 +185,38 @@ function labelsForGroup(group) {
   const hasCritical = (group.findings ?? []).some(
     (f) => f.severity === 'critical',
   );
-  if (hasCritical) labels.push('risk::high');
-  return uniq(labels);
+  if (hasCritical) labels.push(RISK_LABELS.HIGH);
+  return assertLabelsInTaxonomy(uniq(labels));
+}
+
+/**
+ * Refuse to generate a label the audit bootstrap taxonomy does not define
+ * (Story #4877).
+ *
+ * Story #4195 fixed half of this: `audit::<dimension>` labels minted from
+ * free-form dimension prose ("stale-description", "dry") named labels that did
+ * not exist, so derivation moved to the closed lens list. The other half stayed
+ * open — `risk::high` was a bare string literal here, defined by no taxonomy —
+ * and nothing checked the generated set against anything at all. Throwing is
+ * deliberate: a label the repo has never created is dropped or fails the create
+ * outright, and a filer that silently loses `risk::high` on a Critical merge is
+ * worse than a loud failure at the point of generation.
+ *
+ * @param {string[]} labels
+ * @returns {string[]} the same labels, when every one is defined.
+ * @throws {Error} naming the offending labels.
+ */
+function assertLabelsInTaxonomy(labels) {
+  const undefinedLabels = labels.filter((l) => !definesAuditLabel(l));
+  if (undefinedLabels.length > 0) {
+    throw new Error(
+      `buildStoryBody: generated label(s) ${undefinedLabels.join(', ')} are not ` +
+        'defined by the audit label taxonomy (audit-label-taxonomy.js). Add ' +
+        'them there — or stop generating them — rather than emitting a label ' +
+        'the repository does not have.',
+    );
+  }
+  return labels;
 }
 
 /**

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

@@ -21,7 +21,7 @@
  * Pure: no I/O.
  */
 
-const SEVERITY_RANK = { critical: 3, high: 2, medium: 1, low: 0, null: -1 };
+import { highestSeverity as highestSeverityOf } from '../findings/severity.js';
 
 function dirOf(filePath) {
   if (typeof filePath !== 'string' || filePath.length === 0) return '';
@@ -37,17 +37,26 @@ function pickPrimaryFile(finding) {
   return null;
 }
 
+/**
+ * The highest severity across a group's findings, ranked by the severity SSOT
+ * ({@link highestSeverityOf}) rather than a local copy of the scale.
+ *
+ * The rank map this replaces knew four levels and not `info`, so an Info
+ * finding tied with a finding carrying no severity at all — the same partial
+ * vocabulary this Story removes everywhere else.
+ *
+ * A group whose findings all lack a usable severity still reports `null`, not
+ * the SSOT's `info` floor: absent is not the same claim as "graded lowest",
+ * and the callers that tally and threshold on this value distinguish them.
+ *
+ * @param {Array<{ severity?: string }>} findings
+ * @returns {string|null} a canonical severity, or null when none is stated.
+ */
 function highestSeverity(findings) {
-  let best = null;
-  let bestRank = -2;
-  for (const f of findings) {
-    const r = SEVERITY_RANK[f.severity ?? 'null'] ?? -1;
-    if (r > bestRank) {
-      bestRank = r;
-      best = f.severity ?? null;
-    }
-  }
-  return best;
+  const stated = findings
+    .map((f) => f?.severity)
+    .filter((value) => typeof value === 'string' && value.length > 0);
+  return stated.length === 0 ? null : highestSeverityOf(stated);
 }
 
 /**

package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js

@@ -17,14 +17,7 @@
 
 import path from 'node:path';
 
-const SEVERITY_ALIASES = Object.freeze({
-  critical: 'critical',
-  high: 'high',
-  medium: 'medium',
-  mod: 'medium',
-  moderate: 'medium',
-  low: 'low',
-});
+import { normalizeSeverity } from '../findings/severity.js';
 
 const KEY_LINE = /^\s*-\s*\*\*([^:*]+):\*\*\s*(.*)$/;
 const HEADING_FINDING = /^###\s+(.+?)\s*$/;
@@ -44,6 +37,27 @@ function unwrapInlineCode(value) {
   return trimmed;
 }
 
+/**
+ * Resolve a raw severity/impact token to a canonical level, or `null` when the
+ * token carries no recognisable severity at all.
+ *
+ * The vocabulary itself is NOT written down here (Story #4877). This module used
+ * to carry its own alias table covering `critical|high|medium|mod|moderate|low`
+ * — four of the canonical five levels, missing `info`. A lens that graded a
+ * finding `Info` or `Informational` (which the shared severity scale now
+ * sanctions) therefore parsed to `null`, tallied as `unknown`, and was dropped
+ * by every severity-filtered run, `--severity low` included. Delegating to the
+ * canonical normaliser in `lib/findings/severity.js` means this parser cannot
+ * know a narrower vocabulary than the rest of the pipeline.
+ *
+ * `null` — rather than the normaliser's `info` fallback — remains the
+ * no-severity answer, because {@link deriveSeverity} walks several candidate
+ * keys and needs to distinguish "this key had no severity" from "this key said
+ * `info`".
+ *
+ * @param {unknown} token
+ * @returns {string|null}
+ */
 function normaliseSeverity(token) {
   if (typeof token !== 'string') return null;
   const cleaned = token
@@ -53,7 +67,7 @@ function normaliseSeverity(token) {
     .trim();
   if (!cleaned) return null;
   for (const word of cleaned.split(/[\s|/,]+/)) {
-    const hit = SEVERITY_ALIASES[word];
+    const hit = normalizeSeverity(word, null);
     if (hit) return hit;
   }
   return null;

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

@@ -17,6 +17,7 @@
  * Pure: returns a string. The caller decides where to persist it.
  */
 
+import { SEVERITIES } from '../findings/severity.js';
 import {
   renderFingerprintFooter,
   renderSemanticKeyFooter,
@@ -37,10 +38,16 @@ const DIMENSION_LABEL = {
   architecture: 'Architecture',
 };
 
-const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low'];
+/**
+ * The severity profile in the seed's Problem Statement is ordered and bucketed
+ * by the canonical scale (Story #4877) rather than by a fourth local copy of
+ * it. The list this replaces omitted `info`, so an informational finding was
+ * absent from the profile the planner reads even when it survived the filter.
+ */
+const SEVERITY_ORDER = SEVERITIES;
 
 function tallySeverities(findings) {
-  const tally = { critical: 0, high: 0, medium: 0, low: 0 };
+  const tally = Object.fromEntries(SEVERITIES.map((s) => [s, 0]));
   for (const f of findings) {
     if (Object.hasOwn(tally, f.severity)) tally[f.severity] += 1;
   }