@peterxiaoyang/superspec 0.1.20 → 0.1.21

package/dist/cli.js

@@ -5,7 +5,7 @@ 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";
@@ -62,6 +62,7 @@ async function main(argv) {
 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 子命令：
@@ -215,6 +216,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.21",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": { "node": ">=20.19.0" },