@peterxiaoyang/superspec 0.1.40 → 0.1.41

package/dist/phase_plan.js

@@ -5,11 +5,23 @@ import { collectProposeOpenQuestions, countDiscoveryOpenQuestions, parseTasksMd,
 import { currentGitHead } from "./git_state.js";
 import { docRef, sha256File } from "./store.js";
 import { isReviewReadyVerifier, isFreshReviewVerifier, readReviewPolicyFromEvents, reviewEvidenceDigest, } from "./review.js";
-import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, codeReviewDecisionScope, collectCodeReviewGateFacts, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, } from "./code_review.js";
+import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, codeReviewDecisionScope, codeReviewJobStaleReason, collectCodeReviewGateFacts, currentCodeReviewWorkingPaths, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, } from "./code_review.js";
+import { isPhaseAdvanceAuthorized, latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 function requiredJobs(state, jobs, reason) {
     return { kind: "required_jobs", state, jobs, reason };
 }
+function phaseConfirmationStep(context, boundary, reason) {
+    const confirmation = phaseConfirmationForBoundary(context.projectRoot, context.events, context.snapshot, boundary, context.mode.risk);
+    if (!confirmation || isPhaseAdvanceAuthorized(context.events, confirmation))
+        return null;
+    return {
+        kind: "ask_user",
+        state: context.snapshot.state,
+        ask: confirmation.ask,
+        reason,
+    };
+}
 function reviewGatePlan(snapshot, gate, requiredRoles) {
     const missingRoles = [];
     for (const role of requiredRoles) {
@@ -63,14 +75,36 @@ function missingBaseArtifact(changeRoot, risk) {
     return null;
 }
 export function proposalDocsBaseline(changeRoot) {
-    // specs/ 用目录聚合指纹：审查可能只对 specs 提出修复，reopen 后仅改 specs 也算文档变化
-    const docs = ["proposal.md", "design.md", "tasks.md", "specs/", ".superspec/artifacts/test-contract.md"];
+    // 与 Propose gate 的可修改审查目标保持同一来源：specs/ 用目录聚合指纹，避免 reopen 基线漏掉任一个可修改的计划材料。
+    const docs = PROPOSE_FINAL_REVIEW_GATE.reviewTargets;
     const baseline = {};
     for (const doc of docs) {
         baseline[doc] = docRef(changeRoot, doc).sha;
     }
     return baseline;
 }
+function isDigestMap(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    return entries.length > 0 && entries.every(([, digest]) => typeof digest === "string");
+}
+export function latestAcceptedProposalBaseline(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition !== "accept" ||
+            payload.from_state !== "review" ||
+            payload.to_state !== "accepted")
+            continue;
+        return isDigestMap(payload.accepted_baseline_docs)
+            ? payload.accepted_baseline_docs
+            : null;
+    }
+    return null;
+}
 export function latestReopenProposeBaseline(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const ev = events[i];
@@ -185,8 +219,42 @@ export function pendingTaskStatusForApply(changeRoot, events) {
 export function formatPendingTaskMessage(ids, action) {
     return `尚有未完成任务：${ids.join(", ")}；${action}`;
 }
+function nextArgv(change, risk) {
+    return [
+        "superspec",
+        "transition",
+        "next",
+        "--change",
+        change,
+        ...(risk === "strict" ? [] : ["--risk", risk]),
+    ];
+}
+function acceptedMaterialFollowup(change, risk, planDocsChangedSinceAccept) {
+    return {
+        kind: "accepted_material_followup",
+        trigger: "material_user_followup",
+        reason_source: "summarize_user_input",
+        reopen_argv_template: [
+            "superspec",
+            "transition",
+            "reopen",
+            "--change",
+            change,
+            "--to",
+            "propose",
+            "--reason",
+            "{{reason}}",
+        ],
+        resume: {
+            kind: "continue_current_phase",
+            instruction: "根据用户补充更新 proposal/specs/design/tasks/test-contract；完成后重新执行 next。",
+            next_argv_after_completion: nextArgv(change, risk),
+        },
+        plan_docs_changed_since_accept: planDocsChangedSinceAccept,
+    };
+}
 export function planNextStep(context) {
-    const { changeRoot, mode, snapshot } = context;
+    const { change, changeRoot, events, mode, snapshot } = context;
     switch (snapshot.state) {
         case "init":
             if (snapshot.open_jobs.length > 0) {
@@ -217,6 +285,12 @@ export function planNextStep(context) {
                 };
                 return { kind: "ask_user", state: "explore", ask, reason: `有 ${openQs} 个未确认问题` };
             }
+            const requiredRoles = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(mode.risk);
+            if (!reviewGatePlan(snapshot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles)) {
+                const confirmation = phaseConfirmationStep(context, "explore_to_propose", "探索完成，等待用户确认进入计划阶段");
+                if (confirmation)
+                    return confirmation;
+            }
             return {
                 kind: "run_transition",
                 state: "explore",
@@ -253,6 +327,12 @@ export function planNextStep(context) {
             if (proposalReviewJobs.length > 0) {
                 return requiredJobs("propose_ready", proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
             }
+            const startApplyPlan = planStartApplyTransition(context, false);
+            if (startApplyPlan.kind === "advance") {
+                const confirmation = phaseConfirmationStep(context, "propose_to_apply", "计划阶段完成，等待用户确认开始实现");
+                if (confirmation)
+                    return confirmation;
+            }
             return { kind: "run_transition", state: "propose_ready", transition: "start-apply", reason: "计划就绪，开始执行" };
         }
         case "apply":
@@ -263,14 +343,28 @@ export function planNextStep(context) {
             return planReviewNext(context);
         case "accepted":
             if (snapshot.open_jobs.length > 0) {
-                return requiredJobs("accepted", snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项，暂不归档`);
+                return requiredJobs("accepted", snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项，暂不结束流程`);
+            }
+            {
+                const acceptedBaseline = latestAcceptedProposalBaseline(events);
+                const planDocsChanged = acceptedBaseline
+                    ? proposalDocsChangedSinceBaseline(changeRoot, acceptedBaseline)
+                    : null;
+                const driftNote = planDocsChanged === true
+                    ? "检测到 accepted 后计划材料已变化；当前完成结论仍对应 accepted 时冻结的版本。"
+                    : "";
+                return {
+                    kind: "done",
+                    state: "accepted",
+                    reason: `${driftNote}审查已接受，流程完成；后续若使用者补充或修改需求、方案、验收或实现约束，按 continuation 自动回到 propose 后继续，不得要求使用者执行工作流命令`,
+                    continuation: acceptedMaterialFollowup(change, mode.risk, planDocsChanged),
+                };
             }
-            return { kind: "ask_archive_confirmation", state: "accepted", reason: "审查通过，等待用户确认归档" };
         case "archive":
             if (snapshot.open_jobs.length > 0) {
-                return requiredJobs("archive", snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项，暂不结束`);
+                return requiredJobs("archive", snapshot.open_jobs, `历史 archive 状态仍有 ${snapshot.open_jobs.length} 个待完成工作项`);
             }
-            return { kind: "done", state: "archive", reason: "已归档，流程完成。" };
+            return { kind: "done", state: "archive", reason: "历史 archive 状态，流程已结束。" };
         case "abandoned":
             return { kind: "done", state: "abandoned", reason: "变更已放弃，流程终止。" };
         default:
@@ -320,6 +414,14 @@ function planApplyNext(context) {
         reason: "所有任务完成，进入审查",
     };
 }
+export function blockingJobsForApplyDone(projectRoot, events, snapshot) {
+    const facts = collectCodeReviewGateFacts(events);
+    const currentWorkingPaths = currentCodeReviewWorkingPaths(projectRoot, events);
+    const freshCodeReviewJobIds = new Set(facts.openJobs
+        .filter(job => codeReviewJobStaleReason(projectRoot, job, currentWorkingPaths) == null)
+        .map(job => job.job_id));
+    return snapshot.open_jobs.filter(job => job.role !== "code-reviewer" || freshCodeReviewJobIds.has(job.job_id));
+}
 function planApplyDoneNext(context) {
     const { change, changeRoot, events, mode, snapshot } = context;
     const pendingTasks = pendingTaskStatusForApply(changeRoot, events).pending;
@@ -332,10 +434,12 @@ function planApplyDoneNext(context) {
             reason: `发现未完成任务 ${pendingTasks[0]}，回到执行阶段`,
         };
     }
-    if (snapshot.open_jobs.length > 0) {
-        return requiredJobs("apply_done", snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项`);
-    }
     const facts = collectCodeReviewGateFacts(events);
+    const currentWorkingPaths = currentCodeReviewWorkingPaths(context.projectRoot, events);
+    const relevantOpenJobs = blockingJobsForApplyDone(context.projectRoot, events, snapshot);
+    if (relevantOpenJobs.length > 0) {
+        return requiredJobs("apply_done", relevantOpenJobs, `有 ${relevantOpenJobs.length} 个待完成工作项`);
+    }
     const latest = facts.latestTerminal;
     if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
         const status = latestCodeReviewFailedStatus(events);
@@ -423,6 +527,19 @@ function planApplyDoneNext(context) {
         };
         return { kind: "ask_user", state: "apply_done", ask, reason: "代码审查报告连续不符合要求或没有可处理问题" };
     }
+    const codeScan = scanCodeChangesForReview(context.projectRoot, events);
+    const acceptedScope = latest?.state === "accepted"
+        ? latest.job.packet_context?.code_review_scope
+        : undefined;
+    const acceptedCurrentHead = acceptedScope?.current_head;
+    const acceptedReviewReady = latest?.state === "accepted" &&
+        codeReviewJobStaleReason(context.projectRoot, latest.job, currentWorkingPaths) == null && (acceptedCurrentHead === null ||
+        (typeof acceptedCurrentHead === "string" && acceptedCurrentHead.trim() !== ""));
+    if (!codeScan.hasCodeChanges || acceptedReviewReady) {
+        const confirmation = phaseConfirmationStep(context, "apply_to_review", "Apply 与代码审查完成，等待用户确认进入最终审查");
+        if (confirmation)
+            return confirmation;
+    }
     return {
         kind: "run_transition",
         state: "apply_done",
@@ -485,7 +602,7 @@ export function planTransition(name, context) {
     }
 }
 function planExploreTransition(context) {
-    const { changeRoot, mode, snapshot } = context;
+    const { changeRoot, events, mode, projectRoot, snapshot } = context;
     if (snapshot.state === "init") {
         return { kind: "advance", fromState: "init", toState: "explore", reason: "进入探索阶段" };
     }
@@ -499,7 +616,18 @@ function planExploreTransition(context) {
     const gatePlan = reviewGatePlan(snapshot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles);
     if (gatePlan)
         return gatePlan;
-    return { kind: "advance", fromState: "explore", toState: "propose", reason: "探索完成" };
+    const confirmation = phaseConfirmationForBoundary(projectRoot, events, snapshot, "explore_to_propose");
+    const decision = confirmation ? latestAcceptedPhaseDecision(events, confirmation) : null;
+    if (!confirmation || decision?.decision !== "advance") {
+        return { kind: "skip", message: confirmation ? phaseConfirmationMissingMessage(confirmation) : "无法建立 Explore 阶段确认范围" };
+    }
+    return {
+        kind: "advance",
+        fromState: "explore",
+        toState: "propose",
+        reason: "探索完成",
+        payload: phaseConfirmationCommitPayload(confirmation, decision),
+    };
 }
 function planProposeReadyTransition(context) {
     const { changeRoot, mode, snapshot } = context;
@@ -526,7 +654,7 @@ function planProposeReadyTransition(context) {
         return gatePlan;
     return { kind: "advance", fromState: "propose", toState: "propose_ready", reason: `risk=${risk}，所有需求已满足` };
 }
-function planStartApplyTransition(context) {
+function planStartApplyTransition(context, enforceConfirmation = true) {
     const { changeRoot, events, projectRoot, snapshot } = context;
     if (snapshot.state !== "propose_ready")
         return { kind: "skip", message: `当前状态 ${snapshot.state}，需要 propose_ready` };
@@ -548,6 +676,11 @@ function planStartApplyTransition(context) {
     const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot);
     if (!executionRequirementPlan.ok)
         return { kind: "skip", message: executionRequirementPlan.message };
+    const confirmation = phaseConfirmationForBoundary(projectRoot, events, snapshot, "propose_to_apply");
+    const decision = confirmation ? latestAcceptedPhaseDecision(events, confirmation) : null;
+    if (enforceConfirmation && (!confirmation || decision?.decision !== "advance")) {
+        return { kind: "skip", message: confirmation ? phaseConfirmationMissingMessage(confirmation) : "无法建立 Propose 阶段确认范围" };
+    }
     const gitHead = currentGitHead(projectRoot);
     return {
         kind: "advance",
@@ -558,6 +691,7 @@ function planStartApplyTransition(context) {
             apply_start_head: gitHead.head,
             apply_start_head_reason: gitHead.reason,
             apply_contract_mode: executionRequirementPlan.mode,
+            ...(confirmation && decision?.decision === "advance" ? phaseConfirmationCommitPayload(confirmation, decision) : {}),
         },
     };
 }
@@ -578,5 +712,11 @@ function planAcceptTransition(context) {
         if (!verifierAccepted)
             return { kind: "skip", message: "缺少仍然匹配当前证据的最终验证，请先运行 review-ready" };
     }
-    return { kind: "advance", fromState: "review", toState: "accepted", reason: "审查通过" };
+    return {
+        kind: "advance",
+        fromState: "review",
+        toState: "accepted",
+        reason: "审查通过",
+        payload: { accepted_baseline_docs: proposalDocsBaseline(changeRoot) },
+    };
 }

package/dist/record.js

@@ -2,10 +2,14 @@
 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 { rebuildSnapshot } from "./sync.js";
+import { changeRoot as openspecChangeRoot } from "./openspec.js";
+import { isPhaseConfirmationScope, phaseActionForAnswer, phaseConfirmationForCurrentState, } 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 { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.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"]);
@@ -13,6 +17,9 @@ const CODE_REVIEW_FINDING_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
 function requiresReviewer(role) {
     return role === "critic" || role === "architect" || role === "test-engineer" || role === "code-reviewer";
 }
+function isOrdinaryReviewer(role) {
+    return role === "critic" || role === "architect" || role === "test-engineer";
+}
 function recommendedAgentForRole(role) {
     switch (role) {
         case "critic": return "critic";
@@ -42,6 +49,43 @@ function roleDescription(role) {
             return "执行受限测试工作项";
     }
 }
+function previousRejectionInstruction(job) {
+    const previous = job.previous_rejection;
+    if (!previous)
+        return "";
+    const reason = `上一次同角色审查没有形成可推进结论，原因：${previous.reason}。`;
+    if (!previous.findings || previous.findings.length === 0)
+        return `${reason}本次请先针对该原因重新审查，`;
+    return `${reason}本工作项附带上一次同角色审查尚未闭环的问题列表；请优先逐项复核：同一问题仍存在时复用原 finding ID；legacy finding 没有 ID 时沿用其原始语义并补一个稳定 ID；已解决的问题不要重复报告，不得通过更换 ID、标题或措辞重复同一问题；新增问题必须提供与历史问题不同的具体证据。`;
+}
+function ordinaryReviewerFindingInstruction(job) {
+    if (!isOrdinaryReviewer(job.role))
+        return "";
+    return "问题列表中的每个新 finding 必须分配稳定 ID，后续同一问题沿用该 ID，";
+}
+function reviewScopeForJob(job) {
+    if (job.review_targets !== undefined || job.read_only_refs !== undefined) {
+        return {
+            reviewTargets: job.review_targets ?? [],
+            readOnlyRefs: job.read_only_refs ?? [],
+        };
+    }
+    const gate = [EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE]
+        .find(candidate => candidate.isJobForGate(job));
+    return gate
+        ? { reviewTargets: [...gate.reviewTargets], readOnlyRefs: [...gate.readOnlyRefs] }
+        : { reviewTargets: [], readOnlyRefs: [] };
+}
+function reviewScopeInstruction(job, reviewTargets, readOnlyRefs) {
+    if (reviewTargets.length === 0 && readOnlyRefs.length === 0) {
+        return `请审查 ${job.boundFiles.map(file => file.path).join(", ")}，`;
+    }
+    const targets = reviewTargets.length > 0 ? `本 gate 可提出修改建议的审查目标为 ${reviewTargets.join(", ")}。` : "";
+    const refs = readOnlyRefs.length > 0
+        ? `只读上游引用为 ${readOnlyRefs.join(", ")}；只允许读取和核对一致性，不得要求在当前阶段修改、追加、删除、重排或格式化这些文件，不得把修改只读引用列为本阶段 required fix。只读引用自身的缺失、错误或矛盾可在 risks 或 open_questions 中上报给主流程，但不得单独作为本 gate 的 fail。只有能定位到审查目标的不一致，才能作为 fail 并指向该审查目标的修复。`
+        : "";
+    return targets + refs;
+}
 function asObject(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -205,6 +249,7 @@ function failedReviewReportRejectEventPayload(input) {
         job_id: input.jobId,
         role: input.job.role,
         report_digest: input.reportDigest,
+        result_kind: "review_failed",
         reason: "报告结论为 fail，工作项未通过",
         findings: Array.isArray(input.parsedReport.findings) ? input.parsedReport.findings : [],
         ...input.rawRef,
@@ -286,6 +331,9 @@ 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 至少包含一个问题");
+            }
             if (requiresReviewer(job.role)) {
                 validateReviewer(obj, checks);
             }
@@ -311,29 +359,21 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         checks.push("报告内容为空");
     }
     if (checks.length > 0) {
-        const resultKind = job.role === "code-reviewer" ? "invalid_report" : undefined;
-        const rawRef = resultKind && parsedReport
+        const resultKind = "invalid_report";
+        const rawRef = job.role === "code-reviewer" && parsedReport
             ? appendRawRecord(projectRoot, change, "review-reports", parsedReport)
             : null;
         const rejectEvent = makeEvent(change, "job_rejected", {
-            ...(resultKind
-                ? codeReviewRejectEventPayload({
-                    jobId,
-                    job,
-                    reportDigest,
-                    resultKind,
-                    reason: checks.join("; "),
-                    parsedReport,
-                    rawRef,
-                    reportPath,
-                })
-                : {
-                    job_id: jobId,
-                    role: job.role,
-                    report_digest: reportDigest,
-                    ...(reportPath ? { report_path: reportPath } : {}),
-                    reason: checks.join("; "),
-                }),
+            ...codeReviewRejectEventPayload({
+                jobId,
+                job,
+                reportDigest,
+                resultKind,
+                reason: checks.join("; "),
+                parsedReport,
+                rawRef,
+                reportPath,
+            }),
         });
         appendEvent(projectRoot, change, rejectEvent);
         return {
@@ -475,21 +515,21 @@ export function recordJobSubmitContent(projectRoot, change, changeRoot, jobId, r
     });
 }
 function recordUserDecisionLoaded(projectRoot, change, events, content, inputDigest) {
-    const existing = events.find(e => e.event_type === "user_decision_recorded"
+    const existing = [...events].reverse().find(e => e.event_type === "user_decision_recorded"
         && e.payload.input_digest === inputDigest);
-    if (existing) {
-        const accepted = existing.payload.accepted !== false;
-        return {
-            event_type: "user_decision_recorded",
-            accepted,
-            message: accepted ? "幂等返回：同一用户决策已登记" : "幂等返回：同一无效用户决策已登记",
-        };
-    }
     let decision;
     try {
         decision = JSON.parse(content);
     }
     catch {
+        if (existing) {
+            const accepted = existing.payload.accepted !== false;
+            return {
+                event_type: "user_decision_recorded",
+                accepted,
+                message: accepted ? "幂等返回：同一用户决策已登记" : "幂等返回：同一无效用户决策已登记",
+            };
+        }
         appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", {
             accepted: false,
             reason: "invalid_json",
@@ -505,6 +545,76 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         }));
         return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少决策范围（scope）或答复内容（answer）" };
     }
+    let phaseConfirmation = null;
+    let phaseAction = null;
+    if (isPhaseConfirmationScope(decision.scope)) {
+        const existingAccepted = existing &&
+            existing.payload.accepted !== false;
+        const latestAcceptedForScope = [...events].reverse().find(event => {
+            if (event.event_type !== "user_decision_recorded")
+                return false;
+            const payload = event.payload;
+            return payload.accepted !== false &&
+                payload.scope === decision.scope &&
+                payload.phase_confirmation != null;
+        });
+        const changeRoot = openspecChangeRoot(projectRoot, change);
+        const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
+        const current = phaseConfirmationForCurrentState(projectRoot, events, snapshot);
+        if (existingAccepted &&
+            current?.scope === decision.scope &&
+            latestAcceptedForScope?.event_id === existing.event_id) {
+            return {
+                event_type: "user_decision_recorded",
+                accepted: true,
+                message: "幂等返回：同一用户决策已登记",
+            };
+        }
+        const action = current ? phaseActionForAnswer(current, decision.answer) : null;
+        const rejectionReason = !current
+            ? "phase_confirmation_not_pending"
+            : decision.scope !== current.scope
+                ? "stale_phase_confirmation_scope"
+                : !action
+                    ? "invalid_phase_confirmation_answer"
+                    : action.reason === "required" && !nonEmptyString(decision.reason)
+                        ? "missing_phase_confirmation_reason"
+                        : null;
+        if (rejectionReason) {
+            if (existing &&
+                existing.payload.accepted === false &&
+                existing.payload.reason === rejectionReason) {
+                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: rejectionReason,
+                input_digest: inputDigest,
+            }));
+            const message = rejectionReason === "invalid_phase_confirmation_answer" && current
+                ? `阶段确认答复必须精确为：${current.ask.allowed_answers.join("、")}`
+                : rejectionReason === "missing_phase_confirmation_reason" && action
+                    ? action.reason_prompt ?? "当前选择必须写明原因"
+                    : "阶段确认已失效或当前没有待确认的阶段边界，请重新执行 next";
+            return { event_type: "user_decision_recorded", accepted: false, message };
+        }
+        phaseConfirmation = current;
+        phaseAction = action;
+    }
+    if (existing && !phaseAction) {
+        const accepted = existing.payload.accepted !== false;
+        return {
+            event_type: "user_decision_recorded",
+            accepted,
+            message: accepted ? "幂等返回：同一用户决策已登记" : "幂等返回：同一无效用户决策已登记",
+        };
+    }
     if (decision.scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX)) {
         const normalizedAnswer = normalizeCodeReviewDecisionAnswer(decision.answer);
         if (!normalizedAnswer) {
@@ -541,9 +651,19 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         : null;
     const normalizedDecision = {
         scope: decision.scope,
-        question: typeof decision.question === "string" ? decision.question : "",
-        answer: normalizedAnswer ? codeReviewDecisionAnswerLabel(normalizedAnswer) : decision.answer,
+        question: phaseConfirmation
+            ? phaseConfirmation.ask.question
+            : typeof decision.question === "string" ? decision.question : "",
+        answer: phaseAction
+            ? phaseAction.label
+            : normalizedAnswer ? codeReviewDecisionAnswerLabel(normalizedAnswer) : decision.answer,
         ...(typeof decision.reason === "string" ? { reason: decision.reason.trim() } : {}),
+        ...(phaseAction ? {
+            phase_confirmation: {
+                boundary: phaseAction.boundary,
+                decision: phaseAction.decision,
+            },
+        } : {}),
     };
     const rawRef = appendRawRecord(projectRoot, change, "user-decisions", normalizedDecision);
     const event = makeEvent(change, "user_decision_recorded", {
@@ -649,6 +769,7 @@ export function jobsPacket(projectRoot, change, jobId) {
     }
     const isCodeReviewer = job.role === "code-reviewer";
     const packetContext = job.packet_context;
+    const { reviewTargets, readOnlyRefs } = reviewScopeForJob(job);
     return {
         found: true,
         packet: {
@@ -657,6 +778,8 @@ 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 } : {}),
             ...(job.review_evidence_digest ? { review_evidence_digest: job.review_evidence_digest } : {}),
             ...(job.previous_rejection ? { previous_rejection: job.previous_rejection } : {}),
             ...(packetContext ? { packet_context: packetContext } : {}),
@@ -677,10 +800,12 @@ export function jobsPacket(projectRoot, change, jobId) {
                 : 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(", ")}，` +
+            output_instructions: `${roleDescription(job.role)}。` +
+                reviewScopeInstruction(job, reviewTargets, readOnlyRefs) +
                 (job.review_evidence_digest ? `本工作项对应的执行证据版本为 ${job.review_evidence_digest}，` : "") +
-                (job.previous_rejection ? `上一次代码审查没有形成可推进结论，原因：${job.previous_rejection.reason}。本次请根据该原因重新审查，` : "") +
+                previousRejectionInstruction(job) +
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
+                ordinaryReviewerFindingInstruction(job) +
                 `产出 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":${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>"}。`

package/dist/review.d.ts

@@ -1,4 +1,5 @@
-import type { Event, Job, Ref } from "./types.ts";
+import { type ReviewGateRule } from "./review_job_gates.ts";
+import type { Event, Job, JobRole, Ref, ReviewPreviousRejection } from "./types.ts";
 export type ReviewRisk = "minimal" | "normal" | "strict";
 export interface ReviewPolicy {
     review_risk: ReviewRisk;
@@ -8,6 +9,7 @@ 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 function latestReviewHistoryForGateRole(events: Event[], gate: ReviewGateRule, role: JobRole): ReviewPreviousRejection | null;
 export declare function isReviewReadyVerifier(job: Job): boolean;
 export declare function reviewBoundFiles(changeRoot: string): Ref[];
 export declare function reviewEvidenceDigest(events: Event[]): string;