@event4u/agent-config 9.26.0 → 9.27.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.26.0",
+    "version": "9.27.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/config/evaluator-budgets.json

@@ -58,11 +58,11 @@
       "deterministic": false
     },
     "cli_help_command_count": {
-      "max": 86,
-      "last_measured": 86,
-      "last_measured_at": "2026-08-06",
+      "max": 88,
+      "last_measured": 88,
+      "last_measured_at": "2026-08-07",
       "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. 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. 84 → 85 on 2026-08-05: the `settings:set` verb (road-to-zero-ceremony-settings Phase 2 — the one agent-reachable settings writer) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 85. 85 → 86 on 2026-08-06: the `conformance:behavior` verb (road-to-agent-behavior-conformance Phase 5 — replays the local transcript store through the four mechanised conformance checks) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 86."
+      "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. 84 → 85 on 2026-08-05: the `settings:set` verb (road-to-zero-ceremony-settings Phase 2 — the one agent-reachable settings writer) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 85. 85 → 86 on 2026-08-06: the `conformance:behavior` verb (road-to-agent-behavior-conformance Phase 5 — replays the local transcript store through the four mechanised conformance checks) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 86. 86 → 88 on 2026-08-07: the `sessions:list` + `sessions:claim` verbs (road-to-parallel-session-coordination — the shell surface of the shared session register, needed because /roadmap:next is command markdown and can only reach the register through a shell call) register in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 88."
     },
     "mcp_public_tool_count": {
       "max": 19,

package/src/scripts/_cli/cmd_doctor.ts

@@ -90,6 +90,7 @@ import * as installed_tools from '../_lib/installed_tools.js';
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
 import { censusDuplicateScope } from '../_lib/duplicate_scope_census.js';
+import { git_common_dir } from '../_lib/git_common_dir.js';
 import * as sync_gitattributes from '../sync_gitattributes.js';
 import {
     PROJECT_ROOT_ENV,
@@ -897,27 +898,11 @@ const _PLACEHOLDER_EMAIL_RE = /^(t@t\.t|.*@example\.(com|org)|.*@localhost)$/i;
 const _PLACEHOLDER_NAME_RE = /^(t|test|user|nobody|x)$/i;
 
 export function _git_config_path(project_root: string): string | null {
-    const gd = path.join(project_root, '.git');
-    try {
-        const st = fs.statSync(gd);
-        if (st.isDirectory()) {
-            return path.join(gd, 'config');
-        }
-        // Worktree: `.git` is a file "gitdir: <path>".
-        const m = readText(gd).match(/^gitdir:\s*(.+)\s*$/m);
-        if (m === null) {
-            return null;
-        }
-        const gdPath = path.resolve(project_root, m[1]!.trim());
-        const commondirFile = path.join(gdPath, 'commondir');
-        if (pathExists(commondirFile)) {
-            const common = path.resolve(gdPath, readText(commondirFile).trim());
-            return path.join(common, 'config');
-        }
-        return path.join(gdPath, 'config');
-    } catch {
-        return null;
-    }
+    // The `.git`-file / `commondir` walk this used to inline now lives in
+    // `_lib/git_common_dir.ts`, so the session register and this check cannot
+    // drift into two different answers to "where is the common dir".
+    const common = git_common_dir(project_root);
+    return common === null ? null : path.join(common, 'config');
 }
 
 function _parse_git_user(configText: string): { name: string | null; email: string | null } {

package/src/scripts/_dispatch.bash

@@ -177,6 +177,10 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              projection (from the pinned token baseline). Flags: --format
   code-graph                 Deterministic code-graph engine (ADR-124, Class A).
                              Usage: code-graph build|validate|detect|query|explain|affected|path [options]
+  sessions:list              List live agent sessions on this repository (shared
+                             session register). Flags: --json
+  sessions:claim             Claim a roadmap for this session so other sessions skip
+                             it; --release clears the claim
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
@@ -579,6 +583,18 @@ cmd_mcp_run() {
   exec_ts "$server_main" "$@"
 }
 
+# Shared session register (road-to-parallel-session-coordination). Resolved from
+# PACKAGE_ROOT, not the consumer projection: the CLI imports the register library
+# under src/scripts/_lib/, which is package-internal and never shipped into
+# dist/agent-src/scripts/. Same shape as cmd_settings_set.
+cmd_sessions_list() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/sessions_cli.ts" list "$@"
+}
+
+cmd_sessions_claim() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/sessions_cli.ts" claim "$@"
+}
+
 cmd_roadmap_progress() {
   local script
   script="$(resolve_script "dist/agent-src/scripts/update_roadmap_progress.ts" ".augment/scripts/update_roadmap_progress.ts")"
@@ -1252,6 +1268,8 @@ main() {
     benchmark)               cmd_benchmark "$@" ;;
     code-graph)              cmd_code_graph "$@" ;;
     conformance:behavior)    cmd_conformance_behavior "$@" ;;
