finding(ci): a root-level markdown file a PR ADDS is not on the shard trigger, and the test written to notice it is the one that does not run

[claude]

Filed bare by the developer seat while closing objectui#9096. ⛔ Not a claim that objectui#9096's change is wrong — this is the residual its own mechanism cannot express, measured on the branch that closes it.

The gap

objectui#9096 put the scripts/__tests__ markdown population on the Test (shard N/4) trigger by adding scripts to SCAN_ROOTS in scripts/markdown-test-inputs.mjs and adjudicating all 45 candidates. After it, the declared class is total over the markdown that EXISTS today — 1734 of 1734 tracked documents.

It is not total over the markdown a pull request ADDS at the repository root:

node -e "import('./scripts/markdown-test-inputs.mjs').then(m=>{
  for (const p of ['NOTES.md','SECURITY.md','AGENTS.md','packages/plugin-grid/NOTES.md'])
    console.log(m.markdownTestInputsAmong([p]).length, p); })"
0 NOTES.md
0 SECURITY.md
1 AGENTS.md
1 packages/plugin-grid/NOTES.md

A document inside a declared tree inherits that tree's declaration the moment it lands — that is what the …/** entries buy. The repository root has no tree spelling, so every root document is declared per file, and a root document nobody has declared yet is not on the trigger.

Why that is not cosmetic

Two tests under scripts/__tests__ read a NEW root markdown file the moment it is tracked, and one of them exists specifically to fail on it:

• check-doc-links.test.ts — "scans EVERY tracked root-level markdown file — the invariant that replaces the list". It runs git ls-files -- '*.md', filters to the root, and fails when a root document has no SCAN_ROOTS row.
• dollar-dialect-alias-census.test.ts — scans every tracked path through a helper module, root documents included.

⇒ a pull request whose only change is "add SECURITY.md" skips Test (shard N/4), and the test written to notice exactly that file does not run. The merge queue catches it and the pull request is dequeued — the same shape, and the same cost, as objectui#8857.

Why it was not fixed on the way past

The ledger's entries are either one exact existing path or a …/** tree, and missingDocuments() reds on a declared path that is not in the tree — so "any future root markdown document" cannot be written down in the vocabulary the file has today. Closing this needs a new spelling (a root-level rule, or a tree entry whose prefix is the repository root), which is instrument work rather than a ledger entry, and objectui#9096's triage said ⛔ not to build an instrument on that card.

Shape of the population

8 tracked root markdown documents today, all declared. The hazard is the next one — which is precisely the moment check-doc-links.test.ts's invariant is supposed to speak.

⚠️ Measured on claude/issue-9096-scripts-tests-markdown-inputs at b41bea392; main at fac5acfa4 has the same gap plus the larger one objectui#9096 closes.

---

Generated by Claude Code