ADR 017 Revision Specific Document References - joeroberts/release-radar GitHub Wiki

  • ID: ADR-017
  • Status: Accepted
  • Date: 2026-09-09
  • Date meaning: Original dated decision/source section; extraction recorded 2026-10-02.
  • Implementation: No implementation information was recorded in the source status; tickets own progress.
  • Approval qualification: Recorded owner-approved Phase 5 scope; slice-specific exclusions and later dependencies remain as stated.

Context

Ticket requirement/decision references identify exact managed source revisions without making copied prose or source changes delivery authority.

Authority and retained identity

The owner-approved revision-specific requirement/decision links remain distinct from authoritative repository prose and generic evidence. Stable ticket-link identities and retained versions bind project/ticket, repository/artifact, supplied source-local identity where available, and complete safely read content digest. Native browsing remains read-only; typed app-owned commands create, revise and retire links atomically with audit and replay receipts. Accepted ticket link sets are immutable. Source changes alter resolution facts, not accepted history.

New records must survive placement, archive/restore, removal history and full backup without reconnecting historical registrations on re-add. Future complete portable packages must represent all link/version/retirement facts and required source documents without transferring capabilities. This decision does not change v1, implement export/import, or implement later proposals/successors/lifecycle. The Phase 5B brief contains the bounded delivery contract and verification.

Source content and resolution

This decision applies owner-authorized Phase 5 scope. The managed-documentation contract's original approval statements retain their historical context. Ticket requirement/decision links reuse the accepted managed-root/catalog and bounded no-follow reader boundaries but do not change evidence locator uniqueness. New or revised links require an active controlling source in the exact accepted repository/catalog and a revalidated complete-source SHA-256 digest. Catalog digest identifies metadata, not mutable content revision or prose approval. No mutable-document checksum is added to the catalog merely to support link identity.

Retain link versions, source-local IDs and observed path/authority metadata. Resolve current state by artifact identity: changed, moved, retired, superseded and unavailable are separate facts. Missing files do not prove catalog retirement. Never relink automatically or present current bytes as an unavailable historical revision. Link retirement retains history and does not require the source to remain readable. New/revised links still require full managed authorization; no operation implicitly binds or accepts a catalog. See the Phase 5B brief.