@wenaixi/dsh-superpower 6.3.1 → 7.0.0

package/skills/{superpower-requesting-code-review → requesting-code-review}/SKILL.md

@@ -1,18 +1,18 @@
 ---
-name: superpower-requesting-code-review
-description: "在任务完成、重大功能实现或准备合并到主分支时发起，用于校验实现是否符合需求与质量标准，建议定期执行"
+name: requesting-code-review
+description: "Superpower Skill（最高优先级）：在任务完成、重大功能实现或准备合并到主分支时发起，用于校验实现是否符合需求与质量标准，建议定期执行。"
 ---
 
 # 请求代码评审
 
-派发代码评审子代理，提前发现问题，避免问题级联扩散。评审者仅获得为评估而精确构造的上下文——而非你的完整会话历史。
+派发一个代码评审 subagent，在问题级联扩散前发现它们。reviewer 获得为评估而精确构造的上下文——绝不使用你的会话历史。
 
 **核心原则：** 尽早评审，频繁评审。
 
 ## 何时请求评审
 
 **必做：**
-- 子代理驱动开发中，完成每个任务后
+- subagent 驱动开发中，完成每个任务后
 - 完成重大功能后
 - 合并到主分支前
 
@@ -25,13 +25,13 @@ description: "在任务完成、重大功能实现或准备合并到主分支时
 
 **1. 获取 git SHA：**
 ```bash
-BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
+BASE_SHA=$(git rev-parse HEAD~1)  # 或：git merge-base origin/main HEAD
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. 派发代码评审子代理：**
+**2. 派发代码评审 subagent：**
 
-派发一个 `general-purpose` 子代理，并按 [code-reviewer.md](code-reviewer.md) 中的模板填入信息
+派发一个 `general-purpose` subagent，并按 [code-reviewer.md](code-reviewer.md) 中的模板填入信息
 
 **占位符说明：**
 - `{DESCRIPTION}` - 本次构建内容的简要总结
@@ -55,13 +55,13 @@ HEAD_SHA=$(git rev-parse HEAD)
 BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
 HEAD_SHA=$(git rev-parse HEAD)
 
-[派发代码评审子代理]
+[派发代码评审 subagent]
   DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
   PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
 
-[子代理返回]：
+[subagent 返回]：
   Strengths: Clean architecture, real tests
   Issues:
     Important: Missing progress indicators
@@ -76,8 +76,8 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 | 借口 | 现实 |
 |--------|---------|
-| “我自己看一下 diff 就行，没必要再派评审” | 你是协调者——在行内直接看 diff 会消耗你本该用于推进工作的上下文窗口。派发评审子代理：diff 与评估都在它的上下文中完成，回传给你的只有结论。 |
-| “评审者需要我的完整会话历史才能看懂改动” | 只给它为评估而精确构造的上下文，绝不给完整会话历史。这样评审者关注的是工作产物本身，而非你的思考过程。 |
+| “我自己看一下 diff 就行，没必要再派评审” | 你是协调者——在行内直接看 diff 会消耗你本该用于推进工作的上下文窗口。派发评审 subagent：diff 与评估都在它的上下文中完成，回传给你的只有结论。 |
+| “reviewer 需要我的完整会话历史才能看懂改动” | 只给它为评估而精确构造的上下文，绝不给完整会话历史。这样 reviewer 关注的是工作产物本身，而非你的思考过程。 |
 
 ## 红线
 

package/skills/{superpower-requesting-code-review → requesting-code-review}/code-reviewer.md

@@ -1,6 +1,6 @@
 # 代码评审提示词模板
 
-在派发代码评审子代理时使用此模板。
+在派发代码评审 subagent 时使用此模板。
 
 **用途：** 在已完成的工作引发连锁影响前，对照需求与代码质量标准进行评审。
 
@@ -28,13 +28,21 @@ Subagent (general-purpose):
     git diff [BASE_SHA]..[HEAD_SHA]
     ```
 
+    ## 规格是一份愿景文档
+
+    规格说明软件必须做什么。它不会逐一列举软件将遇到的所有输入、环境或条件。对于规格未提及的行为，按使用该软件的合理用户会有的预期来判断：合理用户的预期就是需求，规格的沉默不是许可。分级这类发现时依据的是该行为对那位用户的影响，而不是规格是否提到了触发条件。
+
+    ## 拒绝裁决
+
+    在给出结论前，逐条列出你考虑过但判定为超出计划或规格范围的行为，每行一条并附理由。运行会话将对每一行逐条裁决；你搁置的任何内容都不会被静默丢弃。空列表意味着你没有搁置任何内容。
+
     ## 只读评审
 
-    本次评审在当前检出上为只读操作。不得以任何方式修改工作区、暂存区、HEAD 或分支状态。请使用 `git show`、`git diff`、`git log` 等工具查看历史。如需基于其他版本的可用工作副本，请将其检出到独立的临时目录（例如 `git worktree add /tmp/review-[SHA] [SHA]`），切勿在当前检出上移动 HEAD。
+    本次评审在当前检出上为只读操作。不得以任何方式修改 working tree、暂存区、HEAD 或分支状态。请使用 `git show`、`git diff`、`git log` 等工具查看历史。如需基于其他版本的可用工作副本，请将其检出到独立的临时目录（例如 `git worktree add /tmp/review-[SHA] [SHA]`），切勿在当前检出上移动 HEAD。
 
-    ## 禁止派发子代理
+    ## 禁止派发 subagent
 
-    请独立完成全部评审。不要派生子代理来分担 diff 的部分评审，也不要为获取第二意见而另起评审者。本流程已提供该项工作所需的所有评审席位；你派生的评审者会以全量成本重复其中一个席位，且其结论不计入结果。如果 diff 过大难以一次完成，请自行分轮评审，并在报告中说明。
+    请独立完成全部评审。不要派生 subagent 来分担 diff 的部分评审，也不要为获取第二意见而另起 reviewer。本流程已提供该项工作所需的所有评审席位；你派生的 reviewer 会以全量成本重复其中一个席位，且其结论不计入结果。如果 diff 过大难以一次完成，请自行分轮评审，并在报告中说明。
 
     ## 检查项
 
