@boyingliu01/xp-gate 0.15.4 → 0.18.0

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

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

package/skills/domain-modeling/SKILL.md

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

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

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

package/skills/grilling/SKILL.md

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

package/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-07-23
-**Commit:** 884f68c
+**Generated:** 2026-07-25
+**Commit:** 3150b22
 **Branch:** main
-**Version:** 0.15.4.0
+**Version:** 0.18.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.

package/skills/sprint-flow/SKILL.md

@@ -3,7 +3,7 @@ name: sprint-flow
 version: 2.1.0
 description: >
   Orchestrates a 6-phase end-to-end feature development pipeline (PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE).
-  Integrates brainstorming, autoplan, delphi-review, TDD, ralph-loop, code-walkthrough, ship, and other skills.
+  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.
@@ -87,12 +87,10 @@ workflow_steps:
   - "Phase 6/6: CLOSE → Output: ## Phase 6/6: CLOSE (收尾)"
 hooks:
   security:
-    - "/careful": "Safety guardrails for destructive commands — activate before any rm, force-push, or git reset"
-    - "/freeze": "Restrict edits to sprint worktree directory — prevent accidental changes outside scope"
-    - "/guard": "Full safety mode combining careful + freeze for maximum protection"
+    - "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:
-    - "/context-save": "Save sprint context before pause or handoff"
-    - "/context-restore": "Restore sprint context on resume"
+    - "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
@@ -101,7 +99,7 @@ tools_allowed:
   - "Glob"                       # find project files by pattern
   - "Grep"                       # search file contents
   - "Task"                       # delegate to subagents (quick, deep, unspecified-high)
-  - "Skill"                      # invoke integrated skills (brainstorming, autoplan, delphi-review, etc.)
+  - "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:
@@ -167,15 +165,15 @@ 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) → brainstorming (如需要) → autoplan → delphi-review (HARD-GATE ≥90% consensus) → to-issues → specification.yaml | specification.yaml + slices-manifest.json |
-| 3/6 | BUILD | GITHOOKS-GATE → DELPHI-GATE → ralph-loop (default) or parallel → TDD → freeze → blind review → verification | MVP code |
-| 4/6 | VERIFY | delphi-review --mode code-walkthrough → test-specification-alignment → browse QA → learn + retro | Review report + feedback-log.md |
-| 5/6 | SHIP | VERSION-GATE → finishing-a-development-branch → ship (create PR) → land-and-deploy → merge to main + CI + canary | PR URL + deploy status + merge confirmation |
-| 6/6 | CLOSE | SHIP→CLOSE GATE (merge verified) → Backup sprint-state → USER ACCEPTANCE (⚠️ mandatory manual) → Capture emergent issues → Cleanup worktree + branch | Emergent issues list + cleanup report |
+| 2/6 | DESIGN | CONTEXT.md 预检 (#322) → grill-with-docs → R1 需求评审 → 设计文档+APPROVAL (HARD-GATE) → batch-grill-me → R2 delphi-review (≥90% consensus) → 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**:
-- **DESIGN → BUILD**: Design must be APPROVED by delphi-review (≥90% consensus) + GITHOOKS-GATE + DELPHI-GATE
-- **VERIFY → SHIP**: feedback-log.md must exist (HARD-GATE)
+- **DESIGN → BUILD**: R1 需求评审 APPROVED + 设计文档用户 APPROVED + R2 delphi-review APPROVED (≥90% consensus) + 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)
 
 ---
@@ -199,11 +197,28 @@ Every phase MUST output its header as the first line of that phase's output. For
 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`
-6. Each phase completion MUST call `xp-gate phase-transition <N> <status> --render` — this programmatically updates `sprint-state.json` AND renders the ASCII dashboard in one command (resolves #338, #146)
 
-### Phase Transition CLI (MANDATORY — replaces manual state updates)
+### Phase Transition — TodoWrite Embedded (MANDATORY, resolves #366)
 
-7. **NEVER** manually write to `sprint-state.json` or manually render the dashboard from template. ALWAYS use:
+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.
+
+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:
+
+   ```
+   TodoWrite item format:
+   - "Phase N: <main task> + phase-transition N completed → N+1 in_progress --render"
+   ```
+
+   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
+   ```
+
+   **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).
+
+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>']
    ```
@@ -211,14 +226,8 @@ Every phase MUST output its header as the first line of that phase's output. For
    - `<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
