spec-driven-checkpoint

为 spec-driven-dev 提供流程中断保存与恢复能力。在任意阶段触发 checkpoint 保存当前 Git 快照、迭代状态、Session 元数据和上下文重建包；rollback 命令可将 Git 仓库和 Agent 上下文恢复到任意历史 checkpoint。支持 save_checkpoint-{us_id} 和 rollback {ckpt_id} 触发。

# spec-driven-checkpoint

> **设计前言 — 可行性分析**
>
> 在实现之前，必须明确 Coding Agent Session 的真实限制，以便选择最可靠的技术路径。

---

## 可行性分析

### 五个核心问题的可行性评估

| 问题 | 可行性 | 限制与解法 |
|------|--------|-----------|
| **保存 Git 快照** | ✅ 完全可行 | `git commit` + `git tag ckpt-{id}` — 成熟方案，完全可靠 |
| **保存阶段/迭代状态** | ✅ 完全可行 | 写入结构化 Markdown 文件，与 `current_iter.md` 同等可靠 |
| **捕获 Session ID** | ⚠️ 环境依赖 | OpenCode 通过 `$OPENCODE_SESSION_ID` 暴露；Claude Code CLI 通过 `$CLAUDE_SESSION_ID`；无法获取时生成本地 fallback UUID |
| **真正恢复对话历史** | ❌ 不可行 | **所有主流 Coding Agent（OpenCode、Claude Code、Cursor）均不支持跨 Session 导入原始对话历史**。对话历史存在 Agent 运行时内存中，进程退出即消失，无对外持久化 API |
| **上下文语义恢复** | ✅ 完全可行 | 用「重建 Prompt 包」替代原始历史。将关键决策、修复记录、状态快照压缩为结构化 Markdown，作为新 Session 的首条 context 注入，使新 Session 能精确接续工作 |

### 关键设计选择：重建 Prompt 而非回放历史

真正恢复对话历史在技术层面不可行，但**对话历史本身并非目标**——目标是让新 Session 知道：
1. 在做什么（任务/阶段/迭代）
2. 做到哪了（完成的文件、通过的测试）
3. 遇到什么问题（失败记录、待修复项）
4. 接下来要做什么（明确的下一步指令）

这四点完全可以通过结构化文档重建，效果等同于甚至优于原始对话历史（因为噪音更少）。

### Rollback 可行性

| 操作 | 可行性 | 实现 |
|------|--------|------|
| Git 仓库回滚 | ✅ | `git reset --hard ckpt-{id}` 或 `git checkout ckpt-{id}` |
| 恢复 working tree 文件 | ✅ | 附带 git reset |
| 恢复 Session 上下文 | ✅ | 将 checkpoint 文档作为新 Session 首条 context 注入 |
| 恢复原始 Session | ❌ | 技术不可行，用「重建 Session」替代 |

---

## 最终架构决策

```
checkpoint 保存
  ├─ [Git 层]     git commit(WIP) + git tag ckpt-{id}    ← 代码快照，硬保证
  ├─ [状态层]     写入 checkpoints/{ckpt_id}.md          ← 结构化状态文档
  └─ [重建层]     生成 resume_prompt 块                  ← 新 Session 启动包

rollback {ckpt_id}
  ├─ [Git 层]     git reset --hard ckpt-{id}             ← 代码回滚
  ├─ [状态层]     恢复 current_iter.md 快照              ← 状态回滚
  └─ [重建层]     输出 RESUME_CONTEXT 块                 ← 新 Session 启动
```

---

## 前置依赖

| 工具 | 用途 |
|------|------|
| `git` | 提交、打标签、reset、log |

---

## 路径常量

```
requirements/{us_id}/docs/checkpoints/                   ← checkpoint 目录
requirements/{us_id}/docs/checkpoints/index.md           ← 所有 checkpoint 索引
requirements/{us_id}/docs/checkpoints/{ckpt_id}.md       ← 单个 checkpoint 文档
```

**Checkpoint ID 格式：** `ckpt-{YYYYMMDD}-{HHmmss}-{8位hex}`
- 示例：`ckpt-20240115-143022-a3f8b21c`
- 8 位 hex 由 `git rev-parse --short=8 HEAD` 或随机生成提供
- 全局唯一，不依赖 Session ID

**Git Tag 格式：** `checkpoint/{ckpt_id}`
- 示例：`refs/tags/checkpoint/ckpt-20240115-143022-a3f8b21c`

---

## 触发方式

