# SoloForge

SoloForge 是面向 AI 编程宿主的工程验证与任务交付控制面。它把“如何生成产物”“即时反馈、权威验证”“审查闭环”和“任务状态推进”拆成独立职责，避免一个大型工作流引擎同时理解所有领域和副作用。

## 核心原则

- Skills 指导 AI 研讨和生成具体产物。
- Hooks 只做低延迟、只读的 quick 检查。
- `VerificationService` 是完整验证的唯一权威入口。
- Validators 只返回 findings，不写状态。
- `TaskService` 只理解动作需要哪些证据，以及证据是否有效。
- 完整验证记录按任务绑定，并通过产物内容、完整验证输入、规则集和引擎摘要判断新鲜度。
- 不为已删除入口保留 alias、redirect、公共导出 或宽松 schema。

## 架构

```text
AI Host
  Claude Code
  OpenCode (experimental)
      |
      +-- Skills: 产物生成指导
      +-- Hooks: quick 即时反馈
      |
CLI / MCP
      |
VerificationService
  +-- ArtifactResolver
  +-- ValidatorRunner
  +-- DigestBuilder
  +-- FreshnessPolicy
  +-- EvidenceWriter
      |
Validators + Evidence Store
      |
TaskService
  +-- EvidenceRequirementPolicy
  +-- EvidenceEvaluator
      |
advance / deliver
```

`VerificationService` 是薄门面。内部按 `input/`、`execution/`、`evidence/`、`persistence/`、`policy/` 和 `quick/` 分层，防止服务或任一注册表重新膨胀成大型 engine。

`TaskService` 不读取需求文档、API 规格或数据库设计内容。阶段和动作所需证据由声明式 policy 提供，生命周期服务只消费证据报告。

产品判断以真实用户链路为准：安装必须把 MCP、hooks、CLAUDE.md 和完整 skills 送达；quick 只提示；full 对真实产物和完整源码失败关闭；报告与 `sf_review` 各自承担用户交付和权威审查证据，不能互相冒充。

## 安装

前置要求：Node.js 18 或更高版本，以及 Claude Code。

```bash
npm install -g soloforge
cd /path/to/project
soloforge init
```

`soloforge init` 生成：

- `.mcp.json`：SoloForge MCP 连接。
- `CLAUDE.md`：从当前工具契约和领域契约生成的项目指令。
- `.claude/settings.json`：危险操作保护和通用 quick hook。
- `~/.claude/skills/soloforge-*/`：产物生成 skills、模板及定制正反例。

已有项目需要覆盖 SoloForge 管理文件时使用 `soloforge init --force`。只预览写入内容时使用 `soloforge init --dry-run`。

## 标准工作流

1. 接手已有项目或 SoloForge 版本变化时，首次 `sf_verify`/`sf_task` 操作会自动检查升级状态并在需要迁移时阻断提示；升级状态见 `.soloforge/upgrade/`，诊断用 `soloforge doctor`（V2 无独立升级 MCP 工具）。
2. 调用 `sf_task start`，显式提供 intent、system_context 和 scope。
3. 用当前目标、业务术语、scope 和能力域调用 `sf_knowledge query`，读取真正相关的项目/内置 guidance；空结果不代表“没有约束”，也不能覆盖已确认项目事实。
4. 选择一个产物对应的 skill，研讨必要决策后由 AI 宿主编辑真实文件。涉及前端时，端模块必须先经用户确认并写入 `intent.projects`（`.soloforge/intent.yaml`）；`soloforge project-modules` 输出为空时，先在 intent 确认端模块清单再继续设计，不能只在文档中自造目录或发布拓扑。
5. PostToolUse 调用 `soloforge hook-check`。它只提供即时反馈，不写 EvidenceView，不推进任务。
6. 调用 `sf_verify full`，显式传 `task_id` 和 `artifact`，执行完整验证并写权威记录。
7. 需要语义审查时通过 `sf_review start/submit/status/resolve/auto_fix` 完成独立审查和 finding 闭环。
8. 当前阶段证据全部通过且仍然新鲜后，调用 `sf_task advance`。
9. 最终调用 `sf_task deliver`。缺失、失败、过期或未闭环的证据都会阻断交付。

