@peterxiaoyang/superspec 0.1.32 → 0.1.34

package/README.md

@@ -158,27 +158,6 @@ openspec/changes/<变更ID>/.superspec/
 
 这里的 `<变更ID>` 就是一次需求变更的名字。
 
-`.superspec/` 要不要提交到 git，由你的团队决定。
-如果不提交，删掉后就没有 git 历史可以恢复。
-
-## 流程门禁
-
-SuperSpec 的阶段入口由 `superspec transition next --change <变更ID>` 驱动。
-
-当当前阶段还有未完成的用户确认、审查、验证或工作项时，`next` 会先返回这些事项，不会把下一阶段命令作为推荐路径。重复运行会创建审查工作项的 transition 时，如果同阶段工作项已经存在，CLI 会返回正常的门禁结果，不会写入新事件，也不会把它当作程序错误。
-
-这仍然是轻量流程控制，不是写入拦截。它约束按 SuperSpec 正常入口执行时的下一步建议和状态提交结果，不承诺阻止绕过流程的手动编辑。
-
-## Hook 会做什么
-
-SuperSpec 默认安装的 hook 只在子智能体启动和停止时运行：
-
-- 子智能体启动和停止时：记录这次子智能体运行的基本信息
-
-这些 hook 的默认超时时间是 `120` 秒。这个时间限制的是 hook 自己的检查过程，不限制 `npm test`、构建命令或子智能体本身能运行多久。
-
-hook 不是安全沙箱。默认 hook 只留下子智能体审计线索；它不会机械阻止写入，也不能把记录变成不可伪造的安全证明。
-
 ## 重要边界
 
 SuperSpec 能让流程更规范，但它不是安全锁。
@@ -215,18 +194,6 @@ superspec install
 
 `superspec init --scope project` 是兼容别名，也会执行同一套安装逻辑。
 
-### OpenSpec 中文输出
-
-OpenSpec 生成文档的语言应通过官方项目配置控制。在 `openspec/config.yaml` 中使用 `context`：
-
-```yaml
-schema: spec-driven
-
-context: |
-  语言：中文（简体）
-  所有产出物必须用简体中文撰写。
-```
-
 `superspec install` 会创建缺失的 `openspec/config.yaml`，或在没有顶层 `context` 时追加这段官方中文 context。如果文件已经有顶层 `context`，SuperSpec 不会覆盖它。
 
 可以用下面的命令检查生成的 instructions 是否包含语言上下文：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": {

package/templates/workflow/AGENTS.md

@@ -1,6 +1,8 @@
 <!-- SUPERSPEC:AGENTS:START -->
 本项目启用 SuperSpec。使用 `superspec-*` 工作流时，以 `superspec transition next --change "<change>"` 返回的下一步为准；流程完成前不得跳阶段、不得自称完成。
 
+即使用户没有显式调用 `superspec-*`，如果新输入像是在改变业务规则、产品口径、验收标准、示例规范或影响范围，编辑代码前先提醒并做只读确认：这是实现偏差，还是需要先回 `superspec-propose` 更新计划文档；不要直接把这类自然语言当作 apply 授权。
+
 当用户显式调用 `$superspec-explore` 工作流时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `$superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
 
 SuperSpec 创建的独立审查/验证工作项，视为已授权启动对应 subagent；无需再次询问用户。主会话不得自批这些工作项。

package/templates/workflow/prompts/architect.md

@@ -41,7 +41,8 @@ argument-hint: "本次架构审查说明"
 审查计划文档时，重点判断影响范围、技术决策和任务拆分是否能支撑后续实现，不要把文档格式本身当成目标。
 
 - `proposal.md` 的 `## Impact` 应通过 `Area` / `Reason` 说明受影响区域和原因；如果只有泛目录、没有原因或把 `Area` 当路径白名单，应提出阻塞或风险
