MORPHISM: Governance Framework for morphism-systems¶
Version: 2.0 (repo-aligned)
Normative source: morphism-kernel.md
Rationale: ADR-002
Theory (non-normative): morphism-theory.md
Soundness: Executable and rationale soundness for all 7 invariants and 10 tenets. Formal verification on roadmap. See ALGORITHMIC_VALIDATION.md §6.
NON-NORMATIVE. Normative invariants live only in morphism-kernel.md.
Preamble¶
Entropy is the default. Governance is the override.
In evolving systems, disorder increases unless work is applied to maintain order. In software this is drift; in LLM sessions it is context loss. This framework defines a minimal governance architecture for the morphism-systems monorepo using category theory and ideation algebra. The goal is not to maximize features but to minimize entropy. Enforceable requirements are in the Kernel; this document is the consolidated reference.
1. Normative kernel (invariants and protocol)¶
Canonical text: morphism-kernel.md. The table below is a quick-reference mapping; it does not restate the normative text.
| Invariant | Name | Enforcement |
|---|---|---|
| I-1 | One Truth Per Domain | ssot_verify.py · docs_sync.py |
| I-2 | Drift Is Debt | drift-check workflow · ssot_extract.py |
| I-3 | Observability | commit-msg hook · validate_commit.py |
| I-4 | Scope Binding | PR review · MORPHISM.md §4 |
| I-5 | Entropy Monotonicity | maturity_score.py --ci --threshold 60 |
| I-6 | Refusal as Structure | policy_check.py --mode ci --explain |
| I-7 | Minimal Authority | verify_pipeline.py (CODEOWNERS check) |
Protocol (Read–Verify–Execute) — canonical:
READ → Establish current state, entropy bounds, applicable scope constraints. VERIFY → Check: valid state output? entropy preserved? scope respected? EXECUTE → Apply change, record input state, rule applied, output state, evidence.
Scope: see morphism-kernel.md §Scope.
2. Formal model (non-normative)¶
Full mathematical exposition: morphism-theory.md. The seven Kernel invariants are the minimal generating set derivable from that category-theoretic structure (categories of context, entropy functors, governance monads, refusal functors, and ideation algebra). For formal definitions and theorem statements, see MORPHISM_FORMAL.md.
3. Protocol in practice (agents and humans)¶
Operational refinement of Read–Verify–Execute for daily use:
- Read — Load AGENTS.md, SSOT.md, GUIDELINES.md, handoff-and-integration.md, deferred-work.md. No assumptions.
- State — The one thing is: [X]. Done means: [Y]. (Makes domain and completion criterion explicit; supports I-2 and I-3.)
- Verify — Confirm understanding and that the change respects scope and entropy before proposing edits.
- Execute — Small change → verify → commit. Repeat. Each step leaves an auditable trace (I-3).
- Refuse — Scope creep is out of scope. Refusal is first-class (I-6); say "That's out of scope" when the request crosses the declared boundary.
When using Claude Code or other agents, the same protocol applies: read the governance baseline first (see CLAUDE.md), state the one thing and definition of done, verify then execute, and refuse requests outside scope.
%% Agent protocol: Read-State-Verify-Execute with Refuse exits
flowchart TD
R[Read: Load governance baseline] --> S[State: Define one thing and done criteria]
S --> V{Verify: Scope respected? Entropy preserved?}
V -- Yes --> E[Execute: Small change, verify, commit]
V -- No --> REFUSE[Refuse: Out of scope]
E --> D{Done?}
D -- No --> E
D -- Yes --> T[Trace recorded]
E -- Late violation --> REFUSE
4. Operational tenets (implementation of the Kernel)¶
The following tenets are the operational implementation of the seven invariants. Tenet derivation traces: TENET_DERIVATION.md.
| Executive tenet | Invariant | One-line mapping |
|---|---|---|
| Tenet 1: SSOT Integrity | I-1, I-2 | One canonical location; drift blocks merge |
| Tenet 2: Commit Grammar | I-3 | Structured commits produce auditable trace |
| Tenet 3: Branch Naming | I-3, I-4 | Naming and branch policy enforce scope and trace |
| Tenet 4: CI Gate Passage | I-5, I-6 | All gates must pass; refusal is observable |
| Tenet 5: Secret Zero | I-3, I-7 | No secrets in repo; minimal authority over credentials |
| Tenet 6: Docs Coverage | I-1, I-4 | No orphans; docs in scope of nav and graph |
| Tenet 7: Registry Consistency | I-1, I-2 | Registry is index of SSOT atoms; hashes must match |
| Tenet 8: Dependency Freshness | I-5 | Vulnerabilities increase entropy; Dependabot + audit |
| Tenet 9: Incident Readiness | I-3, I-4 | Runbooks are trace and scope for incidents |
| Tenet 10: Maturity Tracking | I-5 | Maturity score ratchets; no regression without exception |
Tenet 1: SSOT Integrity¶
Invariant: Every governance fact exists in exactly one canonical location. Consumers reference the canonical source; duplication is replaced by SSOT atom injection.
Enforcement: scripts/ssot_verify.py validates registry hashes on every PR. scripts/docs_sync.py --check ensures consumer docs match canonical atoms. Failure: Merge blocked when ssot_verify.py exits non-zero.
Tenet 2: Commit Grammar¶
Invariant: Every commit message on main conforms to <type>(<scope>): <subject>.
Enforcement: .githooks/commit-msg runs scripts/validate_commit.py. scripts/policy_check.py --mode ci validates in CI. Failure: Commit rejected locally; CI fails on malformed commits.
Tenet 3: Branch Naming¶
Invariant: All branches follow <type>/<description>. Direct pushes to main/master blocked.
Enforcement: scripts/validate_branch.py + .githooks/pre-push. Failure: Push rejected.
Tenet 4: CI Gate Passage¶
Invariant: No PR merges without all required CI jobs passing: lint, typecheck, test, build, drift-check, SSOT verification.
Enforcement: .github/workflows/ci.yml and drift-check.yml. GitHub branch protection requires all checks. Failure: PR cannot be merged.
Tenet 5: Secret Zero¶
Invariant: No secret, credential, or API key is ever committed to the repository.
Enforcement: .morphism/hooks/pre-commit-validation.sh scans diffs. .github/workflows/security.yml runs on PRs. Failure: Commit blocked; CI security workflow fails.
Tenet 6: Docs Coverage¶
Invariant: Every governance doc, runbook, and ADR is reachable from MkDocs navigation. No orphan docs.
Enforcement: scripts/docs_graph.py --check. Failure: Docs CI fails on orphans or broken links.
Tenet 7: Registry Consistency¶
Invariant: docs/ssot/registry.json is the canonical atom index. Every atom file exists with matching SHA-256.
Enforcement: scripts/ssot_verify.py on every PR. Failure: Merge blocked on hash mismatch.
Tenet 8: Dependency Freshness¶
Invariant: No dependency has a known critical/high vulnerability unaddressed for >7 days.
Enforcement: .github/dependabot.yml (weekly). .github/workflows/security.yml runs npm audit. Failure: Security workflow fails.
Tenet 9: Incident Readiness¶
Invariant: A runbook exists for every SEV1-SEV2 incident category with decision tree, escalation, comms, and rollback.
Enforcement: docs/runbooks/ + docs_graph.py ensures nav linkage. Maturity score includes runbook coverage. Failure: Score drops below threshold.
Tenet 10: Maturity Tracking¶
Invariant: Maturity score never regresses below the CI threshold. Threshold ratchets upward.
Enforcement: scripts/maturity_score.py --ci --threshold N. Failure: CI fails on regression.
5. Repo scope and layout¶
This framework governs the morphism-systems monorepo. The normative Kernel is the document morphism-kernel.md, not a directory. There is no Kernel/Hub/Lab directory hierarchy in this repo.
| Path | Purpose |
|---|---|
apps/morphism/ |
Next.js app |
packages/shared/, packages/agentic-math/, packages/mcp-server/, packages/cli/, packages/plugin-bundle/, packages/design-tokens/ |
npm packages |
src/morphism/ |
Python core (engine, CLI) |
docs/, scripts/ |
Governance and automation |
.morphism/ |
Consumer config, hooks, workflows |
archive/ |
Read-only historical artifacts |
Governance authority: AGENTS.md, SSOT.md, GUIDELINES.md. Configuration: .morphism/. Deferred work: deferred-work.md.
6. Claude Code and tooling¶
When working with Claude Code (or Cursor, Codex, etc.):
- Baseline: Read CLAUDE.md (or the IDE-specific config in
.morphism/ide-configs/). It points to AGENTS, SSOT, GUIDELINES, HANDOFF, TODO and lists commands for validation. - Plans: Multi-step work should follow the protocol: Read → State → Verify → Execute → Refuse. Plans (e.g. from a "writing-plans" skill) should respect the same invariants and scope.
- Skills and hooks: Any skill or hook that enforces governance should align with the seven invariants (e.g. SSOT checks, trace checks, scope checks, refusal with structured output). See handoff-and-integration.md for integration checklist, CI, hooks, and drift-check.
- Agent-facing prompt: Required inputs, output formats, refusal/trace templates: agent-kernel-prompt.md.
Structure preserves through transformation. If you do not define the structure, the transformation will destroy it.
7. Glossary¶
| Term | Definition |
|---|---|
| Category | A collection of objects and morphisms (structure-preserving maps) between them, with associative composition and identity morphisms. |
| Morphism | A structure-preserving map from a source object to a target object. In governance: an enforcement relationship (e.g., Policy → GitHook). |
| Functor | A map between categories that preserves structure. The Compliance Functor maps governance objects to verification results. |
| Natural Transformation | A coherent family of morphisms between functors. Ensures policy transforms commute across all governance objects. |
| Kappa (κ) | The convergence metric: κ = d(s, F(s)), measuring distance from current state to the ideal compliant state. κ = 0 means fully compliant. |
| Delta (δ) | Rate of κ change between commits. δ < 0 = improving; δ > 0 = degrading. |
| Entropy | Information-theoretic disorder across governance dimensions. Lower entropy = more consistent compliance. |
| Governance Monad | The categorical structure (T, η, μ) encoding context accumulation and flattening in governance state. |
| Ideation Algebra | The algebraic structure governing how governance concepts compose, refine, and propagate through the system. |
| Sheaf | A mathematical structure that tracks local-to-global consistency. Used for drift detection across governance dimensions. |
| Fixed Point | A governance state s where F(s) = s — the system is fully compliant and stable under the compliance functor. |
For the full mathematical treatment, see morphism-theory.md.
8. Amendment process¶
- Open a PR modifying the Kernel (morphism-kernel.md) and the corresponding ADR.
- Run
python scripts/ssot_extract.pyto re-hash updated atoms. - Obtain review from CODEOWNERS.
- Merge only after drift-check and integration-gate pass.
Amendments that weaken an invariant MUST include a documented exception rationale in the ADR.
Normative: morphism-kernel.md · Theory: morphism-theory.md · Rationale: ADR-002 · Operations: MORPHISM.md §4