flower-trellis 0.2.3 → 0.2.5-beta.1

package/enhancements/0.6/.agents/skills/trellis-route/SKILL.md

@@ -1,76 +1,158 @@
 ---
 name: trellis-route
 description: |
-  Route trellis-implement / trellis-check execution mode by asking the user to choose inline or subagent.
-  For check, additionally choose between trellis-check (lightweight) and trellis-check-all (comprehensive,
-  default pre-commit). Invoked from Phase 2.1 / 2.2 of the routing-aware workflow. Skip in non-trellis
-  projects (no .trellis/). Not for other subagents (trellis-research / trellis-debug).
+  Route trellis-implement / trellis-check execution mode with a gitignored personal preference file.
+  Implement can route inline or subagent. Check defaults to check-all inline/subagent; lightweight
+  trellis-check is hidden and only available when the user explicitly requests "light check" / "轻量检查".
+  Invoked from Phase 2.1 / 2.2 / 3.1 of the routing-aware workflow. Skip in non-trellis projects
+  (no .trellis/). Not for other subagents (trellis-research / trellis-debug).
 ---
 
 # Trellis 路由器：implement / check 执行模式选择
 
-主 agent 进入 Phase 2.1 / 2.2 时调用本 skill，询问用户选择执行模式（inline / subagent / check-all）后输出执行指令。implement 支持本会话偏好（4h 内连续 dispatch 不重复问）。
+主 agent 进入 Phase 2.1 / 2.2 / 3.1 时调用本 skill，决定 implement / check 的执行模式。核心目标是减少重复打断：正常路由优先读取个人本地配置；用户要求临时改、重新选择或清除默认时，必须绕过配置并重新展示选项。
+
+个人配置只写入 `.trellis/.route-prefs.tmp`。该文件匹配 `.trellis/.gitignore` 的 `*.tmp` 规则，属于开发者本地偏好，不纳入 git，也不影响其他开发者。
+
+---
+
+## Step 0: 识别目标与用户意图
+
+个人 route 配置只决定“已获准执行后的模式”，不是开工授权。读取 `.trellis/.route-prefs.tmp` 前，必须确认当前 workflow 已允许进入对应 target：implement 需要任务已完成规划确认并处于 `in_progress`；check 需要已有本轮实现变更或用户明确要求检查。如果仍在 planning、等待用户确认，或用户表达“等一下 / 我再想想”，停止，不读取个人配置。
+
+先判断本次路由目标：
+
+- `target=implement`：决定 `inline` / `subagent`。
+- `target=check`：普通入口只决定 `check-all inline` / `check-all subagent`。
+- `target=check` 且用户明确说 `light check` / `轻量检查` / `轻量 check`：进入轻量检查隐藏逃生口。
+
+再判断用户是否要求覆盖个人配置：
+
+- 临时改：`临时改` / `这次用` / `本次用` / `这次不用默认` / `override once`
+- 重新选择：`重新选择` / `重选` / `route 选项` / `show route options`
+- 更新默认：`改默认` / `更新默认` / `保存默认`
+- 清除默认：`清除默认` / `删除 route 默认` / `reset route`
+
+如果命中上述覆盖意图，即使 `.trellis/.route-prefs.tmp` 存在，也不能直接使用配置；必须进入 Step 2 展示对应选项。
 
 ---
 
-## Step 1.5: 检查会话偏好（仅 target=implement）
+## Step 1: 读取个人路由配置
+
+仅在没有覆盖意图时读取 `.trellis/.route-prefs.tmp`。
+
+配置格式是简单 key-value 文本：
 
-读 `.trellis/.route-prefs.tmp`（4h mtime 内有效）：
+```text
+implement=inline
+check=check-all-inline
+```
+
+允许值：
+
+- `implement`: `inline` / `subagent`
+- `check`: `check-all-inline` / `check-all-subagent`
+
+读取参考：
 
 ```bash
 PREF_FILE=".trellis/.route-prefs.tmp"
 if [ -f "$PREF_FILE" ]; then
-  MTIME=$(stat -c %Y "$PREF_FILE" 2>/dev/null || stat -f %m "$PREF_FILE" 2>/dev/null)
-  if [ -n "$MTIME" ] && [ $(( $(date +%s) - MTIME )) -lt 14400 ]; then
-    cat "$PREF_FILE"
-  else
-    rm -f "$PREF_FILE"
-  fi
+  IMPLEMENT_PREF=$(awk -F= '$1=="implement"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1)
+  CHECK_PREF=$(awk -F= '$1=="check"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1)
 fi
 ```
 
-输出 `inline` 或 `subagent` → **跳过 Step 2**，直接 Step 3 按记忆走，输出指令前加一行 `📌 来自本会话偏好（4h 内不再问；rm .trellis/.route-prefs.tmp 可重置）`。
+规则：
 
-target=check **跳过本步**，每次都询问。
+- `target=implement` 且 `IMPLEMENT_PREF` 是 `inline` / `subagent`：跳过 Step 2，进入 Step 3。
+- `target=check` 且 `CHECK_PREF` 是 `check-all-inline` / `check-all-subagent`：跳过 Step 2，进入 Step 3。
+- 配置缺失、值不合法、目标 key 缺失：忽略配置，进入 Step 2。
+- 文件损坏严重时可删除 `.trellis/.route-prefs.tmp`，然后进入 Step 2。
 
