soloforge 1.2.1 → 1.2.3

package/dist/adapters/claude_code/tools.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import path from "node:path";
+import fss from "node:fs";
 import { classify } from "../../engine/classifier.js";
 import { expand } from "../../engine/intent_expander.js";
 import { generateVerifyCommands } from "../../engine/verifier.js";
@@ -18,6 +20,7 @@ import { auditKnowledge, addKnowledge, updateKnowledge } from "../../engine/know
 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 { analyzeMigration } from "../../engine/migration_guard.js";
 import { generateTestGuide } from "../../engine/test_generator.js";
 import { analyzeTestQuality } from "../../engine/test_quality.js";
@@ -25,6 +28,17 @@ import { scanDependencies } from "../../engine/dependency_scanner.js";
 import { generateDebtReport } from "../../engine/debt_reporter.js";
 import { exploreSolutions } from "../../engine/exploration.js";
 import { scanAndResume } from "../../engine/workspace_resumer.js";
+import { LLMGateway } from "../../engine/llm_gateway.js";
+import { IOController } from "../../engine/io_controller.js";
+import { getSummary as getCapabilitySummary, getAllCapabilities } from "../../engine/capability_registry.js";
+import { validateDecisionOutput } from "../../engine/decision_contract.js";
+import { readMapJson, checkAnchorStaleness, filterRelevantAnchors } from "../../engine/cognitive_anchor.js";
+import { JobManager } from "../../engine/job_manager.js";
+import { AuditPool } from "../../engine/audit_pool.js";
+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";
 // ── Zod Schema 定义 ──
 const ClassifySchema = {
     intent: z.string().describe("开发者意图描述"),
@@ -51,6 +65,8 @@ const LearnSchema = {
 const StatusSchema = {
     task_id: z.string().optional().describe("任务 ID（不传则查当前任务）"),
     action: z.enum(["current", "recent", "resume", "cancel"]).optional().describe("操作类型"),
+    job_id: z.string().optional().describe("Job ID（用于 job_status / job_resume / job_cancel）"),
+    job_action: z.enum(["job_status", "job_resume", "job_cancel"]).optional().describe("Job 操作: 查询状态、从 checkpoint 恢复、取消 job（advisory）"),
 };
 const PlanSchema = {
     task_id: z.string().describe("sf_classify 返回的任务 ID"),
@@ -126,14 +142,17 @@ const ExploreSchema = {
  *              sf_deliver、sf_coord_check、sf_team_status、sf_contract_check、
  *              sf_onboard、sf_feasibility_check、sf_debug、sf_observability、
  *              sf_migration_check、sf_test_guide、sf_test_quality、sf_dependency_scan、
- *              sf_debt_report，以及条件注册的 sf_knowledge_audit/add/update。
+ *              sf_debt_report、sf_explore、sf_knowledge_audit/add/update、sf_resume_workspace。
  * @param server - MCP 服务器实例
  * @param deps - SoloForge 核心依赖项
- * @param options - 注册选项（控制自维护工具是否注册）
  */
-export function registerTools(server, deps, options) {
+export function registerTools(server, deps) {
     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);
     // 统一错误处理包装器，捕获工具执行中的异常并返回结构化错误响应
     function registerSafeTool(name, desc, schema, handler) {
         server.tool(name, desc, schema, async (args) => {
@@ -148,6 +167,58 @@ export function registerTools(server, deps, options) {
             }
         });
     }
+    // 加载认知锚点上下文 — 必须提供相关性参数，禁止全量加载
+    function loadRelevantAnchors(query) {
+        const stateDir = taskContext.getStateDir();
+        const mapPath = path.join(stateDir, "cognitive.map.json");
+        const mapData = 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" && fss.existsSync(path.join(projectPath, ref.ref))) {
+                        existingFiles.add(ref.ref);
+                    }
+                }
+            }
+        }
+        catch { /* ignore */ }
+        const checked = checkAnchorStaleness(mapData.anchors, existingFiles);
+        // 必须有 module 或 file_paths，否则不返回任何锚点（禁止全量加载）
+        if (!query.module && (!query.file_paths || query.file_paths.length === 0))
+            return undefined;
+        // Collect anchors matching ANY of the provided file_paths or module
+        const seen = new Set();
+        const relevant = [];
+        if (query.module) {
+            for (const a of 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 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,
+        }));
+    }
     // ── sf_classify: 意图分类入口，创建任务上下文并返回分类结果 ──
     registerSafeTool("sf_classify", "分析开发者意图，返回任务类型、风险、复杂度和执行策略", ClassifySchema, async (args) => {
         // 检查是否存在进行中的任务
@@ -173,8 +244,9 @@ export function registerTools(server, deps, options) {
         const classification = classify(input);
         // 存储分类结果
         await taskContext.setClassification(ctx.task_id, classification);
-        // 转换到膨胀阶段
-        await taskContext.updateStatus(ctx.task_id, "expanding");
+        if (classification.strategy === "skip_soloForge") {
+            await taskContext.updateStatus(ctx.task_id, "done");
+        }
         return {
             content: [{
                     type: "text",
@@ -194,6 +266,16 @@ export function registerTools(server, deps, options) {
                 isError: true,
             };
         }
+        // 状态守卫：classifying → expanding 或允许 expanding 恢复（中断重试）
+        if (ctx.status === "classifying") {
+            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,
+            };
+        }
         // 构建计划上下文（如果存在计划）
         let planContext;
         if (ctx.planning && ctx.planning.sub_tasks.length > 0 && ctx.planning.current_step_index < ctx.planning.sub_tasks.length) {
@@ -215,24 +297,93 @@ export function registerTools(server, deps, options) {
             }
             planContext = { current_step: currentStep, previous_outputs: previousOutputs };
         }
-        const expansion = await expand({
-            intent: ctx.intent,
-            classification: ctx.classification,
-            projectPath,
-            config,
-            knowledgeIndex,
-            clarificationAnswers: args.clarification_answers,
-            plan_context: planContext,
-        });
+        // H1: Token 预算检查 — advisory 模式，仅警告不阻断
+        gateway.beginTask(args.task_id);
+        let h1Warning;
+        try {
+            const gateResult = gateway.request("solution_brainstorm");
+            if (!gateResult.allowed) {
+                h1Warning = { warning: `H1 advisory: ${gateResult.reason}`, budget_remaining: gateResult.remaining_budget };
+            }
+        }
+        catch (e) {
+            h1Warning = { warning: `H1 advisory: ${e.message}`, budget_remaining: 0 };
+        }
+        // H4: advisory-only — 不获取持久锁，仅检查当前锁定状态
+        let h4LockWarning;
+        const lockStatus = await ioController.isLocked();
+        if (lockStatus.locked && lockStatus.task_id !== args.task_id) {
+            h4LockWarning = `H4 advisory: 工作区已被任务 ${lockStatus.task_id} 锁定（${lockStatus.reason ?? "未知"}），当前 H4 未进入强制层`;
+        }
+        let expansion;
+        try {
+            expansion = await expand({
+                intent: ctx.intent,
+                classification: ctx.classification,
+                projectPath,
+                config,
+                knowledgeIndex,
+                clarificationAnswers: args.clarification_answers,
+                plan_context: planContext,
+            });
+        }
+        catch (expandErr) {
+            // 尝试回退到 failed 状态，避免任务停留在 expanding
+            try {
+                await taskContext.updateStatus(args.task_id, "failed");
+            }
+            catch {
+                // 状态转换非法（如已非 expanding），忽略
+            }
+            throw expandErr;
+        }
+        finally {
+            if (!h1Warning)
+                gateway.completeOperation();
+            gateway.endTask();
+        }
         expansion.task_id = args.task_id;
+        // 注入 H1/H4 advisory warnings
+        const advisories = {};
+        if (h1Warning)
+            advisories.h1_advisory = h1Warning;
+        if (h4LockWarning)
+            advisories.h4_advisory = h4LockWarning;
+        // 决策契约 advisory: 校验 expand 输出是否包含默认决策字段
+        const decisionContract = validateDecisionOutput(expansion);
+        if (!decisionContract.passed) {
+            advisories.decision_contract_advisory = decisionContract.advisory;
+        }
         // 存储膨胀结果
-        await taskContext.setExpansion(args.task_id, expansion);
+        try {
+            await taskContext.setExpansion(args.task_id, expansion);
+        }
+        catch (setErr) {
+            try {
+                await taskContext.updateStatus(args.task_id, "failed");
+            }
+            catch {
+                // 状态转换非法，忽略
+            }
+            throw setErr;
+        }
         // 转换到执行阶段
-        await taskContext.updateStatus(args.task_id, "executing");
+        try {
+            await taskContext.updateStatus(args.task_id, "executing");
+        }
+        catch (updateErr) {
+            try {
+                await taskContext.updateStatus(args.task_id, "failed");
+            }
+            catch {
+                // 状态转换非法，忽略
+            }
+            throw updateErr;
+        }
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify(expansion, null, 2),
+                    text: JSON.stringify(Object.keys(advisories).length > 0 ? { ...expansion, advisories } : expansion, null, 2),
                 }],
         };
     });
