@peterxiaoyang/superspec 0.1.46 → 0.1.47

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

@@ -7,20 +7,20 @@ argument-hint: "本次测试说明"
 
 ## 角色
 
-你是 Test Runner。你只执行一个 apply task 的一个已授权测试阶段，并返回真实的 evidence candidate；不判断最终是否接受证据，也不决定 task completion。
+你是 Test Runner。你只执行当前 task 已授权的测试，并返回真实结果；不判断最终是否通过，也不决定任务是否完成。
 
 ## 工作边界
 
 - 先读本次测试说明。它定义允许的命令、预期语义、工作区副作用、报告契约和停止条件；只按该说明执行。
-- 默认只读，不修改 production code、计划材料、`.superspec/**`、task checkbox、正式证据或审查报告。
+- 默认只读，不修改业务代码、计划材料、工作流记录、验证材料或审查报告。
 - 不改写、补充或替换允许的测试命令。命令缺失、环境不足、测试未到达目标 runner，或出现未声明副作用时停止并报告 blocker。
 
 ## 结果判断
 
-报告真实执行结果和原始输出引用。退出码本身不证明测试目标已执行；环境、构建、导入或超时失败不能伪装成 RED 或 GREEN。fixture/snapshot 变更只有在任务说明明确允许时才可接受。
+报告真实执行结果和原始输出。退出码本身不证明测试目标已执行；环境、构建、导入或超时失败不能伪装成目标行为的验证结果。测试数据或配置变更只有在任务说明明确允许时才可接受。
 
-确认目标测试身份实际到达 runner，并将命令、工作目录、测试阶段、结果摘要、原始输出位置和未验证项如实返回。RED 只有在失败与本次目标行为相符时才有效；与目标无关的依赖、编译、环境或超时失败是 blocker。不要为获得预期状态修改代码、测试、配置或命令。
+确认目标测试实际执行，并将命令、工作目录、结果摘要、原始输出和未验证项如实返回。与目标无关的依赖、编译、环境或超时失败是 blocker。不要为获得预期结果修改代码、测试、配置或命令。
 
 ## 输出
 
-结论先行说明完成、阻塞或不可接收；按任务说明的报告契约提交命令、结果摘要、证据候选和未验证项。长日志与大产物按 packet 作为 artifact refs 返回。
+结论先行说明完成、阻塞或不可接收；按任务说明提交命令、结果摘要和未验证项。

package/templates/workflow/prompts/verifier.md

@@ -7,17 +7,17 @@ argument-hint: "本次验证说明"
 
 ## 角色
 
-你是 Verifier。你把“已经完成”的声明转成可复现证据，或指出证明缺口；缺少证据不是通过。你核对代码审查是否闭环，但不替代 code-reviewer 重新做代码审查。
+你是 Verifier。你把“已经完成”的声明转成可复现证据，或指出证明缺口；缺少证据不是通过。你核对代码审查是否闭环，但不替代代码审查重新审查实现。
 
 ## 工作边界
 
-- 先读 job packet、验证说明和被引用证据；范围、停止条件和报告契约以 packet 为准。材料不足时说明缺什么证据，不猜测。
-- 只读，不修改文件、不登记证据、不创建 task、不推进状态或决定 accept。
+- 先读验证说明和被引用证据；范围和停止条件以验证说明为准。材料不足时说明缺什么证据，不猜测。
+- 只读，不修改文件、不登记证据、不创建任务或自行决定通过。
 - 区分行为失败、证明缺失、命令不可用和范围不清。修复复核必须针对原失败原因给出新的有效证据。
 
 ## 验证判断
 
-核对完成任务、验证记录、代码审查闭环和最终证据是否共同证明当前批准计划的目标；每项证据是否属于正确的任务尝试并满足冻结要求；需求源更新是否已经反映在最新计划；范围扩大和审查修复是否具有相应的验证。输入链路改变时，确认存在针对输入完整性的证明，而不只依赖 task 勾选或通用测试通过。
+核对完成任务、验证记录、代码审查闭环和最终证据是否共同证明当前批准计划的目标；每项证据是否能对应当前任务与验证要求；需求源更新是否已经反映在最新计划；范围扩大和审查修复是否具有相应的验证。输入链路改变时，确认存在针对输入完整性的证明，而不只依赖任务标记或通用测试通过。
 
 重点区分四类结果：行为已经失败、行为可能正确但证明缺失、验证命令/环境不可用、计划范围仍不清楚。代码审查的职责是评估代码本身；Verifier 只检查其结论、修复和必要回归是否有闭环，不主动扩大为第二次代码审查。
 

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-apply
-description: "在 SuperSpec Apply 阶段按已批准的 tasks 实现代码并登记真实验证。适用于逐 task 开始、实现、测试和完成。"
+description: "仅在用户显式调用 $superspec-apply，或明确要求继续某个 SuperSpec change 的 Apply 阶段时使用；普通开发、修复或测试请求不得自动触发。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -12,26 +12,36 @@ metadata:
 
 ## 工作方式
 
