# Migration Guide — MORPH-SPEC v2.x → v3.0

This guide covers migrating an existing MORPH-SPEC v2.x installation to v3.0.0.

---

## What Changes in v3.0

### state.json Schema (breaking)

v3.0 adds required fields to `state.json`:

| Field | Where | Description |
|-------|-------|-------------|
| `version` | root | Updated from `2.x.x` → `3.0.0` |
| `threads` | root | New `{}` object for thread tracking |
| `features.*.threadMetrics` | per-feature | Thread statistics object |
| `features.*.trustConfig` | per-feature | Trust level and override |
| `features.*.contextBundles` | per-feature | Array of context bundle references |
| `features.*.checkpoints` | per-feature | Array (if not already present) |
| `metadata.migratedAt` | metadata | Migration timestamp |

### agents.json (additive, non-breaking)

v3.0 adds 4 new agents. Existing agents are preserved unchanged:
- `vector-search-expert` — Azure AI Search + RAG
- `thread-orchestrator` — Parallel execution coordination
- `context-optimizer` — Token efficiency
- `observability-expert` — App Insights, Serilog, OpenTelemetry

### New CLI Commands

All new — no existing commands changed:
- `morph-spec threads [list|status|kill|analytics|wait-all|wait-any]`
- `morph-spec trust [status|set|history|auto-calculate|clear]`
- `morph-spec migrate [status|v2-to-v3|rollback-to-v2]`
- `morph-spec hop [list|render]`
- `morph-spec analytics [feature|context|project]`
- `morph-spec core-four`
- `morph-spec parallel [plan|run|status]`
- `morph-spec fusion [run|aggregate]`
- `morph-spec mcp [optimize|list]`
- `morph-spec micro-agent [create|list|show]`
- `morph-spec prime`

### New Framework Files

83 new files added across:
- `src/lib/` — 15 new library files
- `src/commands/` — 11 new command files
- `src/migrations/` — 2 migration scripts
- `framework/templates/meta-prompts/` — 12 HOP templates
- `framework/standards/` — 23 new standards files
- `framework/workflows/configs/zero-touch.json`
- `test/integration/` — 4 integration test suites
- `docs/next-generation/` — 6 documentation files

---

## Prerequisites

Before migrating:

- [ ] MORPH-SPEC CLI version ≥ 4.2.0 (`morph-spec --version`)
- [ ] Node.js ≥ 18 (`node --version`)
- [ ] Git working tree clean (`git status`)
- [ ] Current `.morph/state.json` is valid JSON

```bash
# Verify CLI version
morph-spec --version
# Should show: 4.2.0 or higher

# Check migration status before starting
morph-spec migrate status
```

---

## Step-by-Step Migration

### Step 1: Check current state

```bash
morph-spec migrate status
```

Expected output:
```
📊 Migration Status

state.json
  Version:      ⚠ Needs migration (current: v2.1.1)
  Needs update: Yes
  Has backup:   No

agents.json files
  ⚠ .morph/config/agents.json
    Missing: vector-search-expert, thread-orchestrator, context-optimizer, observability-expert
```

### Step 2: Run the migration

```bash
morph-spec migrate v2-to-v3
```

This will:
1. Backup `state.json` → `state.v2.backup.json`
2. Update `state.json` version to `3.0.0`
3. Add `threads: {}` to root
4. Add `threadMetrics`, `trustConfig`, `contextBundles` to each feature
5. Add 4 new agents to each `agents.json` file found

Expected output:
```
🚀 Migrating MORPH-SPEC v2 → v3.0

Step 1: Migrating state.json (2.1.1 → 3.0.0)
  ✓ Migration complete: v2.1.1 → 3.0.0
  Backup: .morph/state.v2.backup.json
  Changes:
    • Version: 2.1.1 → 3.0.0
    • Added: threads: {}
    • Feature "user-auth": added threadMetrics, trustConfig, contextBundles, checkpoints
    • Updated metadata.lastUpdated and migratedAt

Step 2: Updating agents.json files
  ✓ .morph/config/agents.json: added vector-search-expert, thread-orchestrator, context-optimizer, observability-expert
  – stacks/blazor-azure/.morph/config/agents.json: already up to date

✅ Migration complete! MORPH-SPEC is now on v3.0.0
```

### Step 3: Verify migration

```bash
morph-spec doctor --v3
```

All checks should pass:
```
✅ 8/8 — All v3.0 checks passed!
```

### Step 4: Commit the migration

```bash
git add .morph/state.json .morph/config/agents.json
git commit -m "chore(migration): upgrade MORPH-SPEC state to v3.0.0"
```

---

## Rollback

If the migration causes issues, restore the v2 backup:

```bash
morph-spec migrate rollback-to-v2 --force
```

This restores `state.v2.backup.json` → `state.json`.

**Note:** `agents.json` changes are NOT rolled back (additive only, safe to keep).

---

## Manual Migration (Fallback)

If the automated migration fails, update `state.json` manually:

```json
{
  "version": "3.0.0",
  "threads": {},
  "features": {
    "your-feature": {
      "threadMetrics": {
        "totalThreads": 0,
        "completedThreads": 0,
        "failedThreads": 0,
        "parallelBatches": 0
      },
      "trustConfig": {
        "level": "low",
        "passRate": 0,
        "lastCalculated": "2026-02-19T10:00:00.000Z"
      },
      "contextBundles": [],
      "checkpoints": []
    }
  },
  "metadata": {
    "migratedAt": "2026-02-19T10:00:00.000Z",
    "migratedFrom": "2.1.1"
  }
}
```

---

## Post-Migration: Enable v3.0 Features

After migration, v3.0 features are available immediately:

```bash
# Check trust level (starts at "low")
morph-spec trust status

# View thread management
morph-spec threads list

# Try context priming
morph-spec prime feature

# Explore HOPs
morph-spec hop list
```

**Trust level** starts at `low` until checkpoints accumulate. To reach `maximum` trust (required for zero-touch), complete 10+ checkpoints with >95% pass rate.

---

## Troubleshooting

### "state.json not found"

Run `morph-spec state init` first to create the initial state.

### "agents.json: Failed to parse"

Check for JSON syntax errors: `cat .morph/config/agents.json | node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))"`

### "migration fails with unknown version"

The migration handles any version string that isn't `3.0.0`. If your version field is missing or corrupted, set it manually to `2.1.1` before running migration.

### Rollback backup missing

If `state.v2.backup.json` is gone but you need v2:
- Restore from git: `git show HEAD:.morph/state.json > .morph/state.json`
- Or re-run migration (it's idempotent for already-migrated files)

---

## Related

- [Thread Management](THREAD-MANAGEMENT.md) — New thread features in v3.0
- [Context Optimization](CONTEXT-OPTIMIZATION.md) — Using new context tools
- [Meta-Prompts](META-PROMPTS.md) — HOP system overview
- `src/migrations/v2-to-v3.js` — Migration script source
- `src/migrations/agents-update.js` — Agents update script source
