soloforge 1.3.1 → 1.3.3

package/templates/knowledge/acceptance_templates/OOD/350/256/276/350/256/241/346/221/230/350/246/201/346/250/241/347/211/210.md

@@ -0,0 +1,60 @@
+---
+name: OOD设计摘要模版
+when: '面向对象设计, SOLID, 复杂业务实现'
+scope:
+  - backend
+  - frontend
+products:
+  - '*'
+id: ka-artifact_template-OOD设计摘要模版
+asset_kind: artifact_template
+lifecycle_status: active
+authority: supporting
+owner_mechanism_id: mc-ood-solid-contract
+routes:
+  - artifact_generation
+  - code_change
+primary_triggers:
+  - OOD设计摘要
+secondary_triggers:
+  - SOLID
+negative_triggers: []
+priority: P1
+specificity: 5
+consumes:
+  - mc-ood-solid-contract
+emits:
+  - acceptance_report
+required_evidence:
+  - ood_design_summary
+  - code_review_findings
+version: 1.0.0
+last_reviewed: '2026-05-26'
+type: acceptance_template
+status: active
+---
+
+# OOD/SOLID 设计摘要
+
+## 适用性
+
+- 任务：
+- 适用/不适用理由：
+
+## 对象与职责
+
+| 对象/模块 | 单一职责 | 协作者 | 禁止承担的职责 |
+|---|---|---|---|
+| | | | |
+
+## 接口与依赖方向
+
+| 接口/端口 | 提供者 | 消费者 | 依赖方向 | 替换/测试策略 |
+|---|---|---|---|---|
+| | | | | |
+
+## 变化点与 SOLID 复验
+
+| 变化点 | SRP | OCP | LSP | ISP | DIP | 复验证据 |
+|---|---|---|---|---|---|---|
+| | | | | | | |

package/templates/knowledge/acceptance_templates//345/220/216/347/253/257/345/256/236/347/216/260/351/252/214/346/224/266/346/270/205/345/215/225.md

@@ -0,0 +1,46 @@
+---
+name: 后端实现验收清单
+when: '后端实现验收, API编码, Controller, Service'
+scope:
+  - backend
+products:
+  - '*'
+id: ka-artifact_template-后端实现验收清单
+asset_kind: artifact_template
+lifecycle_status: active
+authority: supporting
+owner_mechanism_id: mc-backend-implementation-contract
+routes:
+  - code_change
+  - verification_only
+primary_triggers:
+  - 后端实现验收清单
+secondary_triggers:
+  - API实现
+negative_triggers: []
+priority: P1
+specificity: 5
+consumes:
+  - mc-backend-implementation-contract
+emits:
+  - acceptance_report
+required_evidence:
+  - backend_work_package
+  - verification_result
+version: 1.0.0
+last_reviewed: '2026-05-26'
+type: acceptance_template
+status: active
+---
+
+# 后端实现验收清单
+
+| 检查项 | 结论 | 权威证据 | 失败修复 |
+|---|---|---|---|
+| 请求 DTO 与字段校验 | | | |
+| 响应 DTO、分页与错误码 | | | |
+| 事务和状态流转 | | | |
+| 幂等与并发冲突 | | | |
+| 权限、租户和审计 | | | |
+| OpenAPI 与 migration 对齐 | | | |
+| 自动化测试和负向案例 | | | |

package/templates/knowledge/procedures/OOD/350/256/276/350/256/241/345/267/245/344/275/234/346/265/201.md

@@ -0,0 +1,50 @@
+---
+name: OOD设计工作流
+type: procedure
+when: '面向对象设计, SOLID, 领域服务, 业务规则实现, 重构'
+scope:
+  - backend
+  - frontend
+products:
+  - '*'
+id: ka-procedure-OOD设计工作流
+asset_kind: procedure
+lifecycle_status: active
+authority: supporting
+owner_mechanism_id: mc-ood-solid-contract
+routes:
+  - code_change
+  - artifact_generation
+primary_triggers:
+  - OOD设计工作流
+secondary_triggers:
+  - SOLID
+negative_triggers:
+  - 文案修改
+priority: P1
+specificity: 5
+consumes:
+  - mc-ood-solid-contract
+emits:
+  - ood_design_summary
+  - code_review_findings
+required_evidence:
+  - execution_evidence
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+## 步骤
+
+1. 判断任务是否确实存在对象边界或变化点，简单改动记录不适用理由。
+2. 列出对象职责、接口、依赖方向和主要协作流程。
+3. 对五项 SOLID 原则逐项说明适用风险与取舍。
+4. 编码后执行审查和验证，以实际源码 finding 为准。
+5. 存在硬失败则修复并重验，不能仅在报告中解释。
+
+## 输出摘要
+
+| 对象/模块 | 单一职责 | 依赖接口 | 变化点 | SOLID 风险 | 验证证据 |
+|---|---|---|---|---|---|
+| | | | | | |

