@peterxiaoyang/superspec 0.1.43 → 0.1.45

package/dist/record.js

@@ -4,11 +4,11 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, sha256Text, withLock, appendRawRecord, } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
 import { changeRoot as openspecChangeRoot } from "./openspec.js";
-import { isPhaseConfirmationScope, phaseActionForAnswer, phaseConfirmationForCurrentState, } from "./phase_confirmation.js";
+import { isPhaseConfirmationScope, phaseActionForAnswer, phaseConfirmationForCurrentState, workflowRiskForPhaseConfirmation, } from "./phase_confirmation.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";
+import { REVIEW_DOC_PATHS, REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX, REVIEW_REJECTION_OVERRIDE_ANSWER, parseReviewRejectionOverrideScope, reviewGateRoleResolution, reviewRejectionOverrideScope, } from "./review.js";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
 import { RecordInputDecodingError, readRecordInputFile } from "./record_input.js";
 const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
@@ -90,14 +90,14 @@ function reviewScopeInstruction(job, reviewTargets, readOnlyRefs) {
     }
     const targets = reviewTargets.length > 0 ? `本 gate 可提出修改建议的审查目标为 ${reviewTargets.join(", ")}。` : "";
     const refs = readOnlyRefs.length > 0
-        ? `只读上游引用为 ${readOnlyRefs.join(", ")}；只允许读取和核对一致性，不得要求在当前阶段修改、追加、删除、重排或格式化这些文件，不得把修改只读引用列为本阶段 required fix。只读引用自身的缺失、错误或矛盾可在 risks 或 open_questions 中上报给主流程，但不得单独作为本 gate 的 fail。只有能定位到审查目标的不一致，才能作为 fail 并指向该审查目标的修复。`
+        ? `只读上游引用为 ${readOnlyRefs.join(", ")}；只允许读取和核对一致性，不得要求在当前阶段修改、追加、删除、重排或格式化这些文件。只读引用中与本次目标或绑定上游事实无直接因果关系的历史质量问题不得作为本 gate 的 fail。如果本次审查目标或 boundFiles 中绑定的上游事实直接造成变更包跨文档不一致，并且会影响明确验收或实施落地，可以 fail；finding 必须锚定为当前变更包未完成一致性闭环，required outcome 只要求消除矛盾，不得指定必须修改哪份文档或采用哪种技术方案。`
         : "";
     return targets + refs;
 }
 function reviewCoverageInstruction(job) {
     if (!requiresReviewScope(job))
         return "";
-    return `审查顺序固定为：先建立覆盖索引，按文件和标题/行段完整浏览全部 boundFiles 至文件末尾；长文档必须分段读取，不能在发现第一个 blocker 时停止覆盖。完整读取只用于核对本次 change 的目标、直接修改及跨文档一致性，不等于允许重新审计全部历史设计。若 proposal.md 存在“需求变化”，以其中记录的受影响能力、直接修改章节和保持不变范围作为本轮增量审查的权威锚点；本轮新 finding 必须由该需求变化、为接入变化所做的直接修改，或这些修改造成的跨文档矛盾引起，并说明因果链。此前已通过且被明确记录为保持不变的设计不得重新打开为 blocker；不要凭通用风险类别猜测变化范围。注意事项和故障类别是条件式检查项，不是必须穷举的清单。Recommendation 只能描述需要补足的结果、契约或证据，不得把未经 proposal、design 或用户决定选定的新基础设施写成 required fix。报告中的 review_scope.checked_paths 必须列出全部已浏览的 boundFiles；它只是覆盖回执，不能代替语义审查，也不扩大可报告问题的范围。`;
+    return `审查顺序固定为：先建立覆盖索引，按文件和标题/行段完整浏览全部 boundFiles 至文件末尾；长文档必须分段读取，不能在发现第一个 blocker 时停止覆盖。read_only_refs 按本次问题需要读取，用于核对目标与上下游一致性，不要求机械全文遍历或写入 checked_paths。完整读取只用于核对本次 change 的目标、直接修改及跨文档一致性，不等于允许重新审计全部历史设计。若 proposal.md 存在“需求变化”，以其中记录的受影响能力、直接修改章节和保持不变范围作为本轮增量审查的权威锚点；本轮新 finding 必须由该需求变化、为接入变化所做的直接修改，或这些修改造成的跨文档矛盾引起，并说明因果链。此前已通过且被明确记录为保持不变的设计不得重新打开为 blocker；不要凭通用风险类别猜测变化范围。注意事项和故障类别是条件式检查项，不是必须穷举的清单。Recommendation 只能描述需要补足的结果、契约或证据，不得把未经 proposal、design 或用户决定选定的新基础设施写成 required fix。报告中的 review_scope.checked_paths 必须列出全部已浏览的 boundFiles；它只是覆盖回执，不能代替语义审查，也不扩大可报告问题的范围。`;
 }
 function migrationEvidenceInstruction(job) {
     const isProposeReview = PROPOSE_FINAL_REVIEW_GATE.isJobForGate(job);
@@ -321,6 +321,21 @@ function findJob(events, jobId) {
     }
     return null;
 }
