@peterxiaoyang/superspec 0.1.1 → 0.1.3

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

@@ -1,6 +1,9 @@
 ---
 name: superspec-apply
-description: "3.在 SuperSpec RED/GREEN guard 检查下执行 tasks，并从 OpenSpec `openspec instructions apply` 获取任务上下文、顺序和进度。 / Apply tasks under SuperSpec RED/GREEN guard checks, delegating task context, ordering, and progress to OpenSpec `openspec instructions apply`."
+description: "3.方案通过后用：按 tasks 一项项写代码、跑测试、记录证据；每个任务都要先证明测试会失败，再实现到测试通过。"
+metadata:
+  author: SuperSpec
+  source: SuperSpec
 ---
 
 # SuperSpec Apply
@@ -11,8 +14,23 @@ description: "3.在 SuperSpec RED/GREEN guard 检查下执行 tasks，并从 Ope
 - 保留命令、路径、JSON 字段、gate 名、task/test id、代码标识符和外部 API 名称的原文。
 - 当 OpenSpec 模板要求固定标题或字段时，保留模板结构，只将正文内容写成中文。
 - 对话窗口里的解释、总结、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
+- 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
+- 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
 - 向用户转述 guard / review 输出时，不要直接贴英文 `message`、`next_allowed_actions` 或英文模板标题；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
+## 命令执行 / Shell
+
+- Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
+- macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
+
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 task 必要 artifact、OpenSpec instructions apply 返回的 `contextFiles`、native subagent `output_ref` 的摘要/结论段，以及 task RED/GREEN 所需的最小测试摘要。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- RED/GREEN 仍按 task 的 `test_refs` 记录 gate-driving evidence；同一次命令输出可以作为共享 raw log 被引用，但不要仅凭聚合日志替代每个 task/test 所需的 RED/GREEN 证据字段。
+- 使用按运行合并建档的 `test_ids[]` 清单时，每个 claimed id 都必须出现在引用的 raw log 中；若当前 task gate 需要单个 `test_id` 覆盖，仍要补齐对应 gate-driving evidence。
+
 在 propose package 完成后使用本 skill 执行实现任务。**Task context、ordering 和 progress 来自 OpenSpec native apply instructions**（`openspec instructions apply`）；SuperSpec 为每个 task 包上一层 RED/GREEN guard checks。
 
 ## 边界 / Boundaries
@@ -21,18 +39,18 @@ description: "3.在 SuperSpec RED/GREEN guard 检查下执行 tasks，并从 Ope
 - SuperSpec 覆盖 OpenSpec apply skill 的直接实现循环：对应 SuperSpec RED/GREEN guard 允许之前，不要编辑实现，也不要勾选 task。
 - Apply 只能在 propose package 完成后开始。
 - Task list、`contextFiles` 和 dynamic instruction **必须**来自 `openspec instructions apply --json`。不要自行发明 task list，也不要跳过 native context files。
-- 主线程负责编排和编辑；role review evidence 仍必须来自 native subagents。
+- 主流程负责编排和编辑；role review evidence 仍必须来自 native subagents。
 - `check-task-edit` 允许之前，不得进行 task 的实现编辑。`check-task-complete` 允许之前，不得勾选 task checkbox。
 - `openspec instructions apply --json` 返回 `state:"all_done"` 只表示 `tasks.md` 当前全部勾选；它不等于 workflow 已经通过 review。若存在 live/pass 的 `kind:"main_adjudication"` 且 `review_decision:"request_changes"`，必须先按其路由决定是 reopen 既有 task，还是停止并回 propose / change update。
 - 若存在 live/pass 的 `main_adjudication(review_decision:"request_changes")` 或 unresolved `task_reopen`，apply 必须把 reopen 分支视为高优先级状态；此时忽略 OpenSpec `state:"all_done"` 的归档建议，不得结束 apply。
-- 对已完成 task 的合法回退路径固定为：补齐 reopen package（`task_reopen` + 配套 `status:"superseded"` evidence）-> `check-task-reopen` -> 仅把目标 task 的 checkbox 从 `[x]` 改回 `[ ]` -> 重新 RED/GREEN -> `check-task-complete` -> 勾回 `[x]` -> `task_reopen_resolved`。这些 reopen lifecycle evidence 一律由 `superspec-apply` 主线程创建。不要把 reopen 当普通 pending task，也不要绕过 guard 直接手工回退。
+- 对已完成 task 的合法回退路径固定为：补齐 reopen package（`task_reopen` + 配套 `status:"superseded"` evidence）-> `check-task-reopen` -> 仅把目标 task 的 checkbox 从 `[x]` 改回 `[ ]` -> 重新 RED/GREEN -> `check-task-complete` -> 勾回 `[x]` -> `task_reopen_resolved`。这些 reopen lifecycle evidence 一律由 `superspec-apply` 主流程创建。不要把 reopen 当普通 pending task，也不要绕过 guard 直接手工回退。
 - 若当前仓库尚未暴露 `check-task-reopen` 或等效 reopen-aware apply surface，本 skill 必须 fail-closed：报告协议未启用，不得建议 archive，也不得手工回退 checkbox。
 - v1 evidence 是 audit-only/self-reported；实际命令输出应尽量记录到 `.superspec/raw/`。
 
 ## 步骤 / Steps
 
-1. 对 apply isolation 和 execution mode 使用 AskUserQuestion，并等待明确选择。
-2. 当 dirty worktree、untracked files 或 branch state 需要决策时，使用 AskUserQuestion 处理 branch handling。
+1. 对实现隔离（apply isolation）和执行模式（execution mode）使用 AskUserQuestion，并等待明确选择；记录 `gate:"apply_isolation"` 的 `human_confirmation` evidence，必须包含 `confirmation_text`、`confirmed_refs` 和当前 `tasks_structure_hash`。
+2. 当 dirty worktree、untracked files 或 branch state 需要确认时，使用 AskUserQuestion 处理分支状态。
 3. 验证 apply readiness：
    ```text
    superspec guard check-apply-ready --change "<change>"
@@ -43,9 +61,9 @@ description: "3.在 SuperSpec RED/GREEN guard 检查下执行 tasks，并从 Ope
    ```
    读取 `contextFiles` 下的每个路径，遵守 `openspec-apply-change` 的要求。把返回的 task list、progress 和 dynamic instruction 作为实现 source of truth，并按 `tasks.md` 的结构化字段（`dependencies`、`parallel_group`、`read_scope`、`write_scope`、`test_refs`、`invariant_refs`）判断串行/并行顺序。
 5. 先判断是否进入 review 驱动的 reopen 分支：