-   
-   Example (end of each phase):
-   ```
-   npx xp-gate phase-transition 1 completed --render --outputs '{"estimate":"3 story points"}'
-   npx xp-gate phase-transition 2 in_progress --render
-   ```
-   
-   This is a **HARD GATE** — the orchestrator MUST invoke this CLI command. Text-level instructions to "update state" or "render dashboard" are DEPRECATED; the CLI is the single source of truth for state transitions and dashboard rendering.
+
+   This is a **HARD GATE** — the CLI is the single source of truth for state transitions and dashboard rendering.
 
 ### Phase Output Status Schema (MANDATORY per phase)
 
@@ -233,25 +242,75 @@ next_phase_context: [key info for next phase]
 
 ---
 
-## Detailed Phase Instructions
+## Phase 1/6: PREP (准备工作)
+
+**触发条件**：用户输入匹配 Triggers 表中任一短语，或显式调用 `/sprint-flow`。
+
+**输入**：
+| 输入 | 来源 | 必需 |
+|------|------|------|
+| 功能描述 | 用户命令参数 | 是 |
+| 当前分支 | `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`
+
+**输出**：
+| 输出物 | 路径 | 格式 |
+|--------|------|------|
+| 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`
+
+---
+
+## 门禁条件表 (Gate Conditions)
 
-**All detailed phase instructions are in `references/phase-overview.md`**. The router file above provides the canonical structure; load the reference file for step-by-step execution guides, skill integration details, parameter documentation, output contracts, templates, and research evidence.
+| 门禁 | 位置 | 条件 | 失败处理 |
+|------|------|------|----------|
+| 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 |
 
-> **Path convention**: `@references/` and `@templates/` resolve relative to the skill directory (`skills/sprint-flow/`). The per-phase reference files (`phase-*.md`) are the authoritative source for implementation details — this router file provides summary and dispatch logic only.
+---
+
+## Phase 2–6 详细指令
+
+> Phase 2–6 的完整步骤、输入/输出契约、模板和 Skill 集成详情见 `references/` 目录。本节提供路由摘要。
 
-**Key reference files:**
-| File | Phase | Content |
-|------|-------|---------|
-| `@references/phase-overview.md` | ALL | Complete phase details, skill integration, params, output contract |
-| `@references/phase-1-prep.md` | 1/6 | PREP — worktree isolation + sizing |
-| `@references/phase-2-design.md` | 2/6 | DESIGN — brainstorming + delphi-review HARD-GATE |
-| `@references/phase-3-build.md` | 3/6 | BUILD — ralph-loop default + TDD |
-| `@references/phase-4-verify.md` | 4/6 | VERIFY — code-walkthrough + QA + feedback |
-| `@references/phase-5-ship.md` | 5/6 | SHIP — PR + merge + deploy + canary |
-| `@references/phase-6-close.md` | 6/6 | CLOSE — UAT + cleanup |
-| `@references/orchestration-rules.md` | ALL | Agent dispatch, context inheritance, transition gates |
-| `@references/force-levels.md` | ALL | Phase forcing rules |
-| `@templates/` | ALL | Pain doc, emergent issues, sprint summary, progress templates |
+| 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/` 和 `@templates/` 相对于 skill 目录（`skills/sprint-flow/`）解析。
+
+**完整参考文件索引**：
+| 文件 | 内容 |
+|------|------|
+| `@references/phase-overview.md` | 全阶段详情、Skill 集成、参数、输出契约 |
+| `@references/orchestration-rules.md` | Agent 调度、上下文继承、转换门禁 |
+| `@references/force-levels.md` | 阶段强制执行规则 |
+| `@templates/` | Pain doc、emergent issues、sprint summary、progress 模板 |
 
 ---
 
