@boyingliu01/xp-gate 0.8.1 → 0.8.2

package/plugins/qoder/skills/sprint-flow/SKILL.md

@@ -247,6 +247,7 @@ ISOLATE → AUTO-ESTIMATE → THINK → PLAN → [GITHOOKS-GATE] → BUILD → R
 | 步骤 | 动作 | 说明 |
 |------|------|------|
 | 0 | **检测当前环境** | 运行 `git rev-parse --git-dir` 和 `git rev-parse --git-common-dir`。如果 `GIT_DIR != GIT_COMMON`：已在 worktree 中 → 输出 "Already in isolated worktree" → 进入 Phase 0 |
+| 0.5 | **Sprint Lock 检测（Issue #144）** | 检查 `.sprint-state/sprint.lock` 是否存在: `[ -f .sprint-state/sprint.lock ]`。如果存在: 读取锁内容，检查是否 stale（超过 24 小时或 worktree 目录不存在）→ stale → 输出 `[WARN] 发现过期 sprint lock，将覆盖` → 更新锁。非 stale → 输出 `[BLOCK] 已有活跃 sprint (ID: {sprint_id}, started: {started_at})。请先完成当前 sprint 或手动删除 .sprint-state/sprint.lock` → 退出。锁不存在 → 创建锁: `echo '{"sprint_id":"sprint-YYYY-MM-DD-NN","started_at":"<ISO8601>"}' > .sprint-state/sprint.lock` |
 | 1 | **检查保护分支** | 获取当前分支名 `git branch --show-current`。保护分支列表: `main, master, develop, trunk, mainline`。保护分支 → 强制创建 worktree。非保护分支 → 依然创建 worktree（推荐，不阻断） |
 | 2 | **创建 worktree** | 创建目录: `mkdir -p .worktrees/sprint`。检测已有 NN 编号: `ls .worktrees/sprint/ 2>/dev/null | grep -oE '[0-9]{2}$' | sort -n | tail -1`（取最后两位数字，数值排序，取最大），NN = 结果 + 1（无结果则从 01 开始）。运行 `git worktree add .worktrees/sprint/sprint-YYYY-MM-DD-NN -b sprint/YYYY-MM-DD-NN`。**注意**: `cd` 在 AI agent 单次工具调用中不保持状态，步骤 3-6 必须通过 `workdir` 参数或 `&&` 链式命令在新 worktree 目录下执行 |
 | 3 | **项目 setup** | 在 worktree 目录下: 检测项目类型: `package.json` → `npm install`, `go.mod` → `go mod download`, `pyproject.toml` → `pip/poetry install` |
@@ -485,6 +486,25 @@ Phase 2 第一步必须执行 DELPHI-GATE 检查。没有 delphi-review APPROVED
   - 更新 `CHANGELOG.md` 添加本次变更记录（含变更类型说明：skill-only / code / mixed）
   - 验证：`git diff VERSION` 确认版本号已变更，未变更 → 阻断
   - **此规则与变更类型无关** — 纯 skill 变更（仅 .md 文件）也必须 bump PATCH，确保每次 sprint 都触发 npm 发布
+- **📋 VERSION CHANGESET（Issue #142）**: 每次 VERSION bump 必须创建原子化的 changeset 记录，确保版本变更可追溯、可审计
+  - 在 `.sprint-state/changesets/` 目录下创建 JSON 文件，文件名格式: `changeset-{YYYYMMDDHHMMSS}.json`
+  - changeset 字段:
+    ```json
+    {
+      "id": "cs_xxxxxxxx",
+      "created_at": "2026-06-07T12:00:00Z",
+      "sprint_id": "sprint-2026-06-07-01",
+      "old_version": "0.8.1.2",
+      "new_version": "0.8.2.0",
+      "change_type": "patch|minor|major",
+      "description": "brief description of changes in this bump",
+      "files_changed": ["VERSION", "CHANGELOG.md", "package.json", "src/npm-package/package.json", "plugins/claude-code/.claude-plugin/plugin.json", "plugins/opencode/package.json"],
+      "semver_note": "npm semver 3-digit: 0.8.2"
+    }
+    ```
+  - changeset 创建时机：VERSION 更新后、`sync-version.sh` 执行后、commit 前
+  - changeset 随 commit 一起提交，形成版本变更的完整审计链
+  - **用途**: 回滚时通过 changeset 精确还原版本号、CI/CD 自动确定发布范围、审核时追踪每次 bump 的原因
 - **`finishing-a-development-branch`** (superpowers) — 结构化完成流：4 选项（merge / PR / discard / keep）
 - `ship` (gstack) — 创建 PR（PR 路径时使用）
 - Phase 6 输出：PR URL（用于 Phase 7 输入）
@@ -535,7 +555,10 @@ Phase 2 第一步必须执行 DELPHI-GATE 检查。没有 delphi-review APPROVED
 6. **更新 `.sprint-state/sprint-state.json`**:
    - `phase: 8`
    - `status: "merged"` 或 `"completed"`
