@boyingliu01/xp-gate 0.18.5 → 0.19.1

package/plugins/dsh/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/plugins/dsh/skills/domain-modeling/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/plugins/dsh/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+---
+
+Run a `/grilling` session, using the `/domain-modeling` skill.

package/plugins/dsh/skills/grilling/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
+
+If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+
+Do not act on it until I confirm we have reached a shared understanding.

package/plugins/dsh/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: improve-codebase-architecture
+description: Find deepening opportunities in a codebase, informed by domain language in CONTEXT.md and decisions in ADRs. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable. Run periodically (weekly or after surges of development).
+---
+
+# Improve Codebase Architecture
+
+周期性架构健康检查：发现 **shallow module → deep module** 的深度化机会。目标是提升可测试性、AI 可导航性、模块边界清晰度。
+
+与 XP-Gate 质量门禁的分工：
+| 机制 | 时机 | 作用 |
+|------|------|------|
+| **6 道门禁** | 每次 commit | 被动拦截明显问题（函数过长、重复代码等） |
+| **improve-codebase-architecture** | 每周/开发潮后 | 主动深度化改进（seam 识别、模块合并、接口提炼） |
+
+---
+
+## 术语（与 XP-Gate Principles 一致）
+
+| 术语 | 定义 |
+|------|------|
+| **Module** | 任何有接口和实现的东西（函数、类、包、slice） |
+| **Interface** | 调用者使用前必须知道的一切：类型、不变量、错误模式、顺序、配置 |
+| **Implementation** | 接口背后的代码 |
+| **Depth** | 接口的杠杆率：大量行为隐藏在简单接口后。**Deep = 高杠杆**。**Shallow = 接口几乎与实现一样复杂** |
+| **Seam** | 接口所在位置；可以在不修改实现的情况下改变行为的地方 |
+| **Adapter** | 在 seam 处满足接口的具体实现 |
+| **Locality** | 深度带来的可维护性收益：变更、bug、知识集中在一处 |
+
+---
+
+## 核心判断工具
+
+### Deletion Test
+想象删除某个模块：
+- 如果复杂性消失 → 它是 pass-through，不值得保留
+- 如果复杂性在 N 个调用方中重新出现 → **它真正提供了价值**
+- **"Yes, concentrates" = 你想发现的信号**
+
+### The Interface Is the Test Surface
+接口就是测试的边界。如果测试需要深入实现细节，说明接口太浅。
+
+### One Adapter = Hypothetical Seam. Two Adapters = Real Seam.
+只有一个实现满足接口 → 可能过度抽象。两个以上 → 真正的可替换边界。
+
+---
+
+## 流程
+
+### 1. 探索
+
+先读项目的 `CONTEXT.md`（领域语言）和 `docs/adr/`（架构决策）。
+
+然后有机地走查代码库（不要遵循死板启发式），注意你在哪里感受到摩擦：
+
+- 理解一个概念是否需要在多个小文件间跳来跳去？
+- 模块是否 **shallow** — 接口几乎与实现一样复杂？
+- 纯函数是否仅仅为了可测试性而被提取，但真正的 bug 隐藏在调用方式中？（缺乏 **locality**）
+- 紧密耦合的模块是否在其 seams 之处泄漏？
+- 哪些部分难以通过当前接口进行测试？
+
+对任何怀疑 shallow 的模块执行 **Deletion Test**：删除它会让复杂性集中还是分散？"是的，会集中"就是你要的信号。
+
+### 2. 呈现候选项
+
+以编号列表呈现深度化机会。每项包含：
+
+- **Files** — 涉及哪些文件/模块
+- **Problem** — 当前架构为何造成摩擦（使用 CONTEXT.md 中的领域术语）
+- **Solution** — 自然语言描述会怎样改变
+- **Benefits** — 用 locality 和 leverage 解释收益，以及测试会怎样改善
+
+**使用 CONTEXT.md 领域术语。如果与 ADR 冲突**，仅在摩擦值得重新讨论 ADR 时才标注：
+> *"Contradicts ADR-0007 — 但值得重新打开，因为…"*
+
+不要列出 ADR 禁止的每个理论重构。
+
+**此时不要提出接口设计**。先问用户："你想探索哪个候选项？"
+
+### 3. 用户选择候选项
+
+仅当用户明确选择某个候选项时，才进入步骤 4。
+
+### 4. Grilling 循环（设计树遍历）
+
+用户选中某个候选项后，进入 grilling 对话：
+- 遍历约束、依赖、深度化模块的形状
+- seam 背后放什么、什么不放在 seam 背后
+- 哪些测试能在深度化后存活/新增
+
+**对话中的副作用**（决策固化时立即执行）：
+- 命名不在 CONTEXT.md 中的新概念 → **新增到 CONTEXT.md**
+- 模糊术语在对话中变清晰 → **更新 CONTEXT.md**
+- 用户拒绝候选项且有有理由 → **提议记录为 ADR**（避免未来重复建议）
+- 需要探索替代接口 → **按接口设计原则引导**
+
+### 5. 输出（可选）
+
+如果用户在 grilling 后决定执行重构：
+- 生成重构计划（含文件列表、步骤顺序、风险点）
+- 调用 test-driven-development skill 执行重构（保持行为不变）
+
+---
+
+## 与 XP-Gate 集成
+
+### 触发时机
+```
+Phase 5 (FEEDBACK) 后推荐调用：
+  → learn + retro + **improve-codebase-architecture**
+  → 发现架构摩擦 → 记录到 retro → 下一 Sprint 纳入 backlog
+
+或作为独立周期性任务：
+  → /improve-codebase-architecture  → 每周/开发潮后
+```
+
+### 与 ralph-loop 的关系
+架构改进本身可以作为一个独立的 REQ 通过 ralph-loop 执行：
+- REQ: "深度化 Order 模块（从 N 个散文件合并为 deep module）"
+- 通过 test-driven-development 保证行为不变
+
+### 与质量门禁的关系
+架构改进后，质量门禁的 violation 数量应减少：
+- God class → 拆分为 deep modules → SOLID-001 (SRP) 告警消失
+- Deep nesting → 封装为简单接口 → CC-002 告警消失
+- Code duplication → 提取公共 deep module → Gate 2 (Dup Code) 改善
+
+---
+
+## Anti-Patterns
+
+| ❌ 错误 | ✅ 正确 |
+|---------|---------|
+| 仅在文件层面重构（拆分大文件） | 在概念边界处重构（deep module 封装行为） |
+| 为了测试而提取纯函数 | 为了 locality 和组织行为边界而重构 |
+| 过度设计接口（只有一个 adapter） | 发现真实 seam（≥2 adapters 或需要可测试性）后再抽象 |
+| 忽视现有 ADR 提出重构 | 尊重 ADR，仅在摩擦值得重新讨论时标注冲突 |
+| 一次性重构整个模块 | 逐个候选项执行，使用 TDD 保证行为不变 |
+| 与 ADR 冲突但不记录决策 | 记录为 ADR，避免未来重复建议 |
+
+---
+
+## 使用示例
+
+```
+/improve-codebase-architecture
+
+→ Explore: 读取 CONTEXT.md, 走查代码库
+→ 发现 3 个浅模块候选项
+→ 呈现: #1 Order 模块过浅 / #2 Auth 适配器泄漏 / #3 支付领域缺乏 locality
+→ 用户选中 #1
+→ Grilling: 讨论 Order 的 seam 应该在哪
+→ 更新 CONTEXT.md: 新增 "Order Intake" 术语
+→ 提议 ADR: "Order 状态机封装" → 用户同意 → 创建 docs/adr/000X.md
+→ 输出: 重构计划 → TDD 执行
+```