@@ -70,7 +78,7 @@ Subagent (general-purpose):
 
     ## 评审校准
 
-    按实际严重程度对问题分级，并非所有问题都是严重问题。列出问题前先肯定做得好的部分——准确的肯定有助于实现者信任后续反馈。
+    按实际严重程度对问题分级。并非所有问题都是严重（Critical）级别。列出问题前先肯定做得好的部分——准确的肯定有助于实现者信任后续反馈。
 
     如发现与计划的显著偏离，请明确指出，以便实现者确认偏离是否有意。如发现问题出在计划本身而非实现，也请直言。
 
@@ -128,7 +136,7 @@ Subagent (general-purpose):
 - `[BASE_SHA]` — 起始提交
 - `[HEAD_SHA]` — 结束提交
 
-**评审者返回：** 优点、问题（严重 / 重要 / 轻微）、改进建议、总体评估
+**reviewer 返回：** 优点、问题（严重 / 重要 / 轻微）、改进建议、总体评估
 
 ## 输出示例
 

package/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: subagent-driven-development
+description: "Superpower Skill（最高优先级）：在当前会话内执行包含独立任务的实现计划时使用，基于 subagent 分发与逐任务评审保障质量。"
+---
+
+# subagent 驱动开发
+
+按任务分发全新实现 subagent、每任务后进行任务评审（规格符合度 + 代码质量）、最后进行全分支广度评审来执行计划。
+
+**为什么使用 subagent：** 你将任务委托给拥有隔离上下文的 specialized agents。通过精确构造指令与上下文，确保其保持专注并顺利完成任务。它们不应继承你的会话上下文或历史——你只需构造其所需的一切。这也能保留你自己的上下文用于统筹协调。
+
+**核心原则：** 每任务全新 subagent + 任务评审（规格 + 质量）+ 最终广度评审 = 高质量、快迭代
+
+**叙述：** 工具调用之间至多用一行简短语句叙述——ledger 与工具结果负责承载记录。
+
+**持续执行：** 任务之间不要停下来向 human partner 确认。一次性不间断执行计划中的所有任务。仅在以下四种情况或全部任务完成时才停下。“是否继续？”之类的确认与进度总结只会浪费对方时间——对方已要求你执行计划，那就执行到底。
+
+**做裁决，不停摆。** 运行中的计划不等待 human partner。冲突、歧义、计划缺陷、你本想申请突破的上限——自行裁决。规格是约束性依据，计划是对规格的论证，你的判断填补二者未覆盖之处。将每个决策以 `Ruling: <裁决内容> — <原因> — <若错的代价>` 记录到 ledger，然后继续。错误的裁决只会带来可见、可撤销的返工；而卡在问题上停摆的会话会耗掉对方一整天且毫无收益。
+
+仅以下四件事能让你停下，且只有这四件：不可逆或破坏性操作；安全敏感操作；超出本 worktree、按惯例需先征询的副作用（如合并、推送到共享分支、发布）；以及计划破损到每条前行路径都只能靠猜。对于这些，停下来提问。
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "是否有实现计划？" [shape=diamond];
+    "任务是否大多相互独立？" [shape=diamond];
+    "human partner 选择内联执行，或没有 subagent 工具？" [shape=diamond];
+    "subagent-driven-development" [shape=box];
+    "executing-plans" [shape=box];
+    "手动执行或先行头脑风暴" [shape=box];
+
+    "是否有实现计划？" -> "任务是否大多相互独立？" [label="是"];
+    "是否有实现计划？" -> "手动执行或先行头脑风暴" [label="否"];
+    "任务是否大多相互独立？" -> "human partner 选择内联执行，或没有 subagent 工具？" [label="是"];
+    "任务是否大多相互独立？" -> "手动执行或先行头脑风暴" [label="否 - 高度耦合"];
+    "human partner 选择内联执行，或没有 subagent 工具？" -> "executing-plans" [label="是"];
+    "human partner 选择内联执行，或没有 subagent 工具？" -> "subagent-driven-development" [label="否"];
+}
+```
+
+**对比 Executing Plans（内联执行）：**
+- 每任务全新 subagent（无上下文污染），而非一个上下文执行所有任务
+- 每任务后评审（规格符合度 + 代码质量），而非仅在最后评审
+- 每任务与每次评审各消耗一个全新上下文；内联执行只消耗一个上下文外加一位最终 reviewer
+- 两者都在本会话中运行，共享同一计划 workspace 与 ledger，任务之间从不暂停
+
+## 流程
+
+```dot
+digraph process {
+    rankdir=TB;
+
+    subgraph cluster_per_task {
+        label="单任务循环";
+        "分发实现 subagent (./implementer-prompt.md)" [shape=box];
+        "实现者是否提问？" [shape=diamond];
+        "回答问题，提供上下文" [shape=box];
+        "实现者实现、测试、提交、自检" [shape=box];
+        "生成review package，分发任务 reviewer (./task-reviewer-prompt.md)" [shape=box];
+        "规格 [OK] 且质量通过？" [shape=diamond];
+        "finding 是否与计划文本冲突？" [shape=diamond];
+        "对冲突进行裁决并记入 ledger" [shape=box];
+        "修复轮次 R/5：R≤3 恢复原实现者；R≥4 启用全新、能力更强的实现者" [shape=box];
+        "分发scoped re-review (./re-review-prompt.md)" [shape=box];
+        "所有 finding 已处理？" [shape=diamond];
+        "R = 5？" [shape=diamond];
+        "逐条裁决未关闭的 finding" [shape=box];
+        "是否存在承重型 finding？" [shape=diamond];
+        "裁决后继续；仅当所有前行路径皆为猜测时才停下" [shape=box];
+        "将 finding 连同裁决暂存至 ledger" [shape=box];
+        "向 ledger 追加完成记录，标记 todo 已完成" [shape=box];
+    }
+
+    "准备：worktree、ledger 检查、读取计划、飞行前检查" [shape=box];
+    "是否还有剩余任务？" [shape=diamond];
+    "分发最终代码 reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
+    "有最终 finding？一次修复分发、一次 scoped re-review、裁决残留项" [shape=box];
+    "最终评审通过：删除本计划的 workspace" [shape=box];
+    "使用 finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
+
+    "准备：workspace、ledger 检查、读取计划、飞行前检查" -> "分发实现 subagent (./implementer-prompt.md)";
+    "分发实现 subagent (./implementer-prompt.md)" -> "实现者是否提问？";
+    "实现者是否提问？" -> "回答问题，提供上下文" [label="是"];
+    "回答问题，提供上下文" -> "实现者实现、测试、提交、自检";
+    "实现者是否提问？" -> "实现者实现、测试、提交、自检" [label="否"];
+    "实现者实现、测试、提交、自检" -> "生成review package，分发任务 reviewer (./task-reviewer-prompt.md)";
+    "生成review package，分发任务 reviewer (./task-reviewer-prompt.md)" -> "规格 [OK] 且质量通过？";
+    "规格 [OK] 且质量通过？" -> "向 ledger 追加完成记录，标记 todo 已完成" [label="是"];
+    "规格 [OK] 且质量通过？" -> "finding 是否与计划文本冲突？" [label="否"];
+    "finding 是否与计划文本冲突？" -> "对冲突进行裁决并记入 ledger" [label="是"];
+    "对冲突进行裁决并记入 ledger" -> "修复轮次 R/5：R≤3 恢复原实现者；R≥4 启用全新、能力更强的实现者";
+    "finding 是否与计划文本冲突？" -> "修复轮次 R/5：R≤3 恢复原实现者；R≥4 启用全新、能力更强的实现者" [label="否"];
+    "修复轮次 R/5：R≤3 恢复原实现者；R≥4 启用全新、能力更强的实现者" -> "分发scoped re-review (./re-review-prompt.md)";
+    "分发scoped re-review (./re-review-prompt.md)" -> "所有 finding 已处理？";
+    "所有 finding 已处理？" -> "向 ledger 追加完成记录，标记 todo 已完成" [label="是"];
+    "所有 finding 已处理？" -> "R = 5？" [label="否"];
+    "R = 5？" -> "修复轮次 R/5：R≤3 恢复原实现者；R≥4 启用全新、能力更强的实现者" [label="否 - 进入下一轮"];
+    "R = 5？" -> "逐条裁决未关闭的 finding" [label="是 - 触发熔断"];
+    "逐条裁决未关闭的 finding" -> "是否存在承重型 finding？";
+    "是否存在承重型 finding？" -> "裁决后继续；仅当所有前行路径皆为猜测时才停下" [label="是"];
+    "是否存在承重型 finding？" -> "将 finding 连同裁决暂存至 ledger" [label="否"];
+    "将 finding 连同裁决暂存至 ledger" -> "向 ledger 追加完成记录，标记 todo 已完成";
+    "向 ledger 追加完成记录，标记 todo 已完成" -> "是否还有剩余任务？";
+    "是否还有剩余任务？" -> "分发实现 subagent (./implementer-prompt.md)" [label="是"];
+    "是否还有剩余任务？" -> "分发最终代码 reviewer (../requesting-code-review/code-reviewer.md)" [label="否"];
+    "分发最终代码 reviewer (../requesting-code-review/code-reviewer.md)" -> "有最终 finding？一次修复分发、一次scoped re-review、裁决残留项";
+    "有最终 finding？一次修复分发、一次scoped re-review、裁决残留项" -> "最终评审通过：删除本计划的 workspace";
+    "最终评审通过：删除本计划的 workspace" -> "使用 finishing-a-development-branch";
+}
+```
+
+## 准备工作
+
+确保工作在隔离的 worktree 中进行：使用 using-git-worktrees 创建或校验现有 worktree。未经 human partner 明确同意，绝不在 main/master 分支上开始实现。
+
+对话记忆在压缩后不会保留。在真实会话中，丢失进度的控制器曾重新分发整串已完成任务——这是目前观察到代价最高的失败。请在 ledger 文件中跟踪进度，而不仅依赖 todos。
+
+- 每个计划拥有独立 workspace：在技能启动时，运行本技能的 `bash scripts/sdd-workspace PLAN_FILE`——它会打印该计划的 git 忽略目录（位于 `<repo-root>/.superpowers/sdd/` 下），该目录承载本计划的所有产物：ledger、brief、报告、review package。其他计划的目录绝不归你读写。
+- 在 `<workspace>/progress.md` 检查本计划的 ledger。若其首行写明了你的计划文件，则带有 `Task <N>: complete` 行的任务即视为已完成——不要重新分发；从首个没有该行的任务继续。若任务最后一行是修复轮次，则该任务处于循环中：从下一轮继续循环。若 ledger 首行指向另一计划文件——或在旧的扁平路径 `.superpowers/sdd/progress.md` 下发现游离 ledger——那是另一计划的进度：保持原位，为当前计划新建一份全新 ledger。
+- 以标识作为首行创建 ledger：`# SDD ledger — plan: <plan file path>`。
+- ledger 是你的恢复地图：其中记录的提交在 git 中真实存在，即使你的上下文已不再记得曾创建过它们。压缩之后，请信任 ledger 与 `git log`，而非你自己的记忆。
+- `git clean -fdx` 会销毁 workspace（它是被 git 忽略的临时区）；若发生，请从 `git log` 恢复。
+
+通读一次计划，记下其上下文与全局约束，并为每个任务创建 todo。若计划中指明了 Spec，也一并阅读：规格是计划所论证的权威依据，计划内部的冲突应以规格为准进行裁决。无法找到可达规格的计划需在 ledger 中注明——在没有规格的情况下做出的裁决均为临时性。
+
+在分发任务 1 之前，对计划做一次冲突扫描，并边检查边记录检查内容：
+
+- 相互矛盾或与计划全局约束冲突的任务
+- 计划明确要求、但按评审标准视为缺陷的内容（例如断言为空的测试、逻辑块的逐字重复）
+
+扫描输出是表格，而非结论。对每一对共享文件或接口的任务各列一行：两个任务、其一产出与另一消费内容的对照、以及你的发现。对每个任务各列一行：其自身文本是否自洽——所规定的测试与所规定的代码是否一致、所创建的文件与后续触及的文件是否一致。没有这些行的“扫描通过”不算完成扫描。
+
+将表格写入 ledger。在执行开始前对所有 finding 进行裁决——每项裁决均对照要求它的计划文本——并将每条裁决记录到 ledger。若扫描干净，则无需多言直接继续。对扫描暴露的每个冲突进行裁决——规格是约束性依据，计划是其论证——将裁决记录在对应行旁，然后分发任务 1。评审循环仍是兜底机制，用于捕获仅在实现中才显现的冲突。
+
+## 模型选择
+
+为每个角色选用能胜任的最弱模型，以节省成本并提升速度。
+
+**机械性实现任务**（孤立函数、清晰规格、1-2 个文件）：使用快速、廉价的模型。计划描述充分时，大多数实现任务都属于机械性任务。
+
+**集成与判断类任务**（多文件协同、模式匹配、调试）：使用标准模型。
+
+**架构与设计任务**：使用当前可用能力最强的模型。最终全分支评审即属此类——请在最强模型上分发，而非使用会话默认模型。
+
+**评审任务**：根据差异的大小、复杂度与风险选择具有相应判断力的模型。小而机械的差异不需要最强模型；微妙的并发改动则需要。对小范围修复差异的scoped re-review，选用廉价至中等层级即可。
+
+**修复循环升级（第 4-5 轮）**：使用至少比卡住的实现者高一个层级的模型。
+
+**分发 subagent 时务必显式指定模型。** 省略模型会继承你会话的模型——通常是最强也最昂贵的模型——这会无声地破坏本节的约束。
+
+**轮次数量胜过 token 单价。** 墙钟耗时与上下文成本随 subagent 轮次数量线性增长，而最廉价的模型在多步任务上常需 2-3 倍轮次——总体成本反而更高。对 reviewer，以及基于自然语言描述工作的实现者，请以中等层级作为下限。当任务的计划文本已包含待编写的完整代码时，实现只是转录加测试：该实现者使用最廉价层级。单文件机械性修复同样使用最廉价层级。
+
+**任务复杂度信号（实现任务）：**
+- 涉及 1-2 个文件且规格完整 → 廉价模型
+- 涉及多文件且有集成关注点 → 标准模型
+- 需要设计判断或对代码库的广泛理解 → 最强模型
+
+### 可选：让控制器下沉一层（嵌套 subagent）
+
+控制器会话是本技能中最昂贵的一席：它读取每一次分发结果、每一份报告，且通常跑在会话最强的模型上。若宿主支持嵌套 subagent（在主对话之下再开若干层），整个循环可以下沉一层运行，实测成本与墙钟耗时约减半。
+
+这是 human partner 明确要求的可选项，不改变本技能的任何其他要求。当 human partner 提出该要求，或表示会话模型用于统筹过于昂贵时：以一个中等层级模型分发**一个**编排者 subagent，交给它计划路径，并要求端到端使用 subagent-driven-development。该编排者按本技能的模型选择规则自行分发实现者与 reviewer；workspace 与 ledger 都落在磁盘上，因此多一层不会丢失任何东西。它的最终消息必须原样携带「我的裁决」列表——该列表是决策送达 human partner 的通道，你负责转述，而不是概括。
+
+仅对整份计划这样做。把单个任务的分发嵌套进去毫无收益，只会多占一席。
+
+## 任务循环
+
+**批量处理小型同构工作。** 当计划列出多个同类的小而独立的编辑——同一种单行修复、常量变更或跨文件重复的字段添加——不要为每项任务各分发一个 subagent。将每份文件及其变更汇总到一份分发 brief 中，将整个批次交给单个 subagent，并把它的差异作为一个整体进行评审。只有需要独立判断、独立测试或独立评审面的工作，才保留一任务一分发。
+
+你粘贴到分发提示中的一切——以及 subagent 返回的一切——都会在会话剩余时间内常驻上下文，并在后续每一轮被重新读取。请以文件形式移交产物。
+
+**等待已分发的 subagent 时：** 切勿以短超时轮询等待接口，也不要陷入无声的无限等待。当你有本地工作可做时——更新 ledger、打包下一份评审、阅读报告——持续推进；子代结果会自行到达。当你真正空闲时，以有界时长等待（平台允许时每次 5 至 10 分钟），并在每段间隔发布一行状态、核对存活的子代：列出它们，并追查任何已完成却未上报的子代。有界等待几乎保留了长等待的全部效率，同时保证卡住或丢失的子代能在数分钟内被发现，而非等到会话结束。
+
+### 1. 分发实现者
+
+在分发前记录基线 BASE（`git rev-parse HEAD`）——review package与修复轮次的差异需要它。
+
+- **task brief：** 分发实现者前，运行本技能的 `bash scripts/task-brief PLAN_FILE N`——它会将任务完整文本提取到唯一命名的文件并打印路径。按以下方式组织分发：让 brief 保持为需求的单一来源。你的分发应包含：(1) 一行说明本任务在项目中的位置；(2) brief 路径，并说明“先读此文件——它是你的需求，内有需逐字使用的精确取值”；(3) brief 无法获知的、来自先前任务的接口与决策；(4) 你在 brief 中发现的任何歧义的消解；(5) 报告文件路径与报告契约。精确取值（数值、魔法字符串、签名、测试用例）仅出现在 brief 中。切勿让 subagent 阅读整份计划文件。
+- **报告文件：** 以 brief 命名实现者的报告文件（brief `…/task-N-brief.md` → 报告 `…/task-N-report.md`），并写入分发提示。实现者在该文件中撰写完整报告，仅返回状态、提交记录、一行测试摘要与顾虑说明。
+- 分发提示只描述一项任务，而非会话历史。不要将累积的先前任务摘要（“任务 1-3 之后的状态”）粘贴到后续分发中——真实会话中曾出现分发达 42k 字符、其中 99% 为粘贴历史的情况。全新 subagent 只需要其任务、所触及的接口与全局约束，不需要其他。
+- 分发中携带无 subagent 契约（已在实现者模板中）：实现者绝不分发 subagent——既不派生助手，也绝不派生 reviewer。评审由你在报告之后分发。在真实会话中，工作者自行派生的每个 reviewer 都与控制器分发的任务评审重复——相当于每任务多出一席评审。
+- 若先前任务在当前任务触及的区域暂存了 finding，请在分发中携带指向该 ledger 条目的指针。
+- 从分发结果中记录实现者的 agent 身份——修复循环第 1-3 轮将恢复该 agent。
+- 切勿并行分发多个实现 subagent（会冲突）。
+
+模板：[implementer-prompt.md](implementer-prompt.md)
+
+### 2. 处理报告
+
+实现 subagent 会报告四种状态之一，请分别妥善处理：
+
+**DONE：** 生成review package（从本技能目录运行 `bash scripts/review-package PLAN_FILE BASE HEAD`——它会打印所写文件的唯一路径；BASE 为分发实现者前记录的提交——切勿使用 `HEAD~1`，它会在多提交任务中静默丢弃除最后一次提交外的所有内容），然后使用打印出的路径分发任务 reviewer。
+
+**DONE_WITH_CONCERNS：** 实现者已完成工作但标记了疑虑。先阅读顾虑再继续。若顾虑涉及正确性或范围，请在评审前处理；若只是观察性意见（例如“此文件正变得过大”），记录后进入评审。
+
+**NEEDS_CONTEXT：** 实现者需要未提供的信息。补充缺失的上下文并重新分发。
+
+**BLOCKED：** 实现者无法完成任务。评估阻塞原因：
+1. 若是上下文问题，补充更多上下文并以相同模型重新分发
+2. 若任务需要更强推理，以更强的模型重新分发
+3. 若任务过大，将其拆分为更小的块
+4. 若计划本身有误，对修正进行裁决、记入 ledger，并在分发中携带裁决后重新分发
+
+**切勿**忽视升级或在不做任何改变的情况下强制同一模型重试。若实现者表示卡住，一定有需要改变的地方。
+
+若实现者在开始前或任务中提问——请清晰、完整地回答，按需提供额外上下文，不要催促其进入实现。
+
+### 3. 评审任务
+
+单任务评审是任务级关卡。广度评审仅在最终全分支评审时进行一次。切勿跳过任务评审，也不要接受缺少任一裁定的报告——规格符合度与任务质量二者缺一不可。实现者的自检永远不能替代任务评审；二者都需要。
+
+- 以文件形式将差异交给 reviewer：运行本技能的 `bash scripts/review-package PLAN_FILE BASE HEAD`，将打印出的文件路径传给 reviewer（或在无 bash 时：对该区间执行 `git log --oneline`、`git diff --stat` 与 `git diff -U10`，重定向到一个唯一命名的文件）。输出不会进入你自己的上下文，reviewer 通过一次 Read 调用即可看到提交列表、统计摘要与带上下文的完整差异。使用分发实现者前记录的 BASE——切勿使用 `HEAD~1`，它会静默截断多提交任务。切勿在没有差异文件的情况下分发任务 reviewer。
+- **reviewer 输入：** 任务 reviewer 获得三个路径——同一份 brief 文件、报告文件与review package——以及约束该任务的全局约束。
+- 你交给 reviewer 的全局约束块是其注意力透镜。请逐字复制计划全局约束章节或规格中的约束性要求：精确取值、精确格式、以及组件间的既定关系（“与 X 布局一致”、“与 Y 匹配”）。reviewer 模板中已包含流程规则（YAGNI、测试卫生、评审方法）——约束块用于承载本项目规格所要求的特定内容。
+- 不要添加诸如“检查所有用例”或“若有用则跑竞态测试”之类无具体任务依据的开放式指令
+- 不要要求 reviewer 重跑实现者已在相同代码上跑过的测试——实现者报告中已包含测试证据
+- 不要为 reviewer 预判 finding——绝不指示 reviewer 忽略或不标记某个具体问题。若你认为某 finding 可能是误报，让 reviewer 先提出，再在评审循环中裁决。若你正在编写的提示中出现“不要标记”、“不要将 X 视为缺陷”、“至多 Minor”或“计划如此选择”——请停下：你正在预判，通常是为了省去一次评审循环。
+任务 reviewer 可能报告“[WARN] 无法从差异中验证”的条目——这些需求存在于未变更代码或跨任务范围。此类条目不阻塞评审其余部分，但你必须在标记任务完成前自行逐条消解：你掌握 reviewer 所缺乏的计划与跨任务上下文。若确认某条目为真实缺口，则视为规格评审未通过——它将与其他 finding 一同进入修复循环。
+
+模板：[task-reviewer-prompt.md](task-reviewer-prompt.md)
+
+### 4. 修复循环
+
+当评审报告规格 [FAIL]、任意 Critical 或 Important 级 finding、或你确认为真实缺口的 [WARN] 条目时触发循环。
+
+在循环开始前，有两条路径可立即退出：
+
+- 将 Minor 级 finding 随手记入进度 ledger（`Task <N>: minor (deferred): <one-liner>`），并将最终全分支评审指向该列表，以便其分拣哪些必须在合并前修复。无人阅读的汇总等于静默丢弃。Minor 级 finding 永不进入循环。
+- 被标记为计划强制要求的 finding——或任何与计划文本要求冲突的 finding——由你裁决：权衡 finding 与计划文本，以规格为约束性依据做出决定，并在采取行动前将裁决记入 ledger。不要因计划强制要求就驳回 finding，也不要在未记录裁决的情况下分发与计划相矛盾的修复。
+其余项进入循环。一次修复轮次 = 一次修复分发 + 一次scoped re-review。每任务最多五轮：
+
+**第 1-3 轮——恢复原实现者。** 将未关闭的 finding 逐字发送。其上下文仍完整：它了解任务、代码与自身选择。若你的 harness 无法向存活 subagent 再发送消息，则分发携带 brief 路径、报告文件路径与 finding 的全新实现者——报告文件在两种情况下都是持久记忆。
+
+**第 4-5 轮——在更强模型上分发全新实现者**（见模型选择），携带 brief 路径、报告文件路径、未关闭 finding 及如下说明：“先前的实现者已尝试此任务 [N] 次；现由你接管。请阅读报告文件了解已尝试的内容。” 能挺过三次恢复的循环通常意味着实现者无法自见其问题——换视角并提升能力一步到位。
+
+**无论哪一轮，两种方式皆是：** 实现者修复后，重新运行覆盖受改代码的测试，将修复报告追加到同一报告文件，并返回简短契约。在重新分发 reviewer 前，确认修复报告包含覆盖测试、所运行命令及输出；三者齐全后再分发复审。在修复消息中写明覆盖测试文件——单行修复无需跑全量套件。
+
+**复审是范围化的。** 运行 `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`，其中 FIX_BASE 为上次评审所见的 head，并使用 finding 列表、brief、报告文件与打印出的差异路径分发 [re-review-prompt.md](re-review-prompt.md)。re-reviewer 对每项 finding 给出 ADDRESSED 或 NOT ADDRESSED 的裁定，且仅标记修复差异中的新增破坏。若修复差异中出现新的 Critical/Important 破坏，则加入未关闭 finding 列表。超出范围的观察记入 ledger 作为延期 minor——永不延长循环。
+
+**每轮结束后，** 向 ledger 追加：`Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)`
+
+切勿在控制器会话中自行修复 finding——你的上下文需保持干净以用于统筹，且控制器修复会跳过评审。
+
+**熔断。** 当第 5 轮复审后仍有未关闭 finding 时，停止分发。自行逐条裁决未关闭 finding——你掌握计划与 reviewer 所缺乏的跨任务上下文：
+
+- **reviewer 有误，或观点可商榷：** 暂存——`Task <N>: parked — <finding> — Ruling: <代码成立的理由>`。最终评审将看到双方观点。
+- **属实，但无下游依赖：** 同样暂存，并给出“属实但延期”的裁决。
+- **属实且承重**——后续任务依赖于此，或暴露了计划缺陷：对能解开依赖的最小变更进行裁决，以 `Task <N>: Ruling: <finding> — <你的决定与理由>` 记入 ledger，并带入下一任务的分发。将结构性失败静默暂存，会让所有依赖任务都建于其上。仅当缺陷导致每条前行路径都只能靠猜时才停下。
+
+仅在达到上限时才裁决。提前裁决以结束循环本质上是换名的预判。每次裁决均为 ledger 条目——静默丢弃是被禁止的。
+
+### 5. 完成任务
+
+当评审干净返回——或所有未关闭 finding 均在达到上限后附裁决被暂存——在同一条消息中连同其他记账一并向 ledger 追加完成行：
+
+- `Task <N>: complete (commits <base7>..<head7>, review clean)`
+- `Task <N>: complete (commits <base7>..<head7>, <K> parked)` 触发熔断后
+
+然后标记 todo 已完成并继续。切勿在评审仍有未修复或在达到上限后未附裁决暂存的 Critical/Important 问题时进入下一任务。
+
+## 最终评审
+
+最终全分支评审同样获得产物包：运行 `bash scripts/review-package PLAN_FILE MERGE_BASE HEAD`（MERGE_BASE = 分支起点提交，例如 `git merge-base main HEAD`），并在最终评审分发中包含打印出的路径，使最终 reviewer 只需读取一个文件，而无需用 git 命令重新推导分支差异。请在当前可用最强模型上分发（见模型选择），使用 requesting-code-review 的 [code-reviewer.md](../requesting-code-review/code-reviewer.md)。将 ledger 中延期 minor 与暂存行指向 reviewer，以便其分拣哪些必须在合并前修复。
+
+若最终全分支评审返回 finding，仅分发一个携带完整 finding 列表的修复 subagent——而非每项 finding 各派一个修复者。按 finding 分派的修复者各自重建上下文并重跑套件；真实会话中最终评审修复波的成本曾超过所有任务之和。然后对修复波做一次scoped re-review（在修复区间上执行 `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`，使用 [re-review-prompt.md](re-review-prompt.md)）。对残留 finding 按任务循环熔断方式裁决：附裁决暂存，或对承重项进行裁决并记入 ledger。只有上述四类情况能在此让你停下。不存在第二波修复——残留承重 finding 将在 finishing-a-development-branch 呈现选项时上抛给 human partner。
+
+## 收尾
+
+在删除任何内容前，收集 ledger 中所有包含 `Ruling:` 的行——飞行前裁决、暂存 finding、熔断裁决，全部——按做出顺序汇总到最终消息的“我的裁决”下，每条附上若错的代价。列表必须穷尽：ledger 中有裁决，列表中就有。该列表是你代表 human partner 所做决策触达对方的唯一通道——对方会阅读并返工你做错的部分。随 workspace 一同消失的裁决，等同于秘密决策。
+
+当最终全分支评审通过且其修复已合并后，删除本计划的 workspace（`rm -rf <workspace>`）——记录现已留存于 git 历史。同级目录属于其他计划；保持不动。
+
+使用 finishing-a-development-branch。
+
+## 常见托辞
+
+| 托辞 | 现实 |
+|--------|---------|
+| “规格符合度差不多就行” | 评审发现规格缺口 = 未完成。修复或打到上限后裁决——只有这两条出路。 |
+| “我自己修更快，分发是开销” | 控制器修复会污染你的上下文并跳过评审。请恢复实现者。 |
+| “再来一轮就能收敛” | 超过上限后轮次不会收敛——失败是结构性的。请裁决并分流。 |
+| “reviewer 反正还会找出新问题” | scoped re-review只验证修复；不会漫游。未触及代码上的新 finding 记入 ledger，不进入循环。 |
+| “这条 finding 明显有误，我直接丢弃” | 仅在达到上限时裁决，且每条裁决均为 ledger 条目。静默丢弃是被禁止的。 |
+| “修复很小，跳过复审” | 未经评审的修复正是回归的来源。每轮都以scoped re-review结束。 |
+| “评审拖慢循环” | 没有评审的循环只是未经验证的空转。评审是循环的刹车与方向盘。 |
+| “ledger 记账是开销” | ledger 在压缩后依然存活。没有 ledger 的控制器曾重新分发整串已完成任务。 |
+| “实现者自己派了 reviewer——多一份保障” | 那是重复席位，对同一差异做重复评审；任务评审才是关卡。工作者自派的 reviewer 是应标记的缺陷，而非严谨。 |
+
+## 示例工作流
+
+```
+You: 我正在使用 subagent 驱动开发来执行此计划。
+
+[准备：worktree 已校验]
+[通读一次计划文件：docs/superpowers/plans/feature-plan.md]
+[解析 workspace：bash scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — 内部无 ledger，全新开始]
+[为所有任务创建 todos]
+
+任务 1：钩子安装脚本
+
+[为任务 1 运行 task-brief；携带 brief + 报告路径 + 上下文分发实现者]
+
+Implementer: "开始前确认一下——钩子应安装在用户级还是系统级？"
+
+You: "用户级（~/.config/superpowers/hooks/）"
+
+Implementer: [稍后]
+  - 已实现 install-hook 命令
+  - 已添加测试，5/5 通过
+  - 自检：发现遗漏 --force 标志，已补上
+  - 已提交
+
+[运行 review-package PLAN_FILE BASE HEAD；使用打印出的路径分发任务 reviewer]
+任务 reviewer：规格 [OK] - 所有需求已满足，无多余内容。
+  优点：测试覆盖良好、整洁。问题：无。任务质量：通过。
+
+[ledger：Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]
+
+任务 2：恢复模式
+
+[为任务 2 运行 task-brief；携带 brief + 报告路径 + 上下文分发实现者]
+
+Implementer: [无问题]
+  - 已添加 verify/repair 模式
+  - 8/8 测试通过
+  - 已提交
+
+[运行 review-package PLAN_FILE BASE HEAD；使用打印出的路径分发任务 reviewer]
+任务 reviewer：规格 [FAIL]：
+  - 缺失：进度报告（规格要求“每 100 项报告一次”）
+  问题（Important）：魔法数字（100）
+
+[修复第 1 轮：恢复实现者并携带两项 finding]
+Implementer: 已添加进度报告，提取 PROGRESS_INTERVAL 常量。
+  重跑 test/recovery.test.js — 10/10 通过。修复报告已追加。
+
+[运行 review-package PLAN_FILE FIX_BASE HEAD；分发scoped re-review]
+re-reviewer：缺失进度报告 — ADDRESSED (src/recovery.js:41)。
+  魔法数字 — ADDRESSED (src/recovery.js:7)。新增破坏：无。
+  裁定：所有 finding 已处理。
+
+[ledger：Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
+[ledger：Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]
+
+...
+
+[所有任务之后]
+[运行 review-package PLAN_FILE MERGE_BASE HEAD；以最强模型分发最终 code-reviewer]
+最终 reviewer：所有需求已满足。延期 minors 已分拣：无阻塞合并项。
+
+[删除本计划的 workspace——记录现已留存于 git]
+
+完成！使用 finishing-a-development-branch。
+```

