Skip to content

ADR-005: SSOT Atoms with registry.json

NON-NORMATIVE. This document records rationale and tradeoffs. Enforceable invariants are in docs/governance/morphism-kernel.md.

Status: Accepted Date: 2026-02-19 Author: @alawein Ticket: N/A (foundational decision)

Context

Governance content was duplicated across AGENTS.md, SSOT.md, GUIDELINES.md, and various docs. When one copy was updated, others drifted silently. We needed a mechanism to enforce "one truth per domain" (Kernel Invariant I-1).

Decision

Adopt an SSOT atom architecture:

  1. Atoms are small, self-contained Markdown files in docs/ssot/atoms/, each owning exactly one governance assertion (e.g., governance-authority.md, monorepo-scope.md).
  2. Registry at docs/ssot/registry.json tracks every atom with fields: id, title, file, sha256, owners, consumers.
  3. Extraction (scripts/ssot_extract.py) pulls atoms from canonical sources into the atoms directory.
  4. Verification (scripts/ssot_verify.py) checks that each atom's SHA-256 hash matches the registry, detecting drift.
  5. Consumer documents (AGENTS.md, SSOT.md, etc.) embed atoms via <!-- SSOT:atom-id:begin --> / <!-- SSOT:atom-id:end --> markers. They reference, not restate.

Consequences

Positive

  • Every governance fact has exactly one canonical source
  • Drift is detected mechanically via hash comparison
  • CI can block merges that introduce SSOT inconsistencies
  • Adding a new governance domain requires only a new atom + registry entry

Negative

  • Editing governance content requires understanding the atom/consumer indirection
  • Registry must be kept in sync (additional step after atom changes)

Neutral

  • Atoms are plain Markdown; no special tooling needed to read them
  • The sha256 field acts as a content-addressed version identifier

Alternatives Considered

Alternative 1: Single large governance document

  • Pros: Everything in one place; easy to search
  • Cons: Merge conflicts, no granular ownership, no drift detection
  • Why rejected: Does not scale; violated I-1 in practice

Alternative 2: Database-backed SSOT

  • Pros: Rich querying, access control
  • Cons: Not version-controlled, requires infrastructure
  • Why rejected: Over-engineered; file-based atoms in Git provide audit trail for free

References