soloforge 1.1.38 → 1.1.42

package/dist/server/tools/tool_groups/state_machine.js

@@ -1,18 +1,31 @@
 /**
- * 工具组: 状态机驱动路由 — 10 个 MCP 工具。
+ * 工具组: 状态机驱动路由 — MCP 工具集。
  *
  * sf_pipeline_init, sf_stage_execute, sf_stage_advance,
- * sf_stage_rollback, sf_gate_check, sf_command,
+ * sf_stage_rollback, sf_command,
  * sf_next, sf_pipeline_status, sf_direct_answer,
  * sf_single_artifact
  *
- * 双轨并行：与现有工具完全独立，不修改任何现有代码。
+ * 审查统一入口：[sf] 审查 通过 classifyTarget 路由到四层编排。
  */
 import { z } from "zod";
 import { createToolRegistrar } from "../middleware.js";
 import { TOOL } from "../tool_names.js";
 import { PipelineStateMachine } from "../../../engine/pipeline/state_machine/pipeline_state_machine.js";
 import { parseSfCommand } from "../../../engine/pipeline/state_machine/sf_command_parser.js";
+import { TASK_STAGES } from "../../../engine/workflow/workflow_navigation_contract.js";
+import { lazyEvidenceGrounding } from "../lazy_loaders.js"; // evidence_grounding_contract 主链路消费（problem-60）
+import { lazyArchitectureWorkshop } from "../lazy_loaders.js"; // architecture_decision_workshop 主链路消费（架构研讨场景）
+import { lazyDecisionWorkshop } from "../lazy_loaders.js"; // decision_workshop 主链路消费（决策研讨场景）
+/** 运行时校验并转换 stage 参数为 TaskStage 类型 */
+function validateStage(value) {
+    if (!value)
+        return undefined;
+    if (!TASK_STAGES.includes(value)) {
+        throw new Error(`无效的阶段名: ${value}。有效值: ${TASK_STAGES.join(", ")}`);
+    }
+    return value;
+}
 export async function registerStateMachineTools(ctx) {
     const { registerSafeTool } = createToolRegistrar(ctx);
     const { taskContext } = ctx;
@@ -46,18 +59,221 @@ export async function registerStateMachineTools(ctx) {
         action: z.string().optional().describe("阶段内动作 ID。如: start_slice, execute"),
         description: z.string().optional().describe("工作描述（用于知识匹配和风险模式扫描）"),
         task_id: z.string().optional().describe("关联任务 ID（可选）"),
+        architecture_decision_workshop: z.any().optional().describe("已确认的架构决策研讨契约（二次调用传入）"),
+        decision_workshop: z.any().optional().describe("已确认的通用决策研讨契约（二次调用传入）"),
     };
     registerSafeTool(TOOL.stageExecute, "执行当前或指定阶段的工作。运行确定性门禁，注入知识，返回执行结果。阶段推进需调用 sf_stage_advance（通过 sf_command 调用）", StageExecuteSchema, async (args) => {
         try {
+            // 证据接地门禁（problem-60）— 写回失败不影响阻断判定
+            try {
+                const egMod = await lazyEvidenceGrounding();
+                const _evRiskLevel = egMod.assessTaskRisk(undefined, args.stage, args.description);
+                if (_evRiskLevel === "critical" || _evRiskLevel === "high") {
+                    const _evSystem = egMod.createEvidenceGroundingSystem();
+                    const _evMatrix = _evSystem.builder.buildContext([], { target_claims: [], source_types: [], keywords: [], max_results: 0 });
+                    const _evGateResult = _evSystem.gate.evaluate(_evMatrix, _evRiskLevel);
+                    if (!_evGateResult.allowed) {
+                        // 门禁明确拒绝 — 写回失败也不影响阻断判定
+                        try {
+                            const _evPipeline = await sm.getCurrentPipeline();
+                            if (_evPipeline?.pipeline_id) {
+                                await taskContext.setEvidenceGroundingResult(_evPipeline.pipeline_id, {
+                                    evidence_matrix: _evMatrix,
+                                    evidence_gate_result: _evGateResult,
+                                    unsupported_claims: _evGateResult.unsupported_claims,
+                                });
+                            }
+                        }
+                        catch { /* 写回失败不阻断门禁 */ }
+                        return { result: { evidence_blocked: true, _evGate: _evGateResult } };
+                    }
+                }
+            }
+            catch {
+                /* 证据门禁模块加载/运行异常降级，不阻断 */
+            }
             const result = await sm.executeStage({
-                stage: args.stage ?? undefined,
+                stage: validateStage(args.stage),
                 action: args.action,
                 description: args.description,
                 task_id: args.task_id,
                 knowledgeIndex: ctx.knowledgeIndex,
                 config: ctx.config,
             });
-            return { result };
+            // 证据接地运行时写回（problem-60）
+            try {
+                const _evPipeline = await sm.getCurrentPipeline();
+                if (_evPipeline?.pipeline_id) {
+                    await taskContext.setEvidenceGroundingResult(_evPipeline.pipeline_id, {
+                        evidence_gate_result: {
+                            allowed: true,
+                            reason_zh: "证据门禁通过",
+                            diagnostic_code: "SF-EVIDENCE-6000",
+                            unsupported_claims: [],
+                            unresolved_conflicts: [],
+                            missing_evidence: [],
+                            risk_level: "low",
+                            requires_user_confirmation: [],
+                        },
+                    });
+                }
+            }
+            catch {
+                /* 写回失败不阻断主流程 */
+            }
+            // ── 架构决策研讨门禁（architecture_decision_workshop） ──
+            // 从管线描述/任务上下文中检测架构设计意图，创建/评估研讨契约
+            try {
+                const archMod = await lazyArchitectureWorkshop();
+                // 收集所有可用描述文本用于意图匹配（parseSfCommand 会剥离阶段关键词，需从多源拼接）
+                let intentText = args.description ?? "";
+                try {
+                    const pipeline = await sm.getCurrentPipeline();
+                    if (pipeline?.description)
+                        intentText += " " + pipeline.description;
+                }
+                catch { /* 降级 */ }
+                try {
+                    const tCtx = args.task_id ? await taskContext.load(args.task_id) : null;
+                    if (tCtx?.intent)
+                        intentText += " " + tCtx.intent;
+                }
+                catch { /* 降级 */ }
+                if (args.architecture_decision_workshop) {
+                    // 二次调用: 用户确认后传入已确认的研讨契约
+                    const contract = args.architecture_decision_workshop;
+                    const evaluated = archMod.applyArchitectureWorkshopGate(contract);
+                    const gate = archMod.evaluateArchitectureDecisionWorkshop(evaluated);
+                    if (!gate.allowed) {
+                        // 确认后仍未通过门禁 — 阻断
+                        return { result: {
+                                blocked: true,
+                                block_reason: "架构决策研讨门禁未通过，请检查决策项后重试",
+                                architecture_decision_workshop: { ...evaluated, gate_result: gate },
+                            } };
+                    }
+                    // 门禁通过 — 写入已确认结果
+                    result.architecture_decision_workshop = { ...evaluated, status: "confirmed" };
+                }
+                else if (archMod.requiresArchitectureDecisionWorkshop(undefined, intentText)) {
+                    // 首次调用: 创建新的研讨契约 → 阻断等待人类确认
+                    const projectContext = /老系统|存量|改造|现有/.test(intentText) ? "existing_system" : "new_system";
+                    const contract = archMod.createArchitectureDecisionWorkshop(result.pipeline_id ?? args.task_id ?? "unknown", projectContext);
+                    const gate = archMod.evaluateArchitectureDecisionWorkshop(contract);
+                    return { result: {
+                            blocked: true,
+                            block_reason: "架构决策需要人类确认后方可执行",
+                            architecture_decision_workshop: { ...contract, status: "awaiting_confirmation", gate_result: gate },
+                        } };
+                }
+            }
+            catch {
+                /* 架构研讨模块加载失败降级，不阻断 */
+            }
+            // ── 通用决策研讨门禁（decision_workshop + activated_packs） ──
+            // 从管线描述/任务上下文中匹配决策包，创建/评估研讨契约
+            try {
+                const decMod = await lazyDecisionWorkshop();
+                // 收集所有可用描述文本用于决策包匹配
+                let intentText = args.description ?? "";
+                try {
+                    const pipeline = await sm.getCurrentPipeline();
+                    if (pipeline?.description)
+                        intentText += " " + pipeline.description;
+                }
+                catch { /* 降级 */ }
+                try {
+                    const tCtx = args.task_id ? await taskContext.load(args.task_id) : null;
+                    if (tCtx?.intent)
+                        intentText += " " + tCtx.intent;
+                }
+                catch { /* 降级 */ }
+                // 判断架构研讨是否已通过（避免架构研讨已确认后被决策研讨重复阻断）
+                const archWorkshopPassed = args.architecture_decision_workshop &&
+                    result.architecture_decision_workshop?.status === "confirmed";
+                if (args.decision_workshop) {
+                    // 二次调用: 用户确认后传入已确认的研讨契约
+                    const normalized = decMod.normalizeDecisionWorkshopContract(args.decision_workshop);
+                    const evaluated = decMod.applyDecisionWorkshopGate(normalized);
+                    const gate = decMod.evaluateDecisionWorkshop(evaluated);
+                    if (!gate.allowed) {
+                        // 确认后仍未通过门禁 — 阻断
+                        return { result: {
+                                blocked: true,
+                                block_reason: "决策研讨门禁未通过，请检查决策项后重试",
+                                decision_workshop: { ...evaluated, gate_result: gate },
+                                activated_packs: evaluated?.activated_packs ?? [],
+                            } };
+                    }
+                    // 门禁通过 — 写入已确认结果
+                    result.decision_workshop = { ...evaluated, status: "confirmed" };
+                    result.activated_packs = evaluated?.activated_packs ?? [];
+                }
+                else {
+                    // 首次调用: 检测匹配的决策包（排除已通过架构研讨的 architecture 包）
+                    const match = decMod.matchDecisionPacks({ intent: intentText });
+                    const filteredPacks = archWorkshopPassed
+                        ? match.packs.filter((p) => p !== "architecture")
+                        : match.packs;
+                    if (filteredPacks.length > 0) {
+                        const contract = decMod.createDecisionWorkshop(result.pipeline_id ?? args.task_id ?? "unknown", filteredPacks, "new_system", match.reasons.join("; "));
+                        const gate = decMod.evaluateDecisionWorkshop(contract);
+                        // 首次创建的研讨契约 → 阻断等待人类确认
+                        return { result: {
+                                blocked: true,
+                                block_reason: "决策研讨需要人类确认后方可执行",
+                                decision_workshop: { ...contract, status: "awaiting_confirmation", gate_result: gate },
+                                activated_packs: filteredPacks,
+                            } };
+                    }
+                }
+            }
+            catch {
+                /* 决策研讨模块加载失败降级，不阻断 */
+            }
+            // ── 产出物检测（artifact_output） ──
+            // 根据意图关键词在任务上下文中写入 artifact_output，供后续修复指令场景消费
+            try {
+                if (args.task_id) {
+                    const tCtx = await taskContext.load(args.task_id);
+                    const intentStr = String(tCtx?.intent ?? args.description ?? "");
+                    let artifactKind;
+                    let artifactPath;
+                    if (/接口设计|API.*设计|api_spec|接口规格/i.test(intentStr)) {
+                        artifactKind = "api_spec";
+                        artifactPath = "docs/architecture/03-API接口规格文档.md";
+                    }
+                    else if (/架构设计|总体架构/i.test(intentStr)) {
+                        artifactKind = "architecture";
+                        artifactPath = "docs/architecture/01-架构设计文档.md";
+                    }
+                    else if (/数据库设计/i.test(intentStr)) {
+                        artifactKind = "database";
+                        artifactPath = "docs/architecture/02-数据库设计文档.md";
+                    }
+                    if (artifactKind && tCtx && !tCtx.artifact_output) {
+                        const updatedCtx = {
+                            ...tCtx,
+                            artifact_output: { kind: artifactKind, path: artifactPath, status: "draft" },
+                        };
+                        await taskContext.save(updatedCtx);
+                    }
+                }
+            }
+            catch {
+                /* 产出物检测失败不阻断主流程 */
+            }
+            // ── 将 companion_injection 提升为 must_follow + 添加执行指令 ──
+            // 原始返回 `return { result }` 将 companion_injection 埋在 result 中，AI 可忽略。
+            // 改造 8: 与 single_artifact 一致的返回格式，强制 AI 遵守规则。
+            const resultAsRecord = result;
+            const companionInjection = resultAsRecord.companion_injection;
+            const executeStageInstruction = buildExecuteStageInstruction(resultAsRecord);
+            return {
+                result,
+                must_follow: companionInjection || undefined,
+                instruction: executeStageInstruction,
+            };
         }
         catch (err) {
             return { result: { error: String(err.message ?? err) } };
@@ -69,15 +285,83 @@ export async function registerStateMachineTools(ctx) {
     const StageAdvanceSchema = {
         confirmation: z.string().optional().describe("人工确认内容（如: ADR已确认, 测试通过）"),
         task_id: z.string().optional().describe("关联任务 ID（可选）"),
+        confirm: z.boolean().optional().describe("显式确认标志（可选）"),
+        confirmed_by: z.string().optional().describe("确认人（可选）"),
+        confirmation_ref: z.string().optional().describe("确认引用（可选）"),
+        acceptance_notes: z.string().optional().describe("验收备注（可选）"),
+        run_mode: z.string().optional().describe("运行模式（可选）"),
     };
     registerSafeTool(TOOL.stageAdvance, "推进管线到下一阶段。运行门禁检查后推进。最后阶段无法推进（通过 sf_command 调用）", StageAdvanceSchema, async (args) => {
         try {
+            // 修复重验指令阻断 — 产物未通过验证时阻止推进
+            if (args.task_id) {
+                let tCtx;
+                try {
+                    tCtx = await taskContext.load(args.task_id);
+                }
+                catch (err) {
+                    // 任务上下文加载失败时不可跳过重验检查 — 返回错误
+                    return { result: {
+                            error: `任务上下文加载失败，无法验证产物状态: ${err instanceof Error ? err.message : String(err)}`,
+                        } };
+                }
+                if (tCtx?.repair_reverify_directive?.blocked && args.result !== "failure") {
+                    return { result: { diagnostic_code: "SF-CONTRACT-0003", error: "产物未通过验证，请先修复并重验" } };
+                }
+                // failure 标记 — 不推进，仅记录失败状态
+                if (args.result === "failure") {
+                    await taskContext.save({
+                        ...tCtx,
+                        failure_type: args.failure_type ?? "unknown",
+                        failed_at: new Date().toISOString(),
+                    });
+                    return { result: { status: "failure_recorded", failure_type: args.failure_type } };
+                }
+            }
             const result = await sm.advanceStage({
                 confirmation: args.confirmation,
                 task_id: args.task_id,
                 knowledgeIndex: ctx.knowledgeIndex,
                 config: ctx.config,
+                force: args.confirm === true,
             });
+            // 验收参数处理: 检测 confirm/confirmed_by/acceptance_notes 等参数，设置验收状态
+            if (args.confirm && args.confirmed_by) {
+                result.acceptance_status = "passed";
+                result.confirmed_by = args.confirmed_by;
+                result.confirmation_ref = args.confirmation_ref ?? "";
+                result.acceptance_notes = args.acceptance_notes ?? "";
+                // 产物验收 — 检查 artifact_output 状态并标记 accepted
+                try {
+                    if (args.task_id) {
+                        const tCtx = await taskContext.load(args.task_id);
+                        if (tCtx?.artifact_output?.status === "verified") {
+                            result.artifact_transition = "accepted";
+                            await taskContext.save({
+                                ...tCtx,
+                                artifact_output: { ...tCtx.artifact_output, status: "accepted" },
+                            });
+                        }
+                    }
+                }
+                catch { /* 非关键 */ }
+                // 更新 next_allowed_tools 允许再次 advance（多阶段推进场景）
+                try {
+                    if (args.task_id) {
+                        const tCtx = await taskContext.load(args.task_id);
+                        if (tCtx?.last_tool_trace) {
+                            const tools = [...(tCtx.last_tool_trace.next_allowed_tools ?? [])];
+                            if (!tools.includes("sf_stage_advance"))
+                                tools.push("sf_stage_advance");
+                            await taskContext.save({
+                                ...tCtx,
+                                last_tool_trace: { ...tCtx.last_tool_trace, next_allowed_tools: tools },
+                            });
+                        }
+                    }
+                }
+                catch { /* 非关键 */ }
+            }
             return { result };
         }
         catch (err) {
@@ -95,7 +379,7 @@ export async function registerStateMachineTools(ctx) {
     registerSafeTool(TOOL.stageRollback, "回退管线到指定阶段。中间阶段的产出标记为 stale。回退目标必须在该阶段的 rollback_targets 列表中（通过 sf_command 调用）", StageRollbackSchema, async (args) => {
         try {
             const result = await sm.rollbackStage({
-                target_stage: args.target_stage ?? undefined,
+                target_stage: validateStage(args.target_stage),
                 reason: args.reason,
                 task_id: args.task_id,
             });
@@ -106,21 +390,49 @@ export async function registerStateMachineTools(ctx) {
         }
     });
     // ══════════════════════════════════════════════════
-    // sf_gate_check — 门禁检查
+    // sf_record_verification_execution — 记录验证执行结果
     // ══════════════════════════════════════════════════
-    const GateCheckSchema = {
-        stage: z.string().optional().describe("检查的阶段（中文），空=当前阶段"),
-        task_id: z.string().optional().describe("关联任务 ID（可选）"),
+    const RecordVerificationSchema = {
+        task_id: z.string().describe("关联任务 ID"),
+        plan_id: z.string().describe("验证计划 ID"),
+        execution_records: z.array(z.object({
+            command: z.string(),
+            exit_code: z.number(),
+            stdout_hash: z.string().optional(),
+            stderr_hash: z.string().optional(),
+            started_at: z.string().optional(),
+            finished_at: z.string().optional(),
+            evidence_id: z.string().optional(),
+        })).describe("执行记录列表"),
     };
-    registerSafeTool(TOOL.gateCheck, "显式运行三级确定性门禁检查。返回知识覆盖、风险模式、人类确认三个级别的检查结果（通过 sf_command 调用）", GateCheckSchema, async (args) => {
+    registerSafeTool(TOOL.recordVerificationExecution, "记录验证执行结果。将验证计划的执行记录写入任务上下文，供后续验收使用", RecordVerificationSchema, async (args) => {
         try {
-            const result = await sm.checkGate({
-                stage: args.stage ?? undefined,
-                task_id: args.task_id,
-                knowledgeIndex: ctx.knowledgeIndex,
-                config: ctx.config,
-            });
-            return { result };
+            if (!args.task_id) {
+                return { result: { error: "缺少 task_id" } };
+            }
+            const tCtx = await taskContext.load(args.task_id);
+            if (!tCtx) {
+                return { result: { error: `任务上下文不存在: ${args.task_id}` } };
+            }
+            // 写入验证执行记录
+            const updatedCtx = {
+                ...tCtx,
+                verification_execution_records: args.execution_records,
+                verification_execution_plan_id: args.plan_id,
+                verification_execution_status: "completed",
+                verification_execution_at: new Date().toISOString(),
+            };
+            await taskContext.save(updatedCtx);
+            const allPassed = args.execution_records.every((r) => r.exit_code === 0);
+            return {
+                result: {
+                    task_id: args.task_id,
+                    plan_id: args.plan_id,
+                    recorded_count: args.execution_records.length,
+                    all_passed: allPassed,
+                    status: allPassed ? "completed" : "partial_failure",
+                },
+            };
         }
         catch (err) {
             return { result: { error: String(err.message ?? err) } };
@@ -170,6 +482,42 @@ export async function registerStateMachineTools(ctx) {
                         system_type: systemType,
                         description: parsed.description || "未提供描述",
                     });
+                    // 桥接: 为管线创建对应的任务上下文（供 setupPlanGate、injectTechDecision 等依赖 TaskContext 的功能使用）
+                    try {
+                        const rawIntent = args.text || parsed.description || "未提供描述";
+                        // 检测脚手架意图 → 注入 classification 供 sf_scaffold 使用
+                        const isScaffold = /脚手架|scaffold|创建.*模块|生成.*骨架/i.test(rawIntent);
+                        const bridgeCtx = {
+                            task_id: result.pipeline_id,
+                            created_at: new Date().toISOString(),
+                            updated_at: new Date().toISOString(),
+                            // 保留原始命令文本（含完整关键词），供研讨匹配使用
+                            intent: rawIntent,
+                            product_profile: ctx.config?.product_profile ?? "saas",
+                            status: "executing",
+                            // 工作流合同门控: 初始化后允许 sf_stage_execute 等核心工具调用
+                            last_tool_trace: {
+                                tool_name: "sf_command",
+                                next_allowed_tools: [
+                                    "sf_stage_execute", "sf_stage_advance",
+                                    "sf_command", "sf_next", "sf_pipeline_status",
+                                ],
+                                forbidden_tools: [],
+                            },
+                        };
+                        if (isScaffold) {
+                            bridgeCtx.classification = {
+                                task_type: "scaffold",
+                                complexity: "moderate",
+                                risk_level: "low",
+                                domains: ["backend", "frontend"],
+                            };
+                        }
+                        await taskContext.save(bridgeCtx);
+                    }
+                    catch {
+                        /* 桥接创建失败不阻断主流程 */
+                    }
                     return { result: { parsed_command: parsed, execution_result: result, hint } };
                 }
                 case "start": {
@@ -203,13 +551,132 @@ export async function registerStateMachineTools(ctx) {
                     });
                     return { result: { parsed_command: parsed, execution_result: result, hint } };
                 }
-                case "gate_check": {
-                    const result = await sm.checkGate({
-                        stage: parsed.stage,
-                        knowledgeIndex: ctx.knowledgeIndex,
-                        config: ctx.config,
-                    });
-                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                // ── 审查统一入口 — 四层编排驱动（原 gate_check + single_artifact.review 合并） ──
+                case "review": {
+                    const projectPath = ctx.config?._projectPath ?? process.cwd();
+                    // 获取当前管线状态
+                    let reviewSystemType;
+                    let currentReviewStage = "需求分析";
+                    try {
+                        const pipeline = await sm.getCurrentPipeline();
+                        if (pipeline) {
+                            reviewSystemType = pipeline.system_type;
+                            currentReviewStage = pipeline.current_stage;
+                        }
+                    }
+                    catch { /* 无管线时降级 */ }
+                    // 1. 分类目标
+                    const { classifyTarget, TargetClassificationError } = await import("../../../engine/pipeline/target_classifier.js");
+                    let classified;
+                    try {
+                        classified = classifyTarget(parsed.stage || parsed.description, currentReviewStage, projectPath);
+                    }
+                    catch (err) {
+                        if (err instanceof TargetClassificationError) {
+                            return {
+                                result: {
+                                    parsed_command: parsed,
+                                    execution_result: {
+                                        mode: "review",
+                                        status: "error",
+                                        error: err.message,
+                                    },
+                                    hint,
+                                },
+                            };
+                        }
+                        throw err;
+                    }
+                    // 2. 按类型路由到四层编排
+                    if (classified.type === "stage" || classified.type === "current_stage") {
+                        // ── 阶段级审查 ──
+                        const { orchestrateStageReview } = await import("../../../engine/pipeline/orchestrate_single_artifact.js");
+                        const stageResult = await orchestrateStageReview({
+                            stage: classified.stage,
+                            projectPath,
+                            original_command: parsed.raw_text,
+                            systemType: reviewSystemType,
+                        });
+                        return {
+                            result: {
+                                parsed_command: parsed,
+                                execution_result: stageResult,
+                                must_follow: stageResult.injection_text || undefined,
+                                instruction: buildStageReviewInstruction(stageResult, parsed),
+                                hint,
+                            },
+                        };
+                    }
+                    if (classified.type === "artifact") {
+                        // ── 产物级审查 ──
+                        const { orchestrateSingleArtifact } = await import("../../../engine/pipeline/orchestrate_single_artifact.js");
+                        const orchestrateResult = await orchestrateSingleArtifact({
+                            kind: classified.artifactKind,
+                            operation: "review",
+                            projectPath,
+                            original_command: parsed.raw_text,
+                            systemType: reviewSystemType,
+                        });
+                        return {
+                            result: {
+                                parsed_command: parsed,
+                                execution_result: orchestrateResult,
+                                must_follow: orchestrateResult.injection_text || undefined,
+                                instruction: buildTopLevelInstruction(orchestrateResult, parsed),
+                                hint,
+                            },
+                        };
+                    }
+                    if (classified.type === "slice") {
+                        // ── 切片级审查 — 编码阶段 gate + 限定文件范围 ──
+                        const { orchestrateSingleArtifact } = await import("../../../engine/pipeline/orchestrate_single_artifact.js");
+                        const orchestrateResult = await orchestrateSingleArtifact({
+                            kind: "source_code_package",
+                            operation: "review",
+                            projectPath,
+                            original_command: parsed.raw_text,
+                            systemType: reviewSystemType,
+                        });
+                        // 追加切片文件范围限定
+                        const injectionParts = [];
+                        if (orchestrateResult.injection_text) {
+                            injectionParts.push(orchestrateResult.injection_text);
+                        }
+                        if (classified.files && classified.files.length > 0) {
+                            injectionParts.push([
+                                ``,
+                                `## 切片审查范围限定`,
+                                ``,
+                                `审查仅限以下文件：`,
+                                ...classified.files.map(f => `- \`${f}\``),
+                                ``,
+                                `忽略此范围外的文件变更。`,
+                            ].join("\n"));
+                        }
+                        else {
+                            injectionParts.push([
+                                ``,
+                                `## 切片审查范围`,
+                                ``,
+                                `⚠️ 未找到切片 ${classified.sliceId} 的文件列表。请检查 .soloforge/output/slice_plan.yaml 是否存在。`,
+                            ].join("\n"));
+                        }
+                        return {
+                            result: {
+                                parsed_command: parsed,
+                                execution_result: {
+                                    ...orchestrateResult,
+                                    slice_id: classified.sliceId,
+                                    slice_files: classified.files,
+                                },
+                                must_follow: injectionParts.join("\n") || undefined,
+                                instruction: buildTopLevelInstruction(orchestrateResult, parsed),
+                                hint,
+                            },
+                        };
+                    }
+                    // 兜底（不应到达）
+                    return { result: { parsed_command: parsed, execution_result: { error: "未知的审查目标类型" }, hint } };
                 }
                 case "status": {
                     const pipeline = await sm.getCurrentPipeline();
@@ -275,19 +742,6 @@ export async function registerStateMachineTools(ctx) {
                     });
                     return { result: { parsed_command: parsed, execution_result: result, hint } };
                 }
-                case "brainstorm":
-                case "first_principles": {
-                    return {
-                        result: {
-                            parsed_command: parsed,
-                            execution_result: {
-                                message: `Phase 2 功能：${parsed.verb} 将在确定性门禁第二级自动触发`,
-                                topic: parsed.description,
-                            },
-                            hint,
-                        },
-                    };
-                }
                 // D13: 快捷路径
                 case "direct_answer": {
                     return {
@@ -303,14 +757,51 @@ export async function registerStateMachineTools(ctx) {
                     };
                 }
                 case "single_artifact": {
+                    // ── 委托共享内核 — 按方案四层编排 ──
+                    const projectPath = ctx.config?._projectPath ?? process.cwd();
+                    // ── 获取当前管线 system_type（用于老系统产物过滤） ──
+                    let currentSystemType;
+                    try {
+                        const pipeline = await sm.getCurrentPipeline();
+                        if (pipeline)
+                            currentSystemType = pipeline.system_type;
+                    }
+                    catch { /* 无管线时降级 */ }
+                    // ── 单产物路径（原有逻辑不变） ──
+                    // 从描述匹配 artifact kind（优先 description，回退 raw_text + stage）
+                    const { inferArtifactKindFromDescription } = await import("../../../engine/pipeline/artifact_resolver.js");
+                    const kind = inferArtifactKindFromDescription(parsed.description)
+                        || inferArtifactKindFromDescription(parsed.raw_text)
+                        || (parsed.stage ? inferArtifactKindFromDescription(parsed.stage) : undefined);
+                    if (!kind) {
+                        return {
+                            result: {
+                                parsed_command: parsed,
+                                execution_result: {
+                                    mode: "single_artifact",
+                                    status: "error",
+                                    error: `无法识别产物: "${parsed.description}"。可用的产物类型：原型说明、架构设计、详细设计、接口设计、数据库设计等`,
+                                },
+                                hint,
+                            },
+                        };
+                    }
+                    // 委托共享内核完成四层编排
+                    const { orchestrateSingleArtifact } = await import("../../../engine/pipeline/orchestrate_single_artifact.js");
+                    const orchestrateResult = await orchestrateSingleArtifact({
+                        kind,
+                        operation: parsed.operation ?? "review",
+                        projectPath,
+                        original_command: parsed.raw_text,
+                        systemType: currentSystemType,
+                    });
                     return {
                         result: {
                             parsed_command: parsed,
-                            execution_result: {
-                                mode: "single_artifact",
-                                message: parsed.description || "单产物快速生成",
-                                note: "单产物快速生成，适用于简单文档/配置文件",
-                            },
+                            execution_result: orchestrateResult,
+                            // 将 injection_text 提升到顶层，确保 AI 将其作为必须执行的指令而非参考数据
+                            must_follow: orchestrateResult.injection_text || undefined,
+                            instruction: buildTopLevelInstruction(orchestrateResult, parsed),
                             hint,
                         },
                     };
@@ -321,7 +812,7 @@ export async function registerStateMachineTools(ctx) {
                             parsed_command: parsed,
                             execution_result: {
                                 error: `无法识别的命令: "${args.text}"`,
-                                available_verbs: ["开始", "推进", "回退", "检查", "状态", "初始化", "头脑风暴", "第一性原理", "诊断", "修复", "跳转", "重置", "归档"],
+                                available_verbs: ["开始", "审查", "推进", "回退", "状态", "初始化", "诊断", "修复"],
                             },
                         },
                     };
@@ -392,25 +883,55 @@ export async function registerStateMachineTools(ctx) {
         }
     });
     // ══════════════════════════════════════════════════
-    // sf_single_artifact — 快捷路径：单产物快速生成
+    // sf_single_artifact — 场景 B：结构化参数快捷入口
     // ══════════════════════════════════════════════════
     const SingleArtifactSchema = {
-        artifact_kind: z.string().max(100).describe("产物类型：如 doc、config、script、test、migration 等"),
-        intent: z.string().max(10_000).describe("产物意图描述：说明要生成什么内容、目标是什么"),
-        scope: z.array(z.string()).max(20).optional().describe("影响范围：涉及的文件或模块路径列表，用于限定产物边界"),
+        artifact_kind: z.string().max(100).describe("产物类型（ArtifactKind）：如 prototype_spec, design_doc, api_spec, detailed_design 等"),
+        operation: z.enum(["extract", "review", "fix", "iterate"]).optional().describe("操作类型：extract=生成, review=审查, fix=修改, iterate=迭代。默认 extract"),
+        intent: z.string().max(10_000).optional().describe("操作意图描述（可选）"),
     };
-    registerSafeTool(TOOL.singleArtifact, "快捷路径：单产物快速生成。适用于简单文档、配置文件、脚本、测试等单一产出场景。跳过完整管线的阶段流转，直接执行并返回产物。生成后建议调用 sf_gate_check 进行质量验证", SingleArtifactSchema, async (args) => {
+    registerSafeTool(TOOL.singleArtifact, "场景 B 快捷入口：单产物四层编排。传入 artifact_kind 和 operation，委托共享内核完成模板→引擎→规则→门禁编排", SingleArtifactSchema, async (args) => {
         try {
-            // 快捷路径：不经过管线阶段流转，直接标记单产物生成模式
-            // 实际产物由 AI 模型在工具调用后生成，工具本身标记模式和边界
+            const projectPath = ctx.projectPath ?? process.cwd();
+            // 获取当前管线 system_type
+            let singleSystemType;
+            try {
+                const pipeline = await sm.getCurrentPipeline();
+                if (pipeline)
+                    singleSystemType = pipeline.system_type;
+            }
+            catch { /* 无管线时降级 */ }
+            const { orchestrateSingleArtifact } = await import("../../../engine/pipeline/orchestrate_single_artifact.js");
+            const { inferArtifactKindFromDescription, hasArtifactAlias } = await import("../../../engine/pipeline/artifact_resolver.js");
+            // 解析 kind：优先直接匹配，否则从描述推断
+            let kind = args.artifact_kind;
+            if (kind && !hasArtifactAlias(kind)) {
+                kind = inferArtifactKindFromDescription(args.artifact_kind) ?? undefined;
+            }
+            if (!kind) {
+                return {
+                    result: {
+                        mode: "single_artifact",
+                        status: "error",
+                        error: `无法识别产物类型: "${args.artifact_kind}"`,
+                    },
+                };
+            }
+            // 委托共享内核
+            const orchestrateResult = await orchestrateSingleArtifact({
+                kind: kind,
+                operation: args.operation ?? "extract",
+                projectPath,
+                original_command: args.intent,
+                systemType: singleSystemType,
+            });
             return {
                 result: {
-                    mode: "single_artifact",
-                    artifact_kind: args.artifact_kind,
+                    execution_result: orchestrateResult,
+                    // 与场景 A 保持一致：将 injection_text 提升为必须执行的指令
+                    must_follow: orchestrateResult.injection_text || undefined,
+                    instruction: buildTopLevelInstruction(orchestrateResult, { operation: args.operation ?? "extract", raw_text: args.intent }),
                     intent: args.intent,
-                    scope: args.scope ?? [],
-                    note: "单产物快速生成模式：跳过管线阶段流转",
-                    suggestion: "生成完成后建议调用 sf_gate_check 进行质量验证",
                 },
             };
         }
@@ -418,5 +939,240 @@ export async function registerStateMachineTools(ctx) {
             return { result: { error: String(err.message ?? err) } };
         }
     });
+    // ══════════════════════════════════════════════════
+    // sf_config_update — 配置更新
+    // ══════════════════════════════════════════════════
+    const ConfigUpdateSchema = {
+        updates: z.record(z.unknown()).describe("要更新的字段键值对。支持 dot-path（如 {\"delivery.auto_push\": true}）"),
+        reason: z.string().max(500).optional().describe("更新原因（审计日志）"),
+    };
+    registerSafeTool(TOOL.configUpdate, "更新 intent.yaml 配置字段。AI 写入项目意图声明的唯一入口。支持 dot-path 设置。自动校验 + 写入后验证配置完整性", ConfigUpdateSchema, async (args) => {
+        try {
+            const { loadIntent, saveIntent } = await import("../../../engine/config/intent.js");
+            const { validateForWrite } = await import("../../../engine/config/intent_schema.js");
+            const { resolveConfig, checkConfigReadiness } = await import("../../../engine/config/resolver.js");
+            const { debug } = await import("../../../engine/core/logger.js");
+            const projectRoot = ctx.projectPath;
+            if (!projectRoot) {
+                return { result: { error: "无法确定项目根目录" } };
+            }
+            debug("配置更新", "sf_config_update 调用", args.updates);
+            // 1. 加载当前 intent
+            const current = await loadIntent(projectRoot);
+            // 2. 安全守卫：禁止写入内部字段（必须在 applyDotPathUpdates 之前检查）
+            for (const key of Object.keys(args.updates)) {
+                if (key.startsWith("_")) {
+                    return { result: { error: `禁止写入内部字段: ${key}` } };
+                }
+            }
+            // 3. 应用 updates（支持 dot-path）
+            const updated = applyDotPathUpdates(current, args.updates);
+            // 4. 补充 product_profile（首次写入可能没有）
+            if (!updated.product_profile) {
+                updated.product_profile = "default";
+            }
+            // 5. 严格校验
+            const validation = validateForWrite(updated);
+            if (!validation.success) {
+                const issues = validation.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+                return { result: { error: `校验失败: ${issues}` } };
+            }
+            // 6. 写入
+            await saveIntent(projectRoot, validation.data);
+            // 7. 重新解析验证配置完整性
+            const newConfig = await resolveConfig(projectRoot);
+            const readiness = checkConfigReadiness(newConfig);
+            return {
+                result: {
+                    status: "ok",
+                    updated_fields: Object.keys(args.updates),
+                    reason: args.reason,
+                    config_readiness: readiness,
+                    hint: readiness.ready
+                        ? "配置完整"
+                        : `配置仍缺少: ${readiness.missing.join(", ")}。请继续通过 sf_config_update 补充。`,
+                },
+            };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+}
+// ── 辅助函数 ──
+/**
+ * 为单产物编排结果生成顶层指令。
+ *
+ * 将四层编排的 injection_text 从"参考数据"提升为"必须执行的指令"，
+ * 确保 AI 不会在审查后停下来，而是自动执行 修复→重审→直到通过 的循环。
+ *
+ * @visibleForTesting — 仅用于防回归测试导出，不供外部消费者使用。
+ */
+export function buildTopLevelInstruction(result, parsed) {
+    const status = result.status;
+    const targetName = result.target_name;
+    const targetPaths = result.target_paths;
+    // 非 ready 状态 — 给出明确动作指引
+    if (status === "missing_upstream") {
+        const suggestedAction = result.suggested_action;
+        const originalTask = result.original_task;
+        return [
+            `⚠️ 上游产物缺失，无法直接执行当前操作。`,
+            ``,
+            suggestedAction?.produce_first ?? `请先产出缺失的上游产物。`,
+            suggestedAction?.then_resume ?? `上游就绪后重新执行。`,
+            originalTask?.command ? `\n原任务命令: ${originalTask.command}` : "",
+        ].filter(Boolean).join("\n");
+    }
+    if (status === "error" || status === "no_template") {
+        return `❌ 编排失败: ${result.error ?? "未知错误"}`;
+    }
+    // ready 状态 — 构建明确执行指令
+    const operation = result.operation ?? parsed.operation ?? "review";
+    const pathList = targetPaths?.length ? targetPaths.join("、") : "产物文件";
+    if (operation === "extract") {
+        return [
+            `📋 你现在必须执行「${targetName}」的创建。禁止产出空洞内容。`,
+            ``,
+            `执行步骤（不可跳过、不可简化）：`,
+            `1. 阅读 execution_result.injection_text 中的规则和门禁（含万物执行基线）`,
+            `2. 参考模板结构（template_body），每个章节必须填写完整内容`,
+            `3. 结合上游产物内容（upstream_inputs），穷尽所有实体/流程/字段`,
+            `4. 产出完整产物并写入: ${pathList}`,
+            `5. 产出后执行完整性自检：逐条核对门禁，引用产物原文作为证据`,
+            `6. 任何门禁无证据 → 立即补充内容，不要停下来`,
+            ``,
+            `⚠️ 绝对不允许留空章节、使用占位符、或以「上游未提供」为由省略内容。`,
+            `⚠️ 绝对不允许跳过完整性自检。`,
+        ].join("\n");
+    }
+    // review / fix / iterate — 对抗性审查-修复协议（强制）
+    return [
+        `🔥 你是严格的质量审查员。你的职责是发现问题，不是放行。`,
+        ``,
+        `必须严格遵守 execution_result.must_follow 中的全部规则（含万物执行基线 + 对抗性审查协议）。`,
+        ``,
+        `执行步骤（不可跳过、不可简化）：`,
+        `1. 逐条读取门禁检查项，对每条引用产物原文作为证据`,
+        `2. 无证据的 ✅ 等同于 ❌ — 你必须引用章节名或行号`,
+        `3. 对每一个 ❌/⚠️ 项：立即修复，不允许停下来问用户`,
+        `4. 修复后重写完整产物到: ${pathList}`,
+        `5. 修复完成后，必须调用 [sf] 审查 进行独立重审`,
+        `6. 如果重审仍有问题 → 继续修复（最多 5 轮）`,
+        ``,
+        `⚠️ 绝对不允许只输出审查报告就停下来。`,
+        `⚠️ 绝对不允许无证据地批量标记 ✅。`,
+        `⚠️ 独立重审是强制步骤，不是可选建议。`,
+    ].join("\n");
+}
+/**
+ * 为阶段级审查生成顶层指令。
+ *
+ * 告诉 AI 必须审查该阶段全部产出，发现问题后逐个修复，直到全部通过。
+ *
+ * @visibleForTesting — 仅用于防回归测试导出，不供外部消费者使用。
+ */
+export function buildStageReviewInstruction(result, parsed) {
+    const status = result.status;
+    const stage = result.stage ?? parsed.stage ?? "未知阶段";
+    if (status === "no_artifacts" || status === "error") {
+        return `❌ 阶段「${stage}」没有可审查的产物: ${result.error ?? "未知错误"}`;
+    }
+    const artifactResults = result.artifact_results;
+    const readyCount = artifactResults?.filter((r) => r.status === "ready").length ?? 0;
+    const partialCount = artifactResults?.filter((r) => r.status !== "ready").length ?? 0;
+    return [
+        `🔥 你是严格的质量审查员。你的职责是发现问题，不是放行。`,
+        ``,
+        `阶段共 ${readyCount} 个产物需要审查${partialCount > 0 ? `，${partialCount} 个产物因缺失上游被跳过` : ""}。`,
+        ``,
+        `必须严格遵守 execution_result.must_follow 中的全部规则（含万物执行基线 + 对抗性审查协议）。`,
+        ``,
+        `审查原则（违反任何一条等同审查失败）：`,
+        `1. 默认立场：每一条门禁检查项都是 ❌，除非你能引用产物中的具体内容作为证据`,
+        `2. 无证据的 ✅ 等同于 ❌ — 你必须引用章节名或行号 + 原文`,
+        `3. 禁止批量标记 ✅ — 每条必须独立检查并附证据`,
+        `4. 禁止跳过任何检查项`,
+        ``,
+        `执行步骤（不可跳过、不可简化）：`,
+        `1. 逐个审查阶段内的所有产物，对每条门禁引用产物原文作为证据`,
+        `2. 检查跨产物一致性（术语、引用、覆盖、冲突），引用两个产物中的对应内容`,
+        `3. 对每一个 ❌/⚠️ 项：立即修复，不允许停下来问用户`,
+        `4. 修复后重写完整产物到对应文件`,
+        `5. 修复完成后，必须调用 [sf] 审查 ${stage} 进行独立重审`,
+        `6. 如果重审仍有问题 → 继续修复（最多 5 轮）`,
+        ``,
+        `⚠️ 绝对不允许只输出审查报告就停下来。`,
+        `⚠️ 绝对不允许无证据地批量标记 ✅。`,
+        `⚠️ 独立重审是强制步骤，不是可选建议。`,
+    ].join("\n");
+}
+/**
+ * 为 execute-stage 结果生成执行指令。
+ *
+ * 将 companion_injection 中的规则/门禁从"参考数据"提升为"必须执行"，
+ * 并将 trigger 信号（头脑风暴/第一性原理/抽象模型）转化为 AI 指令。
+ */
+export function buildExecuteStageInstruction(result) {
+    const stage = result.stage ?? "当前阶段";
+    const lines = [];
+    lines.push(`🔧 你现在必须执行「${stage}」阶段的工作。`);
+    lines.push("");
+    lines.push("必须严格遵守以下规则和门禁（含万物执行基线）：");
+    lines.push("");
+    // 头脑风暴触发
+    const bsTrigger = result.brainstorm_trigger;
+    if (bsTrigger) {
+        lines.push("⚠️ **风险检测触发头脑风暴（强制）**");
+        lines.push(`原因: ${bsTrigger.reason}`);
+        lines.push(`要求: ${bsTrigger.suggestion}`);
+        lines.push("在执行阶段工作前，你必须先完成头脑风暴方案探索。");
+        lines.push("");
+    }
+    // 第一性原理触发
+    const fpTrigger = result.first_principles_trigger;
+    if (fpTrigger) {
+        lines.push("⚠️ **FP 规则触发第一性原理推理（强制）**");
+        lines.push(`原因: ${fpTrigger.reason}`);
+        lines.push(`要求: ${fpTrigger.suggestion}`);
+        lines.push("在执行阶段工作前，你必须先从第一性原理重新审视决策。");
+        lines.push("");
+    }
+    // 抽象模型触发
+    const amTrigger = result.abstract_model_trigger;
+    if (amTrigger) {
+        lines.push("⚠️ **抽象缺失触发抽象建模（强制）**");
+        lines.push(`原因: ${amTrigger.reason}`);
+        lines.push(`要求: ${amTrigger.suggestion}`);
+        lines.push("在执行阶段工作前，你必须先对核心概念进行抽象建模：识别领域实体、提取通用模式、建立概念关系。");
+        lines.push("");
+    }
+    lines.push("执行纪律（不可违反）：");
+    lines.push("1. 先读 must_follow 中的全部规则，理解每条规则的约束");
+    lines.push("2. 执行阶段工作时，每一步都必须符合规则要求");
+    lines.push("3. 如果规则要求提供证据 — 必须引用你产出的具体内容");
+    lines.push("4. 如果门禁检查有 ❌ 项 — 立即修复，不允许跳过");
+    lines.push("5. 不可以「简化」或「跳过」任何规则要求的步骤");
+    lines.push("");
+    lines.push("⚠️ 绝对不允许忽略 must_follow 中的任何规则。");
+    lines.push("⚠️ 绝对不允许产出不完整的阶段交付物。");
+    return lines.join("\n");
+}
+/** 应用 dot-path updates 到对象 */
+function applyDotPathUpdates(target, updates) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(updates)) {
+        const parts = key.split(".");
+        let obj = result;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i];
+            if (!(part in obj) || typeof obj[part] !== "object" || obj[part] === null) {
+                obj[part] = {};
+            }
+            obj = obj[part];
+        }
+        obj[parts[parts.length - 1]] = value;
+    }
+    return result;
 }
 //# sourceMappingURL=state_machine.js.map