@peterxiaoyang/superspec 0.1.47 → 0.1.49

package/templates/workflow/AGENTS.md

@@ -1,16 +1,22 @@
 <!-- SUPERSPEC:AGENTS:START -->
 只有当用户显式调用 `superspec-*`，或明确要求继续处理某个已有 SuperSpec change 时，才进入或续转 SuperSpec 工作流。普通开发、修复、排查、测试或审查请求，即使项目已安装 SuperSpec，也不得自行启动工作流、创建 change、执行 `transition next`，或切换到某个 `superspec-*` 阶段。
 
+以下规则仅适用于已经显式启动或明确指定的 SuperSpec change。没有活跃 SuperSpec change 时，本区块除上述工作流激活边界外均不适用，按项目常规开发指令执行。
+
 一旦用户已显式启动工作流或明确指定 change，使用 `superspec-*` 工作流时一律以 `superspec transition next --change "<change>"` 返回的下一步推进；主流程执行内部命令，不要求用户手动运行工作流命令。流程完成前不得跳阶段、不得自称完成。
 
 每完成 `next` 返回的当前事项（材料更新、用户答复回写、实现、验证、审查或修复时），立即再次运行 `superspec transition next --change "<change>"` 并继续处理。完成单个事项不等于完成整个 change；只有工作流明确需要用户决定、当前独立工作项尚未返回结果、遇到真实阻塞或整个 change 已完成时才暂停。
 
