@peterxiaoyang/superspec 0.1.45 → 0.1.47

package/dist/phase_plan.js

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
-import { collectProposeOpenQuestions, countDiscoveryOpenQuestions, parseTasksMd, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, } from "./format.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 { currentGitHead } from "./git_state.js";
+import { validateOpenSpecChange } from "./openspec.js";
 import { docRef, sha256File } from "./store.js";
 import { isReviewReadyVerifier, isFreshReviewVerifier, historicalProposeReadyRoles, readReviewPolicyFromEvents, reviewGateRoleResolution, reviewRejectionOverrideScope, reviewEvidenceDigest, } from "./review.js";
 import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, codeReviewDecisionScope, codeReviewJobStaleReason, collectCodeReviewGateFacts, currentCodeReviewWorkingPaths, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, } from "./code_review.js";
@@ -79,13 +81,19 @@ function reviewGatePlan(snapshot, events, changeRoot, gate, requiredRoles) {
     }
     return null;
 }
-function validateTasksPlan(changeRoot) {
+function validateTasksPlan(changeRoot, executionRequirementVersion) {
     const tasksPath = join(changeRoot, "tasks.md");
     if (!existsSync(tasksPath))
         return "tasks.md 不存在";
     const tasksContent = readFileSync(tasksPath, "utf8");
-    if (!tasksContent.includes("# Tasks") && !tasksContent.includes("- [ ]"))
-        return "tasks.md 内容不像任务计划文档";
+    if (executionRequirementVersion === 1) {
+        return tasksContent.includes("# Tasks") || tasksContent.includes("- [ ]")
+            ? null
+            : "tasks.md 内容不像任务计划文档";
+    }
+    const errors = validateTasksDocument(tasksContent);
+    if (errors.length > 0)
+        return errors.join("；");
     return null;
 }
 export function executionPolicyForRisk(risk) {
@@ -122,6 +130,43 @@ function missingBaseArtifact(changeRoot, risk) {
     }
     return null;
 }
+/** OpenSpec strict gate 只在当前 planning round 冻结为 strict 时执行。 */
+function validateOpenSpecPlanningDocuments(projectRoot, change, changeRoot, profile) {
+    if (profile == null || profile.openspec.mode !== "strict")
+        return null;
+    const currentConfigDigest = sha256File(join(projectRoot, "openspec", "config.yaml"));
+    if (currentConfigDigest !== profile.openspec.config_digest) {
+        return "OpenSpec 配置自本 planning round 起已变化；请恢复原配置或 reopen --to propose 创建新的计划轮";
+    }
+    const tasksPath = join(changeRoot, "tasks.md");
+    const referenceErrors = validateExecutionRequirementDocumentReferences(changeRoot, parseExecutionRequirements(readFileSync(tasksPath, "utf8")));
+    if (referenceErrors.length > 0)
+        return referenceErrors.join("；");
+    const proposalPath = join(changeRoot, "proposal.md");
+    if (!existsSync(proposalPath))
+        return "proposal.md 不存在";
+    const impact = validateProposalImpact(readFileSync(proposalPath, "utf8"));
+    if (!impact.ok)
+        return impact.message;
+    const native = validateOpenSpecChange(projectRoot, change);
+    return native.ok ? null : native.message;
+}
+function validatePlanningPreflight(projectRoot, change, changeRoot, risk, executionPolicy, profile) {
+    const executionRequirementVersion = profile?.version ?? 1;
+    const tasksPlanError = validateTasksPlan(changeRoot, executionRequirementVersion);
+    if (tasksPlanError)
+        return { error: tasksPlanError, contractMode: false };
+    const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot, executionPolicy, executionRequirementVersion);
+    if (!executionRequirementPlan.ok)
+        return { error: executionRequirementPlan.message, contractMode: false };
+    const missingArtifact = missingBaseArtifact(changeRoot, risk);
+    if (missingArtifact)
+        return { error: missingArtifact, contractMode: false };
+    return {
+        error: validateOpenSpecPlanningDocuments(projectRoot, change, changeRoot, profile),
+        contractMode: executionRequirementPlan.mode,
+    };
+}
 export function proposalDocsBaseline(changeRoot) {
     // 与 Propose gate 的可修改审查目标保持同一来源：specs/ 用目录聚合指纹，避免 reopen 基线漏掉任一个可修改的计划材料。
     const docs = PROPOSE_FINAL_REVIEW_GATE.reviewTargets;
@@ -140,6 +185,11 @@ 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);
+}
 function isDigestMap(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -234,6 +284,62 @@ function executionRequirementVersionForProposeRound(events) {
     }
     return 1;
 }
