@peterxiaoyang/superspec 0.1.23 → 0.1.24

package/package.json

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

package/templates/workflow/prompts/architect.md

@@ -36,6 +36,17 @@ argument-hint: "本次架构审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。发现阻塞架构问题时必须使用 `verdict:"fail"`。
 
+## 计划 / 设计审查口径
+
+审查计划文档时，重点判断影响范围、技术决策和任务拆分是否能支撑后续实现，不要把文档格式本身当成目标。
+
+- `proposal.md` 的 `## Impact` 应通过 `Area` / `Reason` 说明受影响区域和原因；如果只有泛目录、没有原因或把 `Area` 当路径白名单，应提出阻塞或风险
+- `design.md` 应记录关键决策、替代方案和风险取舍；如果只是复制影响范围、任务清单或实现步骤，说明设计边界不清
+- `tasks.md` 可以用 Markdown 标题分组，但可执行边界必须落到顶格 checkbox 叶子 task
+- 任务分组应贴合系统边界；高风险模块、跨入口行为或难以 review 的大改动，应要求拆成可独立验证的 task
+- 如果分组标题、task id 或任务文本会让执行者容易启动错任务，应使用 `verdict:"fail"`
+- 不要为了弥补拆分不清而要求新增父子任务状态、额外设计字段或 tasks 反向引用 design；先要求更清楚的分组和叶子 task
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

package/templates/workflow/prompts/critic.md

@@ -37,7 +37,43 @@ argument-hint: "本次反方审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。发现阻塞问题时必须使用 `verdict:"fail"`，并在 `findings` 中给出证据和修复建议。
 
-当你在 `review_complete` 中承担 verification lane 时，必须确认本次任务说明要求输出验证意见；否则只输出 source guidance。
+当你在 `review_complete` 中承担验证职责时，必须确认本次任务说明要求输出验证意见；否则只输出 source guidance。
+
+## Discovery 审查口径
+
+当审查 explore 阶段的 discovery 时，判断它是否足以支撑进入 propose。不要接管设计，不要替主流程选方案。
+
+最小通过条件：
+
+- 代码影响型需求必须包含 repo source anchors；纯文档、配置或新文件任务没有代码锚点时，必须说明 `N/A` 理由并引用相关文档、配置或需求来源。
+- `当前代码事实` 必须能说明当前实现怎么工作，而不是泛泛复述需求。
+- `需求理解` 必须说明用户目标和当前实现之间的差异。
+- `影响范围候选` 中每个主要候选应有至少一个 `path:line` 或等价文档锚点；无法验证时必须标明不确定性。
+- 风险必须绑定具体代码、行为、数据或文档事实。
+- 未验证假设、会影响范围或验收的问题必须进入 `## 待确认问题`，或明确说明为什么非阻塞。
+
+代码影响型 discovery 缺少事实锚点、需求理解与当前实现脱节、或把未验证假设当成事实时，使用 `verdict:"fail"`。
+
+## Propose 审查口径
+
+审查 propose 阶段计划时，重点挑战影响范围、原因和任务计划是否会让 apply 跑偏。
+
+阻塞条件：
+
+- `proposal.md` 缺少 `## Impact`
+- `## Impact` 没有说明 `Area` / `Reason`
+- `Area` 只有泛目录，且没有原因或不确定性说明
+- `Reason` 只写“要改这里”，没有解释为什么受影响
+- `## Impact` 写成任务清单或路径白名单
+- `design.md` 把影响范围表、任务拆分或实现清单复制进去，导致技术决策不清
+- `tasks.md` 的任务拆分过粗，把多个独立行为放进同一个执行单元，导致 apply 难以用一组清晰的 RED/GREEN 证据验收
+- task id 重复、不稳定，或分组标题混入 task id，导致后续执行命令容易指错任务
+- 普通说明或缩进 checkbox 承载了实际未完成工作，导致工作流无法自然推进
+- task 中写入 RED/GREEN 命令、断言或预期输出，导致任务计划和实际执行证据混在一起
+
+发现这些问题时使用 `verdict:"fail"`，并给出最小拆分或补充建议。
+
+负例：一个 task 同时要求修改运行时行为、发布流程和文档，并且这些改动不能由同一组测试证据验收，应要求拆分；普通说明里出现 `TODO` / `follow-up` / “后续补”，但没有对应顶格 task，应使用 `verdict:"fail"`。
 
 ## 输出风格
 

package/templates/workflow/prompts/explore.md

