flower-trellis 0.2.4 → 0.2.5-beta.2

package/enhancements/0.6/.claude/skills/trellis-extract-prd/SKILL.md

@@ -1,34 +1,39 @@
 ---
 name: trellis-extract-prd
-description: "Extract a single requirement faithfully from a source requirements document into structured prd.md + task.json; forbid embellishment, preserve UI copy verbatim, annotate source positions. Triggers: 「提取需求」「从需求文档抽 PRD」「严格提取 PRD」「extract PRD」. Not for conversational PRD generation (trellis-brainstorm) or task-spec coverage audit (trellis-verify-task)."
+description: "Extract a cohesive task PRD faithfully from a source requirements document, optionally using version task/wave planning as task boundary context; preserve UI copy verbatim and annotate source positions."
 ---
 # Extract PRD — 基于原始需求文档
 
-从原始需求文档中提取指定需求的完整内容，结构化为 `prd.md`。**正文必须有据可依，禁止自行发挥**；仅允许在「本任务 TL;DR」与「本任务范围」两块做结论性提炼（且必须能在原文找到依据）。
+从原始需求文档中提取指定需求或版本规划中的 task 候选，结构化为 `prd.md`。**正文必须有据可依，禁止自行发挥**；仅允许在「本任务 TL;DR」与「本任务范围」两块做结论性提炼（且必须能在原文或已确认版本规划中找到依据）。
 
 ---
 
 ## 核心原则
 
 1. **原文优先** — 「来源需求原文」「Requirements 索引」「Acceptance Criteria 索引」三节必须引用或指向原始文档原文，不得改写语义
-2. **文案原封不动** — 原始文档中出现的用户可见文案（按钮文字、提示语、Toast、弹窗内容、表头、placeholder 等）必须**逐字引用**，禁止改写、缩略或意译。一个字的差异都会导致前端实现偏差
-3. **标注出处** — 每条需求/AC 标注来源位置（文档行号、章节编号或页码）
-4. **允许提炼的两个例外** — 「本任务 TL;DR」「本任务范围」允许做结论性总结，但：
-   - 每条结论必须能在原文或上下文（commit、既有任务档案、用户确认）里找到依据
-   - 只做"本次任务 vs 全功能"的分界，不引入原文没有的新需求
-5. **禁止发挥** — 不得添加原始文档中没有的需求、验收标准或业务规则
-6. **完整提取** — 该需求单元下的所有内容全部提取，不跳不漏
-7. **去重** — 同一条款在 PRD 中只应"完整出现一次"（即「来源需求原文」一节），Requirements / AC / 关联需求等其他节均以**指针**形式引用，不得复述内容
-8. **散射追踪是参考，不是清单** — 散射追踪的产物仅用于"知会关联"，不得被误读为工作范围；必须明确标注「本任务是否实现」列
+2. **版本规划约束 task 边界** — 如果存在 `doc/<版本>/任务拆分与waves.md` 或用户提供的版本规划产物，单 task PRD 的 Scope 必须落在该产物中对应 task 候选的范围内
+3. **task 必须内聚** — 单 task PRD 应代表一个可开发、可自测、可验收的闭环；不能把不相关需求塞进来，也不能把一个闭环拆成页面 / 接口 / 字段碎片
+4. **wave 是归属，不是 task** — wave 用来说明本 task 属于哪个版本提测 / 交付批次；不要把 wave 当成 `task.py` 状态或独立任务目录
+5. **文案原封不动** — 原始文档中出现的用户可见文案（按钮文字、提示语、Toast、弹窗内容、表头、placeholder 等）必须**逐字引用**，禁止改写、缩略或意译
+6. **标注出处** — 每条需求 / AC 标注来源位置（文档行号、章节编号或页码）
+7. **允许提炼的两个例外** — 「本任务 TL;DR」与「本任务范围」允许做结论性总结，但必须能在原文、版本规划或用户确认中找到依据
+8. **完整提取** — 该 task 候选 / 需求单元下的所有内容全部提取，不跳不漏
+9. **去重** — 同一条款在 PRD 中只应完整出现一次；Requirements / AC / 关联需求等其他节均以指针形式引用，不复述原文
+10. **散射追踪是参考，不是清单** — 散射追踪成果仅用于知会关联，不得误读为工作范围；必须明确标注「本任务实现」列
 
 ---
 
 ## 输入
 
 用户需提供：
