Morphism Unified Documentation Draft

assetactive

Morphism Unified Documentation Draft

Source: morphism-unified-documentation-draft.md (ingested 2026-03-28)

Done — I consolidated the material into a single canonical documentation draft in the canvas and normalized the overlapping versions into one structure:

MORPHISM

Unified Overview and Technical Documentation

Governance for Computational Systems, AI Agents, and Repo-Scale Transformation

0. Executive Summary

MORPHISM is a governance framework for computational systems. Its purpose is not to add process theater, observability theater, or tool sprawl. Its purpose is to preserve structure under transformation.

The core claim is simple:

Entropy is the default. Governance is the override.

In software, entropy appears as drift, duplicated truth, undocumented changes, uncontrolled scope expansion, weak dependency boundaries, and loss of alignment between specification and implementation. In AI-assisted development, the same problem appears as context loss, hallucination, archaeology before execution, and motion without durable progress.

MORPHISM treats these failures as structure violations rather than productivity quirks. It therefore frames software work, documentation work, and agent work as constrained transformations inside a governed system.

The framework has three tightly related forms:

  1. The formal model: category theory, entropy, monadic governance, and ideation algebra.
  2. The operational kernel: the smallest enforceable set of tenets and protocol steps.
  3. The implementation layer: hooks, plans, skills, CI/CD, dashboards, and repository layout.

The document below unifies all of those into one canonical description.

1. Problem Statement

Modern engineering systems do not fail only because code is wrong. They fail because transformations are under-governed.

Typical failure patterns include:

| Failure | Description | Consequence | | ------------------ | ------------------------------------------------ | -------------------------------------------- | | Duplicate truth | Multiple docs claim to govern the same domain | Drift, ambiguity, invalid decisions | | Intent drift | Docs and code diverge | Broken trust between spec and implementation | | Activity theater | Many actions, little durable progress | False sense of momentum | | Archaeology trap | Excessive exploration before defining the target | Long sessions, weak execution | | Context loss | Sessions restart without preserving decisions | Rework, reversals, hallucinated continuity | | Scope creep | Local task leaks into unrelated domains | Boundary failure, hidden risk | | Reverse dependency | Core logic depends on peripheral experimentation | Fragile architecture | | Missing trace | Changes happen without explanation | No auditability or remediation path |

MORPHISM exists to make these failures explicit, measurable, and enforceable.

2. What MORPHISM Is

MORPHISM is a governance kernel for computational systems.

It is:

  • a way to define the canonical source of truth for each domain,
  • a way to constrain transformations before they execute,
  • a way to preserve intent through implementation,
  • a way to reject unsafe or out-of-scope actions,
  • a way to operationalize all of the above through software.

It is not merely:

  • a linter,
  • a documentation standard,
  • an observability dashboard,
  • a static policy bundle,
  • an AI wrapper,
  • or a prompt pattern.

Those may be implementation surfaces, but they are not the governing idea.

3. Formal Model

3.1 Category of Context

Let a project, repository, workflow, or LLM session be modeled as a category C.

  • Objects are states of the system:

    • Intent
    • Spec
    • Codebase
    • Documentation
    • Config
    • Deployment
    • Agent State

  • Morphisms are valid transitions between states:

    • draft_spec
    • implement_feature
    • refactor
    • run_migration
    • answer_query
    • update_policy
    • deploy

Composition is defined only when types line up:

g ∘ f is admissible iff cod(f) = dom(g).

This is the first governance rule in mathematical form: invalid compositions are not “creative flexibility”; they are structurally invalid transitions.

3.2 Entropy as Disorder of Future Action

A system without governance tends toward increasing disorder.

For interactive sessions, one useful approximation is:

S(session) = -k Σ p_i ln p_i

where p_i is the probability mass assigned to the set of plausible next actions.

Interpretation:

  • If the next action is highly constrained and obvious, entropy is low.
  • If the session could branch into many unrelated actions, entropy is high.
  • Multiple competing documents increase branching.
  • Ambiguous scope increases branching.
  • Missing “done” criteria increase branching.

A second practical relation appears directly in the source material:

Signal(docs) ∝ 1 / n

where n is the number of competing “sources of truth.”

This is not a literal physical law; it is a governance heuristic. As the number of supposed canonical sources increases, the signal available to both humans and agents decays.

3.3 Governance Monad

Raw transformation is unsafe. Therefore governance wraps action.

