@boyingliu01/xp-gate 0.8.21 → 0.9.1

package/skills/ralph-loop/references/components.md

@@ -0,0 +1,113 @@
+# Ralph Loop 组件分解
+
+## 1. System Prompt — 核心原则
+
+| # | 原则 | 说明 |
+|---|------|------|
+| 1 | 逐 REQ 迭代 | 一次处理一个 REQ/切片，干净上下文，避免上下文线性膨胀 |
+| 2 | Token 节约 | 比旧并行模式节约 40-67% token |
+| 3 | 全量回归 | 每个 REQ 完成后跑全量测试 |
+| 4 | 进度持久化 | progress.log 持久化 learnings/permanent/contextual |
+| 5 | 可中断续传 | 中断后可从最后完成 REQ 继续 |
+
+## 2. Memory — 状态与记忆结构
+
+### Progress Log Schema (`progress.log` — YAML)
+
+```yaml
+req_progress:
+  completed_count: 3
+  total_count: 5
+  current_req: REQ-XXX-004
+  status: running|completed|blocked
+  test_infra_status: generated|existing|skipped|fallback
+
+learnings:
+  permanent:
+    - pattern: "描述持久模式"
+      evidence: "来源证据"
+  contextual:
+    - pattern: "描述当前 REQ 有效模式"
+      expires_on: "过期条件"
+
+cost:
+  req_number: 3
+  tokens_used: 15000
+  cumulative_tokens: 85000
+  threshold: 200000
+```
+
+### Test Infra Status 字段
+
+| 值 | 含义 |
+|---|------|
+| `generated` | 本 REQ 首次生成 test-utils.ts |
+| `existing` | test-utils.ts 已存在且接口完整 |
+| `skipped` | 非首次 REQ，跳过 test-infra 检查 |
+| `fallback` | test-infra dispatch 失败，使用 inline 生成 |
+
+### Learnings 分类
+
+| 类型 | 生命周期 | 示例 |
+|------|---------|------|
+| `permanent` | 跨所有 REQ | "项目使用 ESLint strict 模式" |
+| `contextual` | 当前 REQ 内 | "REQ 003 使用 Zod 验证 schema" |
+
+## 3. Middleware — 迭代控制逻辑
+
+### 状态机
+
+```
+REQ N → 加载 learnings → 测试基础设施检查 → [infra missing?] → test_infra_dispatch
+     │                              │                             │
+     │                              │ infra ready                 │ FAIL (max 2 retry)
+     │                              ▼                             ▼
+     │                         TDD → 回归测试 ←───────────── BLOCK/fallback
+     │                              │
+     │ PASS → REQ N+1
+     │ FAIL → 重试 (max 3) → BLOCK → 用户决策
+     │ ALL_REQS_COMPLETE → 结束，返回控制权给 sprint-flow orchestrator
+```
+
+### 熔断机制
+
+| 触发条件 | 动作 |
+|---------|------|
+| TDD 失败 > 3 次 | BLOCK + 用户决策 |
+| Token 使用超阈值 | BLOCK + 用户决策 |
+| 回归测试失败 | 记录到 progress.log，通知 orchestrator |
+| test-infra dispatch 失败 (max 2 retry) | BLOCK 或 fallback inline 生成 |
+
+## 4. Skill Invocations — 技能调用链
+
+| 步骤 | Skill | 参数 |
+|------|-------|------|
+| 0 | 测试基础设施检查 | 检查 test-utils.ts 存在性 + 接口契约 |
+| 1 | `test-driven-development` | `--lang` 注入 + TDD 铁律 + Mock 边界 |
+| 2 | `learn` (gstack) | classification: permanent/contextual |
+| 3 | `requesting-code-review` | REQ 完成后评审 |
+
+### test-infra dispatch 节点
+
+当 test-utils.ts 不存在或接口缺失时：
+```
+task(category="unspecified-high", load_skills=["test-driven-development"],
+     prompt="生成测试基础设施：createTestApp() + withTestDb()。TDD 铁律：先写测试再实现。")
+```
+- retry max 2 次
+- 仍失败 → BLOCK 或 fallback inline 生成（记录 warning）
+- 成功后与业务代码合并为同一 commit
+
+## 5. Tool Descriptions — 构建步骤
+
+| 步骤 | 动作 | 说明 |
+|------|------|------|
+| 1 | 加载当前 REQ | 从 specification.yaml 获取下一个 READY REQ |
+| 2 | 加载 learnings | 从 progress.log 加载 permanent + contextual learnings |
+| 3 | 测试基础设施检查 | 检查 test-utils.ts。不存在 → dispatch, retry max 2 |
+| 4 | TDD (RED→GREEN→REFACTOR) | test-driven-development skill |
+| 5 | 全量回归测试 | 运行全部现有测试 |
+| 6 | 测试先行比率检查 (L1b) | 新增测试行数 / 总新增行数 ≥ 40% |
+| 7 | 记录 progress.log | learnings 分类存储 |
+| 8 | 成本检查 | token 使用量是否超阈值 |
+| 9 | 完成/继续 | 所有 REQ 完成 → 结束；否则 → 下一个 |

