mandrel 2.25.0 → 2.26.0

package/.agents/scripts/acceptance-eval.js

@@ -41,10 +41,20 @@
  * tier along with the per-AC-cluster `--epic <id> --cluster <id>` mode that
  * scored an Epic `## Acceptance Table` against a `main..epic/<id>` diff.)
  *
+ * One gate call per round (Story #4951). A round may fan out into N parallel
+ * maker-blind cluster critics, but their per-cluster verdicts are merged by
+ * the caller into ONE verdict — `criteria[]` in acceptance-array order — and
+ * scored here exactly once. Invoking the gate per cluster instead would burn
+ * one Story-level round per cluster (distinct fingerprints defeat the replay
+ * guard) and race the `signals.ndjson` round ledger. `--expected-criteria`
+ * makes that contract enforceable: a partial (single-cluster) verdict is
+ * rejected before scoring, so the mistake costs no round.
+ *
  * CLI:
- *   --story <id>           Story ID (required).
- *   --verdict <path>       Path to the round's verdict JSON (required).
- *   --no-signal            Suppress the signal emit (tests).
+ *   --story <id>              Story ID (required).
+ *   --verdict <path>          Path to the round's verdict JSON (required).
+ *   --expected-criteria <n>   Reject a verdict not covering exactly n criteria.
+ *   --no-signal               Suppress the signal emit (tests).
  *
  * Stdout: a single JSON envelope
  *   { storyId, epicId, decision, round, cap, capReached, totalCriteria,
@@ -143,6 +153,7 @@ function parseCliArgs(argv) {
     options: {
       story: { type: 'string' },
       verdict: { type: 'string' },
+      'expected-criteria': { type: 'string' },
       'no-signal': { type: 'boolean', default: false },
     },
     strict: false,
@@ -151,10 +162,69 @@ function parseCliArgs(argv) {
   return {
     storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
     verdictPath: values.verdict ?? null,
+    expectedCriteria: values['expected-criteria'] ?? null,
     emitSignal: values['no-signal'] !== true,
   };
 }
 
+/**
+ * The merge contract, stated once so both the flag error and the coverage
+ * error name the same shape the caller has to produce.
+ */
+const MERGE_CONTRACT =
+  'One round = N parallel cluster critics -> ONE merged verdict -> ONE gate call: ' +
+  "merge every cluster's records into a single criteria[] in acceptance[] order, " +
+  'one per acceptance item, before scoring.';
+
+/**
+ * Resolve the optional `--expected-criteria` flag to a positive integer, or
+ * `null` when the flag is absent (which preserves the pre-#4951 behaviour
+ * exactly — no coverage assertion is made).
+ *
+ * Exported for tests.
+ *
+ * @param {string|null|undefined} raw
+ * @returns {number|null}
+ */
+export function resolveExpectedCriteria(raw) {
+  if (raw === null || raw === undefined) return null;
+  // Digits only. `Number.parseInt` stops at the first non-digit, so `4abc`
+  // resolved to 4 — a guard whose entire job is to reject a wrong-sized
+  // verdict was itself accepting a malformed count, and a typo'd `--expected-
+  // criteria` would then wave through a verdict of the wrong length.
+  const text = String(raw).trim();
+  const expected = /^\d+$/.test(text) ? Number(text) : Number.NaN;
+  if (!Number.isInteger(expected) || expected < 1) {
+    throw new Error(
+      `acceptance-eval: --expected-criteria must be a positive integer (the Story's acceptance[] count). ${MERGE_CONTRACT}`,
+    );
+  }
+  return expected;
+}
+
+/**
+ * Reject a verdict that does not cover exactly `expectedCriteria` criteria.
+ *
+ * Called **before** `runAcceptanceEval`, which is where the round ledger is
+ * read and appended — so a partial cluster verdict handed to the gate by
+ * mistake costs no round and can never escalate a `redraft` into a `block`.
+ *
+ * Exported for tests.
+ *
+ * @param {object} verdict — schema-validated verdict.
+ * @param {number|null} expectedCriteria — `null` disables the assertion.
+ * @returns {void}
+ */
+export function assertCriteriaCoverage(verdict, expectedCriteria) {
+  if (expectedCriteria === null) return;
+  const actual = Array.isArray(verdict?.criteria) ? verdict.criteria.length : 0;
+  if (actual === expectedCriteria) return;
+  throw new Error(
+    `acceptance-eval: verdict covers ${actual} criteria but --expected-criteria is ${expectedCriteria}. ` +
+      `${MERGE_CONTRACT} No round was consumed.`,
+  );
+}
+
 /**
  * Compose the operator-facing envelope and emit the per-criterion signal.
  *
@@ -294,11 +364,13 @@ export async function runAcceptanceEvalCli(
     runAcceptanceEvalImpl = runAcceptanceEval,
     logger = Logger,
   } = deps;
-  const { storyId, verdictPath, emitSignal } = parseCliArgs(argv);
+  const { storyId, verdictPath, expectedCriteria, emitSignal } =
+    parseCliArgs(argv);
+  const expected = resolveExpectedCriteria(expectedCriteria);
 
   if (!storyId) {
     throw new Error(
-      'Usage: node acceptance-eval.js --story <id> --verdict <path> [--no-signal]',
+      'Usage: node acceptance-eval.js --story <id> --verdict <path> [--expected-criteria <n>] [--no-signal]',
     );
   }
   if (!verdictPath) {
@@ -329,6 +401,11 @@ export async function runAcceptanceEvalCli(
 
   const verdict = validateVerdictImpl(parsed);
 
+  // Story #4951: a merged verdict must cover every acceptance[] item. This
+  // runs before the round ledger is touched, so a partial cluster verdict is
+  // a free mistake.
+  assertCriteriaCoverage(verdict, expected);
+
   // A verdict whose embedded storyId disagrees with the CLI flag is a
   // wiring error worth failing on, not a silent mismatch.
   if (Number.isInteger(verdict.storyId) && verdict.storyId !== storyId) {
@@ -372,12 +449,18 @@ runAsCli(import.meta.url, main, {
   source: 'acceptance-eval',
   usage: {
     invocation:
-      'node .agents/scripts/acceptance-eval.js --story <id> --verdict <path> [--no-signal]',
+      'node .agents/scripts/acceptance-eval.js --story <id> --verdict <path> [--expected-criteria <n>] [--no-signal]',
     summary:
       "Score an authored acceptance verdict against the Story's acceptance[] criteria and emit the bounded loop's proceed / redraft / block decision.",
     flags: [
       ['--story <id>', 'GitHub issue number of the Story (required).'],
       ['--verdict <path>', 'Path to the authored verdict JSON (required).'],
+      [
+        '--expected-criteria <n>',
+        'Reject — before scoring, consuming no round — a verdict whose criteria[] ' +
+          "length is not n. Pass the Story's acceptance[] count so a partial " +
+          'cluster verdict cannot be scored as the round.',
+      ],
       [
         '--no-signal',
         "Skip appending the per-criterion signal to the Story's signals ledger.",

package/.agents/scripts/audit-baselines.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+/**
+ * CLI: baseline hotspot engine for the `/audit-baselines` lens (Story #4902).
+ *
+ * Turns the committed `baselines/` folder into ranked hotspot clusters,
+ * gate-surface health signals, trend deltas, and floor-tightening headroom —
+ * the deterministic evidence half of a baseline review, so the lens spends
+ * its judgment on findings instead of re-deriving the numbers by hand.
+ *
+ * Read-only by contract: nothing under `baselines/` is written, and no test,
+ * coverage, or mutation suite is run. The only file this process creates is
+ * the envelope at `--out`.
+ *
+ * Exit 0 whenever evidence was assembled — findings are evidence, not a gate.
+ * A missing git history, absent friction ledger, or unresolvable import graph
+ * are reported as degradations and still exit 0. Only an unwritable `--out`
+ * (or a missing one) is a failure.
+ *
+ * Usage:
+ *   node .agents/scripts/audit-baselines.js --out temp/audit-baselines/envelope.json
+ */
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  DEFAULT_HOTSPOT_LIMIT,
+  runEngine,
+  summarize,
+} from './lib/audit-baselines/engine.js';
+import { DEFAULT_TOP_N } from './lib/audit-baselines/outliers.js';
+import { buildBaselineSchemaAjv } from './lib/baseline-schema-registry.js';
+import { defineFlags } from './lib/cli-args.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+const ENVELOPE_SCHEMA_FILE = 'audit-baselines-envelope.schema.json';
+
+const FLAG_SPEC = {
+  out: { type: 'string' },
+  cwd: { type: 'string' },
+  'top-n': { type: 'integer' },
+  'hotspot-limit': { type: 'integer' },
+  'trend-depth': { type: 'integer' },
+};
+
+/**
+ * Validate the envelope against its shipped schema through the shared
+ * baseline schema registry. Throws with the AJV error list on mismatch —
+ * a malformed envelope is an engine bug, not evidence.
+ *
+ * @param {object} envelope
+ * @returns {void}
+ */
+export function assertEnvelope(envelope) {
+  const validate = buildBaselineSchemaAjv().getSchema(ENVELOPE_SCHEMA_FILE);
+  if (!validate) {
+    throw new Error(
+      `[audit-baselines] ${ENVELOPE_SCHEMA_FILE} is not registered in the baseline schema registry`,
+    );
+  }
+  if (validate(envelope)) return;
+  const detail = (validate.errors ?? [])
+    .map((e) => `${e.instancePath || '/'} ${e.message}`)
+    .join('; ');
+  throw new Error(
+    `[audit-baselines] envelope failed schema validation: ${detail}`,
+  );
+}
+
+/**
+ * Assemble the envelope, validate it, write it, and return the stdout
+ * summary. Exported so tests drive the whole pipeline without spawning.
+ *
+ * @param {{ argv?: string[], cwd?: string, stdout?: { write: (s: string) => void } }} [opts]
+ * @returns {Promise<number>} exit code
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+} = {}) {
+  const { values } = defineFlags(FLAG_SPEC, argv);
+  if (!values.out) {
+    throw new Error('[audit-baselines] --out <path> is required');
+  }
+  const repoRoot = path.resolve(values.cwd ?? cwd);
+  const outPath = path.resolve(repoRoot, values.out);
+
+  const envelope = runEngine({
+    cwd: repoRoot,
+    topN: values.topN ?? DEFAULT_TOP_N,
+    hotspotLimit: values.hotspotLimit ?? DEFAULT_HOTSPOT_LIMIT,
+    trendDepth: values.trendDepth ?? 5,
+  });
+  assertEnvelope(envelope);
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(envelope, null, 2)}\n`, 'utf8');
+
+  stdout.write(`${JSON.stringify(summarize(envelope, outPath), null, 2)}\n`);
+  return 0;
+}
+
+runAsCli(import.meta.url, async () => runCli(), {
+  source: 'audit-baselines',
+  propagateExitCode: true,
+  errorPrefix: '[audit-baselines] ❌ Fatal error',
+  usage: {
+    invocation:
+      'node .agents/scripts/audit-baselines.js --out <path> [--cwd <dir>] [--top-n <n>] [--hotspot-limit <n>] [--trend-depth <n>]',
+    summary:
+      'Read-only baseline hotspot engine: extract bounded per-gate outliers, cluster them per file, rank by severity x churn x import in-degree x friction, and report gate-surface health, trend deltas, and floor headroom.',
+    flags: [
+      ['--out <path>', 'Write the JSON envelope here (required).'],
+      ['--cwd <dir>', 'Repository root to analyse (default: cwd).'],
+      [
+        '--top-n <n>',
+        `Outlier rows extracted per gate (default: ${DEFAULT_TOP_N}).`,
+      ],
+      [
+        '--hotspot-limit <n>',
+        `Hotspot clusters emitted (default: ${DEFAULT_HOTSPOT_LIMIT}).`,
+      ],
+      ['--trend-depth <n>', 'Baseline commits sampled per kind (default: 5).'],
+    ],
+    notes: [
+      'Never writes under baselines/ and never runs a test, coverage, or mutation suite.',
+      'Exit codes:\n  0  evidence assembled (including every degraded input)\n  1  the envelope could not be built or written',
+    ],
+  },
+});

package/.agents/scripts/check-arch-cycles.js

@@ -37,16 +37,19 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  buildGraph,
+  collectJsFiles,
+  DEFAULT_ROOTS,
+  parseRelativeImports,
+} from './lib/import-graph.js';
 
-/**
- * Default scan roots making up the project's distributed surface — the
- * directories published to npm via `package.json` `files[]`. Resolving
- * them into one graph (relativized against the repo root) means a cycle
- * crossing two roots is visible to `findCycles`.
- *
- * @type {string[]}
- */
-export const DEFAULT_ROOTS = [path.join('.agents', 'scripts'), 'bin', 'lib'];
+// The import-graph builder itself lives in `lib/import-graph.js` (Story
+// #4902) so `audit-baselines.js` can rank hotspots by import in-degree
+// against the same graph this ratchet detects cycles in. Re-exported here
+// because this module's named exports are its unit-test surface and its
+// documented contract; the behaviour is unchanged by the move.
+export { buildGraph, collectJsFiles, DEFAULT_ROOTS, parseRelativeImports };
 
 /**
  * Parse argv for `--baseline <path>`, `--root <path>`, and `--json`.
@@ -80,90 +83,6 @@ export function parseArgv(argv = []) {
   return { baselinePath, rootPath, json };
 }
 
-/**
- * Recursively collect `.js` files under `rootDir`, skipping
- * `node_modules`. Returns absolute paths, sorted for determinism.
- *
- * @param {string} rootDir
- * @returns {string[]}
- */
-export function collectJsFiles(rootDir) {
-  const out = [];
-  const walk = (dir) => {
-    let entries;
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      if (entry.name === 'node_modules') continue;
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(full);
-      } else if (entry.isFile() && entry.name.endsWith('.js')) {
-        out.push(full);
-      }
-    }
-  };
-  walk(rootDir);
-  return out.sort();
-}
-
-const IMPORT_RE = /from\s+['"](\.\.?\/[^'"]+\.js)['"]/g;
-
-/**
- * Pure helper: extract relative static-import specifiers from source text.
- *
- * @param {string} source
- * @returns {string[]}
- */
-export function parseRelativeImports(source) {
-  const specs = [];
-  for (const m of source.matchAll(IMPORT_RE)) {
-    specs.push(m[1]);
-  }
-  return specs;
-}
-
-/**
- * Build a directed import graph over the given files. Node identity is the
- * file path relative to `rootDir`, posix-separated, so the graph (and any
- * cycles found in it) serializes identically across platforms. Edges that
- * resolve outside the scanned file set are dropped.
- *
- * @param {string[]} files absolute paths
- * @param {string} rootDir
- * @param {{ readFile?: (p: string) => string }} [opts]
- * @returns {Map<string, string[]>}
- */
-export function buildGraph(files, rootDir, { readFile } = {}) {
-  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
-  const toId = (abs) => path.relative(rootDir, abs).split(path.sep).join('/');
-  const idSet = new Set(files.map(toId));
-  const graph = new Map();
-  for (const file of files) {
-    const id = toId(file);
-    let source;
-    try {
-      source = read(file);
-    } catch {
-      graph.set(id, []);
-      continue;
-    }
-    const edges = [];
-    for (const spec of parseRelativeImports(source)) {
-      const target = path
-        .relative(rootDir, path.resolve(path.dirname(file), spec))
-        .split(path.sep)
-        .join('/');
-      if (idSet.has(target) && target !== id) edges.push(target);
-    }
-    graph.set(id, [...new Set(edges)].sort());
-  }
-  return graph;
-}
-
 /**
  * Pure helper: rotate a cycle (array of module ids, no repeated terminal
  * element) so it starts at its lexicographically-smallest member. The same

package/.agents/scripts/check-baseline-drift.js

@@ -118,21 +118,34 @@ export async function runCheckBaselineDrift({
   return { exitCode: run.ok ? 0 : 1, output };
 }
 
+/**
+ * Run the drift check and *return* its exit code rather than calling
+ * `process.exit()` — this CLI prints one row per drifted baseline entry
+ * full-scope, so its report is exactly the kind of payload that outgrows the
+ * 64 KiB pipe buffer under a `| tee`. `process.exit()` terminates before a
+ * queued async pipe write drains, silently truncating it (Story #4783, the
+ * same defect `check-baselines.js` carried). Handing the code back lets
+ * `runAsCli`'s `propagateExitCode` path settle it through
+ * `settleCli`/`flushStdio` instead. The 0/1/2 contract documented at the top
+ * of this file is unchanged — only *when* the process leaves is.
+ *
+ * @returns {Promise<number>} 0 no drift, 1 drift detected, 2 could not run.
+ */
 async function main() {
   let result;
   try {
     result = await runCheckBaselineDrift({ argv: process.argv.slice(2) });
   } catch (err) {
     process.stdout.write(`${err?.message ?? String(err)}\n`);
-    process.exit(2);
-    return;
+    return 2;
   }
   process.stdout.write(`${result.output}\n`);
-  process.exit(result.exitCode);
+  return result.exitCode;
 }
 
 runAsCli(import.meta.url, main, {
   source: 'check-baseline-drift',
   usage: HELP_TEXT,
   exitCode: 2,
+  propagateExitCode: true,
 });