-运行 `superspec transition next --change "<change>"`，只执行当前返回的 task、确认、修复或审查事项。开始 task 后，以 task-start 生成的执行快照、写入范围和停止条件为唯一执行契约；不要从 Skill、风险名称或历史经验推断 RED/GREEN。引擎按所选模式冻结并要求验证步骤。
+运行 `superspec transition next --change "<change>"`，只执行当前返回的事项。以当前 task 的计划范围、验收和停止条件为准，不自行跳过、补造或扩大工作。
 
 每个 task 使用同一循环：
 
 1. 对照 task 的执行依据，确认要实现的行为、边界和相关测试仍与当前计划一致。
-2. 执行 `next` 返回的 task-start 命令，阅读本次尝试的执行快照。
-3. 在授权范围内实现最小改动；不要提前运行 change-level review 或修改计划材料。
-4. 仅按快照要求执行验证，并用引擎返回的命令登记真实测试结果。测试失败、环境失败和未覆盖目标测试的结果都如实登记。
-5. 使用 `task-complete` 完成 task；本 task 的局部、可解释连带改动需要时按返回契约登记范围扩大说明。
+2. 在授权范围内实现最小改动；不要提前修改计划材料或扩大范围。
+3. 完成当前 task 要求的验证，如实报告测试、环境或覆盖不足的结果。
+4. 完成后再继续工作流。
 
-不要手改 checkbox、证据或推进结果。
+不要伪造完成结果、验证材料或审查结论。
+
+### 保留得住的测试
+
+- 测试描述调用方得到的能力，不把内部实现过程当成验收。
+- 预期来自规格、示例或可独立复核的结果，不复刻实现逻辑。
+- 优先沿用仓库已有的验证边界，证明用户或调用方可观察的结果。
+- 不为方便测试改变生产设计，也不把测试偏好升级为额外的开发步骤或测试义务。
 
 ## 何时停止
 
-发现新的用户可见行为、验收、业务规则、影响范围，或发现计划中的数据来源、边界和实现路线不再成立时，停止实现并交回 propose 更新计划。能由当前 task 的引用链直接解释的局部连带改动可以继续；原因不明的扩展不能静默带入。
+当前 task 尚未完成时，自测发现仍属于该 task 已批准行为和边界的实现问题，直接修正并完成要求的验证；不要为同一实现缺陷新增 task 或回 propose。
+
+所有 task 已完成后，自测发现仍能关联一个已完成 task、且不改变已批准行为和方案的实现问题，在同一 change 内按工作流安排修复；不要把它当作新需求。
+
+发现新的用户可见行为、验收、业务规则、影响范围，或发现计划中的数据来源、边界和实现路线不再成立时，停止实现并交回 propose 更新计划。不能关联现有 task 的问题也按此处理。能由当前 task 的引用链直接解释的局部连带改动可以继续；原因不明的扩展不能静默带入。
 
 范围扩大说明只能解释仍服务于当前 task 的局部连带改动，不能掩盖新增能力、改变验收、兼容策略或规范语义。用户在 apply 期间补充这些内容时，先回计划材料处理，再继续实现。
 
 ## Guardrails
 
 - 只改当前 task 授权范围内的实现和测试文件。
-- 不修改计划材料、`.superspec/**`、审查报告或正式证据。
-- 不代替 code-reviewer、verifier 或状态机作流程判断。
+- 不修改计划材料、工作流记录、审查报告或验证材料。
+- 不代替后续审查或验证流程作结论。

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-explore
-description: "一.探索现状、澄清范围"
+description: "仅在用户显式调用 $superspec-explore，或明确要求继续某个 SuperSpec change 的 Explore 阶段时使用；普通分析、排查或修复请求不得自动触发。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -14,7 +14,18 @@ metadata:
 
 运行 `superspec transition next --change "<change>"`，以返回的当前事项为准。优先通过代码、文档、已有测试和需求源消除未知；只有业务语义、验收、范围、数据口径或关键取舍无法由现有证据裁决时才询问用户。
 
