Appendix G: Architecture Decision Record (ADR) Standard

An ADR records a significant decision, its evidence, trade-offs and accountable approval. It does not turn an agent’s recommendation into organizational authority. This is the full reference; agents use the compact s4u-adr operating procedure. The selected project profile identifies who may accept architecture, security and business decisions.

1. ADR Template

Use the following fields, with unknowns made explicit. A filled template is not proof that the decision was reviewed.

# ADR-NNNN: Descriptive Title

**Created**: YYYY-MM-DD
**Accepted**: Pending
**Status**: Proposed
**Accountable decider(s)**: Role and identified authorized person; pending if unknown
**Contributors**: Human and AI analysis/review contributors, with relevant run references
**Approval reference**: Pending; bind to exact accepted revision when authorized
**Supersedes**: None, or ADR-NNNN

## Context
The problem, approved business constraints, system boundaries and evidence.
Distinguish observed facts, estimates, assumptions and unresolved questions.

## Decision context
- Latency:
- Dependency surface:
- Debuggability:
- Reversibility:
- Blast radius:
- Cost (compute/token spend):
- Alternative considered:

## Decision
A specific proposed change, scope, compatibility constraints and acceptance conditions.

## Consequences
### Positive
Expected benefits and how they will be measured.
### Negative
Known costs, risks and uncertainty; do not invent a trade-off to fill this heading.
### Neutral
Other affected systems and necessary operational changes.

## Alternatives Considered
Credible options, including the status quo when viable, and evidence-based reasons.
If only one feasible option is known, explain the constraints and search limits.

## Verification and follow-up
Independent acceptance evidence, owner, unresolved questions and review trigger.

Template Usage Notes

• Title states the decision, not merely the problem.
• Created records drafting; Accepted remains pending until actual authorization. Record retroactive documentation honestly.
• Accountable decider(s) identifies authorized human responsibility. AI belongs under Contributors, with useful model/tool/version or run references. No EU AI Act article is assumed to require an AI agent to be a decider.
• Approval reference identifies the exact approved content revision and approval event. An approval of a different draft does not transfer automatically.
• Context should stand alone without reproducing private transcripts or hidden model reasoning. Link authorized evidence and concise rationales.
• Consequences distinguishes observed outcomes from expectations. “No downside identified in the assessed scope” is more honest than a fabricated disadvantage.
• Decision context uses the seven axes in methodology §2.7. Estimates need a basis; deferred measurement needs a reason and follow-up.

2. File Location and Naming Convention

Store the register in docs/adr/, indexed by docs/adr/README.md.

Element	Reference convention
Filename	ADR-NNNN-kebab-case.md
Identity	Issued once; never reused
Allocation	Serialized register/reservation, including concurrent proposals
Legacy convention	Existing NNNN-slug.md files may remain; the integrity checker recognizes both

The next number on main is not a safe allocation when proposals are concurrent. Reserve an identity through the project’s chosen mechanism. Without a reservation mechanism, keep a temporary draft identity and reconcile before acceptance. A sequential number records identity, not temporal ordering or proof of approval.

3. Status Lifecycle

Status Definitions

Status	Meaning
Proposed	Under discussion; not binding
Accepted	Authorized for its stated scope and exact revision
Deprecated	No longer applicable; reason and authority recorded
Superseded by ADR-NNNN	Replaced by an accepted, cross-linked decision

Proposed vs. Accepted

A single commit may contain both drafting and acceptance only when the authorized person actually approved that exact content. PoC speed, a merge, agent agreement and passing tests do not create missing authority. Acceptance of architecture is not automatically authorization to change business policy or release to production.

Deprecated vs. Superseded

Use Deprecated when no replacement decision exists. Use Superseded when another accepted ADR replaces the decision. A withdrawn proposal retains its issued identity and reason; do not recycle its number.

4. Supersession Tracking Pattern

Step 1: Update the Original ADR

Preserve its accepted body. Change the status to Superseded by ADR-NNNN after the replacement is accepted; record transition provenance without rewriting the original rationale.

Step 2: Add a Supersedes Field to the New ADR

