soloforge 1.2.20 → 1.3.1

package/README.md

@@ -63,6 +63,7 @@ soloforge init --adapter all         # 同时生成所有适配器配置
 |------|------|
 | `.soloforge/knowledge/` | 项目知识模板和规则 |
 | `.soloforge/config.yaml` | 可选项目配置，仅在高置信度或手动确认后生成 |
+| `~/.soloforge/patterns/` | 全局默认模板（所有项目共享），init 时自动同步、已有文件不覆盖 |
 | `.claude/settings.json` / `CLAUDE.md` / `.mcp.json` | Claude Code 配置 |
 | `.codex/config.toml` / `.codex/hooks.json` / `AGENTS.md` | Codex App 配置 |
 | `.trae/mcp.json` / `.trae/rules/project_rules.md` | Trae IDE 配置 |
@@ -74,25 +75,118 @@ SoloForge 不会覆盖已有知识文件。重新运行 `soloforge init` 可刷
 ```bash
 soloforge validate          # 检查项目配置和知识文件
 soloforge status            # 查看当前项目状态和配置来源
+soloforge config resolve    # 查看配置解析结果和来源
+soloforge config explain    # 解释某项配置为什么是当前值
 soloforge version           # 查看版本
 ```
 
-更新 SoloForge 后，建议重新生成适配器配置：
+### 状态清理与审计
+
+```bash
+soloforge cleanup --dry-run            # 预览可清理的状态文件
+soloforge cleanup --apply              # 执行清理（默认 dry-run，需显式 --apply）
+soloforge audit-template-mechanisms    # 审计知识资产 schema 完整性
+soloforge audit-design-artifacts       # 审计架构/数据库/API 设计产物包
+soloforge upgrade-design-artifacts     # 预览设计产物升级计划（dry-run）
+soloforge upgrade-design-artifacts --apply --confirm  # 确认后归档旧设计产物并写入升级契约
+```
+
+### 发布自检（SoloForge 维护者）
+
+```bash
+# 发布前必须通过的门禁，普通用户不需要执行
+npm run validate-release
+node dist/bin/soloforge.js validate-release --json
+```
+
+`validate-release` 是 SoloForge 自身的发布门禁，检查构建产物、机制消费、模板完整等长期产品结构。
+
+### 模板与适配器同步
+
+```bash
+soloforge sync-templates                # 预览模板变更（dry-run）
+soloforge sync-templates --apply --confirm  # 应用模板同步
+soloforge sync-adapters                 # 预览适配器同步（dry-run）
+soloforge sync-adapters --apply --confirm   # 应用适配器同步
+soloforge migrate                       # 预览项目迁移（dry-run）
+soloforge migrate --apply --confirm     # 执行项目迁移
+```
+
+**默认安全，写入需确认：**
+
+- `sync-templates` 和 `sync-adapters` 默认只预览，不写任何文件。需要加 `--apply --confirm` 才会实际写入。
+- `migrate` 默认也是 dry-run。只有 `--apply --confirm` 才会写入版本状态和迁移记录，并自动创建备份。
+- 你手动修改过的模板和适配器文件（如 `CLAUDE.md`）不会被静默覆盖——SoloForge 会检测文件是否被用户修改，修改过的文件在同步时自动跳过并报告。
+- 核心知识模板受保护，即使 apply 也不会被自动同步覆盖。
+
+**典型升级流程：**
 
 ```bash
 npm update -g soloforge
 cd /path/to/my-project
-soloforge init
+soloforge sync-templates                # 看看有哪些模板更新
+soloforge sync-templates --apply --confirm  # 确认后应用
+soloforge sync-adapters                 # 看看适配器是否需要更新
+soloforge sync-adapters --apply --confirm   # 确认后应用
+soloforge migrate                       # 看看是否需要迁移
+soloforge migrate --apply --confirm     # 确认后迁移
 ```
 
 ## 使用时你会看到什么
 
 接入成功后，AI 助手会在合适的时候调用 SoloForge 来理解任务、生成执行上下文、给出验证建议和记录任务状态。对你来说，主要变化是：
 