## Governance Runtime

Governance Runtime 是 V2 治理内核，在 `sf_plan` 生成 ExecutionPlan 时注入 governance extension（Policy 要求 + Decision 记录），形成可审计的治理闭环。

核心能力（均已实现）：

- **Policy governance**：声明式 Policy 文件（`.soloforge/state/governance/policies/*.json`）驱动 requirement 声明，`sf_plan` 自动注入。
- **Decision traceability**：每次 governance 触发生成 `GovernanceDecisionRecord`（含 policyIds/requirementIds/policyMetadata 来源链），持久化到 `.soloforge/state/governance/decisions/`。
- **Audit query**：`sf_governance_history` 查询决策审计摘要（只读，不泄露 governanceResult）。
- **Coverage metrics**：`sf_governance_report` 聚合覆盖率（totalDecisions/generated/failed/skipped 原因/policyUsage）。
- **Effectiveness**：`sf_governance_effectiveness` 聚合有效性（failureRate/policyEffectiveness/requirementCompletionRate）。
- **Evidence fulfillment**：`sf_governance_fulfillment` 查询 Requirement 完成状态（经 EvidenceSource 链接 VerificationEvidence，target → artifact_kind 显式映射）。

Governance Engine 保持纯函数（不碰 store/evidence），IO 边界由 Provider/Adapter 承担。

## Quick 与 Full

| 模式 | 入口 | 写权威状态 | 用途 |
|---|---|---:|---|
| quick | `soloforge hook-check` 或 `soloforge verify --check-only` | 否 | 编辑后的低延迟反馈 |
| full | `sf_verify action="full"` 或 `soloforge verify --task ... --artifact ...` | 是 | 阶段推进和交付证据 |

Hook 被禁用、超时、未触发或被 Bash 绕过，不会降低最终正确性，因为 `sf_task advance` 和 `sf_task deliver` 只认可 full 记录。

Full 记录（`VerificationEvidence`，`kind: "artifact_structure"` 维度）至少包含：

- `schema_version: 3`
- `evidence_id`
- `task_id`
- `kind: "artifact_structure"`
- `passed`
- `evaluated_at`
- `engine_revision`
- `evidence_source`
- `artifact`: { `artifact_kind`, `domain`, `gate_name`, `artifact_path`, `artifact_git_hash`, `verification_input_hash`, `ruleset_hash`, `findings`, `check_results` }
- `verification_run_id`（引用验证执行记录，防手写伪造 passed）

产物内容、上游产物、任务 scope/system context、项目配置、研讨记录、适用 waiver、规则集或引擎版本任一变化，旧记录都会失效。

## MCP 工具

| 工具 | Action / 入参 | 职责 |
|---|---|---|
| `sf_task` | `start/query/advance/deliver/reset/cancel` | 任务生命周期和证据门禁 |
| `sf_verify` | `full/status` | 完整验证权威入口与记录查询 |
| `sf_review` | `start/submit/status/resolve/auto_fix` | 独立对抗审查和 finding 闭环 |
| `sf_knowledge` | `query/audit/add/update` | 按任务信号读取 guidance/knowledge，并管理项目知识 |
| `sf_plan` | `task_id` | V2：从 Requirement 生成 ExecutionPlan 并持久化（不执行 step/不改 requirement）|
| `sf_requirement` | `action` | V2：RequirementContract 需求 CRUD（create 写 manual requirement / list 按 task 列出 / query 按 id 查），经 HMAC 签名 |
| `sf_waiver` | `create/list/revoke` | 豁免生命周期入口（create/revoke 需 confirm=true 人工裁决，non_waivable check 拒绝），经 HMAC 签名 |
| `sf_execute` | `task_id` | V2：跑 command verification 写 VerificationEvidenceStore，供 deliver 消费 |
| `sf_repair` | `task_id` | V2 修复计划生成器：retry 上限卡住或机械重试无进展时生成分型建议；常规失败循环不需要（不执行 repair/不改文件）|
| `sf_evidence_graph` | `task_id` | 只读查询 task 证据图摘要（Finding→Resolution→Artifact）|
| `sf_governance_history` | `task_id` | 只读查询 governance 决策审计摘要 |
| `sf_governance_report` | `task_id` | 只读聚合 governance 覆盖率报告 |
| `sf_governance_effectiveness` | `task_id` | 只读聚合 governance 有效性指标 |
| `sf_governance_fulfillment` | —（全局查询）| 只读查询 governance requirement 完成状态 |

