用途
cheat-migrate 的职责是把用户项目根目录下的 .cheat-state.json 从旧的 schema_version 升级到 cheat-on-content 当前期望的 LATEST_SCHEMA。它只负责 state 文件的 schema 迁移，不涉及其他用户数据。
触发方式包括：用户主动说「迁移」「升级 state」「migrate」等触发词；或在 SessionStart hook 检测到 state.schema_version 与 LATEST_SCHEMA 不一致后，由用户手动运行；或在 git pull 拉到新版本、CHANGELOG 标注 BREAKING 后主动运行。
主要能力
迁移链计算：读取 .cheat-state.json 得到 current_version，读取 migrations/registry.md 得到 LATEST_SCHEMA 与版本链，算出从 current 到 target 的迁移链 chain = [(from, to, file), ...]。若某一步在注册表缺失，会报错并列出目前已知版本。
调用时可覆盖参数：/cheat-migrate — dry-run: false 直接执行；/cheat-migrate — to: 1.2 仅升到指定版本。也支持 args.from 覆盖，用于 state 文件 schema 字段损坏时强制指定起点。
状态判断：current == target 时输出无需迁移并退出；current > target（如从 dev 版切回 release）时报错无法降级，需手动调整或重新 init；current < target 时继续执行。
使用方式（工作流）
Phase 0：读 .cheat-state.json 与 migrations/registry.md，确定迁移链。
Phase 1：dry-run（默认开启）输出迁移计划，展示当前版本、目标版本、按顺序的每一步（含 MAJOR/MINOR 标识、新增/删除字段、对应迁移文件），并询问用户确认。用户回 yes 执行、no 退出、dry-run-detail 查看每步具体改动。
Phase 2：备份，cp .cheat-state.json 到 .cheat-state.json.backup-<timestamp>。备份是硬约束，即使使用 --dry-run: false 也会执行。
Phase 3：按顺序应用每一步迁移文件。读取 migrations/<file> 中「## HOW (Claude steps for /cheat-migrate)」段，按段内自然语言步骤逐项执行（迁移由 Claude 读 markdown 执行，不是 python 脚本）。每步完成后更新内存中 schema_version 并原子写盘（写 .tmp 再 rename）。某步失败则输出错误，不前进、不回滚，提示已停在最后一个成功的中间版本，修复后重跑会从断点继续。
Phase 4：验证。读 .cheat-state.json 应能成功解析，schema_version 应等于 target，所有必填字段非缺失（参照 shared-references/state-management.md）。验证失败则报错并建议查看备份恢复。
Phase 5：报告。输出迁移起止版本、应用步数，提示备份保留位置，以及下一步建议（如跑 /cheat-status 确认看板正常；如有 hooks 重装需求跑 bash <skill_repo>/install.sh --reinstall-hooks）。
关键规则
幂等：在已升过的 state 上重跑会立即退出「无需迁移」，靠对比 current_version == target 实现。
不跳版：1.0 → 1.3 必须按 1.0→1.1→1.2→1.3 顺序，每步独立可恢复，不允许合并式一步升级。
不静默兼容：schema_version 无法识别时报错「未知版本 X，最近已知版本 Y」，不假装能继续。
失败停在原地：第 N 步失败时 schema_version 停在 N-1 已成功的版本，不回滚，重跑可从断点继续。
备份是硬约束：写之前必有备份。
不碰其他数据：只改 .cheat-state.json，不动 predictions / rubric / videos。
MAJOR 与 MINOR 透明：dry-run 输出必标 (MAJOR) / (MINOR)；MAJOR 时额外提示迁移完不能回退到老 skill 版本。
拒绝场景
拒绝降级（current > target），schema 演进单向，如需降级请手动 cp 历史 git 快照；拒绝把多步迁移合并成一个 atomic；拒绝在跑 cheat-bump / cheat-predict 中途调用 migrate，需等其他 skill 完成，避免 in_progress_session 状态被破坏。对「跳过 dry-run 立刻覆盖」允许但备份仍强制执行；对「state 损坏、schema_version 字段缺失、猜测版本」允许指定 --from 并警告可能字段错位。
与其他 skill 的关系
cheat-init 写新 state 时直接用 LATEST_SCHEMA，不需要走 migrate。迁移不重装 hook 脚本（hook 属于 skill 包代码，不属于用户 state），与 install.sh --reinstall-hooks 解耦。迁移完成后，其他 skill 读 state 都能拿到最新字段。
限制
资料未提供具体支持的版本号范围、迁移文件数量或各版本字段明细；除 .cheat-state.json 之外的数据不在本 skill 职责内。