soloforge weekly downloads statistics

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…