soloforge 1.1.38 → 1.1.40

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

@@ -9,10 +9,26 @@
  * 双轨并行：与现有工具完全独立，不修改任何现有代码。
  */
 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";
 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 主链路消费（决策研讨场景）
+import { lazyDesignArtifactPack } from "../lazy_loaders.js"; // design_artifact_pack 主链路消费（设计产物包场景）
+/** 运行时校验并转换 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,17 +62,191 @@ 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);
+                    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,
+                            });
+                        }
+                        return { result: { evidence_blocked: true, _evGate } };
+                    }
+                }
+            }
+            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,
             });
+            // 证据接地运行时写回（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);
+                    result.architecture_decision_workshop = evaluated;
+                    const gate = archMod.evaluateArchitectureDecisionWorkshop(evaluated);
+                    if (!gate.allowed) {
+                        result.status = "awaiting_confirmation";
+                    }
+                }
+                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";
+                    }
+                }
+            }
+            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);
+                    result.decision_workshop = evaluated;
+                    result.activated_packs = evaluated?.activated_packs ?? [];
+                    const gate = decMod.evaluateDecisionWorkshop(evaluated);
+                    if (!gate.allowed) {
+                        result.status = "awaiting_confirmation";
+                    }
+                }
+                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);
+                        result.decision_workshop = contract;
+                        result.activated_packs = filteredPacks;
+                        if (!gate.allowed) {
+                            result.status = "awaiting_confirmation";
+                        }
+                    }
+                }
+            }
+            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 {
+                /* 产出物检测失败不阻断主流程 */
+            }
             return { result };
         }
         catch (err) {
@@ -69,15 +259,77 @@ 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) {
+                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 } };
+                    }
+                }
+                catch { /* 非关键 */ }
+            }
             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 +347,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,
             });
@@ -111,15 +363,89 @@ export async function registerStateMachineTools(ctx) {
     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: args.stage ?? undefined,
+                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) {
@@ -127,6 +453,55 @@ export async function registerStateMachineTools(ctx) {
         }
     });
     // ══════════════════════════════════════════════════
+    // sf_record_verification_execution — 记录验证执行结果
+    // ══════════════════════════════════════════════════
+    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.recordVerificationExecution, "记录验证执行结果。将验证计划的执行记录写入任务上下文，供后续验收使用", RecordVerificationSchema, async (args) => {
+        try {
+            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) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
     // sf_command — [sf] 命令统一入口
     // ══════════════════════════════════════════════════
     const CommandSchema = {
@@ -170,6 +545,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_gate_check",
+                                    "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": {
@@ -275,14 +686,64 @@ export async function registerStateMachineTools(ctx) {
                     });
                     return { result: { parsed_command: parsed, execution_result: result, hint } };
                 }
-                case "brainstorm":
+                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: `Phase 2 功能：${parsed.verb} 将在确定性门禁第二级自动触发`,
+                                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,
                         },
@@ -321,7 +782,7 @@ export async function registerStateMachineTools(ctx) {
                             parsed_command: parsed,
                             execution_result: {
                                 error: `无法识别的命令: "${args.text}"`,
-                                available_verbs: ["开始", "推进", "回退", "检查", "状态", "初始化", "头脑风暴", "第一性原理", "诊断", "修复", "跳转", "重置", "归档"],
+                                available_verbs: ["开始", "推进", "回退", "检查", "状态", "初始化", "头脑风暴", "第一性原理", "推理记录", "诊断", "修复", "跳转", "重置", "归档"],
                             },
                         },
                     };
@@ -418,5 +879,82 @@ 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) } };
+        }
+    });
+}
+// ── 辅助函数 ──
+/** 应用 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