soloforge 1.1.42 → 1.1.44

package/dist/server/tools/middleware.js

@@ -1,134 +1,64 @@
-// ── 工具注册中间件 ──
-// 封装安全的工具注册边界: 授权、状态预检、
-// 计划门控、指令合同门控、设计产物门控、生命周期知识门控、
-// 合同校验和错误处理。
-//
-// 从 tools.ts 第 1096-1658 行提取。
-import path from "node:path";
-import { promises as fsp } from "node:fs";
-import { debug } from "../../engine/core/logger.js";
-import { ENV } from "../../engine/core/env.js";
-import { findToolInvocationContractByName, createToolTrace, validateToolInvocation, hasWriteSideEffect, } from "../../engine/contracts/tool_invocation_contract_registry.js";
-import { TOOL_DIAGNOSTIC_CODES } from "../../engine/audit/diagnostic_registry.js";
-import { lazyAnchor } from "./lazy_loaders.js";
-import { checkInstructionContractGate, } from "./gate_checks.js";
-import { errorMessage } from "../../engine/core/helpers.js";
-import { mergeSceneContractsIntoToolContracts } from "../../engine/pipeline/state_machine/static_route_table.js";
-import { matchesScopePattern } from "../../engine/core/path_scope_utils.js";
-import { evaluatePlanProposalGate, evaluateDesignArtifactGate, evaluateLifecycleKnowledgeGate, } from "../../engine/pipeline/state_machine/certainty_gate.js";
-import { checkBrainstormGate } from "./cep_assessment.js";
+/**
+ * 工具注册中间件 — 封装安全的工具注册边界。
+ *
+ * 职责边界：
+ * - 负责：合同查找、动态 category/side_effects 计算、合同验证、
+ *   声明式门禁链调用、handler 执行与响应装饰
+ * - 不负责：授权决策（在 middleware/authorization.ts）、
+ *   LLM 预算（在 middleware/budget_check.ts）、
+ *   工作区/denied_paths（在 middleware/workspace_check.ts）、
+ *   具体工具业务逻辑（在各 sf_* 工具模块中）
+ *
+ * 被谁调用：各 sf_* 工具模块通过 createToolRegistrar 注册工具
+ * 调用谁：middleware/authorization、middleware/budget_check、
+ *   middleware/workspace_check、middleware_gates、gate_engine、lazy_loaders
+ *
+ * 数据流：MCP 请求 → 合同查找 → 授权 → 状态/预算/工作区预检 →
+ *   声明式门禁链 → 合同验证 → handler 执行 → 响应装饰 → MCP 响应
+ * 持久化：读写 .soloforge/ 目录、项目知识文件
+ */
+import { debug } from "../../shared/logger.js";
+import { SoloForgeError } from "../../shared/errors.js";
+import { findToolInvocationContractByName, createToolTrace, validateToolInvocation, hasWriteSideEffect, runMiddlewareGates, } from "../../gate/index.js";
+import { errorMessage } from "../../shared/helpers.js";
+// 场景路由已移除，保留空操作兼容
+import { checkAuth, checkStatePrecondition } from "./middleware/authorization.js";
+import { checkTokenBudget } from "./middleware/budget_check.js";
+import { checkWorkspaceIntegrity, checkDeniedPaths } from "./middleware/workspace_check.js";
+import { loadRelevantAnchors } from "./middleware/anchor_loader.js";
 // ── 工厂 ──
 export function createToolRegistrar(ctx) {
-    const { server, config, taskContext, projectPath } = ctx;
+    const { server, config, taskContext, gateway, ioController, projectPath } = ctx;
     // ── 辅助: 计算有效 category ──
-    /** 计算 sf_pipeline_status cancel 的动态 category */
+    /** 计算 sf_task cancel 的动态 category */
     function computeEffectiveCategory(toolName, args, contract) {
-        if (toolName === "sf_pipeline_status" && (args.action === "cancel" || args.action === "archive_stale" || args.job_action === "job_cancel")) {
+        if (toolName === "sf_task" && (args.action === "cancel")) {
             return "normal_controlled";
         }
         return contract.category;
     }
     // ── 辅助: 计算有效副作用 ──
-    /** 计算 sf_pipeline_status cancel 的动态 side_effects */
+    /** 计算 sf_task cancel 的动态 side_effects */
     function computeEffectiveSideEffects(toolName, args, contract) {
-        if (toolName === "sf_pipeline_status" && (args.action === "cancel" || args.action === "archive_stale" || args.job_action === "job_cancel")) {
+        if (toolName === "sf_task" && args.action === "cancel") {
             return ["task_context_write"];
         }
         return contract.side_effects;
     }
-    // ── 状态预检 ──
-    /** 状态预检: 在合同守卫之前验证任务状态 */
-    const STATE_PRECHECKS = {
-        sf_record_verification_execution: ["verifying", "executing"],
-    };
-    const STATE_ERROR_LABELS = {
-        sf_record_verification_execution: "不可录入验证结果",
-    };
-    // ── D2: 状态机驱动路由工具 — 跳过旧任务状态预检 ──
-    // 这些工具使用 PipelineState 管理状态，不依赖旧 TaskContext.status
-    const STATE_MACHINE_TOOL_NAMES = new Set([
-        "sf_pipeline_init", "sf_stage_execute", "sf_stage_advance",
-        "sf_stage_rollback", "sf_gate_check", "sf_command",
-        "sf_next", "sf_pipeline_status", "sf_direct_answer", "sf_single_artifact",
-        "sf_config_update",
-    ]);
-    // ── 授权模型 ──
-    /** 授权模型: explicit > dynamic write gate > destructive gate > workflow gate > category default */
-    function checkAuth(toolName, args, contract, tCtx, effectiveCategory) {
-        // 1. 显式确认
-        // 安全修复: confirm/authorized 仅在未配置 AUTH_TOKEN 时允许（旧行为兼容）
-        // 配置了 AUTH_TOKEN 时，必须通过 authorization_token 精确匹配
-        const hasAuthToken = !!process.env[ENV.AUTH_TOKEN];
-        if (args.confirm === true || args.authorized === true) {
-            if (hasAuthToken) {
-                // 配置了 AUTH_TOKEN 时不接受 confirm/authorized 快捷授权
-                return { required: true, granted: false, reason: "AUTH_TOKEN 已配置，需提供 authorization_token" };
-            }
-            return { required: true, granted: true, reason: "explicit confirmation" };
-        }
-        if (args.authorization_token) {
-            const expectedToken = process.env[ENV.AUTH_TOKEN];
-            if (expectedToken) {
-                // 配置了 token 验证: 必须精确匹配
-                if (args.authorization_token !== expectedToken) {
-                    return { required: true, granted: false, reason: "authorization_token 不匹配" };
-                }
-            }
-            // 未配置 AUTH_TOKEN 时保持旧行为（truthy 即通过）
-            return { required: true, granted: true, reason: "explicit confirmation" };
-        }
-        // 1b. sf_pipeline_status 的写入型动作必须显式确认，即便普通查询本身允许自动维护状态。
-        if (toolName === "sf_pipeline_status" && (args.action === "cancel" || args.action === "archive_stale" || args.job_action === "job_cancel")) {
-            return { required: true, granted: false, reason: "dynamic write upgrade requires explicit confirmation" };
-        }
-        // 2. 动态写入升级: cancel/job_cancel 从 read_only 变为 write → 必须确认
-        if (effectiveCategory && effectiveCategory !== contract.category && effectiveCategory !== "read_only_bypass") {
-            return { required: true, granted: false, reason: "dynamic write upgrade requires explicit confirmation" };
-        }
-        // 3. 破坏性副作用始终需要显式确认
-        const destructive = ["git_commit", "git_push", "pr_create", "external_write"];
-        if (contract.side_effects.some((e) => destructive.includes(e))) {
-            return { required: true, granted: false, reason: "destructive side effects require explicit confirmation" };
-        }
-        // 4. 独立严格工具（无 workflow 要求，无 task context）→ 由 handler 自行检查
-        if (contract.category === "strict_controlled" && !tCtx && !contract.requires_workflow) {
-            if (contract.requires_authorization) {
-                return { required: true, granted: false, reason: "standalone strict tool requires explicit confirmation" };
-            }
-            return { required: false, granted: true, reason: "standalone strict tool" };
-        }
-        // 5. strict_controlled 的 workflow 合同门控
-        if (contract.category === "strict_controlled" && tCtx?.last_tool_trace) {
-            const allowed = tCtx.last_tool_trace.next_allowed_tools ?? [];
-            if (allowed.includes(toolName)) {
-                return { required: true, granted: true, reason: "workflow contract gate" };
-            }
-        }
-        // 5b. 基于状态的回退: 严格工具且任务处于有效状态但无 tool_trace
-        if (contract.category === "strict_controlled" && tCtx && !tCtx.last_tool_trace && contract.requires_workflow) {
-            const validStates = STATE_PRECHECKS[toolName];
-            if (validStates && validStates.includes(tCtx.status)) {
-                return { required: true, granted: true, reason: "task in valid state for tool" };
-            }
-        }
-        // 5c. 非严格工具: 自动授权，除非 requires_authorization
-        if (contract.category === "read_only_bypass" || contract.category === "normal_controlled") {
-            if (contract.requires_authorization) {
-                return { required: true, granted: false, reason: "tool requires explicit authorization" };
-            }
-            return { required: false, granted: true, reason: "non-strict category" };
-        }
-        return { required: true, granted: false, reason: "no authorization source" };
-    }
+    // 注：STATE_PRECHECKS / STATE_MACHINE_TOOL_NAMES / checkAuth / checkStatePrecondition
+    // 已迁移到 ./middleware/authorization.ts
     // ── 安全工具注册 ──
     /** P0-B3: 工具超时配置（毫秒） */
     const DEFAULT_TOOL_TIMEOUT_MS = 5 * 60 * 1000; // 5 分钟
     const TOOL_TIMEOUTS_MS = {
-        sf_stage_execute: 10 * 60 * 1000, // 10 分钟
-        sf_stage_advance: 10 * 60 * 1000, // 10 分钟
-        sf_gate_check: 10 * 60 * 1000, // 10 分钟
-        sf_pipeline_status: 30 * 1000, // 30 秒
-        sf_next: 30 * 1000, // 30 秒
+        // v2 域架构工具
+        sf_work: 10 * 60 * 1000, // 10 分钟（act/verify 可能耗时较长）
+        sf_gate: 5 * 60 * 1000, // 5 分钟
+        sf_task: 30 * 1000, // 30 秒
+        sf_doctor: 30 * 1000, // 30 秒
+        sf_knowledge: 30 * 1000, // 30 秒
+        sf_analyze: 30 * 1000, // 30 秒
+        sf_scaffold: 10 * 60 * 1000, // 10 分钟
     };
     function getToolTimeoutMs(toolName) {
         return TOOL_TIMEOUTS_MS[toolName] ?? DEFAULT_TOOL_TIMEOUT_MS;
@@ -172,9 +102,8 @@ export function createToolRegistrar(ctx) {
     /** P0-B3: 实际工具执行逻辑（从 server.tool handler 抽出，便于超时包裹） */
     async function performToolCall(name, args, invocationId, handler) {
         const taskId = typeof args.task_id === "string" ? args.task_id : undefined;
-        // 合同查找: 状态机工具仍消费合同中的 category/side_effects/next_tools 等字段，
-        // 但状态转移由 PipelineState 驱动（见 STATE_MACHINE_TOOL_NAMES 豁免机制，L298）。
-        // 非状态机工具迁移到 scene_route 合同后，此查找可简化为仅服务状态机工具。
+        // 合同查找: 工具消费合同中的 category/side_effects/next_tools 等字段，
+        // 域架构下状态转移由 DomainTransition 管理。
         const contract = findToolInvocationContractByName(name);
         // 无合同 → hard fail
         if (!contract) {
@@ -185,36 +114,23 @@ export function createToolRegistrar(ctx) {
         }
         const effectiveCategory = computeEffectiveCategory(name, args, contract);
         const rawSideEffects = computeEffectiveSideEffects(name, args, contract);
-        // 非管线静态路由：合并场景化约束（知识管理、分析、审计、报告等独立工具）
-        const sceneExtension = mergeSceneContractsIntoToolContracts(name, {
-            allowed_side_effects: rawSideEffects,
-        });
-        // 将场景允许的额外副作用合并到有效副作用列表
-        const effectiveSideEffects = sceneExtension.additional_allowed_side_effects.length > 0
-            ? [...rawSideEffects, ...sceneExtension.additional_allowed_side_effects]
-            : rawSideEffects;
+        // 场景路由已移除，直接使用原始副作用列表
+        const effectiveSideEffects = rawSideEffects;
         // 加载 TaskContext
         let tCtx = null;
         if (taskId) {
             tCtx = await taskContext.load(taskId);
         }
-        // 状态预检: 在合同守卫之前验证任务状态
-        // D2: 状态机工具跳过旧任务状态预检
-        if (STATE_MACHINE_TOOL_NAMES.has(name)) {
-            // 状态机工具使用 PipelineState，不受旧 TaskContext.status 约束
-        }
-        else if (taskId && STATE_PRECHECKS[name] && tCtx) {
-            const validStates = STATE_PRECHECKS[name];
-            if (!validStates.includes(tCtx.status)) {
-                const label = STATE_ERROR_LABELS[name] ?? "状态不正确";
-                return {
-                    content: [{ type: "text", text: JSON.stringify({
-                                error: `任务状态 ${tCtx.status} ${label}，需要 ${validStates.join(" 或 ")}`,
-                                status: tCtx.status,
-                            }) }],
-                    isError: true,
-                };
-            }
+        // 状态预检: 在合同守卫之前验证任务状态（已抽出至 middleware/authorization.ts）
+        const stateError = checkStatePrecondition(name, taskId, tCtx);
+        if (stateError) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            error: stateError,
+                            status: tCtx?.status,
+                        }) }],
+                isError: true,
+            };
         }
         // 严格受控但缺少 task_id
         const isStandaloneStrict = !contract.requires_workflow;
@@ -228,7 +144,7 @@ export function createToolRegistrar(ctx) {
         const authorization = checkAuth(name, args, contract, tCtx ?? undefined, effectiveCategory);
         // 授权拒绝 → 仅对网关级拒绝执行 hard fail
         // （动态写入升级、破坏性操作、无授权源的 strict_controlled）
-        // Handler 级授权（如 sf_gate_check confirm）由 handler 自行处理
+        // Handler 级授权（如 sf_gate confirm）由 handler 自行处理
         const gatewayDenial = !authorization.granted &&
             authorization.reason !== "tool requires explicit authorization";
         if (gatewayDenial) {
@@ -261,249 +177,75 @@ export function createToolRegistrar(ctx) {
         // read_only_bypass 的旁路处理
         const bypass = effectiveCategory === "read_only_bypass"
             ? { allowed: true, reason: "read_only" } : undefined;
-        // 场景禁止路径校验：非管线工具不得操作场景声明的禁止路径
+        // 声明式门禁链（场景禁止路径、设计产物门、施工指令契约门、计划前置门、生命周期知识门禁、头脑风暴门禁）
         const hasWriteEffect = hasWriteSideEffect(effectiveSideEffects);
-        if (sceneExtension.forbidden_path_patterns.length > 0 && hasWriteEffect) {
-            const targetPaths = [];
-            if (typeof args.file_path === "string")
-                targetPaths.push(args.file_path);
-            if (typeof args.target_path === "string")
-                targetPaths.push(args.target_path);
-            if (typeof args.output_path === "string")
-                targetPaths.push(args.output_path);
-            if (Array.isArray(args.file_paths)) {
-                for (const fp of args.file_paths) {
-                    if (typeof fp === "string")
-                        targetPaths.push(fp);
-                }
-            }
-            const forbiddenHit = targetPaths.find((p) => sceneExtension.forbidden_path_patterns.some((pat) => matchesScopePattern(p, pat)));
-            if (forbiddenHit) {
-                const pathViolation = {
-                    invocation_id: invocationId,
-                    tool_name: name,
-                    violation_type: "guard_blocked",
-                    severity: "hard_fail",
-                    reason: `工具 ${name} 的场景 ${sceneExtension.scene_id} 禁止操作路径 ${forbiddenHit}（匹配模式 ${sceneExtension.forbidden_path_patterns.join(", ")}）`,
-                    recovery: "选择场景允许的路径或使用合适的工具执行此操作",
-                };
-                const pathTrace = createToolTrace({
-                    tool_name: name, invocation_id: invocationId, task_id: taskId,
-                    actual_side_effects: effectiveSideEffects,
-                    next_allowed_tools: contract.default_next_tools,
-                    forbidden_tools: contract.forbidden_next_tools,
-                    authorization, bypass,
-                });
-                if (taskId && tCtx) {
-                    await taskContext.setToolTrace(taskId, pathTrace, [pathViolation]);
-                }
-                return {
-                    content: [{ type: "text", text: JSON.stringify({
-                                error: pathViolation.reason,
-                                violation: pathViolation,
-                                scene_id: sceneExtension.scene_id,
-                                forbidden_path_patterns: sceneExtension.forbidden_path_patterns,
-                            }) }],
-                    isError: true,
-                };
-            }
-        }
-        // 计划前置门（确定性门禁第二级）: 写工具必须有 plan_proposal_gate
-        // sf_pipeline_init 创建任务、sf_stage_execute 创建 plan_proposal_gate — 两者豁免
-        // 注: hasWriteEffect 已在场景禁止路径校验处计算
-        const planGateExempt = name === "sf_pipeline_init" || name === "sf_stage_execute";
-        if (hasWriteEffect && taskId && !planGateExempt) {
-            const pgResult = evaluatePlanProposalGate({ ctx: tCtx, toolName: name, sideEffects: effectiveSideEffects });
-            if (!pgResult.allowed) {
-                const planViolation = {
-                    invocation_id: invocationId, tool_name: name,
-                    violation_type: "guard_blocked", severity: "hard_fail",
-                    reason: pgResult.reason ?? "执行前缺少 Plan Proposal Gate",
-                    recovery: "先调用 sf_pipeline_init → sf_stage_execute → 设置 plan_proposal_gate 后再执行此工具",
-                };
-                const blockedTrace = createToolTrace({
-                    tool_name: name, invocation_id: invocationId, task_id: taskId,
-                    actual_side_effects: effectiveSideEffects,
-                    next_allowed_tools: contract.default_next_tools,
-                    forbidden_tools: contract.forbidden_next_tools,
-                    authorization, bypass,
-                });
-                await taskContext.setToolTrace(taskId, blockedTrace, [planViolation]);
-                return {
-                    content: [{ type: "text", text: JSON.stringify({
-                                error: planViolation.reason,
-                                violation: planViolation,
-                                diagnostic_code: pgResult.diagnostic_code ?? TOOL_DIAGNOSTIC_CODES.planGate,
-                                recovery: planViolation.recovery,
-                            }) }],
-                    isError: true,
-                };
-            }
-            const planGateCheck = taskContext.checkPlanGateBeforeWrite(tCtx);
-            if (!planGateCheck.allowed) {
-                const planViolation = {
-                    invocation_id: invocationId, tool_name: name,
-                    violation_type: "guard_blocked", severity: "hard_fail",
-                    reason: planGateCheck.reason_zh,
-                    recovery: "请先通过 PlanProposalFirstGate 生成并确认执行计划",
-                };
-                const blockedTrace = createToolTrace({
-                    tool_name: name, invocation_id: invocationId, task_id: taskId,
-                    actual_side_effects: effectiveSideEffects,
-                    next_allowed_tools: contract.default_next_tools,
-                    forbidden_tools: contract.forbidden_next_tools,
-                    authorization, bypass,
-                });
-                await taskContext.setToolTrace(taskId, blockedTrace, [planViolation]);
-                return {
-                    content: [{ type: "text", text: JSON.stringify({
-                                error: planViolation.reason,
-                                violation: planViolation,
-                                diagnostic_code: TOOL_DIAGNOSTIC_CODES.planGate,
-                                recovery: planViolation.recovery,
-                            }) }],
-                    isError: true,
-                };
-            }
-        }
-        // 施工指令契约门: 写操作前检查 instruction_contract 状态
-        if (hasWriteEffect && taskId) {
-            const instrResult = await checkInstructionContractGate({ ctx: tCtx, toolName: name, sideEffects: effectiveSideEffects, task_id: taskId, taskContextMgr: taskContext });
-            if (!instrResult.allowed) {
-                const instrViolation = {
-                    invocation_id: invocationId, tool_name: name,
-                    violation_type: "guard_blocked", severity: "hard_fail",
-                    reason: instrResult.reason ?? "施工指令未就绪",
-                    recovery: "请先完善施工指令（目标、范围、非目标、落点、验收标准、禁止绕过项）",
-                };
-                const instrTrace = createToolTrace({
-                    tool_name: name, invocation_id: invocationId, task_id: taskId,
-                    actual_side_effects: effectiveSideEffects,
-                    next_allowed_tools: contract.default_next_tools,
-                    forbidden_tools: contract.forbidden_next_tools,
-                    authorization, bypass,
-                });
-                await taskContext.setToolTrace(taskId, instrTrace, [instrViolation]);
-                return {
-                    content: [{ type: "text", text: JSON.stringify({
-                                error: instrViolation.reason,
-                                violation: instrViolation,
-                                diagnostic_code: instrResult.diagnostic_code ?? TOOL_DIAGNOSTIC_CODES.instructionContract,
-                                recovery: instrViolation.recovery,
-                            }) }],
-                    isError: true,
-                };
-            }
-        }
-        // 设计产物门（确定性门禁第三级）: MCP 写入路径同样必须消费设计产物包状态，不能绕开 CLI hook。
-        if (hasWriteEffect && taskId) {
-            const designWriteGate = evaluateDesignArtifactGate({ ctx: tCtx, toolName: name, sideEffects: effectiveSideEffects });
-            if (!designWriteGate.allowed) {
-                const designViolation = {
-                    invocation_id: invocationId, tool_name: name,
-                    violation_type: "guard_blocked", severity: "hard_fail",
-                    reason: designWriteGate.reason ?? "设计产物包未达到实现就绪状态",
-                    recovery: "仅可继续补充设计资产并执行 sf_gate_check 真实复验；通过前不得写入业务实现",
-                };
-                const designTrace = createToolTrace({
-                    tool_name: name, invocation_id: invocationId, task_id: taskId,
-                    actual_side_effects: effectiveSideEffects,
-                    next_allowed_tools: contract.default_next_tools,
-                    forbidden_tools: contract.forbidden_next_tools,
-                    authorization, bypass,
-                });
-                await taskContext.setToolTrace(taskId, designTrace, [designViolation]);
-                return {
-                    content: [{ type: "text", text: JSON.stringify({
-                                error: designViolation.reason,
-                                violation: designViolation,
-                                diagnostic_code: designWriteGate.diagnostic_code,
-                                recovery: designViolation.recovery,
-                            }) }],
-                    isError: true,
-                };
-            }
-        }
-        // 生命周期知识门禁（确定性门禁第一级）: sf_stage_execute/sf_stage_advance 不能绕过项目 hard rule。
-        // sf_gate_check 豁免: 门禁检查自身需要先执行才能产出设计产物包验证结果，避免死循环
-        if (["sf_stage_execute", "sf_stage_advance"].includes(name)) {
-            const lifecycleResult = await evaluateLifecycleKnowledgeGate({
-                toolName: name,
-                projectPath,
-                config,
-                ctx: tCtx,
-                taskId,
-                changedFiles: Array.isArray(args.changed_files) ? args.changed_files : undefined,
-                sideEffects: effectiveSideEffects,
+        // problem-72 受控任务前置门禁：写入类工具必须在受控 SoloForge 任务上下文内调用。
+        // 无 task_id（没有受控 SoloForge 任务）时调用写入工具，等价于绕过受控生成链路的旁路编码
+        // （含禁止通过 Bash 直接写业务实现文件的同类风险），必须硬拦截。
+        // 豁免：standalone 工具（requires_workflow=false，如 sf_task 写 intent.yaml）
+        // 不属于业务实现编码，显式放行。
+        if (hasWriteEffect && !taskId && !isStandaloneStrict) {
+            const bypassTrace = createToolTrace({
+                tool_name: name, invocation_id: invocationId, task_id: taskId,
+                actual_side_effects: effectiveSideEffects,
+                next_allowed_tools: ["sf_task", "sf_doctor"],
+                forbidden_tools: contract.forbidden_next_tools,
+                authorization, bypass,
             });
-            if (!lifecycleResult.allowed) {
-                const pkViolation = {
-                    invocation_id: invocationId,
-                    tool_name: name,
-                    violation_type: "guard_blocked",
-                    severity: "hard_fail",
-                    reason: lifecycleResult.decision_summary_zh,
-                    recovery: lifecycleResult.recovery_commands.join("；") || "运行 soloforge next 查看统一生命周期知识合同阻断项",
-                };
-                const pkTrace = createToolTrace({
-                    tool_name: name, invocation_id: invocationId, task_id: taskId,
-                    actual_side_effects: effectiveSideEffects,
-                    next_allowed_tools: ["sf_stage_execute", "sf_pipeline_status"],
-                    forbidden_tools: ["sf_stage_execute", "sf_gate_check", "sf_stage_advance"],
-                    authorization, bypass,
-                });
-                if (taskId && tCtx)
-                    await taskContext.setToolTrace(taskId, pkTrace, [pkViolation]);
-                return {
-                    content: [{ type: "text", text: JSON.stringify({
-                                error: pkViolation.reason,
-                                violation: pkViolation,
-                                diagnostic_code: TOOL_DIAGNOSTIC_CODES.projectKnowledgeBlocked,
-                                findings: lifecycleResult.findings,
-                                lifecycle_knowledge_decision: {
-                                    contract_id: lifecycleResult.contract_id,
-                                    lifecycle_stage: lifecycleResult.lifecycle_stage,
-                                    authoritative_paths: lifecycleResult.authoritative_paths,
-                                    recovery_commands: lifecycleResult.recovery_commands,
-                                },
-                                recovery: pkViolation.recovery,
-                            }) }],
-                    isError: true,
-                };
-            }
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            error: "没有受控 SoloForge 任务，禁止通过 Bash 直接写业务实现文件。必须先 sf_task start 创建受控任务，再经 sf_work 在受控生成链路内编码。",
+                            violation: {
+                                invocation_id: invocationId, tool_name: name,
+                                violation_type: "controlled_implementation_bypass", severity: "hard_fail",
+                                reason: "写入类工具缺少受控任务上下文（无 task_id）",
+                                recovery: "先调用 sf_task start 创建受控任务，再通过 sf_work 编码",
+                            },
+                            tool_trace: bypassTrace,
+                            next_allowed_tools: ["sf_task", "sf_doctor"],
+                            forbidden_tools: contract.forbidden_next_tools,
+                        }) }],
+                isError: true,
+            };
         }
-        // ── 头脑风暴门禁（改造 10: CEP brainstorm gate 接入） ──
-        // TaskContext 中无 brainstorm_session 时返回 not_applicable_with_reason，不阻断
-        if (name === "sf_stage_execute") {
-            try {
-                const bsGate = await checkBrainstormGate({ ctx: tCtx });
-                if (!bsGate.allowed && !bsGate.not_applicable_with_reason) {
-                    const bsViolation = {
-                        invocation_id: invocationId,
-                        tool_name: name,
-                        violation_type: "guard_blocked",
-                        severity: "hard_fail",
-                        reason: bsGate.reason_zh ?? "头脑风暴门禁未通过",
-                        recovery: "完成头脑风暴方案探索后重试",
-                    };
-                    return {
-                        content: [{ type: "text", text: JSON.stringify({
-                                    error: bsViolation.reason,
-                                    violation: bsViolation,
-                                    recovery: bsViolation.recovery,
-                                }) }],
-                        isError: true,
-                    };
-                }
-            }
-            catch {
-                /* brainstorm gate 模块加载/运行异常降级，不阻断 */
+        const gateCtx = {
+            toolName: name, args, invocationId, taskId,
+            tCtx, hasWriteEffect, effectiveSideEffects,
+            sceneExtension: {
+                forbidden_path_patterns: [],
+                scene_id: undefined,
+            },
+            projectPath, config, taskContextMgr: taskContext,
+            contract: {
+                default_next_tools: contract.default_next_tools,
+                forbidden_next_tools: contract.forbidden_next_tools,
+            },
+            authorization, bypass,
+        };
+        const gateResult = await runMiddlewareGates(gateCtx);
+        // 2.3：提取累积的 advisory warnings（status 门禁降级后的建议，无论是否硬阻断都传给 AI agent）
+        const gateAdvisoryWarnings = gateResult?.extraResponseFields?.advisory_warnings ?? [];
+        if (gateResult && !gateResult.allowed) {
+            // 门禁拒绝 → 写入 trace 并返回拦截响应
+            if (gateResult.violation && taskId && tCtx) {
+                await taskContext.setToolTrace(taskId, gateResult.trace, [gateResult.violation]);
             }
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            error: gateResult.violation?.reason,
+                            violation: gateResult.violation,
+                            tool_trace: gateResult.trace,
+                            next_allowed_tools: contract.default_next_tools,
+                            forbidden_tools: contract.forbidden_next_tools,
+                            ...(gateResult.extraResponseFields ?? {}),
+                        }) }],
+                isError: true,
+            };
         }
         // 合同验证
         const lastTrace = tCtx?.last_tool_trace;