-## Step 1.7: 上下文判断与推荐（无偏好命中时强制执行）
+配置命中时，输出指令必须写明：
 
-Step 1.5 未命中偏好时，主 agent 在调用 `AskUserQuestion` **之前**必须基于当前任务上下文做一次判断，**自己**挑出最合适的选项并写 1-2 句中文推荐理由。**SKILL.md 不硬编码"哪个是推荐项"也不限定判断维度——主 agent 用自己的判断力。**
+```markdown
+来自个人 route 配置：`.trellis/.route-prefs.tmp` (<key>=<value>)。
+如需临时改或重新显示选项，说“route 重新选择”“这次用 subagent”“清除 route 默认”等。
+```
 
-将推荐选项编号 + 1-2 句中文理由作为 Step 2 `question` 字段的**首句**，例如：
+---
 
-- implement: "任务只改 1 个 vue 文件且 PRD 清晰，建议 #1 inline。本次 implement 走哪种模式？"
-- check: "改动跨前后端 + DB 且即将提交，建议 #1 check-all inline。本次 check 走哪种模式？"
+## Step 2: 展示选项并等待用户选择
 
-option label 里**不写"（推荐）"后缀**——推荐落点通过 question 文案体现，用户能看到判断依据并否决。
+优先调用 `AskUserQuestion`。选项 label 前缀编号，方便用户直接打数字快速选。
 
-## Step 2: 询问用户
+如果当前平台或模式没有 `AskUserQuestion` / `request_user_input`，不要自行选择 inline 或 subagent 继续。改用普通聊天消息原样呈现同一组编号选项，并停止等待用户回复；用户回复数字后再进入 Step 2.5 / 2.6 / 3。
 
-优先调用 `AskUserQuestion`。**选项 label 前缀 1/2/3/4，方便用户直接打数字快速选**。`question` 字段首句必须是 Step 1.7 输出的推荐理由（1-2 句中文），**不可省略**。
+### target = implement，且无可用配置
 
-如果当前平台或模式没有 `AskUserQuestion` / `request_user_input`，不要选择 inline 或 subagent 继续。改用普通聊天消息原样呈现同一组编号选项，并停止等待用户回复；用户回复数字后再进入 Step 2.5 / 2.6 / 3。禁止写"request_user_input 当前不可用，所以记录为 inline/subagent 路径并继续"。
+- **question**: "本次 implement 走哪种模式？"
+- **header**: "Impl 模式"
+- **options**:
+  1. label "1. 本次 Inline", description "主 agent 直接执行，只影响这一次"
+  2. label "2. 本次 Subagent", description "dispatch trellis-implement，只影响这一次"
+  3. label "3. 保存默认：Inline", description "本次使用 inline，并写入个人配置，后续默认不再问"
+  4. label "4. 保存默认：Subagent", description "本次使用 subagent，并写入个人配置，后续默认不再问"
 
-### target = implement（4 选项）
+### target = implement，且用户要求临时改 / 重新选择
 
-- **question**: "[Step 1.7 推荐理由 1-2 句] 本次 implement 走哪种模式？"
-- **header**: "Impl 模式"
+- **question**: "当前默认：implement=<当前值或无>。本次要怎么处理？"
+- **header**: "Impl 覆盖"
 - **options**:
-  1. label "1. Inline", description "本次主 agent 直接执行，更快，共享上下文"
-  2. label "2. Subagent", description "本次 dispatch 子 agent，隔离独立思考"
-  3. label "3. Inline 本会话", description "本次 + 4h 内所有 implement 都 inline，不再问"
-  4. label "4. Subagent 本会话", description "本次 + 4h 内所有 implement 都 dispatch 子 agent，不再问"
+  1. label "1. 仅本次 Inline", description "只覆盖这一次，不修改个人配置"
+  2. label "2. 仅本次 Subagent", description "只覆盖这一次，不修改个人配置"
+  3. label "3. 更新默认为 Inline", description "本次使用 inline，并写入个人配置"
+  4. label "4. 更新默认为 Subagent", description "本次使用 subagent，并写入个人配置"
+  5. label "5. 清除默认", description "删除 implement 默认，然后重新显示无配置选项"
+
+### target = check，且无可用配置
 
-### target = check（4 选项）
+普通 check 路由不展示轻量 `trellis-check`。
 
-- **question**: "[Step 1.7 推荐理由 1-2 句] 本次 check 走哪种模式？"
+- **question**: "本次 check 走哪种模式？"
 - **header**: "Check 模式"
 - **options**:
