xp-gate 0.5.1

package/skills/ralph-loop/evolution-history.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Ralph Loop Evolution History",
+  "description": "Machine-readable change manifest for AHE-inspired skill evolution.",
+  "iterations": [
+    {
+      "id": 1,
+      "date": "2026-05-22",
+      "trigger": "new-feature",
+      "issue": "#62 (sync with sprint-flow)",
+      "root_cause": "ralph-loop is sprint-flow Phase 2 default build mode. Component structure must be consistent with parent skill's observability infrastructure.",
+      "component_changes": ["middleware", "tools", "memory"],
+      "files_changed": [
+        "skills/ralph-loop/references/components/system-prompt.md",
+        "skills/ralph-loop/references/components/tool-descriptions.md",
+        "skills/ralph-loop/references/components/middleware.md",
+        "skills/ralph-loop/references/components/skill-invocations.md",
+        "skills/ralph-loop/references/components/memory.md",
+        "skills/ralph-loop/evolution-log.md",
+        "skills/ralph-loop/evolution-history.json"
+      ],
+      "prediction": {
+        "metric": "skill-consistency",
+        "direction": "up",
+        "delta_pct": 100,
+        "risk": "No measurable impact; metrics depend on P1 debugger implementation"
+      },
+      "actual_outcome": null,
+      "delphi_review": "Sync modification per Delphi Round 2 minority concern resolution"
+    },
+    {
+      "id": 2,
+      "date": "2026-05-25",
+      "trigger": "bug-fix-and-feature-enhancement",
+      "issue": "#66 (test-infra-first + dispatch category fix)",
+      "root_cause": "category='build' was invalid, causing silent skill load failures. Test infrastructure was not checked before TDD dispatch, leading to subagents reinventing test helpers.",
+      "component_changes": ["middleware", "tools", "memory", "skill-invocations", "evals"],
+      "files_changed": [
+        "skills/ralph-loop/SKILL.md",
+        "skills/ralph-loop/references/components/tool-descriptions.md",
+        "skills/ralph-loop/references/components/middleware.md",
+        "skills/ralph-loop/references/components/skill-invocations.md",
+        "skills/ralph-loop/references/components/memory.md",
+        "skills/ralph-loop/evals/evals.json",
+        "skills/ralph-loop/templates/progress-log.md",
+        "skills/ralph-loop/evolution-log.md",
+        "skills/ralph-loop/evolution-history.json"
+      ],
+      "prediction": {
+        "metric": "tdd-enforcement-rate",
+        "direction": "up",
+        "delta_pct": 40,
+        "risk": "test-infra dispatch may fail if no subagent available; mitigated by fallback inline generation"
+      },
+      "actual_outcome": null,
+      "delphi_review": "code-walkthrough Round 1 REQUEST_CHANGES → fixed state machine inconsistency + reference cleanup"
+    }
+  ]
+}

package/skills/ralph-loop/evolution-log.md

@@ -0,0 +1,16 @@
+# Evolution Log — ralph-loop
+
+> AHE 启发的可观测性变更日志。
+
+## Entry 001 — 2026-05-22 — AHE Observability Infrastructure (P0 Sync)
+
+- **Trigger**: new-feature — 与 sprint-flow #62 同步创建 components/ 分解结构
+- **Evidence**: Delphi Round 2 Expert C 少数派意见明确要求 ralph-loop 同步修改
+- **Root Cause**: ralph-loop 是 sprint-flow Phase 2 默认构建模式，组件结构不一致会导致引用断裂
+- **Change Made**:
+  1. 创建 `references/components/` 目录，包含 5 个 AHE 对齐组件
+  2. 创建 `evolution-log.md`
+  3. 创建 `evolution-history.json`
+- **Self-Predicted Impact**: 保证 sprint-flow 与 ralph-loop 对 observability 组件的引用一致性
+- **Actual Outcome**: ⏳ pending
+- **Component Changed**: [middleware, tools, memory]

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

