@boyingliu01/xp-gate 0.19.1 → 0.19.3

package/plugins/qoder/skills/sprint-flow/SKILL.md

@@ -1,42 +1,31 @@
 ---
 name: sprint-flow
-version: 2.0.0
+version: 2.1.0
 description: >
-  One-Shot Sprint 自动流水线。单一入口，自动串联 Think → Plan → Build → 
-  Review → Ship 流程。整合 brainstorming + autoplan + delphi-review + TDD +
-  delphi-review --mode code-walkthrough + ship 等现有 Skills。关键节点暂停等待用户决策。
-  承认 Emergent Requirements 限制，设计用户验收环节。
-  
-  TRIGGER: 
-  - "开发新功能"
-  - "实现 X"
-  - "start sprint"
-  - "一键开发"
-  - "/sprint-flow"
-   触发后第一行输出: `Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE`
-  用法: /sprint-flow "[需求描述]"
-  示例: /sprint-flow "开发访谈机器人，支持多轮对话"
-  可选参数:
-  --no-isolate: 跳过自动 worktree 隔离（⚠️ 在保护分支上有污染风险）
-  --branch-name <name>: 自定义分支名（默认自动生成 sprint/YYYY-MM-DD-NN）
-  --force: 强制在当前分支继续（即使已是保护分支，⚠️ 输出警告）
-  --stop-at <phase>: 执行到指定阶段后停止 (prep/design/build/verify/ship/close). Legacy names: isolate/think/plan/review/ship/land/cleanup
-  --resume-from <phase>: 从指定阶段继续，跳过前面阶段 (prep/design/build/verify/ship/close)
-  --phase <phase>: 只执行单个阶段 (prep-only/design-only/build-only/verify-only/ship-only/close-only). Legacy: isolate-only/think-only/plan-only/build-only/review-only/ship-only/land-only/cleanup-only
-  --lang <language>: 指定项目语言 (springboot/django/golang)
-  --type <project_type>: 指定项目类型 (web-nextjs/web-react/web-vue/mobile-flutter/mobile-react-native/backend-django/backend-go/backend-springboot)
-  --spec <file>: 使用已有的 specification.yaml 文件
-  --with-performance: 启用负载/压力测试（后端项目）
-  --mode <build_mode>: 指定 Phase 3 BUILD 构建模式。默认 = ralph-loop（逐 REQ 迭代，token 节约）。parallel = 旧有并行模式（一次性 dispatch 所有需求）
-  --status: 查看当前 Sprint 进度看板（不执行任何阶段，仅读取 sprint-state.json 并渲染进度）
-  Use when asked to "开发新功能", "实现 X", "start sprint", "一键开发", or "/sprint-flow" for end-to-end feature development.
+  Orchestrates a 6-phase end-to-end feature development pipeline (PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE).
+  Integrates grill-with-docs, batch-grill-me, delphi-review (R1 requirements + R2 design), TDD, ralph-loop, code-walkthrough, and native ship/land steps.
+  Pauses at key gates for user decisions. Acknowledges emergent requirements with mandatory manual UAT in CLOSE phase.
+
+  WHAT: Automates the full development lifecycle from worktree isolation to production deployment.
+  WHEN: User explicitly requests building a feature, developing new functionality, starting a sprint, or running /sprint-flow.
+  NOT WHEN: Asking HOW to implement something (educational), implementing a single function/algorithm, environment setup,
+  deployment-only requests, feature suggestions without execution intent, or casual "do it" requests without a feature scope.
+
+  TRIGGERS: "/sprint-flow", "start sprint", "开发新功能", "实现 X (where X is a feature/module)", "一键开发", "develop new feature",
+  "implement feature X", "one-shot development", "build X (where X is a feature)".
+  NEGATIVE TRIGGERS: "实现排序算法", "实现一下", "帮我实现这个函数", "怎么实现登录功能", "start spring boot", "开发环境配置",
+  "一键部署", "新功能建议", "implement a sort function", "how to implement auth".
+  On trigger, first line MUST output: `Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE`
 maturity: beta
+auto_continue: false    # Sprint-flow pauses at user decision gates (unlike delphi-review which auto-continues rounds)
 triggers:
   - "/sprint-flow"
   - "start sprint"
   - "开发新功能"
-  - "实现 X"
   - "一键开发"
+  - "implement feature"
+  - "one-shot development"
+  - "build a feature"
 triggers_negative_examples:
   - "实现排序算法"          # algorithm implementation, not feature development
   - "实现一下"              # casual "do it", not a sprint request
@@ -48,6 +37,10 @@ triggers_negative_examples:
   - "新功能建议"            # feature suggestion/request, not execution
   - "implement a sort function"  # algorithm, not full feature
   - "how to implement auth"      # educational question
+  - "实现一个util函数"      # utility function, not feature
+  - "帮我写个脚本"          # script writing, not feature development
+  - "代码review"            # code review, not development
+  - "refactor this"         # refactoring, not new feature
 triggers_negative_test_cases:
   - input: "实现排序算法"
     expect: "NOT triggered"
@@ -75,23 +68,58 @@ triggers_negative_test_cases:
     expect: "triggered"
   - input: "一键开发 REST API"
     expect: "triggered"
+  - input: "implement user authentication feature"
+    expect: "triggered"
+  - input: "start sprint for login module"
+    expect: "triggered"
+  - input: "帮我写个脚本"
+    expect: "NOT triggered"
+  - input: "代码review"
+    expect: "NOT triggered"
+  - input: "refactor this module"
+    expect: "NOT triggered"
 workflow_steps:
-  - "Phase 1/6: PREP"
-  - "Phase 2/6: DESIGN"
-  - "Phase 3/6: BUILD"
-  - "Phase 4/6: VERIFY"
-  - "Phase 5/6: SHIP"
-  - "Phase 6/6: CLOSE"
+  - "Phase 1/6: PREP → Output: ## Phase 1/6: PREP (准备工作)"
+  - "Phase 2/6: DESIGN → Output: ## Phase 2/6: DESIGN (设计)"
+  - "Phase 3/6: BUILD → Output: ## Phase 3/6: BUILD (构建)"
+  - "Phase 4/6: VERIFY → Output: ## Phase 4/6: VERIFY (验证)"
+  - "Phase 5/6: SHIP → Output: ## Phase 5/6: SHIP (发布)"
+  - "Phase 6/6: CLOSE → Output: ## Phase 6/6: CLOSE (收尾)"
+hooks:
+  security:
+    - "tools_denied": "Destructive commands blocked via tools_denied (rm -rf, git push --force, DROP TABLE)"
+    - "Security Notes": "See Security Notes section for safety guarantees"
+  operational:
+    - "sprint-state.json": "Native sprint state persistence + --resume-from for context restore"
+tools_allowed:
+  - "Bash(git, gh, npm, node)"  # git worktree/branch/commit, gh PR/release, npm/node CLI
+  - "Read"                       # read project files, configs, docs
+  - "Write"                      # write sprint-state, specification.yaml, phase summaries
+  - "Edit"                       # edit sprint-state, CHANGELOG, VERSION
+  - "Glob"                       # find project files by pattern
+  - "Grep"                       # search file contents
+  - "Task"                       # delegate to subagents (quick, deep, unspecified-high)
+  - "Skill"                      # invoke integrated skills (grill-with-docs, batch-grill-me, delphi-review, to-issues, etc.)
+  - "TodoWrite"                  # track sprint progress
+  - "Question"                   # ask user at decision gates
+tools_denied:
+  - "rm -rf (any recursive force remove)"
+  - "git push --force"
+  - "DROP TABLE or destructive DB operations"
+  - "Write(source code)"            # NEVER write implementation code directly — delegate to subagents via Task
+  - "Edit(source code)"             # NEVER edit implementation code — sprint-flow orchestrates, subagents implement
 ---
 