+function isPlanningValidationProfile(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    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";
+}
+/** 新 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 } };
+}
+/** propose 状态尚未 ready 时，从进入本 planning round 的事件读取冻结 profile。 */
+function planningValidationProfileForPendingProposeRound(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        // 只读取“进入 propose”的边界事件。propose-ready 创建审查 job 时也会
+        // 保持在 propose；若把它误当作新的 planning round，便会覆盖此前冻结的
+        // profile 并把当前轮错误降级为 v1。
+        const entersPropose = payload.to_state === "propose" && (payload.transition === "explore" ||
+            payload.transition === "propose" ||
+            payload.transition === "reopen" && payload.reopen_target === "propose");
+        if (!entersPropose)
+            continue;
+        return isPlanningValidationProfile(payload.planning_validation_profile)
+            ? payload.planning_validation_profile
+            : null;
+    }
+    return null;
+}
+/** 已完成 propose-ready 的 round 只回放当时冻结的 profile。 */
+function planningValidationProfileForReadyProposeRound(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        if (payload.transition !== "propose-ready" || payload.to_state !== "propose_ready")
+            continue;
+        if (isPlanningValidationProfile(payload.planning_validation_profile))
+            return payload.planning_validation_profile;
+        // 过渡期已写 v2 执行依据、但尚未带 profile 的事件保持 v2 tasks 契约，
+        // 但不在 start-apply 追溯新增 strict gate。
+        return executionRequirementVersionFromPayload(event.payload) === 2
+            ? { version: 2, openspec: { mode: "disabled" } }
+            : null;
+    }
+    return null;
+}
 export function applyRequirementModeForCurrentRound(events) {
     const index = latestStartApplyIndex(events);
     if (index < 0)
@@ -352,10 +458,6 @@ 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 discoveryCheck = validateDiscovery(changeRoot);
             if (!discoveryCheck.ok) {
                 const ask = {
@@ -366,14 +468,32 @@ 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 currentQuestion = parseDiscoveryOpenQuestions(content)[0];
+            if (currentQuestion) {
+                const questionText = discoveryOpenQuestionDisplayText(currentQuestion);
                 const ask = {
-                    question: `discovery.md 有 ${openQs} 个未解决的待确认问题，请逐个确认`,
-                    allowed_answers: ["所有问题已确认"],
-                    scope: "explore_open_questions",
+                    question: `现在有一件事需要你确认：${questionText}\n\n请只回答这一件事。主流程会先登记答复，再将结论回写 discovery.md；回写完成前会继续询问这一件事。`,
+                    // 用户可以接受建议、选择其他方向或补充事实；状态机不解释答案语义。
+                    allowed_answers: [],
+                    scope: discoveryOpenQuestionScope(currentQuestion, currentExploreRoundId(events)),
+                };
+                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: "ask_user", state: "explore", ask, reason: `有 ${openQs} 个未确认问题` };
+                return { kind: "ask_user", state: "explore", ask, reason: "存在未登记答复的已确认事项" };
+            }
+            // 先让用户澄清当前 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)) {
@@ -542,6 +662,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) {
@@ -704,7 +834,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 不适用` };
@@ -716,6 +852,14 @@ 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 有已确认事项缺少对应答复登记，请先恢复为待确认并按主流程登记答复" };
+    }
     const requiredRoles = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(mode.risk);
     const gatePlan = reviewGatePlan(snapshot, events, changeRoot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles);
     if (gatePlan)
@@ -730,7 +874,11 @@ function planExploreTransition(context) {
         fromState: "explore",
         toState: "propose",
         reason: "探索完成",
-        payload: phaseConfirmationCommitPayload(confirmation, decision),
+        payload: {
+            ...phaseConfirmationCommitPayload(confirmation, decision),
+            planning_validation_version: 2,
+            planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
+        },
     };
 }
 function planProposeReadyTransition(context) {
@@ -738,20 +886,15 @@ function planProposeReadyTransition(context) {
     const risk = mode.risk;
     if (snapshot.state !== "propose")
         return { kind: "skip", message: `当前状态 ${snapshot.state}，不能 propose-ready` };
-    const tasksPlanError = validateTasksPlan(changeRoot);
-    if (tasksPlanError)
-        return { kind: "skip", message: tasksPlanError };
-    const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot, executionPolicyForRisk(risk), 2);
-    if (!executionRequirementPlan.ok)
-        return { kind: "skip", message: executionRequirementPlan.message };
+    const planningProfile = planningValidationProfileForPendingProposeRound(context.events);
+    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}` };
     }
