soloforge 1.1.40 → 1.1.42

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

@@ -1,16 +1,14 @@
 /**
- * 工具组: 状态机驱动路由 — 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 fss from "node:fs";
-import path from "node:path";
 import { createToolRegistrar } from "../middleware.js";
 import { TOOL } from "../tool_names.js";
 import { PipelineStateMachine } from "../../../engine/pipeline/state_machine/pipeline_state_machine.js";
@@ -19,7 +17,6 @@ import { TASK_STAGES } from "../../../engine/workflow/workflow_navigation_contra
 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 主链路消费（决策研讨场景）
-import { lazyDesignArtifactPack } from "../lazy_loaders.js"; // design_artifact_pack 主链路消费（设计产物包场景）
 /** 运行时校验并转换 stage 参数为 TaskStage 类型 */
 function validateStage(value) {
     if (!value)
@@ -67,7 +64,7 @@ export async function registerStateMachineTools(ctx) {
     };
     registerSafeTool(TOOL.stageExecute, "执行当前或指定阶段的工作。运行确定性门禁，注入知识，返回执行结果。阶段推进需调用 sf_stage_advance（通过 sf_command 调用）", StageExecuteSchema, async (args) => {
         try {
-            // 证据接地门禁（problem-60）
+            // 证据接地门禁（problem-60）— 写回失败不影响阻断判定
             try {
                 const egMod = await lazyEvidenceGrounding();
                 const _evRiskLevel = egMod.assessTaskRisk(undefined, args.stage, args.description);
@@ -75,22 +72,25 @@ export async function registerStateMachineTools(ctx) {
                     const _evSystem = egMod.createEvidenceGroundingSystem();
                     const _evMatrix = _evSystem.builder.buildContext([], { target_claims: [], source_types: [], keywords: [], max_results: 0 });
                     const _evGateResult = _evSystem.gate.evaluate(_evMatrix, _evRiskLevel);
-                    const _evGate = _evGateResult;
-                    if (!_evGate.allowed) {
-                        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,
-                            });
+                    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,
+                                });
+                            }
                         }
-                        return { result: { evidence_blocked: true, _evGate } };
+                        catch { /* 写回失败不阻断门禁 */ }
+                        return { result: { evidence_blocked: true, _evGate: _evGateResult } };
                     }
                 }
             }
             catch {
-                /* 证据门禁失败不阻断主流程 */
+                /* 证据门禁模块加载/运行异常降级，不阻断 */
             }
             const result = await sm.executeStage({
                 stage: validateStage(args.stage),
@@ -121,7 +121,7 @@ export async function registerStateMachineTools(ctx) {
             catch {
                 /* 写回失败不阻断主流程 */
             }
-            // ── 架构决策研讨富化（architecture_decision_workshop） ──
+            // ── 架构决策研讨门禁（architecture_decision_workshop） ──
             // 从管线描述/任务上下文中检测架构设计意图，创建/评估研讨契约
             try {
                 const archMod = await lazyArchitectureWorkshop();
@@ -143,27 +143,34 @@ export async function registerStateMachineTools(ctx) {
                     // 二次调用: 用户确认后传入已确认的研讨契约
                     const contract = args.architecture_decision_workshop;
                     const evaluated = archMod.applyArchitectureWorkshopGate(contract);
-                    result.architecture_decision_workshop = evaluated;
                     const gate = archMod.evaluateArchitectureDecisionWorkshop(evaluated);
                     if (!gate.allowed) {
-                        result.status = "awaiting_confirmation";
+                        // 确认后仍未通过门禁 — 阻断
+                        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)) {
-                    // 首次调用: 创建新的研讨契约（6 域未确认 → awaiting_confirmation）
+                    // 首次调用: 创建新的研讨契约 → 阻断等待人类确认
                     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);
-                    result.architecture_decision_workshop = contract;
-                    if (!gate.allowed) {
-                        result.status = "awaiting_confirmation";
-                    }
+                    return { result: {
+                            blocked: true,
+                            block_reason: "架构决策需要人类确认后方可执行",
+                            architecture_decision_workshop: { ...contract, status: "awaiting_confirmation", gate_result: gate },
+                        } };
                 }
             }
             catch {
-                /* 架构研讨富化失败不阻断主流程 */
+                /* 架构研讨模块加载失败降级，不阻断 */
             }
-            // ── 通用决策研讨富化（decision_workshop + activated_packs） ──
+            // ── 通用决策研讨门禁（decision_workshop + activated_packs） ──
             // 从管线描述/任务上下文中匹配决策包，创建/评估研讨契约
             try {
                 const decMod = await lazyDecisionWorkshop();
@@ -188,12 +195,19 @@ export async function registerStateMachineTools(ctx) {
                     // 二次调用: 用户确认后传入已确认的研讨契约
                     const normalized = decMod.normalizeDecisionWorkshopContract(args.decision_workshop);
                     const evaluated = decMod.applyDecisionWorkshopGate(normalized);
-                    result.decision_workshop = evaluated;
-                    result.activated_packs = evaluated?.activated_packs ?? [];
                     const gate = decMod.evaluateDecisionWorkshop(evaluated);
                     if (!gate.allowed) {
-                        result.status = "awaiting_confirmation";
+                        // 确认后仍未通过门禁 — 阻断
+                        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 包）
@@ -204,16 +218,18 @@ export async function registerStateMachineTools(ctx) {
                     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);
-                        result.decision_workshop = contract;
-                        result.activated_packs = filteredPacks;
-                        if (!gate.allowed) {
-                            result.status = "awaiting_confirmation";
-                        }
+                        // 首次创建的研讨契约 → 阻断等待人类确认
+                        return { result: {
+                                blocked: true,
+                                block_reason: "决策研讨需要人类确认后方可执行",
+                                decision_workshop: { ...contract, status: "awaiting_confirmation", gate_result: gate },
+                                activated_packs: filteredPacks,
+                            } };
                     }
                 }
             }
             catch {
-                /* 决策研讨富化失败不阻断主流程 */
+                /* 决策研讨模块加载失败降级，不阻断 */
             }
             // ── 产出物检测（artifact_output） ──
             // 根据意图关键词在任务上下文中写入 artifact_output，供后续修复指令场景消费
@@ -247,7 +263,17 @@ export async function registerStateMachineTools(ctx) {
             catch {
                 /* 产出物检测失败不阻断主流程 */
             }
-            return { result };
+            // ── 将 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) } };
@@ -269,22 +295,28 @@ export async function registerStateMachineTools(ctx) {
         try {
             // 修复重验指令阻断 — 产物未通过验证时阻止推进
             if (args.task_id) {
+                let tCtx;
                 try {
-                    const tCtx = await taskContext.load(args.task_id);
-                    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 } };
-                    }
+                    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 } };
                 }
-                catch { /* 非关键 */ }
             }
             const result = await sm.advanceStage({
                 confirmation: args.confirmation,
@@ -358,101 +390,6 @@ export async function registerStateMachineTools(ctx) {
         }
     });
     // ══════════════════════════════════════════════════
