Morphism Doctrine

Source: morphism-doctrine.md (ingested 2026-03-28)

type: normative authority: canonical audience: [agents, contributors, founders] last-verified: 2026-03-25

Morphism Doctrine

The canonical operating document for the morphism-systems monorepo. Every IDE, LLM, agent, and contributor follows this.

Mathematical foundations: Tenet derivations from invariants via the ideation algebra are proven in Paper 1 (Agentic Mathematics, papers/agentic-mathematics/main.tex, Section 10). Full derivation proofs for all 10 tenets are in papers/bible/full-proofs.md.

+============================================================+
|                     MORPHISM DOCTRINE                       |
|                                                             |
|   "The control plane for AI-assisted engineering."          |
+============================================================+

Morphism is a control plane for AI-assisted engineering. It enforces policy, detects drift, and produces typed evidence across four surfaces: CLI, MCP Server, CI Gate, and Dashboard. One config defines rules. Four surfaces enforce them. Every check produces a proof, not a log entry.

1. Kernel — Seven Immovable Invariants

Source: morphism-kernel.md Axiomatic motivation: morphism-philosophy.md

The Kernel is the normative source for these invariants. If this section and the Kernel disagree, the Kernel text controls.

These are enforceable, not aspirational. Violations block merges.

+-----+----------------------------+-------------------------+
| ID  | Invariant                  | Enforced By             |
+-----+----------------------------+-------------------------+
| I-1 | One Truth Per Domain       | ssot_verify.py          |
| I-2 | Drift Is Debt              | ssot_extract.py + CI    |
| I-3 | Observability              | validate_commit.py      |
| I-4 | Scope Binding              | PR review + agents      |
| I-5 | Entropy Monotonicity       | maturity_score.py       |
| I-6 | Refusal as Structure       | policy_check.py         |
| I-7 | Minimal Authority          | CODEOWNERS + CI         |
+-----+----------------------------+-------------------------+

I-1 One Truth Per Domain — Every governance assertion has exactly one canonical source. Derived artifacts reference but never restate the source. When drift is detected, merge is blocked.

I-2 Drift Is Debt — Any deviation between canonical source and its consumers is a defect. "We'll update it later" is not allowed.

I-3 Observability — Every decision that changes governance state produces an immutable trace: commit (with ticket), ADR, or registry update. Silent changes are forbidden.

I-4 Scope Binding — Every protocol declares what it does NOT govern. Implicit scope expansion is a violation. Refusal is valid when work falls outside declared scope.

I-5 Entropy Monotonicity — System entropy must not increase across releases without explicit authorization. Maturity score must not decrease below threshold.

I-6 Refusal as Structure — Rejecting a change is as cheap and observable as accepting one. Policy scripts emit structured, actionable output on rejection. Silent passes that mask failures are forbidden.

I-7 Minimal Authority — Permissions are expressed in the smallest admissible unit. CODEOWNERS covers all critical paths.

2. Protocol — Read, Verify, Execute

Source: morphism-kernel.md

Every governance-touching transition follows this sequence:

READ    -->  Establish current state, entropy bounds, scope
              |
VERIFY  -->  Valid state? Entropy preserved? Scope respected?
              |
EXECUTE -->  Apply change. Record input, rule, output, evidence.

Executing without completing Verify is undefined behavior. If a violation is discovered mid-Execute, the action rolls back.

3. Architecture

Concept Map

Ten concepts, one derivation chain:

  PHILOSOPHY (5 axioms)           morphism-philosophy.md
       | generates
  KERNEL (7 invariants)           morphism-kernel.md
       | enforced by
  DOCTRINE (operating manual)     morphism-doctrine.md (this file)
       | operationalized across
       +-- CLI .................. morphism validate, doctor, score
       +-- MCP .................. 33 governance tools for agents
       +-- CI ................... drift-check, governance-gate workflows
       +-- Dashboard ............ visual evidence + drift display
       |
       +-- Agents ............... classifier: who owns which files
       +-- Skills ............... 8 product bundles, marketplace taxonomy

Philosophy defines WHY (axioms). Kernel defines WHAT (invariants). Doctrine defines HOW (style, layout, enforcement, tenets). The four surfaces enforce it. Agents and Skills organize who does what.

System Architecture

                  .morphism/config.json
                         |
          +--------------+--------------+
          |              |              |
       packages/      src/morphism/   apps/morphism/
       (npm, TS)      (engine, Py)   (dashboard, Next.js)
          |              |              |
       CLI, MCP      Functor,        React,
       SDK, tokens   Sheaf, Entropy  Clerk, Stripe
          |              |              |
          +--------------+--------------+
                         |
                    scripts/
                 (enforcement)

Surfaces

| Surface | Command | What It Checks | Tier | |---------|---------|---------------|------| | CLI | morphism validate | Full governance suite | Free | | CLI | morphism doctor | Config + hook health | Free | | MCP | governance_validate | Same as CLI, JSON output | Free | | MCP | governance_facts | Architectural anti-patterns | Pro | | CI | validate --check | Exit 1 on any violation | Free | | Dashboard | /governance | Visual drift + evidence | Pro |

Layer Boundaries

Apps  ----depends-on---->  Packages  ----depends-on---->  (nothing app-specific)
                           Python core is independent of TypeScript.
                           Turborepo enforces TS workspace boundaries.

Python Core (`src/morphism/`)

src/morphism/
  engine/ .............. Morphism, Functor, NatTrans, Isomorphism
  core/ ................ Unified schema registry
  governance/ .......... Policy -> category mapping
  metrics/ ............. Kappa (convergence), Delta (drift)
  sheaf/ ............... Cech cohomology (consistency checking)
  entropy/ ............. Shannon + structural entropy
  proof/ ............... Categorical verification results
  healing/ ............. DriftScanner, DriftHealer, HealingLog
  cli/ ................. Click CLI (morphism command)
  agents/ .............. Agent classifier (globs + dimensions)
  bridge/ .............. JSON-RPC bridge (Python <-> TS MCP)
  review/ .............. Review engine (validation + drift scan)
  learn/ ............... Append-only learning store (178 observations)
  stats.py ............. Governance analytics
  config.py ............ Loads .morphism/config.json (Pydantic)

TypeScript Packages (`packages/`)

packages/
  shared/ .............. Types, Zod schemas — BUILDS FIRST
  mcp-server/ .......... MCP server (26 tools, plan-gated)
  cli/ ................. @morphism-systems/cli (init, validate, doctor)
  agentic-math/ ........ MCP for category theory computations
  plugin-bundle/ ....... One-command MCP installer
  sdk/ ................. Embeddable governance client
  design-tokens/ ....... Canonical design themes + CSS generators

4. Commit Grammar

Source: commit-grammar.bnf

<header>  ::=  <type>(<scope>): <subject>
<type>    ::=  feat | fix | chore | ci | docs | refactor | test | perf | build | revert
<subject> ::=  lowercase start, no period, max 72 chars total header

10 commit types. Enforced by scripts/validate_commit.py in the commit-msg hook and CI.

Examples:

feat(ssot): add atom regeneration on migration
fix(docs): correct stale link in kernel.md
chore(deps): upgrade typescript to 5.5
docs(governance): add maturity scoring rationale
docs(doctrine): collapse doc topology into five lanes

Prohibited: AI attribution (Co-Authored-By, Generated with), ALL_CAPS headers, trailing periods.

Branch Types

13 branch type prefixes (per docs/ssot/atoms/branch-types.md):

feat  feature  fix  chore  ci  docs  refactor  test  perf
hotfix  codex  build  release

Format: <type>/<description>. Direct work on main is blocked. Break-glass: ALLOW_MAIN_BRANCH=1.

This is intentional — commit types and branch types are different sets. Do not "align" them.

5. Canonical Layout

Source: canonical-layout.md

Root Files

| File | Role | Authority | |------|------|-----------| | AGENTS.md | Governance root (normative) | Canonical — contributor + agent behavior | | SSOT.md | Scope and authority (normative) | Canonical — non-doc domain ownership | | GUIDELINES.md | Development standards (normative) | Canonical — coding standards | | CLAUDE.md | Claude Code configuration | Tool adapter — no authority claims | | README.md | Public-facing entry point | Canonical — public orientation only | | docs/operations/contributing.md | Contributor workflow | Derived — points to AGENTS.md | | CHANGELOG.md | Release history | Generated | | SECURITY.md | Security reporting | Canonical — security domain |

