@peterxiaoyang/superspec 0.1.34 → 0.1.36

package/dist/record.js

@@ -1,14 +1,16 @@
 // SuperSpec 流程引擎 — record：工作项结果登记
 import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, sha256Text, withLock, appendRawRecord, } from "./store.js";
 import { reviewEvidenceDigest, reviewVerifierStaleReason } from "./review.js";
+import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewDecisionAnswerLabel, codeReviewJobStaleReason, normalizeCodeReviewDecisionAnswer, scanCodeChanges, } from "./code_review.js";
 import { jobSubmitArgv } from "./job_action.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 requiresReviewer(role) {
-    return role === "critic" || role === "architect" || role === "test-engineer";
+    return role === "critic" || role === "architect" || role === "test-engineer" || role === "code-reviewer";
 }
 function recommendedAgentForRole(role) {
     switch (role) {
@@ -16,6 +18,7 @@ function recommendedAgentForRole(role) {
         case "architect": return "architect";
         case "test-engineer": return "test-engineer";
         case "verifier": return "verifier";
+        case "code-reviewer": return "code-reviewer";
         case "executor": return "executor";
         case "test-run": return "test-runner";
     }
@@ -30,12 +33,209 @@ function roleDescription(role) {
             return "审查测试契约、覆盖策略、RED/GREEN 可信度和验收场景映射";
         case "verifier":
             return "验证 proposal、实现状态、任务完成、测试契约和 SuperSpec 证据是否足以支撑完成结论";
+        case "code-reviewer":
+            return "审查 apply 后的代码实现质量、健壮性、性能、安全、兼容、边界条件、是否偏离 proposal/design/tasks/test-contract 以及关键测试缺口";
         case "executor":
             return "执行受限实现工作项";
         case "test-run":
             return "执行受限测试工作项";
     }
 }
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === "string");
+}
+function safeCodeReviewFindingId(value) {
+    return CODE_REVIEW_FINDING_ID_RE.test(value);
+}
+function uncheckedCodeReviewPaths(value, checks) {
+    const paths = new Set();
+    if (!Array.isArray(value))
+        return paths;
+    for (const item of value) {
+        const obj = asObject(item);
+        if (!obj) {
+            checks.push("代码审查覆盖范围里的未检查项必须是包含 path/reason 的对象");
+            continue;
+        }
+        if (!nonEmptyString(obj.path)) {
+            checks.push("代码审查覆盖范围里的未检查项缺少 path");
+            continue;
+        }
+        if (!nonEmptyString(obj.reason)) {
+            checks.push(`代码审查覆盖范围里的未检查项 ${obj.path} 缺少 reason`);
+            continue;
+        }
+        paths.add(obj.path);
+    }
+    return paths;
+}
+function codeReviewResultKind(value) {
+    return value === "invalid_report" || value === "non_actionable_report" || value === "review_failed"
+        ? value
+        : null;
+}
+function validateReviewer(obj, checks) {
+    if (!("reviewer" in obj))
+        checks.push("报告缺少必填字段 reviewer");
+    const reviewer = obj.reviewer;
+    if (!reviewer || typeof reviewer !== "object" || Array.isArray(reviewer)) {
+        checks.push("报告 reviewer 必须是包含 kind/id 的对象");
+    }
+    else {
+        if (typeof reviewer.kind !== "string" || !REVIEWER_KINDS.has(reviewer.kind)) {
+            checks.push(`报告 reviewer.kind 必须是 ${[...REVIEWER_KINDS].join("|")} 之一`);
+        }
+        if (typeof reviewer.id !== "string" || reviewer.id.trim() === "") {
+            checks.push("报告 reviewer.id 必须是非空字符串");
+        }
+    }
+}
+function validateCodeReviewScope(obj, job, checks) {
+    const scope = asObject(obj.review_scope);
+    if (!scope) {
+        checks.push("代码审查报告缺少覆盖范围字段 review_scope");
+        return;
+    }
+    if (scope.job_id !== job.job_id) {
+        checks.push(`代码审查覆盖范围里的 job_id ${String(scope.job_id)} 与工作项 ${job.job_id} 不匹配`);
+    }
+    if (scope.packet_digest !== job.packet_digest) {
+        checks.push("代码审查覆盖范围里的 packet_digest 与工作项不匹配，请使用当前工作项说明重新生成报告");
+    }
+    if (!stringArray(scope.checked_paths))
+        checks.push("代码审查覆盖范围里的 checked_paths 必须是字符串数组");
+    if (!stringArray(scope.checked_docs))
+        checks.push("代码审查覆盖范围里的 checked_docs 必须是字符串数组");
+    if (!Array.isArray(scope.unchecked))
+        checks.push("代码审查覆盖范围里的 unchecked 必须是数组");
+    if (stringArray(scope.checked_paths) && Array.isArray(scope.unchecked)) {
+        const checkedPaths = new Set(scope.checked_paths);
+        const uncheckedPaths = uncheckedCodeReviewPaths(scope.unchecked, checks);
+        for (const bound of job.boundFiles) {
+            if (!checkedPaths.has(bound.path) && !uncheckedPaths.has(bound.path)) {
+                checks.push(`代码审查报告未说明是否检查了 ${bound.path}`);
+            }
+        }
+    }
+}
+function actionableCodeReviewFindings(findings) {
+    if (!Array.isArray(findings))
+        return { actionable: [], reasons: ["报告字段 findings 必须是数组"] };
+    const actionable = [];
+    const reasons = [];
+    const ids = new Set();
+    for (const raw of findings) {
+        const finding = asObject(raw);
+        if (!finding) {
+            reasons.push("问题项必须是对象");
+            continue;
+        }
+        if (finding.blocking !== true)
+            continue;
+        const id = finding.id;
+        if (!nonEmptyString(id)) {
+            reasons.push("阻塞问题项缺少 id");
+            continue;
+        }
+        if (!safeCodeReviewFindingId(id)) {
+            reasons.push(`阻塞问题 ${id} 的 id 只能包含字母、数字、点、下划线、冒号或短横线，且不能包含空格或 #`);
+            continue;
+        }
+        if (ids.has(id)) {
+            reasons.push(`阻塞问题项 id 重复：${id}`);
+            continue;
+        }
+        ids.add(id);
+        const findingReasons = [];
+        const type = finding.type;
+        if (type !== "implementation" && type !== "spec" && type !== "mixed") {
+            findingReasons.push(`阻塞问题 ${id} 的分类 type 必须是 implementation|spec|mixed`);
+            reasons.push(...findingReasons);
+            continue;
+        }
+        for (const field of ["description", "evidence", "impact", "suggested_action"]) {
+            if (!nonEmptyString(finding[field]))
+                findingReasons.push(`阻塞问题 ${id} 缺少 ${field}`);
+        }
+        if (!stringArray(finding.source_refs) || finding.source_refs.length === 0) {
+            findingReasons.push(`阻塞问题 ${id} 缺少 source_refs`);
+        }
+        if (finding.suggested_action !== "apply" && finding.suggested_action !== "propose") {
+            findingReasons.push(`阻塞问题 ${id} 的 suggested_action 必须是 apply|propose`);
+        }
+        if (type === "implementation" && finding.suggested_action !== "apply") {
+            findingReasons.push(`纯代码实现问题 ${id} 的 suggested_action 必须是 apply`);
+        }
+        if (findingReasons.length > 0) {
+            reasons.push(...findingReasons);
+            continue;
+        }
+        actionable.push(finding);
+    }
+    return { actionable, reasons };
+}
+function codeReviewRejectEventPayload(input) {
+    const payload = {
+        job_id: input.jobId,
+        role: input.job.role,
+        report_digest: input.reportDigest,
+        result_kind: input.resultKind,
+        reason: input.reason,
+        ...(input.rawRef ?? {}),
+    };
+    if (input.resultKind === "review_failed" && input.parsedReport) {
+        payload.review_scope = input.parsedReport.review_scope ?? {};
+        payload.findings = Array.isArray(input.parsedReport.findings) ? input.parsedReport.findings : [];
+        payload.reviewer = input.parsedReport.reviewer ?? null;
+        if (typeof input.parsedReport.summary === "string")
+            payload.summary = input.parsedReport.summary;
+    }
+    return payload;
+}
+function failedReviewReportRejectEventPayload(input) {
+    const payload = {
+        job_id: input.jobId,
+        role: input.job.role,
+        report_digest: input.reportDigest,
+        reason: "报告结论为 fail，工作项未通过",
+        findings: Array.isArray(input.parsedReport.findings) ? input.parsedReport.findings : [],
+        ...input.rawRef,
+    };
+    for (const field of REVIEW_REPORT_OPTIONAL_FIELDS) {
+        if (field in input.parsedReport)
+            payload[field] = input.parsedReport[field];
+    }
+    return payload;
+}
+function projectRelativePath(projectRoot, path) {
+    const absolute = isAbsolute(path) ? path : resolve(projectRoot, path);
+    const rel = relative(projectRoot, absolute).replace(/\\/g, "/");
+    if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel))
+        return null;
+    return rel;
+}
+function staleBoundFilesChecks(job, projectRoot, changeRoot, ignoredCodePaths = []) {
+    const checks = [];
+    if (job.role === "code-reviewer") {
+        const ignored = new Set(ignoredCodePaths);
+        const currentPaths = scanCodeChanges(projectRoot).paths.filter(path => !ignored.has(path));
+        const reason = codeReviewJobStaleReason(projectRoot, job, currentPaths);
+        return reason ? [reason] : [];
+    }
+    for (const bf of job.boundFiles) {
+        const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
+        if (currentSha !== bf.sha) {
+            checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
+        }
+    }
+    return checks;
+}
 /** 从 events 中查找 job（H4 修复：job 只在 transition_commit 的 new_jobs payload 里） */
 function findJob(events, jobId) {
     for (const ev of events) {
@@ -66,23 +266,23 @@ function terminalJobSubmitResult(events, jobId, terminal, reportDigest) {
         return {
             event_type: existing.event_type,
             accepted: existing.event_type === "job_accepted",
-            message: "幂等返回：同 report 已提交",
+            message: "幂等返回：同一报告已提交",
             job_state: existing.event_type === "job_accepted" ? "accepted" : "rejected",
         };
     }
     return {
         event_type: "job_rejected",
         accepted: false,
-        message: `工作项 ${jobId} 已终态（${terminal}），不接受新报告。需要新工作项请重跑 transition。`,
+        message: `工作项 ${jobId} 已结束（${terminal}），不接受新报告。需要新工作项请重新执行对应的 transition。`,
     };
 }
-function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest) {
+function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest, reportFile) {
     const checks = [];
     let parsedReport = null;
     try {
         const report = JSON.parse(reportContent);
         if (!report || typeof report !== "object" || Array.isArray(report)) {
-            checks.push("报告必须是 JSON object");
+            checks.push("报告必须是 JSON 对象");
         }
         else {
             parsedReport = report;
@@ -95,42 +295,27 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
                 checks.push(`报告角色 ${String(obj.role)} 与工作项角色 ${job.role} 不匹配`);
             }
             if (obj.verdict !== "pass" && obj.verdict !== "fail") {
-                checks.push("报告 verdict 必须是 pass 或 fail");
+                checks.push("报告结论字段 verdict 必须是 pass 或 fail");
             }
             if (!Array.isArray(obj.findings)) {
-                checks.push("报告 findings 必须是数组");
-            }
-            if (obj.verdict === "fail") {
-                checks.push("报告 verdict=fail，工作项未通过");
+                checks.push("报告问题列表 findings 必须是数组");
             }
             if (requiresReviewer(job.role)) {
-                if (!("reviewer" in obj))
-                    checks.push("报告缺少必填字段 reviewer");
-                const reviewer = obj.reviewer;
-                if (!reviewer || typeof reviewer !== "object" || Array.isArray(reviewer)) {
-                    checks.push("报告 reviewer 必须是包含 kind/id 的对象");
-                }
-                else {
-                    if (typeof reviewer.kind !== "string" || !REVIEWER_KINDS.has(reviewer.kind)) {
-                        checks.push(`报告 reviewer.kind 必须是 ${[...REVIEWER_KINDS].join("|")} 之一`);
-                    }
-                    if (typeof reviewer.id !== "string" || reviewer.id.trim() === "") {
-                        checks.push("报告 reviewer.id 必须是非空字符串");
-                    }
-                }
+                validateReviewer(obj, checks);
+            }
+            if (job.role === "code-reviewer") {
+                validateCodeReviewScope(parsedReport, job, checks);
             }
         }
     }
     catch {
         checks.push("报告必须是有效 JSON");
     }