package/templates/knowledge/procedures//345/205/250/347/224/237/345/221/275/345/221/250/346/234/237/345/267/245/344/275/234/346/265/201/345/257/274/350/210/252.md

@@ -0,0 +1,100 @@
+---
+name: 全生命周期工作流导航
+type: procedure
+when: '下一步, 继续, 现在能写代码吗, 工作流导航, navigation, 阶段判断, 工作包生成'
+scope:
+  - backend
+  - frontend
+products:
+  - '*'
+id: ka-procedure-全生命周期工作流导航
+asset_kind: procedure
+lifecycle_status: active
+authority: supporting
+owner_mechanism_id: mc-workflow-navigation-contract
+routes:
+  - operation
+  - multi_stage_plan
+  - artifact_generation
+primary_triggers:
+  - 全生命周期工作流导航
+secondary_triggers:
+  - 下一步
+  - 继续
+  - 现在能写代码吗
+  - 阶段导航
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - mc-workflow-navigation-contract
+  - current_task_context
+  - project_configuration
+  - design_artifact_audit
+  - repair_reverify_directive
+emits:
+  - next_action_plan
+  - executable_work_package
+  - prohibited_actions
+required_evidence:
+  - project_stage
+  - task_stage
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+# 全生命周期工作流导航
+
+本流程定义了从项目初始化到发布后的完整工作流导航决策树。
+
+## 项目生命周期阶段
+
+| 阶段 | 判断条件 | 下一步 |
+|------|----------|--------|
+| 未初始化 | .soloforge/ 不存在或无 config.yaml | 运行 soloforge init |
+| 配置待确认 | config.yaml 存在但字段未确认 | 运行 soloforge config confirm |
+| 知识就绪 | 配置已确认、知识库已索引 | 提交开发意图开始新任务 |
+| 设计进行中 | 设计产物存在但未通过审计 | 完成设计并通过审计 |
+| 实现就绪 | 设计产物已通过审计 | 制定开发切片计划 |
+| 开发进行中 | 有任务在编码/验证阶段 | 继续编码和验证 |
+| 交付就绪 | 任务已通过验证 | 进行交付验收 |
+| 已发布 | 已交付上线 | 进入观察期 |
+| 发布后观察 | 发布后验证阶段 | 监控、反馈、回滚预案 |
+
+## 任务生命周期阶段
+
+任务从分类到交付的完整流程：
+
+1. 输入材料收集 → 2. 需求明确化 → 3. 决策研讨 → 4. 架构设计 → 5. 详细设计 → 6. 数据库设计 → 7. API 设计 → 8. 切片规划 → 9. 编码实现 → 10. 本地验证 → 11. 测试 → 12. 代码审查 → 13. 修复复验 → 14. 交付验收 → 15. 发布准备 → 16. 发布后观察
+
+## 导航决策流程
+
+1. 调用 `sf_navigation` 或 `soloforge next` 获取当前状态
+2. 检查是否有陈旧任务需要处理
+3. 读取返回的 work_package，按描述执行下一步
+4. 遵守 disallowed_actions 中的禁止动作
+5. 执行完成后运行 acceptance_commands 验证
+6. 如需用户确认，暂停并等待确认后再继续
+
+## 陈旧任务处理
+
+当 current-task.json 指向旧任务时：
+- 选择"恢复"：继续旧任务从上次中断处开始
+- 选择"归档"：将旧任务标记为归档，清理指针
+- 选择"新建"：归档旧任务后开始新任务
+- 不得绕过 SoloForge 直接操作
+
+## 常见导航场景
+
+**场景: 用户说"继续"**
+→ 调用 sf_navigation 获取 work_package，按描述执行
+
+**场景: 用户说"现在能写代码吗"**
+→ sf_navigation 检查项目阶段和设计审计状态，返回允许或阻断原因
+
+**场景: 用户说"审查后做什么"**
+→ sf_navigation 检查 code_review 结果，推荐下一步验证或交付
+
+**场景: 用户说"发布后做什么"**
+→ sf_navigation 返回发布后观察工作包：验证、监控、反馈收集

