mandrel 2.24.0 → 2.25.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/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',

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -17,6 +17,20 @@
  * from the cap enforcement path — a critic that always reports `round: 1`
  * can no longer defeat the bounded-loop guarantee.
  *
+ * ## Reading a verdict is not a round (Story #4874)
+ *
+ * Counting signals made *observation* costly: re-running the gate over an
+ * already-scored verdict — a resumed sub-agent re-reading its own verdict,
+ * an operator re-checking why the loop said `redraft` — appended another
+ * signal and advanced the derived round, so a `redraft` could escalate to
+ * `block` with no work in between. Every appended signal therefore carries
+ * a `details.verdictFingerprint` content-addressing the verdict it scored,
+ * and {@link resolveAcceptanceEvalRound} replays the round already recorded
+ * for that fingerprint instead of minting a new one. A replay is observably
+ * free: the round does not advance and no signal is appended. New work
+ * produces different verdict content, hence a new fingerprint, hence a
+ * genuine round.
+ *
  * ## The three terminal actions
  *
  *   - `proceed`  — every criterion is `met`. The Story may flip to
@@ -39,6 +53,7 @@
  * possible action is `block`.
  */
 
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
 import { runArtifactPath, signalsFile } from '../config/temp-paths.js';
@@ -112,7 +127,7 @@ function partitionCriteria(criteria) {
  *   The resolved (already-clamped) redraft ceiling from
  *   `getAcceptanceEval(config).maxRounds`.
  * @param {number} [args.round]
- *   The current round number, derived via `deriveAcceptanceEvalRound`.
+ *   The current round number, derived via `resolveAcceptanceEvalRound`.
  *   Defaults to 1 when absent or invalid.
  * @returns {{
  *   decision: 'proceed' | 'redraft' | 'block',
@@ -172,6 +187,7 @@ export function buildAcceptanceEvalSignal({
   outcome,
   phase = 'implement',
   clusterId = null,
+  verdictFingerprint = null,
 }) {
   return {
     kind: 'acceptance-eval',
@@ -186,6 +202,13 @@ export function buildAcceptanceEvalSignal({
     phase,
     emitter: { tool: 'acceptance-eval.js' },
     details: {
+      // Content address of the verdict this signal scored. The replay guard
+      // in `resolveAcceptanceEvalRound` matches on it, so a re-read of an
+      // already-scored verdict reuses its round instead of minting one.
+      ...(typeof verdictFingerprint === 'string' &&
+      verdictFingerprint.length > 0
+        ? { verdictFingerprint }
+        : {}),
       decision: outcome.decision,
       round: outcome.round,
       cap: outcome.cap,
@@ -201,29 +224,29 @@ export function buildAcceptanceEvalSignal({
 }
 
 /**
- * Derive the current acceptance-eval round for a Story by counting the
- * `acceptance-eval` signals already appended to the Story's
- * `signals.ndjson` (Story #4019). Round = prior-signal count + 1, so the
- * first run reports round 1 and each completed round (which appends one
- * signal via `acceptance-eval.js`) advances the derived round by one.
+ * Read the `acceptance-eval` records already appended to the Story's (or AC
+ * cluster's) `signals.ndjson`, in append order — the prior rounds
+ * {@link resolveAcceptanceEvalRound} counts from (Story #4019).
  *
- * The derivation is restart-safe: the ledger lives on disk, so a subagent
- * that dies mid-loop and restarts still observes every prior round. A
- * missing or malformed ledger degrades to round 1 (no prior rounds), and
- * malformed lines are skipped — observability corruption never wedges the
- * gate.
+ * The read is restart-safe: the ledger lives on disk, so a subagent that
+ * dies mid-loop and restarts still observes every prior round. A missing or
+ * unreadable ledger degrades to "no prior rounds" and malformed lines are
+ * skipped — observability corruption never wedges the gate.
  *
  * @param {object} args
  * @param {number|null} args.epicId   Parent Epic ID, or `null` for a
  *   standalone Story (routes to `<tempRoot>/standalone/stories/...`).
  * @param {number} args.storyId
+ * @param {string|null} [args.clusterId] AC-cluster id (Epic #4475 M4-B).
  * @param {object} [args.config]      Resolved config (tempRoot resolution).
  * @param {(p: string) => string} [args.readFile]  Injectable reader (tests).
  * @param {(eid: number|null, sid: number, config?: object) => string} [args.signalsPathResolver]
  *   Injectable path resolver (tests). Defaults to `signalsFile`.
- * @returns {number} The 1-based current round.
+ * @param {(eid: number, config?: object) => string} [args.epicSignalsPathResolver]
+ *   Injectable epic-stream path resolver (tests).
+ * @returns {object[]} The matching records, oldest first.
  */
-export function deriveAcceptanceEvalRound({
+function readPriorAcceptanceEvalRecords({
   epicId,
   storyId,
   clusterId = null,
@@ -249,10 +272,10 @@ export function deriveAcceptanceEvalRound({
       : readFile(signalsPathResolver(epicId ?? null, storyId, config));
   } catch (_err) {
     // No ledger yet → no prior rounds.
-    return 1;
+    return [];
   }
 
-  let priorRounds = 0;
+  const records = [];
   for (const line of String(text).split('\n')) {
     const trimmed = line.trim();
     if (trimmed === '') continue;
@@ -269,7 +292,77 @@ export function deriveAcceptanceEvalRound({
     } else if (record.storyId !== storyId) {
       continue;
     }
-    priorRounds += 1;
+    records.push(record);
   }
-  return priorRounds + 1;
+  return records;
+}
+
+/**
+ * Content-address a verdict so re-scoring the same verdict is recognisable
+ * as a re-read rather than a new round (Story #4874).
+ *
+ * The fingerprint covers exactly what the decision depends on — the ordered
+ * per-criterion `index` / `criterion` / `verdict` / `evidence` tuples — and
+ * deliberately nothing else: the verdict's self-reported `round`, its
+ * timestamp, and any authoring scratch must not make an unchanged
+ * evaluation look like a new one. Conversely, real rework changes at least
+ * one criterion's verdict or its evidence, so a genuine re-evaluation
+ * always fingerprints differently.
+ *
+ * @param {{ criteria?: Array<object> }} verdict
+ * @returns {string} 16 hex chars of a SHA-256 over the canonical form.
+ */
+export function computeVerdictFingerprint(verdict) {
+  const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
+  const canonical = criteria.map((c) => [
+    Number.isInteger(c?.index) ? c.index : null,
+    typeof c?.criterion === 'string' ? c.criterion : '',
+    typeof c?.verdict === 'string' ? c.verdict : '',
+    typeof c?.evidence === 'string' ? c.evidence : '',
+  ]);
+  return createHash('sha256')
+    .update(JSON.stringify(canonical))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+/**
+ * Resolve the round a verdict should be scored under, distinguishing a
+ * genuine evaluation from a re-read of an already-scored verdict
+ * (Story #4874). A genuine round is `prior-signal count + 1`, so the first
+ * run reports round 1 and each completed round advances it by one.
+ *
+ * When the ledger already carries an `acceptance-eval` signal whose
+ * `details.verdictFingerprint` matches, this invocation is a **replay**: it
+ * reports that signal's round and tells the caller not to append a second
+ * one, so reading is observably free and cannot escalate a `redraft` into a
+ * `block`. Otherwise it is a genuine round and the counter advances exactly
+ * as the pre-#4874 count-based derivation always did.
+ *
+ * Signals written before this field existed carry no fingerprint; they can
+ * never match, so legacy ledgers keep their count-based behaviour.
+ *
+ * @param {object} args — {@link readPriorAcceptanceEvalRecords}'s arguments
+ *   plus:
+ * @param {string} args.verdictFingerprint
+ * @returns {{ round: number, replay: boolean }}
+ */
+export function resolveAcceptanceEvalRound(args) {
+  const { verdictFingerprint } = args;
+  const records = readPriorAcceptanceEvalRecords(args);
+  const priorIndex =
+    typeof verdictFingerprint === 'string' && verdictFingerprint.length > 0
+      ? records.findIndex(
+          (r) => r?.details?.verdictFingerprint === verdictFingerprint,
+        )
+      : -1;
+  if (priorIndex === -1) {
+    return { round: records.length + 1, replay: false };
+  }
+  const recorded = records[priorIndex]?.details?.round;
+  return {
+    round:
+      Number.isInteger(recorded) && recorded >= 1 ? recorded : priorIndex + 1,
+    replay: true,
+  };
 }