+- **架构设计** — 让 AI 设计架构时，会生成结构化方案（含架构边界、技术栈、模块关系），输出目录会先征求你确认，不会自作主张写到你不想放的位置。
+- **架构决策研讨** — 进入正式架构设计前，AI 会先围绕业务流程、数据架构、安全架构、后端架构、前端架构、基础设施六类决策逐项给出候选方案、推荐理由、风险和需要你确认的结论；六类必要决策未闭合时，不会把草案冒充正式架构文档。
+- **设计产物包** — 架构设计、数据库设计、API 规格不再各自漂移。标准产物包包含 `docs/architecture/00-架构决策记录.md`、`01-架构设计文档.md`、`02-数据库设计文档.md`、`03-API接口规格文档.md`、`99-设计一致性验收报告.md`、`docs/api/openapi.yaml` 和 `db/migrations/` 或 `db/schema/` 下的数据库结构资产。
+- **现有系统新需求** — 在已有项目里开发新功能时，AI 会先分析现有系统现状和差距，再给出实现计划，不会跳过理解直接写代码。
+- **编码任务** — 写代码前会先明确约束和验收项、生成验证/测试计划，再动手实现。编码不是第一步。
+- **可运行项目交付** — 涉及前端/全栈/可运行项目时，交付前会支持本地运行和浏览器验收。验收失败会自动诊断、修复并重测，最终给你一个可以在浏览器打开的本地地址来人工查验。
+- **技术决策** — 高影响技术选型（架构、数据库、框架等）会区分"AI 建议"和"需要你确认的决策"，不会悄悄帮你拍板不可逆的选择。
+- **多方案探索** — 遇到不确定的技术问题时，会先列出多个候选方案、给出权衡分析和推荐，而不是只给一个答案。
+- **路径与平台安全** — 跨平台（macOS/Linux/Windows）路径处理更谨慎，不会意外修改工作区之外的文件。第三方扩展有明确的权限边界。
+- **执行前确认** — 涉及写入、编码、构建、迁移、发布、交付等操作前，AI 会先给出计划或确认项，不会直接动手改。
+- **简单问答** — 提问、闲聊、低风险确认不会触发完整工作流，直接处理，不强行走重流程。
+- **施工指令约束** — AI 写代码前必须先明确目标、范围、非目标和验收标准，不会跳过定义直接动手写实现。
+- **证据驱动** — AI 不得无证据声称项目事实。默认模板和通用规则不算项目证据；架构分析必须有真实代码依据或你的人工确认。
+- **存量设计复验** — 升级 SoloForge 后，已有架构/数据库/API 文档不会被默认信任。运行 `soloforge audit-design-artifacts` 可得到差距报告；需要升级时先 dry-run，再经 `--apply --confirm` 归档旧文件并写入升级契约，修订后的文档必须重新复验。
+- **日志清晰** — 用户可见输出中文优先；JSON 模式（`--json`）输出保持纯 JSON，不混入内部日志。
 - 写代码类任务会更明确 scope、验收项和验证命令。
 - 生成文档、提取说明、分析日志等产物型任务会默认输出到 `.soloforge/output/`，不会默认修改 `src/`。
 - 遇到缺少路径、源码包、日志等必需输入时，会先澄清，而不是猜着执行。
 - 敏感信息、危险命令和高风险交付动作会更保守，需要你确认。
