@event4u/agent-config 9.13.0 → 9.15.0

package/src/scripts/lint_agents_md.ts

@@ -9,7 +9,7 @@
  * historical quirks preserved (consumers pin the exact behaviour).
  *
  * Enforces caps + pointer-ratio + pointer-anatomy + emergency-triage
- * contract from `.agent-src.uncondensed/skills/agents-md-thin-root/SKILL.md`.
+ * contract from `src/skills/agents-md-thin-root/SKILL.md`.
  *
  * Exit non-zero on any (a) FAIL, (b)–(e) error. WARN is informational.
  */
@@ -87,12 +87,18 @@ function _resolve(target_str: string, template: boolean): boolean {
         return true;
     }
     const candidates = [path.join(ROOT, raw)];
+    // DEAD-ROOT REPAIR (road-to-renewal-foundation Phase 1): the
+    // retired-authoring-root fallbacks were unreachable (ADR-051 deleted that
+    // tree). They were harmless only while `dist/agent-src/` happened to
+    // be materialised; the moment it is not, a valid pointer is reported
+    // unresolved. `src/agent-src/` is the source of truth those paths project
+    // from.
     if (template && raw.startsWith('.augment/')) {
-        candidates.push(path.join(ROOT, raw.replace('.augment/', '.agent-src.uncondensed/')));
         candidates.push(path.join(ROOT, raw.replace('.augment/', 'dist/agent-src/')));
+        candidates.push(path.join(ROOT, raw.replace('.augment/', 'src/agent-src/')));
     }
     if (raw.startsWith('dist/agent-src/')) {
-        candidates.push(path.join(ROOT, raw.replace('dist/agent-src/', '.agent-src.uncondensed/')));
+        candidates.push(path.join(ROOT, raw.replace('dist/agent-src/', 'src/agent-src/')));
     }
     return candidates.some((c) => _exists(c));
 }

package/src/scripts/lint_archived_skills.ts

@@ -9,7 +9,7 @@
  * frontmatter parser, same `artefact_roots()` skill-root discovery.
  *
  * Enforces the contract from
- * .agent-src.uncondensed/templates/skill-archive-note.md:
+ * src/agent-src/templates/skill-archive-note.md:
  *
  *   1. Every <slug>.md under agents/evidence/archived-skills/ has the six
  *      required frontmatter fields with valid values.

package/src/scripts/lint_artefact_frontmatter.ts

@@ -21,6 +21,9 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { SRC_AGENT, SRC_RULES, SRC_SKILLS, iter_commands } from './_lib/agent_src.js';
+import { checkRatchet } from './_lib/gate_baseline.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
 import { parse_frontmatter } from './validate_frontmatter.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -31,6 +34,24 @@ let ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 let SRC = path.join(ROOT, '.agent-src.uncondensed');
 let VOCAB_DIR = path.join(ROOT, 'src', 'config', 'discovery');
 
