soloforge 1.2.2 → 1.2.3

package/README.md

@@ -10,14 +10,51 @@ SoloForge 是一个 [MCP (Model Context Protocol)](https://modelcontextprotocol.
 # 全局安装
 npm install -g soloforge
 
-# 或直接使用（不安装）
-npx soloforge init
+# 初始化（默认适配器: Claude Code）
+soloforge init
 
-# 更新到最新版本
+# Trae IDE / Codex App / 全部适配器
+soloforge init --adapter trae
+soloforge init --adapter codex
+soloforge init --adapter all
+
+# 交互式配置（引导输入项目名称、技术栈等）
+soloforge init --interactive
+
+# 指定项目路径
+soloforge init --project-path /path/to/project
+```
+
+`init` 会生成 `.soloforge/config.yaml`、初始化知识模板、并为你的 AI 工具生成适配配置（hooks、规则文件等）。
+
+### 更新与重新生成
+
+SoloForge 更新后，需要重新生成适配器配置以获取最新的 hooks 和规则：
+
+```bash
+# 更新 SoloForge
 npm update -g soloforge
+
+# 重新生成当前适配器的配置（不会覆盖 config.yaml 和已有知识）
+soloforge init                          # Claude Code: .claude/settings.json + CLAUDE.md
+soloforge generate-hooks                # 仅重新生成 hooks
+soloforge generate-claude-md            # 仅重新生成 CLAUDE.md
+soloforge generate-trae                 # 仅重新生成 .trae/ 配置
+soloforge generate-codex                # 仅重新生成 .codex/ 配置 + AGENTS.md
+
+# 查看版本
+soloforge version
 ```
 
-`init` 命令会生成项目配置（`.soloforge/config.yaml`）、初始化知识模板、并为你的 AI 工具生成适配配置。
+### 日常命令
+
+```bash
+# 验证配置和知识文件
+soloforge validate
+
+# 查看当前项目状态
+soloforge status
+```
 
 ## 工作原理
 
@@ -28,9 +65,9 @@ SoloForge 以 MCP Server（stdio 传输）运行。AI 助手在开发过程中
                                        ← 知识、规则、模板
 ```
 
-SoloForge **零 AI/LLM 依赖**。所有智能来自宿主 AI，SoloForge 提供结构、规则和知识。
+SoloForge 引擎不直接调用 LLM API，由宿主 AI 中转。所有智能来自宿主 AI（Claude Code、Cursor、Trae），SoloForge 提供结构、规则和知识。
 
-## MCP 工具（27 个）
+## MCP 工具（32 个）
 
 ### 核心管线（Phase 1）
 
@@ -62,7 +99,7 @@ SoloForge **零 AI/LLM 依赖**。所有智能来自宿主 AI，SoloForge 提供
 | `sf_contract_check` | 检测接口契约的破坏性变更 |
 | `sf_onboard` | 引导式入职：项目概览 → 代码导览 → 首任务 |
 
-### 自维护（仅 SoloForge 自身项目）
+### 知识维护
 
 | 工具 | 说明 |
 |------|------|
@@ -88,18 +125,27 @@ SoloForge **零 AI/LLM 依赖**。所有智能来自宿主 AI，SoloForge 提供
 | `sf_dependency_scan` | 扫描依赖漏洞，支持 npm/maven/gradle |
 | `sf_debt_report` | 技术债务聚合报告：分类、趋势、优先级 |
 
+### 治理闭环
+
+| 工具 | 说明 |
+|------|------|
+| `sf_audit_sample` | 按风险加权抽样，critical 100% 抽中 |
+| `sf_escape_report` | 记录逃逸/误伤/工具故障 |
+| `sf_governance_report` | 汇总治理健康报告 |
+| `sf_capability_update` | 人工确认后更新能力状态 |
+
 ## 知识体系
 
-SoloForge 内置 **108+ 知识模板**，覆盖 6 种类型：
+SoloForge 内置知识模板（含全局模式），覆盖 6 种类型：
 
-| 类型 | 数量 | 用途 |
-|------|------|------|
-| `pattern` | 50 | 决策规则 + 验收标准 |
-| `procedure` | 24 | 操作流程 + 检查点 |
-| `domain` | 9 | 业务规则、约束条件、例外情况 |
-| `acceptance_template` | 19 | 质量门禁 + 自动化检查命令 |
-| `review_rule` | 6 | 正则驱动的代码审查规则 |
-| `pipeline_procedure` | — | CI/CD 流水线阶段定义 |
+| 类型 | 用途 |
+|------|------|
+| `pattern` | 决策规则 + 验收标准 |
+| `procedure` | 操作流程 + 检查点 |
+| `domain` | 业务规则、约束条件、例外情况 |
+| `acceptance_template` | 质量门禁 + 自动化检查命令 |
+| `review_rule` | 正则驱动的代码审查规则 |
+| `pipeline_procedure` | CI/CD 流水线阶段定义 |
 
 知识文件采用 Markdown + YAML frontmatter 格式：
 
@@ -163,17 +209,31 @@ scope:
 ```
 知识层                   机制层                      适配层
 +------------------+    +---------------------+    +------------------+
-| 108+ 知识模板     |    | 分类器               |    | Claude Code      |
+| 知识模板          |    | 分类器               |    | Claude Code      |
 | 6 种知识类型      |    | 意图膨胀器           |    | Cursor           |
 | 产品 Profile     |    | 验证器               |    | Trae             |
 |                  |    | 代码审查器           |    | CLI              |
 | 项目专属知识      |    | 任务规划器           |    |                  |
 |                  |    | 脚手架生成器         |    |                  |
 |                  |    | 自动交付             |    |                  |
+|                  |    | 契约治理内核         |    |                  |
 |                  |    | + 20+ 个引擎模块     |    |                  |
 +------------------+    +---------------------+    +------------------+
 ```
 
+## 契约治理内核
+
+SoloForge 的治理能力按四级状态管理，新增治理能力不伪装 hard block：
+
+| 状态 | 含义 |
+|------|------|
+| `enforced` | 强制执行，阻断不合规操作 |
+| `advisory` | 建议性告警，由开发者决策 |
+| `experimental` | 实验性，需晋级计划才能升级 |
+| `removed` | 已移除，不再生效 |
+
+治理闭环：任务完成入池 → 按风险加权抽样 → 逃逸记录 → 治理报告 → 人工确认后状态更新。所有状态变更必须经 `sf_capability_update` + 人工确认，不自动执行。
+
 ## 开发
 
 ```bash
@@ -183,7 +243,7 @@ npm install
 # 构建
 npm run build
 
-# 运行测试（447 个测试）
+# 运行测试（1256 tests / 86 files）
 npm test
 
 # 类型检查

package/dist/adapters/claude_code/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAA+B,MAAM,gBAAgB,CAAC;AACjF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA2BvE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAIzD;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc;IACd,cAAc,EAAE,qBAAqB,CAAC;IACtC,eAAe;IACf,WAAW,EAAE,kBAAkB,CAAC;IAChC,yDAAyD;IACzD,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAwHD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAygC1E"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/tools.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAA+B,MAAM,gBAAgB,CAAC;AACjF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA4BvE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAYzD;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc;IACd,cAAc,EAAE,qBAAqB,CAAC;IACtC,eAAe;IACf,WAAW,EAAE,kBAAkB,CAAC;IAChC,yDAAyD;IACzD,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AA0HD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAg4C1E"}

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";
@@ -27,7 +30,15 @@ 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 } from "../../engine/capability_registry.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("开发者意图描述"),
@@ -54,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"),
@@ -154,6 +167,58 @@ export function registerTools(server, deps) {
             }
         });
     }
+    // 加载认知锚点上下文 — 必须提供相关性参数，禁止全量加载
+    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) => {
         // 检查是否存在进行中的任务
@@ -284,6 +349,11 @@ export function registerTools(server, deps) {
             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;
+        }
         // 存储膨胀结果
         try {
             await taskContext.setExpansion(args.task_id, expansion);
@@ -349,10 +419,17 @@ export function registerTools(server, deps) {
         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(h4Warning ? { ...verifyResult, h4_advisory: h4Warning } : verifyResult, null, 2),
+                    text: JSON.stringify(Object.keys(verifyExtras).length > 0 ? { ...verifyResult, ...verifyExtras } : verifyResult, null, 2),
                 }],
         };
     });
@@ -415,6 +492,64 @@ export function registerTools(server, deps) {
     // ── 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
@@ -445,6 +580,24 @@ export function registerTools(server, deps) {
                     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) }],
                 };
@@ -492,6 +645,9 @@ export function registerTools(server, deps) {
                                     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),
                         }],
                 };
@@ -604,8 +760,14 @@ export function registerTools(server, deps) {
             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: 代码审查（质量、安全、性能、技术债务） ──
@@ -629,8 +791,14 @@ export function registerTools(server, deps) {
         }, 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: 生成标准化代码骨架 ──
@@ -836,8 +1004,14 @@ export function registerTools(server, deps) {
             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(result, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(Object.keys(exploreExtras).length > 0 ? { ...result, ...exploreExtras } : result, null, 2) }],
         };
     });
     // ── sf_knowledge_audit: 知识库健康审计 ──
@@ -900,9 +1074,149 @@ export function registerTools(server, deps) {
     // ── 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;
+                }
+            }
+        }
+        // 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);
+        });
+        // 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