mandrel 2.35.0 → 2.37.0

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

@@ -35,6 +35,7 @@ import {
   resolveCyclomaticPolicy,
   scanCyclomatic,
 } from './lib/cyclomatic-ceiling.js';
+import { resolveScanScope } from './lib/cyclomatic-scope.js';
 
 /**
  * Parse `--baseline <path>`, `--json`, and `--update`.
@@ -82,6 +83,86 @@ function loadCyclomaticBaseline(baselinePath) {
   }
 }
 
+/**
+ * `--update`: rewrite the baseline from the current (whole-tree) scan. The
+ * sanctioned motion after a deliberate refactor lands, and the only way the
+ * recorded breach count is allowed to rise.
+ *
+ * @param {{ scan: object, ceiling: number, baselinePath: string, writeFileImpl: Function, stdout: { write: (s: string) => void } }} args
+ * @returns {number} Always 0 — writing a baseline cannot fail the ratchet.
+ */
+function writeUpdatedBaseline({
+  scan,
+  ceiling,
+  baselinePath,
+  writeFileImpl,
+  stdout,
+}) {
+  const envelope = buildCyclomaticEnvelope({ rows: scan.rows, ceiling });
+  writeFileImpl(baselinePath, `${JSON.stringify(envelope, null, 2)}\n`);
+  stdout.write(
+    `[cyclomatic] wrote ${scan.rows.length} breach row(s) at ceiling c=${ceiling} to ${baselinePath}\n`,
+  );
+  return 0;
+}
+
+/**
+ * `--json`: the machine-readable comparison envelope.
+ *
+ * @param {{ policy: object, baseline: object|null, baselineRows: Array<object>, baselinePath: string, scan: object, diff: object, exitCode: number }} args
+ * @returns {string}
+ */
+function renderJsonReport({
+  policy,
+  baseline,
+  baselineRows,
+  baselinePath,
+  scan,
+  diff,
+  exitCode,
+}) {
+  return `${JSON.stringify(
+    {
+      kind: 'cyclomatic-report',
+      ceiling: policy.mustFix,
+      flag: policy.flag,
+      baselinePath,
+      baselineCeiling: baseline?.ceiling ?? null,
+      scannedFiles: scan.scannedFiles,
+      parseErrors: scan.parseErrors,
+      baselineRows,
+      currentRows: scan.rows,
+      ...diff,
+      exitCode,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * Announce a baseline the comparison cannot fully trust: absent, or recorded
+ * at a ceiling the config no longer uses. Both are warnings rather than
+ * failures — the diff still runs, and staying silent is what would let an
+ * operator read a meaningless verdict as a clean one.
+ *
+ * @param {{ baseline: object|null, mustFix: number, baselinePath: string, stderr: { write: (s: string) => void } }} args
+ * @returns {void}
+ */
+function warnAboutBaseline({ baseline, mustFix, baselinePath, stderr }) {
+  if (!baseline) {
+    stderr.write(
+      `[cyclomatic] ⚠ baseline not found at ${baselinePath} — treating as empty\n`,
+    );
+    return;
+  }
+  if (typeof baseline.ceiling === 'number' && baseline.ceiling !== mustFix) {
+    stderr.write(
+      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the configured cyclomaticMustFix is c=${mustFix} — re-run with --update\n`,
+    );
+  }
+}
+
 /**
  * Top-level CLI entry. Exported so tests can drive the whole pipeline through
  * the injected seams below without spawning a process.
@@ -109,75 +190,64 @@ export async function runCli({
   writeFileImpl = (p, data) => fs.writeFileSync(p, data),
 } = {}) {
   const { baselinePath, json, update } = parseArgv(argv);
-  const quality = getQuality(resolveConfigImpl({ cwd }));
+  const config = resolveConfigImpl({ cwd });
+  const quality = getQuality(config);
   const policy = resolveCyclomaticPolicy(quality);
   const resolvedBaselinePath = path.resolve(
     cwd,
     baselinePath ?? DEFAULT_CYCLOMATIC_BASELINE,
   );
 
+  // Read the baseline before scanning: its rows are half the diff scope
+  // (Story #5109). `--update` rewrites the baseline from the whole tree, and
+  // `BASELINE_SCOPE=full` is the operator's explicit "re-derive everything",
+  // so both opt out of scoping entirely.
+  const baseline = loadBaselineImpl(resolvedBaselinePath);
+  const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
+  const scopeFiles = resolveScanScope({ cwd, config, update, baselineRows });
+
   const scan = scanImpl({
     targetDirs: policy.targetDirs,
     ignoreGlobs: policy.ignoreGlobs,
     ceiling: policy.mustFix,
     cwd,
+    scopeFiles,
   });
 
   if (update) {
-    const envelope = buildCyclomaticEnvelope({
-      rows: scan.rows,
+    return writeUpdatedBaseline({
+      scan,
       ceiling: policy.mustFix,
+      baselinePath: resolvedBaselinePath,
+      writeFileImpl,
+      stdout,
     });
-    writeFileImpl(
-      resolvedBaselinePath,
-      `${JSON.stringify(envelope, null, 2)}\n`,
-    );
-    stdout.write(
-      `[cyclomatic] wrote ${scan.rows.length} breach row(s) at ceiling c=${policy.mustFix} to ${resolvedBaselinePath}\n`,
-    );
-    return 0;
   }
 
-  const baseline = loadBaselineImpl(resolvedBaselinePath);
-  const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
   const diff = diffCyclomaticRows(baselineRows, scan.rows);
   const exitCode = diff.added.length + diff.worsened.length > 0 ? 1 : 0;
 
   if (json) {
     stdout.write(
-      `${JSON.stringify(
-        {
-          kind: 'cyclomatic-report',
-          ceiling: policy.mustFix,
-          flag: policy.flag,
-          baselinePath: resolvedBaselinePath,
-          baselineCeiling: baseline?.ceiling ?? null,
-          scannedFiles: scan.scannedFiles,
-          parseErrors: scan.parseErrors,
-          baselineRows,
-          currentRows: scan.rows,
-          ...diff,
-          exitCode,
-        },
-        null,
-        2,
-      )}\n`,
+      renderJsonReport({
+        policy,
+        baseline,
+        baselineRows,
+        baselinePath: resolvedBaselinePath,
+        scan,
+        diff,
+        exitCode,
+      }),
     );
     return exitCode;
   }
 
-  if (!baseline) {
-    stderr.write(
-      `[cyclomatic] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
-    );
-  } else if (
-    typeof baseline.ceiling === 'number' &&
-    baseline.ceiling !== policy.mustFix
-  ) {
-    stderr.write(
-      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the configured cyclomaticMustFix is c=${policy.mustFix} — re-run with --update\n`,
-    );
-  }
+  warnAboutBaseline({
+    baseline,
+    mustFix: policy.mustFix,
+    baselinePath: resolvedBaselinePath,
+    stderr,
+  });
   stdout.write('\n--- cyclomatic preview ---\n');
   stdout.write(`${renderCyclomaticDiff(diff, policy.mustFix)}\n`);
   return exitCode;

package/.agents/scripts/check-doc-links.js

@@ -325,6 +325,22 @@ function stripAnchorAndQuery(target) {
   return t;
 }
 
+// Percent-decode a link target's path portion (Story #5090). A correctly
+// encoded Markdown destination escapes URL-reserved characters — a
+// file-based router's `[token]` segment is written `%5Btoken%5D`, the form
+// CommonMark renderers require — but the filesystem knows only the decoded
+// name. The decode is one-way and total: a malformed escape (`%zz`) degrades
+// to the raw string instead of throwing `URIError`, so an undecodable target
+// is resolved exactly as it was before.
+function decodeLinkPath(pathOnly) {
+  if (!pathOnly.includes('%')) return pathOnly;
+  try {
+    return decodeURIComponent(pathOnly);
+  } catch {
+    return pathOnly;
+  }
+}
+
 // --- Slash-token extraction ------------------------------------------------
 
 // Tokens look like `/<lowercase-alphanum-with-hyphens>`. We exclude tokens
@@ -394,8 +410,13 @@ export function checkFile(absPath, repoRoot) {
   // 2. Relative-link resolution.
   for (const { target, line } of extractLinks(masked)) {
     if (isExternalOrInternalAnchor(target)) continue;
-    const pathOnly = stripAnchorAndQuery(target);
-    if (!pathOnly) continue; // pure anchor that survived earlier check
+    const rawPathOnly = stripAnchorAndQuery(target);
+    if (!rawPathOnly) continue; // pure anchor that survived earlier check
+    // Decode AFTER anchor/query stripping — so an escaped `%23` cannot
+    // collapse into an anchor delimiter and truncate the target — and BEFORE
+    // resolution, so the payload-boundary branch below reports the decoded
+    // path rather than the escaped one.
+    const pathOnly = decodeLinkPath(rawPathOnly);
     let resolved;
     if (pathOnly.startsWith('/')) {
       // Treat root-absolute paths as repo-root relative.

package/.agents/scripts/check-generated-validator.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * CLI: keep the committed `.agentrc` validator in step with its schema
+ * (Story #5109).
+ *
+ * `getAgentrcValidator()` used to compile `AGENTRC_SCHEMA` with AJV in every
+ * process that touched configuration — 36 of the 79 entry scripts, at ~35 ms
+ * each — to produce a function that is a pure derivative of a literal already
+ * committed to the repository. The compile is now done **once, here**, and its
+ * output is committed as `lib/generated/agentrc-validator.js`; the runtime
+ * imports that module and only falls back to a live compile behind
+ * `MANDREL_AGENTRC_VALIDATOR=dynamic`.
+ *
+ * A generated artifact that nothing re-derives is a lie waiting to happen, so
+ * this script joins the standalone-ratchet family — `check-arch-cycles.js`,
+ * `check-cyclomatic.js`, `check-dead-exports.js` — and follows their contract:
+ *
+ *   - `--check` regenerates in memory and compares against the committed
+ *     file. Exit 0 when they agree, exit 1 (naming the fix) when they do not.
+ *     `npm run lint` runs this, so a schema edit that skips regeneration is
+ *     refused before it can ship a validator that accepts the wrong config.
+ *   - No flag rewrites the file. That is the sanctioned motion after a
+ *     deliberate schema change.
+ *
+ * The comparison is over the exact bytes, which is what makes the gate
+ * meaningful: AJV's standalone emit is deterministic for a given schema and
+ * AJV version, so a diff means either the schema moved or the compiler did,
+ * and both demand a fresh artifact.
+ */
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import { AGENTRC_SCHEMA } from './lib/config-settings-schema.js';
+
+const require = createRequire(import.meta.url);
+
+/** Repo-relative home of the committed artifact. */
+export const GENERATED_VALIDATOR_PATH =
+  '.agents/scripts/lib/generated/agentrc-validator.js';
+
+/** The command that rewrites it — quoted in every failure message. */
+const REGEN_COMMAND = 'npm run validator:gen';
+
+/**
+ * AJV options for the generated validator.
+ *
+ * `allErrors: true` MUST match the runtime fallback in
+ * `config-settings-schema.js#getAgentrcValidator` — it is the difference
+ * between reporting one error and reporting all of them, and every caller
+ * that renders `validate.errors` would change behaviour if the two diverged.
+ * `code.source` is what makes the instance emittable; `code.esm` selects the
+ * ES-module emit. Neither touches validation semantics.
+ */
+const AJV_OPTIONS = Object.freeze({
+  allErrors: true,
+  code: { source: true, esm: true },
+});
+
+/**
+ * Banner prepended to the emitted module.
+ *
+ * The `createRequire` shim is load-bearing: AJV's `esm` emit still reaches for
+ * its shared runtime helpers (`ajv/dist/runtime/*`) with `require(...)`, which
+ * is not defined inside an ES module. Handing the generated code a real
+ * `require` is the smallest fix that keeps the emit verbatim — rewriting those
+ * calls into imports would mean re-deriving AJV's own codegen by hand, and
+ * would silently rot the next time it changes shape.
+ *
+ * The coverage pragma matches `config-settings-schema.js`: generated code has
+ * no branches anyone authored, so a coverage figure over it measures nothing.
+ */
+const BANNER = `/* node:coverage ignore file -- generated artifact; see check-generated-validator.js */
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Precompiled AJV validator for \`AGENTRC_SCHEMA\`
+ * (.agents/scripts/lib/config-settings-schema.js), emitted by
+ * .agents/scripts/check-generated-validator.js.
+ *
+ * Regenerate with \`${REGEN_COMMAND}\`; \`npm run lint\` fails when this file
+ * and the schema disagree.
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+`;
+
+/**
+ * Emit the standalone validator source for `AGENTRC_SCHEMA`.
+ *
+ * Exported so the parity test can assert the committed artifact and a fresh
+ * emit agree without shelling out to this CLI.
+ *
+ * @returns {string} Complete module source, newline-terminated.
+ */
+export function generateValidatorSource() {
+  const ajvModule = require('ajv');
+  const Ajv = ajvModule.default ?? ajvModule;
+  const standaloneModule = require('ajv/dist/standalone');
+  const standaloneCode = standaloneModule.default ?? standaloneModule;
+  const ajv = new Ajv(AJV_OPTIONS);
+  const validate = ajv.compile(AGENTRC_SCHEMA);
+  const body = standaloneCode(ajv, validate);
+  return `${BANNER}\n${body.trim()}\n`;
+}
+
+/**
+ * Read the committed artifact, or `null` when it is absent.
+ *
+ * @param {string} absPath
+ * @returns {string | null}
+ */
+function readCommitted(absPath) {
+  try {
+    return fs.readFileSync(absPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive both modes through the
+ * injected seams rather than by spawning a process.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ *   generateImpl?: () => string,
+ *   writeFileImpl?: (p: string, data: string) => void,
+ * }} [opts]
+ * @returns {number} 0 = in step (or written); 1 = stale artifact.
+ */
+export function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  generateImpl = generateValidatorSource,
+  writeFileImpl = (p, data) => fs.writeFileSync(p, data),
+} = {}) {
+  const checkOnly = argv.includes('--check');
+  const absPath = path.resolve(cwd, GENERATED_VALIDATOR_PATH);
+  const expected = generateImpl();
+
+  if (!checkOnly) {
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    writeFileImpl(absPath, expected);
+    stdout.write(
+      `[generated-validator] wrote ${expected.length} bytes to ${GENERATED_VALIDATOR_PATH}\n`,
+    );
+    return 0;
+  }
+
+  const actual = readCommitted(absPath);
+  if (actual === null) {
+    stderr.write(
+      `[generated-validator] ❌ ${GENERATED_VALIDATOR_PATH} is missing — run \`${REGEN_COMMAND}\`\n`,
+    );
+    return 1;
+  }
+  if (actual !== expected) {
+    stderr.write(
+      `[generated-validator] ❌ ${GENERATED_VALIDATOR_PATH} is stale against AGENTRC_SCHEMA ` +
+        `(committed ${actual.length} bytes, regenerated ${expected.length}) — run \`${REGEN_COMMAND}\`\n`,
+    );
+    return 1;
+  }
+  stdout.write(
+    `[generated-validator] ✅ ${GENERATED_VALIDATOR_PATH} is in step with AGENTRC_SCHEMA\n`,
+  );
+  return 0;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'generated-validator',
+  propagateExitCode: true,
+  errorPrefix: '[generated-validator] ❌ Fatal error',
+  usage: {
+    invocation: 'node .agents/scripts/check-generated-validator.js [--check]',
+    summary:
+      'Regenerate the committed AJV validator for `AGENTRC_SCHEMA`, or (with --check) fail when the committed artifact is stale against the schema.',
+    flags: [
+      [
+        '--check',
+        'Compare only: exit 1 when the committed artifact differs from a fresh emit. Writes nothing.',
+      ],
+    ],
+    notes: [
+      'Exit codes:\n  0  artifact written, or already in step\n  1  committed artifact is missing or stale',
+      `Regenerate with \`${REGEN_COMMAND}\`. The runtime falls back to a live AJV compile when MANDREL_AGENTRC_VALIDATOR=dynamic.`,
+    ],
+  },
+});

