@peterxiaoyang/superspec 0.1.48 → 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.d.ts

@@ -106,6 +106,8 @@ export interface ApplyPendingTaskStatus {
 export declare function executionPolicyForRisk(risk: ReviewRisk): ExecutionPolicy;
 export declare function executionPolicyForCurrentRound(events: Event[]): ExecutionPolicy;
 export declare function proposalDocsBaseline(changeRoot: string): Record<string, string>;
+export declare function applyPlanningBaseline(changeRoot: string): Record<string, string>;
+export declare function applyPlanningDocsChangedSinceBaseline(changeRoot: string, baseline: Record<string, string>): boolean;
 export declare function discoveryDocsBaseline(changeRoot: string): Record<string, string>;
 /** 新 Explore 轮次冻结已有已确认事项，避免把历史答复当作本轮遗漏。 */
 export declare function exploreAnswerRegistrationPayloadForChange(changeRoot: string): ReturnType<typeof exploreAnswerRegistrationPayload>;

package/dist/phase_plan.js

@@ -25,14 +25,14 @@ function freeTextDecisionAsk(change, question, scope) {
         required_fields: ["answer"],
     };
 }
-function requiredArtifact(projectRoot, change, changeRoot, state, kind, fileName, risk) {
-    const artifactPath = relative(projectRoot, join(changeRoot, ".superspec", "artifacts", fileName)).replaceAll("\\", "/");
+function requiredArtifact(projectRoot, change, changeRoot, state, kind, canonicalPath, risk) {
+    const artifactPath = relative(projectRoot, join(changeRoot, canonicalPath)).replaceAll("\\", "/");
     return {
         kind: "artifact_required",
         state,
         artifact: { kind, path: artifactPath, operation: "create_or_update" },
         resume: { argv: nextArgv(change, risk) },
-        reason: `${fileName} 不存在`,
+        reason: `${canonicalPath.split("/").at(-1)} 不存在`,
     };
 }
 function phaseConfirmationStep(context, boundary, reason) {
@@ -244,6 +244,15 @@ export function proposalDocsBaseline(changeRoot) {
     }
     return baseline;
 }
+export function applyPlanningBaseline(changeRoot) {
+    const baseline = proposalDocsBaseline(changeRoot);
+    delete baseline["tasks.md"];
+    return baseline;
+}
+export function applyPlanningDocsChangedSinceBaseline(changeRoot, baseline) {
+    const current = applyPlanningBaseline(changeRoot);
+    return Object.entries(baseline).some(([path, digest]) => current[path] !== digest);
+}
 export function discoveryDocsBaseline(changeRoot) {
     // 与 Explore gate 使用同一组审查目标。回退到 explore 后，至少要更新一项
     // discovery 材料，才允许重新进入 propose，避免把一次纯状态回退误当作新探索轮次。
@@ -476,6 +485,20 @@ export function pendingTaskStatusForApply(changeRoot, events) {
         completedByEvent,
     };
 }
+function isPostApplyPlanOnlyRepair(changeRoot, events) {
+    // Propose 返工发生在新 Apply round 之前，旧 round 的 task_completed 不能覆盖
+    // 当前计划明确重新打开的 checkbox；这里以当前 tasks.md 为准。
+    if (pendingTaskIds(changeRoot).length > 0)
+        return false;
+    const roundId = currentProposeRoundId(events);
+    const roundEvent = events.find(event => event.event_id === roundId);
+    if (roundEvent?.event_type !== "transition_commit")
+        return false;
+    const payload = roundEvent.payload;
+    return payload.transition === "reopen"
+        && payload.reopen_target === "propose"
+        && ["apply", "apply_done", "review", "accepted"].includes(String(payload.reopen_source));
+}
 export function formatPendingTaskMessage(ids, action) {
     return `尚有未完成任务：${ids.join(", ")}；${action}`;
 }
@@ -532,7 +555,7 @@ export function planNextStep(context) {
             }
             const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
             if (!existsSync(discoveryPath)) {
-                return requiredArtifact(projectRoot, change, changeRoot, "explore", "discovery", "discovery.md", mode.risk);
+                return requiredArtifact(projectRoot, change, changeRoot, "explore", "discovery", ".superspec/artifacts/discovery.md", mode.risk);
             }
             const discoveryCheck = validateDiscovery(changeRoot);
             if (!discoveryCheck.ok) {
@@ -616,7 +639,10 @@ export function planNextStep(context) {
             }
             const testContractPath = join(changeRoot, ".superspec", "artifacts", "test-contract.md");
             if (!existsSync(testContractPath)) {
-                return requiredArtifact(projectRoot, change, changeRoot, "propose", "test_contract", "test-contract.md", mode.risk);
+                return requiredArtifact(projectRoot, change, changeRoot, "propose", "test_contract", ".superspec/artifacts/test-contract.md", mode.risk);
+            }
+            if (!existsSync(join(changeRoot, "tasks.md"))) {
+                return requiredArtifact(projectRoot, change, changeRoot, "propose", "tasks", "tasks.md", mode.risk);
             }
             const planningProfile = planningValidationProfileForPendingProposeRound(events);
             const preflight = validatePlanningPreflight(projectRoot, change, changeRoot, mode.risk, executionPolicyForRisk(mode.risk), planningProfile);
@@ -646,7 +672,8 @@ export function planNextStep(context) {
                 return requiredJobs("propose_ready", proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
             }
             const startApplyPlan = planStartApplyTransition(context, false);
-            if (startApplyPlan.kind === "advance") {
+            const planOnlyRepair = isPostApplyPlanOnlyRepair(changeRoot, events);
+            if (startApplyPlan.kind === "advance" && !planOnlyRepair) {
                 const confirmation = phaseConfirmationStep(context, "propose_to_apply", "计划阶段完成，等待用户确认开始实现");
                 if (confirmation)
                     return confirmation;
@@ -661,7 +688,12 @@ export function planNextStep(context) {
                 };
                 return { kind: "ask_user", state: "propose_ready", ask, reason: startApplyPlan.message };
             }
-            return { kind: "run_transition", state: "propose_ready", transition: "start-apply", reason: "计划就绪，开始执行" };
+            return {
+                kind: "run_transition",
+                state: "propose_ready",
+                transition: "start-apply",
+                reason: planOnlyRepair ? "计划材料已修正且没有待实施任务，跳过重复的 Apply 确认" : "计划就绪，开始执行",
+            };
         }
         case "apply":
             return planApplyNext(context);
@@ -746,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));
 }
