@peterxiaoyang/superspec 0.1.39 → 0.1.41

package/templates/workflow/prompts/critic.md

@@ -40,22 +40,28 @@ argument-hint: "本次反方审查说明"
 
 ## Proposal / Design / Tasks 审查
 
+重点审查计划文档是否完整、一致、可定位和可审查。技术路线优劣、系统边界合理性和绑定性技术契约由 Architect 主责；测试策略和证明力由 Test Engineer 主责。除非缺失已经造成文档无法对应能力、任务或来源，否则不要代替专业角色重复技术判断。
+
 阻塞条件：
 
-- `proposal.md` 缺 `## Impact`，或 `Area / Reason` 不能说明受影响范围和原因。
-- `Impact` 写成任务清单、路径白名单，或 `Reason` 只写“要改这里”。
-- `design.md` 缺路线级实现方向，或写成任务拆分/代码步骤。
-- 关键路线未决却未进入 `## 待用户确认`。
-- `tasks.md` 无法从 `design.md` 推出，任务过粗，或多个独立行为混在同一 RED/GREEN 闭环。
-- task id 重复/不稳定，标题混入 task id，缩进 checkbox 或普通说明承载实际工作。
-- task 中写 RED/GREEN 命令、断言或预期输出。
-- discovery 含 IDC 时，`Impact Reason` 未引用相关 `IDC-xxx`；`design.md` 在相关 IDC 为 `未知阻塞` 时仍声称 ready。
-- 已勾选的 `## 待用户确认` 项无行内结论，或结论未反映到 proposal / design / test-contract 相关内容。
-- discovery 含链路五要素时，非 `未知阻塞` 链路行中已确证的下游消费者/视图差异未进入 `Impact`（引用 `CHAIN-xxx`）也无排除理由；或 `Impact` 引用的 `CHAIN-xxx` 无测试场景映射且无不覆盖理由。对账不要求逐行进入 Impact；同一链路已由 IDC 覆盖且互指的，不重复报错。
-- `design.md` 基于与已确证链路事实不符的现状假设（如重复上游已有处理且无理由），或变更已确证的规则变形/持久化语义却未声明为本次目标。
-- `specs/` 规范增量与 `proposal.md` 能力变化不对应：声明的能力变化缺规范增量、specs 引入未声明的能力变化，或规范正文写成实现路线/过程性描述。`specs/` 以目录形式绑定在审查材料中，须打开目录内的规范文件逐个核对；无法读取时在报告中说明材料缺口并给 `verdict:"fail"`，不得默认通过。
-- `business-invariants.md` 条目不可证伪（不存在能使其失败的具体操作和可观察结果），或本次行为变化触及的核心规则缺少对应不变量。
-- `tasks.md` 任务顺序与依赖矛盾：被依赖的 task（含行内注明的跨组依赖）出现在依赖它的 task 之后。引擎按全文顶格 checkbox 行顺序驱动，标题分组和行内注明都不改变执行顺序。
+- `proposal.md` 缺 `## Impact`，或 `Area / Reason` 无法说明受影响范围和原因；Impact 写成任务清单、路径白名单或纯实现步骤。
+- proposal / specs 必须符合当前 `openspec instructions proposal` 和 `openspec instructions specs` 的原生结构与语义；审查前须在项目根目录运行 `openspec validate <change> --strict --no-interactive`。命令失败，或仍存在原生校验未覆盖的核心结构、Capabilities / BREAKING、delta 操作、完整 MODIFIED requirement、REMOVED Reason / Migration、RENAMED FROM / TO、requirement / scenario 格式问题时必须失败；命令通过不能替代语义审查。
+- `proposal.md` 声明的每个代码影响型能力，无论 specs 是否已完整具体化，都必须能定位到 design 中对应的实现方案；不要求能力与方案一一对应，多个紧密相关能力可以共用方案，只有存在独立技术路线时才要求拆分。design 引入 proposal / specs 未声明的新能力时必须失败。
+- 方案标题只有“策略复用”“数据处理”“接口调整”等泛称，导致审查者无法判断实现什么、采用什么路线。内容等价的 `## 实现路线`、`## 架构决策` 等结构可以接受，不因标题不同失败。
+- 无法从 design 的等价语义判断本次范围边界或各实现方案的总体关系，导致文档不可审查时阻塞。新模板的 `## 非目标` 和 `## 总体方案` 由生成侧保证；审查不机械要求标题，也不在不存在真实非目标时要求用“无”或“不适用”占位。
+- “不采用”、`## 整体方案取舍`、`## 关键契约`、`## 风险 / 取舍`、`## 迁移与回滚` 没有真实内容时应省略；不得仅因缺少可选章节判失败，但空章节、“无 / 不适用”占位或为了模板编造内容应按文档噪声处理。真实技术风险、取舍或迁移约束是否遗漏由 Architect 审查。
+- design 写成 discovery 调查记录、Impact 复述、specs 行为复述、文件浏览记录、task 拆分、测试操作或执行日志。算法、数据 / 控制流、状态转换和事务顺序可以有序表达，不因编号或顺序词失败。
+- 同一事实、约束或契约在多个方案中重复堆叠，导致真实方案差异无法辨识；共享内容应有一个可定位的权威定义。
+- 文档显式标注的未决路线没有登记到 `## 待用户确认`；或已确认 DEC 没有行内结论，结论未回写 proposal、design、specs、test-contract。
+- discovery 含 IDC 时，`Impact Reason` 未引用相关 `IDC-xxx`；IDC 状态、Impact 和 design readiness 相互矛盾；`未知阻塞` 仍存在时 design 不得 ready。`未知非阻塞` 必须有不影响验收的理由，不能只抄状态。
+- discovery 含链路五要素时，已确认的下游消费者或视图差异未进入 Impact 且无排除理由；或 Impact 引用的 `CHAIN-xxx` 没有测试场景映射且无不覆盖理由。design 仅引用 CHAIN 解释路线不重复产生测试映射；design 暴露的新消费者、视图差异或可观察行为影响必须先进入 Impact。对账不要求每条 CHAIN 单独进入 Impact；同一链路已由 IDC 覆盖且互相引用时不重复报错。
+- proposal、design、specs 与已确认的 CHAIN / IDC 结论显式矛盾，且没有声明为待确认或本次有意变更。
+- `specs/` 增量与 proposal 能力变化不对应：声明的能力缺规范增量、specs 引入未声明能力，或规范正文写成实现路线 / 过程描述。绑定为目录时须逐个打开 Markdown 规范；无法读取时必须失败。
+- `business-invariants.md` 条目不可证伪，或本次行为变化触及的核心规则缺少对应不变量。
+- `tasks.md` 无法定位到 design 的实现方案或边界约束，任务过粗，或多个独立行为混在同一 RED/GREEN 闭环。
+- task ID 重复 / 不稳定，标题混入 task ID，缩进 checkbox 或普通说明承载实际工作，task 中写入 RED/GREEN 命令、断言或预期输出。
+- tasks 顺序与依赖矛盾：被依赖 task 出现在依赖它的 task 之后；标题分组和行内依赖说明不改变全文顶格 checkbox 执行顺序。
+- 分组标题、task ID 或任务文本会让执行者容易启动错任务时应失败；不要为弥补拆分不清而要求父子任务状态、额外设计字段或 tasks 反向引用 design。
 
 ### 执行依据审查
 
