@xulthekl/team-flow 0.22.4

package/skills/session-handoff/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: session-handoff
+description: >
+  将当前会话的工作上下文压缩为结构化交接文档，供新会话无缝继续。
+  当长时间对话导致上下文腐化、产出质量下降时使用；
+  也可在切换设备、交接给其他开发者时使用。
+  不适用于：change 级任务委派（用 tf handoff）、
+  产品级状态恢复（已由 .team-flow/ yaml 自动处理）、
+  subagent 进程内交接（已由 §18.1 交接协议覆盖）。
+argument-hint: "[下一个会话的关注点描述]"
+---
+
+# Session Handoff
+
+将当前会话的隐性知识压缩为结构化交接文档，让新会话无损继续。
+
+> **设计依据**：设计增强方案 v0.8 §21.1（P1-10，v0.16.0）
+
+## Use This Skill When
+
+- 长时间对话后产出质量下降（重复提问、遗忘约束、答非所问）
+- 用户主动说"交接"、"换会话"、"handoff"、"上下文太长"
+- 切换设备或交接给其他开发者
+- 模型检测到上下文腐化迹象时**建议**用户触发（不强制）
+
+**Do NOT use when**：
+- change 级任务委派 → `tf handoff`（prototype/research/experiment）
+- 产品级状态恢复 → 已由 `.team-flow/` yaml 自动处理
+- subagent 进程内交接 → 已由 §18.1 交接协议覆盖
+
+## Support Files
+
+| 文件 | 用途 | 何时读取 |
+|------|------|---------|
+| `references/handoff-template.md` | 交接文档 10 节模板 | Step 3 生成文档时 |
+| `references/context-extraction.md` | 上下文萃取规则（6 类隐性知识） | Step 2 萃取时 |
+| `references/skill-recommendation.md` | 基于触发域分层的 skill 推荐规则 | Step 4 恢复指引时 |
+
+**按需读取，勿批量加载。**
+
+## Core Workflow
+
+```
+触发 → 1. 环境感知 → 2. 上下文萃取 → 3. 文档生成 → 4. 恢复指引
+```
+
+### Step 1：环境感知（自动）
+
+检测以下状态文件，构建工作流快照：
+
+| 检测目标 | 路径 | 提取信息 |
+|---------|------|---------|
+| 需求注册表 | `.team-flow/registry.yaml` | 活跃需求、需求列表 |
+| 编排状态 | `.team-flow/requirements/<req-id>/orchestrator.yaml` | SOP 阶段（S1-S5） |
+| 变更级状态 | `<change>/.team-flow.yaml` | 状态机 8 态中的当前态 |
+| PRD 版本 | `prd/vN/prd.md` frontmatter | 迭代版本、冻结状态 |
+
+**降级规则**：上述文件均不存在 → 通用 handoff 模式（跳过工作流状态节）。
+
+### Step 2：上下文萃取
+
+从当前对话中提取 6 类隐性知识（详见 `references/context-extraction.md`）：
+
+1. **进度摘要**：已完成 / 正在进行 / 下一步
+2. **关键决策**：本次会话做出的、尚未写入产物的决策
+3. **未解决问题**：悬而未决的问题、临时假设
+4. **用户偏好**：不在文档中的隐性偏好
+5. **失败尝试**：尝试过但放弃的方案及原因
+6. **敏感信息**：API Key / Token / 密码 → 替换为 `${PLACEHOLDER}`
+
+### Step 3：文档生成
+
+按 `references/handoff-template.md` 的 10 节结构生成：
+
+- **有 argument** → 直接写入 §1「下一个会话的关注点」
+- **无 argument** → 从对话最后 5 轮推断关注点
+- **输出路径**：`.team-flow/handoffs/<YYYYMMDD-HHmmss>-<req-id|general>.md`
+- **核心原则**：引用产物路径，**不复制内容**
+- **敏感信息**：所有凭据以 `${PLACEHOLDER}` 表示
+
+### Step 4：恢复指引（输出到终端，不写入文档）
+
+1. 告诉用户新会话中的恢复操作：
+   ```
+   新会话中执行：
+   1. 读取 .team-flow/handoffs/<文件名>.md
+   2. 按文档 §8 建议的 skills 继续工作
+   ```
+2. 基于当前阶段推荐 skills（详见 `references/skill-recommendation.md`）
+
+## Guardrails
+
+1. **不复制产物内容**：PRD、plan.md、spec 等只引用路径
+2. **不重复状态文件**：yaml 中已有的结构化数据只引用，不抄写
+3. **必须脱敏**：所有凭据值替换为 `${PLACEHOLDER}`
+4. **不替代状态恢复**：`.team-flow/` yaml 的跨 session 恢复是自动的，handoff 补充非结构化隐性知识
+5. **handoffs/ 目录加入 .gitignore**：交接文档是临时性质
+
+## Output
+
+- 交接文档：`.team-flow/handoffs/<timestamp>-<req-id>.md`
+- 终端输出：恢复指引 + 建议 skills 列表
+
+## Exception Handling
+
+| 异常 | 处理 |
+|------|------|
+| `.team-flow/` 不存在 | 降级为通用 handoff（跳过工作流状态节） |
+| 对话内容过短（<5 轮对话，一问一答为一轮） | 提示用户：当前上下文尚浅，建议继续当前会话 |
+| handoffs/ 目录不存在 | 自动创建 |

