[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6NQDJEC1N301PBR9STW5YDM":3,"skill-same:01M6NQDJEC1N301PBR9STW5YDM":136},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":86,"commitSha":87,"skillDirectory":88,"forksCount":14,"repositoryHtmlUrl":89,"repositoryHomepageUrl":90,"ownerHtmlUrl":91,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":92,"install":93,"resources":106},"01M6NQDJEC1N301PBR9STW5YDM","migration-management",null,"Manage Migration entities — pending, in-progress, and applied transitions between upstream source versions. Use when an upstream source bumps version (processkit, a host installer, or a community package), when a user wants to draft a migration plan, when an agent needs to reason about pending migrations, or when working through an in-progress migration.","projectious-work\u002Fprocesskit","projectious-work","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F263889726?v=4","01M6N97TJJ118WQ35CHRV8RD0E","projectious.work","01M6N97TPWJPF0BMKYQ4PBY5W8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"migration","management","migration management","audit trail","migrate","when","get","write","audit","progress","plan","work","fresh","log","sqlite","query","workflow","host","decision","community","2026-11-10 10:12:30",false,"---\nname: migration-management\ndescription: |\n  Manage Migration entities — pending, in-progress, and applied transitions between upstream source versions. Use when an upstream source bumps version (processkit, a host installer, or a community package), when a user wants to draft a migration plan, when an agent needs to reason about pending migrations, or when working through an in-progress migration.\nmetadata:\n  processkit:\n    apiVersion: processkit.projectious.work\u002Fv2\n    id: SKILL-migration-management\n    version: \"1.0.0\"\n    created: 2026-04-07T00:00:00Z\n    category: processkit\n    layer: 3\n    uses:\n      - skill: event-log\n        purpose: Log events to keep the audit trail accurate after every write.\n      - skill: decision-record\n        purpose: Record consequential decisions made during this skill's workflow.\n      - skill: index-management\n        purpose: Query existing entities and keep the SQLite index fresh after writes.\n      - skill: id-management\n        purpose: Allocate unique entity identifiers via central ID generation.\n    provides:\n      primitives: [Migration]\n      templates: [migration]\n      mcp_tools:\n        - list_migrations\n        - get_migration\n        - draft_migration\n        - start_migration\n        - apply_migration\n        - reject_migration\n        - normalize_migration_filename\n        - migrate_context_to_v2\n        - plan_v0_to_v1_migration\n        - execute_v0_to_v1_migration\n---\n\n# Migration Management\n\n## Intro\n\nA Migration is processkit's tracked representation of an upstream version\nbump. When a host installer\u002Fsync tool notices a new processkit,\nhost-installer, or community-package version, it writes a Migration\nentity into `context\u002Fmigrations\u002Fpending\u002F`.\nThe agent and the user work through it together over one or more sessions —\ndrafting a plan, applying changes, then archiving the result. This skill is\nhow the agent navigates that lifecycle.\n\nMigration is also the upstream-source-version transition primitive. Use it for\nevery upstream Schema change, every adopted third-party spec version change\n(A2A, ACP, Cilium CRDs, kagent CRDs if adopted), and every auditable data-fix.\nThe Migration records the exact source version transition through\n`source_api_version`, `source_processkit_version`, `target_api_version`, and\n`target_processkit_version`; `pk-doctor` treats missing version metadata as a\nschema vocabulary error for v2 content.\n\nTwo subtype patterns are canonical:\n\n- `Migration{kind=schema-extension}` documents an extension to a Schema\n  vocabulary such as `Artifact.spec.known_kinds` or\n  `Binding.spec.known_types`.\n- `Migration{kind=data-fix}` documents a correction to already-emitted data.\n  For LogEntry repair, the original event is superseded by reference and never\n  deleted; this preserves the append-only event-log invariant.\n\n## Overview\n\n### The migration directory layout\n\n```\ncontext\u002Fmigrations\u002F\n├── INDEX.md                    ← always-loaded summary of all migrations\n│\n├── pending\u002F                    ← briefings waiting for human review\n│   └── MIG-\u003Cid>.md\n│\n├── in-progress\u002F                ← migrations being worked on\n│   └── MIG-\u003Cid>.md\n│\n└── applied\u002F                    ← completed migrations (historical record)\n    └── MIG-\u003Cid>.md\n```\n\nThe directory the file lives in **mirrors** the entity's `spec.state`. Moving\nthe file is part of the state transition — `transition_migration` does both\nthe file move and the spec update atomically.\n\n### The lifecycle\n\n```\n                ┌──────────────┐\n                │   pending    │ ← host sync writes new migrations here\n                └──────┬───────┘\n                       │ user reviews briefing, approves a plan\n                       ▼\n                ┌──────────────┐\n                │ in-progress  │ ← agent works through plan, updates progress_notes\n                └──────┬───────┘\n                       │ all plan items done, user accepts\n                       ▼\n                ┌──────────────┐\n                │   applied    │ ← terminal, kept as history\n                └──────────────┘\n\n      Either pending or in-progress can transition to `rejected`\n      (terminal side branch — \"we looked at this and decided not to take it\")\n```\n\n### Always-loaded INDEX.md\n\n`context\u002Fmigrations\u002FINDEX.md` is a small file the agent loads at session start.\nIt summarizes every migration's state and the next action. Update it whenever\nyou transition a migration. Sample shape:\n\n```markdown\n# Migrations Index\n\n## Pending (2)\n\n- **MIG-bright-owl** — processkit v0.3.0 → v0.4.0 (generated 2026-04-15)\n  4 affected skills, 2 affected processes, 8 new entities, 1 removal\n- **MIG-calm-river** — aibox 0.14.4 → 0.15.0 (generated 2026-04-12)\n\n## In progress (1)\n\n- **MIG-quick-hawk** — processkit v0.2.0 → v0.3.0 (started 2026-04-08)\n  Plan: 6 items, 4 done. Next: migrate workitem-management overrides.\n\n## Applied (4)\n\n| Date       | Migration                                |\n|------------|------------------------------------------|\n| 2026-04-15 | MIG-... — processkit v0.1.0 → v0.2.0     |\n| 2026-03-20 | MIG-... — aibox 0.13.0 → 0.14.0          |\n```\n\n### Workflow when starting a session\n\n1. Read `context\u002Fmigrations\u002FINDEX.md` — get the migration state at a glance.\n2. If anything is in `pending\u002F` and the user hasn't asked about something\n   else, surface it: \"There's a pending migration MIG-bright-owl from\n   processkit v0.3.0 to v0.4.0. Do you want to review it now?\"\n3. If anything is in `in-progress\u002F`, surface it: \"We're 4\u002F6 of the way\n   through MIG-quick-hawk. Want to continue?\"\n4. Otherwise proceed with the user's request.\n\n### Workflow for a pending migration\n\n1. **Read the briefing** — open the file in `pending\u002F`. The body has a\n   summary, list of affected files (with classification), new additions,\n   removals.\n2. **Draft a plan** — propose a project-specific migration plan to the\n   user. Keep it small: each item is one concrete action (\"update the\n   release process to call the new gate\", \"rename `foo` references in\n   our overrides\", etc.). Prefer many small items over a few big ones.\n3. **Get approval** — show the plan, ask for explicit approval. Do NOT\n   start changing files until approved.\n4. **Transition** — when approved, set `spec.state: in-progress`, set\n   `spec.plan: \u003Capproved plan>`, and **move the file** from `pending\u002F`\n   to `in-progress\u002F`.\n5. **Update INDEX.md**.\n\n### Workflow for an in-progress migration\n\n1. Read `spec.plan` and `spec.progress_notes` — figure out where you are.\n2. Pick the next plan item, do the work, get user confirmation per item\n   if non-trivial.\n3. Append a `progress_note` to `spec.progress_notes` after each completed\n   item — date, actor, what was done.\n4. When all items are done, ask the user to accept. On acceptance:\n   - Set `spec.state: applied`, set `spec.applied_at` and `spec.applied_by`\n   - Move the file from `in-progress\u002F` to `applied\u002F`\n   - Update INDEX.md\n   - Optionally write a `LogEntry` (`event_type: migration.applied`)\n\n### Rejecting a migration\n\nIf the user decides not to take an upstream change:\n- Set `spec.state: rejected`, `spec.rejected_reason: \"...\"`\n- Move the file from `pending\u002F` (or `in-progress\u002F`) to `applied\u002F`\n  (rejected migrations live in `applied\u002F` because that's their terminal home —\n  \"applied\" here means \"decision finalized\", not \"code applied\")\n- Future host sync runs see this migration in `applied\u002F` and do NOT\n  re-propose the same transition.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Drafting a Migration without a rollback plan.** Every Migration\n  must answer \"what happens if this fails halfway through\". A\n  Migration without rollback is a one-way door — and one-way\n  doors deserve much more scrutiny than the typical Migration\n  flow allows. State the rollback explicitly even when it's\n  \"manual restore from backup\".\n- **Running a Migration without a dry-run pass.** Always preview\n  the changes before applying. A dry-run that shows the diff\n  surfaces typos, ordering issues, and unintended scope before\n  they hit the live tree.\n- **Forgetting to log `migration.applied` (and `migration.failed`).**\n  The audit trail is how the next Migration knows where the last\n  one stopped. Skipping the log strands future maintainers.\n- **Sequencing dependent Migrations wrong.** If Migration B\n  assumes the state Migration A produced, applying B before A is\n  guaranteed corruption. Use the `depends_on` field and verify\n  the dependency graph before scheduling.\n- **Migration markers without actual diffs.** Don't create a\n  Migration entity for \"fix the thing\" if there's no concrete\n  before\u002Fafter state. Migrations are records of mechanical\n  transitions, not aspirational notes.\n- **Treating \"no-op migrations\" as harmless.** A Migration that\n  does nothing should not exist — delete it. Otherwise it\n  pollutes the audit trail with phantom transitions.\n- **Editing an applied Migration after the fact.** Migrations are\n  immutable history. If the Migration was wrong, write a NEW\n  Migration that corrects it (`migration.corrected`), don't\n  rewrite the old one.\n\n## Full reference\n\n### Migration entity shape\n\nSee `src\u002Fprimitives\u002Fschemas\u002Fmigration.yaml` for the authoritative schema.\nFrequently-used fields:\n\n| Field | Type | Notes |\n|---|---|---|\n| `source` | string | `aibox`, `processkit`, `processkit-acme`, ... |\n| `from_version` | string | semver tag |\n| `to_version` | string | semver tag |\n| `state` | enum | `pending` \u002F `in-progress` \u002F `applied` \u002F `rejected` |\n| `summary` | string | one-line for INDEX.md |\n| `affected_files` | list[object] | path + classification per file |\n| `affected_groups` | list[string] | logical groups touched |\n| `plan` | list[string] | ordered declarative or reviewed plan steps |\n| `progress_notes` | list[object] | append-only progress log |\n\n### Data-fix migrations are required for legacy shapes\n\nCompatibility shims are temporary aids for discovering drift, not a\nterminal state. When pk-doctor reports legacy vocabulary, non-canonical\nIDs, filename-policy drift, wrong directory layouts, placeholder\ntimestamps, or stale references, record a `kind: data-fix` Migration\nthat names every affected file and the canonical target shape. Apply\nthe migration through migration-management MCP tools so indexes,\nschemas, state-machine transitions, and event logs stay consistent.\n\nDo not resolve strict schema\u002Fstorage drift by adding project-local\n`legacy_known_*` allowlists or by documenting a permanent policy\nexception. If a legacy value should become current vocabulary, ship an\nexplicit schema migration that adds it to the authoritative\n`known_*` field before new entities use it.\n\n### The five file classifications\n\n| Classification | Meaning |\n|---|---|\n| `changed-upstream-only` | Upstream changed it, the user has not touched it. Safe to take the new version with one approval. |\n| `changed-locally-only` | The user has edited it, upstream is unchanged. No-op for this migration — but worth flagging that the file diverges. |\n| `conflict` | Both have changed. Must be resolved by hand (or by agent + user). Highest priority. |\n| `new-upstream` | Upstream added a new file. Decide whether to take it. |\n| `removed-upstream` | Upstream removed a file the project still uses. Decide whether to remove locally or keep as a project-local fork. |\n\n### Why migrations are tracked entities, not just markdown files\n\nThree reasons:\n1. **Queryable.** The `index-management` MCP server indexes them. An agent can\n   ask \"what migrations are pending?\" without filesystem walking.\n2. **State machine validation.** Transitions are validated by the migration\n   state machine — you cannot accidentally move a file from `applied\u002F` back\n   to `pending\u002F`.\n3. **Cross-referenceable.** A `WorkItem` can reference a `Migration`\n   (`spec.related_migrations: [MIG-bright-owl]`), so if a migration spawns\n   work, the agent can find the linkage. Same for `DecisionRecord`.\n\n### Interaction with PROVENANCE.toml\n\nWhen a host sync tool generates a Migration, it diffs the\n`PROVENANCE.toml` files of the old and new upstream versions. This gives\nthe change set without having to walk every file. The diff script\n(`scripts\u002Fprocesskit-diff.sh`) is the canonical implementation; host\ninstallers can call it or reimplement its logic.\n\n### Interaction with the upstream reference templates\n\nThe project's `context\u002Ftemplates\u002Fprocesskit\u002F\u003Cversion>\u002F` directory holds\na verbatim copy of every file shipped by the pinned processkit release\n(installed and refreshed by the host installer). The migration's\n`affected_files` classification is computed by comparing three SHAs on\nthe fly:\n\n- **template SHA** — read from\n  `context\u002Ftemplates\u002Fprocesskit\u002F\u003Cversion>\u002F\u003Cfile>` (the as-installed\n  reference)\n- **cache SHA** — what upstream NOW says (from the host installer's\n  runtime cache, fetched from the pinned processkit tag)\n- **live SHA** — what's in the project right now\n\nThree SHAs → five classifications. See the host installer migration\ngeneration logic for the truth table. The pinned source URL + version +\nresolved commit live in the project lockfile at the project root\n(Cargo-style), not in a separate manifest file.\n\n### Agent-facing MCP tools\n\nThis skill ships an MCP server — see\n[`mcp\u002FSERVER.md`](mcp\u002FSERVER.md) for the contract. The server exposes\ntools that cover discovery, local drafting, lifecycle, administrative\nnormalization, and the v0-to-v1 corpus conversion. `list_migrations`\nand `get_migration` provide discovery, `draft_migration` creates a\nschema-valid pending repair, and `start_migration` handles the\n`pending → in-progress` edge, `apply_migration` for the terminal\n`in-progress → applied` edge (with implicit-start support from a\npending file), and `reject_migration` for the\n`{pending, in-progress} → rejected` branch. Every write-side tool\nstamps the appropriate timestamp (`started_at` \u002F `applied_at` \u002F\n`rejected_at`), moves the file between the `pending\u002F`, `in-progress\u002F`,\nand `applied\u002F` directories, refreshes `context\u002Fmigrations\u002FINDEX.md`\n(preserving the hand-written Notes column and the trailing\n`## CLI Migrations` section), and writes a `migration.*` event via the\nside-effect log helper.\n\nIn gateway deployments, these tools are available only when\nmigration-management is present in the installed\u002Fmerged MCP\nconfiguration. The gateway must not infer or expose unrelated\nprocesskit servers from this skill's documentation.\n\n`list_migrations()` without arguments is intentionally an active-work\nview: it returns only `pending` and `in-progress` migrations. Historical\n`applied` and `rejected` migrations accumulate for the life of a project\nand must be requested explicitly with `state=\"applied\"` or\n`state=\"rejected\"` to avoid filling status\u002Fresume context.\n\n`normalize_migration_filename` is the narrow, audited repair path for\nhistorical filename-policy findings. It preserves LogEntries and other\nterminal Migration references rather than rewriting append-only history.\n\n`plan_v0_to_v1_migration` produces a deterministic, source-hashed plan.\n`execute_v0_to_v1_migration` accepts that plan unchanged, validates stale\ninput and target hashes, stages all writes, preserves unknown fields and\nLogEntry bytes, and records a recovery journal.\n\n### Boundaries\n\n- Host installers may still generate version-diff Migrations.\n- General migration plans do not execute arbitrary scripts.\n- The v0-to-v1 executor only implements its declared deterministic corpus\n  transformation vocabulary.\n","# Migration Management\n\n## Intro\n\nA Migration is processkit's tracked representation of an upstream version\nbump. When a host installer\u002Fsync tool notices a new processkit,\nhost-installer, or community-package version, it writes a Migration\nentity into `context\u002Fmigrations\u002Fpending\u002F`.\nThe agent and the user work through it together over one or more sessions —\ndrafting a plan, applying changes, then archiving the result. This skill is\nhow the agent navigates that lifecycle.\n\nMigration is also the upstream-source-version transition primitive. Use it for\nevery upstream Schema change, every adopted third-party spec version change\n(A2A, ACP, Cilium CRDs, kagent CRDs if adopted), and every auditable data-fix.\nThe Migration records the exact source version transition through\n`source_api_version`, `source_processkit_version`, `target_api_version`, and\n`target_processkit_version`; `pk-doctor` treats missing version metadata as a\nschema vocabulary error for v2 content.\n\nTwo subtype patterns are canonical:\n\n- `Migration{kind=schema-extension}` documents an extension to a Schema\n  vocabulary such as `Artifact.spec.known_kinds` or\n  `Binding.spec.known_types`.\n- `Migration{kind=data-fix}` documents a correction to already-emitted data.\n  For LogEntry repair, the original event is superseded by reference and never\n  deleted; this preserves the append-only event-log invariant.\n\n## Overview\n\n### The migration directory layout\n\n```\ncontext\u002Fmigrations\u002F\n├── INDEX.md                    ← always-loaded summary of all migrations\n│\n├── pending\u002F                    ← briefings waiting for human review\n│   └── MIG-\u003Cid>.md\n│\n├── in-progress\u002F                ← migrations being worked on\n│   └── MIG-\u003Cid>.md\n│\n└── applied\u002F                    ← completed migrations (historical record)\n    └── MIG-\u003Cid>.md\n```\n\nThe directory the file lives in **mirrors** the entity's `spec.state`. Moving\nthe file is part of the state transition — `transition_migration` does both\nthe file move and the spec update atomically.\n\n### The lifecycle\n\n```\n                ┌──────────────┐\n                │   pending    │ ← host sync writes new migrations here\n                └──────┬───────┘\n                       │ user reviews briefing, approves a plan\n                       ▼\n                ┌──────────────┐\n                │ in-progress  │ ← agent works through plan, updates progress_notes\n                └──────┬───────┘\n                       │ all plan items done, user accepts\n                       ▼\n                ┌──────────────┐\n                │   applied    │ ← terminal, kept as history\n                └──────────────┘\n\n      Either pending or in-progress can transition to `rejected`\n      (terminal side branch — \"we looked at this and decided not to take it\")\n```\n\n### Always-loaded INDEX.md\n\n`context\u002Fmigrations\u002FINDEX.md` is a small file the agent loads at session start.\nIt summarizes every migration's state and the next action. Update it whenever\nyou transition a migration. Sample shape:\n\n```markdown\n# Migrations Index\n\n## Pending (2)\n\n- **MIG-bright-owl** — processkit v0.3.0 → v0.4.0 (generated 2026-04-15)\n  4 affected skills, 2 affected processes, 8 new entities, 1 removal\n- **MIG-calm-river** — aibox 0.14.4 → 0.15.0 (generated 2026-04-12)\n\n## In progress (1)\n\n- **MIG-quick-hawk** — processkit v0.2.0 → v0.3.0 (started 2026-04-08)\n  Plan: 6 items, 4 done. Next: migrate workitem-management overrides.\n\n## Applied (4)\n\n| Date       | Migration                                |\n|------------|------------------------------------------|\n| 2026-04-15 | MIG-... — processkit v0.1.0 → v0.2.0     |\n| 2026-03-20 | MIG-... — aibox 0.13.0 → 0.14.0          |\n```\n\n### Workflow when starting a session\n\n1. Read `context\u002Fmigrations\u002FINDEX.md` — get the migration state at a glance.\n2. If anything is in `pending\u002F` and the user hasn't asked about something\n   else, surface it: \"There's a pending migration MIG-bright-owl from\n   processkit v0.3.0 to v0.4.0. Do you want to review it now?\"\n3. If anything is in `in-progress\u002F`, surface it: \"We're 4\u002F6 of the way\n   through MIG-quick-hawk. Want to continue?\"\n4. Otherwise proceed with the user's request.\n\n### Workflow for a pending migration\n\n1. **Read the briefing** — open the file in `pending\u002F`. The body has a\n   summary, list of affected files (with classification), new additions,\n   removals.\n2. **Draft a plan** — propose a project-specific migration plan to the\n   user. Keep it small: each item is one concrete action (\"update the\n   release process to call the new gate\", \"rename `foo` references in\n   our overrides\", etc.). Prefer many small items over a few big ones.\n3. **Get approval** — show the plan, ask for explicit approval. Do NOT\n   start changing files until approved.\n4. **Transition** — when approved, set `spec.state: in-progress`, set\n   `spec.plan: \u003Capproved plan>`, and **move the file** from `pending\u002F`\n   to `in-progress\u002F`.\n5. **Update INDEX.md**.\n\n### Workflow for an in-progress migration\n\n1. Read `spec.plan` and `spec.progress_notes` — figure out where you are.\n2. Pick the next plan item, do the work, get user confirmation per item\n   if non-trivial.\n3. Append a `progress_note` to `spec.progress_notes` after each completed\n   item — date, actor, what was done.\n4. When all items are done, ask the user to accept. On acceptance:\n   - Set `spec.state: applied`, set `spec.applied_at` and `spec.applied_by`\n   - Move the file from `in-progress\u002F` to `applied\u002F`\n   - Update INDEX.md\n   - Optionally write a `LogEntry` (`event_type: migration.applied`)\n\n### Rejecting a migration\n\nIf the user decides not to take an upstream change:\n- Set `spec.state: rejected`, `spec.rejected_reason: \"...\"`\n- Move the file from `pending\u002F` (or `in-progress\u002F`) to `applied\u002F`\n  (rejected migrations live in `applied\u002F` because that's their terminal home —\n  \"applied\" here means \"decision finalized\", not \"code applied\")\n- Future host sync runs see this migration in `applied\u002F` and do NOT\n  re-propose the same transition.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Drafting a Migration without a rollback plan.** Every Migration\n  must answer \"what happens if this fails halfway through\". A\n  Migration without rollback is a one-way door — and one-way\n  doors deserve much more scrutiny than the typical Migration\n  flow allows. State the rollback explicitly even when it's\n  \"manual restore from backup\".\n- **Running a Migration without a dry-run pass.** Always preview\n  the changes before applying. A dry-run that shows the diff\n  surfaces typos, ordering issues, and unintended scope before\n  they hit the live tree.\n- **Forgetting to log `migration.applied` (and `migration.failed`).**\n  The audit trail is how the next Migration knows where the last\n  one stopped. Skipping the log strands future maintainers.\n- **Sequencing dependent Migrations wrong.** If Migration B\n  assumes the state Migration A produced, applying B before A is\n  guaranteed corruption. Use the `depends_on` field and verify\n  the dependency graph before scheduling.\n- **Migration markers without actual diffs.** Don't create a\n  Migration entity for \"fix the thing\" if there's no concrete\n  before\u002Fafter state. Migrations are records of mechanical\n  transitions, not aspirational notes.\n- **Treating \"no-op migrations\" as harmless.** A Migration that\n  does nothing should not exist — delete it. Otherwise it\n  pollutes the audit trail with phantom transitions.\n- **Editing an applied Migration after the fact.** Migrations are\n  immutable history. If the Migration was wrong, write a NEW\n  Migration that corrects it (`migration.corrected`), don't\n  rewrite the old one.\n\n## Full reference\n\n### Migration entity shape\n\nSee `src\u002Fprimitives\u002Fschemas\u002Fmigration.yaml` for the authoritative schema.\nFrequently-used fields:\n\n| Field | Type | Notes |\n|---|---|---|\n| `source` | string | `aibox`, `processkit`, `processkit-acme`, ... |\n| `from_version` | string | semver tag |\n| `to_version` | string | semver tag |\n| `state` | enum | `pending` \u002F `in-progress` \u002F `applied` \u002F `rejected` |\n| `summary` | string | one-line for INDEX.md |\n| `affected_files` | list[object] | path + classification per file |\n| `affected_groups` | list[string] | logical groups touched |\n| `plan` | list[string] | ordered declarative or reviewed plan steps |\n| `progress_notes` | list[object] | append-only progress log |\n\n### Data-fix migrations are required for legacy shapes\n\nCompatibility shims are temporary aids for discovering drift, not a\nterminal state. When pk-doctor reports legacy vocabulary, non-canonical\nIDs, filename-policy drift, wrong directory layouts, placeholder\ntimestamps, or stale references, record a `kind: data-fix` Migration\nthat names every affected file and the canonical target shape. Apply\nthe migration through migration-management MCP tools so indexes,\nschemas, state-machine transitions, and event logs stay consistent.\n\nDo not resolve strict schema\u002Fstorage drift by adding project-local\n`legacy_known_*` allowlists or by documenting a permanent policy\nexception. If a legacy value should become current vocabulary, ship an\nexplicit schema migration that adds it to the authoritative\n`known_*` field before new entities use it.\n\n### The five file classifications\n\n| Classification | Meaning |\n|---|---|\n| `changed-upstream-only` | Upstream changed it, the user has not touched it. Safe to take the new version with one approval. |\n| `changed-locally-only` | The user has edited it, upstream is unchanged. No-op for this migration — but worth flagging that the file diverges. |\n| `conflict` | Both have changed. Must be resolved by hand (or by agent + user). Highest priority. |\n| `new-upstream` | Upstream added a new file. Decide whether to take it. |\n| `removed-upstream` | Upstream removed a file the project still uses. Decide whether to remove locally or keep as a project-local fork. |\n\n### Why migrations are tracked entities, not just markdown files\n\nThree reasons:\n1. **Queryable.** The `index-management` MCP server indexes them. An agent can\n   ask \"what migrations are pending?\" without filesystem walking.\n2. **State machine validation.** Transitions are validated by the migration\n   state machine — you cannot accidentally move a file from `applied\u002F` back\n   to `pending\u002F`.\n3. **Cross-referenceable.** A `WorkItem` can reference a `Migration`\n   (`spec.related_migrations: [MIG-bright-owl]`), so if a migration spawns\n   work, the agent can find the linkage. Same for `DecisionRecord`.\n\n### Interaction with PROVENANCE.toml\n\nWhen a host sync tool generates a Migration, it diffs the\n`PROVENANCE.toml` files of the old and new upstream versions. This gives\nthe change set without having to walk every file. The diff script\n(`scripts\u002Fprocesskit-diff.sh`) is the canonical implementation; host\ninstallers can call it or reimplement its logic.\n\n### Interaction with the upstream reference templates\n\nThe project's `context\u002Ftemplates\u002Fprocesskit\u002F\u003Cversion>\u002F` directory holds\na verbatim copy of every file shipped by the pinned processkit release\n(installed and refreshed by the host installer). The migration's\n`affected_files` classification is computed by comparing three SHAs on\nthe fly:\n\n- **template SHA** — read from\n  `context\u002Ftemplates\u002Fprocesskit\u002F\u003Cversion>\u002F\u003Cfile>` (the as-installed\n  reference)\n- **cache SHA** — what upstream NOW says (from the host installer's\n  runtime cache, fetched from the pinned processkit tag)\n- **live SHA** — what's in the project right now\n\nThree SHAs → five classifications. See the host installer migration\ngeneration logic for the truth table. The pinned source URL + version +\nresolved commit live in the project lockfile at the project root\n(Cargo-style), not in a separate manifest file.\n\n### Agent-facing MCP tools\n\nThis skill ships an MCP server — see\n[`mcp\u002FSERVER.md`](mcp\u002FSERVER.md) for the contract. The server exposes\ntools that cover discovery, local drafting, lifecycle, administrative\nnormalization, and the v0-to-v1 corpus conversion. `list_migrations`\nand `get_migration` provide discovery, `draft_migration` creates a\nschema-valid pending repair, and `start_migration` handles the\n`pending → in-progress` edge, `apply_migration` for the terminal\n`in-progress → applied` edge (with implicit-start support from a\npending file), and `reject_migration` for the\n`{pending, in-progress} → rejected` branch. Every write-side tool\nstamps the appropriate timestamp (`started_at` \u002F `applied_at` \u002F\n`rejected_at`), moves the file between the `pending\u002F`, `in-progress\u002F`,\nand `applied\u002F` directories, refreshes `context\u002Fmigrations\u002FINDEX.md`\n(preserving the hand-written Notes column and the trailing\n`## CLI Migrations` section), and writes a `migration.*` event via the\nside-effect log helper.\n\nIn gateway deployments, these tools are available only when\nmigration-management is present in the installed\u002Fmerged MCP\nconfiguration. The gateway must not infer or expose unrelated\nprocesskit servers from this skill's documentation.\n\n`list_migrations()` without arguments is intentionally an active-work\nview: it returns only `pending` and `in-progress` migrations. Historical\n`applied` and `rejected` migrations accumulate for the life of a project\nand must be requested explicitly with `state=\"applied\"` or\n`state=\"rejected\"` to avoid filling status\u002Fresume context.\n\n`normalize_migration_filename` is the narrow, audited repair path for\nhistorical filename-policy findings. It preserves LogEntries and other\nterminal Migration references rather than rewriting append-only history.\n\n`plan_v0_to_v1_migration` produces a deterministic, source-hashed plan.\n`execute_v0_to_v1_migration` accepts that plan unchanged, validates stale\ninput and target hashes, stages all writes, preserves unknown fields and\nLogEntry bytes, and records a recovery journal.\n\n### Boundaries\n\n- Host installers may still generate version-diff Migrations.\n- General migration plans do not execute arbitrary scripts.\n- The v0-to-v1 executor only implements its declared deterministic corpus\n  transformation vocabulary.\n",{"name":5,"metadata":49,"description":85},{"processkit":50},{"id":51,"uses":52,"layer":65,"created":66,"version":67,"category":68,"provides":69,"apiVersion":84},"SKILL-migration-management",[53,56,59,62],{"skill":54,"purpose":55},"event-log","Log events to keep the audit trail accurate after every write.",{"skill":57,"purpose":58},"decision-record","Record consequential decisions made during this skill's workflow.",{"skill":60,"purpose":61},"index-management","Query existing entities and keep the SQLite index fresh after writes.",{"skill":63,"purpose":64},"id-management","Allocate unique entity identifiers via central ID generation.",3,1775520000000,"1.0.0","processkit",{"mcp_tools":70,"templates":81,"primitives":82},[71,72,73,74,75,76,77,78,79,80],"list_migrations","get_migration","draft_migration","start_migration","apply_migration","reject_migration","normalize_migration_filename","migrate_context_to_v2","plan_v0_to_v1_migration","execute_v0_to_v1_migration",[24],[83],"Migration","processkit.projectious.work\u002Fv2","Manage Migration entities — pending, in-progress, and applied transitions between upstream source versions. Use when an upstream source bumps version (processkit, a host installer, or a community package), when a user wants to draft a migration plan, when an agent needs to reason about pending migrations, or when working through an in-progress migration.\n","main","4876a92620ee792aac2ac9a1a806322d8a572367","src\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit","https:\u002F\u002Fprojectious-work.github.io\u002Fprocesskit\u002F","https:\u002F\u002Fgithub.com\u002Fprojectious-work","2026-11-11 23:24:18",{"source":8,"skillName":5,"commands":94,"prompt":104,"zipAvailable":105},[95,98,101],{"tool":96,"command":97},"npx","npx skills add projectious-work\u002Fprocesskit --skill migration-management",{"tool":99,"command":100},"bunx","bunx skills add projectious-work\u002Fprocesskit --skill migration-management",{"tool":102,"command":103},"pnpm","pnpm dlx skills add projectious-work\u002Fprocesskit --skill migration-management","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management\u002FSKILL.md",true,[107,113,119,123,129,132],{"path":108,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":111,"sourceHtmlUrl":112},"assets\u002Fmigration.yaml","ASSET","资产文件",988,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management\u002Fassets\u002Fmigration.yaml",{"path":114,"resourceType":115,"resourceTypeDesc":116,"sizeBytes":117,"sourceHtmlUrl":118},"mcp\u002Fmcp-config.json","REFERENCE","参考文档",223,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management\u002Fmcp\u002Fmcp-config.json",{"path":120,"resourceType":115,"resourceTypeDesc":116,"sizeBytes":121,"sourceHtmlUrl":122},"mcp\u002FSERVER.md",5011,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management\u002Fmcp\u002FSERVER.md",{"path":124,"resourceType":125,"resourceTypeDesc":126,"sizeBytes":127,"sourceHtmlUrl":128},"mcp\u002Fserver.py","SCRIPT","脚本",46530,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management\u002Fmcp\u002Fserver.py",{"path":130,"resourceType":125,"resourceTypeDesc":126,"sizeBytes":14,"sourceHtmlUrl":131},"scripts\u002F.gitkeep","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management\u002Fscripts\u002F.gitkeep",{"path":133,"resourceType":125,"resourceTypeDesc":126,"sizeBytes":134,"sourceHtmlUrl":135},"scripts\u002Ftest_migration_management.py",7649,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fmigration-management\u002Fscripts\u002Ftest_migration_management.py",[137,144,151,157,178,198],{"skillNo":138,"name":139,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":140,"categories":141,"keywords":142,"publishedAt":143},"01M7665G2ED3624R3X93304265","standard-ui-design","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-ui-design\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":150,"publishedAt":143},"01M76651QTC6W0HJ4AFW2MMR3V","standard-agent-use","Company standard for working with AI agents. Use when deciding what to delegate to agents, capturing open work, keeping agent memory or knowledge notes, improving an agent workflow, or introducing agent work in a team or for a client.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-use\u002FSKILL.md",[],[],{"skillNo":152,"name":153,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":156,"publishedAt":143},"01M76650NN4T8P241021NBR64S","standard-agent-building","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-building\u002FSKILL.md",[],[],{"skillNo":158,"name":159,"nameZh":6,"description":160,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":161,"categories":162,"keywords":164,"publishedAt":44},"01M6X5MTC89B4ZGXW3JVSQCPF8","skill-management","Manage Skill package manifests as v1 ontology entities.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fskill-management\u002FSKILL.md",[163],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[25,165,166,167,168,169,35,170,30,171,172,173,159,174,175,176,177],"skill management","ontology","v1","create","as","transition","manage","update","alpha","list","package","skill package","manifests",{"skillNo":179,"name":180,"nameZh":6,"description":181,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":182,"categories":183,"keywords":185,"publishedAt":44},"01M6X5MCV74NHW5MEDNHZRF2C8","schema-management","Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fschema-management\u002FSKILL.md",[184],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[186,187,25,188,189,190,191,192,193,194,195,196,35,30,171,173,197],"schema","schema management","contract","rebuild","contracts","workflows","wed","generated","MCP","validation","deterministic","mode",{"skillNo":199,"name":200,"nameZh":6,"description":201,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":202,"categories":203,"keywords":204,"publishedAt":44},"01M6X5M5G6YJ96AMZGSCZJ1D13","proposition-management","Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fproposition-management\u002FSKILL.md",[],[205,25,206,207,168,208,209,210,35,30,211,212,172,213,173,214,215,39,216,37],"proposition management","proposition","interface","claims","record","world","creation","event","WSJF","index","updates","facts"]