@@ -68,11 +74,11 @@ argument-hint: "本次反方审查说明"
 - 普通 `tdd_required:true` task 缺 `执行依据:`，或其执行依据缺 `测试` 字段（`tdd_required:false` task 的 `测试` 按需填写，不作为阻塞条件）。
 - 普通 `tdd_required:true` task 的执行依据缺 `设计`、`来源`、`原因` 或 `边界` 字段。
 - 执行依据字段重复，或块内出现 checkbox（会变成无人执行的暗任务）。
-- `设计`、`来源`、`边界` 引用无法定位到原文（对应文件不存在该标题/摘录/ID），或引用不带文件前缀导致无法回读。
+- `设计`、`来源` 引用无法定位到原文（对应文件不存在该标题/摘录/ID），或引用不带文件前缀导致无法回读。`边界` 默认可以直接写具体保护语义，不要求文件前缀；只有它声明引用既有文档原文时，才要求可定位。
 - 声明的 `TEST-xxx` 不存在于 `test-contract.md`。
 - 单个 task 声明的测试超过 3 个但 `原因` 未说明为什么不再拆分；或 `原因` 与 `来源` 明显不支持该 task 的拆分边界。
 - 字段内容是放在任何 task 上都成立的套话（如 `边界` 写"不破坏现有功能"、`原因` 写"需要单独实现"），无法用来对照实现或审查越界；或多个 task 的执行依据互相复制、与各自任务内容不对应。
-- `设计` 引用能定位，但原文内容不支持该 task 的实现路线（引用与任务实质脱节）。
+- `设计` 引用虽可定位，但内容与 task 实质无关时阻塞；引用方案在技术上是否可行、边界是否充分，由 Architect 审查。
 
 ## 输出风格
 

package/templates/workflow/prompts/executor.md

@@ -12,7 +12,7 @@ argument-hint: "本次执行说明"
 ## 读写边界
 
 - 只能修改本次任务说明中 `declared_task_write_scope` 明确列出的实现路径。
-- 不要修改 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`，也不要写正式 evidence、ledger、review report 或 archive artifact。
+- 不要修改 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`，也不要写正式 evidence、ledger 或 review report。
 - 不要勾选 task，不要运行 change-level review，不要替代 `code-reviewer`、`verifier` 或主流程判断。
 - 如果 write scope 缺失、不安全、上下文不足、测试命令不明确或必须扩大范围，停止并报告 blocker。
 - 如果实现过程中发现实际输入数据来源、字段形态或 producer-to-consumer 链路与 discovery 的 `输入数据来源核查` 或 `链路五要素` 不一致，停止扩大实现并报告 blocker；不要在 apply 阶段悄悄补改 proposal/design/test-contract 或扩大任务范围。