-    for (const bf of job.boundFiles) {
-        const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
-        if (currentSha !== bf.sha) {
-            checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
-        }
-    }
-    const reviewStaleReason = reviewVerifierStaleReason(job, changeRoot, reviewEvidenceDigest(events));
+    const reportPath = reportFile ? projectRelativePath(projectRoot, reportFile) : null;
+    checks.push(...staleBoundFilesChecks(job, projectRoot, changeRoot, reportPath ? [reportPath] : []));
+    const reviewStaleReason = job.role === "code-reviewer"
+        ? null
+        : reviewVerifierStaleReason(job, changeRoot, reviewEvidenceDigest(events));
     if (reviewStaleReason && !checks.includes(reviewStaleReason)) {
         checks.push(reviewStaleReason);
     }
@@ -138,11 +323,27 @@ 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
+            ? appendRawRecord(projectRoot, change, "review-reports", parsedReport)
+            : null;
         const rejectEvent = makeEvent(change, "job_rejected", {
-            job_id: jobId,
-            role: job.role,
-            report_digest: reportDigest,
-            reason: checks.join("; "),
+            ...(resultKind
+                ? codeReviewRejectEventPayload({
+                    jobId,
+                    job,
+                    reportDigest,
+                    resultKind,
+                    reason: checks.join("; "),
+                    parsedReport,
+                    rawRef,
+                })
+                : {
+                    job_id: jobId,
+                    role: job.role,
+                    report_digest: reportDigest,
+                    reason: checks.join("; "),
+                }),
         });
         appendEvent(projectRoot, change, rejectEvent);
         return {
@@ -152,6 +353,77 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
             job_state: "rejected",
         };
     }
