mandrel 2.32.0 → 2.34.0

package/.agents/scripts/lib/story-body/footer-block.js

@@ -0,0 +1,97 @@
+/**
+ * footer-block.js — the Story body's `---` footer grammar.
+ *
+ * A Story body is prose an operator edits. Its **declared dependency edges**
+ * are not: they live in a footer block, in one exact line shape, and that
+ * distinction is the whole safety property. An unanchored whole-body scan
+ * (what `parseBlockedBy` used to be) turned any sentence that merely mentioned
+ * a blocker into a real dispatch gate — an example, a changelog note, an
+ * acceptance criterion quoting the phrase — and withheld the Story until an
+ * unrelated issue closed.
+ *
+ * This module is the single home for that grammar. Both readers go through it:
+ * `lib/story-body/story-body.js` (what a body round-trips as `depends_on`) and
+ * `lib/dependency-parser.js` (what gates dispatch). Sharing one implementation
+ * is what keeps them from drifting apart into two different answers about the
+ * same body.
+ *
+ * @module lib/story-body/footer-block
+ */
+
+/**
+ * The one line shape that declares a dependency edge: `blocked by #N` alone on
+ * its own line inside the footer block. Anchored at both ends deliberately —
+ * `depends on #N`, `Blocked by: #N`, and `blocked by #N once X lands` all
+ * declare nothing.
+ */
+const FOOTER_BLOCKED_BY_LINE_RE = /^blocked by\s+(#\d+)$/i;
+
+/** A `---` rule on its own line. */
+const FOOTER_RULE_RE = /^---\s*$/;
+
+/** Footer keys that qualify a bare `---` rule as the footer separator. */
+const FOOTER_KEY_RE = /^(parent:|Epic:|blocked by)/im;
+
+/**
+ * True when line `index` opens the footer block: a `---` on its own line whose
+ * remaining lines start with a recognised footer key (`parent:`, `Epic:`,
+ * `blocked by`). A `---` opening a thematic break or a table mid-body is
+ * therefore not mistaken for the footer.
+ *
+ * @param {string} line
+ * @param {string[]} lines
+ * @param {number} index
+ * @returns {boolean}
+ */
+export function isFooterSeparator(line, lines, index) {
+  if (!FOOTER_RULE_RE.test(line)) return false;
+  return FOOTER_KEY_RE.test(lines.slice(index + 1).join('\n'));
+}
+
+/**
+ * Return the footer block of a body — everything after the footer separator —
+ * or `''` when the body carries no footer.
+ *
+ * Module-private: `parseFooterBlockedByIds` is its only caller. The body
+ * parser splits its own sections and reaches for `parseFooterBlockedByRefs`
+ * with the footer it already has, so exporting this would ship a symbol with
+ * no consumer.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+function extractFooterBlock(body) {
+  if (!body) return '';
+  const lines = String(body).split('\n');
+  const start = lines.findIndex((line, i) => isFooterSeparator(line, lines, i));
+  return start === -1 ? '' : lines.slice(start + 1).join('\n');
+}
+
+/**
+ * Extract the `blocked by #N` refs from an already-split footer block, as the
+ * `"#N"` strings a Story body's `depends_on` field round-trips.
+ *
+ * @param {string} footerBlock
+ * @returns {string[]}
+ */
+export function parseFooterBlockedByRefs(footerBlock) {
+  if (!footerBlock) return [];
+  return String(footerBlock)
+    .split('\n')
+    .map((line) => line.trim().match(FOOTER_BLOCKED_BY_LINE_RE)?.[1])
+    .filter((ref) => typeof ref === 'string');
+}
+
+/**
+ * Parse a body's declared blocker issue **numbers**, deduped — the
+ * dispatch-edge view of the same footer the body parser reads.
+ *
+ * @param {string} body
+ * @returns {number[]}
+ */
+export function parseFooterBlockedByIds(body) {
+  const ids = parseFooterBlockedByRefs(extractFooterBlock(body)).map((ref) =>
+    Number.parseInt(ref.slice(1), 10),
+  );
+  return [...new Set(ids)];
+}

package/.agents/scripts/lib/story-body/story-body.js

@@ -48,6 +48,7 @@ import {
 } from '../framework-version.js';
 import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
 import { suggestPathEntryFix } from './body-format-lints.js';
+import { isFooterSeparator, parseFooterBlockedByRefs } from './footer-block.js';
 
 // ---------------------------------------------------------------------------
 // Public types (JSDoc only — no runtime schema file)
@@ -313,16 +314,15 @@ function pathEntryFixIt(raw) {
  * Extract the `blocked by #N` lines from the footer block (text after
  * the last `---` separator). Returns an array of "#N" strings.
  *
+ * Delegates to `./footer-block.js`, which owns the footer-block grammar
+ * (Story #5046) so the body parser and the dispatch-edge parser cannot
+ * disagree about what declares an edge.
+ *
  * @param {string} footerBlock
  * @returns {string[]}
  */
 function extractBlockedBy(footerBlock) {
-  const deps = [];
-  for (const line of footerBlock.split('\n')) {
-    const m = line.trim().match(/^blocked by\s+(#\d+)$/i);
-    if (m) deps.push(m[1]);
-  }
-  return deps;
+  return parseFooterBlockedByRefs(footerBlock);
 }
 
 // Matches any trailing `<!-- meta: … -->` block. Object payloads are the
@@ -491,22 +491,6 @@ function splitSections(markdown) {
   return { sections, footer, preamble };
 }
 
-/**
- * True when line `index` opens the footer block: a `---` on its own line
- * whose remaining lines start with a recognised footer key (`parent:`,
- * `Epic:`, `blocked by`).
- *
- * @param {string} line
- * @param {string[]} lines
- * @param {number} index
- * @returns {boolean}
- */
-function isFooterSeparator(line, lines, index) {
-  if (!/^---\s*$/.test(line)) return false;
-  const remaining = lines.slice(index + 1).join('\n');
-  return /^(parent:|Epic:|blocked by)/im.test(remaining);
-}
-
 /**
  * True for a non-canonical markdown heading that TERMINATES the current
  * structured section. Trailing extended content a producer appends after the

package/.agents/scripts/lib/wave-runner/footprint.js

@@ -0,0 +1,306 @@
+/**
+ * lib/wave-runner/footprint.js — what a Story is going to touch, and what two
+ * Stories would touch in common.
+ *
+ * Split out of `ready-set.js` (Story #5044), which is the *scheduling* kernel:
+ * eligibility, capacity, admission order. Deciding whether two Stories collide
+ * is a separate question with its own rules — what counts as a declaration,
+ * what counts as evidence, what a glob means, and which text is edit intent
+ * rather than machine-generated noise — and it had grown large enough inside
+ * the scheduler to obscure both.
+ *
+ * The layer has exactly one job: given two Story records, say whether their
+ * file footprints intersect, name the paths, and say whether a declaration or
+ * the text scrape produced the answer. It reads nothing and mutates nothing.
+ *
+ * @module lib/wave-runner/footprint
+ */
+
+/**
+ * Why two footprints collided.
+ *
+ * `declared-overlap` — at least one colliding path was **declared** by both
+ * Stories (or is a declared glob). This is the guard doing its intended job:
+ * two Stories that both list `baselines/maintainability.json` really do have to
+ * be serialized, and no amount of scrape-narrowing should change that.
+ *
+ * `scraped-overlap` — every colliding path reached the comparison through the
+ * evidence widening rather than a declaration. Still a real signal (Story
+ * #4875 exists because declarations are systematically a lower bound), but it
+ * is the class where a false positive is possible, so it is the one an operator
+ * should be able to see and — via `footprintGuard: 'advisory'` — choose not to
+ * enforce.
+ */
+export const OVERLAP_SOURCES = Object.freeze({
+  DECLARED: 'declared-overlap',
+  SCRAPED: 'scraped-overlap',
+});
+
+/**
+ * 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;
+
+/**
+ * The **machine-generated audit provenance footers** — and nothing else.
+ *
+ * `/audit-to-stories` and `plan-persist` stamp `<!-- audit-fingerprints: … -->`
+ * and `<!-- audit-semantic-keys: … -->` onto a Story body as dedup identity.
+ * A semantic key is `area␟primaryFile`, and that `␟` (U+241F) separator is
+ * outside {@link PROSE_PATH_RE}'s character class, so the `primaryFile` half
+ * matches as a standalone path token. `plan-persist` carries the **sweep-wide
+ * union** of those footers onto every sibling of an audit-derived plan, so
+ * every pair of that plan shared path-shaped tokens neither Story would edit —
+ * measured at 10/10 colliding pairs, 0/10 once these blocks are ignored
+ * (issue #5040).
+ *
+ * **This is surgical on purpose: a blanket HTML-comment strip would be wrong.**
+ * `.agents/instructions.md` § 7 puts a complexity decomposition's numbered
+ * sub-steps inside a `<!-- DECOMPOSITION -->` block, and the paths a sub-step
+ * names are exactly the edit intent this layer exists to read. Only the two
+ * provenance markers below are removed; every other comment stays evidence.
+ */
+const PROVENANCE_FOOTER_RE =
+  /<!--\s*audit-(?:fingerprints|semantic-keys)\s*:[\s\S]*?-->/g;
+
+/**
+ * The URL interior of a markdown inline link (`](…)`), with an optional title.
+ * A link target is a *citation* — "see [the spec](docs/architecture.md)" — not
+ * a declaration that this Story will edit that file, and generated bodies cite
+ * the same source report from every sibling. The link **text** is left intact:
+ * a human writing "the caller in [`bin/mandrel.js`](bin/mandrel.js)" is naming
+ * an edit target in the prose half, and that half still counts.
+ */
+const MARKDOWN_LINK_URL_RE = /\]\(\s*[^)\s]*(?:\s+"[^"]*")?\s*\)/g;
+
+/** Default gitignored scratch root when no `project.paths.tempRoot` is threaded. */
+const DEFAULT_TEMP_ROOT = 'temp';
+
+/**
+ * Extract a Story's declared file footprint as a normalized set of path
+ * strings. Accepts the three footprint shapes a Story record can carry:
+ *
+ *   - `files: string[]`                         — explicit footprint.
+ *   - `changes: string[]`                       — string-array sketch.
+ *   - `changeset: Array<{ path }>` /            — object-array sketch (the
+ *     `changes: Array<{ path }>`                   `{ path, assumption }`
+ *                                                  shape from a Story body).
+ *
+ * Paths are trimmed; empty / non-string entries are dropped. A Story with
+ * no declared footprint yields an empty set, which (by {@link detectCollision}'s
+ * contract) means it overlaps with nothing and is never withheld.
+ *
+ * @param {object} story
+ * @returns {Set<string>}
+ */
+export function storyFootprint(story) {
+  const out = new Set();
+  const push = (entry) => {
+    const path =
+      typeof entry === 'string'
+        ? entry
+        : typeof entry?.path === 'string'
+          ? entry.path
+          : null;
+    const trimmed = path?.trim();
+    if (trimmed) out.add(trimmed);
+  };
+  for (const shape of [story?.files, story?.changes, story?.changeset]) {
+    if (Array.isArray(shape)) for (const entry of shape) push(entry);
+  }
+  return out;
+}
+
+/**
+ * Does a declared path contain a glob metacharacter? Mirrors the detection
+ * in `story-body.js#extractChangePaths`, whose `isGlob` flag documents an
+ * "unknown-width footprint" policy that was never implemented downstream.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+function isGlobPath(path) {
+  return path.includes('*') || path.includes('?') || path.includes('{');
+}
+
+/**
+ * Is this path inside the gitignored temp root?
+ *
+ * `project.paths.tempRoot` is scratch space by contract
+ * ([`.agents/instructions.md`](../../../instructions.md) § 6): nothing under it
+ * is ever committed, so it can never be a delivery write target, and two
+ * Stories naming the same `temp/audits/audit-<lens>-results.md` source report
+ * are not racing anything. The match is rooted, not a substring test, so a real
+ * deliverable like `lib/temperature.js` is untouched.
+ *
+ * @param {string} path
+ * @param {string} tempRoot
+ * @returns {boolean}
+ */
+function isUnderTempRoot(path, tempRoot) {
+  if (!tempRoot) return false;
+  const normalized = path.replace(/^\.\//, '');
+  return normalized === tempRoot || normalized.startsWith(`${tempRoot}/`);
+}
+
+/**
+ * Scrape file paths a Story's **text** mentions but its `changes[]` never
+ * declared (Story #4875), **narrowed to text that expresses edit intent**
+ * (Story #5044).
+ *
+ * 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.
+ *
+ * But the converse failure is just as real: a path-shaped token that no human
+ * wrote as intent manufactures a collision, and a manufactured collision
+ * serializes a run that had no reason to be serial. Three token sources are
+ * therefore excluded before the scrape, each because it is *structurally*
+ * incapable of naming an edit target:
+ *
+ *   1. **Audit provenance footers** ({@link PROVENANCE_FOOTER_RE}) — machine-
+ *      stamped dedup identity, unioned sweep-wide across siblings.
+ *   2. **Markdown-link URLs** ({@link MARKDOWN_LINK_URL_RE}) — citations.
+ *   3. **Paths under the temp root** ({@link isUnderTempRoot}) — gitignored
+ *      scratch, never a write target.
+ *
+ * Evidence is only ever **added** to the declaration — nothing here can shrink
+ * a declared footprint, so `changes[]` remains a lower bound (Story #4875) and
+ * narrowing the scrape can never co-dispatch a pair the declared comparison
+ * would have caught.
+ *
+ * @param {object} story
+ * @param {object} [options]
+ * @param {string} [options.tempRoot='temp'] Resolved `project.paths.tempRoot`.
+ * @returns {Set<string>}
+ */
+function storyEvidencePaths(story, { tempRoot = DEFAULT_TEMP_ROOT } = {}) {
+  const out = new Set();
+  for (const field of [story?.title, story?.body, story?.spec]) {
+    if (typeof field !== 'string') continue;
+    const scannable = field
+      .replace(PROVENANCE_FOOTER_RE, ' ')
+      .replace(MARKDOWN_LINK_URL_RE, ']()');
+    for (const [token] of scannable.matchAll(PROSE_PATH_RE)) {
+      if (!isUnderTempRoot(token, tempRoot)) out.add(token);
+    }
+  }
+  return out;
+}
+
+/**
+ * A Story's declared footprint **and** the evidence-widened one.
+ *
+ * Both are returned because they answer different questions. `widened` decides
+ * *whether* two Stories collide; `declared` decides *how to describe* the
+ * collision — a path both Stories declared is intended serialization (two
+ * Stories that really do rewrite the same generated baseline), while one only
+ * the scrape produced may be an artifact of how a body was worded. An operator
+ * reading an unfilled slot needs to tell those apart.
+ *
+ * @param {object} story
+ * @param {object} [options]
+ * @returns {{ declared: Set<string>, widened: Set<string> }}
+ */
+function storyFootprints(story, options) {
+  const declared = storyFootprint(story);
+  const widened = new Set(declared);
+  for (const path of storyEvidencePaths(story, options)) widened.add(path);
+  return { declared, widened };
+}
+
+/**
+ * Record one colliding path, remembering whether **any** occurrence of it was
+ * declaration-backed.
+ *
+ * `declared` is tracked per path rather than per pair because the two hit kinds
+ * qualify differently: a shared **concrete** path counts as declared only when
+ * both sides declared it, whereas a **glob** names no file to share and counts
+ * as declared when its own side declared it. The scraper cannot emit a glob —
+ * prose globs are narrative ("everything under `.agents/**`") and never match
+ * {@link PROSE_PATH_RE} — so a glob hit is essentially always declared width
+ * failing safe, and labelling it `scraped` would make advisory mode read as if
+ * the text widening had caused it.
+ *
+ * @param {Map<string, boolean>} hits
+ * @param {string} path
+ * @param {boolean} declared
+ */
+function recordHit(hits, path, declared) {
+  hits.set(path, (hits.get(path) ?? false) || declared);
+}
+
+/**
+ * Collect the glob paths on one side. A glob is unknown width, and unknown
+ * width is not no width: within a beat it collides with everything, because
+ * exact-string comparison would silently pass a Story declaring
+ * `.agents/scripts/lib/**` alongside one declaring a file underneath it
+ * (Story #4539/#4540).
+ *
+ * @param {Map<string, boolean>} hits
+ * @param {{ declared: Set<string>, widened: Set<string> }} side
+ */
+function recordGlobs(hits, side) {
+  for (const path of side.widened) {
+    if (isGlobPath(path)) recordHit(hits, path, side.declared.has(path));
+  }
+}
+
+/**
+ * The colliding paths between two Stories' widened footprints, tagged with
+ * whether a declaration produced the collision — or `null` when they do not
+ * collide.
+ *
+ * **An empty footprint means "no known overlap"**, so this short-circuits to
+ * `null` on one. That is permissive by necessity: a Story with no declared
+ * footprint and no path evidence in its text carries no information, and
+ * withholding on absence would serialize every run.
+ *
+ * `concreteOnly` selects between the two guards' deliberately different
+ * treatment of unknown width (Story #4960). The beat-local guard counts a glob
+ * on either side as colliding with everything; the cross-beat reservation
+ * ignores globs entirely, because an in-flight Story holds its footprint for a
+ * whole implementation window and one glob would otherwise withhold the entire
+ * run for hours — and `resolve-stories.js` substitutes an UNKNOWN sentinel for
+ * any body it cannot parse, so one malformed Story would make a run serial.
+ *
+ * @param {object} a
+ * @param {object} b
+ * @param {object} [options]
+ * @param {boolean} [options.concreteOnly=false] Skip glob paths on both sides.
+ * @param {string} [options.tempRoot]
+ * @returns {{ paths: string[], source: string }|null}
+ */
+export function detectCollision(
+  a,
+  b,
+  { concreteOnly = false, ...evidence } = {},
+) {
+  const fa = storyFootprints(a, evidence);
+  if (fa.widened.size === 0) return null;
+  const fb = storyFootprints(b, evidence);
+  if (fb.widened.size === 0) return null;
+
+  const hits = new Map();
+  for (const path of fa.widened) {
+    if (!isGlobPath(path) && fb.widened.has(path)) {
+      recordHit(hits, path, fa.declared.has(path) && fb.declared.has(path));
+    }
+  }
+  if (!concreteOnly) {
+    recordGlobs(hits, fa);
+    recordGlobs(hits, fb);
+  }
+  if (hits.size === 0) return null;
+  return {
+    paths: [...hits.keys()].sort(),
+    source: [...hits.values()].some(Boolean)
+      ? OVERLAP_SOURCES.DECLARED
+      : OVERLAP_SOURCES.SCRAPED,
+  };
+}