-  1. label "1. Check-all inline", description "全面检查（PRD 对照 + 5 维 + spec），主 agent 执行"
-  2. label "2. Check-all subagent", description "全面检查，dispatch 子 agent"
-  3. label "3. Check inline", description "轻量检查（lint/type/spec），主 agent 执行"
-  4. label "4. Check subagent", description "轻量检查，dispatch 子 agent"
+  1. label "1. 本次 Check-all inline", description "主 agent 执行全面检查，只影响这一次"
+  2. label "2. 本次 Check-all subagent", description "dispatch 全面检查，只影响这一次"
+  3. label "3. 保存默认：Check-all inline", description "本次使用 check-all inline，并写入个人配置"
+  4. label "4. 保存默认：Check-all subagent", description "本次使用 check-all subagent，并写入个人配置"
+
+### target = check，且用户要求临时改 / 重新选择
 
-## Step 2.5: 读 subagent_skip_compile（仅 implement + subagent 时）
+普通选项仍只展示 `check-all` 路径。
+
+- **question**: "当前默认：check=<当前值或无>。本次要怎么处理？"
+- **header**: "Check 覆盖"
+- **options**:
+  1. label "1. 仅本次 Check-all inline", description "只覆盖这一次，不修改个人配置"
+  2. label "2. 仅本次 Check-all subagent", description "只覆盖这一次，不修改个人配置"
+  3. label "3. 更新默认为 Check-all inline", description "本次使用 check-all inline，并写入个人配置"
+  4. label "4. 更新默认为 Check-all subagent", description "本次使用 check-all subagent，并写入个人配置"
+  5. label "5. 清除默认", description "删除 check 默认，然后重新显示无配置选项"
+
+### target = check，且用户明确请求轻量检查
+
+轻量 `trellis-check` 是隐藏逃生口，不写入个人默认。
+
+如果用户已经明确 inline / subagent：
+
+- `轻量检查 inline` / `light check inline` → 直接输出 `inline check`
+- `轻量检查 subagent` / `light check subagent` → 直接输出 `subagent check`
+
+如果用户只说轻量检查但未指定执行方式：
+
+- **question**: "用户明确请求轻量检查。本次轻量 check 走哪种模式？"
+- **header**: "轻量 Check"
+- **options**:
+  1. label "1. 轻量 Check inline", description "主 agent 执行 trellis-check，只影响这一次"
+  2. label "2. 轻量 Check subagent", description "dispatch trellis-check，只影响这一次"
+
+---
+
+## Step 2.5: 读 subagent_skip_compile
+
+仅 `target=implement` 且最终选择 `subagent` 时读取：
 
 ```bash
 if [ -f .trellis/config.yaml ]; then
@@ -78,20 +160,41 @@ if [ -f .trellis/config.yaml ]; then
 fi
 ```
 
-为 `true` 时，Step 3 的 implement subagent 指令会附加"跳过编译"prompt 段。其他路径不读此配置。
+为 `true` 时，Step 3 的 implement subagent 指令会附加“跳过编译”prompt 段。其他路径不读此配置。
+
+---
+
+## Step 2.6: 写入或清除个人配置
+
+选项含“保存默认”或“更新默认”时，更新 `.trellis/.route-prefs.tmp`。写入时保留另一个 target 的偏好；没有另一个 target 时只写当前 key。
 
-## Step 2.6: 持久化偏好（仅 implement 选项 3/4 时）
+推荐写法：
 
 ```bash
+PREF_FILE=".trellis/.route-prefs.tmp"
 mkdir -p .trellis
-# 选项 3 (Inline 本会话)
-echo "inline" > .trellis/.route-prefs.tmp
+OLD_IMPLEMENT=$(awk -F= '$1=="implement"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1)
+OLD_CHECK=$(awk -F= '$1=="check"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1)
 
-# 选项 4 (Subagent 本会话)
-echo "subagent" > .trellis/.route-prefs.tmp
+# 按用户选择覆盖其中一个值：
+# NEW_IMPLEMENT="inline" 或 "subagent" 或沿用 "$OLD_IMPLEMENT"
+# NEW_CHECK="check-all-inline" 或 "check-all-subagent" 或沿用 "$OLD_CHECK"
+
+{
+  [ -n "$NEW_IMPLEMENT" ] && printf 'implement=%s\n' "$NEW_IMPLEMENT"
+  [ -n "$NEW_CHECK" ] && printf 'check=%s\n' "$NEW_CHECK"
+} > "$PREF_FILE"
 ```
 
-文件名 `.tmp` 后缀被 trellis `.gitignore` 默认 `*.tmp` 规则自动忽略，无需额外配置。选项 1/2 不写文件。
+清除默认时：
+
+- 清除 implement 默认：只移除 `implement=...`，保留 `check=...`。
+- 清除 check 默认：只移除 `check=...`，保留 `implement=...`。
+- 如果文件最终为空，删除 `.trellis/.route-prefs.tmp`。
+
+不要把 `.trellis/.route-prefs.tmp` 纳入任何提交计划。
+
+---
 
 ## Step 3: 输出执行指令
 
@@ -99,61 +202,62 @@ echo "subagent" > .trellis/.route-prefs.tmp
 
 ### 路由表
 
-| 用户选择 | 主 agent 应执行 |
+| 路由决定 | 主 agent 应执行 |
 |---------|----------------|
