@event4u/agent-config 9.20.0 → 9.22.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;

package/src/scripts/check_update_banner.ts

@@ -22,6 +22,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as agent_settings from './_lib/agent_settings.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 import * as update_check from './_lib/update_check.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -107,6 +108,29 @@ async function main(argv: readonly string[] = process.argv.slice(2)): Promise<nu
         return 0;
     }
 
+    if (!args.installed_version) {
+        // Without the flag, `$PACKAGE_ROOT/package.json` IS the whole input.
+        // `_read_installed_version` swallows a missing or unparseable file into
+        // '' and the banner then simply never fires — indistinguishable from
+        // "you are up to date". The exit code stays 0 on purpose: "never
+        // raises, never exits non-zero" is this wrapper's pinned CLI contract,
+        // so the only loudness available is stderr, which is where the banner
+        // itself goes anyway.
+        try {
+            assertWatchlistResolves({
+                gate: 'check_update_banner',
+                candidates: ['package.json'],
+                repoRoot: ROOT,
+            });
+        } catch (err) {
+            if (err instanceof DeadScopeError) {
+                process.stderr.write(`❌  ${err.message}\n`);
+                return 0;
+            }
+            throw err;
+        }
+    }
+
     const installed = args.installed_version || _read_installed_version(ROOT);
     if (!installed) {
         return 0;