-- **需要提取的需求**（编号、名称或功能描述均可）
+- **需要提取的需求**（编号、名称、功能描述，或版本规划中的 Task ID）
 - **原始需求文档路径**（如未指定，在 `doc/` 下查找）
 
+可选输入：
+- **版本规划产物路径**（默认尝试 `doc/<版本>/任务拆分与waves.md`）
+- **Task ID / task 候选名称**
+- **Wave ID / wave 名称**
+
 ---
 
 ## 执行步骤
@@ -43,18 +48,42 @@ description: "Extract a single requirement faithfully from a source requirements
 
 > **不要假设文档有特定格式**，先读再判断。
 
+### Step 1.5: 查找版本规划产物（如有）
+
+如果用户提供了版本号、版本规划路径、Task ID、Wave ID，或默认路径 `doc/<版本>/任务拆分与waves.md` 存在，则读取版本规划产物。
+
+从版本规划产物中提取：
+- Task ID / task 名称
+- 所属 wave id / 名称
+- ✅ 本 task 范围
+- ❌ 相关但不在本 task 范围
+- 来源需求位置
+- 散射组归属
+- 依赖 task
+- 可验收结果 / 可提测性
+
+如果版本规划产物存在但找不到用户指定的 task 候选：
+- 不要猜测映射
+- 明确列出候选 task，让用户选择
+
+如果版本规划产物不存在：
+- 按原始需求文档继续提取
+- 不要编造 wave / Task ID
+- 仍需遵守“task 必须内聚”的原则
+
 ### Step 2: 定位并完整提取
 
-在文档中定位用户指定的需求，**完整读取**该需求下的所有内容，直到下一个同级需求开始。
+在文档中定位用户指定的需求或 task 候选对应的来源需求，完整读取相关内容。
 
 提取时注意：
 - 保留原始的编号、层级、表格结构
 - 不要跳过任何子节（即使看起来不重要）
 - 记录提取的起止位置（行号或章节号）
+- 如果版本规划已确认 task 边界，只提取该 task 范围内的来源内容；关联但不在范围的内容放入「关联需求」或「不在范围」
 
 ### Step 3: 识别变更性质（关键一步）
 
-判断本次任务属于哪一类，并记录依据（来源文档的哪一行/章节明示）：
+判断本次任务属于哪一类，并记录依据（来源文档的哪一行 / 章节明示）：
 
 | 类别 | 典型信号 |
 |------|---------|
@@ -63,44 +92,46 @@ description: "Extract a single requirement faithfully from a source requirements
 | **修复** | 原文描述"修复/纠正"某行为 |
 | **重构** | 改实现不改行为 |
 
-> **局部变更是最容易被写偏的情况**：原文的 User Story 通常描述的是**整个功能**（历史 + 变更），不是本任务的变更点。Step 4 的 TL;DR 必须只写变更点，不要写全功能。
+> **局部变更是最容易被写偏的情况**：原文的 User Story 通常描述的是**整个功能**（历史 + 变更），不是本任务的变更点。TL;DR 必须只写变更点，不要写全功能。
 
 ### Step 4: 散射追踪
 
-提取目标需求中涉及的**关键实体**（字段名、功能点、业务概念），在全文中搜索这些关键词，检查是否在其他需求单元中也有相关内容：
+提取目标 task 中涉及的关键实体（字段名、功能点、业务概念），在全文中搜索这些关键词，检查是否在其他需求单元中也有相关内容：
 
