mandrel 2.24.0 → 2.25.0

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -113,9 +113,9 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
-If you do write those sections into the \`body\` string anyway, they must mirror the top-level arrays **item for item** — persist fails closed on a disagreement rather than guessing which list is authoritative. Do **not** invent a second criteria list inside \`## Spec\`, and do not author a separate Acceptance Spec / PRD artifact.
+Never hand-mirror either list into the \`body\` — there is no step that asks you to. Persist fails closed on a body section that disagrees with its top-level array rather than guessing which list is authoritative, so writing one anyway only adds a way to be wrong. Do **not** invent a second criteria list inside \`## Spec\`, and do not author a separate Acceptance Spec / PRD artifact.
 
-The serialized \`body\` string renders these markdown sections (in order):
+The **persisted** \`body\` renders these markdown sections (in order) — you author every one of them except \`## Acceptance\` / \`## Verify\`, which persist synthesizes from the top-level arrays:
 
     ## Goal
     <one sentence — why this Story exists>
@@ -130,11 +130,11 @@ The serialized \`body\` string renders these markdown sections (in order):
     - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
     - ...
 
-    ## Acceptance
+    ## Acceptance          <-- synthesized by persist from acceptance[]; do not author
     - [ ] <testable, observable criterion>
     - ...
 
-    ## Verify
+    ## Verify              <-- synthesized by persist from verify[]; do not author
     - <exact command or test path> (<tier>)
     - ...
 

package/.agents/scripts/lib/ticket-body-sections.js

@@ -235,7 +235,7 @@ export function sliceTicketBodyForDelivery(body) {
   //    survive verbatim.
   const techLoc = locate(working, 'techSpec');
   let techRegion = null;
-  const PLACEHOLDER = 'MANDREL_TECH_SPEC_PLACEHOLDER';
+  const PLACEHOLDER = '\u0000MANDREL_TECH_SPEC_PLACEHOLDER\u0000';
   if (techLoc) {
     const { end } = descriptor('techSpec');
     techRegion = working.slice(techLoc.startIdx, techLoc.endIdx + end.length);

package/.agents/scripts/lib/util/poll-loop.js

@@ -13,6 +13,13 @@
  * `sleep` is exported as the cancellable delay primitive used internally;
  * callers that already have their own cadence (e.g. a continuous ticker)
  * can import it directly.
+ *
+ * `sleepFn` is the inter-tick delay seam (Story #4873). A caller that already
+ * owns a delay seam of its own — the close-and-land merge wait, whose suite
+ * must never actually sleep out a 30s poll interval — passes it here so
+ * adopting this primitive does not cost it that seam. It is called as
+ * `sleepFn(intervalMs, signal)`; a one-argument stub simply ignores the
+ * signal, and the default is the cancellable {@link sleep} below.
  */
 
 /**
@@ -23,11 +30,20 @@
  *   timeoutMs?: number,
  *   signal?: AbortSignal,
  *   logger?: { warn?: Function },
+ *   sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>,
  * }} opts
  * @returns {Promise<any | undefined>}
  */
 export async function pollUntil(opts) {
-  const { fn, predicate, intervalMs, timeoutMs, signal, logger } = opts;
+  const {
+    fn,
+    predicate,
+    intervalMs,
+    timeoutMs,
+    signal,
+    logger,
+    sleepFn = sleep,
+  } = opts;
   if (typeof fn !== 'function') throw new TypeError('pollUntil: fn required');
   if (typeof predicate !== 'function') {
     throw new TypeError('pollUntil: predicate required');
@@ -52,7 +68,7 @@ export async function pollUntil(opts) {
     if (deadline !== null && Date.now() >= deadline) {
       throw new Error(`pollUntil: timed out after ${timeoutMs}ms`);
     }
-    await sleep(intervalMs, signal);
+    await sleepFn(intervalMs, signal);
   }
   return undefined;
 }

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -246,7 +246,7 @@ export function createProbeContext({
  * caller tracked in-flight itself; probe mode must put them back.
  *
  * @returns {Promise<{
- *   nodes: Array<{id: number, dependsOn: number[], files: string[], labels: string[]}>,
+ *   nodes: Array<{id: number, dependsOn: number[], files: string[], body: string, labels: string[]}>,
  *   doneIds: Set<number>,
  *   inFlight: number,
  *   blockedIds: number[],
@@ -282,6 +282,11 @@ export async function probeLiveState({
   });
 
   const labelsById = new Map(stories.map((s) => [s.id, s.labels ?? []]));
+  // Bodies ride along with the node so the co-dispatch guard can widen a
+  // declared footprint from the paths a Story's own text names (Story #4875).
+  // They are consumed in-process by `selectReadySet` and never serialized into
+  // the beat envelope, which stays a list of ids.
+  const bodyById = new Map(stories.map((s) => [s.id, s.body ?? '']));
   const inFlightIds = deriveInFlightIds(stories, dispatched);
   // A Story another operator's lease holds occupies a (global) dispatch slot
   // just like an in-flight one: fold it into the in-flight set so it is both
@@ -292,6 +297,7 @@ export async function probeLiveState({
   return {
     nodes: envelope.dag.map((node) => ({
       ...node,
+      body: bodyById.get(node.id) ?? '',
       labels: projectInFlightLabels(
         labelsById.get(node.id) ?? [],
         inFlightIds.has(node.id),

package/.agents/scripts/lib/wave-runner/ready-set.js

@@ -26,10 +26,14 @@
  *     (`agent::done` OR closed issue) so a Story closed manually through
  *     the GitHub UI is recognised as done.
  *   - `storiesOverlap(a, b)` — the file-overlap co-dispatch guard: true
- *     when two Stories' declared file footprints intersect. Two Stories
- *     that would touch the same file MUST NOT be dispatched onto parallel
+ *     when two Stories' file footprints intersect. Two Stories that would
+ *     touch the same file MUST NOT be dispatched onto parallel
  *     `story-<id>` branches in the same beat (they would race the same
- *     path and produce a merge conflict at close).
+ *     path and produce a merge conflict at close). The comparison runs over
+ *     the **widened** footprint (`storyWidenedFootprint`) — a declared
+ *     `changes[]` is treated as a lower bound and widened from the paths the
+ *     Story's own text names, because a guard that trusts a prediction cannot
+ *     prevent the collision nobody predicted (Story #4875).
  *   - `selectReadySet({ stories, doneIds, inFlight, globalCap })` — the
  *     scheduler. Returns the deterministic, overlap-free set of ready
  *     Stories, capped at `globalCap − inFlight`.
@@ -168,6 +172,59 @@ function isGlobPath(path) {
   return path.includes('*') || path.includes('?') || path.includes('{');
 }
 
+/**
+ * Repo-relative file paths as they appear in Story prose: at least one `/`
+ * separator and a short file extension. Deliberately narrow — a token has to
+ * look like a real path before it can widen a footprint and withhold a Story.
+ */
+const PROSE_PATH_RE = /(?:[\w.@~-]+\/)+[\w.@-]+\.[A-Za-z0-9]{1,6}/g;
+
+/**
+ * Scrape file paths a Story's **text** mentions but its `changes[]` never
+ * declared (Story #4875).
+ *
+ * The declared footprint is a planner's *prediction*, and it is systematically
+ * a lower bound: a Story's `## Spec` names the module it must also touch, its
+ * acceptance criteria name the caller that must be updated, and none of that
+ * reaches `changes[]`. The overlap guard exists to stop two Stories racing the
+ * same file, so trusting the declaration outright means the guard is blind to
+ * precisely the collisions nobody predicted.
+ *
+ * Evidence is only ever **added** — nothing here can shrink a declared
+ * footprint, so widening can withhold a Story for a beat but can never
+ * co-dispatch one the declared comparison would have caught.
+ *
+ * @param {StoryRecord} story
+ * @returns {Set<string>}
+ */
+function storyEvidencePaths(story) {
+  const out = new Set();
+  for (const field of [story?.title, story?.body, story?.spec]) {
+    if (typeof field !== 'string' || field === '') continue;
+    for (const match of field.matchAll(PROSE_PATH_RE)) {
+      const trimmed = match[0].trim();
+      if (trimmed) out.add(trimmed);
+    }
+  }
+  return out;
+}
+
+/**
+ * A Story's footprint **widened from observable evidence** — the set the
+ * co-dispatch guard actually compares (Story #4875).
+ *
+ * `declared ∪ scraped-from-prose`. See {@link storyEvidencePaths} for why the
+ * declaration is treated as a lower bound rather than the answer.
+ *
+ * @param {StoryRecord} story
+ * @returns {Set<string>}
+ */
+function storyWidenedFootprint(story) {
+  const out = storyFootprint(story);
+  for (const path of storyEvidencePaths(story)) out.add(path);
+  return out;
+}
+
 /**
  * File-overlap co-dispatch guard. Returns `true` when two Stories' declared
  * file footprints intersect — meaning they would race the same file if
@@ -175,12 +232,19 @@ function isGlobPath(path) {
  * Stories that overlap MUST NOT both appear in one dispatch set; one is
  * withheld until the other clears.
  *
+ * Comparison runs over the **widened** footprint
+ * ({@link storyWidenedFootprint}), not the declaration: a declared `changes[]`
+ * is a lower bound on what a Story will touch, and two Stories whose real edits
+ * collide were being co-dispatched whenever the collision was not predicted
+ * (Story #4875).
+ *
  * Two deliberate asymmetries:
  *
- *   - **An empty footprint means "no known overlap"** → `false`. A Story that
- *     declares no files is never withheld. This is permissive by necessity:
- *     an undeclared footprint carries no information, and withholding on
- *     absence would serialize every run.
+ *   - **An empty footprint means "no known overlap"** → `false`. A Story with
+ *     no declared footprint and no path evidence in its text is never
+ *     withheld. This is permissive by necessity: a genuinely unknown footprint
+ *     carries no information, and withholding on absence would serialize every
+ *     run.
  *   - **A glob footprint overlaps EVERYTHING** → `true` (Story #4539/#4540).
  *     Comparison is exact-string, so a Story declaring
  *     `.agents/scripts/lib/**` would not match another declaring
@@ -193,9 +257,9 @@ function isGlobPath(path) {
  * @returns {boolean}
  */
 export function storiesOverlap(a, b) {
-  const fa = storyFootprint(a);
+  const fa = storyWidenedFootprint(a);
   if (fa.size === 0) return false;
-  const fb = storyFootprint(b);
+  const fb = storyWidenedFootprint(b);
   if (fb.size === 0) return false;
   for (const path of fa) {
     if (isGlobPath(path)) return true;

package/.agents/scripts/lib/workers/combined-mi-crap-worker.js

@@ -24,7 +24,7 @@
  *
  * Message contract — see lib/cpu-pool.js:
  *   IN  : { item: { abs: string, relPath: string, requireCoverage: boolean,
- *                   coverageEntry: object | null } }
+ *                   coverageAvailable?: boolean, coverageEntry: object | null } }
  *         { exit: true }
  *   OUT : { ok: true, result: {
  *           relPath,
@@ -88,7 +88,7 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
       },
     };
   }