-   - 如果 native apply 返回 `state:"all_done"`，但当前 change 仍有 live/pass 的 `kind:"main_adjudication"` 且 `review_decision:"request_changes"`，或已经存在 unresolved `task_reopen`，不要把它当成“可归档”。
+   - 如果 native apply 返回 `state:"all_done"`，但当前 change 仍有有效的最终审查判断要求返工（内部 `review_decision:"request_changes"`），或已经存在 unresolved `task_reopen`，不要把它当成“可归档”。
    - 若 `request_changes_route:"reopen_tasks"`，读取 `reopen_task_ids`，逐个判断当前 task 所处阶段：
-     - 如果该 task 仍是 `[x]`，说明还处于首次回退前；先由主线程基于本轮 review 的结构化 output 写出该 task 的 `task_reopen` evidence 与配套 `status:"superseded"` evidence，形成完整 reopen package，再执行：
+     - 如果该 task 仍是 `[x]`，说明还处于首次回退前；先由主流程基于本轮 review 的结构化 output 写出该 task 的 `task_reopen` evidence 与配套 `status:"superseded"` evidence，形成完整 reopen package，再执行：
      ```text
      superspec guard check-task-reopen --change "<change>" --task-id "<task-id>"
      ```
@@ -58,7 +76,7 @@ description: "3.在 SuperSpec RED/GREEN guard 检查下执行 tasks，并从 Ope
    ```
 7. 在 runtime/business implementation edits 前产出 RED evidence，除非有允许的 `no_tdd_reason` 或处于现状锁定测试模式（`characterization mode`）。这里的 `characterization` 指“先把当前真实行为测出来并锁住，重构后保持一致”。RED/GREEN evidence 必须引用 task 的 `test_refs`，并在 task 声明 `invariant_refs` 时同步记录 `invariant_refs`。若 task 来自 reopen，本轮 successor GREEN / alternative verification / manual verification 必须携带同一 `reopen_id`。
 8. 按 native dynamic instruction 和 `contextFiles` 指引，实现最小 task scope。
-9. 产出 GREEN evidence，保留 `test_id`、`invariant_refs`、命令、输出摘要和 raw log ref。
+9. 产出 GREEN evidence，保留 `test_id`、`invariant_refs`、命令、输出摘要和 raw log ref；raw log ref 指向原始输出文件，evidence 中只写必要摘要，不复制完整日志。
 10. 勾选 task 前执行任务完成检查（`check-task-complete`）：
    ```text
    superspec guard check-task-complete --change "<change>" --task-id "<task-id>"
@@ -69,6 +87,6 @@ description: "3.在 SuperSpec RED/GREEN guard 检查下执行 tasks，并从 Ope
     - 回退并恢复该 task 的 checkbox
     - 在该 task 既有 `write_scope` 内返工
     若需要修改 sibling task 的 `write_scope`，停止并对 sibling 单独 reopen，或回 propose / 新开 change。
-12. 如果 scope expands，停止并通过 AskUserQuestion 重新设计或拆分新 change。
+12. 如果实现范围扩大（scope expands），停止并通过 AskUserQuestion 重新设计或拆分新 change。
 
 遇到任何 guard `block` 就停止。

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

@@ -1,6 +1,9 @@
 ---
 name: superspec-archive
-description: "5.通过原生 `openspec archive` 归档 SuperSpec OpenSpec change，并执行 SuperSpec preservation checks。 / Archive an SuperSpec OpenSpec change via native `openspec archive` with SuperSpec preservation checks."
+description: "5.所有审查和验证通过后用：把完成的 change 归档到 specs，并确认关键证据和历史没有丢失；这一步是流程收尾。"
+metadata:
+  author: SuperSpec
+  source: SuperSpec
 ---
 
 # SuperSpec Archive
@@ -11,8 +14,21 @@ description: "5.通过原生 `openspec archive` 归档 SuperSpec OpenSpec change
 - 保留命令、路径、JSON 字段、gate 名、task/test id、代码标识符和外部 API 名称的原文。
 - 当 OpenSpec 模板要求固定标题或字段时，保留模板结构，只将正文内容写成中文。
 - 对话窗口里的解释、确认、总结和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
+- 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
+- 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
 - 向用户转述 guard / archive 输出时，不要直接贴英文 `message`、`next_allowed_actions` 或英文模板标题；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
+## 命令执行 / Shell
+
+- Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
+- macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
+
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算 archive 判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 preservation manifest，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、archive preservation 摘要、OpenSpec archive 输出摘要，以及最终验证 archive 结果所需的最小 manifest 信息。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+
 仅在 `review_complete` passes（其中已经包含 final verification）后使用本 skill。
 
 ## 边界 / Boundaries
@@ -25,7 +41,7 @@ description: "5.通过原生 `openspec archive` 归档 SuperSpec OpenSpec change
 
 ## 步骤 / Steps
 
