@peterxiaoyang/superspec 0.1.14 → 0.1.15-alpha

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// SuperSpec 流程引擎 — CLI 入口
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { writeSnapshot } from "./store.js";
+import { rebuildSnapshot } from "./sync.js";
+import { next as nextCmd } from "./next.js";
+import { proposeReady, commitTransition, transitionInit, transitionExplore, startApply, taskStart, taskComplete, reviewReady, accept, archive } from "./transition.js";
+import { recordJobSubmit, recordUserDecision, jobsList, jobsPacket } from "./record.js";
+import { recordTestRun } from "./task.js";
+import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
+// ===== 参数解析 =====
+function parseArgs(argv) {
+    const [command, subcommand, ...rest] = argv;
+    const opts = {};
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i].startsWith("--")) {
+            const key = rest[i].slice(2);
+            const val = rest[i + 1] && !rest[i + 1].startsWith("--") ? rest[++i] : "true";
+            opts[key] = val;
+        }
+    }
+    // 如果 subcommand 以 -- 开头，说明没有 subcommand
+    if (subcommand && subcommand.startsWith("--")) {
+        Object.entries(parseFlags([subcommand, ...rest])).forEach(([k, v]) => { opts[k] = v; });
+        return { command, opts };
+    }
+    return { command, subcommand, opts };
+}
+function parseFlags(args) {
+    const opts = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith("--")) {
+            const key = args[i].slice(2);
+            const val = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true";
+            opts[key] = val;
+        }
+    }
+    return opts;
+}
+// ===== 初始化 transition init =====
+// ===== init/explore 现在在 transition.ts 中（走统一锁内路径）=====
+// ===== 主分发 =====
+async function main(argv) {
+    // --help / 无参数 → 打印用法
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+        console.log(`SuperSpec 流程引擎 0.1.15-alpha
+
+用法：superspec <命令> [选项]
+
+命令：
+  status --change <C>              查看状态
+  transition <子命令> --change <C>  状态流转（见下）
+  record <子命令> --change <C>      登记证据（见下）
+  jobs <子命令> --change <C>        工作项管理（见下）
+  install [--global]               安装到项目或全局
+  update                           更新 SuperSpec
+  version                          版本号
+
+transition 子命令：
+  init / explore / sync / next / propose-ready / start-apply
+  task-start --task <T> / task-complete --task <T>
+  review-ready / accept / archive
+
+record 子命令：
+  job-submit --job <J> --report <F>
+  user-decision --input <F>
+  test-run --input <F>
+
+jobs 子命令：
+  list / packet --job <J>
+`);
+        return 0;
+    }
+    // version
+    if (argv[0] === "version" || argv[0] === "--version" || argv[0] === "-v") {
+        console.log("SuperSpec 0.1.15-alpha");
+        return 0;
+    }
+    const { command, subcommand, opts } = parseArgs(argv);
+    const projectRoot = process.cwd();
+    // install / update 不需要 --change
+    if (command === "install") {
+        const { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync } = await import("node:fs");
+        const engineDir = join(projectRoot, ".superspec");
+        // 检测老版残留（0.x 的 superspec-state.json / superspec-state.lock）
+        const oldStateFiles = ["superspec-state.json", "superspec-state.lock", "ledger.jsonl"];
+        const foundOld = oldStateFiles.some(f => existsSync(join(projectRoot, "openspec", "changes")) &&
+            readdirSync(join(projectRoot, "openspec", "changes")).some(c => existsSync(join(projectRoot, "openspec", "changes", c, ".superspec", f))));
+        if (foundOld) {
+            console.log(JSON.stringify({
+                ok: false,
+                message: "检测到老版 SuperSpec (0.x) 的状态文件。\n" +
+                    "SuperSpec 0.1.15-alpha 是全新引擎，不兼容 0.x 的状态格式。\n" +
+                    "请先用老版（0.1.x）完成或归档现有 change，再安装 0.1.15-alpha。\n" +
+                    "或在全新项目目录中安装。",
+            }));
+            return 1;
+        }
+        if (!existsSync(engineDir))
+            mkdirSync(join(engineDir, "changes"), { recursive: true });
+        const gitignorePath = join(engineDir, ".gitignore");
+        if (!existsSync(gitignorePath))
+            writeFileSync(gitignorePath, "changes/\n*.log\n*.tmp\n");
+        console.log(JSON.stringify({ ok: true, message: "SuperSpec 0.1.15-alpha 已安装" }));
+        return 0;
+    }
+    if (command === "update") {
+        // 检测是否从老版 update 过来
+        const { existsSync } = await import("node:fs");
+        const isLegacyUpdate = !existsSync(join(projectRoot, ".superspec", "changes"));
+        if (isLegacyUpdate) {
+            console.log(JSON.stringify({
+                ok: false,
+                message: "SuperSpec 0.1.15-alpha 是全新引擎，不能从 0.x 直接 update。\n" +
+                    "请用 npm install -g @peterxiaoyang/superspec@0.1.15-alpha 手动安装。\n" +
+                    "现有 change 请先用 0.1.x 完成归档。",
+            }));
+            return 1;
+        }
+        console.log(JSON.stringify({ ok: true, message: "已是最新版本 0.1.15-alpha" }));
+        return 0;
+    }
+    const change = opts.change;
+    if (!change && command !== "status") {
+        console.error("错误：缺少 --change（用 --help 查看用法）");
+        return 1;
+    }
+    try {
+        switch (command) {
+            case "status": {
+                if (!change) {
+                    // 全局 status
+                    const probe = probeOpenSpec(projectRoot);
+                    console.log(JSON.stringify({ openspec: probe }, null, 2));
+                    return 0;
+                }
+                const cr = changeRoot(projectRoot, change);
+                const snapshot = rebuildSnapshot(projectRoot, change, cr);
+                const jobs = jobsList(projectRoot, change);
+                console.log(JSON.stringify({
+                    change,
+                    state: snapshot.state,
+                    open_jobs: jobs.open.length,
+                    accepted_jobs: jobs.accepted.length,
+                    rejected_jobs: jobs.rejected.length,
+                    document_digests: snapshot.document_digests,
+                    last_transition: snapshot.last_transition,
+                }, null, 2));
+                return 0;
+            }
+            case "transition": {
+                const cr = changeRoot(projectRoot, change);
+                switch (subcommand) {
+                    case "init":
+                        console.log(JSON.stringify(transitionInit(projectRoot, change, cr), null, 2));
+                        return 0;
+                    case "explore":
+                        console.log(JSON.stringify(transitionExplore(projectRoot, change, cr), null, 2));
+                        return 0;
+                    case "sync": {
+                        const snapshot = rebuildSnapshot(projectRoot, change, cr, openspecStatus(projectRoot, change));
+                        writeSnapshot(projectRoot, change, snapshot);
+                        console.log(JSON.stringify({
+                            ok: true,
+                            state: snapshot.state,
+                            message: "snapshot 已重建",
+                            stale_accepted_removed: 0, // sync 不报告具体移除（轻量）
+                        }, null, 2));
+                        return 0;
+                    }
+                    case "next": {
+                        const risk = opts.risk ?? "normal";
+                        const result = nextCmd(projectRoot, change, cr, risk);
+                        console.log(JSON.stringify(result, null, 2));
+                        return 0;
+                    }
+                    case "propose-ready": {
+                        const risk = opts.risk ?? "normal";
+                        const result = proposeReady(projectRoot, change, cr, risk);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
+                    }
+                    case "start-apply": {
+                        const result = startApply(projectRoot, change, cr);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.events_written === 0 ? 1 : 0;
+                    }
+                    case "task-start": {
+                        const taskId = opts.task;
+                        if (!taskId) {
+                            console.error("task-start 需要 --task");
+                            return 1;
+                        }
+                        const result = taskStart(projectRoot, change, cr, taskId);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.events_written === 0 ? 1 : 0;
+                    }
+                    case "task-complete": {
+                        const taskId = opts.task;
+                        if (!taskId) {
+                            console.error("task-complete 需要 --task");
+                            return 1;
+                        }
+                        const result = taskComplete(projectRoot, change, cr, taskId);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.events_written === 0 ? 1 : 0;
+                    }
+                    case "review-ready": {
+                        const risk = opts.risk ?? "normal";
+                        const result = reviewReady(projectRoot, change, cr, risk);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.events_written === 0 ? 1 : 0;
+                    }
+                    case "accept": {
+                        const result = accept(projectRoot, change, cr);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.events_written === 0 ? 1 : 0;
+                    }
+                    case "archive": {
+                        const result = archive(projectRoot, change, cr);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.events_written === 0 ? 1 : 0;
+                    }
+                    default:
+                        console.error(`未知的 transition 子命令：${subcommand}`);
+                        return 1;
+                }
+            }
+            case "record": {
+                const cr = changeRoot(projectRoot, change);
+                switch (subcommand) {
+                    case "job-submit": {
+                        const jobId = opts.job;
+                        const report = opts.report;
+                        if (!jobId || !report) {
+                            console.error("record job-submit 需要 --job 和 --report");
+                            return 1;
+                        }
+                        const result = recordJobSubmit(projectRoot, change, cr, jobId, report);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.accepted ? 0 : 1;
+                    }
+                    case "user-decision": {
+                        const inputFile = opts.input;
+                        if (!inputFile) {
+                            console.error("record user-decision 需要 --input");
+                            return 1;
+                        }
+                        const result = recordUserDecision(projectRoot, change, inputFile);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.accepted ? 0 : 1;
+                    }
+                    case "test-run": {
+                        const inputFile = opts.input;
+                        if (!inputFile) {
+                            console.error("record test-run 需要 --input");
+                            return 1;
+                        }
+                        const result = recordTestRun(projectRoot, change, inputFile);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.accepted ? 0 : 1;
+                    }
+                    default:
+                        console.error(`未知的 record 子命令：${subcommand}`);
+                        return 1;
+                }
+            }
+            case "jobs": {
+                switch (subcommand) {
+                    case "list": {
+                        const result = jobsList(projectRoot, change);
+                        console.log(JSON.stringify(result, null, 2));
+                        return 0;
+                    }
+                    case "packet": {
+                        const jobId = opts.job;
+                        if (!jobId) {
+                            console.error("jobs packet 需要 --job");
+                            return 1;
+                        }
+                        const result = jobsPacket(projectRoot, change, jobId);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.found ? 0 : 1;
+                    }
+                    default:
+                        console.error(`未知的 jobs 子命令：${subcommand}`);
+                        return 1;
+                }
+            }
+            default:
+                console.error(`未知命令：${command}。可用：status, transition, record, jobs`);
+                return 1;
+        }
+    }
+    catch (err) {
+        console.error(`错误：${err.message}`);
+        return 2;
+    }
+}
+// 入口
+main(process.argv.slice(2)).then(exitCode => process.exit(exitCode));