+- AI 给你的反馈会先说结论、必要依据和下一步建议，不展示内部处理流水账。
+
+### 验证与交付
+
+SoloForge 对验证和交付有严格的分层设计：
+
+- **验证计划不等于验证结果**：SoloForge 会生成验证命令（如 `npm test`），但不会自己执行。只有你或 AI 工具实际执行并录入结果后，才被视为已验证。纯计划不等于通过。
+- **未验证不交付**：交付前必须通过真实执行的验证结果。计划阶段的产物、直接构造的通过记录、未执行的验证，都不会触发交付。
+- **证据必须完整**：每条验证结果必须包含完整的执行证据（命令输出哈希、执行时间、唯一证据 ID）。缺少证据或格式不合法的记录会被判定为失败。
+- **交付需要显式触发**：交付就绪检查只判断能不能交付，不会自动执行 commit、push 或创建 PR。交付动作必须由 `sf_deliver` 或你手动触发。
+- **交付指标来自真实数据**：交付质量指标从真实 TaskContext 状态目录聚合，不接受空数组、undefined 或构造的通过样本。验证失败会进入修复/复验闭环，不能只报告不修复。
+
+### 失败处理
+
+当验证或执行失败时：
+
+- **确定性失败不重试**：相同的错误反复出现时，SoloForge 会升级给你处理，不会无限重试。
+- **可修复失败有预算**：重试次数有上限，超预算后停止并升级。
+- **范围不足不越权**：如果失败是因为 scope 不够，SoloForge 会请求扩大范围，不会静默越权写入。
+- **错误信息已脱敏**：失败报告中的敏感信息（密钥、密码、原始输出）会自动脱敏，只保留摘要和哈希。
+
+### 安全护栏
+
+SoloForge 在运行时执行以下强制护栏：
+
+- **只读保护**：被分类为只读的任务（分析、文档生成等）不能修改项目源码。
+- **写入范围保护**：代码修改只能在声明的 scope 路径内进行，超出范围的写入会被阻断。
+- **状态保护**：已失败的任务不能被直接标记为完成，需要先修复并重新验证。
+- **并发保护**：同一个文件范围不会被两个任务同时写入。
+- **隐私保护**：密钥、凭证和个人信息在存储前自动脱敏。
+
+这些护栏不会降级或关闭。如果误判，你可以通过配置覆盖或人工确认解除。
 
 ## 产物输出
 
@@ -172,14 +266,67 @@ AGENTS.md
 
 删除 `CLAUDE.md` 或 `AGENTS.md` 前请确认没有手写内容。
 
+### validate / status 出现 EMFILE 或 too many open files
+
+`soloforge validate` 和 `soloforge status` 是一次性 CLI 命令，知识索引使用 `watch: false`，不会启动长期 watcher。如果出现 `EMFILE`、`too many open files` 或 watch 崩溃，属于异常，请提交 issue 反馈。
+
 ## 本仓库开发
 
+### 日常开发
+
 ```bash
 npm install
+npm run build        # clean build：先删除 dist 再编译，防止 stale 产物进入发布包
+npm test             # 等价于 npm test -- --run
+```
+
+`npm run build` 执行的是 clean build：先 `rm -rf dist`，再 `tsc` 编译。这保证 dist 产物与 src 源码严格一致，不会残留已删除源码对应的旧编译文件。
+
+### 发布前验收
+
+SoloForge 维护者在发布前必须依次执行以下命令，全部通过才能进入 Release Candidate：
+
+```bash
+# 1. 编译（clean build）
 npm run build
-npm test
+
+# 2. 测试类型检查（tsconfig.test.json 编译 tests/**/*.ts）
+npm run lint:tests
+
+# 3. 全量测试
+npm test -- --run
+
+# 4. 发布门禁（文本输出）
+npm run validate-release
+
+# 5. 发布门禁（JSON 输出，必须 passed=true、hard_fail_count=0）
+node dist/bin/soloforge.js validate-release --json
+
+# 6. 用户项目可用性抽查
+REPO_DIR=$(pwd)
+TMPDIR=$(mktemp -d) && cd "$TMPDIR"
+node "$REPO_DIR/dist/bin/soloforge.js" init
+node "$REPO_DIR/dist/bin/soloforge.js" validate
+node "$REPO_DIR/dist/bin/soloforge.js" status
+# 三条命令的 exit code 都必须为 0
+cd "$REPO_DIR"
+
+# 7. 发布包内容验证
+npm --cache /private/tmp/soloforge-npm-cache pack --dry-run --json
+# 必须包含: dist/bin/soloforge.js, dist/index.js, templates/knowledge/, templates/patterns/
+# 不得包含: docs/, tests/, scripts/, dist/engine/batch*
 ```
 
+`npm run lint:tests` 使用 `tsconfig.test.json` 对 `tests/**/*.ts` 做 TypeScript 编译检查。`npm test` 通过不等于测试类型检查通过——vitest 运行时不做完整类型检查，测试代码可能使用旧字段、隐式 any 或错误类型断言而仍然通过。发布前必须同时通过源码编译、测试类型检查、全量测试和 `validate-release`。
+
+<details>
+<summary>内部说明：validate-release 与历史施工回归的区别</summary>
+
+- `npm run validate-release` 是 SoloForge 正式发布门禁，检查构建产物、机制消费、模板完整等长期产品结构。
+- `npm run validate-batch*` 是历史施工回归检查，用于确认早期施工问题修复后没有回归，不代表正式发布通过。该检查由维护者按需执行，不写入普通用户文档。
+
+</details>
+
 ## 技术要求
 
 - Node.js >= 18

