@peterxiaoyang/superspec 0.1.46 → 0.1.48

package/dist/transition.js

@@ -5,11 +5,11 @@ import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot,
 import { rebuildSnapshot } from "./sync.js";
 import { requiredJobActions } from "./job_action.js";
 import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, latestReviewHistoryForGateRole, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, REVIEW_DOC_PATHS, } from "./review.js";
-import { REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE_ID, reviewScopeForGateRole, } 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 { REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE, REVIEW_FINAL_VERIFIER_GATE_ID, reviewScopeForGateRole, } from "./review_job_gates.js";
+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, isReviewFixTaskId, parseTasksMd, parseTestContractEntries, } from "./format.js";
-import { applyRequirementModeForCurrentRound, executionRequirementVersionForCurrentRound, blockingJobsForApplyDone, executionPolicyForCurrentRound, formatPendingTaskMessage, latestAcceptedProposalBaseline, pendingTaskStatusForApply, planningValidationProfileForNewRound, planTransition, discoveryDocsBaseline, proposalDocsBaseline, } from "./phase_plan.js";
+import { adoptedContractForTask, findTaskInLines, isFixTaskId, parseTasksMd, parseTestContractEntries, } from "./format.js";
+import { applyRequirementModeForCurrentRound, executionRequirementVersionForCurrentRound, blockingJobsForApplyDone, executionPolicyForCurrentRound, formatPendingTaskMessage, latestAcceptedProposalBaseline, pendingTaskStatusForApply, planningValidationProfileForNewRound, planTransition, discoveryDocsBaseline, exploreAnswerRegistrationPayloadForChange, proposeAnswerRegistrationPayloadForChange, proposalDocsBaseline, } from "./phase_plan.js";
 import { latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { currentGitHead, dirtyCodeFiles, stageProductionJavaFilesSince } from "./git_state.js";
 import { workflowRiskForProject } from "./workflow_config.js";
@@ -17,9 +17,9 @@ 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}`; }
-function createReviewJobsForGate(state, gate, roles, changeRoot, change, reason, events) {
+function createReviewJobsForGate(state, gate, roles, requiredRoles, changeRoot, change, reason, events) {
     const newJobs = roles.map(role => {
-        const scope = reviewScopeForGateRole(gate, role);
+        const scope = reviewScopeForGateRole(gate, role, requiredRoles);
         // 角色职责目标和显式 freshness 路径绑定时点指纹：单文件缺失使用 sha256:missing，目录缺失使用稳定空指纹。
         const boundPaths = [...new Set(scope.boundPaths)];
         const boundFiles = boundPaths
@@ -173,13 +173,13 @@ function validateTaskStartContract(changeRoot, taskId, parsedContract) {
  */
 function validateLegacyTaskStartContract(changeRoot, taskId, tddRequired, parsedContract) {
     if (!parsedContract) {
-        return tddRequired && !isReviewFixTaskId(taskId)
+        return tddRequired && !isFixTaskId(taskId)
             ? `执行依据模式下，普通 TDD 任务 ${taskId} 缺少执行依据`
             : null;
     }
     if (parsedContract.errors.length > 0)
         return parsedContract.errors.join("；");
-    if (tddRequired && !isReviewFixTaskId(taskId) && parsedContract.contract.tests.length === 0) {
+    if (tddRequired && !isFixTaskId(taskId) && parsedContract.contract.tests.length === 0) {
         return `${taskId} 是普通 TDD 任务，执行依据缺少测试`;
     }
     if (parsedContract.contract.tests.length === 0)
@@ -199,7 +199,7 @@ function validateLegacyTaskStartContract(changeRoot, taskId, tddRequired, parsed
  * RED 是否要求由这里读取已冻结的 execution_policy 决定，之后不再依赖 tasks.md。
  */
 function compileRequiredEvidence(executionPolicy, testIds, requiresVerificationWithoutDeclaredTest) {
-    // REVIEW-FIX 没有计划阶段声明的 TEST，但仍必须登记一次真实回归验证。
+    // Fix task 没有计划阶段声明的 TEST，但仍必须登记一次真实回归验证。
     // 是否需要 RED 始终由已冻结的 execution_policy 决定。
     const requiresVerification = testIds.length > 0 || requiresVerificationWithoutDeclaredTest;
     return {
@@ -209,6 +209,28 @@ function compileRequiredEvidence(executionPolicy, testIds, requiresVerificationW
         accepted_green_statuses: ["expected_success"],
     };
 }
+function evidenceActionsForAttempt(change, attemptId, required) {
+    const testIds = required.test_ids.length > 0 ? required.test_ids : [undefined];
+    const statuses = [];
+    if (required.red_required)
+        statuses.push("expected_failure");
+    if (required.green_required)
+        statuses.push(required.accepted_green_statuses[0] ?? "expected_success");
+    return testIds.flatMap(testId => statuses.map(semanticStatus => ({
+        kind: "test_run",
+        ...(testId ? { test_id: testId } : {}),
+        record_argv: ["superspec", "record", "test-run", "--change", change, "--input", "-"],
+        record_input: {
+            ...(testId ? { test_id: testId } : {}),
+            attempt_id: attemptId,
+            command: null,
+            cwd: null,
+            exit_code: null,
+            semantic_status: semanticStatus,
+        },
+        required_fields: ["command", "cwd", "exit_code"],
+    })));
+}
 function hasRejectedReviewReadyVerifier(events) {
     const reviewReadyVerifierIds = new Set();
     for (const ev of events) {
@@ -279,26 +301,133 @@ function findReviewFailedFinding(events, ref) {
         return null;
     return { event: status.terminal.event, finding };
 }
-function reviewFixMarker(ref) {
-    return `review_fix_of:${ref.jobId}#${ref.findingId}`;
+function reviewFixDescriptor(ref, finding) {
+    const reason = typeof finding.description === "string" && finding.description.trim()
+        ? finding.description.trim().replace(/\s+/g, " ")
+        : `修复代码审查问题 ${ref.findingId}`;
+    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 },
+    };
+}
+function selfTestFixBaseId(parentTaskId, reason) {
+    const normalizedReason = reason.trim().replace(/\s+/g, " ");
+    const normalizedTaskId = parentTaskId.replace(/[^A-Za-z0-9_-]/g, "-");
+    const digest = sha256Text(`${parentTaskId}\n${normalizedReason}`).replace(/^sha256:/, "").slice(0, 12);
+    return `FIX-SELFTEST-${normalizedTaskId}-${digest}`;
+}
+function selfTestFixDescriptor(parentTaskId, reason, occurrence) {
+    const normalizedReason = reason.trim().replace(/\s+/g, " ");
+    const baseId = selfTestFixBaseId(parentTaskId, normalizedReason);
+    return {
+        fix_id: occurrence === 1 ? baseId : `${baseId}-${occurrence}`,
+        source: "self_test",
+        parent_task_id: parentTaskId,
+        reason: normalizedReason,
+    };
 }