Let M be the governance monad.

  • Unit (η): load canonical context before acting.
  • Bind: permit execution only after validation against source, scope, and protocol.

Informally:

Action -> M(Action)

and then:

M(Action) >>= Verify

which yields either:

  • an admissible governed action, or
  • a refusal.

This is the formal basis for the operational protocol:

Read -> State -> Verify -> Execute -> Refuse

3.4 Refusal Functor

Governance is incomplete if it cannot reject invalid work.

Define a refusal operator:

R(x) =
  Error        if x ∉ Scope or x lacks required structure
  Execute(x)   otherwise

An agent or tool that cannot refuse:

  • out-of-scope work,
  • under-specified work,
  • conflicting-truth work,
  • or non-traceable work,

is structurally unsafe.

3.5 Governance Functor

A stronger formulation appears in the supporting material:

Let Γ : C_free -> C_gov map unconstrained system behavior into governed behavior while preserving composition and identity.

Properties:

  1. Γ(s) = s' where s' satisfies the tenets.
  2. Γ(φ : A -> B) = φ' : Γ(A) -> Γ(B).
  3. Γ(ψ ∘ φ) = Γ(ψ) ∘ Γ(φ).
  4. Γ(id_A) = id_{Γ(A)}.

This captures the idea that governance is not an after-the-fact annotation. It is a structure-preserving projection from free behavior into admissible behavior.

3.6 Entropy Reduction Claim

A useful supporting theorem from the source material is:

H(Γ(s)) ≤ H(s)

Interpretation:

Governance reduces the accessible state space by eliminating states that violate the tenets. Fewer admissible misaligned states means less disorder.

This does not mean governance removes all complexity. It means it removes invalid complexity.

4. Ideation Algebra

MORPHISM does not only govern code. It governs the transformation of ideas into artifacts.

4.1 Composition

The canonical development chain is:

Intent -> Spec -> Code -> Deployment

or, more explicitly:

Intent --architect--> Spec --implement--> Code --release--> Deployment

Rule:

You may not apply a later morphism before the earlier one exists with compatible type.

Practical meaning:

  • do not code before the spec exists,
  • do not deploy before the implementation has been verified,
  • do not refactor behavior unless the behavior contract is known.

4.2 Product

A real system is rarely one thing. It is a product of components:

System = Frontend × Backend × Policy × Documentation × Observability

Changing one factor changes the effective system.

Practical meaning:

  • policy changes are product changes,
  • documentation changes are product changes,
  • interface changes require re-evaluation of dependent components.

4.3 Limit: The One Thing

Every work session must converge on a single goal.

Represent that as a limit over admissible actions toward a target object:

lim <- (Goal)

Operational interpretation:

  • each action must pull back to the same goal,
  • if an action does not reduce distance to the goal, it is divergence,
  • if there are multiple incompatible goals, the session is under-specified.

This is the formal basis for the sentence:

The ONE thing is: [X]. Done means: [Y].

5. Deriving the Minimal Kernel

The source material contains several overlapping formulations:

  • an 8-tenet minimal formalization,
  • a 7-tenet prompt-form kernel,
  • a broader 42-tenet / 12-section framing,
  • and an axiomatic extension with 10 foundational axioms.

These can be reconciled by treating the 7-tenet kernel as the minimal operational basis, and the larger systems as extensions.

5.1 The Minimal Seven Tenets

| ID | Name | Core claim | | --- | ------------------------------------------ | ---------------------------------------------------------------- | | I-1 | Sole Source | One truth per domain | | I-2 | Drift Is Debt | Intent/implementation divergence is a defect | | I-3 | Observability | Every meaningful change must be traceable | | I-4 | Scope Binding | Every action must remain within an explicit sub-domain | | I-5 | Morphism Preservation | Transformations must preserve required structure and contracts | | I-6 | Refusal as Structure | Unsafe or under-specified work must be rejected or paused | | I-7 | Entropy Monotonicity and Minimal Authority | Governance must reduce disorder using the least sufficient force |

5.2 Why These Seven Are Minimal

They are sufficient because:

  • without I-1, truth fragments,
  • without I-2, drift becomes normalized,
  • without I-3, no audit trail exists,
  • without I-4, locality collapses,
  • without I-5, structure is destroyed by transformation,
  • without I-6, the system cannot protect itself,
  • without I-7, governance either fails to reduce entropy or becomes overbearing.