@@ -245,9 +396,21 @@ export function registerTools(server, deps, options) {
                 isError: true,
             };
         }
+        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,
+            };
+        }
         const acceptanceItems = ctx.expansion
             ? [...ctx.expansion.acceptance.automated, ...ctx.expansion.acceptance.manual]
             : [];
+        // H4: 工作区完整性检查 — advisory 模式，仅警告不阻断
+        const integrity = await ioController.verify();
+        const h4Warning = !integrity.clean
+            ? { warning: `H4 advisory: ${integrity.message}`, dirty_files: integrity.dirty_files }
+            : undefined;
         const verifyResult = generateVerifyCommands(config, args.changed_files, acceptanceItems);
         verifyResult.task_id = args.task_id;
         // 记录变更文件
@@ -256,10 +419,17 @@ export function registerTools(server, deps, options) {
         await taskContext.updateStatus(args.task_id, "verifying");
         // 存储验证结果
         await taskContext.setVerification(args.task_id, verifyResult);
+        // 认知锚点上下文回放（按变更文件相关性）
+        const verifyAnchors = loadRelevantAnchors({ file_paths: args.changed_files });
+        const verifyExtras = {};
+        if (h4Warning)
+            verifyExtras.h4_advisory = h4Warning;
+        if (verifyAnchors && verifyAnchors.length > 0)
+            verifyExtras.cognitive_anchors = verifyAnchors;
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify(verifyResult, null, 2),
+                    text: JSON.stringify(Object.keys(verifyExtras).length > 0 ? { ...verifyResult, ...verifyExtras } : verifyResult, null, 2),
                 }],
         };
     });