-| **inline implement**（选项 1 或 3，或来自偏好） | `Skill({skill: "trellis-before-dev"})` 加载 spec → 读 prd.md → 主线程实施 → 跑 lint/type-check |
-| **subagent implement**（选项 2 或 4，或来自偏好） | `Agent({subagent_type: "trellis-implement"})`；若 `subagent_skip_compile=true`，dispatch prompt 附加"跳过 mvn install / npm run build / tsc 等耗时编译类检查（已由主 agent 验证或最终统一执行）" |
-| **inline check**（选项 3） | `Skill({skill: "trellis-check"})` |
-| **inline check-all**（选项 1） | `Skill({skill: "trellis-check-all"})` |
-| **subagent check**（选项 4） | `Agent({subagent_type: "trellis-check"})` |
-| **subagent check-all**（选项 2） | 优先 `Agent({subagent_type: "trellis-check-all"})`；不存在时 fallback `Agent({subagent_type: "trellis-check"})` + dispatch prompt 含 trellis-check-all 全流程要求（PRD 对照 → 5 维断言 → 跨层 → 委托 trellis-check 收尾） |
+| `inline implement` | `Skill({skill: "trellis-before-dev"})` 加载 spec → 读任务文档 → 主线程实施 → 跑必要验证 |
+| `subagent implement` | `Agent({subagent_type: "trellis-implement"})`；若 `subagent_skip_compile=true`，dispatch prompt 附加“跳过 mvn install / npm run build / tsc 等耗时编译类检查（已由主 agent 验证或最终统一执行）” |
+| `inline check-all` | `Skill({skill: "trellis-check-all"})` |
+| `subagent check-all` | 优先 `Agent({subagent_type: "trellis-check-all"})`；不存在时 fallback `Agent({subagent_type: "trellis-check"})` + dispatch prompt 含 trellis-check-all 全流程要求（PRD 对照 → 5 维断言 → 跨层 → 委托 trellis-check 收尾） |
+| `inline check` | 仅轻量检查隐藏逃生口；`Skill({skill: "trellis-check"})` |
+| `subagent check` | 仅轻量检查隐藏逃生口；`Agent({subagent_type: "trellis-check"})` |
 
 ### 输出模板
 
 ```markdown
-路由决定：<inline/subagent> <implement | check | check-all>
-[📌 来自本会话偏好（4h 内不再问；rm .trellis/.route-prefs.tmp 可重置）]
+路由决定：<inline/subagent> <implement | check-all | check>
+[来自个人 route 配置：`.trellis/.route-prefs.tmp` (<key>=<value>)。]
+[说明：用户明确请求轻量检查，使用隐藏逃生口。]
 
 接下来主 agent 应当：
 - <路由表里对应的工具调用形式>
-- [若 implement subagent 且 subagent_skip_compile=true：附加"跳过编译"prompt 段]
+- [若 implement subagent 且 subagent_skip_compile=true：附加“跳过编译”prompt 段]
 
 不要：
 - <要避免的工具调用>
 ```
 
-中括号内行为条件性出现：仅命中本会话偏好时显示第二行；仅 implement subagent + skip_compile=true 时附加"跳过编译"段。
+中括号内行为条件性出现：仅命中个人配置时显示配置行；仅轻量 check 时显示隐藏逃生口说明；仅 implement subagent + skip_compile=true 时附加“跳过编译”段。
 
 ---
 
 ## 核心原则
 
-1. **决策与执行分离**：本 skill 只输出指令，下一轮由主 agent 调工具
-2. **严格执行用户选择**：路由结论一旦输出，主 agent 必须按指令执行，不可"出于谨慎"再换路径
-3. **无偏好命中必问，无自动 fallback**：Step 1.5 未命中偏好时，Step 2 询问是强制步骤；缺工具/权限时必须退化为普通聊天询问并等待用户回复，**不是**绕过询问或自行选择路径的合法理由
-4. **推荐由主 agent 上下文判断生成**（Step 1.7），不在 SKILL.md 里硬编码"哪个是推荐项"——避免静态偏好和当下任务实际不匹配
-5. **本会话偏好仅 implement 适用**：check 每次询问（避免累积偏好导致提交前漏跑 check-all）
-6. **config 联动仅 implement subagent 路径**：`subagent_skip_compile` 仅在 target=implement + 选 subagent 时读取并注入 prompt
+1. **个人配置私有**：`.trellis/.route-prefs.tmp` 是本地偏好，gitignored，不能进入提交计划。
+2. **正常路由少打断**：命中个人配置时直接输出路由决定，不再重复询问。
+3. **显式覆盖优先于配置**：用户要求临时改、重新选择或清除默认时，必须重新展示选项，不能让配置优先。
+4. **check 默认全面检查**：普通 check 路由只展示 `check-all` inline/subagent，不推荐轻量 `trellis-check`。
+5. **轻量 check 是隐藏逃生口**：只有用户明确请求 `light check` / `轻量检查` 时才可走轻量 `trellis-check`。
+6. **决策与执行分离**：本 skill 只输出指令，下一轮由主 agent 调工具。
+7. **严格执行用户选择**：路由结论一旦输出，主 agent 必须按指令执行，不可“出于谨慎”再换路径。
 
 ---
 
 ## 反模式
 
