Skip to content

ADR-004: Model Governance as Category Theory

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 rules in software projects are typically expressed as prose checklists or ad-hoc scripts. This leads to ambiguity: rules overlap, contradict, or silently drift. We needed a formal model that makes governance composable, verifiable, and mechanically enforceable.

Decision

Model the governance framework using category theory concepts:

  • Objects: Governance artifacts (SSOT atoms, docs, configs, scripts)
  • Morphisms: Transformations between artifacts (extract, verify, sync, score)
  • Functors: Structure-preserving maps between governance domains (e.g., policy domain to enforcement domain)
  • Natural transformations: Systematic changes across all artifacts in a category (e.g., schema migrations, format upgrades)

The Python core (src/morphism/) implements the category-theory engine. Governance scripts (scripts/) act as concrete morphisms. The 7 kernel invariants (I-1 through I-7) define the laws that morphisms must preserve.

This framing is explanatory, not prescriptive -- the enforceable rules live in morphism-kernel.md, not in the theory document.

Consequences

Positive

  • Composability: governance rules combine predictably (functor composition)
  • Completeness checks: the theory identifies missing morphisms (gaps in enforcement)
  • Formal verification path: invariants can be stated as theorems and checked

Negative

  • Steep conceptual barrier for contributors unfamiliar with category theory
  • Risk of over-formalization for simple governance tasks

Neutral

  • The theory document (docs/architecture/morphism-theory.md) is non-normative; contributors can ignore it and follow the kernel directly

Alternatives Considered

Alternative 1: Flat rule lists (YAML/JSON policy files)

  • Pros: Simple to read, easy to extend
  • Cons: No composition model; rules interact unpredictably at scale
  • Why rejected: Does not prevent contradictions or detect gaps

Alternative 2: OPA/Rego policy engine

  • Pros: Industry-standard, good tooling
  • Cons: External dependency; limited to access-control-style policies
  • Why rejected: Our governance includes documentation, CI, and entropy measurement -- broader than OPA's scope

References