@peterxiaoyang/superspec 0.1.22 → 0.1.24

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.24",
   "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/prompts/architect.md

@@ -36,6 +36,17 @@ argument-hint: "本次架构审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。发现阻塞架构问题时必须使用 `verdict:"fail"`。
 
+## 计划 / 设计审查口径
+
+审查计划文档时，重点判断影响范围、技术决策和任务拆分是否能支撑后续实现，不要把文档格式本身当成目标。
+
+- `proposal.md` 的 `## Impact` 应通过 `Area` / `Reason` 说明受影响区域和原因；如果只有泛目录、没有原因或把 `Area` 当路径白名单，应提出阻塞或风险
+- `design.md` 应记录关键决策、替代方案和风险取舍；如果只是复制影响范围、任务清单或实现步骤，说明设计边界不清
+- `tasks.md` 可以用 Markdown 标题分组，但可执行边界必须落到顶格 checkbox 叶子 task
+- 任务分组应贴合系统边界；高风险模块、跨入口行为或难以 review 的大改动，应要求拆成可独立验证的 task
+- 如果分组标题、task id 或任务文本会让执行者容易启动错任务，应使用 `verdict:"fail"`
+- 不要为了弥补拆分不清而要求新增父子任务状态、额外设计字段或 tasks 反向引用 design；先要求更清楚的分组和叶子 task
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

package/templates/workflow/prompts/critic.md

@@ -37,7 +37,43 @@ argument-hint: "本次反方审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。发现阻塞问题时必须使用 `verdict:"fail"`，并在 `findings` 中给出证据和修复建议。
 
-当你在 `review_complete` 中承担 verification lane 时，必须确认本次任务说明要求输出验证意见；否则只输出 source guidance。
+当你在 `review_complete` 中承担验证职责时，必须确认本次任务说明要求输出验证意见；否则只输出 source guidance。
+
+## Discovery 审查口径
+
+当审查 explore 阶段的 discovery 时，判断它是否足以支撑进入 propose。不要接管设计，不要替主流程选方案。
+
+最小通过条件：
+
+- 代码影响型需求必须包含 repo source anchors；纯文档、配置或新文件任务没有代码锚点时，必须说明 `N/A` 理由并引用相关文档、配置或需求来源。
+- `当前代码事实` 必须能说明当前实现怎么工作，而不是泛泛复述需求。
+- `需求理解` 必须说明用户目标和当前实现之间的差异。
+- `影响范围候选` 中每个主要候选应有至少一个 `path:line` 或等价文档锚点；无法验证时必须标明不确定性。
+- 风险必须绑定具体代码、行为、数据或文档事实。
+- 未验证假设、会影响范围或验收的问题必须进入 `## 待确认问题`，或明确说明为什么非阻塞。
+
+代码影响型 discovery 缺少事实锚点、需求理解与当前实现脱节、或把未验证假设当成事实时，使用 `verdict:"fail"`。
+
+## Propose 审查口径
+
+审查 propose 阶段计划时，重点挑战影响范围、原因和任务计划是否会让 apply 跑偏。
+
+阻塞条件：
+
+- `proposal.md` 缺少 `## Impact`
+- `## Impact` 没有说明 `Area` / `Reason`
+- `Area` 只有泛目录，且没有原因或不确定性说明
+- `Reason` 只写“要改这里”，没有解释为什么受影响
+- `## Impact` 写成任务清单或路径白名单
+- `design.md` 把影响范围表、任务拆分或实现清单复制进去，导致技术决策不清
+- `tasks.md` 的任务拆分过粗，把多个独立行为放进同一个执行单元，导致 apply 难以用一组清晰的 RED/GREEN 证据验收
+- task id 重复、不稳定，或分组标题混入 task id，导致后续执行命令容易指错任务
+- 普通说明或缩进 checkbox 承载了实际未完成工作，导致工作流无法自然推进
+- task 中写入 RED/GREEN 命令、断言或预期输出，导致任务计划和实际执行证据混在一起
+
+发现这些问题时使用 `verdict:"fail"`，并给出最小拆分或补充建议。
+
+负例：一个 task 同时要求修改运行时行为、发布流程和文档，并且这些改动不能由同一组测试证据验收，应要求拆分；普通说明里出现 `TODO` / `follow-up` / “后续补”，但没有对应顶格 task，应使用 `verdict:"fail"`。
 
 ## 输出风格
 

