Upgrade Guide¶

NON-NORMATIVE.

This guide covers upgrade steps for each @morphism-systems package and the Python core. All packages follow semver under BUSL-1.1.

Semver policy for this project:

Patch (0.x.Y) — no API changes, packaging or metadata fixes only. Safe to upgrade without code changes.
Minor (0.X.0) — additive API changes (new commands, new tools, new exports). Existing integrations continue to work unchanged.
Major (X.0.0) — breaking changes. Migration steps will be listed in the release note and in this guide.

All packages are currently in 0.1.x (pre-1.0). Minor bumps within 0.1.x may include behavioral changes documented in the release notes under docs/release-notes/.

Upgrading @morphism-systems/cli¶

Current version: v0.1.7

Installing or upgrading¶

npm install @morphism-systems/cli@latest

Verifying after upgrade¶

morphism doctor

Stable command API (since v0.1.1)¶

The following commands are stable across all v0.1.x releases:

morphism init — initialize governance scaffolding
morphism validate — run governance validation pipeline
morphism score — compute maturity score
morphism doctor — verify environment and configuration health

Added in v0.1.5¶

morphism policy list — list available governance policy packs with metadata
morphism policy validate <file> — validate a policy pack YAML against the schema
morphism proof — query proof witness history (--limit, --since, --json options)

No breaking changes have occurred within the v0.1.x series. The v0.1.6 and v0.1.7 releases were packaging-only (repository metadata, version banner alignment) with no command behavior changes.

Upgrading @morphism-systems/mcp-server¶

Current version: v0.1.9

Installing or upgrading¶

npm install @morphism-systems/mcp-server@latest

Connection protocol¶

The MCP server uses the Model Context Protocol (MCP) over stdio. Start it with:

morphism-mcp

Configure your MCP client (e.g. Claude, Cursor, VS Code) to connect via stdio transport.

Stable tool names (since v0.1.1)¶

Core governance tools available across all v0.1.x releases:

governance_validate — run full governance validation
maturity_score — compute maturity score with optional JSON output
convergence_report — drift and convergence metrics

Added in v0.1.7¶

policy_pack_list — list governance policy packs with rule counts and metadata
policy_pack_validate — validate a policy pack YAML against required fields
proof_witness_query — query proof witness history with limit and date filtering

No tool names have been removed or renamed within the v0.1.x series. The v0.1.8 and v0.1.9 releases were packaging-only with no tool behavior changes.

Upgrading @morphism-systems/design-tokens¶

Current version: v0.1.0

Installing or upgrading¶

npm install @morphism-systems/design-tokens@latest

Stable API¶

All six exported functions are stable: getTheme, getThemeNames, getThemeCSS, getThemeTailwind, hslToHex, getThemeHex. See Design Tokens Reference for full signatures.

CSS variable format¶

getThemeCSS emits raw HSL channel strings (e.g. --accent: 270 100% 74%;). Reference tokens in CSS as:

color: hsl(var(--accent));
color: hsl(var(--accent) / 0.7); /* alpha variant */

This matches Tailwind's hsl(var(--token) / alpha) convention. If you were previously hardcoding --accent: hsl(270, 100%, 74%) or similar, update your references to wrap at the call site rather than at the definition.

Migrating from hardcoded CSS variables to generated variables¶

If your project used manually written CSS custom properties and you are moving to getThemeCSS:

Replace your manual :root { ... } block with output from getThemeCSS.
Update all var(--my-old-name) references to use the canonical token names (--bg, --surface, --accent, etc.).
Wrap all color variable references in hsl() at the call site.
Optionally add a prebuild script to regenerate the CSS on each build (see Design Tokens Reference for an example).

Tailwind preset¶

If you used getThemeTailwind, colors in the returned config are already wrapped in hsl() — do not double-wrap.

Upgrading @morphism-systems/shared¶

Current version: v0.1.2

Installing or upgrading¶

npm install @morphism-systems/shared@latest

Stable exports¶

@morphism-systems/shared uses path-based subpath exports. Available subpaths:

Import path	Contents
`@morphism-systems/shared`	Re-exports from all submodules
`@morphism-systems/shared/utils`	`cn`, `formatDate`, `formatRelative`, `riskColor`, `statusColor`
`@morphism-systems/shared/types`	Shared TypeScript types
`@morphism-systems/shared/schemas`	Zod validation schemas
`@morphism-systems/shared/governance`	Governance utilities
`@morphism-systems/shared/ai`	AI/LLM helpers
`@morphism-systems/shared/stripe`	Stripe billing helpers
`@morphism-systems/shared/supabase/server`	Supabase server-side client
`@morphism-systems/shared/rate-limit`	Rate limiting utilities
`@morphism-systems/shared/storage`	File storage utilities
`@morphism-systems/shared/encryption`	Encryption utilities
`@morphism-systems/shared/csrf`	CSRF protection

Key utilities¶

import { cn, formatDate, formatRelative } from "@morphism-systems/shared/utils";

cn("px-4 py-2", condition && "bg-accent");  // clsx + tailwind-merge
formatDate(new Date());      // "Mar 12, 2026"
formatRelative(new Date());  // "just now"

No breaking changes within v0.1.x. v0.1.2 added the governance subpath export.

General upgrade steps¶

# Upgrade all @morphism-systems packages at once
npm install \
  @morphism-systems/cli@latest \
  @morphism-systems/mcp-server@latest \
  @morphism-systems/design-tokens@latest \
  @morphism-systems/shared@latest

# Verify CLI
morphism doctor

# Verify TypeScript compilation
npx turbo typecheck

# Verify tests
npx turbo test

After upgrading design-tokens, if you use a prebuild script to generate CSS, re-run it:

node apps/morphism/scripts/generate-tokens-css.mjs

Python core upgrade¶

The Python governance core (src/morphism/) is installed from the monorepo root, not from npm.

Installing / upgrading¶

pip install -e ".[dev]"

Verifying¶

ruff check src/ tests/
mypy src/
pytest tests/

Governance scripts¶

After any Python core upgrade, verify all governance scripts still pass:

python scripts/verify_pipeline.py

This runs the full 7-check pipeline: SSOT extract/verify, docs sync, docs graph, maturity score, layout check, and policy check.