package/.agents/scripts/check-lifecycle-lint.js

@@ -78,6 +78,7 @@ import { fileURLToPath } from 'node:url';
 
 import { runAsCli } from './lib/cli-utils.js';
 import { walkFilesByExtension } from './lib/fs-walk.js';
+import { stripJsComments } from './lib/source-text/strip-js-comments.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -162,73 +163,6 @@ export function findPromiseAllViolations(
   return violations;
 }
 
-/**
- * Strip block (`/* … *​/`) and line (`// …`) comments from a source
- * string. Pure — exported for tests so the comment-stripping contract
- * is explicit. Defends against the corner case where the literal
- * `'gh pr merge'` appears INSIDE a justification comment at the
- * deletion site (Story #2253 deliberately leaves a prose explanation
- * referencing the removed CLI call).
- *
- * The implementation is a tiny state machine rather than a regex so it
- * correctly handles the (legal) case of a string literal containing
- * `//` or `/​*` characters.
- *
- * @param {string} src
- * @returns {string} source with comments replaced by spaces (line
- *   numbers preserved so violations report the original line).
- */
-export function stripComments(src) {
-  let out = '';
-  let i = 0;
-  const n = src.length;
-  while (i < n) {
-    const ch = src[i];
-    const nx = src[i + 1];
-    // line comment
-    if (ch === '/' && nx === '/') {
-      while (i < n && src[i] !== '\n') {
-        i += 1;
-      }
-      continue;
-    }
-    // block comment
-    if (ch === '/' && nx === '*') {
-      i += 2;
-      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) {
-        // preserve newlines so line numbers in violation reports stay
-        // aligned with the original file.
-        if (src[i] === '\n') out += '\n';
-        i += 1;
-      }
-      i += 2; // skip closing */
-      continue;
-    }
-    // string literal — copy through unchanged (we WANT to keep these
-    // so Rule 3 can flag them).
-    if (ch === '"' || ch === "'" || ch === '`') {
-      const quote = ch;
-      out += ch;
-      i += 1;
-      while (i < n) {
-        const c = src[i];
-        out += c;
-        if (c === '\\' && i + 1 < n) {
-          out += src[i + 1];
-          i += 2;
-          continue;
-        }
-        i += 1;
-        if (c === quote) break;
-      }
-      continue;
-    }
-    out += ch;
-    i += 1;
-  }
-  return out;
-}
-
 /**
  * Rule 3 enforcement (Story #2253 / Task #2255, Epic #2172 review
  * High-1). Returns an array of `{ file, line, hint }` violations for
@@ -263,7 +197,7 @@ export function findMergeLockoutViolations(
 
     const raw = read(file, 'utf8');
     const rawLines = raw.split('\n');
-    const stripped = stripComments(raw);
+    const stripped = stripJsComments(raw);
     const lines = stripped.split('\n');
     for (let i = 0; i < lines.length; i += 1) {
       const line = lines[i];

package/.agents/scripts/check-schema-references.js

@@ -88,6 +88,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
+import { stripJsComments } from './lib/source-text/strip-js-comments.js';
 
 /** Schema root, relative to the repository root. */
 const SCHEMA_ROOT = path.join('.agents', 'schemas');
