mandrel 2.53.0 → 2.55.0

package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js

@@ -36,15 +36,80 @@ const BASELINE_MERGE_ATTRIBUTE = `baselines/*.json merge=${BASELINE_MERGE_DRIVER
 /** Git config key holding the driver command. */
 export const BASELINE_MERGE_DRIVER_CONFIG_KEY = `merge.${BASELINE_MERGE_DRIVER_NAME}.driver`;
 
+/** Script path the driver command invokes, relative to the worktree root. */
+const DRIVER_SCRIPT = '.agents/scripts/merge-baseline.js';
+
+/** Git's merge-driver placeholders, in the order the driver's argv expects. */
+const DRIVER_PLACEHOLDERS = '%O %A %B %P';
+
 /**
- * The driver command. Relative to the worktree root, which is where git runs
- * a merge driver from, and where `mandrel sync` materializes `.agents/`.
+ * Build the driver command for a given node binary.
+ *
+ * The interpreter is the RESOLVED ABSOLUTE path (`process.execPath`), not the
+ * bare word `node`, and it is quoted. Git runs a merge driver through the
+ * shell, and that shell's `PATH` is whatever launched git — a GUI client, a
+ * Finder-launched editor, a `launchd` job — none of which necessarily carry
+ * the nvm/volta shim that puts `node` on an interactive shell's `PATH`. A
+ * driver that cannot start is not a loud failure: git reports the driver
+ * exited non-zero and falls back to leaving the file conflicted, which reads
+ * as "baselines conflict again" — the exact symptom the driver exists to
+ * remove. Quoting covers the installation whose node lives under a path with
+ * a space (`/Users/a b/.nvm/...`).
+ *
+ * The script path stays RELATIVE: git runs the driver from the worktree root,
+ * and that is also where `mandrel sync` materializes `.agents/`, so one
+ * command is correct in the main checkout and in every linked worktree.
+ *
+ * @param {string} [execPath] Absolute path to the node binary.
+ * @returns {string}
  */
-const BASELINE_MERGE_DRIVER_COMMAND =
-  'node .agents/scripts/merge-baseline.js %O %A %B %P';
+function buildBaselineMergeDriverCommand(execPath = process.execPath) {
+  return `"${execPath}" ${DRIVER_SCRIPT} ${DRIVER_PLACEHOLDERS}`;
+}
 
-/** The exact command an operator runs to complete registration. */
-export const BASELINE_MERGE_DRIVER_REMEDY = `git config ${BASELINE_MERGE_DRIVER_CONFIG_KEY} "${BASELINE_MERGE_DRIVER_COMMAND}"`;
+/** The driver command this process would install. */
+const BASELINE_MERGE_DRIVER_COMMAND = buildBaselineMergeDriverCommand();
+
+/**
+ * The exact command an operator runs to complete registration. Single-quoted
+ * because the command itself carries the double quotes around the node path.
+ */
+export const BASELINE_MERGE_DRIVER_REMEDY = `git config ${BASELINE_MERGE_DRIVER_CONFIG_KEY} '${BASELINE_MERGE_DRIVER_COMMAND}'`;
+
+/**
+ * Split a configured driver command into an executable + argv pair, dropping
+ * git's `%O %A %B %P` placeholders.
+ *
+ * Used by the `mandrel doctor` check to actually RUN the configured command
+ * (with `--help`) rather than only assert the config key is non-empty. A key
+ * pointing at a node that no longer exists — the ordinary outcome of an nvm
+ * version bump after the driver was installed — is set, non-empty, and
+ * completely broken, and the pre-Story-#5277 check called that healthy.
+ *
+ * Tokenising here rather than handing the string to a shell is deliberate:
+ * the value is per-clone git config, and executing it through `shell: true`
+ * would turn any write to that key into arbitrary command execution
+ * (`security-baseline.md` § Output & Rendering — never concatenate into a
+ * shell command). Only double quotes are honoured, which is exactly the
+ * quoting {@link buildBaselineMergeDriverCommand} emits.
+ *
+ * @param {string|null|undefined} command
+ * @returns {{ file: string, args: string[] }|null} null when there is no
+ *   runnable first token.
+ */
+export function parseBaselineMergeDriverCommand(command) {
+  const tokens = String(command ?? '').match(/"[^"]*"|\S+/g) ?? [];
+  const cleaned = tokens
+    .map((token) =>
+      token.startsWith('"') && token.endsWith('"') && token.length >= 2
+        ? token.slice(1, -1)
+        : token,
+    )
+    .filter((token) => token.length > 0 && !/^%[A-Za-z]$/.test(token));
+  if (cleaned.length === 0) return null;
+  const [file, ...args] = cleaned;
+  return { file, args };
+}
 
 /**
  * Does this `.gitattributes` content route baselines through the driver?
@@ -53,7 +118,7 @@ export const BASELINE_MERGE_DRIVER_REMEDY = `git config ${BASELINE_MERGE_DRIVER_
  * @param {string|null|undefined} gitattributes
  * @returns {boolean}
  */
-export function declaresBaselineMergeDriver(gitattributes) {
+function declaresBaselineMergeDriver(gitattributes) {
   return String(gitattributes ?? '')
     .split('\n')
     .some((line) => {
@@ -63,6 +128,55 @@ export function declaresBaselineMergeDriver(gitattributes) {
     });
 }
 
+/**
+ * Is the driver DECLARED by this project and REGISTERED in this clone?
+ *
+ * Two callers ask this exact question of two different clones — the
+ * `mandrel doctor` check, and the pre-push base-sync guard — and both need
+ * the same two-part answer, because the two halves fail differently:
+ *
+ *   - **Not declared** → the project never opted in. Both callers stay
+ *     silent; telling a consumer to register a driver for files they do not
+ *     route through it is noise. An unreadable `.gitattributes` reads the
+ *     same way, deliberately.
+ *   - **Declared, empty command** → the silent case. Git reports nothing at
+ *     all: it falls back to its own line-based merge, which on a generated
+ *     baseline either conflicts on the `generatedAt` stamp or splices both
+ *     sides' rows into a set neither side scored.
+ *
+ * The `runGit` seam takes argv tokens and returns `{ status, stdout }`, which
+ * is the shape both callers' own git surfaces already produce.
+ *
+ * @param {{
+ *   projectRoot: string,
+ *   fsImpl?: typeof fs,
+ *   runGit: (args: string[]) => { status?: number|null, stdout?: unknown },
+ * }} ctx
+ * @returns {{ declared: boolean, command: string }}
+ */
+export function probeBaselineMergeDriver({ projectRoot, fsImpl = fs, runGit }) {
+  let attributes = '';
+  try {
+    attributes = fsImpl.readFileSync(
+      path.join(projectRoot, '.gitattributes'),
+      'utf8',
+    );
+  } catch {
+    attributes = '';
+  }
+  if (!declaresBaselineMergeDriver(attributes)) {
+    return { declared: false, command: '' };
+  }
+  const configured = runGit([
+    'config',
+    '--get',
+    BASELINE_MERGE_DRIVER_CONFIG_KEY,
+  ]);
+  const command =
+    configured?.status === 0 ? String(configured.stdout ?? '').trim() : '';
+  return { declared: true, command };
+}
+
 /**
  * Add the attribute line, preserving every existing line verbatim.
  *
@@ -144,32 +258,84 @@ function ensureDriverGitConfig(projectRoot, spawnImpl = spawnCapture) {
 }
 
 /**
- * Install both halves. Idempotent: a second run reports `already-present`
- * and changes no bytes.
+ * Read `.gitattributes` without writing it — the `configOnly` half of
+ * {@link ensureBaselineMergeDriver}.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} fsImpl
+ * @returns {{ action: 'already-present'|'absent', path: string }}
+ */
+function probeGitattributesLine(projectRoot, fsImpl) {
+  const target = path.join(projectRoot, '.gitattributes');
+  let existing = '';
+  try {
+    existing = fsImpl.readFileSync(target, 'utf8');
+  } catch {
+    existing = '';
+  }
+  return {
+    action: declaresBaselineMergeDriver(existing)
+      ? 'already-present'
+      : 'absent',
+    path: target,
+  };
+}
+
+/**
+ * Install the registration. Idempotent: a second run reports
+ * `already-present` and changes no bytes.
+ *
+ * Two modes, because the two callers mean different things by "install":
+ *
+ * - **Full (default)** — `mandrel init --with-quality` and this repo's own
+ *   `prepare`. Writes the `.gitattributes` line as well as the config key:
+ *   the caller has opted the repository into the quality surface, so
+ *   declaring the attribute is part of what it asked for.
+ * - **`configOnly: true`** — consumer `mandrel sync`. Writes ONLY the
+ *   per-clone config key, and only when `.gitattributes` already declares the
+ *   attribute. `sync` materializes `.agents/`; it is not an opt-in to the
+ *   quality surface, and creating a `.gitattributes` in a project that never
+ *   asked for one would be `sync` changing git's behaviour on files it has no
+ *   business touching. What it DOES fix is the real gap: the attribute is
+ *   tracked and therefore ships with the repo, while the config key is
+ *   per-clone and silently absent in every fresh clone — so the half that
+ *   cannot travel is installed on the one command every consumer runs.
  *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
+ * @param {boolean} [ctx.configOnly]
  * @param {typeof spawnCapture} [ctx.spawnImpl]
  * @param {typeof fs} [ctx.fsImpl]
  * @returns {{
- *   action: 'already-present'|'updated',
+ *   action: 'already-present'|'updated'|'skipped',
  *   attributes: string,
  *   config: string,
  *   path: string,
  *   line: string,
+ *   command: string,
  * }}
  */
 export function ensureBaselineMergeDriver(ctx) {
-  const attributes = ensureGitattributesLine(ctx.projectRoot, ctx.fsImpl ?? fs);
+  const fsImpl = ctx.fsImpl ?? fs;
+  const attributes = ctx.configOnly
+    ? probeGitattributesLine(ctx.projectRoot, fsImpl)
+    : ensureGitattributesLine(ctx.projectRoot, fsImpl);
+  const base = {
+    attributes: attributes.action,
+    path: attributes.path,
+    line: BASELINE_MERGE_ATTRIBUTE,
+    command: BASELINE_MERGE_DRIVER_COMMAND,
+  };
+  if (attributes.action === 'absent') {
+    return { ...base, action: 'skipped', config: 'skipped' };
+  }
   const config = ensureDriverGitConfig(ctx.projectRoot, ctx.spawnImpl);
   const settled =
     attributes.action === 'already-present' &&
     (config.action === 'already-present' || config.action === 'not-a-repo');
   return {
+    ...base,
     action: settled ? 'already-present' : 'updated',
-    attributes: attributes.action,
     config: config.action,
-    path: attributes.path,
-    line: BASELINE_MERGE_ATTRIBUTE,
   };
 }

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

@@ -62,6 +62,22 @@ function parsePositiveInt(value) {
   return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
 
+/**
+ * The same contract for a flag whose ZERO is meaningful (Story #5266):
+ * `--rerun-advisory 0` is an explicit "spend nothing", not an absent flag.
+ * A negative or non-numeric value is still treated as absent rather than
+ * coerced, so a typo falls back to the config default instead of inventing an
+ * allowance that spends the consumer's CI minutes.
+ *
+ * @param {unknown} value
+ * @returns {number|undefined}
+ */
+function parseNonNegativeInt(value) {
+  if (value === undefined || value === null) return undefined;
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
 /** The only two merge-watch postures `--merge-watch-mode` accepts. */
 const MERGE_WATCH_MODES = ['sync', 'async'];
 
@@ -200,6 +216,10 @@ export function parseSprintArgs(
       // Absent means "use the config"; see `parseMergeWatchMode` for why an
       // unrecognized value fails closed instead of degrading to absent.
       'merge-watch-mode': { type: 'string' },
+      // Story #5266 — per-invocation override of `delivery.ci.rerunAdvisory`.
+      // Absent means "use the config", whose default is 0: close re-runs
+      // nothing and mutates no GitHub state on an advisory red unless asked.
+      'rerun-advisory': { type: 'string' },
       // Sanctioned override of a code-review critical blocker.
       // Absent means "the blocker blocks"; see `parseOverrideReviewBlock` for
       // why a bare or too-short reason fails closed instead of arming a silent
@@ -240,6 +260,12 @@ export function parseSprintArgs(
     mergeWatchMode: tolerant
       ? tolerantMergeWatchMode(values['merge-watch-mode'])
       : parseMergeWatchMode(values['merge-watch-mode']),
+    // Story #5266 — how many times close may re-run a failed ADVISORY run
+    // before blocking on it. `undefined` when absent, which is what lets the
+    // merge wait fall back to `delivery.ci.rerunAdvisory` (default 0).
+    // `parseNonNegativeInt` degrades a junk value to undefined rather than
+    // guessing an allowance that would spend the consumer's CI minutes.
+    rerunAdvisory: parseNonNegativeInt(values['rerun-advisory']),
     // The operator's recorded reason for overriding a review
     // blocker. `undefined` when the flag is absent, which is what keeps the
     // blocker blocking by default.

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

@@ -9,7 +9,9 @@
 import { existsSync } from 'node:fs';
 
 import { _internals as baselineReaderInternals } from '../baselines/reader.js';
+import { getChangedFiles } from '../changed-files.js';
 import { getQuality } from '../config/quality.js';
+import { filterFilesUnderTargets } from '../coverage-capture.js';
 import { hasNpmScript, readPackageScripts } from '../npm-scripts.js';
 import { KNOWN_KINDS } from '../orchestration/check-baselines/phases/parse-args.js';
 import {
@@ -28,6 +30,11 @@ import {
  * @property {string[]} args  - Arguments passed to `cmd`.
  * @property {string}   [hint] - Remediation hint shown on failure.
  * @property {{ baseRef: string }} [changedFileScope] - Optional Story-diff scope.
+ * @property {{ reason: string }} [skip] - Pre-decided skip (Story #5278). The
+ *   runner records the gate as skipped with this reason and never spawns it.
+ *   Used for the `coverage-capture` gate when the incremental-coverage skip
+ *   is already known to fire, so the gate list can register a real `npm test`
+ *   gate in its place instead of the close silently running no test gate.
  * @property {Record<string, string>} [env] - Optional per-gate environment
  *   overlay. Merged over `process.env` for this gate's spawned child only.
  *   Used to thread the epic baseRef into the `check-baselines` gate via
@@ -112,12 +119,18 @@ function isCrapGateEnabled(config) {
  * has NO working test gate at all. Splitting this out keeps
  * `buildDefaultGates` flat for the CRAP-cyclomatic gate.
  *
- * @param {boolean} coverageCaptureActive - Whether the coverage-capture gate
- *   is registered as the test runner for this build.
+ * Story #5278 adds a third way for coverage-capture to stop being the test
+ * runner: it is registered, but its own incremental-coverage skip is already
+ * known to fire (nothing changed under `crap.targetDirs`), so it will exit 0
+ * without running anything. A tests-only Story hits that on every close, and
+ * before #5278 the close then recorded a suite it never ran as `passed`.
+ *
+ * @param {boolean} coverageCaptureRunsSuite - Whether the coverage-capture
+ *   gate will actually run the suite for this build.
  * @returns {Gate[]}
  */
-function buildTestGateEntry(coverageCaptureActive) {
-  if (coverageCaptureActive) return [];
+function buildTestGateEntry(coverageCaptureRunsSuite) {
+  if (coverageCaptureRunsSuite) return [];
   // Story #5173 — `fullSuiteLock` marks the one gate here that spawns a whole
   // suite, so `defaultGateRunner` serializes it behind the host lock. It is
   // set on this entry alone precisely because the two full-suite gates are
@@ -350,6 +363,78 @@ function splitCommand(commandString) {
   return { cmd, args };
 }
 
+/**
+ * Will the `coverage-capture` gate skip its own capture before running
+ * anything? (Story #5278.)
+ *
+ * `coverage-capture-incremental.js` exits 0 without a suite when no changed
+ * file lives under `crap.targetDirs` — the saving that makes incremental mode
+ * worth having. The gate list has to know that in advance, because the
+ * consequence is not "coverage-capture is cheap today" but "there is no test
+ * gate in this close at all": the plain `test` gate is dropped precisely
+ * because coverage-capture was going to carry test-failure signalling. A
+ * tests-only Story therefore closed green over a red suite.
+ *
+ * Predicting the skip is safe in one direction only, so every uncertainty
+ * resolves to `false` (coverage-capture runs, no extra `test` gate — the
+ * pre-#5278 shape): an unresolvable ref, a missing cwd, a git error, or the
+ * mode being off. A wrong `false` costs one redundant capture; a wrong `true`
+ * would register a `test` gate beside a coverage-capture that also runs the
+ * suite, which is the double-spend the credit economy exists to prevent.
+ *
+ * @param {{
+ *   config?: object,
+ *   cwd?: string,
+ *   baseBranch?: string,
+ *   getChangedFilesImpl?: typeof getChangedFiles,
+ * }} opts
+ * @returns {boolean}
+ */
+function predictsIncrementalCaptureSkip({
+  config,
+  cwd,
+  baseBranch,
+  getChangedFilesImpl = getChangedFiles,
+}) {
+  // No cwd is the module-load `DEFAULT_GATES` case: never spawn git at import
+  // time just to answer a question that caller cannot act on.
+  if (typeof cwd !== 'string' || cwd.length === 0) return false;
+  const { crap } = getQuality(config);
+  if (crap?.incrementalCoverage?.skipWhenUnchanged !== true) return false;
+  const ref = crap.incrementalCoverage.baseRef || baseBranch;
+  if (typeof ref !== 'string' || ref.length === 0) return false;
+  try {
+    const changed = getChangedFilesImpl({ ref, cwd });
+    // Not an array is "the change set is unknown", not "the change set is
+    // empty" — and `filterFilesUnderTargets` flattens both to `[]`, so the
+    // shape has to be checked here or an unknown diff reads as a skip.
+    if (!Array.isArray(changed)) return false;
+    return filterFilesUnderTargets(changed, crap.targetDirs).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The `coverage-capture` gate's argv.
+ *
+ * Story #5278 — `--require-credited` is passed here, and only here, when the
+ * consumer has set `delivery.execution.requireCreditedCapture`. The CLI no
+ * longer reads that key, so the worker's pre-push deposit invocation always
+ * runs while the close gate refuses to pay for a suite the worker should
+ * already have banked.
+ *
+ * @param {object} [config]
+ * @returns {string[]}
+ */
+function buildCoverageCaptureArgs(config) {
+  const args = ['.agents/scripts/coverage-capture.js'];
+  if (config?.delivery?.execution?.requireCreditedCapture === true) {
+    args.push('--require-credited');
+  }
+  return args;
+}
+
 /**
  * Build the canonical close-validation gate list.
  *
@@ -402,7 +487,7 @@ function splitCommand(commandString) {
  * none are required, the gate is skipped with a logged reason (via `log`)
  * instead of a blocking failure.
  *
- * @param {{ config?: object, baseBranch?: string, cwd?: string, packageScripts?: Record<string, string>, presentBaselines?: string[]|Set<string>, log?: (message: string) => void }} [opts]
+ * @param {{ config?: object, baseBranch?: string, cwd?: string, packageScripts?: Record<string, string>, presentBaselines?: string[]|Set<string>, log?: (message: string) => void, getChangedFilesImpl?: typeof getChangedFiles }} [opts]
  *   `config` is the canonical resolved config (`{ project, delivery, ... }`);
  *   gate commands resolve from `project.commands` and the CRAP toggle from
  *   `delivery.quality.gates.crap.enabled`. `baseBranch` is the close run's
@@ -424,10 +509,28 @@ export function buildDefaultGates({
   packageScripts,
   presentBaselines,
   log,
+  getChangedFilesImpl,
 } = {}) {
   const scripts = packageScripts ?? readPackageScripts(cwd);
   const coverageCaptureActive =
     isCrapGateEnabled(config) && hasNpmScript(scripts, 'test:coverage');
+  // Story #5278 — a registered coverage-capture gate that is going to take
+  // its own incremental skip is not the test runner for this close, so the
+  // plain `test` gate comes back beside it and the capture gate registers as
+  // a pre-decided skip rather than as a suite that silently did not run.
+  const captureSkipPredicted =
+    coverageCaptureActive &&
+    predictsIncrementalCaptureSkip({
+      config,
+      cwd,
+      baseBranch,
+      ...(getChangedFilesImpl ? { getChangedFilesImpl } : {}),
+    });
+  if (captureSkipPredicted) {
+    log?.(
+      '[close-validation] coverage-capture will take the incremental skip (no changed file under the CRAP target dirs) — registering the plain `test` gate so this close still runs the suite.',
+    );
+  }
   const typecheck = splitCommand(resolveTypecheckCommand(config));
   const lint = splitCommand(resolveLintCommand(config));
   const formatCheckString = resolveFormatCheckCommand(config);
@@ -460,7 +563,7 @@ export function buildDefaultGates({
     // 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),
+    ...buildTestGateEntry(coverageCaptureActive && !captureSkipPredicted),
     {
       // Gate name kept generic ("format") so the close-orchestrator log line
       // doesn't shift when a repo swaps biome for Prettier / dprint via
@@ -479,8 +582,11 @@ export function buildDefaultGates({
           {
             name: 'coverage-capture',
             cmd: 'node',
-            args: ['.agents/scripts/coverage-capture.js'],
+            args: buildCoverageCaptureArgs(config),
             hint: 'Coverage capture failed — `npm run test:coverage` exited non-zero. Fix failing tests or coverage-threshold breaches, then re-run close.',
+            ...(captureSkipPredicted
+              ? { skip: { reason: 'incremental-no-crap-changes' } }
+              : {}),
           },
         ]
       : []),

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

@@ -153,15 +153,19 @@ function isBiomeNoFilesProcessed(output) {
  *
  * @param {string} cmd
  * @param {string[]} args
- * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean }} opts
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, skipIfSatisfied?: () => {status: number}|undefined }} opts
  * @returns {Promise<{ status: number }>}
  */
 export function defaultGateRunner(cmd, args, opts = {}) {
   if (!opts.fullSuiteLock) return spawnGate(cmd, args, opts);
   // `log` is passed through as-is: `withFullSuiteLockAsync` supplies its own
   // no-op default, so a second fallback here would be an untestable branch.
-  return withFullSuiteLockAsync({ cwd: opts.cwd, log: opts.log }, () =>
-    spawnGate(cmd, args, opts),
+  // `skipIfSatisfied` (Story #5278) is the caller's post-wait re-probe: after
+  // queueing behind another full suite, the gate re-asks whether its evidence
+  // has since been deposited and returns that verdict instead of spawning.
+  return withFullSuiteLockAsync(
+    { cwd: opts.cwd, log: opts.log, skipIfSatisfied: opts.skipIfSatisfied },
+    () => spawnGate(cmd, args, opts),
   );
 }
 

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

@@ -8,9 +8,11 @@
  * surfaces actionable hints on failure.
  */
 
+import { gitSpawn } from '../git-utils.js';
 import {
   recordPass as defaultRecordPass,
   shouldSkip as defaultShouldSkip,
+  treeFingerprint as defaultTreeFingerprint,
   hashCommandConfig,
 } from '../validation-evidence.js';
 import {
@@ -25,6 +27,20 @@ import { defaultGetHeadSha } from './projections/head-sha.js';
 /** @typedef {import('./gates.js').Gate} Gate */
 
 function applyChangedFileScope({ gate, spawnCwd, log }) {
+  // Story #5278 — a skip the gate list already decided (the coverage-capture
+  // gate whose incremental skip is known to fire). Honoured before anything
+  // else so the gate is recorded as `skipped` with its real reason rather
+  // than spawned to discover the same thing minutes later.
+  if (gate.skip) {
+    log(`[close-validation] ⏭ ${gate.name} skipped (${gate.skip.reason})`);
+    return {
+      gate,
+      cmd: gate.cmd,
+      args: gate.args,
+      skip: true,
+      skipReason: gate.skip.reason,
+    };
+  }
   if (!gate.changedFileScope) {
     return { gate, cmd: gate.cmd, args: gate.args, skip: false };
   }
@@ -116,6 +132,7 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  *   useEvidence?: boolean,
  *   evidenceClock?: () => number,
  *   getHeadSha?: (cwd: string) => string|null,
+ *   getTreeFingerprint?: (cwd: string) => string|null,
  *   recordPass?: typeof defaultRecordPass,
  *   shouldSkip?: typeof defaultShouldSkip,
  * }} opts
@@ -137,6 +154,8 @@ export async function runCloseValidation({
   useEvidence = true,
   evidenceClock = () => Date.now(),
   getHeadSha = (resolvedCwd) => defaultGetHeadSha(resolvedCwd),
+  getTreeFingerprint = (resolvedCwd) =>
+    defaultTreeFingerprint(resolvedCwd, gitSpawn),
   recordPass = defaultRecordPass,
   shouldSkip = defaultShouldSkip,
 } = {}) {
@@ -153,6 +172,13 @@ export async function runCloseValidation({
   // Story #1120.
   const spawnCwd = worktreePath ?? cwd;
   const headSha = evidenceActive ? getHeadSha(spawnCwd) : null;
+  // Story #5278 — one tree fingerprint for the whole run, not one per gate.
+  // Every gate here reads the same working tree, so an identical tree means
+  // identical inputs for all of them; a per-gate scope would be narrower but
+  // would have to model each gate's read set, and being wrong about that
+  // grants a skip the gate did not earn. A gate that carries its own
+  // `inputFingerprint` still wins.
+  const treeSha = evidenceActive ? getTreeFingerprint(spawnCwd) : null;
 
   // Helper closures so the parallel and serial passes share evidence
   // bookkeeping bit-for-bit.
@@ -166,7 +192,7 @@ export async function runCloseValidation({
         gateName: gate.name,
         currentSha: headSha,
         configHash,
-        inputFingerprint: gate.inputFingerprint ?? null,
+        inputFingerprint: gate.inputFingerprint ?? treeSha,
       },
       evidenceStoreOpts,
     );
@@ -192,7 +218,7 @@ export async function runCloseValidation({
           configHash,
           exitCode: 0,
           durationMs,
-          inputFingerprint: gate.inputFingerprint ?? null,
+          inputFingerprint: gate.inputFingerprint ?? treeSha,
         },
         evidenceStoreOpts,
       );
@@ -214,7 +240,7 @@ export async function runCloseValidation({
    *
    * @returns {Promise<{ status: number }>}
    */
-  const dispatchGate = async (gate, signal) => {
+  const dispatchGate = async (gate, signal, configHash) => {
     log(
       `[close-validation] ▶ ${gate.name}${worktreePath ? ` (cwd=${worktreePath})` : ''}`,
     );
@@ -226,6 +252,20 @@ export async function runCloseValidation({
       log,
       signal,
       ...(gate.env ? { env: gate.env } : {}),
+      // Story #5278 — only the full-suite gate can end up *waiting* on the
+      // host lock, and only it is expensive enough for the wait to change the
+      // answer: whoever we queued behind may have deposited this gate's
+      // evidence while we sat there. Re-asking the same question the runner
+      // asked before the wait is the whole mechanism; a `{ status: 0 }`
+      // stands in for the spawn.
+      ...(gate.fullSuiteLock && configHash
+        ? {
+            skipIfSatisfied: () =>
+              evidenceVerdict(gate, configHash).skip
+                ? { status: 0 }
+                : undefined,
+          }
+        : {}),
       // Story #5173 — forwarded unconditionally (never a conditional spread
       // like the two below): `defaultGateRunner` already treats a falsy value
       // as "no lock", so a branch here would only add a decision point to the
@@ -263,7 +303,10 @@ export async function runCloseValidation({
       return;
     }
     if (execution.skip) {
-      skipped.push({ gate, reason: 'no-changed-files' });
+      skipped.push({
+        gate,
+        reason: execution.skipReason ?? 'no-changed-files',
+      });
       return;
     }
     const configHash = hashCommandConfig({
@@ -287,6 +330,7 @@ export async function runCloseValidation({
           tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
         },
         ac.signal,
+        configHash,
       );
     } catch (err) {
       result = { status: 1, error: err };
@@ -395,7 +439,10 @@ async function runSerialGates(
       return;
     }
     if (execution.skip) {
-      skipped.push({ gate, reason: 'no-changed-files' });
+      skipped.push({
+        gate,
+        reason: execution.skipReason ?? 'no-changed-files',
+      });
       continue;
     }
     const configHash = hashCommandConfig({
@@ -409,12 +456,16 @@ async function runSerialGates(
       continue;
     }
     const startedAt = evidenceActive ? evidenceClock() : 0;
-    const result = await dispatchGate({
-      ...gate,
-      cmd: execution.cmd,
-      args: execution.args,
-      tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
-    });
+    const result = await dispatchGate(
+      {
+        ...gate,
+        cmd: execution.cmd,
+        args: execution.args,
+        tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
+      },
+      undefined,
+      configHash,
+    );
     if (result.status !== 0) {
       failGate(
         gate,