@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/check_kernel_edit_ratified.ts

@@ -59,23 +59,38 @@
  *
  * Inputs:
  *   --base-ref REF    git ref to diff against (default: origin/main, then main)
- *   --files F [F …]   override the changed-file list (testing and CI)
+ *   --files F [F …]   override the changed-file list (testing); CI derives
+ *                     the list from git with --base-ref, because a hosted
+ *                     PR file list names a rename by its destination only
  *   --root DIR        repo root the diff and artifacts are read from (testing)
+ *   --rev REV         the commit the gated content and the artifacts are read
+ *                     at (default HEAD) — Git objects, never the working tree,
+ *                     so an uncommitted edit can neither pass nor fail the gate.
+ *                     Without --files it is resolved ONCE to a commit id, and
+ *                     that id — not the name — feeds the diff, the digest and
+ *                     the record read, so a ref that moves mid-run cannot pair
+ *                     one commit's file list with another commit's content
  *   --policy-root DIR where the quorum policy is read from (testing); defaults
  *                     to THIS script's tree, so a base-revision run reads the
  *                     base's policy rather than one the candidate lowered
  *   --quiet           verdict line only
  *
+ * An option that takes a value and is given none is a refusal (exit 1), never
+ * a silent default.
+ *
  * Exit codes: 0 = pass (or nothing gated) · 1 = fail · 3 = internal error.
  */
 
