soloforge 1.1.46 → 1.1.47

package/templates/build//347/206/224/346/226/255/351/231/215/347/272/247.md

@@ -1,49 +0,0 @@
----
-id: ka-pattern-circuit-breaker
-kind: knowledge
-title: 熔断降级
-sync_policy: copy_to_project
-status: active
-extra:
-  name: circuit-breaker
-  scope:
-    - backend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  domain:
-    - build
-    - verify
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-backend-pattern
----
-
-## 决策规则
-- 外部依赖（第三方 API、中间件、其他微服务）必须配置超时时间，禁止无限等待
-- 核心链路的外部调用必须配置熔断器：失败率阈值（建议 50%）、熔断时长（建议 30s）、半开探测数（建议 5）
-- 熔断触发后必须有降级策略：返回缓存数据/默认值/友好提示，禁止直接抛异常给用户
-- 接口必须有限流保护（令牌桶/漏桶），防止突发流量击穿服务
-- 降级方案必须提前定义：降级行为、用户提示文案、数据一致性保障、恢复条件
-- 重试必须满足幂等性，重试间隔必须使用指数退避（initial 100ms, multiplier 2, max 3 次）
-- 线程池隔离：不同外部依赖使用独立线程池，防止一个慢服务拖垮所有请求
-- 必须有服务健康检查端点（/actuator/health），包含依赖组件状态（DB/Redis/MQ）
-- 熔断器必须配置 half-open 状态的探测请求量（如允许 5 个请求通过测试），成功后才恢复
-- 降级 fallback 必须返回有意义的默认值或缓存数据，禁止返回 null 或空对象
-- 熔断/降级事件必须触发监控告警，不能静默降级
-- 外部调用必须设置独立的超时时间（不依赖全局超时），与熔断器配合使用
-- 熔断器状态变化必须有日志记录（closed → open → half-open → closed）
-
-## 验收项
-- [AC-01] 外部调用有超时和熔断配置
-- [AC-02] 熔断后有降级策略和用户提示
-- [AC-03] 重试有指数退避和幂等保障
-- [AC-04] 有限流保护
-- [AC-05] 健康检查端点包含依赖状态
-- [AC-06] half-open 探测机制配置
-- [AC-07] fallback 返回有意义的值
-- [AC-08] 熔断事件有监控告警
-- [AC-09] 外部调用有独立超时

package/templates/build//347/212/266/346/200/201/346/265/201/350/275/254.md

@@ -1,43 +0,0 @@
----
-id: ka-pattern-state-transition
-kind: knowledge
-title: 状态流转
-sync_policy: copy_to_project
-status: active
-extra:
-  name: state-transition
-  scope:
-    - backend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  domain: build
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-backend-pattern
----
-
-## 决策规则
-- 仅列出状态列表不够，每个状态转换必须定义：触发条件、守卫条件、失败/回滚动作
-- 金额、库存、配额、计数器等并发敏感节点默认需要并发控制
-- 并发敏感操作必须显式声明：并发控制方式（乐观锁/悲观锁/幂等键/去重表）、重试策略、重复提交处理、用户可见失败反馈
-- 跨模块或跨服务状态变更必须显式声明最终一致性和补偿策略
-- 集成测试必须覆盖：至少一次成功转换、一次守卫失败、一次失败恢复或升级路径
-- 状态流转必须通过状态机框架（如 Spring Statemachine）或显式流转表校验，禁止硬编码 if-else
-- 每次状态变更必须记录流转日志（原状态→新状态、操作人、时间、原因）
-- 并发状态变更必须使用乐观锁或分布式锁，防止状态覆盖
-- 状态流转失败必须返回明确的错误原因，告知用户当前状态和允许的下一步操作
-- 状态定义必须包含初始状态和终态，禁止出现无法流转的"悬挂状态"
-
-## 验收项
-- [AC-01] 状态转换有触发条件、守卫条件、回滚动作
-- [AC-02] 并发敏感操作有显式并发控制声明
-- [AC-03] 跨服务状态变更有补偿策略
-- [AC-04] 集成测试覆盖成功和失败路径
-- [AC-05] 状态机校验（非硬编码）
-- [AC-06] 状态变更审计日志
-- [AC-07] 并发状态变更防护
-- [AC-08] 无悬挂状态

