@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/lint_major_migration_sections.ts

@@ -53,6 +53,23 @@ const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
 export const GATE = 'lint_major_migration_sections';
 export const MIGRATION_PATH = path.join('docs', 'MIGRATION.md');
+
+/**
+ * The consumer-facing index of what every major broke.
+ *
+ * The SECOND obligation this gate carries, and it is the same obligation
+ * pointed at a different reader. `docs/MIGRATION.md` answers "what do I have to
+ * do"; this table answers "what happened, and when" — it is the first thing
+ * somebody planning an upgrade across several majors opens, because it is the
+ * only place the breaks are side by side.
+ *
+ * It stopped at 9.0.0 while the archived changelogs carried 10.0.0 through
+ * 16.0.0. Seven majors with no row, and nothing in the tree could see it: the
+ * forward half (`lint_scheduled_deprecations`) looks at commitments, the
+ * backward half looked only at `MIGRATION.md`, and the index was guarded by
+ * nobody. The source that reported it counted the report as its twentieth.
+ */
+export const BREAKING_INDEX_PATH = 'BREAKING_CHANGES.md';
 const CHANGELOG_PATH = 'CHANGELOG.md';
 const ARCHIVE_DIR = path.join('docs', 'archive');
 
@@ -145,8 +162,37 @@ export function migrationVersions(text: string): Set<string> {
     return out;
 }
 
+/**
+ * Versions the breaking-changes index carries a ROW for.
+ *
+ * Reads the FIRST cell only, and that is the load-bearing choice rather than a
+ * parsing convenience. The live table's Migration cells end in pointers like
+ * "See [CHANGELOG 8.0.0](CHANGELOG.md)", so a whole-line scan would hand the
+ * index rows it does not have — and would do it in the direction that makes the
+ * gate green, which is the direction a reader cannot detect.
+ *
+ * The bold spelling the table happens to use is not required: a row is a row.
+ */
+export function indexVersions(text: string): Set<string> {
+    const out = new Set<string>();
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|')) continue;
+        const first = trimmed.slice(1).split('|')[0];
+        if (first === undefined) continue;
+        for (const m of first.matchAll(/(?<![\d.])(\d+)\.0\.0(?![\d.])/g)) {
+            out.add(`${m[1] as string}.0.0`);
+        }
+    }
+    return out;
+}
+
+/** Which of the two obligations a major failed. Never empty on a finding. */
+export type MissingKind = 'migration' | 'index';
+
 export interface Finding {
     readonly section: MajorSection;
+    readonly missing: readonly MissingKind[];
 }
 
 /** Read every changelog file under `root`, newest-era file first. */
@@ -171,15 +217,23 @@ export interface EvaluateResult {
 }
 
 /**
- * Compare the majors found against the sections MIGRATION.md carries.
+ * Compare the majors found against BOTH records a breaking major owes.
  *
  * Every section reaches exactly one ledger outcome: out of scope below the
- * floor, out of scope with no BREAKING entries, completed when a heading
- * exists, failed when it does not.
+ * floor, out of scope with no BREAKING entries, completed when both records
+ * name it, failed when either does not.
+ *
+ * The two are checked together and reported apart. Together, because they are
+ * one obligation — "a major that broke something is written down where a
+ * consumer looks" — and splitting it across two gates would mean two copies of
+ * `findMajorSections` free to disagree about what a major even is. Apart,
+ * because a finding that says only "17.0.0 is undocumented" leaves the reader
+ * to discover which of two files to open.
  */
 export function evaluate(
     sections: readonly MajorSection[],
     migration: ReadonlySet<string>,
+    index: ReadonlySet<string>,
     ledger: GateLedger,
 ): EvaluateResult {
     const findings: Finding[] = [];
@@ -196,12 +250,24 @@ export function evaluate(
             continue;
         }
         inScope += 1;
-        if (migration.has(s.version)) {
+        const missing: MissingKind[] = [];
+        if (!migration.has(s.version)) missing.push('migration');
+        if (!index.has(s.version)) missing.push('index');
+        if (missing.length === 0) {
             ledger.complete(target);
             continue;
         }
-        ledger.fail(target, `no docs/MIGRATION.md section for ${s.version}`);
-        findings.push({ section: s });
+        ledger.fail(
+            target,
+            missing
+                .map((k) =>
+                    k === 'migration'
+                        ? `no ${MIGRATION_PATH} section for ${s.version}`
+                        : `no ${BREAKING_INDEX_PATH} row for ${s.version}`,
+                )
+                .join('; '),
+        );
+        findings.push({ section: s, missing });
     }
     return { findings, sections: [...sections], inScope };
 }