package/templates/knowledge/procedures//345/220/216/347/253/257/346/216/245/345/217/243/345/256/236/347/216/260/345/267/245/344/275/234/346/265/201.md

@@ -0,0 +1,50 @@
+---
+name: 后端接口实现工作流
+type: procedure
+when: '后端接口, Controller, DTO, API实现, 数据写入'
+scope:
+  - backend
+products:
+  - '*'
+id: ka-procedure-后端接口实现工作流
+asset_kind: procedure
+lifecycle_status: active
+authority: supporting
+owner_mechanism_id: mc-backend-implementation-contract
+routes:
+  - code_change
+  - artifact_generation
+primary_triggers:
+  - 后端接口实现工作流
+secondary_triggers:
+  - REST API
+negative_triggers: []
+priority: P1
+specificity: 5
+consumes:
+  - mc-backend-implementation-contract
+emits:
+  - backend_work_package
+  - verification_result
+required_evidence:
+  - execution_evidence
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+## 步骤
+
+1. 确认 OpenAPI、数据库 migration、权限与状态流转基线。
+2. 定义请求 DTO、响应 DTO、字段校验、错误码和分页排序边界。
+3. 定义应用服务事务边界、幂等策略、并发控制和审计事件。
+4. 编码并执行单元、集成、权限、重复提交与契约一致性验证。
+5. 审查 finding 清零并提供验收证据后交付。
+
+## 工作包
+
+| 类别 | 需明确内容 | 证据 |
+|---|---|---|
+| 接口边界 | DTO、统一响应、错误码、分页 | OpenAPI/测试 |
+| 一致性 | 事务、幂等、并发、状态流转 | migration/集成测试 |
+| 安全 | 权限、租户、审计、隐私 | 越权测试/审计日志 |

package/templates/knowledge/review_rules/SOLID/344/273/243/347/240/201/345/256/241/346/237/245/350/247/204/345/210/231.md

@@ -0,0 +1,40 @@
+---
+name: SOLID代码审查规则
+type: review_rule
+when: '代码审查, SOLID, 面向对象设计, controller, service'
+scope:
+  - backend
+  - frontend
+products:
+  - '*'
+id: ka-review-rule-SOLID代码审查规则
+asset_kind: review_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-ood-solid-contract
+routes:
+  - code_change
+primary_triggers:
+  - SOLID代码审查规则
+secondary_triggers:
+  - 重构
+negative_triggers: []
+priority: P1
+specificity: 5
+required_evidence:
+  - code_review_findings
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+## 阻断项
+
+| 原则 | 阻断表现 | 修复方向 |
+|---|---|---|
+| SRP | Controller 承担事务、持久化或业务计算 | 下沉至应用服务并只保留协议映射 |
+| LSP | 子类型对父契约操作抛出 unsupported | 修正抽象层级或拆分契约 |
+| ISP | 宽接口迫使实现提供空方法/异常 | 拆分客户端特定接口 |
+| DIP | 业务服务直接构造外部 SDK 或仓储实现 | 引入端口并通过依赖注入装配 |
+
+OCP 的多分支扩展风险可先作为 warning，但必须记录变化维度和后续扩展方案。

package/templates/knowledge/review_rules//345/220/216/347/253/257/345/256/236/347/216/260/345/267/245/347/250/213/345/256/241/346/237/245/350/247/204/345/210/231.md