package/templates/workflow/prompts/explore.md

@@ -12,7 +12,7 @@ argument-hint: "本次探索说明"
 ## 边界
 
 - 只读；不要修改文件。
-- 必须用 repo search 和文件读取验证事实，结论绑定 `path:line` 或文档锚点。
+- 必须用 repo search 和文件读取验证事实，结论绑定短锚点（类名/文件名:行号）或文档锚点。
 - 不写 `proposal.md` / `design.md` / `tasks.md` / `specs/**` / `.superspec/**`。
 - 不作为 `explore_complete` evidence；门禁审查交给 `critic`。
 - 输出事实、推断、未知、影响范围候选、风险和需要主流程确认的问题；不写实现方案。
@@ -34,7 +34,7 @@ argument-hint: "本次探索说明"
 
 不要把自己的理解当成用户需求。用户没有明确说、代码/文档也不能证明的业务语义、验收口径、默认值、边界条件和优先级，只能写为推断或未知；影响实现或验收的未知交给主流程确认。
 
-代码影响型需求尽量提供 `path:line`。纯文档/配置/新文件没有代码锚点时，写明 `N/A` 理由。
+代码影响型需求尽量提供短锚点，格式为 `ClassName.java:123`、`file.ts:45` 或 `ClassName#method:123`；不要写绝对路径，也不要反复写项目相对长路径。只有短名在当前仓库无法唯一定位时，才加最短必要目录前缀。纯文档/配置/新文件没有代码锚点时，写明 `N/A` 理由。
 
 ## 链路广度探查
 

package/templates/workflow/prompts/test-engineer.md

@@ -19,12 +19,16 @@ argument-hint: "本次测试审查说明"
 
 ## 任务拆分与 RED/GREEN 审查口径
 
-- TDD task 应能形成清晰 RED/GREEN 闭环；`tasks.md` 只声明任务边界和 `tdd_required:true/false`，RED/GREEN 命令、断言或预期输出不写进 `tasks.md`，实际细节属于工作流记录的 test-run 证据
-- 根据 `design.md` 的实现方向判断测试契约是否覆盖主要风险；不要求把测试命令或断言写回计划文档
-- `tasks.md` 存在绑定到 task 的 `执行依据:` 块时，审查执行依据的 `测试` 字段与 `test-contract.md` 场景的对应关系：声明的 `TEST-xxx` 必须存在且其 scenario 确实是该 task 的验收场景；scenario 无法推导断言、或与 task 描述明显不匹配时，应使用失败结论（`verdict:"fail"`）。反向也要核对：task 的主要验收路径（含其 `边界` 声明要保护的行为）没有任何声明测试覆盖且无豁免安排时，按覆盖缺口处理
-- 此时 `test-contract.md` 必须可解析（表头含 `test_id` 和 `scenario`，无重复 `test_id`）；`test-contract.md` 中未绑定任何 task `测试` 字段的 TEST，应有合理说明或留待用户豁免决策，无解释的悬空 TEST 按覆盖缺口处理。注意：文档里写了不覆盖理由不等于已豁免，进入 review 前引擎仍要求登记用户豁免决策
-- 无法定义目标测试身份、RED 失败信号、GREEN 覆盖映射，或只靠退出码/笼统命令证明的测试方案，应使用失败结论（`verdict:"fail"`）
-- `tdd_required:false` 必须有明确 `no_tdd_reason`；只有 `no_tdd_reason:characterization` 的 task 可以在执行阶段以特征化通过作为测试证据
+重点审查设计约束是否可验证，以及 task / design / test-contract 是否形成可信闭环。能力覆盖和文档可审查性由 Critic 主责；技术路线和系统边界由 Architect 主责。
+
+- TDD task 应形成清晰 RED/GREEN 闭环；`tasks.md` 只声明任务边界和 `tdd_required:true/false`，不得写 RED/GREEN 命令、断言或预期输出
+- 根据 design 的实现方案、边界约束、共享契约和真实风险判断 test-contract 是否覆盖主要风险；不要求 design 使用固定字段或可选风险章节
+- task 或 test-contract 场景无法定位到对应实现方案、共享契约或边界约束，因而无法推导测试条件和预期结果时，应失败
+- task 执行依据声明的 `TEST-xxx` 必须存在，scenario 必须确实验收该 task；scenario 无法推导断言、与 task 描述明显不匹配，或 task 的主要验收路径及其边界没有测试覆盖且无豁免时，应失败
+- task 的 `设计` 引用与声明测试必须匹配；测试只覆盖 happy path、没有覆盖方案关键边界、状态转换、优先级、一致性 / 并发 / 兼容约束或真实风险时，应判为覆盖缺口
+- `test-contract.md` 必须可解析，表头含 `test_id` 和 `scenario`，无重复 `test_id`；未绑定任何 task 的 TEST 必须有合理说明或留待用户豁免，不能把文档内的不覆盖理由当成已豁免
+- 测试方案必须能定义目标测试身份、RED 失败信号和 GREEN 覆盖映射；不能只靠退出码或笼统命令证明
+- `tdd_required:false` 必须有明确 `no_tdd_reason`；只有 `no_tdd_reason:characterization` 的 task 可以用特征化通过作为测试证据
 
 ## 输入数据与链路覆盖审查口径
 