@@ -220,6 +286,7 @@ export function pendingMajorFinding(
     target: string,
     changelogEntry: string,
     migrationText: string,
+    indexText: string,
 ): string | null {
     const m = /^(\d+)\.0\.0$/.exec(target.trim());
     if (m === null) return null;
@@ -227,12 +294,19 @@ export function pendingMajorFinding(
     const breaking = sections.reduce((n, s) => n + s.breaking, 0);
     if (breaking === 0) return null;
     if (Number(m[1]) < FLOOR_MAJOR) return null;
-    if (migrationVersions(migrationText).has(target)) return null;
+    const owed: string[] = [];
+    if (!migrationVersions(migrationText).has(target)) {
+        owed.push(`${MIGRATION_PATH} has no "## " heading naming ${target}`);
+    }
+    if (!indexVersions(indexText).has(target)) {
+        owed.push(`${BREAKING_INDEX_PATH} has no row naming ${target}`);
+    }
+    if (owed.length === 0) return null;
     return (
         `the ${target} entry carries ${String(breaking)} BREAKING CHANGES entr(y/ies) and ` +
-        `docs/MIGRATION.md has no "## " heading naming ${target}. Add one before the cut — ` +
-        'a section stating that the change asks nothing of a consumer satisfies this, and is ' +
-        'the right answer when it is true. What is not acceptable is silence.'
+        `${owed.join(', and ')}. Add them before the cut — a section stating that the change ` +
+        'asks nothing of a consumer satisfies the first, and is the right answer when it is ' +
+        'true. What is not acceptable is silence.'
     );
 }
 
@@ -264,14 +338,28 @@ function selfTest(): number {
             '',
         ].join('\n');
 
+    const indexTable = (versions: readonly string[]): string =>
+        [
+            '# Breaking Changes',
+            '',
+            '## Breaking changes by major',
+            '',
+            '| Version | Date | What broke | Migration |',
+            '|---|---|---|---|',
+            ...versions.map((v) => `| **${v}** | 2026-01-01 | something | do a thing |`),
+            '',
+        ].join('\n');
+
     const fixture = (
         name: string,
         changelogText: string,
         migrationHeadings: readonly string[],
+        indexRows: readonly string[] = [],
     ): number => {
         const dir = path.join(root, name);
         fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
         fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), changelogText, 'utf8');