@@ -0,0 +1,38 @@
+---
+name: 后端实现工程审查规则
+type: review_rule
+when: '后端审查, Controller, DTO, 事务, 幂等, 权限'
+scope:
+  - backend
+products:
+  - '*'
+id: ka-review-rule-后端实现工程审查规则
+asset_kind: review_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-backend-implementation-contract
+routes:
+  - code_change
+primary_triggers:
+  - 后端实现工程审查规则
+secondary_triggers:
+  - 接口审查
+negative_triggers: []
+priority: P1
+specificity: 5
+required_evidence:
+  - code_review_findings
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+## 硬失败检查
+
+| 分类 | 失败表现 | 修复要求 |
+|---|---|---|
+| Controller 边界 | 入参/出参使用数据库实体 | 改为 DTO/VO 并显式映射 |
+| 参数校验 | POST/PUT/PATCH 未校验 | 补校验注解或验证器与失败测试 |
+| 事务 | 事务中调用 HTTP/MQ/外部 SDK | 拆分边界或采用 outbox/补偿 |
+| 幂等 | 支付、回调或写入无幂等证据 | 补请求键/唯一约束/重复提交测试 |
+| 安全审计 | 敏感接口无权限、租户或审计 | 补安全校验和审计证据 |

package/templates/knowledge/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/knowledge/rules//345/220/216/347/253/257/345/256/236/347/216/260/345/267/245/347/250/213/345/245/221/347/272/246/350/247/204/345/210/231.md

@@ -0,0 +1,55 @@
+---
+name: 后端实现工程契约规则
+scope:
+  - backend
+products:
+  - '*'
+id: ka-hard-rule-后端实现工程契约规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-backend-implementation-contract
+asset_role: required
+consumed_by:
+  - mc-backend-implementation-contract
+routes:
+  - code_change
+  - artifact_generation
+  - multi_stage_plan
+primary_triggers:
+  - 后端实现
+  - 接口实现
+secondary_triggers:
+  - Controller
+  - DTO
+  - 事务
+  - 幂等
+negative_triggers:
+  - 文案
+priority: P1
+specificity: 5
+consumes:
+  - mc-coding-readiness
+hard_blocks:
+  - backend_work_package_missing
+  - backend_hard_fail_unresolved
+fallback: manual_required
+required_evidence:
+  - backend_work_package
+  - verification_result
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+## 编码前必须确认
+
+- Controller 只接收 DTO、执行校验、调用应用服务并返回统一响应对象。
+- 写操作的事务、一致性、幂等键、并发冲突处理已定义。
+- 权限、租户隔离、敏感字段与审计日志已定义。
+- OpenAPI、请求/响应字段表、数据库 migration 和错误码有权威对齐依据。
+- 验证计划包含成功、失败、重试、越权、重复提交和边界数据。
+
+## 阻断规则
+
+直接暴露实体、写接口无校验、事务内外部调用、高风险写入无幂等或敏感接口无安全审计证据，均不得交付。

package/templates/knowledge/rules//345/267/245/344/275/234/346/265/201/345/257/274/350/210/252/345/245/221/347/272/246/350/247/204/345/210/231.md

