soloforge 1.1.2 → 1.1.30

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

@@ -0,0 +1,76 @@
+---
+name: authority
+when: '知识更新, 知识自愈, 知识进化, 模式漂移, 自进化'
+scope:
+  - shared
+products:
+  - '*'
+id: ka-pattern-authority
+asset_kind: pattern
+lifecycle_status: active
+authority: supporting
+routes:
+  - '*'
+primary_triggers:
+  - 知识更新
+  - 知识自愈
+  - 知识进化
+  - 模式漂移
+  - 自进化
+priority: P2
+specificity: 3
+version: 1.0.0
+last_reviewed: '2026-05-22'
+consumes: []
+emits: []
+secondary_triggers: []
+negative_triggers: []
+type: pattern
+status: active
+---
+
+## 决策规则
+
+- knowledge/patterns/core/ 为人工维护只读区，AI 严禁修改
+- AI 进化产物只能写入 knowledge/patterns/temp/
+- 自进化机制（evolve）生成的知识条目经 KnowledgeWriter 写入 temp/
+- KnowledgeWriter.promoteToActive() 路由所有 pattern 类型到 patterns/temp/
+- updateKnowledge() 检测 core/ 路径时直接拒绝，返回知识隔离错误
+- drift_ratio >= 0.3 时触发漂移检测，根因分析判定:
+  - code_degradation: 安全规则违反，禁止更新知识库
+  - business_evolution: 多文件普遍违反，允许更新知识库（仅 temp/）
+  - unknown: 人工审核后决定
+- drift_ratio >= 0.5 且 code_degradation 时触发逻辑奇点警告
+
+## 验收项
+
+- [AC-01] core/ 目录下任何文件无法通过 AI 工具修改
+- [AC-02] evolve() 写入的条目路径包含 temp/
+- [AC-03] updateKnowledge() 对 core/ 条目返回"知识隔离"错误
+- [AC-04] KnowledgeWriter.isCorePath() 正确识别 core/ 路径
+- [AC-05] 自进化知识条目 status 从 staged → active 的路径仅经过 temp/
+
+## 逆向退化防护
+
+- 连续 3 次 drift 检测均为 code_degradation 时，暂停自动自愈
+- 暂停后需人工审查代码库状态，确认不是 AI 连续敷衍导致的退化
+
+## 何时使用
+
+advisory: 知识治理是建议性的，尚未接入强制门禁
+
+## 是否 hard block
+
+否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
+
+## 证据要求
+
+- 知识模板格式验证测试通过
+- 中文语义化路径测试通过
+-
+
+## 人工确认/降级边界
+
+- 此能力可被开发者决策覆盖
+- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
+- 降级/禁用需经 sf_capability_update + 人工确认

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

@@ -0,0 +1,64 @@
+---
+name: semantic_evidence
+when: '代码交付, 需求覆盖, 验证证据, 语义分析'
+scope:
+  - shared
+products:
+  - '*'
+id: ka-pattern-semantic_evidence
+asset_kind: pattern
+lifecycle_status: active
+authority: supporting
+routes:
+  - '*'
+primary_triggers:
+  - 代码交付
+  - 需求覆盖
+  - 验证证据
+  - 语义分析
+priority: P2
+specificity: 3
+version: 1.0.0
+last_reviewed: '2026-05-22'
+consumes: []
+emits: []
+secondary_triggers: []
+negative_triggers: []
+type: pattern
+status: active
+---
+
+## 决策规则
+
+- 需求点（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/internal/patterns//350/277/220/350/241/214/345/256/211/345/205/250/345/214/205.md

@@ -0,0 +1,68 @@
+---
+name: runtime_safety
+when: '运行安全, 证据链, 命令分级, 供应链, 迁移回滚'
+scope:
+  - shared
+products:
+  - '*'
+id: ka-pattern-runtime_safety
+asset_kind: pattern
+lifecycle_status: active
+authority: supporting
+routes:
+  - '*'
+primary_triggers:
+  - 运行安全
+  - 证据链
+  - 命令分级
+  - 供应链
+  - 迁移回滚
+priority: P2
+specificity: 3
+version: 1.0.0
+last_reviewed: '2026-05-22'
+consumes: []
+emits: []
+secondary_triggers: []
+negative_triggers: []
+type: pattern
+status: active
+---
+
+## 决策规则
+
+- 证据 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/internal/patterns//351/233/266/351/205/215/347/275/256/345/210/235/345/247/213/345/214/226.md

