mandrel 2.58.0 → 2.60.0

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

@@ -15,12 +15,12 @@
  *
  * Two halves, deliberately separated by the `createIssue` boundary:
  *
- *   1. **`assertSupersedePartition`** — a plan-time, fail-closed check that
- *      runs *before* any GitHub write. Mirrors `assertAcceptancePartition`:
- *      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
- *      write time.
+ *   1. **`resolveSupersedePartition`** — the plan-time completion pass that
+ *      runs *before* any GitHub write. No id may be claimed by two Stories
+ *      and no Story may claim an id that was not a source ticket — both fail
+ *      closed. A source id nobody claimed is assigned to the primary Story
+ *      with a warning (Story #5342): the plan is replacing it either way, so
+ *      the only open question was bookkeeping.
  *   2. **`closeSupersededTickets`** — the bookkeeping pass that runs *after*
  *      the Stories exist. It **never throws**: a throw here would leave the
  *      run half-done with Stories already live. An already-closed, deleted,
@@ -279,18 +279,12 @@ function describeStoryIds(entries) {
 }
 
 /**
- * Fail closed on a partial supersede map.
+ * Index which Story claims each source id.
  *
- * Runs **before** `createIssue` so a mis-authored map never leaves Stories
- * live against an inconsistent tracker.
- *
- * @param {Array<{ slug: string, supersedes: Array<{ id: number }> }>} stories
- * @param {number[]} sourceTicketIds Ids passed to `/mandrel-plan --tickets`.
+ * @param {Array<{ slug: string, supersedes?: Array<{ id: number }> }>} list
+ * @returns {Map<number, string[]>} id → claiming slugs, in draft order.
  */
-export function assertSupersedePartition(stories, sourceTicketIds = []) {
-  const list = Array.isArray(stories) ? stories : [];
-  const sources = new Set(sourceTicketIds);
-
+function indexSupersedeClaims(list) {
   /** @type {Map<number, string[]>} */
   const claims = new Map();
   for (const story of list) {
@@ -300,9 +294,47 @@ export function assertSupersedePartition(stories, sourceTicketIds = []) {
       claims.set(id, owners);
     }
   }
+  return claims;
+}
 
-  const errors = [];
+/**
+ * Complete the supersede map, refusing only what the plan gets wrong.
+ *
+ * Two halves, split by who can be right (Story #5342):
+ *
+ *   - **Refused.** A Story claiming an id that was never a source ticket, and
+ *     two Stories claiming the same id. Both name an intent the run cannot
+ *     act on — the first would comment on and close an issue nobody asked
+ *     about, the second cannot say which Story replaced it — so they fail
+ *     closed, **before** `createIssue`, and no Story goes live against an
+ *     inconsistent tracker.
+ *   - **Assigned with a warning.** A source id no Story claimed. Every id
+ *     passed to `--tickets` is being replaced by this plan by construction;
+ *     which Story records it is a bookkeeping detail, and the primary Story
+ *     is the answer the operator would have given. Refusing cost a whole
+ *     re-author round to type back a fact the run already knew.
+ *
+ * Mutates the unclaimed ids onto the primary Story's `supersedes[]`.
+ *
+ * **`stories[0]` is the primary, and it is the *only* derivation of it**
+ * (Story #5361): `assemblePlanStories` hands this list over already sorted by
+ * `orderStoriesByDependencies`, which is the same order the create loop files
+ * the Stories in — so the `superseded-by` comment this assignment produces
+ * can never name a different Story from the checkpoint and the plan summary.
+ * A non-empty list is the caller's contract (assembly refuses an empty
+ * draft before it gets here).
+ *
+ * @param {Array<{ slug: string, supersedes: Array<{ id: number, note: string|null }> }>} stories
+ *   Dependency-ordered and non-empty.
+ * @param {number[]} sourceTicketIds Ids passed to `/mandrel-plan --tickets`.
+ * @returns {string[]} One warning per id assigned by default.
+ */
+export function resolveSupersedePartition(stories, sourceTicketIds = []) {
+  const list = Array.isArray(stories) ? stories : [];
+  const sources = new Set(sourceTicketIds);
+  const claims = indexSupersedeClaims(list);
 
+  const errors = [];
   for (const [id, owners] of claims) {
     if (owners.length > 1) {
       errors.push(
@@ -317,23 +349,25 @@ export function assertSupersedePartition(stories, sourceTicketIds = []) {
       );
     }
   }
-
-  for (const id of sources) {
-    if (!claims.has(id)) {
-      errors.push(
-        `source ticket #${id} is not claimed by any Story's supersedes[] — ` +
-          'a partial supersede map is a planning error. Claim it, or drop it ' +
-          'from --tickets.',
-      );
-    }
-  }
-
   if (errors.length > 0) {
     throw new Error(
       `[plan-persist] supersede partition failed with ${errors.length} ` +
         `error(s):\n${errors.map((e) => `  - ${e}`).join('\n')}`,
     );
   }
+
+  const primary = list[0];
+  const warnings = [];
+  for (const id of sources) {
+    if (claims.has(id)) continue;
+    primary.supersedes = [...(primary.supersedes ?? []), { id, note: null }];
+    warnings.push(
+      `source ticket #${id} was claimed by no Story's supersedes[] — ` +
+        `assigned to the primary Story "${primary.slug}". Author the claim ` +
+        'explicitly if another Story is the one that replaces it.',
+    );
+  }
+  return warnings;
 }
 
 /**
@@ -567,7 +601,7 @@ export async function closeSupersededTickets({
       });
     },
     // The per-source-ticket close (Story #4952) fans out across **distinct**
-    // tickets — `assertSupersedePartition` has already failed the run closed
+    // tickets — `resolveSupersedePartition` has already failed the run closed
     // if two Stories claim the same id, so no two units in flight can touch
     // the same issue. Within one unit the probe → comment → close sequence
     // stays strictly ordered: commenting on an issue the probe reported

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.',
+  );
+}

package/.agents/scripts/lib/orchestration/review-depth.js

@@ -75,19 +75,22 @@ export const DEFAULT_DIFF_WIDTH = Object.freeze({
  * `audit-rules.json`?
  *
  * This is the **single source** of the derived level — the review depth
- * ({@link resolveDepth}), the acceptance-critic fresh-vs-inline routing
- * (`ceremony-routing.js#resolveCeremonyForRisk`), and the dispatch-side
- * complexity routing (`complexity-gate.js#deriveStoryShape`, Story #4722)
- * all consume what this returns, so no ceremony decision can disagree about
- * how risky a change is. Dispatch reads the **predicted** shape (the Story's
- * declared `changes[]` footprint) and close reads the **actual** diff — one
- * taxonomy, two read points, which is what keeps a lite-shaped Story whose
- * footprint touches a sensitive path on the full route with its fresh critic.
+ * ({@link resolveDepth}) and the dispatch-side complexity routing
+ * (`complexity-gate.js#deriveStoryShape`, Story #4722) both consume what this
+ * returns, so no risk decision can disagree about how risky a change is.
+ * Dispatch reads the **predicted** shape (the Story's declared `changes[]`
+ * footprint) and close reads the **actual** diff — one taxonomy, two read
+ * points, which is what keeps a lite-shaped Story whose footprint touches a
+ * sensitive path on the full route and under a deep review.
+ *
+ * The acceptance verdict owner is **not** downstream of this level: Story
+ * #5343 re-based `ceremony-routing.js#resolveCeremonyForRisk` on the ceremony
+ * profile alone, and Story #5366 removed the level from its signature.
  *
  * Returns `null` — the fail-safe "no derivable signal" level — when the change
- * set is empty/unknown or the manifest cannot be read. Both downstream
- * consumers treat `null` as the more thorough posture (`standard` depth, a
- * `fresh` critic), so a derivation failure never buys a change less checking.
+ * set is empty/unknown or the manifest cannot be read. Both consumers treat
+ * `null` as the more thorough posture (`standard` depth, the conservative
+ * `full` route), so a derivation failure never buys a change less checking.
  *
  * Total: never throws.
  *