Decision record · ADR
ADR-0045: Reference authority surfaces instead of restating versioned facts in agent-facing docs
Status: accepted | Date: 2026-09-03
References: ADR-0009
Context
Section titled “Context”Agent-facing documentation (the bundled agent skill, operator guides) historically carried concrete versioned facts: product versions, adapter protocol versions, and exact package pins in migration notes. These statements are a second source of truth for facts that already have authorities — the changelog, the backend support matrix version-correspondence table, the --version output stating the adapter protocol version, and the runtime protocol-mismatch error naming both versions with a remedy. Prose copies decay: a stale plugin cache told downstream agents to pin adapter SDK 0.7.0 two protocol lines behind current, and an in-tree migration note kept future-tense wording after its release shipped. The failure mode is not hypothetical; it produced real misconfiguration guidance.
The constraint is the repository’s one-authority-per-fact principle applied to prose: a fact that changes every release cannot be maintained by hand in narrative documentation. The decision driver is that agents need the mechanics of an upgrade (what a hard cut does, which pins move together, which commands re-establish authority) and a reliable pointer to current values — not the values themselves.
Decision
Section titled “Decision”Agent-facing documentation must not restate versioned facts — product versions, adapter protocol versions, and exact package pin values. Migration sections become version-free mechanics: what a protocol hard cut does (rejection rather than partial interpretation, records failing the schema-version gate), which pins move together (adapter SDK and the selected framework integration), and which commands re-establish authority (workspace lock, toolchain install). Current values are obtained from the authority surfaces: inferlab --version for the spoken protocol version, the backend support matrix front matter for the product-to-package correspondence, and the changelog for migration history.
The rule is enforced mechanically, not by convention: the public-register guard gains a lint that flags InferLab-owned version pins and protocol-version statements in plugin skill content. Version numbers belonging to third-party frameworks (CUDA, vLLM, and similar) are unaffected — the lint matches only InferLab-owned package names and protocol-line phrasing.
Consequences
Section titled “Consequences”Positive: one authority per versioned fact, so agent guidance cannot drift from the released state; the plugin cache’s age stops mattering for version guidance because the skill no longer carries values that expire; and the guard makes the rule self-sustaining rather than review-dependent.
Negative: an agent reading the skill must take one extra hop to an authority surface to learn the current pins, and the lint must be maintained as the InferLab-owned package set evolves. Historical migration narrative moves to the changelog, which is a less tutorial-shaped home.
Neutral: the backend support matrix keeps its version-correspondence table — that document is the designated authority for the correspondence and is updated as part of release preparation.
Alternatives Considered
Section titled “Alternatives Considered”Keep versioned facts out of agent-facing prose; teach version-free mechanics and point to authority surfaces, enforced by a guard lint (accepted)
Section titled “Keep versioned facts out of agent-facing prose; teach version-free mechanics and point to authority surfaces, enforced by a guard lint (accepted)”- Pros: Single authority per fact; skill content cannot silently expire; guard makes the rule self-enforcing
- Cons: Agents take one extra hop to the support matrix or –version output to learn current pins
Keep versioned migration notes in the skill and rely on release-time review to refresh them (rejected)
Section titled “Keep versioned migration notes in the skill and rely on release-time review to refresh them (rejected)”- Cons: Empirically failed twice in one release cycle: a stale plugin cache pinned two-lines-old packages and an in-tree note kept future tense after its release shipped
Inject versioned facts into the skill at plugin pack time from the owning manifests (rejected)
Section titled “Inject versioned facts into the skill at plugin pack time from the owning manifests (rejected)”- Pros: Skill text would always match the built artifact
- Cons: Turns prose into a generated projection for information agents can already query from authority surfaces; adds codegen complexity without new capability