Morphism Repo Cleanup Plan

planactive

Morphism Repo Cleanup Plan

Safe execution plan for Morphism repository cleanup — collapsing 18 doc lanes into 5 canonical lanes, removing generated caches, consolidating root files, and updating gitignore. Estimated 30 minutes total.

Provenance

Ingested from Morphism/repo-cleanup-plan.md on 2026-03-28.

Phases

Phase 0: Safety Net (2 min)

Create cleanup branch (chore/repo-cleanup), tag current state (pre-cleanup-YYYYMMDD). Never work on main.

Phase 1: Audit (5 min, read-only)

Inventory docs files, root markdown, empty dirs, stale files (90+ days), large/binary files, duplicate authority files, cache dirs, orphan docs, git-ignored but tracked files.

Phase 2: Nuke Safe Targets (3 min)

Remove generated caches that regenerate on build: .turbo/, .pytest_cache/, __pycache__/, .mypy_cache/, .ruff_cache/, .next/, apps/morphism/.next/, site/, output/, dist/, coverage/, .vercel/, all .pyc files, empty directories.

Phase 3: Collapse Docs Lanes (15 min)

Target 5 canonical lanes per Doctrine:

| Source Lane | Target | Action | |-------------|--------|--------| | docs/pitch | docs/about | Move all | | docs/product | Split: docs/about + docs/architecture | Per-file decision | | docs/public | docs/about | Move all | | docs/runbooks | docs/operations | Move all | | docs/release-notes | docs/operations | Move all | | docs/adr | docs/governance/decisions | Move all | | docs/integrations | docs/reference | Move all | | docs/prompts | docs/reference | Move all | | docs/security | docs/reference | Move all | | docs/legal | docs/reference | Move all | | docs/math | docs/architecture | Move all | | docs/research | docs/architecture | Move all | | docs/shared | Remove | Junk lane | | docs/superpowers | Remove | Junk lane |

Phase 4: Root File Cleanup (5 min)

  • Keep: README.md, AGENTS.md, SSOT.md
  • Demote: DOCKER.md → docs/operations/, LESSONS.md → docs/operations/, CONTRIBUTING.md → docs/operations/
  • Keep at root: CLAUDE.md (tool adapter per Doctrine Section 4.2)

Phase 5: Verify Final Layout (2 min)

Confirm exactly 5 lanes + DOCTRINE.md, max 4 levels deep, no files outside lanes.

Phase 6: Update .gitignore (1 min)

Add coverage for all cache directories and /_*/ for human-local lanes.

Phase 7: PR and Merge

Push chore/repo-cleanup branch, open PR documenting: collapse 18 lanes → 5, remove caches, consolidate root files.

What NOT to Touch

  • .morphism/ — config and policies
  • src/ — Python engine code
  • packages/ — TypeScript packages
  • apps/ — Next.js dashboard
  • scripts/ — enforcement scripts
  • tests/ — test suites
  • docs/ssot/atoms/ — generated, managed by ssot_extract.py

Risk Assessment

| Phase | Time | Risk | |-------|------|------| | Safety net | 2 min | Zero | | Audit | 5 min | Zero (read-only) | | Nuke caches | 3 min | Zero (all regenerate) | | Collapse lanes | 15 min | Low (git mv preserves history) | | Root cleanup | 5 min | Low | | Verify | 2 min | Zero | | Gitignore + PR | 1 min | Zero |

Only risk: Phase 3 lane collapse may break internal links. Fix with grep after moving.