| 触发命令 | 含义 |
|---------|------|
| `save_checkpoint-{us_id}` | 手动保存 checkpoint |
| `checkpoint-{us_id}` | 同上（别名） |
| `rollback {ckpt_id}` | 回滚到指定 checkpoint |
| `rollback {ckpt_id} --git-only` | 仅回滚 Git，不输出重建 Prompt |
| `rollback {ckpt_id} --context-only` | 仅输出重建 Prompt，不操作 Git |
| `list_checkpoints-{us_id}` | 列出所有 checkpoint |

**自动触发（由 spec-driven-dev 在检测到以下情况时调用）：**
- 质量门控连续失败 3 次（`bugfix` 阶段自动保存）
- `code_review` 返回 `REQUEST_CHANGES` 前自动保存
- 任意阶段 `CHECKPOINT … STATUS=FAIL` 连续出现 3 次

---

## 操作一：保存 Checkpoint

### 输入参数

| 参数 | 类型 | 必须 | 说明 |
|------|------|------|------|
| `us_id` | string | 是 | 用户故事 ID |
| `iter_id` | string | 是 | 当前迭代 ID |
| `stage` | string | 是 | 中断时所在阶段 |
| `interrupt_reason` | string | 否 | 中断原因描述；自动触发时由调用方填入 |
| `session_id` | string | 否 | Agent 运行时 Session ID；从环境变量读取 |
| `pending_items` | string | 否 | 未完成事项列表（自由文本） |
| `context` | string | 否 | 额外补充上下文 |

### 执行步骤

#### Step S-0 — 生成 Checkpoint ID

```bash
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
GIT_SHORT=$(git rev-parse --short=8 HEAD 2>/dev/null || openssl rand -hex 4)
CKPT_ID="ckpt-${TIMESTAMP}-${GIT_SHORT}"
```

#### Step S-1 — 捕获 Session ID

```bash
# 优先级：OpenCode → Claude Code → 环境变量 → 本地生成
SESSION_ID="${OPENCODE_SESSION_ID:-${CLAUDE_SESSION_ID:-${AGENT_SESSION_ID:-}}}"
if [ -z "$SESSION_ID" ]; then
  SESSION_ID="local-$(date +%s)-$(openssl rand -hex 4)"
fi
```

> Session ID 仅作为**元数据追溯**使用，不用于恢复原始会话。

#### Step S-2 — 保存 Git 快照

```bash
# 1. 暂存所有当前修改（包括未 commit 的 WIP）
git add -A

# 2. 检查是否有变更需要提交
if ! git diff --cached --quiet; then
  git commit -m "checkpoint(#{us_id}/{iter_id}): ${CKPT_ID} WIP auto-save"
fi

# 3. 打轻量标签，记录代码状态
git tag "checkpoint/${CKPT_ID}"

# 记录提交 SHA（即使无新提交也记录当前 HEAD）
GIT_SHA=$(git rev-parse HEAD)
GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
```

#### Step S-3 — 采集状态快照

```bash
# 采集以下信息用于写入 checkpoint 文档
MODIFIED_FILES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || git diff --name-only)
TEST_STATUS="从 requirements/{us_id}/docs/reports/test-{us_id}-report.md 读取最后测试状态"
ITER_SUMMARY="从 requirements/{us_id}/docs/iteration_summary/current_iter.md 读取全文"
```

#### Step S-4 — 写入 Checkpoint 文档

写入 `requirements/{us_id}/docs/checkpoints/{ckpt_id}.md`，使用下方**文档模板**。

#### Step S-5 — 更新索引

在 `requirements/{us_id}/docs/checkpoints/index.md` 追加一行：

```markdown
| {ckpt_id} | {YYYY-MM-DD HH:mm:ss} | {stage} | {iter_id} | {interrupt_reason} | {git_sha_short} |
```

#### Step S-6 — 推送标签到远端（可选）

```bash
git push origin "checkpoint/${CKPT_ID}"
```

```
[SKILL:spec-driven-checkpoint] CHECKPOINT saved STATUS=OK  id={ckpt_id}  git_sha={sha}
```

---

## Checkpoint 文档模板

````markdown
---
ckpt_id: {ckpt_id}
session_id: {session_id}
created_at: YYYY-MM-DD HH:mm:ss
us_id: {us_id}
iter_id: {iter_id}
stage: {stage}
interrupt_reason: {interrupt_reason}
git_sha: {git_sha}
git_branch: {git_branch}
git_tag: checkpoint/{ckpt_id}
status: ACTIVE
---

# Checkpoint {ckpt_id}

