Migration

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

---
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 for the full migration model.