@peterxiaoyang/superspec 0.1.45 → 0.1.47

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, 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, 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";
@@ -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 {
@@ -279,26 +279,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 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 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 reviewFixTaskId(ref) {
-    return `REVIEW-FIX-${ref.jobId}#${ref.findingId}`;
+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 appendReviewFixTask(changeRoot, ref, finding) {
+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 +463,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 +518,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 +541,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) {
@@ -695,11 +820,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 +840,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,
                 }),
@@ -745,8 +876,9 @@ 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）
+                    // legacy 轮统一标注历史模式（无论有无执行依据文本）；契约轮无块时标 false（如 Fix task）
                     ...(adopted.contract ? {} : { legacy_contract: !contractMode }),
                 },
             };
@@ -792,11 +924,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）" };
@@ -826,6 +967,8 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         finding_id: ref.findingId,
                         decision_scope: scope,
                         baseline_docs: proposalDocsBaseline(changeRoot),
+                        planning_validation_version: 2,
+                        planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
                     },
                 };
             }
@@ -850,6 +993,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",
@@ -859,9 +1003,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);
                     },
                 };
             }
@@ -878,6 +1069,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()),
                 };
@@ -915,6 +1107,8 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         reopen_source: snapshot.state,
                         baseline_source: acceptedBaseline ? (baselineNeedsBackfill ? "accepted_backfill" : "accepted") : "reopen_fallback",
                         baseline_docs: baselineDocs,
