docs: repair the ADR-to-ADR citations the link gate could not see

[lusoris]

Summary

#1522 shipped a gate for adr/NNNN-slug.md links and reported the tree clean.
It was clean only of the spelling it matched. An ADR cites a sibling as
(0530-slug.md), and one under docs/adr/by-tag/ as (../0530-slug.md) —
neither carries the adr/ segment the pattern required, so 237 broken
sibling links were invisible to it. Making the segment optional finds them;
admitting the bare form only for files under docs/adr/ keeps docs/research/,
which names its digests NNNN-slug.md too, from being read as broken ADR
citations.

The more important finding is what repairing them by number would have done.
Inside docs/adr/ the population inverts: 196 of the 237 carry a slug that
names no ADR at all, leaving only the number — and for 56 of those the number
had been reallocated by the collision sweeps. Repairing from the number would
have pointed [ADR-0033](0033-hip-applicability.md), cited in ADR-0315 as the
precedent for fork-side GPU ports, at 0033-codeql-config-moved-to-github.md,
and [ADR-0009](0009-batch-a-upstream-port-strategy.md), cited there as the
fork's demand-pull pattern, at the MCP server tool surface. That is the failure
#1522 exists to prevent, arriving from the other direction: it resolves, reads
as authoritative, and is worse than the dead link it replaced.

So a by-number repair now has to be corroborated by the target's own title and
abstract, and the corroboration weighs the words that identify a decision over
the words a whole family shares. The measurement that forces that weighting:
[ADR-0138 — PSNR-HVS SIMD bit-exactness] cited 0138-psnr-hvs-simd-bitexact,
and 0138-iqa-convolve-avx2-bitexact-double does say "simd" and "bitexact" — it
is a sibling in that family, not the same decision, and says nothing about
PSNR-HVS. Counting shared words admits it; ranking hvs (3 ADRs) above simd
does not.

A third rule resolves a reordered slug from the slug half:
0335-sycl-adaptivecpp-second-toolchain is
0407-adaptivecpp-second-sycl-toolchain with two words swapped, and 0335 now
belongs to an ADR about hardware capability priors.

What was repaired

181 mechanically — 35 by exact slug, 2 by reordered slug, 144 by
corroborated number.

56 by hand, split:

• 26 repaired against evidence. Some from the target's own text (ADR-0164
  discusses the EOTF and cbrt LUT the citation names; ADR-0269 carries the
  barrier pattern; ADR-0161 is the only ADR that discusses the SSIMULACRA 2 IIR
  blur). Some from git log: 0371-cambi-sycl-port.md is now
  0415-cambi-sycl-port.md and 0199-tiny-ai-netflix-training-corpus.md is now
  0242-…, so those citations named the right decision before it moved.
• 30 de-linked, because the cited ADR was never written under any number and
  the number now belongs to something else. The visible text is kept exactly, so
  the rendered prose is unchanged and only the hyperlink goes. Two were left
  de-linked rather than guessed: ADR-0509 in ADR-0542, because that file already
  cites ADR-0514 on the next line so the author meant a second ADR; and the
  PSNR-HVS citation in ADR-0918, because 0159 (AVX2) and 0160 (NEON) both carry
  the FP_CONTRACT pragma and the citation does not say which.

Type

• docs — documentation only

Checklist

• Commits follow Conventional Commits (the commit-msg hook enforces this).
• make format && make lint is green locally.
• Unit tests pass: meson test -C build. — n/a for a docs + scripts/ci/ change; the checker's own suite is green (24 tests).
• If I touched any SIMD/GPU code path, I ran /cross-backend-diff and the worst ULP is ≤ 2. — n/a, no code path touched.
• If I touched a feature extractor with SIMD/GPU twins, I either updated every twin or listed the gap under "Known follow-ups" below. — n/a.
• If I added a new .c / .cpp / .cu / .h / .hpp, it has the appropriate license header (see CONTRIBUTING.md). — n/a, no new source file.
• If this is a breaking change, the commit message uses ! or BREAKING CHANGE: and the migration path is documented below. — not breaking.
• If this PR adds an ADR, the ADR row lives in docs/adr/_index_fragments/<NNNN-slug>.md. — no ADR added; this implements the gate ADR-0221 and ADR-0386 already require.

Bug-status hygiene (ADR-0165)

• docs/state.md updated in this PR with a row —
  T-DOCS-ADR-SIBLING-LINK-DRIFT-2026-09-23, closed, recording the measurement,
  the fifteen ADR numbers cited for decisions nobody wrote, and what the gate
  still does not check.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: the measurement is reproducible
  from the checker itself (the command below prints the same counts) and is
  recorded in the module docstring and the docs/state.md row.
• Decision matrix — no alternatives: only-one-way fix. The gate either
  sees the sibling spelling or it does not; the one real choice — whether to
  auto-apply an uncorroborated by-number repair — is settled by the 56 measured
  mislinks and written up in the docstring.
• AGENTS.md invariant note — no rebase-sensitive invariants: this
  touches docs/ prose and one scripts/ci/ checker, neither upstream-mirrored.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/adr-sibling-link-repair.md.
• Rebase note — no rebase impact: fork-local documentation and a fork-local CI script; no upstream-mirrored file is touched.

Reproducer

# The gate, on this branch:
python3 scripts/ci/check-adr-links.py
#   -> check-adr-links: OK (1017 ADR numbers, every ADR link under docs resolves)

# The same gate on master still reports clean, because it cannot see the form:
git stash && git checkout master -- scripts/ci/check-adr-links.py
python3 scripts/ci/check-adr-links.py   # -> OK, on a tree with 237 broken links

# Positive, negative and boundary coverage (HISS-15), 16 tests -> 24:
python3 -m pytest scripts/ci/tests/test_check_adr_links.py -q

# Docs gates that read the same tree:
bash scripts/docs/concat-adr-index.sh --check
bash scripts/docs/generate-adr-nav.sh --check
bash scripts/docs/generate-adr-by-tag.sh --check
npx markdownlint-cli2 $(git diff --name-only origin/master -- 'docs/**/*.md')

Known follow-ups

• Fifteen ADR numbers are cited for decisions nobody wrote — ADR-0009,
  0026, 0033, 0040, 0122, 0125, 0127, 0287, 0358, 0379, 0460, 0568, 0864, 0867,
  0979. Several were cited as "in-flight" and never landed; their numbers now
  belong to other decisions. Their citations are plain text here. Writing them,
  or recording them as abandoned, is a separate job.
• A citation where both halves agree and both name the wrong decision is
  still unchecked by any gate. That needs review, not a parser — tracked as
  T-STALE-ADR-CITATIONS-2026-09-16.