@@ -272,6 +442,13 @@ export function registerTools(server, deps, options) {
                 isError: true,
             };
         }
+        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,
+            };
+        }
         // 如适用，记录失败
         if (args.result === "failure" && args.failure_type) {
             await taskContext.setExecution(args.task_id, [], {
@@ -315,6 +492,64 @@ export function registerTools(server, deps, options) {
     // ── sf_status: 任务状态查询（current/recent/resume/cancel） ──
     registerSafeTool("sf_status", "查询当前任务状态、列出近期任务、恢复中断任务或取消任务", StatusSchema, async (args) => {
         const action = args.action || "current";
+        // Job actions — advisory, independent of task actions
+        if (args.job_action) {
+            if (!args.job_id) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: "job 操作需要 job_id" }) }],
+                    isError: true,
+                };
+            }
+            const jm = new JobManager(taskContext.getStateDir());
+            const taskId = args.task_id ?? await jm.resolveTaskId(args.job_id) ?? "";
+            if (args.job_action === "job_status") {
+                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,
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ job: status }, null, 2) }],
+                };
+            }
+            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,
+                    };
+                }
+                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),
+                        }],
+                };
+            }
+            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,
+                            }),
+                        }],
+                };
+            }
+        }
         switch (action) {
             case "current": {
                 const ctx = args.task_id
@@ -345,6 +580,24 @@ export function registerTools(server, deps, options) {
                     result.changed_files = ctx.execution.changed_files;
                     result.attempt_count = ctx.execution.attempt_count;
                 }
+                // JobManager advisory: 查询关联 job 状态
+                try {
+                    const jm = new JobManager(taskContext.getStateDir());
+                    const activeJobs = await jm.listActiveJobs();
+                    const relatedJob = activeJobs.find((j) => j.task_id === ctx.task_id);
+                    if (relatedJob) {
+                        result.job = {
+                            job_id: relatedJob.job_id,
+                            phase: relatedJob.current_phase,
+                            checkpoint_count: relatedJob.checkpoint_count,
+                            is_alive: relatedJob.is_alive,
+                            latest_anchor_summary: relatedJob.latest_anchor?.summary,
+                        };
+                    }
+                }
+                catch {
+                    // JobManager advisory — ignore errors
+                }
                 return {
                     content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
                 };
@@ -392,6 +645,9 @@ export function registerTools(server, deps, options) {
                                     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),
                         }],
                 };
