@boyingliu01/xp-gate 0.9.0 → 0.9.2

package/plugins/opencode/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/plugins/opencode/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.