@peterxiaoyang/superspec 0.1.37 → 0.1.39

package/dist/transition.js

@@ -1,78 +1,49 @@
 // SuperSpec 流程引擎 — transition：提交协议 + 所有 transition 处理器
 import { join } from "node:path";
-import { existsSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
-import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot, snapshotDigest, withLock, idempotencyKey, sha256File, sha256Text, } from "./store.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot, snapshotDigest, withLock, idempotencyKey, docRef, listMarkdownFiles, sha256File, sha256Text, } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
 import { requiredJobActions } from "./job_action.js";
 import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, REVIEW_DOC_PATHS, } from "./review.js";
-import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketDigest, collectCodeReviewGateFacts, dismissedCodeReviewSummary, latestCodeReviewDecision, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, scanCodeChanges, } from "./code_review.js";
-import { validateDiscovery, collectProposeOpenQuestions, findTaskInLines, parseTasksMd, pendingTasksInContent, tasksStructureDigest } from "./format.js";
+import { REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE_ID, } from "./review_job_gates.js";
+import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketContext, codeReviewPacketDigest, collectCodeReviewGateFacts, computeCodeStateCheck, currentCodeReviewWorkingPaths, dismissedCodeReviewSummary, latestCodeReviewDecision, latestCodeReviewFailedStatus, missingCoverageExemptionTestIds, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, } from "./code_review.js";
+import { taskEvidenceReadiness } from "./task_evidence.js";
+import { adoptedContractForTask, findTaskInLines, isReviewFixTaskId, parseTasksMd, parseTestContractEntries, } from "./format.js";
+import { applyRequirementModeForCurrentRound, formatPendingTaskMessage, pendingTaskStatusForApply, planTransition, proposalDocsBaseline, } from "./phase_plan.js";
+import { currentGitHead, dirtyCodeFiles } from "./git_state.js";
 let transitionSeq = 0;
 function newTransitionId() { return `T-${Date.now()}-${++transitionSeq}`; }
 let jobSeq = 0;
 function newJobId(change, role) { return `JOB-${change.slice(0, 8)}-${role.slice(0, 4)}-${Date.now()}-${++jobSeq}`; }
