@event4u/agent-config 9.20.0 → 9.21.0

package/src/scripts/check_secret_leak.ts

@@ -37,6 +37,7 @@ 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';
 import { scanText, type SecretFinding } from './_lib/secret_detector.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -253,6 +254,52 @@ function _stderr(s: string): void {
 export function main(argv?: readonly string[]): number {
     const args = parseArgs(argv ?? process.argv.slice(2));
     const mode: Mode = args.paths.length > 0 ? 'explicit' : args.all ? 'all' : 'diff';
+
+    // Scope assertion, deliberately here and not inside `scanRepo`: that export
+    // is called directly by tests and other callers against arbitrary roots, and
+    // a secret gate is the last place to widen a throw. The cost is one extra
+    // `resolveFiles` (a `git ls-files` / `git diff`); the file reads are not
+    // repeated. Assert the RESOLVED set, before the exclude/binary filters —
+    // those legitimately drop everything (a diff touching only `tests/`), so
+    // filtering to zero is not the same signal as resolving to zero.
+    // Exit 2 (usage/env) over 1 (leak found) — a dead scope means the gate could
+    // not run. `resolveFiles` already hard-throws on an unresolvable base, so
+    // that case never arrives here as a quiet zero; a non-DeadScopeError is
+    // re-thrown untouched to preserve it.
+    try {
+        const targets = resolveFiles(REPO_ROOT, mode, { explicit: args.paths, base: args.base });
+        assertScanned({
+            gate: 'check_secret_leak',
+            scanned: targets.length,
+            units: 'candidate file(s)',
+            roots:
+                mode === 'all'
+                    ? ['git ls-files']
+                    : mode === 'explicit'
+                      ? ['<explicit path arguments>']
+                      : [`git diff --name-only --diff-filter=ACMR ${args.base ?? 'origin/main'}`, 'git ls-files --others --exclude-standard'],
+            // `all` and `explicit` carry no reason: zero tracked files, or zero
+            // named paths, is blindness in a repo that has content.
+            ...(mode === 'diff'
+                ? {
+                      allowEmpty:
+                          'EMPTY_VALID: shift-left mode scans what the change introduces, and a ' +
+                          'branch identical to its base with no untracked files introduces nothing ' +
+                          '— an absent question, not an empty corpus. Deletion test: wiping the ' +
+                          'tracked tree would show up here as changed paths, and an unresolvable ' +
+                          'base (the dangerous zero, which shallow CI produces) already throws in ' +
+                          'resolveFiles above rather than reaching this line.',
+                  }
+                : {}),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            _stderr(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     const hits = scanRepo(REPO_ROOT, mode, { explicit: args.paths, base: args.base });
 
     if (args.json) {

package/src/scripts/check_skill_gaps.ts

@@ -16,6 +16,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const SKILLS_DIR = path.join(ROOT, 'src', 'skills');
@@ -76,8 +78,38 @@ export function findBrokenPointers(entries: SkillGaps[], root: string = ROOT): s
     return errs;
 }
 
+/** SKILL.md files under `skillsDir` — the corpus `collectSkillGaps` reads. */
+function countSkillFiles(skillsDir: string = SKILLS_DIR): number {
+    try {
+        return fs
+            .readdirSync(skillsDir)
+            .filter((name) => fs.existsSync(path.join(skillsDir, name, 'SKILL.md'))).length;
+    } catch {
+        // A missing root counts zero, which the caller's assertion turns into a
+        // loud failure — never a silent "no gaps to check".
+        return 0;
+    }
+}
+
 export function main(argv: string[] = process.argv.slice(2)): number {
     const quiet = argv.includes('--quiet');
+    // The scanned unit is every SKILL.md, not the subset declaring `gaps:` —
+    // asserting on the declaration count would read a vanished skills tree as
+    // "no gaps declared" and stay green, the exact blindness this guards.
+    try {
+        assertScanned({
+            gate: 'check_skill_gaps',
+            scanned: countSkillFiles(),
+            units: 'SKILL.md file(s)',
+            roots: ['src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const entries = collectSkillGaps();
     const errs = findBrokenPointers(entries);
     if (errs.length > 0) {

package/src/scripts/check_skill_requires.ts

@@ -19,6 +19,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML from 'yaml';
 
 import { ROOT, iter_artefacts } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { parse_frontmatter } from './validate_frontmatter.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -107,6 +108,24 @@ function _set_hooks_for_test(overrides: Partial<typeof _hooks>): void {
 function main(): number {
     const closure = _hooks.load_pack_closure();
     const skills = _hooks.collect_skills();
+    // The unit is every parsed SKILL.md, not the subset declaring
+    // `requires_skills:` — over a vanished skills tree "0 composition edges"
+    // is indistinguishable from a suite that legitimately declares none.
+    try {
+        assertScanned({
+            gate: 'check_skill_requires',
+            scanned: Object.keys(skills).length,
+            units: 'SKILL.md file(s)',
+            roots: ['src/agent-src', 'src/skills', 'src/rules'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only failure code (0 clean / 1 violations).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const errors: string[] = [];
 
     for (const skill_id of Object.keys(skills).sort()) {

package/src/scripts/check_source_pointer_freshness.ts

@@ -36,6 +36,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // parents[2] of src/scripts/<file> is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -142,6 +144,24 @@ function main(argv: readonly string[]): number {
         return _selftest();
     }
     const asJson = argv.includes('--json');
+    // Scope is the allowlist itself — there is no tree to walk. An emptied
+    // AUTHORING_FILES scans nothing and reports "No retired source-of-truth
+    // pointers" forever, which is the one result this gate must never produce
+    // by accident. Exit 2 (the usage / self-test class, i.e. the gate could
+    // not run), never 1 — 1 asserts a retired pointer was actually found.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_source_pointer_freshness',
+            candidates: AUTHORING_FILES,
+            repoRoot: ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
     const hits: Hit[] = [];
     for (const rel of AUTHORING_FILES) {
         hits.push(..._scanFile(rel));

package/src/scripts/check_structural_breaking.ts

@@ -30,6 +30,8 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const QUIET = process.argv.includes('--quiet');
 // src/scripts/check_structural_breaking.ts → three levels up is the repo root
 // (Python: Path(__file__).resolve().parent.parent.parent).
@@ -91,12 +93,37 @@ function main(): number {
         return 0; // no trunk to diff against (e.g. shallow CI) → no-op
     }
     const names = _git('diff', '--name-status', `${base}...HEAD`);
-    if (names.trim() === '') {
+    const changed = _splitlines(names);
+    // Replaces the bare `names.trim() === ''` early return: a branch identical
+    // to trunk genuinely changes nothing, so zero is allowed — but it now says
+    // so through the shared primitive instead of a silent `return 0`.
+    // Exit 1 is this pinned CLI's only failure code.
+    try {
+        assertScanned({
+            gate: 'check_structural_breaking',
+            scanned: changed.length,
+            units: 'changed path(s)',
+            roots: [`git diff --name-status ${BASE_REF}...HEAD`],
+            allowEmpty:
+                'EMPTY_VALID: a branch with no diff against trunk has no structural change to ' +
+                'judge — an absent question, not an empty corpus. Deletion test: deleting the ' +
+                'watched artifact trees would show up here as D lines (the very break this gate ' +
+                'reports), so a wiped tree cannot produce this zero. An unresolvable base does ' +
+                'not reach here either — it exits at the no-trunk no-op above.',
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    if (changed.length === 0) {
         return 0; // nothing changed vs trunk
     }
 
     const breaks: string[] = [];
-    for (const line of _splitlines(names)) {
+    for (const line of changed) {
         const parts = line.split('\t');
         const status = parts[0]!;
         if (status.startsWith('D') && ARTIFACT_RE.test(parts[1]!)) {

package/src/scripts/check_surface_tiers.ts

@@ -37,6 +37,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const SCRIPTS = path.join(ROOT, 'src', 'scripts');
 const REGISTRY = path.join(SCRIPTS, 'surface-tiers.yml');
@@ -105,6 +107,20 @@ function check_exhaustive(clusters: Map<string, string>): string[] {
     return errors;
 }
 
+/** Cluster dirs on disk under SCRIPTS — the corpus `check_exhaustive` classifies. */
+function _count_cluster_dirs(): number {
+    let children: fs.Dirent[];
+    try {
+        children = fs.readdirSync(SCRIPTS, { withFileTypes: true });
+    } catch {
+        // A missing root counts zero; the caller's assertion makes that loud.
+        return 0;
+    }
+    return children.filter(
+        (c) => !_IGNORE_DIRS.has(c.name) && _isDir(path.join(SCRIPTS, c.name)),
+    ).length;
+}
+
 function _module_tier(
     dotted: string,
     clusters: Map<string, string>,
@@ -527,6 +543,24 @@ function main(argv?: readonly string[]): number {
         args.skip_imports || envSkip === '1' || envSkip === 'true' || envSkip === 'yes';
 
     const { clusters, lab_modules } = _load_registry();
+    // The unit is the cluster dirs found on disk, not `clusters.size` (the
+    // registry's own entries): over a vanished src/scripts/ every registry
+    // entry goes unchallenged and both assertions are trivially clean.
+    try {
+        assertScanned({
+            gate: 'check_surface_tiers',
+            scanned: _count_cluster_dirs(),
+            units: 'cluster dir(s)',
+            roots: ['src/scripts'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = violation(s); 2 is reserved for argparse usage errors.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const errors = check_exhaustive(clusters);
     if (skip_imports) {
         process.stdout.write('surface-tiers: import boundary check SKIPPED (kill-switch).\n');

package/src/scripts/check_template_pin_drift.ts

@@ -27,6 +27,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { resolve_logical } from './_lib/agent_src.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // Python `Path(__file__).resolve().parents[2]` — two dirs up from src/scripts.
@@ -159,8 +160,29 @@ function main(argv: readonly string[] = []): number {
         return 1;
     }
 
+    // Scope is two named templates, one of them resolved through
+    // `resolve_logical` — a resolver returning a path under an artefact root
+    // that no longer exists is exactly how this comparison ends up with
+    // nothing to compare. Exit 1: it is this gate's only failure code, and it
+    // already carries the could-not-run meaning (a missing template file is
+    // reported as a failure below); 2 is reserved for CLI misuse.
+    const templates = _template_files();
+    try {
+        assertWatchlistResolves({
+            gate: 'check_template_pin_drift',
+            candidates: templates.map((p) => path.relative(REPO_ROOT, p)),
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  check_template_pin_drift: ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const failures: string[] = [];
-    for (const template of _template_files()) {
+    for (const template of templates) {
         const rel = _relToPosixOrAbs(template, REPO_ROOT);
         if (!_isFile(template)) {
             failures.push(`missing template file: ${rel}`);

package/src/scripts/check_test_coverage_diff.ts

@@ -17,6 +17,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 _HERE = fileURLToPath(import.meta.url);
 
 // Injectable for tests (monkeypatch parity): REPO_ROOT, _git_name_status,
@@ -177,7 +179,21 @@ function parse_args(argv: readonly string[]): ParsedArgs {
 
 function main(argv?: readonly string[]): number {
     const opts = parse_args(argv ?? process.argv.slice(2));
-    const changed = _hooks.git_name_status(_resolve_base_ref(opts.base_ref));
+    const base_ref = _resolve_base_ref(opts.base_ref);
+    const changed = _hooks.git_name_status(base_ref);
+    assertScanned({
+        gate: 'check_test_coverage_diff',
+        scanned: changed.length,
+        units: 'changed path(s)',
+        roots: [`git diff --name-status ${base_ref}...HEAD`],
+        allowEmpty:
+            'EMPTY_VALID: a diff with no changed paths adds no gate, so there is nothing for a ' +
+            'coverage forcing-function to warn about. Deletion test: a deleted worktree cannot ' +
+            'produce this state — an UNREADABLE range is a different case and is not silent, ' +
+            '`_git_name_status` prints `⚠️  coverage-diff: git diff failed (…); skipping.` to ' +
+            'stderr before returning empty. The exit code is 0 either way by pinned contract ' +
+            '(warn-only this phase), so this assertion declares the scope rather than gating it.',
+    });
     const [warnings, suppressed] = evaluate(changed, _hooks.pragma_reason_from_tree);
     if (warnings.length > 0) {
         process.stdout.write(

package/src/scripts/check_token_optimizer_freshness.ts

@@ -20,6 +20,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { resolve_logical, strip_source_prefix } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -150,9 +151,23 @@ function main(): number {
     }
     const text = fs.readFileSync(SKILL, 'utf-8');
     const rows = parse_catalog(text);
-    if (rows.length === 0) {
-        process.stderr.write('ERROR: token-optimizer SKILL.md has no parseable catalog rows\n');
-        return 1;
+    // Supersedes the hand-rolled "no parseable catalog rows" guard: same exit
+    // code and stream, but the shared assertion names the root, so a renamed
+    // `## Catalog` heading or a moved SKILL.md reports as a dead scope instead
+    // of a bare ERROR line.
+    try {
+        assertScanned({
+            gate: 'check_token_optimizer_freshness',
+            scanned: rows.length,
+            units: 'catalog row(s)',
+            roots: [path.relative(REPO_ROOT, SKILL)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`ERROR: ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const allErrs: string[] = [];
     let checked = 0;

package/src/scripts/check_token_quality_golden.ts

@@ -43,6 +43,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as yaml from 'js-yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const CORPUS = path.join(REPO_ROOT, 'internal/bench/corpora/token-quality-golden.yaml');
@@ -350,6 +352,25 @@ function main(argv: string[]): number {
   // Structure (incl. the fires-check) always validates against the FULL
   // universe — a maintainer-rule tag is not "unknown" under consumer scope.
   const report = validate(corpus, ruleIds, router);
+  // `tasks: []` parses, validates clean, and covers nothing — and without
+  // `--require-complete` an uncovered universe is only a ⚠️, so an emptied
+  // corpus exits 0 while proving nothing about any rule.
+  try {
+    assertScanned({
+      gate: 'check_token_quality_golden',
+      scanned: report.task_count,
+      units: 'golden task(s)',
+      roots: [path.relative(REPO_ROOT, CORPUS)],
+    });
+  } catch (e) {
+    if (e instanceof DeadScopeError) {
+      // 2 = invalid corpus; 1 is reserved for an unreadable file, and this one
+      // read and parsed fine.
+      process.stderr.write(`❌  ${e.message}\n`);
+      return 2;
+    }
+    throw e;
+  }
 
   // Coverage accounting runs against the SCOPED universe: which flip is
   // being gated decides what "complete" means.

package/src/scripts/check_token_regression.ts

@@ -41,6 +41,8 @@ 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';
+
 const _HERE = fileURLToPath(import.meta.url);
 // REPO_ROOT = <repo>/src/scripts/<file> → up two.
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -216,6 +218,29 @@ function main(argv: string[]): number {
   }
   const current = extract_metrics(report);
 
+  // `_num` returns 0 both for "absent from the report" and for "genuinely
+  // zero", and no gated surface is ever legitimately zero tokens — so a
+  // renamed report key reads as 0, every pct goes negative against the
+  // baseline, and the gate reports ✅ while measuring nothing. Counting the
+  // metrics that resolved is counting units READ, not units passing. Asserted
+  // BEFORE --update-baseline so a report of zeros can never be recorded as the
+  // baseline every later run compares against. Exit 1 (the file/argument
+  // error class — the gate could not run); 2 means a real regression.
+  try {
+    assertScanned({
+      gate: 'check_token_regression',
+      scanned: Object.values(current.metrics).filter((v) => v > 0).length,
+      units: 'gated metric(s)',
+      roots: [path.relative(REPO_ROOT, PROJECTION_REPORT)],
+    });
+  } catch (err) {
+    if (err instanceof DeadScopeError) {
+      process.stderr.write(`❌  ${err.message}\n`);
+      return 1;
+    }
+    throw err;
+  }
+
   if (updateBaseline) {
     const payload = JSON.stringify(current, null, 2) + '\n';
     fs.writeFileSync(BASELINE_FILE, payload);

package/src/scripts/check_tracked_but_ignored.ts

@@ -19,14 +19,23 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as path from 'node:path';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 function main(argv?: readonly string[]): number {
     const args = argv ?? process.argv.slice(2);
     const quiet = args.includes('--quiet');
 
+    let tracked: string;
     let output: string;
     try {
+        // The corpus is the tracked index, not the `-ci` result — that result IS
+        // the finding list, so counting it would count violations. Read the index
+        // itself: `git ls-files` is path-scoped to the cwd, so running from a
+        // subtree with nothing tracked yields an empty index AND an empty `-ci`
+        // result, and the gate prints its green line having examined nothing.
+        tracked = execSync('git ls-files', { encoding: 'utf-8', cwd: process.cwd() }).trim();
         output = execSync('git ls-files -ci --exclude-standard', {
             encoding: 'utf-8',
             cwd: process.cwd(),
@@ -36,6 +45,23 @@ function main(argv?: readonly string[]): number {
         return 2;
     }
 
+    try {
+        assertScanned({
+            gate: 'check_tracked_but_ignored',
+            scanned: tracked ? tracked.split('\n').filter(Boolean).length : 0,
+            units: 'tracked file(s)',
+            roots: ['git ls-files (cwd-scoped index)'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 2 = "this gate could not run" (its git-unavailable code), never 1,
+            // which asserts the stronger claim that ignored-but-tracked files exist.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     if (!output) {
         if (!quiet) {
             process.stdout.write(`✅  No tracked-but-ignored files found.\n`);

package/src/scripts/check_trigger_eval_presence.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 REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const SKILLS_DIR = path.join(REPO_ROOT, 'src', 'skills');
 const ALLOWLIST_PATH = path.join(REPO_ROOT, 'src', 'scripts', 'trigger_eval_grandfather.json');
@@ -128,7 +130,27 @@ function main(): number {
         return 2;
     }
 
-    const { errors, covered, total } = check(list_skill_dirs(SKILLS_DIR), allowlist.skills);
+    // The ratchet only bites per skill directory found: an empty (or moved)
+    // skills root makes every rule in `check` iterate nothing, and the ✅ line
+    // reads "0/0 skills carry evals/triggers.json" — a passing presence gate
+    // over no skills at all.
+    const skills = list_skill_dirs(SKILLS_DIR);
+    try {
+        assertScanned({
+            gate: 'check_trigger_eval_presence',
+            scanned: skills.length,
+            units: 'skill director(ies)',
+            roots: ['src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const { errors, covered, total } = check(skills, allowlist.skills);
 
     if (errors.length) {
         process.stderr.write('❌ check-trigger-eval-presence: presence-ratchet violation(s):\n');

package/src/scripts/check_trigger_evals.ts

@@ -27,6 +27,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 REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const GLOB = 'src/skills/*/evals/triggers.json';
 const MAX_AGE_DAYS = 90;
@@ -276,6 +278,20 @@ function _isFile(p: string): boolean {
     }
 }
 
+/** Immediate `src/skills/*` directories — the population `_glob_triggers` filters. */
+function _skill_dirs(root: string): string[] {
+    const skillsDir = path.join(root, 'src', 'skills');
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((ent) => ent.isDirectory() || ent.isSymbolicLink())
+        .map((ent) => path.join(skillsDir, ent.name));
+}
+
 /** Component-wise path comparison matching PosixPath ordering. */
 function _pathSort(a: string, b: string): number {
     const pa = a.split(path.sep);
@@ -342,6 +358,26 @@ function main(): number {
         return 2;
     }
 
+    // The scanned unit is the skill directory, not the triggers.json subset:
+    // whether a given skill ships evals is `check_trigger_eval_presence`'s
+    // ratchet, so zero trigger sets under a populated tree is that gate's
+    // finding, not this one's. Zero skill DIRECTORIES is this gate's blindness
+    // — the ✅ line then reads "0 trigger set(s) fresh + valid".
+    try {
+        assertScanned({
+            gate: 'check_trigger_evals',
+            scanned: _skill_dirs(REPO_ROOT).length,
+            units: 'skill director(ies)',
+            roots: ['src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const files = _glob_triggers(REPO_ROOT);
     const errors: string[] = [];
     for (const p of files) {

package/src/scripts/check_trunk_drift.ts

@@ -16,6 +16,8 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as path from 'node:path';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 export type DriftInput = {
     /** True when origin/main is an ancestor of HEAD (branch contains trunk tip). */
     trunkIsAncestor: boolean;
@@ -42,8 +44,13 @@ function _git(args: string[]): string {
 
 export function main(): number {
     let input: DriftInput;
+    let trunkCommits = 0;
     try {
         _git(['fetch', 'origin', 'main', '--quiet']);
+        // The comparison is only meaningful against a trunk that has history.
+        // An origin/main pointing at an empty/orphan ref answers "0 behind" and
+        // scores the branch up to date without ever having read a trunk commit.
+        trunkCommits = Number(_git(['rev-list', '--count', 'origin/main']) || '0');
         let isAncestor = true;
         try {
             execFileSync('git', ['merge-base', '--is-ancestor', 'origin/main', 'HEAD'], { stdio: 'ignore' });
@@ -56,6 +63,22 @@ export function main(): number {
         process.stdout.write(`⚠️  trunk-drift check skipped (no origin/main or git error): ${String(e)}\n`);
         return 0; // advisory — never block on a missing remote
     }
+    try {
+        assertScanned({
+            gate: 'check_trunk_drift',
+            scanned: trunkCommits,
+            units: 'trunk commit(s)',
+            roots: ['origin/main'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is the only failure code; 0 means pass/advisory-skip, so a dead
+            // scope must not borrow it — a gate that read no trunk has not passed.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const v = driftVerdict(input);
     process.stdout.write(`${v.message}\n`);
     return v.ok ? 0 : 1;