-1. 对 final `archive_ready` confirmation 使用 AskUserQuestion，等待明确选择。记录 archive-scoped human-confirmation evidence。当前 v1 不询问也不使用 `--skip-specs`；若 change 不应同步 specs，应先回到 propose/change update 调整 OpenSpec 包，而不是在 archive 阶段跳过。
+1. 对 `archive_ready` 最终确认使用 AskUserQuestion，等待明确选择。记录 archive-scoped human-confirmation evidence。当前 v1 不询问也不使用 `--skip-specs`；若 change 不应同步 specs，应先回到 propose/change update 调整 OpenSpec 包，而不是在 archive 阶段跳过。
 2. 检查 archive readiness 并生成 preservation manifest：
    ```text
    superspec guard check-archive-ready --change "<change>"

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

@@ -1,6 +1,9 @@
 ---
 name: superspec-explore
-description: "1.探索并澄清需求，进入 SuperSpec propose 前完成 OpenSpec explore 立场和 critic 复核。 / Explore and clarify requirements before SuperSpec propose, adopting OpenSpec's explore stance plus critic review."
+description: "1.新需求刚开始时用：先把目标、范围、风险和现有代码事实弄清楚，产出探索记录（`discovery.md`）；这一步只探索，不写正式方案，也不改代码。"
+metadata:
+  author: SuperSpec
+  source: SuperSpec
 ---
 
 # SuperSpec Explore
@@ -10,15 +13,30 @@ description: "1.探索并澄清需求，进入 SuperSpec propose 前完成 OpenS
 - 默认使用简体中文撰写所有人类可读产物、分析、报告、说明和 OpenSpec 文档正文。
 - 保留命令、路径、JSON 字段、gate 名、task/test id、代码标识符和外部 API 名称的原文。
 - 当 OpenSpec 模板要求固定标题或字段时，保留模板结构，只将正文内容写成中文。
-- 对话窗口里的解释、披露、总结、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
+- 对话窗口里的解释、问题说明、总结、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
+- 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
+- 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
 - 向用户转述 guard / review 输出时，不要直接贴英文 `message`、`next_allowed_actions` 或英文模板标题；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
+## 命令执行 / Shell
+
+- Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
+- macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
+
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 gate 必要 artifact、OpenSpec instructions 返回的必要 context、native subagent `output_ref` 的摘要/结论段，以及用户确认所需的最小原文。
+- 当前轮披露循环所需的最小结构化字段必须读取，不能只看 `output_ref` 摘要；包括 role evidence 的 `findings[]`、`finding_uid`、`decision_scope_key`、逐字 `summary`、`target_refs`，以及本轮 digest 需要引用的 evidence id。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- native subagent 的 `output_ref` 应指向简洁审查报告；原始命令输出或长日志放在 raw/report 文件中被引用，不作为默认阅读材料。
+
 在 init 之后、编写 OpenSpec proposal package 之前使用本 skill。
 
 ## 边界 / Boundaries
 
-- 先桥接 repo-local OpenSpec explore skill：读取 `.codex/skills/openspec-explore/SKILL.md`，并遵守其中的 explore 立场与 `OpenSpec Awareness` 指引。
-- SuperSpec 在 OpenSpec explore 之上增加更严格的边界：**只思考和调查，不实现**。主线程可以读代码、搜索代码并创建 `discovery.md` evidence，但不能修改应用代码，也不能在本阶段编写 OpenSpec planning artifacts。如果 OpenSpec explore 建议把决策沉淀到 proposal/specs/design/tasks，请先记录到 discovery，再交给 `superspec-propose`，由 `openspec instructions` 生成 OpenSpec artifacts。
+- 先桥接 repo-local OpenSpec explore skill：读取 `.codex/skills/openspec-explore/SKILL.md`，并按它的探索方式工作：像需求探索搭档一样帮助用户澄清目标、调查代码、比较方案和暴露风险，不急着下结论。
+- 相比 OpenSpec 的原始探索模式，SuperSpec 增加了更严格的边界：**只思考和调查，不实现**。主流程可以读代码、搜索代码，并把发现写成探索记录（`discovery.md`）作为 evidence；但不能修改应用代码，也不能在本阶段编写 OpenSpec planning artifacts。如果调查过程中发现需要沉淀 proposal/specs/design/tasks，请先记录到探索记录（`discovery.md`），再交给 `superspec-propose`，由 `openspec instructions` 生成 OpenSpec artifacts。
 - Explore 只产出需求和上下文证据；不完成 OpenSpec proposal、specs、design 或 tasks。
 - 需求 critique evidence 必须来自 repo-local `critic` native subagent。
 - v1 evidence 是 audit-only/self-reported；除非有 OpenSpec facts 支撑，不要把它描述成强制运行时事实。
@@ -26,20 +44,20 @@ description: "1.探索并澄清需求，进入 SuperSpec propose 前完成 OpenS
 ## 范围收敛透明度 / Scope Transparency
 
 - Agent 可以在 explore/propose 前基于证据收敛范围，但不得静默收窄用户目标。
-- 当用户目标、现有实现或合理利益相关方预期自然覆盖多个层级、模块、入口、流程、角色或行为，而 discovery/proposal/design 只准备覆盖其中一部分时，必须显式记录纳入范围、排除范围、排除理由、已知或可合理推断的影响，以及仍未知但会影响范围判断的风险。
+- 当用户目标、现有实现或合理利益相关方预期自然覆盖多个层级、模块、入口、流程、角色或行为，而探索记录、proposal 或 design 只准备覆盖其中一部分时，必须显式记录纳入范围、排除范围、排除理由、已知或可合理推断的影响，以及仍未知但会影响范围判断的风险。
 - 不能把“本轮先做最小改动”“默认不处理其他模块”“按当前实现猜测无影响”作为隐式排除理由；这些都必须写成可审查的范围决策。
-- `critic` 必须阻塞未说明的关键范围收窄：如果范围收敛会改变用户合理预期、验收口径、兼容承诺、测试边界或后续实现风险，而 artifact 没有说明纳入/排除/理由/影响，则不能通过 explore/propose handoff。
+- `critic` 必须拦住未说明的关键范围收窄：如果范围收敛会改变用户合理预期、验收标准、兼容承诺、测试边界或后续实现风险，而 artifact 没有说明纳入/排除/理由/影响，则不能通过 explore/propose handoff。
 
-## 审查披露循环 / Review Disclosure Loop（DISC Phase 1）
+## 审查问题确认循环 / Review Disclosure Loop（DISC Phase 1）
 
-多角色审查发现的问题**不允许主线程自行消化**。material 问题包括：范围（`scope`）、非目标（`non_goal`）、验收口径（`acceptance`）、业务语义（`business_semantics`）、设计边界（`design_boundary`）。这些问题必须以原文披露给用户，拿到用户裁决后才能继续。
+多角色审查发现的问题**不允许主流程自行处理掉**。关键问题包括：范围（`scope`）、非目标（`non_goal`）、验收标准（`acceptance`）、业务语义（`business_semantics`）、设计边界（`design_boundary`）。这些问题必须按原文展示给用户，拿到用户确认后才能继续。
 
-- critic review evidence 必须携带 `review_round_id`（形如 `explore_complete-r<N>`，从 r1 连续编号）和结构化 `findings[]`：每条 finding 含 `finding_id`、`finding_uid`（`<gate>:<evidence_id>:<finding_id>`）、`finding_type`（`blocker|scope_risk|open_question|agent_assumption|non_blocking_finding`）、`category`、`material_categories[]`、material 时的 `decision_scope_key`，以及 reviewer 原话 `summary`。分类字段的 producer 是 reviewer，主线程不得改写（P0-2）。
-- 每轮审查后主线程写 `kind:"main_review_digest"` evidence（`created_by:"main-thread"`），逐条覆盖该轮所有 findings：身份字段与 `summary` **逐字拷贝** origin finding，给出 `disposition`（`fixed|false_positive|accepted_deviation|user_decided|needs_user_decision`）、`rationale`、`route`/`route_reason` 和 per-disposition proof；`target_refs` 钉住当前 discovery blob；`source_review_evidence_refs` 引用本轮全部 role review；round>1 时 `previous_digest_refs` 串接上一轮 digest。
-- **material finding 一律走用户 checkpoint**：digest 先以 `status:"blocked"` + `needs_user_decision` 记录，然后把 finding 原文 + A/B/C/D 选项 +（每个选项对范围、非目标、验收口径、测试边界的影响面）呈现给用户。用户裁决记录为 `kind:"user_review_decision"`（`created_by:"user"`，`finding_uids` 精确到 `finding_uid`，`decision_scope_key`、`material_categories[]`、`confirmed_refs` 钉住用户看到的 blob）。D 选项必须保留 `user_text` 原文并填 `structured_decision`（scope/non_goals/acceptance_impact/test_impact + requires_artifact_update/requires_rereview 布尔值）。
-- 用户裁决导致 discovery 修改后：更新 artifact → supersede 过期的旧轮 review → 重跑 critic（round k>1 的 prompt **必须**内嵌工具渲染的 finding ledger，由 `render_finding_ledger` 生成，guard 逐字校验）→ 写新一轮 digest（终态 disposition 引用 `user_decision_refs`，artifact 修改时附 `artifact_update_refs`）。
-- material finding 的任何终态 disposition（含 `fixed`/`false_positive`）必须引用 `user_decision_refs[]`、有效 `standing_authorization_refs[]` 或 `baseline_decision_refs[]`；standing authorization 只能由用户创建、按 category 授权、永不覆盖 blocker。
-- finding history 是 append-only：旧 blocker 不会因 clean 重审而消失，必须拿到终态 disposition；同 gate 超过 3 轮仍未收敛时停止迭代，把未决 findings 整体升级给用户（`escalate_round_budget`）。
+- critic review evidence 必须携带 `review_round_id`（形如 `explore_complete-r<N>`，从 r1 连续编号）和结构化 `findings[]`：每条 finding 含 `finding_id`、`finding_uid`（`<gate>:<evidence_id>:<finding_id>`）、`finding_type`（`blocker|scope_risk|open_question|agent_assumption|non_blocking_finding`）、`category`、`material_categories[]`、关键问题的 `decision_scope_key`，以及 reviewer 原话 `summary`。分类字段由 reviewer 产生，主流程不得改写（P0-2）。
+- 每轮审查后主流程写 `kind:"main_review_digest"` evidence（`created_by:"main-thread"`），逐条覆盖该轮所有 findings：身份字段与 `summary` **逐字拷贝**原始 finding，给出 `disposition`（`fixed|false_positive|accepted_deviation|user_decided|needs_user_decision`）、`rationale`、`route`/`route_reason` 和每种处理结果的证据；`target_refs` 固定记录当前探索记录内容；`source_review_evidence_refs` 引用本轮全部 role review；round>1 时 `previous_digest_refs` 串接上一轮记录。
+- **关键 finding 一律走用户确认点**：内部先写审查问题记录 evidence（JSON kind 为 `main_review_digest`，`status:"blocked"` + `needs_user_decision`），然后把 finding 原文 + A/B/C/D 选项 +（每个选项对范围、非目标、验收标准、测试边界的影响）呈现给用户。用户确认记录 evidence 的 JSON kind 为 `user_review_decision`（`created_by:"user"`，`finding_uids` 精确到 `finding_uid`，`decision_scope_key`、`material_categories[]`、`confirmed_refs` 固定记录用户看到的 blob）。D 选项必须保留 `user_text` 原文并填 `structured_decision`（scope/non_goals/acceptance_impact/test_impact + requires_artifact_update/requires_rereview 布尔值）。
+- 用户确认导致探索记录修改后：更新 artifact → supersede 过期的旧轮 review → 重跑 critic（round k>1 的 prompt **必须**内嵌工具生成的问题清单，由 `render_finding_ledger` 生成，guard 逐字校验）→ 写新一轮 `main_review_digest`（最终处理结果引用 `user_decision_refs`，artifact 修改时附 `artifact_update_refs`）。
+- 关键 finding 的任何最终处理结果（含 `fixed`/`false_positive`）必须引用 `user_decision_refs[]`、有效 `standing_authorization_refs[]` 或 `baseline_decision_refs[]`；standing authorization 只能由用户创建、按 category 授权、永不覆盖 blocker。
+- finding history 是 append-only：旧 blocker 不会因 clean 重审而消失，必须拿到最终处理结果；同一 gate 超过 3 轮仍未处理完成时停止迭代，把未决 findings 整体升级给用户（`escalate_round_budget`）。
 - 历史 change 的旧式 critic evidence（无 `review_round_id`/`findings[]`）维持原判定口径，不被追溯 block。
 
 ## 步骤 / Steps
@@ -55,18 +73,19 @@ description: "1.探索并澄清需求，进入 SuperSpec propose 前完成 OpenS
    openspec list --json
    openspec status --change "<change>" --json   # changeRoot / artifactPaths / actionContext for grounding
    ```