+    if (job.role !== "code-reviewer" && parsedReport?.verdict === "fail") {
+        const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
+        const rejectEvent = makeEvent(change, "job_rejected", failedReviewReportRejectEventPayload({
+            jobId,
+            job,
+            reportDigest,
+            parsedReport,
+            rawRef,
+        }));
+        appendEvent(projectRoot, change, rejectEvent);
+        return {
+            event_type: "job_rejected",
+            accepted: false,
+            message: `工作项 ${jobId} 被拒绝：报告结论为 fail，工作项未通过`,
+            job_state: "rejected",
+        };
+    }
+    if (job.role === "code-reviewer" && parsedReport) {
+        const verdict = parsedReport.verdict;
+        const findings = parsedReport.findings;
+        const blockingCount = Array.isArray(findings)
+            ? findings.filter(item => asObject(item)?.blocking === true).length
+            : 0;
+        const { actionable, reasons } = actionableCodeReviewFindings(findings);
+        if (verdict === "pass") {
+            if (blockingCount > 0) {
+                const reason = "报告结论为 pass 时不能包含 blocking:true 的阻塞问题";
+                const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
+                appendEvent(projectRoot, change, makeEvent(change, "job_rejected", codeReviewRejectEventPayload({
+                    jobId,
+                    job,
+                    reportDigest,
+                    resultKind: "invalid_report",
+                    reason,
+                    parsedReport,
+                    rawRef,
+                })));
+                return {
+                    event_type: "job_rejected",
+                    accepted: false,
+                    message: `工作项 ${jobId} 被拒绝：${reason}`,
+                    job_state: "rejected",
+                };
+            }
+        }
+        else if (verdict === "fail") {
+            const hasOnlyActionableBlockingFindings = actionable.length > 0 && reasons.length === 0;
+            const resultKind = hasOnlyActionableBlockingFindings ? "review_failed" : "non_actionable_report";
+            const reason = hasOnlyActionableBlockingFindings
+                ? `代码审查发现 ${actionable.length} 个需要处理的阻塞问题`
+                : actionable.length > 0
+                    ? `代码审查报告包含无法处理的阻塞问题：${reasons.join("; ")}`
+                    : `代码审查报告没有给出可处理的阻塞问题${reasons.length > 0 ? `：${reasons.join("; ")}` : ""}`;
+            const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
+            appendEvent(projectRoot, change, makeEvent(change, "job_rejected", codeReviewRejectEventPayload({
+                jobId,
+                job,
+                reportDigest,
+                resultKind,
+                reason,
+                parsedReport,
+                rawRef,
+            })));
+            return {
+                event_type: "job_rejected",
+                accepted: false,
+                message: `工作项 ${jobId} 被拒绝：${reason}`,
+                job_state: "rejected",
+            };
+        }
+    }
     const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
     const acceptEvent = makeEvent(change, "job_accepted", {
         job_id: jobId,
@@ -187,7 +459,7 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
         }
         const reportContent = readFileSync(reportFile, "utf8");
         const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
-        return recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest);
+        return recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest, reportFile);
     });
 }
 /** record job-submit：从 JSON 内容登记工作项结果 */
