mandrel 2.57.0 → 2.59.0

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -29,11 +29,8 @@ import { parse as parseStoryBody } from '../story-body/story-body.js';
 import {
   renderStoryAuthorCore,
   renderStorySplitRules,
+  ticketsModePromptField,
 } from '../templates/decomposer-prompts.js';
-import {
-  renderAcceptanceSpecSystemPrompt,
-  renderTechSpecSystemPrompt,
-} from '../templates/spec-author-prompts.js';
 import { concurrentMap, FANOUT_CONCURRENCY } from '../util/concurrent-map.js';
 import { buildComplexitySignals } from './complexity-gate.js';
 import { findDependencyCandidates } from './dependency-candidates.js';
@@ -328,6 +325,17 @@ export function renderStoriesTemplate({ complexitySignals = null } = {}) {
       title: 'Fill: short descriptive title',
       body: {
         goal: 'Fill: one sentence stating why this Story exists.',
+        // A filled, multi-checkpoint example rather than a placeholder
+        // (Story #5332): `## Slicing` is how one cohesive sweep stays one
+        // Story, so the skeleton has to show an author what a checkpoint
+        // list looks like. Each line is a stage of the work — a commit
+        // boundary inside one session — never a restatement of an
+        // acceptance item, which states what is true once the Story lands.
+        slicing:
+          '1. Re-anchor the shared constant and its consumers.\n' +
+          '2. Move the gate ahead of the first write and arm the refusal.\n' +
+          '3. Delete the superseded module, its test and its flag.\n' +
+          '4. Regenerate the affected baselines; run the full gate chain.',
         spec:
           'Optional — contract and invariants only: interfaces, status ' +
           'codes, security invariants, and load-bearing constraints with ' +
@@ -339,7 +347,7 @@ export function renderStoriesTemplate({ complexitySignals = null } = {}) {
         non_goals: [],
       },
       acceptance: [
-        'Fill: an outcome a PR reviewer can confirm from the diff and the verify output (three to six items)',
+        'Fill: an outcome a PR reviewer can confirm from the diff and the verify output — as many as the capability has, no target and no ceiling',
       ],
       verify: [
         'Fill: exact command or test path — the mechanical check the acceptance item rests on',
@@ -366,25 +374,23 @@ function countEnumeratedItems(text) {
 }
 
 /**
- * Delta-shaped change-request verbs — the `core/scope-triage` skill's
- * change-request rubric routes these to `story` by default when the
- * footprint stays inside Story width.
+ * Delta-shaped change-request verbs — a change request naming one of these
+ * stays a Story by default when the footprint stays inside Story width.
  */
 const DELTA_VERB_RE =
   /\b(fix(?:es)?|tweak(?:s)?|extend(?:s)?|update(?:s)?|adjust(?:s)?|rename(?:s)?|correct(?:s)?|patch(?:es)?|bug|regression|flaky)\b/i;
 
 /**
- * Deterministic, CLI-applied scope-triage verdict over a raw `--seed` text
- * (#4496 fix 6). Embedding the verdict in the `--seed` envelope removes the
- * two skill Reads (`core/scope-triage` + the gate fragment's rubric pass)
- * from the headless path; the attended path keeps the skill-based judgment.
+ * Deterministic, CLI-applied scope signal over a raw `--seed` text
+ * (#4496 fix 6). Embedding it in the `--seed` envelope keeps the headless
+ * path from needing a judgment pass of its own.
  *
- * The heuristics anchor to the same granularity SSOT the skill anchors to —
+ * The heuristics anchor to the granularity SSOT —
  * `DELIVERABLE_GRANULARITY_GUIDANCE` in `ticket-validator-sizing.js` (one
  * Story = one coherent capability slice; multiple independent capabilities =
- * an Epic) — and to the skill's change-request delta rubric. Like the skill,
- * the verdict is **advisory**: being wrong in the `epic` direction is cheap,
- * and `borderline` is a first-class output, not a forced call.
+ * an Epic) — and to the change-request delta rubric above. The verdict is
+ * **advisory**: being wrong in the `epic` direction is cheap, and
+ * `borderline` is a first-class output, not a forced call.
  *
  * @param {{ seedText?: string }} args
  * @returns {{ verdict: 'epic'|'story'|'borderline', reasons: string[], advisory: true, appliedBy: 'cli' }}
@@ -633,21 +639,29 @@ function withAdvisorySignals(complexitySignals, { config, cwd } = {}) {
 
 /**
  * Render the authoring system prompts the collapsed pipeline's single
- * authoring pass consumes. The spec/acceptance prompts render from
- * `lib/templates/spec-author-prompts.js` (the M3/M8 handshake — envelope
- * authoritative from day one); the story prompt is the N=1 core from
- * `lib/templates/decomposer-prompts.js`, with the schedule and partition
- * rules a planner reads only when the default-single split policy clears
- * carried separately as `storySplitRules` (Story #5312).
+ * authoring pass consumes: the N=1 core from
+ * `lib/templates/decomposer-prompts.js`, with the schedule rules and the
+ * collision refusal a planner reads only when the default-single split policy
+ * clears carried separately as `storySplitRules` (Story #5312).
+ *
+ * Story #5332 deleted the `spec` / `acceptance` fields with the module that
+ * rendered them: nothing read either, and both contradicted the current
+ * contract — one asserting Spec budgets that no longer exist, the other
+ * demanding the verify tier suffixes tickets mode now strips.
  *
- * @returns {{ spec: string, acceptance: string, story: string, storySplitRules: string }}
+ * `storyTicketsRules` is the one mode-conditional field (Story #5323): it
+ * only means anything when the seed is an existing ticket, and an envelope
+ * that carries it in every mode teaches the author to look for a source
+ * ticket that a `--seed` run does not have.
+ *
+ * @param {{ mode?: string }} [args]
+ * @returns {{ story: string, storySplitRules: string, storyTicketsRules?: string }}
  */
-export function buildSystemPrompts() {
+export function buildSystemPrompts({ mode } = {}) {
   return {
-    spec: renderTechSpecSystemPrompt(),
-    acceptance: renderAcceptanceSpecSystemPrompt(),
     story: renderStoryAuthorCore(),
     storySplitRules: renderStorySplitRules(),
+    ...ticketsModePromptField(mode),
   };
 }
 
@@ -1007,7 +1021,7 @@ async function buildTicketsModeEnvelope({
     memoryPoolAdvisory: authoring.memoryPoolAdvisory,
     priorFeedback: authoring.priorFeedback,
     ticketSchema: TICKET_SCHEMA_DESCRIPTOR,
-    systemPrompts: buildSystemPrompts(),
+    systemPrompts: buildSystemPrompts({ mode: 'tickets' }),
     planState: null,
     planProfile:
       ticketIds.length === 1 ? 'story-default' : 'story-from-tickets',

package/.agents/scripts/lib/orchestration/plan-persist/acceptance-handle-repair.js

@@ -0,0 +1,107 @@
+/**
+ * acceptance-handle-repair.js — repair-before-judging for the `AC-<n>:`
+ * presentation handle on authored acceptance items (Story #5323).
+ *
+ * The handle belongs to the body renderer, which numbers each checkbox from
+ * its position in `acceptance[]` (`story-body.js`). An author planning from
+ * an existing ticket reads that rendered body as a template and carries the
+ * handle forward, so the persisted checkbox reads `- [ ] AC-1: AC-1: …`; a
+ * lettered handle copied out of a hand-edited source (`AC-14a:`) misnumbers
+ * the rest of the list against its own text.
+ *
+ * The correction is mechanical and total — strip the handle the renderer
+ * will re-apply — so this module applies it and **reports** it, exactly as
+ * `changes-repair.js` does for the `{ path, assumption }` formality. Charging
+ * the author a re-draft round to paste back text the strip already produced
+ * buys nothing.
+ *
+ * It lives beside the validator rather than inside it for the same reason
+ * `changes-repair.js` does: the validator's job is to judge, and mixing a
+ * mutating repair pass into a module of pure collectors muddies both.
+ * `persist-helpers.js#validateTickets` calls this first, then the validators.
+ *
+ * @module lib/orchestration/plan-persist/acceptance-handle-repair
+ */
+
+import { stripAcceptanceHandle } from '../../story-body/story-body.js';
+import { renderChangeRepair } from './changes-repair.js';
+
+/**
+ * Strip the handle off one surface's `acceptance[]`, recording each distinct
+ * strip on `repairs`.
+ *
+ * @param {object} surface An object that may carry an `acceptance` array.
+ * @param {string} slug
+ * @param {Set<string>} reported Items already reported for this ticket.
+ * @param {object[]} repairs Accumulator, mutated.
+ * @returns {void}
+ */
+function repairSurface(surface, slug, reported, repairs) {
+  if (!Array.isArray(surface.acceptance)) return;
+  surface.acceptance = surface.acceptance.map((item) => {
+    const { text, stripped } = stripAcceptanceHandle(item);
+    if (!stripped) return item;
+    const from = String(item ?? '');
+    if (!reported.has(from)) {
+      reported.add(from);
+      repairs.push({ kind: 'acceptance-handle', slug, from, to: text });
+    }
+    return text;
+  });
+}
+
+/**
+ * Strip the presentation `AC-<n>:` handle off every authored `acceptance[]`
+ * item, on both surfaces that can carry one: the ticket's top-level array
+ * (the machine contract) and a structured body's.
+ *
+ * A serialized **string** body needs no pass of its own — `parse()` strips
+ * the handle with the same grammar this does, so the two surfaces converge
+ * on one list whichever carried the handle, and the contract sync (which
+ * fails closed on a disagreement) sees them agree.
+ *
+ * Mutates `tickets` in place — the persist pipeline threads this same array
+ * on to assembly. Total: a non-array argument and non-Story tickets are
+ * no-ops.
+ *
+ * @param {object[]} tickets
+ * @returns {Array<{ kind: 'acceptance-handle', slug: string, from: string, to: string }>}
+ */
+export function normalizeAcceptanceHandles(tickets) {
+  const repairs = [];
+  for (const ticket of Array.isArray(tickets) ? tickets : []) {
+    if (!ticket || typeof ticket !== 'object' || ticket.type !== 'story') {
+      continue;
+    }
+    const slug = ticket.slug ?? ticket.title ?? '<unknown>';
+    // A ticket normally carries the same list on both surfaces, so report
+    // each distinct item once — the operator reads one correction, not two.
+    const reported = new Set();
+    repairSurface(ticket, slug, reported, repairs);
+    const body = ticket.body;
+    if (body && typeof body === 'object') {
+      repairSurface(body, slug, reported, repairs);
+    }
+  }
+  return repairs;
+}
+
+/**
+ * Render one entry of the dry-run's mixed repair list.
+ *
+ * The list carries two kinds — a `changes[]` entry repaired by probing base,
+ * and an `acceptance[]` item whose handle was normalised off — and both are
+ * mechanical corrections the run applied on the author's behalf, so both
+ * belong on the one list the operator reads. This module owns the dispatch
+ * because it owns the newer kind: it renders its own line and delegates
+ * every other kind to `changes-repair.js`, so neither producer has to know
+ * the other's shape.
+ *
+ * @param {{ kind?: string, slug: string, from: string, to?: string }} repair
+ * @returns {string}
+ */
+export function renderRepair(repair) {
+  if (repair.kind !== 'acceptance-handle') return renderChangeRepair(repair);
+  const { slug, from, to } = repair;
+  return `Story "${slug}": acceptance[] item "${from}" carried an AC-<n> handle — normalised to "${to}"; the body renderer numbers the checkboxes.`;
+}

package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js

@@ -261,7 +261,12 @@ function repairTicket(ticket, existsAtBase) {
 }
 
 /**
- * Render one repair as the dry-run line the operator reads.
+ * Render one `changes[]` repair as the dry-run line the operator reads.
+ *
+ * The dry-run's repair list is mixed — an `acceptance[]` handle strip is
+ * reported on it too — but the dispatch across kinds lives in
+ * [`acceptance-handle-repair.js`](acceptance-handle-repair.js)`#renderRepair`,
+ * which delegates here for this kind. Each producer owns its own line.
  *
  * @param {{ slug: string, from: string, path: string, assumption: string, reason: string }} repair
  * @returns {string}

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

@@ -10,9 +10,10 @@
  * checkout on CI has no local `main`), else nothing — a shallow checkout
  * with no base at all skips the probes instead of reading every path as
  * absent.
- *   - `validateTickets(tickets, config, opts)` — repairs the mechanical
- *     `changes[]` formalities against the base branch, then runs the
- *     cross-link, freshness, and task-body validators in one pass.
+ *   - `validateTickets(tickets, config, opts)` — normalises the authored
+ *     `acceptance[]` handles and repairs the mechanical `changes[]`
+ *     formalities against the base branch, then runs the cross-link,
+ *     freshness, and task-body validators in one pass.
  *
  * Story #5312 deleted the fan-out probe that lived here: the delete
  * blast-radius count never refused a real plan, and the `git grep` it paid
@@ -24,6 +25,7 @@
 import { gitSpawn } from '../../git-utils.js';
 import { validateTaskBodies } from '../task-body-validator.js';
 import { validateAndNormalizeTickets } from '../ticket-validator.js';
+import { normalizeAcceptanceHandles } from './acceptance-handle-repair.js';
 import { repairChangeEntries } from './changes-repair.js';
 
 /**
@@ -167,13 +169,16 @@ function defineHidden(validated, extras) {
 export function validateTickets(tickets, config, opts = {}) {
   const baseBranch = resolveBaseBranchRef(config);
   const baseBranchRef = resolveProbeRef({ baseBranch, cwd: opts.cwd });
-  const repairs = repairChangeEntries(tickets, {
-    existsAtBase: makeExistsAtBase({
-      baseBranchRef,
-      cwd: opts.cwd,
-      gitRunner: opts.gitRunner,
+  const repairs = [
+    ...normalizeAcceptanceHandles(tickets),
+    ...repairChangeEntries(tickets, {
+      existsAtBase: makeExistsAtBase({
+        baseBranchRef,
+        cwd: opts.cwd,
+        gitRunner: opts.gitRunner,
+      }),
     }),
-  });
+  ];
   const validated = validateAndNormalizeTickets(tickets, {
     baseBranchRef: baseBranchRef ?? undefined,
     gitRunner: opts.gitRunner,

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

@@ -7,7 +7,7 @@
  *
  *   1. `changes[]` repair + ticket validator + file-assumption + DAG
  *   2. Draft reachability (named soft failure, exit 3)
- *   3. Split-policy partition (`assertAcceptancePartition`) + spec fold
+ *   3. Same-wave collision refusal (`assertNoWaveCollisions`) + spec fold
  *   4. Create Story issues (`type::story` + sanitized authored labels —
  *      deliberately NOT `agent::ready`), resumably via a plan fingerprint
  *   5. Upsert `story-plan-state` on every created Story; upsert `plan-summary`
@@ -62,8 +62,8 @@ import {
   conflictFindingKey,
 } from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
+import { renderRepair } from './acceptance-handle-repair.js';
 import { recordAuditFilings, withAuditLabels } from './audit-provenance.js';
-import { renderChangeRepair } from './changes-repair.js';
 import {
   resolveContainerEpic,
   resolveCrossPlanLinks,
@@ -81,7 +81,7 @@ import {
   PLAN_SUMMARY_COMMENT_TYPE,
 } from './summary.js';
 import { closeSupersededTickets } from './supersede-ops.js';
-import { predictWaveSerialisation } from './wave-serialisation.js';
+import { assertNoWaveCollisions } from './wave-collision-gate.js';
 
 /** Checkpoint schema version written on each Story's story-plan-state. */
 const PLAN_CHECKPOINT_SCHEMA_VERSION_V2 = 2;
@@ -146,7 +146,7 @@ function enforceTicketValidation(validated) {
     );
   }
   const warnings = [
-    ...(validated.repairs ?? []).map((repair) => renderChangeRepair(repair)),
+    ...(validated.repairs ?? []).map(renderRepair),
     ...(validated.warnings ?? []),
   ];
   return {
@@ -170,18 +170,28 @@ function freshnessCounts(probeRef, warnings) {
   return { stale: warnings.length, ambiguous: 0 };
 }
 
+/** How each text-hygiene finding kind names itself on the warning list. */
+const TEXT_HYGIENE_LABELS = {
+  'open-question': 'open question in body',
+  'pinned-identifier': 'pinned identifier in acceptance[]',
+};
+
 /**
- * The `open-question` lint over the draft bodies (Story #5312) — an
+ * The advisory text-hygiene lints over the draft (Story #5312, #5323) — an
  * operator-directed question persisted into a Story a non-interactive
- * sub-agent executes. A warning the dry-run lists, never a refusal.
+ * sub-agent executes, and an acceptance item pinning an internal symbol the
+ * advisory `changes[]` may reshape. Warnings the dry-run lists, never
+ * refusals.
  *
  * @param {object[]} rawStories
  * @returns {string[]}
  */
-function collectOpenQuestionWarnings(rawStories) {
+function collectTextHygieneWarnings(rawStories) {
   return evaluateTextHygiene({ draftStories: rawStories }).findings.map(
     (finding) =>
-      `Story "${finding.slug}": open question in body — "${finding.evidence}". ${finding.message}`,
+      `Story "${finding.slug}": ${
+        TEXT_HYGIENE_LABELS[finding.kind] ?? finding.kind
+      } — "${finding.evidence}". ${finding.message}`,
   );
 }
 
@@ -533,7 +543,6 @@ function logPersistEpilogue({
  *   artifacts: {
  *     stories: Array<object>,
  *     techSpecContent?: string|null,
- *     planAcceptance?: string[]|null,
  *     planContextEnvelope?: object|null,
  *   },
  *   config?: object,
@@ -559,7 +568,6 @@ export async function runPlanPersist({
   const {
     stories: rawStories = null,
     techSpecContent = null,
-    planAcceptance = null,
     planContextEnvelope = null,
   } = artifacts ?? {};
   const {
@@ -595,7 +603,7 @@ export async function runPlanPersist({
     enforceTicketValidation(validated);
   const warnings = [
     ...validationWarnings,
-    ...collectOpenQuestionWarnings(rawStories),
+    ...collectTextHygieneWarnings(rawStories),
   ];
   logWarnings(warnings);
 
@@ -613,11 +621,10 @@ export async function runPlanPersist({
     epicId: opts.adoptEpicId ?? null,
   });
 
-  // Split policy + inline Spec fold (Specs stay inline, never under docs/).
+  // Inline Spec fold (Specs stay inline, never under docs/).
   const seedContent = planContextEnvelope?.seed?.content ?? '';
   const { stories: assembled } = assemblePlanStories(rawStories, {
     sharedSpec: techSpecContent,
-    planAcceptance: planAcceptance ?? undefined,
     sourceTicketIds,
     // The seed this plan was authored from: an audit sweep's Single-plan seed
     // carries the `audit-fingerprints` / `audit-semantic-keys` footers, and
@@ -644,6 +651,31 @@ export async function runPlanPersist({
     rawFindings: validated.findings,
   });
 
+  // Story #5332 — the split gate, ahead of the first create. `buildWaveTable`
+  // needs only `{slug, title, depends_on}` and the prediction needs only the
+  // assembled bodies, so both can run before anything is written; they used
+  // to sit *after* creation, which is why the collision table could only ever
+  // be a receipt for a plan already live. The same computed value is handed
+  // to the summary rendering below rather than recomputed, so the refusal and
+  // the receipt can never disagree.
+  const waveTable = buildWaveTable(
+    stories.map((s) => ({
+      slug: s.slug,
+      title: s.title,
+      depends_on: s.depends_on,
+    })),
+  );
+
+  // Story #5265: the table says which Stories share an order; the dispatcher
+  // decides which of those actually run together. Run its own predicate over
+  // the assembled bodies — the exact artifact the tick will read back off
+  // GitHub — so an N>1 draft it would serialize is refused here, and the
+  // summary comment names the serialisation instead of promising parallelism
+  // the next tick refuses. One enumeration feeds both.
+  const waveCollisions = assertNoWaveCollisions(waveTable, stories, {
+    tempRoot: getPaths(config).tempRoot,
+  });
+
   const { created, planRunLabel, planRunLabelApplied } =
     await createStoryIssues({
       provider,
@@ -656,24 +688,6 @@ export async function runPlanPersist({
   recordAuditFilings({ stories, created, tickets: rawStories, dryRun });
 
   const primary = created[0];
-  const waveTable = buildWaveTable(
-    stories.map((s) => ({
-      slug: s.slug,
-      title: s.title,
-      depends_on: s.depends_on,
-    })),
-  );
-
-  // Story #5265: the table says which Stories share an order; the dispatcher
-  // decides which of those actually run together, and it decides on the
-  // evidence-widened footprint. Run its own predicate over the assembled
-  // bodies — the exact artifact the tick will read back off GitHub — so the
-  // comment names the serialisation instead of promising parallelism the
-  // next tick refuses. `tempRoot` is threaded for the same reason the tick
-  // threads it: the scrape must ignore this project's scratch root.
-  const waveCollisions = predictWaveSerialisation(waveTable, stories, {
-    tempRoot: getPaths(config).tempRoot,
-  });
 
   // Story #4541: `readPlanMetrics` is declared `(epicId, config)` but was
   // called with `config` first, so the ledger path resolver received the

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

@@ -4,7 +4,7 @@
  * Under the Story collapse (`docs/roadmap.md` § Stage 3), `/mandrel-plan` persists
  * zero-or-more Story issues directly — no Epic parent, no reconciler tree,
  * no `deliveryShape` mode matrix. Default is **one Story**; N>1 is gated by
- * the Stage-1 split-policy validator (`assertAcceptancePartition`).
+ * the supersede partition check.
  *
  * Each Story body is the single executable document: Tech Spec stays inline
  * under `## Spec`, at whatever length the work needs (Story #5312 deleted
@@ -34,7 +34,6 @@ import {
   concurrentMap,
   FANOUT_CONCURRENCY,
 } from '../../util/concurrent-map.js';
-import { assertAcceptancePartition } from '../split-policy-validator.js';
 import {
   externalDependencyId,
   isExternalDependencyRef,
@@ -514,15 +513,18 @@ function assertSharedSpecAllowed(tickets, sharedSpec) {
 
 /**
  * Assemble markdown bodies for every Story: normalize → fold spec →
- * assertAcceptancePartition → assertSupersedePartition → serialize.
+ * assertSupersedePartition → serialize.
  *
- * Both partition checks run **before** any GitHub write so a mis-authored
- * plan never leaves Stories live against an inconsistent tracker.
+ * The partition check runs **before** any GitHub write so a mis-authored
+ * plan never leaves Stories live against an inconsistent tracker. Story #5332
+ * retired the acceptance partition that used to run beside it: it refused
+ * only byte-identical acceptance text across siblings, and the split gate is
+ * now `assertNoWaveCollisions` in `run-plan-persist.js`, ahead of the first
+ * create.
  *
  * @param {object[]} tickets
  * @param {object} [opts]
  * @param {string|null} [opts.sharedSpec]
- * @param {string[]} [opts.planAcceptance]
  * @param {number[]} [opts.sourceTicketIds] Ids passed to `/mandrel-plan --tickets`.
  * @returns {{ stories: Array<{ slug: string, title: string, body: string, acceptance: string[], depends_on: string[], supersedes: Array<{ id: number, note: string|null }> }> }}
  */
@@ -539,9 +541,6 @@ export function assemblePlanStories(tickets, opts = {}) {
     (ticket) => assembleOnePlanStory(ticket, opts).story,
   );
 
-  assertAcceptancePartition(stories, {
-    planAcceptance: opts.planAcceptance,
-  });
   assertSupersedePartition(stories, opts.sourceTicketIds ?? []);
 
   return { stories };

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

@@ -16,7 +16,7 @@
  * Two halves, deliberately separated by the `createIssue` boundary:
  *
  *   1. **`assertSupersedePartition`** — a plan-time, fail-closed check that
- *      runs *before* any GitHub write. Mirrors `assertAcceptancePartition`:
+ *      runs *before* any GitHub write. Same fail-closed shape as the
  *      every id passed to `--tickets` must be claimed by exactly one Story,
  *      and no Story may claim an id that was not a source ticket. A partial
  *      supersede map is a planning error, not something to paper over at

package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js

@@ -0,0 +1,107 @@
+/**
+ * wave-collision-gate.js — the split gate (Story #5332).
+ *
+ * Kept out of `wave-serialisation.js` because it answers a different
+ * question. That module *predicts* what the dispatcher will do with a draft
+ * and renders the prediction as a receipt; this one decides whether the draft
+ * may be created at all, and so owns both the one enumeration the refusal and
+ * the receipt share and the shape reconciliation that enumeration needs.
+ *
+ * @module lib/orchestration/plan-persist/wave-collision-gate
+ */
+
+import { predictWaveSerialisation } from './wave-serialisation.js';
+
+/**
+ * Expose an assembled Story's declared footprint where `storyFootprint`
+ * looks for it.
+ *
+ * `assemblePlanStories` returns the persisted artifact — `{ slug, title,
+ * body, bodyObject, acceptance, depends_on, … }` — and carries the parsed
+ * `changes[]` inside `bodyObject`, not at the top level. `storyFootprint`
+ * reads `files` / `changes` / `changeset` only, so from Story #5313 (which
+ * retired the body scrape that had been widening the footprint out of the
+ * markdown) until this Story the production call saw an empty footprint for
+ * every assembled Story and predicted nothing — the unit fixtures passed a
+ * top-level `changes` and so could not show it. The prediction is now the
+ * split gate, and a gate that cannot see a declaration cannot fire, so the
+ * shapes are reconciled here rather than by widening the dispatcher's own
+ * predicate: the runtime's records (`resolve-stories.js`) already carry
+ * `changes` at the top level and pass through untouched.
+ *
+ * @param {object} story
+ * @returns {object} The same record, with a top-level `changes` when one can
+ *   be resolved from its `bodyObject`.
+ */
+function withDeclaredFootprint(story) {
+  if (!story || typeof story !== 'object') return story;
+  const declared = [story.files, story.changes, story.changeset].some(
+    (shape) => Array.isArray(shape) && shape.length > 0,
+  );
+  if (declared) return story;
+  const fromBody = story.bodyObject?.changes;
+  return Array.isArray(fromBody) ? { ...story, changes: fromBody } : story;
+}
+
+/**
+ * Render one refused pair as a report line.
+ *
+ * @param {{ wave: number, slugs: [string, string], paths: string[], source: string }} collision
+ * @returns {string}
+ */
+function formatCollision({ wave, slugs, paths, source }) {
+  const declared = paths.map((p) => `\`${p}\``).join(', ');
+  return `  - wave ${wave}: "${slugs[0]}" + "${slugs[1]}" both declare ${declared} (${source})`;
+}
+
+/**
+ * Compute the same-wave collisions of a draft and refuse an N>1 draft that
+ * has any — the split gate.
+ *
+ * ADR `20260912-5312` deleted every numeric plan-time ceiling and left the
+ * default-single policy enforced by prose plus `assertAcceptancePartition`,
+ * which refused only byte-identical acceptance text across siblings — a shape
+ * model output does not produce. The measured result was a plan of 18 Stories
+ * whose own summary comment recorded 39 shared files across 14 same-wave
+ * Stories: the plan refuted its own parallelism claim, after persist, with
+ * nothing acting on it.
+ *
+ * So the gate is the dispatcher's own predicate rather than a proxy for it. A
+ * pair {@link predictWaveSerialisation} names is a pair
+ * `stories-wave-tick.js` will refuse to co-dispatch, so the split buys no
+ * parallelism while still paying a delivery session per Story. Two remedies,
+ * both the author's to take before anything is created: merge the pair into
+ * the one Story it already is, or order it with `depends_on` so the members
+ * land in different waves.
+ *
+ * **N=1 can never trip it.** A single-Story draft has no pair to score, so
+ * the prediction is empty by construction.
+ *
+ * The computed collisions are **returned** so the caller hands the same value
+ * to the plan-summary receipt instead of recomputing it — a recomputation is
+ * how the refusal and the receipt would come to disagree.
+ *
+ * @param {ReturnType<typeof import('./summary.js').buildWaveTable>} waveTable
+ * @param {Array<object>} stories The assembled Stories, in draft order.
+ * @param {{ tempRoot?: string }} [options] Threaded to the predicate.
+ * @returns {ReturnType<typeof predictWaveSerialisation>}
+ * @throws {Error} When an N>1 draft has at least one colliding same-wave pair.
+ */
+export function assertNoWaveCollisions(waveTable, stories, options = {}) {
+  const list = Array.isArray(stories) ? stories : [];
+  const collisions = predictWaveSerialisation(
+    waveTable,
+    list.map(withDeclaredFootprint),
+    options,
+  );
+  if (list.length <= 1 || collisions.length === 0) return collisions;
+  throw new Error(
+    `[plan-persist] ${collisions.length} same-wave collision(s) — the ` +
+      'dispatcher will refuse to co-dispatch these pairs, so the split buys ' +
+      'no parallelism and costs a delivery session per Story:\n' +
+      `${collisions.map(formatCollision).join('\n')}\n` +
+      'Remedy: merge each pair into the one Story it already is (its stages ' +
+      'belong in `## Slicing`), or order the pair with `depends_on` so the ' +
+      'members sit in different waves.',
+  );
+}