+function ordinaryReviewGateForJob(job) {
+    return [EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE]
+        .find(gate => gate.isJobForGate(job)) ?? null;
+}
+function invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, decision, reason, message) {
+    appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", {
+        accepted: false,
+        scope: decision.scope,
+        answer: decision.answer,
+        ...(decision.decision_source !== undefined ? { decision_source: decision.decision_source } : {}),
+        reason,
+        input_digest: inputDigest,
+    }));
+    return { event_type: "user_decision_recorded", accepted: false, message };
+}
 /** 检查 job 是否已终态 */
 function jobTerminalState(events, jobId) {
     for (const ev of events) {
@@ -331,6 +346,10 @@ function jobTerminalState(events, jobId) {
     }
     return null;
 }
+function jobInvalidated(events, jobId) {
+    return events.some(ev => ev.event_type === "job_invalidated" &&
+        ev.payload.job_id === jobId);
+}
 function terminalJobSubmitResult(events, jobId, terminal, reportDigest) {
     const existing = events.find(e => (e.event_type === "job_accepted" || e.event_type === "job_rejected")
         && e.payload.job_id === jobId
@@ -532,6 +551,9 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
         if (!job) {
             return { event_type: "job_rejected", accepted: false, message: `工作项 ${jobId} 不存在` };
         }
+        if (jobInvalidated(events, jobId)) {
+            return { accepted: false, message: `工作项 ${jobId} 已因回退到更早阶段失效，不接受新报告。` };
+        }
         const terminal = jobTerminalState(events, jobId);
         if (terminal) {
             const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
@@ -569,6 +591,9 @@ export function recordJobSubmitContent(projectRoot, change, changeRoot, jobId, r
         if (!job) {
             return { event_type: "job_rejected", accepted: false, message: `工作项 ${jobId} 不存在` };
         }
+        if (jobInvalidated(events, jobId)) {
+            return { accepted: false, message: `工作项 ${jobId} 已因回退到更早阶段失效，不接受新报告。` };
+        }
         const reportDigest = sha256Text(reportContent);
         const terminal = jobTerminalState(events, jobId);
         if (terminal) {
@@ -610,6 +635,7 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
     }
     let phaseConfirmation = null;
     let phaseAction = null;
+    let phaseReviewRisk = null;
     if (isPhaseConfirmationScope(decision.scope)) {
         const existingAccepted = existing &&
             existing.payload.accepted !== false;
@@ -623,7 +649,9 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         });
         const changeRoot = openspecChangeRoot(projectRoot, change);
         const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
-        const current = phaseConfirmationForCurrentState(projectRoot, events, snapshot);
+        // mode 是状态机从配置/round 快照推导的输入，不接受 user-decision JSON 注入。
+        const decisionRisk = workflowRiskForPhaseConfirmation(projectRoot, events, snapshot);
+        const current = phaseConfirmationForCurrentState(projectRoot, events, snapshot, decisionRisk);
         if (existingAccepted &&
             current?.scope === decision.scope &&
             latestAcceptedForScope?.event_id === existing.event_id) {
@@ -669,6 +697,7 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         }
         phaseConfirmation = current;
         phaseAction = action;
+        phaseReviewRisk = decisionRisk;
     }
     if (existing && !phaseAction) {
         const accepted = existing.payload.accepted !== false;
@@ -678,6 +707,59 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
             message: accepted ? "幂等返回：同一用户决策已登记" : "幂等返回：同一无效用户决策已登记",
         };
     }
+    let reviewRejectionOverride = null;
+    let reviewRejectionDecisionSource = null;
+    if (decision.scope.startsWith(REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX)) {
+        const jobId = parseReviewRejectionOverrideScope(decision.scope);
+        if (!jobId) {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "invalid_review_rejection_override_scope", "审查拒绝裁决 scope 必须包含有效 job ID");
+        }
+        if (decision.scope !== reviewRejectionOverrideScope(jobId)) {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "invalid_review_rejection_override_scope", `审查拒绝裁决 scope 必须精确为 ${reviewRejectionOverrideScope(jobId)}`);
+        }
+        if (decision.answer !== REVIEW_REJECTION_OVERRIDE_ANSWER) {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "invalid_review_rejection_override_answer", `审查拒绝裁决 answer 必须是 ${REVIEW_REJECTION_OVERRIDE_ANSWER}`);
+        }
+        if (decision.decision_source !== "main_process" && decision.decision_source !== "user") {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "invalid_review_rejection_override_source", "审查拒绝裁决 decision_source 必须是 main_process 或 user");
+        }
+        if (!nonEmptyString(decision.reason)) {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "missing_review_rejection_override_reason", "审查拒绝裁决必须写明原因");
+        }
+        const job = findJob(events, jobId);
+        const gate = job ? ordinaryReviewGateForJob(job) : null;
+        if (!job || !gate || !isOrdinaryReviewer(job.role)) {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "review_rejection_override_job_not_found", "审查拒绝裁决必须指向当前 Explore / Propose gate 的普通 Reviewer job");
+        }
+        const changeRoot = openspecChangeRoot(projectRoot, change);
+        const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
+        const gateIsCurrent = gate.gate_id === EXPLORE_DISCOVERY_REVIEW_GATE.gate_id
+            ? snapshot.state === "explore"
+            : snapshot.state === "propose" || snapshot.state === "propose_ready";
+        if (!gateIsCurrent) {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "review_rejection_override_gate_not_current", "审查拒绝裁决只能在对应 Explore / Propose gate 仍为当前阶段时登记");
+        }
+        const resolution = reviewGateRoleResolution(events, changeRoot, gate, job.role);
+        if (resolution.kind === "none" || resolution.terminal.job.job_id !== job.job_id) {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "review_rejection_override_not_latest_terminal", "审查拒绝裁决只能指向当前 gate cycle 中该角色最新的 terminal job");
+        }
+        if (resolution.kind === "stale") {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "stale_review_rejection_override_job", `审查拒绝裁决指向的 job 已过期：${resolution.stale_reason}`);
+        }
+        if (resolution.kind === "accepted") {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "review_rejection_override_job_not_rejected", "审查拒绝裁决只能指向 rejected job");
+        }
+        if (resolution.kind === "rejected_invalid") {
+            return invalidReviewRejectionOverrideResult(projectRoot, change, inputDigest, { scope: decision.scope, answer: decision.answer, decision_source: decision.decision_source }, "review_rejection_override_not_review_failed", "只有 result_kind=review_failed 的拒绝报告可以裁决；无效报告必须修正后重新提交");
+        }
+        reviewRejectionOverride = {
+            job_id: job.job_id,
+            role: job.role,
+            gate_id: gate.gate_id,
+            packet_digest: job.packet_digest,
+        };
+        reviewRejectionDecisionSource = decision.decision_source;
+    }
     if (decision.scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX)) {
         const normalizedAnswer = normalizeCodeReviewDecisionAnswer(decision.answer);
         if (!normalizedAnswer) {
@@ -721,10 +803,13 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
             ? phaseAction.label
             : normalizedAnswer ? codeReviewDecisionAnswerLabel(normalizedAnswer) : decision.answer,
         ...(typeof decision.reason === "string" ? { reason: decision.reason.trim() } : {}),
+        ...(reviewRejectionDecisionSource ? { decision_source: reviewRejectionDecisionSource } : {}),
+        ...(reviewRejectionOverride ? { review_rejection_override: reviewRejectionOverride } : {}),
         ...(phaseAction ? {
             phase_confirmation: {
                 boundary: phaseAction.boundary,
                 decision: phaseAction.decision,
+                review_risk: phaseReviewRisk ?? "strict",
             },
         } : {}),
     };
@@ -773,7 +858,7 @@ export function recordUserDecisionContent(projectRoot, change, content) {
         return recordUserDecisionLoaded(projectRoot, change, events, content, sha256Text(content));
     });
 }