-3. 保持 OpenSpec explore 立场，同时遵守 SuperSpec 输出边界：可以自由调查和澄清，但本阶段只写 SuperSpec sidecar evidence。
-4. 主线程直接调查当前实现：定位相关文件、隐藏契约、约束、风险和 source anchors。
-5. 启动 repo-local `critic` native subagent（round r1），审查歧义、遗漏场景、矛盾、scope risk 和范围收敛透明度；如存在未显式说明的关键范围收窄，critic 必须 block。critic 输出按上方披露循环要求落成带 `review_round_id` + `findings[]` 的 evidence。
-6. 写入合并后的 discovery artifact：
+3. 按 OpenSpec 的探索方式工作，同时遵守 SuperSpec 输出边界：可以自由调查和澄清，但本阶段只写 SuperSpec sidecar evidence。
+4. 主流程直接调查当前实现：定位相关文件、隐藏契约、约束、风险和 source anchors。
+5. 启动 repo-local `critic` native subagent（round r1），审查歧义、遗漏场景、矛盾、scope risk 和范围收敛透明度；如存在未显式说明的关键范围收窄，critic 必须 block。critic 输出按上方确认循环要求落成带 `review_round_id` + `findings[]` 的 evidence。
+6. 写入合并后的探索记录文件：
    ```text
    openspec/changes/<change>/.superspec/artifacts/discovery.md
    ```
 7. 在 `.superspec/evidence/discovery/` 记录 critic evidence，包含 `execution_mode:"native_subagent"`、`agent_role`、`agent_id`、`output_ref`、`source_anchors` 和 `target_refs`。
