mandrel 2.55.0 → 2.56.0

package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js

@@ -0,0 +1,197 @@
+/**
+ * lib/orchestration/plan-persist/audit-provenance.js — what an audit-seeded
+ * plan leaves behind for the next sweep.
+ *
+ * The chained `/mandrel-plan` path files Stories from an audit seed, and until
+ * Story #5307 those Stories were invisible to the sweep that proposed them:
+ * they carried no `audit::*` label, so they were absent from the label-listed
+ * corpus dedup indexes, and nothing recorded them in the cross-run ledger. The
+ * provenance footers `carryProvenanceFooters` stamps could not cover for
+ * either — with an index in play the exact lookup is answered from that pool
+ * and never reaches the provider.
+ *
+ * Both halves ride the create loop in `story-ops.js` because that is the only
+ * seam on this path that cannot be forgotten: there is no second required pass
+ * here the way `--wire-edges` is one for the standalone filer.
+ */
+
+import {
+  DEFAULT_LEDGER_PATH,
+  readLedger,
+  recordFiledIdentities,
+  writeLedger,
+} from '../../findings/audit-ledger.js';
+import {
+  parseAuditLabelFooter,
+  parseFingerprintFooter,
+  parseSemanticKeyFooter,
+} from '../../findings/route-finding.js';
+import { Logger } from '../../Logger.js';
+
+/**
+ * A fresh accumulator for one persist run's audit filings.
+ *
+ * The run collects into this and flushes once, so a plan that files N Stories
+ * leaves one reviewable ledger diff rather than N.
+ *
+ * @param {string} [ledgerPath]
+ * @returns {{ path: string, ledger: object|null, recorded: number, ambiguous: number }}
+ */
+function newAuditLedgerRecord(ledgerPath) {
+  return {
+    path: ledgerPath ?? DEFAULT_LEDGER_PATH,
+    ledger: null,
+    recorded: 0,
+    ambiguous: 0,
+  };
+}
+
+/**
+ * Merge the seed's `audit::*` labels into an audit-seeded Story's labels.
+ *
+ * Taken from the **seed union**, not from the attributed provenance source: a
+ * label only scopes which issues the next sweep's corpus fetch returns, and
+ * matching inside that corpus is by fingerprint and semantic key. A superset
+ * corpus can therefore only ever find more, never less — so erring wide is the
+ * safe direction, and it keeps lens-to-label knowledge in the audit filer that
+ * owns it rather than re-deriving a dimension here (the junk-derivation trap
+ * Story #4195 closed).
+ *
+ * A non-audit seed carries no such footer, so this is a no-op there.
+ *
+ * @param {Array<object>} stories — the assembled Stories.
+ * @param {string} [provenanceSource] — the seed this plan was authored from.
+ * @returns {Array<object>}
+ */
+export function withAuditLabels(stories, provenanceSource) {
+  const fromSeed = parseAuditLabelFooter(provenanceSource ?? '');
+  if (fromSeed.length === 0) return stories;
+  return stories.map((story) => ({
+    ...story,
+    labels: [...new Set([...story.labels, ...fromSeed])],
+  }));
+}
+
+/**
+ * Record one just-created Story in the cross-run audit ledger.
+ *
+ * The identities are read back off the body this run assembled, so what is
+ * recorded is exactly what was stamped — attribution already applied. A Story
+ * from a non-audit plan carries no footers and records nothing, which is why
+ * a `--seed` or `--tickets` run never touches the ledger file at all.
+ *
+ * **The union fallback is deliberately NOT recorded.** When the seed carried
+ * footers but the plan attributed none per-Story, every sibling carries every
+ * fingerprint; binding a finding to one of them would be a coin flip, and a
+ * wrong binding is worse than none — the finding would be suppressed against an
+ * Issue that never tracked it, or resurrected when an unrelated Story closed.
+ * The audit path stamps `provenance` mechanically, so this is the exception.
+ *
+ * @param {{ story: object, id: number, ledgerRecord: object, attributed: boolean }} args
+ */
+function recordAuditFiling({ story, id, ledgerRecord, attributed }) {
+  const fingerprints = parseFingerprintFooter(story.body);
+  if (fingerprints.length === 0) return;
+  if (!attributed) {
+    ledgerRecord.ambiguous += fingerprints.length;
+    return;
+  }
+  const semanticKeys = parseSemanticKeyFooter(story.body);
+  const identities = fingerprints.map((fingerprint, i) => ({
+    fingerprint,
+    semanticKey: semanticKeys[i] ?? '',
+    title: story.title,
+  }));
+  const { ledger, recorded } = recordFiledIdentities({
+    ledger: ledgerRecord.ledger ?? readLedger(ledgerRecord.path),
+    identities,
+    issue: { number: id },
+  });
+  ledgerRecord.ledger = ledger;
+  ledgerRecord.recorded += recorded;
+}
+
+/**
+ * Persist the run's audit filings, once, after every Story exists.
+ *
+ * Writing per-Story would rewrite a committed baseline N times for one plan;
+ * writing once keeps the diff to a single reviewable change. A run that
+ * recorded nothing writes nothing.
+ *
+ * @param {object} ledgerRecord
+ * @param {{ warn: Function }} logger
+ */
+function flushAuditLedger(ledgerRecord, logger) {
+  if (ledgerRecord.ambiguous > 0) {
+    logger.warn(
+      `[plan-persist] audit ledger: ${ledgerRecord.ambiguous} identity(ies) not recorded — ` +
+        'the seed carried provenance footers but no Story attributed them, so ownership is ' +
+        'ambiguous. Author per-Story `provenance` to record them.',
+    );
+  }
+  if (!ledgerRecord.ledger || ledgerRecord.recorded === 0) return;
+  writeLedger(ledgerRecord.path, ledgerRecord.ledger);
+  logger.warn(
+    `[plan-persist] audit ledger: recorded ${ledgerRecord.recorded} filed finding(s) ` +
+      `to ${ledgerRecord.path}.`,
+  );
+}
+
+/**
+ * Record everything one persist run filed, once, after every Story exists.
+ *
+ * Driven from the persist orchestrator rather than from inside the create loop:
+ * the loop's job is to create issues, and this is the only other place that
+ * always runs after it. Either seam is unforgettable — there is no second
+ * required pass on this path the way `--wire-edges` is one for the standalone
+ * filer — and keeping the side effect at the orchestration layer leaves the
+ * create loop doing one thing.
+ *
+ * One write per plan, not per Story: the ledger is committed state, and N
+ * rewrites of it for one plan is a diff nobody can review. A run that recorded
+ * nothing — a non-audit plan, or one whose identities were all union-carried —
+ * writes nothing at all.
+ *
+ * @param {object} params
+ * @param {Array<object>} params.stories — the assembled Stories.
+ * @param {Array<{ slug: string, id: number }>} params.created — persist receipts.
+ * @param {Array<object>} params.tickets — the raw authored tickets.
+ * @param {string} [params.ledgerPath]
+ * @param {{ warn: Function }} [params.logger]
+ * @param {boolean} [params.dryRun] — a dry run records nothing at all.
+ * @returns {{ recorded: number, ambiguous: number }}
+ */
+export function recordAuditFilings({
+  stories,
+  created,
+  tickets,
+  ledgerPath,
+  logger,
+  dryRun = false,
+}) {
+  // A dry run created no issue to record against, and must not touch committed
+  // state. Owned here rather than at the call site so the contract is testable.
+  if (dryRun) return { recorded: 0, ambiguous: 0 };
+  const record = newAuditLedgerRecord(ledgerPath);
+  const idBySlug = new Map((created ?? []).map((c) => [c.slug, c.id]));
+  // Attribution is a property of what the plan AUTHORED, so it is read off the
+  // raw tickets rather than threaded through assembly: a Story that declared no
+  // `provenance` inherited the seed union, where ownership is a coin flip.
+  const attributedSlugs = new Set(
+    (tickets ?? [])
+      .filter((t) => t?.provenance !== undefined && t?.provenance !== null)
+      .map((t) => t?.slug),
+  );
+  for (const story of stories ?? []) {
+    const id = idBySlug.get(story.slug);
+    if (typeof id !== 'number') continue;
+    recordAuditFiling({
+      story,
+      id,
+      ledgerRecord: record,
+      attributed: attributedSlugs.has(story.slug),
+    });
+  }
+  flushAuditLedger(record, logger ?? Logger);
+  return { recorded: record.recorded, ambiguous: record.ambiguous };
+}

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -68,6 +68,7 @@ import {
   renderHardConflictError,
 } from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