package/templates/build//347/213/254/347/253/213/345/256/241/346/237/245.md

@@ -1,45 +0,0 @@
----
-id: 独立审查
-kind: guidance
-title: 独立审查
-triggers:
-  - 代码审查
-  - review
-  - 独立检查
-sync_policy: copy_to_project
-status: active
-extra:
-  name: independent-review
-  type: constraint
-  scope:
-    - '*'
-  domain: build
-  lifecycle_status: active
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-command-router
----
-
-# 独立审查规则
-
-## 审查测试要求
-
-- 每个任务完成后，独立审查必须新增 ≥9 个测试场景
-- 测试描述和场景必须与编码阶段的实施测试不同（不同角度、不同数据）
-- 审查测试必须覆盖：
-  - 全部公开接口（每个接口至少 2 个场景）
-  - 全部核心逻辑路径（正向 + 反向）
-  - 全部错误处理分支
-
-## 审查覆盖范围
-
-- 接口覆盖：每个公开方法/函数必须有审查测试
-- 逻辑路径覆盖：每个 if/switch 分支必须有测试用例
-- 边界值覆盖：数值边界、空值、超长输入
-- 并发/竞态覆盖（如适用）：多线程/异步场景
-
-## 审查独立性
-
-- 审查测试不得复制实施测试的代码和断言
-- 审查测试必须独立设计测试数据和场景
-- 审查发现的问题必须记录，不得直接修改代码绕过

package/templates/build//347/272/246/346/235/237/345/256/236/347/216/260.md

@@ -1,47 +0,0 @@
----
-id: ka-pattern-constrained-implementation
-kind: knowledge
-title: 约束实现
-sync_policy: copy_to_project
-status: active
-extra:
-  name: constrained-implementation
-  scope:
-    - backend
-    - frontend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  domain: build
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-general-pattern
----
-
-## 决策规则
-- 必须在修改代码前定位根因，解释根因、修改边界和验证方式后再编码
-- 只修改任务卡/补丁计划/白名单明确范围内的文件
-- 禁止补丁叠补丁或试错式堆叠修复
-- 禁止删除断言、放宽测试、增加 sleep、让测试适应错误行为
-- 禁止顺手重构或范围外的"清理"
-- 每个代码变更必须追溯到任务卡、补丁计划或阻塞性缺陷
-- 范围超出白名单或需要变更接口/DDL/权限/菜单时，立即上报而非自行决定
-- 必须完成本地验证并产出结构化证据后再结束
-- 唯一约束必须同时在数据库和应用层校验，防止并发场景下的重复数据
-- 外键约束在微服务架构中不建议使用物理外键，应通过应用层保证数据一致性
-- 乐观锁必须使用 version 字段而非 update_time（后者可能因精度问题失效）
-- 软删除数据必须排除在唯一约束之外（如添加 is_deleted 条件索引）
-- 数据库约束的校验失败必须返回用户友好的错误消息，而非数据库原始报错
-
-## 验收项
-- [AC-01] 变更范围与白名单完全匹配
-- [AC-02] 根因已确认再编码（非先改再试）
-- [AC-03] 无顺手重构或范围外变更
-- [AC-04] 本地验证执行完毕有结果
-- [AC-05] 超范围变更已上报
-- [AC-06] 唯一约束双层校验
-- [AC-07] 乐观锁用 version 字段
-- [AC-08] 软删除与唯一约束兼容

package/templates/build//347/274/226/347/240/201/345/260/261/347/273/252/345/256/241/346/237/245.md