-const TRANSITION_REQUIREMENTS = {
-    "propose-ready": {
-        minimal: [],
-        normal: ["critic"],
-        strict: ["critic", "architect", "test-engineer"],
-    },
-    "explore": {
-        minimal: [],
-        normal: [],
-        strict: ["critic"],
-    },
-};
-/**
- * 通用 job 检查/创建逻辑——任何 transition 都能调用。
- * 检查 requiredRoles 是否有 fresh accepted job；缺则创建新 job。
- * 返回 null = 全部满足；返回 Decision = 需要创建 job（状态不变）。
- */
-function checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, transitionName, bindDocPaths) {
-    const staleRoles = [];
-    for (const role of requiredRoles) {
-        const openForRole = snapshot.open_jobs.find(j => j.role === role && j.created_from_transition === transitionName);
-        if (openForRole)
-            return { blocked: true, reason: `状态未推进；已有待完成工作项 ${role}（${openForRole.job_id}）`, jobs: [openForRole] };
-        const fresh = snapshot.accepted_jobs.find(j => j.role === role && j.created_from_transition === transitionName);
-        if (!fresh) {
-            staleRoles.push({ role, reason: `需求 ${role} 无已接受的工作项` });
-        }
-        else {
-            for (const bf of fresh.boundFiles) {
-                const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
-                if (currentSha !== bf.sha) {
-                    staleRoles.push({ role, reason: `${role} 绑定文件 ${bf.path} 已变化` });
-                    break;
-                }
-            }
-        }
-    }
-    if (staleRoles.length > 0) {
-        const newJobs = staleRoles.map(({ role }) => {
-            const boundFiles = bindDocPaths.filter(p => existsSync(join(changeRoot, p))).map(p => ({ path: p, sha: sha256File(join(changeRoot, p)) ?? "sha256:missing" }));
-            return { job_id: newJobId(change, role), role, state: "requested", boundFiles, packet_digest: sha256Text(JSON.stringify({ role, boundFiles })), created_from_transition: transitionName, created_at: new Date().toISOString() };
-        });
+function createReviewJobsForGate(state, gate, roles, changeRoot, change, reason) {
+    const newJobs = roles.map(role => {
+        // 目录路径（以 / 结尾）始终绑定聚合指纹：审查时不存在、审查后新建同样视为变化
+        const boundFiles = gate.reviewedDocPaths
+            .filter(p => p.endsWith("/") || existsSync(join(changeRoot, p)))
+            .map(p => docRef(changeRoot, p));
         return {
-            fromState: snapshot.state, toState: snapshot.state, outcome: "job_created",
-            newJobs, reason: staleRoles.map(s => s.reason).join("; "),
+            job_id: newJobId(change, role),
+            role,
+            state: "requested",
+            gate_id: gate.gate_id,
+            boundFiles,
+            packet_digest: sha256Text(JSON.stringify({
+                role,
+                gate_id: gate.gate_id,
+                boundFiles,
+                created_from_transition: gate.created_from_transition,
+            })),
+            created_from_transition: gate.created_from_transition,
+            created_at: new Date().toISOString(),
         };
-    }
-    return null; // 全部满足
-}
-function historicalProposeReadyRoles(projectRoot, change) {
-    const roles = new Set();
-    for (const ev of readEvents(projectRoot, change)) {
-        if (ev.event_type !== "transition_commit")
-            continue;
-        const newJobs = ev.payload.new_jobs ?? [];
-        for (const job of newJobs) {
-            if (job.created_from_transition === "propose-ready" &&
-                (job.role === "critic" || job.role === "architect" || job.role === "test-engineer"))
-                roles.add(job.role);
-        }
-    }
-    return [...roles];
+    });
+    return {
+        fromState: state,
+        toState: state,
+        outcome: "job_created",
+        newJobs,
+        reason,
+    };
 }
 /**
  * 已迁移到 format.ts：findTaskInLines / parseTasksMd / tasksStructureDigest
@@ -81,12 +52,94 @@ function historicalProposeReadyRoles(projectRoot, change) {
 function findTaskLine(lines, taskId) {
     return findTaskInLines(lines, taskId);
 }
-function pendingTaskIds(changeRoot) {
-    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
-    return pendingTasksInContent(tasksContent).map(task => task.taskId);
+function boundarySnapshotResult(projectRoot) {
+    const head = currentGitHead(projectRoot);
+    const dirty = dirtyCodeFiles(projectRoot);
+    if (!dirty.ok)
+        return { snapshot: null, reason: dirty.reason };
+    return {
+        snapshot: {
+            head: head.head,
+            ...(head.reason !== "ok" ? { head_reason: head.reason } : {}),
+            dirty_files: dirty.files,
+        },
+    };
+}
+function boundarySnapshotPayload(projectRoot) {
+    const result = boundarySnapshotResult(projectRoot);
+    return {
+        boundary_snapshot: result.snapshot,
+        ...(result.reason ? { boundary_snapshot_reason: result.reason } : {}),
+    };
 }
-function formatPendingTaskMessage(ids, action) {
-    return `尚有未完成任务：${ids.join(", ")}；${action}`;
+function parseScopeNoteInput(inputContent) {
+    if (inputContent == null)
+        return { ok: true, value: null, digest: null };
+    const digest = sha256Text(inputContent);
+    if (inputContent.trim() === "")
+        return { ok: false, message: "范围扩大说明（scope_note）输入不能为空", digest };
+    let parsed;
+    try {
+        parsed = JSON.parse(inputContent);
+    }
+    catch {
+        return { ok: false, message: "范围扩大说明（scope_note）输入必须是有效 JSON", digest };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, message: "范围扩大说明（scope_note）输入顶层必须是 JSON object", digest };
+    }
+    const obj = parsed;
+    const keys = Object.keys(obj);
+    if (keys.some(key => key !== "scope_note")) {
+        return { ok: false, message: "范围扩大说明（scope_note）输入包含未知顶层字段", digest };
+    }
+    const note = obj.scope_note;
+    if (!note || typeof note !== "object" || Array.isArray(note)) {
+        return { ok: false, message: "范围扩大说明（scope_note）必须是对象", digest };
+    }
+    const noteObj = note;
+    const allowed = new Set(["reason", "changed_area", "plan_alignment", "verification"]);
+    if (Object.keys(noteObj).some(key => !allowed.has(key))) {
+        return { ok: false, message: "范围扩大说明（scope_note）包含未知字段", digest };
+    }
+    for (const field of ["reason", "changed_area", "plan_alignment"]) {
+        if (typeof noteObj[field] !== "string" || noteObj[field].trim() === "") {
+            return { ok: false, message: `范围扩大说明里的 ${field} 字段（scope_note.${field}）必须是非空字符串`, digest };
+        }
+    }
+    if (!Array.isArray(noteObj.verification) || noteObj.verification.length === 0 || !noteObj.verification.every(item => typeof item === "string" && item.trim() !== "")) {
+        return { ok: false, message: "范围扩大说明里的验证字段（scope_note.verification）必须是非空字符串数组", digest };
+    }
+    return {
+        ok: true,
+        digest,
+        value: {
+            reason: noteObj.reason,
+            changed_area: noteObj.changed_area,
+            plan_alignment: noteObj.plan_alignment,
+            verification: noteObj.verification,
+        },
+    };
+}
+function validateTaskStartContract(changeRoot, taskId, tddRequired, parsedContract) {
+    if (!parsedContract)
+        return null;
+    if (parsedContract.errors.length > 0)
+        return parsedContract.errors.join("；");
+    if (tddRequired && !isReviewFixTaskId(taskId) && parsedContract.contract.tests.length === 0) {
+        return `${taskId} 是普通 TDD 任务，执行依据缺少测试`;
+    }
+    if (parsedContract.contract.tests.length === 0)
+        return null;
+    const testContractPath = join(changeRoot, ".superspec", "artifacts", "test-contract.md");
+    if (!existsSync(testContractPath))
+        return "test-contract.md 不存在，无法校验执行依据测试引用";
+    const parsed = parseTestContractEntries(readFileSync(testContractPath, "utf8"));
+    if (!parsed.ok)
+        return parsed.message;
+    const known = new Set(parsed.entries.map(entry => entry.test_id));
+    const missing = parsedContract.contract.tests.filter(testId => !known.has(testId));
+    return missing.length > 0 ? `执行依据引用了不存在的 TEST ID：${missing.join(", ")}` : null;
 }
 function hasRejectedReviewReadyVerifier(events) {
     const reviewReadyVerifierIds = new Set();
@@ -102,9 +155,10 @@ function hasRejectedReviewReadyVerifier(events) {
     return events.some(ev => ev.event_type === "job_rejected" &&
         reviewReadyVerifierIds.has(ev.payload.job_id ?? ""));
 }
-function createCodeReviewerJob(change, projectRoot, events) {
-    const scan = scanCodeChanges(projectRoot);
+function createCodeReviewerJob(change, projectRoot, changeRoot, events) {
+    const scan = scanCodeChangesForReview(projectRoot, events);
     const boundFiles = codeReviewBoundFiles(projectRoot, scan.paths);
+    const packetContext = codeReviewPacketContext(changeRoot, projectRoot, scan.scope, events);
     const facts = collectCodeReviewGateFacts(events);
     const latestRejected = facts.latestRejected;
     const reviewFailedStatus = latestCodeReviewFailedStatus(events);
@@ -119,8 +173,10 @@ function createCodeReviewerJob(change, projectRoot, events) {
         : undefined;
     const packetInput = {
         role: "code-reviewer",
+        gate_id: REVIEW_CODE_REVIEW_GATE_ID,
         boundFiles,
         checkedDocs: REVIEW_DOC_PATHS,
+        packet_context: packetContext,
         created_from_transition: "review-ready",
         ...(previousRejection ? { previous_rejection: previousRejection } : {}),
     };
@@ -130,7 +186,9 @@ function createCodeReviewerJob(change, projectRoot, events) {
             job_id: newJobId(change, "code-reviewer"),
             role: "code-reviewer",
             state: "requested",
+            gate_id: REVIEW_CODE_REVIEW_GATE_ID,
             boundFiles,
+            packet_context: packetContext,
             packet_digest: codeReviewPacketDigest(packetInput),
             created_from_transition: "review-ready",
             created_at: new Date().toISOString(),
@@ -173,34 +231,195 @@ function appendReviewFixTask(changeRoot, ref, finding) {
     writeFileSync(tasksPath, `${content}${suffix}${line}\n`);
     return "created";
 }
-function isFreshOpenCodeReviewerJob(job, projectRoot) {
-    return codeReviewJobStaleReason(projectRoot, job) == null;
+function isFreshOpenCodeReviewerJob(job, projectRoot, currentWorkingPaths) {
+    return codeReviewJobStaleReason(projectRoot, job, currentWorkingPaths) == null;
+}
+function hasFrozenCodeReviewCurrentHead(scope) {
+    if (!scope || typeof scope !== "object")
+        return false;
+    if (!Object.prototype.hasOwnProperty.call(scope, "current_head"))
+        return false;
+    const currentHead = scope.current_head;
+    return currentHead === null || (typeof currentHead === "string" && currentHead.trim() !== "");
 }
-function documentBaseline(changeRoot) {
-    const docs = ["proposal.md", "design.md", "tasks.md", ".superspec/artifacts/test-contract.md"];
-    const baseline = {};
-    for (const doc of docs) {
-        baseline[doc] = sha256File(join(changeRoot, doc)) ?? "sha256:missing";
+function evaluateApplyDoneCodeReviewGate(input) {
+    const scan = scanCodeChangesForReview(input.projectRoot, input.events);
+    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));
+        if (freshOpenJobs.length > 0) {
+            return {
+                blocked: true,
+                reason: `状态未推进；已有待完成代码审查工作项 ${freshOpenJobs[0].job_id}`,
+                jobs: [freshOpenJobs[0]],
+            };
+        }
+        const latest = facts.latestTerminal;
+        if (latest?.state === "accepted") {
+            const acceptedScope = latest.job.packet_context?.code_review_scope;
+            if (!hasFrozenCodeReviewCurrentHead(acceptedScope)) {
+                const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.changeRoot, input.events);
+                return {
+                    fromState: "apply_done",
+                    toState: "apply_done",
+                    outcome: "job_created",
+                    newJobs: [job],
+                    reason: `已接受代码审查工作项缺少冻结 current_head，重新创建代码审查工作项；${scanReason}`,
+                };
+            }
+            return {
+                fromState: "apply_done",
+                toState: "review",
+                outcome: "advanced",
+                reason: "代码审查已通过，进入最终审查阶段",
+                commitPayload: {
+                    ...input.policyPayload,
+                    code_review_gate: {
+                        decision: "passed",
+                        job_id: latest.job.job_id,
+                        packet_digest: latest.job.packet_digest,
+                        current_head: acceptedScope.current_head,
+                    },
+                },
+            };
+        }
+        if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
+            const reviewFailedStatus = latestCodeReviewFailedStatus(input.events);
+            if (reviewFailedStatus && reviewFailedStatus.findings.length > 0 && reviewFailedStatus.unresolved.length === 0) {
+                const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.changeRoot, input.events);
+                return {
+                    fromState: "apply_done",
+                    toState: "apply_done",
+                    outcome: "job_created",
+                    newJobs: [job],
+                    reason: `重新创建代码审查工作项；${scanReason}；上一次阻塞问题已被主流程复核驳回`,
+                };
+            }
+            return {
+                skip: true,
+                message: "代码审查发现需要处理的问题，请先执行 next，根据提示回到实现阶段修复或让使用者决定是否回到计划阶段",
+            };
+        }
+        const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.changeRoot, input.events);
+        return {
+            fromState: "apply_done",
+            toState: "apply_done",
+            outcome: "job_created",
+            newJobs: [job],
+            reason: latest?.state === "rejected"
+                ? `重新创建代码审查工作项；上一次报告未被接受，原因：${latest.reason ?? "报告不符合要求"}`
+                : `创建代码审查工作项；${scanReason}`,
+        };
     }
-    return baseline;
+    return {
+        fromState: "apply_done",
+        toState: "review",
+        outcome: "advanced",
+        reason: "没有代码类改动，直接进入最终审查阶段",
+        commitPayload: {
+            ...input.policyPayload,
+            code_review_gate: {
+                decision: "skipped",
+                reason: "no_code_changes",
+                head: scan.scope?.current_head ?? null,
+            },
+        },
+    };
 }
-function latestReopenProposeBaseline(events) {
-    for (let i = events.length - 1; i >= 0; i--) {
-        const ev = events[i];
-        if (ev.event_type !== "transition_commit")
-            continue;
-        const payload = ev.payload;
-        if (payload.transition !== "reopen" || payload.reopen_target !== "propose")
-            continue;
-        if (!payload.baseline_docs || typeof payload.baseline_docs !== "object" || Array.isArray(payload.baseline_docs))
-            return null;
-        return payload.baseline_docs;
+function createFinalVerifierJob(change, projectRoot, changeRoot, events, currentEvidenceDigest) {
+    const boundFiles = reviewBoundFiles(changeRoot);
+    const packetContext = {
+        code_state_check: computeCodeStateCheck(projectRoot, events),
+    };
+    return {
+        job_id: newJobId(change, "verifier"),
+        role: "verifier",
+        state: "requested",
+        gate_id: REVIEW_FINAL_VERIFIER_GATE_ID,
+        boundFiles,
+        review_evidence_digest: currentEvidenceDigest,
+        packet_context: packetContext,
+        packet_digest: sha256Text(JSON.stringify({
+            role: "verifier",
+            gate_id: REVIEW_FINAL_VERIFIER_GATE_ID,
+            boundFiles,
+            review_evidence_digest: currentEvidenceDigest,
+            packet_context: packetContext,
+            created_from_transition: "review-ready",
+        })),
+        created_from_transition: "review-ready",
+        created_at: new Date().toISOString(),
+    };
+}
+function evaluateFinalVerifierGate(input) {
+    const verifierOpen = input.snapshot.open_jobs.find(isReviewReadyVerifier);
+    if (verifierOpen) {
+        return {
+            blocked: true,
+            reason: `状态未推进；已有待完成最终验证工作项 ${verifierOpen.job_id}`,
+            jobs: [verifierOpen],
+        };
+    }
+    const verifierAccepted = input.snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, input.changeRoot, input.currentEvidenceDigest, input.projectRoot, input.events));
+    const finalVerifierRequired = requiresFinalVerifierForCurrentReview(input.events) || input.policy.requires_verifier;
+    if (!finalVerifierRequired) {
+        if (!input.hasStoredPolicy) {
+            return {
+                fromState: "review",
+                toState: "review",
+                outcome: "advanced",
+                reason: `补写审查策略=${input.policy.review_risk}`,
+                commitPayload: input.policyPayload,
+            };
+        }
+        return { skip: true, message: "已在 review 状态，审查策略无需 verifier" };
     }
-    return null;
+    if (!verifierAccepted) {
+        const previousVerifierRejected = hasRejectedReviewReadyVerifier(input.events);
+        const job = createFinalVerifierJob(input.change, input.projectRoot, input.changeRoot, input.events, input.currentEvidenceDigest);
+        return {
+            fromState: input.snapshot.state,
+            toState: input.snapshot.state,
+            outcome: "job_created",
+            newJobs: [job],
+            reason: previousVerifierRejected
+                ? "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项"
+                : "创建最终验证工作项",
+            commitPayload: input.policyPayload,
+            ...(previousVerifierRejected ? {
+                details: { advisory: "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项" },
+            } : {}),
+        };
+    }
+    if (!input.hasStoredPolicy) {
+        return {
+            fromState: "review",
+            toState: "review",
+            outcome: "advanced",
+            reason: `补写审查策略=${input.policy.review_risk}`,
+            commitPayload: input.policyPayload,
+        };
+    }
+    return { skip: true, message: "已在 review 状态，最终验证仍然有效" };
 }
-function proposalDocsChangedSinceBaseline(changeRoot, baseline) {
-    const current = documentBaseline(changeRoot);
-    return Object.entries(baseline).some(([path, digest]) => current[path] !== digest);
+function transitionPlanToDecision(snapshot, changeRoot, change, plan) {
+    switch (plan.kind) {
+        case "skip":
+            return { skip: true, message: plan.message };
+        case "blocked":
+            return { blocked: true, reason: plan.reason, jobs: plan.jobs };
+        case "create_gate_jobs":
+            return createReviewJobsForGate(snapshot.state, plan.gate, plan.roles, changeRoot, change, plan.reason);
+        case "advance":
+            return {
+                fromState: plan.fromState,
+                toState: plan.toState,
+                outcome: "advanced",
+                reason: plan.reason,
+                commitPayload: plan.payload,
+            };
+    }
 }
 /**
  * 统一 transition 提交协议——所有校验在锁内。
@@ -292,32 +511,16 @@ export function proposeReady(projectRoot, change, changeRoot, risk = "strict") {
     return commitTransition(projectRoot, change, changeRoot, {
         name: "propose-ready", idempotencyInputs: { risk },
         decide: (snapshot) => {
-            if (snapshot.state !== "propose")
-                return { skip: true, message: `当前状态 ${snapshot.state}，不能 propose-ready` };
-            const tasksPath = join(changeRoot, "tasks.md");
-            if (!existsSync(tasksPath))
-                return { skip: true, message: "tasks.md 不存在" };
-            const tasksContent = readFileSync(tasksPath, "utf8");
-            if (!tasksContent.includes("# Tasks") && !tasksContent.includes("- [ ]"))
-                return { skip: true, message: "tasks.md 内容不像任务计划文档" };
-            const openQuestions = collectProposeOpenQuestions(changeRoot);
-            if (openQuestions.openCount > 0) {
-                const files = openQuestions.files.map(f => `${f.path}(${f.openCount})`).join(", ");
-                return { skip: true, message: `计划文档有 ${openQuestions.openCount} 个待用户确认问题：${files}` };
-            }
-            if (risk !== "minimal") {
-                const artifactsDir = join(changeRoot, ".superspec", "artifacts");
-                for (const doc of ["discovery.md", "business-invariants.md", "test-contract.md"]) {
-                    if (!existsSync(join(artifactsDir, doc)))
-                        return { skip: true, message: `基础职责缺失：${doc} 不存在（risk=${risk} 需要）` };
-                }
-            }
-            // 通用 job 检查（用提取的 helper）
-            const requiredRoles = TRANSITION_REQUIREMENTS["propose-ready"]?.[risk] ?? [];
-            const reviewResult = checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, "propose-ready", ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"]);
-            if (reviewResult)
-                return reviewResult;
-            return { fromState: "propose", toState: "propose_ready", outcome: "advanced", reason: `risk=${risk}，所有需求已满足` };
+            const events = readEvents(projectRoot, change);
+            const plan = planTransition("propose-ready", {
+                projectRoot,
+                change,
+                changeRoot,
+                events,
+                snapshot,
+                mode: { kind: "risk", risk },
+            });
+            return transitionPlanToDecision(snapshot, changeRoot, change, plan);
         },
     });
 }
@@ -338,24 +541,16 @@ export function transitionExplore(projectRoot, change, changeRoot, risk = "stric
     return commitTransition(projectRoot, change, changeRoot, {
         name: "explore", idempotencyInputs: { phase: "explore", risk },
         decide: (snapshot) => {
-            if (snapshot.state === "init")
-                return { fromState: "init", toState: "explore", outcome: "advanced", reason: "进入探索阶段" };
-            if (snapshot.state === "explore") {
-                const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
-                if (!existsSync(discoveryPath))
-                    return { skip: true, message: "discovery.md 不存在" };
-                // explore→propose：校验 discovery + strict 模式下的 critic 审查
-                const discoveryCheck = validateDiscovery(changeRoot);
-                if (!discoveryCheck.ok)
-                    return { skip: true, message: discoveryCheck.message };
-                // 通用 job 审查（和 propose-ready 同一个 helper）
-                const requiredRoles = TRANSITION_REQUIREMENTS["explore"]?.[risk] ?? [];
-                const reviewResult = checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, "explore", [".superspec/artifacts/discovery.md"]);
-                if (reviewResult)
-                    return reviewResult;
-                return { fromState: "explore", toState: "propose", outcome: "advanced", reason: "探索完成" };
-            }
-            return { skip: true, message: `当前状态 ${snapshot.state}，explore 不适用` };
+            const events = readEvents(projectRoot, change);
+            const plan = planTransition("explore", {
+                projectRoot,
+                change,
+                changeRoot,
+                events,
+                snapshot,
+                mode: { kind: "risk", risk },
+            });
+            return transitionPlanToDecision(snapshot, changeRoot, change, plan);
         },
     });
 }
@@ -364,24 +559,16 @@ export function startApply(projectRoot, change, changeRoot) {
     return commitTransition(projectRoot, change, changeRoot, {
         name: "start-apply", idempotencyInputs: { phase: "start-apply" },
         decide: (snapshot) => {
-            if (snapshot.state !== "propose_ready")
-                return { skip: true, message: `当前状态 ${snapshot.state}，需要 propose_ready` };
             const events = readEvents(projectRoot, change);
-            const reopenBaseline = latestReopenProposeBaseline(events);
-            if (reopenBaseline && !proposalDocsChangedSinceBaseline(changeRoot, reopenBaseline)) {
-                return { skip: true, message: "回到 propose 后 proposal/design/tasks/test-contract 至少一个文档必须变化" };
-            }
-            const reviewedRoles = historicalProposeReadyRoles(projectRoot, change);
-            if (reviewedRoles.length > 0) {
-                const reviewResult = checkOrCreateReviewJobs(snapshot, reviewedRoles, changeRoot, change, "propose-ready", ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"]);
-                if (reviewResult) {
-                    return {
-                        ...reviewResult,
-                        reason: `进入执行阶段前需要重新完成计划文档审查：${reviewResult.reason}`,
-                    };
-                }
-            }
-            return { fromState: "propose_ready", toState: "apply", outcome: "advanced", reason: "进入执行阶段" };
+            const plan = planTransition("start-apply", {
+                projectRoot,
+                change,
+                changeRoot,
+                events,
+                snapshot,
+                mode: { kind: "risk", risk: "strict" },
+            });
+            return transitionPlanToDecision(snapshot, changeRoot, change, plan);
         },
     });
 }
@@ -393,31 +580,64 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
         decide: (snapshot) => {
             if (snapshot.state !== "apply")
                 return { skip: true, message: `当前状态 ${snapshot.state}，需要 apply` };
+            const events = readEvents(projectRoot, change);
             const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
             const lines = tasksContent.split("\n");
             const taskLineIdx = findTaskLine(lines, taskId);
             if (taskLineIdx < 0)
                 return { skip: true, message: `任务 ${taskId} 不存在` };
-            if (lines[taskLineIdx].match(/- \[x\]/))
+            const contractMode = applyRequirementModeForCurrentRound(events);
+            if (contractMode && pendingTaskStatusForApply(changeRoot, events).completedByEvent.includes(taskId)) {
+                return { skip: true, message: `任务 ${taskId} 已通过完成事件完成` };
+            }
+            if (lines[taskLineIdx].match(/- \[[xX]\]/))
                 return { skip: true, message: `任务 ${taskId} 已完成` };
+            const taskInfo = parseTasksMd(tasksContent).find(task => task.taskId === taskId);
+            if (!taskInfo)
+                return { skip: true, message: `任务 ${taskId} 不存在` };
             const existing = snapshot.active_task_attempts?.find(a => a.task_id === taskId && a.state === "active");
             if (existing)
                 return { skip: true, message: `任务 ${taskId} 已有活跃尝试` };
+            // 统一出口：adopted.contract 非 null 当且仅当契约模式下有绑定块；
+            // legacy 轮即使 task 带执行依据文本也输出 null，避免"看似契约、实按 legacy 校验"的误导态
+            const adopted = adoptedContractForTask(tasksContent, taskId, contractMode);
+            if (contractMode && taskInfo.tddRequired && !isReviewFixTaskId(taskId) && !adopted.parsed) {
+                return { skip: true, message: `执行依据模式下，普通 TDD 任务 ${taskId} 缺少执行依据` };
+            }
+            if (contractMode) {
+                const contractError = validateTaskStartContract(changeRoot, taskId, taskInfo.tddRequired, adopted.parsed);
+                if (contractError)
+                    return { skip: true, message: contractError };
+            }
             const structureDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
             const attempt = {
                 attempt_id: `ATT-${taskId}-${Date.now()}-${++attemptSeq}`,
                 task_id: taskId, state: "active",
                 task_structure_digest: structureDigest,
+                contract_mode: contractMode,
+                contract: adopted.contract,
+                tdd_required: taskInfo.tddRequired,
+                no_tdd_reason: taskInfo.noTddReason,
                 declared_write_scope: [], pre_edit_source_fingerprint: null,
                 pre_edit_red_ref: null, executor_packet_digest: null,
                 executor_result_ref: null, post_edit_green_ref: null,
                 created_at: new Date().toISOString(),
             };
+            const eventPayload = {
+                ...attempt,
+                ...boundarySnapshotPayload(projectRoot),
+            };
             return {
                 fromState: "apply", toState: "apply", outcome: "advanced",
                 reason: `创建任务 ${taskId} 执行尝试`,
-                extraEvents: [{ type: "task_started", payload: attempt }],
-                details: { attempt_id: attempt.attempt_id },
+                extraEvents: [{ type: "task_started", payload: eventPayload }],
+                details: {
+                    attempt_id: attempt.attempt_id,
+                    task_id: taskId,
+                    contract: adopted.contract,
+                    // legacy 轮统一标注历史模式（无论有无执行依据文本）；契约轮无块时标 false（如 REVIEW-FIX）
+                    ...(adopted.contract ? {} : { legacy_contract: !contractMode }),
+                },
             };
         },
     });
@@ -458,7 +678,7 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         source_job_id: ref.jobId,
                         finding_id: ref.findingId,
                         decision_scope: scope,
-                        baseline_docs: documentBaseline(changeRoot),
+                        baseline_docs: proposalDocsBaseline(changeRoot),
                     },
                 };
             }
@@ -503,7 +723,7 @@ 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` };
             }
-            const pending = pendingTaskIds(changeRoot);
+            const pending = pendingTaskStatusForApply(changeRoot, events).pending;
             if (pending.length === 0)
                 return { skip: true, message: "没有未完成任务，不能 reopen 到 apply" };
             return {
@@ -526,9 +746,18 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
             const policyPayload = storedPolicy ? {} : { review_policy: policy };
             const currentEvidenceDigest = reviewEvidenceDigest(events);
             // 检查是否所有任务已完成
-            const pending = pendingTaskIds(changeRoot);
+            const pending = pendingTaskStatusForApply(changeRoot, events).pending;
             if (pending.length > 0)
                 return { skip: true, message: formatPendingTaskMessage(pending, "请先通过 next/reopen 继续执行") };
+            if (applyRequirementModeForCurrentRound(events)) {
+                const missingExemptions = missingCoverageExemptionTestIds(changeRoot, events);
+                if (missingExemptions.length > 0) {
+                    return {
+                        skip: true,
+                        message: `test-contract 中存在未绑定任务且缺少覆盖豁免的 TEST：${missingExemptions.join(", ")}；请先向用户确认原因（不要代替用户决策），再执行 superspec record user-decision --change "${change}" --input - 登记，stdin 传入 JSON：{"scope":"test_coverage_exemption:${missingExemptions[0]}","question":"<向用户提出的问题>","answer":"<用户给出的豁免原因>"}`,
+                    };
+                }
+            }
             // 如果当前是 apply，先推进到 apply_done
             if (snapshot.state === "apply") {
                 return {
@@ -538,111 +767,26 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
                 };
             }
             if (snapshot.state === "apply_done") {
-                const scan = scanCodeChanges(projectRoot);
-                const facts = collectCodeReviewGateFacts(events);
-                if (scan.hasCodeChanges) {
-                    const freshOpenJobs = facts.openJobs.filter(job => isFreshOpenCodeReviewerJob(job, projectRoot));
-                    if (freshOpenJobs.length > 0) {
-                        return {
-                            blocked: true,
-                            reason: `状态未推进；已有待完成代码审查工作项 ${freshOpenJobs[0].job_id}`,
-                            jobs: [freshOpenJobs[0]],
-                        };
-                    }
-                    const latest = facts.latestTerminal;
-                    if (latest?.state === "accepted") {
-                        return {
-                            fromState: "apply_done", toState: "review", outcome: "advanced",
-                            reason: "代码审查已通过，进入最终审查阶段",
-                            commitPayload: {
-                                ...policyPayload,
-                                code_review_gate: { decision: "passed", job_id: latest.job.job_id },
-                            },
-                        };
-                    }
-                    if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
-                        const reviewFailedStatus = latestCodeReviewFailedStatus(events);
-                        if (reviewFailedStatus && reviewFailedStatus.findings.length > 0 && reviewFailedStatus.unresolved.length === 0) {
-                            const { job, scanReason } = createCodeReviewerJob(change, projectRoot, events);
-                            return {
-                                fromState: "apply_done", toState: "apply_done", outcome: "job_created",
-                                newJobs: [job],
-                                reason: `重新创建代码审查工作项；${scanReason}；上一次阻塞问题已被主流程复核驳回`,
-                            };
-                        }
-                        return {
-                            skip: true,
-                            message: "代码审查发现需要处理的问题，请先执行 next，根据提示回到实现阶段修复或让使用者决定是否回到计划阶段",
-                        };
-                    }
-                    const { job, scanReason } = createCodeReviewerJob(change, projectRoot, events);
-                    return {
-                        fromState: "apply_done", toState: "apply_done", outcome: "job_created",
-                        newJobs: [job],
-                        reason: latest?.state === "rejected"
-                            ? `重新创建代码审查工作项；上一次报告未被接受，原因：${latest.reason ?? "报告不符合要求"}`
-                            : `创建代码审查工作项；${scanReason}`,
-                    };
-                }
-                return {
-                    fromState: "apply_done", toState: "review", outcome: "advanced",
-                    reason: "没有代码类改动，直接进入最终审查阶段",
-                    commitPayload: {
-                        ...policyPayload,
-                        code_review_gate: { decision: "skipped", reason: "no_code_changes" },
-                    },
-                };
+                return evaluateApplyDoneCodeReviewGate({
+                    events,
+                    projectRoot,
+                    changeRoot,
+                    change,
+                    policyPayload,
+                });
             }
             if (snapshot.state === "review") {
-                const verifierOpen = snapshot.open_jobs.find(isReviewReadyVerifier);
-                if (verifierOpen)
-                    return { blocked: true, reason: `状态未推进；已有待完成最终验证工作项 ${verifierOpen.job_id}`, jobs: [verifierOpen] };
-                const verifierAccepted = snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest));
-                const finalVerifierRequired = requiresFinalVerifierForCurrentReview(events) || policy.requires_verifier;
-                if (!finalVerifierRequired) {
-                    if (!storedPolicy) {
-                        return {
-                            fromState: "review", toState: "review", outcome: "advanced",
-                            reason: `补写审查策略=${policy.review_risk}`,
-                            commitPayload: policyPayload,
-                        };
-                    }
-                    return { skip: true, message: "已在 review 状态，审查策略无需 verifier" };
-                }
-                if (!verifierAccepted) {
-                    const boundFiles = reviewBoundFiles(changeRoot);
-                    const previousVerifierRejected = hasRejectedReviewReadyVerifier(events);
-                    const job = {
-                        job_id: newJobId(change, "verifier"), role: "verifier", state: "requested",
-                        boundFiles, review_evidence_digest: currentEvidenceDigest,
-                        packet_digest: sha256Text(JSON.stringify({
-                            role: "verifier",
-                            boundFiles,
-                            review_evidence_digest: currentEvidenceDigest,
-                            created_from_transition: "review-ready",
-                        })),
-                        created_from_transition: "review-ready", created_at: new Date().toISOString(),
-                    };
-                    return {
-                        fromState: snapshot.state, toState: snapshot.state, outcome: "job_created",
-                        newJobs: [job],
-                        reason: previousVerifierRejected
-                            ? "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项"
-                            : "创建最终验证工作项",
-                        commitPayload: policyPayload,
-                        ...(previousVerifierRejected ? {
-                            details: { advisory: "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项" },
-                        } : {}),
-                    };
-                }
-                if (!storedPolicy) {
-                    return {
-                        fromState: "review", toState: "review", outcome: "advanced",
-                        reason: `补写审查策略=${policy.review_risk}`,
-                        commitPayload: policyPayload,
-                    };
-                }
-                return { skip: true, message: "已在 review 状态，最终验证仍然有效" };
+                return evaluateFinalVerifierGate({
+                    snapshot,
+                    events,
+                    change,
+                    projectRoot,
+                    changeRoot,
+                    currentEvidenceDigest,
+                    policy,
+                    policyPayload,
+                    hasStoredPolicy: Boolean(storedPolicy),
+                });
             }
             return { skip: true, message: `当前状态 ${snapshot.state}，review-ready 不适用` };
         },
@@ -653,22 +797,16 @@ export function accept(projectRoot, change, changeRoot) {
     return commitTransition(projectRoot, change, changeRoot, {
         name: "accept", idempotencyInputs: { phase: "accept" },
         decide: (snapshot) => {
-            if (snapshot.state !== "review")
-                return { skip: true, message: `当前状态 ${snapshot.state}，需要 review` };
-            const pending = pendingTaskIds(changeRoot);
-            if (pending.length > 0)
-                return { skip: true, message: formatPendingTaskMessage(pending, "请先 reopen --to apply 继续执行") };
             const events = readEvents(projectRoot, change);
-            const policy = readReviewPolicyFromEvents(events);
-            if (!policy)
-                return { skip: true, message: "缺少审查策略，请先运行 review-ready" };
-            if (requiresFinalVerifierForCurrentReview(events) || policy.requires_verifier) {
-                const currentEvidenceDigest = reviewEvidenceDigest(events);
-                const verifierAccepted = snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest));
-                if (!verifierAccepted)
-                    return { skip: true, message: "缺少仍然匹配当前证据的最终验证，请先运行 review-ready" };
-            }
-            return { fromState: "review", toState: "accepted", outcome: "advanced", reason: "审查通过" };
+            const plan = planTransition("accept", {
+                projectRoot,
+                change,
+                changeRoot,
+                events,
+                snapshot,
+                mode: { kind: "risk", risk: "strict" },
+            });
+            return transitionPlanToDecision(snapshot, changeRoot, change, plan);
         },
     });
 }
@@ -685,13 +823,10 @@ export function archive(projectRoot, change, changeRoot) {
             for (const p of docPaths) {
                 manifest[p] = sha256File(join(changeRoot, p)) ?? "sha256:missing";
             }
-            // specs/ 目录
+            // specs/ 目录：递归收录 .md（覆盖 specs/<capability>/spec.md 布局）
             const specsDir = join(changeRoot, "specs");
-            if (existsSync(specsDir)) {
-                for (const f of readdirSync(specsDir)) {
-                    if (f.endsWith(".md"))
-                        manifest[`specs/${f}`] = sha256File(join(specsDir, f)) ?? "sha256:missing";
-                }
+            for (const rel of listMarkdownFiles(specsDir)) {
+                manifest[`specs/${rel}`] = sha256File(join(specsDir, rel)) ?? "sha256:missing";
             }
             return {
                 fromState: "accepted", toState: "archive", outcome: "advanced",
@@ -702,73 +837,50 @@ export function archive(projectRoot, change, changeRoot) {
     });
 }
 // ===== task-complete =====
-export function taskComplete(projectRoot, change, changeRoot, taskId) {
+export function taskComplete(projectRoot, change, changeRoot, taskId, inputContent = null) {
+    const scopeInput = parseScopeNoteInput(inputContent);
     return commitTransition(projectRoot, change, changeRoot, {
-        name: "task-complete", idempotencyInputs: { task: taskId, phase: "complete" },
+        name: "task-complete", idempotencyInputs: { task: taskId, phase: "complete", scope_note_digest: scopeInput.digest ?? "" },
         decide: (snapshot) => {
+            if (!scopeInput.ok)
+                return { skip: true, message: scopeInput.message };
             if (snapshot.state !== "apply")
                 return { skip: true, message: `当前状态 ${snapshot.state}，需要 apply` };
             const attempt = snapshot.active_task_attempts?.find(a => a.task_id === taskId && a.state === "active");
             if (!attempt)
                 return { skip: true, message: `任务 ${taskId} 无活跃执行尝试` };
-            const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
-            const currentDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
-            if (currentDigest !== attempt.task_structure_digest)
-                return { skip: true, message: "任务结构指纹不匹配" };
-            // 解析任务属性（委托给 format.ts 的 parseTasksMd）
-            const tasks = parseTasksMd(tasksContent);
-            const taskInfo = tasks.find(t => t.taskId === taskId);
-            const isTdd = taskInfo?.tddRequired ?? true;
-            const hasNoTddReason = taskInfo?.noTddReason != null;
-            // RED/GREEN 检查（HIGH-2 修复：按 attempt_id 匹配，避免多任务 digest 碰撞）
-            const events = readEvents(projectRoot, change);
-            let hasRed = false, hasGreen = false;
-            for (const ev of events) {
-                if (ev.event_type === "test_run_recorded") {
-                    const tr = ev.payload;
-                    // 匹配当前 attempt（优先按 attempt_id，回退到 digest）
-                    const matches = tr.attempt_id === attempt.attempt_id ||
-                        (!tr.attempt_id && tr.task_structure_digest === attempt.task_structure_digest);
-                    if (matches) {
-                        if (tr.semantic_status === "expected_failure" || tr.semantic_status === "characterization_pass")
-                            hasRed = true;
-                        if (tr.semantic_status === "expected_success")
-                            hasGreen = true;
-                    }
-                }
-            }
-            if (isTdd) {
-                if (!hasRed)
-                    return { skip: true, message: `TDD 任务 ${taskId} 缺少 RED 证据` };
-                if (!hasGreen)
-                    return { skip: true, message: `TDD 任务 ${taskId} 缺少 GREEN 证据` };
-            }
-            else {
-                if (!hasNoTddReason)
-                    return { skip: true, message: `非 TDD 任务 ${taskId} 缺少 no_tdd_reason` };
-            }
-            // B1 修复：checkbox 写入移到 postCommit（commit 事件写入后执行）
+            const readiness = taskEvidenceReadiness(projectRoot, change, changeRoot, attempt);
+            if (!readiness.ready)
+                return { skip: true, message: `任务 ${taskId} 无法完成：${readiness.reason}` };
+            const completedPayload = {
+                task_id: taskId,
+                attempt_id: attempt.attempt_id,
+                ...boundarySnapshotPayload(projectRoot),
+                checkbox_update: { status: "pending" },
+                ...(scopeInput.value ? { scope_note: scopeInput.value } : {}),
+            };
             return {
                 fromState: "apply", toState: "apply", outcome: "advanced",
                 reason: `任务 ${taskId} 完成`,
-                extraEvents: [{ type: "task_completed", payload: { task_id: taskId, attempt_id: attempt.attempt_id } }],
+                extraEvents: [{ type: "task_completed", payload: completedPayload }],
                 postCommit: (_pr, _ch, cr) => {
                     const lines = readFileSync(join(cr, "tasks.md"), "utf8").split("\n");
                     const idx = findTaskLine(lines, taskId);
-                    if (idx < 0 || !lines[idx].match(/- \[ \]/))
-                        throw new Error(`找不到 ${taskId} 的未完成复选框`);
-                    // H2 修复：应用前验证结构指纹
-                    const beforeDigest = sha256Text(lines.join("\n").replace(/- \[[xX]\]/g, "- [ ]"));
+                    if (idx < 0) {
+                        completedPayload.checkbox_update = { status: "failed", reason: `找不到 ${taskId} 的任务行` };
+                        return;
+                    }
+                    if (lines[idx].match(/- \[[xX]\]/)) {
+                        completedPayload.checkbox_update = { status: "applied" };
+                        return;
+                    }
+                    if (!lines[idx].match(/- \[ \]/)) {
+                        completedPayload.checkbox_update = { status: "failed", reason: `找不到 ${taskId} 的未完成复选框` };
+                        return;
+                    }
                     lines[idx] = lines[idx].replace(/- \[ \]/, "- [x]");
                     writeFileSync(join(cr, "tasks.md"), lines.join("\n"));
-                    // H2 修复：应用后验证只有目标变了
-                    const afterLines = readFileSync(join(cr, "tasks.md"), "utf8").split("\n");
-                    const afterDigest = sha256Text(afterLines.join("\n").replace(/- \[[xX]\]/g, "- [ ]"));
-                    if (afterDigest !== beforeDigest) {
-                        afterLines[idx] = afterLines[idx].replace(/- \[x\]/, "- [ ]");
-                        writeFileSync(join(cr, "tasks.md"), afterLines.join("\n"));
-                        throw new Error(`复选框补丁导致结构变化：${taskId}`);
-                    }
+                    completedPayload.checkbox_update = { status: "applied" };
                 },
             };
         },