package/plugins/dsh/skills/ralph-loop/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: ralph-loop
+description: Use when executing Sprint-Flow Phase 2 BUILD, processing one REQ, building the next requirement, iterating with clean context, or requiring full regression per requirement.
+maturity: stable
+---
+
+# Ralph Loop — Default REQ-Level Iterative Build
+
+Core principles: **isolated context per REQ**, **TDD-first**, **full regression every iteration**, **token efficiency** (40-67% savings vs parallel).
+
+## Triggers
+
+**Keywords**: ralph-loop, process one REQ, Phase 2 BUILD, iterate REQ, isolated REQ build
+
+**Use when**: executing Sprint-Flow Phase 2 BUILD; reading specification.yaml to implement REQs one-by-one; needing controlled token budget per REQ; preventing context pollution between REQs; full regression needed per step.
+
+**Don't use**: 1-2 simple independent REQs (use parallel); emergency hotfix; `--mode parallel` is explicitly set.
+
+## Architecture Overview
+
+Ralph Loop is the **default Phase 2 BUILD mode**. Each REQ gets a fresh subagent context:
+
+```
+Sprint-Flow Phase 2 (default):
+  ralph-loop → per-REQ iteration → clean context each time → full regression
+
+Sprint-Flow Phase 2 (--mode parallel):
+  dispatching-parallel-agents → parallel dispatch → context grows linearly
+```
+
+## Full Flow
+
+```
+Phase 0: 准备 → 读取 specification.yaml → 构建依赖图 → 拓扑排序
+    │
+    ▼
+Phase 1: 迭代循环 (max_iterations=15 默认)
+    │
+    ├── 取下一个 READY REQ（依赖已满足，优先级最高）
+    │
+    ├── 测试基础设施检查 (test-utils.ts)
+    │     ├── 不存在或接口缺失 → dispatch 生成 subagent (retry max 2)
+    │     └── 已存在 → 注入 API 摘要到 subagent context
+    │
+    ├── Dispatch 独立 subagent (unspecified-high + test-driven-development)
+    │     Context: 当前 REQ + AC + permanent learnings + contextual learnings
+    │              + AGENTS.md + git log -5 + Mock 边界策略
+    │
+    ├── 三层验证
+    │     ├── L1: typecheck + lint → FAIL? → retry
+    │     ├── L1b: 测试行占比 ≥ 40% → FAIL? → retry
+    │     ├── L2: 全量测试（ALL tests）→ FAIL? → retry
+    │     └── L3: coverage ≥ 80% → FAIL? → retry
+    │
+    ├── PASS → git commit → 标记 done
+    │        → 写 learnings (permanent/contextual)
+    │        → orchestrator 更新 AGENTS.md
+    │        → 继续下一个 READY REQ
+    │
+    └── FAIL (max 3 retry) → BLOCK → 用户决策 (skip/manual/stop/rollback)
+        │
+        ▼
+    终止条件: ALL DONE → COMPLETE | max_iterations → PARTIAL | BLOCK → WAIT_USER
+```
+
+## 输入格式 (specification.yaml)
+
+```yaml
+specification:
+  requirements:
+    - id: REQ-001
+      description: "Create User Model"
+      acceptance_criteria:
+        - id: AC-001-01
+          criteria: "email (unique), password_hash, created_at"
+      priority: 1
+      status: pending
+    - id: REQ-002
+      description: "Password encryption"
+      depends_on: [REQ-001]
+      priority: 2
+      status: pending
+```
+
+每个 REQ 自动作为迭代单元，所有 AC-XXX-XX 作为验收标准。
+
+## 依赖排序
+
+1. 拓扑排序（Kahn's algorithm，基于 `depends_on`）
+2. 同层按 `priority` 升序
+3. 循环依赖 → BLOCK + 报告循环链
+
+## 状态机
+
+```
+PENDING → test_infra_check → [infra needed?] → test_infra_dispatch
+                                        │                    │
+                                        │ FAIL (max 2)      │ pass
+                                        ▼                    ▼
+                                    BLOCK/fallback      in_progress → done (commit)
+                                        │                  │
+                                        │  depend not met  │ all done → COMPLETE
+                                        ▼                  ▼
+                                     PENDING (waiting)  RETRY (n≤3, 注入错误)
+                                                            │
+                                                         n≥3 → BLOCKED
+```
+
+**崩溃恢复**：检查 checkpoint → 跳过已 done REQs → 从下一个 pending 继续。
+
+## Retry 策略
+
+| 轮次 | 注入上下文 | 超时 |
+|------|-----------|------|
+| 1 | 标准上下文 | 300s |
+| 2 | 标准 + 上次失败摘要 | 300s |
+| 3 | 标准 + 前两次失败 + "请使用不同实现方式" | 300s |
+
+## Mock 边界策略
+
+| Mock | No Mock |
+|------|---------|
+| 外部 HTTP API、LLM 调用、第三方平台 | 数据库（真实测试库或 sqlite-in-memory）|
+| 时间/随机数/UUID（注入依赖） | HTTP 路由（app.inject()）|
+| — | 模板引擎（真实渲染）|
+| — | 纯业务逻辑（真实输入输出）|
+
+Mock 密度上限：mock/spy/fn 行数 > 总测试行 30% → 必须加 `// @mock-justified: <理由>`。
+
+## Learnings 分类
+
+| 分类 | 内容 | 传递策略 | 升级条件 |
+|------|------|---------|---------|
+| permanent | 架构决策、接口约定 | 始终传入 | ≥2 REQ 引用 / 涉及接口/数据结构 / 用户手动标记 |
+| contextual | 实现细节、一次性 gotchas | 滑动窗口 (最近 3 条) | 满足 permanent 条件自动升级，否则过期 |
+
+## AGENTS.md 更新机制
+
+Orchestrator 统一执行，subagent 输出 `agentmd_addition` 字段，orchestrator append。>500 行触发归档到 `.sprint-state/ralph-loop/agents-archive/`。
+
+## Output Format
+
+```json
+{
+  "skill_name": "ralph-loop",
+  "version": "2.0.0",
+  "requirements": { "total": 6, "done": 4, "pending": 1, "blocked": 1, "skipped": 0 },
+  "learnings": {
+    "permanent": ["Auth middleware must run before validation"],
+    "contextual": ["migration files must be in src/migrations/"]
+  },
+  "status": "running",
+  "checkpoint_at": "2026-05-08T10:30:00Z"
+}
+```
+
+**Eval**: `done + pending + blocked + skipped == total`, `iteration <= max_iterations`.
+
+## Scope
+
+**In Scope**:
+- Phase 2 BUILD 的 REQ 级迭代构建
+- 从 specification.yaml 读取需求实现
+- TDD + 全量回归测试
+- Learnings 持久化 + 依赖排序 + 崩溃恢复
+
+**Out of Scope**:
+- Phase 0-1 (THINK/PLAN) / Phase 3-6 (REVIEW/SHIP/等)
+- 并行模式（`--mode parallel`）
+- 紧急热修复
+- 非 spec 定义的需求
+
+## Token Savings
+
+| REQs | Default | Ralph Loop | Savings |
+|------|---------|-----------|---------|
+| 3 | ~15k | ~9k | 40% |
+| 5 | ~50k | ~25k | 50% |
+| 10 | ~150k | ~50k | 67% |
+
+## Anti-Patterns
+
+| ❌ Wrong | ✅ Right |
+|----------|---------|
+| 所有需求一个 REQ | 每个 REQ ≤ 1 context window |
+| 验证失败仍 commit | 不提交 |
+| 只跑当前 REQ 的测试 | 全量回归 |
+| 忽略 depends_on | 拓扑排序 |
+| retry 不注入失败原因 | 每次注入上次错误 |
+| subagent 各自写 AGENTS.md | orchestrator 统一更新 |
+
+## References
+
+- [Components](references/components.md) — 系统提示/状态记忆/中间件/技能调用/构建步骤分解
+- [Workflow Details](references/workflow-details.md) — 详细执行步骤 + Output Contract 检查清单
+- [Phase 2 Integration](references/phase-2-build-ralph.md) — Sprint-Flow 集成细节
+- [Progress Log Template](templates/progress-log.md)
+- [Design Doc: ralph-loop v3.0](docs/ralph-loop-design.md)

package/plugins/dsh/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 完成 → 结束；否则 → 下一个 |