package/dist/format.d.ts

@@ -0,0 +1,29 @@
+/** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
+export declare function countDiscoveryOpenQuestions(content: string): number;
+/** 完整校验 discovery.md：存在 + 非空 + 无未确认问题 */
+export declare function validateDiscovery(changeRoot: string): {
+    ok: boolean;
+    message: string;
+    openCount: number;
+};
+export interface ParsedTask {
+    taskId: string;
+    lineIdx: number;
+    done: boolean;
+    tddRequired: boolean;
+    noTddReason: string | null;
+}
+/** 解析 tasks.md 的全部任务行 */
+export declare function parseTasksMd(content: string): ParsedTask[];
+/** 在 tasks.md 中按 taskId 精确查找任务（词边界，不误判子串） */
+export declare function findTaskInLines(lines: string[], taskId: string): number;
+/** tasks.md 结构指纹（复选框归一化） */
+export declare function tasksStructureDigest(content: string, sha256Text: (s: string) => string): string;
+export declare function validateTestRunInput(tr: Record<string, unknown>): {
+    ok: boolean;
+    message: string;
+};
+export declare function validateUserDecision(d: Record<string, unknown>): {
+    ok: boolean;
+    message: string;
+};

package/dist/format.js

@@ -0,0 +1,141 @@
+// SuperSpec 流程引擎 — format.ts：文档格式解析的唯一权威源
+//
+// 所有文档的格式定义和解析逻辑都在这里。skills 文案引用这里的格式。
+// 修改格式 = 修改这里 + 对应 skill。禁止在其它地方重复解析。
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+// ===== discovery.md =====
+//
+// 格式（explore skill 定义）：
+//   ## 待确认问题
+//   - [ ] 问题1的描述
+//   - [ ] 问题2的描述
+//
+// 引擎只解析"待确认问题"段内的 `- [ ]`，不误判正常 checklist。
+/** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
+export function countDiscoveryOpenQuestions(content) {
+    // 找"待确认问题"标题（中英文兼容）
+    const sectionMatch = content.match(/^#{1,6}\s*(待确认问题|Open Questions|Pending Questions)\s*$/im);
+    if (!sectionMatch)
+        return 0;
+    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+    // 截取到下一个标题或文件末尾
+    const restContent = content.slice(sectionStart);
+    const nextHeadingMatch = restContent.match(/^#{1,6}\s+/m);
+    const sectionBody = nextHeadingMatch ? restContent.slice(0, nextHeadingMatch.index) : restContent;
+    // 数未确认项
+    const matches = sectionBody.match(/- \[ \]/g);
+    return matches ? matches.length : 0;
+}
+/** 完整校验 discovery.md：存在 + 非空 + 无未确认问题 */
+export function validateDiscovery(changeRoot) {
+    const path = join(changeRoot, ".superspec", "artifacts", "discovery.md");
+    if (!existsSync(path))
+        return { ok: false, message: "discovery.md 不存在", openCount: -1 };
+    const content = readFileSync(path, "utf8");
+    if (!content.trim())
+        return { ok: false, message: "discovery.md 为空", openCount: -1 };
+    const openCount = countDiscoveryOpenQuestions(content);
+    if (openCount > 0)
+        return { ok: false, message: `discovery.md 有 ${openCount} 个未确认问题`, openCount };
+    return { ok: true, message: "discovery.md 就绪", openCount: 0 };
+}
+const TASK_LINE_RE = /^(- \[([ xX])\])\s+(\S+)/;
+/** 解析 tasks.md 的全部任务行 */
+export function parseTasksMd(content) {
+    const lines = content.split("\n");
+    const tasks = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(TASK_LINE_RE);
+        if (!m)
+            continue;
+        const taskId = m[3];
+        const done = m[2].toLowerCase() === "x";
+        // 用正则锚定字段边界，不依赖 includes()
+        const tddMatch = lines[i].match(/\btdd_required:(true|false)\b/);
+        const reasonMatch = lines[i].match(/\bno_tdd_reason:(\S+)\b/);
+        tasks.push({
+            taskId,
+            lineIdx: i,
+            done,
+            tddRequired: tddMatch ? tddMatch[1] === "true" : true, // 默认 true
+            noTddReason: reasonMatch ? reasonMatch[1] : null,
+        });
+    }
+    return tasks;
+}
+/** 在 tasks.md 中按 taskId 精确查找任务（词边界，不误判子串） */
+export function findTaskInLines(lines, taskId) {
+    for (let i = 0; i < lines.length; i++) {
+        // 精确匹配行内的 taskId token
+        const m = lines[i].match(TASK_LINE_RE);
+        if (m && m[3] === taskId)
+            return i;
+        // 回退：用转义正则匹配（兼容 taskId 后跟标点的情况）
+        const escaped = taskId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        if (new RegExp("(?:^|\\s)" + escaped + "(?:\\s|$|[.,:;!?)\\]])").test(lines[i]))
+            return i;
+    }
+    return -1;
+}
+/** tasks.md 结构指纹（复选框归一化） */
+export function tasksStructureDigest(content, sha256Text) {
+    return sha256Text(content.replace(/- \[[xX]\]/g, "- [ ]"));
+}
+// ===== test-run JSON =====
+//
+// 格式（apply skill 定义）：
+//   {
+//     "test_id": "TEST-XXX",
+//     "attempt_id": "ATT-TASK-XXX-...",
+//     "task_structure_digest": "sha256:...",
+//     "command": "npm test",
+//     "cwd": "/path",
+//     "exit_code": 1,
+//     "semantic_status": "expected_failure",
+//     "target_fingerprint": "sha256:..."
+//   }
+//
+// 引擎校验：test_id + task_structure_digest 必填，其余可选
+export function validateTestRunInput(tr) {
+    if (!tr.test_id)
+        return { ok: false, message: "缺少 test_id" };
+    if (!tr.task_structure_digest)
+        return { ok: false, message: "缺少 task_structure_digest" };
+    return { ok: true, message: "" };
+}
+// ===== user-decision JSON =====
+//
+// 格式（explore skill 定义）：
+//   {
+//     "scope": "enter_propose",
+//     "question": "是否进入计划阶段？",
+//     "answer": "yes"
+//   }
+//
+// 引擎校验：scope + answer 必填
+export function validateUserDecision(d) {
+    if (!d.scope)
+        return { ok: false, message: "决策文件缺少 scope" };
+    if (!d.answer)
+        return { ok: false, message: "决策文件缺少 answer" };
+    return { ok: true, message: "" };
+}
+// ===== business-invariants.md =====
+//
+// 格式（propose skill 定义）：
+//   # Business Invariants
+//   - INV-001 用户密码必须加密存储
+//
+// 引擎行为：Phase 1-5 只校验文件存在性（轻量）。
+// 内部结构（INV-XXX 编号）是 agent 指引，引擎不逐行解析。
+// ===== test-contract.md =====
+//
+// 格式（propose skill 定义）：
+//   # Test Contract
+//   | test_id | invariant | scenario |
+//   |---|---|---|
+//   | TEST-001 | INV-001 | 注册时密码被加密 |
+//
+// 引擎行为：Phase 1-5 只校验文件存在性（轻量）。
+// 表格结构是 agent 指引，引擎不逐行解析。