Everything else can be derived as a concrete specialization.

5.3 Relation to the Eight-Tenet Version

The earlier 8-tenet version can be embedded into the 7-tenet kernel like this:

| 8-Tenet Form | 7-Tenet Kernel Mapping | | ------------------------ | ---------------------------------------- | | Sole Source | I-1 | | Definition of Done | I-4 + I-5 + protocol state step | | Intent vs Implementation | I-2 + I-5 | | Isomorphism of Execution | I-5 | | Trace Requirement | I-3 | | Scope as Functor | I-4 | | Entropy Mitigation | I-7 | | Kernel Hierarchy | I-4 + I-5 as an architectural constraint |

So the seven-tenet version is more minimal because it lifts several implementation-specific tenets into broader structural principles.

6. The Extended Axiomatic System

The longer-form material also introduces foundational axioms. These are useful as meta-properties of the governance kernel.

| Axiom | Meaning | | ------------- | -------------------------------------------------------- | | Consistency | No action may violate established invariants | | Idempotence | Reapplying governance to a stable state changes nothing | | Composability | Governance distributes over sequential actions | | Determinism | Same governed input should produce same governed outcome | | Minimality | Apply the least restrictive sufficient constraint | | Observability | Every transition is attributable | | Reversibility | Preserve provenance needed for remediation | | Locality | Constrain the smallest relevant context | | Monotonicity | Governance strength increases with risk | | Completeness | The tenet system covers meaningful action classes |

These axioms do not replace the seven tenets. They characterize what a valid governance framework should itself satisfy.

7. The Operational Protocol

The protocol is the runtime instance of the governance monad.

| Step | Name | Purpose | Output | | ---- | ------- | --------------------------------------------------------- | ---------------------- | | 1 | Read | Load canonical sources and boundary documents | Active context | | 2 | State | Define the one thing and done criteria | Goal card | | 3 | Verify | Check truth, scope, preservation, and trace requirements | Admissibility result | | 4 | Execute | Perform the smallest valid transformation | Traceable state change | | 5 | Refuse | Reject or defer invalid requests with actionable guidance | Safe non-action |

7.1 Read

Load:

  • the governing kernel,
  • project-specific instructions,
  • the source-of-truth map,
  • scope boundaries,
  • relevant specs, ADRs, or contracts.

Canonical operational phrase from the source material:

  • Load MORPHISM.md.
  • Load CLAUDE.md.
  • No assumptions.

7.2 State

Before proposing or executing work, explicitly state:

  • The ONE thing is: [objective]
  • Done means: [binary completion condition]

This prevents the archaeology trap.

7.3 Verify

Check at least:

  • Is there exactly one canonical source for this domain?
  • Does the requested action remain in scope?
  • Will the transformation preserve required behavior and structure?
  • Is trace being created?
  • Is the request sufficiently specified?

If not, either refuse or ask for the minimum missing information.

7.4 Execute

Execution must be:

  • local,
  • small,
  • verified,
  • traceable,
  • and composable.

Canonical pattern:

Small change -> verify -> commit. Repeat.

7.5 Refuse

Refusal is not failure. It is successful governance.

A valid refusal should state:

  • what constraint is violated,
  • why execution would be unsafe,
  • and the minimum needed to proceed.

8. Failure Modes

The source material names several important failure modes. They can be unified as entropy manifestations.

8.1 Activity Theater

Definition:

High local motion, zero meaningful displacement in governed state.

Symptoms:

  • many commands,
  • many tool calls,
  • little durable output,
  • no canonical artifacts updated.

Formal intuition:

Large path length in action space, near-zero net displacement in state space.

8.2 Archaeology Trap

Definition:

Excessive exploration of the input universe before defining the output target.

Symptoms:

  • scanning many files before stating the actual goal,
  • learning the whole system to solve a local task,
  • conflating uncertainty reduction with progress.

Formal intuition:

Searching large neighborhoods in state space without first selecting the target object.

8.3 Context Loss

Definition:

Session transitions that fail to preserve crucial prior decisions.

Symptoms:

  • restarting analysis from scratch,
  • reversing settled decisions,
  • duplicate work,
  • hallucinated continuity.

Formal intuition:

A non-injective transition from one session state to the next.

8.4 Drift

Definition:

A mismatch between the intent category and the implementation category.

