@peterxiaoyang/superspec 0.1.34 → 0.1.35

package/README.md

@@ -11,7 +11,7 @@
 SuperSpec 会把一次需求变更拆成 5 步：
 
 ```text
-探索需求 -> 写方案 -> 做实现 -> 做审查 -> 归档收尾
+探索需求 -> 写方案 -> 做实现 -> 代码审查与最终验证 -> 归档收尾
 ```
 
 这样做的目的很简单：
@@ -112,10 +112,10 @@ superspec.cmd install
 使用 superspec-apply，按任务实现。
 ```
 
-实现完成后，审查：
+实现完成后，代码审查与最终验证：
 
 ```text
-使用 superspec-review，检查实现、测试和风险。
+使用 superspec-review，完成代码审查、问题处理和最终验证。
 ```
 
 审查通过后，归档：
@@ -131,7 +131,7 @@ superspec.cmd install
 | `superspec-explore` | 需求刚开始时 | 读代码、查现状、整理范围和风险；这一步不改业务代码 |
 | `superspec-propose` | 需求已经清楚后 | 写正式方案、规格、设计和任务，并提前规划测试 |
 | `superspec-apply` | 方案通过后 | 按任务实现代码，记录测试或验证结果 |
-| `superspec-review` | 实现完成后 | 做代码审查、架构审查、反方审查和最终验证 |
+| `superspec-review` | 实现完成后 | 检查代码实现是否符合方案，处理审查问题，并完成最终验证 |
 | `superspec-archive` | 审查通过后 | 用 OpenSpec 完成归档，并检查关键记录是否保留 |
 
 你日常主要记住这五个入口就够了。

package/dist/cli.js

@@ -501,7 +501,8 @@ async function main(argv) {
 transition 子命令：
   init / explore / sync / next / propose-ready / start-apply
   task-start --task <T> / task-complete --task <T>
-  reopen --to apply --reason <TEXT>
+  reopen --to apply --reason <TEXT> [--review-fix <JOB#FINDING>]
+  reopen --to propose --reason <TEXT> --review-finding <JOB#FINDING>
   review-ready / accept / archive
 
 record 子命令：
@@ -693,7 +694,10 @@ jobs 子命令：
                             console.error("reopen 需要 --reason");
                             return 1;
                         }
-                        const result = reopen(projectRoot, change, cr, to, reason);
+                        const result = reopen(projectRoot, change, cr, to, reason, {
+                            ...(opts["review-fix"] ? { reviewFix: opts["review-fix"] } : {}),
+                            ...(opts["review-finding"] ? { reviewFinding: opts["review-finding"] } : {}),
+                        });
                         console.log(JSON.stringify(result, null, 2));
                         return transitionExitCode(result);
                     }

package/dist/code_review.d.ts

@@ -0,0 +1,74 @@
+import type { CodeReviewResultKind, Event, Job, Ref } from "./types.ts";
+export declare const CODE_REVIEW_REPAIR_SCOPE_PREFIX = "code_reviewer_report_repair:";
+export declare const CODE_REVIEW_DECISION_SCOPE_PREFIX = "code_review_decision:";
+export type CodeReviewDecisionAnswer = "reopen_propose" | "reopen_apply" | "dismiss";
+export declare const CODE_REVIEW_DECISION_ANSWER_LABELS: Record<CodeReviewDecisionAnswer, string>;
+export interface CodeChangeScan {
+    reliable: boolean;
+    hasCodeChanges: boolean;
+    paths: string[];
+    reason: string;
+}
+export interface CodeReviewTerminalResult {
+    job: Job;
+    event: Event;
+    state: "accepted" | "rejected";
+    result_kind?: CodeReviewResultKind;
+    reason?: string;
+}
+export interface CodeReviewDecision {
+    answer: CodeReviewDecisionAnswer;
+    reason: string;
+    event: Event;
+}
+export interface CodeReviewFindingStatus {
+    id: string;
+    type: "implementation" | "spec" | "mixed";
+    finding: Record<string, unknown>;
+    decision: CodeReviewDecision | null;
+}
+export interface CodeReviewFailedStatus {
+    terminal: CodeReviewTerminalResult;
+    findings: CodeReviewFindingStatus[];
+    unresolved: CodeReviewFindingStatus[];
+    dismissed: CodeReviewFindingStatus[];
+}
+export interface CodeReviewGateFacts {
+    cycleStartIndex: number;
+    jobs: Job[];
+    openJobs: Job[];
+    terminalResults: CodeReviewTerminalResult[];
+    latestTerminal: CodeReviewTerminalResult | null;
+    latestRejected: CodeReviewTerminalResult | null;
+    consecutiveRejected: number;
+}
+export declare function isCodeLikePath(path: string): boolean;
+export declare function scanCodeChanges(projectRoot: string): CodeChangeScan;
+export declare function codeReviewBoundFiles(projectRoot: string, paths: string[]): Ref[];
+export declare function codeReviewJobStaleReason(projectRoot: string, job: Job, currentPaths?: string[]): string | null;
+export declare function codeReviewPacketDigest(input: {
+    role: "code-reviewer";
+    boundFiles: Ref[];
+    checkedDocs: string[];
+    created_from_transition: string;
+    previous_rejection?: {
+        result_kind: CodeReviewResultKind;
+        reason: string;
+        job_id: string;
+    };
+}): string;
+export declare function codeReviewDecisionScope(jobId: string, findingId: string): string;
+export declare function isCodeReviewDecisionAnswer(value: unknown): value is CodeReviewDecisionAnswer;
+export declare function codeReviewDecisionAnswerLabel(answer: CodeReviewDecisionAnswer): string;
+export declare function normalizeCodeReviewDecisionAnswer(value: unknown): CodeReviewDecisionAnswer | null;
+export declare function latestCodeReviewDecision(events: Event[], scope: string): CodeReviewDecision | null;
+export declare function latestCodeReviewFailedStatus(events: Event[]): CodeReviewFailedStatus | null;
+export declare function dismissedCodeReviewSummary(status: CodeReviewFailedStatus): string;
+export declare function currentApplyDoneCycleStart(events: Event[]): number;
+export declare function collectCodeReviewGateFacts(events: Event[]): CodeReviewGateFacts;
+export declare function latestApplyDoneToReviewGate(events: Event[]): {
+    decision: "passed" | "skipped";
+    job_id?: string;
+    reason?: string;
+} | null;
+export declare function requiresFinalVerifierForCurrentReview(events: Event[]): boolean;

package/dist/code_review.js

@@ -0,0 +1,323 @@
+// SuperSpec code-reviewer gate helpers.
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, extname } from "node:path";
+import { findLatestEvent, sha256File, sha256Text } from "./store.js";
+export const CODE_REVIEW_REPAIR_SCOPE_PREFIX = "code_reviewer_report_repair:";
+export const CODE_REVIEW_DECISION_SCOPE_PREFIX = "code_review_decision:";
+export const CODE_REVIEW_DECISION_ANSWER_LABELS = {
+    reopen_propose: "回到计划阶段",
+    reopen_apply: "回到实现阶段",
+    dismiss: "驳回该问题",
+};
+const PROCESS_DOC_RE = /^(?:openspec\/changes\/[^/]+\/)?(?:proposal|design|tasks)\.md$/;
+const PROCESS_ARTIFACT_RE = /^(?:openspec\/changes\/[^/]+\/)?\.superspec\/artifacts\/(?:discovery|business-invariants|test-contract)\.md$/;
+const CODE_EXTENSIONS = new Set([
+    ".c", ".cc", ".cpp", ".cs", ".css", ".go", ".h", ".hpp", ".html", ".java", ".js", ".jsx",
+    ".json", ".kt", ".mjs", ".mts", ".php", ".py", ".rb", ".rs", ".scss", ".sh", ".sql",
+    ".swift", ".toml", ".ts", ".tsx", ".yaml", ".yml",
+]);
+const CODE_BASENAMES = new Set([
+    "Dockerfile", "Makefile", "package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+    "tsconfig.json", "tsconfig.build.json", "eslint.config.js", "vite.config.ts", "webpack.config.js",
+]);
+const WALK_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".superspec", ".omx"]);
+function normalizeGitPath(rawPath) {
+    const trimmed = rawPath.trim();
+    const unquoted = trimmed.startsWith('"') && trimmed.endsWith('"')
+        ? trimmed.slice(1, -1).replace(/\\"/g, '"')
+        : trimmed;
+    const renamed = unquoted.includes(" -> ") ? unquoted.split(" -> ").pop() ?? unquoted : unquoted;
+    return renamed.replace(/\\/g, "/");
+}
+function gitChangedPaths(projectRoot) {
+    try {
+        const output = execFileSync("git", ["-C", projectRoot, "status", "--porcelain", "--untracked-files=all"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const paths = output
+            .split("\n")
+            .map(line => line.trimEnd())
+            .filter(Boolean)
+            .map(line => normalizeGitPath(line.slice(3)))
+            .filter(Boolean);
+        return { ok: true, paths: [...new Set(paths)].sort() };
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : "git status failed" };
+    }
+}
+function isProcessOrOrdinaryDoc(path) {
+    if (path.startsWith(".superspec/") || path.startsWith(".omx/"))
+        return true;
+    if (path.includes("/.superspec/") || path.includes("/.omx/"))
+        return true;
+    if (PROCESS_DOC_RE.test(path) || PROCESS_ARTIFACT_RE.test(path))
+        return true;
+    return extname(path).toLowerCase() === ".md";
+}
+export function isCodeLikePath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    if (!normalized || isProcessOrOrdinaryDoc(normalized))
+        return false;
+    const base = normalized.split("/").pop() ?? normalized;
+    if (CODE_BASENAMES.has(base))
+        return true;
+    return CODE_EXTENSIONS.has(extname(base).toLowerCase());
+}
+function walkCodeFiles(root, dir = root, out = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (WALK_SKIP_DIRS.has(entry.name))
+                continue;
+            walkCodeFiles(root, join(dir, entry.name), out);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const full = join(dir, entry.name);
+        const rel = full.slice(root.length + 1).replace(/\\/g, "/");
+        if (isCodeLikePath(rel))
+            out.push(rel);
+    }
+    return out;
+}
+export function scanCodeChanges(projectRoot) {
+    const git = gitChangedPaths(projectRoot);
+    if (!git.ok) {
+        const paths = existsSync(projectRoot) && statSync(projectRoot).isDirectory()
+            ? walkCodeFiles(projectRoot).sort()
+            : [];
+        return {
+            reliable: false,
+            hasCodeChanges: true,
+            paths,
+            reason: `无法读取 git 状态，已按当前代码文件范围发起审查：${git.reason}`,
+        };
+    }
+    const paths = git.paths.filter(isCodeLikePath);
+    return {
+        reliable: true,
+        hasCodeChanges: paths.length > 0,
+        paths,
+        reason: paths.length > 0 ? "检测到代码类改动" : "没有代码类改动",
+    };
+}
+export function codeReviewBoundFiles(projectRoot, paths) {
+    return paths.map(path => ({ path, sha: sha256File(join(projectRoot, path)) ?? "sha256:missing" }));
+}
+function samePathSet(left, right) {
+    const a = [...new Set(left)].sort();
+    const b = [...new Set(right)].sort();
+    return a.length === b.length && a.every((path, index) => path === b[index]);
+}
+export function codeReviewJobStaleReason(projectRoot, job, currentPaths) {
+    if (!isCodeReviewerJob(job))
+        return null;
+    const scanPaths = currentPaths ?? scanCodeChanges(projectRoot).paths;
+    const boundPaths = job.boundFiles.map(file => file.path);
+    if (!samePathSet(boundPaths, scanPaths)) {
+        return `代码审查范围已变化（原范围：${boundPaths.join(", ") || "<none>"}；当前范围：${scanPaths.join(", ") || "<none>"}）`;
+    }
+    for (const bound of job.boundFiles) {
+        const currentSha = sha256File(join(projectRoot, bound.path)) ?? "sha256:missing";
+        if (currentSha !== bound.sha) {
+            return `代码审查范围内的文件 ${bound.path} 已变化（原记录：${bound.sha}；当前：${currentSha}）`;
+        }
+    }
+    return null;
+}
+export function codeReviewPacketDigest(input) {
+    return sha256Text(JSON.stringify(input));
+}
+function isCodeReviewerJob(job) {
+    return job.role === "code-reviewer" && job.created_from_transition === "review-ready";
+}
+function codeReviewResultKind(value) {
+    return value === "invalid_report" || value === "non_actionable_report" || value === "review_failed"
+        ? value
+        : undefined;
+}
+export function codeReviewDecisionScope(jobId, findingId) {
+    return `${CODE_REVIEW_DECISION_SCOPE_PREFIX}${jobId}#${findingId}`;
+}
+export function isCodeReviewDecisionAnswer(value) {
+    return value === "reopen_propose" || value === "reopen_apply" || value === "dismiss";
+}
+export function codeReviewDecisionAnswerLabel(answer) {
+    return CODE_REVIEW_DECISION_ANSWER_LABELS[answer];
+}
+export function normalizeCodeReviewDecisionAnswer(value) {
+    if (isCodeReviewDecisionAnswer(value))
+        return value;
+    if (value === CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_propose)
+        return "reopen_propose";
+    if (value === CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_apply)
+        return "reopen_apply";
+    if (value === CODE_REVIEW_DECISION_ANSWER_LABELS.dismiss)
+        return "dismiss";
+    return null;
+}
+export function latestCodeReviewDecision(events, scope) {
+    const event = findLatestEvent(events, "user_decision_recorded", ev => {
+        const payload = ev.payload;
+        if (payload.scope !== scope)
+            return false;
+        if (payload.accepted === false)
+            return false;
+        if (!normalizeCodeReviewDecisionAnswer(payload.answer))
+            return false;
+        if (typeof payload.reason !== "string" || payload.reason.trim() === "")
+            return false;
+        return true;
+    });
+    if (!event)
+        return null;
+    const payload = event.payload;
+    const answer = normalizeCodeReviewDecisionAnswer(payload.answer);
+    if (!answer)
+        return null;
+    return {
+        answer,
+        reason: typeof payload.reason === "string" ? payload.reason.trim() : "",
+        event,
+    };
+}
+function blockingFindingsFromReviewFailed(event, jobId, events) {
+    const payload = event.payload;
+    const findings = Array.isArray(payload.findings) ? payload.findings : [];
+    const result = [];
+    for (const raw of findings) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const finding = raw;
+        if (finding.blocking !== true)
+            continue;
+        if (typeof finding.id !== "string" || finding.id.trim() === "")
+            continue;
+        if (finding.type !== "implementation" && finding.type !== "spec" && finding.type !== "mixed")
+            continue;
+        const id = finding.id;
+        result.push({
+            id,
+            type: finding.type,
+            finding,
+            decision: latestCodeReviewDecision(events, codeReviewDecisionScope(jobId, id)),
+        });
+    }
+    return result;
+}
+export function latestCodeReviewFailedStatus(events) {
+    const facts = collectCodeReviewGateFacts(events);
+    const terminal = facts.latestTerminal;
+    if (!terminal || terminal.state !== "rejected" || terminal.result_kind !== "review_failed")
+        return null;
+    const findings = blockingFindingsFromReviewFailed(terminal.event, terminal.job.job_id, events);
+    const dismissed = findings.filter(item => item.decision?.answer === "dismiss");
+    const unresolved = findings.filter(item => item.decision?.answer !== "dismiss");
+    return { terminal, findings, unresolved, dismissed };
+}
+export function dismissedCodeReviewSummary(status) {
+    const details = status.dismissed
+        .map(item => `${item.id}：${item.decision?.reason || "主流程已驳回该问题"}`)
+        .join("；");
+    return details
+        ? `上一次代码审查提出的问题已被主流程复核驳回：${details}。没有新的具体证据时，不要重复提出同一问题。`
+        : "上一次代码审查提出的问题已被主流程复核驳回。没有新的具体证据时，不要重复提出同一问题。";
+}
+export function currentApplyDoneCycleStart(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.to_state === "apply_done" && payload.from_state !== "apply_done")
+            return i;
+    }
+    return 0;
+}
+export function collectCodeReviewGateFacts(events) {
+    const cycleStartIndex = currentApplyDoneCycleStart(events);
+    const jobs = [];
+    const jobsById = new Map();
+    const terminalResults = [];
+    const terminalJobIds = new Set();
+    for (let i = cycleStartIndex; i < events.length; i++) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const newJobs = ev.payload.new_jobs ?? [];
+        for (const job of newJobs) {
+            if (!isCodeReviewerJob(job))
+                continue;
+            jobs.push(job);
+            jobsById.set(job.job_id, job);
+        }
+    }
+    for (let i = cycleStartIndex; i < events.length; i++) {
+        const ev = events[i];
+        if (ev.event_type !== "job_accepted" && ev.event_type !== "job_rejected")
+            continue;
+        const payload = ev.payload;
+        if (typeof payload.job_id !== "string")
+            continue;
+        const job = jobsById.get(payload.job_id);
+        if (!job)
+            continue;
+        terminalJobIds.add(job.job_id);
+        terminalResults.push({
+            job,
+            event: ev,
+            state: ev.event_type === "job_accepted" ? "accepted" : "rejected",
+            result_kind: ev.event_type === "job_rejected"
+                ? codeReviewResultKind(payload.result_kind) ?? "invalid_report"
+                : undefined,
+            reason: typeof payload.reason === "string" ? payload.reason : undefined,
+        });
+    }
+    let consecutiveRejected = 0;
+    for (let i = terminalResults.length - 1; i >= 0; i--) {
+        const result = terminalResults[i];
+        if (result.state !== "rejected")
+            break;
+        if (result.result_kind !== "invalid_report" && result.result_kind !== "non_actionable_report")
+            break;
+        consecutiveRejected += 1;
+    }
+    const latestTerminal = terminalResults.at(-1) ?? null;
+    const latestRejected = [...terminalResults].reverse().find(result => result.state === "rejected") ?? null;
+    return {
+        cycleStartIndex,
+        jobs,
+        openJobs: jobs.filter(job => !terminalJobIds.has(job.job_id)),
+        terminalResults,
+        latestTerminal,
+        latestRejected,
+        consecutiveRejected,
+    };
+}
+export function latestApplyDoneToReviewGate(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 !== "review-ready")
+            continue;
+        if (payload.from_state !== "apply_done" || payload.to_state !== "review")
+            continue;
+        const gate = payload.code_review_gate;
+        if (!gate || (gate.decision !== "passed" && gate.decision !== "skipped"))
+            return null;
+        return {
+            decision: gate.decision,
+            ...(typeof gate.job_id === "string" ? { job_id: gate.job_id } : {}),
+            ...(typeof gate.reason === "string" ? { reason: gate.reason } : {}),
+        };
+    }
+    return null;
+}
+export function requiresFinalVerifierForCurrentReview(events) {
+    return latestApplyDoneToReviewGate(events) != null;
+}

