@peterxiaoyang/superspec 0.1.38 → 0.1.39

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

@@ -27,15 +27,15 @@ metadata:
 
 每个 task 的标准循环：
 
-1. **计划核对**：执行 `task-start` 前，确认当前 task 是 `tasks.md` 顶格任务，并能对应 `design.md` 的实现方向和 `proposal.md` 的 `## Impact` 受影响原因。缺少映射、需要新增能力/验收/影响范围时先停止，交回 propose，不写 RED。
-2. **任务开始**：`superspec transition task-start --change "<change>" --task <task_id>`。
-3. **读取 attempt_id**：从 task-start 返回结果或当前活跃 task attempt 中读取。
-4. **RED**：写测试前确认测试意图能对应 `test-contract.md` 的 `test_id` 或 `business-invariants.md`；缺少对应关系时先停止，交回 propose。运行后确认失败，并用 `superspec record test-run --change "<change>" --input -` 登记。
+1. **计划核对**：执行 `task-start` 前，确认当前 task 是 `tasks.md` 顶格任务。task 带 `执行依据:` 块时，以它为主要执行上下文；没有执行依据的历史 task 对应 `design.md` 的实现方向和 `proposal.md` 的 `## Impact` 受影响原因。缺少映射、需要新增能力/验收/影响范围时先停止，交回 propose，不写 RED。
+2. **任务开始**：执行 next 下发的 task-start 命令。
+3. **读取执行依据快照**：task-start 的返回结果包含本次任务尝试 ID（`attempt_id`，登记测试时要用）和执行依据快照（五字段在启动时刻的定格版本）。返回结果带快照时，实现和验收以它为准；返回结果标明是历史任务（`legacy_contract`）时，即使 `tasks.md` 里有执行依据文本也不采纳为引擎契约，按原有方式回读 `proposal.md`、`design.md` 和 `test-contract.md`，test-run 走历史规则。
+4. **RED**：执行依据声明了测试时，测试必须对应其中的 `TEST-xxx`（登记其他 TEST 会被拒绝）；没有执行依据的历史 task 确认测试意图能对应 `test-contract.md` 的 `test_id` 或 `business-invariants.md`，缺少对应关系时先停止，交回 propose。运行后确认失败，并用 `superspec record test-run --change "<change>" --input -` 登记。
 5. **实现**：根据任务写代码，保持范围小。`design.md` 不锁死字段名、函数名、SQL 或局部写法。
-6. **GREEN**：运行测试确认通过，并登记 test-run。
-7. **完成 task**：`superspec transition task-complete --change "<change>" --task <task_id>`。
+6. **GREEN**：运行测试确认通过，并登记 test-run。执行依据声明多个测试时，每个声明 TEST 都要有 GREEN；普通 `tdd_required:true` task 还要求至少一个 TEST 形成同 TEST 先 RED 后 GREEN，其余可以只有 GREEN 作为回归覆盖。
+7. **完成 task**：执行 next 下发的 task-complete 命令。实现中发现改动明显超出 `执行依据:` 的 `边界`、`设计` 或 task 描述暗示的影响范围、但仍服务于当前 task 时，在该命令后追加 `--input -` 登记范围扩大说明（见「范围扩大说明」一节）；范围扩大改变了用户可见能力、验收标准或规范时，不要用范围扩大说明掩盖，停止实现交回 propose。
 
-no-TDD 任务（`tdd_required:false` + `no_tdd_reason`）跳过 RED/GREEN，但仍必须有清楚的完成证据。
+no-TDD 任务（`tdd_required:false` + `no_tdd_reason`）不要求 RED/GREEN 配对，但仍必须有清楚的完成证据。注意：如果该任务的 `执行依据:` 声明了 `测试`，每个声明 TEST 仍需登记一次通过证据才能完成，否则 task-complete 会被拒绝（特征化任务即 `no_tdd_reason:characterization`——为固化既有行为而写保护测试的任务——用特征化通过状态登记，其余用普通通过状态，取值见「test-run 输入」）。
 
 `tasks.md` 不写 RED/GREEN 命令、断言或预期输出。RED/GREEN 的真实证明来自 apply 阶段实际执行后登记的 `record test-run`。
 