-8. 按披露循环处理 findings：写本轮 `main_review_digest`；存在 material finding 时**停下来向用户披露并等待 `user_review_decision`**，再按裁决更新 discovery / 重跑 critic / 写新一轮 digest，直到最新轮 clean 且 ledger 无未终态 finding。
-9. 运行前置门禁检查（`check-enter`），验证 explore completion：
+8. 按确认循环处理 findings：写本轮审查问题记录；存在关键问题时**停下来向用户说明并等待用户确认**，再按用户确认更新探索记录 / 重跑 critic / 写新一轮记录，直到最新轮 clean 且问题清单里没有未处理完的问题。
+9. 对探索结论、范围边界和进入 propose 的授权使用 AskUserQuestion，并等待明确选择；记录探索阶段人工确认 evidence（JSON 中为 `gate:"explore_complete"`、`kind:"human_confirmation"`、`created_by:"user"`），`confirmed_refs` 固定记录用户确认过的探索记录。
+10. 运行进入阶段前检查（`check-enter`），验证 explore completion：
    ```text
    superspec guard check-enter --change "<change>" --gate explore_complete
    ```
 
-遇到任何 guard `block` 就停止。披露相关阻塞码包括：缺少审查披露记录（`missing_review_digest`）、等待用户裁决（`needs_user_decision_pending`）、历史 finding 未收口（`finding_unresolved`）、用户裁决未绑定（`user_decision_unbound`）、缺少 finding 台账注入（`ledger_injection_missing`）、审查轮次预算耗尽（`round_budget_exhausted`）等。它们的唯一合法出路是回到披露循环或升级给用户，不允许绕过。
+遇到任何 guard `block` 就停止。用户确认相关阻塞原因包括：缺少审查问题记录（`missing_review_digest`）、等待用户确认（`needs_user_decision_pending`）、历史 finding 未处理完（`finding_unresolved`）、用户确认未绑定（`user_decision_unbound`）、缺少 finding 问题清单（`ledger_injection_missing`）、审查轮次已达上限（`round_budget_exhausted`）等。它们的唯一合法出路是回到确认循环或升级给用户，不允许绕过。

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

@@ -1,6 +1,9 @@
 ---
 name: superspec-propose
-description: "2.生成 SuperSpec propose 包，将 artifact 编写委托给 OpenSpec `openspec instructions`，并叠加 SuperSpec design review / business-invariants / test-contract / tasks gates。 / Produce the SuperSpec propose package by delegating artifact authoring to OpenSpec `openspec instructions`, with SuperSpec design review / business-invariants / test-contract / tasks gates layered on top."
+description: "2.需求已经清楚后用：把探索记录（`discovery.md`）整理成正式方案包，包括方案说明（`proposal.md`）、需求规格（`specs/**`）、设计说明（`design.md`）、任务清单（`tasks.md`）、测试契约和业务约束；这一步只定方案，不写实现。"
+metadata:
+  author: SuperSpec
+  source: SuperSpec
 ---
 
 # SuperSpec Propose
@@ -10,66 +13,81 @@ description: "2.生成 SuperSpec propose 包，将 artifact 编写委托给 Open
 - 默认使用简体中文撰写所有人类可读产物、分析、报告、说明和 OpenSpec 文档正文。
 - 保留命令、路径、JSON 字段、gate 名、task/test id、代码标识符和外部 API 名称的原文。
 - 当 OpenSpec 模板要求固定标题或字段时，保留模板结构，只将正文内容写成中文。
-- 对话窗口里的解释、披露、总结、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
+- 对话窗口里的解释、问题说明、总结、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
+- 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
+- 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
 - 向用户转述 guard / review 输出时，不要直接贴英文 `message`、`next_allowed_actions` 或英文模板标题；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
-在 explore 完成后使用本 skill，用于生成完整 OpenSpec planning package。Artifact 编写必须委托给 OpenSpec native instruction engine（`openspec instructions`）；SuperSpec 只在其外层增加 adversarial review gates、sidecar business invariants、sidecar test contract 和 tasks metadata。
+## 命令执行 / Shell
+
+- Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
+- macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
+
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 gate 必要 artifact、OpenSpec instructions 返回的必要 context、native subagent `output_ref` 的摘要/结论段，以及用户确认所需的最小原文。
+- 当前轮披露循环所需的最小结构化字段必须读取，不能只看 `output_ref` 摘要；包括 role evidence 的 `findings[]`、`finding_uid`、`decision_scope_key`、逐字 `summary`、`target_refs`，以及本轮 digest 需要引用的 evidence id。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- native subagent 的 `output_ref` 应指向简洁审查报告；原始命令输出或长日志放在 raw/report 文件中被引用，不作为默认阅读材料。
+
+在 explore 完成后使用本 skill，用于把探索记录整理成可执行的正式方案包。OpenSpec 负责生成标准方案文件，具体写法必须通过它自带的指令（`openspec instructions`）获取；SuperSpec 负责在外层增加审查门禁（gates）、业务约束（`business-invariants.md`）、测试契约（`test-contract.md`）和任务元数据。
 
 ## 边界 / Boundaries
 
