fix(scripts): let dispatch-gates name check:examples-live-imports for an examples card (#10727)

The dispatch derivation scans a gate's module body for path-ish string
literals. This gate's only literal describing its example-app population was
the bare word `examples` (from `'examples/'`, trailing slash trimmed), and
`hintCovers` refuses a separator-less literal as too generic -- a measured
refusal, priced at +139084 fabricated pairs if relaxed. So the gate scored
`unreachable BY CONSTRUCTION` for every card in the tree, and no dispatch
brief named it, including a brief for an `examples/**` edit -- the one change
most likely to break it (#8754).

Declare the subtree spelling the derivation CAN read, following PR #10114:

- `SCAN_ROOTS` makes the two walked roots data, each carrying WHICH PART of it
  is the gate's population (`examples` wholesale, `packages` filtered to test
  files that live-import an example app).
- `ROOT_DIR_WATCH_HINTS = ['examples/**']` -- provenance only; nothing in the
  gate reads it.
- The self-test pins the coupling in BOTH directions, derived from SCAN_ROOTS
  rather than re-spelled, plus the refusal of the filtered root.

Measured answer to the card's open half -- the `packages/**` side stays
undeclared. It is unreachable too (`'packages'` is dropped before `hintCovers`
is consulted, and the gate is not in `CHANGE_KIND_GATES`), but a root hint
covers a whole subtree: `packages/**` would name this gate for all 4861
tracked files under `packages/` to reach the 76 that carry a coupling.


Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

scripts/check-examples-live-imports.mjs

@@ -127,6 +127,107 @@ import { isEntrypoint } from './invoked-as.mjs';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(HERE, '..');
 
+const EXAMPLES_ROOT = 'examples';
+const PACKAGES_ROOT = 'packages';
+
+/**
+ * The two trees this gate walks, and WHICH PART of each is its population.
+ *
+ * The asymmetry is the whole content of this table, and it is why the roots are
+ * written as records rather than as a flat list of directory names:
+ *
+ *   `subtree`  -- read WHOLESALE. Every file under an example app is something
+ *                 a coupling can target, and `couplingTarget()` resolves to
+ *                 arbitrary paths beneath it, so an edit anywhere in the tree
+ *                 can move this gate's verdict. 239 tracked files, effectively
+ *                 all of them in the population.
+ *
+ *   `filtered` -- walked, then narrowed twice: to test files
+ *                 (`TEST_FILE_RE` / `TEST_DIR_RE`), and then to the handful of
+ *                 those that actually live-import an example app. Measured on
+ *                 this tree: 76 coupled files across 3 packages
+ *                 (`@objectstack/dogfood` 72, `@objectstack/cli` 2,
+ *                 `@objectstack/lint` 2) out of 4861 tracked files under
+ *                 `packages/`, of which 2507 are test files.
+ *
+ * `population` is not decoration: `--self-test` reads it to decide which roots
+ * MUST appear in ROOT_DIR_WATCH_HINTS below and which must NOT. Both directions
+ * are derived from this table rather than re-spelled, so renaming a root or
+ * re-scoping what it contributes cannot leave the declaration describing a
+ * population the gate stopped walking.
+ */
+const SCAN_ROOTS = [
+  { dir: EXAMPLES_ROOT, population: 'subtree' },
+  { dir: PACKAGES_ROOT, population: 'filtered' },
+];
+
+/**
+ * The half of SCAN_ROOTS that `scripts/pm/dispatch-gates.mjs` cannot see,
+ * written in the syntax that derivation CAN read.
+ *
+ * ── The defect this repairs ─────────────────────────────────────────────────
+ *
+ * The dispatch derivation scans a gate's module body for path-ish string
+ * literals. The only literal describing this gate's example-app population was
+ * the bare single-segment word `examples` (from `'examples/'`, whose trailing
+ * slash the extractor trims), and `hintCovers` refuses a separator-less literal
+ * as too generic. So this gate scored, for EVERY card in the tree:
+ *
+ *   pnpm check:examples-live-imports  [lint.yml]  dead: 'examples' -- the tree
+ *   HAS it; the covering rule refuses the literal as too generic (no path
+ *   separator)
+ *
+ * A gate in that state is named by no dispatch brief -- including a brief for
+ * the one edit most likely to break it. That is the exact cost shape #8754
+ * records: an examples-only diff runs neither of CI's scoping layers, and the
+ * shared merge queue is the first signal.
+ *
+ * ── Why the subtree spelling, and not a wider extractor ─────────────────────
+ *
+ * The refusal is measured, not incidental, and it is not this file's to relax:
+ * `hintCovers`' docblock prices teaching the extractor to accept bare top-level
+ * directory words at +139084 fabricated (gate, file) pairs, precisely because
+ * `packages`, `apps` and `examples` are path COMPONENTS in dozens of gates that
+ * never read those roots. A declared subtree is a different claim -- an author
+ * stating what this gate reads -- and the glob collapse reduces `examples/**`
+ * back to this root and to nothing else. One gate pays for its own precision
+ * instead of every gate paying for one gate's.
+ *
+ * ── Why `packages/**` is deliberately NOT declared ──────────────────────────
+ *
+ * The `packages/**` test-inventory side is unreachable too, and by a wider
+ * margin: `'packages'` carries no separator either, so `extractWatchHints`
+ * drops it BEFORE `hintCovers` is ever consulted -- it is not even a dead hint.
+ * It is also not reached by the test-file convention trigger
+ * (`CHANGE_KIND_GATES`), which this gate is not listed in. Measured: a
+ * dispatch derivation for `packages/cli/test/i18n-section-coverage.test.ts`
+ * -- the very file #8754 went red on -- names this gate nowhere.
+ *
+ * It stays undeclared anyway, because the instrument cannot express this side's
+ * population. A root hint covers a whole subtree, so `packages/**` would name
+ * this gate for all 4861 tracked files under `packages/` in order to reach the
+ * 76 that carry a coupling: 1.6% precision, pasted into every `packages/**`
+ * dispatch prompt. That is the "22 leads is the same as none" failure the
+ * derivation's header prices a fabricated lead against, bought at a worse ratio
+ * than the wholesale admission it already refuses. The two sides are also not
+ * symmetric in what they cost a dev: a `packages/**` test that couples to an
+ * example app spells `examples/` in its own diff and gets a failure text naming
+ * itself and what to write, while an example-app edit gets no signal at all.
+ *
+ * The refusal is pinned below rather than left in this paragraph, so a later
+ * author who adds `packages/**` meets an assertion instead of prose.
+ *
+ * ── Provenance, never a lookup key ──────────────────────────────────────────
+ *
+ * Nothing in this gate reads this array. The glob form appearing in SCAN_ROOTS
+ * would send `walk()` at a directory that does not exist -- and both walks here
+ * fail SOFT (`existsSync` guard in `exampleApps`/`testFiles`, a swallowed
+ * `readdirSync` throw in `walk`), so the mistake would quietly shrink the
+ * population to nothing while every gate stayed green. The self-test pins that
+ * apart too.
+ */
+const ROOT_DIR_WATCH_HINTS = ['examples/**'];
+
 /**
  * Every `packages/**` test coupling to `examples/**` that CI's scoping layers
  * CANNOT see -- the #8754 population.
@@ -252,7 +353,7 @@ function walk(dir, out = []) {
 
 /** Test files (and the helpers under a test dir that carry couplings into them). */
 function testFiles() {
-  const pkgRoot = join(REPO_ROOT, 'packages');
+  const pkgRoot = join(REPO_ROOT, PACKAGES_ROOT);
   if (!existsSync(pkgRoot)) return [];
   return walk(pkgRoot).filter((abs) => {
     if (!/\.[mc]?[jt]sx?$/.test(abs)) return false;
@@ -263,7 +364,7 @@ function testFiles() {
 
 /** The example apps, by directory and by published package name. */
 function exampleApps() {
-  const root = join(REPO_ROOT, 'examples');
+  const root = join(REPO_ROOT, EXAMPLES_ROOT);
   const apps = [];
   if (!existsSync(root)) return apps;
   for (const e of readdirSync(root, { withFileTypes: true })) {
@@ -741,6 +842,36 @@ function selfTest() {
       '* does not span segments',
       !globCoversTarget('examples/app-showcase/src/*.ts', 'examples/app-showcase/src/ui/x.ts', false),
     ],
+
+    // ── the dispatch-gates declaration (#9964's pattern, #10114's coupling) ──
+    //
+    // Enforcement cannot hold any of these: ROOT_DIR_WATCH_HINTS is read by
+    // another tool entirely, so a wrong or stale one runs green here forever and
+    // pays itself out as a dev dispatched on an examples card with this gate
+    // missing from the brief. Both directions are derived from SCAN_ROOTS rather
+    // than re-spelled, so widening or renaming a root cannot leave the
+    // declaration describing the old population.
+    [
+      'every WHOLESALE root is declared (a root with no path separator is refused as too generic, so it needs the subtree spelling)',
+      SCAN_ROOTS.filter((r) => r.population === 'subtree' && !r.dir.includes('/')).every((r) =>
+        ROOT_DIR_WATCH_HINTS.includes(`${r.dir}/**`),
+      ),
+    ],
+    [
+      'and it declares no root this gate does not walk (a declaration that can drift from the scan is worse than none -- it replaces a silent gate with a lying one)',
+      ROOT_DIR_WATCH_HINTS.every((h) => SCAN_ROOTS.some((r) => r.dir === h.replace(/\/\*+$/, ''))),
+    ],
+    [
+      'a FILTERED root stays undeclared (packages/** would name this gate for 4861 files to reach 76; the measurement is in the docblock)',
+      SCAN_ROOTS.filter((r) => r.population !== 'subtree').every(
+        (r) => !ROOT_DIR_WATCH_HINTS.some((h) => h.replace(/\/\*+$/, '') === r.dir),
+      ),
+    ],
+    ['examples is the root it declares (the #8754 population)', ROOT_DIR_WATCH_HINTS.includes('examples/**')],
+    [
+      'the declared form is NOT a SCAN_ROOTS dir (provenance, never a lookup key: the glob form would send the walk at a directory that does not exist)',
+      !SCAN_ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r.dir)),
+    ],
   ];
 
   let failed = 0;