@@ -1,60 +0,0 @@
----
-id: ka-review-rule-编码就绪审查规则
-kind: guidance
-title: 编码就绪审查
-sync_policy: copy_to_project
-status: active
-triggers:
-  - build
-  - 编码就绪
-  - coding readiness
-extra:
-  name: coding-readiness-review
-  type: constraint
-  scope:
-    - backend
-    - frontend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.2.0
-  last_reviewed: '2026-06-04'
-  domain: build
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-coding-readiness
----
-
-# 编码就绪审查规则
-
-## READY-01: CodingReadiness 非空
-
-check_hint: 编码前必须确认 CodingReadiness 检查已通过
-severity: error
-check_type: deterministic
-scope: [backend, frontend]
-description: CodingReadiness 报告必须存在且 status 非 blocked；blocked 状态必须先解决前置问题
-
-## READY-02: OOD 摘要完整
-
-check_hint: OOD 设计摘要必须包含类定义、方法签名和协作关系
-severity: warning
-check_type: deterministic
-scope: [backend, frontend]
-description: OOD 摘要至少包含：核心类名、公开方法签名、类间协作关系图；缺少任一项必须补充后再编码
-
-## READY-03: 前置产物已确认
-
-check_hint: 编码依赖的设计产物必须全部就绪
-severity: error
-check_type: deterministic
-scope: [backend, frontend]
-description: API 接口规格、数据库设计文档、切片计划等编码依赖产物必须已生成且无 hard_fail
-
-## READY-04: 技术栈明确
-
-check_hint: 编码前必须确认使用的技术栈和框架版本
-severity: warning
-check_type: deterministic
-scope: [backend, frontend]
-description: 语言版本、框架版本、关键依赖版本必须在编码前明确，避免编码过程中变更技术栈

package/templates/build//347/274/226/347/240/201/350/201/232/345/220/210/346/243/200/346/237/245.md

@@ -1,22 +0,0 @@
----
-id: build-aggregate-checks
-kind: guidance
-title: 编码聚合检查
-triggers:
-  - 编码
-  - 规范
-  - 命名
-  - 注释
-sync_policy: engine_only
-status: active
-extra:
-  type: constraint
-  scope:
-    - '*'
-  stage: build
-  owner_mechanism: mc-stage-gate-engine
----
-
-# build 阶段聚合检查
-
-收容无单一资产归属的 stage 级 check（如编译/测试/部署证据等）。

package/templates/build//347/274/226/347/240/201/350/264/250/351/207/217.md

@@ -1,46 +0,0 @@
----
-id: ka-pattern-coding-quality
-kind: knowledge
-title: 编码质量
-sync_policy: copy_to_project
-status: active
-extra:
-  name: coding-quality
-  scope:
-    - backend
-    - frontend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  domain: build
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-general-pattern
----
-
-## 决策规则
-- 50 行能解决的问题禁止写 200 行；禁止为单次使用场景过度设计
-- 每行代码变更必须可追溯到任务卡片中的显式需求，禁止"顺手"重构相邻代码
-- 实现记录必须显式声明业务入口集成状态（菜单/路由/权限）
-- Bug 修复必须针对根因，禁止在破损代码上叠加 workaround
-- 方法必须按业务步骤拆分为单一职责的私有方法
-- 新增/修改类必须文档化业务职责、边界和关键协作者
-- 仅在"非显而易见"的关键行添加注释说明 why，禁止对简单赋值加噪声注释
-- 方法长度不超过 80 行，超过时拆分为子方法
-- 方法参数不超过 5 个，超过时封装为请求对象
-- 单个类职责单一（SRP），超过 500 行的类应考虑拆分
-- 条件嵌套不超过 3 层，超过时使用卫语句、策略模式或 Optional 链重构
-- 禁止使用魔法数字，必须提取为命名常量或枚举
-
-## 验收项
-- [AC-01] 代码变更可追溯到任务需求
-- [AC-02] 业务入口集成状态已声明
-- [AC-03] Bug 修复针对根因而非 workaround
-- [AC-04] 无过度设计（50行能解决的不写200行）
-- [AC-05] 方法不超过 80 行
-- [AC-06] 参数不超过 5 个
-- [AC-07] 嵌套不超过 3 层
-- [AC-08] 无魔法数字