@@ -32,7 +36,7 @@ argument-hint: "本次测试审查说明"
 
 可接受的证明方式包括源码锚点、fixture、targeted test、日志或 trace；不强制集成测试，但必须说明证明力。只证明 consumer 算法正确、没有证明目标输入从 producer 进入 consumer 时，应使用失败结论（`verdict:"fail"`）。
 
-`proposal.md` 的 `## Impact` 引用 `CHAIN-xxx`（链路五要素）时，对应的下游消费者/视图差异应映射到 test-contract 场景并在 scenario 中引用该 `CHAIN-xxx`；未映射且无不覆盖理由时，按覆盖缺口使用失败结论（`verdict:"fail"`）。
+`proposal.md` 的 `## Impact` 引用 `CHAIN-xxx`（链路五要素）时，对应的下游消费者/视图差异应映射到 test-contract 场景并在 scenario 中引用该 `CHAIN-xxx`；未映射且无不覆盖理由时，按覆盖缺口使用失败结论（`verdict:"fail"`）。design 仅引用 CHAIN 作为方案依据时不重复产生测试映射要求；若 design 暴露了 Impact 未记录的消费者、视图差异或用户 / 系统可观察行为影响，应先按 Impact 对账缺口处理，再核对对应测试。测试脆弱性、实现复杂度等纯实施风险只在 design / test-contract 内处理，不要求写入 Impact。
 
 `未知非阻塞` 的测试策略必须说明为什么该未知不影响验收；缺少说明时按覆盖缺口处理。
 

package/templates/workflow/prompts/test-runner.md

@@ -11,7 +11,7 @@ argument-hint: "本次测试说明"
 
 ## 读写边界
 
-- 默认只读；不要修改 production code、OpenSpec artifacts、`.superspec/**`、task checkbox、review artifacts 或 archive artifacts。
+- 默认只读；不要修改 production code、OpenSpec artifacts、`.superspec/**`、task checkbox 或 review artifacts。
 - 只能执行本次任务说明中的 `allowed_test_command`，不要发明、改写或补充命令。
 - 只有 test-runner worker 运行结果可以成为正式 RED/characterization/GREEN candidate；不要让主线程代跑或伪造正式 evidence。
 - 如果本次任务说明没有 `allowed_test_command`、`worker_state` 不是 `ready`、命令上下文不足或测试产生未声明副作用，停止并报告 blocker。

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

@@ -34,7 +34,7 @@ metadata:
 ```text
 目标：<本次要回答的探查问题，一句话>
 需求原话：<用户原话或 PRD 关键句，不转述>
-已知锚点：<已确认的 path:line 或文档锚点；没有写“无”>
+已知锚点：<已确认的短锚点（类名/文件名:行号）或文档锚点；没有写“无”>
 参考：<PRD/需求文档/artifact 路径；没有写“无”>
 必查：<正向搜索的具体搜索词（字段名/枚举/路由/文案）> + 反向调用/入口面检查；
       按链路五要素枚举上游来源、规则变形、持久化语义、下游消费者、视图差异；
@@ -43,7 +43,7 @@ metadata:
 边界：只读，不写方案；“未发现”只能写按哪些发现方式未发现
 ```
 
-subagent 结论写入 discovery 前，抽验决定影响范围判断的关键 `path:line` 锚点；核验不了的降级为推断或未知，不写成事实。
+subagent 结论写入 discovery 前，抽验决定影响范围判断的关键短锚点；核验不了的降级为推断或未知，不写成事实。
 
 ## discovery.md 契约
 
