# Migration Protocol（schema 演进哲学）

被 `cheat-migrate` skill / `cheat-init` / SessionStart hook / 维护者引用。规定如何安全演进 `.cheat-state.json` schema 而不让老用户被打断。

---

## 核心原则

1. **每个 release 必须能让老用户的旧 state 工作**——通过 migrate 升级，或通过 `state.get(field, default)` 兼容
2. **MINOR 改动 = 加字段 / 软化 enum**；老 state 不跑 migrate 也能工作（字段缺失用默认值），跑了让 state 完整
3. **MAJOR 改动 = 删字段 / 重命名 / 改语义**；老 state **必须**跑 migrate，否则 skill 读到不一致字段会出错
4. **不允许跳版**；多版升级必须按顺序应用每个 step。每步幂等
5. **失败停在原地**；不回滚，让用户在断点修复后继续
6. **schema_version 是单调递增**；不允许降级（如需降级，cp 历史 git 快照）

---

## 何时算 MINOR vs MAJOR

### MINOR 范围（不需要 migrate 也能跑老 state）

- 新增字段（默认值定义良好，老 skill 不读它也不出错）
- 软化 enum 取值（如 `"strict" / "lenient"` 加第三个 `"adaptive"`，老值仍合法）
- 给字段加新可选取值（如某个 list 字段加新元素）
- 改默认值（不改语义）

### MAJOR 范围（必须跑 migrate）

- **删除字段**——老 skill 仍写它，新 skill 不读它，会出歧义
- **重命名字段**——老/新 skill 看不到对方写的
- **改字段语义**（如 `mode` 从 enum 改为整数；`baseline_plays` 从 int 改为 list）
- **改 enum 取值**（如 `"opinion-video"` 改成 `"opinion_video"`，老值不再合法）
- **拆字段 / 合字段**

> 模糊地带建议**保守判定为 MAJOR**——多写一份 migration 文件比让用户的 state 出错更好。

---

## 维护者 checklist：bump schema 时必做的 4 件事

每次准备 release 时如果改了 state schema：

### 1. 改 cheat-init 写新 state 的硬编码 schema_version

```diff
- "schema_version": "1.1",
+ "schema_version": "1.2",
```

位置：`skills/cheat-init/SKILL.md` Phase 3 的 state 写入段。

### 2. 改 migrations/registry.md 的 LATEST_SCHEMA 标记位

```diff
- LATEST_SCHEMA = "1.1"
+ LATEST_SCHEMA = "1.2"
```

并在"版本链"表追加新行：

```
| 1.1 | 1.2 | NO/YES | [1.1-to-1.2.md](1.1-to-1.2.md) | 一句话描述 |
```

### 3. 写 migrations/<old>-to-<new>.md

4 段必填（参考 `1.0-to-1.1.md` 模板）：
- WHAT changed
- WHY
- HOW (Claude steps for /cheat-migrate)
- Manual fallback

> 写不出 4 段 = 改动太复杂没想清楚 = 不该 release 这次 schema bump。

### 4. CHANGELOG.md 标版本号 + 链接

```markdown
## [0.2.0] — YYYY-MM-DD

### BREAKING / MINOR

- schema_version 1.1 → 1.2: <一句话描述>。迁移指南：[migrations/1.1-to-1.2.md](migrations/1.1-to-1.2.md)
- ...
```

MINOR 用 `### MINOR`，MAJOR 用 `### BREAKING`，要醒目。

---

## skill 内部怎么读 state（防御式编程）

每个 skill 读 state 时**必须**用 `state.get(field, default)` 模式：

```python
# 好
target_cadence = state.get("target_publish_cadence_days", None)
benchmark_status = state.get("benchmark_status", "none")
shoots = state.get("shoots", [])

# 坏（老 state 没这字段会 KeyError）
target_cadence = state["target_publish_cadence_days"]
```

理由：
- MINOR 升级时老 state 缺新字段——`get` 模式让 skill 自动用默认值
- 用户手改 state 删了字段——同上
- 减少 skill 内"必须先迁移才能跑"的强依赖

**例外**：核心标识字段允许直接索引（如 `state["schema_version"]`、`state["rubric_version"]`）——这些缺失意味着 state 文件根本不合法，应该明确报错。

---

## SessionStart hook 的角色

hook 在每次会话开始时检测：

```bash
state_schema=$(jq -r '.schema_version // "unknown"' "$STATE_FILE")
if [[ "$state_schema" != "$LATEST_SCHEMA" ]]; then
  echo "⚠️ schema 版本不一致：state=$state_schema, skill 期望=$LATEST_SCHEMA"
  echo "   建议跑 /cheat-migrate 升级（不阻塞继续工作）"
fi
```

**非阻塞**：用户可以选择"先继续工作，回头再跑 migrate"。MINOR 不一致时大部分功能仍能跑；MAJOR 时部分 skill 可能报错——这时再跑 migrate 也来得及。

---

## 给开发者：避免 schema 频繁 bump 的实践

不是每个改动都需要 schema bump。下面是哲学：

- **优先 MINOR**：能加字段就加字段，少删字段。删字段让老用户不爽
- **批量 bump**：积攒 3-5 个 MINOR 一起 release 比每次小改都 bump 要友好
- **延迟 bump**：MINOR 字段如果 90% 用户用不到，**不**急着 bump schema——可以让该字段 `state.get(field, default)` 默默 work，等下次 release 顺路 bump
- **避免 MAJOR**：能用 MINOR 解决的绝不上 MAJOR。例：与其重命名字段，不如保留旧字段 + 加新字段（旧的标 deprecated，下个 MAJOR release 才删）

---

## 备份保留策略

`/cheat-migrate` 写之前会备份到 `.cheat-state.json.backup-<timestamp>`。

备份保留多久：
- 用户跑 `/cheat-status` 时，如果有备份 + state 已稳定运行 N 天 → 提示"可以清理 N 个旧备份"
- `/cheat-init` 重 init 时清理所有旧备份（既然要重 init，老备份意义不大）
- 用户手动 `rm .cheat-state.json.backup-*` 永远 OK

不入版本控制：`.cheat-state.json.backup-*` 应在 `.gitignore` 里（已含 `.cheat-state.json` 通配规则）。