@@ -0,0 +1,55 @@
+# memory.md — Ralph Loop 状态与记忆结构（AHE 组件分解）
+
+> **本文是 `skills/ralph-loop/SKILL.md` 中状态管理的 AHE 对齐展开。**
+
+## 组件职责
+
+定义 Ralph Loop 的进度持久化 Schema、learnings 分类结构。
+
+## 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 生成（含 warning）|
+
+## Learnings 分类
+
+| 类型 | 生命周期 | 持久化 | 示例 |
+|------|---------|--------|------|
+| `permanent` | 跨所有 REQ | progress.log | "项目使用 ESLint strict 模式" |
+| `contextual` | 当前 REQ 内 | progress.log (过期标记) | "REQ 003 使用 Zod 验证 schema" |
+
+## AHE 分类
+
+| 字段 | 值 |
+|------|---|
+| 组件类型 | Long-Term Memory |
+| 修改频率预期 | 低 |

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

@@ -0,0 +1,54 @@
+# middleware.md — Ralph Loop 迭代控制逻辑（AHE 组件分解）
+
+> **本文是 `skills/ralph-loop/SKILL.md` 中迭代流程的 AHE 对齐展开。**
+
+## 组件职责
+
+定义 Ralph Loop 的状态机：REQ 级迭代控制、熔断机制、中断续传逻辑。
+
+## 状态机
+
+```
+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
+```
+
+## 测试基础设施状态机
+
+```
+test_infra_check → [needs infra?] → test_infra_dispatch → FAIL → retry (max 2)
+        │               │                        │                      │
+        │               │ infra ready            │ pass                 │ pass
+        ▼               ▼                        ▼                      ▼
+     in_progress   test_infra_ready ─────────→ TDD → regression     BLOCK/fallback
+```
+
+## 熔断机制
+
+| 触发条件 | 动作 |
+|---------|------|
+| TDD 失败 > 3 次 | BLOCK + 用户决策 |
+| Token 使用超阈值 | BLOCK + 用户决策 |
+| 回归测试失败 | 记录到 progress.log，通知 sprint-flow orchestrator |
+| test-infra dispatch 失败 (max 2 retry) | BLOCK 或 fallback inline 生成（记录 warning）|
+
+## 暂停点
+
+| 暂停点 | 触发条件 | 恢复 |
+|--------|---------|------|
+| REQ 完成 | 自动暂停等待确认 | 确认后继续下一个 REQ |
+| 熔断 | 自动触发 | 用户决策后继续或放弃 |
+
+## AHE 分类
+
+| 字段 | 值 |
+|------|---|
+| 组件类型 | Middleware |
+| 修改频率预期 | 高 |

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

@@ -0,0 +1,39 @@
+# skill-invocations.md — Ralph Loop 技能调用（AHE 组件分解）
+
+> **本文是 `skills/ralph-loop/SKILL.md` 中技能调用链的 AHE 对齐展开。**
+
+## 组件职责
+
+提供 Ralph Loop 在每个 REQ 执行中的技能调用链。
+
+## 完整调用链
+
+| 步骤 | Skill | 来源 | 参数 |
+|------|-------|------|------|
+| 0 | 测试基础设施检查 | 内置 | 检查 test-utils.ts 存在性 + 接口契约（createTestApp, withTestDb）|
+| 1 | `test-driven-development` | superpowers | `--lang` 注入 + TDD 铁律 + Mock 边界（覆盖默认策略）|
+| 2 | `learn` | gstack | classification: permanent/contextual |
+| 3 | `requesting-code-review` | superpowers | 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
+
+## 上游依赖
+
+从 `specification.yaml` 获取 REQ 列表（由 `to-issues` skill 生成）
+
+## AHE 分类
+
+| 字段 | 值 |
+|------|---|
+| 组件类型 | Skill Invocation Chain |
+| 修改频率预期 | 中 |

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