-- ❌ 本 skill 内部直接调用 `Agent` / `Skill` 工具（违反"决策与执行分离"）
-- ❌ 自行编造"工具/权限/平台不支持子代理"等理由跳过 Step 2 询问（**无偏好命中时必须询问用户**；交互工具不可用时用普通聊天询问并等待，不能绕过路由）
-- ❌ `AskUserQuestion` / `request_user_input` 不可用时，记录为 inline 或 subagent 路径并继续
-- ❌ Step 1.7 推荐理由空着、随便写一句敷衍、或不放进 question 文案（推荐必须基于当前任务的具体上下文，给用户可判断依据）
-- ❌ check 端默认降级到轻量 trellis-check，特别是 pre-commit Phase 3.1（除非 Step 1.7 已显式说明"改动仅 lint/重命名级别"才走 check）
-- ❌ check-all 选项被错误降级为普通 trellis-check（必须优先 trellis-check-all skill / subagent）
-- ❌ 给 check 任何模式附加"跳过编译"指令（check 的核心职责就是跑编译/typecheck）
-- ❌ 询问后忽视用户答案默认 subagent
-- ❌ check 端读 `.route-prefs.tmp`（仅 implement 适用本会话偏好）
-- ❌ implement 偏好命中后还询问用户（违反"4h 内不再问"承诺）
+- 在本 skill 内部直接调用 `Agent` / `Skill` 工具。
+- 用户要求临时改 / 重新选择时，仍直接使用 `.trellis/.route-prefs.tmp`。
+- 把 `.trellis/.route-prefs.tmp` 加入 git 暂存或提交计划。
+- 在普通 check 选项里展示 `Check inline` / `Check subagent`。
+- 没有用户明确请求时，把 check 降级到轻量 `trellis-check`。
+- `AskUserQuestion` / `request_user_input` 不可用时，记录为 inline 或 subagent 路径并继续。
+- 给 check 任何模式附加“跳过编译”指令。
+- 询问后忽视用户答案默认 subagent。
 
 ---
 
 ## 边界
 
-- **非 trellis 项目**（无 `.trellis/`）：输出"非 trellis 项目，跳过路由"，不阻断流程
-- **config.yaml 缺失或字段缺失**：视为 false，不附加跳过编译指令
-- **.route-prefs.tmp 内容损坏**（非 inline/subagent）：忽略偏好，删除文件，正常询问
+- **非 trellis 项目**（无 `.trellis/`）：输出“非 trellis 项目，跳过路由”，不阻断流程。
+- **config.yaml 缺失或字段缺失**：视为 false，不附加跳过编译指令。
+- **.route-prefs.tmp 内容损坏**：忽略偏好；必要时删除该文件并重新展示选项。
+- **旧单值偏好**：文件内容只有 `inline` / `subagent` 时视为无效配置，按无配置处理并重新展示选项。

package/enhancements/0.6/.agents/skills/trellis-verify-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trellis-verify-task
-description: "Audit task planning artifacts (prd.md, plus design.md and implement.md when present) against the original requirements doc AND across layers via forward checks + reverse coverage scans + cross-layer consistency; flag missing/misinterpreted/embellished/UI-copy-mismatch/cross-layer-drift items and propose ONE consolidated edit list. Triggers: 「校验任务」「校验三件套」「对照原始需求」「verify task spec」「verify task」. Not for PRD generation (trellis-brainstorm/trellis-extract-prd) or implementation-vs-spec check (trellis-check-all)."
+description: "Audit task planning artifacts (prd.md, plus design.md and implement.md when present) against the original requirements doc AND across layers via forward checks + reverse coverage scans + cohesive task boundary + version wave consistency; flag missing/misinterpreted/embellished/UI-copy-mismatch/cross-layer-drift items and propose ONE consolidated edit list. Triggers: 「校验任务」「校验三件套」「对照原始需求」「verify task spec」「verify task」. Not for PRD generation (trellis-brainstorm/trellis-extract-prd) or implementation-vs-spec check (trellis-check-all)."
 ---
 # 校验任务 — 三件套统一校验
 
@@ -8,6 +8,7 @@ description: "Audit task planning artifacts (prd.md, plus design.md and implemen
 
 - **Lightweight 任务**（只有 `prd.md`）：仅做 PRD 准确性 + 覆盖度校验
 - **Complex 任务**（含 `design.md` 和/或 `implement.md`）：在上述基础上追加 PRD↔Design / Design↔Implement / 跨层一致性三道校验
+- **版本规划任务**（存在 `doc/<版本>/任务拆分与waves.md` 或 PRD / `task.json.meta.version_plan` 指向版本规划产物）：在单 task 校验之外，追加“版本需求 -> 内聚 task -> wave”覆盖度、粒度和边界校验
 
 发现的所有偏差**一次性汇总**为一份完整修正清单，获得用户**单次确认**后批量更新，不分层逐次确认。
 
