mandrel 2.52.0 → 2.54.0

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

@@ -2,7 +2,7 @@
  * close-validation/commands.js — Command resolution + formatter file policy.
  *
  * Owns the `project.commands.*` resolution helpers used by the close-
- * validation gates (typecheck / formatCheck / formatWrite), the Story-diff
+ * validation gates (typecheck / lint / formatCheck / formatWrite), the Story-diff
  * changed-file listing for the format gate, and the formatter
  * file-eligibility policy (Story #3410).
  */
@@ -17,6 +17,15 @@ import { getCommands } from '../config/commands.js';
  */
 const TYPECHECK_FALLBACK = 'npm run typecheck';
 
+/**
+ * Fallback lint command. The gate is mandatory, and this string is the exact
+ * command the gate spawned before `project.commands.lint` existed — an
+ * unconfigured consumer must keep getting byte-identical argv, because the
+ * gate's `commandConfigHash` is computed over it and any drift would silently
+ * invalidate every previously recorded lint evidence record.
+ */
+const LINT_FALLBACK = 'npm run lint';
+
 /** Default formatter command when `project.commands.formatCheck` is unset. */
 export const FORMAT_CHECK_FALLBACK = 'npx biome format .';
 
@@ -72,6 +81,23 @@ export function resolveTypecheckCommand(config) {
   return resolveCommandWithFallback(config, 'typecheck', TYPECHECK_FALLBACK);
 }
 
+/**
+ * Resolve the lint command. Reads `project.commands.lint`; falls back to
+ * `npm run lint`. The framework-wide `COMMANDS_DEFAULTS.lint` is `null` — as
+ * for typecheck — because the fallback belongs to this mandatory gate rather
+ * than to the shared accessor.
+ *
+ * A consumer sets this to point the gate at the scoped pair its hooks already
+ * run: the close-time gate stays real (the diff is still linted) while CI
+ * keeps owning whole-repo drift. Exported for testing.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ * @returns {string}
+ */
+export function resolveLintCommand(config) {
+  return resolveCommandWithFallback(config, 'lint', LINT_FALLBACK);
+}
+
 /**
  * Resolve the format-check command. Reads `project.commands.formatCheck`;
  * falls back to `npx biome format .` so existing repos keep working byte-

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

@@ -17,6 +17,7 @@ import {
   FORMAT_CHECK_FALLBACK,
   resolveFormatCheckCommand,
   resolveFormatWriteCommand,
+  resolveLintCommand,
   resolveTypecheckCommand,
 } from './commands.js';
 
@@ -335,6 +336,20 @@ function buildBaselinesGateEntries({ decision, kinds, env }) {
   ];
 }
 
+/**
+ * Split a resolved command string into the `{ cmd, args }` pair a gate entry
+ * carries. Whitespace-separated, so `npm run lint` yields the argv the gate
+ * spawned before any of these commands were configurable — which is what
+ * keeps an unconfigured consumer's `commandConfigHash` unchanged.
+ *
+ * @param {string} commandString
+ * @returns {{ cmd: string, args: string[] }}
+ */
+function splitCommand(commandString) {
+  const [cmd, ...args] = commandString.split(/\s+/).filter(Boolean);
+  return { cmd, args };
+}
+
 /**
  * Build the canonical close-validation gate list.
  *
@@ -347,8 +362,12 @@ function buildBaselinesGateEntries({ decision, kinds, env }) {
  * absent, coverage-capture is dropped and the `test` gate is restored so
  * there is always a working test gate.
  *
- * `typecheck` is mandatory; consumers may customise the command via
- * `project.commands.typecheck` (default `npm run typecheck`).
+ * `typecheck` and `lint` are mandatory; consumers may customise either
+ * command via `project.commands.typecheck` / `project.commands.lint`
+ * (defaults `npm run typecheck` / `npm run lint`). Customising `lint` is how
+ * a consumer whose hooks and CI already lint the diff stops paying for a
+ * third whole-repo pass at close: `lint` runs in the parallel partition, so
+ * a slow whole-repo lint sets the floor for that whole phase.
  *
  * Story #2210 retired the legacy per-kind in-process regression gates
  * (`check-maintainability`, `check-crap`, `check-mutation`) and their
@@ -409,14 +428,10 @@ export function buildDefaultGates({
   const scripts = packageScripts ?? readPackageScripts(cwd);
   const coverageCaptureActive =
     isCrapGateEnabled(config) && hasNpmScript(scripts, 'test:coverage');
-  const typecheckCmdString = resolveTypecheckCommand(config);
-  const [typecheckCmd, ...typecheckArgs] = typecheckCmdString
-    .split(/\s+/)
-    .filter(Boolean);
+  const typecheck = splitCommand(resolveTypecheckCommand(config));
+  const lint = splitCommand(resolveLintCommand(config));
   const formatCheckString = resolveFormatCheckCommand(config);
-  const [formatCmd, ...formatArgs] = formatCheckString
-    .split(/\s+/)
-    .filter(Boolean);
+  const format = splitCommand(formatCheckString);
   const formatWriteString = resolveFormatWriteCommand(config);
   const formatChangedFileScope =
     formatCheckString === FORMAT_CHECK_FALLBACK
@@ -436,11 +451,15 @@ export function buildDefaultGates({
   return [
     {
       name: 'typecheck',
-      cmd: typecheckCmd,
-      args: typecheckArgs,
+      cmd: typecheck.cmd,
+      args: typecheck.args,
       hint: TYPECHECK_HINT,
     },
-    { name: 'lint', cmd: 'npm', args: ['run', 'lint'] },
+    // Gate name kept generic ("lint") for the same reason the format gate's
+    // is: the command resolves from config, so a consumer pointing it at a
+    // scoped pair does not shift the close-orchestrator log line, the
+    // evidence keyspace, or the parallel-partition membership below.
+    { name: 'lint', cmd: lint.cmd, args: lint.args },
     ...buildTestGateEntry(coverageCaptureActive),
     {
       // Gate name kept generic ("format") so the close-orchestrator log line
@@ -448,8 +467,8 @@ export function buildDefaultGates({
       // `project.commands.formatCheck`. The
       // actual command and the remediation hint resolve from config.
       name: 'format',
-      cmd: formatCmd,
-      args: formatArgs,
+      cmd: format.cmd,
+      args: format.args,
       hint: buildFormatHint(formatWriteString),
       ...(formatChangedFileScope
         ? { changedFileScope: formatChangedFileScope }

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

@@ -1,13 +1,14 @@
 /**
  * `project.commands` accessor (Epic #1720 Story #1739 — top-level reshape).
  *
- * The surviving four command keys are `test`, `typecheck`,
- * `formatCheck`, `formatWrite`.
+ * The command keys are `test`, `typecheck`, `lint`, `formatCheck`,
+ * `formatWrite`.
  */
 
 export const COMMANDS_DEFAULTS = Object.freeze({
   test: 'npm test',
   typecheck: null,
+  lint: null,
   formatCheck: 'npx biome format .',
   formatWrite: 'npx biome format --write .',
 });
@@ -18,17 +19,18 @@ export const COMMANDS_DEFAULTS = Object.freeze({
  * a bare `{ project }` bag.
  *
  * @param {object | null | undefined} config
- * @returns {{ test: string, typecheck: string|null, formatCheck: string, formatWrite: string }}
+ * @returns {{ test: string, typecheck: string|null, lint: string|null, formatCheck: string, formatWrite: string }}
  */
 export function getCommands(config) {
   const commands = config?.project?.commands ?? {};
-  return {
-    test: commands.test ?? COMMANDS_DEFAULTS.test,
-    typecheck:
-      commands.typecheck === undefined
-        ? COMMANDS_DEFAULTS.typecheck
-        : commands.typecheck,
-    formatCheck: commands.formatCheck ?? COMMANDS_DEFAULTS.formatCheck,
-    formatWrite: commands.formatWrite ?? COMMANDS_DEFAULTS.formatWrite,
-  };
+  // `??` is uniform across every key: the two nullable ones (`typecheck`,
+  // `lint`) default to `null` themselves, so coalescing an explicit `null`
+  // onto the default returns that same `null` — the per-key `=== undefined`
+  // ladder this replaces drew a distinction that had no observable effect.
+  return Object.fromEntries(
+    Object.keys(COMMANDS_DEFAULTS).map((key) => [
+      key,
+      commands[key] ?? COMMANDS_DEFAULTS[key],
+    ]),
+  );
 }

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

@@ -45,6 +45,12 @@ const EXECUTION_SCHEMA = {
         'Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.',
       default: true,
     },
+    requireCreditedCapture: {
+      type: 'boolean',
+      description:
+        'Refuse a full-suite coverage capture that no committed stamp covers, instead of paying for it. Default false — the run is announced (a warning naming the crediting invocation, emitted before the spawn) and then executed, which is the pre-existing behaviour. Set true when the whole-suite cost is large enough that a close should stop at zero seconds rather than absorb it silently.',
+      default: false,
+    },
   },
   additionalProperties: false,
 };

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

@@ -128,9 +128,10 @@ const PATHS_SCHEMA = {
 };
 
 /**
- * `project.commands` — names of the test/typecheck/format commands the
+ * `project.commands` — names of the test/typecheck/lint/format commands the
  * close-validation chain spawns. `typecheck` accepts `null` to mean
- * "disabled". `validate` and `build` were dropped (no production consumers).
+ * "disabled"; `lint` accepts `null` to mean "use the framework default",
+ * because that gate is mandatory and cannot be switched off. `validate` and `build` were dropped (no production consumers).
  */
 const COMMANDS_SCHEMA = {
   type: 'object',
@@ -149,6 +150,12 @@ const COMMANDS_SCHEMA = {
         'Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it.',
       default: COMMANDS_DEFAULTS.typecheck,
     },
+    lint: {
+      ...NULLABLE_NONEMPTY_SAFE_STRING,
+      description:
+        'Lint command run as a close-validation gate. `null` (the default) uses `npm run lint`; the gate is mandatory, so unlike `typecheck` this key cannot disable it. Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-linter pair in one npm script and name that.',
+      default: COMMANDS_DEFAULTS.lint,
+    },
     formatCheck: {
       ...SAFE_STRING,
       minLength: 1,

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

@@ -375,6 +375,76 @@ export function describeFreshness(freshness, targetDirs) {
   return `${reason} — no scorable source file found under [${dirs}]; if that does not name this project's sources, fix quality.gates.crap.targetDirs`;
 }
 
+/**
+ * The invocation that deposits capture credit for a Story branch. Named in
+ * the uncredited-capture announcement so a reader of a close log sees the
+ * command that would have avoided the cost, not just the cost.
+ */
+const CREDITING_INVOCATION =
+  'node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>';
+
+/**
+ * Announce — and, when the consumer requires credit, refuse — a full-suite
+ * capture that no committed stamp covers.
+ *
+ * Every caller invokes this immediately before it would spawn the suite, and
+ * the ordering is the whole point. The capture itself is the most expensive
+ * thing a close does; discovering that it ran uncredited is only actionable
+ * while it is still ahead of you, not once it is visible as a `durationMs`
+ * in `validation-evidence.json` twelve minutes later.
+ *
+ * The probe is read-only by construction: every caller has already decided
+ * to capture by the time it runs, and it writes nothing — so it never takes
+ * the full-suite host lock and can never itself be the reason a close waits.
+ *
+ * @param {{
+ *   requireCredited?: boolean,
+ *   logger: { info: Function, warn: Function, error: Function },
+ * }} opts `requireCredited` mirrors `delivery.execution.requireCreditedCapture`
+ *   (default false → announce and run).
+ * @returns {number | null} A non-zero exit code the caller MUST return
+ *   without spawning the suite, or `null` to proceed with the capture.
+ */
+function announceUncreditedCapture({ requireCredited = false, logger }) {
+  const preamble =
+    'no credited capture stamp covers this change set — ' +
+    `the full suite is about to run. Deposit credit before the push with: ${CREDITING_INVOCATION}`;
+  if (requireCredited) {
+    logger.error(
+      `[coverage-capture] ✖ ${preamble} (delivery.execution.requireCreditedCapture is set, so this run is refused instead of paid for).`,
+    );
+    return 1;
+  }
+  logger.warn(`[coverage-capture] ⚠ ${preamble}`);
+  return null;
+}
+
+/**
+ * Compose the uncredited-capture probe over a capture runner, so the
+ * announcement is structurally inseparable from the spawn it describes.
+ *
+ * This mirrors `lockedCapture`, and for the same reason: there are two
+ * capture paths (full-scope and incremental) and neither should have to
+ * remember the policy. Wrapping the runner they share means a third path
+ * added later inherits the probe for free, and that the warning can never be
+ * emitted for a capture that does not happen — or omitted for one that does.
+ *
+ * It composes OUTSIDE `lockedCapture`, so a refusal costs nothing: the host
+ * lock is never acquired for a run that is about to be declined.
+ *
+ * @param {(opts: object) => number} runCaptureFn The (possibly already
+ *   lock-wrapped) capture runner.
+ * @param {{ requireCredited?: boolean, logger: object }} policy
+ * @returns {(opts?: object) => number} A runner returning the capture's exit
+ *   code, or a non-zero refusal code without having spawned anything.
+ */
+export function creditedCapture(runCaptureFn, { requireCredited, logger }) {
+  return (captureOpts = {}) => {
+    const refusal = announceUncreditedCapture({ requireCredited, logger });
+    return refusal === null ? runCaptureFn(captureOpts) : refusal;
+  };
+}
+
 /**
  * Narrow `changedFiles` to the subset that lives under one of `targetDirs`.
  *