@peterxiaoyang/superspec 0.1.14 → 0.1.15-alpha

package/dist/sync.js

@@ -0,0 +1,135 @@
+// 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";
+const TRACKED_DOCS = [
+    "proposal.md", "design.md", "tasks.md",
+    ".superspec/artifacts/discovery.md",
+    ".superspec/artifacts/business-invariants.md",
+    ".superspec/artifacts/test-contract.md",
+];
+/** 从 events.jsonl 推导：当前状态、jobs、attempts、pending decisions */
+function replayEvents(events) {
+    let state = "init";
+    const openJobs = [];
+    const acceptedJobs = [];
+    const activeAttempts = [];
+    const taskStatuses = {};
+    let lastTransition = null;
+    for (const ev of events) {
+        switch (ev.event_type) {
+            case "transition_commit": {
+                const p = ev.payload;
+                state = p.to_state;
+                if (ev.transition_id)
+                    lastTransition = ev.transition_id;
+                // HIGH 6 修复：从 commit payload replay job
+                const created = ev.payload.created_job_ids ?? [];
+                const payloadJobs = ev.payload.new_jobs ?? [];
+                for (const jid of created) {
+                    const job = payloadJobs.find(j => j.job_id === jid);
+                    if (job && !openJobs.some(j => j.job_id === jid))
+                        openJobs.push(job);
+                }
+                break;
+            }
+            // H4 修复：删除 job_requested / job_invalidated 死分支——job 只通过 transition_commit 的 new_jobs payload 创建，staleness 只在 sync 内存计算（不写事件）
+            case "job_accepted": {
+                const { job_id } = ev.payload;
+                const idx = openJobs.findIndex(j => j.job_id === job_id);
+                if (idx >= 0) {
+                    const job = openJobs.splice(idx, 1)[0];
+                    job.state = "accepted";
+                    acceptedJobs.push(job);
+                }
+                break;
+            }
+            case "job_rejected": {
+                const { job_id } = ev.payload;
+                const idx = openJobs.findIndex(j => j.job_id === job_id);
+                if (idx >= 0) {
+                    openJobs.splice(idx, 1)[0]; // remove from open
+                }
+                break;
+            }
+            // H4：job_invalidated 事件从不发射（删除死分支）
+            case "task_started": {
+                const attempt = ev.payload;
+                activeAttempts.push(attempt);
+                taskStatuses[attempt.task_id] = "doing";
+                break;
+            }
+            case "task_completed": {
+                const { task_id, attempt_id } = ev.payload;
+                const idx = activeAttempts.findIndex(a => a.attempt_id === attempt_id);
+                if (idx >= 0)
+                    activeAttempts[idx].state = "closed";
+                taskStatuses[task_id] = "done";
+                break;
+            }
+            case "task_abandoned": {
+                const { attempt_id } = ev.payload;
+                const idx = activeAttempts.findIndex(a => a.attempt_id === attempt_id);
+                if (idx >= 0)
+                    activeAttempts.splice(idx, 1);
+                break;
+            }
+        }
+    }
+    return { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition };
+}
+/** 粗粒度失效：检查 accepted job 的 boundFiles 是否仍匹配当前文档 */
+function checkStaleJobs(acceptedJobs, documentDigests) {
+    const stale = [];
+    for (const job of acceptedJobs) {
+        for (const bf of job.boundFiles) {
+            const current = documentDigests[bf.path];
+            if (current && current !== bf.sha) {
+                stale.push({
+                    job_id: job.job_id,
+                    reason: `绑定文件 ${bf.path} 已变化（${bf.sha} → ${current}）`,
+                });
+                break; // 一个文件变就够了
+            }
+        }
+    }
+    return stale;
+}
+/** 解析 tasks.md 结构指纹（复选框归一化） */
+function tasksStructureDigest(changeRoot) {
+    const tasksPath = join(changeRoot, "tasks.md");
+    if (!existsSync(tasksPath))
+        return null;
+    const content = readFileSync(tasksPath, "utf8");
+    // 复选框归一化：- [x] → - [ ]
+    const normalized = content.replace(/- \[[xX]\]/g, "- [ ]");
+    return sha256Text(normalized);
+}
+/** 重建 snapshot（sync 的核心） */
+export function rebuildSnapshot(projectRoot, change, changeRoot, openspecStatusDigest = "sha256:unknown") {
+    ensureChangeLayout(projectRoot, change);
+    const events = readEvents(projectRoot, change);
+    const evDigest = eventsDigest(events);
+    const documentDigests = computeDocumentDigests(changeRoot, TRACKED_DOCS);
+    const tsDigest = tasksStructureDigest(changeRoot);
+    const { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition } = replayEvents(events);
+    // 粗粒度失效检查（只读，不写事件）
+    const staleInfo = checkStaleJobs(acceptedJobs, documentDigests);
+    // stale 的 job 从 accepted 移除（sync 只反映当前事实）
+    const freshAccepted = acceptedJobs.filter(j => !staleInfo.some(s => s.job_id === j.job_id));
+    return {
+        change_id: change,
+        state,
+        openspec_status_digest: openspecStatusDigest,
+        events_digest: evDigest,
+        document_digests: documentDigests,
+        tasks_structure_digest: tsDigest,
+        task_statuses: taskStatuses,
+        open_jobs: openJobs,
+        accepted_jobs: freshAccepted,
+        active_task_attempts: activeAttempts,
+        pending_user_decisions: [],
+        last_transition: lastTransition,
+        computed_at: new Date().toISOString(),
+    };
+}