Symptoms:

  • code and docs disagree,
  • tool behavior no longer matches policy,
  • dashboards report a state the repo no longer has.

8.5 Reverse Dependency

Definition:

Peripheral layers constrain or infect the core.

Symptoms:

  • experimental code imported by governance core,
  • policy logic depends on temporary workflows,
  • distribution layer mutates kernel contracts.

9. Architectural Form: Kernel / Hub / Lab

The source material repeatedly presents a three-layer architecture:

KERNEL (governance)
  ↓ imports
HUB (distribution)
  ↓ imports
LAB (experiments)

9.1 Meaning of the Layers

| Layer | Role | Change rate | Permitted responsibility | | ------ | -------------------------------------------------- | ----------- | --------------------------------------------------- | | Kernel | Governing contracts, invariants, definitions | Lowest | Canonical rules, semantics, constraints | | Hub | Reusable operationalization and distribution logic | Medium | CLI, policy packs, adapters, shared execution logic | | Lab | Experiments and provisional exploration | Highest | Research, prototypes, temporary tests |

9.2 Boundary Rule

The reverse direction is prohibited.

Why:

  • the core must not depend on experimentation,
  • policy must not inherit instability from labs,
  • reusable distribution logic must not be rewritten by peripheral work.

9.3 Practical Repository Mapping

A canonical repo layout implied by the source material is:

.morphism/
  KERNEL.md
  claude-code-config.yml
  skills/
  plans/

docs/
  GOVERNANCE.md
  adr/
  specs/

src/
  kernel/
  hub/
  lab/

hooks/
  t1_sole_source.py
  t3_verify_commutativity.py
  t5_trace_commit.py
  t6_scope_guardian.py

scripts/
  validators/
  governance/

tools/
  generate_governance_health.py

.github/workflows/
  morphism.yml

10. MORPHISM as Product Architecture

One supporting file also describes Morphism as a product/control-plane concept.

That can be integrated without changing the formal kernel.

10.1 Product Framing

Morphism helps engineering teams keep AI-assisted workflows consistent, auditable, and controllable across repositories, CI surfaces, and agent-driven tooling.

This implies four product layers:

| Layer | Function | | ---------- | ------------------------------------------------------------ | | CLI | First adoption surface; local validation and scoring | | MCP Server | Same control logic exposed to editors and agents | | CI | Workflow gates, evidence capture, policy enforcement | | Dashboard | Shared visibility into policies, drift, agents, proofs, logs |

10.2 Key Product Claim

The product is not just visibility. It is a workflow control plane.

That aligns cleanly with the formal model:

  • the CLI performs local governance,
  • the MCP layer exposes governed transforms to agents,
  • CI enforces admissibility before merge,
  • the dashboard makes governed state legible.

11. From Kernel to Implementation

The source material operationalizes MORPHISM in three major ways:

  1. Hookify rules
  2. Writing plans
  3. Writing skills

These are not arbitrary tooling categories. They correspond to different governance surfaces.

| Surface | Governance role | | ------- | ------------------------------------------------ | | Hooks | Prevent invalid transitions automatically | | Plans | Structure multi-step work before implementation | | Skills | Reusable governed operations for recurring tasks |

11.1 Hookify Rules as Enforcement

Hooks are the automated realization of refusal and admissibility checks.

Representative hook families from the source material:

| Tenet | Hook purpose | | ------------------------ | --------------------------------------------- | | Sole Source | Detect duplicate or conflicting documentation | | Intent vs Implementation | Compare specs and code behavior | | Scope Binding | Enforce layer and path boundaries | | Trace Requirement | Enforce meaningful commit messages |

11.2 Plans as Protocol Materialization

Plans force work to pass through:

Read -> State -> Verify -> Execute -> Refuse

before code is touched.

This is especially important for:

  • large refactors,
  • governance consolidation,
  • behavior-preserving migration,
  • architecture changes.

11.3 Skills as Tenet Embodiments

Skills package recurring governed transforms.

Representative skills from the source material:

  • Verify Commutativity
  • Scope Guardian
  • Intent Capture

These map naturally onto I-5, I-4, and I-1/I-2.

12. Example Governance Hooks

The source includes sample Python implementations. They are preserved here as canonical examples.

12.1 T1 / I-1: Sole Source Check

#!/usr/bin/env python3
"""
T1: Detect multiple sources of truth for the same section header in docs/.
If duplicates exist across docs/*md with the same header, block commit.
Usage: python t1_sole_source.py <docs_dir>
"""

