@event4u/agent-config 9.29.0 → 9.31.0

package/src/scripts/check_adr_frontmatter.ts

@@ -35,6 +35,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -101,48 +102,81 @@ export function trigger_is_meaningful(value: string): boolean {
     return true;
 }
 
-export function check(dir: string = ADR_DIR): AdrFinding[] {
+/** Every frontmatter finding for one ADR file. Pure — no I/O, no enumeration. */
+export function check_one(rel: string, text: string): AdrFinding[] {
+    const findings: AdrFinding[] = [];
+    const fm = parse_frontmatter(text);
+
+    if (fm === null) {
+        findings.push({ file: rel, level: 'error', message: 'no YAML frontmatter block' });
+        return findings;
+    }
+    for (const req of REQUIRED) {
+        if (!fm[req]) findings.push({ file: rel, level: 'error', message: `missing \`${req}\`` });
+    }
+    if (fm['status'] && !ALLOWED_STATUS.has(fm['status'])) {
+        findings.push({
+            file: rel,
+            level: 'error',
+            message: `status \`${fm['status']}\` is not one of: ${[...ALLOWED_STATUS].sort().join(', ')}`,
+        });
+    }
+
+    const date = fm['date'] ?? '';
+    const grandfathered = date !== '' && date < REVIEW_TRIGGER_SINCE;
+    const trigger = fm['review_trigger'];
+
+    if (!trigger) {
+        findings.push({
+            file: rel,
+            level: grandfathered ? 'warn' : 'error',
+            message: grandfathered
+                ? `no \`review_trigger\` (grandfathered — dated ${date}, before ${REVIEW_TRIGGER_SINCE})`
+                : `missing \`review_trigger\` — name the CONDITION that would reopen this decision`,
+        });
+    } else if (!trigger_is_meaningful(trigger)) {
+        findings.push({
+            file: rel,
+            level: grandfathered ? 'warn' : 'error',
+            message: `\`review_trigger\` is a cadence, not a condition: "${trigger}". A calendar review is ignored; an event fires.`,
+        });
+    }
+    return findings;
+}
+
+/**
+ * Check every ADR in `dir`, optionally recording per-file completeness.
+ *
+ * The candidate set is every `*.md` in the directory, not the `ADR-*.md` subset:
+ * the name filter used to be a bare `continue`, so a decision record saved as
+ * `adr-131-foo.md` (lower case) or `131-foo.md` left the corpus without a trace
+ * and the gate still printed a green line over the files it did read. It is now
+ * an out-of-scope outcome with a reason, and it prints.
+ *
+ * A `warn`-level finding resolves as `complete`: warnings are allowed by this
+ * gate's exit-code contract, so `fail` is reserved for what actually reds it.
+ */
+export function check(dir: string = ADR_DIR, ledger?: GateLedger): AdrFinding[] {
     const findings: AdrFinding[] = [];
     if (!fs.existsSync(dir)) return findings;
 
-    for (const name of fs.readdirSync(dir).sort()) {
-        if (!/^ADR-.*\.md$/.test(name)) continue;
-        const rel = path.relative(REPO_ROOT, path.join(dir, name));
-        const fm = parse_frontmatter(fs.readFileSync(path.join(dir, name), 'utf-8'));
+    const candidates = fs.readdirSync(dir).filter((n) => n.endsWith('.md')).sort();
+    ledger?.plan(candidates);
 
-        if (fm === null) {
-            findings.push({ file: rel, level: 'error', message: 'no YAML frontmatter block' });
+    for (const name of candidates) {
+        if (!/^ADR-.*\.md$/.test(name)) {
+            ledger?.outOfScope(name, 'not_applicable_kind');
             continue;
         }
-        for (const req of REQUIRED) {
-            if (!fm[req]) findings.push({ file: rel, level: 'error', message: `missing \`${req}\`` });
-        }
-        if (fm['status'] && !ALLOWED_STATUS.has(fm['status'])) {
-            findings.push({
-                file: rel,
-                level: 'error',
-                message: `status \`${fm['status']}\` is not one of: ${[...ALLOWED_STATUS].sort().join(', ')}`,
-            });
-        }
+        const rel = path.relative(REPO_ROOT, path.join(dir, name));
+        const own = check_one(rel, fs.readFileSync(path.join(dir, name), 'utf-8'));
+        findings.push(...own);
 
-        const date = fm['date'] ?? '';
-        const grandfathered = date !== '' && date < REVIEW_TRIGGER_SINCE;
-        const trigger = fm['review_trigger'];
-
-        if (!trigger) {
-            findings.push({
-                file: rel,
-                level: grandfathered ? 'warn' : 'error',
-                message: grandfathered
-                    ? `no \`review_trigger\` (grandfathered — dated ${date}, before ${REVIEW_TRIGGER_SINCE})`
-                    : `missing \`review_trigger\` — name the CONDITION that would reopen this decision`,
-            });
-        } else if (!trigger_is_meaningful(trigger)) {
-            findings.push({
-                file: rel,
-                level: grandfathered ? 'warn' : 'error',
-                message: `\`review_trigger\` is a cadence, not a condition: "${trigger}". A calendar review is ignored; an event fires.`,
-            });
+        const errors = own.filter((f) => f.level === 'error').length;
+        if (errors > 0) {
+            ledger?.fail(name, `${String(errors)} frontmatter error(s)`);
+        } else {
+            ledger?.complete(name);
         }
     }
     return findings;
@@ -150,10 +184,17 @@ export function check(dir: string = ADR_DIR): AdrFinding[] {
 
 function main(argv: string[]): number {
     const as_json = argv.includes('--json');
-    const findings = check();
-    const total = fs.existsSync(ADR_DIR)
-        ? fs.readdirSync(ADR_DIR).filter((f) => /^ADR-.*\.md$/.test(f)).length
-        : 0;
+    const ledger = new GateLedger('check_adr_frontmatter');
+    const findings = check(ADR_DIR, ledger);
+    // Finalized here, printed later by `report()` (which re-finalizes — the call
+    // is pure): the denominator is needed for the scope assertion below, which
+    // runs before any output. It is the ledger's own per-file accounting — the
+    // ADRs that actually reached a checked outcome — where it used to be a SECOND
+    // `readdirSync` of the same directory, independent of the loop that did the
+    // work, so the printed count could not disagree with the scan even when the
+    // scan had skipped files.
+    const tally = ledger.finalize();
+    const total = tally.completed + tally.failed;
 
     // `check()` returns findings, never a count, so a moved `docs/decisions/`
     // yields an empty list — reported as "0 ADR(s) · 0 error(s)" and green.
@@ -174,7 +215,9 @@ function main(argv: string[]): number {
     }
 
     if (as_json) {
-        process.stdout.write(JSON.stringify({ findings }, null, 2) + '\n');
+        // The tally rides in the payload rather than on stdout: `ledger.report()`
+        // would print beside the JSON and break every parser of this mode.
+        process.stdout.write(JSON.stringify({ findings, ledger: tally }, null, 2) + '\n');
         return 0;
     }
 
@@ -185,6 +228,7 @@ function main(argv: string[]): number {
         `ADR frontmatter: ${total} ADR(s) · ${errors.length} error(s) · ` +
             `${warns.length} grandfathered without a revisit condition\n`,
     );
+    ledger.report();
     for (const e of errors) process.stderr.write(`    ❌ ${e.file}: ${e.message}\n`);
 
     if (errors.length > 0) {

package/src/scripts/check_branch_freshness.ts

@@ -41,6 +41,7 @@ import { fileURLToPath } from "node:url";
 import { runGateCli, runSelfTest, type SelfTestCase } from "./_lib/gate_self_test.js";
 import { reportScanned } from "./_lib/scan_scope.js";
 
+// ledger-exempt: single remote-ref probe — the entire scope is ONE ls-remote answer (0 or 1 refs) resolved to one aggregate ancestor verdict, and every empty path already publishes its reason via reportScanned allowEmpty; there is no per-target collection to account.
 const DEFAULT_BASE = "main";
 const SELF_TEST_MIN_CASES = 3;
 const SELF_TEST_MIN_REJECT = 1;

package/src/scripts/check_corpus_staleness.ts

@@ -49,6 +49,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
@@ -423,20 +424,32 @@ export interface RunResult {
     readonly corpora: number;
     /** CSVs actually opened, reported so "checked nothing" cannot read as clean. */
     readonly csvs: number;
+    /** Per-corpus completeness accounting — every discovered corpus reaches one outcome. */
+    readonly ledger: GateLedger;
 }
 
 export function run_checks(todayStamp: number, skillsDir: string = SKILLS_DIR): RunResult {
     const corpora = discover_corpora(skillsDir);
+    const ledger = new GateLedger('check_corpus_staleness');
+    ledger.plan(corpora.map((c) => c.slug));
     const findings: CorpusFinding[] = [];
     let csvs = 0;
     for (const corpus of corpora) {
-        findings.push(...check_staleness(corpus, todayStamp));
-        findings.push(...check_attribution_pin(corpus));
+        const found: CorpusFinding[] = [
+            ...check_staleness(corpus, todayStamp),
+            ...check_attribution_pin(corpus),
+        ];
         const csv = check_csv_integrity(corpus);
-        findings.push(...csv.findings);
+        found.push(...csv.findings);
         csvs += csv.opened;
+        findings.push(...found);
+        if (found.length > 0) {
+            ledger.fail(corpus.slug, `${String(found.length)} corpus finding(s)`);
+        } else {
+            ledger.complete(corpus.slug);
+        }
     }
-    return { findings, corpora: corpora.length, csvs };
+    return { findings, corpora: corpora.length, csvs, ledger };
 }
 
 const HELP = `check_corpus_staleness — offline staleness + CSV-integrity gate for the grounding corpora
@@ -651,6 +664,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     // gate-coverage contract (src/config/gate-coverage.yml): corpora inspected.
     process.stdout.write(`scanned: ${String(result.corpora)}\n`);
+    result.ledger.report();
 
     if (result.findings.length > 0) {
         process.stdout.write(`❌  ${String(result.findings.length)} corpus finding(s):\n`);

package/src/scripts/check_detector_corpus.ts

@@ -28,6 +28,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as YAML from 'yaml';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import {
     type DefectFinding,
     type TurnSnapshot,
@@ -163,6 +164,22 @@ export function main(repoRoot: string = process.cwd()): number {
         roots: [CORPUS_REL],
     });
 
+    // Per-detector completeness: every registered detector AND every corpus
+    // entry reaches exactly one outcome, so a detector silently absent from the
+    // loop above could not read as a pass.
+    const ledger = new GateLedger(GATE);
+    const names = [...new Set([...Object.keys(DETECTORS), ...Object.keys(corpus)])].sort();
+    ledger.plan(names);
+    const failing = new Set(findings.map((f) => f.detector));
+    for (const name of names) {
+        if (failing.has(name)) {
+            ledger.fail(name, 'corpus finding(s) against this detector');
+        } else {
+            ledger.complete(name);
+        }
+    }
+    ledger.report();
+
     if (findings.length > 0) {
         process.stderr.write(`${GATE}: ${String(findings.length)} finding(s)\n\n`);
         for (const f of findings) {

package/src/scripts/check_gitignore_freshness.ts

@@ -17,6 +17,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger, LedgerUsageError } from './_lib/gate_ledger.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -108,15 +109,48 @@ function main(argv?: readonly string[]): number {
 
     const missing: string[] = [];
 
-    for (const e of entries) {
-        if (e.policy !== 'ignored') continue;
-        if (e.scope !== 'consumer' && e.scope !== 'both') continue;
-        // Carve-out negations (path starts with !) are separately tracked
-        if (e.path.startsWith('!')) continue;
-        if (!blockLines.has(e.path)) {
-            missing.push(e.path);
+    // Per-entry completeness. Three of the four decisions below used to be bare
+    // `continue`s, so an entry whose `policy`/`scope` line failed to parse read
+    // as "correctly out of scope" and the success line still counted the rest.
+    // Each is now a recorded outcome with a reason, and the count printed below
+    // is the ledger's, not a second independent filter over the same list.
+    const ledger = new GateLedger('check_gitignore_freshness');
+    try {
+        ledger.plan(entries.map((e) => e.path));
+
+        for (const e of entries) {
+            if (e.policy !== 'ignored') {
+                ledger.outOfScope(e.path, 'not_applicable_kind');
+                continue;
+            }
+            if (e.scope !== 'consumer' && e.scope !== 'both') {
+                ledger.outOfScope(e.path, 'not_applicable_kind');
+                continue;
+            }
+            // Carve-out negations (path starts with !) are separately tracked
+            if (e.path.startsWith('!')) {
+                ledger.outOfScope(e.path, 'declared_exemption');
+                continue;
+            }
+            if (!blockLines.has(e.path)) {
+                missing.push(e.path);
+                ledger.fail(e.path, 'absent from gitignore-block.txt');
+            } else {
+                ledger.complete(e.path);
+            }
         }
+    } catch (err) {
+        // A path listed twice in the manifest makes the denominator wrong in the
+        // direction that hides work, so the ledger refuses it. That is a manifest
+        // defect, not a missing gitignore line: exit 2 ("the gate could not run"),
+        // never 1.
+        if (err instanceof LedgerUsageError) {
+            process.stderr.write(`❌  ${path.relative(REPO_ROOT, MANIFEST)}: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
     }
+    const tally = ledger.report();
 
     if (missing.length > 0) {
         process.stdout.write(
@@ -134,7 +168,7 @@ function main(argv?: readonly string[]): number {
 
     if (!quiet) {
         process.stdout.write(
-            `✅  gitignore-block.txt covers all ${entries.filter((e) => e.policy === 'ignored' && (e.scope === 'consumer' || e.scope === 'both')).length} consumer-scoped ignored paths.\n`,
+            `✅  gitignore-block.txt covers all ${tally.completed + tally.failed} consumer-scoped ignored paths.\n`,
         );
     }
     return 0;

package/src/scripts/check_hook_bundle_freshness.ts

@@ -44,6 +44,8 @@ import { fileURLToPath } from "node:url";
 
 import { parse as parseYaml } from "yaml";
 
+// Single-quoted on purpose: check_gate_completeness detects ledger adoption by this exact import form.
+import { GateLedger } from './_lib/gate_ledger.js';
 import { reportScanned } from "./_lib/scan_scope.js";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -135,6 +137,24 @@ export function main(argv: string[] = process.argv.slice(2)): number {
       : {}),
   });
 
+  // Per-source completeness: every bundled source reaches exactly one outcome
+  // (fresh or stale), so a source silently dropped from the mtime sweep could
+  // not read as a pass. Nothing to plan when no self-hosted bundle exists.
+  if (!r.skipped) {
+    const ledger = new GateLedger("check_hook_bundle_freshness");
+    const sources = bundledSources(root);
+    ledger.plan(sources);
+    const staleSet = new Set(r.stale.map((s) => s.file));
+    for (const file of sources) {
+      if (staleSet.has(file)) {
+        ledger.fail(file, "source is newer than the built bundle");
+      } else {
+        ledger.complete(file);
+      }
+    }
+    ledger.report();
+  }
+
   // A gate that scans nothing must SAY it scanned nothing — a silent green
   // here is indistinguishable from a pass.
   if (r.skipped) {

package/src/scripts/check_kernel_prefix_stability.ts

@@ -39,6 +39,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
+// ledger-exempt: single folded-hash comparison — the ordered kernel bodies become ONE sha256 via compute_prefix, byte-compared against the single committed snapshot, so the gate has exactly one aggregate drift verdict and no per-rule outcome exists to record; a changed byte in any body is indistinguishable from a reorder by construction, which IS the invariant. The kernel-count scope floor is already asserted by assertScanned over dist/router.json.
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const ROUTER = path.join(REPO_ROOT, 'dist/router.json');

package/src/scripts/check_standing_rule_delivery.ts

@@ -114,7 +114,7 @@ export function reasonIsStated(reason: string): boolean {
 }
 
 /** One measured layer. */
-interface LayerMeasure {
+export interface LayerMeasure {
     readonly label: string;
     readonly dir: string;
     readonly files: number;
@@ -122,17 +122,66 @@ interface LayerMeasure {
     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);
+function measureFiles(label: string, dir: string, files: ReadonlyMap<string, string>): LayerMeasure {
+    const m = measure([...files.values()].join('\n'));
+    return { label, dir, files: files.size, tokens: m.tokens_gpt, exact: m.tokens_gpt_exact };
+}
+
+/**
+ * The one measurement both the gate (`main` below) and the doctor surface
+ * (`routing_doctor`) consume — per-layer rule tokens, the overlap between the
+ * two layers, and which input the numbers came from. Exported so the doctor
+ * reuses it instead of growing a second, drifting copy.
+ */
+export interface StandingDeliveryMeasure {
+    /** Which input produced the numbers — see `instructionsLoadedRecord`. */
+    readonly input: 'instructions-loaded' | 'filesystem';
+    readonly layers: readonly LayerMeasure[];
+    /** Sum over present layers — what the session receives under the host's no-dedup contract. */
+    readonly received_tokens: number;
+    /** Rules present in BOTH layers (basename match). */
+    readonly overlap_rules: number;
+    readonly duplicate_rules: number;
+    readonly divergent_rules: number;
+    /** Tokens of the project-layer copies of overlapping rules — the doubled delivery. */
+    readonly overlap_tokens: number;
+    readonly exact: boolean;
+}
+
+/** Measure both layers once. `null` when neither directory exists (nothing installed). */
+export function measureStandingDelivery(
+    global_dir: string,
+    project_dir: string,
+    record_path: string,
+): StandingDeliveryMeasure | null {
+    const g = rule_layer_overlap.readRuleLayer(global_dir);
+    const p = rule_layer_overlap.readRuleLayer(project_dir);
+    if (g === null && p === null) return null;
+    const layers: LayerMeasure[] = [];
+    if (g !== null) layers.push(measureFiles('global', global_dir, g.files));
+    if (p !== null) layers.push(measureFiles('project', project_dir, p.files));
+    let overlap_rules = 0;
+    let duplicate_rules = 0;
+    let divergent_rules = 0;
+    let overlap_tokens = 0;
+    if (g !== null && p !== null) {
+        const r = rule_layer_overlap.compareLayers(g.files, p.files);
+        overlap_rules = r.overlap.length;
+        duplicate_rules = r.duplicate.length;
+        divergent_rules = r.divergent.length;
+        if (r.overlap.length > 0) {
+            overlap_tokens = measure(r.overlap.map((n) => p.files.get(n) ?? '').join('\n')).tokens_gpt;
+        }
+    }
     return {
-        label,
-        dir,
-        files: layer.files.size,
-        tokens: m.tokens_gpt,
-        exact: m.tokens_gpt_exact,
+        input: fs.existsSync(record_path) ? 'instructions-loaded' : 'filesystem',
+        layers,
+        received_tokens: layers.reduce((n, l) => n + l.tokens, 0),
+        overlap_rules,
+        duplicate_rules,
+        divergent_rules,
+        overlap_tokens,
+        exact: layers.every((l) => l.exact),
     };
 }
 
@@ -185,10 +234,12 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         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 measured = measureStandingDelivery(
+        path.join(os.homedir(), '.claude', 'rules'),
+        path.join(REPO_ROOT, '.claude', 'rules'),
+        instructionsLoadedRecord(REPO_ROOT),
+    );
+    const layers = measured?.layers ?? [];
 
     const scanned = layers.reduce((n, l) => n + l.files, 0);
     // Two zeroes that mean opposite things, and conflating them is how this gate
@@ -202,7 +253,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     // - **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;
+    const no_layer_present = measured === null;
     try {
         assertScanned({
             gate: PROG,
@@ -239,10 +290,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         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);
+    const { input, received_tokens: total, exact } = measured;
 
     out(`${PROG} · input: ${input} · ${method_note()}\n`);
     if (input === 'filesystem') {
@@ -256,18 +304,11 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         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`,
-                );
-            }
-        }
+    if (measured.overlap_rules > 0) {
+        out(
+            `  overlap  ${String(measured.overlap_rules).padStart(4)} rule(s) in both layers `
+                + `(${measured.duplicate_rules} duplicate, ${measured.divergent_rules} divergent)\n`,
+        );
     }
 
     const pct = total / budget.total_cap_tokens;