package/skills/session-handoff/references/context-extraction.md

@@ -0,0 +1,70 @@
+# 上下文萃取规则（6 类隐性知识）
+
+> 本文件定义 session-handoff Step 2 的萃取规则。
+> 核心原则：萃取"只存在于对话上下文中的隐性知识"，已在产物中的信息只引用路径。
+
+## 萃取分类
+
+### 1. 进度摘要
+
+**萃取方法**：回顾对话中的工作动作序列，归纳为三类：
+- **已完成**：已经产出文件或已经确认的事项
+- **正在进行**：当前正在处理但未完成的事项（标注卡点）
+- **下一步**：紧接着要做的 1-3 件事
+
+**注意**：进度是会话级的，不是项目级的。只记录本次会话的进展。
+
+### 2. 关键决策
+
+**萃取方法**：识别对话中用户确认或模型提出并被接受的决策，且该决策**尚未写入任何产物文件**。
+
+**判断标准**：
+- 如果决策已写入 PRD/plan/spec/design → 不记录，引用产物路径
+- 如果决策只在对话中确认 → 记录到 §4
+
+**典型场景**：
+- "用方案 A 不用方案 B"（但未写入 design.md）
+- "这个功能先不做"（但未更新 PRD scope）
+- "用 X 库代替 Y 库"（但未更新 plan.md）
+
+### 3. 未解决问题
+
+**萃取方法**：识别对话中提出但未最终回答的问题，以及模型做出的临时假设。
+
+**格式**：每个问题标注"默认处理"（当前按什么假设在继续）和"需要确认？"。
+
+### 4. 用户偏好
+
+**萃取方法**：识别用户表达的偏好、约束、风格要求，且这些偏好**不在任何项目文档中**。
+
+**典型场景**：
+- "我不喜欢太多确认弹窗"
+- "代码风格偏向函数式"
+- "先做核心功能，花里胡哨的后面的再说"
+- "不要引入新的依赖"
+
+### 5. 失败尝试
+
+**萃取方法**：识别对话中尝试过但放弃的方案，记录放弃原因。
+
+**价值**：防止新会话重新走一遍同样的死路。
+
+**格式**：`方案 X：放弃原因 → ...`
+
+### 6. 敏感信息
+
+**萃取方法**：扫描对话和生成的文档内容，识别以下模式：
+- API Key / Token / Secret
+- 密码 / 凭据
+- 个人身份信息（PII）
+
+**处理**：全部替换为 `${PLACEHOLDER}`，在 §10 声明已脱敏。
+
+## 萃取优先级
+
+当对话内容过多时，按以下优先级取舍：
+
+1. **必须**：进度摘要 + 下一步（没有这个新会话无法继续）
+2. **重要**：关键决策 + 未解决问题（没有这个新会话可能走弯路）
+3. **建议**：失败尝试 + 用户偏好（没有这个新会话可能重蹈覆辙）
+4. **可选**：敏感信息声明（无敏感信息时可简化）