@@ -63,7 +63,7 @@ subagent 结论写入 discovery 前，抽验决定影响范围判断的关键 `p
 ## 链路五要素
 | ID | 发现方式 | 上游来源 | 规则变形 | 持久化语义 | 下游消费者 | 视图差异 | 未知/排除 | 证据 | 状态 |
 |---|---|---|---|---|---|---|---|---|---|
-| CHAIN-001 | rg 字段名 + 调用方反查 | 配置/输入/历史数据 | 计算/过滤/兜底/无 | 落库含义/不落库 | 详情/APP/报表/导出/定时任务/无 | 计算/展示/统计/回放是否一致 | 未知项或排除理由 | src/path.ts:10 | 已确认 |
+| CHAIN-001 | rg 字段名 + 调用方反查 | 配置/输入/历史数据 | 计算/过滤/兜底/无 | 落库含义/不落库 | 详情/APP/报表/导出/定时任务/无 | 计算/展示/统计/回放是否一致 | 未知项或排除理由 | path.ts:10 | 已确认 |
 
 ## 风险和边界
 - 技术风险、依赖、兼容性，绑定代码或文档锚点
@@ -85,7 +85,8 @@ subagent 结论写入 discovery 前，抽验决定影响范围判断的关键 `p
 
 - 事实必须有源码/文档锚点、命令输出或用户确认支撑；推断要写依据；未知要说明是否阻塞。
 - 不要把自己的理解当成用户需求：用户没有明确说、代码/文档也不能证明的业务语义、验收口径、默认值、边界条件和优先级，只能写为“推断”或“未知”。
-- 代码影响型需求尽量提供 `path:line`；纯文档/配置/新文件无代码锚点时写明 `N/A` 理由。
+- 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，或写“代码审查/见上/对照实现”，不合格。

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

@@ -23,47 +23,118 @@ metadata:
 
 什么问题需要用户确认，判定标准见「待用户确认」一节；就绪或审查后向用户只概括任务可验证性、关键风险/证据覆盖和下一步。
 
-执行 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 或留待用户豁免决策）。自检不替代审查工作项，只为减少驳回往返。
+执行 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 或留待用户豁免决策）。自检不替代审查工作项，只为减少驳回往返。
 
 人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。OpenSpec 生成文档语言不符合预期时，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。
 
+路径/锚点写法：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/...` 补充材料路径仍按协议保留原始路径。
+
 ## 本阶段做什么
 
 ### proposal.md
-使用 OpenSpec proposal 原生结构，说明为什么做、做什么、能力变化和影响范围。`## Impact` 段落必须能看出受影响范围和原因，推荐写成：
+严格使用 `openspec instructions proposal` 给出的原生结构。`proposal.md` 用于说明为什么需要这个 change、准备改变哪些能力、范围边界和影响面，不负责定义具体实现方案。
+
+规则：
+- `Why` 只说明当前问题、机会、造成的影响和现在需要处理的原因，不提前给出解决路线
+- `What Changes` 以用户或系统可辨识的能力变化为粒度，说明新增、修改或移除什么，已知破坏性变化按 OpenSpec 要求标记 `**BREAKING**`；`Capabilities` 只按原生 New / Modified 分类登记精确 capability 名称和简述，不自创分类
+- 能力变化只描述目标结果和范围，不展开 requirement / scenario，也不写类、函数、字段、算法、数据流、调用顺序或复用机制；这些内容分别属于 specs 和 design
+- 可以说明必须保持不变的相邻能力、兼容边界和高层发布影响，但不为完整而编造非目标；具体迁移顺序、回滚步骤和技术方案属于 design
+- `## Impact` 必须能看出受影响范围和原因，写成：
 
 ```markdown
 | Area | Reason |
 |---|---|
-| src/review.ts | 需要核对 review verifier 如何绑定文档和执行证据 |
+| review.ts | 需要核对 verifier 如何绑定文档和执行证据 |
 ```
 
-规则：
-- `Area` 可以写代码区域、API、依赖、系统、配置或文档；不作为路径白名单
-- `Reason` 只解释为什么该范围受影响，不写详细实现方案
+- `Area` 可以写代码区域、API、依赖、系统、配置或文档；优先使用模块、类、接口等简短定位，不写成待修改文件白名单
+- `Reason` 只解释该范围为什么受影响、会暴露什么变化或承担什么兼容责任，不展开具体实现方案
 - discovery 含 `## 输入数据来源核查` 的 IDC 项时，相关 `Reason` 须引用对应 `IDC-xxx` 状态（`已证明` / `未知阻塞` / `未知非阻塞`）
-- discovery 含 `## 链路五要素` 时，`## Impact` 须与非 `未知阻塞` 链路行中已确证的下游消费者/视图差异对账：受本次改动影响的写入 Area/Reason 并引用对应 `CHAIN-xxx`；不受影响的在 `## Impact` 中写明排除理由（可按组书写，排除理由不回写 discovery.md）。对账不要求逐行进入 Impact；同一链路已由 `IDC-xxx` 覆盖时，引用其一并注明对应即可
-- 不写任务拆分
+- discovery 含 `## 链路五要素` 时，`## Impact` 须与非 `未知阻塞` 链路行中已确证的下游消费者 / 视图差异对账：受本次改动影响的写入 Area / Reason 并引用对应 `CHAIN-xxx`；不受影响的写明排除理由，可按组书写，排除理由不回写 discovery.md。对账不要求逐行进入 Impact；同一链路已由 `IDC-xxx` 覆盖时，引用其一并注明对应即可
+- 不写设计决策、字段归属、测试场景、RED/GREEN 过程、任务拆分、文件修改顺序或执行日志
 
 ### specs/
-OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
+严格使用 `openspec instructions specs` 给出的增量格式。`specs/` 定义 change 完成后系统必须满足的长期行为契约，回答“系统应表现为什么”，不回答“内部如何实现”。
 
 规则：
 - `specs/` 只放 Markdown 规范文件，非 `.md` 文件不纳入审查绑定
 - `proposal.md` 声明的每个能力变化都有对应规范增量；specs 不引入 proposal 未声明的能力变化
-- 规范写系统应满足的行为要求和场景，不写实现路线（实现路线属于 design.md）
-- specs 归档时会合入长期规范，是本次变更留下的长期资产：requirement / scenario 正文按变更后的目标状态书写，不写「本次改动」「原来是 X 现在改成 Y」这类过程性描述；OpenSpec 增量结构标题（ADDED/MODIFIED/REMOVED/RENAMED）照常使用
+- 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 应明确前置条件、触发行为和确定的可观察结果；强制性结果使用 SHALL / MUST，不使用模糊 OR 或「保持原有行为」代替可判定结论。只有可选性本身属于契约时才使用 MAY，并同时写清允许范围和始终成立的不变量
+- 一个 scenario 可以包含同一触发下紧密相关的一组结果，但不得混合多个能够独立失败的责任边界
+- 同一业务规则只保留一个权威 requirement；不同边界情况作为其 scenario，不重复建立语义重叠的 requirement
+- 不写实现路线、测试代码、测试命令、测试数据准备过程或文件修改清单
 
 ### design.md
-使用 OpenSpec design 原生结构，写技术方案、关键决策、替代方案和风险取舍。
+`design.md` 说明“怎么实现”：审查者从目录能看出涉及什么功能、各自采用什么路线；实现者从正文能读出实现机制、影响边界和不能自行决定的关键契约。
+
+```markdown
+# 设计
+
+## 背景
+<本次变更要解决的设计问题，以及会影响技术路线的现状和约束>
+
+## 设计目标
+<本次方案必须达成的技术能力、质量属性和边界>
+
+## 非目标
+- <明确不处理的能力或路线，以及边界原因>
+
+## 总体方案
+<用 2～5 句说明各功能点的关系、主要数据流或调用关系>
+
+## 实现方案
+
+### <功能点、运行阶段或系统边界>：<采用的技术路线或实现结论>
+<用自然段、表格、流程图或必要的伪代码说明实现方式>
+
+<!-- 可选：本方案存在真实可行且容易误走的替代路线时保留 -->
+**不采用：** <替代路线> — <不采用原因>
+
+<!-- 可选：同一取舍横跨多个功能点时保留，否则优先写在对应方案内 -->
+## 整体方案取舍
+| 方案 | 收益 | 代价 | 结论 |
+|---|---|---|---|
+| <方案> | <收益> | <代价> | <采用或放弃原因> |
+
+<!-- 可选：同一契约被多个功能点共享时保留，局部契约写在对应方案内 -->
+## 关键契约
+
+### <契约名称>
+<数据、接口、状态、优先级或一致性规则>
+
+<!-- 可选：选定方案仍有非显然风险或明确接受的代价时保留 -->
+## 风险 / 取舍
+| 风险或代价 | 影响 | 缓解或验证 |
+|---|---|---|
+| <风险> | <可能结果> | <控制方式或测试映射> |
+
+<!-- 可选：涉及数据、配置、协议兼容、版本切换或发布顺序时保留 -->
+## 迁移与回滚
+- <迁移或发布顺序>
+- <兼容窗口>
+- <回滚触发条件和恢复路径>
+
+<!-- 可选：存在阻塞确认项时保留，并使用本文“待用户确认”的 DEC-xxx 格式 -->
+## 待用户确认
+- [ ] DEC-xxx <阻塞决策>
+```
 
 规则：
