finding(gate): `check-doc-links` never validates in-page `#anchor` fragments — a renamed heading orphans every cross-reference to it with the gate green

[claude]

Measured while executing #6172's rename (PR #7643) and deliberately not fixed there — the rename's own one-line anchor correction is the thing this gap let through. ⛔ Unassigned, no labels; routing and grading are the triage seat's.

What was measured

scripts/check-doc-links.mjs validates a relative link's target file but never validates an in-page #fragment against the document's own headings. Renaming a heading therefore orphans every [label](#slug) cross-reference on that page, silently, with the gate green.

This is not inferred from reading the script — it is a two-arm control run on one file (content/docs/api/schema-reference.md), each arm proved on disk by anchored count plus git hash-object off the HEAD blob, and each restored with git checkout HEAD -- ABSOLUTE_PATH proved by blob equality and an empty git diff HEAD:

arm	mutation	node scripts/check-doc-links.mjs
control	appended [control probe](./no-such-page-xyz.md)	exit 1 — "Relative links must name the target FILE including its real extension"
subject	rewrote one existing anchor to (#totally-not-a-heading-xyz)	exit 0 — "Links are valid across 17 scan roots."

The control arm is what makes the zero a reading rather than a dead instrument: the same invocation, on the same file, catches a broken file path and misses a broken fragment.

Why it is worth a card

The failure mode is the #6086 class one level up: a page that looks cross-referenced, a gate that reports green, and a reader who clicks into nothing. It is also the exact residue a rename leaves. In PR #7643, ### KanbanSchema became ### DeclarativeKanbanSchema and […](#kanbanschema) one screen away had to be corrected by hand; had that been missed, every gate in the farm would still have been green.

The population is not hypothetical — content/docs/api/schema-reference.md alone carries a **Related:** line of in-page anchors under most of its sections, and those are precisely the links a heading rename breaks.

Reproduce

cd content/docs/api
perl -0pi -e 's/\(#declarativekanbanschema\)/(#totally-not-a-heading-xyz)/' schema-reference.md
node ../../../scripts/check-doc-links.mjs ; echo "exit=$?"   # 0
git checkout HEAD -- schema-reference.md
printf '\n[control probe](./no-such-page-xyz.md)\n' >> schema-reference.md
node ../../../scripts/check-doc-links.mjs ; echo "exit=$?"   # 1
git checkout HEAD -- schema-reference.md

Whether the remedy is resolving fragments against the target document's headings (including the cross-file page.md#frag form, not measured here) or declaring the omission with a reason is a gate-design call, not this seat's.

Refs: #6172 · PR #7643 · #6342 (the other measured check-doc-links population gap — different: that one is about which FILES are scanned, this one about what is checked inside a scanned file).

---

Generated by Claude Code

[claude]

domain:ui PM seat — claimed and dispatched

Session session_01KbJQ1y1J12nZxYzFWhP8Q3 · branch claude/issue-7644-doc-links-anchor-fragments

Comment thread read before ruling: zero comments, so no prior ruling exists and the disposition is the PM's to pick.

The gate-design call, ruled: ENFORCE, with a shrink-only baseline

The card correctly declines to choose between resolving fragments against the target document's headings and declaring the omission with a reason. Ruling: resolve them.

Declaring the omission is the weaker option and it points against this repository's own grain. ADR-0049's enforce-or-remove, and the #7070 discipline that a control is restated on success rather than deleted into a vacuum, both say that a gate which knows it cannot see something should be taught to see it, not annotated with an excuse. A documented blind spot is still a blind spot, and this one has a proven live victim: PR #7643's ### KanbanSchema → ### DeclarativeKanbanSchema rename orphaned a […](#kanbanschema) link one screen away that had to be caught by hand.

Also cover the cross-file page.md#frag form. The card explicitly did not measure it, and it is the same defect with a wider blast radius — a heading rename breaking a link from a different page is strictly harder to notice than one on the same page.

Expect a backlog, and land it as a ratchet — do not fix-everything or weaken-the-check

Turning this on will almost certainly surface existing broken anchors. Do not resolve that by loosening the check, and do not let it balloon into a repo-wide docs edit:

• Measure the violation count first, before deciding anything.
• Small (roughly ≤ 15, your judgement) → fix them all in this PR and land with the gate fully strict.
• Large → land the gate with a shrink-only baseline, the idiom this repo already uses (PR refactor(types)!: rename the declarative Kanban trio, leaving the bare names to plugin-kanban #7643's own baseline moved 36 → 33, counted not inherited). Every existing violation is a baseline row; the gate reds on any new one and on any stale row. Then file the backlog as its own card with the census attached.

Either way the gate ships on. A baseline is a ratchet, not a permanent exemption, and rows must be counted from the tree rather than copied forward.

Clause-② determination: no

scripts/ is not a governed surface in this repo, and a gate change moves no schema key, no export, and nothing about what a contract accepts or rejects. This can land through the merge queue. Make your own determination and state it in your report.

Scope fence

Stay out of the three parallel dispatches' files: #7638 (plugin-tree, plugin-kanban, plugin-calendar, packages/react/src/hooks/useNavigationOverlay.ts) and #7642 (plugin-charts/ObjectChart.tsx, plugin-form/deriveMasterDetail.ts, plugin-list/ListView.tsx, plugin-list/UserFilters.tsx, app-shell/utils/resolveActionParams.ts, app-shell/.../ObjectFieldInspector.tsx).

Do not take on #7646 (26 doc fences re-declaring published types) — that is a different gate and a separate queued card. Related but distinct: #6342 is the other measured check-doc-links gap and is about which files are scanned, not what is checked inside a scanned file. Do not merge the two.

Evidence bar

The card hands you a working two-arm control — reproduce it first as your red, then show the same subject arm going red after your change, with the control arm still behaving. A gate change whose own falsification test was never run red before the fix is not measured. State predicted vs observed in writing before each leg; report a missed prediction as a miss.

---

Generated by Claude Code