@peterxiaoyang/superspec 0.1.37 → 0.1.39

package/dist/record.js

@@ -2,9 +2,10 @@
 import { readFileSync, existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, sha256Text, withLock, appendRawRecord, } from "./store.js";
-import { reviewEvidenceDigest, reviewVerifierStaleReason } from "./review.js";
-import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewDecisionAnswerLabel, codeReviewJobStaleReason, normalizeCodeReviewDecisionAnswer, scanCodeChanges, } from "./code_review.js";
+import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewDecisionAnswerLabel, normalizeCodeReviewDecisionAnswer, } from "./code_review.js";
+import { invalidReasonForSubmittedReport } from "./job_validity.js";
 import { jobSubmitArgv } from "./job_action.js";
+import { REVIEW_DOC_PATHS } from "./review.js";
 const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
 const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
 const REVIEWER_KINDS = new Set(["codex-subagent", "human", "external-agent"]);
@@ -187,6 +188,7 @@ function codeReviewRejectEventPayload(input) {
         report_digest: input.reportDigest,
         result_kind: input.resultKind,
         reason: input.reason,
+        ...(input.reportPath ? { report_path: input.reportPath } : {}),
         ...(input.rawRef ?? {}),
     };
     if (input.resultKind === "review_failed" && input.parsedReport) {
@@ -220,22 +222,6 @@ function projectRelativePath(projectRoot, path) {
         return null;
     return rel;
 }
-function staleBoundFilesChecks(job, projectRoot, changeRoot, ignoredCodePaths = []) {
-    const checks = [];
-    if (job.role === "code-reviewer") {
-        const ignored = new Set(ignoredCodePaths);
-        const currentPaths = scanCodeChanges(projectRoot).paths.filter(path => !ignored.has(path));
-        const reason = codeReviewJobStaleReason(projectRoot, job, currentPaths);
-        return reason ? [reason] : [];
-    }
-    for (const bf of job.boundFiles) {
-        const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
-        if (currentSha !== bf.sha) {
-            checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
-        }
-    }
-    return checks;
-}
 /** 从 events 中查找 job（H4 修复：job 只在 transition_commit 的 new_jobs payload 里） */
 function findJob(events, jobId) {
     for (const ev of events) {
@@ -312,12 +298,14 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         checks.push("报告必须是有效 JSON");
     }
     const reportPath = reportFile ? projectRelativePath(projectRoot, reportFile) : null;
-    checks.push(...staleBoundFilesChecks(job, projectRoot, changeRoot, reportPath ? [reportPath] : []));
-    const reviewStaleReason = job.role === "code-reviewer"
-        ? null
-        : reviewVerifierStaleReason(job, changeRoot, reviewEvidenceDigest(events));
-    if (reviewStaleReason && !checks.includes(reviewStaleReason)) {
-        checks.push(reviewStaleReason);
+    const invalidReason = invalidReasonForSubmittedReport(job, {
+        projectRoot,
+        changeRoot,
+        events,
+        reportPath,
+    });
+    if (invalidReason) {
+        checks.push(invalidReason);
     }
     if (!reportContent.trim()) {
         checks.push("报告内容为空");
@@ -337,11 +325,13 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
                     reason: checks.join("; "),
                     parsedReport,
                     rawRef,
+                    reportPath,
                 })
                 : {
                     job_id: jobId,
                     role: job.role,
                     report_digest: reportDigest,
+                    ...(reportPath ? { report_path: reportPath } : {}),
                     reason: checks.join("; "),
                 }),
         });
@@ -362,6 +352,8 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
             parsedReport,
             rawRef,
         }));
+        if (reportPath)
+            rejectEvent.payload.report_path = reportPath;
         appendEvent(projectRoot, change, rejectEvent);
         return {
             event_type: "job_rejected",
@@ -389,6 +381,7 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
                     reason,
                     parsedReport,
                     rawRef,
+                    reportPath,
                 })));
                 return {
                     event_type: "job_rejected",
@@ -415,6 +408,7 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
                 reason,
                 parsedReport,
                 rawRef,
+                reportPath,
             })));
             return {
                 event_type: "job_rejected",
@@ -430,6 +424,7 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         role: job.role,
         report_digest: reportDigest,
         accepted_at: new Date().toISOString(),
+        ...(reportPath ? { report_path: reportPath } : {}),
         ...rawRef,
     });
     appendEvent(projectRoot, change, acceptEvent);
@@ -508,7 +503,7 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
             reason: "missing_scope_or_answer",
             input_digest: inputDigest,
         }));
