Roadmap Phases

NON-NORMATIVE.

Four phases to take morphism-systems from green-repo to production product. Execute in order (1-2-3-4); Phase 4 can run in parallel with Phase 3.

---

Phase 1 — Harden for Users

Do this first — it's the foundation everything else builds on.

/bootstrap

## Task: Harden morphism-systems for real users

Work through these in order, committing after each:

### 1. Auth scaffolding
- Add a Supabase Auth integration to apps/morphism (sign-up, sign-in, sign-out)
- Use @supabase/ssr for Next.js 15 server components
- Add middleware.ts for route protection (protect /beta/* routes)
- Add a minimal /auth/login and /auth/callback page

### 2. API route hardening
- Add rate limiting middleware to all API routes (use upstash/ratelimit or a simple in-memory limiter)
- Validate request bodies with zod on any POST/PUT routes
- Ensure all API routes return consistent error shapes: { error: string, code: string }

### 3. E2E staging smoke tests
- Create tests/e2e/ with playwright or a simple fetch-based test suite
- Tests should hit the staging URL (from env var STAGING_URL)
- Cover: health endpoint, auth flow (sign-up, sign-in, sign-out), protected route redirect, API error shapes
- Add an npm script: "test:e2e": "npx playwright test" (or node-based runner)

### 4. Sentry validation
- Trigger a test error on staging and confirm it appears in Sentry
- Add a /api/debug-sentry route (dev/staging only) that throws a test error
- Verify source maps are uploading (check Sentry release artifacts)

### 5. Verify
- Run full test suite (npx turbo test && pytest tests/)
- Run governance checks (python scripts/verify_pipeline.py)
- Commit with conventional commits, one per logical unit

/handoff when done.

---

Phase 2 — Build Out the App

/bootstrap

## Task: Build the governance dashboard in apps/morphism

### 1. Dashboard page (/dashboard)
- Protected route (redirect to /auth/login if unauthenticated)
- Layout: sidebar nav + main content area
- Use the design tokens from apps/morphism/src/styles/tokens.ts

### 2. Governance overview panel
- Call the Python engine via the python_bridge (or shell out to `morphism validate`)
- Display: maturity score (gauge/progress), kappa coefficient, drift status
- Show last proof witness timestamp and link to details

### 3. Governance history chart
- Store governance run results in Supabase (table: governance_runs with columns: id, timestamp, maturity_score, kappa, drift_count, proof_path)
- Line chart showing maturity score over time (use recharts or a lightweight chart lib)

### 4. Drift detail view (/dashboard/drift)
- List current drift items from drift_detector.py output
- Show severity, file, description, suggested fix
- Button to trigger healing (calls morphism heal --dry-run, shows preview)

### 5. Proof explorer (/dashboard/proofs)
- List proof witnesses from .morphism/proofs/
- Click to view full JSON with syntax highlighting
- Show proof metadata: timestamp, kappa, functor path

### 6. Verify
- All new components have basic vitest tests
- Pages render without errors
- Full test suite passes
- Governance checks pass

/handoff when done.

---

Phase 3 — Grow the Ecosystem

/bootstrap

## Task: Improve CLI, MCP servers, and external documentation

### 1. CLI enhancements (packages/cli)
- Add `morphism init` command: scaffolds .morphism/ config, AGENTS.md template, SSOT.md template, and pre-commit hook into a target repo
- Add `morphism status` command: one-line summary of maturity, drift count, last proof
- Add `morphism diff` command: show governance delta since last commit (wraps drift_detector.py)
- Add tests for each new command

### 2. MCP server enhancements (packages/mcp-server)
- Add tool: governance_status — returns current maturity, kappa, drift summary
- Add tool: governance_diff — returns drift delta since last commit
- Add tool: governance_heal — runs healing in dry-run mode, returns proposed fixes
- Add tests for each new tool

### 3. External quickstart guide
- Create docs/public/quickstart.md: step-by-step for adopting morphism in an existing repo
- Cover: npm install, morphism init, first audit, interpreting results
- Add to mkdocs.yml public nav

### 4. Verify
- CLI: `npx @morphism-systems/cli doctor` still works
- MCP: existing + new tool tests pass
- Full test suite passes
- Governance checks pass

/handoff when done.

---

Phase 4 — Deepen the Math

/bootstrap

## Task: Extend the category theory engine and add property-based testing

### 1. New morphism types (src/morphism/engine/)
- Add Isomorphism (morphism with inverse, verify round-trip)
- Add Endomorphism (morphism from object to itself)
- Add composition validation: verify associativity for chains of 3+ morphisms
- Tests for each new type

### 2. New proof strategies
- Add inductive proof strategy: prove property holds for base case + inductive step
- Add contrapositive strategy: prove by negation
- Integrate into governance_loop so proofs can use multiple strategies
- Tests for each strategy

### 3. Property-based testing (tests/test_properties.py)
- Use hypothesis library
- Properties to test:
  - Functor preserves composition: F(g . f) = F(g) . F(f)
  - Functor preserves identity: F(id_A) = id_F(A)
  - Natural transformation naturality squares commute
  - Morphism composition is associative
  - Kappa coefficient is bounded [0, 1]
- Generate random morphisms, functors, natural transformations as test inputs

### 4. Benchmarks (benchmarks/)
- Benchmark governance_loop on corpora of 10, 50, 100, 500 documents
- Benchmark CechComplex construction at varying cover sizes
- Benchmark proof generation time by strategy
- Store results for ASV tracking

### 5. Verify
- All new tests pass (pytest tests/)
- Property tests run with at least 100 examples each
- Benchmarks complete without error
- Full governance pipeline passes

/handoff when done.