@peterxiaoyang/superspec 0.1.22 → 0.1.23

package/dist/next.js

@@ -3,6 +3,7 @@ import { rebuildSnapshot } from "./sync.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { readEvents, sha256Text } from "./store.js";
+import { isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewEvidenceDigest } from "./review.js";
 import { validateDiscovery, countDiscoveryOpenQuestions, collectProposeOpenQuestions, parseTasksMd, pendingTasksInContent } from "./format.js";
 const ACTIVE_PROPOSAL_REVIEW_ROLES = new Set(["critic", "architect", "test-engineer"]);
 function isActiveProposalReviewJob(job) {
@@ -244,6 +245,43 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                     missing_inputs: [],
                 };
             }
+            const reviewVerifierJobs = snapshot.open_jobs.filter(isReviewReadyVerifier);
+            if (reviewVerifierJobs.length > 0) {
+                return {
+                    state: "review",
+                    path: "required_job",
+                    required_jobs: reviewVerifierJobs.map(j => ({
+                        job_id: j.job_id,
+                        role: j.role,
+                        packet_command: packetCommand(change, j.job_id),
+                    })),
+                    reason: `有 ${reviewVerifierJobs.length} 个待完成最终验证工作项`,
+                };
+            }
+            const events = readEvents(projectRoot, change);
+            const policy = readReviewPolicyFromEvents(events);
+            if (!policy) {
+                return {
+                    state: "review",
+                    path: "next_command",
+                    next_command: transitionCommand(change, "review-ready", riskFlag(defaultRisk)),
+                    reason: "缺少审查策略，先补 review-ready",
+                    missing_inputs: [],
+                };
+            }
+            if (policy.requires_verifier) {
+                const currentEvidenceDigest = reviewEvidenceDigest(events);
+                const verifierAccepted = snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest));
+                if (!verifierAccepted) {
+                    return {
+                        state: "review",
+                        path: "next_command",
+                        next_command: transitionCommand(change, "review-ready", riskFlag(defaultRisk)),
+                        reason: "缺少 fresh verifier，先补最终验证",
+                        missing_inputs: [],
+                    };
+                }
+            }
             return {
                 state: "review",
                 path: "next_command",

package/dist/record.js

@@ -1,7 +1,8 @@
 // SuperSpec 流程引擎 — record：工作项结果登记
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, withLock, } from "./store.js";
+import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, withLock, appendRawRecord, } from "./store.js";
+import { reviewEvidenceDigest, reviewVerifierStaleReason } from "./review.js";
 const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
 const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
 const REVIEWER_KINDS = new Set(["codex-subagent", "human", "external-agent"]);
@@ -97,6 +98,7 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
         const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
         // acceptance checks
         const checks = [];
+        let parsedReport = null;
         // 0. 报告格式和角色匹配（最小 JSON contract）
         try {
             const report = JSON.parse(reportContent);
@@ -104,7 +106,8 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
                 checks.push("报告必须是 JSON object");
             }
             else {
-                const obj = report;
+                parsedReport = report;
+                const obj = parsedReport;
                 for (const field of REVIEW_REPORT_REQUIRED_FIELDS) {
                     if (!(field in obj))
                         checks.push(`报告缺少必填字段 ${field}`);
@@ -149,6 +152,10 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
                 checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
             }
         }
+        const reviewStaleReason = reviewVerifierStaleReason(job, changeRoot, reviewEvidenceDigest(events));
+        if (reviewStaleReason && !checks.includes(reviewStaleReason)) {
+            checks.push(reviewStaleReason);
+        }
         // 2. 报告格式基本校验（非空 JSON 或文本）
         if (!reportContent.trim()) {
             checks.push("报告内容为空");
@@ -170,11 +177,13 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
             };
         }
         // 接受