诊断用 CLI `soloforge doctor`；升级影响查看 `.soloforge/upgrade/`（V2 无独立升级/诊断/豁免 MCP 工具，升级隐式经 `sf_verify`/`sf_task` 阻断提示）。

## CLI

```bash
soloforge                         # 启动 MCP server
soloforge mcp                     # 显式启动 MCP server
soloforge init [--dry-run] [--force]
soloforge doctor [--json]
soloforge skills                  # 同步内置 skills
soloforge scope-check             # 危险路径保护 hook
soloforge bash-check              # 危险命令保护 hook
soloforge hook-check              # 通用 quick 路由器
soloforge verify --task <id> --artifact <kind> [--json]
soloforge verify --check-only --path <path> [--task <id>]
soloforge project-modules         # 从项目声明生成端模块约束文本
```

## 状态目录

```text
.soloforge/
  state/current-task.json
  state/tasks/{task_id}.json
  state/evidence/{evidence_id}.json
  reviews/{review_id}.json
  reviews/{review_id}/baseline/...
  waivers/{waiver_id}.json
  locks/{store}/{record}.lock
```

EvidenceView 记录 `task_id`，消费时必须匹配当前任务；review 与 waiver 同样强制保存 `task_id`。权威写入使用按业务主键划分的跨进程锁和原子替换。旧 schema 不做宽松读取；发现无效记录时失败关闭，由升级流程一次性清理或重建。

## 产物与 Skills

每个产物的写作说明、模板和定制正反例位于 `skills/{artifact}/SKILL.md`、`skills/{artifact}/template.md` 与 `skills/{artifact}/examples.md`。正例只定义质量下限，必须替换为项目真实值；反例用于识别空话、占位和不可验证内容，不能复制进正式产物。`templates/` 只保留运行时 enforced、可查询 guidance/knowledge 和 scaffold，不再保存第二份产物写作模板或带固定阈值的产品画像。

常见产物包括需求分析、原型说明、架构设计、数据库设计、API 规格、开发切片计划、代码、测试计划、审查报告、测试报告、部署配置和发布说明。具体适用性由 task scope 和领域契约决定。

容器组合运行资产只在解析后的 `deployment.method` 为 `docker_compose` 时成为证据。Compose 检查只验证它能确定的事实（服务、本地 build context 和 Dockerfile），不强制 nginx、每工程独立 Dockerfile 或其他特定部署形态。使用平台构建、本地服务或其他运行方式的项目不会被要求为通过验证而创建 Compose、nginx 或 Playwright 文件；operate 阶段仍需如实记录实际运行与恢复方式。

## 适配器状态

Claude Code 是当前正式适配器。生成的 `CLAUDE.md` 和 hooks 直接使用本 README 中的架构与工具集。

OpenCode 目前仅为 experimental。核心 CLI/MCP 虽然平台无关，但在 skill 发现、hook payload、阻断语义和真实端到端流程完成验证前，不宣称稳定支持，也不由 `soloforge init` 默认写入。

未来支持 Codex 不需要复制验证或任务内核。Codex 适配器只需从同一工具契约、领域契约和 skills 生成 `AGENTS.md`、`.codex/config.toml` 等宿主文件，并完成真实客户端回放；在这些回放进入发布门禁前同样不能宣称 supported。架构残留扫描已经覆盖这两类文件，防止新增适配器重新带回旧入口。

## 开发与验证

