@boyingliu01/xp-gate 0.10.11 → 0.10.13

package/plugins/qoder/skills/sprint-flow/references/orchestration-rules.md

@@ -0,0 +1,365 @@
+## 编排层规则（Orchestration Rules）
+
+### Agent Dispatch Rules
+
+| Agent Type | 适用场景 | 不适用场景 | 超时处理 |
+|-----------|---------|-----------|---------|
+| `explore` (bare) | **窄搜索**：单个关键词/pattern，已知文件位置 | 多角度宽泛搜索，读取大文件，3+ search angles | >5min → cancel + 用 `deep` 重试 |
+| `librarian` (bare) | **外部参考**：API 文档、OSS 示例 | 内部代码库宽泛探索 | >5min → cancel + 用 `deep` 重试 |
+| `task(category="deep")` | **复杂研究**：多模块分析，架构决策 | 单文件 trivial fix | 无限制 |
+| `task(category="unspecified-high")` | **高 effort 实现**：新模块、重构 | 单行修改 | 无限制 |
+
+**关键规则**：
+
+1. Bare `explore` agent 本质是 contextual grep，**不是研究 agent**。如果任务涉及：
+   - 3+ 个独立搜索角度
+   - 读取多个大文件（>200 行）
+   - 需要跨层分析（如"查 ralph-loop + .sprint-state/ + token 阈值 + phase transition"）
+   
+   → **必须用 `task(category="deep", load_skills=[...])` 替代**
+
+2. 如果 `explore` agent >5 分钟未返回 → cancel 并立即用 `task(category="deep")` 重试。不要等待。
+
+3. **并行 explore 仍然是正确模式**。2-4 个窄搜索 explore agent 并行执行是高效且推荐的。问题在于给单一 explore agent 分配宽泛任务。
+
+**issue #83 根因**：`bg_1abf2ed9` 被分配了 4 个独立搜索角度的宽泛任务（ralph-loop context + .sprint-state/ + token threshold + phase transition），bare explore agent 超时丢失 session。同批的 `bg_5ecf590d`（窄搜索 OpenCode compaction API）3m35s 正常完成。
+
+### Phase Subagent Dispatch Matrix
+
+| Phase | 名称 | Subagent? | Category | load_skills | 执行者 |
+|-------|------|:---------:|----------|-------------|--------|
+| -1 | ISOLATE | ❌ | Bash（直接执行） | 无 | orchestrator |
+| -0.5 | AUTO-ESTIMATE | ❌ | Bash（直接执行） | 无 | orchestrator |
+| 0 | THINK | ❌ | orchestrator（直接执行） | `["brainstorming"]` | orchestrator |
+| 1 | PLAN | ❌ | orchestrator（直接执行） | `["autoplan", "delphi-review", "to-issues"]` | orchestrator |
+| 2 | BUILD | ✅ | ralph-loop | `["test-driven-development"]` | subagent |
+| 3 | REVIEW | ❌ | orchestrator（直接执行） | `["delphi-review", "test-specification-alignment"]` | orchestrator |
+| 4 | USER ACCEPT | ❌ | **强制人工** | 无 | 用户 |
+| 5 | FEEDBACK | ✅ | `quick` | `["learn", "retro", "systematic-debugging"]` | subagent |
+| 6 | SHIP | ❌ | orchestrator（直接执行） | `["finishing-a-development-branch", "ship"]` | orchestrator |
+| 7 | LAND | ❌ | orchestrator（直接执行） | `["land-and-deploy"]` | orchestrator |
+| 8 | CLEANUP | ❌ | Bash（直接执行） | 无 | orchestrator |
+
+**⚠️ 交互式 skill 必须由 orchestrator 直接执行（不可 dispatch 到 subagent）**：
+
+| Phase | Skill | 为什么不能在 subagent 中执行 |
+|-------|-------|---------------------------|
+| 0 | `brainstorming` | 需要与用户对话确认需求、提出澄清问题。Subagent 是 fire-and-forget 模式，无法暂停等待用户输入（Issue #217） |
+| 1 | `autoplan` | taste_decisions 节点暂停等待用户确认。必须由 orchestrator 直接执行（Issue #225） |
+| 1 | `delphi-review` | design 模式需等待 verdict APPROVED；非 APPROVED 时需用户确认是否接受分歧方案（Issue #249） |
+| 1 | `to-issues` | Step 6 "向用户确认" — 展示拆分结果，等待用户批准后才生成 slices-manifest.json |
+| 3 | `delphi-review --mode code-walkthrough` | Code walkthrough 非 APPROVED 时需暂停等待用户处理 Critical Issues（Issue #249） |
+| 6 | `finishing-a-development-branch` | 4 选项菜单 (merge/PR/keep/discard) 需要用户选择；Option 4 (discard) 要求 typed confirmation |
+| 6 | `ship` | PR 创建前需要用户确认；包含 AskUserQuestion STOP 点 |
+| 7 | `land-and-deploy` | Merge 确认、rollback 决策 — 均为用户交互点 |
+
+**Phase 1 执行模式（全部 orchestrator 直接执行）**：
+1. **Orchestrator 直接执行 autoplan**：`skill(name="autoplan")` → 等待用户确认 taste_decisions
+2. **Orchestrator 直接执行 delphi-review**：`skill(name="delphi-review")` → 等待 APPROVED（非 APPROVED 时暂停等待用户确认）
+3. **Orchestrator 直接执行 to-issues**：`skill(name="to-issues")` → 等待用户确认 Issue 拆分
+
+**上下文隔离原则**：
+- 每个 Subagent 在**独立 session** 中启动，不继承 orchestrator 的对话历史
+- orchestrator session 仅接收 subagent 的最终结果摘要（~13,000 tokens/sprint）
+- 现代模型百万 token 上下文 + 缓存命中 → 单 sprint 不会触发 overflow
+
+### CONTEXT INHERITANCE
+
+每个 Phase subagent 启动时，上下文仅通过以下路径继承：
+
+| Phase | 加载来源 | 内容 |
+|-------|---------|------|
+| Phase -1 | 无前置（Bash 操作） | 用户原始需求 + 当前分支状态 |
+| Phase 0 | phase--1-summary（仅路径） | 隔离环境信息（worktree 路径） |
+| Phase 1 | phase-0-summary.md + design-doc | 设计决策 + 结构化规格 |
+| Phase 2 | phase-1-summary.md + specification.yaml | 评审结论 + REQ 列表 |
+| Phase 3 | phase-2-summary.md + MVP 代码 | 构建结果（orchestrator 直接执行，无 subagent 上下文继承） |
+| Phase 4 | — | **人工验收**。Phase 4 不产生 subagent summary，但用户验收结果记录在 `.sprint-state/phase-outputs/emergent-issues.md`（如有 emergent issues）。Phase 5 加载此文件。 |
+| Phase 5 | phase-4-summary.md + emergent-issues.md | 验收结论 |
+| Phase 6 | phase-5-summary.md + feedback-log.md | 复盘结论 |
+| Phase 7 | phase-6-summary.md + PR URL | 发布准备 |
+| Phase 8 | phase-7-summary（Bash 操作） | 部署结果 |
+
+**隔离原则**：每个 Phase subagent 在干净上下文中启动。
+输入仅限上表对应的摘要文件和一级产出物。
+不包含前一 Phase 的完整对话、中间文件、失败尝试。
+
+**特殊场景**：
+- `--resume-from <phase>`：跳过前置 Phase，直接从指定 Phase 启动。**MUST 先执行 RESUME GATE（Issue #148）** 校验 sprint 状态、git 可达性和文件时效性，再执行 Phase Transition Gate 校验摘要文件格式。例如 `--resume-from build` 要求 `phase-1-summary.md` 和 `specification.yaml` 已存在且非 stale。
+- `--no-isolate`：跳过 Phase -1 ISOLATE，直接在当前分支执行。Phase 0 无 `phase--1-summary` 可用，上下文继承来源为用户原始需求 + 当前 git 状态。所有后续 Phase 的 worktree enforcement 不适用（无 worktree），但仍需保持代码隔离。
+- `next_phase_context` 中的 `{path}` 等变量占位符在实际写入时被替换为具体值。示例中的 `{path}` 应替换为实际 worktree 路径（如 `.worktrees/sprint/sprint-2026-06-01-01`）。
+
+### PHASE TRANSITION RULES
+
+每个 Phase subagent 完成后，必须按顺序执行以下步骤：
+
+1. **写入 Phase 摘要**：创建 `.sprint-state/phase-outputs/phase-{N}-summary.md`
+   - 格式：YAML frontmatter + Markdown body（body ≤ 50 行）
+   - 大小限制：≤ 40,000 字符（≈ 10,000 tokens）
+
+2. **更新 sprint-state.json**：
+   - `phase`: 当前阶段编号
+   - `outputs`: 新增当前阶段输出文件路径
+   - `phase_history`: 追加或更新当前阶段的记录
+     - Phase 开始时：追加 `{ "phase": N, "phase_name": "NAME", "status": "running", "started_at": "<ISO 8601>", "completed_at": null, "duration_seconds": null }`
+     - Phase 完成时：更新对应条目，填充 `completed_at`（ISO 8601）和 `duration_seconds`（`completed_at - started_at` 的秒数）
+     - Phase 跳过时（如轻量路由跳过 Phase 0 brainstorming）：设置 `status: "skipped"`
+
+3. **等待用户确认 checkpoint**（如适用）
+
+4. **展示进度看板**：执行 `node scripts/render-sprint-progress.cjs` 渲染进度看板
+   - 脚本自动读取 `.sprint-state/sprint-state.json` 并输出 ASCII 进度看板
+   - 渲染规则：已完成阶段显示 ✅ + 耗时，当前阶段 🔄，待做 ⬜，跳过 ⏭️，失败 ❌
+   - 进度条：`[████▓░░░░░░] {pct}%`（已完成数/总阶段数 11）
+   - 下一步行动：根据当前阶段 + 状态，自动查找对应提示
+   - 输出物路径：列出 `outputs` 中已有的文件路径
+   - 时机：每个 Phase 完成后的 transition 阶段自动展示，用户无需请求
+   - 向后兼容：旧版 `sprint-state.json` 缺少 `phase_history` 时，从 `phase` 字段推断状态
+
+### Background Task Resume Protocol (MANDATORY — Issue #248)
+
+After dispatching background agents with `run_in_background=true` (e.g., Phase -0.5 AUTO-ESTIMATE explore agents, Phase 1 delphi-review subagent):
+
+1. **END YOUR RESPONSE** — do NOT poll `background_output()` before receiving `<system-reminder>`
+2. **On `<system-reminder>` notification**: collect ALL completed results via `background_output(task_id="bg_...")`
+3. **When ALL tasks complete**: immediately resume by:
+   a. Synthesizing results into the current phase assessment
+   b. Executing the phase transition gate
+   c. Continuing to the next phase **WITHOUT waiting for human input**
+4. **If any task failed**: collect partial results, log the failure, continue with available data (do NOT block the pipeline)
+
+**The orchestrator MUST treat task completion notifications as an implicit "continue" signal.** This protocol prevents the "human-in-loop stall" where all background tasks complete but the orchestrator waits indefinitely for a human message (Issue #235, #248).
+
+### Phase Summary 格式（YAML Frontmatter Schema）
+
+每个 `phase-N-summary.md` 必须包含以下 YAML frontmatter：
+
+```markdown
+---
+phase: -1
+phase_name: ISOLATE
+status: completed
+outputs:
+  - path: ".worktrees/sprint/sprint-YYYY-MM-DD-NN"
+    type: directory
+decisions:
+  - title: "Worktree isolation enabled"
+    rationale: "Prevent main branch pollution"
+unresolved_issues: []
+next_phase_context: "Worktree created at {path}. All subsequent edits MUST use this workdir."
+---
+
+## Phase Summary
+{简明摘要，不超过 50 行}
+```
+
+**必填字段**: `phase`, `phase_name`, `status`, `outputs`, `decisions`, `next_phase_context`
+**可选字段**: `unresolved_issues`
+
+### Phase Transition Gate
+
+Orchestrator dispatch 下一 Phase 前必须执行验证：
+
+```bash
+# === Phase Transition Gate ===
+
+# 1. Phase summary file validation
+SUMMARY=".sprint-state/phase-outputs/phase-${N}-summary.md"
+[ -f "$SUMMARY" ] || { echo "[BLOCK] phase-${N}-summary 不存在"; exit 1; }
+FRONTMARKERS=$(grep -c "^---" "$SUMMARY" 2>/dev/null || echo 0)
+[ "$FRONTMARKERS" -ge 2 ] || { echo "[BLOCK] YAML frontmatter 格式不完整"; exit 1; }
+grep -q "^phase:" "$SUMMARY" || { echo "[BLOCK] 缺少 phase 字段"; exit 1; }
+grep -q "^phase_name:" "$SUMMARY" || { echo "[BLOCK] 缺少 phase_name 字段"; exit 1; }
+grep -q "^status:" "$SUMMARY" || { echo "[BLOCK] 缺少 status 字段"; exit 1; }
+grep -q "^decisions:" "$SUMMARY" || { echo "[BLOCK] 缺少 decisions 字段"; exit 1; }
+grep -q "^outputs:" "$SUMMARY" || { echo "[BLOCK] 缺少 outputs 字段"; exit 1; }
+grep -q "^next_phase_context:" "$SUMMARY" || { echo "[BLOCK] 缺少 next_phase_context"; exit 1; }
+CHARS=$(wc -c < "$SUMMARY" | tr -d ' ')
+[ "$CHARS" -le 40000 ] || { echo "[BLOCK] 摘要超出大小限制 (${CHARS}/40000 chars)"; exit 1; }
+
+# 2. sprint-state.json enforcement check (Issue #146)
+SPRINT_STATE=".sprint-state/sprint-state.json"
+[ -f "$SPRINT_STATE" ] || { echo "[BLOCK] sprint-state.json 不存在"; exit 1; }
+
+# Verify phase_history includes current phase with completed_at
+PHASE_HISTORY_CHECK=$(grep -c "\"phase\": $N" "$SPRINT_STATE" 2>/dev/null || echo 0)
+[ "$PHASE_HISTORY_CHECK" -gt 0 ] || {
+  echo "[BLOCK] sprint-state.json phase_history 缺少 phase $N 的记录"
+  echo "[ACTION] 在 dispatch 下一 Phase 前更新 sprint-state.json:"
+  echo "  - phase: $N"
+  echo "  - phase_history: 追加 {phase:N, status:completed, completed_at:<ISO8601>}"
+  echo "  - outputs: 追加当前 phase 的输出文件"
+  exit 1
+}
+
+# Verify completed_at is set (not null)
+COMPLETED_AT_VALUE=$(grep -A3 "\"phase\": $N" "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | grep -o '"[^"]*"$' | tr -d '"')
+[ "$COMPLETED_AT_VALUE" != "null" ] && [ -n "$COMPLETED_AT_VALUE" ] || {
+  echo "[BLOCK] sprint-state.json phase $N 的 completed_at 未设置 (null)"
+  echo "[ACTION] 设置 completed_at 为当前时间 (ISO 8601):"
+  echo "  date -u +%Y-%m-%dT%H:%M:%SZ"
+  exit 1
+}
+```
+
+**由 orchestrator 强制执行**，不依赖 subagent 自觉遵守。
+验证失败 → BLOCK，不可 dispatch 下一 Phase。
+
+### RESUME GATE / --resume-from 断点校验（Issue #148）
+
+当使用 `--resume-from <phase>` 时，在执行 Phase Transition Gate 之前，
+orchestrator MUST 先执行以下断点校验。任何一项失败 → BLOCK，拒绝恢复。
+
+```bash
+SPRINT_STATE=".sprint-state/sprint-state.json"
+[ -f "$SPRINT_STATE" ] || { echo "[BLOCK] sprint-state.json 不存在，无法恢复"; exit 1; }
+
+# 1. Sprint ID 一致性：确认 resume 的目标 sprint 与 sprint-state.json 匹配
+SPRINT_ID=$(grep -o '"id": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+CURRENT_SPRINT_ID=$(echo "$TASK_DESCRIPTION" | md5sum | head -8 2>/dev/null || echo "unknown")
+# 实际 sprint id 由 Phase -1 生成，此处仅验证文件存在且包含 id 字段
+[ -n "$SPRINT_ID" ] || { echo "[BLOCK] sprint-state.json 缺少 id 字段"; exit 1; }
+
+# 2. 阶段顺序校验：--resume-from 的 phase 必须是最后已完成 phase 的后继
+LAST_COMPLETED_PHASE=$(grep -o '"phase": [0-9]' "$SPRINT_STATE" | tail -1 | awk '{print $2}')
+RESUME_PHASE=$((RESUME_PHASE))  # orchestrator 将 --resume-from 参数值转为整数
+[ "$RESUME_PHASE" -gt "$LAST_COMPLETED_PHASE" ] || { 
+  echo "[BLOCK] --resume-from phase ($RESUME_PHASE) 必须在最后已完成 phase ($LAST_COMPLETED_PHASE) 之后"
+  exit 1
+}
+
+# 3. Git 状态校验：isolation branch 仍然可达
+ISOLATION_BRANCH=$(grep -o '"branch": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+ISOLATION_COMMIT=$(grep -o '"created_from_commit": "[^"]*"' "$SPRINT_STATE" | head -1 | cut -d'"' -f4)
+if [ -n "$ISOLATION_BRANCH" ]; then
+  git rev-parse --verify "$ISOLATION_BRANCH" >/dev/null 2>&1 || {
+    echo "[BLOCK] isolation branch '$ISOLATION_BRANCH' 已不存在（可能被删除或 force push 覆盖）"
+    exit 1
+  }
+fi
+if [ -n "$ISOLATION_COMMIT" ]; then
+  git cat-file -e "${ISOLATION_COMMIT}^{commit}" 2>/dev/null || {
+    echo "[WARN] isolation commit $ISOLATION_COMMIT 不可达（可能被 GC 或 rebase 清理），恢复后可能状态不一致"
+    # WARN 而非 BLOCK — 可继续但有风险
+  }
+fi
+
+# 4. 文件时效性校验：前置摘要文件的 mtime 不晚于其生成 phase 的完成时间
+RESUME_PREREQ_PHASE=$((RESUME_PHASE - 1))
+PREREQ_FILE=".sprint-state/phase-outputs/phase-${RESUME_PREREQ_PHASE}-summary.md"
+[ -f "$PREREQ_FILE" ] || { echo "[BLOCK] 前置摘要文件 ${PREREQ_FILE} 不存在"; exit 1; }
+
+# 提取前置 phase 的完成时间
+PREREQ_COMPLETED_AT=$(grep -A3 "\"phase\": $RESUME_PREREQ_PHASE" "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | cut -d'"' -f4)
+if [ -n "$PREREQ_COMPLETED_AT" ] && [ "$PREREQ_COMPLETED_AT" != "null" ]; then
+  FILE_MTIME=$(stat -c %Y "$PREREQ_FILE" 2>/dev/null || stat -f %m "$PREREQ_FILE" 2>/dev/null)
+  COMPLETED_EPOCH=$(date -d "$PREREQ_COMPLETED_AT" +%s 2>/dev/null || echo "")
+  if [ -n "$FILE_MTIME" ] && [ -n "$COMPLETED_EPOCH" ]; then
+    # 容忍 60 秒时钟偏差
+    [ "$FILE_MTIME" -le $((COMPLETED_EPOCH + 60)) ] || {
+      echo "[WARN] 前置摘要文件 ${PREREQ_FILE} 在 phase $RESUME_PREREQ_PHASE 完成后被修改（mtime: $(date -d @$FILE_MTIME '+%Y-%m-%d %H:%M:%S'), completed_at: $PREREQ_COMPLETED_AT）"
+      echo "[ACTION] 继续恢复前请确认修改是预期的。输入 'confirm' 继续，其他取消："
+      read USER_CONFIRM
+      [ "$USER_CONFIRM" = "confirm" ] || { echo "[BLOCK] 用户取消恢复"; exit 1; }
+    }
+  fi
+fi
+
+# 5. specification.yaml 时效性校验（仅 --resume-from build）
+SPEC_FILE="specification.yaml"
+if [ "$RESUME_PHASE" -ge 2 ] && [ -f "$SPEC_FILE" ]; then
+  SPEC_MTIME=$(stat -c %Y "$SPEC_FILE" 2>/dev/null || stat -f %m "$SPEC_FILE" 2>/dev/null)
+  PLAN_COMPLETED_AT=$(grep -A3 '"phase": 1' "$SPRINT_STATE" 2>/dev/null | grep "completed_at" | head -1 | cut -d'"' -f4)
+  if [ -n "$SPEC_MTIME" ] && [ -n "$PLAN_COMPLETED_AT" ] && [ "$PLAN_COMPLETED_AT" != "null" ]; then
+    PLAN_EPOCH=$(date -d "$PLAN_COMPLETED_AT" +%s 2>/dev/null || echo "")
+    if [ -n "$PLAN_EPOCH" ] && [ "$SPEC_MTIME" -gt $((PLAN_EPOCH + 60)) ]; then
+      echo "[WARN] specification.yaml 在 Plan phase 完成后被修改"
+      echo "[ACTION] 继续恢复前请确认 specification.yaml 的修改是预期的。输入 'confirm' 继续："
+      read USER_CONFIRM
+      [ "$USER_CONFIRM" = "confirm" ] || { echo "[BLOCK] 用户取消恢复"; exit 1; }
+    fi
+  fi
+fi
+
+echo "✅ RESUME GATE PASSED — 断点校验通过"
+# 继续执行 Phase Transition Gate
+```
+
+验证失败 → BLOCK，不可执行 `--resume-from`。
+orchestrator 必须展示失败原因并建议用户启动新 Sprint 或手动修复后重试。
+
+### WORKTREE ENFORCEMENT（Issue #84）
+
+Phase -1 执行完毕后，**所有后续操作（Phase 0 到 Phase 8）的文件编辑、命令执行 MUST 在 worktree 目录下执行**：
+
+- **工作目录**：所有 Bash 命令必须通过 `workdir` 参数或 `&&` 链式命令在 worktree 路径下执行
+- **文件写入**：所有 `write`、`edit` 工具的 `filePath` 必须位于 `isolation.worktree_path` 下
+- **验证步骤**：Phase 0 开始前，输出 `[WORKTREE] 后续所有操作将在 {worktree_path} 中进行`
+- **例外**：`.gitignore` 校验（Phase -1 表步 4）和 `git worktree remove`（Phase 8 清理）在仓库根目录执行
+Sprint state is persisted as JSON in `.sprint-state/sprint-state.json`:
+```json
+{
+  "id": "sprint-2026-04-26-01",
+  "task_description": "开发访谈机器人，支持多轮对话",
+  "phase": -1,
+  "status": "running|paused|completed",
+  "started_at": "2026-04-26T10:00:00Z",
+  "isolation": {
+    "worktree_path": ".worktrees/sprint/sprint-2026-04-26-01",
+    "branch": "sprint/2026-04-26-01",
+    "created_from": "main",
+    "created_from_commit": "abc123def..."
+  },
+  "auto_estimate": {
+    "change_type": "删除已存在代码|修改已存在代码|新增功能|Bug修复",
+    "metrics": {
+      "ref_count": 12,
+      "cross_module_count": 3,
+      "modules": ["auth", "user", "admin"],
+      "circular_dep": true,
+      "public_api_count": 5,
+      "test_file_count": 4
+    },
+    "estimated_level": "轻量|标准|复杂",
+    "recommended_flow": "轻量流程 (Phase 0-3, reduced-intensity Delphi)|标准流程 (Phase 0-4)|完整 Sprint Flow (Phase 0-8)",
+    "risk_warnings": ["循环依赖: user ↔ plane"],
+    "user_decision": "accepted|overridden|cancelled",
+    "override_reason": null
+  },
+  "phase_history": [
+    {
+      "phase": -1,
+      "phase_name": "ISOLATE",
+      "status": "completed",
+      "started_at": "2026-04-26T10:00:00Z",
+      "completed_at": "2026-04-26T10:03:00Z",
+      "duration_seconds": 180
+    }
+  ],
+  "outputs": {
+    "pain_document": "docs/pain-document.md",
+    "specification": "specification.yaml",
+    "mvp": "mvp-v1/",
+    "review_report": "review-report.md"
+  },
+  "metrics": {
+    "tests_passed": 15,
+    "tests_failed": 0,
+    "coverage_pct": 85
+  }
+}
+```
+
+**新增字段说明**:
+- `task_description`: Sprint 需求描述（Phase -1 启动时写入）
+- `started_at`: Sprint 启动时间戳（Phase -1 启动时写入，ISO 8601 格式）
+- `phase_history`: 阶段历史数组，每个元素记录阶段的执行信息：
+  - `phase`: 阶段编号
+  - `phase_name`: 阶段名称
+  - `status`: completed / running / failed / skipped
+  - `started_at`: 阶段开始时间（ISO 8601）
+  - `completed_at`: 阶段完成时间（null 表示未完成）
+  - `duration_seconds`: 耗时秒数（null 表示未完成）
+
+**Eval assertions check for:** `phase`, `status`, `isolation.branch`, `outputs.specification`, `metrics.coverage_pct`, `phase_history`, `task_description`.
+

package/plugins/qoder/skills/sprint-flow/references/phase-1-plan.md

@@ -105,7 +105,7 @@ Decision 2: [决策描述]
 
 ---
 
-### Step 2b: 调用 delphi-review（强制）
+### Step 2b: 调用 delphi-review（强制，orchestrator 直接执行）
 
 ```bash
 skill(name="delphi-review", user_message="[设计文档 + taste_decisions 确认结果]")
@@ -117,7 +117,7 @@ delphi-review 执行：
 - 输出: APPROVED / REQUEST_CHANGES
 
 **如果 REQUEST_CHANGES**:
-- ⚠️ 暂停等待用户修复
+- ⚠️ 暂停等待用户处理（orchestrator 直接执行，可交互确认）
 - 修复后重新评审（从 Round 2 起步）
 - 直到 APPROVED
 

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

@@ -1,198 +1,43 @@
 # Phase 2: BUILD（TDD + 并行执行 + 盲评 + 验证）
 
-## 目标
+**完整指令**: @see SKILL.md `## Phase 2: BUILD` section.
 
-TDD 执行，多 Agent 并行加速，盲评验证，Gate 1 验证通过。生成 MVP v1。
+**摘要**: TDD 执行, 多 Agent 并行加速, 盲评验证, Gate 1 验证通过。
 
----
-
-## 调用 Skills
+**关键链路**: DELPHI-GATE → parallel-dispatch/ralph-loop → TDD → freeze → blind-review → unfreeze → verification → cost monitor
 
-| 步骤 | Skill | 来源 | 说明 |
-|------|-------|------|------|
-| 0 | **`dispatching-parallel-agents`** _(新增)_ | superpowers | 检测可并行任务，并行分发独立子任务 |
-| 0 | **`executing-plans`** _(新增)_ | superpowers | 在隔离 session 中执行计划，有 review checkpoint |
-| 1 | `test-driven-development` | superpowers | RED → GREEN → REFACTOR 铁律 |
-| 1.5 | `vercel-react-native-skills` | gstack | React Native 特定测试框架引用（如适用） |
-| 2 | `freeze` | gstack | 锁定业务代码，盲评隔离 |
-| 3 | `requesting-code-review` | superpowers | 独立 agent 盲评（隔离状态） |
-| 4 | `unfreeze` | gstack | 解锁业务代码 |
-| 5 | `verification-before-completion` | superpowers | 测试 + lint 证据优先 |
-| 6 | 成本监控 | sprint-flow 编排层 | 超阈值 BLOCK + 用户决策 |
+**输出**: MVP v1
 
 ---
 
-## 执行步骤
-
-### Step 0: 并行检测与任务分发（新增 — ISSUE29）
-
-**检测可并行任务**:
-从 specification.yaml 或 Phase 1 输出中提取独立任务。并行条件:
-- 无共享状态依赖（不读写同一文件）
-- 无文件冲突风险（不同模块/组件）
-- 2+ 独立任务存在
-
-**IF 检测到可并行任务 → dispatching-parallel-agents 模式**:
-
-```
-Phase 2: 
-  ├── task: [独立A] ──┐
-  ├── task: [独立B] ──┼── dispatching-parallel-agents (并行)
-  ├── task: [独立C] ──┘
-  └── merge → freeze → review → verification
-```
-
-每个独立任务调用:
-```
-skill(name="executing-plans", user_message="[计划内容] + review checkpoint")
-```
-
-**IF 无并行机会 → 串行模式**（保持现有行为）:
-```
-Phase 2: test-driven-development → freeze → review → verification
-```
+## Gate 参考表（Phase 2 相关）
 
-### Step 1: TDD 执行（test-driven-development）
-
-```
-skill(name="test-driven-development", user_message="[需求描述]，基于 specification.yaml")
-```
-
-**TDD 铁律**:
-1. 🔴 **RED**: 先写测试（根据 specification.yaml 的 acceptance_criteria）
-2. 🟢 **GREEN**: 写最小实现代码让测试通过
-3. 🔵 **REFACTOR**: 重构代码，保持测试通过
-
-**语言特定 TDD**（通过 `--lang` 参数选择）：
-
-| 语言 | 调用的 TDD skill |
-|------|-----------------|
-| Spring Boot | `springboot-tdd` |
-| Django | `django-tdd` |
-| Go | `golang-testing` |
-
-**输出**: tests + code
-
-### Step 1.5: React Native 特定 TDD（如适用）
-
-**移动端项目特定测试策略**：
-
-对于 mobile-react-native 项目:
-- 检测 `--type mobile-react-native` 或 `package.json` 中包含 react-native 依赖
-- 使用 Jest 进行单元测试 (RN 默认)
-- 使用 Detox 进行端到端测试
-- 使用 React Native Testing Library 进行组件测试
-- TDD 流程: 先写组件测试 → 极简组件实现 → 通过测试 → 重构
-
-配置文件:
-- `jest.config.js` 用于测试环境设置
-- `.detoxrc.js` 包含 Detox 配置
-- iOS/Android 模拟器/真机测试支持
-
-**执行顺序**:
-- `npx jest` 运行单元测试
-- `npx detox build && npx detox test` 运行 E2E 测试
-- `npx jest --coverage` 检查测试覆盖率
-
-**Flutter 项目**（作为补充）:
-- 对于 mobile-flutter 项目: `flutter test --coverage` 运行单元和 widget 测试
-
-### Step 2: 盲评隔离（freeze）
-
-```
-skill(name="freeze", user_message="[业务代码文件路径]")
-```
-
-锁定所有业务代码文件，排除测试文件。
-Navigator agent 在盲评阶段将无法访问业务代码。
-
-### Step 3: 独立盲评（requesting-code-review）
-
-```
-skill(name="requesting-code-review", user_message="[需求] + 测试文件 + 测试结果")
-```
-
-**关键**: 盲评 agent 只接收需求 + 测试 + 测试结果，**不传业务代码**（freeze 锁定中）。
-
-**输出**: review findings（问题清单 + 建议）
-
-### Step 4: 解锁业务代码（unfreeze）
-
-```
-skill(name="unfreeze", user_message="[业务代码文件路径]")
-```
-
-解锁业务代码文件，允许后续步骤访问。
-
-### Step 5: 验证（verification-before-completion）
-
-```
-skill(name="verification-before-completion", user_message="验证实现完整性")
-```
-
-**验证内容**：
-- 测试全部通过
-- Lint 无错误
-- 覆盖率 ≥ 80%
-- 证据优先：必须运行命令并确认输出
-
-**失败处理**：
-- 自动修复 max 3 次
-- 每次失败后修复代码，重新运行验证
-- max 3 次失败 → ⚠️ BLOCK，暂停等待用户决定
-
-### Step 6: 成本监控（sprint-flow 编排层）
-
-sprint-flow 编排层监控本次 Phase 2 的成本：
-
-| 阈值 | 值 | 处理 |
-|------|-----|------|
-| 单任务阈值 | $0.15 | BLOCK + 提示用户决定 |
-| 日阈值 | $1.00 | BLOCK + 提示用户决定 |
-
-**零降级原则**: 成本超阈值时，必须 BLOCK 并通知用户，由用户决定是否继续。AI 不能自动跳过验证步骤。
+| Gate | 名称 | 行为 |
+|------|------|------|
+| Gate 5 | 单元测试 + 覆盖率 | 全部通过 + ≥80% 覆盖率 |
+| Gate 5a-BLOCK | 新增 .ts/.tsx 文件测试强制 | 新增 .ts/.tsx 文件无对应测试文件 → BLOCK；修改文件 → WARNING |
+| Gate M2 | Mock 密度检查 | 30% WARNING (Phase 1); 可配置 via `.mockpolicyrc` |
 
 ---
 
-## 关键行为保留（原 xp-consensus 17 状态机）
+## TDD 强制执行
 
-| 原状态 | 含义 | 新处理方案 |
-|--------|------|-----------|
-| `CIRCUIT_BREAKER_TRIGGERED` | 成本/资源超阈值 | sprint-flow 编排层监控成本，超阈值 BLOCK + 用户决策 |
-| `ROLLBACK_TO_ROUND1` | Gate 1 失败自动修复 → 回退 | verification-before-completion 失败 → 修复 max 3 次 → 仍失败 BLOCK |
-| `GATE1_FAILED`/`GATE1_COMPLETE` | 区分可修复 vs 致命失败 | verification-before-completion 内置此区分 |
-| `GATE2_RUNNING` | Security Scan 集成 | `cso` (gstack) Phase 1-6 安全审计替代 |
-| `SEALED_CODE_ISOLATION` | freeze 技术隔离 | **保留 freeze skill 调用** |
-| `MOBILE_TDD_EXECUTION` | React Native/Flutter 特定 TDD 执行 | 根据 `--type` 参数选择: mobile-react-native → RN TDD, mobile-flutter → Flutter TDD |
+### Gate 5a-BLOCK: 新增文件测试强制
 
----
+- **新增 `.ts/.tsx` 文件**必须有对应的测试文件（`*.test.ts`、`*.spec.ts`、`__tests__/` 目录），否则 **BLOCK** 提交
+- **修改已有文件**仅触发 WARNING（不阻断）
+- **Escape valve**: 非 main/master 分支可设置 `SKIP_GATE_5A_BLOCK=1` 跳过阻断（仅 WARNING）
 
-## Skill 间数据流契约
+### Gate M2: Mock 密度阈值调整
 
-| 步骤 | Skill | 输入 | 输出 | 失败回退 |
-|------|-------|------|------|----------|
-| 0a | dispatching-parallel-agents | specification.yaml + 任务分解 | 并行子任务分发 | 降级为串行 |
-| 0b | executing-plans | 子任务计划 | 实现 + review checkpoint | BLOCK |
-| 1 | test-driven-development | 需求描述 + 现有代码上下文 | 测试 + 代码 (RED→GREEN→REFACTOR) | 修复 max 3 次 → BLOCK |
-| 1.5 | vercel-react-native-skills | 项目类型 (mobile-react-native 或 mobile-flutter), package.json | RN/Flutter 测试执行结果 | RN/Flutter 测试失败 → 修复 max 3 次 → BLOCK |
-| 2 | freeze | 业务代码文件路径 | 锁定状态确认 | ❌ BLOCK |
-| 3 | requesting-code-review | 需求 + 测试 + 测试结果（**不传业务代码**） | review findings | 继续（记录 findings） |
-| 4 | unfreeze | 业务代码文件路径 | 解锁状态确认 | ❌ BLOCK |
-| 5 | verification-before-completion | 测试执行结果 | pass/fail 证据 | 修复 max 3 次 → BLOCK |
+- Mock 密度阈值从 50% 降低至 **30%**
+- **Phase 1**: WARNING 模式（仅告警，不阻断）
+- **Phase 2**: 将在基线分析后启用 BLOCK 模式
+- 可通过 `.mockpolicyrc` 配置阈值和行为
 
----
-
-## 暂停点
+### Escape Valve
 
-| 暂停点 | 触发条件 | 用户操作 |
-|--------|---------|---------|
-| 验证 max 3 失败 | verification-before-completion 失败超过 3 次 | 用户决定修复或放弃 |
-| 成本超阈值 | 单任务 >$0.15 或日 >$1.00 | 用户决定继续或暂停 |
-| RN/Flutter 测试失败 | mobile-react-native 或 mobile-flutter 项目的测试执行失败且自动修复 max 3 次后仍未通过 | 用户决定继续修复或调整方案 |
-
----
-
-## 输出
-
-- MVP v1 (`mvp-v1/` 目录)
-- 进入 Phase 3 自动执行
+```bash
+# 非 main/master 分支临时跳过 Gate 5a-BLOCK
+SKIP_GATE_5A_BLOCK=1 git commit -m "message"
+```

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

@@ -4,6 +4,8 @@
 
 多专家代码走查、测试对齐、浏览器测试。确保 MVP 符合 specification。
 
+**执行者**: orchestrator 直接执行全部步骤（非 subagent dispatch）— Issue #249。
+
 Web 前端项目额外增加：系统化 QA、视觉审计、性能基线。
 
 ---
@@ -46,7 +48,7 @@ delphi code-walkthrough 执行：
 - ≥90% 共识 + APPROVED 才通过
 
 **如果 REQUEST_CHANGES**:
-- ⚠️ 暂停等待用户修复 Critical Issues + 处理 Major Concerns
+- ⚠️ 暂停等待用户处理 Critical Issues + Major Concerns（orchestrator 直接执行，可交互）
 - 修复后回到 Round 2 重新评审
 
 **如果 APPROVED**: