mandrel 2.24.0 → 2.26.0

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/git-utils.js

@@ -40,6 +40,23 @@ import { execFileSync, spawnSync } from 'node:child_process';
  * @property {string} stderr - Trimmed stderr.
  */
 
+/**
+ * Explicit stdout ceiling for every git invocation in this module.
+ *
+ * Both child-process runners default `maxBuffer` to 1 MB, at which point the
+ * child is killed and the call fails with `ENOBUFS` for a reason unrelated to
+ * git. The push path is the sharp edge: `git push` relays the whole `pre-push`
+ * hook output, which is unbounded by design — this repo's hook emits a full
+ * `check-baselines` envelope, measured at 2,166,643 bytes, so every Story
+ * close failed at `phase: push` once hooks became reachable inside worktrees.
+ *
+ * 64 MB is the bound Story #4914 already set on `baselines/git-base.js` for
+ * the identical failure, matching `run-test-profile.js`,
+ * `audit-baselines/trend.js` and `audit-baselines/weights.js`. This module was
+ * missed by that sweep.
+ */
+const MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
 let _execFileSync = execFileSync;
 let _spawnSync = spawnSync;
 
@@ -108,38 +125,44 @@ export function __setGitRunners(exec, spawn) {
 }
 
 /**
- * Run a git command synchronously, returning trimmed stdout.
- * Throws an Error if the command exits with a non-zero code.
+ * The **single** throwing git runner. Both the module-level {@link gitSync} and
+ * the interface returned by {@link createGitInterface} route through this —
+ * they differ only in which `execFileSync` they hand it.
  *
- * @param {string}   cwd  - Working directory for the git process.
- * @param {...string} args - Git sub-command and arguments.
+ * @param {typeof execFileSync} exec
+ * @param {string} cwd
+ * @param {string[]} args
  * @returns {string} Trimmed stdout text.
  */
