soloforge 1.3.1 → 1.3.3

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

@@ -0,0 +1,71 @@
+---
+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
+---
+
+# 模板资产可见性规则
+
+## 适用范围
+
+所有 `templates/**` 资产的同步、索引、注入和消费入口。
+
+## 可见性分类
+
+| 可见性 | 说明 |
+|--------|------|
+| user_project | 用户项目知识，可同步到 `.soloforge/knowledge` |
+| soloforge_internal | SoloForge 内部治理，不进入用户项目 |
+| adapter_runtime_only | 仅 adapter 运行时消费，不进入用户知识库 |
+| scaffold_only | 仅脚手架机制消费，不进入知识索引 |
+| global_pattern | 全局工程模式，进入 `~/.soloforge/patterns` |
+
+## 硬规则
+
+- 内部资产不得同步到用户项目。
+- 不同技术栈的审查规则不得互相注入。
+- 脚手架模板只由脚手架机制消费。
+- 全局 patterns 只能作为 `template_guidance`，不得支撑项目事实。
+- 用户可见资产不得包含内部施工术语。
+
+## 术语污染扫描
+
+用户可见资产禁止出现: Batch、validate-release、SoloForge Audit: PASS、Mechanism Contract Registry 等内部术语。

package/templates/knowledge/rules//347/224/250/346/210/267/345/217/215/351/246/210/345/245/221/347/272/246/350/247/204/345/210/231.md

@@ -13,18 +13,38 @@ routes:
   - 用户反馈契约规则
 primary_triggers:
   - 用户反馈契约规则
-secondary_triggers: []
+  - 用户反馈
+  - 实际使用反馈
+  - 问题反馈
+  - 机制缺口
+  - 设计缺陷
+secondary_triggers:
+  - 全局抽象
+  - 系统性问题
+  - 机制族归因
+  - 用户项目路径
+  - 防回归
 negative_triggers: []
 priority: P0
 specificity: 5
 consumes:
   - mc-task-context-lifecycle
+  - mc-first-principles
+  - mc-detail-discipline
+  - mc-evolution-regression
 hard_blocks:
   - 反馈未响应
   - 阻塞性信息未展示
+  - 仅按表面文件或单个场景收窄处理
+  - 未做机制族归因
+  - 未分析 SoloForge 自身与用户项目双路径影响
+  - 未分析模板层、知识层、机制层、adapter、CLI、MCP、发布门禁、迁移和防回归影响
 fallback: manual_required
 required_evidence:
   - user_feedback_message
+  - global_abstraction_review
+  - mechanism_family_mapping
+  - cross_layer_impact_matrix
 version: 1.0.0
 last_reviewed: '2026-05-22'
 migration_note: 知识资产标准化迁移
@@ -42,6 +62,15 @@ status: active
 3. 技术内容（路径、命令、错误码）禁止翻译，必须保留原文。
 4. `blocked` 类型反馈必须包含阻塞原因和建议下一步。
 5. `failure` 类型反馈必须包含失败证据和 retry_hint。
+6. 任何用户反馈、缺陷、设计疑问或实际使用偏差，不得只按表面文件、单个目录或单个场景收窄处理。
+7. 进入修复讨论前，必须先完成全局抽象审查：
+   - 该问题属于哪个机制族？
+   - 是否只是某个现象暴露出来的系统性问题？
+   - 是否同时影响 SoloForge 自身与用户项目使用路径？
+   - 是否涉及模板层、知识层、机制层、adapter、CLI、MCP、发布门禁、迁移和防回归？
+   - 是否需要抽象成通用能力，而不是只修当前案例？
+8. 如果全局抽象审查未完成，只能输出待分析项、影响矩阵和建议讨论顺序，不得直接给单点修复结论。
+9. 如果当前案例只是系统性问题的一个样本，修复方案必须覆盖同类入口、同类资产、同类任务和新增资产防回归。
 
 ## 适用场景
 
@@ -49,9 +78,41 @@ status: active
 - sf_verify 结果反馈
 - sf_learn 学习反馈
 - sf_expand 降级/澄清反馈
+- 用户反馈实际使用问题
+- 讨论新增机制、模板、规则、流程、验收或发布风险
+- 将问题落入 Batch、备忘录、发布门槛或施工合同前
 
 ## 违规处理
 
 - 禁止的反馈类型 → hard_fail，阻断输出
 - 空洞反馈 → advisory，标记质量降级
 - 翻译技术内容 → advisory，标记违规