package/skills/ralph-loop/references/workflow-details.md

@@ -0,0 +1,99 @@
+# Ralph Loop Workflow Details
+
+## Mandatory Execution Order
+
+每个 REQ 必须按以下顺序执行，不得跳过或重排：
+
+### 1. Load next READY REQ
+- 从 specification.yaml 读取下一个依赖已满足的 REQ
+- 检查 priority 和 status (pending 状态)
+- 构建依赖图，确认无循环依赖
+
+### 2. Create isolated context
+- 清空前一个 REQ 的对话历史
+- 注入：当前 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
+PRE_REQ_HASH=$(git rev-parse HEAD)
+echo "$PRE_REQ_HASH" > .sprint-state/last-req-baseline.txt
+```
+
+### 4. Dispatch build subagent
+- 使用 `task(category="unspecified-high", load_skills=["test-driven-development"], timeout=300)`
+- 强制 TDD 流程：RED → GREEN → REFACTOR
+- 强制执行 Mock 边界策略
+
+### 5. Run full regression tests
+- **L1**: typecheck + lint on changed files
+- **L1b**: 使用 git diff 验证新增测试行数占总新增行数比例 ≥ 40%
+- **L1b-alt**: 当 diff 为空时，降级检查测试文件是否在 changeset 中
+- **L2**: 全量测试运行（不只是 @test 当前 REQ 的测试）
+- **L3**: 检查整体覆盖率 ≥ 80%
+
+### 6. Fix until green or block
+- 失败 → retry (max 3 次，每次注入失败摘要)
+- 第 3 次仍失败 → BLOCK → 等待用户决策 (skip/manual/stop/rollback)
+- 通过 → git commit + 标记 done
+
+### 7. Persist learnings
+- 分类为 permanent（架构级）或 contextual（临时性）
+- 自动升级条件：被≥2 个 REQ 引用 或 涉及接口/数据结构
+- 调用 `gstack/learn` 总结经验教训
+
+### 8. Update sprint state
+- orchestrator 统一更新 AGENTS.md（append `## ralph-loop: [REQ-XXX title]`）
+- 原子写 checkpoint (progress.log)
+- 继续下一个 READY REQ
+
+### 禁止行为
+- ❌ 跳过测试基础设施检查
+- ❌ 只运行部分测试（必须全量回归）
+- ❌ 验证失败仍 commit
+- ❌ 多个 subagent 同时写 AGENTS.md
+- ❌ 修改前一个 REQ 的代码（除非修复回归）
+
+## Output Contract (Mandatory Checklist)
+
+每个 REQ 完成时必须输出以下结构化检查清单：
+
+```markdown
+## REQ-XXX: [Title] - Execution Summary
+
+**Status**: ✅ PASS / ❌ FAIL (retry n/3) / 🚫 BLOCKED
+
+**Context Isolation**:
+- [ ] Previous REQ context cleared
+- [ ] Permanent learnings injected (N items)
+- [ ] Contextual learnings injected (≤3 items)
+- [ ] Test infrastructure confirmed ready
+
+**TDD Compliance**:
+- [ ] Tests written BEFORE implementation
+- [ ] Test/implementation ratio ≥ 40% (L1b)
+- [ ] Mock usage justified (if >30% mock density)
+- [ ] Test files present in changeset (L1b-alt)
+- [ ] TDD 合规检查 (test-first or @no-test-required)
+
+**Verification Layers**:
+- [ ] L1: typecheck + lint pass
+- [ ] L1b: Test-first ratio check pass
+- [ ] L2: FULL regression tests (all tests)
+- [ ] L3: coverage ≥ 80%
+
+**Learnings Persisted**:
+- [ ] Permanent: [N items]
+- [ ] Contextual: [N items, sliding window]
+- [ ] `gstack/learn` called
+
+**State Updated**:
+- [ ] AGENTS.md updated (orchestrator)
+- [ ] progress.log atomically written
+- [ ] Git commit created (if PASS)
+
+**Next Step**: [REQ-YYY title / COMPLETE / BLOCKED]
+```
+
+**Eval Criteria**: Structured execution plan visible, all 7 workflow steps followed, full regression tests run.

