soloforge 1.3.2 → 1.3.4

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//344/273/243/347/240/201/345/217/257/347/273/264/346/212/244/346/200/247/344/270/216/345/217/257/350/247/202/346/265/213/346/200/247/345/256/241/346/237/245.md

@@ -0,0 +1,81 @@
+---
+name: 代码可维护性与可观测性审查
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-review-rule-代码可维护性与可观测性审查
+asset_kind: review_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-code-maintainability-observability-contract
+routes:
+  - code_change
+  - review
+primary_triggers:
+  - 代码审查
+  - review
+  - 验证
+secondary_triggers:
+  - 业务代码
+  - 接口实现
+negative_triggers:
+  - 纯文档
+  - 纯样式
+priority: P1
+specificity: 4
+consumes:
+required_evidence:
+  - execution_evidence
+version: 1.0.0
+last_reviewed: '2026-05-26'
+---
+
+## 审查维度
+
+### 1. 日志完整性
+检查 changed files 中:
+- 支付/金额/退款操作是否有含对象 ID 和前后值的日志
+- 权限拒绝是否有含操作人和拒绝原因的日志
+- 外部调用是否有含目标、响应码和重试信息的失败日志
+- 状态变更是否有含前后状态和触发原因的流转日志
+- 数据修复/迁移是否有含修复前值和影响行数的审计日志
+
+### 2. 敏感信息泄漏
+检查所有日志输出是否:
+- 不包含 token、password、cookie 全量
+- 不包含身份证、手机号、银行卡全量
+- 不包含健康隐私信息
+
+### 3. 注释质量
+检查 changed files 中:
+- 复杂业务规则是否有说明"为什么"的注释
+- 金额计算是否有设计意图注释
+- 状态机是否有状态流转注释
+- 不检查纯复述代码的废话注释
+
+### 4. Logger 使用
+检查是否使用了项目已有 logger:
+- Java/Spring 项目是否使用 Slf4j
+- Node 项目是否使用 pino/winston
+- NestJS 项目是否使用 NestJS Logger
+- 前端项目是否避免裸 console
+
+### 5. 异常处理
+检查 catch 块是否:
+- 不吞异常（至少记录日志）
+- 不只输出 "error" / "failed" 这类不可定位信息
+
+## 审查输出格式
+每条 finding 包含:
+- 类别 (category)
+- 严重度 (P0/P1/P2/P3)
+- 文件路径
+- 证据位置
+- 中文修复建议
+
+## 低风险跳过规则
+- 纯样式、文案修改不触发审查
+- 简单 getter/setter 不触发审查
+- 测试 fixture 不触发审查
+- 低风险只读查询（且已有统一 access log）不触发审查

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//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,121 @@
+---
+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
+  - 异常处理
+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
+fallback: manual_required
+required_evidence:
+  - code_observability_work_package
+  - review_findings
+  - verification_result
+version: 1.0.0
+last_reviewed: '2026-05-26'
+---
+
+## 注释契约
+
+### 必须有注释
+- 业务规则不直观时
+- 领域不变量（如"一个长者同一时间只能有一个有效入住"）
+- 金额、账单、补贴、支付、退款、核销逻辑
+- 状态流转逻辑（如 pending → paid → refunded）
+- 幂等、分布式锁、事务、并发控制
+- 权限、安全、审计判断
+- 外部系统兼容、历史包袱、第三方接口限制
+- 复杂 SQL、复杂查询条件、非显而易见算法
+
+### 必须禁止
+- 每行废话注释
+- 复述代码字面含义的注释
+- 注释与代码行为不一致
+- 注释承诺了代码没有做到的安全性、幂等性或事务性
+
+## 日志契约
+
+### 必须有日志
+- 用户登录、登出、认证失败
+- 权限拒绝、越权访问
+- 创建、修改、删除关键业务对象
+- 状态变更、金额变更、支付、退款、补贴、核销
+- 合同、入住、账单、证照、人员角色变更
+- 外部 API 调用失败、超时、重试
+- 异步任务开始、成功、失败、重试、跳过
+- 数据修复、批处理、迁移脚本
+- 捕获异常后继续执行
+- 降级、兜底、补偿逻辑
+
+### 日志必须具备
+- 事件名或动作名
+- 业务对象 ID
+- 操作人或系统来源
+- traceId / correlationId（如果项目已有）
+- 失败原因
+- 关键状态变化前后值
+- 合理日志级别
+
+### 必须禁止
+- 裸 console.log（生产代码）
+- 生产代码遗留调试日志
+- catch 后无日志直接吞异常
+- 只打印 "error"、"failed" 这类不可定位日志
+- 打印 password、token、secret、cookie、身份证全量、手机号全量、银行卡全量、健康隐私
+- 高频循环里刷屏日志
+- 日志拼接大对象导致性能或隐私问题
+
+## 项目 logger 识别
+- Java/Spring: Slf4j + LoggerFactory
+- Node: pino, winston, 项目封装 logger
+- NestJS: Logger
+- 前端: 项目封装 logger，或生产环境禁止 console
+- 如果项目没有 logger，要求先建立项目 logger 包装
+
+## 严重度
+- P0 阻断: 敏感信息泄漏、catch 吞异常、支付/金额/权限变更无日志
+- P1 阻断: 状态流转无日志、复杂规则无注释、外部调用无日志、裸 console.log
+- P2 警告: 日志级别不合理、上下文字段不足
+- P3 建议: 普通可读性优化
+
+## 低风险跳过
+- 纯样式、文案、简单 getter/setter、简单类型定义、测试 fixture
+- 低风险只读查询且已有统一 access log
+- 简单配置修改、一次性本地实验代码

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。