-- `design.md` 应记录关键决策、替代方案和风险取舍；如果只是复制影响范围、任务清单或实现步骤，说明设计边界不清
+- `design.md` 应记录每个代码影响型需求的实现方向，粒度到路线选择即可；如果只是复制影响范围、任务清单或代码步骤，说明设计边界不清
+- 关键路线未定且未进入 `## 待用户确认`，或 `tasks.md` 无法从 `design.md` 的方向推出，应判为设计缺口
 - 当 discovery 含 `## 输入数据来源核查` 时，审查 `数据来源` 是否追到目标字段或集合最后一次会改变形态的位置；停在 consumer、validator、DTO 名称或机械一跳上游，应提出阻塞或风险
 - 审查设计是否把输入完整性决策和 consumer 算法决策分开；如果把“数据是否加载完整”和“如何比较/计算”混成一个决策，应要求拆清
 - 相关 `IDC-xxx` 为 `未知阻塞` 时，设计不得 ready；`未知非阻塞` 必须说明为什么不影响验收，并绑定验收口径或反例

package/templates/workflow/prompts/critic.md

@@ -69,7 +69,9 @@ argument-hint: "本次反方审查说明"
 - `Area` 只有泛目录，且没有原因或不确定性说明
 - `Reason` 只写“要改这里”，没有解释为什么受影响
 - `## Impact` 写成任务清单或路径白名单
-- `design.md` 把影响范围表、任务拆分或实现清单复制进去，导致技术决策不清
+- `design.md` 缺少实现方向，或把方向写成任务拆分、实现清单、代码步骤
+- 关键路线仍未决，且没有进入 `## 待用户确认`
+- `tasks.md` 需要的实现路线无法从 `design.md` 看出
 - `tasks.md` 的任务拆分过粗，把多个独立行为放进同一个执行单元，导致 apply 难以用一组清晰的 RED/GREEN 证据验收
 - task id 重复、不稳定，或分组标题混入 task id，导致后续执行命令容易指错任务
 - 普通说明或缩进 checkbox 承载了实际未完成工作，导致工作流无法自然推进

package/templates/workflow/prompts/executor.md

@@ -16,6 +16,7 @@ argument-hint: "本次执行说明"
 - 不要勾选 task，不要运行 change-level review，不要替代 `code-reviewer`、`verifier` 或主流程判断。
 - 如果 write scope 缺失、不安全、上下文不足、测试命令不明确或必须扩大范围，停止并报告 blocker。
 - 如果实现过程中发现实际输入数据来源、字段形态或 producer-to-consumer 链路与 discovery 的 `输入数据来源核查` 不一致，停止扩大实现并报告 blocker；不要在 apply 阶段悄悄补改 proposal/design/test-contract 或扩大任务范围。
+- 如果用户在本任务期间补充最新业务规则、产品口径、验收标准、示例规范或影响范围，停止实现并报告 blocker；不要把这类自然语言输入当作本 task 的实现授权。
 
 ## 本次任务说明
 

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

@@ -43,6 +43,7 @@ argument-hint: "本次测试审查说明"
 
 - TDD task 应能形成清晰 RED/GREEN 闭环，但 RED/GREEN 命令、断言或预期输出不应写进 `tasks.md`
 - `tasks.md` 只声明任务边界和 `tdd_required:true/false`；实际 RED/GREEN 细节属于 apply 阶段的 `record test-run` 证据
+- 根据 `design.md` 的实现方向判断测试契约是否覆盖主要风险；不要要求把具体测试命令或断言写回计划文档
 - 无法定义目标测试身份、RED 失败信号、GREEN 覆盖映射，或只靠退出码/笼统命令证明的测试方案，应使用 `verdict:"fail"`
 - `tdd_required:false` 必须有明确 `no_tdd_reason`
 - 不要求建立新的 test-contract 关联，也不要求把 RED/GREEN 细节塞回 task 行

package/templates/workflow/prompts/verifier.md

