# Migration

LLMS index: [llms.txt](/processkit/v1.x/llms.txt)

---

A pending, in-progress, or applied transition between two upstream
processkit versions. Migrations are generated by `aibox sync` and
represent the delta an agent must apply to bring the project's
`context/` up to date.

| | |
|---|---|
| **ID prefix** | `MIG` |
| **State machine** | `migration` |
| **MCP server** | `migration-management` |
| **Skill** | `migration-management` (Layer 3) |

## State machine

```
pending → in-progress → applied
                      ↘ rejected
```

`applied` and `rejected` are terminal.

## Fields

### Required

| Field | Type | Description |
|---|---|---|
| `source` | string | Upstream source identifier (`processkit`, `processkit-acme`, …) |
| `from_version` | string | Version migrating FROM (semver tag) |
| `to_version` | string | Version migrating TO (semver tag) |
| `state` | string | Current state |

### Optional

| Field | Type | Description |
|---|---|---|
| `source_url` | string | Git URL of upstream (for re-fetch if needed) |
| `generated_by` | string | What generated this (`aibox sync`, `user`, …) |
| `generated_at` | datetime | When the migration document was written |
| `summary` | string | One-line summary for listings |
| `affected_files` | object[] | Files touched — each with `path`, `classification`, and optional `group` |
| `affected_groups` | string[] | Logical groups affected (unit of auto-update) |
| `plan` | string | Project-specific migration plan drafted by agent |
| `progress_notes` | object[] | Append-only notes: `{timestamp, note, actor}` |
| `applied_at` | datetime | When migration reached `applied` |
| `applied_by` | string | Actor ID that finalised the migration |
| `rejected_reason` | string | If rejected, why |
| `source_api_version` | string | API version before a v2 conversion |
| `target_api_version` | string | API version after a v2 conversion |
| `source_processkit_version` | string | processkit version before conversion |
| `target_processkit_version` | string | processkit version after conversion |
| `apply_mode` | string | Migration apply mode (`one-shot`, etc.) |

The `migration-management` MCP server manages migration state
transitions and provides `migrate_context_to_v2(dry_run=true)` for the
breaking v2 API conversion path.

### `affected_files` classification values

| Value | Meaning |
|---|---|
| `changed-upstream-only` | Upstream changed it; project did not — safe to auto-apply |
| `changed-locally-only` | Project customised it; upstream did not — no action needed |
| `conflict` | Both sides changed it — requires manual resolution |
| `new-upstream` | New file added upstream — agent should install it |
| `removed-upstream` | File removed upstream — agent should confirm removal |

## Example

```yaml
---
apiVersion: processkit.projectious.work/v1
kind: Migration
metadata:
  id: MIG-20260411_0913-BrightHaven-v0-11-1-to-v0-12-0
  created: '2026-04-11T09:13:00Z'
spec:
  source: processkit
  from_version: v0.11.1
  to_version: v0.12.0
  state: applied
  summary: Add artifact-management skill and MCP server
  applied_at: '2026-04-11T06:40:00Z'
  applied_by: ACTOR-claude
---
```

## Notes

- Migrations live under `context/migrations/pending/` until applied,
  then move to `context/migrations/applied/`.
- `aibox sync` generates migrations automatically by diffing
  `PROVENANCE.toml` across versions.
- `conflict` files require human review — the agent drafts options in
  the `plan` field but should not apply them unilaterally.
- See [Reference → Migration](../reference/migration) for the full
  migration model.