020-Link vocabulary: add contrasts and mechanism; declare directional asymmetry

Type: ../types/adr.md · Status: accepted

Status: accepted Date: 2026-04-19 Extends: ADR-009 Depends on: ADR-019 Amended by: ADR-058 (source-as-subject identifiers), ADR-060 (rationale becomes rests-on)

Scope. This ADR's additions land in the theoretical-register default template (recorded in the catalogue at link-vocabulary.md) and are adopted by collections whose COLLECTION.md includes them in its authorised sets. Cross-register labels (rests-on, evidenced-by, is-evidence-for, procedure, operates-on, defined-in) are a separate concern handled by the catalogue and selected per destination in each COLLECTION.md; this ADR does not speak to them.

Context

ADR 009 adopted a five-label vocabulary (extends, grounds/foundation, contradicts, enables, exemplifies/example) and committed to slow, evidence-driven expansion.

An audit of every footer annotation across kb/**/*.md (3420 matches, 236 distinct labels) found that most off-vocabulary labels fold into existing ADR 009 aliases (the folds are listed under the decision). Two candidates survive with genuine semantic daylight.

contrasts occupies a slot no ADR 009 label covers

Authors use contrasts (~150 occurrences) to name a difference between peers without claiming either is wrong: "ACE performs bullet-level operations with helpful/harmful counters on an addressable playbook; Dynamic Cheatsheet performs whole-document rewrite on an unaddressable blob." Neither is incorrect — they sit on different points of a named axis. contradicts is too strong (implies conflict forcing resolution); exemplifies and extends are directional when the relationship is peer-level.

The agent-memory-systems/ reviews rely on contrasts to map the landscape of similar-but-different systems (124 of the occurrences have a descriptive source). Folding it into contradicts would mislead readers arriving expecting resolution and getting parallel design choices instead.

mechanism is distinct from grounds

grounds answers "on what premises?" — the target is the theoretical or evidential base. mechanism answers "by what operation?" — the target is the operational principle or machinery that makes the source's claim work.

Register usage reinforces the split. grounds is a cross-register upward move: ~71% of its occurrences terminate in a theoretical note, with sources in every register. mechanism stays within the theoretical and workshop layers, with zero uses whose source is descriptive, source, or managed.

Decision-cost argument from linking-theory.md: a reader following grounds wants to verify the claim's justification; a reader following mechanism wants to understand how the claim operates. Different reader needs, different follow/skip choices.

ADR 009 has an implicit directional rule worth stating

The audit also surfaced that ADR 009's vocabulary is directionally asymmetric by design: most labels point upstream from source to target, one target typically has many downstream users linking up, and the inverse view is derived from authored links rather than represented by a required paired edge. Leaving this implicit risks future label proposals drifting toward "every forward needs a paired backward" — which doesn't match the fan-out structure and would impose maintenance load that doesn't scale.

Decision

Additions

Add two labels to the theoretical-register default template. Collections adopting that template (currently kb/notes/) will surface these for authoring; collections with their own declared grammar pick them up only if their COLLECTION.md authors opt in.

  • contrasts — names a difference between peers on a specified axis, without claiming either is wrong. Self-dual.
  • mechanism — target is the operational principle or machinery that makes the source's claim work. Upstream-pointing (target is more operationally fundamental than source).

Directional asymmetry principle

The vocabulary splits into two classes by directional shape. New label proposals must fit one of these shapes.

Asymmetric labels (forward-authored, backward-derived; 1:many fan-out): extends, grounds, enables, exemplifies, mechanism. Per-label semantics are in the catalogue.

Each label points upstream (toward more fundamental, more general, or more foundational content). Each upstream note typically accumulates many incoming links, so it should not be required to maintain forward links back to all of them. The authored edge from the downstream side is sufficient to derive the upstream note's inbound view (inbound and outbound links serve asymmetric reader needs). An upstream note may still author a reciprocal link when that direction independently helps its readers.

Symmetric labels (self-dual; either end may author): contradicts, contrasts.

These are pair-level relationships with low fan-out. Both ends may legitimately mark them from their own vantage without creating clutter.

Upstream notes may link downstream selectively — to index a canonical application, to pin a key example, to flag a known tension. This is editorial curation, not inverse-duty. It does not scale with fan-out and is a conscious per-note decision.

Label folds (theoretical defaults)

The audit surfaced off-vocabulary labels that fold cleanly into existing theoretical-default labels or aliases. These are recorded so authors drifting toward them are redirected:

  • sharpens, refines, clarifies → extends (covers "builds on, adds a dimension to, refines")
  • motivates → grounds
  • applies, instance, application → exemplifies
  • complements, consequence, sibling → extends or see-also for pure navigation
  • tension, challenges → contradicts

Not folded: rationale (now rests-on) and justification are kept distinct from grounds: cross-register design/rule dependency answers "why does this design/rule exist?", while grounds is intra-theoretical premise verification.

Consequences

Easier

  • Review landscape mapping. The descriptive register can now name peer differences accurately without overloading contradicts or stretching extends.
  • Operational-vs-epistemic distinction. Readers following mechanism and readers following grounds get different kinds of support, matching different decision needs.
  • Future label decisions. The directional-asymmetry principle gives a test: does the proposed label fit an asymmetric (upstream-pointing) or symmetric (pair-level) shape? If neither, it's probably a synonym or a prose hedge.

Harder

  • Vocabulary is now seven, not five. Authoring cost is slightly higher; picking the right label requires slightly more discrimination.
  • contrasts vs contradicts boundary. Authors must distinguish "differs on an axis" from "conflicts with". Test: if the reader would follow the link expecting to resolve a disagreement, the label is contradicts; if expecting to understand the neighbour's shape, it is contrasts.
  • mechanism vs grounds boundary. Both are upstream-pointing. Test: if the reader would follow to verify the claim's justification, the label is grounds; if to understand how it works operationally, it is mechanism.

Not changing

  • ADR 009's decisions for the theoretical default remain in force; this ADR extends rather than supersedes.
  • Inbound views remain derived on demand from authored links; upstream notes are not required to carry forward links back to their users.

Update discipline

The vocabulary is operative through the link-vocabulary.md catalogue, which COLLECTION.md authors consult, and through each COLLECTION.md's outbound-linking section, which note writers and the connect skill read. Any future change to ADR 009 or ADR 020 that touches the theoretical default must re-sync the catalogue and any COLLECTION.md files whose authorised labels reflect the change, in the same edit.

Relevant Notes: