@peterxiaoyang/superspec 0.1.40 → 0.1.42

package/dist/phase_plan.js

@@ -5,11 +5,23 @@ import { collectProposeOpenQuestions, countDiscoveryOpenQuestions, parseTasksMd,
 import { currentGitHead } from "./git_state.js";
 import { docRef, sha256File } from "./store.js";
 import { isReviewReadyVerifier, isFreshReviewVerifier, readReviewPolicyFromEvents, reviewEvidenceDigest, } from "./review.js";
-import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, codeReviewDecisionScope, collectCodeReviewGateFacts, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, } from "./code_review.js";
+import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, codeReviewDecisionScope, codeReviewJobStaleReason, collectCodeReviewGateFacts, currentCodeReviewWorkingPaths, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, } from "./code_review.js";
+import { isPhaseAdvanceAuthorized, latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 function requiredJobs(state, jobs, reason) {
     return { kind: "required_jobs", state, jobs, reason };
 }
+function phaseConfirmationStep(context, boundary, reason) {
+    const confirmation = phaseConfirmationForBoundary(context.projectRoot, context.events, context.snapshot, boundary, context.mode.risk);
+    if (!confirmation || isPhaseAdvanceAuthorized(context.events, confirmation))
+        return null;
+    return {
+        kind: "ask_user",
+        state: context.snapshot.state,
+        ask: confirmation.ask,
+        reason,
+    };
+}
 function reviewGatePlan(snapshot, gate, requiredRoles) {
     const missingRoles = [];
     for (const role of requiredRoles) {
@@ -63,14 +75,36 @@ function missingBaseArtifact(changeRoot, risk) {
     return null;
 }
 export function proposalDocsBaseline(changeRoot) {
-    // specs/ 用目录聚合指纹：审查可能只对 specs 提出修复，reopen 后仅改 specs 也算文档变化
-    const docs = ["proposal.md", "design.md", "tasks.md", "specs/", ".superspec/artifacts/test-contract.md"];
+    // 与 Propose gate 的可修改审查目标保持同一来源：specs/ 用目录聚合指纹，避免 reopen 基线漏掉任一个可修改的计划材料。
+    const docs = PROPOSE_FINAL_REVIEW_GATE.reviewTargets;
     const baseline = {};
     for (const doc of docs) {
         baseline[doc] = docRef(changeRoot, doc).sha;
     }
     return baseline;
 }
+function isDigestMap(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    return entries.length > 0 && entries.every(([, digest]) => typeof digest === "string");
+}
+export function latestAcceptedProposalBaseline(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition !== "accept" ||
+            payload.from_state !== "review" ||
+            payload.to_state !== "accepted")
+            continue;
+        return isDigestMap(payload.accepted_baseline_docs)
+            ? payload.accepted_baseline_docs
+            : null;
+    }
+    return null;
+}
 export function latestReopenProposeBaseline(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const ev = events[i];
@@ -185,8 +219,42 @@ export function pendingTaskStatusForApply(changeRoot, events) {
 export function formatPendingTaskMessage(ids, action) {
     return `尚有未完成任务：${ids.join(", ")}；${action}`;
 }
+function nextArgv(change, risk) {
+    return [
+        "superspec",
+        "transition",
+        "next",
+        "--change",
+        change,
+        ...(risk === "strict" ? [] : ["--risk", risk]),
+    ];
+}
+function acceptedMaterialFollowup(change, risk, planDocsChangedSinceAccept) {
+    return {
+        kind: "accepted_material_followup",
+        trigger: "material_user_followup",
+        reason_source: "summarize_user_input",
+        reopen_argv_template: [
+            "superspec",
+            "transition",
+            "reopen",
+            "--change",
+            change,
+            "--to",
+            "propose",
+            "--reason",
+            "{{reason}}",
+        ],
+        resume: {
+            kind: "continue_current_phase",
+            instruction: "根据用户补充更新 proposal/specs/design/tasks/test-contract；完成后重新执行 next。",
+            next_argv_after_completion: nextArgv(change, risk),
+        },
+        plan_docs_changed_since_accept: planDocsChangedSinceAccept,
+    };
+}
 export function planNextStep(context) {
-    const { changeRoot, mode, snapshot } = context;
+    const { change, changeRoot, events, mode, snapshot } = context;
     switch (snapshot.state) {
         case "init":
             if (snapshot.open_jobs.length > 0) {
@@ -217,6 +285,12 @@ export function planNextStep(context) {
                 };
                 return { kind: "ask_user", state: "explore", ask, reason: `有 ${openQs} 个未确认问题` };
             }
+            const requiredRoles = EXPLORE_DISCOVERY_REVIEW_GATE.requiredRolesForRisk(mode.risk);
+            if (!reviewGatePlan(snapshot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles)) {
+                const confirmation = phaseConfirmationStep(context, "explore_to_propose", "探索完成，等待用户确认进入计划阶段");
+                if (confirmation)
+                    return confirmation;
+            }
             return {
                 kind: "run_transition",
                 state: "explore",
@@ -253,6 +327,12 @@ export function planNextStep(context) {
             if (proposalReviewJobs.length > 0) {
                 return requiredJobs("propose_ready", proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
             }
+            const startApplyPlan = planStartApplyTransition(context, false);
+            if (startApplyPlan.kind === "advance") {
+                const confirmation = phaseConfirmationStep(context, "propose_to_apply", "计划阶段完成，等待用户确认开始实现");
+                if (confirmation)
+                    return confirmation;
+            }
             return { kind: "run_transition", state: "propose_ready", transition: "start-apply", reason: "计划就绪，开始执行" };
         }
         case "apply":
@@ -263,14 +343,28 @@ export function planNextStep(context) {
             return planReviewNext(context);
         case "accepted":
             if (snapshot.open_jobs.length > 0) {
-                return requiredJobs("accepted", snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项，暂不归档`);
+                return requiredJobs("accepted", snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项，暂不结束流程`);
+            }
+            {
+                const acceptedBaseline = latestAcceptedProposalBaseline(events);
+                const planDocsChanged = acceptedBaseline
+                    ? proposalDocsChangedSinceBaseline(changeRoot, acceptedBaseline)
+                    : null;
+                const driftNote = planDocsChanged === true
+                    ? "检测到 accepted 后计划材料已变化；当前完成结论仍对应 accepted 时冻结的版本。"
+                    : "";
+                return {
+                    kind: "done",
+                    state: "accepted",
+                    reason: `${driftNote}审查已接受，流程完成；后续若使用者补充或修改需求、方案、验收或实现约束，按 continuation 自动回到 propose 后继续，不得要求使用者执行工作流命令`,
+                    continuation: acceptedMaterialFollowup(change, mode.risk, planDocsChanged),
+                };
             }
-            return { kind: "ask_archive_confirmation", state: "accepted", reason: "审查通过，等待用户确认归档" };
         case "archive":
             if (snapshot.open_jobs.length > 0) {
-                return requiredJobs("archive", snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项，暂不结束`);
+                return requiredJobs("archive", snapshot.open_jobs, `历史 archive 状态仍有 ${snapshot.open_jobs.length} 个待完成工作项`);
             }
-            return { kind: "done", state: "archive", reason: "已归档，流程完成。" };
+            return { kind: "done", state: "archive", reason: "历史 archive 状态，流程已结束。" };
         case "abandoned":
             return { kind: "done", state: "abandoned", reason: "变更已放弃，流程终止。" };
         default:
@@ -320,6 +414,14 @@ function planApplyNext(context) {
         reason: "所有任务完成，进入审查",
     };
 }
+export function blockingJobsForApplyDone(projectRoot, events, snapshot) {
+    const facts = collectCodeReviewGateFacts(events);
+    const currentWorkingPaths = currentCodeReviewWorkingPaths(projectRoot, events);
+    const freshCodeReviewJobIds = new Set(facts.openJobs
+        .filter(job => codeReviewJobStaleReason(projectRoot, job, currentWorkingPaths) == null)
+        .map(job => job.job_id));
+    return snapshot.open_jobs.filter(job => job.role !== "code-reviewer" || freshCodeReviewJobIds.has(job.job_id));
+}
 function planApplyDoneNext(context) {
     const { change, changeRoot, events, mode, snapshot } = context;
     const pendingTasks = pendingTaskStatusForApply(changeRoot, events).pending;
@@ -332,10 +434,12 @@ function planApplyDoneNext(context) {
             reason: `发现未完成任务 ${pendingTasks[0]}，回到执行阶段`,
         };
     }
-    if (snapshot.open_jobs.length > 0) {
-        return requiredJobs("apply_done", snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项`);
-    }
     const facts = collectCodeReviewGateFacts(events);
+    const currentWorkingPaths = currentCodeReviewWorkingPaths(context.projectRoot, events);
+    const relevantOpenJobs = blockingJobsForApplyDone(context.projectRoot, events, snapshot);
+    if (relevantOpenJobs.length > 0) {
+        return requiredJobs("apply_done", relevantOpenJobs, `有 ${relevantOpenJobs.length} 个待完成工作项`);
+    }
     const latest = facts.latestTerminal;
     if (latest?.state === "rejected" && latest.result_kind === "review_failed") {
         const status = latestCodeReviewFailedStatus(events);
@@ -423,6 +527,19 @@ function planApplyDoneNext(context) {
         };
         return { kind: "ask_user", state: "apply_done", ask, reason: "代码审查报告连续不符合要求或没有可处理问题" };
     }
+    const codeScan = scanCodeChangesForReview(context.projectRoot, events);
+    const acceptedScope = latest?.state === "accepted"
+        ? latest.job.packet_context?.code_review_scope
+        : undefined;
+    const acceptedCurrentHead = acceptedScope?.current_head;
+    const acceptedReviewReady = latest?.state === "accepted" &&
+        codeReviewJobStaleReason(context.projectRoot, latest.job, currentWorkingPaths) == null && (acceptedCurrentHead === null ||
+        (typeof acceptedCurrentHead === "string" && acceptedCurrentHead.trim() !== ""));
+    if (!codeScan.hasCodeChanges || acceptedReviewReady) {
+        const confirmation = phaseConfirmationStep(context, "apply_to_review", "Apply 与代码审查完成，等待用户确认进入最终审查");
+        if (confirmation)
+            return confirmation;
+    }
     return {
         kind: "run_transition",
         state: "apply_done",
@@ -485,7 +602,7 @@ export function planTransition(name, context) {
     }
 }
 function planExploreTransition(context) {
-    const { changeRoot, mode, snapshot } = context;
+    const { changeRoot, events, mode, projectRoot, snapshot } = context;
     if (snapshot.state === "init") {
         return { kind: "advance", fromState: "init", toState: "explore", reason: "进入探索阶段" };
     }
@@ -499,7 +616,18 @@ function planExploreTransition(context) {
     const gatePlan = reviewGatePlan(snapshot, EXPLORE_DISCOVERY_REVIEW_GATE, requiredRoles);
     if (gatePlan)
         return gatePlan;
-    return { kind: "advance", fromState: "explore", toState: "propose", reason: "探索完成" };
+    const confirmation = phaseConfirmationForBoundary(projectRoot, events, snapshot, "explore_to_propose");
+    const decision = confirmation ? latestAcceptedPhaseDecision(events, confirmation) : null;
+    if (!confirmation || decision?.decision !== "advance") {
+        return { kind: "skip", message: confirmation ? phaseConfirmationMissingMessage(confirmation) : "无法建立 Explore 阶段确认范围" };
+    }
+    return {
+        kind: "advance",
+        fromState: "explore",
+        toState: "propose",
+        reason: "探索完成",
+        payload: phaseConfirmationCommitPayload(confirmation, decision),
+    };
 }
 function planProposeReadyTransition(context) {
     const { changeRoot, mode, snapshot } = context;
@@ -526,7 +654,7 @@ function planProposeReadyTransition(context) {
         return gatePlan;
     return { kind: "advance", fromState: "propose", toState: "propose_ready", reason: `risk=${risk}，所有需求已满足` };
 }
-function planStartApplyTransition(context) {
+function planStartApplyTransition(context, enforceConfirmation = true) {
     const { changeRoot, events, projectRoot, snapshot } = context;
     if (snapshot.state !== "propose_ready")
         return { kind: "skip", message: `当前状态 ${snapshot.state}，需要 propose_ready` };
@@ -548,6 +676,11 @@ function planStartApplyTransition(context) {
     const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot);
     if (!executionRequirementPlan.ok)
         return { kind: "skip", message: executionRequirementPlan.message };
+    const confirmation = phaseConfirmationForBoundary(projectRoot, events, snapshot, "propose_to_apply");
+    const decision = confirmation ? latestAcceptedPhaseDecision(events, confirmation) : null;
+    if (enforceConfirmation && (!confirmation || decision?.decision !== "advance")) {
+        return { kind: "skip", message: confirmation ? phaseConfirmationMissingMessage(confirmation) : "无法建立 Propose 阶段确认范围" };
+    }
     const gitHead = currentGitHead(projectRoot);
     return {
         kind: "advance",
@@ -558,6 +691,7 @@ function planStartApplyTransition(context) {
             apply_start_head: gitHead.head,
             apply_start_head_reason: gitHead.reason,
             apply_contract_mode: executionRequirementPlan.mode,
+            ...(confirmation && decision?.decision === "advance" ? phaseConfirmationCommitPayload(confirmation, decision) : {}),
         },
     };
 }
@@ -578,5 +712,11 @@ function planAcceptTransition(context) {
         if (!verifierAccepted)
             return { kind: "skip", message: "缺少仍然匹配当前证据的最终验证，请先运行 review-ready" };
     }
-    return { kind: "advance", fromState: "review", toState: "accepted", reason: "审查通过" };
+    return {
+        kind: "advance",
+        fromState: "review",
+        toState: "accepted",
+        reason: "审查通过",
+        payload: { accepted_baseline_docs: proposalDocsBaseline(changeRoot) },
+    };
 }