-7. **输出 Cleanup Report + Sprint Summary**
+7. **释放 Sprint Lock（Issue #144）**:
+   - `rm -f .sprint-state/sprint.lock`
+   - 验证锁已删除: `[ ! -f .sprint-state/sprint.lock ] || echo "[WARN] sprint lock 未能删除，请手动清理"`
+8. **输出 Cleanup Report + Sprint Summary**
 
 **执行顺序依赖**:
 ```
@@ -619,7 +642,7 @@ Phase 2 第一步必须执行 DELPHI-GATE 检查。没有 delphi-review APPROVED
 不包含前一 Phase 的完整对话、中间文件、失败尝试。
 
 **特殊场景**：
-- `--resume-from <phase>`：跳过前置 Phase，直接从指定 Phase 启动。此时要求该 Phase 的前置摘要文件已存在。例如 `--resume-from build` 要求 `phase-1-summary.md` 和 `specification.yaml` 已存在。orchestrator 仍执行 Phase Transition Gate 验证。
+- `--resume-from <phase>`：跳过前置 Phase，直接从指定 Phase 启动。**MUST 先执行 RESUME GATE（Issue #148）** 校验 sprint 状态、git 可达性和文件时效性，再执行 Phase Transition Gate 校验摘要文件格式。例如 `--resume-from build` 要求 `phase-1-summary.md` 和 `specification.yaml` 已存在且非 stale。
 - `--no-isolate`：跳过 Phase -1 ISOLATE，直接在当前分支执行。Phase 0 无 `phase--1-summary` 可用，上下文继承来源为用户原始需求 + 当前 git 状态。所有后续 Phase 的 worktree enforcement 不适用（无 worktree），但仍需保持代码隔离。
 - `next_phase_context` 中的 `{path}` 等变量占位符在实际写入时被替换为具体值。示例中的 `{path}` 应替换为实际 worktree 路径（如 `.worktrees/sprint/sprint-2026-06-01-01`）。
 
@@ -681,6 +704,9 @@ next_phase_context: "Worktree created at {path}. All subsequent edits MUST use t
 Orchestrator dispatch 下一 Phase 前必须执行验证：
 
 ```bash
+# === Phase Transition Gate ===
+
+# 1. Phase summary file validation
 SUMMARY=".sprint-state/phase-outputs/phase-${N}-summary.md"
 [ -f "$SUMMARY" ] || { echo "[BLOCK] phase-${N}-summary 不存在"; exit 1; }
 FRONTMARKERS=$(grep -c "^---" "$SUMMARY" 2>/dev/null || echo 0)