@@ -504,8 +760,14 @@ export function registerTools(server, deps, options) {
             projectPath,
         });
         result.task_id = args.task_id;
+        // 决策契约 advisory: 校验 analyze 输出
+        const decisionContract = validateDecisionOutput(result);
+        const advisoryExtras = {};
+        if (!decisionContract.passed) {
+            advisoryExtras.decision_contract_advisory = decisionContract.advisory;
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(Object.keys(advisoryExtras).length > 0 ? { ...result, ...advisoryExtras } : result, null, 2) }],
         };
     });
     // ── sf_review: 代码审查（质量、安全、性能、技术债务） ──
@@ -529,8 +791,14 @@ export function registerTools(server, deps, options) {
         }, tracker);
         result.task_id = args.task_id;
         await taskContext.setCodeReview(args.task_id, result);
+        // 决策契约 advisory: 校验 review 输出
+        const decisionContract = validateDecisionOutput(result);
+        const reviewExtras = {};
+        if (!decisionContract.passed) {
+            reviewExtras.decision_contract_advisory = decisionContract.advisory;
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(Object.keys(reviewExtras).length > 0 ? { ...result, ...reviewExtras } : result, null, 2) }],
         };
     });
     // ── sf_scaffold: 生成标准化代码骨架 ──
@@ -574,6 +842,11 @@ export function registerTools(server, deps, options) {
                 isError: true,
             };
         }
+        // H4: 交付前工作区完整性检查 — advisory 模式，仅警告不阻断
+        const deliverIntegrity = await ioController.verify();
+        const h4DeliverWarning = !deliverIntegrity.clean
+            ? { warning: `H4 advisory: ${deliverIntegrity.message}`, dirty_files: deliverIntegrity.dirty_files }
+            : undefined;
         const result = await deliver({
             taskContext: ctx,
             config,
@@ -585,7 +858,10 @@ export function registerTools(server, deps, options) {
         });
         await taskContext.setDelivery(args.task_id, result);
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(h4DeliverWarning ? { ...result, h4_advisory: h4DeliverWarning } : result, null, 2),
+                }],
         };
     });
     // ── sf_coord_check: 预测性冲突检测和跨仓库协调 ──
@@ -670,11 +946,13 @@ export function registerTools(server, deps, options) {
         };
     });
     // ── sf_observability: 系统可观测和运行报告 ──
-    registerSafeTool("sf_observability", "系统可观测：运行指标、成本估算、告警检测、周期报告", ObservabilitySchema, async (args) => {
+    registerSafeTool("sf_observability", "系统可观测：运行指标、成本估算、告警检测、能力状态、周期报告", ObservabilitySchema, async (args) => {
         const stateDir = taskContext.getStateDir();
         const result = await generateReport(stateDir, args.period_days);
+        const capability = getCapabilitySummary();
+        const output = { ...result, capability };
         return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
         };
     });
     // ── sf_migration_check: 数据库迁移安全性分析 ──
@@ -726,76 +1004,219 @@ export function registerTools(server, deps, options) {
             classification,
             knowledgeIndex,
         });