-- 每个代码影响型需求说明采用的路线，如复用现有链路、改接口、加表、发消息、定时任务或查询聚合
-- 实现方向只到路线级；不写字段名、函数名、SQL、类名或逐步代码。路线无法确定时写入 `## 待用户确认`
-- 不复制 `proposal.md` 的影响范围表
-- 不写任务拆分
-- discovery 含 `## 输入数据来源核查` 且影响设计成立时，记录输入完整性决策；相关 `IDC-xxx` 为 `未知阻塞` 时设计不得标 ready
-- discovery 含 `## 链路五要素` 时，实现方向不得基于与已确证链路事实不符的现状假设，例如上游已完成的处理在下游重做兜底（确需重复防御时写明理由）；有意变更已确证的规则变形或持久化语义时，在 design.md 写明该变更属于本次目标
+- 写 design 前对照 discovery / proposal / specs，把影响实现的事实和约束转成具体安排；不记录调查过程，不复制 Impact、specs 行为、discovery 证据或 tasks 拆分。
+- `## 实现方案` 是主体。代码影响型需求必须能映射到可定位的方案，但不要求需求与小节一一对应；紧密相关需求可以共用方案，只有存在独立技术路线时才拆分。
+- 方案按业务功能、运行时阶段或系统边界组织。标题同时写明“针对什么”和“怎么实现”，例如 `班段内最新入/最早出：复用既有 START/END 选择策略`；不要只写“策略复用”“数据处理”“接口调整”等泛称。
+- 每个方案整体说明实现机制、影响范围、设计依据和边界约束；不要求固定字段，只写本次实际涉及的数据、接口、流程和运行边界。共享契约集中定义一次，其他方案引用。
+- 如果不同实现会产生不同的行为、数据语义、接口兼容、状态、优先级、一致性、并发或恢复结果，必须明确对应契约；可以使用必要的模块、接口、表 / 字段、关键函数、数据流、状态机、优先级矩阵和简短伪代码。
+- 声明“复用现有逻辑”或“保持行为不变”时，说明复用对象、接入位置、本次差异和需要保持的语义，不能只写抽象结论。
+- 可以描述运行时算法、数据 / 控制流、状态转换和事务顺序；不写逐行代码、完整 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 标题只用于分组。
@@ -76,14 +147,14 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 - [ ] 1.1 检查 verifier 绑定文档 tdd_required:true
   执行依据:
   - 测试: test-contract.md#TEST-001
-  - 设计: design.md#verifier 绑定路线
+  - 设计: 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#执行证据核对路线
+  - 设计: design.md#执行证据核对：复用现有证据链
   - 来源: proposal.md#Impact；discovery.md#CHAIN-001
   - 原因: 证据核对与文档绑定是两个独立验收入口
   - 边界: 不改变历史证据的判定语义
@@ -96,10 +167,10 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 规则：
 - 每个普通 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）可以逗号合并
+- `设计`、`来源` 的标题或短摘录引用必须使用带文件名前缀的可定位格式，如 `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 的实现方向——先补设计，不编造引用
+- 写不出可定位的 `设计` 引用时，说明 `design.md` 缺少该 task 的实现方案或边界约束——先补设计，不编造引用
 - 单个 task 声明的测试超过 3 个时，`原因` 必须说明为什么不再拆分
 - `tdd_required:false` task 可以写执行依据，`测试` 字段按需填写；特征化任务（characterization task，指为固化既有行为而写保护测试、不引入新行为的任务）用 `tdd_required:false no_tdd_reason:characterization` 标记，只有这类任务可以在执行阶段以特征化通过作为测试证据
 - `REVIEW-FIX-*` task 由引擎在审查返工时追加，不需要手写执行依据
@@ -144,11 +215,11 @@ scenario 写到能推导断言的程度：给定什么条件、发生什么动
 
 | 核查ID | 验证方式 | 输入链路声明 | 证据或计划 |
 |---|---|---|---|
-| IDC-001 | 源码锚点 + 聚焦测试 | producer 产生的目标输入会进入 consumer | src/path.ts:10 + TEST-001 |
+| IDC-001 | 源码锚点 + 聚焦测试 | producer 产生的目标输入会进入 consumer | path.ts:10 + TEST-001 |
 
 证明方式可用源码锚点、fixture、targeted test、日志或 trace，须说明证明力；不强制集成测试。只证 consumer 算法、没证 producer→consumer 输入完整性，测试契约不足。
 
-discovery 含 `## 链路五要素` 时，`proposal.md` `## Impact` 中引用的 `CHAIN-xxx` 应映射到测试场景（scenario 内引用对应 `CHAIN-xxx`），或在测试表后写明不覆盖理由。
+discovery 含 `## 链路五要素` 时，`proposal.md` `## Impact` 中引用的 `CHAIN-xxx` 应映射到测试场景（scenario 内引用对应 `CHAIN-xxx`），或在测试表后写明不覆盖理由。design 只引用 CHAIN 作为方案依据时不重复产生映射要求；若 design 暴露新的消费者、视图差异或用户 / 系统可观察行为影响，先补入 Impact，再按同一规则映射测试。
 
 ### 待用户确认
 遇到会影响需求范围、验收标准、用户可见行为、方案取舍、测试策略、安全、权限、数据或迁移判断的关键不确定问题，先写入相关计划文档的 `## 待用户确认` 段落；没有阻塞确认项的文档不加该段落：

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

@@ -8,7 +8,7 @@ metadata:
 
 # SuperSpec Review
 
-你是审查阶段。目标是按工作流引擎返回的下一步，完成代码审查、最终验证、accept 和归档确认。这个阶段用来提高实现质量，不用来增加额外审批负担。
+你是审查阶段。目标是按工作流引擎返回的下一步，完成代码审查、最终验证和 accept。这个阶段用来提高实现质量，不用来增加额外审批负担。
 
 ## 驱动方式
 
