@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/check_pack_size.ts

@@ -23,6 +23,7 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -206,6 +207,220 @@ export function classifyPayload(files: readonly PackFile[]): string[] {
     return out;
 }
 
+/**
+ * Payload TYPE classification — what an entry IS, not where it sits.
+ *
+ * `CONTENT_CLASSES` above matches PATHS. That catches the shapes with a naming
+ * convention (a `.pem`, a `.test.js`, a `.vscode/` directory) and is blind to
+ * everything else: a compiled binary named `helper`, an archive named
+ * `data.md`, an extensionless script nobody looked at. Extension is the
+ * attacker's choice; the first bytes are not.
+ *
+ * Priority is archive > binary > dotfile > no-extension > text, so each entry
+ * lands in exactly one class and a count is a partition of the payload.
+ */
+export type PayloadType = 'text' | 'dotfile' | 'no-extension' | 'binary' | 'archive';
+
+export const PAYLOAD_TYPES: readonly PayloadType[] = [
+    'archive',
+    'binary',
+    'dotfile',
+    'no-extension',
+    'text',
+];
+
+/** Leading magic bytes for the archive container formats worth naming. */
+const ARCHIVE_MAGIC: ReadonlyArray<readonly number[]> = [
+    [0x50, 0x4b, 0x03, 0x04], // zip / jar / docx / xlsx
+    [0x1f, 0x8b], // gzip
+    [0x42, 0x5a, 0x68], // bzip2
+    [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00], // xz
+    [0x04, 0x22, 0x4d, 0x18], // lz4
+    [0x28, 0xb5, 0x2f, 0xfd], // zstd
+    [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c], // 7z
+    [0x52, 0x61, 0x72, 0x21], // rar
+];
+
+/** How many leading bytes are read to decide. */
+export const MAGIC_BYTES_READ = 512;
+
+function startsWith(buf: Uint8Array, sig: readonly number[]): boolean {
+    if (buf.length < sig.length) return false;
+    return sig.every((b, i) => buf[i] === b);
+}
+
+/**
+ * Classify one entry from its name and its first bytes.
+ *
+ * `head` is null when the file could not be read. That is NOT text: an entry
+ * the check could not open is an entry it did not classify, and the caller
+ * treats it as a failure rather than letting it fall through to the class that
+ * needs no exception.
+ */
+export function classifyEntry(entryPath: string, head: Uint8Array | null): PayloadType | 'unreadable' {
+    if (head === null) return 'unreadable';
+    if (ARCHIVE_MAGIC.some((sig) => startsWith(head, sig))) return 'archive';
+    if (head.length > 0) {
+        // A NUL byte is decisive. Short of that, a high proportion of C0
+        // control bytes outside tab/newline/CR is what separates a compiled
+        // object from prose that happens to contain an unusual character.
+        if (head.includes(0)) return 'binary';
+        let control = 0;
+        for (const b of head) {
+            if (b < 0x09 || (b > 0x0d && b < 0x20)) control += 1;
+        }
+        if (control / head.length > 0.1) return 'binary';
+    }
+    const base = entryPath.split('/').pop() ?? entryPath;
+    if (base.startsWith('.')) return 'dotfile';
+    if (!base.includes('.')) return 'no-extension';
+    return 'text';
+}
+
+/**
+ * An entry admitted into a class that would otherwise be empty.
+ *
+ * BOUND, not allow-listed, and the distinction is the whole point. A count
+ * ratchet ("8 extensionless entries are fine") is satisfied by ANY eight
+ * extensionless entries, so swapping one for something else passes silently —
+ * the same key-lookup weakness the Phase 5 pragma work removed one layer up.
+ * Here the binding is `sha256(path + "\n" + size)`: change the file and the
+ * exception stops applying, which re-fires the check on the entry that changed.
+ *
+ * NOT a `*_allowlist.json`. There is no file to grow, each entry states its own
+ * reason next to the class it excepts, and adding one is a reviewed code change
+ * in the gate — the same shape `CONTENT_CLASSES` already uses for its ratchets.
+ *
+ * Recompute a fingerprint with:
+ *   ./scripts-run src/scripts/check_pack_size   (the failure names path and size)
+ */
+export interface BoundPayloadException {
+    readonly fingerprint: string;
+    readonly path: string;
+    readonly size: number;
+    readonly why: string;
+}
+
+export function payloadFingerprint(entryPath: string, size: number): string {
+    return createHash('sha256').update(`${entryPath}\n${String(size)}`).digest('hex');
+}
+
+/**
+ * Measured on the BUILT payload, 2026-09-07: 3041 entries, of which 3026 are
+ * text and these 15 are not. `archive` is empty and stays a hard zero.
+ *
+ * The roadmap step that added this expected `binary` to be zero too. It is not:
+ * three 69-byte PNG placeholders ship as media-adapter fixtures. Recorded as a
+ * correction rather than resolved by redefining the class — they are genuinely
+ * binary, they genuinely ship, and dropping them from the published surface is
+ * a consumer-visible change that belongs to whoever owns those adapters.
+ */
+const BOUND_PAYLOAD_EXCEPTIONS: readonly BoundPayloadException[] = [
+    { fingerprint: '955b5da399e14fb39cfe1f3279044061043e64e2bd1576871514db927e56d701', path: 'src/scripts/media/lib/fixtures/flux/asset-0001.png', size: 69, why: 'media-adapter response fixture — a 69-byte placeholder PNG the flux adapter test decodes; binary by construction' },
+    { fingerprint: 'c2dd9743367ece8ffe0deef5e798d39967c22245749fd7f798edd8aa78b70f59', path: 'src/scripts/media/lib/fixtures/gemini-image/asset-0001.png', size: 69, why: 'media-adapter response fixture — same class as the flux placeholder' },
+    { fingerprint: 'cbac44d021a1dc41b938e798eb9be4147fc9d35194c348dfe9acaa0596bc83a5', path: 'src/scripts/media/lib/fixtures/ideogram/asset-0001.png', size: 69, why: 'media-adapter response fixture — same class as the flux placeholder' },
+    { fingerprint: 'fdf6334f2342a48faaea708fd43853066f7057e528dfd1dd6fb5dcf8c0f67845', path: 'agents/templates/.ai-council.yml.example', size: 29872, why: 'shipped council config TEMPLATE — a dotfile because the file it is copied to is one' },
+    { fingerprint: 'd36a53951c184db7481139235056e90b53a853714b3a68b31ba1349ecb95ac1d', path: 'agents/templates/.ai-video.xml.example', size: 9209, why: 'shipped video-provider config template — same reason as the council template' },
+    { fingerprint: 'f83229412cf8cceaadd0cb1934140a0c7c8277df43edc590f370572f6df6da98', path: 'dist/agent-src/templates/agents/.gitattributes.fragment', size: 2140, why: 'gitattributes fragment the installer appends to a consumer repo' },
+    { fingerprint: 'a4f51dba3a66c0f2c3548e77961271ed4d7b5ec8a6661ea359ff044758f0d921', path: 'src/templates/minimal/.agent-settings.yml', size: 1042, why: 'the minimal-install settings template; the dot is the consumer-side filename' },
+    { fingerprint: 'a9cb828c7f3e6ac62d3c55c2fd215779307bf695a065498b1d1e1188210ebea8', path: 'LICENSE', size: 1064, why: 'the licence npm requires in the tarball; extensionless by convention' },
+    { fingerprint: 'e89a3d025a838e295838db68d0d832c701eeca01bb7e6c3983d3a48950f80017', path: 'NOTICE', size: 472, why: 'attribution notice shipped with the licence; extensionless by convention' },
+    { fingerprint: 'c9da3c6e2476a6d2b9610a1fbf638ba9bb78ddd76fc0f799631d601774c32cab', path: 'dist/agent-src/templates/hooks/pre-commit-frontmatter', size: 2537, why: 'git hook template — git requires a hook file to carry no extension' },
+    { fingerprint: 'aeffa474df3f805de07cdc9c6960c4918aa8e51e317fa1c30906d2f0267b7a16', path: 'dist/agent-src/templates/hooks/pre-commit-roadmap-progress', size: 3988, why: 'git hook template — same reason' },
+    { fingerprint: '914f9c34551c5f4c42a70cd8bb0cd7b73078b0c4e7815b551833a3c64c8476d3', path: 'src/scripts/agent-config', size: 2391, why: 'the CLI entry script; an executable entry point carries no extension by convention' },
+    { fingerprint: '0bb1cdd48ac2e9b6a2a56cde25de9fc221d75d42683680284c43118cff796e92', path: 'src/scripts/hooks/shims/php', size: 4439, why: 'shim invoked as the command name `php`; an extension would break the lookup' },
+    { fingerprint: 'b14bdd3cd589848ad8e6d7e5f4ee633dc9005a2a97abba327a9426ce556714da', path: 'src/scripts/install', size: 22049, why: 'the installer entry script; same reason as the CLI entry' },
+    { fingerprint: '1fb564019de468368e34941dffd5eb8bc994364313e02f476ff354ac0da464d7', path: 'src/templates/minimal/overrides-gitkeep', size: 164, why: 'placeholder that becomes .gitkeep on install; extensionless on purpose' },
+];
+
+/** Read the first bytes of a payload entry from the tree it was packed from. */
+function readHead(entryPath: string, root: string): Uint8Array | null {
+    try {
+        const fd = fs.openSync(path.join(root, entryPath), 'r');
+        try {
+            const buf = Buffer.alloc(MAGIC_BYTES_READ);
+            const read = fs.readSync(fd, buf, 0, MAGIC_BYTES_READ, 0);
+            return buf.subarray(0, read);
+        } finally {
+            fs.closeSync(fd);
+        }
+    } catch {
+        return null;
+    }
+}
+
+export interface TypeClassification {
+    readonly counts: Record<PayloadType | 'unreadable', number>;
+    /** Entries in a non-`text` class with no bound exception. */
+    readonly unbound: Array<{ path: string; size: number; type: PayloadType | 'unreadable'; fingerprint: string }>;
+    /** Bound exceptions matching no entry in this payload. */
+    readonly unusedExceptions: string[];
+}
+
+/**
+ * Classify the whole payload by type and report what is not accounted for.
+ *
+ * Every entry outside `text` needs a bound exception. `archive` has none and is
+ * meant to stay that way; `binary` has three, named; the dotfile and
+ * extensionless entries are each bound to a path AND a size, so replacing one
+ * with different content re-fires the check on that entry rather than passing
+ * inside a count.
+ */
+export function classifyPayloadTypes(
+    files: readonly PackFile[],
+    root = REPO_ROOT,
+    head: (p: string) => Uint8Array | null = (p) => readHead(p, root),
+): TypeClassification {
+    const counts: Record<PayloadType | 'unreadable', number> = {
+        archive: 0,
+        binary: 0,
+        dotfile: 0,
+        'no-extension': 0,
+        text: 0,
+        unreadable: 0,
+    };
+    const byFingerprint = new Map(BOUND_PAYLOAD_EXCEPTIONS.map((e) => [e.fingerprint, e]));
+    const used = new Set<string>();
+    const unbound: TypeClassification['unbound'] = [];
+    for (const f of files) {
+        const type = classifyEntry(f.path, head(f.path));
+        counts[type] += 1;
+        if (type === 'text') continue;
+        const fingerprint = payloadFingerprint(f.path, f.size);
+        if (byFingerprint.has(fingerprint)) {
+            used.add(fingerprint);
+            continue;
+        }
+        unbound.push({ path: f.path, size: f.size, type, fingerprint });
+    }
+    return {
+        counts,
+        unbound,
+        unusedExceptions: BOUND_PAYLOAD_EXCEPTIONS.filter((e) => !used.has(e.fingerprint)).map((e) => e.path),
+    };
+}
+
+/** One line naming every type class and its count. */
+export function payloadTypeLine(c: TypeClassification): string {
+    const parts = [...PAYLOAD_TYPES, 'unreadable' as const]
+        .filter((t) => t !== 'unreadable' || c.counts.unreadable > 0)
+        .map((t) => `${t} ${String(c.counts[t])}`);
+    return `${parts.join(' · ')} — ${String(c.unbound.length)} unaccounted`;
+}
+
+/** Violations from the type classification, as human-readable lines. */
+export function typeClassViolations(c: TypeClassification): string[] {
+    return c.unbound.map(
+        (u) =>
+            `payload type \`${u.type}\`: ${u.path} (${String(u.size)} bytes) is not accounted for. ` +
+            (u.type === 'archive' || u.type === 'binary'
+                ? 'This class is meant to be empty. '
+                : 'Every dotfile and extensionless entry is carried by a path-and-size-bound exception. ') +
+            `If it belongs in the published surface, add a BoundPayloadException with ` +
+            `fingerprint sha256:${u.fingerprint} and a reason; otherwise exclude it from package.json files[].`,
+    );
+}
+
 /** Per-class counts, for the green-path report. */
 export function payloadClassCounts(
     files: readonly PackFile[],
@@ -377,8 +592,8 @@ function selfTest(): number {
         Array.from({ length: n }, (_, i) => `dist/hooks/chunk-${String(i)}.js.map`);
     return runSelfTest({
         gate: 'check_pack_size',
-        minCases: 9,
-        minRejectCases: 5,
+        minCases: 14,
+        minRejectCases: 9,
         cases: [
             {
                 name: 'credential-shaped: a .pem in the payload is refused',
@@ -410,6 +625,95 @@ function selfTest(): number {
                 expect: 'accept',
                 run: () => (classifyPayload(builtPayload(...maps(120))).length > 0 ? 1 : 0),
             },
+            {
+                // MAGIC BYTES, NOT THE EXTENSION. This is the whole reason the
+                // type pass exists beside the path pass above: an archive named
+                // `.md` is invisible to every path pattern in CONTENT_CLASSES.
+                name: 'type/archive: a zip planted under a .md name is classified archive, not text',
+                expect: 'reject',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes(packFiles('src/skills/x/SKILL.md'), REPO_ROOT, () =>
+                            Uint8Array.from([0x50, 0x4b, 0x03, 0x04, 0x14, 0x00]),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                name: 'type/archive: the SAME path with ordinary text is classified text and passes',
+                expect: 'accept',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes(packFiles('src/skills/x/SKILL.md'), REPO_ROOT, () =>
+                            new TextEncoder().encode('# An ordinary skill\n'),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                name: 'type/binary: a NUL-bearing entry is refused however it is named',
+                expect: 'reject',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes(packFiles('src/scripts/helper.ts'), REPO_ROOT, () =>
+                            Uint8Array.from([0x7f, 0x45, 0x4c, 0x46, 0x02, 0x00, 0x00]),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                name: 'type/extensionless: an unbound extensionless entry is refused',
+                expect: 'reject',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes(packFiles('src/scripts/newtool'), REPO_ROOT, () =>
+                            new TextEncoder().encode('#!/bin/sh\n'),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                // The property a COUNT ratchet cannot have. LICENSE is bound at
+                // its measured size; the same path at a different size is a
+                // different artifact and the exception stops applying.
+                name: 'type/binding: a bound entry whose SIZE changed is refused again',
+                expect: 'reject',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes([{ path: 'LICENSE', size: 999999 }], REPO_ROOT, () =>
+                            new TextEncoder().encode('MIT\n'),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                name: 'type/binding: that same entry at its recorded size passes',
+                expect: 'accept',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes([{ path: 'LICENSE', size: 1064 }], REPO_ROOT, () =>
+                            new TextEncoder().encode('MIT\n'),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                // An entry the check could not open is one it did not classify.
+                name: 'type/unreadable: an entry that cannot be read is refused, never assumed text',
+                expect: 'reject',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes(packFiles('src/scripts/gone.ts'), REPO_ROOT, () => null),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
             {
                 name: 'a plain payload passes — the classes are not firing on everything',
                 expect: 'accept',
@@ -477,7 +781,12 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     // still knows the population it was red over.
     process.stdout.write(`scanned: ${String(pack.files.length)}\n`);
 
-    const errors = [...evaluate(budget, pack), ...classifyPayload(pack.files)];
+    const types = classifyPayloadTypes(pack.files);
+    const errors = [
+        ...evaluate(budget, pack),
+        ...classifyPayload(pack.files),
+        ...typeClassViolations(types),
+    ];
     const { perSkill, total } = skillBytes(pack.files);
     if (argv.includes('--json')) {
         process.stdout.write(
@@ -485,6 +794,15 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         );
         return errors.length > 0 ? 1 : 0;
     }
+    // Printed BEFORE the verdict and on EVERY path, red included. The counts are
+    // what a reader needs to judge a violation: "one unaccounted binary" reads
+    // very differently against a payload of 3 binaries than against one of 0.
+    process.stdout.write(`    payload types: ${payloadTypeLine(types)}\n`);
+    for (const unused of types.unusedExceptions) {
+        // Not an error: an unbuilt tree legitimately packs fewer files. Named
+        // so a stale exception is visible rather than accumulating unread.
+        process.stdout.write(`    bound exception matched no entry: ${unused}\n`);
+    }
     if (errors.length > 0) {
         for (const e of errors) process.stderr.write(`❌  pack size: ${e}\n`);
         return 1;

package/src/scripts/check_release_highlights.ts

@@ -72,13 +72,17 @@ import {
     derive_categories,
     parse_git_log,
     mix_response_blockers,
+    previous_promise,
     previous_release_tag,
+    promise_readback_blockers,
     stale_draft_labels,
 } from './_lib/release_highlights.js';
 import { loadTaxonomy, measureRange } from './measure_release_mix.js';
 import {
     CURATED_HEAD_INSTRUCTION,
+    PROMISE_READBACK_MARKER,
     extract_changelog_section,
+    previous_changelog_version,
 } from './_lib/release_material.js';
 import { assertScanned, assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
@@ -207,7 +211,8 @@ export function main(argv: readonly string[]): number {
         }
         throw err;
     }
-    const section = extract_changelog_section(fs.readFileSync(changelogPath, 'utf-8'), version);
+    const changelogText = fs.readFileSync(changelogPath, 'utf-8');
+    const section = extract_changelog_section(changelogText, version);
     if (!section) {
         process.stderr.write(`CHANGELOG carries no section for ${version}\n`);
         return 2;
@@ -251,6 +256,11 @@ export function main(argv: readonly string[]): number {
         return mix;
     }
 
+    const readback = check_previous_promise_readback(changelogText, section.body, version);
+    if (readback !== 0) {
+        return readback;
+    }
+
     const curated = parse_curated_head(section.body);
     if (!curated) {
         process.stdout.write(`ℹ️  no curated head in the ${version} section — nothing to check\n`);
@@ -417,6 +427,69 @@ export function check_governance_mix_response(
     return 1;
 }
 
+/**
+ * The previous release's promise, read back at the next release.
+ *
+ * `_lib/release_material.ts` generates `Next cycle ships …` and, until this
+ * check existed, nothing ever asked what became of it: 14.18.0 promised the MCP
+ * bridge repair, and no gate in the tree would have noticed the same promise
+ * being reprinted in 14.19.0 and 14.20.0. A commitment nothing reads back is
+ * free to restate, and one that is free to restate is not a commitment.
+ *
+ * Only the section under release is read, and only the previous section's
+ * governance-response block — the same scope every other check here uses, so a
+ * historical section cannot red a future release.
+ *
+ * The check is about ANSWERING, never about having kept the promise. A gate
+ * that refused an unkept promise would price honesty above silence and teach
+ * the next author to promise nothing.
+ */
+export function check_previous_promise_readback(
+    changelogText: string,
+    body: string,
+    version: string,
+): number {
+    const previousVersion = previous_changelog_version(changelogText, version);
+    if (previousVersion === null) {
+        process.stdout.write(`✅  no previous CHANGELOG section before ${version} — no promise to read back\n`);
+        return 0;
+    }
+    const promise = previous_promise(changelogText, previousVersion);
+    if (promise === null) {
+        process.stdout.write(
+            `✅  the ${previousVersion} section made no next-cycle promise — nothing owed by ${version}\n`,
+        );
+        return 0;
+    }
+    const blockers = promise_readback_blockers(
+        body,
+        version,
+        previousVersion,
+        promise,
+        `\`release/${version}\``,
+    );
+    if (blockers.length === 0) {
+        process.stdout.write(`✅  ${version} answers the ${previousVersion} next-cycle promise\n`);
+        return 0;
+    }
+    process.stderr.write(
+        `❌  the ${version} section owes an answer to the ${previousVersion} next-cycle promise.\n` +
+            blockers.map((b) => `    - ${b}\n`).join('') +
+            `    The ${previousVersion} promise reads:\n` +
+            promise
+                .split('\n')
+                .map((l) => `        ${l}\n`)
+                .join('') +
+            `    Answering it is one blockquote line under the curated head, e.g.\n` +
+            `        > ${PROMISE_READBACK_MARKER} the <promise> did not ship; <what happened>.\n` +
+            '    Shipped, did not ship, or withdrawn with a reason — the check refuses a MISSING\n' +
+            '    answer, never a particular outcome. An unkept promise answered honestly passes.\n' +
+            '    Reproduce locally, before any push:\n' +
+            `        ./scripts-run src/scripts/check_release_highlights --version ${version}\n`,
+    );
+    return 1;
+}
+
 const _isMain = (() => {
     const entry = process.argv[1];
     if (!entry) return false;

package/src/scripts/check_skill_activation_claim.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env tsx
+/**
+ * The published skill-activation figure agrees with the record it came from.
+ *
+ * WHY THIS IS A SEPARATE SCRIPT FROM THE CENSUS
+ * ---------------------------------------------
+ * `report_skill_activation` is a REPORT: it gates on nothing, has no threshold,
+ * and its own docstring says it must never acquire one. This is a GATE, and the
+ * two must not share an entry point — `src/config/gate-coverage.yml` is a
+ * manifest of gates, and `_lib/gate_population.ts` classifies a script by its
+ * prefix precisely so that "is this a gate" is answered structurally rather
+ * than by whoever last edited a config. Registering a `report_*` id there forks
+ * that population, which `tests/scripts/gate_population.test.ts` refuses.
+ *
+ * So the split is not cosmetic. The report keeps its exit-0 contract; the
+ * assertion that CAN fail lives here, where a floor and a self-test belong.
+ *
+ * WHAT IT CANNOT DO, STATED SO NOBODY READS IT AS COVERED
+ * ------------------------------------------------------
+ * It compares two COMMITTED files — the census record against the sentence
+ * `docs/CLAIMS.md` publishes. It cannot tell whether the record still describes
+ * the world: the transcript store it was taken from is one machine's, keyed on
+ * the directory the census ran in, and absent from CI. Re-taking the
+ * measurement is `report_skill_activation --emit`, which refuses to write from
+ * an empty store. This gate only forbids the published sentence and the record
+ * from telling two different stories.
+ *
+ * Exit: 0 agree · 1 disagree or a file is missing.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+import {
+  CLAIMS_PATH,
+  CLAIM_ID,
+  RECORD_PATH,
+  claimBlock,
+  claimProblems,
+  parseClaimFigures,
+  readRecord,
+} from './report_skill_activation.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export function check(root: string): number {
+  const rec = readRecord(root);
+  if (rec === null) {
+    process.stderr.write(`❌  ${RECORD_PATH} is missing — the published figure has no record behind it.\n`);
+    return 1;
+  }
+  const claimsFile = path.join(root, CLAIMS_PATH);
+  if (!fs.existsSync(claimsFile)) {
+    process.stderr.write(`❌  ${CLAIMS_PATH} is missing.\n`);
+    return 1;
+  }
+  const block = claimBlock(fs.readFileSync(claimsFile, 'utf8'), CLAIM_ID);
+  // Emitted before the verdict on both paths: a gate that reports what it
+  // inspected only when it passes leaves the coverage census blind exactly when
+  // it matters.
+  reportScanned({
+    gate: 'check_skill_activation_claim',
+    scanned: block === null ? 0 : 1,
+    units: 'published claim block(s)',
+    roots: [CLAIMS_PATH],
+  });
+  if (block === null) {
+    process.stderr.write(`❌  claim \`${CLAIM_ID}\` is not in ${CLAIMS_PATH}.\n`);
+    return 1;
+  }
+  const problems = claimProblems(rec, parseClaimFigures(block));
+  if (problems.length > 0) {
+    process.stderr.write('❌  the published census claim and its record disagree:\n');
+    for (const p of problems) {
+      process.stderr.write(`  · ${p}\n`);
+    }
+    process.stderr.write(
+      `\nRe-take the measurement (report_skill_activation --emit) and update the claim from ${RECORD_PATH}.\n`,
+    );
+    return 1;
+  }
+  process.stdout.write(`✅  census claim matches ${RECORD_PATH} (measured ${rec.measured_at}).\n`);
+  return 0;
+}
+
+/**
+ * The gate proving it still discriminates.
+ *
+ * The third case is the one a value comparison alone would miss: a claim that
+ * silently stops stating a figure would otherwise pass every equality test it
+ * no longer participates in.
+ */
+function selfTest(): number {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'activation-claim-selftest-'));
+  const record = {
+    schema_version: 1,
+    measured_at: '2026-01-02',
+    skills_shipped: 300,
+    with_trigger_key: 10,
+    with_trigger_corpus: 100,
+    trigger_key_and_corpus: 5,
+    human_named_only: 195,
+    sessions: 7,
+    assistant_turns: 1234,
+    invocations: 0,
+    distinct_skills_invoked: 0,
+    stores: ['fixture'],
+  };
+  const agreeing =
+    '`report_skill_activation` over 7 sessions and 1,234 assistant turns records 0 Skill ' +
+    'invocations and 0 of 300 distinct skills (measured 2026-01-02). 10 declare a ' +
+    'machine-matchable trigger key in frontmatter, 100 carry an `evals/triggers.json` corpus, ' +
+    '5 do both, and the remaining 195 are reachable only by a human naming them.';
+  const write = (name: string, body: string): string => {
+    const root = path.join(tmp, name);
+    fs.mkdirSync(path.join(root, path.dirname(RECORD_PATH)), { recursive: true });
+    fs.mkdirSync(path.join(root, path.dirname(CLAIMS_PATH)), { recursive: true });
+    fs.writeFileSync(path.join(root, RECORD_PATH), JSON.stringify(record));
+    fs.writeFileSync(
+      path.join(root, CLAIMS_PATH),
+      `# Claims\n\n### claim: ${CLAIM_ID}\n- claim: ${body}\n- kind: quant\n- status: backed\n- last_verified: 2026-01-02\n\n### claim: unrelated\n- claim: x\n`,
+    );
+    return root;
+  };
+  const run = (root: string): number =>
+    runGateCli(REPO_ROOT, 'src/scripts/check_skill_activation_claim.ts', ['--root', root], root);
+  try {
+    return runSelfTest({
+      gate: 'check_skill_activation_claim',
+      minCases: 4,
+      minRejectCases: 3,
+      cases: [
+        {
+          name: 'a turn count that moved away from the record is rejected',
+          expect: 'reject',
+          run: () => run(write('turns', agreeing.replace('1,234 assistant', '9,999 assistant'))),
+        },
+        {
+          name: 'a population redrawn to enlarge the human-named remainder is rejected',
+          expect: 'reject',
+          run: () => run(write('population', agreeing.replace('remaining 195 are', 'remaining 290 are'))),
+        },
+        {
+          name: 'a claim that stops stating the population split is rejected',
+          expect: 'reject',
+          run: () => run(write('dropped', agreeing.slice(0, agreeing.indexOf('. 10 declare') + 1))),
+        },
+        {
+          name: 'a claim reproducing every recorded figure passes',
+          expect: 'accept',
+          run: () => run(write('agreeing', agreeing)),
+        },
+      ],
+    });
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+export function main(argv: readonly string[]): number {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write('usage: check_skill_activation_claim [--root DIR] [--self-test]\n');
+    return 0;
+  }
+  if (argv.includes('--self-test')) {
+    return selfTest();
+  }
+  const i = argv.indexOf('--root');
+  return check(i === -1 ? REPO_ROOT : (argv[i + 1] ?? REPO_ROOT));
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_trigger_evals.ts

@@ -150,7 +150,7 @@ function _check_one(p: string, today: PyDate): string[] {
         if (age > MAX_AGE_DAYS) {
             errors.push(
                 `${rel}: \`last_eval\` ${raw as string} is ${age}d old (> ${MAX_AGE_DAYS}d) ` +
-                    '— re-run skill_trigger_eval.py and bump it',
+                    '— re-run skill_trigger_eval and bump it',
             );
         }
     }