+# Sprint Flow — 6-Phase Development Pipeline
+
 ## Triggers
 
 | Trigger Type | Phrases |
 |--------------|---------|
-| **中文** | "开发新功能", "实现 X", "start sprint", "一键开发", "/sprint-flow", "开发用户登录", "创建 XXX 模块" |
-| **English** | "implement feature", "build X", "start sprint", "one-shot development", "create XXX", "develop new functionality" |
+| **中文** | "开发新功能", "一键开发", "/sprint-flow", "开发用户登录", "创建 XXX 模块" |
+| **English** | "/sprint-flow", "start sprint", "implement feature", "one-shot development", "build a feature" |
 
-**Usage**: `/sprint-flow "[需求描述]"`
+**Usage**: `/sprint-flow "[feature description]"`
 
 **Examples**:
 - `/sprint-flow "开发访谈机器人，支持多轮对话"`
@@ -102,25 +130,22 @@ workflow_steps:
 - `--no-isolate`: Skip auto worktree isolation (⚠️ risk of polluting protected branches)
 - `--branch-name <name>`: Custom branch name (default: `sprint/YYYY-MM-DD-NN`)
 - `--force`: Force continue on current branch even if protected (⚠️ requires explicit confirmation)
-- `--stop-at <phase>`: Stop after specified phase (prep/design/build/verify/ship/close). For backward compat, legacy names (isolate/think/plan/review/ship/land/cleanup) are accepted and mapped.
-- `--resume-from <phase>`: Resume from specified phase, skipping earlier phases (prep/design/build/verify/ship/close)
-- `--phase <phase>`: Execute only single phase (prep-only/design-only/build-only/verify-only/ship-only/close-only). Legacy: isolate-only/think-only/plan-only/build-only/review-only/ship-only/land-only/cleanup-only
+- `--stop-at <phase>`: Stop after specified phase (prep/design/build/verify/ship/close)
+- `--resume-from <phase>`: Resume from specified phase
+- `--phase <phase>`: Execute only single phase (prep-only/design-only/build-only/verify-only/ship-only/close-only)
 - `--lang <language>`: Specify project language (springboot/django/golang)
-- `--type <project_type>`: Specify project type (web-nextjs/web-react/web-vue/mobile-flutter/mobile-react-native/backend-django/backend-go/backend-springboot)
+- `--type <project_type>`: Specify project type (web-nextjs/web-react/web-vue/backend-go/backend-django/backend-springboot)
 - `--spec <file>`: Use existing specification.yaml file
 - `--with-performance`: Enable load/stress testing (backend projects)
-- `--mode <build_mode>`: Phase 3 BUILD build mode. Default = ralph-loop (REQ-level iteration, token-efficient). parallel = legacy all-at-once mode
-
-# Sprint Flow Skill
+- `--mode <build_mode>`: Phase 3 BUILD build mode. Default = ralph-loop. parallel = legacy all-at-once mode
+- `--status`: View Sprint progress dashboard (read-only, no execution)
 
 ## Security Notes
 
-- sprint-flow **不执行任何破坏性命令**（no `rm -rf`, `git push --force`, `DROP TABLE` 等）
-- `git worktree remove` 仅删除 sprint 创建的临时 worktree 目录，不影响主仓库
-- Phase 5 SHIP 仅创建 PR（`gh pr create`），不自动 merge（除非用户显式确认）
-- Phase 5 SHIP / LAND 使用 `gh pr merge --squash`（非 force push），merge 前等待 CI 通过
-- 文档中 `+ platform deploy` 等描述仅表示可选的部署步骤映射，**不是可执行命令**
-- sprint-flow 不下载、安装或执行任何外部二进制文件
+- Sprint flow **does NOT execute destructive commands** (no `rm -rf`, `git push --force`, `DROP TABLE`, etc.)
+- `git worktree remove` only deletes temporary worktree directories created by the sprint, never affects the main repo
+- Phase 5 SHIP only creates PRs (`gh pr create`), never auto-merges without explicit user confirmation
+- Sprint flow does not download, install, or execute external binaries
 
 ## Permissions
 
@@ -129,103 +154,33 @@ workflow_steps:
 - `filesystem`: read/write (project dir + `.worktrees/` only)
 - `network`: read-only (CI status, canary health)
 
