mandrel 2.55.0 → 2.56.0

package/.agents/scripts/lib/audit-to-stories/issues-file.js

@@ -0,0 +1,121 @@
+/**
+ * lib/audit-to-stories/issues-file.js — the issue corpus dedup checks against,
+ * and the one normaliser every source of it goes through.
+ *
+ * Dedup needs exactly one thing from GitHub: the list of Issues carrying an
+ * `audit::*` label. Until Story #5301 the only way to get it was the provider,
+ * which spawns `gh`, so a host without a `gh` CLI — a Claude Code cloud
+ * sandbox, where `gh` is absent and direct API access is disabled but the
+ * GitHub MCP tools work fine — could not dedup at all. Every group classified
+ * `create` and a scheduled sweep re-filed findings it had already filed.
+ *
+ * `--issues-file <path>` breaks that coupling: the host fetches the list by
+ * whatever access path it has and hands over a JSON array. Nothing here knows
+ * how it was fetched, so MCP, REST, and a cached dump are all equally valid.
+ *
+ * A file that cannot be read as an issue array is a **hard error**, never a
+ * degrade. Falling back would mean "dedup did not run" on precisely the
+ * invocation whose whole purpose is that it does — and a create-only plan the
+ * operator reads as checked is how the duplicate-filing loop starts.
+ */
+
+import fs from 'node:fs';
+
+/**
+ * Flatten one raw issue onto the `{ number, state, title, body }` shape the
+ * dedupe module reads, collapsing every closed-ish state spelling (`CLOSED`,
+ * `state_reason: not_planned`, …) onto `'closed'`.
+ *
+ * Shared by both corpus sources — the provider's `searchIssues` hits and the
+ * `--issues-file` array — so a host can hand over a raw `list_issues` result
+ * verbatim without knowing which spelling this repo's dedup expects.
+ *
+ * @param {object} hit
+ * @returns {{ number: number, state: 'open'|'closed', title: string, body: string }}
+ */
+export function normaliseIssueHit(hit) {
+  return {
+    number: hit.number,
+    state: (hit.state ?? hit.state_reason ?? 'open')
+      .toString()
+      .toLowerCase()
+      .includes('closed')
+      ? 'closed'
+      : 'open',
+    title: hit.title ?? '',
+    body: hit.body ?? '',
+  };
+}
+
+/**
+ * Read and normalise a host-supplied issue corpus.
+ *
+ * `state` is read from either `state` or `state_reason`, so a closed-as-
+ * not-planned issue is recognised however the host's API spelled it. Only
+ * `number` and `body` are load-bearing: the number identifies the match and
+ * the body carries the provenance footers dedup confirms identity against.
+ *
+ * @param {string} filePath — path to a JSON array of issues.
+ * @param {{ readFileSyncImpl?: typeof fs.readFileSync }} [seams]
+ * @returns {Array<{ number: number, state: string, title: string, body: string }>}
+ * @throws {Error} when the file is missing, unreadable, not JSON, or not an array.
+ */
+export function loadIssuesFile(
+  filePath,
+  { readFileSyncImpl = fs.readFileSync } = {},
+) {
+  let raw;
+  try {
+    raw = readFileSyncImpl(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `--issues-file: cannot read "${filePath}" (${err.message}). Dedup needs ` +
+        'the issue corpus to check against; running without it would classify ' +
+        'every group "create" and re-file findings already tracked.',
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `--issues-file: "${filePath}" is not valid JSON (${err.message}). ` +
+        'Expected a JSON array of issues, e.g. the result of listing every ' +
+        'issue labelled audit::* with state "all".',
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(
+      `--issues-file: "${filePath}" holds ${describeShape(parsed)}, not a JSON ` +
+        'array of issues. Pass the issue list itself, not the envelope wrapping it.',
+    );
+  }
+  return parsed.filter(isIssueLike).map(normaliseIssueHit);
+}
+
+/**
+ * Whether one array entry can possibly identify an issue. An entry without a
+ * numeric `number` can never confirm a match — exactly as it could not when it
+ * came back from a search — so it is dropped rather than indexed under nothing.
+ *
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+function isIssueLike(entry) {
+  return (
+    Boolean(entry) &&
+    typeof entry === 'object' &&
+    typeof entry.number === 'number'
+  );
+}
+
+/**
+ * Name what a non-array payload actually was, so the error points at the fix.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeShape(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `a JSON ${typeof value}`;
+}

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

@@ -28,9 +28,9 @@
  * complexity budget does not absorb a git driver.
  */
 
+import { DEFAULT_LEDGER_PATH } from '../findings/audit-ledger.js';
 import { gh as defaultGh } from '../gh-exec.js';
 import { gitSync } from '../git-utils.js';
-import { DEFAULT_LEDGER_PATH } from './ledger.js';
 import { openLedgerPullRequest, probeGit } from './ledger-pr.js';
 
 /** Fallback base branch when config carries no `project.baseBranch`. */

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

@@ -0,0 +1,126 @@
+/**
+ * lib/audit-to-stories/ledger-record.js — record what a run actually filed.
+ *
+ * The cross-run ledger can only suppress an already-filed finding if something
+ * tells it the finding was filed. Until Story #5305 nothing did: the reconcile
+ * ran *during* the scan, before any Issue existed, and its `issueStates` were
+ * derived from `matchedIssues` — the Issues dedup FOUND. A group classified
+ * `create` has none, so a freshly opened Issue contributed nothing and its
+ * entry persisted as `status: "new", issue: null` forever. On a host where
+ * GitHub-search dedup works that is invisible; on one where it cannot run,
+ * nothing suppresses anything and every sweep re-files everything.
+ *
+ * The missing input is the `groupKey → issueNumber` map, which exists only
+ * after the Issues are opened. `--wire-edges` already takes exactly that map
+ * and is already a required pass, which is why the record rides along with it
+ * rather than arriving as a second command an operator must remember.
+ *
+ * Nothing here reaches the network: the caller hands over the map it already
+ * holds, and the only I/O is the ledger read/write this module delegates to
+ * `ledger.js`. That is what lets the record run BEFORE the provider is loaded,
+ * so a host whose provider cannot be constructed still records what it filed.
+ */
+
+import {
+  DEFAULT_LEDGER_PATH,
+  readLedger,
+  reconcileLedger,
+  writeLedger,
+} from '../findings/audit-ledger.js';
+import {
+  fingerprintAuditFinding,
+  toCanonicalFinding,
+} from './finding-adapter.js';
+
+/**
+ * Project the opened-issue map onto the `{ fingerprint → issueState }` shape
+ * `reconcileLedger` reads, and collect the findings those groups carry.
+ *
+ * Only groups present in the map contribute. A group the map does not mention
+ * was not opened — deduped, ledger-suppressed, or simply skipped — and
+ * inventing an Issue state for it is how a finding gets suppressed against an
+ * Issue that does not exist.
+ *
+ * Every recorded state is `open`: the map names Issues this run just created,
+ * and a just-created Issue is open. A later close is learned from the live
+ * lookup on the next run, where it outranks this record (`decideStatus` reads
+ * the closed-Issue branch first).
+ *
+ * @param {object} params
+ * @param {Array<object>} params.groups — the `create`-eligible groups.
+ * @param {Record<string, number>} params.issueByGroupKey — group key → issue number.
+ * Module-internal: `recordFiledIssues` is the only production entrypoint, and
+ * exporting this for tests alone trips the CI-only `dead-exports:production`
+ * gate. It is covered through `recordFiledIssues`, which is the seam that
+ * actually ships.
+ *
+ * @returns {{ findings: Array<object>, issueStates: Record<string, { state: string, number: number }>, groupsRecorded: number }}
+ */
+function issueStatesFromIssueMap({ groups, issueByGroupKey }) {
+  const findings = [];
+  const issueStates = {};
+  let groupsRecorded = 0;
+
+  for (const group of groups ?? []) {
+    const number = issueByGroupKey?.[group?.groupKey];
+    if (typeof number !== 'number') continue;
+    groupsRecorded += 1;
+    for (const finding of group.findings ?? []) {
+      findings.push(finding);
+      issueStates[fingerprintAuditFinding(finding).full] = {
+        state: 'open',
+        number,
+      };
+    }
+  }
+
+  return { findings, issueStates, groupsRecorded };
+}
+
+/**
+ * Fold the just-opened Issues onto the committed ledger.
+ *
+ * Only the mapped groups' findings are passed to `reconcileLedger`, so every
+ * other entry survives untouched — `reconcileLedger` copies the prior index
+ * forward and rewrites only what this scan hands it.
+ *
+ * @param {object} params
+ * @param {string} [params.ledgerPath]
+ * @param {Array<object>} params.groups — the `create`-eligible groups.
+ * @param {Record<string, number>} params.issueByGroupKey
+ * @param {boolean} [params.write=true] — `false` computes the record without
+ *   persisting it, which is what `--dry-run` needs.
+ * @param {{ readLedgerImpl?: Function, writeLedgerImpl?: Function }} [seams]
+ * @returns {{ path: string, written: boolean, groupsRecorded: number, findingsRecorded: number, filed: number }}
+ */
+export function recordFiledIssues(
+  { ledgerPath, groups, issueByGroupKey, write = true },
+  { readLedgerImpl = readLedger, writeLedgerImpl = writeLedger } = {},
+) {
+  const path = ledgerPath ?? DEFAULT_LEDGER_PATH;
+  const { findings, issueStates, groupsRecorded } = issueStatesFromIssueMap({
+    groups,
+    issueByGroupKey,
+  });
+
+  const { ledger: next, classifications } = reconcileLedger({
+    ledger: readLedgerImpl(path),
+    findings,
+    issueStates,
+    toCanonical: toCanonicalFinding,
+  });
+  // Nothing to record means nothing to write. The ledger is committed consumer
+  // state and `--ledger-commit` opens a PR only when it changed, so rewriting
+  // it with a fresh `generatedAt` and no new memory would manufacture a diff
+  // that says nothing.
+  const wrote = Boolean(write) && findings.length > 0;
+  if (wrote) writeLedgerImpl(path, next);
+
+  return {
+    path,
+    written: wrote,
+    groupsRecorded,
+    findingsRecorded: findings.length,
+    filed: classifications.filter((c) => c.status === 'filed').length,
+  };
+}

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

@@ -18,6 +18,7 @@
  */
 
 import { SEVERITIES } from '../findings/severity.js';
+import { auditLabelFooterForFindings } from './audit-label-taxonomy.js';
 import { formatEpicGrouping } from './epic-grouping-directive.js';
 import {
   renderFingerprintFooter,
@@ -107,6 +108,16 @@ function formatMVPScope(groups) {
       const footers = [
         renderFingerprintFooter(findings),
         renderSemanticKeyFooter(findings),
+        // ...and the `audit::*` labels the dedup corpus is listed by.
+        //
+        // Without them a Story the chained planning path files is absent from
+        // the pool an indexed sweep matches against, and with an index in play
+        // the exact lookup is answered from that pool without ever reaching
+        // the provider — so the fingerprint footer above cannot rescue it. The
+        // two footers are therefore a pair: one carries the identity, the
+        // other carries the reason the next sweep ever looks at this issue
+        // (Story #5307).
+        auditLabelFooterForFindings(findings),
       ]
         .map((f) => `   ${f}`)
         .join('\n');

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

@@ -16,6 +16,7 @@ import { SHELL_INJECTION_PATTERN_STRING } from './config-schema-shared.js';
 // resolved AGENTRC_SCHEMA is unchanged.
 import { DELIVERY_SCHEMA } from './config-settings-schema-delivery.js';
 import compiledAgentrcValidator from './generated/agentrc-validator.js';
+import { DEFAULT_FRAMEWORK_REPO } from './github/framework-repo.js';
 import { SKILL_ID_RE } from './skills/walk-skill-files.js';
 
 /**
@@ -386,6 +387,37 @@ const MERGE_METHODS_SCHEMA = {
   additionalProperties: false,
 };
 
+/**
+ * Where follow-up work is filed when the repository that surfaced it does not
+ * own it. Ownership splits three ways — consumer / framework / platform — and
+ * `github.owner`/`github.repo` already carry the consumer bucket, so only the
+ * other two are configured here. Routing itself lives in
+ * `lib/github/framework-repo.js`; an unset bucket is reported as unroutable
+ * rather than silently re-pointed at the consumer's own tracker.
+ */
+const FOLLOW_UP_REPOS_SCHEMA = {
+  type: 'object',
+  description:
+    'Repository slugs for the non-consumer follow-up ownership buckets, used when a CI gap, retro proposal, or audit finding belongs to someone other than the repo that surfaced it.',
+  properties: {
+    framework: {
+      type: 'string',
+      pattern: '^[^/\\s]+/[^/\\s]+$',
+      description:
+        '`<owner>/<repo>` that owns framework-level defects. Defaults to the Mandrel mirror — the one bucket with a knowable default.',
+      default: DEFAULT_FRAMEWORK_REPO,
+    },
+    platform: {
+      type: ['string', 'null'],
+      pattern: '^[^/\\s]+/[^/\\s]+$',
+      description:
+        '`<owner>/<repo>` for a shared platform or infrastructure tracker (a shared base config, a runner fleet, a cross-repo toolchain). No default — nothing can guess a shared repo. Left unset, platform-owned findings file locally and say so.',
+      default: null,
+    },
+  },
+  additionalProperties: false,
+};
+
 const GITHUB_SCHEMA = {
   type: 'object',
   description:
@@ -432,6 +464,7 @@ const GITHUB_SCHEMA = {
         'Default `timeoutMs` applied to every `gh` subprocess the provider facade spawns, so a stalled socket or long-poll cannot hang an orchestration indefinitely. A `GhExecTimeoutError` from a hit ceiling is classified `transient` and retried by `withTransientRetry`. Story #2860.',
       default: 60000,
     },
+    followUpRepos: FOLLOW_UP_REPOS_SCHEMA,
     branchProtection: BRANCH_PROTECTION_SCHEMA,
     mergeMethods: MERGE_METHODS_SCHEMA,
     notifications: NOTIFICATIONS_SCHEMA,

package/.agents/scripts/lib/feedback-loop/graduator-core.js

@@ -45,12 +45,18 @@
  *   - **Durable cross-repo deferral.** Cross-repo-deferred findings are
  *     upserted into a structured comment on the Epic instead of only a
  *     log line.
+ *   - **Routed, never re-pointed.** Ownership routing is delegated to
+ *     `github/framework-repo.js#routeOwnership`; an unroutable bucket is
+ *     skipped `unroutable` and named in that same durable comment. The
+ *     predecessor resolved an absent framework slug to the consumer's own
+ *     repo, which silently mis-filed framework-owned work.
  */
 
 import { spawn as defaultSpawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 
 import { inNodeTestContext } from '../config/temp-paths.js';
+import { routeOwnership } from '../github/framework-repo.js';
 import { LABEL_COLORS } from '../label-constants.js';
 import { classifyPathSource as defaultClassifier } from '../observability/source-classifier.js';
 import { upsertStructuredComment } from '../orchestration/ticketing.js';
@@ -531,7 +537,7 @@ async function findExistingFollowUp({
  *
  * @returns {Promise<{ url: string|null, error: string|null }>}
  */
-async function updateFollowUpIssue({
+export async function updateFollowUpIssue({
   owner,
   repo,
   number,
@@ -675,7 +681,7 @@ async function readLiveLabelNames({
  * @param {number} [opts.timeoutMs]
  * @returns {Promise<{ created: string[], missing: string[], errors: string[] }>}
  */
-async function ensureIssueLabels({
+export async function ensureIssueLabels({
   owner,
   repo,
   labels,
@@ -947,7 +953,7 @@ async function processGraduateFinding({
   decorate,
   epicId,
   currentRepo,
-  frameworkRepo,
+  repos,
   classifier,
   gitRef,
   ghPath,
@@ -994,12 +1000,26 @@ async function processGraduateFinding({
   }
 
   const source = classifier(finding.path, null);
-  const routedRepo =
-    source === 'framework' && frameworkRepo ? frameworkRepo : currentRepo;
-  const isCrossRepo =
-    routedRepo.owner !== currentRepo.owner ||
-    routedRepo.repo !== currentRepo.repo;
-  if (isCrossRepo) {
+  // Ownership routing is the shared SSOT's call, and an unroutable bucket is
+  // an outcome rather than a fallback: the predecessor resolved an absent
+  // framework slug to the CONSUMER's repo, silently filing framework-owned
+  // work in the wrong place (see `github/framework-repo.js`). Unroutable
+  // findings are deferred and named, never re-pointed.
+  const routing = routeOwnership({ bucket: source, repos, currentRepo });
+  if (!routing.routable) {
+    const logLine = `[${spec.fnName}] unroutable ${source} finding (${routing.missingKey} is unset) — not filed: ${finding.title ?? finding.path ?? `finding ${finding.index}`}`;
+    logger?.warn?.(logLine);
+    crossRepoDeferred.push({
+      finding,
+      routedRepo: null,
+      source,
+      logLine,
+      missingKey: routing.missingKey,
+    });
+    return skip('unroutable');
+  }
+  const routedRepo = routing.routedRepo;
+  if (routing.crossRepo) {
     const logLine = spec.buildCrossRepoLog({ finding, routedRepo, source });
     logger?.info?.(logLine);
     crossRepoDeferred.push({ finding, routedRepo, source, logLine });
@@ -1165,13 +1185,18 @@ function renderCrossRepoDeferredBody(deferred, spec) {
   const header =
     spec.crossRepoCommentHeader ??
     '### Cross-repo-deferred findings\n\nThese findings route to a different repository and were **not** filed here. They are recorded for a cross-repo follow-up pass.';
-  const rows = deferred.map(({ finding, routedRepo, logLine }) => {
+  const rows = deferred.map(({ finding, routedRepo, logLine, missingKey }) => {
     const path =
       typeof finding.path === 'string' && finding.path.length > 0
         ? `\`${finding.path}\``
         : '_(no path)_';
+    // An unroutable finding has no destination to name — say which config
+    // key would give it one instead of inventing a repo for the row.
+    const destination = routedRepo
+      ? `${routedRepo.owner}/${routedRepo.repo}`
+      : `**unroutable** (\`${missingKey}\` is unset)`;
     return [
-      `- ${path} (severity: ${finding.severity ?? 'n/a'}) → ${routedRepo.owner}/${routedRepo.repo}`,
+      `- ${path} (severity: ${finding.severity ?? 'n/a'}) → ${destination}`,
       `  - ${logLine}`,
     ].join('\n');
   });
@@ -1244,7 +1269,12 @@ async function persistCrossRepoDeferred({
  *   the durable cross-repo-deferred persistence
  * @param {object} [opts.config]
  * @param {{owner: string, repo: string}} opts.currentRepo
- * @param {{owner: string, repo: string}} [opts.frameworkRepo]
+ * @param {{owner: string, repo: string}} [opts.frameworkRepo] — the
+ *   `framework` ownership bucket. Absent means **unroutable**, never the
+ *   consumer's repo: a framework-classified finding is then deferred and
+ *   named rather than filed in the wrong tracker.
+ * @param {{owner: string, repo: string}} [opts.platformRepo] — the shared
+ *   platform/infra bucket, for a caller whose classifier can reach it.
  * @param {string} [opts.gitRef='HEAD']
  * @param {Function} [opts.classifier=classifyPathSource]
  * @param {string} [opts.ghPath='gh']
@@ -1279,6 +1309,7 @@ export async function graduate({
   config,
   currentRepo,
   frameworkRepo,
+  platformRepo,
   gitRef = 'HEAD',
   classifier = defaultClassifier,
   ghPath = 'gh',
@@ -1347,6 +1378,15 @@ export async function graduate({
     return envelope;
   }
 
+  // The ownership map the routing SSOT resolves against. `platform` is
+  // absent for both graduators today (their classifier is binary) and is
+  // threaded so a caller that does know a shared-infra repo routes there
+  // rather than into the nearest plausible tracker.
+  const repos = {
+    consumer: currentRepo,
+    framework: frameworkRepo ?? null,
+    platform: platformRepo ?? null,
+  };
   const crossRepoDeferred = [];
   for (const finding of findings) {
     await processGraduateFinding({
@@ -1355,7 +1395,7 @@ export async function graduate({
       decorate,
       epicId,
       currentRepo,
-      frameworkRepo,
+      repos,
       classifier,
       gitRef,
       ghPath,

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;