@peterxiaoyang/superspec 0.1.10 → 0.1.12

package/dist/src/tasks.js

@@ -243,6 +243,68 @@ export function task_test_refs(tasks) {
     }
     return refs;
 }
+export const APPLY_EXECUTION_SURFACES = new Set(["implementation", "runtime_config", "docs_generated", "no_code"]);
+function cleanWriteScope(scope) {
+    return scope.trim().replace(/\\/g, "/");
+}
+function unsafeWriteScope(scope) {
+    const parts = scope.split("/");
+    return scope === "" || scope === "." || scope.startsWith("/") || parts.some((part) => part === "" || part === "." || part === "..");
+}
+function rootMarkdown(scope) {
+    return !scope.includes("/") && /\.(?:md|mdx|rst|adoc)$/iu.test(scope);
+}
+function rootReadmeOrChangelog(scope) {
+    if (scope.includes("/"))
+        return false;
+    return /^(?:README|CHANGELOG)(?:\.(?:md|mdx|rst|adoc))?$/iu.test(scope);
+}
+function docsGeneratedScopeAllowed(scope) {
+    if (unsafeWriteScope(scope))
+        return false;
+    if (scope.startsWith("docs/") || scope.startsWith("doc/"))
+        return true;
+    if (rootMarkdown(scope) || rootReadmeOrChangelog(scope))
+        return true;
+    return scope.startsWith("templates/") && scope.endsWith(".md");
+}
+export function docs_generated_write_scope_reasons(writeScope, taskId = "") {
+    const invalid = writeScope
+        .map(cleanWriteScope)
+        .filter((scope) => !docsGeneratedScopeAllowed(scope))
+        .sort();
+    if (invalid.length === 0)
+        return [];
+    const prefix = taskId ? `task ${taskId} ` : "";
+    return [reason("invalid_docs_generated_write_scope", `${prefix}apply_execution_surface=docs_generated only allows docs/**, doc/**, root README/CHANGELOG/markdown, and templates/**/*.md write_scope entries: ${renderList(invalid)}`, invalid)];
+}
+export function task_apply_execution_surface(task) {
+    const explicit = task.attrs.apply_execution_surface?.trim();
+    if (explicit)
+        return explicit;
+    return splitList(task.attrs.write_scope ?? "").length > 0 ? "implementation" : "no_code";
+}
+export function task_apply_execution_surface_reasons(taskId, task) {
+    const surface = task_apply_execution_surface(task);
+    const writeScope = splitList(task.attrs.write_scope ?? "");
+    if (!APPLY_EXECUTION_SURFACES.has(surface)) {
+        return [reason("invalid_apply_execution_surface", `task ${taskId}: apply_execution_surface=${surface}`)];
+    }
+    if (surface === "implementation" || surface === "runtime_config") {
+        return writeScope.length === 0
+            ? [reason("missing_write_scope", `task ${taskId} apply_execution_surface=${surface} requires non-empty write_scope`)]
+            : [];
+    }
+    if (surface === "no_code") {
+        return writeScope.length === 0
+            ? []
+            : [reason("invalid_apply_execution_surface_write_scope", `task ${taskId} apply_execution_surface=no_code requires empty write_scope`, writeScope)];
+    }
+    if (writeScope.length === 0) {
+        return [reason("missing_write_scope", `task ${taskId} apply_execution_surface=docs_generated requires non-empty write_scope`)];
+    }
+    return docs_generated_write_scope_reasons(writeScope, taskId);
+}
 export function write_scope_conflict_reasons(tasks) {
     const byGroup = {};
     for (const [taskId, task] of Object.entries(tasks)) {

package/dist/src/util.d.ts

@@ -53,6 +53,10 @@ export declare const ALLOWED_CONFIG_KEYS: Set<string>;
 export declare const EVIDENCE_STATUSES: Set<string>;
 export declare const EVIDENCE_KINDS: Set<string>;
 export declare const HUMAN_CONFIRMATION_GATES: Set<string>;
+export declare const PENDING_CONFIRMATION_RE: RegExp;
+export declare const UNCHECKED_CHECKBOX_RE: RegExp;
+export declare const CHECKED_CHECKBOX_RE: RegExp;
+export declare function confirmation_text_has_pending_wording(text: string): boolean;
 export declare const NO_TDD_REASONS: Set<string>;
 export declare const TDD_MODES: Set<string>;
 export declare const ROLE_EVIDENCE_FIELDS: readonly ["agent_role", "agent_id", "prompt_ref", "output_ref", "source_anchors", "target_refs"];

package/dist/src/util.js

@@ -87,8 +87,21 @@ export const HUMAN_CONFIRMATION_GATES = new Set([
     "branch_handling",
     "apply_isolation",
     "scope_expansion",
+    "serial_takeover",
     "verify_failure_handling",
 ]);
+// Pending-confirmation wording shared by two defenses so they cannot drift:
+//  - the explore_complete open-questions gate (B1) counts list items inside discovery.md's
+//    "待确认问题" section that carry this wording;
+//  - the human_confirmation self-pending guard (B3) rejects confirmation_text that carries it.
+// Worded to confirmation semantics only: "仍需/还需要 + 评估/细化" (legitimate follow-up prose,
+// not an unresolved confirmation) is intentionally excluded because it does not end in 确认.
+export const PENDING_CONFIRMATION_RE = /仍需确认|待确认|尚未确认|未确认完|还需要[^，。；\n]{0,20}确认/u;
+export const UNCHECKED_CHECKBOX_RE = /\[ \]/u;
+export const CHECKED_CHECKBOX_RE = /\[[xX]\]/u;
+export function confirmation_text_has_pending_wording(text) {
+    return PENDING_CONFIRMATION_RE.test(text);
+}
 export const NO_TDD_REASONS = new Set([
     "documentation-only",
     "configuration-only",

package/dist/superspec.js

@@ -25,14 +25,14 @@ function help() {
         "  init        install SuperSpec Codex surfaces (asks project/user; default project)",
         "  update      update SuperSpec CLI, then update manifest-managed surfaces",
         "  uninstall   remove manifest-managed SuperSpec surfaces",
-        "  guard       run the SuperSpec guard command surface",
+        "  check       run the SuperSpec check command surface",
         "  doctor      diagnose SuperSpec/OpenSpec/npm/PATH wiring",
         "  version     print SuperSpec CLI version",
         "",
         "examples:",
         "  superspec init --scope project",
         "  superspec init --scope user",
-        "  superspec guard check-init --change <change> --format agent",
+        "  superspec check check-init --change <change> --format agent",
         "  superspec doctor",
         "",
     ].join("\n");
@@ -80,11 +80,11 @@ export async function main_superspec(argv = process.argv.slice(2)) {
     }
     if (command === "uninstall")
         return main_init_async([...rest, "--uninstall"]);
-    if (command === "guard")
+    if (command === "check" || command === "guard")
         return main(rest);
     if (command === "doctor")
         return main_doctor(rest);
-    // Convenience fallback: `superspec check-init ...` behaves like `superspec guard check-init ...`.
+    // Convenience fallback: `superspec check-init ...` behaves like `superspec check check-init ...`.
     if (command.startsWith("check-") || command === "status" || command === "recompute" || command === "init") {
         return main(argv);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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/hooks/codex-hooks.json

@@ -5,32 +5,6 @@
     "strict_profile_default": "audit-only-until-r1-provenance-passes"
   },
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash|apply_patch|Edit|Write|mcp__.*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 120,
-            "statusMessage": "SuperSpec 写入策略检查"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 120,
-            "statusMessage": "SuperSpec 运行证据记录"
-          }
-        ]
-      }
-    ],
     "SubagentStart": [
       {
         "matcher": ".*",

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/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,59 +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 语义。
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-apply --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```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。
 
 ## 用户确认边界
 
@@ -82,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` 只用于诊断，不作为默认上下文。
@@ -26,18 +26,11 @@ Archive 在 `review_complete` allowed 后收尾：确认 archive readiness、保
 
 ## 第一条必跑命令
 
-先尝试建立当前 change 的 SuperSpec hook session。R-1/provenance 未通过时该命令只会记录 audit-only lease 和降级诊断，不代表 mechanical enforcement 已启用：
-
-```text
-superspec guard hook-session-begin --change "<change>" --workflow superspec-archive --entrypoint-token "<fresh-entrypoint-token>" --format agent
-superspec guard hook-session-status --change "<change>" --format agent
-```
-
 ```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 边界
 
@@ -54,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：
@@ -66,8 +59,7 @@ openspec archive -y "<change>"
 最后验证 archived sidecar preservation：
 
 ```text
-superspec guard check-archived --change "<change>" --format agent
-superspec guard hook-session-end --change "<change>" --reason archived --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 追溯。