@event4u/agent-config 9.26.0 → 9.27.0

package/src/scripts/_lib/session_register.ts

@@ -0,0 +1,361 @@
+/**
+ * Shared per-session register — so a starting session can see that another
+ * session is already live on this repo, on which branch, and on which roadmap.
+ *
+ * ## Where it lives, and why that needs no new machinery
+ *
+ * `<git-common-dir>/agent-sessions/<session_id>.json`. The common git directory
+ * resolves to the **same** directory from every worktree of a repo, so the
+ * register is shared by construction: no new directory to create, no sync step,
+ * no generator, and never tracked by git. Resolution is
+ * `_lib/git_common_dir.ts` — reused, not re-implemented, because a repo with two
+ * different answers to "where is the common dir" is a bug waiting for a
+ * symlinked parent.
+ *
+ * Runtime state under `agents/runtime/state/` cannot serve this purpose:
+ * concerns run with `CWD = envelope.workspace_root`, so in a worktree that path
+ * is the worktree's own. Measured 2026-08-07 — the main checkout's state
+ * directory was populated and a fresh worktree's did not exist at all. Two
+ * sessions in two worktrees share nothing there.
+ *
+ * ## One file per session — one writer each
+ *
+ * Each session owns exactly one file and is its only writer, so there is no
+ * concurrent-write case to solve: atomicity comes from write-temp + rename
+ * (`_lib/fs_atomic.ts`), the file never grows, compaction does not exist, the
+ * reader does a `readdir` plus N small reads, and cleanup is an `unlink` of
+ * expired files during the `session_start` read.
+ *
+ * The append-only JSONL alternative buys concurrency safety this layout does not
+ * need and pays for it with unbounded growth (one record per turn per session
+ * once heartbeating), a rotation problem (rotating under live appenders loses
+ * heartbeats to the unlinked inode — the classic logrotate defect), and
+ * fold-the-whole-file reads.
+ *
+ * ## Liveness is a heartbeat inside the record — never file mtime
+ *
+ * `last_seen` is rewritten every turn by a hook, and expiry compares that field.
+ * File mtime is explicitly ruled out: `worktree_cleanup_check.ts:65-68` records
+ * the failure — plain `git status` refreshes the on-disk index and bumps the very
+ * mtime being read as liveness, which moved 10 worktrees from safe to live
+ * between two consecutive runs. A field only this concern writes has no such
+ * coupling.
+ *
+ * ## Two accepted limits — declared, not hidden
+ *
+ * 1. **Idle is indistinguishable from crashed.** A session left open over lunch
+ *    stops heartbeating, expires, and releases its claim although the user
+ *    returns. No hook-based heartbeat can tell that apart from a crash. This is
+ *    accepted, and it belongs in user-facing documentation: walking away for
+ *    longer than the TTL means another session may claim your branch.
+ * 2. **This is advisory, not a mutex.** Two sessions can claim in the same
+ *    millisecond. Nothing here provides exclusion, and no later feature may be
+ *    built on it as if it did.
+ *
+ * ## Failure is always open
+ *
+ * Every function here swallows its errors and degrades to "no register": a
+ * session that cannot read or write it still starts, and behaves exactly as
+ * sessions did before this existed.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { write_atomic } from './fs_atomic.js';
+import { git_common_dir } from './git_common_dir.js';
+
+/** Directory name under the common git dir. Never tracked; git ignores unknown
+ *  directories inside `.git` by construction. */
+export const REGISTER_DIRNAME = 'agent-sessions';
+
+/**
+ * Per-host TTL in seconds — how long a record may go without a heartbeat before
+ * a reader treats the session as gone.
+ *
+ * **Derived from data for exactly one host, and honest about the rest.** The
+ * chat-history corpus in this repo holds 71 records across 5 sessions over 24.5
+ * hours, and every one of them is `claude`; 77 % of the gaps come from a single
+ * session. The per-host split the design asked for is **not measurable** from
+ * that, so no interpolated values are shipped for hosts nobody observed. Full
+ * measurement record: `agents/evidence/analysis/parallel-session-register-phase1.md`.
+ *
+ * `claude` is taken from the **raw, unfiltered** p99 (13 705 s) and the raw
+ * user→user max (14 199 s), rounded up to the next hour. Deliberately *not* the
+ * idle-filtered p95: filtering gaps > 30 min characterises turn cadence
+ * correctly and is wrong as an expiry basis, because those gaps occur **inside**
+ * live sessions — 35 % of user→user gaps exceed 30 minutes while the session is
+ * demonstrably still working. A TTL from the filtered p95 would expire a live
+ * claim on roughly a third of turns, which is the collision this register exists
+ * to prevent, re-created by its own mitigation.
+ */
+export const TTL_MEASURED_SECONDS: Readonly<Record<string, number>> = Object.freeze({
+    claude: 14_400, // 4 h — raw p99 13 705 s / raw user→user max 14 199 s, rounded up
+});
+
+/**
+ * TTL for a host with **no** measurements: `3 ×` the one measured p99.
+ *
+ * The name says `MEASURED` above and `DEFAULT` here on purpose (council
+ * 2026-08-07, both members): a map holding one real entry plus a fallback is
+ * honest only if it is *named* as that, rather than presented as a populated
+ * per-host table. Six empty slots would be speculation wearing a data structure.
+ *
+ * The council also moved this number down from a proposed 24 h. The argument
+ * against 24 h: the evidence for a wide spread is that the same host's raw p99
+ * in another project corpus is 53 903 s, i.e. a 4× range — which does not
+ * justify a 6× extrapolation, and a full day makes the register useless on an
+ * unmeasured host, since a crashed session blocks a roadmap claim until
+ * tomorrow. 12 h stays comfortably above every observed live-session gap while
+ * keeping the claim recoverable within a working day.
+ */
+export const TTL_DEFAULT_SECONDS = 43_200; // 12 h
+
+/**
+ * Resolve the TTL for a record, from **the record's own platform** — never the
+ * reader's. Session B on one host reading session A's record must apply A's
+ * cadence, because the TTL describes how often A heartbeats.
+ */
+export function ttl_seconds_for(platform: string | null | undefined): number {
+    const key = String(platform ?? '').trim().toLowerCase();
+    return TTL_MEASURED_SECONDS[key] ?? TTL_DEFAULT_SECONDS;
+}
+
+/** True when this platform's TTL is a measured value rather than the fallback. */
+export function ttl_is_measured(platform: string | null | undefined): boolean {
+    const key = String(platform ?? '').trim().toLowerCase();
+    return Object.prototype.hasOwnProperty.call(TTL_MEASURED_SECONDS, key);
+}
+
+/**
+ * Platforms whose `stop` slot means **the task really ended**, so the register
+ * entry is deleted there instead of merely refreshed.
+ *
+ * The general rule is the opposite and stays the default: `stop` is a *second
+ * heartbeat carrier*, never a deregistration trigger, because on Claude Code the
+ * native `Stop` fires after **every assistant reply** — deregistering there
+ * would kill a live session's own record after its first reply.
+ *
+ * Cline is the one host where that reading is wrong. Its `stop` is mapped from
+ * `TaskCancel` (`hook_manifest.yaml:473`) and is typed `per-event` rather than
+ * `per-turn` (`_lib/obligation_frequency.ts:269-271`), while its `session_end`
+ * is mapped from `TaskComplete` (`:472`). A **cancelled** Cline task therefore
+ * reaches neither deregistration path and leaks its claim until the TTL — and
+ * cancel-and-restart is a routine Cline workflow, not an edge case.
+ *
+ * **This is an explicit allow-list, not a computed condition** (council
+ * 2026-08-07, both members). Deriving it from `slot_frequency(...) ===
+ * 'per-event'` would mean a future platform silently acquires deregistration
+ * behaviour the moment someone types it that way, in a code path where the
+ * failure mode is "a live session deleted its own claim". A human adds a line
+ * here, deliberately, or the platform keeps the safe default.
+ *
+ * The safety model is unchanged either way: TTL remains the correctness basis on
+ * every platform including Cline. This only frees the claim sooner.
+ */
+export const DEREGISTER_ON_STOP_PLATFORMS: ReadonlySet<string> = new Set(['cline']);
+
+/** True when `stop` on this platform means the task ended, not "a reply landed". */
+export function stop_means_session_end(platform: string | null | undefined): boolean {
+    return DEREGISTER_ON_STOP_PLATFORMS.has(String(platform ?? '').trim().toLowerCase());
+}
+
+/**
+ * Platforms where a per-turn heartbeat actually fires today.
+ *
+ * Deliberately **not** derived from the frequency lattice. That instrument
+ * models *slot presence*, and two hosts have a slot that never fires:
+ *
+ * - `cursor` — `user_prompt_submit` and `stop` are **IDE-only**; the CLI fires
+ *   only shell-execution hooks (`hook_manifest.yaml:365-366`,
+ *   `chat-history-platform-hooks.md:214`). The lattice has no IDE/CLI dimension,
+ *   so it reports cursor covered.
+ * - `cowork` — slots are structurally wired but lifecycle events do not fire
+ *   (`hook_manifest.yaml:346-351`).
+ * - `copilot` — no hook surface at all (`hook_manifest.yaml:428-429`), excluded
+ *   from the join by declaration.
+ *
+ * A session on an excluded host still *registers* if a `session_start` reaches
+ * it, and simply stops being visible after its TTL. It is never reported as
+ * covered.
+ */
+export const HEARTBEAT_REACHABLE_PLATFORMS: ReadonlySet<string> = new Set([
+    'claude',
+    'augment', // post-reply `stop` only — sufficient for a liveness stamp
+    'cline', // pre-reply `user_prompt_submit` only
+    'windsurf',
+    'gemini',
+]);
+
+/** One live session, as seen by every other session on the repo. */
+export interface SessionRecord {
+    /** Host-provided session id; also the filename stem. */
+    session_id: string;
+    /** Host platform — decides which TTL applies to THIS record. */
+    platform: string;
+    /** Absolute path of the worktree this session is working in. */
+    worktree: string;
+    /** Branch at the last heartbeat. Re-read every beat; sessions check out. */
+    branch: string | null;
+    /** Roadmap slug this session claims, or null when it has not picked one. */
+    roadmap_slug: string | null;
+    /** ISO-8601 UTC, set once at registration. */
+    started_at: string;
+    /** ISO-8601 UTC, rewritten every heartbeat. The liveness signal. */
+    last_seen: string;
+}
+
+/**
+ * Filename-safe stem for a session id. Path separators and `..` collapse to `_`
+ * so a hostile or merely odd id cannot escape the register directory — the same
+ * traversal guard the dispatcher applies to its feedback directory.
+ *
+ * The fallback fires when the sanitised stem carries **no alphanumeric
+ * character**, not merely when it is empty. `'///'` sanitises to `'___'`, which
+ * is a legal filename and a useless one: it distinguishes nothing, so two
+ * different odd session ids would silently share a record. Requiring one
+ * alphanumeric makes the degenerate case land on the explicit marker instead.
+ */
+export function safe_stem(session_id: string): string {
+    const collapsed = String(session_id ?? '')
+        .replace(/\.\./g, '_')
+        .replace(/[/\\]/g, '_')
+        .replace(/[^A-Za-z0-9._-]/g, '_')
+        .slice(0, 128);
+    return /[A-Za-z0-9]/.test(collapsed) ? collapsed : 'unknown-session';
+}
+
+/**
+ * The register directory for a workspace, or `null` when there is no git common
+ * dir to anchor it to. Does **not** create the directory — writers do.
+ */
+export function register_dir(workspace_root: string): string | null {
+    const common = git_common_dir(workspace_root);
+    return common === null ? null : path.join(common, REGISTER_DIRNAME);
+}
+
+/** ISO-8601 UTC at seconds precision, matching the chat-history stamp format. */
+export function iso_now(now: Date = new Date()): string {
+    return now.toISOString().replace(/\.\d{3}Z$/, '+00:00');
+}
+
+/** Parse an ISO stamp to epoch ms; `null` when unparseable. */
+function epoch_ms(stamp: string | null | undefined): number | null {
+    if (typeof stamp !== 'string' || stamp.length === 0) return null;
+    const ms = Date.parse(stamp);
+    return Number.isFinite(ms) ? ms : null;
+}
+
+/** True when `rec` has not been heard from within its own platform's TTL. */
+export function is_expired(rec: SessionRecord, now: Date = new Date()): boolean {
+    const seen = epoch_ms(rec.last_seen);
+    if (seen === null) return true; // unreadable stamp → not evidence of life
+    const age_s = (now.getTime() - seen) / 1000;
+    return age_s > ttl_seconds_for(rec.platform);
+}
+
+function is_record(v: unknown): v is SessionRecord {
+    if (typeof v !== 'object' || v === null) return false;
+    const o = v as Record<string, unknown>;
+    return typeof o['session_id'] === 'string' && typeof o['last_seen'] === 'string';
+}
+
+/**
+ * Write (or overwrite) this session's own record. Returns `true` on success.
+ * Never throws — a session that cannot write the register still starts.
+ */
+export function write_record(dir: string, rec: SessionRecord): boolean {
+    try {
+        const target = path.join(dir, `${safe_stem(rec.session_id)}.json`);
+        write_atomic(target, `${JSON.stringify(rec, null, 2)}\n`);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** Read this session's own record back, or `null` when it is absent/unreadable. */
+export function read_own_record(dir: string, session_id: string): SessionRecord | null {
+    try {
+        const target = path.join(dir, `${safe_stem(session_id)}.json`);
+        const parsed: unknown = JSON.parse(fs.readFileSync(target, 'utf-8'));
+        return is_record(parsed) ? parsed : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Remove this session's own record. Best-effort; a failure is not an error. */
+export function delete_record(dir: string, session_id: string): boolean {
+    try {
+        fs.unlinkSync(path.join(dir, `${safe_stem(session_id)}.json`));
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export interface ReadLiveOptions {
+    /** Unlink expired records as they are encountered. Default `false`. */
+    prune?: boolean;
+    /** Clock injection for tests. */
+    now?: Date;
+}
+
+/**
+ * Every live record in the register, optionally pruning expired ones as it goes.
+ *
+ * Expiry is evaluated per record against **its own** platform's TTL. A file that
+ * does not parse as a record is treated as expired: it carries no evidence of
+ * life, and leaving it would make the register grow without bound on a host that
+ * writes garbage.
+ *
+ * Returns `[]` on any failure — including "the directory does not exist", which
+ * is the normal state before the first session registers.
+ */
+export function read_live_records(dir: string, options: ReadLiveOptions = {}): SessionRecord[] {
+    const now = options.now ?? new Date();
+    const prune = options.prune === true;
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+    } catch {
+        return [];
+    }
+    const live: SessionRecord[] = [];
+    for (const name of names) {
+        const full = path.join(dir, name);
+        let rec: SessionRecord | null = null;
+        try {
+            const parsed: unknown = JSON.parse(fs.readFileSync(full, 'utf-8'));
+            rec = is_record(parsed) ? parsed : null;
+        } catch {
+            rec = null;
+        }
+        if (rec === null || is_expired(rec, now)) {
+            if (prune) {
+                try {
+                    fs.unlinkSync(full);
+                } catch {
+                    /* another session may have pruned it first — fine */
+                }
+            }
+            continue;
+        }
+        live.push(rec);
+    }
+    return live;
+}
+
+/**
+ * Live records belonging to sessions other than `session_id` — the set a
+ * starting session actually cares about.
+ */
+export function foreign_live_records(
+    dir: string,
+    session_id: string,
+    options: ReadLiveOptions = {},
+): SessionRecord[] {
+    const own = safe_stem(session_id);
+    return read_live_records(dir, options).filter((r) => safe_stem(r.session_id) !== own);
+}

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