-  const { abs, relPath, requireCoverage } = item;
+  const { abs, relPath, requireCoverage, coverageAvailable = true } = item;
   const prepare = deps.prepare ?? prepareSourceForScoring;
   const analyze = deps.analyze ?? analyzeOnce;
 
@@ -150,7 +150,10 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
   }
 
   const { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods } =
-    finalizeMethodRows(rawCrapRows, { requireCoverage });
+    finalizeMethodRows(rawCrapRows, {
+      requireCoverage,
+      coverageAvailable,
+    });
   return reply({
     miScore,
     crapRows: rows,

package/.agents/scripts/lib/workers/crap-worker.js

@@ -11,7 +11,7 @@
  *
  * Message contract — see lib/cpu-pool.js:
  *   IN  : { item: { abs: string, relPath: string, requireCoverage: boolean,
- *                   coverageEntry: object | null } }
+ *                   coverageAvailable?: boolean, coverageEntry: object | null } }
  *         { exit: true }
  *   OUT : { ok: true, result: {
  *           relPath,
@@ -80,7 +80,7 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
       },
     };
   }
-  const { abs, relPath, requireCoverage } = item;
+  const { abs, relPath, requireCoverage, coverageAvailable = true } = item;
 
   // Coverage entry is pre-resolved on the host and attached to the item.
   // `item.coverageEntry` may be explicitly `null` when the file has no
@@ -143,7 +143,10 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
     );
   }
 
-  const finalized = finalizeMethodRows(methodRows, { requireCoverage });
+  const finalized = finalizeMethodRows(methodRows, {
+    requireCoverage,
+    coverageAvailable,
+  });
   return {
     kind: 'reply',
     message: {