@peterxiaoyang/superspec 0.1.36 → 0.1.38

package/dist/cli.js

@@ -66,6 +66,20 @@ function proposeReadyExitCode(result) {
         return 0;
     return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
 }
+function parseReviewRisk(value) {
+    if (value == null)
+        return "strict";
+    if (value === "minimal" || value === "normal" || value === "strict")
+        return value;
+    return null;
+}
+function readReviewRisk(opts) {
+    const risk = parseReviewRisk(opts.risk);
+    if (!risk) {
+        console.error("--risk 只能是 minimal、normal 或 strict");
+    }
+    return risk;
+}
 function parseVersion(version) {
     const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
     if (!match)
@@ -631,7 +645,9 @@ jobs 子命令：
                         return 0;
                     case "explore":
                         {
-                            const risk = opts.risk ?? "strict";
+                            const risk = readReviewRisk(opts);
+                            if (!risk)
+                                return 1;
                             console.log(JSON.stringify(transitionExplore(projectRoot, change, cr, risk), null, 2));
                         }
                         return 0;
@@ -647,13 +663,17 @@ jobs 子命令：
                         return 0;
                     }
                     case "next": {
-                        const risk = opts.risk ?? "strict";
+                        const risk = readReviewRisk(opts);
+                        if (!risk)
+                            return 1;
                         const result = nextCmd(projectRoot, change, cr, risk);
                         console.log(JSON.stringify(result, null, 2));
                         return 0;
                     }
                     case "propose-ready": {
-                        const risk = opts.risk ?? "strict";
+                        const risk = readReviewRisk(opts);
+                        if (!risk)
+                            return 1;
                         const result = proposeReady(projectRoot, change, cr, risk);
                         console.log(JSON.stringify(result, null, 2));
                         return proposeReadyExitCode(result);
@@ -702,7 +722,9 @@ jobs 子命令：
                         return transitionExitCode(result);
                     }
                     case "review-ready": {
-                        const risk = opts.risk ?? "strict";
+                        const risk = readReviewRisk(opts);
+                        if (!risk)
+                            return 1;
                         const result = reviewReady(projectRoot, change, cr, risk);
                         console.log(JSON.stringify(result, null, 2));
                         return transitionExitCode(result);

package/dist/code_review.d.ts

@@ -48,6 +48,7 @@ export declare function codeReviewBoundFiles(projectRoot: string, paths: string[
 export declare function codeReviewJobStaleReason(projectRoot: string, job: Job, currentPaths?: string[]): string | null;
 export declare function codeReviewPacketDigest(input: {
     role: "code-reviewer";
+    gate_id?: "review.code_review";
     boundFiles: Ref[];
     checkedDocs: string[];
     created_from_transition: string;

package/dist/code_review.js

@@ -3,6 +3,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, extname } from "node:path";
 import { findLatestEvent, sha256File, sha256Text } from "./store.js";
+import { REVIEW_CODE_REVIEW_GATE } from "./review_job_gates.js";
 export const CODE_REVIEW_REPAIR_SCOPE_PREFIX = "code_reviewer_report_repair:";
 export const CODE_REVIEW_DECISION_SCOPE_PREFIX = "code_review_decision:";
 export const CODE_REVIEW_DECISION_ANSWER_LABELS = {
@@ -132,7 +133,7 @@ export function codeReviewPacketDigest(input) {
     return sha256Text(JSON.stringify(input));
 }
 function isCodeReviewerJob(job) {
-    return job.role === "code-reviewer" && job.created_from_transition === "review-ready";
+    return job.role === "code-reviewer" && REVIEW_CODE_REVIEW_GATE.isJobForGate(job);
 }
 function codeReviewResultKind(value) {
     return value === "invalid_report" || value === "non_actionable_report" || value === "review_failed"

package/dist/job_validity.d.ts

@@ -0,0 +1,15 @@
+import type { Event, Job } from "./types.ts";
+export interface SubmittedReportValidityContext {
+    projectRoot: string;
+    changeRoot: string;
+    events: Event[];
+    reportPath?: string | null;
+    ignoredCodePaths?: string[];
+}
+export declare function invalidReasonForSnapshot(input: {
+    job: Job;
+    projectRoot: string;
+    changeRoot: string;
+    currentReviewEvidenceDigest: string;
+}): string | null;
+export declare function invalidReasonForSubmittedReport(job: Job, context: SubmittedReportValidityContext): string | null;

package/dist/job_validity.js

@@ -0,0 +1,34 @@
+import { reviewEvidenceDigest, reviewVerifierStaleReason, } from "./review.js";
+import { codeReviewJobStaleReason, scanCodeChanges, } from "./code_review.js";
+const MISSING_REVIEW_EVIDENCE_REASON = "最终验证工作项缺少执行证据版本";
+function reviewReadyVerifierWithoutEvidenceReason(job) {
+    if (job.role === "verifier" &&
+        job.created_from_transition === "review-ready" &&
+        !job.gate_id &&
+        (typeof job.review_evidence_digest !== "string" || job.review_evidence_digest.length === 0)) {
+        return MISSING_REVIEW_EVIDENCE_REASON;
+    }
+    return null;
+}
+export function invalidReasonForSnapshot(input) {
+    if (input.job.role === "code-reviewer") {
+        return codeReviewJobStaleReason(input.projectRoot, input.job);
+    }
+    const invalidReviewReadyVerifier = reviewReadyVerifierWithoutEvidenceReason(input.job);
+    if (invalidReviewReadyVerifier)
+        return invalidReviewReadyVerifier;
+    return reviewVerifierStaleReason(input.job, input.changeRoot, input.currentReviewEvidenceDigest);
+}
+export function invalidReasonForSubmittedReport(job, context) {
+    if (job.role === "code-reviewer") {
+        const ignored = new Set(context.ignoredCodePaths ?? []);
+        if (context.reportPath)
+            ignored.add(context.reportPath);
+        const currentPaths = scanCodeChanges(context.projectRoot).paths.filter(path => !ignored.has(path));
+        return codeReviewJobStaleReason(context.projectRoot, job, currentPaths);
+    }
+    const invalidReviewReadyVerifier = reviewReadyVerifierWithoutEvidenceReason(job);
+    if (invalidReviewReadyVerifier)
+        return invalidReviewReadyVerifier;
+    return reviewVerifierStaleReason(job, context.changeRoot, reviewEvidenceDigest(context.events));
+}

package/dist/next.js

@@ -2,18 +2,13 @@
 import { rebuildSnapshot } from "./sync.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { readEvents, sha256Text } from "./store.js";
+import { readEvents } from "./store.js";
 import { isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewEvidenceDigest } from "./review.js";
 import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, codeReviewDecisionScope, collectCodeReviewGateFacts, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, } from "./code_review.js";
 import { requiredJobActions } from "./job_action.js";
-import { validateDiscovery, countDiscoveryOpenQuestions, collectProposeOpenQuestions, parseTasksMd, pendingTasksInContent } from "./format.js";
-const ACTIVE_PROPOSAL_REVIEW_ROLES = new Set(["critic", "architect", "test-engineer"]);
-function isActiveProposalReviewJob(job) {
-    return job.created_from_transition === "propose-ready" && ACTIVE_PROPOSAL_REVIEW_ROLES.has(job.role);
-}
-function isExploreReviewJob(job) {
-    return job.created_from_transition === "explore" && job.role === "critic";
-}
+import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
+import { taskEvidenceReadiness } from "./task_evidence.js";
+import { validateDiscovery, countDiscoveryOpenQuestions, collectProposeOpenQuestions, pendingTasksInContent } from "./format.js";
 function requiredJobsOutput(state, change, jobs, reason) {
     return {
         state,
@@ -35,43 +30,6 @@ function pendingTaskIds(changeRoot) {
 function reopenCommand(change, pending) {
     return transitionCommand(change, "reopen", `--to apply --reason "pending tasks: ${pending.join(", ")}"`);
 }
-function taskCompletionReadiness(projectRoot, change, changeRoot, attempt) {
-    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
-    const tasks = parseTasksMd(tasksContent);
-    const taskInfo = tasks.find(task => task.taskId === attempt.task_id);
-    const missing = [];
-    if (!taskInfo)
-        return { ready: false, missing: [`任务 ${attempt.task_id} 不存在`] };
-    const currentDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
-    // Keep the wording aligned with task-complete; no command should be suggested if it would fail this guard.
-    if (currentDigest !== attempt.task_structure_digest)
-        missing.push("任务结构指纹");
-    if (!taskInfo.tddRequired) {
-        if (!taskInfo.noTddReason)
-            missing.push("no_tdd_reason");
-        return { ready: missing.length === 0, missing };
-    }
-    let hasRed = false;
-    let hasGreen = false;
-    for (const ev of readEvents(projectRoot, change)) {
-        if (ev.event_type !== "test_run_recorded")
-            continue;
-        const tr = ev.payload;
-        const matches = tr.attempt_id === attempt.attempt_id ||
-            (!tr.attempt_id && tr.task_structure_digest === attempt.task_structure_digest);
-        if (!matches)
-            continue;
-        if (tr.semantic_status === "expected_failure" || tr.semantic_status === "characterization_pass")
-            hasRed = true;
-        if (tr.semantic_status === "expected_success")
-            hasGreen = true;
-    }
-    if (!hasRed)
-        missing.push("RED 证据");
-    if (!hasGreen)
-        missing.push("GREEN 证据");
-    return { ready: missing.length === 0, missing };
-}
 /** next 命令：读 snapshot，返回唯一可执行路径 */
 export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
     const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
@@ -88,7 +46,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                 missing_inputs: [],
             };
         case "explore": {
-            const exploreReviewJobs = snapshot.open_jobs.filter(isExploreReviewJob);
+            const exploreReviewJobs = EXPLORE_DISCOVERY_REVIEW_GATE.openJobsForGate(snapshot);
             if (exploreReviewJobs.length > 0) {
                 return requiredJobsOutput("explore", change, exploreReviewJobs, `有 ${exploreReviewJobs.length} 个待完成探索审查工作项`);
             }
@@ -132,7 +90,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                 };
                 return { state: "propose", path: "ask_user", ask_user: ask, reason: `有 ${openQuestions.openCount} 个 propose 未确认问题` };
             }
-            const proposalReviewJobs = snapshot.open_jobs.filter(isActiveProposalReviewJob);
+            const proposalReviewJobs = PROPOSE_FINAL_REVIEW_GATE.openJobsForGate(snapshot);
             if (proposalReviewJobs.length > 0) {
                 return requiredJobsOutput("propose", change, proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
             }
@@ -145,7 +103,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
             };
         }
         case "propose_ready": {
-            const proposalReviewJobs = snapshot.open_jobs.filter(isActiveProposalReviewJob);
+            const proposalReviewJobs = PROPOSE_FINAL_REVIEW_GATE.openJobsForGate(snapshot);
             if (proposalReviewJobs.length > 0) {
                 return requiredJobsOutput("propose_ready", change, proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
             }
@@ -166,7 +124,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
             if (pending.length > 0) {
                 const activePending = snapshot.active_task_attempts.find(attempt => attempt.state === "active" && pending.includes(attempt.task_id));
                 if (activePending) {
-                    const readiness = taskCompletionReadiness(projectRoot, change, changeRoot, activePending);
+                    const readiness = taskEvidenceReadiness(projectRoot, change, changeRoot, activePending);
                     if (readiness.ready) {
                         return {
                             state: "apply",

package/dist/record.d.ts

@@ -1,4 +1,4 @@
-import type { RecordResult, Job } from "./types.ts";
+import type { RecordResult, Job, JobPacket } from "./types.ts";
 /** record job-submit：登记工作项结果 */
 export declare function recordJobSubmit(projectRoot: string, change: string, changeRoot: string, jobId: string, reportFile: string): RecordResult;
 /** record job-submit：从 JSON 内容登记工作项结果 */
@@ -19,6 +19,6 @@ export declare function jobsList(projectRoot: string, change: string): {
 /** jobs packet：返回工作项执行说明 */
 export declare function jobsPacket(projectRoot: string, change: string, jobId: string): {
     found: boolean;
-    packet?: Record<string, unknown>;
+    packet?: JobPacket;
     message: string;
 };

package/dist/record.js

@@ -2,8 +2,8 @@
 import { readFileSync, existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, sha256Text, withLock, appendRawRecord, } from "./store.js";
-import { reviewEvidenceDigest, reviewVerifierStaleReason } from "./review.js";
-import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewDecisionAnswerLabel, codeReviewJobStaleReason, normalizeCodeReviewDecisionAnswer, scanCodeChanges, } from "./code_review.js";
+import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewDecisionAnswerLabel, normalizeCodeReviewDecisionAnswer, } from "./code_review.js";
+import { invalidReasonForSubmittedReport } from "./job_validity.js";
 import { jobSubmitArgv } from "./job_action.js";
 const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
 const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
@@ -220,22 +220,6 @@ function projectRelativePath(projectRoot, path) {
         return null;
     return rel;
 }
-function staleBoundFilesChecks(job, projectRoot, changeRoot, ignoredCodePaths = []) {
-    const checks = [];
-    if (job.role === "code-reviewer") {
-        const ignored = new Set(ignoredCodePaths);
-        const currentPaths = scanCodeChanges(projectRoot).paths.filter(path => !ignored.has(path));
-        const reason = codeReviewJobStaleReason(projectRoot, job, currentPaths);
-        return reason ? [reason] : [];
-    }
-    for (const bf of job.boundFiles) {
-        const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
-        if (currentSha !== bf.sha) {
-            checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
-        }
-    }
-    return checks;
-}
 /** 从 events 中查找 job（H4 修复：job 只在 transition_commit 的 new_jobs payload 里） */
 function findJob(events, jobId) {
     for (const ev of events) {
@@ -312,12 +296,14 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         checks.push("报告必须是有效 JSON");
     }
     const reportPath = reportFile ? projectRelativePath(projectRoot, reportFile) : null;
-    checks.push(...staleBoundFilesChecks(job, projectRoot, changeRoot, reportPath ? [reportPath] : []));
-    const reviewStaleReason = job.role === "code-reviewer"
-        ? null
-        : reviewVerifierStaleReason(job, changeRoot, reviewEvidenceDigest(events));
-    if (reviewStaleReason && !checks.includes(reviewStaleReason)) {
-        checks.push(reviewStaleReason);
+    const invalidReason = invalidReasonForSubmittedReport(job, {
+        projectRoot,
+        changeRoot,
+        events,
+        reportPath,
+    });
+    if (invalidReason) {
+        checks.push(invalidReason);
     }
     if (!reportContent.trim()) {
         checks.push("报告内容为空");
@@ -633,6 +619,7 @@ export function jobsPacket(projectRoot, change, jobId) {
         packet: {
             job_id: job.job_id,
             role: job.role,
+            ...(job.gate_id ? { gate_id: job.gate_id } : {}),
             recommended_agent: recommendedAgentForRole(job.role),
             boundFiles: job.boundFiles,
             ...(job.review_evidence_digest ? { review_evidence_digest: job.review_evidence_digest } : {}),

package/dist/review.js

@@ -2,6 +2,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { sha256File, sha256Text } from "./store.js";
+import { REVIEW_FINAL_VERIFIER_GATE } from "./review_job_gates.js";
 export const REVIEW_DOC_PATHS = [
     "proposal.md",
     "tasks.md",
@@ -52,7 +53,7 @@ export function readReviewPolicyFromEvents(events) {
     return null;
 }
 export function isReviewReadyVerifier(job) {
-    return job.role === "verifier" && job.created_from_transition === "review-ready";
+    return job.role === "verifier" && REVIEW_FINAL_VERIFIER_GATE.isJobForGate(job);
 }
 export function reviewBoundFiles(changeRoot) {
     return REVIEW_DOC_PATHS

package/dist/review_job_gates.d.ts

@@ -0,0 +1,20 @@
+import type { ReviewRisk } from "./review.ts";
+import type { Job, JobRole, ReviewJobGateId, Snapshot } from "./types.ts";
+export interface ReviewGateRule {
+    gate_id: ReviewJobGateId;
+    created_from_transition: "explore" | "propose-ready" | "review-ready";
+    allowedRoles: JobRole[];
+    reviewedDocPaths: string[];
+    requiredRolesForRisk(risk: ReviewRisk): JobRole[];
+    matchesOldJob(job: Job): boolean;
+    isJobForGate(job: Job): boolean;
+    openJobsForGate(snapshot: Snapshot): Job[];
+}
+export declare const EXPLORE_DISCOVERY_REVIEW_GATE_ID: "explore.discovery_review";
+export declare const PROPOSE_FINAL_REVIEW_GATE_ID: "propose.final_review";
+export declare const REVIEW_CODE_REVIEW_GATE_ID: "review.code_review";
+export declare const REVIEW_FINAL_VERIFIER_GATE_ID: "review.final_verifier";
+export declare const EXPLORE_DISCOVERY_REVIEW_GATE: ReviewGateRule;
+export declare const PROPOSE_FINAL_REVIEW_GATE: ReviewGateRule;
+export declare const REVIEW_CODE_REVIEW_GATE: ReviewGateRule;
+export declare const REVIEW_FINAL_VERIFIER_GATE: ReviewGateRule;

package/dist/review_job_gates.js

@@ -0,0 +1,84 @@
+import { reviewRolesForGate } from "./workflow_profile.js";
+function makeReviewGateRule(input) {
+    const gate = {
+        ...input,
+        isJobForGate(job) {
+            if (!input.allowedRoles.includes(job.role))
+                return false;
+            if (job.gate_id)
+                return job.gate_id === input.gate_id;
+            return input.matchesOldJob(job);
+        },
+        openJobsForGate(snapshot) {
+            return snapshot.open_jobs.filter(job => gate.isJobForGate(job));
+        },
+    };
+    return gate;
+}
+export const EXPLORE_DISCOVERY_REVIEW_GATE_ID = "explore.discovery_review";
+export const PROPOSE_FINAL_REVIEW_GATE_ID = "propose.final_review";
+export const REVIEW_CODE_REVIEW_GATE_ID = "review.code_review";
+export const REVIEW_FINAL_VERIFIER_GATE_ID = "review.final_verifier";
+const EXPLORE_DISCOVERY_REVIEW_ROLES = ["critic"];
+const PROPOSAL_REVIEW_ROLES = ["critic", "architect", "test-engineer"];
+const PROPOSAL_REVIEW_ROLE_SET = new Set(PROPOSAL_REVIEW_ROLES);
+const REVIEW_CODE_REVIEW_ROLES = ["code-reviewer"];
+const REVIEW_FINAL_VERIFIER_ROLES = ["verifier"];
+export const EXPLORE_DISCOVERY_REVIEW_GATE = makeReviewGateRule({
+    gate_id: EXPLORE_DISCOVERY_REVIEW_GATE_ID,
+    created_from_transition: "explore",
+    allowedRoles: EXPLORE_DISCOVERY_REVIEW_ROLES,
+    reviewedDocPaths: [".superspec/artifacts/discovery.md"],
+    requiredRolesForRisk(risk) {
+        return reviewRolesForGate(EXPLORE_DISCOVERY_REVIEW_GATE_ID, risk);
+    },
+    matchesOldJob(job) {
+        return job.created_from_transition === "explore" && job.role === "critic";
+    },
+});
+export const PROPOSE_FINAL_REVIEW_GATE = makeReviewGateRule({
+    gate_id: PROPOSE_FINAL_REVIEW_GATE_ID,
+    created_from_transition: "propose-ready",
+    allowedRoles: PROPOSAL_REVIEW_ROLES,
+    reviewedDocPaths: [
+        "proposal.md",
+        "tasks.md",
+        "design.md",
+        ".superspec/artifacts/discovery.md",
+        ".superspec/artifacts/business-invariants.md",
+        ".superspec/artifacts/test-contract.md",
+    ],
+    requiredRolesForRisk(risk) {
+        return reviewRolesForGate(PROPOSE_FINAL_REVIEW_GATE_ID, risk);
+    },
+    matchesOldJob(job) {
+        return job.created_from_transition === "propose-ready" && PROPOSAL_REVIEW_ROLE_SET.has(job.role);
+    },
+});
+export const REVIEW_CODE_REVIEW_GATE = makeReviewGateRule({
+    gate_id: REVIEW_CODE_REVIEW_GATE_ID,
+    created_from_transition: "review-ready",
+    allowedRoles: REVIEW_CODE_REVIEW_ROLES,
+    reviewedDocPaths: [],
+    requiredRolesForRisk(risk) {
+        return reviewRolesForGate(REVIEW_CODE_REVIEW_GATE_ID, risk);
+    },
+    matchesOldJob(job) {
+        return job.created_from_transition === "review-ready" && job.role === "code-reviewer";
+    },
+});
+export const REVIEW_FINAL_VERIFIER_GATE = makeReviewGateRule({
+    gate_id: REVIEW_FINAL_VERIFIER_GATE_ID,
+    created_from_transition: "review-ready",
+    allowedRoles: REVIEW_FINAL_VERIFIER_ROLES,
+    reviewedDocPaths: [],
+    requiredRolesForRisk(risk) {
+        return reviewRolesForGate(REVIEW_FINAL_VERIFIER_GATE_ID, risk);
+    },
+    matchesOldJob(job) {
+        return job.created_from_transition === "review-ready" &&
+            job.role === "verifier" &&
+            typeof job.review_evidence_digest === "string" &&
+            job.review_evidence_digest.length > 0;
+    },
+});

package/dist/sync.js

@@ -2,8 +2,8 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { readEvents, eventsDigest, computeDocumentDigests, sha256Text, ensureChangeLayout, } from "./store.js";
-import { reviewEvidenceDigest, reviewVerifierStaleReason } from "./review.js";
-import { codeReviewJobStaleReason } from "./code_review.js";
+import { reviewEvidenceDigest } from "./review.js";
+import { invalidReasonForSnapshot } from "./job_validity.js";
 const TRACKED_DOCS = [
     "proposal.md", "design.md", "tasks.md",
     ".superspec/artifacts/discovery.md",
@@ -84,9 +84,7 @@ function replayEvents(events) {
 function checkStaleJobs(jobs, projectRoot, changeRoot, currentReviewEvidenceDigest) {
     const stale = [];
     for (const job of jobs) {
-        const reason = job.role === "code-reviewer"
-            ? codeReviewJobStaleReason(projectRoot, job)
-            : reviewVerifierStaleReason(job, changeRoot, currentReviewEvidenceDigest);
+        const reason = invalidReasonForSnapshot({ job, projectRoot, changeRoot, currentReviewEvidenceDigest });
         if (reason) {
             stale.push({ job_id: job.job_id, reason });
         }

package/dist/task_evidence.d.ts

@@ -0,0 +1,10 @@
+import type { TaskAttempt } from "./types.ts";
+export type TaskEvidenceReadiness = {
+    ready: true;
+    missing: [];
+} | {
+    ready: false;
+    missing: string[];
+    reason: string;
+};
+export declare function taskEvidenceReadiness(projectRoot: string, change: string, changeRoot: string, attempt: TaskAttempt): TaskEvidenceReadiness;

package/dist/task_evidence.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseTasksMd } from "./format.js";
+import { readEvents, sha256Text } from "./store.js";
+export function taskEvidenceReadiness(projectRoot, change, changeRoot, attempt) {
+    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+    const tasks = parseTasksMd(tasksContent);
+    const taskInfo = tasks.find(task => task.taskId === attempt.task_id);
+    const missing = [];
+    if (!taskInfo) {
+        missing.push(`任务 ${attempt.task_id} 不存在`);
+        return { ready: false, missing, reason: missing.join("、") };
+    }
+    const currentDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
+    if (currentDigest !== attempt.task_structure_digest)
+        missing.push("任务结构指纹");
+    if (!taskInfo.tddRequired) {
+        if (!taskInfo.noTddReason)
+            missing.push("no_tdd_reason");
+        return missing.length === 0
+            ? { ready: true, missing: [] }
+            : { ready: false, missing, reason: missing.join("、") };
+    }
+    let hasRed = false;
+    let hasGreen = false;
+    for (const ev of readEvents(projectRoot, change)) {
+        if (ev.event_type !== "test_run_recorded")
+            continue;
+        const tr = ev.payload;
+        const matches = tr.attempt_id === attempt.attempt_id ||
+            (!tr.attempt_id && tr.task_structure_digest === attempt.task_structure_digest);
+        if (!matches)
+            continue;
+        if (tr.semantic_status === "expected_failure" || tr.semantic_status === "characterization_pass")
+            hasRed = true;
+        if (tr.semantic_status === "expected_success")
+            hasGreen = true;
+    }
+    if (!hasRed)
+        missing.push("RED 证据");
+    if (!hasGreen)
+        missing.push("GREEN 证据");
+    return missing.length === 0
+        ? { ready: true, missing: [] }
+        : { ready: false, missing, reason: missing.join("、") };
+}

package/dist/transition.js

@@ -5,36 +5,26 @@ import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot,
 import { rebuildSnapshot } from "./sync.js";
 import { requiredJobActions } from "./job_action.js";
 import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, REVIEW_DOC_PATHS, } from "./review.js";
+import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE, REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE_ID, } from "./review_job_gates.js";
 import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketDigest, collectCodeReviewGateFacts, dismissedCodeReviewSummary, latestCodeReviewDecision, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, scanCodeChanges, } from "./code_review.js";
-import { validateDiscovery, collectProposeOpenQuestions, findTaskInLines, parseTasksMd, pendingTasksInContent, tasksStructureDigest } from "./format.js";
+import { taskEvidenceReadiness } from "./task_evidence.js";
+import { validateDiscovery, collectProposeOpenQuestions, findTaskInLines, pendingTasksInContent } from "./format.js";
 let transitionSeq = 0;
 function newTransitionId() { return `T-${Date.now()}-${++transitionSeq}`; }
 let jobSeq = 0;
 function newJobId(change, role) { return `JOB-${change.slice(0, 8)}-${role.slice(0, 4)}-${Date.now()}-${++jobSeq}`; }
-const TRANSITION_REQUIREMENTS = {
-    "propose-ready": {
-        minimal: [],
-        normal: ["critic"],
-        strict: ["critic", "architect", "test-engineer"],
-    },
-    "explore": {
-        minimal: [],
-        normal: [],
-        strict: ["critic"],
-    },
-};
 /**
  * 通用 job 检查/创建逻辑——任何 transition 都能调用。
  * 检查 requiredRoles 是否有 fresh accepted job；缺则创建新 job。
  * 返回 null = 全部满足；返回 Decision = 需要创建 job（状态不变）。
  */
-function checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, transitionName, bindDocPaths) {
+function checkOrCreateReviewJobs(snapshot, gate, requiredRoles, changeRoot, change) {
     const staleRoles = [];
     for (const role of requiredRoles) {
-        const openForRole = snapshot.open_jobs.find(j => j.role === role && j.created_from_transition === transitionName);
+        const openForRole = snapshot.open_jobs.find(j => gate.isJobForGate(j) && j.role === role);
         if (openForRole)
             return { blocked: true, reason: `状态未推进；已有待完成工作项 ${role}（${openForRole.job_id}）`, jobs: [openForRole] };
-        const fresh = snapshot.accepted_jobs.find(j => j.role === role && j.created_from_transition === transitionName);
+        const fresh = snapshot.accepted_jobs.find(j => gate.isJobForGate(j) && j.role === role);
         if (!fresh) {
             staleRoles.push({ role, reason: `需求 ${role} 无已接受的工作项` });
         }
@@ -50,8 +40,22 @@ function checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, tr
     }
     if (staleRoles.length > 0) {
         const newJobs = staleRoles.map(({ role }) => {
-            const boundFiles = bindDocPaths.filter(p => existsSync(join(changeRoot, p))).map(p => ({ path: p, sha: sha256File(join(changeRoot, p)) ?? "sha256:missing" }));
-            return { job_id: newJobId(change, role), role, state: "requested", boundFiles, packet_digest: sha256Text(JSON.stringify({ role, boundFiles })), created_from_transition: transitionName, created_at: new Date().toISOString() };
+            const boundFiles = gate.reviewedDocPaths.filter(p => existsSync(join(changeRoot, p))).map(p => ({ path: p, sha: sha256File(join(changeRoot, p)) ?? "sha256:missing" }));
+            return {
+                job_id: newJobId(change, role),
+                role,
+                state: "requested",
+                gate_id: gate.gate_id,
+                boundFiles,
+                packet_digest: sha256Text(JSON.stringify({
+                    role,
+                    gate_id: gate.gate_id,
+                    boundFiles,
+                    created_from_transition: gate.created_from_transition,
+                })),
+                created_from_transition: gate.created_from_transition,
+                created_at: new Date().toISOString(),
+            };
         });
         return {
             fromState: snapshot.state, toState: snapshot.state, outcome: "job_created",
@@ -67,7 +71,7 @@ function historicalProposeReadyRoles(projectRoot, change) {
             continue;
         const newJobs = ev.payload.new_jobs ?? [];
         for (const job of newJobs) {
-            if (job.created_from_transition === "propose-ready" &&
+            if (PROPOSE_FINAL_REVIEW_GATE.isJobForGate(job) &&
                 (job.role === "critic" || job.role === "architect" || job.role === "test-engineer"))
                 roles.add(job.role);
         }
@@ -119,6 +123,7 @@ function createCodeReviewerJob(change, projectRoot, events) {
         : undefined;
     const packetInput = {
         role: "code-reviewer",
+        gate_id: REVIEW_CODE_REVIEW_GATE_ID,
         boundFiles,
         checkedDocs: REVIEW_DOC_PATHS,
         created_from_transition: "review-ready",
@@ -130,6 +135,7 @@ function createCodeReviewerJob(change, projectRoot, events) {
             job_id: newJobId(change, "code-reviewer"),
             role: "code-reviewer",
             state: "requested",
+            gate_id: REVIEW_CODE_REVIEW_GATE_ID,
             boundFiles,
             packet_digest: codeReviewPacketDigest(packetInput),
             created_from_transition: "review-ready",
@@ -176,6 +182,141 @@ function appendReviewFixTask(changeRoot, ref, finding) {
 function isFreshOpenCodeReviewerJob(job, projectRoot) {
     return codeReviewJobStaleReason(projectRoot, job) == null;
 }
+function evaluateApplyDoneCodeReviewGate(input) {
+    const scan = scanCodeChanges(input.projectRoot);
+    const facts = collectCodeReviewGateFacts(input.events);
+    if (scan.hasCodeChanges) {
+        const freshOpenJobs = facts.openJobs.filter(job => isFreshOpenCodeReviewerJob(job, input.projectRoot));
+        if (freshOpenJobs.length > 0) {
+            return {
+                blocked: true,
+                reason: `状态未推进；已有待完成代码审查工作项 ${freshOpenJobs[0].job_id}`,
+                jobs: [freshOpenJobs[0]],
+            };
+        }
+        const latest = facts.latestTerminal;
+        if (latest?.state === "accepted") {
+            return {
+                fromState: "apply_done",
+                toState: "review",
+                outcome: "advanced",
+                reason: "代码审查已通过，进入最终审查阶段",
+                commitPayload: {
+                    ...input.policyPayload,
+                    code_review_gate: { decision: "passed", job_id: latest.job.job_id },
+                },
+            };
+        }
+        if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
+            const reviewFailedStatus = latestCodeReviewFailedStatus(input.events);
+            if (reviewFailedStatus && reviewFailedStatus.findings.length > 0 && reviewFailedStatus.unresolved.length === 0) {
+                const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.events);
+                return {
+                    fromState: "apply_done",
+                    toState: "apply_done",
+                    outcome: "job_created",
+                    newJobs: [job],
+                    reason: `重新创建代码审查工作项；${scanReason}；上一次阻塞问题已被主流程复核驳回`,
+                };
+            }
+            return {
+                skip: true,
+                message: "代码审查发现需要处理的问题，请先执行 next，根据提示回到实现阶段修复或让使用者决定是否回到计划阶段",
+            };
+        }
+        const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.events);
+        return {
+            fromState: "apply_done",
+            toState: "apply_done",
+            outcome: "job_created",
+            newJobs: [job],
+            reason: latest?.state === "rejected"
+                ? `重新创建代码审查工作项；上一次报告未被接受，原因：${latest.reason ?? "报告不符合要求"}`
+                : `创建代码审查工作项；${scanReason}`,
+        };
+    }
+    return {
+        fromState: "apply_done",
+        toState: "review",
+        outcome: "advanced",
+        reason: "没有代码类改动，直接进入最终审查阶段",
+        commitPayload: {
+            ...input.policyPayload,
+            code_review_gate: { decision: "skipped", reason: "no_code_changes" },
+        },
+    };
+}
+function createFinalVerifierJob(change, changeRoot, currentEvidenceDigest) {
+    const boundFiles = reviewBoundFiles(changeRoot);
+    return {
+        job_id: newJobId(change, "verifier"),
+        role: "verifier",
+        state: "requested",
+        gate_id: REVIEW_FINAL_VERIFIER_GATE_ID,
+        boundFiles,
+        review_evidence_digest: currentEvidenceDigest,
+        packet_digest: sha256Text(JSON.stringify({
+            role: "verifier",
+            gate_id: REVIEW_FINAL_VERIFIER_GATE_ID,
+            boundFiles,
+            review_evidence_digest: currentEvidenceDigest,
+            created_from_transition: "review-ready",
+        })),
+        created_from_transition: "review-ready",
+        created_at: new Date().toISOString(),
+    };
+}
+function evaluateFinalVerifierGate(input) {
+    const verifierOpen = input.snapshot.open_jobs.find(isReviewReadyVerifier);
+    if (verifierOpen) {
+        return {
+            blocked: true,
+            reason: `状态未推进；已有待完成最终验证工作项 ${verifierOpen.job_id}`,
+            jobs: [verifierOpen],
+        };
+    }
+    const verifierAccepted = input.snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, input.changeRoot, input.currentEvidenceDigest));
+    const finalVerifierRequired = requiresFinalVerifierForCurrentReview(input.events) || input.policy.requires_verifier;
+    if (!finalVerifierRequired) {
+        if (!input.hasStoredPolicy) {
+            return {
+                fromState: "review",
+                toState: "review",
+                outcome: "advanced",
+                reason: `补写审查策略=${input.policy.review_risk}`,
+                commitPayload: input.policyPayload,
+            };
+        }
+        return { skip: true, message: "已在 review 状态，审查策略无需 verifier" };
+    }
+    if (!verifierAccepted) {
+        const previousVerifierRejected = hasRejectedReviewReadyVerifier(input.events);
+        const job = createFinalVerifierJob(input.change, input.changeRoot, input.currentEvidenceDigest);
+        return {
+            fromState: input.snapshot.state,
+            toState: input.snapshot.state,
+            outcome: "job_created",
+            newJobs: [job],
+            reason: previousVerifierRejected
+                ? "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项"
+                : "创建最终验证工作项",
+            commitPayload: input.policyPayload,
+            ...(previousVerifierRejected ? {
+                details: { advisory: "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项" },
+            } : {}),
+        };
+    }
+    if (!input.hasStoredPolicy) {
+        return {
+            fromState: "review",
+            toState: "review",
+            outcome: "advanced",
+            reason: `补写审查策略=${input.policy.review_risk}`,
+            commitPayload: input.policyPayload,
+        };
+    }
+    return { skip: true, message: "已在 review 状态，最终验证仍然有效" };
+}
 function documentBaseline(changeRoot) {
     const docs = ["proposal.md", "design.md", "tasks.md", ".superspec/artifacts/test-contract.md"];
     const baseline = {};
@@ -313,8 +454,8 @@ export function proposeReady(projectRoot, change, changeRoot, risk = "strict") {
                 }
             }
             // 通用 job 检查（用提取的 helper）
-            const requiredRoles = TRANSITION_REQUIREMENTS["propose-ready"]?.[risk] ?? [];
-            const reviewResult = checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, "propose-ready", ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"]);
+            const requiredRoles = PROPOSE_FINAL_REVIEW_GATE.requiredRolesForRisk(risk);
+            const reviewResult = checkOrCreateReviewJobs(snapshot, PROPOSE_FINAL_REVIEW_GATE, requiredRoles, changeRoot, change);
             if (reviewResult)
                 return reviewResult;
             return { fromState: "propose", toState: "propose_ready", outcome: "advanced", reason: `risk=${risk}，所有需求已满足` };
@@ -349,8 +490,8 @@ export function transitionExplore(projectRoot, change, changeRoot, risk = "stric
                 if (!discoveryCheck.ok)
                     return { skip: true, message: discoveryCheck.message };
                 // 通用 job 审查（和 propose-ready 同一个 helper）
-                const requiredRoles = TRANSITION_REQUIREMENTS["explore"]?.[risk] ?? [];
-                const reviewResult = checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, "explore", [".superspec/artifacts/discovery.md"]);
+                const requiredRoles = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(risk);
+                const reviewResult = checkOrCreateReviewJobs(snapshot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles, changeRoot, change);
                 if (reviewResult)
                     return reviewResult;
                 return { fromState: "explore", toState: "propose", outcome: "advanced", reason: "探索完成" };
@@ -373,7 +514,7 @@ export function startApply(projectRoot, change, changeRoot) {
             }
             const reviewedRoles = historicalProposeReadyRoles(projectRoot, change);
             if (reviewedRoles.length > 0) {
-                const reviewResult = checkOrCreateReviewJobs(snapshot, reviewedRoles, changeRoot, change, "propose-ready", ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"]);
+                const reviewResult = checkOrCreateReviewJobs(snapshot, PROPOSE_FINAL_REVIEW_GATE, reviewedRoles, changeRoot, change);
                 if (reviewResult) {
                     return {
                         ...reviewResult,
@@ -538,111 +679,24 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
                 };
             }
             if (snapshot.state === "apply_done") {
-                const scan = scanCodeChanges(projectRoot);
-                const facts = collectCodeReviewGateFacts(events);
-                if (scan.hasCodeChanges) {
-                    const freshOpenJobs = facts.openJobs.filter(job => isFreshOpenCodeReviewerJob(job, projectRoot));
-                    if (freshOpenJobs.length > 0) {
-                        return {
-                            blocked: true,
-                            reason: `状态未推进；已有待完成代码审查工作项 ${freshOpenJobs[0].job_id}`,
-                            jobs: [freshOpenJobs[0]],
-                        };
-                    }
-                    const latest = facts.latestTerminal;
-                    if (latest?.state === "accepted") {
-                        return {
-                            fromState: "apply_done", toState: "review", outcome: "advanced",
-                            reason: "代码审查已通过，进入最终审查阶段",
-                            commitPayload: {
-                                ...policyPayload,
-                                code_review_gate: { decision: "passed", job_id: latest.job.job_id },
-                            },
-                        };
-                    }
-                    if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
-                        const reviewFailedStatus = latestCodeReviewFailedStatus(events);
-                        if (reviewFailedStatus && reviewFailedStatus.findings.length > 0 && reviewFailedStatus.unresolved.length === 0) {
-                            const { job, scanReason } = createCodeReviewerJob(change, projectRoot, events);
-                            return {
-                                fromState: "apply_done", toState: "apply_done", outcome: "job_created",
-                                newJobs: [job],
-                                reason: `重新创建代码审查工作项；${scanReason}；上一次阻塞问题已被主流程复核驳回`,
-                            };
-                        }
-                        return {
-                            skip: true,
-                            message: "代码审查发现需要处理的问题，请先执行 next，根据提示回到实现阶段修复或让使用者决定是否回到计划阶段",
-                        };
-                    }
-                    const { job, scanReason } = createCodeReviewerJob(change, projectRoot, events);
-                    return {
-                        fromState: "apply_done", toState: "apply_done", outcome: "job_created",
-                        newJobs: [job],
-                        reason: latest?.state === "rejected"
-                            ? `重新创建代码审查工作项；上一次报告未被接受，原因：${latest.reason ?? "报告不符合要求"}`
-                            : `创建代码审查工作项；${scanReason}`,
-                    };
-                }
-                return {
-                    fromState: "apply_done", toState: "review", outcome: "advanced",
-                    reason: "没有代码类改动，直接进入最终审查阶段",
-                    commitPayload: {
-                        ...policyPayload,
-                        code_review_gate: { decision: "skipped", reason: "no_code_changes" },
-                    },
-                };
+                return evaluateApplyDoneCodeReviewGate({
+                    events,
+                    projectRoot,
+                    change,
+                    policyPayload,
+                });
             }
             if (snapshot.state === "review") {
-                const verifierOpen = snapshot.open_jobs.find(isReviewReadyVerifier);
-                if (verifierOpen)
-                    return { blocked: true, reason: `状态未推进；已有待完成最终验证工作项 ${verifierOpen.job_id}`, jobs: [verifierOpen] };
-                const verifierAccepted = snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest));
-                const finalVerifierRequired = requiresFinalVerifierForCurrentReview(events) || policy.requires_verifier;
-                if (!finalVerifierRequired) {
-                    if (!storedPolicy) {
-                        return {
-                            fromState: "review", toState: "review", outcome: "advanced",
-                            reason: `补写审查策略=${policy.review_risk}`,
-                            commitPayload: policyPayload,
-                        };
-                    }
-                    return { skip: true, message: "已在 review 状态，审查策略无需 verifier" };
-                }
-                if (!verifierAccepted) {
-                    const boundFiles = reviewBoundFiles(changeRoot);
-                    const previousVerifierRejected = hasRejectedReviewReadyVerifier(events);
-                    const job = {
-                        job_id: newJobId(change, "verifier"), role: "verifier", state: "requested",
-                        boundFiles, review_evidence_digest: currentEvidenceDigest,
-                        packet_digest: sha256Text(JSON.stringify({
-                            role: "verifier",
-                            boundFiles,
-                            review_evidence_digest: currentEvidenceDigest,
-                            created_from_transition: "review-ready",
-                        })),
-                        created_from_transition: "review-ready", created_at: new Date().toISOString(),
-                    };
-                    return {
-                        fromState: snapshot.state, toState: snapshot.state, outcome: "job_created",
-                        newJobs: [job],
-                        reason: previousVerifierRejected
-                            ? "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项"
-                            : "创建最终验证工作项",
-                        commitPayload: policyPayload,
-                        ...(previousVerifierRejected ? {
-                            details: { advisory: "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项" },
-                        } : {}),
-                    };
-                }
-                if (!storedPolicy) {
-                    return {
-                        fromState: "review", toState: "review", outcome: "advanced",
-                        reason: `补写审查策略=${policy.review_risk}`,
-                        commitPayload: policyPayload,
-                    };
-                }
-                return { skip: true, message: "已在 review 状态，最终验证仍然有效" };
+                return evaluateFinalVerifierGate({
+                    snapshot,
+                    events,
+                    change,
+                    changeRoot,
+                    currentEvidenceDigest,
+                    policy,
+                    policyPayload,
+                    hasStoredPolicy: Boolean(storedPolicy),
+                });
             }
             return { skip: true, message: `当前状态 ${snapshot.state}，review-ready 不适用` };
         },
@@ -711,42 +765,9 @@ export function taskComplete(projectRoot, change, changeRoot, taskId) {
             const attempt = snapshot.active_task_attempts?.find(a => a.task_id === taskId && a.state === "active");
             if (!attempt)
                 return { skip: true, message: `任务 ${taskId} 无活跃执行尝试` };
-            const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
-            const currentDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
-            if (currentDigest !== attempt.task_structure_digest)
-                return { skip: true, message: "任务结构指纹不匹配" };
-            // 解析任务属性（委托给 format.ts 的 parseTasksMd）
-            const tasks = parseTasksMd(tasksContent);
-            const taskInfo = tasks.find(t => t.taskId === taskId);
-            const isTdd = taskInfo?.tddRequired ?? true;
-            const hasNoTddReason = taskInfo?.noTddReason != null;
-            // RED/GREEN 检查（HIGH-2 修复：按 attempt_id 匹配，避免多任务 digest 碰撞）
-            const events = readEvents(projectRoot, change);
-            let hasRed = false, hasGreen = false;
-            for (const ev of events) {
-                if (ev.event_type === "test_run_recorded") {
-                    const tr = ev.payload;
-                    // 匹配当前 attempt（优先按 attempt_id，回退到 digest）
-                    const matches = tr.attempt_id === attempt.attempt_id ||
-                        (!tr.attempt_id && tr.task_structure_digest === attempt.task_structure_digest);
-                    if (matches) {
-                        if (tr.semantic_status === "expected_failure" || tr.semantic_status === "characterization_pass")
-                            hasRed = true;
-                        if (tr.semantic_status === "expected_success")
-                            hasGreen = true;
-                    }
-                }
-            }
-            if (isTdd) {
-                if (!hasRed)
-                    return { skip: true, message: `TDD 任务 ${taskId} 缺少 RED 证据` };
-                if (!hasGreen)
-                    return { skip: true, message: `TDD 任务 ${taskId} 缺少 GREEN 证据` };
-            }
-            else {
-                if (!hasNoTddReason)
-                    return { skip: true, message: `非 TDD 任务 ${taskId} 缺少 no_tdd_reason` };
-            }
+            const readiness = taskEvidenceReadiness(projectRoot, change, changeRoot, attempt);
+            if (!readiness.ready)
+                return { skip: true, message: `任务 ${taskId} 无法完成：${readiness.reason}` };
             // B1 修复：checkbox 写入移到 postCommit（commit 事件写入后执行）
             return {
                 fromState: "apply", toState: "apply", outcome: "advanced",

package/dist/types.d.ts

@@ -6,6 +6,7 @@ export type Ref = {
 };
 export type JobState = "requested" | "accepted" | "rejected";
 export type JobRole = "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "verifier" | "code-reviewer";
+export type ReviewJobGateId = "explore.discovery_review" | "propose.final_review" | "review.code_review" | "review.final_verifier";
 export type CodeReviewResultKind = "invalid_report" | "non_actionable_report" | "review_failed";
 export interface CodeReviewPreviousRejection {
     result_kind: CodeReviewResultKind;
@@ -16,6 +17,7 @@ export interface Job {
     job_id: string;
     role: JobRole;
     state: JobState;
+    gate_id?: ReviewJobGateId;
     boundFiles: Ref[];
     review_evidence_digest?: string;
     packet_digest: string;
@@ -26,9 +28,11 @@ export interface Job {
 export interface JobPacket {
     job_id: string;
     role: JobRole;
+    gate_id?: ReviewJobGateId;
     recommended_agent?: string;
     boundFiles: Ref[];
     review_evidence_digest?: string;
+    previous_rejection?: CodeReviewPreviousRejection;
     packet_digest: string;
     required_output_kind: string;
     preferred_input_mode?: "stdin" | "file";

package/dist/workflow_profile.d.ts

@@ -0,0 +1,11 @@
+import type { ReviewRisk } from "./review.ts";
+import type { JobRole, ReviewJobGateId } from "./types.ts";
+export type WorkflowProfile = "light" | "normal" | "strict";
+export interface WorkflowProfileResolution {
+    profile: WorkflowProfile;
+    risk: ReviewRisk;
+    reviewRolesByGate: Partial<Record<ReviewJobGateId, JobRole[]>>;
+}
+export declare function workflowProfileForRisk(risk: ReviewRisk): WorkflowProfile;
+export declare function resolveWorkflowProfile(risk: ReviewRisk): WorkflowProfileResolution;
+export declare function reviewRolesForGate(gateId: ReviewJobGateId, risk: ReviewRisk): JobRole[];

package/dist/workflow_profile.js

@@ -0,0 +1,39 @@
+const CURRENT_GATE_ROLES_BY_RISK = {
+    minimal: {
+        "explore.discovery_review": [],
+        "propose.final_review": [],
+        "review.code_review": ["code-reviewer"],
+        "review.final_verifier": ["verifier"],
+    },
+    normal: {
+        "explore.discovery_review": [],
+        "propose.final_review": ["critic"],
+        "review.code_review": ["code-reviewer"],
+        "review.final_verifier": ["verifier"],
+    },
+    strict: {
+        "explore.discovery_review": ["critic"],
+        "propose.final_review": ["critic", "architect", "test-engineer"],
+        "review.code_review": ["code-reviewer"],
+        "review.final_verifier": ["verifier"],
+    },
+};
+export function workflowProfileForRisk(risk) {
+    if (risk === "minimal")
+        return "light";
+    if (risk === "normal")
+        return "normal";
+    return "strict";
+}
+export function resolveWorkflowProfile(risk) {
+    const profile = workflowProfileForRisk(risk);
+    const rolesByGate = CURRENT_GATE_ROLES_BY_RISK[risk];
+    const reviewRolesByGate = {};
+    for (const [gateId, roles] of Object.entries(rolesByGate)) {
+        reviewRolesByGate[gateId] = [...roles];
+    }
+    return { profile, risk, reviewRolesByGate };
+}
+export function reviewRolesForGate(gateId, risk) {
+    return resolveWorkflowProfile(risk).reviewRolesByGate[gateId] ?? [];
+}

package/package.json

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

package/templates/workflow/AGENTS.md

@@ -1,7 +1,7 @@
 <!-- SUPERSPEC:AGENTS:START -->
 本项目启用 SuperSpec。使用 `superspec-*` 工作流时，以 `superspec transition next --change "<change>"` 返回的下一步为准；流程完成前不得跳阶段、不得自称完成。
 
-即使用户没有显式调用 `superspec-*`，如果新输入像是在改变业务规则、产品口径、验收标准、示例规范或影响范围，编辑代码前先提醒并做只读确认：这是实现偏差，还是需要先回 `superspec-propose` 更新计划文档；不要直接把这类自然语言当作 apply 授权。
+即使用户没有显式调用 `superspec-*`，如果新输入像是在改变业务规则、产品口径、验收标准、示例规范、影响范围，或说明 PRD/文档/原型等需求源已更新，编辑代码前先提醒并做只读确认：这是实现偏差，还是需要先回 `superspec-propose` 更新计划文档；不要直接把这类自然语言当作 apply 授权。
 
 当用户显式调用 `$superspec-explore` 工作流时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `$superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
 

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

@@ -36,6 +36,7 @@ argument-hint: "本次代码审查说明"
 - 是否存在明显性能、兼容性或维护风险。
 - 是否缺少当前任务要求的关键测试或回归验证。
 - 是否引入和当前任务目标无关的代码改动。
+- 如果工作项、用户输入或引用材料显示需求源已更新，但 proposal/design/tasks/test-contract 没有体现最新口径或 `## 需求变化` 处理，不要把旧计划当成最新依据；按方案或需求问题归因。
 
 可以阻塞流程的问题：
 

package/templates/workflow/prompts/explore.md

@@ -21,6 +21,7 @@ argument-hint: "本次探索说明"
 ## 本次任务说明
 
 如果主流程提供本次任务说明，先读取其中指向的 refs。以本次任务说明中的目标范围、来源 refs、必读 refs、artifact refs 和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+如果本次任务说明表示 PRD、文档、原型或其它需求源已更新，但只提供旧 artifact 或旧 refs，不要把旧内容当作最新事实；在输出中标记需要主流程重新核对需求源，并说明可能影响范围、验收或用户可见行为的点。
 
 ## 深扫输出要求
 
@@ -28,7 +29,9 @@ argument-hint: "本次探索说明"
 
 输出至少区分：
 
-- 已确认事实
+- 已确认事实（有源码/文档锚点、命令输出或用户确认直接支撑）
+- 基于锚点的推断（写明依据）
+- 未知/证据缺口（说明是否阻塞；影响范围、验收、用户可见行为、数据或安全相关未知交给主流程确认）
 - 影响范围候选
 - 风险和隐性约束
 - 需要主流程确认的问题

package/templates/workflow/prompts/verifier.md

@@ -34,6 +34,7 @@ argument-hint: "本次验证说明"
 - 代码审查提出的阻塞问题是否都有合法闭环；审查修复是否有自身验证和必要的回归验证，回归 test-run 优先用 `covers_task_ids` 说明覆盖了哪些已完成任务。
 - 已完成任务、测试记录、审查记录和提交给 verifier 的证据，是否能对应到 proposal、design、tasks、test-contract 的目标。
 - 计划材料是否被绕过工作流改写；合法自动勾选和代码审查追加的修复项以工作项说明和事件记录为准。
+- 工作项、用户输入或引用材料显示需求源已更新时，最终证据必须能对应已处理该变化的最新计划材料；仍引用旧计划且无 `## 需求变化` 处理时，按证据不足失败。
 - RED/GREEN 证据是否同一次任务尝试闭环；退出码、环境错误或构建错误不能单独作为行为证明。
 - 输入数据来源核查是否闭环；不得只用 GREEN 测试或 task 勾选证明输入完整性。
 

package/templates/workflow/skills/superspec-apply/SKILL.md

@@ -27,10 +27,10 @@ metadata:
 
 每个 task 的标准循环：
 
-1. **设计核对**：执行 `task-start` 前，确认本任务符合 `design.md` 的实现方向。缺少方向时先停止，不写 RED。
+1. **计划核对**：执行 `task-start` 前，确认当前 task 是 `tasks.md` 顶格任务，并能对应 `design.md` 的实现方向和 `proposal.md` 的 `## Impact` 受影响原因。缺少映射、需要新增能力/验收/影响范围时先停止，交回 propose，不写 RED。
 2. **任务开始**：`superspec transition task-start --change "<change>" --task <task_id>`。
 3. **读取 attempt_id**：从 task-start 返回结果或当前活跃 task attempt 中读取。
-4. **RED**：写测试，运行后确认失败，并用 `superspec record test-run --change "<change>" --input -` 登记。
+4. **RED**：写测试前确认测试意图能对应 `test-contract.md` 的 `test_id` 或 `business-invariants.md`；缺少对应关系时先停止，交回 propose。运行后确认失败，并用 `superspec record test-run --change "<change>" --input -` 登记。
 5. **实现**：根据任务写代码，保持范围小。`design.md` 不锁死字段名、函数名、SQL 或局部写法。
 6. **GREEN**：运行测试确认通过，并登记 test-run。
 7. **完成 task**：`superspec transition task-complete --change "<change>" --task <task_id>`。
@@ -74,7 +74,7 @@ no-TDD 任务（`tdd_required:false` + `no_tdd_reason`）跳过 RED/GREEN，但
 - 需要判断影响范围或改动原因不自明时，参考 `proposal.md` 的 `## Impact`，但不要把它当作路径白名单。
 - 编码时发现未列入影响范围的文件，如果从 diff 或引用链能直接解释为同一任务下的局部引用、测试辅助或机械连带改动，可以继续。
 - 如果发现新增能力、用户可见行为、明显新增影响范围或原因不自明，停止扩大实现并报告给主流程；不要在 apply 阶段补改 `proposal.md`。
-- 用户在 apply 期间或 apply 后补充最新业务规则、产品口径、验收标准、示例规范、兼容策略或影响范围时，停止实现并交回主流程使用 `superspec-propose` 更新计划文档。
+- 用户在 apply 期间或 apply 后补充最新业务规则、产品口径、验收标准、示例规范、兼容策略、影响范围，或说明需求源已更新时，停止实现并交回主流程使用 `superspec-propose` 更新计划文档；交回时说明变化来源、变化内容、影响范围和建议处理方式。
 - 不修改 `proposal.md`、`design.md`、`specs/**` 或 `.superspec/**`。
 - active attempt 期间不要修改 `tasks.md` 中除 `task-complete` 自动勾选目标 checkbox 外的内容。
 - 不跳过 RED 直接写 GREEN。

package/templates/workflow/skills/superspec-explore/SKILL.md

@@ -21,7 +21,7 @@ metadata:
 
 如果下一步提示当前阶段还有用户确认、审查或验证事项，先完成这些事项。完成前不要进入下一阶段，也不要修改业务代码；就绪或审查后只概括关键事实、真实待确认项和下一步。
 
-如果下一步说明 discovery 不完整或有未确认问题，先检查并填写 discovery 草稿，不要把草稿占位、格式缺口或路径空白直接转问用户；只有影响范围、验收标准、用户可见行为、数据来源或安全边界存在真实阻塞时才向用户提问，收到回答后优先用 `superspec record user-decision --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback。
+如果下一步说明 discovery 不完整或有未确认问题，先检查并填写 discovery 草稿，不要把草稿占位、格式缺口或路径空白直接转问用户；用户明确说 PRD、文档、原型或其它需求源已更新时，先重新核对来源，不要复用旧依据；只有影响范围、验收标准、用户可见行为、数据来源或安全边界存在真实阻塞时才向用户提问，收到回答后优先用 `superspec record user-decision --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback。
 
 本技能默认走完整审查路径。探索完成后，`explore → propose` 会先创建 `critic` 工作项，由 Critic 角色审查需求澄清记录。审查完成后优先通过 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 登记 JSON 报告内容；文件路径模式仍可作为 fallback。
 
@@ -81,6 +81,7 @@ metadata:
 只有 `## 待确认问题` 段落内的 `- [ ]` 表示阻塞确认项。其他段落列事实、风险或影响范围时使用普通 bullet，不要用 checklist。
 
 代码影响型需求的 `当前代码事实`、`影响范围候选`、`风险和边界` 应尽量包含 `path:line` 锚点。纯文档、配置或新文件任务没有代码锚点时，写明 `N/A` 理由并引用相关文档、配置或需求来源。
+有源码/文档锚点、命令输出或用户确认直接支撑的内容，才写成事实；只有间接锚点支撑的，写为推断并说明依据；没有支撑的，写为未知并说明是否阻塞。影响范围、验收、用户可见行为、数据来源或安全边界的未知必须进入待确认问题，或说明非阻塞理由。
 
 ### 输入数据来源核查
 

package/templates/workflow/skills/superspec-propose/SKILL.md

@@ -144,6 +144,8 @@ superspec record user-decision --change "<change>" --input -
 
 然后把用户决定反映到 proposal/design/test-contract，并将对应确认项改为 `[x]` 或移出未确认列表。局部实现细节、命名、普通文件组织和不影响需求/验收/风险的技术微调不要升级为用户确认。
 
+进入 propose 后出现新的业务规则、产品口径、验收标准、示例规范或需求源更新时，不要静默覆盖原计划；默认先在 `proposal.md` 记录 `## 需求变化`，说明变化来源、变化内容、影响范围和处理方式（更新当前 change / 新建后续 change / 暂不处理）。只有影响技术路线、测试契约或业务不变量时，才同步更新 `design.md`、`test-contract.md` 或 `business-invariants.md`。
+
 ## 完成条件
 
 tasks.md 作为计划文档就绪（不是复选框全完成）+ 基础职责文档齐全 → next 返回 propose-ready 命令。