package/dist/task.d.ts

@@ -0,0 +1,7 @@
+/** tasks.md 结构指纹（委托给 format.ts 统一实现） */
+export declare function tasksStructureDigestOf(changeRoot: string): string | null;
+/** record test-run：登记测试运行记录 */
+export declare function recordTestRun(projectRoot: string, change: string, inputFile: string): {
+    accepted: boolean;
+    message: string;
+};

package/dist/task.js

@@ -0,0 +1,44 @@
+// SuperSpec 流程引擎 — task：测试运行记录 + 任务结构指纹工具
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock } from "./store.js";
+import { tasksStructureDigest as formatDigest } from "./format.js";
+/** tasks.md 结构指纹（委托给 format.ts 统一实现） */
+export function tasksStructureDigestOf(changeRoot) {
+    const p = join(changeRoot, "tasks.md");
+    if (!existsSync(p))
+        return null;
+    const content = readFileSync(p, "utf8");
+    return formatDigest(content, sha256Text);
+}
+/** record test-run：登记测试运行记录 */
+export function recordTestRun(projectRoot, change, inputFile) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        if (!existsSync(inputFile))
+            return { accepted: false, message: `文件不存在：${inputFile}` };
+        let tr;
+        try {
+            tr = JSON.parse(readFileSync(inputFile, "utf8"));
+        }
+        catch {
+            return { accepted: false, message: "无效 JSON" };
+        }
+        if (!tr.test_id || !tr.task_structure_digest) {
+            return { accepted: false, message: "缺少 test_id 或 task_structure_digest" };
+        }
+        const event = makeEvent(change, "test_run_recorded", {
+            test_id: tr.test_id,
+            task_structure_digest: tr.task_structure_digest,
+            attempt_id: tr.attempt_id ?? null,
+            command: tr.command ?? "",
+            cwd: tr.cwd ?? "",
+            exit_code: tr.exit_code ?? -1,
+            semantic_status: tr.semantic_status ?? "unknown",
+            target_fingerprint: tr.target_fingerprint ?? null,
+            raw_log_ref: tr.raw_log_ref ?? null,
+        });
+        appendEvent(projectRoot, change, event);
+        return { accepted: true, message: `测试运行已登记：test_id=${tr.test_id}` };
+    });
+}

package/dist/transition.d.ts