package/dist/next.d.ts

@@ -0,0 +1,3 @@
+import type { NextOutput } from "./types.ts";
+/** next 命令：读 snapshot，返回唯一可执行路径 */
+export declare function next(projectRoot: string, change: string, changeRoot: string, defaultRisk?: "minimal" | "normal" | "strict"): NextOutput;

package/dist/next.js

@@ -0,0 +1,161 @@
+// SuperSpec 流程引擎 — next：返回可执行路径
+import { rebuildSnapshot } from "./sync.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateDiscovery, countDiscoveryOpenQuestions } from "./format.js";
+function packetCommand(change, jobId) {
+    return `superspec jobs packet --change "${change}" --job "${jobId}"`;
+}
+function transitionCommand(change, name, extra = "") {
+    return `superspec transition ${name} --change "${change}"${extra ? " " + extra : ""}`;
+}
+/** next 命令：读 snapshot，返回唯一可执行路径 */
+export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
+    const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
+    switch (snapshot.state) {
+        case "init":
+            return {
+                state: "init",
+                path: "next_command",
+                next_command: transitionCommand(change, "explore"),
+                reason: "初始化完成，开始探索",
+                missing_inputs: [],
+            };
+        case "explore": {
+            // Phase 2：检查 discovery.md
+            const discoveryCheck = validateDiscovery(changeRoot);
+            if (!discoveryCheck.ok) {
+                const ask = {
+                    question: discoveryCheck.message + "，请处理后继续",
+                    allowed_answers: ["已处理"],
+                    scope: "explore_discovery",
+                };
+                return { state: "explore", path: "ask_user", ask_user: ask, reason: discoveryCheck.message };
+            }
+            // 检查"待确认问题"段（用 format.ts 的段感知解析）
+            const content = readFileSync(join(changeRoot, ".superspec", "artifacts", "discovery.md"), "utf8");
+            const openQs = countDiscoveryOpenQuestions(content);
+            if (openQs > 0) {
+                const ask = {
+                    question: `discovery.md 有 ${openQs} 个未解决的待确认问题，请逐个确认`,
+                    allowed_answers: ["所有问题已确认"],
+                    scope: "explore_open_questions",
+                };
+                return { state: "explore", path: "ask_user", ask_user: ask, reason: `有 ${openQs} 个未确认问题` };
+            }
+            return {
+                state: "explore",
+                path: "next_command",
+                next_command: transitionCommand(change, "explore"),
+                reason: "探索完成，推进到计划阶段",
+                missing_inputs: [],
+            };
+        }
+        case "propose": {
+            if (snapshot.open_jobs.length > 0) {
+                const jobs = snapshot.open_jobs.map(j => ({
+                    job_id: j.job_id,
+                    role: j.role,
+                    packet_command: packetCommand(change, j.job_id),
+                }));
+                return {
+                    state: "propose",
+                    path: "required_job",
+                    required_jobs: jobs,
+                    reason: `有 ${jobs.length} 个待完成工作项`,
+                };
+            }
+            const riskFlag = `--risk ${defaultRisk}`;
+            return {
+                state: "propose",
+                path: "next_command",
+                next_command: transitionCommand(change, "propose-ready", riskFlag),
+                reason: "计划文档就绪，提交 propose-ready",
+                missing_inputs: [],
+            };
+        }
+        case "propose_ready":
+            return {
+                state: "propose_ready",
+                path: "next_command",
+                next_command: transitionCommand(change, "start-apply"),
+                reason: "计划就绪，开始执行",
+                missing_inputs: [],
+            };
+        case "apply": {
+            // 有 open job → 做
+            if (snapshot.open_jobs.length > 0) {
+                return {
+                    state: "apply",
+                    path: "required_job",
+                    required_jobs: snapshot.open_jobs.map(j => ({ job_id: j.job_id, role: j.role, packet_command: packetCommand(change, j.job_id) })),
+                    reason: `有 ${snapshot.open_jobs.length} 个待完成工作项`,
+                };
+            }
+            // 检查是否所有任务已完成
+            const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+            const allDone = !tasksContent.split("\n").some(l => l.includes("- [ ]"));
+            if (allDone) {
+                return {
+                    state: "apply",
+                    path: "next_command",
+                    next_command: transitionCommand(change, "review-ready"),
+                    reason: "所有任务完成，进入审查",
+                    missing_inputs: [],
+                };
+            }
+            return {
+                state: "apply",
+                path: "next_command",
+                next_command: transitionCommand(change, "task-start", "--task TASK-XXX"),
+                reason: "执行中：查看 tasks.md 找下一个未完成任务",
+                missing_inputs: [],
+            };
+        }
+        case "apply_done": {
+            if (snapshot.open_jobs.length > 0) {
+                return {
+                    state: "apply_done",
+                    path: "required_job",
+                    required_jobs: snapshot.open_jobs.map(j => ({ job_id: j.job_id, role: j.role, packet_command: packetCommand(change, j.job_id) })),
+                    reason: `有 ${snapshot.open_jobs.length} 个待完成工作项`,
+                };
+            }
+            return {
+                state: "apply_done",
+                path: "next_command",
+                next_command: transitionCommand(change, "review-ready"),
+                reason: "所有任务完成，进入审查",
+                missing_inputs: [],
+            };
+        }
+        case "review":
+            return {
+                state: "review",
+                path: "next_command",
+                next_command: transitionCommand(change, "accept"),
+                reason: "审查完成，提交接受",
+                missing_inputs: [],
+            };
+        case "accepted":
+            return {
+                state: "accepted",
+                path: "next_command",
+                next_command: transitionCommand(change, "archive"),
+                reason: "审查通过，提交归档",
+                missing_inputs: [],
+            };
+        case "archive":
+            return {
+                state: "archive",
+                path: "done",
+                reason: "已归档，流程完成。",
+            };
+        default:
+            return {
+                state: snapshot.state,
+                path: "done",
+                reason: `状态 ${snapshot.state} 超出 Phase 1 范围`,
+            };
+    }
+}

package/dist/openspec.d.ts

@@ -0,0 +1,9 @@
+export interface OpenSpecProbe {
+    available: boolean;
+    version: string | null;
+    changeExists: boolean;
+    error?: string;
+}
+export declare function probeOpenSpec(projectRoot: string, change?: string): OpenSpecProbe;
+export declare function openspecStatus(projectRoot: string, change: string): string;
+export declare function changeRoot(projectRoot: string, change: string): string;