@event4u/agent-config 9.25.0 → 9.27.0

package/src/scripts/check_enforcement_coverage.ts

@@ -38,6 +38,16 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { KERNEL_RULE_ID_SET } from './_lib/kernel_rules.js';
+import {
+    carrier_frequency_by_platform,
+    covers,
+    covers_any,
+    is_frequency,
+    parse_hook_platforms,
+    type Frequency,
+    type PlatformBinding,
+} from './_lib/obligation_frequency.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
@@ -73,6 +83,25 @@ export type Resolution =
     | 'missing'         // declared target does not exist at all
     | 'none';           // honest, recorded gap
 
+/**
+ * Whether the carrier's firing set covers the obligation's — the question
+ * `effective` does not answer.
+ *
+ * `covered`      — some declared carrier covers the obligation on every
+ *                  hook-capable platform.
+ * `gap`          — at least one hook-capable platform where no declared carrier
+ *                  covers it. `gap_platforms` names them.
+ * `declared-gap` — the rule declares `enforced_by: none`; the gap is stated in
+ *                  the rule's own text, so it is honest, not a defect.
+ * `unclassified` — no `obligation_frequency` to join against. The nine kernel
+ *                  rules sit here: `block_kernel_rule_writes.ts` denies agent
+ *                  writes to them, so the field cannot be populated by the same
+ *                  pass that populated the other 105.
+ * `unmeasured`   — the rule declares no carrier at all; model-carried by design,
+ *                  making no claim this join could falsify.
+ */
+export type FrequencyVerdict = 'covered' | 'gap' | 'declared-gap' | 'unclassified' | 'unmeasured';
+
 export interface RuleCoverage {
     id: string;
     tier: string;
@@ -82,6 +111,21 @@ export interface RuleCoverage {
     /** Strongest resolution, by the ordering in `RANK`. */
     effective: Resolution;
     notes: string[];
+    /** Declared obligation period (frontmatter), or null when undeclared. */
+    obligation_frequency: Frequency | null;
+    /**
+     * Carrier period per hook-capable platform — never a single scalar.
+     *
+     * A scalar is wrong twice over: copilot has no hook surface at all, so a
+     * weakest-platform collapse turns one platform property into a finding on
+     * every hook-carried rule; and cline maps `stop` from `TaskCancel`, so the
+     * same slot means per-turn on six platforms and per-interruption there. Both
+     * are invisible in one number.
+     */
+    carrier_frequency: Record<string, string> | null;
+    frequency_verdict: FrequencyVerdict;
+    /** Hook-capable platforms where no declared carrier covers the obligation. */
+    gap_platforms: string[];
 }
 
 /** Strength order — a rule is credited with its strongest resolving backstop. */
@@ -396,14 +440,87 @@ export function strongest(resolutions: Resolution[]): Resolution {
     return best;
 }
 
+// ----------------------------------------------------------- frequency join
+
+/**
+ * Join a rule's declared obligation period against its carriers' firing periods.
+ *
+ * Runs per hook-capable platform, never as one scalar. A rule is covered only
+ * when SOME declared carrier covers it on EVERY hook-capable platform; the
+ * platforms where none does are named, because "uncovered on windsurf" and
+ * "uncovered everywhere" are different findings with different fixes.
+ *
+ * `validator:` / `test:` carriers are SWEEP carriers — they fire once and read
+ * the whole tree, so their reach is bounded by what lands in an artefact rather
+ * than by how often they run. Modelling them as per-commit point carriers would
+ * make every `validator:`-carried rule with a per-edit obligation a finding at
+ * once: one modelling error rendered as a fifth of the corpus.
+ */
+export function join_frequency(
+    obligation: Frequency | null,
+    declared: string[],
+    binding: PlatformBinding,
+): {
+    verdict: FrequencyVerdict;
+    carrier_frequency: Record<string, string> | null;
+    gap_platforms: string[];
+} {
+    if (obligation === null) {
+        return { verdict: 'unclassified', carrier_frequency: null, gap_platforms: [] };
+    }
+    if (declared.length === 0) {
+        return { verdict: 'unmeasured', carrier_frequency: null, gap_platforms: [] };
+    }
+    if (declared.every((d) => d === 'none')) {
+        return { verdict: 'declared-gap', carrier_frequency: null, gap_platforms: [] };
+    }
+
+    const has_sweep = declared.some((d) => d.startsWith('validator:') || d.startsWith('test:'));
+    const hook_concerns = declared
+        .filter((d) => d.startsWith('hook:'))
+        .map((d) => d.slice('hook:'.length));
+
+    const per_platform: Record<string, string> = {};
+    const gap_platforms: string[] = [];
+
+    for (const platform of binding.slots.keys()) {
+        if (binding.fallback_only.has(platform)) continue;
+
+        let covered = false;
+        const seen: Frequency[] = [];
+
+        if (has_sweep && covers({ frequency: 'per-commit', mode: 'sweep' }, obligation)) {
+            covered = true;
+        }
+        for (const concern of hook_concerns) {
+            for (const f of carrier_frequency_by_platform(concern, binding)[platform] ?? []) {
+                if (!seen.includes(f)) seen.push(f);
+            }
+        }
+        if (covers_any(seen, obligation)) covered = true;
+
+        per_platform[platform] =
+            seen.length > 0 ? seen.join('+') : has_sweep ? 'sweep' : 'absent';
+        if (!covered) gap_platforms.push(platform);
+    }
+
+    return {
+        verdict: gap_platforms.length === 0 ? 'covered' : 'gap',
+        carrier_frequency: per_platform,
+        gap_platforms,
+    };
+}
+
 // -------------------------------------------------------------------- report
 
 export function collect(): RuleCoverage[] {
     const ci_corpus = load_corpus(WORKFLOW_DIRS);
     const local_corpus = load_corpus(TASK_DIRS, TASK_FILES);
-    const hooks = fs.existsSync(HOOK_MANIFEST)
-        ? parse_hook_manifest(fs.readFileSync(HOOK_MANIFEST, 'utf-8'))
-        : new Map<string, boolean>();
+    const manifest_text = fs.existsSync(HOOK_MANIFEST)
+        ? fs.readFileSync(HOOK_MANIFEST, 'utf-8')
+        : '';
+    const hooks = manifest_text ? parse_hook_manifest(manifest_text) : new Map<string, boolean>();
+    const binding = parse_hook_platforms(manifest_text);
     const exists = (rel: string): boolean => fs.existsSync(path.join(REPO_ROOT, rel));
     // Seeded separately so the umbrella expansion answers "reachable from CI"
     // rather than "reachable from anything". The expansion itself was correct;
@@ -425,14 +542,36 @@ export function collect(): RuleCoverage[] {
             resolutions.push(resolution);
             if (note) notes.push(note);
         }
+        const id = name.replace(/\.md$/, '');
+        const raw_freq = fm['obligation_frequency'];
+        const obligation: Frequency | null = is_frequency(raw_freq) ? raw_freq : null;
+        const { verdict, carrier_frequency, gap_platforms } = join_frequency(
+            obligation,
+            declared,
+            binding,
+        );
+        // Say WHY a row is unclassified. For the nine kernel rules the answer is
+        // structural rather than an authoring lapse — block_kernel_rule_writes
+        // denies the write — and a reader who cannot tell those apart will read
+        // the same bucket as either "expected" or "someone forgot".
+        if (verdict === 'unclassified' && KERNEL_RULE_ID_SET.has(id)) {
+            notes.push(
+                'no obligation_frequency: kernel rule, and block_kernel_rule_writes denies ' +
+                    'the write with no agent-accessible override',
+            );
+        }
         out.push({
-            id: name.replace(/\.md$/, ''),
+            id,
             tier: String(fm['tier'] ?? '—'),
             type: String(fm['type'] ?? '—'),
             declared,
             resolutions,
             effective: strongest(resolutions),
             notes,
+            obligation_frequency: obligation,
+            carrier_frequency,
+            frequency_verdict: verdict,
+            gap_platforms,
         });
     }
     return out;
@@ -450,6 +589,16 @@ export interface Summary {
     missing: number;
     undeclared: number;
     blocking_pct: number;
+    /**
+     * Rules whose declared carrier does not fire often enough to cover their
+     * declared obligation, on at least one hook-capable platform. The number
+     * this roadmap exists to produce — and the one `--check` ratchets, because
+     * `blocking` cannot see it: `session-canary` is declared, wired, firing, and
+     * in this bucket.
+     */
+    frequency_gap: number;
+    /** Rules with no `obligation_frequency` to join — the nine kernel rules. */
+    frequency_unclassified: number;
 }
 
 export function summarise(rows: RuleCoverage[]): Summary {
@@ -466,6 +615,8 @@ export function summarise(rows: RuleCoverage[]): Summary {
         missing: count((r) => r.effective === 'missing'),
         undeclared: rows.length - declared.length,
         blocking_pct: rows.length === 0 ? 0 : Math.round((blocking / rows.length) * 1000) / 10,
+        frequency_gap: count((r) => r.frequency_verdict === 'gap'),
+        frequency_unclassified: count((r) => r.frequency_verdict === 'unclassified'),
     };
 }
 
@@ -513,9 +664,13 @@ function main(argv: string[]): number {
                 {
                     _doc:
                         'Enforcement-coverage baseline. `blocking` counts rules whose strongest ' +
-                        'enforced_by resolves to something that can fail a build. Coverage is a ' +
-                        'ratchet: --check fails when blocking falls or unwired rises. Regenerate ' +
-                        'intentionally with --write-baseline when the change is the point.',
+                        'enforced_by resolves to something that can fail a build. `frequency_gap` ' +
+                        'counts rules whose carrier does not fire often enough to cover their ' +
+                        'declared obligation on some hook-capable platform — a rule can be ' +
+                        'blocking and in that bucket at once. Coverage is a ratchet: --check fails ' +
+                        'when blocking falls, or unwired / local_only / missing / frequency_gap ' +
+                        'rises. Regenerate intentionally with --write-baseline when the change is ' +
+                        'the point.',
                     summary,
                 },
                 null,
@@ -543,6 +698,27 @@ function main(argv: string[]): number {
         );
     }
 
+    lines.push(
+        `  frequency: ${summary.frequency_gap} gap · ${summary.frequency_unclassified} unclassified ` +
+            `(kernel — block_kernel_rule_writes denies the field)`,
+    );
+
+    const gaps = rows.filter((r) => r.frequency_verdict === 'gap');
+    if (gaps.length > 0) {
+        lines.push('');
+        lines.push('  frequency gaps — carrier fires, but not often enough:');
+        for (const r of gaps) {
+            const where =
+                r.gap_platforms.length === Object.keys(r.carrier_frequency ?? {}).length
+                    ? 'every hook-capable platform'
+                    : r.gap_platforms.join(', ');
+            lines.push(
+                `    · ${r.id}: obligation ${r.obligation_frequency}, carrier ` +
+                    `${r.declared.join(' + ')} — uncovered on ${where}`,
+            );
+        }
+    }
+
     const problems = rows.filter((r) => r.notes.length > 0);
     if (problems.length > 0) {
         lines.push('');
@@ -569,6 +745,15 @@ function main(argv: string[]): number {
         if (summary.unwired > base.unwired) {
             regressions.push(`unwired declarations rose: ${base.unwired} → ${summary.unwired}`);
         }
+        // The bucket `blocking` structurally cannot see: a rule can be declared,
+        // wired, firing and still mis-slotted. `??` tolerates a pre-frequency
+        // baseline so the field's own introduction does not red the ratchet.
+        if (summary.frequency_gap > (base.frequency_gap ?? Number.POSITIVE_INFINITY)) {
+            regressions.push(
+                `frequency gaps rose: ${base.frequency_gap} → ${summary.frequency_gap} ` +
+                    `(a rule's carrier no longer fires often enough for its obligation)`,
+            );
+        }
         // A validator dropping out of a workflow back into taskfile-only is the
         // exact regression this split was built to name. Without this line the
         // headline would fall and only the `blocking` check would notice, which

package/src/scripts/check_gate_coverage.ts

@@ -363,6 +363,7 @@ export function main(argv: readonly string[]): number {
     );
   }
   const hardening = report_hardening_ratchet();
+  const selfTest = report_self_test_ratchet();
   if (failed.length > 0) {
     process.stdout.write(`❌  ${String(failed.length)} gate(s) failed the coverage floor.\n`);
     return 1;
@@ -370,6 +371,9 @@ export function main(argv: readonly string[]): number {
   if (hardening !== 0) {
     return hardening;
   }
+  if (selfTest !== 0) {
+    return selfTest;
+  }
   process.stdout.write('✅  every enforced gate cleared its coverage floor.\n');
   return 0;
 }
@@ -400,6 +404,69 @@ export function report_hardening_ratchet(): number {
   return verdict.ok ? 0 : 1;
 }
 
+/**
+ * Registered gates that carry no `--self-test` and no exemption — the count
+ * that must not RISE.
+ *
+ * `_lib/gate_self_test.ts` proves a gate DISCRIMINATES: it drives the real
+ * binary through cases that must reject and cases that must accept, with a
+ * `minRejectCases` floor so an all-accepting suite cannot satisfy it. A gate
+ * that emits an enforced `scanned:` count has proven it read something; only a
+ * self-test proves the reading changes the verdict.
+ *
+ * ## Why this is a NON-ADOPTER count and not an adoption column
+ *
+ * The roadmap item asked for adoption as a column in `gate-coverage.yml`,
+ * ratcheted upward. That is the exact shape `report_hardening_ratchet` above
+ * rejects in this same file — a coverage-percentage ratchet "tracks how far the
+ * fix has spread and can never regress, so it grades the solution instead of
+ * the problem". Inverting it fixes that: the number below can regress (a new
+ * registered gate written without a self-test raises it), and the target is 0.
+ * That is also the shape the sibling adoption ratchet already uses —
+ * `check_gate_completeness`'s ledger baseline is a shrink-only count of
+ * non-adopters, not a rising percentage.
+ *
+ * Population is the MANIFEST, not every script under `src/scripts`: a self-test
+ * is a claim about a gate CI runs against a floor. Padding the manifest to move
+ * this number would add a floor per row, which is the opposite of gaming.
+ *
+ * Exemption marker: `// self-test-exempt: <reason>` with a non-empty reason. A
+ * bare marker does not count — same discipline as `// no-index:` and
+ * `// ledger-exempt:`.
+ */
+export function list_self_test_non_adopters(
+  dir = path.join(REPO_ROOT, 'src/scripts'),
+  ids: ReadonlySet<string> = enforced_manifest_ids(),
+): string[] {
+  const out: string[] = [];
+  for (const id of [...ids].sort()) {
+    let src: string;
+    try {
+      src = fs.readFileSync(path.join(dir, `${id}.ts`), 'utf8');
+    } catch {
+      // A registered id with no readable script cannot prove discrimination.
+      out.push(id);
+      continue;
+    }
+    const adopts = /_lib\/gate_self_test\.js/.test(src);
+    const exempt = /\/\/\s*self-test-exempt:\s*\S/.test(src);
+    if (!adopts && !exempt) out.push(id);
+  }
+  return out;
+}
+
+/** Ratchet wrapper for {@link list_self_test_non_adopters}. */
+export function report_self_test_ratchet(): number {
+  const missing = list_self_test_non_adopters();
+  const verdict = checkRatchet({
+    gate: 'gate-self-test:registered-non-adopters',
+    actual: missing.length,
+    repoRoot: REPO_ROOT,
+  });
+  process.stdout.write(`  ${verdict.ok ? '✅' : '❌'} ${verdict.message}\n`);
+  return verdict.ok ? 0 : 1;
+}
+
 /**
  * Manifest ids whose `scanned:` line is actually ENFORCED against a floor.
  *

package/src/scripts/check_hook_bundle_freshness.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env tsx
+/**
+ * Fail when the self-hosted hook bundle is older than the hook sources it
+ * bundles — i.e. when this repo's own agent is running a hook fix that has
+ * not been built.
+ *
+ * WHY THIS EXISTS — measured, not hypothetical.
+ *
+ * The Claude hook command resolves its dispatcher in two steps: the installed
+ * package copy (`node_modules/@event4u/agent-config/dist/hooks/dispatch.js`)
+ * if present, else this repo's OWN `dist/hooks/dispatch.js`. In the
+ * agent-config repo the second branch always wins — that is the dogfooding
+ * path, and it is the only place these hooks are exercised before release.
+ *
+ * `dist/hooks/dispatch.js` is UNTRACKED (a build artifact) and is produced
+ * only by `npm run build:hooks`, which no Taskfile target, no `task ci`
+ * target, and no workflow invokes. `prepack` runs the full build, so a
+ * PUBLISHED package is always fresh and consumers are unaffected. The gap is
+ * local and it is exactly where the testing happens.
+ *
+ * Consequence, observed on 2026-08-06: the conformance round-2 PR (#1195)
+ * merged four hook fixes — among them the language-mirror pin — while the
+ * running bundle was from 07:27 that morning, before any of them existed.
+ * Ten hook sources were newer than the bundle. In the very session that
+ * shipped the language fix, the scanner counted four German-prompt /
+ * English-reply violations: the fix was merged, correct, and not loaded.
+ *
+ * A hook fix that cannot reach the agent that wrote it is indistinguishable
+ * from no fix, and nothing said so. This gate says so.
+ *
+ * WHAT IT DOES NOT DO: it never builds. Building into a live hook path is a
+ * documented hazard in this repo (an esbuild run that overwrites the
+ * dispatcher a running hook is executing can wedge the tool loop), so the
+ * remedy is printed for a human to run deliberately.
+ *
+ * Exit codes: 0 = fresh, or no self-hosted bundle to check · 1 = stale.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parse as parseYaml } from "yaml";
+
+import { reportScanned } from "./_lib/scan_scope.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, "..", "..");
+const BUNDLE = path.join("dist", "hooks", "dispatch.js");
+const MANIFEST = path.join("src", "scripts", "hook_manifest.yaml");
+const HOOK_DIR = path.join("src", "scripts", "hooks");
+const REMEDY = "npm run build:hooks";
+
+/** Every source whose edit changes the bundle's behaviour. */
+export function bundledSources(root: string): string[] {
+  const out = new Set<string>();
+
+  const manifestAbs = path.join(root, MANIFEST);
+  if (fs.existsSync(manifestAbs)) {
+    out.add(MANIFEST);
+    try {
+      const doc = parseYaml(fs.readFileSync(manifestAbs, "utf-8")) as {
+        concerns?: Record<string, { script?: string }>;
+      };
+      for (const def of Object.values(doc?.concerns ?? {})) {
+        const s = def?.script;
+        // A concern script is bundled wherever it lives, not only under hooks/.
+        if (typeof s === "string" && s.endsWith(".ts")) out.add(s);
+      }
+    } catch {
+      // A malformed manifest is another gate's problem; still check the dir.
+    }
+  }
+
+  const hookDirAbs = path.join(root, HOOK_DIR);
+  if (fs.existsSync(hookDirAbs)) {
+    for (const e of fs.readdirSync(hookDirAbs, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith(".ts")) out.add(path.join(HOOK_DIR, e.name));
+    }
+  }
+
+  return [...out].filter((rel) => fs.existsSync(path.join(root, rel))).sort();
+}
+
+export interface Result {
+  /** No self-hosted bundle → the installed package copy is authoritative. */
+  skipped: boolean;
+  bundleMtimeMs: number;
+  /** Sources strictly newer than the bundle, newest first. */
+  stale: { file: string; mtimeMs: number }[];
+  checked: number;
+}
+
+export function check(root: string): Result {
+  const bundleAbs = path.join(root, BUNDLE);
+  if (!fs.existsSync(bundleAbs)) {
+    return { skipped: true, bundleMtimeMs: 0, stale: [], checked: 0 };
+  }
+  const bundleMtimeMs = fs.statSync(bundleAbs).mtimeMs;
+  const sources = bundledSources(root);
+  const stale = sources
+    .map((file) => ({ file, mtimeMs: fs.statSync(path.join(root, file)).mtimeMs }))
+    .filter((s) => s.mtimeMs > bundleMtimeMs)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return { skipped: false, bundleMtimeMs, stale, checked: sources.length };
+}
+
+function stamp(ms: number): string {
+  return new Date(ms).toISOString().replace("T", " ").slice(0, 16);
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+  const root = REPO_ROOT;
+  const quiet = argv.includes("--quiet");
+  const r = check(root);
+
+  // Scope hardening: publish the count and refuse a silent zero. The one
+  // legitimate zero is the absent self-hosted bundle — an optional input, and
+  // the reason survives the manifest's own test ("if the scan root were
+  // deleted, would this still make sense?"): with no bundle there is no stale
+  // dispatcher to catch, which is a correct verdict rather than blindness.
+  reportScanned({
+    gate: "check_hook_bundle_freshness",
+    scanned: r.checked,
+    units: "bundled hook source(s)",
+    roots: [BUNDLE, HOOK_DIR, MANIFEST],
+    ...(r.skipped
+      ? {
+          allowEmpty:
+            "OPTIONAL_INPUT: no self-hosted dist/hooks/dispatch.js — this repo is not " +
+            "running its own bundle (fresh checkout / CI), so there is nothing to compare against.",
+        }
+      : {}),
+  });
+
+  // A gate that scans nothing must SAY it scanned nothing — a silent green
+  // here is indistinguishable from a pass.
+  if (r.skipped) {
+    if (!quiet) {
+      process.stdout.write(
+        `✅  OK  hook bundle: no self-hosted ${BUNDLE} — the installed package copy is in use, nothing to check\n`,
+      );
+    }
+    return 0;
+  }
+
+  if (r.stale.length === 0) {
+    if (!quiet) {
+      process.stdout.write(
+        `✅  OK  hook bundle: fresh (built ${stamp(r.bundleMtimeMs)}, ${String(r.checked)} bundled source(s) checked)\n`,
+      );
+    }
+    return 0;
+  }
+
+  console.error(
+    `❌  hook bundle is STALE — the running dispatcher predates ${r.stale.length} of ${r.checked} bundled source(s).`,
+  );
+  console.error(`    ${BUNDLE} built ${stamp(r.bundleMtimeMs)}; newer sources:`);
+  for (const s of r.stale.slice(0, 10)) {
+    console.error(`      ${stamp(s.mtimeMs)}  ${s.file}`);
+  }
+  if (r.stale.length > 10) console.error(`      … and ${r.stale.length - 10} more`);
+  console.error("");
+  console.error(`    Your hooks are running the OLD code. Rebuild:  ${REMEDY}`);
+  console.error(
+    "    (This gate never builds for you — writing into a live hook path can wedge the tool loop.)",
+  );
+  return 1;
+}
+
+const invokedDirectly = ((): boolean => {
+  const entry = process.argv[1];
+  if (entry === undefined) return false;
+  try {
+    return fs.realpathSync(path.resolve(entry)) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  process.exit(main());
+}