soloforge 1.2.8 → 1.2.9

package/dist/adapters/claude_code/tools.js

@@ -1,7 +1,10 @@
 import { z } from "zod";
 import path from "node:path";
 import fss from "node:fs";
+import crypto from "node:crypto";
+import { findToolInvocationContractByName, createToolTrace, validateToolInvocation, } from "../../engine/tool_invocation_contract_registry.js";
 import { classify } from "../../engine/classifier.js";
+import { shouldEnterSoloForge } from "../../engine/intent_router.js";
 import { expand } from "../../engine/intent_expander.js";
 import { generateVerifyCommands } from "../../engine/verifier.js";
 import { evolve } from "../../engine/evolver.js";
@@ -21,6 +24,7 @@ import { checkFeasibility } from "../../engine/feasibility_checker.js";
 import { debugError } from "../../engine/debugger.js";
 import { generateReport } from "../../engine/observability.js";
 import { generateReport as generateGovernanceReport } from "../../engine/governance_report.js";
+import { resolveCurrentProjectConfigReports } from "../../engine/config_precedence_contract.js";
 import { analyzeMigration } from "../../engine/migration_guard.js";
 import { generateTestGuide } from "../../engine/test_generator.js";
 import { analyzeTestQuality } from "../../engine/test_quality.js";
@@ -39,6 +43,10 @@ import { EscapeReportStore } from "../../engine/escape_report.js";
 import { sampleAuditItems } from "../../engine/audit_sampler.js";
 import { decideAction } from "../../engine/capability_action_advisor.js";
 import { CapabilityStateStore } from "../../engine/capability_state_store.js";
