@peterxiaoyang/superspec 0.1.20 → 0.1.22

package/README.md

@@ -238,7 +238,7 @@ superspec status
 superspec update
 ```
 
-这条命令会补齐 `.superspec/changes` 运行时目录，并把当前 CLI 内置的 `.codex/skills/superspec-*`、`.codex/prompts/*.md`、`.codex/agents/*.toml` 同步到项目里。真正升级全局 npm 包仍需使用 `npm install -g @peterxiaoyang/superspec@<version>`。
+这条命令会先检查 npm 上的 latest 版本；如果有新版，会自动执行全局升级并用新版 CLI 重新同步项目入口。同步内容包括补齐 `.superspec/changes` 运行时目录，并把当前 CLI 内置的 `.codex/skills/superspec-*`、`.codex/prompts/*.md`、`.codex/agents/*.toml` 同步到项目里。
 
 ## 进阶信息
 

package/dist/cli.js

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 // SuperSpec 流程引擎 — CLI 入口
 import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
 import { installProject } from "./install.js";
 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 { proposeReady, commitTransition, transitionInit, transitionExplore, startApply, taskStart, taskComplete, reopen, 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";
 import { SUPERSPEC_VERSION } from "./version.js";
+const PACKAGE_NAME = "@peterxiaoyang/superspec";
 // ===== 参数解析 =====
 function parseArgs(argv) {
     const [command, subcommand, ...rest] = argv;
@@ -39,6 +42,279 @@ function parseFlags(args) {
     }
     return opts;
 }
+function parseVersion(version) {
+    const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] ?? null,
+    };
+}
+function compareVersions(a, b) {
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    if (!left || !right)
+        return a.localeCompare(b);
+    for (const key of ["major", "minor", "patch"]) {
+        if (left[key] !== right[key])
+            return left[key] - right[key];
+    }
+    if (left.prerelease === right.prerelease)
+        return 0;
+    if (left.prerelease == null)
+        return 1;
+    if (right.prerelease == null)
+        return -1;
+    return left.prerelease.localeCompare(right.prerelease);
+}
+function commandErrorMessage(err) {
+    if (!err || typeof err !== "object")
+        return String(err);
+    const maybe = err;
+    const stderr = maybe.stderr ? Buffer.from(maybe.stderr).toString("utf8").trim() : "";
+    const stdout = maybe.stdout ? Buffer.from(maybe.stdout).toString("utf8").trim() : "";
+    return stderr || stdout || maybe.message || String(err);
+}
+class SelfUpdateError extends Error {
+    phase;
+    latest;
+    constructor(phase, message, latest = null) {
+        super(message);
+        this.name = "SelfUpdateError";
+        this.phase = phase;
+        this.latest = latest;
+    }
+}
+function isTestMode() {
+    return process.env.SUPERSPEC_TEST_MODE === "1" || process.env.NODE_ENV === "test";
+}
+function testEnv(name) {
+    return isTestMode() ? process.env[name] : undefined;
+}
+function selfUpdateError(phase, err, latest = null) {
+    return new SelfUpdateError(phase, commandErrorMessage(err), latest);
+}
+function attachSelfUpdateLatest(err, phase, latest) {
+    if (err instanceof SelfUpdateError) {
+        return new SelfUpdateError(err.phase, err.message, err.latest ?? latest);
+    }
+    return selfUpdateError(phase, err, latest);
+}
+function selfUpdateFailurePayload(err) {
+    if (err instanceof SelfUpdateError) {
+        return {
+            ok: false,
+            message: err.message,
+            self_update: {
+                updated: false,
+                from: SUPERSPEC_VERSION,
+                to: err.latest,
+                phase: err.phase,
+            },
+        };
+    }
+    return {
+        ok: false,
+        message: commandErrorMessage(err),
+        self_update: {
+            updated: false,
+            from: SUPERSPEC_VERSION,
+            to: null,
+            phase: "unknown",
+        },
+    };
+}
+function npmLatestVersion() {
+    const testError = testEnv("SUPERSPEC_TEST_NPM_VIEW_ERROR");
+    if (testError)
+        throw new SelfUpdateError("npm_view", testError);
+    const testLatest = testEnv("SUPERSPEC_TEST_LATEST_VERSION");
+    if (testLatest)
+        return testLatest;
+    try {
+        const output = execFileSync("npm", ["view", PACKAGE_NAME, "version"], { encoding: "utf8" });
+        return output.trim().replace(/^"|"$/g, "");
+    }
+    catch (err) {
+        throw selfUpdateError("npm_view", err);
+    }
+}
+function installLatestGlobal() {
+    const testError = testEnv("SUPERSPEC_TEST_GLOBAL_INSTALL_ERROR");
+    if (testError)
+        throw new SelfUpdateError("global_install", testError);
+    if (testEnv("SUPERSPEC_TEST_SKIP_GLOBAL_INSTALL") === "1")
+        return;
+    try {
+        execFileSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        throw selfUpdateError("global_install", err);
+    }
+}
+function parseSuperSpecVersion(output) {
+    const match = output.trim().match(/^SuperSpec\s+(.+)$/);
+    return match?.[1]?.trim() ?? null;
+}
+function pathCliVersion() {
+    const testError = testEnv("SUPERSPEC_TEST_CLI_VERSION_ERROR");
+    if (testError)
+        throw new Error(testError);
+    const testVersion = testEnv("SUPERSPEC_TEST_CLI_VERSION");
+    if (testVersion)
+        return testVersion;
+    const testOutput = testEnv("SUPERSPEC_TEST_CLI_VERSION_OUTPUT");
+    if (testOutput) {
+        const parsed = parseSuperSpecVersion(testOutput);
+        if (!parsed)
+            throw new Error(`无法解析 superspec --version 输出：${testOutput}`);
+        return parsed;
+    }
+    const output = execFileSync("superspec", ["--version"], {
+        encoding: "utf8",
+        env: process.env,
+    });
+    const parsed = parseSuperSpecVersion(output);
+    if (!parsed)
+        throw new Error(`无法解析 superspec --version 输出：${output.trim()}`);
+    return parsed;
+}
+function assertUpdatedCliVersion(latest) {
+    let actual;
+    try {
+        actual = pathCliVersion();
+    }
+    catch (err) {
+        throw selfUpdateError("version_check", err, latest);
+    }
+    if (actual !== latest) {
+        throw new SelfUpdateError("version_mismatch", `全局 superspec 版本仍为 ${actual}，期望 ${latest}。请检查 npm 全局 bin 是否在 PATH 前置。`, latest);
+    }
+}
+function rerunUpdatedCli(projectRoot, args) {
+    const testError = testEnv("SUPERSPEC_TEST_RERUN_ERROR");
+    if (testError)
+        throw new SelfUpdateError("rerun", testError);
+    const testOutput = testEnv("SUPERSPEC_TEST_RERUN_OUTPUT");
+    if (testOutput)
+        return testOutput;
+    try {
+        return execFileSync("superspec", args, {
+            cwd: projectRoot,
+            encoding: "utf8",
+            env: process.env,
+        });
+    }
+    catch (err) {
+        throw selfUpdateError("rerun", err);
+    }
+}
+function updateSelfIfNeeded(projectRoot, rerunArgs) {
+    const latest = npmLatestVersion();
+    if (compareVersions(latest, SUPERSPEC_VERSION) <= 0)
+        return { updated: false, latest };
+    try {
+        installLatestGlobal();
+    }
+    catch (err) {
+        throw attachSelfUpdateLatest(err, "global_install", latest);
+    }
+    assertUpdatedCliVersion(latest);
+    let output;
+    try {
+        output = rerunUpdatedCli(projectRoot, rerunArgs);
+    }
+    catch (err) {
+        throw attachSelfUpdateLatest(err, "rerun", latest);
+    }
+    return {
+        updated: true,
+        latest,
+        output,
+    };
+}
+function updatedCliOutput(output, latest) {
+    const trimmed = output.trim();
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("新版 CLI 输出不是 JSON object");
+        }
+        const payload = {
+            ...parsed,
+            self_update: {
+                updated: true,
+                from: SUPERSPEC_VERSION,
+                to: latest,
+            },
+        };
+        return {
+            exitCode: payload.ok === false ? 1 : 0,
+            text: JSON.stringify(payload, null, 2),
+        };
+    }
+    catch {
+        const failure = new SelfUpdateError("rerun_output", "新版 CLI 输出不是 JSON object", latest);
+        return {
+            exitCode: 1,
+            text: JSON.stringify(selfUpdateFailurePayload(failure), null, 2),
+        };
+    }
+}
+async function askToUpdateSelfIfNeeded(projectRoot, rerunArgs) {
+    const assumeTty = testEnv("SUPERSPEC_TEST_ASSUME_TTY") === "1";
+    if (!assumeTty && (!process.stdin.isTTY || !process.stdout.isTTY))
+        return { updated: false, latest: null };
+    let latest;
+    try {
+        latest = npmLatestVersion();
+    }
+    catch (err) {
+        console.error(`SuperSpec 检查最新版本失败：${commandErrorMessage(err)}。继续使用当前版本。`);
+        return { updated: false, latest: null };
+    }
+    if (compareVersions(latest, SUPERSPEC_VERSION) <= 0)
+        return { updated: false, latest };
+    const testAnswer = testEnv("SUPERSPEC_TEST_PROMPT_ANSWER");
+    if (testAnswer !== undefined) {
+        if (/^n(o)?$/i.test(testAnswer.trim()))
+            return { updated: false, latest };
+    }
+    else {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            const answer = await rl.question(`发现 SuperSpec ${latest} 可用，当前为 ${SUPERSPEC_VERSION}。是否先升级再继续？ [Y/n] `);
+            if (/^n(o)?$/i.test(answer.trim()))
+                return { updated: false, latest };
+        }
+        finally {
+            rl.close();
+        }
+    }
+    try {
+        installLatestGlobal();
+    }
+    catch (err) {
+        throw attachSelfUpdateLatest(err, "global_install", latest);
+    }
+    assertUpdatedCliVersion(latest);
+    try {
+        return {
+            updated: true,
+            latest,
+            output: rerunUpdatedCli(projectRoot, rerunArgs),
+        };
+    }
+    catch (err) {
+        throw attachSelfUpdateLatest(err, "rerun", latest);
+    }
+}
 // ===== 初始化 transition init =====
 // ===== init/explore 现在在 transition.ts 中（走统一锁内路径）=====
 // ===== 主分发 =====
@@ -56,12 +332,13 @@ async function main(argv) {
   jobs <子命令> --change <C>        工作项管理（见下）
   install                           安装项目工作流入口
   init --scope project              install 的兼容别名
-  update                           同步项目工作流模板
+  update                           升级 CLI 到 npm latest 并同步项目工作流模板
   version                          版本号
 
 transition 子命令：
   init / explore / sync / next / propose-ready / start-apply
   task-start --task <T> / task-complete --task <T>
+  reopen --to apply --reason <TEXT>
   review-ready / accept / archive
 
 record 子命令：
@@ -91,19 +368,37 @@ jobs 子命令：
             return 1;
         }
         try {
+            if (opts["skip-self-update"] !== "true") {
+                const rerunArgs = command === "init"
+                    ? ["init", "--scope", "project", "--skip-self-update"]
+                    : ["install", "--skip-self-update"];
+                const selfUpdate = await askToUpdateSelfIfNeeded(projectRoot, rerunArgs);
+                if (selfUpdate.updated) {
+                    const rerun = updatedCliOutput(selfUpdate.output, selfUpdate.latest);
+                    console.log(rerun.text);
+                    return rerun.exitCode;
+                }
+            }
             console.log(JSON.stringify(installProject(projectRoot)));
             return 0;
         }
         catch (err) {
-            console.log(JSON.stringify({
-                ok: false,
-                message: err.message,
-            }));
+            console.log(JSON.stringify(err instanceof SelfUpdateError
+                ? selfUpdateFailurePayload(err)
+                : { ok: false, message: commandErrorMessage(err) }));
             return 1;
         }
     }
     if (command === "update") {
         try {
+            if (opts["skip-self-update"] !== "true") {
+                const selfUpdate = updateSelfIfNeeded(projectRoot, ["update", "--skip-self-update"]);
+                if (selfUpdate.updated) {
+                    const rerun = updatedCliOutput(selfUpdate.output, selfUpdate.latest);
+                    console.log(rerun.text);
+                    return rerun.exitCode;
+                }
+            }
             const result = installProject(projectRoot, { allowLegacyState: true });
             console.log(JSON.stringify({
                 ...result,
@@ -112,10 +407,9 @@ jobs 子命令：
             return 0;
         }
         catch (err) {
-            console.log(JSON.stringify({
-                ok: false,
-                message: err.message,
-            }));
+            console.log(JSON.stringify(err instanceof SelfUpdateError
+                ? selfUpdateFailurePayload(err)
+                : { ok: false, message: commandErrorMessage(err) }));
             return 1;
         }
     }
@@ -215,6 +509,21 @@ jobs 子命令：
                         console.log(JSON.stringify(result, null, 2));
                         return result.events_written === 0 ? 1 : 0;
                     }
+                    case "reopen": {
+                        const to = opts.to;
+                        const reason = opts.reason;
+                        if (!to) {
+                            console.error("reopen 需要 --to");
+                            return 1;
+                        }
+                        if (!reason) {
+                            console.error("reopen 需要 --reason");
+                            return 1;
+                        }
+                        const result = reopen(projectRoot, change, cr, to, reason);
+                        console.log(JSON.stringify(result, null, 2));
+                        return result.events_written === 0 ? 1 : 0;
+                    }
                     case "review-ready": {
                         const risk = opts.risk ?? "strict";
                         const result = reviewReady(projectRoot, change, cr, risk);

package/dist/format.d.ts

@@ -24,6 +24,8 @@ export interface ParsedTask {
 }
 /** 解析 tasks.md 的全部任务行 */
 export declare function parseTasksMd(content: string): ParsedTask[];