+工作流要求用户决定时，只能登记当前对话中用户针对当前问题作出的明确答复。启动工作流、要求推进到某阶段、允许自动执行或表达一般偏好，不等于回答后续具体业务问题或阶段确认；主流程、Skill、subagent 和审查角色都不得根据目标、建议、历史偏好或推断代替用户作答。答复与当前问题不对应或仍有实质歧义时，保持待确认，不得登记为用户决定。
+
 当用户显式调用 `$superspec-explore`，或明确要求继续处于 Explore 的已有 change 时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `$superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
 
 Explore 中需要用户决定业务、验收、范围或关键取舍时，先简要说明当前理解、影响和建议，再一次只请用户决定一件事；收到明确答复后，更新相关 discovery 结论，再继续工作流。其他阶段要求用户确认、选择处理方向或补齐材料时，按当前工作流返回的要求登记结论或更新相应材料；不得把这类答复默认写入 discovery。
 
 当前 change 的自测、联调或用户指出的问题若仍能由既有 task 的批准行为、边界和验收解释，就在同一 change 内处理：
 
+计划材料没有枚举某个类、继承关系、方法或局部实现细节，不等于计划遗漏。只要正确修法能够由既有 task、已批准行为和仓库事实唯一推导，仍属于 Apply；只有需要重新决定公共接口、数据归属、迁移兼容、实现路线、验收或 task 边界时才回 Propose。
+
 - 当前 task 尚未完成时，在其范围内直接修复；不要为同一实现问题新增 task 或回 propose。
 - 所有 task 已完成后，若问题仍能关联一个已完成 task、且不改变已批准行为和方案，主流程执行 `superspec transition reopen --change "<change>" --to apply --self-test-fix "<task>" --reason "<reason>"`，让工作流创建修复事项；随后继续 `next`，不得手改 tasks。
 - 无法关联既有 task，或需要改变行为、验收、接口、数据语义或实现路线时，才回 propose。

package/templates/workflow/prompts/architect.md

@@ -22,6 +22,7 @@ argument-hint: "本次架构审查说明"
 - 方案必须说明在何处承担责任，以及本次数据、接口、状态或控制流如何改变；实现者不能据此落地时阻塞。
 - 需求、规格和 discovery 中影响实现的事实必须在设计中得到一致安排。共享数据、接口、状态或优先级规则不能在不同方案中得到冲突解释。
 - 复用既有机制时，核对接入点、本次差异和保持语义；只审查本次接入是否破坏现有契约，不要求重建或重新证明底层基础设施。
+- 参考实现证明的是可复用能力和候选机制，不自动决定本次的接口、资源、数据模型或模块形态。新增 Controller、API、实体、表、公共类型、独立模块或跨仓库改动时，检查其是否承担不可由现有边界表达的独立责任；不要规定数量，但应挑战无必要依据的平行结构和机械复制。
 - 只有本次确实改变的兼容、并发、恢复、数据语义或发布顺序才需要明确设计；未改变的既有风险和理论故障不是 blocker。
 - 设计取舍受用户决定和明确非目标约束。报告无法满足的结果或事实冲突，不把未经采纳的架构方案写成 required fix。
 
@@ -31,6 +32,7 @@ argument-hint: "本次架构审查说明"
 - 多个功能点共享字段组、接口语义、状态转换、优先级或一致性规则时，检查是否有一个一致的权威契约；局部方案互相矛盾时阻塞。
 - 改变既有规则变形、持久化语义、调用顺序或事务边界时，确认该变化已被声明为目标，并有与影响相称的保护边界；无理由地重复上游变形、双重兜底或扩大数据语义应报告。
 - 运行时输入或 producer-to-consumer 契约变化时，设计应分开说明输入如何完整到达 consumer、consumer 如何处理；不要用单一算法描述掩盖输入链路缺口。
+- 跨仓库、外部模块或不同运行时参与方案时，区分已经核实的契约、尚待核实的假设和必须先完成的外部前置变更。方案不能把当前证据范围外的实现当作确定事实，也不能让 Apply 隐含承担未登记的外部设计工作。
 - 任务应能从实现方案和边界约束自然推出。仅当多个独立行为、入口或系统边界确实不能共享一个验证边界时，才要求拆分；不要为了形式化而增加层级或任务。
 
 ### 停止边界

package/templates/workflow/prompts/critic.md

@@ -12,7 +12,7 @@ argument-hint: "本次反方审查说明"
 ## 工作边界
 
 - 先读任务说明和被引用材料；只审查本次 change 的既定范围。材料不足时报告证据缺口，不猜测或静默扩大范围。
-- 修复复核优先判断原问题是否仍成立；新 blocker 只能来自修复直接引入的回归，并说明因果链。
+- 修复复核优先判断原问题是否仍成立；不得通过缩小已确认范围、改写用户决定或删除验收来让 finding 字面消失。新 blocker 只能来自修复直接引入的回归，并说明因果链。
 - 不要因标题、字段、表格、编号、勾选或引用写法提出 finding；只判断材料表达的事实、范围和可执行性。
 
 ## 反方判断
@@ -21,7 +21,7 @@ argument-hint: "本次反方审查说明"
 
 Discovery 阶段，检查用户目标、当前差异和完成口径是否清楚；事实、推断和未知是否被诚实区分；影响范围、数据来源和下游影响是否由实际链路支撑。数据或跨边界输入发生变化时，确认调查能证明相关 producer-to-consumer 契约；局部行为且不改变数据传递时不要求虚构全链路。
 
-计划阶段，检查 proposal、specs、design、tasks 与测试契约是否围绕同一已确认目标：能力是否被可观察行为、可落地设计、独立验证边界和证据路径支撑；已确认决策与需求变化是否得到一致回写；是否把调查记录、实现日志、技术偏好或未证实消费者伪装成需求。技术路线优劣交给 Architect，测试证明力交给 Test Engineer。
+计划阶段，检查 proposal、specs、design、tasks 与测试契约是否围绕同一已确认目标：能力是否被可观察行为、可落地设计、独立验证边界和证据路径支撑；已确认决策与需求变化是否得到一致回写；是否把调查记录、实现日志、技术偏好或未证实消费者伪装成需求。Architect 和 Test Engineer 存在时分别承担技术路线与测试证明力的深入审查；Critic 仍需识别会让整个计划无法实施或无法证明的跨材料缺口。
 
 ### Discovery 反方口径
 
@@ -29,6 +29,11 @@ Discovery 阶段，检查用户目标、当前差异和完成口径是否清楚
 - 影响范围和风险应由当前调用、数据流、现有契约或用户可观察行为支撑。消费者类别只是搜索线索，不是无证据的覆盖配额。
 - 对共享数据、跨边界输入或下游可观察行为，检查是否追到足以判断影响的真实链路，以及是否说明已排除的相邻消费者。对局部改动，直接锚点和具体不适用理由可以构成闭环。
 - 已确认结论、未知和排除理由必须互相一致。会改变范围或验收的未知不能被伪装成非阻塞；可由继续调查解决的问题不应升级给用户。
+- 区分证据支持的事实、基于事实提出的建议和需要用户选择的产品决定。会实质收窄范围、定义兼容或接口语义、选择行为主体或改变验收结果的结论，没有明确需求源、系统不变量或用户针对该问题的答复时，不得视为已确认。
+
+Discovery 准备结束时，从本次变更及已有证据出发，反向检查是否仍有会影响范围、验收、兼容、数据语义或可落地性的未闭合分支。结合实际链路和边界自由判断，不套固定问题清单，也不为了形式完整而穷举可能性；正文已经暴露却没有得到明确处理的关键问题仍属于缺口。
+
+能够通过代码、依赖、配置、测试或需求源继续核实的事实，应要求补足调查；只有证据无法裁决且确实需要选择的事项才交给用户。没有直接证据或不影响本次结果的可能性不应扩展为审查义务。
 
 ### 计划反方口径
 
@@ -36,6 +41,10 @@ Discovery 阶段，检查用户目标、当前差异和完成口径是否清楚
 - `Impact` 应说明受影响原因和可观察影响，而不是文件清单；已证实会变化的影响没有登记且会使验收或实现判断失真时才阻塞。
 - design 应表达方案关系、责任边界和约束，而不是 discovery 调查过程、规格复述、测试步骤或实现日志。共享事实需要一个可定位的权威定义，避免多处含义漂移。
 - task 的来源、设计依据、验收和边界应能让执行者判断是否越界；这些材料与 task 实质无关、空泛或互相矛盾时才报告。不要检查字段、ID 或引用写法本身。
+- 参考实现只证明已有能力和候选机制，不自动证明其接口数量、资源拆分、数据模型或模块边界适合本次 change。新增公共表面或跨系统改动缺少独立责任与必要性依据，或者明显存在可复用、合并、缩减空间并影响实施边界时，应要求计划补足判断，而不是规定具体数量或替代方案。
+- 计划通过前，执行者应能在不重新决定产品语义或重做架构设计的前提下开始 Apply。会改变数据归属、调用路径、一致性或发布顺序的候选路线不得留给 Apply 临时选择。跨越可独立发布、失败或验证边界的 task，未经核实却被当成既定事实的外部依赖，以及无法证明已声明行为或设计直接风险的测试契约，都会削弱这一条件。
+- 检查计划自己声明的关键不变量是否在迁移、兼容、回退和失败路径下仍成立；新旧实现同时存在且可能承担同一写入责任时，计划应明确权威写入边界，避免实现阶段重新决定所有权。
+- 需求语义未闭合的问题属于 Explore；需求结果已经明确、但不同可行路线会改变迁移、兼容、数据归属、发布、成本或长期责任边界时，计划应让使用者明确选择。只有内部实现不同且不改变这些结果时，不得要求新增用户决定。
 
 建议只能说明需补足的事实、范围或闭环，不能把个人技术偏好、新基础设施或额外测试升级为强制要求。已声明行为及其直接边界有充分证据时停止。
 

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

@@ -22,6 +22,7 @@ argument-hint: "本次测试审查说明"
 - 测试应证明用户或调用方可观察的结果；预期值应来自规格、示例或独立计算，而不是复刻被测实现。
 - 复用基础设施或既有测试时，只补本次接入的最小证明；不因理论上的长期风险重测未改变机制。
 - 数据传递、字段形态或 producer-to-consumer 契约变化时，测试或其他可信证据必须证明目标输入按新契约抵达 consumer；只证明 consumer 算法不足以证明链路。
+- 从已采纳方案实际引入的责任边界和失败方式推导测试义务。例如只有异步投影、一致性窗口、批量范围变更、租户路由、缓存陈旧或跨运行时版本差确实由本次方案产生并影响验收时，才要求相应证明；不要把这些例子当作所有 change 的固定矩阵。
 - 已采纳的方案和验收约束决定测试义务。技术偏好、未采纳架构、通用故障矩阵和审查建议不能自行升级为必须新增的测试。
 
 ### 证明力审查

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

@@ -16,10 +16,12 @@ metadata:
 
 每个 task 使用同一循环：
 
-1. 对照 task 的执行依据，确认要实现的行为、边界和相关测试仍与当前计划一致。
+1. 开始 task 前先检查当前工作区变化，并沿 task 引用链核对发生变化的需求源或计划材料；确认要实现的行为、边界和相关测试仍与当前计划一致。新变化使已批准行为、验收、边界或方案失效时，不按旧计划继续，停止实现并交回 Propose。
 2. 在授权范围内实现最小改动；不要提前修改计划材料或扩大范围。
 3. 完成当前 task 要求的验证，如实报告测试、环境或覆盖不足的结果。
-4. 完成后再继续工作流。
+4. 当前 task 完成后立即继续工作流并处理下一事项；不要总结交付或等待用户再次要求继续。
+
+验证和登记所需的执行顺序、固定语义与提交方式以工作流当前返回为准；执行者只补充真实命令、工作目录和退出结果。不要通过阅读 CLI 或引擎源码猜测证据格式。
 
 不要伪造完成结果、验证材料或审查结论。
 
@@ -30,7 +32,9 @@ metadata:
 - 优先沿用仓库已有的验证边界，证明用户或调用方可观察的结果。
 - 不为方便测试改变生产设计，也不把测试偏好升级为额外的开发步骤或测试义务。
 
-## 何时停止
+## 连续执行与停止
+
+完成单个 task、测试通过或文件修改完成都不是暂停条件。只有工作流明确需要用户决定、当前独立工作项仍在执行、遇到无法在当前范围内解决的真实阻塞，或整个 change 已完成时才暂停。
 
 当前 task 尚未完成时，自测发现仍属于该 task 已批准行为和边界的实现问题，直接修正并完成要求的验证；不要为同一实现缺陷新增 task 或回 propose。
 

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

@@ -12,7 +12,9 @@ metadata:
 
 ## 工作方式
 
-运行 `superspec transition next --change "<change>"`，以返回的当前事项为准。优先通过代码、文档、已有测试和需求源消除未知；只有业务语义、验收、范围、数据口径或关键取舍无法由现有证据裁决时才询问用户。
+运行 `superspec transition next --change "<change>"`，以返回的当前事项为准。工作流明确给出材料目标时，只在该目标位置创建或更新材料；路径、生命周期和后续动作都以工作流为准，不自行推断目录或推进方式。
+
+优先通过代码、文档、已有测试和需求源消除未知；只有业务语义、验收、范围、数据口径或关键取舍无法由现有证据裁决时才询问用户。
 
 用户明确说明 PRD、文档、原型或其他需求源已更新时，重新核对来源，不复用旧结论；需要继续或修改材料时，按工作流反馈处理。
 
@@ -23,7 +25,7 @@ metadata:
 1. 先读需求源、代码、测试和现有材料，主动消除可查证的事实；不要把可以继续搜索得到的答案包装成用户问题。
 2. 将真正会改变结果的未知整理为待确认事项：每项只对应一个业务理解、验收口径、范围或取舍；写清当前理解、可选结果或所需事实、推荐及依据、会受影响的结果。
 3. 需要用户确认时，不要只转述问题：先基于当前 Discovery 给出简短理解（目标、当前差异、影响和明确排除），再说明这件事的可选结果或需补充的事实、推荐及依据、影响。只围绕这一件事提问并等待答复；不要在同一轮要求用户确认一串问题，也不要把候选推荐写成既定需求。没有证据的内容明确为未知，不补造。不要在用户对话中展示文档编号。
-4. 用户答复后，先把结论与受影响事实回写到 discovery，再重新检查后续事项是否仍成立、是否需要重写或已被排除；前提变化时不能沿用旧顺序。
+4. 用户答复后按工作流反馈处理并回写 Discovery；勾选事项时保留原问题内容，将结论写入相邻正文。随后重新判断受影响事实与后续事项，前提变化时不沿用旧结论。
 
 没有需要用户决定的高影响未知时，不制造问答，直接完成基于证据的 Discovery。所有待确认事项都已回写且没有阻塞未知后，再继续形成后续计划。
 
@@ -95,7 +97,9 @@ Discovery 必须明确区分已确认事实、基于证据的推断和仍未裁
 
 ### 未知与用户决策
 
-先通过继续调查、阅读代码、运行已有测试或核对需求源消除未知。只有无法由现有证据裁决、且会影响需求范围、验收、用户可见行为、数据语义、安全、兼容或关键方案取舍的问题，才交给用户决定。
+先通过继续调查、阅读代码、运行已有测试或核对需求源消除未知。只有无法由现有证据裁决、且会影响需求范围、验收、用户可见行为、数据语义或安全的问题，才在 Explore 交给用户决定。
+
+需求目标与验收已经明确，但不同技术路线会改变迁移、兼容、数据归属、发布方式、成本或长期责任边界时，将它作为 Propose 的设计决策候选写入调查结论和风险依据，不在 Explore 提前替用户选择，也不把它伪装成需求问题。若路线差异会改变产品行为或验收，则仍属于 Explore。
 
 每个待决问题只表达一个会改变结果的确认点，并说明影响、可选方向或需要补充的信息及建议依据。选择型问题给出候选结果和推荐；事实型问题说明需要用户提供什么、现有证据为什么无法裁决，以及缺少它会阻塞什么。
 

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

@@ -12,7 +12,7 @@ metadata:
 
 ## 工作方式
 
-先运行 `superspec transition next --change "<change>"`，以返回的事项、确认、审查与提交命令为准。只把用户已确认的行为、边界和有证据的风险写成计划，不改业务代码。
+先运行 `superspec transition next --change "<change>"`，以返回的事项、材料目标、确认、审查与后续动作作为唯一流程依据；不要根据 Skill 模板猜测产物目录或推进方式。只把用户已确认的行为、边界和有证据的风险写成计划，不改业务代码。
 
 需求源、业务口径或验收更新时，先在 `proposal.md` 增加 `## 需求变化`，记录变化来源、变化、受影响能力、已修改材料、保持不变的范围和处理方式；再按实际影响同步规格、设计和测试契约。
 
