mandrel 2.23.0 → 2.25.0

package/.agents/scripts/deliver-light.js

@@ -61,10 +61,10 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
-import { computeChangeSet } from './lib/orchestration/change-set.js';
+import { resolveBackstopOutcome } from './lib/orchestration/light-backstop.js';
+import { recordGateRefusal } from './lib/orchestration/light-escalation.js';
 import {
   buildReceiptStoryTicket,
-  checkLightDiffBackstop,
   deriveLightSuitability,
   resolveLightGateOutcome,
 } from './lib/orchestration/light-suitability.js';
@@ -121,7 +121,11 @@ Gate options:
                      envelope and ENDS the session (no prompt, no fallback).
 
 Backstop options:
-  --backstop         Re-check the ACTUAL diff after implementation.
+  --backstop         Re-check the ACTUAL diff after implementation. Bounds the
+                     change's IMPLEMENTATION half by magnitude (changed lines +
+                     file sprawl); test/doc/baseline companions are exempt from
+                     the counts but still matched for sensitive paths. A block
+                     emits a nextCommand recycling the receipt through /plan.
   --story <id>       Story issue number whose story-<id> branch to diff.
 
   --pretty           Pretty-print the JSON envelope.
@@ -130,8 +134,6 @@ Backstop options:
 
 /** Exit code when the gate did not resolve to proceed-light. */
 const EXIT_NOT_PROCEED = 2;
-/** Exit code when the diff backstop blocked the land. */
-const EXIT_BACKSTOP_BLOCKED = 3;
 
 /**
  * Split a comma-separated path list into trimmed, non-empty entries.
@@ -292,33 +294,6 @@ export function buildNextCommands(storyId) {
   };
 }
 
-/**
- * Run the diff backstop against a Story branch's actual change set.
- *
- * @param {{
- *   storyId: number,
- *   baseRef?: string,
- *   cwd?: string,
- *   computeFn?: typeof computeChangeSet,
- *   injectedRules?: object,
- * }} args
- * @returns {ReturnType<typeof checkLightDiffBackstop>}
- */
-export function runDiffBackstop({
-  storyId,
-  baseRef = 'main',
-  cwd = process.cwd(),
-  computeFn = computeChangeSet,
-  injectedRules,
-} = {}) {
-  const { files } = computeFn({
-    baseRef,
-    headRef: `story-${storyId}`,
-    cwd,
-  });
-  return checkLightDiffBackstop({ changedFiles: files, injectedRules });
-}
-
 /**
  * Was a non-blank `--operator-proceed-light` supplied? The gate core decides
  * whether it *applies*; this only asks whether the operator typed one, so the
@@ -348,27 +323,27 @@ function emit(envelope, pretty) {
 }
 
 /**
- * Backstop mode — re-check the actual diff.
+ * Backstop mode — re-check the actual diff. The decision lives in
+ * {@link module:lib/orchestration/light-backstop}; this branches and prints.
  *
- * @param {{ story?: string, pretty: boolean }} values
+ * @param {object} values Parsed CLI values.
+ * @param {{ resolveFn?: typeof resolveBackstopOutcome }} [deps]
  * @returns {Promise<number>}
  */