package/skills/session-handoff/references/handoff-template.md

@@ -0,0 +1,90 @@
+# 交接文档模板（10 节结构）
+
+> 本文件是 session-handoff skill 的交接文档生成模板。
+> 设计依据：v0.8 §21.1
+
+## YAML Frontmatter
+
+```yaml
+---
+type: session-handoff
+version: 1
+created_at: <ISO 8601>
+requirement_id: <req-id | null>
+workflow_phase: <S1-S5 | change-level | null>
+state_machine: <8态之一 | null>
+change_dir: <path | null>
+---
+```
+
+## 正文结构
+
+### §1 下一个会话的关注点
+
+用户传入的 argument 内容，或从对话上下文推断的下一步关注点。如果用户未传入 argument，从对话最后 5 轮推断。
+
+### §2 工作流状态（自动检测，引用不复制）
+
+- 活跃需求：`<req-id>` — `<title>`
+- 产品级阶段：`<S1-S5>`（详见 `.team-flow/requirements/<req-id>/orchestrator.yaml`）
+- 变更级状态：`<state>`（详见 `<change>/.team-flow.yaml`）
+- PRD 版本：`<vN>`，冻结状态：`<frozen_downstream | frozen_absolute | unfrozen>`
+
+> 通用 handoff 模式下跳过本节。
+
+### §3 本次会话进度
+
+#### 已完成
+- （列出本次会话完成的工作项）
+
+#### 正在进行
+- （列出当前卡在哪里、进展到什么程度）
+
+#### 下一步
+- （列出紧接着要做的事情）
+
+### §4 关键决策（未写入产物的）
+
+| 决策 | 理由 | 影响范围 |
+|------|------|---------|
+| （本次会话中做出的、尚未持久化到任何产物中的决策） | | |
+
+> 已写入 PRD/plan/spec 的决策不需要重复。
+
+### §5 未解决问题与临时假设
+
+| 问题/假设 | 默认处理 | 需要确认？ |
+|-----------|---------|-----------|
+| （悬而未决的问题） | （当前按什么假设在处理） | 是/否 |
+
+### §6 失败尝试（避免重蹈覆辙）
+
+- 方案 X：放弃原因 → （为什么不行，避免新会话重新尝试）
+
+### §7 用户偏好与约束（会话级）
+
+- （不在文档中的隐性偏好，如"LT 不喜欢 X 方案"、"优先用 Y 技术"）
+
+### §8 建议 Skills（新会话应调用）
+
+| 优先级 | Skill | 理由 |
+|--------|-------|------|
+| 1 | （基于当前阶段推荐的 skill） | （为什么需要这个 skill） |
+| 2 | | |
+
+> 推荐规则详见 `skill-recommendation.md`。
+
+### §9 关键产物引用（不复制，只引用路径）
+
+- PRD: `prd/vN/prd.md`
+- 实施方案: `prd/vN/plan.md`
+- 原型: `prototype/index.html`
+- 设计方案: `docs/architecture-api-db-design-enhancement-v0.8.md`
+- 复利经验: `docs/solutions/INDEX.md`
+- 领域词汇: `CONCEPTS.md`
+
+> 仅列出与当前工作相关的产物，不需要全部列出。
+
+### §10 敏感信息声明
+
+本文档已脱敏。所有凭据以 `${PLACEHOLDER}` 表示。原始值不存在于本文档中。

package/skills/session-handoff/references/skill-recommendation.md