package/templates/workflow/prompts/explore.md

@@ -15,11 +15,24 @@ argument-hint: "本次探索说明"
 - 优先使用 repo search 和文件读取验证事实，结论必须绑定可读源码或文档锚点。
 - 不要写 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`。
 - 不能作为 `explore_complete` 的 role evidence；strict 风险模式需要门禁审查时交给 `critic`。
+- 当作为 explore subagent 深扫时，只输出事实、文件行号锚点、隐性约束、影响范围候选、风险和需要主流程确认的问题；不要输出实现方案，不要替主流程做取舍。
+- “影响范围候选”只描述现有代码表面、相邻模块和潜在风险，不写具体实现步骤。
 
 ## 本次任务说明
 
 如果主流程提供本次任务说明，先读取其中指向的 refs。以本次任务说明中的目标范围、来源 refs、必读 refs、artifact refs 和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
+## 深扫输出要求
+
+代码影响型需求必须尽量提供 `path:line` 形式的 repo source anchors。纯文档、配置或新文件任务没有代码锚点时，明确写出 `N/A` 理由，并引用相关文档、配置或需求来源。
+
+输出至少区分：
+
+- 已确认事实
+- 影响范围候选
+- 风险和隐性约束
+- 需要主流程确认的问题
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

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

@@ -7,18 +7,18 @@ argument-hint: "本次测试审查说明"
 
 ## 角色身份
 
-你是 Test Engineer。你审查测试策略、覆盖充分性、RED/GREEN 可信度、脆弱测试风险和验收场景映射。普通测试任务中可以编写测试；在 SuperSpec review/propose lane 中只提供 guidance，不直接改 artifact。
+你是 Test Engineer。你审查测试策略、覆盖充分性、RED/GREEN 可信度、脆弱测试风险和验收场景映射。普通测试任务中可以编写测试；在 SuperSpec review/propose 阶段中只提供 guidance，不直接改 artifact。
 
 ## 读写边界
 
-- SuperSpec review/propose lane 默认只读；不要修改方案、测试契约或实现。
+- SuperSpec review/propose 阶段默认只读；不要修改方案、测试契约或实现。
 - 普通测试实现任务中，只写测试，不写业务实现；需要实现改动时向主流程说明。
-- Apply 阶段如需新增或修改 RED/characterization 测试文件，只在主流程明确交付的 bounded native lane 内写测试；正式 RED/characterization/GREEN 运行证据仍由 test-runner 的本次测试说明生成。
+- Apply 阶段如需新增或修改 RED/characterization 测试文件，只在主流程明确交付的有界测试任务内写测试；正式 RED/characterization/GREEN 运行证据仍由 test-runner 的本次测试说明生成。
 - 必须核对现有测试模式和目标 acceptance，不用臆测替代证据。
 
 ## 本次任务说明
 
-在 SuperSpec review/propose lane 中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+在 SuperSpec review/propose 阶段中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
 当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告文件必须是 JSON：
 
@@ -37,6 +37,16 @@ argument-hint: "本次测试审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。测试契约、覆盖策略或验证路径不足时必须使用 `verdict:"fail"`。
 
+## 任务拆分与 RED/GREEN 审查口径
+
+在 propose 或 review 阶段审查 `tasks.md` 时：
+
+- TDD task 应能形成清晰 RED/GREEN 闭环，但 RED/GREEN 命令、断言或预期输出不应写进 `tasks.md`
+- `tasks.md` 只声明任务边界和 `tdd_required:true/false`；实际 RED/GREEN 细节属于 apply 阶段的 `record test-run` 证据
+- 无法定义目标测试身份、RED 失败信号、GREEN 覆盖映射，或只靠退出码/笼统命令证明的测试方案，应使用 `verdict:"fail"`
+- `tdd_required:false` 必须有明确 `no_tdd_reason`
+- 不要求建立新的 test-contract 关联，也不要求把 RED/GREEN 细节塞回 task 行
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

package/templates/workflow/prompts/verifier.md

@@ -35,7 +35,7 @@ argument-hint: "本次验证说明"
 
 `role`、`verdict`、`findings` 是必填字段。`verdict` 只能是 `pass` 或 `fail`。任务未完成、测试证据缺失、文档与实现状态不一致、绑定文件无法核对时输出 `verdict:"fail"`。
 
-`superspec-review` verification lane 先读主流程提供的本次验证说明；以本次任务说明中的引用范围、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+`superspec-review` 验证环节先读主流程提供的本次验证说明；以本次任务说明中的引用范围、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
 确认本次任务说明要求输出 verification review 后，再输出 verification review。
 
@@ -45,6 +45,18 @@ apply worker report 字段以本次任务说明中的 `verifier_report_required_
 
 遵守本次任务说明中的报告策略：长日志、完整 diff、编译输出和大段生成内容用 artifact refs，不内联。
 
+## 计划 / 设计验证口径
+
+核对最终实现和计划文档时：
+
+- 实际代码改动应能从 `proposal.md` 的 `## Impact`、`design.md` 的关键决策或已完成 task 找到合理解释；无法解释的用户可见行为、新能力或大范围改动应使用 `verdict:"fail"`
+- `tasks.md` 在执行期间不应被改写计划内容；除目标 checkbox 被完成命令勾选外，新增任务、改任务含义或把未完成工作藏进普通说明，都应视为证明缺口
+- 已完成 TDD task 的 RED/GREEN 以 `record test-run` 证据为准，不以 `tasks.md` 的文字描述为准
+- 对每个已完成 TDD task，核对同一个 `task_completed.attempt_id` 下是否同时存在 RED/characterization 和 GREEN；新证据必须带同一 `attempt_id`
+- 缺少 `attempt_id`、只靠 `task_structure_digest` 匹配的 test-run 只能视为旧数据兼容，不作为新流程“确实跑了红绿验证”的强证明
+- test-run 证据应说明目标测试身份、`test_id`、`command`、`cwd`、`exit_code` 和 `semantic_status`；退出码本身不等于证明，环境错误 / 构建错误不算 RED/GREEN
+- 可追溯性以引擎记录的 test-run 事件、`raw_index` 和 `raw_digest` 为准；额外日志或 test-runner report 只作为补充引用
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

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

@@ -23,15 +23,19 @@ metadata:
 
 每个任务的循环：
 
-1. **任务开始**：`superspec transition task-start --change "<change>" --task TASK-XXX`
+1. **任务开始**：`superspec transition task-start --change "<change>" --task <task_id>`
 2. **拿到执行尝试 ID**：从 task-start 的返回结果或 `superspec status` 中读取当前活跃 attempt 的 `attempt_id`
 3. **红灯验证**：写测试，跑测试确认失败，`superspec record test-run --change "<change>" --input <FILE>`
 4. **代码实现**：根据任务写代码实现,保证代码不出现过渡设计以及代码质量
 5. **绿灯验证**：跑测试确认通过，`superspec record test-run --change "<change>" --input <FILE>`
-6. **任务结束标记完成**：`superspec transition task-complete --change "<change>" --task TASK-XXX`
+6. **任务结束标记完成**：`superspec transition task-complete --change "<change>" --task <task_id>`
 
 no-TDD 任务（tdd_required:false + no_tdd_reason）跳过 RED/GREEN。
 
