ADR-0015: ADR Governance — Single Source of Truth

Accepted Cross-Project

Date: 2026-03-09

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., issue-tracker/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 Issue Tracker 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.

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.

What Lives Where

Content	Location	Maintained By
All ADRs (territory-specific + cross-project)	presentation/decisions/	War room
Internal war room ADRs (spy/soldier/squad system)	War room CLAUDE.md + agent prompts	War room
ADR quick-reference registry	War room CLAUDE.md (Active ADRs section)	War room
Territory CLAUDE.md ADR references	Link to adrs.script.nl	Territory maintainers

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. One update, one location — all consumers see the change immediately via the deployed site

Access Model

Consumer	Access Method
War room (Commander + General)	Direct file access in presentation/decisions/
Allies (developers)	Browse adrs.script.nl
Territory Claude instances	Web fetch from adrs.script.nl
Territory CLAUDE.md	Links to specific decision pages

What Was Removed

• /adrs/ directory — Eliminated. Presentation pages are now canonical.
• Territory ADR copies — Eliminated. Replaced with URL references in territory CLAUDE.md.

Options Considered

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.

Consequences

Positive

• Zero drift — one source of truth, no copies to sync
• Allies get a polished, browsable site instead of raw markdown files
• Territory Claude instances can web-fetch current ADR content
• Cross-project ADRs are naturally accessible to all territories
• War room retains editorial control over all architectural decisions
• Reduced maintenance — one page to update per ADR, not three

Negative

• Deployment dependency — the site must stay up for territory Claude instances to access ADRs
• All ADR updates require a war room commit + deploy cycle
• Allies cannot self-service amend ADRs — must go through the war room

Risks

• Site downtime — Mitigated by Cloudflare Pages (high availability, global CDN). Territory Claude instances can fall back to cached knowledge.
• Bottleneck on war room — If allies need rapid ADR amendments, the war room approval step could slow them down. Mitigated by treating amendments as high-priority when allies flag them.