mandrel 2.32.0 → 2.33.0

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -22,6 +22,7 @@
  * structured contract.
  */
 
+import path from 'node:path';
 import { AGENT_LABELS, RISK_LABELS, TYPE_LABELS } from '../label-constants.js';
 import { serialize } from '../story-body/story-body.js';
 import { definesAuditLabel } from './audit-label-taxonomy.js';
@@ -116,10 +117,7 @@ function acceptanceCriteriaFromGroup(group) {
 
 /**
  * Resolve the `edges[]` sequencing anchored on this group. Each edge whose
- * `fromGroupKey` matches this group's key contributes its `toGroupKey`. Group
- * keys are the only stable identifier available at emit time — issues are not
- * numbered yet — so the relationship is preserved as machine-readable keys the
- * operator can resolve.
+ * `fromGroupKey` matches this group's key contributes its `toGroupKey`.
  *
  * @param {object} group
  * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} edges
@@ -135,22 +133,38 @@ function sequencingDepsForGroup(group, edges) {
 }
 
 /**
- * Render the carried-through `edges[]` sequencing as a dedicated extended
- * markdown block. The canonical `depends_on[]` footer only round-trips `#N`
- * issue refs (`blocked by #123`), which do not exist before the issues are
- * opened; rendering the group-key sequencing as its own informational section
- * keeps the signal in the body (not discarded — Story #4270) and survives
- * `parse()` / `serialize()` round-tripping (it is preamble/extended content,
- * not a structured section). Returns the empty string when there is no
- * sequencing to surface.
+ * Resolve this group's sequencing to canonical `#N` issue refs, or `[]` when
+ * the caller has no issue numbers yet (Story #5044).
  *
- * @param {string[]} deps
- * @returns {string}
+ * Group keys are the only identifier that exists at *emit* time — the issues
+ * are not numbered — which is why this used to render as a prose
+ * `## Sequencing` block that nothing could act on. Standalone audit Stories
+ * therefore hardcoded `depends_on: []`, and their only actual serializer was
+ * an accident: their shared provenance footers collided under the delivery
+ * footprint guard. Narrowing that scrape removes the accident, so the ordering
+ * has to become real in the same change.
+ *
+ * The resolution is the two-pass shape `plan-persist` already uses: create every
+ * issue first, then re-render each body with the now-known numbers and mirror
+ * the same edges as native `blocked_by` relations. An edge whose target was not
+ * created (deduped against an existing Issue, suppressed by the ledger) simply
+ * drops — a `blocked by #undefined` would be worse than an absent edge.
+ *
+ * A **plain object**, deliberately, not a `Map`: the same map is handed to
+ * `applyBlockedByDependencies`, which indexes it with property access, so a
+ * `Map` there would silently resolve every lookup to `undefined`, skip every
+ * edge, and report success having written nothing. One shape, both halves.
+ *
+ * @param {string[]} deps                     Group keys this group depends on.
+ * @param {Record<string, number>|null} issueByGroupKey
+ * @returns {string[]} `#N` refs, in `deps` order.
  */
-function sequencingSection(deps) {
-  if (deps.length === 0) return '';
-  const lines = deps.map((k) => `- depends on group \`${k}\``);
-  return ['## Sequencing', '', lines.join('\n'), ''].join('\n');
+function dependencyRefs(deps, issueByGroupKey) {
+  if (!issueByGroupKey) return [];
+  return deps
+    .map((key) => issueByGroupKey[key])
+    .filter((n) => Number.isInteger(n) && n > 0)
+    .map((n) => `#${n}`);
 }
 
 function agentPromptsSection(group) {
@@ -162,6 +176,21 @@ function agentPromptsSection(group) {
   return blocks.join('\n\n') || '_(no copy-pasteable prompts captured)_';
 }
 
+/**
+ * Link each source audit report **once**.
+ *
+ * This used to render `- [\`path\`](path)` — the same
+ * `temp/audits/audit-<lens>-results.md` in the link text and again in the URL,
+ * byte-identical across every Story of a same-lens sweep. That doubled a token
+ * the delivery footprint guard scraped as edit intent, so a lens's whole cohort
+ * serialized on a report none of them would ever write to (Story #5044). The
+ * guard now ignores markdown-link URLs and temp-root paths, but rendering the
+ * path twice was never useful to a reader either: the file name is the label,
+ * the path is the target.
+ *
+ * @param {object} group
+ * @returns {string}
+ */
 function contextLinksFromGroup(group) {
   const reports = uniq(
     (group.findings ?? [])
@@ -169,7 +198,11 @@ function contextLinksFromGroup(group) {
       .filter((s) => typeof s === 'string'),
   );
   if (reports.length === 0) return '_(no source audit reports captured)_';
-  return reports.map((r) => `- [\`${r}\`](${r})`).join('\n');
+  // `path.basename` rather than `split('/')`: on win32 it splits on both
+  // separators, so an absolute Windows path yields the file name instead of
+  // the whole path — which would render the path twice in one link and
+  // re-create the very duplication this function exists to remove.
+  return reports.map((r) => `- [${path.basename(r)}](${r})`).join('\n');
 }
 
 function labelsForGroup(group) {
@@ -226,20 +259,27 @@ function assertLabelsInTaxonomy(labels) {
  *   — the dependency `edges[]` emitted by `groupFindings`. Edges anchored on
  *   this group are carried through to `depends_on[]`; omit when no sequencing
  *   is known.
- * @returns {{ title: string, body: string, labels: string[] }}
+ * @param {Record<string, number>|null} [params.issueByGroupKey]
+ *   — group key → opened issue number. Supplied on the **second** pass, once
+ *   the issues exist, so this group's edges render as canonical
+ *   `blocked by #N` footers (Story #5044). Omit on the first pass.
+ * @returns {{ title: string, body: string, labels: string[], groupKey: string, dependsOn: string[] }}
+ *   `groupKey` and `dependsOn` are the caller's handle on the second pass:
+ *   they name this Story and the groups it must follow, so the caller can map
+ *   both onto issue numbers without re-deriving the grouping.
  */
-export function buildStoryBody({ group, edges = [] }) {
+export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
   if (!group || !Array.isArray(group.findings)) {
     throw new Error('buildStoryBody: group with findings[] is required');
   }
   const title = group.title;
+  const dependsOn = sequencingDepsForGroup(group, edges);
 
   // Build the canonical StoryBody object from the audit group data. The
   // acceptance + verify arrays are populated so the body clears the
-  // inline-contract bar; changes[] carries the file footprint. The edges[]
-  // sequencing is carried through as an extended `## Sequencing` block (see
-  // sequencingSection) — group keys are not `#N` refs, so they cannot ride the
-  // canonical depends_on footer.
+  // inline-contract bar; changes[] carries the file footprint. `depends_on`
+  // is empty on the first pass (the blockers have no issue numbers yet) and
+  // carries real `#N` refs on the second — see dependencyRefs.
   const storyBody = {
     goal: goalFromGroup(group),
     changes: changesFromGroup(group),
@@ -248,20 +288,21 @@ export function buildStoryBody({ group, edges = [] }) {
     references: [],
     wide: null,
     reason_to_exist: null,
-    depends_on: [],
+    depends_on: dependencyRefs(dependsOn, issueByGroupKey),
   };
 
-  // Serialize via the canonical serializer (no footer — depends_on is empty).
-  const canonicalSections = serialize(storyBody);
-  const sequencing = sequencingSection(sequencingDepsForGroup(group, edges));
+  // The `---` / `blocked by #N` footer is the canonical serializer's own, so
+  // the body round-trips through `parse()` and `/deliver`'s resolver reads the
+  // ordering from the same place it reads every other Story's.
+  const canonicalSections = serialize(storyBody, {
+    includeFooter: storyBody.depends_on.length > 0,
+  });
 
-  // Append audit-specific extended sections (sequencing, agent prompts,
-  // context links, fingerprint footer) that are not part of the canonical
-  // shape.
+  // Append audit-specific extended sections (agent prompts, context links,
+  // provenance footers) that are not part of the canonical shape.
   const body = [
     canonicalSections,
     '',
-    ...(sequencing ? [sequencing] : []),
     '## Agent Prompts',
     '',
     agentPromptsSection(group),
@@ -276,5 +317,11 @@ export function buildStoryBody({ group, edges = [] }) {
     renderSemanticKeyFooter(group.findings),
   ].join('\n');
 
-  return { title, body, labels: labelsForGroup(group) };
+  return {
+    title,
+    body,
+    labels: labelsForGroup(group),
+    groupKey: group.groupKey,
+    dependsOn,
+  };
 }

package/.agents/scripts/lib/audit-to-stories/wire-dependencies.js

@@ -0,0 +1,185 @@
+/**
+ * lib/audit-to-stories/wire-dependencies.js — turn a standalone audit cohort's
+ * detected group edges into declared ordering, once the issues exist.
+ *
+ * `groupFindings` detects `edges[]` between finding groups, but at emit time
+ * the groups have no issue numbers, so the ordering could only be rendered as
+ * prose. Every standalone audit Story therefore shipped with `depends_on: []`,
+ * and what actually kept a cohort from being co-dispatched onto colliding
+ * branches was an **accident**: siblings shared the sweep-wide audit provenance
+ * footers `plan-persist` stamps, and the delivery footprint guard scraped
+ * path-shaped tokens out of them. Story #5044 narrows that scrape, which is why
+ * this module lands with it — removing the accidental serializer without giving
+ * the cohort a real one would leave it less ordered than before.
+ *
+ * The shape is `plan-persist`'s two-pass crossing (`plan-persist/story-ops.js`),
+ * because it is the same problem: **create every issue first, then mirror the
+ * edges**. Both halves are written:
+ *
+ *   1. The **body footer** (`---` / `blocked by #N`) — canonical, parsed by
+ *      `/deliver`'s resolver, and the fallback when the dependencies API is
+ *      unavailable.
+ *   2. The **native `blocked_by` relation** — visible in the GitHub UI,
+ *      readable without parsing markdown, and settable by an operator later.
+ *
+ * Native mirroring is **non-fatal by design**, matching `plan-persist`: the
+ * footer has already been written by the time it runs, so a dependencies API
+ * that says no costs visibility, not ordering.
+ *
+ * @module lib/audit-to-stories/wire-dependencies
+ */
+
+import { applyBlockedByDependencies } from '../../providers/github/blocked-by-add.js';
+import { Logger } from '../Logger.js';
+import { buildStoryBody } from './build-story-body.js';
+
+/**
+ * Re-render each created Story's body with its blockers resolved to `#N`, and
+ * mirror the same edges as native `blocked_by` relations.
+ *
+ * Groups whose issue was not created — deduped against an existing Issue,
+ * suppressed by the ledger, or simply not in `issueByGroupKey` — are skipped
+ * rather than guessed at, and an edge pointing at one drops with them
+ * (`dependencyRefs` filters it). A `blocked by #undefined` would gate a Story
+ * on nothing forever, which is strictly worse than the un-ordered cohort this
+ * replaces.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.groups          The `create`-eligible groups, in
+ *   the order their issues were opened.
+ * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} [args.edges]
+ * @param {Record<string, number>} args.issueByGroupKey  Group key → issue number.
+ * @param {(issueNumber: number, body: string) => Promise<unknown>} args.updateBody
+ *   Persist a re-rendered body. Injected so the caller owns the provider call.
+ * @param {object|null} [args.provider] Provider for native edge mirroring.
+ *   Omit (or pass one without the dependency ports) to write footers only.
+ * @returns {Promise<{
+ *   storiesWired: number,
+ *   bodiesUpdated: number,
+ *   edgesDeclared: number,
+ *   native: { edgesAdded: number, edgesSkipped: number, edgesFailed: number }|null
+ * }>}
+ */
+export async function wireAuditStoryEdges({
+  groups,
+  edges = [],
+  issueByGroupKey,
+  updateBody,
+  provider = null,
+}) {
+  const wired = collectWiredStories({ groups, edges, issueByGroupKey });
+  if (wired.length === 0) {
+    return {
+      storiesWired: 0,
+      bodiesUpdated: 0,
+      edgesDeclared: 0,
+      native: null,
+    };
+  }
+
+  let bodiesUpdated = 0;
+  for (const story of wired) {
+    await updateBody(story.issueNumber, story.body);
+    bodiesUpdated++;
+  }
+
+  return {
+    storiesWired: wired.length,
+    bodiesUpdated,
+    edgesDeclared: wired.reduce((n, s) => n + s.blockerKeys.length, 0),
+    native: await mirrorNativeEdges({ provider, wired, issueByGroupKey }),
+  };
+}
+
+/**
+ * Re-render every group that both has an issue **and** has at least one blocker
+ * whose issue also exists.
+ *
+ * A group with no resolvable blocker is deliberately left alone rather than
+ * rewritten to an identical body: an issue-body update is a mutation and a
+ * notification, and doing it for a no-op edit is noise on every Story of every
+ * sweep.
+ *
+ * @param {object} args
+ * @returns {Array<{ groupKey: string, issueNumber: number, body: string, blockerKeys: string[] }>}
+ */
+function collectWiredStories({ groups, edges, issueByGroupKey }) {
+  const wired = [];
+  for (const group of groups ?? []) {
+    const issueNumber = issueByGroupKey?.[group?.groupKey];
+    if (!Number.isInteger(issueNumber)) continue;
+    const rendered = buildStoryBody({ group, edges, issueByGroupKey });
+    const blockerKeys = rendered.dependsOn.filter((key) =>
+      Number.isInteger(issueByGroupKey[key]),
+    );
+    if (blockerKeys.length === 0) continue;
+    wired.push({
+      groupKey: rendered.groupKey,
+      issueNumber,
+      body: rendered.body,
+      blockerKeys,
+    });
+  }
+  return wired;
+}
+
+/**
+ * Mirror the declared edges as native GitHub `blocked_by` relations.
+ *
+ * Two shape hazards this crossing inherits from `plan-persist`, both silent if
+ * missed: `applyBlockedByDependencies` indexes `slugToIssueNumber` with plain
+ * property access (so it must be a plain object, never a `Map` — a `Map` yields
+ * `undefined` for every lookup, skips every edge, and reports success having
+ * written nothing), and it reads `dependsOn`, not `depends_on`.
+ *
+ * @param {object} args
+ * @returns {Promise<{ edgesAdded: number, edgesSkipped: number, edgesFailed: number }|null>}
+ *   `null` when there is no interface to mirror through.
+ */
+async function mirrorNativeEdges({ provider, wired, issueByGroupKey }) {
+  if (
+    typeof provider?.getDependencyWriteContext !== 'function' ||
+    typeof provider?.getTicket !== 'function'
+  ) {
+    Logger.warn(
+      '[audit-to-stories] provider exposes no getDependencyWriteContext/getTicket — ' +
+        'skipping native blocked_by edges. Ordering survives in the ' +
+        '`blocked by #N` body footers just written.',
+    );
+    return null;
+  }
+  try {
+    const { gh, owner, repo } = provider.getDependencyWriteContext();
+    const summary = await applyBlockedByDependencies({
+      // The group key IS the slug here — it is the stable identifier both
+      // sides of an edge are keyed by — so `issueByGroupKey` is already the
+      // slug→number map the helper wants.
+      stories: wired.map((s) => ({
+        slug: s.groupKey,
+        dependsOn: s.blockerKeys,
+      })),
+      slugToIssueNumber: issueByGroupKey,
+      getTicket: (issueNumber) => provider.getTicket(issueNumber),
+      owner,
+      repo,
+      gh,
+    });
+    if (summary.edgesFailed > 0) {
+      Logger.warn(
+        `[audit-to-stories] ${summary.edgesFailed} native blocked_by edge(s) could ` +
+          'not be written. Ordering survives in the `blocked by #N` body footers.',
+      );
+    }
+    return {
+      edgesAdded: summary.edgesAdded,
+      edgesSkipped: summary.edgesSkipped,
+      edgesFailed: summary.edgesFailed,
+    };
+  } catch (err) {
+    Logger.warn(
+      `[audit-to-stories] native blocked_by mirroring failed (${err.message}) — ` +
+        'ordering survives in the `blocked by #N` body footers.',
+    );
+    return null;
+  }
+}

package/.agents/scripts/lib/config/runners.js

@@ -30,9 +30,19 @@ export const DEFAULT_DECOMPOSER = Object.freeze({
  * `verifyWaveResults` loop it claimed to bound never existed in the tree, and
  * its only reader was the retired execution-analysis CLI, which echoed the
  * number into a report rather than bounding anything.
+ *
+ * **Serialization tradeoff — `footprintGuard`.** `enforce` is the default and
+ * stays it: the file-overlap guard encodes delivery-time-only knowledge (which
+ * implementation windows are open, which Stories a foreign lease holds) that no
+ * plan-time `depends_on` edge can carry, so demoting it by default would trade
+ * a real merge-conflict class for throughput nobody asked for. `advisory`
+ * detects collisions and reports every would-be withhold but lets dispatch
+ * follow the declared edges alone — for runs whose ordering is fully declared
+ * (Story #5044).
  */
 const DEFAULT_DELIVER_RUNNER = Object.freeze({
   concurrencyCap: 3,
+  footprintGuard: 'enforce',
 });
 
 /**
@@ -51,28 +61,40 @@ export const DEFAULT_CODE_REVIEW = Object.freeze({
  *
  * @param {object | null | undefined} config
  * @returns {{
- *   deliverRunner: { concurrencyCap: number },
+ *   deliverRunner: { concurrencyCap: number, footprintGuard: 'enforce'|'advisory' },
  *   codeReview: { maxFixAttempts: number, maxFixScopeFiles: number, autoFixSeverity: 'high'|'medium' },
  *   decomposer: { concurrencyCap: number },
  * }}
  */
 export function getRunners(config) {
-  const deliverRunnerUser = config?.delivery?.deliverRunner ?? {};
-  const codeReviewUser = config?.delivery?.codeReview ?? {};
   return {
-    deliverRunner: {
-      concurrencyCap:
-        deliverRunnerUser.concurrencyCap ??
-        DEFAULT_DELIVER_RUNNER.concurrencyCap,
-    },
-    codeReview: {
-      maxFixAttempts:
-        codeReviewUser.maxFixAttempts ?? DEFAULT_CODE_REVIEW.maxFixAttempts,
-      maxFixScopeFiles:
-        codeReviewUser.maxFixScopeFiles ?? DEFAULT_CODE_REVIEW.maxFixScopeFiles,
-      autoFixSeverity:
-        codeReviewUser.autoFixSeverity ?? DEFAULT_CODE_REVIEW.autoFixSeverity,
-    },
+    deliverRunner: withDefaults(
+      DEFAULT_DELIVER_RUNNER,
+      config?.delivery?.deliverRunner,
+    ),
+    codeReview: withDefaults(DEFAULT_CODE_REVIEW, config?.delivery?.codeReview),
     decomposer: DEFAULT_DECOMPOSER,
   };
 }
+
+/**
+ * Overlay an operator's block onto the framework defaults — the per-key `??`
+ * fallback these accessors have always applied, written once.
+ *
+ * Iterating the **defaults'** keys rather than the user's is what keeps the
+ * returned shape closed: a key the framework does not define cannot reach a
+ * consumer through here even if one somehow survived AJV, so a typo degrades to
+ * the default rather than to an undefined a caller would read as configuration.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} defaults      Frozen framework defaults.
+ * @param {object|null|undefined} user Operator block from `.agentrc`.
+ * @returns {T} A fresh object; the frozen defaults are never mutated.
+ */
+function withDefaults(defaults, user) {
+  const out = { ...defaults };
+  for (const key of Object.keys(defaults)) {
+    if (user?.[key] != null) out[key] = user[key];
+  }
+  return out;
+}

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

@@ -73,10 +73,18 @@ const DELIVER_RUNNER_SCHEMA = {
       minimum: 1,
       description:
         'Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff.',
-      // getRunners() resolves this inline rather than from an exported
-      // constant; the rewritten parity suite asserts the two agree.
+      // getRunners() resolves this from its own DEFAULT_DELIVER_RUNNER
+      // constant, not from this annotation; the parity suite asserts the two
+      // agree.
       default: 3,
     },
+    footprintGuard: {
+      type: 'string',
+      enum: ['enforce', 'advisory'],
+      description:
+        "How a file-footprint collision affects dispatch. 'enforce' (default, and the behaviour to keep unless you have a reason) withholds a Story whose footprint races a peer admitted this beat or one still in flight — the guard encodes delivery-time-only knowledge (open implementation windows, foreign leases, ground that moved since planning) that no depends_on edge can carry. 'advisory' still DETECTS every collision and reports each would-be withhold in the tick envelope, but lets dispatch follow the declared depends_on edges alone — a deliberate throughput trade for a run whose ordering is fully declared. See stories-wave-tick.js and helpers/deliver-reference.md.",
+      default: 'enforce',
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/dependency-parser.js

@@ -7,18 +7,31 @@
  * lib/story-adjacency.js, lib/branch-name-guard.js).
  */
 
+import { parseFooterBlockedByIds } from './story-body/footer-block.js';
+
 /**
- * Parse `blocked by #NNN` and `depends on #NNN` references from text.
- * Handles case-insensitive variations.
+ * Parse a body's declared blocker issue numbers — **footer-scoped and
+ * strict**.
+ *
+ * Only a `blocked by #N` line standing alone inside the `---` footer block
+ * declares an edge. The unanchored predecessor scanned the whole body for
+ * `blocked by|depends on #N` anywhere, so a Story whose prose merely mentioned
+ * a blocker — an example, a changelog note, an acceptance criterion describing
+ * this very defect — minted a real dispatch gate that withheld the Story until
+ * an unrelated issue closed.
+ *
+ * The behaviour change is deliberate and user-visible: prose-only mentions
+ * outside the footer no longer gate. Every machine-authored body already
+ * carries the canonical footer form (`plan-persist` has always serialized it),
+ * so only hand-written prose edges are affected — those must be moved into the
+ * footer block to keep gating. The grammar itself lives in
+ * `lib/story-body/footer-block.js`, shared with the body parser.
  *
  * @param {string} body - Issue body or freeform text.
- * @returns {number[]} Array of issue numbers this text declares as blockers.
+ * @returns {number[]} Array of issue numbers this body declares as blockers.
  */
 export function parseBlockedBy(body) {
-  if (!body) return [];
-  const re = /(?:blocked\s+by|depends\s+on):?\s+#(\d+)/gi;
-  const ids = [...body.matchAll(re)].map((m) => Number.parseInt(m[1], 10));
-  return [...new Set(ids)];
+  return parseFooterBlockedByIds(body);
 }
 
 /**

package/.agents/scripts/lib/findings/provenance-field.js

@@ -0,0 +1,135 @@
+/**
+ * lib/findings/provenance-field.js — the per-Story `provenance` field.
+ *
+ * An audit-seeded plan carries dedup identities forward so the next sweep
+ * recognises what it already planned. The optional top-level `provenance`
+ * field on a `stories.json` entry says **which of them that Story owns**:
+ *
+ * ```jsonc
+ * { "fingerprints": ["<40-char sha1>"], "semanticKeys": ["architecture␟lib/a.js"] }
+ * ```
+ *
+ * Two callers, deliberately split from
+ * [`route-finding.js`](route-finding.js): the ticket validator shape-checks
+ * the authored field, and plan-persist's assembly renders the owned identities
+ * into the footer source it stamps. Neither is dedup *routing*, which is what
+ * `route-finding.js` is for — this module reads its identity vocabulary
+ * (`SHA1_RE`, `SEMANTIC_KEY_RE`, and the two footer renderers) from there so
+ * there is exactly one definition of what a fingerprint or a semantic key
+ * looks like.
+ *
+ * @module lib/findings/provenance-field
+ */
+
+import {
+  fingerprintFooter,
+  SEMANTIC_KEY_RE,
+  SHA1_RE,
+  semanticKeyFooter,
+} from './route-finding.js';
+
+/** Human-readable rendering of the `provenance` field's two lists. */
+const PROVENANCE_SHAPE = 'fingerprints[] / semanticKeys[]';
+
+/** What each `provenance` list accepts, and how to say so when it does not. */
+const PROVENANCE_FIELDS = Object.freeze({
+  fingerprints: { pattern: SHA1_RE, expected: 'a 40-char sha1 hex string' },
+  semanticKeys: {
+    pattern: SEMANTIC_KEY_RE,
+    expected: 'a non-empty key carrying no comma or ">"',
+  },
+});
+
+/**
+ * Validate one authored `provenance` list into its normalized form.
+ *
+ * @param {unknown} list
+ * @param {{ where: string, field: string, pattern: RegExp, expected: string }} spec
+ * @returns {string[]} Trimmed, de-duplicated, first-seen order.
+ */
+function normalizeList(list, { where, field, pattern, expected }) {
+  if (list === null || list === undefined) return [];
+  if (!Array.isArray(list)) {
+    throw new Error(`${where}: ${field} must be an array of strings`);
+  }
+  const out = [];
+  for (const entry of list) {
+    const value = typeof entry === 'string' ? entry.trim() : '';
+    if (!pattern.test(value)) {
+      throw new Error(
+        `${where}: ${field} entry ${JSON.stringify(entry)} is not ${expected}`,
+      );
+    }
+    if (!out.includes(value)) out.push(value);
+  }
+  return out;
+}
+
+/**
+ * Normalize the optional per-Story `provenance` field a plan may author —
+ * the identities of the findings **that Story owns**.
+ *
+ * Absence is meaningful and must stay cheap: `undefined` / `null` returns
+ * `null`, which is the caller's signal to fall back to the whole-seed union
+ * carry. That fallback is not vestigial — leaving the authoring agent to
+ * hand-carry provenance out of the seed's HTML comments was measured to fail,
+ * and the mechanical union is what closed it. Attribution is **additive**: a
+ * plan that attributes gets exact stamping, a plan that does not keeps recall.
+ *
+ * An empty object is therefore *not* the same as an absent field: it means
+ * "this Story owns nothing", and stamps nothing.
+ *
+ * Present-but-malformed is a hard error rather than a silent drop, because a
+ * dropped identity is invisible until the next sweep re-files work that was
+ * already planned.
+ *
+ * @param {unknown} raw
+ * @param {string} [label] Identifier for the error message (a Story slug).
+ * @returns {{ fingerprints: string[], semanticKeys: string[] }|null}
+ * @throws {Error} On any shape the stamper cannot honour exactly.
+ */
+export function normalizeOwnedProvenance(raw, label = 'story') {
+  if (raw === undefined || raw === null) return null;
+  const where = `provenance on "${label}"`;
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${where} must be an object of ${PROVENANCE_SHAPE}`);
+  }
+  const out = { fingerprints: [], semanticKeys: [] };
+  for (const [field, list] of Object.entries(raw)) {
+    const spec = PROVENANCE_FIELDS[field];
+    if (!spec) {
+      throw new Error(
+        `${where} carries an unknown field: ${field} — only ${PROVENANCE_SHAPE} are stamped`,
+      );
+    }
+    out[field] = normalizeList(list, { where, field, ...spec });
+  }
+  return out;
+}
+
+/**
+ * Render the provenance **source document** for a set of owned identities, in
+ * the same footer vocabulary `carryProvenanceFooters` harvests from an audit
+ * seed. That reuse is the point: attribution changes *which* identities reach
+ * a Story body, never how they are stamped, so the carry stays additive,
+ * union-preserving and idempotent for an attributed plan exactly as it is for
+ * an un-attributed one.
+ *
+ * An empty (or absent) set renders the empty string, which the carry treats as
+ * nothing-to-do — so a Story that owns no findings is stamped with none rather
+ * than inheriting its siblings'.
+ *
+ * Expects the normalized shape {@link normalizeOwnedProvenance} returns; the
+ * validator runs first on every production path.
+ *
+ * @param {{ fingerprints?: string[], semanticKeys?: string[] }|null} [provenance]
+ * @returns {string}
+ */
+export function ownedProvenanceSource(provenance) {
+  const shas = provenance?.fingerprints ?? [];
+  const keys = provenance?.semanticKeys ?? [];
+  const parts = [];
+  if (shas.length > 0) parts.push(fingerprintFooter(shas));
+  if (keys.length > 0) parts.push(semanticKeyFooter(keys));
+  return parts.join('\n');
+}