import sys
import os
import re
from collections import defaultdict

HEADER_RE = re.compile(r"^(#+)\s+(.*)$", re.M)

def collect_headers(docs_dir):
    headers_map = defaultdict(list)
    for root, _, files in os.walk(docs_dir):
        for f in files:
            if not f.lower().endswith(".md"):
                continue
            path = os.path.join(root, f)
            try:
                with open(path, "r", encoding="utf-8") as fh:
                    content = fh.read()
            except Exception:
                continue
            for m in HEADER_RE.finditer(content):
                level = len(m.group(1))
                title = m.group(2).strip()
                if level >= 2:
                    key = (level, title)
                    headers_map[key].append(path)
    return headers_map

def main():
    docs_dir = sys.argv[1] if len(sys.argv) > 1 else "docs"
    headers_map = collect_headers(docs_dir)
    conflicts = {k: v for k, v in headers_map.items() if len(v) > 1}
    if conflicts:
        print("T1 Violation: Conflicting headers detected across docs/")
        for (level, title), paths in conflicts.items():
            print(f"  Header (level {level}): '{title}' found in:")
            for p in paths:
                print(f"    - {p}")
        print("\nAction: Merge into a single canonical document and update references.")
        sys.exit(1)
    print("T1 Passed: No header conflicts detected.")
    sys.exit(0)

if __name__ == "__main__":
    main()

12.2 T3 / I-2 + I-5: Verify Commutativity

#!/usr/bin/env python3
"""
T3: Verify that code behavior matches documented intent.
A lightweight symbolic check: compare documented function signatures/intent
in ADRs/specs with actual Python function signatures in src/.
Exit code 0 if commutes, non-zero if divergence detected.
"""

import ast
import os
import re
import sys

INTENT_RE = re.compile(r"^Intent:\s*(.*)$", re.M)
SIGNATURE_RE = re.compile(r"def\s+([a-zA-Z_]\w*)\s*\((.*?)\):")

def extract_intents(doc_root):
    intents = {}
    for root, _, files in os.walk(doc_root):
        for f in files:
            if not f.endswith(".md"):
                continue
            path = os.path.join(root, f)
            with open(path, "r", encoding="utf-8") as fh:
                text = fh.read()
            for m in INTENT_RE.finditer(text):
                header = m.group(1).strip()
                if header:
                    intents[header] = m.group(0)
    return intents

def extract_signatures(src_root):
    sigs = {}
    for root, _, files in os.walk(src_root):
        for f in files:
            if not f.endswith(".py"):
                continue
            path = os.path.join(root, f)
            with open(path, "r", encoding="utf-8") as fh:
                src = fh.read()
            try:
                tree = ast.parse(src, filename=path)
            except SyntaxError:
                continue
            for node in ast.walk(tree):
                if isinstance(node, ast.FunctionDef):
                    sig = (node.name, ast.get_source_segment(src, node.args))
                    sigs[node.name] = (path, sig[1] if sig[1] else "")
    return sigs

def main():
    docs_root = "docs"
    src_root = "src"

    intents = extract_intents(docs_root)
    sigs = extract_signatures(src_root)

    mismatches = []
    for name, sig in sigs.items():
        if name in intents:
            mismatches.append((name, sig, intents[name]))
    if mismatches:
        print("T3 Divergence Detected:")
        for name, sig, intent in mismatches:
            print(f"- {name}: signature={sig}, intent={intent}")
        sys.exit(1)
    print("T3 Passed: Code signatures align with documented intents where provided.")
    sys.exit(0)

if __name__ == "__main__":
    main()

12.3 T6 / I-4: Scope Guardian

#!/usr/bin/env python3
"""
T6: Enforce Kernel/Hub/Lab import hierarchy.
Rules:
- KERNEL can import HUB and LAB
- HUB can import LAB
- LAB must not import KERNEL or HUB
"""

import ast
import os
import sys

LAYERS = {
    "kernel": 0,
    "hub": 1,
    "lab": 2,
}

def layer_of(path):
    p = path.replace("\\", "/")
    if p.startswith("src/kernel/"):
        return 0
    if p.startswith("src/hub/"):
        return 1
    if p.startswith("src/lab/"):
        return 2
    return 3