+        // 决策契约 advisory: sf_explore 应始终通过（10 字段已内置）
+        const decisionContract = validateDecisionOutput(result);
+        const exploreExtras = {};
+        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) }],
+        };
+    });
+    // ── sf_knowledge_audit: 知识库健康审计 ──
+    registerSafeTool("sf_knowledge_audit", "审计知识库：识别过时条目、重复触发词、格式缺失、覆盖缺口。定期执行或手动触发", {}, async () => {
+        const result = await auditKnowledge(knowledgeIndex, config);
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── 自维护工具（仅在 SoloForge 自身项目中注册） ──
-    if (options?.isSelfProject) {
-        // ── sf_knowledge_audit: 知识库健康审计 ──
-        registerSafeTool("sf_knowledge_audit", "审计知识库：识别过时条目、重复触发词、格式缺失、覆盖缺口。定期执行或手动触发", {}, async () => {
-            const result = await auditKnowledge(knowledgeIndex, config);
-            return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            };
-        });
-        // ── sf_knowledge_add: 新增知识条目（默认保存为草稿） ──
-        const KnowledgeAddSchema = {
-            title: z.string().describe("知识条目标题（英文 kebab-case，如 payment-rules）"),
-            type: z.enum(["pattern", "procedure", "pipeline_procedure", "domain", "acceptance_template", "review_rule"]).describe("知识类型"),
-            scope: z.array(z.string()).describe("适用范围（如 [backend]、[frontend]、[backend, frontend]）"),
-            when_triggers: z.string().describe("触发关键词（逗号分隔）"),
-            decision_rules: z.string().optional().describe("决策规则（每行一条）"),
-            save_to_drafts: z.boolean().optional().describe("是否保存为草稿（默认 true，需人工 review 后移入正式目录）"),
-            auto_enrich: z.boolean().optional().describe("是否返回行业最佳实践探索指引（默认 true，宿主 AI 将自动执行探索并填充内容）"),
-        };
-        registerSafeTool("sf_knowledge_add", "新增知识条目。默认保存为草稿到 .soloforge/knowledge/drafts/，人工确认后移入正式目录", KnowledgeAddSchema, async (args) => {
-            const result = await addKnowledge({
-                title: args.title,
-                type: args.type,
-                scope: args.scope,
+    // ── sf_knowledge_add: 新增知识条目（默认保存为草稿） ──
+    const KnowledgeAddSchema = {
+        title: z.string().describe("知识条目标题（英文 kebab-case，如 payment-rules）"),
+        type: z.enum(["pattern", "procedure", "pipeline_procedure", "domain", "acceptance_template", "review_rule"]).describe("知识类型"),
+        scope: z.array(z.string()).describe("适用范围（如 [backend]、[frontend]、[backend, frontend]）"),
+        when_triggers: z.string().describe("触发关键词（逗号分隔）"),
+        decision_rules: z.string().optional().describe("决策规则（每行一条）"),
+        save_to_drafts: z.boolean().optional().describe("是否保存为草稿（默认 true，需人工 review 后移入正式目录）"),
+        auto_enrich: z.boolean().optional().describe("是否返回行业最佳实践探索指引（默认 true，宿主 AI 将自动执行探索并填充内容）"),
+    };
+    registerSafeTool("sf_knowledge_add", "新增知识条目。默认保存为草稿到 .soloforge/knowledge/drafts/，人工确认后移入正式目录", KnowledgeAddSchema, async (args) => {
+        const result = await addKnowledge({
+            title: args.title,
+            type: args.type,
+            scope: args.scope,
+            when_triggers: args.when_triggers,
+            decision_rules: args.decision_rules,
+            save_to_drafts: args.save_to_drafts,
+            auto_enrich: args.auto_enrich,
+        }, config);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_knowledge_update: 更新已有知识条目（自动创建备份） ──
+    const KnowledgeUpdateSchema = {
+        entry_name: z.string().describe("要更新的知识条目名称（如 payment-rules）"),
+        when_triggers: z.string().optional().describe("新的触发关键词（替换现有）"),
+        add_decision_rules: z.array(z.string()).optional().describe("追加的决策规则"),
+        add_acceptance_criteria: z.array(z.string()).optional().describe("追加的验收项"),
+        status: z.enum(["active", "deprecated"]).optional().describe("更新条目状态"),
+    };
+    registerSafeTool("sf_knowledge_update", "更新已有知识条目：追加规则、更新触发词、标记废弃。自动创建备份", KnowledgeUpdateSchema, async (args) => {
+        const result = await updateKnowledge({
+            entry_name: args.entry_name,
+            updates: {
                 when_triggers: args.when_triggers,
-                decision_rules: args.decision_rules,
-                save_to_drafts: args.save_to_drafts,
-                auto_enrich: args.auto_enrich,
-            }, config);
-            return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            };
-        });
-        // ── sf_knowledge_update: 更新已有知识条目（自动创建备份） ──
-        const KnowledgeUpdateSchema = {
-            entry_name: z.string().describe("要更新的知识条目名称（如 payment-rules）"),
-            when_triggers: z.string().optional().describe("新的触发关键词（替换现有）"),
-            add_decision_rules: z.array(z.string()).optional().describe("追加的决策规则"),
-            add_acceptance_criteria: z.array(z.string()).optional().describe("追加的验收项"),
-            status: z.enum(["active", "deprecated"]).optional().describe("更新条目状态"),
-        };
-        registerSafeTool("sf_knowledge_update", "更新已有知识条目：追加规则、更新触发词、标记废弃。自动创建备份", KnowledgeUpdateSchema, async (args) => {
-            const result = await updateKnowledge({
-                entry_name: args.entry_name,
-                updates: {
-                    when_triggers: args.when_triggers,
-                    add_decision_rules: args.add_decision_rules,
-                    add_acceptance_criteria: args.add_acceptance_criteria,
-                    status: args.status,
-                },
-            }, knowledgeIndex, config);
-            // 重载知识索引
-            if (result.success) {
-                await knowledgeIndex.reload();
+                add_decision_rules: args.add_decision_rules,
+                add_acceptance_criteria: args.add_acceptance_criteria,
+                status: args.status,
+            },
+        }, knowledgeIndex, config);
+        // 重载知识索引
+        if (result.success) {
+            await knowledgeIndex.reload();
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_resume_workspace: 工作区状态唤醒（解决前端刷新导致UUID丢失） ──
+    registerSafeTool("sf_resume_workspace", "扫描 .soloforge/state/ 目录，恢复中断工单并播报当前进度。新会话启动时必须优先调用", {}, async () => {
+        const result = await scanAndResume(taskContext);
+        // 认知锚点：按恢复任务的 changed_files 相关性加载，禁止全量
+        if (result.task) {
+            const ctx = await taskContext.load(result.task.task_id);
+            const changedFiles = ctx?.execution?.changed_files;
+            if (changedFiles && changedFiles.length > 0) {
+                const anchors = loadRelevantAnchors({ file_paths: changedFiles });
+                if (anchors && anchors.length > 0) {
+                    result.cognitive_anchors = anchors;
+                }
             }
-            return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            };
-        });
-        // ── sf_resume_workspace: 工作区状态唤醒（解决前端刷新导致UUID丢失） ──
-        registerSafeTool("sf_resume_workspace", "扫描 .soloforge/state/ 目录，恢复中断工单并播报当前进度。新会话启动时必须优先调用", {}, async () => {
-            const result = await scanAndResume(taskContext);
-            return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-            };
+        }
+        // JobManager advisory: 查询活跃 jobs
+        try {
+            const jm = new JobManager(taskContext.getStateDir());
+            const activeJobs = await jm.listActiveJobs();
+            if (activeJobs.length > 0) {
+                result.active_jobs = activeJobs.map((j) => ({
+                    job_id: j.job_id,
+                    task_id: j.task_id,
+                    phase: j.current_phase,
+                    is_alive: j.is_alive,
+                    latest_anchor_summary: j.latest_anchor?.summary,
+                    checkpoint_count: j.checkpoint_count,
+                }));
+            }
+        }
+        catch {
+            // JobManager advisory — ignore errors
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_audit_sample: 从审计池按风险加权抽样生成抽检清单 ──
+    const AuditSampleSchema = {
+        seed: z.number().optional().describe("抽样种子（默认 0，同种子可复现）"),
+    };
+    registerSafeTool("sf_audit_sample", "从审计池按风险加权抽样，生成抽检清单（SamplingDecision 列表）。只读，不落盘，不生成逃逸报告，不改能力状态", AuditSampleSchema, async (args) => {
+        const stateDir = taskContext.getStateDir();
+        const pool = new AuditPool(stateDir);
+        const items = pool.list();
+        const seed = args.seed ?? 0;
+        const result = sampleAuditItems(items, seed);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_escape_report: 记录逃逸/误伤/工具故障报告 ──
+    const EscapeReportSchema = {
+        escape_id: z.string().describe("逃逸报告唯一 ID"),
+        task_id: z.string().describe("关联任务 ID"),
+        policy_id: z.string().describe("关联能力 policy ID"),
+        failure_type: z.enum(["rule_gap", "weak_test", "bad_evidence", "ai_escape", "human_miss", "tool_bug", "false_positive"]).describe("失败类型"),
+        expected_guard: z.string().describe("期望的守卫行为"),
+        actual_escape: z.string().describe("实际的逃逸行为"),
+        evidence: z.string().describe("证据"),
+        root_cause: z.string().describe("根因分析"),
+        fix_required: z.string().describe("修复要求"),
+        owner: z.string().describe("负责人"),
+        due_date: z.string().describe("修复截止日期"),
+        capability_action: z.enum(["keep", "downgrade", "disable", "promote_blocked"]).describe("建议的能力动作"),
+        created_at: z.string().optional().describe("报告时间（ISO，默认当前时间）"),
+    };
+    registerSafeTool("sf_escape_report", "记录逃逸、误伤或工具故障报告。只落盘记录，不自动降级，不改能力状态", EscapeReportSchema, async (args) => {
+        const stateDir = taskContext.getStateDir();
+        const store = new EscapeReportStore(stateDir);
+        const report = {
+            escape_id: args.escape_id,
+            task_id: args.task_id,
+            policy_id: args.policy_id,
+            failure_type: args.failure_type,
+            expected_guard: args.expected_guard,
+            actual_escape: args.actual_escape,
+            evidence: args.evidence,
+            root_cause: args.root_cause,
+            fix_required: args.fix_required,
+            owner: args.owner,
+            due_date: args.due_date,
+            capability_action: args.capability_action,
+            created_at: args.created_at ?? new Date().toISOString(),
+        };
+        store.append(report);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ recorded: true, escape_id: report.escape_id }, null, 2) }],
+        };
+    });
+    // ── sf_capability_update: 根据复盘结果更新 Capability Registry ──
+    const CapabilityUpdateSchema = {
+        policy_id: z.string().describe("要更新的 policy ID（如 CAP-003）"),
+        target_state: z.enum(["enforced", "advisory", "experimental", "removed"]).describe("目标状态"),
+        reason: z.string().describe("变更原因"),
+        evidence_ids: z.array(z.string()).describe("支撑此变更的 escape report ID 列表"),
+        confirmed_by: z.string().describe("人工确认者标识（如操作者名字）"),
+        dry_run: z.boolean().optional().describe("dry_run 模式：只校验不持久化（默认 false）"),
+        confirm: z.boolean().describe("人工确认标志，必须为 true 才能执行变更"),
+    };
+    registerSafeTool("sf_capability_update", "根据复盘结果更新 Capability Registry 状态。支持 dry_run 校验、证据校验、人工确认。不会自动触发，必须显式调用", CapabilityUpdateSchema, async (args) => {
+        const stateDir = taskContext.getStateDir();
+        const escapeStore = new EscapeReportStore(stateDir);
+        const stateStore = new CapabilityStateStore(stateDir);
+        const escapeReports = escapeStore.list();
+        const capabilities = getAllCapabilities();
+        const cap = capabilities.find((c) => c.policy_id === args.policy_id);
+        const currentState = stateStore.getEffectiveState(args.policy_id, cap?.state ?? "experimental");
+        const result = stateStore.apply({
+            policy_id: args.policy_id,
+            target_state: args.target_state,
+            reason: args.reason,
+            evidence_ids: args.evidence_ids,
+            confirmed_by: args.confirmed_by,
+            dry_run: args.dry_run ?? false,
+            confirm: args.confirm,
+        }, currentState, cap?.id ?? null, escapeReports);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_governance_report: 治理健康报告 ──
+    const GovernanceReportSchema = {
+        seed: z.number().optional().describe("抽样种子（用于计算 sampled_count，默认 0）"),
+    };
+    registerSafeTool("sf_governance_report", "生成治理健康报告：汇总审计池、逃逸报告、能力动作决策。只读，不改状态", GovernanceReportSchema, async (args) => {
+        const stateDir = taskContext.getStateDir();
+        const seed = args.seed ?? 0;
+        const pool = new AuditPool(stateDir);
+        const escapeStore = new EscapeReportStore(stateDir);
+        const auditItems = pool.list();
+        const auditStats = pool.stats();
+        const escapeReports = escapeStore.list();
+        const escapeStats = escapeStore.stats();
+        // Generate action decisions for all capabilities (using effective states)
+        const capabilities = getAllCapabilities();
+        const stateStore = new CapabilityStateStore(stateDir);
+        const decisions = capabilities.map((cap) => {
+            const effectiveState = stateStore.getEffectiveState(cap.policy_id, cap.state);
+            return decideAction(escapeReports, effectiveState, cap.policy_id);
         });
-    } // end isSelfProject guard
+        // Generate sample decisions for sampled_count
+        const sampleResult = sampleAuditItems(auditItems, seed);
+        const report = generateGovernanceReport(auditStats, auditItems, escapeReports, escapeStats, decisions, new Date(), sampleResult.decisions);
+        return {
+            content: [{ type: "text", text: JSON.stringify(report, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=tools.js.map