@boyingliu01/xp-gate 0.19.1 → 0.19.3

package/plugins/qoder/skills/sprint-flow/references/phase-3-build.md

@@ -6,7 +6,7 @@
 
 **摘要**: TDD 执行, 多 Agent 并行加速, 盲评验证, Gate 1 验证通过。
 
-**关键链路**: DELPHI-GATE → parallel-dispatch/ralph-loop → TDD → freeze → blind-review → unfreeze → verification → cost monitor
+**关键链路**: BUILD-ENTRY-CONTRACT → DELPHI-GATE → parallel-dispatch/ralph-loop → TDD → blind-review (read-only subagent) → verification → cost monitor
 
 **输出**: MVP v1
 
@@ -22,6 +22,27 @@
 
 ---
 
+## BUILD Entry Contract Check (MANDATORY — v0.18.0+, 程序化)
+
+**Purpose**: Validate `slices-manifest.json` schema and slice↔REQ cross-artifact consistency before entering BUILD.
+
+**Execution**: `phase-transition 3 in_progress` 时程序化校验：
+
+```
+1. slices-manifest.json 存在且 schema 合法
+2. manifest 每个 slice 引用的 REQ 必须存在于 specification.yaml
+3. 不合法 → BLOCK
+```
+
+**GATE CHECK**:
+```
+[BUILD-ENTRY] slices-manifest.json exists ✓
+[BUILD-ENTRY] manifest schema valid ✓
+[BUILD-ENTRY] slice↔REQ consistency ✓    # 每个 slice 的 REQ 引用在 specification.yaml 中存在
+```
+
+**IF GATE FAILS**: BLOCK — 返回 Phase 2/6 修复 manifest 或 specification.yaml。
+
 ---
 
 ## Uncommitted Changes Gate
@@ -81,6 +102,186 @@ SKIP_UNCOMMITTED_GATE=1
 
 ---
 