-        // 为动态工具构建有效的合同覆盖（如 sf_pipeline_status cancel）
-        // 合同覆盖: 用于 sf_pipeline_status cancel 等动态 category 升级场景。
+        // 为动态工具构建有效的合同覆盖（如 sf_task cancel）
+        // 合同覆盖: 用于 sf_task cancel 等动态 category 升级场景。
         let contractOverride;
         if (effectiveCategory !== contract.category || effectiveSideEffects !== contract.side_effects) {
             contractOverride = { ...contract, category: effectiveCategory, side_effects: effectiveSideEffects };
@@ -520,8 +262,15 @@ export function createToolRegistrar(ctx) {
             workflow_id: explicitWorkflowId,
             _contractOverride: contractOverride,
         });
-        // 基于状态的回退: 将 contract_state_mismatch 从 hard_fail 降级为 require_human
-        if (authorization.reason === "task in valid state for tool") {
+        // 基于状态的回退: 将 contract_state_mismatch 从 hard_fail 降级为 require_human。
+        // 覆盖两类状态授权：①「task in valid state for tool」(无 trace，authorization 5b 分支)
+        // ②「workflow contract gate」(工具在 last_tool_trace.next_allowed_tools 中，authorization 5 分支)。
+        // 两者均表明管线/任务态已授权该 strict_controlled 工具——pipeline_id 即工作流上下文，
+        // expansion.workflow_trace.workflow_id 在常态 sf_task→sf_work 流程中不填充，
+        // 不应据此对已状态授权的工具（如 sf_scaffold）判 hard_fail 而阻断执行。
+        const stateAuthorized = authorization.reason === "task in valid state for tool"
+            || authorization.reason === "workflow contract gate";
+        if (stateAuthorized) {
             for (const v of violations) {
                 if (v.violation_type === "contract_state_mismatch" && v.severity === "hard_fail") {
                     v.severity = "require_human";
@@ -552,6 +301,87 @@ export function createToolRegistrar(ctx) {
                 isError: true,
             };
         }
+        // ── CORE-001: LLMGateway Token 预算检查（已抽出至 middleware/budget_check.ts） ──
+        const budgetResult = checkTokenBudget(name, invocationId, taskId, gateway);
+        if (budgetResult.violation) {
+            const budgetTrace = createToolTrace({
+                tool_name: name, invocation_id: invocationId, task_id: taskId,
+                actual_side_effects: effectiveSideEffects,
+                next_allowed_tools: contract.default_next_tools,
+                forbidden_tools: contract.forbidden_next_tools,
+                authorization, bypass,
+            });
+            if (taskId && tCtx) {
+                await taskContext.setToolTrace(taskId, budgetTrace, [budgetResult.violation]);
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            error: budgetResult.violation.reason,
+                            violation: budgetResult.violation,
+                            tool_trace: budgetTrace,
+                            next_allowed_tools: contract.default_next_tools,
+                            forbidden_tools: contract.forbidden_next_tools,
+                        }) }],
+                isError: true,
+            };
+        }
+        const tokenBudgetWarning = budgetResult.warning;
+        // ── CORE-WF-001: IOController 工作区完整性检查（已抽出至 middleware/workspace_check.ts） ──
+        let workspaceWarning;
+        if (hasWriteEffect) {
+            const wsResult = await checkWorkspaceIntegrity(name, invocationId, taskId, ioController);
+            if (wsResult.violation) {
+                const workspaceTrace = createToolTrace({
+                    tool_name: name, invocation_id: invocationId, task_id: taskId,
+                    actual_side_effects: effectiveSideEffects,
+                    next_allowed_tools: ["sf_task", "sf_doctor"],
+                    forbidden_tools: contract.forbidden_next_tools,
+                    authorization, bypass,
+                });
+                if (taskId && tCtx) {
+                    await taskContext.setToolTrace(taskId, workspaceTrace, [wsResult.violation]);
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                error: wsResult.violation.reason,
+                                violation: wsResult.violation,
+                                tool_trace: workspaceTrace,
+                                ...(wsResult.extraResponseFields ?? {}),
+                                next_allowed_tools: ["sf_task", "sf_doctor"],
+                                forbidden_tools: contract.forbidden_next_tools,
+                            }) }],
+                    isError: true,
+                };
+            }
+            workspaceWarning = wsResult.warning;
+        }
+        // ── CORE-SEC-001: denied_paths 写入路径黑名单检查（已抽出至 middleware/workspace_check.ts） ──
+        if (hasWriteEffect) {
+            const deniedResult = checkDeniedPaths(name, invocationId, args, projectPath);
+            if (deniedResult.violation) {
+                const deniedTrace = createToolTrace({
+                    tool_name: name, invocation_id: invocationId, task_id: taskId,
+                    actual_side_effects: effectiveSideEffects,
+                    next_allowed_tools: contract.default_next_tools,
+                    forbidden_tools: contract.forbidden_next_tools,
+                    authorization, bypass,
+                });
+                if (taskId && tCtx) {
+                    await taskContext.setToolTrace(taskId, deniedTrace, [deniedResult.violation]);
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                error: deniedResult.violation.reason,
+                                violation: deniedResult.violation,
+                                tool_trace: deniedTrace,
+                                ...(deniedResult.extraResponseFields ?? {}),
+                                next_allowed_tools: contract.default_next_tools,
+                                forbidden_tools: contract.forbidden_next_tools,
+                            }) }],
+                    isError: true,
+                };
+            }
+        }
         // 执行 handler
         try {
             const raw = await handler(args);
@@ -577,22 +407,50 @@ export function createToolRegistrar(ctx) {
                 return raw;
             }
             // 从 { result } 模式中提取数据
+            // 注意：handler 可能返回 { result, must_follow, instruction }，
+            // must_follow/instruction 是 AI 必须遵守的执行指令，不能丢弃
             const rawRec = raw;
             const data = rawRec?.result !== undefined ? rawRec.result : rawRec;
+            // 将 handler 返回的 must_follow/instruction 合入 result，确保 AI 可见
+            if (rawRec && typeof rawRec === "object" && rawRec.result !== undefined && typeof rawRec.result === "object" && rawRec.result !== null) {
+                const resultObj = rawRec.result;
+                if (rawRec.must_follow !== undefined && resultObj._must_follow === undefined) {
+                    resultObj._must_follow = rawRec.must_follow;
+                }
+                if (rawRec.instruction !== undefined && resultObj._instruction === undefined) {
+                    resultObj._instruction = rawRec.instruction;
+                }
+                // 验证套件步骤约束：handler 可返回 _step_forbidden/_step_next_allowed
+                if (rawRec._step_forbidden !== undefined && resultObj._step_forbidden === undefined) {
+                    resultObj._step_forbidden = rawRec._step_forbidden;
+                }
+                if (rawRec._step_next_allowed !== undefined && resultObj._step_next_allowed === undefined) {
+                    resultObj._step_next_allowed = rawRec._step_next_allowed;
+                }
+            }
             const hasError = !!(data && typeof data === "object" && "error" in data);
             const dataRec = data;
             const recoveryNextTools = hasError && Array.isArray(dataRec.recovery_next_tools)
                 ? dataRec.recovery_next_tools
                 : contract.default_next_tools;
-            const recoveryForbiddenTools = hasError && Array.isArray(dataRec.recovery_forbidden_tools)
+            let recoveryForbiddenTools = hasError && Array.isArray(dataRec.recovery_forbidden_tools)
                 ? dataRec.recovery_forbidden_tools
                 : contract.forbidden_next_tools;
+            // ── 验证套件步骤约束覆盖 ──
+            // handler 通过 _step_forbidden/_step_next_allowed 传递验证套件的工具约束
+            const stepForbidden = Array.isArray(dataRec._step_forbidden) ? dataRec._step_forbidden : undefined;
+            const stepNextAllowed = Array.isArray(dataRec._step_next_allowed) ? dataRec._step_next_allowed : undefined;
+            if (!hasError) {
+                if (stepForbidden && stepForbidden.length > 0) {
+                    recoveryForbiddenTools = [...new Set([...recoveryForbiddenTools, ...stepForbidden])];
+                }
+            }
             // 构建 trace；失败处理器可显式开放修复重验路径
             const trace = createToolTrace({
                 tool_name: name, invocation_id: invocationId, task_id: taskId,
                 workflow_id: tCtx?.expansion?.workflow_trace?.workflow_id,
                 actual_side_effects: effectiveSideEffects,
-                next_allowed_tools: recoveryNextTools,
+                next_allowed_tools: stepNextAllowed && !hasError ? stepNextAllowed : recoveryNextTools,
                 forbidden_tools: recoveryForbiddenTools,
                 authorization, bypass,
             });
@@ -602,32 +460,43 @@ export function createToolRegistrar(ctx) {
             }
             // 用 trace + next/forbidden 装饰响应
             const response = {
-                ...data,
+                ...(typeof data === "object" && data !== null ? data : {}),
                 tool_trace: trace,
-                next_allowed_tools: recoveryNextTools,
+                next_allowed_tools: stepNextAllowed && !hasError ? stepNextAllowed : recoveryNextTools,
                 forbidden_tools: recoveryForbiddenTools,
             };
-            // 基于状态的回退: 在响应中暴露降级 workflow
-            if (authorization.reason === "task in valid state for tool") {
+            // 基于状态的回退: 在响应中暴露降级 workflow（与上方 stateAuthorized 同源判定）
+            if (stateAuthorized) {
                 response.degraded_workflow = true;
                 response.workflow_source = "state-based-fallback";
             }
+            // 注入降级放行时的警告信息
+            if (tokenBudgetWarning) {
+                response.token_budget_warning = tokenBudgetWarning;
+            }
+            if (workspaceWarning) {
+                response.workspace_warning = workspaceWarning;
+            }
+            // 2.3：注入 status 门禁降级后的 advisory 建议（供 AI agent 参考，不阻断流程）
+            if (gateAdvisoryWarnings.length > 0) {
+                response.advisory_warnings = gateAdvisoryWarnings;
+            }
             return {
                 content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
                 isError: hasError ? true : undefined,
             };
         }
         catch (err) {
-            const errorNextTools = name === "sf_stage_execute"
-                ? ["sf_stage_execute", "sf_pipeline_status", "sf_debug", "sf_governance_report"]
+            const errorNextTools = name === "sf_work"
+                ? ["sf_work", "sf_task", "sf_doctor", "sf_gate"]
                 : contract.default_next_tools;
-            const errorForbiddenTools = name === "sf_stage_execute"
-                ? ["sf_gate_check", "sf_stage_advance", "sf_scaffold"]
+            const errorForbiddenTools = name === "sf_work"
+                ? ["sf_scaffold"]
                 : contract.forbidden_next_tools;
             // P0-C1: 所有状态转换工具失败时统一标记 failed
-            // 防止 sf_stage_execute/sf_stage_advance/sf_gate_check 异常后任务卡 executing 30 分钟
+            // 防止 sf_work 异常后任务卡住
             const STATE_TRANSITION_TOOLS = new Set([
-                "sf_stage_execute", "sf_stage_advance", "sf_gate_check",
+                "sf_work",
             ]);
             if (STATE_TRANSITION_TOOLS.has(name) && taskId) {
                 // [ENG-7] 记录失败信息到 trace 再标记 failed，不跳过失败分析流程
@@ -653,74 +522,33 @@ export function createToolRegistrar(ctx) {
                     debug("middleware", `ToolTrace 写入失败 (error path): ${traceErr instanceof Error ? traceErr.message : String(traceErr)}`);
                 }
             }
+            // SoloForgeError 结构化传播: 将错误码、严重性、恢复建议暴露给 AI agent
+            const isSoloForgeErr = err instanceof SoloForgeError;
+            const errorResponse = {
+                error: errorMessage(err),
+                tool_trace: errorTrace,
+                next_allowed_tools: errorNextTools,
+                forbidden_tools: errorForbiddenTools,
+                recovery: `工具「${name}」执行出错：${errorMessage(err)}。${isSoloForgeErr && err.recovery ? err.recovery : "使用 sf_doctor 诊断或 sf_task query 查看任务状态"}`,
+            };
+            if (isSoloForgeErr) {
+                const sfErr = err;
+                errorResponse.recovery_hint = sfErr.recovery;
+                errorResponse.error_code = sfErr.code;
+                errorResponse.error_severity = sfErr.severity;
+            }
             return {
-                content: [{ type: "text", text: JSON.stringify({
-                            error: errorMessage(err),
-                            tool_trace: errorTrace,
-                            next_allowed_tools: errorNextTools,
-                            forbidden_tools: errorForbiddenTools,
-                        }) }],
+                content: [{ type: "text", text: JSON.stringify(errorResponse) }],
                 isError: true,
             };
         }
     }
     // ── 加载认知锚点上下文 ──
