ADR-004: The standard's decisions reach client repos by reference, not by copy


Status	Accepted; mechanism extended to method docs by ADR-023; reading semantics set latest-first by ADR-025 (references resolve at `main` - the living standard)
Date	2026-07-07
Author	Łukasz Bodurka
Tags	methodology, distribution, decision-records

Context

The standard makes methodology decisions (ADR-001, ADR-002, ADR-003, ...). A client that adopts the standard follows the rules those decisions produce (specs/README, conventions). Open question: do the standard's ADRs themselves get copied into each client repo, or referenced?

Decision drivers

Deviating from a standard prescription is rare; re-aligning to a new standard version is frequent.
A client adopts the standard's decisions - it does not own them.
A deviation should be a visible, governed record, not a silent edit.
A client's decision log should be about the client's product, not cluttered with the standard's meta-decisions.

Options considered

Copy - the standard's ADRs are copied into the client repo; the client edits them to deviate. Easy to deviate (edit in place), but every standard revision conflicts with the client's edited copy (forked-config drift); clutters the client's log; blurs ownership.
Reference (link) - the standard's ADRs stay in the standard (public rationale); the client gets the rules (specs/README) with a link; to deviate, the client writes its own ADR that supersedes the standard's default. Trivial to update (nothing copied); deviation is a first-class client-owned record; zero noise.
Overlay layer over copied ADRs - rejected: noise, and it does not fix the update conflict.

Decision

The standard's methodology ADRs live in the standard and are referenced, not copied. Clients receive the rules (methodology docs, which ship to dist/) and link to the standard's ADR for the rationale. To deviate, a client writes its own ADR that supersedes the standard's default. No copies, no overlay.

Consequences

Positive: standard updates stay trivial (no forked copies to reconcile); deviations are explicit, client-owned records; the standard's public ADRs double as adoption / marketing rationale; client logs stay about the client's product.
Cost accepted: deviating takes a small ceremony (a superseding client ADR) rather than an in-place edit - fine, because deviation is rare and the ceremony is the correct, visible way to record it.

Confirmation

dist/ ships the rules (specs/README, conventions) + the ADR template - not the standard's own filled ADRs.
The standard's ADRs (ADR-001..N) exist source-only in the standard's decision-records/.
Client deviations are recorded as client ADRs that reference the standard's default.

Revisit when

A reflection engine (manifest + versioned migrations, Copier-style 3-way merge) makes updateable copies cheap enough to reconsider - though a client's edits would still conflict on update.

Builds on ADR-001 (decision-record policy). Governs how ADR-002 / ADR-003 and future methodology ADRs reach clients.