+        const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
         const acceptEvent = makeEvent(change, "job_accepted", {
             job_id: jobId,
             role: job.role,
             report_digest: reportDigest,
             accepted_at: new Date().toISOString(),
+            ...rawRef,
         });
         appendEvent(projectRoot, change, acceptEvent);
         return {
@@ -189,6 +198,7 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
 export function recordUserDecision(projectRoot, change, inputFile) {
     return withLock(projectRoot, change, () => {
         ensureChangeLayout(projectRoot, change);
+        const events = readEvents(projectRoot, change);
         if (!existsSync(inputFile)) {
             appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "file_not_found", path: inputFile }));
             return { event_type: "user_decision_recorded", accepted: false, message: `决策文件不存在：${inputFile}` };
@@ -206,11 +216,26 @@ export function recordUserDecision(projectRoot, change, inputFile) {
             appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "missing_scope_or_answer" }));
             return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少 scope 或 answer" };
         }
-        const event = makeEvent(change, "user_decision_recorded", {
+        const inputDigest = sha256File(inputFile) ?? "sha256:unknown";
+        const existing = events.find(e => e.event_type === "user_decision_recorded"
+            && e.payload.input_digest === inputDigest);
+        if (existing) {
+            return {
+                event_type: "user_decision_recorded",
+                accepted: true,
+                message: "幂等返回：同 user decision 已登记",
+            };
+        }
+        const normalizedDecision = {
             scope: decision.scope,
             question: decision.question ?? "",
             answer: decision.answer,
-            input_digest: sha256File(inputFile) ?? "sha256:unknown",
+        };
+        const rawRef = appendRawRecord(projectRoot, change, "user-decisions", normalizedDecision);
+        const event = makeEvent(change, "user_decision_recorded", {
+            ...normalizedDecision,
+            input_digest: inputDigest,
+            ...rawRef,
         });
         appendEvent(projectRoot, change, event);
         return {
@@ -268,11 +293,13 @@ export function jobsPacket(projectRoot, change, jobId) {
             role: job.role,
             recommended_agent: recommendedAgentForRole(job.role),
             boundFiles: job.boundFiles,
+            ...(job.review_evidence_digest ? { review_evidence_digest: job.review_evidence_digest } : {}),
             packet_digest: job.packet_digest,
             required_output_kind: "job_report_json",
             output_contract_fields: requiresReviewer(job.role) ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer"] : [...REVIEW_REPORT_REQUIRED_FIELDS],
             output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
             output_instructions: `${roleDescription(job.role)}。请审查 ${job.boundFiles.map(f => f.path).join(", ")}，` +
+                (job.review_evidence_digest ? `本工作项绑定的执行证据版本为 ${job.review_evidence_digest}，` : "") +
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} reviewer 执行并在 reviewer.kind/id 中记录来源，` : "") +
                 `产出 JSON 报告文件并通过 superspec record job-submit 登记。` +
                 (requiresReviewer(job.role)

package/dist/review.d.ts

@@ -0,0 +1,17 @@
+import type { Event, Job, Ref } from "./types.ts";
+export type ReviewRisk = "minimal" | "normal" | "strict";
+export interface ReviewPolicy {
+    review_risk: ReviewRisk;
+    requires_verifier: boolean;
+}
+export declare const REVIEW_DOC_PATHS: string[];
+export declare function assertCommitPayloadExtension(payload: Record<string, unknown>): void;
+export declare function reviewPolicyForRisk(risk: ReviewRisk): ReviewPolicy;
+export declare function readReviewPolicyFromEvents(events: Event[]): ReviewPolicy | null;
+export declare function isReviewReadyVerifier(job: Job): boolean;
+export declare function reviewBoundFiles(changeRoot: string): Ref[];
+export declare function reviewEvidenceDigest(events: Event[]): string;
+export declare function boundFilesStaleReason(job: Job, changeRoot: string): string | null;
+export declare function reviewEvidenceStaleReason(job: Job, currentDigest: string): string | null;
+export declare function reviewVerifierStaleReason(job: Job, changeRoot: string, currentEvidenceDigest: string): string | null;
+export declare function isFreshReviewVerifier(job: Job, changeRoot: string, currentEvidenceDigest: string): boolean;

package/dist/review.js

@@ -0,0 +1,159 @@
+// SuperSpec review helpers: policy, verifier freshness, evidence digest
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { sha256File, sha256Text } from "./store.js";
+export const REVIEW_DOC_PATHS = [
+    "proposal.md",
+    "tasks.md",
+    "design.md",
+    ".superspec/artifacts/discovery.md",
+    ".superspec/artifacts/business-invariants.md",
+    ".superspec/artifacts/test-contract.md",
+];
+const CORE_COMMIT_FIELDS = new Set([
+    "transition",
+    "from_state",
+    "to_state",
+    "outcome",
+    "created_job_ids",
+    "new_jobs",
+    "reason",
+]);
+export function assertCommitPayloadExtension(payload) {
+    for (const key of Object.keys(payload)) {
+        if (CORE_COMMIT_FIELDS.has(key)) {
+            throw new Error(`commitPayload 不能覆盖核心字段：${key}`);
+        }
+    }
+}
+export function reviewPolicyForRisk(risk) {
+    return {
+        review_risk: risk,
+        requires_verifier: risk !== "minimal",
+    };
+}
+function isReviewPolicy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const obj = value;
+    return ((obj.review_risk === "minimal" || obj.review_risk === "normal" || obj.review_risk === "strict") &&
+        typeof obj.requires_verifier === "boolean");
+}
+export function readReviewPolicyFromEvents(events) {
+    for (const ev of events) {
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition !== "review-ready")
+            continue;
+        if (isReviewPolicy(payload.review_policy))
+            return payload.review_policy;
+    }
+    return null;
+}
+export function isReviewReadyVerifier(job) {
+    return job.role === "verifier" && job.created_from_transition === "review-ready";
+}
+export function reviewBoundFiles(changeRoot) {
+    return REVIEW_DOC_PATHS
+        .filter(path => existsSync(join(changeRoot, path)))
+        .map(path => ({ path, sha: sha256File(join(changeRoot, path)) ?? "sha256:missing" }));
+}
+function evidenceSortKey(record) {
+    return [
+        record.kind,
+        record.task_id ?? "",
+        record.attempt_id ?? "",
+        record.task_structure_digest ?? "",
+        record.test_id ?? "",
+        record.semantic_status ?? "",
+        record.command ?? "",
+        record.cwd ?? "",
+        record.exit_code == null ? "" : String(record.exit_code),
+        record.target_fingerprint ?? "",
+        record.event_digest,
+    ].join("\u0000");
+}
+export function reviewEvidenceDigest(events) {
+    const attemptsById = new Map();
+    const completed = [];
+    for (const ev of events) {
+        if (ev.event_type === "task_started") {
+            const attempt = ev.payload;
+            attemptsById.set(attempt.attempt_id, attempt);
+        }
+        else if (ev.event_type === "task_completed") {
+            const payload = ev.payload;
+            if (typeof payload.task_id !== "string" || typeof payload.attempt_id !== "string")
+                continue;
+            const attempt = attemptsById.get(payload.attempt_id);
+            completed.push({
+                task_id: payload.task_id,
+                attempt_id: payload.attempt_id,
+                task_structure_digest: attempt?.task_structure_digest ?? null,
+                event_digest: ev.event_digest,
+            });
+        }
+    }
+    const completedAttemptIds = new Set(completed.map(item => item.attempt_id));
+    const completedStructureDigests = new Set(completed
+        .map(item => item.task_structure_digest)
+        .filter((digest) => typeof digest === "string" && digest.length > 0));
+    const records = completed.map(item => ({
+        kind: "task_completed",
+        task_id: item.task_id,
+        attempt_id: item.attempt_id,
+        task_structure_digest: item.task_structure_digest,
+        event_digest: item.event_digest,
+    }));
+    for (const ev of events) {
+        if (ev.event_type !== "test_run_recorded")
+            continue;
+        const payload = ev.payload;
+        const attemptId = typeof payload.attempt_id === "string" ? payload.attempt_id : null;
+        const structureDigest = typeof payload.task_structure_digest === "string" ? payload.task_structure_digest : null;
+        const matchesCompletedAttempt = attemptId != null && completedAttemptIds.has(attemptId);
+        const matchesLegacyDigest = attemptId == null && structureDigest != null && completedStructureDigests.has(structureDigest);
+        if (!matchesCompletedAttempt && !matchesLegacyDigest)
+            continue;
+        records.push({
+            kind: "test_run_recorded",
+            test_id: typeof payload.test_id === "string" ? payload.test_id : null,
+            attempt_id: attemptId,
+            task_structure_digest: structureDigest,
+            semantic_status: typeof payload.semantic_status === "string" ? payload.semantic_status : null,
+            command: typeof payload.command === "string" ? payload.command : "",
+            cwd: typeof payload.cwd === "string" ? payload.cwd : "",
+            exit_code: typeof payload.exit_code === "number" ? payload.exit_code : null,
+            target_fingerprint: typeof payload.target_fingerprint === "string" ? payload.target_fingerprint : null,
+            event_digest: ev.event_digest,
+        });
+    }
+    records.sort((a, b) => evidenceSortKey(a).localeCompare(evidenceSortKey(b)));
+    return sha256Text(JSON.stringify(records));
+}
+export function boundFilesStaleReason(job, changeRoot) {
+    for (const bf of job.boundFiles) {
+        const current = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
+        if (current !== bf.sha) {
+            return `绑定文件 ${bf.path} 已变化（${bf.sha} → ${current}）`;
+        }
+    }
+    return null;
+}
+export function reviewEvidenceStaleReason(job, currentDigest) {
+    if (!isReviewReadyVerifier(job))
+        return null;
+    if (!job.review_evidence_digest)
+        return "最终验证工作项缺少执行证据版本";
+    if (job.review_evidence_digest !== currentDigest) {
+        return `最终验证执行证据版本已变化（${job.review_evidence_digest} → ${currentDigest}）`;
+    }
+    return null;
+}
+export function reviewVerifierStaleReason(job, changeRoot, currentEvidenceDigest) {
+    return boundFilesStaleReason(job, changeRoot) ?? reviewEvidenceStaleReason(job, currentEvidenceDigest);
+}
+export function isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest) {
+    return isReviewReadyVerifier(job) && reviewVerifierStaleReason(job, changeRoot, currentEvidenceDigest) == null;
+}

package/dist/store.d.ts

@@ -1,7 +1,15 @@
 import type { Event, Snapshot, Ref } from "./types.ts";
+export declare const RAW_RECORD_KINDS: readonly ["test-runs", "review-reports", "user-decisions"];
+export type RawRecordKind = typeof RAW_RECORD_KINDS[number];
+export interface RawRecordRef {
+    raw_kind: RawRecordKind;
+    raw_index: number;
+    raw_digest: string;
+}
 export declare function engineRoot(projectRoot: string): string;
 export declare function changeDir(projectRoot: string, change: string): string;
 export declare function eventsFile(projectRoot: string, change: string): string;
+export declare function rawFile(projectRoot: string, change: string, kind: RawRecordKind): string;
 export declare function snapshotFile(projectRoot: string, change: string): string;
 export declare function lockFile(projectRoot: string, change: string): string;
 export declare function stagingDir(projectRoot: string, change: string, transitionId: string): string;
@@ -21,6 +29,13 @@ export declare function makeEvent(change: string, eventType: Event["event_type"]
     outputRefs?: Ref[];
 }): Event;
 export declare function eventsDigest(events: Event[]): string;
+/**
+ * Append an accepted record input to the raw archive.
+ *
+ * Contract: call only while holding the per-change lock. The returned raw_index
+ * is the zero-based valid-record index, not necessarily the physical line.
+ */
+export declare function appendRawRecord(projectRoot: string, change: string, kind: RawRecordKind, record: unknown): RawRecordRef;
 export declare function writeSnapshot(projectRoot: string, change: string, snapshot: Snapshot): void;
 export declare function readSnapshot(projectRoot: string, change: string): Snapshot | null;
 export declare function snapshotDigest(snapshot: Snapshot): string;

package/dist/store.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, openSync, closeSync
 import { join, dirname } from "node:path";
 import { hostname } from "node:os";
 // ===== 路径 =====
+export const RAW_RECORD_KINDS = ["test-runs", "review-reports", "user-decisions"];
 export function engineRoot(projectRoot) {
     return join(projectRoot, ".superspec");
 }
@@ -13,6 +14,9 @@ export function changeDir(projectRoot, change) {
 export function eventsFile(projectRoot, change) {
     return join(changeDir(projectRoot, change), "events.jsonl");
 }
+export function rawFile(projectRoot, change, kind) {
+    return join(changeDir(projectRoot, change), "raw", `${kind}.jsonl`);
+}
 export function snapshotFile(projectRoot, change) {
     return join(changeDir(projectRoot, change), "snapshot.json");
 }
@@ -109,6 +113,52 @@ export function makeEvent(change, eventType, payload, opts = {}) {
 export function eventsDigest(events) {
     return sha256Text(events.map(e => e.event_digest).join("\n"));
 }
+// ===== Raw 归档 =====
+function countValidJsonlRecords(filePath) {
+    if (!existsSync(filePath))
+        return 0;
+    let count = 0;
+    for (const line of readFileSync(filePath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            JSON.parse(line);
+            count++;
+        }
+        catch {
+            // raw JSONL 与 events.jsonl 一样容忍截断/损坏行；raw_index 按有效记录计数。
+        }
+    }
+    return count;
+}
+/**
+ * Append an accepted record input to the raw archive.
+ *
+ * Contract: call only while holding the per-change lock. The returned raw_index
+ * is the zero-based valid-record index, not necessarily the physical line.
+ */
+export function appendRawRecord(projectRoot, change, kind, record) {
+    if (!RAW_RECORD_KINDS.includes(kind)) {
+        throw new Error(`Unsupported raw record kind: ${kind}`);
+    }
+    const rf = rawFile(projectRoot, change, kind);
+    mkdirSync(dirname(rf), { recursive: true });
+    const rawIndex = countValidJsonlRecords(rf);
+    const line = JSON.stringify(record);
+    const rawDigest = sha256Text(line);
+    const fd = openSync(rf, "a");
+    try {
+        writeFileSync(fd, line + "\n", "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+    return {
+        raw_kind: kind,
+        raw_index: rawIndex,
+        raw_digest: rawDigest,
+    };
+}
 // ===== 快照 =====
 export function writeSnapshot(projectRoot, change, snapshot) {
     writeFileSync(snapshotFile(projectRoot, change), JSON.stringify(snapshot, null, 2) + "\n", "utf8");

package/dist/sync.js

@@ -1,7 +1,8 @@
 // SuperSpec 流程引擎 — sync：从当前文档 + events.jsonl 重建 snapshot
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { readEvents, eventsDigest, computeDocumentDigests, sha256File, sha256Text, ensureChangeLayout, } from "./store.js";
+import { readEvents, eventsDigest, computeDocumentDigests, sha256Text, ensureChangeLayout, } from "./store.js";
+import { reviewEvidenceDigest, reviewVerifierStaleReason } from "./review.js";
 const TRACKED_DOCS = [
     "proposal.md", "design.md", "tasks.md",
     ".superspec/artifacts/discovery.md",
@@ -79,18 +80,12 @@ function replayEvents(events) {
     return { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition };
 }
 /** 粗粒度失效：检查 job 的 boundFiles 是否仍匹配当前文档 */
-function checkStaleJobs(jobs, changeRoot) {
+function checkStaleJobs(jobs, changeRoot, currentReviewEvidenceDigest) {
     const stale = [];
     for (const job of jobs) {
-        for (const bf of job.boundFiles) {
-            const current = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
-            if (current !== bf.sha) {
-                stale.push({
-                    job_id: job.job_id,
-                    reason: `绑定文件 ${bf.path} 已变化（${bf.sha} → ${current}）`,
-                });
-                break; // 一个文件变就够了
-            }
+        const reason = reviewVerifierStaleReason(job, changeRoot, currentReviewEvidenceDigest);
+        if (reason) {
+            stale.push({ job_id: job.job_id, reason });
         }
     }
     return stale;
@@ -113,9 +108,10 @@ export function rebuildSnapshot(projectRoot, change, changeRoot, openspecStatusD
     const documentDigests = computeDocumentDigests(changeRoot, TRACKED_DOCS);
     const tsDigest = tasksStructureDigest(changeRoot);
     const { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition } = replayEvents(events);
+    const currentReviewEvidenceDigest = reviewEvidenceDigest(events);
     // 粗粒度失效检查（只读，不写事件）：snapshot 只暴露当前可执行/可复用 job。
-    const staleOpenInfo = checkStaleJobs(openJobs, changeRoot);
-    const staleAcceptedInfo = checkStaleJobs(acceptedJobs, changeRoot);
+    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));
     const freshAccepted = acceptedJobs.filter(j => !staleAcceptedInfo.some(s => s.job_id === j.job_id));
     return {

package/dist/task.js

@@ -1,7 +1,7 @@
 // SuperSpec 流程引擎 — task：测试运行记录 + 任务结构指纹工具
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock } from "./store.js";
+import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock, appendRawRecord } from "./store.js";
 import { tasksStructureDigest as formatDigest } from "./format.js";
 /** tasks.md 结构指纹（委托给 format.ts 统一实现） */
 export function tasksStructureDigestOf(changeRoot) {
@@ -27,7 +27,7 @@ export function recordTestRun(projectRoot, change, inputFile) {
         if (!tr.test_id || !tr.task_structure_digest) {
             return { accepted: false, message: "缺少 test_id 或 task_structure_digest" };
         }
-        const event = makeEvent(change, "test_run_recorded", {
+        const normalizedTestRun = {
             test_id: tr.test_id,
             task_structure_digest: tr.task_structure_digest,
             attempt_id: tr.attempt_id ?? null,
@@ -37,6 +37,11 @@ export function recordTestRun(projectRoot, change, inputFile) {
             semantic_status: tr.semantic_status ?? "unknown",
             target_fingerprint: tr.target_fingerprint ?? null,
             raw_log_ref: tr.raw_log_ref ?? null,
+        };
+        const rawRef = appendRawRecord(projectRoot, change, "test-runs", normalizedTestRun);
+        const event = makeEvent(change, "test_run_recorded", {
+            ...normalizedTestRun,
+            ...rawRef,
         });
         appendEvent(projectRoot, change, event);
         return { accepted: true, message: `测试运行已登记：test_id=${tr.test_id}` };

package/dist/transition.d.ts

@@ -5,6 +5,7 @@ interface Decision {
     outcome: "advanced" | "job_created";
     newJobs?: Job[];
     reason: string;
+    commitPayload?: Record<string, unknown>;
     extraEvents?: {
         type: string;
         payload: Record<string, unknown>;

package/dist/transition.js

@@ -1,8 +1,9 @@
 // SuperSpec 流程引擎 — transition：提交协议 + 所有 transition 处理器
 import { join } from "node:path";
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
-import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot, snapshotDigest, withLock, idempotencyKey, stagingDir, sha256File, sha256Text, } from "./store.js";
+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 { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, } from "./review.js";
 import { validateDiscovery, collectProposeOpenQuestions, findTaskInLines, parseTasksMd, pendingTasksInContent, tasksStructureDigest } from "./format.js";
 let transitionSeq = 0;
 function newTransitionId() { return `T-${Date.now()}-${++transitionSeq}`; }
@@ -85,6 +86,20 @@ function pendingTaskIds(changeRoot) {
 function formatPendingTaskMessage(ids, action) {
     return `尚有未完成任务：${ids.join(", ")}；${action}`;
 }
+function hasRejectedReviewReadyVerifier(events) {
+    const reviewReadyVerifierIds = new Set();
+    for (const ev of events) {
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const newJobs = ev.payload.new_jobs ?? [];
+        for (const job of newJobs) {
+            if (isReviewReadyVerifier(job))
+                reviewReadyVerifierIds.add(job.job_id);
+        }
+    }
+    return events.some(ev => ev.event_type === "job_rejected" &&
+        reviewReadyVerifierIds.has(ev.payload.job_id ?? ""));
+}
 /**
  * 统一 transition 提交协议——所有校验在锁内。
  */
@@ -113,7 +128,8 @@ export function commitTransition(projectRoot, change, changeRoot, opts) {
                 created_jobs: [], message: decision.message, events_written: 0,
             };
         }
-        const { fromState, toState, outcome, newJobs = [], reason, extraEvents = [], details } = decision;
+        const { fromState, toState, outcome, newJobs = [], reason, commitPayload = {}, extraEvents = [], details } = decision;
+        assertCommitPayloadExtension(commitPayload);
         if (fromState !== snapshot.state) {
             return {
                 transition: name, outcome: "advanced",
@@ -137,6 +153,7 @@ export function commitTransition(projectRoot, change, changeRoot, opts) {
         appendEvent(projectRoot, change, makeEvent(change, "transition_commit", {
             transition: name, from_state: fromState, to_state: toState,
             outcome, created_job_ids: newJobs.map(j => j.job_id), new_jobs: newJobs, reason,
+            ...commitPayload,
         }, { transitionId, idempotencyKey: idemKey, prevSnapshotDigest: worldDigest }));
         // extra events (task_started, task_completed, etc.)
         for (const ex of extraEvents) {
@@ -311,35 +328,86 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
     return commitTransition(projectRoot, change, changeRoot, {
         name: "review-ready", idempotencyInputs: { phase: "review-ready", risk },
         decide: (snapshot) => {
+            const events = readEvents(projectRoot, change);
+            const storedPolicy = readReviewPolicyFromEvents(events);
+            const policy = storedPolicy ?? reviewPolicyForRisk(risk);
+            const policyPayload = storedPolicy ? {} : { review_policy: policy };
+            const currentEvidenceDigest = reviewEvidenceDigest(events);
             // 检查是否所有任务已完成
             const pending = pendingTaskIds(changeRoot);
             if (pending.length > 0)
                 return { skip: true, message: formatPendingTaskMessage(pending, "请先通过 next/reopen 继续执行") };
             // 如果当前是 apply，先推进到 apply_done
             if (snapshot.state === "apply") {
-                return { fromState: "apply", toState: "apply_done", outcome: "advanced", reason: "所有任务完成" };
+                return {
+                    fromState: "apply", toState: "apply_done", outcome: "advanced",
+                    reason: `所有任务完成；审查策略=${policy.review_risk}`,
+                    commitPayload: policyPayload,
+                };
             }
-            if (snapshot.state === "apply_done") {
-                const isReviewReadyVerifier = (job) => job.role === "verifier" && job.created_from_transition === "review-ready";
+            if (snapshot.state === "apply_done" || snapshot.state === "review") {
                 const verifierOpen = snapshot.open_jobs.find(isReviewReadyVerifier);
                 if (verifierOpen)
                     return { skip: true, message: `有待完成的最终验证工作项 ${verifierOpen.job_id}` };
-                const verifierAccepted = snapshot.accepted_jobs.find(isReviewReadyVerifier);
-                // minimal 直接推进；normal/strict 需要 review-ready verifier
-                if (risk !== "minimal" && !verifierAccepted) {
-                    const docPaths = ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"];
-                    const boundFiles = docPaths.filter(p => existsSync(join(changeRoot, p))).map(p => ({ path: p, sha: sha256File(join(changeRoot, p)) ?? "sha256:missing" }));
+                const verifierAccepted = snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest));
+                if (!policy.requires_verifier) {
+                    if (snapshot.state === "apply_done") {
+                        return {
+                            fromState: "apply_done", toState: "review", outcome: "advanced",
+                            reason: `审查策略=${policy.review_risk}，无需最终验证，进入审查阶段`,
+                            commitPayload: policyPayload,
+                        };
+                    }
+                    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, packet_digest: sha256Text(JSON.stringify({ role: "verifier", boundFiles, created_from_transition: "review-ready" })),
+                        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: "apply_done", toState: "apply_done", outcome: "job_created",
-                        newJobs: [job], reason: "创建最终验证工作项",
+                        fromState: snapshot.state, toState: snapshot.state, outcome: "job_created",
+                        newJobs: [job],
+                        reason: previousVerifierRejected
+                            ? "此前 verifier 未通过；请先根据 findings 修改任务或文档，确认无需修改时再执行新的最终验证工作项"
+                            : "创建最终验证工作项",
+                        commitPayload: policyPayload,
+                        ...(previousVerifierRejected ? {
+                            details: { advisory: "此前 verifier 未通过；请先根据 findings 修改任务或文档，确认无需修改时再执行新的最终验证工作项" },
+                        } : {}),
                     };
                 }
-                return { fromState: "apply_done", toState: "review", outcome: "advanced", reason: "最终验证已接受，进入审查阶段" };
+                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",
+                        reason: `补写审查策略=${policy.review_risk}`,
+                        commitPayload: policyPayload,
+                    };
+                }
+                return { skip: true, message: "已在 review 状态，最终验证仍然有效" };
             }
             return { skip: true, message: `当前状态 ${snapshot.state}，review-ready 不适用` };
         },
@@ -355,6 +423,16 @@ export function accept(projectRoot, change, changeRoot) {
             const pending = pendingTaskIds(changeRoot);
             if (pending.length > 0)
                 return { skip: true, message: formatPendingTaskMessage(pending, "请先 reopen --to apply 继续执行") };
+            const events = readEvents(projectRoot, change);
+            const policy = readReviewPolicyFromEvents(events);
+            if (!policy)
+                return { skip: true, message: "缺少审查策略，请先运行 review-ready" };
+            if (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 { fromState: "review", toState: "accepted", outcome: "advanced", reason: "审查通过" };
         },
     });

package/dist/types.d.ts

@@ -11,6 +11,7 @@ export interface Job {
     role: JobRole;
     state: JobState;
     boundFiles: Ref[];
+    review_evidence_digest?: string;
     packet_digest: string;
     created_from_transition: string;
     created_at: string;
@@ -20,6 +21,7 @@ export interface JobPacket {
     role: JobRole;
     recommended_agent?: string;
     boundFiles: Ref[];
+    review_evidence_digest?: string;
     packet_digest: string;
     required_output_kind: string;
     output_contract_fields?: string[];
@@ -48,7 +50,12 @@ export interface TransitionCommitPayload {
     to_state: State;
     outcome: "advanced" | "job_created";
     created_job_ids: string[];
+    new_jobs?: Job[];
     reason: string;
+    review_policy?: {
+        review_risk: "minimal" | "normal" | "strict";
+        requires_verifier: boolean;
+    };
 }
 export interface Snapshot {
     change_id: string;

package/package.json

@@ -1,14 +1,25 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
-  "engines": { "node": ">=20.19.0" },
-  "bin": { "superspec": "dist/cli.js" },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "superspec": "dist/cli.js"
+  },
   "exports": {
-    ".": { "types": "./dist/types.d.ts", "default": "./dist/cli.js" }
+    ".": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/cli.js"
+    }
   },
-  "files": ["README.md", "dist", "templates"],
+  "files": [
+    "README.md",
+    "dist",
+    "templates"
+  ],
   "scripts": {
     "build": "node build.js",
     "typecheck": "tsc --noEmit",

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

@@ -21,12 +21,23 @@ metadata:
 
 next 返回需要 verifier 工作项时，先按返回的验证说明执行核对，再用 `superspec record job-submit --change "<change>" --job <JOB> --report <FILE>` 提交验证报告。
 
+`record job-submit` 沿用现有 raw 归档：报告追加到 `raw/review-reports.jsonl`，不会为 review gate 新增 raw 文件类型。
+
 ## 本阶段做什么
 
 1. **确认所有任务完成**：review-ready 会检查 tasks.md 无未完成项
 2. **处理 verifier**：核对 proposal + 实现 + 测试契约一致性
 3. **accept**：`superspec transition accept --change "<change>"`
 
+## verifier gate 规则
+
+- `review-ready` 首次运行会持久化审查策略；后续 risk 参数不会覆盖首次策略。
+- `minimal` 不要求 verifier；`normal` 和 `strict` 要求 verifier。
+- 当前 MVP 中 `strict` 等同 `normal`，不启用额外检查。
+- 如果 review 状态缺少审查策略，先运行 `review-ready` 补策略，不直接 accept。
+- verifier 工作项 packet 会包含绑定文档和 `review_evidence_digest`，用于确认审查对应的任务完成与 RED/GREEN 证据版本。
+- verifier 通过后，如果绑定文档或已登记执行证据版本变化，需要重新运行 `review-ready` 创建新的 verifier。
+
 ## Guardrails
 
 - 不改业务代码（审查阶段只读）