@@ -114,33 +115,6 @@ const EXEMPTION_KEY = 'x-mandrel-uncompiled';
  */
 const COMPUTED_PATH_RE = /\$\{[^}]*\}\.schema\.json/;
 
-/** Block comments, including the JSDoc prose every module here opens with. */
-const BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
-
-/**
- * Line comments. Anchored to start-of-line or whitespace so a `//` inside a
- * URL (`http://…`) is left alone — truncating that line could delete a real
- * reference sitting after it.
- */
-const LINE_COMMENT_RE = /(^|\s)\/\/[^\n]*/g;
-
-/**
- * Strip comments from a source before matching.
- *
- * Prose is not a compile. This module's own header names
- * `friction-event.schema.json` a dozen times while compiling nothing, and
- * every schema-loading module documents the path it loads directly above the
- * line that loads it — matching raw text would let a gate certify itself and
- * would count a docblock as enforcement, which is precisely the confusion
- * Story #4938 exists to end.
- *
- * @param {string} text raw source
- * @returns {string} source with comment bodies removed
- */
-function stripComments(text) {
-  return text.replace(BLOCK_COMMENT_RE, ' ').replace(LINE_COMMENT_RE, '$1');
-}
-
 /**
  * Parse argv. Exported so a unit test can pin the parser without spawning.
  *
@@ -194,7 +168,7 @@ function walk(dir, extensions, acc = []) {
 function readSources(root) {
   return walk(root, JS_EXTENSIONS).map((file) => ({
     rel: path.relative(root, file),
-    text: stripComments(fs.readFileSync(file, 'utf8')),
+    text: stripJsComments(fs.readFileSync(file, 'utf8')),
   }));
 }
 

package/.agents/scripts/drain-pending-cleanup.js

@@ -39,6 +39,18 @@ const progress = Logger.createProgress('drain-pending-cleanup', {
   stderr: false,
 });
 
+/**
+ * The escalation posture, as a real boolean. `allowNegative` resolves
+ * `--no-escalate` to boolean `false`, but under `strict: false` the other
+ * documented spelling `--escalate=false` arrives as the *string* `'false'`,
+ * which is truthy while `forceDrainPendingCleanup` gates on `!escalate`.
+ * Both must reach the engine as a boolean or the flag is advertised and inert.
+ *
+ * @param {boolean|string|undefined} value
+ * @returns {boolean}
+ */
+const escalateFrom = (value) => value !== false && value !== 'false';
+
 /**
  * The drain core, extracted from the CLI shell so the whole decision table —
  * empty manifest, dry-run report, drain + escalate reporting — is reachable
@@ -83,6 +95,11 @@ export async function runDrainPendingCleanup(
       'worktree-root': { type: 'string' },
     },
     strict: false,
+    // `node:util.parseArgs` honours a `--no-<flag>` spelling ONLY when this is
+    // set. Without it `--no-escalate` landed in `values['no-escalate']` and
+    // left `values.escalate` at its `true` default, so the documented passive
+    // drain performed the forced removal it promises to suppress.
+    allowNegative: true,
   });
 
   const config = resolveConfigImpl();
@@ -126,7 +143,7 @@ export async function runDrainPendingCleanup(
     repoRoot: projectRoot,
     worktreeRoot,
     git: gitImpl,
-    escalate: values.escalate,
+    escalate: escalateFrom(values.escalate),
     logger: {
       info: (m) => progressImpl('DRAIN', m),
       warn: (m) => progressImpl('DRAIN', `⚠️ ${m}`),

package/.agents/scripts/git-cleanup.js

@@ -64,6 +64,7 @@ import {
   probeMergedPr,
   refExists,
 } from './lib/orchestration/git-cleanup/phases/git-probes.js';
+import { probeAncestry } from './lib/orchestration/git-cleanup/phases/merged-tip.js';
 import { parseCleanupArgs } from './lib/orchestration/git-cleanup/phases/parse-args.js';
 import {
   executePrune,
@@ -110,6 +111,7 @@ export {
   planFastForward,
   planStashes,
   probeAllPrs,
+  probeAncestry,
   probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,

package/.agents/scripts/lib/baselines/components.js

@@ -19,11 +19,41 @@
 // the literal `*` are treated as the whole-repo rollup and always match
 // every row regardless of declared globs.
 
-import { minimatch } from 'minimatch';
+import { Minimatch } from 'minimatch';
 
 /** The default components map, used when a gate omits `components`. */
 const DEFAULT_COMPONENTS = Object.freeze({ '*': Object.freeze(['**']) });
 
