@peterxiaoyang/superspec 0.1.33 → 0.1.35

package/dist/sync.js

@@ -3,6 +3,7 @@ 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";
 const TRACKED_DOCS = [
     "proposal.md", "design.md", "tasks.md",
     ".superspec/artifacts/discovery.md",
@@ -80,10 +81,12 @@ function replayEvents(events) {
     return { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition };
 }
 /** 粗粒度失效：检查 job 的 boundFiles 是否仍匹配当前文档 */
-function checkStaleJobs(jobs, changeRoot, currentReviewEvidenceDigest) {
+function checkStaleJobs(jobs, projectRoot, changeRoot, currentReviewEvidenceDigest) {
     const stale = [];
     for (const job of jobs) {
-        const reason = reviewVerifierStaleReason(job, changeRoot, currentReviewEvidenceDigest);
+        const reason = job.role === "code-reviewer"
+            ? codeReviewJobStaleReason(projectRoot, job)
+            : reviewVerifierStaleReason(job, changeRoot, currentReviewEvidenceDigest);
         if (reason) {
             stale.push({ job_id: job.job_id, reason });
         }
@@ -109,10 +112,13 @@ export function rebuildSnapshot(projectRoot, change, changeRoot, openspecStatusD
     const tsDigest = tasksStructureDigest(changeRoot);
     const { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition } = replayEvents(events);
     const currentReviewEvidenceDigest = reviewEvidenceDigest(events);
-    // 粗粒度失效检查（只读，不写事件）：snapshot 只暴露当前可执行/可复用 job。
-    const staleOpenInfo = checkStaleJobs(openJobs, changeRoot, currentReviewEvidenceDigest);
-    const staleAcceptedInfo = checkStaleJobs(acceptedJobs, changeRoot, currentReviewEvidenceDigest);
-    const freshOpen = openJobs.filter(j => !staleOpenInfo.some(s => s.job_id === j.job_id));
+    // 粗粒度失效检查（只读，不写事件）：open code-reviewer job 防止提交过期报告；
+    // accepted code-reviewer pass 不做持续 freshness gate，避免 apply_done 循环重审。
+    const staleOpenInfo = checkStaleJobs(openJobs, projectRoot, changeRoot, currentReviewEvidenceDigest);
+    const staleAcceptedInfo = checkStaleJobs(acceptedJobs.filter(j => j.role !== "code-reviewer"), projectRoot, changeRoot, currentReviewEvidenceDigest);
+    const freshOpen = openJobs
+        .filter(j => !staleOpenInfo.some(s => s.job_id === j.job_id))
+        .filter(j => j.role !== "code-reviewer" || state === "apply_done");
     const freshAccepted = acceptedJobs.filter(j => !staleAcceptedInfo.some(s => s.job_id === j.job_id));
     return {
         change_id: change,

package/dist/task.js

@@ -22,10 +22,29 @@ function recordTestRunLoaded(projectRoot, change, content) {
     if (!tr.test_id || !tr.task_structure_digest) {
         return { accepted: false, message: "缺少 test_id 或 task_structure_digest" };
     }
+    let coversTaskIds;
+    if (tr.covers_task_ids !== undefined) {
+        if (!Array.isArray(tr.covers_task_ids)) {
+            return { accepted: false, message: "covers_task_ids 必须是字符串数组" };
+        }
+        if (tr.covers_task_ids.length === 0) {
+            return { accepted: false, message: "covers_task_ids 不能是空数组" };
+        }
+        for (const raw of tr.covers_task_ids) {
+            if (typeof raw !== "string")
+                return { accepted: false, message: "covers_task_ids 必须是字符串数组" };
+            const value = raw.trim();
+            if (!value)
+                return { accepted: false, message: "covers_task_ids 不能包含空字符串" };
+            (coversTaskIds ??= []).push(value);
+        }
+        coversTaskIds = [...new Set(coversTaskIds)].sort();
+    }
     const normalizedTestRun = {
         test_id: tr.test_id,
         task_structure_digest: tr.task_structure_digest,
         attempt_id: tr.attempt_id ?? null,
+        ...(coversTaskIds ? { covers_task_ids: coversTaskIds } : {}),
         command: tr.command ?? "",
         cwd: tr.cwd ?? "",
         exit_code: tr.exit_code ?? -1,

package/dist/transition.d.ts

@@ -36,7 +36,10 @@ export declare function transitionInit(projectRoot: string, change: string, chan
 export declare function transitionExplore(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
 export declare function startApply(projectRoot: string, change: string, changeRoot: string): TransitionResult;
 export declare function taskStart(projectRoot: string, change: string, changeRoot: string, taskId: string): TransitionResult;
-export declare function reopen(projectRoot: string, change: string, changeRoot: string, to: State, reason: string): TransitionResult;
+export declare function reopen(projectRoot: string, change: string, changeRoot: string, to: State, reason: string, opts?: {
+    reviewFix?: string;
+    reviewFinding?: string;
+}): TransitionResult;
 export declare function reviewReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
 export declare function accept(projectRoot: string, change: string, changeRoot: string): TransitionResult;
 export declare function archive(projectRoot: string, change: string, changeRoot: string): TransitionResult;

package/dist/transition.js

@@ -4,7 +4,8 @@ import { existsSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot, snapshotDigest, withLock, idempotencyKey, sha256File, sha256Text, } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
 import { requiredJobActions } from "./job_action.js";
-import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, } from "./review.js";
+import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, REVIEW_DOC_PATHS, } from "./review.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";
 let transitionSeq = 0;
 function newTransitionId() { return `T-${Date.now()}-${++transitionSeq}`; }
@@ -101,6 +102,106 @@ function hasRejectedReviewReadyVerifier(events) {
     return events.some(ev => ev.event_type === "job_rejected" &&
         reviewReadyVerifierIds.has(ev.payload.job_id ?? ""));
 }
+function createCodeReviewerJob(change, projectRoot, events) {
+    const scan = scanCodeChanges(projectRoot);
+    const boundFiles = codeReviewBoundFiles(projectRoot, scan.paths);
+    const facts = collectCodeReviewGateFacts(events);
+    const latestRejected = facts.latestRejected;
+    const reviewFailedStatus = latestCodeReviewFailedStatus(events);
+    const previousRejection = latestRejected && latestRejected.state === "rejected"
+        ? {
+            result_kind: latestRejected.result_kind ?? "invalid_report",
+            reason: latestRejected.result_kind === "review_failed" && reviewFailedStatus && reviewFailedStatus.unresolved.length === 0 && reviewFailedStatus.dismissed.length > 0
+                ? dismissedCodeReviewSummary(reviewFailedStatus)
+                : latestRejected.reason ?? "缺少拒绝原因",
+            job_id: latestRejected.job.job_id,
+        }
+        : undefined;
+    const packetInput = {
+        role: "code-reviewer",
+        boundFiles,
+        checkedDocs: REVIEW_DOC_PATHS,
+        created_from_transition: "review-ready",
+        ...(previousRejection ? { previous_rejection: previousRejection } : {}),
+    };
+    return {
+        scanReason: scan.reason,
+        job: {
+            job_id: newJobId(change, "code-reviewer"),
+            role: "code-reviewer",
+            state: "requested",
+            boundFiles,
+            packet_digest: codeReviewPacketDigest(packetInput),
+            created_from_transition: "review-ready",
+            created_at: new Date().toISOString(),
+            ...(previousRejection ? { previous_rejection: previousRejection } : {}),
+        },
+    };
+}
+function parseCodeReviewFindingRef(value) {
+    const idx = value.indexOf("#");
+    if (idx <= 0 || idx === value.length - 1)
+        return null;
+    return { jobId: value.slice(0, idx), findingId: value.slice(idx + 1) };
+}
+function findReviewFailedFinding(events, ref) {
+    const status = latestCodeReviewFailedStatus(events);
+    if (!status || status.terminal.job.job_id !== ref.jobId)
+        return null;
+    const finding = status.findings.find(item => item.id === ref.findingId)?.finding;
+    if (!finding)
+        return null;
+    return { event: status.terminal.event, finding };
+}
+function reviewFixMarker(ref) {
+    return `review_fix_of:${ref.jobId}#${ref.findingId}`;
+}
+function reviewFixTaskId(ref) {
+    return `REVIEW-FIX-${ref.jobId}#${ref.findingId}`;
+}
+function appendReviewFixTask(changeRoot, ref, finding) {
+    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} tdd_required:true ${marker}`;
+    const suffix = content.endsWith("\n") ? "" : "\n";
+    writeFileSync(tasksPath, `${content}${suffix}${line}\n`);
+    return "created";
+}
+function isFreshOpenCodeReviewerJob(job, projectRoot) {
+    return codeReviewJobStaleReason(projectRoot, job) == null;
+}
+function documentBaseline(changeRoot) {
+    const docs = ["proposal.md", "design.md", "tasks.md", ".superspec/artifacts/test-contract.md"];
+    const baseline = {};
+    for (const doc of docs) {
+        baseline[doc] = sha256File(join(changeRoot, doc)) ?? "sha256:missing";
+    }
+    return baseline;
+}
+function latestReopenProposeBaseline(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition !== "reopen" || payload.reopen_target !== "propose")
+            continue;
+        if (!payload.baseline_docs || typeof payload.baseline_docs !== "object" || Array.isArray(payload.baseline_docs))
+            return null;
+        return payload.baseline_docs;
+    }
+    return null;
+}
+function proposalDocsChangedSinceBaseline(changeRoot, baseline) {
+    const current = documentBaseline(changeRoot);
+    return Object.entries(baseline).some(([path, digest]) => current[path] !== digest);
+}
 /**
  * 统一 transition 提交协议——所有校验在锁内。
  */
@@ -265,13 +366,18 @@ export function startApply(projectRoot, change, changeRoot) {
         decide: (snapshot) => {
             if (snapshot.state !== "propose_ready")
                 return { skip: true, message: `当前状态 ${snapshot.state}，需要 propose_ready` };
+            const events = readEvents(projectRoot, change);
+            const reopenBaseline = latestReopenProposeBaseline(events);
+            if (reopenBaseline && !proposalDocsChangedSinceBaseline(changeRoot, reopenBaseline)) {
+                return { skip: true, message: "回到 propose 后 proposal/design/tasks/test-contract 至少一个文档必须变化" };
+            }
             const reviewedRoles = historicalProposeReadyRoles(projectRoot, change);
             if (reviewedRoles.length > 0) {
                 const reviewResult = checkOrCreateReviewJobs(snapshot, 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"]);
                 if (reviewResult) {
                     return {
                         ...reviewResult,
-                        reason: `进入 apply 前需要 fresh proposal 审查：${reviewResult.reason}`,
+                        reason: `进入执行阶段前需要重新完成计划文档审查：${reviewResult.reason}`,
                     };
                 }
             }
@@ -317,14 +423,83 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
     });
 }
 // ===== reopen =====
-export function reopen(projectRoot, change, changeRoot, to, reason) {
+export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
     return commitTransition(projectRoot, change, changeRoot, {
-        name: "reopen", idempotencyInputs: { to, reason },
+        name: "reopen", idempotencyInputs: { to, reason, reviewFix: opts.reviewFix ?? "", reviewFinding: opts.reviewFinding ?? "" },
         decide: (snapshot) => {
-            if (to !== "apply")
-                return { skip: true, message: `reopen 当前只支持 --to apply，不支持 ${to}` };
             if (!reason || reason.trim() === "")
                 return { skip: true, message: "reopen 需要非空 --reason" };
+            const events = readEvents(projectRoot, change);
+            if (opts.reviewFinding) {
+                if (to !== "propose")
+                    return { skip: true, message: "--review-finding 只能用于回到计划阶段（reopen --to propose）" };
+                if (snapshot.state !== "apply_done")
+                    return { skip: true, message: `当前状态 ${snapshot.state}，不能通过代码审查问题回到计划阶段` };
+                const ref = parseCodeReviewFindingRef(opts.reviewFinding);
+                if (!ref)
+                    return { skip: true, message: "--review-finding 必须是 <job_id>#<finding_id>" };
+                const found = findReviewFailedFinding(events, ref);
+                if (!found)
+                    return { skip: true, message: `找不到有效的代码审查问题 ${opts.reviewFinding}` };
+                const type = found.finding.type;
+                if (type !== "spec" && type !== "mixed")
+                    return { skip: true, message: "只有方案/需求文档问题或混合问题可以回到计划阶段" };
+                const scope = codeReviewDecisionScope(ref.jobId, ref.findingId);
+                const decision = latestCodeReviewDecision(events, scope);
+                if (decision?.answer !== "reopen_propose")
+                    return { skip: true, message: `缺少使用者确认：需要先确认问题 ${ref.findingId} 是否回到计划阶段` };
+                return {
+                    fromState: "apply_done",
+                    toState: "propose",
+                    outcome: "advanced",
+                    reason: reason.trim(),
+                    commitPayload: {
+                        reopen_target: "propose",
+                        source_job_id: ref.jobId,
+                        finding_id: ref.findingId,
+                        decision_scope: scope,
+                        baseline_docs: documentBaseline(changeRoot),
+                    },
+                };
+            }
+            if (opts.reviewFix) {
+                if (to !== "apply")
+                    return { skip: true, message: "--review-fix 只能用于回到实现阶段（reopen --to apply）" };
+                if (snapshot.state !== "apply_done")
+                    return { skip: true, message: `当前状态 ${snapshot.state}，不能通过代码审查修复回到实现阶段` };
+                const ref = parseCodeReviewFindingRef(opts.reviewFix);
+                if (!ref)
+                    return { skip: true, message: "--review-fix 必须是 <job_id>#<finding_id>" };
+                const found = findReviewFailedFinding(events, ref);
+                if (!found)
+                    return { skip: true, message: `找不到有效的代码审查问题 ${opts.reviewFix}` };
+                const type = found.finding.type;
+                if (type === "spec" || type === "mixed") {
+                    const scope = codeReviewDecisionScope(ref.jobId, ref.findingId);
+                    const decision = latestCodeReviewDecision(events, scope);
+                    if (decision?.answer !== "reopen_apply")
+                        return { skip: true, message: `缺少使用者确认：需要先确认问题 ${ref.findingId} 是否直接回到实现阶段修复` };
+                }
+                else if (type !== "implementation") {
+                    return { skip: true, message: "这个代码审查问题不能直接回到实现阶段处理" };
+                }
+                return {
+                    fromState: "apply_done",
+                    toState: "apply",
+                    outcome: "advanced",
+                    reason: reason.trim(),
+                    commitPayload: {
+                        review_fix_of: `${ref.jobId}#${ref.findingId}`,
+                        source_job_id: ref.jobId,
+                        finding_id: ref.findingId,
+                    },
+                    postCommit: (_pr, _ch, cr) => {
+                        appendReviewFixTask(cr, ref, found.finding);
+                    },
+                };
+            }
+            if (to !== "apply")
+                return { skip: true, message: `reopen 当前只支持 --to apply 或 --to propose，不支持 ${to}` };
             if (snapshot.state !== "apply_done" && snapshot.state !== "review") {
                 return { skip: true, message: `当前状态 ${snapshot.state}，不能 reopen 到 apply` };
             }
@@ -362,19 +537,69 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
                     commitPayload: policyPayload,
                 };
             }
-            if (snapshot.state === "apply_done" || 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));
-                if (!policy.requires_verifier) {
-                    if (snapshot.state === "apply_done") {
+            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: `审查策略=${policy.review_risk}，无需最终验证，进入审查阶段`,
-                            commitPayload: policyPayload,
+                            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" },
+                    },
+                };
+            }
+            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",
@@ -402,21 +627,14 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
                         fromState: snapshot.state, toState: snapshot.state, outcome: "job_created",
                         newJobs: [job],
                         reason: previousVerifierRejected
-                            ? "此前 verifier 未通过；请先根据 findings 修改任务或文档，确认无需修改时再执行新的最终验证工作项"
+                            ? "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项"
                             : "创建最终验证工作项",
                         commitPayload: policyPayload,
                         ...(previousVerifierRejected ? {
-                            details: { advisory: "此前 verifier 未通过；请先根据 findings 修改任务或文档，确认无需修改时再执行新的最终验证工作项" },
+                            details: { advisory: "此前最终验证未通过；请先根据验证报告修改任务或文档，确认无需修改时再执行新的最终验证工作项" },
                         } : {}),
                     };
                 }
