@peterxiaoyang/superspec 0.1.44 → 0.1.46

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

@@ -8,105 +8,96 @@ metadata:
 
 # SuperSpec Explore
 
-职责：只读调查现状、梳理范围、识别风险，并把结论写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`。
+只读调查当前 change，形成基于证据的 `discovery.md`。目标不是穷举仓库，而是确认本次 change 的目标、现状差异、真实影响范围、关键链路与待决问题。
 
-## 驱动方式
+## 工作方式
 
-所有状态由工作流引擎管理：
+运行 `superspec transition next --change "<change>"`，以返回的当前事项为准。优先通过代码、文档、已有测试和需求源消除未知；只有业务语义、验收、范围、数据口径或关键取舍无法由现有证据裁决时才询问用户。
 
-1. `superspec transition next --change "<change>"`
-2. 执行返回的命令、工作项或用户确认
-3. 用户确认用 `superspec record user-decision --change "<change>" --input -`；工作项审查报告用 `superspec record job-submit --change "<change>" --job <JOB> --report -`
-4. 回到第 1 步
-
-进入下一阶段前，必须先处理 next 返回的用户确认、审查或验证事项。默认完整审查路径下，`explore -> propose` 会创建 `critic` 工作项审查 discovery。
-
-如果 next 提示 discovery 不完整或有未确认问题，先检查并填写 discovery，不要把草稿占位、格式缺口或路径空白直接转问用户。用户明确说 PRD、文档、原型或其它需求源已更新时，先重新核对来源，不复用旧依据。什么未知该进 `## 待确认问题`，判定标准见「写作规则」。
-
-执行推进类命令前，对照 critic 的 Discovery 审查阻塞条件快速自检（非穷尽）：锚点可核验、链路表完整且状态为枚举值、完成判定可判定、未知去向明确、已勾选问题有行内结论。自检不替代审查工作项，只为减少驳回往返。
-
-Discovery 审查报告是待验证的独立意见，不会自动扩大本次 change。审查未通过时，主流程先根据用户目标、当前 discovery 的直接证据和明确完成判定，独立判断整份报告是否有资格阻塞：只要存在一个属于本次 change、有直接证据且影响范围判断或阶段完成条件的问题，就补充 discovery 并重新审查；不要为了让报告“全部正确”而处理其余越界建议。只有整份报告提出的问题均不具备阻塞条件时，才可将本次审查结论标记为不阻塞，并按工作流提供的方式留痕。该判断只适用于当前材料；discovery 变化后必须重新审查，不做部分问题裁决或永久豁免。问题是否成立取决于业务范围、完成判定或风险接受时，先询问用户；可由现有材料直接判定的越界、无证据或非阻断建议由主流程说明判断理由。
+用户明确说明 PRD、文档、原型或其他需求源已更新时，重新核对来源，不复用旧结论。文档协议、状态和推进由工作流校验；按 `next` 的反馈修正即可。
 
 ## 探索分工
 
-主会话负责理解需求、提出探查问题、汇总 discovery、判断哪些未知必须问用户；默认必须启动 `explore` subagent 做只读深扫，避免只按用户表述或局部代码自行判断影响范围。仅纯文档、明显 typo、单文件机械小修、明确无代码影响可跳过 subagent，跳过时在 discovery 说明原因。
-
-给 subagent 的深扫任务书按此骨架下达，缺项会直接拉低深扫质量：
+对于可能影响代码、数据、运行时行为或用户可观察结果的 change，主流程必须委派 `explore` subagent 进行独立只读深扫。
 
-```text
-目标：<本次要回答的探查问题，一句话>
-需求原话：<用户原话或 PRD 关键句，不转述>
-已知锚点：<已确认的短锚点（类名/文件名:行号）或文档锚点；没有写“无”>
-参考：<PRD/需求文档/artifact 路径；没有写“无”>
-必查：<正向搜索的具体搜索词（字段名/枚举/路由/文案）> + 反向调用/入口面检查；
-      按链路五要素枚举上游来源、规则变形、持久化语义、下游消费者、视图差异；
-      运行时数据依赖按 IDC 追到 producer 侧最后一次变形处
-返回：已确认事实 / 基于锚点的推断 / 未知及是否阻塞 / 影响范围候选 / 风险 / 需主流程确认的问题；全部带发现方式和证据锚点
-边界：只读，不写方案；“未发现”只能写按哪些发现方式未发现
-```
+主流程负责定义本次要回答的探查问题、核验决定范围的关键证据并汇总 discovery；subagent 负责补全主会话可能遗漏的调用关系、数据链路、相邻消费者、隐性契约和未知项。
 
-subagent 结论写入 discovery 前，抽验决定影响范围判断的关键短锚点；核验不了的降级为推断或未知，不写成事实。
+纯文档、明确 typo、单文件机械修改或已确认无代码影响的任务可以跳过 subagent，并在 discovery 中说明原因。
 
-## discovery.md 契约
+## discovery.md 模板
 
 ```markdown
 # Discovery
 
 ## 需求理解
-- 用户原话/明确目标、当前实现差异、基于证据的推断；未确认的业务语义不要写成事实
-- 完成判定：用户可见行为的验收口径（改动前/后对比）；定不下来的部分进 `## 待确认问题`
+- 用户目标：<用户原话或可核验的归纳>
+- 当前差异：<当前实现与目标的差异，附证据>
+- 完成判定：<用户可见行为的改动前/后口径>
 
 ## 现状