+/** 返回未完成任务 */
+export declare function pendingTasksInContent(content: string): ParsedTask[];
 /** 在 tasks.md 中按 taskId 精确查找任务（词边界，不误判子串） */
 export declare function findTaskInLines(lines: string[], taskId: string): number;
 /** tasks.md 结构指纹（复选框归一化） */

package/dist/format.js

@@ -94,6 +94,10 @@ export function parseTasksMd(content) {
     }
     return tasks;
 }
+/** 返回未完成任务 */
+export function pendingTasksInContent(content) {
+    return parseTasksMd(content).filter(task => !task.done);
+}
 /** 在 tasks.md 中按 taskId 精确查找任务（词边界，不误判子串） */
 export function findTaskInLines(lines, taskId) {
     for (let i = 0; i < lines.length; i++) {

package/dist/next.js

@@ -2,7 +2,8 @@
 import { rebuildSnapshot } from "./sync.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { validateDiscovery, countDiscoveryOpenQuestions, collectProposeOpenQuestions } from "./format.js";
+import { readEvents, sha256Text } from "./store.js";
+import { validateDiscovery, countDiscoveryOpenQuestions, collectProposeOpenQuestions, parseTasksMd, pendingTasksInContent } from "./format.js";
 const ACTIVE_PROPOSAL_REVIEW_ROLES = new Set(["critic", "architect", "test-engineer"]);
 function isActiveProposalReviewJob(job) {
     return job.created_from_transition === "propose-ready" && ACTIVE_PROPOSAL_REVIEW_ROLES.has(job.role);
@@ -16,6 +17,50 @@ function transitionCommand(change, name, extra = "") {
 function riskFlag(risk) {
     return risk === "strict" ? "" : `--risk ${risk}`;
 }
+function pendingTaskIds(changeRoot) {
+    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+    return pendingTasksInContent(tasksContent).map(task => task.taskId);
+}
+function reopenCommand(change, pending) {
+    return transitionCommand(change, "reopen", `--to apply --reason "pending tasks: ${pending.join(", ")}"`);
+}
+function taskCompletionReadiness(projectRoot, change, changeRoot, attempt) {
+    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+    const tasks = parseTasksMd(tasksContent);
+    const taskInfo = tasks.find(task => task.taskId === attempt.task_id);
+    const missing = [];
+    if (!taskInfo)
+        return { ready: false, missing: [`任务 ${attempt.task_id} 不存在`] };
+    const currentDigest = sha256Text(tasksContent.replace(/- \[[xX]\]/g, "- [ ]"));
+    // Keep the wording aligned with task-complete; no command should be suggested if it would fail this guard.
+    if (currentDigest !== attempt.task_structure_digest)
+        missing.push("任务结构指纹");
+    if (!taskInfo.tddRequired) {
+        if (!taskInfo.noTddReason)
+            missing.push("no_tdd_reason");
+        return { ready: missing.length === 0, missing };
+    }
+    let hasRed = false;
+    let hasGreen = false;
+    for (const ev of readEvents(projectRoot, change)) {
+        if (ev.event_type !== "test_run_recorded")
+            continue;
+        const tr = ev.payload;
+        const matches = tr.attempt_id === attempt.attempt_id ||
+            (!tr.attempt_id && tr.task_structure_digest === attempt.task_structure_digest);
+        if (!matches)
+            continue;
+        if (tr.semantic_status === "expected_failure" || tr.semantic_status === "characterization_pass")
+            hasRed = true;
+        if (tr.semantic_status === "expected_success")
+            hasGreen = true;
+    }
+    if (!hasRed)
+        missing.push("RED 证据");
+    if (!hasGreen)
+        missing.push("GREEN 证据");
+    return { ready: missing.length === 0, missing };
+}
 /** next 命令：读 snapshot，返回唯一可执行路径 */
 export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
     const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
@@ -114,6 +159,36 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
             };
         }
         case "apply": {
+            // 检查是否所有任务已完成
+            const pending = pendingTaskIds(changeRoot);
+            if (pending.length > 0) {
+                const activePending = snapshot.active_task_attempts.find(attempt => attempt.state === "active" && pending.includes(attempt.task_id));
+                if (activePending) {
+                    const readiness = taskCompletionReadiness(projectRoot, change, changeRoot, activePending);
+                    if (readiness.ready) {
+                        return {
+                            state: "apply",
+                            path: "next_command",
+                            next_command: transitionCommand(change, "task-complete", `--task ${activePending.task_id}`),
+                            reason: `任务 ${activePending.task_id} 证据已登记，可以完成`,
+                            missing_inputs: [],
+                        };
+                    }
+                    const ask = {
+                        question: `任务 ${activePending.task_id} 已开始，请先登记 ${readiness.missing.join("、")} 后继续`,
+                        allowed_answers: ["证据已登记"],
+                        scope: `apply_active_task_${activePending.task_id}`,
+                    };
+                    return { state: "apply", path: "ask_user", ask_user: ask, reason: `任务 ${activePending.task_id} 缺少完成证据` };
+                }
+                return {
+                    state: "apply",
+                    path: "next_command",
+                    next_command: transitionCommand(change, "task-start", `--task ${pending[0]}`),
+                    reason: `执行中：下一个未完成任务 ${pending[0]}`,
+                    missing_inputs: [],
+                };
+            }
             // 有 open job → 做
             if (snapshot.open_jobs.length > 0) {
                 return {
@@ -123,27 +198,25 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                     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", riskFlag(defaultRisk)),
-                    reason: "所有任务完成，进入审查",
-                    missing_inputs: [],
-                };
-            }
             return {
                 state: "apply",
                 path: "next_command",
-                next_command: transitionCommand(change, "task-start", "--task TASK-XXX"),
-                reason: "执行中：查看 tasks.md 找下一个未完成任务",
+                next_command: transitionCommand(change, "review-ready", riskFlag(defaultRisk)),
+                reason: "所有任务完成，进入审查",
                 missing_inputs: [],
             };
         }
         case "apply_done": {
+            const pending = pendingTaskIds(changeRoot);
+            if (pending.length > 0) {
+                return {
+                    state: "apply_done",
+                    path: "next_command",
+                    next_command: reopenCommand(change, pending),
+                    reason: `发现未完成任务 ${pending[0]}，回到执行阶段`,
+                    missing_inputs: [],
+                };
+            }
             if (snapshot.open_jobs.length > 0) {
                 return {
                     state: "apply_done",
@@ -160,7 +233,17 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                 missing_inputs: [],
             };
         }
-        case "review":
+        case "review": {
+            const pending = pendingTaskIds(changeRoot);
+            if (pending.length > 0) {
+                return {
+                    state: "review",
+                    path: "next_command",
+                    next_command: reopenCommand(change, pending),
+                    reason: `发现未完成任务 ${pending[0]}，回到执行阶段`,
+                    missing_inputs: [],
+                };
+            }
             return {
                 state: "review",
                 path: "next_command",
@@ -168,6 +251,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                 reason: "审查完成，提交接受",
                 missing_inputs: [],
             };
+        }
         case "accepted":
             return {
                 state: "accepted",

package/dist/sync.js

@@ -78,13 +78,13 @@ function replayEvents(events) {
     }
     return { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition };
 }
-/** 粗粒度失效：检查 accepted job 的 boundFiles 是否仍匹配当前文档 */
-function checkStaleJobs(acceptedJobs, documentDigests) {
+/** 粗粒度失效：检查 job 的 boundFiles 是否仍匹配当前文档 */
+function checkStaleJobs(jobs, changeRoot) {
     const stale = [];
-    for (const job of acceptedJobs) {
+    for (const job of jobs) {
         for (const bf of job.boundFiles) {
-            const current = documentDigests[bf.path];
-            if (current && current !== bf.sha) {
+            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}）`,
@@ -113,10 +113,11 @@ 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 staleInfo = checkStaleJobs(acceptedJobs, documentDigests);
-    // stale 的 job 从 accepted 移除（sync 只反映当前事实）
-    const freshAccepted = acceptedJobs.filter(j => !staleInfo.some(s => s.job_id === j.job_id));
+    // 粗粒度失效检查（只读，不写事件）：snapshot 只暴露当前可执行/可复用 job。
+    const staleOpenInfo = checkStaleJobs(openJobs, changeRoot);
+    const staleAcceptedInfo = checkStaleJobs(acceptedJobs, changeRoot);
+    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 {
         change_id: change,
         state,
@@ -125,7 +126,7 @@ export function rebuildSnapshot(projectRoot, change, changeRoot, openspecStatusD
         document_digests: documentDigests,
         tasks_structure_digest: tsDigest,
         task_statuses: taskStatuses,
-        open_jobs: openJobs,
+        open_jobs: freshOpen,
         accepted_jobs: freshAccepted,
         active_task_attempts: activeAttempts,
         pending_user_decisions: [],

package/dist/transition.d.ts

@@ -28,6 +28,7 @@ export declare function transitionInit(projectRoot: string, change: string, chan
 export declare function transitionExplore(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): 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 reopen(projectRoot: string, change: string, changeRoot: string, to: State, reason: 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;

package/dist/transition.js

@@ -3,7 +3,7 @@ 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, collectProposeOpenQuestions, findTaskInLines, parseTasksMd, tasksStructureDigest } from "./format.js";
+import { validateDiscovery, collectProposeOpenQuestions, findTaskInLines, parseTasksMd, pendingTasksInContent, tasksStructureDigest } from "./format.js";
 let transitionSeq = 0;
 function newTransitionId() { return `T-${Date.now()}-${++transitionSeq}`; }
 let jobSeq = 0;
@@ -78,6 +78,13 @@ function historicalProposeReadyRoles(projectRoot, change) {
 function findTaskLine(lines, taskId) {
     return findTaskInLines(lines, taskId);
 }
+function pendingTaskIds(changeRoot) {
+    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+    return pendingTasksInContent(tasksContent).map(task => task.taskId);
+}
+function formatPendingTaskMessage(ids, action) {
+    return `尚有未完成任务：${ids.join(", ")}；${action}`;
+}
 /**
  * 统一 transition 提交协议——所有校验在锁内。
  */
@@ -275,16 +282,39 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
         },
     });
 }
+// ===== reopen =====
+export function reopen(projectRoot, change, changeRoot, to, reason) {
+    return commitTransition(projectRoot, change, changeRoot, {
+        name: "reopen", idempotencyInputs: { to, reason },
+        decide: (snapshot) => {
+            if (to !== "apply")
+                return { skip: true, message: `reopen 当前只支持 --to apply，不支持 ${to}` };
+            if (!reason || reason.trim() === "")
+                return { skip: true, message: "reopen 需要非空 --reason" };
+            if (snapshot.state !== "apply_done" && snapshot.state !== "review") {
+                return { skip: true, message: `当前状态 ${snapshot.state}，不能 reopen 到 apply` };
+            }
+            const pending = pendingTaskIds(changeRoot);
+            if (pending.length === 0)
+                return { skip: true, message: "没有未完成任务，不能 reopen 到 apply" };
+            return {
+                fromState: snapshot.state,
+                toState: "apply",
+                outcome: "advanced",
+                reason: `${reason.trim()}（pending tasks: ${pending.join(", ")}）`,
+            };
+        },
+    });
+}
 // ===== review-ready =====
 export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
     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: "尚有未完成任务" };
+            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: "所有任务完成" };
@@ -322,6 +352,9 @@ export function accept(projectRoot, change, changeRoot) {
         decide: (snapshot) => {
             if (snapshot.state !== "review")
                 return { skip: true, message: `当前状态 ${snapshot.state}，需要 review` };
+            const pending = pendingTaskIds(changeRoot);
+            if (pending.length > 0)
+                return { skip: true, message: formatPendingTaskMessage(pending, "请先 reopen --to apply 继续执行") };
             return { fromState: "review", toState: "accepted", outcome: "advanced", reason: "审查通过" };
         },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": { "node": ">=20.19.0" },