@peterxiaoyang/superspec 0.1.43 → 0.1.45

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

@@ -8,22 +8,19 @@ metadata:
 
 # SuperSpec Propose
 
-你是计划阶段。职责：把探索结论转化为可执行的计划——写 proposal.md / specs / design.md / tasks.md + business-invariants.md + test-contract.md。
+你是计划阶段。职责：把探索结论转化为可执行的计划——写 proposal.md / specs / design.md / tasks.md + test-contract.md。
 
-## 驱动方式
+## 使用方式
 
-所有状态由工作流引擎管理：
+先运行 `superspec transition next --change "<change>"`；它给出的命令、确认或工作项就是当前要处理的一组事项。不要根据历史 job 或记忆自行拼接推进命令。
 
-1. `superspec transition next --change "<change>"`
-2. 执行返回的命令、工作项或用户确认
-3. 用户确认用 `superspec record user-decision --change "<change>" --input -`；工作项审查报告用 `superspec record job-submit --change "<change>" --job <JOB> --report -`（文件路径模式仍可作为 fallback）
-4. 回到第 1 步
-
-进入下一阶段前，必须先处理 next 返回的用户确认、审查或验证事项。默认完整审查路径下，进入实现前会要求 `critic`、`architect`、`test-engineer` 三个独立审查工作项完成；审查必须由独立角色执行，不能由主流程自审代替，报告按工作流返回的格式提交并记录实际审查来源。
+- 文档未就绪：补齐本 Skill 定义的计划材料，再重新获取下一步。
+- 需要用户确认：汇总真正影响业务、验收或范围的选择，按输出格式登记。
+- 需要审查：交给输出指定的独立角色，使用返回的提交格式记录报告；主流程自检不能替代独立审查。
 
 什么问题需要用户确认，判定标准见「待用户确认」一节；就绪或审查后向用户只概括任务可验证性、关键风险/证据覆盖和下一步。
 
-执行 propose-ready 前，对照 critic / architect / test-engineer 的阻塞条件快速自检（非穷尽）：Impact 与 CHAIN/IDC 对账、specs 增量与 proposal 能力变化互相对应、design 的功能点与实现方案能推出 tasks、DEC 已有行内结论并回写、task 粒度单一行为且顺序可执行、每个普通 TDD task 有完整可定位的 `执行依据:`（声明的 TEST 都存在于 test-contract，`边界`/`原因` 具体到该 task 而非套话）、不变量可证伪且覆盖核心行为变化、test-contract 覆盖 Impact 引用的 CHAIN、test-contract 中未绑定任何 task 的 TEST 有明确取舍（绑定到 task 或留待用户豁免决策）。自检不替代审查工作项，只为减少驳回往返。
+执行 propose-ready 前，对照 critic / architect / test-engineer 的阻塞条件快速自检（非穷尽）：Impact 与 CHAIN/IDC 对账、specs 增量与 proposal 能力变化互相对应、design 的功能点与实现方案能推出 tasks、DEC 已有行内结论并回写、task 粒度单一行为且顺序可执行、每个普通 task 有完整可定位的 `执行依据:`（声明的 TEST 都存在于 test-contract，`边界`/`验收` 具体到该 task 而非套话）、specs 中的核心业务规则可验证、test-contract 覆盖 Impact 引用的 CHAIN、test-contract 中未绑定任何 task 的 TEST 有明确取舍（绑定到 task 或留待用户豁免决策）。自检不替代审查工作项，只为减少驳回往返。
 
 人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。OpenSpec 生成文档语言不符合预期时，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。
 
@@ -139,72 +136,62 @@ metadata:
 
 ## Review verifier
 
-- [ ] 1.1 检查 verifier 绑定文档 tdd_required:true
+- [ ] 1.1 检查 verifier 绑定文档
   执行依据:
   - 测试: test-contract.md#TEST-001
   - 设计: design.md#Verifier 文档绑定：沿用现有校验入口
   - 来源: proposal.md#Impact；specs/review/spec.md#verifier 绑定