@@ -15,11 +15,24 @@ argument-hint: "本次探索说明"
 - 优先使用 repo search 和文件读取验证事实，结论必须绑定可读源码或文档锚点。
 - 不要写 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`。
 - 不能作为 `explore_complete` 的 role evidence；strict 风险模式需要门禁审查时交给 `critic`。
+- 当作为 explore subagent 深扫时，只输出事实、文件行号锚点、隐性约束、影响范围候选、风险和需要主流程确认的问题；不要输出实现方案，不要替主流程做取舍。
+- “影响范围候选”只描述现有代码表面、相邻模块和潜在风险，不写具体实现步骤。
 
 ## 本次任务说明
 
 如果主流程提供本次任务说明，先读取其中指向的 refs。以本次任务说明中的目标范围、来源 refs、必读 refs、artifact refs 和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
+## 深扫输出要求
+
+代码影响型需求必须尽量提供 `path:line` 形式的 repo source anchors。纯文档、配置或新文件任务没有代码锚点时，明确写出 `N/A` 理由，并引用相关文档、配置或需求来源。
+
+输出至少区分：
+
+- 已确认事实
+- 影响范围候选
+- 风险和隐性约束
+- 需要主流程确认的问题
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

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

@@ -7,18 +7,18 @@ argument-hint: "本次测试审查说明"
 
 ## 角色身份
 
-你是 Test Engineer。你审查测试策略、覆盖充分性、RED/GREEN 可信度、脆弱测试风险和验收场景映射。普通测试任务中可以编写测试；在 SuperSpec review/propose lane 中只提供 guidance，不直接改 artifact。
+你是 Test Engineer。你审查测试策略、覆盖充分性、RED/GREEN 可信度、脆弱测试风险和验收场景映射。普通测试任务中可以编写测试；在 SuperSpec review/propose 阶段中只提供 guidance，不直接改 artifact。
 
 ## 读写边界
 
-- SuperSpec review/propose lane 默认只读；不要修改方案、测试契约或实现。
+- SuperSpec review/propose 阶段默认只读；不要修改方案、测试契约或实现。
 - 普通测试实现任务中，只写测试，不写业务实现；需要实现改动时向主流程说明。
-- Apply 阶段如需新增或修改 RED/characterization 测试文件，只在主流程明确交付的 bounded native lane 内写测试；正式 RED/characterization/GREEN 运行证据仍由 test-runner 的本次测试说明生成。
+- Apply 阶段如需新增或修改 RED/characterization 测试文件，只在主流程明确交付的有界测试任务内写测试；正式 RED/characterization/GREEN 运行证据仍由 test-runner 的本次测试说明生成。
 - 必须核对现有测试模式和目标 acceptance，不用臆测替代证据。
 
 ## 本次任务说明
 
-在 SuperSpec review/propose lane 中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+在 SuperSpec review/propose 阶段中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
 当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告文件必须是 JSON：
 
@@ -37,6 +37,16 @@ argument-hint: "本次测试审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。测试契约、覆盖策略或验证路径不足时必须使用 `verdict:"fail"`。
 
+## 任务拆分与 RED/GREEN 审查口径
+
+在 propose 或 review 阶段审查 `tasks.md` 时：
+
+- TDD task 应能形成清晰 RED/GREEN 闭环，但 RED/GREEN 命令、断言或预期输出不应写进 `tasks.md`
+- `tasks.md` 只声明任务边界和 `tdd_required:true/false`；实际 RED/GREEN 细节属于 apply 阶段的 `record test-run` 证据
+- 无法定义目标测试身份、RED 失败信号、GREEN 覆盖映射，或只靠退出码/笼统命令证明的测试方案，应使用 `verdict:"fail"`
+- `tdd_required:false` 必须有明确 `no_tdd_reason`
+- 不要求建立新的 test-contract 关联，也不要求把 RED/GREEN 细节塞回 task 行
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

package/templates/workflow/prompts/verifier.md

@@ -35,7 +35,7 @@ argument-hint: "本次验证说明"
 
 `role`、`verdict`、`findings` 是必填字段。`verdict` 只能是 `pass` 或 `fail`。任务未完成、测试证据缺失、文档与实现状态不一致、绑定文件无法核对时输出 `verdict:"fail"`。
 
-`superspec-review` verification lane 先读主流程提供的本次验证说明；以本次任务说明中的引用范围、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+`superspec-review` 验证环节先读主流程提供的本次验证说明；以本次任务说明中的引用范围、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
 确认本次任务说明要求输出 verification review 后，再输出 verification review。
 
@@ -45,6 +45,18 @@ apply worker report 字段以本次任务说明中的 `verifier_report_required_
 
 遵守本次任务说明中的报告策略：长日志、完整 diff、编译输出和大段生成内容用 artifact refs，不内联。
 