package/dist/format.js

@@ -127,15 +127,25 @@ export function tasksStructureDigest(content, sha256Text) {
 //     "cwd": "/path",
 //     "exit_code": 1,
 //     "semantic_status": "expected_failure",
+//     "covers_task_ids": ["TASK-001"],
 //     "target_fingerprint": "sha256:..."
 //   }
 //
-// 引擎校验：test_id + task_structure_digest 必填，其余可选
+// 引擎校验：test_id + task_structure_digest 必填，covers_task_ids 如存在必须是非空字符串数组，其余可选
 export function validateTestRunInput(tr) {
     if (!tr.test_id)
         return { ok: false, message: "缺少 test_id" };
     if (!tr.task_structure_digest)
         return { ok: false, message: "缺少 task_structure_digest" };
+    if (tr.covers_task_ids !== undefined) {
+        if (!Array.isArray(tr.covers_task_ids))
+            return { ok: false, message: "covers_task_ids 必须是字符串数组" };
+        if (tr.covers_task_ids.length === 0)
+            return { ok: false, message: "covers_task_ids 不能是空数组" };
+        if (!tr.covers_task_ids.every(item => typeof item === "string" && item.trim().length > 0)) {
+            return { ok: false, message: "covers_task_ids 不能包含空字符串或非字符串" };
+        }
+    }
     return { ok: true, message: "" };
 }
 // ===== user-decision JSON =====

package/dist/next.js

@@ -4,6 +4,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { readEvents, sha256Text } from "./store.js";
 import { isFreshReviewVerifier, isReviewReadyVerifier, 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 { requiredJobActions } from "./job_action.js";
 import { validateDiscovery, countDiscoveryOpenQuestions, collectProposeOpenQuestions, parseTasksMd, pendingTasksInContent } from "./format.js";
 const ACTIVE_PROPOSAL_REVIEW_ROLES = new Set(["critic", "architect", "test-engineer"]);
@@ -212,6 +213,83 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
             if (snapshot.open_jobs.length > 0) {
                 return requiredJobsOutput("apply_done", change, snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项`);
             }
+            const events = readEvents(projectRoot, change);
+            const facts = collectCodeReviewGateFacts(events);
+            const latest = facts.latestTerminal;
+            if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
+                const status = latestCodeReviewFailedStatus(events);
+                const pending = status?.unresolved[0] ?? null;
+                if (status && status.findings.length > 0 && !pending) {
+                    return {
+                        state: "apply_done",
+                        path: "next_command",
+                        next_command: transitionCommand(change, "review-ready", riskFlag(defaultRisk)),
+                        reason: "代码审查问题已被主流程复核驳回，重新发起代码审查",
+                        missing_inputs: [],
+                    };
+                }
+                const findingId = pending?.id ?? "";
+                const type = pending?.type;
+                const decision = pending?.decision;
+                if (findingId && type === "implementation") {
+                    return {
+                        state: "apply_done",
+                        path: "next_command",
+                        next_command: transitionCommand(change, "reopen", `--to apply --review-fix ${latest.job.job_id}#${findingId} --reason "修复代码审查问题 ${findingId}"`),
+                        reason: `代码审查发现纯代码实现问题 ${findingId}，回到实现阶段修复`,
+                        missing_inputs: [],
+                    };
+                }
+                if (findingId && (type === "spec" || type === "mixed")) {
+                    if (decision?.answer === "reopen_propose") {
+                        return {
+                            state: "apply_done",
+                            path: "next_command",
+                            next_command: transitionCommand(change, "reopen", `--to propose --review-finding ${latest.job.job_id}#${findingId} --reason "根据代码审查问题 ${findingId} 回到计划阶段"`),
+                            reason: `使用者已确认问题 ${findingId} 需要回到计划阶段`,
+                            missing_inputs: [],
+                        };
+                    }
+                    if (decision?.answer === "reopen_apply") {
+                        return {
+                            state: "apply_done",
+                            path: "next_command",
+                            next_command: transitionCommand(change, "reopen", `--to apply --review-fix ${latest.job.job_id}#${findingId} --reason "根据代码审查问题 ${findingId} 回到实现阶段修复"`),
+                            reason: `使用者已确认问题 ${findingId} 直接回到实现阶段修复`,
+                            missing_inputs: [],
+                        };
+                    }
+                    const problemKind = type === "spec"
+                        ? "方案或需求文档可能需要调整"
+                        : "代码实现和方案文档都可能有关";
+                    const ask = {
+                        question: `代码审查发现问题 ${findingId}：${problemKind}。请选择回到计划阶段修改文档、确认现有文档方向不变并回到实现阶段修代码，或驳回该问题；无论选择哪一项都必须写明原因。`,
+                        allowed_answers: [
+                            CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_propose,
+                            CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_apply,
+                            CODE_REVIEW_DECISION_ANSWER_LABELS.dismiss,
+                        ],
+                        scope: codeReviewDecisionScope(latest.job.job_id, findingId),
+                    };
+                    return { state: "apply_done", path: "ask_user", ask_user: ask, reason: `代码审查发现需要使用者判断的问题 ${findingId}` };
+                }
+                const ask = {
+                    question: "代码审查报告里缺少可用于处理问题的编号或分类。请修正审查报告后重新执行 review-ready。",
+                    allowed_answers: ["报告已修正"],
+                    scope: `${CODE_REVIEW_REPAIR_SCOPE_PREFIX}${change}`,
+                };
+                return { state: "apply_done", path: "ask_user", ask_user: ask, reason: "代码审查报告中的阻塞问题无法处理" };
+            }
+            if (latest?.state === "rejected" &&
+                (latest.result_kind === "invalid_report" || latest.result_kind === "non_actionable_report") &&
+                facts.consecutiveRejected >= 2) {
+                const ask = {
+                    question: "代码审查报告连续两次不符合要求，或者没有给出可处理的问题。请先修正报告生成方式、模板或审查口径；修正后仍可显式执行 review-ready。",
+                    allowed_answers: ["已修正"],
+                    scope: `${CODE_REVIEW_REPAIR_SCOPE_PREFIX}${change}`,
+                };
+                return { state: "apply_done", path: "ask_user", ask_user: ask, reason: "代码审查报告连续不符合要求或没有可处理问题" };
+            }
             return {
                 state: "apply_done",
                 path: "next_command",
@@ -246,7 +324,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                     missing_inputs: [],
                 };
             }
-            if (policy.requires_verifier) {
+            if (requiresFinalVerifierForCurrentReview(events) || policy.requires_verifier) {
                 const currentEvidenceDigest = reviewEvidenceDigest(events);
                 const verifierAccepted = snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest));
                 if (!verifierAccepted) {
@@ -254,7 +332,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                         state: "review",
                         path: "next_command",
                         next_command: transitionCommand(change, "review-ready", riskFlag(defaultRisk)),
-                        reason: "缺少 fresh verifier，先补最终验证",
+                        reason: "最终验证已经缺失或不再匹配当前证据，先补最终验证",
                         missing_inputs: [],
                     };
                 }