mandrel 2.53.0 → 2.55.0

package/.agents/scripts/check-test-portability.js

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+
+/**
+ * Test-portability guard (Story #5284).
+ *
+ * Windows-only breaks reached `main` three times in one week through two
+ * source shapes a static reader can see, because the `windows-smoke` job is
+ * advisory: it is not a required check, so auto-merge lands a PR whose only
+ * red is that leg. Making the leg required is an operator ruleset decision;
+ * catching the shapes at authoring time is not, and that is what this guard
+ * does.
+ *
+ * Three shapes, all invisible on POSIX and all fatal on Windows:
+ *
+ *   1. **A `RegExp` built from an interpolated path.** `new RegExp(`source:
+ *      ${src}`)` is accidentally literal on POSIX — a temp path carries no
+ *      regex metacharacters. On Windows every separator is a backslash, so
+ *      `C:\Users\…` compiles to a pattern matching `C:Users…` and the
+ *      assertion can never match (PR #5276 fixed three of these).
+ *
+ *   2. **A dynamic `import()` of a plain filesystem path.** An absolute
+ *      Windows path is not a valid ESM specifier: the drive letter reads as
+ *      a URL scheme. The portable form is `pathToFileURL(p).href`, which is
+ *      why the suite's own dynamic imports launder through it.
+ *
+ *   3. **A file URL's `.pathname` read as a filesystem path.** `new
+ *      URL(import.meta.url).pathname` yields `/D:/a/repo` on Windows, and the
+ *      leading slash survives `path.resolve` as a second drive letter, so the
+ *      test dies on `D:\D:\a\repo\package.json`. `fileURLToPath` is the one
+ *      spelling that round-trips on both platforms. This shape reached `main`
+ *      the same day this guard did, through a test the guard did not yet read.
+ *
+ * ## What is deliberately NOT flagged
+ *
+ * Interpolating into a `RegExp` is not itself the defect — the suite does it
+ * constantly with heading text, flag names and label ids, and flagging those
+ * would make the guard noise. Only an interpolation whose *expression text*
+ * names a filesystem path counts (see {@link PATH_EXPRESSION}).
+ *
+ * The import rule is the same shape, and for the same reason. It fires on a
+ * path expression reaching `import()` unlaundered — not on "anything that is
+ * not a relative specifier". The suite's dynamic imports are overwhelmingly
+ * `import(SUT_URL)` and `` import(`${SUT_URL}?t=${tag}`) ``, where the URL was
+ * laundered once at module scope and the interpolation is a cache-busting
+ * query; those carry no path expression and are silent here, while
+ * `import(path.join(LIB, 'x.js'))` is exactly what reds.
+ *
+ * An interpolation that escapes itself for a regex — `.replace(/\\/g, …)`,
+ * `escapeRegExp(…)` — is laundered and not reported either.
+ *
+ * A line (or the line above it) carrying `portability-allow` opts out.
+ *
+ * Scope is `tests/**` plus `.agents/scripts/ ** /__tests__/**` by default.
+ * Unlike `check-test-temp-hygiene.js`'s raw-tmpdir lint this is not scoped to
+ * caller-passed globs: it runs over this repository's own tree in CI and
+ * ships in the payload for a consumer to wire up the same way.
+ *
+ * Exit codes: 1 when any finding is reported, 0 otherwise.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runAsCli } from './lib/cli-utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+/** Directories that are never test source, skipped wholesale during the walk. */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.worktrees',
+  '.git',
+  'temp',
+  'coverage',
+]);
+
+/** Repo-relative directory prefixes scanned for test sources. */
+const SCAN_ROOTS = ['tests', '.agents/scripts'];
+
+/** Opt-out marker, honoured on the finding's line or the line above it. */
+const LINT_ESCAPE = 'portability-allow';
+
+/**
+ * Expression text that names a filesystem path.
+ *
+ * Two families, kept separate because they fail differently. The call family
+ * is unambiguous — nothing but a path comes out of `path.join()`. The name
+ * family is a heuristic over identifiers, so it is anchored to the *final*
+ * segment of a member expression and deliberately excludes `…Path`: the
+ * suite uses that suffix for non-filesystem discriminators too (an
+ * `evidencePath` of `'per-run'`), and a guard that reds on those would be
+ * turned off rather than obeyed. `…Dir` / `…Root` / `src` / `dest` carry no
+ * such second meaning here.
+ */
+const PATH_EXPRESSION =
+  /(?:\b(?:path\.(?:join|resolve|dirname|relative|normalize)|os\.tmpdir|process\.cwd|fileURLToPath|makeTempDir|mkdtemp(?:Sync)?)\s*\(|\b__(?:dirname|filename)\b|(?:^|[^\w$.])(?:src|dst|dest|dir|cwd|tmpdir|workCwd|repoRoot)\b|[\w$]+(?:Dir|Root|Cwd|Tmpdir)\b)/;
+
+/**
+ * An argument already laundered into a URL, in any of the three shapes the
+ * suite uses.
+ */
+const URL_LAUNDERED =
+  /\bpathToFileURL\s*\(|\bnew\s+URL\s*\(|\bimport\.meta\.url\b/;
+
+/**
+ * An interpolation that escapes itself before reaching the pattern. The
+ * separator problem is solved once the backslashes are doubled, so escaping a
+ * path in is a correct use, not the defect.
+ */
+const REGEX_ESCAPED =
+  /\.replace(?:All)?\s*\(|\bescapeReg(?:Exp|ex)\b|\bregexEscape\b/;
+
+/**
+ * A **file** URL's `.pathname` read as though it were a filesystem path.
+ *
+ * Scoped to URLs built from a file source (`import.meta.url`, `pathToFileURL`,
+ * a `file://` literal) because `.pathname` on an http URL is a correct read
+ * with no filesystem meaning. On Windows the property yields `/D:/a/repo`,
+ * whose leading slash survives `path.resolve` as a second drive letter —
+ * `D:\D:\a\repo` — so the failure is an ENOENT naming an impossible path
+ * rather than anything that points at the real defect.
+ */
+const FILE_URL_PATHNAME =
+  /\bnew\s+URL\s*\([^()]*(?:import\.meta\.url|pathToFileURL|file:\/\/)[^()]*\)\s*\.pathname/g;
+
+/**
+ * Blank out comments while preserving every byte offset and newline, so a
+ * finding's line number survives and the scan cannot be satisfied — or
+ * tripped — by prose.
+ *
+ * String and template literals are left intact on purpose: the suite builds
+ * child-process source inside template literals, and the `await import(...)`
+ * in one of those is real code that runs on Windows like any other.
+ *
+ * Regex literals are not tracked. A `//` inside one would be read as a
+ * comment start; the shapes this guard matches do not occur inside regex
+ * literals, so the trade is a simpler scanner for no measured loss.
+ *
+ * @param {string} src
+ * @returns {string} `src` with comment bodies replaced by spaces
+ */
+function blankComments(src) {
+  const out = src.split('');
+  let i = 0;
+  const blank = (from, to) => {
+    for (let k = from; k < to; k += 1) if (out[k] !== '\n') out[k] = ' ';
+  };
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === '`') {
+      i = skipStringLiteral(src, i);
+      continue;
+    }
+    if (ch === '/' && src[i + 1] === '/') {
+      const end = src.indexOf('\n', i);
+      const stop = end === -1 ? src.length : end;
+      blank(i, stop);
+      i = stop;
+      continue;
+    }
+    if (ch === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      const stop = end === -1 ? src.length : end + 2;
+      blank(i, stop);
+      i = stop;
+      continue;
+    }
+    i += 1;
+  }
+  return out.join('');
+}
+
+/**
+ * Index just past the string literal opening at `start`.
+ *
+ * @param {string} src
+ * @param {number} start index of the opening quote
+ * @returns {number}
+ */
+function skipStringLiteral(src, start) {
+  const quote = src[start];
+  let i = start + 1;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    if (quote !== '`' && ch === '\n') return i;
+    i += 1;
+  }
+  return i;
+}
+
+/**
+ * Blank the contents of quoted string literals in `text`, leaving template
+ * literals alone.
+ *
+ * A specifier's own characters are not a path expression: without this,
+ * `import('../lib/auto-merge-cwd.js')` matches the `cwd` name signal on a
+ * filename. Template literals are left intact because their `${…}` bodies are
+ * exactly what both rules need to read.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function blankStrings(text) {
+  const out = text.split('');
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === '`') {
+      i = skipStringLiteral(text, i);
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      const end = skipStringLiteral(text, i);
+      for (let k = i + 1; k < end - 1; k += 1) out[k] = ' ';
+      i = end;
+      continue;
+    }
+    i += 1;
+  }
+  return out.join('');
+}
+
+/**
+ * Capture the text between the parenthesis at `open` and its match.
+ *
+ * Balanced rather than line-based because both shapes span lines in practice
+ * — a `pathToFileURL(path.resolve(…)).href` argument runs to six.
+ *
+ * @param {string} src
+ * @param {number} open index of the opening `(`
+ * @returns {string|null} the argument text, or `null` when unbalanced
+ */
+function captureArgs(src, open) {
+  let depth = 0;
+  let i = open;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      i = skipStringLiteral(src, i);
+      continue;
+    }
+    if (ch === '(') depth += 1;
+    else if (ch === ')') {
+      depth -= 1;
+      if (depth === 0) return src.slice(open + 1, i);
+    }
+    i += 1;
+  }
+  return null;
+}
+
+/**
+ * Every `${…}` substitution body in `text`, at one level of nesting.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function substitutions(text) {
+  const found = [];
+  for (let i = 0; i < text.length - 1; i += 1) {
+    if (text[i] !== '$' || text[i + 1] !== '{') continue;
+    let depth = 0;
+    for (let k = i + 1; k < text.length; k += 1) {
+      if (text[k] === '{') depth += 1;
+      else if (text[k] === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          found.push(text.slice(i + 2, k));
+          i = k;
+          break;
+        }
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Line number (1-based) of `index` within `src`.
+ *
+ * @param {string} src
+ * @param {number} index
+ * @returns {number}
+ */
+function lineOf(src, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < src.length; i += 1) {
+    if (src[i] === '\n') line += 1;
+  }
+  return line;
+}
+
+/**
+ * Whether the finding at `line` (1-based) is opted out by a marker on that
+ * line or the one above it.
+ *
+ * @param {string[]} lines original source lines
+ * @param {number} line
+ * @returns {boolean}
+ */
+function isSuppressed(lines, line) {
+  const here = lines[line - 1] ?? '';
+  const above = line >= 2 ? (lines[line - 2] ?? '') : '';
+  return here.includes(LINT_ESCAPE) || above.includes(LINT_ESCAPE);
+}
+
+/**
+ * Scan one file's source for both shapes.
+ *
+ * @param {string} rel repo-relative POSIX path, used in the report
+ * @param {string} source raw file contents
+ * @returns {{ file: string, line: number, shape: string, text: string }[]}
+ */
+function scanSource(rel, source) {
+  const src = blankComments(source);
+  const lines = source.split('\n');
+  const findings = [];
+  const add = (index, shape, detail) => {
+    const line = lineOf(src, index);
+    if (isSuppressed(lines, line)) return;
+    findings.push({ file: rel, line, shape, text: detail });
+  };
+
+  for (const m of src.matchAll(/\bnew\s+RegExp\s*\(/g)) {
+    const open = m.index + m[0].length - 1;
+    const args = captureArgs(src, open);
+    if (args === null) continue;
+    const offender = substitutions(args).find(
+      (sub) =>
+        PATH_EXPRESSION.test(blankStrings(sub)) && !REGEX_ESCAPED.test(sub),
+    );
+    if (offender !== undefined) {
+      add(m.index, 'regexp-from-path', `\${${offender.trim()}}`);
+    }
+  }
+
+  for (const m of src.matchAll(FILE_URL_PATHNAME)) {
+    add(m.index, 'url-pathname-as-path', m[0].trim().replace(/\s+/g, ' '));
+  }
+
+  for (const m of src.matchAll(/(?<![\w$.])import\s*\(/g)) {
+    const open = m.index + m[0].length - 1;
+    const args = captureArgs(src, open);
+    if (args === null) continue;
+    if (PATH_EXPRESSION.test(blankStrings(args)) && !URL_LAUNDERED.test(args)) {
+      add(m.index, 'import-raw-path', args.trim().replace(/\s+/g, ' '));
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Is `rel` a test source this guard scans?
+ *
+ * @param {string} rel repo-relative POSIX path
+ * @returns {boolean}
+ */
+function isTestSource(rel) {
+  if (!/\.(?:js|mjs|cjs)$/.test(rel)) return false;
+  if (rel.startsWith('tests/')) return true;
+  return rel.startsWith('.agents/scripts/') && rel.includes('/__tests__/');
+}
+
+/**
+ * Walk `root` for scannable test sources, POSIX-relative and sorted.
+ *
+ * @param {string} root
+ * @param {typeof fs} fsImpl
+ * @returns {string[]}
+ */
+function listTestSources(root, fsImpl) {
+  const out = [];
+  const walk = (dir, prefix) => {
+    if (!fsImpl.existsSync(dir)) return;
+    for (const ent of fsImpl.readdirSync(dir, { withFileTypes: true })) {
+      if (SKIP_DIRS.has(ent.name)) continue;
+      const rel = prefix ? `${prefix}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) walk(path.join(dir, ent.name), rel);
+      else if (ent.isFile() && isTestSource(rel)) out.push(rel);
+    }
+  };
+  for (const scanRoot of SCAN_ROOTS) {
+    walk(path.join(root, scanRoot), scanRoot);
+  }
+  return out.sort();
+}
+
+/**
+ * Collect every finding under `root`.
+ *
+ * @param {string} root repository root to scan
+ * @param {{ fsImpl?: typeof fs }} [deps]
+ * @returns {{ file: string, line: number, shape: string, text: string }[]}
+ */
+function findPortabilityIssues(root, { fsImpl = fs } = {}) {
+  const findings = [];
+  for (const rel of listTestSources(root, fsImpl)) {
+    const source = fsImpl.readFileSync(path.join(root, rel), 'utf8');
+    findings.push(...scanSource(rel, source));
+  }
+  return findings;
+}
+
+/** Remedy line printed under each shape, keyed by the shape's id. */
+const REMEDIES = Object.freeze({
+  'regexp-from-path':
+    'a path interpolated into a RegExp is literal on POSIX and escaped on Windows — assert with `includes()`, or escape the interpolation.',
+  'import-raw-path':
+    'a filesystem path is not a valid ESM specifier on Windows — import `pathToFileURL(p).href`.',
+  'url-pathname-as-path':
+    "a file URL's `.pathname` is a URL path, not a filesystem path: on Windows it reads `/D:/…`, and resolving it yields `D:\\D:\\…` — use `fileURLToPath(url)`.",
+});
+
+/**
+ * Parse argv into normalised options.
+ *
+ * @param {string[]} argv
+ * @returns {{ root: string, json: boolean }}
+ */
+function parseArgv(argv) {
+  let root = REPO_ROOT;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--json') json = true;
+    else if (argv[i] === '--root') {
+      i += 1;
+      root = path.resolve(String(argv[i] ?? '.'));
+    }
+  }
+  return { root, json };
+}
+
+/**
+ * Execute the guard and return the process exit code.
+ *
+ * @param {{ root: string, json: boolean }} opts
+ * @param {(line: string) => void} [log]
+ * @param {{ fsImpl?: typeof fs }} [deps]
+ * @returns {number}
+ */
+function runPortability(
+  opts,
+  log = (l) => process.stdout.write(`${l}\n`),
+  deps,
+) {
+  const findings = findPortabilityIssues(opts.root, deps);
+  if (opts.json) {
+    log(JSON.stringify({ ok: findings.length === 0, findings }, null, 2));
+    return findings.length === 0 ? 0 : 1;
+  }
+  if (findings.length === 0) {
+    log(
+      '[test-portability] OK — no path-derived RegExp or raw-path dynamic import in test sources.',
+    );
+    return 0;
+  }
+  log(
+    `[test-portability] FAIL — ${findings.length} Windows-hostile shape(s) in test sources:`,
+  );
+  for (const f of findings) {
+    log(`  ${f.file}:${f.line}  [${f.shape}]  ${f.text}`);
+  }
+  for (const shape of new Set(findings.map((f) => f.shape))) {
+    log(`[test-portability] ${shape}: ${REMEDIES[shape]}`);
+  }
+  log(
+    `[test-portability] the windows-smoke job is advisory, so these land on main unnoticed. Mark a deliberate exception with '${LINT_ESCAPE}: <reason>' on the line or the line above.`,
+  );
+  return 1;
+}
+
+runAsCli(
+  import.meta.url,
+  async () => runPortability(parseArgv(process.argv.slice(2))),
+  {
+    source: 'check-test-portability',
+    propagateExitCode: true,
+    usage: {
+      invocation:
+        'node .agents/scripts/check-test-portability.js [--json] [--root <dir>]',
+      summary:
+        'Static guard for the two Windows-only shapes that reach main through the advisory windows-smoke job: a RegExp built from an interpolated filesystem path, and a dynamic import() of a raw path instead of a pathToFileURL href.',
+      flags: [
+        [
+          '--json',
+          'Emit { ok, findings[] } as JSON instead of the text report.',
+        ],
+        ['--root <dir>', 'Repository root to scan (default: this repo root).'],
+      ],
+      notes: [
+        "A line (or the line above it) carrying 'portability-allow' opts out.",
+        'Scope: tests/** plus .agents/scripts/**/__tests__/**.',
+        'Exit codes:\n  0  clean\n  1  at least one finding',
+      ],
+    },
+  },
+);

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

@@ -17,8 +17,17 @@
  *      `npm run test:coverage`, serialized behind the host-level full-suite
  *      lock (Story #5173) so two concurrent runs on one checkout do not race;
  *      write a fresh capture stamp on success and propagate the exit code.
- *      With `delivery.execution.requireCreditedCapture` set, step 4 refuses
- *      instead of spawning, so the cost is never paid unannounced.
+ *      With `--require-credited`, step 4 refuses instead of spawning, so the
+ *      cost is never paid unannounced.
+ *
+ * **`--require-credited` is an argument, not a config read (Story #5278).**
+ * `delivery.execution.requireCreditedCapture` is a policy about *close*: the
+ * close gate must not silently pay for a suite the worker was supposed to
+ * have deposited. Reading it here applied the refusal to every invocation
+ * including the worker's depositing one, so turning the policy on left no
+ * path that could ever deposit and bricked the CRAP gate outright. The policy
+ * now lives where it is enforced — `close-validation/gates.js` passes this
+ * flag when the consumer sets it — and a bare invocation always runs.
  *
  * Step 3 is preceded by the changed-file skip when
  * `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` is on
@@ -29,7 +38,7 @@
  *   0 — coverage is fresh (or capture skipped/succeeded).
  *   1 — capture run failed (broken tests or coverage-threshold breach), or
  *       the run was refused because it carried no credit and
- *       `delivery.execution.requireCreditedCapture` is set. The caller MUST
+ *       `--require-credited` was passed. The caller MUST
  *       surface this — silently passing here would defeat the CRAP gate's
  *       `requireCoverage: true` policy.
  */
@@ -56,17 +65,20 @@ import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
  * Parse the full `process.argv` (index 2 onward) into the capture options.
  *
  * @param {string[]} argv
- * @returns {{ skipWhenNoCrapFiles: boolean, ref: string, cwd: string }}
+ * @returns {{ skipWhenNoCrapFiles: boolean, requireCredited: boolean, ref: string, cwd: string }}
  */
 export function parseArgs(argv) {
   const out = {
     skipWhenNoCrapFiles: false,
+    // Story #5278 — an ARGUMENT, never a config read. See `runCoverageCapture`.
+    requireCredited: false,
     ref: 'main',
     cwd: process.cwd(),
   };
   for (let i = 2; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--skip-when-no-crap-files') out.skipWhenNoCrapFiles = true;
+    else if (a === '--require-credited') out.requireCredited = true;
     else if (a === '--ref') out.ref = argv[++i] ?? out.ref;
     else if (a === '--cwd') out.cwd = argv[++i] ?? out.cwd;
   }
@@ -116,11 +128,6 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
   const args = parseArgs(argv);
   const config = resolveConfigImpl({ cwd: args.cwd });
   const { crap, coverage } = getQualityImpl(config);
-  // Read once here, where the config is already in scope, and thread it into
-  // whichever capture path reaches a spawn. Default false — an unconfigured
-  // consumer gets the announcement and the run, exactly as before.
-  const requireCreditedCapture =
-    config?.delivery?.execution?.requireCreditedCapture === true;
 
   if (crap.enabled === false) {
     logger.info('[coverage-capture] CRAP gate disabled — skipping capture.');
@@ -154,7 +161,7 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
   // Whichever capture path gets here spawns through both without knowing
   // about either.
   const capture = creditedCapture(lockedCapture(runCaptureImpl, config), {
-    requireCredited: requireCreditedCapture,
+    requireCredited: args.requireCredited,
     logger,
   });
 

package/.agents/scripts/evidence-gate.js

@@ -41,6 +41,7 @@ import {
   hashCommandConfig,
   recordPass,
   shouldSkip,
+  treeFingerprint,
 } from './lib/validation-evidence.js';
 
 /**
@@ -94,6 +95,28 @@ function resolveHeadShaDefault(cwd, gitSpawnFn) {
   return sha.length > 0 ? sha : null;
 }
 
+/**
+ * The pair of keys an evidence record is written and read under: the commit
+ * this gate ran at, and the content identity of the tree it ran against
+ * (Story #5278).
+ *
+ * Both are read from the **spawn** cwd — the Story worktree when one is
+ * supplied — so the keys describe the tree the gate actually saw. The tree
+ * fingerprint is what keeps this gate credited across close's own base-sync
+ * fast-forward, which moves HEAD between the deposit and the gates that would
+ * spend it; see `validation-evidence.js#treeFingerprint`.
+ *
+ * @param {{ spawnCwd: string, gitSpawnFn: Function, useEvidence: boolean }} args
+ * @returns {{ headSha: string|null, inputFingerprint: string|null }}
+ */
+function resolveEvidenceKeys({ spawnCwd, gitSpawnFn, useEvidence }) {
+  if (!useEvidence) return { headSha: null, inputFingerprint: null };
+  return {
+    headSha: resolveHeadShaDefault(spawnCwd, gitSpawnFn),
+    inputFingerprint: treeFingerprint(spawnCwd, gitSpawnFn),
+  };
+}
+
 /**
  * Runner-shaped entry-point: takes the parsed wrapper args + runner args and
  * executes the gate. Pure-ish (modulo IO) — all side-effects are routed via
@@ -168,9 +191,11 @@ export async function runEvidenceGate(params, deps = {}) {
   const spawnCwd = worktreePath ?? cwd;
   const [cmd, ...cmdArgs] = runnerArgs;
   const configHash = hashCommandConfig({ cmd, args: cmdArgs, cwd: spawnCwd });
-  const headSha = useEvidence
-    ? resolveHeadShaDefault(spawnCwd, gitSpawnFn)
-    : null;
+  const { headSha, inputFingerprint } = resolveEvidenceKeys({
+    spawnCwd,
+    gitSpawnFn,
+    useEvidence,
+  });
 
   if (useEvidence && headSha) {
     const verdict = shouldSkipFn(
@@ -179,13 +204,14 @@ export async function runEvidenceGate(params, deps = {}) {
         gateName: gate,
         currentSha: headSha,
         configHash,
+        inputFingerprint,
       },
       evidenceStoreOpts,
     );
     if (verdict.skip) {
       const ts = verdict.record?.timestamp ?? 'n/a';
       logger.info(
-        `[evidence-gate] ⏭ ${gate} skipped (evidence match: SHA=${headSha.slice(0, 7)}, recorded ${ts})`,
+        `[evidence-gate] ⏭ ${gate} skipped (${verdict.reason}: SHA=${headSha.slice(0, 7)}, recorded ${ts})`,
       );
       return { status: 0, skipped: true };
     }
@@ -220,6 +246,7 @@ export async function runEvidenceGate(params, deps = {}) {
           configHash,
           exitCode: 0,
           durationMs: Date.now() - startedAt,
+          inputFingerprint,
         },
         evidenceStoreOpts,
       );