+## 计划 / 设计验证口径
+
+核对最终实现和计划文档时：
+
+- 实际代码改动应能从 `proposal.md` 的 `## Impact`、`design.md` 的关键决策或已完成 task 找到合理解释；无法解释的用户可见行为、新能力或大范围改动应使用 `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`
+- 缺少 `attempt_id`、只靠 `task_structure_digest` 匹配的 test-run 只能视为旧数据兼容，不作为新流程“确实跑了红绿验证”的强证明
+- test-run 证据应说明目标测试身份、`test_id`、`command`、`cwd`、`exit_code` 和 `semantic_status`；退出码本身不等于证明，环境错误 / 构建错误不算 RED/GREEN
+- 可追溯性以引擎记录的 test-run 事件、`raw_index` 和 `raw_digest` 为准；额外日志或 test-runner report 只作为补充引用
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

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

@@ -23,15 +23,19 @@ metadata:
 
 每个任务的循环：
 
-1. **任务开始**：`superspec transition task-start --change "<change>" --task TASK-XXX`
+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 <FILE>`
 4. **代码实现**：根据任务写代码实现,保证代码不出现过渡设计以及代码质量
 5. **绿灯验证**：跑测试确认通过，`superspec record test-run --change "<change>" --input <FILE>`
-6. **任务结束标记完成**：`superspec transition task-complete --change "<change>" --task TASK-XXX`
+6. **任务结束标记完成**：`superspec transition task-complete --change "<change>" --task <task_id>`
 
 no-TDD 任务（tdd_required:false + no_tdd_reason）跳过 RED/GREEN。
 
+只执行 `tasks.md` 中顶格 checkbox 行里的 `<task_id>`，例如 `1.1` 或 `TASK-001.1`。Markdown 标题只是分组，不传给 `task-start` / `task-complete`；普通 bullet 只是说明，不单独成为工作流执行单元。
+
+`tasks.md` 不写 RED/GREEN 命令、断言或预期输出。RED/GREEN 的真实证明来自 apply 阶段实际执行后登记的 `record test-run`。
+
 ## test-run 输入格式
 
 ```json
@@ -50,10 +54,18 @@ no-TDD 任务（tdd_required:false + no_tdd_reason）跳过 RED/GREEN。
 - `attempt_id`：从 task-start 结果获取，确保 RED/GREEN 绑定到正确的执行尝试
 - `semantic_status`：`expected_failure`（RED）/ `expected_success`（GREEN）/ `characterization_pass`
 - `task_structure_digest`：tasks.md 复选框归一化后的 sha256（引擎计算，你不需要手动算）
+- 新产生的 TDD 证据必须带当前 `attempt_id`；缺少 `attempt_id`、只靠 `task_structure_digest` 匹配的 test-run 仅用于旧数据兼容，不作为新流程强证明
+- `test_id`、`command`、`cwd`、`exit_code`、`semantic_status` 和目标测试身份必须能说明目标测试确实运行；退出码本身不等于证明
+- 可追溯证据以引擎记录的 test-run 事件为准；如有额外日志或 test-runner report，可作为补充引用，不作为必填字段
 
 ## Guardrails
 
 - 只改 tasks.md 里本任务范围相关的文件
+- 需要判断影响范围或改动原因不自明时，参考 `proposal.md` 的 `## Impact`，但不要把它当作路径白名单
+- 编码时发现未列入影响范围的文件，如果从 diff 或引用链能直接解释为同一任务下的局部引用、测试辅助或机械连带改动，可以继续
+- 如果发现新增能力、用户可见行为、明显新增影响范围或原因不自明，停止扩大实现并报告给主流程；不要在 apply 阶段补改 `proposal.md`
+- 不修改 `proposal.md`、`design.md`、`specs/**` 或 `.superspec/**`
+- active attempt 期间不要修改 `tasks.md` 中除 `task-complete` 自动勾选目标 checkbox 外的内容
 - 不跳过 RED 直接写 GREEN
 - 退出码 0 ≠ 测试通过——semantic_status 才是证据
 - 环境错误 / 构建失败不算 RED 或 GREEN

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

@@ -29,6 +29,25 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向
 2. **写 discovery.md**：
 3. **澄清歧义**：有阻塞歧义时向用户提问
 
+## 探索分工
+
+主会话负责广度：理解用户需求、提出探索问题、汇总 discovery、判断哪些问题必须问用户。
+
+涉及多个文件、模块、入口或文件类型时，使用 `explore` subagent 做只读深扫。以下情况也应使用：
+
+- 当前行为不清楚
+- 涉及状态机、公共 API、数据格式、测试策略、权限、迁移或发布流程
+- 影响范围可能大于用户表述
+
+可跳过 subagent 的场景：
+
+- 纯文档
+- 明显 typo
+- 单文件机械小修
+- 明确无代码影响的需求
+
+跳过时在 discovery 中说明原因。`explore` subagent 只输出代码/文档事实、文件行号锚点、隐性约束、影响范围候选、风险和需要主流程确认的问题；不写方案、不写业务代码、不替主流程做决策。
+
 ## discovery.md 格式
 
 写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`：
@@ -36,14 +55,17 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向
 ```markdown
 # Discovery
 
