@shirlytaylor73/superharness 1.5.0

package/plugins/superharness/skills/parallel-execution/wave-final-quality-prompt.md

@@ -0,0 +1,59 @@
+# Wave FINAL · F2 代码质量审查 prompt 模板
+
+派发 F2 reviewer 时使用此模板。F2 与 F1/F3/F4 并发派发，关注点**互不重叠**。
+
+**F2 关注点（独占）：** 跨任务的**全局**代码质量——只看一个任务的代码看不出"质量好不好"，必须横向比较才有判断。
+
+```
+Task tool (superharness:code-reviewer):
+  description: "Wave FINAL F2: 跨任务代码质量审查"
+
+  使用模板 requesting-code-review/code-reviewer.md，附加以下 F2 专属指令：
+
+  ## 你的范围
+
+  你审查整个 plan 实现的**跨任务代码质量**——**只看任务间的关系，不看单文件级问题**（单文件级 AI slop / 残留由 task-local spec-reviewer 在每任务收口时顺手抓）：
+  - 命名一致性（不同任务的同类对象是否用了不同名字？例如任务 3 叫 `clearLayers()` 但任务 7 叫 `clearFullLayers()`）
+  - 跨任务重复代码（多个任务实现了同样的工具函数 / 同样的 try-catch 模式）
+  - 抽象层级一致性（有的任务直接操作底层 API、有的封装得很重）
+  - 跨任务过度抽象（为了将来"可能"的扩展加了用不上的接口层）
+
+  ## 你不审查的内容（避免与其它 reviewer 重叠）
+
+  - 单个任务是否实现了规格 → 这是 task-local spec-reviewer 的工作
+  - 全 plan 的需求覆盖 → F1 的工作
+  - 跑起来对不对 → F3 的工作
+  - 是否构建了规格外的东西 → F4 的工作
+
+  ## 文件级质量检查（沿用原 code-quality-reviewer 的标准）
+
+  - 每个文件是否有单一明确的职责和定义清晰的接口？
+  - 各单元是否拆分得足以独立理解和测试？
+  - 实现是否遵循了 plan 中的文件结构？
+  - 本次实现是否创建了已经很大的新文件，或显著增大了现有文件？（不要标记已有的文件大小问题——聚焦于本次变更带来的影响。）
+
+  ## 输入
+
+  - **plan：** [PLAN_FILE_PATH]
+  - **commit 范围：** [BASE_SHA..HEAD_SHA]
+  - **任务清单（含每任务文件集）：** [由 controller 提供]
+
+  ## 输出格式
+
+  ```
+  VERDICT: APPROVE | REJECT
+
+  优点：[最多 3 条]
+
+  问题（按严重度）：
+  - 关键：[file:line — 描述]
+  - 重要：[file:line — 描述]
+  - 次要：[file:line — 描述]
+
+  跨任务一致性问题：
+  - [描述跨任务的命名/抽象/重复问题]
+  ```
+```
+
+**当 F2 给 REJECT 时**：仅修关键和重要级别的问题。次要建议可以记录但不阻断。修完后仅重跑 F2。
+

package/plugins/superharness/skills/parallel-execution/wave-final-scope-fidelity-prompt.md