-        return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少 scope 或 answer" };
+        return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少决策范围（scope）或答复内容（answer）" };
     }
     if (decision.scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX)) {
         const normalizedAnswer = normalizeCodeReviewDecisionAnswer(decision.answer);
@@ -561,7 +556,7 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
     return {
         event_type: "user_decision_recorded",
         accepted: true,
-        message: `用户决策已登记：${decision.scope}`,
+        message: `用户决策已登记：决策范围（scope）=${decision.scope}`,
     };
 }
 /** record user-decision：登记用户决策 */
@@ -620,6 +615,31 @@ export function jobsList(projectRoot, change) {
     }
     return { open, accepted, rejected };
 }
+function packetFieldDescriptions() {
+    return {
+        job_id: "工作项 ID，用于提交本次审查或验证报告。",
+        packet_digest: "工作项说明摘要，用于证明报告对应的是当前这份工作项说明。",
+        boundFiles: "本工作项绑定的文件清单；代码审查报告必须说明这些文件是否都看过。",
+        review_scope: "报告中的审查覆盖范围，说明看了哪些文件、哪些没看及原因。",
+        code_review_scope: "代码审查范围：从已审基点到当前 HEAD 的提交改动、工作区改动和未跟踪代码文件。",
+        task_execution_index: "按任务汇总的执行证据：每个任务（task）的执行依据、声明测试、测试证据和改动文件。",
+        contract: "任务启动时的执行依据快照：tests/design/source/reason/guard 分别对应 测试/设计/来源/原因/边界；null 表示历史任务没有执行依据。",
+        changed_paths: "与某个任务（task）或代码状态检查相关的改动文件。",
+        changed_paths_partial_reason: "该任务（task）的提交段 diff 失败原因；存在时 changed_paths 只包含工作区对比结果，归属可能不完整。",
+        unattributed_paths: "代码审查范围中暂时无法归属到某个任务（task）的文件。",
+        unknown_attribution_tasks: "因为缺少边界快照或提交段 diff 失败而无法完整计算改动归属的任务（task）。",
+        coverage_exemption_refs: "测试覆盖豁免引用：说明某个 TEST 为什么没有绑定到任务（task）。",
+        code_state_check: "代码状态检查：最终验证时用于判断代码审查后代码是否又发生变化。",
+        event_id: "事件 ID，用于追溯证据来源。",
+        event_digest: "事件摘要，用于确认引用的证据事件没有被替换。",
+        attempt_id: "任务尝试 ID；执行依据模式下测试运行必须绑定当前活跃任务尝试。",
+        task_structure_digest: "历史模式的任务结构指纹；仅用于兼容旧证据。",
+        test_id: "测试契约里的 TEST ID。",
+        semantic_status: "测试语义状态：RED 预期失败、GREEN 预期成功或特征化（characterization）通过。",
+        covers_task_ids: "回归测试覆盖了哪些已完成任务（task）。",
+        scope_note: "范围扩大说明；任务（task）实现超出执行依据边界时填写。",
+    };
+}
 /** jobs packet：返回工作项执行说明 */
 export function jobsPacket(projectRoot, change, jobId) {
     const events = readEvents(projectRoot, change);
@@ -628,15 +648,24 @@ export function jobsPacket(projectRoot, change, jobId) {
         return { found: false, message: `工作项 ${jobId} 不存在` };
     }
     const isCodeReviewer = job.role === "code-reviewer";
+    const packetContext = job.packet_context;
     return {
         found: true,
         packet: {
             job_id: job.job_id,
             role: job.role,
+            ...(job.gate_id ? { gate_id: job.gate_id } : {}),
             recommended_agent: recommendedAgentForRole(job.role),
             boundFiles: job.boundFiles,
             ...(job.review_evidence_digest ? { review_evidence_digest: job.review_evidence_digest } : {}),
             ...(job.previous_rejection ? { previous_rejection: job.previous_rejection } : {}),
+            ...(packetContext ? { packet_context: packetContext } : {}),
+            ...(packetContext?.code_review_scope ? { code_review_scope: packetContext.code_review_scope } : {}),
+            ...(packetContext?.coverage_exemption_refs ? { coverage_exemption_refs: packetContext.coverage_exemption_refs } : {}),
+            ...(packetContext?.task_execution_index ? { task_execution_index: packetContext.task_execution_index } : {}),
+            ...(packetContext?.unattributed_paths ? { unattributed_paths: packetContext.unattributed_paths } : {}),
+            ...(packetContext?.unknown_attribution_tasks ? { unknown_attribution_tasks: packetContext.unknown_attribution_tasks } : {}),
+            ...(packetContext?.code_state_check ? { code_state_check: packetContext.code_state_check } : {}),
             packet_digest: job.packet_digest,
             required_output_kind: "job_report_json",
             preferred_input_mode: "stdin",
@@ -647,16 +676,23 @@ export function jobsPacket(projectRoot, change, jobId) {
                 ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer", "review_scope"]
                 : requiresReviewer(job.role) ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer"] : [...REVIEW_REPORT_REQUIRED_FIELDS],
             output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
+            字段说明: packetFieldDescriptions(),
             output_instructions: `${roleDescription(job.role)}。请审查 ${job.boundFiles.map(f => f.path).join(", ")}，` +
                 (job.review_evidence_digest ? `本工作项对应的执行证据版本为 ${job.review_evidence_digest}，` : "") +
                 (job.previous_rejection ? `上一次代码审查没有形成可推进结论，原因：${job.previous_rejection.reason}。本次请根据该原因重新审查，` : "") +
-                (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在 reviewer.kind/id 中记录来源，` : "") +
-                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仍可作为 fallback。以下 JSON 合约给审查代理使用，普通对话不要原样复述。` +
+                (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
+                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仅作备用。协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
                 (isCodeReviewer
-                    ? `最小格式：{"role":"code-reviewer","verdict":"pass|fail","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":${JSON.stringify(job.boundFiles.map(f => f.path))},"checked_docs":["proposal.md","design.md","tasks.md",".superspec/artifacts/test-contract.md"],"unchecked":[]},"findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}；review_scope 用来说明本次审查覆盖了哪些文件和文档，checked_paths 与 unchecked 必须合起来覆盖全部 boundFiles，unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}。`
-                        + `报告结论为 fail 时，findings 至少包含一个可处理、可追溯的阻塞问题，字段为 {"id":"<stable-id>","blocking":true,"type":"implementation|spec|mixed","description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。type 中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题。`
+                    ? `最小格式：{"role":"code-reviewer","verdict":"pass|fail","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":${JSON.stringify(job.boundFiles.map(f => f.path))},"checked_docs":${JSON.stringify(REVIEW_DOC_PATHS)},"unchecked":[]},"findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}；审查覆盖范围（review_scope）用来说明本次审查覆盖了哪些文件和文档，已检查路径（checked_paths）与未检查项（unchecked）必须合起来覆盖全部绑定文件（boundFiles），unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}。`
+                        + `报告结论为 fail 时，问题列表（findings）至少包含一个可处理、可追溯的阻塞问题，字段为 {"id":"<stable-id>","blocking":true,"type":"implementation|spec|mixed","description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。问题类型（type）中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题。`
+                        + (packetContext?.task_execution_index
+                            ? `本工作项带任务执行索引（task_execution_index）：按 task 对照其执行依据快照（contract）审查——实现路线对照 design 引用原文、累计 diff 对照 guard 边界、测试断言对照 tests 声明的 scenario；每项的 scope_note 是执行者登记的范围扩大说明，判断其合理性与验证充分性；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动逐个判断合理性；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。`
+                            : "")
                     : job.role === "verifier"
-                        ? `最小格式：{"role":"verifier","verdict":"pass|fail","findings":[]}。核对代码审查记录 code_review_gate：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对代码审查问题闭环：实现修复任务必须带 review_fix_of:<job_id>#<problem_id>，方案/混合问题必须有用户决策或后续修复证据。核对 RED/GREEN：同一 task_completed.attempt_id 下必须有 RED/characterization 与 GREEN；test-run 证据应包含 test_id、command、cwd、exit_code、semantic_status；审查修复的回归 test-run 可用 covers_task_ids 说明覆盖了哪些已完成任务；缺少 attempt_id 的旧证据只能弱引用。`
+                        ? `最小格式：{"role":"verifier","verdict":"pass|fail","findings":[]}。核对代码审查记录（code_review_gate）：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对代码审查问题闭环：实现修复任务必须带审查修复引用（review_fix_of:<job_id>#<problem_id>），方案/混合问题必须有用户决策或后续修复证据。核对 RED/GREEN：证据须在同一已完成任务的任务尝试 ID（task_completed.attempt_id）下闭环——普通 TDD 任务至少一个同 TEST 先 RED（expected_failure）后 GREEN（expected_success）配对且每个声明 TEST 都有 GREEN；特征化任务（no_tdd_reason:characterization）可用 characterization_pass 作为通过证据，不要求 RED；测试运行证据应包含测试 ID（test_id）、命令（command）、工作目录（cwd）、退出码（exit_code）、语义状态（semantic_status）；审查修复的回归测试运行可用回归覆盖任务列表（covers_task_ids）说明覆盖了哪些已完成任务；缺少任务尝试 ID（attempt_id）的旧证据只能弱引用。` +
+                            (packetContext?.code_state_check
+                                ? `本工作项带代码状态检查（code_state_check）：head_matches 为 false 或 changed_paths 非空表示代码审查后代码又发生变化，须在报告中列出差异并交主流程与用户裁决，不自行判定无害，也不据此自动否定已接受的代码审查。`
+                                : "")
                         : requiresReviewer(job.role)
                             ? `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}`
                             : `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]}`),

package/dist/review.d.ts

@@ -13,5 +13,6 @@ export declare function reviewBoundFiles(changeRoot: string): Ref[];
 export declare function reviewEvidenceDigest(events: Event[]): string;
 export declare function boundFilesStaleReason(job: Job, changeRoot: string): string | null;
 export declare function reviewEvidenceStaleReason(job: Job, currentDigest: string): string | null;
-export declare function reviewVerifierStaleReason(job: Job, changeRoot: string, currentEvidenceDigest: string): string | null;
-export declare function isFreshReviewVerifier(job: Job, changeRoot: string, currentEvidenceDigest: string): boolean;
+export declare function codeStateCheckStaleReason(job: Job, projectRoot: string | undefined, events: Event[] | undefined, ignoredCodePaths?: string[]): string | null;
+export declare function reviewVerifierStaleReason(job: Job, changeRoot: string, currentEvidenceDigest: string, projectRoot?: string, events?: Event[], ignoredCodePaths?: string[]): string | null;
+export declare function isFreshReviewVerifier(job: Job, changeRoot: string, currentEvidenceDigest: string, projectRoot?: string, events?: Event[]): boolean;

package/dist/review.js

@@ -1,11 +1,14 @@
 // SuperSpec review helpers: policy, verifier freshness, evidence digest
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { sha256File, sha256Text } from "./store.js";
+import { docRef, sha256File, sha256Text } from "./store.js";
+import { REVIEW_FINAL_VERIFIER_GATE } from "./review_job_gates.js";
+import { computeCodeStateCheck, effectiveCoverageExemptionRefsFromEvents } from "./code_review.js";
 export const REVIEW_DOC_PATHS = [
     "proposal.md",
     "tasks.md",
     "design.md",
+    "specs/",
     ".superspec/artifacts/discovery.md",
     ".superspec/artifacts/business-invariants.md",
     ".superspec/artifacts/test-contract.md",
@@ -52,35 +55,24 @@ export function readReviewPolicyFromEvents(events) {
     return null;
 }
 export function isReviewReadyVerifier(job) {
-    return job.role === "verifier" && job.created_from_transition === "review-ready";
+    return job.role === "verifier" && REVIEW_FINAL_VERIFIER_GATE.isJobForGate(job);
 }
 export function reviewBoundFiles(changeRoot) {
+    // 目录路径（以 / 结尾）始终绑定聚合指纹，与 boundFilesStaleReason 的 docRef 比对保持一致
     return REVIEW_DOC_PATHS
-        .filter(path => existsSync(join(changeRoot, path)))
-        .map(path => ({ path, sha: sha256File(join(changeRoot, path)) ?? "sha256:missing" }));
+        .filter(path => path.endsWith("/") || existsSync(join(changeRoot, path)))
+        .map(path => docRef(changeRoot, path));
 }
+// 方案排序键：kind → task_id → test_id → attempt_id → event_id；缺失字段按空字符串。
+// event_id 全局唯一，作为末位排序键足以保证稳定。
 function evidenceSortKey(record) {
-    const parts = [
+    return [
         record.kind,
         record.task_id ?? "",
-        record.attempt_id ?? "",
-        record.task_structure_digest ?? "",
         record.test_id ?? "",
-        record.semantic_status ?? "",
-    ];
-    if (record.covers_task_ids && record.covers_task_ids.length > 0) {
-        parts.push(`covers:${JSON.stringify(record.covers_task_ids)}`);
-    }
-    parts.push(record.command ?? "", record.cwd ?? "", record.exit_code == null ? "" : String(record.exit_code), record.target_fingerprint ?? "", record.event_digest);
-    return parts.join("\u0000");
-}
-function normalizedCoveredTaskIds(value) {
-    if (!Array.isArray(value))
-        return [];
-    return [...new Set(value
-            .filter((item) => typeof item === "string")
-            .map(item => item.trim())
-            .filter(Boolean))].sort();
+        record.attempt_id ?? "",
+        record.event_id ?? "",
+    ].join("\u0000");
 }
 export function reviewEvidenceDigest(events) {
     const attemptsById = new Map();
@@ -99,6 +91,7 @@ export function reviewEvidenceDigest(events) {
                 task_id: payload.task_id,
                 attempt_id: payload.attempt_id,
                 task_structure_digest: attempt?.task_structure_digest ?? null,
+                event_id: ev.event_id,
                 event_digest: ev.event_digest,
             });
         }
@@ -107,11 +100,12 @@ export function reviewEvidenceDigest(events) {
     const completedStructureDigests = new Set(completed
         .map(item => item.task_structure_digest)
         .filter((digest) => typeof digest === "string" && digest.length > 0));
+    // scope_note / boundary_snapshot / checkbox_update 属于 task_completed 事件 payload，已由 event_digest 覆盖
     const records = completed.map(item => ({
         kind: "task_completed",
         task_id: item.task_id,
         attempt_id: item.attempt_id,
-        task_structure_digest: item.task_structure_digest,
+        event_id: item.event_id,
         event_digest: item.event_digest,
     }));
     for (const ev of events) {
@@ -124,18 +118,41 @@ export function reviewEvidenceDigest(events) {
         const matchesLegacyDigest = attemptId == null && structureDigest != null && completedStructureDigests.has(structureDigest);
         if (!matchesCompletedAttempt && !matchesLegacyDigest)
             continue;
-        const coversTaskIds = normalizedCoveredTaskIds(payload.covers_task_ids);
         records.push({
             kind: "test_run_recorded",
             test_id: typeof payload.test_id === "string" ? payload.test_id : null,
             attempt_id: attemptId,
-            task_structure_digest: structureDigest,
             semantic_status: typeof payload.semantic_status === "string" ? payload.semantic_status : null,
-            ...(coversTaskIds.length > 0 ? { covers_task_ids: coversTaskIds } : {}),
+            exit_code: typeof payload.exit_code === "number" ? payload.exit_code : null,
             command: typeof payload.command === "string" ? payload.command : "",
             cwd: typeof payload.cwd === "string" ? payload.cwd : "",
-            exit_code: typeof payload.exit_code === "number" ? payload.exit_code : null,
-            target_fingerprint: typeof payload.target_fingerprint === "string" ? payload.target_fingerprint : null,
+            event_id: ev.event_id,
+            event_digest: ev.event_digest,
+        });
+    }
+    for (const ref of effectiveCoverageExemptionRefsFromEvents(events)) {
+        records.push({
+            kind: "coverage_exemption",
+            test_id: ref.test_id,
+            event_id: ref.event_id,
+            event_digest: ref.event_digest,
+        });
+    }
+    for (const ev of events) {
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition !== "review-ready" || payload.from_state !== "apply_done" || payload.to_state !== "review")
+            continue;
+        const gate = payload.code_review_gate;
+        if (!gate || (gate.decision !== "passed" && gate.decision !== "skipped"))
+            continue;
+        records.push({
+            kind: "code_review_gate",
+            decision: gate.decision,
+            job_id: typeof gate.job_id === "string" ? gate.job_id : null,
+            packet_digest: typeof gate.packet_digest === "string" ? gate.packet_digest : null,
+            event_id: ev.event_id,
             event_digest: ev.event_digest,
         });
     }
@@ -144,7 +161,8 @@ export function reviewEvidenceDigest(events) {
 }
 export function boundFilesStaleReason(job, changeRoot) {
     for (const bf of job.boundFiles) {
-        const current = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
+        // 目录绑定（path 以 / 结尾）比对聚合指纹，覆盖目录内文件的增/删/改
+        const current = docRef(changeRoot, bf.path).sha;
         if (current !== bf.sha) {
             return `绑定文件 ${bf.path} 已变化（${bf.sha} → ${current}）`;
         }
@@ -161,9 +179,24 @@ export function reviewEvidenceStaleReason(job, currentDigest) {
     }
     return null;
 }
-export function reviewVerifierStaleReason(job, changeRoot, currentEvidenceDigest) {
-    return boundFilesStaleReason(job, changeRoot) ?? reviewEvidenceStaleReason(job, currentEvidenceDigest);
+export function codeStateCheckStaleReason(job, projectRoot, events, ignoredCodePaths = []) {
+    if (!isReviewReadyVerifier(job))
+        return null;
+    if (!job.packet_context?.code_state_check)
+        return null;
+    if (!projectRoot || !events)
+        return null;
+    const current = computeCodeStateCheck(projectRoot, events, ignoredCodePaths);
+    if (JSON.stringify(current) !== JSON.stringify(job.packet_context.code_state_check)) {
+        return "最终验证工作项的代码状态事实已变化";
+    }
+    return null;
+}
+export function reviewVerifierStaleReason(job, changeRoot, currentEvidenceDigest, projectRoot, events, ignoredCodePaths = []) {
+    return boundFilesStaleReason(job, changeRoot)
+        ?? reviewEvidenceStaleReason(job, currentEvidenceDigest)
+        ?? codeStateCheckStaleReason(job, projectRoot, events, ignoredCodePaths);
 }
-export function isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest) {
-    return isReviewReadyVerifier(job) && reviewVerifierStaleReason(job, changeRoot, currentEvidenceDigest) == null;
+export function isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest, projectRoot, events) {
+    return isReviewReadyVerifier(job) && reviewVerifierStaleReason(job, changeRoot, currentEvidenceDigest, projectRoot, events) == null;
 }

package/dist/review_job_gates.d.ts

@@ -0,0 +1,20 @@
+import type { ReviewRisk } from "./review.ts";
+import type { Job, JobRole, ReviewJobGateId, Snapshot } from "./types.ts";
+export interface ReviewGateRule {
+    gate_id: ReviewJobGateId;
+    created_from_transition: "explore" | "propose-ready" | "review-ready";
+    allowedRoles: JobRole[];
+    reviewedDocPaths: string[];
+    requiredRolesForRisk(risk: ReviewRisk): JobRole[];
+    matchesOldJob(job: Job): boolean;
+    isJobForGate(job: Job): boolean;
+    openJobsForGate(snapshot: Snapshot): Job[];
+}
+export declare const EXPLORE_DISCOVERY_REVIEW_GATE_ID: "explore.discovery_review";
+export declare const PROPOSE_FINAL_REVIEW_GATE_ID: "propose.final_review";
+export declare const REVIEW_CODE_REVIEW_GATE_ID: "review.code_review";
+export declare const REVIEW_FINAL_VERIFIER_GATE_ID: "review.final_verifier";
+export declare const EXPLORE_DISCOVERY_REVIEW_GATE: ReviewGateRule;
+export declare const PROPOSE_FINAL_REVIEW_GATE: ReviewGateRule;
+export declare const REVIEW_CODE_REVIEW_GATE: ReviewGateRule;
+export declare const REVIEW_FINAL_VERIFIER_GATE: ReviewGateRule;

package/dist/review_job_gates.js

@@ -0,0 +1,85 @@
+import { reviewRolesForGate } from "./workflow_profile.js";
+function makeReviewGateRule(input) {
+    const gate = {
+        ...input,
+        isJobForGate(job) {
+            if (!input.allowedRoles.includes(job.role))
+                return false;
+            if (job.gate_id)
+                return job.gate_id === input.gate_id;
+            return input.matchesOldJob(job);
+        },
+        openJobsForGate(snapshot) {
+            return snapshot.open_jobs.filter(job => gate.isJobForGate(job));
+        },
+    };
+    return gate;
+}
+export const EXPLORE_DISCOVERY_REVIEW_GATE_ID = "explore.discovery_review";
+export const PROPOSE_FINAL_REVIEW_GATE_ID = "propose.final_review";
+export const REVIEW_CODE_REVIEW_GATE_ID = "review.code_review";
+export const REVIEW_FINAL_VERIFIER_GATE_ID = "review.final_verifier";
+const EXPLORE_DISCOVERY_REVIEW_ROLES = ["critic"];
+const PROPOSAL_REVIEW_ROLES = ["critic", "architect", "test-engineer"];
+const PROPOSAL_REVIEW_ROLE_SET = new Set(PROPOSAL_REVIEW_ROLES);
+const REVIEW_CODE_REVIEW_ROLES = ["code-reviewer"];
+const REVIEW_FINAL_VERIFIER_ROLES = ["verifier"];
+export const EXPLORE_DISCOVERY_REVIEW_GATE = makeReviewGateRule({
+    gate_id: EXPLORE_DISCOVERY_REVIEW_GATE_ID,
+    created_from_transition: "explore",
+    allowedRoles: EXPLORE_DISCOVERY_REVIEW_ROLES,
+    reviewedDocPaths: [".superspec/artifacts/discovery.md"],
+    requiredRolesForRisk(risk) {
+        return reviewRolesForGate(EXPLORE_DISCOVERY_REVIEW_GATE_ID, risk);
+    },
+    matchesOldJob(job) {
+        return job.created_from_transition === "explore" && job.role === "critic";
+    },
+});
+export const PROPOSE_FINAL_REVIEW_GATE = makeReviewGateRule({
+    gate_id: PROPOSE_FINAL_REVIEW_GATE_ID,
+    created_from_transition: "propose-ready",
+    allowedRoles: PROPOSAL_REVIEW_ROLES,
+    reviewedDocPaths: [
+        "proposal.md",
+        "tasks.md",
+        "design.md",
+        "specs/",
+        ".superspec/artifacts/discovery.md",
+        ".superspec/artifacts/business-invariants.md",
+        ".superspec/artifacts/test-contract.md",
+    ],
+    requiredRolesForRisk(risk) {
+        return reviewRolesForGate(PROPOSE_FINAL_REVIEW_GATE_ID, risk);
+    },
+    matchesOldJob(job) {
+        return job.created_from_transition === "propose-ready" && PROPOSAL_REVIEW_ROLE_SET.has(job.role);
+    },
+});
+export const REVIEW_CODE_REVIEW_GATE = makeReviewGateRule({
+    gate_id: REVIEW_CODE_REVIEW_GATE_ID,
+    created_from_transition: "review-ready",
+    allowedRoles: REVIEW_CODE_REVIEW_ROLES,
+    reviewedDocPaths: [],
+    requiredRolesForRisk(risk) {
+        return reviewRolesForGate(REVIEW_CODE_REVIEW_GATE_ID, risk);
+    },
+    matchesOldJob(job) {
+        return job.created_from_transition === "review-ready" && job.role === "code-reviewer";
+    },
+});
+export const REVIEW_FINAL_VERIFIER_GATE = makeReviewGateRule({
+    gate_id: REVIEW_FINAL_VERIFIER_GATE_ID,
+    created_from_transition: "review-ready",
+    allowedRoles: REVIEW_FINAL_VERIFIER_ROLES,
+    reviewedDocPaths: [],
+    requiredRolesForRisk(risk) {
+        return reviewRolesForGate(REVIEW_FINAL_VERIFIER_GATE_ID, risk);
+    },
+    matchesOldJob(job) {
+        return job.created_from_transition === "review-ready" &&
+            job.role === "verifier" &&
+            typeof job.review_evidence_digest === "string" &&
+            job.review_evidence_digest.length > 0;
+    },
+});

package/dist/store.d.ts

@@ -17,6 +17,16 @@ export declare function jobsDir(projectRoot: string, change: string): string;
 export declare function ensureChangeLayout(projectRoot: string, change: string): void;
 export declare function sha256Text(text: string): string;
 export declare function sha256File(filePath: string): string | null;
+/**
+ * 递归列出目录下全部 .md 文件（相对路径，确定性顺序：逐层排序的深度优先）。
+ * 目录缺失返回空数组；symlink、并发删除的条目跳过（不参与聚合），
+ * 避免 specs/ 出现异常项时打断 rebuildSnapshot 的所有调用方。
+ */
+export declare function listMarkdownFiles(dirPath: string): string[];
+/** 目录聚合指纹：排序后的相对路径 + 逐文件内容 sha，只聚合 .md（临时/系统文件不参与）；增/删/改任一 .md 都会变化。目录缺失或为空返回稳定空指纹 */
+export declare function sha256Dir(dirPath: string): string;
+/** 文档引用：路径以 / 结尾按目录聚合指纹绑定，其余按单文件 sha */
+export declare function docRef(root: string, path: string): Ref;
 export declare function computeDocumentDigests(changeRoot: string, docPaths: string[]): Record<string, string>;
 export declare function digestOf(obj: unknown): string;
 export declare function appendEvent(projectRoot: string, change: string, event: Event): void;

package/dist/store.js

@@ -1,6 +1,6 @@
 // SuperSpec 流程引擎 — 存储层：路径、指纹、事件日志、快照、锁
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, openSync, closeSync, unlinkSync, statSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, openSync, closeSync, unlinkSync, statSync, lstatSync, renameSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { hostname } from "node:os";
 // ===== 路径 =====
@@ -48,11 +48,61 @@ export function sha256File(filePath) {
         return null;
     return "sha256:" + createHash("sha256").update(readFileSync(filePath)).digest("hex");
 }
+/**
+ * 递归列出目录下全部 .md 文件（相对路径，确定性顺序：逐层排序的深度优先）。
+ * 目录缺失返回空数组；symlink、并发删除的条目跳过（不参与聚合），
+ * 避免 specs/ 出现异常项时打断 rebuildSnapshot 的所有调用方。
+ */
+export function listMarkdownFiles(dirPath) {
+    const out = [];
+    const lstatOrNull = (p) => { try {
+        return lstatSync(p);
+    }
+    catch {
+        return null;
+    } };
+    const walk = (dir, prefix) => {
+        const dirStat = lstatOrNull(dir);
+        if (!dirStat?.isDirectory() || dirStat.isSymbolicLink())
+            return;
+        let names;
+        try {
+            names = readdirSync(dir).sort();
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const full = join(dir, name);
+            const rel = prefix ? `${prefix}/${name}` : name;
+            const st = lstatOrNull(full);
+            if (!st || st.isSymbolicLink())
+                continue;
+            if (st.isDirectory())
+                walk(full, rel);
+            else if (name.endsWith(".md"))
+                out.push(rel);
+        }
+    };
+    walk(dirPath, "");
+    return out;
+}
+/** 目录聚合指纹：排序后的相对路径 + 逐文件内容 sha，只聚合 .md（临时/系统文件不参与）；增/删/改任一 .md 都会变化。目录缺失或为空返回稳定空指纹 */
+export function sha256Dir(dirPath) {
+    const entries = listMarkdownFiles(dirPath)
+        .map(rel => `${rel}\u0000${sha256File(join(dirPath, rel)) ?? "sha256:missing"}`);
+    return sha256Text(entries.join("\n"));
+}
+/** 文档引用：路径以 / 结尾按目录聚合指纹绑定，其余按单文件 sha */
+export function docRef(root, path) {
+    if (path.endsWith("/"))
+        return { path, sha: sha256Dir(join(root, path)) };
+    return { path, sha: sha256File(join(root, path)) ?? "sha256:missing" };
+}
 export function computeDocumentDigests(changeRoot, docPaths) {
     const digests = {};
     for (const p of docPaths) {
-        const full = join(changeRoot, p);
-        digests[p] = sha256File(full) ?? "sha256:missing";
+        digests[p] = docRef(changeRoot, p).sha;
     }
     return digests;
 }

package/dist/sync.js

@@ -2,10 +2,10 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { readEvents, eventsDigest, computeDocumentDigests, sha256Text, ensureChangeLayout, } from "./store.js";
-import { reviewEvidenceDigest, reviewVerifierStaleReason } from "./review.js";
-import { codeReviewJobStaleReason } from "./code_review.js";
+import { reviewEvidenceDigest } from "./review.js";
+import { invalidReasonForSnapshot } from "./job_validity.js";
 const TRACKED_DOCS = [
-    "proposal.md", "design.md", "tasks.md",
+    "proposal.md", "design.md", "tasks.md", "specs/",
     ".superspec/artifacts/discovery.md",
     ".superspec/artifacts/business-invariants.md",
     ".superspec/artifacts/test-contract.md",
@@ -81,12 +81,10 @@ function replayEvents(events) {
     return { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition };
 }
 /** 粗粒度失效：检查 job 的 boundFiles 是否仍匹配当前文档 */
-function checkStaleJobs(jobs, projectRoot, changeRoot, currentReviewEvidenceDigest) {
+function checkStaleJobs(jobs, projectRoot, changeRoot, events, currentReviewEvidenceDigest) {
     const stale = [];
     for (const job of jobs) {
-        const reason = job.role === "code-reviewer"
-            ? codeReviewJobStaleReason(projectRoot, job)
-            : reviewVerifierStaleReason(job, changeRoot, currentReviewEvidenceDigest);
+        const reason = invalidReasonForSnapshot({ job, projectRoot, changeRoot, events, currentReviewEvidenceDigest });
         if (reason) {
             stale.push({ job_id: job.job_id, reason });
         }
@@ -114,8 +112,8 @@ export function rebuildSnapshot(projectRoot, change, changeRoot, openspecStatusD
     const currentReviewEvidenceDigest = reviewEvidenceDigest(events);
     // 粗粒度失效检查（只读，不写事件）：open code-reviewer job 防止提交过期报告；
     // accepted code-reviewer pass 不做持续 freshness gate，避免 apply_done 循环重审。
-    const staleOpenInfo = checkStaleJobs(openJobs, projectRoot, changeRoot, currentReviewEvidenceDigest);
-    const staleAcceptedInfo = checkStaleJobs(acceptedJobs.filter(j => j.role !== "code-reviewer"), projectRoot, changeRoot, currentReviewEvidenceDigest);
+    const staleOpenInfo = checkStaleJobs(openJobs, projectRoot, changeRoot, events, currentReviewEvidenceDigest);
+    const staleAcceptedInfo = checkStaleJobs(acceptedJobs.filter(j => j.role !== "code-reviewer"), projectRoot, changeRoot, events, currentReviewEvidenceDigest);
     const freshOpen = openJobs
         .filter(j => !staleOpenInfo.some(s => s.job_id === j.job_id))
         .filter(j => j.role !== "code-reviewer" || state === "apply_done");