+/**
+ * Compiled-matcher cache for `groupRows`, keyed on the glob string.
+ *
+ * `groupRows` is called once per gate over the whole baseline row set — tens
+ * of thousands of rows for `crap.json` — and the functional `minimatch()` it
+ * used re-parsed each component glob for every single row. The component
+ * globs come from config, so the distinct set is small and immutable; caching
+ * the compiled matcher turns an O(rows × globs) parse into an O(globs) one
+ * (Story #5109). Matching semantics are unchanged: same patterns, same
+ * `{ dot: true }`.
+ *
+ * @type {Map<string, import('minimatch').Minimatch>}
+ */
+const GLOB_MATCHER_CACHE = new Map();
+
+/**
+ * Compile (once) the `Minimatch` for one glob.
+ *
+ * @param {string} glob
+ * @returns {import('minimatch').Minimatch}
+ */
+function matcherFor(glob) {
+  let matcher = GLOB_MATCHER_CACHE.get(glob);
+  if (!matcher) {
+    matcher = new Minimatch(glob, { dot: true });
+    GLOB_MATCHER_CACHE.set(glob, matcher);
+  }
+  return matcher;
+}
+
 /**
  * Resolve the components map for a single gate config.
  *
@@ -112,7 +142,7 @@ export function groupRows(rows, components, keyField = 'path') {
       const list = Array.isArray(globs) ? globs : [];
       for (const glob of list) {
         if (typeof glob !== 'string' || glob.length === 0) continue;
-        if (minimatch(normalized, glob, { dot: true })) {
+        if (matcherFor(glob).match(normalized)) {
           buckets[name].push(row);
           break;
         }