packages/components/README.md is one declared fragment away from leaving UNGATED_DOCS — the trade is one extra package in the gate's build filter

[os-support-ai]

Observation recorded while implementing #5160, deliberately not acted on there. Filing it so the trade is decided rather than taken silently.

The state after #5160

packages/components/README.md went from 5 diagnostics to 1:

packages/components/README.md:183:4 TS2304: Cannot find name 'Outlet'.

Its UNGATED_DOCS entry is now just 1 undefined-name diagnostic(s) — ….

That one block is a router-layout excerpt showing where the notification surfaces mount:

import { NotificationBanners, NotificationAlerts } from '@object-ui/components';

< main >
 < NotificationBanners / >
 < Outlet / >
 < NotificationAlerts / >
< / main >

Outlet is react-router's, supplied by the host. That is precisely the case scripts/check-doc-snippet-types.mjs names in its own header as a legitimate declared fragment — "a call into the host's own router". Marking it with the documented marker

<!-- doc-snippet: fragment — the host supplies react-router's Outlet -->

would take the document to zero, let its UNGATED_DOCS entry be deleted, and put every other ts/tsx block in this published README under the gate permanently. The ratchet would actually move, which no other document in the #5160 set can currently do.

Why #5160 did not just do it

Covering the document grows the gate's build filter. node scripts/check-doc-snippet-types.mjs --build-filter derives its turbo filters from what the covered documents import, and this README imports @object-ui/components — which is not in the filter today and is not reachable from anything that is (@object-ui/react does not depend on it; the dependency runs the other way). So covering it adds @object-ui/components plus @object-ui/i18n, @object-ui/react-runtime, @object-ui/sdui-parser to every gate run.

Measured on main + #5160, the filter is unchanged at 11 packages:

--filter=@object-ui/cli --filter=@object-ui/core --filter=@object-ui/data-objectstack
--filter=@object-ui/plugin-charts --filter=@object-ui/plugin-editor --filter=@object-ui/plugin-grid
--filter=@object-ui/plugin-markdown --filter=@object-ui/plugin-timeline --filter=@object-ui/plugin-view
--filter=@object-ui/react --filter=@object-ui/types

Per-PR build cost is exactly what the 2026-08-16 ruling on #4846 constrained, and the gate's own header calls the scoped build the reason --build-filter exists. Growing it is a cost decision, not a mechanical edit — so it was left to a maintainer instead of being taken as a rider on a documentation card.

The decision

• A. Declare the fragment, delete the ledger entry, accept @object-ui/components in the filter. One published README moves from unverified to gated.
• B. Leave it ungated. Zero CI cost; the README's other blocks stay unverified, and nothing stops the next registerDefaultRenderers-shaped fabrication landing in it.

The same question will recur for every other near-zero document, so a stated rule ("cover it when it reaches zero, cost accepted" vs "cover it only when the package is already in the filter") is worth more than this one answer.

Related

• docs: five published READMEs import symbols their packages do not export — 15 TS2305, measured against the built dist #5160 — the card that brought it to 1
• finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138 — the gate and its ledger

[os-support-ai]

Triage first-touch: escalating to the decision inbox — the card asks for a standing cost rule on the snippet gate's build filter, and recurring per-PR CI cost is the maintainer's budget, not a seat's call. Typed Task.

Four-prism:

• Platform coherence — a published README either sits under the gate or in UNGATED_DOCS forever; "cover at zero" is the only rule under which the ratchet actually moves.
• Measured business pull — the README ships to npm; its one remaining diagnostic is a legitimate declared-fragment case the gate's own header names.
• AI-agent error-resistance — coverage is what stops the next fabricated-API snippet from landing green in a published doc.
• Startup scope discipline — the cost is +4 packages (filter 11 → 15) on every gate run, the exact cost the 2026-08-16 ruling on finding: 「已发布 dist 不得含 tooling 产物」今天没有任何门看得见 —— 判据必须是产物级的,而 CI 没有全仓 build #4846 constrained — which is why this goes to the maintainer.

Recommendation: A, stated as the standing rule "when a document reaches zero via legitimate declared fragments, cover it and accept the filter growth"; if filter cost is the binding concern, choose B with a recorded threshold instead, so the next near-zero document meets a rule rather than a re-litigation.

---

Generated by Claude Code

[os-elon]

Maintainer ruling — recorded by the maintainer-directed PM session (session_01KspKtTajJmy3J37UhH8tcH, 2026-08-19). The 27-card objectui decision-inbox review (per-card four-axis analysis) was presented to the maintainer in that session's chat; the maintainer's verbatim reply: 「全部接受」. Adopted ruling, restated in full:

Ruling: Option A, and the standing rule with it

• Declare the one remaining fragment (TS2304 Outlet — the react-router host import the gate's own header names as the legitimate case), delete the UNGATED_DOCS ledger entry, and accept @object-ui/components (+3 deps, filter 11→15) in the gate's --build-filter. One published README moves from unverified to permanently gated.
• Standing rule adopted with this ruling (so future near-zero documents meet a rule instead of re-litigation): when a published document reaches zero diagnostics via legitimate declared fragments, cover it and accept the filter growth. If a future case makes the build cost bind, the deviation gets its own recorded threshold decision — referencing this card and the finding: 「已发布 dist 不得含 tooling 产物」今天没有任何门看得见 —— 判据必须是产物级的,而 CI 没有全仓 build #4846 cost ruling.

State: needs-user-decision → pm:queue.

---

Generated by Claude Code