@event4u/agent-config 9.17.0 → 9.18.1

package/src/config/agent-settings.template.yml

@@ -550,6 +550,52 @@ roadmap:
   # only if your team genuinely commits work on a calendar plate.
   horizon_weeks: 0
 
+# --- Plan governance gates ---
+#
+# Three governance gates around the plan/delivery workflow (contract:
+# docs/contracts/plan-review-gates.md). Scope is every plan artifact —
+# roadmaps AND feature plans — which is why these keys do not live under
+# `roadmap:`. All three default to true; a missing key behaves as true.
+planning:
+  # Gate C — plan-confidence gate, BEFORE authoring (true, false).
+  # true  = default. A plan-artifact authoring ask (/roadmap:create,
+  #         roadmap-writing, /feature:plan, /feature:roadmap) first runs
+  #         the four 95%-confidence conditions from /challenge-me vision.
+  #         All four hold → the agent creates directly and emits exactly
+  #         one marker line ("Confidence ≥ 95% — creating directly").
+  #         Any gap → the ask routes into the /challenge-me vision
+  #         interview first; hosts without that command run the inline
+  #         degrade interview (one question per turn, same stop
+  #         conditions — contexts/execution/plan-confidence-gate.md).
+  #         An explicit user bypass ("just write it") wins for that turn
+  #         and is counted (gate_c_bypass_rate).
+  # false = inert; plan asks author directly (today's behavior).
+  challenge_on_create: true
+
+  # Gate R1 — plan-risk review at plan creation / substantial change
+  # (true, false).
+  # true  = default. Every ready (non-draft) plan carries a schema-valid
+  #         `## Risk Register` section (ranked risks, mitigation +
+  #         in-document anchor per row, freshness marker). Enforced by
+  #         lint_plan_risk_register at pre-push + CI; drafts are exempt
+  #         until flipped to ready. Honest-null: an empty register is
+  #         valid only with the exact marker grammar from the contract.
+  # false = escape hatch; the validator skips (governance default is on).
+  risk_review: true
+
+  # Gate R2 — completion review at 100% roadmap completion / pre-PR
+  # (true, false).
+  # true  = default. A findings-BEFORE-fixes review by a fresh reviewer
+  #         context: the findings artifact (agents/evidence/reviews/…) must exist
+  #         for the current diff hash before the first fix commit; every
+  #         finding ends fixed | accepted-risk | deferred. No code
+  #         surface → explicit skip declaration, never a silent skip.
+  #         Enforced by check_completion_review at pre-push + CI (CI
+  #         authoritative); a crashed validator (exit 2) warns and
+  #         allows — a broken gate never blocks its own fix.
+  # false = escape hatch; the validator skips (governance default is on).
+  completion_review: true
+
 # --- Quality / CI execution ---
 #
 # Controls whether the agent runs the project's quality pipeline

package/src/config/evaluator-budgets.json

