@peterxiaoyang/superspec 0.1.47 → 0.1.49

package/dist/phase_plan.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
-import { currentExploreRoundId, exploreAnswerRegistrationPayload, unregisteredClosedExploreQuestions, } from "./explore_round.js";
-import { collectProposeOpenQuestions, discoveryOpenQuestionDisplayText, discoveryOpenQuestionScope, parseExecutionRequirements, parseDiscoveryOpenQuestions, parseTasksMd, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, validateExecutionRequirementDocumentReferences, validateProposalImpact, validateTasksDocument, } from "./format.js";
+import { currentExploreRoundId, exploreAnswerRegistrationPayload, unregisteredClosedExploreQuestions, unresolvedPresentedExploreQuestionScopes, } from "./explore_round.js";
+import { currentProposeOpenQuestion, currentProposeRoundId, proposeAnswerRegistrationPayload, unregisteredClosedProposeQuestions, unresolvedPresentedProposeQuestionScopes, } from "./propose_round.js";
+import { discoveryOpenQuestionDisplayText, discoveryOpenQuestionScope, proposeOpenQuestionDisplayText, proposeOpenQuestionScope, parseExecutionRequirements, parseDiscoveryOpenQuestions, parseTasksMd, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, validateExecutionRequirementDocumentReferences, validateProposalImpact, validateTasksDocument, } from "./format.js";
 import { currentGitHead } from "./git_state.js";
 import { validateOpenSpecChange } from "./openspec.js";
 import { docRef, sha256File } from "./store.js";
@@ -14,6 +15,26 @@ import { workflowRiskForProposeRound, workflowRiskForState } from "./workflow_co
 function requiredJobs(state, jobs, reason) {
     return { kind: "required_jobs", state, jobs, reason };
 }
+function freeTextDecisionAsk(change, question, scope) {
+    return {
+        question,
+        allowed_answers: [],
+        scope,
+        record_argv: ["superspec", "record", "user-decision", "--change", change, "--input", "-"],
+        record_input: { scope, question, answer: null },
+        required_fields: ["answer"],
+    };
+}
+function requiredArtifact(projectRoot, change, changeRoot, state, kind, canonicalPath, risk) {
+    const artifactPath = relative(projectRoot, join(changeRoot, canonicalPath)).replaceAll("\\", "/");
+    return {
+        kind: "artifact_required",
+        state,
+        artifact: { kind, path: artifactPath, operation: "create_or_update" },
+        resume: { argv: nextArgv(change, risk) },
+        reason: `${canonicalPath.split("/").at(-1)} 不存在`,
+    };
+}
 function phaseConfirmationStep(context, boundary, reason) {
     // 进入 propose_ready / apply 后，mode 来自本轮快照而非当前配置。
     const risk = workflowRiskForState(context.events, context.snapshot.state, context.mode.risk);
@@ -76,6 +97,7 @@ function reviewGatePlan(snapshot, events, changeRoot, gate, requiredRoles) {
             kind: "create_gate_jobs",
             gate,
             roles: missingRoles.map(item => item.role),
+            requiredRoles: [...requiredRoles],
             reason: missingRoles.map(item => item.reason).join("; "),
         };
     }
@@ -96,6 +118,42 @@ function validateTasksPlan(changeRoot, executionRequirementVersion) {
         return errors.join("；");
     return null;
 }