@@ -23,6 +24,9 @@ description: "Audit task planning artifacts (prd.md, plus design.md and implemen
 6. **版本变更全覆盖** — 原始需求中属于本次版本的所有变更内容都必须被某个任务/PRD 覆盖，不得遗漏
 7. **跨层不可发明** — 下层（Design / Implement）不得引入上层（PRD）未提及的需求或行为；只能引入"实现上必需的技术决策"，并标注"实现必需"原因
 8. **修正清单一次性给完整** — 不要边发现边改，也不要按层分次请用户确认。一次扫完，一次给清单，一次确认，一次落盘
+9. **版本规划不替代原始需求** — 版本规划产物用于校验 task 边界、wave 归属和覆盖矩阵；原始需求文档仍是需求内容和文案的最终权威
+10. **task 必须是内聚闭环** — 一个版本可以拆多个 task，但每个 task 必须可开发、可自测、可验收；不能按章节 / 页面 / 接口 / 字段机械碎拆，也不能把整个版本塞进一个过大的 task
+11. **wave 是版本级批次** — wave 用来组织多个内聚 task 的分批提测 / 分批交付，不是 `task.py` 状态，也不强制一个 wave 对应一个 task
 
 ---
 
@@ -31,6 +35,7 @@ description: "Audit task planning artifacts (prd.md, plus design.md and implemen
 - 任务三件套刚写完，尚未进入开发，需要对照原始需求文档做正反双向核对
 - 需求文档更新后，想确认 PRD / Design / Implement 是否仍完整反映了最新版本的所有变更
 - 多任务 / 多 PRD 并行时，怀疑某次版本变更被漏挂到任何任务下
+- 已通过 `trellis-plan-version` 生成版本级内聚 task 候选和 wave 编排，想确认单 task PRD 与版本规划是否一致
 - 怀疑 Design 或 Implement 跟 PRD 漂移（命名、边界、UI 文案任一不一致）
 
 ---
@@ -56,7 +61,11 @@ python3 ./.trellis/scripts/task.py list
 
 ### Step 2: 获取原始需求文档
 
-**必须主动获取原始需求文档来源**。按以下优先级查找：
+**必须主动获取原始需求文档来源**。同时检查是否存在版本规划产物。
+
+#### 2.1 获取原始需求文档
+
+按以下优先级查找：
 
 1. **任务目录下的附件** — 检查任务目录下是否有 `requirements.md`、`spec.md`、`需求.md`、`*.xlsx`、`*.pdf` 等文件
 2. **PRD 中的引用链接 / Technical Notes** — 检查 PRD 头部 `> 来源:` 行或 Technical Notes 中是否引用了外部文档路径
@@ -72,6 +81,27 @@ python3 ./.trellis/scripts/task.py list
 
 > **[!] 严禁在没有原始需求文档的情况下进行 Step 3 / 3.5 校验** — 没有参照物的校验没有意义。Step 4 / 5 / 6 是内部一致性校验，不强依赖原始文档，但仍推荐先有原始文档以便交叉印证。
 
+#### 2.2 获取版本规划产物（如有）
+
+按以下优先级查找：
+
+1. **`task.json.meta.version_plan`** — 如果当前 task 写了版本规划路径，优先使用
+2. **PRD 的「版本规划上下文」或 Technical Notes** — 查找 `版本规划`、`version_plan`、`任务拆分与waves.md`
+3. **默认路径** — 根据版本号尝试 `doc/<版本>/任务拆分与waves.md`
+4. **用户提供** — 如果用户明确要做版本级校验但上述都没有，询问版本规划产物路径
+
+如果版本规划产物存在，读取其中：
+- task 候选列表
+- 每个 task 的范围、非范围、来源需求、散射组、依赖、可验收结果
+- wave 计划
+- 覆盖度矩阵
+- 依赖关系
+- 争议 / 待确认
+
+如果版本规划产物不存在：
+- 跳过 Step 3.6
+- 不要编造 wave 或 task 候选
+
 ### Step 3: 原始需求 ↔ prd.md（正向准确性校验）
 
 将原始需求文档分解为独立条目（逐个需求点 / AC / 功能点），然后逐条在 `prd.md` 中查找对应描述。
@@ -126,6 +156,79 @@ Step 3.5 是**反向检查**（原始文档里本次版本的变更 → PRD 里
 > **特别注意散射型变更**：同一个功能点可能散布在多个需求单元中。
 > 即使主需求已覆盖，也要检查所有关联位置。
 
