@event4u/agent-config 9.20.0 → 9.22.0

package/src/scripts/lint_pre_migration_refs.ts

@@ -30,6 +30,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 
 const PATTERNS: readonly { re: RegExp; label: string }[] = [
@@ -72,6 +74,7 @@ export function scanText(relPath: string, text: string): string[] {
 
 export function main(): number {
     const findings: string[] = [];
+    let scanned = 0;
     for (const rel of shippedTrackedFiles()) {
         if (CARVE_OUTS.has(rel)) continue;
         if (SKIP_EXT.has(path.extname(rel))) continue;
@@ -83,8 +86,29 @@ export function main(): number {
         } catch {
             continue;
         }
+        scanned += 1;
         findings.push(...scanText(rel, text));
     }
+    // The scope is an intersection — `git ls-files` ∩ the package.json `files`
+    // whitelist — and either side collapsing to nothing (no git, a rewritten
+    // whitelist) leaves the gate printing "no pre-migration install hints"
+    // over an empty set. Counts files whose text was READ, which is zero
+    // whenever the enumeration itself is empty. Exit 2 is the internal-error
+    // code ("could not run"); 1 means a live hint was found.
+    try {
+        assertScanned({
+            gate: 'lint_pre_migration_refs',
+            scanned,
+            units: 'shipped tracked file(s)',
+            roots: ['git ls-files ∩ package.json files[]'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     if (findings.length > 0) {
         for (const f of findings) {
             process.stderr.write(`❌  pre-migration reference: ${f}\n`);

package/src/scripts/lint_profile_overlay_set_only.ts

@@ -21,6 +21,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);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const ALIASES_YML = path.join(REPO_ROOT, 'src/config/discovery/session-profiles.yml');
@@ -237,11 +239,13 @@ function lint(quiet = false): number {
         ['profile', PROFILES_DIR, 'profile', 'packs'],
         ['pack', PACKS_DIR, 'pack', null],
     ];
+    let definitions = 0;
     for (const [, directory, rootKey, seedKey] of dirs) {
         if (!_exists(directory)) {
             continue;
         }
         for (const p of _globYmlSorted(directory)) {
+            definitions += 1;
             const doc = _load_yaml(p);
             if (!_isPlainObject(doc)) {
                 continue;
@@ -291,6 +295,26 @@ function lint(quiet = false): number {
         }
     }
 
+    // Clauses 1b/2a/2b run per static definition file, and both their roots are
+    // skipped silently when absent — so the whole per-file half of this lint can
+    // go quiet while clause 1a keeps printing an alias count. Counted before the
+    // parse filter above: an unparseable file is still a file that was walked.
+    try {
+        assertScanned({
+            gate: 'lint_profile_overlay_set_only',
+            scanned: definitions,
+            units: 'static definition file(s)',
+            roots: ['src/agent-src/profiles', 'src/agent-src/packs'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            // 1 is this CLI's only failure code — pinned by the ported contract.
+            process.stderr.write(`❌ ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+
     if (errors.length > 0) {
         for (const e of errors) {
             process.stderr.write(`❌ ${e}\n`);

package/src/scripts/lint_provenance.ts

@@ -54,6 +54,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const _FILE = fileURLToPath(import.meta.url);
 const _HERE = path.dirname(_FILE);
 // src/scripts/lint_provenance.ts → two levels up is the repo root.
@@ -480,6 +482,25 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const args = parseArgs(argv);
     const ledgerPath = path.join(REPO, LEDGER_REL);
     const noticesPath = path.join(REPO, NOTICES_REL);
+    // The ledger is the record this gate audits. Record COUNT is not the scope
+    // signal — an empty ledger is a legitimate "no borrows yet" state (it is
+    // empty today) — but an absent ledger file is not: the `existsSync ? … : ''`
+    // fallback below would read a moved ledger as zero borrows and re-render the
+    // notices to match, laundering the loss into a clean sync. Exit 2 is this
+    // linter's single failure code ("this run produced nothing trustworthy").
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_provenance',
+            candidates: [LEDGER_REL],
+            repoRoot: REPO,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     const text = fs.existsSync(ledgerPath) ? fs.readFileSync(ledgerPath, 'utf-8') : '';
     const deny = resolveDenyPolicy(REPO);
     const { records, findings } = lintLedgerText(text, REPO, deny);

package/src/scripts/lint_provenance_vocabulary.ts

@@ -38,6 +38,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 CLAIMS_LEDGER_REL = 'docs/CLAIMS.md';
@@ -384,6 +386,16 @@ export function lintProvenanceVocabulary(repoRoot: string = REPO_ROOT): Violatio
     for (const root of SCAN_ROOTS) {
         for (const f of _collectMd(path.join(repoRoot, root))) files.add(f);
     }
+    // `_collectMd` returns [] for a root that is not there, so a moved docs
+    // tree turns the honesty floor into a no-op that still prints its ✅ line.
+    // Counted over every markdown file walked — the banned-phrase scan reads
+    // all of them, long before any approved-vocabulary filtering.
+    assertScanned({
+        gate: 'lint_provenance_vocabulary',
+        scanned: files.size,
+        units: 'prose file(s)',
+        roots: SCAN_ROOTS,
+    });
     for (const abs of [...files].sort()) {
         const rel = path.relative(repoRoot, abs);
         const text = fs.readFileSync(abs, 'utf-8');
@@ -398,7 +410,18 @@ function _print(quiet: boolean, msg: string): void {
 
 export function main(): number {
     const quiet = process.argv.slice(2).includes('--quiet');
-    const violations = lintProvenanceVocabulary();
+    let violations: Violation[];
+    try {
+        violations = lintProvenanceVocabulary();
+    } catch (e) {
+        // 1 is the only failure code this gate defines, so a dead scan root and
+        // a real violation share it — the message distinguishes them.
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
     if (violations.length > 0) {
         for (const v of violations) {
             process.stderr.write(`❌ [${v.rule}] ${v.file}: ${v.msg}\n`);

package/src/scripts/lint_readme_jargon.ts

@@ -18,6 +18,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 README = 'README.md';
@@ -124,9 +126,25 @@ function _pyRepr(s: string): string {
 
 function main(): number {
     const quiet = process.argv.slice(2).includes('--quiet');
-    if (!fs.existsSync(README)) {
-        process.stderr.write(`error: ${README} not found\n`);
-        return 1;
+    // README is this gate's whole scope and resolves against cwd, so a wrong
+    // cwd is indistinguishable from a deleted file. Replaces the bare
+    // existsSync check: same exit code, but the failure now names the root it
+    // looked under. Exit 1 is the only failure code this CLI has (over budget /
+    // missing) — here it means "could not run", not "over budget".
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_readme_jargon',
+            candidates: [README],
+            repoRoot: process.cwd(),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // First line is the pinned py2ts wording; the second names the root.
+            process.stderr.write(`error: ${README} not found\n`);
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
 
     const allLines = _splitlines(fs.readFileSync(README, 'utf-8'));

package/src/scripts/lint_readme_serial_comma.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 README = 'README.md';
@@ -116,9 +118,25 @@ function collect_hits(text: string): Hit[] {
 
 function main(): number {
     const quiet = process.argv.slice(2).includes('--quiet');
-    if (!fs.existsSync(README)) {
-        process.stderr.write(`error: ${README} not found\n`);
-        return 1;
+    // README is this gate's whole scope and resolves against cwd, so a wrong
+    // cwd is indistinguishable from a deleted file. Replaces the bare
+    // existsSync check: same exit code, but the failure now names the root it
+    // looked under. Exit 1 is the only failure code this CLI has (violation /
+    // missing) — here it means "could not run", not "violation found".
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_readme_serial_comma',
+            candidates: [README],
+            repoRoot: process.cwd(),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // First line is the pinned wording; the second names the root.
+            process.stderr.write(`error: ${README} not found\n`);
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
 
     const hits = collect_hits(fs.readFileSync(README, 'utf-8'));

package/src/scripts/lint_readme_size.ts

@@ -16,6 +16,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 README = 'README.md';
@@ -45,9 +47,25 @@ function _splitlinesCount(text: string): number {
 
 function main(): number {
     const quiet = process.argv.slice(2).includes('--quiet');
-    if (!fs.existsSync(README)) {
-        process.stderr.write(`error: ${README} not found\n`);
-        return 1;
+    // README is this gate's whole scope and resolves against cwd, so a wrong
+    // cwd is indistinguishable from a deleted file. Replaces the bare
+    // existsSync check: same exit code, but the failure now names the root it
+    // looked under. Exit 1 is the only failure code this CLI has (over budget /
+    // missing) — here it means "could not run", not "over budget".
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_readme_size',
+            candidates: [README],
+            repoRoot: process.cwd(),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // First line is the pinned py2ts wording; the second names the root.
+            process.stderr.write(`error: ${README} not found\n`);
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const text = fs.readFileSync(README, 'utf-8');
     const n = _splitlinesCount(text);

package/src/scripts/lint_regression.ts

@@ -24,6 +24,8 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 interface FileEntry {
     status: string;
     codes: Set<string>;
@@ -519,6 +521,32 @@ function main(): number {
     // Sanity guard: two non-empty result sets sharing no file → not comparable.
     const baseKeys = Object.keys(baseline_map);
     const currKeys = Object.keys(current_map);
+
+    // The asserted unit is the WORKING TREE's linted-file population, not the
+    // baseline's. Baseline emptiness has two documented, legitimate causes (no
+    // linter file in the ref; a pre-migration `.py` baseline with no python3)
+    // and its own guard below, so asserting there would re-litigate the false
+    // reds this script already carries scars from. An empty CURRENT tree has no
+    // legitimate cause: it means the linter's corpus moved. Both guards below
+    // require `currKeys.length`, so today that case slips through all of them
+    // and every prior finding is reported as an improvement — exit 0.
+    // Exit 2 is the "runs are not comparable / could not run" code both guards
+    // already use; 1 stays "regressions found".
+    try {
+        assertScanned({
+            gate: 'lint_regression',
+            scanned: currKeys.length,
+            units: 'linted file(s) in the working tree',
+            roots: [`${root} (skill_linter --all)`],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`Error: ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
     const shared = baseKeys.some((k) => k in current_map);
     if (baseKeys.length && currKeys.length && !shared) {
         process.stderr.write(

package/src/scripts/lint_roadmap_blockers.ts

@@ -20,6 +20,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const QUIET = process.argv.slice(2).includes('--quiet');
 
@@ -154,7 +156,48 @@ function _relPosix(target: string, root: string): string {
     return path.relative(root, target).split(path.sep).join('/');
 }
 
+/**
+ * Every `*.md` anywhere under the roadmap tree — active plus `archive/`,
+ * `later/`, `skipped/`.
+ *
+ * The active glob is the subset this gate judges, and it reaches zero
+ * legitimately once everything is archived, so it cannot double as the scope
+ * assertion. The whole tree reaching zero has only one cause: the root moved.
+ */
+function _countRoadmapTree(dir: string): number {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return 0;
+    }
+    let n = 0;
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            n += _countRoadmapTree(path.join(dir, entry.name));
+        } else if (entry.name.endsWith('.md')) {
+            n += 1;
+        }
+    }
+    return n;
+}
+
 function main(): number {
+    try {
+        assertScanned({
+            gate: 'lint_roadmap_blockers',
+            scanned: _countRoadmapTree(path.join(REPO_ROOT, 'agents', 'roadmaps')),
+            units: 'roadmap file(s)',
+            roots: ['agents/roadmaps'],
+        });
+    } catch (e) {
+        // 1 is the only failure code this gate defines.
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
     const roadmaps = _globRoadmaps();
     if (roadmaps.length === 0) {
         if (!QUIET) {

package/src/scripts/lint_roadmap_ci_steps.ts

@@ -21,6 +21,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { project_settings_path } from './_lib/agent_settings.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const QUIET = process.argv.slice(2).includes('--quiet');
@@ -173,6 +174,32 @@ function _relPosix(target: string, root: string): string {
     return path.relative(root, target).split(path.sep).join('/');
 }
 
+/**
+ * Every `*.md` anywhere under the roadmap tree — active plus `archive/`,
+ * `later/`, `skipped/`.
+ *
+ * The active glob is the subset this gate judges, and it reaches zero
+ * legitimately once everything is archived, so it cannot double as the scope
+ * assertion. The whole tree reaching zero has only one cause: the root moved.
+ */
+function _countRoadmapTree(dir: string): number {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return 0;
+    }
+    let n = 0;
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            n += _countRoadmapTree(path.join(dir, entry.name));
+        } else if (entry.name.endsWith('.md')) {
+            n += 1;
+        }
+    }
+    return n;
+}
+
 function main(): number {
     if (_read_local_auto_run()) {
         if (!QUIET) {
@@ -182,6 +209,24 @@ function main(): number {
         }
         return 0;
     }
+    // Asserted only past the disabled-return: a declared no-op reads nothing by
+    // design, and failing there would red every repo that leaves the setting
+    // unset. Past it the gate claims to be armed, so its root must resolve.
+    try {
+        assertScanned({
+            gate: 'lint_roadmap_ci_steps',
+            scanned: _countRoadmapTree(path.join(REPO_ROOT, 'agents', 'roadmaps')),
+            units: 'roadmap file(s)',
+            roots: ['agents/roadmaps'],
+        });
+    } catch (e) {
+        // 1 is the only failure code this gate defines.
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
     const roadmaps = _globRoadmaps();
     if (roadmaps.length === 0) {
         if (!QUIET) {

package/src/scripts/lint_roadmap_complexity.ts

@@ -20,6 +20,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { project_settings_path } from './_lib/agent_settings.js';
+import { granularity_problems } from './_lib/roadmap_granularity.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 /** Mirror `QUIET = "--quiet" in sys.argv` (computed at import). */
 const QUIET = process.argv.slice(2).includes('--quiet');
@@ -184,6 +186,10 @@ function lint_roadmap(
     if (complexity === 'lightweight') {
         _check_lightweight(text, line_count, problems);
     }
+    // Bite-sized granularity — self-gated to `complexity: structural`. Folded in
+    // here rather than shipped as its own gate; `_lib/roadmap_granularity.ts`
+    // carries the reason.
+    problems.push(...granularity_problems(text));
     if (horizon_weeks <= 0) {
         _check_no_plate(text, problems);
     }
@@ -383,6 +389,21 @@ function _check_execution_mode(fm: string, problems: string[]): void {
 }
 
 function main(): number {
+    try {
+        assertScanned({
+            gate: 'lint_roadmap_complexity',
+            scanned: _countRoadmapTree(path.join(REPO_ROOT, 'agents', 'roadmaps')),
+            units: 'roadmap file(s)',
+            roots: ['agents/roadmaps'],
+        });
+    } catch (e) {
+        // 1 is the only failure code this gate defines.
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
     const roadmaps = _globRoadmaps();
     const horizon_weeks = _read_horizon_weeks();
     if (roadmaps.length === 0) {
@@ -477,6 +498,32 @@ function _relPosix(target: string, root: string): string {
     return path.relative(root, target).split(path.sep).join('/');
 }
 
+/**
+ * Every `*.md` anywhere under the roadmap tree — active plus `archive/`,
+ * `later/`, `skipped/`.
+ *
+ * The active glob is the subset this gate judges, and it reaches zero
+ * legitimately once everything is archived, so it cannot double as the scope
+ * assertion. The whole tree reaching zero has only one cause: the root moved.
+ */
+function _countRoadmapTree(dir: string): number {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return 0;
+    }
+    let n = 0;
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            n += _countRoadmapTree(path.join(dir, entry.name));
+        } else if (entry.name.endsWith('.md')) {
+            n += 1;
+        }
+    }
+    return n;
+}
+
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;

package/src/scripts/lint_roadmap_later_disposition.ts

@@ -44,6 +44,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);
 
 // REPO_ROOT = Path(__file__).resolve().parent.parent.parent
@@ -313,6 +315,27 @@ function main(argv?: readonly string[]): number {
     }
     const args = parsed.args as Args;
 
+    // `check` walks the whole tree already, but returns only violations, and it
+    // opens with `if (!_isDir(root)) return []` — a moved root reads as "every
+    // blocked-for-later roadmap is parked correctly". Assert the unfiltered
+    // walk here rather than inside `check`, which is exercised against empty
+    // sandbox roots. Exit 2 is this CLI's internal-error slot; 1 stays
+    // "disposition violations found".
+    try {
+        assertScanned({
+            gate: 'lint_roadmap_later_disposition',
+            scanned: _rglobMdSorted(ROADMAP_ROOT).length,
+            units: 'roadmap file(s)',
+            roots: ['agents/roadmaps'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
     const violations = check(ROADMAP_ROOT);
 
     if (args.json) {

package/src/scripts/lint_rule_interactions.ts

@@ -21,6 +21,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { resolve_logical, strip_source_prefix } from './_lib/agent_src.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -125,8 +126,21 @@ function fail(errors: string[]): never {
 }
 
 function _run(): number {
-    if (!_exists(MATRIX)) {
-        fail([`${_relTo(MATRIX, ROOT)} is missing`]);
+    // Replaces the ad-hoc `_exists(MATRIX)` precondition: this gate's entire
+    // corpus is one named contract file, so a moved matrix is a dead scope, not
+    // a content finding. Exit 1 either way — the gate has a single failure code.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_rule_interactions',
+            candidates: [_relTo(MATRIX, ROOT)],
+            repoRoot: ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            throw new FailExit([e.message]);
+        }
+        throw e;
     }
 
     const data = parseYaml(fs.readFileSync(MATRIX, 'utf-8'), { version: '1.1' });

package/src/scripts/lint_rule_tiers.ts

@@ -19,9 +19,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { artefact_roots } from "./_lib/agent_src.js";
+import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
 
 const QUIET = process.argv.includes("--quiet");
 
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
 // Rules live under every artefact root post-monorepo Phase 4.
 function RULES_DIRS(): string[] {
   return artefact_roots()
@@ -106,12 +109,22 @@ export function main(): number {
     rules.push(...globMd(rulesDir));
   }
   rules.sort();
-  if (rules.length === 0) {
-    const rootsLabel = RULES_DIRS().join(", ") || "<no rules root>";
-    process.stderr.write(
-      `lint_rule_tiers: no rules found under ${rootsLabel}\n`,
-    );
-    return 1;
+  // Supersedes the previous bare `rules.length === 0` message: same exit code
+  // (1 — the only failure this CLI contract defines), but the shared assertion
+  // names the roots and says the scope is dead rather than merely "no rules".
+  try {
+    assertScanned({
+      gate: "lint_rule_tiers",
+      scanned: rules.length,
+      units: "rule file(s)",
+      roots: artefact_roots().map((r) => `${path.relative(REPO_ROOT, r)}/rules`),
+    });
+  } catch (e) {
+    if (e instanceof DeadScopeError) {
+      process.stderr.write(`${e.message}\n`);
+      return 1;
+    }
+    throw e;
   }
 
   const missing: string[] = [];