-- 当前系统如何工作
+- <当前实现、入口、已有约束和关键事实>
 
 ## 影响范围
-- 受影响的代码表面、相邻模块和风险
+- <受影响的代码面、相邻模块、用户/系统可观察面及排除理由>
 
 ## 链路五要素
 | ID | 发现方式 | 上游来源 | 规则变形 | 持久化语义 | 下游消费者 | 视图差异 | 未知/排除 | 证据 | 状态 |
 |---|---|---|---|---|---|---|---|---|---|
-| CHAIN-001 | rg 字段名 + 调用方反查 | 配置/输入/历史数据 | 计算/过滤/兜底/无 | 落库含义/不落库 | 详情/APP/报表/导出/定时任务/无 | 计算/展示/统计/回放是否一致 | 未知项或排除理由 | path.ts:10 | 已确认 |
+| CHAIN-001 | <发现路径> | <输入/配置/历史数据> | <关键变形或无> | <持久化含义或不落库> | <消费者或无> | <可观察差异或无> | <未知或排除理由> | <锚点> | 已确认 |
 
 ## 风险和边界
-- 技术风险、依赖、兼容性，绑定代码或文档锚点
+- <有证据的技术、兼容、依赖或发布风险>
 
 ## 输入数据来源核查
-- 无运行时数据依赖：写明具体原因。
-- 有运行时数据依赖：按表核查。
+- <无运行时数据依赖时，说明不适用原因>
 
 | 核查ID | 消费位置 | 必需输入 | 数据来源 | 区分依据 | 状态/理由 |
 |---|---|---|---|---|---|
-| IDC-001 | 入口/规则/算法 | 字段/集合/枚举/状态 | 查询/组装/过滤/缓存/转换位置 | 断点/日志/反例/静态锚点 | 已证明 / 未知阻塞 / 未知非阻塞 |
+| IDC-001 | <入口/规则/算法> | <字段/集合/状态> | <相关 producer 或组装位置> | <可证伪依据> | 已证明 |
 
 ## 待确认问题
-- [ ] Q-001 [验收] 结算价按原始值还是换算值展示？影响：详情页与报表口径（CHAIN-002）。选项：A 原始值（现状、无迁移）/ B 换算值（需回填历史）。建议 A：报表现有消费按原始值聚合
-- [ ] Q-002 [数据来源] status 字段的业务口径以哪份文档为准？需要用户指认来源；阻塞 IDC-001 判定
+- [ ] Q-001 [验收] <一个待决问题>。影响：<范围或验收>。选项：A <后果> / B <后果>。建议：<理由>
 ```
 
-## 写作规则
-
-- 事实必须有源码/文档锚点、命令输出或用户确认支撑；推断要写依据；未知要说明是否阻塞。
-- 不要把自己的理解当成用户需求：用户没有明确说、代码/文档也不能证明的业务语义、验收口径、默认值、边界条件和优先级，只能写为“推断”或“未知”。
-- Discovery 正文默认使用短锚点，格式为 `ClassName.java:123`、`file.ts:45` 或 `ClassName#method:123`；不要写绝对路径，也不要反复写项目相对长路径。只有短名在当前仓库无法唯一定位时，才加最短必要目录前缀（如 `meta/ShiftBlockMatchStrategyType.java:8`）。该规则只适用于人类可读的 discovery 正文；CLI 参数、job packet、JSON 报告字段（如 `source_refs`）和真实文件参数仍按协议保留原始路径。
-- 代码影响型需求尽量提供短锚点；纯文档/配置/新文件无代码锚点时写明 `N/A` 理由。
-- `## 链路五要素` 防止只看局部方法：`发现方式` 必须具体；代码影响型需求至少包含一个正向搜索和一个反向/入口面检查；声称“无规则变形 / 不落库 / 单一消费者 / 无视图差异”必须写证据和排除理由。表格单元格内的字面竖线写成 `\|`（如 `rg "a\|b"`）。
-- 链路五要素 `状态` 列只写枚举值 `已确认` / `未知阻塞` / `未知非阻塞`，不附加说明（引擎按该列判定阻塞）；解决痕迹写在 `未知/排除` 列或对应问题行。
-- `## 输入数据来源核查` 默认必做。`数据来源` 必须追到 producer 侧目标字段最后一次变形处；`区分依据` 必须可证伪。停在 consumer/validator/DTO，或写“代码审查/见上/对照实现”，不合格。
-- 必须进入 `## 待确认问题`：影响需求范围、验收口径、用户可见行为、数据来源、业务语义、安全/权限、兼容/迁移、发布边界的未知；链路五要素或 IDC 中标为 `未知阻塞` 的项；多个可行路线需要用户选择且代码证据无法裁决的决策。
-- `未知非阻塞` 必须说明为什么不影响验收，并绑定验收口径或反例。
-- 不要进入 `## 待确认问题`：可通过继续读代码/跑测试解决的调查项、实现 TODO、内部拆分细节、已被证据排除的范围、已说明不影响验收的 `未知非阻塞`。
-- 每个待确认问题只含一个决策点，带稳定 ID `Q-xxx`：决策类写明影响面（引用相关 `CHAIN-xxx` / `IDC-xxx`）、候选项及后果、建议默认值及理由；事实类写明需要用户提供什么信息、为什么阻塞。
-- 只有 `## 待确认问题` 段落内的 `- [ ]` 是阻塞确认项；选项和补充说明用普通文本或普通 bullet，不要写成 `- [ ]`，引擎会把它们计为未确认项。
-- 所有阻塞问题汇总一次向用户提问，按影响排序并说明问题间依赖，不逐个往返。
-- 答案来自用户时，勾选 `[x]` 前先用 `record user-decision` 登记（scope 建议引用问题 ID，如 `explore_open_questions:Q-001`，一条决策可列多个 ID；此为留痕约定，引擎不校验格式）；答案来自需求文档、代码证据等外部事实核对时，行内写明证据来源，不伪造用户决策。
-- 用户回答含糊、与候选项不匹配或引出新问题时，不视为已确认；复述理解并获得明确答复后再登记勾选。
-- 勾选行内注明结论要点，并同步更新相关段落（需求理解 / 链路五要素状态 / IDC 状态），不能只勾框；问题作废或重复时改为 `[x]` 并注明理由，不要删除问题行。
+模板提供稳定骨架；不要为了填满每个章节或表格而制造事实、链路或风险。
+
+## 写作原则
+
+### 证据与认知边界
+
+Discovery 必须明确区分已确认事实、基于证据的推断和仍未裁决的未知。
+
+事实应能追溯到源码、文档、命令输出或用户确认；推断应说明其证据链和不确定性。不要把当前实现、模型偏好或未经确认的业务语义当成用户需求、验收口径或范围结论。
+
+使用足以复核的源码或文档锚点。纯文档、配置或新文件没有代码锚点时，说明原因即可。
+
+### 影响范围与链路
+
+调查的目标是识别本次 change 实际会改变的责任边界，而不是穷举所有相关模块。
+
+沿真实调用、数据流和既有契约扩展调查：说明重要范围为什么受影响，也说明相邻范围为什么保持不变。只有名称相似、技术上可能相关或属于某类消费者，不构成进入影响范围的理由。
+
+当 change 涉及共享数据、跨边界输入、持久化语义或下游可观察行为时，建立足以判断影响的链路视图：输入来自哪里、关键形态如何变化、由谁持久化或解释、哪些消费者和视图会观察到结果。调查应追到决定本次输入语义的责任点，而不止停在 consumer、DTO 或校验器。
+
+不涉及此类链路时，说明不适用的具体原因；不要为了填表虚构链路。
+
+### 未知与用户决策
+
+先通过继续调查、阅读代码、运行已有测试或核对需求源消除未知。只有无法由现有证据裁决、且会影响需求范围、验收、用户可见行为、数据语义、安全、兼容或关键方案取舍的问题，才交给用户决定。
+
+每个待决问题只表达一个决策，并说明影响、可选方向及建议依据。彼此相关的问题一次汇总提出，而不是逐个往返。
+
+已经被证据排除的范围、实现细节、内部拆分和不影响验收的未知，不应升级为用户问题。非阻塞未知必须说明为什么不影响本次验收。
+
+### 结论闭环
+
+用户答复或新的证据不会只解决一个问题行；应同步更新需求理解、影响范围、链路结论、风险与后续计划依据。
+
+回答含糊、与问题不对应或引入新的关键未知时，不把它视为确认。按工作流记录有效决策后，再将结论写回 discovery。
 
 ## Guardrails
 
