@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/_lib/ratification_artifact.ts

@@ -96,10 +96,227 @@ export interface RatificationProblem {
         | 'no-providers'
         | 'diversity-required'
         | 'diversity-unverifiable'
-        | 'bad-effective-after';
+        | 'bad-effective-after'
+        | 'no-seats'
+        | 'malformed-seats'
+        | 'bad-seat-provider'
+        | 'unknown-seat-verdict'
+        | 'seat-dissent'
+        | 'providers-exceed-seats'
+        | 'header-not-derived';
     message: string;
 }
 
+/** A seat that closed, timed out or was absent at the last round gave no final verdict. */
+export const SEAT_NO_FINAL_VERDICT = 'no-final-verdict';
+export type SeatVerdict = RatificationVerdict | typeof SEAT_NO_FINAL_VERDICT;
+/** Every value a seat's final verdict may take — shared by the writer and the reader. */
+export const SEAT_VERDICTS: readonly string[] = [...RATIFICATION_VERDICTS, SEAT_NO_FINAL_VERDICT];
+
+/**
+ * A provider id as a seat key: lower-case, no whitespace and no YAML
+ * metacharacter, so a rendered header cannot be split or extended by a name
+ * and two spellings of one provider cannot collide after normalisation.
+ */
+export const SEAT_PROVIDER_RE = /^[a-z0-9][a-z0-9._-]*$/u;
+
+export type SeatsReading =
+    | { kind: 'absent' }
+    | { kind: 'invalid'; problems: RatificationProblem[] }
+    | { kind: 'present'; seats: Map<string, SeatVerdict> };
+
+/**
+ * The `seats:` map — provider id to that seat's FINAL verdict — in source
+ * order, which is the order `providers` is derived in.
+ *
+ * Absent and present-but-unusable are reported apart: a missing key and a
+ * `seats:` key that is empty, a scalar, a list, or carries a bad id or verdict
+ * are both refusals, with different codes.
+ */
+export function readSeats(fm: AdrFrontmatter, text = ''): SeatsReading {
+    const duplicates = duplicateSeatKeys(text);
+    if (duplicates.length > 0) {
+        return {
+            kind: 'invalid',
+            problems: [
+                {
+                    code: 'bad-seat-provider',
+                    message: `seat \`${duplicates.join('`, `')}\` is recorded more than once — the parser keeps only the last`,
+                },
+            ],
+        };
+    }
+    const hasScalar = Object.prototype.hasOwnProperty.call(fm.scalars, 'seats');
+    const node = fm.nested['seats'];
+    if (node === undefined && !hasScalar) {
+        return { kind: 'absent' };
+    }
+    if (node === undefined || typeof node === 'string' || Array.isArray(node)) {
+        return {
+            kind: 'invalid',
+            problems: [{ code: 'malformed-seats', message: '`seats:` is present but is not a provider-to-verdict map' }],
+        };
+    }
+    const problems: RatificationProblem[] = [];
+    const seats = new Map<string, SeatVerdict>();
+    for (const [provider, verdict] of Object.entries(node)) {
+        if (!SEAT_PROVIDER_RE.test(provider)) {
+            problems.push({
+                code: 'bad-seat-provider',
+                message: `seat key \`${provider}\` is not a provider id (${String(SEAT_PROVIDER_RE)})`,
+            });
+            continue;
+        }
+        if (typeof verdict !== 'string' || !SEAT_VERDICTS.includes(verdict.trim())) {
+            problems.push({
+                code: 'unknown-seat-verdict',
+                message: `seat \`${provider}\` records \`${String(verdict)}\`, not one of ${SEAT_VERDICTS.join(', ')}`,
+            });
+            continue;
+        }
+        seats.set(provider, verdict.trim() as SeatVerdict);
+    }
+    if (problems.length === 0 && seats.size === 0) {
+        problems.push({ code: 'malformed-seats', message: '`seats:` is present and empty' });
+    }
+    return problems.length > 0 ? { kind: 'invalid', problems } : { kind: 'present', seats };
+}
+
+/** Keys repeated inside the frontmatter `seats:` block, read from the raw text. */
+function duplicateSeatKeys(text: string): string[] {
+    if (!text.startsWith('---\n')) return [];
+    const end = text.indexOf('\n---\n', 4);
+    const lines = text.slice(4, end === -1 ? undefined : end).split('\n');
+    const start = lines.findIndex((l) => /^seats:\s*$/u.test(l));
+    if (start === -1) return [];
+    const seen = new Set<string>();
+    const dup = new Set<string>();
+    for (const line of lines.slice(start + 1)) {
+        if (!/^\s/u.test(line)) break;
+        // Compared by the identity a YAML parser would give the key, so a quoted
+        // spelling cannot hide a second entry for the same seat.
+        const key = line
+            .slice(0, line.indexOf(':') === -1 ? undefined : line.indexOf(':'))
+            .trim()
+            .replace(/^(["'])(.*)\1$/u, '$2')
+            .trim();
+        if (key === '' || key.startsWith('#')) continue;
+        if (seen.has(key)) dup.add(key);
+        seen.add(key);
+    }
+    return [...dup];
+}
+
+/**
+ * The header a set of seat verdicts supports, and no more.
+ *
+ * `providers` is every seat that gave a final verdict — a closed seat is not a
+ * provider the verdict came from. Any refusing seat makes the verdict `refused`,
+ * any non-convergent one `non-convergent`; only when every final seat passed is
+ * the verdict passing, and then `ratified` if any seat said so. No final seat at
+ * all is `non-convergent`: a review that ended without a verdict did not pass.
+ */
+export function deriveRatificationHeader(
+    seats: ReadonlyMap<string, SeatVerdict> | Readonly<Record<string, SeatVerdict>>,
+): { providers: string[]; verdict: RatificationVerdict } {
+    const entries = seats instanceof Map ? [...seats.entries()] : Object.entries(seats);
+    const final = entries.filter(([, v]) => v !== SEAT_NO_FINAL_VERDICT) as [string, RatificationVerdict][];
+    const verdicts = final.map(([, v]) => v);
+    let verdict: RatificationVerdict;
+    if (verdicts.includes('refused')) {
+        verdict = 'refused';
+    } else if (final.length === 0 || verdicts.includes('non-convergent')) {
+        verdict = 'non-convergent';
+    } else {
+        verdict = verdicts.includes('ratified') ? 'ratified' : 'confirmed-non-expanding';
+    }
+    return { providers: final.map(([p]) => p), verdict };
+}
+
+/**
+ * The `providers:`, `verdict:` and `seats:` frontmatter lines, derived — never
+ * typed. Throws on a provider id outside {@link SEAT_PROVIDER_RE}: a name that
+ * could carry YAML syntax is refused rather than escaped.
+ */
+export function renderRatificationHeader(
+    seats: ReadonlyMap<string, SeatVerdict> | Readonly<Record<string, SeatVerdict>>,
+): string {
+    const entries = seats instanceof Map ? [...seats.entries()] : Object.entries(seats);
+    for (const [p, v] of entries) {
+        if (!SEAT_PROVIDER_RE.test(p)) throw new Error(`not a provider id: ${JSON.stringify(p)}`);
+        if (!SEAT_VERDICTS.includes(v)) throw new Error(`not a seat verdict: ${JSON.stringify(v)}`);
+    }
+    const { providers, verdict } = deriveRatificationHeader(seats);
+    return [
+        `providers: [${providers.join(', ')}]`,
+        `verdict: ${verdict}`,
+        'seats:',
+        ...entries.map(([p, v]) => `  ${p}: ${v}`),
+    ].join('\n');
+}
+
+/**
+ * The header claims the seats do not support.
+ *
+ * `seats:` is required. Optional, it left `providers` and `verdict` free-written
+ * for every author who omitted it, which is the defect it exists to close; the
+ * round-2 ratification review refused that shape. The gate reads only the
+ * artifacts in the diff under review, so an artifact merged before the field
+ * existed is never re-read and needs no migration to stay valid.
+ *
+ * The recorded header must EQUAL the derived one; the two named overclaims get
+ * their own codes so a reader sees which one it was.
+ */
+function seatProblems(reading: SeatsReading, providers: readonly string[], verdict: string | null): RatificationProblem[] {
+    if (reading.kind === 'absent') {
+        return [
+            {
+                code: 'no-seats',
+                message:
+                    'missing `seats:` — `providers` and `verdict` are derived from the per-seat final ' +
+                    'verdicts, never typed (print all three with `ratification_header`)',
+            },
+        ];
+    }
+    if (reading.kind === 'invalid') return reading.problems;
+    const seats = reading.seats;
+    const problems: RatificationProblem[] = [];
+    if (verdict !== null && PASSING_VERDICTS.has(verdict)) {
+        const dissent = [...seats].filter(([, v]) => v === 'refused' || v === 'non-convergent');
+        if (dissent.length > 0) {
+            problems.push({
+                code: 'seat-dissent',
+                message:
+                    `verdict \`${verdict}\` while ${dissent.map(([p, v]) => `${p} was \`${v}\``).join(', ')} ` +
+                    'at the final round — a header cannot say more than its seats said',
+            });
+        }
+    }
+    const derived = deriveRatificationHeader(seats);
+    const extra = providers.filter((p) => !derived.providers.includes(p));
+    if (extra.length > 0) {
+        problems.push({
+            code: 'providers-exceed-seats',
+            message:
+                `providers names ${extra.join(', ')}, which gave no final verdict ` +
+                `(${String(derived.providers.length)} seat(s) did) — diversity is counted over seats that answered`,
+        });
+    }
+    if (
+        problems.length === 0 &&
+        (verdict !== derived.verdict || providers.join('\u0000') !== derived.providers.join('\u0000'))
+    ) {
+        problems.push({
+            code: 'header-not-derived',
+            message:
+                `recorded providers [${providers.join(', ')}] / verdict \`${String(verdict)}\` differ from the ` +
+                `header the seats derive: [${derived.providers.join(', ')}] / \`${derived.verdict}\` ` +
+                '(print it with `ratification_header`)',
+        });
+    }
+    return problems;
+}
+
 export interface RatificationReading {
     artifact: RatificationArtifact | null;
     problems: RatificationProblem[];
@@ -208,6 +425,8 @@ export function readRatification(
         }
     }
 
+    problems.push(...seatProblems(readSeats(fm, text), providers, verdict));
+
     // Diversity, against the REQUIRED count.
     //
     // Round 1 refused the previous shape: the count came from the user-global

package/src/scripts/_lib/ratification_subject.ts

@@ -0,0 +1,92 @@
+/**
+ * ratification_subject — the digest a ratification record carries over the
+ * gated content it reviewed.
+ *
+ * `road-to-self-modification-that-a-council-must-pass` step 2.1, the half that
+ * does not touch the gate. The record says WHO reviewed; without a digest it
+ * does not say WHAT, so a gated file edited after its review still ships under
+ * a record that approved something else.
+ *
+ * WHY IT RE-ASSEMBLES THE LIST RATHER THAN RE-DECIDING IT. The gate's
+ * `classifyPaths` returns the kernel rules, hooks and plumbing by name but
+ * reports the self surface as a BOOLEAN, so the gated list cannot be read back
+ * out of it. This module therefore imports the gate's own path constants and
+ * re-assembles — it never restates the membership rule, because a second
+ * definition of "gated" is a second thing to keep in step, and the first time
+ * the two diverged a file would be reviewed by one and digested by the other.
+ *
+ * NO BASE DIFF. The digest is over the tree as it stands, so it is the same on
+ * a branch and on the merged checkout CI judges — unless the base changed a
+ * gated file the change also touches, and then the content that would land is
+ * not the content that was reviewed, which is precisely what should move it.
+ */
+
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    ANCHOR_PATHS,
+    CLOSURE_READER_PATH,
+    POLICY_PATH,
+    READER_PATH,
+    SELF_PATH,
+    WORKFLOW_PATH,
+    classifyPaths,
+} from '../check_kernel_edit_ratified.js';
+
+/**
+ * Stands in for the content of a gated file the change deletes. A deleted file
+ * is ENTERED, never skipped: skipping would make "this file was removed"
+ * digest-identical to "this file was never gated", and removing a governance
+ * hook is exactly the change the record most needs to be bound to.
+ */
+export const DELETED_MARKER = '\u0000deleted\u0000';
+
+/** The self surface, by the gate's own constants rather than a copy of them. */
+const SELF_SET: ReadonlySet<string> = new Set<string>([
+    SELF_PATH,
+    READER_PATH,
+    CLOSURE_READER_PATH,
+    POLICY_PATH,
+    WORKFLOW_PATH,
+    ...ANCHOR_PATHS,
+]);
+
+/**
+ * The gated subset of a changed-file list: sorted, deduplicated, and stable
+ * against the order the caller happened to collect the paths in.
+ */
+export function gatedFilesOf(
+    files: readonly string[],
+    derived?: readonly string[],
+): readonly string[] {
+    const normalized = files.map((f) => f.replace(/\\/g, '/').trim()).filter((f) => f !== '');
+    const g = derived === undefined ? classifyPaths(normalized) : classifyPaths(normalized, derived);
+    const out = new Set<string>([...g.kernelRules, ...g.governanceHooks, ...g.plumbing]);
+    for (const f of normalized) {
+        if (SELF_SET.has(f)) out.add(f);
+    }
+    return [...out].sort();
+}
+
+/**
+ * One digest over the sorted paths AND contents of the gated files, read from
+ * `root`.
+ *
+ * The path is hashed alongside its content, so two files with identical bytes
+ * do not collide and a rename moves the digest — a gated file moved to another
+ * gated path is a different change, not the same one.
+ */
+export function subjectDigest(root: string, files: readonly string[]): string {
+    const h = createHash('sha256');
+    for (const rel of gatedFilesOf(files)) {
+        const abs = path.join(root, rel);
+        const content = fs.existsSync(abs) ? fs.readFileSync(abs) : Buffer.from(DELETED_MARKER);
+        h.update(rel);
+        h.update('\u0000');
+        h.update(createHash('sha256').update(content).digest('hex'));
+        h.update('\n');
+    }
+    return h.digest('hex');
+}

package/src/scripts/_lib/release_findings_ingest.ts

@@ -160,7 +160,9 @@ export function dispositionStopMessage(
     resumeCmd: string,
 ): string {
     const count =
-        blocking > 0 ? `  ${blocking} of them are blocking findings with no status yet.\n` : '';
+        blocking > 0
+            ? `  ${blocking} of them are blocking findings with no disposition yet (no status, or still_open).\n`
+            : '';
     return (
         `the disposition gate refuses ${version}. Its own report:\n` +
         `${gateOutput.trim() || '  (the gate printed nothing — run it directly to see why)'}\n` +
@@ -296,7 +298,7 @@ export function settleFindingsLedger(
                 // the operator `scanned: N` and discarded the entire reason the
                 // release stopped.
                 [verdict.stdout, verdict.stderr].map((s) => s.trim()).filter(Boolean).join('\n'),
-                blockingWithoutDisposition(path.join(deps.repoRoot, rel)),
+                blockingWithoutDisposition(path.join(deps.repoRoot, rel), version),
                 'task release -- --resume --yes',
             ),
         );
@@ -304,20 +306,26 @@ export function settleFindingsLedger(
 }
 
 /**
- * How many blocking findings carry no status — a figure for the stop message,
- * never the reason for it.
+ * How many blocking findings carry no disposition — no status, or `still_open`,
+ * which a blocking row may not rest on — a figure for the stop message, never
+ * the reason for it.
  *
  * The gate refuses for more shapes than this counts (an unknown status, an
  * empty rationale or verifier, a `fixed` with no commit, a malformed ledger),
- * which is why the gate's own output is what the operator is shown.
+ * which is why the gate's own output is what the operator is shown. It
+ * classifies against the version being released, the same input the gate
+ * reads from `--release`, not the ledger file's own `release` field.
  */
-function blockingWithoutDisposition(ledgerAbs: string): number {
+export function blockingWithoutDisposition(ledgerAbs: string, version: string): number {
     if (!fs.existsSync(ledgerAbs)) {
         return 0;
     }
     try {
         const ledger = parse_ledger(fs.readFileSync(ledgerAbs, 'utf-8'), ledgerAbs);
-        return ledger.findings.filter((f) => isBlocking(f) && !f.status).length;
+        return ledger.findings.filter((f) => {
+            const status = (f.status ?? '').trim();
+            return isBlocking(f, version) && (status === '' || status === 'still_open');
+        }).length;
     } catch {
         return 0;
     }

package/src/scripts/_lib/release_highlights.ts

@@ -610,6 +610,11 @@ const TEST_FOOTER_RE = /^Tests: \d+/mu;
  */
 export interface MixObligation {
     level: string;
+    /** The resolved ends the counts were read on; the rendered level names both. */
+    from_sha?: string;
+    to_sha?: string;
+    governance_only?: number;
+    consumer_only?: number;
 }
 
 /** Labels whose curated value is still the generator's unedited draft. */

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.'
+    );
+}