@@ -0,0 +1,64 @@
+---
+name: zero_config_init
+when: '项目初始化, 技术栈检测, 零配置, fingerprint'
+scope:
+  - shared
+products:
+  - '*'
+id: ka-pattern-zero_config_init
+asset_kind: pattern
+lifecycle_status: active
+authority: supporting
+routes:
+  - '*'
+primary_triggers:
+  - 项目初始化
+  - 技术栈检测
+  - 零配置
+  - fingerprint
+priority: P2
+specificity: 3
+version: 1.0.0
+last_reviewed: '2026-05-22'
+consumes: []
+emits: []
+secondary_triggers: []
+negative_triggers: []
+type: pattern
+status: active
+---
+
+## 决策规则
+
+- 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/internal/patterns//351/252/214/350/257/201/345/221/275/344/273/244/347/224/237/346/210/220.md

@@ -0,0 +1,63 @@
+---
+name: verify_command_generation
+when: '验证, 编译, 测试命令, 项目类型检测'
+scope:
+  - shared
+products:
+  - '*'
+id: ka-pattern-verify_command_generation
+asset_kind: pattern
+lifecycle_status: active
+authority: supporting
+routes:
+  - '*'
+primary_triggers:
+  - 验证
+  - 编译
+  - 测试命令
+  - 项目类型检测
+priority: P2
+specificity: 3
+version: 1.0.0
+last_reviewed: '2026-05-22'
+consumes: []
+emits: []
+secondary_triggers: []
+negative_triggers: []
+type: pattern
+status: active
+---
+
+## 决策规则
+
+- 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 证据

package/templates/internal/rules/OOD/344/270/216SOLID/350/256/276/350/256/241/350/247/204/345/210/231.md

@@ -0,0 +1,62 @@
+---
+name: OOD与SOLID设计规则
+scope:
+  - backend
+  - frontend
+products:
+  - '*'
+id: ka-hard-rule-OOD与SOLID设计规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-ood-solid-contract
+asset_role: required
+consumed_by:
+  - mc-ood-solid-contract
+routes:
+  - code_change
+  - artifact_generation
+  - multi_stage_plan
+primary_triggers:
+  - 面向对象设计
+  - SOLID
+secondary_triggers:
+  - 领域服务
+  - 重构
+  - 策略
+negative_triggers:
+  - 文案
+  - 样式
+priority: P1
+specificity: 5
+consumes:
+  - mc-coding-readiness
+hard_blocks:
+  - ood_summary_missing
+  - solid_hard_fail_unresolved
+fallback: manual_required
+required_evidence:
+  - ood_design_summary
+  - code_review_findings
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+## 编码前门禁
+
+复杂业务逻辑、领域模型、服务边界、策略或重构任务在编码前必须给出：
+
+- 对象及单一职责。
+- 对外接口与依赖方向。
+- 可变化点与扩展方式。
+- SRP、OCP、LSP、ISP、DIP 风险及验证方式。
+
+## 代码审查门禁
+
+- Controller 不承担业务计算或持久化职责。
+- 应用/领域服务依赖抽象端口，不直接构造基础设施依赖。
+- 子类型不能拒绝父契约操作，接口不能迫使实现提供无效操作。
+- 同一类型或状态的多处分支应判断是否需要策略扩展点。
+
+硬失败未清零时，不得交付。简单文案或样式修改不强行引入对象设计。

package/templates/internal/rules//344/272/247/347/211/251/345/245/221/347/272/246/350/247/204/345/210/231.md

@@ -0,0 +1,57 @@
+---
+name: 产物契约规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-产物契约规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-artifact-contract
+routes:
+  - 产物契约规则
+primary_triggers:
+  - 产物契约规则
+secondary_triggers: []
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - mc-workflow-contract
+hard_blocks:
+  - 产物scope外
+  - force_overwrite
+fallback: manual_required
+required_evidence:
+  - output_artifact
+  - artifact_status
+version: 1.0.0
+last_reviewed: '2026-05-22'
+migration_note: 知识资产标准化迁移
+type: hard_rule
+when: 产物契约规则
+status: active
+---
+
+# 产物契约规则
+
+## 核心约束
+
+1. 产物必须通过 `artifact_contract_registry` 注册，包含 kind、format、path、overwrite_policy。
+2. 产物生命周期：draft → verified → accepted。跳过阶段必须显式声明 `skip_verification`。
+3. `overwrite_policy` 仅允许 `fail_if_exists` 或 `versioned`。禁止 `force_overwrite`。
+4. 产物路径必须在 `declared_scope` 内。scope 外产物触发 hard_fail。
+5. 所有产物变更必须通过 `sf_verify` 验证后才能推进状态。
+
+## 适用场景
+
+- 单产物生成 (`single_artifact`)
+- 多阶段计划产物交付 (`multi_stage_plan`)
+- 代码执行产物 (`code_execution`)
+
+## 违规处理
+
+- 未注册产物 → hard_fail，阻断交付
+- scope 外产物 → hard_fail，阻断写入
+- 跳过验证且无声明 → advisory，标记降级

