soloforge 1.2.2 → 1.2.3

package/templates/knowledge/patterns/core//345/206/263/347/255/226/347/275/221/345/205/263.md

@@ -1,24 +1,23 @@
 ---
 name: decision_gateway
 type: pattern
-when: "代码执行, 代码生成, 自动执行, 自动生成"
+when: "代码执行, 代码生成, 自动执行, 自动生成, LLM 预算, Token 控制"
 scope: [shared]
 products: ["*"]
 status: active
 confidence: 1.0
 created_at: 2026-05-17
-updated_at: 2026-05-17
+updated_at: 2026-05-18
 usage_count: 0
 ---
 
 ## 决策规则
 
-- 置信度阈值 Confidence_Threshold = 0.95，低于此值禁止直接输出执行代码
-- 低于阈值时必须调用 sf_brainstorm 向人类展示三轨方案（极简/工业/激进）
-- LLM Gateway Token 全局预算上限 Budget_Total = 100000
-- LLM Gateway 单任务预算上限 Task_Budget = 30000
-- 熔断触发比 Circuit_Breaker_Ratio = 0.9，超过即硬熔断
-- 重型操作分级 tier=heavy 自动启动流式心跳
+- LLM Gateway Token 全局预算上限 Budget_Total = 100000（advisory，不 hard block）
+- LLM Gateway 单任务预算上限 Task_Budget = 30000（advisory，预算耗尽返回 warning 不阻断）
+- H1 handler 返回 h1_advisory warning，任务仍继续进入 executing
+- 熔断触发比 Circuit_Breaker_Ratio = 0.9，超过即 advisory 告警并建议降级模型
+- 重型操作分级 tier=heavy 自动启动流式心跳（advisory）
 - 心跳间隔 Heartbeat_Interval = 5000 毫秒
 - 控制流操作（classify/scope_resolve/drift_detect 等）走本地，不消耗 Token
 - 决策流操作（intent_refinement/solution_brainstorm/code_generation 等）走 Gateway，消耗 Token
@@ -26,8 +25,28 @@ usage_count: 0
 
 ## 验收项
 
-- [AC-01] 代码执行前检查置信度 >= Confidence_Threshold
-- [AC-02] Token 消耗监控按 operation_type 追踪
-- [AC-03] 熔断后所有 AI 操作返回 circuit_open = true
+- [AC-01] Token 消耗监控按 operation_type 追踪
+- [AC-02] 预算超限返回 advisory warning，不阻断任务
+- [AC-03] 熔断后 AI 操作建议降级模型（advisory）
 - [AC-04] 心跳在重型操作期间每 Heartbeat_Interval 毫秒输出进度
 - [AC-05] 每次请求返回 remaining_budget 和 remaining_task_budget
+
+## 何时使用
+
+advisory: 预算耗尽是 warning 不是 hard fail，不应阻断任务
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- H1/H4 handler 测试通过
+- heartbeat 测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//345/217/230/345/274/202/345/256/241/350/256/241.md

@@ -28,3 +28,23 @@ usage_count: 0
 - [AC-03] 未覆盖行的变异被自动过滤
 - [AC-04] 变异审计未通过时测试文件打回重写
 - [AC-05] 随机种子基于源码内容哈希，可复现
+
+## 何时使用
+
+advisory: 变异测试是质量建议，非强制要求
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- 变异算子测试通过
+- 评分一致性测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//345/233/236/345/275/222/347/237/251/351/230/265.md

@@ -0,0 +1,46 @@
+---
+name: regression_matrix
+type: pattern
+when: "回归测试, fixture 项目, 兼容性验证, 复杂度预算"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- fixture 项目模板: Spring Boot、React、Go 的标准结构
+- 回归矩阵对 fixture 验证 classify/expand/verify 兼容性
+- 复杂度预算: 每个能力模块有代码行数预算，超出产生 advisory
+- fixture 使用真实 detectFingerprint 进行项目检测
+
+## 验收项
+
+- [AC-01] fixture 项目定义完整
+- [AC-02] 回归矩阵覆盖所有 fixture
+- [AC-03] 复杂度预算超出时产生 advisory
+- [AC-04] 真实 detectFingerprint 通过 fixture 检测
+
+## 何时使用
+
+advisory: 回归矩阵是质量保证工具，复杂度超预算不阻断
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- 回归矩阵测试通过
+- 复杂度预算报告正确
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//345/267/245/344/275/234/345/214/272/344/272/222/346/226/245/351/224/201.md

