@event4u/agent-config 9.20.0 → 9.22.0

package/src/scripts/lint_hook_concern_budget.ts

@@ -25,6 +25,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { project_settings_path } from './_lib/agent_settings.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -148,14 +149,16 @@ function _isPlainDict(v: unknown): v is Record<string, unknown> {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
+/** @returns the number of platform/event concern lists inspected. */
 function _check_concern_counts(
     manifest: Manifest,
     max_per_event: number,
     warnings: string[],
-): void {
+): number {
+    let inspected = 0;
     const platforms = manifest['platforms'] ?? {};
     if (!_isPlainDict(platforms)) {
-        return;
+        return inspected;
     }
     for (const [plat, block] of Object.entries(platforms)) {
         if (!_isPlainDict(block) || block['fallback_only']) {
@@ -165,6 +168,7 @@ function _check_concern_counts(
             if (!Array.isArray(names)) {
                 continue;
             }
+            inspected += 1;
             const count = names.length;
             if (count > max_per_event) {
                 warnings.push(
@@ -175,18 +179,22 @@ function _check_concern_counts(
             }
         }
     }
+    return inspected;
 }
 
-function _check_fail_closed_tier(manifest: Manifest, tier1: string[], errors: string[]): void {
+/** @returns the number of concern declarations inspected. */
+function _check_fail_closed_tier(manifest: Manifest, tier1: string[], errors: string[]): number {
+    let inspected = 0;
     const concerns = manifest['concerns'] ?? {};
     if (!_isPlainDict(concerns)) {
-        return;
+        return inspected;
     }
     const allowed = new Set(tier1);
     for (const [name, spec] of Object.entries(concerns)) {
         if (!_isPlainDict(spec)) {
             continue;
         }
+        inspected += 1;
         if (spec['fail_closed'] === true && !allowed.has(name)) {
             errors.push(
                 `concerns.${name}: fail_closed=true but not declared in ` +
@@ -195,6 +203,7 @@ function _check_fail_closed_tier(manifest: Manifest, tier1: string[], errors: st
             );
         }
     }
+    return inspected;
 }
 
 export function lint(
@@ -227,8 +236,32 @@ export function lint(
 
     const warnings: string[] = [];
     const errors: string[] = [];
-    _check_concern_counts(manifest, max_per_event, warnings);
-    _check_fail_closed_tier(manifest, tier1, errors);
+    const inspected =
+        _check_concern_counts(manifest, max_per_event, warnings) +
+        _check_fail_closed_tier(manifest, tier1, errors);
+
+    // The manifest loads and parses, then every walk below silently tolerates a
+    // shape it does not recognise — no `platforms:`, no `concerns:`, a renamed
+    // top-level key — and the gate exits 0 having budgeted nothing. Counts units
+    // INSPECTED (platform/event concern lists + concern declarations), not
+    // warnings or errors. Exit 1 is the load-failure code and is the right one
+    // here: the manifest was readable but carried nothing this gate governs; 2
+    // is reserved for a hard-fail WITH violations.
+    try {
+        assertScanned({
+            gate: 'lint_hook_concern_budget',
+            scanned: inspected,
+            units: 'manifest concern unit(s)',
+            roots: [manifest_path],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // The message already carries the gate name as its prefix.
+            process.stderr.write(`${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
 
     for (const w of warnings) {
         process.stderr.write(`warn: ${w}\n`);

package/src/scripts/lint_hook_manifest.ts

@@ -28,6 +28,8 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 
+import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
+
 // src/scripts/lint_hook_manifest.ts → two levels up is the repo root.
 const REPO_ROOT = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -322,6 +324,26 @@ export function lint(manifestPath: string, strict: boolean): number {
     process.stderr.write(`error: ${e}\n`);
   }
 
+  // Concerns are the units read — each one resolves a script path on disk.
+  // Runs after the findings are printed so the existing `'concerns' must be a
+  // non-empty mapping` line still reaches the caller. Exit 1, not 2: the
+  // manifest loaded fine (2 is reserved for a file that could not be read or
+  // parsed); what is empty is its declared scope.
+  try {
+    assertScanned({
+      gate: "lint_hook_manifest",
+      scanned: concernNames.size,
+      units: "concern(s)",
+      roots: [manifestPath],
+    });
+  } catch (exc) {
+    if (exc instanceof DeadScopeError) {
+      process.stderr.write(`error: ${exc.message}\n`);
+      return 1;
+    }
+    throw exc;
+  }
+
   if (errors.length > 0) {
     return 1;
   }

package/src/scripts/lint_instruction_smuggling.ts

@@ -28,6 +28,7 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 export const CHECK = 'instruction-smuggling';
 
@@ -152,12 +153,34 @@ export function main(argv: readonly string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const findings: sl.Finding[] = [];
+    let corpusFiles = 0;
     for (const sf of sl.iter_corpus()) {
+        corpusFiles += 1;
         for (const h of _scan(sf)) {
             findings.push(h);
         }
     }
 
+    // `iter_corpus` skips a root that does not exist, so a moved corpus yields
+    // zero files and this security lint reports "clean" — and the umbrella
+    // aggregate reads that as 0 blocking findings. Count files READ, not
+    // findings. Exit 1 is this CLI's only failure code (2 is reserved for the
+    // pinned argparse usage error), so it carries "could not run" here.
+    try {
+        assertScanned({
+            gate: 'lint_instruction_smuggling',
+            scanned: corpusFiles,
+            units: 'corpus file(s)',
+            roots: sl.DEFAULT_SCAN_ROOTS,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     if (args.json) {
         const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
         process.stdout.write(payload + '\n');

package/src/scripts/lint_knowledge_scale.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_knowledge_scale.ts';
 
 export const INTAKE_EVENTS_MAX = 2000;
@@ -109,7 +111,12 @@ export function collectTypeCounts(root: string): Map<string, number> {
     return counts;
 }
 
-export function runChecks(root: string): Warning[] {
+/** Out-param so the caller can assert the scope it just walked. */
+export interface ScanStats {
+    corpusFiles: number;
+}
+
+export function runChecks(root: string, stats?: ScanStats): Warning[] {
     const warnings: Warning[] = [];
 
     // 1. Intake scale.
@@ -156,6 +163,9 @@ export function runChecks(root: string): Warning[] {
             });
         }
     }
+    if (stats) {
+        stats.corpusFiles = total;
+    }
     if (total > CORPUS_FILES_MAX) {
         warnings.push({
             rule: 'corpus-scale',
@@ -252,12 +262,32 @@ function main(argv: string[]): number {
     }
 
     let warnings: Warning[];
+    const stats: ScanStats = { corpusFiles: 0 };
     try {
-        warnings = runChecks(path.resolve(dir));
+        warnings = runChecks(path.resolve(dir), stats);
     } catch (exc) {
         process.stderr.write(`${PROG}: internal error: ${String(exc)}\n`);
         return 3;
     }
+    try {
+        assertScanned({
+            gate: 'lint_knowledge_scale',
+            scanned: stats.corpusFiles,
+            units: 'knowledge/memory file(s)',
+            roots: ['agents/knowledge', 'agents/memory'],
+            allowEmpty:
+                'OPTIONAL_INPUT: the memory/knowledge substrate accumulates in the consumer ' +
+                'tree over time — a project that has recorded nothing yet has no corpus, and ' +
+                'the tripwires it would trip are all upper bounds. Delete both roots and zero ' +
+                'still means "nothing recorded", never "the scale checks stopped looking".',
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`${PROG}: ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
 
     if (format === 'json') {
         process.stdout.write(JSON.stringify({ warnings }, null, 2) + '\n');

package/src/scripts/lint_legal_pack.ts

@@ -24,6 +24,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.includes('--quiet');
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -246,7 +248,36 @@ export function lintLegalPack(skillsDir: string = SKILLS_DIR): Violation[] {
     return violations;
 }
 
+/** SKILL.md files under `skillsDir` — the corpus `lintLegalPack` walks. */
+function countSkillFiles(skillsDir: string = SKILLS_DIR): number {
+    try {
+        return fs
+            .readdirSync(skillsDir)
+            .filter((d) => fs.existsSync(path.join(skillsDir, d, 'SKILL.md'))).length;
+    } catch {
+        return 0;
+    }
+}
+
 export function main(): number {
+    // The unit is every SKILL.md, not the `packs: [legal-review-prep]` subset:
+    // the pack is opt-in, so a zero-legal-pack-skills count is a normal state
+    // and asserting on it would prove nothing. Over a vanished src/skills the
+    // subset is zero too — indistinguishable from "the pack is not installed".
+    try {
+        assertScanned({
+            gate: 'lint_legal_pack',
+            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 violations = lintLegalPack();
     if (violations.length === 0) {
         _print('✅  legal pack — all legal-pack skills carry the attorney-review line + Jurisdiction tag');

package/src/scripts/lint_marketplace.ts

@@ -27,6 +27,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { assertWatchlistResolves, DeadScopeError } from "./_lib/scan_scope.js";
+
 const ROOT = ".";
 const MARKETPLACE = path.join(ROOT, ".claude-plugin", "marketplace.json");
 const PACKAGE_JSON = path.join(ROOT, "package.json");
@@ -87,6 +89,30 @@ function require_key(
 }
 
 export function main(): number {
+  // No corpus to count — the shim is exactly one manifest plus one pointer
+  // skill, and every count the shape offers (plugins, skill entries, dirs under
+  // .claude-plugin/skills/) is a value an existing negative case drives to zero
+  // on purpose. What CAN vanish is the fixed set of paths this resolves against
+  // cwd, so the watch list is the honest guard: run from the wrong directory
+  // and the gate now says so instead of reporting a missing manifest.
+  try {
+    assertWatchlistResolves({
+      gate: "lint_marketplace",
+      candidates: [
+        ".claude-plugin/marketplace.json",
+        "package.json",
+        `${POINTER_SKILL_ENTRY.replace(/^\.\//, "")}/SKILL.md`,
+      ],
+      repoRoot: path.resolve(ROOT),
+    });
+  } catch (exc) {
+    if (exc instanceof DeadScopeError) {
+      process.stdout.write(`❌  ${exc.message}\n`);
+      return 1;
+    }
+    throw exc;
+  }
+
   if (!_exists(MARKETPLACE)) {
     process.stdout.write(`❌  ${MARKETPLACE} not found\n`);
     return 1;

package/src/scripts/lint_marketplace_install_completeness.ts

@@ -25,6 +25,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/lint_marketplace_install_completeness.ts → two dirs up is the
@@ -150,6 +152,27 @@ function lint(
     const commands = load_hook_commands(hooks_path);
     const known = load_dispatcher_subcommands(dispatch_path);
 
+    // `load_hook_commands` skips every non-conforming `hooks` shape silently, so
+    // a restructured hooks.json yields an empty command list and the gate
+    // announces "0 hook command(s) checked" — green. Assert the UNFILTERED list:
+    // `checked` below excludes entries whose command line failed to parse, and
+    // those are exactly the ones this gate must still report on. Exit 2 is the
+    // schema/file-error code ("could not run"); 1 means an unknown subcommand.
+    try {
+        assertScanned({
+            gate: 'lint-marketplace-install',
+            scanned: commands.length,
+            units: 'hook command(s)',
+            roots: [hooks_path],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     const issues: string[] = [];
     let checked = 0;
     for (const [event, cmd] of commands) {

package/src/scripts/lint_mcp_config_security.ts

@@ -24,6 +24,7 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 export const CHECK = 'mcp-config-security';
 
@@ -204,12 +205,35 @@ export function main(argv: readonly string[] | null = null): number {
     // scan .md (fenced examples) under the default roots PLUS named MCP configs
     // under src/templates (where the shipped claude_desktop_config template lives).
     const roots = [...sl.DEFAULT_SCAN_ROOTS, 'src/templates'];
+    let corpusFiles = 0;
     for (const sf of sl.iter_corpus(roots, ['.md', '.json', '.template'])) {
+        corpusFiles += 1;
         for (const h of _scan(sf)) {
             findings.push(h);
         }
     }
 
+    // `iter_corpus` skips a root that does not exist, so a moved
+    // `src/templates` (where the only shipped MCP config template lives) leaves
+    // this lint scanning `.md` fences alone — or nothing at all — while still
+    // printing "clean". Count files READ, not findings. Exit 1 is this CLI's
+    // only failure code (2 is the pinned argparse usage error), so it carries
+    // "could not run" here.
+    try {
+        assertScanned({
+            gate: 'lint_mcp_config_security',
+            scanned: corpusFiles,
+            units: 'corpus file(s)',
+            roots,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     if (args.json) {
         const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
         process.stdout.write(payload + '\n');

package/src/scripts/lint_mcp_registry_manifest.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 _HERE = path.resolve(fileURLToPath(import.meta.url));
 // ROOT = Path(__file__).resolve().parents[2]
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -295,7 +297,26 @@ function main(argv: readonly string[]): number {
         throw e;
     }
 
-    for (const p of [SCHEMA, MANIFEST, ROW_MD, CF_JSON, SERVER_JSON]) {
+    const artefacts = [SCHEMA, MANIFEST, ROW_MD, CF_JSON, SERVER_JSON];
+    // The per-artefact loop below stays authoritative — it names the FIRST
+    // missing file and is the pinned `missing: <path>` contract. This assertion
+    // covers the case that loop reports misleadingly: all five gone at once,
+    // which is a relocated ROOT rather than an unbuilt artefact, and deserves a
+    // message that says so. Exit 1 is the gate's only failure code.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_mcp_registry_manifest',
+            candidates: artefacts.map(_relToRoot),
+            repoRoot: ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    for (const p of artefacts) {
         if (!fs.existsSync(p)) {
             return _fail(`missing: ${_relToRoot(p)}`);
         }

package/src/scripts/lint_memory_tripwire.ts

@@ -24,6 +24,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -73,6 +75,15 @@ function _git(root: string, args: string[]): string {
     return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
 }
 
+/** How many tracked memory files `scanWorktree` has to read (0 when git fails). */
+function _trackedCount(root: string): number {
+    try {
+        return _git(root, ['ls-files', TRACKED_GLOB_ROOT]).split('\n').filter(Boolean).length;
+    } catch {
+        return 0;
+    }
+}
+
 /** Scan the current worktree's tracked memory files. */
 export function scanWorktree(root: string): Hit[] {
     const out: Hit[] = [];
@@ -147,6 +158,15 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             process.stdout.write(
                 `scanned ${commits} commit(s), ${blobs} unique blob(s) under ${TRACKED_GLOB_ROOT}\n`,
             );
+            // The honest-null verdict rests on this scan having covered the
+            // full history; a "zero fires" certification over zero blobs would
+            // silently re-certify nothing at all.
+            assertScanned({
+                gate: 'lint_memory_tripwire',
+                scanned: blobs,
+                units: 'historical blob(s)',
+                roots: [TRACKED_GLOB_ROOT],
+            });
             if (hits.length === 0) {
                 process.stdout.write('✅  zero tripwire fires across the full history.\n');
                 return 0;
@@ -157,6 +177,15 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             process.stdout.write(`❌  ${hits.length} fire(s). HALT — never rewrite; a human decides.\n`);
             return 1;
         }
+        // Count the corpus separately from the hits: `scanWorktree` returns
+        // only fires, and "no fires" is the pass state, so an unlistable or
+        // moved agents/memory tree would otherwise read as clean.
+        assertScanned({
+            gate: 'lint_memory_tripwire',
+            scanned: _trackedCount(root),
+            units: 'tracked memory file(s)',
+            roots: [TRACKED_GLOB_ROOT],
+        });
         const hits = scanWorktree(root);
         if (hits.length === 0) {
             process.stdout.write('✅  tripwire clean on tracked memory files.\n');
@@ -168,6 +197,12 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         process.stdout.write(`❌  ${hits.length} fire(s). HALT — never rewrite; a human decides.\n`);
         return 1;
     } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // A dead scope is a tripwire failure, not an internal fault: the
+            // gate reports the same HALT code it uses for a fire.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
         process.stderr.write(`lint_memory_tripwire: internal error: ${String(exc)}\n`);
         return 3;
     }

package/src/scripts/lint_missions.ts

@@ -35,6 +35,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);
 
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -684,16 +686,30 @@ export function main(argv?: string[]): number {
     const mission_schema = _load_schema(MISSION_SCHEMA_PATH);
     const catalog_schema = _load_schema(CATALOG_SCHEMA_PATH);
 
-    if (!_isDir(MISSIONS_ROOT)) {
-        if (!args.quiet) {
-            process.stderr.write(`No missions directory found at ${MISSIONS_ROOT}\n`);
-        }
-        return 0;
-    }
-
     const all_findings: Finding[] = [];
     const mission_dirs = _sortedMissionDirs();
 
+    // Supersedes the `No missions directory found → exit 0` short-circuit: this
+    // gate is warn-only about what a mission SAYS, never about whether there are
+    // missions to read, and a missing root produced the same silent 0 as a clean
+    // run. Exit 1 is the hard-failure code (2 is reserved for argparse and
+    // schema-load errors), and it fires regardless of --strict — a scope that
+    // read nothing is not a warning about a manifest.
+    try {
+        assertScanned({
+            gate: 'lint_missions',
+            scanned: mission_dirs.length,
+            units: 'mission(s)',
+            roots: ['src/missions'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     for (const mission_dir of mission_dirs) {
         const findings = validate_mission(mission_dir, mission_schema, catalog_schema);
         all_findings.push(...findings);

package/src/scripts/lint_model_tier_coverage.ts

@@ -23,6 +23,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse_frontmatter } from './validate_frontmatter.js';
 import { artefact_roots, iter_commands } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -99,6 +100,23 @@ function main(argv: readonly string[]): number {
         }
     }
 
+    // `total` is the artefacts read, `missing` the verdict — a coverage gate
+    // whose enumerator yields nothing reports full coverage of nothing.
+    try {
+        assertScanned({
+            gate: 'lint_model_tier_coverage',
+            scanned: total,
+            units: 'artefact(s)',
+            roots: ['src/skills', 'src/agent-src/commands', 'src/domains'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     if (missing.length > 0) {
         for (const [kind, rel] of missing.slice(0, 40)) {
             process.stdout.write(

package/src/scripts/lint_namespace_collisions.ts

@@ -29,6 +29,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { iter_all_sources } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -135,6 +136,24 @@ function main(): number {
         }
     }
 
+    // `total` is the names read, not the collisions found: uniqueness holds
+    // vacuously over an empty name space, so only the corpus count can tell
+    // "no collisions" apart from "no artefacts reached the normalizer".
+    try {
+        assertScanned({
+            gate: 'lint_namespace_collisions',
+            scanned: total,
+            units: 'artefact name(s)',
+            roots: ['src/skills', 'src/rules', 'src/agent-src/commands', 'src/domains'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const collisions = [...seen.entries()].filter(([, v]) => v.length > 1);
     if (collisions.length) {
         // sorted(collisions) — by (namespace, name) tuple, which the key