@peterxiaoyang/superspec 0.1.38 → 0.1.39

package/dist/transition.js

@@ -1,82 +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 { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE, REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE_ID, } from "./review_job_gates.js";
-import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketDigest, collectCodeReviewGateFacts, dismissedCodeReviewSummary, latestCodeReviewDecision, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, scanCodeChanges, } from "./code_review.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 { validateDiscovery, collectProposeOpenQuestions, findTaskInLines, pendingTasksInContent } from "./format.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}`; }
-/**
- * 通用 job 检查/创建逻辑——任何 transition 都能调用。
- * 检查 requiredRoles 是否有 fresh accepted job；缺则创建新 job。
- * 返回 null = 全部满足；返回 Decision = 需要创建 job（状态不变）。
- */
-function checkOrCreateReviewJobs(snapshot, gate, requiredRoles, changeRoot, change) {
-    const staleRoles = [];
-    for (const role of requiredRoles) {
-        const openForRole = snapshot.open_jobs.find(j => gate.isJobForGate(j) && j.role === role);
-        if (openForRole)
-            return { blocked: true, reason: `状态未推进；已有待完成工作项 ${role}（${openForRole.job_id}）`, jobs: [openForRole] };
-        const fresh = snapshot.accepted_jobs.find(j => gate.isJobForGate(j) && j.role === role);
-        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 = gate.reviewedDocPaths.filter(p => existsSync(join(changeRoot, p))).map(p => ({ path: p, sha: sha256File(join(changeRoot, p)) ?? "sha256:missing" }));
-            return {
-                job_id: newJobId(change, role),
+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 {
+            job_id: newJobId(change, role),
+            role,
+            state: "requested",
+            gate_id: gate.gate_id,
+            boundFiles,
+            packet_digest: sha256Text(JSON.stringify({
                 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 {
-            fromState: snapshot.state, toState: snapshot.state, outcome: "job_created",
-            newJobs, reason: staleRoles.map(s => s.reason).join("; "),
+            })),
+            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 (PROPOSE_FINAL_REVIEW_GATE.isJobForGate(job) &&
-                (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
@@ -85,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 formatPendingTaskMessage(ids, action) {
-    return `尚有未完成任务：${ids.join(", ")}；${action}`;
+function boundarySnapshotPayload(projectRoot) {
+    const result = boundarySnapshotResult(projectRoot);
+    return {
+        boundary_snapshot: result.snapshot,
+        ...(result.reason ? { boundary_snapshot_reason: result.reason } : {}),
+    };
+}
+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();
@@ -106,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);
@@ -126,6 +176,7 @@ function createCodeReviewerJob(change, projectRoot, events) {
         gate_id: REVIEW_CODE_REVIEW_GATE_ID,
         boundFiles,
         checkedDocs: REVIEW_DOC_PATHS,
+        packet_context: packetContext,
         created_from_transition: "review-ready",
         ...(previousRejection ? { previous_rejection: previousRejection } : {}),
     };
@@ -137,6 +188,7 @@ function createCodeReviewerJob(change, projectRoot, events) {
             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(),
@@ -179,14 +231,23 @@ 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 evaluateApplyDoneCodeReviewGate(input) {
-    const scan = scanCodeChanges(input.projectRoot);
+    const scan = scanCodeChangesForReview(input.projectRoot, input.events);
     const facts = collectCodeReviewGateFacts(input.events);
     if (scan.hasCodeChanges) {
-        const freshOpenJobs = facts.openJobs.filter(job => isFreshOpenCodeReviewerJob(job, input.projectRoot));
+        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,
@@ -196,6 +257,17 @@ function evaluateApplyDoneCodeReviewGate(input) {
         }
         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",
@@ -203,14 +275,19 @@ function evaluateApplyDoneCodeReviewGate(input) {
                 reason: "代码审查已通过，进入最终审查阶段",
                 commitPayload: {
                     ...input.policyPayload,
-                    code_review_gate: { decision: "passed", job_id: latest.job.job_id },
+                    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.events);
+                const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.changeRoot, input.events);
                 return {
                     fromState: "apply_done",
                     toState: "apply_done",
@@ -224,7 +301,7 @@ function evaluateApplyDoneCodeReviewGate(input) {
                 message: "代码审查发现需要处理的问题，请先执行 next，根据提示回到实现阶段修复或让使用者决定是否回到计划阶段",
             };
         }
-        const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.events);
+        const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.changeRoot, input.events);
         return {
             fromState: "apply_done",
             toState: "apply_done",
@@ -242,12 +319,19 @@ function evaluateApplyDoneCodeReviewGate(input) {
         reason: "没有代码类改动，直接进入最终审查阶段",
         commitPayload: {
             ...input.policyPayload,
-            code_review_gate: { decision: "skipped", reason: "no_code_changes" },
+            code_review_gate: {
+                decision: "skipped",
+                reason: "no_code_changes",
+                head: scan.scope?.current_head ?? null,
+            },
         },
     };
 }
-function createFinalVerifierJob(change, changeRoot, currentEvidenceDigest) {
+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",
@@ -255,11 +339,13 @@ function createFinalVerifierJob(change, changeRoot, currentEvidenceDigest) {
         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",
@@ -275,7 +361,7 @@ function evaluateFinalVerifierGate(input) {
             jobs: [verifierOpen],
         };
     }
-    const verifierAccepted = input.snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, input.changeRoot, input.currentEvidenceDigest));
+    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) {
@@ -291,7 +377,7 @@ function evaluateFinalVerifierGate(input) {
     }
     if (!verifierAccepted) {
         const previousVerifierRejected = hasRejectedReviewReadyVerifier(input.events);
-        const job = createFinalVerifierJob(input.change, input.changeRoot, input.currentEvidenceDigest);
+        const job = createFinalVerifierJob(input.change, input.projectRoot, input.changeRoot, input.events, input.currentEvidenceDigest);
         return {
             fromState: input.snapshot.state,
             toState: input.snapshot.state,
@@ -317,31 +403,23 @@ function evaluateFinalVerifierGate(input) {
     }
     return { skip: true, message: "已在 review 状态，最终验证仍然有效" };
 }
-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";
-    }
-    return baseline;
-}
-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 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,
+            };
     }
-    return null;
-}
-function proposalDocsChangedSinceBaseline(changeRoot, baseline) {
-    const current = documentBaseline(changeRoot);
-    return Object.entries(baseline).some(([path, digest]) => current[path] !== digest);
 }
 /**
  * 统一 transition 提交协议——所有校验在锁内。
@@ -433,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 = PROPOSE_FINAL_REVIEW_GATE.requiredRolesForRisk(risk);
-            const reviewResult = checkOrCreateReviewJobs(snapshot, PROPOSE_FINAL_REVIEW_GATE, requiredRoles, changeRoot, change);
-            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);
         },
     });
 }
@@ -479,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 = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(risk);
-                const reviewResult = checkOrCreateReviewJobs(snapshot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles, changeRoot, change);
-                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);
         },
     });
 }
@@ -505,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, PROPOSE_FINAL_REVIEW_GATE, reviewedRoles, changeRoot, change);
-                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);
         },
     });
 }
@@ -534,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 }),
+                },
             };
         },
     });
@@ -599,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),
                     },
                 };
             }
@@ -644,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 {
@@ -667,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 {
@@ -682,6 +770,7 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
                 return evaluateApplyDoneCodeReviewGate({
                     events,
                     projectRoot,
+                    changeRoot,
                     change,
                     policyPayload,
                 });
@@ -691,6 +780,7 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
                     snapshot,
                     events,
                     change,
+                    projectRoot,
                     changeRoot,
                     currentEvidenceDigest,
                     policy,
@@ -707,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);
         },
     });
 }
@@ -739,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",
@@ -756,10 +837,13 @@ 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");
@@ -768,28 +852,35 @@ export function taskComplete(projectRoot, change, changeRoot, taskId) {
             const readiness = taskEvidenceReadiness(projectRoot, change, changeRoot, attempt);
             if (!readiness.ready)
                 return { skip: true, message: `任务 ${taskId} 无法完成：${readiness.reason}` };
-            // B1 修复：checkbox 写入移到 postCommit（commit 事件写入后执行）
+            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" };
                 },
             };
         },