@peterxiaoyang/superspec 0.1.49 → 0.1.50

package/dist/code_review.d.ts

@@ -1,4 +1,4 @@
-import type { CodeReviewGateEvidence, CodeReviewResultKind, CodeReviewScope, CodeStateCheck, CoverageExemptionRef, Event, Job, JobPacketContext, Ref, ReviewPreviousRejection, TaskExecutionIndexEntry } from "./types.ts";
+import type { CodeReviewGateEvidence, CodeReviewResultKind, CodeReviewScope, CodeStateCheck, CoverageExemptionRef, DirtyFileFingerprint, Event, Job, JobPacketContext, Ref, ReviewPreviousRejection, TaskExecutionIndexEntry } 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 declare const TEST_COVERAGE_EXEMPTION_SCOPE_PREFIX = "test_coverage_exemption:";
@@ -47,15 +47,19 @@ export interface CodeReviewGateFacts {
 export declare function scanCodeChanges(projectRoot: string): CodeChangeScan;
 export declare function currentCodeReviewWorkingPaths(projectRoot: string, events: Event[], extraIgnoredPaths?: string[]): string[];
 export declare function knownCodeReviewReportPaths(projectRoot: string, events: Event[]): Set<string>;
-export declare function selectCodeReviewBase(events: Event[]): {
+interface CodeReviewBase {
     base_head: string | null;
-    kind: "reviewed" | "start_apply" | "empty_tree" | "history_missing";
+    kind: "reviewed" | "task_start" | "start_apply" | "empty_tree" | "history_missing";
     reason: string;
-};
+    dirty_files?: DirtyFileFingerprint[];
+    reviewed_files?: Ref[];
+    required_recheck_paths?: string[];
+}
+export declare function selectCodeReviewBase(events: Event[]): CodeReviewBase;
 export declare function scanCodeReviewScope(projectRoot: string, events: Event[]): CodeReviewScope;
 export declare function scanCodeChangesForReview(projectRoot: string, events: Event[]): 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 codeReviewJobStaleReason(projectRoot: string, job: Job, currentPaths?: string[], events?: Event[], extraIgnoredPaths?: string[]): string | null;
 export declare function codeReviewPacketDigest(input: {
     role: "code-reviewer";
     gate_id?: "review.code_review";
@@ -94,3 +98,4 @@ export declare function latestApplyDoneToReviewGate(events: Event[]): {
 export declare function latestCodeReviewGateEvidence(events: Event[]): CodeReviewGateEvidence | null;
 export declare function requiresFinalVerifierForCurrentReview(events: Event[]): boolean;
 export declare function computeCodeStateCheck(projectRoot: string, events: Event[], ignoredCodePaths?: string[]): CodeStateCheck;
+export {};

package/dist/code_review.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { findLatestEvent, sha256File, sha256Text } from "./store.js";
 import { REVIEW_CODE_REVIEW_GATE } from "./review_job_gates.js";
-import { codeFileContentSha, currentGitHead, diffFingerprints, dirtyCodePaths, gitLines, isCodeLikePath, projectHasReadableDirectory, walkCodeFiles, } from "./git_state.js";
+import { codeFileContentSha, currentGitHead, diffFingerprints, dirtyCodeFiles, dirtyCodePaths, gitLines, isCodeLikePath, projectHasReadableDirectory, walkCodeFiles, } from "./git_state.js";
 import { parseExecutionRequirements, parseTestContractEntries } from "./format.js";
 export const CODE_REVIEW_REPAIR_SCOPE_PREFIX = "code_reviewer_report_repair:";
 export const CODE_REVIEW_DECISION_SCOPE_PREFIX = "code_review_decision:";
@@ -88,32 +88,101 @@ function firstStartApplyHead(events) {
     }
     return { present: false, head: null, reason: "没有 apply_start_head" };
 }
-function latestReviewedHead(events) {
+function latestReviewAttemptBase(events) {
+    const jobs = new Map();
+    let latest = null;
+    let startIndex = 0;
     for (let i = events.length - 1; i >= 0; i--) {
         const ev = events[i];
-        if (ev.event_type !== "transition_commit")
+        if (ev.event_type === "transition_commit" && ev.payload.transition === "start-apply") {
+            startIndex = i;
+            break;
+        }
+    }
+    for (let i = startIndex; i < events.length; i++) {
+        const ev = events[i];
+        if (ev.event_type === "transition_commit") {
+            for (const job of ev.payload.new_jobs ?? []) {
+                if (isCodeReviewerJob(job))
+                    jobs.set(job.job_id, job);
+            }
+            const gate = ev.payload.code_review_gate;
+            if (gate?.decision === "skipped" && typeof gate.head === "string" && gate.head.trim() !== "") {
+                latest = { base_head: gate.head, kind: "reviewed", reason: "latest_code_review_gate" };
+            }
+            continue;
+        }
+        if (ev.event_type !== "job_accepted" && ev.event_type !== "job_rejected")
             continue;
         const payload = ev.payload;
-        const gate = payload.code_review_gate;
-        if (!gate)
+        if (typeof payload.job_id !== "string")
             continue;
-        if (gate.decision === "passed") {
-            if (typeof gate.current_head !== "string" || gate.current_head.trim() === "")
-                continue;
-            return { present: true, head: gate.current_head };
-        }
-        if (gate.decision === "skipped") {
-            if (typeof gate.head !== "string" || gate.head.trim() === "")
-                continue;
-            return { present: true, head: gate.head };
+        const job = jobs.get(payload.job_id);
+        const scope = job?.packet_context?.code_review_scope;
+        if (!job || !scope || !("current_head" in scope))
+            continue;
+        const reusable = ev.event_type === "job_accepted" || payload.result_kind === "review_failed";
+        if (!reusable)
+            continue;
+        const findings = ev.payload.findings;
+        const requiredRecheckPaths = Array.isArray(findings)
+            ? findings.flatMap(raw => {
+                if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                    return [];
+                const refs = raw.source_refs;
+                if (!Array.isArray(refs))
+                    return [];
+                return refs.flatMap(ref => {
+                    if (typeof ref !== "string")
+                        return [];
+                    const match = /^(.+?)(?::\d+(?::\d+)?)?$/.exec(ref.trim());
+                    return match && isCodeLikePath(match[1]) ? [normalizeKnownPath(match[1])] : [];
+                });
+            })
+            : [];
+        latest = {
+            base_head: scope.current_head ?? null,
+            kind: "reviewed",
+            reason: "latest_code_review_attempt",
+            reviewed_files: job.boundFiles,
+            required_recheck_paths: uniqSorted(requiredRecheckPaths),
+        };
+    }
+    return latest;
+}
+function firstTaskBoundaryInCurrentApply(events) {
+    let startIndex = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        if (ev.payload.transition === "start-apply") {
+            startIndex = i;
+            break;
         }
     }
-    return { present: false, head: null };
+    for (let i = startIndex + 1; i < events.length; i++) {
+        if (events[i].event_type !== "task_started")
+            continue;
+        const boundary = boundaryFromPayload(events[i].payload);
+        if (boundary)
+            return boundary;
+    }
+    return null;
 }
 export function selectCodeReviewBase(events) {
-    const reviewed = latestReviewedHead(events);
-    if (reviewed.present)
-        return { base_head: reviewed.head, kind: "reviewed", reason: "latest_code_review_gate" };
+    const reviewed = latestReviewAttemptBase(events);
+    if (reviewed)
+        return reviewed;
+    const taskBoundary = firstTaskBoundaryInCurrentApply(events);
+    if (taskBoundary) {
+        return {
+            base_head: taskBoundary.head,
+            kind: "task_start",
+            reason: "first_task_boundary",
+            dirty_files: taskBoundary.dirty_files,
+        };
+    }
     const firstStart = firstStartApplyHead(events);
     if (!firstStart.present)
         return { base_head: null, kind: "history_missing", reason: firstStart.reason };
@@ -148,17 +217,54 @@ function scanCodeReviewScopeFromBase(projectRoot, base, ignoredPaths = new Set()
             }
         }
     }
-    const staged = gitLines(projectRoot, ["diff", "--name-only", "--cached"]);
-    const unstaged = gitLines(projectRoot, ["diff", "--name-only"]);
-    const untracked = gitLines(projectRoot, ["ls-files", "--others", "--exclude-standard"]);
-    if (!staged.ok || !unstaged.ok || !untracked.ok) {
-        scopeReliable = false;
-        scopeReason = [scopeReason, !staged.ok ? staged.reason : "", !unstaged.ok ? unstaged.reason : "", !untracked.ok ? untracked.reason : ""]
-            .filter(Boolean)
-            .join("; ");
-    }
-    const worktreePaths = excludeKnownPaths(uniqSorted([...(staged.ok ? staged.lines : []), ...(unstaged.ok ? unstaged.lines : [])]), ignoredPaths);
-    const untrackedPaths = excludeKnownPaths(uniqSorted(untracked.ok ? untracked.lines : []), ignoredPaths);
+    let worktreePaths;
+    let untrackedPaths;
+    if (base.dirty_files) {
+        const dirty = dirtyCodeFiles(projectRoot);
+        if (!dirty.ok) {
+            scopeReliable = false;
+            scopeReason = [scopeReason, dirty.reason].filter(Boolean).join("; ");
+            worktreePaths = [];
+        }
+        else {
+            worktreePaths = excludeKnownPaths(uniqSorted(diffFingerprints(base.dirty_files, dirty.files)), ignoredPaths);
+        }
+        untrackedPaths = [];
+    }
+    else if (base.reviewed_files) {
+        const dirty = dirtyCodePaths(projectRoot);
+        if (!dirty.ok) {
+            scopeReliable = false;
+            scopeReason = [scopeReason, dirty.reason].filter(Boolean).join("; ");
+            worktreePaths = [];
+        }
+        else {
+            const reviewed = new Map(base.reviewed_files.map(file => [file.path, file.sha]));
+            const changedReviewed = base.reviewed_files
+                .filter(file => (codeFileContentSha(projectRoot, file.path) ?? "sha256:missing") !== file.sha)
+                .map(file => file.path);
+            const newlyChanged = dirty.paths.filter(path => !reviewed.has(path));
+            worktreePaths = excludeKnownPaths(uniqSorted([
+                ...changedReviewed,
+                ...newlyChanged,
+                ...(base.required_recheck_paths ?? []),
+            ]), ignoredPaths);
+        }
+        untrackedPaths = [];
+    }
+    else {
+        const staged = gitLines(projectRoot, ["diff", "--name-only", "--cached"]);
+        const unstaged = gitLines(projectRoot, ["diff", "--name-only"]);
+        const untracked = gitLines(projectRoot, ["ls-files", "--others", "--exclude-standard"]);
+        if (!staged.ok || !unstaged.ok || !untracked.ok) {
+            scopeReliable = false;
+            scopeReason = [scopeReason, !staged.ok ? staged.reason : "", !unstaged.ok ? unstaged.reason : "", !untracked.ok ? untracked.reason : ""]
+                .filter(Boolean)
+                .join("; ");
+        }
+        worktreePaths = excludeKnownPaths(uniqSorted([...(staged.ok ? staged.lines : []), ...(unstaged.ok ? unstaged.lines : [])]), ignoredPaths);
+        untrackedPaths = excludeKnownPaths(uniqSorted(untracked.ok ? untracked.lines : []), ignoredPaths);
+    }
     const fallbackPaths = projectHasReadableDirectory(projectRoot)
         ? excludeKnownPaths(walkCodeFiles(projectRoot).sort(), ignoredPaths)
         : [];
@@ -181,7 +287,8 @@ export function scanCodeReviewScope(projectRoot, events) {
 }
 export function scanCodeChangesForReview(projectRoot, events) {
     const scope = scanCodeReviewScope(projectRoot, events);
-    const hasCodeChanges = !scope.scope_reliable ||
+    const hasReviewHistory = collectCodeReviewGateFacts(events).jobs.length > 0;
+    const hasCodeChanges = hasReviewHistory || !scope.scope_reliable ||
         scope.committed_paths == null ||
         scope.committed_paths.length > 0 ||
         scope.worktree_paths.length > 0 ||
@@ -202,7 +309,16 @@ function samePathSet(left, right) {
     const b = [...new Set(right)].sort();
     return a.length === b.length && a.every((path, index) => path === b[index]);
 }
-export function codeReviewJobStaleReason(projectRoot, job, currentPaths) {
+function currentPathsForFrozenCodeReview(projectRoot, events, job, extraIgnoredPaths = []) {
+    const creationIndex = events.findIndex(ev => ev.event_type === "transition_commit" &&
+        (ev.payload.new_jobs ?? []).some(candidate => candidate.job_id === job.job_id));
+    const priorEvents = creationIndex >= 0 ? events.slice(0, creationIndex) : events;
+    const ignored = knownCodeReviewReportPaths(projectRoot, events);
+    for (const path of extraIgnoredPaths)
+        ignored.add(normalizeKnownPath(path));
+    return scanCodeReviewScopeFromBase(projectRoot, selectCodeReviewBase(priorEvents), ignored).review_paths;
+}
+export function codeReviewJobStaleReason(projectRoot, job, currentPaths, events, extraIgnoredPaths = []) {
     if (!isCodeReviewerJob(job))
         return null;
     const frozenScope = job.packet_context?.code_review_scope;
@@ -211,10 +327,14 @@ export function codeReviewJobStaleReason(projectRoot, job, currentPaths) {
         if (frozenScope.current_head !== currentHead.head) {
             return `代码审查创建后的 HEAD 已变化（原记录：${frozenScope.current_head ?? "<none>"}；当前：${currentHead.head ?? "<none>"}）`;
         }
-        const currentWorkingPaths = currentPaths ?? scanCodeChanges(projectRoot).paths;
-        const frozenWorkingPaths = uniqSorted([...frozenScope.worktree_paths, ...frozenScope.untracked_paths]);
-        if (!samePathSet(frozenWorkingPaths, currentWorkingPaths)) {
-            return `代码审查范围已变化：工作区范围已变化（原范围：${frozenWorkingPaths.join(", ") || "<none>"}；当前范围：${currentWorkingPaths.join(", ") || "<none>"}）`;
+        const currentScopePaths = events
+            ? currentPathsForFrozenCodeReview(projectRoot, events, job, extraIgnoredPaths)
+            : currentPaths ?? scanCodeChanges(projectRoot).paths;
+        const frozenScopePaths = events
+            ? frozenScope.review_paths
+            : uniqSorted([...frozenScope.worktree_paths, ...frozenScope.untracked_paths]);
+        if (!samePathSet(frozenScopePaths, currentScopePaths)) {
+            return `代码审查范围已变化：工作区范围已变化（原范围：${frozenScopePaths.join(", ") || "<none>"}；当前范围：${currentScopePaths.join(", ") || "<none>"}）`;
         }
         for (const bound of job.boundFiles) {
             const currentSha = codeFileContentSha(projectRoot, bound.path) ?? "sha256:missing";

package/dist/job_validity.js

@@ -12,7 +12,7 @@ function reviewReadyVerifierWithoutEvidenceReason(job) {
 }
 export function invalidReasonForSnapshot(input) {
     if (input.job.role === "code-reviewer") {
-        return codeReviewJobStaleReason(input.projectRoot, input.job, currentCodeReviewWorkingPaths(input.projectRoot, input.events));
+        return codeReviewJobStaleReason(input.projectRoot, input.job, currentCodeReviewWorkingPaths(input.projectRoot, input.events), input.events);
     }
     const invalidReviewReadyVerifier = reviewReadyVerifierWithoutEvidenceReason(input.job);
     if (invalidReviewReadyVerifier)
@@ -25,7 +25,10 @@ export function invalidReasonForSubmittedReport(job, context) {
             ...(context.ignoredCodePaths ?? []),
             ...(context.reportPath ? [context.reportPath] : []),
         ]);
-        return codeReviewJobStaleReason(context.projectRoot, job, currentPaths);
+        return codeReviewJobStaleReason(context.projectRoot, job, currentPaths, context.events, [
+            ...(context.ignoredCodePaths ?? []),
+            ...(context.reportPath ? [context.reportPath] : []),
+        ]);
     }
     const invalidReviewReadyVerifier = reviewReadyVerifierWithoutEvidenceReason(job);
     if (invalidReviewReadyVerifier)

package/dist/phase_plan.js

@@ -778,7 +778,7 @@ 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)
+        .filter(job => codeReviewJobStaleReason(projectRoot, job, currentWorkingPaths, events) == null)
         .map(job => job.job_id));
     return snapshot.open_jobs.filter(job => job.role !== "code-reviewer" || freshCodeReviewJobIds.has(job.job_id));
 }
@@ -802,7 +802,7 @@ function planApplyDoneNext(context) {
     }
     const latest = facts.latestTerminal;
     if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
-        const staleReason = codeReviewJobStaleReason(context.projectRoot, latest.job, currentWorkingPaths);
+        const staleReason = codeReviewJobStaleReason(context.projectRoot, latest.job, currentWorkingPaths, events);
         if (staleReason) {
             return {
                 kind: "run_transition",
@@ -903,7 +903,7 @@ function planApplyDoneNext(context) {
         : undefined;
     const acceptedCurrentHead = acceptedScope?.current_head;
     const acceptedReviewReady = latest?.state === "accepted" &&
-        codeReviewJobStaleReason(context.projectRoot, latest.job, currentWorkingPaths) == null && (acceptedCurrentHead === null ||
+        codeReviewJobStaleReason(context.projectRoot, latest.job, currentWorkingPaths, events) == null && (acceptedCurrentHead === null ||
         (typeof acceptedCurrentHead === "string" && acceptedCurrentHead.trim() !== ""));
     if (!codeScan.hasCodeChanges || acceptedReviewReady) {
         const confirmation = phaseConfirmationStep(context, "apply_to_review", "Apply 与代码审查完成，等待用户确认进入最终审查");

package/dist/record.js

@@ -102,7 +102,7 @@ function reviewScopeInstruction(job, reviewTargets, readOnlyRefs) {
 function genericReviewCoverageInstruction(job) {
     if (!requiresReviewScope(job))
         return "";
-    return "完整审查全部 boundFiles，不因发现第一个 blocker 停止；read_only_refs 只在核对本次问题与上下游一致性时读取。review_scope.checked_paths 必须回执已浏览的全部 boundFiles，但该回执不能代替语义审查，也不扩大可报告问题的范围。";
+    return "完整审查全部 boundFiles，不因发现第一个 blocker 停止；read_only_refs 只在核对本次问题与上下游一致性时读取。review_scope.checked_paths 只填写本次实际浏览并完成语义审查的绑定文件，不能根据 packet 预填；未检查项如实写入 unchecked。覆盖回执不能代替语义审查，也不扩大可报告问题的范围。";
 }
 function proposalIncrementalReviewInstruction(job) {
     if (!PROPOSE_FINAL_REVIEW_GATE.isJobForGate(job))
@@ -317,6 +317,9 @@ function validateCodeReviewScope(obj, job, checks) {
                 checks.push(`代码审查报告未说明是否检查了 ${bound.path}`);
             }
         }
+        if (obj.verdict === "pass" && uncheckedPaths.size > 0) {
+            checks.push("代码审查结论为 pass 时不能包含未检查的绑定文件");
+        }
     }
 }
 function validateReviewScope(obj, job, checks) {
@@ -991,7 +994,7 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
             ? 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))
+            ? codeReviewJobStaleReason(projectRoot, status.terminal.job, currentCodeReviewWorkingPaths(projectRoot, events), events)
             : null;
         if (!ref || snapshot.state !== "apply_done" || !status || !finding || staleReason) {
             const reason = !ref
@@ -1231,7 +1234,7 @@ export function jobsPacket(projectRoot, change, jobId) {
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
                 `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仅作备用。${recordInputInstruction(job)}协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
                 (isCodeReviewer
-                    ? `最小格式：{"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>"}。`
+                    ? `格式骨架：{"role":"code-reviewer","verdict":"pass","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":[],"checked_docs":[],"unchecked":[]},"findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}。提交前按真实审查结果填写数组；不得从 boundFiles 自动复制 checked_paths。verdict 只能为 pass 或 fail；审查覆盖范围（review_scope）用来说明本次审查覆盖了哪些文件和文档，已检查路径（checked_paths）与未检查项（unchecked）必须合起来覆盖全部绑定文件（boundFiles），unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}；pass 不允许仍有未检查的绑定文件。`
                         + `报告结论为 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；fix 非空表示状态机创建的实现修复，source、parent_task_id 和 reason 说明其归属，code_review 来源还需核对 review_finding；每项的 scope_note 是执行者登记的范围扩大说明，判断其合理性与验证充分性；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动逐个判断合理性；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。`

package/dist/transition.js

@@ -428,8 +428,8 @@ function fixDescriptorForTask(events, taskId) {
         }
         : null;
 }
-function isFreshOpenCodeReviewerJob(job, projectRoot, currentWorkingPaths) {
-    return codeReviewJobStaleReason(projectRoot, job, currentWorkingPaths) == null;
+function isFreshOpenCodeReviewerJob(job, projectRoot, events, currentWorkingPaths) {
+    return codeReviewJobStaleReason(projectRoot, job, currentWorkingPaths, events) == null;
 }
 function hasFrozenCodeReviewCurrentHead(scope) {
     if (!scope || typeof scope !== "object")
@@ -444,7 +444,7 @@ function evaluateApplyDoneCodeReviewGate(input) {
     const facts = collectCodeReviewGateFacts(input.events);
     if (scan.hasCodeChanges) {
         const currentWorkingPaths = currentCodeReviewWorkingPaths(input.projectRoot, input.events);
-        const freshOpenJobs = facts.openJobs.filter(job => isFreshOpenCodeReviewerJob(job, input.projectRoot, currentWorkingPaths));
+        const freshOpenJobs = facts.openJobs.filter(job => isFreshOpenCodeReviewerJob(job, input.projectRoot, input.events, currentWorkingPaths));
         if (freshOpenJobs.length > 0) {
             return {
                 blocked: true,
@@ -455,7 +455,7 @@ function evaluateApplyDoneCodeReviewGate(input) {
         const latest = facts.latestTerminal;
         if (latest?.state === "accepted") {
             const acceptedScope = latest.job.packet_context?.code_review_scope;
-            const staleReason = codeReviewJobStaleReason(input.projectRoot, latest.job, currentWorkingPaths);
+            const staleReason = codeReviewJobStaleReason(input.projectRoot, latest.job, currentWorkingPaths, input.events);
             if (staleReason || !hasFrozenCodeReviewCurrentHead(acceptedScope)) {
                 const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.changeRoot, input.events);
                 return {
@@ -485,7 +485,7 @@ function evaluateApplyDoneCodeReviewGate(input) {
             };
         }
         if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
-            const staleReason = codeReviewJobStaleReason(input.projectRoot, latest.job, currentWorkingPaths);
+            const staleReason = codeReviewJobStaleReason(input.projectRoot, latest.job, currentWorkingPaths, input.events);
             if (staleReason) {
                 const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.changeRoot, input.events);
                 return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": {

package/templates/workflow/AGENTS.md

@@ -17,6 +17,8 @@ Explore 中需要用户决定业务、验收、范围或关键取舍时，先简
 
 计划材料没有枚举某个类、继承关系、方法或局部实现细节，不等于计划遗漏。只要正确修法能够由既有 task、已批准行为和仓库事实唯一推导，仍属于 Apply；只有需要重新决定公共接口、数据归属、迁移兼容、实现路线、验收或 task 边界时才回 Propose。
 
+Apply 以满足已批准行为的最小语义影响面为成功标准。需求未要求改变的公共契约、共享行为和兼容语义应保持不变；扩大公共实现边界必须有当前 task 和真实调用链支持。最小改动不能成为遗漏已确认消费者或验收路径的理由。
+
 - 当前 task 尚未完成时，在其范围内直接修复；不要为同一实现问题新增 task 或回 propose。
 - 所有 task 已完成后，若问题仍能关联一个已完成 task、且不改变已批准行为和方案，主流程执行 `superspec transition reopen --change "<change>" --to apply --self-test-fix "<task>" --reason "<reason>"`，让工作流创建修复事项；随后继续 `next`，不得手改 tasks。
 - 无法关联既有 task，或需要改变行为、验收、接口、数据语义或实现路线时，才回 propose。

package/templates/workflow/prompts/code-reviewer.md

@@ -7,13 +7,13 @@ argument-hint: "本次代码审查说明"
 
 ## 角色
 
-你是 Code Reviewer。你独立、只读地审查本次实现是否符合已批准计划，找出真实 bug、边界条件、安全/性能/兼容问题、关键测试缺口和无关改动。
+你是 Code Reviewer。你独立、只读地审查本次实现是否以最小语义影响兑现已批准计划，找出真实 bug、范围遗漏、边界条件、安全/性能/兼容问题、关键测试缺口和无关改动。
 
 ## 工作边界
 
 - 先读任务说明、指定代码范围和相关计划材料；范围和停止条件以任务说明为准。不要把未打开的材料当作审查依据。
 - 只读；不实现修复、不修改计划或证据、不自行宣布完成。上下文不足时明确指出缺口。
-- 修复复核优先验证原问题是否被修复；新 blocker 必须由修复直接引入并有证据。
+- 修复复核优先关闭原问题，并审查本次变化及其直接影响链路。此前漏报的问题只有在当前代码中存在直接证据、影响既定验收或兼容边界时才能成为新 blocker；不要重新打开与本次修复无关、未变化的模块。
 
 ## 审查判断
 
@@ -23,11 +23,12 @@ argument-hint: "本次代码审查说明"
 
 - 实现是否兑现当前任务的验收和边界，且与已批准的方案/规格一致。
 - 是否引入功能、数据、一致性、安全、权限、性能或兼容问题，以及直接的边界条件遗漏。
-- 改动范围是否包含与当前目标无关的代码，或隐含新增能力、用户可见行为和未计划依赖。
+- 改动是否覆盖计划及真实调用链已经确认的直接影响，并且每项语义变化都有必要性证据。任务勾选和测试通过不能替代对遗漏路径与无关改动的判断。
+- 文件或代码数量本身不是问题。局部需求改变无关生产行为、扩大共享边界或夹带重构时，只有能够证明这些变化并非当前验收所必需，才作为过度实现问题。
 - 测试是否实际证明相关行为和直接回归风险，而非只存在一条通过记录。
 - 需求源已更新时，代码是否仍在执行过期计划；此类问题按方案或需求缺口归因，不把旧材料当作当前依据。
 
-风格偏好、无证据的猜测、历史无关问题和“另一种写法更优雅”不阻塞。
+风格偏好、无证据的猜测、历史无关问题和“另一种写法更优雅”不阻塞。不要用“最小改动”要求遗漏批准范围。
 
 将问题归因为：纯实现问题（可回 apply 修复）、方案/需求问题（计划不能支持正确实现）或混合问题（需要主流程处理分歧），并说明依据。不要用审查建议创造新的需求或架构。
 

package/templates/workflow/skills/superspec-apply/SKILL.md

@@ -8,7 +8,7 @@ metadata:
 
 # SuperSpec Apply
 
-按当前 change 的已批准 task 完成小范围实现和真实验证。Apply 只执行已批准计划，不把发现的新需求悄悄带进代码。
+按当前 change 的已批准 task 完成小范围实现和真实验证。Apply 只执行已批准计划，不把发现的新需求悄悄带进代码。实现目标是在满足验收的同时保持最小语义影响面，而不只是让最终功能可用。
 
 ## 工作方式
 
@@ -17,7 +17,7 @@ metadata:
 每个 task 使用同一循环：
 
 1. 开始 task 前先检查当前工作区变化，并沿 task 引用链核对发生变化的需求源或计划材料；确认要实现的行为、边界和相关测试仍与当前计划一致。新变化使已批准行为、验收、边界或方案失效时，不按旧计划继续，停止实现并交回 Propose。
-2. 在授权范围内实现最小改动；不要提前修改计划材料或扩大范围。
+2. 在授权范围内实现最小改动；不要提前修改计划材料或扩大范围。优先复用现有边界或作局部适配，保持未被需求要求改变的公共接口、共享工具、默认行为和兼容语义不变。
 3. 完成当前 task 要求的验证，如实报告测试、环境或覆盖不足的结果。
 4. 当前 task 完成后立即继续工作流并处理下一事项；不要总结交付或等待用户再次要求继续。
 
@@ -25,6 +25,14 @@ metadata:
 
 不要伪造完成结果、验证材料或审查结论。
 
+### 最小语义影响面
+
+最小改动不是追求最少文件或最少行数，而是只引入实现已批准行为所必需的语义变化。需求责任确实跨越多个层次时可以跨文件实现；局部需求不能成为重写共享逻辑或扩大公共行为的理由。
+
+- 不为方便当前实现或测试而改变无关生产行为，也不把顺手重构、历史清理或技术偏好带入本次交付。
+- 公共或共享实现的扩展必须由当前 task、现有结构和真实调用链证明必要；存在安全的局部实现时，保持公共边界不变。
+- 完成标准包括整体差异可解释，并覆盖批准范围内的真实消费者。无法对应当前 task 或必要直接影响的变化不应保留，最小改动也不能以遗漏需求为代价。
+
 ### 保留得住的测试
 
 - 测试描述调用方得到的能力，不把内部实现过程当成验收。
@@ -47,5 +55,6 @@ metadata:
 ## Guardrails
 
 - 只改当前 task 授权范围内的实现和测试文件。
+- 不改变当前 task 未要求变化的共享语义；必要的公共改动必须有调用链证据，并验证直接受影响的既有行为。
 - 不修改计划材料、工作流记录、审查报告或验证材料。
 - 不代替后续审查或验证流程作结论。