# SoloForge

AI 编程助手的项目工作流配置器。SoloForge 帮你把 Claude Code、Codex App、Trae IDE 接入同一套项目规则、知识模板和验证习惯，让 AI 在你的项目里更少误判、更少乱写、更容易交付可检查的结果。

## 适合谁

- 你已经在用 Claude Code、Codex App 或 Trae IDE 写代码。
- 你希望每个项目都有稳定的 AI 工作流规则，而不是每次从零解释。
- 你希望 AI 修改代码前先理解项目边界，生成产物时不要误改源码。
- 你希望配置可以自动推断，但不要在低置信度时乱写项目配置。
- 你希望 AI 写业务代码时能遵守必要注释、结构化日志、敏感信息脱敏和交付复验要求。

## 核心能力

- **下一步导航**: `soloforge next` 会根据当前阶段、阻断项和已有证据提示下一步，而不是只报告状态。
- **设计产物包审计**: 需求、原型、架构、详细设计、切片、实现、测试和验收按统一生命周期合同审计，避免文档之间漂移。
- **工程实现契约**: 编码阶段会约束 OOD/SOLID、Controller/Handler/Router 入参出参、参数校验、事务、幂等、权限、日志和错误处理等实现细节。
- **注释与日志治理**: 后端写操作、前端关键交互、状态变更、支付/权限/安全路径、异常处理和迁移脚本需要可定位日志、埋点/错误上报或必要注释；敏感信息不得进入日志。
- **MCP 控制面可信**: `soloforge doctor` 会检查 MCP 配置、适配器 hook、任务状态和恢复路径；AI 绕过 MCP 直接篡改 `.soloforge/state` 会被 hook 拦截，非 MCP 来源的代码变更不能冒充完整可信交付。
- **长期机制化门禁**: SoloForge 自身发布前会检查机制消费链路、知识治理、配置落盘边界、日志治理和诊断码集中注册，防止只靠文档或测试自证。

## 最短成功路径

```bash
# 1. 全局安装
npm install -g soloforge

# 2. 进入项目根目录
cd /path/to/my-project

# 3. 预检：查看 SoloForge 会识别出什么，不写入配置
soloforge init --auto --dry-run

# 4. 初始化项目
soloforge init --auto

# 5. 重新打开你的 AI 工具，让它加载新配置
# Claude Code: 退出后在项目目录重新启动 claude
# Codex App: 重新打开项目目录
# Trae IDE: 重新打开项目目录

# 6. 检查状态
soloforge validate
soloforge status
```

如果 `init --auto` 提示置信度不足，改用：

```bash
soloforge init --interactive
```

## 初始化方式

所有命令默认作用于当前目录。推荐先 `cd` 到项目根目录再执行。

```bash
soloforge init --auto --dry-run      # 只预览，不写入 config.yaml
soloforge init --auto                # 高置信度时生成项目配置和适配器文件
soloforge init                       # 生成目录、知识模板和适配器文件，不写 config.yaml
soloforge init --interactive         # 手动确认项目配置
soloforge init --adapter claude      # 只生成 Claude Code 配置
soloforge init --adapter codex       # 只生成 Codex App 配置
soloforge init --adapter trae        # 只生成 Trae IDE 配置
soloforge init --adapter all         # 同时生成所有适配器配置
```

`config.yaml` 是可选文件。没有它时，SoloForge 会根据 `package.json`、`pom.xml`、`go.mod` 等文件在运行时推断项目类型；只有高置信度或你手动确认时，才会把配置写入 `.soloforge/config.yaml`。

配置里的 scope、仓库路径和产物路径都按项目相对路径理解和存储，适配 Windows、macOS、Linux 时不要手写宿主机绝对路径。

## 生成文件