-async function runBackstopMode(values) {
+async function runBackstopMode(values, deps = {}) {
+  const { resolveFn = resolveBackstopOutcome } = deps;
   const storyId = Number.parseInt(String(values.story ?? ''), 10);
   if (!Number.isInteger(storyId) || storyId <= 0) {
     process.stderr.write(HELP);
     throw new Error('[deliver-light] --backstop requires --story <id>');
   }
-  const result = runDiffBackstop({ storyId });
-  emit({ mode: 'backstop', storyId, ...result }, values.pretty);
-  if (result.blocked) {
-    Logger.warn(
-      `[deliver-light] diff backstop BLOCKED Story #${storyId}: ${result.reasons.join('; ')}`,
-    );
-    return EXIT_BACKSTOP_BLOCKED;
-  }
-  Logger.info(`[deliver-light] diff backstop clean for Story #${storyId}.`);
-  return 0;
+  const { result, nextCommand, preservation, exitCode, message } =
+    await resolveFn({ storyId });
+  const extra = nextCommand === null ? {} : { nextCommand, preservation };
+  emit({ mode: 'backstop', storyId, ...result, ...extra }, values.pretty);
+  if (result.blocked) Logger.warn(message);
+  else Logger.info(message);
+  return exitCode;
 }
 
 /**
@@ -407,6 +382,7 @@ export async function runGateMode(values, deps = {}) {
     createReceiptFn = createLightReceipt,
     emitFn = emit,
     emitTerminalFn = emitTerminalEnvelope,
+    recordRefusalFn = recordGateRefusal,
   } = deps;
 
   if (!values.prompt || String(values.prompt).trim() === '') {
@@ -457,6 +433,7 @@ export async function runGateMode(values, deps = {}) {
       { mode: 'gate', action: gate.action, outcome: gate.outcome },
       values.pretty,
     );
+    await recordRefusalFn({ gate, amends: values.amends });
     Logger.warn(
       `[deliver-light] gate did not proceed light (${gate.action}): ${gate.outcome.reasons.join('; ')}`,
     );

package/.agents/scripts/deliver-recover.js

@@ -16,6 +16,14 @@
  * `single-story-init.js` hard-errors on an already-closed Story. Before this
  * surface, that Story had no automated way back.
  *
+ * Every command it prints **resumes** — it re-enters the in-flight worker or
+ * close, or closes the branch that is already pushed. None of them re-dispatch
+ * the Story, and that is deliberate: since Story #4876 the close-and-land tail
+ * belongs to the dispatching orchestrator, so a worker returning without a
+ * terminal envelope is the expected shape rather than evidence the Story never
+ * ran. Answering it with a fresh dispatch re-runs `single-story-init.js`
+ * underneath live work and puts a second close on one PR.
+ *
  * Usage:
  *   node .agents/scripts/deliver-recover.js --story <STORY_ID> [--cwd <main-repo>]
  *                                           [--json]
@@ -46,6 +54,11 @@ Probes a Story's live delivery state — labels, lease, branch, worktree, PR
 state and checks — and prints the single next command that resumes it, with
 the evidence it was derived from. Read-only: mutates nothing.
 
+The command always resumes the existing worker or close (or closes an already
+pushed branch); it never re-dispatches the Story, which would re-run init
+underneath live work. A worker that returned no terminal envelope is expected —
+the orchestrator owns the close-and-land tail.
+
 Mid-flight shapes (executing-*/closing-*) get a stability re-probe after a
 short settle window: matching shapes return the fresher verdict; diverging
 shapes report \`in-transition\` (a live delivery process is mutating the

package/.agents/scripts/lib/audit-suite/lens-diff-floor.js

@@ -28,6 +28,7 @@
  */
 
 import { gitSpawn } from '../git-utils.js';
+import { readNumstatRows } from '../orchestration/diff-magnitude.js';
 import { selectSensitivePathClasses } from './selector.js';
 
 /**
@@ -58,6 +59,12 @@ export function resolveLensDiffFloor(config) {
  * Count the changed lines (additions + deletions) in the
  * `baseRef...headRef` diff via `git diff --numstat`.
  *
+ * The read and the parse are shared with the light path's magnitude backstop
+ * ({@link module:lib/orchestration/diff-magnitude.readNumstatRows}) so the two
+ * cannot disagree about how a diff is measured. This one keeps a whole-diff
+ * total: the lens floor asks "is this diff small", not "is its implementation
+ * half small", so it deliberately does **not** apply the companion exemption.
+ *
  * Total — never throws. Returns `null` (the neutral "count unknown" signal
  * the floor fails open on) for any git failure or unparseable output, and
  * `0` for a genuinely empty diff. Binary rows (`-\t-\tpath`) contribute 0
@@ -77,31 +84,9 @@ export function countChangedLines({
   cwd = process.cwd(),
   gitSpawnFn = gitSpawn,
 } = {}) {
-  if (typeof baseRef !== 'string' || baseRef.length === 0) return null;
-  if (typeof headRef !== 'string' || headRef.length === 0) return null;
-  try {
-    const result = gitSpawnFn(
-      cwd,
-      'diff',
-      '--numstat',
-      `${baseRef}...${headRef}`,
-    );
-    if (!result || result.status !== 0 || typeof result.stdout !== 'string') {
-      return null;
-    }
-    let total = 0;
-    for (const line of result.stdout.split('\n')) {
-      const trimmedEnd = line.replace(/\s+$/, '');
-      if (trimmedEnd.length === 0) continue;
-      const match = /^(\d+|-)\t(\d+|-)\t/.exec(trimmedEnd);
-      if (!match) return null; // Unexpected format — the count is not trustworthy.
-      if (match[1] !== '-') total += Number(match[1]);
-      if (match[2] !== '-') total += Number(match[2]);
-    }
-    return total;
-  } catch {
-    return null;
-  }
+  const rows = readNumstatRows({ baseRef, headRef, cwd, gitSpawnFn });
+  if (rows === null) return null;
+  return rows.reduce((total, row) => total + row.additions + row.deletions, 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;
   }