@event4u/agent-config 9.19.0 → 9.21.0

package/src/scripts/check_preamble_payload_budget.ts

@@ -23,6 +23,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { censusClaudeMdHierarchy, censusRuleDir, censusSkillsCatalog } from './preamble_byte_census.js';
 
 const HERE = path.dirname(new URL(import.meta.url).pathname);
@@ -40,7 +41,7 @@ export interface BudgetVerdict {
     baseline: number;
     ceiling: number;
     withinBudget: boolean;
-    buckets: Array<{ name: string; tokens: number }>;
+    buckets: Array<{ name: string; tokens: number; files: number }>;
 }
 
 function tokens(chars: number): number {
@@ -65,7 +66,7 @@ export function readBudget(file: string = BUDGET_FILE): Budget {
 /** Measure only what the repo tree determines — no `~`, no transcripts, no network. */
 export function measureDeterministicPayload(
     repoRoot: string = REPO_ROOT,
-): Array<{ name: string; tokens: number }> {
+): Array<{ name: string; tokens: number; files: number }> {
     const projectRules = censusRuleDir(path.join(repoRoot, 'dist', 'agent-src', 'rules'));
     const skills = censusSkillsCatalog(path.join(repoRoot, 'dist', 'agent-src', 'skills'));
     // Only the PROJECT half of the CLAUDE.md hierarchy is deterministic — the
@@ -73,10 +74,20 @@ export function measureDeterministicPayload(
     const claudeMd = censusClaudeMdHierarchy(repoRoot, path.join(repoRoot, '.no-such-home'));
     const projectClaudeMdChars =
         claudeMd.project_claude_md_chars + claudeMd.project_claude_local_md_chars;
+    // `files` carries the count of sources each census actually read. A token
+    // total cannot tell "the root moved" from "the payload is genuinely tiny",
+    // so the scope assertion in `main` needs the count, not the bytes.
+    const claudeMdFiles =
+        (claudeMd.project_claude_md_present ? 1 : 0) +
+        (claudeMd.project_claude_local_md_present ? 1 : 0);
     return [
-        { name: 'project-scope rules', tokens: tokens(projectRules.chars) },
-        { name: 'preloaded skills catalog', tokens: tokens(skills.chars) },
-        { name: 'CLAUDE.md hierarchy (project only)', tokens: tokens(projectClaudeMdChars) },
+        { name: 'project-scope rules', tokens: tokens(projectRules.chars), files: projectRules.files },
+        { name: 'preloaded skills catalog', tokens: tokens(skills.chars), files: skills.skills },
+        {
+            name: 'CLAUDE.md hierarchy (project only)',
+            tokens: tokens(projectClaudeMdChars),
+            files: claudeMdFiles,
+        },
     ];
 }
 
@@ -98,6 +109,25 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
 
+    // A ratchet over a measurement of nothing always passes: move
+    // `dist/agent-src/` and every census returns zero, which is trivially under
+    // any ceiling. Exit 2 (misuse / unreadable budget — the could-not-run
+    // code), never 1, which asserts the payload actually grew.
+    try {
+        assertScanned({
+            gate: 'check_preamble_payload_budget',
+            scanned: verdict.buckets.reduce((n, b) => n + b.files, 0),
+            units: 'payload source file(s)',
+            roots: ['dist/agent-src/rules', 'dist/agent-src/skills', 'CLAUDE.md'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  preamble-payload budget: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
     if (json) {
         process.stdout.write(JSON.stringify(verdict, null, 2) + '\n');
         return verdict.withinBudget ? 0 : 1;

package/src/scripts/check_proposal.ts

@@ -37,6 +37,8 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 type Severity = 'error' | 'warning';
 
 const REQUIRED_FRONTMATTER: ReadonlySet<string> = new Set([
@@ -456,7 +458,28 @@ function main(): number {
         process.stderr.write(`error: ${p} not found\n`);
         return 3;
     }
-    const findings = _runChecks(fs.readFileSync(p, 'utf-8'), p);
+    const text = fs.readFileSync(p, 'utf-8');
+    // No corpus walk: this gate's scope is the single document named on argv.
+    // The unit is therefore the content lines actually read — every check below
+    // is a search over this text, so a zero-byte target makes the negative ones
+    // ("no TODO/TBD markers") vacuously true against nothing.
+    try {
+        assertScanned({
+            gate: 'check_proposal',
+            scanned: text.split('\n').filter((l) => l.trim() !== '').length,
+            units: 'content line(s)',
+            roots: [p],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = gate failure, which is what an unusable proposal already
+            // returns today (3 is reserved for the not-found path above).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    const findings = _runChecks(text, p);
     const errors = findings.filter((f) => f.severity === 'error');
     if (args.format === 'json') {
         process.stdout.write(

package/src/scripts/check_public_catalog_links.ts

@@ -26,6 +26,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const QUIET = process.argv.slice(2).includes('--quiet');
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -117,6 +119,10 @@ function main(): number {
     const missing: Array<[number, string]> = [];
     const unshipped: Array<[number, string]> = [];
 
+    // Counted BEFORE any filtering — external hrefs and anchors included — so
+    // the number answers "did the catalog still carry links", not "how many
+    // survived the checks".
+    let links_seen = 0;
     const lines = _splitlines(text);
     for (let i = 0; i < lines.length; i++) {
         const lineno = i + 1;
@@ -124,6 +130,7 @@ function main(): number {
         LINK_RE.lastIndex = 0;
         let m: RegExpExecArray | null;
         while ((m = LINK_RE.exec(line)) !== null) {
+            links_seen += 1;
             const href = m[1]!;
             if (href.includes(FORBIDDEN_PREFIX)) {
                 forbidden.push([lineno, href]);
@@ -143,6 +150,26 @@ function main(): number {
         }
     }
 
+    // The catalog is generated. A renderer that stops emitting links leaves a
+    // file that still exists and still parses, so the three violation buckets
+    // stay empty and this reports "all links resolve" over no links at all.
+    // Exit 1 is the only failure code here, and it already carries the
+    // could-not-run meaning (the missing-catalog path above returns it too).
+    try {
+        assertScanned({
+            gate: 'check_public_catalog_links',
+            scanned: links_seen,
+            units: 'markdown link(s)',
+            roots: ['docs/catalog.md'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stdout.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const total_violations = forbidden.length + missing.length + unshipped.length;
     if (total_violations === 0) {
         if (!QUIET) {

package/src/scripts/check_public_links.ts

@@ -22,6 +22,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const PUBLIC_FILES = ['README.md', 'AGENTS.md', 'docs/architecture.md'] as const;
@@ -269,6 +271,23 @@ function main(): number {
     const args = parse_args(process.argv.slice(2));
 
     const contracts = collect_contracts();
+    // Every verdict below is decided against this map: an empty contracts dir
+    // turns "no stability violations" into "nothing was ever compared".
+    try {
+        assertScanned({
+            gate: 'check_public_links',
+            scanned: contracts.size,
+            units: 'contract file(s)',
+            roots: [CONTRACTS_DIR],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = violations found (2 is argparse, 3 internal error).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     if (args.list) {
         for (const [p, lvl] of contracts) {
             const label = lvl ?? '(no frontmatter)';

package/src/scripts/check_quality_regression.ts

@@ -51,6 +51,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { wilcoxon } from './bench_ab_v2_stats.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -299,6 +300,24 @@ function main(argv: string[]): number {
   }
 
   const results = Array.isArray(report.results) ? report.results : [];
+  // A MISSING report is the documented inert path and already returned above. A
+  // report that exists and carries no pairs is a different thing entirely — a
+  // truncated or half-written judge run — yet it aggregates to `no-data` and
+  // exits 0 outside flip-gate mode, i.e. reads as "quality held" on zero data.
+  try {
+    assertScanned({
+      gate: 'check_quality_regression',
+      scanned: results.length,
+      units: 'judged pair(s)',
+      roots: [path.relative(REPO_ROOT, reportPath)],
+    });
+  } catch (e) {
+    if (e instanceof DeadScopeError) {
+      process.stderr.write(`error: ${e.message}\n`);
+      return 1; // the gate's file-error code — the report is present but unusable
+    }
+    throw e;
+  }
   const thr = typeof report.threshold === 'number' ? report.threshold : threshold;
   const agg = aggregate(results, thr);
 

package/src/scripts/check_reach_channels.ts

@@ -53,6 +53,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { SchemaError, validate, type YamlValue } from './validate_frontmatter.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -305,6 +306,27 @@ export function check_probe_cmd_binding(registry: unknown): SchemaError[] {
     return findings;
 }
 
+/**
+ * Backends declared across every channel — the units the schema rules and the
+ * `probe_cmd-binding` rule actually judge. Same deliberate shape-tolerance as
+ * `check_probe_cmd_binding`: anything unreadable is skipped, so the number is
+ * "entries a rule could be applied to", never "entries that passed".
+ */
+function count_backends(registry: unknown): number {
+    const root =
+        registry !== null && typeof registry === 'object' && !Array.isArray(registry)
+            ? (registry as Record<string, unknown>)
+            : null;
+    const channels = Array.isArray(root?.['channels']) ? (root['channels'] as unknown[]) : [];
+    return channels.reduce<number>((total, rawChannel) => {
+        if (rawChannel === null || typeof rawChannel !== 'object' || Array.isArray(rawChannel)) {
+            return total;
+        }
+        const backends = (rawChannel as Record<string, unknown>)['backends'];
+        return total + (Array.isArray(backends) ? backends.length : 0);
+    }, 0);
+}
+
 /**
  * Validate one registry file against the schema.
  *
@@ -376,6 +398,28 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 1;
     }
 
+    // Reaching a CLEAN verdict over zero backends means the SCHEMA stopped
+    // constraining, not that the registry is empty: `minItems: 1` sits on both
+    // `channels` and `backends`, so an empty registry is an error-severity
+    // finding and returned above. A gutted or repointed schema is therefore
+    // the only way to arrive here with nothing scanned — and it would print ✅
+    // over a file no rule was applied to. Exit 3 is the could-not-run class
+    // `RegistryLoadError` already uses; 1 asserts real violations were found.
+    try {
+        assertScanned({
+            gate: 'check_reach_channels',
+            scanned: count_backends(load_registry(targetPath)),
+            units: 'backend(s)',
+            roots: [relTarget],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError || err instanceof RegistryLoadError) {
+            process.stderr.write(`❌  check_reach_channels: ${err.message}\n`);
+            return 3;
+        }
+        throw err;
+    }
+
     if (!quiet) {
         process.stdout.write(`✅  ${relTarget}: schema-valid (reach channel registry).\n`);
     }

package/src/scripts/check_reach_staleness.ts

@@ -51,6 +51,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { RegistryLoadError, load_registry } from './check_reach_channels.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -313,8 +314,16 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const relTarget = path.relative(ROOT, registryPath) || registryPath;
 
     let findings: StalenessFinding[];
+    let channelCount: number;
     try {
         findings = run_checks({ registryPath, today });
+        // `load_registry` already refuses a missing / unparseable file (exit 3),
+        // but a registry that PARSES with no `channels:` list is the blind case:
+        // `extract_channels` is defensive by contract and returns [], so every
+        // per-channel check iterates nothing and the gate prints the ✅ line.
+        // Re-reading the (small) YAML keeps run_checks / extract_channels — both
+        // exported and pinned by fixtures — untouched.
+        channelCount = extract_channels(load_registry(registryPath)).length;
     } catch (err) {
         if (err instanceof RegistryLoadError) {
             process.stderr.write(`❌  check_reach_staleness: ${err.message}\n`);
@@ -323,6 +332,24 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         throw err;
     }
 
+    // No `allowEmpty`: a registry with zero channels is a registry this gate
+    // cannot judge, and it reads exactly like a clean one. Exit 3 (unusable
+    // input) over 1 (violations) — a dead scope means the gate could not run.
+    try {
+        assertScanned({
+            gate: 'check_reach_staleness',
+            scanned: channelCount,
+            units: 'channel(s)',
+            roots: [`${path.relative(ROOT, registryPath) || registryPath} → channels[]`],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 3;
+        }
+        throw err;
+    }
+
     if (findings.length > 0) {
         process.stdout.write(`❌  ${relTarget}: ${findings.length} staleness violation(s):\n`);
         for (const finding of findings) {

package/src/scripts/check_release_adjacent_health.ts

@@ -18,7 +18,14 @@
  * Exit codes: 0 all green/absent · 1 durably-red workflow(s) · 2 usage/env.
  */
 
+import * as path from 'node:path';
 import { argv, env, exit } from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
+// src/scripts/check_release_adjacent_health.ts → two levels up is the repo root.
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 const WATCHED = [
     'publish-npm.yml',
@@ -71,6 +78,27 @@ async function main(): Promise<number> {
         return 2;
     }
 
+    // The scope is the watch list itself. A renamed or deleted workflow answers
+    // 404 → the loop logs "no completed runs (or workflow absent) — skipping"
+    // and continues, so a fully stale WATCHED list still prints "✅ healthy" —
+    // the same silent-tripwire failure this gate exists to detect. Checking the
+    // names against `.github/workflows/` catches the rename locally, before the
+    // API can launder it into a skip. Exit 2 (usage/env) over 1 (durably red):
+    // a phantom watch list means the tripwire could not run.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_release_adjacent_health',
+            candidates: WATCHED.map((wf) => `.github/workflows/${wf}`),
+            repoRoot: REPO,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
     // Tag/release-triggered workflows have no branch association — query
     // without the branch filter for those; branch-scoped for PR/push ones.
     const branchless = new Set(['publish-npm.yml', 'deploy-mcp-worker.yml', 'release.yml']);

package/src/scripts/check_release_highlights.ts

@@ -47,6 +47,7 @@ import {
     stale_draft_labels,
 } from './_lib/release_highlights.js';
 import { extract_changelog_section } from './_lib/release_material.js';
+import { assertScanned, assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -142,6 +143,23 @@ function main(argv: readonly string[]): number {
             return 2;
         }
     }
+    // The changelog is the curated half of the comparison and it is read
+    // unconditionally below; a moved or renamed file would otherwise surface as
+    // an ENOENT stack trace rather than a gate verdict. Exit 2 is this gate's
+    // could-not-run code (same as a missing section); 1 means a contradiction.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_release_highlights',
+            candidates: [path.relative(REPO_ROOT, path.resolve(changelogPath))],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
     const section = extract_changelog_section(fs.readFileSync(changelogPath, 'utf-8'), version);
     if (!section) {
         process.stderr.write(`CHANGELOG carries no section for ${version}\n`);
@@ -159,6 +177,22 @@ function main(argv: readonly string[]): number {
         process.stderr.write(`${(err as Error).message}\n`);
         return 2;
     }
+    // Every derived category comes from this span, so an empty one makes the
+    // contradiction check pass over nothing.
+    assertScanned({
+        gate: 'check_release_highlights',
+        scanned: span.length,
+        units: 'span commit(s)',
+        roots: [`git log ${from}..${to}`],
+        allowEmpty:
+            'EMPTY_VALID: git already answered for the range — a from..to it could not read ' +
+            'throws in collect_span_commits above and exits 2, so reaching here with zero ' +
+            'commits means git read the range successfully and it is genuinely empty. ' +
+            '"Empty span with _none_ everywhere is green" is a pre-registered fixture of this ' +
+            'gate, not a scope failure: with no commits there is no evidence a curated `_none_` ' +
+            'could contradict. Deleting the scan root is not the same state — that is the ' +
+            'throwing branch, not this one.',
+    });
     // A generator-derived line that nobody rewrote is a prose gap, never a
     // contradiction: the line's evidence is true, it is just unpolished. Warn
     // so the omission is visible, and keep the exit code owned solely by the

package/src/scripts/check_release_includes_discovery.ts

@@ -20,6 +20,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/check_release_includes_discovery.ts → two dirs up is repo root.
 // Mirrors Python `Path(__file__).resolve().parents[2]`.
@@ -68,17 +70,34 @@ function main(): number {
         data !== null && typeof data === 'object'
             ? (data as Record<string, unknown>)['artefacts']
             : undefined;
-    if (!Array.isArray(artefacts) || artefacts.length === 0) {
-        return _die(
-            `${_rel(MANIFEST)} carries no artefacts — discovery` +
-                ' scanner produced an empty manifest.',
-        );
+    // The empty-manifest check IS this gate's scan-scope assertion: a manifest
+    // listing nothing means the discovery scanner walked a dead root, and
+    // shipping it would tell every consumer the package has no artefacts.
+    const artefact_count = Array.isArray(artefacts) ? artefacts.length : 0;
+    try {
+        assertScanned({
+            gate: 'check_release_includes_discovery',
+            scanned: artefact_count,
+            units: 'artefact(s)',
+            roots: [_rel(MANIFEST)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only failure code, and the wording below is the
+            // pinned py2ts message — so the DeadScopeError text is not
+            // substituted for it.
+            return _die(
+                `${_rel(MANIFEST)} carries no artefacts — discovery` +
+                    ' scanner produced an empty manifest.',
+            );
+        }
+        throw exc;
     }
     if (!_isFile(SUMMARY)) {
         return _die(`${_rel(SUMMARY)} is missing.`);
     }
     process.stdout.write(
-        `check-release-discovery: OK (${artefacts.length} artefacts in` +
+        `check-release-discovery: OK (${artefact_count} artefacts in` +
             ` ${_rel(MANIFEST)})\n`,
     );
     return 0;

package/src/scripts/check_release_pr_shape.ts

@@ -20,6 +20,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 const ALLOWLIST_GLOBS = [
@@ -127,7 +129,22 @@ function _gh_diff_files(pr: string): string[] {
 }
 
 function check(files: readonly string[]): number {
-    if (files.length === 0) {
+    // This gate already refused an empty diff by hand; routing that refusal
+    // through the shared primitive keeps the behaviour (pinned stdout line,
+    // exit 1) while making the scope assertion explicit. No `allowEmpty`: a
+    // release PR that touches nothing is the failure, not a clean state — and
+    // an empty `gh pr diff` (bad PR number, auth failure) reads identically.
+    try {
+        assertScanned({
+            gate: 'check_release_pr_shape',
+            scanned: files.length,
+            units: 'changed file(s)',
+            roots: ['gh pr diff --name-only <pr> | --files <list>'],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
         process.stdout.write(
             'OUT-OF-SHAPE: empty diff — release PR must touch at least one file.\n',
         );

package/src/scripts/check_release_published.ts

@@ -26,6 +26,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -131,6 +133,25 @@ const _hooks: Hooks = {
 function main(argv: readonly string[] = [], hooks: Hooks = _hooks): number {
     const args = parse_args(argv);
 
+    // This gate walks no tree: one named file supplies BOTH sides of every
+    // invariant — the version the git tag must match and the package name npm
+    // is queried for. A repointed PACKAGE_JSON constant is the whole failure
+    // surface, so the watch list is the scope assertion. Exit 3 (internal
+    // error — the gate could not run), never 1, which asserts real drift.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_release_published',
+            candidates: [path.relative(REPO_ROOT, PACKAGE_JSON)],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     let version: string;
     try {
         version = hooks._package_version();

package/src/scripts/check_release_surface_equality.ts

@@ -28,6 +28,7 @@ import {
     strip_pr_wrapper,
     surface_divergence,
 } from './_lib/release_material.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -102,6 +103,27 @@ function main(argv: readonly string[]): number {
         ) as Record<string, unknown>;
         version = String(pkg['version']);
     }
+    // The changelog is this gate's one fixed named input — the other surface is
+    // either fetched over the network (`--pr`) or a caller-supplied fixture. It
+    // is read unguarded below, so a moved or renamed CHANGELOG would surface as
+    // an ENOENT stack trace rather than a verdict. Listed alone on purpose: a
+    // watch list passes as soon as ANY candidate resolves, so pairing it with
+    // `--body-file` would let an existing fixture mask an absent changelog.
+    // Exit 2 — this gate's usage/extraction class — never 1, which asserts
+    // the two surfaces genuinely diverged.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_release_surface_equality',
+            candidates: [path.relative(REPO_ROOT, path.resolve(changelogPath))],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
     const prBody = pr !== null ? _pr_body(pr) : fs.readFileSync(bodyFile!, 'utf-8');
     const changelogText = fs.readFileSync(changelogPath, 'utf-8');
     const result = check_surface_equality({ prBody, changelogText, version });

package/src/scripts/check_release_trunk_sync.ts

@@ -21,6 +21,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned } from './_lib/scan_scope.js';
+
 const RELEASE_BRANCH_RE = /^release\/(\d+)\.(\d+)\.(\d+)$/;
 const SEMVER_TAG_RE = /^(\d+)\.(\d+)\.(\d+)$/;
 const BOOTSTRAP_FILE = 'docs/contracts/release-trunk-sync.bootstrap';
@@ -137,6 +139,23 @@ function main(): number {
     }
     const m = RELEASE_BRANCH_RE.exec(branch);
     if (!m) {
+        // Declared no-op, not a silent one. The gate's other empty states —
+        // no semver tags, no tag reachable from main — are NOT swallowed
+        // either: each prints its own `::warning::… skipped` line below, and
+        // that wording is the pinned py2ts contract, so neither is converted
+        // into a DeadScopeError here.
+        assertScanned({
+            gate: 'check_release_trunk_sync',
+            scanned: 0,
+            units: 'release-prep branch(es)',
+            roots: ['git rev-parse --abbrev-ref HEAD'],
+            allowEmpty:
+                'OPTIONAL_INPUT: the checked-out branch is not release/X.Y.Z, so there is no ' +
+                'target version to compare main against — an absent question, not an empty ' +
+                'corpus. Deletion test: wiping every git ref would not produce this branch; ' +
+                'the input read here is the branch NAME, it was read successfully, and a ' +
+                'branch that could not be read exits at the detached-HEAD warning above.',
+        });
         return 0; // non-release branch class — gate is a no-op
     }
     const target: SemVer = [Number(m[1]), Number(m[2]), Number(m[3])];