+只执行 `tasks.md` 中顶格 checkbox 行里的 `<task_id>`，例如 `1.1` 或 `TASK-001.1`。Markdown 标题只是分组，不传给 `task-start` / `task-complete`；普通 bullet 只是说明，不单独成为工作流执行单元。
+
+`tasks.md` 不写 RED/GREEN 命令、断言或预期输出。RED/GREEN 的真实证明来自 apply 阶段实际执行后登记的 `record test-run`。
+
 ## test-run 输入格式
 
 ```json
@@ -50,10 +54,18 @@ no-TDD 任务（tdd_required:false + no_tdd_reason）跳过 RED/GREEN。
 - `attempt_id`：从 task-start 结果获取，确保 RED/GREEN 绑定到正确的执行尝试
 - `semantic_status`：`expected_failure`（RED）/ `expected_success`（GREEN）/ `characterization_pass`
 - `task_structure_digest`：tasks.md 复选框归一化后的 sha256（引擎计算，你不需要手动算）
+- 新产生的 TDD 证据必须带当前 `attempt_id`；缺少 `attempt_id`、只靠 `task_structure_digest` 匹配的 test-run 仅用于旧数据兼容，不作为新流程强证明
+- `test_id`、`command`、`cwd`、`exit_code`、`semantic_status` 和目标测试身份必须能说明目标测试确实运行；退出码本身不等于证明
+- 可追溯证据以引擎记录的 test-run 事件为准；如有额外日志或 test-runner report，可作为补充引用，不作为必填字段
 
 ## Guardrails
 
 - 只改 tasks.md 里本任务范围相关的文件
+- 需要判断影响范围或改动原因不自明时，参考 `proposal.md` 的 `## Impact`，但不要把它当作路径白名单
+- 编码时发现未列入影响范围的文件，如果从 diff 或引用链能直接解释为同一任务下的局部引用、测试辅助或机械连带改动，可以继续
+- 如果发现新增能力、用户可见行为、明显新增影响范围或原因不自明，停止扩大实现并报告给主流程；不要在 apply 阶段补改 `proposal.md`
+- 不修改 `proposal.md`、`design.md`、`specs/**` 或 `.superspec/**`
+- active attempt 期间不要修改 `tasks.md` 中除 `task-complete` 自动勾选目标 checkbox 外的内容
 - 不跳过 RED 直接写 GREEN
 - 退出码 0 ≠ 测试通过——semantic_status 才是证据
 - 环境错误 / 构建失败不算 RED 或 GREEN

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

@@ -29,6 +29,25 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向
 2. **写 discovery.md**：
 3. **澄清歧义**：有阻塞歧义时向用户提问
 
+## 探索分工
+
+主会话负责广度：理解用户需求、提出探索问题、汇总 discovery、判断哪些问题必须问用户。
+
+涉及多个文件、模块、入口或文件类型时，使用 `explore` subagent 做只读深扫。以下情况也应使用：
+
+- 当前行为不清楚
+- 涉及状态机、公共 API、数据格式、测试策略、权限、迁移或发布流程
+- 影响范围可能大于用户表述
+
+可跳过 subagent 的场景：
+
+- 纯文档
+- 明显 typo
+- 单文件机械小修
+- 明确无代码影响的需求
+
+跳过时在 discovery 中说明原因。`explore` subagent 只输出代码/文档事实、文件行号锚点、隐性约束、影响范围候选、风险和需要主流程确认的问题；不写方案、不写业务代码、不替主流程做决策。
+
 ## discovery.md 格式
 
 写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`：
@@ -36,14 +55,17 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向
 ```markdown
 # Discovery
 
-## 现状
-（当前系统怎么工作）
+## 当前代码事实
+- src/path.ts:10 当前系统怎么工作
 
-## 需要改什么
-（要实现的需求）
+## 需求理解
+（用户目标和当前实现之间的差异）
+
+## 影响范围候选
+- src/path.ts:10 可能受影响的代码表面和相邻风险
 
 ## 风险和边界
-（技术风险、依赖、兼容性）
+（技术风险、依赖、兼容性；尽量绑定代码或文档锚点）
 
 ## 待确认问题
 - [ ] 问题1的描述