@@ -0,0 +1,69 @@
+# Wave FINAL · F4 范围保真审查 prompt 模板
+
+派发 F4 reviewer 时使用此模板。F4 与 F1/F2/F3 并发派发，关注点**互不重叠**。
+
+**F4 关注点（独占）：** 1:1 对账 plan vs 实际 diff。LLM 实现最常翻车的方向是 **YAGNI 违反 / scope creep**——构建了 plan 里没要求的东西。F4 专门捕捉这类问题。
+
+````
+Task tool (general-purpose):
+  description: "Wave FINAL F4: 范围保真审查"
+  prompt: |
+    你是 Wave FINAL 的 F4 reviewer，做**范围保真审查**。
+    与你并发的还有 F1（规格）/ F2（代码质量）/ F3（真实手测）——它们各自审查不同维度，**不要越界**。
+
+    ## 你的范围
+
+    你做 plan vs 实际 diff 的 **1:1 对账**——**只标"超出"，不标"遗漏"或"违反 Must NOT"**（那是 F1 的工作）：
+    - **每个任务的"What to do"** vs **该任务的实际 diff（git show <task-commit-sha>）**：
+      - 是否构建了 plan 描述之外的东西？（**scope creep——这是 F4 的独占视角**）
+    - **commit 历史卫生**：
+      - 是否每个任务一个 commit？
+      - commit message 是否引用任务编号？
+    - **工作区残留兜底（仅当 controller 报告层 2 异常时启用）**：
+      - 如果输入的 `git status --porcelain` 不为空 → 全 plan REJECT（commit 闸门层 2 漏拦——属于事故）
+      - 正常情况下层 2 已保证工作区干净，F4 不需主动检查
+
+    ## 你不审查的内容（避免与其它 reviewer 重叠 + 避免重复劳动）
+
+    - **遗漏的需求**（"What to do"中没实现的）→ **F1 的工作**，你绝不标记
+    - **触犯 Must NOT Have / Must NOT do** → **F1 的工作**，你绝不标记
+    - **跨任务文件污染**（任务 N 改了 任务 M 的文件）→ **commit 闸门层 1+层 2 已机械保证**，你不重复检查
+    - **claimed_files vs commit_files 对账**（implementer 谎报漏报）→ **commit 闸门层 1+层 2 已机械保证**，你不重复检查
+    - 代码质量、命名、抽象 → F2 的工作
+    - 跑起来对不对 → F3 的工作
+
+    **强约束：你的 REJECT 只能是"超出范围（scope creep）/ commit 卫生 / 工作区残留"三类。任何"漏了 X"或"违反 Must NOT Y"的发现，必须留给 F1。任何越界 / 谎报 / 漏报，commit 闸门已机械抓——你不要重复审查。**
+
+    ## 输入
+
+    - **plan：** [PLAN_FILE_PATH]
+    - **commit 范围：** [BASE_SHA..HEAD_SHA]
+    - **任务清单：** [由 controller 提供]
+    - **wave 收口后的工作区状态：** [controller 跑 `git status --porcelain` 的输出，正常应为空]
+
+    ## 你的工作
+
+    对每个任务：
+    1. 读任务的 "What to do"
+    2. 读 `git show <task-commit-sha>` 看实际 diff
+    3. **对账（唯一对账）：** diff 里的每一处改动是否都对应 "What to do" 的某一项？标记**超出**的部分（scope creep）
+    4. **检查 commit message**：是否引用任务编号？
+    5. （兜底）输入的 `git status --porcelain` 是否为空？不空 → 全 plan REJECT
+
+    ## 输出格式
+
+    ```
+    VERDICT: APPROVE | REJECT
+
+    任务范围保真（scope creep 检测）：[N/M 任务通过]
+    Commit 卫生：[CLEAN | N 处问题]
+    工作区残留：[CLEAN | NOT CLEAN — 列出 git status 输出]
+
+    REJECT 原因（仅当 REJECT；只能是"超出/commit 卫生/残留"三类）：
+    - 任务 N — file:line 处的改动不在 "What to do" 内：[改动描述]
+    - 任务 N 的 commit message 未引用任务编号
+    - 工作区残留：git status 显示 [...]，commit 闸门层 2 漏拦
+    ```
+````
+
+**当 F4 给 REJECT 时**：controller 派发修复 subagent 移除游离改动 / 修复污染，再仅重跑 F4。

package/plugins/superharness/skills/parallel-execution/wave-final-spec-prompt.md