@@ -49,7 +49,6 @@ no-TDD 任务（`tdd_required:false` + `no_tdd_reason`）跳过 RED/GREEN，但
 {
   "test_id": "TEST-XXX",
   "attempt_id": "ATT-TASK-XXX-...",
-  "task_structure_digest": "<当前 task 结构版本>",
   "command": "npm test",
   "cwd": "<工作目录>",
   "exit_code": 1,
@@ -59,15 +58,39 @@ no-TDD 任务（`tdd_required:false` + `no_tdd_reason`）跳过 RED/GREEN，但
 
 证据规则：
 
-- `record test-run` 入库至少需要 `test_id` 和 `task_structure_digest`；RED/GREEN 完成判定优先核对当前 `attempt_id`。
+- task 带执行依据时，示例中的六个字段全部必填，且 `test_id` 必须属于执行依据声明的测试。没有执行依据的历史 task 沿用旧规则：至少需要 `test_id` 和 `task_structure_digest`（当前 task 结构版本）。
 - `attempt_id` 来自当前 task attempt；新产生的 TDD 证据必须带当前 `attempt_id`。
-- `semantic_status` 使用 `expected_failure`（RED）/ `expected_success`（GREEN）/ `characterization_pass`。
+- `semantic_status` 使用 `expected_failure`（RED，要求 `exit_code != 0`）/ `expected_success`（GREEN，要求 `exit_code == 0`）/ `characterization_pass`（要求 `exit_code == 0`，且只有 `tdd_required:false no_tdd_reason:characterization` 的 task 可以使用）。
 - `covers_task_ids` 可选，只在回归或等价场景中填写到同一份 test-run JSON，用来说明这次测试覆盖了哪些已完成任务；省略表示不声明覆盖关系。
 - `command`、`cwd`、`exit_code` 和目标测试身份必须能说明目标测试确实运行。
 - 退出码本身不等于证明；环境错误或构建失败不算 RED 或 GREEN。
-- 缺少 `attempt_id`、只靠 `task_structure_digest` 匹配的 test-run 只能作为弱引用，不作为强证明。
+- 缺少 `attempt_id`、只靠 `task_structure_digest` 匹配的旧 test-run 只能作为弱引用，不作为强证明。
 - 其他可选字段只有在有明确来源时再填；不要为通过校验编造。
 
+## 范围扩大说明
+
+实现时发现必须扩大影响范围（本次改动明显超出执行依据的 `边界`、`设计` 或 task 描述的暗示），且仍服务于当前 task 时，在 next 下发的 task-complete 命令后追加 `--input -`，从 stdin 传入 JSON（四个字段全部必填，`verification` 为非空字符串数组，格式不合法时引擎会说明原因并拒绝完成）：
+
+```json
+{
+  "scope_note": {
+    "reason": "为什么需要超出原执行依据的边界",
+    "changed_area": "实际扩大的代码或行为范围",
+    "plan_alignment": "扩大后仍如何服务于当前 task 或原设计",
+    "verification": ["TEST-001", "覆盖该变化的其他说明引用"]
+  }
+}
+```
+
+- 这是完成 task 时的一次性说明，task 完成后不能补写；需要说明但没写的，会被代码审查作为问题提出。不要为了通过校验编造字段。
+- 范围扩大改变了用户可见能力、验收标准或 OpenSpec 规范时，不适用本机制，交回 propose。
+
+## 测试覆盖豁免
+
+进入审查前，`test-contract.md` 中每个 TEST 要么绑定到某个 task 的 `测试` 字段，要么有用户豁免决策。被阻断提示某个 TEST 未绑定时，先向用户确认原因（不要代替用户决策），再按阻断消息给出的命令和格式登记。注意：计划文档里写了不覆盖理由不等于已豁免，引擎只认已登记的用户决策。
+
+以上两种登记在向用户沟通时都用人话说明（如"这次实现比计划多改了导出列，原因和验证已记录在案"、"测试契约里的 TEST-003 没有任务实现它，请确认是否豁免及原因"），不要原样复述命令、JSON 字段或内部事件。
+
 ## Guardrails
 
 - 只改当前 task 范围相关的实现或测试文件。

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

@@ -8,101 +8,102 @@ metadata:
 
 # SuperSpec Explore
 
-你是探索阶段。职责：调查现状、梳理范围、识别风险，把结果沉淀到 `discovery.md`。不写业务代码，不提前写 proposal/specs/design/tasks。
+职责：只读调查现状、梳理范围、识别风险，并把结论写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`。
 
 ## 驱动方式
 
-所有状态由工作流引擎管理。循环：
+所有状态由工作流引擎管理：
 
-1. `superspec transition next --change "<change>"` 获取下一步
-2. 执行返回的命令
-3. 登记结果
-4. 回到 1
+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。
 
-如果下一步说明 discovery 不完整或有未确认问题，先检查并填写 discovery 草稿，不要把草稿占位、格式缺口或路径空白直接转问用户；用户明确说 PRD、文档、原型或其它需求源已更新时，先重新核对来源，不要复用旧依据；只有影响范围、验收标准、用户可见行为、数据来源或安全边界存在真实阻塞时才向用户提问，收到回答后优先用 `superspec record user-decision --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback。
+如果 next 提示 discovery 不完整或有未确认问题，先检查并填写 discovery，不要把草稿占位、格式缺口或路径空白直接转问用户。用户明确说 PRD、文档、原型或其它需求源已更新时，先重新核对来源，不复用旧依据。什么未知该进 `## 待确认问题`，判定标准见「写作规则」。
 
-本技能默认走完整审查路径。探索完成后，`explore → propose` 会先创建 `critic` 工作项，由 Critic 角色审查需求澄清记录。审查完成后优先通过 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 登记 JSON 报告内容；文件路径模式仍可作为 fallback。
-
-## 本阶段做什么
-
-1. **建立事实基线**：读代码、查架构、理解当前系统行为（只读）
-2. **写 discovery.md**：首次进入 explore 时引擎可能已创建草稿；必须用真实事实替换草稿标记和占位内容
-3. **澄清歧义**：有阻塞歧义时向用户提问
+执行推进类命令前，对照 critic 的 Discovery 审查阻塞条件快速自检（非穷尽）：锚点可核验、链路表完整且状态为枚举值、完成判定可判定、未知去向明确、已勾选问题有行内结论。自检不替代审查工作项，只为减少驳回往返。
 
 ## 探索分工
 
-主会话负责广度：理解用户需求、提出探索问题、汇总 discovery、判断哪些问题必须问用户。
-
-涉及多个文件、模块、入口或文件类型时，使用 `explore` subagent 做只读深扫。以下情况也应使用：
-
-- 当前行为不清楚
-- 涉及状态机、公共 API、数据格式、测试策略、权限、迁移或发布流程
-- 影响范围可能大于用户表述
-
-可跳过 subagent 的场景：
+主会话负责理解需求、提出探查问题、汇总 discovery、判断哪些未知必须问用户；默认必须启动 `explore` subagent 做只读深扫，避免只按用户表述或局部代码自行判断影响范围。仅纯文档、明显 typo、单文件机械小修、明确无代码影响可跳过 subagent，跳过时在 discovery 说明原因。
 
-- 纯文档
-- 明显 typo
-- 单文件机械小修
-- 明确无代码影响的需求
+给 subagent 的深扫任务书按此骨架下达，缺项会直接拉低深扫质量：
 
-跳过时在 discovery 中说明原因。`explore` subagent 只输出代码/文档事实、文件行号锚点、隐性约束、影响范围候选、风险和需要主流程确认的问题；不写方案、不写业务代码、不替主流程做决策。
+```text
+目标：<本次要回答的探查问题，一句话>
+需求原话：<用户原话或 PRD 关键句，不转述>
+已知锚点：<已确认的 path:line 或文档锚点；没有写“无”>
+参考：<PRD/需求文档/artifact 路径；没有写“无”>
+必查：<正向搜索的具体搜索词（字段名/枚举/路由/文案）> + 反向调用/入口面检查；
+      按链路五要素枚举上游来源、规则变形、持久化语义、下游消费者、视图差异；
+      运行时数据依赖按 IDC 追到 producer 侧最后一次变形处
+返回：已确认事实 / 基于锚点的推断 / 未知及是否阻塞 / 影响范围候选 / 风险 / 需主流程确认的问题；全部带发现方式和证据锚点
+边界：只读，不写方案；“未发现”只能写按哪些发现方式未发现
+```
 
-## discovery.md 格式
+subagent 结论写入 discovery 前，抽验决定影响范围判断的关键 `path:line` 锚点；核验不了的降级为推断或未知，不写成事实。
 
-写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`：
+## discovery.md 契约
 
 ```markdown
 # Discovery
 
 ## 需求理解
-- 用户目标
+- 用户原话/明确目标、当前实现差异、基于证据的推断；未确认的业务语义不要写成事实
+- 完成判定：用户可见行为的验收口径（改动前/后对比）；定不下来的部分进 `## 待确认问题`
 
 ## 现状
-- 当前系统怎么工作  src/path.ts:10
+- 当前系统如何工作
 
 ## 影响范围
-- 可能受影响的代码表面和相邻风险
+- 受影响的代码表面、相邻模块和风险
+
+## 链路五要素
+| ID | 发现方式 | 上游来源 | 规则变形 | 持久化语义 | 下游消费者 | 视图差异 | 未知/排除 | 证据 | 状态 |
+|---|---|---|---|---|---|---|---|---|---|
+| CHAIN-001 | rg 字段名 + 调用方反查 | 配置/输入/历史数据 | 计算/过滤/兜底/无 | 落库含义/不落库 | 详情/APP/报表/导出/定时任务/无 | 计算/展示/统计/回放是否一致 | 未知项或排除理由 | src/path.ts:10 | 已确认 |
 
 ## 风险和边界
-- 技术风险、依赖、兼容性；尽量绑定代码或文档锚点
+- 技术风险、依赖、兼容性，绑定代码或文档锚点
 
 ## 输入数据来源核查
-- 默认必做。无运行时数据依赖(纯文档/改名/配置)写明具体原因;有依赖见下方表格逐项核查。
-
-## 待确认问题
-- [ ] 问题1的描述
-- [ ] 问题2的描述
-```
-
-**重要**：`- [ ]` 标记的待确认问题必须全部解决（用户确认后改为 `- [x]` 或删除），否则工作流引擎会阻止推进到 propose。
-只有 `## 待确认问题` 段落内的 `- [ ]` 表示阻塞确认项。其他段落列事实、风险或影响范围时使用普通 bullet，不要用 checklist。
-
-代码影响型需求的 `当前代码事实`、`影响范围候选`、`风险和边界` 应尽量包含 `path:line` 锚点。纯文档、配置或新文件任务没有代码锚点时，写明 `N/A` 理由并引用相关文档、配置或需求来源。
-有源码/文档锚点、命令输出或用户确认直接支撑的内容，才写成事实；只有间接锚点支撑的，写为推断并说明依据；没有支撑的，写为未知并说明是否阻塞。影响范围、验收、用户可见行为、数据来源或安全边界的未知必须进入待确认问题，或说明非阻塞理由。
-
-### 输入数据来源核查
-
-默认必做,不是可选项。`## 输入数据来源核查` 段必须存在:
-
-- 无运行时数据依赖(纯文档/改名/配置):一行写明**具体原因**,不是"无依赖"三个字。
-- 有运行时数据依赖:按下表逐项核查。
+- 无运行时数据依赖：写明具体原因。
+- 有运行时数据依赖：按表核查。
 
 | 核查ID | 消费位置 | 必需输入 | 数据来源 | 区分依据 | 状态/理由 |
 |---|---|---|---|---|---|
-| IDC-001 | 入口/规则/算法 | 字段/集合/枚举/状态 | 查询/组装/过滤/缓存/转换位置 | 见下 | 已证明 / 未知阻塞 / 未知非阻塞 |
+| IDC-001 | 入口/规则/算法 | 字段/集合/枚举/状态 | 查询/组装/过滤/缓存/转换位置 | 断点/日志/反例/静态锚点 | 已证明 / 未知阻塞 / 未知非阻塞 |
+
+## 待确认问题
+- [ ] Q-001 [验收] 结算价按原始值还是换算值展示？影响：详情页与报表口径（CHAIN-002）。选项：A 原始值（现状、无迁移）/ B 换算值（需回填历史）。建议 A：报表现有消费按原始值聚合
+- [ ] Q-002 [数据来源] status 字段的业务口径以哪份文档为准？需要用户指认来源；阻塞 IDC-001 判定
+```
 
-- `数据来源` 追到 producer 侧目标字段**最后一次变形处**(查询、组装、过滤、缓存、转换);停在 consumer、validator、DTO 名或机械一跳上游,不算追到。
-- `区分依据` 必须是**可证伪观测**(断点、日志、反例、静态锚点),能区分"规则算法错"和"输入数据缺"。`代码审查` / `见上` / `对照实现` 这类不可证伪写法不合格。
-- `未知阻塞`(影响目标行为成立)必须同时进 `## 待确认问题` 的 `- [ ]`,否则引擎不拦。
-- `未知非阻塞` 必须写明为何不影响验收并绑定验收口径或反例;理由缺失按 `未知阻塞` 处理。
+## 写作规则
+
+- 事实必须有源码/文档锚点、命令输出或用户确认支撑；推断要写依据；未知要说明是否阻塞。
+- 不要把自己的理解当成用户需求：用户没有明确说、代码/文档也不能证明的业务语义、验收口径、默认值、边界条件和优先级，只能写为“推断”或“未知”。
+- 代码影响型需求尽量提供 `path:line`；纯文档/配置/新文件无代码锚点时写明 `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]` 并注明理由，不要删除问题行。
 
 ## Guardrails
 
-- 不改业务代码
-- 不写 proposal/specs/design/tasks
-- 不跳过 transition 直接编辑状态文件
-- 用户未确认的决策不自行推断
-- 完整审查路径下不跳过 `critic` 角色审查
+- 不改业务代码。
+- 不写 proposal/specs/design/tasks。
+- 不跳过 transition。
+- 不跳过完整审查路径下的审查工作项。
+- 用户未确认的决策不自行推断。
+- 审查通过后、推进前不做非必要的文档编辑；文档变更会作废已通过的审查并触发重审。

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

@@ -12,30 +12,25 @@ metadata:
 
 ## 驱动方式
 
-所有状态由工作流引擎管理。循环：
+所有状态由工作流引擎管理：
 
-1. `superspec transition next --change "<change>"` 获取下一步
-2. 执行返回的命令
-3. 登记结果
-4. 回到 1
+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` 三个独立审查工作项完成；审查必须由独立角色执行，不能由主流程自审代替，报告按工作流返回的格式提交并记录实际审查来源。
 
-如果下一步需要审查，先按返回的审查说明完成对应审查，再优先用 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 提交 JSON 审查报告内容；文件路径模式仍可作为 fallback。
+什么问题需要用户确认，判定标准见「待用户确认」一节；就绪或审查后向用户只概括任务可验证性、关键风险/证据覆盖和下一步。
 
-人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。
-如果 OpenSpec 生成文档语言不符合预期，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。
+执行 propose-ready 前，对照 critic / architect / test-engineer 的阻塞条件快速自检（非穷尽）：Impact 与 CHAIN/IDC 对账、specs 增量与 proposal 能力变化互相对应、design 路线能推出 tasks、DEC 已有行内结论并回写、task 粒度单一行为且顺序可执行、每个普通 TDD task 有完整可定位的 `执行依据:`（声明的 TEST 都存在于 test-contract，`边界`/`原因` 具体到该 task 而非套话）、不变量可证伪且覆盖核心行为变化、test-contract 覆盖已引用的 CHAIN、test-contract 中未绑定任何 task 的 TEST 有明确取舍（绑定到 task 或留待用户豁免决策）。自检不替代审查工作项，只为减少驳回往返。
 
-本技能默认走完整审查路径。计划阶段进入实现前，工作流会要求 `critic`、`architect`、`test-engineer` 三个独立审查完成。
-
-所有审查工作项必须由独立角色 reviewer 执行，不能由主流程自审代替；报告必须按工作流返回的格式提交，并记录实际审查来源。
+人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。OpenSpec 生成文档语言不符合预期时，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。
 
 ## 本阶段做什么
 
 ### proposal.md
-使用 OpenSpec proposal 原生结构。正文使用简体中文。
-
-SuperSpec 只增加一个轻量要求：在 OpenSpec 原生 `## Impact` 段落中，必须能看出受影响范围和原因。推荐写成：
+使用 OpenSpec proposal 原生结构，说明为什么做、做什么、能力变化和影响范围。`## Impact` 段落必须能看出受影响范围和原因，推荐写成：
 
 ```markdown
 | Area | Reason |
@@ -44,28 +39,31 @@ SuperSpec 只增加一个轻量要求：在 OpenSpec 原生 `## Impact` 段落
 ```
 
 规则：
-- `proposal.md` 说明为什么要做、做什么、能力变化和影响范围
-- `Area` 可以写代码区域、API、依赖、系统、配置或文档
+- `Area` 可以写代码区域、API、依赖、系统、配置或文档；不作为路径白名单
 - `Reason` 只解释为什么该范围受影响，不写详细实现方案
 - discovery 含 `## 输入数据来源核查` 的 IDC 项时，相关 `Reason` 须引用对应 `IDC-xxx` 状态（`已证明` / `未知阻塞` / `未知非阻塞`）
-- `Area` 不作为路径白名单
+- discovery 含 `## 链路五要素` 时，`## Impact` 须与非 `未知阻塞` 链路行中已确证的下游消费者/视图差异对账：受本次改动影响的写入 Area/Reason 并引用对应 `CHAIN-xxx`；不受影响的在 `## Impact` 中写明排除理由（可按组书写，排除理由不回写 discovery.md）。对账不要求逐行进入 Impact；同一链路已由 `IDC-xxx` 覆盖时，引用其一并注明对应即可
 - 不写任务拆分
-- 只有存在阻塞确认项时才增加 `## 待用户确认`
 
 ### specs/
 OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 
+规则：
+- `specs/` 只放 Markdown 规范文件，非 `.md` 文件不纳入审查绑定
+- `proposal.md` 声明的每个能力变化都有对应规范增量；specs 不引入 proposal 未声明的能力变化
+- 规范写系统应满足的行为要求和场景，不写实现路线（实现路线属于 design.md）
+- specs 归档时会合入长期规范，是本次变更留下的长期资产：requirement / scenario 正文按变更后的目标状态书写，不写「本次改动」「原来是 X 现在改成 Y」这类过程性描述；OpenSpec 增量结构标题（ADDED/MODIFIED/REMOVED/RENAMED）照常使用
+
 ### design.md
-使用 OpenSpec design 原生结构。正文使用简体中文。
+使用 OpenSpec design 原生结构，写技术方案、关键决策、替代方案和风险取舍。
 
 规则：
-- `design.md` 写技术方案、关键决策、替代方案和风险取舍
-- 在上述内容中补充实现方向；每个代码影响型需求说明采用的路线，如复用现有链路、改接口、加表、发消息、定时任务或查询聚合
+- 每个代码影响型需求说明采用的路线，如复用现有链路、改接口、加表、发消息、定时任务或查询聚合
 - 实现方向只到路线级；不写字段名、函数名、SQL、类名或逐步代码。路线无法确定时写入 `## 待用户确认`
 - 不复制 `proposal.md` 的影响范围表
 - 不写任务拆分
 - discovery 含 `## 输入数据来源核查` 且影响设计成立时，记录输入完整性决策；相关 `IDC-xxx` 为 `未知阻塞` 时设计不得标 ready
-- 只有存在阻塞确认项时才增加 `## 待用户确认`
+- discovery 含 `## 链路五要素` 时，实现方向不得基于与已确证链路事实不符的现状假设，例如上游已完成的处理在下游重做兜底（确需重复防御时写明理由）；有意变更已确证的规则变形或持久化语义时，在 design.md 写明该变更属于本次目标
 
 ### tasks.md
 使用 OpenSpec tasks 原生分组结构。每个顶格 checkbox 行是一个 SuperSpec 可执行 task，Markdown 标题只用于分组。
@@ -76,7 +74,19 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 ## Review verifier
 
 - [ ] 1.1 检查 verifier 绑定文档 tdd_required:true
+  执行依据:
+  - 测试: 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
 
@@ -84,16 +94,23 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 ```
 
 规则：
-- 标题只分组，不是可执行 task；标题不要包含可执行 task id token，例如不要写 `## 1.1 Review verifier`
-- 顶格 `- [ ] <task_id> ...` 才是可执行 task，`<task_id>` 可以是 `1.1` 或 `TASK-001.1`
-- 每个可执行 task id 必须唯一、稳定
-- 不展示、不推荐缩进 checkbox；task 内部步骤用普通 bullet，不用 checkbox
+- 每个普通 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]`），否则会变成无人执行的暗任务并被引擎拒绝
+- 引用使用带文件前缀的可定位格式；`设计`、`来源`、`边界` 的标题或短摘录引用逐项写完整文件前缀，只有 ID 型引用（TEST/CHAIN/IDC）可以逗号合并
+- 声明的每个 `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 阶段执行，并通过 `record test-run` 绑定到 attempt
+- task 行只标记是否需要 TDD，不写 RED/GREEN 命令、断言或预期输出；实际 RED/GREEN 由 apply 阶段执行并记录
 - 一个 task 对应一个可独立验证的行为变化，或一个明确的非行为改动
