@peterxiaoyang/superspec 0.1.47 → 0.1.48

package/dist/cli.js

@@ -66,7 +66,7 @@ function transitionExitCode(result) {
 function proposeReadyExitCode(result) {
     if (result.outcome === "blocked")
         return 0;
-    return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
+    return result.events_written === 0 && result.outcome === "advanced" && result.from_state === result.to_state ? 1 : 0;
 }
 function ensureWorkflowMode(projectRoot, _opts) {
     try {
@@ -493,10 +493,8 @@ async function askToUpdateSelfIfNeeded(projectRoot, rerunArgs) {
 // ===== 初始化 transition init =====
 // ===== init/explore 现在在 transition.ts 中（走统一锁内路径）=====
 // ===== 主分发 =====
-async function main(argv) {
-    // --help / 无参数 → 打印用法
-    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-        console.log(`SuperSpec 流程引擎 ${SUPERSPEC_VERSION}
+function topLevelHelp() {
+    return `SuperSpec 流程引擎 ${SUPERSPEC_VERSION}
 
 用法：superspec <命令> [选项]
 
@@ -507,8 +505,8 @@ async function main(argv) {
   jobs <子命令> --change <C>        工作项管理（见下）
   install                           安装项目工作流入口
   init --scope project              install 的兼容别名
-  update                           升级 CLI 到 npm latest 并同步项目工作流模板
-  version                          版本号
+  update                            升级 CLI 到 npm latest 并同步项目工作流模板
+  version                           版本号
 
 transition 子命令：
   init / explore / sync / next / propose-ready / start-apply
@@ -525,7 +523,49 @@ record 子命令：
 
 jobs 子命令：
   list / packet --job <J>
-`);
+`;
+}
+function commandHelp(command, subcommand) {
+    if (command === "record" && subcommand === "user-decision") {
+        return `用法：superspec record user-decision --change <C> --input <F|->
+
+从 JSON 文件读取用户决定；--input - 表示从 stdin 读取。
+输入至少包含 scope 和 answer，工作流给出的 question 可一并保留。
+
+示例：
+  printf '%s' '{"scope":"<next 返回的 scope>","question":"<原问题>","answer":"<用户答复>"}' | superspec record user-decision --change <C> --input -
+`;
+    }
+    if (command === "record" && subcommand === "job-submit") {
+        return `用法：superspec record job-submit --change <C> --job <J> --report <F|->
+
+提交 reviewer JSON 报告；--report - 表示从 stdin 读取。报告契约以 jobs packet 返回的 report_schema 为准。
+
+示例：
+  superspec jobs packet --change <C> --job <J>
+  superspec record job-submit --change <C> --job <J> --report report.json
+`;
+    }
+    if (command === "record" && subcommand === "test-run") {
+        return `用法：superspec record test-run --change <C> --input <F|->
+
+登记测试证据；--input - 表示从 stdin 读取。输入需包含 test_id、task_structure_digest、command、cwd、exit_code 和 semantic_status。
+
+示例：
+  printf '%s' '{"test_id":"TEST-001","task_structure_digest":"sha256:<digest>","command":"npm test","cwd":"<project>","exit_code":0,"semantic_status":"expected_success"}' | superspec record test-run --change <C> --input -
+`;
+    }
+    if (command === "transition" && subcommand === "propose-ready") {
+        return `用法：superspec transition propose-ready --change <C>
+
+校验当前计划材料和审查门禁；满足条件时推进到 propose_ready。工作流模式来自项目配置，不接受 --risk。
+`;
+    }
+    return topLevelHelp();
+}
+async function main(argv) {
+    if (argv.length === 0) {
+        console.log(topLevelHelp());
         return 0;
     }
     // version
@@ -534,6 +574,10 @@ jobs 子命令：
         return 0;
     }
     const { command, subcommand, opts } = parseArgs(argv);
+    if (argv.includes("--help") || argv.includes("-h") || command === "--help" || command === "-h") {
+        console.log(commandHelp(command, subcommand));
+        return 0;
+    }
     const projectRoot = process.cwd();
     // install / init / update 不需要 --change
     if (command === "install" || command === "init") {

package/dist/explore_round.d.ts

@@ -15,9 +15,11 @@ export declare function exploreAnswerRegistrationPayload(discoveryContent: strin
     };
 };
 /** 当前确认事项已通过本轮主流程登记过答复。 */
-export declare function exploreAnswerWasRecorded(events: readonly Event[], roundId: string, question: Pick<DiscoveryQuestion, "id" | "ordinal">, discoveryContent: string): boolean;
+export declare function exploreAnswerWasRecorded(events: readonly Event[], roundId: string, question: Pick<DiscoveryQuestion, "id" | "ordinal" | "text">, discoveryContent: string): boolean;
 /**
  * 新协议轮次中，被回写为已确认的事项必须有对应答复记录。
  * 进入本轮前已经关闭的事项作为基线保留，历史 change 因缺少协议标记整体兼容。
  */
 export declare function unregisteredClosedExploreQuestions(events: readonly Event[], discoveryContent: string): DiscoveryQuestion[];
+/** 已正式展示但尚未登记答复的 Explore 问题不能通过删除问题行绕过。 */
+export declare function unresolvedPresentedExploreQuestionScopes(events: readonly Event[]): string[];

package/dist/explore_round.js

@@ -1,4 +1,4 @@
-import { discoveryQuestionContextFingerprint, discoveryQuestionKey, parseDiscoveryQuestions, } from "./format.js";
+import { discoveryQuestionContextFingerprint, discoveryQuestionDecisionBasisDigest, discoveryQuestionKey, parseDiscoveryQuestions, } from "./format.js";
 const EXPLORE_ANSWER_REGISTRATION_VERSION = 1;
 function isExploreRoundEntry(event) {
     if (event.event_type !== "transition_commit")
@@ -68,16 +68,20 @@ export function exploreAnswerWasRecorded(events, roundId, question, discoveryCon
     const currentContextFingerprint = discoveryQuestionContextFingerprint(discoveryContent, question);
     if (!currentContextFingerprint)
         return false;
+    const currentBasisDigest = discoveryQuestionDecisionBasisDigest(question);
     return events.some(event => {
         if (event.event_type !== "user_decision_recorded")
             return false;
         const payload = event.payload;
         const recorded = payload.explore_open_question;
+        const revisionMatches = typeof recorded?.decision_basis_digest === "string"
+            ? recorded.decision_basis_digest === currentBasisDigest
+            : recorded?.context_fingerprint === currentContextFingerprint;
         return payload.accepted === true &&
             recorded?.round_id === roundId &&
             recorded.question_id === question.id &&
-            recorded.question_ordinal === question.ordinal &&
-            recorded.context_fingerprint === currentContextFingerprint;
+            (!question.id.startsWith("item-") || recorded.question_ordinal === question.ordinal) &&
+            revisionMatches;
     });
 }
 /**
@@ -92,3 +96,44 @@ export function unregisteredClosedExploreQuestions(events, discoveryContent) {
         !registration.baselineClosedQuestionKeys.has(discoveryQuestionKey(question)) &&
         !exploreAnswerWasRecorded(events, registration.roundId, question, discoveryContent));
 }
+/** 已正式展示但尚未登记答复的 Explore 问题不能通过删除问题行绕过。 */
+export function unresolvedPresentedExploreQuestionScopes(events) {
+    const roundId = currentExploreRoundId(events);
+    const acceptedDecisions = events.flatMap(event => {
+        if (event.event_type !== "user_decision_recorded")
+            return [];
+        const payload = event.payload;
+        return payload.accepted === true ? [payload] : [];
+    });
+    const latestByQuestion = new Map();
+    for (const event of events) {
+        if (event.event_type !== "user_question_presented")
+            continue;
+        const payload = event.payload;
+        if (payload.phase !== "explore" || payload.round_id !== roundId || typeof payload.scope !== "string" || typeof payload.question_id !== "string")
+            continue;
+        const identity = payload.question_id.startsWith("item-")
+            ? `${payload.question_id}:${String(payload.question_ordinal)}`
+            : payload.question_id;
+        latestByQuestion.set(identity, {
+            scope: payload.scope,
+            legacyScope: typeof payload.legacy_scope === "string" ? payload.legacy_scope : null,
+            questionId: payload.question_id,
+            questionOrdinal: payload.question_ordinal,
+            revisionDigest: payload.decision_basis_digest,
+        });
+    }
+    return [...latestByQuestion.values()].flatMap(presented => {
+        const answered = acceptedDecisions.some(decision => {
+            if (decision.scope === presented.scope || decision.scope === presented.legacyScope)
+                return true;
+            const recorded = decision.explore_open_question;
+            return recorded?.round_id === roundId &&
+                recorded.question_id === presented.questionId &&
+                (!presented.questionId.startsWith("item-") || recorded.question_ordinal === presented.questionOrdinal) &&
+                typeof presented.revisionDigest === "string" &&
+                recorded.decision_basis_digest === presented.revisionDigest;
+        });
+        return answered ? [] : [presented.scope];
+    });
+}

package/dist/format.d.ts

@@ -26,6 +26,11 @@ export interface DiscoveryQuestion extends DiscoveryOpenQuestion {
  * 已经确认的旧事项误认为新答复。
  */
 export declare function discoveryQuestionKey(question: Pick<DiscoveryQuestion, "id" | "ordinal" | "text">): string;
+/**
+ * 当前决定所依据的规范化问题内容。会改变选择、推荐或影响的事实必须写入该问题项；
+ * 状态机只绑定这份明确依据，不猜测文档其它段落与决定是否相关。
+ */
+export declare function discoveryQuestionDecisionBasisDigest(question: Pick<DiscoveryQuestion, "id" | "ordinal" | "text">): string;
 /**
  * 计算某一确认事项之外的 Discovery 决策上下文。回写时该事项本身会从问题改为
  * 结论，因此只归一化这一行；其余事实、证据和其它待确认项的改动都会使指纹失效。
@@ -35,7 +40,9 @@ export declare function discoveryQuestionContextFingerprint(content: string, que
 export declare function parseDiscoveryQuestions(content: string): DiscoveryQuestion[];
 /** 按文档顺序提取 discovery.md 中尚未确认的问题。 */
 export declare function parseDiscoveryOpenQuestions(content: string): DiscoveryOpenQuestion[];
-export declare function discoveryOpenQuestionScope(question: Pick<DiscoveryOpenQuestion, "id" | "documentFingerprint">, exploreRoundId: string): string;
+export declare function discoveryOpenQuestionScope(question: Pick<DiscoveryOpenQuestion, "id" | "ordinal" | "text">, exploreRoundId: string): string;
+/** 兼容升级前已经展示给用户、但尚未登记的 scope。 */
+export declare function legacyDiscoveryOpenQuestionScope(question: Pick<DiscoveryOpenQuestion, "id" | "documentFingerprint">, exploreRoundId: string): string;
 /** 面向用户展示时隐藏 Q-xxx 这一内部编号；历史无编号问题保持原文。 */
 export declare function discoveryOpenQuestionDisplayText(question: Pick<DiscoveryOpenQuestion, "id" | "text">): string;
 /** 从 discovery.md 提取“待确认问题”段内的未确认项数量。 */
@@ -61,6 +68,26 @@ export interface ProposeOpenQuestionFile {
     path: string;
     openCount: number;
 }
+export declare const PROPOSE_OPEN_QUESTION_SCOPE_PREFIX = "propose_open_question:";
+export interface ProposeQuestion {
+    path: string;
+    id: string;
+    ordinal: number;
+    text: string;
+    raw: string;
+    documentFingerprint: string;
+    status: "open" | "closed";
+}
+export declare function parseProposeQuestions(content: string, path: string): ProposeQuestion[];
+export declare function proposeQuestionKey(question: Pick<ProposeQuestion, "path" | "id" | "ordinal" | "text">): string;
+/** Propose 决定的明确依据；其它计划材料变化不会自动使已展示决定失效。 */
+export declare function proposeQuestionDecisionBasisDigest(question: Pick<ProposeQuestion, "path" | "id" | "ordinal" | "text">): string;
+export declare function proposeQuestionContextFingerprint(content: string, question: Pick<ProposeQuestion, "id" | "ordinal">): string | null;
+export declare function proposeOpenQuestionScope(question: ProposeQuestion, proposeRoundId: string): string;
+/** 兼容升级前已经展示给用户、但尚未登记的 scope。 */
+export declare function legacyProposeOpenQuestionScope(question: ProposeQuestion, proposeRoundId: string): string;
+export declare function proposeOpenQuestionDisplayText(question: Pick<ProposeQuestion, "id" | "text">): string;
+export declare function collectProposeQuestions(changeRoot: string): ProposeQuestion[];
 export declare function countProposeOpenQuestionsInContent(content: string): number;
 export declare function collectProposeOpenQuestions(changeRoot: string): {
     openCount: number;

package/dist/format.js

@@ -52,6 +52,17 @@ export const EXPLORE_OPEN_QUESTION_SCOPE_PREFIX = "explore_open_question:";
 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 决策上下文。回写时该事项本身会从问题改为
  * 结论，因此只归一化这一行；其余事实、证据和其它待确认项的改动都会使指纹失效。
@@ -105,6 +116,11 @@ export function parseDiscoveryOpenQuestions(content) {
         .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}`;
 }
@@ -168,21 +184,24 @@ 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 };
 }
 /**
@@ -206,12 +225,84 @@ export function validateDiscovery(changeRoot) {
         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);
 }
@@ -543,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);
@@ -589,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("、")}` : ""}`);
                 }
             }
         }

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/phase_confirmation.js

@@ -123,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";
@@ -255,7 +256,8 @@ export function phaseConfirmationForBoundary(projectRoot, events, snapshot, boun
     const summary = boundary === "propose_to_apply"
         ? proposeTaskDeliverySummary(openspecChangeRoot(projectRoot, snapshot.change_id))
         : null;
-    const question = summary ? `${summary}\n\n${spec.question}` : spec.question;
+    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,

package/dist/phase_plan.d.ts

@@ -1,6 +1,7 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
 import { exploreAnswerRegistrationPayload } from "./explore_round.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, State } from "./types.ts";
+import { proposeAnswerRegistrationPayload } from "./propose_round.ts";
+import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, WorkflowArtifactKind, State } from "./types.ts";
 import type { Snapshot } from "./types.ts";
 import type { ReviewRisk } from "./review.ts";
 export type TransitionName = "explore" | "propose-ready" | "start-apply" | "task-start" | "task-complete" | "review-ready" | "reopen" | "accept";
@@ -39,11 +40,28 @@ export type NextStepPlan = {
     state: State;
     jobs: Job[];
     reason: string;
+} | {
+    kind: "artifact_required";
+    state: State;
+    artifact: {
+        kind: WorkflowArtifactKind;
+        path: string;
+        operation: "create_or_update";
+    };
+    resume: {
+        argv: string[];
+    };
+    reason: string;
 } | {
     kind: "ask_user";
     state: State;
     ask: AskUser;
     reason: string;
+} | {
+    kind: "material_update_required";
+    state: State;
+    errors: string[];
+    reason: string;
 } | {
     kind: "run_transition";
     state: State;
@@ -70,6 +88,7 @@ export type TransitionDecisionPlan = {
     kind: "create_gate_jobs";
     gate: ReviewGateRule;
     roles: JobRole[];
+    requiredRoles: JobRole[];
     reason: string;
 } | {
     kind: "advance";
@@ -90,6 +109,7 @@ export declare function proposalDocsBaseline(changeRoot: string): Record<string,
 export declare function discoveryDocsBaseline(changeRoot: string): Record<string, string>;
 /** 新 Explore 轮次冻结已有已确认事项，避免把历史答复当作本轮遗漏。 */
 export declare function exploreAnswerRegistrationPayloadForChange(changeRoot: string): ReturnType<typeof exploreAnswerRegistrationPayload>;
+export declare function proposeAnswerRegistrationPayloadForChange(changeRoot: string): ReturnType<typeof proposeAnswerRegistrationPayload>;
 export declare function latestAcceptedProposalBaseline(events: Event[]): Record<string, string> | null;
 export declare function latestReopenProposeBaseline(events: Event[]): Record<string, string> | null;
 export declare function latestReopenExploreBaseline(events: Event[]): Record<string, string> | null;