ADR-0015: ADR Governance — Single Source of Truth

Accepted Cross-Project

Date: 2026-03-09 Amended: 2026-03-27

Context

Architecture Decision Records were maintained in three locations:

1. War room /adrs/ — Full technical ADRs, canonical source
2. Presentation site /presentation/decisions/ — Ally-readable VitePress pages, condensed format
3. Territory repos (e.g., kendo/adrs/) — Copies for local access

This triple-copy approach caused drift:

• ADR-0001 (Audit Logging): War room updated to Accepted with classification matrix reference; territory copy still at Proposed with no matrix reference.
• ADR-0008 (Multi-Tenancy): Territory copy promoted to Accepted with updated file paths; war room copy still at Proposed.
• ADR-0008 amendment: Allies drafted a tenancy refactor plan (singleton → request-scoped) that would amend ADR-0008. The war room had no visibility into this planned change.

Additionally, the Kendo allies authored four ADRs locally (0009-0012 in territory numbering) that documented cross-project patterns (Action architecture, DTO flow, frontend structure) — patterns the war room enforces but had never formally recorded.

The drift was inevitable: no sync protocol existed, and two independent teams maintaining separate copies of the same decisions will always diverge.

Amendment Context (2026-03-27)

The original decision solved drift by centralizing all ADR content at adrs.script.nl. This eliminated divergence but introduced an accessibility problem: territory agents (Claude instances working inside a territory) and allies reading CLAUDE.md cannot reliably access the website mid-execution. The territory knows which ADRs apply but not what they say.

In practice, kendo's backend CLAUDE.md had already evolved distilled operational rules for ADR-0001, 0003, 0006, and 0009 — informal projections that proved the pattern works. Meanwhile, brick-inventory operates as the ADR development laboratory with full ADR content in docs/adr/, where patterns are explored and proven before graduating to cross-project governance.

The amendment formalizes both patterns: distilled projections for consumer territories and an explicit laboratory exemption for brick-inventory.

Decision

One Format, One Location, One URL

All ADRs — regardless of origin — live as VitePress pages in the presentation site, deployed at adrs.script.nl. This site is the single source of truth for all architectural decisions and serves human consumers (allies, Commander, negotiation contexts).

Distilled Projections

Each territory's CLAUDE.md receives a distilled projection of every cross-project ADR that applies to it. A projection is not a copy of the ADR — it is a condensed set of operational rules extracted from the decision.

What a Projection Contains

• The enforceable rules — "you must" and "you must not" statements
• A one-liner on why — enough context to understand the rule's purpose
• Enforcement mechanism — how the rule is caught if violated (architecture test, CI gate, etc.)

What a Projection Does Not Contain

• Options considered or rejection rationale
• Full deliberation context
• Implementation state tracking (that stays on the canonical ADR page)
• Territory-specific implementation details that already live in the CLAUDE.md naturally

Projection Format

Each territory CLAUDE.md that receives projections has a dedicated ## War Room ADR Projections section. This section is owned by the war room — territories do not edit it. The dedicated section makes drift detection straightforward: the Adjutant can diff the section against canonical ADRs without parsing the entire CLAUDE.md.

Each projection entry follows this structure:

### ADR-NNNN: {Title}