+    sessions:list)           cmd_sessions_list "$@" ;;
+    sessions:claim)          cmd_sessions_claim "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;

package/src/scripts/_lib/git_common_dir.ts

@@ -0,0 +1,128 @@
+/**
+ * Resolve a repository's **common git directory** — the one directory every
+ * worktree of a repo shares.
+ *
+ * Extracted from `_cli/cmd_doctor.ts::_git_config_path`, which has resolved the
+ * `commondir` file this way since the git-identity check shipped. It is
+ * extracted rather than re-implemented on purpose: a repo with two different
+ * answers to "where is the common dir" is a bug waiting for a symlinked parent,
+ * and the worktree-cleanup work already hit that class once.
+ *
+ * ## Why this reads files instead of shelling out to git
+ *
+ * `git rev-parse --git-common-dir` is the obvious implementation and is wrong
+ * for the callers here, twice over:
+ *
+ * 1. **Inherited `GIT_DIR` overrides discovery.** Git hooks export `GIT_DIR`,
+ *    and every child inherits it, so `execFileSync('git', …, { cwd })` silently
+ *    resolves against the *hook's* repository rather than `cwd` — in a linked
+ *    worktree those differ, and the symptom is wrong data, not an error. That
+ *    is exactly what `_lib/git_env.ts` exists to strip. A file-based resolution
+ *    has nothing to override and needs no such guard.
+ * 2. **The raw output is not comparable across checkouts.** Measured
+ *    2026-08-07: from a main checkout `git rev-parse --git-common-dir` prints
+ *    the **relative** `.git`; from a linked worktree it prints an absolute
+ *    path. A consumer comparing the raw strings concludes the two checkouts
+ *    have different common dirs. Only the resolved realpath is a repo identity.
+ *
+ * ## Symlinked parents converge
+ *
+ * Measured on a throwaway repo reached both directly and through a symlinked
+ * ancestor: all four accesses (main / worktree × real / symlinked) resolve to
+ * the same directory, because the returned path is realpath-normalised here.
+ * This is the opposite of the worktree-cleanup finding that motivated the
+ * check — there realpath reporting caused a mis-classification; here it is the
+ * property that makes one shared register possible.
+ *
+ * Never throws: every caller treats "no common dir" as a reason to degrade,
+ * not as an error worth failing a hook over.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** `fs.realpathSync` that falls back to the input when the path is unreadable. */
+function realpath_or_self(p: string): string {
+    try {
+        return fs.realpathSync(p);
+    } catch {
+        return p;
+    }
+}
+
+/**
+ * The **per-worktree** git directory for `project_root` — `.git` in a plain
+ * checkout, the linked gitdir in a worktree. This is where `HEAD` lives, so it
+ * is the right anchor for "which branch is THIS checkout on", as opposed to
+ * `git_common_dir` which is deliberately shared across worktrees.
+ */
+export function git_dir(project_root: string): string | null {
+    const dot_git = path.join(project_root, '.git');
+    try {
+        const st = fs.statSync(dot_git);
+        if (st.isDirectory()) {
+            return realpath_or_self(dot_git);
+        }
+        const m = fs.readFileSync(dot_git, 'utf-8').match(/^gitdir:\s*(.+)\s*$/m);
+        if (m === null) {
+            return null;
+        }
+        return realpath_or_self(path.resolve(project_root, m[1]!.trim()));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Current branch name for `project_root`, or `null` on a detached HEAD or
+ * outside a repo.
+ *
+ * Reads `<git-dir>/HEAD` directly rather than shelling out, for the same reason
+ * as everything else in this module: hooks export `GIT_DIR`, and an inherited
+ * one silently redirects `git` to the wrong repository.
+ */
+export function current_branch(project_root: string): string | null {
+    const gd = git_dir(project_root);
+    if (gd === null) return null;
+    try {
+        const head = fs.readFileSync(path.join(gd, 'HEAD'), 'utf-8').trim();
+        const m = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+        return m === null ? null : m[1]!.trim();
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The common git directory for `project_root`, realpath-normalised, or `null`
+ * when `project_root` is not inside a git repository.
+ *
+ * - Plain checkout → `<project_root>/.git`.
+ * - Linked worktree → the `commondir` target of the worktree's gitdir, i.e. the
+ *   main checkout's `.git`, which is identical from every worktree of the repo.
+ * - Worktree gitdir without a `commondir` file → the gitdir itself (degenerate,
+ *   but the historical behaviour and not this change's to alter).
+ */
+export function git_common_dir(project_root: string): string | null {
+    const dot_git = path.join(project_root, '.git');
+    try {
+        const st = fs.statSync(dot_git);
+        if (st.isDirectory()) {
+            return realpath_or_self(dot_git);
+        }
+        // Linked worktree: `.git` is a FILE containing "gitdir: <path>".
+        const m = fs.readFileSync(dot_git, 'utf-8').match(/^gitdir:\s*(.+)\s*$/m);
+        if (m === null) {
+            return null;
+        }
+        const gitdir = path.resolve(project_root, m[1]!.trim());
+        const commondir_file = path.join(gitdir, 'commondir');
+        if (fs.existsSync(commondir_file)) {
+            const common = path.resolve(gitdir, fs.readFileSync(commondir_file, 'utf-8').trim());
+            return realpath_or_self(common);
+        }
+        return realpath_or_self(gitdir);
+    } catch {
+        return null;
+    }
+}

package/src/scripts/_lib/obligation_frequency.ts

@@ -0,0 +1,391 @@
+/**
+ * Obligation frequency, carrier frequency, and the coverage lattice between them.
+ *
+ * `enforced_by` answers *does something carry this rule*. It does not answer
+ * *does it carry it often enough*, and the difference is not academic:
+ * `session-canary` declares `hook:session-canary`, the hook exists, is wired and
+ * fires — so the coverage instrument counts the rule as enforced — while the hook
+ * sits in the `session_start` slot and the rule's obligation is per task. The
+ * rule's own 30-session audit measured the opening canary dropped on ~13 of 15
+ * task starts. Enforced on paper, broken in fact.
+ *
+ * This module supplies the missing half: a declared obligation period per rule
+ * (frontmatter `obligation_frequency`), a carrier period resolved per slot AND
+ * per platform, and a `covers()` relation that is honest about the two ways the
+ * intuitive linear ordering produces FALSE GREENS.
+ *
+ * ## The value set is a forest, not a chain
+ *
+ * Four roots. A carrier in one root never covers an obligation in another:
+ *
+ *   lifecycle       per-turn ⊃ per-task ⊃ per-session
+ *   tool-call       per-edit ⊃ per-file-write
+ *   repository      per-commit
+ *   external-event  per-event
+ *
+ * Two corrections that a magnitude-ordered chain would get wrong:
+ *
+ *  - `per-edit` and `per-turn` are INCOMPARABLE. `pre_tool_use`/`post_tool_use`
+ *    fire per tool call, so a plain conversational reply fires them zero times.
+ *    A per-turn obligation carried only by a per-edit hook is uncovered on
+ *    exactly those turns — and a chain would paint that green.
+ *  - `per-event` is a SEPARATE ROOT, not the bottom of the lifecycle chain. An
+ *    external event fires on its own clock: a CI gate firing three times inside
+ *    one session is not covered by a `session_start` check, yet a chain with
+ *    `per-event` at the bottom would accept the session-scoped carrier as
+ *    dominating it and report green.
+ *
+ * ## Point carriers vs sweep carriers — the third correction
+ *
+ * The forest rule above is stated for carriers that fire AT an event and see
+ * only that event: a hook. A CI validator is not that shape. It fires once per
+ * commit and inspects the whole tree, so it catches every edit inside the commit
+ * regardless of how many there were. Treating it as a `per-commit` point carrier
+ * would make every `validator:`-carried rule with a per-edit obligation a
+ * finding — roughly a fifth of the declared corpus at once, all from one
+ * modelling error, which is precisely the unusable-first-run failure this audit
+ * must avoid.
+ *
+ * So carriers have a MODE. A `sweep` carrier covers any obligation whose
+ * violations land in a durable artefact (`per-edit`, `per-file-write`,
+ * `per-commit`). It covers none of the transient ones (`per-turn`, `per-task`,
+ * `per-session`, `per-event`), because a reply's language, a greeting, or a
+ * fetched-content decision leaves nothing in the tree for a sweep to read.
+ */
+
+// ------------------------------------------------------------------ vocabulary
+
+export type Frequency =
+    | 'per-edit'
+    | 'per-turn'
+    | 'per-task'
+    | 'per-session'
+    | 'per-event'
+    | 'per-commit'
+    | 'per-file-write'
+    | 'none';
+
+export const FREQUENCIES: readonly Frequency[] = [
+    'per-edit',
+    'per-turn',
+    'per-task',
+    'per-session',
+    'per-event',
+    'per-commit',
+    'per-file-write',
+    'none',
+] as const;
+
+export function is_frequency(v: unknown): v is Frequency {
+    return typeof v === 'string' && (FREQUENCIES as readonly string[]).includes(v);
+}
+
+export type Root = 'lifecycle' | 'tool-call' | 'repository' | 'external-event' | 'none';
+
+const ROOT_OF: Record<Frequency, Root> = {
+    'per-turn': 'lifecycle',
+    'per-task': 'lifecycle',
+    'per-session': 'lifecycle',
+    'per-edit': 'tool-call',
+    'per-file-write': 'tool-call',
+    'per-commit': 'repository',
+    'per-event': 'external-event',
+    none: 'none',
+};
+
+/**
+ * Cross-root coverage that IS real, enumerated rather than inferred.
+ *
+ * `per-commit` keeps its own root because it is not a lifecycle event — a
+ * `--fixup` during a rebase has no preceding user turn, so no lifecycle carrier
+ * covers it. But in an agent runtime every commit the agent makes is issued
+ * through a tool call, so a point carrier in the tool-call root DOES observe it:
+ * `block-no-verify` sits in `pre_tool_use` and inspects the very `git commit`
+ * command. Refusing that edge on a tidy root rule would report the commit guard
+ * as failing to carry the commit rule, which is the opposite of true.
+ *
+ * The relation is one-directional. A per-commit carrier does not cover a
+ * per-edit obligation: one commit can hold twenty edits, and a point carrier at
+ * the commit sees the command, not each edit that preceded it.
+ */
+const CROSS_ROOT_COVERAGE: ReadonlyArray<readonly [Frequency, Frequency]> = [
+    ['per-edit', 'per-commit'],
+];
+
+export function root_of(f: Frequency): Root {
+    return ROOT_OF[f];
+}
+
+/**
+ * Within-root inclusion depth: a SMALLER number fires more often, so it is a
+ * superset of every larger number in the same root. Cross-root comparison is
+ * rejected before this table is consulted.
+ */
+const DEPTH: Record<Frequency, number> = {
+    'per-turn': 0,
+    'per-task': 1,
+    'per-session': 2,
+    'per-edit': 0,
+    'per-file-write': 1,
+    'per-commit': 0,
+    'per-event': 0,
+    none: 0,
+};
+
+// -------------------------------------------------------------------- carriers
+
+/**
+ * How a carrier observes the world.
+ *
+ * `point` — fires at an event and sees that event (a hook).
+ * `sweep` — fires once and inspects the whole artefact tree (a CI validator, a
+ *           test suite). Its reach is bounded by what lands in the tree, not by
+ *           how often it runs.
+ */
+export type CarrierMode = 'point' | 'sweep';
+
+/** Obligations whose violations leave a durable trace a sweep can read. */
+const SWEEPABLE: ReadonlySet<Frequency> = new Set<Frequency>([
+    'per-edit',
+    'per-file-write',
+    'per-commit',
+]);
+
+/**
+ * Does `carrier` cover `obligation`?
+ *
+ * An obligation of `none` is covered vacuously — there is nothing recurring to
+ * carry, which is what `none` means. Everything else is decided by mode first,
+ * then root, then within-root depth.
+ */
+export function covers(
+    carrier: { frequency: Frequency; mode: CarrierMode },
+    obligation: Frequency,
+): boolean {
+    if (obligation === 'none') return true;
+    if (carrier.mode === 'sweep') return SWEEPABLE.has(obligation);
+    if (carrier.frequency === 'none') return false;
+    if (CROSS_ROOT_COVERAGE.some(([c, o]) => c === carrier.frequency && o === obligation)) {
+        return true;
+    }
+    if (ROOT_OF[carrier.frequency] !== ROOT_OF[obligation]) return false;
+    return DEPTH[carrier.frequency] <= DEPTH[obligation];
+}
+
+/** True when ANY of a carrier's firing periods covers the obligation. */
+export function covers_any(frequencies: readonly Frequency[], obligation: Frequency): boolean {
+    return frequencies.some((f) => covers({ frequency: f, mode: 'point' }, obligation));
+}
+
+// ------------------------------------------------------------- the decay guard
+
+/**
+ * Prose signals that suggest a period, keyed to the value they suggest.
+ *
+ * A declared value can be right the day it is written and wrong two edits later,
+ * and nothing in the join notices — the field would then be a stale claim
+ * wearing a schema. This heuristic reads the rule's own prose and reports when
+ * it demands a TIGHTER period than the frontmatter declares.
+ *
+ * Deliberately one-directional. Prose looser than the declaration is not a
+ * finding: a rule may state a per-session cache and still carry a per-turn
+ * obligation elsewhere in its body, and flagging that would fire on most of the
+ * corpus. Prose demanding MORE often than declared is the direction where the
+ * join silently over-credits a carrier.
+ */
+const PROSE_SIGNALS: ReadonlyArray<readonly [Frequency, RegExp]> = [
+    ['per-turn', /\b(every|each) (reply|turn|answer|response)\b/i],
+    ['per-turn', /\bper (reply|turn)\b/i],
+    ['per-task', /\b(every|each) (new )?task\b/i],
+    ['per-edit', /\bafter every (code )?edit\b/i],
+    ['per-edit', /\b(every|each) edit\b/i],
+    ['per-commit', /\b(in the )?same commit\b/i],
+    ['per-commit', /\b(every|each) commit\b/i],
+];
+
+/**
+ * Frequencies the prose demands but the declared value does not cover.
+ *
+ * Empty is the passing answer. A non-empty result is a WARNING — the heuristic
+ * is a keyword match over prose and will be noisy, so it never fails a build;
+ * an audited mismatch is silenced with an explicit `# frequency-override:`
+ * comment, which makes a suppression a decision someone signed rather than
+ * silence.
+ */
+export function frequency_prose_conflicts(body: string, declared: Frequency): Frequency[] {
+    const out: Frequency[] = [];
+    for (const [freq, re] of PROSE_SIGNALS) {
+        if (!re.test(body)) continue;
+        if (covers({ frequency: declared, mode: 'point' }, freq)) continue;
+        if (!out.includes(freq)) out.push(freq);
+    }
+    return out;
+}
+
+/** True when the file carries an audited `# frequency-override: <reason>` note. */
+export function has_frequency_override(text: string): boolean {
+    return /^#\s*frequency-override:\s*\S/m.test(text);
+}
+
+// --------------------------------------------------------- slot × platform map
+
+export type Slot =
+    | 'session_start'
+    | 'session_end'
+    | 'stop'
+    | 'user_prompt_submit'
+    | 'pre_tool_use'
+    | 'post_tool_use';
+
+/**
+ * Default firing period per slot, before per-platform native-event corrections.
+ *
+ * `stop` is per-turn, NOT session end. On Claude Code the native `Stop` event
+ * fires after every assistant reply — `hook_manifest.yaml` says so itself,
+ * describing the `stop` write as a "deterministic … overwrite of hot-context.md",
+ * i.e. a working-memory refresh per reply. True session end is the separate
+ * `session_end` slot.
+ */
+const SLOT_FREQUENCY_DEFAULT: Record<Slot, Frequency> = {
+    session_start: 'per-session',
+    session_end: 'per-session',
+    stop: 'per-turn',
+    user_prompt_submit: 'per-turn',
+    pre_tool_use: 'per-edit',
+    post_tool_use: 'per-edit',
+};
+
+/**
+ * Per-platform overrides where the native event a slot is mapped from means
+ * something other than the default.
+ *
+ * Cline maps `stop` from `TaskCancel` — the session is interrupted with partial
+ * state (`hook_manifest.yaml`: "TaskCancel maps to stop because the session is
+ * interrupted with partial state"). That is an interruption on its own clock,
+ * not a per-reply beat, so it belongs to the external-event root and covers no
+ * lifecycle obligation. Collapsing it into per-turn is the semantic type error
+ * a one-dimensional slot→frequency table cannot express.
+ */
+const SLOT_FREQUENCY_OVERRIDE: Record<string, Partial<Record<Slot, Frequency>>> = {
+    cline: { stop: 'per-event' },
+};
+
+export function slot_frequency(platform: string, slot: Slot): Frequency {
+    return SLOT_FREQUENCY_OVERRIDE[platform]?.[slot] ?? SLOT_FREQUENCY_DEFAULT[slot];
+}
+
+/**
+ * Platforms with no hook surface at all.
+ *
+ * Copilot declares `fallback_only: true` in the manifest — concerns route
+ * through rule-only fallback and the dispatcher no-ops. Every hook-declared
+ * carrier fires zero times there, for every rule equally. Including it in the
+ * join would turn one structural fact into a finding on every hook-carried rule
+ * at once, which reports a platform property as if it were a per-rule defect.
+ * It is excluded by declaration, and the exclusion is named in the report rather
+ * than hidden.
+ */
+export function is_hook_capable(platform_block: Record<string, unknown>): boolean {
+    return platform_block['fallback_only'] !== true;
+}
+
+// ------------------------------------------------- hook manifest platform read
+
+export interface PlatformBinding {
+    /** Platform id → slot → concern ids bound in that slot. */
+    slots: Map<string, Map<Slot, string[]>>;
+    /** Platform ids that carry no hook surface at all. */
+    fallback_only: Set<string>;
+}
+
+const SLOT_NAMES: ReadonlySet<string> = new Set<string>([
+    'session_start',
+    'session_end',
+    'stop',
+    'user_prompt_submit',
+    'pre_tool_use',
+    'post_tool_use',
+]);
+
+/**
+ * Read the `platforms:` block of `hook_manifest.yaml`.
+ *
+ * A narrow reader, matching the one `check_enforcement_coverage.parse_hook_manifest`
+ * already uses for `concerns:` — the block is a fixed two-level shape
+ * (`platform: slot: [concern, …]`) and the only facts needed are slot membership
+ * and the `fallback_only` sentinel. Deliberately NOT a second YAML dependency.
+ */
+export function parse_hook_platforms(text: string): PlatformBinding {
+    const slots = new Map<string, Map<Slot, string[]>>();
+    const fallback_only = new Set<string>();
+    let in_platforms = false;
+    let current: string | null = null;
+
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (/^platforms:\s*$/.test(line)) {
+            in_platforms = true;
+            continue;
+        }
+        if (!in_platforms) continue;
+        if (/^\S/.test(line)) break; // left the platforms block
+        if (line.trim() === '' || /^\s*#/.test(line)) continue;
+
+        const platform = /^ {2}([a-z0-9_-]+):\s*$/.exec(line)?.[1];
+        if (platform !== undefined) {
+            current = platform;
+            slots.set(current, new Map());
+            continue;
+        }
+        if (current === null) continue;
+
+        if (/^\s+fallback_only:\s*true\s*$/.test(line)) {
+            fallback_only.add(current);
+            continue;
+        }
+        const m = /^\s+([a-z_]+):\s*\[(.*)\]\s*$/.exec(line);
+        if (m === null) continue;
+        const slot = m[1] as string;
+        if (!SLOT_NAMES.has(slot)) continue;
+        const concerns = (m[2] as string)
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        slots.get(current)?.set(slot as Slot, concerns);
+    }
+    return { slots, fallback_only };
+}
+
+/**
+ * Resolve, per platform, EVERY period at which `concern` fires — a set, never a
+ * scalar.
+ *
+ * A concern bound in more than one slot fires at the UNION of their periods, and
+ * those periods can sit in different roots: `minimal-safe-diff` is bound in
+ * `session_start` (per-session), `user_prompt_submit` (per-turn) AND
+ * `post_tool_use` (per-edit). Collapsing that to one "strongest" value has no
+ * correct answer, because per-turn and per-edit are incomparable by
+ * construction — and picking either drops a root the carrier really does cover.
+ * Doing so reported `minimal-safe-diff` as failing to carry its own per-edit
+ * obligation while a post_tool_use binding was sitting right there.
+ *
+ * An empty array means the concern is bound in no slot on that platform, which
+ * is a distinct answer from any frequency and must not be collapsed into one.
+ */
+export function carrier_frequency_by_platform(
+    concern: string,
+    binding: PlatformBinding,
+): Record<string, Frequency[]> {
+    const out: Record<string, Frequency[]> = {};
+    for (const [platform, slot_map] of binding.slots) {
+        if (binding.fallback_only.has(platform)) continue; // named in the report, not joined
+        const found: Frequency[] = [];
+        for (const [slot, concerns] of slot_map) {
+            if (!concerns.includes(concern)) continue;
+            const f = slot_frequency(platform, slot);
+            if (!found.includes(f)) found.push(f);
+        }
+        out[platform] = found;
+    }
+    return out;
+}