Architecture Change Control, ADR and Supersession

1. The problem: a decision that lives only in chat is not auditable

Architecture choices often begin in a meeting or chat, move into code, and later lose their rationale. The more damaging case is a previously accepted decision that is silently edited after the implementation changes. Reviewers can no longer tell what the original decision was, what changed, or why.

This lesson produces Architecture Decision Supersession Record v1. It keeps the decision separate from implementation evidence, preserves accepted history, records supersession explicitly, and leaves architecture/runtime drift visible until it is reconciled.

2. What an ADR records

An Architecture Decision Record (ADR) captures a significant architecture choice. AWS Prescriptive Guidance describes an ADR as recording the decision, its context, and its consequences; a collection of ADRs forms a decision log. The value is not only remembering what was selected, but preserving why it was selected and what trade-offs came with it.

An ADR is not a complete architecture specification. It also does not replace implementation, tests, deployment evidence, or runtime verification. Treat it as a decision record, not proof that the decision is currently implemented.

3. Lifecycle: Proposed, Accepted, Rejected, and Superseded

An ADR normally enters review in a Proposed state. The team can keep it proposed for rework, reject it, or accept it. AWS guidance treats an ADR as immutable after acceptance. If new insight requires a different decision, the change should be represented by a new ADR and a new review process.

When the new ADR is accepted, it supersedes the old one. Superseded does not mean deleted. The old ADR remains in the decision log so the historical chain stays traceable.

4. Minimum reviewable content

A useful minimum is Context, Decision, and Consequences. AWS guidance also uses status and a changelog to make the record reviewable, and the context should capture the alternatives considered. In this lesson, alternatives and trade-offs are explicit evidence fields.

A note that says only “use Kafka” or “choose PostgreSQL” is too weak for change control. It does not show the problem, the competing options, the reason for the choice, or the consequences that were accepted.

5. Separate architecturally significant choices from trivial ones

Not every code change needs an ADR. Choices that affect structure, non-functional requirements, dependencies, published interfaces, or important construction techniques are stronger ADR candidates. A local variable name or a refactor with no material effect on boundaries or system behavior usually is not.

The boundary is not fully mechanical. Human judgment remains necessary: scope, coupling, operational behavior, consequences, and reversal cost all contribute to whether the decision is architecturally significant.

6. Decision-log ownership

A single ADR becomes more useful when it belongs to a central decision log. Each record should make its ID, status, owner/date, and relationship to prior decisions clear. A change history should also show who made an allowed update and when.

Ownership does not mean the owner is infallible. It means responsibility for review, communication, and maintenance is explicit and a decision change follows a traceable path.

7. Supersession changes the decision without erasing the past

Assume ADR-002 was accepted with option A. New constraints now support option B. The anti-pattern is opening ADR-002 and replacing A with B. That erases the basis on which the earlier implementation may have been built.

The better pattern is to create ADR-003, capture the new context and alternatives, review it, and—if accepted—record supersedes: ADR-002. ADR-002 becomes Superseded and both records remain available.

8. Documentation state is not implementation state

A decision log can be perfectly consistent while the runtime still implements the old decision. Accepting a new ADR therefore does not prove conformance. Change control needs separate implementation evidence: an appropriate code/config snapshot, manifest, test, or architecture check for the bounded scenario.

Linking the ADR chain to implementation evidence is a MAKNOW instructional extension in this lesson. It prevents “accepted decision” from being treated as equivalent to “observed implementation.”

9. Keep architecture drift OPEN

If the active ADR requires an asynchronous interaction but the implementation manifest still shows the old synchronous path, do not rewrite the ADR to match runtime. Record the discrepancy as drift. The record should state the evidence, current conformance, review trigger, and reconciliation action.

If evidence is incomplete, keep the result UNKNOWN. Missing evidence is not permission to invent a passing state.

10. Failure probe: a silently edited accepted ADR

One fixture changes the checksum/content of an ADR that was already Accepted. Passing tests or having a sensible new decision does not repair the historical problem. The preserved accepted record must first be restored or recovered, and the new choice must be expressed through a new ADR.

If accepted history is rewritten, the causal chain between earlier design, implementation, and later change can no longer be reconstructed reliably.

11. Failure probe: two accepted ADRs with no supersedes link

Another fixture looks cleaner: the old and new ADRs both exist and both say Accepted, but the new record does not identify which decision it supersedes. The result is two apparently current, conflicting decisions.

Repair the relationship explicitly and re-establish a valid review state. A newer timestamp must not silently become the rule for selecting the active decision.

12. Build the record row by row

For each decision, record ADR ID, Status, Context, Alternatives, Decision, Consequences, Supersedes, Implementation Evidence, Conformance, Drift, Review Trigger, and Reconciliation Action. Every conclusion should connect to observed evidence or a declared authority.

Keep three kinds of statement separate: direct evidence, inference/policy choice, and unknown. That separation lets a reviewer see which parts were observed and which parts depend on judgment.

13. Reconciliation action should match the mismatch

If the only defect is a missing supersedes link, the repair belongs in decision history. If the decision chain is correct but code does not match the active decision, the action belongs in implementation or in a newly reviewed decision. If evidence is missing, collect evidence before forcing a conclusion.

The goal is not a green table. The goal is a defensible current state and a traceable path to reconciliation.

14. Lab: reconstruct the decision chain from synthetic evidence

The local exercise includes eight synthetic cases: a valid baseline, accepted-history tampering, a missing supersedes link, implementation drift, a trivial choice, a proposal not yet accepted, a rejected decision, and a materially different transfer scenario. run_checks.py validates fixture structure only; it does not contain the answer.

In starter.py, return eight dimensions for each case: decision status, historical integrity, option set, supersession link, active decision, implementation conformance, drift register, and significance judgment. Anything not proven by the evidence must remain OPEN or UNKNOWN.

15. Transfer: rebuild a different decision chain independently

The transfer changes the architectural concern, alternatives, status history, and implementation mismatch. Do not copy identifiers or the first-case outcome. Reassess significance, rebuild context and options, derive the active decision from status and supersession, and compare implementation evidence against that active decision.

The result is defensible when accepted history remains traceable, supersession is explicit, documentation and implementation are assessed separately, and no drift or unknown is hidden by rewriting history.