Rubric: annotation anchors

Written by a person. Last read by a person on 2026-09-05, 3 days ago. Its facts were checked by the eval suite on 2026-09-07.

Enforced by check_annotations, and by the build, which fails first.

The claim

Guidance lives beside the example rather than inside it, and stays attached to the exact text it explains.

Observable evidence

• For each note: id, anchor, note, provenance, audience.
• How many steps of the example contain the anchor text: zero, one, or more than one.
• Whether the annotated example exists at all.

The pass bar

Every anchor resolves to exactly one step, and every note carries all five fields.

Zero matches and two matches both fail, for different reasons. Zero means an edit removed the text a note explains, so the note is now about nothing. Two means the note would attach to whichever step happened to come first, which is a silent decision about what it is about.

Why this layer exists

Docs-as-code forces guidance inline, which caps its density at whatever an example can carry before it stops being copyable, and gives every reader the same comments. Separating the layers lifts both limits. The cost is a second file that can drift, and the anchor rule is how that cost is paid: the drift fails the build rather than failing the reader.

Ambiguous cases

An anchor that still resolves but no longer means the same thing. The check catches text that has disappeared or become ambiguous. It cannot catch text that survived an edit which changed what the surrounding code does — max_attempts still matching after the loop around it was rewritten.

This is the same class as a glossary entry pointing at a renamed constant, and string matching cannot close it. Each note records the date it was written against, so a note older than its example is visibly stale rather than quietly wrong. That mitigates; it does not solve, and pinning a content hash of the span is recorded in the research register rather than assumed to be the fix.

A note addressed to nobody. Fails. Addressing is the reason the layer exists; an unaddressed note is a comment that has been moved to a different file for no gain.

Whether the note is any good. Not checkable. This rubric confirms a note is attached to the right text and is addressed to someone. Whether it says something worth reading is review.