@@ -19,7 +19,7 @@ metadata:
 3. 登记结果。
 4. 回到第 1 步。
 
-如果 next 返回待完成工作项，先完成工作项；如果 next 返回用户确认，先让使用者决策；完成前不要 accept 或 archive。审查/验证只说明通过与否、阻塞摘要、缺失证据、下一步，以及应回 apply 还是 propose；验收通过时说明等待用户明确确认后再归档。
+如果 next 返回待完成工作项，先完成工作项；如果 next 返回用户确认，先让使用者决策；完成前不要 accept。审查/验证只说明通过与否、阻塞摘要、缺失证据、下一步，以及应回 apply 还是 propose；验收通过并进入 accepted 时，说明本轮流程已经完成。
 
 ## review-ready 语义
 
@@ -36,7 +36,7 @@ metadata:
 - 有代码类改动时，`review-ready` 创建或等待代码审查工作项。
 - 没有代码类改动时，`review-ready` 直接进入 `review`，不启动子代理；内部会记录跳过原因。
 - 代码审查通过后，再次执行 `review-ready` 进入 `review`。
-- 代码审查通过后不要再增加持续代码变化拦截；流程内如果需要改代码，必须回 apply，修完后重新走代码审查。
+- 代码审查通过后若代码状态再次变化，旧审查失效；流程内如果需要改代码，必须先回 apply，修完后重新走代码审查。
 
 在 `review`：
 
@@ -72,10 +72,13 @@ superspec record job-submit --change "<change>" --job <JOB> --report -
 - 最终验证通过：执行 next 下发的 accept 命令。
 - 最终验证未通过：报告会保全原始报告引用和问题列表。按报告中的问题修复或回退；不要直接 accept。
 
-## accept 和 archive
+## accept 和 accepted 后返工
 
 - 只有状态为 `review`，且 `next` / `review-ready` 要求的审查或验证已满足时，才执行 accept。
-- accepted 后不要自动 archive，等待用户明确确认。
+- `accepted` 是正常完成终态，next 不再继续推进。
+- 使用者补充、修正或扩展方案、需求、验收或实现约束时，主流程先确定唯一对应的 change 并读取真实状态；只有该 change 当前为 accepted，才按 next 返回的内部 continuation 自动把用户内容概括为 reason 并回到 propose。无法唯一确定 change 时只询问补充属于哪个 change；不要让使用者选择工作流动作，也不要要求使用者执行命令。
+- 如果只是问答、致谢或不改变方案含义的说明，保持 accepted，不触发状态变化。
+- 不从 accepted 直接回 apply；回到 propose 后先修改计划材料，再按 next 重新完成计划审查、实现、代码审查和最终验证。
 
 ## Guardrails
 
@@ -83,6 +86,6 @@ superspec record job-submit --change "<change>" --job <JOB> --report -
 - 不绕过 `next` / `review-ready` 要求的代码审查或最终验证。
 - 主流程不重审代码，只复核代码审查报告是否可登记、问题是否可分流、回退和闭环证据是否存在。
 - 涉及代码审查问题回退时，以 next 当前返回为准，不手动套用旧 job 或旧问题编号。
-- 不在 accepted 后自动 archive。
+- 不把 accepted 后的新需求直接当作 apply 授权，必须先 reopen 到 propose。
 - 审查和验证报告必须引用真实文件、事件或测试证据，不编造。
 - 不跳过 transition。

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

@@ -1,38 +0,0 @@
----
-name: superspec-archive
-description: "五.验证文档完整性，归档"
-metadata:
-  author: SuperSpec
-  source: SuperSpec
----
-
-# SuperSpec Archive
-
-你是归档阶段。职责：用户明确确认归档后，执行归档——保全清单记录当前文档指纹。
-
-## 驱动方式
-
-所有状态由工作流引擎管理。循环：
-
-1. `superspec transition next --change "<change>"` 获取下一步
-2. 执行返回的命令
-3. 回到 1
-
-如果下一步提示还有用户确认、审查或验证事项，先完成这些事项。完成前不要归档或宣布流程完成；只说明等待确认、缺失事项或归档完成；归档完成时说关键文档和证据记录已保全，默认不展开指纹、raw 或 manifest。
-如果 next 返回 `archive_confirmation`，不要自行确认；只有用户明确要求归档时才执行 archive。
-
-## 本阶段做什么
-
-1. **确认用户已要求归档**
-2. **确认状态为 accepted**：next 会检查
-3. **archive**：`superspec transition archive --change "<change>"`
-   - 引擎记录当前文档指纹（proposal/tasks/design/discovery/bi/test-contract/specs）作为保全清单
-   - 状态推进到 archive（终态）
-
-## Guardrails
-
-- 不改文档内容（归档前应已定稿）
-- 不跳过 accept 直接 archive
-- 不替用户确认归档
-- archive 后不可逆——确认无误再提交
-- 不跳过 transition