+## TDD-GATE: Pre-Implementation TDD Check (MANDATORY — v0.14.0+)
+
+**Purpose**: Enforce RED → GREEN → REFACTOR discipline at BUILD entry before any delegation.
+
+**Execution**: Before dispatching to ralph-loop or parallel agents, the orchestrator MUST verify for each REQ:
+
+### Gate Logic
+
+```
+FOR each REQ in slices-manifest.json:
+  IF test file exists for this REQ:
+    IF test passes (GREEN state) AND no implementation exists:
+      → BLOCK: TDD bypass detected. Test is passing before implementation.
+    ELSE IF test fails (RED state):
+      → ALLOW: Proceed to implementation (GREEN phase).
+  ELSE (no test file exists):
+    → ALLOW: Mark REQ as [TDD-RED]. ralph-loop creates the test as step 0.
+```
+
+### Todo Prefix Convention
+
+Each todo item MUST carry a TDD phase prefix in the content field:
+- `[TDD-RED]`: Write failing test first. No implementation yet.
+- `[TDD-GREEN]`: Write minimal implementation to make test pass.
+- `[TDD-REFACTOR]`: Refactor while keeping tests green.
+
+The priority field (high/medium/low) is separate and unchanged.
+
+Example:
+```
+"[TDD-RED] src/lib/auth.ts: Add validateToken() test for expired tokens - expect test to fail"
+"[TDD-GREEN] src/lib/auth.ts: Implement validateToken() to pass test - expect test passes"
+"[TDD-REFACTOR] src/lib/auth.ts: Extract token parsing into parseToken() helper - expect tests stay green"
+```
+
+### Deadlock Prevention
+
+The TDD-GATE is a PRE-RALPH-LOOP check, NOT a replacement for ralph-loop's internal TDD:
+- If no test exists → ralph-loop IS allowed to proceed (creates test as step 0)
+- If test exists and is GREEN without implementation → BLOCK (TDD bypass)
+- The gate verifies TDD DISCIPLINE was followed, not that TDD was skipped
+
+### Limitation
+
+This enforcement is instructional (LLM follows SKILL.md instructions), not programmatic. For stronger enforcement, consider a future automated pre-commit hook that checks git staging order (test file must be staged before source file).
+
+### Log Format (`.sprint-state/tdd-gate-log.json`)
+
+```json
+{
+  "checked": true,
+  "blocked": false,
+  "skipped": false,
+  "reqs_checked": 4,
+  "reqs_blocked": 0,
+  "timestamp": "2026-07-09T00:00:00Z"
+}
+```
+
+**Log location**: `.sprint-state/tdd-gate-log.json` — written on every gate execution for audit trail.
+
+---
+
+## In-Session Verification (MANDATORY — v0.14.31+)
+
+**Purpose**: Ensure every implementation change is immediately verified and recorded, enabling Better Loop Harness (and other observability tools) to capture normalized change→validation event pairs.
+
+**Problem it solves**: Without explicit in-session verification, Agents may edit files and move on without running tests or linters. This creates unverified changes that are invisible to post-hoc review tools, breaking the traceability chain between "what changed" and "was it validated".
+
+### Mandatory Verification Protocol
+
+After **every** implementation change (file edit, refactor, new feature, bug fix), the Agent MUST execute the following sequence BEFORE claiming the change is complete:
+
+1. **Run tests**: `npm test` or `npx vitest run` (or project-specific test command)
+2. **Run linter**: `npm run lint` or `npx eslint .` (or project-specific lint command)
+3. **Type-check** (TypeScript projects): `npx tsc --noEmit`
+4. **Record the result**: Append a structured verification event (see format below)
+
+### Verification Event Format
+
+Each verification event MUST be recorded as a structured JSON object. Agents should output this to stdout or append to `.sprint-state/phase-outputs/verification-events.jsonl`:
+
+```json
+{
+  "timestamp": "2026-07-22T10:30:00Z",
+  "change": {
+    "type": "edit|refactor|feature|bugfix",
+    "files": ["src/lib/auth.ts", "src/lib/auth.test.ts"],
+    "description": "Implement validateToken() for expired token handling"
+  },
+  "verification": {
+    "tests": { "command": "npx vitest run src/lib/auth.test.ts", "status": "pass|fail", "summary": "4 passed, 0 failed" },
+    "lint": { "command": "npm run lint", "status": "pass|fail|warn", "summary": "0 errors, 2 warnings" },
+    "typecheck": { "command": "npx tsc --noEmit", "status": "pass|fail|skip", "summary": "No type errors" }
+  },
+  "outcome": "verified|failed|partial",
+  "req": "REQ-003"
+}
+```
+
+### Integration with ralph-loop
+
+When using ralph-loop mode (default BUILD strategy), each REQ iteration MUST include verification as the final step before marking the REQ complete:
+
+```
+ralph-loop iteration:
+  1. [TDD-RED] Write failing test
+  2. [TDD-GREEN] Implement minimal code to pass
+  3. [TDD-REFACTOR] Clean up while keeping tests green
+  4. [VERIFY] Run tests + lint + typecheck ← MANDATORY
+  5. [RECORD] Append verification event ← MANDATORY
+  6. Mark REQ complete and continue to next
+```
+
+### Anti-Patterns
+
+| ❌ Error | ✅ Correct |
+|----------|----------|
+| Edit file → claim done → move to next task | Edit file → run tests + lint → record result → claim done |
+| "Tests should pass" (assertion without evidence) | "Tests passed: 4 passed, 0 failed (npx vitest run)" |
+| Run tests only at end of entire BUILD phase | Run tests after every individual change/REQ |
+| Skip type-check because "I didn't touch types" | Always run `tsc --noEmit` on TypeScript projects |
+
+### Harness Integration
+
+Better Loop Harness captures change and verification events by inspecting session history. The structured verification events above serve as the canonical signal that:
+- A change occurred (the `change` field)
+- The change was validated (the `verification` field)
+- The outcome is attributable (the `outcome` field ties result to specific change)
+
+Without these events, the Harness can only infer changes from file diffs and has no verification signal, resulting in lower "改动验证" (Change Verification) dimension scores.
+
+---
+
+## Blind Review — Read-Only Subagent Convention (v0.18.0+, 证据型标准步骤)
+
+**Purpose**: Code review by an isolated subagent with read-only tool access. Replaces the former `freeze/unfreeze` mechanism.
+
+**Convention**: The blind-review reviewer runs as a Task subagent with restricted tools:
+
+```
+tools: [Read, Grep, Glob]    # 只读 — 禁止 Write/Edit/Bash 写操作
+```
+
+**Execution**:
+1. Orchestrator dispatches a Task subagent with `tools: [Read, Grep, Glob]`
+2. Subagent reviews all changed files (from `git diff` or slices-manifest scope)
+3. Subagent outputs review findings (issues, suggestions, risks)
+4. Orchestrator records findings to `.sprint-state/phase-outputs/blind-review-report.md`
+
+**Classification**: 证据型标准步骤（非 HARD-GATE）— 执行并留存评审记录，不设程序化阻断。Worktree 本身已是隔离边界。
+
+**Anti-Pattern**: Reviewer subagent MUST NOT have Write, Edit, or Bash permissions. This ensures the review is truly read-only and cannot accidentally modify code under review.
+
+---
+
+## Learnings Capture (v0.18.0+, 原生)
+
+**Purpose**: Record patterns and lessons learned during BUILD for future sprints.
+
+**Execution**: ralph-loop 迭代中或 BUILD 完成后，将有价值的模式/教训写入：
+
+```
+.sprint-history/learnings.md
+```
+
+**Format**:
+```markdown
+## [YYYY-MM-DD] Sprint <id> — BUILD Learnings
+
+### Pattern: <title>
+- **Context**: <when this applies>
+- **Insight**: <what was learned>
+- **Action**: <how to apply in future>
+```
+
+**Note**: 替代原 `gstack/learn` 调用，纯原生文件写入，零外部依赖。
+
+---
+
 ## TDD 强制执行
 
 ### Gate 5a-BLOCK: 新增文件测试强制