@@ -262,7 +321,7 @@ next_phase_context: [key info for next phase]
 | 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 autoplan + delphi-review; APPROVED before coding |
+| 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 |
@@ -273,6 +332,72 @@ next_phase_context: [key info for next phase]
 
 ---
 
+## 状态机 (State Machine)
+
+```mermaid
+stateDiagram-v2
+    [*] --> PREP : trigger matched
+    PREP --> DESIGN : worktree ready
+    DESIGN --> BUILD : APPROVED ≥90%
+    DESIGN --> DESIGN : REQUEST_CHANGES (max 3 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 : 3 redesign rounds exhausted
+    BLOCKED --> [*] : user decision
+```
+
+---
+
+## 决策记录模板 (Decision Record)
+
+每个用户决策点必须记录到 `.sprint-state/decisions.md`：
+
+```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}
+```
+
+**强制决策点**：
+| 决策点 | 阶段 | 触发条件 |
+|--------|------|----------|
+| 规模确认 | PREP | AUTO-ESTIMATE 结果与用户预期不符 |
+| 设计审批 | DESIGN | delphi-review 返回 REQUEST_CHANGES |
+| 修复策略 | BUILD | 修复循环达到 3 次上限 |
+| 发布确认 | SHIP | PR 创建后等待用户确认合并 |
+| UAT 结果 | CLOSE | 用户手动验收（必须手动，禁止自动化） |
+
+---
+
+## 失败处理 (Failure Handling)
+
+| 失败场景 | 处理策略 | 升级条件 |
+|----------|----------|----------|
+| Worktree 创建失败 | 重试 1 次，失败则提示用户手动处理 | 磁盘空间不足或权限问题 |
+| delphi-review 连续 REQUEST_CHANGES | 最多 3 轮重设计，超过则 BLOCK | 3 轮后仍未 APPROVED |
+| BUILD 修复循环超限 | 最多 3 次 fix cycle，超过则 BLOCK + 用户决策 | 测试持续失败 |
+| CI 失败 | 分析失败原因，尝试 1 次自动修复 | 非 flaky 失败 |
+| PR 合并冲突 | 提示用户手动解决 | 始终（禁止自动 force） |
+| 工具缺失 | SKIP（不 BLOCK），记录到 phase summary | 始终不阻断 |
+
+**BLOCK 状态处理**：
+1. 写入 `.sprint-state/sprint-state.json` 状态为 `blocked`
+2. 输出阻塞原因 + 已完成工作 + 建议操作
+3. 等待用户决策（继续/放弃/降级）
+4. 记录决策到 `decisions.md`
+
+---
+
 ## 使用示例
 
 | 场景 | 命令 | 说明 |
@@ -283,4 +408,4 @@ next_phase_context: [key info for next phase]
 
 ## 底层 Skills 保持独立
 
-所有被调用的 Skills 独立可用：`delphi-review` (单独评审), `test-driven-development` (TDD)，sprint-flow 仅自动串联
+所有被调用的 Skills 独立可用：`delphi-review` (单独评审), `test-driven-development` (TDD), `grill-with-docs` (需求访谈), `batch-grill-me` (批量决策), `to-issues` (切片拆分)，sprint-flow 仅自动串联

package/skills/sprint-flow/references/components/memory.md

@@ -73,7 +73,7 @@ ralph-loop 内部分类:
 - `permanent`: 跨 REQ 持久化（通用约束、模式）
 - `contextual`: 当前 REQ 生命周期内有效
 
-gstack/learn 调用分类: permanent / contextual 通过 progress.log 持久化。
+learnings.md 写入分类: permanent / contextual 通过 `.sprint-history/learnings.md` 持久化（原生，替代原 gstack/learn）。
 
 ---
 