@@ -0,0 +1,24 @@
+# system-prompt.md — Ralph Loop 行为定义（AHE 组件分解）
+
+> **本文是 `skills/ralph-loop/SKILL.md` 核心原则的 AHE 对齐展开。**
+
+## 核心职责
+
+定义 Ralph Loop (Phase 2 BUILD 默认模式) 的行为边界：逐 REQ/切片 迭代构建，每个 REQ dispatch 独立 subagent，干净上下文，全量回归测试。
+
+## 核心原则 (AHE 对齐)
+
+| # | 原则 | 说明 |
+|---|------|------|
+| 1 | 逐 REQ 迭代 | 一次处理一个 REQ/切片，干净上下文，避免上下文线性膨胀 |
+| 2 | Token 节约 | 比旧并行模式节约 40-67% token |
+| 3 | 全量回归 | 每个 REQ 完成后跑全量测试 |
+| 4 | 进度持久化 | progress.log 持久化 learnings/permanent/contextual |
+| 5 | 可中断续传 | 中断后可从最后完成 REQ 继续 |
+
+## AHE 分类
+
+| 字段 | 值 |
+|------|---|
+| 组件类型 | System Prompt |
+| 修改频率预期 | 低 |

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

@@ -0,0 +1,32 @@
+# tool-descriptions.md — Ralph Loop 各步骤工具链（AHE 组件分解）
+
+> **本文是 `skills/ralph-loop/SKILL.md` 中构建步骤的 AHE 对齐展开。**
+
+## 组件职责
+
+描述 Ralph Loop 中每个 REQ 执行的具体工具链：TDD 流、回归测试、成本监控。
+
+## 构建步骤
+
+| 步骤 | 动作 | 说明 |
+|------|------|------|
+| 1 | 加载当前 REQ | 从 specification.yaml 获取下一个 READY REQ |
+| 2 | 加载 learnings | 从 progress.log 加载 permanent + contextual learnings |
+| 3 | 测试基础设施检查 | 检查 test-utils.ts 是否存在且导出 createTestApp()、withTestDb()。不存在 → dispatch test-infra subagent，retry max 2，失败 → BLOCK/fallback |
+| 4 | TDD (RED→GREEN→REFACTOR) | test-driven-development skill（含 TDD 铁律 + Mock 边界注入）|
+| 5 | 全量回归测试 | 运行全部现有测试 |
+| 6 | 测试先行比率检查 (L1b) | 新增测试行数 / (新增测试 + 新增实现) ≥ 40% |
+| 7 | 记录 progress.log | 将 learnings 分类存储 (permanent/contextual) |
+| 8 | 成本检查 | token 使用量是否超阈值 |
+| 9 | 完成/继续 | 所有 REQ 完成 → 结束；否则 → 下一个 REQ |
+
+## 语言特定
+
+通过 `--lang` 注入对应 TDD skill: `springboot-tdd`, `django-tdd`, `golang-testing`
+
+## AHE 分类
+
+| 字段 | 值 |
+|------|---|
+| 组件类型 | Tool Description |
+| 修改频率预期 | 高 |

package/skills/ralph-loop/references/phase-2-build-ralph.md