The replacement contains Supersedes: ADR-NNNN, the accountable decider, acceptance reference and exact replacement scope. A draft replacement does not itself deactivate an accepted decision.

Step 3: Reference the Original in Context

State why the decision changed: new constraints, new evidence, an earlier factual error or a mistaken choice. Do not manufacture a story in which the original was necessarily sound.

Worked Example: ADR-0004 to ADR-0013

An illustrative project initially accepts synchronous delivery to a partner API. Observed outage behaviour later shows that retrying requests can duplicate an external effect. A replacement ADR introduces durable dispatch and receiver-side deduplication. It records the failure evidence, compatibility plan and acceptance tests. Both ADRs link to each other after the authorized replacement is accepted.

The numbers and scenario are illustrative, not evidence of a deployed implementation.

5. When to Write an ADR

Write one for a non-obvious decision whose effects or trade-offs future maintainers need to understand.

ADR-Worthy Decisions

Decision class	Typical concern
Technology and architecture	Frameworks, data model, dependency or execution model
Integration	API/event contracts, delivery semantics, ownership boundaries
Security and privacy	Authorization, tenant isolation, retention, model-data routing
AI-assisted delivery	Agent authority, evaluation oracle, approval and release boundaries
Testing and operations	Test strategy, migration compatibility, rollback or recovery
Deferral	Explicitly postponed capability, scope limits and review trigger

A “config-only” change can alter authorization or isolation. A “bug fix” can change an externally relied-upon contract. Assess effects and the accepted design, not the label or patch size. A PoC using real or sensitive data still requires its applicable protections.

The "Future Engineer" Test

Would a maintainer ask why this approach was chosen, or unknowingly remove an important constraint? Record or reference the decision. Routine implementation of an existing pattern normally needs the relevant ADR link, not another record.

6. When NOT to Write an ADR

Mechanical refactoring, routine tuning within approved bounds, and changes that simply implement an accepted pattern can reference existing decisions. Confirm that they do not change permissions, business meaning, public contracts, data semantics or recovery behaviour. If they do, use the appropriate decision and approval process regardless of the number of code changes.

7. ADR Quality Checklist

• Context, scope and evidence are understandable without private conversation history.
• Facts, estimates and unknowns are distinguishable; no unsupported marketing claims.
• Decision and acceptance conditions are actionable.
• Credible alternatives and known consequences are recorded without invented facts.
• Exact revision and accountable approval match the stated status.
• Relevant business/security authority exists; architecture approval does not substitute for it.
• Supersession links are bidirectional; errata do not conceal changed decisions.
• The register check ran against the stated, nonempty subject; its limits are reported.

8. ADR Maintenance

Living Documents, Immutable History

Preserve accepted decision bodies. To change a decision, accept a superseding ADR. To correct a factual error without changing the decision, append or link a clearly marked erratum with author, evidence, date and approval; retain the original wording and version. Errata must not be used to change accepted meaning.

There is no fixed number of Git commits per ADR. Draft iterations, acceptance metadata, status changes and explicit corrections are legitimate history.

Periodic Review

At meaningful milestones, examine pending proposals, accepted decisions affected by new evidence, and undocumented decisions. Resolve them with the responsible role. Age alone does not prove a decision or blocker is obsolete. Retroactive records distinguish the actual decision date from the documentation date; use Unknown where evidence is absent.

ADR Index in CLAUDE.md

Keep the complete index in docs/adr/README.md. Project instructions contain a pointer and only the currently relevant decision references, not a duplicate, ever-growing table. Index freshness is distinct from decision correctness.

9. Example ADR Inventory

A synthetic register illustrates complementary decision classes:

ADR	Decision	Status
0001	Define business approval and execution boundaries	Accepted
0004	Synchronous partner delivery	Superseded by ADR-0013
0013	Durable partner dispatch with deduplication	Accepted
0014	Evaluate a new model route	Proposed

Patterns Visible in the Inventory

Status, authority and scope matter more than the number of records. A proposal is not an implemented capability; a frequent ADR cadence is not a productivity or quality metric.