-- 不改业务代码。
-- 不写 proposal/specs/design/tasks。
-- 不跳过 transition。
-- 不跳过完整审查路径下的审查工作项。
-- 用户未确认的决策不自行推断。
-- 审查通过后、推进前不做非必要的文档编辑；文档变更会作废已通过的审查并触发重审。
+- 不改业务代码或计划材料。
+- 不自行扩大范围、选择未确认的业务语义或推进状态。
+- 审查意见用于补足证据，不自动创造新范围、新需求或新方案。
+- discovery 发生实质变化后，以 `next` 决定后续审查或推进。

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-propose
-description: "二.编写计划文档（proposal/specs/design/tasks）"
+description: "在 SuperSpec Propose 阶段把 discovery 转成可审查、可执行的计划。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,68 +8,73 @@ metadata:
 
 # SuperSpec Propose
 
-你是计划阶段。职责：把探索结论转化为可执行的计划——写 proposal.md / specs / design.md / tasks.md + test-contract.md。
+你是计划阶段。职责：把已确认的 discovery 转成 `proposal.md`、`specs/`、`design.md`、`tasks.md` 和 `test-contract.md`。Skill 提供作者模板；状态机负责校验结构、字段、引用和推进协议，gate 报错时按错误修正，不把机械问题交给审查角色。
 
-## 驱动方式
+## 工作方式
 
-所有状态由工作流引擎管理：
+先运行 `superspec transition next --change "<change>"`，以返回的事项、确认、审查与提交命令为准。只把用户已确认的行为、边界和有证据的风险写成计划，不改业务代码。
 
-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 步
+需求源、业务口径或验收更新时，先在 `proposal.md` 增加 `## 需求变化`，记录变化来源、变化、受影响能力、已修改材料、保持不变的范围和处理方式；再按实际影响同步规格、设计和测试契约。
 
-进入下一阶段前，必须先处理 next 返回的用户确认、审查或验证事项。默认完整审查路径下，进入实现前会要求 `critic`、`architect`、`test-engineer` 三个独立审查工作项完成；审查必须由独立角色执行，不能由主流程自审代替，报告按工作流返回的格式提交并记录实际审查来源。
+人类可读正文使用简体中文。源码锚点采用能唯一定位的最短写法；文档引用使用 `文件#锚点`，让实现者能打开原材料。
 