@@ -115,7 +316,7 @@ SKIP_GATE_5A_BLOCK=1 git commit -m "message"
 | ralph-loop (per REQ) | TDD + verification per requirement | 5-15 min | 30 min/REQ | Mark REQ as `timeout`, continue next REQ |
 | parallel dispatch | Multi-agent parallel build | 10-30 min | 45 min | Collect partial results, continue |
 | TDD cycle (per unit) | RED → GREEN → REFACTOR | 2-5 min | 10 min | Skip unit, log failure |
-| freeze + blind-review | Code review in isolation | 5-10 min | 20 min | WARNING, continue |
+| blind-review (read-only subagent) | Code review via read-only subagent | 5-10 min | 20 min | WARNING, continue |
 | verification | Test suite + coverage check | 2-5 min | 15 min | Retry once, then BLOCK |
 | cost monitor | Token cost accounting | <1s | 5s | Skip, log warning |
 | Phase 3/6 total (lightweight) | ≤3 REQs | 15-30 min | 45 min | — |

package/plugins/qoder/skills/sprint-flow/references/phase-4-verify.md

@@ -1,15 +1,15 @@
-# Phase 4/6: VERIFY（验证 — 代码走查 + QA + 反馈获取）
+# Phase 4/6: VERIFY（验证 — 代码走查 + 测试对齐 + 反馈获取）
 
 **执行时机**: Phase 3/6 BUILD 完成后、Phase 5/6 SHIP 之前。
 **对应旧模型**: Phase 3 REVIEW + Phase 4 FEEDBACK
 
 ## 目标
 