package/skills/sprint-flow/references/components/middleware.md

@@ -61,7 +61,7 @@ Phase 6: SHIP → finishing-a-development-branch → canary → Sprint Summary
 | `CIRCUIT_BREAKER_TRIGGERED` | sprint-flow 编排层监控成本，超阈值 BLOCK + 用户决策 |
 | `ROLLBACK_TO_ROUND1` | verification-before-completion 失败 → 修复 max 3 次 → 仍失败 BLOCK |
 | `GATE1_FAILED`/`GATE1_COMPLETE` | verification-before-completion 内置此区分 |
-| `GATE2_RUNNING` | `cso` (gstack) — Phase 1-6 安全审计 |
+| `GATE2_RUNNING` | `xp-gate check --all`（Gate 7/8/9）— Phase 1-6 安全审计 |
 
 ---
 

package/skills/sprint-flow/references/components/skill-invocations.md

@@ -15,15 +15,17 @@
 
 | Skill | 来源 | 触发条件 | 输出 |
 |-------|------|---------|------|
-| `brainstorming` | superpowers | 无条件（首个 Skill） | 结构化设计文档 |
+| `grill-with-docs` | Matt Pocock (内置) | CONTEXT.md 不存在时（首个 Skill） | 访谈记录 + CONTEXT.md + ADR |
+| `delphi-review --mode requirements` | xp-gate | R1 需求评审（轻量 2 专家 1 轮） | requirements-reviewed.json |
+| 原生设计文档生成 | sprint-flow 编排层 | R1 APPROVED 后 | docs/plans/YYYY-MM-DD-<topic>-design.md |
 | **硬闸门** | — | 设计未批准 → 停止 | 禁止进入 Plan |
 
 ### Phase 1: PLAN
 
 | Skill | 来源 | 触发条件 | 条件分支 |
 |-------|------|---------|---------|
-| `autoplan` | gstack | 进入 Phase 1 自动调用 | 输出 AUTO_APPROVED 或 NEEDS_REVIEW |
-| `delphi-review` | xp-gate | Phase 1 强制调用；AUTO_APPROVED + 无 taste_decisions 使用 lightweight delphi-review | 必须产生 `.sprint-state/delphi-reviewed.json` 且 verdict=APPROVED |
+| `batch-grill-me` | Matt Pocock (内置) | 标准路径（change_type != "修改已存在代码"） | 批量前置决策 |
+| `delphi-review` | xp-gate | R2 设计评审；lightweight 路径使用 2 专家 1 轮 | 必须产生 `.sprint-state/delphi-reviewed.json` 且 verdict=APPROVED |
 | `to-issues` | xp-gate | delphi-review APPROVED 后 | 拆解为垂直切片 → slices-manifest.json |
 
 ### Phase 2: BUILD
@@ -31,22 +33,22 @@
 | 步骤 | Skill | 来源 | 参数注入 |
 |------|-------|------|---------|
 | -1 | `hooks-install` | githooks | 无 |
-| 0 | `dispatching-parallel-agents` | superpowers | 仅分发 AFK 切片（dependency_graph 判定） |
-| 1 | `test-driven-development` | superpowers | `--lang` 注入对应 TDD skill |
-| 2 | `executing-plans` | superpowers | 隔离 session，review checkpoint |
-| 3 | `freeze` | gstack | 锁定业务代码 |
-| 4 | `requesting-code-review` | superpowers | 盲评 agent |
-| 5 | `unfreeze` | gstack | 解锁 |
-| 6 | `verification-before-completion` | superpowers | 运行测试 + lint |
-| 7 | 成本监控 | sprint-flow 编排层 | token 阈值 |
+| 0 | BUILD-ENTRY-CONTRACT | xp-gate CLI | slices-manifest.json schema + slice↔REQ 校验 |
+| 1 | `test-driven-development` | xp-gate (内置) | `--lang` 注入对应 TDD skill |
+| 2 | ralph-loop / parallel dispatch | sprint-flow 编排层 | 隔离 session，review checkpoint |
+| 3 | blind-review (read-only subagent) | sprint-flow 编排层 | tools: [Read, Grep, Glob] |
+| 4 | verification-before-completion | sprint-flow 编排层 | 运行测试 + lint |
+| 5 | 成本监控 | sprint-flow 编排层 | token 阈值 |
+| 6 | learnings.md 写入 | sprint-flow 编排层 | 原生文件写入 |
 
 ### Phase 3: REVIEW
 
 | Skill | 模式 | 触发条件 |
 |-------|------|---------|
 | `delphi-review` | `--mode code-walkthrough` | 强制调用 |