- **Rule:** {Enforceable "you must" / "you must not" statement}
- **Why:** {One-liner explaining the rule's purpose}
- **Enforcement:** {How violations are caught — architecture test, CI gate, etc.}

Multiple rules from the same ADR are listed as separate bullet points under the same heading. Territory-specific implementation details (e.g., which entities have audit logging in kendo) remain in the territory's own doctrine sections — the projection only carries the cross-project rules.

Laboratory Exemption: Brick-Inventory

Brick-inventory (BIO) is the ADR development laboratory. It operates under different rules:

• Full ADR content — BIO maintains complete ADR content in docs/adr/ for patterns under development
• Always editable — The Commander develops, tweaks, and battle-tests ADR content in BIO, even after graduation to cross-project status
• Source end of the pipeline — Changes proven in BIO flow up to the war room for cross-project formalization; projections flow down to other territories
• No projection lockdown — BIO does not receive read-only projections. Its local ADRs are the living development versions

This exemption exists because BIO is the Commander's controlled environment for exploring architectural patterns before they affect ally territories.

Sovereign ADR Numbering

BIO maintains its own independent ADR number sequence (currently 0001–0009 in docs/adr/) for territory-local decisions (session auth, routing conventions, controller architecture, etc.). These numbers are completely independent from the war room sequence — BIO ADR-0002 and war room ADR-0002 are unrelated decisions. When a BIO-local pattern graduates to cross-project status, it is assigned a war room number and the BIO original remains as the development version.

ADR Lifecycle

BIO (full ADR, development)
  ↓ proven
War Room (canonical full ADR, adrs.script.nl)
  ↓ projections pushed
Other Territories (distilled rules in CLAUDE.md)

Projection Maintenance

Push on Amend

When a cross-project ADR is amended at the war room level, the General immediately pushes updated projections to all affected territory CLAUDE.md files as part of the amendment process. Allies see the updated rules without delay.

Audit for Drift

Projection integrity is audited as part of enforcement queue #8 (CLAUDE.md drift). The Adjutant/Muster inspection detects:

• Stale projections — territory CLAUDE.md rules that no longer match the canonical ADR
• Unauthorized amendments — ally edits to projection content that weren't routed through the war room
• Missing projections — cross-project ADRs that apply to a territory but have no projection in its CLAUDE.md

When drift is detected, the war room resolves it — not the territory. Allies propose changes through the amendment protocol; they do not edit projections directly.

What Lives Where

Content	Location	Maintained By
Full ADRs (canonical, human-readable)	presentation/decisions/ → adrs.script.nl	War room
ADR development versions	BIO docs/adr/	Commander
Distilled projections (agent-readable)	Territory CLAUDE.md files	General (push on amend)
Internal war room ADRs (spy/soldier/squad)	War room CLAUDE.md + agent prompts	War room
ADR quick-reference registry	War room CLAUDE.md (Active ADRs section)	War room

Access Model

Consumer	Access Method	Content Level
War room (Commander + General)	Direct file access in presentation/decisions/	Full ADR
Allies (developers)	Browse adrs.script.nl	Full ADR
Territory Claude instances	Territory CLAUDE.md (distilled projections)	Operational rules only
BIO Claude instances	Local docs/adr/ + CLAUDE.md	Full ADR

Numbering

The war room owns the ADR number sequence. Territory-authored ADRs are renumbered when absorbed:

War Room #	Decision	Origin
0001–0010	Original war room ADRs	War room
0011	Action Class Architecture	Territory (was IT-0011)
0012	FormRequest → DTO Flow	Territory (was IT-0012)
0013	Adapter-Store Pattern	Territory (was IT-0009)
0014	Domain-Driven Frontend Structure	Territory (was IT-0010)
0015+	Future ADRs	War room assigns number

Amendment Protocol

When allies need to amend an ADR:

1. Allies draft the proposed changes (plan document, PR description, or direct communication)
2. The war room reviews, challenges, and integrates the amendment into the canonical page
3. The General pushes updated projections to all affected territory CLAUDE.md files
4. One amendment cycle updates all consumers — canonical page, projections, and quick-reference

What Was Removed

• /adrs/ directory — Eliminated. Presentation pages are now canonical.
• Territory ADR copies — Eliminated for all territories except BIO (laboratory exemption). Replaced with distilled projections in territory CLAUDE.md.

Implementation State Tracking

Each ADR carries an Implementation section with per-territory state. This separates the decision lifecycle (Proposed → Accepted → Superseded) from execution progress.

States

State	Meaning
Not Started	Decision accepted, no code yet
In Progress	Active campaign executing
Partial	Some phases or entities done, more to come
Complete	Fully implemented for this territory
Evergreen	Pattern is established and applied as the codebase evolves — no fixed finish line

Territories where a decision is not in scope are omitted from the table (not listed as "N/A").

Where It Lives

Location	What's Tracked
Presentation page (## Implementation)	Per-territory state table — canonical source
CLAUDE.md (Active ADRs section)	One-line implementation summary — quick-reference
Muster inspection	Drift detection — flags mismatches between code state and declared implementation

Maintenance

Implementation state is updated by the General when campaigns complete. The /muster inspection detects drift — if the declared state doesn't match the actual code state, it surfaces as a finding. This is passive governance: the state is updated when work happens, not on a schedule.

The distinction between Complete and Evergreen matters: Complete ADRs are done — the muster checks that the code matches. Evergreen ADRs are living patterns — the muster checks that the pattern is still being followed (via architecture tests, conventions, or enforcement mechanisms).

Options Considered

Original Decision (2026-03-09)

Option	Verdict	Reason
War room canonical, territory gets copies	Rejected	Two copies = guaranteed drift. Territory copies go stale (ADR-0001) or get ahead (ADR-0008) without sync protocol.
Territory canonical, war room gets copies	Rejected	Loses editorial control. Allies could amend decisions without war room review.
Split ownership by origin	Rejected	Still requires sync discipline for cross-references. Three different owners = three different update cadences.
Single source in presentation site, deployed at adrs.script.nl	Accepted	One copy, one format, one URL. No sync needed. All consumers access the same version.

Amendment Options (2026-03-27)

Option	Verdict	Reason
Keep pure centralization (status quo)	Rejected	Territory agents can't access adrs.script.nl reliably. ADR content is inaccessible where it's needed most — at development time.
Full ADR copies back in all territories	Rejected	Reintroduces the exact drift problem the original decision solved.
Projections woven into native CLAUDE.md doctrine	Rejected	Elegant but unauditable. Different territories would format the same ADR's rules differently, requiring semantic comparison for drift detection. Waiting for problems.
Distilled projections in dedicated CLAUDE.md section + BIO laboratory exemption	Accepted	Dedicated section is auditable by string diff, clearly war-room-owned, and unambiguous about control boundaries. BIO keeps full content as the development environment.
Web-fetch from adrs.script.nl at agent startup	Rejected	Adds latency, fragile dependency on site availability, and still requires the agent to parse a full ADR page to extract operational rules. The projection is more useful than the full ADR at development time.

Consequences

Positive

• Zero drift on canonical ADRs — one source of truth at adrs.script.nl, unchanged
• Territory agents can read operational rules directly from CLAUDE.md without external dependencies
• Allies reading CLAUDE.md get actionable rules without leaving the codebase
• BIO retains full development freedom as the ADR laboratory
• Projection format (rules + one-liner why + enforcement) is more useful at development time than a full ADR
• Push-on-amend + audit-for-drift closes both proactive and reactive maintenance gaps
• Formalizes a pattern kendo was already following informally

Negative

• Projections are a new maintenance artifact — the General must update them on every cross-project ADR amendment
• Two representations of the same decision exist (full ADR + projection) — semantic drift is possible even if textual drift is caught
• BIO's laboratory exemption creates an asymmetry that must be documented and understood

Risks

• Projection staleness — Mitigated by push-on-amend protocol and enforcement queue #8 audit. The Adjutant/Muster inspection catches drift.
• Ally edits to projections — Mitigated by audit-for-drift. Unauthorized changes are detected and resolved by the war room, not accepted silently.
• BIO-to-war-room graduation lag — A pattern proven in BIO could sit unformalized for weeks. Mitigated by the General flagging graduation candidates during campaign reviews.
• Site downtime — Mitigated by Cloudflare Pages (high availability, global CDN). Territory agents no longer depend on site availability for operational rules.

Enforcement

What	Mechanism	Scope
Projection currency	Enforcement queue #8 (CLAUDE.md drift) — Adjutant/Muster audit	All territories with projections
Unauthorized projection edits	Adjutant/Muster diff against canonical ADR	All territories except BIO
Missing projections	Adjutant/Muster cross-reference of applicable ADRs vs territory CLAUDE.md	All territories except BIO
Push-on-amend compliance	General's amendment checklist (Propagation Checklist in template)	War room process

Resolved Questions

Should BIO receive projections for graduated ADRs?

Resolved 2026-03-27. No. BIO keeps full ADR content always — even for graduated ADRs. The Commander needs the freedom to tweak, amend, and battle-test ADR content in a controlled environment. Switching BIO to projections after graduation would create a hybrid format (some full, some projected) for no operational benefit. Clean rule: BIO has full content, everyone else gets projections.

Should projections be pushed proactively or audited reactively?

Resolved 2026-03-27. Both. Push-on-amend ensures allies see updated rules immediately. Audit-for-drift catches unauthorized ally amendments — the original source of drift that motivated ADR-0015 in the first place. Two mechanisms, two failure modes covered.

Where do projections live within the CLAUDE.md?

Resolved 2026-03-27. In a dedicated ## War Room ADR Projections section owned by the war room. Initially considered weaving projections into native territory doctrine (as kendo had done informally), but this makes drift detection require semantic comparison rather than string diffing. A dedicated section is auditable, clearly owned, and unambiguous about what the war room controls vs what the territory controls.

Implementation

Territory	State	Notes
kendo	Complete	## War Room ADR Projections section with 7 ADRs (0002, 0009, 0011, 0012, 0014, 0016, 0017). PR #694.
brick-inventory	Complete	Laboratory exemption. Full ADR content in docs/adr/ with sovereign numbering. War-room ADR cross-references in orchestrator CLAUDE.md.
the-laboratory	Complete	## War Room ADR Projections section with 5 ADRs (0002, 0009, 0011, 0012, 0016). Committed directly to main (Commander's personal domain).
ublgenie	Partial	## War Room ADR Projections section with 5 ADRs (0002, 0009, 0011, 0012, 0016). PR #23. ADR-0014 (frontend) deferred.
entreezuil	Complete	## War Room ADR Projections section with 6 ADRs (0001, 0002, 0009, 0011, 0012, 0016). PR #19, PR #21.
fs-packages	Partial	## War Room ADR Projections section with 2 ADRs (0013, 0015). Backend-centric ADRs (0001, 0002, 0008, 0009, 0011, 0012, 0016, 0019, 0020) are N/A — frontend service package monorepo.
emmie	Not Started	territories/emmie/CLAUDE.md exists but has no ## War Room ADR Projections section yet. Onboarded 2026-04-24.
daymate	Not Started	Orchestrator has no CLAUDE.md (only README.md); vassal-state CLAUDE.md files (daymate/api/, daymate/app/) lack projections. Onboarded recently.