-- 同一字段在不同页面/模块的展示、编辑、导出规则
+- 同一字段在不同页面 / 模块的展示、编辑、导出规则
 - 同一业务规则在不同入口的复用
 - 跨需求的依赖或约束
 
-**对每一条散射发现，必须立刻判定**：
+对每一条散射发现，必须立刻判定：
 - ✅ 属于本任务实现？
-- ❌ 不属于本任务？（由谁实现 / 已在哪里落地 / N/A）
+- ❌ 不属于本任务？（由哪个 task / wave 实现，或 N/A）
 
 将发现记录到 PRD 的「关联需求」表，表头必须含「本任务实现」列。
 
 ### Step 5: 生成 PRD
 
-PRD 的结构**按下列顺序**组织（顺序有意为之——让读者打开 PRD 的前 30 行就能回答"做什么、不做什么、为什么"）：
+PRD 的结构按下列顺序组织：
 
 ```markdown
-# <需求标识> <需求名称>
+# <Task ID> <任务名称>
 
 > 来源：<文档名>，<位置范围>
+> 版本规划：<doc/<版本>/任务拆分与waves.md；无则 N/A>
+> 所属 Wave：<Wave ID / 名称；无则 N/A>
 > 变更性质：新增 / 局部变更 / 修复 / 重构
 > 优先级：P?
 
 ## 本任务（TL;DR）
 - **做什么**：<一句话，≤30 字，只写本任务要改动的行为>
 - **为什么**：<一句话，变更动机 / 触发来源>
-- **变更性质**：新增 / 局部变更 / 修复 / 重构
+- **所属 Wave**：<wave id + name；没有版本规划时写 N/A>
 
 ## 本任务范围（Scope）
 - ✅ **本任务实现**：
   - <条目 1，一句一条>
   - <条目 2>
 - ❌ **相关但不在本任务范围**：
-  - <条目> — 归属：<任务名 / commit / 独立任务 / N/A 原因>
+  - <条目> — 归属：<Task ID / Wave / 独立任务 / N/A 原因>
 
 ## 来源需求原文
 <按原始文档的子结构组织，使用 blockquote 或分级标题忠实摘录>
@@ -108,33 +139,24 @@ PRD 的结构**按下列顺序**组织（顺序有意为之——让读者打开
 
 ## Requirements（索引）
 - [<编号>] <一句话摘要> — 详见「来源需求原文」§<编号> / <原文位置>
-- ...
 
 ## Acceptance Criteria（索引）
 - [ ] [<编号>] <一句话摘要> — 详见「来源需求原文」§<编号> / <原文位置>
-- ...
 
 ## 关联需求（⚠️ 上下文参考，非本任务范围）
 | 需求单元 | 关联内容 | 本任务实现 | 归属 / 位置 |
 |---------|---------|-----------|-------------|
-| REQ-xxx | ... | ❌ | 已实现于 commit xxx |
 
 ## Out of Scope
-- <原始文档中明确排除的内容>
+- <原始文档或版本规划中明确排除的内容>
 
 ## Technical Notes
 - 原始文档路径、提取范围、提取时间
+- 版本规划产物路径、Task ID、Wave ID（如有）
 - 关键文件路径（用于 task.json `relatedFiles`）
-- 其他对实现者有用的上下文
 ```
 
-> **关键差异（与旧版对比）**：
-> - 「本任务 TL;DR」和「本任务范围」放在最前面，读者不必翻到文末去找"本任务到底做什么"
-> - 「Requirements」「Acceptance Criteria」改为**索引式**，只写编号 + 一句话摘要 + 原文指针，**不复述原文内容**（原文已经在「来源需求原文」一节完整出现过一次）
-> - 「关联需求」表头增加「本任务实现」列，小节标题明确写⚠️提示
-> - 散射追踪成果归入「关联需求」，不得混入「Requirements」或「Scope ✅」
-
-### Step 6: 创建 task.json
+### Step 6: 创建 / 更新 task.json
 
 PRD 写入后，调用框架脚本创建 `task.json`，使任务目录完整可用：
 