-  - 原因: 独立可验收行为，可由 TEST-001 验收
+  - 验收: 独立可验收行为，可由 TEST-001 验收
   - 边界: 保持既有 job 提交协议不变
-- [ ] 1.2 检查 verifier 绑定执行证据 tdd_required:true
+- [ ] 1.2 检查 verifier 绑定执行证据
   执行依据:
   - 测试: test-contract.md#TEST-002,TEST-003
   - 设计: design.md#执行证据核对：复用现有证据链
   - 来源: proposal.md#Impact；discovery.md#CHAIN-001
-  - 原因: 证据核对与文档绑定是两个独立验收入口
+  - 验收: 证据核对与文档绑定是两个独立验收入口
   - 边界: 不改变历史证据的判定语义
 
 ## Documentation
 
-- [ ] 2.1 更新文档 tdd_required:false no_tdd_reason:documentation-only
+- [ ] 2.1 更新文档
+  执行依据:
+  - 测试:
+  - 设计: design.md#文档说明
+  - 来源: proposal.md#Impact
+  - 验收: 文档准确反映已确定的行为变化
+  - 边界: 不改业务代码或行为
 ```
 
 规则：
-- 每个普通 TDD task（`tdd_required:true`）必须紧跟一个 `执行依据:` 块，包含五个字段：`测试`（该 task 必须兑现的 test-contract 场景，引用 `test-contract.md#TEST-xxx`，多个用逗号合并）、`设计`（执行路线在 `design.md` 的位置或短摘录）、`来源`（task 产生依据，如 `proposal.md#Impact`、spec delta、`discovery.md#CHAIN-xxx,IDC-xxx`，已有明确文件路径的补充材料用 `.superspec/artifacts/...`）、`原因`（为什么单独拆出这个 task）、`边界`（执行时需要保护的边界）
+- 每个普通 task 必须紧跟一个 `执行依据:` 块，包含五个字段：`测试`（该 task 必须兑现的 test-contract 场景，引用 `test-contract.md#TEST-xxx`，多个用逗号合并；没有自动化测试的纯文档/机械任务留空）、`设计`（执行路线在 `design.md` 的位置或短摘录）、`来源`（task 产生依据，如 `proposal.md#Impact`、spec delta、`discovery.md#CHAIN-xxx,IDC-xxx`，已有明确文件路径的补充材料用 `.superspec/artifacts/...`）、`验收`（完成后可检查的结果）、`边界`（执行时需要保护的边界）
 - `执行依据:` 必须紧跟所属 task 行（中间最多允许一个空行）；字段不得重复；块内不得出现 checkbox（`- [ ]` / `- [x]`），否则会变成无人执行的暗任务并被引擎拒绝
 - `设计`、`来源` 的标题或短摘录引用必须使用带文件名前缀的可定位格式，如 `design.md#...`、`proposal.md#...`、`specs/.../spec.md#...`；只有 ID 型引用（TEST/CHAIN/IDC）可以逗号合并。`边界` 默认直接写可对照 diff 的具体保护语义，不需要文件前缀；只有主动引用既有文档原文时才写对应文件和锚点
 - 声明的每个 `TEST-xxx` 必须存在于 `test-contract.md`，否则 `propose-ready` 和 `start-apply` 会被阻断
-- 五个字段的内容必须针对该 task 具体可核验，执行者和审查者要拿它们对照实现：`边界` 写出改动不应触碰的具体行为、模块或语义（能对着 diff 判断有没有越界），不写"不破坏现有功能"这类放在任何 task 上都成立的套话；`原因` 说明这个 task 独立存在的理由，不写"需要单独实现"；不同 task 的执行依据不应互相复制
+- 五个字段的内容必须针对该 task 具体可核验，执行者和审查者要拿它们对照实现：`边界` 写出改动不应触碰的具体行为、模块或语义（能对着 diff 判断有没有越界），不写"不破坏现有功能"这类放在任何 task 上都成立的套话；`验收` 写出完成后的可检查结果，不写"完成实现"；不同 task 的执行依据不应互相复制
 - 写不出可定位的 `设计` 引用时，说明 `design.md` 缺少该 task 的实现方案或边界约束——先补设计，不编造引用
