SoloForge

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

核心原则

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

架构

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。

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

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         # 从项目声明生成端模块约束文本

状态目录

.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。架构残留扫描已经覆盖这两类文件，防止新增适配器重新带回旧入口。

开发与验证

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