soloforge 1.1.42 → 1.1.44

package/README.md

@@ -1,99 +1,135 @@
+<div align="center">
+
 # SoloForge
 
-AI 编程助手的项目工作流配置器。SoloForge 帮你把 Claude Code、Codex App、Trae IDE 接入同一套项目规则、知识模板和验证习惯，让 AI 在你的项目里更少误判、更少乱写、更容易交付可检查的结果。
+**一人干完一个小团队的活。**
 
-## 适合谁
+规则驱动的 AI 工程协作 MCP 工作流系统
 
-- 你已经在用 Claude Code、Codex App 或 Trae IDE 写代码。
-- 你希望每个项目都有稳定的 AI 工作流规则，而不是每次从零解释。
-- 你希望 AI 修改代码前先理解项目边界，生成产物时不要误改源码。
-- 你希望配置可以自动推断，但不要在低置信度时乱写项目配置。
-- 你希望 AI 写业务代码时能遵守必要注释、结构化日志、敏感信息脱敏和交付复验要求。
+[![npm version](https://img.shields.io/npm/v/soloforge?label=npm&color=brightgreen)](https://www.npmjs.com/package/soloforge)
+[![license](https://img.shields.io/npm/l/soloforge?color=blue)](./LICENSE)
+![node](https://img.shields.io/node/v/soloforge?label=node&color=green)
+[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
+[![platform](https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Trae-blue)](#-快速开始)
+[![gitee](https://img.shields.io/badge/source-gitee-C71D23)](https://gitee.com/CharlieLuoBo/SoloForge)
+[![issues](https://img.shields.io/badge/issues-gitee-C71D23)](https://gitee.com/CharlieLuoBo/SoloForge/issues)
 
-## 核心能力
+</div>
 
-- **下一步导航**: `soloforge next` 会根据当前阶段、阻断项和已有证据提示下一步，而不是只报告状态。
-- **设计产物包审计**: 需求、原型、架构、详细设计、切片、实现、测试和验收按统一生命周期合同审计，避免文档之间漂移。
-- **工程实现契约**: 编码阶段会约束 OOD/SOLID、Controller/Handler/Router 入参出参、参数校验、事务、幂等、权限、日志和错误处理等实现细节。
-- **注释与日志治理**: 后端写操作、前端关键交互、状态变更、支付/权限/安全路径、异常处理和迁移脚本需要可定位日志、埋点/错误上报或必要注释；敏感信息不得进入日志。
-- **MCP 控制面可信**: `soloforge doctor` 会检查 MCP 配置、适配器 hook、任务状态和恢复路径；AI 绕过 MCP 直接篡改 `.soloforge/state` 会被 hook 拦截，非 MCP 来源的代码变更不能冒充完整可信交付。
-- **长期机制化门禁**: SoloForge 自身发布前会检查机制消费链路、知识治理、配置落盘边界、日志治理和诊断码集中注册，防止只靠文档或测试自证。
+---
 
-## 最短成功路径
+SoloForge 把 Claude Code、Trae 等 AI 编程助手接入同一套**项目规则、知识模板和验证门禁**，让 AI 在你的项目里：先理解边界再动手、按能力域推进、产物可追溯、交付有证据。
 
-```bash
-# 1. 全局安装
-npm install -g soloforge
+它是一个**契约治理内核**——负责分类任务、注入知识、生成验证计划、记录任务状态、提供审查建议和证据链。它不假装替宿主 AI 完成完整工程治理，而是给 AI 套上可审计的约束。
 
-# 2. 进入项目根目录
-cd /path/to/my-project
+> ⚠️ **控制权原则**：任务状态机、工具调用、副作用权限、验证裁决由本地 TypeScript 内核控制；LLM 只作为认知节点提供结构化 proposal。AI 不能绕过 MCP 篡改 `.soloforge/state`，非 MCP 来源的变更不能冒充可信交付。
 
-# 3. 预检：查看 SoloForge 会识别出什么，不写入配置
-soloforge init --auto --dry-run
+---
+
+## 目录
+
+- [✨ 特性](#-特性)
+- [📦 安装](#-安装)
+- [🚀 快速开始](#-快速开始)
+- [🧠 工作原理](#-工作原理)
+- [📂 项目知识库](#-项目知识库)
+- [📐 设计产物目录](#-设计产物目录)
+- [✅ 验证与交付](#-验证与交付)
+- [🛡️ 安全护栏](#-安全护栏)
+- [🖥️ CLI 与 MCP 工具](#-cli-与-mcp-工具)
+- [❓ 常见问题](#-常见问题)
+- [🛠️ 贡献与本仓库开发](#-贡献与本仓库开发)
+- [📄 许可证](#-许可证)
 
-# 4. 初始化项目
-soloforge init --auto
+---
 
-# 5. 重新打开你的 AI 工具，让它加载新配置
-# Claude Code: 退出后在项目目录重新启动 claude
-# Codex App: 重新打开项目目录
-# Trae IDE: 重新打开项目目录
+## ✨ 特性
 
-# 6. 检查状态
-soloforge validate
-soloforge status
-```
+**🎯 任务驱动导航** — `sf_task` 按当前阶段、阻断项和已有证据提示下一步。确认项分 `must_confirm` / `should_confirm` / `auto_resolvable`：必须确认的才挡路，能自动处理的直接给命令。
 
-如果 `init --auto` 提示置信度不足，改用：
+**📐 设计产物不漂移** — 需求、原型、架构、数据库、API、切片按统一生命周期合同审计。全链路用两位数 ID 绑定（`REQ-01` / `ARCH-01` / `SLICE-01` / `AC-01`），不能只说"已按设计实现"。
+
+**🔒 工程实现契约** — 编码阶段约束 OOD/SOLID、Controller/Handler/Router 入参出参、参数校验、事务、幂等、权限、日志和错误处理。
+
+**🔍 抗偷懒与独立审查** — 禁止空洞章节、占位符（TBD）、无证据 ✅。审查采用三阶段强制循环：对抗性审查（默认所有门禁 ❌，逐条引用原文）→ 强制修复 → 独立重审（全新视角，不受修复偏见）。
+
+**✅ 验证有证据** — SoloForge 生成验证命令但不自己执行。只有真实执行并录入结果才算通过；计划、构造记录、未执行的验证都不触发交付。
+
+**🧩 抽象缺失检测** — 自动检测 AM-01~04 反模式（无领域模型、复制无提取、硬编码魔法数字、复杂分支无抽象），触发时强制抽象建模。
+
+**🛡️ 不可降级的安全护栏** — 只读保护、写入 scope 保护、状态保护、并发保护、隐私脱敏，全程强制。
+
+**🔧 机制化发布门禁** — SoloForge 自身发布前跑 **15 phase 门禁**，检查机制消费链路、知识治理、配置边界、诊断码注册，防止只靠文档自证。
+
+## 📦 安装
 
 ```bash
-soloforge init --interactive
+npm install -g soloforge
 ```
 
-## 初始化方式
+**前置要求**：Node.js >= 18，以及 Claude Code 或 Trae。
 
-所有命令默认作用于当前目录。推荐先 `cd` 到项目根目录再执行。
+## 🚀 快速开始
 
 ```bash
-soloforge init --auto --dry-run      # 只预览，不写入 intent.yaml
-soloforge init --auto                # 高置信度时生成 intent.yaml 和适配器文件
-soloforge init                       # 生成目录、知识模板和适配器文件，不写 intent.yaml
-soloforge init --interactive         # 手动确认项目配置
-soloforge init --adapter claude-code # 只生成 Claude Code 配置
-soloforge init --adapter codex       # 只生成 Codex App 配置
-soloforge init --adapter trae        # 只生成 Trae IDE 配置
-soloforge init --adapter all         # 同时生成所有适配器配置
-soloforge init --blueprint "描述"     # 从自然语言蓝图初始化项目
-soloforge init --system-type 新系统   # 指定系统类型（新系统 / 老系统）
+# 1. 进入项目根目录
+cd /path/to/my-project
+
+# 2. 一键接入（生成 MCP 连接 + 工作流指令 + 知识库骨架）
+soloforge init
+
+# 3. 重新打开 AI 工具加载新配置
+#    Claude Code: 退出后在项目目录重新启动 claude
+#    Trae: 重新打开项目目录
 ```
 
-SoloForge 使用三层配置解析：从 `package.json`、`pom.xml`、`go.mod` 等项目文件自动探测技术栈和构建命令；用户偏好（如产品类型、交付设置）存储在可选的 `.soloforge/intent.yaml` 中。探测结果优先于 intent 声明——大多数项目无需手动配置。
+接入后，直接对 AI 说自然语言——「下一步」「验证」「设计架构」「查看状态」——AI 会自动选择对应 MCP 工具。
 
-配置里的 scope、仓库路径和产物路径都按项目相对路径理解和存储，适配 Windows、macOS、Linux 时不要手写宿主机绝对路径。
+> 想先看不写盘的预览？跑 `soloforge init --dry-run`。MCP 连不上？跑 `soloforge doctor` 诊断控制面与状态可信。
 
-## 生成文件
+`init` 只做接入，**不写 intent.yaml**——项目规划、配置推断都留给 AI 连上 MCP 后通过对话完成。技术栈和构建命令由 `package.json` / `pom.xml` / `go.mod` 等项目文件自动探测，大多数项目无需手动配置。
 
-| 位置 | 用途 |
-|------|------|
-| `.soloforge/knowledge/` | 公司全局知识库：项目规则和模板；内置同步资产受 manifest/hash 保护，用户自定义规则会被审计为 hard rule、injectable 或 index_only |
-| `.soloforge/templates/` | 管线阶段模板：artifacts（输出模板）、rules（规则）、gates（门禁配置），按系统类型同步，用户修改过的文件不会被覆盖 |
-| `.soloforge/intent.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 配置 |
+## 🧠 工作原理
 
-SoloForge 不会覆盖已有知识文件和管线模板。知识模板同步到 `.soloforge/knowledge/`，管线模板按系统类型同步到 `.soloforge/templates/`（含 shared + 系统专属目录）。旧项目补齐新模板或适配器时，优先使用 `sync-templates` 和 `sync-adapters`，不要把 `init` 当作升级命令。
+SoloForge 把工程交付拆成 **4 个能力域**，AI 在每个域内通过 **7 个 MCP 工具** 推进：
 
-## 项目知识库维护
+```
+┌─────────────────────────────────────────────────────────┐
+│                    4 能力域（domain）                     │
+├──────────┬──────────┬──────────┬─────────────────────────┤
+│  design  │  build   │  verify  │        operate          │
+│ 设计      │ 构建      │ 验证      │ 运营                    │
+│ 需求/原型  │ 编码/实现 │ 审查/测试  │ 交付/回滚/诊断          │
+│ 架构/DB   │          │ 验收      │                         │
+│ API/切片  │          │          │                         │
+└──────────┴──────────┴──────────┴─────────────────────────┘
+        AI 在域内循环：observe → act → verify
+```
 
-SoloForge 在执行任务时会自动从 `.soloforge/knowledge/` 读取匹配的知识文件注入 AI prompt，帮助 AI 理解你的项目规则和业务约束。你可以往里面添加自己的知识文件。
+**核心循环**：`sf_task` 开任务 → `sf_work action=observe` 看当前域状态 → `sf_work action=act` 拿到受门禁约束的执行 prompt（生成产物）→ `sf_work action=verify` 跑域内门禁 → 通过则推进下一域。
 
-### 文件格式
+```
+AI（认知节点）                          SoloForge 内核（控制权）
+  │                                        │
+  │── sf_work action=act ──────────────▶── │ 读取知识 + 应用门禁
+  │                                        │ 生成结构化执行 prompt
+  │◀────────── 返回受约束的 prompt ──────── │
+  │                                        │
+  │   AI 按 prompt 写产物文件               │
+  │                                        │
+  │── sf_work action=verify ───────────▶── │ 校验产物 + 验证证据
+  │◀────────── 返回裁决 + 下一步 ──────────  │
+```
+
+> **控制权边界**：LLM 提供建议和结构化 proposal，但任务状态机、工具调用、副作用权限、验证裁决由内核裁决。这是 SoloForge 区别于"纯 prompt 工程"的根本。
+
+## 📂 项目知识库
+
+SoloForge 执行任务时自动从 `.soloforge/knowledge/` 读取匹配的知识文件注入 AI prompt。你可以往里面添加自己的规则。`soloforge init` 会在 `.soloforge/knowledge/` 下生成**空骨架目录**（`domain/`、`procedures/`、`checklists/` 等）和一份说明文件——它不预置任何内置规则（避免与 `templates/` 重复），你直接往对应子目录加 `.md` 规则即可。
 
-**必须用 `.md`**（Markdown）。`.yaml` 文件不支持正文注入，对任务执行没有实际效果。
+### 文件格式
 
-每个文件由 YAML frontmatter（`---` 之间的部分）和 Markdown 正文组成。正文是真正注入 prompt 的内容。
+**必须用 `.md`**（`.yaml` 不支持正文注入）。每个文件由 YAML frontmatter 和 Markdown 正文组成，**正文才是注入 prompt 的内容**。
 
 ### 最小示例
 
@@ -101,335 +137,170 @@ SoloForge 在执行任务时会自动从 `.soloforge/knowledge/` 读取匹配的
 ---
 name: 支付规则
 triggers: ["支付", "结算", "退款", "payment", "refund"]
-scope: [backend]
+domain: [backend]
 products: ["*"]
 ---
 
 ## 业务规则
 1. 退款金额不得超过原支付金额
 2. 跨境支付需走外汇审批流程
-
-## 约束条件
-- 所有金额单位为分（整数）
-- 支付超时时间 30 分钟
 ```
 
-### 放在哪个目录
-
-在 `.soloforge/knowledge/` 下按类型分子目录：
-
-```
-.soloforge/knowledge/
-  domain/                → 业务领域规则（支付、权限、工作流等）
-  procedures/            → 自定义流程
-  checklists/            → 自定义验收清单
-  acceptance_templates/  → 自定义产物模板
-  review_rules/          → 自定义审查规则
-  patterns/              → 可复用模式（含 core/ 和 temp/ 子目录）
-  profiles/              → 产品线配置文件
-  rules/                 → 阶段规则（shared / new-system / existing-system）
-  artifacts/             → 产物模板（shared / new-system / existing-system）
-  drafts/                → sf_knowledge_add 的默认输出位置
-```
-
-也可以自建子目录。只要文件路径不和内置模板重名，都会被当作"用户自建文件"放行。
-
 ### frontmatter 字段
 
-| 字段 | 必填 | 默认值 | 说明 |
-|---|---|---|---|
-| `name` | 否 | 文件名 | 注入 prompt 时显示的标题 |
-| `triggers` | **是** | `[]` | 触发关键词字符串数组。AI 任务意图匹配到这些词时才会选中这条知识 |
-| `scope` | 否 | `["shared"]` | 作用域：`backend`、`frontend`、`shared`。`shared` 匹配所有 |
-| `products` | 否 | `["*"]` | 适用产品线，`*` 匹配所有 |
-| `stages` | 否 | `["*"]` | 适用阶段（`需求分析`、`编码与单元测试` 等），`*` 匹配所有 |
-| `status` | 否 | `"active"` | 只有不填或 `active` 才会被使用 |
-| `type` | 否 | 从目录名推断 | 用于分类过滤 |
-| `tech_stack` | 否 | `[]` | 技术栈过滤，如 `["typescript", "react"]` |
-| `confidence` | 否 | — | 置信度评分 |
-| `id` | 否 | 自动生成 | 唯一标识 |
-
-### SoloForge 如何使用你的知识
-
-1. **索引** — 运行任务时，SoloForge 扫描 `.soloforge/knowledge/` 下所有 `.md` 文件
-2. **匹配** — 根据任务的意图关键词和 `triggers` 数组元素做匹配
-3. **注入** — 匹配到的文件正文写入 AI prompt 的 `## 适用知识` 段落
-
-知识注入有预算上限（默认 15 条，索引查询默认返回 5 条），按优先级排序。你的项目知识优先级低于 SoloForge 内置核心规则，但高于全局 patterns。
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `triggers` | **是** | 触发关键词数组，任务意图匹配时才选中 |
+| `verification_layer` | **是** | 校验层：`L0`/`L1`（确定性探针，需配 `probe`+`probe_path`）/ `L2`（LLM 审查注入，默认）/ `L3`（人工确认）。缺失即被拒绝，不默认 L2 |
+| `domain` | 否 | 适用能力域：`design` / `build` / `verify` / `operate`，可多选 |
+| `routes` | 否 | 执行路由（如 `code_change`），hard rule 必填 |
+| `enforcement.level` | 否 | 强制级别（如 `hard_rule`），进入强执行审计 |
+| `lifecycle_stages` | 否 | 生命周期阶段，与 `triggers` 至少填一个，否则 hard rule fail-closed |
+| `scope` / `products` / `type` / `tech_stack` | 否 | 作用域 / 产品线 / 分类 / 技术栈过滤 |
 
-### 注意事项
+> **字段统一**：frontmatter 用 `type` / `triggers` / `domain`，已废弃的 `asset_kind` / `when` / `primary_triggers` / `stages` 不得出现（由架构测试守护）。
 
-- **不要和内置模板同名** — 比如 `.soloforge/knowledge/procedures/功能开发流程.md` 会被当作"被篡改的内置文件"而拒绝。用不同的文件名。
-- **已有文件不会被覆盖** — `sync-templates` 不会删除或覆盖你在 `.soloforge/knowledge/` 里创建的任何文件。
-- **`triggers` 决定命中率** — 不填 `triggers` 或写得太窄，知识文件不会被选中。写宽一些（包括中英文同义词）效果更好。
-- **正文要精简** — 注入 prompt 有长度限制，正文控制在关键规则和约束，不要放长篇背景描述。
+### 校验层（verification_layer）
 
-## 更新与旧项目同步
+规则按"可机械化程度"分四层，决定它怎么被校验：
 
-用户升级已发布的全局 CLI：
-
-```bash
-npm update -g soloforge
-# 或强制安装最新发布版
-npm install -g soloforge@latest
-
-soloforge --version
-```
-
-旧项目补齐新增模板、规则或适配器文件：
-
-```bash
-cd /path/to/my-project
+| 层 | 机制 | 适用 |
+|----|------|------|
+| `L0` | 确定性探针（builtin 正则 / semgrep）经 ODA 门禁执行 | 事务内禁 RPC、空 catch、分层调用等可模式化硬规则 |
+| `L1` | 可执行策略（rego / property 测试） | 金额用 BigDecimal、数据流约束 |
+| `L2` | 注入审查 prompt，LLM 按清单审（默认） | 业务约定、缓存策略等语义规则 |
+| `L3` | 人工确认（must_confirm 硬停） | 架构选型、支付通道等关键决策 |
 
-soloforge sync-templates
-soloforge sync-adapters
+L0/L1 需旁挂探针文件（`probe` + `probe_path`），依赖缺失会硬失败（doctor 预检 + 运行时 fail，不降级）。详见 [`docs/项目规则分层写法指南.md`](docs/项目规则分层写法指南.md)。
 
-soloforge sync-templates --apply --confirm
-soloforge sync-adapters --apply --confirm
+### 目录约定
 
-soloforge doctor
-soloforge audit-design-artifacts
 ```
-
-如果你只是升级 CLI，不需要重新 `init` 旧项目。`soloforge init` 只用于新项目首次接入，或者项目里根本还没有 `.soloforge/`。
-
-存量设计产物需要升级到当前标准时，单独使用设计产物升级命令：
-
-```bash
-soloforge upgrade-design-artifacts
-soloforge upgrade-design-artifacts --apply --confirm
+.soloforge/knowledge/
+  domain/                → 业务领域规则
+  procedures/            → 自定义流程
+  checklists/            → 验收清单
+  review_rules/          → 审查规则
+  patterns/              → 可复用模式（core/ temp/）
+  rules/ artifacts/      → 阶段规则 / 产物模板
+  drafts/                → sf_knowledge action=add 默认输出
 ```
 
-只有新项目首次接入 SoloForge 时才运行 `soloforge init`。已经有 `.soloforge/` 的旧项目，优先用同步和审计命令；如果只是 AI 工具配置缺失，可按 `doctor` 输出的恢复命令处理。
+> ⚠️ **不要和内置模板同名**（如 `procedures/功能开发流程.md` 会被当篡改拒绝）；已有文件不会被覆盖；`triggers` 决定命中率，写宽些（含中英文同义词）。
 
-## 日常命令
+## 📐 设计产物目录
 
-大部分命令支持 `--json` 输出 JSON 格式，方便工具集成。
+SoloForge 用固定的 `docs/` 结构管理产物，每个产物有明确位置和上下游依赖，系统按固定路径查找：
 
-```bash
-soloforge validate [--json]           # 检查项目配置和知识文件
-soloforge validate-knowledge [--json] # 验证知识规则完整性和消费链路
-soloforge validate-foundation [--json] # 验证基础场景矩阵
-soloforge validate-new-issue --title="问题标题" [--json] # 验证新 issue 注册和消费
-soloforge validate-mechanisms         # 验证双层机制模型完整性
-soloforge status                      # 查看当前项目状态和配置来源
-soloforge next [--json] [--write-snapshot] # 查看当前阶段、阻断项和下一步可执行工作包
-soloforge stage [--explain]           # 查看项目阶段与当前任务阶段
-soloforge config show                 # 查看配置解析结果（探测 + intent + 约定合并）
-soloforge config explain <field>      # 解释某项配置为什么是当前值
-soloforge config set <field> <value>  # 写入 intent.yaml 字段（产品类型、交付设置等）
-soloforge config export               # 导出 intent.yaml 原始内容
-soloforge config unset <field>        # 删除 intent.yaml 字段
-soloforge config check                # 运行探测 + 验证 + 冲突检测
-soloforge audit-project-knowledge [--json] # 审计项目自定义知识规则是否可被稳定消费
-soloforge audit-template-visibility [--json] # 审计内部治理资产的可见性隔离
-soloforge doctor [--json]             # 诊断 MCP 控制面、适配器 hook、状态可信和恢复路径
-soloforge analyze --view <视图名> --targets [...] [--json]  # 按需调用上下文引擎
-soloforge modify <产物路径> [--stdin|--file <path>] [--json]  # 脱离管线修改产物
-soloforge review <产物路径> [--json]  # 脱离管线审查产物
-soloforge version                     # 查看版本
+```text
+docs/
+├── context/              需求分析.md（需求文档）· 原型源码包/
+├── analyze/              {端}/01-原型说明.md（多端，每端一份，如 web/admin/小程序/APP）
+├── architecture/         00-架构决策记录.md · 01-架构设计文档.md · 02-开发切片计划.md
+├── design/               01-数据库设计文档.md · 02-API接口规格文档.md · 03-详细设计文档.md（可选）
+├── audits/               01-设计一致性验收报告.md · 02-代码审查报告.md · 03-测试报告.md · 04-发布说明.md
+├── existing-system/      现有系统分析 · 增量边界界定 · 数据血缘图 · 历史遗留雷区（老系统改造专属）
+├── api/                  openapi.yaml
+└── db/                   migration/
 ```
 
-多个命令支持 `--project-path <path>` 指定项目路径（非当前目录时使用）。
-
-### 状态清理与审计
+| 产物 | 路径 | 依赖 |
+|------|------|------|
+| 需求文档 | `context/需求分析.md` | — |
+| 原型说明 | `analyze/{端}/01-原型说明.md` | 需求 + 原型源码包 |
+| 架构决策 | `architecture/00-架构决策记录.md` | — |
+| 架构设计 | `architecture/01-架构设计文档.md` | 需求 + 原型 + 决策 |
+| 开发切片计划 | `architecture/02-开发切片计划.md` | 数据库 + API + 架构 |
+| 数据库设计 | `design/01-数据库设计文档.md` | 决策 + 架构 |
+| API 规格 | `design/02-API接口规格文档.md` | 决策 + 架构 + 数据库 |
+| 详细设计 | `design/03-详细设计文档.md`（可选） | 架构 + 数据库 + API |
+| 设计一致性验收 | `audits/01-设计一致性验收报告.md` | 全设计产物 |
+| 代码审查报告 | `audits/02-代码审查报告.md` | 切片 + 实现 |
+| 测试报告 | `audits/03-测试报告.md` | 切片 + 实现 |
+| 发布说明 | `audits/04-发布说明.md` | 验收 + 一致性 |
+| OpenAPI | `api/openapi.yaml` | API 规格 |
 
-```bash
-soloforge cleanup --dry-run            # 预览可清理的状态文件
-soloforge cleanup --apply [--stale]    # 执行清理（默认 dry-run，需显式 --apply）
-soloforge cleanup --json               # JSON 格式输出
-soloforge audit-template-mechanisms [--json]    # 审计知识资产 schema 完整性
-soloforge audit-design-artifacts [--json]       # 审计架构/数据库/API 设计产物包
-soloforge upgrade-design-artifacts     # 预览设计产物升级计划（dry-run）
-soloforge upgrade-design-artifacts --apply --confirm  # 确认后归档旧设计产物并写入升级契约
-```
+域内验证时按路径查上游产物；缺失返回 `missing_upstream` 并提示模板。非代码产物（文档、分析、提取结果）按上面产物目录归类写入对应 `docs/` 子目录。
 
-### 发布自检（SoloForge 维护者）
+## ✅ 验证与交付
 
-```bash
-# 发布前必须通过的门禁，普通用户不需要执行
-npm run validate-release
-node dist/bin/soloforge.js validate-release --json
-```
+- **验证计划 ≠ 验证结果** — SoloForge 生成验证命令但不执行。只有真实执行并录入结果才算通过。
+- **未验证不交付** — 交付前必须真实执行的验证结果。计划、构造记录、未执行的验证都不触发交付。
+- **证据必须完整** — 每条验证结果含执行证据（输出哈希、时间、证据 ID）且覆盖全部 `changed_files`。
+- **交付需显式触发** — 交付就绪检查只判断"能不能交付"，不自动 commit/push/建 PR。验收接受必须有可审计的用户确认，不能由 AI 自标已接受。
 
-`validate-release` 是 SoloForge 自身的发布门禁，检查构建产物、机制消费、模板完整等长期产品结构。
+**失败处理**：确定性失败不无限重试（升级人工）；可修复失败有预算上限；scope 不足请求扩大不越权；错误信息自动脱敏。
 
-### 模板与适配器同步
+## 🛡️ 安全护栏
 
-```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     # 执行项目迁移
-```
+运行时强制护栏（不降级、不关闭；误判可通过配置覆盖或人工确认解除）：
 
-**默认安全，写入需确认：**
+| 护栏 | 作用 |
+|------|------|
+| 只读保护 | 分析/文档类任务不能改源码 |
+| 写入 scope 保护 | 代码修改只能在声明的 scope 路径内 |
+| 状态保护 | 已失败任务不能直接标完成 |
+| 并发保护（advisory） | 检测同一文件范围的并发写入冲突并标记需确认；仅 CAS 与租约同时冲突时升级阻断 |
+| 隐私保护 | 密钥、凭证、个人信息存储前脱敏 |
 
-- `sync-templates` 和 `sync-adapters` 默认只预览，不写任何文件。需要加 `--apply --confirm` 才会实际写入。
-- `migrate` 默认也是 dry-run。只有 `--apply --confirm` 才会写入版本状态和迁移记录，并自动创建备份。
-- 你手动修改过的模板和适配器文件（如 `CLAUDE.md`）不会被静默覆盖——SoloForge 会检测文件是否被用户修改，修改过的文件在同步时自动跳过并报告。
-- 核心知识模板受保护，即使 apply 也不会被自动同步覆盖。
-- dry-run 中的“应用安全: 需确认”表示发现用户已有文件或需要人工确认；这不是命令失败，只有加 `--apply --confirm` 才会写入。
-- 用户自己新增到 `.soloforge/knowledge/**` 的规则不会被当成普通静态文件。带有 `type: hard_rule`、`stages`、`triggers` 或 `enforcement.level` 的项目规则会进入审计和任务选择；缺少触发条件的 hard rule 会被 `audit-project-knowledge` 标为阻断。
-- 项目规则在阶段执行时（`sf_stage_execute`）按 intent、stage、技术栈和触发词筛选，不会整库塞进 prompt；`sf_code_review`、`sf_gate_check`、`sf_stage_advance` 会在项目规则不可消费或冲突时阻断。
-- 项目规则可用 `conflict_group` + `rule_value` 或 `conflicts_with` 声明互斥口径，例如 API 响应格式、分页格式、日志字段、数据库命名和权限模型。冲突不会由 AI 直接拍板，必须先由用户确认。
-- 知识资产与项目规则消费体系受发布门禁矩阵约束：模板卫生、脚手架质量、项目知识承载、选择注入、冲突确认、`next` 消费、同步保护、技术栈过滤、设计产物消费、消费 trace 和用户可见解释都必须有真实入口和 release gate。
+## 🖥️ CLI 与 MCP 工具
 
-**典型升级流程：**
+### CLI 命令（仅接入与诊断）
 
 ```bash
-npm update -g soloforge
-cd /path/to/my-project
-soloforge sync-templates                # 看看有哪些模板更新
-soloforge sync-templates --apply --confirm  # 确认后应用
-soloforge sync-adapters                 # 看看适配器是否需要更新
-soloforge sync-adapters --apply --confirm   # 确认后应用
-soloforge migrate                       # 看看是否需要迁移
-soloforge migrate --apply --confirm     # 确认后迁移
+soloforge                                # 启动 MCP server（默认）
+soloforge mcp                            # 启动 MCP server
+soloforge init [--adapter] [--dry-run] [--force]   # 一键接入（仅新项目首次）
+soloforge doctor [--json]                # 诊断控制面/状态可信/恢复路径
+soloforge --version | --help
 ```
 
-## 使用时你会看到什么
-
-接入成功后，AI 助手会在合适的时候调用 SoloForge 来理解任务、生成执行上下文、给出验证建议和记录任务状态。对你来说，主要变化是：
-
-- **架构设计** — 让 AI 设计架构时，会生成结构化方案（含架构边界、技术栈、模块关系），输出目录会先征求你确认，不会自作主张写到你不想放的位置。
-- **决策研讨** — 高影响或不确定任务会先进入决策研讨，而不是直接生成方案或代码。架构设计会覆盖业务流程、数据架构、安全架构、后端架构、前端架构、基础设施六类架构决策；技术选型、数据迁移、安全策略、部署、产品范围、重构和第三方集成等任务会展开对应决策包。必要决策未确认时，不会把草案冒充正式结论。
-- **设计产物包** — 架构设计、数据库设计、API 规格不再各自漂移。标准产物包包含 `docs/architecture/00-架构决策记录.md`、`01-架构设计文档.md`、`02-数据库设计文档.md`、`03-API接口规格文档.md`、`04-开发切片计划.md`、`99-设计一致性验收报告.md`、`docs/traceability/01-需求原型设计实现追踪矩阵.md`、`docs/api/openapi.yaml` 和 `db/migration`/`db/migrations`/`db/schema`/`db/changelog` 下的数据库结构资产。`04-详细设计文档.md` 只是旧项目或复杂模块的可选补充，不是必需详细设计载体；旧的 `04-第一阶段开发切片计划.md` 会作为兼容别名读取并给出迁移提示，正式权威路径仍应迁移为 `04-开发切片计划.md`。
-- **全链路追踪矩阵** — 需求、原型、架构、详细设计、阶段、切片、实现、测试和验收使用两位数 ID 绑定，例如 `REQ-01`、`PROTO-01`、`ARCH-01`、`DD-T01`、`DD-A01`、`PHASE-01`、`SLICE-01`、`AC-01`。编码任务必须能绑定 `PHASE-*`、`SLICE-*`、`DD-*` 和 `AC-*`，不能只说“已按设计实现”。
-- **标准资产契约** — 模板、规则、流程、验收清单、审查规则、脚手架和 adapter workflow 不是“参考文件”。SoloForge 会按资产契约检查正式产物的章节、字段表、权威资产、适用技术栈和修复重验状态；API 文档必须有每个接口的请求/响应字段说明表，数据库/API Markdown 必须绑定 SQL/OpenAPI 权威资产。
-- **模板可见性** — 内部治理资产可以随 npm 包发布，供 SoloForge runtime、审计和发布门禁使用，但不会同步到用户项目，也不会注入到 AI prompt。用户项目只获得可见且适用的知识资产；脚手架只由脚手架命令消费，不进入知识索引；不匹配技术栈的内置脚手架不会 fallback 生成。
-- **现有系统新需求** — 在已有项目里开发新功能时，AI 会先分析现有系统现状和差距，再给出实现计划，不会跳过理解直接写代码。
-- **编码任务** — 写代码前会先明确约束和验收项、生成验证/测试计划，再动手实现。编码不是第一步。
-- **可运行项目交付** — 涉及前端/全栈/可运行项目时，交付前会支持本地运行和浏览器验收。验收失败会自动诊断、修复并重测，最终给你一个可以在浏览器打开的本地地址来人工查验。
-- **技术决策** — 高影响技术选型（架构、数据库、框架等）会区分"AI 建议"和"需要你确认的决策"，不会悄悄帮你拍板不可逆的选择。
-- **多方案探索** — 遇到不确定的技术问题时，会先列出多个候选方案、给出权衡分析和推荐，而不是只给一个答案。
-- **路径与平台安全** — 跨平台（macOS/Linux/Windows）路径处理更谨慎，不会意外修改工作区之外的文件。第三方扩展有明确的权限边界。
-- **执行前确认** — 涉及写入、编码、构建、迁移、发布、交付等操作前，AI 会先给出计划或确认项，不会直接动手改。验收接受必须有可审计的用户确认引用，不能由 AI 自己把产物标记为已接受。
-- **简单问答** — 提问、闲聊、低风险确认不会触发完整工作流，直接处理，不强行走重流程。
-- **施工指令约束** — AI 写代码前必须先明确目标、范围、非目标和验收标准，不会跳过定义直接动手写实现。
-- **证据驱动** — AI 不得无证据声称项目事实。默认模板和通用规则不算项目证据；架构分析必须有真实代码依据或你的人工确认。
-- **存量设计复验** — 升级 SoloForge 后，已有架构/数据库/API 文档不会被默认信任。运行 `soloforge audit-design-artifacts` 可得到差距报告；需要升级时先 dry-run，再经 `--apply --confirm` 归档旧文件并写入升级契约，修订后的文档必须重新复验。
-- **下一步导航** — 不确定接下来该做什么时，运行 `soloforge next`，或向 AI 直接说“下一步/继续/现在能写代码吗”。SoloForge 会依据配置、设计验收、当前任务、修复指令和验证证据输出阶段、阻断原因、确认分级与工作包；陈旧任务不会被静默绕过。确认项会分为 `must_confirm`、`should_confirm` 和 `auto_resolvable`：必须确认的才挡路，建议确认的只提醒，能自动处理的给出命令。空项目只确认目标、边界、技术选择和默认口径，不会把自动推断当成既有项目事实。
-- **OOD 与 SOLID 编码约束** — 复杂业务、领域服务、策略和重构类实现会先要求对象职责、接口与依赖方向摘要；代码审查可识别职责膨胀、直接依赖基础设施、宽接口和替换违约。文案或简单配置修改不会被强行复杂化。
-- **后端实现工程约束** — 实现后端接口前会要求 DTO/校验、响应与分页、事务与幂等、安全审计、OpenAPI/数据库对齐和测试证据；Spring Boot Entity 默认保持 `@Getter`/`@Setter`，DTO/VO/Request/Response 默认使用 `@Data`；实体泄漏、写接口无校验、事务内外调、关键写入无幂等或敏感接口无安全证据会阻断交付。
-- **日志与注释清晰** — 用户可见输出中文优先；JSON 模式（`--json`）输出保持纯 JSON，不混入内部日志。用户项目业务日志和注释也必须中文；后端类需要说明类作用的 Javadoc，方法需要说明方法、入参和出参，关键业务行需要中文行注释。
-- 写代码类任务会更明确 scope、验收项和验证命令。
-- 生成文档、提取说明、分析日志等产物型任务会默认输出到 `.soloforge/output/`，不会默认修改 `src/`。
-- 遇到缺少路径、源码包、日志等必需输入时，会先澄清，而不是猜着执行。
-- 敏感信息、危险命令和高风险交付动作会更保守，需要你确认。
-- AI 给你的反馈会先说结论、必要依据和下一步建议，不展示内部处理流水账。
-
-### 验证与交付
-
-SoloForge 对验证和交付有严格的分层设计：
-
-- **验证计划不等于验证结果**：SoloForge 会生成验证命令（如 `npm test`），但不会自己执行。只有你或 AI 工具实际执行，并通过 `sf_record_verification_execution` 录入结果后，才被视为已验证。纯计划不等于通过。
-- **未验证不交付**：交付前必须通过真实执行的验证结果。计划阶段的产物、直接构造的通过记录、未执行的验证，都不会触发交付。
-- **证据必须完整**：每条验证结果必须包含完整的执行证据（命令输出哈希、执行时间、唯一证据 ID）并覆盖本次完整 `changed_files`。缺少证据、格式不合法或只验证部分变更文件的记录会被判定为失败。
-- **交付需要显式触发**：交付就绪检查只判断能不能交付，不会自动执行 commit、push 或创建 PR。交付动作必须由 `sf_stage_advance` 或你手动触发。
-- **交付指标来自真实数据**：交付质量指标从真实 TaskContext 状态目录聚合，不接受空数组、undefined 或构造的通过样本。验证失败会进入修复/复验闭环，不能只报告不修复。
-
-### 失败处理
-
-当验证或执行失败时：
-
-- **确定性失败不重试**：相同的错误反复出现时，SoloForge 会升级给你处理，不会无限重试。
-- **可修复失败有预算**：重试次数有上限，超预算后停止并升级。
-- **范围不足不越权**：如果失败是因为 scope 不够，SoloForge 会请求扩大范围，不会静默越权写入。
-- **错误信息已脱敏**：失败报告中的敏感信息（密钥、密码、原始输出）会自动脱敏，只保留摘要和哈希。
-- **项目知识可审计**：项目自定义规则必须能说明适用路由、触发词、生命周期阶段、文件路径、业务域和技术栈。能执行的规则会以 SelectionDecision 形式说明是否选中、命中的信号、强制级别、验证命令和恢复路径；只适合作为背景资料的规则会标为 `index_only`，不得冒充已执行约束。`soloforge next`、`sf_code_review`、`sf_gate_check`、`sf_stage_advance` 和 `audit-project-knowledge` 消费同一份决策结果，避免各入口各说各话。
-- **历史问题机制化**：新反馈不会只按表面文件或单个场景处理。SoloForge 的发布门禁要求历史问题先归入长期机制族，并具备第一性原理不变量、生产入口、用户项目路径、must-fail 和 must-pass。
-
-### 安全护栏
-
-SoloForge 在运行时执行以下强制护栏：
-
-- **只读保护**：被分类为只读的任务（分析、文档生成等）不能修改项目源码。
-- **写入范围保护**：代码修改只能在声明的 scope 路径内进行，超出范围的写入会被阻断。
-- **状态保护**：已失败的任务不能被直接标记为完成，需要先修复并重新验证。
-- **并发保护**：同一个文件范围不会被两个任务同时写入。
-- **隐私保护**：密钥、凭证和个人信息在存储前自动脱敏。
-
-这些护栏不会降级或关闭。如果误判，你可以通过配置覆盖或人工确认解除。
-
-## 产物输出
-
-文档、分析报告、源码包提取结果等非代码产物默认写入：
-
-```text
-.soloforge/output/
-```
+### MCP 工具（AI 通过 MCP 自动调用，共 7 个）
 
-例如让 AI “从 `/tmp/prototype.zip` 抓取原型说明”，SoloForge 会把它作为只读外部材料处理，要求产物写入 `.soloforge/output/**`，而不是修改项目源码。
+| 工具 | action | 职责 |
+|------|--------|------|
+| `sf_task` | `start` / `query` / `cancel` | 任务生命周期：启动、查下一步、取消 |
+| `sf_work` | `observe` / `act` / `verify` | 能力域工作（需传 `domain`）：看状态、拿执行 prompt、跑域内验证 |
+| `sf_knowledge` | `audit` / `add` / `update` | 知识库：审计规则可消费性、新增、更新 |
+| `sf_gate` | —（参数 `gate_name` + `domain`） | 独立门禁审查（OOD/SOLID、抽象缺失、风险模式等） |
+| `sf_scaffold` | —（参数 `task_id`） | 脚手架生成（不匹配技术栈时不 fallback） |
+| `sf_analyze` | —（参数 `view`） | 上下文引擎视图：`file_impact` / `reference_trace` / `dependency_graph` / `change_impact` / `coverage_gap` / `knowledge_ref` |
+| `sf_doctor` | —（参数 `check_type`） | MCP 诊断：`check_type` = `state` / `gates` / `scope` / `full` |
 
-## 产物目录规范
+> **工具契约**：每个工具有对应 invocation contract，启动时覆盖预检——已注册必须有契约，契约必须有实现，避免工具与门禁各说各话。
 
-SoloForge 采用固定的 `docs/` 目录结构管理项目产物。每个产物有明确的存放位置和上下游依赖，系统直接按固定路径查找，无需猜测。
+## ❓ 常见问题
 
-### 目录结构
-
-```text
-docs/
-├── context/                          # 输入材料
-│   ├── 需求文档.md                    ← requirement_analysis
-│   └── 原型源码包/                    ← source_code_package（含各端 zip）
-├── analyze/                          # 分析产物
-│   └── 01-原型说明.md                  ← prototype_spec
-├── architecture/                     # 设计产物
-│   ├── 00-架构决策记录.md             ← tech_decision_record
-│   ├── 01-架构设计文档.md             ← design_doc
-│   ├── 02-数据库设计文档.md           ← database_design
-│   ├── 03-API接口规格文档.md          ← api_spec
-│   ├── 04-开发切片计划.md             ← task_plan
-│   └── 05-详细设计文档.md             ← detailed_design（可选）
-├── traceability/                     # 追踪产物
-│   └── 01-需求原型设计实现追踪矩阵.md  ← traceability_matrix
-├── api/                              # API 定义
-│   └── openapi.yaml
-├── review/                           # 审查报告
-│   └── 99-设计一致性验收报告.md
-└── db/                               # 数据库资产
-    └── migration/
-```
+<details>
+<summary><b><code>soloforge init</code> 没有生成 intent.yaml</b></summary>
 
-### 节点依赖表
+设计行为。`init` 只做接入，不推断项目规划。intent.yaml 是 AI 连上 MCP 后通过对话补充的可选偏好文件。技术栈由项目文件自动探测。
+</details>
 
-每个产物的固定路径、输入依赖和触发命令：
+<details>
+<summary><b>AI 工具没有调用 SoloForge</b></summary>
 
-| 产物（kind） | 固定路径 | 输入（consumes） | 触发命令示例 |
-|---|---|---|---|
-| 需求分析 `requirement_analysis` | `docs/context/需求文档.md` | — | `[sf]审查需求` |
-| 原型源码包 `source_code_package` | `docs/context/原型源码包/` | — | 输入材料，非产出 |
-| 原型说明 `prototype_spec` | `docs/analyze/*/01-原型说明.md` | 需求分析 + 原型源码包 | `[sf]审查原型说明` |
-| 架构决策 `tech_decision_record` | `docs/architecture/00-架构决策记录.md` | — | `[sf]审查决策记录` |
-| 架构设计 `design_doc` | `docs/architecture/01-架构设计文档.md` | 需求分析 + 原型说明 + 决策记录 | `[sf]审查架构设计` |
-| 数据库设计 `database_design` | `docs/architecture/02-数据库设计文档.md` | 决策记录 + 架构设计 | `[sf]审查数据库设计` |
-| 接口设计 `api_spec` | `docs/architecture/03-API接口规格文档.md` | 决策记录 + 架构设计 + 数据库设计 | `[sf]审查接口设计` |
-| 切片计划 `task_plan` | `docs/architecture/04-开发切片计划.md` | 数据库设计 + 接口设计 | `[sf]审查切片计划` |
-| 详细设计 `detailed_design` | `docs/architecture/05-详细设计文档.md` | 架构设计 + 数据库设计 | `[sf]审查详细设计` |
-| 追踪矩阵 `traceability_matrix` | `docs/traceability/01-需求原型设计实现追踪矩阵.md` | 需求 + 原型 + 架构 + 数据库 + 接口 + 切片 | `[sf]审查追踪矩阵` |
+检查配置文件是否生成，重启 AI 工具：
+- Claude Code：`.mcp.json` / `.claude/settings.json` / `CLAUDE.md`
+- Trae：`.trae/mcp.json` / `.trae/rules/project_rules.md`
 
-### 新项目初始化
+再跑 `soloforge doctor` 按恢复路径处理。不建议手动删 `.soloforge/state`。
+</details>
 
-按上述结构创建目录和文件即可：
+<details>
+<summary><b>旧项目补齐或修复配置</b></summary>
 
 ```bash
-mkdir -p docs/context docs/analyze docs/architecture docs/traceability docs/api docs/review docs/db/migration
+soloforge doctor    # 查看缺失项与恢复路径
 ```
 
-SoloForge 在执行 `[sf]审查` 命令时，会按固定路径查找上游产物。如果某个产物缺失，系统会返回 `missing_upstream` 状态并提示需要先产出的产物及其模板。
-
-## Cursor 说明
-
-Cursor 暂无内置适配器。可以先生成 `.mcp.json`，再手动复制到 `.cursor/mcp.json`：
+旧项目优先用 `doctor` 和 MCP 工具维护；只有新项目首次接入才跑 `soloforge init`。
+</details>
 
-```bash
-soloforge init
-```
+<details>
+<summary><b>Cursor 接入</b></summary>
 
-示例：
+Cursor 暂无内置适配器。先 `soloforge init` 生成 `.mcp.json`，再手动复制到 `.cursor/mcp.json`：
 
 ```json
 {
@@ -444,152 +315,85 @@ soloforge init
 ```
 
 保存后重载 Cursor 窗口。
+</details>
 
-## 常见问题
-
-### `soloforge init --auto` 没有生成 intent.yaml
-
-这是正常行为。SoloForge 只有在项目指纹足够明确时才会自动写 intent.yaml。大多数项目通过文件探测即可获得完整配置；你也可以执行 `soloforge init --interactive` 手动确认偏好设置。
-
-### AI 工具没有调用 SoloForge
-
-先检查对应配置文件是否生成，然后重启或重载 AI 工具：
-
-- Claude Code: `.mcp.json`、`.claude/settings.json`、`CLAUDE.md`
-- Codex App: `.codex/config.toml`、`.codex/hooks.json`、`AGENTS.md`
-- Trae IDE: `.trae/mcp.json`、`.trae/rules/project_rules.md`
-
-也可以先运行:
-
-```bash
-soloforge doctor
-```
-
-如果 doctor 报告 MCP 配置缺失、hook 漂移、旧任务指针或恢复路径问题，先按输出的恢复命令处理。SoloForge 不建议手动删除 `.soloforge/state`；需要恢复陈旧任务时应使用受控命令或 MCP 工具。
-
-### 想补齐或修复配置
-
-```bash
-soloforge doctor
-```
-
-先按 `doctor` 输出的恢复命令处理。旧项目需要补齐新增模板或适配器文件时，使用 `sync-templates` / `sync-adapters`；新项目首次接入时才运行 `soloforge init`。
-
-如果 `status` 提示配置不完整（缺少 tech_stack 或 build_commands），可以通过配置命令补充：
-
-```bash
-soloforge config check         # 检查配置完整性和冲突
-soloforge config set <field>   # 写入缺失的 intent.yaml 字段
-soloforge validate
-soloforge status
-soloforge next
-```
-
-`config set` 通过 AI 对话或 MCP 工具 `sf_config_update` 写入 intent.yaml 中的用户偏好字段（如 product_profile、delivery）。技术栈和构建命令由项目文件自动探测，无需手动配置。
-
-### 想清理项目中的 SoloForge 文件
-
-全局卸载只会移除命令：
-
-```bash
-npm uninstall -g soloforge
-```
-
-项目内文件需要手动删除：
-
-```text
-.soloforge/
-.mcp.json
-.claude/
-CLAUDE.md
-.codex/
-AGENTS.md
-.trae/
-```
-
-删除 `CLAUDE.md` 或 `AGENTS.md` 前请确认没有手写内容。
-
-### validate / status 出现 EMFILE 或 too many open files
+<details>
+<summary><b>清理项目中的 SoloForge 文件</b></summary>
 
-`soloforge validate` 和 `soloforge status` 是一次性 CLI 命令，知识索引使用 `watch: false`，不会启动长期 watcher。如果出现 `EMFILE`、`too many open files` 或 watch 崩溃，属于异常，请提交 issue 反馈。
+全局卸载：`npm uninstall -g soloforge`。项目内文件手动删：`.soloforge/` / `.mcp.json` / `.claude/` / `CLAUDE.md` / `.trae/`（删 `CLAUDE.md` 前确认无手写内容）。
+</details>
 
-## 本仓库开发
+## 🛠️ 贡献与本仓库开发
 
 ### 日常开发
 
 ```bash
 npm install
-npm run build        # clean build：先删除 dist 再编译，防止 stale 产物进入发布包
-npm test             # 等价于 npm test -- --run
+npm run build        # clean build（rm -rf dist + tsc）
+npm test             # 全量 vitest 测试
 ```
 
-`npm run build` 执行的是 clean build：先 `rm -rf dist`，再 `tsc` 编译。这保证 dist 产物与 src 源码严格一致，不会残留已删除源码对应的旧编译文件。
+### 常用脚本
+
+| 脚本 | 用途 |
+|------|------|
+| `npm run build` | clean build |
+| `npm run dev` | tsc --watch 增量编译 |
+| `npm run clean` | 清理 `dist/` |
+| `npm test` | 全量测试 |
+| `npm run test:e2e` | 端到端测试（需 `E2E=1`） |
+| `npm run typecheck` | tsc --noEmit |
+| `npm run typecheck:tests` | 测试文件类型检查 |
+| `npm run lint` | eslint（仅 `src/`） |
+| `npm run lint:all` | eslint 全项目零警告 |
+| `npm run check:comments` | 中文注释防回归 |
+| `npm run check:schema-enum` | Schema 枚举一致性 |
+| `npm run check:runtime-recovery` | 运行时态自救闭环校验 |
+| `npm run validate-release` | **15 phase 发布门禁** |
 
 ### 发布前验收
 
-SoloForge 维护者在发布前必须依次执行以下命令，全部通过才能进入 Release Candidate：
+维护者发布前必须依次执行，全绿才能进 Release Candidate：
 
 ```bash
-# 1. 编译 + 类型检查 + lint（三合一）
-npm run build && npx eslint . --max-warnings 0
-
-# 2. 全量测试
-npm test
-
-# 3. 中文注释防回归
-npm run check:comments
-
-# 4. 发布门禁（文本输出，14 项 PASS / 0 hard_fail）
-npm run validate-release
-
-# 5. 发布门禁（JSON 输出，必须 passed=true、hard_fail_count=0）
-node dist/bin/soloforge.js validate-release --json
-
-# 6. 循环依赖检查
-npx madge --circular --extensions ts src/
-
-# 7. 用户项目可用性抽查
-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
+npm run build && npm run lint:all       # 1. 编译 + 类型 + lint
+npm test                                # 2. 全量测试
+npm run check:comments                  # 3. 中文注释防回归
+npm run check:schema-enum               # 4. 枚举一致性
+npm run check:runtime-recovery          # 5. 运行态自救
+npm run validate-release                # 6. 15 phase 发布门禁（全 PASS / 0 hard_fail）
+npx madge --circular --extensions ts src/   # 7. 循环依赖检查
+
+# 8. 用户项目可用性抽查
+REPO_DIR=$(pwd); TMPDIR=$(mktemp -d) && cd "$TMPDIR"
+node "$REPO_DIR/dist/index.js" init
+node "$REPO_DIR/dist/index.js" doctor   # exit code 都必须为 0
 cd "$REPO_DIR"
 ```
 
-当前代码质量基线：tsc 零错误 | 293 测试文件 / 5305 测试全部通过 | eslint 零警告 | 零循环依赖 | 中文注释零回归 | `noUnusedLocals` + `noUnusedParameters` 已启用。
-
 <details>
-<summary>内部说明：validate-release 门禁检查项</summary>
-
-`npm run validate-release` 检查以下 14 项门禁：
-
-1. dist 旧产物风险检查
-2. npm pack 产物验证
-3. 依赖漏洞扫描
-4. MCP 控制面可信与受控生成链路
-5. 关键问题消费验证
-6. 主链路真实消费
-7. P0/P1 知识资产 schema
-8. 模板卫生与项目知识消费
-9. 工作流导航契约行为
-10. TypeScript 编译检查
-11. 发布问题场景矩阵
-12. 代码质量门禁
-13. 架构边界回归
-14. 模板消费覆盖率
-
-全部 14 项 PASS / 0 hard_fail 才能发布。
+<summary>validate-release 15 phase 门禁</summary>
+
+1. dist 旧产物风险 · 2. 主链路真实消费 · 3. 依赖漏洞扫描 · 4. TypeScript 编译检查 · 5. 关键问题消费验证 · 6. MCP 控制面可信与受控生成链路 · 7. 模板卫生与项目知识消费 · 8. 工作流导航契约行为验证 · 9. npm pack 验证 · 10. 资产防膨胀审计 · 11. 发布问题场景矩阵 · 12. 候选版本排序与回滚路径验证 · 13. 代码质量门禁 · 14. 架构边界回归 · 15. 模板消费覆盖率
+
+> 另有入口预检「运行时态自救闭环」（`check:runtime-recovery`）在 15 phase 之前执行，不属于 15 phase 之一。
 
 </details>
 
-## 技术要求
+代码质量基线：tsc 零错误 ｜ 全量测试零失败 ｜ eslint 零警告 ｜ 零循环依赖 ｜ 中文注释零回归 ｜ `noUnusedLocals` + `noUnusedParameters` 已启用。
+
+### 文档导航
+| 你想做什么 | 看哪个文档 | 类型 |
+|-----------|-----------|------|
+| 5 分钟跑起来 | 本 README 的「快速开始」 | 快速入门 |
+| 学怎么完成一次完整交付 | [`docs/SoloForge-开发者操作手册.md`](docs/SoloForge-开发者操作手册.md) | How-to（做）|
+| 贡献一个模板资产 | [`templates/shared/模版贡献指南.md`](templates/shared/模版贡献指南.md) | How-to（做）|
+| 理解为什么这样设计 | [`docs/SoloForge-设计文档.md`](docs/SoloForge-设计文档.md) | Explanation（懂）|
+| 查代码必须遵守什么规则 | [`docs/SoloForge-架构范式契约.md`](docs/SoloForge-架构范式契约.md) | Reference（查）|
+| 发布前要验收什么 | [`docs/正式发布门槛.md`](docs/正式发布门槛.md) | Reference（查）|
 
-- Node.js >= 18
-- TypeScript / ESM
-- 支持的 AI 编程工具（Claude Code / Codex App / Trae IDE）
+> 原则：**想做事看 How-to，想理解看 Explanation，查规则看 Reference**。一个文档只承担一种主要职能，避免既教操作又讲原理导致的混乱。
 
-## 许可证
+## 📄 许可证
 
-MIT
+[MIT](LICENSE) © SoloForge Team