-多专家代码走查、测试对齐、浏览器测试、反馈捕获。确保 MVP 符合 specification 并记录经验教训。
+多专家代码走查、测试对齐（#367 程序化 HARD-GATE）、浏览器验证（Layer 4 可选链）、反馈捕获。确保 MVP 符合 specification 并记录经验教训。
 
 **执行者**: orchestrator 直接执行 Part A（非 subagent dispatch — Issue #249）。
 
-Web 前端项目额外增加：系统化 QA、视觉审计、性能基线。
+Web 前端项目额外增加：原生 UI 审查 + 可选增强。
 
 ---
 
@@ -17,20 +17,27 @@ Web 前端项目额外增加：系统化 QA、视觉审计、性能基线。
 
 ### 调用 Skills
 
-**所有项目**:
-- `delphi-review --mode code-walkthrough` — 三个 Qoder Custom Agent 匿名代码走查（模型不受 provider、vendor 或国籍限制，≥90% consensus）
-- `test-specification-alignment` — 测试与 Spec 对齐验证
-- `browse` (gstack) — 浏览器自动化测试
+**所有项目（原生 HARD-GATE 链）**:
+- `delphi-review --mode code-walkthrough` — 三位专家匿名代码走查，验证三个 distinct requested_model 并聚合 ≥90% consensus
+- `test-specification-alignment` — 测试与 Spec 对齐验证（#367 程序化 HARD-GATE）
+- `xp-gate check --all` — 全量质量门禁（Gate 0–9，含安全审计）
+
+**浏览器验证 — Layer 4 可选链**:
+```
+OPTIONAL: 若检测到 gstack browse 已安装 → 使用 gstack browse 进行浏览器自动化测试
+ELSE IF 平台支持 browser-use MCP → 使用 browser-use MCP
+ELSE → SKIP 并记录 "[sprint-flow] 浏览器验证 SKIP（无可用浏览器工具）"
+```
 
 **Web 前端项目额外注入** (`--type web-nextjs` / `web-react` / `web-vue`):
-- `qa` (gstack) — 三层 QA（Quick/Standard/Exhaustive）系统化测试
-- `design-review` (gstack) — 线上 UI 视觉审计（间距、层级、AI slop 检测）
-- `benchmark` (gstack) — Core Web Vitals 性能基线
+- `xp-gate ui-review`（原生）— UI 视觉审查（间距、层级、一致性）
+- OPTIONAL: 若检测到 gstack `qa` 已安装 → 三层 QA 系统化测试；未安装则 SKIP
+- OPTIONAL: 若检测到 gstack `design-review` 已安装 → 视觉审计增强；未安装则 SKIP
+- OPTIONAL: 若检测到 gstack `benchmark` 已安装 → Core Web Vitals 基线；未安装则 SKIP
 
 **Mobile 项目额外注入** (`--type mobile-flutter` / `mobile-react-native`):
 - `flutter-test` — Flutter 单元测试 + widget 测试 (Flutter only)
 - Detox E2E — React Native 端到端测试 (RN only)
-- `flutter-review` (user) — Flutter 代码审查 (Flutter only)
 
 **Backend 项目额外注入** (`--type backend-go` / `backend-springboot` / `backend-django`):
 - API Testing — 后端 API 自动化测试
@@ -43,14 +50,15 @@ Web 前端项目额外增加：系统化 QA、视觉审计、性能基线。
 skill(name="delphi-review", user_message="--mode code-walkthrough")
 ```
 
-- architecture、technical、feasibility 三个 Custom Agent 匿名独立评审
-- Round 1 验证三份成功结果及三个 distinct trimmed `requested_model`
-- 后续轮次保持三个 Agent，最多执行到 Round 5
-- 三份结果聚合 ≥90% 共识 + APPROVED 才通过；任一执行失败都阻断
+- architecture、technical、feasibility 三位专家匿名独立评审，模型 ID 必须 distinct
+- Round 1: 三位专家独立执行，输出 `result_type=delphi_expert_result`
+- 验证三份成功结果和三个 distinct requested_model 后再聚合
+- 后续轮次最多到 Round 5，≥90% 共识 + APPROVED 才通过
+- 任一失败或模型重复都阻断，不降级为少数专家
 
 **如果 REQUEST_CHANGES**: 暂停等待用户处理 → 修复后重新评审。**如果 APPROVED**: 写入 `.code-walkthrough-result.json`（1 小时有效期）→ 进入 Step 2。
 
-#### Step 2: 调用 test-specification-alignment
+#### Step 2: 调用 test-specification-alignment（#367 程序化 HARD-GATE）
 
 ```
 skill(name="test-specification-alignment", user_message="--spec specification.yaml --tests mvp-v1/tests")