-/** jobs list（HIGH-1 修复：从 transition_commit.new_jobs 提取，不再依赖已删除的 job_requested 事件） */
+/** jobs list（job 从 transition_commit.new_jobs 提取；reopen 可用 job_invalidated 关闭未完成工作项） */
 export function jobsList(projectRoot, change) {
     const events = readEvents(projectRoot, change);
     const open = [];
@@ -804,6 +889,12 @@ export function jobsList(projectRoot, change) {
                 open.splice(idx, 1)[0];
             rejected.push({ job_id, role });
         }
+        else if (ev.event_type === "job_invalidated") {
+            const { job_id } = ev.payload;
+            const idx = open.findIndex(j => j.job_id === job_id);
+            if (idx >= 0)
+                open.splice(idx, 1);
+        }
     }
     return { open, accepted, rejected };
 }
@@ -814,8 +905,9 @@ function packetFieldDescriptions() {
         boundFiles: "本工作项绑定的文件清单；审查报告必须说明这些文件是否都看过。",
         review_scope: "报告中的审查覆盖范围；普通 reviewer/verifier 用 checked_paths 回执全部绑定文件，code-reviewer 还需按专用协议说明未检查项。",
         code_review_scope: "代码审查范围：从已审基点到当前 HEAD 的提交改动、工作区改动和未跟踪代码文件。",
-        task_execution_index: "按任务汇总的执行证据：每个任务（task）的执行依据、声明测试、测试证据和改动文件。",
-        contract: "任务启动时的执行依据快照：tests/design/source/reason/guard 分别对应 测试/设计/来源/原因/边界；null 表示历史任务没有执行依据。",
+        task_execution_index: "按任务汇总的执行证据：每个任务（task）的执行依据、有效证据要求、声明测试、测试证据和改动文件。",
+        contract: "任务启动时的执行依据快照：tests/design/source/acceptance/guard 分别对应 测试/设计/来源/验收/边界；null 表示历史任务没有执行依据。",
+        required_evidence: "task-start 结合冻结策略编译并写入 attempt 的有效证据要求：test_ids、red_required、green_required 和允许的 GREEN 语义状态；null 表示历史任务按旧记录回放。",
         changed_paths: "与某个任务（task）或代码状态检查相关的改动文件。",
         changed_paths_partial_reason: "该任务（task）的提交段 diff 失败原因；存在时 changed_paths 只包含工作区对比结果，归属可能不完整。",
         unattributed_paths: "代码审查范围中暂时无法归属到某个任务（task）的文件。",
@@ -890,10 +982,10 @@ export function jobsPacket(projectRoot, change, jobId) {
                     ? `最小格式：{"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 豁免。`
+                            ? `本工作项带任务执行索引（task_execution_index）：按 task 对照其执行依据快照（contract）审查——实现路线对照 design 引用原文、累计 diff 对照 guard 边界、测试断言对照 tests 声明的 scenario；每项的 required_evidence 是 task-start 冻结的证据口径，red_required/green_required 分别说明是否需要 RED/GREEN；每项的 scope_note 是执行者登记的范围扩大说明，判断其合理性与验证充分性；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动逐个判断合理性；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。`
                             : "")
                     : job.role === "verifier"
-                        ? `最小格式：{"role":"verifier","verdict":"pass|fail","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}。核对代码审查记录（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）的旧证据只能弱引用。` +
+                        ? `最小格式：{"role":"verifier","verdict":"pass|fail","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}。核对代码审查记录（code_review_gate）：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对代码审查问题闭环：实现修复任务必须带审查修复引用（review_fix_of:<job_id>#<problem_id>），方案/混合问题必须有用户决策或后续修复证据。按 task_execution_index 的 required_evidence 核对测试证据：red_required 时需要同一 TEST 的 RED（expected_failure）后 GREEN；green_required 时每个声明 TEST 都需要允许的 GREEN 语义状态；测试运行证据应包含测试 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 非空表示代码审查后代码又发生变化，须在报告中列出差异并交主流程与用户裁决，不自行判定无害，也不据此自动否定已接受的代码审查。`
                                 : "")