package/templates/build//347/274/226/347/240/201/351/230/266/346/256/265/346/211/247/350/241/214.md

@@ -1,105 +0,0 @@
----
-id: 编码阶段执行
-kind: guidance
-title: 编码阶段执行
-sync_policy: copy_to_project
-status: active
-triggers:
-  - 编码执行
-  - 编码阶段
-  - coding stage
-  - 开始编码
-extra:
-  name: coding-stage-execution-workflow
-  type: procedure
-  scope:
-    - backend
-    - frontend
-  products:
-    - '*'
-  domain: build
-  version: 1.0.0
-  last_reviewed: '2026-06-04'
-  lifecycle_status: active
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-core-engineering-principles
----
-
-# 编码阶段执行工作流
-
-## 适用场景
-编码与单元测试阶段的完整 Agent 执行工作流。从读取上游产物到推进至下一阶段的全流程编排。
-
-## 步骤
-
-### 1. [读取] 加载上游产物
-- 加载数据库设计文档（docs/design/01-数据库设计文档.md）
-- 加载 API 接口规格文档（docs/design/02-API接口规格文档.md）
-- 加载 openapi.yaml（若存在）
-- 确认所有设计产物无 hard_fail 状态
-
-### 2. [触发] 调用 sf_work action=act
-- 获取当前 scope 和 forbidden_tools
-- 确认 stage 为"build"
-- 确认 forbidden_tools 不影响编码核心流程
-
-### 3. [任务规划] 执行任务拆解流程（E-01）
-- 执行任务拆解流程 → 选择分解策略 → 生成切片计划 → 生成依赖图
-- 运行 G-01 build-gate（8 项检查）
-- gate 未通过 → 修复后重新执行步骤 3
-
-### 4. [编码准备] 执行编码前澄清流程（E-02）
-- 不确定性分级 → 澄清问题 → 输入完备报告
-- 运行 G-02 build-gate（3 项检查）
-- status=blocked → 阻断，等待用户解决
-- status=allowed → 进入步骤 5
-
-4a. **头脑风暴触发**：若实现方案存在多种选择且无明确最优，或反复修复同一模块 ≥ 3 次：
-   → 进入「不确定时头脑风暴流程」（templates/procedures/不确定时头脑风暴.md）
-   → 若 fundamental_need 为空 → 先触发 FP-01
-
-### 5. [切片循环] 对每个切片执行
-- **5a.** 执行 E-03 测试优先编码工作流
-  - 模式 A（核心逻辑）：red→green→refactor
-  - 模式 B（简单 CRUD）：红绿合并
-- **5b.** 运行 G-03 build-gate（3 项检查）
-- **5c.** 运行 G-06 slice-gate（3 项检查）
-- **5d.** 老系统切片：执行新老逻辑比对（100% 一致率）
-- **5e.** 切片验证点（E-04 步骤 7）：运行测试 → 检查覆盖率 → 确认涉及文件 → 更新测试状态
-- **5f.** 运行 G-05 build-gate（2 项检查）
-- **5g.** 若触发重规划（E-06 动态重规划）：
-  - 局部重规划 → 回到 5a
-  - 结构重规划 → 回到步骤 3
-  - 回退 → 阻断并通知用户
-
-### 6. [编码验证] 运行 G-04 build-gate
-- 构建通过（0 error）
-- 测试通过（passed/failed/total）
-- 覆盖率达标（增量行覆盖率≥阈值）
-- gate 未通过 → 修复后重新运行
-
-### 7. [切片审查] 运行 G-07 slice-gate
-- 独立审查测试充分性
-- 无 hard_fail（代码质量检查）
-- 无遗留问题
-- gate 未通过 → 修复后重新审查
-
-### 8. [推进] 调用 sf_work action=verify
-- 所有 gate 通过后推进至下一阶段
-- 生成编码阶段完成报告
-
-## 检查点
-- [ ] 上游产物已全部加载且无 hard_fail
-- [ ] 任务规划 gate 通过（G-01）
-- [ ] 编码准备 gate 通过（G-02）
-- [ ] 每个切片：编码实现→切片执行→编码与单元测试 gate 全部通过
-- [ ] 编码验证 gate 通过（G-04）
-- [ ] 切片审查 gate 通过（G-07）
-- [ ] 编码阶段完成报告已生成
-
-## 禁止退化
-- 跳过任何 gate 直接推进
-- gate 失败后不修复直接重试
-- 切片循环中跳过老系统比对
-- 重规划时降低验收标准

