mandrel 2.25.0 → 2.27.0

package/.agents/scripts/lib/cli-args.js

@@ -62,13 +62,71 @@ function parsePositiveInt(value) {
   return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
 
+/** The only two merge-watch postures `--merge-watch-mode` accepts. */
+const MERGE_WATCH_MODES = ['sync', 'async'];
+
+/**
+ * Parse `--merge-watch-mode` (Story #4949), the per-invocation override of
+ * `delivery.mergeWatch.mode`. Absence is preserved as `undefined` so the
+ * caller can distinguish "not supplied" (fall back to config) from an explicit
+ * posture — the same contract {@link parsePositiveInt} gives
+ * `--max-wait-seconds`.
+ *
+ * Unlike that sibling, an unrecognized value **throws** rather than degrading
+ * to absent. A `--max-wait-seconds` typo falls back to a sane bound; a
+ * `--merge-watch-mode` typo would fall back to `sync` and silently return a
+ * multi-Story run to a serialized foreground wait per close, with the wall
+ * clock as the only evidence. Parsing runs before the first close phase, so
+ * failing here costs no mutation.
+ *
+ * @param {unknown} value
+ * @returns {'sync'|'async'|undefined}
+ */
+export function parseMergeWatchMode(value) {
+  if (value == null) return undefined;
+  const mode = String(value).trim().toLowerCase();
+  if (MERGE_WATCH_MODES.includes(mode)) return mode;
+  throw new Error(
+    `--merge-watch-mode must be one of ${MERGE_WATCH_MODES.join('|')} (got "${value}")`,
+  );
+}
+
+/**
+ * {@link parseMergeWatchMode} degraded to the "absent" value instead of
+ * throwing — how the tolerant parse below treats a flag that failed
+ * validation. Reporting `undefined` is safe there and only there, because a
+ * tolerant parse never drives a pipeline: its caller surfaces the rejection
+ * as the run's failure and runs no phase at all.
+ *
+ * @param {unknown} value
+ * @returns {'sync'|'async'|undefined}
+ */
+function tolerantMergeWatchMode(value) {
+  try {
+    return parseMergeWatchMode(value);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Standardized CLI argument parser for sprint scripts.
  * Supports options like --epic, --story, --dry-run, --skip-dashboard.
+ *
+ * Throws when a *validating* parser rejects a flag value (currently only
+ * `--merge-watch-mode`). Callers that must not throw — an error handler
+ * needing `storyId` to report an envelope — use {@link parseSprintArgsTolerant}
+ * rather than calling this a second time inside their own catch.
+ *
  * @param {string[]} args Array of arguments (defaults to process.argv)
+ * @param {{ tolerant?: boolean }} [options] `tolerant` degrades a rejected
+ *   flag to its absent value instead of throwing. For reporting only.
  * @returns {object} Parsed and typed argument values
  */
-export function parseSprintArgs(args = process.argv) {
+export function parseSprintArgs(
+  args = process.argv,
+  { tolerant = false } = {},
+) {
   const { values, positionals } = parseArgs({
     args: args.slice(2),
     options: {
@@ -85,6 +143,10 @@ export function parseSprintArgs(args = process.argv) {
       // Story #4543 — per-run override of `delivery.mergeWatch.maxWaitSeconds`
       // (the merge wait's per-invocation bound). Absent means "use the config".
       'max-wait-seconds': { type: 'string' },
+      // Story #4949 — per-invocation override of `delivery.mergeWatch.mode`.
+      // Absent means "use the config"; see `parseMergeWatchMode` for why an
+      // unrecognized value fails closed instead of degrading to absent.
+      'merge-watch-mode': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -115,6 +177,12 @@ export function parseSprintArgs(args = process.argv) {
     // headless caller with no host tool-invocation ceiling, so it lands in
     // one block instead of returning `pending` at the default 300s.
     maxWaitSeconds: parsePositiveInt(values['max-wait-seconds']),
+    // Story #4949 — per-invocation override of `delivery.mergeWatch.mode`.
+    // `undefined` when the flag is absent, which is what lets the merge wait
+    // fall back to the config; anything unrecognized throws here.
+    mergeWatchMode: tolerant
+      ? tolerantMergeWatchMode(values['merge-watch-mode'])
+      : parseMergeWatchMode(values['merge-watch-mode']),
     executor: values.executor ?? null,
     // Resolve worktree cwd from flag or env. Empty string/whitespace → null.
     cwd:
@@ -137,6 +205,52 @@ export function parseSprintArgs(args = process.argv) {
   return parsed;
 }
 
+/**
+ * Last-resort tolerant parse: the fields, or an empty bag if even the
+ * tolerant pass cannot produce one.
+ *
+ * @param {string[]} args
+ * @returns {object}
+ */
+function parseSprintArgsOrEmpty(args) {
+  try {
+    return parseSprintArgs(args, { tolerant: true });
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parse argv **without ever throwing**, returning the fields alongside the
+ * rejection rather than in place of it.
+ *
+ * `parseSprintArgs` gained its first *validating* parser in
+ * {@link parseMergeWatchMode} (Story #4949), which made a latent shape in the
+ * CLI entries fatal: their catch blocks called
+ * `failedTerminalFor(err, parseSprintArgs())` — re-invoking the very parser
+ * that had just thrown. The second throw escaped the catch, so an
+ * unparseable argv produced a bare stack trace with **no terminal envelope
+ * and no friction signal**, on the two surfaces whose whole contract is that
+ * they always emit one. An error handler must not depend on an operation
+ * already known to fail.
+ *
+ * So the entries parse **once**, up front, through this wrapper: `args`
+ * carries the `storyId` and skip flags the envelope is built from, and
+ * `error` is the failure to report. The tolerant re-parse degrades **only**
+ * the flag that failed validation; every other field parses normally. Use
+ * the result to *report*, never to run a pipeline.
+ *
+ * @param {string[]} [args] Array of arguments (defaults to `process.argv`)
+ * @returns {{ args: object, error: Error|null }}
+ */
+export function parseSprintArgsTolerant(args = process.argv) {
+  try {
+    return { args: parseSprintArgs(args), error: null };
+  } catch (error) {
+    return { args: parseSprintArgsOrEmpty(args), error };
+  }
+}
+
 const SUPPORTED_FLAG_TYPES = new Set([
   'boolean',
   'ticket',

package/.agents/scripts/lib/close-validation/runner.js

@@ -315,17 +315,79 @@ export async function runCloseValidation({
   }
 
   // ── Phase 2: serial gates in declared order ─────────────────────────
+  await runSerialGates(serial, {
+    spawnCwd,
+    log,
+    failed,
+    skipped,
+    evidenceActive,
+    evidenceClock,
+    evidenceVerdict,
+    recordIfActive,
+    dispatchGate,
+  });
+
+  // ── Phase 3: advisory projections ───────────────────────────────────
+  // Story #4776 — the projection layer's live call site. Deliberately
+  // outside the `ok` computation: a projected breach informs, it never
+  // fails a close.
+  if (failed.length === 0) {
+    await runAdvisoryProjections({
+      runProjections,
+      cwd: spawnCwd,
+      baseBranch,
+      storyBranch,
+      config,
+      log,
+    });
+  }
+
+  return { ok: failed.length === 0, failed, skipped };
+}
+
+/**
+ * Phase 2 helper — run the serial gates in declared order, stopping at the
+ * first failure. Extracted from `runCloseValidation` (Story #4926); the
+ * evidence bookkeeping stays bit-identical to the parallel pass because both
+ * call the same injected `evidenceVerdict` / `recordIfActive` closures.
+ *
+ * Mutates the caller's `failed` / `skipped` accumulators — the same arrays
+ * Phase 1 already wrote into, so the returned verdict stays one list.
+ *
+ * @param {Array<object>} serial
+ * @param {object} deps
+ * @returns {Promise<void>}
+ */
+async function runSerialGates(
+  serial,
+  {
+    spawnCwd,
+    log,
+    failed,
+    skipped,
+    evidenceActive,
+    evidenceClock,
+    evidenceVerdict,
+    recordIfActive,
+    dispatchGate,
+  },
+) {
+  const failGate = (gate, status, message) => {
+    failed.push({ gate, status, cwd: spawnCwd });
+    log(message);
+    if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
+  };
   for (const gate of serial) {
     let execution;
     try {
       execution = applyChangedFileScope({ gate, spawnCwd, log });
     } catch (err) {
-      failed.push({ gate, status: 1, cwd: spawnCwd });
-      log(
+      failGate(
+        gate,
+        1,
         `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
       );
-      if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
-      break;
+      return;
     }
     if (execution.skip) {
       skipped.push({ gate, reason: 'no-changed-files' });
@@ -349,12 +411,12 @@ export async function runCloseValidation({
       tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
     });
     if (result.status !== 0) {
-      failed.push({ gate, status: result.status, cwd: spawnCwd });
-      log(
+      failGate(
+        gate,
+        result.status,
         `[close-validation] ✖ ${gate.name} failed (exit ${result.status}) in ${spawnCwd}`,
       );
-      if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
-      break;
+      return;
     }
     log(`[close-validation] ✓ ${gate.name}`);
     recordIfActive(
@@ -363,23 +425,6 @@ export async function runCloseValidation({
       evidenceActive ? evidenceClock() - startedAt : 0,
     );
   }
-
-  // ── Phase 3: advisory projections ───────────────────────────────────
-  // Story #4776 — the projection layer's live call site. Deliberately
-  // outside the `ok` computation: a projected breach informs, it never
-  // fails a close.
-  if (failed.length === 0) {
-    await runAdvisoryProjections({
-      runProjections,
-      cwd: spawnCwd,
-      baseBranch,
-      storyBranch,
-      config,
-      log,
-    });
-  }
-
-  return { ok: failed.length === 0, failed, skipped };
 }
 
 /**

package/.agents/scripts/lib/crap-engine.js

@@ -1,5 +1,6 @@
 import escomplex from 'typhonjs-escomplex';
 import { coverageForMethodInEntry } from './coverage-utils.js';
+import { deriveMethodIdentities } from './crap-method-identity.js';
 
 /**
  * The two line coordinate systems a CRAP row's `startLine` can be expressed
@@ -47,6 +48,7 @@ export const COORDINATE_TRANSPILED = 'transpiled';
  * @param {((line: number) => number|null)|null} [mapLine]
  * @returns {Array<{
  *   method: string,
+ *   anonymous: boolean,
  *   startLine: number,
  *   cyclomatic: number,
  *   coverage: number|null,
@@ -78,8 +80,14 @@ function resolveCoordinate(rawStartLine, mapLine) {
 
 export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
   const methods = report?.methods ?? [];
+  // Identities are derived over the WHOLE method list, before any row is
+  // skipped, and read back by index (Story #4969). Deriving them from the
+  // surviving rows instead would let an unscorable method's absence shift its
+  // siblings' ordinals — reintroducing, through the back door, exactly the
+  // position dependence this replaces.
+  const identities = deriveMethodIdentities(methods);
   const rows = [];
-  for (const m of methods) {
+  for (const [i, m] of methods.entries()) {
     const rawStartLine = m?.lineStart;
     if (typeof rawStartLine !== 'number') continue;
     const { startLine, coordinateSystem } = resolveCoordinate(
@@ -93,7 +101,7 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
         : null;
     const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
     rows.push({
-      method: m.name,
+      ...identities[i],
       startLine,
       cyclomatic,
       coverage,
@@ -132,10 +140,16 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
  * so `requireCoverage: false` keeps meaning "score untested code" whenever a
  * real coverage run stands behind the verdict.
  *
- * `resolvedMethods` / `totalMethods` count the *join*, not the fill: a
- * method scored 0% because its coverage was unresolved counts as
- * unresolved. That is what makes them usable as a health signal for the
- * updater's fail-closed resolution-rate floor.
+ * **Unjoinable is not untested (Story #4901).** Both policies above are about
+ * a method whose coverage is *absent*; neither is about one whose coverage
+ * could not be **joined**. A transpiled `startLine` is the latter — not in
+ * the coordinate space the `fnMap` or the baseline is keyed against — so 0%
+ * is not a measurement but a number invented for it, and `crapFormula(c, 0)`
+ * is the maximal `c² + c`. Excluded under **either** policy, and counted.
+ *
+ * `resolvedMethods` / `totalMethods` count the *join*, not the fill, which is
+ * what makes them a health signal for the updater's fail-closed
+ * resolution-rate floor — so the exclusion is applied *after* both counters.
  *
  * @param {Array<object>} rawRows Rows from `methodRowsFromReport`.
  * @param {{requireCoverage?: boolean, coverageAvailable?: boolean}} [opts]
@@ -158,21 +172,25 @@ export function finalizeMethodRows(
     totalMethods += 1;
     const unresolved = mr.crap === null || mr.coverage === null;
     if (!unresolved) resolvedMethods += 1;
-    if (unresolved && (requireCoverage || !coverageAvailable)) {
+    // Unjoinable is not untested (Story #4901) — see the block comment above.
+    if (
+      mr.coordinateSystem === COORDINATE_TRANSPILED ||
+      (unresolved && (requireCoverage || !coverageAvailable))
+    ) {
       skippedMethodsNoCoverage += 1;
       continue;
     }
     const coverage = unresolved ? 0 : mr.coverage;
     const crap = unresolved ? crapFormula(mr.cyclomatic, 0) : mr.crap;
+    // Everything the scan decided is carried forward; this step overrides only
+    // what its own policy resolves. Spreading rather than re-listing each field
+    // is why the row's identity marker (Story #4969) and its provenance
+    // (Story #4866) survive the step without a line each to remember them —
+    // a hand-rebuilt row is how a marker silently stops reaching the baseline.
     rows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
+      ...mr,
       coverage,
       crap,
-      // Provenance survives the policy step (Story #4866): a row scored 0%
-      // under `requireCoverage: false` may still be carrying a transpiled
-      // coordinate, and the compare needs to know that before it keys on it.
       coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
     });
   }
@@ -203,6 +221,7 @@ export function finalizeMethodRows(
  *   original line resolver; see `methodRowsFromReport`.
  * @returns {Array<{
  *   method: string,
+ *   anonymous: boolean,
  *   startLine: number,
  *   cyclomatic: number,
  *   coverage: number|null,

package/.agents/scripts/lib/crap-method-identity.js

@@ -0,0 +1,153 @@
+/**
+ * crap-method-identity.js — order-independent identity for the methods an
+ * escomplex report describes (Story #4969).
+ *
+ * Split out of `crap-engine.js` deliberately. That module is the CRAP scoring
+ * kernel — parse, remap a line, join coverage, apply the formula — and naming
+ * a method is a different question from scoring one: it reads the shape of the
+ * scope tree and nothing about coverage or complexity. Keeping the walker here
+ * leaves the kernel's contract ("pure, no I/O, one method in, one score out")
+ * legible instead of half-buried under a tree traversal.
+ */
+
+/**
+ * The label `typhonjs-escomplex-commons` gives a function it cannot name
+ * (Story #4969).
+ *
+ * The `N` is a per-module counter incremented during the AST walk, so it
+ * numbers a function by its *position among its anonymous siblings* rather
+ * than by anything about the function itself. Inserting or deleting one
+ * anonymous function renumbers every later one in the file — and 34.6% of this
+ * repository's CRAP rows were keyed on exactly that. See
+ * `deriveMethodIdentities` for what replaces it.
+ */
+const ESCOMPLEX_ANON_LABEL_RE = /^<anon method-\d+>$/;
+
+/**
+ * True for a `method` value that is a derived anonymous identity rather than a
+ * name the source actually carries — either this module's `<anon …>` identity
+ * or escomplex's superseded ordinal label.
+ *
+ * @param {unknown} method
+ * @returns {boolean}
+ */
+export function isAnonymousMethodLabel(method) {
+  return typeof method === 'string' && method.startsWith('<anon ');
+}
+
+/**
+ * Coerce a method's escomplex line span into a usable numeric pair. A method
+ * missing either bound still has to take a deterministic place in the scope
+ * tree, so it collapses to a zero-width span rather than being dropped: an
+ * identity that varies with how the parser failed would be worse than one that
+ * is merely coarse.
+ *
+ * @param {{lineStart?: unknown, lineEnd?: unknown}} m
+ * @returns {{lineStart: number, lineEnd: number}}
+ */
+function spanOf(m) {
+  const lineStart = Number.isFinite(m?.lineStart) ? m.lineStart : 0;
+  const lineEnd = Number.isFinite(m?.lineEnd) ? m.lineEnd : lineStart;
+  return { lineStart, lineEnd: Math.max(lineStart, lineEnd) };
+}
+
+/**
+ * Give every method in an escomplex report an identity that does not depend on
+ * how many anonymous functions happen to precede it (Story #4969).
+ *
+ * **Named methods are untouched** — their identity is the name escomplex
+ * reported, exactly as before, so no named row is re-keyed by this change.
+ *
+ * **An anonymous method is identified by where it sits, not by when it was
+ * counted.** The identity is `<anon {scope path}>`, where the path is the
+ * chain of enclosing methods from the module down to the method itself. Each
+ * link contributes a name if it has one, otherwise its parameter list plus an
+ * ordinal among the siblings that share *that exact parent and that exact
+ * parameter list*:
+ *
+ * ```text
+ *   <anon (p)#0>                                        module-scope, first (p) arrow
+ *   <anon buildDefaultCrapScorer/(files,opts)#0>        inside a named function
+ *   <anon buildDefaultCrapScorer/(files,opts)#0/(r)#0>  inside that one
+ * ```
+ *
+ * **Why the parameter list and not the body.** The identity has to survive an
+ * edit *to* the method — a method that gains a branch must still be recognised
+ * as the same method, or a genuine complexity regression would read as a brand
+ * new function and score against the new-method ceiling instead of its own
+ * baseline. That rules out anything derived from the body: a source or
+ * normalized-AST hash re-keys the row on the very edit the gate exists to
+ * catch. A parameter list is stable across the edits CRAP measures, and it
+ * partitions same-scope siblings finely enough that the residual ordinal is
+ * almost always `#0`.
+ *
+ * **The residual.** Within one parent *and* one parameter list, siblings are
+ * still told apart by source order, so inserting a same-signature sibling
+ * *before* an existing one still shifts it. That residual is irreducible:
+ * anything that distinguishes two same-scope, same-signature functions has to
+ * read their bodies, and reading their bodies re-keys them on every edit. The
+ * blast radius drops from "every anonymous function in the file" to "the
+ * same-signature siblings of one scope".
+ *
+ * Emission order is load-bearing and guaranteed: escomplex walks the AST
+ * pre-order, so a method's ancestors are always emitted before it. That lets a
+ * single forward pass with an open-ancestor stack resolve every parent in
+ * O(n), and it makes the innermost enclosing method the most recent one still
+ * open.
+ *
+ * @param {Array<object>} methods `report.methods` from escomplex.
+ * @returns {Array<{method: string, anonymous: boolean}>} One entry per input
+ *   method, index-aligned with `methods` and spreadable straight onto a row.
+ *   The scope path itself stays internal — only the identity leaves.
+ */
+export function deriveMethodIdentities(methods) {
+  const identities = [];
+  /** @type {Array<{lineEnd: number, scopePath: string}>} */
+  const openAncestors = [];
+  /** Sibling counts keyed by `parent scope path` + `parameter list`. */
+  const ordinals = new Map();
+
+  for (const m of methods ?? []) {
+    const { lineStart, lineEnd } = spanOf(m);
+    // Close every ancestor whose span has ended before this method begins.
+    while (
+      openAncestors.length > 0 &&
+      openAncestors[openAncestors.length - 1].lineEnd < lineStart
+    ) {
+      openAncestors.pop();
+    }
+    const parentPath =
+      openAncestors.length > 0
+        ? openAncestors[openAncestors.length - 1].scopePath
+        : '';
+
+    const name = typeof m?.name === 'string' ? m.name : '';
+    let segment;
+    let anonymous;
+    if (name === '' || ESCOMPLEX_ANON_LABEL_RE.test(name)) {
+      const params = Array.isArray(m?.paramNames) ? m.paramNames : [];
+      const signature = `(${params.join(',')})`;
+      // NUL separates the two halves because it is the one character a scope
+      // path can never contain — a printable delimiter could be produced by a
+      // parameter name and silently merge two distinct buckets. Spelled as an
+      // escape: a literal NUL byte would make this file binary to git and grep.
+      const bucket = `${parentPath}\u0000${signature}`;
+      const ordinal = ordinals.get(bucket) ?? 0;
+      ordinals.set(bucket, ordinal + 1);
+      segment = `${signature}#${ordinal}`;
+      anonymous = true;
+    } else {
+      segment = name;
+      anonymous = false;
+    }
+
+    const scopePath = parentPath === '' ? segment : `${parentPath}/${segment}`;
+    identities.push({
+      method: anonymous ? `<anon ${scopePath}>` : name,
+      anonymous,
+    });
+    openAncestors.push({ lineEnd, scopePath });
+  }
+
+  return identities;
+}

package/.agents/scripts/lib/crap-utils.js

@@ -139,6 +139,12 @@ function projectCrapEnvelopeToLegacy(parsed) {
       ...(row.coordinateSystem === undefined
         ? {}
         : { coordinateSystem: row.coordinateSystem }),
+      // Story #4969, same reason as the stamps above: `anonymous` is a
+      // BASELINE fact. Dropping it here left every re-keyed row looking like
+      // an unmarked anonymous one, which is precisely the shape the
+      // `anon-identity-unstamped` axis fails closed — the projection would
+      // have manufactured the very defect the axis exists to catch.
+      ...(row.anonymous === undefined ? {} : { anonymous: row.anonymous }),
     })),
   };
 }
@@ -215,6 +221,7 @@ export function buildBaselineEnvelope({
       file: r.file,
       method: r.method,
       startLine: r.startLine,
+      ...(r.anonymous === undefined ? {} : { anonymous: r.anonymous }),
     })),
     tsTranspilerVersion,
   };
@@ -501,6 +508,9 @@ export async function scanAndScore({
       rows.push({
         file: item.relPath,
         method: mr.method,
+        // Story #4969: `method` may be a derived anonymous identity; the flag
+        // is what lets the persisted row say so.
+        anonymous: mr.anonymous === true,
         startLine: mr.startLine,
         cyclomatic: mr.cyclomatic,
         coverage: mr.coverage,
@@ -844,6 +854,9 @@ export async function scanAndScoreCombined({
       crapRows.push({
         file: item.relPath,
         method: mr.method,
+        // Story #4969: `method` may be a derived anonymous identity; the flag
+        // is what lets the persisted row say so.
+        anonymous: mr.anonymous === true,
         startLine: mr.startLine,
         cyclomatic: mr.cyclomatic,
         coverage: mr.coverage,