Repository navigation
Agent UX: pm schema rename-type/remap migrations require --migration-id but fail with a cryptic non-structured error (even --dry-run) #665
Description
Summary
The 2026.7.24 schema-evolution migrations (pm schema rename-type|rename-field|remap-status) require a --migration-id, but that requirement is invisible until you hit a cryptic, non-standard error. This is a rough edge on an otherwise excellent new feature — especially for agents, which rely on the CLI's structured error contract to self-correct.
Reproduction (2026.7.24, fresh workspace)
pm init --pm-path . --yes
pm --path . schema add-type ticket --description 'A ticket' --folder tickets
pm --path . create ticket --title 'Ticket one'
pm --path . schema rename-type ticket --to case
Actual:
Schema migration migrationId must be non-empty
Problems
-
--migration-idis de-facto required but presented as optional.pm schema --helplists it as--migration-id <id> Stable idempotency key for a resumable schema migrationwith no indication that migrations refuse to run without it. Every other required input in the CLI is enforced with the structured contract. -
The failure is not a structured CLI error. Instead of the usual
What happened / What is required / Why / Examples / Next steps / Recovery bundleenvelope (used consistently elsewhere, e.g. unknown-option errors), this surfaces a raw internal assertion stringSchema migration migrationId must be non-empty. An agent gets no actionable guidance and no recovery bundle to repair the call. -
--dry-runis also blocked by it.pm schema rename-type ticket --to case --dry-runfails identically. A dry-run only plans a migration and writes nothing — it shouldn't require committing to a durable idempotency key just to preview the plan.
Confirmation the feature works when the key is supplied
pm --path . schema rename-type ticket --to case --migration-id mig-001
# rename-type: ticket -> case [applied] affected: 1 (item type migrated losslessly)
Suggested fix (any subset)
- Auto-derive a default
migration-idwhen omitted (e.g. content-hash of{op, from, to, workspace}) and let--migration-idoverride it for explicit resume — so the happy path is one command, resume stays possible. - If the key must stay explicit, enforce it through the standard structured-error contract (What is required + an
Examples:line showing--migration-id <id>), not a raw assertion string. - Do not require a migration-id for
--dry-run(planning writes nothing).
Impact
Headline 2026.7.24 feature; blocks the first-try happy path for agents doing schema evolution, and the non-structured error breaks the self-correction contract agents depend on.
Found while exercising 2026.7.24 in a throwaway workspace (agent-UX pass).
Activity
coderabbitai commentedon Jul 24, 2026
🔗 Related PRs
#200 - Add validation self-repair and agent ergonomics primitives [closed]
#563 - feat(sdk): own schema primitives and modernize init prefixes [merged]
#593 - SDK-first agent UX graph, ownership, and recovery contracts [merged]
#624 - SDK atomic structured mutations, lean output, and agent-first envelopes [merged]
#660 - SDK schema evolution, workspace audit history, and governance contracts [merged]
📝 Issue Planner
Check the box below or use the
@coderabbitai plancommand to generate an implementation plan and prompts that you can use with your favorite coding assistant.🧪 Issue enrichment is currently in open beta.
You can configure auto-planning by selecting labels in the issue_enrichment configuration.
To disable automatic issue enrichment, add the following to your
.coderabbit.yaml:💬 Have feedback or questions? Drop into our discord!
unbraind commentedon Jul 24, 2026
Tracked in pm-s79kel, the canonical schema-migration idempotency and structured-recovery item. It is actively included in the current broad SDK/CLI lifecycle tranche.