@@ -0,0 +1,34 @@
+import type { Snapshot, State, Job, TransitionResult } from "./types.ts";
+interface Decision {
+    fromState: State;
+    toState: State;
+    outcome: "advanced" | "job_created";
+    newJobs?: Job[];
+    reason: string;
+    extraEvents?: {
+        type: string;
+        payload: Record<string, unknown>;
+    }[];
+    postCommit?: (projectRoot: string, change: string, changeRoot: string) => void;
+}
+/**
+ * 统一 transition 提交协议——所有校验在锁内。
+ */
+export declare function commitTransition(projectRoot: string, change: string, changeRoot: string, opts: {
+    name: string;
+    decide: (snapshot: Snapshot) => Decision | {
+        skip: true;
+        message: string;
+    };
+    idempotencyInputs?: Record<string, unknown>;
+}): TransitionResult;
+export declare function proposeReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
+export declare function transitionInit(projectRoot: string, change: string, changeRoot: string): TransitionResult;
+export declare function transitionExplore(projectRoot: string, change: string, changeRoot: string): 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 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;
+export declare function taskComplete(projectRoot: string, change: string, changeRoot: string, taskId: string): TransitionResult;
+export {};

package/dist/transition.js

@@ -0,0 +1,400 @@
+// 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 { rebuildSnapshot } from "./sync.js";
+import { validateDiscovery, findTaskInLines, parseTasksMd, tasksStructureDigest } from "./format.js";
+let transitionSeq = 0;
+function newTransitionId() { return `T-${Date.now()}-${++transitionSeq}`; }
+let jobSeq = 0;
+function newJobId(change, role) { return `JOB-${change.slice(0, 8)}-${role.slice(0, 4)}-${Date.now()}-${++jobSeq}`; }
+const TRANSITION_REQUIREMENTS = {
+    "propose-ready": {
+        minimal: [],
+        normal: ["proposal-auditor"],
+        strict: ["critic-review", "architect-review", "test-engineer-review"],
+    },
+    "explore": {
+        minimal: [],
+        normal: [],
+        strict: ["clarification-review"],
+    },
+};
+/**
+ * 通用 job 检查/创建逻辑——任何 transition 都能调用。
+ * 检查 requiredRoles 是否有 fresh accepted job；缺则创建新 job。
+ * 返回 null = 全部满足；返回 Decision = 需要创建 job（状态不变）。
+ */
+function checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, transitionName, bindDocPaths) {
+    const staleRoles = [];
+    for (const role of requiredRoles) {
+        const openForRole = snapshot.open_jobs.find(j => j.role === role);
+        if (openForRole)
+            return { fromState: snapshot.state, toState: snapshot.state, outcome: "advanced", reason: `工作项 ${role} 已存在（${openForRole.job_id}），请先完成它` };
+        const fresh = snapshot.accepted_jobs.find(j => j.role === role);
+        if (!fresh) {
+            staleRoles.push({ role, reason: `需求 ${role} 无已接受的工作项` });
+        }
+        else {
+            for (const bf of fresh.boundFiles) {
+                const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
+                if (currentSha !== bf.sha) {
+                    staleRoles.push({ role, reason: `${role} 绑定文件 ${bf.path} 已变化` });
+                    break;
+                }
+            }
+        }
+    }
+    if (staleRoles.length > 0) {
+        const newJobs = staleRoles.map(({ role }) => {
+            const boundFiles = bindDocPaths.filter(p => existsSync(join(changeRoot, p))).map(p => ({ path: p, sha: sha256File(join(changeRoot, p)) ?? "sha256:missing" }));
+            return { job_id: newJobId(change, role), role, state: "requested", boundFiles, packet_digest: sha256Text(JSON.stringify({ role, boundFiles })), created_from_transition: transitionName, created_at: new Date().toISOString() };
+        });
+        return {
+            fromState: snapshot.state, toState: snapshot.state, outcome: "job_created",
+            newJobs, reason: staleRoles.map(s => s.reason).join("; "),
+        };
+    }
+    return null; // 全部满足
+}
+/**
+ * 已迁移到 format.ts：findTaskInLines / parseTasksMd / tasksStructureDigest
+ * 以下保留 findTaskLine 作为兼容 wrapper（内部调用 format.ts）
+ */
+function findTaskLine(lines, taskId) {
+    return findTaskInLines(lines, taskId);
+}
+/**
+ * 统一 transition 提交协议——所有校验在锁内。
+ */
+export function commitTransition(projectRoot, change, changeRoot, opts) {
+    const { name } = opts;
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
+        const worldDigest = snapshotDigest(snapshot);
+        const idemKey = idempotencyKey(name, opts.idempotencyInputs ?? {}, worldDigest);
+        const events = readEvents(projectRoot, change);
+        const existing = events.find(e => e.idempotency_key === idemKey && e.event_type === "transition_commit");
+        if (existing) {
+            const p = existing.payload;
+            return {
+                transition: name, outcome: p.outcome,
+                from_state: p.from_state, to_state: p.to_state,
+                created_jobs: p.created_job_ids ?? [], message: "幂等返回", events_written: 0,
+            };
+        }
+        const decision = opts.decide(snapshot);
+        if ("skip" in decision) {
+            return {
+                transition: name, outcome: "advanced",
+                from_state: snapshot.state, to_state: snapshot.state,
+                created_jobs: [], message: decision.message, events_written: 0,
+            };
+        }
+        const { fromState, toState, outcome, newJobs = [], reason, extraEvents = [] } = decision;
+        if (fromState !== snapshot.state) {
+            return {
+                transition: name, outcome: "advanced",
+                from_state: snapshot.state, to_state: snapshot.state,
+                created_jobs: [], message: `from_state 不匹配：期望 ${fromState}，实际 ${snapshot.state}`,
+                events_written: 0,
+            };
+        }
+        const transitionId = newTransitionId();
+        // prepare
+        appendEvent(projectRoot, change, makeEvent(change, "transition_prepare", {
+            transition: name, transition_id: transitionId, from_state: fromState, to_state: toState, reason,
+        }, { transitionId, idempotencyKey: idemKey, prevSnapshotDigest: worldDigest }));
+        // BLOCKER-1 修复：postCommit 在 commit 写入前执行。
+        // 如果 postCommit 抛错 → 只有 prepare（无 commit）→ 幂等重试会跳过 prepare 重新执行。
+        // 如果 postCommit 成功 → commit + extraEvents 写入 → 一致。
+        if (decision.postCommit) {
+            decision.postCommit(projectRoot, change, changeRoot);
+        }
+        // commit（postCommit 成功后才写）
+        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,
+        }, { transitionId, idempotencyKey: idemKey, prevSnapshotDigest: worldDigest }));
+        // extra events (task_started, task_completed, etc.)
+        for (const ex of extraEvents) {
+            appendEvent(projectRoot, change, makeEvent(change, ex.type, ex.payload, { transitionId }));
+        }
+        writeSnapshot(projectRoot, change, rebuildSnapshot(projectRoot, change, changeRoot));
+        return {
+            transition: name, outcome, from_state: fromState, to_state: toState,
+            created_jobs: newJobs.map(j => j.job_id),
+            message: outcome === "advanced" ? `状态推进：${fromState} → ${toState}` : `状态不变（${fromState}），创建了 ${newJobs.length} 个工作项`,
+            events_written: 1 + extraEvents.length,
+        };
+    });
+}
+// ===== propose-ready =====
+export function proposeReady(projectRoot, change, changeRoot, risk = "normal") {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "propose-ready", idempotencyInputs: { risk },
+        decide: (snapshot) => {
+            if (snapshot.state !== "propose")
+                return { skip: true, message: `当前状态 ${snapshot.state}，不能 propose-ready` };
+            const tasksPath = join(changeRoot, "tasks.md");
+            if (!existsSync(tasksPath))
+                return { skip: true, message: "tasks.md 不存在" };
+            const tasksContent = readFileSync(tasksPath, "utf8");
+            if (!tasksContent.includes("# Tasks") && !tasksContent.includes("- [ ]"))
+                return { skip: true, message: "tasks.md 内容不像任务计划文档" };
+            if (risk !== "minimal") {
+                const artifactsDir = join(changeRoot, ".superspec", "artifacts");
+                for (const doc of ["discovery.md", "business-invariants.md", "test-contract.md"]) {
+                    if (!existsSync(join(artifactsDir, doc)))
+                        return { skip: true, message: `基础职责缺失：${doc} 不存在（risk=${risk} 需要）` };
+                }
+            }
+            // 通用 job 检查（用提取的 helper）
+            const requiredRoles = TRANSITION_REQUIREMENTS["propose-ready"]?.[risk] ?? [];
+            const reviewResult = checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, "propose-ready", ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"]);
+            if (reviewResult)
+                return reviewResult;
+            return { fromState: "propose", toState: "propose_ready", outcome: "advanced", reason: `risk=${risk}，所有需求已满足` };
+        },
+    });
+}
+// ===== init =====
+export function transitionInit(projectRoot, change, changeRoot) {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "init", idempotencyInputs: { phase: "init" },
+        decide: () => {
+            const events = readEvents(projectRoot, change);
+            if (events.length > 0)
+                return { skip: true, message: "change 已初始化" };
+            return { fromState: "init", toState: "init", outcome: "advanced", reason: "引擎初始化" };
+        },
+    });
+}
+// ===== explore =====
+export function transitionExplore(projectRoot, change, changeRoot) {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "explore", idempotencyInputs: { phase: "explore" },
+        decide: (snapshot) => {
+            if (snapshot.state === "init")
+                return { fromState: "init", toState: "explore", outcome: "advanced", reason: "进入探索阶段" };
+            if (snapshot.state === "explore") {
+                const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
+                if (!existsSync(discoveryPath))
+                    return { skip: true, message: "discovery.md 不存在" };
+                // explore→propose：校验 discovery + 通用 job 审查（normal+ 需 clarification-review）
+                const discoveryCheck = validateDiscovery(changeRoot);
+                if (!discoveryCheck.ok)
+                    return { skip: true, message: discoveryCheck.message };
+                // 通用 job 审查（和 propose-ready 同一个 helper）
+                const requiredRoles = TRANSITION_REQUIREMENTS["explore"]?.["normal"] ?? [];
+                const reviewResult = checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, "explore", [".superspec/artifacts/discovery.md"]);
+                if (reviewResult)
+                    return reviewResult;
+                return { fromState: "explore", toState: "propose", outcome: "advanced", reason: "探索完成" };
+            }
+            return { skip: true, message: `当前状态 ${snapshot.state}，explore 不适用` };
+        },
+    });
+}
+// ===== start-apply =====
+export function startApply(projectRoot, change, changeRoot) {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "start-apply", idempotencyInputs: { phase: "start-apply" },
+        decide: (snapshot) => {
+            if (snapshot.state !== "propose_ready")
+                return { skip: true, message: `当前状态 ${snapshot.state}，需要 propose_ready` };
+            return { fromState: "propose_ready", toState: "apply", outcome: "advanced", reason: "进入执行阶段" };
+        },
+    });
+}
+// ===== task-start =====
+let attemptSeq = 0;
+export function taskStart(projectRoot, change, changeRoot, taskId) {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "task-start", idempotencyInputs: { task: taskId },
+        decide: (snapshot) => {
+            if (snapshot.state !== "apply")
+                return { skip: true, message: `当前状态 ${snapshot.state}，需要 apply` };
+            const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+            const lines = tasksContent.split("\n");
+            const taskLineIdx = findTaskLine(lines, taskId);
+            if (taskLineIdx < 0)
+                return { skip: true, message: `任务 ${taskId} 不存在` };
+            if (lines[taskLineIdx].match(/- \[x\]/))
+                return { skip: true, message: `任务 ${taskId} 已完成` };
+            const existing = snapshot.active_task_attempts?.find(a => a.task_id === taskId && a.state === "active");
+            if (existing)
+                return { skip: true, message: `任务 ${taskId} 已有活跃尝试` };
+            const structureDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
+            const attempt = {
+                attempt_id: `ATT-${taskId}-${Date.now()}-${++attemptSeq}`,
+                task_id: taskId, state: "active",
+                task_structure_digest: structureDigest,
+                declared_write_scope: [], pre_edit_source_fingerprint: null,
+                pre_edit_red_ref: null, executor_packet_digest: null,
+                executor_result_ref: null, post_edit_green_ref: null,
+                created_at: new Date().toISOString(),
+            };
+            return {
+                fromState: "apply", toState: "apply", outcome: "advanced",
+                reason: `创建任务 ${taskId} 执行尝试`,
+                extraEvents: [{ type: "task_started", payload: attempt }],
+            };
+        },
+    });
+}
+// ===== review-ready =====
+export function reviewReady(projectRoot, change, changeRoot, risk = "normal") {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "review-ready", idempotencyInputs: { phase: "review-ready", risk },
+        decide: (snapshot) => {
+            // 检查是否所有任务已完成
+            const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+            const allDone = !tasksContent.split("\n").some(l => l.includes("- [ ]"));
+            if (!allDone)
+                return { skip: true, message: "尚有未完成任务" };
+            // 如果当前是 apply，先推进到 apply_done
+            if (snapshot.state === "apply") {
+                return { fromState: "apply", toState: "apply_done", outcome: "advanced", reason: "所有任务完成" };
+            }
+            if (snapshot.state === "apply_done") {
+                // 检查是否有 final-audit job 需求
+                const finalAuditOpen = snapshot.open_jobs.find(j => j.role === "final-audit");
+                if (finalAuditOpen)
+                    return { skip: true, message: `有待完成的最终审查工作项 ${finalAuditOpen.job_id}` };
+                const finalAuditAccepted = snapshot.accepted_jobs.find(j => j.role === "final-audit");
+                // minimal 直接推进；normal/strict 需要 final-audit
+                if (risk !== "minimal" && !finalAuditAccepted) {
+                    // 创建 final-audit job
+                    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 job = {
+                        job_id: newJobId(change, "final-audit"), role: "final-audit", state: "requested",
+                        boundFiles, packet_digest: sha256Text(JSON.stringify({ role: "final-audit", boundFiles })),
+                        created_from_transition: "review-ready", created_at: new Date().toISOString(),
+                    };
+                    return {
+                        fromState: "apply_done", toState: "apply_done", outcome: "job_created",
+                        newJobs: [job], reason: "创建最终审查工作项",
+                    };
+                }
+                return { fromState: "apply_done", toState: "review", outcome: "advanced", reason: "最终审查已接受，进入审查阶段" };
+            }
+            return { skip: true, message: `当前状态 ${snapshot.state}，review-ready 不适用` };
+        },
+    });
+}
+// ===== accept =====
+export function accept(projectRoot, change, changeRoot) {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "accept", idempotencyInputs: { phase: "accept" },
+        decide: (snapshot) => {
+            if (snapshot.state !== "review")
+                return { skip: true, message: `当前状态 ${snapshot.state}，需要 review` };
+            return { fromState: "review", toState: "accepted", outcome: "advanced", reason: "审查通过" };
+        },
+    });
+}
+// ===== archive =====
+export function archive(projectRoot, change, changeRoot) {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "archive", idempotencyInputs: { phase: "archive" },
+        decide: (snapshot) => {
+            if (snapshot.state !== "accepted")
+                return { skip: true, message: `当前状态 ${snapshot.state}，需要 accepted` };
+            // 构建保全清单（Phase 4 简化版：记录文档指纹 + specs/）
+            const manifest = {};
+            const docPaths = ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"];
+            for (const p of docPaths) {
+                manifest[p] = sha256File(join(changeRoot, p)) ?? "sha256:missing";
+            }
+            // specs/ 目录
+            const specsDir = join(changeRoot, "specs");
+            if (existsSync(specsDir)) {
+                for (const f of readdirSync(specsDir)) {
+                    if (f.endsWith(".md"))
+                        manifest[`specs/${f}`] = sha256File(join(specsDir, f)) ?? "sha256:missing";
+                }
+            }
+            return {
+                fromState: "accepted", toState: "archive", outcome: "advanced",
+                reason: "归档完成",
+                extraEvents: [{ type: "artifact_recorded", payload: { kind: "archive_preservation_manifest", manifest } }],
+            };
+        },
+    });
+}
+// ===== task-complete =====
+export function taskComplete(projectRoot, change, changeRoot, taskId) {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "task-complete", idempotencyInputs: { task: taskId, phase: "complete" },
+        decide: (snapshot) => {
+            if (snapshot.state !== "apply")
+                return { skip: true, message: `当前状态 ${snapshot.state}，需要 apply` };
+            const attempt = snapshot.active_task_attempts?.find(a => a.task_id === taskId && a.state === "active");
+            if (!attempt)
+                return { skip: true, message: `任务 ${taskId} 无活跃执行尝试` };
+            const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+            const currentDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
+            if (currentDigest !== attempt.task_structure_digest)
+                return { skip: true, message: "任务结构指纹不匹配" };
+            // 解析任务属性（委托给 format.ts 的 parseTasksMd）
+            const tasks = parseTasksMd(tasksContent);
+            const taskInfo = tasks.find(t => t.taskId === taskId);
+            const isTdd = taskInfo?.tddRequired ?? true;
+            const hasNoTddReason = taskInfo?.noTddReason != null;
+            // RED/GREEN 检查（HIGH-2 修复：按 attempt_id 匹配，避免多任务 digest 碰撞）
+            const events = readEvents(projectRoot, change);
+            let hasRed = false, hasGreen = false;
+            for (const ev of events) {
+                if (ev.event_type === "test_run_recorded") {
+                    const tr = ev.payload;
+                    // 匹配当前 attempt（优先按 attempt_id，回退到 digest）
+                    const matches = tr.attempt_id === attempt.attempt_id ||
+                        (!tr.attempt_id && tr.task_structure_digest === attempt.task_structure_digest);
+                    if (matches) {
+                        if (tr.semantic_status === "expected_failure" || tr.semantic_status === "characterization_pass")
+                            hasRed = true;
+                        if (tr.semantic_status === "expected_success")
+                            hasGreen = true;
+                    }
+                }
+            }
+            if (isTdd) {
+                if (!hasRed)
+                    return { skip: true, message: `TDD 任务 ${taskId} 缺少 RED 证据` };
+                if (!hasGreen)
+                    return { skip: true, message: `TDD 任务 ${taskId} 缺少 GREEN 证据` };
+            }
+            else {
+                if (!hasNoTddReason)
+                    return { skip: true, message: `非 TDD 任务 ${taskId} 缺少 no_tdd_reason` };
+            }
+            // B1 修复：checkbox 写入移到 postCommit（commit 事件写入后执行）
+            return {
+                fromState: "apply", toState: "apply", outcome: "advanced",
+                reason: `任务 ${taskId} 完成`,
+                extraEvents: [{ type: "task_completed", payload: { task_id: taskId, attempt_id: attempt.attempt_id } }],
+                postCommit: (_pr, _ch, cr) => {
+                    const lines = readFileSync(join(cr, "tasks.md"), "utf8").split("\n");
+                    const idx = findTaskLine(lines, taskId);
+                    if (idx < 0 || !lines[idx].match(/- \[ \]/))
+                        throw new Error(`找不到 ${taskId} 的未完成复选框`);
+                    // H2 修复：应用前验证结构指纹
+                    const beforeDigest = sha256Text(lines.join("\n").replace(/- \[[xX]\]/g, "- [ ]"));
+                    lines[idx] = lines[idx].replace(/- \[ \]/, "- [x]");
+                    writeFileSync(join(cr, "tasks.md"), lines.join("\n"));
+                    // H2 修复：应用后验证只有目标变了
+                    const afterLines = readFileSync(join(cr, "tasks.md"), "utf8").split("\n");
+                    const afterDigest = sha256Text(afterLines.join("\n").replace(/- \[[xX]\]/g, "- [ ]"));
+                    if (afterDigest !== beforeDigest) {
+                        afterLines[idx] = afterLines[idx].replace(/- \[x\]/, "- [ ]");
+                        writeFileSync(join(cr, "tasks.md"), afterLines.join("\n"));
+                        throw new Error(`复选框补丁导致结构变化：${taskId}`);
+                    }
+                },
+            };
+        },
+    });
+}