@@ -0,0 +1,43 @@
+# Skill 推荐规则（基于触发域分层）
+
+> 本文件定义 session-handoff Step 4 的 skill 推荐逻辑。
+> 基于 AGENTS.md 触发域分层表，根据当前工作流阶段推荐新会话应调用的 skills。
+
+## 推荐矩阵
+
+| 当前阶段 | 推荐 Skill（优先级 1） | 推荐 Skill（优先级 2） | 说明 |
+|---------|---------------------|---------------------|------|
+| Bootstrap（无 baseline.md） | workflow-bootstrap | — | 继续完成接入初始化 |
+| S1 路径路由 | workflow-orchestrator | — | 继续需求选择/路径判断 |
+| S2 PRD + 原型 | workflow-orchestrator | ce-brainstorm / prototype | 继续 PRD 编写或原型迭代 |
+| S3 计划 | workflow-orchestrator | ce-plan | 继续实施方案制定 |
+| S4 拆分分发 | workflow-orchestrator | — | 继续 change 拆分 |
+| S5 全局监控 | workflow-orchestrator | — | 继续跨 change 监控 |
+| change: exploring | workflow-start | need-explorer | 继续需求探索 |
+| change: specifying | workflow-start | spec-writer | 继续规划制品编写 |
+| change: bridging | workflow-start | contract-builder | 继续执行契约构建 |
+| change: executing | workflow-start | build-executor | 继续实现 |
+| change: debugging | workflow-start | bug-investigator | 继续调试 |
+| change: closing | workflow-start | release-archivist | 继续收尾 |
+| 无工作流上下文 | （根据用户 argument 推断） | ce-compound | 通用模式 |
+
+## 附加推荐
+
+无论处于哪个阶段，以下 skills 可作为附加推荐：
+
+| 条件 | 附加推荐 | 理由 |
+|------|---------|------|
+| 本次会话有值得沉淀的经验 | ce-compound | 捕获经验到 docs/solutions/ |
+| 本次会话发现工作流问题 | workflow-feedback | 记录问题供 plugin 优化 |
+| 涉及架构设计决策 | architecture-design | 4A+DDD 增量设计 |
+| 涉及 E2E 测试 | e2e | AC 驱动 Playwright 测试 |
+
+## 推荐输出格式
+
+在交接文档 §8 和终端输出中，按以下格式呈现：
+
+```
+建议 Skills（新会话应调用）：
+1. workflow-orchestrator — 当前在 S2 阶段，需继续 PRD 编写
+2. ce-compound — 本次会话有值得沉淀的经验（XX 问题的解决方案）
+```