-- 单个 task 声明的测试超过 3 个时，`原因` 必须说明为什么不再拆分
-- `tdd_required:false` task 可以写执行依据，`测试` 字段按需填写；特征化任务（characterization task，指为固化既有行为而写保护测试、不引入新行为的任务）用 `tdd_required:false no_tdd_reason:characterization` 标记，只有这类任务可以在执行阶段以特征化通过作为测试证据
+- 单个 task 声明的测试超过 3 个时，`验收` 必须说明为什么不再拆分
+- Propose 只声明 TEST 和验收目标，不写 `tdd_required`、`no_tdd_reason`、RED/GREEN 或模式参数；`task-start` 会把本轮已冻结的策略与该声明编译为执行要求。代码/行为 task 必须声明至少一个 TEST；纯文档、配置或机械任务的 `测试` 留空，并在验收与边界中说明其非行为性质
 - `REVIEW-FIX-*` task 由引擎在审查返工时追加，不需要手写执行依据
 - `<task_id>` 可以是 `1.1` 或 `TASK-001.1`，必须唯一、稳定；标题不要包含 task id token，例如不要写 `## 1.1 Review verifier`
 - task 内部步骤用普通 bullet，不用缩进 checkbox——引擎只解析顶格 checkbox 行，缩进的会变成无人执行的暗任务
-- `tdd_required:true`（默认）——改运行时代码/业务逻辑/权限/外部接口
-- `tdd_required:false` + `no_tdd_reason:xxx`——纯文档/配置/机械改名/生成物
-- task 行只标记是否需要 TDD，不写 RED/GREEN 命令、断言或预期输出；实际 RED/GREEN 由 apply 阶段执行并记录
+- task 行不写 RED/GREEN 命令、断言、预期输出或执行模式；实际需要的验证由 task-start 返回的执行快照决定
 - 一个 task 对应一个可独立验证的行为变化，或一个明确的非行为改动
-- 多个行为变化、入口或运行时模块不能形成同一个 RED/GREEN 闭环时拆开；需要“顺便”改多个不相邻模块的 task 在 propose 阶段就拆分或补充任务，不留到 apply 阶段扩大范围
+- 多个行为变化、入口或运行时模块不能形成同一个独立验证边界时拆开；需要“顺便”改多个不相邻模块的 task 在 propose 阶段就拆分或补充任务，不留到 apply 阶段扩大范围
 - 任务按可执行顺序排列：引擎忽略标题、按全文顶格 checkbox 行的先后顺序逐个驱动执行，被依赖的任务必须排在依赖它的任务之前，跨组同样如此（顺序与分组冲突时调整任务归组或拆组）；跨组依赖可在任务行内注明依赖的 task id 作为提示，但注明不改变执行顺序
 
-### business-invariants.md
-格式：
-
-```markdown
-# Business Invariants
-
-- INV-001 用户密码必须加密存储
-- INV-002 订单金额不能为负数
-```
-
-规则：
-- 不变量是本次改动必须保持或新确立的业务规则，必须可违反、可验证——存在能让它失败的具体操作和可观察结果；「系统应稳定」「代码应可维护」这类不可证伪的陈述不算
-- 覆盖本次行为变化触及的核心规则即可，不堆砌与本次改动无关的通用约束
-
 ### test-contract.md
 格式：
 
 ```markdown
 # Test Contract
 
-| test_id | invariant | scenario |
-|---|---|---|
-| TEST-001 | INV-001 | 注册时提交明文密码，落库字段为加密值且不含明文 |
-| TEST-002 | INV-002 | 已登录用户提交金额为 -1 的订单，下单被拒绝并返回校验错误 |
+| test_id | scenario |
+|---|---|
+| TEST-001 | 注册时提交明文密码，落库字段为加密值且不含明文 |
+| TEST-002 | 已登录用户提交金额为 -1 的订单，下单被拒绝并返回校验错误 |
 ```
 
