[Design Gap] governance: orphan-ADR back-reference check, ADR-search workflow step, ADR reference policy

[Coldwings]

Background

A reader of this repository navigates by "entry file + current file + whatever is linked from them" — nobody reads docs/adr/ cover to cover. An ADR that no current-law document references is therefore effectively invisible: the real ADR failure mode is not that decisions go unrecorded, it is that recorded decisions go unread. Three complementary governance additions close that, all mechanically enforceable or one-line policy:

Items

1. Orphan-ADR back-reference check (push channel; scripts/check-docs.sh check 7).
Every non-superseded ADR (proposed / accepted / rejected) must be cited by number (ADR-NNNN) from at least one current-law document (docs/*.md or AGENTS.md, excluding docs/adr/). Superseded records are exempt: they stay reachable through the Supersedes chain that check 5 already validates. Current compliance verified: ADR-0001 ← docs/design-assumptions.md, ADR-0002 ← docs/cluster.md, ADR-0003 ← docs/dart.md + docs/node.md — the check lands green today, no anchor debt.
Anchoring policy (goes into docs/adr/README.md): cite an ADR where a reader of the current rule needs its rationale. For rejected records the anchor belongs at the temptation site — the current-law entry whose rule the rejected alternative would violate (e.g. Rejected: ADR-XXXX inside the matching docs/design-assumptions.md assumption) — not in "see also" link piles.

2. ADR-search step in the AGENTS.md workflow (pull channel).
The mandatory workflow requires an ADR for contract-level changes and declares "the newest accepted ADR resolves ambiguity", but never tells the agent to look before writing. Add one line to the Documentation section: before changing an existing convention or proposing a new direction, search docs/adr/ — including rejected records, which exist precisely so rejected alternatives are not re-proposed (T5). Pull (§2) and push (§1) together cover both directions of discoverability.

3. ADR reference policy + current-law/case-law editorial rule (docs/adr/README.md).

• No live code anchors in ADR bodies. An accepted ADR's body is frozen; a live anchor must stay valid. The two rules are mutually exclusive — one would force edits to frozen text, the other a permanently red CI. Bodies must be self-contained (semantic descriptions, no code references needed to understand them). Context/Evidence may optionally link an "as of this PR" commit snapshot — the ADR and the code it discusses land in the same PR, so the writing cost is ~0 and a frozen reference is a feature for historical claims. Verification of "what did the code look like then" goes through standard archaeology (git log -S, blame, snapshot links); git log -- docs/adr/NNNN-*.md plus the merge commit already supplies the time context for free.
• Editorial rule for the two layers. Current law states what the rule is today; ADRs state why, and what was rejected. Sentences containing "used to / originally / considered / rejected" belong in ADRs. One explicit exception: a single-clause issue/ADR reference kept inline as a reader signpost (e.g. "the issue [Design Gap] fetch: cancelled coalescing waiters retain goroutines until the flight bound #53 gap: …") remains acceptable in current-law documents — it is a pointer, not a narrative.

Considered and not adopted

A "median docs-lines / code-lines per fix-PR > 1" trend as a governance-rent early warning. This repository mandates documentation as part of every change, and contract-adjacent fixes legitimately carry heavy documentation (e.g. PR #70: ~60 doc lines vs ~21 code lines, ratio ≈3:1 — by design, not by rent). The baseline ratio here is structurally high, so the metric would measure the repository's documentation culture rather than governance rent; and as a trend-only dashboard it costs maintenance nobody staffs while gating nothing. Rejected as a measurement; the underlying concern is covered by item 3's editorial rule.

Out of scope

Symbol-level evidence anchors (file::symbol, no line numbers) with drift checking in check-docs.sh — a pilot in one package, tracked as a separate issue.