-什么问题需要用户确认，判定标准见「待用户确认」一节；就绪或审查后向用户只概括任务可验证性、关键风险/证据覆盖和下一步。
+## 产物模板
 
-执行 propose-ready 前，对照 critic / architect / test-engineer 的阻塞条件快速自检（非穷尽）：Impact 与 CHAIN/IDC 对账、specs 增量与 proposal 能力变化互相对应、design 的功能点与实现方案能推出 tasks、DEC 已有行内结论并回写、task 粒度单一行为且顺序可执行、每个普通 TDD task 有完整可定位的 `执行依据:`（声明的 TEST 都存在于 test-contract，`边界`/`原因` 具体到该 task 而非套话）、specs 中的核心业务规则可验证、test-contract 覆盖 Impact 引用的 CHAIN、test-contract 中未绑定任何 task 的 TEST 有明确取舍（绑定到 task 或留待用户豁免决策）。自检不替代审查工作项，只为减少驳回往返。
+### proposal.md
 
-人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。OpenSpec 生成文档语言不符合预期时，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。
+严格以 `openspec instructions proposal` 的原生结构为准；在该结构中清楚回答为什么需要这个 change、哪些能力变化和影响范围，而不是写实现步骤。
 
-路径/锚点写法：proposal/design/tasks/test-contract 正文里的代码区域和源码证据默认使用短写法，例如 `MatchingProcessor`、`AttendanceReportCalculationRuleController#getSelectShiftBlockStrategy`、`ShiftBlockMatchStrategyType.java:8`。不要写绝对路径，也不要反复写项目相对长路径；只有短名在当前仓库无法唯一定位时，才加最短必要目录前缀（如 `meta/ShiftBlockMatchStrategyType.java:8`）。文档引用仍须带文件名前缀，例如 `design.md#Verifier 文档绑定：沿用现有校验入口`、`test-contract.md#TEST-001`、`specs/review/spec.md#verifier 绑定`；CLI 参数、job packet、JSON 报告字段和 `.superspec/artifacts/...` 补充材料路径仍按协议保留原始路径。
+```markdown
+# Proposal
 
-## 本阶段做什么
+## Why
+<当前问题、影响，以及现在为什么要处理>
 
-### proposal.md
-严格使用 `openspec instructions proposal` 给出的原生结构。`proposal.md` 用于说明为什么需要这个 change、准备改变哪些能力、范围边界和影响面，不负责定义具体实现方案。
+## What Changes
+- <用户或系统可辨识的能力变化>
 
-规则：
-- `Why` 只说明当前问题、机会、造成的影响和现在需要处理的原因，不提前给出解决路线
-- `What Changes` 以用户或系统可辨识的能力变化为粒度，说明新增、修改或移除什么，已知破坏性变化按 OpenSpec 要求标记 `**BREAKING**`；`Capabilities` 只按原生 New / Modified 分类登记精确 capability 名称和简述，不自创分类
-- 能力变化只描述目标结果和范围，不展开 requirement / scenario，也不写类、函数、字段、算法、数据流、调用顺序或复用机制；这些内容分别属于 specs 和 design
-- 可以说明必须保持不变的相邻能力、兼容边界和高层发布影响，但不为完整而编造非目标；具体顺序、回滚步骤和技术方案属于 design
-- `## Impact` 必须能看出受影响范围和原因，写成：
+## Capabilities
+### New Capabilities
+- `<capability>`: <能力简述>
 
-```markdown
+### Modified Capabilities
+- `<capability>`: <变化简述>
+
+## Impact
 | Area | Reason |
 |---|---|
-| review.ts | 需要核对 verifier 如何绑定文档和执行证据 |
+| <模块/API/数据面> | <为什么会受影响、要保持什么语义> |
 ```
 
-- `Area` 可以写代码区域、API、依赖、系统、配置或文档；优先使用模块、类、接口等简短定位，不写成待修改文件白名单
-- `Reason` 只解释该范围为什么受影响、会暴露什么变化或承担什么兼容责任，不展开具体实现方案
-- discovery 含 `## 输入数据来源核查` 的 IDC 项时，相关 `Reason` 须引用对应 `IDC-xxx` 状态（`已证明` / `未知阻塞` / `未知非阻塞`）
-- discovery 含 `## 链路五要素` 时，`## Impact` 须与非 `未知阻塞` 链路行中已确证的下游消费者 / 视图差异对账：受本次改动影响的写入 Area / Reason 并引用对应 `CHAIN-xxx`；不受影响的写明排除理由，可按组书写，排除理由不回写 discovery.md。对账不要求逐行进入 Impact；同一链路已由 `IDC-xxx` 覆盖时，引用其一并注明对应即可
-- 不写设计决策、字段归属、测试场景、RED/GREEN 过程、任务拆分、文件修改顺序或执行日志
+`Why` 不提前指定方案；`What Changes` 与 `Capabilities` 只写可辨识结果。`Impact` 是有原因的影响分析，不是待修改文件白名单或任务清单。discovery 已证实的输入链路、消费者或视图影响应在此对账；已排除的范围说明理由即可。
 
 ### specs/