-- 多个行为变化、多个入口、多个运行时模块混在一起，且不能形成同一个 RED/GREEN 闭环时，应拆开
-- 如果一个 task 需要“顺便”改很多不相邻模块，应在 propose 阶段重新拆分或补充任务，不留到 apply 阶段扩大范围
+- 多个行为变化、入口或运行时模块不能形成同一个 RED/GREEN 闭环时拆开；需要“顺便”改多个不相邻模块的 task 在 propose 阶段就拆分或补充任务，不留到 apply 阶段扩大范围
+- 任务按可执行顺序排列：引擎忽略标题、按全文顶格 checkbox 行的先后顺序逐个驱动执行，被依赖的任务必须排在依赖它的任务之前，跨组同样如此（顺序与分组冲突时调整任务归组或拆组）；跨组依赖可在任务行内注明依赖的 task id 作为提示，但注明不改变执行顺序
 
 ### business-invariants.md
 格式：
@@ -105,6 +122,10 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 - INV-002 订单金额不能为负数
 ```
 
+规则：
+- 不变量是本次改动必须保持或新确立的业务规则，必须可违反、可验证——存在能让它失败的具体操作和可观察结果；「系统应稳定」「代码应可维护」这类不可证伪的陈述不算
+- 覆盖本次行为变化触及的核心规则即可，不堆砌与本次改动无关的通用约束
+
 ### test-contract.md
 格式：
 
@@ -113,10 +134,12 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 
 | test_id | invariant | scenario |
 |---|---|---|
-| TEST-001 | INV-001 | 注册时密码被加密 |
-| TEST-002 | INV-002 | 订单金额为负时拒绝 |
+| TEST-001 | INV-001 | 注册时提交明文密码，落库字段为加密值且不含明文 |
+| TEST-002 | INV-002 | 已登录用户提交金额为 -1 的订单，下单被拒绝并返回校验错误 |
 ```
 
