mandrel 2.36.0 → 2.37.0

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/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;
         }

package/.agents/scripts/lib/baselines/env-overrides.js

@@ -16,7 +16,7 @@ import { Logger } from '../Logger.js';
 // rounding) routinely drifts +/- 0.05 to 0.3 on otherwise-unchanged files —
 // well below the threshold of "actually less maintainable." A 0.5 floor
 // stops the pre-push hook from auto-ratcheting the baseline on noise.
-export const MI_DEFAULT_TOLERANCE = 0.5;
+const MI_DEFAULT_TOLERANCE = 0.5;
 
 /**
  * Pure helper: resolve the effective CRAP config by layering env-var

package/.agents/scripts/lib/bootstrap/branch-protection.js

@@ -43,7 +43,7 @@ const TARGET_APPROVAL_COUNT = 0;
  * return value is a structured diff suitable for `hitlConfirm` so the
  * operator sees exactly what would flip.
  */
-export function diffProtection(current, targetContexts) {
+function diffProtection(current, targetContexts) {
   if (!current) return null; // create-from-scratch path; no diff needed.
 
   const diff = {};

package/.agents/scripts/lib/bootstrap/install-ledger.js

@@ -80,7 +80,7 @@ const TARGET_TO_PHASE = Object.freeze({
  * @param {Record<string, { action?: string }>} [report]
  * @returns {string|undefined}
  */
-export function resolveExecutedAction(entry, report) {
+function resolveExecutedAction(entry, report) {
   if (!report) return undefined;
   const phaseName = TARGET_TO_PHASE[entry.target];
   if (!phaseName) return undefined;

package/.agents/scripts/lib/bootstrap/prompt.js

@@ -28,7 +28,7 @@ import readline from 'node:readline/promises';
  * Flags the bootstrap CLI accepts. Keep this list in sync with the
  * `--help` text in bootstrap.js.
  */
-export const KNOWN_FLAGS = Object.freeze({
+const KNOWN_FLAGS = Object.freeze({
   string: [
     'owner',
     'repo',

package/.agents/scripts/lib/bootstrap/quality-bootstrap.js

@@ -41,7 +41,7 @@ import { deepEqual } from '../json-utils.js';
  * the hook-installer can detect a verbatim framework hook (overwrite-safe)
  * vs a custom hook (preserve and warn).
  */
-export const FRAMEWORK_PRE_COMMIT = `node scripts/check-version-sync.js
+const FRAMEWORK_PRE_COMMIT = `node scripts/check-version-sync.js
 npx lint-staged
 # Story #1395 / Epic #1386: catch MI/CRAP drift at git-commit time so the
 # agent refactors before the diff is closed. quality:preview wraps both gates
@@ -78,7 +78,7 @@ export const PRE_COMMIT_MARKER =
  * when the keys are absent. Mirrors `.agents/docs/agentrc-reference.json` — keep in
  * sync when those numbers move.
  */
-export const QUALITY_CONFIG_DEFAULTS = Object.freeze({
+const QUALITY_CONFIG_DEFAULTS = Object.freeze({
   codingGuardrails: Object.freeze({
     cyclomaticFlag: 8,
     cyclomaticMustFix: 12,

package/.agents/scripts/lib/checks/loop-health.js

@@ -42,7 +42,7 @@ import { validateSignal } from '../observability/signal-validator.js';
  * a health probe, not an exhaustive audit — the most recent window is a
  * representative sample that keeps the read bounded on long streams.
  */
-export const MAX_SAMPLE_LINES = 200;
+const MAX_SAMPLE_LINES = 200;
 
 /**
  * Locate the most-recently-touched `run-<id>` temp tree under

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

@@ -210,7 +210,6 @@ export function parseSprintArgs(
       'recut-of': { type: 'string' },
       resume: { type: 'boolean', default: false },
       restart: { type: 'boolean', default: false },
-      'no-evidence': { type: 'boolean', default: false },
     },
     allowPositionals: true,
     strict: false,
@@ -260,7 +259,6 @@ export function parseSprintArgs(
     // CLI compatibility).
     resume: values.resume ?? false,
     restart: values.restart ?? false,
-    noEvidence: values['no-evidence'] ?? false,
   };
 
   parsed.ticketId =

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

@@ -392,7 +392,7 @@ export const DEFAULT_GATES = buildDefaultGates();
  * state, no overlapping ports/sockets). Safe to run concurrently — see
  * `runCloseValidation` for the Promise.all + AbortController plumbing.
  */
-export const INDEPENDENT_GATE_NAMES = new Set(['lint', 'format', 'typecheck']);
+const INDEPENDENT_GATE_NAMES = new Set(['lint', 'format', 'typecheck']);
 
 /**
  * Partition a gate list into the parallel-safe set and the order-sensitive

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

@@ -113,7 +113,7 @@ const MARKER_PROBE_TAIL_LINES = 32;
  * @param {string} output - Combined stdout/stderr captured from the gate child.
  * @returns {boolean}
  */
-export function isBiomeNoFilesProcessed(output) {
+function isBiomeNoFilesProcessed(output) {
   return (
     typeof output === 'string' && output.includes(BIOME_NO_FILES_PROCESSED)
   );

package/.agents/scripts/lib/config/sync-agentrc.js

@@ -173,7 +173,7 @@ export function collectRedundantAdvisories(
  * @param {string} dottedPath
  * @returns {boolean}
  */
-export function isLeafSchemaRemovable(rootSchema, dottedPath) {
+function isLeafSchemaRemovable(rootSchema, dottedPath) {
   if (!rootSchema || typeof rootSchema !== 'object') return true;
   const parts = dottedPath.split('.');
   let cursor = rootSchema;

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

@@ -1,7 +1,7 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code); MI < 70 is inherent to large flat schema literals, no business logic to test */
 
-import Ajv from 'ajv';
-
+import { createRequire } from 'node:module';
+import process from 'node:process';
 import { COMMANDS_DEFAULTS } from './config/commands.js';
 import {
   BRANCH_PROTECTION_DEFAULTS,
@@ -15,6 +15,7 @@ import { SHELL_INJECTION_PATTERN_STRING } from './config-schema-shared.js';
 // to keep this aggregate module above the maintainability floor. The
 // resolved AGENTRC_SCHEMA is unchanged.
 import { DELIVERY_SCHEMA } from './config-settings-schema-delivery.js';
+import compiledAgentrcValidator from './generated/agentrc-validator.js';
 
 /**
  * Annotation contract (Story #5007). These schema literals are the SINGLE
@@ -861,10 +862,49 @@ export const AGENTRC_SCHEMA = {
 };
 
 let _agentrcValidator = null;
+
+/**
+ * Compile `AGENTRC_SCHEMA` with a live AJV instance.
+ *
+ * `ajv` is pulled in through `createRequire` rather than a top-level
+ * `import` so the module never enters the graph on the fast path
+ * (Story #5109). Loading AJV was itself a measurable share of the ~35 ms
+ * this function used to cost in each of the 36 config-touching entry
+ * scripts, and the precompiled validator needs none of it.
+ *
+ * @returns {import('ajv').ValidateFunction}
+ */
+function compileAgentrcValidatorDynamically() {
+  const require = createRequire(import.meta.url);
+  const ajvModule = require('ajv');
+  const Ajv = ajvModule.default ?? ajvModule;
+  const ajv = new Ajv({ allErrors: true });
+  return ajv.compile(AGENTRC_SCHEMA);
+}
+
+/**
+ * The `.agentrc.json` validator.
+ *
+ * Returns the **precompiled** validator committed at
+ * `lib/generated/agentrc-validator.js` — AJV's standalone emit for the exact
+ * `AGENTRC_SCHEMA` literal above, kept in step by
+ * `check-generated-validator.js --check` inside `npm run lint`. The verdicts
+ * are AJV's own, produced by AJV's own generated code with the same
+ * `allErrors: true` option the dynamic path uses, so nothing about what a
+ * config is allowed to contain changes — only when the codegen runs.
+ *
+ * Set `MANDREL_AGENTRC_VALIDATOR=dynamic` to compile at runtime instead. That
+ * escape hatch exists so a consumer who has hand-edited the schema (or hit a
+ * platform where the generated module will not load) is never stuck with a
+ * validator they cannot regenerate; it costs the ~35 ms the artifact removes.
+ *
+ * @returns {import('ajv').ValidateFunction}
+ */
 export function getAgentrcValidator() {
-  if (!_agentrcValidator) {
-    const ajv = new Ajv({ allErrors: true });
-    _agentrcValidator = ajv.compile(AGENTRC_SCHEMA);
-  }
+  if (_agentrcValidator) return _agentrcValidator;
+  _agentrcValidator =
+    process.env.MANDREL_AGENTRC_VALIDATOR === 'dynamic'
+      ? compileAgentrcValidatorDynamically()
+      : compiledAgentrcValidator;
   return _agentrcValidator;
 }

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

@@ -22,7 +22,7 @@ import path from 'node:path';
 import picomatch from 'picomatch';
 import { write, writeFile } from './baselines/writer.js';
 
-export const COVERAGE_FINAL_PATH = 'coverage/coverage-final.json';
+const COVERAGE_FINAL_PATH = 'coverage/coverage-final.json';
 export const COVERAGE_BASELINE_PATH = 'baselines/coverage.json';
 // Absolute floating-point tolerance (percentage points). Values in the
 // baseline are stored to two decimals, so anything below 0.01 is noise.
@@ -32,7 +32,7 @@ export const COVERAGE_TOLERANCE = 0.01;
 // branch flipping covered↔uncovered between runs is the natural noise floor
 // under non-deterministic Windows/Node 22 V8 instrumentation. We absorb up
 // to one event of slack per axis. Anything beyond one event is real signal.
-export const NOISE_EVENT_HEADROOM = 1.0;
+const NOISE_EVENT_HEADROOM = 1.0;
 
 function toForwardSlash(p) {
   return p.replace(/\\/g, '/');