@event4u/agent-config 9.27.0 → 9.29.0

package/src/scripts/check_council_config_location.ts

@@ -37,6 +37,14 @@
  *      (ADR-104); any project-tree path is drift. Corrective mentions ("is
  *      ignored", "never read", "no project-local", "superseded") pass on the
  *      same line. (PATH_CHECK_GLOBS)
+ *   4. NO always-loaded carrier for the user-global fact. §1–§3 keep the tree
+ *      honest but say nothing about REACH: before this check the fact lived
+ *      only in `src/skills/ai-council/SKILL.md`, a skill body that reaches
+ *      context only on activation, so consumer sessions repeatedly inferred
+ *      "council not configured" from a missing `.agent-settings.yml` while the
+ *      council was configured all along. §4 requires one rule under
+ *      `src/rules/` to carry the fact and to project at least as widely as the
+ *      kernel reference. (RULES_GLOB)
  *
  * Escape hatch: a line carrying `<!-- council-config-allowed -->` is exempt
  * (for a legitimate non-council `.agent-settings.yml` reference, e.g.
@@ -64,6 +72,7 @@ const SCAN_GLOBS = [
     'src/domains/meta/council/**/*.md',
     'src/domains/product-basic/roadmap/ai-council/**/*.md',
     'src/skills/ai-council/**/*.md',
+    'src/rules/council-availability.md',
     'docs/contracts/ai-council-config.md',
 ] as const;
 
@@ -105,6 +114,35 @@ const PROJECT_PATH_COUNCIL_RE =
 const PATH_NEGATION_RE =
     /\b(not|never|removed|no\s+longer|neither|instead|ignored|superseded|no\s+project-local|not\s+read|does\s+not\s+read)\b/i;
 
+// ── §4 always-loaded carrier check ─────────────────────────────────
+// The user-global fact is useless where the agent cannot see it. Before this
+// check the fact lived only in `src/skills/ai-council/SKILL.md` — a skill body
+// that only reaches context on activation — so consumer sessions repeatedly
+// inferred "council not configured" from a missing `.agent-settings.yml` and
+// substituted a subagent fan-out while the council was configured all along.
+// §4 pins the fix: at least one rule under `src/rules/` must carry the fact,
+// declare a council trigger, and project at least as widely as the kernel.
+const RULES_GLOB = 'src/rules/**/*.md';
+// Reference for the reach requirement: a carrier scoped more narrowly than an
+// always-loaded kernel rule would not reach the consumer repos that failed.
+const REACH_REFERENCE_RULE = 'src/rules/direct-answers.md';
+const WORKSPACES_RE = /^workspaces:\s*\[([^\]]*)\]/m;
+// The three markers a carrier must show, all in the same file.
+const CARRIER_MARKERS = [
+    {
+        re: /^\s*-\s*keyword:\s*"council"\s*$/m,
+        what: 'a `- keyword: "council"` trigger',
+    },
+    {
+        re: /~\/\.event4u\/agent-config\/settings\/\.ai-council\.yml/,
+        what: 'the one real user-global config path',
+    },
+    {
+        re: /NEVER\s+INFER\s+"NOT\s+CONFIGURED"/i,
+        what: 'the never-infer-from-project-files obligation',
+    },
+] as const;
+
 /**
  * Mirror Python `str.lstrip()` — strips all leading Unicode whitespace.
  * Python's `str.lstrip()` (no args) strips the Unicode whitespace class;
@@ -318,6 +356,84 @@ function find_path_violations(root: string): string[] {
     return findings;
 }
 
+/** Parse a rule's `workspaces: [a, b, c]` frontmatter line into a set. */
+function _workspaces(text: string): Set<string> {
+    const m = WORKSPACES_RE.exec(text);
+    if (m === null) {
+        return new Set<string>();
+    }
+    return new Set(
+        m[1]!
+            .split(',')
+            .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+            .filter((s) => s.length > 0),
+    );
+}
+
+/**
+ * §4 — the user-global fact must have an always-loaded carrier (reach check).
+ *
+ * A correct resolver, a correct skill, and a green §1–§3 still left consumer
+ * sessions claiming "council not configured" — because the fact reached no
+ * always-loaded surface. This check fails when no rule under `src/rules/`
+ * carries it, and when every carrier that does is scoped more narrowly than
+ * the kernel reference (i.e. would not reach the consumer repos that failed).
+ */
+function find_carrier_violations(root: string): string[] {
+    // Scope guard: only a tree that HAS a rule layer can carry the fact. A
+    // consumer checkout or a tmp fixture without `src/rules/` is out of scope,
+    // exactly as a missing `src/skills/ai-council/` is for §1. The real-repo
+    // test asserts this scope is live here, so the skip cannot go unnoticed.
+    if (!_isDir(path.join(root, 'src', 'rules'))) {
+        return [];
+    }
+    const rules = [...iter_files(root, [RULES_GLOB])];
+    if (rules.length === 0) {
+        return [
+            `${RULES_GLOB}: \`src/rules/\` exists but resolved to no files — ` +
+                'the council user-global fact is unpinned.',
+        ];
+    }
+    const carriers = rules.filter((p) => {
+        const text = fs.readFileSync(p, 'utf-8');
+        return CARRIER_MARKERS.every((m) => m.re.test(text));
+    });
+    if (carriers.length === 0) {
+        return [
+            'src/rules/: no always-loaded rule carries the council user-global ' +
+                'fact. One rule must show all of — ' +
+                CARRIER_MARKERS.map((m) => m.what).join('; ') +
+                '. Without it the fact lives only in ' +
+                '`src/skills/ai-council/SKILL.md`, whose body reaches context ' +
+                'only on skill activation.',
+        ];
+    }
+    const refPath = path.join(root, REACH_REFERENCE_RULE);
+    if (!_isFile(refPath)) {
+        return [];
+    }
+    const refWs = _workspaces(fs.readFileSync(refPath, 'utf-8'));
+    if (refWs.size === 0) {
+        return [];
+    }
+    const findings: string[] = [];
+    for (const p of carriers) {
+        const missing = [...refWs].filter(
+            (w) => !_workspaces(fs.readFileSync(p, 'utf-8')).has(w),
+        );
+        if (missing.length > 0) {
+            findings.push(
+                `${_relPosix(root, p)}: council carrier is scoped more narrowly ` +
+                    `than \`${REACH_REFERENCE_RULE}\` — missing workspace(s): ` +
+                    `${missing.join(', ')}. A carrier the consumer never receives ` +
+                    'is exactly the gap this check exists to close.',
+            );
+        }
+    }
+    // One carrier with full reach is enough; only report when none has it.
+    return findings.length === carriers.length ? findings : [];
+}
+
 function main(): number {
     const root = process.cwd();
     // PATH_CHECK_GLOBS is the superset of both passes, so its resolution is the
@@ -338,7 +454,11 @@ function main(): number {
         }
         throw exc;
     }
-    const findings = [...find_violations(root), ...find_path_violations(root)];
+    const findings = [
+        ...find_violations(root),
+        ...find_path_violations(root),
+        ...find_carrier_violations(root),
+    ];
     if (findings.length) {
         process.stdout.write('❌  Council config-location violations:\n\n');
         for (const f of findings) {
@@ -396,5 +516,9 @@ export {
     iter_files,
     find_violations,
     find_path_violations,
+    find_carrier_violations,
+    RULES_GLOB,
+    REACH_REFERENCE_RULE,
+    CARRIER_MARKERS,
     main,
 };

package/src/scripts/check_detector_corpus.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * Detector corpus gate (P4.3 of road-to-rule-delivery-integrity).
+ *
+ * Every self-repair detector must carry all THREE fixture classes, and every
+ * fixture must behave as its class says:
+ *
+ *   fire            a recorded real failure the detector must catch
+ *   near-miss-fire  a real failure phrased unlike the canonical one, which must
+ *                   still be caught — recall at the boundary
+ *   must-not-fire   text that superficially matches and must stay silent
+ *
+ * The three-class rule is the point of the gate rather than a stylistic one.
+ * Precision and recall fail in opposite directions and a single corpus hides
+ * that: a detector with `fire` cases only looks perfect while opening records on
+ * praise, which is exactly what `detectUserReport` did until 2026-08-09 (it
+ * fired on "das ist fine, du hast nichts falsch gemacht"). A missing class is
+ * therefore a gate failure, not a warning — the absent half is where the defects
+ * live.
+ *
+ * Registration is explicit: a detector added to `self_repair.ts` without a
+ * matching corpus entry fails here, which is the coupling that keeps the corpus
+ * from silently lagging the code.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as YAML from 'yaml';
+
+import {
+    type DefectFinding,
+    type TurnSnapshot,
+    detectCouncilClaim,
+    detectLanguageMirror,
+    detectUserReport,
+} from './_lib/self_repair.js';
+import { assertScanned } from './_lib/scan_scope.js';
+
+export const CORPUS_REL = path.join('tests', 'fixtures', 'self-repair-detector-corpus.yml');
+
+const GATE = 'check_detector_corpus';
+const CLASSES = ['fire', 'near-miss-fire', 'must-not-fire'] as const;
+type FixtureClass = (typeof CLASSES)[number];
+
+/** One corpus entry, in the union of shapes the three detectors need. */
+export interface Fixture {
+    text?: string;
+    reply?: string;
+    pinned_language?: 'de' | 'en';
+    tool_commands?: string[];
+    note?: string;
+}
+
+export type Corpus = Record<string, Partial<Record<FixtureClass, Fixture[]>>>;
+
+/**
+ * Every detector that must appear in the corpus, with how to run it.
+ *
+ * Keyed by the `defect_class` the detector produces, so the corpus reads as a
+ * list of defect classes rather than of function names.
+ */
+export const DETECTORS: Record<string, (f: Fixture) => DefectFinding | null> = {
+    'user-reported': (f) => detectUserReport(f.text ?? f.reply ?? ''),
+    'council-availability-claim': (f) => detectCouncilClaim(asTurn(f)),
+    'language-mirror': (f) => detectLanguageMirror(asTurn(f)),
+};
+
+function asTurn(f: Fixture): TurnSnapshot {
+    return {
+        prompt: f.text ?? '',
+        reply: f.reply ?? '',
+        toolCommands: f.tool_commands ?? [],
+        pinnedLanguage: f.pinned_language ?? null,
+    };
+}
+
+export interface Finding {
+    detector: string;
+    kind: 'missing-class' | 'empty-class' | 'wrong-outcome' | 'unregistered';
+    message: string;
+}
+
+/** Pure: audit a parsed corpus against the registered detectors. */
+export function auditCorpus(corpus: Corpus): { findings: Finding[]; fixtures: number } {
+    const findings: Finding[] = [];
+    let fixtures = 0;
+
+    for (const name of Object.keys(corpus)) {
+        if (!(name in DETECTORS)) {
+            findings.push({
+                detector: name,
+                kind: 'unregistered',
+                message: `corpus names "${name}", which is not a registered detector`,
+            });
+        }
+    }
+
+    for (const [name, run] of Object.entries(DETECTORS)) {
+        const entry = corpus[name];
+        if (entry === undefined) {
+            findings.push({
+                detector: name,
+                kind: 'missing-class',
+                message: `no corpus entry at all — needs all of: ${CLASSES.join(', ')}`,
+            });
+            continue;
+        }
+        for (const cls of CLASSES) {
+            const cases = entry[cls];
+            if (cases === undefined) {
+                findings.push({
+                    detector: name,
+                    kind: 'missing-class',
+                    message: `missing the \`${cls}\` class`,
+                });
+                continue;
+            }
+            if (cases.length === 0) {
+                // An empty class is the same hole as a missing one wearing a key.
+                findings.push({
+                    detector: name,
+                    kind: 'empty-class',
+                    message: `\`${cls}\` is present but empty`,
+                });
+                continue;
+            }
+            for (const f of cases) {
+                fixtures += 1;
+                const fired = run(f) !== null;
+                const shouldFire = cls !== 'must-not-fire';
+                if (fired !== shouldFire) {
+                    const what = f.text ?? f.reply ?? '(empty)';
+                    findings.push({
+                        detector: name,
+                        kind: 'wrong-outcome',
+                        message:
+                            `\`${cls}\` fixture ${shouldFire ? 'did NOT fire' : 'FIRED'}: ` +
+                            JSON.stringify(what.slice(0, 90)),
+                    });
+                }
+            }
+        }
+    }
+    return { findings, fixtures };
+}
+
+export function loadCorpus(repoRoot: string): Corpus {
+    const p = path.join(repoRoot, CORPUS_REL);
+    const parsed = YAML.parse(fs.readFileSync(p, 'utf-8')) as { detectors?: Corpus };
+    return parsed.detectors ?? {};
+}
+
+export function main(repoRoot: string = process.cwd()): number {
+    const corpus = loadCorpus(repoRoot);
+    const { findings, fixtures } = auditCorpus(corpus);
+
+    // A corpus that parsed to nothing is the dead-scope case, not a pass.
+    assertScanned({
+        gate: GATE,
+        scanned: fixtures,
+        units: 'detector fixtures',
+        roots: [CORPUS_REL],
+    });
+
+    if (findings.length > 0) {
+        process.stderr.write(`${GATE}: ${String(findings.length)} finding(s)\n\n`);
+        for (const f of findings) {
+            process.stderr.write(`  ${f.detector}: ${f.message}\n`);
+        }
+        process.stderr.write(
+            `\nEvery detector needs all three classes (${CLASSES.join(', ')}) and every\n` +
+                'fixture must behave as its class says. Precision and recall fail in\n' +
+                'opposite directions; a corpus missing one half hides the other.\n',
+        );
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  ${GATE}: ${String(Object.keys(DETECTORS).length)} detector(s) × ` +
+            `${String(CLASSES.length)} classes, ${String(fixtures)} fixtures, all behaving\n`,
+    );
+    return 0;
+}
+
+function isCliEntry(): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(argv1))
+        );
+    } catch {
+        return pathToFileURL(argv1).href === import.meta.url;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/check_hook_bundle_freshness.ts

@@ -31,7 +31,10 @@
  * WHAT IT DOES NOT DO: it never builds. Building into a live hook path is a
  * documented hazard in this repo (an esbuild run that overwrites the
  * dispatcher a running hook is executing can wedge the tool loop), so the
- * remedy is printed for a human to run deliberately.
+ * remedy is printed for a human to run deliberately. The SAFE rebuild
+ * (build to .new → probe → atomic rename) lives in `rebuild_hook_bundle.ts`,
+ * which preflight runs right before this gate — so a red here means the heal
+ * itself failed or was bypassed, not merely that a merge landed.
  *
  * Exit codes: 0 = fresh, or no self-hosted bundle to check · 1 = stale.
  */

package/src/scripts/check_standing_rule_delivery.ts

@@ -0,0 +1,314 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Gate — how many rule tokens does a session actually RECEIVE?
+ *
+ * P1.2 of `road-to-rule-delivery-integrity`. Claude Code loads
+ * `~/.claude/rules/` and `<project>/.claude/rules/` **both**, user layer first,
+ * with no dedup between them (host contract, quoted with citations in
+ * `agents/evidence/analysis/claude-code-rules-dir-contract.md`). So the number
+ * that matters is not what one tree contains — it is the sum of what arrives.
+ *
+ * Measured 2026-08-08 on a maintainer machine, exact BPE: **176,354 tokens
+ * standing, 74,137 of them (42%) the same 91 rules twice.** Full six-topology
+ * accounting: `agents/evidence/analysis/standing-rule-delivery-topologies.md`.
+ *
+ * Three deliberate properties:
+ *
+ * 1. **Measure what arrived, not what was projected.** Where an
+ *    `InstructionsLoaded` record exists (the host logs which instruction files
+ *    loaded, when, and why) the gate reads it and the filesystem sum becomes a
+ *    cross-check. Where it does not, the filesystem sum stands alone. The gate
+ *    always NAMES which input it used — a filesystem-only sum cannot see a rule
+ *    that is projected but never loaded, nor one that loads from a layer nobody
+ *    projected, and the second of those is the defect itself.
+ * 2. **`assertScanned` posture.** Zero rule files is exit 3, not green. This
+ *    repo has shipped gates that scanned an emptied tree and certified coverage
+ *    that did not exist; the posture is the recorded fix, not boilerplate.
+ * 3. **The ceiling cannot be raised silently.** `cap_raise_reason` in
+ *    `src/config/budgets.yml` must be a real sentence naming which rule added
+ *    the tokens. A placeholder fails the gate.
+ *
+ * Exit codes: `0` under cap · `1` over cap or an unstated cap raise · `2` usage
+ * error · `3` dead scan scope.
+ *
+ * ## This is deliberately NOT a CI gate
+ *
+ * Both inputs are machine-local by construction. `.claude/rules/` is gitignored
+ * (`.gitignore:123` — it is generated by `task sync` / `task generate-tools`),
+ * and no CI workflow performs a user-scope install, so on a fresh runner
+ * **neither** layer exists. Wired into `ci` it would either red on a dead scope
+ * or, with the empty case allowed, sit permanently green while certifying a
+ * property it cannot observe — the exact failure `src/config/gate-coverage.yml`
+ * was written to end. It is therefore registered as a local / doctor-surface
+ * check and is absent from `gate-coverage.yml`, whose contract is CI-identical
+ * invocation.
+ *
+ * What that costs, stated plainly: the duplicate-delivery defect is not
+ * mechanically caught for anyone who never runs this locally. The enforced layer
+ * is the installer gate (`install.ts::_gate_rule_layer_overlap`), which refuses
+ * to CREATE the doubled state; this script measures a state that already exists.
+ * Making the measurement CI-observable needs the `InstructionsLoaded` record
+ * committed from a real session, which is a different piece of work.
+ */
+
+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 } from 'node:url';
+
+import { assertScanned, DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+import { measure, method_note } from './_lib/token_count.js';
+import * as rule_layer_overlap from './_lib/rule_layer_overlap.js';
+
+const PROG = 'check_standing_rule_delivery';
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const BUDGETS = path.join(REPO_ROOT, 'src', 'config', 'budgets.yml');
+
+/** Placeholder reasons that do not count as a stated cause for a cap raise. */
+const PLACEHOLDER_REASONS: readonly string[] = ['', '-', 'tbd', 'todo', 'n/a', 'na', 'none', 'bump'];
+
+interface Budget {
+    readonly total_cap_tokens: number;
+    readonly warn_threshold: number;
+    readonly cap_raise_reason: string;
+}
+
+/**
+ * Read the `standing_rule_delivery` block from `budgets.yml`.
+ *
+ * Deliberately a narrow line scan rather than a YAML dependency: this gate must
+ * run in a consumer tree where `yaml` may not be installed, and the three keys
+ * it needs are flat scalars. An absent block is a configuration error (exit 2),
+ * never a permissive default — a budget gate that invents its own ceiling is
+ * the same class of failure as one that scans nothing.
+ */
+export function readBudget(text: string): Budget | null {
+    const lines = text.split('\n');
+    const start = lines.findIndex((l) => l.trimEnd() === 'standing_rule_delivery:');
+    if (start === -1) return null;
+    let cap: number | null = null;
+    let warn: number | null = null;
+    let reason: string | null = null;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (/^\S/.test(line)) break; // next top-level key ends the block
+        const m = /^\s+([a-z_]+):\s*(.*)$/.exec(line);
+        if (m === null) continue;
+        const [, key, rawValue] = m;
+        const value = (rawValue ?? '').trim().replace(/^['"]|['"]$/g, '');
+        if (key === 'total_cap_tokens') cap = Number.parseInt(value, 10);
+        if (key === 'warn_threshold') warn = Number.parseFloat(value);
+        if (key === 'cap_raise_reason') reason = value;
+    }
+    if (cap === null || Number.isNaN(cap) || warn === null || Number.isNaN(warn) || reason === null) {
+        return null;
+    }
+    return { total_cap_tokens: cap, warn_threshold: warn, cap_raise_reason: reason };
+}
+
+/** Is `reason` a real stated cause, or a placeholder? */
+export function reasonIsStated(reason: string): boolean {
+    return !PLACEHOLDER_REASONS.includes(reason.trim().toLowerCase());
+}
+
+/** One measured layer. */
+interface LayerMeasure {
+    readonly label: string;
+    readonly dir: string;
+    readonly files: number;
+    readonly tokens: number;
+    readonly exact: boolean;
+}
+
+function measureLayer(label: string, dir: string): LayerMeasure | null {
+    const layer = rule_layer_overlap.readRuleLayer(dir);
+    if (layer === null) return null;
+    const joined = [...layer.files.values()].join('\n');
+    const m = measure(joined);
+    return {
+        label,
+        dir,
+        files: layer.files.size,
+        tokens: m.tokens_gpt,
+        exact: m.tokens_gpt_exact,
+    };
+}
+
+/**
+ * Where the loaded-instruction record would live if the host wrote one.
+ *
+ * Returning a path that does not exist is the expected case today: the
+ * `InstructionsLoaded` hook is a host feature this suite does not yet bind, so
+ * the gate reports `filesystem` as its input and says so. The probe exists now
+ * so that the day the hook is bound, the gate reads the better input without a
+ * second change — and so that "which input did this number come from" is
+ * answerable rather than assumed.
+ */
+export function instructionsLoadedRecord(repo_root: string): string {
+    return path.join(repo_root, 'agents', 'runtime', 'metrics', 'instructions-loaded.jsonl');
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const unknown = argv.filter((a) => a !== '--quiet');
+    if (unknown.length > 0) {
+        process.stderr.write(`usage: ${PROG} [--quiet]\n`);
+        process.stderr.write(`${PROG}: error: unrecognized arguments: ${unknown.join(' ')}\n`);
+        return 2;
+    }
+    const quiet = argv.includes('--quiet');
+    const out = (s: string): void => {
+        if (!quiet) process.stdout.write(s);
+    };
+
+    let budget: Budget | null;
+    try {
+        budget = readBudget(fs.readFileSync(BUDGETS, 'utf-8'));
+    } catch {
+        process.stderr.write(`❌  ${PROG}: cannot read ${path.relative(REPO_ROOT, BUDGETS)}\n`);
+        return 2;
+    }
+    if (budget === null) {
+        process.stderr.write(
+            `❌  ${PROG}: no complete \`standing_rule_delivery\` block in `
+                + `${path.relative(REPO_ROOT, BUDGETS)} — needs total_cap_tokens, `
+                + 'warn_threshold and cap_raise_reason. A budget gate does not invent its own ceiling.\n',
+        );
+        return 2;
+    }
+    if (!reasonIsStated(budget.cap_raise_reason)) {
+        process.stderr.write(
+            `❌  ${PROG}: cap_raise_reason is a placeholder (${JSON.stringify(budget.cap_raise_reason)}). `
+                + 'Every ceiling value needs a stated cause naming which rule added the tokens and why.\n',
+        );
+        return 1;
+    }
+
+    const layers = [
+        measureLayer('global', path.join(os.homedir(), '.claude', 'rules')),
+        measureLayer('project', path.join(REPO_ROOT, '.claude', 'rules')),
+    ].filter((l): l is LayerMeasure => l !== null);
+
+    const scanned = layers.reduce((n, l) => n + l.files, 0);
+    // Two zeroes that mean opposite things, and conflating them is how this gate
+    // would become the thing it guards against:
+    //
+    // - **No layer directory at all** — a machine that has not installed the
+    //   suite. Zero rule tokens are delivered, which IS the success state, so
+    //   `allowEmpty` is honest here and passes scan_scope's own operational test
+    //   ("if the scan root were deleted, would the reason still make sense?" —
+    //   yes: nothing installed, nothing loaded).
+    // - **A layer directory that exists and holds no `.md`** — a projection that
+    //   ran and produced nothing. That is blindness, not cleanliness, and it
+    //   stays exit 3.
+    const no_layer_present = layers.length === 0;
+    try {
+        assertScanned({
+            gate: PROG,
+            scanned,
+            units: 'rule file(s) across the layers a session loads',
+            roots: ['~/.claude/rules', '.claude/rules'],
+            ...(no_layer_present
+                ? {
+                      allowEmpty:
+                          'EMPTY_VALID: neither ~/.claude/rules nor .claude/rules exists on this '
+                          + 'machine, so zero rule tokens are delivered — the success state, not a dead scope.',
+                  }
+                : {}),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+    if (no_layer_present) {
+        out(
+            `${PROG}: no rule layer on this machine (neither ~/.claude/rules nor .claude/rules) — `
+                + 'nothing is delivered, nothing to cap.\n',
+        );
+        reportScanned({
+            gate: PROG,
+            scanned: 0,
+            units: 'rule file(s)',
+            roots: ['~/.claude/rules', '.claude/rules'],
+            allowEmpty: 'EMPTY_VALID: no layer installed on this machine.',
+        });
+        return 0;
+    }
+
+    const record = instructionsLoadedRecord(REPO_ROOT);
+    const input = fs.existsSync(record) ? 'instructions-loaded' : 'filesystem';
+    const total = layers.reduce((n, l) => n + l.tokens, 0);
+    const exact = layers.every((l) => l.exact);
+
+    out(`${PROG} · input: ${input} · ${method_note()}\n`);
+    if (input === 'filesystem') {
+        out(
+            '  note: no InstructionsLoaded record present, so this is what the filesystem\n'
+                + '        projects, not what the host confirmed loading. A rule projected but never\n'
+                + '        loaded, or loaded from an unprojected layer, is invisible to this input.\n',
+        );
+    }
+    for (const l of layers) {
+        out(`  ${l.label.padEnd(8)} ${String(l.files).padStart(4)} file(s)  ${String(l.tokens).padStart(8)} tok\n`);
+    }
+
+    if (layers.length === 2) {
+        const g = rule_layer_overlap.readRuleLayer(layers[0]!.dir);
+        const p = rule_layer_overlap.readRuleLayer(layers[1]!.dir);
+        if (g !== null && p !== null) {
+            const r = rule_layer_overlap.compareLayers(g.files, p.files);
+            if (r.overlap.length > 0) {
+                out(
+                    `  overlap  ${String(r.overlap.length).padStart(4)} rule(s) in both layers `
+                        + `(${r.duplicate.length} duplicate, ${r.divergent.length} divergent)\n`,
+                );
+            }
+        }
+    }
+
+    const pct = total / budget.total_cap_tokens;
+    out(
+        `  TOTAL    ${String(total).padStart(13)} tok / ${budget.total_cap_tokens} cap `
+            + `(${(pct * 100).toFixed(1)}%)${exact ? '' : ' — proxy, not exact'}\n`,
+    );
+    reportScanned({
+        gate: PROG,
+        scanned,
+        units: 'rule file(s)',
+        roots: ['~/.claude/rules', '.claude/rules'],
+    });
+
+    if (pct > 1) {
+        process.stderr.write(
+            `❌  ${PROG}: ${total} tok of standing rule prose exceeds the ${budget.total_cap_tokens} cap. `
+                + 'If two layers overlap, `agent-config install --layer=<global|project>` suppresses one '
+                + 'without deleting a file; otherwise scope rules with `paths:` or move bodies into the digest.\n',
+        );
+        return 1;
+    }
+    if (pct >= budget.warn_threshold) {
+        process.stderr.write(
+            `⚠️  ${PROG}: ${(pct * 100).toFixed(1)}% of the standing rule cap used `
+                + `(warn at ${(budget.warn_threshold * 100).toFixed(0)}%).\n`,
+        );
+    }
+    out(`✅  ${PROG}: standing rule delivery within cap\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    try {
+        if (process.argv[1] === undefined) return false;
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}