Morphism Product Spec
Morphism Product Spec
Source: product-spec.md (ingested 2026-03-28)
type: reference authority: non-normative audience: [leadership, agents, contributors] last-verified: 2026-03-25 scope: product
Morphism Product Spec
NON-NORMATIVE.
The control plane for AI-assisted engineering.
North star: A developer installs the CLI, sees their governance health in 15 minutes, and upgrades when they need drift detection, observability, and control across repos.
Canonical pricing: packages/shared/src/plans.ts
Market analysis: docs/architecture/research/market-readiness-assessment.md
1. The Problem: Context Contamination
When AI agents rely on global caches, cross-repo memory, or unstructured file searches, they lose the boundary of the current project. The agent confidently generates code or architectural decisions that belong to Project A while working in Project B. The real danger isn't obvious failure — it's plausible but incorrect execution that slowly degrades a codebase because the AI is mashing together incompatible truths from the user's ecosystem.
This is Context Contamination (or "Context Bleed"), and it is the core problem morphism solves.
How Morphism Makes Context Contamination Recoverable
Layer 1 — Contextual Agent Boundaries via MCP.
When an agent enters a repo, Morphism's MCP server feeds it the .morphism/ config
specific to that repository. The agent sees the rules, architecture, and state relevant
to the exact repo it is operating in. This prevents "Alawein" context from bleeding into
a "OptiQAP" session.
Honest scope: MCP is a delivery mechanism, not an access control boundary. It feeds the agent repo-scoped context, but it cannot evict contaminated prior turns from the conversation or suppress the model's own weights. The boundary is advisory, not enforced at the protocol level.
Layer 2 — Explicit State Over Fuzzy Memory.
AI tools often guess intent by scraping all available files, which dilutes focus.
Morphism relies on explicit, version-controlled governance. By defining repository rules
locally in .morphism/, the system creates a Single Source of Truth (SSOT). The agent
reads explicit, repo-scoped constraints directly from the control plane instead of pulling
from a global cache. Context-switching commands (/switch-to-morphism,
/switch-to-alawein) reset agent state to the target repo's boundary.
Layer 3 — Continuous Output Validation (the strongest layer).
Even if an agent's context does get contaminated — e.g., the user pastes code from
another project, confusing the AI — Morphism acts as the safety net. If the confused
agent attempts to implement a pattern that violates the current repo's policy,
morphism validate catches the drift in CI and blocks the merge. This layer is
genuinely robust because it is independent of how the agent got confused.
The Paradigm Shift
The conventional approach is to perfectly tune the AI's "memory" so it doesn't get confused. Morphism says: we don't trust the agent's memory. Instead, we give the agent strict, repo-scoped boundaries (MCP) and mathematically validate its output against a local policy file (CLI/CI) before anything is merged.
Two Types of Contamination
| Type | Description | Morphism Coverage | |------|-------------|-------------------| | Policy bleed | Agent applies rules from the wrong repo (wrong branch naming, wrong auth pattern) | Caught well by Layers 1-3 | | Semantic/factual bleed | Agent carries assumptions across repos ("auth uses JWT here" when it uses sessions) | Partially caught — requires richer SSOT (see roadmap) |
Policy bleed produces rule violations that morphism validate catches directly.
Semantic bleed produces syntactically valid, policy-compliant, but semantically wrong
code. Closing this gap requires SSOT that encodes not just rules but current
architectural facts, so the validator can say "this code assumes JWT but this repo
uses sessions."
Prior validation: Project Isolation Validation Report (2026-03-21) — 6/6 isolation tests passed across Morphism, Alawein, and Blackmalejournal.
2. User Personas
| Persona | Role | Pain | Buys | |---------|------|------|------| | Dev | Individual IC, 1-3 repos | "Is my repo healthy? Am I drifting?" | Free | | Lead | Team lead, 5-20 engineers | "I can't see governance across repos or agents" | Pro ($29/seat/mo) | | Director | VP Eng / compliance owner | "Auditors need evidence. I need a control plane." | Team ($79) / Enterprise (custom) |
Anti-personas: Solo devs with no governance need. Non-technical compliance teams (Vanta/Drata serve them). Teams using zero AI agents.
3. Product Surface Map
What each persona can do on each surface at each tier.
CLI (morphism / @morphism-systems/cli)
| Command | Free | Pro | Team | Enterprise |
|---------|------|-----|------|-----------|
| init | Y | Y | Y | Y |
| validate | Y | Y | Y | Y |
| score | Y | Y | Y | Y |
| doctor | Y | Y | Y | Y |
| status | Y | Y | Y | Y |
| entropy (measure/compare/report) | Y | Y | Y | Y |
| diff | - | Y | Y | Y |
| proof list/verify | - | - | Y | Y |
| scaffold (monorepo/package/governance/tier/legacy) | - | - | Y | Y |
| heal --dry-run | - | - | partial | full |
| heal | - | - | partial | full |
| policy list/validate | Y | Y | Y | Y |
| plugin (list/install/remove/search) | Y | Y | Y | Y |
| learn (summary/rules/pairs) | Y | Y | Y | Y |
| sync-registry | Y | Y | Y | Y |
Dashboard (morphism.systems)
| Feature | Free | Pro | Team | Enterprise | |---------|------|-----|------|-----------| | Overview (score, status) | Y | Y | Y | Y | | Agent registry | - | Y | Y | Y | | Drift charts + kappa trends | - | Y | Y | Y | | Team governance views | - | - | Y | Y | | Multi-repo governance | - | - | Y | Y | | Policy management | - | - | Y | Y | | Audit log export | - | - | Y | Y | | Proof witness browser | - | - | - | Y | | SSO / SAML | - | - | - | Y | | Assessments | Y | Y | Y | Y | | Skills browser | Y | Y | Y | Y | | Billing / plans | Y | Y | Y | Y | | Settings (general/workspace) | Y | Y | Y | Y |
MCP Server (@morphism-systems/mcp-server)
| Tool | Free | Pro | Team | Enterprise |
|------|------|-----|------|-----------|
| governance_validate | Y | Y | Y | Y |
| governance_score | Y | Y | Y | Y |
| governance_status | Y | Y | Y | Y |
| entropy_* (measure/compare/report) | Y | Y | Y | Y |
| compute_kappa | - | Y | Y | Y |
| compute_delta | - | Y | Y | Y |
| categorical_* (functor, NT, drift, kappa) | - | Y | Y | Y |
| governance_review | - | Y | Y | Y |
| governance_gate | - | Y | Y | Y |
| governance_scan | - | Y | Y | Y |
| governance_stats | - | Y | Y | Y |
| governance_diff | - | Y | Y | Y |
| governance_heal | - | - | partial | full |
| policy_pack_list/validate | - | - | Y | Y |
| ssot_verify | - | - | Y | Y |
| proof_* (witness_query, verify) | - | - | - | Y |
| template_apply | - | - | Y | Y |
| workspace_audit | - | Y | Y | Y |
| plugin_list/tools | Y | Y | Y | Y |
| learning_summary | Y | Y | Y | Y |
| drift_lessons_query | - | Y | Y | Y |
| governance_pairs_query | - | Y | Y | Y |
| governance_context | Y | Y | Y | Y |
| governance_facts | - | Y | Y | Y |
SDK (@morphism-systems/sdk)
| Method | Free | Pro | Team | Enterprise |
|--------|------|-----|------|-----------|
| validate() | Y | Y | Y | Y |
| runGovernanceCheck() | Y | Y | Y | Y |
| computeKappa() | - | Y | Y | Y |
| checkDrift() | - | Y | Y | Y |
| getProofWitnesses() | - | - | - | Y |
4. Conversion Triggers
What makes a user upgrade. These are the product moments that drive revenue.
| Transition | Trigger | Product Moment |
|------------|---------|----------------|
| Free -> Pro | "I want to see drift over time, not just one snapshot" | User runs validate 3+ times and wishes they could see the trend |
| Free -> Pro | "My AI agent should check governance before acting" | User discovers MCP server but kappa is Pro-gated |
| Pro -> Team | "I need this across all our repos, not just mine" | Lead wants multi-repo view or audit log for compliance review |
| Pro -> Team | "My team needs shared policies" | Multiple devs using Morphism independently, policies diverge |
| Team -> Enterprise | "Auditors need formal evidence" | Compliance team asks for proof witnesses mapped to SOC 2 controls |
| Team -> Enterprise | "We need SSO and on-prem" | Security team requires SAML, data residency |
| Any -> Pro/Team | "My AI agent keeps mixing up my repos" | User experiences context contamination across projects; wants MCP boundaries + validation |
5. Feature Placement: Lessons, Enforcers, Subagents
Where the planned features fit in the product and pricing.
Lessons (/lesson-* commands)
Tier: FREE. Rationale: lessons are onboarding and adoption tooling. They teach users the governance framework, making them invested in the mental model. More invested users are more likely to upgrade. Gating lessons behind a paywall would slow adoption.
| Lesson | Invariant | Status |
|--------|-----------|--------|
| /lesson-drift | I-2 | Done |
| /lesson-governance | I-4 | Done |
| /lesson-hallucination | General | Done |
| /lesson-prompts | General | Done |
| /lesson-tokens | General | Done |
| /lesson-ssot | I-1 | Done |
| /lesson-observability | I-3 | Done |
| /lesson-entropy | I-5 | Done |
| /lesson-refusal | I-6 | Done |
| /lesson-authority | I-7 | Done |
| /lesson-tenets | T1-T10 | Done |
Enforcer Hooks (automatic, background)
Tier: FREE. Rationale: automated enforcement makes governance sticky. Once a team has hooks running, switching away is painful. This is the lock-in mechanism for the free tier — not a paywall, but habit formation.
| Hook | Trigger | Script |
|------|---------|--------|
| SSOT check | Edit docs/ssot/ | ssot_verify.py |
| Commit grammar | Pre-commit | validate_commit.py |
| Branch naming | Pre-push | validate_branch.py |
| Docs coverage | Edit docs/ | docs_graph.py --check |
| Credential scan | Pre-commit | scan-credentials.sh |
| Layout check | Edit project structure | layout_check.py --check |
Enforcer Subagents (on-demand, intelligent)
Tier: PRO. Rationale: subagents don't just run a script — they interpret the result, explain what's wrong, and suggest fixes. This is the intelligence layer that justifies the Pro price. Free users get pass/fail; Pro users get guided remediation.
| Subagent | What It Does | Underlying Script |
|----------|-------------|-------------------|
| ssot-enforcer | Explains which SSOT atom drifted, why, and proposes fix | ssot_verify.py + ssot_extract.py |
| drift-enforcer | Analyzes drift report, categorizes severity, suggests heal actions | policy_check.py + drift scanner |
| scope-enforcer | Detects scope creep in a changeset, recommends commit splitting | scope_check.py |
| entropy-enforcer | Measures entropy change from a PR, flags regressions | maturity_score.py |
| docs-enforcer | Finds orphan docs, broken links, missing nav entries | docs_graph.py + orphan_scan.py |
Learning Subagents (pattern detection, improvement)
Tier: TEAM / ENTERPRISE. Rationale: learning subagents observe patterns across the team and suggest structural improvements. This requires org-wide data (multi-repo, multi-agent) which is the Team value prop. Enterprise gets full autonomous healing.
| Subagent | What It Does | Tier |
|----------|-------------|------|
| drift-learner | Detects recurring drift patterns, suggests policy additions | Team |
| tenet-learner | Proposes new tenets based on observed violations | Team |
| heal-agent | Autonomous governance remediation (partial) | Team |
| heal-agent (full) | Full self-healing with proof witnesses | Enterprise |
| compliance-mapper | Maps proof witnesses to SOC 2 / NIST controls | Enterprise |
6. Revenue Architecture
FREE (acquisition) PRO (retention) TEAM (expansion) ENTERPRISE (high-touch)
CLI installs Dashboard stickiness Multi-repo views Compliance evidence
MCP discovery Drift alerts over time Audit log exports Proof witnesses
Lesson adoption Enforcer subagents Shared policies Custom tenets
Enforcer hooks Kappa trends Learning subagents SSO, on-prem
Agent registry Team governance Dedicated SLA
Value: "Is it healthy?" Value: "How is it Value: "Govern the Value: "Prove it to
trending?" whole org" auditors"
7. Critical Path
What must work end-to-end before anything else matters, in priority order.
| # | What | Status | Blocker |
|---|------|--------|---------|
| 1 | CLI install -> validate -> score | Done | - |
| 2 | MCP server in Claude/Cursor | Done | - |
| 3 | Dashboard signup (Clerk) -> see data | Partial | Supabase schema, data flow |
| 4 | Stripe checkout -> plan stored in DB -> feature gates unlock | Partial | End-to-end testing needed |
| 5 | CI integration -> drift reports -> dashboard alerts | Planned | API endpoint + webhook |
| 6 | Enforcer hooks wired in .claude/settings.json | Planned | Config only |
| 7 | Enforcer subagents (Pro value) | Planned | Prompt engineering |
| 8 | Learning subagents (Team value) | Planned | Org-wide data pipeline |
Items 1-4 are the core product loop. Nothing after item 4 matters until a user can: install CLI -> sign up -> upgrade -> get gated features unlocked.
8. Known Gaps and Decisions Needed
| Gap | Impact | Decision Needed |
|-----|--------|-----------------|
| Feature gating is mostly UI-only | Users could bypass gates via API | Implement requirePlan() in all API routes |
| Billing mode: per-seat vs per-org | market-readiness says per-org, plans.ts says per-seat | Align to one model |
| Enterprise pricing floor | $79/mo (current) vs $199-500/mo (recommended) | Set floor price |
| ADR-PRICING-002 referenced but missing | No formal pricing decision record | Write the ADR |
| entropy gated as Pro but CLI runs it free | Inconsistent gating | Decide: free in CLI, Pro in API/dashboard? |
| No usage telemetry | Can't measure conversion triggers | Add anonymous CLI usage events (opt-in) |
| Semantic bleed not caught by policy validation | Agent carries false architectural assumptions across repos; code is policy-compliant but semantically wrong | Extend SSOT to encode architectural facts (auth method, data layer, API style) so validators can catch semantic mismatches |
| MCP boundary is advisory, not enforced | MCP delivers repo-scoped context but cannot evict contaminated prior turns | Document honestly; explore conversation-reset mechanisms in context-switching commands |
9. How Features Connect to Payment
User installs CLI (free)
|
v
Runs `morphism validate` -- sees score, basic drift (free)
|
v
Wants kappa trend over time -- UPGRADE TO PRO ($29/seat/mo)
| |
| v
| Dashboard: drift charts, kappa trends
| MCP: categorical tools, kappa
| CLI: `morphism diff`
| Enforcer subagents: explain + fix
|
v
Team adopts, needs shared policies -- UPGRADE TO TEAM ($79/seat/mo)
| |
| v
| Multi-repo governance
| Audit log export
| Policy management
| Learning subagents
| `morphism proof` + `scaffold`
|
v
Auditors need evidence -- UPGRADE TO ENTERPRISE (custom)
|
v
Proof witnesses -> SOC 2 mapping
Full self-healing
SSO / SAML / on-prem
H1 cohomology analysis
Dedicated support (4h SLA)