@@ -58,11 +58,11 @@
             "deterministic": false
         },
         "cli_help_command_count": {
-            "max": 82,
-            "last_measured": 82,
+            "max": 84,
+            "last_measured": 84,
             "last_measured_at": "2026-08-04",
             "method": "registry enumeration — count of `{ name: '...', disposition` entries in src/cli/registry.ts (NOT --help prose parsing; methods historically disagreed 74 vs 76 vs 79)",
-            "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82."
+            "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82. 82 → 84 on 2026-08-04: the `route:explain` + `route:audit` verbs (routing-correctness validation surface) register in the same PR that adds the surface. Re-measured via the pinned method: 84."
         },
         "mcp_public_tool_count": {
             "max": 19,

package/src/config/gate-coverage.yml

@@ -84,6 +84,12 @@
 # contract is `dist == rewrite(src)`; `check_ci_local_parity`, whose corpus is
 # workflow files) carries no recipe and is reported UNPROVEN, never green.
 gates:
+  - id: lint_trigger_collisions
+    argv: []
+    min_scanned: 90
+    corpus: "src/rules/*.md frontmatters (111 at baseline)"
+    status: enforced
+
   - id: check_condensation
     argv: []
     min_scanned: 380
@@ -302,3 +308,41 @@ gates:
       count. Its inventory-file exemption was also dead: it compared against
       the retired root AND against 'dist/agent-src' as a single path segment,
       which a '/'-split can never yield.
+
+  - id: lint_plan_risk_register
+    argv: []
+    min_scanned: 12
+    corpus: "ready roadmap files under agents/roadmaps/ top level (19 at baseline: 14 grandfathered + 4 draft-exempt + 1 carrying a live register)"
+    status: enforced
+    note: >
+      Gate R1 (docs/contracts/plan-review-gates.md § 1). The count is READY
+      FILES INSPECTED incl. grandfathered/draft-exempt ones — exemptions are
+      reported, never silently skipped, so a collapse below the floor means
+      the roadmaps root moved, not that the corpus went clean.
+
+  - id: check_completion_review
+    argv: ["--advisory", "--base", "origin/main"]
+    min_scanned: 1
+    corpus: "findings artefacts under agents/evidence/reviews/ + the current-diff evaluation (1 at baseline — the evaluation itself; artefact count grows with gated PRs)"
+    status: enforced
+    note: >
+      Gate R2 (docs/contracts/plan-review-gates.md § 2). HONEST LIMIT, stated
+      because a floor that cannot fail is exactly the false green this file
+      exists to prevent: scanned = artefacts inspected + 1 for the diff
+      evaluation, so on any run that REACHES the count `min_scanned: 1` cannot
+      trip. It is not unreachable in principle — a moved reviews root exits
+      before the inventory and reports `scanned: 0`, which the guard does read —
+      but that path is the dead-scope violation below, so the floor never adds
+      anything the assertion does not already catch.
+      NOTHING TRIPS AT ALL DURING THE ADVISORY WINDOW. The argv above
+      mirrors the CI invocation, and under `--advisory` every violation kind —
+      dead-scan-scope included — is printed as a warning and the exit code is 0.
+      So for the duration of the Stage-A window this entry proves only that the
+      gate RAN: it has no blocking path and no trippable floor. The blocking
+      behaviour is real but dormant — the dead-scan-scope assertion is a policy
+      violation, exit 1 (contract § 6 carve-out: a gate that read nothing has not
+      passed), which is what makes a moved reviews root fail loudly instead of
+      reporting a clean scope. It takes effect when Stage B drops `--advisory`
+      from the CI invocation; nothing else changes at that switch. The entry
+      stays registered so the guard reports this gate rather than skipping it
+      silently.

package/src/scripts/_cli/cmd_explain.ts

@@ -61,6 +61,8 @@ import {
     load_agent_settings,
     resolve_project_root,
 } from '../_lib/agent_settings.js';
+import { trigger_matches } from '../_lib/router_match.js';
+import type { Trigger } from '../_lib/router_match.js';
 import * as presets from '../config/presets.js';
 import * as profiles from '../config/profiles.js';
 import { build_trace } from './explain_last/index.js';
@@ -410,52 +412,51 @@ function pyReprAny(value: unknown): string {
     return String(value);
 }
 
-function _matches_trigger(trigger: Dict, text: string, lowered: string): string | null {
-    if ('keyword' in trigger) {
-        const kw = String(trigger['keyword']).toLowerCase();
-        if (kw && lowered.includes(kw)) {
-            return `keyword: ${kw}`;
+/** `kind: value` label for a trigger's single match key. */
+function _trigger_reason(trigger: Dict): string {
+    for (const kind of ['keyword', 'phrase', 'command', 'path_prefix', 'file_pattern']) {
+        if (kind in trigger) {
+            return `${kind}: ${String(trigger[kind])}`;
         }
     }
-    if ('phrase' in trigger) {
-        const ph = String(trigger['phrase']).toLowerCase();
-        if (ph && lowered.includes(ph)) {
-            return `phrase: ${ph}`;
-        }
-    }
-    if ('path_prefix' in trigger) {
-        const prefix = String(trigger['path_prefix']);
-        if (prefix && text.includes(prefix)) {
-            return `path_prefix: ${prefix}`;
-        }
-    }
-    return null;
+    return `trigger: ${JSON.stringify(trigger)}`;
 }
 
 function _explain_route(project_root: string, text: string, as_json: boolean): number {
     const router = _load_router(project_root);
-    const lowered = text.toLowerCase();
-    const matches: Dict[] = [];
-    const tier_1 = (router['tier_1'] as Dict[] | undefined) || [];
-    for (const entry of tier_1) {
-        const triggers = (entry['triggers'] as Dict[] | undefined) || [];
-        for (const trig of triggers) {
-            const reason = _matches_trigger(trig, text, lowered);
-            if (reason !== null) {
-                matches.push({ id: entry['id'], tier: 'tier_1', reason });
-                break;
+    // Matching goes through the SHARED matcher (_lib/router_match) — anchored
+    // keyword semantics, both tiers. This surface carries no open-files /
+    // command context, so path_prefix / file_pattern / command triggers
+    // cannot match here (previously path_prefix was probed against the
+    // prompt TEXT — a divergent second matcher, removed on purpose).
+    const tier_1_matches: Dict[] = [];
+    const tier_2_matches: Dict[] = [];
+    for (const [tier, sink] of [
+        ['tier_1', tier_1_matches],
+        ['tier_2', tier_2_matches],
+    ] as Array<[string, Dict[]]>) {
+        const rules = (router[tier] as Dict[] | undefined) || [];
+        for (const entry of rules) {
+            const triggers = (entry['triggers'] as Dict[] | undefined) || [];
+            for (const trig of triggers) {
+                if (trigger_matches(trig as Trigger, text, null, null)) {
+                    sink.push({ id: entry['id'], tier, reason: _trigger_reason(trig) });
+                    break;
+                }
             }
         }
     }
+    const total = tier_1_matches.length + tier_2_matches.length;
     const kernel_always = [...((router['kernel'] as unknown[] | undefined) || [])];
     const payload: Dict = {
         input: text,
         kernel_always,
-        tier_1_matches: matches,
+        tier_1_matches,
+        tier_2_matches,
     };
     if (as_json) {
         _dumpJson(payload);
-        return 0;
+        return total === 0 ? 1 : 0;
     }
     print(`  input: ${pyReprStr(text)}`);
     print();
@@ -464,14 +465,19 @@ function _explain_route(project_root: string, text: string, as_json: boolean): n
         print(`    · ${pyStr(kid)}`);
     }
     print();
-    print(`  tier-1 matches (${matches.length}):`);
-    if (matches.length === 0) {
-        print('    · (no trigger matched — only kernel rules active)');
-        return 1;
+    print(`  tier-1 matches (${tier_1_matches.length}):`);
+    for (const match of tier_1_matches) {
+        print(`    · ${match['id']}  (${match['reason']})`);
     }
-    for (const match of matches) {
+    print();
+    print(`  tier-2 matches (${tier_2_matches.length}):`);
+    for (const match of tier_2_matches) {
         print(`    · ${match['id']}  (${match['reason']})`);
     }
+    if (total === 0) {
+        print('    · (no trigger matched — only kernel rules active)');
+        return 1;
+    }
     return 0;
 }
 
@@ -757,7 +763,6 @@ export {
     _explain_config,
     _find_rule,
     _explain_rule,
-    _matches_trigger,
     _explain_route,
     _explain_last,
     _LAST_HELP,

package/src/scripts/_cli/cmd_route_audit.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config route:audit [--last N] [--record] [--weekly] [--json]` —
+ * replay the shared router matcher over the last N USER prompts of the
+ * repo-local chat-history log and render matched-vs-unmatched per prompt.
+ * Read-only over the inputs; no LLM call; deterministic.
+ *
+ * Measurement level (ADR-126): trigger matching only — what the host actually
+ * invoked on those turns is NOT measured here. "Should-have-matched" is the
+ * human reviewer's judgment over this table, not a computed verdict.
+ *
+ * `--record` appends one JSONL record per audited prompt to the opt-in
+ * routing recorder (`telemetry.routing_recorder.enabled`, default OFF —
+ * disabled means zero file IO and a silent exit contribution). The record is
+ * PII-excluded by construction: it carries a truncated sha256 of the prompt,
+ * never the prompt text, plus matched rule ids / trigger labels and an
+ * enforcement join against `agents/runtime/state/rule-trips.json` where a
+ * same-named hook concern exists. Delete-and-rerun rebuilds it from chat
+ * history — losing it changes no answer (state-store test, ADR-124 § 6).
+ *
+ * `--weekly` renders the rolling last-7-days picture from the recorder log.
+ * Resolver authority note: this instrument is corpus-growth raw material for
+ * `internal/bench/layer1-resolver-PREREG.md` (its P2 condition) as a side
+ * effect only — the PREREG stays the sole authority over any resolver
+ * revival; nothing here builds or scores a resolver.
+ *
+ * Exit codes: 0 rendered (even when the recorder is disabled), 1 no prompts /
+ * no records to audit, 2 invocation or IO error.
+ */
+
+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 { match_prompt, type Router } from '../_lib/router_match.js';
+import { load_agent_settings } from '../_lib/agent_settings.js';
+import { read_entries } from '../chat_history.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const ROUTER_JSON = path.join(REPO_ROOT, 'dist', 'router.json');
+
+// cache-version: v1 — rebuildable audit log: delete-and-rerun rebuilds it from
+// chat history (`route:audit --record`); losing it changes no answer.
+export const RECORDER_REL = 'agents/runtime/state/routing-telemetry.jsonl';
+const RULE_TRIPS_REL = 'agents/runtime/state/rule-trips.json';
+export const RECORD_SCHEMA_VERSION = 1;
+
+export const MEASUREMENT_HEADER =
+    'Measurement level: trigger matching only — what the host actually invokes is NOT measured here (ADR-126).';
+export const PREREG_AUTHORITY_LINE =
+    'Resolver authority: internal/bench/layer1-resolver-PREREG.md — this corpus feeds its P2 condition as a side effect; nothing here revives a resolver.';
+
+function recorder_path(): string {
+    return process.env['AGENT_ROUTING_TELEMETRY_FILE'] ?? path.join(REPO_ROOT, RECORDER_REL);
+}
+
+export function recorder_enabled(): boolean {
+    try {
+        const settings = load_agent_settings({ cwd: REPO_ROOT }) as Record<string, unknown>;
+        const t = settings['telemetry'];
+        if (t === null || typeof t !== 'object' || Array.isArray(t)) return false;
+        const rr = (t as Record<string, unknown>)['routing_recorder'];
+        if (rr === null || typeof rr !== 'object' || Array.isArray(rr)) return false;
+        const enabled = (rr as Record<string, unknown>)['enabled'];
+        return enabled === true || enabled === 'true' || enabled === 'on' || enabled === 'yes';
+    } catch {
+        return false; // unparseable means disabled — default-off doctrine
+    }
+}
+
+interface AuditedPrompt {
+    prompt: string;
+    matched: { rule: string; tier: string; triggers: string[] }[];
+}
+
+function _trigger_label(trigger: Record<string, unknown>): string {
+    for (const kind of ['keyword', 'phrase', 'command', 'path_prefix', 'file_pattern']) {
+        if (kind in trigger) return `${kind}: ${String(trigger[kind])}`;
+    }
+    return JSON.stringify(trigger);
+}
+
+export function audit_prompts(router: Router, prompts: string[]): AuditedPrompt[] {
+    return prompts.map((prompt) => {
+        const result = match_prompt(router, prompt, 'full', null, null);
+        const byRule = new Map<string, { tier: string; triggers: string[] }>();
+        for (const mt of result.matched_triggers) {
+            const id = String(mt.rule);
+            const entry = byRule.get(id) ?? { tier: mt.tier.replace('_', '-'), triggers: [] };
+            entry.triggers.push(_trigger_label(mt.trigger as Record<string, unknown>));
+            byRule.set(id, entry);
+        }
+        const matched = [...byRule.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([rule, v]) => ({ rule, tier: v.tier, triggers: v.triggers }));
+        return { prompt, matched };
+    });
+}
+
+/** Last N user prompts from the repo chat-history log, oldest first. */
+export function load_user_prompts(last: number, history_path?: string | null): string[] {
+    let entries: Array<{ t?: unknown; text?: unknown }> = [];
+    try {
+        entries = read_entries({ path: history_path ?? null }) as Array<{ t?: unknown; text?: unknown }>;
+    } catch {
+        return [];
+    }
+    const prompts: string[] = [];
+    for (const e of entries) {
+        if (e === null || typeof e !== 'object') continue;
+        if (e.t !== 'user' || typeof e.text !== 'string') continue;
+        const text = e.text.trim();
+        // Host-injected meta turns are not user prompts (same filter as the
+        // handoff session reader).
+        if (text === '' || text.startsWith('<') || text.startsWith('Caveat:')) continue;
+        prompts.push(text);
+    }
+    return prompts.slice(-last);
+}
+
+interface TripsDoc {
+    concerns?: Record<string, { block?: number; warn?: number }>;
+}
+
+function _load_trips(): TripsDoc {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, RULE_TRIPS_REL), 'utf-8')) as TripsDoc;
+    } catch {
+        return {};
+    }
+}
+
+export function build_records(audits: AuditedPrompt[], now_iso: string): Record<string, unknown>[] {
+    const trips = _load_trips();
+    return audits.map((a) => {
+        const enforcement_trips: Record<string, { block: number; warn: number }> = {};
+        for (const m of a.matched) {
+            const concern = trips.concerns?.[m.rule];
+            if (concern) {
+                enforcement_trips[m.rule] = { block: concern.block ?? 0, warn: concern.warn ?? 0 };
+            }
+        }
+        // PII-exclusion-by-construction: no free-form prompt field exists in
+        // this record type — only a truncated digest and closed-shape labels.
+        return {
+            schema_version: RECORD_SCHEMA_VERSION,
+            ts: now_iso,
+            prompt_sha16: crypto.createHash('sha256').update(a.prompt).digest('hex').slice(0, 16),
+            matched: a.matched,
+            enforcement_trips,
+        };
+    });
+}
+
+export function append_records(records: Record<string, unknown>[], target: string): number {
+    if (process.env['AGENT_CONFIG_REPLAY'] === '1') return 0; // replay mode: no state writes
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const fd = fs.openSync(target, 'a', 0o644);
+    try {
+        for (const r of records) fs.writeSync(fd, JSON.stringify(r) + '\n');
+        fs.fsyncSync(fd);
+    } finally {
+        fs.closeSync(fd);
+    }
+    return records.length;
+}
+
+export function render_weekly(target: string, now: Date): { text: string; records: number } {
+    let lines: string[] = [];
+    try {
+        lines = fs.readFileSync(target, 'utf-8').split('\n').filter(Boolean);
+    } catch {
+        lines = [];
+    }
+    const cutoff = now.getTime() - 7 * 24 * 60 * 60 * 1000;
+    const perRule = new Map<string, number>();
+    let inWindow = 0;
+    for (const line of lines) {
+        let rec: { ts?: string; matched?: { rule: string }[] };
+        try {
+            rec = JSON.parse(line) as typeof rec;
+        } catch {
+            continue;
+        }
+        const ts = Date.parse(rec.ts ?? '');
+        if (Number.isNaN(ts) || ts < cutoff) continue;
+        inWindow += 1;
+        for (const m of rec.matched ?? []) {
+            perRule.set(m.rule, (perRule.get(m.rule) ?? 0) + 1);
+        }
+    }
+    const out: string[] = [MEASUREMENT_HEADER, ''];
+    out.push(`routing recorder — rolling 7-day window (${inWindow} recorded prompt(s))`);
+    if (inWindow === 0) {
+        out.push('  (no records in the window — enable telemetry.routing_recorder and run `route:audit --record`)');
+    } else {
+        const rows = [...perRule.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+        for (const [rule, n] of rows) out.push(`  ${String(n).padStart(4)} × ${rule}`);
+    }
+    out.push('');
+    out.push(PREREG_AUTHORITY_LINE);
+    return { text: out.join('\n') + '\n', records: inWindow };
+}
+
+export function main(argv: string[]): number {
+    const args = [...argv];
+    const as_json = args.includes('--json');
+    const weekly = args.includes('--weekly');
+    const record = args.includes('--record');
+    let last = 10;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] as string;
+        if (a === '--last') last = Number(args[++i] ?? '10') || 10;
+        else if (a.startsWith('--last=')) last = Number(a.slice('--last='.length)) || 10;
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: agent-config route:audit [--last N] [--record] [--weekly] [--json]\n');
+            return 0;
+        }
+    }
+
+    if (weekly) {
+        const { text, records } = render_weekly(recorder_path(), new Date());
+        process.stdout.write(text);
+        return records === 0 ? 1 : 0;
+    }
+
+    let router: Router;
+    try {
+        router = JSON.parse(fs.readFileSync(ROUTER_JSON, 'utf-8')) as Router;
+    } catch (e) {
+        process.stderr.write(`route:audit: cannot read ${ROUTER_JSON}: ${String(e)}\n`);
+        return 2;
+    }
+    const prompts = load_user_prompts(last);
+    if (prompts.length === 0) {
+        process.stdout.write(MEASUREMENT_HEADER + '\n\n');
+        process.stdout.write('no user prompts found in the chat-history log — nothing to audit\n');
+        return 1;
+    }
+    const audits = audit_prompts(router, prompts);
+
+    let recorded = 0;
+    let recorder_note = '';
+    if (record) {
+        if (recorder_enabled()) {
+            recorded = append_records(build_records(audits, new Date().toISOString()), recorder_path());
+            recorder_note = `recorded ${recorded} prompt(s) to ${RECORDER_REL}`;
+        } else {
+            recorder_note = 'recorder disabled (telemetry.routing_recorder.enabled is off — default) — nothing written';
+        }
+    }
+
+    if (as_json) {
+        process.stdout.write(
+            JSON.stringify(
+                { measurement_level: MEASUREMENT_HEADER, audited: audits.length, recorded, prompts: audits },
+                null,
+                2,
+            ) + '\n',
+        );
+        return 0;
+    }
+    const out: string[] = [MEASUREMENT_HEADER, ''];
+    out.push(`audited the last ${audits.length} user prompt(s) — matched rules per prompt`);
+    out.push('(should-have-matched is the reviewer\'s judgment over this table, not a computed verdict)');
+    out.push('');
+    audits.forEach((a, i) => {
+        const shown = a.prompt.length > 100 ? a.prompt.slice(0, 97) + '...' : a.prompt;
+        out.push(`${String(i + 1).padStart(3)}. ${JSON.stringify(shown)}`);
+        if (a.matched.length === 0) {
+            out.push('       → (no trigger matched — kernel only)');
+        } else {
+            for (const m of a.matched) {
+                out.push(`       → ${m.rule} [${m.tier}] (${m.triggers.join(' · ')})`);
+            }
+        }
+    });
+    if (recorder_note) {
+        out.push('');
+        out.push(recorder_note);
+    }
+    process.stdout.write(out.join('\n') + '\n');
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+if (process.argv[1] && (import.meta.url === pathToFileURL(process.argv[1]).href || path.resolve(process.argv[1]) === _HERE)) {
+    process.exitCode = main(process.argv.slice(2));
+}