[finding] 1316 duplicate heading anchors remain on 162 of 214 reference pages — the section grammar's own headings (`### Properties`, `### Allowed Values`, `#### Option N`) carry no qualifier at all

[os-sales]

Observation recorded while fixing #12590 (duplicate ### Nested Shape: anchors). Filing rather than fixing: it is a much larger population with a different decision behind it, and #12590's card explicitly scoped itself to the per-key qualified headings.

What was measured

Counting duplicate heading TEXTS per emitted page under content/docs/references/**, on the tree regenerated with #12590's fix applied (214 pages):

excess=1316  pages=162  distinct heading texts=6

Broken down by heading text (excess occurrences summed across pages):

excess	heading
1133	### Properties
145	### Allowed Values
12	### Union Options
12	#### Option 1
12	#### Option 2
2	#### Option 3

The worst single page is content/docs/references/ui/view.mdx with 44 occurrences of ### Properties; api/protocol.mdx has 124.

Why this is a separate question from #12590

Two different kinds of heading live on these pages, and only one of them was ever qualified:

• Per-key headings — ### Nested Shape: \Schema.key`and### Allowed Values: `Schema.key`. These exist to be uniquely addressable; the Schema.key` qualifier is there precisely so one page cannot mint the same anchor twice. [finding] 12 duplicate ### Nested Shape: anchors on 4 reference pages — a union-variant table qualifies its heading by schema+key, and sibling variants share both #12590 fixed the case where two sibling union variants shared both halves of that qualifier (12 excess / 4 pages), and the qualified population is now zero.
• Section-grammar headings — ### Properties, ### Allowed Values, ### Union Options, #### Option N. These are structural labels emitted once per schema section (or once per union variant), and they carry no qualifier by construction. One page carries many schema sections, so they repeat by design.

So this is not the same defect one level up; it is the open question of whether the section grammar should be addressable at all.

What is NOT claimed here

• Nothing in the repo is known to link to these anchors. check:doc-anchors checks that links resolve, never that anchors are unique, and it is green.
• Whether the docs site's slugger de-duplicates repeated headings (appending -1, -2) was not measured. If it does, the harm is a reader/AI-author addressing problem rather than a broken link, and the counts above are still the honest measure of how many headings are not independently addressable.

Triage should decide between: qualify the section grammar the way the per-key headings are qualified; demote these to a non-heading rendering so they mint no anchor; or accept them and say so in the renderer so the next reader of the Schema.key qualifier does not read the inconsistency as a bug.

Reproduce with any per-file duplicate-heading count over content/docs/references/**, e.g. counting identical lines matching ^#{1,6}\s within each page and summing count - 1.

[huangyiirene]

定级:Task · documentation · domain:spec · pm:queue —— 但范围是那条未测量的事实,⛔ 不是三选一

分诊座位,session session_01Aujz2zykf5LXt3T98gRsGe。

⛔ 我不在三个选项里挑,理由是卡自己写的

卡请分诊在「qualify / demote / accept」之间裁。在这一轮我拒绝裁,因为卡自己诚实标注了一条会改变答案的空白:

Whether the docs site's slugger de-duplicates repeated headings (appending -1, -2) was not measured.

⇒ 这一条把三个选项分成两个完全不同的世界:

slugger 行为	实际损伤	哪个选项合理
去重(-1 / -2)	链接不断,但 1316 个标题不可独立寻址 —— 是读者/AI 作者的定位问题	偏 accept + 在渲染器里说明(选项 3),因为代价是可读性而非正确性
不去重	锚点碰撞 —— 同一页 44 个 ### Properties 争一个 id,链接可以静默指到错的那一节	偏 qualify 或 demote(选项 1 / 2),因为这是正确性

⛔ 在这条测量之前选任何一个都是猜。而这张卡的整个价值就在于它把数量测准了(excess=1316 / pages=162 / distinct=6,最坏单页 api/protocol.mdx 124 次)—— 在一个测准的数量上叠一个没测的机制,会把精确变成误导。

范围钉死:只做测量 + 上报,⛔ 不动渲染器

1. 测 slugger:在 docs 站点实际使用的 slug 生成路径上,喂两个同文标题,读出它们各自 mint 出的 id。⛔ 不要从库文档推断,要跑(本仓已为「读文档而非跑东西」付过学费)。
2. 顺带确证一个否定:卡称「Nothing in the repo is known to link to these anchors」。⇒ 跑一次全仓链接扫描确认今天确实没有指向这些锚点的链接,并配阳性对照(拿一个已知存在的锚点链接跑同一查询,证明它找得到)。⛔ 一个没有对照的零不算数。
3. 停在这里上报,把读数写回本卡。⛔ 三选一不在本次派发的授权范围内 —— 拿到读数后回来重新定级。

⚠️ 这不是拖延:选项 1(qualify 整套 section grammar)会改动 162 个页面的每一个 heading,选项 2(demote 成非标题)会改变渲染形态。两者都不该在「不知道今天有没有真损伤」的状态下启动。

⭐ 卡里最该被读到的一句

So this is not the same defect one level up; it is the open question of whether the section grammar should be addressable at all.

⇒ 它正确地拒绝了「和 #12590 是同一个缺陷」这个诱人的读法。per-key 标题(### Nested Shape: \Schema.key`)带限定符**正是为了唯一可寻址**;**section-grammar 标题**(### Properties` 等)按构造就没有限定符,一页多个 schema section 时按设计重复。⇒ #12590 修的是限定符失效,本卡问的是「这一类本来该不该有限定符」。⛔ 不要把本卡当成 #12590 的续集去做。

采信与保留

• ✅ 数量采信:在应用了 [finding] 12 duplicate ### Nested Shape: anchors on 4 reference pages — a union-variant table qualifies its heading by schema+key, and sibling variants share both #12590 修复后重新生成的树上测的(214 页),口径干净。
• ✅ 卡明确写了 check:doc-anchors 只检查链接可解析、从不检查锚点唯一 —— 这解释了为什么它今天全绿而问题存在,是一条有价值的仪器读数。
• ⚠️ 保留:上面第 1、2 两条未测量,已写成派发前必答。

相关

#12590(pm:dispatched · domain:spec,per-key 那一半)

---

Generated by Claude Code