| 位置 | 用途 |
|------|------|
| `.soloforge/knowledge/` | 公司全局知识库：项目规则和模板；内置同步资产受 manifest/hash 保护，用户自定义规则会被审计为 hard rule、injectable 或 index_only |
| `.soloforge/templates/` | 管线阶段模板：artifacts（输出模板）、rules（规则）、gates（门禁配置），按系统类型同步，用户修改过的文件不会被覆盖 |
| `.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 配置 |

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: 支付规则
when: "支付, 结算, 退款, payment, refund"
scope: [backend]
products: ["*"]
---

## 业务规则
1. 退款金额不得超过原支付金额
2. 跨境支付需走外汇审批流程

## 约束条件
- 所有金额单位为分（整数）
- 支付超时时间 30 分钟
```

### 放在哪个目录

在 `.soloforge/knowledge/` 下按类型分子目录：

```
.soloforge/knowledge/
  domain/                → 业务领域规则（支付、权限、工作流等）
  procedures/            → 自定义流程
  checklists/            → 自定义验收清单
  acceptance_templates/  → 自定义产物模板
  review_rules/          → 自定义审查规则
  drafts/                → sf_knowledge_add 的默认输出位置
```

也可以自建子目录。只要文件路径不和内置模板重名，都会被当作"用户自建文件"放行。

### frontmatter 字段

| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
| `name` | 否 | 文件名 | 注入 prompt 时显示的标题 |
| `when` | **是** | `""` | 触发关键词，逗号分隔。AI 任务意图匹配到这些词时才会选中这条知识 |
| `scope` | 否 | `["shared"]` | 作用域：`backend`、`frontend`、`shared`。`shared` 匹配所有 |
| `products` | 否 | `["*"]` | 适用产品线，`*` 匹配所有 |
| `routes` | 否 | `["*"]` | 适用路由（`operation`、`code_change` 等），`*` 匹配所有 |
| `status` | 否 | `"active"` | 只有不填或 `active` 才会被使用 |
| `type` | 否 | 从目录名推断 | 用于分类过滤 |

### SoloForge 如何使用你的知识

1. **索引** — 运行任务时，SoloForge 扫描 `.soloforge/knowledge/` 下所有 `.md` 文件
2. **匹配** — 根据任务的意图关键词和 `when` 字段做匹配
3. **注入** — 匹配到的文件正文写入 AI prompt 的 `## 适用知识` 段落

知识注入有预算上限（默认 5 条），按优先级排序。你的项目知识优先级低于 SoloForge 内置核心规则，但高于全局 patterns。

### 注意事项

- **不要和内置模板同名** — 比如 `.soloforge/knowledge/procedures/功能开发流程.md` 会被当作"被篡改的内置文件"而拒绝。用不同的文件名。
- **已有文件不会被覆盖** — `sync-templates` 不会删除或覆盖你在 `.soloforge/knowledge/` 里创建的任何文件。
- **`when` 决定命中率** — 不填 `when` 或写得太窄，知识文件不会被选中。写宽一些（包括中英文同义词）效果更好。
- **正文要精简** — 注入 prompt 有长度限制，正文控制在关键规则和约束，不要放长篇背景描述。

## 更新与旧项目同步

用户升级已发布的全局 CLI：

```bash
npm update -g soloforge
# 或强制安装最新发布版
npm install -g soloforge@latest

soloforge --version
```

旧项目补齐新增模板、规则或适配器文件：

```bash
cd /path/to/my-project

soloforge sync-templates
soloforge sync-adapters

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 时才运行 `soloforge init`。已经有 `.soloforge/` 的旧项目，优先用同步和审计命令；如果只是 AI 工具配置缺失，可按 `doctor` 输出的恢复命令处理。

## 日常命令

```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           # 查看版本
```

### 状态清理与审计

```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 也不会被自动同步覆盖。
- 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` 会在项目规则不可消费或冲突时阻断。
- 项目规则可用 `conflict_group` + `rule_value` 或 `conflicts_with` 声明互斥口径，例如 API 响应格式、分页格式、日志字段、数据库命名和权限模型。冲突不会由 AI 直接拍板，必须先由用户确认。
- 知识资产与项目规则消费体系受 20 项防回归矩阵约束：模板卫生、脚手架质量、项目知识承载、选择注入、冲突确认、`next` 消费、同步保护、技术栈过滤、设计产物消费、消费 trace 和用户可见解释都必须有真实入口和 release gate。

**典型升级流程：**

```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     # 确认后迁移
```

## 使用时你会看到什么

接入成功后，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_deliver` 或你手动触发。
- **交付指标来自真实数据**：交付质量指标从真实 TaskContext 状态目录聚合，不接受空数组、undefined 或构造的通过样本。验证失败会进入修复/复验闭环，不能只报告不修复。