@@ -0,0 +1,44 @@
+---
+name: io_lock
+type: pattern
+when: "互斥锁, 工作区, 并发控制, 写入冲突"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- P0 已移除持久锁 acquire/release，仅保留 isLocked() 查询
+- 锁机制为 advisory check，不强制阻断操作
+- 写入前冲突检测是建议性的，开发者可选择忽略
+
+## 验收项
+
+- [AC-01] isLocked() 查询返回正确状态
+- [AC-02] 写入前冲突检测正常工作
+- [AC-03] 不强制阻断操作
+
+## 何时使用
+
+advisory: 锁机制为 advisory check，不强制阻断
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- isLocked() 查询测试通过
+- 写入前冲突检测测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//345/267/245/344/275/234/345/214/272/345/224/244/351/206/222.md

@@ -0,0 +1,46 @@
+---
+name: resume_workspace
+type: pattern
+when: "会话恢复, 工作区状态, 中断恢复, state 目录"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- scanAndResume() 扫描 state 目录恢复中断任务
+- 恢复是 advisory 级别，新会话可忽略恢复直接新建任务
+- corrupt state 文件降级处理，产生 advisory 报告不阻断
+- 恢复后任务可无缝继续执行
+
+## 验收项
+
+- [AC-01] 中断任务可被恢复
+- [AC-02] corrupt state 不阻断新任务
+- [AC-03] 无活跃任务时不强制恢复
+- [AC-04] 多任务时标记 needs_human_confirm
+
+## 何时使用
+
+advisory: 恢复是最佳实践但非强制，新会话可忽略恢复直接新建任务
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- 中断恢复测试通过
+- corrupt state 处理测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//345/271/266/345/217/221/351/224/201.md

@@ -7,30 +7,43 @@ products: ["*"]
 status: active
 confidence: 1.0
 created_at: 2026-05-17
-updated_at: 2026-05-17
+updated_at: 2026-05-18
 usage_count: 0
 ---
 
 ## 决策规则
 
 - 人类主权高于 AI 推演，AI 不得静默覆盖人类的代码修改
-- 长耗时任务（影响 3+ 文件）写入前必须生成 .soloforge.lock
-- 锁文件包含: task_id、git_tree_hash、file_snapshots（每文件 mtime_ms + size + sha256）
-- 写入前调用 assertClean() 校验 Git Hash 和文件 SHA256
-- 若校验失败抛出 DirtyWorkspaceError，禁止覆盖并报错
-- 任务完成后必须调用 release() 释放锁
-- 已有锁且属于其他任务时，等待或报错，不得强制覆盖
+- 作用域租约（scope lease）为 advisory check，不强制阻断操作
+- 租约查询 isLocked() 供开发者参考，可选择忽略
+- ConflictGate preWriteGate 执行 CAS 校验，冲突为 advisory 报告
+- 标记确认 markConfirmed() 后冲突状态更新，允许写入继续
+- 任务完成或取消时建议释放租约（advisory，不强制）
+- P0 已移除持久锁 acquire/release，仅保留 isLocked() 查询
 
 ## 验收项
 
-- [AC-01] 长耗时任务写入前 .soloforge.lock 存在
-- [AC-02] DirtyWorkspaceError 消息包含冲突文件的文件名和修改时间
-- [AC-03] 锁释放后 .soloforge.lock 文件被删除
-- [AC-04] 任务异常中断后锁不会泄漏（下次 acquire 时检测 stale lock）
+- [AC-01] 租约 acquire/release 测试通过
+- [AC-02] CAS 冲突检测测试通过
+- [AC-03] 锁机制不强制阻断操作
+- [AC-04] 冲突报告包含完整信息供开发者决策
 
-## DirtyWorkspaceError 处理流程
+## 何时使用
 
-1. 向人类展示冲突文件列表和差异概要
-2. 人类选择: 保留人类版本 / 保留 AI 版本 / 手动合并
-3. 根据选择执行: 丢弃 AI 产出 / 覆盖 / 打开合并视图
-4. 重新执行 assertClean() 确认状态干净
+advisory: 租约是写入前建议检查，不强制阻断
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- acquire/release 测试通过
+- 过期清理测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//345/274/200/345/217/221/350/200/205/345/256/252/346/263/225.md