+        fs.writeFileSync(path.join(dir, BREAKING_INDEX_PATH), indexTable(indexRows), 'utf8');
         fs.writeFileSync(
             path.join(dir, 'docs', 'MIGRATION.md'),
             ['# Migration Guide', '', ...migrationHeadings.flatMap((h) => [h, '', 'body', ''])].join(
@@ -293,28 +381,48 @@ function selfTest(): number {
             // one half proves the refusal fires, the other that the heading is
             // what clears it, so neither can be satisfied by a gate that always
             // reds or always passes.
-            name: 'the same major passes once the heading exists',
+            name: 'the same major passes once the heading and the index row exist',
             expect: 'accept',
             run: () =>
-                fixture('present', changelog('17.0.0', ['**x:** drop y']), [
-                    '## 17.0.0 — what to do',
-                ]),
+                fixture(
+                    'present',
+                    changelog('17.0.0', ['**x:** drop y']),
+                    ['## 17.0.0 — what to do'],
+                    ['17.0.0'],
+                ),
         },
         {
             name: 'a heading naming a DIFFERENT major does not satisfy the requirement',
             expect: 'reject',
             run: () =>
-                fixture('wrong-version', changelog('17.0.0', ['**x:** drop y']), [
-                    '## 16.0.0 — what to do',
+                fixture(
+                    'wrong-version',
+                    changelog('17.0.0', ['**x:** drop y']),
+                    ['## 16.0.0 — what to do'],
+                    ['17.0.0'],
+                ),
+        },
+        {
+            // The index half of the same pair. Section present, row absent —
+            // so this case can only pass by checking the index, and the
+            // 'present' case above can only pass by accepting a correct one.
+            name: 'a major with a migration section but no index row is refused',
+            expect: 'reject',
+            run: () =>
+                fixture('no-index-row', changelog('17.0.0', ['**x:** drop y']), [
+                    '## 17.0.0 — what to do',
                 ]),
         },
         {
             name: 'an arrow-form heading naming the version satisfies it',
             expect: 'accept',
             run: () =>
-                fixture('arrow', changelog('17.0.0', ['**x:** drop y']), [
-                    '## 16.x → 17.0.0 — what to do',
-                ]),
+                fixture(
+                    'arrow',
+                    changelog('17.0.0', ['**x:** drop y']),
+                    ['## 16.x → 17.0.0 — what to do'],
+                    ['17.0.0'],
+                ),
         },
         {
             name: 'a major BELOW the floor is forgiven',
@@ -336,6 +444,10 @@ function selfTest(): number {
                 const dir = path.join(root, 'no-changelog');
                 fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
                 fs.writeFileSync(path.join(dir, 'docs', 'MIGRATION.md'), '# Migration Guide\n', 'utf8');
+                // The index IS present, so the refusal below can only be the
+                // dead-scan-root one. Without it this case would reject on a
+                // missing file and stop testing what it is named for.
+                fs.writeFileSync(path.join(dir, BREAKING_INDEX_PATH), indexTable([]), 'utf8');
                 return runGateCli(repo, script, ['--root', dir, '--quiet'], repo);
             },
         },
@@ -381,6 +493,15 @@ export function main(argv: readonly string[]): number {
         return 1;
     }
     const migration = migrationVersions(fs.readFileSync(migrationFile, 'utf-8'));
+    // An absent index reds rather than skipping the index half. A missing
+    // comparand that silently narrows the comparison is how a gate reports
+    // "nothing wrong" about a question it stopped asking.
+    const indexFile = path.join(root, BREAKING_INDEX_PATH);
+    if (!fs.existsSync(indexFile)) {
+        process.stderr.write(`❌  ${GATE}: ${BREAKING_INDEX_PATH} not found under ${root}\n`);
+        return 1;
+    }
+    const index = indexVersions(fs.readFileSync(indexFile, 'utf-8'));
 
     const sources = changelogSources(root);
     const sections: MajorSection[] = [];
@@ -389,7 +510,7 @@ export function main(argv: readonly string[]): number {
     }
 
     const ledger = new GateLedger(GATE);
-    const result = evaluate(sections, migration, ledger);
+    const result = evaluate(sections, migration, index, ledger);
     const tally = ledger.finalize();
 
     try {
@@ -400,7 +521,7 @@ export function main(argv: readonly string[]): number {
             gate: GATE,
             scanned: tally.planned,
             units: 'major changelog section(s)',
-            roots: [CHANGELOG_PATH, ARCHIVE_DIR],
+            roots: [CHANGELOG_PATH, ARCHIVE_DIR, MIGRATION_PATH, BREAKING_INDEX_PATH],
         });
     } catch (exc) {
         if (exc instanceof DeadScopeError) {
@@ -412,13 +533,22 @@ export function main(argv: readonly string[]): number {
 
     if (result.findings.length > 0) {
         for (const f of result.findings) {
+            const owed = f.missing
+                .map((k) =>
+                    k === 'migration'
+                        ? `${MIGRATION_PATH} carries no "## " heading naming it`
+                        : `${BREAKING_INDEX_PATH} carries no row naming it`,
+                )
+                .join(', and ');
             process.stderr.write(
                 `❌  ${GATE}: ${f.section.version} ships ${String(f.section.breaking)} BREAKING ` +
                     `CHANGES entr(y/ies) (${f.section.source}:${String(f.section.line)}) and ` +
-                    `${MIGRATION_PATH} carries no "## " heading naming it.\n` +
-                    `    Add a section for ${f.section.version}. A section stating that the change\n` +
-                    '    asks nothing of a consumer satisfies this and is the right answer when it\n' +
-                    '    is true — the requirement is a stated answer, never a procedure.\n',
+                    `${owed}.\n` +
+                    `    Add what is missing for ${f.section.version}. A migration section stating\n` +
+                    '    that the change asks nothing of a consumer satisfies that half and is the\n' +
+                    '    right answer when it is true — the requirement is a stated answer, never a\n' +
+                    `    procedure. The ${BREAKING_INDEX_PATH} row is one line in the by-major table,\n` +
+                    '    linking the changelog section it came from.\n',
             );
         }
         return 1;
@@ -429,7 +559,7 @@ export function main(argv: readonly string[]): number {
         process.stdout.write(
             `✅  ${GATE}: ${String(tally.planned)} major section(s) read, ` +
                 `${String(result.inScope)} in scope (major >= ${String(FLOOR_MAJOR)} with BREAKING ` +
-                'CHANGES), each with a migration section' +
+                'CHANGES), each with a migration section and an index row' +
                 (result.inScope === 0
                     ? ' — NONE in scope this run, so no comparison ran. Green here means\n' +
                       '    "nothing to compare", not "the comparison passed".\n'

package/src/scripts/lint_pack_boundaries.ts

@@ -34,10 +34,19 @@
  *   this gate now matches that definition.
  * - **BROKEN deliberately:** exit code 2 is new (dead scan scope). 0 and 1
  *   keep their meanings.
+ * - **BROKEN deliberately (2026-10-01):** the always-installed set is the
+ *   hard-coded `core` PLUS every pack flagged `always_on: true`. The original
+ *   knew only `core`, so it reported a violation for a target the resolver
+ *   provably does install — the same defect shape as the direct-vs-transitive
+ *   `requires` comparison above. `config/packs.resolve_active_packs` seeds the
+ *   active set with the always-on packs before expanding any selection, and
+ *   `docs/contracts/capability-packs.md` § Always-on packs states such a pack
+ *   "cannot be deselected". One-way: a link OUT of an always-on pack into a
+ *   gated one still dangles and is still reported.
  * - **STILL HOLDS:** the CLI surface (`--format text|json`, `--quiet`, `-h`),
  *   the link regex and its fragment/query stripping, link-resolution semantics
  *   (external / absolute / out-of-tree targets ignored), the allow rule
- *   (same pack · `core` · declared `requires`), the per-violation text and
+ *   (same pack · always-installed · declared `requires`), the per-violation text and
  *   JSON shapes, the stdout/stderr split, and exit 0 clean / 1 violations.
  *
  * ## Where the `requires` graph is read from
@@ -115,6 +124,47 @@ const LINK_RE = /\[[^\]]*\]\(([^)#?]+)(?:[#?][^)]*)?\)/g;
 /** A pack every install carries — a link into it can never dangle. */
 const ALWAYS_INSTALLED = 'core';
 
+/**
+ * Packs every projection carries, so a link INTO one can never dangle.
+ *
+ * `core` is the hard-coded floor. Beyond it, `always_on: true` in the pack
+ * vocabulary means exactly this: `config/packs.resolve_active_packs` seeds the
+ * active set with every always-on pack BEFORE expanding the selected profile's
+ * `requires` closure, and `docs/contracts/capability-packs.md` § Always-on
+ * packs states the pack "is never gated by the selected profile, workspace, or
+ * pack set, and it cannot be deselected".
+ *
+ * Reading only `core` was the same class of defect this file's header already
+ * records for the direct-vs-transitive `requires` comparison: the gate reported
+ * a violation for a target the resolver provably does install. The direction is
+ * one-way — a link OUT of an always-on pack into a gated one still dangles and
+ * is still a violation.
+ */
+function _always_installed_packs(): Set<string> {
+    const out = new Set<string>([ALWAYS_INSTALLED]);
+    if (_exists(VOCAB)) {
+        const vocab = parseYaml(fs.readFileSync(VOCAB, 'utf-8'), { version: '1.1' });
+        if (Array.isArray(vocab)) {
+            for (const entry of vocab) {
+                if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
+                    const e = entry as Record<string, unknown>;
+                    if (typeof e['id'] === 'string' && e['always_on'] === true) {
+                        out.add(e['id']);
+                    }
+                }
+            }
+        }
+    }
+    for (const dir of _pack_home_dirs()) {
+        const meta = _load_pack_meta(dir);
+        if (meta['always_on'] === true) {
+            const id = typeof meta['id'] === 'string' ? meta['id'] : path.basename(dir);
+            out.add(id);
+        }
+    }
+    return out;
+}
+
 type ViolationKind =
     /** Link crosses into a pack the source pack does not require. */
     | 'cross-pack'
@@ -479,11 +529,16 @@ function _scan_file(p: string): string[] {
     return out;
 }
 
-function _is_allowed(source_pack: string, target_pack: string, requires: string[]): boolean {
+function _is_allowed(
+    source_pack: string,
+    target_pack: string,
+    requires: string[],
+    always_installed: ReadonlySet<string> = new Set([ALWAYS_INSTALLED]),
+): boolean {
     if (source_pack === target_pack) {
         return true;
     }
-    if (target_pack === ALWAYS_INSTALLED) {
+    if (always_installed.has(target_pack)) {
         return true;
     }
     return (requires || []).includes(target_pack);
@@ -501,10 +556,11 @@ function _link_allowed(
     source_packs: readonly string[],
     target_packs: readonly string[],
     closureOf: (pack: string) => Set<string>,
+    always_installed: ReadonlySet<string> = new Set([ALWAYS_INSTALLED]),
 ): boolean {
     return source_packs.every((s) => {
         const reach = [...closureOf(s)];
-        return target_packs.some((t) => _is_allowed(s, t, reach));
+        return target_packs.some((t) => _is_allowed(s, t, reach, always_installed));
     });
 }
 
@@ -597,6 +653,7 @@ function main(argv?: readonly string[]): number {
     }
 
     const pack_requires = _pack_requires();
+    const always_installed = _always_installed_packs();
     const closureCache = new Map<string, Set<string>>();
     const closureOf = (pack: string): Set<string> => {
         let c = closureCache.get(pack);
@@ -635,7 +692,7 @@ function main(argv?: readonly string[]): number {
             if (target_packs === undefined) {
                 continue; // docs/, scripts/, root files, unassigned — not pack-scoped
             }
-            if (_link_allowed(src_packs, target_packs, closureOf)) {
+            if (_link_allowed(src_packs, target_packs, closureOf, always_installed)) {
                 continue;
             }
             violations.push({
@@ -743,6 +800,7 @@ export {
     _build_artefact_index,
     _resolve_link,
     _scan_file,
+    _always_installed_packs,
     _is_allowed,
     _link_allowed,
     _load_pack_meta,

package/src/scripts/lint_roadmap_blockers.ts

@@ -3,7 +3,8 @@
  * Hard-gate linter for the roadmap `## Blockers` contract
  * (`templates/roadmaps.md` rule 20 / `roadmap-ci-steps-policy` siblings).
  *
- * Validates, for every active roadmap under `agents/roadmaps/*.md`:
+ * Validates, for every active roadmap and every parked idea one directory
+ * down in `stubs/`:
  *
  *   1. Every `### blocker: <id>` entry declares all five required fields
  *      (Status, Owner, Blocks, What to do, Resolved when).
@@ -22,11 +23,14 @@
  *      road-to-asked-not-parked exists to stop; without this field a marker
  *      cannot distinguish a declined decision from an unoffered one.
  *
- *      HARD, not ratcheted, and it can be: no active roadmap carries a real
- *      checkbox annotation today, so on the day it ships the rule fires on
- *      nothing — the same "no backlog to grandfather" argument the `Class:`
- *      contract above makes. `later/` and `archive/` are outside this gate's
- *      glob and are untouched by it.
+ *      HARD, not ratcheted, and it can be: no file in scope carries a real
+ *      checkbox annotation pointing at a blocker today, so on the day it ships
+ *      the rule fires on nothing — the same "no backlog to grandfather"
+ *      argument the `Class:` contract above makes. Re-measured when `stubs/`
+ *      entered scope on 2026-09-28: 7 stubs carry checkboxes and 0 of them
+ *      carry a `blocked-by:` marker, so the rule stays latent there too.
+ *      `later/`, `archive/` and `skipped/` are outside this gate's glob and
+ *      are untouched by it; `stubs/` is inside it — see § SCOPE.
  *
  *   5. An entry that declares `- **Ownership:**` declares one of the three
  *      OWNER-OWNED classes (`product-owned`, `business-owned`,
@@ -41,10 +45,49 @@
  *      field, so on the day it ships no entry in the tree declares one and the
  *      rule fires on nothing.
  *
+ * SCOPE — the active tree plus `stubs/`, and deliberately nothing else.
+ *
+ * Widened from the active tree alone by an owner ruling on 2026-09-28. Before
+ * it, a stub's hold was unreachable by every blocker gate: a parked idea is
+ * where a hold sits LONGEST, so excluding it exempted exactly the entries most
+ * likely to rot. The rejected alternative was to keep the scope and reword the
+ * acceptance criterion that named this gate — refused because a criterion
+ * edited to match what was achieved stops being an acceptance test.
+ *
+ * Measured on the tree the widening shipped against: 121 files under `stubs/`
+ * (120 stubs plus the directory README), of which 6 carry a `### blocker:`
+ * heading and 4 declare one open inside a `## Blockers` section. Zero hard
+ * violations, zero additions to the decidability ratchet, zero new
+ * active/archived overlaps. So it lands on nothing — the same "no backlog to
+ * grandfather" argument the `Class:` and `Ownership:` contracts make.
+ *
+ * REACH, stated honestly, because the obvious reading of the paragraph above
+ * is wrong: this does NOT hold every future stub blocker to the contract. Both
+ * scanners require the entry to sit under a `## Blockers` heading, and 2 of
+ * today's 6 put it under `## State` instead — so a third of the population is
+ * in the glob and still unread. Stub headings are free-form, unlike the
+ * template-driven roadmaps this gate was written for, so that is the likely
+ * shape rather than an edge case. Widening the glob fixes WHERE the gate looks
+ * and not WHAT it can parse; the second half is the sibling defect recorded in
+ * `stubs/road-to-blocker-parse-visibility.md`, and it is untouched here.
+ *
+ * `later/`, `archive/` and `skipped/` stay OUT, and the reason is not symmetry:
+ * those record decisions already taken (parked, closed, dropped), so a blocker
+ * left unresolved there is history rather than debt. A stub records a decision
+ * still to take. The polarity is pinned in both directions by
+ * `tests/scripts/lint_roadmap_blockers.test.ts` § the scanned scope, so
+ * widening further cannot happen by accident.
+ *
+ * One consequence worth naming rather than discovering: `_archiveOverlap`
+ * defaults its ACTIVE corpus to this glob, so a stub declaring a blocker open
+ * that an archived roadmap also declares open now fails. That is the same
+ * self-contradiction the assertion already caught one directory up, and it
+ * measured 0 on the widening tree.
+ *
  * Fenced code blocks are stripped before scanning so a roadmap that shows
  * the `## Blockers` shape as a documentation example is not flagged.
  *
- * Exit codes: 0 = clean / no active roadmaps, 1 = violations.
+ * Exit codes: 0 = clean / nothing in scope, 1 = violations.
  */
 
 import * as fs from 'node:fs';
@@ -58,7 +101,14 @@ const _HERE = fileURLToPath(import.meta.url);
 const QUIET = process.argv.slice(2).includes('--quiet');
 
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const ROADMAP_GLOB = 'agents/roadmaps/*.md';
+/**
+ * The scanned scope, for display. Two plain globs rather than one brace
+ * expression: nothing globs with this string, and a `{,stubs/}` empty
+ * alternative is bash-only syntax that would mislead anyone who tried.
+ */
+const ROADMAP_GLOB = 'agents/roadmaps/*.md + agents/roadmaps/stubs/*.md';
+/** The one subdirectory inside the glob. See § SCOPE for why only this one. */
+const SCANNED_SUBDIRS: readonly string[] = ['stubs'];
 
 const FENCED_CODE_RE = /^[ \t]*```[^\n]*\n[\s\S]*?^[ \t]*```[ \t]*$/gm;
 const BLOCKERS_SECTION_RE = /^##[ \t]+Blockers[ \t]*$/im;
@@ -370,13 +420,14 @@ function _scanBoth(rawText: string): ScanResult {
     return { hard: violations, decidability };
 }
 
-/** Sorted `agents/roadmaps/*.md` (non-recursive — active roadmaps only). */
-function _globRoadmaps(): string[] {
-    const dir = path.join(REPO_ROOT, 'agents', 'roadmaps');
+/** Sorted `*.md` directly inside `dir` — never recursive. */
+function _globFlat(dir: string): string[] {
     let entries: fs.Dirent[];
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
     } catch {
+        // A missing directory is not an error: `stubs/` is optional, and the
+        // dead-scope assertion in `main` is what catches a MOVED root.
         return [];
     }
     const out: string[] = [];
@@ -388,6 +439,21 @@ function _globRoadmaps(): string[] {
     return out.sort();
 }
 
+/**
+ * The files this gate judges: active roadmaps, plus `stubs/`. See § SCOPE.
+ *
+ * Takes its root so the scope can be driven from a fixture tree. Asserting the
+ * rule against the real tree would only restate today's file list; the test
+ * pins which DIRECTORIES are in and which are out, in both directions.
+ */
+function _globRoadmaps(roadmapRoot: string = path.join(REPO_ROOT, 'agents', 'roadmaps')): string[] {
+    const out = _globFlat(roadmapRoot);
+    for (const sub of SCANNED_SUBDIRS) {
+        out.push(..._globFlat(path.join(roadmapRoot, sub)));
+    }
+    return out;
+}
+
 function _relPosix(target: string, root: string): string {
     return path.relative(root, target).split(path.sep).join('/');
 }
@@ -561,7 +627,7 @@ function main(): number {
     const roadmaps = _globRoadmaps();
     if (roadmaps.length === 0) {
         if (!QUIET) {
-            process.stdout.write(`✅  no active roadmaps under ${ROADMAP_GLOB}\n`);
+            process.stdout.write(`✅  nothing in scope under ${ROADMAP_GLOB}\n`);
         }
         return 0;
     }