mandrel 2.55.0 → 2.57.0

package/.agents/scripts/lib/{audit-to-stories/ledger.js → findings/audit-ledger.js}

@@ -1,5 +1,5 @@
 /**
- * lib/audit-to-stories/ledger.js — Cross-run audit findings ledger.
+ * lib/findings/audit-ledger.js — Cross-run audit findings ledger.
  *
  * Without a committed memory of what a prior sweep already saw, every
  * `/audit-to-stories` run re-litigates the whole backlog from zero: it cannot
@@ -30,10 +30,7 @@
 
 import nodeFs from 'node:fs';
 import nodePath from 'node:path';
-import {
-  fingerprintAuditFinding,
-  semanticKeyForAuditFinding,
-} from './finding-adapter.js';
+import { fingerprintFinding, semanticKeyFor } from './route-finding.js';
 
 export const DEFAULT_LEDGER_PATH = 'baselines/audit-ledger.json';
 const LEDGER_SCHEMA_URL =
@@ -54,13 +51,24 @@ function createEmptyLedger(now = new Date().toISOString()) {
 /**
  * Compute a finding's stable identity: its fingerprint (title-sensitive) and
  * its location-based semantic key (title-insensitive).
+ *
+ * The projection onto the canonical identity is the **caller's**, injected as
+ * `toCanonical`. That is what lets this module live beside `route-finding.js`
+ * in the shared findings layer: the audit pipeline's own adapter
+ * (`lib/audit-to-stories/finding-adapter.js`) imports *from* here, so importing
+ * it back would close a `findings → audit-to-stories → findings` cycle that
+ * `check-arch-cycles` rightly refuses. A caller that already holds canonical
+ * findings passes nothing.
+ *
  * @param {object} finding — a parsed/stamped audit finding.
+ * @param {(finding: object) => object} [toCanonical]
  * @returns {{ fingerprint: string, semanticKey: string }}
  */
-function findingIdentity(finding) {
+function findingIdentity(finding, toCanonical) {
+  const canonical = toCanonical ? toCanonical(finding) : finding;
   return {
-    fingerprint: fingerprintAuditFinding(finding).full,
-    semanticKey: semanticKeyForAuditFinding(finding),
+    fingerprint: fingerprintFinding(canonical).full,
+    semanticKey: semanticKeyFor(canonical),
   };
 }
 
@@ -132,6 +140,19 @@ function resolveIssueState(id, existing, issueStates) {
   };
 }
 
+/**
+ * The four verdicts the policy can reach, spelled once. Deduping them keeps
+ * `decideStatus` readable as the decision table it is, rather than eight
+ * near-identical object literals.
+ * @type {Record<string, { status: string, action: string }>}
+ */
+const VERDICT = Object.freeze({
+  filed: Object.freeze({ status: 'filed', action: 'known' }),
+  propose: Object.freeze({ status: 'new', action: 'propose' }),
+  suppress: Object.freeze({ status: 'accepted-risk', action: 'suppress' }),
+  regressed: Object.freeze({ status: 'regressed', action: 'regressed' }),
+});
+
 /**
  * Decide the finding's next status + action from its prior ledger state and
  * the live Issue state. This is the whole reconciliation policy in one place.
@@ -140,31 +161,41 @@ function resolveIssueState(id, existing, issueStates) {
  * @returns {{ status: string, action: 'propose'|'known'|'suppress'|'regressed' }}
  */
 function decideStatus(existing, issue) {
-  // A closed Issue is the strongest signal — its close reason drives the verdict.
+  // A closed Issue is the strongest signal — its close reason drives the
+  // verdict, and it is read FIRST so a recorded `filed` can never outrank it.
   if (issue && issue.state === 'closed') {
-    if (issue.stateReason === 'not_planned') {
-      return { status: 'accepted-risk', action: 'suppress' };
-    }
-    // Closed as completed (or unspecified) but the finding is in this scan →
-    // it came back. That is a regression, not a fresh proposal.
-    return { status: 'regressed', action: 'regressed' };
+    return issue.stateReason === 'not_planned'
+      ? VERDICT.suppress
+      : // Closed as completed (or unspecified) but the finding is in this scan
+        // → it came back. That is a regression, not a fresh proposal.
+        VERDICT.regressed;
   }
 
-  if (!existing) return { status: 'new', action: 'propose' };
+  // An OPEN tracking Issue means the finding has been filed, whatever the prior
+  // entry said — including when there is no prior entry at all. Until Story
+  // #5305 nothing in the package ever assigned `filed`, so this fell through to
+  // `new`/`propose` on every run and the `filed` arm below was unreachable in
+  // production: the ledger suppressed nothing, and only the GitHub-search dedup
+  // stopped a sweep re-filing what it had already filed. Reading it before the
+  // `!existing` guard is what makes a record pass correct on its FIRST run
+  // rather than its second.
+  const unseen = issue?.state === 'open' ? VERDICT.filed : VERDICT.propose;
+  if (!existing) return unseen;
 
   switch (existing.status) {
     case 'accepted-risk':
-      return { status: 'accepted-risk', action: 'suppress' };
+      return VERDICT.suppress;
     case 'filed':
-      return { status: 'filed', action: 'known' };
+      return VERDICT.filed;
+    // Recorded fixed, yet detected again with no closed-Issue evidence → treat
+    // as a regression the operator should look at. An open Issue does not
+    // soften that: the finding came back either way.
     case 'fixed':
-      // Recorded fixed, yet detected again with no closed-Issue evidence →
-      // treat as a regression the operator should look at.
-      return { status: 'regressed', action: 'regressed' };
+      return VERDICT.regressed;
     case 'regressed':
-      return { status: 'regressed', action: 'regressed' };
+      return VERDICT.regressed;
     default:
-      return { status: 'new', action: 'propose' };
+      return unseen;
   }
 }
 
