migration-state.json

migration-state.json tracks the current state of the modernization effort. It captures overall progress, per-context status, parity test results, blockers, and velocity metrics. This file changes frequently as work progresses.

Full Example

{
  "started": "2026-01-20",
  "lastUpdated": "2026-02-08",
  "overallProgress": 0.18,
  "contexts": [
    {
      "name": "Accounts",
      "status": "in-progress",
      "progress": 0.45,
      "entitiesMigrated": 12,
      "entitiesTotal": 27,
      "parityTests": { "passing": 68, "failing": 4, "total": 72 },
      "assignedTeam": "Zeta",
      "notes": "Tax parity replicated; GL entry validation pending"
    },
    {
      "name": "Stock",
      "status": "not-started",
      "progress": 0.0,
      "entitiesMigrated": 0,
      "entitiesTotal": 48,
      "parityTests": { "passing": 0, "failing": 0, "total": 0 },
      "assignedTeam": null,
      "notes": "Blocked on Accounts completion (dependency)"
    }
  ],
  "blockers": [
    {
      "id": "BLOCK-001",
      "context": "Accounts",
      "description": "AccountsController God-class (4,412 LOC) requires decomposition before extraction",
      "severity": "high",
      "created": "2026-01-25",
      "resolved": null
    }
  ],
  "velocity": {
    "entitiesPerWeek": 4.2,
    "testsPerWeek": 22,
    "estimatedCompletion": "2026-04-15"
  }
}

Interactive Visualization

Field Reference

Root Fields

Field	Type	Required	Description
started	string	Yes	ISO date when modernization began
lastUpdated	string	Yes	ISO date of last update
overallProgress	number	Yes	Overall progress (0.0 to 1.0)

contexts Array

Per-bounded-context progress:

Field	Type	Required	Description
name	string	Yes	Context name (matches domains.json)
status	string	Yes	Status: "not-started", "in-progress", "complete", "blocked"
progress	number	Yes	Progress percentage (0.0 to 1.0)
entitiesMigrated	number	Yes	Entities successfully migrated
entitiesTotal	number	Yes	Total entities in this context
parityTests	object	Yes	Parity test results (see below)
assignedTeam	string	No	Team or agent assigned to this context
notes	string	No	Free-text notes on current status

parityTests Object

Field	Type	Description
passing	number	Tests currently passing
failing	number	Tests currently failing
total	number	Total tests written

blockers Array

Field	Type	Required	Description
id	string	Yes	Unique blocker identifier
context	string	Yes	Affected bounded context
description	string	Yes	What is blocking progress
severity	string	Yes	Severity: "low", "medium", "high", "critical"
created	string	Yes	ISO date when identified
resolved	string	No	ISO date when resolved (null if unresolved)

velocity Object

Field	Type	Required	Description
entitiesPerWeek	number	No	Average entities migrated per week
testsPerWeek	number	No	Average parity tests written per week
estimatedCompletion	string	No	Projected completion date

Status Values

Status	Meaning
not-started	No extraction work has begun
in-progress	Extraction is underway
complete	All entities migrated, parity tests passing
blocked	Work cannot proceed due to a blocker

Updating State

Via the SDK

const spec = await ModernizeSpec.load("/path/to/project");

spec.migrationState.updateContext("Accounts", {
  progress: 0.45,
  entitiesMigrated: 12,
  parityTests: { passing: 68, failing: 4, total: 72 },
});

await spec.save();

Via the CLI

npx modernizespec progress --context Accounts --progress 0.45

Via MCP Server

AI agents with MCP access can update progress directly through the modernize_update_progress tool.

Agent Behavior

Agents should update migration-state.json after completing work on any context:

1. Update entitiesMigrated count
2. Update parityTests with latest test run results
3. Adjust progress based on entities migrated / total
4. Add or resolve blockers as appropriate
5. Update lastUpdated timestamp

Next Steps

• Progress Dashboard — Interactive visualization
• Quick Start — Set up ModernizeSpec in your project