Skip to content

DIRAC-ADR-0004: Repo Authority and ADR Boundary

Status

Accepted

Date

2026-06-20

Context

The dirac-* workspace has grown to 7 repositories, each with its own ADR layer and documentation surface. Without explicit authority rules, agents and developers cannot determine whether a topic should be decided in dirac-framework or in a repo-local ADR.

Key triggers for this ADR:

  • dirac-odoo now has 8 repo-local ADRs (0001–0008), several of which make design decisions that could be mistaken for framework-level ADRs
  • dirac-fed has substantial BFF contract design without formal ADRs yet
  • The previous boundary ADR (DIRAC-ADR-0002) defined platform ownership but not ADR authority ordering

Decision

Rule 1: Framework ADRs define cross-repo decisions

dirac-framework/docs/adr/canonical/ is the sole location for:

  • cross-repo naming and namespace conventions
  • platform-wide governance patterns (messaging, federation, security)
  • repo lifecycle and standardization rules
  • repo boundary definitions

Rule 2: Repo-local ADRs are authoritative for their domain

Each dirac-* repo may maintain its own ADR set for decisions that:

  • affect only that repo's implementation semantics
  • narrow or interpret a framework ADR within the repo's domain
  • record domain-specific design progression (e.g., V0→V1→V2→V3 evolution)

Rule 3: Conflict resolution

When framework and repo-local ADRs disagree:

  • framework ADRs win on cross-repo concerns (naming, messaging, boundaries)
  • repo-local ADRs win on domain-specific implementation (Odoo semantics, ABS behavior, FED contract design)
  • repo-local ADRs that narrow framework guidance are valid; repo-local ADRs that contradict framework guidance must be escalated

Rule 4: Framework-doc surface must reference repo-local ADRs

The framework platform-architecture pages should summarize and link to repo-local ADRs so the overview remains useful without duplicating content.

Consequences

Benefits

  • Clear authority ordering prevents duplicate or conflicting ADRs
  • Repo owners retain autonomy over domain-specific decisions
  • Framework overview stays lean while pointing to rich repo-local detail

Trade-Offs

  • Requires discipline to keep framework pages in sync with repo-local ADRs
  • Agents must check both framework and repo-local ADRs before making decisions