@@ -770,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",
@@ -871,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 与代码审查完成，等待用户确认进入最终审查");
@@ -1061,10 +1093,12 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
             reason: `进入执行阶段前需要重新完成计划文档审查：${gatePlan.reason}`,
         };
     }
+    const planOnlyRepair = isPostApplyPlanOnlyRepair(changeRoot, events);
     const acceptedConfirmation = enforceConfirmation
+        && !planOnlyRepair
         ? acceptedProposeToApplyConfirmation(context, risk)
         : null;
-    if (enforceConfirmation && !acceptedConfirmation) {
+    if (enforceConfirmation && !acceptedConfirmation && !planOnlyRepair) {
         const confirmation = phaseConfirmationForBoundary(projectRoot, events, snapshot, "propose_to_apply", risk);
         return {
             kind: "skip",
@@ -1076,7 +1110,7 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
         kind: "advance",
         fromState: "propose_ready",
         toState: "apply",
-        reason: "进入执行阶段",
+        reason: planOnlyRepair ? "计划材料修正完成且没有待实施任务" : "进入执行阶段",
         payload: {
             apply_start_head: gitHead.head,
             apply_start_head_reason: gitHead.reason,
@@ -1088,6 +1122,7 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
                 review_risk: risk,
                 requires_verifier: risk !== "minimal",
             },
+            apply_planning_baseline: applyPlanningBaseline(changeRoot),
             ...(acceptedConfirmation ? phaseConfirmationCommitPayload(acceptedConfirmation.confirmation, acceptedConfirmation.decision) : {}),
         },
     };

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

@@ -9,7 +9,7 @@ import { REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE, REVIEW_FINAL_VE
 import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketContext, codeReviewPacketDigest, collectCodeReviewGateFacts, computeCodeStateCheck, currentCodeReviewWorkingPaths, dismissedCodeReviewSummary, effectiveCoverageExemptionRefsFromEvents, latestCodeReviewGateEvidence, latestCodeReviewDecision, latestCodeReviewFailedStatus, missingCoverageExemptionTestIds, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, taskExecutionIndexForReview, } from "./code_review.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 import { adoptedContractForTask, findTaskInLines, isFixTaskId, parseTasksMd, parseTestContractEntries, } from "./format.js";
-import { applyRequirementModeForCurrentRound, executionRequirementVersionForCurrentRound, blockingJobsForApplyDone, executionPolicyForCurrentRound, formatPendingTaskMessage, latestAcceptedProposalBaseline, pendingTaskStatusForApply, planningValidationProfileForNewRound, planTransition, discoveryDocsBaseline, exploreAnswerRegistrationPayloadForChange, proposeAnswerRegistrationPayloadForChange, proposalDocsBaseline, } from "./phase_plan.js";
+import { applyRequirementModeForCurrentRound, applyPlanningDocsChangedSinceBaseline, executionRequirementVersionForCurrentRound, blockingJobsForApplyDone, executionPolicyForCurrentRound, formatPendingTaskMessage, latestAcceptedProposalBaseline, pendingTaskStatusForApply, planningValidationProfileForNewRound, planTransition, discoveryDocsBaseline, exploreAnswerRegistrationPayloadForChange, proposeAnswerRegistrationPayloadForChange, proposalDocsBaseline, } from "./phase_plan.js";
 import { latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { currentGitHead, dirtyCodeFiles, stageProductionJavaFilesSince } from "./git_state.js";
 import { workflowRiskForProject } from "./workflow_config.js";
@@ -209,8 +209,8 @@ function compileRequiredEvidence(executionPolicy, testIds, requiresVerificationW
         accepted_green_statuses: ["expected_success"],
     };
 }
-function evidenceActionsForAttempt(change, attemptId, required) {
-    const testIds = required.test_ids.length > 0 ? required.test_ids : [undefined];
+function evidenceActionsForAttempt(change, attemptId, fallbackTestId, required) {
+    const testIds = required.test_ids.length > 0 ? required.test_ids : [fallbackTestId];
     const statuses = [];
     if (required.red_required)
         statuses.push("expected_failure");
@@ -218,10 +218,10 @@ function evidenceActionsForAttempt(change, attemptId, required) {
         statuses.push(required.accepted_green_statuses[0] ?? "expected_success");
     return testIds.flatMap(testId => statuses.map(semanticStatus => ({
         kind: "test_run",
-        ...(testId ? { test_id: testId } : {}),
+        test_id: testId,
         record_argv: ["superspec", "record", "test-run", "--change", change, "--input", "-"],
         record_input: {
-            ...(testId ? { test_id: testId } : {}),
+            test_id: testId,
             attempt_id: attemptId,
             command: null,
             cwd: null,
@@ -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 {
@@ -820,6 +820,9 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
             if (snapshot.state !== "apply")
                 return { skip: true, message: `当前状态 ${snapshot.state}，需要 apply` };
             const events = readEvents(projectRoot, change);
+            if (applyPlanningMaterialsChanged(changeRoot, events)) {
+                return { skip: true, message: "Apply 期间计划材料已变化；请回到 Propose 核对并重新批准计划后再继续任务" };
+            }
             const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
             const lines = tasksContent.split("\n");
             const taskLineIdx = findTaskLine(lines, taskId);
@@ -890,7 +893,7 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
                 ...boundarySnapshotPayload(projectRoot),
             };
             const evidenceActions = requiredEvidence
-                ? evidenceActionsForAttempt(change, attempt.attempt_id, requiredEvidence)
+                ? evidenceActionsForAttempt(change, attempt.attempt_id, taskId, requiredEvidence)
                 : null;
             return {
                 fromState: "apply", toState: "apply", outcome: "advanced",
@@ -934,6 +937,36 @@ function invalidateOpenJobs(snapshot, to, reason) {
         },
     }));
 }
+function latestApplyPlanningBaseline(events) {
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        if (payload.transition !== "start-apply")
+            continue;
+        const baseline = payload.apply_planning_baseline;
+        if (!baseline || typeof baseline !== "object" || Array.isArray(baseline))
+            return null;
+        const entries = Object.entries(baseline);
+        return entries.every(([, digest]) => typeof digest === "string")
+            ? Object.fromEntries(entries)
+            : null;
+    }
+    return null;
+}
+function applyPlanningMaterialsChanged(changeRoot, events) {
+    const baseline = latestApplyPlanningBaseline(events);
+    return baseline != null && applyPlanningDocsChangedSinceBaseline(changeRoot, baseline);
+}
+function proposalReopenBaseline(changeRoot, events, source) {
+    const applyBaseline = ["apply", "apply_done", "review"].includes(source)
+        ? latestApplyPlanningBaseline(events)
+        : null;
+    return applyBaseline
+        ? { baseline: { ...proposalDocsBaseline(changeRoot), ...applyBaseline }, source: "apply" }
+        : { baseline: proposalDocsBaseline(changeRoot), source: "reopen_fallback" };
+}
 function planningReopenExtraEvents(snapshot, to, reason) {
     return [
         ...invalidateOpenJobs(snapshot, to, reason),
@@ -1004,6 +1037,9 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                     return { skip: true, message: "--review-fix 只能用于回到实现阶段（reopen --to apply）" };
                 if (snapshot.state !== "apply_done")
                     return { skip: true, message: `当前状态 ${snapshot.state}，不能通过代码审查修复回到实现阶段` };
+                if (applyPlanningMaterialsChanged(changeRoot, events)) {
+                    return { skip: true, message: "计划材料已变化，不能作为纯实现问题回到 Apply；请 reopen --to propose" };
+                }
                 const ref = parseCodeReviewFindingRef(opts.reviewFix);
                 if (!ref)
                     return { skip: true, message: "--review-fix 必须是 <job_id>#<finding_id>" };
@@ -1045,6 +1081,9 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                     return { skip: true, message: `当前状态 ${snapshot.state}，不能通过自测问题回到实现阶段` };
                 }
                 const parentTaskId = opts.selfTestFix.trim();
+                if (applyPlanningMaterialsChanged(changeRoot, events)) {
+                    return { skip: true, message: "计划材料已变化，不能作为纯实现问题创建 self-test 修复；请 reopen --to propose" };
+                }
                 const parentTask = parseTasksMd(readFileSync(join(changeRoot, "tasks.md"), "utf8"))
                     .find(task => task.taskId === parentTaskId);
                 if (!parentTask)
@@ -1118,12 +1157,13 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                 // 的摘要，并用 reopen 当刻的摘要补齐缺项，确保本轮之后对任一审查目标的修改都能被检测。
                 const baselineNeedsBackfill = acceptedBaseline !== null && Object.keys(currentBaseline)
                     .some(path => !Object.prototype.hasOwnProperty.call(acceptedBaseline, path));
+                const applyReopenBaseline = acceptedBaseline ? null : proposalReopenBaseline(changeRoot, events, snapshot.state);
                 const baselineDocs = acceptedBaseline
                     ? Object.fromEntries(Object.entries(currentBaseline).map(([path, digest]) => [
                         path,
                         Object.prototype.hasOwnProperty.call(acceptedBaseline, path) ? acceptedBaseline[path] : digest,
                     ]))
-                    : currentBaseline;
+                    : applyReopenBaseline.baseline;
                 return {
                     fromState: snapshot.state,
                     toState: "propose",
@@ -1132,7 +1172,9 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                     commitPayload: {
                         reopen_target: "propose",
                         reopen_source: snapshot.state,
-                        baseline_source: acceptedBaseline ? (baselineNeedsBackfill ? "accepted_backfill" : "accepted") : "reopen_fallback",
+                        baseline_source: acceptedBaseline
+                            ? (baselineNeedsBackfill ? "accepted_backfill" : "accepted")
+                            : applyReopenBaseline.source,
                         baseline_docs: baselineDocs,
                         planning_validation_version: 2,
                         planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
@@ -1145,6 +1187,9 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
             if (snapshot.state !== "apply_done" && snapshot.state !== "review") {
                 return { skip: true, message: `当前状态 ${snapshot.state}，不能 reopen 到 apply` };
             }
+            if (applyPlanningMaterialsChanged(changeRoot, events)) {
+                return { skip: true, message: "计划材料已变化，不能直接回到 Apply；请 reopen --to propose" };
+            }
             const pending = pendingTaskStatusForApply(changeRoot, events).pending;
             if (pending.length === 0)
                 return { skip: true, message: "没有未完成任务，不能 reopen 到 apply" };
@@ -1167,6 +1212,9 @@ export function reviewReady(projectRoot, change, changeRoot, risk = workflowRisk
             const policy = storedPolicy ?? reviewPolicyForRisk(risk);
             const policyPayload = storedPolicy ? {} : { review_policy: policy };
             const currentEvidenceDigest = reviewEvidenceDigest(events);
+            if (snapshot.state === "apply" && applyPlanningMaterialsChanged(changeRoot, events)) {
+                return { skip: true, message: "Apply 期间计划材料已变化，不能进入 Review；请回到 Propose 核对并重新批准计划" };
+            }
             // 检查是否所有任务已完成
             const pending = pendingTaskStatusForApply(changeRoot, events).pending;
             if (pending.length > 0)
@@ -1267,10 +1315,14 @@ export function taskComplete(projectRoot, change, changeRoot, taskId, inputConte
             const attempt = snapshot.active_task_attempts?.find(a => a.task_id === taskId && a.state === "active");
             if (!attempt)
                 return { skip: true, message: `任务 ${taskId} 无活跃执行尝试` };
+            const events = readEvents(projectRoot, change);
+            if (applyPlanningMaterialsChanged(changeRoot, events)) {
+                return { skip: true, message: "Apply 期间计划材料已变化，不能完成当前任务；请回到 Propose 核对并重新批准计划" };
+            }
             const readiness = taskEvidenceReadiness(projectRoot, change, changeRoot, attempt);
             if (!readiness.ready)
                 return { skip: true, message: `任务 ${taskId} 无法完成：${readiness.reason}` };
-            const taskStartBoundary = boundarySnapshotForTaskAttempt(readEvents(projectRoot, change), attempt.attempt_id);
+            const taskStartBoundary = boundarySnapshotForTaskAttempt(events, attempt.attempt_id);
             const completedPayload = {
                 task_id: taskId,
                 attempt_id: attempt.attempt_id,

package/dist/types.d.ts

@@ -226,6 +226,8 @@ export interface TransitionCommitPayload {
         review_risk?: "minimal" | "normal" | "strict";
     };
     accepted_baseline_docs?: Record<string, string>;
+    /** Apply 开始时冻结的计划材料摘要；tasks.md 由状态机维护，不参与冻结。 */
+    apply_planning_baseline?: Record<string, string>;
     /** Propose-ready / start-apply 写入的本轮 workflow mode，后续阶段只读该快照。 */
     workflow_mode?: "minimal" | "normal" | "strict";
     /** v2 起所有普通任务必须有五字段执行依据；缺失表示旧 change，沿用旧规则回放。 */
@@ -342,7 +344,7 @@ export interface AcceptedMaterialFollowupContinuation {
     };
     plan_docs_changed_since_accept: boolean | null;
 }
-export type WorkflowArtifactKind = "discovery" | "test_contract";
+export type WorkflowArtifactKind = "discovery" | "test_contract" | "tasks";
 export interface RequiredWorkflowArtifact {
     kind: WorkflowArtifactKind;
     /** Repository-relative canonical path owned by the workflow engine. */
@@ -357,10 +359,10 @@ export interface MaterialUpdateRequiredResume {
 }
 export interface TestEvidenceAction {
     kind: "test_run";
-    test_id?: string;
+    test_id: string;
     record_argv: string[];
     record_input: {
-        test_id?: string;
+        test_id: string;
         attempt_id: string;
         command: null;
         cwd: null;

package/package.json

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

package/templates/workflow/AGENTS.md

@@ -1,6 +1,8 @@
 <!-- SUPERSPEC:AGENTS:START -->
 只有当用户显式调用 `superspec-*`，或明确要求继续处理某个已有 SuperSpec change 时，才进入或续转 SuperSpec 工作流。普通开发、修复、排查、测试或审查请求，即使项目已安装 SuperSpec，也不得自行启动工作流、创建 change、执行 `transition next`，或切换到某个 `superspec-*` 阶段。
 
+以下规则仅适用于已经显式启动或明确指定的 SuperSpec change。没有活跃 SuperSpec change 时，本区块除上述工作流激活边界外均不适用，按项目常规开发指令执行。
+
 一旦用户已显式启动工作流或明确指定 change，使用 `superspec-*` 工作流时一律以 `superspec transition next --change "<change>"` 返回的下一步推进；主流程执行内部命令，不要求用户手动运行工作流命令。流程完成前不得跳阶段、不得自称完成。
 
 每完成 `next` 返回的当前事项（材料更新、用户答复回写、实现、验证、审查或修复时），立即再次运行 `superspec transition next --change "<change>"` 并继续处理。完成单个事项不等于完成整个 change；只有工作流明确需要用户决定、当前独立工作项尚未返回结果、遇到真实阻塞或整个 change 已完成时才暂停。
@@ -13,6 +15,10 @@ Explore 中需要用户决定业务、验收、范围或关键取舍时，先简
 
 当前 change 的自测、联调或用户指出的问题若仍能由既有 task 的批准行为、边界和验收解释，就在同一 change 内处理：
 
+计划材料没有枚举某个类、继承关系、方法或局部实现细节，不等于计划遗漏。只要正确修法能够由既有 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 未要求变化的共享语义；必要的公共改动必须有调用链证据，并验证直接受影响的既有行为。
 - 不修改计划材料、工作流记录、审查报告或验证材料。
 - 不代替后续审查或验证流程作结论。

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

@@ -186,6 +186,8 @@ metadata:
 
 Propose 以已确认的 Discovery 为需求边界。范围、业务行为、验收、数据语义或安全仍不明确时，回同一 change 的 Explore 澄清，不静默采用默认业务语义。
 
+用户补充与已经核实的代码、运行行为、接口契约或外部系统事实冲突时，不通过改写事实材料来消除冲突。若用户明确要求改变真实行为，将相应实现、迁移和验证影响纳入计划；若是否改变真实行为仍不明确，保留冲突并交给用户确认。
+
 当需求结果已经明确，但多个可行技术路线会让使用者承担不同的迁移、兼容、数据归属、发布、成本或长期维护边界时，不替使用者静默选择。在 `design.md` 的 `## 待用户确认` 中保留当前高影响设计决定，说明已知事实、候选结果、推荐及依据和会受影响的交付；内部命名、文件组织、局部实现和不改变这些结果的技术选择由模型自主决定。没有这类取舍时不制造问答。
 
 每项使用 `DEC-xxx` 标识并只表达一个决定。工作流一次返回当前一项；用户答复后按工作流反馈处理，勾选时保留决定项原文，将最终选择与影响写入相邻正文及相关 design、specs、tasks 和测试契约，并按新方案重新判断后续事项。审查角色只能依据本次目标和直接证据指出缺失的决定，不能把个人偏好或更理想的架构升级为用户义务。