@@ -208,35 +480,80 @@ 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"
+        && 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 {
-        appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "invalid_json" }));
+        appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", {
+            accepted: false,
+            reason: "invalid_json",
+            input_digest: inputDigest,
+        }));
         return { event_type: "user_decision_recorded", accepted: false, message: "决策文件不是有效 JSON" };
     }
-    if (!decision.scope || !decision.answer) {
-        appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "missing_scope_or_answer" }));
+    if (!nonEmptyString(decision.scope) || !nonEmptyString(decision.answer)) {
+        appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", {
+            accepted: false,
+            reason: "missing_scope_or_answer",
+            input_digest: inputDigest,
+        }));
         return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少 scope 或 answer" };
     }
-    const existing = events.find(e => e.event_type === "user_decision_recorded"
-        && e.payload.input_digest === inputDigest);
-    if (existing) {
-        return {
-            event_type: "user_decision_recorded",
-            accepted: true,
-            message: "幂等返回：同 user decision 已登记",
-        };
+    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}`,
+            };
+        }
+        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: "代码审查决策必须写明原因",
+            };
+        }
     }
+    const normalizedAnswer = decision.scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX)
+        ? normalizeCodeReviewDecisionAnswer(decision.answer)
+        : null;
     const normalizedDecision = {
         scope: decision.scope,
-        question: decision.question ?? "",
-        answer: decision.answer,
+        question: typeof decision.question === "string" ? decision.question : "",
+        answer: normalizedAnswer ? codeReviewDecisionAnswerLabel(normalizedAnswer) : decision.answer,
+        ...(typeof decision.reason === "string" ? { reason: decision.reason.trim() } : {}),
     };
     const rawRef = appendRawRecord(projectRoot, change, "user-decisions", normalizedDecision);
     const event = makeEvent(change, "user_decision_recorded", {
         ...normalizedDecision,
+        accepted: true,
         input_digest: inputDigest,
         ...rawRef,
     });
@@ -244,7 +561,7 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
     return {
         event_type: "user_decision_recorded",
         accepted: true,
-        message: `用户决策已登记：scope=${decision.scope}`,
+        message: `用户决策已登记：${decision.scope}`,
     };
 }
 /** record user-decision：登记用户决策 */
@@ -310,6 +627,7 @@ export function jobsPacket(projectRoot, change, jobId) {
     if (!job) {
         return { found: false, message: `工作项 ${jobId} 不存在` };
     }
+    const isCodeReviewer = job.role === "code-reviewer";
     return {
         found: true,
         packet: {
@@ -318,21 +636,30 @@ export function jobsPacket(projectRoot, change, jobId) {
             recommended_agent: recommendedAgentForRole(job.role),
             boundFiles: job.boundFiles,
             ...(job.review_evidence_digest ? { review_evidence_digest: job.review_evidence_digest } : {}),
+            ...(job.previous_rejection ? { previous_rejection: job.previous_rejection } : {}),
             packet_digest: job.packet_digest,
             required_output_kind: "job_report_json",
             preferred_input_mode: "stdin",
             submission_command: `superspec record job-submit --change "${change}" --job "${job.job_id}" --report -`,
             submission_argv: jobSubmitArgv(change, job.job_id),
             file_fallback: true,
-            output_contract_fields: requiresReviewer(job.role) ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer"] : [...REVIEW_REPORT_REQUIRED_FIELDS],
+            output_contract_fields: isCodeReviewer
+                ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer", "review_scope"]
+                : requiresReviewer(job.role) ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer"] : [...REVIEW_REPORT_REQUIRED_FIELDS],
             output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
             output_instructions: `${roleDescription(job.role)}。请审查 ${job.boundFiles.map(f => f.path).join(", ")}，` +
-                (job.review_evidence_digest ? `本工作项绑定的执行证据版本为 ${job.review_evidence_digest}，` : "") +
-                (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} reviewer 执行并在 reviewer.kind/id 中记录来源，` : "") +
-                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仍可作为 fallback。` +
-                (requiresReviewer(job.role)
-                    ? `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}`
-                    : `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]}`),
+                (job.review_evidence_digest ? `本工作项对应的执行证据版本为 ${job.review_evidence_digest}，` : "") +
+                (job.previous_rejection ? `上一次代码审查没有形成可推进结论，原因：${job.previous_rejection.reason}。本次请根据该原因重新审查，` : "") +
+                (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在 reviewer.kind/id 中记录来源，` : "") +
+                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仍可作为 fallback。以下 JSON 合约给审查代理使用，普通对话不要原样复述。` +
+                (isCodeReviewer
+                    ? `最小格式：{"role":"code-reviewer","verdict":"pass|fail","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":${JSON.stringify(job.boundFiles.map(f => f.path))},"checked_docs":["proposal.md","design.md","tasks.md",".superspec/artifacts/test-contract.md"],"unchecked":[]},"findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}；review_scope 用来说明本次审查覆盖了哪些文件和文档，checked_paths 与 unchecked 必须合起来覆盖全部 boundFiles，unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}。`
+                        + `报告结论为 fail 时，findings 至少包含一个可处理、可追溯的阻塞问题，字段为 {"id":"<stable-id>","blocking":true,"type":"implementation|spec|mixed","description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。type 中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题。`
+                    : job.role === "verifier"
+                        ? `最小格式：{"role":"verifier","verdict":"pass|fail","findings":[]}。核对代码审查记录 code_review_gate：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对代码审查问题闭环：实现修复任务必须带 review_fix_of:<job_id>#<problem_id>，方案/混合问题必须有用户决策或后续修复证据。核对 RED/GREEN：同一 task_completed.attempt_id 下必须有 RED/characterization 与 GREEN；test-run 证据应包含 test_id、command、cwd、exit_code、semantic_status；审查修复的回归 test-run 可用 covers_task_ids 说明覆盖了哪些已完成任务；缺少 attempt_id 的旧证据只能弱引用。`
+                        : requiresReviewer(job.role)
+                            ? `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}`
+                            : `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]}`),
             stop_conditions: ["审查完成后提交报告，不要修改文档"],
             created_from_transition: job.created_from_transition,
         },

