@peterxiaoyang/superspec 0.1.46 → 0.1.47

package/dist/phase_plan.js

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
-import { collectProposeOpenQuestions, countDiscoveryOpenQuestions, parseExecutionRequirements, parseTasksMd, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, validateExecutionRequirementDocumentReferences, validateProposalImpact, validateTasksDocument, } from "./format.js";
+import { currentExploreRoundId, exploreAnswerRegistrationPayload, unregisteredClosedExploreQuestions, } from "./explore_round.js";
+import { collectProposeOpenQuestions, discoveryOpenQuestionDisplayText, discoveryOpenQuestionScope, parseExecutionRequirements, parseDiscoveryOpenQuestions, parseTasksMd, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, validateExecutionRequirementDocumentReferences, validateProposalImpact, validateTasksDocument, } from "./format.js";
 import { currentGitHead } from "./git_state.js";
 import { validateOpenSpecChange } from "./openspec.js";
 import { docRef, sha256File } from "./store.js";
@@ -184,6 +185,11 @@ export function discoveryDocsBaseline(changeRoot) {
     }
     return baseline;
 }
+/** 新 Explore 轮次冻结已有已确认事项，避免把历史答复当作本轮遗漏。 */
+export function exploreAnswerRegistrationPayloadForChange(changeRoot) {
+    const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
+    return exploreAnswerRegistrationPayload(existsSync(discoveryPath) ? readFileSync(discoveryPath, "utf8") : null);
+}
 function isDigestMap(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -452,10 +458,6 @@ export function planNextStep(context) {
                     reason: "回到 explore 后至少一个 discovery 材料必须变化",
                 };
             }
