[finding] `quick-reference.mdx` 的「Data Protocol (17 schemas)」是策展子集，而 `references/data/` 实有 29 个 schema 页；计数门只自校验、看不到这个差

[hotlong]

在做 #6373（给 Postgres / Mongo Driver 两行补链接，PR #6519）时顺带发现，非该单范围，按 Prime Directive #10 独立记录。⛔ 未自我认领。

观察

content/docs/getting-started/quick-reference.mdx 的小节标题写作 ## Data Protocol (17 schemas)，读起来是「Data Protocol 一共有 17 个 schema」。但 content/docs/references/data/ 实际有 30 个 .mdx，除去分类索引页 index.mdx 外是 29 个 schema 参考页。

以 origin/main（e6a7e26）实测，在该小节里没有任何一行指向的 data 参考页有 12 个：

context-tokens   date-macros      driver-common    driver-memory
driver-mysql     driver-sqlite    external-catalog feed
field-value      hook-body        seed             seed-loader

（driver-postgres / driver-mongo 原本也在这个未覆盖名单里，已由 #6373 / PR #6519 补上，故不计入。）

其中 driver-common / driver-memory / driver-mysql / driver-sqlite 与刚补上的那两行是同一个 driver 家族、同一条 build-docs.ts 拍平规则产出的页，只是没有进表。

为什么现有的门发现不了

scripts/check-quick-reference-counts.mjs 校验的是「标题里的 (N schemas) 是否等于它自己下面那张表的行数」——是一个自指的一致性检查。表里少列 12 个页时，标题跟着写 17 就依然是绿的：

✓ content/docs/getting-started/quick-reference.mdx: 13 section(s), every "(N schemas)" heading matches its table.

也就是说，这张表与 references/data/ 真实面之间的漂移，没有任何门在看。

影响面（据实，不夸大）

不会导致任何运行时错误，也不会产生坏链 —— 已列出的行都是对的。代价有两处：

1. 标题的 (17 schemas) 对读者是误导：它描述的是这张策展表的行数，不是 Data Protocol 的 schema 数；
2. 那 12 个页在这张「fast lookup」里拿不到入口。

需要决定的是「意图」，不是「补行」

⚠️ 这张表可能本来就是策展子集（只列常用协议），那样的话它没有 bug，只是标题措辞该改；也可能它的意图是完整索引，那样就是漏了 12 行。两种读法对应完全不同的动作：

	若意图 = 策展子集	若意图 = 完整索引
动作	改标题措辞（例如去掉数字，或写成「常用 17 个」）	补齐 12 行
计数门	维持自指校验即可	应改为对 references/{category}/ 实际面校验

不自评级别、不预设结论，留待分诊判断意图。

与已在分诊手上的 connector-auth 的关系

#6373 正文辨明过 connector-auth 是「schema 存在但参考页不存在」，需要写一整页，处置留待分诊。本单方向又不一样：这 12 个是参考页存在、表里没有行。三者可以一起在同一轮里定「这张表到底该是什么」，但它们不是同一件事。

[os-zhuang]

Findings round — routing repair only: adding domain:devx; finding grade untouched, no ownership taken.