### 失败处理

当验证或执行失败时：

- **确定性失败不重试**：相同的错误反复出现时，SoloForge 会升级给你处理，不会无限重试。
- **可修复失败有预算**：重试次数有上限，超预算后停止并升级。
- **范围不足不越权**：如果失败是因为 scope 不够，SoloForge 会请求扩大范围，不会静默越权写入。
- **错误信息已脱敏**：失败报告中的敏感信息（密钥、密码、原始输出）会自动脱敏，只保留摘要和哈希。
- **项目知识可审计**：项目自定义规则必须能说明适用路由、触发词、生命周期阶段、文件路径、业务域和技术栈。能执行的规则会以 SelectionDecision 形式说明是否选中、命中的信号、强制级别、验证命令和恢复路径；只适合作为背景资料的规则会标为 `index_only`，不得冒充已执行约束。`soloforge next`、`sf_expand`、`sf_review`、`sf_verify`、`sf_deliver` 和 `audit-project-knowledge` 消费同一份决策结果，避免各入口各说各话。
- **历史问题机制化**：新反馈不会只按表面文件或单个场景处理。SoloForge 的发布门禁要求历史问题先归入长期机制族，并具备第一性原理不变量、生产入口、用户项目路径、must-fail 和 must-pass。

### 安全护栏

SoloForge 在运行时执行以下强制护栏：

- **只读保护**：被分类为只读的任务（分析、文档生成等）不能修改项目源码。
- **写入范围保护**：代码修改只能在声明的 scope 路径内进行，超出范围的写入会被阻断。
- **状态保护**：已失败的任务不能被直接标记为完成，需要先修复并重新验证。
- **并发保护**：同一个文件范围不会被两个任务同时写入。
- **隐私保护**：密钥、凭证和个人信息在存储前自动脱敏。

这些护栏不会降级或关闭。如果误判，你可以通过配置覆盖或人工确认解除。

## 产物输出

文档、分析报告、源码包提取结果等非代码产物默认写入：

```text
.soloforge/output/
```

例如让 AI “从 `/tmp/prototype.zip` 抓取原型说明”，SoloForge 会把它作为只读外部材料处理，要求产物写入 `.soloforge/output/**`，而不是修改项目源码。

## Cursor 说明

Cursor 暂无内置适配器。可以先生成 `.mcp.json`，再手动复制到 `.cursor/mcp.json`：

```bash
soloforge init
```

示例：

```json
{
  "mcpServers": {
    "soloforge": {
      "command": "soloforge",
      "args": ["mcp"],
      "env": { "SOLOFORGE_PROJECT": "/absolute/path/to/my-project" }
    }
  }
}
```

保存后重载 Cursor 窗口。

## 常见问题

### `soloforge init --auto` 没有生成 config.yaml

这是正常行为。SoloForge 只有在项目指纹足够明确时才会自动写配置。你可以继续使用运行时推断，也可以执行 `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` 提示 `version` 数字/字符串、`scope` 字符串/数组或 `config.evidence.json` 过期，这属于机械配置问题，不需要逐字段人工确认：

```bash
soloforge config repair --dry-run
soloforge config repair
soloforge validate
soloforge status
soloforge next
```

`config repair` 会先备份旧配置，再修复可安全归一化的 YAML 类型并重签 evidence。业务口径变更仍由 `config confirm` 或人工决策处理。

### 想清理项目中的 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

`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

# 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/artifacts/, templates/rules/, templates/gates/, templates/internal/, 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
- TypeScript / ESM
- 支持的 AI 编程工具（Claude Code / Codex App / Trae IDE）

## 许可证

MIT
