soloforge 1.2.1 → 1.2.3

package/templates/knowledge/patterns/core//344/273/273/345/212/241/347/256/241/347/220/206/345/231/250.md

@@ -0,0 +1,47 @@
+---
+name: job_manager
+type: pattern
+when: "任务管理, checkpoint, heartbeat, 恢复, 认知锚点"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- JobManager 管理 任务生命周期: 创建、更新 checkpoint、heartbeat、恢复、取消
+- CognitiveAnchor 记录阶段、摘要、关键决策、待办事项
+- resumeFromCheckpoint 从最近 checkpoint 恢复任务
+- listActiveJobs 列出活跃任务，过滤过期任务
+- checkpoint 用于中断恢复和进度追踪
+
+## 验收项
+
+- [AC-01] 任务创建返回有效 ID
+- [AC-02] checkpoint 更新正确
+- [AC-03] 过期任务被过滤
+- [AC-04] 恢复从 checkpoint 继续
+
+## 何时使用
+
+advisory: 任务管理是辅助工具，不强制要求使用
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- checkpoint 更新测试通过
+- 恢复测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//344/275/234/347/224/250/345/237/237/344/270/216/345/257/206/351/222/245/346/213/246/346/210/252.md

@@ -0,0 +1,46 @@
+---
+name: scope_hook
+type: pattern
+when: "文件范围, 路径校验, 越权检测, symlink 解析"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- checkScope() 校验文件路径是否在 allowed_paths 范围内
+- symlink 解析后校验真实路径，防止路径穿越
+- 路径匹配使用规范化比较，支持通配符
+- 越权访问为 enforced 级别，违规即 hard fail
+
+## 验收项
+
+- [AC-01] 合法路径通过校验
+- [AC-02] symlink 路径穿越被拦截
+- [AC-03] 越权路径产生 hard fail
+- [AC-04] 通配符匹配正确
+
+## 何时使用
+
+文件范围和安全是强制门禁
+
+## 是否 hard block
+
+是。此能力为 enforced 状态，违规即 hard fail 阻断流程。
+
+## 证据要求
+
+- 路径匹配 + symlink 测试通过
+- 密钥扫描 golden set 通过
+- 无已知越权逃逸
+-
+
+## 人工确认/降级边界
+
+- enforced 能力不可跳过，违反即阻断
+- 降级需经 sf_capability_update + 人工确认，提供 escape report 证据

package/templates/knowledge/patterns/core//344/275/234/347/224/250/345/237/237/347/247/237/347/272/246.md

@@ -0,0 +1,47 @@
+---
+name: scope_lease
+type: pattern
+when: "文件写入, 作用域控制, 租约, 并发写入, 文件锁定"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- 写入文件前必须获取作用域租约（scope lease），同一文件不可被多个任务同时持有
+- 租约包含: task_id、allowed_paths、acquired_at、expires_at
+- 租约超时后自动失效，其他任务可重新获取
+- 任务完成或取消时必须释放租约
+- 租约查询 isLocked() 为 advisory check，不阻断流程
+
+## 验收项
+
+- [AC-01] acquire 返回有效租约，release 后 isLocked 返回 false
+- [AC-02] 同一文件不可被两个任务同时租约
+- [AC-03] 过期租约自动清理
+- [AC-04] clear() 清理所有租约
+
+## 何时使用
+
+advisory: 租约是写入前建议检查，不强制阻断
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- acquire/release 测试通过
+- 过期清理测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core//345/206/262/347/252/201/351/227/250/347/246/201.md

@@ -0,0 +1,47 @@
+---
+name: conflict_gate
+type: pattern
+when: "写入前检查, 冲突检测, CAS 校验, 文件冲突"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-18
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- 写入前执行 CAS（Compare-And-Swap）校验：比较文件当前 hash 与预期 hash
+- CAS 不匹配表示文件被外部修改，必须报告冲突
+- 冲突报告包含: file_path、expected_hash、actual_hash、task_id
+- 统一 CAS + Lease 冲突报告，一个接口返回所有冲突信息
+- markConfirmed() 将冲突标记为已确认，允许写入继续
+
+## 验收项
+
+- [AC-01] 文件未被修改时 preWriteGate 返回无冲突
+- [AC-02] 文件被修改后 preWriteGate 返回 CAS 冲突
+- [AC-03] markConfirmed 后冲突状态更新
+- [AC-04] 租约冲突和 CAS 冲突统一报告
+
+## 何时使用
+
+advisory: 冲突检测是建议性的，开发者可选择覆盖
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- CAS 校验测试通过
+- 冲突报告测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

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

@@ -0,0 +1,52 @@
+---
+name: decision_gateway
+type: pattern
+when: "代码执行, 代码生成, 自动执行, 自动生成, LLM 预算, Token 控制"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-17
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- 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
+- AI 操作分级: light（<2000）/ medium（2000-3000）/ heavy（>3000）
+
+## 验收项
+
+- [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/{mutation_audit.md → /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

@@ -0,0 +1,49 @@
+---
+name: concurrency_lock
+type: pattern
+when: "文件写入, 代码修改, 重构, 全量重构, 大规模验证, 批量操作"
+scope: [shared]
+products: ["*"]
+status: active
+confidence: 1.0
+created_at: 2026-05-17
+updated_at: 2026-05-18
+usage_count: 0
+---
+
+## 决策规则
+
+- 人类主权高于 AI 推演，AI 不得静默覆盖人类的代码修改
+- 作用域租约（scope lease）为 advisory check，不强制阻断操作
+- 租约查询 isLocked() 供开发者参考，可选择忽略
+- ConflictGate preWriteGate 执行 CAS 校验，冲突为 advisory 报告
+- 标记确认 markConfirmed() 后冲突状态更新，允许写入继续
+- 任务完成或取消时建议释放租约（advisory，不强制）
+- P0 已移除持久锁 acquire/release，仅保留 isLocked() 查询
+
+## 验收项
+
+- [AC-01] 租约 acquire/release 测试通过
+- [AC-02] CAS 冲突检测测试通过
+- [AC-03] 锁机制不强制阻断操作
+- [AC-04] 冲突报告包含完整信息供开发者决策
+
+## 何时使用
+
+advisory: 租约是写入前建议检查，不强制阻断
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- acquire/release 测试通过
+- 过期清理测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

package/templates/knowledge/patterns/core/{developer_constitution.md → /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/{streaming_protocol.md → /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/{authority.md → /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 + 人工确认