@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/report_dispatch_import_closure.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env tsx
+/**
+ * Print the static import closure of the hook dispatcher, one module per line
+ * with its class — `verdict`, `payload`, `neither` or `concern`.
+ *
+ * The reading behind `check_kernel_edit_ratified`'s derived watched set: the
+ * `verdict` rows are what the gate adds to its hand-written plumbing pattern.
+ * Named `report_` because it publishes a reading and gates nothing.
+ *
+ * Inputs:
+ *   --root DIR   tree to read (default: this script's repository)
+ *   --markdown   emit a Markdown table instead of plain lines
+ *
+ * Exit 0 always, unless the dispatcher is absent under `--root` (exit 1): an
+ * empty closure from a tree with no dispatcher is not a reading.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    DISPATCHER_PATH,
+    dispatchImportClosure,
+    type ClosureEntry,
+    type ModuleClass,
+} from './_lib/dispatch_import_closure.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+
+const ORDER: readonly ModuleClass[] = ['verdict', 'payload', 'neither', 'concern'];
+
+export function render(entries: readonly ClosureEntry[], markdown: boolean): string[] {
+    const sorted = [...entries].sort(
+        (a, b) => ORDER.indexOf(a.class) - ORDER.indexOf(b.class) || a.path.localeCompare(b.path),
+    );
+    const counts = ORDER.map((c) => `${c} ${entries.filter((e) => e.class === c).length}`).join(' · ');
+    const lines: string[] = [];
+    if (markdown) {
+        lines.push('| Class | Module |', '|---|---|');
+        for (const e of sorted) {
+            lines.push(`| ${e.class} | \`${e.path}\` |`);
+        }
+        lines.push('', `Totals: ${counts}.`);
+        return lines;
+    }
+    for (const e of sorted) {
+        lines.push(`${e.class.padEnd(8)} ${e.path}`);
+    }
+    lines.push(`totals: ${counts}`);
+    return lines;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let root = REPO;
+    let markdown = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--root') {
+            root = path.resolve(argv[i + 1] ?? root);
+            i += 1;
+        } else if (argv[i] === '--markdown') {
+            markdown = true;
+        }
+    }
+    if (!fs.existsSync(path.join(root, DISPATCHER_PATH))) {
+        process.stderr.write(`report_dispatch_import_closure: no ${DISPATCHER_PATH} under ${root}\n`);
+        return 1;
+    }
+    process.stdout.write(`${render(dispatchImportClosure(root), markdown).join('\n')}\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}

package/src/scripts/report_installed_rule_links.ts

@@ -29,10 +29,12 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
     type LinkAuditReport,
+    auditInstalledKindLinks,
     auditInstalledRuleLinks,
     deployPlanFrom,
     rewriteOptionCost,
 } from '../install/installedRuleLinks.js';
+import { loadBaselines } from './_lib/gate_baseline.js';
 import { GLOBAL_DEPLOY_SOURCES } from './install.js';
 
 // ledger-exempt: a REPORTER, not a gate. It has no verdict for a per-target
@@ -73,6 +75,89 @@ export function readings(packageRoot: string, prefixChars: number): HostLinkRead
     return out;
 }
 
+/** Installed artefact kinds `--kinds` can select, in print order. */
+export const LINK_KINDS = ['rules', 'skills', 'commands', 'contexts', 'guidelines'] as const;
+export type LinkKind = (typeof LINK_KINDS)[number];
+
+export interface KindLinkReading {
+    kind: LinkKind | 'non-projected';
+    /** False when the host's plan does not deploy this kind at all. */
+    installed: boolean;
+    links: number;
+    unresolved: number;
+}
+
+/**
+ * One reading per selected kind for one host, plus a final `non-projected` row.
+ *
+ * A link into `docs/` (the ADRs live there) is dead in every install by
+ * construction, so it is taken OUT of its kind's deployable count and summed
+ * into its own row instead — mixing it in would make a kind's number move for a
+ * reason no deploy change can address.
+ */
+export function kindReadings(
+    packageRoot: string,
+    pairs: ReadonlyArray<readonly [string, string]>,
+    kinds: ReadonlyArray<LinkKind>,
+): KindLinkReading[] {
+    const plan = deployPlanFrom(pairs);
+    const out: KindLinkReading[] = [];
+    let npLinks = 0;
+    let npUnresolved = 0;
+    for (const kind of kinds) {
+        const report = auditInstalledKindLinks(plan, packageRoot, `dist/agent-src/${kind}`);
+        if (report === null) {
+            out.push({ kind, installed: false, links: 0, unresolved: 0 });
+            continue;
+        }
+        out.push({
+            kind,
+            installed: true,
+            links: report.audits.length,
+            unresolved: report.audits.length - report.counts.resolved,
+        });
+        npLinks += report.non_projected.length;
+        npUnresolved += report.non_projected.filter((a) => a.verdict !== 'resolved').length;
+    }
+    out.push({ kind: 'non-projected', installed: true, links: npLinks, unresolved: npUnresolved });
+    return out;
+}
+
+/** Key of a kind's recorded count in `src/config/gate-violation-baselines.json`. */
+export function kindBaselineKey(host: string, kind: KindLinkReading['kind']): string {
+    return `report_installed_rule_links:kinds:${host}:${kind}`;
+}
+
+/**
+ * The recorded count for each row, or null where none is recorded.
+ *
+ * Read, never written: the baseline only moves by a reviewed commit, so a new
+ * dead link shows as a live count above it rather than as a quietly raised
+ * number. Nothing here fails on the comparison (D2 — report, never fail).
+ */
+export function recordedBaselines(packageRoot: string, host: string, rows: KindLinkReading[]): (number | null)[] {
+    const { gates } = loadBaselines(packageRoot);
+    return rows.map((r) => gates[kindBaselineKey(host, r.kind)]?.count ?? null);
+}
+
+/** `kind: <name> unresolved <n> of <m>` — the line form the roadmap fixed. */
+export function formatKindLine(r: KindLinkReading, host: string, baseline: number | null = null): string {
+    const name = r.kind === 'non-projected' ? 'non-projected (adr, docs/)' : r.kind;
+    const tail = r.installed ? '' : ` (not installed for ${host})`;
+    const base =
+        baseline === null
+            ? ''
+            : ` [baseline ${String(baseline)}${r.unresolved > baseline ? `, ${String(r.unresolved - baseline)} above it` : ''}]`;
+    return `kind: ${name} unresolved ${String(r.unresolved)} of ${String(r.links)}${tail}${base}`;
+}
+
+function parseKinds(raw: string): LinkKind[] | null {
+    if (raw === 'all') return [...LINK_KINDS];
+    const picked = raw.split(',').map((k) => k.trim());
+    if (picked.length === 0 || picked.some((k) => !(LINK_KINDS as readonly string[]).includes(k))) return null;
+    return LINK_KINDS.filter((k) => picked.includes(k));
+}
+
 function flagValue(flag: string): string | null {
     const argv = process.argv.slice(2);
     const i = argv.indexOf(flag);
@@ -81,9 +166,14 @@ function flagValue(flag: string): string | null {
 
 const USAGE =
     'usage: report_installed_rule_links [--root DIR] [--prefix-chars N] [--json]\n' +
+    '                                   [--kinds all|K[,K...]] [--host HOST]\n' +
     '  --root          package checkout the installer copies FROM (default: cwd)\n' +
     '  --prefix-chars  length of the installed package root, for the rewrite price\n' +
     '                  (default 48, a typical `~/.claude/agent-config` expansion)\n' +
+    '  --kinds         one unresolved count per installed kind instead of the rule\n' +
+    `                  reading: ${LINK_KINDS.join(', ')}, or all; docs/ and ADR\n` +
+    '                  targets are printed as their own row. Reports, never fails.\n' +
+    '  --host          host whose deploy plan --kinds reads (default claude-code)\n' +
     '  --json          machine-readable readings\n';
 
 export function main(): number {
@@ -93,7 +183,7 @@ export function main(): number {
         return 0;
     }
     for (const a of argv) {
-        if (a.startsWith('-') && !['--root', '--prefix-chars', '--json'].includes(a)) {
+        if (a.startsWith('-') && !['--root', '--prefix-chars', '--json', '--kinds', '--host'].includes(a)) {
             process.stderr.write(`unknown argument: ${a}\n${USAGE}`);
             return 2;
         }
@@ -111,6 +201,33 @@ export function main(): number {
         return 1;
     }
 
+    const rawKinds = flagValue('--kinds');
+    if (rawKinds !== null || argv.includes('--kinds')) {
+        const kinds = rawKinds === null ? null : parseKinds(rawKinds);
+        if (kinds === null) {
+            process.stderr.write(`--kinds takes all or a comma list of: ${LINK_KINDS.join(', ')}\n`);
+            return 2;
+        }
+        const host = flagValue('--host') ?? 'claude-code';
+        const pairs = GLOBAL_DEPLOY_SOURCES[host];
+        if (pairs === undefined) {
+            process.stderr.write(`unknown --host ${host}; known: ${Object.keys(GLOBAL_DEPLOY_SOURCES).join(', ')}\n`);
+            return 2;
+        }
+        const kindRows = kindReadings(root, pairs, kinds);
+        const baselines = recordedBaselines(root, host, kindRows);
+        if (argv.includes('--json')) {
+            const rows = kindRows.map((r, i) => ({ ...r, baseline: baselines[i] }));
+            process.stdout.write(`${JSON.stringify({ host, kinds: rows }, null, 2)}\n`);
+            return 0;
+        }
+        process.stdout.write(`installed links per kind, host ${host} (report only; counted since 2026-10-06)\n\n`);
+        kindRows.forEach((r, i) => {
+            process.stdout.write(`  ${formatKindLine(r, host, baselines[i] ?? null)}\n`);
+        });
+        return 0;
+    }
+
     const rows = readings(root, prefixChars);
 
     if (argv.includes('--json')) {

package/src/scripts/report_module_reach.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env tsx
+/**
+ * Report — which `_lib` modules does nothing in production call?
+ *
+ * A REPORT, not a gate: it always exits 0. Phase 3 of
+ * `road-to-modules-that-something-calls.md` wires its counts into
+ * `check_gate_reachability`'s own output, reported and not gated, the way
+ * the estate gate already prints its draft-roadmap count.
+ *
+ * ```bash
+ *   report_module_reach                 # human-readable, one line per module
+ *   report_module_reach --markdown      # the four tables, for the evidence page
+ *   report_module_reach --json
+ * ```
+ */
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+
+import { analyseModuleReach, groupCounts, type ModuleFact, type ReachGroup } from './_lib/module_reach.js';
+import { assertScanned, reportScanned } from './_lib/scan_scope.js';
+
+const _FILE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_FILE), '..', '..');
+
+const GROUP_LABEL: Record<ReachGroup, string> = {
+    'contract-test': 'imported by a test under tests/contracts/',
+    'open-or-deferred-step': 'named in an open or deferred step',
+    'named-outside-open-step': 'named in such a roadmap outside any open step',
+    'named-in-none': 'named in no live roadmap',
+};
+
+function humanLine(m: ModuleFact): string {
+    const bits = [
+        `${m.lines}L`,
+        m.namedByProduction ? 'named-by-production' : 'UNREFERENCED',
+        m.reachedByImportOrPath ? 'reached' : 'REACHED-BY-NOTHING',
+        m.hasOwnEntryPoint ? 'has-entry-point' : null,
+        m.registryDeclared.length > 0 ? `registry:[${m.registryDeclared.join(',')}]` : null,
+        m.importingTests.length > 0 ? `tests:${String(m.importingTests.length)}` : 'tests:0',
+        m.group !== null ? `group:${m.group}` : null,
+    ].filter((b): b is string => b !== null);
+    return `  ${m.relPath} — ${bits.join(' · ')}`;
+}
+
+export function human(modules: readonly ModuleFact[]): string {
+    const unreferenced = modules.filter((m) => !m.namedByProduction);
+    const unreached = modules.filter((m) => !m.reachedByImportOrPath);
+    const counts = groupCounts(unreferenced);
+    const lines: string[] = [];
+    lines.push(
+        `module reach: ${String(modules.length)} module(s) under src/scripts/_lib — ` +
+            `${String(unreferenced.length)} unreferenced by name, ${String(unreached.length)} reached by nothing`,
+    );
+    for (const m of modules) lines.push(humanLine(m));
+    lines.push('');
+    lines.push('unreferenced-by-name groups:');
+    for (const g of Object.keys(GROUP_LABEL) as ReachGroup[]) {
+        lines.push(`  ${GROUP_LABEL[g]}: ${String(counts[g])}`);
+    }
+    return lines.join('\n');
+}
+
+function table(modules: readonly ModuleFact[], header: readonly string[], row: (m: ModuleFact) => string[]): string {
+    const lines = [`| ${header.join(' | ')} |`, `|${header.map(() => '---').join('|')}|`];
+    for (const m of modules) lines.push(`| ${row(m).join(' | ')} |`);
+    return lines.join('\n');
+}
+
+export function markdown(modules: readonly ModuleFact[], roadmapsAvailable: boolean): string {
+    const unreferenced = modules.filter((m) => !m.namedByProduction);
+    const unreached = modules.filter((m) => !m.reachedByImportOrPath);
+    const byGroup = (g: ReachGroup): ModuleFact[] => unreferenced.filter((m) => m.group === g);
+
+    const lines: string[] = [];
+    lines.push('<!-- evidence-type: analysis -->');
+    lines.push('# Module reach — 2026-10');
+    lines.push('');
+    lines.push(
+        `Command: \`npx tsx src/scripts/report_module_reach.ts --markdown\`. ` +
+            `${String(modules.length)} module(s) directly under \`src/scripts/_lib/\`, ` +
+            `${String(unreferenced.length)} named in no file outside themselves and their own tests, ` +
+            `${String(unreached.length)} reached by nothing via import edges or run-by-path.`,
+    );
+    lines.push('');
+    if (!roadmapsAvailable) {
+        lines.push('> No `agents/roadmaps/` directory in this checkout — the two roadmap-based groups below are skipped.');
+        lines.push('');
+    }
+
+    lines.push('## Group 1 — imported by a contract test');
+    lines.push('');
+    lines.push(table(byGroup('contract-test'), ['module', 'lines', 'evidence'], (m) => [m.relPath, String(m.lines), m.groupEvidence ?? '']));
+    lines.push('');
+
+    lines.push('## Group 2 — named in an open or deferred step');
+    lines.push('');
+    lines.push(
+        table(byGroup('open-or-deferred-step'), ['module', 'lines', 'evidence'], (m) => [
+            m.relPath,
+            String(m.lines),
+            m.groupEvidence ?? '',
+        ]),
+    );
+    lines.push('');
+
+    lines.push('## Group 3 — named in such a roadmap outside any open step');
+    lines.push('');
+    lines.push(
+        table(byGroup('named-outside-open-step'), ['module', 'lines', 'evidence'], (m) => [
+            m.relPath,
+            String(m.lines),
+            m.groupEvidence ?? '',
+        ]),
+    );
+    lines.push('');
+
+    lines.push('## Group 4 — named in no live roadmap');
+    lines.push('');
+    lines.push(
+        table(byGroup('named-in-none'), ['module', 'lines', 'importing tests'], (m) => [
+            m.relPath,
+            String(m.lines),
+            String(m.importingTests.length),
+        ]),
+    );
+    lines.push('');
+
+    lines.push('## Every module under `_lib` — full facts');
+    lines.push('');
+    lines.push(
+        table(
+            modules,
+            ['module', 'lines', 'importing tests', 'named by production', 'has entry point', 'registry', 'reached'],
+            (m) => [
+                m.relPath,
+                String(m.lines),
+                String(m.importingTests.length),
+                m.namedByProduction ? 'yes' : 'no',
+                m.hasOwnEntryPoint ? 'yes' : 'no',
+                m.registryDeclared.length > 0 ? m.registryDeclared.join(', ') : '—',
+                m.reachedByImportOrPath ? 'yes' : 'no',
+            ],
+        ),
+    );
+    lines.push('');
+
+    // Phase 2.1: one `reading:` line per fourth-group module — never the
+    // whole unreferenced set, which also holds groups 1-3 that Phase 2
+    // explicitly leaves untouched. The content here is a placeholder; the
+    // real verdict (test-carried / helper-never-connected / only-caller-is-
+    // its-own-test) is a judgement call a re-run of this script cannot make,
+    // and is filled in by hand after reading each module and its test.
+    for (const m of byGroup('named-in-none')) {
+        lines.push(`reading: ${m.relPath} — TODO: read the module and its test, then state the verdict`);
+    }
+
+    return lines.join('\n');
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), root = REPO): number {
+    const { modules, roadmapsAvailable } = analyseModuleReach(root);
+    // One options literal, not three (a second R2 review found it triplicated
+    // across the --json, --markdown and default branches).
+    const scanOpts = {
+        gate: 'report_module_reach',
+        scanned: modules.length,
+        units: 'module(s) under src/scripts/_lib',
+        roots: ['src/scripts/_lib'],
+    };
+    if (argv.includes('--json')) {
+        // No trailing `scanned:` line here — an R2 review found that
+        // `reportScanned` (which PRINTS) made this invalid as a single JSON
+        // document; `check_gate_reachability.ts`'s own `--json` branch already
+        // returns immediately after writing JSON for the same reason. The
+        // scope is still ASSERTED (never silently printed clean from an empty
+        // corpus).
+        assertScanned(scanOpts);
+        process.stdout.write(`${JSON.stringify({ modules, roadmapsAvailable }, null, 2)}\n`);
+    } else if (argv.includes('--markdown')) {
+        // The page is the artifact — no trailing `scanned:` line inside it,
+        // but the scope is still asserted (never silently printed clean from
+        // an empty corpus). The default human mode below is the only one that
+        // still publishes the count per this family's convention.
+        assertScanned(scanOpts);
+        process.stdout.write(`${markdown(modules, roadmapsAvailable)}\n`);
+    } else {
+        // Asserted BEFORE writing, matching the other two branches (an R2
+        // review found the prior "assert after" order here was the one case
+        // that would have printed a human report before a DeadScopeError on
+        // an empty corpus, while --json/--markdown print nothing in that
+        // case) — then printed, since the default mode is the one that still
+        // publishes the count per this family's convention.
+        reportScanned(scanOpts);
+        process.stdout.write(`${human(modules)}\n`);
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    const a = process.argv[1];
+    if (!a) return false;
+    if (a === _FILE || pathToFileURL(path.resolve(a)).href === import.meta.url) return true;
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(_FILE);
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main());
+
+export { REPO };

package/src/scripts/report_obligation_mechanism.ts

@@ -11,8 +11,11 @@
  *     declaration resolves TO (a wired validator, a bound hook, nothing).
  *   · `report_obligation_carriers` — how many artifacts restate the same
  *     obligation, which is a different question from whether one enforces it.
- *   · The `# obligation: line N` frontmatter marker — 107 of 121 rules carry
- *     one and nothing in the tree reads it, so this is its first reader.
+ *   · `src/config/rule-obligations.json` — the stable obligation ids per rule
+ *     (road-to-enforcement-per-obligation). It replaced the hand-kept
+ *     `# obligation: line N` frontmatter marker this report was the only
+ *     reader of, and whose line numbers had drifted out of the law section on
+ *     half the rules that carried one.
  *
  * **Two columns, and conflating them would be the error worth avoiding.**
  * `carried` is measured: a gate either refuses or it does not.
@@ -31,6 +34,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { loadRuleObligations, RULE_OBLIGATIONS_PATH } from './_lib/rule_obligations.js';
+
 // ledger-exempt: a REPORTER, not a gate. Its only non-zero exit says an input
 // instrument could not be run, which is a statement about the walk.
 
@@ -53,7 +58,8 @@ const REFUSING: ReadonlySet<string> = new Set(['validator', 'validator-local', '
 export interface MechanismRow {
     rule: string;
     tier: string;
-    marker_line: number | null;
+    /** Obligation ids this rule declares, `null` when it declares none (the kernel). */
+    obligations: number | null;
     frequency: string;
     declared: number;
     effective: string;
@@ -65,15 +71,6 @@ export interface MechanismRow {
     restatements: number;
 }
 
-/** `# obligation: line N` inside the frontmatter block. */
-export function markerLine(content: string): number | null {
-    if (!content.startsWith('---')) return null;
-    const end = content.indexOf('\n---', 3);
-    const block = end === -1 ? content : content.slice(0, end);
-    const m = /^#\s*obligation:\s*line\s+(\d+)\s*$/m.exec(block);
-    return m ? Number.parseInt(m[1] as string, 10) : null;
-}
-
 function run(root: string, script: string, args: readonly string[]): string {
     return execFileSync(path.join(root, 'scripts-run'), [script, ...args], {
         cwd: root,
@@ -123,10 +120,11 @@ export function rows(root: string): MechanismRow[] {
         }
     }
 
+    const inventory = fs.existsSync(path.join(root, RULE_OBLIGATIONS_PATH))
+        ? loadRuleObligations(root).rules
+        : {};
     const out: MechanismRow[] = [];
     for (const r of coverage.rules) {
-        const file = path.join(root, 'src', 'rules', `${r.id}.md`);
-        const content = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
         const declared = r.declared ?? [];
         const effective = r.effective ?? 'none';
         const frequency = r.obligation_frequency ?? '—';
@@ -140,7 +138,7 @@ export function rows(root: string): MechanismRow[] {
         out.push({
             rule: r.id,
             tier: r.tier ?? '—',
-            marker_line: markerLine(content),
+            obligations: inventory[r.id]?.obligations.length ?? null,
             frequency,
             declared: declared.length,
             effective,
@@ -155,11 +153,11 @@ export function rows(root: string): MechanismRow[] {
 
 export function renderTable(data: readonly MechanismRow[]): string[] {
     const L: string[] = [];
-    L.push('| Rule | Tier | Marker | Frequency | `enforced_by` | Resolves to | Carried | Slot exists | Restatements |');
+    L.push('| Rule | Tier | Obligations | Frequency | `enforced_by` | Resolves to | Carried | Slot exists | Restatements |');
     L.push('|---|---|---:|---|---:|---|---|---|---:|');
     for (const r of data) {
         L.push(
-            `| \`${r.rule}\` | ${r.tier} | ${r.marker_line === null ? '—' : String(r.marker_line)} | ` +
+            `| \`${r.rule}\` | ${r.tier} | ${r.obligations === null ? '—' : String(r.obligations)} | ` +
                 `${r.frequency} | ${String(r.declared)} | \`${r.effective}\` | ${r.carried} | ` +
                 `${r.slot_exists ? 'yes' : 'no'} | ${String(r.restatements)} |`,
         );
@@ -210,7 +208,7 @@ export function main(): number {
             `  declared gap (the rule says instruction-only / none): ${String(by('declared-gap'))}\n` +
             `  no enforcement declaration at all: ${String(by('undeclared'))}\n` +
             `  not gated, but a host event fires at the obligation's frequency: ${String(slotNoGate)}\n` +
-            `  carry no \`# obligation: line N\` marker: ${String(data.filter((r) => r.marker_line === null).length)}\n`,
+            `  declare no obligation ids: ${String(data.filter((r) => r.obligations === null).length)}\n`,
     );
     return 0;
 }