@boyingliu01/xp-gate 0.18.4 → 0.19.0

package/plugins/dsh/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/plugins/dsh/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/plugins/dsh/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 -->

package/plugins/dsh/skills/sprint-flow/AGENTS.md

@@ -0,0 +1,103 @@
+# SKILLS/SPRINT-FLOW KNOWLEDGE BASE
+
+**Generated:** 2026-08-24
+**Commit:** a1a4683
+**Branch:** dsh-plugin
+**Version:** 0.19.0.0
+
+## OVERVIEW
+**6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.
+
+> **v2.0 Compact Redesign (Issue #290)**: Merged from 11 phases to 6. PREP = old ISOLATE + AUTO-ESTIMATE. DESIGN = old THINK + PLAN. BUILD = old BUILD. VERIFY = old REVIEW + FEEDBACK. SHIP = old SHIP + LAND. CLOSE = old USER ACCEPTANCE + CLEANUP.
+
+## STRUCTURE
+```
+skills/sprint-flow/
+├── SKILL.md              # 6-phase pipeline definition (canonical, v2.0)
+├── AGENTS.md             # This file (mirrored to 7 other locations — DO NOT edit mirrors)
+├── evals/                # Evaluation test cases
+├── evolution-history.json
+├── evolution-log.md
+├── references/
+│   ├── phase-1-prep.md                    # Phase 1/6: PREP (worktree isolation + sizing)
+│   ├── phase-2-design.md                  # Phase 2/6: DESIGN (brainstorming + delphi-review HARD-GATE)
+│   ├── phase-3-build.md                   # Phase 3/6: BUILD (ralph-loop default + TDD + test-align)
+│   ├── phase-4-verify.md                  # Phase 4/6: VERIFY (code-walkthrough + QA + feedback)
+│   ├── phase-5-ship.md                    # Phase 5/6: SHIP (PR + merge + deploy + canary)
+│   ├── phase-6-close.md                   # Phase 6/6: CLOSE (UAT + cleanup)
+│   ├── force-levels.md                    # Phase forcing rules
+│   ├── orchestration-rules.md             # Agent dispatch, context inheritance, transition rules
+│   └── components/                        # Reusable phase building blocks
+└── templates/
+    ├── auto-estimate-output-template.md
+    ├── auto-estimate-learning-log.md
+    ├── pain-document-template.md
+    ├── sprint-progress-template.md
+    ├── sprint-summary-template.md
+    └── emergent-issues-template.md
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Pipeline definition | SKILL.md | 6 phases with HARD-GATE between DESIGN (2/6) and BUILD (3/6) |
+| PREP phase | references/phase-1-prep.md | worktree isolation + sizing pass |
+| DESIGN phase + HARD-GATE | references/phase-2-design.md | brainstorming + autoplan + delphi-review → specification.yaml |
+| BUILD phase | references/phase-3-build.md | ralph-loop (default) vs parallel |
+| VERIFY phase | references/phase-4-verify.md | code-walkthrough + QA + retro + learn |
+| SHIP phase | references/phase-5-ship.md | PR + merge + deploy + canary |
+| CLOSE phase | references/phase-6-close.md | UAT + cleanup |
+| Force-level rules | references/force-levels.md | Defines when each phase becomes mandatory |
+| Orchestration rules | references/orchestration-rules.md | Agent dispatch, context inheritance, transition gates |
+| Templates | templates/ | Auto-estimate, sprint progress/summary, pain doc, emergent issues |
+
+## THE 6 PHASES (v2.0)
+
+| Phase | Name | Maps From (old 11) | Key Action | Hard Gate |
+|-------|------|-------------------|------------|-----------|
+| 1/6 | PREP | ISOLATE + AUTO-ESTIMATE | Worktree isolation + sizing | — |
+| 2/6 | DESIGN | THINK + PLAN | brainstorming → autoplan → Delphi consensus | **HARD-GATE**: design must reach ≥90% Delphi consensus |
+| 3/6 | BUILD | BUILD | ralph-loop (default) + TDD + test-spec-alignment | — |
+| 4/6 | VERIFY | REVIEW + FEEDBACK | code-walkthrough + QA + retro + learn | HARD-GATE: feedback-log.md must exist |
+| 5/6 | SHIP | SHIP + LAND | PR → squash-merge → deploy → canary | — |
+| 6/6 | CLOSE | USER ACCEPT + CLEANUP | Manual UAT → emergent issues → cleanup | HARD-GATE: UAT mandatory manual |
+
+## CONVENTIONS
+- **ralph-loop is Phase 3/6 BUILD default**. Each REQ runs in a clean context, saving 40-67% tokens.
+- **delphi-review HARD-GATE in Phase 2/6 DESIGN**: all three expert roles must execute with three distinct requested model IDs, then aggregate ≥90% consensus within 5 rounds. Unapproved or unverifiable → BLOCK coding.
+- **`learn` is called twice**: once per REQ in Phase 3/6 (ralph-loop internal) and once in Phase 4/6 VERIFY (Sprint-level retro).
+- **Phase isolation**: each phase has explicit entry/exit criteria documented in its `references/phase-*.md` file.
+- **Emergent Requirements** discovered in Phase 6/6 CLOSE (USER ACCEPTANCE) are explicitly captured via `templates/emergent-issues-template.md` — never silently merged.
+- **Auto-detection**: Phase 2/6 DESIGN uses `src/npm-package/lib/ui-detector.ts` to pick the right tech-stack templates.
+
+## ANTI-PATTERNS (THIS PROJECT)
+- Do NOT skip `delphi-review` in Phase 2/6 DESIGN — HARD-GATE blocks implementation.
+- Do NOT use parallel build mode unless explicitly requested. Ralph-loop is the default for a reason.
+- Do NOT enter Phase 2/6 DESIGN (PLAN) without completing DESIGN (brainstorming).
+- Do NOT implement before design is APPROVED — Phase 2/6 DESIGN must reach Delphi consensus first.
+- Do NOT merge an Emergent Requirement into the original Sprint silently — capture it via the template in Phase 6/6 CLOSE.
+- Do NOT terminate Delphi review before ≥90% consensus or 5 rounds, whichever first.
+
+## UNIQUE STYLES
+- **6 phases** (v2.0 Issue #290) — compact design with merged phases (1-6 numbering)
+- **HARD-GATE** between DESIGN and BUILD enforced both in SKILL.md and Claude Code plugin's PreToolUse hook.
+- **Per-REQ clean context in ralph-loop** = the core efficiency mechanism.
+- **Tech-stack auto-detection** via `--type` and `--lang` flags or `ui-detector.ts`.
+
+## COMMANDS
+```bash
+/sprint-flow "开发用户登录"                                     # Full 6-phase pipeline
+/sprint-flow "开发用户登录" --type web-nextjs --lang typescript # Pin tech stack
+/sprint-flow "开发用户登录" --phase build-only                  # Skip design (advanced)
+/sprint-flow "开发用户登录" --mode parallel                     # Legacy all-at-once (NOT default)
+/sprint-flow "开发用户登录" --stop-at design                    # Stop after DESIGN phase
+/delphi-review "开发用户登录" --type web-nextjs --lang typescript
+```
+
+## NOTES
+- Integrates: brainstorming, autoplan, delphi-review, TDD, test-specification-alignment, qa, design-review, benchmark, systematic-debugging, retro, learn, finishing-a-development-branch, land-and-deploy.
+- ralph-loop's internal learnings are persisted via `progress.log` (permanent vs contextual classification).
+- Phase 4/6 VERIFY calls `gstack/learn` for Sprint-level retrospective.
+- Phase 6/6 CLOSE cleanup behavior is governed by `docs/plans/2026-06-06-sprint-branch-cleanup-design.md`.
+- This `AGENTS.md` is the canonical version. **7 byte-identical mirrors** exist.
+  Mirrors are updated by `scripts/copy-skills.sh`. Do NOT edit them by hand.