package/skills/spec-merger/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: spec-merger
+description: Sync delta specs to main specs after closure. Invoke when a change is closing, delta specs need merging into the main spec base, or when detecting spec drift across multiple changes.
+---
+
+# Spec Merger
+
+After a change completes, delta specs (ADDED/MODIFIED/REMOVED/RENAMED) must be merged into the main spec base. **Specs that aren't synced become lies.**
+
+## Pre-Flight Checks
+
+### Conflict Detection
+Run `npx --yes --package @xulthekl/team-flow@0.22.4 tf sync <change-dir>`. If conflicts are detected (same requirement modified by multiple changes), present the conflict list to the user for resolution order.
+
+### Abandoned Change Guard
+Check if the change is `abandoned`. If so → STOP: "Abandoned changes cannot be synced. Delta specs are preserved for reference but must not be merged."
+
+## Sync Process
+
+### Step 1: Identify Deltas
+Each `specs/<capability>/spec.md` under the change folder contains delta operations under `## ADDED/MODIFIED/REMOVED/RENAMED Requirements`.
+
+### Step 2: Apply by Operation
+
+**ADDED**: Append to `specs/<capability>/spec.md`. Create the main spec if it doesn't exist. Insert before any REMOVED section.
+
+**MODIFIED**: Match on `### Requirement: <name>`. Replace description and scenarios. Preserve original in a `### Previous version` subsection. Flag if requirement doesn't exist in main spec.
+
+**REMOVED**: Move to `## Removed` section with deprecation note: reason, migration, and change name. Flag if requirement doesn't exist.
+
+**RENAMED**: Match old name, change header to new name, add `_Renamed from <old> in <change>_`. Flag if new name collides with existing.
+
+### Step 3: Conflict Detection
+Before executing, detect:
+- Same requirement modified by multiple unsynced changes → manual resolution
+- RENAMED target collides with existing requirement → manual resolution
+- MODIFIED/REMOVED targeting nonexistent requirements → flag
+
+### Step 4: Execute Merge
+Apply changes. Do NOT delete delta specs — they remain for traceability. After merge, validate: no duplicate requirement names, no orphaned references, REMOVED section clearly separated.
+
+### Step 5: Report
+Output sync report table: Capability, ADDED/MODIFIED/REMOVED/RENAMED counts, Status (✓/⚠). Summary with totals and unresolved conflicts.
+
+## Guardrails
+
+- Do not delete delta spec files (historical record)
+- Do not auto-resolve conflicts across changes
+- Do not merge specs for unverified changes
+- Validate main spec consistency after each capability merge
+
+## Post-Sync
+
+1. Report results. If no conflicts → ready to archive. If conflicts → user resolves before archive.
+2. Change folder (including deltas) remains for traceability.
+3. Record that merging is complete so the `executing → closing` guard allows closure:
+   ```bash
+   npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> spec_merged true
+   ```
+   (If the change had no delta sections, still set `spec_merged true` — there was nothing to merge.)
+
+## Exception Handling
+
+- **Parse failures**: Report file and section. Do not attempt partial merges.
+- **No deltas**: If change has no delta sections, report nothing to merge and exit cleanly.
+- **User interruption**: On resume, check for merge conflict markers before proceeding.

