mandrel 2.32.0 → 2.34.0

package/.agents/scripts/stories-wave-tick.js

@@ -55,7 +55,8 @@
  *     inFlight: number,
  *     cycleError: string | null,
  *     wedged: { reason, stories: [{ id, unmetBlockers }] } | null,
- *     inFlightReservation: { available, withheld: [{ id, blockedBy, reason }], note }
+ *     inFlightReservation: { available, withheld: [{ id, blockedBy, reason, source, paths }], note },
+ *     footprintGuard: { mode, withheld: [{ id, blockedBy, scope, source, paths }], advisory, note }
  *   }
  *
  * `inFlightReservation` reports the cross-beat half of the co-dispatch guard
@@ -70,6 +71,17 @@
  * `available: false` rather than an empty — and therefore indistinguishable —
  * result.
  *
+ * `footprintGuard` reports the **beat-local** half, which until Story #5044 was
+ * reported nowhere: a same-beat overlap skip was a bare `continue` inside
+ * `planReadySet`, so the Story vanished from `ready[]` with no field anywhere
+ * naming the collision. Every entry in either report now also carries the
+ * colliding `paths` and a `source` tag — `declared-overlap` when both Stories'
+ * `changes[]` named the path (intended serialization: two Stories really do
+ * rewrite the same generated baseline) versus `scraped-overlap` when only the
+ * text evidence produced it. `mode` names the `footprintGuard` config value;
+ * under `advisory` the collisions are detected and listed in `advisory[]` but
+ * dispatch follows the declared `depends_on` edges alone.
+ *
  * Probe mode adds fields the caller can no longer compute for itself:
  * `done: number[]` (the resolved done set, in-set ∪ satisfied foreign
  * blockers), `epilogueDue: boolean` (true exactly when every listed Story
@@ -111,19 +123,24 @@ import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 
 import { runAsCli } from './lib/cli-utils.js';
-import { getRunners, resolveConfig } from './lib/config-resolver.js';
+import { getPaths, getRunners, resolveConfig } from './lib/config-resolver.js';
 import { detectCycle } from './lib/Graph.js';
 import { Logger } from './lib/Logger.js';
 import { AGENT_LABELS } from './lib/label-constants.js';
 import { parseIds } from './lib/orchestration/resolve-stories.js';
 import { buildStoryAdjacency } from './lib/story-adjacency.js';
 import { expandIdList } from './lib/util/parse-id-list.js';
+import { OVERLAP_SOURCES } from './lib/wave-runner/footprint.js';
 import {
   createProbeContext,
   probeLiveState,
   validateProbeFlags,
 } from './lib/wave-runner/live-probe.js';
-import { planReadySet } from './lib/wave-runner/ready-set.js';
+import {
+  GUARD_MODES,
+  planReadySet,
+  WITHHOLD_SCOPES,
+} from './lib/wave-runner/ready-set.js';
 
 /**
  * Exit code for a wedged run — deliberately distinct from the cycle exit (2)
@@ -214,7 +231,29 @@ Output envelope:
     "wedged": null,
     "inFlightReservation": {
       "available": true,
-      "withheld": [{ "id": 4951, "blockedBy": 4949 }],
+      "withheld": [
+        {
+          "id": 4951,
+          "blockedBy": 4949,
+          "reason": "in-flight-earlier-beat",
+          "source": "declared-overlap",
+          "paths": ["lib/shared.js"]
+        }
+      ],
+      "note": "..."
+    },
+    "footprintGuard": {
+      "mode": "enforce",
+      "withheld": [
+        {
+          "id": 4952,
+          "blockedBy": 4951,
+          "scope": "beat",
+          "source": "scraped-overlap",
+          "paths": ["lib/other.js"]
+        }
+      ],
+      "advisory": [],
       "note": "..."
     }
   }
@@ -225,6 +264,15 @@ blocking id — so an unfilled slot is explained rather than mysterious. It need
 the in-flight Stories' footprints, which only --probe-live has: under --dag the
 report is { available: false } and selection de-conflicts within the beat only.
 
+footprintGuard names each Story withheld from THIS beat by a peer already
+admitted on it — the half that used to be an unreported skip — and every
+entry in either report carries the colliding paths plus a source tag
+(declared-overlap when both changes[] declarations named the path, else
+scraped-overlap from the text evidence). Its "mode" echoes
+delivery.deliverRunner.footprintGuard: under "advisory" the collisions are
+detected and listed in "advisory" but never withhold, and dispatch follows the
+declared depends_on edges alone.
+
 Exit codes:
   0 - Success, ready set emitted
   1 - Invalid input (missing/malformed DAG, invalid --concurrency/--in-flight/--done)
@@ -258,6 +306,7 @@ function inputErrorResult(message, concurrencyCap = null, inFlightValue = 0) {
       cycleError: null,
       wedged: null,
       inFlightReservation: null,
+      footprintGuard: null,
       inputError: message,
     },
     exitCode: 1,
@@ -299,10 +348,18 @@ const RESERVATION_REASONS = Object.freeze({
  * and no later beat of this run will clear it. `foreignHeldIds` splits the two
  * so each carries its own reason (Story #4960).
  *
+ * Each entry also carries the **colliding paths** and an
+ * `OVERLAP_SOURCES` tag (Story #5044). A withhold that names no path is one an
+ * operator cannot act on, and `declared-overlap` vs `scraped-overlap` is the
+ * difference between "these two Stories both declared this generated baseline,
+ * serializing them is the point" and "one Story's body happened to mention a
+ * path the other declared" — the same unfilled slot for two very different
+ * reasons.
+ *
  * @param {object[]|null|undefined} inFlightRecords
- * @param {Array<{id: number, blockedBy: number}>} withheld
+ * @param {Array<{id: number, blockedBy: number, source?: string, paths?: string[]}>} withheld
  * @param {Iterable<number>} [foreignHeldIds] Ids held by a foreign lease.
- * @returns {{ available: boolean, withheld: Array<{id: number, blockedBy: number, reason: string}>, note: string|null }}
+ * @returns {{ available: boolean, withheld: Array<{id: number, blockedBy: number, reason: string, source: string, paths: string[]}>, note: string|null }}
  */
 export function buildReservationReport(
   inFlightRecords,
@@ -326,10 +383,13 @@ export function buildReservationReport(
   }
   const foreign = new Set(foreignHeldIds);
   const classified = withheld.map((w) => ({
-    ...w,
+    id: w.id,
+    blockedBy: w.blockedBy,
     reason: foreign.has(w.blockedBy)
       ? RESERVATION_REASONS.FOREIGN_LEASE
       : RESERVATION_REASONS.EARLIER_BEAT,
+    source: w.source ?? OVERLAP_SOURCES.DECLARED,
+    paths: w.paths ?? [],
   }));
   return {
     available: true,
@@ -338,6 +398,87 @@ export function buildReservationReport(
   };
 }
 
+/**
+ * Report the **beat-local** half of the footprint guard, plus the guard mode
+ * itself (Story #5044).
+ *
+ * Until now a same-beat overlap skip was an anonymous `continue` inside
+ * `planReadySet`: the Story simply did not appear in `ready[]` and no field
+ * anywhere said why. That is the same unexplained-unfilled-slot failure the
+ * cross-beat `inFlightReservation` report was built to remove, left standing on
+ * the other half of the guard — and it is how a plan whose siblings collided
+ * only on machine-generated footer text ran fully serial without leaving a
+ * trace to notice.
+ *
+ * `withheld` and `advisory` are disjoint by construction: under `enforce` every
+ * detection withheld, under `advisory` none did. Reporting them as separate
+ * lists rather than one flagged list means a consumer counting withheld
+ * dispatches never has to inspect a boolean to get the count right.
+ *
+ * @param {Array<object>} footprintWithholds The kernel's complete ledger.
+ * @param {'enforce'|'advisory'} mode
+ * @returns {{ mode: string, withheld: object[], advisory: object[], note: string|null }}
+ */
+export function buildFootprintGuardReport(footprintWithholds, mode) {
+  const ledger = Array.isArray(footprintWithholds) ? footprintWithholds : [];
+  const project = ({ id, blockedBy, scope, source, paths }) => ({
+    id,
+    blockedBy,
+    scope,
+    source,
+    paths,
+  });
+  const beat = ledger
+    .filter((w) => w.scope === WITHHOLD_SCOPES.BEAT && w.enforced)
+    .map(project);
+  const advisory = ledger.filter((w) => !w.enforced).map(project);
+  return {
+    mode,
+    withheld: beat,
+    advisory,
+    note: footprintGuardNote(beat, advisory, mode),
+  };
+}
+
+/**
+ * Render the operator-facing note for the beat-local guard, naming the
+ * colliding path(s) for every entry. `null` when the guard neither withheld nor
+ * waved anything through.
+ *
+ * @param {object[]} beat
+ * @param {object[]} advisory
+ * @param {string} mode
+ * @returns {string|null}
+ */
+function footprintGuardNote(beat, advisory, mode) {
+  const detail = (entries) =>
+    entries
+      .map(
+        (w) =>
+          `#${w.id} ← #${w.blockedBy} on ${w.paths.join(', ')} (${w.source})`,
+      )
+      .join('; ');
+  if (beat.length > 0) {
+    return (
+      `${beat.length} Story(ies) withheld from THIS beat because their file ` +
+      `footprint overlaps a peer already admitted on it — ${detail(beat)}. ` +
+      `Each is still eligible and re-admits on a later beat once its peer ` +
+      `lands. A ${OVERLAP_SOURCES.SCRAPED} source means the collision came ` +
+      `from path evidence in the Story text rather than from either ` +
+      `changes[] declaration.`
+    );
+  }
+  if (advisory.length > 0) {
+    return (
+      `footprintGuard is '${mode}': ${advisory.length} footprint collision(s) ` +
+      `were detected and NOT enforced — ${detail(advisory)}. Dispatch followed ` +
+      `the declared depends_on edges alone. Set ` +
+      `delivery.deliverRunner.footprintGuard: 'enforce' to serialize these.`
+    );
+  }
+  return null;
+}
+
 /**
  * Render the operator-facing reservation note, one sentence per reason class
  * present. Neither class is a failure or a wedge, but they clear by different
@@ -600,6 +741,29 @@ export function resolveCapPrecedence({ cwd, config, override } = {}) {
   };
 }
 
+/**
+ * Resolve the two footprint-guard inputs from the same config seam the cap
+ * comes from (Story #5044).
+ *
+ * `tempRoot` is threaded rather than hardcoded because the evidence scrape must
+ * exclude the project's *configured* scratch root: a consumer that sets
+ * `project.paths.tempRoot: '.scratch'` would otherwise have every sibling
+ * citing a report under it collide, which is the exact defect this Story
+ * removes for the default `temp/`.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]     Repo root for config resolution.
+ * @param {object} [opts.config]  Pre-resolved config (test injection).
+ * @returns {{ footprintGuard: 'enforce'|'advisory', tempRoot: string }}
+ */
+export function resolveFootprintGuardSettings({ cwd, config } = {}) {
+  const resolved = config ?? resolveConfig({ cwd });
+  return {
+    footprintGuard: getRunners(resolved).deliverRunner.footprintGuard,
+    tempRoot: getPaths(resolved).tempRoot,
+  };
+}
+
 /**
  * Build the per-beat ready-set envelope from a validated DAG.
  *
@@ -648,6 +812,8 @@ export function buildReadySetEnvelope(
     inFlight = 0,
     inFlightRecords = null,
     foreignHeldIds = [],
+    footprintGuard = GUARD_MODES.ENFORCE,
+    tempRoot,
   },
 ) {
   const totalStories = nodes.length;
@@ -668,6 +834,11 @@ export function buildReadySetEnvelope(
     // which Stories a reservation withheld (Story #4950). Never omitted on a
     // resolved beat: an absent report reads exactly like an empty one.
     inFlightReservation: buildReservationReport(inFlightRecords, []),
+    // The beat-local half of the same guard, plus the mode it ran in (Story
+    // #5044). Also never omitted: a same-beat skip used to be reported nowhere
+    // at all, which is precisely how an evidence-widening artifact could
+    // serialize a whole run unnoticed.
+    footprintGuard: buildFootprintGuardReport([], footprintGuard),
   };
 
   if (totalStories === 0) {
@@ -714,7 +885,7 @@ export function buildReadySetEnvelope(
     return rec;
   });
 
-  const { selected, withheldByInFlight } = planReadySet({
+  const { selected, footprintWithholds, guardMode } = planReadySet({
     stories: records,
     doneIds,
     inFlight,
@@ -723,13 +894,21 @@ export function buildReadySetEnvelope(
     // contract (an array) while `base.inFlightReservation` reports that the
     // reservation itself was unavailable rather than merely empty.
     inFlightRecords: inFlightRecords ?? [],
+    footprintGuard,
+    tempRoot,
   });
   const ready = selected.map((rec) => rec.id);
+  // The cross-beat report reads the enforced in-flight slice of the kernel's
+  // ledger rather than the legacy `withheldByInFlight` list, so it carries the
+  // colliding paths and the overlap source through to the operator.
   const reservation = buildReservationReport(
     inFlightRecords,
-    withheldByInFlight,
+    footprintWithholds.filter(
+      (w) => w.scope === WITHHOLD_SCOPES.IN_FLIGHT && w.enforced,
+    ),
     foreignHeldIds,
   );
+  const guardReport = buildFootprintGuardReport(footprintWithholds, guardMode);
 
   // Wedge detection (Story #4540). `ready: []` is normal while work is in
   // flight — the loop is simply waiting. But ready-empty AND nothing in
@@ -750,6 +929,7 @@ export function buildReadySetEnvelope(
         ready,
         wedged: wedge,
         inFlightReservation: reservation,
+        footprintGuard: guardReport,
       },
       exitCode: WEDGED_EXIT_CODE,
     };
@@ -761,6 +941,7 @@ export function buildReadySetEnvelope(
       ready,
       wedged: null,
       inFlightReservation: reservation,
+      footprintGuard: guardReport,
     },
     exitCode: 0,
   };
@@ -896,6 +1077,7 @@ export function runStoriesWaveTick({
     capPrecedence,
     doneIds,
     inFlight: inFlightValue,
+    ...resolveFootprintGuardSettings({ cwd, config }),
   });
 }
 
@@ -1001,6 +1183,7 @@ export async function runProbedStoriesWaveTick({
     // ...and the only mode that can tell a foreign lease-holder apart from
     // this run's own earlier-beat dispatch (Story #4960).
     foreignHeldIds: foreignHeld.map((h) => h.id),
+    ...resolveFootprintGuardSettings({ cwd, config }),
   });
 
   const done = [...doneIds].sort((a, b) => a - b);

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

@@ -189,6 +189,32 @@ Labels applied:
   (cross-audit groups carry multiple).
 - `risk::high` — added when any finding in the group is Critical.
 
+### Phase 5c — Wire the cohort's declared ordering (**required**)
+
+Creating the Issues is only the first pass. `groupFindings` detects `edges[]`
+between groups, but at emit time no group has an issue number, so each body
+ships with an empty `depends_on` and the cohort has **no declared ordering
+at all**. Replay the numbers you just opened:
+
+```bash
+node .agents/scripts/audit-to-stories.js --wire-edges \
+  --plan temp/audits/audit-to-stories-plan.json \
+  --ids '{"<groupKey>": <issueNumber>, ...}' \
+  --out temp/audits/audit-to-stories-wired.json
+```
+
+Each entry in the emitted `--json` payload carries its own `groupKey` and
+`dependsOn`, so the map is a lookup, not a reconstruction. The pass re-renders
+every Story that has a resolvable blocker with a canonical
+`---` / `blocked by #N` footer **and** mirrors the same edges as native
+GitHub `blocked_by` relations. An edge whose target was never opened (deduped,
+ledger-suppressed) drops rather than becoming a `blocked by #undefined`.
+
+**Do not skip this.** `/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 `/deliver` will co-dispatch Stories the edges say
+must follow one another.
+
 ## Phase 6 — Idempotency (folded into Phase 1 scan)
 
 The `--scan` step routes each group's findings through the shared

package/.agents/workflows/helpers/deliver-light.md

@@ -131,8 +131,11 @@ answer).
    invoked, not reimplemented.
 
 3. **Implement + self-eval.** `cd` into `workCwd`, implement the change, run
-   `npm test` once in the worktree, then run the bounded acceptance self-eval
-   loop ([`deliver-story.md`](deliver-story.md) Step 1a). Commit
+   the full suite once in the worktree **so close can credit it** — the
+   crediting invocation and the freshness contract are
+   [`deliver-story.md`](deliver-story.md) Step 1.3, unchanged here — then run
+   the bounded acceptance self-eval loop
+   ([`deliver-story.md`](deliver-story.md) Step 1a). Commit
    on `story-<id>` with `(refs #<storyId>)`.
 
 4. **Diff backstop.** Before close, re-check the ACTUAL diff:

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

@@ -94,7 +94,7 @@ probe logs a warning and leans on init's lease refusal alone.
 **Overlapping footprints are reserved across beats, not just within one.** A
 Story sharing a **concrete** path with a still-implementing Story is withheld
 and named in `inFlightReservation: { available, withheld: [{ id, blockedBy,
-reason }], note }`, where `reason` is `in-flight-earlier-beat` or
+reason, source, paths }], note }`, where `reason` is `in-flight-earlier-beat` or
 `foreign-lease`. Like `foreignHeld` this is neither a failure nor a wedge — the
 Story re-admits automatically once its blocker leaves the in-flight set — and
 it exists so an unfilled slot is explained rather than mysterious. A **glob**
@@ -103,6 +103,33 @@ across beats; it still serializes its own beat. Reservation needs the in-flight
 Stories' footprints, so it is a `--probe-live` capability: under `--dag` the
 report is `available: false` and selection de-conflicts within the beat only.
 
+**Beat-local skips are reported too**, in `footprintGuard: { mode, withheld,
+advisory, note }`. They used to be an unreported skip, so a Story simply
+vanished from `ready[]` and an unfilled slot read exactly like a cap that was
+never reached. Every entry in **either** report carries the colliding `paths`
+and a `source` tag:
+
+- `declared-overlap` — both Stories' `changes[]` named the path (or a declared
+  glob). Intended serialization; two Stories rewriting the same generated
+  baseline must not co-dispatch.
+- `scraped-overlap` — only the text evidence produced it. Real signal — a
+  declaration is only a lower bound — but the class where a false positive is
+  possible.
+
+**The evidence scrape excludes exactly three token sources**, each structurally
+incapable of naming an edit target: `audit-fingerprints` /
+`audit-semantic-keys` provenance footers, paths under `project.paths.tempRoot`,
+and markdown-link URL interiors. Nothing else is stripped — a
+`<!-- DECOMPOSITION -->` block's paths are genuine intent
+([`instructions.md` § 7](../../instructions.md)) and still count.
+
+**`delivery.deliverRunner.footprintGuard`** selects what a collision does:
+
+| Mode | Effect |
+| --- | --- |
+| `enforce` (default) | A collision withholds the Story. Keep this unless you have a reason — the guard encodes delivery-time-only knowledge (open implementation windows, foreign leases, ground moved since planning) no `depends_on` edge can carry. |
+| `advisory` | Collisions are still **detected** and listed in `footprintGuard.advisory`, but never withhold; dispatch follows the declared `depends_on` edges alone. A throughput trade for a run whose ordering is fully declared. |
+
 ## Dispatch mechanics (role-scoped by default)
 
 **A single-Story run executes inline.** Sub-agent isolation is

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

@@ -161,6 +161,63 @@ terminal envelope are byte-identical either way.
 
 ---
 
+## Declared dependency edges — what actually gates dispatch
+
+`resolve-stories.js` builds each `dag[].dependsOn` from the **union of two
+declared-edge channels**, and nothing else: the Story body's footer block and
+the issue's native GitHub `blocked_by` relations. Both are read strictly — an
+edge the resolver cannot read is never quietly reported as an edge that does
+not exist.
+
+**The body channel is footer-scoped.** Only a `blocked by #N` line standing
+alone inside the `---` footer block declares an edge:
+
+```markdown
+## Goal
+
+…
+
+---
+
+blocked by #42
+```
+
+Prose elsewhere in the body declares **nothing**, and this is a deliberate,
+user-visible change from the whole-body scan that preceded it. A sentence
+merely mentioning a blocker — an example, a changelog note, an acceptance
+criterion quoting the phrase — used to mint a real dispatch gate that withheld
+the Story until an unrelated issue closed. `plan-persist` has always
+serialized the canonical footer form, so no machine-authored body is affected;
+only a **hand-written prose edge** stops gating, and the fix is to move it into
+the footer block. The loose spellings never reached the footer grammar either:
+`depends on #N`, `Blocked by: #N`, and `blocked by #N once X lands` all declare
+nothing. One grammar serves both readers — the body parser and the
+dispatch-edge parser share it — so what a Story body round-trips and what gates
+dispatch cannot drift apart.
+
+**The native channel fails loud.** The read paginates to exhaustion (a
+first-page read silently truncated a Story's gates at GitHub's 30-item
+default), and **a 404 is not an empty result**. An issue with no dependencies
+answers `200 []`; a 404 is how GitHub also answers a token that cannot see the
+dependencies API, so treating it as "no edges" erased every native edge in the
+run under a mis-scoped token, silently, with a clean exit code. Any non-OK
+read now fails the resolution naming the Story — check the token's scopes
+first. The one degrade that is scoped rather than fatal is a **cross-repo
+edge**: another repository's issue number cannot be matched against this
+repo's same-numbered issue without risking a false match, so that edge is
+dropped with a warning naming the Story, and its siblings resolve normally.
+
+**Edges are monotone — retraction is not built.** Both channels only ever
+_add_ a gate for the current resolution. Removing a `blocked by` footer line
+or deleting a native relation makes the edge absent from the **next** resolve,
+but nothing reconciles an edge that a previous run already acted on, and the
+write path never deletes a native relation it did not need. In practice that
+means: re-resolve after editing edges, and treat a stale gate as a body/issue
+edit plus a fresh `resolve-stories.js` run, never as something delivery
+un-declares on your behalf. This is a known limitation, not an oversight.
+
+---
+
 ## Step 1 — Implementation detail
 
 **Docs context — digest-first.** Read a full doc only when the Story's own
@@ -176,12 +233,34 @@ runs maker-blind at Story-scope review inside the close subprocess. The
 dispatch step produces `checklistPath` from the Story's predicted footprint
 before it spawns the worker — see [`/deliver`](../deliver.md).
 
-**Pre-eval full-suite discipline (spine step 5).** Repo-invariant guards —
+**Pre-eval full-suite discipline (spine step 1.3).** Repo-invariant guards —
 drift-guard and schema tests living outside the Story's scoped greps — are
 the failure class that actually bounces deliveries: close-validation
 discovers them only after the whole close pipeline has run, at several times
 the cost of one pre-eval full-suite run.
 
+**Run it so close can credit it.** Close skips a gate that already passed at
+the current HEAD, but a bare `npm test` deposits no such record — the suite
+then runs twice per delivery, once here and once in the close gate chain.
+Pick the invocation by the same predicate `close-validation/gates.js` uses to
+choose its test gate:
+
+```bash
+# CRAP gate enabled (default) + a `test:coverage` script — writes the stamp
+# the close `coverage-capture` gate reads:
+node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>
+# otherwise — the evidence record the close `test` gate reads. <workCwd> must
+# be ABSOLUTE and the runner exactly `npm test`: both sides hash
+# {cmd, args, cwd}, so a relative path or a wrapper misses the credit.
+node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
+  --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
+```
+
+The credit expires the moment it stops describing the tree: evidence is keyed
+on HEAD, the capture stamp on a content digest of `crap.targetDirs`. A
+self-eval fix — or any commit — invalidates it and close re-runs the suite for
+real, so this never trades away the gate.
+
 **Conflict with `main` mid-implementation** → resolve as you would any branch
 rebase. There is no `epic/<id>` intermediate, so the rebase base is `main`
 directly.

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

@@ -75,9 +75,11 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
    `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
 2. Implement and commit on the Story branch, iterating with quick advisory
    gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3.
-3. Run `npm test` once in the worktree **before Step 1a**: repo-invariant
+3. Run the full suite once in the worktree **before Step 1a**: repo-invariant
    guards outside the Story's scoped greps are the failure class that bounces
-   deliveries. Fix and commit first, then run the self-eval loop.
+   deliveries. Fix and commit first, then run the self-eval loop. Run it **so
+   Step 3 credits it** — a bare `npm test` records nothing, so close re-runs
+   the identical suite (reference § Step 1, "Pre-eval full-suite discipline").
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 

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

@@ -243,6 +243,82 @@ as a hard error — so the grounding contract is the author's own targeted reads
 plus that gate. There is no pre-computed codebase snapshot to fall back on,
 and no manifest-derived replacement to build.
 
+### Per-Story audit provenance (`provenance`)
+
+An audit-seeded plan carries dedup identities forward so the next sweep
+recognises what it already planned. The optional top-level `provenance` field
+says **which of them this Story owns**:
+
+```jsonc
+{
+  "slug": "own-the-seam",
+  "provenance": {
+    "fingerprints": ["<40-char sha1, one per finding this Story tracks>"],
+    "semanticKeys": ["architecture␟lib/owned.js"]
+  }
+}
+```
+
+Both arrays are optional; a malformed entry is a validator rejection, never a
+silent drop — a dropped identity is invisible until the next sweep re-files
+work this plan already tracked.
+
+| `provenance` | What persist stamps |
+| --- | --- |
+| Present | **Exactly** the identities listed — siblings' groups never leak in. |
+| Present but empty (`{}`) | Nothing. "Owns no findings" is a real answer. |
+| **Absent** | The **whole seed's** footers (the union) — the recall-safe default. |
+
+**The union fallback is load-bearing, not legacy.** Leaving the authoring agent
+to hand-carry provenance out of the seed's HTML comments was measured to fail —
+a remembered step is no step at all — and the mechanical union carry is what
+closed it. Attribution is additive: it sharpens a plan that opts in and changes
+nothing for one that does not. Never remove the fallback to "finish the
+migration".
+
+Attribution is what makes the next sweep's dedup answerable rather than
+arbitrary. Under the union every sibling carried every key, so a finding
+confirming against several open Stories could only pick one at random, and a
+key whose owning Story had since **closed** was masked by any open neighbour —
+a genuine regression filed as a routine update. With ownership stamped, the
+issue carrying a finding's own fingerprint decides both the match and its
+state (`lib/findings/route-finding.js`).
+
+The audit path authors this mechanically from the per-group footers the seed
+already carries — see [`audit-to-stories`](../audit-to-stories.md). A `--seed`
+or `--tickets` plan has nothing to attribute and omits the field.
+
+## Cross-Story conflict analysis at persist
+
+The conflict passes run **twice**: once over the raw `stories.json` payload
+(alongside the freshness, file-assumption and sizing gates), and again over the
+**assembled, footer-stamped bodies** — the artifact persist actually posts.
+The second pass is not belt-and-braces. The canonical authoring shape carries
+`acceptance[]` / `verify[]` at the ticket's top level and assembly folds them
+into the body, so the passes that scan `body.acceptance` / `body.verify`
+(`implicit-cross-story-dep`, `missing-bdd-scaffold`) saw two empty arrays on
+the real payload and emitted nothing. Both passes complete before the first
+`createIssue`, so a refusal still costs no writes.
+
+`shared-editor` findings are rendered into the posted `plan-summary` comment,
+directly beneath the wave table: the table promises which Stories can run
+together, and a path two same-wave Stories both write is exactly where that
+promise breaks. Promise and caveat belong on one durable surface — previously
+the caveat was a stderr warning nobody kept.
+
+Two `planning.*` knobs upgrade a conflict class from advisory to a hard
+refusal. **Both default to `false` and are documented, not recommended:**
+
+| Knob | Upgrades | Why it is off |
+| --- | --- | --- |
+| `planning.failOnSharedEditors` | `shared-editor` → `hard` | Co-editing one file is routine and often correct; the delivery scheduler already serializes file-overlapping Stories. |
+| `planning.requireExplicitCrossStoryDeps` | `implicit-cross-story-dep` → `hard` | Path references are matched by substring, so a legitimate mention in prose can read as a dependency. |
+
+Turn one on for a repo where the class is genuinely fatal; expect a refusal to
+name the Stories and the fix (a `depends_on` edge, or folding the shared edit
+into one Story). The sibling knobs `failOnRegistryConflicts`,
+`failOnMissingBddScaffold` and `failOnLargeFanOut` behave the same way.
+
 ## Tickets mode — authoring `supersedes[]`
 
 In `--tickets` mode each Story carries a top-level `supersedes` array claiming

package/docs/CHANGELOG.md

@@ -15,6 +15,32 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.34.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.33.0...mandrel-v2.34.0) (2026-08-27)
+
+
+### Fixed
+
+* **baselines:** weight the mutation rollup by mutant count and gate the migration (refs [#5058](https://github.com/dsj1984/mandrel/issues/5058)) ([#5062](https://github.com/dsj1984/mandrel/issues/5062)) ([a645d30](https://github.com/dsj1984/mandrel/commit/a645d3085450b4dae39ae5d0a9b9844014535f84))
+* **coverage:** describe incrementalCoverage honestly, drop inert forwarding (refs [#5065](https://github.com/dsj1984/mandrel/issues/5065)) ([#5066](https://github.com/dsj1984/mandrel/issues/5066)) ([04ff450](https://github.com/dsj1984/mandrel/commit/04ff450cb1774a1faa0b4f901f1e09261b0ae00a))
+* delivery lifecycle: credit the Step 1 full-suite run to close and enable incremental coverage by default ([#5063](https://github.com/dsj1984/mandrel/issues/5063)) ([#5064](https://github.com/dsj1984/mandrel/issues/5064)) ([39b1ea4](https://github.com/dsj1984/mandrel/commit/39b1ea421c9a8a43f35ad4c8cbc082e1f2ead8c4))
+* **plan-persist:** re-carry audit provenance onto dependent Stories (refs [#5056](https://github.com/dsj1984/mandrel/issues/5056)) ([#5060](https://github.com/dsj1984/mandrel/issues/5060)) ([548cc8a](https://github.com/dsj1984/mandrel/commit/548cc8a46afc5b643452060cc3a03bf71a874b89))
+
+## [2.33.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.32.0...mandrel-v2.33.0) (2026-08-07)
+
+
+### Added
+
+* deliver: widen footprints from edit intent only, explain every withhold, and give standalone audit cohorts declared edges ([#5044](https://github.com/dsj1984/mandrel/issues/5044)) ([#5049](https://github.com/dsj1984/mandrel/issues/5049)) ([6bd0653](https://github.com/dsj1984/mandrel/commit/6bd0653e88e07ddbcc90c3c947b5f135374649d4))
+* plan: stamp only the provenance a Story owns, and run cross-Story conflict analysis over the bodies persist actually writes ([#5045](https://github.com/dsj1984/mandrel/issues/5045)) ([#5048](https://github.com/dsj1984/mandrel/issues/5048)) ([804b308](https://github.com/dsj1984/mandrel/commit/804b3087c001f21815aecb109bb636e59a87b2cb))
+
+
+### Fixed
+
+* check-knip-entries: resolve the entry list through knip's own config resolver, and skip cleanly when there is no knip config ([#5039](https://github.com/dsj1984/mandrel/issues/5039)) ([#5041](https://github.com/dsj1984/mandrel/issues/5041)) ([7f69a18](https://github.com/dsj1984/mandrel/commit/7f69a18ead79da77779981bec3eed8772dc05643))
+* deliver: make the declared-edge channel trustworthy — paginate native reads, fail loud on 404, parse footers strictly ([#5046](https://github.com/dsj1984/mandrel/issues/5046)) ([#5047](https://github.com/dsj1984/mandrel/issues/5047)) ([38b543d](https://github.com/dsj1984/mandrel/commit/38b543dec2634318b2407b54404239e7ae34d381))
+* **lint:** add a --root scan seam so the lint test stops mutating the shared tree (refs [#5052](https://github.com/dsj1984/mandrel/issues/5052)) ([#5053](https://github.com/dsj1984/mandrel/issues/5053)) ([69d1952](https://github.com/dsj1984/mandrel/commit/69d1952fb7410659ca21a9bb0d34eefadb654d2e))
+* plan: resolve the cross-Story conflict policy once for the raw and assembled passes ([#5050](https://github.com/dsj1984/mandrel/issues/5050)) ([711199a](https://github.com/dsj1984/mandrel/commit/711199a861bc1e85218a09fe4674c507b0c0edb1))
+
 ## [2.32.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.31.0...mandrel-v2.32.0) (2026-08-06)