-function reviewFixTaskId(ref) {
-    return `REVIEW-FIX-${ref.jobId}#${ref.findingId}`;
+function selfTestFixOccurrence(taskId, baseId) {
+    if (taskId === baseId)
+        return 1;
+    const suffix = taskId.slice(baseId.length + 1);
+    if (!taskId.startsWith(`${baseId}-`) || !/^\d+$/.test(suffix))
+        return null;
+    const occurrence = Number(suffix);
+    return Number.isSafeInteger(occurrence) && occurrence >= 2 ? occurrence : null;
 }
-function appendReviewFixTask(changeRoot, ref, finding) {
+function nextSelfTestFixDescriptor(changeRoot, events, parentTaskId, reason) {
+    const normalizedReason = reason.trim().replace(/\s+/g, " ");
+    const baseId = selfTestFixBaseId(parentTaskId, normalizedReason);
+    let maxOccurrence = 0;
+    const completion = pendingTaskStatusForApply(changeRoot, events);
+    const pendingTaskIds = new Set(completion.pending);
+    const taskInfos = parseTasksMd(readFileSync(join(changeRoot, "tasks.md"), "utf8"));
+    for (const task of taskInfos) {
+        const occurrence = selfTestFixOccurrence(task.taskId, baseId);
+        if (occurrence == null)
+            continue;
+        maxOccurrence = Math.max(maxOccurrence, occurrence);
+        if (pendingTaskIds.has(task.taskId))
+            return { activeFixTaskId: task.taskId };
+    }
+    for (const event of events) {
+        if (event.event_type !== "transition_commit")
+            continue;
+        const fix = event.payload.fix;
+        if (!fix || typeof fix !== "object" || Array.isArray(fix))
+            continue;
+        const candidate = fix;
+        if (candidate.source !== "self_test" || candidate.parent_task_id !== parentTaskId || candidate.reason !== normalizedReason)
+            continue;
+        if (typeof candidate.fix_id !== "string")
+            continue;
+        const occurrence = selfTestFixOccurrence(candidate.fix_id, baseId);
+        if (occurrence != null)
+            maxOccurrence = Math.max(maxOccurrence, occurrence);
+    }
+    return { fix: selfTestFixDescriptor(parentTaskId, normalizedReason, maxOccurrence + 1) };
+}
+function fixMarker(fix) {
+    if (fix.source === "code_review" && fix.review_finding) {
+        return `review_fix_of:${fix.review_finding.job_id}#${fix.review_finding.finding_id}`;
+    }
+    return `self_test_fix_of:${fix.parent_task_id ?? "unknown"}:${fix.fix_id}`;
+}
+function appendFixTask(changeRoot, fix) {
     const tasksPath = join(changeRoot, "tasks.md");
     const content = readFileSync(tasksPath, "utf8");
-    const marker = reviewFixMarker(ref);
-    if (content.includes(marker))
-        return "exists";
-    const description = typeof finding.description === "string" && finding.description.trim()
-        ? finding.description.trim().replace(/\s+/g, " ")
-        : `修复代码审查问题 ${ref.findingId}`;
-    const line = `- [ ] ${reviewFixTaskId(ref)} ${description} ${marker}`;
+    const marker = fixMarker(fix);
+    if (content.includes(marker)) {
+        const matchingTask = content.split("\n").some(line => line.includes(marker) && line.startsWith(`- [ ] ${fix.fix_id} `));
+        if (matchingTask)
+            return "exists";
+        throw new Error(`修复标记 ${marker} 已被其它 task 占用，拒绝创建 ${fix.fix_id}`);
+    }
+    if (parseTasksMd(content).some(task => task.taskId === fix.fix_id)) {
+        throw new Error(`修复 task ID ${fix.fix_id} 已被其它任务占用，拒绝创建重复修复`);
+    }
+    const description = fix.source === "self_test"
+        ? `修复自测问题（关联 ${fix.parent_task_id}）：${fix.reason}`
+        : fix.reason;
+    const line = `- [ ] ${fix.fix_id} ${description} ${marker}`;
     const suffix = content.endsWith("\n") ? "" : "\n";
     writeFileSync(tasksPath, `${content}${suffix}${line}\n`);
     return "created";
 }
+function fixDescriptorForTask(events, taskId) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const fix = event.payload.fix;
+        if (!fix || typeof fix !== "object" || Array.isArray(fix))
+            continue;
+        const candidate = fix;
+        if (candidate.fix_id !== taskId)
+            continue;
+        if (candidate.source !== "code_review" && candidate.source !== "self_test")
+            continue;
+        if (typeof candidate.parent_task_id !== "string" && candidate.parent_task_id !== null)
+            continue;
+        if (typeof candidate.reason !== "string")
+            continue;
+        return candidate;
+    }
+    // 兼容发布前已写入 tasks.md、但 transition payload 尚未保存修复描述符的记录。
+    const legacy = /^REVIEW-FIX-(.+)#([^#]+)$/.exec(taskId);
+    return legacy
+        ? {
+            fix_id: taskId,
+            source: "code_review",
+            parent_task_id: null,
+            reason: "历史代码审查修复任务",
+            review_finding: { job_id: legacy[1], finding_id: legacy[2] },
+        }
+        : null;
+}
 function isFreshOpenCodeReviewerJob(job, projectRoot, currentWorkingPaths) {
     return codeReviewJobStaleReason(projectRoot, job, currentWorkingPaths) == null;
 }