+scenario 写到能推导断言的程度：给定什么条件、发生什么动作、观察到什么结果；不写测试命令和断言代码。「验证功能正常」这类无法推导断言的写法不合格。
+
 如果 discovery 含 `## 输入数据来源核查` 的 IDC 项，在测试表后增加 `## 输入数据覆盖验证`：
 
 | 核查ID | 验证方式 | 输入链路声明 | 证据或计划 |
@@ -125,24 +148,22 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 
 证明方式可用源码锚点、fixture、targeted test、日志或 trace，须说明证明力；不强制集成测试。只证 consumer 算法、没证 producer→consumer 输入完整性，测试契约不足。
 
+discovery 含 `## 链路五要素` 时，`proposal.md` `## Impact` 中引用的 `CHAIN-xxx` 应映射到测试场景（scenario 内引用对应 `CHAIN-xxx`），或在测试表后写明不覆盖理由。
+
 ### 待用户确认
-如果计划阶段遇到会影响需求范围、验收标准、用户可见行为、方案取舍、测试策略、安全、权限、数据或迁移判断的关键不确定问题，先写入相关计划文档的 `## 待用户确认` 段落：
+遇到会影响需求范围、验收标准、用户可见行为、方案取舍、测试策略、安全、权限、数据或迁移判断的关键不确定问题，先写入相关计划文档的 `## 待用户确认` 段落；没有阻塞确认项的文档不加该段落：
 
 ```markdown
 ## 待用户确认
 
-- [ ] DEC-001 是否需要兼容历史行为？
+- [ ] DEC-001 [方案] 是否需要兼容历史行为？影响：迁移成本与验收口径（CHAIN-003）。选项：A 兼容（加开关、保留旧路径）/ B 不兼容（一次性迁移）。建议 A：存量数据仍被报表消费
 ```
 