@@ -0,0 +1,89 @@
+# Ralph Loop — Phase 2 BUILD 默认模式
+
+> ralph-loop 是 Sprint-Flow Phase 2 BUILD 的默认执行模式。token-constraint 优先：每次只处理一个 REQ，干净上下文，全量回归。
+
+## 模式切换
+
+### 默认行为
+
+```bash
+/sprint-flow "需求描述"
+# → Phase 2 自动使用 ralph-loop 模式
+```
+
+### 可选并行模式
+
+```bash
+/sprint-flow "需求描述" --mode parallel
+# → 旧有行为：一次性并行 dispatch 所有需求
+```
+
+## 核心差异
+
+| 维度 | ralph-loop (默认) | --mode parallel (可选) |
+|------|-------------------|----------------------|
+| 需求源 | specification.yaml | specification.yaml |
+| 执行方式 | 逐 REQ 串行迭代 | 一次性并行 dispatch |
+| 上下文 | 每个 REQ 独立 dispatch，干净上下文 | 共享 session，线性增长 |
+| 验证范围 | **全量测试**（含跨 REQ 回归） | 关联测试 |
+| AGENTS.md 更新 | **orchestrator 统一写** | subagent 写 |
+| 依赖排序 | 拓扑排序 + 同层 priority | 无 |
+
+## 流程
+
+```
+默认模式:                          ralph-loop 模式:
+┌──────────────────────┐           ┌──────────────────────────┐
+│ dispatching-parallel │           │ 读取 specification.yaml  │
+│ -agents              │           │ 构建依赖图                │
+│                      │           │ 拓扑排序 (Kahn's algo)    │
+│ 一次性 dispatch 所有  │           └──────────┬───────────────┘
+│ 共享同一 session      │                      ▼
+└──────────┬───────────┘           ┌──────────────────────────┐
+           │                       │ 迭代循环:                │
+           ▼                       │  取 next READY REQ       │
+┌──────────────────────┐           │  dispatch 独立 subagent  │
+│ verification +       │           │  (clean context)         │
+│   commit             │           │  L1: typecheck+lint      │
+└──────────────────────┘           │  L2: 全量测试 ← 回归检测 │
+                                   │  L3: coverage ≥ 80%      │
+                                   │  PASS → commit + learn   │
+                                   │  FAIL → retry max 3      │
+                                   └──────────┬───────────────┘
+                                              ▼
+                                         Phase 3 REVIEW
+```
+
+## 与 Sprint-Flow 参数交互
+
+| 参数 | 行为 (默认=ralph-loop) |
+|------|----------------------|
+| `--stop-at build` | 执行完 ralph-loop 后停止 |
+| `--resume-from build` | 从 checkpoint 恢复，跳过已 done REQs |
+| `--phase build-only` | 只执行 ralph-loop |
+| `--mode parallel` | 切换回旧有并行模式 |
+
+## Token 对比
+
+| REQ 数量 | 默认模式 | ralph-loop | 节约 |
+|---------|---------|-----------|------|
+| 3 | ~15k | ~9k | 40% |
+| 5 | ~50k | ~25k | 50% |
+| 10 | ~150k | ~50k | 67% |
+
+## 集成检查点
+
+Ralph Loop 完成后返回：
+
+```json
+{
+  "mode": "ralph-loop",
+  "specification_source": "specification.yaml",
+  "topology_order": ["REQ-001", "REQ-002", "REQ-003"],
+  "requirements": { "total": 6, "done": 6, "pending": 0, "blocked": 0 },
+  "learnings": { "permanent": ["..."], "contextual": ["..."] },
+  "status": "completed"
+}
+```
+
+Phase 3 REVIEW 正常执行（delphi code-walkthrough + test-specification-alignment）。PARTIAL 状态时仅检查 done REQs。

package/skills/ralph-loop/templates/progress-log.md

@@ -0,0 +1,36 @@
+# Ralph Loop — Progress Log
+
+Feature: [feature name]
+Started: [ISO 8601]
+Source: specification.yaml
+Topology Order: [REQ-001, REQ-002, ...]
+
+---
+
+## REQ-001 — [title]
+
+**Status**: PASS / FAIL / TIMEOUT / BLOCKED
+**Retry count**: 0
+**Test infra**: generated / existing / skipped
+**Files changed**: [file1, file2, ...]
+**Learnings**:
+- `[permanent]` migration files must be in src/migrations/
+- `[contextual]` off-by-one at line 42 in utils.ts
+**Timestamp**: [ISO 8601]
+
+---
+
+## REQ-002 — [title]
+
+**Status**: PASS
+**Retry count**: 1
+**Failure injected**: Linter: unused-var at line 42
+**Test infra**: existing (createTestApp, withTestDb)
+**Files changed**: [file1, file2, ...]
+**Learnings**:
+- `[permanent]` Auth middleware must run before validation
+**Timestamp**: [ISO 8601]
+
+---
+
+<!-- Append new REQs below. Tag: permanent / contextual -->