@event4u/agent-config 9.19.0 → 9.21.0

package/src/scripts/lint_no_new_atomic_commands.ts

@@ -21,6 +21,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_no_new_atomic_commands.ts → parent.parent.parent is repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -288,6 +290,37 @@ function main(argv?: readonly string[]): number {
 
     const clusters = load_locked_clusters();
     const targets = args.all ? all_command_files() : added_command_files(args.baseline);
+    // Two scopes behind one variable. `--all` walks src/domains, and an empty
+    // walk there is a moved root — the gate would print "No new commands added"
+    // and pass over a corpus it never found. The default mode reads a git diff,
+    // where zero added command files is the ordinary clean-branch state, so it
+    // carries a justified allowEmpty. Exit 3 is the internal-error code ("could
+    // not run"); 1 means a real policy violation.
+    try {
+        assertScanned({
+            gate: 'lint_no_new_atomic_commands',
+            scanned: targets.length,
+            units: args.all ? 'command file(s)' : 'added command file(s)',
+            roots: [COMMANDS_DIR],
+            ...(args.all
+                ? {}
+                : {
+                      allowEmpty:
+                          'EMPTY_VALID: the default mode reads `git diff --diff-filter=A` plus ' +
+                          'untracked status, so zero added command files IS the pass state on a ' +
+                          'branch that adds none. Deletion test: deleting src/domains would not ' +
+                          'produce this zero — a deletion shows up as diff-filter=D, never as A — ' +
+                          'so an empty diff cannot launder a dead root. The tree-walking half of ' +
+                          'this gate (--all) is asserted without the exemption.',
+                  }),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
     if (targets.length === 0) {
         process.stdout.write(
             `✅  No new commands added under ${COMMANDS_DIR} ` +

package/src/scripts/lint_no_python_twin_rationale.ts

@@ -22,6 +22,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 ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const SCOPE = path.join(ROOT, 'src', 'scripts');
@@ -79,11 +81,27 @@ export function scan_file(rel: string, text: string): string[] {
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     const QUIET = argv.includes('--quiet');
     const findings: string[] = [];
+    let scanned = 0;
     for (const f of walk(SCOPE)) {
         if (path.resolve(f) === path.resolve(_HERE)) continue; // this guard documents the shapes
+        scanned += 1;
         const rel = path.relative(ROOT, f).split(path.sep).join('/');
         findings.push(...scan_file(rel, fs.readFileSync(f, 'utf-8')));
     }
+    try {
+        assertScanned({
+            gate: 'lint_no_python_twin_rationale',
+            scanned,
+            units: 'source file(s)',
+            roots: ['src/scripts'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stdout.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     if (findings.length === 0) {
         if (!QUIET) process.stdout.write('✅  No Python-twin rationale in src/scripts comments.\n');
         return 0;

package/src/scripts/lint_one_off_age.ts

@@ -28,6 +28,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 ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 // Mirrors the (scan-unused) module constant; kept for export parity.
@@ -159,7 +161,12 @@ function _exists(p: string): boolean {
     }
 }
 
-export function scan(root: string, today?: SimpleDate): Finding[] {
+/** Out-param so the caller can assert the scope `scan` just walked. */
+export interface ScanStats {
+    entries: number;
+}
+
+export function scan(root: string, today?: SimpleDate, stats?: ScanStats): Finding[] {
     const day = today ?? _today_utc();
     const base = path.join(root, 'scripts', '_one_off');
     if (!_exists(base)) {
@@ -170,6 +177,11 @@ export function scan(root: string, today?: SimpleDate): Finding[] {
         if (!_isDir(month_dir)) {
             continue;
         }
+        // A month dir is itself a checked unit — its name shape is validated
+        // below, so an empty one is still something this walk read.
+        if (stats) {
+            stats.entries += 1;
+        }
         const monthName = path.basename(month_dir);
         const anchor = _month_anchor(monthName);
         if (anchor === null) {
@@ -186,6 +198,9 @@ export function scan(root: string, today?: SimpleDate): Finding[] {
             if (fname === 'README.md' || _isDir(f)) {
                 continue;
             }
+            if (stats) {
+                stats.entries += 1;
+            }
             if (!NAME_RE.test(fname)) {
                 out.push({
                     path: _relTo(f, root),
@@ -315,13 +330,34 @@ function parse_args(argv: readonly string[]): ParsedArgs {
 export function main(): number {
     const args = parse_args(process.argv.slice(2));
     let findings: Finding[];
+    const stats: ScanStats = { entries: 0 };
     try {
-        findings = scan(args.root);
+        findings = scan(args.root, undefined, stats);
     } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         process.stderr.write(`Internal error: ${msg}\n`);
         return 3;
     }
+    try {
+        assertScanned({
+            gate: 'lint_one_off_age',
+            scanned: stats.entries,
+            units: 'one-off entr(y/ies)',
+            roots: ['scripts/_one_off'],
+            allowEmpty:
+                'OPTIONAL_INPUT: `scripts/_one_off/` is a TTL-managed scratch tree created on ' +
+                'demand and purged by this very policy — an absent or empty root is the ' +
+                'intended steady state, not a lost corpus. Delete the root and zero still ' +
+                'means "no one-off scripts exist", which is exactly what the TTL is for.',
+        });
+    } catch (e) {
+        // 1 is the hard-fail code (2 is argparse, 3 an internal error).
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
     if (args.format === 'json') {
         // json.dumps([asdict(f) for f in findings], indent=2) — keys keep the
         // dataclass declaration order (path, age_days, severity, reason).

package/src/scripts/lint_orchestration_dsl.ts

@@ -24,6 +24,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { resolve_logical } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -301,11 +302,30 @@ function main(argv?: readonly string[]): number {
     if (args.file !== null) {
         return lint(args.file);
     }
-    if (!_isDir(args.dir)) {
-        return 0; // opt-in directory; absence is not a failure
+    const pipelines = _isDir(args.dir) ? _globYamlSorted(args.dir) : [];
+    try {
+        assertScanned({
+            gate: 'lint_orchestration_dsl',
+            scanned: pipelines.length,
+            units: 'pipeline file(s)',
+            roots: ['.agent-config/orchestrations'],
+            allowEmpty:
+                'OPTIONAL_INPUT: `.agent-config/orchestrations/` is an opt-in consumer ' +
+                'directory — most projects author no pipelines at all, and the DSL contract ' +
+                'only binds files that exist. Delete the root and zero still means "this ' +
+                'project declares no pipelines", never a corpus that went missing.',
+        });
+    } catch (exc) {
+        // 2 is the file/schema-load code; 1 is reserved for a pipeline that
+        // violates the contract.
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`lint_orchestration_dsl: ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
     }
     let rc = 0;
-    for (const p of _globYamlSorted(args.dir)) {
+    for (const p of pipelines) {
         rc = Math.max(rc, lint(p));
     }
     return rc;

package/src/scripts/lint_orchestrator_auto_detect.ts

@@ -13,6 +13,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 SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.dirname(path.dirname(SCRIPTS_DIR));
 const DOMAINS = path.join(ROOT, 'src', 'domains');
@@ -28,14 +30,6 @@ export interface Violation {
     reason: string;
 }
 
-function isDir(p: string): boolean {
-    try {
-        return fs.statSync(p).isDirectory();
-    } catch {
-        return false;
-    }
-}
-
 /** Recursively collect files named `command.md`, sorted by POSIX path. */
 function rglobCommandMd(dir: string): string[] {
     const out: string[] = [];
@@ -78,10 +72,17 @@ export function _split_frontmatter(text: string): [string, string] {
 
 export function check(): Violation[] {
     const violations: Violation[] = [];
-    if (!isDir(DOMAINS)) {
-        return violations;
-    }
-    for (const filePath of rglobCommandMd(DOMAINS)) {
+    // Assert the whole walk, not the `auto_detect:`-carrying subset: opting out
+    // is the common case, so "0 opted in" is normal while "0 command files" can
+    // only mean the domains root moved out from under the literal above.
+    const commands = rglobCommandMd(DOMAINS);
+    assertScanned({
+        gate: 'lint_orchestrator_auto_detect',
+        scanned: commands.length,
+        units: 'command file(s)',
+        roots: ['src/domains'],
+    });
+    for (const filePath of commands) {
         const text = fs.readFileSync(filePath, 'utf-8');
         const [fm, body] = _split_frontmatter(text);
         const m = AUTO_DETECT_RE.exec(fm);
@@ -149,6 +150,12 @@ export function main(argv?: readonly string[]): number {
     try {
         violations = check();
     } catch (exc) {
+        // 3 = "the gate could not run" (1 is reserved for contract violations
+        // it actually found), so a dead scan root reports as the former.
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
         const msg = exc instanceof Error ? exc.message : String(exc);
         process.stderr.write(`❌  lint-orchestrator-auto-detect: internal error: ${msg}\n`);
         return 3;

package/src/scripts/lint_originality.ts

@@ -57,6 +57,7 @@ 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 { shingles } from './_lib/shingle_similarity.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -411,6 +412,27 @@ export function main(argv?: string[]): number {
         else { process.stderr.write(`unexpected argument: ${a} (did you mean --changed ${a}?)\n${_usage()}`); return 2; }
     }
 
+    // Asserted for BOTH modes, and before either: `--changed` compares each
+    // candidate against the same corpus, so a dead root there reports "no
+    // overlap" instead of "nothing to compare against" — the quieter failure of
+    // the two. Supersedes the post-corpus `scanned === 0` check the full audit
+    // used to carry alone; exit 3 is that check's code, kept so 1 still means
+    // "a real overlap was found".
+    try {
+        assertScanned({
+            gate: 'lint_originality',
+            scanned: CLASSES.reduce((n, spec) => n + spec.files().length, 0),
+            units: 'corpus file(s)',
+            roots: ['src/skills', 'src/agent-src/personas', 'src/domains'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 3;
+        }
+        throw e;
+    }
+
     if (changedFiles !== null) {
         const { pairs, fails } = _changed(changedFiles);
         if (pairs.length > 0) {
@@ -428,10 +450,6 @@ export function main(argv?: string[]): number {
     // Full audit
     const byClass = _corpus();
     const scanned = [...byClass.values()].reduce((n, a) => n + a.length, 0);
-    if (scanned === 0) {
-        process.stderr.write('❌  No artifacts found under the corpus roots.\n');
-        return 3;
-    }
     const dist = _distribution(byClass);
     const pairs = _fullPairs(byClass);
     _writeReport(byClass, pairs, dist);

package/src/scripts/lint_originality_shingles.ts

@@ -32,6 +32,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 = path.dirname(fileURLToPath(import.meta.url));
 const REPO = path.resolve(_HERE, '..', '..');
 
@@ -84,8 +86,12 @@ function _shingles(words: string[]): Set<string> {
     return out;
 }
 
-function _collect(): Doc[] {
+/** `read` counts every corpus file opened, `docs` only those long enough to
+ *  compare — a corpus of stubs is a different problem from a corpus that is not
+ *  there, and only the second one means the roots below have rotted. */
+function _collect(): { docs: Doc[]; read: number } {
     const docs: Doc[] = [];
+    let read = 0;
     const push = (id: string, file: string): void => {
         let body: string;
         try {
@@ -93,6 +99,7 @@ function _collect(): Doc[] {
         } catch {
             return;
         }
+        read += 1;
         const sh = _shingles(_normalize(body));
         if (sh.size >= 20) {
             docs.push({ id, shingles: sh });
@@ -132,7 +139,7 @@ function _collect(): Doc[] {
             }
         }
     }
-    return docs;
+    return { docs, read };
 }
 
 function _jaccardPct(a: Set<string>, b: Set<string>): number {
@@ -162,7 +169,25 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         else if (arg === '--quiet') quiet = true;
     }
 
-    const docs = _collect();
+    const { docs, read } = _collect();
+    // Two of the three roots are behind `existsSync` guards, which is exactly
+    // how the personas root went missing for a whole release (see `_collect`).
+    // Exit 1 is the only failure this gate has; report-only mode included, since
+    // an empty corpus makes the report itself a false all-clear.
+    try {
+        assertScanned({
+            gate: 'lint_originality_shingles',
+            scanned: read,
+            units: 'corpus file(s)',
+            roots: ['src/skills', 'src/agent-src/personas', 'src/subagents'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
     const pairs: Array<{ a: string; b: string; pct: number }> = [];
     for (let i = 0; i < docs.length; i++) {
         for (let j = i + 1; j < docs.length; j++) {

package/src/scripts/lint_output_slop.ts

@@ -26,6 +26,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
+
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, "..", "..");
 
@@ -191,6 +193,23 @@ function main(): void {
   const quiet = process.argv.includes("--quiet");
 
   const files = collectFiles();
+  // `walkDir` returns nothing for a root that does not exist, so all three
+  // literals above can rot into a clean run. Exit 1 is the "internal error"
+  // slot; 2 means findings were actually located and must stay distinct.
+  try {
+    assertScanned({
+      gate: "lint_output_slop",
+      scanned: files.length,
+      units: "file(s)",
+      roots: ["src/skills", "src/rules", "docs/guidelines"],
+    });
+  } catch (e) {
+    if (e instanceof DeadScopeError) {
+      process.stderr.write(`❌  ${e.message}\n`);
+      process.exit(1);
+    }
+    throw e;
+  }
   const allFindings: Finding[] = [];
 
   for (const file of files) {

package/src/scripts/lint_override_kernel_guard.ts

@@ -47,6 +47,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { KERNEL_RULE_IDS, is_kernel_rule } from './_lib/kernel_rules.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
@@ -220,6 +221,35 @@ export function audit(): OverrideRow[] {
 function main(argv: string[]): number {
     const as_json = argv.includes('--json');
     const strict = argv.includes('--strict');
+
+    // Not the override corpus: an empty `agents/overrides/rules/` is a real and
+    // common state (the report says so in words). The scope that cannot be
+    // allowed to die is `safety_floor_ids`' input — with src/rules gone the
+    // floor set is empty, every safety-floor override downgrades to "ordinary",
+    // and the replace/registration checks stop firing while the audit still
+    // reads clean. Exit 2 is this CLI's env-error slot; 1 stays "contract
+    // violated".
+    let rule_sources = 0;
+    try {
+        rule_sources = fs.readdirSync(RULES_DIR).filter((n) => n.endsWith('.md')).length;
+    } catch {
+        rule_sources = 0;
+    }
+    try {
+        assertScanned({
+            gate: 'lint_override_kernel_guard',
+            scanned: rule_sources,
+            units: 'rule source(s)',
+            roots: ['src/rules'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
     const rows = audit();
 
     if (as_json) {

package/src/scripts/lint_pack_first_win.ts

@@ -21,6 +21,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_pack_first_win.ts → parents[2] is the repo root.
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -142,6 +144,7 @@ function _has_onboarding_block(packYaml: string): [boolean, string[]] {
 
 function main(): number {
     const errors: string[] = [];
+    let homesResolved = 0;
     for (const pid of [...FEATURED_PACK_IDS].sort()) {
         const packDir = _pack_home(pid);
         if (packDir === null) {
@@ -151,6 +154,7 @@ function main(): number {
             );
             continue;
         }
+        homesResolved += 1;
         const firstWin = path.join(packDir, 'FIRST_WIN.md');
         let firstWinOk = false;
         try {
@@ -169,6 +173,25 @@ function main(): number {
             );
         }
     }
+    // The success line below reports FEATURED_PACK_IDS.size — a constant that
+    // stays 5 no matter what is on disk. This asserts the number that does move:
+    // pack homes actually resolved through the three-candidate precedence. Zero
+    // means every candidate root is gone, which is a layout migration, not five
+    // separate missing packs. Exit 1 is the gate's only failure code.
+    try {
+        assertScanned({
+            gate: 'lint_pack_first_win',
+            scanned: homesResolved,
+            units: 'featured pack home(s)',
+            roots: ['src/packs', 'src/domains', 'packages'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     if (errors.length > 0) {
         process.stderr.write('❌ pack first-win lint failed:\n');
         for (const e of errors) {

package/src/scripts/lint_pack_risk_class.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 QUIET = process.argv.includes('--quiet');
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
@@ -60,9 +62,23 @@ function _print(s: string): void {
 }
 
 export function main(): number {
-    if (!fs.existsSync(PACKS_YML)) {
-        _print('⚠️  packs.yml not found — skipping risk_class lint');
-        return 0;
+    // packs.yml IS the scope — there is nowhere else a `risk_class: high`
+    // declaration can hide. Replaces the "not found → skip, exit 0" branch,
+    // which turned a moved declaration file into a permanent green. Exit 1 is
+    // the only failure code; here it means the invariant could not be checked,
+    // not that a pack violates it.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_pack_risk_class',
+            candidates: [path.relative(REPO, PACKS_YML)],
+            repoRoot: REPO,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const violations = riskClassViolations(fs.readFileSync(PACKS_YML, 'utf-8'));
     if (violations.length === 0) {

package/src/scripts/lint_persistence.ts

@@ -28,6 +28,7 @@ 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';
 import type { Finding, WaiverRecord } from './_lib/persistence/types.js';
 import { scan_dir as scan_sql_dir } from './_lib/persistence/adapter_raw_sql.js';
 import { scan_dir as scan_n1_dir } from './_lib/persistence/detect_n1_eloquent.js';
@@ -150,6 +151,24 @@ function main(argv: string[]): number {
     }
 
     const resolved_stacks = stacks.length > 0 ? stacks : detect_stacks(dir);
+    // `--dir` existing is not the same as `--dir` holding anything scannable:
+    // every adapter is keyed off a resolved stack, so zero stacks provably
+    // reads zero files while still printing "no gate findings". Exit 2 is the
+    // usage/env slot this CLI already uses for an unusable `--dir`.
+    try {
+        assertScanned({
+            gate: 'lint_persistence',
+            scanned: resolved_stacks.length,
+            units: 'stack(s) to scan',
+            roots: [dir],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
     const report = run_lint(dir, resolved_stacks, audit_scope);
 
     if (format === 'json') {

package/src/scripts/lint_persona_governance.ts

@@ -22,6 +22,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);
@@ -214,9 +216,22 @@ function citations_for(personaId: string): string[] {
 
 function main(): number {
     const personas = collect_personas();
-    if (personas.length === 0) {
-        emit('persona-governance: no persona files found — nothing to lint.');
-        return 0;
+    // Zero personas used to exit 0 with "nothing to lint" — but this gate has
+    // already been inert once on a stale root (see PERSONA_DIR above), and that
+    // message is indistinguishable from the root having moved again.
+    try {
+        assertScanned({
+            gate: 'lint_persona_governance',
+            scanned: personas.length,
+            units: 'persona file(s)',
+            roots: ['src/agent-src/personas'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
 
     const byDomain = new Map<string, string[]>();

package/src/scripts/lint_positioning.ts

@@ -22,6 +22,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), '..', '..');
 const README = path.join(REPO_ROOT, 'README.md');
@@ -155,6 +157,27 @@ function parse_args(argv: readonly string[]): ParsedArgs {
 export function main(): number {
     const args = parse_args(process.argv.slice(2));
 
+    // Four named surfaces ARE the scope; the gate only compares them against
+    // each other, so if the set moved there is nothing left to disagree. Asserted
+    // before the reads so a relocated repo layout names the roots instead of
+    // surfacing as a bare ENOENT stack. Exit 1 is the drift code and doubles as
+    // "could not run" (2 is reserved for the missing-YAML-runtime case).
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_positioning',
+            candidates: [README, PACKAGE_JSON, ABOUT_YML, TOPICS_YML].map((p) =>
+                path.relative(REPO_ROOT, p),
+            ),
+            repoRoot: REPO_ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+
     let anchor: string;
     let pkg_desc: string;
     let about_desc: string;