@@ -0,0 +1,56 @@
+# Wave FINAL · F1 规格合规审查 prompt 模板
+
+派发 F1 reviewer 时使用此模板。F1 与 F2/F3/F4 并发派发，关注点**互不重叠**。
+
+**F1 关注点（独占）：** 全 plan vs 原始规格的**条目级**对账。每条规格需求都要在实现里找到对应。
+
+```
+Task tool (general-purpose):
+  description: "Wave FINAL F1: 全 plan 规格合规审查"
+  prompt: |
+    你是 Wave FINAL 的 F1 reviewer，做**全 plan 规格合规审查**。
+    与你并发的还有 F2（代码质量）/ F3（真实手测）/ F4（范围保真）——它们各自审查不同维度，**不要越界**。
+
+    ## 你的范围
+
+    你审查整个 plan 的实现 vs 原始规格/需求文档的**逐条对账**：
+    - **Must Have** 列表中每一条需求 → 是否在代码中实现？
+    - **Must NOT Have / 边界条件** 列表中每一条 → 是否被遵守（无违反）？
+    - 规格中的每个章节/小节 → 至少有一个对应的实现任务覆盖？
+
+    ## 你不审查的内容（避免与其它 reviewer 重叠）
+
+    - 代码风格、命名、抽象层级 → 这是 F2 的工作
+    - 真实功能跑起来对不对 → 这是 F3 的工作
+    - 是否实现了规格之外的东西 → 这是 F4 的工作
+
+    ## 输入
+
+    - **原始规格/plan：** [PLAN_FILE_PATH]
+    - **本次实现的 commit 范围：** [BASE_SHA..HEAD_SHA]
+    - **完整的 task 清单 + 实现汇报：** [由 controller 提供]
+
+    ## 你的工作
+
+    1. 通读 plan/规格，列出全部 **Must Have**、**Must NOT Have**、章节级需求
+    2. 对每一条，在 commit 范围内找证据：
+       - 实现的 file:line（哪段代码履行了这条需求）
+       - 测试的 file:line（如有）
+    3. 对找不到证据的需求，明确标记**缺失**
+
+    ## 输出格式
+
+    ```
+    VERDICT: APPROVE | REJECT
+
+    Must Have 覆盖：[N/M] 条
+    Must NOT Have 遵守：[N/M] 条
+    章节覆盖：[N/M] 节
+
+    REJECT 原因（仅当 REJECT）：
+    - [需求描述] — 缺失：在 commit 范围内未找到对应实现
+    - [需求描述] — 违反：file:line 处出现禁止的模式
+    ```
+```
+
+**当 F1 给 REJECT 时**：controller 派发修复 subagent 修缺失的需求，再仅重跑 F1（不要顺带重跑 F2/F3/F4）。