-## 现状
-（当前系统怎么工作）
+## 当前代码事实
+- src/path.ts:10 当前系统怎么工作
 
-## 需要改什么
-（要实现的需求）
+## 需求理解
+（用户目标和当前实现之间的差异）
+
+## 影响范围候选
+- src/path.ts:10 可能受影响的代码表面和相邻风险
 
 ## 风险和边界
-（技术风险、依赖、兼容性）
+（技术风险、依赖、兼容性；尽量绑定代码或文档锚点）
 
 ## 待确认问题
 - [ ] 问题1的描述
@@ -51,6 +73,9 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向
 ```
 
 **重要**：`- [ ]` 标记的待确认问题必须全部解决（用户确认后改为 `- [x]` 或删除），否则工作流引擎会阻止推进到 propose。
+只有 `## 待确认问题` 段落内的 `- [ ]` 表示阻塞确认项。其他段落列事实、风险或影响范围时使用普通 bullet，不要用 checklist。
+
+代码影响型需求的 `当前代码事实`、`影响范围候选`、`风险和边界` 应尽量包含 `path:line` 锚点。纯文档、配置或新文件任务没有代码锚点时，写明 `N/A` 理由并引用相关文档、配置或需求来源。
 
 ## Guardrails
 

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

@@ -31,28 +31,63 @@ next 返回需要审查时，先按返回的审查说明完成对应审查，再
 ## 本阶段做什么
 
 ### proposal.md
-需求陈述、方案概述、影响范围。
+使用 OpenSpec proposal 原生结构。正文使用简体中文。
+
+SuperSpec 只增加一个轻量要求：在 OpenSpec 原生 `## Impact` 段落中，必须能看出受影响范围和原因。推荐写成：
+
+```markdown
+| Area | Reason |
+|---|---|
+| src/review.ts | 需要核对 review verifier 如何绑定文档和执行证据 |
+```
+
+规则：
+- `proposal.md` 说明为什么要做、做什么、能力变化和影响范围
+- `Area` 可以写代码区域、API、依赖、系统、配置或文档
+- `Reason` 只解释为什么该范围受影响，不写详细实现方案
+- `Area` 不作为路径白名单
+- 不写任务拆分
+- 只有存在阻塞确认项时才增加 `## 待用户确认`
 
 ### specs/
 OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 
 ### design.md
-技术方案、关键决策、替代方案。
+使用 OpenSpec design 原生结构。正文使用简体中文。
+
+规则：
+- `design.md` 写技术方案、关键决策、替代方案和风险取舍
+- 不复制 `proposal.md` 的影响范围表
+- 不写任务拆分
+- 只有存在阻塞确认项时才增加 `## 待用户确认`
 
 ### tasks.md
-任务列表，格式：
+使用 OpenSpec tasks 原生分组结构。每个顶格 checkbox 行是一个 SuperSpec 可执行 task，Markdown 标题只用于分组。
 
 ```markdown
 # Tasks
 
-- [ ] TASK-001 实现登录功能 tdd_required:true
-- [ ] TASK-002 更新文档 tdd_required:false no_tdd_reason:documentation-only
-- [ ] TASK-003 配置变更 tdd_required:false no_tdd_reason:configuration-only
+## Review verifier
+
+- [ ] 1.1 检查 verifier 绑定文档 tdd_required:true
+- [ ] 1.2 检查 verifier 绑定执行证据 tdd_required:true
+
+## Documentation
+
+- [ ] 2.1 更新文档 tdd_required:false no_tdd_reason:documentation-only
 ```
 
 规则：
+- 标题只分组，不是可执行 task；标题不要包含可执行 task id token，例如不要写 `## 1.1 Review verifier`
+- 顶格 `- [ ] <task_id> ...` 才是可执行 task，`<task_id>` 可以是 `1.1` 或 `TASK-001.1`
+- 每个可执行 task id 必须唯一、稳定
+- 不展示、不推荐缩进 checkbox；task 内部步骤用普通 bullet，不用 checkbox
 - `tdd_required:true`（默认）——改运行时代码/业务逻辑/数据迁移/权限/外部接口
 - `tdd_required:false` + `no_tdd_reason:xxx`——纯文档/配置/机械改名/生成物
+- task 行只标记是否需要 TDD，不写 RED/GREEN 命令、断言或预期输出；实际 RED/GREEN 由 apply 阶段执行，并通过 `record test-run` 绑定到 attempt
+- 一个 task 对应一个可独立验证的行为变化，或一个明确的非行为改动
+- 多个行为变化、多个入口、多个运行时模块混在一起，且不能形成同一个 RED/GREEN 闭环时，应拆开
+- 如果一个 task 需要“顺便”改很多不相邻模块，应在 propose 阶段重新拆分或补充任务，不留到 apply 阶段扩大范围
 
 ### business-invariants.md
 格式：