-                if (snapshot.state === "apply_done") {
-                    return {
-                        fromState: "apply_done", toState: "review", outcome: "advanced",
-                        reason: "最终验证已接受，进入审查阶段",
-                        commitPayload: policyPayload,
-                    };
-                }
                 if (!storedPolicy) {
                     return {
                         fromState: "review", toState: "review", outcome: "advanced",
@@ -444,11 +662,11 @@ export function accept(projectRoot, change, changeRoot) {
             const policy = readReviewPolicyFromEvents(events);
             if (!policy)
                 return { skip: true, message: "缺少审查策略，请先运行 review-ready" };
-            if (policy.requires_verifier) {
+            if (requiresFinalVerifierForCurrentReview(events) || policy.requires_verifier) {
                 const currentEvidenceDigest = reviewEvidenceDigest(events);
                 const verifierAccepted = snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest));
                 if (!verifierAccepted)
-                    return { skip: true, message: "缺少 fresh verifier，请先运行 review-ready" };
+                    return { skip: true, message: "缺少仍然匹配当前证据的最终验证，请先运行 review-ready" };
             }
             return { fromState: "review", toState: "accepted", outcome: "advanced", reason: "审查通过" };
         },

package/dist/types.d.ts

@@ -5,7 +5,13 @@ export type Ref = {
     sha: string;
 };
 export type JobState = "requested" | "accepted" | "rejected";
-export type JobRole = "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "verifier";
+export type JobRole = "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "verifier" | "code-reviewer";
+export type CodeReviewResultKind = "invalid_report" | "non_actionable_report" | "review_failed";
+export interface CodeReviewPreviousRejection {
+    result_kind: CodeReviewResultKind;
+    reason: string;
+    job_id: string;
+}
 export interface Job {
     job_id: string;
     role: JobRole;
@@ -15,6 +21,7 @@ export interface Job {
     packet_digest: string;
     created_from_transition: string;
     created_at: string;
+    previous_rejection?: CodeReviewPreviousRejection;
 }
 export interface JobPacket {
     job_id: string;
@@ -30,6 +37,7 @@ export interface JobPacket {
     file_fallback?: boolean;
     output_contract_fields?: string[];
     output_contract_optional_fields?: string[];
+    output_instructions?: string;
     stop_conditions: string[];
     created_from_transition: string;
 }
@@ -66,6 +74,11 @@ export interface TransitionCommitPayload {
         review_risk: "minimal" | "normal" | "strict";
         requires_verifier: boolean;
     };
+    code_review_gate?: {
+        decision: "passed" | "skipped";
+        job_id?: string;
+        reason?: "no_code_changes";
+    };
 }
 export interface Snapshot {
     change_id: string;
@@ -100,6 +113,7 @@ export interface TestRun {
     test_id: string;
     attempt_id?: string | null;
     task_structure_digest: string;
+    covers_task_ids?: string[];
     command: string;
     cwd: string;
     exit_code: number;

package/package.json

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

package/templates/workflow/agents/architect.toml

@@ -5,9 +5,9 @@ model_reasoning_effort = "high"
 developer_instructions = """
 Role: Architect. Review system boundaries, interface contracts, data flow, maintenance risk, rollback risk, and design tradeoffs.
 
-Task binding: load `.codex/prompts/architect.md` first, then read the current task instructions. Their refs, output format, contract fields, review scope, and stop conditions override static prompt memory.
+Task binding: load `.codex/prompts/architect.md` first, then read the current job packet and task instructions. The job packet is the runtime contract; follow it over static prompt memory, including any previous rejection it asks you to correct.
 
 Boundary: read-only. Do not edit files or judge materials you have not opened. Report missing context upward instead of guessing.
 
-Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"architect"`, `verdict`, `findings`, and `reviewer:{kind,id}`. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
 """

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

@@ -1,13 +1,13 @@
 # SuperSpec Codex agent: code-reviewer
 name = "code-reviewer"
-description = "Comprehensive review across all concerns"
+description = "Code-level review for spec fit, bugs, safety, and test gaps"
 model_reasoning_effort = "high"
 developer_instructions = """
-Role: Code Reviewer. Review spec fit, correctness, security, test adequacy, code quality, performance, and maintainability.
+Role: Code Reviewer. Check spec fit, correctness, security, test adequacy, code quality, performance, and maintainability without making the workflow heavy.
 
-Task binding: load `.codex/prompts/code-reviewer.md` first, then read the current task instructions. Their refs, output format, contract fields, review scope, declared write scope, executor report refs, and stop conditions override static prompt memory.
+Task binding: load `.codex/prompts/code-reviewer.md` first, then read the current job packet and task instructions. The job packet is the runtime contract; follow it over static prompt memory, including any previous rejection it asks you to correct.
 
-Boundary: read-only. Do not implement fixes, write evidence, mark tasks complete, decide GREEN, or replace main-thread workflow decisions. Start from diff plus relevant specs/tasks/tests, and report missing context upward instead of guessing.
+Boundary: read-only. Do not implement fixes, write evidence, mark tasks complete, decide GREEN, reopen, accept, or replace main-thread workflow decisions. Start from packet-provided materials and report missing context upward instead of guessing.
 
-Output: concise Simplified Chinese. Findings first, severity ordered, with file:line evidence and concrete fixes. Write `无阻塞问题` when no blocking issue is found.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Blocking issues must be traceable and actionable. Write `无阻塞问题` when no blocking issue is found.
 """

package/templates/workflow/agents/critic.toml

@@ -5,9 +5,9 @@ model_reasoning_effort = "high"
 developer_instructions = """
 Role: Critic. Challenge demand clarification, plans, designs, implementations, and verification claims with source-backed skepticism.
 
-Task binding: load `.codex/prompts/critic.md` first, then read the current task instructions. Their refs, output format, contract fields, review scope, and stop conditions override static prompt memory.
+Task binding: load `.codex/prompts/critic.md` first, then read the current job packet and task instructions. The job packet is the runtime contract; follow it over static prompt memory, including any previous rejection it asks you to correct.
 
 Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward.
 
-Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"critic"`, `verdict`, `findings`, and `reviewer:{kind,id}`. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.
 """

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

@@ -5,9 +5,9 @@ model_reasoning_effort = "high"
 developer_instructions = """
 Role: Test Engineer. Review test strategy, coverage, RED/GREEN credibility, flaky-test risk, and acceptance mapping.
 
-Task binding: load `.codex/prompts/test-engineer.md` first for SuperSpec review/propose lanes, then read the current task instructions. Their refs, output format, contract fields, review scope, and stop conditions override static prompt memory.
+Task binding: load `.codex/prompts/test-engineer.md` first, then read the current job packet and task instructions. The job packet is the runtime contract; follow it over static prompt memory, including any previous rejection it asks you to correct.
 
-Boundary: SuperSpec review/propose lanes are read-only. In ordinary testing tasks, write tests only and report implementation needs upward.
+Boundary: review jobs are read-only. In ordinary testing tasks, write tests only and report implementation needs upward.
 
-Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"test-engineer"`, `verdict`, `findings`, and `reviewer:{kind,id}`. Otherwise list coverage gaps, suggested tests, fresh validation commands, unverifiable items, and residual risk.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise list coverage gaps, suggested tests, fresh validation commands, unverifiable items, and residual risk.
 """

package/templates/workflow/agents/verifier.toml

@@ -3,11 +3,11 @@ name = "verifier"
 description = "Completion evidence, claim validation, test adequacy"
 model_reasoning_effort = "high"
 developer_instructions = """
-Role: Verifier. Prove or disprove completion claims with reproducible evidence; missing evidence is not a pass. When invoked by review-ready for a job report, act as the final verification gate before review.
+Role: Verifier. Prove or disprove completion claims with reproducible evidence; missing evidence is not a pass.
 
-Task binding: load `.codex/prompts/verifier.md` first, then read the current task instructions. Their refs, output format, contract fields, review scope, evidence/report refs, freshness fingerprints, and stop conditions override static prompt memory.
+Task binding: load `.codex/prompts/verifier.md` first, then read the current job packet and task instructions. The job packet is the runtime contract; follow it over static prompt memory, including any previous rejection it asks you to correct.
 
-Boundary: read-only. Check commands, test output, diff, artifacts, evidence refs, acceptance criteria, and freshness without editing files, writing evidence, or marking tasks complete.
+Boundary: read-only. Check commands, test output, artifacts, evidence refs, acceptance criteria, code-reviewer closure, and whether the verifier job still matches the packet-provided evidence version. Use diffs only as evidence references when the packet requires them. Do not edit files, write evidence, mark tasks complete, or add an extra code-diff blocker outside the packet contract.
 
-Output: concise Simplified Chinese. For job_report_json, submit `role:"verifier"`, `verdict`, and `findings`. For other verification paths, state pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. For other verification paths, state pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.
 """