mandrel 2.4.0 → 2.5.0

package/.agents/scripts/lib/audit-to-stories/ledger.js

@@ -0,0 +1,256 @@
+/**
+ * lib/audit-to-stories/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
+ * tell a brand-new finding from one already filed, an intentionally-rejected
+ * finding from an unseen one, or a genuine regression from routine churn. The
+ * ledger is that memory. It is a small committed JSON file
+ * (`baselines/audit-ledger.json`, the same envelope shape as the arch-cycles
+ * baseline — `{ $schema, generatedAt, entries: [] }`) keyed by each finding's
+ * shared-helper fingerprint plus a location-based `semanticKey` that survives a
+ * reworded title.
+ *
+ * Each entry carries a lifecycle `status`:
+ *   - `new`          — seen, not yet filed as an Issue.
+ *   - `filed`        — an Issue was opened; re-detections are known, not new.
+ *   - `fixed`        — the tracking Issue closed as completed.
+ *   - `accepted-risk`— the tracking Issue closed as `not_planned`; the finding
+ *                      is deliberately rejected and is SUPPRESSED on re-detect.
+ *   - `regressed`    — a `fixed` finding re-appeared (closed-completed Issue,
+ *                      finding detected again).
+ *
+ * `reconcileLedger` folds a fresh scan and the live Issue states onto the prior
+ * ledger, returning the next ledger plus a per-finding classification whose
+ * `action` (`propose` | `known` | `suppress` | `regressed`) tells the caller
+ * whether to open a Story. Pure: filesystem access is confined to the tiny
+ * {@link readLedger} / {@link writeLedger} helpers, which take an injectable
+ * `fs` so tests never touch disk.
+ */
+
+import nodeFs from 'node:fs';
+import nodePath from 'node:path';
+import {
+  fingerprintAuditFinding,
+  semanticKeyForAuditFinding,
+} from './finding-adapter.js';
+
+export const DEFAULT_LEDGER_PATH = 'baselines/audit-ledger.json';
+const LEDGER_SCHEMA_URL =
+  'https://mandrel.dev/baselines/audit-ledger.schema.json';
+
+// Entry lifecycle states — `new | filed | fixed | accepted-risk | regressed`.
+// The reconcile policy in `decideStatus` is the single source of truth.
+
+/**
+ * Build an empty ledger envelope (arch-cycles-baseline shape).
+ * @param {string} [now] — ISO timestamp to stamp.
+ * @returns {{ $schema: string, generatedAt: string, entries: [] }}
+ */
+function createEmptyLedger(now = new Date().toISOString()) {
+  return { $schema: LEDGER_SCHEMA_URL, generatedAt: now, entries: [] };
+}
+
+/**
+ * Compute a finding's stable identity: its fingerprint (title-sensitive) and
+ * its location-based semantic key (title-insensitive).
+ * @param {object} finding — a parsed/stamped audit finding.
+ * @returns {{ fingerprint: string, semanticKey: string }}
+ */
+function findingIdentity(finding) {
+  return {
+    fingerprint: fingerprintAuditFinding(finding).full,
+    semanticKey: semanticKeyForAuditFinding(finding),
+  };
+}
+
+/**
+ * Read the ledger from disk. Returns an empty ledger when the file is absent
+ * or unparseable — a missing memory is an empty memory, never a hard error.
+ * @param {string} filePath
+ * @param {{ fs?: typeof import('node:fs') }} [deps]
+ * @returns {{ $schema?: string, generatedAt?: string, entries: object[] }}
+ */
+export function readLedger(filePath, { fs } = {}) {
+  const fsLike = fs ?? nodeFs;
+  if (!fsLike || !fsLike.existsSync(filePath)) return createEmptyLedger();
+  try {
+    const parsed = JSON.parse(fsLike.readFileSync(filePath, 'utf8'));
+    if (!parsed || !Array.isArray(parsed.entries)) return createEmptyLedger();
+    return parsed;
+  } catch (_) {
+    return createEmptyLedger();
+  }
+}
+
+/**
+ * Persist the ledger to disk with a stable 2-space indent and a trailing
+ * newline (so the committed file diffs cleanly).
+ * @param {string} filePath
+ * @param {object} ledger
+ * @param {{ fs?: typeof import('node:fs'), path?: typeof import('node:path') }} [deps]
+ */
+export function writeLedger(filePath, ledger, { fs, path } = {}) {
+  const fsLike = fs ?? nodeFs;
+  const pathLike = path ?? nodePath;
+  if (!fsLike) return;
+  fsLike.mkdirSync(pathLike.dirname(filePath), { recursive: true });
+  fsLike.writeFileSync(filePath, `${JSON.stringify(ledger, null, 2)}\n`);
+}
+
+/**
+ * Index a ledger's entries by fingerprint and by semanticKey for O(1) lookup.
+ * @param {{ entries?: object[] }} ledger
+ */
+function indexLedger(ledger) {
+  const byFingerprint = new Map();
+  const bySemanticKey = new Map();
+  for (const entry of ledger?.entries ?? []) {
+    if (entry?.fingerprint) byFingerprint.set(entry.fingerprint, entry);
+    if (entry?.semanticKey) bySemanticKey.set(entry.semanticKey, entry);
+  }
+  return { byFingerprint, bySemanticKey };
+}
+
+/**
+ * Resolve the effective Issue state for a finding: an explicit override in
+ * `issueStates` (keyed by fingerprint then semanticKey) wins over whatever the
+ * prior ledger entry recorded.
+ * @param {{ fingerprint: string, semanticKey: string }} id
+ * @param {object|null} existing
+ * @param {Record<string, { state?: string, stateReason?: string|null, number?: number }>} issueStates
+ * @returns {{ state: string, stateReason: string|null, number: number|null }|null}
+ */
+function resolveIssueState(id, existing, issueStates) {
+  const override = issueStates[id.fingerprint] ?? issueStates[id.semanticKey];
+  const raw = override ?? existing?.issue ?? null;
+  if (!raw) return null;
+  return {
+    state: (raw.state ?? '').toLowerCase(),
+    stateReason: raw.stateReason ? String(raw.stateReason).toLowerCase() : null,
+    number: typeof raw.number === 'number' ? raw.number : null,
+  };
+}
+
+/**
+ * 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.
+ * @param {object|null} existing — prior ledger entry (or null when unseen).
+ * @param {{ state: string, stateReason: string|null }|null} issue
+ * @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.
+  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' };
+  }
+
+  if (!existing) return { status: 'new', action: 'propose' };
+
+  switch (existing.status) {
+    case 'accepted-risk':
+      return { status: 'accepted-risk', action: 'suppress' };
+    case 'filed':
+      return { status: 'filed', action: 'known' };
+    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' };
+    case 'regressed':
+      return { status: 'regressed', action: 'regressed' };
+    default:
+      return { status: 'new', action: 'propose' };
+  }
+}
+
+/**
+ * Fold a fresh scan and the live Issue states onto the prior ledger.
+ *
+ * @param {object} params
+ * @param {{ entries?: object[] }} [params.ledger] — prior ledger (default empty).
+ * @param {Array<object>} params.findings — parsed/stamped audit findings from this scan.
+ * @param {Record<string, { state?: string, stateReason?: string|null, number?: number }>} [params.issueStates]
+ *   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.
+ * @returns {{
+ *   ledger: { $schema: string, generatedAt: string, entries: object[] },
+ *   classifications: Array<{ fingerprint: string, semanticKey: string, status: string, action: string, issue: object|null }>,
+ * }}
+ */
+export function reconcileLedger({
+  ledger = createEmptyLedger(),
+  findings,
+  issueStates = {},
+  now = new Date().toISOString(),
+} = {}) {
+  if (!Array.isArray(findings)) {
+    throw new Error('reconcileLedger: findings must be an array');
+  }
+
+  const { byFingerprint, bySemanticKey } = indexLedger(ledger);
+  // Preserve any prior entries NOT touched by this scan (their memory survives).
+  const nextByFingerprint = new Map(byFingerprint);
+  const classifications = [];
+
+  for (const finding of findings) {
+    const id = findingIdentity(finding);
+    const existing =
+      byFingerprint.get(id.fingerprint) ??
+      (id.semanticKey ? bySemanticKey.get(id.semanticKey) : undefined) ??
+      null;
+
+    const issue = resolveIssueState(id, existing, issueStates);
+    const { status, action } = decideStatus(existing, issue);
+
+    const entry = {
+      fingerprint: id.fingerprint,
+      semanticKey: id.semanticKey,
+      title: finding?.title ?? existing?.title ?? '',
+      dimension: finding?.dimension ?? existing?.dimension ?? '',
+      primaryFile:
+        (Array.isArray(finding?.files) && finding.files[0]) ??
+        existing?.primaryFile ??
+        '',
+      status,
+      issue: issue
+        ? {
+            number: issue.number,
+            state: issue.state,
+            stateReason: issue.stateReason,
+          }
+        : (existing?.issue ?? null),
+      firstSeen: existing?.firstSeen ?? now,
+      lastSeen: now,
+    };
+
+    // Re-key under the fresh fingerprint; drop the old entry if it was matched
+    // by semanticKey under a now-drifted fingerprint (reworded finding).
+    if (existing?.fingerprint && existing.fingerprint !== id.fingerprint) {
+      nextByFingerprint.delete(existing.fingerprint);
+    }
+    nextByFingerprint.set(id.fingerprint, entry);
+
+    classifications.push({
+      fingerprint: id.fingerprint,
+      semanticKey: id.semanticKey,
+      status,
+      action,
+      issue: entry.issue,
+    });
+  }
+
+  return {
+    ledger: {
+      $schema: ledger?.$schema ?? LEDGER_SCHEMA_URL,
+      generatedAt: now,
+      entries: [...nextByFingerprint.values()],
+    },
+    classifications,
+  };
+}