@@ -178,6 +209,8 @@ function decideStatus(existing, issue) {
  *   Live Issue state keyed by fingerprint (or semanticKey). Optional — when a
  *   prior entry already records the Issue, that is used.
  * @param {string} [params.now] — ISO timestamp for firstSeen/lastSeen stamping.
+ * @param {(finding: object) => object} [params.toCanonical] — projection onto
+ *   the canonical identity; omit when `findings` are already canonical.
  * @returns {{
  *   ledger: { $schema: string, generatedAt: string, entries: object[] },
  *   classifications: Array<{ fingerprint: string, semanticKey: string, status: string, action: string, issue: object|null }>,
@@ -188,6 +221,7 @@ export function reconcileLedger({
   findings,
   issueStates = {},
   now = new Date().toISOString(),
+  toCanonical,
 } = {}) {
   if (!Array.isArray(findings)) {
     throw new Error('reconcileLedger: findings must be an array');
@@ -199,7 +233,7 @@ export function reconcileLedger({
   const classifications = [];
 
   for (const finding of findings) {
-    const id = findingIdentity(finding);
+    const id = findingIdentity(finding, toCanonical);
     const existing =
       byFingerprint.get(id.fingerprint) ??
       (id.semanticKey ? bySemanticKey.get(id.semanticKey) : undefined) ??
@@ -254,3 +288,76 @@ export function reconcileLedger({
     classifications,
   };
 }
+
+/**
+ * Record a set of already-known identities as filed against one Issue.
+ *
+ * The finding-shaped {@link reconcileLedger} cannot serve this caller:
+ * `plan-persist` never sees findings. It holds the provenance identities it
+ * stamped on a Story body — fingerprints and semantic keys, as strings — plus
+ * the issue number it just created. That is enough to record the filing, and
+ * demanding a finding it does not have would be the reason the recommended
+ * planning path never reached this ledger at all.
+ *
+ * An identity already carrying a **closed** Issue is left exactly as it is: a
+ * finding whose tracking Issue was closed `not_planned` is `accepted-risk` and
+ * must stay suppressed, and one closed as completed is a `regressed` the
+ * operator still needs to see. A fresh filing never overwrites either verdict.
+ *
+ * @param {object} params
+ * @param {{ entries?: object[] }} [params.ledger] — prior ledger (default empty).
+ * @param {Array<{ fingerprint: string, semanticKey?: string, title?: string, dimension?: string, primaryFile?: string }>} params.identities
+ * @param {{ number: number }} params.issue — the Issue these identities were filed as.
+ * @param {string} [params.now]
+ * @returns {{ ledger: object, recorded: number, skipped: number }}
+ */
+export function recordFiledIdentities({
+  ledger = createEmptyLedger(),
+  identities,
+  issue,
+  now = new Date().toISOString(),
+} = {}) {
+  if (!Array.isArray(identities)) {
+    throw new Error('recordFiledIdentities: identities must be an array');
+  }
+  if (!issue || typeof issue.number !== 'number') {
+    throw new Error('recordFiledIdentities: issue.number must be a number');
+  }
+
+  const { byFingerprint } = indexLedger(ledger);
+  const next = new Map(byFingerprint);
+  let recorded = 0;
+  let skipped = 0;
+
+  for (const identity of identities) {
+    const fingerprint = identity?.fingerprint;
+    if (typeof fingerprint !== 'string' || fingerprint.length === 0) continue;
+    const existing = byFingerprint.get(fingerprint) ?? null;
+    if (existing?.issue && existing.issue.state === 'closed') {
+      skipped += 1;
+      continue;
+    }
+    next.set(fingerprint, {
+      fingerprint,
+      semanticKey: identity.semanticKey ?? existing?.semanticKey ?? '',
+      title: identity.title ?? existing?.title ?? '',
+      dimension: identity.dimension ?? existing?.dimension ?? '',
+      primaryFile: identity.primaryFile ?? existing?.primaryFile ?? '',
+      status: 'filed',
+      issue: { number: issue.number, state: 'open', stateReason: null },
+      firstSeen: existing?.firstSeen ?? now,
+      lastSeen: now,
+    });
+    recorded += 1;
+  }
+
+  return {
+    ledger: {
+      $schema: ledger?.$schema ?? LEDGER_SCHEMA_URL,
+      generatedAt: now,
+      entries: [...next.values()],
+    },
+    recorded,
+    skipped,
+  };
+}

package/.agents/scripts/lib/findings/route-finding.js

@@ -36,6 +36,7 @@ import { fingerprintSeverity } from './severity.js';
 const SEP = '␟'; // unit separator — keeps fingerprint fields unambiguous
 const MARKER = 'audit-fingerprints:';
 const SEMANTIC_MARKER = 'audit-semantic-keys:';
+const LABEL_MARKER = 'audit-labels:';
 export const SHA1_RE = /^[0-9a-f]{40}$/;
 // A semantic key round-trips through a comma-joined footer, so it must not
 // carry a comma or a `>` (which would truncate the HTML comment). Both are
@@ -175,6 +176,43 @@ export function parseSemanticKeyFooter(body) {
   );
 }
 
+/**
+ * Render the machine-readable audit-label footer
+ * (`<!-- audit-labels: audit::x,audit::y -->`).
+ *
+ * The dedup corpus is listed by `audit::*` label, so a Story carrying none is
+ * absent from the pool an indexed run matches against — and with an index in
+ * play the exact lookup is answered locally and never reaches the provider, so
+ * a fingerprint footer alone cannot rescue it. Carrying the labels through the
+ * seed is what lets the planning path stamp them without the authoring agent
+ * being asked to notice them (Story #5307).
+ *
+ * @param {string | string[]} labels
+ * @returns {string}
+ */
+export function auditLabelFooter(labels) {
+  const list = (Array.isArray(labels) ? labels : [labels])
+    .filter((l) => typeof l === 'string' && l.startsWith('audit::'))
+    .map((l) => l.replace(/[,>]/g, ' ').trim())
+    .filter((l) => l.length > 0);
+  if (list.length === 0) return '';
+  return `<!-- ${LABEL_MARKER} ${[...new Set(list)].sort().join(',')} -->`;
+}
+
+/**
+ * Read every `audit-labels` footer out of a body, de-duplicated.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+export function parseAuditLabelFooter(body) {
+  return parseAllFooterValues(
+    body,
+    /<!--\s*audit-labels:\s*([^>]*?)\s*-->/g,
+    (s) => s.startsWith('audit::'),
+  );
+}
+
 /**
  * Render the machine-readable fingerprint footer for one or more shas.
  *