package/templates/internal/rules//344/273/243/347/240/201/346/263/250/351/207/212/344/270/216/346/227/245/345/277/227/345/245/221/347/272/246/350/247/204/345/210/231.md

@@ -0,0 +1,150 @@
+---
+name: 代码注释与日志契约规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-代码注释与日志契约规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-code-maintainability-observability-contract
+routes:
+  - code_change
+  - artifact_generation
+  - operation
+  - multi_stage_plan
+primary_triggers:
+  - 业务编码
+  - 接口实现
+  - 状态流转
+  - 支付
+  - 权限
+  - 迁移脚本
+  - 数据修复
+secondary_triggers:
+  - Service
+  - Controller
+  - UseCase
+  - Handler
+  - Router
+  - Form
+  - Store
+  - 异常处理
+negative_triggers:
+  - 文案
+  - 样式
+  - getter
+  - setter
+  - fixture
+priority: P0
+specificity: 5
+consumes:
+  - mc-coding-readiness
+hard_blocks:
+  - code_observability_work_package_missing
+  - sensitive_log_leak
+  - catch_swallow
+  - missing_log_critical
+  - missing_comment_complex_unresolved
+  - missing_class_doc
+  - missing_method_doc
+  - missing_important_line_comment
+  - non_chinese_log
+  - non_chinese_comment
+fallback: manual_required
+required_evidence:
+  - code_observability_work_package
+  - review_findings
+  - verification_result
+version: 1.0.0
+last_reviewed: '2026-05-26'
+---
+
+## 注释契约
+
+### 中文 Javadoc 必须具备
+- Java/Kotlin 后端类、接口、枚举、记录必须有中文文档注释，说明类型职责、业务边界和使用场景。
+- 后端每个业务方法必须有中文文档注释，说明方法作用；有入参时说明参数语义；有返回值时说明返回对象或结果含义。
+- Controller、Service、UseCase、DomainService、Repository、Mapper、DTO、VO、Request、Response、Entity 等均适用。
+- 关键业务行必须有中文行注释，尤其是事务双写、状态流转、级联删除、账号联动、外部调用、审计写入、补偿和回滚边界。
+- 允许保留英文代码标识符，但业务说明、风险说明、参数说明、返回说明必须中文表达。
+
+### 必须有注释
+- 业务规则不直观时
+- 领域不变量（如"一个用户同一时间只能有一个有效业务办理"）
+- 金额、账单、折扣、支付、退款、核验逻辑
+- 状态流转逻辑（如 pending → paid → refunded）
+- 幂等、分布式锁、事务、并发控制
+- 权限、安全、审计判断
+- 外部系统兼容、历史包袱、第三方接口限制
+- 复杂 SQL、复杂查询条件、非显而易见算法
+- 前端复杂交互规则：权限控制、状态流转、表单联动、乐观更新/回滚、支付与敏感操作
+
+### 必须禁止
+- 每行废话注释
+- 复述代码字面含义的注释
+- 注释与代码行为不一致
+- 注释承诺了代码没有做到的安全性、幂等性或事务性
+- 用户项目业务注释全英文
+- 只写 `{@inheritDoc}` 但没有说明本实现的业务边界、入参和出参
+
+## 日志契约
+
+### 必须有日志
+- 用户登录、登出、认证失败
+- 权限拒绝、越权访问
+- 创建、修改、删除关键业务对象
+- 状态变更、金额变更、支付、退款、折扣、核验
+- 合同、业务办理、账单、证照、人员角色变更
+- 外部 API 调用失败、超时、重试
+- 异步任务开始、成功、失败、重试、跳过
+- 数据修复、批处理、迁移脚本
+- 捕获异常后继续执行
+- 降级、兜底、补偿逻辑
+- 前端关键交互：表单提交、状态变更、权限动作、支付/敏感操作、上传导入、API 调用失败
+
+### 日志必须具备
+- 中文事件名或中文动作说明
+- 事件名或动作名
+- 业务对象 ID
+- 操作人或系统来源
+- traceId / correlationId（如果项目已有）
+- 失败原因
+- 关键状态变化前后值
+- 合理日志级别
+
+### 必须禁止
+- 裸 console.log（生产代码）
+- 生产代码遗留调试日志
+- catch 后无日志直接吞异常
+- 只打印 "error"、"failed" 这类不可定位日志
+- 用户项目业务日志全英文
+- 打印 password、token、secret、cookie、身份证全量、手机号全量、银行卡全量、健康隐私
+- 高频循环里刷屏日志
+- 日志拼接大对象导致性能或隐私问题
+
+## 项目 logger 识别
+- Java/Spring: Slf4j + LoggerFactory
+- Node/Express/NestJS: pino, winston, NestJS Logger, 项目封装 logger
+- Python/FastAPI、Go handler、.NET、Ruby 等后端: 使用项目现有 logger 或先建立 logger 包装
+- NestJS: Logger
+- React/Vue/Svelte 等前端: 项目封装 logger、埋点或错误上报，生产环境禁止裸 console
+- 如果项目没有 logger，要求先建立项目 logger 包装
+
+## 跨技术栈适用范围
+- 后端不限定 Spring：Controller、Service、UseCase、Handler、Router、Resolver、ViewSet、Repository、Mapper 等写操作都适用。
+- 前端不限定框架：React、Vue、Svelte、移动端页面和状态 store 的业务提交、状态变更、权限动作和 API 失败都适用。
+- Entity、Request、Response、VO、DTO、Schema、Serializer、Model 等用户项目契约类的业务字段需要中文含义说明或 Schema 注解。
+- Java Entity 使用 Getter/Setter 分层访问策略；DTO、VO、Request、Response 使用 Data 风格承载边界数据，不得混用导致领域模型语义被抹平。
+
+## 严重度
+- P0 阻断: 敏感信息泄漏、catch 吞异常、支付/金额/权限变更无日志
+- P1 阻断: 状态流转无日志、复杂规则无注释、后端类/方法中文 Javadoc 缺失、关键行中文注释缺失、中文日志缺失、外部调用无日志、裸 console.log
+- P2 警告: 日志级别不合理、上下文字段不足
+- P3 建议: 普通可读性优化
+
+## 低风险跳过
+- 纯样式、文案、简单 getter/setter、简单类型定义、测试 fixture
+- 低风险只读查询且已有统一 access log
+- 简单配置修改、一次性本地实验代码