+- 未做全局抽象审查就收窄为单点修复 → hard_fail，退回机制族归因
+- 只修当前文件/目录/样例但未覆盖同类路径和防回归 → hard_fail，要求补齐通用能力
+- 未分析 SoloForge 自身与用户项目双路径影响 → hard_fail，要求补齐影响矩阵
+- 未说明模板层、知识层、机制层、adapter、CLI、MCP、发布门禁、迁移和防回归影响 → hard_fail，要求补齐跨层影响
+
+## 全局抽象审查输出
+
+每次用户反馈进入讨论或施工合同前，必须形成以下结构化结论：
+
+```text
+1. 表面现象:
+2. 机制族归因:
+3. 是否系统性问题:
+4. SoloForge 自身影响:
+5. 用户项目影响:
+6. 涉及层级:
+   - 模板层:
+   - 知识层:
+   - 机制层:
+   - adapter:
+   - CLI:
+   - MCP:
+   - 发布门禁:
+   - 迁移:
+   - 防回归:
+7. 是否应抽象成通用能力:
+8. 不应只修的局部案例:
+9. 施工和验收必须覆盖的同类路径:
+```

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

@@ -0,0 +1,77 @@
+---
+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
+---
+
+# 通用决策研讨规则
+
+## 触发条件
+
+以下任务类型必须在执行前完成决策研讨与用户确认：
+
+- 架构设计（六域决策子包）
+- 技术选型
+- 数据迁移
+- 安全策略变更
+- 部署基础设施变更
+- 产品范围变更
+- 重构/迁移方案
+- 第三方集成
+
+## 决策域记录要求
+
+每个决策域必须包含：
+
+1. **事实与约束** — 客观现状、技术限制、业务约束
+2. **候选方案** — 至少两个可行方案，含收益与风险
+3. **推荐方案** — 附推荐理由
+4. **用户确认引用** — 必须有明确的用户确认记录
+
+## 门禁规则
+
+- 所有必须域未确认时，阻断正式生成/执行
+- 现有系统变更必须提供现状分析和差距分析证据
+- 标记 `not_applicable` 的域必须提供不适用理由
+- 标记 `deferred` 的域必须列出延期影响

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

@@ -0,0 +1,96 @@
+---
+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
+---
+
+# 验收模板输出契约规则
+
+## 触发条件
+
+当任务产出正式设计文档、架构设计、数据库设计、API 接口规格、原型说明或验收报告时，必须按标准资产契约验收。
+
+## 适用范围
+
+- 架构设计文档（01-架构设计文档.md）
+- 数据库设计文档（02-数据库设计文档.md）
+- API 接口规格（03-API接口规格文档.md）
+- 设计一致性验收报告（99-设计一致性验收报告.md）
+- 原型说明文档
+
+## 契约要求
+
+每个 P0 模板输出必须满足:
+
+1. **章节检查**: 必填章节存在、顺序合理、不得只有空标题。
+2. **表格检查**: 必填表格存在、表头正确、行内容覆盖必要对象。
+3. **字段检查**: API/数据/追踪字段具备类型、必填、来源、说明、示例、校验规则、错误语义。
+4. **权威资产检查**: 必须引用并对齐 OpenAPI、SQL/migration 等机器权威资产。
+5. **语义检查**: Mermaid 图、字段、实体与当前业务相关，不得用无关内容凑数。
+
+## API 字段表最小列
+
+字段名 / 类型 / 必填 / 来源 / 说明 / 示例 / 校验规则 / 错误语义
+
+## Mermaid 检查规则
+
+- fence 语法合法。
+- 图类型符合模板要求（sequenceDiagram、flowchart 等）。
+- 图内容与当前业务相关。
+
+## 修复闭环
+
+模板契约验收失败必须进入修复重验:
+
+1. sf_verify 报告缺口和诊断码。
+2. 修复后重新 sf_verify。
+3. 仍然失败则继续循环或请求用户确认。
+4. 修复期间交付被阻断。
+
+## 草稿状态
+
+草稿必须显式标记 `draft`、`not_for_implementation` 或 `needs_template_verification`。草稿不进入编码消费。
+
+## 低风险跳过
+
+普通 bugfix、样式修复、只读解释和小范围改动不触发模板契约验收。

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 必须与实现同步复验。