package/templates/build//347/274/272/351/231/267/347/256/241/347/220/206.md

@@ -1,47 +0,0 @@
----
-id: ka-pattern-defect-management
-kind: knowledge
-title: 缺陷管理
-sync_policy: copy_to_project
-status: active
-extra:
-  name: defect-management
-  scope:
-    - backend
-    - frontend
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  domain:
-    - build
-    - verify
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-general-pattern
----
-
-## 决策规则
-- 每个缺陷必须归因到最小责任阶段（需求/设计/任务拆解/实现/测试/门禁）
-- 修复必须附带证据，"理论上修好了"不可接受
-- 有复现价值的缺陷必须产出至少一项回填动作：规则、模版、检查项或知识条目
-- 同一缺陷若在案例库中已出现过，自动升级为深层缺陷（方法论级别）
-- 报告必须在修复之前编写，禁止先改规则后写报告
-- 缺陷结论必须区分：已完成 / 未完成 / 未验证 / 未知，无真实证据不得标记为已完成
-- 缺陷必须包含完整的复现步骤、预期结果、实际结果和环境信息
-- 每个缺陷必须有优先级（P0-P4）和严重程度（S1-S4）分类
-- 修复缺陷必须包含根因分析，禁止只修表面症状
-- P0/P1 缺陷修复后必须经过回归测试，不能直接上线
-- 缺陷关闭必须由提单人确认，修复人不能自行关闭
-
-## 验收项
-- [AC-01] 缺陷有归因阶段
-- [AC-02] 修复附带执行证据
-- [AC-03] 有复现价值的缺陷有回填动作
-- [AC-04] 结论区分已完成/未完成/未验证/未知
-- [AC-05] 缺陷有完整复现信息
-- [AC-06] 有优先级和严重程度
-- [AC-07] 修复包含根因分析
-- [AC-08] 高优先级缺陷有回归测试

package/templates/build//350/200/246/345/220/210/346/243/200/346/265/213.md

