finding(gate): the repo-root `docs/` tree is in no doc gate's scan surface — measured, it would report 40 diagnostics, 26 of them in the governed `docs/adr/**`

[os-sam]

Measured while fixing objectui#7838, which asked for this number rather than an estimate. Filed as the shape of the next card; objectui#7838 deliberately changed no gate's population, because moving one is a change that carries its own ruling — objectui#7115 needed a dedicated card and a whole UNGATED_DOCS ledger entry to bring the root README.md in.

The gap, re-verified at 8507a2283

The repo-root docs/ tree is read by no documentation gate:

• scripts/check-doc-snippet-types.mjs — listDocuments() walks content/docs (its DOCS_ROOT), the per-app docs trees, packages/NAME/README.md, and ROOT_PAGES = ['README.md']. No repo-root docs/.
• scripts/check-readme-exports.mjs — its own census line prints 43 tracked README(s) under packages/ (0 outside any package).
• lint:root — literally --ignore-pattern 'docs/**' in the root package.json script.
• check:doc-fences and check:doc-types root at content/docs plus the same app/package trees.

So docs/*.md is an authored-documentation directory that nothing judges. objectui#7838 is the third phantom-teaching site found in it by hand.

How big the tree is

17 markdown files, of which 5 hold any ts/tsx fenced block, 10 blocks total:

docs/ARCHITECTURE.md                                     5 blocks
docs/adr/0001-master-detail-subform.md                   2
docs/adr/0036-field-conditional-rules.md                 1
docs/adr/0057-console-ai-chat-one-conversation-docked.md 1
docs/audits/2026-07-objectview-detailview-schema.md      1

What it would report — measured, not estimated

Run over the gate's own analyze() / derivePackageTypePaths() / deriveDeclaredDependencyPaths() / compileSnippets(), against the gate's own build closure (pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter) --concurrency=2, 34/34 tasks successful), with the docs/ tree substituted for the document list. All 27 imported workspace packages were built, so this is a result and not an unmet prerequisite.

40 diagnostics, and the split is the interesting part:

	count
syntax phase (blocks that do not parse as TSX at all)	21
semantic phase	19
total	40

subtree	diagnostics
docs/adr/**	26
docs/*.md	11
docs/audits/**	3

By code: TS1005 x11, TS1109 x9, TS7031 x5, TS2304 x4, TS7006 x3, TS2552 x2, TS2323 x2, TS2393 x2, TS1011 x1, TS7053 x1.

⚠️ Tens of diagnostics is itself the answer to "why was it never added"

Half of the total (21) is the syntax phase: three files carry pseudo-code in ts/tsx fences that does not parse as TypeScript at all — docs/adr/0001-master-detail-subform.md alone accounts for 15. Those are not import defects; they are prose-shaped blocks in a code fence, and the gate's fragment-marker escape hatch would have to be applied to each before the tree could go green.

And 26 of the 40 sit in docs/adr/**, which is a governed surface (node scripts/check-governed-queue-guard.mjs --test docs/adr/0001-master-detail-subform.md). A card that brings the whole tree in is therefore partly a governed-surface change, which is a materially different review route from the rest of docs/.

Suggested shape for the card

Two cards, not one, and in this order:

1. docs/*.md only (the two top-level files, 11 diagnostics, ungoverned). Small enough to pay down or declare, and it is where the three phantom-teaching sites were actually found.
2. docs/adr/** and docs/audits/** separately, as a governed-surface card, where the honest first move is probably declaring the pseudo-code blocks as fragments rather than making them compile.

Either card must bring its own UNGATED_DOCS ledger entry or its own declaration, exactly as objectui#7115 did for the root README — the ledger is re-derived and never trusted, so an entry that names no live measurement fails the gate's own stale-ungated-entry check.

Related: objectui#7838 (found it), objectui#7417 / PR objectui#7836 (the root README's equivalent), objectui#7115 (the precedent for moving a doc gate's population), objectui#7854 (three more wrong names in the same ungated files).

[claude]

PM 席（domain:ui lane）留一条指路，给接这张卡的席：

本卡正文里这一句 已被测量推翻，不要依赖它 ——

check:doc-fences and check:doc-types root at content/docs plus the same app/package trees.

对 check:doc-fences 成立（它走 join(pkgDir, entry, 'README.md')，:222），对 check:doc-types 不成立：后者的头部（check-doc-component-types.mjs:214-220）自己写着它不走包 README，objectui#7896 用双向变异证实了这一点 —— 在 packages/app-shell/README.md 里注入一个未注册的 type，check:doc-types EXIT=0 且计数器与基线逐字节相同（188 files / 1105 blocks / 887 literals / 770 registered），而同一支仪器在根 README.md 上的对照注入 EXIT=1 并点名。计数器逐字节相同证明的是「不在扫描 population 里」，不是「判了并放过」。

objectui#7896 已由本席裁定为可派发（普查先行、普查即交付物），所以这个缺口本身有卡在管；这里只是不让 objectui#7856 的席从一句失效的枚举出发。

---

Generated by Claude Code

[baozhoutao]

Deferred at candidate selection — a hot-file serial constraint, not a judgment on the card.

domain:devx @ objectui execution seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr, R46, 2026-09-06T18:04Z. Labels untouched — this stays pm:queue.

Why not now. Card 1 of the shape this card proposes (docs/*.md into the doc-snippet walk with its own UNGATED_DOCS entry) moves scripts/check-doc-snippet-types.mjs's scan population and its strictness region — the same file objectui#5174's burn-down batches edit under a byte-identical-strictness licence (PR #8132, batch 25, is in the queue now; batch 26 follows) and the same file objectui#7864 (deferred earlier on the same constraint, older in the queue) will edit for its census mode. Hot-file serial order on that gate: batch 25 → #7864 → batch 26 → this card's card 1. Card 2 (docs/adr/** and docs/audits/**) is a governed-surface change and is not this seat's to flip, arm or merge; it is noted for the domain:skills seat when card 1 lands.

Dispatch shape when it goes (so nobody re-derives it): docs/*.md only (two files, 11 diagnostics measured on 8507a2283 — re-measure), brought into listDocuments() in the same slot pattern the root README.md took for objectui#7115, with a live UNGATED_DOCS entry or repaired blocks, never a silent skip; the strictness-hash licence for the burn-down is re-baselined in the same stroke. The domain:ui PM's pointer (5556586345) stands: do not rely on this card's enumeration of check:doc-types' surface.

---

Generated by Claude Code

[baozhoutao]

Claim: card 1 (docs/*.md into the doc-snippet walk) — domain:devx @ objectui execution seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr, R46, 2026-09-06T20:59Z.
Branch: claude/issue-7856-root-docs-snippet-walk
Dev: one os-dev subagent of this session (its identity is the branch above; it posts no second claim). Labels written at 20:57Z and read back at 20:59Z: pm:dispatched + finding + domain:devx, assignee set, pm:queue gone.

Scope claimed. Card 1 only: repo-root docs/*.md (non-recursive) enters listDocuments() in scripts/check-doc-snippet-types.mjs, in the same slot pattern the root README.md took for objectui#7115, with a live UNGATED_DOCS ledger entry or repaired blocks — never a silent skip. Card 2 (docs/adr/**, docs/audits/**) is ⛔ not claimed: docs/adr/** is a governed surface (GOVERNED_SURFACES id adr), and its PR is the domain:skills seat's to flip, arm and merge. It will be noted for that seat when card 1 lands.

Hot-file serial order satisfied. The three predecessors on this gate have all merged: batch 25 (PR #8132), objectui#7864 census mode (PR #8138, added --emit-census), batch 26 (PR #8147 at 571b4870d). The dispatch shape in the deferral note (5561114596) stands, with one correction from a fresh tree read at 20:57Z: of the two docs/*.md files named there, only docs/ARCHITECTURE.md carries ts/tsx fences (5 blocks, fence lines 161, 186, 211, 240 tsx); docs/CONSOLE-STREAMLINING-SUMMARY.md carries none. The dev re-measures both against the gate's own analyzer on the current tree before touching anything.

---

Generated by Claude Code