mandrel 2.32.0 → 2.34.0

package/.agents/scripts/lib/config/runners.js

@@ -30,9 +30,19 @@ export const DEFAULT_DECOMPOSER = Object.freeze({
  * `verifyWaveResults` loop it claimed to bound never existed in the tree, and
  * its only reader was the retired execution-analysis CLI, which echoed the
  * number into a report rather than bounding anything.
+ *
+ * **Serialization tradeoff — `footprintGuard`.** `enforce` is the default and
+ * stays it: the file-overlap guard encodes delivery-time-only knowledge (which
+ * implementation windows are open, which Stories a foreign lease holds) that no
+ * plan-time `depends_on` edge can carry, so demoting it by default would trade
+ * a real merge-conflict class for throughput nobody asked for. `advisory`
+ * detects collisions and reports every would-be withhold but lets dispatch
+ * follow the declared edges alone — for runs whose ordering is fully declared
+ * (Story #5044).
  */
 const DEFAULT_DELIVER_RUNNER = Object.freeze({
   concurrencyCap: 3,
+  footprintGuard: 'enforce',
 });
 
 /**
@@ -51,28 +61,40 @@ export const DEFAULT_CODE_REVIEW = Object.freeze({
  *
  * @param {object | null | undefined} config
  * @returns {{
- *   deliverRunner: { concurrencyCap: number },
+ *   deliverRunner: { concurrencyCap: number, footprintGuard: 'enforce'|'advisory' },
  *   codeReview: { maxFixAttempts: number, maxFixScopeFiles: number, autoFixSeverity: 'high'|'medium' },
  *   decomposer: { concurrencyCap: number },
  * }}
  */
 export function getRunners(config) {
-  const deliverRunnerUser = config?.delivery?.deliverRunner ?? {};
-  const codeReviewUser = config?.delivery?.codeReview ?? {};
   return {
-    deliverRunner: {
-      concurrencyCap:
-        deliverRunnerUser.concurrencyCap ??
-        DEFAULT_DELIVER_RUNNER.concurrencyCap,
-    },
-    codeReview: {
-      maxFixAttempts:
-        codeReviewUser.maxFixAttempts ?? DEFAULT_CODE_REVIEW.maxFixAttempts,
-      maxFixScopeFiles:
-        codeReviewUser.maxFixScopeFiles ?? DEFAULT_CODE_REVIEW.maxFixScopeFiles,
-      autoFixSeverity:
-        codeReviewUser.autoFixSeverity ?? DEFAULT_CODE_REVIEW.autoFixSeverity,
-    },
+    deliverRunner: withDefaults(
+      DEFAULT_DELIVER_RUNNER,
+      config?.delivery?.deliverRunner,
+    ),
+    codeReview: withDefaults(DEFAULT_CODE_REVIEW, config?.delivery?.codeReview),
     decomposer: DEFAULT_DECOMPOSER,
   };
 }
+
+/**
+ * Overlay an operator's block onto the framework defaults — the per-key `??`
+ * fallback these accessors have always applied, written once.
+ *
+ * Iterating the **defaults'** keys rather than the user's is what keeps the
+ * returned shape closed: a key the framework does not define cannot reach a
+ * consumer through here even if one somehow survived AJV, so a typo degrades to
+ * the default rather than to an undefined a caller would read as configuration.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} defaults      Frozen framework defaults.
+ * @param {object|null|undefined} user Operator block from `.agentrc`.
+ * @returns {T} A fresh object; the frozen defaults are never mutated.
+ */
+function withDefaults(defaults, user) {
+  const out = { ...defaults };
+  for (const key of Object.keys(defaults)) {
+    if (user?.[key] != null) out[key] = user[key];
+  }
+  return out;
+}

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -73,10 +73,18 @@ const DELIVER_RUNNER_SCHEMA = {
       minimum: 1,
       description:
         'Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff.',
-      // getRunners() resolves this inline rather than from an exported
-      // constant; the rewritten parity suite asserts the two agree.
+      // getRunners() resolves this from its own DEFAULT_DELIVER_RUNNER
+      // constant, not from this annotation; the parity suite asserts the two
+      // agree.
       default: 3,
     },
+    footprintGuard: {
+      type: 'string',
+      enum: ['enforce', 'advisory'],
+      description:
+        "How a file-footprint collision affects dispatch. 'enforce' (default, and the behaviour to keep unless you have a reason) withholds a Story whose footprint races a peer admitted this beat or one still in flight — the guard encodes delivery-time-only knowledge (open implementation windows, foreign leases, ground that moved since planning) that no depends_on edge can carry. 'advisory' still DETECTS every collision and reports each would-be withhold in the tick envelope, but lets dispatch follow the declared depends_on edges alone — a deliberate throughput trade for a run whose ordering is fully declared. See stories-wave-tick.js and helpers/deliver-reference.md.",
+      default: 'enforce',
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/coverage-capture-incremental.js

@@ -14,6 +14,14 @@ import path from 'node:path';
  * Run the incremental capture path when
  * `delivery.quality.gates.crap.incrementalCoverage.enabled` is true.
  *
+ * **This does not shorten the capture run.** The changed-file set decides
+ * *whether* to capture, never *what* the capture executes: when nothing under
+ * `crap.targetDirs` changed there is no capture at all, and otherwise the
+ * ordinary full `npm run test:coverage` runs. The saving that makes the mode
+ * worth having is the skip; the other half is the CRAP join, which resolves
+ * methods in untouched files from the committed baseline row
+ * (`crap-baseline-join.js`) instead of demanding fresh coverage for them.
+ *
  * Returns the process exit code when incremental mode handled the run
  * (skip, capture, or a capture failure), or `null` when the caller should
  * fall through to the full-scope path — either incremental mode is
@@ -81,13 +89,12 @@ export function tryIncrementalCapture({
   }
 
   logger.info(
-    `[coverage-capture] Incremental mode: capturing coverage scoped to ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}]…`,
+    `[coverage-capture] Incremental mode: ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}] — capturing…`,
   );
   const code = runCaptureImpl({
     cwd: args.cwd,
     timeoutMs: coverage?.timeoutMs,
     log: (m) => logger.info(m),
-    files: scopedFiles,
   });
   if (code !== 0) {
     logger.error(

package/.agents/scripts/lib/coverage-capture-usage.js

@@ -0,0 +1,55 @@
+/**
+ * coverage-capture-usage.js — the `--help` spec for `coverage-capture.js`
+ * (Story #5063).
+ *
+ * The delivery workflow invokes `coverage-capture.js` by name
+ * (`helpers/deliver-story-reference.md` § Step 1), which brings it under the
+ * workflow-invoked self-description contract enforced by
+ * `tests/enforcement/workflow-script-help.test.js`. It failed that contract:
+ * `--help` fell through to the capture path and spawned the whole coverage
+ * suite instead of describing the script.
+ *
+ * The spec lives here rather than inline for the same reason
+ * `coverage-capture-incremental.js` does — a same-file expansion of the CLI
+ * shell costs maintainability index on a file already near its floor, and a
+ * usage table is data, not decision logic.
+ */
+
+import { respondToHelp } from './cli-usage.js';
+
+/**
+ * Usage spec consumed by `cli-usage.js#respondToHelp`. `coverage-capture.js`
+ * does not route through `runAsCli` (its synchronous main returns an exit
+ * code that `process.exit` forwards), so the help short-circuit is wired by
+ * hand rather than declared on a `runAsCli` call.
+ *
+ * @type {{ invocation: string, summary: string, flags: Array<[string, string]> }}
+ */
+const COVERAGE_CAPTURE_USAGE = {
+  invocation:
+    'node .agents/scripts/coverage-capture.js [--skip-when-no-crap-files] [--ref <git-ref>] [--cwd <path>]',
+  summary:
+    'Ensure coverage/coverage-final.json is present and fresh before the CRAP gate fires, spawning `npm run test:coverage` only when it is stale. Writes a content-digest capture stamp that close-validation reads to skip a redundant re-run.',
+  flags: [
+    [
+      '--skip-when-no-crap-files',
+      'Exit 0 without capturing when no changed file under the CRAP target dirs differs from --ref.',
+    ],
+    ['--ref <git-ref>', 'Git ref the changed-file set is computed against.'],
+    ['--cwd <path>', 'Repository root the capture runs in.'],
+  ],
+};
+
+/**
+ * Answer `--help` / `-h` on stdout, returning whether the caller should stop.
+ * Takes the full `process.argv`-shaped array so the CLI shell hands over its
+ * own argv unchanged and the index arithmetic lives here rather than at the
+ * call site.
+ *
+ * @param {string[]} argv Full `process.argv`-shaped array.
+ * @param {{ write: (s: string) => void }} [out] Defaults to `process.stdout`.
+ * @returns {boolean} `true` when help was printed and the run must not proceed.
+ */
+export function handleCoverageCaptureHelp(argv = [], out = process.stdout) {
+  return respondToHelp(argv.slice(2), COVERAGE_CAPTURE_USAGE, out);
+}

package/.agents/scripts/lib/coverage-capture.js

@@ -363,20 +363,21 @@ export const COVERAGE_TIMEOUT_EXIT_CODE = 124;
  * `timeout(1)` convention exit code 124 so callers can pattern-match a
  * runaway runner without inspecting signal names.
  *
- * `files` (Story #4981) scopes the spawn to a file list — `npm run
- * test:coverage -- <files...>`, the standard npm convention for forwarding
- * argv to the underlying script (which most test runners, including Node's
- * own, treat as positional file filters). Omitted or empty means the
- * default full-scope invocation, byte-identical to the pre-#4981 argv
- * (AC-5); a non-empty list makes the scope observable on the emitted
- * command line (AC-1).
+ * The spawn takes **no positional file arguments**. Story #4981 forwarded the
+ * changed-file list as `npm run test:coverage -- <files...>` on the premise
+ * that a test runner treats trailing positionals as filters over the suite.
+ * Node's runner does not: it treats each path as a test file to execute, so a
+ * forwarded *source* file runs as a trivially-passing test and the real suite
+ * never runs. `run-coverage.js` discarded the list, which is the only reason
+ * that never bit; Story #5063 measured it and Story #5065 removed the
+ * plumbing rather than leave a parameter whose obvious "fix" empties the
+ * coverage artifact.
  *
  * @param {{
  *   cwd: string,
  *   timeoutMs?: number,
  *   runner?: typeof spawnSync,
  *   log?: (m: string) => void,
- *   files?: string[] | null,
  * }} opts
  * @returns {number}
  */
@@ -385,14 +386,8 @@ export function runCapture({
   timeoutMs,
   runner = spawnSync,
   log = () => {},
-  files = null,
 } = {}) {
-  const scopedFiles = Array.isArray(files) && files.length > 0 ? files : null;
-  const args = [
-    'run',
-    'test:coverage',
-    ...(scopedFiles ? ['--', ...scopedFiles] : []),
-  ];
+  const args = ['run', 'test:coverage'];
   log(`[coverage-capture] ▶ npm ${args.join(' ')}`);
   const spawnOpts = {
     cwd,

package/.agents/scripts/lib/dependency-parser.js

@@ -7,18 +7,31 @@
  * lib/story-adjacency.js, lib/branch-name-guard.js).
  */
 
+import { parseFooterBlockedByIds } from './story-body/footer-block.js';
+
 /**
- * Parse `blocked by #NNN` and `depends on #NNN` references from text.
- * Handles case-insensitive variations.
+ * Parse a body's declared blocker issue numbers — **footer-scoped and
+ * strict**.
+ *
+ * Only a `blocked by #N` line standing alone inside the `---` footer block
+ * declares an edge. The unanchored predecessor scanned the whole body for
+ * `blocked by|depends on #N` anywhere, so a Story whose prose merely mentioned
+ * a blocker — an example, a changelog note, an acceptance criterion describing
+ * this very defect — minted a real dispatch gate that withheld the Story until
+ * an unrelated issue closed.
+ *
+ * The behaviour change is deliberate and user-visible: prose-only mentions
+ * outside the footer no longer gate. Every machine-authored body already
+ * carries the canonical footer form (`plan-persist` has always serialized it),
+ * so only hand-written prose edges are affected — those must be moved into the
+ * footer block to keep gating. The grammar itself lives in
+ * `lib/story-body/footer-block.js`, shared with the body parser.
  *
  * @param {string} body - Issue body or freeform text.
- * @returns {number[]} Array of issue numbers this text declares as blockers.
+ * @returns {number[]} Array of issue numbers this body declares as blockers.
  */
 export function parseBlockedBy(body) {
-  if (!body) return [];
-  const re = /(?:blocked\s+by|depends\s+on):?\s+#(\d+)/gi;
-  const ids = [...body.matchAll(re)].map((m) => Number.parseInt(m[1], 10));
-  return [...new Set(ids)];
+  return parseFooterBlockedByIds(body);
 }
 
 /**

package/.agents/scripts/lib/findings/provenance-field.js

@@ -0,0 +1,135 @@
+/**
+ * lib/findings/provenance-field.js — the per-Story `provenance` field.
+ *
+ * An audit-seeded plan carries dedup identities forward so the next sweep
+ * recognises what it already planned. The optional top-level `provenance`
+ * field on a `stories.json` entry says **which of them that Story owns**:
+ *
+ * ```jsonc
+ * { "fingerprints": ["<40-char sha1>"], "semanticKeys": ["architecture␟lib/a.js"] }
+ * ```
+ *
+ * Two callers, deliberately split from
+ * [`route-finding.js`](route-finding.js): the ticket validator shape-checks
+ * the authored field, and plan-persist's assembly renders the owned identities
+ * into the footer source it stamps. Neither is dedup *routing*, which is what
+ * `route-finding.js` is for — this module reads its identity vocabulary
+ * (`SHA1_RE`, `SEMANTIC_KEY_RE`, and the two footer renderers) from there so
+ * there is exactly one definition of what a fingerprint or a semantic key
+ * looks like.
+ *
+ * @module lib/findings/provenance-field
+ */
+
+import {
+  fingerprintFooter,
+  SEMANTIC_KEY_RE,
+  SHA1_RE,
+  semanticKeyFooter,
+} from './route-finding.js';
+
+/** Human-readable rendering of the `provenance` field's two lists. */
+const PROVENANCE_SHAPE = 'fingerprints[] / semanticKeys[]';
+
+/** What each `provenance` list accepts, and how to say so when it does not. */
+const PROVENANCE_FIELDS = Object.freeze({
+  fingerprints: { pattern: SHA1_RE, expected: 'a 40-char sha1 hex string' },
+  semanticKeys: {
+    pattern: SEMANTIC_KEY_RE,
+    expected: 'a non-empty key carrying no comma or ">"',
+  },
+});
+
+/**
+ * Validate one authored `provenance` list into its normalized form.
+ *
+ * @param {unknown} list
+ * @param {{ where: string, field: string, pattern: RegExp, expected: string }} spec
+ * @returns {string[]} Trimmed, de-duplicated, first-seen order.
+ */
+function normalizeList(list, { where, field, pattern, expected }) {
+  if (list === null || list === undefined) return [];
+  if (!Array.isArray(list)) {
+    throw new Error(`${where}: ${field} must be an array of strings`);
+  }
+  const out = [];
+  for (const entry of list) {
+    const value = typeof entry === 'string' ? entry.trim() : '';
+    if (!pattern.test(value)) {
+      throw new Error(
+        `${where}: ${field} entry ${JSON.stringify(entry)} is not ${expected}`,
+      );
+    }
+    if (!out.includes(value)) out.push(value);
+  }
+  return out;
+}
+
+/**
+ * Normalize the optional per-Story `provenance` field a plan may author —
+ * the identities of the findings **that Story owns**.
+ *
+ * Absence is meaningful and must stay cheap: `undefined` / `null` returns
+ * `null`, which is the caller's signal to fall back to the whole-seed union
+ * carry. That fallback is not vestigial — leaving the authoring agent to
+ * hand-carry provenance out of the seed's HTML comments was measured to fail,
+ * and the mechanical union is what closed it. Attribution is **additive**: a
+ * plan that attributes gets exact stamping, a plan that does not keeps recall.
+ *
+ * An empty object is therefore *not* the same as an absent field: it means
+ * "this Story owns nothing", and stamps nothing.
+ *
+ * Present-but-malformed is a hard error rather than a silent drop, because a
+ * dropped identity is invisible until the next sweep re-files work that was
+ * already planned.
+ *
+ * @param {unknown} raw
+ * @param {string} [label] Identifier for the error message (a Story slug).
+ * @returns {{ fingerprints: string[], semanticKeys: string[] }|null}
+ * @throws {Error} On any shape the stamper cannot honour exactly.
+ */
+export function normalizeOwnedProvenance(raw, label = 'story') {
+  if (raw === undefined || raw === null) return null;
+  const where = `provenance on "${label}"`;
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${where} must be an object of ${PROVENANCE_SHAPE}`);
+  }
+  const out = { fingerprints: [], semanticKeys: [] };
+  for (const [field, list] of Object.entries(raw)) {
+    const spec = PROVENANCE_FIELDS[field];
+    if (!spec) {
+      throw new Error(
+        `${where} carries an unknown field: ${field} — only ${PROVENANCE_SHAPE} are stamped`,
+      );
+    }
+    out[field] = normalizeList(list, { where, field, ...spec });
+  }
+  return out;
+}
+
+/**
+ * Render the provenance **source document** for a set of owned identities, in
+ * the same footer vocabulary `carryProvenanceFooters` harvests from an audit
+ * seed. That reuse is the point: attribution changes *which* identities reach
+ * a Story body, never how they are stamped, so the carry stays additive,
+ * union-preserving and idempotent for an attributed plan exactly as it is for
+ * an un-attributed one.
+ *
+ * An empty (or absent) set renders the empty string, which the carry treats as
+ * nothing-to-do — so a Story that owns no findings is stamped with none rather
+ * than inheriting its siblings'.
+ *
+ * Expects the normalized shape {@link normalizeOwnedProvenance} returns; the
+ * validator runs first on every production path.
+ *
+ * @param {{ fingerprints?: string[], semanticKeys?: string[] }|null} [provenance]
+ * @returns {string}
+ */
+export function ownedProvenanceSource(provenance) {
+  const shas = provenance?.fingerprints ?? [];
+  const keys = provenance?.semanticKeys ?? [];
+  const parts = [];
+  if (shas.length > 0) parts.push(fingerprintFooter(shas));
+  if (keys.length > 0) parts.push(semanticKeyFooter(keys));
+  return parts.join('\n');
+}

package/.agents/scripts/lib/findings/route-finding.js

@@ -35,11 +35,11 @@ import { fingerprintSeverity } from './severity.js';
 const SEP = '␟'; // unit separator — keeps fingerprint fields unambiguous
 const MARKER = 'audit-fingerprints:';
 const SEMANTIC_MARKER = 'audit-semantic-keys:';
-const SHA1_RE = /^[0-9a-f]{40}$/;
+export const SHA1_RE = /^[0-9a-f]{40}$/;
 // A semantic key round-trips through a comma-joined footer, so it must not
 // carry a comma or a `>` (which would truncate the HTML comment). Both are
 // stripped when the key is built, so this guard is defence-in-depth.
-const SEMANTIC_KEY_RE = /^[^,>]+$/;
+export const SEMANTIC_KEY_RE = /^[^,>]+$/;
 
 /**
  * Normalise a single scalar identity field to a stable string.
@@ -343,12 +343,59 @@ function decisionForIssue(issue) {
   return state === 'closed' ? 'regression-of-closed' : 'update-existing';
 }
 
+/**
+ * Resolve the pool that **attributes** a finding, out of everything that
+ * confirmed it (Story #5045).
+ *
+ * Confirmation admits two different strengths of claim, and collapsing them
+ * was the source of two wrong routes:
+ *
+ * - An issue carrying the finding's exact **fingerprint** owns it. That is
+ *   identity: this issue tracks *this* finding.
+ * - An issue matching only on the location-based **semantic key** is merely
+ *   adjacent: it tracks *a* finding at the same `area␟primaryFile`.
+ *
+ * Owners win outright when any exist. Location-only matches are not discarded
+ * — they are the whole point of the semantic key and remain the pool when
+ * nothing carries the fingerprint (a reworded finding at an unchanged
+ * location). The pool is sorted by issue number so a genuine tie resolves to
+ * the earliest-filed issue rather than to whatever order the search port
+ * happened to return.
+ *
+ * @param {Array<{ number: number, state: string, body?: string }>} confirmed
+ * @param {string} sha
+ * @returns {Array<{ number: number, state: string }>}
+ */
+function attributedPool(confirmed, sha) {
+  const owns = (issue) => issueCarriesFingerprint(issue, sha);
+  const owners = confirmed.filter(owns);
+  const pool = owners.length > 0 ? owners : confirmed.filter((i) => !owns(i));
+  return [...pool].sort((a, b) => (a?.number ?? 0) - (b?.number ?? 0));
+}
+
 /**
  * Decide the final route from a confirmed-match pool (issues that both
- * surfaced in the candidate/search pass AND carry the finding's fingerprint
- * in their footer). Shared by both the semantic-first and fingerprint-only
- * code paths so the decision enum is identical regardless of how candidates
- * were gathered.
+ * surfaced in the candidate/search pass AND carry a confirming footer).
+ * Shared by both the semantic-first and fingerprint-only code paths so the
+ * decision enum is identical regardless of how candidates were gathered.
+ *
+ * **Attribution decides, not array order (Story #5045).** The pool used to be
+ * read flat, which produced two wrong answers whenever more than one issue
+ * confirmed:
+ *
+ *   1. Two open matches routed `duplicate` pinned to `open[0]` — whichever
+ *    issue the search port happened to return first. With per-Story
+ *    provenance that pick is answerable rather than arbitrary: the issue
+ *    carrying the finding's own fingerprint owns it, and a sibling matching
+ *    only by location does not.
+ *   2. Any open match at all masked a closed one, so a finding whose
+ *    fingerprint is owned by a **closed** Story routed `update-existing`
+ *    against an open neighbour — a genuine regression filed as a
+ *    business-as-usual update. Attribution restores it: state is read off the
+ *    owning issue, not off whatever else shares its location.
+ *
+ * {@link attributedPool} owns that selection; the decision below reads only
+ * the pool it returns.
  *
  * @param {Array<{ number: number, state: string }>} confirmed
  * @param {string} sha
@@ -359,7 +406,8 @@ function decideFromConfirmed(confirmed, sha) {
     return { decision: 'new', matchedIssue: null, fingerprint: sha };
   }
 
-  const open = confirmed.filter((h) => normaliseField(h.state) === 'open');
+  const attributed = attributedPool(confirmed, sha);
+  const open = attributed.filter((h) => normaliseField(h.state) === 'open');
   if (open.length > 1) {
     return { decision: 'duplicate', matchedIssue: open[0], fingerprint: sha };
   }
@@ -371,7 +419,7 @@ function decideFromConfirmed(confirmed, sha) {
     };
   }
 
-  const closed = confirmed[0];
+  const closed = attributed[0];
   return {
     decision: decisionForIssue(closed),
     matchedIssue: closed,
@@ -484,4 +532,5 @@ export const __testing = {
   decideFromConfirmed,
   issueCarriesSemanticKey,
   parseSemanticKeyFooter,
+  attributedPool,
 };