@peterxiaoyang/superspec 0.1.56 → 0.1.57

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

@@ -53,27 +53,29 @@ metadata:
 ## 影响范围
 - <受影响的代码面、相邻模块、用户/系统可观察面及排除理由>
 
+## 风险和边界
+- <有证据的技术、兼容、依赖或发布风险；只陈述风险，不在此处写解法>
+
+## 待确认问题
+- [ ] Q-001 [验收] <一个待决问题>。影响：<范围或验收>。选项：A <后果> / B <后果>。建议：<理由>
+- [ ] Q-002 [事实] <需要用户补充的事实>。影响：<缺少它会阻塞的范围或验收>。现有证据：<为什么仓库无法裁决>
+```
+
+以下两节只在 change 改变共享数据、跨边界输入或持久化语义时加入；纯逻辑、纯文档或不改变数据传递的改动不写这两节，也不写"不适用"占位表：
+
+```markdown
 ## 链路五要素
 | ID | 发现方式 | 上游来源 | 规则变形 | 持久化语义 | 下游消费者 | 视图差异 | 未知/排除 | 证据 | 状态 |
 |---|---|---|---|---|---|---|---|---|---|
 | CHAIN-001 | <发现路径> | <输入/配置/历史数据> | <关键变形或无> | <持久化含义或不落库> | <消费者或无> | <可观察差异或无> | <未知或排除理由> | <锚点> | 已确认 |
 
-## 风险和边界
-- <有证据的技术、兼容、依赖或发布风险>
-
 ## 输入数据来源核查
-- <无运行时数据依赖时，说明不适用原因>
-
 | 核查ID | 消费位置 | 必需输入 | 数据来源 | 区分依据 | 状态/理由 |
 |---|---|---|---|---|---|
 | IDC-001 | <入口/规则/算法> | <字段/集合/状态> | <相关 producer 或组装位置> | <可证伪依据> | 已证明 |