-| `test-specification-alignment` | 默认 | 强制调用 |
-| `browse` | gstack | 强制调用 |
+| `test-specification-alignment` | 默认 | 强制调用（#367 程序化 HARD-GATE） |
+| `xp-gate check --all` | 全量门禁 | 强制调用 |
+| 浏览器验证 | Layer 4 可选链 | gstack browse > browser-use MCP > SKIP |
 | `k6`/`locust`/`gatling` | 性能测试 | `--with-performance` 或 `--type backend-*` |
 
 ### Phase 4: USER ACCEPTANCE
@@ -59,18 +61,17 @@
 
 | Skill | 来源 | 说明 |
 |-------|------|------|
-| `learn` | gstack | 模式记录 |
-| `retro` | gstack | 工程回顾 |
-| `systematic-debugging` | superpowers | 根因调试 |
+| learnings.md 写入 | 原生 | 模式记录（替代原 gstack learn） |
+| `xp-gate retro` | 原生 CLI | 工程回顾（含 #369 返工率区块） |
+| systematic-debugging | Layer 4 可选 | 根因调试（如已安装；否则"无根因不修复"文本纪律） |
 
 ### Phase 6: SHIP
 
 | Skill | 说明 |
 |-------|------|
-| `finishing-a-development-branch` | 4 选项 |
-| `ship` | 创建 PR（可选） |
-| `land-and-deploy` | 合并部署 |
-| `canary` | 监控告警 |
+| 分支完成决策（原生 4 选项） | merge / PR / keep / discard |
+| native ship 步骤 | test → VERSION-GATE → commit → push → gh pr create |
+| native land 步骤 | merge 确认 → wait CI → canary → fail git revert |
 
 ---
 

package/skills/sprint-flow/references/components/tool-descriptions.md

@@ -16,14 +16,13 @@
 | 步骤 | Skill | 来源 | 说明 |
 |------|-------|------|------|
 | -1 | `hooks-install` | githooks | `githooks/verify.sh` → 缺失则 `githooks/install.sh` |
-| 0 | `dispatching-parallel-agents` | superpowers | 检测可并行任务 |
-| 1 | `test-driven-development` | superpowers | RED → GREEN → REFACTOR |
-| 2 | `executing-plans` | superpowers | 隔离 session，review checkpoint |
-| 3 | `freeze` | gstack | 盲评隔离 |
-| 4 | `requesting-code-review` | superpowers | 独立 agent 评审 |
-| 5 | `unfreeze` | gstack | 解锁 |
-| 6 | `verification-before-completion` | superpowers | 测试 + lint |
-| 7 | 成本监控 | sprint-flow 编排层 | 超阈值 BLOCK |
+| 0 | BUILD-ENTRY-CONTRACT | xp-gate CLI | slices-manifest.json schema + slice↔REQ 校验 |
+| 1 | `test-driven-development` | xp-gate (内置) | RED → GREEN → REFACTOR |
+| 2 | ralph-loop / parallel dispatch | sprint-flow 编排层 | 隔离 session，review checkpoint |
+| 3 | blind-review (read-only subagent) | sprint-flow 编排层 | tools: [Read, Grep, Glob]，只读盲评 |
+| 4 | verification-before-completion | sprint-flow 编排层 | 测试 + lint |
+| 5 | 成本监控 | sprint-flow 编排层 | 超阈值 BLOCK |
+| 6 | learnings.md 写入 | sprint-flow 编排层 | 原生模式记录 |
 
 ### GITHOOKS-GATE (Phase 1→2 闸门)
 
