@peterxiaoyang/superspec 0.1.10 → 0.1.12

package/dist/src/gates.js

@@ -1,16 +1,16 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, isObject, reason, renderList, repr, pinned_ref_key, safe_within, sha256_text, runtime, toPosix, } from "./util.js";
-import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate, openspec_cli_probe } from "./openspec.js";
+import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, isObject, reason, renderList, repr, pinned_ref_key, safe_within, sha256_text, runtime, toPosix, PENDING_CONFIRMATION_RE, UNCHECKED_CHECKBOX_RE, CHECKED_CHECKBOX_RE, } from "./util.js";
+import { all_done, artifact_status_map, effective_superseded_ids, get_repo_root, is_done, normalize_gate, openspec_cli_probe } from "./openspec.js";
 import { read_agent_toml_name, read_skill_frontmatter_name, sidecar_business_invariants_path, sidecar_discovery_path, sidecar_test_contract_path } from "./paths.js";
 import { hookInitReasons } from "./hooks/health.js";
 import { business_invariant_ids, business_invariant_validation_reasons, automated_hard_business_invariant_ids, evidence_invariant_refs, evidence_invariant_ref_reasons, evidence_test_contract_invariant_reasons, human_confirmation_business_invariant_ids, invariant_matrix_coverage_reasons, post_implementation_business_invariant_ids, red_green_invariant_ids, test_contract_invariant_ids, } from "./invariants.js";
-import { evidence_test_id_reasons, declared_test_evidence_reasons, parse_spec_scenarios, parse_tasks, parse_test_contract_ids, parse_test_contract_records, red_green_test_ids, splitList, tasks_structure_hash, task_alternative_verification, task_test_evidence, task_test_refs, test_contract_covers_scenario, test_contract_invariant_refs_by_test, write_scope_conflict_reasons, } from "./tasks.js";
+import { evidence_test_id_reasons, declared_test_evidence_reasons, parse_spec_scenarios, parse_tasks, parse_test_contract_ids, parse_test_contract_records, red_green_test_ids, splitList, task_apply_execution_surface, task_apply_execution_surface_reasons, tasks_structure_hash, task_alternative_verification, task_test_evidence, task_test_refs, test_contract_covers_scenario, test_contract_invariant_refs_by_test, write_scope_conflict_reasons, } from "./tasks.js";
 import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, live_user_confirmations, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
 import { review_disclosure_reasons } from "./disclosure.js";
 import { archive_manifest_path } from "./archive.js";
-import { fingerprint_matches, } from "./apply_worker_chain.js";
-import { apply_worker_chain_lifecycle_reasons as shared_apply_worker_chain_lifecycle_reasons, apply_worker_chain_lifecycle_state, serial_completion_green, } from "./apply_worker_chain_lifecycle.js";
+import { pre_edit_worker_test_run_reasons, } from "./apply_worker_chain.js";
+import { apply_worker_chain_lifecycle_reasons as shared_apply_worker_chain_lifecycle_reasons, apply_worker_chain_lifecycle_state, } from "./apply_worker_chain_lifecycle.js";
 function action_list(...items) {
     return [...new Set(items.filter((item) => typeof item === "string" && item.length > 0))];
 }
