@boyingliu01/xp-gate 0.13.2 → 0.14.1

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
 
 ---
 

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

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