soloforge 1.3.2 → 1.3.3

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

@@ -1,3 +1,46 @@
+---
+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
+---
+
 # 标准资产覆盖规则
 
 ## 覆盖范围

package/templates/knowledge/rules//346/250/241/346/235/277/350/265/204/344/272/247/345/217/257/350/247/201/346/200/247/350/247/204/345/210/231.md

@@ -1,3 +1,47 @@
+---
+name: 模板资产可见性规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-模板资产可见性规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-template-asset-visibility
+routes:
+  - operation
+  - code_change
+  - artifact_generation
+primary_triggers:
+  - 模板资产可见性
+  - 内部资产
+  - 知识同步
+secondary_triggers:
+  - sync-templates
+  - init
+  - visibility
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - template_asset_contract_registry
+  - template_init_sync
+  - knowledge_index_manager
+hard_blocks:
+  - internal_asset_leak
+  - cross_stack_injection
+  - unregistered_asset_sync
+fallback: manual_required
+required_evidence:
+  - visibility_contract
+  - sync_manifest
+  - runtime_consumption_trace
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
 # 模板资产可见性规则
 
 ## 适用范围

package/templates/knowledge/rules//351/200/232/347/224/250/345/206/263/347/255/226/347/240/224/350/256/250/350/247/204/345/210/231.md

@@ -1,3 +1,50 @@
+---
+name: 通用决策研讨规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-通用决策研讨规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-decision-workshop
+routes:
+  - analysis
+  - artifact_generation
+  - code_change
+primary_triggers:
+  - 决策研讨
+  - 技术选型
+  - 数据迁移
+  - 安全策略
+secondary_triggers:
+  - 架构设计
+  - 部署
+  - 重构
+  - 第三方集成
+negative_triggers:
+  - 简单说明
+  - 低风险改字
+priority: P0
+specificity: 5
+consumes:
+  - decision_workshop
+  - architecture_decision_workshop
+hard_blocks:
+  - unconfirmed_decision_domain
+  - missing_candidate_options
+  - missing_user_confirmation
+fallback: manual_required
+required_evidence:
+  - decision_workshop
+  - user_confirmation_ref
+  - decision_domain_status
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
 # 通用决策研讨规则
 
 ## 触发条件

package/templates/knowledge/rules//351/252/214/346/224/266/346/250/241/346/235/277/350/276/223/345/207/272/345/245/221/347/272/246/350/247/204/345/210/231.md

@@ -1,3 +1,49 @@
+---
+name: 验收模板输出契约规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-验收模板输出契约规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-standard-asset-contract
+routes:
+  - artifact_generation
+  - code_change
+  - verification
+primary_triggers:
+  - 验收模板
+  - 标准输出
+  - 设计产物
+secondary_triggers:
+  - API接口规格
+  - 数据库设计
+  - 架构设计
+negative_triggers:
+  - 普通解释
+  - 简单 bugfix
+priority: P0
+specificity: 5
+consumes:
+  - standard_asset_contract
+  - design_artifact_pack
+  - repair_reverify_directive
+hard_blocks:
+  - template_contract_violation
+  - draft_artifact_consumed
+  - missing_authoritative_asset
+fallback: manual_required
+required_evidence:
+  - template_contract_result
+  - authoritative_asset
+  - repair_reverify_result
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
 # 验收模板输出契约规则
 
 ## 触发条件

package/templates/patterns/SOLID/350/256/276/350/256/241/350/247/204/350/214/203.md

@@ -0,0 +1,39 @@
+---
+name: solid-design-pattern
+when: 'SOLID, 面向对象设计, 职责划分, 依赖倒置, 接口隔离'
+scope:
+  - backend
+  - frontend
+products:
+  - '*'
+id: ka-pattern-solid-design
+asset_kind: pattern
+lifecycle_status: active
+authority: supporting
+owner_mechanism_id: mc-ood-solid-contract
+routes:
+  - code_change
+primary_triggers:
+  - SOLID
+  - 面向对象设计
+priority: P1
+specificity: 5
+version: 1.0.0
+last_reviewed: '2026-05-26'
+consumes:
+  - mc-ood-solid-contract
+emits: []
+secondary_triggers: []
+negative_triggers: []
+type: pattern
+status: active
+---
+
+## 规则
+
+- 一个类只承担一个清晰可验证的业务原因。
+- 新增行为优先扩展端口或策略，避免修改大量既有条件分支。
+- 子类型必须保持父契约的有效输入、输出和错误语义。
+- 接口按消费者需要拆分，禁止空实现和不支持异常。
+- 业务核心依赖抽象，基础设施实现由装配层注入。
+- 简单修改不建立无用抽象层，避免为原则之名过度设计。

package/templates/patterns//345/220/216/347/253/257/345/256/236/347/216/260/345/267/245/347/250/213/350/247/204/350/214/203.md

@@ -0,0 +1,39 @@
+---
+name: backend-implementation-engineering
+when: 'Controller, DTO, API实现, 事务, 幂等, 权限, 后端编码'
+scope:
+  - backend
+products:
+  - '*'
+id: ka-pattern-backend-implementation-engineering
+asset_kind: pattern
+lifecycle_status: active
+authority: supporting
+owner_mechanism_id: mc-backend-implementation-contract
+routes:
+  - code_change
+primary_triggers:
+  - 后端实现
+  - API实现
+priority: P1
+specificity: 5
+version: 1.0.0
+last_reviewed: '2026-05-26'
+consumes:
+  - mc-backend-implementation-contract
+emits: []
+secondary_triggers: []
+negative_triggers: []
+type: pattern
+status: active
+---
+
+## 工程规则
+
+- Controller 入参与出参按接口语义使用 DTO/VO，不暴露数据库实体。
+- 参数必须验证必填、长度、枚举、金额、日期区间和关联对象存在性。
+- 列表接口限制 page size 并对白名单排序；响应使用统一分页对象。
+- 写操作在 Service 定义清晰事务边界；外部调用不放在长事务内。
+- 支付、回调、创建与状态流转具备幂等键、并发控制和重复提交测试。
+- 敏感操作必须校验权限和租户，并产出可追踪审计记录。
+- OpenAPI、字段表、错误码和 migration 必须与实现同步复验。