+### Step 3.6: 版本规划覆盖校验（存在版本规划产物时）
+
+当存在 `doc/<版本>/任务拆分与waves.md` 或显式版本规划产物时，追加版本级对照。
+
+校验目标不是让 task 数量越多越好，也不是把版本压成一个 task；目标是确认版本需求被拆成若干内聚、可验收、可编排到 wave 的 task。
+
+#### 3.6.0 task 粒度与内聚性
+
+逐个读取 task 候选，检查它是否是合理的开发闭环：
+
+| 检查项 | 说明 |
+|--------|------|
+| **内聚闭环** | task 是否围绕同一业务或技术闭环，而不是多个无关模块拼盘 |
+| **不过散** | task 是否只剩孤立字段、按钮、页面小块、接口小块或文档章节切片 |
+| **不过大** | task 是否横跨多个可独立开发 / 验收的闭环，导致边界、并行和验收失控 |
+| **闭环未被拆散** | 页面、接口、数据、状态流转、导出、权限等同一闭环是否被拆到多个互相等待的 task |
+| **散射组归组合理** | 同一字段 / 规则 / 权限 / 校验 / 导出链路是否归到同一 task，或同一 wave 下有明确边界 |
+| **可验收结果明确** | task 完成后是否能说明“测试验什么” |
+
+判定规则：
+- 只对应文档章节、单个页面、单个接口、单个字段、单个按钮，且不能独立验收 → 标记 🔴 过散
+- 横跨多个互不相关业务域，且可自然拆成多个独立闭环 → 标记 🔴 过大
+- 同一业务闭环被拆成多个 task，任一 task 单独完成都是半成品 → 标记 🔴 闭环被拆散
+- task 边界合理但依赖 / 非范围 / 验收结果未写清 → 标记 ⚠️ 边界不清
+
+#### 3.6.1 版本需求 -> task 覆盖
+
+逐条读取版本规划产物的覆盖度矩阵和 task 候选列表，检查：
+
+| 检查项 | 说明 |
+|--------|------|
+| **需求已覆盖** | 每个版本需求条目都至少归属一个 task |
+| **需求未覆盖** | 覆盖度矩阵中无 task，或 task 候选列表没有对应范围 |
+| **重复覆盖** | 多个 task 覆盖同一需求，但没有明确主次 / 边界 |
+| **散射组完整** | 同一散射组是否被同一个 task 或同一个 wave 有意识地归组 |
+| **覆盖粒度合理** | 覆盖 task 是否是内聚闭环，而不是把一个需求拆成不可验收的碎片 |
+
+#### 3.6.2 task -> wave 覆盖
+
+逐个检查 task 候选：
+
+| 检查项 | 说明 |
+|--------|------|
+| **已归 wave** | task 出现在某个 wave 的包含 task 中 |
+| **未归 wave** | task 没有任何 wave 归属 |
+| **半成品标注** | 不可独立提测 task 是否说明依赖哪个 wave |
+| **依赖一致** | wave 前置条件是否覆盖 task 依赖 |
+
+#### 3.6.3 wave 可提测性
+
+逐个检查 wave：
+
+| 检查项 | 说明 |
+|--------|------|
+| **提测目标明确** | 说明这一批完成后测试能验什么 |
+| **前置条件明确** | 列出依赖 task、外部系统、数据准备 |
+| **完成条件明确** | 有可判断的验收 / 完成标准 |
+| **不是半成品批次** | 只有基础设施、迁移、公共组件或接口契约的批次不得标为可独立提测 |
+
+#### 3.6.4 单 task PRD 与版本规划边界一致
+
+如果当前校验的是单个 task：
+
+| 检查项 | 说明 |
+|--------|------|
+| **PRD 指向正确 task 候选** | PRD / `task.json.meta` 的 task 候选、wave、来源需求能在版本规划产物中找到 |
+| **Scope 不越界** | PRD 的 ✅ 本任务实现不超过版本规划中 task 候选范围 |
+| **Scope 不碎化** | PRD 没有只截取版本规划 task 候选中的页面 / 接口 / 字段碎片，除非版本规划明确允许 |
+| **非范围一致** | PRD 的 ❌ 不在范围覆盖版本规划中明确排除的内容 |
+| **来源需求一致** | `source_requirements` 与版本规划覆盖矩阵一致 |
+
+> Step 3.6 的输出必须进入统一报告。不要因为单 task PRD 通过了原始需求校验，就跳过版本级 task / wave 边界校验。
+
 ### Step 4: prd.md ↔ design.md（仅 Complex 任务）
 
 #### 4.1 正向：Design 中每个设计点能否回溯到 PRD
@@ -244,6 +347,38 @@ Step 3.5 是**反向检查**（原始文档里本次版本的变更 → PRD 里
 
 ---
 
+### 二点五、版本规划覆盖校验（存在版本规划产物时）
+
+#### 2.5.0 task 粒度和内聚性
+- ✅ 内聚: X ｜ 🔴 过散: X ｜ 🔴 过大: X ｜ ⚠️ 边界不清: X
+
+| Task | 范围摘要 | 主要 Wave | 状态 | 问题 |
+|------|----------|-----------|------|------|
+
+#### 2.5.1 版本需求 -> task
+- ✅ 已覆盖: X ｜ 🔴 未覆盖: X ｜ ⚠️ 重复 / 边界不清: X
+
+| 需求条目 | 来源位置 | 覆盖 task | 状态 | 问题 |
+|----------|----------|-----------|------|------|
+
+#### 2.5.2 task -> wave
+- ✅ 已归 wave: X ｜ 🔴 未归 wave: X ｜ ⚠️ 半成品标注不清: X
+
+| Task | Wave | 单 task 可提测 | 状态 | 问题 |
+|------|------|---------------|------|------|
+
+#### 2.5.3 wave 可提测性
+- ✅ 可独立提测: X ｜ 🔴 不可提测却标为可提测: X ｜ ⚠️ 条件不清: X
+
+| Wave | 提测目标 | 前置条件 | 完成条件 | 状态 |
+|------|----------|----------|----------|------|
+
+#### 2.5.4 当前 PRD 与版本规划边界
+| 检查项 | PRD / task.json | 版本规划 | 状态 |
+|--------|-----------------|----------|------|
+
+---
+
 ### 三、prd.md ↔ design.md（仅 Complex）
 
 #### 3.1 正向（Design → PRD）
