mandrel 2.32.0 → 2.34.0

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -17,6 +17,10 @@
 
 import { createHash } from 'node:crypto';
 import { applyBlockedByDependencies } from '../../../providers/github/blocked-by-add.js';
+import {
+  normalizeOwnedProvenance,
+  ownedProvenanceSource,
+} from '../../findings/provenance-field.js';
 import { carryProvenanceFooters } from '../../findings/route-finding.js';
 import { Logger } from '../../Logger.js';
 import { AGENT_LABELS, TYPE_LABELS } from '../../label-constants.js';
@@ -319,8 +323,12 @@ function syncContractFieldFromTopLevel(ticket, bodyObject, field) {
  * bookkeeping for the `--tickets` source issues, not part of the Story's
  * executable body, so it is deliberately not serialized into the markdown.
  *
+ * `provenance` is likewise top-level-only (Story #5045) — it names the audit
+ * identities *this* Story owns, and is stamped into the body as footers rather
+ * than serialized as a section.
+ *
  * @param {object} ticket
- * @returns {{ slug: string, title: string, bodyObject: object, depends_on: string[], labels: string[], supersedes: Array<{ id: number, note: string|null }> }}
+ * @returns {{ slug: string, title: string, bodyObject: object, depends_on: string[], labels: string[], supersedes: Array<{ id: number, note: string|null }>, provenance: { fingerprints: string[], semanticKeys: string[] }|null }}
  */
 export function normalizeStoryTicket(ticket) {
   if (!ticket || typeof ticket !== 'object') {
@@ -345,8 +353,22 @@ export function normalizeStoryTicket(ticket) {
   const depends_on = normalizeDependsOn(ticket, bodyObject);
   const supersedes = normalizeSupersedes(ticket, slug);
   const labels = sanitizeAuthoredLabels(ticket.labels, slug);
+  let provenance;
+  try {
+    provenance = normalizeOwnedProvenance(ticket.provenance, slug);
+  } catch (err) {
+    throw new Error(`[plan-persist] ${err.message}`);
+  }
 
-  return { slug, title, bodyObject, depends_on, labels, supersedes };
+  return {
+    slug,
+    title,
+    bodyObject,
+    depends_on,
+    labels,
+    supersedes,
+    provenance,
+  };
 }
 
 /**
@@ -388,24 +410,59 @@ export function foldSpecIntoStoryBody(bodyObject, slug, opts = {}) {
   return { bodyObject: next };
 }
 
+/**
+ * Resolve the provenance source one Story is stamped from (Story #5045).
+ *
+ * Two channels, and the precedence between them is the whole contract:
+ *
+ * - **Attributed** — the Story authored a `provenance` field naming the audit
+ *   identities *it* owns. Exactly those are stamped. This is what makes the
+ *   footers answer "which Story tracks this finding?" instead of "which sweep
+ *   planned it?": under the union every sibling carried every key, so the next
+ *   sweep's confirmation pass could only pick an arbitrary open Story, and a
+ *   key whose owner had since closed was masked by any open neighbour.
+ * - **Union fallback** — no `provenance` field, so the whole seed's footers are
+ *   carried, exactly as before. This is **not** dead weight to be tidied away:
+ *   hand-carried provenance is the failure Stories #4626 / #4877 measured, and
+ *   the union is what closed it. Attribution is additive and recall-safe;
+ *   deleting the fallback would re-open that hole for every plan that does not
+ *   attribute.
+ *
+ * @param {{ fingerprints: string[], semanticKeys: string[] }|null} provenance
+ * @param {object} opts Assembly options carrying `provenanceSource`.
+ * @returns {string}
+ */
+function resolveProvenanceSource(provenance, opts) {
+  if (provenance !== null) return ownedProvenanceSource(provenance);
+  return opts.provenanceSource ?? '';
+}
+
 function assembleOnePlanStory(ticket, opts) {
-  const { slug, title, bodyObject, depends_on, labels, supersedes } =
-    normalizeStoryTicket(ticket);
+  const {
+    slug,
+    title,
+    bodyObject,
+    depends_on,
+    labels,
+    supersedes,
+    provenance,
+  } = normalizeStoryTicket(ticket);
   const { bodyObject: folded } = foldSpecIntoStoryBody(bodyObject, slug, {
     sharedSpec: opts.sharedSpec ?? null,
   });
   // Body first: the fingerprint is an identity over the *assembled* content,
   // so it cannot be computed until that content exists.
   const serialized = serializeStoryBody({ ...folded, depends_on });
-  // Carry audit dedup provenance out of the seed this plan was authored from
-  // (Story #4877). The audit sweep's Single-plan path stamps the
-  // `audit-fingerprints` / `audit-semantic-keys` footers into the seed it hands
-  // `/plan`; without this the persisted Story carries no provenance and the
-  // next sweep re-files work it already planned. Mechanical on purpose — the
-  // authoring agent is not asked to notice HTML comments in a one-pager. A
-  // non-audit seed carries no footers, so this is a no-op there.
+  // Carry audit dedup provenance into the persisted body (Story #4877). The
+  // audit sweep's Single-plan path stamps the `audit-fingerprints` /
+  // `audit-semantic-keys` footers into the seed it hands `/plan`; without this
+  // the persisted Story carries no provenance and the next sweep re-files work
+  // it already planned. Mechanical on purpose — the authoring agent is not
+  // asked to notice HTML comments in a one-pager. A non-audit seed carries no
+  // footers, so this is a no-op there. Which identities reach *this* Story is
+  // `resolveProvenanceSource`'s call (Story #5045).
   const { body } = carryProvenanceFooters({
-    from: opts.provenanceSource ?? '',
+    from: resolveProvenanceSource(provenance, opts),
     into: serialized,
   });
   const fingerprint = planStoryFingerprint({ slug, title, body });
@@ -615,13 +672,30 @@ function renderStoryBodyForCreate(story, idBySlug) {
   const dependencyRefs = story.depends_on.map(
     (slug) => `#${idBySlug.get(slug)}`,
   );
-  const base =
-    dependencyRefs.length === 0
-      ? story.body
-      : serializeStoryBody(
-          { ...story.bodyObject, depends_on: dependencyRefs },
-          { includeFooter: true },
-        );
+  let base = story.body;
+  if (dependencyRefs.length > 0) {
+    // Re-serializing from `bodyObject` is what resolves the sibling slugs to
+    // real issue ids — but `bodyObject` never held the provenance footers
+    // (`assembleOnePlanStory` appends those to the body *string*), so this
+    // branch drops them unless the carry is re-applied. That is the exact
+    // loss site Story #4935 diagnosed, #4939 fixed, and #4956 reverted
+    // wholesale hours later; Story #5056 restored it with a persist-side
+    // regression test that reads the POSTed body.
+    //
+    // `from: story.body` — not the seed — is load-bearing: it re-carries the
+    // identities *this* Story was stamped with under Story #5045 attribution
+    // rather than reintroducing the whole seed's union. `carryProvenanceFooters`
+    // is additive, union-preserving and idempotent, so re-applying is safe by
+    // construction.
+    const reserialized = serializeStoryBody(
+      { ...story.bodyObject, depends_on: dependencyRefs },
+      { includeFooter: true },
+    );
+    base = carryProvenanceFooters({
+      from: story.body,
+      into: reserialized,
+    }).body;
+  }
   return `${base}\n\n${planFingerprintMarker(story.fingerprint)}`;
 }
 

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

@@ -65,6 +65,53 @@ function renderWaveTableLines(waveTable) {
   return ['| Order | Stories |', '| --- | --- |', ...rows];
 }
 
+/**
+ * Render the shared-editor collisions beside the wave table (Story #5045).
+ *
+ * The wave table is a promise about parallelism — "these Stories can run
+ * together". `computeSharedEditorFindings` knows exactly where that promise
+ * breaks down: a path two same-wave Stories both write will conflict on every
+ * merge after the first. Until now those findings degraded to a `Logger.warn`
+ * on stderr and were discarded, so the comment carried the optimistic half of
+ * the analysis and none of the caveat. Rendering them here puts the promise
+ * and its known exceptions on one durable surface.
+ *
+ * Advisory by default and labelled as such — `planning.failOnSharedEditors`
+ * is the knob that makes a collision refuse the plan, and it stays off.
+ *
+ * @param {object[]|null} conflictFindings
+ * @returns {string[]} Lines to splice after the wave table, or `[]`.
+ */
+function renderSharedEditorLines(conflictFindings) {
+  const shared = (
+    Array.isArray(conflictFindings) ? conflictFindings : []
+  ).filter((finding) => finding?.kind === 'shared-editor');
+  if (shared.length === 0) return [];
+  const rows = shared
+    .slice()
+    .sort((a, b) => String(a.path).localeCompare(String(b.path)))
+    .map(
+      (finding) =>
+        `| \`${finding.path}\` | ${(finding.storySlugs ?? [])
+          .map((slug) => `\`${slug}\``)
+          .join(', ')} |`,
+    );
+  return [
+    '',
+    `#### ⚠️ Known collisions (${shared.length} shared file(s))`,
+    '',
+    '| Path | Stories in the same order |',
+    '| --- | --- |',
+    ...rows,
+    '',
+    '_These Stories are scheduled to run together **and** write the same ' +
+      'file — expect a merge conflict on every landing after the first. Add a ' +
+      '`depends_on` edge to serialize them, or move the shared edit into one ' +
+      'Story. Advisory: `planning.failOnSharedEditors` turns this into a ' +
+      'refusal and is off by default._',
+  ];
+}
+
 /**
  * Build the `plan-summary` structured-comment body.
  *
@@ -81,6 +128,7 @@ export function buildPlanSummaryCommentBody({
   mode = 'stories',
   planMetricsLine = null,
   stories = null,
+  conflictFindings = null,
   // legacy unused knobs kept so older test call sites don't crash mid-migration
   single = null,
   amend = null,
@@ -132,6 +180,7 @@ export function buildPlanSummaryCommentBody({
     '#### Delivery order (`depends_on`)',
     '',
     ...renderWaveTableLines(waveTable),
+    ...renderSharedEditorLines(conflictFindings),
     '',
     `_Deliver with \`${deliverCommand}\` — \`/deliver\` resolves the dependency graph from live state, so edges may point at Stories from earlier plan runs._`,
   ].join('\n');

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -182,9 +182,16 @@ export function storyFootprintPaths(body, id, warn) {
 }
 
 /**
- * Build the DAG nodes. `dependsOn` is the union the adjacency builder already
- * computes (body-parsed `blocked by #N` + explicit fields), plus any native
- * edges threaded in via `nativeEdges`. `files` is a plain `string[]`.
+ * Build the DAG nodes. `dependsOn` is the **union of the two declared-edge
+ * channels**: the Story body's `---` footer (`blocked by #N`) and the native
+ * GitHub `blocked_by` relations threaded in via `nativeEdges`. `files` is a
+ * plain `string[]`.
+ *
+ * The body channel is footer-scoped and strict (`parseBlockedBy`, Story
+ * #5046) — a `blocked by #123` mention in prose no longer mints a dispatch
+ * gate. Only `{ id, dependsOn }` is handed to the adjacency builder, never the
+ * body: the edge set is decided here, once, so the builder's own body parse
+ * cannot re-derive a different one behind this function's back.
  *
  * @param {object[]} stories
  * @param {Map<number, number[]>} [nativeEdges]
@@ -193,7 +200,7 @@ export function storyFootprintPaths(body, id, warn) {
  */
 export function storiesToDag(stories, nativeEdges = new Map(), warn) {
   const withNative = stories.map((s) => ({
-    ...s,
+    id: s.id,
     dependsOn: [
       ...new Set([
         ...parseBlockedBy(s.body ?? ''),
@@ -222,28 +229,39 @@ export function storiesToDag(stories, nativeEdges = new Map(), warn) {
  * matching no Story, foreign to the set, never satisfiable, and (because
  * foreign edges are real gates) a silent permanent wedge.
  *
- * Cross-repo blockers are rejected rather than matched: another repo's #4530
- * is not this repo's #4530, and treating it as one could satisfy a gate that
- * is still open.
+ * A cross-repo blocker is **dropped with a loud warning**, never matched:
+ * another repo's #4530 is not this repo's #4530, and treating it as one could
+ * satisfy a gate that is still open. It used to throw, which failed the WHOLE
+ * resolution — one Story's unsupported edge took every sibling down with it
+ * (Story #5046). The degrade is now scoped to the Story carrying the edge:
+ * its siblings resolve normally, and the operator is told, by number, which
+ * Story lost which edge.
  *
  * @param {unknown} data Parsed API response.
- * @param {{ owner: string, repo: string, issueNumber: number }} ctx
+ * @param {{ owner: string, repo: string, issueNumber: number, warn?: (msg: string) => void }} ctx
  * @returns {number[]}
  */
-export function nativeBlockedByNumbers(data, { owner, repo, issueNumber }) {
+export function nativeBlockedByNumbers(
+  data,
+  { owner, repo, issueNumber, warn },
+) {
   if (!Array.isArray(data)) return [];
   const out = [];
   for (const item of data) {
     const repoUrl = item?.repository_url ?? item?.repository?.url ?? null;
-    if (typeof repoUrl === 'string' && repoUrl.length > 0) {
-      const expected = `/repos/${owner}/${repo}`;
-      if (!repoUrl.endsWith(expected)) {
-        throw new Error(
-          `[resolve-stories] #${issueNumber} is blocked by an issue in another repository ` +
-            `(${repoUrl}). Cross-repo dependency edges are not supported — its number cannot ` +
-            `be matched against this repo's Stories without risking a false match.`,
-        );
-      }
+    if (
+      typeof repoUrl === 'string' &&
+      repoUrl.length > 0 &&
+      !repoUrl.endsWith(`/repos/${owner}/${repo}`)
+    ) {
+      warn?.(
+        `[resolve-stories] #${issueNumber} declares a native blocked_by edge on an issue in ` +
+          `another repository (${repoUrl}). Cross-repo edges are not supported — its number ` +
+          `cannot be matched against this repo's Stories without risking a false match, so the ` +
+          `edge is DROPPED for #${issueNumber} only. Its siblings resolve normally; re-declare ` +
+          `the ordering in this repo if #${issueNumber} must wait.`,
+      );
+      continue;
     }
     const number = Number(item?.number);
     if (Number.isInteger(number) && number > 0) out.push(number);
@@ -252,17 +270,33 @@ export function nativeBlockedByNumbers(data, { owner, repo, issueNumber }) {
 }
 
 /**
- * Read an issue's native `blocked_by` edges as issue numbers.
+ * Read an issue's native `blocked_by` edges as issue numbers, **paginated to
+ * exhaustion**.
+ *
+ * The read used to take the first page only, so a Story with more than a
+ * page of blockers silently lost every edge past the boundary — the exact
+ * failure this function's fail-loud contract exists to prevent, arriving
+ * through the one door that never raised (Story #5046). `paginate` is
+ * injected (the CLI passes `paginateRest`) so the lib layer stays free of a
+ * provider import and the page walk stays testable without a live round-trip.
  *
- * **Fails loud**, deliberately inverting the write path's non-fatal contract.
- * A dropped write-side edge is cosmetic (the ordering still lives in the
- * `blocked by #N` body footer); a dropped READ-side edge silently removes a
- * dispatch gate, so a 403 (dependencies API disabled, or a token without the
- * scope) would erase every native edge at once and co-dispatch the whole run
- * against unlanded blockers. A 404 means "no dependencies on this issue" and
- * is a legitimate empty result.
+ * **Fails loud on every non-OK read**, deliberately inverting the write path's
+ * non-fatal contract. A dropped write-side edge is cosmetic (the ordering
+ * still lives in the `blocked by #N` body footer); a dropped READ-side edge
+ * silently removes a dispatch gate, so one failure would erase every native
+ * edge at once and co-dispatch the run against unlanded blockers.
  *
- * @param {{ gh: object, owner: string, repo: string, issueNumber: number, parseJson: Function }} opts
+ * **A 404 is not an empty result.** It used to be treated as "this issue has
+ * no dependencies", which is how GitHub answers an issue that genuinely has
+ * none — but it is *also* how GitHub answers a token that cannot see the
+ * dependencies API at all. Reading the second as the first erases every
+ * native edge in the run under a mis-scoped token, silently, with a clean
+ * exit code. An issue with no dependencies returns `200 []`, so the empty
+ * case needs no 404 escape hatch and the ambiguity resolves loud.
+ *
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number,
+ *   paginate: (gh: object, endpoint: string, opts?: object) => Promise<unknown[]>,
+ *   warn?: (msg: string) => void }} opts
  * @returns {Promise<number[]>}
  */
 export async function readNativeBlockedBy({
@@ -270,27 +304,30 @@ export async function readNativeBlockedBy({
   owner,
   repo,
   issueNumber,
-  parseJson,
+  paginate,
+  warn,
 }) {
-  let result;
+  const endpoint = `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`;
+  let items;
   try {
-    result = await gh.api({
-      method: 'GET',
-      endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+    items = await paginate(gh, endpoint, {
+      label: `[resolve-stories] blocked_by #${issueNumber}`,
     });
   } catch (err) {
     const detail = String(err?.message ?? err);
-    if (/404|not found/i.test(detail)) return [];
     throw new Error(
       `[resolve-stories] Could not read native blocked_by edges for #${issueNumber}: ${detail}. ` +
         `Refusing to continue: a dropped dependency edge would silently remove a dispatch gate ` +
-        `and co-dispatch this Story against an unlanded blocker.`,
+        `and co-dispatch this Story against an unlanded blocker. A 404 here is NOT "no ` +
+        `dependencies" (that answers 200 with an empty list) — check the token's scopes and ` +
+        `that the dependencies API is enabled for ${owner}/${repo}.`,
     );
   }
-  return nativeBlockedByNumbers(parseJson(result), {
+  return nativeBlockedByNumbers(items, {
     owner,
     repo,
     issueNumber,
+    warn,
   });
 }
 

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -1,3 +1,4 @@
+import { resolveListValue } from '../config/shared.js';
 import { parse as parseStoryBody } from '../story-body/story-body.js';
 import { collectStoryAssumptionEntries } from './file-assumptions.js';
 import { computeStoryReachability } from './story-reachability.js';
@@ -108,8 +109,11 @@ const DEFAULT_POLICY = Object.freeze({
  * Patterns support two shapes:
  *   - exact path  — `lib/orchestration/lifecycle/listeners/index.js`
  *   - `**` suffix — `**\/listeners/index.js` (matches any depth)
+ *
+ * Module-private since `resolveConflictPolicy` became the one production
+ * reader; tests reach it through `_internal`.
  */
-export const DEFAULT_REGISTRY_PATTERNS = Object.freeze([
+const DEFAULT_REGISTRY_PATTERNS = Object.freeze([
   'lib/orchestration/lifecycle/listeners/index.js',
   '**/listeners/index.js',
   '**/handlers/index.js',
@@ -762,6 +766,117 @@ export function computeConflictFindings({ stories, policy } = {}) {
   ];
 }
 
+/**
+ * Resolve the config-derived half of the conflict policy from
+ * `config.planning` — the severity flags, the fan-out threshold, and the
+ * registry patterns, in one place.
+ *
+ * Two passes consume `planning.*` and must not disagree: the raw
+ * pre-assembly pass (`persist-helpers.validateTickets`, which attaches its
+ * production `fanOutCounter` on top of this) and the post-assembly pass
+ * (`computeAssembledConflictFindings`, which forces `fanOutCounter: null`).
+ * Under Story #5045 each resolved its own copy, and the copies had already
+ * drifted — `failOnMissingBddScaffold` reached only the assembled pass,
+ * `failOnLargeFanOut` / `largeFanOutThreshold` / `crossCuttingRegistries`
+ * only the raw one — so a knob set in config silently applied on one of the
+ * two passes. A knob read here reaches both; that is the contract.
+ *
+ * `fanOutCounter` is deliberately absent: it is probe machinery, not
+ * config, and each caller owns its own.
+ *
+ * @param {object} [config] Resolved config carrying `planning.*`.
+ * @returns {object} A `computeConflictFindings` policy (no `fanOutCounter`).
+ */
+export function resolveConflictPolicy(config) {
+  const planning = config?.planning;
+  const policy = {
+    failOnSharedEditors: planning?.failOnSharedEditors === true,
+    requireExplicitCrossStoryDeps:
+      planning?.requireExplicitCrossStoryDeps === true,
+    failOnRegistryConflicts: planning?.failOnRegistryConflicts === true,
+    failOnLargeFanOut: planning?.failOnLargeFanOut === true,
+    failOnMissingBddScaffold: planning?.failOnMissingBddScaffold === true,
+  };
+  if (Number.isFinite(planning?.largeFanOutThreshold)) {
+    policy.largeFanOutThreshold = planning.largeFanOutThreshold;
+  }
+  if (planning?.crossCuttingRegistries !== undefined) {
+    policy.registries = resolveListValue(
+      DEFAULT_REGISTRY_PATTERNS,
+      planning.crossCuttingRegistries,
+    );
+  }
+  return policy;
+}
+
+/**
+ * Re-run the cross-Story conflict passes over the **assembled** Story bodies —
+ * the artifact persist actually writes (Story #5045).
+ *
+ * `validateTickets` runs before `assemblePlanStories`, over the raw
+ * `stories.json` payload, so plan-time conflict analysis never saw what got
+ * persisted. That is not a cosmetic ordering nit: the canonical authoring shape
+ * carries `acceptance[]` / `verify[]` at the ticket's **top level**, and it is
+ * assembly's `syncContractFieldFromTopLevel` that folds them into the body.
+ * `indexConsumers` scans `body.acceptance` / `body.verify` for producer paths —
+ * so on the real payload it scanned two empty arrays, and every
+ * `implicit-cross-story-dep` and `missing-bdd-scaffold` finding was silently
+ * unreachable. Running the passes again over the serialized bodies restores
+ * them.
+ *
+ * **The fan-out pass is deliberately not re-run.** It is a `git grep` per
+ * deleted path and its inputs (`changes[]` deletes) are identical on both
+ * sides, so re-probing would double the git cost for a byte-identical answer;
+ * `enforceFanOutGate` already owns that class over the raw payload.
+ *
+ * @param {object} args
+ * @param {Array<{ slug: string, title?: string, body: string, depends_on?: string[] }>} args.stories
+ *   Assembled Stories — `body` is the serialized, footer-stamped markdown.
+ * @param {object} [args.config] Resolved config; `planning.*` supplies the
+ *   policy via {@link resolveConflictPolicy} — the same resolver the raw
+ *   pass uses, so a knob cannot apply on only one of the two passes.
+ * @returns {ConflictFinding[]}
+ */
+export function computeAssembledConflictFindings({ stories, config } = {}) {
+  return computeConflictFindings({
+    stories: (Array.isArray(stories) ? stories : []).map((story) => ({
+      slug: story.slug,
+      title: story.title,
+      body: story.body,
+      depends_on: Array.isArray(story.depends_on) ? story.depends_on : [],
+    })),
+    policy: {
+      ...resolveConflictPolicy(config),
+      fanOutCounter: null,
+    },
+  });
+}
+
+/**
+ * Stable identity for one conflict finding, so the post-assembly pass can be
+ * diffed against the raw pass and only the genuinely-new findings reported
+ * (Story #5045). Without it the two passes announce the same shared-editor
+ * collision twice per run, which is how a warning channel gets discounted.
+ *
+ * The separator is written as the `\u0000` escape and never as a raw byte — a
+ * literal NUL would make git classify this file as binary and drop its diffs.
+ *
+ * @param {object} finding
+ * @returns {string}
+ */
+export function conflictFindingKey(finding) {
+  return [
+    finding?.kind ?? '',
+    finding?.path ?? finding?.registryPath ?? '',
+    Array.isArray(finding?.storySlugs)
+      ? [...finding.storySlugs].sort().join(',')
+      : (finding?.storySlug ?? ''),
+    finding?.producer?.storySlug ?? '',
+    finding?.consumer?.storySlug ?? '',
+    finding?.consumer?.sourceField ?? '',
+  ].join('\u0000');
+}
+
 /**
  * Render the audit trail behind a fan-out finding's number, so an operator
  * can check the figure rather than trust it (Story #4547).

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -1,4 +1,5 @@
 import { ValidationError } from '../errors/index.js';
+import { normalizeOwnedProvenance } from '../findings/provenance-field.js';
 import { detectCycle } from '../Graph.js';
 import { gitSpawn } from '../git-utils.js';
 
@@ -528,6 +529,41 @@ function assertEveryStoryHasInlineContract({ stories }) {
   );
 }
 
+/**
+ * Shape-check the optional per-Story `provenance` field (Story #5045).
+ *
+ * The field decides which audit identities persist stamps into a Story body,
+ * so a malformed entry has to fail at the validator rather than at the
+ * stamper: by the time assembly runs, an unnoticed drop is indistinguishable
+ * from a Story that legitimately owns nothing — and the cost lands a whole
+ * sweep later, when the next audit re-files work this plan already tracked.
+ *
+ * Absence is valid and common: a Story with no `provenance` inherits the
+ * whole-seed union carry, which is the recall-safe default.
+ *
+ * Errors are batched across the backlog so one pass names every offender.
+ *
+ * @param {{ stories: object[] }} args
+ * @throws {Error} naming each malformed field.
+ */
+function assertStoryProvenanceShape({ stories }) {
+  const violations = [];
+  for (const story of stories) {
+    try {
+      normalizeOwnedProvenance(story?.provenance, story?.slug ?? '<unknown>');
+    } catch (err) {
+      violations.push(`  - ${err.message}`);
+    }
+  }
+  if (violations.length === 0) return;
+  throw new Error(
+    `Cross-Validation Failed: ${violations.length} Story provenance field(s) ` +
+      `are malformed:\n${violations.join('\n')}\n\nAuthor provenance as ` +
+      '{ "fingerprints": ["<40-char sha1>"], "semanticKeys": ["<area␟path>"] }, ' +
+      'or omit it entirely to inherit the seed-wide union.',
+  );
+}
+
 function assertNoUnknownDeps({ tickets, ticketBySlug }) {
   const unknownDeps = [];
   for (const t of tickets) {
@@ -575,6 +611,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 
   assertAllTicketsAreStories({ tickets, stories });
   assertEveryStoryHasInlineContract({ stories });
+  assertStoryProvenanceShape({ stories });
   assertNoUnknownDeps({ tickets, ticketBySlug });
 
   assertAcyclic(slugAdjacency);
@@ -704,6 +741,7 @@ export const _internal = {
   indexTicketsBySlug,
   assertAllTicketsAreStories,
   assertEveryStoryHasInlineContract,
+  assertStoryProvenanceShape,
   assertNoUnknownDeps,
   assertAcyclic,
   attachFindingsAndErrors,