@@ -0,0 +1,113 @@
+---
+name: 工作流导航契约规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-工作流导航契约规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-workflow-navigation-contract
+asset_role: required
+consumed_by:
+  - mc-workflow-navigation-contract
+  - consumable_asset_registry
+  - knowledge_injection
+routes:
+  - operation
+  - multi_stage_plan
+  - artifact_generation
+primary_triggers:
+  - 工作流导航契约规则
+secondary_triggers:
+  - 下一步
+  - 继续
+  - 现在能写代码吗
+  - 导航
+  - navigation
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - mc-workflow-navigation-contract
+hard_blocks:
+  - stale_task_bypass
+  - disallowed_action_execution
+fallback: manual_required
+required_evidence:
+  - project_stage
+  - task_stage
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+## 核心原则
+
+执行任何开发动作前，必须先查询工作流导航状态。不得绕过导航机制凭经验操作。
+
+查询方式：`soloforge next`（CLI）或 `sf_navigation`（MCP 工具）。
+
+## 禁止动作规则
+
+以下 7 条规则在工作流导航中强制执行：
+
+1. **设计审计失败 → 禁止写业务代码**
+   - 条件：design_artifact_pack.status 不是 implementation_ready
+   - 阻断：sf_execute
+   - 必须先通过设计审计复验
+
+2. **配置未确认 → 优先建议确认配置**
+   - 条件：项目阶段为 configuration_pending
+   - 阻断：除 sf_init、config_confirm 外的所有动作
+   - 必须先运行 soloforge config confirm
+
+3. **决策未确认 → 禁止定稿架构/详细设计/代码**
+   - 条件：架构决策研讨中存在未确认域
+   - 阻断：sf_execute、sf_expand
+   - 必须先完成决策研讨并获取用户确认
+
+4. **无开发切片计划 → 禁止大范围编码**
+   - 条件：expansion 存在但 planning 不存在
+   - 阻断：sf_execute（大范围）
+   - 必须先生成切片规划工作包
+
+5. **修复重验指令未清零 → 禁止交付**
+   - 条件：repair_reverify_directive.blocked = true
+   - 阻断：sf_deliver
+   - 必须先完成修复和复验
+
+6. **测试失败 → 禁止交付**
+   - 条件：verification_result.status = failed
+   - 阻断：sf_deliver
+   - 必须先修复测试
+
+7. **本地验收缺失 → 禁止交付结论**
+   - 条件：delivery_ready 但无 local_acceptance_evidence
+   - 阻断：sf_deliver
+   - 必须先完成本地验收
+
+## 陈旧任务处理协议
+
+当检测到陈旧任务时（如 current-task.json 指向旧任务）：
+
+- **不得绕过 SoloForge 状态直接操作**
+- **不得说"无需 SoloForge 状态"然后自由发挥**
+- 必须从三个选项中选择：恢复旧任务 / 归档旧任务 / 开始新任务
+- 旧任务文件不得静默删除，只处理 current-task 指针
+- 选择必须留有审计痕迹
+
+## Override 协议
+
+用户可以显式 override 导航建议，但必须包含：
+- override_reason：覆盖原因
+- user_confirmation_ref：用户确认引用
+- risk_acknowledged：已确认风险
+
+无痕 override 不允许。
+
+## JSON 输出契约
+
+`soloforge next --json` 输出纯 JSON 到 stdout，无日志污染。
+字段包含：project_stage、task_stage、confidence、stage_evidence、blocking_reasons、recommended_commands、recommended_prompt、disallowed_next_actions、work_package。

package/templates/knowledge/rules//346/240/207/345/207/206/350/265/204/344/272/247/350/246/206/347/233/226/350/247/204/345/210/231.md

@@ -0,0 +1,72 @@
+---
+name: 标准资产覆盖规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-标准资产覆盖规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-standard-asset-coverage
+routes:
+  - artifact_generation
+  - code_change
+  - operation
+primary_triggers:
+  - 标准资产覆盖
+  - 模板覆盖
+  - 资产契约
+secondary_triggers:
+  - templates
+  - asset coverage
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - template_asset_contract_registry
+  - explicit_asset_registry
+  - observed_consumption
+hard_blocks:
+  - unregistered_template_asset
+  - missing_runtime_consumer
+  - missing_revalidation_entrypoint
+fallback: manual_required
+required_evidence:
+  - asset_contract
+  - consumption_evidence
+  - validation_entrypoint
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+# 标准资产覆盖规则
+
+## 覆盖范围
+
+所有 `templates/**` 下的资产类型必须被审计覆盖：
+
+- 验收模板 (acceptance_templates)
+- 规则 (rules)
+- 流程 (procedures)
+- 检查清单 (checklists)
+- 审查规则 (review_rules)
+- 模式 (patterns)
+- 脚手架 (scaffolds)
+- Adapter 工作流 (adapter_workflow)
+
+## 覆盖检查要求
+
+每个资产必须具备：
+
+1. **标准承载路径** — 资产存放在正确的类型目录中
+2. **复验路径** — 可通过 sf_verify、template_mechanism_auditor 或 validate-release 复验
+3. **主链路消费者** — 被实际工具（sf_expand、sf_verify、sf_deliver 等）消费
+
+## 门禁规则
+
+- P0 资产缺少标准承载路径时 hard_fail
+- P0 资产未在 Consumable Asset Registry 注册时 hard_fail
+- P0 资产缺少 owner_mechanism_id 时 hard_fail
+- `mc-design-artifact-pack` 仅作为首批 P0 子机制保留