@@ -693,11 +719,118 @@ grep -q "^outputs:" "$SUMMARY" || { echo "[BLOCK] 缺少 outputs 字段"; exit 1
 grep -q "^next_phase_context:" "$SUMMARY" || { echo "[BLOCK] 缺少 next_phase_context"; exit 1; }
 CHARS=$(wc -c < "$SUMMARY" | tr -d ' ')
 [ "$CHARS" -le 40000 ] || { echo "[BLOCK] 摘要超出大小限制 (${CHARS}/40000 chars)"; exit 1; }
+
+# 2. sprint-state.json enforcement check (Issue #146)
+SPRINT_STATE=".sprint-state/sprint-state.json"
+[ -f "$SPRINT_STATE" ] || { echo "[BLOCK] sprint-state.json 不存在"; exit 1; }
+
+# Verify phase_history includes current phase with completed_at
+PHASE_HISTORY_CHECK=$(grep -c "\"phase\": $N" "$SPRINT_STATE" 2>/dev/null || echo 0)
+[ "$PHASE_HISTORY_CHECK" -gt 0 ] || {
+  echo "[BLOCK] sprint-state.json phase_history 缺少 phase $N 的记录"
+  echo "[ACTION] 在 dispatch 下一 Phase 前更新 sprint-state.json:"
+  echo "  - phase: $N"
+  echo "  - phase_history: 追加 {phase:N, status:completed, completed_at:<ISO8601>}"
+  echo "  - outputs: 追加当前 phase 的输出文件"
+  exit 1
+}
+
+# Verify completed_at is set (not null)
+COMPLETED_AT_VALUE=$(grep -A3 "\"phase\": $N" "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | grep -o '"[^"]*"$' | tr -d '"')
+[ "$COMPLETED_AT_VALUE" != "null" ] && [ -n "$COMPLETED_AT_VALUE" ] || {
+  echo "[BLOCK] sprint-state.json phase $N 的 completed_at 未设置 (null)"
+  echo "[ACTION] 设置 completed_at 为当前时间 (ISO 8601):"
+  echo "  date -u +%Y-%m-%dT%H:%M:%SZ"
+  exit 1
+}
 ```
 
 **由 orchestrator 强制执行**，不依赖 subagent 自觉遵守。
 验证失败 → BLOCK，不可 dispatch 下一 Phase。
 
+### RESUME GATE / --resume-from 断点校验（Issue #148）
+
+当使用 `--resume-from <phase>` 时，在执行 Phase Transition Gate 之前，
+orchestrator MUST 先执行以下断点校验。任何一项失败 → BLOCK，拒绝恢复。
+
+```bash
+SPRINT_STATE=".sprint-state/sprint-state.json"
+[ -f "$SPRINT_STATE" ] || { echo "[BLOCK] sprint-state.json 不存在，无法恢复"; exit 1; }
+
+# 1. Sprint ID 一致性：确认 resume 的目标 sprint 与 sprint-state.json 匹配
+SPRINT_ID=$(grep -o '"id": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+CURRENT_SPRINT_ID=$(echo "$TASK_DESCRIPTION" | md5sum | head -8 2>/dev/null || echo "unknown")
+# 实际 sprint id 由 Phase -1 生成，此处仅验证文件存在且包含 id 字段
+[ -n "$SPRINT_ID" ] || { echo "[BLOCK] sprint-state.json 缺少 id 字段"; exit 1; }
+
+# 2. 阶段顺序校验：--resume-from 的 phase 必须是最后已完成 phase 的后继
+LAST_COMPLETED_PHASE=$(grep -o '"phase": [0-9]' "$SPRINT_STATE" | tail -1 | awk '{print $2}')
+RESUME_PHASE=$((RESUME_PHASE))  # orchestrator 将 --resume-from 参数值转为整数
+[ "$RESUME_PHASE" -gt "$LAST_COMPLETED_PHASE" ] || { 
+  echo "[BLOCK] --resume-from phase ($RESUME_PHASE) 必须在最后已完成 phase ($LAST_COMPLETED_PHASE) 之后"
+  exit 1
+}
+
+# 3. Git 状态校验：isolation branch 仍然可达
+ISOLATION_BRANCH=$(grep -o '"branch": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+ISOLATION_COMMIT=$(grep -o '"created_from_commit": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+if [ -n "$ISOLATION_BRANCH" ]; then
+  git rev-parse --verify "$ISOLATION_BRANCH" >/dev/null 2>&1 || {
+    echo "[BLOCK] isolation branch '$ISOLATION_BRANCH' 已不存在（可能被删除或 force push 覆盖）"
+    exit 1
+  }
+fi
+if [ -n "$ISOLATION_COMMIT" ]; then
+  git cat-file -e "${ISOLATION_COMMIT}^{commit}" 2>/dev/null || {
+    echo "[WARN] isolation commit $ISOLATION_COMMIT 不可达（可能被 GC 或 rebase 清理），恢复后可能状态不一致"
+    # WARN 而非 BLOCK — 可继续但有风险
+  }
+fi
+
+# 4. 文件时效性校验：前置摘要文件的 mtime 不晚于其生成 phase 的完成时间
+RESUME_PREREQ_PHASE=$((RESUME_PHASE - 1))
+PREREQ_FILE=".sprint-state/phase-outputs/phase-${RESUME_PREREQ_PHASE}-summary.md"
+[ -f "$PREREQ_FILE" ] || { echo "[BLOCK] 前置摘要文件 ${PREREQ_FILE} 不存在"; exit 1; }
+
+# 提取前置 phase 的完成时间
+PREREQ_COMPLETED_AT=$(grep -A3 "\"phase\": $RESUME_PREREQ_PHASE" "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | cut -d'"' -f4)
+if [ -n "$PREREQ_COMPLETED_AT" ] && [ "$PREREQ_COMPLETED_AT" != "null" ]; then
+  FILE_MTIME=$(stat -c %Y "$PREREQ_FILE" 2>/dev/null || stat -f %m "$PREREQ_FILE" 2>/dev/null)
+  COMPLETED_EPOCH=$(date -d "$PREREQ_COMPLETED_AT" +%s 2>/dev/null || echo "")
+  if [ -n "$FILE_MTIME" ] && [ -n "$COMPLETED_EPOCH" ]; then
+    # 容忍 60 秒时钟偏差
+    [ "$FILE_MTIME" -le $((COMPLETED_EPOCH + 60)) ] || {
+      echo "[WARN] 前置摘要文件 ${PREREQ_FILE} 在 phase $RESUME_PREREQ_PHASE 完成后被修改（mtime: $(date -d @$FILE_MTIME '+%Y-%m-%d %H:%M:%S'), completed_at: $PREREQ_COMPLETED_AT）"
+      echo "[ACTION] 继续恢复前请确认修改是预期的。输入 'confirm' 继续，其他取消："
+      read USER_CONFIRM
+      [ "$USER_CONFIRM" = "confirm" ] || { echo "[BLOCK] 用户取消恢复"; exit 1; }
+    }
+  fi
+fi
+
+# 5. specification.yaml 时效性校验（仅 --resume-from build）
+SPEC_FILE="specification.yaml"
+if [ "$RESUME_PHASE" -ge 2 ] && [ -f "$SPEC_FILE" ]; then
+  SPEC_MTIME=$(stat -c %Y "$SPEC_FILE" 2>/dev/null || stat -f %m "$SPEC_FILE" 2>/dev/null)
+  PLAN_COMPLETED_AT=$(grep -A3 '"phase": 1' "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | cut -d'"' -f4)
+  if [ -n "$SPEC_MTIME" ] && [ -n "$PLAN_COMPLETED_AT" ] && [ "$PLAN_COMPLETED_AT" != "null" ]; then
+    PLAN_EPOCH=$(date -d "$PLAN_COMPLETED_AT" +%s 2>/dev/null || echo "")
+    if [ -n "$PLAN_EPOCH" ] && [ "$SPEC_MTIME" -gt $((PLAN_EPOCH + 60)) ]; then
+      echo "[WARN] specification.yaml 在 Plan phase 完成后被修改"
+      echo "[ACTION] 继续恢复前请确认 specification.yaml 的修改是预期的。输入 'confirm' 继续："
+      read USER_CONFIRM
+      [ "$USER_CONFIRM" = "confirm" ] || { echo "[BLOCK] 用户取消恢复"; exit 1; }
+    fi
+  fi
+fi
+
+echo "✅ RESUME GATE PASSED — 断点校验通过"
+# 继续执行 Phase Transition Gate
+```
+
+验证失败 → BLOCK，不可执行 `--resume-from`。
+orchestrator 必须展示失败原因并建议用户启动新 Sprint 或手动修复后重试。
+
 ### WORKTREE ENFORCEMENT（Issue #84）
 
 Phase -1 执行完毕后，**所有后续操作（Phase 0 到 Phase 8）的文件编辑、命令执行 MUST 在 worktree 目录下执行**：
@@ -796,12 +929,20 @@ Sprint state is persisted as JSON in `.sprint-state/sprint-state.json`:
 
 ### --resume-from（从某阶段继续）
 
+**前置校验**：MUST 执行 RESUME GATE（见上节）后才可 dispatch 下一 Phase。
+
 ```bash
 /sprint-flow "继续 Sprint" --resume-from build --spec specification.yaml
-# → 从 Build 恢复，但必须已有 specification.yaml + .sprint-state/delphi-reviewed.json (verdict: APPROVED)
+# → 1. 执行 RESUME GATE（校验 sprint-state + git 状态 + 文件时效性）
+# → 2. 执行 Phase Transition Gate（校验摘要文件格式）
+# → 3. 从 Build 恢复，但必须已有 specification.yaml + .sprint-state/delphi-reviewed.json (verdict: APPROVED)
 # 适用场景：中断恢复，使用已通过 delphi-review 的 specification.yaml
 ```
 
+**已知限制**：
+- `--resume-from` 校验为**尽力而为**：git commit 可被 GC 回收、文件 mtime 可被 `git checkout` 修改
+- 校验失败时 orchestrator 应输出完整诊断日志，建议用户启动新 Sprint 而非手动修补
+
 ### --phase（只执行单个阶段）
 
 ```bash
@@ -954,7 +1095,9 @@ Sprint 结束时 (Phase 6 完成):
 
 # 第二次：三天后继续
 /sprint-flow "继续开发" --resume-from build --spec docs/specification.yaml
-# → 从 Build 入口恢复，但必须已有 specification.yaml + .sprint-state/delphi-reviewed.json (verdict: APPROVED)
+# → 1. RESUME GATE：校验 sprint-state + git + 文件时效性（三天前生成的文件可能 stale）
+# → 2. Phase Transition Gate：校验摘要文件格式
+# → 3. 从 Build 入口恢复，但必须已有 specification.yaml + .sprint-state/delphi-reviewed.json (verdict: APPROVED)
 ```
 
 ### 示例 3：语言特定

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -3,7 +3,7 @@
 **Generated:** 2026-05-30
 **Commit:** 4517f2b
 **Branch:** main
-**Version:** v0.5.1
+**Version:** v0.8.1
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/skills/delphi-review/AGENTS.md

@@ -3,7 +3,7 @@
 **Generated:** 2026-05-30
 **Commit:** 4517f2b
 **Branch:** main
-**Version:** v0.5.1
+**Version:** v0.8.1
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥91% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/skills/ralph-loop/SKILL.md

@@ -323,6 +323,16 @@ Phase 0, 1, 3-6 行为完全不变。
    - 注入：当前 REQ + AC + permanent learnings + contextual learnings (最近 3 条)
    - 注入：AGENTS.md + git log --oneline -5 + 测试基础设施摘要
 
+3. **Pre-REQ snapshot（Issue #137）**
+   - 在 dispatch subagent 前记录当前 git HEAD，用于 TDD 合规的基线对比
+   ```bash
+   # 保存当前 HEAD 作为 TDD 验证基线
+   PRE_REQ_HASH=$(git rev-parse HEAD)
+   echo "[TDD-BASELINE] Pre-REQ snapshot: $PRE_REQ_HASH"
+   # 记录到临时文件（subagent 只读基线，避免污染）
+   echo "$PRE_REQ_HASH" > .sprint-state/last-req-baseline.txt
+   ```
+
 3. **Dispatch build subagent**
    - 使用 `task(category="unspecified-high", load_skills=["test-driven-development"], timeout=300)`
    - 强制 TDD 流程：RED → GREEN → REFACTOR
@@ -330,7 +340,34 @@ Phase 0, 1, 3-6 行为完全不变。
 
 4. **Run full regression tests**
    - L1: typecheck + lint on changed files
-   - L1b: 检查测试先行比率 (新增测试行数 / 总新增行数 ≥ 40%)
+   - **L1b: 客观测试先行验证（Issue #137）** — 使用 git diff 验证新增测试行数占总新增行数比例
+     ```bash
+     # 从基线读取 pre-REQ HEAD，支持跨多个 commit 的 REQ
+     PRE_BASELINE=$(cat .sprint-state/last-req-baseline.txt 2>/dev/null || echo "HEAD~1")
+     GIT_DIFF=$(git diff "$PRE_BASELINE"..HEAD --stat --diff-filter=AM 2>/dev/null)
+     # 提取新增测试行数（*.test.*, *.spec.*, __tests__/* 等）
+     TEST_LINES=$(echo "$GIT_DIFF" | grep -E '\.(test|spec)\.[a-z]+|__tests__/' | grep -oP '\d+(?= insertion)' | paste -sd+ | bc || echo 0)
+     # 提取总新增行数
+     TOTAL_LINES=$(echo "$GIT_DIFF" | grep -oP '\d+(?= insertion)' | paste -sd+ | bc || echo 0)
+     # 计算比率
+     if [ "$TOTAL_LINES" -gt 0 ]; then
+       RATIO=$((TEST_LINES * 100 / TOTAL_LINES))
+       echo "[TDD-CHECK] Test lines: $TEST_LINES / Total lines: $TOTAL_LINES = ${RATIO}%"
+       [ "$RATIO" -ge 40 ] || {
+         echo "[TDD-FAIL] Test-first ratio ${RATIO}% < 40% threshold"
+         echo "[TDD-FAIL] Expected ≥ 40% test lines. Retry with tests written first."
+         exit 1
+       }
+     else
+       echo "[TDD-CHECK] No new lines in diff (possibly no changes or first commit)"
+     fi
+     ```
+   - **L1b-alt: 测试文件存在验证** — 当 diff 为空或无新增行时，降级检查测试文件是否出现在 changeset 中
+     ```bash
+     HAS_TEST_FILES=$(echo "$GIT_DIFF" | grep -c -E '\.(test|spec)\.[a-z]+|__tests__/' || echo 0)
+     [ "$HAS_TEST_FILES" -gt 0 ] || { echo "[TDD-FAIL] No test files found in changeset"; exit 1; }
+     echo "[TDD-CHECK] Test files present in changeset: $HAS_TEST_FILES file(s)"
+     ```
    - **L2: 全量测试运行**（不只是 @test 当前 REQ 的测试）
    - L3: 检查整体覆盖率 ≥ 80%
 
@@ -438,9 +475,10 @@ REQ-001 开始 → 检查 test-utils.ts → 不存在
 - [ ] Test infrastructure confirmed ready
 
 **TDD Compliance**:
-- [ ] Tests written BEFORE implementation
-- [ ] Test/implementation ratio ≥ 40%
+- [ ] Tests written BEFORE implementation (verified via `git diff HEAD~1 --stat --diff-filter=AM`)
+- [ ] Test/implementation ratio ≥ 40% (L1b check: test_lines / total_lines ≥ 40%)
 - [ ] Mock usage justified (if >30% mock density)
+- [ ] Test files present in changeset (L1b-alt fallback)
 
 **Verification Layers**:
 - [ ] L1: typecheck + lint pass

package/skills/sprint-flow/AGENTS.md

@@ -1,7 +1,7 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-05-30
-**Version:** v0.5.1
+**Version:** v0.8.1
 
 ## OVERVIEW
 7-phase development pipeline: THINK→PLAN→BUILD→REVIEW→USER ACCEPT→FEEDBACK→SHIP, with ralph-loop default build mode.

package/skills/sprint-flow/SKILL.md

@@ -247,6 +247,7 @@ ISOLATE → AUTO-ESTIMATE → THINK → PLAN → [GITHOOKS-GATE] → BUILD → R
 | 步骤 | 动作 | 说明 |
 |------|------|------|
 | 0 | **检测当前环境** | 运行 `git rev-parse --git-dir` 和 `git rev-parse --git-common-dir`。如果 `GIT_DIR != GIT_COMMON`：已在 worktree 中 → 输出 "Already in isolated worktree" → 进入 Phase 0 |
+| 0.5 | **Sprint Lock 检测（Issue #144）** | 检查 `.sprint-state/sprint.lock` 是否存在: `[ -f .sprint-state/sprint.lock ]`。如果存在: 读取锁内容，检查是否 stale（超过 24 小时或 worktree 目录不存在）→ stale → 输出 `[WARN] 发现过期 sprint lock，将覆盖` → 更新锁。非 stale → 输出 `[BLOCK] 已有活跃 sprint (ID: {sprint_id}, started: {started_at})。请先完成当前 sprint 或手动删除 .sprint-state/sprint.lock` → 退出。锁不存在 → 创建锁: `echo '{"sprint_id":"sprint-YYYY-MM-DD-NN","started_at":"<ISO8601>"}' > .sprint-state/sprint.lock` |
 | 1 | **检查保护分支** | 获取当前分支名 `git branch --show-current`。保护分支列表: `main, master, develop, trunk, mainline`。保护分支 → 强制创建 worktree。非保护分支 → 依然创建 worktree（推荐，不阻断） |
 | 2 | **创建 worktree** | 创建目录: `mkdir -p .worktrees/sprint`。检测已有 NN 编号: `ls .worktrees/sprint/ 2>/dev/null | grep -oE '[0-9]{2}$' | sort -n | tail -1`（取最后两位数字，数值排序，取最大），NN = 结果 + 1（无结果则从 01 开始）。运行 `git worktree add .worktrees/sprint/sprint-YYYY-MM-DD-NN -b sprint/YYYY-MM-DD-NN`。**注意**: `cd` 在 AI agent 单次工具调用中不保持状态，步骤 3-6 必须通过 `workdir` 参数或 `&&` 链式命令在新 worktree 目录下执行 |
 | 3 | **项目 setup** | 在 worktree 目录下: 检测项目类型: `package.json` → `npm install`, `go.mod` → `go mod download`, `pyproject.toml` → `pip/poetry install` |
@@ -485,6 +486,25 @@ Phase 2 第一步必须执行 DELPHI-GATE 检查。没有 delphi-review APPROVED
   - 更新 `CHANGELOG.md` 添加本次变更记录（含变更类型说明：skill-only / code / mixed）
   - 验证：`git diff VERSION` 确认版本号已变更，未变更 → 阻断
   - **此规则与变更类型无关** — 纯 skill 变更（仅 .md 文件）也必须 bump PATCH，确保每次 sprint 都触发 npm 发布
+- **📋 VERSION CHANGESET（Issue #142）**: 每次 VERSION bump 必须创建原子化的 changeset 记录，确保版本变更可追溯、可审计
+  - 在 `.sprint-state/changesets/` 目录下创建 JSON 文件，文件名格式: `changeset-{YYYYMMDDHHMMSS}.json`
+  - changeset 字段:
+    ```json
+    {
+      "id": "cs_xxxxxxxx",
+      "created_at": "2026-06-07T12:00:00Z",
+      "sprint_id": "sprint-2026-06-07-01",
+      "old_version": "0.8.1.2",
+      "new_version": "0.8.2.0",
+      "change_type": "patch|minor|major",
+      "description": "brief description of changes in this bump",
+      "files_changed": ["VERSION", "CHANGELOG.md", "package.json", "src/npm-package/package.json", "plugins/claude-code/.claude-plugin/plugin.json", "plugins/opencode/package.json"],
+      "semver_note": "npm semver 3-digit: 0.8.2"
+    }
+    ```
+  - changeset 创建时机：VERSION 更新后、`sync-version.sh` 执行后、commit 前
+  - changeset 随 commit 一起提交，形成版本变更的完整审计链
+  - **用途**: 回滚时通过 changeset 精确还原版本号、CI/CD 自动确定发布范围、审核时追踪每次 bump 的原因
 - **`finishing-a-development-branch`** (superpowers) — 结构化完成流：4 选项（merge / PR / discard / keep）
 - `ship` (gstack) — 创建 PR（PR 路径时使用）
 - Phase 6 输出：PR URL（用于 Phase 7 输入）
@@ -535,7 +555,10 @@ Phase 2 第一步必须执行 DELPHI-GATE 检查。没有 delphi-review APPROVED
 6. **更新 `.sprint-state/sprint-state.json`**:
    - `phase: 8`
    - `status: "merged"` 或 `"completed"`
-7. **输出 Cleanup Report + Sprint Summary**
+7. **释放 Sprint Lock（Issue #144）**:
+   - `rm -f .sprint-state/sprint.lock`
+   - 验证锁已删除: `[ ! -f .sprint-state/sprint.lock ] || echo "[WARN] sprint lock 未能删除，请手动清理"`
+8. **输出 Cleanup Report + Sprint Summary**
 
 **执行顺序依赖**:
 ```
@@ -619,7 +642,7 @@ Phase 2 第一步必须执行 DELPHI-GATE 检查。没有 delphi-review APPROVED
 不包含前一 Phase 的完整对话、中间文件、失败尝试。
 
 **特殊场景**：
-- `--resume-from <phase>`：跳过前置 Phase，直接从指定 Phase 启动。此时要求该 Phase 的前置摘要文件已存在。例如 `--resume-from build` 要求 `phase-1-summary.md` 和 `specification.yaml` 已存在。orchestrator 仍执行 Phase Transition Gate 验证。
+- `--resume-from <phase>`：跳过前置 Phase，直接从指定 Phase 启动。**MUST 先执行 RESUME GATE（Issue #148）** 校验 sprint 状态、git 可达性和文件时效性，再执行 Phase Transition Gate 校验摘要文件格式。例如 `--resume-from build` 要求 `phase-1-summary.md` 和 `specification.yaml` 已存在且非 stale。
 - `--no-isolate`：跳过 Phase -1 ISOLATE，直接在当前分支执行。Phase 0 无 `phase--1-summary` 可用，上下文继承来源为用户原始需求 + 当前 git 状态。所有后续 Phase 的 worktree enforcement 不适用（无 worktree），但仍需保持代码隔离。
 - `next_phase_context` 中的 `{path}` 等变量占位符在实际写入时被替换为具体值。示例中的 `{path}` 应替换为实际 worktree 路径（如 `.worktrees/sprint/sprint-2026-06-01-01`）。
 
@@ -681,6 +704,9 @@ next_phase_context: "Worktree created at {path}. All subsequent edits MUST use t
 Orchestrator dispatch 下一 Phase 前必须执行验证：
 
 ```bash
+# === Phase Transition Gate ===
+
+# 1. Phase summary file validation
 SUMMARY=".sprint-state/phase-outputs/phase-${N}-summary.md"
 [ -f "$SUMMARY" ] || { echo "[BLOCK] phase-${N}-summary 不存在"; exit 1; }
 FRONTMARKERS=$(grep -c "^---" "$SUMMARY" 2>/dev/null || echo 0)
@@ -693,11 +719,118 @@ grep -q "^outputs:" "$SUMMARY" || { echo "[BLOCK] 缺少 outputs 字段"; exit 1
 grep -q "^next_phase_context:" "$SUMMARY" || { echo "[BLOCK] 缺少 next_phase_context"; exit 1; }
 CHARS=$(wc -c < "$SUMMARY" | tr -d ' ')
 [ "$CHARS" -le 40000 ] || { echo "[BLOCK] 摘要超出大小限制 (${CHARS}/40000 chars)"; exit 1; }
+
+# 2. sprint-state.json enforcement check (Issue #146)
+SPRINT_STATE=".sprint-state/sprint-state.json"
+[ -f "$SPRINT_STATE" ] || { echo "[BLOCK] sprint-state.json 不存在"; exit 1; }
+
+# Verify phase_history includes current phase with completed_at
+PHASE_HISTORY_CHECK=$(grep -c "\"phase\": $N" "$SPRINT_STATE" 2>/dev/null || echo 0)
+[ "$PHASE_HISTORY_CHECK" -gt 0 ] || {
+  echo "[BLOCK] sprint-state.json phase_history 缺少 phase $N 的记录"
+  echo "[ACTION] 在 dispatch 下一 Phase 前更新 sprint-state.json:"
+  echo "  - phase: $N"
+  echo "  - phase_history: 追加 {phase:N, status:completed, completed_at:<ISO8601>}"
+  echo "  - outputs: 追加当前 phase 的输出文件"
+  exit 1
+}
+
+# Verify completed_at is set (not null)
+COMPLETED_AT_VALUE=$(grep -A3 "\"phase\": $N" "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | grep -o '"[^"]*"$' | tr -d '"')
+[ "$COMPLETED_AT_VALUE" != "null" ] && [ -n "$COMPLETED_AT_VALUE" ] || {
+  echo "[BLOCK] sprint-state.json phase $N 的 completed_at 未设置 (null)"
+  echo "[ACTION] 设置 completed_at 为当前时间 (ISO 8601):"
+  echo "  date -u +%Y-%m-%dT%H:%M:%SZ"
+  exit 1
+}
 ```
 
 **由 orchestrator 强制执行**，不依赖 subagent 自觉遵守。
 验证失败 → BLOCK，不可 dispatch 下一 Phase。
 
+### RESUME GATE / --resume-from 断点校验（Issue #148）
+
+当使用 `--resume-from <phase>` 时，在执行 Phase Transition Gate 之前，
+orchestrator MUST 先执行以下断点校验。任何一项失败 → BLOCK，拒绝恢复。
+
+```bash
+SPRINT_STATE=".sprint-state/sprint-state.json"
+[ -f "$SPRINT_STATE" ] || { echo "[BLOCK] sprint-state.json 不存在，无法恢复"; exit 1; }
+
+# 1. Sprint ID 一致性：确认 resume 的目标 sprint 与 sprint-state.json 匹配
+SPRINT_ID=$(grep -o '"id": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+CURRENT_SPRINT_ID=$(echo "$TASK_DESCRIPTION" | md5sum | head -8 2>/dev/null || echo "unknown")
+# 实际 sprint id 由 Phase -1 生成，此处仅验证文件存在且包含 id 字段
+[ -n "$SPRINT_ID" ] || { echo "[BLOCK] sprint-state.json 缺少 id 字段"; exit 1; }
+
+# 2. 阶段顺序校验：--resume-from 的 phase 必须是最后已完成 phase 的后继
+LAST_COMPLETED_PHASE=$(grep -o '"phase": [0-9]' "$SPRINT_STATE" | tail -1 | awk '{print $2}')
+RESUME_PHASE=$((RESUME_PHASE))  # orchestrator 将 --resume-from 参数值转为整数
+[ "$RESUME_PHASE" -gt "$LAST_COMPLETED_PHASE" ] || { 
+  echo "[BLOCK] --resume-from phase ($RESUME_PHASE) 必须在最后已完成 phase ($LAST_COMPLETED_PHASE) 之后"
+  exit 1
+}
+
+# 3. Git 状态校验：isolation branch 仍然可达
+ISOLATION_BRANCH=$(grep -o '"branch": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+ISOLATION_COMMIT=$(grep -o '"created_from_commit": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+if [ -n "$ISOLATION_BRANCH" ]; then
+  git rev-parse --verify "$ISOLATION_BRANCH" >/dev/null 2>&1 || {
+    echo "[BLOCK] isolation branch '$ISOLATION_BRANCH' 已不存在（可能被删除或 force push 覆盖）"
+    exit 1
+  }
+fi
+if [ -n "$ISOLATION_COMMIT" ]; then
+  git cat-file -e "${ISOLATION_COMMIT}^{commit}" 2>/dev/null || {
+    echo "[WARN] isolation commit $ISOLATION_COMMIT 不可达（可能被 GC 或 rebase 清理），恢复后可能状态不一致"
+    # WARN 而非 BLOCK — 可继续但有风险
+  }
+fi
+
+# 4. 文件时效性校验：前置摘要文件的 mtime 不晚于其生成 phase 的完成时间
+RESUME_PREREQ_PHASE=$((RESUME_PHASE - 1))
+PREREQ_FILE=".sprint-state/phase-outputs/phase-${RESUME_PREREQ_PHASE}-summary.md"
+[ -f "$PREREQ_FILE" ] || { echo "[BLOCK] 前置摘要文件 ${PREREQ_FILE} 不存在"; exit 1; }
+
+# 提取前置 phase 的完成时间
+PREREQ_COMPLETED_AT=$(grep -A3 "\"phase\": $RESUME_PREREQ_PHASE" "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | cut -d'"' -f4)
+if [ -n "$PREREQ_COMPLETED_AT" ] && [ "$PREREQ_COMPLETED_AT" != "null" ]; then
+  FILE_MTIME=$(stat -c %Y "$PREREQ_FILE" 2>/dev/null || stat -f %m "$PREREQ_FILE" 2>/dev/null)
+  COMPLETED_EPOCH=$(date -d "$PREREQ_COMPLETED_AT" +%s 2>/dev/null || echo "")
+  if [ -n "$FILE_MTIME" ] && [ -n "$COMPLETED_EPOCH" ]; then
+    # 容忍 60 秒时钟偏差
+    [ "$FILE_MTIME" -le $((COMPLETED_EPOCH + 60)) ] || {
+      echo "[WARN] 前置摘要文件 ${PREREQ_FILE} 在 phase $RESUME_PREREQ_PHASE 完成后被修改（mtime: $(date -d @$FILE_MTIME '+%Y-%m-%d %H:%M:%S'), completed_at: $PREREQ_COMPLETED_AT）"
+      echo "[ACTION] 继续恢复前请确认修改是预期的。输入 'confirm' 继续，其他取消："
+      read USER_CONFIRM
+      [ "$USER_CONFIRM" = "confirm" ] || { echo "[BLOCK] 用户取消恢复"; exit 1; }
+    }
+  fi
+fi
+
+# 5. specification.yaml 时效性校验（仅 --resume-from build）
+SPEC_FILE="specification.yaml"
+if [ "$RESUME_PHASE" -ge 2 ] && [ -f "$SPEC_FILE" ]; then
+  SPEC_MTIME=$(stat -c %Y "$SPEC_FILE" 2>/dev/null || stat -f %m "$SPEC_FILE" 2>/dev/null)
+  PLAN_COMPLETED_AT=$(grep -A3 '"phase": 1' "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | cut -d'"' -f4)
+  if [ -n "$SPEC_MTIME" ] && [ -n "$PLAN_COMPLETED_AT" ] && [ "$PLAN_COMPLETED_AT" != "null" ]; then
+    PLAN_EPOCH=$(date -d "$PLAN_COMPLETED_AT" +%s 2>/dev/null || echo "")
+    if [ -n "$PLAN_EPOCH" ] && [ "$SPEC_MTIME" -gt $((PLAN_EPOCH + 60)) ]; then
+      echo "[WARN] specification.yaml 在 Plan phase 完成后被修改"
+      echo "[ACTION] 继续恢复前请确认 specification.yaml 的修改是预期的。输入 'confirm' 继续："
+      read USER_CONFIRM
+      [ "$USER_CONFIRM" = "confirm" ] || { echo "[BLOCK] 用户取消恢复"; exit 1; }
+    fi
+  fi
+fi
+
+echo "✅ RESUME GATE PASSED — 断点校验通过"
+# 继续执行 Phase Transition Gate
+```
+
+验证失败 → BLOCK，不可执行 `--resume-from`。
+orchestrator 必须展示失败原因并建议用户启动新 Sprint 或手动修复后重试。
+
 ### WORKTREE ENFORCEMENT（Issue #84）
 
 Phase -1 执行完毕后，**所有后续操作（Phase 0 到 Phase 8）的文件编辑、命令执行 MUST 在 worktree 目录下执行**：
@@ -796,12 +929,20 @@ Sprint state is persisted as JSON in `.sprint-state/sprint-state.json`:
 
 ### --resume-from（从某阶段继续）
 
+**前置校验**：MUST 执行 RESUME GATE（见上节）后才可 dispatch 下一 Phase。
+
 ```bash
 /sprint-flow "继续 Sprint" --resume-from build --spec specification.yaml
-# → 从 Build 恢复，但必须已有 specification.yaml + .sprint-state/delphi-reviewed.json (verdict: APPROVED)
+# → 1. 执行 RESUME GATE（校验 sprint-state + git 状态 + 文件时效性）
+# → 2. 执行 Phase Transition Gate（校验摘要文件格式）
+# → 3. 从 Build 恢复，但必须已有 specification.yaml + .sprint-state/delphi-reviewed.json (verdict: APPROVED)
 # 适用场景：中断恢复，使用已通过 delphi-review 的 specification.yaml
 ```
 
+**已知限制**：
+- `--resume-from` 校验为**尽力而为**：git commit 可被 GC 回收、文件 mtime 可被 `git checkout` 修改
+- 校验失败时 orchestrator 应输出完整诊断日志，建议用户启动新 Sprint 而非手动修补
+
 ### --phase（只执行单个阶段）
 
 ```bash
@@ -954,7 +1095,9 @@ Sprint 结束时 (Phase 6 完成):
 
 # 第二次：三天后继续
 /sprint-flow "继续开发" --resume-from build --spec docs/specification.yaml
-# → 从 Build 入口恢复，但必须已有 specification.yaml + .sprint-state/delphi-reviewed.json (verdict: APPROVED)
+# → 1. RESUME GATE：校验 sprint-state + git + 文件时效性（三天前生成的文件可能 stale）
+# → 2. Phase Transition Gate：校验摘要文件格式
+# → 3. 从 Build 入口恢复，但必须已有 specification.yaml + .sprint-state/delphi-reviewed.json (verdict: APPROVED)
 ```
 
 ### 示例 3：语言特定

package/skills/test-specification-alignment/AGENTS.md

@@ -3,7 +3,7 @@
 **Generated:** 2026-05-30
 **Commit:** 4517f2b
 **Branch:** main
-**Version:** v0.5.1
+**Version:** v0.8.1
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.