Research-1242: Generated ADR metadata audit¶

At master 7bafbb8cc, read-only changelog and ADR-index concatenation checks passed. Tag and navigation checks failed. A retained regeneration from the same base plus one sibling ADR changed all 445 tracked tag outputs: 256 changes only removed the old lint header and 189 changed membership too. There were 145 new tag pages. Navigation also repeated ADR-1110 and ADR-1112 and omitted later sources. Make and CI referenced neither check command. These counts describe the baseline audit; the final refresh includes the new hook and metadata decisions.

Generator repair¶

The tag renderer now owns its Markdown layout directives and escapes ordinary underscores, HTML-like text, and table delimiters in titles. It retains authored code spans, including the intentional trailing space after ADR-0913's ^## pattern. Only pages carrying such patterns declare the MD038 exception. Accepted ADR text and original tag meanings remain unchanged. Repeated normalized tags are deduplicated, unsafe output names are rejected, and generated bytes are staged before replacement.

The navigation writer now validates exactly one ordered sentinel pair before editing and uses a same-directory atomic replacement. Tests verify read-only drift detection, removed/extra pages, unsafe tags, duplicate membership, code-span preservation, and missing/reversed/repeated markers.

Mutable index reference provenance¶

The source set contained ADR-1123 but no corresponding fragment; its existing title/status/tags supplied the added row. Four mutable fragment files contained five stale references. The targets were resolved from current source headings and topic content, including number changes:

Fragment ADR reference labels change with their verified target IDs. Accepted source ADR bodies remain untouched. A new index contract detects missing fragments, wrong primary links, dangling ADR references, and duplicate or missing order entries before concatenation.

Wiring and validation¶

make docs-fragments-write renders changelog, ADR index, tags, then nav. The matching check target runs in local pre-commit, required Docs CI, and Pages builds. A Pages deployment now requires the build's docs output so code-only impact skips cannot deploy a missing artifact.

Reproduce with python3 scripts/docs/tests/test_generators.py, make docs-fragments-check, and mkdocs build --strict using docs/requirements.txt. The full render uses a temporary virtualenv and site directory; installed versions and build diagnostics are retained with the audit evidence. MkDocs INFO categories remain governed by the existing archival/source-link policy, not silently promoted or disabled.

Follow-up: developer and usage guide references¶

The strict-build INFO inventory contained 27 missing linked targets in docs/development/ and docs/usage/. Canonical headings and source files resolved 26 to existing targets: renamed ADR slugs, corrected IDs for Rust FFI (0706), local dev-MCP (0451), cloud-native server work (0701), SYCL DWT deferral (0406), AdaptiveCpp (0407), and percentile pooling (1188), backend overview pages, core/include/meson.build, and docker/Dockerfile.production. The remaining reference was the local .workingdir2/BACKLOG.md notebook; the guide retains its historical T7-3 identifier as plain text and names the live workflow as its configuration source. It now accurately describes that job's GPU_COVERAGE_ENABLED opt-in and draft guard. No historical research claim or scaffold is removed.

A local path scan confirms zero missing inline-link targets in those 12 repaired guide pages. Source-tree links remain useful on GitHub and continue to appear as INFO in MkDocs when they lie outside docs_dir. Historical ADR and research link debt is reported separately from this bounded guide repair.