-- 先桥接 repo-local OpenSpec propose skill：读取 `.codex/skills/openspec-propose/SKILL.md`，并复用其中的 artifact-order / `openspec status` / `openspec instructions` 编写协议。
-- SuperSpec 覆盖 OpenSpec propose skill 的 one-shot completion 形态：本阶段不创建或选择 change，也不能不经 SuperSpec gates 一次性完成所有 artifacts。`superspec-explore` 负责 change 创建和 discovery；本 skill 负责 gated artifact authoring。
-- OpenSpec artifacts（`proposal.md`、`specs/**/*.md`、`design.md`、`tasks.md`）**必须**通过 `openspec instructions <artifact> --json` 编写，使用其返回的 `template`/`rules`/`context`。**不要手写 OpenSpec artifacts 绕过 native engine**，否则会丢失 schema template、project context 和 validation alignment。
-- Propose 阶段拥有 SuperSpec sidecar planning artifacts：`.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`。任务依赖、读写范围、TDD 元数据和映射关系直接写入 `tasks.md` 的结构化字段，不再维护单独的 JSON 任务图文件。
-- Internal propose gates：`explore_complete`、`proposal_reviewed`（`propose.proposal_reviewed`）、`design_complete`（`propose.design_reviewed`）、`invariants_reviewed`（`propose.invariants_reviewed`）、`test_contract_drafted`（`propose.test_plan_drafted`）、`tasks_complete`（`propose.tasks_mapped`）、最终 `propose_complete`。
-- `proposal_reviewed` 是硬性 internal gate（DISC Phase 2），不是 advisory note：`proposal.md` 完成后必须运行带 `review_round_id`（`proposal_reviewed-r<N>`）和 `findings[]` 的 `critic` review，并由主线程记录 `main_review_digest`。guard 对该 gate 不提供 legacy 豁免——没有 round-tagged review + digest 一律 block。审查披露循环规则（material findings 必须经 `user_review_decision` 用户裁决、findings ledger 不可抹除、digest 链与轮次连续性）与 `superspec-explore` skill 的「审查披露循环 / Review Disclosure Loop」一节完全一致。
-- `design_complete`、`invariants_reviewed`、`test_contract_drafted` 在出现 round-tagged review evidence 后进入同一披露循环（DISC Phase 3）；旧式无 `review_round_id`/`findings[]` 的 review evidence 维持 grandfathered 口径（P2-3），但**新写的 review 必须走完整披露**。
-- `tasks_complete` 仅在新增 round-tagged role review 后才纳入披露循环（本 gate 本身不强制 role review；一旦 agent 为 tasks 写了带 findings 的 review，就必须 digest + 用户裁决闭环）。
-- proposal review 的 route 约束：若 finding 证明 discovery 本身不完整或范围（`scope`）不清，处置 route 必须是 `return_explore`（回 `superspec-explore` 补事实层），不得在 proposal 内静默补范围；仅措辞/意图不一致且不改范围时才可 `stay_same_gate_fix`。
+- 先读取项目里的 OpenSpec propose 说明：`.codex/skills/openspec-propose/SKILL.md`。方案文件的生成顺序、`openspec status` 和 `openspec instructions` 的用法以它为准。
+- SuperSpec 不采用“一次性把所有方案文件都生成完”的做法。本阶段不创建或选择 change，也不能绕过 SuperSpec 门禁检查一次性完成所有产物。`superspec-explore` 负责创建 change 和探索记录（`discovery.md`）；本 skill 负责按阶段检查来编写正式方案文件。
+- OpenSpec 标准方案文件（`proposal.md`、`specs/**/*.md`、`design.md`、`tasks.md`）**必须**通过 `openspec instructions <artifact> --json` 编写，使用其返回的 `template`/`rules`/`context`。**不要手写这些文件绕过 OpenSpec 自带指令**，否则会丢失标准模板、项目上下文和校验一致性。
+- Propose 阶段还要生成 SuperSpec 补充方案文件：`.superspec/artifacts/business-invariants.md` 和 `.superspec/artifacts/test-contract.md`。任务依赖、读写范围、TDD 元数据和映射关系直接写入 `tasks.md` 的结构化字段，不再维护单独的 JSON 任务图文件。
+- 本阶段门禁检查包括：探索完成 `explore_complete`、方案说明已审查 `proposal_reviewed`（`propose.proposal_reviewed`）、设计已审查 `design_complete`（`propose.design_reviewed`）、业务约束已审查 `invariants_reviewed`（`propose.invariants_reviewed`）、测试契约已起草 `test_contract_drafted`（`propose.test_plan_drafted`）、任务映射已完成 `tasks_complete`（`propose.tasks_mapped`），以及最终 `propose_complete`。
+- `proposal_reviewed` 是硬性 internal gate（DISC Phase 2），不是 advisory note：`proposal.md` 完成后必须运行带 `review_round_id`（`proposal_reviewed-r<N>`）和 `findings[]` 的 `critic` review，并由主流程记录审查问题记录（内部 evidence kind 为 `main_review_digest`）。guard 对该 gate 不提供 legacy 豁免——没有 round-tagged review + digest 一律 block。审查问题确认循环规则（关键 findings 必须经用户确认、findings 问题清单不可抹除、digest 链与轮次连续性）与 `superspec-explore` skill 的「审查问题确认循环 / Review Disclosure Loop」一节完全一致。
+- `design_complete`、`invariants_reviewed`、`test_contract_drafted` 在出现 round-tagged review evidence 后进入同一确认循环（DISC Phase 3）；旧式无 `review_round_id`/`findings[]` 的 review evidence 维持 grandfathered 口径（P2-3），但**新写的 review 必须走完整确认循环**。
+- `tasks_complete` 仅在新增 round-tagged role review 后才纳入确认循环（本 gate 本身不强制 role review；一旦 agent 为 tasks 写了带 findings 的 review，就必须完成 digest + 用户确认）。
+- proposal review 的 route 约束：若 finding 证明探索记录本身不完整或范围（`scope`）不清，处理 route 必须是 `return_explore`（回 `superspec-explore` 补事实层），不得在 proposal 内静默补范围；仅措辞/意图不一致且不改范围时才可 `stay_same_gate_fix`。
 - design review 的 route 约束：scope / non-goal 与上游不一致时用 `return_explore_or_proposal_reviewed`；设计边界/架构取舍用 `stay_same_gate_user_decision`。
