Why
From community feedback on the README. The reviewer liked the "unit test for documentation" framing but flagged the axis we already call the central tension (proposal §8, docs/guides/authoring-hubs.md "Choosing granularity"): claim granularity.
If the anchored claim is too broad, every code change becomes noisy. If the claim is too narrow, the doc can still rot at the architecture level while the small anchor passes.
Today we only mitigate this with anchor size (advisory lint warnings: near-whole-file span, too many anchors, rule-of-thumb "smallest symbol whose logic the sentence is about"). That tunes the signal-to-noise of a single symbol-level anchor. It does not give a claim a level — so an architecture-level statement can sit green over anchors that individually didn't drift, while the invariant it asserts has quietly rotted.
What
Introduce a claim-level taxonomy so anchors can declare what kind of statement they make, and have check fail differently per level:
- Local behavior — "this function does X." Today's symbol anchor. Divergence → re-read nudge on that claim.
- Flow — "this middleware changes the auth path like this." Spans a sequence/path of symbols.
- Architecture / invariant — "the system guarantees this boundary." Anchored to a set of symbols; fires (louder, differently) when the set's composition changes, not just one body.
Kept fully deterministic: an invariant claim is still a fingerprint over a declared set of symbols — it fires when the set changes — rather than any embedding/semantic inference. The trigger stays model-free; the optional reviewer plugin (#9) can still consume the richer signal.
Machine-readable failures (agent repair target)
The reviewer also asked for failures that say why, not just "stale." check --format json already carries hub/claim/old-vs-new fingerprint + magnitude. This issue should extend that payload with the claim level and (for set/flow claims) which member changed, so an agent gets a clean repair target ("this invariant may no longer hold because this branch changed") instead of re-reading the whole doc. Pairs with #19 (draft-and-verify agent skill).
Relationship to existing issues
Open questions (research)
- Schema: a per-anchor
level: field vs. distinct anchor kinds vs. a hub-level grouping for invariants.
- For invariant claims over a set, what exactly is fingerprinted — the sorted set of member symbol hashes? member identities? both?
- How does
lint guide authors to the right level without adding ceremony that discourages authoring?
Unlock trigger
After single-hub symbol anchoring is proven in real use and we have evidence (dogfooding / the validation study) that architecture-level rot slips past today's symbol-level gate. Ship advisory-first.
Why
From community feedback on the README. The reviewer liked the "unit test for documentation" framing but flagged the axis we already call the central tension (proposal §8,
docs/guides/authoring-hubs.md"Choosing granularity"): claim granularity.Today we only mitigate this with anchor size (advisory
lintwarnings: near-whole-file span, too many anchors, rule-of-thumb "smallest symbol whose logic the sentence is about"). That tunes the signal-to-noise of a single symbol-level anchor. It does not give a claim a level — so an architecture-level statement can sit green over anchors that individually didn't drift, while the invariant it asserts has quietly rotted.What
Introduce a claim-level taxonomy so anchors can declare what kind of statement they make, and have
checkfail differently per level:Kept fully deterministic: an invariant claim is still a fingerprint over a declared set of symbols — it fires when the set changes — rather than any embedding/semantic inference. The trigger stays model-free; the optional reviewer plugin (#9) can still consume the richer signal.
Machine-readable failures (agent repair target)
The reviewer also asked for failures that say why, not just "stale."
check --format jsonalready carries hub/claim/old-vs-new fingerprint + magnitude. This issue should extend that payload with the claim level and (for set/flow claims) which member changed, so an agent gets a clean repair target ("this invariant may no longer hold because this branch changed") instead of re-reading the whole doc. Pairs with #19 (draft-and-verify agent skill).Relationship to existing issues
calls:/references:); an architecture/invariant level is the natural home for that kind of claim, so design these together.Open questions (research)
level:field vs. distinct anchor kinds vs. a hub-level grouping for invariants.lintguide authors to the right level without adding ceremony that discourages authoring?Unlock trigger
After single-hub symbol anchoring is proven in real use and we have evidence (dogfooding / the validation study) that architecture-level rot slips past today's symbol-level gate. Ship advisory-first.