package/skills/spec-writer/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: spec-writer
+description: Create or refine team-flow planning artifacts. Invoke when the change is understood well enough to write proposal.md, specs/, design.md, and tasks.md.
+---
+
+# Spec Writer
+
+Create or refine planning artifacts when the change has moved beyond exploration.
+
+## Required Inputs
+
+Read `.team-flow.yaml` (especially `dp_0_decisions`, `dp_0_confirmed`) and any existing planning artifacts. If `dp_0_confirmed` is not `true`, stop and route back to `workflow-start` for DP-0.
+
+### Global Prototype Reading (v0.5)
+
+Before generating artifacts, check if a global prototype exists:
+1. Read `prototype/flow.md` if it exists — this defines page navigation and user flows
+2. List `prototype/pages/` directory — these are the UI contract pages
+3. Read `prototype/design-system.md` if it exists — component and token definitions
+4. Store as UI contract context for design.md and tasks.md generation
+
+If `prototype/` does not exist or is empty, skip silently — not all projects have prototypes.
+
+### Solutions Index (v0.5)
+
+Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = spec OR phase = cross-phase` and `domain` matches the current change's domain. Inject top-5 summaries as context constraints for artifact generation. If INDEX.md does not exist or is empty, skip silently.
+
+### Change Brief (v0.9)
+
+若 `change-brief.md` 存在（本 change 由 workflow-orchestrator S4 分发），读取其 Scope / 约束 / AC 列表 / 全局技术方向：
+- **Scope** 作为 proposal.md 的 scope 边界基线——不静默超出 brief scope。
+- **AC 列表** 作为 specs/ 的 AC 覆盖上限——brief 列出的 AC 必须在 specs/ 中体现，**不**静默丢弃；若认为 brief AC 有误或与 plan.md 冲突，以 `prd/vN/plan.md` / PRD 为准并在 proposal 注明，而非静默改写。
+- brief 不存在时（手动新建 / 快速通道）跳过本段，按原流程从 `dp_0_decisions` 取意图。
+
+### Plan Technical Direction (v0.9)
+
+若产品级 `prd/vN/plan.md` 存在，读取其**高阶技术设计段**（模块边界 / 技术选型 / 数据流方向 / 关键聚合与上下文划分），作为 design.md 的 `## Decisions` 约束输入——保证各 change 的技术方案与全局方向一致，避免各自为政。**禁止**反向要求 plan.md 提供接口清单 / 字段定义 / 方法签名（这些是 spec-writer / architecture-design 在本 change 内的产出，plan.md 不含，见 ce-plan 作用边界与 v0.8 §18.7.2）。plan.md 不存在时跳过本段。
+
+### Architecture Design Outputs (v0.9 §26)
+
+若 `architecture/` 目录存在（本 change 经 workflow-start 的 architecture-design 判断门判定为 `required` 并产出了架构设计），读取以下文件作为 design.md / tasks.md 的架构约束输入：
+
+- `architecture/architecture.md` → design.md `## Decisions` 的架构约束（聚合/限界上下文/CQRS 决策）
+- `architecture/database.md` → design.md + tasks.md 的数据层约束（实体/读写模型/schema 变更）
+- `architecture/api.md` → tasks.md 的接口定义约束（端点/方法签名/Command-Read-Query 分流）
+
+**约束传递规则**：
+- design.md 的 `## Decisions` 段必须**引用** architecture/ 中的架构决策，不得与之矛盾
+- tasks.md 的接口定义（Interfaces 段）必须与 `architecture/api.md` 的 API 设计对齐
+- tasks.md 的数据层任务必须与 `architecture/database.md` 的 schema 变更对齐
+
+`architecture/` 目录不存在时（判定为 `skipped`）跳过本段。
+
+## Config Check
+
+Run: `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime config --get artifacts.order` — generate in configured order (default: proposal → specs → design → tasks). Run with `artifacts.skip` — skip any listed artifacts.
+
+## Artifact Roles
+
+- `proposal.md`: why and scope
+- `specs/`: required behavior (testable)
+- `design.md`: architecture decisions and trade-offs (not line-by-line)
+- `design.md` (v0.5 addition): When the change involves UI features, the Context section MUST reference the global prototype as UI contract source. Cite specific prototype pages (e.g., `prototype/pages/login.html`) and flow definitions (e.g., `prototype/flow.md#login-flow`). Do NOT redefine UI interactions in design.md — reference the prototype as the single source of truth for UI behavior.
+- `tasks.md`: dependency-aware implementation steps
+
+## Working Rules
+
+**Honor DP-0**: Read `dp_0_decisions`, respect confirmed constraints, don't silently expand scope. Pause on unconfirmed decisions.
+
+**Honor Brief (v0.9)**: 若 `change-brief.md` 存在，尊重其 scope 边界与 AC 列表（见 Required Inputs「Change Brief」）——不静默丢弃 brief AC、不静默超出 brief scope；与 plan.md 冲突时以 plan.md 为准并注明。
+
+**Honor Architecture (v0.9 §26)**: 若 `architecture/` 目录存在，design.md 的 Decisions 段必须引用其架构决策（聚合/限界上下文/CQRS/API/DB），tasks.md 的接口定义和数据层任务必须与 architecture/ 产出对齐——不得静默忽略或矛盾架构设计产出。
+
+### proposal.md
+Must state: problem, what changes, capabilities affected, impact areas.
+
+### specs/
+Every requirement must be testable. Use SHALL or MUST. Every requirement must have at least one `#### Scenario:` with WHEN/THEN. Group under ADDED/MODIFIED/REMOVED Requirements headers.
+
+Optional structured AC tags under a Scenario are supported for E2E extraction (v0.4, design spec ch.16): `##### Exception:` (→ EX AC, ×2), `##### State:` (→ ST AC, ×2), `##### Boundary:` (→ BND AC, ×1). These are **OPTIONAL** — omitting them does NOT fail validation. The `e2e` skill applies dimension-conditional gating (absent dimension = N/A, not 0%) plus keyword fallback (error/invalid/fail/边界), so no spec is forced to add tags.
+
+### design.md
+Must have: Context (current state, constraints, stakeholders), Goals, Decisions (Choice + Rationale + Alternatives considered), Risks And Trade-Offs.
+
+**Prototype reference (v0.5)**: For UI-related changes, include a `## UI Contract` section in design.md that:
+- References the prototype entry point (`prototype/index.html`)
+- Lists affected prototype pages with their paths
+- References relevant flow definitions from `prototype/flow.md`
+- Notes any prototype components used (`prototype/components/`)
+- States: "UI behavior is defined by the global prototype. This design does not redefine UI interactions."
+
+### tasks.md
+Must include:
+- **File Structure**: all files with one-sentence responsibility (Create/Modify)
+- **Interfaces**: cross-batch Consumes/Produces with exact types
+- **Per-task**: exact file paths, expanded TDD phases (5 steps), Interfaces block
+- **Granularity**: each step 2-5 min, atomic
+- **Zero placeholders**: no TBD, TODO, "figure out", "add appropriate"
+- **Dependency ordering**: depends only on prior tasks, explicit "Depends on: Batch N"
+
+**Prototype-aware tasks (v0.5)**: For UI-related tasks, include prototype references:
+- File paths in `**Files:**` should reference prototype pages when the task implements a UI page
+- Add `**Prototype:** prototype/pages/<page>.html` field for UI implementation tasks
+- Test scenarios for UI tasks should reference prototype flow definitions
+
+## Artifact Generation
+
+Generate one at a time. Confirm each before next. This prevents scope drift — if proposal has errors, downstream artifacts are wrong.
+
+1. `proposal.md` → present summary → wait for confirm
+2. `specs/` → present requirement list → wait for confirm
+3. `design.md` → present key decisions → wait for confirm
+4. `tasks.md` → present batch breakdown → wait for confirm
+
+## Validation Checklist
+
+### proposal.md
+- `## Why` > 50 chars, `## What Changes`, `## Scope` (In/Out), `## Impact`, `## Capabilities`, no TBD/TODO
+
+### specs/
+- SHALL/MUST for required behavior, `#### Scenario:` with WHEN/THEN per requirement, grouped under delta headers, no contradictions; optional `##### Exception:/State:/Boundary:` sub-tags allowed but NOT required (absent dimension = N/A, not 0%). Regression: a spec containing `##### Exception:` must still pass `npm run validate` (validateDeltaSpec must not reject unknown sub-headings).
+
+### design.md
+- `## Context`, `## Goals`, `## Decisions` (≥1, with Choice+Rationale+Alternatives), `## Risks And Trade-Offs`
+- **Architecture alignment (v0.9 §26)**: 若 `architecture/` 存在，`## Decisions` 必须引用架构设计产出中的关键决策（聚合/限界上下文/CQRS/API/DB）
+
+### tasks.md
+- `## File Structure`, `## Interfaces`, numbered tasks, exact file paths, TDD phases, ≤5 min steps, no placeholders, every requirement mapped, explicit dependencies
+
+**If any artifact fails validation, fix before handing off to contract-builder.**
+
+## DP-2: Artifact Review Gate
+
+Present summary of all 4 artifacts (2-3 sentences each). Ask user for adjustments. After approval:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_2_result "approved: <summary>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_2_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+```
+
+## Handoff Rule
+
+Do not start implementation after writing planning artifacts. Once stable, validated, and DP-2 is recorded, hand off to `contract-builder`.
+
+## Exception Handling
+
+- **Parse failures**: Report specific file/error; don't generate from corrupted templates
+- **Missing templates**: Fall back to artifact structure defined in this skill
+- **User interruption**: Artifacts on disk are the recovery checkpoint; resume from first missing/incomplete one
+- **Validation failure**: Fix before handoff — do not hand off broken artifacts