@peterxiaoyang/superspec 0.1.56 → 0.1.58

package/templates/workflow/prompts/code-reviewer.md

@@ -24,7 +24,8 @@ argument-hint: "本次代码审查说明"
 - 实现是否兑现当前任务的验收和边界，且与已批准的方案/规格一致。
 - 是否引入功能、数据、一致性、安全、权限、性能或兼容问题，以及直接的边界条件遗漏。
 - 从批准范围反查实现是否覆盖已确认的消费者、兼容路径和直接影响链路；任务勾选和测试通过不能替代完整性判断。
-- 对当前审查范围内的 Diff，分别判断“是否漏实现”和“是否超出必要范围”：直接消费者没有实现、或没有现有实现已满足验收的证据，属于完整性问题；计划或验收没有要求、也没有直接必要性证据的语义扩大，属于范围问题，应作为纯实现问题交回 Apply 收缩，文件数量和新增私有局部函数本身不是问题。两类判断都锚定当前批准行为和实际 Diff，不把消费者类别或可能性清单当成覆盖义务；若你认为某个计划未写的机制不加上就不正确，标为混合问题交给使用者裁决，不要写成必须实现的纯代码缺口。
+- 对当前审查范围内的 Diff，分别判断“是否漏实现”和“是否超出必要范围”：直接消费者没有实现、或没有现有实现已满足验收的证据，属于完整性问题；计划或验收没有要求、也没有直接必要性证据的语义扩大，属于范围问题，应作为纯实现问题交回 Apply 收缩，文件数量和新增私有局部函数本身不是问题。两类判断都锚定当前批准行为和实际 Diff，不把消费者类别或可能性清单当成覆盖义务。放行任何计划外的文件前，必须能说清它服务于哪条已批准锚点、为何无法避免；给不出依据就按范围问题收缩。若你认为某个计划未写的机制不加上就不正确，标为混合问题交给使用者裁决，不要写成必须实现的纯代码缺口。
+- 任务说明提供的结构变更清单是已批准结构的边界。代码中出现清单外的新表、列、实体、DAO、开关、迁移、公共接口，或清单外的既有签名变化、兼容路径删除，按 `unjustified_addition` 报告并把锚点指向最接近的清单条目或清单本身；清单内的结构不因"可以更简单"而报告。
 - 测试是否实际证明相关行为和直接回归风险，而非只存在一条通过记录。
 - 需求源已更新时，代码是否仍在执行过期计划；此类问题按方案或需求缺口归因，不把旧材料当作当前依据。
 

package/templates/workflow/prompts/critic.md

@@ -43,7 +43,8 @@ Discovery 准备结束时，从本次变更及已有证据出发，反向检查
 - task 的来源、设计依据、验收和边界应能让执行者判断是否越界；这些材料与 task 实质无关、空泛或互相矛盾时才报告。不要检查字段、ID 或引用写法本身。
 - 参考实现只证明已有能力和候选机制，不自动证明其接口数量、资源拆分、数据模型或模块边界适合本次 change。新增公共表面或跨系统改动缺少独立责任与必要性依据，或者明显存在可复用、合并、缩减空间并影响实施边界时，应要求计划补足判断，而不是规定具体数量或替代方案。
 - 计划通过前，执行者应能在不重新决定产品语义或重做架构设计的前提下开始 Apply。会改变数据归属、调用路径、一致性或发布顺序的候选路线不得留给 Apply 临时选择。跨越可独立发布、失败或验证边界的 task，未经核实却被当成既定事实的外部依赖，以及无法证明已声明行为或设计直接风险的测试契约，都会削弱这一条件。
-- 检查计划自己声明的关键不变量是否在迁移、兼容、回退和失败路径下仍成立；新旧实现同时存在且可能承担同一写入责任时，计划应明确权威写入边界，避免实现阶段重新决定所有权。
+- 只有当本次变更自身引入迁移、双写或新旧并存时，才检查其权威写入边界与失败路径；变更没有引入这些机制时，缺少回滚装置、开关或迁移清单不是 blocker，不要用"回退保护"把它们要出来。
+- 结构变更清单是本次已批准结构的边界。清单中没有 Requirement 或 TEST 依据的新表、开关、迁移、签名变化，以及方案正文出现而清单未列的结构，是 blocker；处理方向是删除或补依据，不是补任务。
 - 需求语义未闭合的问题属于 Explore；需求结果已经明确、但不同可行路线会改变迁移、兼容、数据归属、发布、成本或长期责任边界时，计划应让使用者明确选择。只有内部实现不同且不改变这些结果时，不得要求新增用户决定。
 - 未改变的既有风险和没有已声明可观察结果的理论故障，标残余风险，不得升级为 required fix。本条不削弱上两条。
 