-## 核心原则
-
-| 原则 | 说明 |
-|------|------|
-| **单一入口** | 用户只需调用 `/sprint-flow`，自动串联全流程 |
-| **自动流水线** | 类似 autoplan，自动执行多个阶段 |
-| **关键节点暂停** | APPROVED 确认、DELPHI-GATE 通过、Ship 确认、⚠️ Phase 6 CLOSE 必须人工 |
-| **承认 Emergent** | 用户验收环节必须人工，无法自动化（78% 失败不可见） |
-| **复用现有 Skills** | 不重新发明，整合调用现有体系 |
-
----
-
-## Unique Value Proposition
-
-Sprint Flow is NOT just a sequential launcher of existing skills. Here's what makes it different from manually running each skill:
-
-### Why Sprint Flow vs Manual Skill Execution
-
-| Dimension | Manual Execution | Sprint Flow |
-|-----------|-----------------|-------------|
-| **Context Continuity** | Each skill starts fresh; lost design decisions between phases | Phase summaries + sprint-state.json maintain full traceability across 6 phases |
-| **Gate Enforcement** | No enforcement — easy to skip Delphi, skip TDD, skip UAT | HARD-GATE: design must be APPROVED (≥90% Delphi consensus) before coding; UAT is mandatory (no bypass) |
-| **Token Efficiency** | Linear context accumulation across phases — ~150K+ tokens | Ralph-loop default: 40-67% token savings via clean REQ-level contexts |
-| **Emergent Requirements** | Discovered late, silently ignored or merged | Phase 6 CLOSE explicitly captures emergent issues via template; triggers Sprint 2 for critical issues |
-| **Quality Ecosystem** | No integration with quality gates | Integrated with xp-gate's full quality ecosystem: Gate 5 (coverage), Gate M2 (mock density), Delphi code-walkthrough |
-| **Progress Tracking** | Ad-hoc, memory-based | `.sprint-state/` persistence with phase history, timing, and metrics — `--status` renders progress dashboard |
-
-### Key Differentiators
-
-1. **40-67% Token Savings via Ralph Loop**: Phase 3 BUILD default (`ralph-loop`) processes one REQ at a time with clean context, avoiding the linear context accumulation that costs 150K+ tokens in parallel mode.
-
-2. **HARD-GATE Discipline**: Design must pass Delphi review (≥90% consensus from exactly three successfully executed, distinct model IDs; provider, vendor, and country unrestricted) before Phase 3 BUILD can start. Any expert execution failure blocks approval. This is enforced both in SKILL.md instructions and via the Claude Code plugin's PreToolUse hook.
-
-3. **Emergent Requirements Acknowledgment**: Based on research showing 78% of failures are invisible to AI (arXiv study), Phase 6 CLOSE includes mandatory manual UAT verification — cannot be automated, skipped, or bypassed.
-
-4. **XP-Gate Quality Ecosystem Integration**: Sprint Flow is part of the broader xp-gate ecosystem. Phase 3 BUILD integrates with Gate 5 (test coverage ≥80%), Gate M2 (mock density ≤30%), and Gate MW (code-walkthrough validation). Phase 4 VERIFY runs Delphi code-walkthrough that generates `.code-walkthrough-result.json` for pre-push enforcement.
-
-5. **Full Lifecycle Coverage**: From worktree isolation (PREP) to cleanup (CLOSE), sprint-flow covers the entire development lifecycle — not just the "write code" part. PREP (Phase 1/6) prevents over-engineering by routing lightweight changes through simplified workflows.
-
----
-
-## 完整流程（默认无参数）
-
-调用 `/sprint-flow "[需求描述]"` 后，自动执行以下流程：
-
-```
-Phase 1/6: PREP → worktree隔离 + 规模评估 + 流程路由
-Phase 2/6: DESIGN → brainstorming → autoplan → delphi-review → specification.yaml
-Phase 3/6: BUILD → GITHOOKS-GATE → DELPHI-GATE → ralph-loop/TDD → freeze/盲评 → verification
-Phase 4/6: VERIFY → delphi-review --mode code-walkthrough → test-alignment → browse → learn + retro
-Phase 5/6: SHIP → finishing-a-development-branch → ship → land-and-deploy → canary
-Phase 6/6: CLOSE → USER ACCEPTANCE (⚠️ 人工) → emergent issues → cleanup
-```
-
-**v2.0 Compact Redesign** (Issue #290): Merged from 11 phases to 6. PREP = old ISOLATE + AUTO-ESTIMATE. DESIGN = old THINK + PLAN. BUILD = old BUILD (unchanged). VERIFY = old REVIEW + FEEDBACK. SHIP = old SHIP + LAND. CLOSE = old USER ACCEPTANCE + CLEANUP.
-
----
-
-## 暂停点设计（不是随时停，而是设计明确的暂停点）
-
-- **Phase 1/6 PREP**: 保护分支强制隔离 → 输出警告或自动创建 worktree → 自动恢复；AUTO-ESTIMATE 结果展示 → 用户确认 → 按路由继续
-- **Phase 2/6 DESIGN**: brainstorming 设计未 APPROVED (HARD-GATE) → 用户修改 → APPROVED 后继续；autoplan taste_decisions → 用户确认；delphi-review 未 APPROVED → 修复 → APPROVED → specification.yaml
-- **Phase 3/6 BUILD**: DELPHI-GATE 未通过 → BLOCK；验证失败 > max3 → 用户决策修复/放弃；成本超阈值 → 用户确认
-- **Phase 4/6 VERIFY**: delphi code-walkthrough REQUEST_CHANGES → 用户处理 → 重新评审；browse 发现问题 → 回退 Phase 3（不暂停）
-- **Phase 5/6 SHIP**: finishing-a-development-branch (4选项) → 确认；ship PR → 用户确认合并；land-and-deploy 完成/失败 → 用户确认
-- **Phase 6/6 CLOSE**: USER ACCEPTANCE ⚠️ 必须人工验收 → 用户确认后继续；cleanup 完成/失败 → 用户确认 → 结束流程
-
 ---
 
-## Workflow Steps
-
-| Step | Phase | Name | Key Actions | Output |
-|------|-------|------|-------------|--------|
-| 1 | **1/6** | **PREP** | Detect protected branch → Create git worktree → AUTO-ESTIMATE sizing → Classify (lightweight/standard/complex) | Worktree path + impact assessment |
-| 2 | **2/6** | **DESIGN** | brainstorming → autoplan → delphi-review (HARD-GATE ≥90% consensus) → to-issues → specification.yaml | specification.yaml + slices-manifest.json |
-| 3 | **3/6** | **BUILD** | GITHOOKS-GATE → DELPHI-GATE → ralph-loop (default) or parallel → TDD → freeze → blind review → verification | MVP code |
-| 4 | **4/6** | **VERIFY** | delphi-review --mode code-walkthrough → test-specification-alignment → browse QA → benchmark (optional) → learn + retro | Review report + feedback-log.md |
-| 5 | **5/6** | **SHIP** | finishing-a-development-branch → ship (create PR) → land-and-deploy → merge + CI + canary | PR URL + deploy status |
-| 6 | **6/6** | **CLOSE** | USER ACCEPTANCE (⚠️ mandatory manual) → Capture emergent issues → Cleanup worktree + branch → Sprint summary | Emergent issues list + cleanup report |
+## 6-Phase Pipeline
 
-**Phase Flow**:
 ```
 PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 ```
 
+| Phase | Name | Key Actions | Output |
+|-------|------|-------------|--------|
+| 1/6 | PREP | Detect protected branch → Create git worktree → AUTO-ESTIMATE sizing → Classify (lightweight/standard/complex) | Worktree path + impact assessment |
+| 2/6 | DESIGN | CONTEXT.md 预检 (#322) → grill-with-docs → R1 需求评审 → 设计文档+APPROVAL (HARD-GATE) → batch-grill-me → R2 delphi-review (3 distinct models, ≥90% consensus, max 5 rounds) → to-issues → specification.yaml | specification.yaml + slices-manifest.json + requirements-reviewed.json |
+| 3/6 | BUILD | BUILD-ENTRY-CONTRACT → GITHOOKS-GATE → DELPHI-GATE → ralph-loop (default) or parallel → TDD → blind-review (read-only subagent) → verification | MVP code |
+| 4/6 | VERIFY | delphi-review --mode code-walkthrough → test-specification-alignment (#367 HARD-GATE) → xp-gate check --all → browser (Layer 4) → learnings + xp-gate retro | Review report + feedback-log.md + test-alignment-report.json |
+| 5/6 | SHIP | VERSION-GATE → 分支完成决策 (4选项) → native ship (create PR) → native land (merge + CI + canary) | PR URL + deploy status + merge confirmation |
+| 6/6 | CLOSE | SHIP→CLOSE GATE (merge verified) → Backup sprint-state → #369 返工指标 → USER ACCEPTANCE (⚠️ mandatory manual) → Capture emergent issues → Cleanup worktree + branch | Emergent issues list + cleanup report + metrics |
+
 **Hard Gates**:
-- **Phase 2/6 → 3/6 (DESIGN → BUILD)**: Design must be APPROVED by delphi-review (≥90% consensus) + GITHOOKS-GATE (hooks installed) + DELPHI-GATE (spec APPROVED)
-- **Phase 4/6 → 5/6 (VERIFY → SHIP)**: feedback-log.md must exist (HARD-GATE)
-- **Phase 5/6 → 6/6 (SHIP → CLOSE)**: User acceptance must be completed (mandatory manual step)
+- **DESIGN → BUILD**: R1 and R2 invoke all three expert roles independently, verify successful results with three distinct requested models, then aggregate APPROVED consensus ≥90% within 5 rounds, plus GITHOOKS-GATE + DELPHI-GATE + BUILD-ENTRY-CONTRACT (manifest schema + slice↔REQ)
+- **VERIFY → SHIP**: feedback-log.md must exist + test-alignment-report.json PASS (#367 程序化 HARD-GATE)
+- **SHIP → CLOSE**: PR must be merged to main + release completed (HARD-GATE)
 
 ---
 
-## 各 Phase 调用的 Skills
-
-### ⚠️ 强制输出格式规范（Mandatory Output Format）
+## ⚠️ Required Output Format (MANDATORY for L3 Step Adherence)
 
-**执行每个 Phase 时，必须以以下固定格式输出阶段标题**，不可省略、不可合并、不可替换：
+Every phase MUST output its header as the first line of that phase's output. Format MUST be exact:
 
 ```markdown
 ## Phase 1/6: PREP (准备工作)
@@ -236,264 +191,210 @@ PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 ## Phase 6/6: CLOSE (收尾)
 ```
 
-**规则**：
-1. 每个 Phase **开始执行时必须首先输出**对应的 `## Phase X/6: NAME` 标题行（作为该 Phase 输出的第一行）
-2. **禁止省略** "Phase" 关键词（如不能只写 "PREP" 或 "## 1/6"）
-3. **禁止合并**多个 Phase 的输出（每个 Phase 必须有独立标题）
-4. **格式必须精确匹配**：`## Phase X/6:` + 大写英文名 + ` (中文名)`
-5. 跳过某个 Phase（如 `--resume-from build` 跳过了 PREP, DESIGN）时，不输出被跳过 Phase 的标题
-6. 触发 `/sprint-flow` 后，**第一行输出应包含工作流阶段概览**：
-
-```
-Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
-```
-
-### Phase 1/6: PREP (准备工作 — worktree 隔离 + 规模评估)
-
-**执行时机**: `/sprint-flow` 启动后 → Phase 2/6 DESIGN 前。**自动执行**。
-
-**对应旧模型**: Phase -1 ISOLATE + Phase -0.5 AUTO-ESTIMATE
-
-**详细指令**: 参见 `references/phase-1-prep.md` — 包含步骤表、参数处理、错误回退、sprint-state 格式、AUTO-ESTIMATE 指标计算、路由决策。
-
-**快速参考**:
-1. 检测保护分支 (main/master/develop) → 自动创建 worktree `.worktrees/sprint/sprint-YYYY-MM-DD-NN`
-2. Sprint Lock 检测（Issue #144）— stale 锁自动覆盖，非 stale 阻断
-3. 项目 setup (`npm install`/`go mod download`/`pip install`)
-4. `.gitignore` 校验 + Sprint State 记录 + 基线测试
-5. 识别需求类型 → 收集指标（引用计数、跨模块依赖、循环依赖）→ **轻量** / **标准** / **复杂**
-6. 输出评估结果 → 用户确认后按路由继续
-7. **参数**: `--no-isolate` (跳过), `--branch-name <name>`, `--force` (绕过保护分支)
+**Rules**:
+1. First line of every phase output MUST be `## Phase X/6: NAME (中文名)`
+2. NEVER omit "Phase" keyword (not "## 1/6" or "PREP" alone)
+3. NEVER merge phase output — each phase gets its own header
+4. On `/sprint-flow` trigger, first line MUST output: `Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE`
+5. Each phase completion MUST write Phase Summary to `.sprint-state/phase-outputs/phase-{N}-summary.md`
 
-### Phase 2/6: DESIGN (设计 — 需求探索 + 共识评审)
+### Phase Transition — TodoWrite Embedded (MANDATORY, resolves #366)
 
-**对应旧模型**: Phase 0 THINK + Phase 1 PLAN
+6. **Sprint initialization**: Phase 1 PREP MUST begin with `npx xp-gate sprint-init "<task_description>"` — this is the single entry point for sprint creation. NEVER manually write sprint-state.json.
 
-**执行者**: orchestrator 直接执行全部步骤（交互式 skill）。
+7. **Phase transitions are embedded in TodoWrite items**, not as separate post-actions. Each phase's TodoWrite item MUST include the phase-transition call as part of the same atomic step:
 
-**详细指令**: 参见 `references/phase-2-design.md` — 完整流程、条件分支、HARD-GATE。
-
-**快速参考**:
-- **Step 1: brainstorming** — `skill(name="brainstorming")` — 输出设计文档 + CONTEXT.md + ADR。**HARD-GATE**: 设计未批准 → 不可进入实现
-- **Step 2: autoplan** — `skill(name="autoplan")` — CEO/设计/工程自动评审 → 用户确认 taste_decisions
-- **Step 3: delphi-review** — `skill(name="delphi-review")` — 等待 APPROVED（非 APPROVED 暂停等待用户确认）
-- **Step 4: to-issues** — `skill(name="to-issues")` — 垂直切片 Issue 拆分 → slices-manifest.json
-- **Step 5: specification.yaml** — 从 APPROVED 设计文档自动提取
-- **Web 前端额外注入**: `design-shotgun`
-- **条件分支**: force level 只调整上下文深度；所有路径都执行 architecture、technical、feasibility 三个 Custom Agent，最多 5 轮
-
-### Phase 2/6→3/6: GITHOOKS-GATE（质量门禁安装检查）
+   ```
+   TodoWrite item format:
+   - "Phase N: <main task> + phase-transition N completed → N+1 in_progress --render"
+   ```
 
-**执行时机**: Phase 2/6 DESIGN 完全通过、准备进入 Phase 3/6 BUILD 之前。
+   Example TodoWrite items for a sprint:
+   ```
+   - Phase 1: PREP — estimate + sprint-init + phase-transition 1 completed --render
+   - Phase 2: DESIGN — delphi review + phase-transition 2 completed --render
+   - Phase 3: BUILD — implementation + phase-transition 3 completed --render
+   ```
 
-**必须执行**: 运行 `githooks/verify.sh` 检查当前项目的 hooks 是否安装。
+   **Rationale**: TodoWrite items are the LLM's most consistently executed operations. Embedding phase-transition elevates it from "post-action meta-info" (priority 4, ignored) to "main task step" (priority 2, executed).
 
-**检查结果处理**:
-- ✅ 全部存在 → 进入 Phase 3/6 BUILD 入口（仍必须先执行 DELPHI-GATE）
-- ❌ 部分/全部缺失 → 运行 `githooks/install.sh` 安装（包括 `.git/hooks/pre-commit`、`.git/hooks/pre-push`、`githooks/adapter-common.sh`、`githooks/adapters/`）
-  - 如果 githooks/ 目录不存在于项目根目录（即当前项目不是 xp-gate） → 从 xp-gate 仓库拉取 `githooks/` 目录结构
-  - 安装完成后再次 `verify.sh` 确认
+8. **NEVER** manually write to `sprint-state.json` or manually render the dashboard. ALWAYS use:
+   ```
+   npx xp-gate phase-transition <phase> <status> --render [--outputs '<json>']
+   ```
+   - `<phase>`: 1-6
+   - `<status>`: `in_progress` | `completed` | `skipped` | `failed` | `paused`
+   - `--render`: Auto-renders ASCII progress dashboard after state update
+   - `--outputs '<json>'`: Optional JSON of phase outputs to record
 
-**核心原则**: 没有质量门禁的代码不可进入 BUILD 阶段。**GITHOOKS-GATE 失败 → 不可编码。**
+   This is a **HARD GATE** — the CLI is the single source of truth for state transitions and dashboard rendering.
 
-### Phase 3/6: BUILD (构建 — ralph-loop 默认 + TDD + 盲评 + 验证)
+### Phase Output Status Schema (MANDATORY per phase)
 
-**对应旧模型**: Phase 2 BUILD（功能不变）
+Each phase MUST close with structured status:
 
-**详细指令**: 参见 `references/phase-3-build.md`。
+```
+status: completed | blocked | user_decision_required
+outputs: [list of files produced]
+decisions: [list of decisions made]
+next_phase_context: [key info for next phase]
+```
 
-**快速参考**:
-1. **DELPHI-GATE**: 验证 `.sprint-state/delphi-reviewed.json` 存在且 `verdict = "APPROVED"` → 否则 BLOCK
-2. **输入**: `slices-manifest.json`（Phase 2/6 生成），按 `execution_order` 逐个执行
-3. **模式**: 默认 `ralph-loop`（逐 REQ 迭代，token 节约 40-67%），可选 `--mode parallel`
-4. **Skill 步骤**: hooks-install → dispatching-parallel-agents → TDD (RED/GREEN/REFACTOR) → freeze → blind-review → unfreeze → verification-before-completion → 成本监控
-5. **Mock Minimization**: integration-first, mock 仅限 external services, 密度 > 30% 需 `@mock-justified`
+---
 
-### Phase 4/6: VERIFY (验证 — 代码走查 + QA + 反馈获取)
+## Phase 1/6: PREP (准备工作)
 
-**对应旧模型**: Phase 3 REVIEW + Phase 4 FEEDBACK
+**触发条件**：用户输入匹配 Triggers 表中任一短语，或显式调用 `/sprint-flow`。
 
-**详细指令**: 参见 `references/phase-4-verify.md`。
+**输入**：
+| 输入 | 来源 | 必需 |
+|------|------|------|
+| 功能描述 | 用户命令参数 | 是 |
+| 当前分支 | `git branch --show-current` | 自动检测 |
+| 项目语言 | `--lang` 参数或自动检测 | 否 |
+
+**步骤**：
+1. 输出首行：`Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE`
+2. 检测当前分支是否为保护分支（main/master/develop）
+3. 创建 git worktree 隔离（除非 `--no-isolate`）：
+   ```bash
+   git worktree add .worktrees/sprint-$(date +%Y%m%d-%H%M%S) -b sprint/YYYY-MM-DD-NN
+   ```
+4. AUTO-ESTIMATE 规模评估（分析功能描述复杂度）
+5. 分类：lightweight / standard / complex
+6. 执行 `npx xp-gate sprint-init "<task_description>"` 初始化状态
+7. 执行 `npx xp-gate phase-transition 1 completed --render`
 
-**快速参考**:
-- **Orchestrator 直接执行**: delphi-review code-walkthrough 需要用户确认 verdict（Issue #249），**必须由 orchestrator 直接调用** `skill(name="delphi-review")`
-- **执行顺序**: `delphi-review --mode code-walkthrough` → 等待 APPROVED → `test-specification-alignment` → `browse` (gstack) → 可选 `qa`/`design-review`/`benchmark` (gstack)
-- **Feedback 子阶段**: `learn` (Sprint 级复盘) + `retro` (工程回顾) + 可选 `systematic-debugging` (根因调试)
-- **Subagent**: `task(category="quick", load_skills=["learn", "retro", "systematic-debugging"])`
-- 输出: 评审报告 + feedback-log.md
-- **HARD-GATE**: feedback-log.md must exist before Phase 5/6
+**输出**：
+| 输出物 | 路径 | 格式 |
+|--------|------|------|
+| Worktree 路径 | `.worktrees/sprint-*` | 目录 |
+| Sprint 状态 | `.sprint-state/sprint-state.json` | JSON |
+| Phase Summary | `.sprint-state/phase-outputs/phase-1-summary.md` | Markdown |
 
-### 负载/压力测试（可选）
+**详细参考**：`@references/phase-1-prep.md`
 
-- **适用项目**：主要用于后端服务的压力测试 (k6/Locust/Gatling)，Web 前端已有 `benchmark` 技能覆盖 Core Web Vitals、加载时间和资源大小等性能指标
-- **Phase 4/6 技能注入**：可根据项目类型自动选择合适的负载测试工具 (`k6` for Go-based services, `locust` for Python services, `gatling` for JVM-based services)
-- **集成方式**：可作为 Phase 4/6 的可选扩展，在 code-walkthrough 之后执行，与基准测试形成完整性能验证链条
-- **配置文件**：通过 `.sprint-load-test.yaml` 进行配置（待实现），包含并发用户数、持续时间、SLA 指标等参数
-- **触发条件**：后端项目可通过 `--type backend-*` 自动启用，或通过 `--with-performance` 标志手动启用
-- **Web 项目补充说明**：对于 Web 前端项目，现有的 `benchmark` 技能已处理页面加载性能、Core Web Vitals 等前端性能指标；负载/压力测试主要针对服务器端承载能力
+---
 
-### Phase 5/6: SHIP (发布 — 发布准备 + 合并部署)
+## 门禁条件表 (Gate Conditions)
 
-**对应旧模型**: Phase 5 SHIP + Phase 6 LAND
+| 门禁 | 位置 | 条件 | 失败处理 |
+|------|------|------|----------|
+| BUILD-ENTRY-CONTRACT | Phase 2→3 | slices-manifest.json schema 合法 + slice↔REQ 一致 | BLOCK，返回 Phase 2 修复 |
+| GITHOOKS-GATE | Phase 2→3 | hooks 已安装且可执行 | 自动修复 (`xp-gate doctor --fix`)，失败则 BLOCK |
+| DELPHI-GATE | Phase 2→3 | R2 delphi-review APPROVED (≥90%) | 重新设计或用户覆盖（记录原因） |
+| VERSION-GATE | Phase 4→5 | VERSION 文件与 package.json 一致 | 执行 `node scripts/sync-version.cjs` |
+| #367 EVIDENCE-GATE | Phase 4→5 | test-alignment-report.json PASS + head_commit + spec_hash | BLOCK（--skip-evidence 需 --reason，≤2 次/sprint） |
+| SHIP→CLOSE GATE | Phase 5→6 | PR 已合并 + release 完成 | BLOCK，等待合并确认 |
+| feedback-log GATE | Phase 4→5 | feedback-log.md 存在 | BLOCK，必须完成 VERIFY |
 
-**详细指令**: 参见 `references/phase-5-ship.md` — GITHOOKS-GATE / VERSION-GATE / VERSION CHANGESET (Issue #142) / changeset schema。
+---
 
-**快速参考**:
-- **Orchestrator 直接执行**: `finishing-a-development-branch` 和 `ship` 均为交互式 skill（4 选项菜单 + PR 确认），**必须由 orchestrator 直接调用** `skill(name="finishing-a-development-branch")` 和 `skill(name="ship")`
-- 输入: phase-4-summary.md + feedback-log.md → 输出: PR URL
-- **HARD-GATE**: Phase 4/6 未完成 → BLOCK。验证 `feedback-log.md` 存在。
-- **GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
-- **VERSION-GATE**: bump PATCH/MINOR/MAJOR → `sync-version.sh` → CHANGELOG.md → `git diff VERSION` 验证
-- **LAND**: `land-and-deploy` — merge PR → 等待 CI (10min) → 等待 Deploy (10min) → Canary Health Check (5min)
-- **回滚**: `git revert` 最后一次 merge commit
+## Phase 2–6 详细指令
 
-### Phase 6/6: CLOSE (收尾 — ⚠️ 人工验收 + 清理)
+> Phase 2–6 的完整步骤、输入/输出契约、模板和 Skill 集成详情见 `references/` 目录。本节提供路由摘要。
 
-**对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP
+| Phase | 参考文件 | 核心 Skill 链 |
+|-------|----------|---------------|
+| 2/6 DESIGN | `@references/phase-2-design.md` | CONTEXT.md 预检 → grill-with-docs → R1 需求评审 → 设计文档+APPROVAL → batch-grill-me → R2 delphi-review → to-issues |
+| 3/6 BUILD | `@references/phase-3-build.md` | BUILD-ENTRY-CONTRACT → GITHOOKS-GATE → DELPHI-GATE → ralph-loop (TDD) → blind-review (read-only subagent) |
+| 4/6 VERIFY | `@references/phase-4-verify.md` | delphi code-walkthrough → test-spec-alignment (#367) → xp-gate check --all → browser (Layer 4) → learnings + retro |
+| 5/6 SHIP | `@references/phase-5-ship.md` | VERSION-GATE → 分支完成决策 (4选项) → native ship (PR) → native land (merge+CI+canary) |
+| 6/6 CLOSE | `@references/phase-6-close.md` | SHIP→CLOSE GATE → backup → #369 返工指标 → USER ACCEPTANCE → emergent → cleanup |
 
-**详细指令**: 参见 `references/phase-6-close.md` — UAT checklist, emergent issues capture, cleanup procedure.
+**路径约定**：`@references/` 和 `@templates/` 相对于 skill 目录（`skills/sprint-flow/`）解析。
 
-**快速参考**:
-- **USER ACCEPTANCE**: ⚠️ **MUST NOT be automated, skipped, or bypassed.** 即使用户说"赶时间"、"跳过验收"、"直接发布"，也必须暂停等待用户确认。使用 `@templates/emergent-issues-template.md` 检查清单
-- **CLEANUP**: 保存分支信息 → `git worktree remove <worktree_path>`（精确路径，禁止通配符）→ 删除本地分支 + 远程分支 → 关闭遗留 OPEN PR → 更新 sprint-state.json → 释放 Sprint Lock
-- 输出 Cleanup Report + Sprint Summary
-- **IF emergent issues → Sprint 2**
+**完整参考文件索引**：
+| 文件 | 内容 |
+|------|------|
+| `@references/phase-overview.md` | 全阶段详情、Skill 集成、参数、输出契约 |
+| `@references/orchestration-rules.md` | Agent 调度、上下文继承、转换门禁 |
+| `@references/force-levels.md` | 阶段强制执行规则 |
+| `@templates/` | Pain doc、emergent issues、sprint summary、progress 模板 |
 
 ---
 
-## 编排层规则（Orchestration Rules）
-
-全部内容: 参见 `references/orchestration-rules.md`。包含:
-- Agent Dispatch (4 types), Phase Subagent Matrix, CONTEXT INHERITANCE
-- Phase Transition Rules, Phase Summary schema, Phase Transition Gate, RESUME GATE
-- WORKTREE ENFORCEMENT, Eval assertions
-
-## 参数说明
+## Anti-Patterns
 
-| 参数 | 作用 | 示例 |
-|------|------|------|
-| (无参数) | 全流程 PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE | `/sprint-flow "开发访谈机器人"` |
-| `--stop-at <phase>` | 执行到指定 Phase 后停止 | `--stop-at design` |
-| `--resume-from <phase>` | 从指定 Phase 恢复（需先执行 RESUME GATE） | `--resume-from build --spec specification.yaml` |
-| `--phase <name>` | 只执行单个 Phase | `--phase build-only` |
-| `--status` | 查看 Sprint 进度（只读，不执行 Phase） | `--status` |
-| `--lang <lang>` | 指定项目语言 | `--lang springboot` / `django` / `golang` |
-| `--type <type>` | 指定项目类型 | `--type web-nextjs` / `backend-django` |
-| `--spec <file>` | 使用已有的 specification.yaml | `--spec path/to/spec.yaml` |
-| `--no-isolate` | 跳过 git worktree 隔离 | `--no-isolate` |
-| `--branch-name <name>` | 自定义分支名 | `--branch-name feat/my-feature` |
-| `--force` | 强制在当前分支继续 | `--force` |
-| `--with-performance` | 启用负载/压力测试 | `--with-performance` |
-| `--mode <mode>` | 构建模式（ralph-loop / parallel） | `--mode ralph-loop` |
-
-**Backward Compatible Parameter Mapping** (`--stop-at` / `--resume-from` / `--phase`):
-
-| Legacy Value | Maps To |
-|-------------|---------|
-| `isolate`, `isolate-only` | `prep`, `prep-only` |
-| `think`, `think-only` | `design`, `design-only` |
-| `plan`, `plan-only` | `design`, `design-only` |
-| `build`, `build-only` | `build`, `build-only` |
-| `review`, `review-only` | `verify`, `verify-only` |
-| `ship`, `ship-only` | `ship`, `ship-only` |
-| `land`, `land-only` | `ship`, `ship-only` |
-| `cleanup`, `cleanup-only` | `close`, `close-only` |
-
-**`--status` 行为规则**:
-- 执行 `node scripts/render-sprint-progress.cjs`，读取 `.sprint-state/sprint-state.json` 并渲染 ASCII 进度看板
-- 如果 `sprint-state.json` 不存在 → `[INFO] 未找到活跃的 Sprint`
-- 如果 `status == "completed"` → 输出完整看板 + `[INFO] Sprint 已完成。`
-- `--status` 可与其他参数组合：`--status --resume-from build` → 先展示状态，再提示 "将从 Phase 3/6 BUILD 继续"
-
-**`--resume-from` 限制**：校验为**尽力而为**（git commit 可被 GC 回收、文件 mtime 可被 `git checkout` 修改）。校验失败时输出完整诊断日志，建议启动新 Sprint。
-
-**项目类型自动检测**（按顺序检查）：
-
-| 检测条件 | 类型 |
-|---------|------|
-| `package.json` + `next.config.js` | `web-nextjs` |
-| `package.json` + `vite.config.ts` + react 依赖 | `web-react` |
-| `package.json` + vue 依赖 | `web-vue` |
-| `pubspec.yaml` + `flutter:` | `mobile-flutter` |
-| `package.json` + react-native 依赖 or `ios/` + `android/` | `mobile-react-native` |
-| `go.mod` | `backend-go` (可选 k6) |
-| `pom.xml` | `backend-springboot` (可选 gatling) |
-| `manage.py` 或 `pyproject.toml` (django) | `backend-django` (可选 locust) |
-| 无匹配 | `backend-cli` |
-
-**项目类型 → Skill 注入映射**:
-
-| Phase | Backend (default) | Web Frontend | Mobile | Load Test |
-|-------|------------------|-------------|--------|-----------|
-| 2/6 DESIGN | `brainstorming` + `autoplan` + `delphi-review` | + `design-shotgun` | (同 web) | (通用) |
-| 3/6 BUILD | TDD + blind-review | (同 backend) | + `vercel-react-native-skills` / `flutter-review` | (同) |
-| 4/6 VERIFY | `delphi-review --mode code-walkthrough` + `test-specification-alignment` + k6/locust/gatling | + `qa` + `design-review` + `benchmark` | Flutter: `flutter-test` / RN: `detox E2E` | k6/locust/gatling |
-| 4/6 VERIFY (Feedback) | `learn` + `retro` | (同) | (同) | (同) |
-| 5/6 SHIP | `finishing-a-development-branch` + `ship` + `land-and-deploy` | (同) | + platform deploy | (同) |
-| 6/6 CLOSE | — 人工验收 → cleanup | (同) | (同) | (同) |
-| Browse | `localhost:3000` | 部署 URL + 表单/交互 | Flutter Web / RN Web | (专用) |
-
-**Mobile 工具链**: Flutter — `flutter analyze/test/build/pub publish`; RN — `metro/detox/jest/react-native run-ios/android`
+| ❌ Error | ✅ Correct |
+|----------|-----------|
+| Route Q&A, explanation, or code-search requests to sprint-flow | Only trigger for explicit feature development/implementation requests |
+| Skip Phase 1/6 PREP isolation, edit directly on main/master/develop | Default: create worktree; only bypass with `--no-isolate` or `--force` + user confirmation |
+| Skip AUTO-ESTIMATE and apply full heavy pipeline blindly | Evaluate lightweight/standard/complex first, follow recommended or user-confirmed flow |
+| Skip Delphi review in DESIGN, go straight to BUILD | All requirement levels (lightweight/standard/complex) must pass R1 需求评审 + R2 delphi-review; APPROVED before coding |
+| Skip TDD, implement code directly | Phase 3/6 BUILD must follow RED → GREEN → REFACTOR; tests and implementation delivered together |
+| Skip user acceptance, go straight to Ship | Phase 6/6 CLOSE USER ACCEPTANCE must be manual; never automate, skip, or fake |
+| Enter CLOSE without SHIP completing merge to main | Phase 5/6 SHIP must complete merge to main + release before entering Phase 6/6 CLOSE; otherwise worktree cleanup leaves residue + UAT reviews unmerged code |
+| Clean up CLOSE without backing up sprint-state first | `.sprint-state/` is inside worktree; it's lost on worktree removal. CLOSE step 1 MUST back up to repo-tracked path first |
+| Keep adding random changes after verification failures | Max 3 fix cycles; if still failing, BLOCK and request user decision |
+| Enter next phase without generating Phase Summary | Every phase MUST write `.sprint-state/phase-outputs/phase-{N}-summary.md` and pass transition gate |
+| Complete implementation change without running verification | After every file edit/refactor/feature, MUST run `npm test` + `npm run lint` + `npx tsc --noEmit` and record the structured verification event (see `phase-3-build.md` §In-Session Verification) |
 
 ---
 
-## 状态管理
+## 状态机 (State Machine)
+
+```mermaid
+stateDiagram-v2
+    [*] --> PREP : trigger matched
+    PREP --> DESIGN : worktree ready
+    DESIGN --> BUILD : APPROVED ≥90%
+    DESIGN --> DESIGN : REQUEST_CHANGES (max 5 Delphi rounds)
+    BUILD --> VERIFY : tests pass
+    BUILD --> BUILD : fix cycle (max 3)
+    VERIFY --> SHIP : feedback-log exists
+    VERIFY --> BUILD : critical issues found
+    SHIP --> CLOSE : PR merged
+    SHIP --> SHIP : CI failed (retry)
+    CLOSE --> [*] : UAT confirmed
+    BUILD --> BLOCKED : 3 fix cycles exhausted
+    DESIGN --> BLOCKED : 5 Delphi rounds exhausted
+    BLOCKED --> [*] : user decision
+```
 
-**Sprint State**: 存储于 `<project-root>/.sprint-state/` — `sprint-state.yaml`/`.json` + `phase-outputs/` (pain-document.md / specification.yaml / mvp-v1 / review-report.md / emergent-issues.md / feedback-log.md / sprint-summary.md)
+---
 
-**Sprint 2 自动触发**: Phase 6/6 CLOSE 完成时 — `emergent_issues_count == 0` → 结束; `> 0` → Critical 自动启动 Sprint 2, Major/Minor 询问用户
+## 决策记录模板 (Decision Record)
 
----
+每个用户决策点必须记录到 `.sprint-state/decisions.md`：
 
-### ⭐ Phase State Persistence（阶段状态持久化 — MANDATORY）
+```markdown
+## Decision DR-{NNN}
+- **Phase**: {phase_number}/6 {PHASE_NAME}
+- **Question**: {what was asked}
+- **Options**: {options presented}
+- **Choice**: {user's selection}
+- **Rationale**: {why this choice}
+- **Timestamp**: {ISO 8601}
+```
 
-**编排器必须在每个 Phase 完成后更新 `.sprint-state/sprint-state.json`**：
+**强制决策点**：
+| 决策点 | 阶段 | 触发条件 |
+|--------|------|----------|
+| 规模确认 | PREP | AUTO-ESTIMATE 结果与用户预期不符 |
+| 设计审批 | DESIGN | delphi-review 返回 REQUEST_CHANGES |
+| 修复策略 | BUILD | 修复循环达到 3 次上限 |
+| 发布确认 | SHIP | PR 创建后等待用户确认合并 |
+| UAT 结果 | CLOSE | 用户手动验收（必须手动，禁止自动化） |
 
-1. **Phase 完成后立即更新**（每个 Phase 结束前）：
-   - `phase`: 更新为当前 Phase 编号（如 `1`, `2`, `3`...）
-   - `status`: 更新为 `"completed"`（已完成 Phase）
-   - `phase_history`: 追加新条目
+---
 
-2. **`phase_history` 数组条目 schema**：
-   ```json
-   {
-     "phase": 1,
-     "phase_name": "PREP",
-     "status": "completed",
-     "timestamp": "2026-07-08T10:30:00Z"
-   }
-   ```
+## 失败处理 (Failure Handling)
 
-3. **检查点**：
-   - `--status` 参数读取 `sprint-state.json` 并渲染进度看板
-   - TUI panel 显示当前 Phase 和历史
-   - `--resume-from` 校验 `phase_history` 中的最后完成 Phase
-
-4. **完整 sprint-state.json 示例**：
-   ```json
-   {
-     "id": "sprint-2026-07-08-01",
-     "phase": 3,
-     "status": "in_progress",
-     "phase_history": [
-       {"phase": 1, "phase_name": "PREP", "status": "completed", "timestamp": "2026-07-08T10:00:00Z"},
-       {"phase": 2, "phase_name": "DESIGN", "status": "completed", "timestamp": "2026-07-08T10:30:00Z"}
-     ],
-     "isolation": {
-       "worktree_path": "/home/boyingliu01/projects/xp-gate/.worktrees/sprint/sprint-2026-07-08-01",
-       "branch": "sprint/2026-07-08-01"
-     },
-     "outputs": {
-       "pain_document": "phase-outputs/phase-2-summary.md",
-       "specification": "phase-outputs/specification.yaml"
-     },
-     "metrics": {
-       "coverage_pct": 85.5
-     }
-   }
-   ```
+| 失败场景 | 处理策略 | 升级条件 |
+|----------|----------|----------|
+| Worktree 创建失败 | 重试 1 次，失败则提示用户手动处理 | 磁盘空间不足或权限问题 |
+| delphi-review 连续 REQUEST_CHANGES | 最多 3 轮重设计，超过则 BLOCK | 3 轮后仍未 APPROVED |
+| BUILD 修复循环超限 | 最多 3 次 fix cycle，超过则 BLOCK + 用户决策 | 测试持续失败 |
+| CI 失败 | 分析失败原因，尝试 1 次自动修复 | 非 flaky 失败 |
+| PR 合并冲突 | 提示用户手动解决 | 始终（禁止自动 force） |
+| 工具缺失 | SKIP（不 BLOCK），记录到 phase summary | 始终不阻断 |
 
-**Backward compat**: Old sprint-state.json files using negative/legacy phase numbers (`-1`, `-0.5`, `0`..`8`) remain readable. Dashboard renders them as-is. New sprints use phase numbers 1-6.
+**BLOCK 状态处理**：
+1. 写入 `.sprint-state/sprint-state.json` 状态为 `blocked`
+2. 输出阻塞原因 + 已完成工作 + 建议操作
+3. 等待用户决策（继续/放弃/降级）
+4. 记录决策到 `decisions.md`
 
 ---
 
@@ -507,104 +408,4 @@ Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
 
 ## 底层 Skills 保持独立
 
-所有被调用的 Skills 独立可用：`delphi-review` (单独评审), `test-driven-development` (TDD)，sprint-flow 仅自动串联
-
----
-
-## Anti-Patterns
-
-| 错误 | 正确 |
-|------|------|
-| 把普通问答、解释、代码检索请求路由到 sprint-flow | 仅在用户明确要求开发/实现/一键开发完整需求时触发 sprint-flow |
-| 跳过 Phase 1/6 PREP 隔离，直接在 main/master/develop 上改代码 | 默认创建 worktree；除非用户显式使用 `--no-isolate` 或 `--force` 并确认风险 |
-| 未完成 PREP AUTO-ESTIMATE 就套用完整重流程 | 先评估轻量/标准/复杂，再按推荐流程或用户确认后的流程执行 |
-| DESIGN 阶段跳过 Delphi 评审直接 BUILD | 所有需求级别（轻量/标准/复杂）必须经过 autoplan + delphi-review；未 APPROVED 禁止编码 |
-| 跳过 TDD 直接实现代码 | Phase 3/6 BUILD 必须遵循 RED → GREEN → REFACTOR，测试与实现一起交付 |
-| 跳过用户验收直接 Ship | Phase 6/6 CLOSE USER ACCEPTANCE 必须人工完成；不得自动化、跳过或伪造 |
-| 验证失败后继续追加随机修改 | 最多 3 次修复循环；仍失败则 BLOCK 并请求用户决策 |
-| 未生成 Phase Summary 就进入下一阶段 | 每个 Phase 必须写入 `.sprint-state/phase-outputs/phase-{N}-summary.md` 并通过 transition gate |
-
-## Output Format
-
-See [Output Contract](#output-contract) below for the canonical machine-readable output schema.
-
-### Eval Assertions
-- `phase`, `phase_name`, `status`, `outputs`, `decisions`, `next_phase_context`
-- `id`, `isolation.worktree_path`, `isolation.branch`, `metrics.coverage_pct`
-
-## Output Contract
-
-**Phase Summary** (每个 Phase 必须输出 YAML frontmatter): `phase/N`, `phase_name`, `status`, `outputs[]`, `decisions[]`, `next_phase_context` + markdown body (≤50 lines)
-
-**Sprint State JSON**: `{id, phase, status, phase_history[], isolation {worktree_path, branch}, outputs, metrics}` — 存储于 `.sprint-state/sprint-state.json`
-
-**Final User-Facing Output**: Phase/status, file paths, validation results, next user decision, PR URL or cleanup report
-
-## References
-
-详细指令文件位于 `@references/`:
-
-| File | Phase | Phase Name | Maps From (Old) |
-|------|-------|------------|-----------------|
-| `@references/phase-1-prep.md` | 1/6 | PREP | Phase -1 ISOLATE + Phase -0.5 AUTO-ESTIMATE |
-| `@references/phase-2-design.md` | 2/6 | DESIGN | Phase 0 THINK + Phase 1 PLAN |
-| `@references/phase-3-build.md` | 3/6 | BUILD | Phase 2 BUILD |
-| `@references/phase-4-verify.md` | 4/6 | VERIFY | Phase 3 REVIEW + Phase 4 FEEDBACK |
-| `@references/phase-5-ship.md` | 5/6 | SHIP | Phase 5 SHIP + Phase 6 LAND |
-| `@references/phase-6-close.md` | 6/6 | CLOSE | Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP |
-
-Additional reference files:
-- `@references/force-levels.md` — Phase forcing rules
-- `@references/orchestration-rules.md` — Orchestration layer rules
-- `@references/components/` — Reusable phase building blocks
-
----
-
-## Templates
-
-模板文件位于 `@templates/`:
-- `@templates/pain-document-template.md` — Pain Document 模板 (Phase 2/6 DESIGN)
-- `@templates/emergent-issues-template.md` — Emergent Issues 检查清单 (Phase 6/6 CLOSE)
-- `@templates/sprint-summary-template.md` — Sprint Summary 模板 (Phase 6/6 CLOSE)
-- `@templates/sprint-progress-template.md` — Sprint 进度看板（每个 Phase 完成后 + `--status` 查询时渲染）
-- `@templates/auto-estimate-output-template.md` — AUTO-ESTIMATE 输出格式 (Phase 1/6 PREP)
-
----
-
-## 研究证据
-
-| 证据 | 来源 | 应用 |
-|------|------|------|
-| One-shot = 单次迭代执行 | Boris Cherny interview | Phase 3/6 BUILD 设计 |
-| 80% session 从 Plan Mode 开始 | Boris skill | Phase 2/6 DESIGN 设计 |
-| Verification improves 2-3x | Boris #1 tip | Phase 4/6 VERIFY 设计 |
-| Emergent requirements 无法消除 | Mike Cohn, Rafael Santos | Phase 6/6 CLOSE 人工设计 |
-| 78% failures invisible | arXiv research | Phase 6/6 必要性证明 |
-| Think → Plan → Build → Ship | gstack ETHOS | 整体流程设计 |
-
----
-
-## Phase Flow Consistency
-
-This section documents the canonical 6-phase order to ensure all future edits keep the phase sequence synchronized across all locations in this document and its reference files.
-
-**Canonical Phase Order** (Phase 1/6..6/6):
-
-| Phase # | Name | Phase # | Name |
-|---------|------|---------|------|
-| 1/6 | PREP | 4/6 | VERIFY |
-| 2/6 | DESIGN | 5/6 | SHIP |
-| 3/6 | BUILD | 6/6 | CLOSE |
-
-**Locations that MUST keep this order synchronized**:
-1. **Frontmatter `workflow_steps`** — Phase list
-2. **Frontmatter `description` trigger text** — Flow string
-3. **Body "完整流程" section** — Phase descriptions in order
-4. **Body "Phase Flow" diagram** — ASCII flow diagram
-5. **Body "强制输出格式规范" section** — Output format
-6. **Body "Workflow Steps" table** — Step/Phase table
-7. **Body "References" section** — Reference file list
-8. **`references/orchestration-rules.md` Phase Subagent Dispatch Matrix** — Phase/Name order
-9. **`references/force-levels.md`** — Phase references
-
-**⚠️ Migration from old 11-phase model (v2.0)**: The 6-phase model was introduced in Issue #290 to reduce cognitive load. Old sprint-state.json files with negative/legacy phase numbers remain backward-compatible.
+所有被调用的 Skills 独立可用：`delphi-review` (单独评审), `test-driven-development` (TDD), `grill-with-docs` (需求访谈), `batch-grill-me` (批量决策), `to-issues` (切片拆分)，sprint-flow 仅自动串联