fix(devx): re-adjudicate 17 bare-root verdicts whose "unspellable" basis is false

#12300 taught `hintCovers` to MATCH a glob in a non-final segment instead of
collapsing it. That retirement was general, but 17 of the TRIAGE map's 26
REFUSE-UNSPELLABLE verdicts were written against the collapse, so each kept
asserting "no precise spelling exists" about a population that now has one —
silently, with `--self-test` green, because the self-test audits keys and
verdicts and never what a `why` SAYS.

Re-measured all 17 on post-merge main, driven through the real hintCovers and
trackedFiles. Every refusal was false of the tree.

Split by measured downstream pull, per the maintainer ruling:

- 15 rows with no recorded consumer move to a new verdict,
  SPELLABLE-UNDECLARED — "a precise live spelling exists; declaration
  deferred, reason recorded". Every record carries a `spelling`, and
  `--self-test` pins each spelling LIVE, PRECISE and COMPLETE in hintCovers'
  own terms against the live corpus. An unpinned vocabulary value is the
  allowlist rot the ruling rejects the option on.
- 2 rows with measured pull get their spelling declared beside their
  population constant under the ROOT_DIR_WATCH_HINTS idiom, and their refusal
  withdrawn to DECLARED-NARROWER: check:objectql-double-limit reaches
  0 -> 2755 of its test corpus, check:skill-refs 9 -> 12 of its reference
  files.

One row was re-measured into a different population, not merely fresher
digits: #12392 made check-skills-token-ratchet walk skill directories
recursively, so its old 11-of-50 filename filter is now a 49-file subtree.

Also fixes a phantom assertion in the new declaration pin: spelling the
needle as a literal lets `includes` find it in the assertion's own source.
The needle is assembled instead. The same shape in check-cli-command-ids is
filed as #12472, unfixed here.

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

Author: claude

packages/spec/scripts/build-skill-references.ts

@@ -36,6 +36,44 @@ const SPEC_SRC = path.resolve(__dirname, '../src');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
 const SPEC_PKG = '@objectstack/spec';
 
+/**
+ * ## The dispatch-gates declaration — the `ROOT_DIR_WATCH_HINTS` idiom (#12310)
+ *
+ * `scripts/pm/dispatch-gates.mjs` derives WHICH gates a card must run by matching the
+ * path literals in each gate's source against the card's changed files. Every literal it
+ * could recover from THIS file was an import specifier (`lib/export-list`,
+ * `@objectstack/spec`, the `*.zod.ts` entries of SKILL_MAP) — none of them a repo path —
+ * plus the emitted-surface string below, which reaches the 9 `_index.md` files this
+ * generator writes and nothing else. `SKILLS_DIR` resolves to a bare single-segment word
+ * that `hintCovers` REFUSES as too generic. So #12310 measured this gate as one no card
+ * can name: the gate that keeps skill cross-references honest, scoring the same quiet
+ * green for every card in the tree, `skills/**` cards included.
+ *
+ * ⚠️ Until #12300 there was nothing honest to write here. The real population —
+ * every file inside each managed `references/` folder — collapsed to a double slash no
+ * tree can hold (#12246), so the only spellable claim was the bare root. #12300 taught
+ * `hintCovers` to MATCH a glob in a non-final segment instead of collapsing it, and the
+ * spelling below is now live: measured at 12 of the 12 tracked reference files, 100%
+ * precise and complete.
+ *
+ * ⛔ Only what this generator actually reads belongs here, and it reads the FOLDER, not
+ * just its own output: `manageDir(refsDir, ownsReferenceEntry(refsDir))` enumerates each
+ * `skills/<name>/references/` and prunes it wholesale, so hand-written notes and
+ * `react-blocks.md` are inputs to the `--check` verdict too. Declaring only the
+ * `_index.md` files would under-name it by three; declaring the bare `skills` root would
+ * name this gate for every SKILL.md and every eval fixture it never opens — a fabricated
+ * lead, which `hintCovers` prices above the silence it would cure.
+ *
+ * ⛔ It must be spelled as a LITERAL, not built from `SKILLS_DIR` — the hint extractor
+ * reads source text, so a computed path would produce no hint and leave this gate exactly
+ * as invisible. This generator carries no `--self-test` of its own, so the coupling is
+ * held from the other side, in `scripts/pm/bare-root-worklist.mjs`: that file's recorded
+ * verdict for this row carries a LIVENESS and PRECISION pin over the live corpus, and
+ * reds if this declaration ever over-names or goes dead. A declaration that can drift
+ * from the scan is worse than none — it replaces a silent gate with a lying one.
+ */
+export const ROOT_DIR_WATCH_HINTS = ['skills/*/references/**'];
+
 const CHECK = process.argv.includes('--check');
 const { emit, manageDir, flush } = createSink({ check: CHECK, repoRoot: REPO_ROOT });
 

scripts/check-objectql-double-limit.mjs

@@ -230,6 +230,38 @@ const repoRoot = resolve(__dirname, '..');
 const BASELINE_PATH = 'scripts/objectql-double-limit.baseline.json';
 const SCAN_ROOT = 'packages';
 
+/**
+ * ## The dispatch-gates declaration — the `ROOT_DIR_WATCH_HINTS` idiom (#12322)
+ *
+ * `scripts/pm/dispatch-gates.mjs` derives WHICH gates a card must run by matching the
+ * path literals in each gate's source against the card's changed files. `SCAN_ROOT`
+ * above is a bare single-segment word, which `hintCovers` REFUSES as too generic (a
+ * measured refusal, +139084 fabricated pairs, and it stays). The population sentence
+ * this gate does state — every `*.test.ts` under that root — lives in a COMMENT, which
+ * the hint extractor masks by design. So before this declaration the derivation reached
+ * this gate for 0 of the ~2755-file test corpus: #12322 measured it, and a dev adding a
+ * hand-written ObjectQL double ran a full green local union with no signal that the gate
+ * exists to fail on it.
+ *
+ * ⚠️ Until #12300 there was nothing honest to write here. Every glob spelling of this
+ * population collapsed to a malformed double-separator prefix matching NOTHING, so the
+ * only spellable claim was the bare root — TRUE of 2755 test files and FALSE of the
+ * ~2500 non-test files under the same root, the costlier error, since a find double can
+ * only land in a test file. #12300 taught `hintCovers` to MATCH a glob in a non-final
+ * segment instead of collapsing it, so the precise spelling below is live: measured at
+ * 2755 of 2755 on this tree, 100% precise and complete against `testFilesUnder`'s own
+ * admission.
+ *
+ * ⛔ It must be spelled as a LITERAL, not built from `SCAN_ROOT` — the hint extractor
+ * reads source text, so a computed `` `${SCAN_ROOT}/**` `` would produce no hint and
+ * leave the gate exactly as invisible. Both directions are pinned in `--self-test`
+ * below, and the recorded verdict for this row in `scripts/pm/bare-root-worklist.mjs`
+ * carries its own liveness-and-precision pin over the live corpus. A declaration that
+ * can drift from the scan is worse than none — it replaces a silent gate with a lying
+ * one.
+ */
+const ROOT_DIR_WATCH_HINTS = ['packages/**/*.test.ts'];
+
 // ---------------------------------------------------------------------------
 // The probe vocabulary. Field names are deliberately synthetic so no double can
 // special-case them (many branch on `organization_id`, `user_id`, `id`).
@@ -1163,6 +1195,47 @@ async function selfTest() {
     reconcile(fakeWrong, { 'b.test.ts': { blind: 0, wrong: 1 } }).length === 0
     && reconcile(fakeWrong, { 'b.test.ts': { blind: 1 } }).length === 2);
 
+  // -- the dispatch-gates declaration (#12322's landing obligation) ---------
+  //
+  // Enforcement cannot hold either half here: the declaration is read by ANOTHER TOOL
+  // (`scripts/pm/dispatch-gates.mjs`), so a wrong or stale one runs green in this file
+  // forever and pays itself out as a dev dispatched on a test-file card with this gate
+  // missing from the brief. A missing declaration is a silent gate; a surplus one is a
+  // lying gate. Driven through this gate's OWN corpus walk, not a copy of its regex.
+  const DECLARED_TAIL = '.test.ts';
+  const walked = testFilesUnder(join(repoRoot, SCAN_ROOT))
+    .map((abs) => relative(repoRoot, abs).replace(/\\/g, '/'));
+  // ⚠️ The needle is ASSEMBLED, never spelled. Written as a literal here it would appear
+  // in this assertion's own source text, so `includes` would find it in the check rather
+  // than in the declaration and stay green with the declaration deleted -- a phantom pin.
+  // Measured: the naive spelling survived deleting the whole declaration line.
+  const declNeedle = `'${SCAN_ROOT}/` + '*'.repeat(2) + `/*${DECLARED_TAIL}'`;
+  const ownSource = readFileSync(fileURLToPath(import.meta.url), 'utf8');
+  expect('the declaration is spelled as a LITERAL in this source, not computed -- the hint '
+    + 'extractor reads source text, so a computed root would build no hint at all',
+    ownSource.includes(declNeedle));
+  expect('the declared hint is rooted at the population constant this gate actually walks',
+    ROOT_DIR_WATCH_HINTS.length === 1 && ROOT_DIR_WATCH_HINTS[0].startsWith(`${SCAN_ROOT}/`));
+  expect('the corpus walk is non-empty, so the two directions below judge something',
+    walked.length > 0);
+  expect('nothing is declared that this gate does not walk -- every file testFilesUnder admits '
+    + 'lies under the declared root and ends in the declared extension',
+    ROOT_DIR_WATCH_HINTS.every((h) => h.endsWith(DECLARED_TAIL))
+    && walked.every((f) => f.startsWith(`${SCAN_ROOT}/`) && f.endsWith(DECLARED_TAIL)));
+  // …and the declared filter is a NARROWING rather than the bare root wearing a glob:
+  // a non-test sibling sitting in the same directory as an admitted file is NOT admitted.
+  const admitted = new Set(walked);
+  const siblingDir = walked.length ? dirname(join(repoRoot, walked[0])) : null;
+  const nonTestSibling = siblingDir
+    ? readdirSync(siblingDir)
+      .map((e) => relative(repoRoot, join(siblingDir, e)).replace(/\\/g, '/'))
+      .find((f) => !f.endsWith(DECLARED_TAIL) && statSync(join(repoRoot, f)).isFile())
+    : null;
+  expect('a non-test sibling exists to prove the filter discriminates', Boolean(nonTestSibling));
+  expect('and the declaration is a NARROWING, not the bare root wearing a glob -- that sibling '
+    + 'is under the same root and is NOT in the walk',
+    Boolean(nonTestSibling) && !admitted.has(nonTestSibling));
+
   if (failures.length > 0) {
     console.error(`x check-objectql-double-limit --self-test (${failures.length} failure(s)):\n`);
     for (const f of failures) console.error(`  - ${f}`);