@event4u/agent-config 9.26.0 → 9.28.0

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());
+}

package/src/scripts/condense.ts

@@ -1108,6 +1108,36 @@ function _scoped_rule_basenames(): string[] {
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
+/**
+ * The emit plan of {@link generate_rule_symlinks}: active tool dir → the exact
+ * rule basenames it projects there.
+ *
+ * Exported so a completeness gate can assert a host rule tree matches the
+ * generator WITHOUT regenerating it. That distinction is the whole point:
+ * `check_bridge_derivation` regenerates and then diffs, so it can only ever see
+ * a fixpoint, and a five-week-stale tree on a working checkout is invisible to
+ * it. A gate that reads the tree as it stands needs the expected set from
+ * somewhere, and every other candidate source is wrong in a way that
+ * propagates: a hand-maintained array goes obsolete silently, and
+ * `dist/agent-src/rules/` over-counts by the ADR-004 `type: manual` rules these
+ * trees deliberately omit (113 files, 5 manual, 108 projected).
+ *
+ * `generate_rule_symlinks` consumes this too, so there is one emit plan rather
+ * than a gate's reconstruction of one.
+ */
+export function projected_rule_trees(
+    user_home: string = process.env['HOME'] ?? os.homedir(),
+): Record<string, string[]> {
+    const rules = _scoped_rule_basenames();
+    const dedup_on = _read_projection_scope_dedup();
+    const out: Record<string, string[]> = {};
+    for (const tool_dir of Object.keys(_filter_tool_dirs(TOOL_DIRS))) {
+        const skip = dedup_on ? _dedupable_rules(tool_dir, rules, user_home) : new Set<string>();
+        out[tool_dir] = rules.filter((r) => !skip.has(r));
+    }
+    return out;
+}
+
 export function generate_rule_symlinks(): number {
     const rules = _scoped_rule_basenames();
     const tool_dirs = _filter_tool_dirs(TOOL_DIRS);
@@ -1130,14 +1160,18 @@ export function generate_rule_symlinks(): number {
         );
     }
 
-    const dedup_on = _read_projection_scope_dedup();
     const user_home = process.env['HOME'] ?? os.homedir();
+    // Read the emit plan from the exported function rather than recomputing the
+    // dedup skip here, so the gate that asserts this tree is complete and the
+    // code that writes it cannot disagree.
+    const plan = projected_rule_trees(user_home);
     const skipped_per_tool: Record<string, Set<string>> = {};
 
     let total = 0;
     for (const [tool_dir, rel_prefix] of Object.entries(tool_dirs)) {
         const target_dir = path.join(MODULE_STATE.PROJECT_ROOT, tool_dir);
-        const skip = dedup_on ? _dedupable_rules(tool_dir, rules, user_home) : new Set<string>();
+        const emit_here = new Set(plan[tool_dir] ?? rules);
+        const skip = new Set(rules.filter((r) => !emit_here.has(r)));
         skipped_per_tool[tool_dir] = skip;
         _mkdirp(target_dir);
         // Clean stale symlinks — a rule that became de-duplicable this run is

package/src/scripts/config/profiles.ts

@@ -130,7 +130,17 @@ function _load_yaml(p: string): Dict {
     return _isPlainDict(data) ? (data as Dict) : {};
 }
 
-function _profile_file(project_root: string, profile_id: string): string {
+/**
+ * The file `resolve_profile` will read for `profile_id`, or the legacy path
+ * when no candidate exists.
+ *
+ * Exported because a probe that reports "which profile is active" must name
+ * the file the resolver actually used. Re-deriving that path in the caller is
+ * how the two answers drift apart, which is the defect class
+ * `road-to-capability-answerability` exists to close — so there is exactly one
+ * implementation and both the resolver and `packs:active` call it.
+ */
+export function profile_file(project_root: string, profile_id: string): string {
     const legacy = path.join(project_root, PROFILES_DIRNAME, `${profile_id}.yml`);
     if (_exists(legacy)) {
         return legacy;
@@ -230,11 +240,11 @@ export function resolve_profile(params: {
         }
         return _build_resolved(
             DEFAULT_PROFILE_ID,
-            _load_yaml(_profile_file(params.project_root, DEFAULT_PROFILE_ID)),
+            _load_yaml(profile_file(params.project_root, DEFAULT_PROFILE_ID)),
             { source: SOURCE_DEFAULT },
         );
     }
-    const yaml_path = _profile_file(params.project_root, profile_id);
+    const yaml_path = profile_file(params.project_root, profile_id);
     if (!_exists(yaml_path)) {
         throw new ProfileError(
             `profile.id=${_repr(profile_id)} (${source}) but ${yaml_path} not found`,