package/dist/review.d.ts

@@ -1,5 +1,5 @@
 import { type ReviewGateRule } from "./review_job_gates.ts";
-import type { Event, Job, JobRole, Ref, ReviewPreviousRejection } from "./types.ts";
+import type { CodeReviewResultKind, Event, Job, JobRole, Ref, ReviewPreviousRejection } from "./types.ts";
 export type ReviewRisk = "minimal" | "normal" | "strict";
 export interface ReviewPolicy {
     review_risk: ReviewRisk;
@@ -9,7 +9,54 @@ export declare const REVIEW_DOC_PATHS: string[];
 export declare function assertCommitPayloadExtension(payload: Record<string, unknown>): void;
 export declare function reviewPolicyForRisk(risk: ReviewRisk): ReviewPolicy;
 export declare function readReviewPolicyFromEvents(events: Event[]): ReviewPolicy | null;
+export declare const REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX = "review_rejection_override:";
+export declare const REVIEW_REJECTION_OVERRIDE_ANSWER = "do_not_block";
+export type ReviewRejectionDecisionSource = "main_process" | "user";
+export interface ReviewRejectionOverrideAudit {
+    job_id: string;
+    role: JobRole;
+    gate_id: ReviewGateRule["gate_id"];
+    packet_digest: string;
+    decision_source: ReviewRejectionDecisionSource;
+    reason: string;
+    decision_event_id: string;
+    decision_event_digest: string;
+}
+export declare function reviewRejectionOverrideScope(jobId: string): string;
+export declare function parseReviewRejectionOverrideScope(scope: string): string | null;
+export interface ReviewTerminalResult {
+    job: Job;
+    event: Event;
+    state: "accepted" | "rejected";
+    result_kind?: CodeReviewResultKind;
+    reason?: string;
+    findings?: unknown[];
+}
+export declare function latestReviewTerminalForGateRole(events: Event[], gate: ReviewGateRule, role: JobRole): ReviewTerminalResult | null;
+export declare function effectiveReviewRejectionOverride(events: Event[], gate: ReviewGateRule, terminal: ReviewTerminalResult): ReviewRejectionOverrideAudit | null;
+export type ReviewGateRoleResolution = {
+    kind: "none";
+} | {
+    kind: "stale";
+    terminal: ReviewTerminalResult;
+    stale_reason: string;
+} | {
+    kind: "accepted";
+    terminal: ReviewTerminalResult;
+} | {
+    kind: "rejected_invalid";
+    terminal: ReviewTerminalResult;
+} | {
+    kind: "rejected_pending";
+    terminal: ReviewTerminalResult;
+} | {
+    kind: "overridden";
+    terminal: ReviewTerminalResult;
+    override: ReviewRejectionOverrideAudit;
+};
+export declare function reviewGateRoleResolution(events: Event[], changeRoot: string, gate: ReviewGateRule, role: JobRole): ReviewGateRoleResolution;
 export declare function latestReviewHistoryForGateRole(events: Event[], gate: ReviewGateRule, role: JobRole): ReviewPreviousRejection | null;
+export declare function historicalProposeReadyRoles(events: Event[]): JobRole[];
 export declare function isReviewReadyVerifier(job: Job): boolean;
 export declare function reviewBoundFiles(changeRoot: string): Ref[];
 export declare function reviewEvidenceDigest(events: Event[]): string;

package/dist/review.js

@@ -2,7 +2,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { docRef, sha256File, sha256Text } from "./store.js";
-import { EXPLORE_DISCOVERY_REVIEW_GATE_ID, PROPOSE_FINAL_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE, } from "./review_job_gates.js";
+import { EXPLORE_DISCOVERY_REVIEW_GATE_ID, PROPOSE_FINAL_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE, } from "./review_job_gates.js";
 import { computeCodeStateCheck, effectiveCoverageExemptionRefsFromEvents } from "./code_review.js";
 export const REVIEW_DOC_PATHS = [
     "proposal.md",
@@ -10,7 +10,6 @@ export const REVIEW_DOC_PATHS = [
     "design.md",
     "specs/",
     ".superspec/artifacts/discovery.md",
-    ".superspec/artifacts/business-invariants.md",
     ".superspec/artifacts/test-contract.md",
 ];
 const CORE_COMMIT_FIELDS = new Set([
@@ -43,11 +42,27 @@ function isReviewPolicy(value) {
         typeof obj.requires_verifier === "boolean");
 }
 export function readReviewPolicyFromEvents(events) {
-    for (const ev of events) {
+    // 新格式在 start-apply 写入，并且只能读取最新 Apply round 的策略。
+    // 回退到该 round 内的 review-ready，是为了回放升级前的历史 event。
+    let latestStartApplyIndex = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        if (payload.transition === "start-apply" && payload.to_state === "apply") {
+            latestStartApplyIndex = i;
+            break;
+        }
+    }
+    if (latestStartApplyIndex < 0)
+        return null;
+    for (let i = events.length - 1; i >= latestStartApplyIndex; i--) {
+        const ev = events[i];
         if (ev.event_type !== "transition_commit")
             continue;
         const payload = ev.payload;
-        if (payload.transition !== "review-ready")
+        if (payload.transition !== "start-apply" && payload.transition !== "review-ready")
             continue;
         if (isReviewPolicy(payload.review_policy))
             return payload.review_policy;
@@ -59,6 +74,17 @@ function reviewResultKind(value) {
         ? value
         : null;
 }
+export const REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX = "review_rejection_override:";
+export const REVIEW_REJECTION_OVERRIDE_ANSWER = "do_not_block";
+export function reviewRejectionOverrideScope(jobId) {
+    return `${REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX}${jobId}`;
+}
+export function parseReviewRejectionOverrideScope(scope) {
+    if (!scope.startsWith(REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX))
+        return null;
+    const jobId = scope.slice(REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX.length).trim();
+    return jobId === "" ? null : jobId;
+}
 function reviewCycleState(gate) {
     if (gate.gate_id === EXPLORE_DISCOVERY_REVIEW_GATE_ID)
         return "explore";
@@ -109,6 +135,7 @@ function reviewTerminalResultsForGateRole(events, gate, role) {
         const findings = Array.isArray(payload.findings) ? payload.findings : undefined;
         results.push({
             job,
+            event,
             state: event.event_type === "job_accepted" ? "accepted" : "rejected",
             ...(event.event_type === "job_rejected"
                 ? { result_kind: reviewResultKind(payload.result_kind) ?? (findings ? "review_failed" : "invalid_report") }
@@ -119,6 +146,69 @@ function reviewTerminalResultsForGateRole(events, gate, role) {
     }
     return results;
 }
+export function latestReviewTerminalForGateRole(events, gate, role) {
+    return reviewTerminalResultsForGateRole(events, gate, role).at(-1) ?? null;
+}
+function validReviewRejectionOverridePayload(event, terminal, gate) {
+    if (event.event_type !== "user_decision_recorded")
+        return null;
+    const payload = event.payload;
+    if (payload.accepted !== true ||
+        payload.scope !== reviewRejectionOverrideScope(terminal.job.job_id) ||
+        payload.answer !== REVIEW_REJECTION_OVERRIDE_ANSWER ||
+        (payload.decision_source !== "main_process" && payload.decision_source !== "user") ||
+        typeof payload.reason !== "string" || payload.reason.trim() === "" ||
+        !payload.review_rejection_override ||
+        typeof payload.review_rejection_override !== "object" ||
+        Array.isArray(payload.review_rejection_override))
+        return null;
+    const audit = payload.review_rejection_override;
+    if (audit.job_id !== terminal.job.job_id ||
+        audit.role !== terminal.job.role ||
+        audit.gate_id !== gate.gate_id ||
+        audit.packet_digest !== terminal.job.packet_digest)
+        return null;
+    return {
+        job_id: terminal.job.job_id,
+        role: terminal.job.role,
+        gate_id: gate.gate_id,
+        packet_digest: terminal.job.packet_digest,
+        decision_source: payload.decision_source,
+        reason: payload.reason.trim(),
+        decision_event_id: event.event_id,
+        decision_event_digest: event.event_digest,
+    };
+}
+export function effectiveReviewRejectionOverride(events, gate, terminal) {
+    const cycleStartIndex = currentReviewGateCycleStart(events, gate);
+    if (cycleStartIndex == null)
+        return null;
+    const terminalIndex = events.findIndex(event => event.event_id === terminal.event.event_id);
+    if (terminalIndex < cycleStartIndex)
+        return null;
+    for (let i = events.length - 1; i > terminalIndex; i--) {
+        const audit = validReviewRejectionOverridePayload(events[i], terminal, gate);
+        if (audit)
+            return audit;
+    }
+    return null;
+}
+export function reviewGateRoleResolution(events, changeRoot, gate, role) {
+    const terminal = latestReviewTerminalForGateRole(events, gate, role);
+    if (!terminal)
+        return { kind: "none" };
+    const staleReason = boundFilesStaleReason(terminal.job, changeRoot);
+    if (staleReason)
+        return { kind: "stale", terminal, stale_reason: staleReason };
+    if (terminal.state === "accepted")
+        return { kind: "accepted", terminal };
+    if (terminal.result_kind !== "review_failed")
+        return { kind: "rejected_invalid", terminal };
+    const override = effectiveReviewRejectionOverride(events, gate, terminal);
+    return override
+        ? { kind: "overridden", terminal, override }
+        : { kind: "rejected_pending", terminal };
+}
 export function latestReviewHistoryForGateRole(events, gate, role) {
     const terminalResults = reviewTerminalResultsForGateRole(events, gate, role);
     const latest = terminalResults.at(-1);
@@ -156,6 +246,20 @@ export function latestReviewHistoryForGateRole(events, gate, role) {
         job_id: latest.job.job_id,
     };
 }
+export function historicalProposeReadyRoles(events) {
+    const roles = new Set();
+    for (const event of events) {
+        if (event.event_type !== "transition_commit")
+            continue;
+        const jobs = event.payload.new_jobs ?? [];
+        for (const job of jobs) {
+            if (PROPOSE_FINAL_REVIEW_GATE.isJobForGate(job) &&
+                (job.role === "critic" || job.role === "architect" || job.role === "test-engineer"))
+                roles.add(job.role);
+        }
+    }
+    return [...roles];
+}
 export function isReviewReadyVerifier(job) {
     return job.role === "verifier" && REVIEW_FINAL_VERIFIER_GATE.isJobForGate(job);
 }

package/dist/review_job_gates.d.ts

@@ -15,6 +15,11 @@ 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 function reviewScopeForGateRole(gate: ReviewGateRule, role: JobRole): {
+    reviewTargets: string[];
+    readOnlyRefs: string[];
+    boundPaths: string[];
+};
 export declare const EXPLORE_DISCOVERY_REVIEW_GATE: ReviewGateRule;
 export declare const PROPOSE_FINAL_REVIEW_GATE: ReviewGateRule;
 export declare const REVIEW_CODE_REVIEW_GATE: ReviewGateRule;

package/dist/review_job_gates.js

@@ -19,6 +19,58 @@ 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";
+function defaultReviewScope(gate) {
+    return {
+        reviewTargets: [...gate.reviewTargets],
+        readOnlyRefs: [...gate.readOnlyRefs],
+        boundPaths: [...new Set([...gate.reviewTargets, ...gate.readOnlyRefs])],
+    };
+}
+export function reviewScopeForGateRole(gate, role) {
+    if (gate.gate_id !== PROPOSE_FINAL_REVIEW_GATE_ID)
+        return defaultReviewScope(gate);
+    if (role === "critic") {
+        const reviewTargets = ["proposal.md", "specs/", "tasks.md"];
+        const readOnlyRefs = [
+            "design.md",
+            ".superspec/artifacts/test-contract.md",
+            ".superspec/artifacts/discovery.md",
+        ];
+        return {
+            reviewTargets,
+            readOnlyRefs,
+            boundPaths: [...reviewTargets, ".superspec/artifacts/discovery.md"],
+        };
+    }
+    if (role === "architect") {
+        const reviewTargets = ["design.md"];
+        return {
+            reviewTargets,
+            readOnlyRefs: [
+                "proposal.md",
+                "specs/",
+                "tasks.md",
+                ".superspec/artifacts/discovery.md",
+                ".superspec/artifacts/test-contract.md",
+            ],
+            boundPaths: [...reviewTargets],
+        };
+    }
+    if (role === "test-engineer") {
+        const reviewTargets = [".superspec/artifacts/test-contract.md", "tasks.md"];
+        return {
+            reviewTargets,
+            readOnlyRefs: [
+                "proposal.md",
+                "specs/",
+                "design.md",
+                ".superspec/artifacts/discovery.md",
+            ],
+            boundPaths: [...reviewTargets],
+        };
+    }
+    return defaultReviewScope(gate);
+}
 const EXPLORE_DISCOVERY_REVIEW_ROLES = ["critic"];
 const PROPOSAL_REVIEW_ROLES = ["critic", "architect", "test-engineer"];
 const PROPOSAL_REVIEW_ROLE_SET = new Set(PROPOSAL_REVIEW_ROLES);
@@ -46,7 +98,6 @@ export const PROPOSE_FINAL_REVIEW_GATE = makeReviewGateRule({
         "tasks.md",
         "design.md",
         "specs/",
-        ".superspec/artifacts/business-invariants.md",
         ".superspec/artifacts/test-contract.md",
     ],
     readOnlyRefs: [".superspec/artifacts/discovery.md"],

package/dist/sync.js

@@ -7,7 +7,6 @@ import { invalidReasonForSnapshot } from "./job_validity.js";
 const TRACKED_DOCS = [
     "proposal.md", "design.md", "tasks.md", "specs/",
     ".superspec/artifacts/discovery.md",
-    ".superspec/artifacts/business-invariants.md",
     ".superspec/artifacts/test-contract.md",
 ];
 /** 从 events.jsonl 推导：当前状态、jobs、attempts、pending decisions */
@@ -35,7 +34,8 @@ function replayEvents(events) {
                 }
                 break;
             }
-            // H4 修复：删除 job_requested / job_invalidated 死分支——job 只通过 transition_commit 的 new_jobs payload 创建，staleness 只在 sync 内存计算（不写事件）
+            // job 只通过 transition_commit 的 new_jobs payload 创建。reopen 到更早阶段时，
+            // 已绑定旧材料的待完成工作项会被 job_invalidated 关闭，避免阻塞新一轮 gate。
             case "job_accepted": {
                 const { job_id } = ev.payload;
                 const idx = openJobs.findIndex(j => j.job_id === job_id);
@@ -54,7 +54,13 @@ function replayEvents(events) {
                 }
                 break;
             }
-            // H4：job_invalidated 事件从不发射（删除死分支）
+            case "job_invalidated": {
+                const { job_id } = ev.payload;
+                const idx = openJobs.findIndex(j => j.job_id === job_id);
+                if (idx >= 0)
+                    openJobs.splice(idx, 1);
+                break;
+            }
             case "task_started": {
                 const attempt = ev.payload;
                 activeAttempts.push(attempt);
@@ -72,8 +78,10 @@ function replayEvents(events) {
             case "task_abandoned": {
                 const { attempt_id } = ev.payload;
                 const idx = activeAttempts.findIndex(a => a.attempt_id === attempt_id);
-                if (idx >= 0)
-                    activeAttempts.splice(idx, 1);
+                if (idx >= 0) {
+                    const [attempt] = activeAttempts.splice(idx, 1);
+                    taskStatuses[attempt.task_id] = "todo";
+                }
                 break;
             }
         }

package/dist/task.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock, appendRawRecord, readEvents } from "./store.js";
 import { tasksStructureDigest as formatDigest } from "./format.js";
 import { RecordInputDecodingError, readRecordInputFile } from "./record_input.js";
+import { GREEN_ONLY_NO_TDD_REASON } from "./types.js";
 /** tasks.md 结构指纹（委托给 format.ts 统一实现） */
 export function tasksStructureDigestOf(changeRoot) {
     const p = join(changeRoot, "tasks.md");
@@ -124,16 +125,28 @@ function validateContractTestRunInput(tr, attempt) {
     if (!["expected_failure", "expected_success", "characterization_pass"].includes(tr.semantic_status)) {
         return { ok: false, message: "语义状态（semantic_status）必须是 expected_failure、expected_success 或 characterization_pass" };
     }
+    const requiredEvidence = attempt.required_evidence;
+    if (tr.semantic_status === "expected_failure" && requiredEvidence && !requiredEvidence.red_required) {
+        return { ok: false, message: "当前任务执行快照不要求 RED（expected_failure）；请登记声明 TEST 的 GREEN" };
+    }
+    if (tr.semantic_status === "expected_failure" && !requiredEvidence &&
+        attempt.execution_policy === "green_only" &&
+        attempt.no_tdd_reason === GREEN_ONLY_NO_TDD_REASON) {
+        return { ok: false, message: "GREEN-only 任务不登记 RED（expected_failure）；请在实现后登记声明 TEST 的 GREEN" };
+    }
     if (tr.semantic_status === "expected_failure" && tr.exit_code === 0) {
         return { ok: false, message: "RED 预期失败（expected_failure）要求退出码（exit_code）非 0" };
     }
     if ((tr.semantic_status === "expected_success" || tr.semantic_status === "characterization_pass") && tr.exit_code !== 0) {
         return { ok: false, message: `语义状态（semantic_status=${tr.semantic_status}）要求退出码（exit_code）为 0` };
     }
-    if (tr.semantic_status === "characterization_pass" && !(attempt.tdd_required === false && attempt.no_tdd_reason === "characterization")) {
+    if (tr.semantic_status === "characterization_pass" && requiredEvidence && !requiredEvidence.accepted_green_statuses.includes("characterization_pass")) {
+        return { ok: false, message: "当前任务执行快照不接受特征化通过（characterization_pass）" };
+    }
+    if (tr.semantic_status === "characterization_pass" && !requiredEvidence && !(attempt.tdd_required === false && attempt.no_tdd_reason === "characterization")) {
         return { ok: false, message: "特征化通过（characterization_pass）只适用于无需 TDD 的特征化任务（tdd_required:false，no_tdd_reason:characterization）" };
     }
-    const declaredTests = attempt.contract?.tests ?? [];
+    const declaredTests = requiredEvidence?.test_ids ?? attempt.contract?.tests ?? [];
     if (declaredTests.length > 0 && !declaredTests.includes(tr.test_id)) {
         return { ok: false, message: `测试 ID（test_id=${tr.test_id}）不属于当前任务契约声明的测试列表` };
     }

package/dist/task_evidence.d.ts

@@ -1,4 +1,4 @@
-import type { TaskAttempt } from "./types.ts";
+import { type TaskAttempt } from "./types.ts";
 export type TaskEvidenceReadiness = {
     ready: true;
     missing: [];