@@ -145,45 +167,66 @@ python3 .trellis/scripts/task.py create "<PRD标题>" \
   --description "<TL;DR「做什么」一句话>"
 ```
 
-> **注意**：
-> - 如果任务目录已由用户手动创建（已有 `prd.md`），脚本会检测到目录已存在并在其中写入 `task.json`
-> - `--slug` 必须与任务目录名的 slug 部分一致，确保 `task.json` 落在正确目录
-> - `--description` 直接复用 TL;DR 的「做什么」字段，保证 task.json 和 PRD 首屏一致
-> - 根据需求性质设置 `--priority`：紧急修复 P0/P1，常规需求 P2，小改动 P3
-> - 创建完成后，根据 PRD 中的分析补充 `task.json` 中的字段：
->   - `dev_type`：`frontend` / `backend` / `fullstack`
->   - `relatedFiles`：PRD Technical Notes 中识别的关键文件路径
+创建完成后，根据 PRD 中的分析补充 `task.json` 中的字段：
+- `dev_type`：`frontend` / `backend` / `fullstack`
+- `relatedFiles`：PRD Technical Notes 中识别的关键文件路径
+- `meta.version_plan`：版本规划产物路径（如有）
+- `meta.wave`：所属 wave id / 名称 / 可提测性（如有）
+- `meta.source_requirements`：来源需求编号和位置（如有）
+
+`meta` 示例：
+
+```json
+{
+  "meta": {
+    "version_plan": "doc/v1.2/任务拆分与waves.md",
+    "wave": {
+      "id": "wave-1",
+      "name": "核心链路首批提测",
+      "testability": "independent"
+    },
+    "source_requirements": [
+      {
+        "id": "REQ-001",
+        "location": "doc/v1.2/需求清单.md:42"
+      }
+    ]
+  }
+}
+```
 
 ### Step 7: 自检
 
 | 检查项 | 方法 |
 |--------|------|
-| **首屏可读性** | 只看 PRD 前 30 行，能否回答"做什么 / 不做什么 / 为什么"三问？不能则 TL;DR 或 Scope 写得不够清楚 |
-| **去重** | 同一条款（如 BR-06、AC-13）是否只在「来源需求原文」一节完整出现？Requirements / AC / 关联需求是否都只有指针不复述？ |
-| **Scope 分离** | 散射追踪发现的"相关但不做"条款是否**全部**落在「❌ 相关但不在本任务范围」或「关联需求」表里？有没有一条漏到 Scope ✅ 里？ |
-| **关联需求列完整** | 「关联需求」表每一行的「本任务实现」列是否都填写（✅/❌/N/A）？ |
-| **原文完整性** | 原始文档中该需求的所有子节是否都出现在「来源需求原文」中 |
+| **首屏可读性** | 只看 PRD 前 30 行，能否回答"做什么 / 不做什么 / 为什么 / 属于哪个 wave" |
+| **去重** | 同一条款是否只在「来源需求原文」一节完整出现 |
+| **Scope 分离** | 散射追踪发现的相关但不做条款是否全部落在非范围或关联需求中 |
+| **关联需求列完整** | 「关联需求」表每一行的「本任务实现」列是否都填写 |
+| **原文完整性** | 原始文档中该 task 范围内的所有子节是否都出现 |
 | **AC 可追溯** | 每条 AC 索引是否都标注了来源位置 |
-| **无自行发挥** | Requirements 索引中是否有任何一条找不到原文依据 |
-| **文案逐字一致** | PRD 中的 UI 文案（按钮、提示语、Toast、弹窗、表头、placeholder）是否与原始文档**完全一致**，无改写/缩略/意译 |
+| **无自行发挥** | Requirements 索引中是否有任何一条找不到原文或版本规划依据 |
+| **文案逐字一致** | UI 文案是否与原始文档完全一致 |
 | **散射完整** | 至少对 2-3 个关键实体做过全文搜索 |
-| **变更性质匹配** | 若判为"局部变更"，TL;DR 的「做什么」是否只描述变更点，而非整个功能的 User Story？ |
+| **任务边界匹配** | 如存在版本规划产物，Scope 是否严格落在 task 候选范围内 |
+| **Wave 匹配** | PRD / `task.json.meta` 的 wave 是否与版本规划一致 |
 
 ---
 
 ## 反模式
 
-- ❌ 用自己的话改写需求（「来源需求原文」节应引用原文；Requirements/AC 索引应指向原文而非复述）
+- ❌ 用自己的话改写需求原文
 - ❌ 需求条目没有标注来源位置
-- ❌ 添加原始文档中不存在的业务规则或验收标准
-- ❌ 跳过某些子节不提取（即使觉得不重要）
+- ❌ 添加原始文档或版本规划中没有的业务规则 / 验收标准
+- ❌ 跳过某些子节不提取
 - ❌ 不做散射追踪
-- ❌ 假设文档有特定格式（每份文档先读结构再处理）
-- ❌ **TL;DR 写成整个功能的 User Story**（局部变更时必须只写变更点）
-- ❌ **Requirements / AC 小节复述原文内容**（应该是索引指针）
-- ❌ **散射追踪结果混入 Scope ✅ 或 Requirements**（散射是上下文，不是工作清单）
-- ❌ **「关联需求」表遗漏「本任务实现」列**（否则读者无法区分做与不做）
-- ❌ **PRD 末尾补一个「任务范围收敛（必读）」块来救场**（说明 Scope 在首屏没写清楚——回头去修 Scope，不要靠末尾补丁）
+- ❌ TL;DR 写成整个功能的 User Story（局部变更时必须只写变更点）
+- ❌ Requirements / AC 小节复述原文内容
+- ❌ 散射追踪结果混入 Scope ✅ 或 Requirements
+- ❌ 有版本规划产物却忽略 task 候选边界，直接按原始需求整段提取成过大的任务
+- ❌ 把一个内聚 task 拆成页面 / 接口 / 字段碎片
+- ❌ 未找到版本规划产物时自行编造 wave id 或 Task ID
+- ❌ 把 wave 当成独立 task 目录或 `task.py` 状态
 
 ---
 
@@ -191,7 +234,7 @@ python3 .trellis/scripts/task.py create "<PRD标题>" \
 
 | 入口 | 形态 | 职责 | 时机 |
 |------|------|------|------|
-| `trellis-plan-version` | skill | 版本级需求扫描 + 覆盖度确认 | 版本规划阶段 |
+| `trellis-plan-version` | skill | 版本级需求扫描 + 内聚 task 拆分 + wave 编排 | 版本规划阶段 |
 | `trellis-brainstorm` | skill（上游） | 对话式需求发现（**无原始文档时**） | 需求模糊时 |
-| `trellis-extract-prd` | skill（本技能） | 基于原始文档**严格提取**单个需求的 PRD + task.json | 任务开发前、有正式需求文档时 |
-| `trellis-verify-task` | skill | 校验任务三件套（prd / design / implement）准确性 + 覆盖度 + 跨层一致性 | PRD / Design / Implement 生成后 |
+| `trellis-extract-prd` | skill（本技能） | 基于原始文档严格提取单个内聚 task 的 PRD；如有版本规划，则绑定 Task ID / Wave / 来源需求 | 任务开发前、有正式需求文档时 |
+| `trellis-verify-task` | skill | 校验任务三件套准确性 + 覆盖度 + 跨层一致性；如有版本规划，则追加版本需求 -> task -> wave 对照 | PRD / Design / Implement 生成后 |

package/enhancements/0.6/.claude/skills/trellis-plan-version/SKILL.md

@@ -1,18 +1,20 @@
 ---
 name: trellis-plan-version
-description: "Generate a version development plan from a source requirements doc: requirements list, effort estimate, and team assignment."
+description: "Generate a version development plan from a source requirements doc: requirements list, cohesive task candidates, waves, effort estimate, and team assignment."
 ---
-# 版本开发计划 — 从需求文档到任务拆分
+# 版本开发计划 — 从需求文档到内聚 Task 与 Waves
 
-从原始需求文档出发，生成版本开发计划（需求清单 + 工时评估 + 人员分工），内置覆盖度校验确保不遗漏需求。
+从原始需求文档出发，生成版本开发计划（需求清单 + 内聚 task 候选 + waves + 工时评估 + 人员分工），内置覆盖度校验，确保不遗漏需求，并让版本结果能按批次提测 / 分批交付。
 
 ---
 
 ## 核心原则
 
-1. **需求文档是唯一真相** — 需求清单必须从文档全文提取，不能只看目录/总表
-2. **先扫后拆** — 先完成覆盖度扫描，确认无遗漏后再做工时评估和分工
-3. **可追溯** — 每个任务可追溯到原始文档的具体位置（行号/章节）
+1. **需求文档是唯一真相** — 需求清单必须从文档全文提取，不能只看目录 / 总表
+2. **先扫后拆** — 先完成覆盖度扫描，确认无遗漏后再拆 task、排 wave、评估工时和分工
+3. **task 必须内聚** — 可以拆多个 task，但每个 task 必须是可开发、可自测、可验收的闭环，不能按章节 / 页面 / 接口机械碎拆
+4. **wave 是版本级批次** — wave 组织 task 的分批提测 / 分批交付，不是 `task.py` 状态，也不强制一个 wave 一个 task
+5. **可追溯** — 每个需求条目必须能追到 task，每个 task 必须能追到 wave 或明确标记为跨 wave 支撑项
 
 ---
 
@@ -23,6 +25,11 @@ description: "Generate a version development plan from a source requirements doc
 - **版本号或迭代标识**
 - **开发团队信息**（人数、角色分工模式）
 
+可选输入：
+- **产物目录**：默认 `doc/<版本>/`；如果用户显式指定路径，以用户指定路径为准
+- **提测策略偏好**：例如先核心链路、先低风险模块、先后端基础能力等
+- **拆分偏好**：例如“尽量少拆 task”“按团队并行拆”“允许 child task”
+
 ---
 
 ## 执行步骤
@@ -57,15 +64,17 @@ description: "Generate a version development plan from a source requirements doc
 - 变更类型：整体新增 / 局部变更 / 字段级嵌入
 
 > **[!] 关键：必须识别出「字段级嵌入变更」。**
-> 有些需求单元整体是旧版本的，但内部某个字段/段落属于新版本变更。
+> 有些需求单元整体是旧版本的，但内部某个字段 / 段落属于新版本变更。
 > 仅看需求单元标题会遗漏这类变更。
 
 #### 1.3 识别散射型变更
 
 检查是否有同一功能点散布在多个需求单元中：
-- 同一字段在不同页面的展示/编辑/导出
+- 同一字段在不同页面的展示 / 编辑 / 导出
 - 同一业务规则在不同入口的复用
-- 标记每组散射变更，确保后续分工时归同一人
+- 同一权限、校验、状态流转、历史数据处理在多个模块重复出现
+
+记录每组散射变更，后续 task 拆分和 wave 编排时必须显式处理。
 
 ### Step 2: 输出需求清单 — 覆盖度确认
 
@@ -86,8 +95,8 @@ description: "Generate a version development plan from a source requirements doc
 
 ### 散射型变更（同一功能点跨多个需求单元）
 
-| 功能点 | 涉及的需求单元 | 建议处理 |
-|--------|--------------|---------|
+| 散射组 | 功能点 | 涉及的需求单元 | 建议处理 |
+|--------|--------|--------------|---------|
 
 ### 需求总表 vs 全文扫描差异
 
@@ -99,42 +108,155 @@ description: "Generate a version development plan from a source requirements doc
 
 **等待用户确认后再继续。**
 
-### Step 3: 工时评估
+### Step 3: Task 拆分 — 生成内聚 task 候选
+
+基于已确认的需求清单，先生成内聚 task 候选。task 可以有多个，但禁止碎拆。
+
+#### 3.1 合并为同一个 task 的信号
+
+优先合并为同一个 task：
+- 属于同一个可验收业务闭环，例如页面 + 接口 + 状态流转 + 导出完整闭环
+- 同一字段、规则、权限、校验或导出链路在多个入口复用
+- 同一散射组内的变更如果拆开会导致重复改同一批文件或难以独立验收
+- 强依赖同一份数据模型、接口契约或迁移脚本
+- 拆开后任一 task 只剩半成品，无法说明自己的验收结果
+
+#### 3.2 拆成多个 task 的信号
+
+可以拆成多个 task：
+- 每个 task 都能独立开发、独立自测、说明验收结果
+- 只有弱依赖，前置 task 提供稳定接口 / 数据后即可并行
+- 技术层差异明显，例如基础迁移、后端契约、前端体验可分阶段完成
+- 风险等级不同，需要先交付低风险或核心链路
+- 多人并行开发时，边界清晰且交集可控
+
+#### 3.3 每个 task 候选必须写清
+
+- task id / 标题
+- ✅ 本 task 范围
+- ❌ 相关但不在本 task 范围
+- 来源需求位置
+- 散射组归属
+- 依赖 task
+- 建议主要 wave
+- 可验收结果 / 可提测性
+- 风险 / 开放问题
+
+#### 3.4 反碎拆检查
 
-基于确认后的需求清单，评估每个需求的工时。
+输出 task 候选后，必须自检：
+- 有没有 task 只对应一个孤立字段、按钮、接口或页面小块？
+- 有没有一个业务闭环被拆成多个互相等待的 task？
+- 有没有同一散射组被拆到不同 task 且没有理由？
+- 有没有 task 完成后无法说明“验收什么”？
+
+这些情况必须合并或解释理由。
+
+### Step 4: Wave 编排 — 分批提测 / 交付
+
+基于 task 候选编排 waves。wave 是版本级批次，用于组织 task 的提测 / 交付顺序。
+
+#### 4.1 Wave 准则
+
+一个 wave 必须写清：
+- wave id / 名称
+- 目标：这一批完成后测试能验什么
+- 包含 task
+- 提测范围
+- 前置条件：依赖哪些 task / 外部系统 / 数据准备
+- 完成条件：哪些验收项通过才算完成
+- 可提测性：可独立提测 / 依赖后续 wave / 仅前置能力
+
+> 如果一批只包含基础设施、迁移、公共组件或接口契约，不能直接标成“可独立提测 wave”。应作为后续 wave 的前置依赖，或并入首个能形成业务验收闭环的 wave。
+
+#### 4.2 输出 task / wave 拆分结果
+
+```markdown
+## <版本> 任务拆分与 Waves
 
