@event4u/agent-config 9.26.0 → 9.28.0

package/src/scripts/check_enforcement_coverage.ts

@@ -38,6 +38,16 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { KERNEL_RULE_ID_SET } from './_lib/kernel_rules.js';
+import {
+    carrier_frequency_by_platform,
+    covers,
+    covers_any,
+    is_frequency,
+    parse_hook_platforms,
+    type Frequency,
+    type PlatformBinding,
+} from './_lib/obligation_frequency.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
@@ -73,6 +83,25 @@ export type Resolution =
     | 'missing'         // declared target does not exist at all
     | 'none';           // honest, recorded gap
 
+/**
+ * Whether the carrier's firing set covers the obligation's — the question
+ * `effective` does not answer.
+ *
+ * `covered`      — some declared carrier covers the obligation on every
+ *                  hook-capable platform.
+ * `gap`          — at least one hook-capable platform where no declared carrier
+ *                  covers it. `gap_platforms` names them.
+ * `declared-gap` — the rule declares `enforced_by: none`; the gap is stated in
+ *                  the rule's own text, so it is honest, not a defect.
+ * `unclassified` — no `obligation_frequency` to join against. The nine kernel
+ *                  rules sit here: `block_kernel_rule_writes.ts` denies agent
+ *                  writes to them, so the field cannot be populated by the same
+ *                  pass that populated the other 105.
+ * `unmeasured`   — the rule declares no carrier at all; model-carried by design,
+ *                  making no claim this join could falsify.
+ */
+export type FrequencyVerdict = 'covered' | 'gap' | 'declared-gap' | 'unclassified' | 'unmeasured';
+
 export interface RuleCoverage {
     id: string;
     tier: string;
@@ -82,6 +111,21 @@ export interface RuleCoverage {
     /** Strongest resolution, by the ordering in `RANK`. */
     effective: Resolution;
     notes: string[];
+    /** Declared obligation period (frontmatter), or null when undeclared. */
+    obligation_frequency: Frequency | null;
+    /**
+     * Carrier period per hook-capable platform — never a single scalar.
+     *
+     * A scalar is wrong twice over: copilot has no hook surface at all, so a
+     * weakest-platform collapse turns one platform property into a finding on
+     * every hook-carried rule; and cline maps `stop` from `TaskCancel`, so the
+     * same slot means per-turn on six platforms and per-interruption there. Both
+     * are invisible in one number.
+     */
+    carrier_frequency: Record<string, string> | null;
+    frequency_verdict: FrequencyVerdict;
+    /** Hook-capable platforms where no declared carrier covers the obligation. */
+    gap_platforms: string[];
 }
 
 /** Strength order — a rule is credited with its strongest resolving backstop. */
@@ -396,14 +440,87 @@ export function strongest(resolutions: Resolution[]): Resolution {
     return best;
 }
 
+// ----------------------------------------------------------- frequency join
+
+/**
+ * Join a rule's declared obligation period against its carriers' firing periods.
+ *
+ * Runs per hook-capable platform, never as one scalar. A rule is covered only
+ * when SOME declared carrier covers it on EVERY hook-capable platform; the
+ * platforms where none does are named, because "uncovered on windsurf" and
+ * "uncovered everywhere" are different findings with different fixes.
+ *
+ * `validator:` / `test:` carriers are SWEEP carriers — they fire once and read
+ * the whole tree, so their reach is bounded by what lands in an artefact rather
+ * than by how often they run. Modelling them as per-commit point carriers would
+ * make every `validator:`-carried rule with a per-edit obligation a finding at
+ * once: one modelling error rendered as a fifth of the corpus.
+ */
+export function join_frequency(
+    obligation: Frequency | null,
+    declared: string[],
+    binding: PlatformBinding,
+): {
+    verdict: FrequencyVerdict;
+    carrier_frequency: Record<string, string> | null;
+    gap_platforms: string[];
+} {
+    if (obligation === null) {
+        return { verdict: 'unclassified', carrier_frequency: null, gap_platforms: [] };
+    }
+    if (declared.length === 0) {
+        return { verdict: 'unmeasured', carrier_frequency: null, gap_platforms: [] };
+    }
+    if (declared.every((d) => d === 'none')) {
+        return { verdict: 'declared-gap', carrier_frequency: null, gap_platforms: [] };
+    }
+
+    const has_sweep = declared.some((d) => d.startsWith('validator:') || d.startsWith('test:'));
+    const hook_concerns = declared
+        .filter((d) => d.startsWith('hook:'))
+        .map((d) => d.slice('hook:'.length));
+
+    const per_platform: Record<string, string> = {};
+    const gap_platforms: string[] = [];
+
+    for (const platform of binding.slots.keys()) {
+        if (binding.fallback_only.has(platform)) continue;
+
+        let covered = false;
+        const seen: Frequency[] = [];
+
+        if (has_sweep && covers({ frequency: 'per-commit', mode: 'sweep' }, obligation)) {
+            covered = true;
+        }
+        for (const concern of hook_concerns) {
+            for (const f of carrier_frequency_by_platform(concern, binding)[platform] ?? []) {
+                if (!seen.includes(f)) seen.push(f);
+            }
+        }
+        if (covers_any(seen, obligation)) covered = true;
+
+        per_platform[platform] =
+            seen.length > 0 ? seen.join('+') : has_sweep ? 'sweep' : 'absent';
+        if (!covered) gap_platforms.push(platform);
+    }
+
+    return {
+        verdict: gap_platforms.length === 0 ? 'covered' : 'gap',
+        carrier_frequency: per_platform,
+        gap_platforms,
+    };
+}
+
 // -------------------------------------------------------------------- report
 
 export function collect(): RuleCoverage[] {
     const ci_corpus = load_corpus(WORKFLOW_DIRS);
     const local_corpus = load_corpus(TASK_DIRS, TASK_FILES);
-    const hooks = fs.existsSync(HOOK_MANIFEST)
-        ? parse_hook_manifest(fs.readFileSync(HOOK_MANIFEST, 'utf-8'))
-        : new Map<string, boolean>();
+    const manifest_text = fs.existsSync(HOOK_MANIFEST)
+        ? fs.readFileSync(HOOK_MANIFEST, 'utf-8')
+        : '';
+    const hooks = manifest_text ? parse_hook_manifest(manifest_text) : new Map<string, boolean>();
+    const binding = parse_hook_platforms(manifest_text);
     const exists = (rel: string): boolean => fs.existsSync(path.join(REPO_ROOT, rel));
     // Seeded separately so the umbrella expansion answers "reachable from CI"
     // rather than "reachable from anything". The expansion itself was correct;
@@ -425,14 +542,36 @@ export function collect(): RuleCoverage[] {
             resolutions.push(resolution);
             if (note) notes.push(note);
         }
+        const id = name.replace(/\.md$/, '');
+        const raw_freq = fm['obligation_frequency'];
+        const obligation: Frequency | null = is_frequency(raw_freq) ? raw_freq : null;
+        const { verdict, carrier_frequency, gap_platforms } = join_frequency(
+            obligation,
+            declared,
+            binding,
+        );
+        // Say WHY a row is unclassified. For the nine kernel rules the answer is
+        // structural rather than an authoring lapse — block_kernel_rule_writes
+        // denies the write — and a reader who cannot tell those apart will read
+        // the same bucket as either "expected" or "someone forgot".
+        if (verdict === 'unclassified' && KERNEL_RULE_ID_SET.has(id)) {
+            notes.push(
+                'no obligation_frequency: kernel rule, and block_kernel_rule_writes denies ' +
+                    'the write with no agent-accessible override',
+            );
+        }
         out.push({
-            id: name.replace(/\.md$/, ''),
+            id,
             tier: String(fm['tier'] ?? '—'),
             type: String(fm['type'] ?? '—'),
             declared,
             resolutions,
             effective: strongest(resolutions),
             notes,
+            obligation_frequency: obligation,
+            carrier_frequency,
+            frequency_verdict: verdict,
+            gap_platforms,
         });
     }
     return out;
@@ -450,6 +589,16 @@ export interface Summary {
     missing: number;
     undeclared: number;
     blocking_pct: number;
+    /**
+     * Rules whose declared carrier does not fire often enough to cover their
+     * declared obligation, on at least one hook-capable platform. The number
+     * this roadmap exists to produce — and the one `--check` ratchets, because
+     * `blocking` cannot see it: `session-canary` is declared, wired, firing, and
+     * in this bucket.
+     */
+    frequency_gap: number;
+    /** Rules with no `obligation_frequency` to join — the nine kernel rules. */
+    frequency_unclassified: number;
 }
 
 export function summarise(rows: RuleCoverage[]): Summary {
@@ -466,6 +615,8 @@ export function summarise(rows: RuleCoverage[]): Summary {
         missing: count((r) => r.effective === 'missing'),
         undeclared: rows.length - declared.length,
         blocking_pct: rows.length === 0 ? 0 : Math.round((blocking / rows.length) * 1000) / 10,
+        frequency_gap: count((r) => r.frequency_verdict === 'gap'),
+        frequency_unclassified: count((r) => r.frequency_verdict === 'unclassified'),
     };
 }
 
@@ -513,9 +664,13 @@ function main(argv: string[]): number {
                 {
                     _doc:
                         'Enforcement-coverage baseline. `blocking` counts rules whose strongest ' +
-                        'enforced_by resolves to something that can fail a build. Coverage is a ' +
-                        'ratchet: --check fails when blocking falls or unwired rises. Regenerate ' +
-                        'intentionally with --write-baseline when the change is the point.',
+                        'enforced_by resolves to something that can fail a build. `frequency_gap` ' +
+                        'counts rules whose carrier does not fire often enough to cover their ' +
+                        'declared obligation on some hook-capable platform — a rule can be ' +
+                        'blocking and in that bucket at once. Coverage is a ratchet: --check fails ' +
+                        'when blocking falls, or unwired / local_only / missing / frequency_gap ' +
+                        'rises. Regenerate intentionally with --write-baseline when the change is ' +
+                        'the point.',
                     summary,
                 },
                 null,
@@ -543,6 +698,27 @@ function main(argv: string[]): number {
         );
     }
 
+    lines.push(
+        `  frequency: ${summary.frequency_gap} gap · ${summary.frequency_unclassified} unclassified ` +
+            `(kernel — block_kernel_rule_writes denies the field)`,
+    );
+
+    const gaps = rows.filter((r) => r.frequency_verdict === 'gap');
+    if (gaps.length > 0) {
+        lines.push('');
+        lines.push('  frequency gaps — carrier fires, but not often enough:');
+        for (const r of gaps) {
+            const where =
+                r.gap_platforms.length === Object.keys(r.carrier_frequency ?? {}).length
+                    ? 'every hook-capable platform'
+                    : r.gap_platforms.join(', ');
+            lines.push(
+                `    · ${r.id}: obligation ${r.obligation_frequency}, carrier ` +
+                    `${r.declared.join(' + ')} — uncovered on ${where}`,
+            );
+        }
+    }
+
     const problems = rows.filter((r) => r.notes.length > 0);
     if (problems.length > 0) {
         lines.push('');
@@ -569,6 +745,15 @@ function main(argv: string[]): number {
         if (summary.unwired > base.unwired) {
             regressions.push(`unwired declarations rose: ${base.unwired} → ${summary.unwired}`);
         }
+        // The bucket `blocking` structurally cannot see: a rule can be declared,
+        // wired, firing and still mis-slotted. `??` tolerates a pre-frequency
+        // baseline so the field's own introduction does not red the ratchet.
+        if (summary.frequency_gap > (base.frequency_gap ?? Number.POSITIVE_INFINITY)) {
+            regressions.push(
+                `frequency gaps rose: ${base.frequency_gap} → ${summary.frequency_gap} ` +
+                    `(a rule's carrier no longer fires often enough for its obligation)`,
+            );
+        }
         // A validator dropping out of a workflow back into taskfile-only is the
         // exact regression this split was built to name. Without this line the
         // headline would fall and only the `blocking` check would notice, which

package/src/scripts/check_rule_projection_integrity.ts

@@ -0,0 +1,364 @@
+#!/usr/bin/env tsx
+/**
+ * check_rule_projection_integrity.ts — the host rule trees are COMPLETE and
+ * FRESH against `dist/agent-src/rules/`, read as they stand on disk.
+ *
+ * WHY THIS GATE EXISTS (road-to-conformance-round5 Phase 1, measured 2026-08-07)
+ * ---------------------------------------------------------------------------
+ * `docs/contracts/rule-router.md:234` states that nothing loads
+ * `dist/router.json` at runtime, so **projection is the only reach mechanism
+ * there is**: a non-kernel rule activates by the model's judgment over text
+ * already in context, and the per-tool rule tree is what puts it there. That
+ * makes the state of the projection load-bearing, and it was broken:
+ *
+ *   - `.claude/rules/` in the working checkout held **92** entries. A
+ *     regeneration in a clean worktree produces **108**. The tree was last
+ *     generated **2026-07-05**, and **21 rules added since then had no entry** —
+ *     among them `secret-vcs-guard`, `broken-access-control`,
+ *     `senior-engineering-discipline`, `evaluator-independence`,
+ *     `session-canary`, `settings-ask-protocol`, `active-remediation`. At
+ *     project scope those 21 obligations were carried by nothing. The same 21
+ *     were absent from `.clinerules/` and `.cursor/rules/*.md`.
+ *   - The trees are gitignored and untracked, so no diff review sees the gap.
+ *
+ * WHY THE EXISTING GATES DO NOT CATCH IT
+ * --------------------------------------
+ *   - `check_bridge_derivation` **regenerates** the trees and then diffs, so it
+ *     can only ever observe a fixpoint; both CI and the pre-push chain run it
+ *     ahead of anything else, which is why five weeks of staleness were invisible.
+ *     Its symlink leg asserts that entries which EXIST resolve — a missing entry
+ *     is not a wrong entry.
+ *   - `check_generator_output_coverage.ts:37` asserts only that the output
+ *     *root* is classified in the ignore manifest, never its contents.
+ *   - `check_condensation.ts` stops at `dist/`.
+ *
+ * So the last hop — the one that decides what the model actually sees — was
+ * ungated. This gate reads the tree WITHOUT touching it: no regeneration, no
+ * writes. That is the whole design constraint, and it is why the check is a
+ * separate script rather than a third leg on `check_bridge_derivation`.
+ *
+ * HONEST SCOPE — where each leg has teeth
+ * ---------------------------------------
+ * On a fresh CI checkout the trees do not exist at all (gitignored), so CI must
+ * run this AFTER `task generate-tools`, where it is a **generator-regression**
+ * check: it proves the generator emitted every rule it planned to. The stale
+ * case is caught on a developer's working checkout, which is why the pre-push
+ * `preflight` chain runs it FIRST — before `check_bridge_derivation` regenerates
+ * and erases the evidence. Both registrations are deliberate; neither subsumes
+ * the other.
+ *
+ * THE TWO ASSERTIONS
+ * ------------------
+ * 1. COMPLETENESS. Every rule the generator would emit has an entry in every
+ *    active host rule tree. The expected set comes from
+ *    `condense.projected_rule_trees()` — the generator's OWN emit plan, which
+ *    `generate_rule_symlinks` also consumes. It is deliberately NOT a list in
+ *    this file and deliberately NOT `dist/agent-src/rules/` verbatim: a
+ *    hand-maintained array goes obsolete silently, and the dist directory
+ *    over-counts by the ADR-004 `type: manual` rules the trees omit on purpose
+ *    (113 files on disk, 5 manual, 108 projected). A completeness check keyed on
+ *    a non-canonical source propagates that source's mistakes as requirements.
+ * 2. FRESHNESS. No rule in `dist/agent-src/rules/` may be newer than the
+ *    projection entry pointing at it. Entries are symlinks, so the comparison
+ *    uses `lstat` on the LINK, never `stat`: `stat` follows the link and returns
+ *    the target's own mtime, which would compare the dist file with itself and
+ *    make the assertion vacuous. Verified empirically before wiring — with a
+ *    target touched after the link was created, `lstat(link).mtimeMs !==
+ *    stat(target).mtimeMs` while `stat(link).mtimeMs === stat(target).mtimeMs`.
+ *    Under `lean_projection: thin` the entries are real files rather than
+ *    symlinks; `lstat` is correct there too (the file's own mtime).
+ *
+ * NOT IN SCOPE. `.cursor/rules/*.mdc` and `.windsurf/rules/` are written by
+ * different generators with their own filters; this gate covers the three trees
+ * `condense.TOOL_DIRS` projects (`.claude/rules`, `.cursor/rules`, `.clinerules`)
+ * and their `.md` entries, which is where the measured defect was.
+ *
+ * CLI: `--root <path>` (default: this repo) · `--quiet` suppresses the
+ * per-target ledger line. Exit 0 = complete and fresh, or no tool active at all
+ * (announced on stderr — see `auditRuleProjection`); 1 = any gap, any stale
+ * entry, a ledger accounting error, or a dead scan scope.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger, UnaccountedTargetsError } from './_lib/gate_ledger.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { _resetStateForTest as _pointCondenseAt, projected_rule_trees } from './condense.js';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Where the projected rules are condensed to — the freshness comparison's left side. */
+const DIST_RULES = path.join('dist', 'agent-src', 'rules');
+
+export type ProjectionFindingKind = 'missing' | 'stale' | 'dangling';
+
+export interface ProjectionFinding {
+    /** Repo-relative tool dir, e.g. `.claude/rules`. */
+    tree: string;
+    /** Rule basename, e.g. `secret-vcs-guard.md`. */
+    rule: string;
+    kind: ProjectionFindingKind;
+    message: string;
+}
+
+export interface ProjectionAudit {
+    findings: ProjectionFinding[];
+    /** `tree` → whether the directory exists at all; an absent tree fails every rule under it. */
+    treePresent: Record<string, boolean>;
+    ledger: GateLedger;
+}
+
+function _lstatOrNull(p: string): fs.Stats | null {
+    try {
+        return fs.lstatSync(p);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Audit `expected` (tool dir → rule basenames) against the trees under `repoRoot`.
+ *
+ * Pure read: every branch stats, none writes. `expected` is injected rather than
+ * computed here so the caller controls which root the generator's emit plan was
+ * derived from, and so a test can pin an expectation without a settings file.
+ */
+export function auditRuleProjection(
+    repoRoot: string,
+    expected: Readonly<Record<string, readonly string[]>>,
+): ProjectionAudit {
+    const ledger = new GateLedger('check_rule_projection_integrity');
+    const findings: ProjectionFinding[] = [];
+    const treePresent: Record<string, boolean> = {};
+
+    for (const [tree, rules] of Object.entries(expected)) {
+        ledger.plan(rules.map((r) => `${tree}/${r}`));
+    }
+
+    // The planned set is every (tree × rule) pair, and zero has TWO causes that
+    // are not the same defect. `projected_rule_trees()` returns one key per
+    // ACTIVE tool dir, so the key count is the discriminator:
+    //
+    //   - keys > 0, rules == 0 → the rule corpus is dead. No rule reached
+    //     `dist/agent-src/rules/`, or every scope filter rejected every rule,
+    //     and a green checkmark here would cover an assertion never evaluated.
+    //     This still throws.
+    //   - keys == 0 → `agents/.agent-tools.yml` selects zero tools, which
+    //     `_active_tools()` honours by design. There is no projection surface
+    //     in this checkout, so there is nothing to be stale or missing. That is
+    //     an absent optional surface, not a moved root.
+    //
+    // Conflating the two made the gate unsatisfiable on a supported config: it
+    // runs FIRST in the pre-push `preflight` chain, so a maintainer who
+    // deactivates the per-tool trees (they duplicate a globally installed
+    // `~/.claude`) could not push at all, with no fix available short of the
+    // env escape hatch. A gate whose only compliant path is to change an
+    // unrelated setting is not a gate. `main()` prints the skip explicitly —
+    // the empty case must be LOUD, never a silent green.
+    const noActiveTree = Object.keys(expected).length === 0;
+    assertScanned({
+        gate: 'check_rule_projection_integrity',
+        scanned: Object.values(expected).reduce((n, rules) => n + rules.length, 0),
+        units: 'projected rule entries',
+        roots: [DIST_RULES, ...Object.keys(expected)],
+        ...(noActiveTree
+            ? {
+                  allowEmpty:
+                      'OPTIONAL_INPUT: no host rule tree is active — agents/.agent-tools.yml ' +
+                      'selects zero tools, so the surface this gate audits does not exist in ' +
+                      'this checkout. With one or more active tools the emit plan carries the ' +
+                      'full rule set by construction, so a dead dist/agent-src/rules/ still fails here.',
+              }
+            : {}),
+    });
+
+    for (const [tree, rules] of Object.entries(expected)) {
+        const treeDir = path.join(repoRoot, tree);
+        const treeStat = _lstatOrNull(treeDir);
+        treePresent[tree] = treeStat !== null && treeStat.isDirectory();
+
+        for (const rule of rules) {
+            const target = `${tree}/${rule}`;
+            const entry = _lstatOrNull(path.join(treeDir, rule));
+            if (entry === null) {
+                findings.push({
+                    tree,
+                    rule,
+                    kind: 'missing',
+                    message: treePresent[tree]
+                        ? 'no projection entry — the rule reaches the model at no project scope'
+                        : 'projection tree does not exist',
+                });
+                ledger.fail(target, 'missing projection entry');
+                continue;
+            }
+
+            const dist = path.join(repoRoot, DIST_RULES, rule);
+            let distStat: fs.Stats;
+            try {
+                distStat = fs.statSync(dist);
+            } catch {
+                // Unreachable while `expected` derives from this same dist tree,
+                // but reachable if the tree changes under a running gate. Report
+                // rather than crash: a projection entry whose source is gone is
+                // a dangling link, which is a real defect either way.
+                findings.push({
+                    tree,
+                    rule,
+                    kind: 'dangling',
+                    message: `projection entry has no source at ${DIST_RULES}/${rule}`,
+                });
+                ledger.fail(target, 'dangling projection entry');
+                continue;
+            }
+
+            // `entry` is an lstat: for a symlink that is the LINK's mtime, which
+            // is what "when was this projected" means. `statSync` here follows
+            // nothing — dist rules are regular files.
+            if (distStat.mtimeMs > entry.mtimeMs) {
+                findings.push({
+                    tree,
+                    rule,
+                    kind: 'stale',
+                    message:
+                        `source is newer than the projection entry ` +
+                        `(${DIST_RULES}/${rule} ${new Date(distStat.mtimeMs).toISOString()} > ` +
+                        `entry ${new Date(entry.mtimeMs).toISOString()})`,
+                });
+                ledger.fail(target, 'stale projection entry');
+                continue;
+            }
+
+            ledger.complete(target);
+        }
+    }
+
+    return { findings, treePresent, ledger };
+}
+
+/** Group findings by tree, preserving rule order, for a report a reader can act on. */
+export function renderFindings(audit: ProjectionAudit): string[] {
+    const lines: string[] = [];
+    const byTree = new Map<string, ProjectionFinding[]>();
+    for (const f of audit.findings) {
+        const bucket = byTree.get(f.tree);
+        if (bucket === undefined) byTree.set(f.tree, [f]);
+        else bucket.push(f);
+    }
+    for (const [tree, group] of byTree) {
+        const missing = group.filter((f) => f.kind === 'missing');
+        const stale = group.filter((f) => f.kind === 'stale');
+        const dangling = group.filter((f) => f.kind === 'dangling');
+        if (audit.treePresent[tree] !== true) {
+            lines.push(`${tree}: tree does not exist — ${String(group.length)} rule(s) reach the model at no project scope`);
+        }
+        if (missing.length > 0) {
+            lines.push(`${tree}: ${String(missing.length)} rule(s) missing from the projection:`);
+            for (const f of missing) lines.push(`    - ${f.rule}`);
+        }
+        if (stale.length > 0) {
+            lines.push(`${tree}: ${String(stale.length)} projection entry/entries older than their source:`);
+            for (const f of stale) lines.push(`    - ${f.rule} — ${f.message}`);
+        }
+        if (dangling.length > 0) {
+            lines.push(`${tree}: ${String(dangling.length)} dangling projection entry/entries:`);
+            for (const f of dangling) lines.push(`    - ${f.rule} — ${f.message}`);
+        }
+    }
+    return lines;
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const quiet = args.includes('--quiet');
+    const idx = args.indexOf('--root');
+    const root = path.resolve(idx !== -1 ? (args[idx + 1] ?? REPO_ROOT) : REPO_ROOT);
+
+    // `condense`'s emit plan reads `MODULE_STATE`, whose only root seam is this
+    // reassignment. Repointing it is what makes `--root` mean the same thing for
+    // the expected set and for the trees being audited — without it the gate
+    // would compare this repo's rules against another checkout's projection.
+    _pointCondenseAt(root);
+
+    let audit: ProjectionAudit;
+    try {
+        audit = auditRuleProjection(root, projected_rule_trees());
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    // Zero active trees is a legitimate config (see `auditRuleProjection`), but
+    // it means this run audited nothing. Say so on its own line instead of
+    // letting the success line below report "0 entries across 0 trees", which
+    // reads as a pass to every human and every log scraper.
+    if (Object.keys(audit.treePresent).length === 0) {
+        process.stderr.write(
+            '⚠️  check_rule_projection_integrity: no host rule tree is active ' +
+                '(agents/.agent-tools.yml selects zero tools) — nothing to audit. This gate ' +
+                'has teeth only where a tool is active; CI activates all eight.\n',
+        );
+        return 0;
+    }
+
+    const lines = renderFindings(audit);
+
+    let tally;
+    try {
+        tally = quiet ? audit.ledger.finalize() : audit.ledger.report();
+    } catch (exc) {
+        if (exc instanceof UnaccountedTargetsError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    if (lines.length > 0) {
+        for (const l of lines) process.stderr.write(`❌  ${l}\n`);
+        process.stderr.write(
+            `\nThe host rule trees are the ONLY carrier for a non-kernel rule's prose ` +
+                `(docs/contracts/rule-router.md § no runtime router). Regenerate with ` +
+                `\`task generate-tools\`, then re-run this gate.\n`,
+        );
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `✅  ${String(tally.completed)} rule projection entries complete and fresh across ` +
+                `${String(Object.keys(audit.treePresent).length)} host rule tree(s)\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;
+    }
+    // A symlinked invocation makes the raw URLs differ (import.meta.url is the
+    // resolved real path, argv[1] keeps the symlink). Compare realpaths, or the
+    // CLI silently no-ops when run through a projection — the bundled-CLI-entry
+    // landmine this repo has already paid for once.
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}