+const REQUIRED_DESIGN_HEADINGS = [
+    "# 设计",
+    "## 背景",
+    "## 设计目标",
+    "## 非目标",
+    "## 总体方案",
+    "## 实现方案",
+];
+function validateDesignPlan(changeRoot, profile) {
+    if (profile?.openspec.mode !== "strict" || profile.design?.schema_version !== 1)
+        return null;
+    const designPath = join(changeRoot, "design.md");
+    if (!existsSync(designPath))
+        return null;
+    const lines = readFileSync(designPath, "utf8").split(/\r?\n/).map(line => line.trimEnd());
+    const errors = [];
+    const headingIndexes = new Map();
+    for (const heading of REQUIRED_DESIGN_HEADINGS) {
+        const indexes = lines.flatMap((line, index) => line === heading ? [index] : []);
+        headingIndexes.set(heading, indexes);
+        if (indexes.length === 0)
+            errors.push(`design.md 缺少稳定结构标题：${heading}`);
+        if (indexes.length > 1)
+            errors.push(`design.md 稳定结构标题重复：${heading}`);
+    }
+    if (errors.length > 0)
+        return errors.join("；");
+    let previousIndex = -1;
+    for (const heading of REQUIRED_DESIGN_HEADINGS) {
+        const indexes = headingIndexes.get(heading);
+        if (indexes[0] <= previousIndex)
+            return `design.md 稳定结构标题顺序错误：${heading}`;
+        previousIndex = indexes[0];
+    }
+    return null;
+}
 export function executionPolicyForRisk(risk) {
     return risk === "strict" ? "tdd" : "green_only";
 }
@@ -153,17 +211,27 @@ function validateOpenSpecPlanningDocuments(projectRoot, change, changeRoot, prof
 }
 function validatePlanningPreflight(projectRoot, change, changeRoot, risk, executionPolicy, profile) {
     const executionRequirementVersion = profile?.version ?? 1;
+    const errors = [];
     const tasksPlanError = validateTasksPlan(changeRoot, executionRequirementVersion);
     if (tasksPlanError)
-        return { error: tasksPlanError, contractMode: false };
+        errors.push(tasksPlanError);
     const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot, executionPolicy, executionRequirementVersion);
     if (!executionRequirementPlan.ok)
-        return { error: executionRequirementPlan.message, contractMode: false };
+        errors.push(executionRequirementPlan.message);
     const missingArtifact = missingBaseArtifact(changeRoot, risk);
     if (missingArtifact)
-        return { error: missingArtifact, contractMode: false };
+        errors.push(missingArtifact);
+    const designPlanError = validateDesignPlan(changeRoot, profile);
+    if (designPlanError)
+        errors.push(designPlanError);
+    if (existsSync(join(changeRoot, "tasks.md"))) {
+        const openSpecError = validateOpenSpecPlanningDocuments(projectRoot, change, changeRoot, profile);
+        if (openSpecError)
+            errors.push(openSpecError);
+    }
     return {
-        error: validateOpenSpecPlanningDocuments(projectRoot, change, changeRoot, profile),
+        error: errors.length > 0 ? [...new Set(errors)].join("；") : null,
+        errors: [...new Set(errors)],
         contractMode: executionRequirementPlan.mode,
     };
 }
@@ -176,6 +244,15 @@ export function proposalDocsBaseline(changeRoot) {
     }
     return baseline;
 }