-            const exploreReviewJobs = EXPLORE_DISCOVERY_REVIEW_GATE.openJobsForGate(snapshot);
-            if (exploreReviewJobs.length > 0) {
-                return requiredJobs("explore", exploreReviewJobs, `有 ${exploreReviewJobs.length} 个待完成探索审查工作项`);
-            }
             const discoveryCheck = validateDiscovery(changeRoot);
             if (!discoveryCheck.ok) {
                 const ask = {
@@ -466,14 +468,32 @@ export function planNextStep(context) {
                 return { kind: "ask_user", state: "explore", ask, reason: discoveryCheck.message };
             }
             const content = readFileSync(join(changeRoot, ".superspec", "artifacts", "discovery.md"), "utf8");
-            const openQs = countDiscoveryOpenQuestions(content);
-            if (openQs > 0) {
+            const currentQuestion = parseDiscoveryOpenQuestions(content)[0];
+            if (currentQuestion) {
+                const questionText = discoveryOpenQuestionDisplayText(currentQuestion);
                 const ask = {
-                    question: `discovery.md 有 ${openQs} 个未解决的待确认问题，请逐个确认`,
-                    allowed_answers: ["所有问题已确认"],
-                    scope: "explore_open_questions",
+                    question: `现在有一件事需要你确认：${questionText}\n\n请只回答这一件事。主流程会先登记答复，再将结论回写 discovery.md；回写完成前会继续询问这一件事。`,
+                    // 用户可以接受建议、选择其他方向或补充事实；状态机不解释答案语义。
+                    allowed_answers: [],
+                    scope: discoveryOpenQuestionScope(currentQuestion, currentExploreRoundId(events)),
                 };
-                return { kind: "ask_user", state: "explore", ask, reason: `有 ${openQs} 个未确认问题` };
+                return { kind: "ask_user", state: "explore", ask, reason: "等待用户确认" };
+            }
+            const unregisteredClosedQuestions = unregisteredClosedExploreQuestions(events, content);
+            if (unregisteredClosedQuestions.length > 0) {
+                const ask = {
+                    question: "发现一项已标记为已确认的事项没有对应的答复登记。请先将该项恢复为待确认，按主流程重新登记用户答复并回写 discovery.md 后继续。",
+                    allowed_answers: ["已处理"],
+                    scope: "explore_answer_registration",
+                };
+                return { kind: "ask_user", state: "explore", ask, reason: "存在未登记答复的已确认事项" };
+            }
+            // 先让用户澄清当前 Discovery，再审查材料；否则 critic 会审查一份仍有
+            // 关键业务未知的文档。正常创建的 job 已绑定 discovery 指纹，材料变化后
+            // 会由 snapshot freshness 自动失效。
+            const exploreReviewJobs = EXPLORE_DISCOVERY_REVIEW_GATE.openJobsForGate(snapshot);
+            if (exploreReviewJobs.length > 0) {
+                return requiredJobs("explore", exploreReviewJobs, `有 ${exploreReviewJobs.length} 个待完成探索审查工作项`);
             }
             const requiredRoles = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(mode.risk);
             if (!reviewGatePlan(snapshot, events, changeRoot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles)) {
@@ -642,6 +662,16 @@ function planApplyDoneNext(context) {
     }
     const latest = facts.latestTerminal;
     if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
+        const staleReason = codeReviewJobStaleReason(context.projectRoot, latest.job, currentWorkingPaths);
+        if (staleReason) {
+            return {
+                kind: "run_transition",
+                state: "apply_done",
+                transition: "review-ready",
+                risk: mode.risk,
+                reason: `代码审查结论已过期，重新发起审查：${staleReason}`,
+            };
+        }
         const status = latestCodeReviewFailedStatus(events);
         const pendingFinding = status?.unresolved[0] ?? null;
         if (status && status.findings.length > 0 && !pendingFinding) {
@@ -804,7 +834,13 @@ export function planTransition(name, context) {
 function planExploreTransition(context) {
     const { changeRoot, events, mode, projectRoot, snapshot } = context;
     if (snapshot.state === "init") {
-        return { kind: "advance", fromState: "init", toState: "explore", reason: "进入探索阶段" };
+        return {
+            kind: "advance",
+            fromState: "init",
+            toState: "explore",
+            reason: "进入探索阶段",
+            payload: exploreAnswerRegistrationPayloadForChange(changeRoot),
+        };
     }
     if (snapshot.state !== "explore") {
         return { kind: "skip", message: `当前状态 ${snapshot.state}，explore 不适用` };
@@ -816,6 +852,14 @@ function planExploreTransition(context) {
     const discoveryCheck = validateDiscovery(changeRoot);
     if (!discoveryCheck.ok)
         return { kind: "skip", message: discoveryCheck.message };
+    const discoveryContent = readFileSync(join(changeRoot, ".superspec", "artifacts", "discovery.md"), "utf8");
+    const currentQuestion = parseDiscoveryOpenQuestions(discoveryContent)[0];
+    if (currentQuestion) {
+        return { kind: "skip", message: "discovery.md 仍有需要确认的事项，请先完成确认并回写 discovery.md" };
+    }
+    if (unregisteredClosedExploreQuestions(events, discoveryContent).length > 0) {
+        return { kind: "skip", message: "discovery.md 有已确认事项缺少对应答复登记，请先恢复为待确认并按主流程登记答复" };
+    }
     const requiredRoles = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(mode.risk);
     const gatePlan = reviewGatePlan(snapshot, events, changeRoot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles);
     if (gatePlan)

package/dist/record.js

@@ -1,26 +1,31 @@
 // SuperSpec 流程引擎 — record：工作项结果登记
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 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, workflowRiskForPhaseConfirmation, } from "./phase_confirmation.js";
-import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewDecisionAnswerLabel, normalizeCodeReviewDecisionAnswer, } from "./code_review.js";
+import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewJobStaleReason, codeReviewDecisionAnswerLabel, currentCodeReviewWorkingPaths, latestCodeReviewFailedStatus, normalizeCodeReviewDecisionAnswer, parseCodeReviewDecisionScope, } from "./code_review.js";
 import { invalidReasonForSubmittedReport } from "./job_validity.js";
 import { jobSubmitArgv } from "./job_action.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";
+import { currentExploreRoundId } from "./explore_round.js";
+import { discoveryOpenQuestionDisplayText, discoveryQuestionContextFingerprint, discoveryOpenQuestionScope, EXPLORE_OPEN_QUESTION_SCOPE_PREFIX, parseDiscoveryOpenQuestions, } from "./format.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"]);
 const CODE_REVIEW_FINDING_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+function isReviewRole(role) {
+    return role === "critic" || role === "architect" || role === "test-engineer" || role === "code-reviewer" || role === "verifier";
+}
 function requiresReviewer(role) {
     return role === "critic" || role === "architect" || role === "test-engineer" || role === "code-reviewer";
 }
 /** All review reports with bound material acknowledge full file coverage. */
 function requiresReviewScope(job) {
-    return job.boundFiles.length > 0 && job.role !== "executor" && job.role !== "test-run";
+    return job.boundFiles.length > 0 && isReviewRole(job.role);
 }
 function projectLocalInvalidReportMustTerminate(job) {
     return job.role === "code-reviewer" || job.packet_context?.code_state_check !== undefined;
@@ -62,14 +67,13 @@ function previousRejectionInstruction(job) {
     if (!previous)
         return "";
     const reason = `上一次同角色审查没有形成可推进结论，原因：${previous.reason}。`;
-    if (!previous.findings || previous.findings.length === 0)
-        return `${reason}本轮是修复复核；完整读取材料只用于核对当前修正和直接一致性，不得借复核重新审计与修正无关的历史设计，`;
-    return `${reason}本轮是修复复核：逐项判断本工作项附带的上一次同角色 finding 是否仍成立。Finding 中的 recommendation 只是非绑定建议，不是需求或验收标准；先独立核对 underlying problem、直接证据和本次验收，不得因原建议指定了某种架构就要求照做。同一问题仍存在时复用原 finding ID；legacy finding 没有 ID 时沿用其原始语义并补一个稳定 ID；已解决或已由等价证据闭环的问题不要重复报告，不得通过更换 ID、标题或措辞重复同一问题。默认只复核历史 finding；新 blocker 仅允许是本次修正直接引入的回归，并必须说明“修正动作 → 新问题”的因果链，不得展开无关的故障模型、消费者或架构议题。`;
-}
-function ordinaryReviewerFindingInstruction(job) {
-    if (!isOrdinaryReviewer(job.role))
-        return "";
-    return "问题列表中的每个新 finding 必须分配稳定 ID，后续同一问题沿用该 ID，";
+    if (!previous.findings || previous.findings.length === 0) {
+        return `${reason}上一轮没有可复核的历史 finding；请按当前 gate 的完整范围独立审查，不要把拒绝原因当作需求或验收标准，`;
+    }
+    const identityRule = job.role === "code-reviewer"
+        ? "同一问题仍存在时复用原 finding ID；legacy finding 没有 ID 时沿用原始语义并补一个稳定 ID；"
+        : "已解决或已由等价证据闭环的问题不要重复报告，不得通过更换标题或措辞重复同一问题；";
+    return `${reason}本轮是修复复核：逐项判断本工作项附带的上一次同角色 finding 是否仍成立。Finding 中的 recommendation 只是非绑定建议，不是需求或验收标准；先独立核对 underlying problem、直接证据和本次验收，不得因原建议指定了某种架构就要求照做。${identityRule}默认只复核历史 finding；新 blocker 仅允许是本次修正直接引入的回归，并必须说明“修正动作 → 新问题”的因果链，不得展开无关的故障模型、消费者或架构议题。`;
 }
 function reviewScopeForJob(job) {
     if (job.review_targets !== undefined || job.read_only_refs !== undefined) {
@@ -94,10 +98,15 @@ function reviewScopeInstruction(job, reviewTargets, readOnlyRefs) {
         : "";
     return targets + refs;
 }
-function reviewCoverageInstruction(job) {
+function genericReviewCoverageInstruction(job) {
     if (!requiresReviewScope(job))
         return "";
-    return `审查顺序固定为：先建立覆盖索引，按文件和标题/行段完整浏览全部 boundFiles 至文件末尾；长文档必须分段读取，不能在发现第一个 blocker 时停止覆盖。read_only_refs 按本次问题需要读取，用于核对目标与上下游一致性，不要求机械全文遍历或写入 checked_paths。完整读取只用于核对本次 change 的目标、直接修改及跨文档一致性，不等于允许重新审计全部历史设计。若 proposal.md 存在“需求变化”，以其中记录的受影响能力、直接修改章节和保持不变范围作为本轮增量审查的权威锚点；本轮新 finding 必须由该需求变化、为接入变化所做的直接修改，或这些修改造成的跨文档矛盾引起，并说明因果链。此前已通过且被明确记录为保持不变的设计不得重新打开为 blocker；不要凭通用风险类别猜测变化范围。注意事项和故障类别是条件式检查项，不是必须穷举的清单。Recommendation 只能描述需要补足的结果、契约或证据，不得把未经 proposal、design 或用户决定选定的新基础设施写成 required fix。报告中的 review_scope.checked_paths 必须列出全部已浏览的 boundFiles；它只是覆盖回执，不能代替语义审查，也不扩大可报告问题的范围。`;
+    return "完整审查全部 boundFiles，不因发现第一个 blocker 停止；read_only_refs 只在核对本次问题与上下游一致性时读取。review_scope.checked_paths 必须回执已浏览的全部 boundFiles，但该回执不能代替语义审查，也不扩大可报告问题的范围。";
+}
+function proposalIncrementalReviewInstruction(job) {
+    if (!PROPOSE_FINAL_REVIEW_GATE.isJobForGate(job))
+        return "";
+    return "若 proposal.md 有“需求变化”，以其中记录的受影响能力、直接修改章节和保持不变范围作为增量审查锚点；新 finding 必须由该变化、其直接修改或由此造成的跨文档矛盾引起，并说明因果链。此前已通过且明确保持不变的设计不得重新打开为 blocker；Recommendation 只描述需要补足的结果、契约或证据，不得把未经 proposal、design 或用户决定选定的新基础设施写成 required fix。";
 }
 function migrationEvidenceInstruction(job) {
     const isProposeReview = PROPOSE_FINAL_REVIEW_GATE.isJobForGate(job);
@@ -117,6 +126,66 @@ function asObject(value) {
 function nonEmptyString(value) {
     return typeof value === "string" && value.trim() !== "";
 }
+function currentDiscoveryOpenQuestion(projectRoot, change) {
+    const discoveryPath = join(openspecChangeRoot(projectRoot, change), ".superspec", "artifacts", "discovery.md");
+    if (!existsSync(discoveryPath))
+        return null;
+    return parseDiscoveryOpenQuestions(readFileSync(discoveryPath, "utf8"))[0] ?? null;
+}
+function latestAcceptedExploreOpenQuestionDecision(events, scope) {
+    return [...events].reverse().find(event => {
+        if (event.event_type !== "user_decision_recorded")
+            return false;
+        const payload = event.payload;
+        return payload.accepted !== false && payload.scope === scope;
+    }) ?? null;
+}
+function isExploreOpenQuestionScope(scope) {
+    return scope.startsWith(EXPLORE_OPEN_QUESTION_SCOPE_PREFIX);
+}
+function isWellFormedExploreOpenQuestionScope(scope) {
+    return /^explore_open_question:sha256:[a-f0-9]{64}:(?:Q-[A-Za-z0-9][A-Za-z0-9_-]*|item-[1-9]\d*)$/.test(scope);
+}
+function invalidExploreOpenQuestionResult(projectRoot, change, inputDigest, existing, decision, reason) {
+    const existingPayload = existing?.payload;
+    if (existingPayload?.accepted === false && existingPayload.reason === reason) {
+        return {
+            event_type: "user_decision_recorded",
+            accepted: false,
+            message: "幂等返回：同一无效待确认问题答复已登记",
+        };
+    }
+    appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", {
+        accepted: false,
+        scope: decision.scope,
+        answer: decision.answer,
+        reason,
+        input_digest: inputDigest,
+    }));
+    return {
+        event_type: "user_decision_recorded",
+        accepted: false,
+        message: reason === "invalid_explore_open_question_scope"
+            ? "确认事项的内部标识无效，请重新执行 next 获取当前事项"
+            : reason === "explore_open_question_already_recorded"
+                ? "这件事已有已登记答复，请先回写 discovery.md 后重新执行 next"
+                : "需要确认的事项已变化或已完成，请重新执行 next 获取当前事项",
+    };
+}
+function invalidCodeReviewDecisionResult(projectRoot, change, inputDigest, existing, decision, reason, message) {
+    const existingPayload = existing?.payload;
+    if (existingPayload?.accepted === false && existingPayload.reason === reason) {
+        return { event_type: "user_decision_recorded", accepted: false, message: "幂等返回：同一无效代码审查决策已登记" };
+    }
+    appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", {
+        accepted: false,
+        scope: decision.scope,
+        answer: decision.answer,
+        reason,
+        input_digest: inputDigest,
+    }));
+    return { event_type: "user_decision_recorded", accepted: false, message };
+}
 function stringArray(value) {
     return Array.isArray(value) && value.every(item => typeof item === "string");
 }
@@ -421,8 +490,8 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
             if (!Array.isArray(obj.findings)) {
                 checks.push("报告问题列表 findings 必须是数组");
             }
-            else if (isOrdinaryReviewer(job.role) && obj.verdict === "fail" && obj.findings.length === 0) {
-                checks.push("普通审查报告结论为 fail 时 findings 至少包含一个问题");
+            else if ((isOrdinaryReviewer(job.role) || job.role === "verifier") && obj.verdict === "fail" && obj.findings.length === 0) {
+                checks.push("审查报告结论为 fail 时 findings 至少包含一个问题");
             }
             if (requiresReviewer(job.role)) {
                 validateReviewer(obj, checks);
@@ -633,6 +702,40 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         }));
         return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少决策范围（scope）或答复内容（answer）" };
     }
+    // Explore 的用户答复只能绑定当前文档顺序中的第一项。这里不判断答案是否
+    // “正确”，只机械校验当前项、Discovery 决策上下文和 Explore 轮次仍与 next
+    // 返回时一致，防止旧问题在材料改写或重新探索后被错误登记为新问题的决定。
+    let exploreOpenQuestion = null;
+    let exploreOpenQuestionRoundId = null;
+    let exploreOpenQuestionContextFingerprint = null;
+    if (isExploreOpenQuestionScope(decision.scope)) {
+        if (!isWellFormedExploreOpenQuestionScope(decision.scope)) {
+            return invalidExploreOpenQuestionResult(projectRoot, change, inputDigest, existing, { scope: decision.scope, answer: decision.answer }, "invalid_explore_open_question_scope");
+        }
+        const current = currentDiscoveryOpenQuestion(projectRoot, change);
+        const expectedScope = current ? discoveryOpenQuestionScope(current, currentExploreRoundId(events)) : null;
+        if (!expectedScope || decision.scope !== expectedScope) {
+            return invalidExploreOpenQuestionResult(projectRoot, change, inputDigest, existing, { scope: decision.scope, answer: decision.answer }, "stale_explore_open_question_scope");
+        }
+        const acceptedForCurrentScope = latestAcceptedExploreOpenQuestionDecision(events, decision.scope);
+        if (acceptedForCurrentScope) {
+            const previousAnswer = acceptedForCurrentScope.payload.answer;
+            if (previousAnswer === decision.answer) {
+                return {
+                    event_type: "user_decision_recorded",
+                    accepted: true,
+                    message: "幂等返回：同一用户决策已登记",
+                };
+            }
+            return invalidExploreOpenQuestionResult(projectRoot, change, inputDigest, existing, { scope: decision.scope, answer: decision.answer }, "explore_open_question_already_recorded");
+        }
+        exploreOpenQuestion = current;
+        exploreOpenQuestionRoundId = currentExploreRoundId(events);
+        const discoveryPath = join(openspecChangeRoot(projectRoot, change), ".superspec", "artifacts", "discovery.md");
+        exploreOpenQuestionContextFingerprint = current
+            ? discoveryQuestionContextFingerprint(readFileSync(discoveryPath, "utf8"), current)
+            : null;
+    }
     let phaseConfirmation = null;
     let phaseAction = null;
     let phaseReviewRisk = null;
@@ -699,7 +802,10 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         phaseAction = action;
         phaseReviewRisk = decisionRisk;
     }
-    if (existing && !phaseAction) {
+    // Explore scope 已在上面按当前问题和同 scope 的已接受答复完成校验。此前同一
+    // input 曾因 stale 被拒绝、但材料后来回到完全相同的当前项时，不能让旧拒绝
+    // 记录永久吞掉一次现在有效的登记。
+    if (existing && !phaseAction && !exploreOpenQuestion) {
         const accepted = existing.payload.accepted !== false;
         return {
             event_type: "user_decision_recorded",
@@ -760,36 +866,45 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         };
         reviewRejectionDecisionSource = decision.decision_source;
     }
+    let codeReviewDecisionReference = null;
     if (decision.scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX)) {
         const normalizedAnswer = normalizeCodeReviewDecisionAnswer(decision.answer);
         if (!normalizedAnswer) {
-            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", {
-                accepted: false,
-                scope: decision.scope,
-                answer: decision.answer,
-                reason: "invalid_code_review_decision_answer",
-                input_digest: inputDigest,
-            }));
-            return {
-                event_type: "user_decision_recorded",
-                accepted: false,
-                message: `代码审查决策必须是 ${CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_propose}、${CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_apply} 或 ${CODE_REVIEW_DECISION_ANSWER_LABELS.dismiss}`,
-            };
+            return invalidCodeReviewDecisionResult(projectRoot, change, inputDigest, existing, { scope: decision.scope, answer: decision.answer }, "invalid_code_review_decision_answer", `代码审查决策必须是 ${CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_propose}、${CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_apply} 或 ${CODE_REVIEW_DECISION_ANSWER_LABELS.dismiss}`);
         }
         if (!nonEmptyString(decision.reason)) {
-            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", {
-                accepted: false,
-                scope: decision.scope,
-                answer: decision.answer,
-                reason: "missing_reason",
-                input_digest: inputDigest,
-            }));
-            return {
-                event_type: "user_decision_recorded",
-                accepted: false,
-                message: "代码审查决策必须写明原因",
-            };
+            return invalidCodeReviewDecisionResult(projectRoot, change, inputDigest, existing, { scope: decision.scope, answer: decision.answer }, "missing_reason", "代码审查决策必须写明原因");
         }