Authority Precedence

When governance documents appear to overlap, precedence is:

0. Governance Kernel ... invariant definitions (I-1..I-7), RVE protocol
1. This Doctrine ....... documentation structure, topology, style, enforcement
2. SSOT.md ............. non-doc domain ownership, canonical-source declarations
3. AGENTS.md ........... contributor + agent operating behavior
4. GUIDELINES.md ....... coding standards, dev workflow
5. README.md ........... public orientation only

The Kernel defines the invariants. The Doctrine operationalizes them. If this Doctrine and the Kernel disagree on an invariant definition, the Kernel text controls. The Doctrine governs all domains not claimed by the Kernel's explicit scope declaration.

Rule: no domain may have more than one canonical document. Reference documents may explain a canonical domain but must not compete with its authority.

Directory Map

morphism/
  .github/ ............. Workflows, branch protection
  .githooks/ ........... Git enforcement hooks
  .morphism/ ........... Consumer config, schemas, hooks, policies
  apps/morphism/ ....... Next.js SaaS dashboard
  packages/ ............ 7 npm packages (TS)
  src/morphism/ ........ Python engine (category theory)
  docs/ ................ Active documentation (5 lanes — see Section 6)
  scripts/ ............. Governance enforcement
  tests/ ............... Python tests
  benchmarks/ .......... Performance benchmarks

Prefix Semantics

. (dot) = system/tool path. Commit only canonical, cross-contributor paths.
_ (underscore) = human-local workspace. Never committed.

What Never Gets Committed

/_*/              Human-local lanes (scratch, private)
/.venv/           Python virtual environment
/.turbo/          Turborepo cache
/.pytest_cache/   Pytest cache
/.vercel/         Vercel runtime
/site/            Generated docs (build artifact)
/output/          Generated reports

6. Documentation Standards

Source: ../standards.md

Content Type Taxonomy

Every doc declares exactly one type in frontmatter:

| Type | Authority | MUST/SHALL? | Location | |------|-----------|-----------|----------| | normative | Defines rules | Yes | docs/governance/ | | operational | Implements rules | No | Any allowed lane | | reference | Explains concepts | No | Any allowed lane | | historical | Records decisions | No | Any allowed lane |

Required Frontmatter

---
type: [normative|operational|reference|historical]
authority: [canonical|derived|non-normative]
audience: [agents, contributors, leadership, public]
last-verified: YYYY-MM-DD
---

Optional but recommended for canonical docs:

style: [D|E|C|B]
sources:
  - path/or/source
generated_from:
  - script/or/schema

A canonical document without required frontmatter is invalid.

SSOT Markers

Docs linked to SSOT atoms wrap canonical content:

<!-- SSOT:atom-id:begin -->
... canonical content ...
<!-- SSOT:atom-id:end -->

