gate(doc-types): walk packages/NAME/README.md, with its ruled DOC_TYPE_EXEMPTIONS entries

[os-try-charles]

Fixes #8115
Part of #7896 — ⛔ #7896 is not addressed in full here; its acceptance is a reading the PM takes at landing.

check:doc-types now walks every packages/NAME/README.md, and the ruled DOC_TYPE_EXEMPTIONS entries land with it.

Why one PR — the ruling, not the card face

Triage 5582405961 ruled option A; 5594701696 answered the follow-up pm:retriage with reading A₁: the ruled entries land in the live table together with #7896's fourth leg, in one change. This card's own fence (⛔ do not land the leg) is overridden by that ruling. A₂ is not available: an entry whose (file, value) the walk never reaches fails as stale-exemption, so entries-first collapses into option C, which 5582405961 excluded as dominated.

The census, re-derived — ⛔ no number inherited

Re-derived on 5585ba55a's base edbcf1e7a with this gate's own deriveRegistryKeys, its fence walker and its type matcher over all 39 packages/NAME/README.md:

README files: 39 | blocks: 396 | type literals: 243 | registry keys: 648
unregistered sites: 28 across 8 file(s) | distinct (file,value) pairs: 25

The widened gate's own first run agrees to the site: 28 findings, and its counter deltas match the standalone instrument exactly (blocks 1107 → 1503 = +396; type literals 901 → 1144 = +243).

⚠️ The formal acceptance wording "22 entries covering 25 sites" no longer holds, and the card's "26 across 12 files" never did. The 12 was corrected to 8 by 5582405961; the gate header's 26 … across 8 files reading was anchored to c30026715 and is stale too. Today it is 25 entries covering 28 sites. The 22/25 shape survives — the table is keyed by (file, value), plugin-grid's multiple covers 3 sites and plugin-dashboard's line covers 2 — only the numbers moved. A reviewer counting 28 rows against 25 correct entries would read correct work as unfinished.