package/dist/review.js

@@ -60,19 +60,27 @@ export function reviewBoundFiles(changeRoot) {
         .map(path => ({ path, sha: sha256File(join(changeRoot, path)) ?? "sha256:missing" }));
 }
 function evidenceSortKey(record) {
-    return [
+    const parts = [
         record.kind,
         record.task_id ?? "",
         record.attempt_id ?? "",
         record.task_structure_digest ?? "",
         record.test_id ?? "",
         record.semantic_status ?? "",
-        record.command ?? "",
-        record.cwd ?? "",
-        record.exit_code == null ? "" : String(record.exit_code),
-        record.target_fingerprint ?? "",
-        record.event_digest,
-    ].join("\u0000");
+    ];
+    if (record.covers_task_ids && record.covers_task_ids.length > 0) {
+        parts.push(`covers:${JSON.stringify(record.covers_task_ids)}`);
+    }
+    parts.push(record.command ?? "", record.cwd ?? "", record.exit_code == null ? "" : String(record.exit_code), record.target_fingerprint ?? "", record.event_digest);
+    return parts.join("\u0000");
+}
+function normalizedCoveredTaskIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value
+            .filter((item) => typeof item === "string")
+            .map(item => item.trim())
+            .filter(Boolean))].sort();
 }
 export function reviewEvidenceDigest(events) {
     const attemptsById = new Map();
@@ -116,12 +124,14 @@ export function reviewEvidenceDigest(events) {
         const matchesLegacyDigest = attemptId == null && structureDigest != null && completedStructureDigests.has(structureDigest);
         if (!matchesCompletedAttempt && !matchesLegacyDigest)
             continue;
+        const coversTaskIds = normalizedCoveredTaskIds(payload.covers_task_ids);
         records.push({
             kind: "test_run_recorded",
             test_id: typeof payload.test_id === "string" ? payload.test_id : null,
             attempt_id: attemptId,
             task_structure_digest: structureDigest,
             semantic_status: typeof payload.semantic_status === "string" ? payload.semantic_status : null,
+            ...(coversTaskIds.length > 0 ? { covers_task_ids: coversTaskIds } : {}),
             command: typeof payload.command === "string" ? payload.command : "",
             cwd: typeof payload.cwd === "string" ? payload.cwd : "",
             exit_code: typeof payload.exit_code === "number" ? payload.exit_code : null,

package/dist/store.d.ts

@@ -21,6 +21,7 @@ export declare function computeDocumentDigests(changeRoot: string, docPaths: str
 export declare function digestOf(obj: unknown): string;
 export declare function appendEvent(projectRoot: string, change: string, event: Event): void;
 export declare function readEvents(projectRoot: string, change: string): Event[];
+export declare function findLatestEvent(events: Event[], eventType: Event["event_type"], predicate: (event: Event) => boolean): Event | null;
 export declare function makeEvent(change: string, eventType: Event["event_type"], payload: Record<string, unknown>, opts?: {
     transitionId?: string | null;
     idempotencyKey?: string | null;

package/dist/store.js

@@ -93,6 +93,16 @@ export function readEvents(projectRoot, change) {
     }
     return events;
 }
+export function findLatestEvent(events, eventType, predicate) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== eventType)
+            continue;
+        if (predicate(event))
+            return event;
+    }
+    return null;
+}
 export function makeEvent(change, eventType, payload, opts = {}) {
     const base = {
         change_id: change,