ADR 009 ADR Lifecycle and Integrity - joeroberts/release-radar GitHub Wiki

  • ID: ADR-009
  • Status: Accepted
  • Date: 2026-10-02
  • Date meaning: Recorded proposal date; not an acceptance date.
  • Implementation: Not implemented; this document proposes the contract.
  • Approval qualification: Acceptance is separate from drafting, publication, and implementation authorization.

Context

Agents need to find the applicable architectural decision and detect unexplained changes without treating a matching hash as proof of approval.

Decision

Keep ADRs in the Wiki, with a repository-owned skill and executable validator governing their creation, reading and maintenance.

  • Use four decision statuses: Proposed, Accepted, Rejected, Superseded. Preserve approval qualifications in the document. Track implementation progress in GitHub issues.
  • Freeze accepted decision bodies. Never add amendments or edit them to accommodate new work. A changed decision requires a new, self-contained ADR and explicit acceptance.
  • Maintain a development ADR catalog with file identities, fixed accepted baselines and explicit scope applicability. Generate the two-column ADR / Decision status index from it. Do not add historical links between ADRs.
  • Read and validate one pinned Wiki snapshot, including catalog membership, content identity, accepted-body preservation and applicable scope. Unexplained changes or unresolved authority block dependent work; never refresh hashes merely to make checks pass.
  • Treat verified documents as information, not execution authority. Only a separately approved, bounded exception may permit reliance on an eligible failed check; it never makes that check pass.

The supporting contract defines the exact metadata, catalog schema, byte comparisons, validation results, migration procedure and test requirements. It remains proposed alongside this ADR; moving those details does not authorize changing them or weakening this decision.

Rationale

A catalog makes retrieval and integrity checks repeatable. A fixed accepted baseline prevents edits to both a document and its current hash from concealing a changed decision. Explicit applicability avoids choosing authority by document date, numbering or implementation state.

Boundaries and consequences

This governs RR development documentation. It does not change the RR application's catalogs, harness, permissions or hooks.

Acceptance and execution authorization remain distinct. Git proves content identity, not human intent. Skills cannot prevent every bypass or make a check and a later operation atomic.

The authorized cleanup will establish normalized baselines once, preserving approval evidence in the owning ticket. Future architectural changes use new records. Existing instructions remain operative until the authorized skill and AGENTS.md cutover.