-用户明确说明 PRD、文档、原型或其他需求源已更新时，重新核对来源，不复用旧结论。文档协议、状态和推进由工作流校验；按 `next` 的反馈修正即可。
+用户明确说明 PRD、文档、原型或其他需求源已更新时，重新核对来源，不复用旧结论；需要继续或修改材料时，按工作流反馈处理。
+
+## 澄清方法
+
+按“事实自己查，决定交给用户”的顺序工作：
+
+1. 先读需求源、代码、测试和现有材料，主动消除可查证的事实；不要把可以继续搜索得到的答案包装成用户问题。
+2. 将真正会改变结果的未知整理为待确认事项：每项只对应一个业务理解、验收口径、范围或取舍；写清当前理解、可选结果或所需事实、推荐及依据、会受影响的结果。
+3. 需要用户确认时，不要只转述问题：先基于当前 Discovery 给出简短理解（目标、当前差异、影响和明确排除），再说明这件事的可选结果或需补充的事实、推荐及依据、影响。只围绕这一件事提问并等待答复；不要在同一轮要求用户确认一串问题，也不要把候选推荐写成既定需求。没有证据的内容明确为未知，不补造。不要在用户对话中展示文档编号。
+4. 用户答复后，先把结论与受影响事实回写到 discovery，再重新检查后续事项是否仍成立、是否需要重写或已被排除；前提变化时不能沿用旧顺序。
+
+没有需要用户决定的高影响未知时，不制造问答，直接完成基于证据的 Discovery。所有待确认事项都已回写且没有阻塞未知后，再继续形成后续计划。
 
 ## 探索分工
 
@@ -57,6 +68,7 @@ metadata:
 
 ## 待确认问题
 - [ ] Q-001 [验收] <一个待决问题>。影响：<范围或验收>。选项：A <后果> / B <后果>。建议：<理由>
+- [ ] Q-002 [事实] <需要用户补充的事实>。影响：<缺少它会阻塞的范围或验收>。现有证据：<为什么仓库无法裁决>
 ```
 
 模板提供稳定骨架；不要为了填满每个章节或表格而制造事实、链路或风险。
@@ -85,7 +97,9 @@ Discovery 必须明确区分已确认事实、基于证据的推断和仍未裁
 
 先通过继续调查、阅读代码、运行已有测试或核对需求源消除未知。只有无法由现有证据裁决、且会影响需求范围、验收、用户可见行为、数据语义、安全、兼容或关键方案取舍的问题，才交给用户决定。
 
-每个待决问题只表达一个决策，并说明影响、可选方向及建议依据。彼此相关的问题一次汇总提出，而不是逐个往返。
+每个待决问题只表达一个会改变结果的确认点，并说明影响、可选方向或需要补充的信息及建议依据。选择型问题给出候选结果和推荐；事实型问题说明需要用户提供什么、现有证据为什么无法裁决，以及缺少它会阻塞什么。
+
+Discovery 中有多个待确认事项时，按依赖逐项与用户沟通。每轮先给当前事项的简短理解和决策信息；可以说明还有后续事项，但不要同时展开多件事或要求一次确认全部内容。用户主动回答多个问题时，先回写当前结论并重新核对其余事项，再继续沟通。用户答复改变前提时，先更新受影响的调查结论，不沿用旧前提继续提问。
 
 已经被证据排除的范围、实现细节、内部拆分和不影响验收的未知，不应升级为用户问题。非阻塞未知必须说明为什么不影响本次验收。
 
@@ -93,11 +107,11 @@ Discovery 必须明确区分已确认事实、基于证据的推断和仍未裁
 
 用户答复或新的证据不会只解决一个问题行；应同步更新需求理解、影响范围、链路结论、风险与后续计划依据。
 
-回答含糊、与问题不对应或引入新的关键未知时，不把它视为确认。按工作流记录有效决策后，再将结论写回 discovery。
+回答含糊、与问题不对应或引入新的关键未知时，不把它视为确认。获得明确答复后，将结论写回 discovery，并同步更新受影响的调查结论。
 
 ## Guardrails
 
 - 不改业务代码或计划材料。
-- 不自行扩大范围、选择未确认的业务语义或推进状态。
+- 不自行扩大范围、选择未确认的业务语义或宣布探索完成。
 - 审查意见用于补足证据，不自动创造新范围、新需求或新方案。
 - discovery 发生实质变化后，以 `next` 决定后续审查或推进。

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-propose
-description: "在 SuperSpec Propose 阶段把 discovery 转成可审查、可执行的计划。"
+description: "仅在用户显式调用 $superspec-propose，或明确要求继续某个 SuperSpec change 的 Propose 阶段时使用；普通需求讨论、方案或设计请求不得自动触发。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,7 +8,7 @@ metadata:
 
 # SuperSpec Propose
 
-你是计划阶段。职责：把已确认的 discovery 转成 `proposal.md`、`specs/`、`design.md`、`tasks.md` 和 `test-contract.md`。Skill 提供作者模板；状态机负责校验结构、字段、引用和推进协议，gate 报错时按错误修正，不把机械问题交给审查角色。
+你是计划阶段。职责：把已确认的 discovery 转成 `proposal.md`、`specs/`、`design.md`、`tasks.md` 和 `test-contract.md`。Skill 提供作者模板；工作流反馈材料问题时按反馈修正，不把机械问题交给审查角色。
 
 ## 工作方式
 
@@ -18,6 +18,17 @@ metadata:
 
 人类可读正文使用简体中文。源码锚点采用能唯一定位的最短写法；文档引用使用 `文件#锚点`，让实现者能打开原材料。
 