@@ -58,18 +66,61 @@ skill(name="test-specification-alignment", user_message="--spec specification.ya
 
 Phase 1: 验证对齐（可修改测试） → Phase 2: 执行测试（禁止修改测试）
 
+**#367 修复 — 程序化 HARD-GATE**:
+
+test-specification-alignment 执行后**必须**输出 `.sprint-state/phase-outputs/test-alignment-report.json`：
+
+```json
+{
+  "alignment_status": "PASS | FAIL",
+  "head_commit": "<git rev-parse HEAD>",
+  "spec_hash": "<SHA-256 of specification.yaml>",
+  "req_test_mapping": {},
+  "ac_assertion_mapping": {},
+  "timestamp": "<ISO 8601>"
+}
+```
+
+**`phase-transition 4 completed` 程序化校验**:
+- 文件缺失 → BLOCK
+- `alignment_status` 非 PASS → BLOCK
+- `head_commit` 与当前 HEAD 不符 → BLOCK（防陈旧绑定）
+- `spec_hash` 与当前 specification.yaml 不符 → BLOCK（防陈旧绑定）
+
+**--skip-evidence 逃生口护栏**:
+- `--skip-evidence` 必须同时提供 `--reason "<text>"`
+- 每次使用写入 audit.jsonl（`event: evidence_skipped, reason, phase`）
+- `xp-gate retro` 报告设曝光区块
+- 单 sprint 使用 >2 次 → 告警
+
+#### Step 2.5: 质量门禁全量验证
+
+```
+npx xp-gate check --all
+```
+
+运行所有可用的质量门禁（Gate 0–9，含安全审计 Gate 7/8/9）并输出汇总报告。任何 BLOCK 状态 → 回退 Phase 3/6 修复。
+
+> 此步骤自动调用各独立门禁（lint、复杂度、principles、架构、安全扫描等），无需手动逐个执行。替代原 `cso` 外部 skill 调用。
+
 #### Step 2.5-2.10: 项目类型特定验证（Web/Mobile/Backend）
 
-- **Web**: qa → design-review → benchmark
+- **Web**: `xp-gate ui-review`（原生）→ OPTIONAL gstack qa/design-review/benchmark（如已安装）
 - **Mobile**: flutter-test / detox E2E
 - **Backend**: API automation tests
 
-#### Step 3: 调用 browse skill
+#### Step 3: 浏览器验证（Layer 4 可选链）
 
 ```
-skill(name="browse", user_message="--url [URL] --test-ui")
+OPTIONAL: 若检测到 gstack browse 已安装:
+  skill(name="browse", user_message="--url [URL] --test-ui")
+ELSE IF 平台支持 browser-use MCP:
+  使用 browser-use MCP 进行浏览器验证
+ELSE:
+  SKIP 并记录 "[sprint-flow] 浏览器验证 SKIP（无可用浏览器工具）"
 ```
-默认: `localhost:3000`。发现问题 → 回退 Phase 3/6 修复。
+
+默认 URL: `localhost:3000`。发现问题 → 回退 Phase 3/6 修复。
 
 #### Step 4: 保存 Review Report
 
@@ -81,13 +132,14 @@ skill(name="browse", user_message="--url [URL] --test-ui")
 |--------|---------|---------|
 | delphi code-walkthrough REQUEST_CHANGES | Critical Issues 未修复 | 用户修复 → 重新评审 |
 | test-alignment 失败 | 自动回退 Phase 3/6（不暂停） | 自动迭代 |
-| browse 发现问题 | 自动回退 Phase 3/6（不暂停） | 自动迭代 |
+| 浏览器验证发现问题 | 自动回退 Phase 3/6（不暂停） | 自动迭代 |
 
 ### 输出
 
 - `.code-walkthrough-result.json`（pre-push hook 验证）
+- `.sprint-state/phase-outputs/test-alignment-report.json`（#367 程序化 HARD-GATE 证据）
 - Review Report (`review-report.md`)
-- Web 前端附加: QA report + design-review report + benchmark baseline
+- Web 前端附加: ui-review report + OPTIONAL QA/design-review/benchmark reports
 - 验证通过的 MVP
 
 ---
@@ -96,28 +148,49 @@ skill(name="browse", user_message="--url [URL] --test-ui")
 
 ### 调用 Skills
 
-- `learn` (gstack) — 模式记录（个人级）
-- `retro` (gstack) — 周工程回顾：提交历史、工作模式、代码质量趋势（团队级）
-- `systematic-debugging` (superpowers) _(可选)_ — 根因调试：反馈中的 bug 做根因分析
+**原生**:
+- `learnings.md` 写入 — 模式记录（替代原 gstack `learn`）
+- `xp-gate retro` — 工程回顾：提交历史、工作模式、代码质量趋势、返工率区块
+
+**可选（Layer 4）**:
+- OPTIONAL: 若检测到 `systematic-debugging` skill 已安装 → 根因调试（保留"无根因不修复"纪律）；未安装则使用"根因分析后方可修复"文本纪律
 
 ### 执行步骤
 
-#### Step 1: 调用 learn skill
-```
-skill(name="learn", user_message="[Emergent Issues 内容 + Sprint 总结]")
+#### Step 1: Learnings 写入（原生）
+
+将 Sprint 中发现的模式/教训写入 `.sprint-history/learnings.md`：
+
+```markdown
+## [YYYY-MM-DD] Sprint <id> — VERIFY Learnings
+
+### Pattern: <title>
+- **Context**: <when this applies>
+- **Insight**: <what was learned>
+- **Action**: <how to apply in future>
 ```
 
-#### Step 2: 工程回顾 — 调用 retro
+#### Step 2: 工程回顾 — xp-gate retro（原生）
+
 ```
-skill(name="retro")
+npx xp-gate retro
 ```
-- 提交历史分析、代码质量趋势、团队贡献分解、改进建议
 
-#### Step 3: 根因调试（可选）
+- 提交历史分析、代码质量趋势、改进建议
+- 含 #369 返工率趋势区块
+- 含 --skip-evidence 使用曝光区块
+
+#### Step 3: 根因调试（可选 — Layer 4）
+
 **IF Phase 6/6 CLOSE 发现 bug 或 Part A 验证失败**:
+
 ```
-skill(name="systematic-debugging", user_message="[具体 bug 描述]")
+OPTIONAL: 若检测到 systematic-debugging skill 已安装:
+  skill(name="systematic-debugging", user_message="[具体 bug 描述]")
+ELSE:
+  遵循"无根因不修复"文本纪律 — 先分析根因，确认后再修复
 ```
+
 Iron Law: 无调查 → 不修复
 
 #### Step 4: 转化 Emergent Issues 为 Sprint 2 Pain Document
@@ -147,6 +220,6 @@ Iron Law: 无调查 → 不修复
 ### 输出
 
 - Feedback Log (`feedback-log.md`)
-- Retro Report（retro 输出）
+- Retro Report（`xp-gate retro` 输出）
 - Sprint 2 Pain Document (`sprint2-pain.md`) — 如果有 emergent issues
 - 进入 Phase 5/6 SHIP 自动执行