-
-## 待确认问题
-- [ ] Q-001 [验收] <一个待决问题>。影响：<范围或验收>。选项：A <后果> / B <后果>。建议：<理由>
-- [ ] Q-002 [事实] <需要用户补充的事实>。影响：<缺少它会阻塞的范围或验收>。现有证据：<为什么仓库无法裁决>
 ```
 
-模板提供稳定骨架；不要为了填满每个章节或表格而制造事实、链路或风险。
+模板提供稳定骨架；不要为了填满每个章节或表格而制造事实、链路或风险。风险条目描述"什么会出错、证据是什么"，需要设计决定来处理的风险交给 Propose，不在 discovery 里预写状态字段、锁或预检之类的解法。
 
 ## 写作原则
 
@@ -93,7 +95,7 @@ Discovery 必须明确区分已确认事实、基于证据的推断和仍未裁
 
 当 change 涉及共享数据、跨边界输入、持久化语义或下游可观察行为时，建立足以判断影响的链路视图：输入来自哪里、关键形态如何变化、由谁持久化或解释、哪些消费者和视图会观察到结果。调查应追到决定本次输入语义的责任点，而不止停在 consumer、DTO 或校验器。
 
-不涉及此类链路时，说明不适用的具体原因；不要为了填表虚构链路。
+不涉及此类链路时不建链路表；影响范围里的直接锚点和具体排除理由就是闭环。
 
 ### 未知与用户决策
 
@@ -101,6 +103,8 @@ Discovery 必须明确区分已确认事实、基于证据的推断和仍未裁
 
 需求目标与验收已经明确，但不同技术路线会改变迁移、兼容、数据归属、发布方式、成本或长期责任边界时，将它作为 Propose 的设计决策候选写入调查结论和风险依据，不在 Explore 提前替用户选择，也不把它伪装成需求问题。若路线差异会改变产品行为或验收，则仍属于 Explore。
 
+有一类事实例外：当变更把单值扩展为集合、引入新的持久化数据或改变既有字段含义时，"是否存在按该数据筛选、检索、报表、审计或迁移存量的场景"决定了实现路线能有多轻。它是需求侧事实，不是设计取舍：先在需求源和代码中核实；核实不了时作为待确认事项交给用户，并说明不同答案会导向什么样的存储与兼容路线。不要把这个事实留给 Propose 去猜，也不要在 Explore 替用户选存储方式。
+
 每个待决问题只表达一个会改变结果的确认点，并说明影响、可选方向或需要补充的信息及建议依据。选择型问题给出候选结果和推荐；事实型问题说明需要用户提供什么、现有证据为什么无法裁决，以及缺少它会阻塞什么。
 
 Discovery 中有多个待确认事项时，按依赖逐项与用户沟通。每轮先给当前事项的简短理解和决策信息；可以说明还有后续事项，但不要同时展开多件事或要求一次确认全部内容。用户主动回答多个问题时，先回写当前结论并重新核对其余事项，再继续沟通。用户答复改变前提时，先更新受影响的调查结论，不沿用旧前提继续提问。
@@ -117,5 +121,5 @@ Discovery 中有多个待确认事项时，按依赖逐项与用户沟通。每
 
 - 不改业务代码或计划材料。
 - 不自行扩大范围、选择未确认的业务语义或宣布探索完成。
-- 审查意见用于补足证据，不自动创造新范围、新需求或新方案。
+- 审查意见用于补足证据，不自动创造新范围、新需求或新方案。审查通过后列出的残余风险记入 Propose 的风险表，不回写 discovery。
 - discovery 发生实质变化后，以 `next` 决定后续审查或推进。

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

@@ -14,6 +14,8 @@ metadata:
 
 先运行 `superspec transition next --change "<change>"`，以返回的事项、材料目标、确认、审查与后续动作作为唯一流程依据；不要根据 Skill 模板猜测产物目录或推进方式。只把用户已确认的行为、边界和有证据的风险写成计划，不改业务代码。
 
+计划分两拍。第一拍先形成 `proposal.md`、`specs/` 与 `design.md`（含结构变更清单和待用户确认的 DEC），然后运行 `next` 让用户逐个决定结构取舍；所有 DEC 关闭后才写 `tasks.md` 与 `test-contract.md`。结构决定改变方案时，任务与测试契约按新方案编写，不在旧方案的任务上修补。用户在任务写出来之前看到并决定"这次要动哪些结构"，是这一阶段最重要的产出。
+
 需求源、业务口径或验收更新时，先在 `proposal.md` 增加 `## 需求变化`，记录变化来源、变化、受影响能力、已修改材料、保持不变的范围和处理方式；再按实际影响同步规格、设计和测试契约。
 
 人类可读正文使用简体中文。源码锚点采用能唯一定位的最短写法；文档引用使用 `文件#锚点`，让实现者能打开原材料。
@@ -114,6 +116,12 @@ metadata:
 <!-- 可选：本方案存在真实可行且容易误走的替代路线时保留 -->
 **不采用：** <替代路线> — <不采用原因>
 
+## 结构变更清单
+
+| ID | 类别 | 变更 | 需求依据 | 决定 |
+|---|---|---|---|---|
+| SC-001 | <类别> | <新增或改变的结构，写到表/列/类/方法级> | <specs/<cap>/spec.md#Requirement: <标题> 或 TEST-xxx> | <DEC-xxx 或 —> |
+
 <!-- 可选：同一取舍横跨多个功能点时保留，否则优先写在对应方案内 -->
 ## 整体方案取舍
 | 方案 | 收益 | 代价 | 结论 |
@@ -122,7 +130,7 @@ metadata:
 
 <!-- 可选：存在必须由使用者承担结果的高影响设计取舍时保留；确认后回写最终方案 -->
 ## 待用户确认
-- [ ] DEC-001 <决定、候选结果、推荐与依据、对交付的影响>
+- [ ] DEC-001 <决定、候选结果、推荐与依据、对交付的影响；列出它会带来的 SC 条目>
 
 <!-- 可选：同一契约被多个功能点共享时保留，局部契约写在对应方案内 -->
 ## 关键契约