-export function gitSync(cwd, ...args) {
-  return _execFileSync('git', args, {
+function runGitSync(exec, cwd, args) {
+  return exec('git', args, {
     cwd,
     encoding: 'utf8',
     stdio: ['pipe', 'pipe', 'pipe'],
     shell: false,
     env: cleanGitEnv(),
+    maxBuffer: MAX_BUFFER_BYTES,
   }).trim();
 }
 
 /**
- * Run a git command synchronously, returning a result object.
- * Never throws — callers must inspect `status` to detect failure.
+ * The **single** non-throwing git runner — the `spawnSync` counterpart of
+ * {@link runGitSync}, normalising `status`/stdout/stderr into a
+ * {@link GitResult}.
  *
- * @param {string}   cwd  - Working directory for the git process.
- * @param {...string} args - Git sub-command and arguments.
+ * @param {typeof spawnSync} spawn
+ * @param {string} cwd
+ * @param {string[]} args
  * @returns {GitResult}
  */
-export function gitSpawn(cwd, ...args) {
-  const result = _spawnSync('git', args, {
+function runGitSpawn(spawn, cwd, args) {
+  const result = spawn('git', args, {
     cwd,
     stdio: 'pipe',
     encoding: 'utf-8',
     shell: false,
     env: cleanGitEnv(),
+    maxBuffer: MAX_BUFFER_BYTES,
   });
   return {
     status: result.status ?? 1,
@@ -148,6 +171,30 @@ export function gitSpawn(cwd, ...args) {
   };
 }
 
+/**
+ * Run a git command synchronously, returning trimmed stdout.
+ * Throws an Error if the command exits with a non-zero code.
+ *
+ * @param {string}   cwd  - Working directory for the git process.
+ * @param {...string} args - Git sub-command and arguments.
+ * @returns {string} Trimmed stdout text.
+ */
+export function gitSync(cwd, ...args) {
+  return runGitSync(_execFileSync, cwd, args);
+}
+
+/**
+ * Run a git command synchronously, returning a result object.
+ * Never throws — callers must inspect `status` to detect failure.
+ *
+ * @param {string}   cwd  - Working directory for the git process.
+ * @param {...string} args - Git sub-command and arguments.
+ * @returns {GitResult}
+ */
+export function gitSpawn(cwd, ...args) {
+  return runGitSpawn(_spawnSync, cwd, args);
+}
+
 /**
  * Build a git interface closed over injected child-process runners. Preferred
  * seam for callers that want explicit injection without touching the
@@ -165,57 +212,25 @@ export function gitSpawn(cwd, ...args) {
 export function createGitInterface(deps = {}) {
   const exec = deps.exec ?? execFileSync;
   const spawn = deps.spawn ?? spawnSync;
-  const sleep =
-    deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep = deps.sleep ?? defaultSleep;
   const jitterFactor = deps.jitter ?? 0.5;
 
-  const gitSync = (cwd, ...args) =>
-    exec('git', args, {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      shell: false,
-      env: cleanGitEnv(),
-    }).trim();
-
-  const gitSpawn = (cwd, ...args) => {
-    const result = spawn('git', args, {
-      cwd,
-      stdio: 'pipe',
-      encoding: 'utf-8',
-      shell: false,
-      env: cleanGitEnv(),
-    });
-    return {
-      status: result.status ?? 1,
-      stdout: (result.stdout ?? '').trim(),
-      stderr: (result.stderr ?? '').trim(),
-    };
-  };
-
-  async function runWithRetry(leadingArgs, cwd, args) {
-    const backoff = [250, 500, 1000];
-    let attempt = 0;
-    let last;
-    for (;;) {
-      attempt++;
-      last = gitSpawn(cwd, ...leadingArgs, ...args);
-      if (last.status === 0) return { ...last, attempts: attempt };
-      if (!isPackedRefsContention(last.stderr))
-        return { ...last, attempts: attempt };
-      if (attempt > backoff.length) return { ...last, attempts: attempt };
-      const base = backoff[attempt - 1];
-      const jitter = Math.floor(Math.random() * base * jitterFactor);
-      await sleep(base + jitter);
-    }
-  }
+  const boundGitSpawn = (cwd, ...args) => runGitSpawn(spawn, cwd, args);
+  const withRetry =
+    (argvPrefix) =>
+    (cwd, ...args) =>
+      gitWithContentionRetry(
+        { spawnGit: boundGitSpawn, sleep, jitterFactor },
+        cwd,
+        argvPrefix,
+        args,
+      );
 
   return {
-    gitSync,
-    gitSpawn,
-    gitFetchWithRetry: (cwd, ...args) => runWithRetry(['fetch'], cwd, args),
-    gitPullWithRetry: (cwd, ...args) =>
-      runWithRetry(['pull', '--rebase'], cwd, args),
+    gitSync: (cwd, ...args) => runGitSync(exec, cwd, args),
+    gitSpawn: boundGitSpawn,
+    gitFetchWithRetry: withRetry(['fetch']),
+    gitPullWithRetry: withRetry(['pull', '--rebase']),
   };
 }
 
@@ -238,12 +253,21 @@ function isPackedRefsContention(stderr) {
 }
 
 /**
- * Sleep helper for retry backoff. Overridable via `__setSleep` so tests
- * can skip real wall-clock delays without relying on node:test timer mocks.
+ * Real wall-clock sleep — the default backoff delay for both the module-level
+ * retry helpers and {@link createGitInterface}.
  * @param {number} ms
  * @returns {Promise<void>}
  */
-let _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Sleep helper for retry backoff. Overridable via `__setSleep` so tests
+ * can skip real wall-clock delays without relying on node:test timer mocks.
+ * @type {(ms: number) => Promise<void>}
+ */
+let _sleep = defaultSleep;
 let _jitterFactor = 0.5;
 
 /**
@@ -258,38 +282,65 @@ export function __setSleep(fn, opts = {}) {
 }
 
 /**
- * Shared bounded retry loop for git commands that can hit packed-refs lock
- * contention. Only contention signatures trigger a retry — non-contention
+ * Backoff schedule for {@link gitWithContentionRetry}: 250ms, 500ms, 1000ms
+ * (3 retries → 4 attempts total).
+ */
+const CONTENTION_BACKOFF_MS = Object.freeze([250, 500, 1000]);
+
+/**
+ * The **single** bounded retry loop for git commands that can hit packed-refs
+ * lock contention. Only contention signatures trigger a retry — non-contention
  * failures surface immediately, and success short-circuits the loop.
  *
- * Backoff schedule: 250ms, 500ms, 1000ms (3 retries → 4 attempts total).
  * Deliberately no global lock — a mutex would erase the parallelism the
- * worktree-isolation model is designed to enable. The schedule and the
- * jitter policy (`_sleep` / `_jitterFactor` seams) live only here so a
- * backoff tuning change has a single point of application.
+ * worktree-isolation model is designed to enable. The schedule and the jitter
+ * policy live only here, so a backoff tuning change has a single point of
+ * application: the module-level `gitFetchWithRetry` / `gitPullWithRetry` pass
+ * the `_sleep` / `_jitterFactor` seams, and {@link createGitInterface} passes
+ * its injected equivalents.
  *
+ * @param {{ spawnGit: (cwd: string, ...args: string[]) => GitResult,
+ *   sleep: (ms: number) => Promise<void>, jitterFactor: number }} runners
  * @param {string} cwd
  * @param {string[]} argvPrefix - Leading git argv (e.g. `['fetch']`).
  * @param {string[]} args - Trailing arguments (e.g. `['origin']`).
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
-async function gitWithContentionRetry(cwd, argvPrefix, args) {
-  const backoff = [250, 500, 1000];
+async function gitWithContentionRetry(
+  { spawnGit, sleep, jitterFactor },
+  cwd,
+  argvPrefix,
+  args,
+) {
   let attempt = 0;
-  let last;
   for (;;) {
     attempt++;
-    last = gitSpawn(cwd, ...argvPrefix, ...args);
-    if (last.status === 0) return { ...last, attempts: attempt };
-    if (!isPackedRefsContention(last.stderr))
+    const last = spawnGit(cwd, ...argvPrefix, ...args);
+    const exhausted = attempt > CONTENTION_BACKOFF_MS.length;
+    if (
+      last.status === 0 ||
+      exhausted ||
+      !isPackedRefsContention(last.stderr)
+    ) {
       return { ...last, attempts: attempt };
-    if (attempt > backoff.length) return { ...last, attempts: attempt };
-    const base = backoff[attempt - 1];
-    const jitter = Math.floor(Math.random() * base * _jitterFactor);
-    await _sleep(base + jitter);
+    }
+    const base = CONTENTION_BACKOFF_MS[attempt - 1];
+    await sleep(base + Math.floor(Math.random() * base * jitterFactor));
   }
 }
 
+/**
+ * The module-level retry runners — the `__setSleep`-overridable seams bound to
+ * the module-global {@link gitSpawn}. Read lazily so `__setSleep` and
+ * `__setGitRunners` still take effect after import.
+ *
+ * @returns {{ spawnGit: typeof gitSpawn, sleep: (ms: number) => Promise<void>,
+ *   jitterFactor: number }}
+ */
+function moduleRetryRunners() {
+  return { spawnGit: gitSpawn, sleep: _sleep, jitterFactor: _jitterFactor };
+}
+
 /**
  * Run `git fetch …` with the bounded packed-refs-contention retry loop
  * (see `gitWithContentionRetry`).
@@ -299,7 +350,7 @@ async function gitWithContentionRetry(cwd, argvPrefix, args) {
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 export function gitFetchWithRetry(cwd, ...args) {
-  return gitWithContentionRetry(cwd, ['fetch'], args);
+  return gitWithContentionRetry(moduleRetryRunners(), cwd, ['fetch'], args);
 }
 
 /**
@@ -312,7 +363,12 @@ export function gitFetchWithRetry(cwd, ...args) {
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 export function gitPullWithRetry(cwd, ...args) {
-  return gitWithContentionRetry(cwd, ['pull', '--rebase'], args);
+  return gitWithContentionRetry(
+    moduleRetryRunners(),
+    cwd,
+    ['pull', '--rebase'],
+    args,
+  );
 }
 
 /**