+                        planning_validation_version: 2,
+                        planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
                     },
                     extraEvents: planningReopenExtraEvents(snapshot, "propose", 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[];
@@ -156,6 +183,16 @@ export interface Event {
     payload: Record<string, unknown>;
     event_digest: string;
 }
+export type OpenSpecValidationProfile = {
+    mode: "disabled";
+} | {
+    mode: "strict";
+    config_digest: string;
+};
+export interface PlanningValidationProfile {
+    version: 2;
+    openspec: OpenSpecValidationProfile;
+}
 export interface TransitionCommitPayload {
     transition: string;
     from_state: State;
@@ -190,6 +227,10 @@ export interface TransitionCommitPayload {
     workflow_mode?: "minimal" | "normal" | "strict";
     /** v2 起所有普通任务必须有五字段执行依据；缺失表示旧 change，沿用旧规则回放。 */
     execution_requirement_version?: 2;
+    /** 新 planning round 的格式协议版本；缺失表示升级前的 v1 change。 */
+    planning_validation_version?: 2;
+    /** propose-ready 成功时冻结的 OpenSpec 校验 profile，start-apply 只回放此快照。 */
+    planning_validation_profile?: PlanningValidationProfile;
     execution_policy?: ExecutionPolicy;
 }
 export interface Snapshot {
@@ -213,6 +254,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，按旧字段回放。 */

package/package.json

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

package/templates/workflow/AGENTS.md

@@ -1,15 +1,25 @@
 <!-- SUPERSPEC:AGENTS:START -->
-本项目启用 SuperSpec。使用 `superspec-*` 工作流时，以 `superspec transition next --change "<change>"` 返回的下一步为准；流程完成前不得跳阶段、不得自称完成。
+只有当用户显式调用 `superspec-*`，或明确要求继续处理某个已有 SuperSpec change 时，才进入或续转 SuperSpec 工作流。普通开发、修复、排查、测试或审查请求，即使项目已安装 SuperSpec，也不得自行启动工作流、创建 change、执行 `transition next`，或切换到某个 `superspec-*` 阶段。
 
-即使用户没有显式调用 `superspec-*`，如果新输入像是在改变业务规则、产品口径、验收标准、示例规范、影响范围，或说明 PRD/文档/原型等需求源已更新，编辑代码前先提醒并做只读确认：这是实现偏差，还是需要先回 `superspec-propose` 更新计划文档；不要直接把这类自然语言当作 apply 授权。
+一旦用户已显式启动工作流或明确指定 change，使用 `superspec-*` 工作流时一律以 `superspec transition next --change "<change>"` 返回的下一步推进；主流程执行内部命令，不要求用户手动运行工作流命令。流程完成前不得跳阶段、不得自称完成。
 
-用户补充 SuperSpec 相关内容时，先确定对应 change，再按 next 返回处理；无法确定时只询问归属，不执行流转。同一 change 的方案、需求、验收或实现约束补充，按影响回到该 change 的 `propose`，不要另建 repair change；内部命令由主流程完成，不交给用户。
+每完成 `next` 返回的当前事项（材料更新、用户答复回写、实现、验证、审查或修复时），立即再次运行 `superspec transition next --change "<change>"` 并继续处理。完成单个事项不等于完成整个 change；只有工作流明确需要用户决定、当前独立工作项尚未返回结果、遇到真实阻塞或整个 change 已完成时才暂停。
 
-当用户显式调用 `$superspec-explore` 工作流时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `$superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
+当用户显式调用 `$superspec-explore`，或明确要求继续处于 Explore 的已有 change 时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `$superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
+
+Explore 中需要用户决定业务、验收、范围或关键取舍时，先简要说明当前理解、影响和建议，再一次只请用户决定一件事；收到明确答复后，更新相关 discovery 结论，再继续工作流。其他阶段要求用户确认、选择处理方向或补齐材料时，按当前工作流返回的要求登记结论或更新相应材料；不得把这类答复默认写入 discovery。
+
+当前 change 的自测、联调或用户指出的问题若仍能由既有 task 的批准行为、边界和验收解释，就在同一 change 内处理：
+
+- 当前 task 尚未完成时，在其范围内直接修复；不要为同一实现问题新增 task 或回 propose。
+- 所有 task 已完成后，若问题仍能关联一个已完成 task、且不改变已批准行为和方案，主流程执行 `superspec transition reopen --change "<change>" --to apply --self-test-fix "<task>" --reason "<reason>"`，让工作流创建修复事项；随后继续 `next`，不得手改 tasks。
+- 无法关联既有 task，或需要改变行为、验收、接口、数据语义或实现路线时，才回 propose。
+
+在用户已显式启动工作流或明确指定 change 后，若新增或改变业务规则、产品口径、验收、示例规范、影响范围，或说明 PRD/文档/原型等需求源已更新时，先确定对应 change；归属明确则回同一 change 的 `propose` 更新计划，归属不明才询问。不要把这类输入直接当作 apply 授权，也不要另建 repair change。
 
 SuperSpec 创建的独立审查/验证工作项，视为已授权启动对应 subagent；无需再次询问用户。主会话不得自批这些工作项。
 
 审查/验证工作项只授权处理该工作项绑定的内容，不得扩大范围、跳过阶段或代替后续流程。若当前环境无法启动 subagent，只能使用本地或用户已授权的独立来源；没有可用独立来源时停在当前工作项并说明阻塞，主会话不得因此自批。
 
-执行 CLI 返回命令时优先使用 `*_argv` 字段。用户可见回复使用自然语言；除非用户要求调试信息，不复述内部 JSON 字段。
+主流程代为执行必要的工作流操作；用户可见回复使用自然语言，除非用户要求调试信息，不展示底层命令或数据。
 <!-- SUPERSPEC:AGENTS:END -->

package/templates/workflow/agents/architect.toml

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: architect
 name = "architect"
 description = "System design, boundaries, interfaces, long-horizon tradeoffs"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Architect. Review system boundaries, interface contracts, data flow, maintenance risk, rollback risk, and design tradeoffs.
 

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

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: code-reviewer
 name = "code-reviewer"
 description = "Code-level review for spec fit, bugs, safety, and test gaps"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Code Reviewer. Check spec fit, correctness, security, test adequacy, code quality, performance, and maintainability without making the workflow heavy.
 

package/templates/workflow/agents/critic.toml

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: critic
 name = "critic"
 description = "Plan/design critical challenge and review"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Critic. Challenge demand clarification, plans, designs, implementations, and verification claims with source-backed skepticism.
 

package/templates/workflow/agents/executor.toml

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: executor
 name = "executor"
 description = "Bounded SuperSpec apply implementation worker"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Executor. Implement exactly one SuperSpec apply task from the current task instructions.
 

package/templates/workflow/agents/explore.toml

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: explore
 name = "explore"
 description = "Repo-local read-only factual scan for SuperSpec discovery"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Explore. Map repo-local implementation facts, source anchors, hidden contracts, and missing discovery coverage.
 

package/templates/workflow/agents/test-engineer.toml

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: test-engineer
 name = "test-engineer"
 description = "Test strategy, coverage, flaky-test hardening"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Test Engineer. Review test strategy, coverage, RED/GREEN credibility, flaky-test risk, and acceptance mapping.
 

package/templates/workflow/agents/test-runner.toml

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: test-runner
 name = "test-runner"
 description = "Bounded SuperSpec apply test execution worker"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Test Runner. Execute exactly one SuperSpec apply test phase from the current task instructions and report an evidence candidate.
 

package/templates/workflow/agents/verifier.toml

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: verifier
 name = "verifier"
 description = "Completion evidence, claim validation, test adequacy"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Verifier. Prove or disprove completion claims with reproducible evidence; missing evidence is not a pass.