-import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { GateLedger } from './_lib/gate_ledger.js';
-import { dispatchImportClosure, verdictModules } from './_lib/dispatch_import_closure.js';
+import {
+    dispatchImportClosure,
+    verdictModules,
+    type ClosureTree,
+} from './_lib/dispatch_import_closure.js';
 import { is_kernel_rule } from './_lib/kernel_rules.js';
 import { reportScanned } from './_lib/scan_scope.js';
 import {
@@ -85,6 +100,18 @@ import {
     readRequiredProviders,
     type RatificationProblem,
 } from './_lib/ratification_artifact.js';
+import {
+    DEFAULT_REVISION,
+    GatedSubjectRefusal,
+    changedFilesBetween,
+    fileAtRevision,
+    optionValue,
+    refExists,
+    resolveRevision,
+    subjectOf,
+    treeAtRevision,
+    type SubjectReading,
+} from './_lib/ratification_subject.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
@@ -102,6 +129,30 @@ export const READER_PATH = 'src/scripts/_lib/ratification_artifact.ts';
  */
 export const CLOSURE_READER_PATH = 'src/scripts/_lib/dispatch_import_closure.ts';
 
+/**
+ * Modules of this gate's static import closure that run inside the verdict, so
+ * an edit to one is an edit to the gate:
+ *
+ *   - `_lib/adr_frontmatter.ts` parses the record's header, verdict included;
+ *   - `_lib/gate_ledger.ts` and `_lib/scan_scope.ts` run before the exit code is
+ *     returned, so either could end the process first;
+ *   - `_lib/ratification_subject.ts` computes the digest a record must carry.
+ *
+ * `_lib/kernel_rules.ts` is already gated as plumbing. A change that gates a
+ * module and edits it at once is digested over different files by the base
+ * revision's gate and by its own, so no single record answers for both: a
+ * module joins this list in a change that leaves its bytes alone. The writer
+ * CLIs `src/scripts/ratification_subject.ts` and `src/scripts/ratification_header.ts`
+ * and the contract stay outside by owner decision (2026-10-15): the gate does
+ * not import them, recomputes the digest and reads only the record.
+ */
+export const MECHANISM_IMPORT_PATHS: readonly string[] = [
+    'src/scripts/_lib/adr_frontmatter.ts',
+    'src/scripts/_lib/gate_ledger.ts',
+    'src/scripts/_lib/ratification_subject.ts',
+    'src/scripts/_lib/scan_scope.ts',
+];
+
 /** The in-repo quorum policy. Present on every runner; absent means refuse. */
 export const POLICY_PATH = 'src/config/ratification-policy.json';
 
@@ -182,10 +233,11 @@ const GOVERNANCE_HOOK_RE = /^src\/scripts\/hooks\/block_[a-z0-9_]+\.ts$/;
  *     from that list removes a rule from this gate's own reach — the one edit
  *     that could quietly narrow the gate while every other path kept working.
  *
- * Both are also denied at tool-call time, `dispatch_hook.ts` through the
- * plumbing guard's source set and `kernel_rules.ts` through the kernel-rule
- * write guard, so the pairing of deny-plus-record matches what the YAML sources
- * already had.
+ * No `pre_tool_use` concern bound in `hook_manifest.yaml` denies an edit to
+ * either: the plumbing guard protects four generated build outputs and names
+ * `dispatch_hook.ts` only where it reads one, and the kernel-rule write guard
+ * imports `kernel_rules.ts` without protecting it. For these two paths the
+ * record this gate demands is the only layer, not a second one beside a deny.
  *
  * The compiled tables are REGENERATED, not hand-edited, by
  * `./scripts-run src/scripts/compile_hook_manifest --table manifest|host-lowering`,
@@ -243,12 +295,18 @@ export function derivedPlumbing(root: string = REPO): readonly string[] {
  * strips the names that classed it, so declassifying one is itself a gated
  * edit of it.
  *
- * Meaningful only where the two trees differ — in CI, where the gate's code is
- * the base revision's and `root` is the head. A local run with `root` equal to
- * the gate's own tree sees no arrivals, and says nothing it cannot measure.
+ * Each side is a checkout path or a commit's objects (see `derivedFor`). A
+ * checkout equal to `root` is the same tree on both sides and has no arrivals.
  */
-export function closureArrivals(root: string, baseRoot: string = REPO): string[] {
-    if (path.resolve(root) === path.resolve(baseRoot)) {
+export function closureArrivals(
+    root: string | ClosureTree,
+    baseRoot: string | ClosureTree = REPO,
+): string[] {
+    if (
+        typeof root === 'string' &&
+        typeof baseRoot === 'string' &&
+        path.resolve(root) === path.resolve(baseRoot)
+    ) {
         return [];
     }
     const base = new Set(dispatchImportClosure(baseRoot).map((e) => e.path));
@@ -260,13 +318,19 @@ export function closureArrivals(root: string, baseRoot: string = REPO): string[]
 /**
  * A kernel rule, in the source tree or in any projection.
  *
- * The reach is deliberately the same as the retired hook's: any path whose
- * basename is a kernel rule filename and which sits under a `rules/` path
- * segment. `src/rules/commit-policy.md` is the source; `.claude/rules/…`,
- * `.augment/rules/…` and `dist/agent-src/rules/…` are projections. A
- * hand-edited projection reaches consumers without the source ever changing,
- * so narrowing this to the source alone would have quietly dropped half of
- * what the deny covered — a retirement is not supposed to be a reduction.
+ * The reach is deliberately the same as the tool-call deny's, and that deny is
+ * bound rather than retired: `block-kernel-rule-writes` has a row in
+ * `src/scripts/hook_manifest.yaml` and sits in the `pre_tool_use` list of three
+ * host sections there. The header above says why both mechanisms stand; this
+ * sentence described the deny as already withdrawn and contradicted it.
+ *
+ * The reach: any path whose basename is a kernel rule filename and which sits
+ * under a `rules/` path segment. `src/rules/commit-policy.md` is the source;
+ * `.claude/rules/…`, `.augment/rules/…` and `dist/agent-src/rules/…` are
+ * projections. A hand-edited projection reaches consumers without the source
+ * ever changing, so narrowing this to the source alone would cover half of
+ * what the deny covers — the gate that reaches every host is not supposed to
+ * be the narrower of the two.
  *
  * A kernel-NAMED file outside a `rules/` directory (a doc, a fixture) is not a
  * rule file and is not matched.
@@ -281,6 +345,22 @@ export interface GatedPaths {
     self: boolean;
 }
 
+/**
+ * True for a file of the ratification mechanism itself — the one list both the
+ * classification and the subject digest read.
+ */
+export function isMechanismPath(p: string): boolean {
+    return (
+        p === SELF_PATH ||
+        p === READER_PATH ||
+        p === CLOSURE_READER_PATH ||
+        p === POLICY_PATH ||
+        p === WORKFLOW_PATH ||
+        ANCHOR_PATHS.includes(p) ||
+        MECHANISM_IMPORT_PATHS.includes(p)
+    );
+}
+
 /** Partition a changed-file list into the surfaces this gate watches. */
 export function classifyPaths(
     files: readonly string[],
@@ -296,14 +376,7 @@ export function classifyPaths(
         if (p === '') {
             continue;
         }
-        if (
-            p === SELF_PATH ||
-            p === READER_PATH ||
-            p === CLOSURE_READER_PATH ||
-            p === POLICY_PATH ||
-            p === WORKFLOW_PATH ||
-            ANCHOR_PATHS.includes(p)
-        ) {
+        if (isMechanismPath(p)) {
             self = true;
             continue;
         }
@@ -354,33 +427,92 @@ export function configuredProviderCount(policyRoot: string): number | null {
     }
 }
 
-function gitChangedFiles(baseRef: string, root: string): string[] | null {
-    const res = spawnSync('git', ['diff', '--name-only', `${baseRef}...HEAD`], {
-        cwd: root,
-        encoding: 'utf8',
-    });
-    if (res.status !== 0) {
-        return null;
-    }
-    return (res.stdout ?? '').split('\n').filter((l) => l.trim() !== '');
-}
-
 function resolveBaseRef(explicit: string | null, root: string): string {
     if (explicit !== null) {
         return explicit;
     }
     for (const candidate of ['origin/main', 'origin/master', 'main', 'master']) {
-        const res = spawnSync('git', ['rev-parse', '--verify', candidate], {
-            cwd: root,
-            stdio: ['ignore', 'ignore', 'ignore'],
-        });
-        if (res.status === 0) {
+        if (refExists(root, candidate)) {
             return candidate;
         }
     }
     return 'HEAD~1';
 }
 
+/**
+ * The plumbing closure this gate classifies with: the base side's verdict
+ * modules, the head side's, and every module arriving in the closure — so a
+ * module present on either side is watched.
+ *
+ * BOTH SIDES ARE COMMITS, READ FROM GIT OBJECTS IN `root`, in every execution
+ * shape. The head is `revision`, the commit the digest and the record are read
+ * at, so an uncommitted import edit cannot add or hide a module. The base is
+ * `baseRef`, resolved the way the diff's base is. The same two commits
+ * therefore yield the same gated set whichever copy of this script runs.
+ *
+ * Why the base is not this script's checkout: CI runs the base revision's copy
+ * with `--root <head>`, where that checkout IS the base, but a local run
+ * (pre-push, `task ci`, the subject CLI) executes the head's copy, whose
+ * checkout is the head. Compared with itself it saw no arrivals, digested fewer
+ * files than CI and refused the record CI required (PR #2371).
+ *
+ * One residue keeps the old base: a call with no `baseRef` over a `root` that
+ * is not this checkout — a direct call, or `--files` without `--base-ref` —
+ * compares against this script's checkout. A run that builds its own diff
+ * always passes the base it diffed against.
+ *
+ * `headCommit` is already a commit id; the base ref is resolved here.
+ *
+ * THROWS a {@link GatedSubjectRefusal} when the base does not resolve or the
+ * object store cannot be read.
+ */
+function derivedFor(root: string, baseRef: string | null, headCommit: string): readonly string[] {
+    const verdictsOf = (tree: ClosureTree): string[] =>
+        dispatchImportClosure(tree)
+            .filter((e) => e.class === 'verdict')
+            .map((e) => e.path);
+    const head = treeAtRevision(root, headCommit);
+    if (baseRef === null && path.resolve(root) !== REPO) {
+        return [...new Set([...derivedPlumbing(), ...verdictsOf(head), ...closureArrivals(head)])];
+    }
+    const base = treeAtRevision(root, resolveRevision(root, resolveBaseRef(baseRef, root)));
+    return [...new Set([...verdictsOf(base), ...verdictsOf(head), ...closureArrivals(head, base)])];
+}
+
+/**
+ * The `subject` digest a record must carry to answer for this diff, AND the
+ * gated files it covers — from one classification, never two.
+ *
+ * Exported so that whoever WRITES a record asks the gate for the digest rather
+ * than recomputing it from a second reading of the membership rule. A writer
+ * that derived its own list would be the second definition of "gated" that
+ * `ratification_subject`'s header exists to prevent — and it would fail only
+ * for the diffs where the two lists disagree, which are exactly the diffs that
+ * widen the gated set.
+ *
+ * RETURNS BOTH HALVES so that the coverage list printed beside a digest is the
+ * list that digest was taken over: a list classified separately, with a
+ * different `derived` input, could disagree with it — the false reassurance
+ * that list exists to prevent.
+ *
+ * The content is read at `revision` from Git objects, so the digest a writer
+ * prints and the digest this gate checks agree exactly when both name the
+ * same commit — the one the reviewers were shown.
+ *
+ * THROWS a {@link GatedSubjectRefusal} when the revision does not resolve, git
+ * cannot run, or a gated path escapes the tree or is not absent or a regular
+ * file in that commit. Callers turn that into a refusal; none may continue.
+ */
+export function expectedSubjectFor(
+    files: readonly string[],
+    root: string,
+    revision: string = DEFAULT_REVISION,
+    baseRef: string | null = null,
+): SubjectReading {
+    const commit = resolveRevision(root, revision);
+    return subjectOf(root, files, derivedFor(root, baseRef, commit), commit);
+}
+
 export interface GateResult {
     exitCode: 0 | 1 | 3;
     lines: string[];
@@ -392,14 +524,10 @@ export function evaluate(
     files: readonly string[],
     root: string,
     providerCount: number | null,
+    revision: string = DEFAULT_REVISION,
+    baseRef: string | null = null,
 ): GateResult {
     const lines: string[] = [];
-    // The union of the closure read from the tree under review and from this
-    // script's own tree: under CI the gate code is the base revision's and
-    // `root` is the head, so a module present on either side is watched.
-    const gated = classifyPaths(files, [
-        ...new Set([...derivedPlumbing(), ...derivedPlumbing(root), ...closureArrivals(root)]),
-    ]);
     const scanned = files.length;
 
     // Every changed path is a planned target: the gate's denominator is the
@@ -407,11 +535,33 @@ export function evaluate(
     // counting rather than a silence.
     const ledger = new GateLedger('check_kernel_edit_ratified');
     ledger.plan(files.map((f) => f.replace(/\\/g, '/').trim()).filter((f) => f !== ''));
+
+    // The revision is resolved once and the closure computed once, then both
+    // are handed to the digest below, so the classification and the digest
+    // read one head commit and one base.
+    let derived: readonly string[];
+    let headCommit: string;
+    try {
+        headCommit = resolveRevision(root, revision);
+        derived = derivedFor(root, baseRef, headCommit);
+    } catch (err) {
+        if (!(err instanceof GatedSubjectRefusal)) {
+            throw err;
+        }
+        lines.push(`❌  ${err.message}`);
+        for (const target of ledger.unaccountedTargets()) {
+            ledger.fail(target, 'the dispatcher closure could not be read at the named commits');
+        }
+        const tally = ledger.finalize();
+        lines.push('', `ledger: planned ${tally.planned} · completed 0 · failed ${tally.failed} · out_of_scope 0`);
+        return { exitCode: 1, lines, scanned };
+    }
+    const gated = classifyPaths(files, derived);
     const gatedSet = new Set<string>([
         ...gated.kernelRules,
         ...gated.governanceHooks,
         ...gated.plumbing,
-        ...(gated.self ? [SELF_PATH] : []),
+        ...files.map((f) => f.replace(/\\/g, '/').trim()).filter(isMechanismPath),
     ]);
     const artifactSet = new Set(ratificationArtifactsIn(files));
     for (const target of ledger.unaccountedTargets()) {
@@ -442,6 +592,44 @@ export function evaluate(
         );
     };
 
+    /**
+     * The digest of this diff's gated content, recomputed from the tree rather
+     * than read from the record.
+     *
+     * WHICH FILES COUNT IS DECIDED BY THIS CODE, AND IN CI THIS CODE IS THE BASE
+     * REVISION'S. The workflow runs the base's copy of this gate with `--root
+     * <head>`, so the membership rule a candidate is judged by is one the
+     * candidate did not write — and the same holds for the digest, which uses
+     * this module's `classifyPaths` and the derived list computed just above.
+     * A change that widens the gated set is therefore judged, and written, by
+     * the same list.
+     */
+    let expectedSubject: string;
+    let commit: string | null;
+    try {
+        ({ digest: expectedSubject, revision: commit } = subjectOf(root, files, derived, headCommit));
+    } catch (err) {
+        // ONE boundary for EVERY failure of the subject computation: each is
+        // a subclass of `GatedSubjectRefusal`, so a gate that advertises a
+        // refusal cannot crash on one of its own refusal classes instead.
+        //
+        // Fail closed, and BEFORE the "nothing to ratify" exit: a revision
+        // that does not resolve, a git that cannot run, a gated path outside
+        // the tree or one that is not absent or a regular file in the commit
+        // is content the gate cannot describe, and a gate that cannot
+        // describe the content cannot say a record answers for it.
+        //
+        // NARROW AND TYPED, never a blanket catch: wrapping everything would
+        // report a defect in this gate as a property of the checkout. Anything
+        // that is not a refusal is a bug here and stays a crash.
+        if (!(err instanceof GatedSubjectRefusal)) {
+            throw err;
+        }
+        lines.push(`❌  ${err.message}`);
+        close(false);
+        return { exitCode: 1, lines, scanned };
+    }
+
     if (!requiresRatification(gated)) {
         lines.push(
             '✅  no kernel rule, governance hook, hook-plumbing source or self edit in the ' +
@@ -455,7 +643,7 @@ export function evaluate(
         ...gated.kernelRules.map((p) => `kernel rule ${p}`),
         ...gated.governanceHooks.map((p) => `governance hook ${p}`),
         ...gated.plumbing.map((p) => `hook-plumbing source ${p}`),
-        ...(gated.self ? ['the ratification mechanism itself (gate, reader, policy or workflow)'] : []),
+        ...(gated.self ? ['the ratification mechanism itself (gate, its imports, policy or workflow)'] : []),
     ];
     lines.push(`Gated surfaces in this diff (${touched.length}):`);
     for (const t of touched) {
@@ -486,22 +674,33 @@ export function evaluate(
     let anyRatified = false;
     const failures: string[] = [];
     for (const rel of artifacts) {
-        const abs = path.join(root, rel);
+        // The record is read at the same commit as the content it answers
+        // for: a record rewritten in the working tree and never committed is
+        // not what a push or a merge would land.
         let text: string;
         try {
-            text = fs.readFileSync(abs, 'utf8');
-        } catch {
-            failures.push(`${rel}: listed in the diff but not readable on disk`);
+            const bytes = commit === null ? null : fileAtRevision(root, commit, rel);
+            if (bytes === null) {
+                failures.push(`${rel}: listed in the diff but absent at \`${revision}\``);
+                continue;
+            }
+            text = bytes.toString('utf8');
+        } catch (err) {
+            if (!(err instanceof GatedSubjectRefusal)) {
+                throw err;
+            }
+            failures.push(`${rel}: ${err.message}`);
             continue;
         }
-        const reading = readRatification(text, providerCount);
+        const reading = readRatification(text, providerCount, expectedSubject);
         if (isRatified(reading)) {
             anyRatified = true;
             lines.push('');
             lines.push(
                 `✅  ${rel} — ratified by ${reading.artifact?.reviewed_by} ` +
                     `(providers: ${reading.artifact?.providers.join(', ')}; ` +
-                    `effective after ${reading.artifact?.effective_after})`,
+                    `effective after ${reading.artifact?.effective_after}; ` +
+                    `subject ${String(reading.artifact?.subject).slice(0, 12)}…)`,
             );
             continue;
         }
@@ -537,6 +736,7 @@ export function evaluate(
 
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     let baseRef: string | null = null;
+    let revision = DEFAULT_REVISION;
     let root = REPO;
     // The policy is read relative to THIS SCRIPT's tree, never to `--root`.
     //
@@ -552,18 +752,24 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     const files: string[] = [];
     let collectingFiles = false;
 
+    const valueOptions = new Set(['--base-ref', '--root', '--rev', '--policy-root']);
     for (let i = 0; i < argv.length; i += 1) {
         const a = argv[i];
-        if (a === '--base-ref') {
-            baseRef = argv[i + 1] ?? null;
-            i += 1;
-            collectingFiles = false;
-        } else if (a === '--root') {
-            root = path.resolve(argv[i + 1] ?? root);
-            i += 1;
-            collectingFiles = false;
-        } else if (a === '--policy-root') {
-            policyRoot = path.resolve(argv[i + 1] ?? policyRoot);
+        if (a !== undefined && valueOptions.has(a)) {
+            const value = optionValue(argv, i);
+            if (value === null) {
+                process.stderr.write(`❌  check_kernel_edit_ratified: ${a} takes a value\n`);
+                return 1;
+            }
+            if (a === '--base-ref') {
+                baseRef = value;
+            } else if (a === '--root') {
+                root = path.resolve(value);
+            } else if (a === '--rev') {
+                revision = value;
+            } else {
+                policyRoot = path.resolve(value);
+            }
             i += 1;
             collectingFiles = false;
         } else if (a === '--quiet') {
@@ -576,19 +782,38 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         }
     }
 
+    // ONE resolution for the whole run. The diff, the digest and the record read
+    // all receive this id; passing the name to each would let a ref that moves
+    // between them yield a file list from one commit and a digest and record
+    // from another.
+    let commit: string;
+    try {
+        commit = resolveRevision(root, revision);
+    } catch (err) {
+        if (!(err instanceof GatedSubjectRefusal)) {
+            throw err;
+        }
+        process.stderr.write(`❌  check_kernel_edit_ratified: ${err.message}\n`);
+        return 1;
+    }
     let changed: string[];
-    if (files.length > 0) {
-        changed = files;
-    } else {
-        const fromGit = gitChangedFiles(resolveBaseRef(baseRef, root), root);
-        if (fromGit === null) {
-            process.stderr.write('❌  check_kernel_edit_ratified: git diff failed\n');
-            return 3;
+    try {
+        // The base, too, is resolved once: the diff and the closure's base side
+        // read the same commit. A `--files` list may add paths to the range,
+        // never hide one, so a range that cannot be read refuses rather than
+        // falling back to the list alone.
+        baseRef = resolveRevision(root, resolveBaseRef(baseRef, root));
+        changed = [...new Set([...files, ...changedFilesBetween(root, baseRef, commit)])];
+    } catch (err) {
+        if (!(err instanceof GatedSubjectRefusal)) {
+            throw err;
         }
-        changed = fromGit;
+        process.stderr.write(`❌  check_kernel_edit_ratified: ${err.message}\n`);
+        return 3;
     }
+    revision = commit;
 
-    const result = evaluate(changed, root, configuredProviderCount(policyRoot));
+    const result = evaluate(changed, root, configuredProviderCount(policyRoot), revision, baseRef);
 
     // OUTSIDE the quiet guard: CI passes --quiet, and a coverage guard that
     // sees no count reports the gate silent.

package/src/scripts/check_kernel_rule_bundle.ts

@@ -6,9 +6,11 @@
  * Phase 4 / Wave 4c). The CLI contract is pinned — `--base-ref`
  * / `--label` / `--event-path` / `--files` flags, exit codes (0 pass,
  * 1 fail, 3 internal error), stdout/stderr split, byte-identical finding
- * messages, the same git-diff invocation, base-ref candidate order, and
- * PR-label parsing from the GitHub event JSON. No behaviour changes —
- * historical quirks preserved (consumers pin the exact behaviour).
+ * messages, base-ref candidate order, and PR-label parsing from the GitHub
+ * event JSON. Two deliberate departures, both because CI reads the changed
+ * files from git through this script: the diff runs with `--no-renames`, so a
+ * kernel rule renamed away is listed under its old path too, and a failed
+ * diff exits 3 instead of passing on an empty list.
  *
  * Fails when a single PR (or commit range) modifies more than one
  * kernel rule under `src/rules/`. Override via the
@@ -59,17 +61,15 @@ const DEFAULT_LABEL = 'bundled-always-rules-acknowledged';
 // src/scripts/check_kernel_rule_bundle.ts → two levels up is the repo root.
 const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 
-function _git_changed_files(base_ref: string): string[] {
+function _git_changed_files(base_ref: string): string[] | null {
     // Bounded read: a truncated diff would shrink the change set and let the
-    // bundle guard pass on files it never saw.
-    const res = runCountedProbe('git', ['diff', '--name-only', `${base_ref}...HEAD`]);
-    // Python uses check_output(stderr=STDOUT, text=True): on non-zero it raises
-    // CalledProcessError and the handler prints the combined output. spawnSync
-    // does not raise; mirror by checking status and combining stdout+stderr.
+    // bundle guard pass on files it never saw. Rename detection off: a rename
+    // reported under its destination alone hides the kernel rule it moved.
+    const res = runCountedProbe('git', ['diff', '--no-renames', '--name-only', `${base_ref}...HEAD`]);
     if (!res.ok) {
         const combined = `${res.stdout ?? ''}${res.stderr ?? ''}`;
         process.stderr.write(`❌  git diff failed: ${combined.trim()}\n`);
-        return [];
+        return null;
     }
     return (res.stdout ?? '').split('\n').filter((line) => line.trim() !== '');
 }
@@ -217,6 +217,10 @@ export function main(argv?: readonly string[]): number {
         args.files && args.files.length > 0
             ? args.files
             : _git_changed_files(_resolve_base_ref(args.base_ref));
+    if (files === null) {
+        // An unreadable change set is not an empty one.
+        return 3;
+    }
     const hits = _kernel_changes(files);
 
     if (hits.length <= 1) {