@peterxiaoyang/superspec 0.1.46 → 0.1.48

package/dist/phase_plan.d.ts

@@ -1,5 +1,7 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, State } from "./types.ts";
+import { exploreAnswerRegistrationPayload } from "./explore_round.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";
@@ -38,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;
@@ -69,6 +88,7 @@ export type TransitionDecisionPlan = {
     kind: "create_gate_jobs";
     gate: ReviewGateRule;
     roles: JobRole[];
+    requiredRoles: JobRole[];
     reason: string;
 } | {
     kind: "advance";
@@ -87,6 +107,9 @@ export declare function executionPolicyForRisk(risk: ReviewRisk): ExecutionPolic
 export declare function executionPolicyForCurrentRound(events: Event[]): ExecutionPolicy;
 export declare function proposalDocsBaseline(changeRoot: string): Record<string, 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;

package/dist/phase_plan.js

@@ -1,7 +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 { collectProposeOpenQuestions, countDiscoveryOpenQuestions, parseExecutionRequirements, 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";
@@ -13,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, fileName, risk) {
+    const artifactPath = relative(projectRoot, join(changeRoot, ".superspec", "artifacts", fileName)).replaceAll("\\", "/");
+    return {
+        kind: "artifact_required",
+        state,
+        artifact: { kind, path: artifactPath, operation: "create_or_update" },
+        resume: { argv: nextArgv(change, risk) },
+        reason: `${fileName} 不存在`,
+    };
+}
 function phaseConfirmationStep(context, boundary, reason) {
     // 进入 propose_ready / apply 后，mode 来自本轮快照而非当前配置。
     const risk = workflowRiskForState(context.events, context.snapshot.state, context.mode.risk);
@@ -75,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("; "),
         };
     }
@@ -95,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";
 }
@@ -152,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,
     };
 }
@@ -184,6 +253,14 @@ export function discoveryDocsBaseline(changeRoot) {
     }
     return baseline;
 }
+/** 新 Explore 轮次冻结已有已确认事项，避免把历史答复当作本轮遗漏。 */
+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;
@@ -284,15 +361,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) {
@@ -435,7 +513,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) {
@@ -452,9 +530,9 @@ export function planNextStep(context) {
                     reason: "回到 explore 后至少一个 discovery 材料必须变化",
                 };
             }
-            const exploreReviewJobs = EXPLORE_DISCOVERY_REVIEW_GATE.openJobsForGate(snapshot);
-            if (exploreReviewJobs.length > 0) {
-                return requiredJobs("explore", exploreReviewJobs, `有 ${exploreReviewJobs.length} 个待完成探索审查工作项`);
+            const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
+            if (!existsSync(discoveryPath)) {
+                return requiredArtifact(projectRoot, change, changeRoot, "explore", "discovery", "discovery.md", mode.risk);
             }
             const discoveryCheck = validateDiscovery(changeRoot);
             if (!discoveryCheck.ok) {
@@ -466,14 +544,37 @@ export function planNextStep(context) {
                 return { kind: "ask_user", state: "explore", ask, reason: discoveryCheck.message };
             }
             const content = readFileSync(join(changeRoot, ".superspec", "artifacts", "discovery.md"), "utf8");
-            const openQs = countDiscoveryOpenQuestions(content);
-            if (openQs > 0) {
-                const ask = {
-                    question: `discovery.md 有 ${openQs} 个未解决的待确认问题，请逐个确认`,
-                    allowed_answers: ["所有问题已确认"],
-                    scope: "explore_open_questions",
+            const currentQuestion = parseDiscoveryOpenQuestions(content)[0];
+            if (currentQuestion) {
+                const questionText = discoveryOpenQuestionDisplayText(currentQuestion);
+                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) {
+                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: `有 ${openQs} 个未确认问题` };
+            }
+            // 先让用户澄清当前 Discovery，再审查材料；否则 critic 会审查一份仍有
+            // 关键业务未知的文档。正常创建的 job 已绑定 discovery 指纹，材料变化后
+            // 会由 snapshot freshness 自动失效。
+            const exploreReviewJobs = EXPLORE_DISCOVERY_REVIEW_GATE.openJobsForGate(snapshot);
+            if (exploreReviewJobs.length > 0) {
+                return requiredJobs("explore", exploreReviewJobs, `有 ${exploreReviewJobs.length} 个待完成探索审查工作项`);
             }
             const requiredRoles = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(mode.risk);
             if (!reviewGatePlan(snapshot, events, changeRoot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles)) {
@@ -490,15 +591,42 @@ 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", "test-contract.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) {
@@ -642,6 +770,16 @@ function planApplyDoneNext(context) {
     }
     const latest = facts.latestTerminal;
     if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
+        const staleReason = codeReviewJobStaleReason(context.projectRoot, latest.job, currentWorkingPaths);
+        if (staleReason) {
+            return {
+                kind: "run_transition",
+                state: "apply_done",
+                transition: "review-ready",
+                risk: mode.risk,
+                reason: `代码审查结论已过期，重新发起审查：${staleReason}`,
+            };
+        }
         const status = latestCodeReviewFailedStatus(events);
         const pendingFinding = status?.unresolved[0] ?? null;
         if (status && status.findings.length > 0 && !pendingFinding) {
@@ -804,7 +942,13 @@ export function planTransition(name, context) {
 function planExploreTransition(context) {
     const { changeRoot, events, mode, projectRoot, snapshot } = context;
     if (snapshot.state === "init") {
-        return { kind: "advance", fromState: "init", toState: "explore", reason: "进入探索阶段" };
+        return {
+            kind: "advance",
+            fromState: "init",
+            toState: "explore",
+            reason: "进入探索阶段",
+            payload: exploreAnswerRegistrationPayloadForChange(changeRoot),
+        };
     }
     if (snapshot.state !== "explore") {
         return { kind: "skip", message: `当前状态 ${snapshot.state}，explore 不适用` };
@@ -816,6 +960,17 @@ function planExploreTransition(context) {
     const discoveryCheck = validateDiscovery(changeRoot);
     if (!discoveryCheck.ok)
         return { kind: "skip", message: discoveryCheck.message };
+    const discoveryContent = readFileSync(join(changeRoot, ".superspec", "artifacts", "discovery.md"), "utf8");
+    const currentQuestion = parseDiscoveryOpenQuestions(discoveryContent)[0];
+    if (currentQuestion) {
+        return { kind: "skip", message: "discovery.md 仍有需要确认的事项，请先完成确认并回写 discovery.md" };
+    }
+    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)
@@ -834,6 +989,7 @@ function planExploreTransition(context) {
             ...phaseConfirmationCommitPayload(confirmation, decision),
             planning_validation_version: 2,
             planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
+            ...proposeAnswerRegistrationPayloadForChange(changeRoot),
         },
     };
 }
@@ -846,10 +1002,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);

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];
+    });
+}