-    const missingArtifact = missingBaseArtifact(changeRoot, risk);
-    if (missingArtifact)
-        return { kind: "skip", message: missingArtifact };
     const requiredRoles = PROPOSE_FINAL_REVIEW_GATE.requiredRolesForRisk(risk);
     const gatePlan = reviewGatePlan(snapshot, context.events, changeRoot, PROPOSE_FINAL_REVIEW_GATE, requiredRoles);
     if (gatePlan)
@@ -763,7 +906,11 @@ function planProposeReadyTransition(context) {
         reason: `risk=${risk}，所有需求已满足`,
         payload: {
             workflow_mode: risk,
-            execution_requirement_version: 2,
+            ...(planningProfile ? {
+                execution_requirement_version: 2,
+                planning_validation_version: 2,
+                planning_validation_profile: planningProfile,
+            } : {}),
         },
     };
 }
@@ -782,7 +929,12 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
         return { kind: "skip", message: `回到 propose 后至少一个计划文档必须变化（基线绑定：${Object.keys(reopenBaseline).join("、")}）` };
     }
     const risk = workflowRiskForProposeRound(events, context.mode.risk);
-    const executionRequirementVersion = executionRequirementVersionForProposeRound(events);
+    const planningProfile = planningValidationProfileForReadyProposeRound(events);
+    const executionRequirementVersion = planningProfile?.version ?? executionRequirementVersionForProposeRound(events);
+    const executionPolicy = executionPolicyForRisk(risk);
+    const preflight = validatePlanningPreflight(projectRoot, context.change, changeRoot, risk, executionPolicy, planningProfile);
+    if (preflight.error)
+        return { kind: "skip", message: preflight.error };
     const requiredRoles = executionRequirementVersion === 2
         ? PROPOSE_FINAL_REVIEW_GATE.requiredRolesForRisk(risk)
         : historicalProposeReadyRoles(events);
@@ -796,10 +948,6 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
     const acceptedConfirmation = enforceConfirmation
         ? acceptedProposeToApplyConfirmation(context, risk)
         : null;
-    const executionPolicy = executionPolicyForRisk(risk);
-    const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot, executionPolicy, executionRequirementVersion);
-    if (!executionRequirementPlan.ok)
-        return { kind: "skip", message: executionRequirementPlan.message };
     if (enforceConfirmation && !acceptedConfirmation) {
         const confirmation = phaseConfirmationForBoundary(projectRoot, events, snapshot, "propose_to_apply", risk);
         return {
@@ -816,7 +964,7 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
         payload: {
             apply_start_head: gitHead.head,
             apply_start_head_reason: gitHead.reason,
-            apply_contract_mode: executionRequirementPlan.mode,
+            apply_contract_mode: preflight.contractMode,
             ...(executionRequirementVersion === 2 ? { execution_requirement_version: 2 } : {}),
             execution_policy: executionPolicy,
             workflow_mode: risk,