+        const ref = parseCodeReviewDecisionScope(decision.scope);
+        const changeRoot = openspecChangeRoot(projectRoot, change);
+        const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
+        const status = latestCodeReviewFailedStatus(events);
+        const finding = ref && status?.terminal.job.job_id === ref.jobId
+            ? status.findings.find(item => item.id === ref.findingId && (item.type === "spec" || item.type === "mixed"))
+            : null;
+        const staleReason = status && ref && status.terminal.job.job_id === ref.jobId
+            ? codeReviewJobStaleReason(projectRoot, status.terminal.job, currentCodeReviewWorkingPaths(projectRoot, events))
+            : null;
+        if (!ref || snapshot.state !== "apply_done" || !status || !finding || staleReason) {
+            const reason = !ref
+                ? "invalid_code_review_decision_scope"
+                : snapshot.state !== "apply_done"
+                    ? "code_review_decision_not_current"
+                    : staleReason
+                        ? "stale_code_review_decision_target"
+                        : "code_review_decision_target_not_found";
+            const message = staleReason
+                ? "代码审查材料已不再匹配当前代码，请先重新执行 review-ready 获取新的审查结论"
+                : "代码审查决策只能关联当前代码审查报告中的待决定问题，请先执行 next 获取当前选择";
+            return invalidCodeReviewDecisionResult(projectRoot, change, inputDigest, existing, { scope: decision.scope, answer: decision.answer }, reason, message);
+        }
+        codeReviewDecisionReference = {
+            job_id: status.terminal.job.job_id,
+            finding_id: finding.id,
+            rejection_event_id: status.terminal.event.event_id,
+            rejection_event_digest: status.terminal.event.event_digest,
+            packet_digest: status.terminal.job.packet_digest,
+        };
     }
     const normalizedAnswer = decision.scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX)
         ? normalizeCodeReviewDecisionAnswer(decision.answer)
