@peterxiaoyang/superspec 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
   },
   "bin": {
     "superspec": "bin/superspec.js",
-    "superspec-guard": "bin/superspec-guard.js",
+    "superspec-check": "bin/superspec-check.js",
     "superspec-hook": "bin/superspec-hook.js",
     "superspec-init": "bin/superspec-init.js"
   },
@@ -56,7 +56,7 @@
   "scripts": {
     "build": "node build.js",
     "typecheck": "tsc --noEmit",
-    "test": "node --test tests/test_install_engine.test.ts tests/test_packet_measure.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_cli.test.ts tests/test_superspec_guard_output.test.ts tests/test_superspec_guard_core.test.ts tests/test_superspec_guard_review.test.ts tests/test_superspec_guard_request_reopen.test.ts tests/test_superspec_guard_archive.test.ts tests/test_superspec_guard_packet.test.ts tests/test_superspec_guard_disclosure.test.ts tests/test_superspec_hooks.test.ts tests/test_superspec_skills.test.ts",
+    "test": "node --test tests/test_install_engine.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_cli.test.ts tests/test_superspec_guard_output.test.ts tests/test_superspec_guard_core.test.ts tests/test_superspec_guard_review.test.ts tests/test_superspec_guard_request_reopen.test.ts tests/test_superspec_guard_archive.test.ts tests/test_superspec_guard_packet.test.ts tests/test_superspec_guard_disclosure.test.ts tests/test_superspec_hooks.test.ts tests/test_superspec_i18n.test.ts tests/test_superspec_skills.test.ts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "pack:dry-run": "npm pack --dry-run"

package/templates/sidecar/discovery.md

@@ -18,6 +18,15 @@
 
 - 
 
+## 待确认问题
+
+<!-- 需要用户拍板的问题逐条列在此处：未决用 "- [ ]"，已确认用 "- [x]"。
+     explore_complete 检查在所有项变成 "- [x]"（或标注「已确认」）之前不会通过，也不会进入 propose。
+     段标题包含「确认」字样即可被识别（待确认 / 需要用户确认 等）。 -->
+
+- [ ] <待确认问题 1>
+- [ ] <待确认问题 2>
+
 ## Subagent Evidence
 
 - explore:

package/templates/sidecar/test-contract.md

@@ -13,12 +13,13 @@
 - `invariant_refs`: INV-xxx
 - `expected_red`: <实现前因何失败>
 - `expected_green`: <实现后通过的判据>
-- `test_command`: <如 mvn test -Dtest=XxxTest#method>
+- `test_command`: <framework-agnostic command that runs exactly the target test identity>
 
 ## Iron Law
 
 - 没有正在失败的测试，不准写实现代码。
 - 每个实现型 task：先有 RED evidence 才能改实现代码，先有 GREEN evidence 才能勾选。
+- 测试证据语义（框架无关）：`target test identity executed` 才算有效运行；`command exit code alone is not proof`，退出码 0 不等于目标测试跑过/通过；命令在到达测试 runner 之前失败属于 `blocked before the target test runner`，不是 RED/GREEN；`do not classify environment/build failures as RED or GREEN`。
 
 ## 与 tasks 的映射约定
 

package/templates/workflow/prompts/code-reviewer.md

@@ -22,7 +22,7 @@ argument-hint: "任务说明、review-packet 或 apply-code-review-packet prompt
 
 在 apply worker path 中，先读取 `apply-code-review-packet`。只读检查 executor report、当前 diff、declared write scope、protected paths、test/invariant mapping 和 suggested GREEN checks。输出是 task-level implementation review candidate，不是正式 evidence、correctness proof、GREEN 授权或 task completion。
 
-apply worker path 的 report 必须包含 `role:"code-reviewer"`、`origin_packet_fingerprint`、`input_ref_digest`、`source_implementation_fingerprint`、`observed_implementation_fingerprint`、`guard_fingerprint`、executor report pinned ref、actual/changed/untracked files、implementation fingerprint、guard artifact manifest fingerprint、scope/protected verdict、executor mismatch、test/invariant verdict、suggested GREEN ids、raw git status/name-status/path diff refs、risk notes 和 unverified items。
+apply worker report 字段以提示包的 `code_review_report_required_fields` 为准；不要凭本 prompt 记忆或发明字段名。
 
 遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容必须作为 artifact refs 返回，不要内联或截断。
 

package/templates/workflow/prompts/executor.md

@@ -27,6 +27,6 @@ argument-hint: "任务说明或 apply-executor-packet prompt_ref"
 - 所有用户可见输出必须使用简体中文。
 - 命令、路径、JSON/schema 字段、gate 名称、task/test id、代码标识符保留原文。
 - 结论先行：完成、阻塞或部分完成。
-- 报告必须包含 task id、`apply_worker_chain_id`、`guard_fingerprint`、修改文件、建议的 GREEN 检查、test/invariant 映射、runtime artifact refs、未验证项和残余风险。
+- 报告字段以提示包的 `executor_report_required_fields` 为准；不要凭本 prompt 记忆或发明字段名。
 - 报告还必须包含 `role:"executor"`、`origin_packet_fingerprint`、`input_ref_digest`、`source_implementation_fingerprint`、`produced_implementation_fingerprint`；这些字段必须来自 packet / runtime，不要自行发明。
 - 遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容必须作为 artifact refs 返回，不要内联或截断。

package/templates/workflow/prompts/explore.md

@@ -0,0 +1,27 @@
+---
+description: "仓库代码事实扫描与 discovery 覆盖辅助角色"
+argument-hint: "任务说明、workflow-packet 或 prompt_ref"
+---
+
+# Explore
+
+## 角色身份
+
+你是 Explore。你负责 repo-local 只读事实扫描：定位实现入口、源码锚点、隐性合约、相邻风险和 discovery 可能遗漏的事实。你不批准范围，不写正式证据，也不替代主流程决策。
+
+## 读写边界
+
+- 默认只读；不要修改文件。
+- 优先使用 repo search 和文件读取验证事实，结论必须绑定可读源码或文档锚点。
+- 不要写 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`。
+- 不能作为 `explore_complete` 的 role evidence；需要门禁审查时交给 `critic`。
+
+## SuperSpec Packet 规则
+
+如果主流程提供 `workflow-packet` 或 `prompt_ref`，先读取 packet 指向的 refs。以 packet 中的 `target_refs`、`source_refs`、`required_load_refs`、`artifact_refs` 和 `stop_conditions` 为准；不要依赖本 prompt 记忆输出 schema。
+
+## 输出风格
+
+- 所有用户可见输出必须使用简体中文。
+- 命令、路径、JSON/schema 字段、gate 名称、任务/测试 id、代码标识符保留原文。
+- 结论先行；列出最相关文件/行号、已确认事实、仍缺的来源或需要主流程确认的问题。

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

@@ -13,6 +13,7 @@ argument-hint: "任务说明或 review-packet prompt_ref"
 
 - SuperSpec review/propose lane 默认只读；不要修改方案、测试契约或实现。
 - 普通测试实现任务中，只写测试，不写业务实现；需要实现改动时向主流程说明。
+- Apply 阶段如需新增或修改 RED/characterization 测试文件，只在主流程明确交付的 bounded native lane 内写测试；正式 RED/characterization/GREEN 运行证据仍由 test-runner packet 生成。
 - 必须核对现有测试模式和目标 acceptance，不用臆测替代证据。
 
 ## SuperSpec Packet 规则

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

@@ -13,6 +13,7 @@ argument-hint: "任务说明或 apply-test-packet prompt_ref"
 
 - 默认只读；不要修改 production code、OpenSpec artifacts、`.superspec/**`、task checkbox、review artifacts 或 archive artifacts。
 - 只能执行 `apply-test-packet` 中的 `allowed_test_command`，不要发明、改写或补充命令。
+- 只有 test-runner worker 运行结果可以成为正式 RED/characterization/GREEN candidate；不要让主线程代跑或伪造正式 evidence。
 - 如果 packet 没有 `allowed_test_command`、`worker_state` 不是 `ready`、命令上下文不足或测试产生未声明副作用，停止并报告 blocker。
 - fixture/snapshot 更新只有在 packet 明确列入 `expected_worktree_side_effects` 时才可接受；否则视为不可接收风险。
 
@@ -27,7 +28,8 @@ argument-hint: "任务说明或 apply-test-packet prompt_ref"
 - 所有用户可见输出必须使用简体中文。
 - 命令、路径、JSON/schema 字段、gate 名称、task/test id、代码标识符保留原文。
 - 结论先行：测试阶段完成、阻塞或不可接收。
-- 报告必须包含 command、command source、cwd、phase、task id、test id、exit status、semantic status candidate、result summary、runtime raw transcript reference、`repo_head`、pre/post dirty-state summary、changed/untracked files、invariant refs、source refs、guard_fingerprint 和 unverified items。
+- 报告字段以提示包的 `test_runner_report_required_fields` 为准；不要凭本 prompt 记忆或发明字段名。
 - 报告还必须包含 `role:"test-runner"`、`origin_packet_fingerprint`、`input_ref_digest`、`source_implementation_fingerprint`、`observed_implementation_fingerprint`；这些字段必须来自 packet / runtime，不要自行发明。
 - RED packet 带 `expected_failure_signature` 或 `expected_failure_classifier` 时，报告和 raw transcript 必须证明匹配；无关 import/build/env/timeout 失败不能作为有效 RED。
+- 测试证据语义（框架无关）：只有 `target test identity executed` 才算有效运行；`command exit code alone is not proof`，退出码 0 不证明目标测试真正跑过/通过；命令在到达测试 runner 之前就失败属于 `blocked before the target test runner`，必须作为 blocker 报告；`do not classify environment/build failures as RED or GREEN`。
 - 遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容必须作为 artifact refs 返回，不要内联或截断。

package/templates/workflow/prompts/verifier.md

@@ -1,31 +1,31 @@
 ---
-description: "完成证据与验证角色"
-argument-hint: "任务说明、review-packet 或 apply-verify-packet prompt_ref"
+description: "完成验证角色"
+argument-hint: "review-packet 或 apply-verify-packet prompt_ref"
 ---
 
 # Verifier
 
 ## 角色身份
 
-你是 Verifier。你把完成声明转成可复现证据，或指出证明缺口。缺少证据不是通过；你提供 verification guidance，不替代主流程最终判断。
+你是 Verifier。将完成声明转成可复现证据，或指出证明缺口。缺证据不是通过；提供 verification guidance，不替代主流程最终判断。
 
 ## 读写边界
 
 - 默认只读；不要修改文件。
-- 优先核对命令输出、测试结果、diff、artifact、evidence refs 和验收标准。
+- 核对命令输出、测试结果、diff、artifact、evidence refs 和验收标准。
 - 区分行为失败、证明缺失、命令不可用和范围不清。
 
 ## SuperSpec Packet 规则
 
-在 `superspec-review` final verification lane 中，先读取主流程提供的 `review-packet` 或 `prompt_ref`。以 packet 中的 `target_refs`、`source_refs`、`required_output_kind`、`output_contract_fields`、`required_review_scope` 和 `stop_conditions` 为准；不要依赖本 prompt 记忆输出 schema。
+`superspec-review` verification lane 先读 `review-packet` 或 `prompt_ref`；以 packet refs/scope、`required_output_kind`、`output_contract_fields` 和 stop conditions 为准；不要依赖本 prompt 记忆输出 schema。
 
-必须确认 packet 的 `required_output_kind` 是 `verification_review` 后再输出 verification review。
+确认 `required_output_kind` 是 `verification_review` 后再输出 verification review。
 
-在 apply worker path 中，先读取 `apply-verify-packet`。只读检查 RED/characterization evidence、executor report、task-level code-review report、GREEN evidence、current worktree、scope/protected paths 和 freshness。输出是 post-GREEN verification candidate，不是正式 evidence、自动 completion gate 或 `task_complete.allowed` 替代。
+apply worker path 先读 `apply-verify-packet`。只读核对 executor/code-review refs、worktree、scope/protected paths 和 freshness。`completion_proof_kind:"green_tests"` 核对 RED/characterization 与 GREEN；`completion_proof_kind:"alternative_verification"` 核对 `pre_edit_proof_kind:"no_tdd_declared"`、空 pre-edit refs、`tdd_required:false`、surface/no-TDD metadata、`alternative_verification_evidence_refs` / manual refs。输出只是 candidate，不替代 `task_complete.allowed`。
 
-apply worker report 必须带 `role:"verifier"`、`origin_packet_fingerprint`、`input_ref_digest`、`source_implementation_fingerprint`、`observed_implementation_fingerprint`、`guard_fingerprint`，并覆盖 packet 要求的 verdicts、freshness、RED/GREEN refs、executor/code-review refs、dirty files、implementation/guard fingerprints、scope/protected/mismatch、raw git/diff refs、risk/stop/unverified items。
+apply worker report 字段以提示包的 `verifier_report_required_fields` 为准；不要凭本 prompt 记忆或发明字段名。alternative 分支的 `input_ref_digest` 必须覆盖 executor report、code-review report、`alternative_verification_evidence_refs` 和 active chain no-TDD metadata。
 
-遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容用 artifact refs，不内联、不截断。
+遵守 `common_worker_report_policy`：长日志、完整 diff、编译输出和大段生成内容用 artifact refs，不内联。
 
 ## 输出风格
 

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

@@ -10,7 +10,7 @@ metadata:
 
 ## 语言规则 / Language
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、gate 名、task/test id、代码标识符保留原文。
+- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
 - 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
 - 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
 - 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
@@ -22,52 +22,47 @@ metadata:
 
 ## 阶段职责
 
-Apply 按 OpenSpec tasks 执行实现，负责 RED/GREEN 证据、任务勾选和 review request-changes 后的 reopen 修复。不扩大范围，不改 proposal package 语义。
+Apply 按 OpenSpec tasks 实现，负责 RED/GREEN 证据、任务勾选和 review request-changes 后的 reopen 修复；不扩大范围，不改 proposal package 语义。
 
 ## 第一条必跑命令
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate apply_ready --format agent
+superspec check workflow-packet --change "<change>" --gate apply_ready --format agent
 ```
 
-遇到任何 guard `block` 就停止。未 allowed 前不要编辑实现。
+遇到任何返回状态为 `block` 就停止；未 allowed 前不要编辑实现。
 
 ## OpenSpec 边界
 
 - 直接使用 OpenSpec CLI surface，不读取 repo-local `openspec-*` skill 文本。
-- task list、`contextFiles`、progress 和 dynamic instruction 来自：
+- task list、`contextFiles`、progress、dynamic instruction 来自：
 
 ```text
 openspec instructions apply --change "<change>" --json
 ```
 
-不要自行发明 task list，也不要跳过 OpenSpec 返回的 context files。
+不要发明 task list，也不要跳过 OpenSpec 返回的 context files。
 
 ## Task Guard 边界
 
-实现编辑前读取 task packet：
+实现编辑前读取 `task_edit` 检查结果；勾选 task 前读取 `task_complete` 检查结果：
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate task_edit --task-id "<task-id>" --format agent
-```
-
-勾选 task 前读取 completion packet：
-
-```text
-superspec guard workflow-packet --change "<change>" --gate task_complete --task-id "<task-id>" --format agent
+superspec check workflow-packet --change "<change>" --gate task_edit --task-id "<task-id>" --format agent
+superspec check workflow-packet --change "<change>" --gate task_complete --task-id "<task-id>" --format agent
 ```
 
 `task_edit` 未 allowed 不得编辑实现；`task_complete` 未 allowed 不得把 checkbox 改成 done。
 
 ## Reopen 边界
 
-如果 review 给出 `request_changes_route:"reopen_tasks"`，先生成完整 reopen package，再检查：
+review 给出 `request_changes_route:"reopen_tasks"` 时，先生成完整 reopen package，再检查：
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate task_reopen --task-id "<task-id>" --format agent
+superspec check workflow-packet --change "<change>" --gate task_reopen --task-id "<task-id>" --format agent
 ```
 
-只有 `task_reopen` allowed 后，才允许把目标 task 从 checked 改回 unchecked 并重新 RED/GREEN。修完后写 `task_reopen_resolved`，再重新进入 review。若 route 是 `change_update`，停止 apply 并回 propose/change update。
+只有 `task_reopen` allowed 后，才允许把目标 task 从 checked 改回 unchecked 并重新 RED/GREEN。修完写 `task_reopen_resolved`，再进 review。若 route 是 `change_update`，停止 apply 并回 propose/change update。
 
 ## 用户确认边界
 
@@ -75,44 +70,74 @@ superspec guard workflow-packet --change "<change>" --gate task_reopen --task-id
 - 分支状态、dirty worktree、scope expands 或需要改变 task scope 时必须停止并确认。
 - 不要使用默认值、历史偏好或沉默作为确认。
 
-## Native Subagent 边界
+## 专用代理边界
+
+主线程只负责用检查命令生成各角色提示、分派专用代理、审核代理报告、登记证据、推进任务勾选。专用代理来自 `.codex/agents/*.toml` 与 `.codex/prompts/*.md`，不能由主线程自审替代。代理报告只是候选材料，通过检查的才是正式证据。当前 CLI 没有登记证据的命令；代理报告返回后，由主线程按检查命令的 output contract 字段手动写入 `.superspec/evidence/` 对应目录。
+
+RED/characterization/GREEN 测试必须由 `.codex/agents/test-runner.toml` + `.codex/prompts/test-runner.md` 执行；主线程不得代跑或伪造 formal `test_run` evidence。新增或修改测试文件时用 `test-engineer` 专用代理。
+
+```text
+superspec check apply-test-packet --change "<change>" --task-id "<task-id>" --test-id "<test-id>" --phase red --format prompt
+```
+
+用 test-runner 执行检查命令指定的测试命令；主线程审核报告/原始日志并登记为证据后，才写正式 `test_run` 证据。
+
+测试证据语义（框架无关，审核 worker report 时用）：只有 `target test identity executed` 才算有效运行；`command exit code alone is not proof`，退出码 0 不证明目标测试真正跑过/通过；命令在到达测试 runner 之前失败属于 `blocked before the target test runner`，不算 RED/GREEN；`do not classify environment/build failures as RED or GREEN`。
 
-Apply 主流程负责 evidence、审核接收、task checkbox 和 `task_complete`；worker report 只是 candidate。repo-local native agents 必须来自 `.codex/agents/*.toml` 与 `.codex/prompts/*.md`，不能由主线程自审替代。
+`apply_execution_surface`：缺省有 `write_scope` 为 `implementation`，无 `write_scope` 为 `no_code`；显式允许 `implementation`、`runtime_config`、`docs_generated`、`no_code`。`implementation` / `runtime_config` 必须走 executor-worker chain；`tdd_required:false` 也只能用 closed `apply_worker_chain` 的 `completion_proof_kind:"alternative_verification"` 完成。`docs_generated` / `no_code` 可用 direct alternative/manual verification。
 
-可选 RED/characterization 测试 worker：
+编码实现必须由 `.codex/agents/executor.toml` + `.codex/prompts/executor.md` 执行，并通过 active -> closed `apply_worker_chain` 收敛；主线程不得直接改实现代码来完成 task。
 
 ```text
-superspec guard apply-test-packet --change "<change>" --task-id "<task-id>" --test-id "<test-id>" --phase red --format prompt
+superspec check apply-executor-packet --change "<change>" --task-id "<task-id>" --apply-worker-chain-ref "<active-chain-ref>" --format prompt
 ```
 
-使用 `.codex/agents/test-runner.toml` / `.codex/prompts/test-runner.md` 执行 packet 指定命令。主线程审查 test-runner report 和 raw transcript，materialize 为 pinned refs 后，才写正式 `test_run` evidence。
+使用 `.codex/agents/executor.toml` / `.codex/prompts/executor.md`。先把检查命令给出的激活模板登记为工作链证据；缺激活标记不能启动 executor。TDD 与 no-TDD 的激活标记不同（具体字段以检查命令输出为准）。executor 只能改检查命令声明的实现写范围（implementation/runtime_config write scope），不能写正式 evidence，不能改 task checkbox，不能做 review/verification。
 
-可选 executor-worker chain：
+executor 返回后把报告登记为证据，再生成任务级审查：
 
 ```text
-superspec guard apply-executor-packet --change "<change>" --task-id "<task-id>" --apply-worker-chain-ref "<active-chain-ref>" --format prompt
+superspec check apply-code-review-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --format prompt
 ```
 
-使用 `.codex/agents/executor.toml` / `.codex/prompts/executor.md`。先记录 packet 的 `chain_activation_template` 为 active `apply_worker_chain` evidence；缺 active marker 不得 spawn executor。executor 只能改 packet 声明的 implementation write scope，不能写正式 evidence、不能改 task checkbox、不能做 review/verification。
+用 `.codex/agents/code-reviewer.toml` 检查 scope/protected paths、executor report 与 diff、test/invariant mapping 和 suggested GREEN checks。
 
-executor 返回后先 materialize executor report pinned ref，再生成 task-level review：
+code-review 通过后，GREEN 只走同一 executor-worker chain：
 
 ```text
-superspec guard apply-code-review-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --format prompt
+superspec check apply-test-packet --change "<change>" --task-id "<task-id>" --test-id "<test-id>" --phase green --task-code-review-report-ref "<ref>" --format prompt
 ```
 
-用 `.codex/agents/code-reviewer.toml` 检查明显缺陷、scope/protected paths、executor report 与 diff 一致性、test/invariant mapping 和 suggested GREEN checks。code-reviewer report 不是 correctness proof。
+GREEN report 审核并登记为 evidence 后，生成 GREEN verification：
 
-code-review 审核通过后，GREEN 只走同一 executor-worker chain：
+```text
+superspec check apply-verify-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --task-code-review-report-ref "<ref>" --green-test-run-evidence-ref "<ref>" --red-test-run-evidence-ref "<ref>" --format prompt
+```
+
+no-TDD implementation/runtime_config 先登记 live/pass `alternative_verification` 或 `manual_verification`，再生成 alternative verification：
 
 ```text
-superspec guard apply-test-packet --change "<change>" --task-id "<task-id>" --test-id "<test-id>" --phase green --task-code-review-report-ref "<ref>" --format prompt
+superspec check apply-verify-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --task-code-review-report-ref "<ref>" --alternative-verification-evidence-ref "<ref>" --format prompt
 ```
 
-GREEN report 经主线程审核通过并登记为正式 evidence 后，生成 post-GREEN verification：
+用 `.codex/agents/verifier.toml` 检查完成方式分支：GREEN 绑定 RED/characterization、GREEN 和当前工作区；alternative 绑定 no-TDD 激活标记、实际替代/人工验证引用、surface/no-TDD 元数据和当前工作区。审核 verifier 报告后写关闭的工作链证据，再跑 `task_complete`。异常终止只取消旧工作链，不授权完成。
+
+## 完成检查
+
+每个 task 的证据链（RED/characterization → executor → code-review → GREEN 或替代验证 → verifier）齐全后，运行任务完成检查：
+
+```text
+superspec check workflow-packet --change "<change>" --gate task_complete --task-id "<task-id>" --format agent
+```
+
+只有检查结果显示通过后，才把该 task 的 checkbox 改为 done。所有 task 完成后进入 `superspec-review`。
+
+## 异常恢复
+
+状态文件损坏时重建：
 
 ```text
-superspec guard apply-verify-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --task-code-review-report-ref "<ref>" --green-test-run-evidence-ref "<ref>" --red-test-run-evidence-ref "<ref>" --format prompt
+superspec check recompute --change "<change>" --rebuild-corrupt
 ```
 
-用 `.codex/agents/verifier.toml` 检查 RED/characterization -> executor -> code-review -> GREEN -> current worktree 的证据链和 freshness。verifier report 经主线程审核通过后写 closed `apply_worker_chain` evidence，再运行 `task_complete`。中途转串行 fallback 前，先写 abandoned `apply_worker_chain` evidence，并保留恢复或 serial takeover baseline proof。
+状态指纹过期时，重跑对应检查命令即可（检查命令会自动重算并刷新指纹）；不要手写状态文件。

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

@@ -10,7 +10,7 @@ metadata:
 
 ## 语言规则 / Language
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、gate 名、task/test id、代码标识符保留原文。
+- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
 - 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
 - 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
 - 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
@@ -27,10 +27,10 @@ Archive 在 `review_complete` allowed 后收尾：确认 archive readiness、保
 ## 第一条必跑命令
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate archive_ready --format agent
+superspec check workflow-packet --change "<change>" --gate archive_ready --format agent
 ```
 
-遇到任何 guard `block` 就停止，不归档。
+遇到 `block` 就停止，不归档。
 
 ## OpenSpec 边界
 
@@ -47,7 +47,7 @@ superspec guard workflow-packet --change "<change>" --gate archive_ready --forma
 确认后运行会写 preservation manifest 的 readiness check：
 
 ```text
-superspec guard check-archive-ready --change "<change>" --format agent
+superspec check check-archive-ready --change "<change>" --format agent
 ```
 
 然后运行 OpenSpec archive：
@@ -59,7 +59,7 @@ openspec archive -y "<change>"
 最后验证 archived sidecar preservation：
 
 ```text
-superspec guard check-archived --change "<change>" --format agent
+superspec check check-archived --change "<change>" --format agent
 ```
 
 `.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`、review/verification evidence、RED/GREEN evidence 和 archive evidence 必须能从 preservation manifest 追溯。

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

@@ -10,7 +10,7 @@ metadata:
 
 ## 语言规则 / Language
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、gate 名、task/test id、代码标识符保留原文。
+- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
 - 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
 - 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
 - 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
@@ -24,22 +24,38 @@ metadata:
 
 Explore 只做需求澄清、代码事实调查、范围边界和风险记录。产物是 `openspec/changes/<change>/.superspec/artifacts/discovery.md`；不写 `proposal.md`、`specs/**`、`design.md`、`tasks.md`，也不改实现代码。
 
+## 产物格式
+
+- discovery.md 必须按 SuperSpec discovery 模板的结构填写，保留全部段落：`调查范围` / `现有实现事实` / `隐性合约` / `风险与歧义` / `待确认问题` / `Subagent Evidence`；不得自创或删减段落骨架。
+- 第一条必跑命令 `superspec check workflow-packet --change "<change>" --gate explore_complete --format agent` 的返回里带 `discovery_template` 与 `discovery_rules`：按其中的模板骨架和填写规则产出，而不是自由发挥，这样无论哪个模型产物结构都一致。
+
 ## 第一条必跑命令
 
 ```text
 superspec init --scope project --format agent
 ```
 
-随后创建或打开 OpenSpec change，并读取当前上下文：
+随后用 `openspec list --json` 查找匹配 change；若已有则复用，若没有则直接创建，不要先跑 `openspec --help` / `openspec change --help` / `openspec new --help` 探测语法（命令失败或版本报错时才查 help 诊断）。
 
 ```text
 openspec list --json
+```
+
+仅当 `openspec list --json` 没有匹配 change 时运行：
+
+```text
+openspec new change "<change>" --description "<用户需求摘要>"
+```
+
+然后读取当前上下文：
+
+```text
 openspec status --change "<change>" --json
-superspec guard check-init --change "<change>" --format agent
-superspec guard workflow-packet --change "<change>" --gate explore_complete --format agent
+superspec check check-init --change "<change>" --format agent
+superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
 ```
 
-遇到任何 guard `block` 就停止，按 packet 的 `next_action` 处理；不要绕过 guard。
+遇到 `block` 就停止，按检查结果的下一步提示处理；不要绕过检查。
 
 ## OpenSpec 边界
 
@@ -47,33 +63,35 @@ superspec guard workflow-packet --change "<change>" --gate explore_complete --fo
 - 用 `openspec list --json` 和 `openspec status --change "<change>" --json` 确认 change 结构、artifactPaths 和当前状态。
 - OpenSpec 负责 change 结构和后续 artifact 语义；本阶段只补 SuperSpec discovery 证据。
 - 如果发现需要正式方案、规格、设计或任务，先写入 discovery，再交给 `superspec-propose`。
+- 代码事实扫描可由主线程直接完成；若并行创建只读子代理，使用 repo-local `.codex/agents/explore.toml`。该角色只辅助 discovery 覆盖，不能替代 `critic` 审查证据。
 
-## Native Subagent 边界
+## 专用代理边界
 
-需求 critique 必须来自 repo-local `critic` native subagent。生成 prompt 时使用 packet，而不是把 disclosure 协议常驻在 skill 正文：
+需求审查由本仓库的 `critic` 专用代理完成。生成审查提示时使用检查命令的输出，而不是把披露协议常驻在 skill 正文：
 
 ```text
-superspec guard review-packet --change "<change>" --gate explore_complete --role critic --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate explore_complete --role critic --round 1 --format prompt
 ```
 
-主流程整理审查问题时读取 main-thread packet：
+主流程整理审查问题时读取主线程提示信息：
 
 ```text
-superspec guard review-packet --change "<change>" --gate explore_complete --role main-thread --round 1 --format agent
+superspec check review-packet --change "<change>" --gate explore_complete --role main-thread --round 1 --format agent
 ```
 
-round > 1 的 reviewer prompt 必须使用 packet/ledger 注入；不要手写历史问题清单。
+第二轮及以后的审查，必须由检查命令把上一轮的问题注入提示；不要手写历史问题清单。
 
 ## 用户确认边界
 
 - 关键范围、非目标、验收标准、业务语义或设计边界问题必须面向用户说明并等待明确确认。
 - 探索结论、范围边界和进入 propose 的授权必须等待用户确认后再记录 evidence。
+- discovery.md 必须含 `## 待确认问题` 段（标题含「确认」字样即可，如「待确认问题」「需要用户确认的问题」）。每条问题用 `- [ ]`（未决）或 `- [x]`（已确认）标记；也可在已确认项写「已确认：」。**该段只要还有 `- [ ]` 或「仍需确认/待确认」项，`explore_complete` 检查就不会通过**，不得记录人工确认，也不得进入 propose。
 - 用户看到的文字要用中文业务语言；内部 JSON 名只写进证据、命令输出或诊断片段。
 
 ## 完成检查
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate explore_complete --format agent
+superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
 ```
 
-只有 packet 显示 allowed 后，才进入 `superspec-propose`。
+只有检查结果显示通过后，才进入 `superspec-propose`。

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

@@ -10,7 +10,7 @@ metadata:
 
 ## 语言规则 / Language
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、gate 名、task/test id、代码标识符保留原文。
+- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
 - 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
 - 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
 - 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
@@ -27,10 +27,10 @@ Propose 把 discovery 转成 OpenSpec proposal package，并补 SuperSpec 业务
 ## 第一条必跑命令
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate explore_complete --format agent
+superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
 ```
 
-遇到任何 guard `block` 就停止，回 explore 补事实或确认。
+遇到 `block` 就停止，回 explore 阶段补事实或确认。
 
 ## OpenSpec 边界
 
@@ -42,39 +42,50 @@ superspec guard workflow-packet --change "<change>" --gate explore_complete --fo
 openspec instructions <artifact-id> --change "<change>" --json
 ```
 
+## 执行步骤
+
+把 discovery 整理成 OpenSpec proposal package，每个正本 artifact 都通过 OpenSpec 产出引擎生成：
+
+1. 运行 `openspec status --change "<change>" --json`，取 artifact 顺序、状态和 `resolvedOutputPath`。
+2. 每个 artifact（proposal/specs/design/tasks）运行 `openspec instructions <artifact-id> --change "<change>" --json`，取回 template/rules/context/instruction/dependencies。
+3. 先读 dependencies 列出的已完成 artifact，再按 template 写到 `resolvedOutputPath`；context/rules 是对作者的约束，不写进产出文件。
+4. sidecar（`.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`）用 SuperSpec 内置模板，写到 change 内 `.superspec/artifacts/`。
+
 ## Packet 驱动的阶段门
 
-按 artifact 依赖顺序工作，每个门都先读 packet，allowed 后才进入下一段：
+按 artifact 依赖顺序工作，每个门都先读检查结果，通过后才进入下一段：
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate proposal_reviewed --format agent
-superspec guard workflow-packet --change "<change>" --gate design_complete --format agent
-superspec guard workflow-packet --change "<change>" --gate invariants_reviewed --format agent
-superspec guard workflow-packet --change "<change>" --gate test_contract_drafted --format agent
-superspec guard workflow-packet --change "<change>" --gate tasks_complete --format agent
-superspec guard workflow-packet --change "<change>" --gate apply_ready --format agent
+superspec check workflow-packet --change "<change>" --gate proposal_reviewed --format agent
+superspec check workflow-packet --change "<change>" --gate design_complete --format agent
+superspec check workflow-packet --change "<change>" --gate invariants_reviewed --format agent
+superspec check workflow-packet --change "<change>" --gate test_contract_drafted --format agent
+superspec check workflow-packet --change "<change>" --gate test_contract_honored --format agent
+superspec check workflow-packet --change "<change>" --gate tasks_complete --format agent
+superspec check workflow-packet --change "<change>" --gate propose_complete --format agent
+superspec check workflow-packet --change "<change>" --gate apply_ready --format agent
 ```
 
-`proposal_reviewed` 不是 advisory note；它是硬门。`propose.proposal_reviewed`、`propose.design_reviewed`、`propose.invariants_reviewed`、`propose.test_plan_drafted`、`propose.tasks_mapped` 是兼容别名，packet 输出中的规范 gate 名为准。
+`proposal_reviewed` 不是 advisory note；它是硬门。`propose.proposal_reviewed`、`propose.design_reviewed`、`propose.invariants_reviewed`、`propose.test_plan_drafted`、`propose.tasks_mapped` 是兼容别名，检查结果输出中的规范阶段门名为准。
 
-## Native Subagent 边界
+## 专用代理边界
 
 - proposal review 使用 repo-local `critic`。
 - design review 使用 repo-local `architect`、`critic`、`test-engineer`。
 - business-invariants 和 test-contract review 使用 repo-local `critic` / `test-engineer`。
 - reviewer prompt 一律由 `review-packet --format prompt` 生成；主线程 digest 输入一律由 `review-packet --role main-thread --format agent` 读取。
-- round > 1 必须使用 packet/ledger 注入，不手写历史 finding 清单。
+- 第二轮及以后的审查，必须由检查命令把上一轮的问题注入提示，不手写历史 finding 清单。
 
 ## 用户确认边界
 
-关键范围、非目标、验收标准、业务语义和设计边界问题必须停止并交给用户确认。主线程不能静默关闭这类 finding；需要回 explore 或回上游 artifact 时，按 packet 和 guard 给出的 route 处理。
+关键范围、非目标、验收标准、业务语义和设计边界问题必须停止并交给用户确认。主线程不能静默关闭这类 finding；需要回 explore 或回上游 artifact 时，按检查结果和阶段检查给出的回退路径处理。
 
 设计选项选择、任务审查确认，以及任何会改变范围或验收标准的处理，都必须等待明确用户确认。
 
 ## 完成检查
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate apply_ready --format agent
+superspec check workflow-packet --change "<change>" --gate apply_ready --format agent
 ```
 
 只有 apply-ready allowed 后，才进入 `superspec-apply`。