cheat-migrate

/cheat-migrate — Schema 版本迁移

把用户 .cheat-state.json 从旧 schema_version 升级到 cheat-on-content 当前期望的 LATEST_SCHEMA。

---

Overview

[用户：迁移 / 或 SessionStart 提示后用户跑]
  ↓
[Phase 0: 读 .cheat-state.json + migrations/registry.md → 确定迁移链]
  ↓
[Phase 1: dry-run（默认）展示迁移计划，等用户确认]
  ↓
[Phase 2: 备份 .cheat-state.json → .cheat-state.json.backup-<timestamp>]
  ↓
[Phase 3: 按顺序对每个 step 应用对应迁移文件的 HOW 段]
  ↓
[Phase 4: 验证升级后 state 文件能被解析 + schema_version 已更新]
  ↓
[Phase 5: 报告 + 提示如有备份需要清理]

---

Constants

• REGISTRY_PATH = ${SKILL_DIR}/../../migrations/registry.md — 版本链单一来源
• MIGRATIONS_DIR = ${SKILL_DIR}/../../migrations/ — 迁移文件目录
• DRY_RUN_BY_DEFAULT = true — 首次跑展示计划，不直接改文件
• BACKUP_BEFORE_WRITE = true — 写之前必备份；备份文件保留至下次成功 init / 用户手动清理
• STOP_ON_STEP_FAILURE = true — 任何 step 失败 → 停在中间版本，不前进，不回滚

💡 调用时覆盖：/cheat-migrate — dry-run: false 直接执行 / /cheat-migrate — to: 1.2 仅升到指定版本

---

Inputs

必填	来源
.cheat-state.json	用户项目根
migrations/registry.md	LATEST_SCHEMA + 版本链表
migrations/<from>-to-<to>.md	每步具体迁移指令

---

Workflow

Phase 0: 确定迁移链

1. 读 .cheat-state.json → 解析 current_version = state.schema_version
2. 读 migrations/registry.md → 解析 LATEST_SCHEMA 字段（行：LATEST_SCHEMA = "X.Y"）
3. 解析 args.to 覆盖（如有）；否则 target = LATEST_SCHEMA
4. 解析 args.from 覆盖（罕见场景：用户的 state 文件 schema 字段坏了，强制指定起点）
5. 状态判断：
   • current_version == target → 输出"✅ state 已是 {target}，无需迁移" → 退出
   • current_version > target（比如用户跑了 dev 版又切回 release）→ 报错"无法降级，请手动调整或重新 init"
   • current_version < target → 继续，从注册表查出迁移链
6. 从注册表"版本链"表算出 chain = [(from, to, file), ...]，按顺序串起 current → target

如果某一步在注册表里缺失（比如 current_version 不在表里）→ 报错并展示"目前已知版本：[1.0, 1.1, ...]"，让用户检查。

Phase 1: dry-run

输出迁移计划：

📋 迁移计划

当前版本: 1.0
目标版本: 1.2
将按顺序跑 2 步：

  [1/2] 1.0 → 1.1（MINOR）
       新增字段：typical_duration_seconds, target_publish_cadence_days, ...（共 12 字段）
       删除字段：mode, prediction_complexity, bucket_scheme
       详见: migrations/1.0-to-1.1.md

  [2/2] 1.1 → 1.2（MINOR）
       新增字段：[...]
       详见: migrations/1.1-to-1.2.md

⚠️ 备份位置: .cheat-state.json.backup-<timestamp>

继续吗？回 yes 执行 / no 退出 / dry-run-detail 看每步具体改什么。