package/.agents/scripts/check-baselines.js

@@ -65,6 +65,22 @@ export {
   selectEnabledGates,
 };
 
+/**
+ * Run the dispatcher and *return* its exit code rather than calling
+ * `process.exit()`.
+ *
+ * The return is load-bearing (Story #4783's defect, reintroduced here):
+ * `process.exit()` terminates before a queued async pipe write drains, so a
+ * full `--gate coverage` report — a quarter of a megabyte of JSON — arrived
+ * truncated at the 64 KiB pipe boundary under the `| tee` in CI's coverage
+ * step, while still exiting 0. Handing the code back to `runAsCli`'s
+ * `propagateExitCode` path settles it through `settleCli`/`flushStdio`
+ * instead, which assigns `process.exitCode` and lets Node terminate once
+ * stdout has drained. The 0/1/2/3/4 contract in `lib/baselines/exit-codes.js`
+ * is unchanged — only *when* the process leaves is.
+ *
+ * @returns {Promise<number>} An exit code from the `EXIT_*` contract.
+ */
 async function main() {
   let result;
   try {
@@ -74,14 +90,14 @@ async function main() {
     process.stdout.write(
       `${JSON.stringify({ schemaVersion: '1', error: message }, null, 2)}\n`,
     );
-    process.exit(EXIT_CONFIG);
-    return;
+    return EXIT_CONFIG;
   }
   process.stdout.write(`${result.output}\n`);
-  process.exit(result.exitCode);
+  return result.exitCode;
 }
 
 runAsCli(import.meta.url, main, {
   source: 'check-baselines',
   usage: HELP_TEXT,
+  propagateExitCode: true,
 });