soloforge 1.4.16 → 2.0.0

package/dist/engine/pipeline/state_machine/pipeline_state_machine.js

@@ -0,0 +1,1197 @@
+/**
+ * 管线状态机 — 状态转换、阶段序列、持久化、并发锁。
+ *
+ * 初始化 → 阶段执行 → 推进 → 回退 → 门禁检查。
+ *
+ * 持久化格式：YAML 文件（.soloforge/state/pipeline-{id}.yaml）。
+ * 并发控制：乐观锁（lock.version）CAS 校验。
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { findPipelineBySystemType, findStageContract } from "../../workflow/workflow_contract_registry.js";
+import { evaluateCertaintyGate } from "./certainty_gate.js";
+import { getStageActions, getDefaultAction } from "./stage_command_registry.js";
+import { STAGE_WORKFLOW_MAP } from "../../../types/state_machine.js";
+import { runSelfDiagnostic } from "./state_self_diagnostic.js";
+import { verifyStrongConfirmation, generateJumpConfirmationText, generateResetConfirmationText, } from "./strong_confirmation.js";
+import { runPrivacyGate } from "../intent_expander/privacy_gates.js";
+import { appendAuditLog, saveSnapshot } from "./audit_logger.js";
+import { scoreGateCheckConfidence } from "../../audit/confidence_scorer.js";
+import { resolveBrainstormTrigger, resolveFirstPrinciplesTrigger } from "./uncertainty_bridge.js";
+/**
+ * 管线状态机 — 管理单个管线的完整生命周期。
+ *
+ * 使用方式：
+ * ```typescript
+ * const sm = new PipelineStateMachine(stateDir);
+ * const init = await sm.init({ system_type: "新系统", description: "..." });
+ * const exec = await sm.executeStage({ description: "...", knowledgeIndex, config });
+ * const adv = await sm.advanceStage({ knowledgeIndex, config });
+ * ```
+ */
+export class PipelineStateMachine {
+    stateDir;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+    }
+    // ── 初始化 ──
+    /**
+     * 初始化新管线。
+     *
+     * @returns 初始化结果，包含管线 ID 和初始阶段
+     * @throws 管线已存在时返回现有管线信息
+     */
+    async init(params) {
+        // 检查是否已有活跃管线
+        const existing = await this.getCurrentPipeline();
+        if (existing) {
+            return {
+                pipeline_id: existing.pipeline_id,
+                system_type: existing.system_type,
+                initial_stage: existing.current_stage,
+                stage_count: existing.stages.length,
+                available_actions: [],
+                required_inputs: [],
+            };
+        }
+        // 获取阶段序列
+        const pipelineContract = findPipelineBySystemType(params.system_type);
+        if (!pipelineContract) {
+            throw new Error(`未找到 ${params.system_type} 管线契约`);
+        }
+        const stageSequence = pipelineContract.stages;
+        const pipelineId = `pipeline-${crypto.randomUUID().slice(0, 8)}`;
+        const now = new Date().toISOString();
+        // 构建初始状态（包含新字段：output_hashes, rollback_history, audit_log）
+        const state = {
+            version: "1.0",
+            pipeline_id: pipelineId,
+            system_type: params.system_type,
+            description: params.description,
+            current_stage: stageSequence[0],
+            stages: stageSequence.map((stage, index) => ({
+                stage,
+                status: (index === 0 ? "in_progress" : "pending"),
+                started_at: index === 0 ? now : null,
+                completed_at: null,
+                outputs: [],
+            })),
+            lock: {
+                version: 1,
+                locked_at: now,
+            },
+            output_hashes: {},
+            rollback_history: [],
+            audit_log: [{
+                    timestamp: now,
+                    operation: "init",
+                    reason: `初始化${params.system_type}管线`,
+                }],
+        };
+        // 持久化
+        await this.save(state);
+        await this.writePointer(pipelineId);
+        // 获取初始阶段的必需输入
+        const initialStageContract = findStageContract(stageSequence[0]);
+        const requiredInputs = initialStageContract?.required_inputs ?? [];
+        return {
+            pipeline_id: pipelineId,
+            system_type: params.system_type,
+            initial_stage: stageSequence[0],
+            stage_count: stageSequence.length,
+            available_actions: [
+                {
+                    action: "execute",
+                    description_zh: `执行当前阶段: ${stageSequence[0]}`,
+                    tool: "sf_stage_execute",
+                    params: { stage: stageSequence[0] },
+                },
+                {
+                    action: "gate_check",
+                    description_zh: "运行确定性门禁检查",
+                    tool: "sf_gate_check",
+                },
+            ],
+            required_inputs: requiredInputs,
+        };
+    }
+    // ── 读取 ──
+    /** 加载指定管线状态 */
+    async load(pipelineId) {
+        const filePath = this.pipelinePath(pipelineId);
+        try {
+            const content = await fs.readFile(filePath, "utf-8");
+            const parsed = YAML.parse(content);
+            // 兼容旧格式：补全缺失字段
+            return ensurePipelineStateFields(parsed);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 获取当前活跃管线 */
+    async getCurrentPipeline() {
+        const pointer = await this.readPointer();
+        if (!pointer)
+            return null;
+        return this.load(pointer.pipeline_id);
+    }
+    // ── 阶段执行 ──
+    /**
+     * 执行阶段工作或恢复操作。
+     *
+     * 标准流程：
+     * 1. 加载管线状态
+     * 2. 运行自诊断
+     * 3. 运行隐私门禁
+     * 4. 运行确定性门禁
+     * 5. 注入知识
+     * 6. 返回执行结果
+     *
+     * 恢复操作：diagnose / repair / jump / reset / archive
+     */
+    async executeStage(params) {
+        // ── 恢复操作分发 ──
+        const action = params.action;
+        if (action === "diagnose")
+            return this.handleDiagnose(params);
+        if (action === "repair")
+            return this.handleRepair(params);
+        if (action === "jump")
+            return this.handleJump(params);
+        if (action === "reset")
+            return this.handleReset(params);
+        if (action === "archive")
+            return this.handleArchive(params);
+        // ── 标准阶段执行 ──
+        const state = await this.requireCurrentPipeline();
+        const stage = params.stage ?? state.current_stage;
+        // 自诊断检查
+        const diagnosticReport = await runSelfDiagnostic(this.stateDir);
+        // 校验阶段在管线中存在
+        const stageEntry = state.stages.find((s) => s.stage === stage);
+        if (!stageEntry) {
+            throw new Error(`阶段 "${stage}" 不在管线中`);
+        }
+        // 隐私门禁检查
+        const description = params.description ?? "";
+        const privacyResult = runPrivacyGate(description, { lightweight: true }, [], // 无输入材料（stage-native 路径由 stage_executor 提供）
+        stage);
+        if (privacyResult.privacyGate.hard_fail) {
+            return {
+                task_id: params.task_id ?? null,
+                pipeline_id: state.pipeline_id,
+                stage,
+                action: action ?? "execute",
+                status: "in_progress",
+                outputs: [],
+                knowledge_hit_count: 0,
+                gate_result: null,
+                next_actions: [],
+                delegate_hint: null,
+                blocked: true,
+                block_reason: "隐私门禁阻断: " + (privacyResult.privacyGate.blocked_sources.join(", ") || "敏感信息检测"),
+                diagnostic_report: diagnosticReport,
+            };
+        }
+        // 运行确定性门禁
+        const gateResult = await this.runGateCheck(stage, state, description, params.knowledgeIndex, params.config);
+        // 知识注入计数
+        let knowledgeHitCount = 0;
+        try {
+            const results = params.knowledgeIndex.query({ stages: [stage], limit: 50 });
+            knowledgeHitCount = results.length;
+        }
+        catch {
+            // 知识查询失败不阻断
+        }
+        // ── 上下文引擎分析 ──
+        let contextAnalysis;
+        try {
+            const { stageNeedsEngine, resolveContext } = await import("../../context_engine/index.js");
+            const { getView, dispatchView } = await import("../../context_engine/view_registry.js");
+            if (stageNeedsEngine(stage)) {
+                // 使用 file_impact 视图作为默认分析视图
+                const resolved = resolveContext({ view: "file_impact", source: "auto" }, stage, { scopeRoots: [] });
+                if (getView(resolved.view) && resolved.targets.length > 0) {
+                    const vr = await dispatchView(resolved.view, process.cwd(), {
+                        targets: resolved.targets,
+                        scope: resolved.scope,
+                    });
+                    contextAnalysis = vr.summary;
+                }
+            }
+        }
+        catch {
+            // 降级：上下文引擎失败不阻断管线
+        }
+        // ── 执行规则与门禁注入（companion_injector） ──
+        let companionInjection;
+        try {
+            const { injectCompanions } = await import("../../context_engine/companion_injector.js");
+            const matter = await import("gray-matter");
+            const fs = await import("node:fs/promises");
+            const path = await import("node:path");
+            const templateEntries = params.knowledgeIndex.query({
+                type: "acceptance_template",
+                stages: [stage],
+                limit: 5,
+            });
+            for (const entry of templateEntries) {
+                // 从模板文件读取 frontmatter 提取 companion_rules/companion_gates
+                const tplPath = path.resolve(process.cwd(), entry.file_path);
+                let raw;
+                try {
+                    raw = await fs.readFile(tplPath, "utf-8");
+                }
+                catch {
+                    continue;
+                }
+                const parsed = matter.default(raw);
+                const fm = (parsed.data ?? {});
+                const cr = fm.companion_rules;
+                const cg = fm.companion_gates;
+                if (cr?.length || cg?.length) {
+                    const result = injectCompanions({
+                        baseDir: process.cwd(),
+                        companion_rules: cr,
+                        companion_gates: cg,
+                        operation: "execute",
+                    });
+                    if (result.injection_text) {
+                        if (!companionInjection)
+                            companionInjection = result.injection_text;
+                        else
+                            companionInjection += "\n\n" + result.injection_text;
+                    }
+                }
+            }
+        }
+        catch {
+            // 降级：companion 注入失败不阻断管线
+        }
+        // 获取可用动作
+        const actionId = action ?? getDefaultAction(stage).action_id;
+        const actions = getStageActions(stage);
+        const nextActions = actions.map((a) => a.action_id);
+        // 委托提示（Phase 2 使用）
+        const delegateHint = buildDelegateHint(stage, actionId, params.description);
+        // 构建结果
+        const result = {
+            task_id: params.task_id ?? null,
+            pipeline_id: state.pipeline_id,
+            stage,
+            action: actionId,
+            status: stageEntry.status,
+            outputs: stageEntry.outputs,
+            knowledge_hit_count: knowledgeHitCount,
+            gate_result: gateResult,
+            next_actions: nextActions,
+            delegate_hint: delegateHint,
+            diagnostic_report: diagnosticReport,
+            context_analysis: contextAnalysis,
+            companion_injection: companionInjection,
+        };
+        // brainstorm 触发信息（通过 uncertainty_bridge 构建结构化请求）
+        if (gateResult.level2.brainstorm_required) {
+            const fpRules = gateResult.level2.fp_rules_triggered ?? [];
+            const fpSuffix = fpRules.length > 0 ? `；FP 规则命中: ${fpRules.join(", ")}` : "";
+            const req = resolveBrainstormTrigger(gateResult.level2.risk_patterns_hit, stage, `${stage} 阶段风险方案讨论`);
+            result.brainstorm_trigger = {
+                reason: `检测到风险模式: ${gateResult.level2.risk_patterns_hit.join(", ")}${fpSuffix}`,
+                suggestion: gateResult.level2.brainstorm_template?.default_strategy ?? req.topic,
+            };
+        }
+        // first_principles 触发信息（通过 uncertainty_bridge 构建结构化请求）
+        if (gateResult.level2.first_principles_required) {
+            const fpRules = gateResult.level2.fp_rules_triggered ?? [];
+            const fpSuffix = fpRules.length > 0 ? `；FP 规则命中: ${fpRules.join(", ")}` : "";
+            const req = resolveFirstPrinciplesTrigger(stage, gateResult.level2.risk_patterns_hit, `${stage} 阶段需要从第一性原理重新审视`);
+            result.first_principles_trigger = {
+                reason: `涉及高风险模式: ${gateResult.level2.risk_patterns_hit.join(", ")}${fpSuffix}`,
+                suggestion: `建议从第一性原理重新审视决策（参考 templates/rules/shared/第一性原理推理规则.md）— ${req.scope_description}`,
+            };
+        }
+        // 代码审查失败自动回退建议
+        if (stage === "代码审查" && !gateResult.overall_passed) {
+            result.auto_rollback_suggestion = {
+                target: "编码与单元测试",
+                reason: "代码审查未通过，建议回退到编码阶段修复问题",
+            };
+        }
+        // 架构设计阶段: 技术决策门控 — 评估技术决策契约完整性和执行权限
+        if (stage === "架构设计") {
+            try {
+                const { validateTechnologyDecision, evaluateDecisionExecution } = await import("../../contracts/technology_decision.js");
+                // 架构级决策需要人类门禁
+                const archDecision = {
+                    decision_id: `${state.pipeline_id}-arch-decision`,
+                    decision_scope: "architecture",
+                    human_gate_required: true,
+                    executable_without_human: false,
+                    options: [{ option_id: "default", title: "架构方案", description: params.description ?? "架构设计" }],
+                    recommended_option: "default",
+                    rejected_options: [],
+                    evidence: [],
+                    falsification: [],
+                    failure_conditions: [],
+                    validation_plan: [],
+                    rollback_or_exit_plan: [],
+                };
+                const validation = validateTechnologyDecision(archDecision);
+                const execution = evaluateDecisionExecution(archDecision, { decision_id: archDecision.decision_id, decision_status: "recommended", evidence_ids: [] });
+                result.architecture_decision_gate = {
+                    allowed: execution.allowed,
+                    reason_zh: execution.allowed ? "架构决策门控通过" : "架构决策需要人类确认后方可执行",
+                    validation: { valid: validation.valid, violations: validation.violations, warnings: validation.warnings },
+                    execution: { allowed: execution.allowed, requires_human_gate: archDecision.human_gate_required, executable_without_human: archDecision.executable_without_human, reason: execution.reason ?? "" },
+                };
+            }
+            catch {
+                // technology_decision 模块不可用时不阻断
+            }
+        }
+        return result;
+    }
+    // ── 阶段推进 ──
+    /**
+     * 推进到下一阶段。
+     *
+     * 1. 运行自诊断
+     * 2. 运行当前阶段门禁
+     * 3. 标记当前阶段为 completed
+     * 4. 标记下一阶段为 in_progress
+     * 5. 审计日志 + 持久化
+     */
+    async advanceStage(params) {
+        const state = await this.requireCurrentPipeline();
+        // 自诊断检查（Phase 2: fail-closed — 不健康时阻断推进）
+        const diagnosticReport = await runSelfDiagnostic(this.stateDir);
+        if (!diagnosticReport.healthy && !params.force) {
+            const issues = diagnosticReport.checks
+                .filter((c) => !c.passed)
+                .map((c) => c.issue)
+                .join("; ");
+            throw new Error(`管线自诊断发现异常: ${issues}。请运行 soloforge status 查看详情，或使用 --force 强制推进。`);
+        }
+        const currentStage = state.current_stage;
+        // 运行门禁
+        const gateResult = await this.runGateCheck(currentStage, state, "", params.knowledgeIndex, params.config);
+        // Phase 2: 门禁不通过时阻断推进（force 可跳过）
+        if (!gateResult.overall_passed && !params.force) {
+            const failedItems = gateResult.checks
+                .filter((item) => !item.passed)
+                .map((item) => `${item.name_zh}: ${item.blocking_reason ?? item.evidence}`)
+                .join("; ");
+            throw new Error(`阶段推进被门禁阻断: ${failedItems}。请解决门禁项后重试，或使用 --force 强制推进。`);
+        }
+        // 查找下一阶段
+        const stageSequence = state.stages.map((s) => s.stage);
+        const currentIndex = stageSequence.indexOf(currentStage);
+        const nextIndex = currentIndex + 1;
+        if (nextIndex >= stageSequence.length) {
+            throw new Error(`已处于最后阶段 "${currentStage}"，无法推进`);
+        }
+        const nextStage = stageSequence[nextIndex];
+        const fromStage = currentStage;
+        // B8: 任务推进一致性校验（Phase 2: fail-closed）
+        if (currentStage === "任务规划" && !params.force) {
+            const b8Result = checkTaskPlanningConsistency(state);
+            if (!b8Result.passed) {
+                throw new Error(`任务规划一致性校验失败: ${b8Result.details}。请解决后重试，或使用 --force 强制推进。`);
+            }
+        }
+        // B12: 阶段推进门禁完善（Phase 2: fail-closed）
+        if (currentStage === "现有系统分析" && !params.force) {
+            const b12Risk = checkCrashRisk(state);
+            if (b12Risk) {
+                throw new Error("检测到崩溃风险指标，请先完成崩溃风险分析。或使用 --force 强制推进。");
+            }
+        }
+        // 操作前保存快照 + 审计日志
+        let snapshotPath;
+        try {
+            snapshotPath = await saveSnapshot(this.stateDir, state.pipeline_id, state);
+        }
+        catch {
+            // 快照保存失败不阻断操作
+        }
+        // 内嵌审计日志
+        appendAuditLogEntry(state, {
+            timestamp: new Date().toISOString(),
+            operation: "advance",
+            from_stage: fromStage,
+            to_stage: nextStage,
+            user_confirmation: params.confirmation,
+            previous_snapshot_path: snapshotPath,
+        });
+        // 文件审计日志
+        appendAuditLog(this.stateDir, {
+            timestamp: new Date().toISOString(),
+            operation: "advance",
+            from_stage: fromStage,
+            to_stage: nextStage,
+            user_confirmation: params.confirmation,
+            previous_snapshot_path: snapshotPath,
+        }).catch(() => { });
+        // 更新状态
+        const now = new Date().toISOString();
+        for (const entry of state.stages) {
+            if (entry.stage === currentStage) {
+                entry.status = "completed";
+                entry.completed_at = now;
+            }
+            if (entry.stage === nextStage) {
+                entry.status = "in_progress";
+                entry.started_at = now;
+            }
+        }
+        state.current_stage = nextStage;
+        await this.save(state);
+        return {
+            pipeline_id: state.pipeline_id,
+            from_stage: fromStage,
+            to_stage: nextStage,
+            gate_passed: gateResult.overall_passed,
+            gate_result: gateResult,
+        };
+    }
+    // ── 阶段回退 ──
+    /**
+     * 回退到指定阶段。
+     *
+     * 1. 校验目标阶段在 rollback_targets 中
+     * 2. 审计日志 + 保存快照
+     * 3. 标记中间阶段为 skipped
+     * 4. 收集 stale 产出
+     * 5. 持久化
+     */
+    async rollbackStage(params) {
+        const state = await this.requireCurrentPipeline();
+        const currentStage = state.current_stage;
+        // 确定回退目标
+        const stageContract = findStageContract(currentStage);
+        if (!stageContract) {
+            throw new Error(`未找到阶段 "${currentStage}" 的契约`);
+        }
+        // 如果未指定目标，使用第一个 rollback_target
+        let targetStage = params.target_stage;
+        if (!targetStage) {
+            if (stageContract.rollback_targets.length === 0) {
+                throw new Error(`阶段 "${currentStage}" 无可回退目标`);
+            }
+            targetStage = stageContract.rollback_targets[0];
+        }
+        // 校验目标在允许列表中
+        const allowedTargets = [
+            ...stageContract.rollback_targets,
+            ...stageContract.rollback_annotate_targets,
+        ];
+        if (!allowedTargets.includes(targetStage)) {
+            throw new Error(`阶段 "${currentStage}" 不允许回退到 "${targetStage}"，允许目标: ${allowedTargets.join(", ")}`);
+        }
+        // 计算被跳过的阶段
+        const stageSequence = state.stages.map((s) => s.stage);
+        const targetIndex = stageSequence.indexOf(targetStage);
+        const currentIndex = stageSequence.indexOf(currentStage);
+        const skippedStages = [];
+        const staleOutputs = [];
+        const lostOutputs = [];
+        const now = new Date().toISOString();
+        for (let i = targetIndex + 1; i <= currentIndex; i++) {
+            const stage = stageSequence[i];
+            const entry = state.stages[i];
+            skippedStages.push(stage);
+            staleOutputs.push(...entry.outputs);
+            // 已完成阶段的产出在回退后视为丢失
+            if (entry.status === "completed") {
+                lostOutputs.push(...entry.outputs);
+            }
+            entry.status = "skipped";
+            entry.completed_at = now;
+        }
+        // 设置目标阶段为 in_progress
+        const targetEntry = state.stages[targetIndex];
+        targetEntry.status = "in_progress";
+        targetEntry.started_at = now;
+        state.current_stage = targetStage;
+        // 操作前保存快照
+        let snapshotPath;
+        try {
+            snapshotPath = await saveSnapshot(this.stateDir, state.pipeline_id, state);
+        }
+        catch {
+            // 快照保存失败不阻断操作
+        }
+        // 内嵌审计日志
+        appendAuditLogEntry(state, {
+            timestamp: now,
+            operation: "rollback",
+            from_stage: currentStage,
+            to_stage: targetStage,
+            reason: params.reason,
+            previous_snapshot_path: snapshotPath,
+        });
+        // 文件审计日志
+        appendAuditLog(this.stateDir, {
+            timestamp: now,
+            operation: "rollback",
+            from_stage: currentStage,
+            to_stage: targetStage,
+            reason: params.reason,
+            previous_snapshot_path: snapshotPath,
+        }).catch(() => { });
+        // 追加回退历史
+        state.rollback_history.push({
+            from: currentStage,
+            to: targetStage,
+            reason: params.reason,
+            at: now,
+        });
+        await this.save(state);
+        return {
+            pipeline_id: state.pipeline_id,
+            from_stage: currentStage,
+            to_stage: targetStage,
+            stale_outputs: staleOutputs,
+            skipped_stages: skippedStages,
+            lost_outputs: lostOutputs,
+            directive: "回退后需重新执行被跳过阶段",
+            context_snapshot: snapshotPath,
+        };
+    }
+    // ── 门禁检查 ──
+    /**
+     * 显式门禁检查（不修改状态）。
+     */
+    async checkGate(params) {
+        const state = await this.requireCurrentPipeline();
+        const stage = params.stage ?? state.current_stage;
+        return this.runGateCheck(stage, state, "", params.knowledgeIndex, params.config);
+    }
+    // ── 下一步导航 ──
+    /**
+     * 获取下一步导航信息。
+     *
+     * 综合管线状态、项目阶段、可用动作、阻断项和确认项，
+     * 返回完整的导航快照供 AI 和用户参考。
+     */
+    async getNext() {
+        // 自诊断检查
+        const diagnosticReport = await runSelfDiagnostic(this.stateDir);
+        const pipeline = await this.getCurrentPipeline();
+        // 无活跃管线：返回初始导航
+        if (!pipeline) {
+            return {
+                pipeline_type: null,
+                pipeline_active: false,
+                project_stage: "uninitialized",
+                current_task_stage: null,
+                stage_status: "not_started",
+                progress_percent: 0,
+                available_actions: [
+                    {
+                        action: "init",
+                        description_zh: "初始化开发管线",
+                        tool: "sf_pipeline_init",
+                        params: { system_type: "新系统" },
+                    },
+                ],
+                blocking_items: [],
+                confirmations: [],
+                work_package: null,
+            };
+        }
+        // 计算进度百分比（防止空 stages 数组导致 NaN）
+        const totalStages = pipeline.stages.length;
+        const completedCount = pipeline.stages.filter((s) => s.status === "completed").length;
+        const progressPercent = totalStages === 0 ? 0 : Math.round((completedCount / totalStages) * 100);
+        // 当前阶段状态映射
+        const currentEntry = pipeline.stages.find((s) => s.stage === pipeline.current_stage);
+        const stageStatus = mapStageStatus(currentEntry?.status ?? "pending");
+        // 构建可用动作
+        const availableActions = buildAvailableActions(pipeline);
+        // 构建阻断项（自诊断发现问题时提示）
+        const blockingItems = [];
+        if (!diagnosticReport.healthy) {
+            const issues = diagnosticReport.checks
+                .filter((c) => !c.passed && c.severity === "error")
+                .map((c) => c.issue);
+            if (issues.length > 0) {
+                blockingItems.push({
+                    reason: `自诊断发现问题: ${issues.join("; ")}`,
+                    resolution_command: "[sf] 诊断",
+                });
+            }
+        }
+        // 构建确认项
+        const confirmations = [];
+        // 项目阶段推断
+        const projectStage = inferProjectStage(pipeline);
+        return {
+            pipeline_type: `pipeline-${pipeline.system_type === "新系统" ? "new" : "existing"}-system`,
+            pipeline_active: true,
+            project_stage: projectStage,
+            current_task_stage: pipeline.current_stage,
+            stage_status: stageStatus,
+            progress_percent: progressPercent,
+            available_actions: availableActions,
+            blocking_items: blockingItems,
+            confirmations: confirmations,
+            work_package: null,
+        };
+    }
+    // ── 管线全貌 ──
+    /**
+     * 获取管线全貌快照。
+     *
+     * 返回所有阶段的状态、进度百分比和回退历史。
+     */
+    async getPipelineStatus() {
+        const pipeline = await this.requireCurrentPipeline();
+        // 计算当前阶段索引和进度（防止空 stages 数组导致 NaN）
+        const currentIndex = pipeline.stages.findIndex((s) => s.stage === pipeline.current_stage);
+        const completedCount = pipeline.stages.filter((s) => s.status === "completed").length;
+        const progressPercent = pipeline.stages.length === 0 ? 0 : Math.round((completedCount / pipeline.stages.length) * 100);
+        // 映射阶段详情
+        const stages = pipeline.stages.map((entry) => ({
+            stage: entry.stage,
+            status: entry.status === "in_progress"
+                ? "in_progress"
+                : entry.status === "completed"
+                    ? "completed"
+                    : entry.status === "skipped"
+                        ? "skipped"
+                        : "pending",
+            started_at: entry.started_at ?? undefined,
+            completed_at: entry.completed_at ?? undefined,
+            outputs: entry.outputs,
+        }));
+        // 读取回退历史
+        const rollbackHistory = pipeline.rollback_history.map((entry) => ({
+            from: entry.from,
+            to: entry.to,
+            reason: entry.reason,
+            at: entry.at,
+        }));
+        return {
+            pipeline_type: `pipeline-${pipeline.system_type === "新系统" ? "new" : "existing"}-system`,
+            system_type: pipeline.system_type === "新系统" ? "new_system" : "existing_system",
+            stages,
+            current_stage_index: currentIndex,
+            progress_percent: progressPercent,
+            rollback_history: rollbackHistory,
+        };
+    }
+    // ═══════════════════════════════════════════
+    // 恢复操作处理器
+    // ═══════════════════════════════════════════
+    /** 诊断：运行自诊断并返回报告 */
+    async handleDiagnose(_params) {
+        const diagnosticReport = await runSelfDiagnostic(this.stateDir);
+        const state = await this.getCurrentPipeline();
+        return {
+            task_id: _params.task_id ?? null,
+            pipeline_id: state?.pipeline_id ?? "no-pipeline",
+            stage: state?.current_stage ?? "需求分析",
+            action: "diagnose",
+            status: "in_progress",
+            outputs: [],
+            knowledge_hit_count: 0,
+            gate_result: null,
+            next_actions: [],
+            delegate_hint: null,
+            diagnostic_report: diagnosticReport,
+        };
+    }
+    /** 修复：基于诊断结果自动修复 */
+    async handleRepair(_params) {
+        await runSelfDiagnostic(this.stateDir);
+        const state = await this.requireCurrentPipeline();
+        // 修复逻辑：补全缺失字段
+        let repaired = false;
+        const fixDetails = [];
+        // 补全 output_hashes
+        if (!state.output_hashes) {
+            state.output_hashes = {};
+            repaired = true;
+            fixDetails.push("补全 output_hashes 字段");
+        }
+        // 补全 rollback_history
+        if (!state.rollback_history) {
+            state.rollback_history = [];
+            repaired = true;
+            fixDetails.push("补全 rollback_history 字段");
+        }
+        // 补全 audit_log
+        if (!state.audit_log) {
+            state.audit_log = [];
+            repaired = true;
+            fixDetails.push("补全 audit_log 字段");
+        }
+        if (repaired) {
+            appendAuditLogEntry(state, {
+                timestamp: new Date().toISOString(),
+                operation: "repair",
+                reason: `自动修复: ${fixDetails.join(", ")}`,
+            });
+            await this.save(state);
+        }
+        return {
+            task_id: _params.task_id ?? null,
+            pipeline_id: state.pipeline_id,
+            stage: state.current_stage,
+            action: "repair",
+            status: "in_progress",
+            outputs: [],
+            knowledge_hit_count: 0,
+            gate_result: null,
+            next_actions: [],
+            delegate_hint: null,
+            diagnostic_report: await runSelfDiagnostic(this.stateDir),
+            block_reason: repaired ? `已修复: ${fixDetails.join(", ")}` : "无需修复",
+        };
+    }
+    /** 跳转：强确认后跳转到指定阶段 */
+    async handleJump(params) {
+        const state = await this.requireCurrentPipeline();
+        const targetStage = params.target_stage ?? params.stage;
+        if (!targetStage) {
+            return {
+                task_id: params.task_id ?? null,
+                pipeline_id: state.pipeline_id,
+                stage: state.current_stage,
+                action: "jump",
+                status: "in_progress",
+                outputs: [],
+                knowledge_hit_count: 0,
+                gate_result: null,
+                next_actions: [],
+                delegate_hint: null,
+                blocked: true,
+                block_reason: "跳转操作必须指定目标阶段",
+            };
+        }
+        // 强确认校验
+        const expectedConfirmation = generateJumpConfirmationText(targetStage);
+        if (!params.confirmation_text || !verifyStrongConfirmation(expectedConfirmation, params.confirmation_text)) {
+            return {
+                task_id: params.task_id ?? null,
+                pipeline_id: state.pipeline_id,
+                stage: state.current_stage,
+                action: "jump",
+                status: "in_progress",
+                outputs: [],
+                knowledge_hit_count: 0,
+                gate_result: null,
+                next_actions: [],
+                delegate_hint: null,
+                blocked: true,
+                block_reason: "需要强确认才能跳转",
+                required_confirmation: expectedConfirmation,
+            };
+        }
+        // 校验目标阶段在管线中存在
+        const targetEntry = state.stages.find((s) => s.stage === targetStage);
+        if (!targetEntry) {
+            return {
+                task_id: params.task_id ?? null,
+                pipeline_id: state.pipeline_id,
+                stage: state.current_stage,
+                action: "jump",
+                status: "in_progress",
+                outputs: [],
+                knowledge_hit_count: 0,
+                gate_result: null,
+                next_actions: [],
+                delegate_hint: null,
+                blocked: true,
+                block_reason: `目标阶段 "${targetStage}" 不在管线中`,
+            };
+        }
+        // 执行跳转
+        const now = new Date().toISOString();
+        const currentStage = state.current_stage;
+        // 审计日志
+        appendAuditLogEntry(state, {
+            timestamp: now,
+            operation: "jump",
+            from_stage: currentStage,
+            to_stage: targetStage,
+            user_confirmation: params.confirmation_text,
+        });
+        // 更新阶段状态
+        for (const entry of state.stages) {
+            if (entry.stage === currentStage && entry.status === "in_progress") {
+                entry.status = "pending";
+                entry.started_at = null;
+            }
+        }
+        targetEntry.status = "in_progress";
+        targetEntry.started_at = now;
+        state.current_stage = targetStage;
+        await this.save(state);
+        return {
+            task_id: params.task_id ?? null,
+            pipeline_id: state.pipeline_id,
+            stage: targetStage,
+            action: "jump",
+            status: "in_progress",
+            outputs: targetEntry.outputs,
+            knowledge_hit_count: 0,
+            gate_result: null,
+            next_actions: [],
+            delegate_hint: null,
+        };
+    }
+    /** 重置：强确认后清空管线状态 */
+    async handleReset(params) {
+        const state = await this.requireCurrentPipeline();
+        // 强确认校验
+        const expectedConfirmation = generateResetConfirmationText(state.pipeline_id);
+        if (!params.confirmation_text || !verifyStrongConfirmation(expectedConfirmation, params.confirmation_text)) {
+            return {
+                task_id: params.task_id ?? null,
+                pipeline_id: state.pipeline_id,
+                stage: state.current_stage,
+                action: "reset",
+                status: "in_progress",
+                outputs: [],
+                knowledge_hit_count: 0,
+                gate_result: null,
+                next_actions: [],
+                delegate_hint: null,
+                blocked: true,
+                block_reason: "需要强确认才能重置管线",
+                required_confirmation: expectedConfirmation,
+            };
+        }
+        // 审计日志（重置前记录）
+        appendAuditLogEntry(state, {
+            timestamp: new Date().toISOString(),
+            operation: "reset",
+            reason: "用户请求重置管线",
+            user_confirmation: params.confirmation_text,
+        });
+        // 删除管线文件和指针
+        const yamlPath = this.pipelinePath(state.pipeline_id);
+        try {
+            await fs.unlink(yamlPath);
+        }
+        catch {
+            // 文件可能已不存在
+        }
+        const pointerPath = this.currentPointerPath();
+        try {
+            await fs.unlink(pointerPath);
+        }
+        catch {
+            // 文件可能已不存在
+        }
+        return {
+            task_id: params.task_id ?? null,
+            pipeline_id: state.pipeline_id,
+            stage: state.current_stage,
+            action: "reset",
+            status: "pending",
+            outputs: [],
+            knowledge_hit_count: 0,
+            gate_result: null,
+            next_actions: [],
+            delegate_hint: null,
+            block_reason: "管线已重置，请使用 [sf] 初始化 重新开始",
+        };
+    }
+    /** 归档：标记管线为归档状态 */
+    async handleArchive(_params) {
+        const state = await this.requireCurrentPipeline();
+        // 审计日志
+        appendAuditLogEntry(state, {
+            timestamp: new Date().toISOString(),
+            operation: "archive",
+            reason: "用户请求归档管线",
+        });
+        // 归档操作：清除指针文件（管线文件保留供历史查询）
+        const pointerPath = this.currentPointerPath();
+        try {
+            await fs.unlink(pointerPath);
+        }
+        catch {
+            // 文件可能已不存在
+        }
+        return {
+            task_id: _params.task_id ?? null,
+            pipeline_id: state.pipeline_id,
+            stage: state.current_stage,
+            action: "archive",
+            status: "completed",
+            outputs: [],
+            knowledge_hit_count: 0,
+            gate_result: null,
+            next_actions: [],
+            delegate_hint: null,
+            block_reason: "管线已归档",
+        };
+    }
+    // ═══════════════════════════════════════════
+    // 私有方法
+    // ═══════════════════════════════════════════
+    /** 运行门禁检查（公共逻辑抽取） */
+    async runGateCheck(stage, pipelineState, workDescription, knowledgeIndex, config) {
+        const gateResult = evaluateCertaintyGate({
+            stage,
+            knowledgeIndex,
+            workDescription,
+            pipelineState,
+            config,
+        });
+        // 附加置信度评分（由 confidence_scorer 基于门禁结果评估）
+        const confidenceScore = scoreGateCheckConfidence({
+            allChecksPassed: gateResult.overall_passed,
+            hasFailures: !gateResult.overall_passed,
+            isDegraded: gateResult.level1.knowledge_hits < gateResult.level1.min_required,
+            evidenceCount: gateResult.checks.filter((c) => c.passed).length,
+            matchedPatternsCount: gateResult.level2.risk_patterns_hit.length,
+        });
+        return { ...gateResult, confidence_score: confidenceScore };
+    }
+    /** 要求当前有活跃管线，否则抛出错误 */
+    async requireCurrentPipeline() {
+        const state = await this.getCurrentPipeline();
+        if (!state) {
+            throw new Error("无活跃管线，请先调用 sf_pipeline_init 初始化");
+        }
+        return state;
+    }
+    /** 管线 YAML 文件路径 */
+    pipelinePath(pipelineId) {
+        return path.join(this.stateDir, `${pipelineId}.yaml`);
+    }
+    /** 指针文件路径 */
+    currentPointerPath() {
+        return path.join(this.stateDir, "current-pipeline.json");
+    }
+    /**
+     * 原子保存管线状态 — CAS 乐观锁 + 进程内互斥。
+     *
+     * 写入前先读取磁盘当前版本，比较是否一致。
+     * 版本不匹配时抛出 OptimisticLockError。
+     * 进程内互斥确保同一进程中不会并发写入导致版本冲突。
+     */
+    saveInProgress = false;
+    async save(state) {
+        // 进程内互斥：防止同一进程内并发 save 导致乐观锁冲突
+        if (this.saveInProgress) {
+            throw new Error("save 操作正在进行中，请勿并发调用。");
+        }
+        this.saveInProgress = true;
+        try {
+            // CAS 校验：读取磁盘当前版本
+            const diskVersion = await this.readCurrentVersion(state.pipeline_id);
+            if (diskVersion !== null && diskVersion !== state.lock.version) {
+                throw new Error(`乐观锁冲突: 磁盘版本=${diskVersion}, 内存版本=${state.lock.version}。` +
+                    "请重新加载状态后重试。");
+            }
+            // 递增锁版本
+            state.lock.version++;
+            state.lock.locked_at = new Date().toISOString();
+            // 更新产出哈希（遍历阶段 outputs）
+            if (state.output_hashes) {
+                for (const entry of state.stages) {
+                    if (entry.outputs.length > 0) {
+                        const key = `${entry.stage}`;
+                        state.output_hashes[key] = crypto
+                            .createHash("sha256")
+                            .update(entry.outputs.join(","))
+                            .digest("hex")
+                            .slice(0, 16);
+                    }
+                }
+            }
+            const filePath = this.pipelinePath(state.pipeline_id);
+            const content = YAML.stringify(state);
+            // 原子写：先写临时文件再重命名
+            const tmpPath = filePath + ".tmp";
+            await fs.writeFile(tmpPath, content, "utf-8");
+            await fs.rename(tmpPath, filePath);
+        }
+        finally {
+            this.saveInProgress = false;
+        }
+    }
+    /** 读取磁盘上管线的当前版本号（fail-closed：仅 ENOENT 返回 null） */
+    async readCurrentVersion(pipelineId) {
+        const filePath = this.pipelinePath(pipelineId);
+        try {
+            const content = await fs.readFile(filePath, "utf-8");
+            const parsed = YAML.parse(content);
+            return parsed?.lock?.version ?? null;
+        }
+        catch (e) {
+            // ENOENT = 首次写入，无先前版本（正常）
+            if (e instanceof Error && "code" in e && e.code === "ENOENT") {
+                return null;
+            }
+            // 其他异常（权限拒绝、YAML 损坏、IO 错误）→ fail-closed
+            throw new Error(`管线版本号读取失败（CAS 校验），无法保证写入安全性: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /** 写管线指针 */
+    async writePointer(pipelineId) {
+        const pointerPath = this.currentPointerPath();
+        await fs.writeFile(pointerPath, JSON.stringify({ pipeline_id: pipelineId }), "utf-8");
+    }
+    /** 读管线指针 */
+    async readPointer() {
+        const pointerPath = this.currentPointerPath();
+        try {
+            const content = await fs.readFile(pointerPath, "utf-8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ═══════════════════════════════════════════
+// 辅助函数
+// ═══════════════════════════════════════════
+/** 补全旧管线状态的缺失字段 */
+function ensurePipelineStateFields(state) {
+    return {
+        ...state,
+        output_hashes: state.output_hashes ?? {},
+        rollback_history: state.rollback_history ?? [],
+        audit_log: state.audit_log ?? [],
+    };
+}
+/** 追加审计日志条目 */
+function appendAuditLogEntry(state, entry) {
+    if (!state.audit_log) {
+        state.audit_log = [];
+    }
+    state.audit_log.push(entry);
+}
+/** 构建委托提示（Phase 2 使用） */
+function buildDelegateHint(stage, actionId, description) {
+    // Phase 1：所有阶段无实际委托
+    // Phase 2 将根据 stage + action 映射到旧工具
+    const workflowIntent = STAGE_WORKFLOW_MAP[stage];
+    if (!workflowIntent)
+        return null;
+    return {
+        tool_name: "sf_stage_execute", // Phase 2: 动态选择
+        args: {
+            workflow_intent: workflowIntent,
+            action: actionId,
+            description: description ?? "",
+        },
+    };
+}
+/** 将 PipelineStageStatus 映射为 sf_next 的 stage_status */
+function mapStageStatus(status) {
+    switch (status) {
+        case "in_progress":
+            return "in_progress";
+        case "completed":
+            return "completed";
+        case "skipped":
+            return "completed";
+        case "pending":
+        default:
+            return "not_started";
+    }
+}
+/** 根据管线状态推断项目阶段 */
+function inferProjectStage(pipeline) {
+    const currentIndex = pipeline.stages.findIndex((s) => s.stage === pipeline.current_stage);
+    const lastStageIndex = pipeline.stages.length - 1;
+    // 最后阶段完成 → 已发布
+    if (currentIndex === lastStageIndex && pipeline.stages[currentIndex].status === "completed") {
+        return "released";
+    }
+    // 在设计阶段（需求分析、现有系统分析、架构设计、详细设计）
+    const designStages = ["需求分析", "现有系统分析", "架构设计", "详细设计"];
+    if (designStages.includes(pipeline.current_stage)) {
+        return "design_in_progress";
+    }
+    // 在实现阶段（任务规划、编码与单元测试、代码审查、联调验证）
+    return "development_in_progress";
+}
+/** 构建可用动作列表 */
+function buildAvailableActions(pipeline) {
+    const actions = [];
+    const currentIndex = pipeline.stages.findIndex((s) => s.stage === pipeline.current_stage);
+    const lastStageIndex = pipeline.stages.length - 1;
+    const currentEntry = pipeline.stages[currentIndex];
+    // 始终可以执行当前阶段
+    if (currentEntry && currentEntry.status === "in_progress") {
+        actions.push({
+            action: "execute",
+            description_zh: `执行当前阶段: ${pipeline.current_stage}`,
+            tool: "sf_stage_execute",
+            params: { stage: pipeline.current_stage },
+        });
+        // 可以检查门禁
+        actions.push({
+            action: "gate_check",
+            description_zh: "运行确定性门禁检查",
+            tool: "sf_gate_check",
+            params: { stage: pipeline.current_stage },
+        });
+    }
+    // 当前阶段完成时可推进
+    if (currentEntry?.status === "completed" && currentIndex < lastStageIndex) {
+        actions.push({
+            action: "advance",
+            description_zh: "推进到下一阶段",
+            tool: "sf_stage_advance",
+        });
+    }
+    // 非首阶段可回退
+    if (currentIndex > 0) {
+        const stageContract = findStageContract(pipeline.current_stage);
+        if (stageContract && stageContract.rollback_targets.length > 0) {
+            actions.push({
+                action: "rollback",
+                description_zh: `回退到: ${stageContract.rollback_targets[0]}`,
+                tool: "sf_stage_rollback",
+                params: { target_stage: stageContract.rollback_targets[0] },
+            });
+        }
+    }
+    // 最后阶段完成 → 建议使用 sf_command
+    if (currentIndex === lastStageIndex && currentEntry?.status === "completed") {
+        actions.push({
+            action: "complete",
+            description_zh: "管线已完成，可以使用 [sf] 状态 查看最终状态",
+            tool: "sf_command",
+            params: { text: "[sf] 状态" },
+        });
+    }
+    return actions;
+}
+/** B8: 任务规划推进一致性校验 */
+function checkTaskPlanningConsistency(state) {
+    // Phase 1: 简化校验 — 检查详细设计阶段有产出
+    const detailDesign = state.stages.find((s) => s.stage === "详细设计");
+    if (detailDesign && detailDesign.status === "completed" && detailDesign.outputs.length === 0) {
+        return { passed: false, details: "详细设计阶段无产出，任务规划无法验证一致性" };
+    }
+    // Phase 1 占位：接口覆盖率、数据表覆盖率、切片独立性检查
+    // Phase 2 将接入真实的切片计划解析
+    return { passed: true };
+}
+/** B12: 崩溃风险评估（现有系统分析阶段） */
+function checkCrashRisk(state) {
+    // Phase 1: 简化检查 — 查看需求分析阶段产出是否包含崩溃关键词
+    const reqAnalysis = state.stages.find((s) => s.stage === "需求分析");
+    if (!reqAnalysis)
+        return false;
+    const crashKeywords = /崩溃|crash|宕机|挂掉|500|503|OOM|内存溢出/i;
+    const hasCrashIndication = reqAnalysis.outputs.some((o) => crashKeywords.test(o));
+    return hasCrashIndication;
+}
+//# sourceMappingURL=pipeline_state_machine.js.map