-    // sf_gate_check — 门禁检查
-    // ══════════════════════════════════════════════════
-    const GateCheckSchema = {
-        stage: z.string().optional().describe("检查的阶段（中文），空=当前阶段"),
-        task_id: z.string().optional().describe("关联任务 ID（可选）"),
-        changed_files: z.array(z.string()).optional().describe("变更文件列表（可选）"),
-        confirm: z.boolean().optional().describe("是否确认（可选）"),
-    };
-    registerSafeTool(TOOL.gateCheck, "显式运行三级确定性门禁检查。返回知识覆盖、风险模式、人类确认三个级别的检查结果（通过 sf_command 调用）", GateCheckSchema, async (args) => {
-        try {
-            const result = await sm.checkGate({
-                stage: validateStage(args.stage),
-                task_id: args.task_id,
-                knowledgeIndex: ctx.knowledgeIndex,
-                config: ctx.config,
-            });
-            // 产物内容验证 — 检测 draft/非合规产物，创建修复重验指令
-            try {
-                if (args.task_id) {
-                    const tCtx = await taskContext.load(args.task_id);
-                    if (tCtx?.artifact_output) {
-                        const projectPath = ctx.config?._projectPath ?? process.cwd();
-                        const artifactAbs = path.join(projectPath, tCtx.artifact_output.path);
-                        if (fss.existsSync(artifactAbs)) {
-                            const content = fss.readFileSync(artifactAbs, "utf-8");
-                            if (content.trimStart().startsWith("draft")) {
-                                result.diagnostic_code = "SF-CONTRACT-DRAFT";
-                                await taskContext.save({
-                                    ...tCtx,
-                                    repair_reverify_directive: {
-                                        blocked: true,
-                                        reason: "产物包含 draft 标记，需修复后重验",
-                                        artifact_path: tCtx.artifact_output.path,
-                                        original_diagnostic: "SF-CONTRACT-DRAFT",
-                                    },
-                                });
-                            }
-                            else if (tCtx.repair_reverify_directive?.blocked) {
-                                // 产物合规且之前有阻断指令 → 清除指令，标记 verified
-                                await taskContext.save({
-                                    ...tCtx,
-                                    artifact_output: { ...tCtx.artifact_output, status: "verified" },
-                                    repair_reverify_directive: undefined,
-                                });
-                            }
-                        }
-                    }
-                }
-            }
-            catch {
-                /* 产物内容验证失败不阻断主流程 */
-            }
-            // 设计产物包验证 — 扫描项目设计文档，返回 findings 和 diagnostic_code
-            try {
-                const designMod = await lazyDesignArtifactPack();
-                const projectPath = ctx.config?._projectPath ?? process.cwd();
-                const pack = designMod.createDesignArtifactPack(args.task_id ?? "gate-check", designMod.defaultDesignArtifactPaths());
-                const verifyResult = designMod.verifyDesignArtifactPack(projectPath, pack);
-                result.design_artifact_findings = verifyResult.findings;
-                if (!verifyResult.passed && !result.diagnostic_code) {
-                    result.diagnostic_code = "SF-DESIGN-PACK-VERIFY-FAILED";
-                }
-            }
-            catch {
-                /* 设计产物包验证失败不阻断主流程 */
-            }
-            // 确认时写入验证计划（供 sf_record_verification_execution 消费）
-            if (args.confirm && args.task_id) {
-                try {
-                    const tCtx = await taskContext.load(args.task_id);
-                    if (tCtx && !tCtx.verification_plan) {
-                        const planId = `vp-${args.task_id}-${Date.now()}`;
-                        const updatedCtx = {
-                            ...tCtx,
-                            verification_plan: {
-                                plan_id: planId,
-                                commands: ["npm test", "npm run lint", "npm run build"],
-                                created_at: new Date().toISOString(),
-                            },
-                        };
-                        await taskContext.save(updatedCtx);
-                        result.verification_plan_id = planId;
-                    }
-                }
-                catch {
-                    /* 验证计划写入失败不阻断主流程 */
-                }
-            }
-            return { result };
-        }
-        catch (err) {
-            return { result: { error: String(err.message ?? err) } };
-        }
-    });
-    // ══════════════════════════════════════════════════
     // sf_record_verification_execution — 记录验证执行结果
     // ══════════════════════════════════════════════════
     const RecordVerificationSchema = {
@@ -562,7 +499,7 @@ export async function registerStateMachineTools(ctx) {
                             last_tool_trace: {
                                 tool_name: "sf_command",
                                 next_allowed_tools: [
-                                    "sf_stage_execute", "sf_stage_advance", "sf_gate_check",
+                                    "sf_stage_execute", "sf_stage_advance",
                                     "sf_command", "sf_next", "sf_pipeline_status",
                                 ],
                                 forbidden_tools: [],
@@ -614,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();
@@ -686,69 +742,6 @@ export async function registerStateMachineTools(ctx) {
                     });
                     return { result: { parsed_command: parsed, execution_result: result, hint } };
                 }
-                case "brainstorm": {
-                    return {
-                        result: {
-                            parsed_command: parsed,
-                            execution_result: {
-                                message: "头脑风暴流程已激活",
-                                topic: parsed.description,
-                                procedure_ref: "templates/procedures/不确定时头脑风暴流程.md",
-                                steps: [
-                                    "1. 明确不确定的核心问题",
-                                    "2. 列出所有可能方案（至少 3 个）",
-                                    "3. 对照第一性原理推理规则（FP-01~04）逐条检查",
-                                    "4. 评估各方案的风险与收益",
-                                    "5. 选择最符合 fundamental_need 的方案",
-                                    "6. 记录决策理由与推理链",
-                                ],
-                                fp_rules_ref: "templates/rules/shared/第一性原理推理规则.md",
-                                note: "确定性门禁检测到风险模式时也会自动触发头脑风暴",
-                            },
-                            hint,
-                        },
-                    };
-                }
-                case "first_principles": {
-                    return {
-                        result: {
-                            parsed_command: parsed,
-                            execution_result: {
-                                message: "第一性原理推理已激活",
-                                topic: parsed.description,
-                                rules_ref: "templates/rules/shared/第一性原理推理规则.md",
-                                checklist: [
-                                    "FP-01 [error]: fundamental_need 是否已声明？用户目标 vs 解决方案",
-                                    "FP-02 [error]: 推理链是否完整？每个前提是否有证据支撑",
-                                    "FP-03 [warning]: 是否为表面修复？根因分析是否到位",
-                                    "FP-04 [warning]: 是否仅关键词替换？实质问题是否解决",
-                                ],
-                                applicable_stages: ["需求分析", "架构设计", "详细设计", "编码与单元测试"],
-                                note: "确定性门禁在 FIRST_PRINCIPLES_STAGES 阶段自动检测 FP 模式",
-                            },
-                            hint,
-                        },
-                    };
-                }
-                case "reasoning_log": {
-                    return {
-                        result: {
-                            parsed_command: parsed,
-                            execution_result: {
-                                message: "推理记录查看",
-                                topic: parsed.description,
-                                note: "推理记录在确定性门禁评估时自动生成，包含 FP 规则命中和风险模式扫描结果",
-                                fp_rules_triggered: "通过 sf_command 检查门禁 查看 level2.fp_rules_triggered",
-                                brainstorm_history: "通过 sf_command 状态 查看管线历史中的头脑风暴记录",
-                                knowledge_assets: [
-                                    "templates/rules/shared/第一性原理推理规则.md",
-                                    "templates/procedures/不确定时头脑风暴流程.md",
-                                ],
-                            },
-                            hint,
-                        },
-                    };
-                }
                 // D13: 快捷路径
                 case "direct_answer": {
                     return {
@@ -764,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,
                         },
                     };
@@ -782,7 +812,7 @@ export async function registerStateMachineTools(ctx) {
                             parsed_command: parsed,
                             execution_result: {
                                 error: `无法识别的命令: "${args.text}"`,
-                                available_verbs: ["开始", "推进", "回退", "检查", "状态", "初始化", "头脑风暴", "第一性原理", "推理记录", "诊断", "修复", "跳转", "重置", "归档"],
+                                available_verbs: ["开始", "审查", "推进", "回退", "状态", "初始化", "诊断", "修复"],
                             },
                         },
                     };
@@ -853,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 进行质量验证",
                 },
             };
         }
@@ -940,6 +1000,164 @@ export async function registerStateMachineTools(ctx) {
     });
 }
 // ── 辅助函数 ──
+/**
+ * 为单产物编排结果生成顶层指令。
+ *
+ * 将四层编排的 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 };