-- invariants / test-contract review 的 route 约束：业务语义/不变量真相不确定、验收口径（`acceptance`）变更等 material finding 用 `stay_same_gate_user_decision`；若需回改 spec/design 表达，用 `return_explore_or_proposal_reviewed`。
-- tasks review 的 route 约束：task 映射 / test_refs / read-write scope 问题用 `stay_same_gate_fix`；若验收口径本身错了，用 `return_test_contract_drafted` 回 test-contract gate，不得静默改 tasks 消化 material acceptance 问题。
+- invariants / test-contract review 的 route 约束：业务语义/不变量真相不确定、验收标准（`acceptance`）变更等关键 finding 用 `stay_same_gate_user_decision`；若需回改 spec/design 表达，用 `return_explore_or_proposal_reviewed`。
+- tasks review 的 route 约束：task 映射 / test_refs / read-write scope 问题用 `stay_same_gate_fix`；若验收标准本身错了，用 `return_test_contract_drafted` 回 test-contract gate，不得静默改 tasks 来处理关键 acceptance 问题。
 - Role-gate evidence 必须来自 native subagents。v1 evidence 是 audit-only/self-reported；除非有 OpenSpec facts 支撑，不要把它描述成强制运行时事实。
 
 ## 步骤 / Steps
 
-1. 运行前置门禁检查（`check-enter`），验证 explore completion：
+1. 运行前置门禁检查（`check-enter`），确认探索阶段已经完成；该 gate 必须包含用户对探索结论和进入 propose 的明确确认，若 guard block 则停止并回到 explore 补确认：
    ```text
    superspec guard check-enter --change "<change>" --gate explore_complete
    ```
-2. 从 OpenSpec 获取 artifact build order：
+2. 从 OpenSpec 获取方案文件生成顺序：
    ```text
    openspec status --change "<change>" --json
    ```
-   按 `openspec-propose` 的说明解析 `applyRequires`、`artifacts`（status + dependencies）、`planningHome`、`changeRoot`、`artifactPaths` 和 `actionContext`。按依赖顺序编写 artifacts（proposal -> specs -> design -> tasks）。
-3. 对每个状态为 `ready` 的 OpenSpec artifact，都通过 native engine 编写：
+   按 `openspec-propose` 的说明解析 `applyRequires`、`artifacts`（status + dependencies）、`planningHome`、`changeRoot`、`artifactPaths` 和 `actionContext`。按依赖顺序编写方案文件（proposal -> specs -> design -> tasks）。
+3. 对每个状态为 `ready` 的 OpenSpec 方案文件，都通过 OpenSpec 自带指令编写：
    ```text
    openspec instructions <artifact-id> --change "<change>" --json
    ```
-   - 读取 `dependencies` artifacts 和 `.superspec/artifacts/discovery.md` 作为上下文。
+   - 读取依赖的方案文件和探索记录 `.superspec/artifacts/discovery.md` 作为上下文。
    - 使用 `template` 写入 `resolvedOutputPath`；把 `context`/`rules` 当约束使用，不要复制进产物正文。
-   - 重新运行 `openspec status --change "<change>" --json`，确认 artifact 变为 `done`，再执行对应 SuperSpec 层。
-4. `proposal.md` 编写并经 `openspec status` 确认为 `done` 后、开始 `specs/**`/`design.md` 前：执行 `proposal_reviewed` 披露循环：
-   - 启动 `critic` native-subagent review，范围限定在 proposal 的 scope / intent / non-goals / hidden assumptions；evidence 必须带 `review_round_id`（`proposal_reviewed-r<N>`）、`findings[]` 和 pinned `target_refs`（`proposal.md` + `.superspec/artifacts/discovery.md`）。
-   - 主线程记录 `main_review_digest`，给每个 finding 写处置：material findings（范围、非目标、验收口径、业务语义、设计边界）必须 `needs_user_decision` 并停下来，用 AskUserQuestion 把原文和 A/B/C/D 选项抛给用户，拿到 `user_review_decision` 后才能继续；发现 discovery 不完整时 route 用 `return_explore` 回 explore，不得自行补范围。
+   - 重新运行 `openspec status --change "<change>" --json`，确认该方案文件变为 `done`，再执行对应 SuperSpec 层。
+4. 方案说明 `proposal.md` 编写并经 `openspec status` 确认为 `done` 后、开始 `specs/**`/`design.md` 前：执行 `proposal_reviewed` 确认循环：
+   - 启动 `critic` native-subagent review，范围限定在方案范围、意图、非目标和隐藏假设；evidence 必须带 `review_round_id`（`proposal_reviewed-r<N>`）、`findings[]` 和 pinned `target_refs`（`proposal.md` + `.superspec/artifacts/discovery.md`）。
+   - 主流程记录审查问题记录，给每个 finding 写处理结果：关键 findings（范围、非目标、验收标准、业务语义、设计边界）必须进入用户确认并停下来，用 AskUserQuestion 把原文和 A/B/C/D 选项展示给用户，拿到用户确认后才能继续；发现探索记录不完整时 route 用 `return_explore` 回 explore，不得自行补范围。
    - 修订 `proposal.md` 后必须重跑 `critic`（新一轮 round），直到 clean round + digest 通过，然后验证：
    ```text
    superspec guard check-enter --change "<change>" --gate propose.proposal_reviewed
    ```
