@event4u/agent-config 9.27.0 → 9.29.0

package/src/scripts/preamble_byte_census.ts

@@ -44,6 +44,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as YAML from 'yaml';
 
 import { resolveGlobalProfilePath } from './_lib/agent_user_profile.js';
+import { censusRuleDir, type RuleDirCensus } from './_lib/carrier_divergence.js';
 import { DEFAULT_PROJECTS_ROOT, scanTranscripts } from './_lib/cc_transcript.js';
 import { censusDuplicateScope } from './_lib/duplicate_scope_census.js';
 import { computeColdStarts } from './cache_realization_report.js';
@@ -71,26 +72,14 @@ function readCharsIfExists(p: string): number {
 
 // ── source 1/2: rule directories ────────────────────────────────────────
 
-export interface RuleDirCensus {
-    files: number;
-    chars: number;
-}
-
-export function censusRuleDir(dir: string): RuleDirCensus {
-    if (!fs.existsSync(dir)) return { files: 0, chars: 0 };
-    let files = 0;
-    let chars = 0;
-    for (const name of fs.readdirSync(dir)) {
-        if (!name.endsWith('.md')) continue;
-        try {
-            chars += fs.statSync(path.join(dir, name)).size;
-            files += 1;
-        } catch {
-            // Unreadable entry — skip rather than fail the whole census.
-        }
-    }
-    return { files, chars };
-}
+// Moved to `_lib/carrier_divergence.ts` when `conformance_scan` needed the same
+// count (round-6 Phase 4.3): that module is on a bundled CLI path and this one
+// pulls `yaml` plus the cold-start report, so importing this file to reach fifteen
+// lines of `statSync` was the wrong direction. Re-exported so every existing
+// caller keeps its import and there is still one definition. Imported as well as
+// re-exported: a bare `export … from` does not bind the name in this module's own
+// scope, and this file uses both below.
+export { censusRuleDir, type RuleDirCensus };
 
 export interface PerRuleCost {
     file: string;

package/src/scripts/rebuild_hook_bundle.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env tsx
+/**
+ * Safe self-heal for the self-hosted hook bundle — the builder that
+ * `check_hook_bundle_freshness` deliberately is not.
+ *
+ * WHY THIS EXISTS — measured, not hypothetical.
+ *
+ * The freshness gate reds after ANY hook-source merge from main, because
+ * `dist/hooks/dispatch.js` is untracked and nothing in the local chain
+ * rebuilds it. On 2026-08-09 that turned `task release` (9.28.0) into a
+ * blocked push with a remedy the operator had to run by hand — a routine
+ * pre-push chore promoted to a release incident. The gate is right to never
+ * build (its documented hazard: esbuild overwriting the dispatcher a running
+ * hook is executing can wedge the tool loop). The hazard is in HOW a naive
+ * rebuild writes, not in rebuilding: this script builds to a sibling `.new`
+ * file, proves the result actually dispatches, and only then renames it into
+ * place — an atomic same-directory rename that a running hook holding an open
+ * file descriptor never observes mid-write.
+ *
+ * The `.new` file MUST live in `dist/hooks/` (not a temp dir): the bundle
+ * resolves `src/scripts/hook_manifest.yaml` relative to its OWN location via
+ * the `__AGENT_CONFIG_BUNDLE__` path-depth switch. Built anywhere else, every
+ * probe answers "manifest missing" with exit 0 and the smoke test proves
+ * nothing (measured 2026-08-08).
+ *
+ * The esbuild invocation is NOT duplicated here — it is read from
+ * `package.json`'s `build:hooks` script and only the `--outfile=` is
+ * rewritten, so the flag set (banner, defines, target) has exactly one home.
+ *
+ * Behaviour:
+ *   no self-hosted bundle → no-op (fresh checkout / CI — nothing is running
+ *                           stale code, and materialising a bundle here would
+ *                           change what other gates see)
+ *   bundle fresh          → no-op
+ *   bundle stale          → rebuild to `.new`, probe, rename into place
+ *   build or probe fails  → the `.new` file is removed and the OLD bundle
+ *                           keeps running (old-but-working beats broken);
+ *                           exit 1 so the freshness gate behind this still
+ *                           reds and the failure is loud.
+ *
+ * Exit codes: 0 = fresh / healed / nothing to heal · 1 = heal failed.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { check } from "./check_hook_bundle_freshness.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, "..", "..");
+const LIVE_REL = path.join("dist", "hooks", "dispatch.js");
+const NEW_REL = path.join("dist", "hooks", "dispatch.new.js");
+
+/**
+ * Rewrite the `--outfile=` of the canonical `build:hooks` script to the
+ * `.new` sibling. Returns null when the expected outfile token is absent —
+ * a changed `package.json` must fail loudly, never build to a guessed path.
+ */
+export function rewriteOutfile(script: string, newOutfile: string): string | null {
+  const token = `--outfile=${LIVE_REL}`;
+  if (!script.includes(token)) return null;
+  return script.replace(token, `--outfile=${newOutfile}`);
+}
+
+/**
+ * Verdict on a dispatcher probe. The probe contract is pinned against the
+ * real dry-run output: exit 0 AND parseable JSON AND a non-empty `concerns`
+ * array. Exit 0 alone is NOT enough — a bundle that cannot find its manifest
+ * answers "manifest missing" with exit 0 (measured 2026-08-08), which is
+ * exactly the broken dispatcher this probe exists to keep out of the live
+ * path. Returns null on pass, a human-readable reason on failure.
+ */
+export function probeVerdict(exitCode: number, stdout: string): string | null {
+  if (exitCode !== 0) return `probe exited ${String(exitCode)}`;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return `probe output is not JSON: ${stdout.slice(0, 120)}`;
+  }
+  const concerns = (parsed as { concerns?: unknown }).concerns;
+  if (!Array.isArray(concerns) || concerns.length === 0) {
+    return "probe JSON carries no concerns — the bundle dispatched nothing";
+  }
+  return null;
+}
+
+function cleanup(newAbs: string): void {
+  try {
+    fs.rmSync(newAbs, { force: true });
+  } catch {
+    // Best-effort: a leftover .new file is inert (nothing executes it).
+  }
+}
+
+export function main(): number {
+  const r = check(REPO_ROOT);
+
+  if (r.skipped) {
+    process.stdout.write(
+      `✅  OK  rebuild_hook_bundle: no self-hosted ${LIVE_REL} — nothing runs stale code, nothing to heal\n`,
+    );
+    return 0;
+  }
+  if (r.stale.length === 0) {
+    process.stdout.write("✅  OK  rebuild_hook_bundle: bundle already fresh — no rebuild needed\n");
+    return 0;
+  }
+
+  process.stdout.write(
+    `🔧  hook bundle stale (${String(r.stale.length)} newer source(s)) — rebuilding safely (build .new → probe → atomic rename)\n`,
+  );
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, "package.json"), "utf-8")) as {
+    scripts?: Record<string, string>;
+  };
+  const buildScript = pkg.scripts?.["build:hooks"];
+  if (buildScript === undefined) {
+    console.error("❌  rebuild_hook_bundle: package.json has no build:hooks script");
+    return 1;
+  }
+  const cmd = rewriteOutfile(buildScript, NEW_REL);
+  if (cmd === null) {
+    console.error(
+      `❌  rebuild_hook_bundle: build:hooks no longer targets --outfile=${LIVE_REL} — ` +
+        "refusing to build to a guessed path; update this script alongside package.json",
+    );
+    return 1;
+  }
+
+  const newAbs = path.join(REPO_ROOT, NEW_REL);
+  const build = spawnSync("sh", ["-c", cmd], {
+    cwd: REPO_ROOT,
+    encoding: "utf-8",
+    env: { ...process.env, PATH: `${path.join(REPO_ROOT, "node_modules", ".bin")}:${process.env["PATH"] ?? ""}` },
+  });
+  if (build.status !== 0) {
+    cleanup(newAbs);
+    console.error(`❌  rebuild_hook_bundle: esbuild failed (${String(build.status)}):`);
+    console.error((build.stderr || build.stdout || "").trim());
+    return 1;
+  }
+
+  const probe = spawnSync(
+    "node",
+    [newAbs, "--platform", "claude", "--event", "pre_tool_use", "--dry-run"],
+    { cwd: REPO_ROOT, encoding: "utf-8", input: "{}" },
+  );
+  const verdict = probeVerdict(probe.status ?? 1, probe.stdout ?? "");
+  if (verdict !== null) {
+    cleanup(newAbs);
+    console.error(`❌  rebuild_hook_bundle: new bundle failed its probe — ${verdict}`);
+    console.error("    The old bundle stays in place (old-but-working beats broken).");
+    return 1;
+  }
+
+  fs.renameSync(newAbs, path.join(REPO_ROOT, LIVE_REL));
+  process.stdout.write(
+    `✅  OK  rebuild_hook_bundle: rebuilt + probed + renamed into place (${String(r.checked)} bundled source(s))\n`,
+  );
+  return 0;
+}
+
+const invokedDirectly = ((): boolean => {
+  const entry = process.argv[1];
+  if (entry === undefined) return false;
+  try {
+    return fs.realpathSync(path.resolve(entry)) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  process.exit(main());
+}

package/src/scripts/release.ts

@@ -1073,6 +1073,78 @@ function _tag_exists_remote(tag: string): boolean {
     return r.returncode === 0;
 }
 
+/**
+ * True when git rejected a tag push because the ref already exists on the
+ * remote. Wording pinned from the real failure (2026-08-09, 9.28.0 — two
+ * concurrent resume runs, the loser crashed):
+ *
+ *     ! [remote rejected]  9.28.0 -> 9.28.0 (cannot lock ref 'refs/tags/9.28.0': reference already exists)
+ *
+ * plus the `[rejected] … (already exists)` variant git emits when the local
+ * and remote tag objects differ.
+ */
+export function _is_tag_already_exists(stderr: string, stdout: string): boolean {
+    const text = `${stderr}\n${stdout}`;
+    return /\[(?:remote )?rejected\]/i.test(text) && /already exists/i.test(text);
+}
+
+/** Peeled commit the remote tag points at, or null when the tag is absent. */
+function _remote_tag_commit(tag: string): string | null {
+    const r = run(['git', 'ls-remote', REMOTE, `refs/tags/${tag}`, `refs/tags/${tag}^{}`], {
+        check: false,
+        capture: true,
+    });
+    if (r.returncode !== 0) return null;
+    const lines = r.stdout.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) return null;
+    // An annotated tag lists the tag object AND the peeled `^{}` commit — the
+    // peeled line wins so the comparison is commit-vs-commit regardless of
+    // whether the two runs minted distinct tag objects for the same commit.
+    const peeled = lines.find((l) => l.trimEnd().endsWith('^{}'));
+    return (peeled ?? (lines[0] as string)).split('\t')[0] ?? null;
+}
+
+/**
+ * Push a tag, tolerating exactly ONE failure: the concurrent-release race.
+ * `_tag_exists_remote` in step 8 is a live check, but between it and this
+ * push a parallel `task release` run can land the same tag (measured
+ * 2026-08-09, 9.28.0). When the remote tag already points at the same commit
+ * as the local one, the repository IS in the desired state — continue. Any
+ * other rejection, and a same-name tag on a DIFFERENT commit, stays fatal
+ * with the push output as the error.
+ */
+function _push_tag(tag: string): void {
+    const first = run(['git', 'push', REMOTE, tag], { check: false, capture: true });
+    if (first.returncode === 0) {
+        process.stdout.write(first.stdout);
+        process.stderr.write(first.stderr);
+        return;
+    }
+    if (_is_tag_already_exists(first.stderr, first.stdout)) {
+        const remote = _remote_tag_commit(tag);
+        const local = git(['rev-list', '-n', '1', tag], { capture: true });
+        if (remote !== null && remote === local) {
+            process.stdout.write(
+                `↻  tag ${tag} already on ${REMOTE} at the same commit — a parallel run pushed it; continuing\n`,
+            );
+            return;
+        }
+        process.stdout.write(first.stdout);
+        process.stderr.write(first.stderr);
+        die(
+            `tag ${tag} exists on ${REMOTE} pointing at ${remote ?? '<unreadable>'} while the local tag ` +
+                `points at ${local} — refusing to overwrite a published tag; ` +
+                'delete the wrong one deliberately and re-run',
+        );
+    }
+    process.stdout.write(first.stdout);
+    process.stderr.write(first.stderr);
+    die(
+        `push of tag ${tag} failed (exit ${first.returncode}) — ` +
+            'the push output above is the real error (a pre-push gate, credentials, or protection)',
+    );
+}
+
 /** Most recent PR (any state) with `release/X.Y.Z` as head, or null. */
 function _pr_for_branch(branch: string): Record<string, unknown> | null {
     const r = run(
@@ -2029,7 +2101,7 @@ function execute(
             _step(8, total, `Tag ${plan.target} already on ${REMOTE} — skip`);
         } else {
             _step(8, total, `Tag ${plan.target} exists locally — push only`);
-            run(['git', 'push', REMOTE, plan.target]);
+            _push_tag(plan.target);
         }
     } else {
         // Sequencing is load-bearing (release-truth Phase 1, council
@@ -2047,7 +2119,7 @@ function execute(
             );
         }
         run(['git', 'tag', '-a', plan.target, '-m', tag_message_from_section(merged!.body, plan.target)]);
-        run(['git', 'push', REMOTE, plan.target]);
+        _push_tag(plan.target);
     }
 
     // ─── 9. GitHub Release ──────────────────────────────────────────────────

package/src/scripts/report_carrier_divergence.ts

@@ -0,0 +1,364 @@
+#!/usr/bin/env tsx
+/**
+ * report_carrier_divergence.ts — which rules the two carriers deliver
+ * differently, BY NAME.
+ *
+ * Executes round-5 Phase 1.3, landed under round-6 Phase 4.1. Advisory: **it
+ * gates on nothing** and must not acquire a threshold, for the reason
+ * `report_skill_activation` and `report_imperative_density` must not — plus one
+ * specific to this surface, below.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The suite installs machine-globally (`~/.claude/rules/`) and the package's own
+ * checkout also projects per-project (`dist/agent-src/rules/`, which every
+ * project-scope tree symlinks). A machine that has both loads the shared rules
+ * twice, and nothing said whether the two copies agree. Round 5 measured the
+ * condition once and named the dangerous case: its global copy of
+ * `git-history-discipline` asserted an unqualified "deterministically blocked by
+ * the `block-no-verify` PreToolUse guard" while the shipped copy carried the
+ * host-scoped retraction of exactly that claim. The agent held both, with no
+ * precedence marker.
+ *
+ * A one-off measurement cannot own that condition, because the condition is
+ * **transient and maintainer-dependent**: it appears when the checkout moves
+ * ahead of the installed release and disappears the next time the maintainer
+ * reinstalls. Verified both directions — see § THE 2026-08-08 RE-MEASUREMENT.
+ * So the deliverable is a report anyone can re-run, not a number in a roadmap.
+ *
+ * WHY IT MUST NOT BECOME A GATE
+ * -----------------------------
+ * A maintainer developing the package is *legitimately* ahead of their own
+ * global install — `condense.ts` says so where it explains why the byte-keyed
+ * dedup is inert in that state. A gate here would fail on the normal
+ * development condition, and a gate that fires on sanctioned behaviour gets
+ * ignored, which is the failure `check-rule-invariants` already paid for once.
+ * The point is that the condition becomes VISIBLE, not that it becomes illegal.
+ *
+ * THE THREE CLASSES, AND WHICH ONE A READER MUST ACT ON
+ * ----------------------------------------------------
+ *   body-diff        the two carriers deliver different TEXT. This is the class
+ *                    round 5's contradiction lived in, and the only one that
+ *                    needs a decision. Precedence when it appears: the project
+ *                    projection is generated from `src/` at the current commit,
+ *                    so it is the newer copy and it wins; the global install is
+ *                    a release snapshot. Printed with the report so the
+ *                    precedence is read at the moment it matters rather than
+ *                    looked up.
+ *   provenance-only  identical after removing the two installer ownership keys.
+ *                    Structural, expected, and decided against closing —
+ *                    `agents/settings/contexts/dedup-reachability-refusal.md`.
+ *                    Reported as a count with that pointer, never as a finding,
+ *                    or the real class drowns in it.
+ *   one-carrier-only a rule present at exactly one scope. Not a contradiction:
+ *                    project-only is a rule newer than the installed release,
+ *                    global-only is a rule the release still carries. Named
+ *                    because asymmetric reach is what makes a project-scope
+ *                    measurement non-transferable to another machine.
+ *
+ * NOT IN SCOPE. Skills, commands and contexts have the same two-carrier shape
+ * and are not compared here; this executes the rule-scoped step that was
+ * specified. Nor does it compare `~/.claude/CLAUDE.md` against the project's
+ * `CLAUDE.md` — a different mechanism with a different precedence story.
+ *
+ * Exit: 0 always, except a usage error (1). Deliberate — see above.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { comparePair, type PairVerdict } from './_lib/carrier_divergence.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/**
+ * The project carrier — the tree the host actually reads at project scope, NOT
+ * `dist/agent-src/rules/`.
+ *
+ * The distinction is load-bearing and was found by measuring: the global
+ * installer delivers the five ADR-004 `type: manual` rules while the project
+ * projection deliberately omits them, so anchoring on `dist` (which holds all
+ * 115) reports those five as *shared* when in fact only one carrier delivers
+ * them. Two writers, different filters — exactly the asymmetry this report
+ * exists to name. `dist` is still read, as the reference for what COULD be
+ * projected, which is what makes the manual class attributable rather than a
+ * bare absence.
+ */
+export const PROJECT_RULES = path.join('.claude', 'rules');
+/** What the project projection is generated from — the reference set. */
+export const PROJECTION_SOURCE = path.join('dist', 'agent-src', 'rules');
+/** The machine-global carrier, relative to the user's home. */
+export const GLOBAL_RULES = path.join('.claude', 'rules');
+
+export interface CarrierDivergence {
+    projectDir: string;
+    globalDir: string;
+    /** `false` when the global carrier is absent — every count is then 0. */
+    globalPresent: boolean;
+    /** `false` when the project tree has not been generated in this checkout. */
+    projectPresent: boolean;
+    shared: number;
+    identical: string[];
+    provenanceOnly: string[];
+    bodyDiff: string[];
+    projectOnly: string[];
+    globalOnly: string[];
+    /**
+     * Shared names whose copies could not both be read (a dangling symlink from a
+     * half-finished install). Counted rather than dropped: a pair that silently
+     * leaves `shared` makes every other number in the report unaccounted for.
+     */
+    unreadable: string[];
+    /**
+     * Rules the projection source carries, the global carrier delivers, and the
+     * project projection omits by design (`type: manual`). A subset of
+     * `globalOnly`, separated so the expected half does not read as drift.
+     */
+    manualOnlyGlobal: string[];
+}
+
+function _listRules(dir: string): string[] {
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.md'))
+            .sort();
+    } catch {
+        return [];
+    }
+}
+
+/** `type:` from a rule's frontmatter, or `''` when unreadable / absent. */
+function _ruleType(file: string): string {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return '';
+    }
+    if (!text.startsWith('---')) return '';
+    const end = text.indexOf('\n---', 3);
+    const fm = end === -1 ? text : text.slice(0, end);
+    const m = /^type:\s*"?([a-z]+)"?/m.exec(fm);
+    return m === null ? '' : (m[1] as string);
+}
+
+/**
+ * Compare the two carriers over the UNION of their rule names.
+ *
+ * The union is the point: anchoring on either side alone hides one direction of
+ * asymmetric reach, and it was the hidden direction — rules the global install
+ * carries and the project does not — that made round 5's cross-project
+ * comparison hard to interpret.
+ *
+ * `sourceDir` is the projection source, read only to attribute a global-only
+ * rule to the ADR-004 manual filter rather than to drift. Absent → the manual
+ * split is simply empty, never a guess.
+ */
+export function compareCarriers(
+    projectDir: string,
+    globalDir: string,
+    sourceDir?: string,
+): CarrierDivergence {
+    const out: CarrierDivergence = {
+        projectDir,
+        globalDir,
+        globalPresent: fs.existsSync(globalDir),
+        projectPresent: fs.existsSync(projectDir),
+        shared: 0,
+        identical: [],
+        provenanceOnly: [],
+        bodyDiff: [],
+        projectOnly: [],
+        globalOnly: [],
+        unreadable: [],
+        manualOnlyGlobal: [],
+    };
+    const project = new Set(_listRules(projectDir));
+    const global = new Set(_listRules(globalDir));
+
+    for (const rule of [...new Set([...project, ...global])].sort()) {
+        const inP = project.has(rule);
+        const inG = global.has(rule);
+        if (inP && !inG) {
+            out.projectOnly.push(rule);
+            continue;
+        }
+        if (!inP && inG) {
+            out.globalOnly.push(rule);
+            if (sourceDir !== undefined && _ruleType(path.join(sourceDir, rule)) === 'manual') {
+                out.manualOnlyGlobal.push(rule);
+            }
+            continue;
+        }
+        out.shared += 1;
+        let verdict: PairVerdict;
+        try {
+            verdict = comparePair(
+                fs.readFileSync(path.join(projectDir, rule)),
+                fs.readFileSync(path.join(globalDir, rule)),
+            );
+        } catch {
+            // An unreadable copy is not a body difference and must not be
+            // reported as one — a permission error would otherwise manufacture
+            // the only class this report asks a reader to act on. It is still
+            // NAMED: a pair that just disappears from `shared` leaves the ledger
+            // short with nothing saying why.
+            out.shared -= 1;
+            out.unreadable.push(rule);
+            continue;
+        }
+        if (verdict === 'identical') out.identical.push(rule);
+        else if (verdict === 'provenance-only') out.provenanceOnly.push(rule);
+        else out.bodyDiff.push(rule);
+    }
+    return out;
+}
+
+export function render(d: CarrierDivergence): string {
+    const lines: string[] = [];
+    lines.push('cross-carrier rule divergence — advisory, gates on nothing');
+    lines.push(`  project carrier: ${d.projectDir}`);
+    lines.push(`  global carrier:  ${d.globalDir}`);
+    lines.push('');
+
+    if (!d.globalPresent) {
+        lines.push('  The global carrier is absent — this machine loads the project projection');
+        lines.push('  only, so there is no second copy to diverge from. Nothing to report, and');
+        lines.push('  that is a real answer rather than a skipped check.');
+        return lines.join('\n');
+    }
+    if (!d.projectPresent) {
+        lines.push('  The project rule tree does not exist in this checkout — it is generated and');
+        lines.push('  gitignored, so a fresh clone has none, and `agents/.agent-tools.yml` may');
+        lines.push('  select zero tools deliberately. Run `task generate-tools` and re-run this');
+        lines.push('  report. Reported rather than silently substituted with the projection');
+        lines.push('  source: dist/ holds rules the project tree omits by design, so reading it');
+        lines.push('  as the project carrier would answer a different question than the one asked.');
+        return lines.join('\n');
+    }
+
+    lines.push(`  shared rule names                    ${d.shared}`);
+    lines.push(`    byte-identical                     ${d.identical.length}`);
+    lines.push(`    differ ONLY in the install stamp   ${d.provenanceOnly.length}`);
+    lines.push(`    differ in BODY                     ${d.bodyDiff.length}`);
+    if (d.unreadable.length > 0) {
+        lines.push(`    unreadable on one side             ${d.unreadable.length}  (${d.unreadable.join(', ')})`);
+        lines.push('      Not counted as shared and NOT a body difference — a dangling entry is');
+        lines.push('      a broken install, not a disagreement about content.');
+    }
+    lines.push(`  present at project scope only        ${d.projectOnly.length}`);
+    lines.push(`  present at global scope only         ${d.globalOnly.length}`);
+    lines.push('');
+
+    if (d.bodyDiff.length > 0) {
+        lines.push('  BODY DIVERGENCE — the two carriers deliver different text for these rules.');
+        lines.push('  Both copies reach the model, with no precedence marker between them, so a');
+        lines.push('  claim one copy retracts can be re-asserted by the other. PRECEDENCE: the');
+        lines.push('  project projection is generated from src/ at this commit and wins; the');
+        lines.push('  global install is a release snapshot. Close it by reinstalling the global');
+        lines.push('  copy, or by reading the project copy as authoritative.');
+        for (const r of d.bodyDiff) lines.push(`    - ${r}`);
+        lines.push('');
+    }
+
+    if (d.provenanceOnly.length > 0) {
+        lines.push(`  ${String(d.provenanceOnly.length)} pair(s) differ only by the installer's package:/source_path: stamp.`);
+        lines.push('  Not a content difference and NOT a defect: install.ts stamps every installed');
+        lines.push('  rule, the in-repo projection stamps nothing. Closing it was decided against');
+        lines.push('  on 2026-07-31 — agents/settings/contexts/dedup-reachability-refusal.md holds');
+        lines.push('  the analysis and the five reopen conditions. Reported as a count on purpose:');
+        lines.push('  naming every expected pair would bury the class above.');
+        lines.push('');
+    }
+
+    if (d.projectOnly.length > 0) {
+        lines.push(`  project-scope only (${String(d.projectOnly.length)}) — newer than the installed release:`);
+        lines.push(`    ${d.projectOnly.join(', ')}`);
+    }
+    const driftGlobalOnly = d.globalOnly.filter((r) => !d.manualOnlyGlobal.includes(r));
+    if (driftGlobalOnly.length > 0) {
+        lines.push(`  global-scope only (${String(driftGlobalOnly.length)}) — the release carries these, this checkout does not project them:`);
+        lines.push(`    ${driftGlobalOnly.join(', ')}`);
+    }
+    if (d.manualOnlyGlobal.length > 0) {
+        lines.push(
+            `  delivered by the global carrier ONLY, by design (${String(d.manualOnlyGlobal.length)}, ADR-004 \`type: manual\`):`,
+        );
+        lines.push(`    ${d.manualOnlyGlobal.join(', ')}`);
+        lines.push('    The project projection filters these out and the global installer does not.');
+        lines.push('    Two writers, different filters — so on a machine with both carriers these');
+        lines.push('    rules reach the model, and on a project-only machine they do not. Expected,');
+        lines.push('    and worth knowing before citing any project-scope reach figure.');
+    }
+    if (d.projectOnly.length > 0 || d.globalOnly.length > 0) {
+        lines.push('');
+        lines.push('  Asymmetric reach is why a project-scope conformance figure does not transfer');
+        lines.push('  to another machine: the rule set the model was told differs by carrier.');
+    }
+
+    if (d.bodyDiff.length === 0) {
+        lines.push('');
+        lines.push('  No body divergence. The condition is transient — it returns whenever the');
+        lines.push('  checkout moves ahead of the installed release — so this is a reading of');
+        lines.push('  right now, not a property of the repo. Re-run it, do not cite it.');
+    }
+    return lines.join('\n');
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let projectDir = path.join(REPO_ROOT, PROJECT_RULES);
+    let globalDir = path.join(os.homedir(), GLOBAL_RULES);
+    let sourceDir = path.join(REPO_ROOT, PROJECTION_SOURCE);
+    // A value must not itself be a flag. `--project --global /x` otherwise
+    // resolves a directory literally named `--global` and silently drops `/x`,
+    // reporting "tree does not exist" instead of a usage error — the flag-VALUE
+    // half of the hole this file's own test closes on the flag-NAME half.
+    const value = (i: number): string | null => {
+        const v = args[i + 1];
+        return v === undefined || v.startsWith('-') ? null : v;
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === '--project' || a === '--global' || a === '--source') {
+            const v = value(i);
+            if (v === null) {
+                process.stderr.write(`report_carrier_divergence: ${a} needs a directory\n`);
+                return 1;
+            }
+            const resolved = path.resolve(v);
+            if (a === '--project') projectDir = resolved;
+            else if (a === '--global') globalDir = resolved;
+            else sourceDir = resolved;
+            i += 1;
+        } else if (a === '--help' || a === '-h') {
+            process.stdout.write(
+                'usage: report_carrier_divergence [--project DIR] [--global DIR] [--source DIR]\n',
+            );
+            return 0;
+        } else if (a !== undefined && a.startsWith('--') && a !== '--quiet') {
+            process.stderr.write(`report_carrier_divergence: unknown flag ${a}\n`);
+            return 1;
+        }
+    }
+    process.stdout.write(`${render(compareCarriers(projectDir, globalDir, sourceDir))}\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}