@peterxiaoyang/superspec 0.1.33 → 0.1.35

package/templates/workflow/skills/superspec-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: superspec-review
-description: "四.执行最终审查，处理 verifier 最终验证工作项"
+description: "四.执行代码审查和最终验证，推进 accepted"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,44 +8,81 @@ metadata:
 
 # SuperSpec Review
 
-你是审查阶段。职责：最终审查——验证实现质量、处理 verifier 最终验证工作项、推进到 accepted，并等待用户确认归档。
+你是审查阶段。目标是按工作流引擎返回的下一步，完成代码审查、最终验证、accept 和归档确认。这个阶段用来提高实现质量，不用来增加额外审批负担。
 
 ## 驱动方式
 
-所有状态由工作流引擎管理。循环：
+所有状态由工作流引擎管理，按这个循环执行：
 
-1. `superspec transition next --change "<change>"` 获取下一步
-2. 执行返回的命令
-3. 登记结果
-4. 回到 1
+1. `superspec transition next --change "<change>"` 获取下一步。
+2. 执行返回的命令，或处理返回的工作项/用户确认。
+3. 登记结果。
+4. 回到第 1 步。
 
-如果下一步提示当前阶段还有用户确认、审查或验证事项，先完成这些事项。完成前不要 accept 或 archive；对用户说明时使用自然语言，不默认复述内部 JSON 字段或完整 packet。
-当 next 在 `accepted` 状态返回归档确认提示时，停止循环并提醒用户确认归档；不要自行执行 archive。
+如果 next 返回待完成工作项，先完成工作项；如果 next 返回用户确认，先让使用者决策；完成前不要 accept 或 archive。对用户说明时使用自然语言，不默认复述内部 JSON 字段或完整工作项说明。
 
-如果下一步需要 verifier 工作项，先按返回的验证说明执行核对，再优先用 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 提交 JSON 验证报告内容；文件路径模式仍可作为 fallback。
+## review-ready 语义
 
-`record job-submit` 沿用现有 raw 归档：报告追加到 `raw/review-reports.jsonl`，不会为 review gate 新增 raw 文件类型。
+`review-ready` 是 transition 命令，不是状态。它会根据当前状态执行不同动作：
 
-## 本阶段做什么
+| 当前状态 | 动作 |
+|---|---|
+| `apply` | 所有 task 已完成时推进到 `apply_done` |
+| `apply_done` | 执行代码审查 |
+| `review` | 执行最终验证 |
 
-1. **确认所有任务完成**：review-ready 会检查 tasks.md 无未完成项
-2. **处理 verifier**：核对 proposal + 实现 + 测试契约一致性
-3. **accept**：`superspec transition accept --change "<change>"`
-4. **等待归档确认**：accepted 后不要自动 archive，交给用户确认
+在 `apply_done`：
 
-## verifier gate 规则
+- 有代码类改动时，`review-ready` 创建或等待代码审查工作项。
+- 没有代码类改动时，`review-ready` 直接进入 `review`，不启动子代理；内部会记录跳过原因。
+- 代码审查通过后，再次执行 `review-ready` 进入 `review`。
+- 代码审查通过后不要再增加持续代码变化拦截；流程内如果需要改代码，必须回 apply，修完后重新走代码审查。
 
-- `review-ready` 首次运行会持久化审查策略；后续 risk 参数不会覆盖首次策略。
-- `minimal` 不要求 verifier；`normal` 和 `strict` 要求 verifier。
-- 当前 MVP 中 `strict` 等同 `normal`，不启用额外检查。
-- 如果 review 状态缺少审查策略，先运行 `review-ready` 补策略，不直接 accept。
-- verifier 工作项 packet 会包含绑定文档和 `review_evidence_digest`，用于确认审查对应的任务完成与 RED/GREEN 证据版本。
-- verifier 通过后，如果绑定文档或已登记执行证据版本变化，需要重新运行 `review-ready` 创建新的 verifier。
+在 `review`：
+
+- `review-ready` 创建或等待最终验证工作项。
+- 最终验证工作项会绑定方案文档和当前已登记的执行证据版本。
+- 最终验证通过后，如果绑定文档或已登记执行证据版本变化，下一次 `review-ready` 会创建新的最终验证工作项。
+- 不要根据风险参数自行跳过最终验证；按 next 和 `review-ready` 返回结果执行。
+
+## 工作项处理
+
+如果 next 返回代码审查或最终验证工作项：
+
+1. 读取工作项说明（job packet）。
+2. 启动对应独立角色执行只读审查或验证。
+3. 按工作项说明中的提交命令提交 JSON 报告，优先从 stdin 提交。
+
+```bash
+superspec record job-submit --change "<change>" --job <JOB> --report -
+```
+
+文件路径模式仅作为备用。报告登记沿用现有事件和原始报告归档机制；不要新增追溯字段或自定义原始报告文件类型。
+
+代码审查结果处理：
+
+- 代码审查通过：再次执行 `review-ready`，进入 `review`。
+- 报告格式不符合要求，或没有给出可处理的问题：状态停在 `apply_done`，下一轮代码审查工作项说明会带上拒绝原因；按原因修正报告生成方式或审查口径后再执行。
+- 连续两次报告不符合要求或没有可处理问题时，next 会要求先修正报告生成方式、模板或审查口径，避免无限重试。
+- 发现纯代码实现问题：按 next 提示执行 `reopen --to apply --review-fix <job_id>#<problem_id> --reason "<reason>"`，由引擎追加普通修复 task。
+- 发现方案/需求文档问题或混合问题：next 会先返回用户确认。记录使用者选择和原因后，按 next 返回的命令回到计划阶段或实现阶段。
+
+最终验证结果处理：
+
+- 最终验证通过：执行 `superspec transition accept --change "<change>"`。
+- 最终验证未通过：报告会保全原始报告引用和问题列表。按报告中的问题修复或回退；不要直接 accept。
+
+## accept 和 archive
+
+- 只有状态为 `review`，且 `next` / `review-ready` 要求的审查或验证已满足时，才执行 accept。
+- accepted 后不要自动 archive，等待用户明确确认。
 
 ## Guardrails
 
-- 不改业务代码（审查阶段只读）
-- 不跳过 verifier 最终验证直接 accept
-- 不在 accepted 后自动 archive
-- 审查报告必须真实引用文件内容，不编造
-- 不跳过 transition
+- 审查阶段只读，不改业务代码。
+- 不绕过 `next` / `review-ready` 要求的代码审查或最终验证。
+- 主流程不重审代码，只复核代码审查报告是否可登记、问题是否可分流、回退和闭环证据是否存在。
+- 涉及代码审查问题回退时，以 next 当前返回为准，不手动套用旧 job 或旧问题编号。
+- 不在 accepted 后自动 archive。
+- 审查和验证报告必须引用真实文件、事件或测试证据，不编造。
+- 不跳过 transition。