Skip to content

ADR-002: Adopt MORPHISM as the Governance Model

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

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

Context

The monorepo had grown to include governance docs, CI workflows, git hooks, SSOT atoms, and policy scripts — but lacked a single, coherent model explaining why these pieces exist and what invariants they collectively enforce.

Without a unifying model: - Governance docs drifted from scripts (two truths) - Scope of each rule was implicit ("just conventions") - Enforcement was inconsistent — some rules blocked merge, others were advisory - New contributors had no principled basis for deciding where a new rule belonged

The core problem: entropy increases silently and is expensive to reverse.

Decision

Adopt MORPHISM as the governance model for this repository. Normative requirements are defined in docs/governance/morphism-kernel.md (the Kernel). This ADR records the rationale and tradeoffs.

The model rests on three structural elements:

  1. One Truth Per Domain — every governance assertion has exactly one canonical source (SSOT atom). Derived artifacts reference it; they do not restate it.
  2. Read–Verify–Execute protocol — all governance-touching transitions follow an explicit three-phase sequence. Verification is not optional.
  3. Entropy monotonicity — system ambiguity must not increase across releases without explicit authorization, measured by maturity_score.py (Kernel Invariant I-5).

The "category theory / entropy functor" framing in the theory doc (docs/architecture/morphism-theory.md) is non-normative — it is an explanatory tool, not an enforcement document. The Kernel contains the enforceable invariants.

Consequences

Positive

  • Single principled basis for deciding "where does this rule live?"
  • Enforcement is mechanical (CI gates) not cultural (hoping people remember)
  • Drift between canonical sources and consumers is detected automatically
  • New contributors have a clear amendment process (not just "ask someone")
  • Maturity score provides a ratchetable, auditable governance health metric

Negative

  • Adds overhead for governance changes: must update Kernel + ADR + re-extract atoms
  • The normative language (must/shall) in the Kernel is strict; exceptions require documented rationale
  • Teams accustomed to informal governance may experience friction initially

Neutral

  • The framework is internally consistent but does not prescribe application architecture
  • Existing governance docs (AGENTS.md, SSOT.md, GUIDELINES.md) are compatible; this ADR does not supersede them — it provides the unifying rationale

Governance Fields

SSOT Impact: docs/governance/morphism-kernel.md becomes a new canonical governance atom. scripts/ssot_extract.py should extract it; scripts/ssot_verify.py will verify its hash.

Enforcement: CI integration-gate job runs verify_pipeline.py + maturity_score.py. Kernel invariants I-1 through I-7 each have mapped enforcement scripts.

Audit: Run python3 scripts/maturity_score.py for a 0–100 score across 10 governance dimensions. Run python3 scripts/ssot_verify.py to confirm all atoms are current.

Alternatives Considered

Alternative 1: Wiki-first (docs only, no CI enforcement)

  • Pros: Low friction for contributors; easy to update
  • Cons: No enforcement means drift accumulates silently; "governance" becomes aspirational
  • Why rejected: The original state of this repo. Demonstrated that drift increases faster than manual correction.

Alternative 2: Process-only (checklists, PR templates)

  • Pros: No tooling overhead
  • Cons: Depends on human discipline; scales poorly; silently bypassed under deadline pressure
  • Why rejected: Checklists without gate enforcement are decoration.

Alternative 3: External governance platform (Backstage, Cortex)

  • Pros: Richer dashboards, team portals
  • Cons: Additional infrastructure; not version-controlled; enforceability depends on the external platform
  • Why rejected: Over-engineered for current scale; stdlib scripts in-repo provide the same guarantees at zero infra cost.

Alternative 4: Pure convention (naming rules, no tooling)

  • Pros: Minimal overhead
  • Cons: Same failure mode as wiki-first; conventions drift faster than conventions documents
  • Why rejected: Naming conventions without enforcement are semantics, not governance.

References