+export function applyPlanningBaseline(changeRoot) {
+    const baseline = proposalDocsBaseline(changeRoot);
+    delete baseline["tasks.md"];
+    return baseline;
+}
+export function applyPlanningDocsChangedSinceBaseline(changeRoot, baseline) {
+    const current = applyPlanningBaseline(changeRoot);
+    return Object.entries(baseline).some(([path, digest]) => current[path] !== digest);
+}
 export function discoveryDocsBaseline(changeRoot) {
     // 与 Explore gate 使用同一组审查目标。回退到 explore 后，至少要更新一项
     // discovery 材料，才允许重新进入 propose，避免把一次纯状态回退误当作新探索轮次。
@@ -190,6 +267,9 @@ export function exploreAnswerRegistrationPayloadForChange(changeRoot) {
     const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
     return exploreAnswerRegistrationPayload(existsSync(discoveryPath) ? readFileSync(discoveryPath, "utf8") : null);
 }
+export function proposeAnswerRegistrationPayloadForChange(changeRoot) {
+    return proposeAnswerRegistrationPayload(changeRoot);
+}
 function isDigestMap(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -290,15 +370,16 @@ function isPlanningValidationProfile(value) {
     const profile = value;
     if (profile.version !== 2 || !profile.openspec || typeof profile.openspec !== "object")
         return false;
-    return profile.openspec.mode === "disabled" ||
-        profile.openspec.mode === "strict" && typeof profile.openspec.config_digest === "string";
+    const designValid = profile.design == null || profile.design.schema_version === 1;
+    return designValid && (profile.openspec.mode === "disabled" ||
+        profile.openspec.mode === "strict" && typeof profile.openspec.config_digest === "string");
 }
 /** 新 planning round 在进入 propose 时冻结当前 OpenSpec 校验契约。 */
 export function planningValidationProfileForNewRound(projectRoot) {
     const configDigest = sha256File(join(projectRoot, "openspec", "config.yaml"));
     return configDigest == null
-        ? { version: 2, openspec: { mode: "disabled" } }
-        : { version: 2, openspec: { mode: "strict", config_digest: configDigest } };
+        ? { version: 2, openspec: { mode: "disabled" }, design: { schema_version: 1 } }
+        : { version: 2, openspec: { mode: "strict", config_digest: configDigest }, design: { schema_version: 1 } };
 }
 /** propose 状态尚未 ready 时，从进入本 planning round 的事件读取冻结 profile。 */
 function planningValidationProfileForPendingProposeRound(events) {
@@ -404,6 +485,20 @@ export function pendingTaskStatusForApply(changeRoot, events) {
         completedByEvent,
     };
 }
+function isPostApplyPlanOnlyRepair(changeRoot, events) {
+    // Propose 返工发生在新 Apply round 之前，旧 round 的 task_completed 不能覆盖
+    // 当前计划明确重新打开的 checkbox；这里以当前 tasks.md 为准。
+    if (pendingTaskIds(changeRoot).length > 0)
+        return false;
+    const roundId = currentProposeRoundId(events);
+    const roundEvent = events.find(event => event.event_id === roundId);
+    if (roundEvent?.event_type !== "transition_commit")
+        return false;
+    const payload = roundEvent.payload;
+    return payload.transition === "reopen"
+        && payload.reopen_target === "propose"
+        && ["apply", "apply_done", "review", "accepted"].includes(String(payload.reopen_source));
+}
 export function formatPendingTaskMessage(ids, action) {
     return `尚有未完成任务：${ids.join(", ")}；${action}`;
 }
@@ -441,7 +536,7 @@ function acceptedMaterialFollowup(change, risk, planDocsChangedSinceAccept) {
     };
 }
 export function planNextStep(context) {
-    const { change, changeRoot, events, mode, snapshot } = context;
+    const { projectRoot, change, changeRoot, events, mode, snapshot } = context;
     switch (snapshot.state) {
         case "init":
             if (snapshot.open_jobs.length > 0) {
@@ -458,6 +553,10 @@ export function planNextStep(context) {
                     reason: "回到 explore 后至少一个 discovery 材料必须变化",
                 };
             }
+            const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
+            if (!existsSync(discoveryPath)) {
+                return requiredArtifact(projectRoot, change, changeRoot, "explore", "discovery", ".superspec/artifacts/discovery.md", mode.risk);
+            }
             const discoveryCheck = validateDiscovery(changeRoot);
             if (!discoveryCheck.ok) {
                 const ask = {
@@ -471,22 +570,27 @@ export function planNextStep(context) {
             const currentQuestion = parseDiscoveryOpenQuestions(content)[0];
             if (currentQuestion) {
                 const questionText = discoveryOpenQuestionDisplayText(currentQuestion);
-                const ask = {
-                    question: `现在有一件事需要你确认：${questionText}\n\n请只回答这一件事。主流程会先登记答复，再将结论回写 discovery.md；回写完成前会继续询问这一件事。`,
-                    // 用户可以接受建议、选择其他方向或补充事实；状态机不解释答案语义。
-                    allowed_answers: [],
-                    scope: discoveryOpenQuestionScope(currentQuestion, currentExploreRoundId(events)),
-                };
+                const question = `现在有一件事需要你确认：${questionText}\n\n请只回答这一件事。主流程会先登记答复，再将结论回写 discovery.md；回写完成前会继续询问这一件事。`;
+                const scope = discoveryOpenQuestionScope(currentQuestion, currentExploreRoundId(events));
+                const ask = freeTextDecisionAsk(change, question, scope);
                 return { kind: "ask_user", state: "explore", ask, reason: "等待用户确认" };
             }
             const unregisteredClosedQuestions = unregisteredClosedExploreQuestions(events, content);
             if (unregisteredClosedQuestions.length > 0) {
-                const ask = {
-                    question: "发现一项已标记为已确认的事项没有对应的答复登记。请先将该项恢复为待确认，按主流程重新登记用户答复并回写 discovery.md 后继续。",
-                    allowed_answers: ["已处理"],
-                    scope: "explore_answer_registration",
+                return {
+                    kind: "material_update_required",
+                    state: "explore",
+                    errors: ["发现一项已标记为已确认的事项没有对应答复登记；请恢复为待确认，通过 next 登记真实答复后再回写 discovery.md"],
+                    reason: "存在未登记答复的已确认事项",
+                };
+            }
+            if (unresolvedPresentedExploreQuestionScopes(events).length > 0) {
+                return {
+                    kind: "material_update_required",
+                    state: "explore",
+                    errors: ["此前已展示的 Explore 问题尚未登记答复但已从 discovery.md 消失；请恢复原问题，通过 next 登记答复后再回写结论"],
+                    reason: "已展示的 Explore 问题缺少答复登记",
                 };
-                return { kind: "ask_user", state: "explore", ask, reason: "存在未登记答复的已确认事项" };
             }
             // 先让用户澄清当前 Discovery，再审查材料；否则 critic 会审查一份仍有
             // 关键业务未知的文档。正常创建的 job 已绑定 discovery 指纹，材料变化后
@@ -510,15 +614,45 @@ export function planNextStep(context) {
             };
         }
         case "propose": {
-            const openQuestions = collectProposeOpenQuestions(changeRoot);
-            if (openQuestions.openCount > 0) {
-                const files = openQuestions.files.map(f => `${f.path}(${f.openCount})`).join(", ");
-                const ask = {
-                    question: `计划文档有 ${openQuestions.openCount} 个待用户确认问题：${files}。请确认并更新计划文档后继续`,
-                    allowed_answers: ["所有问题已确认"],
-                    scope: "propose_open_questions",
+            const currentQuestion = currentProposeOpenQuestion(changeRoot);
+            if (currentQuestion) {
+                const question = `设计方案中有一件高影响取舍需要你决定：${proposeOpenQuestionDisplayText(currentQuestion)}\n\n请只回答这一件事。主流程会登记答复并将决定回写相关计划材料；回写完成前仍会停在当前事项。`;
+                const scope = proposeOpenQuestionScope(currentQuestion, currentProposeRoundId(events));
+                const ask = freeTextDecisionAsk(change, question, scope);
+                return { kind: "ask_user", state: "propose", ask, reason: "等待用户确认设计取舍" };
+            }
+            if (unregisteredClosedProposeQuestions(events, changeRoot).length > 0) {
+                return {
+                    kind: "material_update_required",
+                    state: "propose",
+                    errors: ["发现一项已标记为确认的设计决定没有对应答复登记；请恢复为待确认，通过 next 登记真实答复后再回写计划材料"],
+                    reason: "存在未登记答复的设计决定",
+                };
+            }
+            if (unresolvedPresentedProposeQuestionScopes(events).length > 0) {
+                return {
+                    kind: "material_update_required",
+                    state: "propose",
+                    errors: ["此前已展示的设计问题尚未登记答复但已从计划材料消失；请恢复原问题，通过 next 登记答复后再回写结论"],
+                    reason: "已展示的设计问题缺少答复登记",
+                };
+            }
+            const testContractPath = join(changeRoot, ".superspec", "artifacts", "test-contract.md");
+            if (!existsSync(testContractPath)) {
+                return requiredArtifact(projectRoot, change, changeRoot, "propose", "test_contract", ".superspec/artifacts/test-contract.md", mode.risk);
+            }
+            if (!existsSync(join(changeRoot, "tasks.md"))) {
+                return requiredArtifact(projectRoot, change, changeRoot, "propose", "tasks", "tasks.md", mode.risk);
+            }
+            const planningProfile = planningValidationProfileForPendingProposeRound(events);
+            const preflight = validatePlanningPreflight(projectRoot, change, changeRoot, mode.risk, executionPolicyForRisk(mode.risk), planningProfile);
+            if (preflight.error) {
+                return {
+                    kind: "material_update_required",
+                    state: "propose",
+                    errors: preflight.errors,
+                    reason: preflight.error,
                 };
-                return { kind: "ask_user", state: "propose", ask, reason: `有 ${openQuestions.openCount} 个 propose 未确认问题` };
             }
             const proposalReviewJobs = PROPOSE_FINAL_REVIEW_GATE.openJobsForGate(snapshot);
             if (proposalReviewJobs.length > 0) {
@@ -538,7 +672,8 @@ export function planNextStep(context) {
                 return requiredJobs("propose_ready", proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
             }
             const startApplyPlan = planStartApplyTransition(context, false);
-            if (startApplyPlan.kind === "advance") {
+            const planOnlyRepair = isPostApplyPlanOnlyRepair(changeRoot, events);
+            if (startApplyPlan.kind === "advance" && !planOnlyRepair) {
                 const confirmation = phaseConfirmationStep(context, "propose_to_apply", "计划阶段完成，等待用户确认开始实现");
                 if (confirmation)
                     return confirmation;
@@ -553,7 +688,12 @@ export function planNextStep(context) {
                 };
                 return { kind: "ask_user", state: "propose_ready", ask, reason: startApplyPlan.message };
             }
-            return { kind: "run_transition", state: "propose_ready", transition: "start-apply", reason: "计划就绪，开始执行" };
+            return {
+                kind: "run_transition",
+                state: "propose_ready",
+                transition: "start-apply",
+                reason: planOnlyRepair ? "计划材料已修正且没有待实施任务，跳过重复的 Apply 确认" : "计划就绪，开始执行",
+            };
         }
         case "apply":
             return planApplyNext(context);
@@ -860,6 +1000,9 @@ function planExploreTransition(context) {
     if (unregisteredClosedExploreQuestions(events, discoveryContent).length > 0) {
         return { kind: "skip", message: "discovery.md 有已确认事项缺少对应答复登记，请先恢复为待确认并按主流程登记答复" };
     }
+    if (unresolvedPresentedExploreQuestionScopes(events).length > 0) {
+        return { kind: "skip", message: "此前展示的 Explore 问题缺少答复登记且已从 discovery.md 消失，请恢复原问题并完成登记" };
+    }
     const requiredRoles = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(mode.risk);
     const gatePlan = reviewGatePlan(snapshot, events, changeRoot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles);
     if (gatePlan)
@@ -878,6 +1021,7 @@ function planExploreTransition(context) {
             ...phaseConfirmationCommitPayload(confirmation, decision),
             planning_validation_version: 2,
             planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
+            ...proposeAnswerRegistrationPayloadForChange(changeRoot),
         },
     };
 }
@@ -890,10 +1034,14 @@ function planProposeReadyTransition(context) {
     const preflight = validatePlanningPreflight(context.projectRoot, context.change, changeRoot, risk, executionPolicyForRisk(risk), planningProfile);
     if (preflight.error)
         return { kind: "skip", message: preflight.error };
-    const openQuestions = collectProposeOpenQuestions(changeRoot);
-    if (openQuestions.openCount > 0) {
-        const files = openQuestions.files.map(f => `${f.path}(${f.openCount})`).join(", ");
-        return { kind: "skip", message: `计划文档有 ${openQuestions.openCount} 个待用户确认问题：${files}` };
+    if (currentProposeOpenQuestion(changeRoot)) {
+        return { kind: "skip", message: "计划文档仍有待用户确认的设计决定，请先完成确认并回写计划材料" };
+    }
+    if (unregisteredClosedProposeQuestions(context.events, changeRoot).length > 0) {
+        return { kind: "skip", message: "计划文档有已确认设计决定缺少对应答复登记，请先恢复为待确认并按主流程登记答复" };
+    }
+    if (unresolvedPresentedProposeQuestionScopes(context.events).length > 0) {
+        return { kind: "skip", message: "此前展示的设计问题缺少答复登记且已从计划材料消失，请恢复原问题并完成登记" };
     }
     const requiredRoles = PROPOSE_FINAL_REVIEW_GATE.requiredRolesForRisk(risk);
     const gatePlan = reviewGatePlan(snapshot, context.events, changeRoot, PROPOSE_FINAL_REVIEW_GATE, requiredRoles);
@@ -945,10 +1093,12 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
             reason: `进入执行阶段前需要重新完成计划文档审查：${gatePlan.reason}`,
         };
     }
+    const planOnlyRepair = isPostApplyPlanOnlyRepair(changeRoot, events);
     const acceptedConfirmation = enforceConfirmation
+        && !planOnlyRepair
         ? acceptedProposeToApplyConfirmation(context, risk)
         : null;
-    if (enforceConfirmation && !acceptedConfirmation) {
+    if (enforceConfirmation && !acceptedConfirmation && !planOnlyRepair) {
         const confirmation = phaseConfirmationForBoundary(projectRoot, events, snapshot, "propose_to_apply", risk);
         return {
             kind: "skip",
@@ -960,7 +1110,7 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
         kind: "advance",
         fromState: "propose_ready",
         toState: "apply",
-        reason: "进入执行阶段",
+        reason: planOnlyRepair ? "计划材料修正完成且没有待实施任务" : "进入执行阶段",
         payload: {
             apply_start_head: gitHead.head,
             apply_start_head_reason: gitHead.reason,
@@ -972,6 +1122,7 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
                 review_risk: risk,
                 requires_verifier: risk !== "minimal",
             },
+            apply_planning_baseline: applyPlanningBaseline(changeRoot),
             ...(acceptedConfirmation ? phaseConfirmationCommitPayload(acceptedConfirmation.confirmation, acceptedConfirmation.decision) : {}),
         },
     };

package/dist/propose_round.d.ts

@@ -0,0 +1,15 @@
+import { type ProposeQuestion } from "./format.ts";
+import type { Event } from "./types.ts";
+export declare function currentProposeRoundId(events: readonly Event[]): string;
+export declare function proposeAnswerRegistrationPayload(changeRoot: string): {
+    propose_answer_registration: {
+        version: number;
+        baseline_closed_question_keys: string[];
+    };
+};
+export declare function proposeAnswerWasRecorded(events: readonly Event[], roundId: string, question: ProposeQuestion, content: string): boolean;
+export declare function unregisteredClosedProposeQuestions(events: readonly Event[], changeRoot: string): ProposeQuestion[];
+export declare function currentProposeOpenQuestion(changeRoot: string): ProposeQuestion | null;
+export declare function currentProposeQuestionContent(changeRoot: string, question: ProposeQuestion): string | null;
+/** 已正式展示但尚未登记答复的 Propose 问题不能通过删除问题行绕过。 */
+export declare function unresolvedPresentedProposeQuestionScopes(events: readonly Event[]): string[];

package/dist/propose_round.js

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { collectProposeQuestions, parseProposeQuestions, proposeQuestionContextFingerprint, proposeQuestionDecisionBasisDigest, proposeQuestionKey, } from "./format.js";
+const PROPOSE_ANSWER_REGISTRATION_VERSION = 1;
+function isProposeRoundEntry(event) {
+    if (event.event_type !== "transition_commit")
+        return false;
+    const payload = event.payload;
+    return payload.to_state === "propose" && (payload.transition === "explore" && payload.from_state === "explore" ||
+        payload.transition === "reopen" && payload.reopen_target === "propose");
+}
+function currentProposeRoundEntry(events) {
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (isProposeRoundEntry(event))
+            return { event, roundId: event.event_id };
+    }
+    return null;
+}
+export function currentProposeRoundId(events) {
+    return currentProposeRoundEntry(events)?.roundId ?? "legacy-propose-round";
+}
+export function proposeAnswerRegistrationPayload(changeRoot) {
+    return {
+        propose_answer_registration: {
+            version: PROPOSE_ANSWER_REGISTRATION_VERSION,
+            baseline_closed_question_keys: collectProposeQuestions(changeRoot)
+                .filter(question => question.status === "closed")
+                .map(proposeQuestionKey)
+                .sort(),
+        },
+    };
+}
+function currentRegistration(events) {
+    const entry = currentProposeRoundEntry(events);
+    if (!entry)
+        return { enabled: false, roundId: "legacy-propose-round", baselineClosedQuestionKeys: new Set() };
+    const payload = entry.event.payload;
+    const registration = payload.propose_answer_registration;
+    if (registration?.version !== PROPOSE_ANSWER_REGISTRATION_VERSION || !Array.isArray(registration.baseline_closed_question_keys)) {
+        return { enabled: false, roundId: entry.roundId, baselineClosedQuestionKeys: new Set() };
+    }
+    return {
+        enabled: true,
+        roundId: entry.roundId,
+        baselineClosedQuestionKeys: new Set(registration.baseline_closed_question_keys.filter((key) => typeof key === "string")),
+    };
+}
+function questionContent(changeRoot, question) {
+    const path = join(changeRoot, question.path);
+    return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+export function proposeAnswerWasRecorded(events, roundId, question, content) {
+    const contextFingerprint = proposeQuestionContextFingerprint(content, question);
+    if (!contextFingerprint)
+        return false;
+    const currentBasisDigest = proposeQuestionDecisionBasisDigest(question);
+    return events.some(event => {
+        if (event.event_type !== "user_decision_recorded")
+            return false;
+        const payload = event.payload;
+        const recorded = payload.propose_open_question;
+        const revisionMatches = typeof recorded?.decision_basis_digest === "string"
+            ? recorded.decision_basis_digest === currentBasisDigest
+            : recorded?.context_fingerprint === contextFingerprint;
+        return payload.accepted === true &&
+            recorded?.round_id === roundId &&
+            recorded.path === question.path &&
+            recorded.question_id === question.id &&
+            (!question.id.startsWith("item-") || recorded.question_ordinal === question.ordinal) &&
+            revisionMatches;
+    });
+}
+export function unregisteredClosedProposeQuestions(events, changeRoot) {
+    const registration = currentRegistration(events);
+    if (!registration.enabled)
+        return [];
+    return collectProposeQuestions(changeRoot).filter(question => {
+        if (question.status !== "closed" || registration.baselineClosedQuestionKeys.has(proposeQuestionKey(question)))
+            return false;
+        const content = questionContent(changeRoot, question);
+        return content != null && !proposeAnswerWasRecorded(events, registration.roundId, question, content);
+    });
+}
+export function currentProposeOpenQuestion(changeRoot) {
+    return collectProposeQuestions(changeRoot).find(question => question.status === "open") ?? null;
+}
+export function currentProposeQuestionContent(changeRoot, question) {
+    const path = join(changeRoot, question.path);
+    if (!existsSync(path))
+        return null;
+    const content = readFileSync(path, "utf8");
+    return parseProposeQuestions(content, question.path).some(candidate => candidate.id === question.id && candidate.ordinal === question.ordinal)
+        ? content
+        : null;
+}
+/** 已正式展示但尚未登记答复的 Propose 问题不能通过删除问题行绕过。 */
+export function unresolvedPresentedProposeQuestionScopes(events) {
+    const roundId = currentProposeRoundId(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 !== "propose" || payload.round_id !== roundId || typeof payload.scope !== "string" || typeof payload.path !== "string" || typeof payload.question_id !== "string")
+            continue;
+        const ordinal = payload.question_id.startsWith("item-") ? `:${String(payload.question_ordinal)}` : "";
+        latestByQuestion.set(`${payload.path}:${payload.question_id}${ordinal}`, {
+            scope: payload.scope,
+            legacyScope: typeof payload.legacy_scope === "string" ? payload.legacy_scope : null,
+            path: payload.path,
+            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.propose_open_question;
+            return recorded?.round_id === roundId &&
+                recorded.path === presented.path &&
+                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];
+    });
+}