package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js

@@ -2,11 +2,14 @@
  * lib/audit-to-stories/parse-audit-md.js — Parse `audit-*-results.md` reports.
  *
  * Extracts the `## Detailed Findings` section of an audit report and turns
- * every `### <title>` block into a normalised finding record. The 12 audit
- * workflows use slightly different field names — `Severity` vs `Impact`,
- * `Dimension` vs `Category` — so the parser captures every key/value pair
- * the block carries and normalises the two axes the downstream pipeline
- * relies on (severity + dimension).
+ * every `### <title>` block into a normalised finding record. Every audit lens
+ * report now shares one findings contract (Story #4625): a `Critical | High |
+ * Medium | Low` severity scale, a mandated `Location:` path anchor, and a
+ * dimension axis. Lenses still label the axes slightly differently — `Severity`
+ * vs `Impact`, `Dimension` vs `Category` vs `Type` — so the parser captures
+ * every key/value pair the block carries and normalises the two axes the
+ * downstream pipeline relies on (severity + dimension), harvesting the
+ * `Location:` field into `files[]` ahead of prose scraping.
  *
  * Pure: no filesystem I/O. The caller supplies the report text and source
  * path; the parser returns plain objects.
@@ -54,7 +57,7 @@ function normaliseSeverity(token) {
 }
 
 function deriveDimension(fields, fallbackDimension) {
-  for (const key of ['dimension', 'category', 'area']) {
+  for (const key of ['dimension', 'category', 'area', 'type']) {
     const raw = fields[key];
     if (typeof raw === 'string' && raw.trim().length > 0) {
       return raw
@@ -66,6 +69,33 @@ function deriveDimension(fields, fallbackDimension) {
   return fallbackDimension;
 }
 
+/**
+ * Harvest the mandated `Location:` field into concrete file paths. Every
+ * non-retired lens template now carries a `- **Location:** <path>:<line>`
+ * bullet (Story #4625); extracting it here — ahead of the heuristic prose
+ * scrape — gives a finding a deterministic identity anchor instead of relying
+ * on whatever path text happens to appear in the prose. The value may wrap the
+ * path in backticks and/or append a `:line` (or `:line:col`) suffix; both are
+ * stripped. Only tokens that look like paths (containing a separator) survive.
+ *
+ * @param {Record<string, string>} fields
+ * @returns {string[]}
+ */
+function deriveLocationFiles(fields) {
+  const raw = fields.location;
+  if (typeof raw !== 'string' || raw.trim().length === 0) return [];
+  const cleaned = raw.replace(/[`[\]]/g, ' ');
+  const out = [];
+  for (const token of cleaned.split(/[\s,]+/)) {
+    if (!token) continue;
+    const withoutLine = token.replace(/:\d+(?::\d+)?$/, '');
+    if (withoutLine.includes('/') || withoutLine.includes('\\')) {
+      out.push(withoutLine);
+    }
+  }
+  return out;
+}
+
 function deriveSeverity(fields) {
   for (const key of ['severity', 'impact', 'risk']) {
     const sev = normaliseSeverity(fields[key]);
@@ -166,7 +196,8 @@ function parseBlockFields(bodyLines) {
  * @param {object} params
  * @param {string} params.markdown — full report text.
  * @param {string} params.sourceReport — path used for `sourceReport` field
- *   and dimension inference when the report omits a `Dimension:` line.
+ *   and dimension inference when the report omits a `Dimension:` / `Category:`
+ *   / `Type:` line.
  * @returns {Array<{
  *   dimension: string,
  *   severity: 'critical'|'high'|'medium'|'low'|null,
@@ -200,6 +231,7 @@ export function parseAuditReport({ markdown, sourceReport }) {
       fields['recommendation & rationale'] ?? fields.recommendation ?? '';
     const agentPrompt = fields['agent prompt'] ?? '';
     const fileSet = new Set([
+      ...deriveLocationFiles(fields),
       ...extractFilePaths(currentState),
       ...extractFilePaths(recommendation),
       ...extractFilePaths(agentPrompt),
@@ -243,4 +275,6 @@ export const __testing = {
   normaliseSeverity,
   extractFilePaths,
   normaliseTitle,
+  deriveDimension,
+  deriveLocationFiles,
 };

package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js

@@ -17,6 +17,11 @@
  * Pure: returns a string. The caller decides where to persist it.
  */
 
+import {
+  renderFingerprintFooter,
+  renderSemanticKeyFooter,
+} from './finding-adapter.js';
+
 const DIMENSION_LABEL = {
   security: 'Security',
   privacy: 'Privacy',
@@ -24,7 +29,7 @@ const DIMENSION_LABEL = {
   'clean-code': 'Clean code',
   dependencies: 'Dependencies',
   devops: 'DevOps',
-  lighthouse: 'Lighthouse',
+  accessibility: 'Accessibility',
   performance: 'Performance',
   seo: 'SEO',
   sre: 'SRE',
@@ -84,7 +89,20 @@ function formatMVPScope(groups) {
     .map((g, idx) => {
       const dims = g.dimensions.join(' / ');
       const file = g.files[0] ? ` (\`${g.files[0]}\`)` : '';
-      return `${idx + 1}. **${g.title}** — ${dims}${file}`;
+      // Carry each group's fingerprint (and location-based semantic-key)
+      // footer into the seed so a Story authored from it via `/plan` inherits
+      // the dedup identity — without this the recommended `/plan --seed-file`
+      // path is invisible to the next sweep's dedup (Story #4626). The footers
+      // are HTML comments, so they never render in the visible one-pager but
+      // stay machine-readable for the dedup probe.
+      const findings = Array.isArray(g.findings) ? g.findings : [];
+      const footers = [
+        renderFingerprintFooter(findings),
+        renderSemanticKeyFooter(findings),
+      ]
+        .map((f) => `   ${f}`)
+        .join('\n');
+      return `${idx + 1}. **${g.title}** — ${dims}${file}\n${footers}`;
     })
     .join('\n');
 }

package/.agents/scripts/lib/command-header.js

@@ -35,7 +35,7 @@ export function applyHeader(content, header) {
 /**
  * True when a workflow opts out of slash-command projection via a
  * `command: false` key in its YAML frontmatter (#4482). Used for dual-use
- * lens files (e.g. `audit-security.md`, `audit-lighthouse.md`) that stay in
+ * lens files (e.g. `audit-security.md`) that stay in
  * the payload as `/deliver` audit-suite prompts but must NOT surface as
  * standalone slash commands because the host ships a native equivalent.
  *

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -303,6 +303,26 @@ const FEEDBACK_LOOP_SCHEMA = {
   additionalProperties: false,
 };
 
+/**
+ * `delivery.auditToStories` — knobs for the `/audit-to-stories` unattended
+ * (`--auto`) sweep (Story #4626). `severityFloor` is the minimum severity a
+ * finding must meet to be proposed as a Story on an unattended run (default
+ * `high`); `autoComment`, when true (default), lets `--auto` post a
+ * "re-detected" comment on an already-open matched Issue instead of silently
+ * skipping it.
+ */
+const AUDIT_TO_STORIES_SCHEMA = {
+  type: 'object',
+  properties: {
+    severityFloor: {
+      type: 'string',
+      enum: ['critical', 'high', 'medium', 'low', 'all'],
+    },
+    autoComment: { type: 'boolean' },
+  },
+  additionalProperties: false,
+};
+
 export const DELIVERY_SCHEMA = {
   type: 'object',
   properties: {
@@ -318,6 +338,7 @@ export const DELIVERY_SCHEMA = {
     refactorStage: REFACTOR_STAGE_SCHEMA,
     acceptanceEval: ACCEPTANCE_EVAL_SCHEMA,
     feedbackLoop: FEEDBACK_LOOP_SCHEMA,
+    auditToStories: AUDIT_TO_STORIES_SCHEMA,
     ci: CI_DELIVERY_SCHEMA,
     routing: ROUTING_SCHEMA,
   },

package/.agents/scripts/lib/dynamic-workflow/performance-report-contract.js

@@ -12,9 +12,10 @@ import { assertSectionsContract } from './report-contract-core.js';
  * contract-tier test assert report conformance against one definition rather
  * than re-deriving headings from prose in two places.
  *
- * Changing the report contract is explicitly **out of scope** for this Story —
- * this module documents the existing shape already declared by the lens
- * markdown's Step 3 template, it does not introduce a new one.
+ * The report shape is declared by the lens markdown's Step 4 template. Story
+ * #4631 added the mandatory per-finding **Evidence** field (a repro command
+ * plus a `measured`/`estimated` tag) so measurement-first evidence is part of
+ * the contract both paths must emit, not just prose in the lens.
  *
  * @module dynamic-workflow/performance-report-contract
  */
@@ -48,6 +49,7 @@ export const REPORT_TITLE = 'Performance Audit Report';
 export const FINDING_FIELDS = Object.freeze([
   'Dimension',
   'Impact',
+  'Evidence',
   'Current State',
   'Recommendation & Rationale',
   'Agent Prompt',

package/.agents/scripts/lib/feedback-loop/audit-results-graduator.js

@@ -45,6 +45,12 @@
  *   - NEVER throw. Every failure path is captured in `errors[]`.
  */
 
+import {
+  fingerprintFinding,
+  fingerprintFooter,
+  semanticKeyFooter,
+  semanticKeyFor,
+} from '../findings/route-finding.js';
 import {
   contentFingerprint,
   graduate,
@@ -121,6 +127,50 @@ export function buildContentMarker(epicId, finding) {
   return `<!-- audit-results-followup: epic-${epicId}-${fp} -->`;
 }
 
+/**
+ * Project a graduator audit finding onto the canonical identity the shared
+ * dedup helper (`lib/findings/route-finding.js`) fingerprints over, so a
+ * close-time graduator filing and a sweep-time `/audit-to-stories` filing
+ * share ONE identity namespace (Story #4626). The graduator's `lens`
+ * (`audit-<dimension>`) maps to the identity `area`; its cited `path` is the
+ * primary file; its `summary` is the title. Historically the graduator only
+ * stamped its own content-hash `audit-results-followup` marker, disjoint from
+ * route-finding's `audit-fingerprints` footer — so a `/audit-to-stories`
+ * sweep could not recognize a graduator-filed issue and would re-file it.
+ *
+ * @param {{ lens?: string, path?: string, summary?: string }} finding
+ * @returns {{ title: string, area: string, primaryFile: string, severity: string, labels: string[] }}
+ */
+export function toCanonicalFinding(finding) {
+  const lens = typeof finding?.lens === 'string' ? finding.lens : '';
+  return {
+    title: typeof finding?.summary === 'string' ? finding.summary : '',
+    area: lens,
+    primaryFile: typeof finding?.path === 'string' ? finding.path : '',
+    severity: '',
+    labels: lens ? [lens] : [],
+  };
+}
+
+/**
+ * Render the canonical `audit-fingerprints` (and location-based
+ * `audit-semantic-keys`) footer for a graduator finding, computed off the
+ * shared helper's canonical hash. Stamped into every filed follow-up body so
+ * the `/audit-to-stories` dedup probe recognizes a graduator-filed issue
+ * (Story #4626).
+ *
+ * @param {{ lens?: string, path?: string, summary?: string }} finding
+ * @returns {string}
+ */
+export function canonicalFingerprintFooter(finding) {
+  const canonical = toCanonicalFinding(finding);
+  const { full } = fingerprintFinding(canonical);
+  const key = semanticKeyFor(canonical);
+  const lines = [fingerprintFooter(full)];
+  if (key) lines.push(semanticKeyFooter(key));
+  return lines.join('\n');
+}
+
 /**
  * Parse the rendered audit-results markdown into a list of findings.
  * The format produced by `epic-audit.md` Step 4 groups findings under
@@ -260,6 +310,12 @@ export async function graduateAuditResults(opts = {}) {
           finding.summary,
           '',
           `_See Epic #${epicId} for the full audit-results report._`,
+          '',
+          // Canonical dedup identity so the `/audit-to-stories` sweep-time
+          // probe recognizes this close-time filing and never re-files it
+          // (Story #4626). The content-hash `audit-results-followup` marker
+          // above stays the graduator's own re-file guard.
+          canonicalFingerprintFooter(finding),
         ].join('\n');
         const labels = [
           'meta::audit-finding',