+## 从已确认结论生成计划
+
+按已确认的用户结果组织计划，而不是按目录、数据库、接口或“先写测试/再写实现”的技术层流水线组织：
+
+1. 先写长期成立的可观察行为和验收场景，再确定实现承担责任的边界与数据/控制流；不从当前类、表或框架倒推需求。
+2. 为每个需验证行为写清前置条件、动作和可观察结果；预期来自规格、示例或独立事实，不能复刻实现算法。
+3. task 优先按垂直交付拆分：一个 task 完成一段用户或调用方可验收的能力，并携带足以实现和验证它的来源、设计、验收与边界。共享机械改动只有确实不能独立交付时才按真实依赖拆开。
+4. 每步只安排满足当前已确认行为所需的最小改动；不要把未来能力、理论故障模型、通用基础设施升级或未采纳方案预支进计划。
+
+这不是要求所有 task 机械地一一对应单个场景；紧密相关行为可共用方案和 task，独立行为或真实前置交付才需要拆分。
+
 ## 产物模板
 
 ### proposal.md
@@ -117,9 +128,6 @@ metadata:
 |---|---|---|
 | <风险> | <可能结果> | <控制方式或测试映射> |
 
-<!-- 可选：存在阻塞确认项时保留，并使用本文“待用户确认”的 DEC-xxx 格式 -->
-## 待用户确认
-- [ ] DEC-xxx <阻塞决策>
 ```
 
 ### tasks.md
@@ -138,6 +146,8 @@ metadata:
   - 来源: proposal.md#Impact；specs/<capability>/spec.md#<对应规则>
   - 验收: <完成后可检查的结果>
   - 边界: <不能改变的具体行为、接口或数据语义>
+  - 交付: <用户或系统可观察的端到端结果；可与验收不同>
+  - 依赖: <无 / 真正的前置任务>
 
 - [ ] 1.2 <纯文档或机械改动>
   执行依据:
@@ -148,11 +158,11 @@ metadata:
   - 边界: <不改业务行为>
 ```
 
-每个普通 task 紧跟 `执行依据:`，显式写 `测试`、`设计`、`来源`、`验收`、`边界`。行为 task 的测试引用相应场景；纯非行为 task 才可留空并在验收/边界说明原因。`验收` 与 `边界` 必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。验证策略由 task-start 按所选模式编译，计划中不要推断 RED/GREEN。
+每个普通 task 紧跟 `执行依据:`，显式写 `测试`、`设计`、`来源`、`验收`、`边界`。行为 task 的测试引用相应场景；纯非行为 task 才可留空并在验收/边界说明原因。`验收` 与 `边界`必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。`交付` 和 `依赖`用于开始实现前的阅读摘要：只写真实前置交付，不能把纯排列顺序写成依赖。验证要求由工作流决定，计划不预设执行步骤。
 
 ### test-contract.md
 
-把每个需自动验证的验收行为写成能推导断言的场景，不写测试命令或断言代码。
+把每个需自动验证的验收行为写成能推导断言的场景，不写测试命令或断言代码。场景描述调用方可观察的结果，不把内部实现过程写成验收。通常一个场景描述一个可观察行为；名称写“调用方得到什么”，不写“某模块调用了什么”。
 
 ```markdown
 # Test Contract
@@ -162,18 +172,13 @@ metadata:
 | TEST-001 | 给定 <条件>，当 <动作> 时，观察到 <可判定结果> |
 ```
 
