soloforge 1.4.16 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,279 @@
+# 变更日志
+
+本文件记录 SoloForge 的所有重要变更。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/)，版本遵循[语义化版本](https://semver.org/)。
+
+## [未发布]
+
+### 新增
+- **产物契约三分离架构**：Schema + ProcessRules + Validator 三分离框架，覆盖全部 19 种 ArtifactKind
+  - `artifact_schema_registry.ts`：集中注册 19 种产物类型的结构定义（必填章节、表格、字段）
+  - `artifact_process_rules.ts`：按 extract/review/fix/iterate 四操作类型区分的过程规则
+  - `template_schema_loader.ts`：模板 YAML frontmatter 解析加载器（运行时可覆盖 Schema）
+  - L4 产物结构校验：check_write/check_bash Hook 层写入时校验（warning/blocked 分级）
+  - Schema 独立注入通道：绕过三道门预算，产物结构约束始终注入到 prompt
+  - TemplateData→prompt 完整传递链：artifact_schema/process_rules 字段贯穿 11 个 Handlebars 模板
+  - consumable_asset_registry 新增 artifact_schema_ref 字段，关联模板资产与 Schema
+  - 能力登记：CAP-026~CAP-029 四项新能力注册
+- 单体拆分：engine/ 子目录重组为 9 个功能模块（207 个文件）
+- MCP Server 从 adapters/ 提取为独立 server/ 目录
+- E2E 测试套件与 CI/CD 流水线
+- 计划归档文件迁移至 ~/.claude/plans/
+- package.json 添加 `sideEffects: false` 以支持 tree-shaking
+- `lint:full` 脚本：全项目（含 tests/）零警告 ESLint 检查
+- tsconfig 启用 `noFallthroughCasesInSwitch` 严格模式
+- tsconfig 启用 `noUnusedLocals` + `noUnusedParameters` 严格模式
+- `safeJsonParse` / `safeJsonStringify` 安全 JSON 工具函数
+- CLI 子命令注册：`validate-knowledge`、`validate-foundation`
+
+### 修复
+- 管线状态机修复与多领域链路闭环（11 项高严重性安全漏洞修复）
+- 计划 003 路径缺失与计划 001 意图测试扩展至 53 个用例
+- prepublishOnly 缺少 build 步骤
+- hooks.ts JSON 解析失败会清空用户 settings.json 的问题
+- ESM 项目中 require() 导致的运行时崩溃
+- 知识索引 build/watch 并发竞态条件
+- Trae 配置默认值缺陷
+- 空数组 [0] 越界保护（6 处）
+- 不安全 JSON.parse 缺少运行时验证（66 处 → 全部替换为 safeJsonParse）
+- 非空断言消除（31 处 → 0，14 个文件）
+- 显式 any 类型消除（20 处 → 1 处，12 个文件）
+- 静默吞错修复（9 处 `.catch(() => {})` → 添加 debug 日志）
+- 死常量删除（4 处：_SELF_DESTRUCT_PATTERNS 等）
+- 未使用变量/参数修复（43 处，noUnusedLocals/noUnusedParameters 启用）
+- 删除未使用模块 state_update_bypass.ts
+- 7 处 `||` → `??` 安全替换（数组/数值 fallback）
+- 657 项测试 ESLint 问题清零（no-explicit-any, no-unused-vars 等）
+- project_stage_detector 旧/新数据格式兼容性修复
+
+### 变更
+- 链接审计优化：14 个模块重新注册，适配器增强，trae host_type 修复
+- 综合优化：架构违规修复，类型安全，类型拆分，异步 fs，测试性能
+- 测试重构：碎片整合，失败修复，边界覆盖增强，发布门槛清零
+- 批量遗留文件清理，废弃模块移除，配置更新
+- 从 git 追踪中移除 gitignore 的文档文件
+- 11 个 as any 类型绕过 → 具体类型或 unknown 断言
+- 11 个循环依赖修复（类型提取 + 模块拆分 + import 重定向）
+- 删除废弃模块：policy_drift_detector, audit_verifier, extension_scenario deprecated 函数
+- N+1 串行查询 → Promise.allSettled 并行化
+- ESLint 配置：tests/ 允许 any 类型（测试 mock 场景）
+
+## [1.4.16] - 2026-05-28
+
+### 新增
+- Learn/Deliver 工具 schema 新增 `confirm` 和 `authorized` 字段
+
+## [1.4.15] - 2026-05-28
+
+### 新增
+- 计划提案门禁轻量路径：`local_acceptance` 类型自动通过
+
+## [1.4.14] - 2026-05-28
+
+### 变更
+- 统一持久化重构：单次加载共享上下文消除写入覆盖；`setExpansion`/`setArtifact`/`setPlanProposalGate` 支持 `existingCtx` 透传
+
+## [1.4.13] - 2026-05-28
+
+### 修复
+- 轻量路径 S4 门禁跳过；计划提案门禁写入时机修复；`updateStatus` 重复加载防护
+
+## [1.4.12] - 2026-05-28
+
+### 新增
+- 契约 JSON 解析错误增强，头脑风暴会话透传，计划门禁自动设置，轻量路径自动通过
+
+## [1.4.11] - 2026-05-28
+
+### 新增
+- 门禁 `expected_schema` 透传，源码匹配器，扩展管线阶段拆分，E2E 测试覆盖
+
+## [1.4.10] - 2026-05-28
+
+### 新增
+- 意图路由验收路由，契约解析循环重构，扩展管线策略，验证自纠辅助
+
+## [1.4.9] - 2026-05-28
+
+### 修复
+- MCP 索引 JSON 解码，schema 类型修复，发布门槛适配，单元测试覆盖
+
+## [1.4.8] - 2026-05-28
+
+### 变更
+- 作用域解析器重构，工作空间租约增强，影响分析器精简，工具调用链扩展
+
+## [1.4.7] - 2026-05-28
+
+### 新增
+- 扩展平台契约增强，发布门槛补充，工具调用链测试覆盖，CLAUDE.md 硬规则标注
+
+## [1.4.6] - 2026-05-28
+
+### 变更
+- `next_action_planner` 重构，项目知识契约强化，冲突检测器修复，工作流导航测试覆盖
+
+## [1.4.5] - 2026-05-28
+
+### 新增
+- 知识消费边界治理，设计生命周期契约，冲突检测器增强，发布门槛加固
+
+## [1.4.4] - 2026-05-28
+
+### 新增
+- `next_action` 增强，资产注册扩展，可追溯性补充，工作流导航升级
+
+## [1.4.3] - 2026-05-28
+
+### 新增
+- 可追溯性增强，决策研讨扩展，发布门槛加固，工具调用链覆盖
+
+## [1.4.0] - 2026-05-27
+
+### 新增
+- 控制面契约，发布门槛增强，工具调用契约强化
+
+## [1.3.10] - 2026-05-27
+
+### 新增
+- 配置自动修复，发布就绪门禁增强，文档更新
+
+## [1.3.8] - 2026-05-27
+
+### 新增
+- 确认分级机制，下一步导航增强，空项目引导
+
+## [1.3.5] - 2026-05-27
+
+### 修复
+- 步骤 2-3 验收可信度修复，系统能力循环激活
+
+## [1.3.4] - 2026-05-26
+
+### 新增
+- 集中化诊断码，机制自治，知识治理，配置边界，日志治理，健康检查
+- 代码可维护性与可观测性契约
+
+## [1.3.3] - 2026-05-26
+
+### 新增
+- 工作流导航，后端实现契约，OOD/SOLID 设计规则
+
+## [1.3.2] - 2026-05-26
+
+### 新增
+- 标准资产契约，决策研讨，模板可见性治理
+
+## [1.3.1] - 2026-05-26
+
+### 修复
+- 发布修复，依赖漏洞扫描
+
+## [1.3.0] - 2026-05-24
+
+### 新增
+- 构建指令契约，日志治理，证据驱动反幻觉机制
+- 日志治理（问题 59），发布操作手册，仓库整洁归档
+- 发布包冻结复验：陈旧 dist 清理，RC 验收通过
+- 发布候选步骤 2-7：批处理后清理，知识资产标准化，语料回归，init/sync 验收，E2E 冒烟测试，迁移演练
+- 批次 5 真实主路径闭环与文档收敛
+- 批次 4 契约治理：工作流模板包，决策主权，本地验收，演进回归
+- 批次 3 CLI 真实数据闭环：用户修改保护，迁移安全状态修复
+- 批次 2 验证/交付契约全链路闭环
+- 全部英文注释和日志中文化，`check:comments` 防回归
+
+### 修复
+- MCP 连接超时，hook 输入解析，热路径日志噪音降低
+
+## [1.2.18] - 2026-05-21
+
+### 修复
+- npm bin 缺少可执行权限：添加 prepublishOnly chmod +x
+
+## [1.2.17] - 2026-05-21
+
+### 新增
+- 任务状态自动终止：executing/verifying/learning 30 分钟后自动失败
+- 用户提示提交 hook，自动注入 `sf_classify` 提醒
+- 入口路由模块拆分：信号驱动路由 + 后缀驱动素材提取 + 结构化日志
+- 全量运行时日志，中文 JSDoc 注释和注释标准
+- 契约注册系统：工作流、工具调用、输入素材、产物、配置优先级、隐私/密钥/数据主权
+- 机制契约注册表，含事实预校验和终端指针清理
+- 可消费资产注册表，覆盖 161 个内置资产
+- 意图路由器替代 task_type-to-strategy 路由
+- Diff Ownership 阶段 1 和 2：状态模型，CAS 验证，任务生命周期集成，建议性冲突报告
+- 治理阶段 P1-P2：能力注册表，策略 ID 漂移检测，持久化审计池，风险加权采样，逃逸报告，能力行动顾问，治理健康报告，审计采样，MCP 工具扩展（31 个工具）
+- 阶段 1-14：一致性闭环，知识模板完成，作用域租约，冲突合并门禁，恢复工作空间，语义交付证据，变更审计，知识主权，开发者主权，长时运行任务上下文回放，零配置初始化，Java 质量守卫，运行时安全包，真实项目回归
+
+### 变更
+- 移除动态事实污染；项目事实声明式而非硬编码
+
+### 修复
+- 发布门禁假绿消除：35 条规则全覆盖
+- UserPromptSubmit hook 事件名，stdin 输入和 JSON 输出格式
+- 安全加固：23 项审计修复，覆盖哈希/注入/竞态条件/沙箱
+- 场景 A 源码哈希和 artifact_ready 含真实引用与快照哈希证据
+- 测试 TS 类型错误，AssetKind 联合类型构建中断
+- `sf_capability_update` 空 evidence_ids 拒绝
+- P0 处理器生命周期修复和工具注册策略
+- Diff Ownership 阶段 2 scope 目录扩展和三个 preWriteCheck 修复
+- CAS 检查删除边界和反向遍历修复
+- 审计池测试与 process.cwd() 隔离
+
+### 移除
+- 遗留 `setup.sh`（已由回归测试替代）
+- 废弃的 `verify-test-counts` 门槛
+
+## [1.2.1] - 2026-05-17
+
+### 修复
+- `init` 支持 `--project-path`；八维知识文件部署到 templates/
+
+## [1.2.0] - 2026-05-17
+
+### 新增
+- 八维闭环防御与知识层对齐（602 个测试，51 个文件）
+
+## [1.1.2] - 2026-05-17
+
+### 变更
+- 附录重构：A/B/C 附录，100% 覆盖矩阵
+
+## [1.1.1] - 2026-05-17
+
+### 新增
+- `version` 命令（`soloforge version` / `-v` / `--version`）
+
+## [1.1.0] - 2026-05-17
+
+### 新增
+- 五大工程机制与 `sf_explore` 自主技术选型引擎
+- 知识层同步：五大机制 + sf_explore 知识条目
+- Codex `AGENTS.md` 生成，共享工作流模板，适配器清理
+- 中文 JSDoc 注释，脚手架模板注释标准，分类器关键词扩展
+
+### 修复
+- 全量安全审计：命令注入防护，gitleaks 缓存 TTL，watcher 泄漏修复，并行 IO 优化，启用/禁用回退
+- 27 项审计问题修复：Codex hooks 格式，环境检测，深拷贝，合并写入，安全加固
+- 审计完成：3 组单元测试，设计文档数据修正，sf_brainstorm 澄清
+
+## [1.0.0] - 2026-05-15
+
+### 新增
+- SoloForge 阶段 1/2/2.5 完成：MCP 服务器含 9 个工具，48 个知识条目，172 个测试
+- 阶段 3 团队协作：5 个引擎模块 + 5 个 MCP 工具（284 个测试）
+- 阶段 3b Trae IDE 适配器：多 IDE 支持（305 个测试）
+- 阶段 2.6 知识驱动规划 + 架构治理原则（312 个测试）
+- `sf_plan_advance` 工具支持多阶段计划步骤推进
+- Figma 到交付管线模板和原型描述模板
+- 阶段 2.7 知识驱动系统扩展：108 个知识条目 + 18 个 MCP 工具
+- 阶段 3b：模板重命名，原型模板升级，自维护工具隔离
+- 知识条目格式规范与防回归机制
+- 模板内容工业化优化与 `auto_enrich` 机制
+- 阶段 4 持续优化，E2E 验证与发布准备
+
+### 修复
+- 全面评审修复：30 个逻辑缺陷 + 13 个评审问题 + 4 个信息性问题
+- 统一所有模板文件格式
+- `sf_plan_advance` 输出格式与设计文档对齐

package/README.md

@@ -55,17 +55,19 @@ soloforge init --interactive
 所有命令默认作用于当前目录。推荐先 `cd` 到项目根目录再执行。
 
 ```bash
-soloforge init --auto --dry-run      # 只预览，不写入 config.yaml
-soloforge init --auto                # 高置信度时生成项目配置和适配器文件
-soloforge init                       # 生成目录、知识模板和适配器文件，不写 config.yaml
+soloforge init --auto --dry-run      # 只预览，不写入 intent.yaml
+soloforge init --auto                # 高置信度时生成 intent.yaml 和适配器文件
+soloforge init                       # 生成目录、知识模板和适配器文件，不写 intent.yaml
 soloforge init --interactive         # 手动确认项目配置
-soloforge init --adapter claude      # 只生成 Claude Code 配置
+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 新系统   # 指定系统类型（新系统 / 老系统）
 ```
 
-`config.yaml` 是可选文件。没有它时，SoloForge 会根据 `package.json`、`pom.xml`、`go.mod` 等文件在运行时推断项目类型；只有高置信度或你手动确认时，才会把配置写入 `.soloforge/config.yaml`。
+SoloForge 使用三层配置解析：从 `package.json`、`pom.xml`、`go.mod` 等项目文件自动探测技术栈和构建命令；用户偏好（如产品类型、交付设置）存储在可选的 `.soloforge/intent.yaml` 中。探测结果优先于 intent 声明——大多数项目无需手动配置。
 
 配置里的 scope、仓库路径和产物路径都按项目相对路径理解和存储，适配 Windows、macOS、Linux 时不要手写宿主机绝对路径。
 
@@ -73,14 +75,94 @@ soloforge init --adapter all         # 同时生成所有适配器配置
 
 | 位置 | 用途 |
 |------|------|
-| `.soloforge/knowledge/` | 项目知识模板和规则；内置同步资产受 manifest/hash 保护，用户自定义规则会被审计为 hard rule、injectable 或 index_only |
-| `.soloforge/config.yaml` | 可选项目配置，仅在高置信度或手动确认后生成 |
+| `.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 不会覆盖已有知识文件。旧项目补齐新模板或适配器时，优先使用 `sync-templates` 和 `sync-adapters`，不要把 `init` 当作升级命令。
+SoloForge 不会覆盖已有知识文件和管线模板。知识模板同步到 `.soloforge/knowledge/`，管线模板按系统类型同步到 `.soloforge/templates/`（含 shared + 系统专属目录）。旧项目补齐新模板或适配器时，优先使用 `sync-templates` 和 `sync-adapters`，不要把 `init` 当作升级命令。
+
+## 项目知识库维护
+
+SoloForge 在执行任务时会自动从 `.soloforge/knowledge/` 读取匹配的知识文件注入 AI prompt，帮助 AI 理解你的项目规则和业务约束。你可以往里面添加自己的知识文件。
+
+### 文件格式
+
+**必须用 `.md`**（Markdown）。`.yaml` 文件不支持正文注入，对任务执行没有实际效果。
+
+每个文件由 YAML frontmatter（`---` 之间的部分）和 Markdown 正文组成。正文是真正注入 prompt 的内容。
+
+### 最小示例
+
+```markdown
+---
+name: 支付规则
+triggers: ["支付", "结算", "退款", "payment", "refund"]
+scope: [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。
+
+### 注意事项
+
+- **不要和内置模板同名** — 比如 `.soloforge/knowledge/procedures/功能开发流程.md` 会被当作"被篡改的内置文件"而拒绝。用不同的文件名。
+- **已有文件不会被覆盖** — `sync-templates` 不会删除或覆盖你在 `.soloforge/knowledge/` 里创建的任何文件。
+- **`triggers` 决定命中率** — 不填 `triggers` 或写得太窄，知识文件不会被选中。写宽一些（包括中英文同义词）效果更好。
+- **正文要精简** — 注入 prompt 有长度限制，正文控制在关键规则和约束，不要放长篇背景描述。
 
 ## 更新与旧项目同步
 
@@ -122,26 +204,42 @@ soloforge upgrade-design-artifacts --apply --confirm
 
 ## 日常命令
 
+大部分命令支持 `--json` 输出 JSON 格式，方便工具集成。
+
 ```bash
-soloforge validate          # 检查项目配置和知识文件
-soloforge status            # 查看当前项目状态和配置来源
-soloforge next              # 查看当前阶段、阻断项和下一步可执行工作包
-soloforge stage             # 查看项目阶段与当前任务阶段
-soloforge config resolve    # 查看配置解析结果和来源
-soloforge config explain    # 解释某项配置为什么是当前值
-soloforge config repair     # 自动修复配置机械类型错误并重签 evidence
-soloforge audit-project-knowledge # 审计项目自定义知识规则是否可被稳定消费
-soloforge doctor            # 诊断 MCP 控制面、适配器 hook、状态可信和恢复路径
-soloforge version           # 查看版本
+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                     # 查看版本
 ```
 
+多个命令支持 `--project-path <path>` 指定项目路径（非当前目录时使用）。
+
 ### 状态清理与审计
 
 ```bash
 soloforge cleanup --dry-run            # 预览可清理的状态文件
-soloforge cleanup --apply              # 执行清理（默认 dry-run，需显式 --apply）
-soloforge audit-template-mechanisms    # 审计知识资产 schema 完整性
-soloforge audit-design-artifacts       # 审计架构/数据库/API 设计产物包
+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  # 确认后归档旧设计产物并写入升级契约
 ```
@@ -174,10 +272,10 @@ soloforge migrate --apply --confirm     # 执行项目迁移
 - 你手动修改过的模板和适配器文件（如 `CLAUDE.md`）不会被静默覆盖——SoloForge 会检测文件是否被用户修改，修改过的文件在同步时自动跳过并报告。
 - 核心知识模板受保护，即使 apply 也不会被自动同步覆盖。
 - dry-run 中的“应用安全: 需确认”表示发现用户已有文件或需要人工确认；这不是命令失败，只有加 `--apply --confirm` 才会写入。
-- 用户自己新增到 `.soloforge/knowledge/**` 的规则不会被当成普通静态文件。带有 `asset_kind: hard_rule`、`routes`、`primary_triggers` 或 `enforcement.level` 的项目规则会进入审计和任务选择；缺少触发条件的 hard rule 会被 `audit-project-knowledge` 标为阻断。
-- 项目规则进入 `sf_expand` 时会按 intent、route、技术栈和触发词筛选，不会整库塞进 prompt；`sf_review`、`sf_verify`、`sf_deliver` 会在项目规则不可消费或冲突时阻断。
+- 用户自己新增到 `.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 直接拍板，必须先由用户确认。
-- 知识资产与项目规则消费体系受 20 项防回归矩阵约束：模板卫生、脚手架质量、项目知识承载、选择注入、冲突确认、`next` 消费、同步保护、技术栈过滤、设计产物消费、消费 trace 和用户可见解释都必须有真实入口和 release gate。
+- 知识资产与项目规则消费体系受发布门禁矩阵约束：模板卫生、脚手架质量、项目知识承载、选择注入、冲突确认、`next` 消费、同步保护、技术栈过滤、设计产物消费、消费 trace 和用户可见解释都必须有真实入口和 release gate。
 
 **典型升级流程：**
 
@@ -230,7 +328,7 @@ SoloForge 对验证和交付有严格的分层设计：
 - **验证计划不等于验证结果**：SoloForge 会生成验证命令（如 `npm test`），但不会自己执行。只有你或 AI 工具实际执行，并通过 `sf_record_verification_execution` 录入结果后，才被视为已验证。纯计划不等于通过。
 - **未验证不交付**：交付前必须通过真实执行的验证结果。计划阶段的产物、直接构造的通过记录、未执行的验证，都不会触发交付。
 - **证据必须完整**：每条验证结果必须包含完整的执行证据（命令输出哈希、执行时间、唯一证据 ID）并覆盖本次完整 `changed_files`。缺少证据、格式不合法或只验证部分变更文件的记录会被判定为失败。
-- **交付需要显式触发**：交付就绪检查只判断能不能交付，不会自动执行 commit、push 或创建 PR。交付动作必须由 `sf_deliver` 或你手动触发。
+- **交付需要显式触发**：交付就绪检查只判断能不能交付，不会自动执行 commit、push 或创建 PR。交付动作必须由 `sf_stage_advance` 或你手动触发。
 - **交付指标来自真实数据**：交付质量指标从真实 TaskContext 状态目录聚合，不接受空数组、undefined 或构造的通过样本。验证失败会进入修复/复验闭环，不能只报告不修复。
 
 ### 失败处理
@@ -241,7 +339,7 @@ SoloForge 对验证和交付有严格的分层设计：
 - **可修复失败有预算**：重试次数有上限，超预算后停止并升级。
 - **范围不足不越权**：如果失败是因为 scope 不够，SoloForge 会请求扩大范围，不会静默越权写入。
 - **错误信息已脱敏**：失败报告中的敏感信息（密钥、密码、原始输出）会自动脱敏，只保留摘要和哈希。
-- **项目知识可审计**：项目自定义规则必须能说明适用路由、触发词、生命周期阶段、文件路径、业务域和技术栈。能执行的规则会以 SelectionDecision 形式说明是否选中、命中的信号、强制级别、验证命令和恢复路径；只适合作为背景资料的规则会标为 `index_only`，不得冒充已执行约束。`soloforge next`、`sf_expand`、`sf_review`、`sf_verify`、`sf_deliver` 和 `audit-project-knowledge` 消费同一份决策结果，避免各入口各说各话。
+- **项目知识可审计**：项目自定义规则必须能说明适用路由、触发词、生命周期阶段、文件路径、业务域和技术栈。能执行的规则会以 SelectionDecision 形式说明是否选中、命中的信号、强制级别、验证命令和恢复路径；只适合作为背景资料的规则会标为 `index_only`，不得冒充已执行约束。`soloforge next`、`sf_code_review`、`sf_gate_check`、`sf_stage_advance` 和 `audit-project-knowledge` 消费同一份决策结果，避免各入口各说各话。
 - **历史问题机制化**：新反馈不会只按表面文件或单个场景处理。SoloForge 的发布门禁要求历史问题先归入长期机制族，并具备第一性原理不变量、生产入口、用户项目路径、must-fail 和 must-pass。
 
 ### 安全护栏
@@ -292,9 +390,9 @@ soloforge init
 
 ## 常见问题
 
-### `soloforge init --auto` 没有生成 config.yaml
+### `soloforge init --auto` 没有生成 intent.yaml
 
-这是正常行为。SoloForge 只有在项目指纹足够明确时才会自动写配置。你可以继续使用运行时推断，也可以执行 `soloforge init --interactive` 手动确认。
+这是正常行为。SoloForge 只有在项目指纹足够明确时才会自动写 intent.yaml。大多数项目通过文件探测即可获得完整配置；你也可以执行 `soloforge init --interactive` 手动确认偏好设置。
 
 ### AI 工具没有调用 SoloForge
 
@@ -320,17 +418,17 @@ soloforge doctor
 
 先按 `doctor` 输出的恢复命令处理。旧项目需要补齐新增模板或适配器文件时，使用 `sync-templates` / `sync-adapters`；新项目首次接入时才运行 `soloforge init`。
 
-如果 `status` 提示 `version` 数字/字符串、`scope` 字符串/数组或 `config.evidence.json` 过期，这属于机械配置问题，不需要逐字段人工确认：
+如果 `status` 提示配置不完整（缺少 tech_stack 或 build_commands），可以通过配置命令补充：
 
 ```bash
-soloforge config repair --dry-run
-soloforge config repair
+soloforge config check         # 检查配置完整性和冲突
+soloforge config set <field>   # 写入缺失的 intent.yaml 字段
 soloforge validate
 soloforge status
 soloforge next
 ```
 
-`config repair` 会先备份旧配置，再修复可安全归一化的 YAML 类型并重签 evidence。业务口径变更仍由 `config confirm` 或人工决策处理。
+`config set` 通过 AI 对话或 MCP 工具 `sf_config_update` 写入 intent.yaml 中的用户偏好字段（如 product_profile、delivery）。技术栈和构建命令由项目文件自动探测，无需手动配置。
 
 ### 想清理项目中的 SoloForge 文件
 
@@ -375,22 +473,25 @@ npm test             # 等价于 npm test -- --run
 SoloForge 维护者在发布前必须依次执行以下命令，全部通过才能进入 Release Candidate：
 
 ```bash
-# 1. 编译（clean build）
-npm run build
+# 1. 编译 + 类型检查 + lint（三合一）
+npm run build && npx eslint . --max-warnings 0
 
-# 2. 测试类型检查（tsconfig.test.json 编译 tests/**/*.ts）
-npm run lint:tests
+# 2. 全量测试
+npm test
 
-# 3. 全量测试
-npm test -- --run
+# 3. 中文注释防回归
+npm run check:comments
 
-# 4. 发布门禁（文本输出）
+# 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. 用户项目可用性抽查
+# 6. 循环依赖检查
+npx madge --circular --extensions ts src/
+
+# 7. 用户项目可用性抽查
 REPO_DIR=$(pwd)
 TMPDIR=$(mktemp -d) && cd "$TMPDIR"
 node "$REPO_DIR/dist/bin/soloforge.js" init
@@ -398,20 +499,31 @@ 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`。
+当前代码质量基线：tsc 零错误 | 293 测试文件 / 5305 测试全部通过 | eslint 零警告 | 零循环依赖 | 中文注释零回归 | `noUnusedLocals` + `noUnusedParameters` 已启用。
 
 <details>
-<summary>内部说明：validate-release 与历史施工回归的区别</summary>
-
-- `npm run validate-release` 是 SoloForge 正式发布门禁，检查构建产物、机制消费、模板完整等长期产品结构。
-- `npm run validate-batch*` 是历史施工回归检查，用于确认早期功能修复后没有回归，不代表正式发布通过。该检查由维护者按需执行，不写入普通用户文档。
+<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 才能发布。
 
 </details>
 

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

@@ -1,6 +1,7 @@
+import type { ProjectConfig } from "../../types/index.js";
 /**
  * 生成 CLAUDE.md 项目指令文件内容。
  * 只记录生成文本实际包含对应内容的资产 trace，trace 含章节 hash 证明。
  */
-export declare function generateClaudeMd(config: import("../../types.js").ProjectConfig): string;
+export declare function generateClaudeMd(config: 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":"AA+BA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,gBAAgB,EAAE,aAAa,GAAG,MAAM,CAuBvF"}
+{"version":3,"file":"claude_md.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2B1D;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAuB9D"}

package/dist/adapters/claude_code/claude_md.js

@@ -1,8 +1,8 @@
 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 { getContractByPath } from "../../engine/template_asset_contract_registry.js";
-import { debug } from "../../engine/logger.js";
+import { recordConsumptionTrace, CONSUMER_FIELD_CONTRACTS } from "../../engine/templates/consumption_trace_store.js";
+import { listConsumableAssetsByConsumer } from "../../engine/templates/consumable_asset_registry.js";
+import { getContractByPath } from "../../engine/templates/template_asset_contract_registry.js";
+import { debug } from "../../engine/core/logger.js";
 /** 计算章节内容 hash: 字符数:行数:首尾字符码 */
 function computeSectionHash(text, sectionHeader) {
     const idx = text.indexOf(sectionHeader);
@@ -17,7 +17,7 @@ function computeSectionHash(text, sectionHeader) {
 const ASSET_CONTENT_CHECKS = {
     "adapter-workflow-template": (t) => {
         const hasWorkflow = /^## 强制工作流/m.test(t) && /@sf-hard-rule/.test(t);
-        const hasSteps = /### 步骤 \d+/.test(t);
+        const hasSteps = /### 原则 \d+/.test(t);
         const hash = computeSectionHash(t, "## 强制工作流");
         return { pass: hasWorkflow && hasSteps, proof: `section=强制工作流 hash=${hash}` };
     },
@@ -47,7 +47,7 @@ export function generateClaudeMd(config) {
                 asset_path: asset.path,
                 fields_consumed: CONSUMER_FIELD_CONTRACTS.adapter_prompt,
                 matched_reason: `CLAUDE.md content_verified consumed ${asset.id} ${checkResult.proof}`,
-                task_id_or_route: "claude-md",
+                task_id_or_pipeline_id: "claude-md",
                 consumed_at: new Date().toISOString(),
                 declared_consumer: contract?.mainline_consumer,
             });