[Documentation] Convention: behavioural claims in contract docs cite the test that pins them

[charles-fineman]

Context:
Identified during work on #11 (see its follow-up comment) and in the architectural review of #12.

Description:

internal/docscheck (added in #12) gates claims that are mechanically false — a link that does not resolve, a path that does not exist, an undated changelog section. It explicitly does not, and cannot, reach a different and more dangerous class: prose in a versioned contract that describes behaviour nothing verifies.

The motivating case, from #11's follow-up comment: docs/schema-threat-model.md stated that the rendered companion "anchors every entity in one namespace", and used that claim to justify the document-wide identifier uniqueness rule. Seven of thirteen collections were not anchored. The same claim was echoed in CHANGELOG.md and two comments in internal/threats/validate.go, so a reader had four mutually consistent statements of something the template did not do. A link checker would have passed all four.

Two more of the same kind: the control-character guarantee the docs promised for ~60 unchecked fields, and the escaping rules in docs/config.md.

What actually caught the anchoring claim was a reviewer reading the template. What now pins it is TestEveryDeclaredEntityIsAnchored, which enumerates the fixture's own collections so a collection added later fails the test the day the fixture declares one.

The gap: that fix exists as one good instance, not as a repository convention. Nothing makes the link from a prose claim to its verifying test discoverable to the next reviewer working under the same time pressure that let the original claim drift.

Proposal:

Add a convention to AGENTS.md, beside the "Documentation checks" section #12 introduced: every behavioural claim in a versioned contract document (docs/schema*.md, docs/config.md, docs/cli.md) cites the test that pins it — the same way CHANGELOG.md already cites issue numbers.

This is a documentation change, not a checker. Do not build a linter for it: deciding from text whether a claim is "verified" versus merely unreferenced is not mechanically decidable, and #12's whole design premise is that a check which cries wolf gets switched off.

If the convention proves its worth, a narrow follow-on check becomes plausible later — assert that a backticked TestXxx name cited in docs/*.md actually exists in the Go source, symmetric to CheckNamedPaths but for identifiers. That is speculative and should not be built ahead of the convention it would enforce.

Rationale:

Deferred from #12, which correctly scoped itself to mechanically-false claims and said so in its package comment rather than pretending to cover this. The architectural review of #12 recommended codifying the convention as a companion change.

Reference:

• [Tech Debt] CI does not check documentation, so contract docs drift silently #11 follow-up comment — the category, and the three instances
• internal/threats — TestEveryDeclaredEntityIsAnchored, the pattern to generalise
• internal/docscheck/docscheck.go — package comment, which declines this class explicitly
• AGENTS.md — "Documentation checks", where the convention belongs

Acceptance Criteria:

• AGENTS.md states the convention and shows one worked example
• The anchoring, control-character, and docs/config.md escaping claims each cite their pinning test
• A contract document with no behavioural claims is not forced to invent citations
• No linter is added for this

[charles-fineman]

Scope suggestion from the grooming pass on #15 / #20.

#20 established two testing conventions in internal/docscheck that live only as a Go comment on unreadableRepository and as prose in a PR description. Both are the same shape as this issue's work — a convention that no linter can enforce, documented in AGENTS.md and anchored to the example that pins it — so they may be worth folding in here rather than opening a separate issue:

1. A test fs.FS wrapper intercepts only the method the target branch actually calls. The worked example is unreadableRepository in internal/docscheck/docscheck_test.go, which overrides ReadDir because that is what fs.WalkDir and rootEntries call. This one is easy to violate silently: a wrapper embedding fstest.MapFS that overrides Open does not intercept fs.ReadFile, because MapFS's own promoted ReadFile satisfies fs.ReadFileFS and reaches the embedded Open. The test then passes for the wrong reason. [Testing] Cover docscheck's remaining content and parse edge-case branches #22 carries the corrected version of this note.

2. A new error-branch test is validated by mutation. Confirm the corresponding production-code change breaks that test and no other. test: cover docscheck's filesystem-error branches with an error-injecting fs.FS #20 did this for all four of its branches; without it, an error-path test easily proves only that a line executed.

Deliberately not filed as its own issue — it is a few sentences of AGENTS.md, not a workstream.