@@ -27,7 +27,11 @@ metadata:
 3. task 优先按垂直交付拆分：一个 task 完成一段用户或调用方可验收的能力，并携带足以实现和验证它的来源、设计、验收与边界。共享机械改动只有确实不能独立交付时才按真实依赖拆开。
 4. 每步只安排满足当前已确认行为所需的最小改动；不要把未来能力、理论故障模型、通用基础设施升级或未采纳方案预支进计划。
 
-这不是要求所有 task 机械地一一对应单个场景；紧密相关行为可共用方案和 task，独立行为或真实前置交付才需要拆分。
+参考实现是现有能力与候选机制的证据，不是本次 change 的默认结构。根据已确认目标重新判断最小责任边界；不能因为参考模块存在某组接口、实体、表或服务，就直接复制其形态。当前证据范围内尚未核实的外部仓库或模块变化，应标为待核实依赖、实施前置或风险，不得写成已经成立的实现事实。
+
+已证实受影响的外部仓库、平台或运行时，在计划中明确外部交付物、责任边界、可核验准入条件和联调验收，或有证据地排除。会改变数据归属、调用路径、一致性或发布顺序的实现路线，在 Propose 中选定其一；不把“两种方式均可”留为 Apply 的架构任务。
+
+这不是要求所有 task 机械地一一对应单个场景；紧密相关行为可共用方案和 task，独立行为或真实前置交付才需要拆分。能够独立发布、失败或验证的系统边界通常不应混入同一 task，除非它们确实构成不可分割的原子交付。
 
 ## 产物模板
 
