Summary
Several `pk-doctor` findings have `suggested_fix: "create and apply a data-fix Migration"` (e.g. for normalizing entity filenames, extending schema vocabulary, rewriting cross-references). But the MCP gateway in derived projects exposes only:
- `start_migration(id)` — pending → in-progress
- `apply_migration(id)` — implicit pending → applied
- `reject_migration(id, reason)`
- `list_migrations`, `get_migration`
There is no `create_migration` / `author_migration` / `draft_data_fix_migration` tool. Existing Migration entities are generated upstream by `aibox apply` for processkit-source upgrades, but data-fix Migrations authored from inside a derived project have no MCP path.
Concrete blocked scenarios (from one ai-market-research `pk-resume` session)
- Filename-policy normalization (B3 + B8): 4 timestamped `BIND-…role-slot-fill.md` Bindings need rename to deterministic policy, with metadata.id update and cross-reference rewrite. Doctor suggested_fix is a data-fix Migration. Cannot author one.
- Schema vocabulary extension (B1, when not already-migrated): adding `role_slot.{created,filled,closed}` to `logentry.yaml.known_event_types`. (In our case a prior `MIG-20260517_1336-DeepRabbit` had been applied and the schema later got reverted by the v0.27.1 migration apply; restoring from git HEAD was the recovery, but a fresh derived project hitting this finding has no MCP authoring path.)
Per the project contract: "writes require a Migration + DEC" for schema files, and "do not hand-edit files under `context/` to create or mutate entities (use MCP tools)". Without an MCP creator, the contract and the suggested_fix are mutually unreachable.
Expected
Add an MCP tool, e.g.:
```
draft_migration(
kind: Literal["schema-extension", "data-fix", "filename-normalize", ...],
summary: str,
affected_files: list[{path, classification}],
related_decisions: list[str] = [],
body: str = "",
) -> {id, path, state: "pending"}
```
That writes a well-formed Migration MD into `context/migrations/pending/` with valid frontmatter, ready for `apply_migration`.
Bonus: a higher-level `rename_entity(old_id, new_id, target_path)` that auto-drafts a filename-normalize Migration with the cross-reference rewrites baked in.
Impact
- Doctor findings with this suggested_fix become unactionable from a derived project.
- Users either hand-edit the entity tree (violating the contract) or leave findings open indefinitely.
- Cross-project consistency drift accumulates.
Related
Summary
Several `pk-doctor` findings have `suggested_fix: "create and apply a data-fix Migration"` (e.g. for normalizing entity filenames, extending schema vocabulary, rewriting cross-references). But the MCP gateway in derived projects exposes only:
There is no `create_migration` / `author_migration` / `draft_data_fix_migration` tool. Existing Migration entities are generated upstream by `aibox apply` for processkit-source upgrades, but data-fix Migrations authored from inside a derived project have no MCP path.
Concrete blocked scenarios (from one ai-market-research `pk-resume` session)
Per the project contract: "writes require a Migration + DEC" for schema files, and "do not hand-edit files under `context/` to create or mutate entities (use MCP tools)". Without an MCP creator, the contract and the suggested_fix are mutually unreachable.
Expected
Add an MCP tool, e.g.:
```
draft_migration(
kind: Literal["schema-extension", "data-fix", "filename-normalize", ...],
summary: str,
affected_files: list[{path, classification}],
related_decisions: list[str] = [],
body: str = "",
) -> {id, path, state: "pending"}
```
That writes a well-formed Migration MD into `context/migrations/pending/` with valid frontmatter, ready for `apply_migration`.
Bonus: a higher-level `rename_entity(old_id, new_id, target_path)` that auto-drafts a filename-normalize Migration with the cross-reference rewrites baked in.
Impact
Related