def main():
    root = "src"
    violations = []
    for dirpath, _, files in os.walk(root):
        for f in files:
            if not f.endswith(".py"):
                continue
            path = os.path.join(dirpath, f)
            with open(path, "r", encoding="utf-8") as fh:
                src = fh.read()
            try:
                tree = ast.parse(src, filename=path)
            except SyntaxError:
                continue
            importer_layer = layer_of(path)
            for node in ast.walk(tree):
                if isinstance(node, (ast.Import, ast.ImportFrom)):
                    if isinstance(node, ast.Import):
                        mod = node.names[0].name
                    else:
                        mod = (node.module or "")
                    imported_path = None
                    if mod.startswith("src.kernel"):
                        imported_path = "src/kernel/..."
                    elif mod.startswith("src.hub"):
                        imported_path = "src/hub/..."
                    elif mod.startswith("src.lab"):
                        imported_path = "src/lab/..."
                    if not imported_path:
                        continue
                    imported_layer = layer_of(imported_path)
                    if importer_layer > imported_layer:
                        violations.append((path, mod, importer_layer, imported_layer))
    if violations:
        print("T6 Scope Violation Detected:")
        for (path, mod, il, ilt) in violations:
            print(f"- {path} imports {mod}: importer_layer={il}, imported_layer={ilt}")
        sys.exit(1)
    print("T6 Passed: Dependency graph respects Kernel/Hub/Lab DAG.")
    sys.exit(0)

if __name__ == "__main__":
    main()

12.4 T5 / I-3: Trace Requirement

#!/usr/bin/env python3
"""
T5: Enforce commit messages include a reference to a Tenet or Issue.
"""

import sys
import re

TENET_REF = re.compile(r"\bT\d+\b|#\d+|ISSUE-\d+", re.IGNORECASE)

def main():
    import_path = ".git/COMMIT_EDITMSG"
    try:
        with open(import_path, "r", encoding="utf-8") as fh:
            msg = fh.read()
    except Exception:
        print("T5: Unable to read commit message.")
        sys.exit(1)

    if TENET_REF.search(msg):
        print("T5 Passed: Commit message contains a tenet/issue reference.")
        sys.exit(0)
    else:
        print("T5 Violation: Commit message missing Tenet/Issue reference.")
        print("Please reference a Tenet (e.g., T1) or an Issue (e.g., #123) in the commit message.")
        sys.exit(1)

if __name__ == "__main__":
    main()

13. Planning Patterns

The source material provides two especially important plan types.

13.1 Consolidation Plan

Use when multiple governance artifacts exist and must be collapsed into one canonical document.

# Consolidation Plan: Unify Governance Documentation

## Phase 1: Read
- Audit all sources
- Extract unique information
- Identify redundancy and contradiction
- Select canonical target

## Phase 2: State
- Define the canonical document as the initial object
- Define done: all governance information flows from this document only

## Phase 3: Verify
- Diff old vs new
- Confirm no information loss
- Update link paths

## Phase 4: Execute
- Move content into canonical source
- Deprecate old sources
- Commit with trace

## Phase 5: Refuse
- Add enforcement so new duplicate governance docs cannot appear silently

13.2 Isomorphic Refactor Plan

Use when architecture changes must preserve behavior.

# Refactoring Plan: Function -> Class Architecture

## Phase 1: Read
- Extract signatures
- Document contracts and edge cases
- Treat current tests as ground truth

## Phase 2: State
- Map each function to a behavior-preserving method
- Define done: all tests pass before and after

## Phase 3: Verify
- Baseline old behavior
- Compare against new behavior
- Assert behavioral equality

## Phase 4: Execute
- Add non-breaking wrapper
- Migrate calls
- Remove old surface only after verification

## Phase 5: Refuse
- Add regression protections in CI

14. Skills as Governed Modules

14.1 Verify Commutativity

Purpose:

Ensure implementation matches documented intent.

Inputs:

  • PR or commit SHA
  • design doc, ADR, or spec

Outputs:

  • PASS: diagram commutes
  • FAIL: specific divergence

14.2 Scope Guardian

Purpose:

Ensure new changes respect Kernel/Hub/Lab and domain boundaries.

Outputs:

  • placement guidance,
  • dependency violation report,
  • suggested refactoring path.

14.3 Intent Capture

Purpose:

Force explicit statement of:

  • the one thing,
  • definition of done,
  • success signal,
  • governing documents.

Representative output structure:

INTENT CAPTURE