@@ -116,6 +120,10 @@ metadata:
 |---|---|---|---|
 | <方案> | <收益> | <代价> | <采用或放弃原因> |
 
+<!-- 可选：存在必须由使用者承担结果的高影响设计取舍时保留；确认后回写最终方案 -->
+## 待用户确认
+- [ ] DEC-001 <决定、候选结果、推荐与依据、对交付的影响>
+
 <!-- 可选：同一契约被多个功能点共享时保留，局部契约写在对应方案内 -->
 ## 关键契约
 
@@ -174,9 +182,15 @@ metadata:
 
 数据传递、字段形态或上下游契约变化时，在测试表后说明输入完整性如何得到证明；只证明使用方算法不足以证明新输入真的到达使用方。
 
-## 未知与审查
+## 设计决策与审查
+
+Propose 以已确认的 Discovery 为需求边界。范围、业务行为、验收、数据语义或安全仍不明确时，回同一 change 的 Explore 澄清，不静默采用默认业务语义。
+
+用户补充与已经核实的代码、运行行为、接口契约或外部系统事实冲突时，不通过改写事实材料来消除冲突。若用户明确要求改变真实行为，将相应实现、迁移和验证影响纳入计划；若是否改变真实行为仍不明确，保留冲突并交给用户确认。
+
+当需求结果已经明确，但多个可行技术路线会让使用者承担不同的迁移、兼容、数据归属、发布、成本或长期维护边界时，不替使用者静默选择。在 `design.md` 的 `## 待用户确认` 中保留当前高影响设计决定，说明已知事实、候选结果、推荐及依据和会受影响的交付；内部命名、文件组织、局部实现和不改变这些结果的技术选择由模型自主决定。没有这类取舍时不制造问答。
 
-Propose 只综合已经确认的 Discovery。若发现范围、验收、兼容、数据语义、安全或关键方案取舍仍无法由已确认材料裁决，回同一 change 的 Explore 澄清；不要静默采用默认业务语义，也不要把未决的用户选择留在 Proposal、Design 或 Tasks 中。
+每项使用 `DEC-xxx` 标识并只表达一个决定。工作流一次返回当前一项；用户答复后按工作流反馈处理，勾选时保留决定项原文，将最终选择与影响写入相邻正文及相关 design、specs、tasks 和测试契约，并按新方案重新判断后续事项。审查角色只能依据本次目标和直接证据指出缺失的决定，不能把个人偏好或更理想的架构升级为用户义务。
 
 只要计划包含 task，就向用户展示任务交付摘要。单个 task 同样展示，不能通过 task 数量或依赖字段猜测其复杂度。用户选择继续完善计划时，可据此调整交付粒度、依赖或顺序；材料变更后再按工作流继续。