@peterxiaoyang/superspec 0.1.14 → 0.1.16-alpha

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: ["proposal-auditor", "critic", "architect", "test-engineer"],
+    },
+    "explore": {
+        minimal: [],
+        normal: [],
+        strict: ["critic"],
+    },
+};
+/**
+ * 通用 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, risk = "normal") {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "explore", idempotencyInputs: { phase: "explore", risk },
+        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 + strict 模式下的 critic 审查
+                const discoveryCheck = validateDiscovery(changeRoot);
+                if (!discoveryCheck.ok)
+                    return { skip: true, message: discoveryCheck.message };
+                // 通用 job 审查（和 propose-ready 同一个 helper）
+                const requiredRoles = TRANSITION_REQUIREMENTS["explore"]?.[risk] ?? [];
+                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}`);
+                    }
+                },
+            };
+        },
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+export type State = "init" | "explore" | "propose" | "propose_ready" | "apply" | "apply_done" | "review" | "accepted" | "archive" | "abandoned";
+export declare const PHASE1_STATES: ReadonlySet<State>;
+export type Ref = {
+    path: string;
+    sha: string;
+};
+export type JobState = "requested" | "accepted" | "rejected";
+export type JobRole = "proposal-auditor" | "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "final-audit";
+export interface Job {
+    job_id: string;
+    role: JobRole;
+    state: JobState;
+    boundFiles: Ref[];
+    packet_digest: string;
+    created_from_transition: string;
+    created_at: string;
+}
+export interface JobPacket {
+    job_id: string;
+    role: JobRole;
+    recommended_agent?: string;
+    boundFiles: Ref[];
+    packet_digest: string;
+    required_output_kind: string;
+    output_contract_fields?: string[];
+    output_contract_optional_fields?: string[];
+    stop_conditions: string[];
+    created_from_transition: string;
+}
+export type EventType = "transition_prepare" | "transition_commit" | "job_requested" | "job_invalidated" | "reopen" | "abandon" | "task_started" | "task_completed" | "task_abandoned" | "job_accepted" | "job_rejected" | "user_decision_recorded" | "test_run_recorded" | "task_activation_recorded" | "artifact_recorded";
+export interface Event {
+    event_id: string;
+    event_type: EventType;
+    change_id: string;
+    transition_id: string | null;
+    idempotency_key: string | null;
+    created_at: string;
+    actor: string;
+    prev_snapshot_digest: string | null;
+    input_refs: Ref[];
+    output_refs: Ref[];
+    payload: Record<string, unknown>;
+    event_digest: string;
+}
+export interface TransitionCommitPayload {
+    transition: string;
+    from_state: State;
+    to_state: State;
+    outcome: "advanced" | "job_created";
+    created_job_ids: string[];
+    reason: string;
+}
+export interface Snapshot {
+    change_id: string;
+    state: State;
+    openspec_status_digest: string;
+    events_digest: string;
+    document_digests: Record<string, string>;
+    tasks_structure_digest: string | null;
+    task_statuses: Record<string, "todo" | "doing" | "done">;
+    open_jobs: Job[];
+    accepted_jobs: Job[];
+    active_task_attempts: TaskAttempt[];
+    pending_user_decisions: AskUser[];
+    last_transition: string | null;
+    computed_at: string;
+}
+export type AttemptState = "active" | "closed" | "abandoned";
+export interface TaskAttempt {
+    attempt_id: string;
+    task_id: string;
+    state: AttemptState;
+    task_structure_digest: string;
+    declared_write_scope: string[];
+    pre_edit_source_fingerprint: string | null;
+    pre_edit_red_ref: string | null;
+    executor_packet_digest: string | null;
+    executor_result_ref: string | null;
+    post_edit_green_ref: string | null;
+    created_at: string;
+}
+export interface TestRun {
+    test_id: string;
+    attempt_id?: string | null;
+    task_structure_digest: string;
+    command: string;
+    cwd: string;
+    exit_code: number;
+    semantic_status: "expected_failure" | "expected_success" | "characterization_pass" | "unknown";
+    target_fingerprint: string | null;
+    raw_log_ref: string | null;
+    created_at: string;
+}
+export interface MissingInput {
+    field: string;
+    expected: string;
+    command_to_fix: string;
+}
+export interface AskUser {
+    question: string;
+    allowed_answers: string[];
+    scope: string;
+}
+export type NextOutput = {
+    state: State;
+} & ({
+    path: "next_command";
+    next_command: string;
+    reason: string;
+    missing_inputs: MissingInput[];
+} | {
+    path: "required_job";
+    required_jobs: {
+        job_id: string;
+        role: JobRole;
+        packet_command: string;
+    }[];
+    reason: string;
+} | {
+    path: "ask_user";
+    ask_user: AskUser;
+    reason: string;
+} | {
+    path: "done";
+    reason: string;
+});
+export interface TransitionResult {
+    transition: string;
+    outcome: "advanced" | "job_created";
+    from_state: State;
+    to_state: State;
+    created_jobs: string[];
+    message: string;
+    events_written: number;
+}
+export interface RecordResult {
+    event_type: EventType;
+    accepted: boolean;
+    message: string;
+    job_state?: JobState;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// SuperSpec 流程引擎 — 核心类型定义
+// Phase 1 只实现前 4 个
+export const PHASE1_STATES = new Set(["init", "explore", "propose", "propose_ready"]);

package/package.json

@@ -1,65 +1,20 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.14",
-  "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/PeterYaoYang/SuperSpec.git"
-  },
-  "bugs": {
-    "url": "https://github.com/PeterYaoYang/SuperSpec/issues"
-  },
-  "homepage": "https://github.com/PeterYaoYang/SuperSpec#readme",
-  "private": false,
+  "version": "0.1.16-alpha",
+  "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=20.19.0"
-  },
-  "bin": {
-    "superspec": "bin/superspec.js",
-    "superspec-check": "bin/superspec-check.js",
-    "superspec-hook": "bin/superspec-hook.js",
-    "superspec-init": "bin/superspec-init.js"
-  },
+  "engines": { "node": ">=20.19.0" },
+  "bin": { "superspec": "dist/cli.js" },
   "exports": {
-    ".": {
-      "types": "./dist/superspec.d.ts",
-      "default": "./dist/superspec.js"
-    },
-    "./superspec_guard": {
-      "types": "./dist/superspec_guard.d.ts",
-      "default": "./dist/superspec_guard.js"
-    },
-    "./superspec_hook": {
-      "types": "./dist/superspec_hook.d.ts",
-      "default": "./dist/superspec_hook.js"
-    },
-    "./superspec_init": {
-      "types": "./dist/superspec_init.d.ts",
-      "default": "./dist/superspec_init.js"
-    },
-    "./templates/*": "./templates/*",
-    "./adapters/*": "./adapters/*",
-    "./schemas/*": "./schemas/*"
+    ".": { "types": "./dist/types.d.ts", "default": "./dist/cli.js" }
   },
-  "files": [
-    "README.md",
-    "bin",
-    "dist",
-    "templates",
-    "adapters",
-    "schemas"
-  ],
+  "files": ["README.md", "dist", "templates"],
   "scripts": {
     "build": "node build.js",
     "typecheck": "tsc --noEmit",
-    "test": "node --test tests/test_install_engine.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_cli.test.ts tests/test_superspec_guard_output.test.ts tests/test_superspec_guard_core.test.ts tests/test_superspec_guard_review.test.ts tests/test_superspec_guard_request_reopen.test.ts tests/test_superspec_guard_archive.test.ts tests/test_superspec_guard_packet.test.ts tests/test_superspec_guard_disclosure.test.ts tests/test_superspec_hooks.test.ts tests/test_superspec_i18n.test.ts tests/test_superspec_skills.test.ts",
+    "test": "node --test tests/*.ts",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build",
-    "pack:dry-run": "npm pack --dry-run"
+    "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@types/node": "^20.19.0",

package/templates/workflow/agents/architect.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: architect
+name = "architect"
+description = "System design, boundaries, interfaces, long-horizon tradeoffs"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Architect. Review system boundaries, interface contracts, data flow, maintenance risk, rollback risk, and design tradeoffs.
+
+Prompt binding: load `.codex/prompts/architect.md` first, then read the provided `review-packet`, job packet, or `prompt_ref`. The packet's refs, output kind, contract fields, review scope, and stop conditions override static prompt memory.
+
+Boundary: read-only. Do not edit files or judge materials you have not opened. Report missing context upward instead of guessing.
+
+Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"architect"`, `verdict`, and `findings`. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
+"""

package/{adapters/codex → templates/workflow}/agents/code-reviewer.toml

@@ -1,7 +1,7 @@
-# oh-my-codex agent: code-reviewer
+# SuperSpec Codex agent: code-reviewer
 name = "code-reviewer"
 description = "Comprehensive review across all concerns"
-model_reasoning_effort = "xhigh"
+model_reasoning_effort = "high"
 developer_instructions = """
 Role: Code Reviewer. Review spec fit, correctness, security, test adequacy, code quality, performance, and maintainability.
 

package/templates/workflow/agents/critic.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: critic
+name = "critic"
+description = "Plan/design critical challenge and review"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Critic. Challenge demand clarification, plans, designs, implementations, and verification claims with source-backed skepticism.
+
+Prompt binding: load `.codex/prompts/critic.md` first, then read the provided `review-packet`, job packet, or `prompt_ref`. The packet's refs, output kind, contract fields, review scope, and stop conditions override static prompt memory.
+
+Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward.
+
+Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"critic"`, `verdict`, and `findings`. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.
+"""