ID

R596

Status

Backlog

Bucket

cleanup

Priority

3

Theme

docs

Created

2026-08-05

Updated

2026-08-05

The published site carries 9 cross-file xref: links whose target page does not exist, so they render as ordinary links and 404 on click. Seven come from roadmap/changelog.adoc (lines 653, 657, 661 twice, 739, 787, 789), which names plan pages that were deleted when their items shipped (load-bearing-annotations-r78-classifier-checks, method-name-binding-enclosing-directive-context, fkjoin-alias-dead-storage, lsp-diagnostic-redundant-splitquery-on-record, id-reference-input-field, plan-generated-fetcher-quality, plan-single-cardinality-split-query); two come from roadmap/plans/service-short-classname-resolution.adoc:21,66 naming computed-field-with-reference.adoc. Nothing reports them: Asciidoctor never resolves a cross-document target, it only rewrites the extension, so a missing page is as silent at build time as a missing anchor. Census taken over docs/target/staging by resolving each xref: target path against the staged tree.

Two halves to decide between (or combine) at Spec time: repointing or delinking the dead references, and whether an unresolvable target should fail the build the way a dangling anchor does. The anchor gate deliberately reports rather than fails on unresolvable targets, because roadmap prose quotes xref syntax as examples and failing on those would break the build; a path gate needs an answer to that same problem, most likely by resolving only references the md-to-adoc renderer emitted rather than ones an author quoted. The changelog case also raises whether a shipped item’s plan page should keep a stable published URL at all, which may be the cheaper fix.