> **恢复此 checkpoint 请执行：** `rollback {ckpt_id}`

---

## 1. 中断上下文摘要

**中断阶段：** {stage}  
**中断时间：** YYYY-MM-DD HH:mm:ss  
**中断原因：** {interrupt_reason}  
**迭代进度：** {iter_id} — 已完成 N/M 个任务  
**Session ID：** {session_id}（仅作追溯，不用于会话恢复）

---

## 2. Git 状态快照

**提交 SHA：** `{git_sha}`  
**分支：** `{git_branch}`  
**Git Tag：** `checkpoint/{ckpt_id}`  

**本次中断前变更的文件：**
```
{modified_files_list}
```

**恢复 Git 状态命令：**
```bash
git reset --hard checkpoint/{ckpt_id}
# 或
git checkout -b restore/{ckpt_id} checkpoint/{ckpt_id}
```

---

## 3. 迭代状态快照

> 以下为中断时 current_iter.md 的完整内容副本

```markdown
{iter_summary_full_text}
```

---

## 4. 已完成任务

| 任务 ID | 描述 | 状态 | 关键文件 |
|---------|------|------|---------|
| task-1  | …    | ✅   | src/… |
| task-2  | …    | 🔄 进行中 | src/… |

---

## 5. 中断时的问题与修复记录

> 记录中断前的错误、尝试过的修复方案、已知结论

```
{pending_issues_and_fixes}
```

---

## 6. 待完成事项

> 恢复后需要立即处理的任务

- [ ] {pending_item_1}
- [ ] {pending_item_2}
- [ ] …

---

## 7. 重建 Prompt 包（RESUME_CONTEXT）

> ⚠️ 这是恢复 Agent Session 的核心。将此块完整粘贴/注入到新 Session 的第一条消息。

```
═══════════════════════════════════════════════════════
RESUME_CONTEXT — spec-driven-dev 会话恢复包
Checkpoint ID : {ckpt_id}
恢复时间      : {restore_timestamp}
═══════════════════════════════════════════════════════

## 你正在做什么

你是 spec-driven-dev Agent，正在处理用户故事 {us_id}。
你在 {stage} 阶段中断，中断原因：{interrupt_reason}。

当前 Git 分支：{git_branch}（代码已通过 git reset 恢复到中断时状态）

## 已完成的工作

{completed_tasks_summary}

## 中断时的状态

{interrupt_state_detail}

## 遇到的问题与已尝试的修复

{issues_and_fixes_summary}

## 接下来你需要做的

1. {next_action_1}
2. {next_action_2}
3. 继续从 {stage} 阶段的第 {resume_step} 步开始执行

## 关键文件状态

{key_files_status}

## 当前迭代摘要（来自 current_iter.md）

{iter_summary_condensed}

═══════════════════════════════════════════════════════
END RESUME_CONTEXT
恢复后请立即输出：[RESUMED FROM {ckpt_id}] 确认收到上下文
═══════════════════════════════════════════════════════
```

---

## 8. 补充上下文

{extra_context}
````

---

## Checkpoint 索引模板

文件路径：`requirements/{us_id}/docs/checkpoints/index.md`

```markdown
# Checkpoint 索引 — {us_id}

| Checkpoint ID | 创建时间 | 阶段 | 迭代 | 中断原因 | Git SHA | 状态 |
|--------------|---------|------|------|---------|---------|------|
| ckpt-… | … | coding | iter_003 | 测试失败 | a3f8b21c | ACTIVE |
| ckpt-… | … | bugfix | iter_003 | 手动保存 | 9c2e441a | ROLLED_BACK |
```

状态值：`ACTIVE`（可用）/ `ROLLED_BACK`（已被回滚到此点）/ `SUPERSEDED`（已有更新 checkpoint）

---

## 操作二：Rollback

### 命令格式

```
rollback {ckpt_id}
rollback {ckpt_id} --git-only
rollback {ckpt_id} --context-only
```

### 执行步骤

#### Step R-0 — 读取 Checkpoint 文档

读取 `requirements/{us_id}/docs/checkpoints/{ckpt_id}.md`，提取所有元数据字段。

若文档不存在，输出：
```
[SKILL:spec-driven-checkpoint] ERROR  checkpoint {ckpt_id} 不存在
请通过 list_checkpoints-{us_id} 查看可用的 checkpoint。
```

#### Step R-1 — 安全检查

```bash
# 检查当前工作区是否有未保存的变更
if ! git diff --quiet || ! git diff --cached --quiet; then
  ec