@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/_lib/neighbour_scan.ts

@@ -0,0 +1,122 @@
+/**
+ * The shape scan a neighbour skill body passes before any of it may be indexed.
+ *
+ * SCAN BEFORE INJECT. A foreign `SKILL.md` is a file another package put on
+ * disk, and the ranker reaches it through the catalogue union. Nothing about
+ * being in `~/.claude/skills` makes its prose safe to fold into a term index
+ * whose output names skills to a model — the body is untrusted content in the
+ * sense `untrusted-input-defense` means it, and the floor here is the same one
+ * that rule states: it is data until something has looked at it.
+ *
+ * THE SHAPES ARE THE ONES THIS SUITE ALREADY SCANS ITS OWN CORPUS WITH. Four
+ * `security_lint` checks, reused as functions rather than re-implemented
+ * (decision D3 of the lane): instruction smuggling, hidden Unicode, mixed-script
+ * confusables and dangerous frontmatter. Re-declaring their patterns here would
+ * create a second copy to drift against the first, and the first is the one CI
+ * keeps honest.
+ *
+ * ANY FINDING REFUSES THE BODY — severity is NOT the discriminator. In the
+ * corpus linters, `HIGH` fails a build and `MED` warns, because the corpus is
+ * this package's own prose and a warning there is a maintainer's to weigh. A
+ * neighbour body is nobody's to weigh at rank time, and the cost of refusing is
+ * known and small: the skill still RANKS, by its name, with the finding kind
+ * printed. Risk-register row 4 is exactly this trade and resolves the same way —
+ * a shell snippet can be an installer skill's whole point, so the skill is never
+ * hidden, only un-indexed.
+ *
+ * WHY THIS IS NOT IMPORTED BY THE RANKER. It pulls four linter modules and,
+ * through one of them, `node:child_process`. The ranker runs inside the shared
+ * hook bundle on `user_prompt_submit`, where every byte is paid by every concern
+ * on every dispatch and `check_hook_bundle_composition` holds the ceiling. So
+ * the scan runs in the census CLI and its verdict reaches the ranker as a cached
+ * record — see `neighbour_census.scanVerdict`, where a missing record is a
+ * refusal rather than a pass.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as sl from './security_lint.js';
+import { fileDigest, type ScanCache, type ScanRecord } from './skill_origin.js';
+import { _scan as scanSmuggling } from '../lint_instruction_smuggling.js';
+import { _scan as scanHiddenUnicode } from '../lint_hidden_unicode.js';
+import { _scan as scanConfusables } from '../lint_confusables.js';
+import { _scan as scanFrontmatter } from '../lint_skill_frontmatter_safety.js';
+
+/** The shape checks, in the order their findings are reported. */
+const SHAPES: ReadonlyArray<readonly [string, (sf: sl.ScannedFile) => sl.Finding[]]> = [
+    ['instruction-smuggling', scanSmuggling],
+    ['dangerous-frontmatter', scanFrontmatter],
+    ['hidden-unicode', scanHiddenUnicode],
+    ['mixed-script-confusable', scanConfusables],
+];
+
+export interface ScanResult {
+    /** `null` when every shape passed; otherwise the first finding's check id. */
+    kind: string | null;
+    /** Every finding, for a report that wants more than the first kind. */
+    findings: sl.Finding[];
+}
+
+/**
+ * Scan one `SKILL.md`.
+ *
+ * An unreadable file is a refusal, not a pass (`unreadable`): a body nobody
+ * could open is in exactly the state this gate exists to keep out of the index,
+ * and returning `kind: null` for it would make an IO error look like a clean
+ * scan. A THROWING check is reported under its own id rather than swallowed, for
+ * the same reason.
+ */
+export function scanNeighbourBody(skillMdPath: string): ScanResult {
+    let sf: sl.ScannedFile;
+    try {
+        sf = sl.scan_file(skillMdPath);
+    } catch {
+        return { kind: 'unreadable', findings: [] };
+    }
+    const findings: sl.Finding[] = [];
+    for (const [id, scan] of SHAPES) {
+        try {
+            findings.push(...scan(sf));
+        } catch {
+            findings.push(
+                new sl.Finding(sf.rel, 0, id, 'HIGH', 'shape check threw on this body', 1.0),
+            );
+        }
+    }
+    return { kind: findings.length === 0 ? null : (findings[0] as sl.Finding).check, findings };
+}
+
+/**
+ * Record what the scan found, for the ranker to read on the hook path.
+ *
+ * The digest is the FILE's, not the finding's: the ranker re-digests the body it
+ * is about to index and compares, so a body edited after its scan reads as
+ * `digest-changed` and goes back to name-only ranking until the census runs
+ * again. That compare is the whole mechanism behind "a changed digest rescans
+ * first" — without it a one-time pass would keep clearing a file forever.
+ *
+ * A write failure is reported to the caller rather than thrown: the scan is
+ * correct either way, and a read-only report directory must not fail a census.
+ */
+export function writeScanCache(file: string, entries: readonly ScanRecord[]): boolean {
+    const payload: ScanCache = {
+        schema_version: 1,
+        entries: [...entries].sort((a, b) => (a.qualified < b.qualified ? -1 : 1)),
+    };
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** A `ScanRecord` for one file, digest included. */
+export function scanRecordFor(qualified: string, skillMdPath: string): ScanRecord {
+    return {
+        qualified,
+        digest: fileDigest(skillMdPath) ?? '',
+        unscanned: scanNeighbourBody(skillMdPath).kind,
+    };
+}

package/src/scripts/_lib/neighbour_tool_use.ts

@@ -0,0 +1,189 @@
+/**
+ * The foreign-MCP-tool-name store: one writer on the post-tool hook path, one
+ * reader in the neighbour census.
+ *
+ * WHY A MODULE OF ITS OWN, AND NOT A CONSTANT IN EITHER SIDE. The writer lives
+ * in `hooks/telemetry_usage_hook.ts`, which is inlined into the shared hook
+ * bundle `check_hook_bundle_composition` caps; the reader lives in
+ * `_lib/neighbour_census.ts`, which is not. Putting the pair here lets esbuild
+ * tree-shake {@link toolsUsedByServer} out of the hook bundle while both sides
+ * still name one path — a constant copied into two files is a store that
+ * silently splits in two the first time one copy is edited.
+ *
+ * WHAT IS RECORDED, AND WHAT IS NOT. One map of `mcp__<server>__<tool>` to the
+ * ISO date it was last seen. No arguments, no responses, no session id, no
+ * project path beyond the file's own location. The names recorded are names the
+ * consumer's own `.mcp.json` already lists, and the file is written under
+ * `agents/runtime/`, which is gitignored and local-only — nothing here is sent
+ * anywhere, and no transport reads it.
+ *
+ * NOT GATED ON THE TELEMETRY OPT-IN, DELIBERATELY. `telemetry_usage_hook`'s
+ * Class-A capture is default-off because it feeds an outbound spool. This store
+ * feeds `doctor neighbours`, a local report the consumer runs on their own tree.
+ * Gating it on an org telemetry switch would make the census print `0` on every
+ * install that never enabled one — a number that looks like a measurement and is
+ * an instrumentation artifact, which is the exact failure the usage hook's own
+ * header records from the collector it replaced.
+ *
+ * GROWTH, DECLARED (scale-discipline R-A7). The store is a map keyed by tool
+ * NAME, not an append log: one entry per distinct `mcp__…` name the consumer
+ * has ever called, each rewritten in place at most once per day. The bound is
+ * therefore the size of the neighbour's tool surface — tens of entries, not a
+ * series — so it needs no TTL job. The reader applies the window; entries older
+ * than it stay on disk and stop counting, which is why a stale entry is inert
+ * rather than wrong.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Host-side prefix of every MCP tool name: `mcp__<server>__<tool>`. */
+export const MCP_TOOL_PREFIX = 'mcp__';
+
+/**
+ * The store, relative to the project root. Gitignored; see the header.
+ *
+ * A literal with forward slashes rather than `path.join`, and the reason is
+ * measured rather than stylistic: `path.join` here is a top-level call, so the
+ * `node:path` namespace import survives into the hook bundle even though every
+ * function in this module that needs it is tree-shaken out of that bundle.
+ * `path.join(root, REL)` at each call site normalises the separator on Windows,
+ * so the only thing lost is the authoring convention.
+ */
+export const FOREIGN_TOOL_USE_REL = 'agents/runtime/neighbour-tool-use.json';
+
+/** The census window. 30 days, matching the step that asked for the number. */
+export const TOOL_USE_WINDOW_DAYS = 30;
+
+/** The filename the writer's root is the directory of. */
+const SETTINGS_FILENAME = '.agent-settings.yml';
+
+/** `YYYY-MM-DD` in UTC — the granularity the store keys on. */
+export function usageDay(now: Date): string {
+    return now.toISOString().slice(0, 10);
+}
+
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/u;
+
+/**
+ * Is this store value a day the window comparison can be trusted on?
+ *
+ * The comparison is lexicographic, which is exactly right for `YYYY-MM-DD` and
+ * quietly wrong for anything else: `'TODO'`, `'unknown'` and `'hand edited'`
+ * all sort ABOVE a real cutoff, so without this check a hand-edited or
+ * half-written store inflates the count instead of being ignored. The reader's
+ * promise is that a malformed store yields nothing, and a malformed VALUE is
+ * the likelier half of that.
+ */
+export function isUsageDay(value: unknown): value is string {
+    return typeof value === 'string' && DAY_RE.test(value);
+}
+
+/**
+ * The `.mcp.json` key as it appears inside a tool name.
+ *
+ * Hosts sanitise the key before embedding it — a server registered as
+ * `claude.ai Claude Docs` arrives as `mcp__claude_ai_Claude_Docs__…`. Normalising
+ * BOTH sides the same way is what keeps a matched count from quietly being a
+ * zero: an exact-key match would report `0` for every server whose name carries
+ * a dot or a space, which reads as "never used" rather than as "never matched".
+ */
+export function serverSegment(key: string): string {
+    return key.replace(/[^A-Za-z0-9_-]/gu, '_');
+}
+
+/**
+ * Does `tool` belong to the server whose sanitised key is `segment`?
+ *
+ * Driven by the KNOWN segment rather than by parsing the tool name, and that
+ * direction is the whole correctness argument. Parsing — split at the first
+ * `__` after the prefix — is ambiguous exactly where {@link serverSegment} is
+ * lossy: `Acme Inc. Tools` sanitises to `Acme_Inc__Tools`, whose own name
+ * contains the separator, so a parser reads the server as `Acme_Inc` and the
+ * census reports `0` for a server in daily use. That is the same never-matched
+ * zero `serverSegment` exists to prevent, reintroduced one layer down. Matching
+ * against the keys `.mcp.json` actually lists cannot be ambiguous, because the
+ * candidate set is finite and known.
+ */
+export function toolBelongsTo(tool: string, segment: string): boolean {
+    if (!tool.startsWith(MCP_TOOL_PREFIX)) return false;
+    const rest = tool.slice(MCP_TOOL_PREFIX.length);
+    return rest === segment || rest.startsWith(`${segment}__`);
+}
+
+/**
+ * The directory the store lives under, from any directory inside the project.
+ *
+ * The WRITER roots the store at the directory holding `.agent-settings.yml`
+ * (`telemetry_usage_hook.readSettingsFor`), because a session started in a
+ * subdirectory would otherwise scatter one store per directory it happened to
+ * start in. The reader has to resolve the same way or it looks in the wrong
+ * place: a monorepo with settings at the repo root and `.mcp.json` under
+ * `packages/web` would report `0` for a server in daily use. The two walks are
+ * pinned equal by a fixture rather than by assertion.
+ *
+ * No settings file on any ancestor → `start`, matching the writer's own
+ * fallback.
+ */
+export function resolveStoreRoot(start: string): string {
+    let dir = path.resolve(start);
+    for (;;) {
+        try {
+            if (fs.statSync(path.join(dir, SETTINGS_FILENAME)).isFile()) return dir;
+        } catch {
+            // Not here — keep walking.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) return path.resolve(start);
+        dir = parent;
+    }
+}
+
+/**
+ * Distinct tools seen per server inside the window, keyed by server segment.
+ *
+ * `segments` is the closed candidate set — the sanitised `.mcp.json` keys. Every
+ * one of them appears in the result, so a server with no sightings reads `0`
+ * rather than being absent. Longest segment wins where one is a prefix of
+ * another, so a tool is counted once.
+ *
+ * A missing, unreadable or malformed store yields all-zero — true of what was
+ * observed. It does not mean the server was unused, and the census says so next
+ * to the number.
+ */
+export function toolsUsedByServer(
+    projectRoot: string,
+    now: Date,
+    segments: Iterable<string>,
+): Map<string, number> {
+    const known = [...new Set(segments)].sort((a, b) => b.length - a.length);
+    const counts = new Map<string, number>(known.map((s) => [s, 0]));
+    if (known.length === 0) return counts;
+
+    let decoded: unknown;
+    try {
+        const root = resolveStoreRoot(projectRoot);
+        decoded = JSON.parse(fs.readFileSync(path.join(root, FOREIGN_TOOL_USE_REL), 'utf-8'));
+    } catch {
+        return counts;
+    }
+    if (typeof decoded !== 'object' || decoded === null || Array.isArray(decoded)) return counts;
+
+    const today = usageDay(now);
+    // Inclusive of both ends, so the span is WINDOW days and not WINDOW+1: a
+    // floor computed at `now - 30d` would count 31 distinct days under a field
+    // named `tools_used_30d`.
+    const floor = usageDay(new Date(now.getTime() - (TOOL_USE_WINDOW_DAYS - 1) * 86_400_000));
+
+    for (const [tool, seen] of Object.entries(decoded as Record<string, unknown>)) {
+        // A future date is as much a sign of a bad write as a malformed one,
+        // and without the upper bound a single `9999-01-01` counts forever.
+        if (!isUsageDay(seen) || seen < floor || seen > today) continue;
+        for (const segment of known) {
+            if (toolBelongsTo(tool, segment)) {
+                counts.set(segment, (counts.get(segment) ?? 0) + 1);
+                break;
+            }
+        }
+    }
+    return counts;
+}

package/src/scripts/_lib/prompt_shape.ts

@@ -41,6 +41,50 @@
  * over-filtering would silently stop pinning real prompts, which is worse.
  * Measured across 1 540 user-role entries: 509 open at character zero with a
  * marker, and in 0 of them does human text survive wrapper removal.
+ *
+ * `<agent-message` added 2026-10-03, by the same under-filtering it warns
+ * about: a subagent hand-back reaches this slot as `<agent-message from="…">`,
+ * and 12 of the 153 hook-sourced user records in this project's capture open
+ * with it. It pinned a German session to `en`, after which the turn-end gate
+ * refused each German reply — a reply language derived from a frame nobody
+ * typed. Its literal stops before the `>` because the element carries an
+ * attribute; the anchor at character zero is unchanged.
+ *
+ * **The fourth shape has NO envelope tag, and it is the exception this file's
+ * own "structural, not linguistic" rule has to name rather than quietly break.**
+ * The host resumes a rate-limited session with a plain sentence —
+ * `Your claude.ai usage limit has reset. Continue the task you were working
+ * on…` — carrying no element, no bracket and no stamp. 5 of the 153
+ * hook-sourced user records in this project's capture open with it. Measured
+ * 2026-10-03: it pinned a German session to `en` with `prompt_chars: 148`,
+ * which is that sentence's exact length, and every German reply for the rest
+ * of the run was then refused by the turn-end gate as wrong-language.
+ *
+ * Matching prose is what the paragraph above warns against, so what makes this
+ * one admissible is stated rather than assumed: it is a FIXED host string, not
+ * a linguistic pattern, and the character-zero anchor does the same work a tag
+ * would — a human asking *why did I get "Your claude.ai usage limit has
+ * reset"* does not open with it. A test pins that direction. If the host ever
+ * reworded the sentence this guard would silently stop matching, which is the
+ * honest failure mode: it under-filters back to today's behaviour rather than
+ * misfiring on a real turn.
+ *
+ * It is deliberately NOT added to `machine_wake.ts`. There the same
+ * misclassification retains an authorization instead of mis-pinning a reply,
+ * and a prose match is too weak a warrant for that consequence — see the
+ * asymmetry note below, which this is the first real test of.
+ *
+ * **A SECOND VOCABULARY ANSWERS THIS SAME QUESTION AND THE TWO HAVE DRIFTED.**
+ * `_lib/machine_wake.ts`'s `humanTypedThisTurn` guards per-turn STATE on this
+ * slot (the git-authorization ledger, the suggestion latch) while this one
+ * guards the language pin. As of this change both know `<task-notification>`,
+ * `<system-reminder>` and `<agent-message`; only this one knows
+ * `[SYSTEM NOTIFICATION` and `<local-command-caveat>`. That asymmetry is NOT
+ * obviously a defect and was deliberately left: mistaking a real turn for a
+ * machine one costs a mis-pinned reply here and a RETAINED AUTHORIZATION
+ * there, so the two sides do not want the same error budget — and
+ * `<local-command-caveat>` in particular precedes a real typed prompt. Unify
+ * them only with that asymmetry answered, never as tidying.
  */
 export function isSyntheticPrompt(prompt: string): boolean {
   const head = prompt.trimStart().slice(0, 400);
@@ -49,6 +93,8 @@ export function isSyntheticPrompt(prompt: string): boolean {
     head.startsWith("<task-notification>") ||
     head.startsWith("<system-reminder>") ||
     head.startsWith("<local-command-caveat>") ||
+    head.startsWith("<agent-message") ||
+    head.startsWith("Your claude.ai usage limit has reset") ||
     /^\[SYSTEM NOTIFICATION\b/.test(head)
   );
 }

package/src/scripts/_lib/release_migration_gate.ts

@@ -24,6 +24,7 @@ import * as path from 'node:path';
 import { REPO_ROOT } from '../release_env.js';
 import { die, run, type RunResult } from '../release_publication.js';
 import {
+    BREAKING_INDEX_PATH,
     MIGRATION_PATH as MAJOR_MIGRATION_PATH,
     pendingMajorFinding,
 } from '../lint_major_migration_sections.js';
@@ -148,8 +149,15 @@ export function assert_scheduled_deprecations_clear(
  * real run will refuse and returns, because `--dry-run exits 0` is a contract
  * this file's own tests assert.
  *
+ * A major owes TWO records and this seam reads both: the migration section and
+ * the by-major row in `BREAKING_CHANGES.md`. Checking only the first at cut
+ * time while the lint checks both would let a cut create the exact state the
+ * lint then reds `main` over — the gate arriving one merge too late, which is
+ * the shape `pendingMajorFinding` exists to avoid in the first place.
+ *
  * @param migrationReader Seam for the file read, so a test can drive the
  * refusal without mutating a tracked file.
+ * @param indexReader The same seam for the breaking-changes index.
  */
 export function assert_major_migration_section(
     target: string,
@@ -157,18 +165,23 @@ export function assert_major_migration_section(
     opts: { previewOnly?: boolean } = {},
     migrationReader: () => string = () =>
         fs.readFileSync(path.join(REPO_ROOT, MAJOR_MIGRATION_PATH), 'utf-8'),
+    indexReader: () => string = () =>
+        fs.readFileSync(path.join(REPO_ROOT, BREAKING_INDEX_PATH), 'utf-8'),
 ): void {
     let migration: string;
+    let index: string;
     try {
         migration = migrationReader();
+        index = indexReader();
     } catch (exc) {
         die(
-            `refusing the ${target} cut: cannot read ${MAJOR_MIGRATION_PATH} ` +
+            `refusing the ${target} cut: cannot read ${MAJOR_MIGRATION_PATH} or ` +
+                `${BREAKING_INDEX_PATH} ` +
                 `(${exc instanceof Error ? exc.message : String(exc)}). That is an environment ` +
                 'failure, not a finding — fix the checkout, then re-run.',
         );
     }
-    const finding = pendingMajorFinding(target, changelog_entry, migration);
+    const finding = pendingMajorFinding(target, changelog_entry, migration, index);
     if (finding === null) {
         return;
     }
@@ -180,5 +193,8 @@ export function assert_major_migration_section(
         );
         return;
     }
-    die(`refusing the ${target} cut: ${MAJOR_MIGRATION_PATH} has no section for ${target}.`);
+    die(
+        `refusing the ${target} cut: ${MAJOR_MIGRATION_PATH} or ${BREAKING_INDEX_PATH} ` +
+            `does not name ${target}.`,
+    );
 }

package/src/scripts/_lib/reserved_name_sweep.ts

@@ -0,0 +1,73 @@
+/**
+ * The reserved-name sweep over flat Claude Code command files.
+ *
+ * A flat command whose slug shadows a Claude Code built-in never ships on the
+ * claude-code anchor — the suite complements the host, it does not overlay its
+ * built-ins. The sweep that enforces this used to delete EVERY builtin-named
+ * `.md` in the anchor's `commands/` directory, including one another agent
+ * package or the consumer had put there. The consumer's own `/review` command
+ * disappeared at install time with no message, because the sweep's only
+ * question was the filename.
+ *
+ * The question it asks now is ownership: a file is removed when this package
+ * wrote it — the current deploy's own written set, or a path a previous
+ * install recorded in the installed-tools manifest. Anything else is FOREIGN:
+ * it stays on disk and is reported, so the consumer learns that a built-in
+ * name is shadowed by someone and can decide, rather than finding their file
+ * gone.
+ *
+ * Both halves of the sweep's original purpose survive: ours never ships under
+ * a reserved name, and the suite still never overlays a built-in with its own
+ * file. What it no longer does is enforce that on a file that is not its own.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface ReservedSweepResult {
+    /** Slugs of OUR files removed because the name is a host built-in. */
+    reserved: string[];
+    /** Slugs left in place because nothing proves this package wrote them. */
+    foreign: string[];
+}
+
+/**
+ * Remove our builtin-named flat commands from `commandsDir`; keep foreign ones.
+ *
+ * Both ownership sets are anchor-relative, exactly as the deploy inventory
+ * records them. `currentFiles` is this deploy's written set — the live half,
+ * and the only one that exists on a first install. `recordedFiles` is what a
+ * previous deploy recorded under the same anchor, so a builtin-named file of
+ * ours left behind by an older version is still reaped rather than becoming
+ * permanently unprovable. A removed entry is dropped from `currentFiles` so
+ * the inventory record stays consistent with the tree, exactly as before.
+ */
+export function sweepReservedNames(
+    commandsDir: string,
+    currentFiles: Set<string>,
+    isBuiltinName: (slug: string) => boolean,
+    recordedFiles: ReadonlySet<string>,
+): ReservedSweepResult {
+    const reserved: string[] = [];
+    const foreign: string[] = [];
+    let entries: string[] = [];
+    try {
+        entries = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md'));
+    } catch {
+        return { reserved, foreign };
+    }
+    for (const fname of entries.sort()) {
+        const slug = fname.slice(0, -'.md'.length);
+        if (!isBuiltinName(slug)) continue;
+        const rel = `commands/${fname}`;
+        const ours = currentFiles.has(rel) || recordedFiles.has(rel);
+        if (!ours) {
+            foreign.push(slug);
+            continue;
+        }
+        fs.rmSync(path.join(commandsDir, fname), { force: true });
+        currentFiles.delete(rel);
+        reserved.push(slug);
+    }
+    return { reserved, foreign };
+}

package/src/scripts/_lib/review_coverage.ts

@@ -0,0 +1,134 @@
+/**
+ * How much of a release the self-review actually read, stated where the record
+ * is read.
+ *
+ * `self_review_gate` writes a `coverage` block — `{chunks, filesReviewed,
+ * filesTotal, unreviewed[]}` — into the findings artifact, `--ingest` carries it
+ * into the per-release ledger named by {@link LEDGER_DIR}, and from there NOBODY
+ * reads `filesReviewed` back. The 16.2.0 ledger records `filesReviewed: 65,
+ * filesTotal: 678`: the review saw under a tenth of the change. Every consumer
+ * of that record — the disposition gate's success line, the release-highlights
+ * gate, a human opening the file — saw output that said nothing about it.
+ *
+ * A finding count over 9.6 % of a diff and the same count over all of it are
+ * different claims, and the record spelled them identically.
+ *
+ * A LABEL, NEVER A FLOOR, and the distinction is the decision.
+ *
+ * Nothing here refuses. `coverageLabel` returns a string or `null`; no caller
+ * turns it into an exit code, and none may. Raising what a review reads costs
+ * one more paid model request per chunk per cut, which is a spend decision
+ * belonging to the owner. A gate that failed a cut on partial coverage would
+ * force that decision through the back door — the operator would either pay or
+ * be unable to release — which is exactly the move the roadmap's decision D1
+ * records as rejected.
+ *
+ * The honest cost of that choice, stated rather than left to be discovered: a
+ * release can ship with 9.6 % coverage and this module will only have said so.
+ * Saying so is the whole claim.
+ *
+ * It lives in its own module because two consumers read it — `check_finding_dispositions` on the ledger and
+ * `check_release_highlights` beside the Known-limitations field — and a label
+ * the two spell differently is a label a reader cannot compare across the two
+ * places they meet it. One definition is also the seam the unit tests use, so
+ * the arithmetic is checked without either CLI in the loop.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Where the per-release ledgers live, relative to the repository root. */
+export const LEDGER_DIR = path.join('agents', 'evidence', 'release-findings');
+
+/**
+ * The coverage block as the gate writes it. Every field optional: this type
+ * describes an artifact read back off disk, which may be from an older writer
+ * or hand-edited, so the reader's job is to decide whether it can answer rather
+ * than to assume it can.
+ */
+export interface ReviewCoverage {
+    readonly chunks?: unknown;
+    readonly filesReviewed?: unknown;
+    readonly filesTotal?: unknown;
+    readonly unreviewed?: unknown;
+}
+
+function _finite(v: unknown): number | null {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
+/**
+ * The one sentence both gates print, or `null` when there is nothing to say.
+ *
+ * `null` covers three cases deliberately collapsed into one, because they lead
+ * to the same output: full coverage (nothing to warn about), an absent block (an
+ * older ledger, written before the gate recorded coverage), and a malformed one
+ * (a string where a number belongs, a zero total). A reader who sees no label
+ * learns "this record makes no partial-coverage claim" — which is true of all
+ * three — and never a fabricated percentage derived from a field that was not
+ * a number.
+ *
+ * `filesTotal === 0` is `null` rather than `0 of 0 (partial)`: a change set with
+ * no files was fully read by any definition, and dividing by it says nothing.
+ */
+export function coverageLabel(coverage: unknown): string | null {
+    if (coverage === null || typeof coverage !== 'object') {
+        return null;
+    }
+    const c = coverage as ReviewCoverage;
+    const reviewed = _finite(c.filesReviewed);
+    const total = _finite(c.filesTotal);
+    if (reviewed === null || total === null || total <= 0 || reviewed >= total) {
+        return null;
+    }
+    return `self-review read ${String(reviewed)} of ${String(total)} changed files (partial)`;
+}
+
+/**
+ * The `coverage` block of a committed ledger, or `undefined`.
+ *
+ * Never throws. A missing ledger is the normal state of an in-flight release and
+ * a corrupt one is already the business of the gate that parses it properly —
+ * a label is not the place to discover either, and a reader that threw here
+ * would turn an informational line into a crash on a release branch.
+ */
+export function readLedgerCoverage(root: string, release: string): unknown {
+    const file = path.join(root, LEDGER_DIR, `${release}.json`);
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object') {
+            return undefined;
+        }
+        return (parsed as Record<string, unknown>)['coverage'];
+    } catch {
+        return undefined;
+    }
+}
+
+/** `coverageLabel` over the committed ledger for `release`. */
+export function ledgerCoverageLabel(root: string, release: string): string | null {
+    return coverageLabel(readLedgerCoverage(root, release));
+}
+
+/**
+ * The same label as a Known-limitations line, for the release-highlights gate.
+ *
+ * It carries the label plus the sentence that keeps a reader from mistaking it
+ * for a refusal, because the field it prints beside is one the gate CAN refuse
+ * on. Without that sentence the next person to read the output reasonably
+ * concludes the gate is about to start failing cuts on coverage, and the cheapest
+ * way to make the message go away becomes raising the ceiling — which is the
+ * owner's spend decision, taken by whoever happened to read the line.
+ *
+ * Returns `null` when there is nothing to say, so the caller prints nothing
+ * rather than a reassuring sentence about a number it does not have.
+ */
+export function coverageLimitationNote(label: string | null): string | null {
+    if (label === null) {
+        return null;
+    }
+    return (
+        `ℹ️  ${label} — a limitation of the RECORD, not a verdict on the release. ` +
+        'Stated, never enforced:\n    what the review reads is a spend decision and this ' +
+        'gate does not take it.'
+    );
+}