package/skills/{superpower-subagent-driven-development → subagent-driven-development}/implementer-prompt.md

@@ -1,6 +1,6 @@
-# 实现者子代理提示词模板
+# 实现者 subagent 提示词模板
 
-在分发实现者子代理时使用此模板。
+在分发实现者 subagent 时使用此模板。
 
 ```
 Subagent (general-purpose):
@@ -11,7 +11,7 @@ Subagent (general-purpose):
 
     ## 任务描述
 
-    请先阅读你的任务简报：[BRIEF_FILE]
+    请先阅读你的 task brief：[BRIEF_FILE]
     其中包含计划中的完整任务原文。
 
     ## 背景
@@ -45,11 +45,11 @@ Subagent (general-purpose):
 
     迭代过程中，仅运行与当前改动相关的聚焦测试；完整测试套件在提交前运行一次即可，无需每次编辑后都运行。
 
-    ## 你不得分发子代理
+    ## 你不得分发 subagent
 
-    自行完成本任务的全部工作。不得衍生子代理来实现任务的某一部分，尤其不得衍生审查者来检查你的工作。自检（见下文）指自行阅读 diff。
-    审查是控制器的职责：在你汇报后，它会针对你的 diff 分发全新的审查者。你自行衍生的审查者会以全量成本重复该审查，且其结论在流程中不作数。
-    如果你产生“独立审查会让汇报更有说服力”的想法——该审查已在计划中。
+    自行完成本任务的全部工作。不得衍生 subagent 来实现任务的某一部分，尤其不得衍生 reviewer 来检查你的工作。自检（见下文）指自行阅读 diff。
+    评审是控制器的职责：在你汇报后，它会针对你的 diff 分发全新的 reviewer。你自行衍生的 reviewer 会以全量成本重复该评审，且其结论在流程中不作数。
+    如果你产生“独立评审会让汇报更有说服力”的想法——该评审已在计划中。
     请直接汇报。
 
     ## 代码组织
@@ -102,10 +102,10 @@ Subagent (general-purpose):
 
     如在自检中发现问题，请在汇报前立即修复。
 
-    ## 收到审查意见后
+    ## 收到评审意见后
 
-    若任务审查发现问题，你将被恢复并收到审查意见。
-    请修复问题，重新运行覆盖修改代码的测试，并在汇报文件中追加修复报告：改了什么、运行了哪些覆盖测试、执行命令及输出。审查者不会替你重跑测试——你的报告即是测试证据。随后以与首次汇报相同的精简状态契约回复。
+    若任务评审发现问题，你将被恢复并收到评审意见。
+    请修复问题，重新运行覆盖修改代码的测试，并在汇报文件中追加修复报告：改了什么、运行了哪些覆盖测试、执行命令及输出。reviewer 不会替你重跑测试——你的报告即是测试证据。随后以与首次汇报相同的精简状态契约回复。
 
     ## 汇报格式
 

package/skills/subagent-driven-development/re-review-prompt.md

@@ -0,0 +1,83 @@
+# 定点复审提示词模板
+
+在派发修复轮次后的复审时使用此模板。re-reviewer 负责核实上一轮的问题是否已修复，并检查修复 diff 是否引入新的破坏性变更。这不是一次全新的评审——完整评审已经完成。
+
+**用途：** 逐条核实上一轮评审中的问题是否已处理，并确认修复本身没有引入新的问题。
+
+```
+Subagent (general-purpose):
+  description: "重新评审任务 N 的修复轮次 R"
+  model: [MODEL — 必填：按 SKILL.md 的模型选择规则选择；若省略则静默继承会话中最昂贵的模型]
+  prompt: |
+    你正在复审单个任务的某一轮修复。上一轮评审已产生若干 finding；实现者已尝试修复它们。你的职责仅是对每一条 finding 给出裁决，并检查修复 diff——除此之外不做其他事。
+
+    ## 任务
+
+    阅读 task brief：[BRIEF_FILE]
+
+    ## 待核实的问题
+
+    [FINDINGS]
+
+    ## 修复内容
+
+    阅读实现者的报告（修复报告追加在末尾）：
+    [REPORT_FILE]
+
+    **修复基线：** [FIX_BASE_SHA]（上一轮评审所见的 head）
+    **当前 Head：** [HEAD_SHA]
+    **Diff 文件：** [DIFF_FILE]
+
+    仅阅读一次 diff 文件——其中包含修复提交、统计摘要以及带上下文的修复 diff。不要重复执行 git 命令。
+    若 diff 文件缺失，请自行获取 diff：
+    `git diff --stat [FIX_BASE_SHA]..[HEAD_SHA]` 和
+    `git diff [FIX_BASE_SHA]..[HEAD_SHA]`。
+
+    本次检出上的评审为只读。不得以任何方式改动 working tree、暂存区、HEAD 或分支状态。
+
+    ## 你不得分发 subagent
+
+    自行完成全部评审。不得衍生 subagent 来分担 diff 的部分评审，也不得另起 reviewer 寻求二次意见。
+    本流程已提供了该工作所需的所有评审席位；你衍生的 reviewer 是对其中一个席位的重复，会产生全量成本，且其裁决不作数。若 diff 过大难以一遍看完，请自行分多遍评审，并在报告中说明。
+
+    ## 范围
+
+    你的范围仅限于 finding 列表和修复 diff。逐条裁决每一条 finding，并检查修复 diff 是否引入了由修复本身导致的新问题。不要重新评审修复未触及的代码：若你注意到完全在修复 diff 之外的问题，请归入“范围外观察”上报——它不会阻塞本任务，也不会延长循环。所有任务完成后再进行一次全分支的广度评审。
+
+    ## 测试
+
+    实现者已重新运行覆盖受改代码的测试，并将结果追加到报告文件中。将报告视为未经核实的陈述：
+    确认修复报告中已列出覆盖性测试并展示其输出，并对照 diff 核实其声明。不要为验证其报告而重新运行整个测试套件。仅当阅读代码产生了现有运行结果无法解答的具体疑虑时，才运行测试——且只运行聚焦的单项测试，绝不要运行包级别的全量套件。
+
+    ## 输出格式
+
+    你的最终消息即为报告本身：直接从第一条 finding 的裁决开始。每一行都是一条裁决、一条带 file:line 的 finding，或你执行过的某项检查——不要写前言，不要叙述过程。
+
+    ### finding 裁决
+
+    按“待核实的问题”中的顺序逐条处理：
+    - **[finding 一句话摘要]** — ADDRESSED | NOT ADDRESSED，并附 file:line 证据。“已尝试”不算已处理：具体缺陷必须已不存在。
+
+    ### 修复 diff 中的新增破坏
+
+    修复本身破坏或引入的任何问题，需标注严重级别（Critical/Important/Minor）及 file:line。若无则写“None”。
+
+    ### 范围外观察
+
+    完全在修复 diff 之外注意到的问题。非阻塞；由控制器记入 ledger 供最终评审使用。若无则写“None”。
+
+    ### 裁决
+
+    **修复轮次：** [所有 finding 已处理且无新增 Critical/Important 级破坏 | 仍有未关闭 finding] —— 列出未关闭项。
+```
+
+**占位符说明：**
+- `[MODEL]` — 必填：按 SKILL.md 的模型选择规则选择评审模型；针对小范围修复 diff 的定点复审选用廉价至中等层级即可
+- `[BRIEF_FILE]` — task brief 文件（与实现者所依据的文件为同一份）
+- `[FINDINGS]` — 上一轮评审中的 Critical/Important 级 finding 及规格缺口，逐字复制，每条一个 bullet
+- `[REPORT_FILE]` — 实现者的报告文件（修复报告会追加在末尾）
+- `[FIX_BASE_SHA]` — 上一轮评审所见的 head
+- `[HEAD_SHA]` — 当前提交
+- `[DIFF_FILE]` — 执行 `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` 时打印的路径
+
+**re-reviewer 返回：** 逐条 finding 的裁决（ADDRESSED / NOT ADDRESSED）、修复 diff 中的新增破坏、范围外观察，以及本轮裁决。

package/skills/{superpower-subagent-driven-development → subagent-driven-development}/scripts/review-package

@@ -22,10 +22,17 @@ head=$3
 git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
 git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
 
+# Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
+# not rooted at BASE; either would silently produce a bogus review package.
+git merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; }
+[ "$(git rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; }
+
 if [ $# -eq 4 ]; then
   out=$4
 else
-  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
+  # Invoke via bash rather than direct exec: some extractors (Python zipfile)
+  # strip Unix exec bits when unpacking marketplace packages (#2040).
+  dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
   out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
 fi