-scenario 写到能推导断言的程度：给定什么条件、发生什么动作、观察到什么结果；不写测试命令和断言代码。「验证功能正常」这类无法推导断言的写法不合格。
+核心业务规则写入对应 `specs/` requirement 和 scenario。test-contract 的 scenario 写到能推导断言的程度：给定什么条件、发生什么动作、观察到什么结果；不写测试命令和断言代码。「验证功能正常」这类无法推导断言的写法不合格。
 
 如果 discovery 含 `## 输入数据来源核查` 的 IDC 项，在测试表后增加 `## 输入数据覆盖验证`：
 
@@ -227,23 +214,24 @@ discovery 含 `## 链路五要素` 时，`proposal.md` `## Impact` 中引用的
 
 每个确认项只含一个决策点，带稳定 ID `DEC-xxx`：决策类写明影响面（引用相关 `CHAIN-xxx` / `IDC-xxx`）、候选项及后果、建议默认值及理由；事实类写明需要用户提供什么信息、为什么阻塞。选项和补充说明用普通文本或普通 bullet，不要写成 `- [ ]`，引擎会把它们计为未确认项。
 
-`next` 会在 propose 阶段检查 `proposal.md`、`design.md` 和 `test-contract.md` 的该段落。存在未确认项时，汇总一次向用户提问（按影响排序并说明问题间依赖，不逐个往返）；收到回答后用驱动方式中的 `record user-decision` 命令登记，JSON 经 stdin 传入（scope 建议引用 `DEC-xxx`，一条决策可列多个 ID；此为留痕约定，引擎不校验格式）。
+`next` 会在计划材料中检查该段落。存在未确认项时，汇总一次向用户提问（按影响排序并说明问题间依赖，不逐个往返）；收到回答后按当前输出给出的 `record user-decision` 格式登记，JSON 经 stdin 传入（scope 建议引用 `DEC-xxx`，一条决策可列多个 ID；此为留痕约定，引擎不校验格式）。
 
 答案来自用户时，先登记再勾选；答案来自需求文档、代码证据等外部事实核对时，行内写明证据来源，不伪造用户决策。用户回答含糊、与候选项不匹配或引出新问题时，不视为已确认；复述理解并获得明确答复后再登记。把结论反映到 proposal/design/test-contract 相关内容，勾选行内注明结论要点；确认项作废或重复时改为 `[x]` 并注明理由，不要删除确认项。局部实现细节、命名、普通文件组织和不影响需求/验收/风险的技术微调不要升级为用户确认。
 
-进入 propose 后出现新的业务规则、产品口径、验收标准、示例规范或需求源更新时，不要静默覆盖原计划；默认先在 `proposal.md` 记录 `## 需求变化`，说明变化来源、变化内容、受影响能力、直接修改的文档章节、确认保持不变的范围和处理方式（更新当前 change / 新建后续 change / 暂不处理）。该段是后续增量审查判断“本轮变化”的权威锚点；不得把未受影响的历史设计重新列为本轮待审范围。只有影响技术路线、测试契约或业务不变量时，才同步更新 `design.md`、`test-contract.md` 或 `business-invariants.md`。
+进入 propose 后出现新的业务规则、产品口径、验收标准、示例规范或需求源更新时，不要静默覆盖原计划；默认先在 `proposal.md` 记录 `## 需求变化`，说明变化来源、变化内容、受影响能力、直接修改的文档章节、确认保持不变的范围和处理方式（更新当前 change / 新建后续 change / 暂不处理）。该段是后续增量审查判断“本轮变化”的权威锚点；不得把未受影响的历史设计重新列为本轮待审范围。只有影响规格、技术路线或测试契约时，才同步更新 `specs/`、`design.md` 或 `test-contract.md`。
 
 审查报告是待验证的独立意见，不会自动创造新需求。主流程处理 finding 时先分离 underlying problem 与 recommendation：根据本次 change 的目标、直接证据和明确验收独立判断问题是否成立；问题成立时选择满足既有需求的最小修复。Recommendation 只是非绑定建议，不是验收标准；与用户决定、已确认复用路线或 `## 非目标` 冲突的具体方案不实施，也不得仅为通过审查增加未经确认的基础设施、兼容、额外任务、故障场景或测试义务。若 reviewer 指出的事实证据证明现有方案无法满足用户已确认的强制需求、规格约束或明确验收结果，补足对应结果、契约或证据，而不是默认采用 reviewer 指定的架构；Reviewer 不得自行新增或升级强制要求。
 