@@ -50,6 +50,7 @@ apply worker report 字段以本次任务说明中的 `verifier_report_required_
 核对最终实现和计划文档时：
 
 - 实际代码改动应能从 `proposal.md` 的 `## Impact`、`design.md` 的关键决策或已完成 task 找到合理解释；无法解释的用户可见行为、新能力或大范围改动应使用 `verdict:"fail"`
+- 实现应与 `design.md` 的方向一致；如果实际走了 design 未说明的新接口、新表、消息、迁移或外部依赖路线，应使用 `verdict:"fail"`
 - `tasks.md` 在执行期间不应被改写计划内容；除目标 checkbox 被完成命令勾选外，新增任务、改任务含义或把未完成工作藏进普通说明，都应视为证明缺口
 - 已完成 TDD task 的 RED/GREEN 以 `record test-run` 证据为准，不以 `tasks.md` 的文字描述为准
 - 对每个已完成 TDD task，核对同一个 `task_completed.attempt_id` 下是否同时存在 RED/characterization 和 GREEN；新证据必须带同一 `attempt_id`

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

@@ -25,10 +25,11 @@ metadata:
 
 每个任务的循环：
 
+0. **设计核对**：执行 `task-start` 前，确认本任务符合 `design.md` 的实现方向。缺少方向时先停止，不写 RED
 1. **任务开始**：`superspec transition task-start --change "<change>" --task <task_id>`
 2. **拿到执行尝试 ID**：从 task-start 的返回结果或 `superspec status` 中读取当前活跃 attempt 的 `attempt_id`
 3. **红灯验证**：写测试，跑测试确认失败，优先用 `superspec record test-run --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback
-4. **代码实现**：根据任务写代码实现,保证代码不出现过渡设计以及代码质量
+4. **代码实现**：根据任务写代码实现，避免过度设计，并保持代码质量。`design.md` 不锁死字段名、函数名、SQL 或局部写法
 5. **绿灯验证**：跑测试确认通过，优先用 `superspec record test-run --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback
 6. **任务结束标记完成**：`superspec transition task-complete --change "<change>" --task <task_id>`
 
@@ -66,6 +67,7 @@ no-TDD 任务（tdd_required:false + no_tdd_reason）跳过 RED/GREEN。
 - 需要判断影响范围或改动原因不自明时，参考 `proposal.md` 的 `## Impact`，但不要把它当作路径白名单
 - 编码时发现未列入影响范围的文件，如果从 diff 或引用链能直接解释为同一任务下的局部引用、测试辅助或机械连带改动，可以继续
 - 如果发现新增能力、用户可见行为、明显新增影响范围或原因不自明，停止扩大实现并报告给主流程；不要在 apply 阶段补改 `proposal.md`
+- 用户在 apply 期间或 apply 后补充“最新要求”时，先判断它是否改变业务规则、产品口径、验收标准、示例规范、兼容策略或影响范围；若改变，停止实现并交回主流程使用 `superspec-propose` 更新相关计划文档，不把自然语言当作 task 授权
 - 不修改 `proposal.md`、`design.md`、`specs/**` 或 `.superspec/**`
 - active attempt 期间不要修改 `tasks.md` 中除 `task-complete` 自动勾选目标 checkbox 外的内容
 - 不跳过 RED 直接写 GREEN

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

@@ -60,6 +60,8 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 
 规则：
 - `design.md` 写技术方案、关键决策、替代方案和风险取舍
+- 在上述内容中补充实现方向；每个代码影响型需求说明采用的路线，如复用现有链路、改接口、加表、发消息、定时任务或查询聚合
+- 实现方向只到路线级；不写字段名、函数名、SQL、类名或逐步代码。路线无法确定时写入 `## 待用户确认`
 - 不复制 `proposal.md` 的影响范围表
 - 不写任务拆分
 - discovery 含 `## 输入数据来源核查` 且影响设计成立时，记录输入完整性决策；相关 `IDC-xxx` 为 `未知阻塞` 时设计不得标 ready