10. Worked Example: A Complete ADR

This example is intentionally Proposed, with synthetic evidence identifiers. It demonstrates record shape, not a validated architecture or production receipt.

# ADR-0014: Pin model routing to an approved project profile

**Created**: YYYY-MM-DD
**Accepted**: Pending
**Status**: Proposed
**Accountable decider(s)**: Architecture and information-security owners; pending
**Contributors**: BA, platform engineer, AI analysis run (synthetic example)
**Approval reference**: Pending

## Context
The project allows more than one model provider, but each project has distinct
data-handling and capability permissions. Provider selection must not widen
the approved data audience. A model name alone is not evidence of private
networking, retention settings or permitted processing.

## Decision context
- Latency: Not measured; compare approved routes before selection.
- Dependency surface: One replaceable routing adapter plus provider clients.
- Debuggability: Record route/profile revision and redacted error receipts.
- Reversibility: New requests can return to the previous compatible profile;
  in-flight runs retain their pinned version or use a reviewed migration.
- Blast radius: All model-bound calls in the selected project.
- Cost: Measure representative tasks; budget limits remain explicit.
- Alternative considered: Per-agent credentials; rejected provisionally because
  policy changes and audit coverage would be distributed.

## Decision
Propose a versioned routing profile that binds allowed models, data classes,
capabilities and operational limits. Reject requests outside that profile.
Do not treat this record as permission to contact a new provider.

## Consequences
### Positive
A shared policy location can make review and replacement easier.
### Negative
The router becomes a critical dependency. Incorrect policy can block legitimate
work or allow unintended processing; both outcomes require tests.
### Neutral
Provider-specific controls still require separate verification.

## Alternatives Considered
- Per-agent configuration: greater flexibility but more policy distribution.
- One fixed provider: simpler initial operation, less portability.

## Verification and follow-up
Security owner verifies the actual processing route and applicable agreement.
Platform engineer tests allowed/denied data classes, revoked profiles and
in-flight version handling. BA checks that user-visible limitations are clear.
No tests or provider controls are claimed verified by this example.

11. Anti-Patterns

The Retroactive Justification

Do not invent alternatives or earlier approval. A retroactive record states what evidence exists and what is unknown.

The Empty Consequences

Do not produce an all-positive sales narrative. Equally, do not invent a negative consequence to satisfy a template. Record assessed scope, known trade-offs and remaining uncertainty.

The Novel ADR

Reference the established pattern for another ordinary instance. Create a new decision when effects or constraints change.

The Abandoned Proposal

Keep an owner and review trigger. Withdraw with a reason or obtain actual approval; time passing does not make a proposal accepted.

12. Automated ADR Enforcement

The shipped scripts/check-adr-register.sh checks register integrity: nonempty discovery, unique numeric identities, exact index entries and both directions of supersession. It returns nonzero for detected defects or unassessed inputs. It does not establish decision merit, authorization, cycle freedom or implementation conformance.

The ADR Gate Hook

No ADR-presence Stop hook is shipped by this reference. The earlier inline example has been retired: it examined only a working-tree diff against HEAD, suppressed errors, mishandled some paths and treated any ADR modification as relevant. Its exit-0 output did not ensure the model or user was asked a question.

Key Design Decisions

If an adopter implements a reminder, specify the exact change range, expected file set, missing-input behaviour and actual delivery contract for that host. Treat a reminder as feedback, not an unbypassable control. Hook reference.

What This Catches

Mechanism	Evidence it can provide	What it cannot prove
Register integrity check	Assessed files, duplicate/index/link defects	Valid decisions or authorized acceptance
Optional tested path reminder	A matched change needs consideration	That an ADR is needed, relevant or approved
Reviewed decision record	Rationale and exact accountable acceptance	That implementation follows it
Independent implementation tests/review	Scoped conformance evidence	Universal correctness or release authority

Complementary Practice: ADR Index in CLAUDE.md

Use a small pointer to the canonical register. When mirroring ADRs into live documentation, retain identity and source revision, admit only publication-authorized material and validate the rendered bundle. Byte freshness is not semantic or privacy approval.