-    // 加载认知锚点上下文 — 必须提供相关性参数，禁止全量加载
-    async function loadRelevantAnchors(query) {
-        debug("工具注册", "加载认知锚点");
-        return _loadRelevantAnchorsInner(query);
-    }
-    async function _loadRelevantAnchorsInner(query) {
-        const stateDir = taskContext.getStateDir();
-        const mapPath = path.join(stateDir, "cognitive.map.json");
-        const mapData = (await lazyAnchor()).readMapJson(mapPath);
-        if (!mapData || mapData.anchors.length === 0)
-            return undefined;
-        const existingFiles = new Set();
-        try {
-            for (const anchor of mapData.anchors) {
-                for (const ref of anchor.source_refs) {
-                    if (ref.type === "file" && await fsp.access(path.join(projectPath, ref.ref)).then(() => true, () => false)) {
-                        existingFiles.add(ref.ref);
-                    }
-                }
-            }
-        }
-        catch { /* ignore */ }
-        const checked = (await lazyAnchor()).checkAnchorStaleness(mapData.anchors, existingFiles);
-        // 必须有 module 或 file_paths，否则不返回任何锚点（禁止全量加载）
-        if (!query.module && (!query.file_paths || query.file_paths.length === 0))
-            return undefined;
-        // 收集与任意提供的 file_paths 或 module 匹配的锚点
-        const seen = new Set();
-        const relevant = [];
-        if (query.module) {
-            for (const a of (await lazyAnchor()).filterRelevantAnchors(checked, { module: query.module })) {
-                if (!seen.has(a.anchor_id)) {
-                    seen.add(a.anchor_id);
-                    relevant.push(a);
-                }
-            }
-        }
-        if (query.file_paths) {
-            for (const fp of query.file_paths) {
-                for (const a of (await lazyAnchor()).filterRelevantAnchors(checked, { file_path: fp })) {
-                    if (!seen.has(a.anchor_id)) {
-                        seen.add(a.anchor_id);
-                        relevant.push(a);
-                    }
-                }
-            }
-        }
-        if (relevant.length === 0)
-            return undefined;
-        return relevant.map((a) => ({
-            anchor_id: a.anchor_id,
-            module: a.module,
-            summary: a.core_contracts.slice(0, 3).join("; "),
-            stale_anchor: a.stale_anchor,
-        }));
-    }
-    return { registerSafeTool, loadRelevantAnchors };
+    // 注：loadRelevantAnchors 已抽出至 ./middleware/anchor_loader.ts
+    const stateDir = taskContext.getStateDir();
+    return {
+        registerSafeTool,
+        loadRelevantAnchors: (query) => loadRelevantAnchors(query, stateDir, projectPath),
+    };
 }
 //# sourceMappingURL=middleware.js.map