fix(pm): declare check-role-word's skills root for dispatch-gates derivation

check-role-word walks ROOTS = ['content/docs', 'skills'], but dispatch-gates
builds its watch hints from path literals carrying a separator, so the bare
word `skills` produced no hint at all: a skills-only card derived the content
half and scored this gate `silent`. PR #10038 paid one repair round for it —
a green local union, then `role-word count grew 2 to 3` in CI.

Adds the provenance-only subtree declaration (`skills/**`) in the gate's own
source, the same pattern root-file populations use, with the coupling to ROOTS
pinned in both self-tests. The extractor and hintCovers are untouched: that
refusal of bare single-segment literals is measured and deliberate.

No scanning behaviour changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AeA3nU1B5Q2pgxqxgUrexd

Author: claude

scripts/check-role-word.mjs

@@ -48,6 +48,50 @@ const EXTENSIONS = new Set(['.mdx', '.md']);
 const BASELINE_PATH = 'scripts/role-word-baseline.json';
 const WORD = /\brole(?:s)?\b/gi;
 
+/**
+ * The half of ROOTS that `scripts/pm/dispatch-gates.mjs` cannot see, written in
+ * the subtree spelling that tool compares in. Provenance ONLY: nothing in this
+ * gate reads this list, and the scan above behaves exactly as it did without it.
+ *
+ * ## The gap this closes (#9964's declaration pattern, one class over)
+ *
+ * That tool builds every dispatch's gate list by scanning each gate's own source
+ * for the path literals it operates on, and "looks like a path" there means
+ * "carries a separator". `content/docs` has one; `skills` does not, so no hint
+ * was ever built for it — this gate's population reached the derivation as its
+ * content half plus its baseline artifact, and a card touching only the skills
+ * tree scored `silent`: not "irrelevant", but "its sources name paths, none of
+ * which cover yours", which that tool's residue summary calls its weakest claim
+ * and explicitly not a clearance.
+ *
+ * Not hypothetical. PR #10038 — a skills-only docs fix — derived a green local
+ * union and met this gate as red CI (`role-word count grew 2 → 3`), costing one
+ * repair round. CI enforces either way (lint.yml carries no path filter); what
+ * was missing is discoverability, and this restores it.
+ *
+ * ## Why the subtree spelling, and not a wider extractor
+ *
+ * `hintCovers` refuses a bare single-segment literal (`skills`) as too generic
+ * BY DESIGN, and that refusal is measured, not incidental: teaching the
+ * extractor to accept bare top-level directory words was priced at +139084
+ * fabricated (gate, file) pairs, because `packages`, `apps` and `examples` are
+ * path COMPONENTS in dozens of gates that never read those roots. A declared
+ * subtree is a different claim from a bare word — an author stating what the
+ * gate reads, in the syntax the repo uses for that everywhere else — and the
+ * glob collapse reduces this one back to this gate's second root and to nothing
+ * else. `.claude/skills/...` is NOT under it, which is correct: ROOTS does not
+ * reach there, so the tool must not name this gate for a card that edits it.
+ *
+ * ## Provenance, never a lookup key
+ *
+ * `walk()` runs over ROOTS behind `existsSync`, so the glob form appearing there
+ * would send the scan at a directory that does not exist — skipped in exactly
+ * the silence the green line below is built to expose. The self-test pins both
+ * halves of the coupling: every separator-less ROOT is declared here, and
+ * nothing declared here is itself a ROOTS entry.
+ */
+const ROOT_DIR_WATCH_HINTS = ['skills/**'];
+
 const update = process.argv.includes('--update');
 
 function walk(dir, out) {
@@ -341,6 +385,29 @@ function selfTest() {
     + 'over a dead scan cannot read like a debt fully paid',
     updateSummary(DEAD_SCAN, PAID_OFF) !== updateSummary(SCANNED, PAID_OFF));
 
+  // ── The dispatch-gates declaration (#9964's pattern) ──────────────────────
+  //
+  // Enforcement cannot hold any of these: the declaration 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 a skills card with this gate missing from
+  // the brief. The coupling is derived from ROOTS on both sides rather than
+  // re-spelled, so widening or renaming a root cannot leave the declaration
+  // describing the old population.
+  const separatorless = ROOTS.filter((r) => !r.includes('/'));
+  expect('the declaration exists for every ROOT the hint extractor cannot see (a root with no '
+    + 'path separator is refused as too generic, so it needs the subtree spelling)',
+    separatorless.every((r) => ROOT_DIR_WATCH_HINTS.includes(`${r}/**`)));
+  expect('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) => ROOTS.includes(h.replace(/\/\*+$/, ''))));
+  expect('skills is the root it declares (the half PR #10038 met as red CI)',
+    ROOT_DIR_WATCH_HINTS.includes('skills/**'));
+  // Provenance, never a lookup key: `walk()` runs behind existsSync(root), so
+  // the glob form appearing in ROOTS would skip the root in silence — the exact
+  // failure the per-root green line above exists to make visible.
+  expect('the declared form is NOT a ROOTS entry',
+    !ROOTS.some((r) => ROOT_DIR_WATCH_HINTS.includes(r)));
+
   if (failures.length) {
     for (const f of failures) console.error(`  x self-test: ${f}`);
     console.error(`\ncheck-role-word --self-test: ${failures.length} failure(s).\n`);
@@ -350,7 +417,8 @@ function selfTest() {
     'OK  self-test: the NEW-use remedy marks baseline expansion as maintainer-only, the predicate '
     + 'rejects an unmarked offer, the ratchet-DOWN remedy stays the author\'s own, and both '
     + 'success texts report what was READ \u2014 so a scanned tree and an unscanned one cannot print '
-    + 'the same result once the ledger is empty.',
+    + 'the same result once the ledger is empty. Every separator-less ROOT also declares the '
+    + 'subtree spelling dispatch-gates derives from, and declares nothing this gate does not walk.',
   );
   process.exit(0);
 }

scripts/pm/dispatch-gates.mjs

@@ -2726,6 +2726,37 @@ function selfTest() {
   const anchorRootHints = extractWatchHints(readFileSync(join(ROOT, 'scripts/check-doc-anchors.mjs'), 'utf8'));
   t('and the doc-anchors pair claims neither instruction file', !anchorRootHints.some((h) => hintCovers(h, 'AGENTS.md') || hintCovers(h, 'CLAUDE.md')));
 
+  // The DIRECTORY half of the same class (#10107). A gate whose population is a
+  // top-level DIRECTORY spelled as a bare word is invisible for the same reason
+  // a root file is — `looksPathy` finds no separator, so the extractor builds no
+  // hint at all — and it is the more expensive half, because the word names a
+  // whole subtree rather than one file. `check:role-word` walks
+  // `['content/docs', 'skills']`: the first is a hint, the second was nothing,
+  // so a skills-only card derived the content half and scored this gate
+  // `silent`. PR #10038 paid for it — a green local union, then
+  // `role-word count grew 2 → 3` in CI. It declares the subtree spelling now.
+  //
+  // Read from the real gate, not a fixture: what is pinned is that the tree
+  // still HAS the declaration. If this gate stops walking that root, delete the
+  // declaration and these cases together — never keep them green by re-pointing
+  // at a gate that never read it.
+  const roleWordHints = extractWatchHints(readFileSync(join(ROOT, 'scripts/check-role-word.mjs'), 'utf8'));
+  t('the role-word ratchet reaches the published skills catalog it declares', roleWordHints.some((h) => hintCovers(h, 'skills/objectstack-platform/SKILL.md')));
+  t('and still reaches the content half it always named', roleWordHints.some((h) => hintCovers(h, 'content/docs/deployment/cli.mdx')));
+  // The negative halves, and the reason this is a DECLARATION and not an
+  // extractor change. `.claude/skills/` is the live specimen: a real tracked
+  // tree whose last segment IS the declared root, which this gate does not walk
+  // — a widened extractor accepting the bare word `skills` would not tell them
+  // apart, and the collapsed subtree does.
+  t('and claims nothing under the internal .claude skills tree it never walks', !roleWordHints.some((h) => hintCovers(h, '.claude/skills/pm-dispatch/SKILL.md')));
+  t('nor a package source file', !roleWordHints.some((h) => hintCovers(h, 'packages/spec/src/index.ts')));
+  t('nor the sibling FILE beside the content root', !roleWordHints.some((h) => hintCovers(h, 'content/docs.site.json')));
+  // The pair that makes the declaration worth having: the bare word this gate
+  // actually spells in its ROOTS array stays refused, so the coverage above is
+  // bought by the declaration and by nothing else.
+  t('the bare root word the gate spells in ROOTS is still refused as too generic', !hintCovers('skills', 'skills/objectstack-platform/SKILL.md'));
+  t('while the declared subtree covers that same path', hintCovers('skills/**', 'skills/objectstack-platform/SKILL.md'));
+
   // ── A trailing sentence period is not part of the path (#8534, half two) ──
   //
   // Coupled to the rule above: the raw-prefix comparison reached the real file