scripts/ssot_extract.py regenerates atom files from these markers. Never edit docs/ssot/atoms/*.md directly — they are generated.

Generated Region Markers

Hybrid docs (manual shell + generated inserts) use stable markers:

<!-- GENERATED:BEGIN commands -->
... generated content ...
<!-- GENERATED:END commands -->

Rules:

Only content outside generated markers may be edited manually
Manual edits inside generated regions are overwritten without notice
Generated markers must be balanced — unmatched BEGIN/END is a validation error
Enforced by scripts/docs_contract.py

File Naming

Docs: kebab-case.md
Governance: UPPER_SNAKE.md if already established
ADRs: NNNN-imperative-verb-phrase.md (e.g., 0001-use-category-theory-for-governance.md)
No date-prefixed filenames (YYYY-MM-DD-slug.md) in docs/. Dates belong in frontmatter.

Documentation Topology — Five Lanes

All human-authored documentation under docs/ lives in exactly one of five lanes. No exceptions. No new lanes without a Doctrine amendment.

docs/
├── governance/
│   ├── morphism-doctrine.md    <-- this file
│   ├── morphism-kernel.md
│   ├── invariants.md
│   ├── workflow.md
│   └── decisions/              <-- ADRs
├── architecture/
├── operations/
├── reference/
└── about/

| Lane | What Lives Here | Audience | |------|----------------|----------| | governance/ | Doctrine, kernel, invariants, policies, ADRs, enforcement rules | Agents, maintainers | | architecture/ | System design, data flow, repo maps, internal modeling, category theory docs | Contributors, architects | | operations/ | Setup, runbooks, CI/CD, deployment, release notes, session logs, backlog | Contributors, operators | | reference/ | Commands, schemas, config, integrations, security reference, glossary | All | | about/ | Positioning, public product narrative, pitch, getting-started for external users | External readers |

Lane boundaries:

governance/ = what constrains Morphism. Normative docs live here.
architecture/ = how Morphism works. Internal specs and design reasoning.
operations/ = how Morphism runs. Anything a contributor needs to do their job.
reference/ = lookup material. Generated docs, schemas, command tables.
about/ = for people who don't work in this repo. If the reader needs repo access to act on the content, it belongs elsewhere.

Forbidden as lanes: misc, general, shared, temp, guides, doctrine, notes. The docs/ssot/ subtree is generated — it is not a human-authored lane.

Migration Mapping

Current docs/ sprawl → target lanes:

| Current Folder | Target | |----------------|--------| | docs/pitch | docs/about/ | | docs/product | Split: narrative → about/, specs → architecture/ | | docs/public | docs/about/ | | docs/runbooks | docs/operations/ | | docs/security | docs/reference/ or docs/operations/ | | docs/integrations | docs/reference/ | | docs/math | docs/architecture/ or docs/governance/ | | docs/research | docs/architecture/ | | docs/shared | Remove or merge into nearest lane | | docs/superpowers | Remove | | docs/prompts | docs/reference/ | | docs/adr (old) | docs/governance/decisions/ | | docs/release-notes | docs/operations/ | | docs/legal | docs/reference/ | | docs/ssot/ | Keep — generated, not a human-authored lane |

Depth Rule

Applies only to human-navigable documentation under docs/.

Allowed:
  docs/<lane>/<file>.md                         (depth 3)
  docs/<lane>/<subtopic>/<file>.md               (depth 4)

Not allowed without exemption:
  docs/<lane>/<sub>/<sub>/<file>.md              (depth 5+)

Not enforced on .morphism/, generated artifacts, apps/, packages/, src/, or vendored layouts.

Current exemptions: none.

Manual vs Generated Content

| Content | Approach | |---------|----------| | Doctrine, architecture rationale, invariants, policies | Manual only | | Onboarding, runbooks, design decisions | Manual only | | Command references, schema tables, repo maps | Generated where feasible | | Package inventories, metrics, reports | Generated where feasible | | Reference docs with context + data | Hybrid (manual shell + generated inserts) |

Rule: generated content must use GENERATED markers (see above). Generated surfaces are declared in a registry at docs/reference/generated-registry.md.

7. Writing Style

Default: Hybrid Control Plane (Style D)

Direct. Visual. Every claim backed by a command or file path.

Tables for structured data, comparisons, inventories
ASCII diagrams for architecture, data flow, enforcement loops
Prose only when explaining why — keep it tight
Code blocks always specify language (python, bash, typescript)
Active voice, imperative for instructions
Present tense for descriptions
No marketing language in governance docs
RFC 2119 keywords (MUST, SHALL, SHOULD) only in normative docs

Style Variants

| Style | Name | Use For | Rules | |-------|------|---------|-------| | D | Control Plane | Default for all internal docs | Every claim → command, path, schema, or artifact | | E | Narrative | README, about/*, pitch | Problem → system → proof. End with demo. | | C | Codex | Invariants, kernel, repo maps | ASCII + formal notation. Wrap in explanation layer. | | B | Notebook | Onboarding intros, architecture rationale | Explain why once, then transition to Style D. |

Style A (Ops Manual) is absorbed into Style D. Its terseness and table orientation survive in runbooks and reference material.

| Doc Type | Default Style | |----------|---------------| | README | E | | About / pitch / public | E | | Governance / doctrine / policy | D + C overlays | | Architecture | D | | Runbook / operations | D (terse ops compression) | | Onboarding | B opening → D body | | Reference / command docs | D | | Invariants / kernel / maps | C inside D shell |

Rule: a canonical document has one dominant style. Mixed-style documents switch intentionally by section, not unconsciously.

Tone: Operator

Public and product copy stays:

GOOD                              AVOID
----                              -----
Restrained.................... Inflated rhetoric
Evidence-oriented............. Theory-first
Workflow-first................ Platform language
Concrete...................... Generic AI marketing

The Canonical Line

"The control plane for AI-assisted engineering."

This is the positioning. Not "governance framework." Not "platform." Not "product." The control plane.

Allowed variants:

"Morphism is the control plane for AI-assisted engineering."
"Morphism gives software teams policy enforcement, drift detection, audit trails, and rollout visibility for AI-assisted delivery."

Prohibited:

Abstract governance-only language
Math-first framing as headline
Observability-only framing
Trust-infrastructure language

8. Copy Invariants

Source: copy-invariants.md

These prevent narrative drift across surfaces.

| Rule | What It Governs | |------|----------------| | CI-COPY-1 | Category line must match canonical | | CI-COPY-2 | Workflow arc visible in all surfaces | | CI-COPY-3 | One rollout path: Free -> Pro -> Team -> Enterprise | | CI-COPY-4 | Evidence loop terms stay connected | | CI-COPY-5 | Claims ceiling: only what is implemented | | CI-COPY-6 | Demo parity with live dashboard | | CI-COPY-7 | Operator tone (no marketing puffery) | | CI-COPY-8 | Legal/pilot surfaces remain explicit |

Pricing Chain

packages/shared/src/plans.ts  (canonical)
         |
         v
docs/architecture/product/product-spec.md Section 3
         |
         v
All other docs, landing pages, dashboard

| Tier | Price | What Unlocks | |------|-------|-------------| | Evaluation | $0 | CLI validate + doctor, basic MCP | | Pro | $29/seat/mo | Facts, dashboard, advanced MCP | | Team | $79/seat/mo | Shared workspace, policy engine | | Enterprise | Custom | SSO, SLA, dedicated support |

9. Agent Behavior

Source: agent-kernel-prompt.md

Prime Directive

Preserve structure through transformation. When constraints are violated or information is insufficient, refuse clearly rather than guessing.

Required Inputs (Before Acting)

1. SSOT MAP .......... Canonical source for each domain
2. SCOPE BOUNDARY .... What's in, what's out
3. THE ONE THING ..... "The one thing is X. Done means Y."
4. TRACE REQUIREMENT . Commit, ticket, or ADR for every change

Mandatory Protocol

READ    -->  Load truth: AGENTS.md, SSOT.md, GUIDELINES.md
STATE   -->  Bind: one thing, done means, scope, non-goals
VERIFY  -->  Check I-1..I-7 explicitly
EXECUTE -->  Smallest change that satisfies "done means"
REFUSE  -->  When constraints fail (use refusal template)

Documentation-Specific Agent Rules

Agents operating on documentation must also:

Not create new top-level doc lanes (Section 6)
Not introduce duplicate authority for an existing domain
Update docs when modifying commands, schemas, structure, or behavior surfaces
Prefer editing canonical docs over creating new sibling explanations
Keep package-level READMEs short and pointer-oriented
Prefer generated outputs over manual duplication when a generation path exists
Surface drift explicitly rather than silently working around it
Not invent metrics or cite unsupported data

Rule: new documents must justify existence by mapping to a domain, a source-of-truth surface, and a maintenance path. If it can't, it shouldn't exist.

Refusal Template

Refusal:         [one sentence]
Violated Tenets: [I-# list]
Why:             [2-4 bullets]
Needed:          [minimum to proceed]
Alternatives:    [1-3 safe options]

Failure Modes to Avoid

| Anti-Pattern | Symptom | |-------------|---------| | Activity theater | High tool usage, zero net displacement | | Archaeology trap | Dozens of diagnostics before defining output | | Context loss | Each session restarts, reversing settled questions | | Authority sprawl | Creating new doc when canonical already exists | | Silent drift | Working around stale docs instead of flagging them |

10. Governance Enforcement Scripts

Source: scripts/

Core Enforcement

| Script | Enforces | Trigger | |--------|----------|---------| | validate_commit.py | I-3 Commit grammar | commit-msg hook + CI | | validate_branch.py | I-3 Branch naming | pre-push hook | | policy_check.py | All invariants | CI policy job | | ssot_verify.py | I-1, I-2 Registry hashes | CI drift-check (required) | | ssot_extract.py | I-1, I-2 Atom extraction | Manual | | docs_graph.py --check | I-4 Doc reachability | CI docs job | | maturity_score.py | I-5 Entropy tracking | CI integration-gate (required) | | verify_pipeline.py | I-7 Pipeline coverage | pre-push hook | | orphan_scan.py | I-6 Orphaned files | pre-push hook | | config_integrity.py | I-1, I-4 Config valid | CI | | governance_freshness.py | I-2 Doc staleness | CI | | dependency_health.py | I-5 Dependency audit | CI security | | docs_contract.py | I-1, I-2, I-4 Doc topology | CI docs job |

docs_contract.py — Documentation Topology Enforcement

Validates that docs/ conforms to the five-lane topology, authority model, and naming rules declared in Section 6.

| Check | What It Validates | Blocks Merge | |-------|-------------------|-------------| | Lane validation | All docs in allowed lanes; forbidden lanes rejected | Yes | | Depth validation | Max 4 levels from repo root under docs/ | Yes | | Naming validation | Kebab-case filenames, approved directory names | Yes | | Frontmatter validation | Required fields present on canonical docs | Yes | | Authority uniqueness | No two files claim canonical for same domain | Yes | | Forbidden lane detection | docs/doctrine/, docs/shared/, etc. rejected | Yes | | Generated region balance | Every GENERATED:BEGIN has matching END | Yes | | Link validation | Internal markdown links resolve | Warn | | Changed-surface awareness | Code changes flag missing doc updates | Warn | | Generated freshness | Generated docs newer than declared inputs | Warn |

Output model:

ERROR docs/reference/Commands.md: filename must be kebab-case
ERROR docs/doctrine/why-morphism.md: forbidden top-level lane "doctrine"
WARN  docs/operations/runbooks/: legacy lane — should migrate to docs/operations/

Exit: 0 = no errors, 1 = one or more errors. Warnings do not fail unless promoted by CI policy.

Migration policy: during lane consolidation, legacy lanes emit warnings. After migration cutoff, they become errors.

Validation Runbook

# Quick (pre-commit)
python scripts/policy_check.py --mode ci --explain
python scripts/verify_pipeline.py

# Full (pre-push)
python scripts/layout_check.py --check
python scripts/orphan_scan.py --check
python scripts/config_integrity.py --check
python scripts/governance_freshness.py --check
python scripts/ssot_verify.py
python scripts/docs_graph.py --check
python scripts/docs_contract.py --check

# Build + test
npx turbo typecheck && npx turbo lint && npx turbo test    # TypeScript
ruff check src/ tests/ && mypy src/ && pytest tests/        # Python

11. Drift Model

Every change goes through the governance loop:

1. DEFINE    .morphism/config.json declares invariants
2. CHECK     Engine runs checks (CLI, MCP, or CI)
3. EVIDENCE  Proof object written (what, when, pass/fail)
4. HEAL      Optional: auto-fix drift (Team+ tier)

Drift Classes

Drift is any mismatch. Four classes, each with an enforcement path:

| Class | Definition | Detected By | |-------|-----------|-------------| | Structural | Docs outside approved lanes, naming violations, depth violations | docs_contract.py | | Authority | Two+ files claim canonical for the same domain | docs_contract.py, ssot_verify.py | | Semantic | Canonical docs no longer match code, commands, schemas, or runtime | governance_freshness.py, PR review | | Generated | Generated docs stale relative to declared inputs | docs_contract.py, ssot_extract.py |

Rules:

Drift must be explicit. Silent drift is a defect.
Critical drift blocks merge.
Canonical-doc drift must not be deferred with "fix later."
If a change modifies structure, commands, schemas, or behavior surfaces, the corresponding docs must be updated in the same change.

Why Category Theory

The engine maps governance onto category theory. That's not decoration — it's what makes enforcement composable.

Morphism    := f : A -> B           (governance transformation)
Functor     := F : Cat -> Cat       (policy mapping across contexts)
Nat. Trans. := eta : F => G         (migration between policy versions)
Isomorphism := f . g = id, g . f = id  (reversible governance change)

A policy that works in one repo works the same way in CI, in MCP, and in the dashboard. The math guarantees it. If you change a policy, the engine can prove whether the change is compatible (natural transformation) or breaking (non-commuting square).

The result: teams get structural guarantees, not process checklists.

12. Operational Tenets

Derivation proofs: Paper 1 Section 10 (papers/agentic-mathematics/main.tex) · papers/bible/full-proofs.md

| # | Tenet | Maps To | Done Means | |---|-------|---------|-----------| | 1 | SSOT Integrity | I-1, I-2 | One canonical location; drift blocks merge | | 2 | Commit Grammar | I-3 | All commits match type(scope): subject | | 3 | Branch Naming | I-3, I-4 | All branches match type/description | | 4 | CI Gate Passage | I-5, I-6 | No merge without all gates passing | | 5 | Secret Zero | I-3, I-7 | No secret ever committed | | 6 | Docs Coverage | I-1, I-4 | Every doc reachable from nav; no orphans | | 7 | Registry Consistency | I-1, I-2 | Atom hashes match registry | | 8 | Dependency Freshness | I-5 | No critical vuln unaddressed >7 days | | 9 | Incident Readiness | I-3, I-4 | Runbook for every SEV1-SEV2 | | 10 | Maturity Tracking | I-5 | Score never regresses below threshold |

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/operations/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. The current scorer reports a 0-125 total across 12 categories and is enforced in CI with threshold 60. Failure: CI fails when the score falls below threshold.

Glossary of category-theory terms: glossary.md

13. Architectural Facts

Source: ../../SSOT.md

Agents must know these. Using incorrect assumptions is drift.

| Domain | Fact | Anti-Pattern | |--------|------|-------------| | Auth | Clerk (session-based) | JWT, NextAuth, custom auth | | Database | Supabase (PostgreSQL) | MongoDB, Prisma, raw SQL | | Hosting | Vercel (serverless) | Docker, K8s, long-running servers | | TS Build | tsup (all packages) | webpack, rollup, esbuild | | Monorepo | Turborepo | Running builds without turbo | | Shared pkg | Must build first (^build) | Importing without building | | Python | python (not python3) | python3 on Windows | | Python deps | uv | pip freeze, pipenv | | Line endings | LF (not CRLF) | Introducing CRLF | | Config sentinel | .morphism/config.json | Path-string matching | | Pricing source | packages/shared/src/plans.ts | Hardcoding elsewhere | | TS testing | vitest | jest, mocha | | Python linting | ruff + mypy | flake8, pylint |

14. Session Discipline

Starting a Session

Load governance: AGENTS.md -> SSOT.md -> GUIDELINES.md
Check open work: docs/operations/backlog.md
Check recent context: docs/operations/session-log.md
Bind scope: one thing, done means, in/out of scope
Execute: Read -> Verify -> Execute

Ending a Session

Commit all work incrementally (conventional commits)
Append dated entry to docs/operations/session-log.md
Update docs/operations/backlog.md (mark done, add new items)
Never leave uncommitted changes without a handoff note

Rate-Limit Awareness

If approaching context limits: (1) complete current atomic change, (2) run verification, (3) commit, (4) write handoff.

15. Release Discipline

Pre-Push Gate

The pre-push hook runs enforce-professional-standards.sh:

enforce_repo_conventions.py  -->  verify_pipeline.py
         |                              |
   orphan_scan.py             policy_check.py

All must pass to push.

Release Gate

When a publishable package's source changes, pre-push requires:

Version bump in package.json
Release note at docs/operations/release-notes/<pkg>-<ver>.md with frontmatter
Version index updated in docs/operations/release-notes/README.md

All three or push fails.

Publishable Packages

shared  sdk  agentic-math  mcp-server  cli  plugin-bundle  design-tokens

License

packages/* — MIT
src/morphism/ — BUSL-1.1 (change date 2030-03-25, change license MIT)
apps/morphism/ — BUSL-1.1

16. Scope and Limits

This Doctrine GOVERNS:

Governance state transitions     CI gate requirements
SSOT atom authority              Hook chain behavior
Commit and branch grammar        Documentation structure + topology
Agent behavior protocol          Naming conventions
Secret handling                  Dependency management
Maturity tracking                Release discipline
Writing style                    Copy invariants
Doc lane enforcement             Authority precedence
Drift classification             Generated-region policy

This Doctrine DOES NOT GOVERN:

Application business logic       UI/UX design decisions
Infrastructure topology          Third-party service config
Research methodology             Mathematical formalism

17. Amendment Process

Open PR modifying the normative source
Create or update ADR in docs/governance/decisions/ with rationale
Run SSOT extraction if atoms affected
Obtain review from CODEOWNERS
Merge only after drift-check and integration-gate pass

Amendments that weaken an invariant require documented exception rationale. Silent weakening is forbidden.

Doctrine Versioning

This Doctrine follows semantic versioning in its frontmatter:

Patch — typo fixes, clarification of existing rules, date updates
Minor — new rules, new enforcement requirements, new lane definitions
Major — authority model changes, structural reorganization, invariant changes

Lane Consolidation Migration

The documentation topology (Section 6) is in migration phase. During migration, legacy lanes emit warnings from docs_contract.py. After migration completes, they become errors.

Migration exit criteria:

All docs migrated into five canonical lanes
All deprecated folders removed or emptied
docs_contract.py enforces lane structure in merge-blocking mode
No non-canonical doc retains authority: canonical for a doc-governed domain

18. Quick Start

npm install -g @morphism-systems/cli
cd your-repo && morphism init && morphism validate

No account. No config wizard. 60 seconds to your first governance score.

$ morphism validate
  governance_docs: 15/15
  ci_coverage: 15/15
  total: 125/125
  Governance validation: PASS

The control plane earns trust before it asks for a credit card.

Morphism Doctrine

Morphism Doctrine

type: normative authority: canonical audience: [agents, contributors, founders] last-verified: 2026-03-25

Morphism Doctrine

1. Kernel — Seven Immovable Invariants

2. Protocol — Read, Verify, Execute

3. Architecture

Concept Map

System Architecture

Surfaces

Layer Boundaries

Python Core (src/morphism/)

TypeScript Packages (packages/)

4. Commit Grammar

Branch Types

5. Canonical Layout

Root Files

Authority Precedence

Directory Map

Prefix Semantics

What Never Gets Committed

6. Documentation Standards

Content Type Taxonomy

Required Frontmatter

SSOT Markers

Generated Region Markers

File Naming

Documentation Topology — Five Lanes

Migration Mapping

Depth Rule

Manual vs Generated Content

7. Writing Style

Default: Hybrid Control Plane (Style D)

Style Variants

Tone: Operator

The Canonical Line

8. Copy Invariants

Pricing Chain

9. Agent Behavior

Prime Directive

Required Inputs (Before Acting)

Mandatory Protocol

Documentation-Specific Agent Rules

Refusal Template

Failure Modes to Avoid

10. Governance Enforcement Scripts

Core Enforcement

docs_contract.py — Documentation Topology Enforcement

Validation Runbook

11. Drift Model

Drift Classes

Why Category Theory

12. Operational Tenets

Tenet 1: SSOT Integrity

Tenet 2: Commit Grammar

Tenet 3: Branch Naming

Tenet 4: CI Gate Passage

Tenet 5: Secret Zero

Tenet 6: Docs Coverage

Tenet 7: Registry Consistency

Tenet 8: Dependency Freshness

Tenet 9: Incident Readiness

Tenet 10: Maturity Tracking

13. Architectural Facts

14. Session Discipline

Starting a Session

Ending a Session

Rate-Limit Awareness

15. Release Discipline

Pre-Push Gate

Release Gate

Publishable Packages

License

16. Scope and Limits

17. Amendment Process

Doctrine Versioning

Lane Consolidation Migration

18. Quick Start

Python Core (`src/morphism/`)

TypeScript Packages (`packages/`)