-严格使用 `openspec instructions specs` 给出的增量格式。`specs/` 定义 change 完成后系统必须满足的长期行为契约，回答“系统应表现为什么”，不回答“内部如何实现”。
-
-规则：
-- `specs/` 只放 Markdown 规范文件，非 `.md` 文件不纳入审查绑定
-- `proposal.md` 声明的每个能力变化都有对应规范增量；specs 不引入 proposal 未声明的能力变化
-- ADDED / MODIFIED / REMOVED / RENAMED 的选择以 `openspec/specs/` 中是否已存在对应 requirement 为依据，不以代码是否已经存在为依据；MODIFIED 必须包含完整更新后的 requirement，REMOVED 必须提供 Reason / Migration，RENAMED 必须提供 FROM / TO
-- 每条 requirement 定义一个可独立理解的行为规则，并至少包含一个符合 OpenSpec 格式的 scenario
-- requirement / scenario 按归档后的目标状态书写，不使用「本次改动」「新增规则」「旧有行为」「变更前」「继续保持」等依赖变更历史的表述；OpenSpec 增量结构标题照常使用
-- 只写可观察行为、公开接口契约和会改变业务结果的稳定语义；私有类、函数、仅服务于当前实现的内部字段、处理阶段、复用机制和清理步骤属于 design。内部数据若构成稳定的跨模块契约或会改变可观察结果，specs 写其语义约束，具体承载方式仍由 design 定义。判断标准是：更换内部实现后仍必须成立的规则属于 specs，只有采用某种实现方式时才成立的内容属于 design
-- scenario 应明确前置条件、触发行为和确定的可观察结果；强制性结果直接使用清晰、可判定的自然语言说明“必须做到什么”或“不得发生什么”，不依赖特定规范关键词，也不使用模糊的多选表达或「保持原有行为」代替可判定结论。只有可选性本身属于契约时才写成可选，并同时说明允许范围和始终成立的不变量
-- 一个 scenario 可以包含同一触发下紧密相关的一组结果，但不得混合多个能够独立失败的责任边界
-- 同一业务规则只保留一个权威 requirement；不同边界情况作为其 scenario，不重复建立语义重叠的 requirement
-- 不写实现路线、测试代码、测试命令、测试数据准备过程或文件修改清单
+
+先执行 `openspec instructions specs`，再为 proposal 中每个能力变化建立对应的增量。规格描述完成后长期成立的可观察行为，不描述类、函数、算法、文件或执行过程。
+
+```markdown
+## ADDED Requirements
+
+### Requirement: <行为规则>
+ <可判定的结果>。
+
+#### Scenario: <场景>
+- **WHEN** <前置条件和触发动作>
+- **THEN** <可观察结果>
+```
+
+使用 OpenSpec 规定的 ADDED / MODIFIED / REMOVED / RENAMED 语义。每个场景要能独立理解和验收；一个行为规则的多个边界情形可以用多个 scenario，不要把多个独立责任混成一句。
 
 ### design.md
-`design.md` 说明“怎么实现”：审查者从目录能看出涉及什么功能、各自采用什么路线；实现者从正文能读出实现机制、影响边界和不能自行决定的关键契约。
+
+`design.md` 的职责是把已确认的需求、事实和约束，转化为实现者可以据此作出一致决策的技术方案。它不是 discovery、Impact、specs 或 tasks 的复述。
+
+- 说明本次方案如何承担责任：关键能力落在哪个边界、主要数据/控制流如何经过、哪些现有机制被接入或改变。按最能表达方案的功能、运行阶段或系统边界组织即可。
+- 只明确会影响验收、兼容性或跨模块一致性的技术决策与契约，例如接口语义、数据形态、状态转换、优先级、事务与恢复行为。未改变的既有语义无需重新设计。
+- 复用现有逻辑时，说明复用什么、接入到哪里、本次差异是什么、哪些语义必须保持。除非需求明确要求，不把本次接入扩展为对通用基础设施的重建或升级。
+- 涉及数据传递时，说明目标输入如何从 producer 到达 consumer，以及 consumer 如何处理它。方案必须与已确认的链路事实一致；发现新的可观察影响时，回写影响分析和测试计划。
+- 明确本次不处理但容易被误解为范围内的相邻能力。对真实存在的取舍、共享契约、风险、回滚或待决问题，按需要说明；没有实际决策价值的章节不要生成。
+- 设计应描述机制与边界，而不是逐行实现、文件修改顺序、任务拆分或测试执行过程。允许使用最有表达力的形式：文字、图、表、伪代码、状态图或数据流。
 
 ```markdown
 # 设计
@@ -117,121 +122,63 @@ metadata:
 - [ ] DEC-xxx <阻塞决策>
 ```
 
