@event4u/agent-config 9.20.0 → 9.22.0

package/src/scripts/lint_surface_matrix.ts

@@ -23,6 +23,7 @@ import YAML from 'yaml';
 
 import { USER_SCOPE_PATHS } from './install.js';
 import { CLAUDE_MARKETPLACE_NAME, CLAUDE_PLUGIN_ID } from './_lib/claude_plugin.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 export const MATRIX_PATH = path.join(REPO_ROOT, 'src', 'config', 'surface-matrix.yml');
@@ -59,9 +60,24 @@ export function load_surface_matrix(matrixPath: string = MATRIX_PATH): Record<st
 }
 
 export function main(): number {
-    if (!fs.existsSync(MATRIX_PATH)) {
-        process.stdout.write(`❌  ${MATRIX_PATH} not found\n`);
-        return 1;
+    // Replaces the ad-hoc `existsSync(MATRIX_PATH)` precondition. The matrix
+    // yaml is the gate's only file input — an emptied `tools:` mapping is
+    // already caught by the set-equality against USER_SCOPE_PATHS (a code
+    // constant a path migration cannot empty), so a moved file is the one
+    // remaining way this gate can go quiet. Exit 1 = "could not run" here; 3
+    // stays reserved for an unexpected throw at the CLI boundary.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_surface_matrix',
+            candidates: [path.relative(REPO_ROOT, MATRIX_PATH)],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
     }
 
     const errors: string[] = [];

package/src/scripts/lint_ticket_buildable.ts

@@ -42,6 +42,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import YAML from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // REPO = Path(__file__).resolve().parents[2]
@@ -676,6 +678,27 @@ function lint(): number {
         return 3;
     }
 
+    // The asserted unit is the roadmap corpus, not the ticket bundles: a repo
+    // with no bundles yet is a real state (the early return below), whereas a
+    // vanished agents/roadmaps/ answers "no orphan markers" for the spine
+    // check and "not materialised" for nothing, both silently.
+    try {
+        assertScanned({
+            gate: 'lint_ticket_buildable',
+            scanned: _glob(ROADMAPS, '*.md').length,
+            units: 'roadmap file(s)',
+            roots: [ROADMAPS],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 3 = IO/setup error, this gate's "could not run" code; 1 means
+            // lint failures were found.
+            process.stderr.write(`${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     if (!_exists(TICKETS_ROOT)) {
         process.stdout.write('agents/tickets/: no bundles yet — nothing to lint\n');
         return 0;

package/src/scripts/lint_topics_yaml.ts

@@ -26,6 +26,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml, YAMLParseError } from 'yaml';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 // src/scripts/lint_topics_yaml.ts → two dirs up is the repo root
 // (mirrors Path(__file__).resolve().parents[2]).
 const _HERE = fileURLToPath(import.meta.url);
@@ -39,15 +41,6 @@ function _relTo(target: string, root: string): string {
     return path.relative(root, target).split(path.sep).join('/');
 }
 
-function _exists(p: string): boolean {
-    try {
-        fs.statSync(p);
-        return true;
-    } catch {
-        return false;
-    }
-}
-
 /**
  * Render a value the way Python's `repr()` / `{x!r}` would for the values
  * that flow into the finding messages: strings (single-quoted, with escape
@@ -103,9 +96,23 @@ function _fail(msg: string): void {
 }
 
 function main(): number {
-    if (!_exists(TOPICS_FILE)) {
-        _fail(`missing file: ${_relTo(TOPICS_FILE, ROOT)}`);
-        return 1;
+    // Replaces the ad-hoc `_exists(TOPICS_FILE)` precondition: the gate's whole
+    // corpus is this one named file, so its absence is a dead scope rather than
+    // a content finding. Same stderr channel, same exit 1 (the only failure code).
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_topics_yaml',
+            candidates: [_relTo(TOPICS_FILE, ROOT)],
+            repoRoot: ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            // Not via `_fail`: its `topics.yml:` prefix would stutter against
+            // the gate name the DeadScopeError message already carries.
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
     }
     let doc: unknown;
     try {

package/src/scripts/lint_trigger_precision.ts

@@ -43,6 +43,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 REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const ROUTER = path.join(REPO_ROOT, 'dist', 'router.json');
@@ -108,6 +110,31 @@ export function main(): number {
         return 1;
     }
 
+    // The routed-rule population, not `found` below: `found` counts VIOLATIONS,
+    // so zero is the direction this ratchet is pushing toward. A router.json
+    // regenerated over a moved rule tree parses fine and yields zero short
+    // keywords — indistinguishable from a clean run. Exit 1 is the existing
+    // "gate could not run" code (missing / unparseable router); 2 stays
+    // "over budget".
+    const routed = ['tier_1', 'tier_2'].reduce(
+        (n, tier) => n + (Array.isArray(router[tier]) ? (router[tier] as unknown[]).length : 0),
+        0,
+    );
+    try {
+        assertScanned({
+            gate: 'lint_trigger_precision',
+            scanned: routed,
+            units: 'routed rule(s)',
+            roots: ['dist/router.json'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`error: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+
     const found = short_keywords(router);
     const over = found.length > SHORT_KEYWORD_BUDGET;
 

package/src/scripts/lint_trust_coherence.ts

@@ -26,6 +26,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { strip_source_prefix } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const _DEFAULT_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -317,6 +318,26 @@ function main(argv: readonly string[] = []): number {
     const manifest = _load_manifest(args.manifest);
     const kernel = _load_kernel(args.router);
 
+    // All three invariants iterate `artefacts`; the existing guard only covers a
+    // manifest that is ABSENT. One that parses but carries no artefacts — a
+    // discovery build over a moved source tree — visits nothing and prints the
+    // same success line, just with zeroes in it. Exit 1 is the gate's only
+    // failure code (the missing-manifest SystemExit lands on 1 too).
+    try {
+        assertScanned({
+            gate: 'lint_trust_coherence',
+            scanned: _asArray(manifest['artefacts']).length,
+            units: 'manifest artefact(s)',
+            roots: [args.manifest],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`ERROR: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+
     const errs: string[] = [];
     errs.push(..._check_pack_safety_floors(manifest));
     errs.push(..._check_human_review_banners(manifest, args.compiledSrc));

package/src/scripts/lint_ui_stack_bundles.ts

@@ -33,6 +33,7 @@ import {
     type StackBundle,
     compose_bundle,
 } from '../agent-src/templates/scripts/work_engine/directives/ui/stack_bundles.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const QUIET = process.argv.includes('--quiet');
 
@@ -153,9 +154,22 @@ function check_lane(lane: string, bundle: StackBundle): void {
 
 function main(): number {
     const lanes = Object.keys(STACK_BUNDLES).sort();
-    if (lanes.length === 0) {
-        process.stderr.write('lint-ui-stack-bundles: STACK_BUNDLES is empty — nothing to check.\n');
-        return 1;
+    // Replaces the ad-hoc `lanes.length === 0` check with the shared assertion,
+    // so an emptied bundle map names the root it came from instead of a bare
+    // "nothing to check". Exit 1 is the gate's only failure code.
+    try {
+        assertScanned({
+            gate: 'lint_ui_stack_bundles',
+            scanned: lanes.length,
+            units: 'stack lane(s)',
+            roots: ['src/agent-src/templates/scripts/work_engine/directives/ui/stack_bundles.ts'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
     }
     for (const lane of lanes) {
         check_lane(lane, STACK_BUNDLES[lane] as StackBundle);

package/src/scripts/lint_value_dashboard.ts

@@ -20,6 +20,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 _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const DASHBOARD = path.join(REPO_ROOT, 'docs', 'value.md');
@@ -176,9 +178,23 @@ function _seqEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
 function lint(quiet = false): number {
     const violations: string[] = [];
 
-    if (!_exists(DASHBOARD)) {
-        _log(`FAIL: dashboard not found: ${_relPosix(DASHBOARD, REPO_ROOT)}`, quiet, true);
-        return 1;
+    // Replaces the ad-hoc `_exists(DASHBOARD)` precondition. Only the dashboard
+    // is guarded: `LATEST` is genuinely optional (its absence is the documented
+    // "placeholder" success path below), so listing it here would let a moved
+    // dashboard pass whenever the report happened to exist. Exit 1 = the gate's
+    // only failure code.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_value_dashboard',
+            candidates: [_relPosix(DASHBOARD, REPO_ROOT)],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            _log(`FAIL: ${e.message}`, quiet, true);
+            return 1;
+        }
+        throw e;
     }
     const text = fs.readFileSync(DASHBOARD, 'utf-8');
     violations.push(...check_required_sections(text));

package/src/scripts/lint_versioned_cache.ts

@@ -31,6 +31,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const PROG = 'lint_versioned_cache.ts';
 
 /** Window (lines) around a cache-path literal scanned for a justification. */
@@ -135,7 +137,17 @@ export function scanFile(file: string, source: string): Violation[] {
 
 export function runChecks(root: string): Violation[] {
     const violations: Violation[] = [];
-    for (const file of listTsFiles(root)) {
+    const files = listTsFiles(root);
+    // The unit is every `.ts` walked — `.ts` defines this gate's corpus, while
+    // the cache-suffix match is the finding. Asserting on matches would read
+    // green for a moved `--dir` exactly as it does for a clean tree.
+    assertScanned({
+        gate: 'lint_versioned_cache',
+        scanned: files.length,
+        units: 'TypeScript file(s)',
+        roots: [root],
+    });
+    for (const file of files) {
         // Never lint this file itself — its regexes contain the very suffixes
         // it hunts for.
         if (path.basename(file) === 'lint_versioned_cache.ts') continue;
@@ -177,6 +189,12 @@ export function main(argv: string[]): number {
     try {
         violations = runChecks(path.resolve(dir));
     } catch (exc) {
+        // 3 (internal) over 2 (violations found): a dead `--dir` means the
+        // gate could not run, not that it found an unversioned cache.
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`${PROG}: ${exc.message}\n`);
+            return 3;
+        }
         process.stderr.write(`${PROG}: internal error: ${String(exc)}\n`);
         return 3;
     }

package/src/scripts/lint_workflow_security.ts

@@ -31,6 +31,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import YAML from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { py_json_dumps_indent2 } from './_lib/security_lint.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -72,14 +73,6 @@ function _isFile(p: string): boolean {
     }
 }
 
-function _isDir(p: string): boolean {
-    try {
-        return fs.statSync(p).isDirectory();
-    } catch {
-        return false;
-    }
-}
-
 function _asObject(v: JsonValue | undefined): JsonObject | null {
     if (v !== null && v !== undefined && typeof v === 'object' && !Array.isArray(v)) {
         return v as JsonObject;
@@ -557,18 +550,33 @@ export function main(argv?: string[]): number {
         throw e;
     }
 
-    if (!_isDir(WORKFLOWS_DIR)) {
-        if (!args.quiet) {
-            process.stderr.write(`No workflows directory found at ${WORKFLOWS_DIR}\n`);
+    // Replaces the former `!_isDir(WORKFLOWS_DIR)` → exit 0: a missing dir and
+    // an existing-but-empty one are the same blindness, and reporting
+    // "0 HIGH, 0 MEDIUM" over zero workflows is the vacuous pass.
+    const yml = _sortedGlob('.yml');
+    const yaml = _sortedGlob('.yaml');
+    try {
+        assertScanned({
+            gate: 'lint_workflow_security',
+            scanned: yml.length + yaml.length,
+            units: 'workflow file(s)',
+            roots: [WORKFLOWS_DIR],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            // 2 (the usage / could-not-run code) over 1, which means
+            // "a HIGH finding blocked under --strict".
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2;
         }
-        return 0;
+        throw e;
     }
 
     const all_findings: Finding[] = [];
-    for (const wf_path of _sortedGlob('.yml')) {
+    for (const wf_path of yml) {
         all_findings.push(...scan_workflow(wf_path, allowlist));
     }
-    for (const wf_path of _sortedGlob('.yaml')) {
+    for (const wf_path of yaml) {
         all_findings.push(...scan_workflow(wf_path, allowlist));
     }
 

package/src/scripts/pr_url_reminder_hook.ts

@@ -37,7 +37,7 @@ type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]:
 type JsonObject = { [k: string]: JsonValue };
 
 // Tool names across platforms whose command field carries a shell command
-// (kept in lock-step with verify_before_complete_hook.COMMAND_TOOLS).
+// (kept in lock-step with before_complete_hook.COMMAND_TOOLS).
 const COMMAND_TOOLS: ReadonlySet<string> = new Set([
   "launch-process",
   "launch_process",

package/src/scripts/skill_collision_clusters.ts

@@ -4,7 +4,7 @@
  *
  * Ported from the retired Python `skill_collision_clusters.py` (Phase 8 / Wave 8e).
  *
- * Walks `.agent-src.uncondensed/skills/<id>/SKILL.md`, extracts the
+ * Walks `src/skills/<id>/SKILL.md`, extracts the
  * `description` frontmatter, computes pairwise keyword overlap, and groups
  * high-overlap skill pairs into clusters. The output drives the
  * selection-accuracy fixture set defined by council file 05 (Round-3
@@ -18,11 +18,26 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { SRC_SKILLS } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 const REPO_ROOT = path.resolve(_HERE, '..', '..', '..');
-const SKILLS_DIR = path.join(REPO_ROOT, '.agent-src.uncondensed', 'skills');
-const OUT_JSON = path.join(REPO_ROOT, 'agents', 'reports', 'skill-collision-clusters.json');
+/**
+ * The live skills tree, via the shared ADR-051 resolver.
+ *
+ * This was a hardcoded path into the source container ADR-051 retired, so the
+ * gate read a directory that does not exist and clustered 0 of 288 skills. It
+ * was invisible for two reasons at once: the dead-root sweep and the hardening
+ * ratchet both defined "a gate" with a prefix set that excluded `skill_*`, so
+ * nothing in the repo was looking at it.
+ */
+const SKILLS_DIR = SRC_SKILLS();
+// `agents/runtime/reports/`, as this file's own header has always declared. The
+// code said `agents/reports/` (tracked) — harmless while the gate read a dead
+// root and never got far enough to write, load-bearing the moment it did.
+const OUT_JSON = path.join(REPO_ROOT, 'agents', 'runtime', 'reports', 'skill-collision-clusters.json');
 
 const KEYWORD_OVERLAP_THRESHOLD = 0.4;
 const MIN_SHARED_KEYWORDS = 3;
@@ -274,6 +289,25 @@ export function main(): number {
         process.stderr.write(`❌  Skills dir not found: ${SKILLS_DIR}\n`);
         return 2;
     }
+    // The dir-exists check above does not cover an existing-but-empty root — a
+    // stray retired-container directory left behind by a local test run passes
+    // it — which would write a `0 clusters from 0 skills` report and exit green.
+    // The unit is the SKILL.md files found, not the subset that parsed a
+    // description.
+    try {
+        assertScanned({
+            gate: 'skill_collision_clusters',
+            scanned: _sortedSkillMds().length,
+            units: 'SKILL.md file(s)',
+            roots: ['src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     const skills = load_skills();
     const clusters = build_clusters(skills);
     fs.mkdirSync(path.dirname(OUT_JSON), { recursive: true });

package/src/scripts/skill_discovery.ts

@@ -31,6 +31,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { load_agent_settings } from './_lib/agent_settings.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { event4u_root as _event4u_root_impl } from './_lib/user_global_paths.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -339,6 +340,25 @@ export function main(argv: string[] | null = null): number {
     }
 
     const catalog = load_catalog();
+    // A recommender still owes an honest scope: analytics events are optional
+    // and degrade gracefully by design, but a vanished skills projection makes
+    // every class recommend nothing while the run still reports success.
+    try {
+        assertScanned({
+            gate: 'skill_discovery',
+            scanned: catalog.size,
+            units: 'catalog skill(s)',
+            roots: ['dist/agent-src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 2 is this gate's only non-zero code (bad / missing role); here it
+            // reads as "could not run".
+            process.stderr.write(`${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     const shortlist = load_role_shortlist(role);
     const use_analytics = analytics_enabled(settings);
     const events = use_analytics ? load_analytics_events() : [];

package/src/scripts/skill_eval_coverage.ts

@@ -43,6 +43,8 @@ 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 REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -327,6 +329,26 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         }
     }
 
+    // Every mode below is decided by the skills walk, and every one of them
+    // reads innocently at zero: `--check` passes a floor of 0/0, `--write-floor`
+    // pins that emptiness as the new floor, and the report prints `n/a`.
+    try {
+        assertScanned({
+            gate: 'skill_eval_coverage',
+            scanned: _allSkills(_skillsDir({})).length,
+            units: 'skill(s)',
+            roots: ['src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 2 (usage) over 1, which this gate documents as a ratchet
+            // regression — a finding, not an inability to run.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     if (argv.includes('--write-floor')) {
         const report = writeFloor();
         process.stdout.write(

package/src/scripts/skill_overlap.ts

@@ -16,14 +16,25 @@ 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 { SRC_SKILLS } from './_lib/agent_src.js';
 import { pyRound } from './_lib/value_ladder.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 // parent.parent.parent of the .py file (src/scripts/skill_overlap.py) is the
 // repo root — two dirs up from src/scripts.
 const REPO = path.resolve(_HERE, '..', '..');
-const SKILLS = path.join(REPO, '.agent-src.uncondensed', 'skills');
-const OUT = path.join(REPO, 'agents', 'metrics', 'skill-overlap.md');
+// The live skills tree via the shared ADR-051 resolver. This was a hardcoded
+// path into the source container ADR-051 retired, so the gate
+// scored overlap across 0 of 288 skills. Invisible until the hardening
+// population stopped excluding the `skill_*` prefix.
+const SKILLS = SRC_SKILLS();
+// `agents/metrics/` was retired by the agents/ taxonomy consolidation, and
+// `agents/reports/skill-overlap.md` is written by the successor gate
+// `audit_skill_overlap` — writing there would silently clobber it. Runtime is
+// the typed, gitignored home for a report nothing tracks. Reviving a gate whose
+// scan root was dead also revives its writes; this one had nowhere legal to land.
+const OUT = path.join(REPO, 'agents', 'runtime', 'reports', 'skill-overlap.md');
 
 const STRONG_TOKEN = 0.6;
 const STRONG_SYMBOL = 0.6;
@@ -290,7 +301,7 @@ export function render(pairs: Pair[], total: number): string {
         '# Skill Structural Overlap (baseline)',
         '',
         '> Generated by `scripts/skill_overlap.py`. Scans',
-        '> `.agent-src.uncondensed/skills/*/SKILL.md` frontmatter (description +',
+        '> `src/skills/*/SKILL.md` frontmatter (description +',
         '> trigger metadata) and body symbol references. Reports pairs in two',
         `> tiers: **strong** ≥ ${pyFloatStr(STRONG_TOKEN)} description-token Jaccard or ≥ ${pyFloatStr(STRONG_SYMBOL)}`,
         `> symbol-set Jaccard (roadmap floor); **candidate** ≥ ${pyFloatStr(CANDIDATE_TOKEN)} / ≥ ${pyFloatStr(CANDIDATE_SYMBOL)}`,
@@ -375,9 +386,24 @@ export function parse_args(argv: string[]): ParsedArgs {
 export function main(argv?: string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
     const skills = load_skills(SKILLS);
-    if (!skills.length) {
-        process.stderr.write(`no skills under ${SKILLS}\n`);
-        return 1;
+    try {
+        // A report is a certification too: writing `Skills scanned: 0` into the
+        // baseline is the same lie a green gate tells, in a quieter voice.
+        assertScanned({
+            gate: 'skill_overlap',
+            scanned: skills.length,
+            units: 'skill(s)',
+            roots: ['src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // `no skills under <root>` is the pinned line; the assertion's
+            // named-root detail follows rather than replaces it.
+            process.stderr.write(`no skills under ${SKILLS}\n`);
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const pairs = analyse(skills);
     fs.mkdirSync(path.dirname(args.out), { recursive: true });

package/src/scripts/skill_preview.ts

@@ -24,6 +24,8 @@ import { fileURLToPath } from 'node:url';
 import { pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/skill_preview.ts → parents[2] is the package root (mirrors the
 // Python module's parent.parent.parent resolution).
@@ -513,6 +515,35 @@ export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
     const name = args.name as string;
 
+    // A reporting tool, not a CI gate — but a moved corpus makes it answer
+    // "no skill named X" for EVERY name, which reads as the caller's typo
+    // rather than as a dead root. The corpus is in-repo (unlike a $HOME
+    // session directory, which may legitimately be empty in CI), so zero
+    // skill directories is never a valid state. Exit 2 is the existing
+    // "cannot preview" code; there is no other failure code.
+    let corpus = 0;
+    try {
+        corpus = fs
+            .readdirSync(_SKILLS_DIR, { withFileTypes: true })
+            .filter((e) => e.isDirectory()).length;
+    } catch {
+        corpus = 0;
+    }
+    try {
+        assertScanned({
+            gate: 'skill_preview',
+            scanned: corpus,
+            units: 'skill director(ies)',
+            roots: [path.relative(REPO_ROOT, _SKILLS_DIR) || _SKILLS_DIR],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     let preview: Preview;
     try {
         preview = load_preview(name);

package/src/scripts/skill_trigger_eval.ts

@@ -22,6 +22,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots, resolve_logical } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import * as user_global_paths from './_lib/user_global_paths.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -966,6 +967,23 @@ export function main(argv?: string[]): number {
     }
 
     const skills = load_skill_metas();
+    // The full catalogue IS the routing condition — an empty one still yields
+    // a complete-looking result file with precision/recall computed over a
+    // router that was never given anything to choose from.
+    try {
+        assertScanned({
+            gate: 'skill_trigger_eval',
+            scanned: skills.length,
+            units: 'catalogue skill(s)',
+            roots: ['src/skills', 'src/agent-src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     let router: TriggerRouter;
     let defaultOutput: string;
     if (args.dry_run) {