@@ -798,13 +913,25 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         scope: decision.scope,
         question: phaseConfirmation
             ? phaseConfirmation.ask.question
-            : typeof decision.question === "string" ? decision.question : "",
+            : exploreOpenQuestion
+                ? discoveryOpenQuestionDisplayText(exploreOpenQuestion)
+                : typeof decision.question === "string" ? decision.question : "",
         answer: phaseAction
             ? phaseAction.label
             : normalizedAnswer ? codeReviewDecisionAnswerLabel(normalizedAnswer) : decision.answer,
         ...(typeof decision.reason === "string" ? { reason: decision.reason.trim() } : {}),
         ...(reviewRejectionDecisionSource ? { decision_source: reviewRejectionDecisionSource } : {}),
         ...(reviewRejectionOverride ? { review_rejection_override: reviewRejectionOverride } : {}),
+        ...(codeReviewDecisionReference ? { code_review_decision: codeReviewDecisionReference } : {}),
+        ...(exploreOpenQuestion && exploreOpenQuestionRoundId && exploreOpenQuestionContextFingerprint ? {
+            explore_open_question: {
+                round_id: exploreOpenQuestionRoundId,
+                question_id: exploreOpenQuestion.id,
+                question_ordinal: exploreOpenQuestion.ordinal,
+                document_fingerprint: exploreOpenQuestion.documentFingerprint,
+                context_fingerprint: exploreOpenQuestionContextFingerprint,
+            },
+        } : {}),
         ...(phaseAction ? {
             phase_confirmation: {
                 boundary: phaseAction.boundary,
@@ -824,7 +951,9 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
     return {
         event_type: "user_decision_recorded",
         accepted: true,
-        message: `用户决策已登记：决策范围（scope）=${decision.scope}`,
+        message: exploreOpenQuestion
+            ? "这件事的答复已登记"
+            : `用户决策已登记：决策范围（scope）=${decision.scope}`,
     };
 }
 /** record user-decision：登记用户决策 */
@@ -913,6 +1042,7 @@ function packetFieldDescriptions() {
         unattributed_paths: "代码审查范围中暂时无法归属到某个任务（task）的文件。",
         unknown_attribution_tasks: "因为缺少边界快照或提交段 diff 失败而无法完整计算改动归属的任务（task）。",
         coverage_exemption_refs: "测试覆盖豁免引用：说明某个 TEST 为什么没有绑定到任务（task）。",
+        code_review_gate: "最终验证读取的代码审查门禁事实：passed 指向已接受的代码审查工作项，skipped 表示本轮没有代码类改动。",
         code_state_check: "代码状态检查：最终验证时用于判断代码审查后代码是否又发生变化。",
         event_id: "事件 ID，用于追溯证据来源。",
         event_digest: "事件摘要，用于确认引用的证据事件没有被替换。",
@@ -932,6 +1062,7 @@ export function jobsPacket(projectRoot, change, jobId) {
         return { found: false, message: `工作项 ${jobId} 不存在` };
     }
     const isCodeReviewer = job.role === "code-reviewer";
+    const isReviewer = isReviewRole(job.role);
     const hasReviewScope = requiresReviewScope(job);
     const packetContext = job.packet_context;
     const { reviewTargets, readOnlyRefs } = reviewScopeForJob(job);
@@ -943,12 +1074,13 @@ export function jobsPacket(projectRoot, change, jobId) {
             ...(job.gate_id ? { gate_id: job.gate_id } : {}),
             recommended_agent: recommendedAgentForRole(job.role),
             boundFiles: job.boundFiles,
-            ...(reviewTargets.length > 0 ? { review_targets: reviewTargets } : {}),
-            ...(readOnlyRefs.length > 0 ? { read_only_refs: readOnlyRefs } : {}),
+            ...(isReviewer && reviewTargets.length > 0 ? { review_targets: reviewTargets } : {}),
+            ...(isReviewer && readOnlyRefs.length > 0 ? { read_only_refs: readOnlyRefs } : {}),
             ...(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?.code_review_gate ? { code_review_gate: packetContext.code_review_gate } : {}),
             ...(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 } : {}),
@@ -970,29 +1102,31 @@ export function jobsPacket(projectRoot, change, jobId) {
             output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
             字段说明: packetFieldDescriptions(),
             output_instructions: `${roleDescription(job.role)}。` +
-                reviewScopeInstruction(job, reviewTargets, readOnlyRefs) +
-                migrationEvidenceInstruction(job) +
+                (isReviewer ? reviewScopeInstruction(job, reviewTargets, readOnlyRefs) : "") +
+                (isReviewer ? migrationEvidenceInstruction(job) : "") +
                 (job.review_evidence_digest ? `本工作项对应的执行证据版本为 ${job.review_evidence_digest}，` : "") +
-                reviewCoverageInstruction(job) +
-                previousRejectionInstruction(job) +
+                (isReviewer ? genericReviewCoverageInstruction(job) + proposalIncrementalReviewInstruction(job) + previousRejectionInstruction(job) : "") +
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
-                ordinaryReviewerFindingInstruction(job) +
                 `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仅作备用。${recordInputInstruction(job)}协议字段含义见 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":${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>"}。`
+                    ? `最小格式：{"role":"code-reviewer","verdict":"pass","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>"}}。verdict 只能为 pass 或 fail；审查覆盖范围（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；每项的 required_evidence 是 task-start 冻结的证据口径，red_required/green_required 分别说明是否需要 RED/GREEN；每项的 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；fix 非空表示状态机创建的实现修复，source、parent_task_id 和 reason 说明其归属，code_review 来源还需核对 review_finding；每项的 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>），方案/混合问题必须有用户决策或后续修复证据。按 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）的旧证据只能弱引用。` +
+                        ? `最小格式：{"role":"verifier","verdict":"pass","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}。verdict 只能为 pass 或 fail；核对代码审查记录（code_review_gate）：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对修复闭环：task_execution_index.fix.source=code_review 时必须核对 review_finding 对应问题是否关闭；source=self_test 时必须核对 parent_task_id、记录的自测原因、本次 attempt 验证和最新代码审查是否共同闭环。方案/混合问题必须有用户决策或后续修复证据。按 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）。修复 task 的回归测试运行可用回归覆盖任务列表（covers_task_ids）说明覆盖了哪些已完成任务；缺少任务尝试 ID（attempt_id）的旧证据只能弱引用。` +
                             (packetContext?.code_state_check
-                                ? `本工作项带代码状态检查（code_state_check）：head_matches 为 false 或 changed_paths 非空表示代码审查后代码又发生变化，须在报告中列出差异并交主流程与用户裁决，不自行判定无害，也不据此自动否定已接受的代码审查。`
+                                ? `本工作项带代码状态检查（code_state_check），它是创建 packet 时的快照：验证期间若代码状态已变化，不要提交该报告；主流程会通过 next 创建携带最新事实的验证工作项。`
                                 : "")
-                        : requiresReviewer(job.role)
-                            ? `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""},"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}`
-                            : `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}`),
-            stop_conditions: ["审查完成后提交报告，不要修改文档"],
+                        : isReviewer
+                            ? `最小格式：{"role":"${job.role}","verdict":"pass","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""},"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}。verdict 只能为 pass 或 fail。`
+                            : `最小格式：{"role":"${job.role}","verdict":"pass","findings":[]}。verdict 只能为 pass 或 fail。`),
+            stop_conditions: isReviewer
+                ? ["完成审查后提交报告，不要修改文档"]
+                : job.role === "executor"
+                    ? ["完成绑定范围内的实现后提交执行报告，不要修改未绑定范围"]
+                    : ["完成指定验证后提交测试报告，不要修改项目文档"],
             created_from_transition: job.created_from_transition,
         },
         message: `工作项 ${jobId} 的执行说明`,

package/dist/review.js

@@ -90,6 +90,8 @@ function reviewCycleState(gate) {
         return "explore";
     if (gate.gate_id === PROPOSE_FINAL_REVIEW_GATE_ID)
         return "propose";
+    if (gate.gate_id === REVIEW_FINAL_VERIFIER_GATE.gate_id)
+        return "review";
     return null;
 }
 function currentReviewGateCycleStart(events, gate) {

package/dist/task_evidence.js

@@ -4,6 +4,11 @@ import { parseTasksMd } from "./format.js";
 import { readEvents, sha256Text } from "./store.js";
 import { GREEN_ONLY_NO_TDD_REASON } from "./types.js";
 export function taskEvidenceReadiness(projectRoot, change, changeRoot, attempt) {
+    // 有效证据计划是 task-start 在当时策略下冻结的事实。状态机新建的 Fix
+    // 即使来自历史/v1 Apply，也必须优先按这个快照回放。
+    if (attempt.required_evidence) {
+        return effectiveContractTaskEvidenceReadiness(projectRoot, change, attempt);
+    }
     if (attempt.contract_mode === true) {
         return contractTaskEvidenceReadiness(projectRoot, change, attempt);
     }
@@ -52,9 +57,6 @@ export function taskEvidenceReadiness(projectRoot, change, changeRoot, attempt)
         : { ready: false, missing, reason: missing.join("、") };
 }
 function contractTaskEvidenceReadiness(projectRoot, change, attempt) {
-    if (attempt.required_evidence) {
-        return effectiveContractTaskEvidenceReadiness(projectRoot, change, attempt);
-    }
     return legacyContractTaskEvidenceReadiness(projectRoot, change, attempt);
 }
 /** 新执行依据模式：只消费 task-start 冻结的有效证据计划。 */

package/dist/transition.d.ts

@@ -40,6 +40,7 @@ export declare function taskStart(projectRoot: string, change: string, changeRoo
 export declare function reopen(projectRoot: string, change: string, changeRoot: string, to: State, reason: string, opts?: {
     reviewFix?: string;
     reviewFinding?: string;
+    selfTestFix?: string;
 }): TransitionResult;
 export declare function reviewReady(projectRoot: string, change: string, changeRoot: string, risk?: ReviewRisk): TransitionResult;
 export declare function accept(projectRoot: string, change: string, changeRoot: string): TransitionResult;