-`next` 会在 propose 阶段检查 `proposal.md`、`design.md` 和 `test-contract.md` 的该段落。存在未确认项时，先向用户提问；收到回答后将 JSON 内容通过 stdin 登记：
-
-```bash
-superspec record user-decision --change "<change>" --input -
-```
+每个确认项只含一个决策点，带稳定 ID `DEC-xxx`：决策类写明影响面（引用相关 `CHAIN-xxx` / `IDC-xxx`）、候选项及后果、建议默认值及理由；事实类写明需要用户提供什么信息、为什么阻塞。选项和补充说明用普通文本或普通 bullet，不要写成 `- [ ]`，引擎会把它们计为未确认项。
 
-文件路径模式仍可作为 fallback。
+`next` 会在 propose 阶段检查 `proposal.md`、`design.md` 和 `test-contract.md` 的该段落。存在未确认项时，汇总一次向用户提问（按影响排序并说明问题间依赖，不逐个往返）；收到回答后用驱动方式中的 `record user-decision` 命令登记，JSON 经 stdin 传入（scope 建议引用 `DEC-xxx`，一条决策可列多个 ID；此为留痕约定，引擎不校验格式）。
 
-然后把用户决定反映到 proposal/design/test-contract，并将对应确认项改为 `[x]` 或移出未确认列表。局部实现细节、命名、普通文件组织和不影响需求/验收/风险的技术微调不要升级为用户确认。
+答案来自用户时，先登记再勾选；答案来自需求文档、代码证据等外部事实核对时，行内写明证据来源，不伪造用户决策。用户回答含糊、与候选项不匹配或引出新问题时，不视为已确认；复述理解并获得明确答复后再登记。把结论反映到 proposal/design/test-contract 相关内容，勾选行内注明结论要点；确认项作废或重复时改为 `[x]` 并注明理由，不要删除确认项。局部实现细节、命名、普通文件组织和不影响需求/验收/风险的技术微调不要升级为用户确认。
 
 进入 propose 后出现新的业务规则、产品口径、验收标准、示例规范或需求源更新时，不要静默覆盖原计划；默认先在 `proposal.md` 记录 `## 需求变化`，说明变化来源、变化内容、影响范围和处理方式（更新当前 change / 新建后续 change / 暂不处理）。只有影响技术路线、测试契约或业务不变量时，才同步更新 `design.md`、`test-contract.md` 或 `business-invariants.md`。
 
@@ -152,9 +173,9 @@ tasks.md 作为计划文档就绪（不是复选框全完成）+ 基础职责文
 
 ## Guardrails
 
-- tasks.md 只列任务，不实现
+- 只产出计划文档，不改业务代码、不做实现
 - 不绕过 `## 待用户确认` 中的未确认项
-- 不改业务代码
 - tdd_required 标注真实
 - 不跳过 transition
 - 不跳过完整审查路径下的审核工作项
+- 审查通过后、推进前不做非必要的文档编辑；绑定审查的内容（proposal/design/tasks/specs/discovery/business-invariants/test-contract）变更会作废已通过的审查并触发重审。

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

@@ -69,7 +69,7 @@ superspec record job-submit --change "<change>" --job <JOB> --report -
 
 最终验证结果处理：
 
-- 最终验证通过：执行 `superspec transition accept --change "<change>"`。
+- 最终验证通过：执行 next 下发的 accept 命令。
 - 最终验证未通过：报告会保全原始报告引用和问题列表。按报告中的问题修复或回退；不要直接 accept。
 
 ## accept 和 archive