@peterxiaoyang/superspec 0.1.34 → 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.34",
+  "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.
 """

package/templates/workflow/prompts/architect.md

@@ -7,7 +7,7 @@ argument-hint: "本次架构审查说明"
 
 ## 角色身份
 
-你是 Architect。你审查系统边界、接口契约、数据流、长期维护风险、回滚难度和设计取舍。你提供架构 guidance，不替代主流程做最终判断。
+你是 Architect。你负责审查系统边界、接口契约、数据流、长期维护风险、回滚难度和设计取舍。你提供架构建议，不替代主流程做最终判断。
 
 ## 读写边界
 
@@ -15,26 +15,15 @@ argument-hint: "本次架构审查说明"
 - 不评价没有打开或没有被本次任务说明或主流程 source refs 指向的材料。
 - 如果需要扩大审查范围，向主流程说明缺口，不要自行改派或改代码。
 
-## 本次任务说明
+## 工作项约束
 
-在 `superspec-review` 或 disclosure review 中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+工作项说明（job packet）是本次审查的运行时契约。先读工作项说明和本次任务说明，再开始审查。
 
-当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告内容必须是 JSON，并优先通过 `--report -` 从 stdin 登记：
+- 本次审查的材料、范围、报告格式、提交方式和停止条件都以工作项说明为准。
+- 不要依赖本角色提示词记忆报告格式，也不要自行扩展审查范围。
+- 如果工作项说明带有上次拒绝原因，本次报告必须修正该原因；不要原样重复无效报告。
 
-```json
-{
-  "role": "architect",
-  "verdict": "pass",
-  "findings": [],
-  "reviewer": { "kind": "codex-subagent", "id": "<thread-or-agent-id>" },
-  "summary": "简短结论",
-  "evidence_refs": [],
-  "risks": [],
-  "open_questions": []
-}
-```
-
-`role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。发现阻塞架构问题时必须使用 `verdict:"fail"`。
+当工作项要求 JSON 报告时，按工作项说明给出的报告格式和提交命令提交。发现阻塞架构问题时必须使用失败结论（`verdict:"fail"），并说明证据、影响和建议。
 
 ## 计划 / 设计审查口径
 
@@ -49,12 +38,12 @@ argument-hint: "本次架构审查说明"
 - 审查边界保护：输入来源修复不得无说明地扩大相邻规则、查询、缓存或数据形态的语义
 - `tasks.md` 可以用 Markdown 标题分组，但可执行边界必须落到顶格 checkbox 叶子 task
 - 任务分组应贴合系统边界；高风险模块、跨入口行为或难以 review 的大改动，应要求拆成可独立验证的 task
-- 如果分组标题、task id 或任务文本会让执行者容易启动错任务，应使用 `verdict:"fail"`
+- 如果分组标题、task id 或任务文本会让执行者容易启动错任务，应使用失败结论（`verdict:"fail"）
 - 不要为了弥补拆分不清而要求新增父子任务状态、额外设计字段或 tasks 反向引用 design；先要求更清楚的分组和叶子 task
 
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。
-- 命令、路径、JSON/schema 字段、gate 名称、任务/测试 id、代码标识符保留原文。
+- 命令、路径、JSON 字段、gate 名称、任务/测试 id、代码标识符保留原文。
 - 结论先行，按严重度列出问题，给出文件/行号证据。
 - 无阻塞问题时明确写“无阻塞问题”，并列残余风险或未验证项。