@peterxiaoyang/superspec 0.1.46 → 0.1.48

package/dist/format.js

@@ -4,6 +4,7 @@
 // 生成与语义判断，不得自行充当格式校验器或在其它地方重复解析。
 import { readFileSync, existsSync, realpathSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { sha256Text } from "./store.js";
 import { GREEN_ONLY_NO_TDD_REASON } from "./types.js";
 // ===== discovery.md =====
 //
@@ -24,7 +25,7 @@ function countOpenChecklistItemsInSection(content, headings) {
     const matches = sectionBody.match(/^\s*-\s+\[ \]/gm);
     return matches ? matches.length : 0;
 }
-function sectionBodyByHeadings(content, headings) {
+function sectionRangeByHeadings(content, headings) {
     const headingPattern = headings.map(escapeRegex).join("|");
     const sectionMatch = new RegExp(`^#{1,6}\\s*(?:${headingPattern})\\s*$`, "im").exec(content);
     if (!sectionMatch)
@@ -33,11 +34,106 @@ function sectionBodyByHeadings(content, headings) {
     // 截取到下一个标题或文件末尾
     const restContent = content.slice(sectionStart);
     const nextHeadingMatch = restContent.match(/^#{1,6}\s+/m);
-    return nextHeadingMatch ? restContent.slice(0, nextHeadingMatch.index) : restContent;
+    return {
+        start: sectionStart,
+        end: nextHeadingMatch ? sectionStart + nextHeadingMatch.index : content.length,
+    };
+}
+function sectionBodyByHeadings(content, headings) {
+    const range = sectionRangeByHeadings(content, headings);
+    return range ? content.slice(range.start, range.end) : null;
+}
+const DISCOVERY_QUESTION_HEADINGS = ["待确认问题", "Open Questions", "Pending Questions"];
+export const EXPLORE_OPEN_QUESTION_SCOPE_PREFIX = "explore_open_question:";
+/**
+ * 当前文档中同一确认事项的稳定键。结合 Q-ID、顺序和原文，避免把本轮开始前
+ * 已经确认的旧事项误认为新答复。
+ */
+export function discoveryQuestionKey(question) {
+    return sha256Text(`${question.id}\n${question.ordinal}\n${question.text}`);
+}
+function normalizedDecisionQuestionText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * 当前决定所依据的规范化问题内容。会改变选择、推荐或影响的事实必须写入该问题项；
+ * 状态机只绑定这份明确依据，不猜测文档其它段落与决定是否相关。
+ */
+export function discoveryQuestionDecisionBasisDigest(question) {
+    const legacyOrdinal = question.id.startsWith("item-") ? String(question.ordinal) : "explicit-id";
+    return sha256Text(`decision-basis:v1\nexplore\n${question.id}\n${legacyOrdinal}\n${normalizedDecisionQuestionText(question.text)}`);
+}
+/**
+ * 计算某一确认事项之外的 Discovery 决策上下文。回写时该事项本身会从问题改为
+ * 结论，因此只归一化这一行；其余事实、证据和其它待确认项的改动都会使指纹失效。
+ */
+export function discoveryQuestionContextFingerprint(content, question) {
+    const range = sectionRangeByHeadings(content, DISCOVERY_QUESTION_HEADINGS);
+    if (!range)
+        return null;
+    const sectionBody = content.slice(range.start, range.end);
+    const checklist = /^\s*-\s+\[([ xX])\]\s+(.*?)\s*$/gm;
+    let ordinal = 0;
+    for (const match of sectionBody.matchAll(checklist)) {
+        ordinal += 1;
+        if (ordinal !== question.ordinal)
+            continue;
+        const lineStart = range.start + match.index;
+        const lineEnd = lineStart + match[0].length;
+        const placeholder = `- [ ] <discovery-question:${question.id}:${question.ordinal}>`;
+        return sha256Text(`${content.slice(0, lineStart)}${placeholder}${content.slice(lineEnd)}`);
+    }
+    return null;
+}
+/** 按文档顺序提取 discovery.md 的全部确认事项。 */
+export function parseDiscoveryQuestions(content) {
+    const sectionBody = sectionBodyByHeadings(content, DISCOVERY_QUESTION_HEADINGS);
+    if (sectionBody == null)
+        return [];
+    const documentFingerprint = sha256Text(content);
+    const questions = [];
+    const checklist = /^\s*-\s+\[([ xX])\]\s+(.*?)\s*$/gm;
+    let ordinal = 0;
+    for (const match of sectionBody.matchAll(checklist)) {
+        ordinal += 1;
+        const text = match[2];
+        const idMatch = /^\s*(Q-[A-Za-z0-9][A-Za-z0-9_-]*)\b/.exec(text);
+        questions.push({
+            id: idMatch?.[1] ?? `item-${ordinal}`,
+            ordinal,
+            text,
+            raw: match[0],
+            documentFingerprint,
+            status: match[1] === " " ? "open" : "closed",
+        });
+    }
+    return questions;
+}
+/** 按文档顺序提取 discovery.md 中尚未确认的问题。 */
+export function parseDiscoveryOpenQuestions(content) {
+    return parseDiscoveryQuestions(content)
+        .filter(question => question.status === "open")
+        .map(({ status: _status, ...question }) => question);
+}
+export function discoveryOpenQuestionScope(question, exploreRoundId) {
+    const fingerprint = sha256Text(`${exploreRoundId}\n${discoveryQuestionDecisionBasisDigest(question)}`);
+    return `${EXPLORE_OPEN_QUESTION_SCOPE_PREFIX}${fingerprint}:${question.id}`;
+}
+/** 兼容升级前已经展示给用户、但尚未登记的 scope。 */
+export function legacyDiscoveryOpenQuestionScope(question, exploreRoundId) {
+    const fingerprint = sha256Text(`${exploreRoundId}\n${question.documentFingerprint}`);
+    return `${EXPLORE_OPEN_QUESTION_SCOPE_PREFIX}${fingerprint}:${question.id}`;
+}
+/** 面向用户展示时隐藏 Q-xxx 这一内部编号；历史无编号问题保持原文。 */
+export function discoveryOpenQuestionDisplayText(question) {
+    if (question.id.startsWith("Q-") && question.text.startsWith(question.id)) {
+        return question.text.slice(question.id.length).replace(/^[\s:：—–-]+/, "").trim();
+    }
+    return question.text.trim();
 }
-/** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
+/** 从 discovery.md 提取“待确认问题”段内的未确认项数量。 */
 export function countDiscoveryOpenQuestions(content) {
-    return countOpenChecklistItemsInSection(content, ["待确认问题", "Open Questions", "Pending Questions"]);
+    return parseDiscoveryOpenQuestions(content).length;
 }
 const DISCOVERY_CHAIN_HEADINGS = ["链路五要素"];
 const DISCOVERY_CHAIN_REQUIRED_COLUMNS = [
@@ -88,24 +184,30 @@ export function validateDiscoveryChainCoverage(content) {
     }
     const statusIdx = header.indexOf("状态");
     const requiredColumnIndexes = DISCOVERY_CHAIN_REQUIRED_COLUMNS.map(col => ({ col, idx: header.indexOf(col) }));
+    const errors = [];
     for (const [idx, cells] of rows.entries()) {
         const rowNum = idx + 1;
         for (const { col, idx: colIdx } of requiredColumnIndexes) {
             if (!(cells[colIdx]?.trim())) {
-                return { ok: false, message: `链路五要素第 ${rowNum} 行缺少${col}`, present: true };
+                errors.push(`链路五要素第 ${rowNum} 行缺少${col}`);
             }
         }
         const status = cells[statusIdx]?.trim() ?? "";
         if (!DISCOVERY_CHAIN_STATUSES.has(status)) {
-            return { ok: false, message: `链路五要素第 ${rowNum} 行状态必须是 已确认、未知阻塞 或 未知非阻塞`, present: true };
+            errors.push(`链路五要素第 ${rowNum} 行状态必须是 已确认、未知阻塞 或 未知非阻塞`);
         }
         if (status.includes("未知阻塞") && countDiscoveryOpenQuestions(content) === 0) {
-            return { ok: false, message: "链路五要素存在未知阻塞，但待确认问题中没有未解决项", present: true };
+            errors.push("链路五要素存在未知阻塞，但待确认问题中没有未解决项");
         }
     }
+    if (errors.length > 0)
+        return { ok: false, message: [...new Set(errors)].join("；"), present: true };
     return { ok: true, message: "链路五要素就绪", present: true };
 }
-/** 完整校验 discovery.md：存在 + 非空 + 无未确认问题 */
+/**
+ * 校验 discovery.md 的可解析结构。未确认问题不是格式错误：next 会把第一个问题
+ * 作为当前用户决策返回；只有缺文档、空文档或已声明链路的结构错误才在此阻断。
+ */
 export function validateDiscovery(changeRoot) {
     const path = join(changeRoot, ".superspec", "artifacts", "discovery.md");
     if (!existsSync(path))
@@ -117,16 +219,90 @@ export function validateDiscovery(changeRoot) {
     if (!chainCoverage.ok)
         return { ok: false, message: chainCoverage.message, 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 };
+    return {
+        ok: true,
+        message: openCount > 0 ? `discovery.md 结构有效，有 ${openCount} 个待确认问题` : "discovery.md 就绪",
+        openCount,
+    };
 }
+export const PROPOSE_OPEN_QUESTION_SCOPE_PREFIX = "propose_open_question:";
 const PROPOSE_CONFIRMATION_DOCS = [
     "proposal.md",
     "design.md",
     ".superspec/artifacts/test-contract.md",
 ];
 const PROPOSE_CONFIRMATION_HEADINGS = ["待用户确认", "待确认问题", "Open Questions", "Pending Questions"];
+export function parseProposeQuestions(content, path) {
+    const sectionBody = sectionBodyByHeadings(content, PROPOSE_CONFIRMATION_HEADINGS);
+    if (sectionBody == null)
+        return [];
+    const documentFingerprint = sha256Text(content);
+    const questions = [];
+    const checklist = /^\s*-\s+\[([ xX])\]\s+(.*?)\s*$/gm;
+    let ordinal = 0;
+    for (const match of sectionBody.matchAll(checklist)) {
+        ordinal += 1;
+        const text = match[2];
+        const idMatch = /^\s*(DEC-[A-Za-z0-9][A-Za-z0-9_-]*)\b/.exec(text);
+        questions.push({
+            path,
+            id: idMatch?.[1] ?? `item-${ordinal}`,
+            ordinal,
+            text,
+            raw: match[0],
+            documentFingerprint,
+            status: match[1] === " " ? "open" : "closed",
+        });
+    }
+    return questions;
+}
+export function proposeQuestionKey(question) {
+    return sha256Text(`${question.path}\n${question.id}\n${question.ordinal}\n${question.text}`);
+}
+/** Propose 决定的明确依据；其它计划材料变化不会自动使已展示决定失效。 */
+export function proposeQuestionDecisionBasisDigest(question) {
+    const legacyOrdinal = question.id.startsWith("item-") ? String(question.ordinal) : "explicit-id";
+    return sha256Text(`decision-basis:v1\npropose\n${question.path}\n${question.id}\n${legacyOrdinal}\n${normalizedDecisionQuestionText(question.text)}`);
+}
+export function proposeQuestionContextFingerprint(content, question) {
+    const range = sectionRangeByHeadings(content, PROPOSE_CONFIRMATION_HEADINGS);
+    if (!range)
+        return null;
+    const sectionBody = content.slice(range.start, range.end);
+    const checklist = /^\s*-\s+\[([ xX])\]\s+(.*?)\s*$/gm;
+    let ordinal = 0;
+    for (const match of sectionBody.matchAll(checklist)) {
+        ordinal += 1;
+        if (ordinal !== question.ordinal)
+            continue;
+        const lineStart = range.start + match.index;
+        const lineEnd = lineStart + match[0].length;
+        const placeholder = `- [ ] <propose-question:${question.id}:${question.ordinal}>`;
+        return sha256Text(`${content.slice(0, lineStart)}${placeholder}${content.slice(lineEnd)}`);
+    }
+    return null;
+}
+export function proposeOpenQuestionScope(question, proposeRoundId) {
+    const fingerprint = sha256Text(`${proposeRoundId}\n${proposeQuestionDecisionBasisDigest(question)}`);
+    return `${PROPOSE_OPEN_QUESTION_SCOPE_PREFIX}${fingerprint}:${question.id}`;
+}
+/** 兼容升级前已经展示给用户、但尚未登记的 scope。 */
+export function legacyProposeOpenQuestionScope(question, proposeRoundId) {
+    const fingerprint = sha256Text(`${proposeRoundId}\n${question.path}\n${question.documentFingerprint}`);
+    return `${PROPOSE_OPEN_QUESTION_SCOPE_PREFIX}${fingerprint}:${question.id}`;
+}
+export function proposeOpenQuestionDisplayText(question) {
+    if (question.id.startsWith("DEC-") && question.text.startsWith(question.id)) {
+        return question.text.slice(question.id.length).replace(/^[\s:：—–-]+/, "").trim();
+    }
+    return question.text.trim();
+}
+export function collectProposeQuestions(changeRoot) {
+    return PROPOSE_CONFIRMATION_DOCS.flatMap(path => {
+        const fullPath = join(changeRoot, path);
+        return existsSync(fullPath) ? parseProposeQuestions(readFileSync(fullPath, "utf8"), path) : [];
+    });
+}
 export function countProposeOpenQuestionsInContent(content) {
     return countOpenChecklistItemsInSection(content, PROPOSE_CONFIRMATION_HEADINGS);
 }
@@ -327,8 +503,17 @@ export function adoptedContractForTask(content, taskId, contractMode) {
     const parsed = executionRequirementForTask(content, taskId);
     return { parsed, contract: contractMode ? parsed?.contract ?? null : null };
 }
+/**
+ * Fix task 由状态机从已批准的实现范围派生；它没有 proposal 阶段执行依据块。
+ * REVIEW-FIX-* 是发布前已有的持久化 task ID，FIX-SELFTEST-* 是当前引擎生成的
+ * 自测修复 task。不能把通用 FIX-* 前缀保留为内部命名空间。
+ */
+export function isFixTaskId(taskId) {
+    return taskId.startsWith("REVIEW-FIX-") || taskId.startsWith("FIX-SELFTEST-");
+}
+/** @deprecated 新代码使用 isFixTaskId；保留给旧扩展和历史调用。 */
 export function isReviewFixTaskId(taskId) {
-    return taskId.startsWith("REVIEW-FIX-");
+    return isFixTaskId(taskId);
 }
 export function isCharacterizationTask(task) {
     return task.tddRequired === false && task.noTddReason === "characterization";
@@ -449,6 +634,31 @@ function documentAnchorParts(anchor) {
         ? parts
         : [anchor];
 }
+function documentAnchorCandidates(content, path, requested) {
+    const candidates = [];
+    for (const match of content.matchAll(/^#{1,6}[\t ]+(.+?)(?:[\t ]+#+)?[\t ]*$/gm)) {
+        const anchor = match[1]?.trim();
+        if (anchor)
+            candidates.push({ anchor, index: match.index ?? candidates.length });
+    }
+    for (const match of content.matchAll(/(?:^|[^A-Za-z0-9_-])((?:TEST|CHAIN|IDC)-[A-Za-z0-9_-]+)(?![A-Za-z0-9_-])/gm)) {
+        candidates.push({ anchor: match[1], index: match.index ?? candidates.length });
+    }
+    const normalizedRequested = requested.toLocaleLowerCase();
+    const score = (anchor) => {
+        const normalized = anchor.toLocaleLowerCase();
+        if (normalized === normalizedRequested)
+            return 100;
+        if (normalized.includes(normalizedRequested) || normalizedRequested.includes(normalized))
+            return 50;
+        const requestedTokens = new Set(normalizedRequested.split(/[^\p{L}\p{N}_-]+/u).filter(Boolean));
+        return normalized.split(/[^\p{L}\p{N}_-]+/u).filter(Boolean).filter(token => requestedTokens.has(token)).length * 10;
+    };
+    return [...new Map(candidates.map(candidate => [candidate.anchor, candidate])).values()]
+        .sort((left, right) => score(right.anchor) - score(left.anchor) || left.index - right.index)
+        .slice(0, 8)
+        .map(candidate => `${path}#${candidate.anchor}`);
+}
 function canonicalDocumentRefPath(path) {
     if (path === "discovery.md" || path === "test-contract.md") {
         return join(".superspec", "artifacts", path);
@@ -495,7 +705,8 @@ export function validateExecutionRequirementDocumentReferences(changeRoot, contr
             const targetContent = readFileSync(target, "utf8");
             for (const anchor of documentAnchorParts(parsed.anchor)) {
                 if (!documentContainsAnchor(targetContent, anchor)) {
-                    errors.push(`${contract.taskId} 的引用锚点不存在：${parsed.path}#${anchor}`);
+                    const candidates = documentAnchorCandidates(targetContent, parsed.path, anchor);
+                    errors.push(`${contract.taskId} 的引用锚点不存在：${parsed.path}#${anchor}${candidates.length > 0 ? `；可用锚点：${candidates.join("、")}` : ""}`);
                 }
             }
         }
@@ -510,7 +721,7 @@ export function validateExecutionRequirements(content, testContractContent, exec
     const hasLegacyGreenOnlyTask = tasks.some(task => task.noTddReason === GREEN_ONLY_NO_TDD_REASON);
     // v2 不允许“所有任务都没有执行依据”这一静默回退：新 Propose 的每个普通
     // task 都必须显式声明五字段。v1 的缺失版本仍保留旧的按需契约语义。
-    const hasV2OrdinaryTask = executionRequirementVersion === 2 && tasks.some(task => !isReviewFixTaskId(task.taskId));
+    const hasV2OrdinaryTask = executionRequirementVersion === 2 && tasks.some(task => !isFixTaskId(task.taskId));
     const mode = hasTaskBoundExecutionRequirements(content) || hasLegacyGreenOnlyTask || hasV2OrdinaryTask;
     const contracts = parseExecutionRequirements(content);
     // 孤儿检测必须在 mode=false 的 early return 之前：全部块都悬空时 mode=false，
@@ -532,11 +743,11 @@ export function validateExecutionRequirements(content, testContractContent, exec
         }
         // v2 是本次改造后的新计划：每个普通 task 必须声明完整五字段，
         // `测试:` 可显式为空以表达非行为任务。旧计划只保持原 TDD 契约要求。
-        if (executionRequirementVersion === 2 && !isReviewFixTaskId(task.taskId) && !contract) {
+        if (executionRequirementVersion === 2 && !isFixTaskId(task.taskId) && !contract) {
             errors.push(`${task.taskId} 缺少执行依据`);
             continue;
         }
-        if (executionRequirementVersion === 1 && task.tddRequired && !isReviewFixTaskId(task.taskId) && !contract) {
+        if (executionRequirementVersion === 1 && task.tddRequired && !isFixTaskId(task.taskId) && !contract) {
             errors.push(`${task.taskId} 缺少执行依据`);
             continue;
         }

package/dist/next.d.ts

@@ -1,3 +1,3 @@
 import type { NextOutput } from "./types.ts";
-/** next 命令：读 snapshot，返回唯一可执行路径 */
+/** next 命令：读取当前状态，返回唯一可执行路径，并登记正式展示的用户问题。 */
 export declare function next(projectRoot: string, change: string, changeRoot: string, defaultRisk?: import("./review.ts").ReviewRisk): NextOutput;

package/dist/next.js

@@ -1,9 +1,73 @@
 // SuperSpec 流程引擎 — next：返回可执行路径
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { rebuildSnapshot } from "./sync.js";
-import { readEvents } from "./store.js";
+import { appendEvent, makeEvent, readEvents, withLock } from "./store.js";
 import { requiredJobActions } from "./job_action.js";
 import { planNextStep } from "./phase_plan.js";
 import { workflowRiskForProject } from "./workflow_config.js";
+import { currentExploreRoundId } from "./explore_round.js";
+import { currentProposeRoundId } from "./propose_round.js";
+import { discoveryQuestionDecisionBasisDigest, legacyDiscoveryOpenQuestionScope, parseDiscoveryOpenQuestions, collectProposeQuestions, proposeQuestionDecisionBasisDigest, legacyProposeOpenQuestionScope, } from "./format.js";
+function recordPresentedQuestion(projectRoot, change, changeRoot, output) {
+    if (output.path !== "ask_user")
+        return;
+    const isExplore = output.ask_user.scope.startsWith("explore_open_question:");
+    const isPropose = output.ask_user.scope.startsWith("propose_open_question:");
+    if (!isExplore && !isPropose)
+        return;
+    const events = readEvents(projectRoot, change);
+    if (isExplore) {
+        const current = parseDiscoveryOpenQuestions(readFileSync(join(changeRoot, ".superspec", "artifacts", "discovery.md"), "utf8"))[0];
+        if (!current)
+            return;
+        const roundId = currentExploreRoundId(events);
+        const latest = [...events].reverse().find(event => {
+            if (event.event_type !== "user_question_presented")
+                return false;
+            const payload = event.payload;
+            return payload.phase === "explore" && payload.round_id === roundId && payload.question_id === current.id &&
+                (!current.id.startsWith("item-") || payload.question_ordinal === current.ordinal);
+        });
+        if (latest?.payload?.scope === output.ask_user.scope)
+            return;
+        appendEvent(projectRoot, change, makeEvent(change, "user_question_presented", {
+            phase: "explore",
+            round_id: roundId,
+            scope: output.ask_user.scope,
+            legacy_scope: legacyDiscoveryOpenQuestionScope(current, roundId),
+            question: output.ask_user.question,
+            question_id: current.id,
+            question_ordinal: current.ordinal,
+            decision_basis_digest: discoveryQuestionDecisionBasisDigest(current),
+        }));
+        return;
+    }
+    const current = collectProposeQuestions(changeRoot).find(question => question.status === "open");
+    if (!current)
+        return;
+    const roundId = currentProposeRoundId(events);
+    const latest = [...events].reverse().find(event => {
+        if (event.event_type !== "user_question_presented")
+            return false;
+        const payload = event.payload;
+        return payload.phase === "propose" && payload.round_id === roundId && payload.path === current.path && payload.question_id === current.id &&
+            (!current.id.startsWith("item-") || payload.question_ordinal === current.ordinal);
+    });
+    if (latest?.payload?.scope === output.ask_user.scope)
+        return;
+    appendEvent(projectRoot, change, makeEvent(change, "user_question_presented", {
+        phase: "propose",
+        round_id: roundId,
+        scope: output.ask_user.scope,
+        legacy_scope: legacyProposeOpenQuestionScope(current, roundId),
+        question: output.ask_user.question,
+        path: current.path,
+        question_id: current.id,
+        question_ordinal: current.ordinal,
+        decision_basis_digest: proposeQuestionDecisionBasisDigest(current),
+    }));
+}
 function requiredJobsOutput(state, change, jobs, reason) {
     return {
         state,
@@ -33,8 +97,24 @@ function toNextOutput(change, plan) {
     switch (plan.kind) {
         case "required_jobs":
             return requiredJobsOutput(plan.state, change, plan.jobs, plan.reason);
+        case "artifact_required":
+            return {
+                state: plan.state,
+                path: "artifact_required",
+                artifact: plan.artifact,
+                resume: plan.resume,
+                reason: plan.reason,
+            };
         case "ask_user":
             return { state: plan.state, path: "ask_user", ask_user: plan.ask, reason: plan.reason };
+        case "material_update_required":
+            return {
+                state: plan.state,
+                path: "material_update_required",
+                errors: plan.errors,
+                resume: { argv: ["superspec", "transition", "next", "--change", change] },
+                reason: plan.reason,
+            };
         case "run_transition":
             return {
                 state: plan.state,
@@ -52,16 +132,21 @@ function toNextOutput(change, plan) {
             };
     }
 }
-/** next 命令：读 snapshot，返回唯一可执行路径 */
+/** next 命令：读取当前状态，返回唯一可执行路径，并登记正式展示的用户问题。 */
 export function next(projectRoot, change, changeRoot, defaultRisk = workflowRiskForProject(projectRoot)) {
-    const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
-    const events = readEvents(projectRoot, change);
-    const plannedNextStep = planNextStep({ projectRoot, change, changeRoot, events, snapshot, mode: { kind: "risk", risk: defaultRisk } });
-    if (plannedNextStep)
-        return toNextOutput(change, plannedNextStep);
-    return {
-        state: snapshot.state,
-        path: "done",
-        reason: `状态 ${snapshot.state} 没有可执行下一步`,
-    };
+    return withLock(projectRoot, change, () => {
+        const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
+        const events = readEvents(projectRoot, change);
+        const plannedNextStep = planNextStep({ projectRoot, change, changeRoot, events, snapshot, mode: { kind: "risk", risk: defaultRisk } });
+        if (plannedNextStep) {
+            const output = toNextOutput(change, plannedNextStep);
+            recordPresentedQuestion(projectRoot, change, changeRoot, output);
+            return output;
+        }
+        return {
+            state: snapshot.state,
+            path: "done",
+            reason: `状态 ${snapshot.state} 没有可执行下一步`,
+        };
+    });
 }

package/dist/openspec.js

@@ -1,8 +1,26 @@
 // SuperSpec 流程引擎 — OpenSpec 探测
-import { execSync, execFileSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
+function isTestMode() {
+    return process.env.SUPERSPEC_TEST_MODE === "1" || process.env.NODE_ENV === "test";
+}
+function runtimePlatform() {
+    return isTestMode() ? process.env.SUPERSPEC_TEST_PLATFORM ?? process.platform : process.platform;
+}
+function windowsCommandHost() {
+    return process.env.ComSpec ?? "cmd.exe";
+}
+/**
+ * 在 Windows 上，npm 安装的 CLI 是 .cmd 启动器，不能被 execFileSync 直接执行。
+ * 保留数组参数传递；只有启动器这一层通过 cmd.exe 运行。
+ */
+function execOpenSpec(args, options) {
+    if (runtimePlatform() !== "win32")
+        return execFileSync("openspec", args, options);
+    return execFileSync(windowsCommandHost(), ["/d", "/s", "/c", "openspec.cmd", ...args], options);
+}
 /** B2 修复：校验 change 字符集，防 shell 注入 */
 function validateChange(change) {
     if (!/^[A-Za-z0-9._-]+$/.test(change)) {
@@ -11,7 +29,10 @@ function validateChange(change) {
 }
 export function probeOpenSpec(projectRoot, change) {
     try {
-        const version = execSync("openspec --version 2>/dev/null", { encoding: "utf8" }).trim();
+        const version = execOpenSpec(["--version"], {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "ignore"],
+        }).trim();
         let changeExists = false;
         if (change) {
             validateChange(change);
@@ -26,8 +47,8 @@ export function probeOpenSpec(projectRoot, change) {
 export function openspecStatus(projectRoot, change) {
     validateChange(change);
     try {
-        // B2 修复：用 execFileSync 数组传参，彻底避免 shell 解析
-        const result = execFileSync("openspec", ["status", "--change", change, "--json"], {
+        // B2 修复：参数始终走数组；Windows 仅通过 cmd.exe 运行 .cmd 启动器。
+        const result = execOpenSpec(["status", "--change", change, "--json"], {
             encoding: "utf8", cwd: projectRoot, stdio: ["pipe", "pipe", "ignore"],
         });
         return "sha256:" + createHash("sha256").update(result).digest("hex");
@@ -45,7 +66,7 @@ export function openspecStatus(projectRoot, change) {
 export function validateOpenSpecChange(projectRoot, change) {
     validateChange(change);
     try {
-        execFileSync("openspec", ["validate", change, "--type", "change", "--strict", "--no-interactive"], {
+        execOpenSpec(["validate", change, "--type", "change", "--strict", "--no-interactive"], {
             cwd: projectRoot,
             encoding: "utf8",
             stdio: ["pipe", "pipe", "pipe"],

package/dist/phase_confirmation.js

@@ -1,10 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { currentGitHead, dirtyCodeFiles } from "./git_state.js";
 import { historicalProposeReadyRoles, reviewEvidenceDigest, reviewGateRoleResolution } from "./review.js";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
 import { changeRoot as openspecChangeRoot } from "./openspec.js";
 import { findLatestEvent, sha256Text } from "./store.js";
+import { parseExecutionRequirements, parseTasksMd, parseTestContractEntries } from "./format.js";
 import { hasFrozenWorkflowModeForProposeRound, workflowRiskForProject, workflowRiskForState, } from "./workflow_config.js";
 export const PHASE_CONFIRMATION_SCOPE_PREFIX = "phase_confirmation:";
+function taskTitle(content, task) {
+    const line = content.split("\n")[task.lineIdx] ?? "";
+    return line.replace(/^-\s+\[[ xX]\]\s+\S+\s*/, "").trim() || task.taskId;
+}
+function taskSummaryField(lines, task, labels) {
+    for (let index = task.lineIdx + 1; index < lines.length; index++) {
+        const line = lines[index];
+        if (/^-\s+\[[ xX]\]\s+\S+/.test(line) || /^#{1,6}\s+/.test(line))
+            break;
+        const match = /^\s*-\s*([^:：]+)\s*[:：]\s*(.+?)\s*$/.exec(line);
+        if (match && labels.includes(match[1].trim()))
+            return match[2].trim();
+    }
+    return null;
+}
+/**
+ * 这是阶段确认的临时阅读面，不是新的计划格式或 gate。优先读取 task 已声明的
+ * 交付/依赖/验收；缺省项如实标为未声明，避免将任务顺序臆造成真实依赖。
+ */
+function proposeTaskDeliverySummary(changeRoot) {
+    const tasksPath = join(changeRoot, "tasks.md");
+    if (!existsSync(tasksPath))
+        return null;
+    const tasksContent = readFileSync(tasksPath, "utf8");
+    const tasks = parseTasksMd(tasksContent);
+    if (tasks.length === 0)
+        return null;
+    const contracts = new Map(parseExecutionRequirements(tasksContent).map(item => [item.taskId, item.contract]));
+    const testContractPath = join(changeRoot, ".superspec", "artifacts", "test-contract.md");
+    const parsedTests = existsSync(testContractPath)
+        ? parseTestContractEntries(readFileSync(testContractPath, "utf8"))
+        : null;
+    const scenarios = parsedTests?.ok
+        ? new Map(parsedTests.entries.map(entry => [entry.test_id, entry.scenario]))
+        : new Map();
+    const lines = tasksContent.split("\n");
+    // Propose 展示的是当前计划，不是旧 Apply 轮的执行历史。重新打开同一 task 时，
+    // 当前 tasks.md 中的未勾选状态明确表示它已重新纳入本轮待实施范围。
+    const pendingTasks = tasks.filter(task => !task.done);
+    const completedCount = tasks.length - pendingTasks.length;
+    const items = pendingTasks.map((task, index) => {
+        const contract = contracts.get(task.taskId);
+        const explicitDelivery = taskSummaryField(lines, task, ["交付", "Delivery"]);
+        const explicitDependency = taskSummaryField(lines, task, ["依赖", "Dependencies", "Depends On"]);
+        const firstTest = contract?.tests[0];
+        const testScenario = firstTest ? scenarios.get(firstTest) : null;
+        const delivery = explicitDelivery ?? contract?.acceptance ?? taskTitle(tasksContent, task);
+        const dependency = explicitDependency ?? "无明确前置交付";
+        const acceptance = contract?.acceptance
+            ?? (testScenario ? `${firstTest}：${testScenario}` : "计划未单独声明验收");
+        return [
+            `${index + 1}. ${task.taskId} ${taskTitle(tasksContent, task)}`,
+            `   - 交付：${delivery}`,
+            `   - 依赖：${dependency}`,
+            `   - 验收：${acceptance}`,
+        ].join("\n");
+    });
+    const status = completedCount === 0
+        ? ""
+        : `已完成 ${completedCount} 项；${pendingTasks.length === 0 ? "当前没有待实施任务。" : `以下 ${pendingTasks.length} 项仍待实施或调整。`}\n\n`;
+    return `执行计划概览\n\n${status}${items.join("\n\n")}`;
+}
 function latestTransition(events, predicate) {
     return findLatestEvent(events, "transition_commit", event => predicate(event.payload));
 }
@@ -58,6 +123,7 @@ const SPECS = {
         epoch: events => latestTransition(events, payload => payload.from_state === "apply" && payload.to_state === "apply_done"),
     },
 };
+const CURRENT_USER_DECISION_NOTICE = "请向用户展示本次选择并等待当前明确答复；不得用启动工作流、要求推进、一般授权、历史偏好或模型推断代替本次回答。";
 function boundaryForState(state) {
     switch (state) {
         case "explore": return "explore_to_propose";
@@ -187,7 +253,12 @@ export function phaseConfirmationForBoundary(projectRoot, events, snapshot, boun
     const epochEventId = epoch?.event_id ?? `legacy-${spec.state}`;
     const digest = materialDigest(projectRoot, events, snapshot, boundary, risk);
     const scope = `${spec.scopePrefix}:${epochEventId}:${digest}`;
-    const actions = buildActions(snapshot.change_id, boundary, scope, spec.question, spec.actions, risk);
+    const summary = boundary === "propose_to_apply"
+        ? proposeTaskDeliverySummary(openspecChangeRoot(projectRoot, snapshot.change_id))
+        : null;
+    const boundaryQuestion = `${spec.question}\n\n${CURRENT_USER_DECISION_NOTICE}`;
+    const question = summary ? `${summary}\n\n${boundaryQuestion}` : boundaryQuestion;
+    const actions = buildActions(snapshot.change_id, boundary, scope, question, spec.actions, risk);
     return {
         boundary,
         epoch_event_id: epochEventId,
@@ -195,7 +266,7 @@ export function phaseConfirmationForBoundary(projectRoot, events, snapshot, boun
         scope,
         actions,
         ask: {
-            question: spec.question,
+            question,
             allowed_answers: actions.map(action => action.label),
             scope,
             actions,