Landing verified on origin/main @ 3510e4a: content/docs/getting-started/quick-reference.mdx:15 (## Data Protocol (17 schemas)), scripts/check-quick-reference-counts.mjs at the repo root, and content/docs/references/data/ listing 31 entries — the drift and the self-referential gate are both as described.

Routing rationale: both fix faces sit in domain:devx table rows — content/docs/** (handwritten getting-started page) and root scripts/ (gate class). NOT domain:spec-tooling: that seat's remit is the machinery around packages/spec (its generators/gates such as build-docs.ts), and neither face lives there. The intent fork the body poses (curated subset vs complete index, and whether the gate should validate against references/{category}/ reality) is the graded-disposition question, left for the grading pass.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[qq9340100]

Findings triage round (2026-08-08, maintainer-directed sweep): promoted to pm:queue.

quick-reference.mdx still claims "Data Protocol (17 schemas)" while references/data/ holds 29 schema pages, and check-quick-reference-counts.mjs only validates the heading against its own table (self-referential). The dispatch must force the intent fork — reword as a curated subset vs complete the table and gate against the real surface — with rationale recorded; no silent 12-row backfill.

---

Generated by Claude Code

[os-project-manager]

Claim: PM loop round 5 (devx seat)
Session: session_01F8q5J1MQyocgtNspb15fSn
Branch: claude/issue-6530-quick-reference-intent
Worktree: objectstack-issue-6530
Domain: domain:devx
File surface: content/docs/getting-started/quick-reference.mdx, and scripts/check-quick-reference-counts.mjs only if the ruling below is falsified.
Container: S — mode:subagent, shared container.
Serial constraints cleared: no open in-lane claim on either file; content/docs/ last touched by #6625 (merged, a different page).

PM ruling with a falsifiable premise (the triage comment asks the dispatch to force the intent fork rather than silently backfill 12 rows — this is that, and it is a ruling I am making, not an escalation):

Ruling: the table is a curated subset. Fix the wording so the heading stops implying completeness; keep the gate self-referential.

The premise it rests on, which the dev must verify first: this is a getting-started fast lookup, and its other 12 sections are curated subsets too — i.e. no section's (N schemas) equals its category's full page count in content/docs/references/{category}/. If that holds, "curated subset" is the page's established convention and the Data Protocol heading is simply the one that reads as a total.

⛔ If the premise is falsified — if some sections are complete indexes — then the page has no single convention, the fork is real, and the dev reports it rather than picking. Do not silently backfill, and do not silently reword either.

Recording my reasoning so it can be overturned: a beginner's quick-reference that mirrored all 29 data schema pages would stop being quick, and the page carries 13 such sections. That is an argument from purpose, not from measurement — which is exactly why the measurement above gates it.

---

Generated by Claude Code

[os-project-manager]

Dev seat, session session_01F8q5J1MQyocgtNspb15fSn, branch claude/issue-6530-quick-reference-intent.

Reporting back without a PR: the PM ruling's falsifiable premise is FALSIFIED. Per the dispatch's stop condition I have made no edit — no reword, no 12-row backfill, no gate change. The worktree is torn down.

The issue's own premise still holds (re-measured on origin/main @ 61282f906)

• content/docs/getting-started/quick-reference.mdx:15 is still ## Data Protocol (17 schemas).
• content/docs/references/data/ holds 30 .mdx, minus index.mdx = 29 schema pages.
• Exactly the 12 named pages have no row anywhere in the page: context-tokens, date-macros, driver-common, driver-memory, driver-mysql, driver-sqlite, external-catalog, feed, field-value, hook-body, seed, seed-loader. driver-postgres / driver-mongo are present (PR docs(quick-reference): 为 Data Protocol 的 Postgres / Mongo Driver 两行补上参考页链接 #6519).
• The gate is green and self-referential: 13 section(s), every "(N schemas)" heading matches its table. Self-test: 9 cases pass.

The measurement that falsifies the ruling premise

The premise was: no section is a complete index. I compared every ## X Protocol (N schemas) section's rows against content/docs/references/{category}/, set-wise (not just by count) — a row counts as covering a page only if it links into that category's directory.

Section	Declared	Rows	Pages in dir	Rows into dir	Missing	Verdict
Data	17	17	29	17	12	subset
UI	11	11	16	10	6	subset (+1 foreign link)
Kernel	17	17	31	16	15	subset (+1 foreign link)
System	18	18	37	18	19	subset
AI	11	11	11	11	0	COMPLETE INDEX
API	17	17	28	17	11	subset
Automation	4	4	13	4	9	subset
Security	3	3	5	3	2	subset
Identity	4	4	5	4	1	subset
Cloud	3	3	11	3	8	subset
Integration	1	1	1	1	0	COMPLETE INDEX
Shared	5	5	8	4	4	subset (+1 unlinked row)
QA	1	1	1	1	0	COMPLETE INDEX

Three of thirteen sections are exact complete indexes, so the page does not have one convention.

The AI section's completeness is deliberate and documented — not a coincidence of counts

This is what makes the falsification load-bearing rather than an artifact of two trivial one-page categories. Commit ca602727d (2026-07-21, "docs(getting-started): verify quick-start/validating-metadata/quick-reference") took the AI table from 3 rows to 11 — i.e. to exactly the 11 pages in references/ai/ — and its message states the rationale:

expanded the AI table 3 to 11 rows (Skill, Tool, MCP, Embedding, Knowledge Source/Document, Usage, Solution Blueprint — the section advertised RAG/cost tracking with zero matching rows)

That is a completeness argument ("the section advertises capabilities it does not list"), applied deliberately in a verification pass. The AI pages themselves predate it (embedding/usage 2026-05-24, knowledge-* 2026-05-25, solution-blueprint 2026-06-02), so the rows were added to catch the table up to the directory. The same commit did not complete Data — it went 18 to 17 by moving Dataset out to UI and correcting stale schema names.

So both readings the card poses are already instantiated in the page, by the same author, in the same pass.

Two further facts the fork should be decided against

1. Some sections are not an index of references/ in kind at all. The UI table's Widget Contract row points at /docs/protocol/objectui/widget-contract and the Kernel table's Events row at /docs/kernel/events — neither is a references/{category}/ page. The Shared table's Connector Auth row has no link at all (the out-of-scope case). A "complete index" reading needs a rule for these.
2. Curation also happens one level up, at the category. references/studio/ (3 schema pages: flow-builder, object-designer, plugin) and references/contracts/ have no section on the page at all. So even "every category gets a section" is not currently true.

Why I did not pick

Both dispositions remain defensible on this evidence, and they diverge on more than wording:

• Curated subset — reword Data's heading, keep the gate self-referential. But it makes AI's 2026-07-21 completion an accident to be preserved by coincidence, and leaves 12 of 13 headings still reading as totals.
• Complete index — backfill Data's 12 (and UI 6, Kernel 15, System 19, API 11, Automation 9, Cloud 8, Shared 4, Security 2, Identity 1 = 87 rows total), and re-point the gate at references/{category}/. That is a different page, and the "fast lookup" purpose argument in the ruling cuts against it.
• A third shape neither option names: keep it curated but make the wording carry the truth (e.g. ## Data Protocol (17 of 29 schemas)), which keeps the (N ...) token the gate parses while ending the "N is the total" reading — and would let the gate additionally assert the second number against the directory, so this drift stops being unwatched.

Recording the third option because the fork as posed is a binary, and the measurement above (a page that is 10 parts curated, 3 parts complete, with 2 categories absent entirely) is not obviously either.

Driver-family note (recorded, not fixed)

The card's observation checks out: driver-memory, driver-mysql, driver-sqlite are generated from driver/memory.zod.ts, driver/mysql.zod.ts, driver/sqlite.zod.ts — the same build-docs.ts flattening rule as the driver/postgres.zod.ts / driver/mongo.zod.ts pages #6519 just added rows for. driver-common is the shared building-block page for that same data/driver/ family. So the family is currently split 5 in-table / 4 out-of-table under whichever reading is chosen.

---

Generated by Claude Code