@event4u/agent-config 9.20.0 → 9.22.0

package/src/scripts/lint_agents_md.ts

@@ -19,6 +19,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { SRC_AGENT } 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), '..', '..');
@@ -253,6 +254,25 @@ function _fileSize(p: string): number {
 }
 
 function main(): number {
+    // No corpus walk — the contract binds two named files, so the watch list IS
+    // the scope. `SRC_AGENT()` has already moved once (ADR-051); if it moves
+    // again the per-target `not found` errors say nothing about the root.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_agents_md',
+            candidates: TARGETS.map((t) => _relPosix(t.path, ROOT)),
+            repoRoot: ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is the gate's only failure code — a missing target already
+            // returns it, so "could not run at all" cannot be louder than that.
+            process.stdout.write(`  ❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     let rc = 0;
     for (const t of TARGETS) {
         const [ok, errors, warnings] = lint_file(t);

package/src/scripts/lint_archived_skills.ts

@@ -30,6 +30,7 @@ import * as 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 _HERE = fileURLToPath(import.meta.url);
 
@@ -40,9 +41,8 @@ const REPO = path.resolve(path.dirname(_HERE), '..', '..');
 const ARCHIVE_DIR = path.join(REPO, 'agents', 'evidence', 'archived-skills');
 
 // Live skill directories live under every artefact root.
-const SKILLS_DIRS = artefact_roots()
-    .map((root) => path.join(root, 'skills'))
-    .filter((d) => _isDir(d));
+const ALL_SKILLS_DIRS = artefact_roots().map((root) => path.join(root, 'skills'));
+const SKILLS_DIRS = ALL_SKILLS_DIRS.filter((d) => _isDir(d));
 
 const REQUIRED_FIELDS = [
     'slug',
@@ -128,6 +128,27 @@ function main(): number {
 
     const notes = archived_slugs();
     const live = live_skill_slugs();
+
+    // The scanned unit is the LIVE skills tree, not the archive notes. Zero
+    // notes is a real success state (nothing has been archived yet), but three
+    // of the five contract checks — replacement-resolves, no-zombie, and the
+    // replaced_by cross-check — are decided entirely by `live`, so an empty or
+    // moved skills root silently answers "no zombies, all replacements fine".
+    try {
+        assertScanned({
+            gate: 'lint_archived_skills',
+            scanned: live.size,
+            units: 'live skill(s)',
+            roots: ALL_SKILLS_DIRS.map((d) => path.relative(REPO, d)),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const errors: string[] = [];
 
     const archivedKeys = new Set<string>();

package/src/scripts/lint_behavioural_eval_freshness.ts

@@ -31,6 +31,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);
 export const REPO = path.resolve(path.dirname(_HERE), '..', '..');
 let SKILLS_DIR = path.join(REPO, 'src', 'skills');
@@ -57,20 +59,28 @@ export interface FreshnessResult {
     ok: boolean;
     stale: Array<{ skill: string; pinned: string; current: string }>;
     inScope: number;
+    /**
+     * Skill directories walked. `inScope` counts only the PINNED subset, which
+     * is legitimately 0 today (nothing has opted in yet) — so it can never
+     * anchor the scope assertion; this can.
+     */
+    scanned: number;
 }
 
 export function checkFreshness(): FreshnessResult {
     const stale: FreshnessResult['stale'] = [];
     let inScope = 0;
+    let scanned = 0;
     let entries: fs.Dirent[];
     try {
         entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
     } catch {
-        return { ok: true, stale, inScope };
+        return { ok: true, stale, inScope, scanned };
     }
     entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     for (const e of entries) {
         if (!e.isDirectory()) continue;
+        scanned += 1;
         const evalsPath = path.join(SKILLS_DIR, e.name, 'evals', 'evals.json');
         const skillMd = path.join(SKILLS_DIR, e.name, 'SKILL.md');
         if (!fs.existsSync(evalsPath) || !fs.existsSync(skillMd)) continue;
@@ -91,7 +101,7 @@ export function checkFreshness(): FreshnessResult {
             stale.push({ skill: e.name, pinned, current });
         }
     }
-    return { ok: stale.length === 0, stale, inScope };
+    return { ok: stale.length === 0, stale, inScope, scanned };
 }
 
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
@@ -103,7 +113,23 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
             return 2;
         }
     }
-    const { ok, stale, inScope } = checkFreshness();
+    const { ok, stale, inScope, scanned } = checkFreshness();
+    // `checkFreshness` swallows an unreadable skills root and returns ok:true,
+    // so a moved `src/skills` prints "0 pinned eval(s) current" and passes.
+    try {
+        assertScanned({
+            gate: 'lint_behavioural_eval_freshness',
+            scanned,
+            units: 'skill director(ies)',
+            roots: ['src/skills'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
     if (!ok) {
         for (const s of stale) {
             process.stderr.write(

package/src/scripts/lint_bench_ab.ts

@@ -20,6 +20,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 _HERE = fileURLToPath(import.meta.url);
 
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -269,6 +271,29 @@ function parse_args(argv: readonly string[]): Args {
 
 function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
+
+    // The two corpora are the scope. `docs/benchmark.md` is deliberately NOT on
+    // the list: it is optional (lint_doc skips when unrendered), and a watch list
+    // passes when ANY entry resolves — including it would let both corpora
+    // disappear behind a rendered doc.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_bench_ab',
+            candidates: [TRACK_A_PATH, TRACK_B_PATH].map((p) =>
+                path.relative(REPO_ROOT, p).split(path.sep).join('/'),
+            ),
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = the gate's violation code; 2 is reserved for the pinned
+            // argparse usage contract, so it cannot carry "could not run".
+            process.stderr.write(`lint_bench_ab: ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     try {
         lint_track_a();
         lint_track_b();

package/src/scripts/lint_bench_corpus.ts

@@ -10,7 +10,8 @@
  * Exit codes:
  *   0  contract holds across every corpus
  *   1  one or more violations
- *   2  invocation error (no corpora found; corpus dir missing)
+ *   2  invocation error (no corpora found — now reported through _lib/scan_scope,
+ *      which names the empty roots; corpus dir missing)
  *
  * Flags:
  *   --quiet            suppress per-file OK lines
@@ -21,6 +22,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseYaml, YAMLParseError } from "yaml";
 import { artefact_roots } from "./_lib/agent_src.js";
+import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
 
 const QUIET = process.argv.includes("--quiet");
 const REQUIRE_FULL = process.argv.includes("--require-full");
@@ -348,9 +350,23 @@ export function main(): number {
   if (_isDir(ROUTER_COVERAGE_DIR)) {
     corpora.push(...globSorted(ROUTER_COVERAGE_DIR, "", ".yaml"));
   }
-  if (corpora.length === 0) {
-    process.stderr.write("error: no corpora found\n");
-    return 2;
+  try {
+    assertScanned({
+      gate: "lint_bench_corpus",
+      scanned: corpora.length,
+      units: "benchmark corpus file(s)",
+      roots: ["tests/eval", "internal/bench/corpora/router-coverage"],
+    });
+  } catch (exc) {
+    if (exc instanceof DeadScopeError) {
+      // Exit 2 stays — the documented code for "no corpora found". The Taskfile
+      // fails on any non-zero, so this was never a silent green; what the
+      // assertion adds is a message that names the roots that came back empty
+      // instead of a bare "error: no corpora found".
+      process.stderr.write(`❌  ${exc.message}\n`);
+      return 2;
+    }
+    throw exc;
   }
 
   const skills = live_skills();

package/src/scripts/lint_breaking_changes_index.ts

@@ -30,6 +30,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_breaking_changes_index.ts → two levels up is the repo root.
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -237,6 +239,28 @@ function main(argv?: readonly string[]): number {
         ? _splitlines(fs.readFileSync(changelogPath, 'utf-8'))
         : [];
 
+    // The diff is between two blobs, but the corpus is the working-tree
+    // CHANGELOG: an absent one yields no lines, hence no added majors, hence the
+    // green "no new released BREAKING entries vs trunk" — a clean bill of health
+    // for a file that was never read. The base blob is legitimately empty for a
+    // newly added CHANGELOG, so only this side is asserted.
+    try {
+        assertScanned({
+            gate: 'lint_breaking_changes_index',
+            scanned: newLines.length,
+            units: `${CHANGELOG_REL} line(s)`,
+            roots: [CHANGELOG_REL],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = the gate's violation code; 2 is reserved for the pinned
+            // argparse usage contract, so it cannot carry "could not run".
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     // Was BREAKING_CHANGES.md touched (staged or unstaged) vs the base?
     const indexChanged = _git('diff', '--name-only', base, '--', INDEX_REL).trim() !== '';
 

package/src/scripts/lint_budget_ownership.ts

@@ -21,6 +21,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 CONFIG_DIR = path.join(REPO_ROOT, 'src', 'config');
 
@@ -52,9 +54,24 @@ export function budgetFiles(dir: string = CONFIG_DIR): string[] {
 
 export function main(): number {
     const files = budgetFiles();
-    if (files.length === 0) {
-        process.stdout.write('ℹ️  no budget configs under src/config/ — nothing to lint\n');
-        return 0;
+    // `*budget*.json` IS this gate's corpus definition, not a content-derived
+    // subset: zero matches means src/config/ moved or the budgets were deleted,
+    // and the old "nothing to lint" exit 0 could not tell either from a healthy
+    // tree. Of the two documented failure codes, 1 is the one the gate actually
+    // returns when it will not vouch for the tree; 2 is reserved for a throw.
+    try {
+        assertScanned({
+            gate: 'lint_budget_ownership',
+            scanned: files.length,
+            units: 'budget config(s)',
+            roots: ['src/config'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const errors: string[] = [];
     const today = new Date().toISOString().slice(0, 10);

package/src/scripts/lint_changelog_rollback.ts

@@ -33,6 +33,7 @@ import {
     REPO_ROOT,
     VERSION_HEADING_RE,
 } from './_lib/changelog_eras.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -243,6 +244,29 @@ function main(argv?: readonly string[]): number {
     const text = fs.readFileSync(changelog_path, 'utf-8');
     const lines = text.split(/\r\n|\r|\n/);
 
+    // Scope is the version sections the heading regex actually recognises, not
+    // the line count: a CHANGELOG whose heading shape drifts away from
+    // VERSION_HEADING_RE still reads as a big file while presenting zero
+    // sections to check, and the gate reports clean. Counted before the cutoff
+    // and patch filters — those are judgement, this is reach.
+    const sections = lines.filter((ln) => VERSION_HEADING_RE.test(ln)).length;
+    try {
+        assertScanned({
+            gate: 'lint_changelog_rollback',
+            scanned: sections,
+            units: 'version section(s)',
+            roots: [path.relative(REPO_ROOT, changelog_path)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = the gate's violation code; 2 is reserved for the pinned
+            // argparse usage contract, so it cannot carry "could not run".
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const violations = check_rollback_lines(lines, cutoff);
     if (violations.length > 0) {
         process.stderr.write(

package/src/scripts/lint_command_flow_coverage.ts

@@ -22,6 +22,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { _iter_domains_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), '..', '..');
@@ -119,6 +120,27 @@ export function main(): number {
         return 3;
     }
 
+    // `_iter_domains_commands` returns nothing when the command tree is not a
+    // directory, so a moved root turns every mapped ref into a "phantom" — the
+    // gate would blame surface-map.yaml for a walk that never happened. Counted
+    // on the walk itself, before any comparison with the map.
+    try {
+        assertScanned({
+            gate: 'lint_command_flow_coverage',
+            scanned: real.size,
+            units: 'command file(s)',
+            roots: ['src/domains/<pack>/**/command.md'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 3 = internal error, i.e. "this gate could not run" — 1 would
+            // claim the surface map is wrong, which is exactly the wrong story.
+            process.stderr.write(`lint_command_flow_coverage: ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     const user_flows = new Set<string>(
         (Array.isArray(data['user_work_flows']) ? (data['user_work_flows'] as unknown[]) : [])
             .map((x) => String(x)),

package/src/scripts/lint_command_tiers.ts

@@ -20,6 +20,7 @@ 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");
 
@@ -315,11 +316,34 @@ function rglobNamed(root: string, name: string): string[] {
 
 export function main(): number {
   const commandsDirs = COMMANDS_DIRS();
-  if (commandsDirs.length === 0 && !_isDir(DOMAINS_DIR)) {
-    process.stderr.write(
-      "lint_command_tiers: no commands dir found under any artefact root\n",
-    );
-    return 1;
+  // Each pass below guards its own emptiness, but nothing guarded the case
+  // where every pass is skipped: COMMANDS_DIRS() drops a root that holds no
+  // .md, and both DOMAINS_DIR and the condensed projection are conditional, so
+  // rc could stay 0 having read no command at all. The sum replaces the older
+  // "no commands dir found" check, which only saw the directory, not the files.
+  const commandsIn = (d: string): number =>
+    rglobMd(d).filter((p) => path.basename(p) !== "AGENTS.md").length;
+  const scanned =
+    (_isDir(DOMAINS_DIR) ? rglobNamed(DOMAINS_DIR, "command.md").length : 0) +
+    commandsDirs.reduce((n, d) => n + commandsIn(d), 0) +
+    (_isDir(COMMANDS_DIR_CONDENSED) ? commandsIn(COMMANDS_DIR_CONDENSED) : 0);
+  try {
+    assertScanned({
+      gate: "lint_command_tiers",
+      scanned,
+      units: "command file(s)",
+      roots: [
+        relPosix(DOMAINS_DIR, REPO),
+        ...commandsDirs.map((d) => relPosix(d, REPO)),
+        relPosix(COMMANDS_DIR_CONDENSED, REPO),
+      ],
+    });
+  } catch (exc) {
+    if (exc instanceof DeadScopeError) {
+      process.stderr.write(`❌  ${exc.message}\n`);
+      return 1;
+    }
+    throw exc;
   }
   let rc = 0;
   if (_isDir(DOMAINS_DIR)) {

package/src/scripts/lint_commit_subjects.ts

@@ -28,6 +28,8 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 const BLOCKLIST: ReadonlySet<string> = new Set([
@@ -182,6 +184,19 @@ function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const subjects = fetch_subjects(args.base, args.head);
+    assertScanned({
+        gate: 'lint_commit_subjects',
+        scanned: subjects.length,
+        units: 'commit subject(s)',
+        roots: [`git log ${args.base}..${args.head}`],
+        allowEmpty:
+            'EMPTY_VALID: a branch that is level with its base contributes no subjects to the ' +
+            'release changelog, so zero subjects is the success state. Deletion test: no ' +
+            'deleted root can produce it — the range is computed from refs, not a tree. An ' +
+            'UNREADABLE range is the distinct case and is announced, not swallowed: ' +
+            '`fetch_subjects` writes `⚠️  git log <base>..<head> failed: …` to stderr first, ' +
+            'and staying advisory there is the pinned contract (never block on git plumbing).',
+    });
     if (subjects.length === 0) {
         if (!args.quiet) {
             process.stdout.write(

package/src/scripts/lint_confusables.ts

@@ -35,6 +35,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
 import { TOKEN_RE, classifyToken } from './_lib/confusables.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 export const CHECK = 'mixed-script-confusable';
 
@@ -113,12 +114,35 @@ export function main(argv: readonly string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const findings: sl.Finding[] = [];
+    let scanned = 0;
     for (const sf of sl.iter_corpus()) {
+        // Counted on the corpus walk, not on `_scan`'s return: `iter_corpus`
+        // skips a root that does not exist, so every root moving at once yields
+        // zero files and the report line still says "clean (scanned <roots>)".
+        scanned += 1;
         for (const h of _scan(sf)) {
             findings.push(h);
         }
     }
 
+    try {
+        assertScanned({
+            gate: 'lint_confusables',
+            scanned,
+            units: 'file(s)',
+            roots: sl.DEFAULT_SCAN_ROOTS,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 2 = "could not run" (the usage-error code), never 0 and never the
+            // finding code 1: a homoglyph lint that read nothing is blind, and
+            // `--json` callers must not read an empty payload as clean either.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        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_consumer_internal_refs.ts

@@ -52,6 +52,8 @@ import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const SKILLS_DIR = path.join(REPO_ROOT, 'dist', 'agent-src', 'skills');
 
@@ -174,9 +176,11 @@ export function main(): number {
     }
 
     const findings: string[] = [];
+    let projected = 0;
     for (const name of skillDirs) {
         const abs = path.join(SKILLS_DIR, name, 'SKILL.md');
         if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+        projected += 1;
         const ws = skillWorkspaces(abs);
         if (isExclusivelyMaintainer(ws)) continue;
         let text: string;
@@ -189,6 +193,26 @@ export function main(): number {
         findings.push(...scanText(name, relPath, text));
     }
 
+    // Counted BEFORE the maintainer-exclusive skip, so an all-maintainer
+    // projection is not mistaken for a dead root. The dir-exists guard above
+    // only catches a deleted tree; a regenerated-but-empty projection reaches
+    // here and would print the ✅ line over nothing. Exit 2 follows that same
+    // guard: the projection is unusable, which is not a "finding" (1).
+    try {
+        assertScanned({
+            gate: 'lint_consumer_internal_refs',
+            scanned: projected,
+            units: 'projected SKILL.md file(s)',
+            roots: ['dist/agent-src/skills'],
+        });
+    } 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(`❌  consumer-internal reference: ${f}\n`);

package/src/scripts/lint_design_quality.ts

@@ -44,6 +44,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
 
 interface Finding {
   rule: string;
@@ -277,6 +278,27 @@ function main(): void {
     }
   }
 
+  // The opt-in escape above is the "consumer has no UI tree" path. Reaching
+  // here means the root EXISTS and still yielded nothing scannable — a moved
+  // subtree, a drifted extension list, or an over-broad ignoreFiles glob. That
+  // prints "clean — 0 file(s) checked" today. Exit 1 is this linter's
+  // internal-error code; 2 is reserved for real findings.
+  try {
+    assertScanned({
+      gate: "lint_design_quality",
+      scanned: htmlCssFiles.length,
+      units: "HTML/CSS file(s)",
+      // Absolute: --dir may point outside the cwd (or outside any repo).
+      roots: [scanDir],
+    });
+  } catch (exc) {
+    if (exc instanceof DeadScopeError) {
+      process.stderr.write(`❌  ${exc.message}\n`);
+      process.exit(1);
+    }
+    throw exc;
+  }
+
   const allFindings: Finding[] = [];
   for (const filePath of htmlCssFiles) {
     const relPath = path.relative(process.cwd(), filePath);

package/src/scripts/lint_design_slop.ts

@@ -37,6 +37,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
 import {
   SLOP_RULES,
   type DesignContext,
@@ -197,6 +198,28 @@ function main(): void {
     if (!ignoreGlobs.some((g) => f.includes(g.replace("**", "")))) files.push(f);
   }
 
+  // The opt-in escape above is the "consumer has no UI tree" path. Reaching
+  // here means the root EXISTS and still yielded nothing scannable — a moved
+  // subtree, a drifted extension list, or an over-broad ignoreFiles glob. This
+  // detector never hard-blocks on findings, so "no tells in 0 file(s)" is
+  // indistinguishable from a clean scan. Exit 1 is its internal-error code; 2
+  // is reserved for the --fail-on threshold.
+  try {
+    assertScanned({
+      gate: "lint_design_slop",
+      scanned: files.length,
+      units: "design source file(s)",
+      // Absolute: --dir may point outside the cwd (or outside any repo).
+      roots: [scanDir],
+    });
+  } catch (exc) {
+    if (exc instanceof DeadScopeError) {
+      process.stderr.write(`❌  ${exc.message}\n`);
+      process.exit(1);
+    }
+    throw exc;
+  }
+
   const findings: Finding[] = [];
   for (const fp of files) {
     const rel = path.relative(process.cwd(), fp);

package/src/scripts/lint_discovery_manifest.ts

@@ -31,6 +31,8 @@ import * as path from 'node:path';
 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 ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const SCHEMA_PATH = path.join(ROOT, 'docs', 'contracts', 'discovery-manifest.schema.json');
@@ -247,6 +249,27 @@ function main(argv?: readonly string[]): number {
         return 1;
     }
 
+    // A manifest built over a dead source root is still well-formed and still
+    // checksums correctly — it just indexes nothing, and this gate signs it off
+    // with "OK …: 0 artefacts, 0 unassigned, checksum verified". Asserted after
+    // the structural checks so their own messages stay the first explanation.
+    try {
+        assertScanned({
+            gate: 'lint_discovery_manifest',
+            scanned: _asArray(manifest['artefacts']).length,
+            units: 'manifest artefact(s)',
+            roots: [_relPosix(args.manifest, ROOT)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = schema/integrity failure, the gate's only failure code; 2 is
+            // reserved for the pinned argparse usage contract.
+            process.stderr.write(`error: ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const vocab_errs = _check_vocab(manifest);
     const det_errs = _check_capability_pack_determinism(manifest);
     const all_errs = [...vocab_errs, ...det_errs];