package/dist/adapters/claude_code/claude_md.d.ts

@@ -1,7 +1,6 @@
 /**
  * 生成 CLAUDE.md 项目指令文件内容。
- * @param config - 项目配置
- * @returns CLAUDE.md 文件的文本内容
+ * 只记录生成文本实际包含对应内容的资产 trace，trace 含章节 hash 证明。
  */
 export declare function generateClaudeMd(config: import("../../types.js").ProjectConfig): string;
 //# sourceMappingURL=claude_md.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"claude_md.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,gBAAgB,EAAE,aAAa,GAAG,MAAM,CAGvF"}
+{"version":3,"file":"claude_md.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"AA8BA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,gBAAgB,EAAE,aAAa,GAAG,MAAM,CAoBvF"}

package/dist/adapters/claude_code/claude_md.js

@@ -1,11 +1,54 @@
 import { generateWorkflowRules } from "../shared/workflow_template.js";
+import { recordConsumptionTrace, CONSUMER_FIELD_CONTRACTS } from "../../engine/consumption_trace_store.js";
+import { listConsumableAssetsByConsumer } from "../../engine/consumable_asset_registry.js";
+import { debug } from "../../engine/logger.js";
+/** 计算章节内容 hash: 字符数:行数:首尾字符码 */
+function computeSectionHash(text, sectionHeader) {
+    const idx = text.indexOf(sectionHeader);
+    if (idx === -1)
+        return "missing";
+    const nextSection = text.indexOf("\n## ", idx + sectionHeader.length);
+    const sectionContent = nextSection === -1 ? text.substring(idx) : text.substring(idx, nextSection);
+    const lines = sectionContent.split("\n");
+    return `${sectionContent.length}c:${lines.length}l:${sectionContent.charCodeAt(0)}:${sectionContent.charCodeAt(sectionContent.length - 1)}`;
+}
+/** 资产 ID → 章节/hash 级内容检查 */
+const ASSET_CONTENT_CHECKS = {
+    "adapter-workflow-template": (t) => {
+        const hasWorkflow = /^## 强制工作流/m.test(t) && /@sf-hard-rule/.test(t);
+        const hasSteps = /### 步骤 \d+/.test(t);
+        const hash = computeSectionHash(t, "## 强制工作流");
+        return { pass: hasWorkflow && hasSteps, proof: `section=强制工作流 hash=${hash}` };
+    },
+    "adapter-claude-md": (t) => {
+        const hasTitle = /^# SoloForge 集成规则/m.test(t);
+        const hash = computeSectionHash(t, "# SoloForge 集成规则");
+        return { pass: hasTitle, proof: `section=集成规则 hash=${hash}` };
+    },
+};
 /**
  * 生成 CLAUDE.md 项目指令文件内容。
- * @param config - 项目配置
- * @returns CLAUDE.md 文件的文本内容
+ * 只记录生成文本实际包含对应内容的资产 trace，trace 含章节 hash 证明。
  */
 export function generateClaudeMd(config) {
-    console.error("[soloForge] ClaudeMD生成: 开始生成 CLAUDE.md");
-    return generateWorkflowRules(config) + "\n";
+    debug("ClaudeMD生成", "开始生成 CLAUDE.md");
+    const result = generateWorkflowRules(config) + "\n";
+    // 只记录生成文本实际包含对应内容的资产 trace（章节/hash 级验证）
+    const registeredAssets = listConsumableAssetsByConsumer("generateClaudeMd");
+    for (const asset of registeredAssets) {
+        const checker = ASSET_CONTENT_CHECKS[asset.id];
+        const checkResult = checker ? checker(result) : { pass: result.length > 0, proof: `length=${result.length}` };
+        if (checkResult.pass) {
+            recordConsumptionTrace({
+                consumer: "adapter_prompt",
+                asset_id: asset.id,
+                fields_consumed: CONSUMER_FIELD_CONTRACTS.adapter_prompt,
+                matched_reason: `CLAUDE.md content_verified consumed ${asset.id} ${checkResult.proof}`,
+                task_id_or_route: "claude-md",
+                consumed_at: new Date().toISOString(),
+            });
+        }
+    }
+    return result;
 }
 //# sourceMappingURL=claude_md.js.map

package/dist/adapters/claude_code/claude_md.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude_md.js","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA8C;IAC7E,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;IACxD,OAAO,qBAAqB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"claude_md.js","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAsC5C"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAsC5C"}

package/dist/adapters/claude_code/hooks.js

@@ -1,10 +1,11 @@
 export { generateClaudeMd } from "./claude_md.js";
+import { debug } from "../../engine/logger.js";
 /**
  * 生成 Claude Code hooks 配置对象。
  * @returns hooks 配置对象，包含 PreToolUse、PostToolUse 和 UserPromptSubmit 钩子
  */
 export function generateHooksConfig() {
-    console.error("[soloForge] Hooks配置: 生成 hooks 配置");
+    debug("Hooks配置", "生成 hooks 配置");
     return {
         hooks: {
             PreToolUse: [

package/dist/adapters/claude_code/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/adapters/claude_code/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAClD,OAAO;QACL,KAAK,EAAE;YACL,UAAU,EAAE;gBACV;oBACE,OAAO,EAAE,YAAY;oBACrB,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,SAAS;4BACf,OAAO,EAAE,uBAAuB;yBACjC;qBACF;iBACF;aACF;YACD,WAAW,EAAE;gBACX;oBACE,OAAO,EAAE,MAAM;oBACf,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,SAAS;4BACf,OAAO,EAAE,qBAAqB;yBAC/B;qBACF;iBACF;aACF;YACH,kBAAkB,EAAE;gBAClB;oBACE,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,SAAS;4BACf,OAAO,EAAE,sBAAsB;yBAChC;qBACF;iBACF;aACF;SACA;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/adapters/claude_code/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAChC,OAAO;QACL,KAAK,EAAE;YACL,UAAU,EAAE;gBACV;oBACE,OAAO,EAAE,YAAY;oBACrB,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,SAAS;4BACf,OAAO,EAAE,uBAAuB;yBACjC;qBACF;iBACF;aACF;YACD,WAAW,EAAE;gBACX;oBACE,OAAO,EAAE,MAAM;oBACf,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,SAAS;4BACf,OAAO,EAAE,qBAAqB;yBAC/B;qBACF;iBACF;aACF;YACH,kBAAkB,EAAE;gBAClB;oBACE,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,SAAS;4BACf,OAAO,EAAE,sBAAsB;yBAChC;qBACF;iBACF;aACF;SACA;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/claude_code/server.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerTools } from "./tools.js";
 import { readFileSync } from "node:fs";
+import { debug, internalWarn } from "../../engine/logger.js";
 const pkgVersion = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf-8")).version;
 /**
  * 启动 SoloForge MCP 服务器。
@@ -10,7 +11,7 @@ const pkgVersion = JSON.parse(readFileSync(new URL("../../../package.json", impo
  * @param deps - 服务器依赖项（配置、知识索引、任务上下文）
  */
 export async function startServer(deps) {
-    console.error("[soloForge] server: startServer() 开始执行");
+    debug("server", "startServer() 开始执行");
     const { config, knowledgeIndex, taskContext } = deps;
     const server = new McpServer({
         name: "soloforge",
@@ -43,14 +44,14 @@ export async function startServer(deps) {
     });
     // 捕获未处理的同步异常，同步清理后退出（避免异步清理未完成就 exit）
     process.on("uncaughtException", (err) => {
-        console.error("SoloForge 未捕获异常:", err);
+        internalWarn("server", "未捕获异常:", err);
         // 同步清理：不等待 async 操作，直接退出
         process.exitCode = 1;
         process.exit(1);
     });
     // 捕获未处理的 Promise 拒绝，同步清理后退出
     process.on("unhandledRejection", (reason) => {
-        console.error("SoloForge 未处理的 Promise 拒绝:", reason);
+        internalWarn("server", "未处理的 Promise 拒绝:", reason);
         process.exitCode = 1;
         process.exit(1);
     });

package/dist/adapters/claude_code/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/adapters/claude_code/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,UAAU,GAAW,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AAmBxH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAgB;IAC9C,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC1D,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAErD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,UAAU;KACpB,CAAC,CAAC;IAEH,MAAM,aAAa,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC,CAAC;IAErE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,IAAI,YAAY;YAAE,OAAO;QACzB,YAAY,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC;YACH,IAAI,cAAc;gBAAE,MAAM,cAAc,CAAC,KAAK,EAAE,CAAC;YACjD,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;QAC5B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,8BAA8B;IAC9B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,QAAQ,EAAE,CAAC;IACb,CAAC,CAAC,CAAC;IAEH,sCAAsC;IACtC,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;QACtC,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;QACvC,yBAAyB;QACzB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,4BAA4B;IAC5B,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;QAC1C,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,MAAM,CAAC,CAAC;QACpD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/adapters/claude_code/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC7D,MAAM,UAAU,GAAW,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AAmBxH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAgB;IAC9C,KAAK,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;IACxC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAErD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,UAAU;KACpB,CAAC,CAAC;IAEH,MAAM,aAAa,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC,CAAC;IAErE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,IAAI,YAAY;YAAE,OAAO;QACzB,YAAY,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC;YACH,IAAI,cAAc;gBAAE,MAAM,cAAc,CAAC,KAAK,EAAE,CAAC;YACjD,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;QAC5B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,8BAA8B;IAC9B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,QAAQ,EAAE,CAAC;IACb,CAAC,CAAC,CAAC;IAEH,sCAAsC;IACtC,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;QACtC,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;QACtC,yBAAyB;QACzB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,4BAA4B;IAC5B,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;QAC1C,YAAY,CAAC,QAAQ,EAAE,kBAAkB,EAAE,MAAM,CAAC,CAAC;QACnD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

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

@@ -1,8 +1,9 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { ProjectConfig } from "../../types.js";
+import type { ProjectConfig, TaskContext } from "../../types.js";
 import type { KnowledgeIndexManager } from "../../knowledge/index_manager.js";
 import type { LLMGateway } from "../../engine/llm_gateway.js";
 import type { TaskContextManager } from "../../engine/task_context.js";
+import { type SideEffect } from "../../engine/tool_invocation_contract_registry.js";
 /**
  * MCP 工具注册模块。
  * @description 将 SoloForge 的全部功能封装为 MCP 工具，注册到 McpServer 实例。
@@ -37,6 +38,286 @@ export interface SoloForgeDeps {
  * @param server - MCP 服务器实例
  * @param deps - SoloForge 核心依赖项
  */
+/**
+ * Plan Gate 写工具拦截 — 从 registerSafeTool 中间件提取的纯函数。
+ * gate 和外部测试可直接调用，无需 MCP server mock。
+ */
+export declare function checkWriteToolPlanGate(params: {
+    ctx: TaskContext | null;
+    toolName: string;
+    sideEffects: SideEffect[];
+}): {
+    allowed: boolean;
+    diagnostic_code?: string;
+    violation_type?: string;
+    reason?: string;
+};
+/**
+ * 施工指令契约门 — 写操作前检查施工指令完整性。
+ * 问题五十八: 通过引擎模块函数真实消费。
+ * 调用链 1: registerInstructionIssueCandidate（无契约时创建候选 draft）
+ * 调用链 2: enforceInstructionBeforeImplementation → checkInstructionCompleteness → validateInstructionContract
+ */
+export declare function checkInstructionContractGate(params: {
+    ctx: TaskContext | null;
+    toolName: string;
+    sideEffects: SideEffect[];
+    task_id?: string;
+    taskContextMgr?: any;
+}): Promise<{
+    allowed: boolean;
+    diagnostic_code?: string;
+    violation_type?: string;
+    reason?: string;
+    findings?: string[];
+}>;
+/**
+ * 设计产物编码门 — 依赖设计包的任务，在真实复验完成前不得写入业务实现。
+ * 仅阻断文件/配置/外部交付写入；任务状态、设计文档复验和讨论本身仍可推进。
+ */
+export declare function checkDesignArtifactWriteGate(params: {
+    ctx: TaskContext | null;
+    toolName: string;
+    sideEffects: SideEffect[];
+}): {
+    allowed: boolean;
+    diagnostic_code?: string;
+    reason?: string;
+};
+/**
+ * 架构设计门 — 架构设计类任务膨胀前执行 reviewArchitectureDesign。
+ * 问题四十九: Architecture Design Contract enforcement。
+ */
+export declare function checkArchitectureDesignGate(params: {
+    ctx: TaskContext | null;
+    route?: string;
+}): Promise<{
+    allowed: boolean;
+    reason_zh?: string;
+    findings?: string[];
+}>;
+/**
+ * 架构决策研讨门 — 正式架构设计前六域决策必须闭合。
+ * 问题六十一: 与是否存在施工指令契约无关，架构设计路由必经此门。
+ */
+export declare function checkArchitectureDecisionWorkshopGate(params: {
+    ctx: TaskContext;
+    workflowIntent?: string;
+    projectContext?: import("../../engine/architecture_decision_workshop.js").ArchitectureProjectContext;
+}): Promise<{
+    allowed: boolean;
+    findings?: string[];
+    next_domain?: string;
+    contract?: unknown;
+}>;
+/**
+ * 现有系统分析门 — 现有项目编码前必须先做分析。
+ * 问题五十: Existing System Analysis Contract enforcement。
+ */
+export declare function checkExistingSystemAnalysisGate(params: {
+    hasExistingCode: boolean;
+    hasPackageJson: boolean;
+    hasSrcDir: boolean;
+    hasAnalysis: boolean;
+    hasGapAnalysis: boolean;
+}): Promise<{
+    allowed: boolean;
+    reason_zh?: string;
+    missing_analysis?: string[];
+}>;
+/**
+ * 编码就绪门 — 编码前必须有测试计划 + 验收标准。
+ * 问题五十一: Coding Readiness / Test-First enforcement。
+ */
+export declare function checkCodingReadinessGate(params: {
+    ctx: TaskContext | null;
+}): Promise<{
+    allowed: boolean;
+    reason_zh?: string;
+    missing_preconditions?: string[];
+}>;
+/**
+ * 本地验收门 — 前端/全栈交付前必须有本地访问证据。
+ * 问题五十二: Local Docker / Browser Acceptance enforcement。
+ */
+export declare function checkLocalAcceptanceGate(params: {
+    ctx: TaskContext | null;
+    hasFrontend: boolean;
+    hasBackend: boolean;
+    hasDockerCompose: boolean;
+    hasDockerfile: boolean;
+}): Promise<{
+    allowed: boolean;
+    reason_zh?: string;
+    required_but_missing?: string[];
+}>;
+/** 技术选型/架构/数据库/框架/高影响决策 → 需 decision sovereignty gate */
+export declare function requiresDecisionSovereignty(ctx: TaskContext | null, route?: string): boolean;
+/** 多步骤/不确定/高风险任务 → 需 detail discipline gate */
+export declare function requiresDetailDiscipline(ctx: TaskContext | null, route?: string): boolean;
+/** 高影响任务/架构设计/复杂编码/跨模块变更 → 需 first principles gate */
+export declare function requiresFirstPrinciples(ctx: TaskContext | null, route?: string): boolean;
+/** 不确定项/方案选择/多选项 → 需 brainstorm gate */
+export declare function requiresBrainstorm(ctx: TaskContext | null, route?: string): boolean;
+/**
+ * 技术选型决策门 — 高影响技术决策需用户确认。
+ * 问题十六: Decision Sovereignty enforcement。
+ * 不依赖 hasInstructionContract — 触发由 requiresDecisionSovereignty 判定。
+ */
+export declare function checkDecisionSovereigntyGate(params: {
+    ctx: TaskContext | null;
+    route?: string;
+}): Promise<{
+    allowed: boolean;
+    reason_zh?: string;
+    requires_human_gate?: boolean;
+    not_applicable_with_reason?: string;
+}>;
+/**
+ * 细节纪律门 — 复杂任务缺关键细节维度时阻断。
+ * 问题二十六: Detail Discipline enforcement。
+ * 不依赖 hasInstructionContract — 触发由 requiresDetailDiscipline 判定。
+ */
+export declare function checkDetailDisciplineGate(params: {
+    ctx: TaskContext | null;
+    route?: string;
+}): Promise<{
+    allowed: boolean;
+    reason_zh?: string;
+    missing_details?: string[];
+    not_applicable_with_reason?: string;
+}>;
+/**
+ * 第一性原理门 — 高影响任务需目标/约束/本质问题/权衡。
+ * 问题二十七: First Principles enforcement。
+ * 不依赖 hasInstructionContract — 触发由 requiresFirstPrinciples 判定。
+ */
+export declare function checkFirstPrinciplesGate(params: {
+    ctx: TaskContext | null;
+    route?: string;
+}): Promise<{
+    allowed: boolean;
+    reason_zh?: string;
+    failures?: string[];
+    not_applicable_with_reason?: string;
+}>;
+/**
+ * 脑暴/方案探索门 — 不确定项需多方案+推荐理由+用户确认。
+ * 问题四十一-brainstorm: Brainstorm Contract enforcement。
+ * 不依赖 hasInstructionContract — 触发由 requiresBrainstorm 判定。
+ */
+export declare function checkBrainstormGate(params: {
+    ctx: TaskContext | null;
+    route?: string;
+}): Promise<{
+    allowed: boolean;
+    reason_zh?: string;
+    violations?: string[];
+    not_applicable_with_reason?: string;
+}>;
+/**
+ */
+export declare function assessCepAfterVerification(params: {
+    task_id: string;
+    has_verification_evidence: boolean;
+    has_failures?: boolean;
+    hard_fail_downgraded?: boolean;
+    failed_but_marked_done?: boolean;
+}): Promise<{
+    passed: boolean;
+    violations: Array<{
+        principle: string;
+        severity: string;
+        reason_zh: string;
+        required_action?: string;
+    }>;
+    evaluated_principles: string[];
+}>;
+/**
+ * CEP 集成: 交付前 false completion 检查 — 从 sf_deliver handler 提取的真实主链路函数。
+ * 返回 CEP 决策（blocked/repair_reverify/allowed），由 handler 和 gate 共用。
+ */
+export declare function assessCepBeforeDelivery(params: {
+    task_id: string;
+    verification_passed: boolean;
+    build_passed: boolean;
+    browser_acceptance_passed: boolean;
+    guard_passed: boolean;
+    evidence_sufficient: boolean;
+    current_status: string;
+}): Promise<{
+    decision: string;
+    reason_zh: string;
+    passed: boolean;
+}>;
+/**
+ * CEP 集成: 工作流解析后评估 — 检查机制是否接入真实主链路、用户路径是否过短。
+ */
+export declare function assessCepAfterWorkflowResolve(params: {
+    task_id: string;
+    workflow_resolved: boolean;
+    route: string;
+    execution_shape: string;
+    mutation_allowed: boolean;
+}): Promise<{
+    passed: boolean;
+    violations: Array<{
+        principle: string;
+        severity: string;
+        reason_zh: string;
+    }>;
+    evaluated_principles: string[];
+}>;
+/**
+ * CEP 集成: 护栏评估后检查 — 硬规则是否被降级、低风险是否过重。
+ */
+export declare function assessCepAfterGuardEvaluation(params: {
+    task_id: string;
+    guard_passed: boolean;
+    guard_type: string;
+    hard_fail_downgraded: boolean;
+    is_low_risk: boolean;
+}): Promise<{
+    passed: boolean;
+    violations: Array<{
+        principle: string;
+        severity: string;
+        reason_zh: string;
+    }>;
+    evaluated_principles: string[];
+}>;
+/**
+ * CEP 集成: 修复重验证决策 — 检查是否假完成、是否进入正确修复路径。
+ */
+export declare function assessCepForRepairReverify(params: {
+    task_id: string;
+    has_failure: boolean;
+    current_status: string;
+    entered_repair: boolean;
+    repair_reverified: boolean;
+    verification_passed: boolean;
+    build_passed: boolean;
+    evidence_sufficient: boolean;
+}): Promise<{
+    decision: string;
+    reason_zh: string;
+    passed: boolean;
+}>;
+/**
+ * CEP 集成: 用户反馈输出质量 — 检查结论优先、摘要清晰、不隐藏失败、中文语义。
+ */
+export declare function assessCepForUserFeedback(params: {
+    task_id: string;
+    has_conclusion_first: boolean;
+    has_clear_summary: boolean;
+    hides_critical_failure: boolean;
+    chinese_semantic_first: boolean;
+    has_actionable_next_step: boolean;
+    exposes_internal_noise: boolean;
+}): Promise<{
+    passed: boolean;
+    issues_zh: string[];
+}>;
 /**
  * 注册所有 MCP 工具到服务器实例。
  * @param server - McpServer 实例