package/templates/workflow/prompts/executor.md

@@ -26,6 +26,7 @@ argument-hint: "本次执行说明"
 - 先理解已有实现、调用点与测试模式，再作最小可维护改动；不要为局部任务引入未经计划的新框架、基础设施或重构。
 - 保持已有公共接口、数据语义、错误处理和兼容行为，除非 task 明确要求改变。
 - 代码审查修复只兑现该问题锚定的已批准行为；审查建议里的架构不是实现授权。
+- 新建非任务直接要求的文件（如配置、脚手架）时，在完成报告中说明必要性；说不清必要性的不要新建。
 - 记录实际修改、验证候选和不能验证的原因。失败或不确定不是完成，不要用推测补足证据。
 
 ## 输出

package/templates/workflow/prompts/explore.md

@@ -17,7 +17,7 @@ argument-hint: "本次探索说明"
 
 ## 探查口径
 
-为代码影响型需求提供能定位的短锚点，如 `ClassName.java:123` 或 `file.ts:45`；没有代码锚点的纯文档/配置/新文件说明 `N/A` 理由。对数据或跨边界行为，沿调用和数据流检查上游来源、关键变形、持久化语义、下游消费者与视图差异；“未发现”必须说明检索方式与范围。运行时数据依赖追到 producer 侧相关字段的最后一次变形，并说明区分依据。
+为代码影响型需求提供能定位的短锚点，如 `ClassName.java:123` 或 `file.ts:45`；没有代码锚点的纯文档/配置/新文件说明 `N/A` 理由。对数据或跨边界行为，沿调用和数据流检查上游来源、关键变形、持久化语义、下游消费者与视图差异；“未发现”必须说明检索方式与范围。运行时数据依赖追到 producer 侧相关字段的最后一次变形，并说明区分依据。变更把单值扩展为集合或引入新持久化数据时，明确报告是否发现按该数据筛选、检索、报表或迁移存量的消费者，以及检索方式与范围——这个事实决定实现路线能有多轻。
 
 先从用户目标和已有锚点形成探查问题，再用正向搜索与调用方/入口反查验证。对每个重要结论明确它是事实、基于锚点的推断还是未知；影响范围候选需要说明为什么可能受影响或为什么排除。不要只扫用户提到的文件，也不要因为模块名看似相关就把它列为影响面。
 

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
@@ -149,7 +172,7 @@ metadata:
 
 - [ ] 1.1 <可独立验证的行为或明确的非行为改动>
   执行依据:
-  - 测试: test-contract.md#TEST-001
+  - 测试: test-contract.md#TEST-001, TEST-002
   - 设计: design.md#<对应实现方案>
   - 来源: proposal.md#Impact；specs/<capability>/spec.md#<对应规则>
   - 验收: <完成后可检查的结果>
@@ -166,11 +189,11 @@ metadata:
   - 边界: <不改业务行为>
 ```
 
-每个普通 task 紧跟 `执行依据:`，显式写 `测试`、`设计`、`来源`、`验收`、`边界`。行为 task 的测试引用相应场景；纯非行为 task 才可留空并在验收/边界说明原因。`验收` 与 `边界`必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。`交付` 和 `依赖`用于开始实现前的阅读摘要：只写真实前置交付，不能把纯排列顺序写成依赖。验证要求由工作流决定，计划不预设执行步骤。
+`验收` 与 `边界` 必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。行为 task 的测试引用相应场景，一个 task 覆盖多个场景时把它们都列在同一 `测试` 字段里；纯非行为 task 才可留空并在验收/边界说明原因。`交付` 和 `依赖` 用于开始实现前的阅读摘要：只写真实前置交付，不能把纯排列顺序写成依赖。验证要求由工作流决定，计划不预设执行步骤。
 
 ### test-contract.md
 
-把每个需自动验证的验收行为写成能推导断言的场景，不写测试命令或断言代码。场景描述调用方可观察的结果，不把内部实现过程写成验收。通常一个场景描述一个可观察行为；名称写“调用方得到什么”，不写“某模块调用了什么”。
+把每个需自动验证的验收行为写成能推导断言的场景，不写测试命令或断言代码。场景描述调用方可观察的结果，不把内部实现过程写成验收。通常一个场景描述一个可观察行为；名称写“调用方得到什么”，不写“某模块调用了什么”。一个 change 用少量场景覆盖主要行为与直接边界即可，不为每个任务、每一层或每个消费者各写一个场景。
 
 ```markdown
 # Test Contract