@@ -46,8 +45,9 @@
 | Skill | 模式 | 说明 |
 |-------|------|------|
 | `delphi-review` | `--mode code-walkthrough` | 多专家匿名代码走查 |
-| `test-specification-alignment` | 默认 | 测试与 Spec 对齐验证 |
-| `browse` | gstack | 浏览器自动化测试 |
+| `test-specification-alignment` | 默认 | 测试与 Spec 对齐验证（#367 程序化 HARD-GATE） |
+| `xp-gate check --all` | 全量门禁 | Gate 0–9 含安全审计 |
+| 浏览器验证 | Layer 4 可选链 | gstack browse > browser-use MCP > SKIP |
 | `k6` / `locust` / `gatling` | 可选 | 后端负载测试 |
 
 ---
@@ -56,9 +56,9 @@
 
 | Skill | 说明 |
 |-------|------|
-| `learn` | gstack，模式记录 |
-| `retro` | gstack，工程回顾 |
-| `systematic-debugging` | superpowers，根因调试 |
+| learnings.md 写入 | 原生模式记录（替代原 gstack learn） |
+| `xp-gate retro` | 原生工程回顾（含 #369 返工率区块） |
+| systematic-debugging | Layer 4 可选，根因调试（如已安装） |
 
 ---
 
@@ -66,10 +66,9 @@
 
 | Skill | 说明 |
 |-------|------|
-| `finishing-a-development-branch` | 4 选项: merge / PR / discard / keep |
-| `ship` | gstack，创建 PR |
-| `land-and-deploy` | 合并部署 |
-| `canary` | 监控告警 |
+| 分支完成决策（原生 4 选项） | merge / PR / keep / discard |
+| native ship 步骤 | test → VERSION-GATE → commit → push → gh pr create |
+| native land 步骤 | merge 确认 → wait CI → canary → fail git revert |
 
 ---
 
@@ -77,12 +76,12 @@
 
 | Phase | Backend (default) | Web Frontend | Mobile |
 |-------|------------------|-------------|--------|
-| Phase 0 (THINK) | `brainstorming` | (同) | (同) |
-| Phase 1 (PLAN) | `autoplan` + `delphi-review` | + `design-shotgun` | (同 web) |
-| Phase 2 (BUILD) | TDD + blind-review | (同 backend) | + `vercel-react-native-skills` / `flutter-review` |
-| Phase 3 (REVIEW) | `delphi-review --mode code-walkthrough` | + `qa` + `design-review` + `benchmark` | `flutter-test` / `detox E2E` |
-| Phase 5 (FEEDBACK) | `learn` + `retro` | (同) | (同) |
-| Phase 6 (SHIP) | `finishing-a-development-branch` + `ship` | (同) | + platform deploy |
+| Phase 0 (THINK) | `grill-with-docs` + R1 `delphi-review --mode requirements` | (同) | (同) |
+| Phase 1 (PLAN) | `batch-grill-me` + R2 `delphi-review` | + OPTIONAL `design-shotgun` | (同 web) |
+| Phase 2 (BUILD) | TDD + blind-review (read-only subagent) | (同 backend) | + `vercel-react-native-skills` / `flutter-review` |
+| Phase 3 (REVIEW) | `delphi-review --mode code-walkthrough` + `xp-gate check --all` | + `xp-gate ui-review` + OPTIONAL qa/design-review/benchmark | `flutter-test` / `detox E2E` |
+| Phase 5 (FEEDBACK) | learnings.md + `xp-gate retro` | (同) | (同) |
+| Phase 6 (SHIP) | 原生 4 选项 + native ship + native land | (同) | + platform deploy |
 
 ---