@peterxiaoyang/superspec 0.1.55 → 0.1.56

package/dist/approved_ref.d.ts

@@ -0,0 +1,26 @@
+import type { CodeReviewClaimKind } from "./types.ts";
+export declare const CODE_REVIEW_CLAIM_KINDS: readonly ["missing_approved", "breaks_existing", "unjustified_addition"];
+export type ApprovedRefKind = "test" | "requirement" | "task" | "design" | "proposal";
+export interface ResolvedApprovedRef {
+    raw: string;
+    kind: ApprovedRefKind;
+    short: string;
+}
+export declare function isCodeReviewClaimKind(value: unknown): value is CodeReviewClaimKind;
+export declare function shortApprovedRef(raw: string): string;
+export declare function resolveApprovedRef(changeRoot: string, raw: unknown): {
+    ok: true;
+    value: ResolvedApprovedRef;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveApprovedRefs(changeRoot: string, refs: unknown): {
+    ok: true;
+    values: ResolvedApprovedRef[];
+} | {
+    ok: false;
+    reasons: string[];
+};
+export declare function hasBehaviorAnchor(values: readonly ResolvedApprovedRef[]): boolean;
+export declare function reviewFixReason(claimKind: CodeReviewClaimKind, refs: readonly string[]): string;

package/dist/approved_ref.js

@@ -0,0 +1,158 @@
+// SuperSpec 代码审查 approved_refs：只做存在性解析，不做语义匹配。
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { parseTasksMd, parseTestContractEntries } from "./format.js";
+export const CODE_REVIEW_CLAIM_KINDS = [
+    "missing_approved",
+    "breaks_existing",
+    "unjustified_addition",
+];
+const TEST_ID_RE = /^TEST-[A-Za-z0-9_-]+$/;
+const TEST_CONTRACT_REL = join(".superspec", "artifacts", "test-contract.md");
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isPathInside(root, target) {
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function headingExists(content, title) {
+    const heading = new RegExp(`^#{1,6}[\\t ]+${escapeRegex(title)}(?:[\\t ]+#+)?[\\t ]*$`, "m");
+    return heading.test(content);
+}
+function shortTestId(raw) {
+    const trimmed = raw.trim();
+    if (TEST_ID_RE.test(trimmed))
+        return trimmed;
+    const hash = trimmed.lastIndexOf("#");
+    if (hash >= 0) {
+        const id = trimmed.slice(hash + 1).trim();
+        if (TEST_ID_RE.test(id))
+            return id;
+    }
+    return null;
+}
+function readChangeFile(changeRoot, relPath) {
+    const target = resolve(changeRoot, relPath);
+    if (!isPathInside(resolve(changeRoot), target) && resolve(changeRoot) !== target)
+        return null;
+    try {
+        if (!statSync(target).isFile())
+            return null;
+        return readFileSync(target, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function isCodeReviewClaimKind(value) {
+    return typeof value === "string" && CODE_REVIEW_CLAIM_KINDS.includes(value);
+}
+export function shortApprovedRef(raw) {
+    const testId = shortTestId(raw);
+    if (testId)
+        return testId;
+    const req = /#Requirement:\s*(.+)$/.exec(raw.trim());
+    if (req)
+        return `Requirement: ${req[1].trim()}`;
+    const hash = raw.lastIndexOf("#");
+    if (hash >= 0 && hash < raw.length - 1)
+        return raw.slice(hash + 1).trim();
+    return raw.trim();
+}
+export function resolveApprovedRef(changeRoot, raw) {
+    if (typeof raw !== "string" || raw.trim() === "") {
+        return { ok: false, reason: "approved_refs 条目必须是非空字符串" };
+    }
+    const ref = raw.trim();
+    if (/[\u0000-\u001f\u007f]/.test(ref)) {
+        return { ok: false, reason: `approved_refs 条目不能包含换行等控制字符：${JSON.stringify(ref)}` };
+    }
+    const testId = shortTestId(ref);
+    if (testId) {
+        if (ref.includes("#") && !ref.endsWith(`#${testId}`)) {
+            return { ok: false, reason: `TEST 引用只能是裸 TEST-ID 或以 #TEST-ID 结尾指向 test-contract.md：${ref}` };
+        }
+        if (ref.includes("#")) {
+            const path = ref.slice(0, ref.lastIndexOf("#")).replace(/\\/g, "/");
+            const allowed = path === TEST_CONTRACT_REL.replace(/\\/g, "/")
+                || path === "test-contract.md"
+                || path.endsWith("/test-contract.md");
+            if (!allowed)
+                return { ok: false, reason: `TEST 引用只能指向 test-contract.md：${ref}` };
+        }
+        const content = readChangeFile(changeRoot, TEST_CONTRACT_REL);
+        if (content == null)
+            return { ok: false, reason: `无法读取 ${TEST_CONTRACT_REL.replace(/\\/g, "/")}，无法校验 TEST 引用：${ref}` };
+        const parsed = parseTestContractEntries(content);
+        if (!parsed.ok || !parsed.entries.some(entry => entry.test_id === testId)) {
+            return { ok: false, reason: `${TEST_CONTRACT_REL.replace(/\\/g, "/")} 中不存在 ${testId}` };
+        }
+        return { ok: true, value: { raw: ref, kind: "test", short: testId } };
+    }
+    const separator = ref.indexOf("#");
+    if (separator <= 0 || separator === ref.length - 1) {
+        return { ok: false, reason: `锚点格式无法解析，应为 文件#标题 或 TEST-ID：${ref}` };
+    }
+    const path = ref.slice(0, separator).replace(/\\/g, "/");
+    const anchor = ref.slice(separator + 1).trim();
+    const content = readChangeFile(changeRoot, path);
+    if (content == null)
+        return { ok: false, reason: `${path} 在当前 change 中不存在` };
+    if (path === "tasks.md") {
+        const tasks = parseTasksMd(content);
+        if (!tasks.some(task => task.taskId === anchor))
+            return { ok: false, reason: `tasks.md 中不存在任务 ${anchor}` };
+        return { ok: true, value: { raw: ref, kind: "task", short: anchor } };
+    }
+    if (path === "design.md") {
+        if (!headingExists(content, anchor))
+            return { ok: false, reason: `design.md 中不存在标题「${anchor}」` };
+        return { ok: true, value: { raw: ref, kind: "design", short: anchor } };
+    }
+    if (path === "proposal.md") {
+        if (!headingExists(content, anchor))
+            return { ok: false, reason: `proposal.md 中不存在标题「${anchor}」` };
+        return { ok: true, value: { raw: ref, kind: "proposal", short: anchor } };
+    }
+    if (/^specs\/[^/]+\/spec\.md$/.test(path)) {
+        const requirementTitle = anchor.startsWith("Requirement:")
+            ? anchor.slice("Requirement:".length).trim()
+            : "";
+        if (!requirementTitle)
+            return { ok: false, reason: `spec 锚点必须以 Requirement: 开头：${ref}` };
+        if (!headingExists(content, `Requirement: ${requirementTitle}`)) {
+            return { ok: false, reason: `${path} 中不存在 Requirement「${requirementTitle}」` };
+        }
+        return {
+            ok: true,
+            value: { raw: ref, kind: "requirement", short: `Requirement: ${requirementTitle}` },
+        };
+    }
+    return { ok: false, reason: `只支持 tasks.md、design.md、proposal.md、specs/*/spec.md 与 test-contract.md 的锚点：${ref}` };
+}
+export function resolveApprovedRefs(changeRoot, refs) {
+    if (!Array.isArray(refs) || refs.length === 0) {
+        return { ok: false, reasons: ["approved_refs 必须是非空字符串数组"] };
+    }
+    const values = [];
+    const reasons = [];
+    for (const raw of refs) {
+        const resolved = resolveApprovedRef(changeRoot, raw);
+        if (!resolved.ok)
+            reasons.push(resolved.reason);
+        else
+            values.push(resolved.value);
+    }
+    if (reasons.length > 0)
+        return { ok: false, reasons };
+    return { ok: true, values };
+}
+export function hasBehaviorAnchor(values) {
+    return values.some(value => value.kind === "test" || value.kind === "requirement");
+}
+export function reviewFixReason(claimKind, refs) {
+    const shorts = refs.map(shortApprovedRef).filter(Boolean);
+    const target = shorts.length > 0 ? shorts.join("、") : "已批准行为";
+    return `兑现 ${target}（${claimKind}）`;
+}

package/dist/code_review.d.ts

@@ -69,6 +69,7 @@ export declare function codeReviewPacketDigest(input: {
     packet_context?: JobPacketContext;
     previous_rejection?: ReviewPreviousRejection;
 }): string;
+export declare function addedCodePathsForScope(projectRoot: string, scope: CodeReviewScope): string[];
 export declare function codeReviewPacketContext(changeRoot: string, projectRoot: string, scope: CodeReviewScope, events: Event[]): JobPacketContext;
 export declare function effectiveCoverageExemptionRefsFromEvents(events: Event[]): CoverageExemptionRef[];
 export declare function missingCoverageExemptionTestIds(changeRoot: string, events: Event[]): string[];

package/dist/code_review.js

@@ -360,6 +360,41 @@ export function codeReviewJobStaleReason(projectRoot, job, currentPaths, events,
 export function codeReviewPacketDigest(input) {
     return sha256Text(JSON.stringify(input));
 }
+export function addedCodePathsForScope(projectRoot, scope) {
+    if (!scope.scope_reliable)
+        return [];
+    const added = new Set();
+    let baseHead = scope.base_head;
+    if (!baseHead && scope.current_head) {
+        // 首轮 start-apply 前仓库还没有提交：以空树为基点，让 Apply 期间产生的首个提交也进入新增清单。
+        const emptyTree = gitLines(projectRoot, ["hash-object", "-t", "tree", "/dev/null"]);
+        if (emptyTree.ok)
+            baseHead = emptyTree.lines[0] ?? null;
+    }
+    if (baseHead && scope.current_head) {
+        const committed = gitLines(projectRoot, [
+            "diff", "--no-renames", "--diff-filter=A", "--name-only", `${baseHead}..${scope.current_head}`,
+        ]);
+        if (committed.ok) {
+            for (const path of committed.lines) {
+                if (isCodeLikePath(path))
+                    added.add(path);
+            }
+        }
+    }
+    const dirty = dirtyCodeFiles(projectRoot);
+    if (dirty.ok) {
+        for (const file of dirty.files) {
+            if (file.status === "added" && isCodeLikePath(file.path))
+                added.add(file.path);
+        }
+    }
+    for (const path of scope.untracked_paths) {
+        if (isCodeLikePath(path))
+            added.add(path);
+    }
+    return [...added].sort();
+}
 export function codeReviewPacketContext(changeRoot, projectRoot, scope, events) {
     const taskExecutionIndex = taskExecutionIndexFromEvents(projectRoot, events);
     // changed_paths 未知（快照缺失）或不完整（committed 段 diff 失败）的 task
@@ -379,6 +414,7 @@ export function codeReviewPacketContext(changeRoot, projectRoot, scope, events)
         task_execution_index: taskExecutionIndex,
         unattributed_paths: scope.review_paths.filter(path => !attributedPaths.has(path)).sort(),
         unknown_attribution_tasks: unknownAttributionTasks,
+        added_code_paths: addedCodePathsForScope(projectRoot, scope),
     };
 }
 export function effectiveCoverageExemptionRefsFromEvents(events) {

package/dist/next.js

@@ -115,14 +115,17 @@ function toNextOutput(change, plan) {
                 resume: { argv: ["superspec", "transition", "next", "--change", change] },
                 reason: plan.reason,
             };
-        case "run_transition":
+        case "run_transition": {
+            const findingContext = plan.reopen?.reason === "review_fix" ? plan.reopen.findingContext : undefined;
             return {
                 state: plan.state,
                 path: "next_command",
                 next_command: transitionCommand(change, plan.transition, formatTransitionArgs(plan)),
                 reason: plan.reason,
                 missing_inputs: [],
+                ...(findingContext ? { finding_context: findingContext } : {}),
             };
+        }
         case "done":
             return {
                 state: plan.state,

package/dist/phase_plan.d.ts

@@ -1,7 +1,7 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
 import { exploreAnswerRegistrationPayload } from "./explore_round.ts";
 import { proposeAnswerRegistrationPayload } from "./propose_round.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, WorkflowArtifactKind, State } from "./types.ts";
+import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, ReviewFindingContext, WorkflowArtifactKind, State } from "./types.ts";
 import type { Snapshot } from "./types.ts";
 import type { ReviewRisk } from "./review.ts";
 export type TransitionName = "explore" | "propose-ready" | "start-apply" | "task-start" | "task-complete" | "review-ready" | "reopen" | "accept";
@@ -29,6 +29,7 @@ export type ReopenNextStep = {
     jobId: string;
     findingId: string;
     reopenReason: string;
+    findingContext?: ReviewFindingContext;
 } | {
     to: "propose";
     reason: "review_finding";

package/dist/phase_plan.js

@@ -12,6 +12,16 @@ import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, co
 import { isPhaseAdvanceAuthorized, latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 import { workflowRiskForProposeRound, workflowRiskForState } from "./workflow_config.js";
+/** 从失败 finding 提取定位上下文：只回传 evidence（位置事实），不回传 description——那是审查建议叙事，不进执行上下文。 */
+function reviewFindingContext(finding) {
+    const evidence = typeof finding?.evidence === "string" ? finding.evidence.trim() : "";
+    if (!evidence)
+        return undefined;
+    return {
+        evidence,
+        note: "非授权上下文：仅用于定位问题代码；实现范围仍以任务行锚定的已批准行为为准",
+    };
+}
 function requiredJobs(state, jobs, reason) {
     return { kind: "required_jobs", state, jobs, reason };
 }
@@ -837,6 +847,7 @@ function planApplyDoneNext(context) {
                     jobId: latest.job.job_id,
                     findingId,
                     reopenReason: `修复代码审查问题 ${findingId}`,
+                    findingContext: reviewFindingContext(pendingFinding?.finding),
                 },
                 reason: `代码审查发现纯代码实现问题 ${findingId}，回到实现阶段修复`,
             };
@@ -862,6 +873,7 @@ function planApplyDoneNext(context) {
                         jobId: latest.job.job_id,
                         findingId,
                         reopenReason: `根据代码审查问题 ${findingId} 回到实现阶段修复`,
+                        findingContext: reviewFindingContext(pendingFinding?.finding),
                     },
                     reason: `使用者已确认问题 ${findingId} 直接回到实现阶段修复`,
                 };

package/dist/record.js

@@ -8,6 +8,7 @@ import { isPhaseConfirmationScope, phaseActionForAnswer, phaseConfirmationForCur
 import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewJobStaleReason, codeReviewDecisionAnswerLabel, currentCodeReviewWorkingPaths, latestCodeReviewFailedStatus, normalizeCodeReviewDecisionAnswer, parseCodeReviewDecisionScope, } from "./code_review.js";
 import { invalidReasonForSubmittedReport } from "./job_validity.js";
 import { jobSubmitArgv } from "./job_action.js";
+import { hasBehaviorAnchor, isCodeReviewClaimKind, resolveApprovedRefs, } from "./approved_ref.js";
 import { REVIEW_DOC_PATHS, REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX, REVIEW_REJECTION_OVERRIDE_ANSWER, parseReviewRejectionOverrideScope, reviewGateRoleResolution, reviewRejectionOverrideScope, } from "./review.js";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
 import { RecordInputDecodingError, readRecordInputFile } from "./record_input.js";
@@ -56,7 +57,7 @@ function roleDescription(role) {
         case "verifier":
             return "验证 proposal、实现状态、任务完成、测试契约和 SuperSpec 证据是否足以支撑完成结论";
         case "code-reviewer":
-            return "审查 apply 后的代码实现质量、健壮性、性能、安全、兼容、边界条件、是否偏离 proposal/design/tasks/test-contract 以及关键测试缺口";
+            return "独立审查实现是否以最小语义影响兑现已批准计划，找出真实缺陷、边界条件、安全/性能/兼容问题与关键测试缺口，并区分漏做与计划或验收没有要求的改动";
         case "executor":
             return "执行受限实现工作项";
         case "test-run":
@@ -339,7 +340,7 @@ function validateReviewScope(obj, job, checks) {
         }
     }
 }
-function actionableCodeReviewFindings(findings) {
+function actionableCodeReviewFindings(findings, changeRoot) {
     if (!Array.isArray(findings))
         return { actionable: [], reasons: ["报告字段 findings 必须是数组"] };
     const actionable = [];
@@ -387,6 +388,18 @@ function actionableCodeReviewFindings(findings) {
         if (type === "implementation" && finding.suggested_action !== "apply") {
             findingReasons.push(`纯代码实现问题 ${id} 的 suggested_action 必须是 apply`);
         }
+        if (!isCodeReviewClaimKind(finding.claim_kind)) {
+            findingReasons.push(`阻塞问题 ${id} 的 claim_kind 必须是 missing_approved|breaks_existing|unjustified_addition`);
+        }
+        const resolved = resolveApprovedRefs(changeRoot, finding.approved_refs);
+        if (!resolved.ok) {
+            findingReasons.push(...resolved.reasons.map((reason) => `阻塞问题 ${id} ${reason}`));
+        }
+        else if (finding.claim_kind === "missing_approved"
+            && finding.suggested_action === "apply"
+            && !hasBehaviorAnchor(resolved.values)) {
+            findingReasons.push(`阻塞问题 ${id} 的 missing_approved 在 suggested_action=apply 时必须引用可解析的 TEST 或 spec Requirement；若缺口属于计划或验收本身的问题，改用 type=mixed 且 suggested_action=propose 交使用者裁决`);
+        }
         if (findingReasons.length > 0) {
             reasons.push(...findingReasons);
             continue;
@@ -614,7 +627,7 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         const blockingCount = Array.isArray(findings)
             ? findings.filter(item => asObject(item)?.blocking === true).length
             : 0;
-        const { actionable, reasons } = actionableCodeReviewFindings(findings);
+        const { actionable, reasons } = actionableCodeReviewFindings(findings, changeRoot);
         if (verdict === "pass") {
             if (blockingCount > 0) {
                 const reason = "报告结论为 pass 时不能包含 blocking:true 的阻塞问题";
@@ -1165,6 +1178,9 @@ function packetFieldDescriptions() {
         changed_paths: "与某个任务（task）或代码状态检查相关的改动文件。",
         changed_paths_partial_reason: "该任务（task）的提交段 diff 失败原因；存在时 changed_paths 只包含工作区对比结果，归属可能不完整。",
         unattributed_paths: "代码审查范围中暂时无法归属到某个任务（task）的文件。",
+        added_code_paths: "相对本次代码审查基点新建的代码文件，供判断是否服务已批准行为。",
+        claim_kind: "阻塞问题相对已批准计划的关系：漏做、破坏已有行为、或计划或验收没有要求的改动。",
+        approved_refs: "指向当前 change 已批准材料的引用；引擎只检查能否解析，apply 漏做还需要 TEST 或 spec Requirement。",
         unknown_attribution_tasks: "因为缺少边界快照或提交段 diff 失败而无法完整计算改动归属的任务（task）。",
         coverage_exemption_refs: "测试覆盖豁免引用：说明某个 TEST 为什么没有绑定到任务（task）。",
         code_review_gate: "最终验证读取的代码审查门禁事实：passed 指向已接受的代码审查工作项，skipped 表示本轮没有代码类改动。",
@@ -1210,6 +1226,7 @@ export function jobsPacket(projectRoot, change, jobId) {
             ...(packetContext?.task_execution_index ? { task_execution_index: packetContext.task_execution_index } : {}),
             ...(packetContext?.unattributed_paths ? { unattributed_paths: packetContext.unattributed_paths } : {}),
             ...(packetContext?.unknown_attribution_tasks ? { unknown_attribution_tasks: packetContext.unknown_attribution_tasks } : {}),
+            ...(packetContext?.added_code_paths ? { added_code_paths: packetContext.added_code_paths } : {}),
             ...(packetContext?.code_state_check ? { code_state_check: packetContext.code_state_check } : {}),
             packet_digest: job.packet_digest,
             required_output_kind: "job_report_json",
@@ -1235,9 +1252,9 @@ export function jobsPacket(projectRoot, change, jobId) {
                 `产出 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":[],"checked_docs":[],"unchecked":[]},"findings":[],"reviewer":{"kind":"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 表示需要使用者判断的混合问题。`
+                        + `报告结论为 fail 时，问题列表（findings）至少包含一个可处理、可追溯的阻塞问题，字段为 {"id":"<stable-id>","blocking":true,"type":"implementation|spec|mixed","claim_kind":"missing_approved|breaks_existing|unjustified_addition","approved_refs":["TEST-001"],"description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。问题类型（type）中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题；claim_kind 与 approved_refs 见字段说明。`
                         + (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 既可能解释必要的范围扩大，也可能说明代码审查修复为何保留原实现，均需结合 Diff、调用链和验证证据独立判断；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动逐个判断合理性；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。当前 packet 的 boundFiles 是本轮冻结的审查范围；若它来自前一轮审查后的增量，只复核本轮变化及其直接影响链路，不要求重复审查未变化文件，但仍要判断批准行为是否完整闭合。`
+                            ? `本工作项带任务执行索引（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 既可能解释必要的范围扩大，也可能说明代码审查修复为何保留原实现，均需结合 Diff、调用链和验证证据独立判断；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动和 added_code_paths 中的新建代码文件，均需判断是否服务已批准行为；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。当前 packet 的 boundFiles 是本轮冻结的审查范围；若它来自前一轮审查后的增量，只复核本轮变化及其直接影响链路，不要求重复审查未变化文件，但仍要判断批准行为是否完整闭合。`
                             : "")
                     : job.role === "verifier"
                         ? `最小格式：{"role":"verifier","verdict":"pass","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}。verdict 只能为 pass 或 fail；核对代码审查记录（code_review_gate）：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对修复闭环：task_execution_index.fix.source=code_review 时必须核对 review_finding 对应问题是否关闭；source=self_test 时必须核对 parent_task_id、记录的自测原因、本次 attempt 验证和最新代码审查是否共同闭环。方案/混合问题必须有用户决策或后续修复证据。按 task_execution_index 的 required_evidence 核对测试证据：red_required 时需要同一 TEST 的 RED（expected_failure）后 GREEN；green_required 时每个声明 TEST 都需要允许的 GREEN 语义状态；测试运行证据应包含测试 ID（test_id）、命令（command）、工作目录（cwd）、退出码（exit_code）、语义状态（semantic_status）。修复 task 的回归测试运行可用回归覆盖任务列表（covers_task_ids）说明覆盖了哪些已完成任务；缺少任务尝试 ID（attempt_id）的旧证据只能弱引用。` +

package/dist/transition.js

@@ -9,6 +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 { isCodeReviewClaimKind, reviewFixReason } from "./approved_ref.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";
@@ -359,15 +360,29 @@ function findReviewFailedFinding(events, ref) {
     return { event: status.terminal.event, finding };
 }
 function reviewFixDescriptor(ref, finding) {
-    const reason = typeof finding.description === "string" && finding.description.trim()
-        ? finding.description.trim().replace(/\s+/g, " ")
-        : `修复代码审查问题 ${ref.findingId}`;
+    const claimKind = isCodeReviewClaimKind(finding.claim_kind) ? finding.claim_kind : null;
+    const approvedRefs = Array.isArray(finding.approved_refs)
+        ? finding.approved_refs.filter((item) => typeof item === "string" && item.trim() !== "")
+        : [];
+    const reason = claimKind && approvedRefs.length > 0
+        ? reviewFixReason(claimKind, approvedRefs).replace(/\s+/g, " ")
+        : typeof finding.description === "string" && finding.description.trim()
+            ? finding.description.trim().replace(/\s+/g, " ")
+            : `修复代码审查问题 ${ref.findingId}`;
+    const reviewFinding = {
+        job_id: ref.jobId,
+        finding_id: ref.findingId,
+    };
+    if (approvedRefs.length > 0)
+        reviewFinding.approved_refs = approvedRefs;
+    if (claimKind)
+        reviewFinding.claim_kind = claimKind;
     return {
         fix_id: `REVIEW-FIX-${ref.jobId}#${ref.findingId}`,
         source: "code_review",
         parent_task_id: null,
         reason,
-        review_finding: { job_id: ref.jobId, finding_id: ref.findingId },
+        review_finding: reviewFinding,
     };
 }
 function selfTestFixBaseId(parentTaskId, reason) {

package/dist/types.d.ts

@@ -10,6 +10,7 @@ export type JobState = "requested" | "accepted" | "rejected";
 export type JobRole = "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "verifier" | "code-reviewer";
 export type ReviewJobGateId = "explore.discovery_review" | "propose.final_review" | "review.code_review" | "review.final_verifier";
 export type CodeReviewResultKind = "invalid_report" | "non_actionable_report" | "review_failed";
+export type CodeReviewClaimKind = "missing_approved" | "breaks_existing" | "unjustified_addition";
 export interface ReviewPreviousRejection {
     result_kind: CodeReviewResultKind;
     reason: string;
@@ -63,6 +64,8 @@ export interface FixDescriptor {
     review_finding?: {
         job_id: string;
         finding_id: string;
+        approved_refs?: string[];
+        claim_kind?: CodeReviewClaimKind;
     };
 }
 export interface DirtyFileFingerprint {
@@ -129,6 +132,7 @@ export interface JobPacketContext {
     task_execution_index?: TaskExecutionIndexEntry[];
     unattributed_paths?: string[];
     unknown_attribution_tasks?: string[];
+    added_code_paths?: string[];
     code_state_check?: CodeStateCheck;
 }
 export interface JobPacket {
@@ -148,6 +152,7 @@ export interface JobPacket {
     task_execution_index?: TaskExecutionIndexEntry[];
     unattributed_paths?: string[];
     unknown_attribution_tasks?: string[];
+    added_code_paths?: string[];
     code_state_check?: CodeStateCheck;
     packet_digest: string;
     required_output_kind: string;
@@ -371,6 +376,11 @@ export interface TestEvidenceAction {
     };
     required_fields: Array<"command" | "cwd" | "exit_code">;
 }
+/** review-fix 计划附带的原始审查问题上下文；仅供定位代码，不是实现授权。 */
+export interface ReviewFindingContext {
+    evidence: string;
+    note: string;
+}
 export type NextOutput = {
     state: State;
 } & ({
@@ -378,6 +388,7 @@ export type NextOutput = {
     next_command: string;
     reason: string;
     missing_inputs: MissingInput[];
+    finding_context?: ReviewFindingContext;
 } | {
     path: "required_job";
     required_jobs: RequiredJobAction[];

package/package.json

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

package/templates/workflow/AGENTS.md

@@ -23,6 +23,8 @@ Apply 的成功标准是完整兑现已批准行为，并在满足验收的实
 - 所有 task 已完成后，若问题仍能关联一个已完成 task、且不改变已批准行为和方案，主流程执行 `superspec transition reopen --change "<change>" --to apply --self-test-fix "<task>" --reason "<reason>"`，让工作流创建修复事项；随后继续 `next`，不得手改 tasks。
 - 无法关联既有 task，或需要改变行为、验收、接口、数据语义或实现路线时，才回 propose。
 
+用户明确否定某个不属于已批准行为的实现装置时，同样按上面三条规则恢复已批准行为，但顺序相反：先完成代码上的移除或修复（self-test-fix 的 reason 写恢复了哪条已批准行为，不写撤回或删除），确认能通过后再把这次否决写进 design 的非目标或相关 task 的边界——计划材料一旦先改，self-test-fix 会被计划冻结挡下，只能回 propose。不要为这次否决新增以删除或撤回为验收内容的 task。
+
 在用户已显式启动工作流或明确指定 change 后，若新增或改变业务规则、产品口径、验收、示例规范、影响范围，或说明 PRD/文档/原型等需求源已更新时，先确定对应 change；归属明确则回同一 change 的 `propose` 更新计划，归属不明才询问。不要把这类输入直接当作 apply 授权，也不要另建 repair change。
 
 SuperSpec 创建的独立审查/验证工作项，视为已授权启动对应 subagent；无需再次询问用户。主会话不得自批这些工作项。

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

@@ -4,7 +4,7 @@ description: Code-level review for spec fit, bugs, safety, and test gaps
 tools: read, grep, glob, bash
 ---
 
-Role: Code Reviewer. Check spec fit, correctness, security, test adequacy, code quality, performance, and maintainability without making the workflow heavy.
+Role: Code Reviewer. Check that approved behaviors landed with minimal extra semantics. Report missing approved results or unjustified additions; do not mint required work outside the approved plan.
 
 Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct.
 

package/templates/workflow/agents-md/critic.md

@@ -8,6 +8,6 @@ Role: Critic. Challenge demand clarification, plans, designs, implementations, a
 
 Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct.
 
-Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward.
+Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward. Undeclared theoretical risks are residual, not blockers.
 
 Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.

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

@@ -7,7 +7,7 @@ argument-hint: "本次代码审查说明"
 
 ## 角色
 
-你是 Code Reviewer。你独立、只读地审查本次实现是否以最小语义影响兑现已批准计划，找出真实 bug、范围遗漏、边界条件、安全/性能/兼容问题、关键测试缺口和无关改动。
+你是 Code Reviewer。你独立、只读地审查本次实现是否以最小语义影响兑现已批准计划，找出真实 bug、已批准行为遗漏、边界条件、安全/性能/兼容问题、关键测试缺口，以及计划或验收没有要求的改动。
 
 ## 工作边界
 
@@ -24,14 +24,13 @@ argument-hint: "本次代码审查说明"
 - 实现是否兑现当前任务的验收和边界，且与已批准的方案/规格一致。
 - 是否引入功能、数据、一致性、安全、权限、性能或兼容问题，以及直接的边界条件遗漏。
 - 从批准范围反查实现是否覆盖已确认的消费者、兼容路径和直接影响链路；任务勾选和测试通过不能替代完整性判断。
-- 对当前审查范围内的 Diff，分别判断“是否漏实现”和“是否超出必要范围”：直接消费者没有实现或没有现有实现已满足验收的证据，属于完整性问题；新增共享语义、公共契约或无关生产逻辑没有直接必要性证据，属于范围问题。两者都应锚定当前批准行为和实际 Diff，不把消费者类别或可能性清单当成覆盖义务。
-- 从实际 Diff 反查每项语义变化是否为当前验收所需。文件数量、新增方法或重载本身不是问题；若公共契约、共享行为或无关生产逻辑被扩大，而现有证据不能说明局部方案为何无法安全、完整地满足验收，应作为纯实现问题交回 Apply 收缩。
+- 对当前审查范围内的 Diff，分别判断“是否漏实现”和“是否超出必要范围”：直接消费者没有实现、或没有现有实现已满足验收的证据，属于完整性问题；计划或验收没有要求、也没有直接必要性证据的语义扩大，属于范围问题，应作为纯实现问题交回 Apply 收缩，文件数量和新增私有局部函数本身不是问题。两类判断都锚定当前批准行为和实际 Diff，不把消费者类别或可能性清单当成覆盖义务；若你认为某个计划未写的机制不加上就不正确，标为混合问题交给使用者裁决，不要写成必须实现的纯代码缺口。
 - 测试是否实际证明相关行为和直接回归风险，而非只存在一条通过记录。
 - 需求源已更新时，代码是否仍在执行过期计划；此类问题按方案或需求缺口归因，不把旧材料当作当前依据。
 
 风格偏好、无证据的猜测、历史无关问题和“另一种写法更优雅”不阻塞。不要用“最小改动”要求遗漏批准范围。
 
-将问题归因为：纯实现问题（可回 apply 修复）、方案/需求问题（计划不能支持正确实现）或混合问题（需要主流程处理分歧），并说明依据。不要用审查建议创造新的需求或架构。
+将问题归因为：纯实现问题（可回 apply 修复，含收缩）、方案/需求问题（计划不能支持正确实现）或混合问题（需要主流程处理分歧），并说明依据。不要用审查建议创造新的需求或架构。
 
 纯实现问题要说明为什么不需要改变计划；方案或混合问题要说明为什么单纯改代码无法满足已确认验收。复核修复时，Apply 可以通过代码变化关闭问题，也可以用可核实的调用链、兼容约束或验证证据说明原实现必须保留；证据成立时关闭原问题，证据不足时沿用原 finding，不因实现者偏好或审查者偏好反复争论。无阻塞问题时也说明尚未验证的风险，避免把审查覆盖当作全局保证。
 

package/templates/workflow/prompts/critic.md

@@ -45,6 +45,7 @@ Discovery 准备结束时，从本次变更及已有证据出发，反向检查
 - 计划通过前，执行者应能在不重新决定产品语义或重做架构设计的前提下开始 Apply。会改变数据归属、调用路径、一致性或发布顺序的候选路线不得留给 Apply 临时选择。跨越可独立发布、失败或验证边界的 task，未经核实却被当成既定事实的外部依赖，以及无法证明已声明行为或设计直接风险的测试契约，都会削弱这一条件。
 - 检查计划自己声明的关键不变量是否在迁移、兼容、回退和失败路径下仍成立；新旧实现同时存在且可能承担同一写入责任时，计划应明确权威写入边界，避免实现阶段重新决定所有权。
 - 需求语义未闭合的问题属于 Explore；需求结果已经明确、但不同可行路线会改变迁移、兼容、数据归属、发布、成本或长期责任边界时，计划应让使用者明确选择。只有内部实现不同且不改变这些结果时，不得要求新增用户决定。
+- 未改变的既有风险和没有已声明可观察结果的理论故障，标残余风险，不得升级为 required fix。本条不削弱上两条。
 
 建议只能说明需补足的事实、范围或闭环，不能把个人技术偏好、新基础设施或额外测试升级为强制要求。已声明行为及其直接边界有充分证据时停止。
 

package/templates/workflow/prompts/executor.md

@@ -25,6 +25,7 @@ argument-hint: "本次执行说明"
 
 - 先理解已有实现、调用点与测试模式，再作最小可维护改动；不要为局部任务引入未经计划的新框架、基础设施或重构。
 - 保持已有公共接口、数据语义、错误处理和兼容行为，除非 task 明确要求改变。
+- 代码审查修复只兑现该问题锚定的已批准行为；审查建议里的架构不是实现授权。
 - 记录实际修改、验证候选和不能验证的原因。失败或不确定不是完成，不要用推测补足证据。
 
 ## 输出