@@ -398,8 +398,15 @@ export function openspec_cli_capability_reasons() {
     return [reason("openspec_native_surface_missing", probe.message)];
 }
 export function evidence_schema_guard(change, changeRoot, repoRoot, evidences) {
+    const effectiveDead = effective_superseded_ids(evidences);
     return [
-        ...evidences.flatMap((ev) => validate_evidence_schema(ev, change, changeRoot, repoRoot)),
+        ...evidences.flatMap((ev) => {
+            const problems = validate_evidence_schema(ev, change, changeRoot, repoRoot);
+            const id = typeof ev.evidence_id === "string" ? ev.evidence_id : "";
+            if (!id || !effectiveDead.has(id) || !ev.agent_role)
+                return problems;
+            return problems.filter((item) => item.code !== "stale_review");
+        }),
         ...duplicate_evidence_id_reasons(evidences),
         ...dangling_evidence_ref_reasons(evidences),
         ...supersede_reasons(evidences),
@@ -450,6 +457,54 @@ function stale_artifact_review_reasons(reviews, changeRoot, artifactRel, code, g
     }
     return reasons;
 }
+// B1: count unresolved open questions inside discovery.md's "待确认问题" section before explore_complete
+// can pass. The section is located by a heading whose text carries confirmation semantics
+// (待确认 / 需要用户确认 / open question / pending confirmation), tolerating inserted words such as
+// 「用户」between 需要 and 确认 (the real secondment-hour-unit-support incident title was
+// 「## 需要用户确认的问题」, which a naive contiguous 「需要确认」 substring would miss).
+//
+// Within a matched section, a list item ("- " / "* " / "+ " / "1. ") counts as open if it carries an
+// unchecked checkbox ("[ ]", literal half-width space — full-width U+3000 is not treated as a box,
+// matching GitHub task-list semantics) OR pending-confirmation wording (PENDING_CONFIRMATION_RE,
+// shared with the B3 confirmation guard). An item is closed (not counted) if it begins with 「已确认」
+// after its list marker or carries a checked box "[x]". Plain prose bullets with neither signal are
+// ignored. When the section is absent the count is 0 (grandfathered: legacy changes with no such
+// section are not retroactively blocked, matching this repo's treatment of legacy evidence).
+const OPEN_QUESTION_SECTION_RE = /(待|需要|需)[^\n]{0,6}确认|待澄清|开放问题|open question|pending confirmation/iu;
+const OPEN_QUESTION_LIST_ITEM_RE = /^\s*(?:[-*+]|\d+\.)\s+(.*)$/u;
+function classify_open_question_line(line) {
+    const m = line.match(OPEN_QUESTION_LIST_ITEM_RE);
+    if (!m)
+        return "none";
+    const body = m[1].trimStart();
+    if (CHECKED_CHECKBOX_RE.test(line))
+        return "closed";
+    if (UNCHECKED_CHECKBOX_RE.test(line))
+        return "open";
+    if (/^已确认/u.test(body))
+        return "closed";
+    if (PENDING_CONFIRMATION_RE.test(line))
+        return "open";
+    return "none";
+}
+export function discovery_open_question_count(discoveryPath) {
+    if (!existsSync(discoveryPath) || !statSync(discoveryPath).isFile())
+        return 0;
+    const text = readFileSync(discoveryPath, "utf8");
+    if (!text.trim())
+        return 0;
+    let inSection = false;
+    let count = 0;
+    for (const line of text.split(/\r?\n/u)) {
+        if (/^#{1,6}\s/u.test(line)) {
+            inSection = OPEN_QUESTION_SECTION_RE.test(line);
+            continue;
+        }
+        if (inSection && classify_open_question_line(line) === "open")
+            count += 1;
+    }
+    return count;
+}
 export function check_superspec_gate(change, status, changeRoot, evidences, gateRaw) {
     const gate = normalize_gate(gateRaw);
     const amap = artifact_status_map(status);
@@ -470,6 +525,13 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
         // DISC Phase 1: material findings raised by explore reviews must be disclosed to the user
         // (main_review_digest + user_review_decision) before the gate can pass.
         reasons.push(...review_disclosure_reasons("explore_complete", changeRoot, evidences));
+        // B1: discovery.md must not still carry unresolved open questions. Without this the gate is a
+        // presence-check on human_confirmation and will pass even when discovery lists 「仍需确认」items
+        // (real incident: secondment-hour-unit-support entered propose with 8 open questions).
+        const openQuestionCount = discovery_open_question_count(discovery);
+        if (openQuestionCount > 0) {
+            reasons.push(reason("explore_open_questions_unresolved", `${discovery}: discovery.md 待确认问题段仍有 ${openQuestionCount} 条未勾选/「仍需确认」项，逐条与用户确认并改为已确认后才能进入 propose`));
+        }
     }
     else if (gate === "proposal_reviewed") {
         // DISC Phase 2: proposal review is an internal gate, not an advisory note. It is born inside
@@ -626,6 +688,9 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
         if (Object.keys(tasks).length === 0)
             reasons.push(reason("invalid_task_graph", "tasks.md has no structured tasks"));
         reasons.push(...write_scope_conflict_reasons(tasks));
+        for (const [taskId, task] of Object.entries(tasks)) {
+            reasons.push(...task_apply_execution_surface_reasons(taskId, task));
+        }
         // DISC Phase 3: tasks_complete enters the disclosure loop only once round-tagged review
         // evidence appears (design: no mandatory role review on this gate until then).
         reasons.push(...review_disclosure_reasons("tasks_complete", changeRoot, evidences));
@@ -702,6 +767,19 @@ function task_reopen_history(evidences, taskId) {
 function task_reopen_match_key(ev) {
     return `${String(ev.evidence_id ?? "")}\u0000${String(ev.reopen_id ?? "")}\u0000${String(ev.task_id ?? "")}`;
 }
+function worker_pre_edit_test_evidence(changeRoot, evidences, taskId, semanticStatus) {
+    const candidates = task_test_evidence(evidences, taskId, semanticStatus, "task_edit");
+    const valid = [];
+    const invalidReasons = [];
+    for (const ev of candidates) {
+        const problems = pre_edit_worker_test_run_reasons(changeRoot, ev, taskId, "pre_edit_test_run_invalid");
+        if (problems.length === 0)
+            valid.push(ev);
+        else
+            invalidReasons.push(...problems);
+    }
+    return { valid, invalid_reasons: invalidReasons, candidate_count: candidates.length };
+}
 function matching_reopen_resolutions(evidences, reopen) {
     const key = task_reopen_match_key(reopen);
     return live_task_reopen_resolutions(evidences)
@@ -1118,18 +1196,24 @@ export function check_task_edit(change, status, changeRoot, evidences, taskId) {
             reasons.push(reason("invalid_no_tdd_reason", `task ${taskId}: no_tdd_reason=${repr(nr)}`));
     }
     else if (tddMode === "behavior-preserving-refactor") {
-        const characterization = task_test_evidence(evidences, taskId, "expected_success", "task_edit");
-        if (characterization.length === 0)
-            reasons.push(reason("missing_characterization", `task ${taskId} (behavior-preserving-refactor) needs GREEN characterization test first`));
+        const characterizationProof = worker_pre_edit_test_evidence(changeRoot, evidences, taskId, "expected_success");
+        const characterization = characterizationProof.valid;
+        if (characterization.length === 0) {
+            reasons.push(reason(characterizationProof.candidate_count === 0 ? "missing_characterization" : "missing_worker_characterization", `task ${taskId} (behavior-preserving-refactor) needs test-runner characterization evidence before edit`));
+            reasons.push(...characterizationProof.invalid_reasons);
+        }
         reasons.push(...evidence_test_id_reasons(characterization, taskId, declared, contractIds, "characterization"));
         reasons.push(...declared_test_evidence_reasons(characterization, taskId, declared, "characterization"));
         reasons.push(...evidence_invariant_ref_reasons(characterization, taskId, declaredInvariants, validInvariantIds, "characterization"));
         reasons.push(...evidence_test_contract_invariant_reasons(characterization, taskId, test_contract_invariant_refs_by_test(changeRoot), "characterization"));
     }
     else {
-        const red = task_test_evidence(evidences, taskId, "expected_failure", "task_edit");
-        if (red.length === 0)
-            reasons.push(reason("missing_red_evidence", `task ${taskId} requires RED evidence (expected_failure) before edit`));
+        const redProof = worker_pre_edit_test_evidence(changeRoot, evidences, taskId, "expected_failure");
+        const red = redProof.valid;
+        if (red.length === 0) {
+            reasons.push(reason(redProof.candidate_count === 0 ? "missing_red_evidence" : "missing_worker_red_evidence", `task ${taskId} requires test-runner RED evidence before edit`));
+            reasons.push(...redProof.invalid_reasons);
+        }
         reasons.push(...evidence_test_id_reasons(red, taskId, declared, contractIds, "RED"));
         reasons.push(...declared_test_evidence_reasons(red, taskId, declared, "RED"));
         reasons.push(...evidence_invariant_ref_reasons(red, taskId, declaredInvariants, validInvariantIds, "RED"));
@@ -1149,6 +1233,34 @@ export function check_task_edit(change, status, changeRoot, evidences, taskId) {
 export function apply_worker_chain_lifecycle_reasons(repoRoot, changeRoot, evidences, taskId) {
     return shared_apply_worker_chain_lifecycle_reasons(repoRoot, changeRoot, evidences, taskId);
 }
+function apply_worker_chain_ref_ids(ev, singular, plural) {
+    const ids = new Set();
+    if (Array.isArray(ev[plural])) {
+        for (const item of ev[plural]) {
+            if (isObject(item) && typeof item.evidence_id === "string" && item.evidence_id)
+                ids.add(item.evidence_id);
+            else if (typeof item === "string" && item)
+                ids.add(item);
+        }
+    }
+    const single = ev[singular];
+    if (isObject(single) && typeof single.evidence_id === "string" && single.evidence_id)
+        ids.add(single.evidence_id);
+    else if (typeof single === "string" && single)
+        ids.add(single);
+    return [...ids].sort();
+}
+function active_no_tdd_metadata_matches(active, executionSurface, noTddReason) {
+    const preIds = Array.isArray(active?.pre_edit_evidence_refs) ? active.pre_edit_evidence_refs.map(String).filter(Boolean) : [];
+    return isObject(active)
+        && active.pre_edit_proof_kind === "no_tdd_declared"
+        && preIds.length === 0
+        && active.tdd_required === false
+        && active.apply_execution_surface === executionSurface
+        && typeof noTddReason === "string"
+        && active.no_tdd_reason === noTddReason
+        && NO_TDD_REASONS.has(noTddReason);
+}
 export function check_task_complete(change, status, changeRoot, evidences, taskId) {
     const gate = "task_complete";
     const reasons = [];
@@ -1163,6 +1275,7 @@ export function check_task_complete(change, status, changeRoot, evidences, taskI
     const task = parse_tasks(changeRoot)[taskId];
     if (!task)
         return block(change, gate, [reason("unknown_task", `task ${taskId} not found`)], { task_id: taskId });
+    reasons.push(...task_apply_execution_surface_reasons(taskId, task));
     const workerChainState = apply_worker_chain_lifecycle_state(get_repo_root(status), changeRoot, evidences, taskId);
     reasons.push(...workerChainState.completionReasons);
     const reopenHistory = task_reopen_history(evidences, taskId);
@@ -1185,21 +1298,11 @@ export function check_task_complete(change, status, changeRoot, evidences, taskI
         reasons.push(reason("invalid_tdd_mode", `task ${taskId}: tdd_mode=${repr(tddMode)}`));
     if (tddRequired) {
         const allGreen = task_test_evidence(evidences, taskId, "expected_success", "task_complete");
-        const green = workerChainState.validClosedGreenEvidenceIds.size > 0
-            ? allGreen.filter((ev) => (ev.apply_execution_chain === "executor_worker"
-                && workerChainState.validClosedChainIds.has(String(ev.apply_worker_chain_id ?? ""))
-                && workerChainState.validClosedGreenEvidenceIds.has(String(ev.evidence_id ?? ""))))
-            : workerChainState.takeoverBaselines.length > 0
-                ? allGreen.filter((ev) => serial_completion_green(ev) && workerChainState.takeoverBaselines.some((baseline) => (baseline.successorGreenRefs.includes(String(ev.evidence_id ?? ""))
-                    && fingerprint_matches(ev.implementation_fingerprint, baseline.fingerprint))))
-                : allGreen.filter(serial_completion_green);
+        const green = allGreen.filter((ev) => (ev.apply_execution_chain === "executor_worker"
+            && workerChainState.validClosedChainIds.has(String(ev.apply_worker_chain_id ?? ""))
+            && workerChainState.validClosedGreenEvidenceIds.has(String(ev.evidence_id ?? ""))));
         if (green.length === 0)
             reasons.push(reason("missing_green_evidence", `task ${taskId} requires GREEN evidence (expected_success) before completion`));
-        if (workerChainState.validClosedGreenEvidenceIds.size === 0 && workerChainState.takeoverBaselines.length > 0) {
-            if (green.length === 0) {
-                reasons.push(reason("apply_worker_chain_takeover_green_mismatch", `task ${taskId} requires declared successor serial GREEN evidence after takeover baseline with matching implementation fingerprint`));
-            }
-        }
         const declared = new Set(splitList(attrs.test_refs ?? ""));
         const declaredInvariants = new Set(splitList(attrs.invariant_refs ?? ""));
         if (declared.size === 0)
@@ -1235,9 +1338,39 @@ export function check_task_complete(change, status, changeRoot, evidences, taskI
         const nr = attrs.no_tdd_reason;
         if (!NO_TDD_REASONS.has(nr))
             reasons.push(reason("invalid_no_tdd_reason", `task ${taskId}: no_tdd_reason=${repr(nr)}`));
-        const verifications = task_alternative_verification(evidences, taskId);
-        if (verifications.length === 0)
+        const executionSurface = task_apply_execution_surface(task);
+        const directAlternativeAllowed = executionSurface === "docs_generated" || executionSurface === "no_code";
+        const implementationAlternativeRequired = executionSurface === "implementation" || executionSurface === "runtime_config";
+        const allVerifications = task_alternative_verification(evidences, taskId);
+        let validAlternativeEvidenceIds = workerChainState.validClosedAlternativeEvidenceIds;
+        if (implementationAlternativeRequired) {
+            const activeByChain = new Map(live_pass(evidences, { gate: "task_complete", kind: "apply_worker_chain", task_id: taskId })
+                .filter((ev) => ev.chain_state === "active" && typeof ev.apply_worker_chain_id === "string")
+                .map((ev) => [String(ev.apply_worker_chain_id), ev]));
+            const closedAlternativeChains = live_pass(evidences, { gate: "task_complete", kind: "apply_worker_chain", task_id: taskId })
+                .filter((ev) => (ev.chain_state === "closed"
+                && String(ev.completion_proof_kind ?? "green_tests") === "alternative_verification"
+                && workerChainState.validClosedAlternativeChainIds.has(String(ev.apply_worker_chain_id ?? ""))));
+            const matchingClosedAlternativeChains = closedAlternativeChains.filter((ev) => (active_no_tdd_metadata_matches(activeByChain.get(String(ev.apply_worker_chain_id ?? "")), executionSurface, nr)));
+            const metadataMismatchChains = closedAlternativeChains
+                .filter((ev) => !matchingClosedAlternativeChains.includes(ev))
+                .map((ev) => String(ev.apply_worker_chain_id ?? ev.evidence_id ?? ""))
+                .filter(Boolean)
+                .sort();
+            if (metadataMismatchChains.length > 0) {
+                reasons.push(reason("apply_worker_chain_active_invalid", `task ${taskId} closed alternative apply_worker_chain active no-TDD metadata must match task metadata: ${renderList(metadataMismatchChains)}`, metadataMismatchChains));
+            }
+            validAlternativeEvidenceIds = new Set(matchingClosedAlternativeChains.flatMap((ev) => apply_worker_chain_ref_ids(ev, "alternative_verification_evidence_ref", "alternative_verification_evidence_refs")));
+        }
+        const verifications = directAlternativeAllowed
+            ? allVerifications
+            : allVerifications.filter((ev) => validAlternativeEvidenceIds.has(String(ev.evidence_id ?? "")));
+        if (implementationAlternativeRequired && verifications.length === 0) {
+            reasons.push(reason("missing_alternative_verification", `task ${taskId} apply_execution_surface=${executionSurface} requires closed apply_worker_chain alternative_verification proof before completion`));
+        }
+        else if (!implementationAlternativeRequired && verifications.length === 0) {
             reasons.push(reason("missing_alternative_verification", `task ${taskId} has tdd_required:false and needs alternative verification evidence`));
+        }
         if (reopenMode.mode === "reopened") {
             const reopen = reopenMode.reopen;
             const reopenId = String(reopen.reopen_id ?? "");

package/dist/src/hooks/adapter.js

@@ -224,11 +224,32 @@ function postToolUseOutput(decision) {
         },
     };
 }
+function isSubagentHookEvent(eventName) {
+    return eventName === "SubagentStart" || eventName === "SubagentStop";
+}
 function subagentOutput(decision, eventName) {
+    if (!decision.allowed) {
+        return {
+            systemMessage: `SuperSpec ${eventName} runlog skipped; ${decision.block_reasons.map((item) => item.message).join("; ") || "audit telemetry unavailable"}`,
+            hookSpecificOutput: {
+                hookEventName: eventName,
+                additionalContext: "SuperSpec subagent telemetry is best-effort and did not block the workflow.",
+            },
+        };
+    }
     return {
         systemMessage: `SuperSpec ${eventName} runlog recorded as ${decision.trust}; strict_profile=${decision.strict_profile}`,
     };
 }
+function inertSubagentOutput(eventName, message) {
+    return {
+        systemMessage: message,
+        hookSpecificOutput: {
+            hookEventName: eventName,
+            additionalContext: "SuperSpec subagent telemetry is best-effort and did not block the workflow.",
+        },
+    };
+}
 function writeTempEvent(event) {
     const path = join(tmpdir(), `superspec-hook-event-${randomUUID()}.json`);
     writeFileSync(path, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
@@ -241,8 +262,9 @@ function validateHookEvent(event) {
     if (!["PreToolUse", "PostToolUse", "SubagentStart", "SubagentStop"].includes(eventName)) {
         return `unsupported hook_event_name: ${eventName}`;
     }
-    if (typeof event.cwd !== "string" || !event.cwd)
+    if ((eventName === "PreToolUse" || eventName === "PostToolUse") && (typeof event.cwd !== "string" || !event.cwd)) {
         return "hook event missing required cwd";
+    }
     if (eventName === "PreToolUse") {
         if (typeof event.tool_name !== "string" || !event.tool_name)
             return "PreToolUse hook event missing required tool_name";
@@ -254,6 +276,7 @@ function validateHookEvent(event) {
 export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSync(0, "utf8")) {
     const parsedArgs = parseArgs(argv);
     let event;
+    let eventNameForFailure = "";
     try {
         if (!stdin.trim())
             throw new Error("hook stdin is empty");
@@ -261,11 +284,16 @@ export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSyn
         if (!isObject(parsed))
             throw new Error("hook stdin must be a JSON object");
         event = parsed;
+        eventNameForFailure = typeof event.hook_event_name === "string" ? event.hook_event_name : "";
         const validationError = validateHookEvent(event);
         if (validationError)
             throw new Error(validationError);
     }
     catch (err) {
+        if (isSubagentHookEvent(eventNameForFailure)) {
+            const payload = inertSubagentOutput(eventNameForFailure, `SuperSpec ${eventNameForFailure} runlog skipped: ${err.message}`);
+            return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
+        }
         return { code: 2, stdout: "", stderr: `SuperSpec hook event parse failed: ${err.message}\n` };
     }
     const inference = parsedArgs.change ? { state: "unique", change: parsedArgs.change } : inferChangeFromActiveSessions(event);
@@ -274,8 +302,9 @@ export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSyn
         const payload = noChangeFallback(event, inference);
         return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
     }
-    const eventRef = writeTempEvent(event);
+    let eventRef = null;
     try {
+        eventRef = writeTempEvent(event);
         const eventName = String(event.hook_event_name ?? "");
         let payload;
         if (eventName === "PreToolUse") {
@@ -298,14 +327,21 @@ export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSyn
         return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
     }
     catch (err) {
+        if (isSubagentHookEvent(String(event.hook_event_name ?? ""))) {
+            const eventName = String(event.hook_event_name ?? "");
+            const payload = inertSubagentOutput(eventName, `SuperSpec ${eventName} runlog skipped: ${err.message}`);
+            return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
+        }
         return { code: 2, stdout: "", stderr: `SuperSpec hook failed closed: ${err.message}\n` };
     }
     finally {
-        try {
-            unlinkSync(resolve(eventRef));
-        }
-        catch {
-            // best effort temp cleanup
+        if (eventRef) {
+            try {
+                unlinkSync(resolve(eventRef));
+            }
+            catch {
+                // best effort temp cleanup
+            }
         }
     }
 }

package/dist/src/hooks/guard_api.js

@@ -457,7 +457,7 @@ export function hookCheckWrite(change, eventRef) {
                     block_reasons: blockReasons,
                     audit_only_reasons: auditOnlyReasons,
                     target_paths: intent.target_paths,
-                    next_allowed_actions: ["rerun the relevant superspec guard check and use the expected workflow command surface"],
+                    next_allowed_actions: ["rerun the relevant superspec check and use the expected workflow command surface"],
                 });
             }
             return hookDecision(ctx, "hook_check_write", true, {
@@ -510,7 +510,7 @@ export function hookCheckWrite(change, eventRef) {
                 block_reasons: blockReasons,
                 audit_only_reasons: auditOnlyReasons,
                 target_paths: intent.target_paths,
-                next_allowed_actions: ["rerun the relevant superspec guard check and use the expected workflow command surface"],
+                next_allowed_actions: ["rerun the relevant superspec check and use the expected workflow command surface"],
             });
         }
         return hookDecision(ctx, "hook_check_write", true, {

package/dist/src/hooks/health.js

@@ -4,18 +4,6 @@ import { reason, sha256_file } from "../util.js";
 import { HOOK_ADAPTER_VERSION } from "./types.js";
 const HOOK_COMMAND = 'superspec-hook --change "$SUPERSPEC_CHANGE"';
 const EXPECTED_HOOK_MATRIX = [
-    {
-        eventName: "PreToolUse",
-        matcher: "Bash|apply_patch|Edit|Write|mcp__.*",
-        timeout: 120,
-        statusMessage: "SuperSpec 写入策略检查",
-    },
-    {
-        eventName: "PostToolUse",
-        matcher: "Bash",
-        timeout: 120,
-        statusMessage: "SuperSpec 运行证据记录",
-    },
     {
         eventName: "SubagentStart",
         matcher: ".*",

package/dist/src/hooks/policy_event.js

@@ -2340,7 +2340,9 @@ function tokenAtSameCommand(tokens, idx) {
     return tokens[idx];
 }
 function isHookEntrypointName(name) {
-    return name === "superspec-guard"
+    return name === "superspec-check"
+        || name === "superspec-check.js"
+        || name === "superspec-guard"
         || name === "superspec-guard.js"
         || name === "superspec-hook"
         || name === "superspec-hook.js";
@@ -2392,9 +2394,13 @@ function commandLooksLikeInternalHookWriter(command, depth = 0) {
                 return true;
             if (next === "guard" && afterNext?.startsWith("hook-record-"))
                 return true;
+            if (next === "check" && afterNext?.startsWith("hook-record-"))
+                return true;
         }
         if (name === "superspec-guard" && tokenAtSameCommand(tokens, commandIdx + 1)?.startsWith("hook-record-"))
             return true;
+        if (name === "superspec-check" && tokenAtSameCommand(tokens, commandIdx + 1)?.startsWith("hook-record-"))
+            return true;
         if (isHookAdapterEntrypointName(name))
             return true;
         if (isHookEntrypointName(name) && tokenAtSameCommand(tokens, commandIdx + 1)?.startsWith("hook-record-"))
@@ -2442,6 +2448,10 @@ function commandLooksLikeUnsafeLifecycleTermination(command, depth = 0) {
             if (segmentHasDangerousReason(commandIdx + 3, segmentEnd))
                 return true;
         }
+        if (token === "superspec" && tokens[commandIdx + 1] === "check" && tokens[commandIdx + 2] === "hook-session-end") {
+            if (segmentHasDangerousReason(commandIdx + 3, segmentEnd))
+                return true;
+        }
         if (token === "superspec" && tokens[commandIdx + 1] === "hook-session-end") {
             if (segmentHasDangerousReason(commandIdx + 2, segmentEnd))
                 return true;

package/dist/src/i18n.js

@@ -73,6 +73,7 @@ const REASON_ZH = {
     invalid_tdd_mode: { label_zh: "TDD 模式无效", hint_zh: "task 上声明的 tdd_mode 不在允许枚举里。" },
     invalid_no_tdd_reason: { label_zh: "免 TDD 理由无效", hint_zh: "task 上声明的 no_tdd_reason 不在允许枚举里。" },
     missing_discovery: { label_zh: "缺少探索记录", hint_zh: "探索阶段缺少 discovery.md，或者该文件内容为空。" },
+    explore_open_questions_unresolved: { label_zh: "探索待确认问题未清空", hint_zh: "discovery.md 的待确认问题还有未勾选或「仍需确认」的项，需要逐条与用户确认并改成已确认后才能进入 propose。" },
     missing_proposal: { label_zh: "缺少提案工件", hint_zh: "提案工件还没有完成。" },
     missing_proposal_review: { label_zh: "缺少提案审查", hint_zh: "提案审查阶段还没有收集到严格审查证据。" },
     explore_complete_failed: { label_zh: "探索阶段未通过", hint_zh: "后续阶段依赖的探索完成检查还没有通过。" },
@@ -95,6 +96,65 @@ const REASON_ZH = {
     user_uninstall_failed: { label_zh: "用户级卸载失败", hint_zh: "用户级 SuperSpec 卸载失败。" },
     guard_error: { label_zh: "检查执行失败", hint_zh: "guard 命令执行过程中发生了可报告错误。" },
     guard_internal_error: { label_zh: "检查器内部错误", hint_zh: "guard 内部抛出了异常，需要查看错误信息排查。" },
+    "apply_worker_chain_active": { label_zh: "活跃工作链存在", hint_zh: "当前任务已有活跃的 apply worker chain。" },
+    "apply_worker_chain_active_conflict": { label_zh: "活跃工作链冲突", hint_zh: "存在多条活跃 apply worker chain，需要先收敛到一条。" },
+    "apply_worker_chain_missing_active": { label_zh: "缺少活跃工作链", hint_zh: "当前任务没有活跃的 apply worker chain，需要先启动。" },
+    "apply_worker_chain_terminal_conflict": { label_zh: "工作链终态冲突", hint_zh: "存在多条终态 apply worker chain，需要先收敛。" },
+    "archive_not_found": { label_zh: "归档未找到", hint_zh: "没有找到已归档的 change，确认归档是否完成。" },
+    "bash_write_target_unknown": { label_zh: "Bash 写入目标未知", hint_zh: "Bash 命令的写入目标无法识别，需要明确目标路径。" },
+    "curl_config_write_target_unknown": { label_zh: "curl 配置写入目标未知", hint_zh: "curl 配置类命令的写入目标无法识别。" },
+    "curl_write_target_unknown": { label_zh: "curl 写入目标未知", hint_zh: "curl 命令的写入目标无法识别。" },
+    "custom_superspec_schema_present": { label_zh: "自定义 schema 存在", hint_zh: "检测到自定义 OpenSpec schema，SuperSpec 只支持默认 spec-driven。" },
+    "dangling_evidence_ref": { label_zh: "证据引用悬空", hint_zh: "evidence 引用的 evidence_id 不存在，检查引用或恢复被删证据。" },
+    "dirty_worktree_unattributed": { label_zh: "脏工作区未归属", hint_zh: "工作区有改动但无法归因到当前 change，需要先确认归属。" },
+    "duplicate_test_command": { label_zh: "测试命令重复", hint_zh: "检测到重复的测试命令声明。" },
+    "evidence_bad_status": { label_zh: "证据状态非法", hint_zh: "evidence 的 status 字段不在合法枚举内。" },
+    "evidence_forbidden_field": { label_zh: "证据含禁止字段", hint_zh: "evidence 包含当前 kind 不允许的字段。" },
+    "evidence_missing_field": { label_zh: "证据缺字段", hint_zh: "evidence 缺少必需字段。" },
+    "evidence_unknown_kind": { label_zh: "证据 kind 未知", hint_zh: "evidence 的 kind 不在白名单内。" },
+    "evidence_unparsable": { label_zh: "证据不可解析", hint_zh: "evidence 文件不是合法 JSON。" },
+    "evidence_unsafe_ref": { label_zh: "证据引用不安全", hint_zh: "evidence 的引用路径逃逸了允许范围。" },
+    "forbidden_alias_path": { label_zh: "禁用别名路径", hint_zh: "使用了被禁用的配置或状态文件别名。" },
+    "hook_internal_writer_invocation": { label_zh: "内部写入命令被调用", hint_zh: "模型控制的工具调用不得触发 SuperSpec hook 写入命令。" },
+    "hook_manifest_missing_or_unmanaged": { label_zh: "hook manifest 缺失或不受管", hint_zh: ".codex/hooks.json 缺失或不是 SuperSpec 受管版本。" },
+    "hook_manifest_unmanaged": { label_zh: "hook manifest 不受管", hint_zh: ".codex/hooks.json 不是 SuperSpec 受管版本。" },
+    "hook_session_audit_only": { label_zh: "hook 会话仅审计", hint_zh: "当前 hook 会话是 audit-only，不能作为可信强制来源。" },
+    "hook_session_corrupt": { label_zh: "hook 会话损坏", hint_zh: "活跃 hook 会话记录损坏，需要重建。" },
+    "hook_session_expired": { label_zh: "hook 会话过期", hint_zh: "活跃 hook 会话已过期。" },
+    "hook_session_termination_untrusted": { label_zh: "hook 会话终止不可信", hint_zh: "会话终止来源不可信，不能关闭 lease。" },
+    "invariants_not_reviewed": { label_zh: "业务约束未审查", hint_zh: "business-invariants 尚未通过审查。" },
+    "mixed_request_changes_route": { label_zh: "混合返工路由", hint_zh: "request_changes 同时包含不一致的 route。" },
+    "openspec_canonical_direct_edit": { label_zh: "直接编辑 OpenSpec 正本", hint_zh: "不允许绕过 openspec instructions 直接编辑正本 artifact。" },
+    "openspec_status_incompatible": { label_zh: "OpenSpec 状态不兼容", hint_zh: "openspec status 输出与预期结构不一致。" },
+    "openspec_tasks_direct_edit": { label_zh: "直接编辑 tasks", hint_zh: "不允许绕过流程直接编辑 tasks.md。" },
+    "post_implementation_invariant_backfill": { label_zh: "实现后补不变量", hint_zh: "不允许在实现后才补业务不变量。" },
+    "protected_path_dirty": { label_zh: "受保护路径被改动", hint_zh: "受保护路径处于脏状态。" },
+    "protected_trust_root_link_source": { label_zh: "信任根符号链接", hint_zh: "信任根路径通过符号链接指向外部来源。" },
+    "protected_trust_root_write": { label_zh: "写入信任根", hint_zh: "不允许写入 SuperSpec 信任根路径。" },
+    "ref_empty": { label_zh: "引用为空", hint_zh: "引用字段为空字符串。" },
+    "ref_not_readable": { label_zh: "引用不可读", hint_zh: "引用指向的文件不可读。" },
+    "ref_path_unsafe": { label_zh: "引用路径不安全", hint_zh: "引用路径逃逸了允许的根。" },
+    "reopen_lifecycle_exhausted": { label_zh: "重开次数耗尽", hint_zh: "task reopen 的生命周期次数已用尽。" },
+    "required_claim_unadjudicated": { label_zh: "必需 claim 未裁决", hint_zh: "存在尚未裁决的必需 claim。" },
+    "review_diff_not_covered": { label_zh: "review 未覆盖 diff", hint_zh: "review 未覆盖当前 diff。" },
+    "runtime_evidence_missing_command_fingerprint": { label_zh: "运行时证据缺命令指纹", hint_zh: "runtime evidence 缺少 command fingerprint。" },
+    "runtime_evidence_missing_exit_code": { label_zh: "运行时证据缺退出码", hint_zh: "runtime evidence 缺少 exit code。" },
+    "runtime_evidence_missing_hook_event": { label_zh: "运行时证据缺 hook 事件", hint_zh: "runtime evidence 缺少可信 hook 事件。" },
+    "runtime_evidence_missing_raw_log_pin": { label_zh: "运行时证据缺日志锚定", hint_zh: "runtime evidence 缺少 raw log pinned refs。" },
+    "runtime_evidence_missing_token": { label_zh: "运行时证据缺 token", hint_zh: "runtime evidence 缺少绑定 token。" },
+    "runtime_evidence_untrusted_provenance": { label_zh: "运行时证据来源不可信", hint_zh: "runtime evidence 缺少可信 provenance。" },
+    "scope_expansion_requires_propose": { label_zh: "范围扩大需回 propose", hint_zh: "任务范围扩大需要回 propose 重新确认。" },
+    "self_review_not_allowed": { label_zh: "不允许自审", hint_zh: "主线程不能充当审查角色。" },
+    "shell_path_may_touch_trust_root": { label_zh: "shell 路径可能触及信任根", hint_zh: "shell 展开的路径可能触及 SuperSpec 信任根。" },
+    "superspec_not_preserved": { label_zh: "SuperSpec 记录未保全", hint_zh: "归档后 .superspec 记录未能从 preservation manifest 追溯。" },
+    "target_path_outside_repo": { label_zh: "写入目标在仓库外", hint_zh: "写入目标路径逃逸了仓库根。" },
+    "task_already_done": { label_zh: "任务已完成", hint_zh: "目标 task 已经勾选完成。" },
+    "test_id_not_in_log": { label_zh: "测试 id 不在日志中", hint_zh: "声称的 test_id 未出现在引用日志里。" },
+    "test_not_declared_for_task": { label_zh: "测试未为任务声明", hint_zh: "测试未在任务的 test_refs 中声明。" },
+    "untrusted_test_command_ref": { label_zh: "测试命令引用不可信", hint_zh: "测试命令引用来源不可信。" },
+    "unsafe_write_scope": { label_zh: "写范围不安全", hint_zh: "任务的 write_scope 包含不安全路径。" },
+    "unsupported_write_surface": { label_zh: "不支持的写入面", hint_zh: "当前面不支持该写入操作。" },
+    "write_scope_conflict": { label_zh: "写范围冲突", hint_zh: "多个任务的 write_scope 存在冲突。" },
 };
 const WORKFLOW_TERMS_ZH = {
     "check-enter": { term: "check-enter", label_zh: "进入阶段前检查", hint_zh: "进入某个流程阶段前先运行的检查命令。" },
@@ -110,9 +170,9 @@ const TRUST_WARNING_ZH = {
     "project init installs project surfaces only; change sidecars are created lazily by later superspec phases": "project init 只安装项目级内容；change sidecar 会在后续 superspec 阶段按需创建。",
 };
 const ACTION_ZH_EXACT = {
-    "continue with superspec-explore/propose/apply guard checks": "继续执行探索、提案和实现阶段的前置检查。",
-    "create/select a change during superspec-explore, then run change-scoped guard checks": "先在探索阶段创建或选择一个变更，然后运行该变更范围内的前置检查。",
-    "review *.new files for user-modified surfaces, then rerun superspec guard check-init": "先检查因用户改动而生成的 *.new 文件，然后重新运行初始化前置检查；Windows PowerShell 中使用 superspec.cmd guard check-init。",
+    "continue with superspec-explore/propose/apply check checks": "继续执行探索、提案和实现阶段的前置检查。",
+    "create/select a change during superspec-explore, then run change-scoped check checks": "先在探索阶段创建或选择一个变更，然后运行该变更范围内的前置检查。",
+    "review *.new files for user-modified surfaces, then rerun superspec check check-init": "先检查因用户改动而生成的 *.new 文件，然后重新运行初始化前置检查；Windows PowerShell 中使用 superspec.cmd check check-init。",
     "review *.new files for user-modified user-level surfaces": "先检查用户级内容对应的 *.new 文件。",
     "user-level SuperSpec Codex surfaces installed; use superspec init --scope project inside a repo when project-local surfaces are needed": "用户级 SuperSpec 配套内容已安装；如果仓库里还需要项目级内容，请在仓库内运行 superspec init --scope project；Windows PowerShell 中使用 superspec.cmd init --scope project。",
     "finish remaining unchecked tasks and mark them complete only after check-task-complete passes": "先完成剩余未勾选任务，并且仅在任务完成检查通过后再标记完成。",

package/dist/src/init_cli.js

@@ -318,7 +318,7 @@ function run_init(args, scope) {
     }
     else if (args.mode === "update") {
         summary = engineDecision(`${gatePrefix}_update`, targetRoot, update_workflow(targetRoot, { scope }), [
-            scope === "project" ? "review *.new files for user-modified surfaces, then rerun superspec guard check-init" : "review *.new files for user-modified user-level surfaces",
+            scope === "project" ? "review *.new files for user-modified surfaces, then rerun superspec check check-init" : "review *.new files for user-modified user-level surfaces",
         ]);
     }
     else if (scope === "user") {