@@ -300,7 +435,8 @@ Step 3.5 是**反向检查**（原始文档里本次版本的变更 → PRD 里
 ### prd.md
 1. **<需求点>**（Step 3 ❌ 曲解）: <原 PRD 内容> → <修正后内容>
 2. **<需求点>**（Step 3.5 🔴 缺失）: 补充章节 ... → <建议内容>
-3. ...
+3. **<版本规划边界>**（Step 3.6 ❌ Scope 越界）: <PRD 当前 Scope> → <版本规划允许范围>
+4. ...
 
 ### design.md
 1. **<设计单元>**（Step 4.1 ❌ 越界）: 删除 ... 段落
@@ -316,6 +452,10 @@ Step 3.5 是**反向检查**（原始文档里本次版本的变更 → PRD 里
 
 ### 补任务建议（不在本任务范围）
 - <未覆盖的变更> — 建议挂到任务 <name> 或新建任务
+- <过散 task> — 建议与 <相关 task> 合并为一个可验收闭环
+- <过大 task> — 建议按 <业务闭环 / 复用链 / wave 提测边界> 拆成多个内聚 task
+- <版本规划中未归 wave 的 task> — 建议补 wave 归属或标记为某 wave 前置依赖
+- <不可独立提测的 wave> — 建议拆分 / 合并 wave 或补前置条件
 
 ---
 
@@ -344,6 +484,14 @@ Step 3.5 是**反向检查**（原始文档里本次版本的变更 → PRD 里
 - ❌ 覆盖度扫描只看需求总表/目录，不扫描全文（嵌入式变更会遗漏）
 - ❌ 假设需求文档有固定的变更标记格式（每份文档结构可能不同）
 - ❌ 只追踪主需求单元，忽略同一功能点在其他页面/模块的散射变更
+- ❌ 有版本规划产物却不做 Step 3.6，导致 task / wave 漏覆盖或 PRD Scope 越界
+- ❌ 把版本规划产物当成原始需求权威，忽略原始需求文档和 UI 文案逐字一致要求
+- ❌ 把 task 数量当目标，按章节 / 页面 / 接口 / 字段机械碎拆
+- ❌ 为避免碎拆，把整个版本塞进一个过大的 task，导致多人协作和阶段验收失控
+- ❌ 单 task PRD 只截取了版本规划 task 候选中的一个页面 / 接口 / 字段碎片，却没有回到版本规划调整 task 边界
+- ❌ wave 当成 task 拆分依据，强制一个 wave 一个 task，或把一个 task 当成完整 wave
+- ❌ wave 只看时间顺序，不检查提测目标、前置条件、完成条件
+- ❌ 发现 task 未归 wave 后直接替用户补 wave，不先输出修正清单确认
 - ❌ Lightweight 任务硬跑 Step 4 / 5 / 6（没有 design / implement 跑不了）
 - ❌ 把 Design / Implement 中的「实现必需」决策当作越界（凡标注了理由的"实现必需"都是合规的 🟡，不是 ❌）
 - ❌ 跨层一致性只校验三个 .md 中的两个（命名 / 文案 / 边界都必须三层全扫）
@@ -355,6 +503,7 @@ Step 3.5 是**反向检查**（原始文档里本次版本的变更 → PRD 里
 | 入口 | 形态 | 用途 | 时机 |
 |------|------|------|------|
 | `trellis-brainstorm` | skill（上游） | 从模糊想法对话生成 PRD（无原始文档时） | 需求讨论阶段 |
-| `trellis-extract-prd` | skill | 从原始需求文档**严格提取** PRD + task.json | 任务开发前、有正式需求文档时 |
-| `trellis-verify-task` | skill（本技能） | 校验任务三件套（prd / design / implement）准确性 + 覆盖度 + 跨层一致性 | 三件套生成后、开发前 |
+| `trellis-plan-version` | skill | 从原始需求文档生成版本级需求清单 + 内聚 task 候选 + wave 编排 + 工时评估 | 版本规划阶段 |
+| `trellis-extract-prd` | skill | 从原始需求文档**严格提取** PRD + task.json；如有版本规划，则绑定 task 候选 / wave / 来源需求 | 任务开发前、有正式需求文档时 |
+| `trellis-verify-task` | skill（本技能） | 校验任务三件套准确性 + 覆盖度 + 跨层一致性；如有版本规划，则追加版本需求 -> task -> wave 对照 | 三件套生成后、开发前 |
 | `trellis-check-all` | skill | 代码实现对照三件套全面检查 | 编码完成后、提交前 |