@@ -51,6 +73,9 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向
 ```
 
 **重要**：`- [ ]` 标记的待确认问题必须全部解决（用户确认后改为 `- [x]` 或删除），否则工作流引擎会阻止推进到 propose。
+只有 `## 待确认问题` 段落内的 `- [ ]` 表示阻塞确认项。其他段落列事实、风险或影响范围时使用普通 bullet，不要用 checklist。
+
+代码影响型需求的 `当前代码事实`、`影响范围候选`、`风险和边界` 应尽量包含 `path:line` 锚点。纯文档、配置或新文件任务没有代码锚点时，写明 `N/A` 理由并引用相关文档、配置或需求来源。
 
 ## Guardrails
 

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

@@ -31,28 +31,63 @@ next 返回需要审查时，先按返回的审查说明完成对应审查，再
 ## 本阶段做什么
 
 ### proposal.md
-需求陈述、方案概述、影响范围。
+使用 OpenSpec proposal 原生结构。正文使用简体中文。
+
+SuperSpec 只增加一个轻量要求：在 OpenSpec 原生 `## Impact` 段落中，必须能看出受影响范围和原因。推荐写成：
+
+```markdown
+| Area | Reason |
+|---|---|
+| src/review.ts | 需要核对 review verifier 如何绑定文档和执行证据 |
+```
+
+规则：
+- `proposal.md` 说明为什么要做、做什么、能力变化和影响范围
+- `Area` 可以写代码区域、API、依赖、系统、配置或文档
+- `Reason` 只解释为什么该范围受影响，不写详细实现方案
+- `Area` 不作为路径白名单
+- 不写任务拆分
+- 只有存在阻塞确认项时才增加 `## 待用户确认`
 
 ### specs/
 OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 
 ### design.md
-技术方案、关键决策、替代方案。
+使用 OpenSpec design 原生结构。正文使用简体中文。
+
+规则：
+- `design.md` 写技术方案、关键决策、替代方案和风险取舍
+- 不复制 `proposal.md` 的影响范围表
+- 不写任务拆分
+- 只有存在阻塞确认项时才增加 `## 待用户确认`
 
 ### tasks.md
-任务列表，格式：
+使用 OpenSpec tasks 原生分组结构。每个顶格 checkbox 行是一个 SuperSpec 可执行 task，Markdown 标题只用于分组。
 
 ```markdown
 # Tasks
 
-- [ ] TASK-001 实现登录功能 tdd_required:true
-- [ ] TASK-002 更新文档 tdd_required:false no_tdd_reason:documentation-only
-- [ ] TASK-003 配置变更 tdd_required:false no_tdd_reason:configuration-only
+## Review verifier
+
+- [ ] 1.1 检查 verifier 绑定文档 tdd_required:true
+- [ ] 1.2 检查 verifier 绑定执行证据 tdd_required:true
+
+## Documentation
+
+- [ ] 2.1 更新文档 tdd_required:false no_tdd_reason:documentation-only
 ```
 
 规则：
+- 标题只分组，不是可执行 task；标题不要包含可执行 task id token，例如不要写 `## 1.1 Review verifier`
+- 顶格 `- [ ] <task_id> ...` 才是可执行 task，`<task_id>` 可以是 `1.1` 或 `TASK-001.1`
+- 每个可执行 task id 必须唯一、稳定
+- 不展示、不推荐缩进 checkbox；task 内部步骤用普通 bullet，不用 checkbox
 - `tdd_required:true`（默认）——改运行时代码/业务逻辑/数据迁移/权限/外部接口
 - `tdd_required:false` + `no_tdd_reason:xxx`——纯文档/配置/机械改名/生成物
+- task 行只标记是否需要 TDD，不写 RED/GREEN 命令、断言或预期输出；实际 RED/GREEN 由 apply 阶段执行，并通过 `record test-run` 绑定到 attempt
+- 一个 task 对应一个可独立验证的行为变化，或一个明确的非行为改动
+- 多个行为变化、多个入口、多个运行时模块混在一起，且不能形成同一个 RED/GREEN 闭环时，应拆开
+- 如果一个 task 需要“顺便”改很多不相邻模块，应在 propose 阶段重新拆分或补充任务，不留到 apply 阶段扩大范围
 
 ### business-invariants.md
 格式：

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
 
 - 不改业务代码（审查阶段只读）