Morphism Canonical Foundation Plan

Source: morphism-canonical-foundation-plan.md (ingested 2026-03-28)

Canonical Foundation Plan: Executive Summary

Current State Analysis

Problems Identified:

Scattered docs - Content in mobius/, products/, reference/, Desktop/ root
LLM bloat - Verbose, redundant explanations throughout
Unclear ownership - Morphism framework mixed with Möbius platform
Inconsistent naming - Mix of kebab-case, snake_case, PascalCase
No single source of truth - Multiple versions of same concepts

AGENTS.md Compliance: Currently following workspace AGENTS.md (pointer to morphism/AGENTS.md), but need canonical enforcement.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Proposed Solution

1. Repository Structure

Create: github.com/morphism-systems/morphism-core (canonical)

morphism-core/ ├── docs/ # MkDocs site │ ├── theory/ # Rigorous math (researchers) │ ├── concepts/ # Pedagogical (developers) │ ├── guide/ # Practical (users) │ ├── api/ # Auto-generated │ ├── notebooks/ # Executable (.ipynb) │ └── engineering/ # Short implementation notes ├── src/morphism/ # Python package ├── tests/ ├── examples/ ├── AGENTS.md # Development rules ├── GOVERNANCE.md # Naming standards └── pyproject.toml

Separate: github.com/mobius/mobius-platform (depends on morphism-core)

2. Documentation IA

Separation of Concerns:

theory/ - Complete proofs, formal (for mathematicians)
concepts/ - Intuitive explanations (for developers)
guide/ - Step-by-step tutorials (for users)
notebooks/ - Executable demos (for all)
engineering/ - Implementation notes (for engineers)

No mixing - Each audience gets dedicated content.

3. Naming Conventions

Files: kebab-case (convergence-proof.md)
Directories: kebab-case (fixed-point/)
Python: PEP 8 (governance_operator.py, class GovernanceOperator)
Git branches: type/description (feat/drift-detection)
Exception: Root meta-files (README.md, AGENTS.md)

4. Governance Process

AGENTS.md Enforcement:

GitHub Actions check PR compliance
ADRs required for architectural decisions
Pre-commit hooks validate naming
Definition of Done checklist

ADR Process:

Draft in docs/adr/drafts/
Discuss in GitHub issue
Accept → move to docs/adr/
Update index

5. Migration Plan (2 Weeks)

Week 1:

Day 1-2: Create GitHub org + repo, initialize structure
Day 3-4: Migrate & de-bloat mathematical content
Day 5: Set up governance (AGENTS.md, CI)

Week 2:

Day 6-7: Migrate code, consolidate duplicates
Day 8-9: Create executable notebooks
Day 10: Separate Möbius content
Day 11-14: Validation & cleanup

6. De-Bloat Strategy

Identify:

Duplicate explanations (same concept 3+ times)
LLM patterns ("As we can see...", "It's important to note...")
Incomplete drafts
Outdated content

Consolidate:

Keep most rigorous math
Keep clearest pedagogy
Keep complete examples
Remove rest

Questions for You

Before I proceed with creating the detailed plan document:

GitHub org name: morphism-systems or prefer different?
Python package name: morphism or morphism-core?
License: MIT (open) or proprietary for core?
Timeline: 2 weeks realistic or need adjustment?
Möbius org: Create new or use existing structure?

Should I create the full detailed plan document with:

Complete directory structures
Step-by-step migration instructions
De-bloat scripts
Governance enforcement code
ADR templates