+普通计划审查未通过后，主流程拥有整份报告的最终阻塞准入判断权，但不得篡改原报告或把审查意见直接升级为需求。只要报告中存在一个有直接证据、属于本次 change 且影响明确验收或落地的问题，就修改对应材料并重新审查；不要为了让报告“全部正确”而处理其余越界建议。只有整份报告提出的问题均不具备上述阻塞条件时，才可将本次审查结论标记为不阻塞，并按工作流提供的方式留痕。该判断只适用于当前材料；材料变化后必须重新审查，不做部分问题裁决或永久豁免。问题是否成立取决于需求范围、验收口径、风险接受或技术路线时，先询问用户；可由当前材料直接判定的越界、无证据或非阻断建议由主流程说明判断理由。
+
 ## 完成条件
 
-tasks.md 作为计划文档就绪（不是复选框全完成）+ 基础职责文档齐全 → next 返回 propose-ready 命令。
+计划材料准备好后重新运行 `next`；由它决定是否需要确认、审查或可以继续。
 
 ## Guardrails
 
 - 只产出计划文档，不改业务代码、不做实现
 - 不绕过 `## 待用户确认` 中的未确认项
-- tdd_required 标注真实
-- 不跳过 transition
+- 不手写流程推进结果；只执行 `next` 当前返回的动作。
 - 不跳过完整审查路径下的审核工作项
-- 审查通过后、推进前不做非必要的文档编辑；绑定审查的内容（proposal/design/tasks/specs/discovery/business-invariants/test-contract）变更会作废已通过的审查并触发重审。
+- 审查通过后、推进前不做非必要的文档编辑；计划材料变更会按当前审查模式和角色职责触发必要的复审。

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-review
-description: "四.执行代码审查和最终验证，推进 accepted"
+description: "四.执行代码审查和最终验证"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,42 +8,18 @@ metadata:
 
 # SuperSpec Review
 
-你是审查阶段。目标是按工作流引擎返回的下一步，完成代码审查、最终验证和 accept。这个阶段用来提高实现质量，不用来增加额外审批负担。
+你负责完成代码审查、最终验证和交付确认。这个阶段用来提高实现质量，不用来增加额外审批负担。
 
-## 驱动方式
+## 使用方式
 
-所有状态由工作流引擎管理，按这个循环执行：
+先运行 `superspec transition next --change "<change>"`。把输出当作当前任务卡：它会告诉你是需要审查、验证、用户决策、修复，还是可以完成交付；不要自行解释内部流程、风险参数或旧工作项来决定下一跳。
 
-1. `superspec transition next --change "<change>"` 获取下一步。
-2. 执行返回的命令，或处理返回的工作项/用户确认。
-3. 登记结果。
-4. 回到第 1 步。
+- 返回审查/验证工作项：按「工作项处理」完成并登记报告。
+- 返回用户确认：按输出取得所需确认并登记；涉及业务范围、需求或验收取舍时，必须由使用者决定，不能用技术判断代替。
+- 返回修复动作：只按当前输出给出的修复方向处理；修复后重新获取下一步。
+- 返回交付动作：确认没有待处理事项后再执行。
 