Net of the two predecessor cards, now completed: the activity-timeline site (objectui#8114) and the flow node action site (objectui#8483) are both gone from the census, and four sites the earlier reading did not carry are now in it.

The falsifiable zone — the absence, proven

The claim is not "the gate is green"; it is that a mutated component type in a package README cannot pass any more. Before the leg it passed with byte-identical counters, which is the proof the file was outside the scan population rather than judged and forgiven. Every mutation proved on disk by counting the injected and removed text, every restore by git hash-object equality against the HEAD blob.

run	mutation	exit	counters
before	packages/app-shell/README.md object-view → object-vieeew	0	188 / 1107 / 901, registered 782 — byte-identical to the unmutated run
before, positive control	root README.md grid → griiid	1 at README.md:84	registered 782 → 781
after	the same package-README mutation	1 at packages/app-shell/README.md:62	227 / 1503 / 1144, registered 997 → 996 — the counters MOVE
after, positive control	the same root-README mutation	1 at README.md:84	registered 997 → 996

The control fires in both states, so the zero above is a reading about the tree and not about a broken instrument.

The two couplings, both taken

1. Slot. The leg sits before the root pages in scanDocs — the slot the two sibling walks append it in, which is what keeps the three document lists comparable element by element.
2. The carriage census. check-doc-expression-carriage.mjs imports this gate's surface constants and pins its own walk as an equality against a walk rebuilt from those constants, not against this gate's actual walk — so a leg added here alone leaves that pin GREEN while the two surfaces diverge, finding(docs/gate): the root README's flagship dashboard example teaches stat-card, which nothing registers — and the root README is outside every doc gate's scan surface #7115's shape rebuilt inside the instrument written to prevent it. That census now takes the same leg through PACKAGE_READMES / packageReadmePages, its SURFACE_LABEL names it, and both walks read 227 documents.

Ablation, on the committed state, each with on-disk and restore proof. Removing the leg from the carriage census alone — leaving this gate's leg in place, which is exactly the silent-divergence shape — turns 2 pins red (walks exactly the document set that surface names, reaches every leg of the walk). Removing it from this gate turns 7 red. Before this change that divergence was invisible in both directions.

The entries are rulings, ⛔ not a green switch

5556586208 binds and the gate's own header is explicit that stuffing the table here "would bury the one real defect among 25 entries nobody read". Every entry names its vocabulary and where that vocabulary is declared, cited by symbol rather than by a cross-file line address (AGENTS.md #11).

file	values	vocabulary · declaration
app-shell	autolaunched	FlowSchema.type, the flow PROCESS-KIND enum — a different vocabulary from the four below, four lines away in the same block
app-shell	start decision notify end	FlowNodeAction (@objectstack/spec). start/end are the two FLOW_STRUCTURAL_NODE_TYPES, which is why they are in the enum and absent from NODE_PALETTE
mobile	swipe-left swipe-right	GestureType — ⚠️ not the useGesture/useSpecGesture hook pair the census cited; the hooks consume the union, they do not declare it
mobile	pinch	SpecGestureType via SPEC_GESTURE_TYPES — a different union from GestureType, and pinch is a member of both
plugin-dashboard	line pie bar	DashboardWidgetTypeName, whose spec half is ChartTypeSchema by reference
plugin-gantt	milestone	GanttTaskType
plugin-gantt	fs ss ff sf	GanttLinkType — a different vocabulary from the task kind, same file
plugin-grid	multiple	SelectionConfigSchema.type (3 sites)
plugin-grid	count_unique	ColumnSummarySchema, reused by ColumnSummaryConfigSchema
plugin-kanban	kanban	⚠️ the one value in the group belonging to the vocabulary this gate judges — the bare node key retired by #8802, spelled deliberately in a warning comment; declared by RetiredKanbanNodeSchema = retiredNodeType('kanban', …). Re-register the key and this entry reports stale-exemption
plugin-report	matrix joined	SpecReportTypeName
plugin-report	bar	⚠️ a chart type under chart.type, ⛔ not a report kind — ChartTypeSchema, planned by planReportChart. The census filed it with its neighbours; recorded here as a correction
plugin-view	share kanban date-range	ObjectViewSchema.viewActions[].type, ViewType, FilterUISchema.filters[].type

⛔ Two sites are deliberately absent — they were re-classified as defects and repaired on their own cards, objectui#8114 and objectui#8483. ⭐ No new site was reclassified in this pass: all 25 took the treatment, each with a declaration site in source.

Which pin covers the new entries

every package-README exemption names a vocabulary and a declaration site in check-doc-component-types.test.ts. It reads all 25 entries (asserted non-vacuously), requires each to cite at least two backticked things and to either name a declaring symbol or defer explicitly to the sibling entry that does, and asserts zero stale-exemption findings tree-wide. ⛔ Its first draft used a length floor, which failed a perfectly good GanttLinkType sibling at 119 characters while passing any padded stub at 121 — a character count is a proxy for teaching and was replaced with the substance.

Two claims this branch made false, repaired

• check-doc-snippet-types.mjs's ownership matrix said packages/NAME/README.md is ✗ for this gate, and gave as the reason that "a package README teaches its own package's API rather than the schema vocabulary" — measured false: they teach 243 type literals.
• check-doc-fence-languages.test.ts said this gate "cannot join that comparison" because its surface does not include the package READMEs. The leg now has its own cross-gate pin instead of a sentence.

Surface shrink, guarded

The leg is collected by walk, not by name, so it cannot dangle the way a ROOT_PAGES entry does — it just returns fewer files while every printed count stays plausible. The CLI therefore refuses to publish a verdict when the leg collects nothing, and a pin drives that refusal.

The ledger markdown-test-inputs.mjs owed two packages/** entries: it is the class a markdown-only pull request consults to decide whether the shard that READS that markdown runs at all, and #8857 was a pull request changing exactly one package README whose shard reported success in ten seconds having run nothing.

Verification

Run through os-verify-lock.sh; exit codes captured by redirecting to a file before reading $?, never across a pipe.

check	result
node scripts/check-doc-component-types.mjs	0 — 227 files, 1503 blocks, 1144 literals, 997 registered, 147 exempted, 5 key tables / 61 keys all registered
node scripts/check-doc-expression-carriage.mjs	0 — 227 files across the named surface
node scripts/check-doc-fence-languages.mjs	0
pnpm exec vitest run scripts/	0 — 175 files, 5242 passed, 2 skipped
pnpm exec tsc -p tsconfig.scripts.json --noEmit	0
check-changeset-presence	0 — "0 of them published source … no changeset is owed"
check-governed-queue-guard --test	0 — NOT GOVERNED, 6 paths against 5 surfaces
check-new-cross-file-line-citations	0 (report-only) — see note below
eslint, targeted	0 errors, 0 warnings over the 7 changed files

The check:doc-snippets gate is NOT MEASURED here, by its own refusal: PRECONDITION NOT MET (exit 2) — The snippet program was NOT run, the workspace being unbuilt. That is "I could not look", not a verdict. This branch's change to that file is comment-only (verified: every non-comment line in its diff is empty), so its behaviour is unchanged; CI builds and runs it.

Lint narrowing, declared. The repo-wide population is 5154 files by eslint's own config; the targeted run covered the 7 changed files, counts read from --format json. Invariance: eslint.config.js configures no type-aware program (no project / projectService), so this diff cannot move the verdict on any file it does not touch. Repo-wide there are 95 pre-existing errors across 79 files on main; none is in this diff. Measured on 5585ba55a.

The one line-citation hit is 'unregistered-doc-type :: packages/demo/README.md:2 :: stat-card' — an expected-string assertion on the gate's own computed diagnostic over a throwaway fixture tree, which the gate itself resolves as unresolvable (ambiguous-basename). It is not a stored citation into a real file; it is the same shape as the pre-existing root-README.md pin beside it. Report-only, exit 0.

维护者速读(草稿)

改了什么 — check:doc-types 现在走 packages/NAME/README.md,并带上 25 条已裁定的豁免条目;姊妹的 carriage 普查同步取这条腿。

为什么改 — 这些 README 随 npm 包一起发出去,它们的 type 被两个姊妹门禁读过两遍、被谁都没判过。读者照抄一个不存在的 type,拿到的是红色 OBJUI-001 面板。这正是 #7115 的老毛病换了个目录重演。

风险与代价(含回滚) — 门禁扫描面从 188 个文档扩到 227 个,首跑红了 28 处,全部是别的词汇表、各自有源码声明点,逐条裁定后转绿。⛔ 没有削弱任何既有检查。回滚 = revert 这两个 commit,扫描面回到 188,豁免条目随之消失(它们键控的文件不再在 walk 内,留着会报 stale-exemption)。

席位意见 — (留空)

你要做的 — 复核那 25 条裁定的措辞是否站得住(尤其 plugin-kanban 的 kanban:它是本组里唯一属于本门禁所判词汇表的值,理由是"已退役、故意写出来教人认出拒收");以及 A₁ 这个读法是否仍是你要的。PR 停在 draft,不翻 ready、不入队。

---

⛔ Draft. Not flipped to ready, not enqueued, nothing approved or merged.

🤖 Generated with Claude Code

https://claude.ai/code/session_015h79niBMyoB1xcaQje3uiz

---

Generated by Claude Code

[github-actions]

changeset-claim-re-read

⚠️ 3 pending changeset(s) describe a file this change touches

Their bodies publish verbatim into the CHANGELOG at the next release, so this is a request to re-read them against your diff — addressed here because you are the one seat that can answer it without re-deriving anything.

⛔ Nothing here blocks, and nothing here is a verdict on your change. This gate exits 0, is not a required context, and judges name resolution, never meaning: it asked whether a pending body names a file you touched. "Is this sentence still true?" is the one question it will not answer, and the one you are being asked to answer.

.changeset/8114-detail-tab-activity-timeline.md

• names scripts/check-doc-component-types.mjs → scripts/check-doc-component-types.mjs — edited by this change

  Which type replaces it was read off the registry rather than guessed, using the repository's own derivation — deriveRegistryKeys() from scripts/check-doc-component-types.mjs, the 649-key universe that gate judges against:

.changeset/8499-node-slot-registered-arms.md

• names scripts/check-doc-component-types.mjs → scripts/check-doc-component-types.mjs — edited by this change

  The defect, and the direction it ran. Nine type spellings sat at DECLARED node slots in this repository's own corpora and resolved in no arm of the component union. Eight were registered renderers with fixtures proving they draw; the ninth (my-component) is the reader's own plugin component and carries a written exemption in scripts/check-doc-component-types.mjs. A reader following content/docs/utilities/runner.mdx's own instruction — "copy one, wrap it in a page document … and save it as src/app-data/pages/index.json" — got a document that renders correctly in the browser and is refused by objectui check. That is the expensive direction: the likely reaction is to stop trusting the validator.

.changeset/9533-dashboard-bare-key-converge-plugin-namespace.md

• names scripts/check-doc-component-types.mjs → scripts/check-doc-component-types.mjs — edited by this change

  What changed. The renderer registers as plugin-dashboard:dashboard, the namespace every sibling plugin, both console stubs and the CLI whitelist already use, so the console stubs are cleared on load and all three claimants of the bare key name ONE full type. The retired view:dashboard key answers RetiredDashboardNodeTombstone — an inline refusal, plus a console.error carrying the same text — registered with skipFallback: true so it claims no bare key. Its spelling is withheld from the derived key universe by declaration in scripts/check-doc-component-types.mjs, the same disposition the RETIRED_FIELD_TYPES tombstones take, so objectui check names it rather than blessing it; packages/cli/src/utils/known-schema-types.ts regenerates and loses that one entry.

Read the paragraph, not the line: both false halves of the objectui#8617 claim sat in one paragraph, and correcting either alone would have left it asserting the same wrong thing.

If a claim did go false, correct the body. That is precedented and prose-only, frontmatter untouched; check-changeset-overwrite.mjs will report the correction as its own case 2 ("correcting a declaration on purpose … legitimate"), which is the intended shape — one gate asks for the read, the other records the write.

Not covered, stated so nobody reads this as more: a born-false claim that spells no line address at all (objectui#9495 coordinated one by ORDINAL — "a grep finds that member first" — and deciding that means reading what the sentence means), a claim spelled as a symbol or a package rather than a backticked file name, and a file named ambiguously.

Compared the checked-out tree with edbcf1e7a (merge-base with origin/main): 7 file(s) changed outside .changeset/, read against 1203 pending declaration(s) that publish a body (1762 pending in total). · run

[os-try-charles]

⛔ This PR is green and mergeable, and the seat's enqueue route does not work. It needs a hand that can merge it. domain:devx @ objectui execution seat, session session_015h79niBMyoB1xcaQje3uiz, R85 — measured 2026-09-19T06:3xZ.

What is true about this PR

mergeable: true · mergeable_state: clean · CI 34/34 green on head 5585ba55a, deduped by check name to the newest run (33 distinct + the second Governed Surface Queue Guard the draft→ready flip always adds) · 0 review threads open · 0 requested reviewers · Governed Surface Queue Guard reports NOT GOVERNED.

⇒ Nothing about the change is blocking it.

What is broken

I enqueued it at 05:24Z via the only route available to this seat. The confirmation said:

Auto-merge enabled for objectstack-ai/objectui#9996 (method: , enabled at ). …

⚠️ Empty method, empty timestamp. An hour later the PR had not moved, so I ran the control I should have run first:

reader	#9996 (subject)	#8941 (control, another open PR)
auto_merge	null	populated (merge_method: merge)

⇒ The field is a working reader on this repo and this token. So #9996's null is a real negative, ⛔ not the instrument's silence. Two further facts agree:

• the PR's updated_at is 2026-09-19T05:21:29Z — earlier than the 05:24Z enqueue, so the call left no trace at all; and
• the queue was alive across that window: fix(app-shell): keep a labelable element on every control picker's catalog-failure arm #9995 merged at 05:35:07Z, eleven minutes after my enqueue.

I retried once with MERGE instead of SQUASH. Same empty confirmation, same null. ⛔ That second attempt was my error and could not have worked — this repo reads allow_squash_merge: true, allow_merge_commit: false, allow_rebase_merge: false, so squash was already the only permitted method and the first attempt had it right. #8941's stored merge is a legacy value, ⛔ not evidence of what is permitted today. The method was never the cause.

⛔ I have stopped at two attempts and will not make a third. ⛔ I have not approved this PR, ⛔ have not merged it, and ⛔ will not hand-merge my own PR.

The likely mechanism, stated as a hypothesis and ⛔ not as a finding

allow_auto_merge is true on the repository, and the PR is already clean with every required check green — i.e. there is nothing left for auto-merge to wait for. GitHub refuses enablePullRequestAutoMerge in that state, and the wrapper this seat calls appears to report success while swallowing that refusal, which is what produces the empty method and empty enabled at.

⛔ I cannot confirm this: the read-only GET …/issues/*/timeline that would show the refusal is denied to this seat, and GET /branches/main/protection returns 403. ⇒ stated as the shape that fits every measurement above, ⛔ not as something I verified.

What this PR needs

A merge by someone whose route works — the change itself is finished and green. Nothing here is waiting on the diff.

⚠️ And a correction this seat owes about its own record

Item ⑫ in my patrol notes has said for several rounds that the enqueue is merely unverifiable, on the reasoning that earlier rounds "enqueued blind and landed anyway". That reasoning does not survive today's control. Since the auto_merge field demonstrably works, I have no evidence this route ever enqueued anything — those earlier PRs may well have been merged by a maintainer or another seat while this seat recorded the landing as its own enqueue succeeding. ⛔ I am not claiming they were; I am withdrawing the claim that they prove the route works.

⭐ The rule I broke is one I had already written down: never report a zero from a reader you have not proven can find something. The control that settles it — any other open PR's auto_merge — was one call away for the whole hour, and I recorded the null as uninformative instead of testing it.

— domain:devx @ objectui execution seat, session session_015h79niBMyoB1xcaQje3uiz

---

Generated by Claude Code

[os-try-charles]

Correction to my own comment above (5739938360) — that claim was too broad, and I am withdrawing its headline.

I wrote there that the auto-merge enqueue route does not work. Measured just now (2026-09-20T07:3xZ), against the full open-PR population of this repo (17 PRs, fully paginated):

PR	author	mergeable_state	auto_merge
#10052	os-tesla	behind	enabled 2026-09-20T07:0xZ, merge_method: merge
#8941	os-zhuang	dirty	enabled, merge_method: merge
#9996 (this PR)	os-try-charles	clean	null — two attempts, nothing written
the other 14	—	—	null, never attempted

#10052 was created at 07:06:58Z today and its auto_merge was enabled an hour ago. So the route is not globally broken, and this repo is not missing the feature. My earlier sentence was wrong and should not be acted on as a platform-breakage report.

What survives, narrowed:

1. Two enqueue attempts from this account on this PR wrote nothing at all — auto_merge stayed null while the same reader shows it populated on feat(app-shell,i18n): render the environment admin's read-rate report from the usage endpoint's readRate reading #10052 and chore(deps): lucide-react 1.31.0 -> 1.43.0, with the one retired spelling repaired #8941, and this PR's updated_at never moved past the attempts. That part is still a real negative, not silence.
2. Leading hypothesis, ⛔ not a finding: both PRs that carry auto_merge are not clean (behind, dirty) — they still have something to wait for. This PR is clean with every check green, and GitHub refuses enablePullRequestAutoMerge when there is nothing left to wait on. I cannot separate that from an actor/permission difference read-only (this token reads admin: false, maintain: false, push: true), and I will not probe it with a third write. Radius: n=2 populated cases; the state and the actor are confounded.
3. ⛔ Retracting a second claim: I said chore(deps): lucide-react 1.31.0 -> 1.43.0, with the one retired spelling repaired #8941's stored merge_method: merge was a stale legacy value, since this repo reads allow_merge_commit: false today. feat(app-shell,i18n): render the environment admin's read-rate report from the usage endpoint's readRate reading #10052 stores merge too and was enqueued today, so GitHub evidently does not validate merge_method against the repo's allowed methods at enqueue time. ⇒ a stored merge_method is evidence of nothing about repo policy, in either direction.

The practical position is unchanged: this PR is mergeable: true, mergeable_state: clean, 34/34 checks green deduped by name, no conflicts with the 15 commits main has taken since it opened (zero path overlap — this PR touches only scripts/**). It needs a merge by someone whose route works. I will not attempt a third enqueue, will not hand-merge it, and will not approve it.

---

Generated by Claude Code

[os-try-charles]

Correcting one number in my comment immediately above (5748402086) — I published a count I had not measured.

I wrote 「15 commits main has taken since it opened」. I had measured exactly one of them. The measured figure, GET /compare/<merge-base>...main with the merge base resolved from this PR's head 5585ba55a:

• merge base edbcf1e7a (2026-09-19T03:34:49Z)
• main is ahead by 21 commits, touching 116 files

The conclusion that number was supporting is unaffected and now has a control: of those 116 files, zero are among this PR's seven, and main did move other scripts/__tests__/** files in that window (body-dialect-census.test.ts, body-dialect-producer-scan.test.ts) — so the empty intersection is a real zero, not an instrument that fails to see overlap. This PR still reads mergeable: true / mergeable_state: clean against the current main.

The defect was mine, not the tree's: a supporting count must be greppped before it is published, not estimated in passing.

---

Generated by Claude Code