@@ -356,6 +485,17 @@ function evaluateApplyDoneCodeReviewGate(input) {
             };
         }
         if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
+            const staleReason = codeReviewJobStaleReason(input.projectRoot, latest.job, currentWorkingPaths);
+            if (staleReason) {
+                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: `代码审查结论已不再匹配当前代码状态，重新创建代码审查工作项；${staleReason}；${scanReason}`,
+                };
+            }
             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);
@@ -400,9 +540,14 @@ function evaluateApplyDoneCodeReviewGate(input) {
 }
 function createFinalVerifierJob(change, projectRoot, changeRoot, events, currentEvidenceDigest) {
     const boundFiles = reviewBoundFiles(changeRoot);
+    const codeReviewGate = latestCodeReviewGateEvidence(events);
     const packetContext = {
         code_state_check: computeCodeStateCheck(projectRoot, events),
+        coverage_exemption_refs: effectiveCoverageExemptionRefsFromEvents(events),
+        task_execution_index: taskExecutionIndexForReview(projectRoot, events),
+        ...(codeReviewGate ? { code_review_gate: codeReviewGate } : {}),
     };
+    const previousRejection = latestReviewHistoryForGateRole(events, REVIEW_FINAL_VERIFIER_GATE, "verifier");
     return {
         job_id: newJobId(change, "verifier"),
         role: "verifier",
@@ -418,9 +563,11 @@ function createFinalVerifierJob(change, projectRoot, changeRoot, events, current
             review_evidence_digest: currentEvidenceDigest,
             packet_context: packetContext,
             created_from_transition: "review-ready",
+            ...(previousRejection ? { previous_rejection: previousRejection } : {}),
         })),
         created_from_transition: "review-ready",
         created_at: new Date().toISOString(),
