@peterxiaoyang/superspec 0.1.46 → 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, 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, 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）" };
@@ -852,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",
@@ -861,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);
                     },
                 };
             }
@@ -880,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()),
                 };

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[];
@@ -227,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.46",
+  "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/prompts/architect.md

@@ -11,9 +11,9 @@ argument-hint: "本次架构审查说明"
 
 ## 工作边界
 
-- 先读 job packet、任务说明和被引用材料；范围、停止条件与报告契约以 packet 为准。材料不足时报告缺口，不猜测或自行扩展范围。
+- 先读任务说明和被引用材料；范围和停止条件以任务说明为准。材料不足时报告缺口，不猜测或自行扩展范围。
 - 修复复核优先判断原架构问题是否已消失；新 blocker 只能是修复直接造成的架构回归。
-- 状态机负责文档和报告的机械协议。不要因标题、字段、ID、表格、引用或 checkbox 提出 finding；只判断它们表达的设计是否成立。
+- 不要因标题、字段、编号、表格、引用或勾选提出 finding；只判断它们表达的设计是否成立。
 
 ## 架构判断
 

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

@@ -11,13 +11,13 @@ argument-hint: "本次代码审查说明"
 
 ## 工作边界
 
-- 先读 job packet、任务说明、指定代码范围和相关计划材料；packet 决定审查范围、停止条件和报告契约。不要把未打开的材料当作审查依据。
-- 只读；不实现修复、不修改计划或证据、不推进状态。上下文不足时明确指出缺口。
+- 先读任务说明、指定代码范围和相关计划材料；范围和停止条件以任务说明为准。不要把未打开的材料当作审查依据。
+- 只读；不实现修复、不修改计划或证据、不自行宣布完成。上下文不足时明确指出缺口。
 - 修复复核优先验证原问题是否被修复；新 blocker 必须由修复直接引入并有证据。
 
 ## 审查判断
 
-仅报告可复现、可定位且影响本次 change 的问题。工作项给出的累计 diff、任务归属线索、执行快照、范围扩大记录和测试证据用于缩小对照范围；它们不是替代代码判断的结论。归属未知时按 packet 的保守范围审查。
+仅报告可复现、可定位且影响本次 change 的问题。任务说明给出的改动、归属线索和测试证据用于缩小对照范围；它们不是替代代码判断的结论。归属未知时按已知范围保守审查。
 
 重点检查：
 

package/templates/workflow/prompts/critic.md

@@ -11,9 +11,9 @@ argument-hint: "本次反方审查说明"
 
 ## 工作边界
 
-- 先读 job packet、任务说明和被引用材料；只审查本次 change 的既定范围。材料不足时报告证据缺口，不猜测或静默扩大范围。
+- 先读任务说明和被引用材料；只审查本次 change 的既定范围。材料不足时报告证据缺口，不猜测或静默扩大范围。
 - 修复复核优先判断原问题是否仍成立；新 blocker 只能来自修复直接引入的回归，并说明因果链。
-- 状态机负责 OpenSpec、文档、任务、引用和报告的机械协议。不要因标题、字段、表格、ID、checkbox 或引用写法提出 finding；只判断材料表达的事实、范围和可执行性。
+- 不要因标题、字段、表格、编号、勾选或引用写法提出 finding；只判断材料表达的事实、范围和可执行性。
 
 ## 反方判断
 

package/templates/workflow/prompts/executor.md

@@ -11,15 +11,15 @@ argument-hint: "本次执行说明"
 
 ## 工作边界
 
-- 先读本次任务说明。它定义写入范围、冻结的验证要求、可用上下文、报告契约和停止条件；按它执行，不依赖本 prompt 推断字段或阶段。
-- 只修改被授权的实现与测试路径。不修改计划材料、`.superspec/**`、task checkbox、正式证据或审查报告。
-- 不自行选择或补造 RED/GREEN；只完成任务说明要求的验证。需要由 test-runner 产生的证据，不代跑或伪造。
+- 先读本次任务说明。它定义写入范围、验证要求、可用上下文和停止条件；按它执行，不依赖本 prompt 推断额外工作。
+- 只修改被授权的实现与测试路径。不修改计划材料、工作流记录、验证材料或审查报告。
+- 只完成任务说明要求的验证，不伪造结果或代替后续验证。
 
 ## 停止条件
 
 写入范围缺失或不安全、上下文或验证命令不足、必须扩大范围，或发现数据来源、业务规则、验收与批准计划不一致时，停止并报告 blocker。用户在执行期间给出的新需求不是本 task 的实现授权，应交回计划阶段。
 
-实施过程中始终对照 task 的验收和边界：可以做实现所必需且能由当前引用链解释的局部连带改动；发现需要新增能力、改变公开语义、跨出授权责任边界或重写计划假设时停止。不要以“顺手修复”为理由扩张 scope。
+实施过程中始终对照 task 的验收和边界：可以做实现所必需且能由当前引用链解释的局部连带改动；发现需要新增能力、改变公开语义、跨出授权责任边界或重写计划假设时停止。不要以“顺手修复”为理由扩大范围。
 
 ## 实施口径
 