@@ -1,86 +0,0 @@
----
-id: 耦合检测
-kind: guidance
-title: 耦合检测
-sync_policy: copy_to_project
-status: active
-triggers:
-  - 耦合检测
-  - mock失败
-  - 循环依赖
-  - 影响范围
-  - 回退判定
-  - coupling detection
-extra:
-  name: coupling-detection
-  type: constraint
-  scope:
-    - '*'
-  domain: build
-  lifecycle_status: active
-  version: 1.2.0
-  last_reviewed: '2026-06-04'
-  products:
-    - '*'
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-existing-system-review
----
-
-# 老代码耦合检测规则
-
-## COUP-TEST-01: 静态方法依赖
-  id: COUP-TEST-01
-  name: 静态方法依赖
-  severity: warning
-  check_type: deterministic
-  check_hint: 老代码使用静态方法/单例导致无法 mock
-  description: 老代码中使用静态方法或单例模式导致测试时无法 mock 隔离。发现此类耦合应评估是否需要引入适配器层。
-
-## COUP-TEST-02: 直接 new 对象
-  id: COUP-TEST-02
-  name: 直接 new 对象
-  severity: warning
-  check_type: deterministic
-  check_hint: 老代码直接 new 依赖对象，未使用依赖注入
-  description: 老代码在业务逻辑中直接 new 依赖对象而非通过依赖注入，导致无法替换为 mock 进行测试。
-
-## COUP-TEST-03: 框架绑定
-  id: COUP-TEST-03
-  name: 框架绑定
-  severity: warning
-  check_type: semantic
-  check_hint: 老代码与框架深度绑定（如直接依赖 Request/Response 对象）
-  description: 老代码直接依赖框架特定对象（HttpServletRequest、ResponseEntity 等），无法在单元测试中独立运行。
-
-## COUP-MOD-01: 影响范围>3×
-  id: COUP-MOD-01
-  name: 影响范围>3×
-  severity: error
-  check_type: deterministic
-  check_hint: 修改影响文件数超过涉及文件列表的 3 倍
-  description: 修改一个函数需要同步修改的关联文件数超过切片涉及文件列表的 3 倍，说明耦合度过高，应评估是否需要架构级重构。
-
-## COUP-MOD-02: 循环依赖
-  id: COUP-MOD-02
-  name: 循环依赖
-  severity: error
-  check_type: deterministic
-  check_hint: 老代码存在循环依赖无法单独抽取
-  description: 老代码中存在 A→B→A 的循环依赖，无法单独抽取和测试。发现循环依赖应评估是否需要引入接口层解耦。
-
-## COUP-ROLLBACK-01: 3 次 mock 失败触发回退
-  id: COUP-ROLLBACK-01
-  name: 3 次 mock 失败触发回退
-  severity: error
-  check_type: deterministic
-  check_hint: 尝试写单测 3 次仍无法 mock 隔离 → 触发回退到 design 域（架构设计）
-  description: 编码阶段尝试为老代码编写单元测试，连续 3 次无法完成 mock 隔离时，触发回退到 design 域（架构设计）重新评估改造方案。
-
-## COUP-ROLLBACK-02: 影响超 3 倍触发回退
-  id: COUP-ROLLBACK-02
-  name: 影响超 3 倍触发回退
-  severity: error
-  check_type: deterministic
-  check_hint: 修改影响范围超过预期的 3 倍 → 触发回退到 design 域（架构设计）
-  description: 编码阶段修改老代码时，实际影响范围超过切片涉及文件列表的 3 倍，触发回退到 design 域（架构设计）重新评估改造范围。

package/templates/build//350/246/206/347/233/226/347/216/207/346/240/207/345/207/206.md

@@ -1,40 +0,0 @@
----
-id: 覆盖率标准
-kind: guidance
-title: 覆盖率标准
-sync_policy: copy_to_project
-status: active
-triggers:
-  - 覆盖率
-  - 测试
-  - 覆盖
-extra:
-  name: coverage-standard
-  type: constraint
-  scope:
-    - '*'
-  products:
-    - '*'
-  lifecycle_status: active
-  domain: build
-  verification_layer: L2
-  stage: build
-  owner_mechanism: mc-generic-review
----
-
-# 覆盖率标准
-
-## 新系统
-- 行覆盖率最低要求：**70%**
-- 每个切片完成后即时校验
-- 不达标的切片必须当场修复后才能继续
-
-## 老系统
-- 增量行覆盖率最低要求：**80%**
-- 每个切片完成后即时校验
-- 额外要求：新老逻辑比对日志通过
-
-## 计算规则
-- 统计范围：新增和修改的代码行
-- 排除：纯配置文件、自动生成代码
-- 工具：项目配置的测试覆盖率工具（如 jest --coverage、pytest --cov）