-输出表格的列结构**根据项目实际的角色分工来定**（如前端/后端/全栈/测试等），不要预设。
+### 拆分原则
+- <为什么这样合并 / 拆分 task>
+
+### Task 候选列表
+
+| Task ID | Task 名称 | 本 task 范围 | 不在范围 | 来源需求 | 散射组 | 依赖 | 主要 Wave | 可验收结果 | 风险 |
+|---------|-----------|-------------|----------|----------|--------|------|-----------|------------|------|
+
+### Wave 计划
+
+| Wave | 目标 | 包含 task | 提测范围 | 前置条件 | 完成条件 | 可独立提测 |
+|------|------|-----------|----------|----------|----------|------------|
+
+### 需求 -> Task -> Wave 覆盖矩阵
+
+| 需求条目 | 来源位置 | 覆盖 task | 所属 wave | 状态 |
+|----------|----------|-----------|-----------|------|
+
+### 依赖关系
+
+| Task | 依赖 | 被谁依赖 | 说明 |
+|------|------|----------|------|
+
+### 争议 / 待确认
+
+- <需要用户确认的拆分争议、提测顺序或范围边界>
+```
+
+**等待用户确认 task / wave 拆分后再继续工时评估。**
+
+### Step 5: 工时评估
+
+基于确认后的 task / wave 拆分评估工时，而不是只按原始需求单元评估。
+
+输出表格的列结构**根据项目实际的角色分工来定**（如前端 / 后端 / 全栈 / 测试等），不要预设。
 
 评估原则：
 - 如有 AI 编程辅助，标注基准（AI 辅助 vs 纯人工）
 - 复用关系明确标注
 - 优先级以需求文档为准
+- task 的依赖和 wave 的提测顺序必须影响排期
+- 半成品 / 前置能力 task 必须说明它服务哪个 wave
 
-### Step 4: 人员分工
+### Step 6: 人员分工
 
-按模块边界分工，遵循：
+按模块边界、复用链和 wave 提测边界分工，遵循：
 - 复用链归同一人
-- 散射型变更归同一人
-- 尽量无交集
+- 散射型变更归同一人或同一小组
+- 同一 wave 的关键路径要清楚
+- 尽量无交集；有交集时明确接口 / 数据 / 文案 / 测试责任边界
 
 输出分工表和排期建议。
 
-### Step 5: 生成产物文件
+### Step 7: 生成产物文件
 
-在 `doc/` 目录下生成：
+默认在 `doc/<版本>/` 目录下生成：
 
-```
+```text
 doc/
-├── <版本>-需求清单.md            # Step 2 的完整输出（含覆盖度校验）
-├── <版本>-开发计划-工时评估.md    # Step 3 + Step 4
+└── <版本>/
+    ├── 需求清单.md
+    ├── 任务拆分与waves.md
+    └── 开发计划-工时评估.md
 ```
 