@@ -37,3 +37,23 @@ usage_count: 0
 - [AC-03] 抽检问题基于实际任务摘要生成
 - [AC-04] 逻辑奇点警告以 ⚠ 符号开头并包含具体触发原因
 - [AC-05] core/ 目录下的规则修改需人工签署双重确认
+
+## 何时使用
+
+advisory: 开发者主权的审查建议不 hard block 交付
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- preDeliveryReview 测试通过
+- veto 逻辑测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//346/225/217/346/204/237/344/277/241/346/201/257/346/211/253/346/217/217.md

@@ -0,0 +1,45 @@
+---
+name: secret_scan
+type: pattern
+when: "密钥检测, 敏感信息, gitleaks, 安全扫描"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- detectSecrets() 使用正则匹配 + gitleaks 回退链检测密钥
+- severity=blocked 的密钥（AWS key、API key 等）阻断写入
+- 扫描覆盖写入内容的每一行
+- gitleaks 不可用时回退到内置正则规则
+
+## 验收项
+
+- [AC-01] 已知密钥格式被检测
+- [AC-02] blocked 级别密钥阻断写入
+- [AC-03] gitleaks 回退正常工作
+- [AC-04] 误报率 < 1%
+
+## 何时使用
+
+密钥泄露是最高风险，必须 hard fail
+
+## 是否 hard block
+
+是。此能力为 enforced 状态，违规即 hard fail 阻断流程。
+
+## 证据要求
+
+- golden set 密钥检测通过
+- 误报率测试通过
+- 无已知密钥泄露事件
+
+## 人工确认/降级边界
+
+- enforced 能力不可跳过，违反即阻断
+- 降级需经 sf_capability_update + 人工确认，提供 escape report 证据

package/templates/knowledge/patterns/core//346/262/273/347/220/206/350/277/220/350/241/214/346/227/266/345/276/252/347/216/257.md

@@ -0,0 +1,48 @@
+---
+name: governance_runtime_loop
+type: pattern
+when: "治理闭环, 抽检, 逃逸报告, 能力状态, 审计"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- 治理闭环: sample → escape → report → capability_update
+- 抽检使用风险加权抽样，critical 风险 100% 抽中
+- 逃逸报告记录发现的问题，不自动降级
+- 治理报告汇总全局状态，只读不改
+- 能力状态更新必须经 sf_capability_update + 人工确认
+
+## 验收项
+
+- [AC-01] 抽检→逃逸→报告闭环测试通过
+- [AC-02] 无自动降级行为
+- [AC-03] 状态更新需人工确认
+- [AC-04] report 数据与实际 escape 一致
+
+## 何时使用
+
+advisory: 治理闭环只读不改，状态更新必须经 sf_capability_update + 人工确认
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- 抽检→逃逸→报告→显式更新闭环测试通过
+- MCP handler 闭环测试通过
+- 无自动降级行为
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//346/265/201/345/274/217/345/277/203/350/267/263.md

@@ -34,3 +34,23 @@ usage_count: 0
 ```
 [SoloForge Heartbeat] 代码生成 执行中... 已耗时 10s，当前任务已用 5000/30000 Token
 ```
+
+## 何时使用
+
+advisory: 预算耗尽是 warning 不是 hard fail，不应阻断任务
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- H1/H4 handler 测试通过
+- heartbeat 测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//347/237/245/350/257/206/344/270/273/346/235/203.md

@@ -36,3 +36,23 @@ usage_count: 0
 
 - 连续 3 次 drift 检测均为 code_degradation 时，暂停自动自愈
 - 暂停后需人工审查代码库状态，确认不是 AI 连续敷衍导致的退化
+
+## 何时使用
+
+advisory: 知识治理是建议性的，尚未接入强制门禁
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- 知识模板格式验证测试通过
+- 中文语义化路径测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//350/257/255/344/271/211/350/257/201/346/215/256.md