+const _DEFAULT_ROOT = ROOT;
+const _DEFAULT_SRC = SRC;
+
+/**
+ * True while a caller has repointed the roots at a fixture tree.
+ *
+ * Stateless on purpose (compared against the values captured at import, not a
+ * sticky flag) so that a test restoring the real paths in `afterEach` also
+ * restores real-repo behaviour. Two things key off it: the scan roots (an
+ * injected container is scanned EXCLUSIVELY — the shared resolver still points
+ * at the real repo and would otherwise drag the whole corpus into a fixture
+ * run) and the violation ratchet, which records repo debt and must never judge
+ * a fixture.
+ */
+function _paths_overridden(): boolean {
+    return ROOT !== _DEFAULT_ROOT || SRC !== _DEFAULT_SRC;
+}
+
 /** Test seam: override the module-level scan roots (mirrors monkeypatch). */
 function _set_paths(opts: { root?: string; src?: string; vocabDir?: string }): void {
     if (opts.root !== undefined) {
@@ -71,25 +92,84 @@ function _load_vocab(): [Set<string>, Set<string>, Set<string>] {
     return [wsIds, packIds, quarantine];
 }
 
+/**
+ * The four scan roots, named individually rather than via one container.
+ *
+ * ADR-051 did not move the pre-ADR-051 source container somewhere else — it
+ * split it. `skills/` and `rules/` became top-level `src/` siblings, `templates/` went to
+ * `src/agent-src/templates`, and `commands/` stopped being a directory at all
+ * (each command is now `src/domains/<pack>/<subpath>/command.md`). Until
+ * 2026-08-02 `SRC` still named the emptied container, so every walk below hit
+ * a missing directory and the gate printed `0 artefact(s) clean` forever.
+ *
+ * Deliberately NOT the resolver's category-append view (`artefact_roots()`
+ * + `/templates`): that also yields `src/templates`, an unrelated
+ * consumer-scaffold tree this gate never scanned. Repairing a root must
+ * restore the old scope, not silently widen it.
+ */
+function _scan_roots(): Array<[root: string, pattern: string]> {
+    if (_paths_overridden()) {
+        // Fixture mode — the injected container is the whole world.
+        return [
+            [path.join(SRC, 'skills'), 'SKILL.md'],
+            [path.join(SRC, 'rules'), '*.md'],
+            [path.join(SRC, 'commands'), '*.md'],
+            [path.join(SRC, 'templates'), '*.md'],
+        ];
+    }
+    return [
+        [SRC_SKILLS(), 'SKILL.md'],
+        [SRC_RULES(), '*.md'],
+        [path.join(SRC_AGENT(), 'templates'), '*.md'],
+    ];
+}
+
 function _iter_artefacts(): string[] {
     const out: string[] = [];
-    for (const p of _rglobSorted(path.join(SRC, 'skills'), 'SKILL.md')) {
-        out.push(p);
-    }
-    for (const p of _rglobSorted(path.join(SRC, 'rules'), '*.md')) {
-        out.push(p);
-    }
-    for (const p of _rglobSorted(path.join(SRC, 'commands'), '*.md')) {
-        out.push(p);
-    }
-    if (_exists(path.join(SRC, 'templates'))) {
-        for (const p of _rglobSorted(path.join(SRC, 'templates'), '*.md')) {
+    const seen = new Set<string>();
+    const push = (p: string): void => {
+        if (!seen.has(p)) {
+            seen.add(p);
             out.push(p);
         }
+    };
+    for (const [root, pattern] of _scan_roots()) {
+        for (const p of _rglobSorted(root, pattern)) {
+            push(p);
+        }
+    }
+    if (!_paths_overridden()) {
+        for (const p of iter_commands()) {
+            push(p);
+        }
     }
     return out;
 }
 
+/**
+ * Does this frontmatter actually declare an ADR-013 discovery block?
+ *
+ * Used only by the quarantine-collision check ("listed as unassigned AND
+ * declaring discovery metadata"). `workspaces`, `packs`, `lifecycle` and
+ * `install` are unambiguous ADR-013 names, so their mere presence counts.
+ *
+ * `trust` is NOT unambiguous: it is also a scalar field in two unrelated
+ * template schemas — `trust: durable` on a knowledge card and `trust: low` on a
+ * Class-C lesson card. A bare `'trust' in fm` test read those as discovery
+ * frontmatter and reported both quarantined templates as contradictions. They
+ * are not: ADR-013 `trust` is an OBJECT (`{level, confidence,
+ * human_review_required}`), a shape neither file has. So `trust` counts here
+ * only when it is object-shaped. Across the whole quarantine list these two
+ * strings were the only hits of any of the five names, so this is the complete
+ * fix, not a special case for two paths.
+ */
+function _declares_discovery_frontmatter(fm: Record<string, unknown>): boolean {
+    if (['workspaces', 'packs', 'lifecycle', 'install'].some((k) => k in fm)) {
+        return true;
+    }
+    return 'trust' in fm && isPlainObject(fm['trust']);
+}
+
 function _check_one(
     p: string,
     wsIds: Set<string>,
@@ -101,10 +181,7 @@ function _check_one(
     if (quarantine.has(rel)) {
         const text = fs.readFileSync(p, 'utf-8');
         const [fm] = parse_frontmatter(text);
-        if (
-            isPlainObject(fm) &&
-            ['workspaces', 'packs', 'lifecycle', 'trust', 'install'].some((k) => k in fm)
-        ) {
+        if (isPlainObject(fm) && _declares_discovery_frontmatter(fm)) {
             errs.push(
                 `${rel}: quarantined in unassigned-artefacts.yml but carries` +
                     ' discovery frontmatter — remove one or the other.',
@@ -120,7 +197,22 @@ function _check_one(
         return errs;
     }
 
-    for (const key of ['workspaces', 'packs', 'lifecycle', 'trust', 'install']) {
+    // Only the two keys that carry irreducible information are REQUIRED.
+    //
+    // ADR-013 Phase 4 read as "all five strictly enforced", and this gate was
+    // written that way — but it never ran (dead scan root), while
+    // `validate_frontmatter` DID run, green, for months against
+    // skill.schema.json, whose `required` list is
+    // ["name","description","source","domain"] and which gives `lifecycle`,
+    // `trust` and `install` documented defaults ("active"; every `trust` and
+    // `install` sub-property defaulted). Two gates asserted contradictory
+    // contracts and only one was ever enforced — the enforced one is the real
+    // contract. The corpus agrees and splits cleanly along exactly that line:
+    // `workspaces`/`packs` are absent 0 times in 618 artefacts, while
+    // lifecycle/trust/install are absent 574/459/456 times. A default cannot
+    // invent which workspace or pack an artefact belongs to; it can supply the
+    // other three. See the 2026-08-02 amendment in ADR-013.
+    for (const key of ['workspaces', 'packs']) {
         if (!(key in fm)) {
             errs.push(`${rel}: missing required key \`${key}\``);
         }
@@ -156,42 +248,70 @@ function _check_one(
         }
     }
 
-    const lc = fm['lifecycle'];
-    if (typeof lc !== 'string' || !LIFECYCLES.has(lc)) {
-        errs.push(`${rel}: lifecycle \`${lc}\` not in ${_sortedListRepr(LIFECYCLES)}`);
+    // lifecycle / trust / install: schema-defaulted, so ABSENCE is legal at
+    // BOTH levels — a missing key and a missing sub-key alike take the
+    // documented default. Anything actually written down is still fully
+    // validated; this narrows WHEN the checks fire, never what they accept.
+    //
+    // The sub-key half matters as much as the top-level half: an earlier pass
+    // defaulted an absent `trust` but still demanded all three sub-keys of a
+    // `trust:` block that was present, which is self-contradictory — the same
+    // default was honoured in one branch and refused in the other. It also had
+    // no basis in the corpus: across 288 skills, `trust` is complete 0 times,
+    // partial 120, absent 168. A required shape with 0/288 adoption was never
+    // the real requirement. `validate_frontmatter` — the gate that has actually
+    // been running — agrees: `apply_schema_defaults` fills missing sub-keys
+    // from the schema before validating, which is why it reports 0 failing on
+    // this same tree.
+    if ('lifecycle' in fm) {
+        const lc = fm['lifecycle'];
+        if (typeof lc !== 'string' || !LIFECYCLES.has(lc)) {
+            errs.push(`${rel}: lifecycle \`${lc}\` not in ${_sortedListRepr(LIFECYCLES)}`);
+        }
     }
 
     const trust = fm['trust'];
-    if (!isPlainObject(trust)) {
+    if (!('trust' in fm)) {
+        // schema default: {level: core, confidence: high, human_review_required: false}
+    } else if (!isPlainObject(trust)) {
         errs.push(`${rel}: trust must be a mapping`);
     } else {
-        const level = (trust as Record<string, unknown>)['level'];
-        if (typeof level !== 'string' || !TRUST_LEVELS.has(level)) {
-            errs.push(
-                `${rel}: trust.level \`${_unwrap(level)}\` not in ${_sortedListRepr(TRUST_LEVELS)}`,
-            );
+        const t = trust as Record<string, unknown>;
+        if ('level' in t) {
+            const level = t['level'];
+            if (typeof level !== 'string' || !TRUST_LEVELS.has(level)) {
+                errs.push(
+                    `${rel}: trust.level \`${_unwrap(level)}\` not in ${_sortedListRepr(TRUST_LEVELS)}`,
+                );
+            }
         }
-        const confidence = (trust as Record<string, unknown>)['confidence'];
-        if (typeof confidence !== 'string' || !TRUST_CONFIDENCE.has(confidence)) {
-            errs.push(
-                `${rel}: trust.confidence \`${_unwrap(confidence)}\` not in` +
-                    ` ${_sortedListRepr(TRUST_CONFIDENCE)}`,
-            );
+        if ('confidence' in t) {
+            const confidence = t['confidence'];
+            if (typeof confidence !== 'string' || !TRUST_CONFIDENCE.has(confidence)) {
+                errs.push(
+                    `${rel}: trust.confidence \`${_unwrap(confidence)}\` not in` +
+                        ` ${_sortedListRepr(TRUST_CONFIDENCE)}`,
+                );
+            }
         }
-        const hrr = (trust as Record<string, unknown>)['human_review_required'];
-        if (typeof hrr !== 'boolean') {
-            errs.push(`${rel}: trust.human_review_required must be bool`);
+        if ('human_review_required' in t) {
+            if (typeof t['human_review_required'] !== 'boolean') {
+                errs.push(`${rel}: trust.human_review_required must be bool`);
+            }
         }
     }
 
     const install = fm['install'];
-    if (!isPlainObject(install)) {
+    if (!('install' in fm)) {
+        // schema default: {default: true, removable: false}
+    } else if (!isPlainObject(install)) {
         errs.push(`${rel}: install must be a mapping`);
     } else {
-        if (typeof (install as Record<string, unknown>)['default'] !== 'boolean') {
+        const i = install as Record<string, unknown>;
+        if ('default' in i && typeof i['default'] !== 'boolean') {
             errs.push(`${rel}: install.default must be bool`);
         }
-        if (typeof (install as Record<string, unknown>)['removable'] !== 'boolean') {
+        if ('removable' in i && typeof i['removable'] !== 'boolean') {
             errs.push(`${rel}: install.removable must be bool`);
         }
     }
@@ -223,6 +343,22 @@ function main(argv?: readonly string[]): number {
 
     const [wsIds, packIds, quarantine] = _load_vocab();
     const artefacts = _iter_artefacts();
+    // Scope assertion: 0 artefacts means every root moved, not that the tree
+    // is clean. That was this gate's shipped state until 2026-08-02.
+    try {
+        assertScanned({
+            gate: 'lint_artefact_frontmatter',
+            scanned: artefacts.length,
+            units: 'artefact(s)',
+            roots: _scan_roots().map(([r]) => _relPosix(r) || '.'),
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
     const allErrs: string[] = [];
     for (const p of artefacts) {
         allErrs.push(..._check_one(p, wsIds, packIds, quarantine));
@@ -235,6 +371,18 @@ function main(argv?: readonly string[]): number {
         process.stderr.write(
             `\n${allErrs.length} violation(s) across ${artefacts.length} artefact(s).\n`,
         );
+        if (!_paths_overridden()) {
+            const verdict = checkRatchet({
+                gate: 'lint_artefact_frontmatter',
+                actual: allErrs.length,
+                repoRoot: ROOT,
+            });
+            if (verdict.ok) {
+                process.stdout.write(`⚠️   ${verdict.message}\n`);
+                return 0;
+            }
+            process.stderr.write(`❌  ${verdict.message}\n`);
+        }
         return 1;
     }
     if (!args.quiet) {

package/src/scripts/lint_command_routing.ts

@@ -25,6 +25,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 // src/scripts/lint_command_routing.ts → repo root is two dirs up. Mirrors the
 // Python `Path(__file__).resolve().parent.parent.parent`.
 const _HERE = fileURLToPath(import.meta.url);
@@ -109,61 +111,18 @@ function _rglobNameSorted(dir: string, name: string): string[] {
     return out.sort();
 }
 
-/** Recursively list `*.md` files under `dir`, sorted. */
-function _rglobMdSorted(dir: string): string[] {
-    const out: string[] = [];
-    const walk = (current: string): void => {
-        let entries: fs.Dirent[];
-        try {
-            entries = fs.readdirSync(current, { withFileTypes: true });
-        } catch {
-            return;
-        }
-        for (const entry of entries) {
-            const full = path.join(current, entry.name);
-            if (entry.isDirectory()) {
-                walk(full);
-            } else if (entry.isFile() && entry.name.endsWith('.md')) {
-                out.push(full);
-            }
-        }
-    };
-    walk(dir);
-    return out.sort();
-}
-
 /**
  * Discover command sources in the post-ADR-051 layout.
  *
- * Authoring lives at src/domains/<domain>/**\/command.md; the legacy
- * packages/*\/.agent-src.uncondensed/commands tree is kept as a fallback for
- * older checkouts.
+ * Authoring lives at `src/domains/<domain>/**\/command.md`. A per-package
+ * `commands/` fallback used to sit behind this for "older checkouts"; that
+ * layout no longer exists in any supported checkout, so the branch was
+ * unreachable — and an unreachable fallback that takes over the moment its
+ * directory reappears is the trap this roadmap is closing, not a safety net.
  */
 function _command_files(): string[] {
     const domains = path.join(ROOT, 'src', 'domains');
-    if (_isDir(domains)) {
-        return _rglobNameSorted(domains, 'command.md');
-    }
-    const packagesDir = path.join(ROOT, 'packages');
-    const legacyRoots: string[] = [];
-    let entries: fs.Dirent[];
-    try {
-        entries = fs.readdirSync(packagesDir, { withFileTypes: true });
-    } catch {
-        entries = [];
-    }
-    // glob("*/.agent-src.uncondensed/commands") — sorted, dirs only.
-    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
-        const d = path.join(packagesDir, entry.name, '.agent-src.uncondensed', 'commands');
-        if (_isDir(d)) {
-            legacyRoots.push(d);
-        }
-    }
-    const out: string[] = [];
-    for (const root of legacyRoots) {
-        out.push(..._rglobMdSorted(root));
-    }
-    return out;
+    return _isDir(domains) ? _rglobNameSorted(domains, 'command.md') : [];
 }
 
 // Central eval store in the post-ADR-051 layout. Eval stems use the
@@ -324,8 +283,18 @@ function main(): number {
     const quiet = _quiet;
 
     const files = _command_files();
-    if (files.length === 0) {
-        process.stderr.write('❌  No command roots found.\n');
+    try {
+        assertScanned({
+            gate: 'lint_command_routing',
+            scanned: files.length,
+            units: 'command file(s)',
+            roots: ['src/domains/**/command.md'],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
         return 3;
     }
 
@@ -364,7 +333,7 @@ function main(): number {
     if (!quiet) {
         process.stdout.write(
             `✅  ${visible} visible command(s) carry intent/routes_to/replaces ` +
-                '+ a routing eval.\n',
+                `+ a routing eval (${files.length} command file(s) scanned).\n`,
         );
     }
     return 0;

package/src/scripts/lint_command_verbs.ts

@@ -25,12 +25,24 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { iter_commands } from './_lib/agent_src.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/lint_command_verbs.ts → three dirs up is the repo root.
 // Mirrors Python `Path(__file__).resolve().parent.parent.parent`.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const VERBS_YML = path.join(ROOT, 'src', 'config', 'discovery', 'command-verbs.yml');
-const _CMD_PATH_RE = /\.agent-src\.uncondensed\/commands\/.+\.md$/;
+/**
+ * Diff-path filter for "is this changed file a command?".
+ *
+ * ADR-051 replaced the flat `commands/` directory with one `command.md` leaf
+ * per verb under `src/domains/<pack>/<subpath>/`. Until 2026-08-02 this regex
+ * still matched the retired layout, so `changed_command_files()` matched
+ * nothing on any diff and the gate printed "No new/changed commands" no matter
+ * what landed — leaving the ADR-041 verb contract unenforced.
+ */
+const _CMD_PATH_RE = /^src\/domains\/.+\/command\.md$/;
 const NAME_RE = /^name:\s*(.*)$/m;
 const TIER_RE = /^tier:\s*(\d+)/m;
 const VISIBILITY_RE = /^visibility:\s*['"]?([A-Za-z-]+)/m;
@@ -196,34 +208,21 @@ function _rglobMd(dir: string): string[] {
     return out;
 }
 
+/**
+ * Every command in the tree, as `--all` sees it.
+ *
+ * Was an enumeration of per-package `commands/` directories, a layout ADR-051
+ * retired; it returned {} on every checkout after that. Now the shared
+ * resolver's command iterator, which knows the `src/domains` leaf shape.
+ */
 function all_visible_command_files(): Record<string, string> {
     const out: Record<string, string> = {};
-    const pkgs = path.join(ROOT, 'packages');
-    let roots: string[] = [];
-    if (_exists(pkgs) && fs.statSync(pkgs).isDirectory()) {
-        // packages/*/.agent-src.uncondensed/commands directories.
-        let pkgDirs: fs.Dirent[];
-        try {
-            pkgDirs = fs.readdirSync(pkgs, { withFileTypes: true });
-        } catch {
-            pkgDirs = [];
-        }
-        for (const d of pkgDirs) {
-            const cand = path.join(pkgs, d.name, '.agent-src.uncondensed', 'commands');
-            if (_exists(cand) && fs.statSync(cand).isDirectory()) {
-                roots.push(cand);
-            }
-        }
-        roots = roots.sort();
-    }
-    for (const root of roots) {
-        for (const md of _rglobMd(root)) {
-            const parts = _relTo(md, ROOT).split('/');
-            if (path.basename(md) === 'AGENTS.md' || parts.includes('_archive')) {
-                continue;
-            }
-            out[_relTo(md, ROOT)] = 'A';
+    for (const md of iter_commands()) {
+        const rel = _relTo(md, ROOT);
+        if (path.basename(md) === 'AGENTS.md' || rel.split('/').includes('_archive')) {
+            continue;
         }
+        out[rel] = 'A';
     }
     return out;
 }
@@ -357,11 +356,31 @@ function main(): number {
     const args = parse_args(process.argv.slice(2));
 
     const { approved, banned, grandfathered } = load_config();
-    const targets = args.all ? all_visible_command_files() : changed_command_files(args.baseline);
+    // Scope assertion: this is a diff gate, so an empty TARGET set is normal
+    // (nothing changed). What is never normal is an empty COMMAND CORPUS — that
+    // means the path filter and the walk root no longer describe the tree, and
+    // the diff can never match. Assert on the corpus, not on the diff.
+    const corpus = all_visible_command_files();
+    try {
+        assertScanned({
+            gate: 'lint_command_verbs',
+            scanned: Object.keys(corpus).length,
+            units: 'command file(s)',
+            roots: ['src/domains/**/command.md'],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
+    const targets = args.all ? corpus : changed_command_files(args.baseline);
     if (Object.keys(targets).length === 0) {
         if (!args.quiet) {
             process.stdout.write(
-                `✅  No new/changed commands under commands/ (baseline: ${args.baseline}).\n`,
+                `✅  No new/changed commands under src/domains/ (baseline: ${args.baseline}; ` +
+                    `${Object.keys(corpus).length} command(s) in scope).\n`,
             );
         }
         return 0;

package/src/scripts/lint_context_spine_usage.ts

@@ -18,16 +18,24 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const QUIET = process.argv.slice(2).includes('--quiet');
 
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-// Mirror the Python glob order: each pattern is rglob'd + sorted, then the
-// patterns are concatenated in declaration order.
-const SKILL_GLOBS = [
-    '.agent-src.uncondensed/skills',
-    'dist/agent-src/skills',
-] as const;
+/**
+ * Skill roots in precedence order — FIRST match wins; they are not unioned.
+ *
+ * The inherited list concatenated its patterns, which was safe only because
+ * the first one — the pre-ADR-051 source container — never matched anything
+ * after the move. So this gate has been linting the `dist/` projection rather
+ * than source. Repointing the first entry at `src/skills` while keeping the
+ * concatenation would double-count: both roots hold the same 288 skills.
+ * Hence first-wins — `src/skills` is the source of truth, `dist/` stays as the
+ * fallback for an installed tree that has no `src/`.
+ */
+const SKILL_GLOBS = ['src/skills', 'dist/agent-src/skills'] as const;
 const VALID_SLOTS = [
     'product',
     'team',
@@ -136,13 +144,30 @@ function _relPosix(target: string, root: string): string {
 }
 
 function main(): number {
-    const skills: string[] = [];
+    let skills: string[] = [];
+    let usedRoot = SKILL_GLOBS[0] as string;
     for (const pattern of SKILL_GLOBS) {
-        skills.push(..._rglobSkillSorted(path.join(REPO_ROOT, pattern)));
+        const found = _rglobSkillSorted(path.join(REPO_ROOT, pattern));
+        if (found.length > 0) {
+            skills = found;
+            usedRoot = pattern;
+            break;
+        }
     }
-    if (skills.length === 0) {
-        process.stderr.write('❌  no SKILL.md files matched\n');
-        return 1;
+    // Scope assertion: no SKILL.md under ANY root means every root moved.
+    try {
+        assertScanned({
+            gate: 'lint_context_spine_usage',
+            scanned: skills.length,
+            units: 'SKILL.md file(s)',
+            roots: SKILL_GLOBS as readonly string[],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
     }
     let failed = 0;
     let declared = 0;
@@ -172,7 +197,8 @@ function main(): number {
     if (!QUIET) {
         process.stdout.write(
             `✅  ${declared} skill(s) declare context_spine; ` +
-                `all declared slots are cited in the body\n`,
+                `all declared slots are cited in the body ` +
+                `(${skills.length} SKILL.md scanned under ${usedRoot})\n`,
         );
     }
     return 0;