@event4u/agent-config 9.29.0 → 9.30.0

package/src/scripts/ask_transport.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Rung-0.5 ask transport — one prompt, one answer, no harness, no session
+ * (road-to-token-economy-dispatch Phase 4.1).
+ *
+ * The judgment ladder's gap this closes: rung 0 routes mechanical slices to
+ * deterministic scripts; rung 1 jumps straight to a full subagent spawn
+ * whose measured median cold start is ~251k tokens (dispatch_floor,
+ * 2026-08-10). A single bounded QUESTION — a classification, a small
+ * verification, a one-file semantic lookup — needs neither a session nor
+ * tools: one completion over the reconciled council transport chain
+ * (cli → api → ∅) answers it at roughly two orders of magnitude below the
+ * spawn floor.
+ *
+ * Hard caps, per the roadmap's anti-loop discipline (Risk 2 — "rung 0.5
+ * becomes a hidden agent loop"):
+ *   - ONE completion. No retry beyond the transport chain's own cli→api
+ *     fallback semantics inside the client.
+ *   - NO tool use, NO session, NO follow-up turn.
+ *   - Honest ∅: council disabled / no member / transport failure → null
+ *     (CLI exit 3), never a fabricated answer and never an escalation this
+ *     module performs itself. Escalating to a spawn is the CALLER's
+ *     decision and is recorded as such (`escalated` on the caller's line).
+ *
+ * Telemetry: every completed ask appends ONE orchestration_record line
+ * (route_taken: "ask", spawn_count: 0, dispatch_tokens measured from the
+ * provider response) — the substitution/adoption metrics registered in
+ * `src/config/dispatch-economy-metrics.json` read these lines.
+ *
+ * Reuses, never re-implements: `council_cli.load_settings` +
+ * `build_members` (member construction, auth, transport resolution,
+ * cli-first billing classification — all unchanged), `CouncilResponse`
+ * accounting, `_lib/orchestration_record` validation.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/ask_transport "is X true in file Y?" \
+ *     [--system "<system prompt>"] [--member <name>] [--format text|json] \
+ *     [--no-record] [--dir <audit-dir>]
+ *
+ * Exit codes: 0 answer produced · 2 usage error · 3 honest-∅ (no transport).
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import type { ExternalAIClient } from './ai_council/clients.js';
+import { buildOrchestrationLine } from './_lib/orchestration_record.js';
+import { DEFAULT_DIR } from './orchestration_record.js';
+
+export interface AskResult {
+    answer: string;
+    member: string;
+    model: string;
+    input_tokens: number;
+    output_tokens: number;
+    latency_ms: number;
+}
+
+export interface AskOptions {
+    /** Injected members (tests). Default: council_cli.load_settings + build_members. */
+    members?: ExternalAIClient[];
+    /** Pick a specific member by provider/name; default: first configured. */
+    member?: string;
+    systemPrompt?: string;
+    /** Telemetry append target; null disables recording (tests / --no-record). */
+    auditDir?: string | null;
+    /** Injected clock/id (tests). */
+    now?: () => Date;
+    id?: () => string;
+}
+
+const DEFAULT_SYSTEM =
+    'You are a single-completion answer service. Answer the question directly, ' +
+    'concisely, and honestly. If the question cannot be answered without tools, ' +
+    'files, or more context, reply exactly: INSUFFICIENT_CONTEXT — one line on ' +
+    'what is missing. Never invent facts.';
+
+/** Lazily import the council CLI surface so tests with injected members never load it. */
+async function defaultMembers(): Promise<ExternalAIClient[]> {
+    const mod = await import('./council_cli.js');
+    const settings = mod.load_settings();
+    return mod.build_members(settings);
+}
+
+function recordAskLine(auditDir: string, result: AskResult | null, member: string, ts: string, id: string): void {
+    const { line, errors } = buildOrchestrationLine({
+        spawn_count: 0,
+        token_delta: 0,
+        token_delta_provenance: 'estimated',
+        route_taken: 'ask',
+        verify_mode: 'none',
+        dispatch_outcome: result === null ? 'BLOCKED' : 'DONE',
+        dispatch_tokens: result === null ? null : result.input_tokens + result.output_tokens,
+        wall_clock_ms: result === null ? 0 : Math.max(0, Math.round(result.latency_ms)),
+        agent_combo: [member || 'none'],
+        origin: 'dispatch-economy-2026',
+        ts,
+        id,
+    });
+    if (errors.length || line === null) return; // telemetry must never fail the ask
+    try {
+        const file = path.join(auditDir, `${ts.slice(0, 7)}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
+    } catch {
+        /* fail-open — accounting never blocks the answer */
+    }
+}
+
+/**
+ * One bounded ask. Returns the answer or `null` (honest ∅ — council
+ * disabled, no member resolves, transport failure, or provider error).
+ */
+export async function askOnce(prompt: string, opts: AskOptions = {}): Promise<AskResult | null> {
+    const trimmed = prompt.trim();
+    if (!trimmed) return null;
+
+    let members: ExternalAIClient[];
+    try {
+        members = opts.members ?? (await defaultMembers());
+    } catch {
+        return _finish(null, 'none', opts); // disabled / unreadable config → ∅
+    }
+    const memberName = (m: ExternalAIClient): string => {
+        const c = m as { name?: string; provider?: string };
+        return c.name || c.provider || 'unknown';
+    };
+    const pick =
+        opts.member !== undefined ? members.find((m) => memberName(m) === opts.member) : members[0];
+    if (pick === undefined) {
+        return _finish(null, opts.member ?? 'none', opts);
+    }
+    const provider = memberName(pick);
+
+    try {
+        const response = pick.ask(opts.systemPrompt ?? DEFAULT_SYSTEM, trimmed);
+        const r = response instanceof Promise ? await response : response;
+        if (r === null || r === undefined || (r.error !== null && r.error !== undefined && r.error !== '')) {
+            return _finish(null, provider, opts);
+        }
+        const text = (r.text ?? '').trim();
+        if (!text) return _finish(null, provider, opts);
+        return _finish(
+            {
+                answer: text,
+                member: provider,
+                model: r.model ?? 'unknown',
+                input_tokens: r.input_tokens ?? 0,
+                output_tokens: r.output_tokens ?? 0,
+                latency_ms: r.latency_ms ?? 0,
+            },
+            provider,
+            opts,
+        );
+    } catch {
+        return _finish(null, provider, opts); // ONE completion — no retry here
+    }
+}
+
+function _finish(result: AskResult | null, member: string, opts: AskOptions): AskResult | null {
+    const auditDir = opts.auditDir === undefined ? path.join(process.cwd(), DEFAULT_DIR) : opts.auditDir;
+    if (auditDir !== null) {
+        const ts = (opts.now ? opts.now() : new Date()).toISOString();
+        const id = opts.id ? opts.id() : crypto.randomUUID();
+        recordAskLine(auditDir, result, member, ts, id);
+    }
+    return result;
+}
+
+export async function main(argv: readonly string[]): Promise<number> {
+    let prompt = '';
+    let system: string | undefined;
+    let member: string | undefined;
+    let format: 'text' | 'json' = 'text';
+    let record = true;
+    let dir: string | undefined;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? '';
+        if (a === '--system') system = argv[++i];
+        else if (a === '--member') member = argv[++i];
+        else if (a === '--format') format = argv[++i] === 'json' ? 'json' : 'text';
+        else if (a === '--no-record') record = false;
+        else if (a === '--dir') dir = argv[++i];
+        else if (!a.startsWith('--')) prompt = prompt ? `${prompt} ${a}` : a;
+    }
+    if (!prompt.trim()) {
+        process.stderr.write('ask_transport: a question argument is required\n');
+        return 2;
+    }
+    const opts: AskOptions = {
+        ...(system !== undefined ? { systemPrompt: system } : {}),
+        ...(member !== undefined ? { member } : {}),
+        auditDir: record ? (dir ?? path.join(process.cwd(), DEFAULT_DIR)) : null,
+    };
+    const result = await askOnce(prompt, opts);
+    if (result === null) {
+        process.stderr.write('ask_transport: ∅ — no transport resolved or the single completion failed (no retry by design)\n');
+        return 3;
+    }
+    process.stdout.write(
+        format === 'json' ? JSON.stringify(result, null, 2) + '\n' : result.answer + '\n',
+    );
+    return 0;
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) {
+    main(process.argv.slice(2)).then((rc) => process.exit(rc));
+}

package/src/scripts/bench_hook_injection.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * Hook-injection byte bench + CI gate (road-to-token-economy-cache Phase 3.2)
+ * — the latency harness's twin for the INJECTION side.
+ *
+ * Runs every concern bound on the `claude` platform against the committed
+ * fixture envelope of each slot it is bound to (tests/fixtures/hooks/
+ * <event>.json), in-process via CONCERN_REGISTRY with the hook-stdin
+ * override, under AGENT_CONFIG_REPLAY=1 (state writes skipped). Measures the
+ * bytes of the stdout payload fields a concern injects — `reason` +
+ * `additional_context` + `context` — and gates them against
+ * `src/config/hook-token-budget.json`:
+ *
+ *   - a concern whose emission exceeds its row (or the default cap) → RED
+ *   - an EMITTING concern with no explicit row above the default is fine;
+ *     the default cap IS its row — but a breach names the missing row so
+ *     the fix is a registered decision, not a silent default bump
+ *   - per-slot SUM over all bound concerns > the slot cap → RED
+ *
+ * HONEST SCOPE, stated up front: concerns are conditional-silence by design —
+ * a generic fixture triggers few of them, so most measure 0 bytes here. The
+ * gate therefore enforces the cap on whatever DOES fire under the committed
+ * fixtures (deterministic, CI-reproducible), while the census mode
+ * (`--record`) measures REAL sessions: it appends counts-only lines
+ * ({ts, slot, concern, bytes}) to agents/runtime/state/injection-census.jsonl
+ * — the repeat-injection-census blocker's instrument. Claiming the fixture
+ * numbers are the live distribution would be the coverage inflation this
+ * repo's gate discipline refuses; the two modes exist because neither
+ * substitutes for the other.
+ *
+ * Class A: in-process, no daemon, no network. Exit 0 green · 1 breach ·
+ * 2 unusable invocation. Dead-scope guarded: zero concerns run = RED.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/bench_hook_injection [--format text|json]
+ *     [--record] [--platform claude]
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { CONCERN_REGISTRY } from './hooks/concern_registry.js';
+import { setHookStdinOverride, clearHookStdinOverride } from './hooks/hook_stdin.js';
+import { _load_yaml, _resolve_concerns, EVENT_VOCABULARY, type JsonObject } from './hooks/dispatch_hook.js';
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _IN_BUNDLE = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+const REPO_ROOT = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    ...(_IN_BUNDLE ? ['..'] : ['..', '..']),
+);
+const MANIFEST = path.join(REPO_ROOT, 'src', 'scripts', 'hook_manifest.yaml');
+const BUDGET = path.join(REPO_ROOT, 'src', 'config', 'hook-token-budget.json');
+const FIXTURES = path.join(REPO_ROOT, 'tests', 'fixtures', 'hooks');
+const CENSUS_FILE = path.join('agents', 'runtime', 'state', 'injection-census.jsonl');
+
+export interface Measurement {
+    slot: string;
+    concern: string;
+    bytes: number;
+    cap: number;
+    breach: boolean;
+}
+
+interface Budget {
+    default_cap_bytes: number;
+    per_concern_caps_bytes: Record<string, number | string>;
+    per_slot_sum_caps_bytes: Record<string, number | string>;
+}
+
+function capFor(budget: Budget, concern: string): number {
+    const v = budget.per_concern_caps_bytes[concern];
+    return typeof v === 'number' ? v : budget.default_cap_bytes;
+}
+
+/** Run one registered concern in-process with the fixture envelope; return payload bytes. */
+export function runConcernOnce(
+    script: string,
+    args: readonly string[],
+    envelope: JsonObject,
+): number {
+    const main = CONCERN_REGISTRY[script];
+    if (main === undefined) return -1; // not in registry — parity tests own that failure
+    let out = '';
+    const prevWrite = process.stdout.write;
+    const prevErr = process.stderr.write;
+    const prevArgv = process.argv;
+    const prevReplay = process.env['AGENT_CONFIG_REPLAY'];
+    setHookStdinOverride(JSON.stringify(envelope));
+    process.env['AGENT_CONFIG_REPLAY'] = '1';
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stdout.write = ((chunk: any, enc?: any, cb?: any): boolean => {
+        out += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8');
+        const callback = typeof enc === 'function' ? enc : cb;
+        if (typeof callback === 'function') callback();
+        return true;
+    }) as typeof process.stdout.write;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stderr.write = ((chunk: any, enc?: any, cb?: any): boolean => {
+        const callback = typeof enc === 'function' ? enc : cb;
+        if (typeof callback === 'function') callback();
+        return true;
+    }) as typeof process.stderr.write;
+    try {
+        process.argv = [prevArgv[0] as string, script, ...args, '--platform', 'claude'];
+        main([...args, '--platform', 'claude']);
+    } catch {
+        /* a crashing concern injects nothing — latency/parity suites own crashes */
+    } finally {
+        process.stdout.write = prevWrite;
+        process.stderr.write = prevErr;
+        process.argv = prevArgv;
+        if (prevReplay === undefined) delete process.env['AGENT_CONFIG_REPLAY'];
+        else process.env['AGENT_CONFIG_REPLAY'] = prevReplay;
+        clearHookStdinOverride();
+    }
+    const text = out.trim();
+    if (!text) return 0;
+    try {
+        const parsed = JSON.parse(text) as Record<string, unknown>;
+        let bytes = 0;
+        for (const key of ['reason', 'additional_context', 'context']) {
+            const v = parsed[key];
+            if (typeof v === 'string') bytes += Buffer.byteLength(v, 'utf-8');
+        }
+        return bytes;
+    } catch {
+        return Buffer.byteLength(text, 'utf-8'); // non-JSON stdout counts whole
+    }
+}
+
+export function bench(opts: { platform?: string; budgetPath?: string } = {}): { measurements: Measurement[]; slotSums: Record<string, { bytes: number; cap: number; breach: boolean }>; errors: string[] } {
+    const platform = opts.platform ?? 'claude';
+    const manifest = _load_yaml(MANIFEST);
+    const budget = JSON.parse(fs.readFileSync(opts.budgetPath ?? BUDGET, 'utf8')) as Budget;
+    const measurements: Measurement[] = [];
+    const slotSums: Record<string, { bytes: number; cap: number; breach: boolean }> = {};
+    const errors: string[] = [];
+
+    for (const event of EVENT_VOCABULARY) {
+        const fixtureFile = path.join(FIXTURES, `${event}.json`);
+        if (!fs.existsSync(fixtureFile)) continue;
+        const envelope = JSON.parse(fs.readFileSync(fixtureFile, 'utf8')) as JsonObject;
+        const concerns = _resolve_concerns(manifest, platform, event);
+        let sum = 0;
+        for (const concern of concerns) {
+            const bytes = runConcernOnce(String(concern['script']), Array.isArray(concern['args']) ? concern['args'].map(String) : [], envelope);
+            if (bytes < 0) {
+                errors.push(`${event}/${String(concern['name'])}: not in CONCERN_REGISTRY`);
+                continue;
+            }
+            const cap = capFor(budget, String(concern['name']));
+            const breach = bytes > cap;
+            measurements.push({ slot: event, concern: String(concern['name']), bytes, cap, breach });
+            sum += bytes;
+        }
+        const slotCapRaw = budget.per_slot_sum_caps_bytes[event];
+        const slotCap = typeof slotCapRaw === 'number' ? slotCapRaw : Number.MAX_SAFE_INTEGER;
+        slotSums[event] = { bytes: sum, cap: slotCap, breach: sum > slotCap };
+    }
+    return { measurements, slotSums, errors };
+}
+
+export function main(argv: readonly string[]): number {
+    let format: 'text' | 'json' = 'text';
+    let record = false;
+    let platform = 'claude';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--format') format = argv[++i] === 'json' ? 'json' : 'text';
+        else if (a === '--record') record = true;
+        else if (a === '--platform') platform = argv[++i] ?? platform;
+    }
+    let result: ReturnType<typeof bench>;
+    try {
+        result = bench({ platform });
+    } catch (err) {
+        process.stderr.write(`bench_hook_injection: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+    }
+    // Dead-scope guard: a bench that ran zero concerns proves nothing (a
+    // gate that scans nothing exits green is the recorded failure class).
+    if (result.measurements.length === 0) {
+        process.stderr.write('bench_hook_injection: DEAD SCOPE — zero concerns ran; fixtures or manifest unreadable\n');
+        return 1;
+    }
+    if (record) {
+        try {
+            const file = path.join(process.cwd(), CENSUS_FILE);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            const ts = new Date().toISOString();
+            for (const m of result.measurements) {
+                if (m.bytes > 0) {
+                    fs.appendFileSync(file, JSON.stringify({ ts, slot: m.slot, concern: m.concern, bytes: m.bytes }) + '\n');
+                }
+            }
+        } catch {
+            /* census is observability — never fails the bench */
+        }
+    }
+    const breaches = result.measurements.filter((m) => m.breach);
+    const slotBreaches = Object.entries(result.slotSums).filter(([, s]) => s.breach);
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    } else {
+        const emitting = result.measurements.filter((m) => m.bytes > 0);
+        process.stdout.write(`bench_hook_injection: ${result.measurements.length} concern-slot pairs · ${emitting.length} emitted under the committed fixtures\n`);
+        for (const m of emitting) {
+            process.stdout.write(`  ${m.slot.padEnd(20)} ${m.concern.padEnd(24)} ${String(m.bytes).padStart(6)} B (cap ${m.cap})${m.breach ? '  ❌ BREACH' : ''}\n`);
+        }
+        for (const [slot, s] of Object.entries(result.slotSums)) {
+            if (s.bytes > 0) process.stdout.write(`  slot-sum ${slot.padEnd(20)} ${String(s.bytes).padStart(6)} B (cap ${s.cap === Number.MAX_SAFE_INTEGER ? '—' : s.cap})${s.breach ? '  ❌ BREACH' : ''}\n`);
+        }
+        for (const e of result.errors) process.stdout.write(`  warn: ${e}\n`);
+    }
+    if (breaches.length > 0 || slotBreaches.length > 0) {
+        process.stderr.write(`bench_hook_injection: ${breaches.length} concern breach(es), ${slotBreaches.length} slot-sum breach(es) — the budget row is the decision surface (src/config/hook-token-budget.json)\n`);
+        return 1;
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (_IN_BUNDLE) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main(process.argv.slice(2)));

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;