-   guard 未放行前不要开始编写 `specs/**` 或 `design.md`（两者的 artifact entry gate 都是 `proposal_reviewed`）。
-5. `design.md` 编写后：获取 `architect`、`critic`、`test-engineer` 的 native-subagent review evidence（带 `review_round_id` `design_complete-r<N>` + `findings[]` + 全量 pinned target：`proposal.md` + `design.md` + `specs/**/*.md` + discovery）。主线程记录 `main_review_digest`；material findings 必须停下来向用户披露并等待 `user_review_decision`，按裁决改 design/specs 后 supersede 旧轮并重审。对于 design option selection 和 final design confirmation，使用 AskUserQuestion 并等待明确选择；记录 human-confirmation evidence，然后验证：
+   guard 未通过前不要开始编写 `specs/**` 或 `design.md`（两者的入口门禁都是 `proposal_reviewed`）。
+5. 设计说明 `design.md` 编写后：获取 `architect`、`critic`、`test-engineer` 的 native-subagent review evidence（带 `review_round_id` `design_complete-r<N>` + `findings[]` + 全量 pinned target：`proposal.md` + `design.md` + `specs/**/*.md` + 探索记录）。主流程记录审查问题记录；关键问题必须停下来向用户说明并等待用户确认，按用户确认改 design/specs 后 supersede 旧轮并重审。对于设计选项选择和最终设计确认，使用 AskUserQuestion 并等待明确选择；记录 human-confirmation evidence，然后验证：
    ```text
    superspec guard check-enter --change "<change>" --gate propose.design_reviewed
    ```
-6. `specs/**` 和 `design.md` 编写后、`test-contract.md` 编写前：起草 `.superspec/artifacts/business-invariants.md`。每条 `INV-*` 必须有 statement、scope、source anchors、acceptance_refs、risk_refs、confidence、enforcement_level、test_refs_or_review_only_reason；记录 rejected candidates，防止把当前实现习惯误升格为业务真相。获取 `critic` + `test-engineer` review evidence（带 `review_round_id` `invariants_reviewed-r<N>` + `findings[]` + pinned target：business-invariants + design + specs glob）。主线程记录 `main_review_digest`；material 业务语义 finding 必须 `needs_user_decision` 并等待用户裁决，不得把实现习惯静默升格为 invariant 真相。然后验证：
+6. 需求规格 `specs/**` 和设计说明 `design.md` 编写后、测试契约 `test-contract.md` 编写前：起草业务约束 `.superspec/artifacts/business-invariants.md`。每条 `INV-*` 必须有 statement、scope、source anchors、acceptance_refs、risk_refs、confidence、enforcement_level、test_refs_or_review_only_reason；记录 rejected candidates，防止把当前实现习惯误升格为业务真相。获取 `critic` + `test-engineer` review evidence（带 `review_round_id` `invariants_reviewed-r<N>` + `findings[]` + pinned target：business-invariants + design + specs glob）。主流程记录审查问题记录；关键业务语义问题必须进入用户确认，不得把实现习惯静默升格为 invariant 真相。然后验证：
    ```text
    superspec guard check-enter --change "<change>" --gate propose.invariants_reviewed
    ```
-7. `business-invariants.md` 完成后、`tasks.md` 编写前：起草 `.superspec/artifacts/test-contract.md`，覆盖 specs 中每个 `#### Scenario` 和命中本 change scope 的 hard `INV-*`，包含 TEST ids、关联 INV ids、预期 RED reasons、预期 GREEN criteria 和 commands。获取 `test-engineer` + `critic` review evidence（带 `review_round_id` `test_contract_drafted-r<N>` + `findings[]` + pinned target：test-contract + invariants + design + specs glob）。主线程记录 `main_review_digest`；验收口径变更等 material finding 必须用户裁决。然后验证：
+7. 业务约束 `business-invariants.md` 完成后、任务清单 `tasks.md` 编写前：起草测试契约 `.superspec/artifacts/test-contract.md`，覆盖 specs 中每个 `#### Scenario` 和命中本 change scope 的 hard `INV-*`，包含 TEST ids、关联 INV ids、预期 RED reasons、预期 GREEN criteria 和 commands。获取 `test-engineer` + `critic` review evidence（带 `review_round_id` `test_contract_drafted-r<N>` + `findings[]` + pinned target：test-contract + invariants + design + specs glob）。主流程记录审查问题记录；验收标准变更等关键问题必须用户确认。然后验证：
    ```text
    superspec guard check-enter --change "<change>" --gate propose.test_plan_drafted
    ```
-8. 通过 `openspec instructions tasks` 编写 `tasks.md` 时：为每个 task 补充 `requirement_refs`、`invariant_refs`（必须是 business-invariants `INV-*` ids 的子集）、`test_refs`（必须是 test-contract TEST ids 的子集）、`read_scope`、`write_scope`、dependencies、TDD metadata，以及需要时的 parallel group。若 reviewer 对 task 映射提出 round-tagged findings，走 `tasks_complete-r<N>` 披露循环（pinned target：tasks + test-contract + invariants + design + specs glob）；验收口径问题 route 用 `return_test_contract_drafted`，映射问题用 `stay_same_gate_fix`。对于 tasks review confirmation，使用 AskUserQuestion 并等待明确选择；记录 human-confirmation evidence，然后验证：
+8. 通过 `openspec instructions tasks` 编写任务清单 `tasks.md` 时：为每个 task 补充 `requirement_refs`、`invariant_refs`（必须是 business-invariants `INV-*` ids 的子集）、`test_refs`（必须是 test-contract TEST ids 的子集）、`read_scope`、`write_scope`、dependencies、TDD metadata，以及需要时的 parallel group。若 reviewer 对 task 映射提出 round-tagged findings，走 `tasks_complete-r<N>` 确认循环（pinned target：tasks + test-contract + invariants + design + specs glob）；验收标准问题 route 用 `return_test_contract_drafted`，映射问题用 `stay_same_gate_fix`。对于任务审查确认，使用 AskUserQuestion 并等待明确选择；按披露循环记录用户裁决和审查问题处理结果，然后验证：
    ```text
    superspec guard check-enter --change "<change>" --gate propose.tasks_mapped
    ```