docs(archive): repair 270 broken archive links and add a repo-wide link-resolution gate (BACKLOG #1095)

[wshallwshall]

Authored by the session in worktree sweet-dhawan-57cbc8; pushed and opened by the coordinator at its
request. BACKLOG #1095, claimed to that worktree (claim.ps1 -Take 1095, verified in the registry).

This one is code-touching, unlike #279 and #280 -- it adds scripts/docs/link_check.py and
tests/test_archive_link_resolution.py, so full CI applies and the doc-drift guards actually run rather
than skipping under the noncode allowlist.

The root cause, measured rather than inferred

Archiving moves an item's text verbatim two directories deeper and nothing rewrites its relative links.
So adr/0083-....md is correct in docs/BACKLOG.md and broken the instant it lands in
docs/archive/backlog/.

The distribution is the proof: 267 of the archive's 270 broken links resolve cleanly when read from
docs/. That is the signature of the move, not of authoring. The remaining 3 are ADR slug rot
(0080/0144/0065 merged under different titles than cited; none ever existed under the cited name). All 270
repaired.

There is no archival tooling -- the author looked before writing a guard. The move is manual, which
means #1094's line about "the archival pass generates the anchor" describes a generator that was never
built, and a guard is the only thing that can catch the next occurrence.

Coordinator verification

claim	verified
tip 8a447209	yes
base 4d5f6304, not stacked (main has since moved to 4cc84e1e)	yes
3 files, +485/-208	yes -- M docs/archive/backlog/BACKLOG-CLOSED.md, A scripts/docs/link_check.py, A tests/test_archive_link_resolution.py
docs/BACKLOG.md untouched -- no contention with #1096/#278	yes -- 0 changed
disjoint from #279 and #280	yes -- 0 overlapping files each
#1095 claimed to the authoring worktree	yes -- registry shows it held by sweet-dhawan-57cbc8 on this branch

I made the gate fail on purpose, twice, rather than trusting its green

This repo's standing rule is that a green gate is evidence only once it has been shown it can go red, with
the mutation landing outside any exemption. Run against 8a447209 in a detached worktree:

1. Planted a plainly broken link inside the gate's scope (docs/archive/backlog/BACKLOG-CLOSED.md) ->
   test_archive_links_all_resolve FAILED. The gate can see its own subject.
2. Planted a broken link disguised as a withheld path (../../security/NOPE-NOT-REAL.md) -> passes.
   That is the intended exemption, not a fail-open: docs/security, reviews and marketing are a
   deliberate publishing boundary, so a link there cannot be distinguished from a withheld-but-real target.

Worth recording because the author caught a real fail-open here before commit: the first version compared
the raw href against the withheld prefixes, so ../../security/X.md matched nothing and the exemption
would have failed open the moment the gate widened.

The shipped test also plants its own failure -- it builds a throwaway repo with one broken and one good
link and asserts the checker reports exactly the broken one -- plus an anti-narrowing floor (>=1 file,
>=200 links) so it cannot pass on an empty scan.

Why the gate's scope is deliberately narrow

Repo-wide the checker still reports 341 unresolved, because #279 and #280 are unmerged. A gate that
is red on arrival gets suppressed, not fixed -- the same reasoning the ledger gate records -- so the test
asserts only docs/archive/backlog, which is now clean. Widening is a one-line change to _SUBTREE once
the queue drains; the author deliberately did not take it.

Author's verification, as reported

Archive 270 -> 0 broken across 277 links; a known-missing path pushed through the checker afterwards to
prove it still reports a miss; ruff format/check and mypy --strict clean; bandit passes with the
repo's standard nosec B603 B607 on three fixed-argv git calls; the 7 doc-drift guards run by hand
(99 passed); backlog_status_check.py OK at 365 items.

Merge ordering

Auto-merge deliberately NOT armed. This is a code PR and costs a full CI cycle, and #274 (seven PRs) is
in flight; under strict: true only one PR can be up-to-date at a time. It is queued behind the trains and
behind the two docs PRs, and will be armed when a slot is free.

---

AMENDMENT, added by the coordinator before merge. Everything above describes an earlier state of this branch and is now partly false.

Kept rather than rewritten, because the verification recorded above was true of 8a447209 and the reasoning is worth preserving. But the branch has moved, and the body would otherwise have carried a false description into the squash commit.

What actually changed

The gate went repo-wide. It was _SUBTREE = "docs/archive/backlog". It is now _GATE_SUBTREE = None, checking every tracked markdown file in the repo. That was the point of the remaining #1095 work, and it is the substantive change since the text above was written.

The test file was renamed tests/test_archive_link_resolution.py to tests/test_link_resolution.py. The old name was true at archive scope and became a false claim once the assertion went repo-wide. No references to the old name remain.

docs/BACKLOG.md IS now touched. The table above says it is not, and that claim was true when written. It contends with any other open PR appending to the same file tail.

Diff is now 6 files, +650/-216: .github/workflows/ci.yml, docs/BACKLOG.md, docs/archive/backlog/BACKLOG-CLOSED.md, docs/testing/master-test-plan/08-publishing-and-promotion.md, scripts/docs/link_check.py, tests/test_link_resolution.py.

A real defect was found in the resolver, and fixed

The original resolution condition was:

if target not in tracked and not (root / target).exists():

Tracked or present on disk. So a link to a present-but-untracked file resolved in a long-lived local checkout and would fail in CI, which clones clean. The verdict depended on which checkout it ran in. The .claude/ entry in WITHHELD was not defending against that class; it was covering the one instance that had been enumerated - a compensating control resting on a false premise, which is the defect SDS-3.7 names.

Fixed structurally: tracked_paths() returns every tracked file plus every ancestor prefix of one, and resolution consults that set alone. No filesystem fallback. The naive fix - simply deleting the fallback - was measured first and would have failed 122 legitimate directory links, because git ls-files lists files and never directories.

Demonstrated by A/B on one fixture, not argued. A markdown file linking to (a) a present-but-untracked file, (b) a directory containing a tracked file, (c) a genuinely absent file:

resolver	result
before the fix	1 unresolved - misses the present-but-untracked target
after the fix	2 unresolved - catches it; the directory link still resolves

Run independently by the coordinator against its own fixture, not against the branch's tests.

The property this gate now has, stated plainly

It checks all 5,327 links on every run, not only links in changed files. So the first broken link anywhere in the repo - an ADR retitled, a doc moved, an archive sweep - reds every open PR until it is repaired, not only the PR that caused it.

That is simultaneously the value (it cannot rot silently) and the cost (it couples the queue). Green at 5,327 of 5,327 across 347 files at time of merge, so it lands clean. Approved by the owner as built, with that consequence stated in advance.

Environment-independence is structural, not enumerated: tracked-set-only resolution with derived directory prefixes. .claude/ remains in WITHHELD as a deliberate publishing boundary alongside docs/security, docs/reviews, docs/marketing and docs/releases - retained as policy, not as protection, since the resolver no longer needs it to stay environment-independent. Owner ruled on that specifically.

Where it runs

ci.yml gates pytest on code == 'true' || event_name == 'push', so on a docs-only PR - exactly the PRs most likely to break a relative link - the repo-wide assertion would not have run at all, and would have fired on the push to main after the merge. The gate is therefore also registered in the ungated doc-guard list, in both the printed manifest and the pytest invocation, so "print what you scanned" survives. Verified with that step's exact command line.

Tests: 11 collected from 7 functions, all passing. Two of them pin the resolver pair directly - test_resolution_ignores_the_filesystem (present-on-disk but untracked must FAIL) and test_directory_links_resolve (a directory containing a tracked file must PASS).

Provenance

All commits authored by the session in worktree sweet-dhawan-57cbc8, unmodified. Pushed by the coordinator session under an explicit owner grant covering external repo actions. Design approved by the owner as built.