mandrel 2.54.0 → 2.56.0

package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js

@@ -25,6 +25,7 @@
  */
 
 import { META_LABELS } from '../label-constants.js';
+import { CI_GAP_INTAKE_MARKER } from '../orchestration/ci-gap-intake.js';
 import { runChild } from './graduator-core.js';
 
 const DEFAULT_LIMIT = 50;
@@ -135,8 +136,15 @@ function formatGhError(label, { code, stderr, spawnError }) {
  * already-budgeted envelope, and trimming early avoids any ambient assumption
  * that downstream consumers can rely on extra fields.
  *
+ * `intake` is the one field derived rather than copied: an issue whose body
+ * carries the CI-gap intake marker is a filing awaiting graduation, not a
+ * finished report, and `/mandrel-plan` offers those a `/mandrel-plan <id>`
+ * rewrite. The body itself is NOT carried onto the envelope — the marker
+ * check is the whole reason it was fetched, and a planner payload does not
+ * need every intake issue's full text.
+ *
  * @param {object} raw
- * @returns {{ number: number, title: string, url: string, labels: string[] }|null}
+ * @returns {{ number: number, title: string, url: string, labels: string[], intake: boolean }|null}
  */
 function normalizeIssue(raw) {
   if (!raw || typeof raw !== 'object') return null;
@@ -144,12 +152,23 @@ function normalizeIssue(raw) {
   if (number === null) return null;
   const title = typeof raw.title === 'string' ? raw.title : '';
   const url = typeof raw.url === 'string' ? raw.url : '';
-  const labels = Array.isArray(raw.labels)
-    ? raw.labels
-        .map((l) => (l && typeof l === 'object' ? l.name : l))
-        .filter((name) => typeof name === 'string')
-    : [];
-  return { number, title, url, labels };
+  const intake =
+    typeof raw.body === 'string' && raw.body.includes(CI_GAP_INTAKE_MARKER);
+  return { number, title, url, labels: normalizeLabels(raw.labels), intake };
+}
+
+/**
+ * Flatten `gh issue list --json labels` into plain names. `gh` returns label
+ * objects; a hand-built fixture may return strings. Pure.
+ *
+ * @param {unknown} raw
+ * @returns {string[]}
+ */
+function normalizeLabels(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((l) => (l && typeof l === 'object' ? l.name : l))
+    .filter((name) => typeof name === 'string');
 }
 
 /**
@@ -176,7 +195,7 @@ async function fetchByLabel({ owner, repo, label, ghPath, limit, spawnImpl }) {
     '--label',
     label,
     '--json',
-    'number,title,labels,url',
+    'number,title,labels,url,body',
     '--limit',
     String(limit),
   ];
@@ -209,10 +228,32 @@ async function fetchByLabel({ owner, repo, label, ghPath, limit, spawnImpl }) {
 }
 
 /**
- * Fetch the union of open issues carrying either `meta::framework-gap` or
- * `meta::consumer-improvement` and split them into two arrays. Issues that
- * carry **both** labels appear in `frameworkGaps` only — dedupe-by-number
- * runs across both arrays so the planner sees each issue exactly once.
+ * Append every not-yet-seen issue to one bucket, marking it seen.
+ *
+ * An issue carrying more than one meta label must reach the planner exactly
+ * once, so the `seen` set spans all three buckets and the first bucket to
+ * claim a number keeps it. Mutates both arguments — one walk, three buckets.
+ *
+ * @param {object[]} bucket
+ * @param {object[]} issues
+ * @param {Set<number>} seen
+ * @returns {void}
+ */
+function dedupeInto(bucket, issues, seen) {
+  for (const issue of issues) {
+    if (seen.has(issue.number)) continue;
+    seen.add(issue.number);
+    bucket.push(issue);
+  }
+}
+
+/**
+ * Fetch the union of open issues carrying `meta::framework-gap`,
+ * `meta::consumer-improvement` or `meta::platform-gap` and split them into
+ * three arrays — one per ownership bucket in `github/framework-repo.js`, so
+ * a filing's bucket survives all the way to the planner. An issue carrying
+ * more than one label appears once, in that precedence order; dedupe-by-number
+ * runs across all three arrays so the planner sees each issue exactly once.
  *
  * The returned envelope is best-effort: every failure mode (gh missing, repo
  * not found, non-zero exit, malformed JSON) is captured as a string in
@@ -227,6 +268,7 @@ async function fetchByLabel({ owner, repo, label, ghPath, limit, spawnImpl }) {
  * @returns {Promise<{
  *   frameworkGaps: object[],
  *   consumerImprovements: object[],
+ *   platformGaps: object[],
  *   recurringDefectClasses: Array<{ class: string, count: number, issues: number[] }>,
  *   fetchedAt: string,
  *   errors: string[],
@@ -251,6 +293,7 @@ export async function fetchPriorFeedback({
   const envelope = {
     frameworkGaps: [],
     consumerImprovements: [],
+    platformGaps: [],
     recurringDefectClasses: [],
     fetchedAt: new Date().toISOString(),
     errors,
@@ -258,7 +301,7 @@ export async function fetchPriorFeedback({
 
   if (errors.length > 0) return envelope;
 
-  const [gapsResult, improvementsResult] = await Promise.all([
+  const [gapsResult, improvementsResult, platformResult] = await Promise.all([
     fetchByLabel({
       owner,
       repo,
@@ -275,25 +318,27 @@ export async function fetchPriorFeedback({
       limit,
       spawnImpl,
     }),
+    fetchByLabel({
+      owner,
+      repo,
+      label: META_LABELS.PLATFORM_GAP,
+      ghPath,
+      limit,
+      spawnImpl,
+    }),
   ]);
 
-  if (gapsResult.error) errors.push(gapsResult.error);
-  if (improvementsResult.error) errors.push(improvementsResult.error);
+  for (const { error } of [gapsResult, improvementsResult, platformResult]) {
+    if (error) errors.push(error);
+  }
 
   // Dedupe by issue number across both arrays. Issues that carry both labels
   // land in frameworkGaps first (deterministic) and are filtered out of
   // consumerImprovements.
   const seen = new Set();
-  for (const issue of gapsResult.issues) {
-    if (seen.has(issue.number)) continue;
-    seen.add(issue.number);
-    envelope.frameworkGaps.push(issue);
-  }
-  for (const issue of improvementsResult.issues) {
-    if (seen.has(issue.number)) continue;
-    seen.add(issue.number);
-    envelope.consumerImprovements.push(issue);
-  }
+  dedupeInto(envelope.frameworkGaps, gapsResult.issues, seen);
+  dedupeInto(envelope.consumerImprovements, improvementsResult.issues, seen);
+  dedupeInto(envelope.platformGaps, platformResult.issues, seen);
 
   // Story #4135 (Epic #4131, F11) — close the retro→planner loop: derive the
   // recurring defect classes from the `friction::<class>` labels carried by
@@ -303,6 +348,7 @@ export async function fetchPriorFeedback({
   envelope.recurringDefectClasses = extractRecurringDefectClasses([
     ...envelope.frameworkGaps,
     ...envelope.consumerImprovements,
+    ...envelope.platformGaps,
   ]);
 
   return envelope;

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -22,7 +22,10 @@
  * Routing correctness: a routed item already knows its source
  * (`framework` / `consumer`), so we file each source bucket with its own
  * constant classifier and thread the graduator's per-run filing cap across
- * the two buckets. The `meta::<framework-gap|consumer-improvement>` +
+ * the two buckets. Which repository a source routes to is decided once, in
+ * `github/framework-repo.js` — the silent consumer-repo fallback that used
+ * to live here (and mis-filed framework work into the consumer's tracker)
+ * is gone from the whole path, not just from this module. The `meta::<framework-gap|consumer-improvement>` +
  * `friction::<category>` labels are lifted verbatim from the routed item.
  *
  * Behind the `delivery.feedbackLoop.retroProposals` toggle (default ON,
@@ -30,7 +33,10 @@
  * failure path is captured in `errors[]`.
  */
 
-import { DEFAULT_FRAMEWORK_REPO } from '../github/framework-repo.js';
+import {
+  DEFAULT_FRAMEWORK_REPO,
+  parseRepoSlug,
+} from '../github/framework-repo.js';
 import { META_LABELS } from '../label-constants.js';
 import {
   contentFingerprint,
@@ -218,6 +224,8 @@ function toFinding(item, source, index) {
  * @param {{owner: string, repo: string}} opts.currentRepo — the repo the
  *   retro is running inside (the consumer's own repo); the cross-repo guard's
  *   anchor.
+ * @param {{owner: string, repo: string}} [opts.platformRepo] — the shared
+ *   platform/infra bucket, forwarded to the walk's routing SSOT.
  * @param {{owner: string, repo: string}} [opts.frameworkRepo] — where
  *   framework-tagged proposals route.
  * @param {{ framework?: object[], consumer?: object[] }} [opts.routedProposals]
@@ -239,6 +247,7 @@ export async function graduateRetroProposals({
   config,
   currentRepo,
   frameworkRepo,
+  platformRepo,
   routedProposals,
   ghPath,
   spawnImpl,
@@ -294,6 +303,7 @@ export async function graduateRetroProposals({
       config,
       currentRepo,
       frameworkRepo,
+      platformRepo,
       // Each bucket's source is known — a constant classifier routes the
       // whole bucket to the correct repo and stamps the correct label.
       classifier: () => source,
@@ -380,22 +390,6 @@ export function enrichRoutedProposalsWithFilings(routedProposals, filed) {
   };
 }
 
-/**
- * Parse an `"<owner>/<repo>"` slug into `{ owner, repo }`, or `null` when
- * the slug is empty / malformed.
- *
- * @param {string|null|undefined} slug
- * @returns {{ owner: string, repo: string } | null}
- */
-function parseRepoSlug(slug) {
-  if (typeof slug !== 'string') return null;
-  const parts = slug.split('/');
-  if (parts.length !== 2) return null;
-  const [owner, repo] = parts;
-  if (!owner || !repo) return null;
-  return { owner, repo };
-}
-
 /**
  * Orchestrating seam invoked by the retro post-and-mirror phase: gate the
  * toggle, file the routed proposals, and return the routed proposals
@@ -452,13 +446,12 @@ export async function fileRetroProposals({
     );
     return passthrough('no-current-repo');
   }
-  // Framework-repo fallback parity with `gatherRetroSignals`
-  // (gather-signals.js): an unconfigured `github.frameworkRepo` falls
-  // back to the Mandrel mirror constant, NEVER to the consumer's own
-  // repo — the prior `?? currentRepo` fallback silently auto-filed
-  // framework-tagged proposals into the consumer's repo while the retro
-  // body rendered them under "framework repo" (masked in this repo only
-  // because consumer === framework here).
+  // An unconfigured framework slug falls back to the Mandrel mirror
+  // constant, NEVER to the consumer's own repo: the retired consumer-repo
+  // fallback silently auto-filed framework-tagged proposals into the
+  // consumer's tracker while the retro body rendered them under "framework
+  // repo" (masked in this repo only because consumer === framework here).
+  // `github/framework-repo.js` is the SSOT for that rule now.
   const frameworkRepoObj =
     parseRepoSlug(frameworkRepo) ?? parseRepoSlug(DEFAULT_FRAMEWORK_REPO);
 

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
@@ -160,12 +161,14 @@ export function semanticKeyFooter(keys) {
 /**
  * Extract semantic keys from an Issue body carrying the semantic-key footer.
  * The audit filers stamp the footer via {@link semanticKeyFooter}; the
- * confirmation path here and {@link carryProvenanceFooters} read it back.
+ * confirmation path here, {@link carryProvenanceFooters} and the audit dedup's
+ * local issue index read it back. Exported alongside its writer so an indexer
+ * cannot drift into a second parse of the same footer.
  *
  * @param {string} body
  * @returns {string[]}
  */
-function parseSemanticKeyFooter(body) {
+export function parseSemanticKeyFooter(body) {
   return parseAllFooterValues(
     body,
     /<!--\s*audit-semantic-keys:\s*([^>]*?)\s*-->/g,
@@ -173,6 +176,43 @@ 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.
  *