-如果 next 返回待完成工作项，先完成工作项；如果 next 返回用户确认，先让使用者决策；完成前不要 accept。审查/验证只说明通过与否、阻塞摘要、缺失证据、下一步，以及应回 apply 还是 propose；验收通过并进入 accepted 时，说明本轮流程已经完成。
-
-## review-ready 语义
-
-`review-ready` 是 transition 命令，不是状态。它会根据当前状态执行不同动作：
-
-| 当前状态 | 动作 |
-|---|---|
-| `apply` | 所有 task 已完成时推进到 `apply_done` |
-| `apply_done` | 执行代码审查 |
-| `review` | 执行最终验证 |
-
-在 `apply_done`：
-
-- 有代码类改动时，`review-ready` 创建或等待代码审查工作项。
-- 没有代码类改动时，`review-ready` 直接进入 `review`，不启动子代理；内部会记录跳过原因。
-- 代码审查通过后，再次执行 `review-ready` 进入 `review`。
-- 代码审查通过后若代码状态再次变化，旧审查失效；流程内如果需要改代码，必须先回 apply，修完后重新走代码审查。
-
-在 `review`：
-
-- `review-ready` 创建或等待最终验证工作项。
-- 最终验证工作项会绑定方案文档和当前已登记的执行证据版本。
-- 最终验证通过后，如果绑定文档或已登记执行证据版本变化，下一次 `review-ready` 会创建新的最终验证工作项。
-- 不要根据风险参数自行跳过最终验证；按 next 和 `review-ready` 返回结果执行。
+代码变化会使先前的审查结论失效；计划材料或执行证据变化会使验证结论失效。不要试图手动复用旧结论，重新运行 `next` 即可得到需要补做的事项。
 
 ## 工作项处理
 
@@ -61,31 +37,26 @@ 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 返回的命令回到计划阶段或实现阶段。
+- 报告必须给出可验证、可处理的结论；格式或内容不合格时，按返回原因修正审查方式后重新提交。
+- 发现纯代码实现问题：按当前输出给出的修复动作处理。
+- 发现方案/需求文档问题或混合问题：让使用者决定处理方向并登记原因；不要擅自选实现或计划路径。
 
 最终验证结果处理：
 
-- 最终验证通过：执行 next 下发的 accept 命令。
-- 最终验证未通过：报告会保全原始报告引用和问题列表。按报告中的问题修复或回退；不要直接 accept。
+- 最终验证通过后，只有 `next` 明确给出交付动作时才执行。
+- 最终验证未通过：按报告中的问题修复或回退；不要直接交付。
 
-## accept 和 accepted 后返工
+## 交付后有新需求
 
-- 只有状态为 `review`，且 `next` / `review-ready` 要求的审查或验证已满足时，才执行 accept。
-- `accepted` 是正常完成终态，next 不再继续推进。
-- 使用者补充、修正或扩展方案、需求、验收或实现约束时，主流程先确定唯一对应的 change 并读取真实状态；只有该 change 当前为 accepted，才按 next 返回的内部 continuation 自动把用户内容概括为 reason 并回到 propose。无法唯一确定 change 时只询问补充属于哪个 change；不要让使用者选择工作流动作，也不要要求使用者执行命令。
-- 如果只是问答、致谢或不改变方案含义的说明，保持 accepted，不触发状态变化。
-- 不从 accepted 直接回 apply；回到 propose 后先修改计划材料，再按 next 重新完成计划审查、实现、代码审查和最终验证。
+- 使用者补充、修正或扩展方案、需求、验收或实现约束时，主流程只需确定对应的 change；引擎会给出重新计划的动作。不要让使用者选择内部工作流动作或执行命令。
+- 问答、致谢或不改变方案含义的说明不触发返工。
+- 新需求必须先回计划材料澄清，不直接作为编码授权。
 
 ## Guardrails
 
 - 审查阶段只读，不改业务代码。
-- 不绕过 `next` / `review-ready` 要求的代码审查或最终验证。
+- 不绕过 `next` 要求的代码审查或最终验证。
 - 主流程不重审代码，只复核代码审查报告是否可登记、问题是否可分流、回退和闭环证据是否存在。
-- 涉及代码审查问题回退时，以 next 当前返回为准，不手动套用旧 job 或旧问题编号。
-- 不把 accepted 后的新需求直接当作 apply 授权，必须先 reopen 到 propose。
+- 涉及代码审查问题时，以当前输出为准，不手动套用旧 job 或旧问题编号。
 - 审查和验证报告必须引用真实文件、事件或测试证据，不编造。
-- 不跳过 transition。
+- 不手写推进或回退结果。