-规则：
-- 写 design 前对照 discovery / proposal / specs，把影响实现的事实和约束转成具体安排；不记录调查过程，不复制 Impact、specs 行为、discovery 证据或 tasks 拆分。
-- `## 实现方案` 是主体。代码影响型需求必须能映射到可定位的方案，但不要求需求与小节一一对应；紧密相关需求可以共用方案，只有存在独立技术路线时才拆分。
-- 方案按业务功能、运行时阶段或系统边界组织。标题同时写明“针对什么”和“怎么实现”，例如 `班段内最新入/最早出：复用既有 START/END 选择策略`；不要只写“策略复用”“数据处理”“接口调整”等泛称。
-- 每个方案整体说明实现机制、影响范围、设计依据和边界约束；不要求固定字段，只写本次实际涉及的数据、接口、流程和运行边界。共享契约集中定义一次，其他方案引用。
-- 当本次 change 确实新增或改变行为、数据语义、接口兼容、状态、优先级、一致性、并发或恢复结果，且不同选择会影响已声明验收时，才明确对应契约；未改变的既有语义不重新设计。可以使用必要的模块、接口、表 / 字段、关键函数、数据流、状态机、优先级矩阵和简短伪代码。
-- 声明“复用现有逻辑”或“保持行为不变”时，说明复用对象、接入位置、本次差异和需要保持的语义，不能只写抽象结论。
-- 复用现有基础设施或通用机制时，只设计本次接入和差异，不重新证明或升级该机制的一般可靠性。除非用户、proposal 或 specs 明确提升对应质量等级，不新增未经确认的基础设施、可靠性模式或版本协调机制。
-- 可以描述运行时算法、数据 / 控制流、状态转换和事务顺序；不写逐行代码、完整 SQL、文件修改顺序、task、测试命令或 RED/GREEN 步骤。
-- discovery 的 `## 输入数据来源核查` 影响方案时，分别写清 producer→consumer 的输入完整性和 consumer 处理方式；相关 `IDC-xxx` 为 `未知阻塞` 时 design 不得 ready。
-- discovery 含 `## 链路五要素` 时，方案不得违背已确证链路事实。design 可以引用 CHAIN 解释路线；若发现 Impact 未记录的消费者、视图差异或用户 / 系统可观察行为影响，先回写 Impact，再进入 test-contract 映射。
-- `## 非目标` 和 `## 总体方案` 必须生成：非目标写最容易被误认为本次范围的相邻能力或技术路线，不编造无关项；总体方案用 2～5 句概括功能点关系、主要数据流或调用关系，不展开任务步骤。
-- 模板中的可选注释只用于判断是否生成，不写入成品。替代路线、整体方案取舍、关键契约、风险 / 取舍与回滚没有真实内容时连标题一起省略；替代路线优先写在对应方案内，只有横跨多个功能点时才集中说明；只有阻塞确认项才追加 `## 待用户确认`。
-
 ### tasks.md
-使用 OpenSpec tasks 原生分组结构。每个顶格 checkbox 行是一个 SuperSpec 可执行 task，Markdown 标题只用于分组。
+
+使用 OpenSpec 的任务分组；每个顶格 checkbox 是一个可独立完成和验证的 task。按依赖顺序排列，多个独立行为或入口不能共享一个验证边界时拆开。
 
 ```markdown
 # Tasks
 
-## Review verifier
+## <分组>
 
-- [ ] 1.1 检查 verifier 绑定文档 tdd_required:true
+- [ ] 1.1 <可独立验证的行为或明确的非行为改动>
   执行依据:
   - 测试: test-contract.md#TEST-001
-  - 设计: design.md#Verifier 文档绑定：沿用现有校验入口
-  - 来源: proposal.md#Impact；specs/review/spec.md#verifier 绑定
-  - 原因: 独立可验收行为，可由 TEST-001 验收
-  - 边界: 保持既有 job 提交协议不变
-- [ ] 1.2 检查 verifier 绑定执行证据 tdd_required:true
-  执行依据:
-  - 测试: test-contract.md#TEST-002,TEST-003
-  - 设计: design.md#执行证据核对：复用现有证据链
-  - 来源: proposal.md#Impact；discovery.md#CHAIN-001
-  - 原因: 证据核对与文档绑定是两个独立验收入口
-  - 边界: 不改变历史证据的判定语义
-
-## Documentation
+  - 设计: design.md#<对应实现方案>
+  - 来源: proposal.md#Impact；specs/<capability>/spec.md#<对应规则>
+  - 验收: <完成后可检查的结果>
+  - 边界: <不能改变的具体行为、接口或数据语义>
 
-- [ ] 2.1 更新文档 tdd_required:false no_tdd_reason:documentation-only
+- [ ] 1.2 <纯文档或机械改动>
+  执行依据:
+  - 测试:
+  - 设计: 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 行（中间最多允许一个空行）；字段不得重复；块内不得出现 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 的执行依据不应互相复制
-- 写不出可定位的 `设计` 引用时，说明 `design.md` 缺少该 task 的实现方案或边界约束——先补设计，不编造引用
-- 单个 task 声明的测试超过 3 个时，`原因` 必须说明为什么不再拆分
-- `tdd_required:false` task 可以写执行依据，`测试` 字段按需填写；特征化任务（characterization task，指为固化既有行为而写保护测试、不引入新行为的任务）用 `tdd_required:false no_tdd_reason:characterization` 标记，只有这类任务可以在执行阶段以特征化通过作为测试证据
-- `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 在 propose 阶段就拆分或补充任务，不留到 apply 阶段扩大范围
-- 任务按可执行顺序排列：引擎忽略标题、按全文顶格 checkbox 行的先后顺序逐个驱动执行，被依赖的任务必须排在依赖它的任务之前，跨组同样如此（顺序与分组冲突时调整任务归组或拆组）；跨组依赖可在任务行内注明依赖的 task id 作为提示，但注明不改变执行顺序
+每个普通 task 紧跟 `执行依据:`，显式写 `测试`、`设计`、`来源`、`验收`、`边界`。行为 task 的测试引用相应场景；纯非行为 task 才可留空并在验收/边界说明原因。`验收` 与 `边界` 必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。验证策略由 task-start 按所选模式编译，计划中不要推断 RED/GREEN。
 
 ### test-contract.md
-格式：
+
+把每个需自动验证的验收行为写成能推导断言的场景，不写测试命令或断言代码。
 
 ```markdown
 # Test Contract
 
 | test_id | scenario |
 |---|---|
-| TEST-001 | 注册时提交明文密码，落库字段为加密值且不含明文 |
-| TEST-002 | 已登录用户提交金额为 -1 的订单，下单被拒绝并返回校验错误 |
+| TEST-001 | 给定 <条件>，当 <动作> 时，观察到 <可判定结果> |
 ```
 