+import { recordAuditFilings, withAuditLabels } from './audit-provenance.js';
 import {
   resolveContainerEpic,
   resolveCrossPlanLinks,
@@ -780,7 +781,8 @@ export async function runPlanPersist({
   });
 
   // Split policy + inline Spec fold (over-budget Specs fail closed — no docs/).
-  const { stories } = assemblePlanStories(rawStories, {
+  const seedContent = planContextEnvelope?.seed?.content ?? '';
+  const { stories: assembled } = assemblePlanStories(rawStories, {
     sharedSpec: techSpecContent,
     planAcceptance: planAcceptance ?? undefined,
     sourceTicketIds,
@@ -791,9 +793,16 @@ export async function runPlanPersist({
     // is the **fallback** — it is carried onto every Story that did not
     // attribute its own `provenance`, which keeps an un-attributed plan exactly
     // as recall-safe as it was. Empty for a `--tickets` run, a no-op there.
-    provenanceSource: planContextEnvelope?.seed?.content ?? '',
+    provenanceSource: seedContent,
   });
 
+  // Stamp the `audit::*` labels the dedup corpus is listed by. Without them a
+  // Story this path files is absent from the pool an indexed sweep matches
+  // against, and an indexed run answers exact lookups from that pool without
+  // ever reaching the provider — so the provenance footers alone leave it
+  // invisible (Story #5307). A non-audit seed carries none: a no-op there.
+  const stories = withAuditLabels(assembled, seedContent);
+
   // Story #5045: the cross-Story conflict passes re-run over the assembled,
   // footer-stamped bodies — the artifact persist actually writes — before any
   // GitHub call, so a policy upgrade still refuses the plan pre-creation.
@@ -824,6 +833,10 @@ export async function runPlanPersist({
       opts: { dryRun, routeLabel: isLiteRoute ? LITE_ROUTE_LABEL : null },
     });
 
+  // What this run filed, recorded where the next audit sweep reads it
+  // (Story #5307). A dry run created nothing, and the call knows it.
+  recordAuditFilings({ stories, created, tickets: rawStories, dryRun });
+
   const primary = created[0];
   const waveTable = buildWaveTable(
     stories.map((s) => ({

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -683,10 +683,10 @@ async function executeFollowUpRollup({
     provider,
     config,
     currentRepo: repos.currentRepo,
-    frameworkRepo: (() => {
-      const [owner, repo] = repos.frameworkRepo.split('/');
-      return { owner, repo };
-    })(),
+    // The resolved bucket object, not a re-split of the slug: routing is
+    // decided once in `github/framework-repo.js`.
+    frameworkRepo: repos.repos.framework,
+    platformRepo: repos.repos.platform,
     routedProposals: proposals,
     cwd,
   });

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -11,7 +11,11 @@
 
 import { signalsFile } from '../config/temp-paths.js';
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
-import { DEFAULT_FRAMEWORK_REPO } from '../github/framework-repo.js';
+import {
+  DEFAULT_FRAMEWORK_REPO,
+  formatRepoSlug,
+  resolveOwnershipRepos,
+} from '../github/framework-repo.js';
 import { Logger } from '../Logger.js';
 import { normalizeGatheredSignal } from '../observability/runtime-friction.js';
 import {
@@ -54,28 +58,36 @@ function resolveFrictionWindowDays(config) {
 }
 
 /**
+ * Resolve the follow-up ownership buckets for the retro composer and the
+ * graduator walk.
+ *
+ * Routing itself lives in `github/framework-repo.js` — this is the slug-shaped
+ * adapter the composer wants (`composeRoutedProposals` renders slugs in prose)
+ * plus the `{owner, repo}` map `graduate()` routes on. The `platform` bucket
+ * has **no default**: an unconfigured shared-infra repo stays `null` so a
+ * caller reports it rather than filing platform-owned work somewhere plausible.
+ *
  * @param {object} [config]
- * @returns {{ frameworkRepo: string, consumerRepo: string, currentRepo: { owner: string, repo: string } }}
+ * @returns {{ frameworkRepo: string, consumerRepo: string, platform: (string|null), currentRepo: { owner: string, repo: string }, repos: { consumer: object|null, framework: object|null, platform: object|null } }}
  */
 export function resolveFollowUpRepos(config) {
-  const owner =
-    typeof config?.github?.owner === 'string' ? config.github.owner.trim() : '';
-  const repo =
-    typeof config?.github?.repo === 'string' ? config.github.repo.trim() : '';
-  const consumerRepo =
-    owner && repo ? `${owner}/${repo}` : DEFAULT_FRAMEWORK_REPO;
-  const frameworkRepo =
-    typeof config?.github?.frameworkRepo === 'string' &&
-    config.github.frameworkRepo.trim()
-      ? config.github.frameworkRepo.trim()
-      : DEFAULT_FRAMEWORK_REPO;
+  const repos = resolveOwnershipRepos(config);
+  const consumerRepo = formatRepoSlug(repos.consumer) ?? DEFAULT_FRAMEWORK_REPO;
+  // `resolveOwnershipRepos` always resolves the framework bucket (it defaults
+  // to the mirror constant), and both slugs above are well-formed by
+  // construction — so neither the render nor the split can yield a blank half.
+  const frameworkRepo = formatRepoSlug(repos.framework);
   const [cOwner, cRepo] = consumerRepo.split('/');
+  const currentRepo = { owner: cOwner, repo: cRepo };
   return {
     frameworkRepo,
     consumerRepo,
-    currentRepo: {
-      owner: cOwner || 'unknown',
-      repo: cRepo || 'unknown',
+    platform: formatRepoSlug(repos.platform),
+    currentRepo,
+    repos: {
+      consumer: currentRepo,
+      framework: repos.framework,
+      platform: repos.platform,
     },
   };
 }
@@ -749,10 +761,10 @@ export async function captureStoryFollowUps({
       provider,
       config,
       currentRepo: repos.currentRepo,
-      frameworkRepo: (() => {
-        const [owner, repo] = repos.frameworkRepo.split('/');
-        return { owner, repo };
-      })(),
+      // The resolved bucket object, not a re-split of the slug: routing is
+      // decided once in `github/framework-repo.js`.
+      frameworkRepo: repos.repos.framework,
+      platformRepo: repos.repos.platform,
       routedProposals: proposals,
       cwd,
     });

package/.agents/scripts/pr-watch-with-update.js

@@ -66,7 +66,8 @@
  * green can already have merged by the time it is observed. On red the
  * watcher disarms auto-merge and records the head SHA; on green it reads
  * the digest and adjudicates: a green on the SAME head SHA is a forbidden
- * re-run (exit 1, `agent::blocked`, `meta::framework-gap` required), while
+ * re-run (exit 1, `agent::blocked`, a `file-ci-gap.js` intake filing
+ *             required), while
  * a green on a NEW head SHA is a fix at source — the digest is retired,
  * auto-merge is re-armed, and the delivery proceeds. A delivery that never
  * went red has no digest and is untouched. Mechanism:
@@ -475,7 +476,7 @@ async function evaluateGreenWatch({
     `[pr-watch] run link: ${digest.runUrl ?? `run id ${digest.runId ?? 'unresolved'}`} — classification: ${digest.classification ?? 'unknown'}`,
   );
   logger.error?.(
-    '[pr-watch] fix the root cause and push a new commit, or file a `meta::framework-gap` issue carrying the run link and failure signature.',
+    '[pr-watch] fix the root cause and push a new commit, or — when the root cause is outside this delivery — run `node .agents/scripts/file-ci-gap.js --story <id> --verdict <verdict> --owner <bucket> --block` to file the routed, deduped intake issue.',
   );
   const outcome = await blockFn({ storyId, body });
   return {

package/.agents/workflows/audit-to-stories.md

@@ -181,6 +181,14 @@ persists, via `carryProvenanceFooters`
 The carry is additive, union-preserving and idempotent, so a resumed persist
 cannot stack footers and a hand-authored fingerprint is never dropped.
 
+**Persist records the ledger and the labels too.** It stamps the seed's
+`audit::<dimension>` labels — the dedup corpus is listed by them, and an indexed
+run answers lookups from that pool without reaching the provider, so a footer
+alone leaves a plan-path Story invisible — and records each Story's
+**attributed** identities. Union-only identities are not recorded: every sibling
+carries every fingerprint, so an owner would be a coin flip; persist says so on
+stderr. Author per-Story `provenance` to record them.
+
 This is deliberately not an authoring step. It used to be: the footers reached
 the seed and stopped there, leaving the authoring agent to notice HTML comments
 in a one-pager and copy them forward — a remembered step, which is to say no
@@ -243,6 +251,14 @@ every Story that has a resolvable blocker with a canonical
 GitHub `blocked_by` relations. An edge whose target was never opened (deduped,
 ledger-suppressed) drops rather than becoming a `blocked by #undefined`.
 
+**This pass also records the ledger.** The `--ids` map is the only artifact
+carrying the numbers just opened, so `--wire-edges` folds in the cross-run
+record: each mapped group's findings are written `filed` against its Issue
+(`--ledger <path>`, default `baselines/audit-ledger.json`; `--dry-run`
+suppresses the write). The record runs **before** the provider loads, so a host
+with no `gh` still remembers what it filed. Without it nothing ever writes
+`filed` and the ledger suppresses nothing.
+
 **Do not skip this.** `/mandrel-deliver` has no other source for this cohort's order:
 its footprint guard ignores the shared provenance footers, so an unwired cohort
 is genuinely unordered and `/mandrel-deliver` will co-dispatch Stories the edges say
@@ -277,31 +293,45 @@ the `classifications` array:
   is skipped by default; flag in the Phase 7 summary so the operator
   can decide whether to reopen.
 
-`routeFinding` is handed a `searchIssues` port adapted from the
-project's existing GitHub provider — the actual search runs against the
-repo's open + closed issues for each sha in the group, and the helper's
-footer-confirmation step filters out false-positive search hits whose
-body mentions the sha in prose without the canonical marker. The
-workflow owns **no** parallel dedup or footer-parsing code: the
-fingerprint, footer round-trip, and routing all live in that one shared
-module.
-
-Dedup runs in **two stages** when a provider resolves: a
-meaning-first **semantic candidate** pass (`searchCandidates`, wired to
-[`lib/findings/semantic-issue-search.js`](../scripts/lib/findings/semantic-issue-search.js))
-runs FIRST and widens the net across open + closed issues; the exact
-**fingerprint / semantic-key** confirmation runs SECOND. A finding whose title
-was reworded but whose *location* is unchanged still confirms against the Issue
-that already tracks that location, because the audit filers stamp a
-location-based `audit-semantic-keys` footer alongside the `audit-fingerprints`
-footer. Filings from the
+`routeFinding` reads open + closed issues through two ports, which **both run
+and union their pools** — the exact `searchIssues` lookup, and the meaning-first
+`searchCandidates` pass wired to
+[`lib/findings/semantic-issue-search.js`](../scripts/lib/findings/semantic-issue-search.js).
+Confirmation then filters that union by footer, dropping hits whose body
+mentions a sha in prose without the canonical marker. A finding reworded but
+unmoved still confirms, because the filers stamp a location-based
+`audit-semantic-keys` footer
+beside `audit-fingerprints`; so do
 [`retro-proposals-graduator`](../scripts/lib/feedback-loop/retro-proposals-graduator.js)
-carry the same canonical `audit-fingerprints` footer, so a sweep recognizes a
-graduator-filed issue and never re-files it.
+filings, which a sweep therefore never re-files.
+
+Where the corpus is pre-fetched — either off the list endpoint or from
+`--issues-file` — the exact lookup is answered from that local index and the
+search API is spent only on findings with no exact hit. The workflow owns **no**
+parallel dedup or footer-parsing code: fingerprint, footer round-trip, and
+routing all live in that one shared module.
+
+### When there is no `gh` CLI
+
+**No GitHub access** (air-gapped): pass `--no-provider` to `--scan`. Every
+group is classified `create` and the operator is told dedupe was skipped — a
+re-run opens duplicates.
+
+**Reachable, but not through `gh`** (a cloud sandbox: no `gh`, no direct API,
+MCP fine): fetch the corpus yourself. List every issue labelled `audit::*` at
+state `all` — `mcp__github__list_issues` or any other path — write the raw
+result as a JSON array, and pass it:
+
+```bash
+node .agents/scripts/audit-to-stories.js --scan --no-provider \
+  --issues-file temp/audits/issues.json --glob "temp/audits/audit-*-results.md"
+```
 
-When no provider is available (e.g. air-gapped dev environment), pass
-`--no-provider` to the `--scan` step — every group is classified
-`create` and the operator is informed that dedupe was skipped.
+Real `skip-open` / `skip-reoccurring` classifications come back. The corpus is
+normalised on load, so a raw list result works as-is; only `number` and `body`
+are read. An unreadable file is a hard error, never a silent fall-back to an
+unchecked run; an **empty** array — a valid first sweep — is reported with its
+count so it cannot pass for a failed fetch.
 
 ### Cross-run ledger
 
@@ -314,8 +344,12 @@ shape). Each entry is keyed by the finding's fingerprint plus a location-based
 (`new | filed | fixed | accepted-risk | regressed`). A finding whose tracking
 Issue was closed as `not_planned` becomes `accepted-risk` and is **suppressed**
 on every later scan; a `fixed` finding that re-appears becomes `regressed`. The
-ledger is written by the unattended `--auto` sweep and by any `--scan --ledger`
-run; the plain `--scan` path leaves it untouched.
+ledger is written by the unattended `--auto` sweep, by any `--scan --ledger`
+run, by the Phase 5c `--wire-edges` pass, and by `plan-persist` on the Phase 5a
+chained path — the two filing paths both record what they filed; the
+plain `--scan` path leaves it untouched. A finding whose resolved Issue is open
+is recorded `filed` and is known on re-detection; a closed Issue still outranks
+that.
 
 ## Phase 7 — Summary & cleanup
 
@@ -391,8 +425,10 @@ The routine shape is **lenses full-scope → dry-run → live with a ledger PR**
 from `delivery.auditToStories.severityFloor` (default `high`, overridable with
 `--severity`), applies the two-stage dedup, reconciles the cross-run ledger,
 and prints a run-summary JSON (create / skip-open / skip-reoccurring /
-suppressed-by-ledger tallies, plus the re-detected open Issue numbers an
-operator may want a "re-detected" comment on). `--dry-run` performs zero GitHub
+suppressed-by-ledger tallies, the `create`-classified group keys the `--ids`
+map is built from, plus the re-detected open Issue numbers an operator may want
+a "re-detected" comment on). It opens no Issues itself, so run Phase 5c after
+filing or the sweep's memory stays empty. `--dry-run` performs zero GitHub
 writes and skips the ledger write, emitting only the summary.
 
 `--auto` **fails closed on any `summary.reportFailures[]` entry** (Phase 1): an

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -682,13 +682,28 @@ When the watch exits, branch on the exit code:
 
 **Triage authority.** How to classify and remediate a red (or repeatedly slow)
 check — the root-cause-only decision tree for infra/transient and flaky failures
-(reproduce → check `main` → bisect env vs code → fix in-scope or file a
-`meta::framework-gap` issue), the never-rerun / never-quarantine prohibitions,
-and the escalation criteria (three-strikes, the 30-minute wall-clock timebox,
-and the clearly-environmental fast path) — is defined once in
+(reproduce → check `main` → bisect env vs code → fix in-scope, or reach an
+Option-2 verdict and file the intake issue), the never-rerun / never-quarantine
+prohibitions, and the escalation criteria (three-strikes, the 30-minute
+wall-clock timebox, and the clearly-environmental fast path) — is defined once in
 [`.agents/rules/ci-remediation.md`](../../rules/ci-remediation.md). Read it
 before remediating a red check.
 
+**Filing an out-of-scope root cause is one command, never a hand-run `gh issue
+create`:**
+
+```bash
+node <agentRoot>/scripts/file-ci-gap.js --story <storyId> \
+  --verdict <pre-existing|capacity|unreproducible-tier> \
+  --owner <consumer|framework|platform> --evidence "<proof reading>" [--block]
+```
+
+It reads the digest, routes the filing to the repo that owns the fault, updates
+the existing ticket when the signature is a repeat, posts the `friction`
+comment, and with `--block` flips the Story. What it files is an **intake**
+issue, not a Story — `/mandrel-plan <issue number>` graduates it on the next
+planning pass, so the delivery never waits on planning.
+
 ### The auto-merge wait is an internally-blocking step
 
 This is the single most important contract of this workflow, and the seam

package/.agents/workflows/helpers/plan-reference.md

@@ -99,6 +99,29 @@ On a truthy `memoryPoolAdvisory.recommend`, name
 `reasons[]`. Purely advisory: a stale pool degrades recall, it does not make
 the plan wrong, so it never blocks and never reroutes.
 
+## Gate #1 → graduating a CI-gap intake filing (`intake`)
+
+The envelope's `priorFeedback` arrays carry the open `meta::*` feedback issues.
+A row flagged `intake: true` is a **CI-gap intake filing** — written by
+[`file-ci-gap.js`](../../scripts/file-ci-gap.js) when a delivery reached an
+Option-2 verdict in [`ci-remediation.md`](../../rules/ci-remediation.md) and the
+root cause was outside its scope. It carries evidence (failure signature, run
+link, occurrence history, ownership routing) but **no `## Spec`, no
+`acceptance[]` / `verify[]` and no `agent::*` label**, so `/mandrel-deliver`
+cannot take it: it is intake awaiting graduation, by design. Delivery files it
+and moves on rather than blocking on a planning pass nobody is present for.
+
+Graduating one is exactly **tickets mode**: `/mandrel-plan <issue number>`
+rewrites it into a Story, `supersedes[]` claims it, and persist closes it.
+
+At Gate #1, in **ask** and **seed** mode, name any open intake rows and offer
+that instead of the seed in front of you — a filing that keeps recurring
+(its `## Occurrences` table is the count) is usually the better next Story than
+whatever prompted this run. It is **advisory**: never reroute automatically, and
+skip the offer entirely under `--yes`, where nobody is at the keyboard to take
+it. A `platformGaps[]` row is the same shape with a different owner — the
+Story it graduates into may well be a config or runbook change rather than code.
+
 ## Gate #1 → the light path (in-session handoff)
 
 On a confirmed `deliverLightSuggestion`, `/mandrel-plan` routes into

package/.agents/workflows/mandrel-plan.md

@@ -58,10 +58,9 @@ and derives source ids from its `sourceTickets[]`; it also writes
 
 The envelope carries docs context, the story-author prompt, `sourceTickets[]`,
 `duplicates[]` (open **Stories**, never Epics), `epicCandidates[]` +
-`dependencyCandidates[]` (Gate #3; path collisions) and advisory
-`complexitySignals` (**no routing authority**). A trivial scope can claim the
-lite route at persist — shape-validated, failing closed to `full`
-([ref](helpers/plan-reference.md)).
+`dependencyCandidates[]` (Gate #3; path collisions), `priorFeedback` and
+advisory `complexitySignals` (**no routing authority**). A trivial scope claims
+the lite route at persist, failing closed to `full`.
 
 **Triage each unknown by resolver** ([ref](helpers/plan-reference.md)): an
 **AFK** unknown (research settles it) is resolved before authoring, never
@@ -69,8 +68,9 @@ assumed; a **HITL** unknown goes to Gate #1. Under `--yes` do not ask free-form
 operator questions — AFK unknowns are still researched; only HITL unknowns land
 in Key Assumptions, each a decision-made-by-default.
 
-**Gate #1** — STOP to confirm the sharpened plan intent and any
-duplicate-candidate review. Under `--yes`, auto-proceed.
+**Gate #1** — STOP to confirm the sharpened plan intent, any
+duplicate-candidate review, and any `intake` row worth graduating
+([ref](helpers/plan-reference.md)). Under `--yes`, auto-proceed.
 
 On a truthy `deliverLightSuggestion.suggested`, offer — advisory, never an
 automatic reroute — to deliver the seed instead; on confirm route **in this

package/docs/CHANGELOG.md

@@ -15,6 +15,16 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.56.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.55.0...mandrel-v2.56.0) (2026-09-11)
+
+
+### Added
+
+* audit-to-stories: dedup against a host-supplied issue index, so a sweep on a gh-less host stops re-filing what it already filed ([#5301](https://github.com/dsj1984/mandrel/issues/5301)) ([#5304](https://github.com/dsj1984/mandrel/issues/5304)) ([1b8abf0](https://github.com/dsj1984/mandrel/commit/1b8abf072a05db65e54a63cb8ec6cf6f06bc80ab))
+* audit-to-stories: make Phase 5a filings visible to the next sweep — record the ledger from plan-persist and stamp the audit labels the corpus is listed by ([#5307](https://github.com/dsj1984/mandrel/issues/5307)) ([#5308](https://github.com/dsj1984/mandrel/issues/5308)) ([094ba8a](https://github.com/dsj1984/mandrel/commit/094ba8ae6e2640ba3ac7cb5a4aeb9309aa72e42d))
+* audit-to-stories: record filed Issues in the cross-run ledger, so its suppression branch stops being unreachable ([#5305](https://github.com/dsj1984/mandrel/issues/5305)) ([#5306](https://github.com/dsj1984/mandrel/issues/5306)) ([d5e36ab](https://github.com/dsj1984/mandrel/commit/d5e36ab796f6946bf93d7161efa1470cad8a0a2b))
+* cI-gap intake: script-backed, repo-routed, deduped meta filings that /mandrel-plan can graduate ([#5300](https://github.com/dsj1984/mandrel/issues/5300)) ([#5302](https://github.com/dsj1984/mandrel/issues/5302)) ([37bc287](https://github.com/dsj1984/mandrel/commit/37bc2875ed8c98298afd90c72ece4f318e2c233d))
+
 ## [2.55.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.54.0...mandrel-v2.55.0) (2026-09-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",