mandrel 2.24.0 → 2.25.0

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/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;
   }