+import { auditIntegration, buildMainPathIntegrationContracts, } from "../../engine/main_path_integration_contract.js";
+import { validateMechanismLayerMaps, listMechanismLayerMaps, } from "../../engine/dual_layer_mechanism_registry.js";
+import { classifyIngestionStatus } from "../../engine/input_material_contract_registry.js";
+import { verifyArtifact, } from "../../engine/artifact_contract_registry.js";
 // ── Zod Schema 定义 ──
 const ClassifySchema = {
     intent: z.string().describe("开发者意图描述"),
@@ -47,6 +55,7 @@ const ClassifySchema = {
 const ExpandSchema = {
     task_id: z.string().describe("sf_classify 返回的任务 ID"),
     clarification_answers: z.array(z.string()).optional().describe("对澄清问题的回答"),
+    input_material_confirmations: z.array(z.string()).optional().describe("已确认安全的输入材料路径列表"),
 };
 const VerifySchema = {
     task_id: z.string().describe("任务 ID"),
@@ -146,22 +155,277 @@ const ExploreSchema = {
  * @param server - MCP 服务器实例
  * @param deps - SoloForge 核心依赖项
  */
+/**
+ * 注册所有 MCP 工具到服务器实例。
+ * @param server - McpServer 实例
+ * @param deps - 工具依赖项（配置、知识索引、任务上下文）
+ */
 export function registerTools(server, deps) {
+    console.error("[soloForge] 工具注册: 开始注册 MCP 工具...");
     const { config, knowledgeIndex, taskContext } = deps;
     const projectPath = config._projectPath || process.cwd();
     // H1: LLM Gateway — Token 预算熔断，防止单任务 Token 超支
     const gateway = deps.gateway ?? new LLMGateway();
     // H4: IO Controller — 工作区互斥锁，防止外部修改导致的静默覆盖
     const ioController = new IOController(projectPath);
-    // 统一错误处理包装器，捕获工具执行中的异常并返回结构化错误响应
+    // ── 统一网关 : 唯一工具调用边界 ──
+    /** 计算 sf_status cancel 的动态 category */
+    function computeEffectiveCategory(toolName, args, contract) {
+        if (toolName === "sf_status" && (args.action === "cancel" || args.job_action === "job_cancel")) {
+            return "normal_controlled";
+        }
+        return contract.category;
+    }
+    /** 计算 sf_status cancel 的动态 side_effects */
+    function computeEffectiveSideEffects(toolName, args, contract) {
+        if (toolName === "sf_status" && (args.action === "cancel" || args.job_action === "job_cancel")) {
+            return ["task_context_write"];
+        }
+        return contract.side_effects;
+    }
+    /** State precheck: validate task status before contract guard */
+    const STATE_PRECHECKS = {
+        sf_verify: ["executing", "retrying"],
+        sf_learn: ["verifying", "executing"],
+        sf_expand: ["classifying", "expanding", "clarifying"],
+    };
+    const STATE_ERROR_LABELS = {
+        sf_verify: "不可验证",
+        sf_learn: "不可学习",
+        sf_expand: "不可膨胀",
+    };
+    /** 授权模型: explicit > dynamic write gate > destructive gate > workflow gate > category default */
+    function checkAuth(toolName, args, contract, ctx, effectiveCategory) {
+        // 1. Explicit confirmation
+        if (args.confirm === true || args.authorized === true || args.authorization_token) {
+            return { required: true, granted: true, reason: "explicit confirmation" };
+        }
+        // 2. Dynamic write upgrade: cancel/job_cancel from read_only to write → must confirm
+        if (effectiveCategory && effectiveCategory !== contract.category && effectiveCategory !== "read_only_bypass") {
+            return { required: true, granted: false, reason: "dynamic write upgrade requires explicit confirmation" };
+        }
+        // 3. Destructive side effects always require explicit
+        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. Standalone strict tools (no workflow required, no task context) → handler does own checks
+        if (contract.category === "strict_controlled" && !ctx && !contract.requires_workflow) {
+            return { required: false, granted: true, reason: "standalone strict tool" };
+        }
+        // 5. Workflow contract gate for strict_controlled
+        if (contract.category === "strict_controlled" && ctx?.last_tool_trace) {
+            const allowed = ctx.last_tool_trace.next_allowed_tools ?? [];
+            if (allowed.includes(toolName)) {
+                return { required: true, granted: true, reason: "workflow contract gate" };
+            }
+        }
+        // 5b. State-based fallback: strict tool with valid-state task but no tool_trace
+        if (contract.category === "strict_controlled" && ctx && !ctx.last_tool_trace && contract.requires_workflow) {
+            const validStates = STATE_PRECHECKS[toolName];
+            if (validStates && validStates.includes(ctx.status)) {
+                return { required: true, granted: true, reason: "task in valid state for tool" };
+            }
+        }
+        // 5c. Non-strict tools: auto-grant unless 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" };
+    }
     function registerSafeTool(name, desc, schema, handler) {
         server.tool(name, desc, schema, async (args) => {
+            const invocationId = `inv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const taskId = args.task_id;
+            const contract = findToolInvocationContractByName(name);
+            // No contract → hard fail
+            if (!contract) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: `工具 ${name} 未注册契约` }) }],
+                    isError: true,
+                };
+            }
+            const effectiveCategory = computeEffectiveCategory(name, args, contract);
+            const effectiveSideEffects = computeEffectiveSideEffects(name, args, contract);
+            // Load TaskContext
+            let ctx = null;
+            if (taskId) {
+                ctx = await taskContext.load(taskId);
+            }
+            // State precheck: validate task status before contract guard
+            if (taskId && STATE_PRECHECKS[name] && ctx) {
+                const validStates = STATE_PRECHECKS[name];
+                if (!validStates.includes(ctx.status)) {
+                    const label = STATE_ERROR_LABELS[name] ?? "状态不正确";
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({
+                                    error: `任务状态 ${ctx.status} ${label}，需要 ${validStates.join(" 或 ")}`,
+                                    status: ctx.status,
+                                }) }],
+                        isError: true,
+                    };
+                }
+            }
+            // Strict controlled without task_id
+            const isStandaloneStrict = !contract.requires_workflow;
+            if (contract.category === "strict_controlled" && !taskId && !isStandaloneStrict) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: `strict controlled 工具 ${name} 需要 task_id` }) }],
+                    isError: true,
+                };
+            }
+            // Authorization
+            const authorization = checkAuth(name, args, contract, ctx ?? undefined, effectiveCategory);
+            // Authorization denied → hard fail for gateway-level denials only
+            // (dynamic write upgrade, destructive ops, strict_controlled with no auth source)
+            // Handler-level authorization (e.g. sf_capability_update confirm) is left to the handler
+            const gatewayDenial = !authorization.granted &&
+                authorization.reason !== "tool requires explicit authorization";
+            if (gatewayDenial) {
+                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: undefined,
+                });
+                const authViolation = {
+                    invocation_id: invocationId, tool_name: name,
+                    violation_type: "missing_authorization", severity: "hard_fail",
+                    reason: authorization.reason ?? "authorization denied",
+                    recovery: "提供 confirm=true / authorized=true / authorization_token",
+                };
+                if (taskId && ctx) {
+                    await taskContext.setToolTrace(taskId, blockedTrace, [authViolation]);
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                error: authViolation.reason, violation: authViolation,
+                                tool_trace: blockedTrace,
+                                next_allowed_tools: contract.default_next_tools,
+                                forbidden_tools: contract.forbidden_next_tools,
+                            }) }],
+                    isError: true,
+                };
+            }
+            // Bypass for read_only_bypass
+            const bypass = effectiveCategory === "read_only_bypass"
+                ? { allowed: true, reason: "read_only" } : undefined;
+            // Contract validation
+            const lastTrace = ctx?.last_tool_trace;
+            // Build effective contract override for dynamic tools (e.g., sf_status cancel)
+            let contractOverride;
+            if (effectiveCategory !== contract.category || effectiveSideEffects !== contract.side_effects) {
+                contractOverride = { ...contract, category: effectiveCategory, side_effects: effectiveSideEffects };
+            }
+            // Workflow ID: only from real expansion trace
+            const explicitWorkflowId = ctx?.expansion?.workflow_trace?.workflow_id;
+            const violations = validateToolInvocation({
+                tool_name: name,
+                current_next_allowed: lastTrace?.next_allowed_tools ?? [],
+                current_forbidden: lastTrace?.forbidden_tools ?? [],
+                authorization,
+                bypass,
+                actual_side_effects: effectiveSideEffects,
+                workflow_id: explicitWorkflowId,
+                _contractOverride: contractOverride,
+            });
+            // State-based fallback: downgrade contract_state_mismatch from hard_fail to require_human
+            if (authorization.reason === "task in valid state for tool") {
+                for (const v of violations) {
+                    if (v.violation_type === "contract_state_mismatch" && v.severity === "hard_fail") {
+                        v.severity = "require_human";
+                        v.reason += " (state-based fallback: no real workflow_id)";
+                    }
+                }
+            }
+            // Hard-fail violations → block
+            const hardFail = violations.find(v => v.severity === "hard_fail");
+            if (hardFail) {
+                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,
+                });
+                if (taskId && ctx) {
+                    await taskContext.setToolTrace(taskId, blockedTrace, violations);
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                error: hardFail.reason, violation: hardFail,
+                                tool_trace: blockedTrace,
+                                next_allowed_tools: contract.default_next_tools,
+                                forbidden_tools: contract.forbidden_next_tools,
+                            }) }],
+                    isError: true,
+                };
+            }
+            // Execute handler
             try {
-                return await handler(args);
+                const raw = await handler(args);
+                // Pass through if handler returned { content } directly
+                if (raw && typeof raw === "object" && "content" in raw && Array.isArray(raw.content)) {
+                    return raw;
+                }
+                // Extract data from { result } pattern
+                const data = raw?.result !== undefined ? raw.result : raw;
+                const hasError = !!(data && typeof data === "object" && "error" in data);
+                // Build trace
+                const trace = createToolTrace({
+                    tool_name: name, invocation_id: invocationId, task_id: taskId,
+                    workflow_id: ctx?.expansion?.workflow_trace?.workflow_id,
+                    actual_side_effects: effectiveSideEffects,
+                    next_allowed_tools: contract.default_next_tools,
+                    forbidden_tools: contract.forbidden_next_tools,
+                    authorization, bypass,
+                });
+                // Write trace to TaskContext
+                if (taskId) {
+                    await taskContext.setToolTrace(taskId, trace, violations.length > 0 ? violations : undefined);
+                }
+                // Decorate response with trace + next/forbidden
+                const response = {
+                    ...data,
+                    tool_trace: trace,
+                    next_allowed_tools: contract.default_next_tools,
+                    forbidden_tools: contract.forbidden_next_tools,
+                };
+                // State-based fallback: expose degraded workflow in response
+                if (authorization.reason === "task in valid state for tool") {
+                    response.degraded_workflow = true;
+                    response.workflow_source = "state-based-fallback";
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                    isError: hasError ? true : undefined,
+                };
             }
             catch (err) {
+                const errorTrace = 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) {
+                    try {
+                        await taskContext.setToolTrace(taskId, errorTrace);
+                    }
+                    catch { /* best effort */ }
+                }
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }) }],
+                    content: [{ type: "text", text: JSON.stringify({
+                                error: err instanceof Error ? err.message : String(err),
+                                tool_trace: errorTrace,
+                                next_allowed_tools: contract.default_next_tools,
+                                forbidden_tools: contract.forbidden_next_tools,
+                            }) }],
                     isError: true,
                 };
             }
@@ -169,6 +433,10 @@ export function registerTools(server, deps) {
     }
     // 加载认知锚点上下文 — 必须提供相关性参数，禁止全量加载
     function loadRelevantAnchors(query) {
+        console.error("[soloForge] 工具注册: 加载认知锚点");
+        return _loadRelevantAnchorsInner(query);
+    }
+    function _loadRelevantAnchorsInner(query) {
         const stateDir = taskContext.getStateDir();
         const mapPath = path.join(stateDir, "cognitive.map.json");
         const mapData = readMapJson(mapPath);
@@ -219,61 +487,52 @@ export function registerTools(server, deps) {
             stale_anchor: a.stale_anchor,
         }));
     }
+    console.error("[soloForge] 工具注册: 批量注册核心/辅助/知识维护工具...");
     // ── sf_classify: 意图分类入口，创建任务上下文并返回分类结果 ──
     registerSafeTool("sf_classify", "分析开发者意图，返回任务类型、风险、复杂度和执行策略", ClassifySchema, async (args) => {
         // 检查是否存在进行中的任务
         const existing = await taskContext.getCurrentTask();
         if (existing && !["done", "failed"].includes(existing.status)) {
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify({
-                            warning: "存在未完成的任务",
-                            existing_task_id: existing.task_id,
-                            existing_status: existing.status,
-                            existing_intent: existing.intent,
-                            hint: "调用 sf_status action=cancel 取消旧任务，或继续完成它",
-                        }),
-                    }],
-                isError: true,
+                result: {
+                    error: "存在未完成的任务",
+                    warning: "存在未完成的任务",
+                    existing_task_id: existing.task_id,
+                    existing_status: existing.status,
+                    existing_intent: existing.intent,
+                    hint: "调用 sf_status action=cancel 取消旧任务，或继续完成它",
+                },
             };
         }
         // 创建任务上下文
         const ctx = await taskContext.create(args.intent, config.product_profile);
-        const input = { intent: args.intent, project_path: projectPath };
+        const input = { intent: args.intent, project_path: projectPath, task_id: ctx.task_id };
         const classification = classify(input);
         // 存储分类结果
         await taskContext.setClassification(ctx.task_id, classification);
-        if (classification.strategy === "skip_soloForge") {
+        if (!shouldEnterSoloForge(classification.route_decision)) {
             await taskContext.updateStatus(ctx.task_id, "done");
         }
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        task_id: ctx.task_id,
-                        ...classification,
-                    }, null, 2),
-                }],
+            result: {
+                task_id: ctx.task_id,
+                ...classification,
+            },
         };
     });
     // ── sf_expand: 意图膨胀，生成结构化 prompt 并注入计划上下文 ──
     registerSafeTool("sf_expand", "将意图膨胀为结构化 prompt，包含 scope、验收标准和知识匹配。当存在计划时自动注入当前阶段上下文和输出模板", ExpandSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx || !ctx.classification) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在或尚未分类，请先调用 sf_classify" }) }],
-                isError: true,
-            };
+            return { result: { error: "任务不存在或尚未分类，请先调用 sf_classify" } };
         }
-        // 状态守卫：classifying → expanding 或允许 expanding 恢复（中断重试）
-        if (ctx.status === "classifying") {
+        // 状态守卫：classifying/expanding/clarifying → expanding
+        if (ctx.status === "classifying" || ctx.status === "clarifying") {
             await taskContext.updateStatus(args.task_id, "expanding");
         }
         else if (ctx.status !== "expanding") {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: `任务状态 ${ctx.status} 不可膨胀，需要 classifying 或 expanding`, status: ctx.status }) }],
-                isError: true,
+                result: { error: `任务状态 ${ctx.status} 不可膨胀，需要 classifying 或 expanding`, status: ctx.status },
             };
         }
         // 构建计划上下文（如果存在计划）
@@ -324,7 +583,10 @@ export function registerTools(server, deps) {
                 config,
                 knowledgeIndex,
                 clarificationAnswers: args.clarification_answers,
+                route_decision: ctx.classification?.route_decision,
                 plan_context: planContext,
+                input_material_confirmations: args.input_material_confirmations,
+                task_id: args.task_id,
             });
         }
         catch (expandErr) {
@@ -343,12 +605,26 @@ export function registerTools(server, deps) {
             gateway.endTask();
         }
         expansion.task_id = args.task_id;
+        // Input Material Contract: 处理 hard-blocking 结果
+        // Privacy Gate: 隐私/敏感信息策略阻断
+        const isBlocked = expansion.prompt.startsWith("## 阻塞：输入材料禁止读取")
+            || expansion.prompt.startsWith("## 阻塞：隐私/敏感信息策略");
+        const isMaterialClarification = expansion.prompt.startsWith("## 澄清请求") && expansion.input_materials?.some((m) => m.access_mode !== "forbidden" && classifyIngestionStatus(m.path_or_ref) === "requires_confirmation");
         // 注入 H1/H4 advisory warnings
         const advisories = {};
         if (h1Warning)
             advisories.h1_advisory = h1Warning;
         if (h4LockWarning)
             advisories.h4_advisory = h4LockWarning;
+        // Config precedence warnings 
+        if (expansion.config_resolution_reports && expansion.config_resolution_reports.length > 0) {
+            const configWarnings = expansion.config_resolution_reports
+                .filter(r => r.conflicts.length > 0)
+                .map(r => r.conflicts.map(c => `${c.reason}`).join("; "));
+            if (configWarnings.length > 0) {
+                advisories.config_precedence_warnings = configWarnings;
+            }
+        }
         // 决策契约 advisory: 校验 expand 输出是否包含默认决策字段
         const decisionContract = validateDecisionOutput(expansion);
         if (!decisionContract.passed) {
@@ -357,6 +633,10 @@ export function registerTools(server, deps) {
         // 存储膨胀结果
         try {
             await taskContext.setExpansion(args.task_id, expansion);
+            // 存储产物记录
+            if (expansion.output_artifact_record) {
+                await taskContext.setArtifact(args.task_id, expansion.output_artifact_record);
+            }
         }
         catch (setErr) {
             try {
@@ -367,9 +647,17 @@ export function registerTools(server, deps) {
             }
             throw setErr;
         }
-        // 转换到执行阶段
+        // 转换到下一阶段：blocked → failed, clarification → clarifying, else → executing
         try {
-            await taskContext.updateStatus(args.task_id, "executing");
+            if (isBlocked) {
+                await taskContext.updateStatus(args.task_id, "failed");
+            }
+            else if (expansion.prompt.startsWith("## 澄清请求")) {
+                await taskContext.updateStatus(args.task_id, "clarifying");
+            }
+            else {
+                await taskContext.updateStatus(args.task_id, "executing");
+            }
         }
         catch (updateErr) {
             try {
@@ -380,11 +668,11 @@ export function registerTools(server, deps) {
             }
             throw updateErr;
         }
+        const expandPayload = Object.keys(advisories).length > 0
+            ? { ...expansion, advisories }
+            : expansion;
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify(Object.keys(advisories).length > 0 ? { ...expansion, advisories } : expansion, null, 2),
-                }],
+            result: expandPayload,
         };
     });
     // ── sf_verify: 生成验证命令（构建、测试、验收检查） ──
@@ -392,15 +680,13 @@ export function registerTools(server, deps) {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
-                isError: true,
+                result: { error: "任务不存在" },
             };
         }
         const VALID_VERIFY_STATES = ["executing", "retrying"];
         if (!VALID_VERIFY_STATES.includes(ctx.status)) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: `任务状态 ${ctx.status} 不可验证，需要 executing 或 retrying`, status: ctx.status }) }],
-                isError: true,
+                result: { error: `任务状态 ${ctx.status} 不可验证，需要 executing 或 retrying`, status: ctx.status },
             };
         }
         const acceptanceItems = ctx.expansion
@@ -411,14 +697,68 @@ export function registerTools(server, deps) {
         const h4Warning = !integrity.clean
             ? { warning: `H4 advisory: ${integrity.message}`, dirty_files: integrity.dirty_files }
             : undefined;
-        const verifyResult = generateVerifyCommands(config, args.changed_files, acceptanceItems);
+        const verifyResult = generateVerifyCommands(config, args.changed_files, acceptanceItems, ctx?.expansion?.workflow_trace?.route);
         verifyResult.task_id = args.task_id;
+        // Artifact lifecycle check : draft → verified requires ArtifactVerificationResult.passed
+        let artifactVerificationResult;
+        let artifactFileMissing = false;
+        if (ctx.artifact_output && ctx.artifact_output.status === "draft") {
+            // Resolve artifact file and compute hash before verification
+            const artifact = ctx.artifact_output;
+            const fullPath = path.join(projectPath, artifact.path);
+            if (fss.existsSync(fullPath)) {
+                const fileContent = fss.readFileSync(fullPath);
+                const hash = crypto.createHash("sha256").update(fileContent).digest("hex");
+                artifact.hash = `sha256:${hash}`;
+                if (!artifact.evidence_refs.some(r => r.startsWith("file:artifact:"))) {
+                    artifact.evidence_refs.push(`file:artifact:path=${artifact.path} hash=sha256:${hash}`);
+                }
+                // Save updated artifact with hash
+                const ctxForHash = await taskContext.load(args.task_id);
+                if (ctxForHash?.artifact_output) {
+                    ctxForHash.artifact_output.hash = artifact.hash;
+                    if (!ctxForHash.artifact_output.evidence_refs.some(r => r.startsWith("file:artifact:"))) {
+                        ctxForHash.artifact_output.evidence_refs.push(`file:artifact:path=${artifact.path} hash=sha256:${hash}`);
+                    }
+                    await taskContext.save(ctxForHash);
+                }
+            }
+            else {
+                artifactFileMissing = true;
+            }
+            artifactVerificationResult = verifyArtifact(artifact.kind, artifact);
+        }
         // 记录变更文件
         await taskContext.setExecution(args.task_id, args.changed_files);
+        // Mark no_change_artifact when no real files changed but artifact exists
+        if (args.changed_files.length === 0 && ctx.artifact_output) {
+            const execCtx = await taskContext.load(args.task_id);
+            if (execCtx?.execution) {
+                execCtx.execution.no_change_artifact = true;
+                await taskContext.save(execCtx);
+            }
+        }
         // 生成验证命令成功后再转换状态，避免操作失败导致任务卡在 verifying
+        if (ctx.status === "retrying") {
+            await taskContext.updateStatus(args.task_id, "executing");
+        }
         await taskContext.updateStatus(args.task_id, "verifying");
         // 存储验证结果
         await taskContext.setVerification(args.task_id, verifyResult);
+        // Artifact lifecycle transition: draft → verified only if ArtifactVerificationResult.passed
+        if (ctx.artifact_output && ctx.artifact_output.status === "draft" && artifactVerificationResult?.passed) {
+            const evidenceRef = `verification:${ctx.task_id}:checks=${artifactVerificationResult.checks.length}:summary=${artifactVerificationResult.summary.slice(0, 60)}`;
+            try {
+                await taskContext.updateArtifactStatus(args.task_id, {
+                    status: "verified",
+                    evidenceRef,
+                    hasVerification: true,
+                });
+            }
+            catch {
+                // Transition blocked — artifact stays draft, pipeline continues
+            }
+        }
         // 认知锚点上下文回放（按变更文件相关性）
         const verifyAnchors = loadRelevantAnchors({ file_paths: args.changed_files });
         const verifyExtras = {};
@@ -426,11 +766,18 @@ export function registerTools(server, deps) {
             verifyExtras.h4_advisory = h4Warning;
         if (verifyAnchors && verifyAnchors.length > 0)
             verifyExtras.cognitive_anchors = verifyAnchors;
+        if (ctx.artifact_output && ctx.artifact_output.status === "draft" && artifactVerificationResult && !artifactVerificationResult.passed) {
+            const reason = artifactFileMissing
+                ? `产物文件不存在 (${ctx.artifact_output.path})，无法计算 hash`
+                : artifactVerificationResult.summary;
+            verifyExtras.artifact_warning = `产物验收检查未通过: ${reason}`;
+            verifyExtras.artifact_verification = artifactVerificationResult;
+        }
+        const verifyPayload = Object.keys(verifyExtras).length > 0
+            ? { ...verifyResult, ...verifyExtras }
+            : verifyResult;
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify(Object.keys(verifyExtras).length > 0 ? { ...verifyResult, ...verifyExtras } : verifyResult, null, 2),
-                }],
+            result: verifyPayload,
         };
     });
     // ── sf_learn: 从执行结果中提取知识，支持重试循环控制 ──
@@ -438,15 +785,13 @@ export function registerTools(server, deps) {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
-                isError: true,
+                result: { error: "任务不存在" },
             };
         }
         const VALID_LEARN_STATES = ["verifying", "executing"];
         if (!VALID_LEARN_STATES.includes(ctx.status)) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: `任务状态 ${ctx.status} 不可学习，需要 verifying 或 executing`, status: ctx.status }) }],
-                isError: true,
+                result: { error: `任务状态 ${ctx.status} 不可学习，需要 verifying 或 executing`, status: ctx.status },
             };
         }
         // 如适用，记录失败
@@ -478,15 +823,28 @@ export function registerTools(server, deps) {
             learnResult.retry_hint = `第 ${attemptCount}/${maxAttempts} 次尝试失败，${args.failure_type === "scope_insufficient" ? "需要扩大范围" : "请修复后重试"}`;
         }
         else {
-            // 最终: 转换到完成（或所有重试耗尽后标记为失败）
-            const finalStatus = args.result === "failure" ? "failed" : "done";
+            // 检查主链路集成 — 即使 build/test 全绿，孤岛仍阻断 done
+            const integrationBlocked = ctx.verification?.main_path_integration
+                && !ctx.verification.main_path_integration.passed;
+            // 核心工程执行原则门禁 — required 原则失败不能进入 completed
+            const principlesBlocked = ctx.verification?.core_principles
+                && !ctx.verification.core_principles.overall_passed;
+            const finalStatus = args.result === "failure"
+                ? "failed"
+                : (integrationBlocked || principlesBlocked) ? "retrying" : "done";
             await taskContext.updateStatus(args.task_id, finalStatus);
+            if (integrationBlocked && finalStatus === "retrying") {
+                learnResult.retry_hint = "主链路集成检查失败: 存在孤岛模块，请接入主链路后重试";
+            }
+            if (principlesBlocked && finalStatus === "retrying") {
+                const failedPrinciples = ctx.verification.core_principles.principles
+                    .filter((p) => p.status === "failed")
+                    .map((p) => p.principle_id);
+                learnResult.retry_hint = `核心工程执行原则检查失败: ${failedPrinciples.join(", ")}，请修复后重试`;
+            }
         }
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify(learnResult, null, 2),
-                }],
+            result: learnResult,
         };
     });
     // ── sf_status: 任务状态查询（current/recent/resume/cancel） ──
@@ -496,8 +854,7 @@ export function registerTools(server, deps) {
         if (args.job_action) {
             if (!args.job_id) {
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ error: "job 操作需要 job_id" }) }],
-                    isError: true,
+                    result: { error: "job 操作需要 job_id" },
                 };
             }
             const jm = new JobManager(taskContext.getStateDir());
@@ -506,47 +863,39 @@ export function registerTools(server, deps) {
                 const status = await jm.getJobStatus(args.job_id, taskId);
                 if (!status) {
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ error: `job ${args.job_id} 不存在或已过期` }) }],
-                        isError: true,
+                        result: { error: `job ${args.job_id} 不存在或已过期` },
                     };
                 }
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ job: status }, null, 2) }],
+                    result: { job: status },
                 };
             }
             if (args.job_action === "job_resume") {
                 const checkpoint = await jm.resumeFromCheckpoint(args.job_id, taskId);
                 if (!checkpoint) {
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ error: `job ${args.job_id} 无可恢复的 checkpoint` }) }],
-                        isError: true,
+                        result: { error: `job ${args.job_id} 无可恢复的 checkpoint` },
                     };
                 }
                 return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                advisory: "job 恢复为 advisory 操作，需确认 checkpoint 数据与当前状态一致",
-                                job_id: checkpoint.job_id,
-                                task_id: checkpoint.task_id,
-                                phase: checkpoint.phase,
-                                checkpoint_number: checkpoint.checkpoint_number,
-                                cognitive_anchor: checkpoint.cognitive_anchor,
-                            }, null, 2),
-                        }],
+                    result: {
+                        advisory: "job 恢复为 advisory 操作，需确认 checkpoint 数据与当前状态一致",
+                        job_id: checkpoint.job_id,
+                        task_id: checkpoint.task_id,
+                        phase: checkpoint.phase,
+                        checkpoint_number: checkpoint.checkpoint_number,
+                        cognitive_anchor: checkpoint.cognitive_anchor,
+                    },
                 };
             }
             if (args.job_action === "job_cancel") {
                 const removed = await jm.cancelJob(args.job_id, taskId);
                 return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                advisory: "job 取消为 advisory 操作",
-                                job_id: args.job_id,
-                                cancelled: removed,
-                            }),
-                        }],
+                    result: {
+                        advisory: "job 取消为 advisory 操作",
+                        job_id: args.job_id,
+                        cancelled: removed,
+                    },
                 };
             }
         }
@@ -557,7 +906,7 @@ export function registerTools(server, deps) {
                     : await taskContext.getCurrentTask();
                 if (!ctx) {
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ message: "当前无活跃任务" }) }],
+                        result: { message: "当前无活跃任务" },
                     };
                 }
                 const resumable = taskContext.isResumable(ctx);
@@ -599,78 +948,61 @@ export function registerTools(server, deps) {
                     // JobManager advisory — ignore errors
                 }
                 return {
-                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    result: result,
                 };
             }
             case "recent": {
                 const recent = await taskContext.listRecent(10);
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ tasks: recent }, null, 2) }],
+                    result: { tasks: recent },
                 };
             }
             case "resume": {
                 if (!args.task_id) {
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ error: "恢复任务需要 task_id" }) }],
-                        isError: true,
+                        result: { error: "恢复任务需要 task_id" },
                     };
                 }
                 const ctx = await taskContext.load(args.task_id);
                 if (!ctx) {
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
-                        isError: true,
+                        result: { error: "任务不存在" },
                     };
                 }
                 if (!taskContext.isResumable(ctx)) {
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ error: `任务状态 ${ctx.status} 不可恢复`, status: ctx.status }) }],
-                        isError: true,
+                        result: { error: `任务状态 ${ctx.status} 不可恢复`, status: ctx.status },
                     };
                 }
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                task_id: ctx.task_id,
-                                intent: ctx.intent,
-                                status: ctx.status,
-                                resume_hint: taskContext.getResumeHint(ctx),
-                                classification: ctx.classification,
-                                expansion: ctx.expansion ? {
-                                    scope: ctx.expansion.scope,
-                                    matched_patterns: ctx.expansion.matched_patterns,
-                                } : undefined,
-                                execution: ctx.execution ? {
-                                    changed_files: ctx.execution.changed_files,
-                                    attempt_count: ctx.execution.attempt_count,
-                                } : undefined,
-                                cognitive_anchors: ctx.execution?.changed_files?.length
-                                    ? loadRelevantAnchors({ file_paths: ctx.execution.changed_files })
-                                    : undefined,
-                            }, null, 2),
-                        }],
+                const resumeResult = {
+                    task_id: ctx.task_id,
+                    intent: ctx.intent,
+                    status: ctx.status,
+                    resume_hint: taskContext.getResumeHint(ctx),
                 };
+                if (ctx.execution)
+                    resumeResult.execution = ctx.execution;
+                const resumeAnchors = ctx.execution?.changed_files
+                    ? loadRelevantAnchors({ file_paths: ctx.execution.changed_files })
+                    : undefined;
+                if (resumeAnchors && resumeAnchors.length > 0)
+                    resumeResult.cognitive_anchors = resumeAnchors;
+                return { result: resumeResult };
             }
             case "cancel": {
                 if (!args.task_id) {
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ error: "取消任务需要 task_id" }) }],
-                        isError: true,
+                        result: { error: "取消任务需要 task_id" },
                     };
                 }
                 const cancelled = await taskContext.cancel(args.task_id);
                 return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({ task_id: args.task_id, cancelled }),
-                        }],
+                    result: { task_id: args.task_id, cancelled },
                 };
             }
             default:
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ error: `未知操作: ${action}` }) }],
-                    isError: true,
+                    result: { error: `未知操作: ${action}` },
                 };
         }
     });
@@ -679,8 +1011,7 @@ export function registerTools(server, deps) {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.classification) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在或尚未分类" }) }],
-                isError: true,
+                result: { error: "任务不存在或尚未分类" },
             };
         }
         const result = planTask({
@@ -692,7 +1023,7 @@ export function registerTools(server, deps) {
         result.task_id = args.task_id;
         await taskContext.setPlanning(args.task_id, result);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_plan_advance: 推进多阶段计划到下一步 ──
@@ -700,8 +1031,7 @@ export function registerTools(server, deps) {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.planning || ctx.planning.sub_tasks.length === 0) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务没有多阶段计划，请先调用 sf_plan" }) }],
-                isError: true,
+                result: { error: "任务没有多阶段计划，请先调用 sf_plan" },
             };
         }
         const plan = ctx.planning;
@@ -709,38 +1039,33 @@ export function registerTools(server, deps) {
         const previousStepTitle = previousStep?.title ?? "未知";
         const nextIndex = plan.current_step_index + 1;
         if (nextIndex >= plan.sub_tasks.length) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({
-                            task_id: args.task_id,
-                            previous_step: previousStepTitle,
-                            current_step_index: plan.current_step_index,
-                            total_steps: plan.sub_tasks.length,
-                            is_completed: true,
-                            message: `所有 ${plan.sub_tasks.length} 个阶段已完成`,
-                        }, null, 2) }],
-            };
+            return { result: {
+                    task_id: args.task_id,
+                    previous_step: previousStepTitle,
+                    current_step_index: plan.current_step_index,
+                    total_steps: plan.sub_tasks.length,
+                    is_completed: true,
+                    message: `所有 ${plan.sub_tasks.length} 个阶段已完成`,
+                } };
         }
         // 推进阶段索引
         plan.current_step_index = nextIndex;
         await taskContext.setPlanning(args.task_id, plan);
         const nextStep = plan.sub_tasks[nextIndex];
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        task_id: args.task_id,
-                        previous_step: previousStepTitle,
-                        current_step_index: nextIndex,
-                        current_step: {
-                            id: nextStep.id,
-                            title: nextStep.title,
-                            output_path: nextStep.output_path,
-                        },
-                        total_steps: plan.sub_tasks.length,
-                        is_completed: false,
-                        message: `阶段推进: ${previousStepTitle} → ${nextStep.title}`,
-                    }, null, 2),
-                }],
+            result: {
+                task_id: args.task_id,
+                previous_step: previousStepTitle,
+                current_step_index: nextIndex,
+                current_step: {
+                    id: nextStep.id,
+                    title: nextStep.title,
+                    output_path: nextStep.output_path,
+                },
+                total_steps: plan.sub_tasks.length,
+                is_completed: false,
+                message: `阶段推进: ${previousStepTitle} → ${nextStep.title}`,
+            },
         };
     });
     // ── sf_analyze: 影响范围分析，建议是否扩大作用域 ──
@@ -748,8 +1073,7 @@ export function registerTools(server, deps) {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.expansion) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务尚未膨胀，请先调用 sf_expand" }) }],
-                isError: true,
+                result: { error: "任务尚未膨胀，请先调用 sf_expand" },
             };
         }
         const result = await analyzeImpact({
@@ -766,17 +1090,14 @@ export function registerTools(server, deps) {
         if (!decisionContract.passed) {
             advisoryExtras.decision_contract_advisory = decisionContract.advisory;
         }
-        return {
-            content: [{ type: "text", text: JSON.stringify(Object.keys(advisoryExtras).length > 0 ? { ...result, ...advisoryExtras } : result, null, 2) }],
-        };
+        return { result: Object.keys(advisoryExtras).length > 0 ? { ...result, ...advisoryExtras } : result };
     });
     // ── sf_review: 代码审查（质量、安全、性能、技术债务） ──
     registerSafeTool("sf_review", "审查代码变更的质量、安全、性能和技术债务。hotfix 场景可跳过。建议性，不强制修复", ReviewSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
-                isError: true,
+                result: { error: "任务不存在" },
             };
         }
         const tracker = new DebtTracker(projectPath);
@@ -797,29 +1118,22 @@ export function registerTools(server, deps) {
         if (!decisionContract.passed) {
             reviewExtras.decision_contract_advisory = decisionContract.advisory;
         }
-        return {
-            content: [{ type: "text", text: JSON.stringify(Object.keys(reviewExtras).length > 0 ? { ...result, ...reviewExtras } : result, null, 2) }],
-        };
+        return { result: Object.keys(reviewExtras).length > 0 ? { ...result, ...reviewExtras } : result };
     });
     // ── sf_scaffold: 生成标准化代码骨架 ──
     registerSafeTool("sf_scaffold", "根据项目模板生成标准化代码骨架（Controller/Service/DTO/测试等）。仅在 task_type=scaffold 时使用", ScaffoldSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.classification) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在或尚未分类" }) }],
-                isError: true,
+                result: { error: "任务不存在或尚未分类" },
             };
         }
         if (ctx.classification.task_type !== "scaffold") {
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify({
-                            error: "sf_scaffold 仅适用于 scaffold 类型任务",
-                            current_type: ctx.classification.task_type,
-                        }),
-                    }],
-                isError: true,
+                result: {
+                    error: "sf_scaffold 仅适用于 scaffold 类型任务",
+                    current_type: ctx.classification.task_type,
+                },
             };
         }
         const result = await generateScaffold({
@@ -830,7 +1144,7 @@ export function registerTools(server, deps) {
         });
         result.task_id = args.task_id;
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_deliver: 自动提交、推送、创建 PR ──
@@ -838,8 +1152,7 @@ export function registerTools(server, deps) {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
-                isError: true,
+                result: { error: "任务不存在" },
             };
         }
         // H4: 交付前工作区完整性检查 — advisory 模式，仅警告不阻断
@@ -847,6 +1160,41 @@ export function registerTools(server, deps) {
         const h4DeliverWarning = !deliverIntegrity.clean
             ? { warning: `H4 advisory: ${deliverIntegrity.message}`, dirty_files: deliverIntegrity.dirty_files }
             : undefined;
+        // Artifact status gate : deliver requires artifact status = accepted with evidence
+        if (ctx.artifact_output) {
+            const status = ctx.artifact_output.status;
+            if (status === "draft") {
+                return {
+                    result: {
+                        error: `产物状态为 ${status}，需先通过验证 (verified) 并确认 (accepted) 才能交付`,
+                        artifact_id: ctx.artifact_output.artifact_id,
+                        current_status: status,
+                    },
+                };
+            }
+            if (status === "verified") {
+                return {
+                    result: {
+                        error: `产物状态为 ${status}，需人工确认或后续 workflow 采用后变为 accepted 才能交付`,
+                        artifact_id: ctx.artifact_output.artifact_id,
+                        current_status: status,
+                    },
+                };
+            }
+            // accepted must have confirmation evidence
+            if (status === "accepted") {
+                const hasAcceptanceEvidence = ctx.artifact_output.evidence_refs.some((r) => r.includes("acceptance") || r.includes("workflow_adoption"));
+                if (!hasAcceptanceEvidence) {
+                    return {
+                        result: {
+                            error: `产物状态为 accepted 但缺少确认证据 (acceptance/workflow_adoption evidence_ref)`,
+                            artifact_id: ctx.artifact_output.artifact_id,
+                            current_status: status,
+                        },
+                    };
+                }
+            }
+        }
         const result = await deliver({
             taskContext: ctx,
             config,
@@ -858,10 +1206,7 @@ export function registerTools(server, deps) {
         });
         await taskContext.setDelivery(args.task_id, result);
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify(h4DeliverWarning ? { ...result, h4_advisory: h4DeliverWarning } : result, null, 2),
-                }],
+            result: h4DeliverWarning ? { ...result, h4_advisory: h4DeliverWarning } : result,
         };
     });
     // ── sf_coord_check: 预测性冲突检测和跨仓库协调 ──
@@ -873,7 +1218,7 @@ export function registerTools(server, deps) {
             gitOps: realGitOps,
         });
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_team_status: 团队活动流和工作负载查询 ──
@@ -886,7 +1231,7 @@ export function registerTools(server, deps) {
             knowledgeIndex: args.include_knowledge ? knowledgeIndex : undefined,
         });
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_contract_check: API 契约变更检测 ──
@@ -903,7 +1248,7 @@ export function registerTools(server, deps) {
             gitOps: realGitOps,
         });
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_onboard: 新人分步引导 ──
@@ -917,7 +1262,7 @@ export function registerTools(server, deps) {
             reset: args.reset,
         });
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_feasibility_check: 任务可行性评估 ──
@@ -925,13 +1270,12 @@ export function registerTools(server, deps) {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.classification) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在或未完成分类，请先调用 sf_classify" }) }],
-                isError: true,
+                result: { error: "任务不存在或未完成分类，请先调用 sf_classify" },
             };
         }
         const result = checkFeasibility(ctx.classification, config);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_debug: 智能排障（解析错误 → 根因分析 → 修复方案） ──
@@ -942,7 +1286,7 @@ export function registerTools(server, deps) {
         ];
         const result = debugError(args.error_output, args.task_id || `debug-${Date.now()}`, projectScope);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_observability: 系统可观测和运行报告 ──
@@ -952,35 +1296,35 @@ export function registerTools(server, deps) {
         const capability = getCapabilitySummary();
         const output = { ...result, capability };
         return {
-            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+            result: output,
         };
     });
     // ── sf_migration_check: 数据库迁移安全性分析 ──
     registerSafeTool("sf_migration_check", "分析数据库迁移文件安全性：检测破坏性操作（DROP/DELETE/TRUNCATE）并生成回滚建议", MigrationCheckSchema, async (args) => {
         const result = analyzeMigration(args.content, args.filename);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_test_guide: 基于变更文件生成测试指引 ──
     registerSafeTool("sf_test_guide", "根据变更文件类型生成测试指引：推荐测试类型、场景、Mock 点和断言模板", TestGuideSchema, async (args) => {
         const result = generateTestGuide(args.changed_files, [], config);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_test_quality: 测试文件质量五维评分 ──
     registerSafeTool("sf_test_quality", "评估测试文件质量：断言密度、边界覆盖、命名、重复率、场景覆盖五维评分", TestQualitySchema, async (args) => {
         const result = analyzeTestQuality(args.content, args.filename);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_dependency_scan: 依赖漏洞扫描 ──
     registerSafeTool("sf_dependency_scan", "扫描依赖声明文件漏洞：已知 CVE 规则匹配、未锁定版本检测、支持 npm/maven/gradle", DependencyScanSchema, async (args) => {
         const result = scanDependencies(args.content, args.filename);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_debt_report: 技术债务报告生成 ──
@@ -988,7 +1332,7 @@ export function registerTools(server, deps) {
         const tracker = new DebtTracker(projectPath);
         const result = await generateDebtReport(tracker);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_explore: 自主技术选型与方案证伪 ──
@@ -1010,15 +1354,13 @@ export function registerTools(server, deps) {
         if (!decisionContract.passed) {
             exploreExtras.decision_contract_advisory = decisionContract.advisory;
         }
-        return {
-            content: [{ type: "text", text: JSON.stringify(Object.keys(exploreExtras).length > 0 ? { ...result, ...exploreExtras } : result, null, 2) }],
-        };
+        return { result: Object.keys(exploreExtras).length > 0 ? { ...result, ...exploreExtras } : result };
     });
     // ── sf_knowledge_audit: 知识库健康审计 ──
     registerSafeTool("sf_knowledge_audit", "审计知识库：识别过时条目、重复触发词、格式缺失、覆盖缺口。定期执行或手动触发", {}, async () => {
         const result = await auditKnowledge(knowledgeIndex, config);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_knowledge_add: 新增知识条目（默认保存为草稿） ──
@@ -1042,7 +1384,7 @@ export function registerTools(server, deps) {
             auto_enrich: args.auto_enrich,
         }, config);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_knowledge_update: 更新已有知识条目（自动创建备份） ──
@@ -1068,7 +1410,7 @@ export function registerTools(server, deps) {
             await knowledgeIndex.reload();
         }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_resume_workspace: 工作区状态唤醒（解决前端刷新导致UUID丢失） ──
@@ -1104,7 +1446,7 @@ export function registerTools(server, deps) {
             // JobManager advisory — ignore errors
         }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_audit_sample: 从审计池按风险加权抽样生成抽检清单 ──
@@ -1118,7 +1460,7 @@ export function registerTools(server, deps) {
         const seed = args.seed ?? 0;
         const result = sampleAuditItems(items, seed);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_escape_report: 记录逃逸/误伤/工具故障报告 ──
@@ -1157,7 +1499,7 @@ export function registerTools(server, deps) {
         };
         store.append(report);
         return {
-            content: [{ type: "text", text: JSON.stringify({ recorded: true, escape_id: report.escape_id }, null, 2) }],
+            result: { recorded: true, escape_id: report.escape_id },
         };
     });
     // ── sf_capability_update: 根据复盘结果更新 Capability Registry ──
@@ -1188,7 +1530,7 @@ export function registerTools(server, deps) {
             confirm: args.confirm,
         }, currentState, cap?.id ?? null, escapeReports);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            result: result,
         };
     });
     // ── sf_governance_report: 治理健康报告 ──
@@ -1213,9 +1555,81 @@ export function registerTools(server, deps) {
         });
         // Generate sample decisions for sampled_count
         const sampleResult = sampleAuditItems(auditItems, seed);
-        const report = generateGovernanceReport(auditStats, auditItems, escapeReports, escapeStats, decisions, new Date(), sampleResult.decisions);
+        // Dual-layer mechanism findings 
+        const dlFindings = validateMechanismLayerMaps();
+        const dlMechanismCount = listMechanismLayerMaps().length;
+        // Collect artifact records from recent tasks 
+        const recentTasks = await taskContext.listRecent(20);
+        const artifacts = [];
+        for (const t of recentTasks) {
+            const tCtx = await taskContext.load(t.task_id);
+            if (tCtx?.artifact_output)
+                artifacts.push(tCtx.artifact_output);
+        }
+        // Collect config resolution reports — use shared function for real data 
+        let configReports = [];
+        let configEntries = [];
+        try {
+            const resolved = await resolveCurrentProjectConfigReports(projectPath);
+            configReports = resolved.reports;
+            configEntries = resolved.entries;
+        }
+        catch (e) {
+            console.error(`[soloForge] 配置报告解析失败: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        // Also include reports from recent task contexts
+        for (const t of recentTasks) {
+            const tCtx = await taskContext.load(t.task_id);
+            if (tCtx?.expansion?.config_resolution_reports) {
+                configReports.push(...tCtx.expansion.config_resolution_reports);
+            }
+        }
+        const report = generateGovernanceReport(auditStats, auditItems, escapeReports, escapeStats, decisions, new Date(), sampleResult.decisions, dlFindings, dlMechanismCount, artifacts.length > 0 ? artifacts : undefined, configReports.length > 0 ? configReports : undefined, configEntries.length > 0 ? configEntries : undefined);
+        return {
+            result: report,
+        };
+    });
+    // ── sf_audit_integration: 主链路集成审计 ──
+    const AuditIntegrationSchema = {
+        changed_files: z.array(z.string()).optional().describe("只审计指定的变更文件列表"),
+        json_output: z.boolean().optional().describe("以 JSON 格式输出（默认为人类可读文本）"),
+    };
+    registerSafeTool("sf_audit_integration", "审计生产代码的主链路集成状态，检测孤岛模块（只被测试导入、无生产代码调用的模块）", AuditIntegrationSchema, async (args) => {
+        const projectPath = config._projectPath || process.cwd();
+        // Use scope-aware production file collection (supports multi-repo, multi-lang)
+        const { collectAllProductionFiles } = await import("../../engine/main_path_integration_contract.js");
+        const allProdFiles = collectAllProductionFiles(projectPath, config);
+        if (allProdFiles.length === 0) {
+            return {
+                result: { error: "未找到生产源文件" },
+            };
+        }
+        const targetFiles = args.changed_files
+            ? allProdFiles.filter((rel) => args.changed_files.some((cf) => rel === cf || rel.startsWith(cf.replace(/\.(ts|tsx|js|jsx|java|kt|go|py)$/, ""))))
+            : allProdFiles;
+        const contracts = buildMainPathIntegrationContracts(projectPath, targetFiles, config);
+        const report = auditIntegration(contracts);
+        if (args.json_output) {
+            return {
+                result: report,
+            };
+        }
+        const lines = [];
+        lines.push("主链路集成审计报告");
+        lines.push(`受检模块: ${targetFiles.length} | 孤岛: ${report.orphan_modules.length} | 仅测试: ${report.test_only_modules.length} | 仅注册: ${report.registry_only_modules.length}`);
+        lines.push("");
+        for (const finding of report.findings) {
+            const icon = finding.severity === "hard_fail" ? "X" : finding.severity === "warning" ? "~" : "i";
+            lines.push(`${icon} ${finding.module_path}: ${finding.reason}`);
+            if (finding.recommended_action) {
+                lines.push(`  -> ${finding.recommended_action}`);
+            }
+        }
+        if (report.findings.length === 0) {
+            lines.push("所有受检模块已通过集成检查。");
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(report, null, 2) }],
+            result: { text: lines.join("\n") },
         };
     });
 }