+如果用户显式指定产物路径，以用户指定路径为准；后续 `trellis-extract-prd` / `trellis-verify-task` 必须引用这个显式路径。
+
+`任务拆分与waves.md` 是后续单 task PRD 的版本级来源：
+- `trellis-extract-prd` 从其中读取 task 候选、wave、来源需求位置和边界
+- `trellis-verify-task` 用它检查“版本需求 -> task -> wave”的覆盖和边界一致性
+
 ---
 
 ## 反模式
 
 - ❌ 只从需求总表提取需求（会漏掉嵌入式变更）
-- ❌ 跳过覆盖度确认直接做工时评估
-- ❌ 散射型变更分给不同的人
+- ❌ 跳过覆盖度确认直接做 task 拆分或工时评估
+- ❌ 按文档章节机械拆 task
+- ❌ 按页面 / 接口 / 字段碎拆 task，导致一个可验收闭环散落多处
+- ❌ 为避免碎拆而整个版本只建一个过大的 task，导致边界和并行开发失控
+- ❌ 散射型变更分给不同 task 且没有统一归组理由
+- ❌ wave 只按日期、人员或模块排序，没有可提测目标和完成条件
+- ❌ 把只有基础设施 / 迁移 / 公共组件的半成品批次标成可提测 wave
+- ❌ 生成 task / wave 拆分后不等待用户确认，直接做工时评估或创建 task
 - ❌ 假设文档有特定格式或特定的角色分工模式
 - ❌ 当多个来源的优先级冲突时不明确说明以哪个为准