docs: repair every ADR link from the half that still identifies it, and close four bug-ledger rows

[lusoris]

Summary

Three things found by diffing the tracked record against master. None of them was
red in CI, which is the point: each is a record or an assertion that quietly stopped
being true.

1. 98 ADR links under docs/ resolved to no file

An ADR link carries the decision's identity twice — as a number and as a slug —
and either half can rot alone. mkdocs build --strict catches none of it: it
validates the nav and page rendering, not the target of an inline relative link.

	Half that rotted	Repair
63	slug — the ADR was renamed	from the number
35	number — a collision sweep renumbered the file	from the slug, and the [ADR-NNNN] text

Root cause of the second group, read out of the history rather than guessed:
af227b026 (PR #310) and fb14bc332 (PR #752) were ADR collision sweeps for
duplicate numbers. The second renamed 50 files, moving
0241-vmaf-tiny-v3-mlp-medium.md to 0389-vmaf-tiny-v3-mlp-medium.md and 27 others
into the 0388–0415 band. Each moved the file and its index fragment and left every
inbound citation on the old number.

Slug-before-number is the whole design, and I got it wrong first. Repairing all
98 from the number was tried, and an independent two-pass review of the result
confirmed 39 sites where that silently repointed a citation at an unrelated
decision — [ADR-0241] in a tiny-AI evaluation digest became a link to the HIP PSNR
kernel-template ADR. Those links resolve, so they read as authoritative and
nothing complains afterwards: strictly worse than the dead link they replaced. That
review is also what recovered the two sweep commits, which turned a plausible
heuristic into a verified one — the slug is the half those sweeps preserved.

One citation resolves by neither half: ADR-0846 is a number the tree skips entirely
(0845 → 0848) and no ADR carries the cpp23-wave8 slug either. It is now plain text
rather than a link to a 404.

The gate is scripts/ci/check-adr-links.py, wired as the check-adr-links
pre-commit hook on any docs/ change. It reports rather than rewrites unless asked,
refuses to guess when neither half resolves or the halves disagree, and carries 16
cases including one that proves slug beats number when both could resolve.

Out of scope on purpose: a citation whose number and slug agree and are both the
wrong decision. That needs review, not a parser — T-STALE-ADR-CITATIONS-2026-09-16.

2. Three MCP tests asserted the wrong error depending on the invocation directory

test_vmaf_score_rejects_invalid_core_params passed ref/dis as the relative path
model/vmaf_v0.6.1.json, and _validate_path resolves a relative path against the
process CWD. From the repository root that lands on an allowlisted root and the three
cases raise the invalid pixfmt / invalid bitdepth / invalid backend they assert.
Run from mcp-server/vmaf-mcp/ they resolve outside the allowlist and all three fail
on not under an allowlisted root instead — the test silently stops asserting what
it names. CI runs from the root, so this was never red.

3. Two ledger rows disagreed with master

• T-PRAETOR-README-GOVERNANCE-BLOCK-MISSING-2026-09-22 sat under Open bugs
  although the branch that fixed it merged. Verified on master: the managed block is
  in README.md and praetorctl audit reaches [PASS] README governance block verified against the recorded baseline.
• T-CI-DOCS-JOB-TIMEOUT-2026-09-19 claimed the docs ceiling is 20 minutes; master
  carries 25. Corrected, with the measurement that forced the second raise.
• T-CI-MYPY-PYTHON-VERSION-STALE-2026-09-19 closed — PR fix: drive whole tree toward zero warnings and HISS #1518 raised the pin to
  3.14. Checked that the residual is a different defect: mypy still stops early,
  now on module resolution, which T-CI-MYPY-JOB-CHECKS-NO-FILES-2026-09-21 tracks.
• T-SPDX-INVALID-IDENTIFIER-2026-09-16 re-measured: residual 92 → 66, and the
  informal BSD+Patent occurrence it names is gone.

Type

• docs — bug-ledger reconciliation and ADR link repair
• test — new gate coverage and a test-fixture correctness fix

Reproducer

# the link drift, and the gate that now catches it
python3 scripts/ci/check-adr-links.py            # OK; exits 1 on any broken link
python3 scripts/ci/tests/test_check_adr_links.py # 16 cases

# the MCP defect, before the fix: 3 failed from the package directory ...
cd mcp-server/vmaf-mcp && PYTHONPATH=src python3 -m pytest \
  tests/test_score_extras_adr1117.py::test_vmaf_score_rejects_invalid_core_params -q
# ... and 3 passed from the repository root, same tests, same code.
# After: passes from both. Whole package suite from the package directory:
#   before: 3 failed, 374 passed, 40 skipped
#   after:  374 passed, 43 skipped

bash scripts/ci/check-state-md-rows.sh

ADR-0108 deep-dive deliverables

• Research digest — no digest needed: the finding is one measurement (98
  broken links, split 63/35 by which half resolves) and one history lookup
  (PR fix(go): propagate ctx through subprocess and DB boundaries (S1 sweep) #310, PR docs(nav): add 10 orphaned pages to mkdocs.yml nav #752), both recorded in the checker's docstring and in
  docs/development/adr-workflow.md where a maintainer will actually meet them.
• Decision matrix — in the commit body and the checker docstring: repair by
  number, by slug, or slug-first. The first was tried and measured wrong for 35
  of 98 links; the third is what shipped, because the collision sweeps preserved
  the slug.
• AGENTS.md invariant note — no rebase-sensitive invariants: no public
  surface, no upstream-mirrored file.
• Reproducer / smoke-test command — above.
• CHANGELOG fragment — changelog.d/fixed/adr-link-slug-drift.md,
  changelog.d/fixed/state-ledger-reconcile-20260923.md,
  changelog.d/fixed/mcp-test-relative-fixture-cwd.md.
• Rebase note — no rebase impact: docs, one CI script and one test fixture.

Bug-status hygiene

• docs/state.md updated — two rows corrected, three closed, one filed and
  closed in the same change per ADR-0165.

Netflix golden-data gate

• No python/test/ assertion touched.