+        ...(previousRejection ? { previous_rejection: previousRejection } : {}),
     };
 }
 function evaluateFinalVerifierGate(input) {
@@ -502,7 +649,7 @@ function transitionPlanToDecision(snapshot, changeRoot, change, plan, events) {
         case "blocked":
             return { blocked: true, reason: plan.reason, jobs: plan.jobs, ...(plan.details ? { details: plan.details } : {}) };
         case "create_gate_jobs":
-            return createReviewJobsForGate(snapshot.state, plan.gate, plan.roles, changeRoot, change, plan.reason, events);
+            return createReviewJobsForGate(snapshot.state, plan.gate, plan.roles, plan.requiredRoles, changeRoot, change, plan.reason, events);
         case "advance":
             return {
                 fromState: plan.fromState,
@@ -695,11 +842,15 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
             // 统一出口：adopted.contract 非 null 当且仅当契约模式下有绑定块；
             // legacy 轮即使 task 带执行依据文本也输出 null，避免"看似契约、实按 legacy 校验"的误导态
             const adopted = adoptedContractForTask(tasksContent, taskId, contractMode);
-            const reviewFix = isReviewFixTaskId(taskId);
-            if (contractMode && executionRequirementVersion === 2 && !reviewFix && !adopted.parsed) {
+            const fix = fixDescriptorForTask(events, taskId);
+            const isFixTask = isFixTaskId(taskId);
+            if (isFixTask && !fix) {
+                return { skip: true, message: `Fix task ${taskId} 缺少状态机创建记录，不能直接手工追加` };
+            }
+            if (contractMode && executionRequirementVersion === 2 && !isFixTask && !adopted.parsed) {
                 return { skip: true, message: `执行依据模式下，任务 ${taskId} 缺少执行依据` };
             }
-            if (contractMode && executionRequirementVersion === 2 && !reviewFix && adopted.parsed) {
+            if (contractMode && executionRequirementVersion === 2 && !isFixTask && adopted.parsed) {
                 const contractError = validateTaskStartContract(changeRoot, taskId, adopted.parsed);
                 if (contractError)
                     return { skip: true, message: contractError };
@@ -711,17 +862,19 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
             }
             const structureDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
             const effectivePolicy = executionPolicy;
-            const requiredEvidence = contractMode && executionRequirementVersion === 2
-                ? compileRequiredEvidence(effectivePolicy, adopted.contract?.tests ?? [], reviewFix)
+            const requiredEvidence = isFixTask || (contractMode && executionRequirementVersion === 2)
+                ? compileRequiredEvidence(effectivePolicy, adopted.contract?.tests ?? [], isFixTask)
                 : null;
             const attempt = {
                 attempt_id: `ATT-${taskId}-${Date.now()}-${++attemptSeq}`,
                 task_id: taskId, state: "active",
                 task_structure_digest: structureDigest,
+                ...(fix ? { fix } : {}),
                 contract_mode: contractMode,
                 contract: adopted.contract,
                 ...(requiredEvidence ? { required_evidence: requiredEvidence } : {
-                    // 历史模式以及 v1 契约轮继续使用 task 行标记回放；v2 只消费快照。
+                    // 非 Fix 的历史模式以及 v1 契约轮继续使用 task 行标记回放；新建 Fix
+                    // 无论来自哪个版本，均只消费本轮冻结的有效证据要求。
                     tdd_required: taskInfo.tddRequired,
                     no_tdd_reason: taskInfo.noTddReason,
                 }),
@@ -736,6 +889,9 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
                 ...attempt,
                 ...boundarySnapshotPayload(projectRoot),
             };
+            const evidenceActions = requiredEvidence
+                ? evidenceActionsForAttempt(change, attempt.attempt_id, requiredEvidence)
+                : null;
             return {
                 fromState: "apply", toState: "apply", outcome: "advanced",
                 reason: `创建任务 ${taskId} 执行尝试`,
@@ -745,8 +901,10 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
                     task_id: taskId,
                     execution_policy: effectivePolicy,
                     contract: adopted.contract,
+                    ...(fix ? { fix } : {}),
                     ...(requiredEvidence ? { required_evidence: requiredEvidence } : {}),
-                    // legacy 轮统一标注历史模式（无论有无执行依据文本）；契约轮无块时标 false（如 REVIEW-FIX）
+                    ...(evidenceActions ? { evidence_actions: evidenceActions } : {}),
+                    // legacy 轮统一标注历史模式（无论有无执行依据文本）；契约轮无块时标 false（如 Fix task）
                     ...(adopted.contract ? {} : { legacy_contract: !contractMode }),
                 },
             };
@@ -792,11 +950,20 @@ function canReopenToPropose(from) {
 }
 export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
     return commitTransition(projectRoot, change, changeRoot, {
-        name: "reopen", idempotencyInputs: { to, reason, reviewFix: opts.reviewFix ?? "", reviewFinding: opts.reviewFinding ?? "" },
+        name: "reopen", idempotencyInputs: {
+            to,
+            reason,
+            reviewFix: opts.reviewFix ?? "",
+            reviewFinding: opts.reviewFinding ?? "",
+            selfTestFix: opts.selfTestFix ?? "",
+        },
         decide: (snapshot) => {
             if (!reason || reason.trim() === "")
                 return { skip: true, message: "reopen 需要非空 --reason" };
             const events = readEvents(projectRoot, change);
+            const specialFixCount = [opts.reviewFix, opts.reviewFinding, opts.selfTestFix].filter(Boolean).length;
+            if (specialFixCount > 1)
+                return { skip: true, message: "一次 reopen 只能指定一种修复或审查引用" };
             if (opts.reviewFinding) {
                 if (to !== "propose")
                     return { skip: true, message: "--review-finding 只能用于回到计划阶段（reopen --to propose）" };
@@ -828,6 +995,7 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         baseline_docs: proposalDocsBaseline(changeRoot),
                         planning_validation_version: 2,
                         planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
+                        ...proposeAnswerRegistrationPayloadForChange(changeRoot),
                     },
                 };
             }
@@ -852,6 +1020,7 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                 else if (type !== "implementation") {
                     return { skip: true, message: "这个代码审查问题不能直接回到实现阶段处理" };
                 }
+                const fix = reviewFixDescriptor(ref, found.finding);
                 return {
                     fromState: "apply_done",
                     toState: "apply",
@@ -861,9 +1030,56 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         review_fix_of: `${ref.jobId}#${ref.findingId}`,
                         source_job_id: ref.jobId,
                         finding_id: ref.findingId,
+                        fix,
+                    },
+                    postCommit: (_pr, _ch, cr) => {
+                        appendFixTask(cr, fix);
                     },
+                };
+            }
+            if (opts.selfTestFix) {
+                if (to !== "apply")
+                    return { skip: true, message: "--self-test-fix 只能用于回到实现阶段（reopen --to apply）" };
+                const allowedStates = ["apply", "apply_done", "review", "accepted"];
+                if (!allowedStates.includes(snapshot.state)) {
+                    return { skip: true, message: `当前状态 ${snapshot.state}，不能通过自测问题回到实现阶段` };
+                }
+                const parentTaskId = opts.selfTestFix.trim();
+                const parentTask = parseTasksMd(readFileSync(join(changeRoot, "tasks.md"), "utf8"))
+                    .find(task => task.taskId === parentTaskId);
+                if (!parentTask)
+                    return { skip: true, message: `自测修复关联的 task ${parentTaskId} 不存在` };
+                const nextFix = nextSelfTestFixDescriptor(changeRoot, events, parentTaskId, reason);
+                if ("activeFixTaskId" in nextFix) {
+                    return { skip: true, message: `同一自测问题的修复 ${nextFix.activeFixTaskId} 尚未完成，不能重复创建` };
+                }
+                const fix = nextFix.fix;
+                const pendingStatus = pendingTaskStatusForApply(changeRoot, events);
+                if (pendingStatus.pending.length > 0 || snapshot.active_task_attempts.some(attempt => attempt.state === "active")) {
+                    return { skip: true, message: "自测修复只允许在当前 task 全部完成且没有活跃执行尝试后创建" };
+                }
+                if (pendingStatus.mode === "contract" && !pendingStatus.completedByEvent.includes(parentTaskId)) {
+                    return { skip: true, message: `自测修复关联的 task ${parentTaskId} 缺少完成事件，不能只依赖 checkbox` };
+                }
+                if (pendingStatus.mode === "legacy" && !parentTask.done) {
+                    return { skip: true, message: `自测修复关联的 task ${parentTaskId} 尚未完成` };
+                }
+                const failedReview = latestCodeReviewFailedStatus(events);
+                if (failedReview?.unresolved.length) {
+                    return {
+                        skip: true,
+                        message: `已有未处理的代码审查问题 ${failedReview.unresolved[0].id}；请先按 next 返回的 --review-fix 处理`,
+                    };
+                }
+                return {
+                    fromState: snapshot.state,
+                    toState: "apply",
+                    outcome: "advanced",
+                    reason: reason.trim(),
+                    commitPayload: { fix },
+                    extraEvents: invalidateOpenJobs(snapshot, "apply", reason.trim()),
                     postCommit: (_pr, _ch, cr) => {
-                        appendReviewFixTask(cr, ref, found.finding);
+                        appendFixTask(cr, fix);
                     },
                 };
             }
@@ -880,6 +1096,7 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         reopen_target: "explore",
                         reopen_source: snapshot.state,
                         baseline_docs: discoveryDocsBaseline(changeRoot),
+                        ...exploreAnswerRegistrationPayloadForChange(changeRoot),
                     },
                     extraEvents: planningReopenExtraEvents(snapshot, "explore", reason.trim()),
                 };

package/dist/types.d.ts

@@ -50,6 +50,21 @@ export interface EffectiveEvidencePlan {
     green_required: boolean;
     accepted_green_statuses: Array<"expected_success" | "characterization_pass">;
 }
+/**
+ * 状态机创建的实现修复工作项。它只纠正已批准 task 的实现，不产生新的计划需求。
+ * 旧事件没有该字段时按历史行为回放。
+ */
+export type FixSource = "code_review" | "self_test";
+export interface FixDescriptor {
+    fix_id: string;
+    source: FixSource;
+    parent_task_id: string | null;
+    reason: string;
+    review_finding?: {
+        job_id: string;
+        finding_id: string;
+    };
+}
 export interface DirtyFileFingerprint {
     path: string;
     status: "added" | "modified" | "deleted";
@@ -78,9 +93,19 @@ export interface CodeStateCheck {
     changed_paths: string[];
     scope_reason: string;
 }
+/** 最终验证读取的最新代码审查门禁事实。 */
+export interface CodeReviewGateEvidence {
+    decision: "passed" | "skipped";
+    job_id: string | null;
+    packet_digest: string | null;
+    reason?: "no_code_changes";
+    event_id: string;
+    event_digest: string;
+}
 export interface TaskExecutionIndexEntry {
     task_id: string;
     attempt_id: string;
+    fix?: FixDescriptor | null;
     execution_policy: ExecutionPolicy;
     changed_paths: string[] | null;
     changed_paths_partial_reason?: string;
@@ -99,6 +124,7 @@ export interface CoverageExemptionRef {
 }
 export interface JobPacketContext {
     code_review_scope?: CodeReviewScope;
+    code_review_gate?: CodeReviewGateEvidence;
     coverage_exemption_refs?: CoverageExemptionRef[];
     task_execution_index?: TaskExecutionIndexEntry[];
     unattributed_paths?: string[];
@@ -117,6 +143,7 @@ export interface JobPacket {
     previous_rejection?: ReviewPreviousRejection;
     packet_context?: JobPacketContext;
     code_review_scope?: CodeReviewScope;
+    code_review_gate?: CodeReviewGateEvidence;
     coverage_exemption_refs?: CoverageExemptionRef[];
     task_execution_index?: TaskExecutionIndexEntry[];
     unattributed_paths?: string[];
@@ -141,7 +168,7 @@ export interface RequiredJobAction {
     packet_command: string;
     packet_argv: string[];
 }
-export type EventType = "transition_prepare" | "transition_commit" | "job_requested" | "job_invalidated" | "reopen" | "abandon" | "task_started" | "task_completed" | "task_abandoned" | "job_accepted" | "job_rejected" | "user_decision_recorded" | "test_run_recorded" | "task_activation_recorded" | "artifact_recorded";
+export type EventType = "transition_prepare" | "transition_commit" | "job_requested" | "job_invalidated" | "reopen" | "abandon" | "task_started" | "task_completed" | "task_abandoned" | "job_accepted" | "job_rejected" | "user_question_presented" | "user_decision_recorded" | "test_run_recorded" | "task_activation_recorded" | "artifact_recorded";
 export interface Event {
     event_id: string;
     event_type: EventType;
@@ -165,6 +192,9 @@ export type OpenSpecValidationProfile = {
 export interface PlanningValidationProfile {
     version: 2;
     openspec: OpenSpecValidationProfile;
+    design?: {
+        schema_version: 1;
+    };
 }
 export interface TransitionCommitPayload {
     transition: string;
@@ -227,6 +257,7 @@ export interface TaskAttempt {
     task_id: string;
     state: AttemptState;
     task_structure_digest: string;
+    fix?: FixDescriptor | null;
     contract?: ExecutionContract | null;
     contract_mode?: boolean;
     /** task-start 编译出的有效执行要求；缺失表示历史 attempt，按旧字段回放。 */
@@ -290,6 +321,14 @@ export interface AskUser {
     allowed_answers: string[];
     scope: string;
     actions?: AskUserAction[];
+    /** 自由文本问题的直接登记入口；固定选项继续使用 actions。 */
+    record_argv?: string[];
+    record_input?: {
+        scope: string;
+        question: string;
+        answer: null;
+    };
+    required_fields?: Array<"answer">;
 }
 export interface AcceptedMaterialFollowupContinuation {
     kind: "accepted_material_followup";
@@ -303,6 +342,33 @@ export interface AcceptedMaterialFollowupContinuation {
     };
     plan_docs_changed_since_accept: boolean | null;
 }
+export type WorkflowArtifactKind = "discovery" | "test_contract";
+export interface RequiredWorkflowArtifact {
+    kind: WorkflowArtifactKind;
+    /** Repository-relative canonical path owned by the workflow engine. */
+    path: string;
+    operation: "create_or_update";
+}
+export interface ArtifactRequiredResume {
+    argv: string[];
+}
+export interface MaterialUpdateRequiredResume {
+    argv: string[];
+}
+export interface TestEvidenceAction {
+    kind: "test_run";
+    test_id?: string;
+    record_argv: string[];
+    record_input: {
+        test_id?: string;
+        attempt_id: string;
+        command: null;
+        cwd: null;
+        exit_code: null;
+        semantic_status: "expected_failure" | "expected_success" | "characterization_pass";
+    };
+    required_fields: Array<"command" | "cwd" | "exit_code">;
+}
 export type NextOutput = {
     state: State;
 } & ({
@@ -314,6 +380,16 @@ export type NextOutput = {
     path: "required_job";
     required_jobs: RequiredJobAction[];
     reason: string;
+} | {
+    path: "artifact_required";
+    artifact: RequiredWorkflowArtifact;
+    resume: ArtifactRequiredResume;
+    reason: string;
+} | {
+    path: "material_update_required";
+    errors: string[];
+    resume: MaterialUpdateRequiredResume;
+    reason: string;
 } | {
     path: "ask_user";
     ask_user: AskUser;

package/dist/workflow_profile.js

@@ -6,7 +6,7 @@ const CURRENT_GATE_ROLES_BY_RISK = {
         "review.final_verifier": ["verifier"],
     },
     normal: {
-        "explore.discovery_review": [],
+        "explore.discovery_review": ["critic"],
         "propose.final_review": ["critic"],
         "review.code_review": ["code-reviewer"],
         "review.final_verifier": ["verifier"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": {
@@ -24,6 +24,12 @@
     "build": "node build.js",
     "typecheck": "tsc --noEmit",
     "test": "node --test tests/*.ts",
+    "eval:probe": "node evals/probe.mjs",
+    "eval:dynamic": "node evals/probe.mjs --scenario evals/scenarios/probe-dynamic-accepted.json",
+    "eval:m2": "node evals/m2.mjs",
+    "eval:m2:validate": "node evals/m2.mjs --validate-faults",
+    "eval:arena": "node evals/arena.mjs",
+    "eval:delegation": "node evals/delegation-probe.mjs",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build"
   },