@@ -138,9 +146,24 @@ metadata:
 
 ```
 
+`## 结构变更清单` 是本次已批准结构的边界，工作流会解析它、在开始实现前展示给用户，并作为代码审查判断"是否多做"的依据。没有结构变更时在该标题下写 `无`。类别固定为：
+
+| 类别 | 覆盖 | 决定列 |
+|---|---|---|
+| 新增持久化结构 | 新表、新列、新实体/DAO、新索引、分表模板 | 必须引用 DEC |
+| 迁移或回填 | 结构脚本之外的数据迁移、回填、双写 | 必须引用 DEC |
+| 功能开关 | 任何运行时开关或灰度控制 | 必须引用 DEC |
+| 新增公共接口 | HTTP/RPC 入口、消息主题、跨服务或跨仓库契约 | 必须引用 DEC |
+| 删除既有路径 | 删除兼容读取/写入/回退路径、删除既有公共方法 | 必须引用 DEC |
+| 改既有公共签名 | 既有公共/受保护方法的参数或返回类型变化 | 必须引用 DEC |
+| 改变既有数据语义 | 既有字段含义、归属或默认值变化 | 必须引用 DEC |
+| 新增公共类型 | VO / DTO / 枚举 / 工具类 | 可写 `—` |
+
+需决定类别的"需求依据"只能是 specs 的 Requirement 或 TEST；找不到这样的依据，说明该结构不是需求要求的，不要写进清单，也不要写进方案。一个 DEC 可以覆盖同一决定带来的多条 SC。`proposal.md#Impact` 不能作为任何条目的依据。
+
 ### tasks.md
 
-使用 OpenSpec 的任务分组；每个顶格 checkbox 是一个可独立完成和验证的 task。按依赖顺序排列，多个独立行为或入口不能共享一个验证边界时拆开。
+使用 OpenSpec 的任务分组；每个顶格 checkbox 是一个可独立完成和验证的 task。任务按用户或调用方可观察的行为切分，为该行为服务的跨层机械改动归入同一 task，不按技术层单列；只有多个独立行为或入口不能共享一个验证边界时才拆开。审计、对账、撤销之类没有可观察交付的工作不是 task。
 
 ```markdown
 # Tasks
@@ -166,11 +189,11 @@ metadata:
   - 边界: <不改业务行为>
 ```
 
-每个普通 task 紧跟 `执行依据:`，显式写 `测试`、`设计`、`来源`、`验收`、`边界`。行为 task 的测试引用相应场景；纯非行为 task 才可留空并在验收/边界说明原因。`验收` 与 `边界`必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。`交付` 和 `依赖`用于开始实现前的阅读摘要：只写真实前置交付，不能把纯排列顺序写成依赖。验证要求由工作流决定，计划不预设执行步骤。
+`验收` 与 `边界` 必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。行为 task 的测试引用相应场景；纯非行为 task 才可留空并在验收/边界说明原因。`交付` 和 `依赖` 用于开始实现前的阅读摘要：只写真实前置交付，不能把纯排列顺序写成依赖。验证要求由工作流决定，计划不预设执行步骤。
 
 ### test-contract.md
 
-把每个需自动验证的验收行为写成能推导断言的场景，不写测试命令或断言代码。场景描述调用方可观察的结果，不把内部实现过程写成验收。通常一个场景描述一个可观察行为；名称写“调用方得到什么”，不写“某模块调用了什么”。
+把每个需自动验证的验收行为写成能推导断言的场景，不写测试命令或断言代码。场景描述调用方可观察的结果，不把内部实现过程写成验收。通常一个场景描述一个可观察行为；名称写“调用方得到什么”，不写“某模块调用了什么”。一个 change 用少量场景覆盖主要行为与直接边界即可，不为每个任务、每一层或每个消费者各写一个场景。
 
 ```markdown
 # Test Contract