@@ -0,0 +1,47 @@
+---
+name: semantic_evidence
+type: pattern
+when: "代码交付, 需求覆盖, 验证证据, 语义分析"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- 需求点（requirement_points）必须与代码变更关联，形成可追踪的证据链
+- computeSemanticEvidence 计算每个需求点的覆盖状态：covered / partial / uncovered
+- buildDeliveryEvidenceChain 构建交付证据链，包含需求覆盖 + 变更摘要 + 验证结果
+- 证据链使用 SHA256 hash chain 保证不可篡改
+- 未覆盖需求点生成 advisory 警告，不阻断交付
+
+## 验收项
+
+- [AC-01] 所有需求点都有覆盖状态
+- [AC-02] 证据链 hash 校验通过
+- [AC-03] uncovered 需求点产生 advisory
+- [AC-04] 证据链可验证完整性
+
+## 何时使用
+
+advisory: 需求覆盖是质量建议，uncovered 不阻断交付
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- 语义证据计算测试通过
+- 证据链完整性测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//350/277/220/350/241/214/345/256/211/345/205/250/345/214/205.md

@@ -0,0 +1,50 @@
+---
+name: runtime_safety
+type: pattern
+when: "运行安全, 证据链, 命令分级, 供应链, 迁移回滚"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- 证据 hash chain: SHA256 链式连接，每块包含 prev_hash + chain_hash + data_hash
+- verifyEvidenceChain 从 payload 重算 data_hash，再重算 chain_hash
+- 命令副作用分级: read_only / mutating / destructive
+- destructive 命令（rm -rf、git push --force、DROP TABLE）需人工确认
+- 供应链治理: 验证依赖有 lockfile 和完整性 hash
+- 迁移回滚契约: schema 变更必须有回滚路径
+
+## 验收项
+
+- [AC-01] 证据链构建和验证一致
+- [AC-02] payload 篡改被检测
+- [AC-03] destructive 命令标记需人工确认
+- [AC-04] 无 lockfile 依赖产生 advisory
+- [AC-05] 迁移无回滚命令产生 advisory
+
+## 何时使用
+
+advisory: 只有 destructive 命令需人工确认，其余为 advisory 警告
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- 证据链构建/验证测试通过
+- 命令分级测试通过
+- 供应链检查测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//351/233/266/351/205/215/347/275/256/345/210/235/345/247/213/345/214/226.md

@@ -0,0 +1,47 @@
+---
+name: zero_config_init
+type: pattern
+when: "项目初始化, 技术栈检测, 零配置, fingerprint"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- detectFingerprint 确定性检测项目技术栈
+- 后端检测: pom.xml → Spring Boot、go.mod → Go、Cargo.toml → Rust、build.gradle → Gradle
+- 前端检测: package.json → React/Vue/Angular
+- generateConfigDraft 根据 fingerprint 生成配置草案
+- 检测失败时返回 null，不强制要求配置
+
+## 验收项
+
+- [AC-01] 主流项目类型正确检测
+- [AC-02] 无配置文件时返回 null
+- [AC-03] 配置草案格式正确
+- [AC-04] 多框架共存时分别检测
+
+## 何时使用
+
+advisory: 自动检测是便利功能，可手动配置覆盖
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- fingerprint 检测测试通过
+- 配置草案格式验证通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//351/252/214/350/257/201/345/221/275/344/273/244/347/224/237/346/210/220.md

@@ -0,0 +1,46 @@
+---
+name: verify_command_generation
+type: pattern
+when: "验证, 编译, 测试命令, 项目类型检测"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- generateVerifyCommands 根据项目类型生成编译和测试命令
+- 三个分支: config（有 sf.yaml）、doc-only（无代码项目）、repo（标准项目）
+- repo 分支通过 detectFingerprint 识别技术栈
+- 生成的命令必须可执行，且覆盖编译 + 测试两个阶段
+- 边界项目（无 package.json）必须有 fallback 处理
+
+## 验收项
+
+- [AC-01] config/doc-only/repo 三分支覆盖
+- [AC-02] 生成的命令格式正确
+- [AC-03] 边界项目有 fallback
+- [AC-04] 自定义命令模板覆盖默认命令
+
+## 何时使用
+
+编译和测试命令是质量门禁的基础
+
+## 是否 hard block
+
+是。此能力为 enforced 状态，违规即 hard fail 阻断流程。
+
+## 证据要求
+
+- config/doc-only/repo 三分支测试通过
+- 边界项目（无 package.json）验证通过
+-
+
+## 人工确认/降级边界
+
+- enforced 能力不可跳过，违反即阻断
+- 降级需经 sf_capability_update + 人工确认，提供 escape report 证据