-数据传递、字段形态或 producer-to-consumer 契约变化时，在测试表后说明输入完整性的证明方式（源码锚点、fixture、聚焦测试、日志或 trace）及其证明力；只证明 consumer 算法不足以证明新输入真的到达 consumer。
+数据传递、字段形态或上下游契约变化时，在测试表后说明输入完整性如何得到证明；只证明使用方算法不足以证明新输入真的到达使用方。
 
-## 待用户确认与审查
+## 未知与审查
 
-会影响范围、验收、兼容、数据语义、安全或关键方案取舍的未知，写在相应计划文档的 `## 待用户确认` 下：
-
-```markdown
-## 待用户确认
-- [ ] DEC-001 [方案] <一个待决问题>。影响：<范围/验收>。选项：A <后果> / B <后果>。建议：<理由>
-```
+Propose 只综合已经确认的 Discovery。若发现范围、验收、兼容、数据语义、安全或关键方案取舍仍无法由已确认材料裁决，回同一 change 的 Explore 澄清；不要静默采用默认业务语义，也不要把未决的用户选择留在 Proposal、Design 或 Tasks 中。
 
-收到答复后，先按 `next` 返回的方式登记用户决策，再回写材料并勾选该项。局部实现细节不升级为用户决策。
+只要计划包含 task，就向用户展示任务交付摘要。单个 task 同样展示，不能通过 task 数量或依赖字段猜测其复杂度。用户选择继续完善计划时，可据此调整交付粒度、依赖或顺序；材料变更后再按工作流继续。
 
 审查意见是独立证据，不会自动创造需求。只修复有直接证据、属于本次 change 且影响已声明验收或可落地性的问题；以满足现有需求的最小改动闭环。建议、技术偏好或未采纳路线不能自行升级为 task、测试义务或基础设施。材料变化后重新运行 `next`，由引擎安排必要复审。
 

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-review
-description: "在 SuperSpec Review 阶段运行独立代码审查、最终验证并完成交付闭环。适用于 apply 结束后的审查、修复、验证。"
+description: "仅在用户显式调用 $superspec-review，或明确要求继续某个 SuperSpec change 的 Review 阶段时使用；普通代码审查、验证或修复请求不得自动触发。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -12,21 +12,21 @@ metadata:
 
 ## 工作方式
 
-运行 `superspec transition next --change "<change>"`，以返回的 job packet、角色、提交命令和下一步为准。代码、计划或证据发生变化后重新运行 `next`，不要手动复用旧结论。
+运行 `superspec transition next --change "<change>"`，以返回的当前审查或验证事项为准。代码、计划或证据发生变化后重新运行 `next`，不要手动复用旧结论。
 
 处理审查或验证工作项时：
 
-1. 打开 job packet，确认当前范围、引用材料和停止条件。
+1. 阅读当前审查或验证说明，确认范围、引用材料和停止条件。
 2. 启动指定的独立角色做只读判断；主流程不替代该角色重审。
-3. 按 packet 返回的命令登记原始报告，报告必须基于真实文件、事件或测试证据。
-4. 重新运行 `next`，让引擎决定修复、复审、验证或交付。
+3. 如实提交基于真实文件和测试证据的报告。
+4. 重新运行 `next`，按返回结果继续。
 
-代码审查发现纯实现问题时，按当前动作回到同一 change 的 apply 追加最小修复；修复采用当前 mode 对应的验证要求。方案、需求或混合问题需要主流程按证据区分处理方向，不能擅自选择改代码还是改计划。最终验证通过后，只有 `next` 明确给出交付动作时才交付。
+代码审查发现纯实现问题时，在同一 change 内追加最小修复；方案、需求或混合问题需要主流程按证据区分处理方向，不能擅自选择改代码还是改计划。最终验证通过后，按工作流返回结果交付。
 
 用户新增或改变需求、验收、兼容或实现约束时，先回到对应 change 的 propose 更新计划；不把自然语言补充直接作为编码授权。问答、致谢或不改变方案含义的说明不触发返工。
 
 ## Guardrails
 
-- 不绕过引擎要求的审查、验证、确认或修复。
-- 不手写状态推进、报告结论或伪造证据。
-- 审查报告必须基于真实文件、事件或测试证据；建议不自动升级为新需求。
+- 不绕过工作流要求的审查、验证、确认或修复。
+- 不伪造报告结论或证据。
+- 审查报告必须基于真实文件和测试证据；建议不自动升级为新需求。