package/plugins/superharness/skills/planning/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: planning
+description: 当你有规格说明或需求用于多步骤任务，或在发现现有计划存在问题需要修改时使用，在动手写代码之前
+---
+
+# 编写计划
+
+## 概述
+
+编写或修改当前可执行的实现计划。plan 是执行手册，不是背景文档；只记录 agent 执行所需的最小充分信息：目标、文件、任务、测试、命令、关键代码片段和约束。可以保留关键设计原则、代码架构、接口约定和实现边界，只要它们能帮助 agent 正确执行。删除背景叙事、决策历史、版本更迭、思考过程和重复解释。DRY。YAGNI。TDD。频繁 commit。
+
+假设他们是有经验的开发者，但对我们的工具链和问题领域几乎一无所知。假设他们不太擅长测试设计。
+
+**开始时宣布：** "我正在使用 planning 技能创建实现计划。"
+
+**上下文：** 此技能应在专用 worktree 中运行（由 brainstorming 技能创建）。
+
+**计划保存位置：** `docs/superharness/plans/YYYY-MM-DD-<feature-name>.md`
+- （用户对计划位置的偏好优先于此默认值）
+
+## 设计原则
+
+1. plan 是 agent 自动执行后一次性烧掉的草稿。agent 退出循环后，原计划无论成功失败都作废，必须重新制定或进行修改。因此不需要在 plan 中考虑失败退出循环后的状态管理。
+2. 在 plan 执行期间，只有 agent 会修改项目文件。不需要在 plan 中规定 agent 在执行过程中检验文件是否被人手动修改（在执行 plan 时除了 agent 主动终止和与用户交互，用户不应当自己介入，这是 agent 与用户的约定）。
+3. plan 是执行手册。只描述 agent 在执行时需要的信息：做什么、怎么做。不需要也不能记录对决策和做法的过分解释、版本更迭记录、思考过程等，除非该信息有助于 agent 的执行，比如编码原则、代码逻辑架构、接口约定或实现边界。
+4. plan 是当前状态的唯一真相。修改 plan 时必须原地替换旧内容，不追加"补充说明"、"变更记录"、"第二版计划"等历史痕迹。
+5. plan 修改后必须同步所有派生内容：任务编号、依赖、metadata、文件集、接口、并行执行图、Critical Path、执行交接。不能因为追求简洁而删掉会影响执行正确性的关键设计原则、代码架构和接口约定。
+
+## 新建计划 vs 编辑计划
+
+**新建计划：**
+- 从规格出发生成完整计划，覆盖目标、架构、任务、测试、metadata、并行执行图和执行交接。
+- 不记录方案推导过程，只保留最终执行结论。
+- 如果规格仍不清晰，先回到需求澄清或 brainstorming，不要用 plan 承载未决问题。
+
+**编辑现有计划：**
+- 先读取现有计划和本次修改意图，定位受影响任务与派生章节。
+- 使用 `git diff -- <plan-file>` 查看计划相对基线的变化，识别已有编辑范围。
+- 修改时原地替换受影响章节，删除过时内容。不要在末尾追加补丁式说明。
+- 修改后再次查看 `git diff -- <plan-file>`，确认 diff 只表达当前有效计划变化，没有历史补丁、重复解释或前后矛盾。
+- 如果 diff 显示只改了前文但 metadata、依赖、并行执行图或 Critical Path 未同步，必须继续修正。
+
+## 范围检查
+
+如果规格涵盖了多个独立子系统，它应该在头脑风暴阶段就被拆分为子项目规格。如果没有，建议将其拆分为独立的计划——每个子系统一个。每个计划应该能独立产出可工作、可测试的软件。
+
+## 文件结构
+
+在定义任务之前，先列出将要创建或修改的文件以及每个文件的职责。这是锁定分解决策的地方。
+
+- 设计边界清晰、接口定义良好的单元。每个文件应有一个明确的职责。
+- 你对能一次放入上下文的代码推理得最好，文件越专注你的编辑越可靠。优先选择小而专注的文件，而非承担过多功能的大文件。
+- 一起变更的文件应放在一起。按职责拆分，而非按技术层级拆分。
+- 在现有代码库中，遵循已有模式。如果代码库使用大文件，不要单方面重构——但如果你正在修改的文件已经变得难以管理，在计划中包含拆分是合理的。
+
+此结构决定了任务分解。每个任务应产出独立的、有意义的变更。
+
+## 小步骤任务粒度
+
+**每步必须是 agent 需要执行的可验证动作：**
+- 可以保留细粒度步骤，只要它会改变文件、运行验证、提交代码，或执行明确检查。
+- 禁止把背景叙事、决策历史、方案解释、提醒事项拆成步骤。
+- 禁止把可以一次完成且一次验证的连续操作过分拆分。
+- 多个动作必须一起完成才有意义时，合并成一个步骤，并在步骤内用简短子句说明。
+
+好步骤示例：
+- "编写失败的测试" - 一步
+- "运行它确认失败" - 一步
+- "实现最少代码让测试通过" - 一步
+- "运行测试确认通过" - 一步
+- "Commit" - 一步
+
+## 计划文档头部
+
+**每个计划必须以此头部开始：**
+
+```markdown
+# [功能名称] 实现计划
+
+> **面向 AI 代理的工作者：** 必需子技能：平台支持子代理且计划较大/可安全分 wave 时使用 superharness:parallel-execution；计划较小、任务强耦合或平台不支持子代理时使用 superharness:serial-execution。步骤使用复选框（`- [ ]`）语法来跟踪进度。
+
+**目标：** [一句话描述要构建什么]
+
+**架构：** [2-3 句话描述方案]
+
+**技术栈：** [关键技术/库]
+
+---
+```
+
+## 任务结构
+
+每个任务头部**必须**包含 5 行 metadata（5 行均必填，无相关项写 `无`）：
+
+| 字段 | 含义 | 示例 |
+|---|---|---|
+| `**依赖：**` | 本任务依赖的其他任务编号 | `任务 2, 任务 3` 或 `无` |
+| `**文件集：**` | 本任务会创建/修改的所有文件路径 | `src/users.ts, tests/users.test.ts` |
+| `**导出/变更接口：**` | 本任务对外暴露/变更的符号（函数、类型、常量） | `users.ts::createUser, users.ts::UserDTO` 或 `无` |
+| `**消费接口：**` | 本任务依赖的、可能由其他任务变更的符号 | `db.ts::query, validator.ts::validate` 或 `无` |
+| `**复杂度：**` | `quick` / `standard` / `deep`（三选一精确匹配） | `standard` |
+
+**严格语法（machine-parseable，不允许变体）：**
+
+- **分隔符：** 列表项之间唯一合法分隔符是 **`, `（英文逗号 + 单个空格）**。禁止使用中文逗号 `，`、顿号 `、`、`和`、`与` 等其它形式
+- **空列表：** 当无相关项时写字面量 **`无`**。禁止留空、写 `-`、写 `[]`、写 `N/A`
+- **任务编号：** 严格形式 `任务 N`，即"任务"+一个空格+阿拉伯数字。禁止 `Task 2`、`任务2`、`#2`、中文数字
+- **文件路径：** 相对项目根的 **POSIX 风格路径**（用 `/`，禁用 `\`）
+- **接口符号：** 严格形式 `<相对路径>::<符号名>`，双冒号 `::` 紧贴两侧无空格。`符号名` 是函数/类型/常量名
+- **Markdown 反引号包裹（可选美化）：** 路径与符号值**允许**用反引号 `` ` `` 包裹用于 Markdown 渲染美化，例如 `` `src/users.ts` `` 或 `` `users.ts::createUser` ``。**parser 必须先剥离反引号再做语义解析**。本规范的"分隔符 / 空列表 / 任务编号 / 路径 / 符号"语义是剥离反引号后的内容
+- **复杂度：** 严格三选一字符串：`quick`（单文件机械改动）、`standard`（多文件协调）、`deep`（架构判断）。可选用反引号包裹，禁止其它值
+
+**为什么必填且需严格语法：** 这 5 行是 `parallel-execution` 构建并发安全 wave 调度图的**唯一信源**，需要 LLM 机械化 parse。任何变体形式都可能让契约扫描漏判冲突。`serial-execution` 不消费它们但也不受影响（线性执行依然正确）。
+
+下面的示例展示最小必要片段。真实 plan 不应粘贴整文件，除非整文件很短且完整内容确实是执行所需。
+
+````markdown
+### 任务 N：[组件名称]
+
+**依赖：** 任务 2, 任务 3
+**文件集：** `src/users.ts`, `tests/users.test.ts`
+**导出/变更接口：** `users.ts::createUser`, `users.ts::UserDTO`
+**消费接口：** `db.ts::query`, `validator.ts::validate`
+**复杂度：** standard
+
+**文件：**
+- 创建：`exact/path/to/file.py`
+- 修改：`exact/path/to/existing.py:123-145`
+- 测试：`tests/exact/path/to/test.py`
+
+- [ ] **步骤 1：编写失败的测试**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **步骤 2：运行测试验证失败**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：FAIL，报错 "function not defined"
+
+- [ ] **步骤 3：编写最少实现代码**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **步骤 4：运行测试验证通过**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：PASS
+
+- [ ] **步骤 5：Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## 禁止占位符
+
+每个步骤都必须包含工程师需要的实际内容。以下是**计划缺陷**——绝不要写出来：
+- "待定"、"TODO"、"后续实现"、"补充细节"
+- "添加适当的错误处理" / "添加验证" / "处理边界情况"
+- "为上述代码编写测试"（没有实际测试代码）
+- "类似任务 N"（重复代码——工程师可能不按顺序阅读任务）
+- 只描述做什么而不给出足够执行的信息（代码步骤必须提供关键片段、精确修改位置、接口形状或测试断言）
+- 引用了未在任何任务中定义的类型、函数或方法
+
+## 注意事项
+- 始终使用精确的文件路径
+- 涉及代码变更时提供最小必要片段；避免整文件复制和重复片段，除非整文件很短且完整内容确实是执行所需
+- 精确的命令和预期输出
+- DRY、YAGNI、TDD、频繁 commit
+
+## 自检
+
+编写完整计划后，以全新视角审视规格并对照检查计划。这是你自己执行的检查清单——不是子代理调度。
+
+**1. 规格覆盖度：** 浏览规格中的每个章节/需求。你能指出实现它的任务吗？列出所有遗漏。
+
+**2. 占位符扫描：** 搜索计划中的红旗——上方"禁止占位符"章节中的任何模式。修复它们。
+
+**3. 可读性与漂移检查：** plan 是否只保留当前可执行状态？检查是否存在历史方案、废弃步骤、补充说明、变更记录、同一信息重复出现、过长代码块或整文件复制。若是编辑现有计划，必须通过 `git diff -- <plan-file>` 确认没有只改局部导致的上下文漂移。
+
+**4. 类型一致性：** 后续任务中使用的类型、方法签名和属性名是否与前面任务中定义的一致？任务 3 中叫 `clearLayers()` 但任务 7 中叫 `clearFullLayers()` 就是 bug。
+
+**5. 接口契约扫描（机械执行）：** 逐对扫描所有任务 (A, B)。
+
+**5.1 推导隐式依赖：**
+- 若 `B.消费接口 ∩ A.导出/变更接口 ≠ ∅`，则 A → B 必须是显式依赖（B 的 `**依赖：**` 必须包含 A）。缺则**自动补上**并重排 wave。
+- 反向同理：若 `A.消费接口 ∩ B.导出/变更接口 ≠ ∅`，则 B → A 必须显式依赖。
+
+**5.2 同 Wave 安全前提（最终精确版本，必须 4 条全部满足）：** 同一 wave 内任意两任务 (A, B) 必须满足：
+
+| # | 规则 | 含义 |
+|---|---|---|
+| 1 | `A.文件集 ∩ B.文件集 = ∅` | 不可同改一个文件 |
+| 2 | `A.导出 ∩ B.导出 = ∅` | 不可同时变更同一对外符号 |
+| 3 | `A.导出 ∩ B.消费 = ∅` | A 改的 B 不能消费——若需消费应建立显式依赖（被规则 5.1 自动补上后会被分到不同 wave） |
+| 4 | `B.导出 ∩ A.消费 = ∅` | 同 #3 反向 |
+
+**关键：`A.消费 ∩ B.消费 ≠ ∅` 完全允许** —— 两任务同读一个上游接口（例如多个 wave-final reviewer 同时消费 `wave-final-protocol`）不构成冲突。**绝不**把"符号空间互不相交"当作单一规则——必须按上面 4 条精确判断。
+
+**5.3 文件集越界声明：** 每任务 `**文件集：**` 是 implementer 的硬约束，越界改动在 wave 收口 commit 前被 `git diff --name-only` 检出 → plan 失败，通过用户输入接口让用户在"重派修复 / 换模型 / 放弃 plan"中三选一（详见 parallel-execution SKILL.md "Commit 时机与文件集越界校验"段）。
+
+**6. 拓扑序检查：** 任务编号顺序是否合法拓扑序？任务 N 的 `**依赖：**` 是否全部 ⊆ {任务 1..N-1}？若否，重排任务编号。
+
+**7. 并行执行图渲染（必填章节）：** plan 文末必须有 `## 并行执行图` 章节，内容机械生成（见下文）。
+
+如果发现问题，直接内联修复。无需重新审查——修好继续推进。如果发现规格中的需求没有对应任务，就添加任务。
+
+## 并行执行图渲染（必填章节）
+
+plan 文末必须有以下结构的章节，由你（planning skill）根据每个任务的 `**依赖：**` 字段机械计算：
+
+```markdown
+## 并行执行图
+
+> 仅 `parallel-execution` 使用；`serial-execution` 忽略本节。
+
+**Critical Path:** 任务 1 → 任务 5 → 任务 8 → 任务 12
+
+- Wave 1（无依赖）：任务 1, 任务 2, 任务 3
+- Wave 2（依赖 Wave 1）：任务 4（依赖 1, 2）, 任务 5（依赖 3）
+- Wave 3（依赖 Wave 2）：任务 8（依赖 5）, 任务 9（依赖 4）
+- Wave FINAL（所有任务完成后）：F1 规格合规、F2 代码质量、F3 真实手测、F4 范围保真
+```
+
+**Wave 划分算法：**
+1. Wave 1 = 所有 `**依赖：**` 为 `无` 的任务
+2. Wave N = 所有任务，使其 `**依赖：**` 全部 ⊆ Wave 1 ∪ ... ∪ Wave N-1，且不属于已分配的 wave
+3. Wave FINAL 永远是固定的 F1-F4 四个 reviewer 任务（不写在主任务列表中）
+
+**Critical Path：** 从 Wave 1 到最终 Wave 的最长路径（按依赖链）。给读者一个"瓶颈在哪"的直观信号。
+
+**目标 wave 大小：** 5-8 任务/wave；少于 3 任务/wave（除 Wave FINAL）通常意味着拆分过细或依赖标注过严。
+
+## 执行交接
+
+保存计划后，提供执行选项：
+
+**"计划已完成并保存到 `docs/superharness/plans/<filename>.md`。两种执行方式：**
+
+**1. 子代理驱动（适合较大计划）** - 平台支持子代理时，多 wave 执行，wave 内并行多任务，通过并行子代理完成每个任务执行和任务间审查，快速迭代
+
+**2. 串行执行（适合小计划或无子代理平台）** - 使用 serial-execution 按任务编号执行，串行推进并设有检查点
+
+**选哪种方式？"**
+
+**如果选择子代理驱动：**
+- **必需子技能：** 使用 superharness:parallel-execution
+- 适用于计划较大且任务可安全分 wave 的场景
+- wave 内并行子代理 + task-local 审查 + Wave FINAL 审查
+
+**如果选择串行执行：**
+- **必需子技能：** 使用 superharness:serial-execution
+- 适用于计划较小、任务强耦合或平台不支持子代理的场景
+- 串行执行并设有检查点供审查
+
+

