@boyingliu01/xp-gate 0.14.0 → 0.14.1

package/lib/__tests__/update-hooks.test.js

@@ -347,10 +347,12 @@ describe('updateHooks', () => {
 
   describe('getProjectHooksDir', () => {
     it('returns .git/hooks path under cwd', () => {
+      const gitDir = path.join(tmpProject, '.git');
+      fs.mkdirSync(gitDir, { recursive: true });
+      vi.spyOn(process, 'cwd').mockReturnValue(tmpProject);
       const mod = getModule();
-      const cwd = process.cwd();
       const result = mod.getProjectHooksDir();
-      expect(result).toBe(path.join(cwd, '.git', 'hooks'));
+      expect(result).toBe(path.join(tmpProject, '.git', 'hooks'));
     });
 
     it('throws when .git/ does not exist', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "./bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 10 quality gates (Gate 0-9), Sprint Flow (11 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/claude-code/skills/sprint-flow/SKILL.md

@@ -274,8 +274,9 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 **详细指令**: 参见 `references/phase-2-design.md` — 完整流程、条件分支、HARD-GATE。
 
 **快速参考**:
+- **Step 0.5: DESIGN 路由分叉 (v0.14.0+)**: 根据 PREP 的 `change_type` 决定路径。`修改已存在代码` → SKIP autoplan, 直接 lightweight delphi-review (2 专家, 1 轮)。`新增功能` 或 undefined → 标准 autoplan 路径。详见 `references/phase-2-design.md#step-05-design-路由分叉`。
 - **Step 1: brainstorming** — `skill(name="brainstorming")` — 输出设计文档 + CONTEXT.md + ADR。**HARD-GATE**: 设计未批准 → 不可进入实现
-- **Step 2: autoplan** — `skill(name="autoplan")` — CEO/设计/工程自动评审 → 用户确认 taste_decisions
+- **Step 2: autoplan** — `skill(name="autoplan")` — CEO/设计/工程自动评审 → 用户确认 taste_decisions（仅标准路径）
 - **Step 3: delphi-review** — `skill(name="delphi-review")` — 等待 APPROVED（非 APPROVED 暂停等待用户确认）
 - **Step 4: to-issues** — `skill(name="to-issues")` — 垂直切片 Issue 拆分 → slices-manifest.json
 - **Step 5: specification.yaml** — 从 APPROVED 设计文档自动提取
@@ -304,10 +305,11 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 
 **快速参考**:
 1. **DELPHI-GATE**: 验证 `.sprint-state/delphi-reviewed.json` 存在且 `verdict = "APPROVED"` → 否则 BLOCK
-2. **输入**: `slices-manifest.json`（Phase 2/6 生成），按 `execution_order` 逐个执行
-3. **模式**: 默认 `ralph-loop`（逐 REQ 迭代，token 节约 40-67%），可选 `--mode parallel`
-4. **Skill 步骤**: hooks-install → dispatching-parallel-agents → TDD (RED/GREEN/REFACTOR) → freeze → blind-review → unfreeze → verification-before-completion → 成本监控
-5. **Mock Minimization**: integration-first, mock 仅限 external services, 密度 > 30% 需 `@mock-justified`
+2. **TDD-GATE (MANDATORY — v0.14.0+)**: 在 delegation 前验证每个 REQ 存在 failing test。无 test → mark `[TDD-RED]`（ralph-loop 创建）。有 test 且 GREEN 且无实现 → BLOCK（TDD bypass）。详见 `references/phase-3-build.md#tdd-gate-pre-implementation-tdd-check-mandatory`。
+3. **输入**: `slices-manifest.json`（Phase 2/6 生成），按 `execution_order` 逐个执行
+4. **模式**: 默认 `ralph-loop`（逐 REQ 迭代，token 节约 40-67%），可选 `--mode parallel`
+5. **Skill 步骤**: hooks-install → TDD-GATE → dispatching-parallel-agents → TDD (RED/GREEN/REFACTOR) → freeze → blind-review → unfreeze → verification-before-completion → 成本监控
+6. **Mock Minimization**: integration-first, mock 仅限 external services, 密度 > 30% 需 `@mock-justified`
 
 ### Phase 4/6: VERIFY (验证 — 代码走查 + QA + 反馈获取)
 
@@ -336,17 +338,20 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 
 **对应旧模型**: Phase 5 SHIP + Phase 6 LAND
 
-**详细指令**: 参见 `references/phase-5-ship.md` — GITHOOKS-GATE / VERSION-GATE / VERSION CHANGESET (Issue #142) / changeset schema。
+**详细指令**: 参见 `references/phase-5-ship.md` — VERSION-GATE (MANDATORY) / finishing-a-development-branch / VERSION CHANGESET (Issue #142) / changeset schema。
 
 **快速参考**:
-- **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill（4 选项菜单 + PR 确认），**必须由 orchestrator 直接调用** `skill(name="finishing-a-development-branch")` 和 `skill(name="ship")`
-- 输入: phase-4-summary.md + feedback-log.md → 输出: PR URL
+- **Step 0: VERSION-GATE (MANDATORY — 必须在 finishing-a-development-branch 之前)**: bump VERSION → update CHANGELOG.md → run sync-version.sh → commit + push → verify PR updated。详见 `references/phase-5-ship.md#step-0-version-gate`
+- **Step 1: finishing-a-development-branch**: 4 选项菜单，选择 "Push and create a Pull Request"
+- **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill，**必须由 orchestrator 直接调用** `skill(name="finishing-a-development-branch")` 和 `skill(name="ship")`
+- 输入: phase-4-summary.md + feedback-log.md → 输出: PR URL (含版本变更 commit)
 - **HARD-GATE**: Phase 4/6 未完成 → BLOCK。验证 `feedback-log.md` 存在。
 - **GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
-- **VERSION-GATE**: bump PATCH/MINOR/MAJOR → `sync-version.sh` → CHANGELOG.md → `git diff VERSION` 验证
 - **LAND**: `land-and-deploy` — merge PR → 等待 CI (10min) → 等待 Deploy (10min) → Canary Health Check (5min)
 - **回滚**: `git revert` 最后一次 merge commit
 
+**⚠️ VERSION-GATE 必须在 finishing-a-development-branch 之前执行。顺序反了会导致 PR 不含版本变更 → CI release workflow 不触发 → 无新版本发布。**
+
 ### Phase 6/6: CLOSE (收尾 — ⚠️ 人工验收 + 清理)
 
 **对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP

package/plugins/claude-code/skills/sprint-flow/references/phase-2-design.md

@@ -102,7 +102,33 @@ skill(name="brainstorming", user_message="[需求描述]")
 skill(name="design-shotgun", user_message="[Pain Document 内容 + 需求描述]")
 ```
 
-#### Step 1: 调用 autoplan skill
+#### Step 0.5: DESIGN 路由分叉（v0.14.0+ — Issue #306）
+
+根据 Phase 1/6 PREP (AUTO-ESTIMATE) 的 `change_type` 决定走哪条路径：
+
+```
+读取 .sprint-state/sprint-state.json → auto_estimate.change_type
+
+IF change_type == "修改已存在代码":
+  → 增量优化路径: SKIP autoplan
+  → 直接进入 Step 2b: delphi-review (lightweight: 2 专家, 1 轮)
+ELSE (change_type == "新增功能" 或 未定义):
+  → 标准路径: 继续 Step 1 (autoplan) → Step 2
+```
+
+**路由决策表**:
+
+| change_type | 路径 | autoplan | delphi-review |
+|------------|------|----------|---------------|
+| `修改已存在代码` | 增量优化 | ❌ SKIP | lightweight (2 专家, 1 轮) |
+| `新增功能` | 标准 | ✅ 执行 | 标准 (3 专家) |
+| `undefined` / 缺失 | 标准 (fail-safe) | ✅ 执行 | 标准 (3 专家) |
+
+**HARD-GATE 不变**: 两条路径最终都必须产出 APPROVED 的 delphi-reviewed.json。
+
+#### Step 1: 调用 autoplan skill（仅标准路径）
+
+**仅当 change_type != "修改已存在代码" 时执行。**
 
 ```
 skill(name="autoplan", user_message="[Pain Document 内容]")
@@ -140,10 +166,15 @@ autoplan_result:
 #### Step 2b: 调用 delphi-review（强制，orchestrator 直接执行）
 
 ```
+# 标准路径（3 专家）
 skill(name="delphi-review", user_message="[设计文档 + taste_decisions 确认结果]")
+
+# 增量优化路径（2 专家, 1 轮 — 来自 Step 0.5 路由）
+skill(name="delphi-review", user_message="[设计文档]", experts=2, max_rounds=1)
 ```
 
-- Round 1: 3 专家匿名独立评审
+- **标准路径**: Round 1: 3 专家匿名独立评审
+- **增量优化路径**: 2 专家, 1 轮 (来自 Step 0.5 DESIGN 路由分叉)
 - Round 2+: 交换意见直到共识
 - 输出: APPROVED / REQUEST_CHANGES
 

package/plugins/claude-code/skills/sprint-flow/references/phase-3-build.md

@@ -81,6 +81,69 @@ SKIP_UNCOMMITTED_GATE=1
 
 ---
 
+## TDD-GATE: Pre-Implementation TDD Check (MANDATORY — v0.14.0+)
+
+**Purpose**: Enforce RED → GREEN → REFACTOR discipline at BUILD entry before any delegation.
+
+**Execution**: Before dispatching to ralph-loop or parallel agents, the orchestrator MUST verify for each REQ:
+
+### Gate Logic
+
+```
+FOR each REQ in slices-manifest.json:
+  IF test file exists for this REQ:
+    IF test passes (GREEN state) AND no implementation exists:
+      → BLOCK: TDD bypass detected. Test is passing before implementation.
+    ELSE IF test fails (RED state):
+      → ALLOW: Proceed to implementation (GREEN phase).
+  ELSE (no test file exists):
+    → ALLOW: Mark REQ as [TDD-RED]. ralph-loop creates the test as step 0.
+```
+
+### Todo Prefix Convention
+
+Each todo item MUST carry a TDD phase prefix in the content field:
+- `[TDD-RED]`: Write failing test first. No implementation yet.
+- `[TDD-GREEN]`: Write minimal implementation to make test pass.
+- `[TDD-REFACTOR]`: Refactor while keeping tests green.
+
+The priority field (high/medium/low) is separate and unchanged.
+
+Example:
+```
+"[TDD-RED] src/lib/auth.ts: Add validateToken() test for expired tokens - expect test to fail"
+"[TDD-GREEN] src/lib/auth.ts: Implement validateToken() to pass test - expect test passes"
+"[TDD-REFACTOR] src/lib/auth.ts: Extract token parsing into parseToken() helper - expect tests stay green"
+```
+
+### Deadlock Prevention
+
+The TDD-GATE is a PRE-RALPH-LOOP check, NOT a replacement for ralph-loop's internal TDD:
+- If no test exists → ralph-loop IS allowed to proceed (creates test as step 0)
+- If test exists and is GREEN without implementation → BLOCK (TDD bypass)
+- The gate verifies TDD DISCIPLINE was followed, not that TDD was skipped
+
+### Limitation
+
+This enforcement is instructional (LLM follows SKILL.md instructions), not programmatic. For stronger enforcement, consider a future automated pre-commit hook that checks git staging order (test file must be staged before source file).
+
+### Log Format (`.sprint-state/tdd-gate-log.json`)
+
+```json
+{
+  "checked": true,
+  "blocked": false,
+  "skipped": false,
+  "reqs_checked": 4,
+  "reqs_blocked": 0,
+  "timestamp": "2026-07-09T00:00:00Z"
+}
+```
+
+**Log location**: `.sprint-state/tdd-gate-log.json` — written on every gate execution for audit trail.
+
+---
+
 ## TDD 强制执行
 
 ### Gate 5a-BLOCK: 新增文件测试强制

package/plugins/claude-code/skills/sprint-flow/references/phase-5-ship.md

@@ -13,15 +13,70 @@
 
 **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill（4 选项菜单 + PR 确认），**必须由 orchestrator 直接调用**。
 
-**关键链**: PHASE4-GATE → verification → finishing-a-development-branch(4选项) → ship
+**关键链**: VERSION-GATE(MANDATORY) → finishing-a-development-branch(4选项) → push PR
 
 **HARD-GATE**: Phase 4/6 VERIFY 未完成 → BLOCK。验证 `feedback-log.md` 存在。
 
 **GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
 
-**VERSION-GATE**: bump PATCH/MINOR/MAJOR → `sync-version.sh` → CHANGELOG.md → `git diff VERSION` 验证
+**NETWORK-RESILIENCE**: GitHub API 在大中华区存在间歇性 TLS/超时问题。所有 `gh` CLI 调用应容忍偶尔失败：
+- `gh` 命令失败时等待 2-5 秒后重试（最多 3 次）
+- 优先使用 REST API (`gh api /repos/...`) 而非 GraphQL (`gh pr view --json ...`)，REST 更轻量更可靠
+- 验证 CI 状态时使用 `gh run list --branch ... --limit 1 --json status,conclusion` 代替 `gh pr view --json statusCheckRollup`
+- 如果 `gh` 持续超时，fallback 到 `curl + token`:
+  ```
+  curl -s -H "Authorization: token $(gh auth token)" \
+    "https://api.github.com/repos/OWNER/REPO/commits/HEAD/status"
+  ```
 
-**输出**: PR URL
+### Step 0: VERSION-GATE（MANDATORY — 在 finishing-a-development-branch 之前执行）
+
+**Purpose**: Ensure version bump, changelog update, and sync before creating PR. This MUST run BEFORE calling `finishing-a-development-branch` — the skill's "Create PR" option creates the PR immediately, so version changes must be committed first.
+
+**Execution**:
+
+```
+1. 根据变更类型决定 bump 级别:
+   - PATCH (0.14.0 → 0.14.1): bug fixes, docs, minor enhancements
+   - MINOR (0.14.0 → 0.15.0): new features, significant enhancements
+   - MAJOR (0.14.0 → 1.0.0): breaking changes
+
+2. 更新 VERSION 文件 (MAJOR.MINOR.PATCH.MICRO 格式)
+
+3. 更新 CHANGELOG.md:
+   - 添加新版本条目 (## [X.Y.Z.W] - YYYY-MM-DD)
+   - 按 ### Added / ### Fixed / ### Changed 分类
+
+4. 运行 sync-version.sh:
+   bash scripts/sync-version.sh
+
+5. 验证:
+   git diff VERSION              # 确认版本号变更
+   git diff CHANGELOG.md         # 确认 changelog 变更
+   git diff --stat               # 确认 package.json 版本同步
+
+6. 提交版本变更:
+   git add VERSION CHANGELOG.md && git commit -m "release: bump version to X.Y.Z.W"
+
+7. 推送到远程分支:
+   git push
+
+8. 验证 CI 流程触发:
+   gh pr view <PR_NUMBER> --json state  # 确认 CI 已开始
+```
+
+**GATE CHECK** (BEFORE proceeding to finishing-a-development-branch):
+```
+[VERSION-GATE] VERSION bump ✓   # VERSION 文件已更新
+[VERSION-GATE] CHANGELOG ✓      # 新版本条目已添加
+[VERSION-GATE] sync-version ✓   # 所有 package.json 已同步
+[VERSION-GATE] committed ✓      # 版本变更已提交并推送
+[VERSION-GATE] PR updated ✓     # PR 已包含版本变更 commit
+```
+
+**⚠️ ANTI-PATTERN**: 先调用 finishing-a-development-branch 创建 PR，再 bump VERSION 会导致 PR 不含版本变更 → CI 不触发 release workflow → 无新版本发布。
+
+**输出**: 版本变更 commit 包含在 PR 中
 
 ---
 

package/plugins/claude-code/skills/sprint-flow/references/phase-6-close.md

@@ -3,6 +3,8 @@
 **执行时机**: Phase 5/6 SHIP 完成后。
 **对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP
 
+**NETWORK-RESILIENCE**: 与 Phase 5/6 相同，GitHub API 在大中华区存在间歇性超时。CLEANUP 中的 `gh pr list` 和 `git push --delete` 需容忍重试。详见 `phase-5-ship.md` NETWORK-RESILIENCE 指南。
+
 ---
 
 ## Part A: USER ACCEPTANCE（⚠️ 人工验收）
@@ -100,7 +102,64 @@ Phase 6/6 CLOSE 完成时:
 ### 输出
 
 - Emergent Issues List (`emergent-issues.md`)
-- 进入 Part B CLEANUP 自动执行（如果用户确认验收）
+- 进入 Part A.5 ARCHIVE 自动执行（如果用户确认验收）
+
+---
+
+## Part A.5: ARCHIVE（归档 — v0.14.0+ Issue #308）
+
+**Purpose**: Preserve sprint decision records before cleanup. `.sprint-state/` is gitignored and deleted during CLEANUP; this step copies structured outputs to `.sprint-history/` which is tracked by git.
+
+**Execution**: After USER ACCEPTANCE (Part A) confirms continuation, BEFORE CLEANUP (Part B).
+
+### Step 1: Read Sprint ID
+
+Read `sprint-state.json` → `id` field (e.g., `sprint-2026-07-09-01`).
+
+### Step 2: Check for Conflicts
+
+```
+IF .sprint-history/<sprint-id>/ already exists:
+  → Append timestamp suffix: <sprint-id>-20260709T120000
+  → Log warning: "Sprint archive conflict, using timestamp suffix"
+```
+
+### Step 3: Archive Files
+
+Copy from `.sprint-state/` to `.sprint-history/<sprint-id>/`:
+
+**Included** (all `.yaml`, `.json`, `.md` files under `.sprint-state/`):
+- `specification.yaml` (if in phase-outputs/)
+- `delphi-reviewed.json`
+- `sprint-state.json`
+- `phase-outputs/*.yaml`, `phase-outputs/*.json`, `phase-outputs/*.md`
+- `tdd-gate-log.json`, `uncommitted-gate-log.json`
+
+**Excluded** (temporary/cache):
+- `*.tmp`, `*.cache` files
+- `sprint.lock` (session lock file)
+
+### Step 4: Verify Git Tracking
+
+```bash
+# .sprint-history/ is NOT in .gitignore (verified — no change needed)
+# Verify files are trackable:
+git status .sprint-history/
+```
+
+**No `.gitignore` change needed**: `.sprint-history/` is NOT currently listed in `.gitignore`. The `.sprint-state/` ignore (line 59) only matches `.sprint-state/` exactly — it does NOT match `.sprint-history/`.
+
+### Step 5: Commit Archive (Optional)
+
+The orchestrator MAY commit the archive:
+```
+git add .sprint-history/<sprint-id>/ && git commit -m "archive: sprint <sprint-id>"
+```
+
+### Output
+
+- `.sprint-history/<sprint-id>/` directory with archived sprint state
+- Git-tracked sprint decision records for future retro/review
 
 ---
 

package/plugins/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "main": "index.ts",
   "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",

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

@@ -274,8 +274,9 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 **详细指令**: 参见 `references/phase-2-design.md` — 完整流程、条件分支、HARD-GATE。
 
 **快速参考**:
+- **Step 0.5: DESIGN 路由分叉 (v0.14.0+)**: 根据 PREP 的 `change_type` 决定路径。`修改已存在代码` → SKIP autoplan, 直接 lightweight delphi-review (2 专家, 1 轮)。`新增功能` 或 undefined → 标准 autoplan 路径。详见 `references/phase-2-design.md#step-05-design-路由分叉`。
 - **Step 1: brainstorming** — `skill(name="brainstorming")` — 输出设计文档 + CONTEXT.md + ADR。**HARD-GATE**: 设计未批准 → 不可进入实现
-- **Step 2: autoplan** — `skill(name="autoplan")` — CEO/设计/工程自动评审 → 用户确认 taste_decisions
+- **Step 2: autoplan** — `skill(name="autoplan")` — CEO/设计/工程自动评审 → 用户确认 taste_decisions（仅标准路径）
 - **Step 3: delphi-review** — `skill(name="delphi-review")` — 等待 APPROVED（非 APPROVED 暂停等待用户确认）
 - **Step 4: to-issues** — `skill(name="to-issues")` — 垂直切片 Issue 拆分 → slices-manifest.json
 - **Step 5: specification.yaml** — 从 APPROVED 设计文档自动提取
@@ -304,10 +305,11 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 
 **快速参考**:
 1. **DELPHI-GATE**: 验证 `.sprint-state/delphi-reviewed.json` 存在且 `verdict = "APPROVED"` → 否则 BLOCK
-2. **输入**: `slices-manifest.json`（Phase 2/6 生成），按 `execution_order` 逐个执行
-3. **模式**: 默认 `ralph-loop`（逐 REQ 迭代，token 节约 40-67%），可选 `--mode parallel`
-4. **Skill 步骤**: hooks-install → dispatching-parallel-agents → TDD (RED/GREEN/REFACTOR) → freeze → blind-review → unfreeze → verification-before-completion → 成本监控
-5. **Mock Minimization**: integration-first, mock 仅限 external services, 密度 > 30% 需 `@mock-justified`
+2. **TDD-GATE (MANDATORY — v0.14.0+)**: 在 delegation 前验证每个 REQ 存在 failing test。无 test → mark `[TDD-RED]`（ralph-loop 创建）。有 test 且 GREEN 且无实现 → BLOCK（TDD bypass）。详见 `references/phase-3-build.md#tdd-gate-pre-implementation-tdd-check-mandatory`。
+3. **输入**: `slices-manifest.json`（Phase 2/6 生成），按 `execution_order` 逐个执行
+4. **模式**: 默认 `ralph-loop`（逐 REQ 迭代，token 节约 40-67%），可选 `--mode parallel`
+5. **Skill 步骤**: hooks-install → TDD-GATE → dispatching-parallel-agents → TDD (RED/GREEN/REFACTOR) → freeze → blind-review → unfreeze → verification-before-completion → 成本监控
+6. **Mock Minimization**: integration-first, mock 仅限 external services, 密度 > 30% 需 `@mock-justified`
 
 ### Phase 4/6: VERIFY (验证 — 代码走查 + QA + 反馈获取)
 
@@ -336,17 +338,20 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 
 **对应旧模型**: Phase 5 SHIP + Phase 6 LAND
 
-**详细指令**: 参见 `references/phase-5-ship.md` — GITHOOKS-GATE / VERSION-GATE / VERSION CHANGESET (Issue #142) / changeset schema。
+**详细指令**: 参见 `references/phase-5-ship.md` — VERSION-GATE (MANDATORY) / finishing-a-development-branch / VERSION CHANGESET (Issue #142) / changeset schema。
 
 **快速参考**:
-- **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill（4 选项菜单 + PR 确认），**必须由 orchestrator 直接调用** `skill(name="finishing-a-development-branch")` 和 `skill(name="ship")`
-- 输入: phase-4-summary.md + feedback-log.md → 输出: PR URL
+- **Step 0: VERSION-GATE (MANDATORY — 必须在 finishing-a-development-branch 之前)**: bump VERSION → update CHANGELOG.md → run sync-version.sh → commit + push → verify PR updated。详见 `references/phase-5-ship.md#step-0-version-gate`
+- **Step 1: finishing-a-development-branch**: 4 选项菜单，选择 "Push and create a Pull Request"
+- **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill，**必须由 orchestrator 直接调用** `skill(name="finishing-a-development-branch")` 和 `skill(name="ship")`
+- 输入: phase-4-summary.md + feedback-log.md → 输出: PR URL (含版本变更 commit)
 - **HARD-GATE**: Phase 4/6 未完成 → BLOCK。验证 `feedback-log.md` 存在。
 - **GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
-- **VERSION-GATE**: bump PATCH/MINOR/MAJOR → `sync-version.sh` → CHANGELOG.md → `git diff VERSION` 验证
 - **LAND**: `land-and-deploy` — merge PR → 等待 CI (10min) → 等待 Deploy (10min) → Canary Health Check (5min)
 - **回滚**: `git revert` 最后一次 merge commit
 
+**⚠️ VERSION-GATE 必须在 finishing-a-development-branch 之前执行。顺序反了会导致 PR 不含版本变更 → CI release workflow 不触发 → 无新版本发布。**
+
 ### Phase 6/6: CLOSE (收尾 — ⚠️ 人工验收 + 清理)
 
 **对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP

package/plugins/opencode/skills/sprint-flow/references/phase-2-design.md

@@ -102,7 +102,33 @@ skill(name="brainstorming", user_message="[需求描述]")
 skill(name="design-shotgun", user_message="[Pain Document 内容 + 需求描述]")
 ```
 
-#### Step 1: 调用 autoplan skill
+#### Step 0.5: DESIGN 路由分叉（v0.14.0+ — Issue #306）
+
+根据 Phase 1/6 PREP (AUTO-ESTIMATE) 的 `change_type` 决定走哪条路径：
+
+```
+读取 .sprint-state/sprint-state.json → auto_estimate.change_type
+
+IF change_type == "修改已存在代码":
+  → 增量优化路径: SKIP autoplan
+  → 直接进入 Step 2b: delphi-review (lightweight: 2 专家, 1 轮)
+ELSE (change_type == "新增功能" 或 未定义):
+  → 标准路径: 继续 Step 1 (autoplan) → Step 2
+```
+
+**路由决策表**:
+
+| change_type | 路径 | autoplan | delphi-review |
+|------------|------|----------|---------------|
+| `修改已存在代码` | 增量优化 | ❌ SKIP | lightweight (2 专家, 1 轮) |
+| `新增功能` | 标准 | ✅ 执行 | 标准 (3 专家) |
+| `undefined` / 缺失 | 标准 (fail-safe) | ✅ 执行 | 标准 (3 专家) |
+
+**HARD-GATE 不变**: 两条路径最终都必须产出 APPROVED 的 delphi-reviewed.json。
+
+#### Step 1: 调用 autoplan skill（仅标准路径）
+
+**仅当 change_type != "修改已存在代码" 时执行。**
 
 ```
 skill(name="autoplan", user_message="[Pain Document 内容]")
@@ -140,10 +166,15 @@ autoplan_result:
 #### Step 2b: 调用 delphi-review（强制，orchestrator 直接执行）
 
 ```
+# 标准路径（3 专家）
 skill(name="delphi-review", user_message="[设计文档 + taste_decisions 确认结果]")
+
+# 增量优化路径（2 专家, 1 轮 — 来自 Step 0.5 路由）
+skill(name="delphi-review", user_message="[设计文档]", experts=2, max_rounds=1)
 ```
 
-- Round 1: 3 专家匿名独立评审
+- **标准路径**: Round 1: 3 专家匿名独立评审
+- **增量优化路径**: 2 专家, 1 轮 (来自 Step 0.5 DESIGN 路由分叉)
 - Round 2+: 交换意见直到共识
 - 输出: APPROVED / REQUEST_CHANGES
 

package/plugins/opencode/skills/sprint-flow/references/phase-3-build.md

@@ -81,6 +81,69 @@ SKIP_UNCOMMITTED_GATE=1
 
 ---
 
+## TDD-GATE: Pre-Implementation TDD Check (MANDATORY — v0.14.0+)
+
+**Purpose**: Enforce RED → GREEN → REFACTOR discipline at BUILD entry before any delegation.
+
+**Execution**: Before dispatching to ralph-loop or parallel agents, the orchestrator MUST verify for each REQ:
+
+### Gate Logic
+
+```
+FOR each REQ in slices-manifest.json:
+  IF test file exists for this REQ:
+    IF test passes (GREEN state) AND no implementation exists:
+      → BLOCK: TDD bypass detected. Test is passing before implementation.
+    ELSE IF test fails (RED state):
+      → ALLOW: Proceed to implementation (GREEN phase).
+  ELSE (no test file exists):
+    → ALLOW: Mark REQ as [TDD-RED]. ralph-loop creates the test as step 0.
+```
+
+### Todo Prefix Convention
+
+Each todo item MUST carry a TDD phase prefix in the content field:
+- `[TDD-RED]`: Write failing test first. No implementation yet.
+- `[TDD-GREEN]`: Write minimal implementation to make test pass.
+- `[TDD-REFACTOR]`: Refactor while keeping tests green.
+
+The priority field (high/medium/low) is separate and unchanged.
+
+Example:
+```
+"[TDD-RED] src/lib/auth.ts: Add validateToken() test for expired tokens - expect test to fail"
+"[TDD-GREEN] src/lib/auth.ts: Implement validateToken() to pass test - expect test passes"
+"[TDD-REFACTOR] src/lib/auth.ts: Extract token parsing into parseToken() helper - expect tests stay green"
+```
+
+### Deadlock Prevention
+
+The TDD-GATE is a PRE-RALPH-LOOP check, NOT a replacement for ralph-loop's internal TDD:
+- If no test exists → ralph-loop IS allowed to proceed (creates test as step 0)
+- If test exists and is GREEN without implementation → BLOCK (TDD bypass)
+- The gate verifies TDD DISCIPLINE was followed, not that TDD was skipped
+
+### Limitation
+
+This enforcement is instructional (LLM follows SKILL.md instructions), not programmatic. For stronger enforcement, consider a future automated pre-commit hook that checks git staging order (test file must be staged before source file).
+
+### Log Format (`.sprint-state/tdd-gate-log.json`)
+
+```json
+{
+  "checked": true,
+  "blocked": false,
+  "skipped": false,
+  "reqs_checked": 4,
+  "reqs_blocked": 0,
+  "timestamp": "2026-07-09T00:00:00Z"
+}
+```
+
+**Log location**: `.sprint-state/tdd-gate-log.json` — written on every gate execution for audit trail.
+
+---
+
 ## TDD 强制执行
 
 ### Gate 5a-BLOCK: 新增文件测试强制

package/plugins/opencode/skills/sprint-flow/references/phase-5-ship.md

@@ -13,15 +13,70 @@
 
 **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill（4 选项菜单 + PR 确认），**必须由 orchestrator 直接调用**。
 
-**关键链**: PHASE4-GATE → verification → finishing-a-development-branch(4选项) → ship
+**关键链**: VERSION-GATE(MANDATORY) → finishing-a-development-branch(4选项) → push PR
 
 **HARD-GATE**: Phase 4/6 VERIFY 未完成 → BLOCK。验证 `feedback-log.md` 存在。
 
 **GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
 
-**VERSION-GATE**: bump PATCH/MINOR/MAJOR → `sync-version.sh` → CHANGELOG.md → `git diff VERSION` 验证
+**NETWORK-RESILIENCE**: GitHub API 在大中华区存在间歇性 TLS/超时问题。所有 `gh` CLI 调用应容忍偶尔失败：
+- `gh` 命令失败时等待 2-5 秒后重试（最多 3 次）
+- 优先使用 REST API (`gh api /repos/...`) 而非 GraphQL (`gh pr view --json ...`)，REST 更轻量更可靠
+- 验证 CI 状态时使用 `gh run list --branch ... --limit 1 --json status,conclusion` 代替 `gh pr view --json statusCheckRollup`
+- 如果 `gh` 持续超时，fallback 到 `curl + token`:
+  ```
+  curl -s -H "Authorization: token $(gh auth token)" \
+    "https://api.github.com/repos/OWNER/REPO/commits/HEAD/status"
+  ```
 
-**输出**: PR URL
+### Step 0: VERSION-GATE（MANDATORY — 在 finishing-a-development-branch 之前执行）
+
+**Purpose**: Ensure version bump, changelog update, and sync before creating PR. This MUST run BEFORE calling `finishing-a-development-branch` — the skill's "Create PR" option creates the PR immediately, so version changes must be committed first.
+
+**Execution**:
+
+```
+1. 根据变更类型决定 bump 级别:
+   - PATCH (0.14.0 → 0.14.1): bug fixes, docs, minor enhancements
+   - MINOR (0.14.0 → 0.15.0): new features, significant enhancements
+   - MAJOR (0.14.0 → 1.0.0): breaking changes
+
+2. 更新 VERSION 文件 (MAJOR.MINOR.PATCH.MICRO 格式)
+
+3. 更新 CHANGELOG.md:
+   - 添加新版本条目 (## [X.Y.Z.W] - YYYY-MM-DD)
+   - 按 ### Added / ### Fixed / ### Changed 分类
+
+4. 运行 sync-version.sh:
+   bash scripts/sync-version.sh
+
+5. 验证:
+   git diff VERSION              # 确认版本号变更
+   git diff CHANGELOG.md         # 确认 changelog 变更
+   git diff --stat               # 确认 package.json 版本同步
+
+6. 提交版本变更:
+   git add VERSION CHANGELOG.md && git commit -m "release: bump version to X.Y.Z.W"
+
+7. 推送到远程分支:
+   git push
+
+8. 验证 CI 流程触发:
+   gh pr view <PR_NUMBER> --json state  # 确认 CI 已开始
+```
+
+**GATE CHECK** (BEFORE proceeding to finishing-a-development-branch):
+```
+[VERSION-GATE] VERSION bump ✓   # VERSION 文件已更新
+[VERSION-GATE] CHANGELOG ✓      # 新版本条目已添加
+[VERSION-GATE] sync-version ✓   # 所有 package.json 已同步
+[VERSION-GATE] committed ✓      # 版本变更已提交并推送
+[VERSION-GATE] PR updated ✓     # PR 已包含版本变更 commit
+```
+
+**⚠️ ANTI-PATTERN**: 先调用 finishing-a-development-branch 创建 PR，再 bump VERSION 会导致 PR 不含版本变更 → CI 不触发 release workflow → 无新版本发布。
+
+**输出**: 版本变更 commit 包含在 PR 中
 
 ---
 

package/plugins/opencode/skills/sprint-flow/references/phase-6-close.md

@@ -3,6 +3,8 @@
 **执行时机**: Phase 5/6 SHIP 完成后。
 **对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP
 
+**NETWORK-RESILIENCE**: 与 Phase 5/6 相同，GitHub API 在大中华区存在间歇性超时。CLEANUP 中的 `gh pr list` 和 `git push --delete` 需容忍重试。详见 `phase-5-ship.md` NETWORK-RESILIENCE 指南。
+
 ---
 
 ## Part A: USER ACCEPTANCE（⚠️ 人工验收）
@@ -100,7 +102,64 @@ Phase 6/6 CLOSE 完成时:
 ### 输出
 
 - Emergent Issues List (`emergent-issues.md`)
-- 进入 Part B CLEANUP 自动执行（如果用户确认验收）
+- 进入 Part A.5 ARCHIVE 自动执行（如果用户确认验收）
+
+---
+
+## Part A.5: ARCHIVE（归档 — v0.14.0+ Issue #308）
+
+**Purpose**: Preserve sprint decision records before cleanup. `.sprint-state/` is gitignored and deleted during CLEANUP; this step copies structured outputs to `.sprint-history/` which is tracked by git.
+
+**Execution**: After USER ACCEPTANCE (Part A) confirms continuation, BEFORE CLEANUP (Part B).
+
+### Step 1: Read Sprint ID
+
+Read `sprint-state.json` → `id` field (e.g., `sprint-2026-07-09-01`).
+
+### Step 2: Check for Conflicts
+
+```
+IF .sprint-history/<sprint-id>/ already exists:
+  → Append timestamp suffix: <sprint-id>-20260709T120000
+  → Log warning: "Sprint archive conflict, using timestamp suffix"
+```
+
+### Step 3: Archive Files
+
+Copy from `.sprint-state/` to `.sprint-history/<sprint-id>/`:
+
+**Included** (all `.yaml`, `.json`, `.md` files under `.sprint-state/`):
+- `specification.yaml` (if in phase-outputs/)
+- `delphi-reviewed.json`
+- `sprint-state.json`
+- `phase-outputs/*.yaml`, `phase-outputs/*.json`, `phase-outputs/*.md`
+- `tdd-gate-log.json`, `uncommitted-gate-log.json`
+
+**Excluded** (temporary/cache):
+- `*.tmp`, `*.cache` files
+- `sprint.lock` (session lock file)
+
+### Step 4: Verify Git Tracking
+
+```bash
+# .sprint-history/ is NOT in .gitignore (verified — no change needed)
+# Verify files are trackable:
+git status .sprint-history/
+```
+
+**No `.gitignore` change needed**: `.sprint-history/` is NOT currently listed in `.gitignore`. The `.sprint-state/` ignore (line 59) only matches `.sprint-state/` exactly — it does NOT match `.sprint-history/`.
+
+### Step 5: Commit Archive (Optional)
+
+The orchestrator MAY commit the archive:
+```
+git add .sprint-history/<sprint-id>/ && git commit -m "archive: sprint <sprint-id>"
+```
+
+### Output
+
+- `.sprint-history/<sprint-id>/` directory with archived sprint state
+- Git-tracked sprint decision records for future retro/review
 
 ---
 

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. Includes 10 quality gates (Gate 0-9), Sprint Flow (11 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-07-08
-**Commit:** 229cf7d
-**Branch:** main
-**Version:** 0.14.0.0
+**Generated:** 2026-07-09
+**Commit:** e53b728
+**Branch:** sprint/2026-07-09-01
+**Version:** 0.14.1.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

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

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-07-08
-**Commit:** 229cf7d
-**Branch:** main
-**Version:** 0.14.0.0
+**Generated:** 2026-07-09
+**Commit:** e53b728
+**Branch:** sprint/2026-07-09-01
+**Version:** 0.14.1.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

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

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-07-08
-**Commit:** 229cf7d
-**Branch:** main
-**Version:** 0.14.0.0
+**Generated:** 2026-07-09
+**Commit:** e53b728
+**Branch:** sprint/2026-07-09-01
+**Version:** 0.14.1.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/skills/sprint-flow/SKILL.md

@@ -274,8 +274,9 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 **详细指令**: 参见 `references/phase-2-design.md` — 完整流程、条件分支、HARD-GATE。
 
 **快速参考**:
+- **Step 0.5: DESIGN 路由分叉 (v0.14.0+)**: 根据 PREP 的 `change_type` 决定路径。`修改已存在代码` → SKIP autoplan, 直接 lightweight delphi-review (2 专家, 1 轮)。`新增功能` 或 undefined → 标准 autoplan 路径。详见 `references/phase-2-design.md#step-05-design-路由分叉`。
 - **Step 1: brainstorming** — `skill(name="brainstorming")` — 输出设计文档 + CONTEXT.md + ADR。**HARD-GATE**: 设计未批准 → 不可进入实现
-- **Step 2: autoplan** — `skill(name="autoplan")` — CEO/设计/工程自动评审 → 用户确认 taste_decisions
+- **Step 2: autoplan** — `skill(name="autoplan")` — CEO/设计/工程自动评审 → 用户确认 taste_decisions（仅标准路径）
 - **Step 3: delphi-review** — `skill(name="delphi-review")` — 等待 APPROVED（非 APPROVED 暂停等待用户确认）
 - **Step 4: to-issues** — `skill(name="to-issues")` — 垂直切片 Issue 拆分 → slices-manifest.json
 - **Step 5: specification.yaml** — 从 APPROVED 设计文档自动提取
@@ -304,10 +305,11 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 
 **快速参考**:
 1. **DELPHI-GATE**: 验证 `.sprint-state/delphi-reviewed.json` 存在且 `verdict = "APPROVED"` → 否则 BLOCK
-2. **输入**: `slices-manifest.json`（Phase 2/6 生成），按 `execution_order` 逐个执行
-3. **模式**: 默认 `ralph-loop`（逐 REQ 迭代，token 节约 40-67%），可选 `--mode parallel`
-4. **Skill 步骤**: hooks-install → dispatching-parallel-agents → TDD (RED/GREEN/REFACTOR) → freeze → blind-review → unfreeze → verification-before-completion → 成本监控
-5. **Mock Minimization**: integration-first, mock 仅限 external services, 密度 > 30% 需 `@mock-justified`
+2. **TDD-GATE (MANDATORY — v0.14.0+)**: 在 delegation 前验证每个 REQ 存在 failing test。无 test → mark `[TDD-RED]`（ralph-loop 创建）。有 test 且 GREEN 且无实现 → BLOCK（TDD bypass）。详见 `references/phase-3-build.md#tdd-gate-pre-implementation-tdd-check-mandatory`。
+3. **输入**: `slices-manifest.json`（Phase 2/6 生成），按 `execution_order` 逐个执行
+4. **模式**: 默认 `ralph-loop`（逐 REQ 迭代，token 节约 40-67%），可选 `--mode parallel`
+5. **Skill 步骤**: hooks-install → TDD-GATE → dispatching-parallel-agents → TDD (RED/GREEN/REFACTOR) → freeze → blind-review → unfreeze → verification-before-completion → 成本监控
+6. **Mock Minimization**: integration-first, mock 仅限 external services, 密度 > 30% 需 `@mock-justified`
 
 ### Phase 4/6: VERIFY (验证 — 代码走查 + QA + 反馈获取)
 
@@ -336,17 +338,20 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 
 **对应旧模型**: Phase 5 SHIP + Phase 6 LAND
 
-**详细指令**: 参见 `references/phase-5-ship.md` — GITHOOKS-GATE / VERSION-GATE / VERSION CHANGESET (Issue #142) / changeset schema。
+**详细指令**: 参见 `references/phase-5-ship.md` — VERSION-GATE (MANDATORY) / finishing-a-development-branch / VERSION CHANGESET (Issue #142) / changeset schema。
 
 **快速参考**:
-- **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill（4 选项菜单 + PR 确认），**必须由 orchestrator 直接调用** `skill(name="finishing-a-development-branch")` 和 `skill(name="ship")`
-- 输入: phase-4-summary.md + feedback-log.md → 输出: PR URL
+- **Step 0: VERSION-GATE (MANDATORY — 必须在 finishing-a-development-branch 之前)**: bump VERSION → update CHANGELOG.md → run sync-version.sh → commit + push → verify PR updated。详见 `references/phase-5-ship.md#step-0-version-gate`
+- **Step 1: finishing-a-development-branch**: 4 选项菜单，选择 "Push and create a Pull Request"
+- **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill，**必须由 orchestrator 直接调用** `skill(name="finishing-a-development-branch")` 和 `skill(name="ship")`
+- 输入: phase-4-summary.md + feedback-log.md → 输出: PR URL (含版本变更 commit)
 - **HARD-GATE**: Phase 4/6 未完成 → BLOCK。验证 `feedback-log.md` 存在。
 - **GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
-- **VERSION-GATE**: bump PATCH/MINOR/MAJOR → `sync-version.sh` → CHANGELOG.md → `git diff VERSION` 验证
 - **LAND**: `land-and-deploy` — merge PR → 等待 CI (10min) → 等待 Deploy (10min) → Canary Health Check (5min)
 - **回滚**: `git revert` 最后一次 merge commit
 
+**⚠️ VERSION-GATE 必须在 finishing-a-development-branch 之前执行。顺序反了会导致 PR 不含版本变更 → CI release workflow 不触发 → 无新版本发布。**
+
 ### Phase 6/6: CLOSE (收尾 — ⚠️ 人工验收 + 清理)
 
 **对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP

package/skills/sprint-flow/references/phase-2-design.md

@@ -102,7 +102,33 @@ skill(name="brainstorming", user_message="[需求描述]")
 skill(name="design-shotgun", user_message="[Pain Document 内容 + 需求描述]")
 ```
 
-#### Step 1: 调用 autoplan skill
+#### Step 0.5: DESIGN 路由分叉（v0.14.0+ — Issue #306）
+
+根据 Phase 1/6 PREP (AUTO-ESTIMATE) 的 `change_type` 决定走哪条路径：
+
+```
+读取 .sprint-state/sprint-state.json → auto_estimate.change_type
+
+IF change_type == "修改已存在代码":
+  → 增量优化路径: SKIP autoplan
+  → 直接进入 Step 2b: delphi-review (lightweight: 2 专家, 1 轮)
+ELSE (change_type == "新增功能" 或 未定义):
+  → 标准路径: 继续 Step 1 (autoplan) → Step 2
+```
+
+**路由决策表**:
+
+| change_type | 路径 | autoplan | delphi-review |
+|------------|------|----------|---------------|
+| `修改已存在代码` | 增量优化 | ❌ SKIP | lightweight (2 专家, 1 轮) |
+| `新增功能` | 标准 | ✅ 执行 | 标准 (3 专家) |
+| `undefined` / 缺失 | 标准 (fail-safe) | ✅ 执行 | 标准 (3 专家) |
+
+**HARD-GATE 不变**: 两条路径最终都必须产出 APPROVED 的 delphi-reviewed.json。
+
+#### Step 1: 调用 autoplan skill（仅标准路径）
+
+**仅当 change_type != "修改已存在代码" 时执行。**
 
 ```
 skill(name="autoplan", user_message="[Pain Document 内容]")
@@ -140,10 +166,15 @@ autoplan_result:
 #### Step 2b: 调用 delphi-review（强制，orchestrator 直接执行）
 
 ```
+# 标准路径（3 专家）
 skill(name="delphi-review", user_message="[设计文档 + taste_decisions 确认结果]")
+
+# 增量优化路径（2 专家, 1 轮 — 来自 Step 0.5 路由）
+skill(name="delphi-review", user_message="[设计文档]", experts=2, max_rounds=1)
 ```
 
-- Round 1: 3 专家匿名独立评审
+- **标准路径**: Round 1: 3 专家匿名独立评审
+- **增量优化路径**: 2 专家, 1 轮 (来自 Step 0.5 DESIGN 路由分叉)
 - Round 2+: 交换意见直到共识
 - 输出: APPROVED / REQUEST_CHANGES
 

package/skills/sprint-flow/references/phase-3-build.md

@@ -81,6 +81,69 @@ SKIP_UNCOMMITTED_GATE=1
 
 ---
 
+## TDD-GATE: Pre-Implementation TDD Check (MANDATORY — v0.14.0+)
+
+**Purpose**: Enforce RED → GREEN → REFACTOR discipline at BUILD entry before any delegation.
+
+**Execution**: Before dispatching to ralph-loop or parallel agents, the orchestrator MUST verify for each REQ:
+
+### Gate Logic
+
+```
+FOR each REQ in slices-manifest.json:
+  IF test file exists for this REQ:
+    IF test passes (GREEN state) AND no implementation exists:
+      → BLOCK: TDD bypass detected. Test is passing before implementation.
+    ELSE IF test fails (RED state):
+      → ALLOW: Proceed to implementation (GREEN phase).
+  ELSE (no test file exists):
+    → ALLOW: Mark REQ as [TDD-RED]. ralph-loop creates the test as step 0.
+```
+
+### Todo Prefix Convention
+
+Each todo item MUST carry a TDD phase prefix in the content field:
+- `[TDD-RED]`: Write failing test first. No implementation yet.
+- `[TDD-GREEN]`: Write minimal implementation to make test pass.
+- `[TDD-REFACTOR]`: Refactor while keeping tests green.
+
+The priority field (high/medium/low) is separate and unchanged.
+
+Example:
+```
+"[TDD-RED] src/lib/auth.ts: Add validateToken() test for expired tokens - expect test to fail"
+"[TDD-GREEN] src/lib/auth.ts: Implement validateToken() to pass test - expect test passes"
+"[TDD-REFACTOR] src/lib/auth.ts: Extract token parsing into parseToken() helper - expect tests stay green"
+```
+
+### Deadlock Prevention
+
+The TDD-GATE is a PRE-RALPH-LOOP check, NOT a replacement for ralph-loop's internal TDD:
+- If no test exists → ralph-loop IS allowed to proceed (creates test as step 0)
+- If test exists and is GREEN without implementation → BLOCK (TDD bypass)
+- The gate verifies TDD DISCIPLINE was followed, not that TDD was skipped
+
+### Limitation
+
+This enforcement is instructional (LLM follows SKILL.md instructions), not programmatic. For stronger enforcement, consider a future automated pre-commit hook that checks git staging order (test file must be staged before source file).
+
+### Log Format (`.sprint-state/tdd-gate-log.json`)
+
+```json
+{
+  "checked": true,
+  "blocked": false,
+  "skipped": false,
+  "reqs_checked": 4,
+  "reqs_blocked": 0,
+  "timestamp": "2026-07-09T00:00:00Z"
+}
+```
+
+**Log location**: `.sprint-state/tdd-gate-log.json` — written on every gate execution for audit trail.
+
+---
+
 ## TDD 强制执行
 
 ### Gate 5a-BLOCK: 新增文件测试强制

package/skills/sprint-flow/references/phase-5-ship.md

@@ -13,15 +13,70 @@
 
 **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill（4 选项菜单 + PR 确认），**必须由 orchestrator 直接调用**。
 
-**关键链**: PHASE4-GATE → verification → finishing-a-development-branch(4选项) → ship
+**关键链**: VERSION-GATE(MANDATORY) → finishing-a-development-branch(4选项) → push PR
 
 **HARD-GATE**: Phase 4/6 VERIFY 未完成 → BLOCK。验证 `feedback-log.md` 存在。
 
 **GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
 
-**VERSION-GATE**: bump PATCH/MINOR/MAJOR → `sync-version.sh` → CHANGELOG.md → `git diff VERSION` 验证
+**NETWORK-RESILIENCE**: GitHub API 在大中华区存在间歇性 TLS/超时问题。所有 `gh` CLI 调用应容忍偶尔失败：
+- `gh` 命令失败时等待 2-5 秒后重试（最多 3 次）
+- 优先使用 REST API (`gh api /repos/...`) 而非 GraphQL (`gh pr view --json ...`)，REST 更轻量更可靠
+- 验证 CI 状态时使用 `gh run list --branch ... --limit 1 --json status,conclusion` 代替 `gh pr view --json statusCheckRollup`
+- 如果 `gh` 持续超时，fallback 到 `curl + token`:
+  ```
+  curl -s -H "Authorization: token $(gh auth token)" \
+    "https://api.github.com/repos/OWNER/REPO/commits/HEAD/status"
+  ```
 
-**输出**: PR URL
+### Step 0: VERSION-GATE（MANDATORY — 在 finishing-a-development-branch 之前执行）
+
+**Purpose**: Ensure version bump, changelog update, and sync before creating PR. This MUST run BEFORE calling `finishing-a-development-branch` — the skill's "Create PR" option creates the PR immediately, so version changes must be committed first.
+
+**Execution**:
+
+```
+1. 根据变更类型决定 bump 级别:
+   - PATCH (0.14.0 → 0.14.1): bug fixes, docs, minor enhancements
+   - MINOR (0.14.0 → 0.15.0): new features, significant enhancements
+   - MAJOR (0.14.0 → 1.0.0): breaking changes
+
+2. 更新 VERSION 文件 (MAJOR.MINOR.PATCH.MICRO 格式)
+
+3. 更新 CHANGELOG.md:
+   - 添加新版本条目 (## [X.Y.Z.W] - YYYY-MM-DD)
+   - 按 ### Added / ### Fixed / ### Changed 分类
+
+4. 运行 sync-version.sh:
+   bash scripts/sync-version.sh
+
+5. 验证:
+   git diff VERSION              # 确认版本号变更
+   git diff CHANGELOG.md         # 确认 changelog 变更
+   git diff --stat               # 确认 package.json 版本同步
+
+6. 提交版本变更:
+   git add VERSION CHANGELOG.md && git commit -m "release: bump version to X.Y.Z.W"
+
+7. 推送到远程分支:
+   git push
+
+8. 验证 CI 流程触发:
+   gh pr view <PR_NUMBER> --json state  # 确认 CI 已开始
+```
+
+**GATE CHECK** (BEFORE proceeding to finishing-a-development-branch):
+```
+[VERSION-GATE] VERSION bump ✓   # VERSION 文件已更新
+[VERSION-GATE] CHANGELOG ✓      # 新版本条目已添加
+[VERSION-GATE] sync-version ✓   # 所有 package.json 已同步
+[VERSION-GATE] committed ✓      # 版本变更已提交并推送
+[VERSION-GATE] PR updated ✓     # PR 已包含版本变更 commit
+```
+
+**⚠️ ANTI-PATTERN**: 先调用 finishing-a-development-branch 创建 PR，再 bump VERSION 会导致 PR 不含版本变更 → CI 不触发 release workflow → 无新版本发布。
+
+**输出**: 版本变更 commit 包含在 PR 中
 
 ---
 

package/skills/sprint-flow/references/phase-6-close.md

@@ -3,6 +3,8 @@
 **执行时机**: Phase 5/6 SHIP 完成后。
 **对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP
 
+**NETWORK-RESILIENCE**: 与 Phase 5/6 相同，GitHub API 在大中华区存在间歇性超时。CLEANUP 中的 `gh pr list` 和 `git push --delete` 需容忍重试。详见 `phase-5-ship.md` NETWORK-RESILIENCE 指南。
+
 ---
 
 ## Part A: USER ACCEPTANCE（⚠️ 人工验收）
@@ -100,7 +102,64 @@ Phase 6/6 CLOSE 完成时:
 ### 输出
 
 - Emergent Issues List (`emergent-issues.md`)
-- 进入 Part B CLEANUP 自动执行（如果用户确认验收）
+- 进入 Part A.5 ARCHIVE 自动执行（如果用户确认验收）
+
+---
+
+## Part A.5: ARCHIVE（归档 — v0.14.0+ Issue #308）
+
+**Purpose**: Preserve sprint decision records before cleanup. `.sprint-state/` is gitignored and deleted during CLEANUP; this step copies structured outputs to `.sprint-history/` which is tracked by git.
+
+**Execution**: After USER ACCEPTANCE (Part A) confirms continuation, BEFORE CLEANUP (Part B).
+
+### Step 1: Read Sprint ID
+
+Read `sprint-state.json` → `id` field (e.g., `sprint-2026-07-09-01`).
+
+### Step 2: Check for Conflicts
+
+```
+IF .sprint-history/<sprint-id>/ already exists:
+  → Append timestamp suffix: <sprint-id>-20260709T120000
+  → Log warning: "Sprint archive conflict, using timestamp suffix"
+```
+
+### Step 3: Archive Files
+
+Copy from `.sprint-state/` to `.sprint-history/<sprint-id>/`:
+
+**Included** (all `.yaml`, `.json`, `.md` files under `.sprint-state/`):
+- `specification.yaml` (if in phase-outputs/)
+- `delphi-reviewed.json`
+- `sprint-state.json`
+- `phase-outputs/*.yaml`, `phase-outputs/*.json`, `phase-outputs/*.md`
+- `tdd-gate-log.json`, `uncommitted-gate-log.json`
+
+**Excluded** (temporary/cache):
+- `*.tmp`, `*.cache` files
+- `sprint.lock` (session lock file)
+
+### Step 4: Verify Git Tracking
+
+```bash
+# .sprint-history/ is NOT in .gitignore (verified — no change needed)
+# Verify files are trackable:
+git status .sprint-history/
+```
+
+**No `.gitignore` change needed**: `.sprint-history/` is NOT currently listed in `.gitignore`. The `.sprint-state/` ignore (line 59) only matches `.sprint-state/` exactly — it does NOT match `.sprint-history/`.
+
+### Step 5: Commit Archive (Optional)
+
+The orchestrator MAY commit the archive:
+```
+git add .sprint-history/<sprint-id>/ && git commit -m "archive: sprint <sprint-id>"
+```
+
+### Output
+
+- `.sprint-history/<sprint-id>/` directory with archived sprint state
+- Git-tracked sprint decision records for future retro/review
 
 ---