```bash
npm install
npm run typecheck
npm run typecheck:tests
npm run lint:all
npm run check:dead-code
npm run check:production-reachability
npm test
npm run ai:check
npm run validate-release
```

发布校验会扫描 `src/`、`tests/`、`templates/`、`docs/`、`scripts/`、`skills/`、`dist/`、`.claude/`、`.codex/`，并真实回放 `.mcp.json`、`CLAUDE.md`、hooks 和安装后的 15 个 skills，再检查 npm 实际入包清单。已删除入口、Unicode 章节符号、实施任务编号式注释、缺失正反例或生成物漂移都会阻断发布。

## 安全边界（诚实声明）

SoloForge 的保证是**确定性地板**（产物存在/schema/写保护/HMAC/freshness/门禁，单机诚实 AI 场景不依赖 AI 诚实执行流程）+ best-effort 审查兜底。下列三条是已知架构边界——单机诚实 AI 场景"抬高门槛"足够，对抗不诚实 AI（可经解释器/osascript 残口读删 keychain）或走向团队/CI/生产时需评估，`soloforge doctor`（full）会在【安全边界提示】段如实列出：

**总括边界（一切具体边界的上位命题）**：本地环境的验证、签名、豁免与诊断在本地被完整控制时可被同时破坏——检测器可被注释、密钥可被读取、豁免可被直写、doctor 可被伪造输出。SoloForge 提高的是疏漏与退化的发现概率（元锁/验签/fail-closed/必拦矩阵让破坏需要" deliberate 且成体系"），不提供对本地完整控制者的防御。最终信任根在平台侧（远端门禁/CI 平台保护/外部签名锚点）；本地一切结论在跨出本机时只是"自述"。

- **confirm 自签（默认部署）**：未配置 `SOLOFORGE_AUTH_TOKEN` 时，`confirm=true` 即可授权豁免任意**非 `non_waivable`** check（waive/resolve 等）。配置 `SOLOFORGE_AUTH_TOKEN` 后 confirm 不再授权，须显式 `authorization_token`。普通单机诚实场景可不配；对抗或团队场景建议配置。
- **HMAC 密钥 keychain 不可移植 + fail-closed**：证据（gate/review/waiver/upgrade 记录）用 OS keychain 密钥签名（macOS `security`/Linux `secret-tool`，init 随机生成；Windows/不支持平台降级 FS `.soloforge/secret/hmac.key`）。读取侧 **fail-closed**：密钥不可用时对声称 passed 的记录不信任（排除），不跳过验签——**密钥丢失/未 init 将致全部历史证据需重验**（务必备份 keychain 条目或 FS 文件）；密钥 per-init 随机，不可跨机器复用（CI/团队无法复用彼此的"已通过"记录）。
- **维护审查闭环为流程提醒非安全门**：SoloForge 自身发版的独立审查门禁（`validate-release` 的 `ai:review --verify`）校验 `last-review.json` 形状与 `change_hash`，但 `change_hash` 可由维护者自行计算——它提醒"做过审查"，不证明"真做了独立审查"。诚实维护者有效，无法阻止不诚实的维护者。
- **resign 是恢复通道不是防伪证明**：`resign-tasks --all`（E1）可在密钥轮换/验签失败收敛时对存量记录重签，重签记录与原始记录在事后不可区分——重签动作本身须由可信的操作者在可信的终端执行（confirm+旧 hmac 落审计是流程约束，不是密码学证明）。

OS keychain 已落地（1.1.148，macOS/Linux）；HMAC 读取侧已 fail-closed（密钥不可用不跳过验签）。剩余根治（confirm 自签 / HMAC 密钥可被同机进程经 node-e/osascript 残口读删）需外部不可伪造锚点（外部签名服务 / HSM / 宿主证明）或 breaking 变更，属架构演进方向，当前以"可见性 + 诚实标注 + fail-closed"处理。对抗不诚实 AI 或团队/CI 场景建议配置 `SOLOFORGE_AUTH_TOKEN` 并评估外部签名方案。


## License

MIT