package/plugins/superharness/skills/planning/plan-document-reviewer-prompt.md

@@ -0,0 +1,80 @@
+# 计划文档审查员提示模板
+
+调度计划文档审查员子代理时使用此模板。
+
+**用途：** 按新建计划或编辑计划两种模式，验证计划是否完整、与规格匹配、任务分解合理，并防止编辑后的 plan 漂移。
+
+**调度时机：** 完整计划编写完成后，或现有计划修改完成后。
+
+```
+Task tool（通用）:
+  description: "审查计划文档"
+  prompt: |
+    你是一名计划文档审查员。验证此计划是否完整、当前有效，并准备好进行实现。
+
+    **审查模式：** 新建计划 | 编辑计划
+    **待审查计划：** [PLAN_FILE_PATH]
+    **参考规格：** [SPEC_FILE_PATH]
+    **编辑意图：** [EDIT_INTENT，可选，仅编辑计划必填]
+
+    ## 审查模式
+
+    **新建计划：**
+    - 从规格出发审查完整计划。
+    - 计划必须覆盖目标、架构、任务、测试、metadata、并行执行图和执行交接。
+    - 不要求记录方案推导过程；只应保留最终执行结论。
+
+    **编辑计划：**
+    - 同时审查全文和 `git diff -- [PLAN_FILE_PATH]`。
+    - 如果你不能直接运行 git diff，要求 controller 提供 diff 后再判断。
+    - diff 必须符合编辑意图，并且只表达当前有效计划变化。
+    - 如果 diff 显示只改了正文任务，但 metadata、依赖、文件集、接口、并行执行图或 Critical Path 未同步，必须标记为问题。
+    - 如果旧方案未删除、出现新旧方案并存、追加式补丁、历史说明、变更记录或"第二版计划"，必须标记为问题。
+
+    ## 检查内容
+
+    | 类别 | 检查要点 |
+    |------|----------|
+    | 模式识别 | 是否明确按"新建计划"或"编辑计划"审查？编辑计划是否提供或检查了编辑意图？ |
+    | 完整性 | TODO、占位符、不完整的任务、缺失的步骤 |
+    | 规格对齐 | 计划覆盖了规格需求，没有重大范围蔓延 |
+    | 任务分解 | 任务有清晰的边界，步骤可执行 |
+    | 可构建性 | 工程师能否按此计划执行而不会卡住？ |
+    | 可读性与简洁性 | 计划是否只保留当前可执行状态，没有历史补丁、废弃方案、重复解释、过长代码块或不必要的整文件复制？ |
+    | 有效上下文保留 | 关键设计原则、代码架构、接口约定和实现边界是否被保留，且确实服务于执行？ |
+    | Metadata 完整性 | 每任务是否填齐 5 行 metadata：`**依赖：**` / `**文件集：**` / `**导出/变更接口：**` / `**消费接口：**` / `**复杂度：**`？无相关项是否写 `无` 而非留空？ |
+    | Metadata 严格语法 | 每任务的 metadata 是否符合 `planning/SKILL.md` 中"严格语法（machine-parseable）"段：分隔符是英文逗号+空格、空列表写 `无`、任务编号格式 `任务 N`（中间有空格）、路径 POSIX 风格（禁 `\`）、接口符号严格 `path::sym` 双冒号紧贴、复杂度精确三选一 `quick`/`standard`/`deep`（**复杂度值同样可选反引号包裹，parser 剥离**）？反引号包裹路径/符号/复杂度被允许（parser 剥离），但其它变体（中文逗号、顿号、`Task 2`、`任务2`、Windows 路径分隔符、复杂度写 `medium`/`高`/`低` 等）一律视为缺陷。 |
+    | 拓扑序 | 任务编号顺序是否合法拓扑序？任务 N 的 `**依赖：**` 是否全部 ⊆ {任务 1..N-1}？ |
+    | 接口契约一致性 | 逐对扫描任务 (A, B)：若 `B.消费接口 ∩ A.导出/变更接口 ≠ ∅`，B 的 `**依赖：**` 是否包含 A？ |
+    | Wave 并行安全（4 条 pairwise 规则） | 同一 wave 内任意两任务 (A, B) 是否满足 4 条规则：(1) `A.文件集 ∩ B.文件集 = ∅`；(2) `A.导出/变更接口 ∩ B.导出/变更接口 = ∅`；(3) `A.导出/变更接口 ∩ B.消费接口 = ∅`；(4) `B.导出/变更接口 ∩ A.消费接口 = ∅`。`A.消费 ∩ B.消费 ≠ ∅` 完全允许。 |
+    | 并行执行图 | plan 文末是否有 `## 并行执行图` 章节？wave 划分是否与 `**依赖：**` 标注一致？是否有 Critical Path？ |
+    | 编辑 diff 防漂移 | 编辑计划时，`git diff -- [PLAN_FILE_PATH]` 是否只表达当前有效修改？是否存在追加式补丁、旧新方案并存、派生章节漏改、diff 与编辑意图不符？ |
+
+    ## 校准标准
+
+    **只标记会在实现阶段造成实际问题的事项。**
+    实现者构建了错误的东西或卡住了——这是问题。
+    措辞上的小改进、风格偏好和"锦上添花"的建议则不是。
+
+    计划长不一定是问题；冗余、历史残留、重复说明、派生内容不一致才是问题。
+    关键设计原则、代码架构、接口约定和实现边界如果帮助 agent 正确执行，应视为有效内容。
+    编辑计划时，diff 中出现追加式补丁、旧新方案并存、派生章节漏改，应标记为问题。
+
+    除非存在严重缺陷——规格中的需求遗漏、
+    矛盾的步骤、占位内容、或者模糊到无法执行的任务——否则应予以通过。
+
+    ## 输出格式
+
+    ## 计划审查
+
+    **状态：** 通过 | 发现问题
+
+    **问题（如有）：**
+    - [任务 X，步骤 Y]：[具体问题] - [为什么这对实现很重要]
+    - [diff]：[具体漂移问题] - [为什么这会导致后续维护或执行出错]
+
+    **建议（仅供参考，不阻止通过）：**
+    - [改进建议]
+```
+
+**审查员返回：** 状态、问题（如有）、建议