-核心业务规则写入对应 `specs/` requirement 和 scenario。test-contract 的 scenario 写到能推导断言的程度：给定什么条件、发生什么动作、观察到什么结果；不写测试命令和断言代码。「验证功能正常」这类无法推导断言的写法不合格。
-
-如果 discovery 含 `## 输入数据来源核查` 的 IDC 项，在测试表后增加 `## 输入数据覆盖验证`：
-
-| 核查ID | 验证方式 | 输入链路声明 | 证据或计划 |
-|---|---|---|---|
-| IDC-001 | 源码锚点 + 聚焦测试 | producer 产生的目标输入会进入 consumer | path.ts:10 + TEST-001 |
-
-证明方式可用源码锚点、fixture、targeted test、日志或 trace，须说明证明力；不强制集成测试。只证 consumer 算法、没证 producer→consumer 输入完整性，测试契约不足。
+数据传递、字段形态或 producer-to-consumer 契约变化时，在测试表后说明输入完整性的证明方式（源码锚点、fixture、聚焦测试、日志或 trace）及其证明力；只证明 consumer 算法不足以证明新输入真的到达 consumer。
 
-discovery 含 `## 链路五要素` 时，`proposal.md` `## Impact` 中引用的 `CHAIN-xxx` 应映射到测试场景（scenario 内引用对应 `CHAIN-xxx`），或在测试表后写明不覆盖理由。design 只引用 CHAIN 作为方案依据时不重复产生映射要求；若 design 暴露新的消费者、视图差异或用户 / 系统可观察行为影响，先补入 Impact，再按同一规则映射测试。
+## 待用户确认与审查
 
-### 待用户确认
-遇到会影响需求范围、验收标准、用户可见行为、方案取舍、测试策略、安全、权限、数据判断的关键不确定问题，先写入相关计划文档的 `## 待用户确认` 段落；没有阻塞确认项的文档不加该段落：
+会影响范围、验收、兼容、数据语义、安全或关键方案取舍的未知，写在相应计划文档的 `## 待用户确认` 下：
 
 ```markdown
 ## 待用户确认
-
-- [ ] DEC-001 [方案] 是否需要兼容历史行为？影响：验收口径（CHAIN-003）。选项：A 兼容（加开关、保留旧路径）/ B 不兼容。建议 A：存量数据仍被报表消费
+- [ ] DEC-001 [方案] <一个待决问题>。影响：<范围/验收>。选项：A <后果> / B <后果>。建议：<理由>
 ```
 
-每个确认项只含一个决策点，带稳定 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；此为留痕约定，引擎不校验格式）。
-
-答案来自用户时，先登记再勾选；答案来自需求文档、代码证据等外部事实核对时，行内写明证据来源，不伪造用户决策。用户回答含糊、与候选项不匹配或引出新问题时，不视为已确认；复述理解并获得明确答复后再登记。把结论反映到 proposal/design/test-contract 相关内容，勾选行内注明结论要点；确认项作废或重复时改为 `[x]` 并注明理由，不要删除确认项。局部实现细节、命名、普通文件组织和不影响需求/验收/风险的技术微调不要升级为用户确认。
-
-进入 propose 后出现新的业务规则、产品口径、验收标准、示例规范或需求源更新时，不要静默覆盖原计划；默认先在 `proposal.md` 记录 `## 需求变化`，说明变化来源、变化内容、受影响能力、直接修改的文档章节、确认保持不变的范围和处理方式（更新当前 change / 新建后续 change / 暂不处理）。该段是后续增量审查判断“本轮变化”的权威锚点；不得把未受影响的历史设计重新列为本轮待审范围。只有影响规格、技术路线或测试契约时，才同步更新 `specs/`、`design.md` 或 `test-contract.md`。
-
-审查报告是待验证的独立意见，不会自动创造新需求。主流程处理 finding 时先分离 underlying problem 与 recommendation：根据本次 change 的目标、直接证据和明确验收独立判断问题是否成立；问题成立时选择满足既有需求的最小修复。Recommendation 只是非绑定建议，不是验收标准；与用户决定、已确认复用路线或 `## 非目标` 冲突的具体方案不实施，也不得仅为通过审查增加未经确认的基础设施、兼容、额外任务、故障场景或测试义务。若 reviewer 指出的事实证据证明现有方案无法满足用户已确认的强制需求、规格约束或明确验收结果，补足对应结果、契约或证据，而不是默认采用 reviewer 指定的架构；Reviewer 不得自行新增或升级强制要求。
-
-普通计划审查未通过后，主流程拥有整份报告的最终阻塞准入判断权，但不得篡改原报告或把审查意见直接升级为需求。只要报告中存在一个有直接证据、属于本次 change 且影响明确验收或落地的问题，就修改对应材料并重新审查；不要为了让报告“全部正确”而处理其余越界建议。只有整份报告提出的问题均不具备上述阻塞条件时，才可将本次审查结论标记为不阻塞，并按工作流提供的方式留痕。该判断只适用于当前材料；材料变化后必须重新审查，不做部分问题裁决或永久豁免。问题是否成立取决于需求范围、验收口径、风险接受或技术路线时，先询问用户；可由当前材料直接判定的越界、无证据或非阻断建议由主流程说明判断理由。
-
-## 完成条件
+收到答复后，先按 `next` 返回的方式登记用户决策，再回写材料并勾选该项。局部实现细节不升级为用户决策。
 