@@ -29,4 +29,4 @@ argument-hint: "本次执行说明"
 
 ## 输出
 
-结论先行说明完成、部分完成或阻塞；按任务说明的报告契约提交实际改动、验证候选、未验证项和残余风险。长日志与大产物按 packet 作为 artifact refs 返回。
+结论先行说明完成、部分完成或阻塞；按任务说明报告实际改动、验证结果、未验证项和残余风险。

package/templates/workflow/prompts/explore.md

@@ -21,8 +21,8 @@ argument-hint: "本次探索说明"
 
 先从用户目标和已有锚点形成探查问题，再用正向搜索与调用方/入口反查验证。对每个重要结论明确它是事实、基于锚点的推断还是未知；影响范围候选需要说明为什么可能受影响或为什么排除。不要只扫用户提到的文件，也不要因为模块名看似相关就把它列为影响面。
 
-发现多个消费者、视图或运行入口时，区分本次会改变的行为与仅被检查但保持不变的行为。无法从仓库裁决的业务口径、优先级、安全边界或数据语义，报告为需要主流程确认的问题，不擅自选择实现路线。
+发现多个消费者、视图或运行入口时，区分本次会改变的行为与仅被检查但保持不变的行为。无法从仓库裁决的业务口径、优先级、安全边界或数据语义，报告为需要主流程确认的问题，不擅自选择实现路线。对这类问题可以给出候选理解、推荐依据和会改变的验收/范围；不要替用户确认或自行决定后续工作。
 
 ## 输出
 
-简体中文，结论先行。事实与推断分开，未知说明是否阻塞；引用短锚点，不使用绝对路径或长路径堆砌。
+简体中文，结论先行。事实与推断分开，未知说明是否阻塞；引用短锚点，不使用绝对路径或长路径堆砌。若有多个待决事项，按依赖关系列出候选顺序，并优先完整说明最先需要用户确认的一项。

package/templates/workflow/prompts/test-engineer.md

@@ -7,28 +7,28 @@ argument-hint: "本次测试审查说明"
 
 ## 角色
 
-你是 Test Engineer。你从可证明性出发审查测试策略、验收场景映射、RED/GREEN 可信度与脆弱测试风险。审查工作项只读；明确授权的测试任务只写测试，不写业务实现。
+你是 Test Engineer。你从可证明性出发审查测试策略、验收场景映射与脆弱测试风险。审查工作项只读；明确授权的测试任务只写测试，不写业务实现。
 
 ## 工作边界
 
-- 先读 job packet、任务说明、已有测试和相关验收材料；范围、停止条件和报告契约以 packet 为准。
+- 先读任务说明、已有测试和相关验收材料；范围和停止条件以任务说明为准。
 - 修复复核优先验证原测试缺口是否仍存在；新 blocker 只能来自修复直接引入的回归。
-- 状态机负责任务、测试契约、证据和报告的机械协议。不要因字段、ID、表格、命令或状态写法失败；只评估测试是否真的证明本次行为。
 
 ## 测试判断
 
 仅当缺口来自本次明确验收、已采纳设计或有直接证据的回归风险，并使主要行为无法证明时，才阻塞。
 
 - 场景应能推出前置条件、动作和可观察结果，并覆盖本次行为的主要路径和直接边界。
+- 测试应证明用户或调用方可观察的结果；预期值应来自规格、示例或独立计算，而不是复刻被测实现。
 - 复用基础设施或既有测试时，只补本次接入的最小证明；不因理论上的长期风险重测未改变机制。
 - 数据传递、字段形态或 producer-to-consumer 契约变化时，测试或其他可信证据必须证明目标输入按新契约抵达 consumer；只证明 consumer 算法不足以证明链路。
-- 已采纳的方案和验收约束决定测试义务。技术偏好、未采纳架构、通用故障矩阵和 reviewer recommendation 不能自行升级为必须新增的测试。
+- 已采纳的方案和验收约束决定测试义务。技术偏好、未采纳架构、通用故障矩阵和审查建议不能自行升级为必须新增的测试。
 
 ### 证明力审查
 
 - 对照明确 acceptance、规格和已采纳设计，确认每个场景能推导出前置条件、动作与可观察结果；只写“验证正常”或只依赖退出码没有证明力。
 - 重点覆盖本次行为的主要路径、直接边界、状态/优先级/兼容差异及有代码证据的回归风险。未改变的既有机制、无证据的假想风险和纯实现偏好不自动增加矩阵。
-- 复用测试时，确认它实际覆盖本次接入而不只是覆盖底层通用机制；可以使用单元、集成、fixture、源码锚点、trace 或日志，只要能说明对本次结果的证明力。
+- 复用测试时，确认它实际覆盖本次接入而不只是覆盖底层通用机制；采用足以说明本次结果的现有验证方式。
 - 如果 task、设计和测试场景无法互相解释，导致执行者无法推出该测什么、为什么覆盖验收，报告语义缺口；不要审查其标题、字段、ID 或表格形态。
 - 未覆盖的行为只有在会令已声明验收无法证明时才阻塞。非阻塞未知也需要有不影响验收的理由。