package/templates/internal/rules//344/273/273/345/212/241/344/270/212/344/270/213/346/226/207/347/224/237/345/221/275/345/221/250/346/234/237/350/247/204/345/210/231.md

@@ -0,0 +1,65 @@
+---
+name: 任务上下文生命周期规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-任务上下文生命周期规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-task-context-lifecycle
+asset_role: required
+consumed_by:
+  - mc-task-context-lifecycle
+  - consumable_asset_registry
+  - knowledge_injection
+routes:
+  - 任务上下文生命周期规则
+primary_triggers:
+  - 任务上下文生命周期规则
+secondary_triggers:
+  - TaskContext
+  - 任务上下文
+  - task_context
+negative_triggers: []
+priority: P1
+specificity: 5
+consumes:
+  - mc-task-context-lifecycle
+hard_blocks:
+  - TaskContext 混入推理过程
+  - TaskContext 包含 stdout/stderr 原文
+  - TaskContext 包含 secret
+  - 无效状态转换
+fallback: manual_required
+required_evidence:
+  - status_transition_log
+  - fact_accumulation_report
+version: 1.0.0
+last_reviewed: '2026-05-23'
+---
+
+# 任务上下文生命周期规则
+
+## hard_rules
+
+- TaskContext 只保存可恢复工程事实（facts、refs、status、evidence id），禁止存储推理过程、chain-of-thought、原始 stdout/stderr 和 Batch 临时字段。
+- 状态转换必须经过 transition gate 验证：created → in_progress → verifying → delivering → completed | failed | degraded。
+- `verify()` 后的 TaskContext 必须 freeze，后续修改必须走 `repair_reverify` 路径。
+- `TaskContextSnapshot` 必须在每次状态转换时生成，用于审计和回滚。
+- 敏感信息（secret、token、credential）禁止写入 TaskContext，必须使用 SecretReference 间接引用。
+- `cleanup()` 不得删除被 evidence 引用的 TaskContext 条目。
+
+## not_done_if_missing
+
+- TaskContext 混入 chain-of-thought 或 secret → hard fail。
+- 无效状态转换（如 created → completed）→ hard fail。
+- cleanup 删除被引用的 evidence → hard fail。
+- TaskContext 不可恢复（进程重启后丢失关键事实）→ degraded。
+
+## verification_evidence
+
+- `tests/engine/task_context.test.ts` 覆盖状态转换、字段过滤、snapshot 生成。
+- `status_transition_gate` 运行时检查阻断无效转换。
+- `diagnostic_codes`: invalid-transition, forbidden-field, evidence-deleted。