-tasks.md 作为计划文档就绪（不是复选框全完成）+ 基础职责文档齐全 → next 返回 propose-ready 命令。
+审查意见是独立证据，不会自动创造需求。只修复有直接证据、属于本次 change 且影响已声明验收或可落地性的问题；以满足现有需求的最小改动闭环。建议、技术偏好或未采纳路线不能自行升级为 task、测试义务或基础设施。材料变化后重新运行 `next`，由引擎安排必要复审。
 
 ## Guardrails
 
-- 只产出计划文档，不改业务代码、不做实现
-- 不绕过 `## 待用户确认` 中的未确认项
-- tdd_required 标注真实
-- 不跳过 transition
-- 不跳过完整审查路径下的审核工作项
-- 审查通过后、推进前不做非必要的文档编辑；计划材料变更会按当前审查模式和角色职责触发必要的复审。
+- 不绕过未确认的业务决策或返回的独立审查事项。
+- 不把 Impact 当作文件白名单，也不把审查建议当作新需求。
+- 不手写流程推进、审查结论或验证证据。

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-review
-description: "四.执行代码审查和最终验证，推进 accepted"
+description: "在 SuperSpec Review 阶段运行独立代码审查、最终验证并完成交付闭环。适用于 apply 结束后的审查、修复、验证。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,84 +8,25 @@ metadata:
 
 # SuperSpec Review
 
-你是审查阶段。目标是按工作流引擎返回的下一步，完成代码审查、最终验证和 accept。这个阶段用来提高实现质量，不用来增加额外审批负担。
+完成代码审查、最终验证和交付确认；目标是证明本次 change 已满足既定计划，而不是增加审批或需求。
 
-## 驱动方式
+## 工作方式
 
-所有状态由工作流引擎管理，按这个循环执行：
+运行 `superspec transition next --change "<change>"`，以返回的 job packet、角色、提交命令和下一步为准。代码、计划或证据发生变化后重新运行 `next`，不要手动复用旧结论。
 
-1. `superspec transition next --change "<change>"` 获取下一步。
-2. 执行返回的命令，或处理返回的工作项/用户确认。
-3. 登记结果。
-4. 回到第 1 步。
+处理审查或验证工作项时：
 
-如果 next 返回待完成工作项，先完成工作项；如果 next 返回用户确认，先让使用者决策；完成前不要 accept。审查/验证只说明通过与否、阻塞摘要、缺失证据、下一步，以及应回 apply 还是 propose；验收通过并进入 accepted 时，说明本轮流程已经完成。
+1. 打开 job packet，确认当前范围、引用材料和停止条件。
+2. 启动指定的独立角色做只读判断；主流程不替代该角色重审。
+3. 按 packet 返回的命令登记原始报告，报告必须基于真实文件、事件或测试证据。
+4. 重新运行 `next`，让引擎决定修复、复审、验证或交付。
 
-## review-ready 语义
+代码审查发现纯实现问题时，按当前动作回到同一 change 的 apply 追加最小修复；修复采用当前 mode 对应的验证要求。方案、需求或混合问题需要主流程按证据区分处理方向，不能擅自选择改代码还是改计划。最终验证通过后，只有 `next` 明确给出交付动作时才交付。
 
-`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 返回代码审查或最终验证工作项：
-
-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 返回的命令回到计划阶段或实现阶段。
-
-最终验证结果处理：
-
-- 最终验证通过：执行 next 下发的 accept 命令。
-- 最终验证未通过：报告会保全原始报告引用和问题列表。按报告中的问题修复或回退；不要直接 accept。
-
-## accept 和 accepted 后返工
-
-- 只有状态为 `review`，且 `next` / `review-ready` 要求的审查或验证已满足时，才执行 accept。
-- `accepted` 是正常完成终态，next 不再继续推进。
-- 使用者补充、修正或扩展方案、需求、验收或实现约束时，主流程先确定唯一对应的 change 并读取真实状态；只有该 change 当前为 accepted，才按 next 返回的内部 continuation 自动把用户内容概括为 reason 并回到 propose。无法唯一确定 change 时只询问补充属于哪个 change；不要让使用者选择工作流动作，也不要要求使用者执行命令。
-- 如果只是问答、致谢或不改变方案含义的说明，保持 accepted，不触发状态变化。
-- 不从 accepted 直接回 apply；回到 propose 后先修改计划材料，再按 next 重新完成计划审查、实现、代码审查和最终验证。
+用户新增或改变需求、验收、兼容或实现约束时，先回到对应 change 的 propose 更新计划；不把自然语言补充直接作为编码授权。问答、致谢或不改变方案含义的说明不触发返工。
 
 ## Guardrails
 
-- 审查阶段只读，不改业务代码。
-- 不绕过 `next` / `review-ready` 要求的代码审查或最终验证。
-- 主流程不重审代码，只复核代码审查报告是否可登记、问题是否可分流、回退和闭环证据是否存在。
-- 涉及代码审查问题回退时，以 next 当前返回为准，不手动套用旧 job 或旧问题编号。
-- 不把 accepted 后的新需求直接当作 apply 授权，必须先 reopen 到 propose。
-- 审查和验证报告必须引用真实文件、事件或测试证据，不编造。
-- 不跳过 transition。
+- 不绕过引擎要求的审查、验证、确认或修复。
+- 不手写状态推进、报告结论或伪造证据。
+- 审查报告必须基于真实文件、事件或测试证据；建议不自动升级为新需求。