The One Thing:
[objective]

Definition of Done:
[binary completion criteria]

Success Signal:
[how success is verified]

Related Documentation:
[canonical sources]

15. CI/CD Integration

The source material includes a GitHub Actions skeleton.

name: MORPHISM Governance CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'

  hooks-and-guards:
    runs-on: ubuntu-latest
    needs: setup
    steps:
      - uses: actions/checkout@v4
      - name: Run governance hooks
        run: |
          python hooks/t1_sole_source.py docs || true
          python hooks/t3_verify_commutativity.py || true
          python hooks/t6_scope_guardian.py || true
          python hooks/t5_trace_commit.py || true

  commutativity-check:
    runs-on: ubuntu-latest
    needs: hooks-and-guards
    steps:
      - uses: actions/checkout@v4
      - name: Verify commutativity
        run: |
          python hooks/t3_verify_commutativity.py || true

15.1 Important Correction

One part of the sample CI uses || true, which suppresses failure.

That is acceptable for demonstration, but not for real enforcement.

In production, governance-critical checks should fail the workflow when their tenet is configured as mandatory.

Recommended pattern:

  • advisory mode during rollout,
  • blocking mode once false positives are controlled.

16. Governance Dashboard

The dashboard is an observability surface for governed state, not the governance itself.

Useful tiles from the source material:

| Metric | Meaning | | --------------- | ---------------------------------------- | | Entropy | Approximate current disorder / branching | | Tenets Passed | Number of active checks passing | | Docs Count | Number of governance-relevant docs | | Plans Generated | Number of structured plan artifacts |

