checkpoint-commit

Checkpoint Commit · 步骤级提交

DDT 步骤级 commit 范式：每个 plan step 完成（validation 通过）后创建 git checkpoint commit，记录到 .ddt/checkpoints.log

M6.4 整改：v0.6.x backend-agent 一次性大 commit，出问题难回滚。 v0.7.0 改 main thread + 每 step checkpoint，让回滚到"上一个绿色状态"成为一行 git revert。

Triggers

• /build-api / /build-web IMPLEMENT phase 的每个 plan step 完成后
• /fix --apply 每条 patch apply 成功后
• 任何 main thread 跑通 validation-loop 后想"标记一个绿色检查点"时

Core Philosophy

每个 step 一个 commit：不是"写到差不多再 commit"，而是"validation 通过即 commit"。 这样回滚永远精确——git revert <sha> 能精准撤销某一步而不影响其他。

Commit message 规范

格式：

<phase>(<step-id>): <短描述>

<可选 body：详细描述本 step 做了什么>

- step: <step 编号或 ID>
- validation: <validation-loop 跑了什么 + 结果>
- files: <改动文件列表，最多 5 个，超过显示 N more>

Checkpoint-Phase: <phase>
Checkpoint-Step: <step>
Checkpoint-Validation: passed

例：

build-api(P1.2): implement task service business logic

实现了 TaskService 类，包含 create / list / update 三个方法，
对应契约的 POST/GET/PATCH /tasks endpoint。错误用 throws 抛出，
统一由 errorHandler 中间件转 4xx/5xx。

- step: P1.2
- validation: tsc --noEmit OK + jest src/services/taskService.spec.ts (3/3 passed)
- files: server/src/services/taskService.ts, server/src/services/taskService.spec.ts

Checkpoint-Phase: build-api
Checkpoint-Step: P1.2
Checkpoint-Validation: passed

.ddt/checkpoints.log 格式

每个 checkpoint commit 后，追加一行到 .ddt/checkpoints.log：

2026-04-29T10:23:00Z | build-api | P1.1 | abc1234 | db layer
2026-04-29T10:25:30Z | build-api | P1.2 | def5678 | task service
2026-04-29T10:30:00Z | build-api | P1.3 | 1234abc | tasks routes
2026-04-29T10:32:00Z | build-web | P2.1 | 5678def | api client

字段：<ISO timestamp> | <phase> | <step-id> | <git short SHA> | <短描述>

实施流程

main thread 在 validation-loop 通过后：

# 1. 收集改动文件
FILES=$(git diff --cached --name-only HEAD)

# 2. 构造 commit message
PHASE="build-api"          # 当前 phase
STEP="P1.2"                 # 当前 step ID
DESC="implement task service business logic"
VALIDATION="tsc OK + jest 3/3"

# 3. git add + commit
git add $FILES
git commit -m "$(cat <<EOF
${PHASE}(${STEP}): ${DESC}

- step: ${STEP}
- validation: ${VALIDATION}
- files: ${FILES}

Checkpoint-Phase: ${PHASE}
Checkpoint-Step: ${STEP}
Checkpoint-Validation: passed
EOF
)"

# 4. 追加 checkpoints.log
SHA=$(git rev-parse --short HEAD)
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
echo "${TS} | ${PHASE} | ${STEP} | ${SHA} | ${DESC}" >> .ddt/checkpoints.log