package/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-06-17
-**Commit:** c0c52f4
+**Generated:** 2026-06-18
+**Commit:** 33cf3f2
 **Branch:** main
-**Version:** 0.8.21.0
+**Version:** 0.9.1.0
 
 ## OVERVIEW
 **11-phase** development pipeline: ISOLATE → AUTO-ESTIMATE → THINK → PLAN → BUILD → REVIEW → USER ACCEPTANCE → FEEDBACK → SHIP → LAND → CLEANUP. Phase 2 default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE in Phase 1: design must pass Delphi review (≥90% consensus) before any coding.

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

@@ -7,3 +7,37 @@
 **关键链路**: DELPHI-GATE → parallel-dispatch/ralph-loop → TDD → freeze → blind-review → unfreeze → verification → cost monitor
 
 **输出**: MVP v1
+
+---
+
+## Gate 参考表（Phase 2 相关）
+
+| Gate | 名称 | 行为 |
+|------|------|------|
+| Gate 5 | 单元测试 + 覆盖率 | 全部通过 + ≥80% 覆盖率 |
+| Gate 5a-BLOCK | 新增 .ts/.tsx 文件测试强制 | 新增 .ts/.tsx 文件无对应测试文件 → BLOCK；修改文件 → WARNING |
+| Gate M2 | Mock 密度检查 | 30% WARNING (Phase 1); 可配置 via `.mockpolicyrc` |
+
+---
+
+## TDD 强制执行
+
+### Gate 5a-BLOCK: 新增文件测试强制
+
+- **新增 `.ts/.tsx` 文件**必须有对应的测试文件（`*.test.ts`、`*.spec.ts`、`__tests__/` 目录），否则 **BLOCK** 提交
+- **修改已有文件**仅触发 WARNING（不阻断）
+- **Escape valve**: 非 main/master 分支可设置 `SKIP_GATE_5A_BLOCK=1` 跳过阻断（仅 WARNING）
+
+### Gate M2: Mock 密度阈值调整
+
+- Mock 密度阈值从 50% 降低至 **30%**
+- **Phase 1**: WARNING 模式（仅告警，不阻断）
+- **Phase 2**: 将在基线分析后启用 BLOCK 模式
+- 可通过 `.mockpolicyrc` 配置阈值和行为
+
+### Escape Valve
+
+```bash
+# 非 main/master 分支临时跳过 Gate 5a-BLOCK
+SKIP_GATE_5A_BLOCK=1 git commit -m "message"
+```

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

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-06-17
-**Commit:** c0c52f4
+**Generated:** 2026-06-18
+**Commit:** 33cf3f2
 **Branch:** main
-**Version:** 0.8.21.0
+**Version:** 0.9.1.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.