Sample HTML from the source material:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>MORPHISM Governance Dashboard</title>
  <style>
    body { font-family: Arial, sans-serif; padding: 20px; }
    .tile { border: 1px solid #ccc; border-radius: 8px; padding: 12px; margin: 8px; width: 200px; display: inline-block; vertical-align: top; }
  </style>
</head>
<body>
  <h1>MORPHISM Governance Dashboard</h1>
  <div class="tile"><h3>Entropy</h3><p>0.12</p></div>
  <div class="tile"><h3>Tenets</h3><p>5 / 8 passes</p></div>
  <div class="tile"><h3>Docs</h3><p>20</p></div>
  <div class="tile"><h3>Plans</h3><p>4</p></div>
</body>
</html>

16.1 Health JSON Generator

#!/usr/bin/env python3
import os, json

def count_docs(root="docs"):
    md = 0
    for _, _, files in os.walk(root):
        for f in files:
            if f.endswith(".md"):
                md += 1
    return md

def main():
    health = {
        "entropy": 0.15,
        "tenets_passed": 5,
        "tenets_total": 8,
        "docs_count": count_docs(),
        "plans_generated": 2,
    }
    with open("governance-health.json", "w", encoding="utf-8") as f:
        json.dump(health, f, indent=2)

if __name__ == "__main__":
    main()

16.2 Important Correction

Entropy should not remain a placeholder forever.

A more useful practical approximation would combine:

  • number of unresolved drift findings,
  • number of duplicate governance sources,
  • number of scope violations,
  • number of undocumented changes,
  • ambiguity count in active plans.

Example:

H_practical = w1*drift + w2*dup_truth + w3*scope_violations + w4*trace_failures + w5*open_ambiguities

This is not Shannon entropy in the strict sense. It is a governance risk score inspired by entropy logic.

17. Claude Code / Agent Integration

The source material presents three integration modes.

17.1 As System Prompt / Constitution

Use the MORPHISM kernel as the governing system prompt or custom instruction set.

17.2 As Versioned Repo Context

Store the kernel in the repo as canonical files such as:

  • .morphism/KERNEL.md
  • CLAUDE.md
  • SCOPE.md
  • SSOT.md

Then start each session with a hard reset into governed context:

Load .morphism/KERNEL.md and CLAUDE.md. No assumptions.

17.3 As Skills / Hooks / Plans Generator

Use the kernel to generate:

  • hook rules,
  • plans,
  • reusable skills,
  • and enforcement workflows.

This is the most powerful form because the constitution becomes executable.

18. Prompt-Form Kernel

The prompt-form version of MORPHISM can be restated as a compact machine-operational contract.

Required Inputs

  1. Source-of-truth map
  2. Scope boundary
  3. The One Thing
  4. Trace requirement

Mandatory runtime behavior

  1. Read canonical sources
  2. State the one thing and done criteria
  3. Verify admissibility
  4. Execute only governed transforms
  5. Refuse unsafe work

Refusal template

A useful refusal should include:

  • violated tenet,
  • blocked action,
  • rationale,
  • minimum needed to proceed.

Trace template

A useful trace should include:

  • governing source,
  • action taken,
  • reason,
  • changed artifacts,
  • verification result,
  • risk notes.

19. Suggested Unified Canonical Files

To collapse the overlapping source material into a coherent repo-level kernel, use the following canonical set.

| File | Purpose | | ------------------------- | ------------------------------------------------ | | .morphism/KERNEL.md | Formal and operational kernel | | .morphism/OPERATIONS.md | Protocol, plans, refusal templates, trace format | | .morphism/AUTOMATION.md | Hooks, skills, CI/CD, dashboard spec | | docs/GOVERNANCE.md | Human-readable overview and policy explanation | | docs/adr/ | Design decisions and deviations | | SCOPE.md | Active boundaries and layer ownership | | SSOT.md | Domain -> canonical source mapping |

Recommended rule:

  • KERNEL.md governs semantics.
  • OPERATIONS.md governs runtime use.
  • AUTOMATION.md governs enforcement.
  • GOVERNANCE.md explains all of the above to humans.

20. What Should Be Kept, Merged, or Removed

Keep

  • entropy framing,
  • category-theoretic formalization,
  • the seven-tenet minimal kernel,
  • the five-step protocol,
  • Kernel/Hub/Lab hierarchy,
  • commutativity and scope skills,
  • example hooks,
  • CI and dashboard concepts,
  • product framing as workflow control plane.

Merge

  • 8-tenet and 7-tenet versions,
  • prompt-form and narrative-form kernel,
  • architecture framing and governance framing,
  • dashboard/CI examples into one automation chapter.

Remove or demote

  • duplicate restatements of the same sections,
  • placeholder examples that silently pass CI via || true unless explicitly marked advisory,
  • claims that are not yet grounded in implementation or proof,
  • repeated instructions about whether to hand the document directly to Claude Code.

21. Recommended Final Positioning

The strongest concise statement consistent with all source material is:

MORPHISM is a governance kernel and workflow control plane for human and AI-assisted software transformation. It defines canonical truth, constrains scope, preserves structure, requires trace, rejects unsafe work, and operationalizes those rules through hooks, plans, skills, CI, and dashboards.

That statement preserves:

  • the theoretical ambition,
  • the repo-agnostic kernel,
  • the product direction,
  • and the agent/tool integration model.

22. Coda

The framework reduces software governance to constraint-preserving transformation.

  1. Define the source of truth.
  2. Define the one thing.
  3. Constrain the scope.
  4. Verify that the transformation preserves required structure.
  5. Execute only traceable local change.
  6. Refuse invalid work.
  7. Measure remaining disorder.

Structure must preserve through transformation.

If structure is undefined, transformation becomes drift. If truth is duplicated, signal decays. If scope is unbound, sessions diverge. If trace is absent, work becomes unverifiable. If refusal is impossible, governance is cosmetic.

Entropy is the default. Governance is the override.

What I unified from your pasted source:

  • the original MORPHISM framing around entropy, governance, Kernel/Hub/Lab, and the 42-tenet / 12-section identity,
  • the formal category-theoretic and ideation-algebra model, including entropy, the governance monad, commutativity, and refusal,
  • the reduced seven-tenet kernel from the prompt-form version, which I treated as the minimal operational basis,
  • the Claude Code operationalization through hookify rules, plans, and skills,
  • the sample Python hooks, CI/CD workflow, and governance dashboard examples,
  • the product/control-plane framing from your Morphism architecture notes.

A few improvements I made while merging:

  • collapsed the 8-tenet and 7-tenet variants into one derivation, rather than leaving them as competing kernels,
  • kept all major code examples and tables,
  • marked where some sample CI behavior is advisory/demo-quality rather than true enforcement,
  • separated the formal kernel from repo implementation and product surfaces,
  • removed repeated restatements so the result reads as one document instead of stacked chat outputs.

Your original pasted file is here for reference: Pasted text.txt.

If you want, the next best step is for me to turn this unified draft into a repo-ready file set such as .morphism/KERNEL.md, .morphism/OPERATIONS.md, and .morphism/AUTOMATION.md.