soloforge 1.1.2 → 1.1.30

package/templates/internal/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/internal/rules//345/221/275/344/273/244/346/211/247/350/241/214/350/247/204/345/210/231.md

@@ -0,0 +1,61 @@
+---
+name: 命令执行规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-命令执行规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-command-execution
+routes:
+  - 命令执行规则
+primary_triggers:
+  - 命令执行规则
+secondary_triggers: []
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - mc-tool-invocation-contract
+hard_blocks:
+  - destructive命令无确认
+  - 命令越权
+fallback: manual_required
+required_evidence:
+  - command_classification
+  - execution_result
+version: 1.0.0
+last_reviewed: '2026-05-22'
+migration_note: 知识资产标准化迁移
+type: hard_rule
+when: 命令执行规则
+status: active
+---
+
+# 命令执行规则
+
+## 核心原则
+
+命令执行必须按副作用分级: destructive 命令需人工确认，read-only 命令可自动执行。
+
+## 命令分级
+
+1. **destructive**: 不可逆操作 (drop table, force push)，需人工确认
+2. **mutating**: 可逆修改 (build, test)，可自动执行但需记录
+3. **read_only**: 只读操作 (ls, cat)，可自由执行
+
+## 规则
+
+1. 每个命令必须通过 classifyCommand 分级
+2. destructive 命令不可自动执行
+3. 所有命令执行结果必须记录证据
+4. 命令执行链必须可追踪
+
+## 验收标准
+
+- [ ] classifyCommand 覆盖所有已知命令模式
+- [ ] destructive 命令被正确分级和阻断
+- [ ] CommandExecutionResult 包含完整证据
+- [ ] 命令执行链记录在 task_context 中

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

@@ -0,0 +1,56 @@
+---
+name: 工作流契约规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-工作流契约规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-workflow-contract
+routes:
+  - 工作流契约规则
+primary_triggers:
+  - 工作流契约规则
+secondary_triggers: []
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - mc-intent-router
+hard_blocks:
+  - workflow未注册
+  - mutation不匹配
+fallback: manual_required
+required_evidence:
+  - workflow_id
+  - required_mechanisms
+version: 1.0.0
+last_reviewed: '2026-05-22'
+migration_note: 知识资产标准化迁移
+type: hard_rule
+when: 工作流契约规则
+status: active
+---
+
+# 工作流契约规则
+
+## 核心原则
+
+每个工作流必须声明所需机制、知识注入要求和权限边界。工作流契约确保编排路径可验证。
+
+## 规则
+
+1. **机制声明**: 每个工作流必须声明 required_mechanisms
+2. **知识注入**: 每个工作流必须引用 mc-knowledge-injection-boundary
+3. **权限一致性**: read-only 工作流不可产生 mutation
+4. **入口回归**: 每个路由必须有对应的工作流
+5. **范围回归**: 工作流 scope 必须覆盖所有产出文件
+
+## 验收标准
+
+- [ ] 每个工作流有 required_mechanisms 列表
+- [ ] 知识注入机制被所有工作流引用
+- [ ] read-only 工作流无 mutation 产出
+- [ ] validateWorkflowContracts() 返回 0 hard_fail

package/templates/internal/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,144 @@
+---
+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 工具）。
+
+导航必须把用户确认项分为三类：
+
+1. `must_confirm`：影响业务口径、架构决策、权限模型、API/数据库语义、陈旧任务处理等不可由 AI 代决的事项。只有这类确认可以阻塞推进。
+2. `should_confirm`：确认后准确性更高，但不确认也允许继续只读分析、初始化、模板同步和低风险准备。
+3. `auto_resolvable`：可通过命令、复验或修复动作解决的事项，不应要求用户拍板。
+
+AI 不得只说“需要确认”。必须说明哪些是必须确认、哪些只是建议确认、哪些可以自动处理，并说明不确认的影响和下一步命令。
+
+从 0 开发的新项目没有既有项目事实可确认。此时只能确认目标、边界、技术选择和默认口径；不得把自动推断当成已有系统事实，也不得因为缺少既有事实阻塞初始化和只读规划。
+
+## 禁止动作规则
+
+以下 7 条规则在工作流导航中强制执行：
+
+1. **设计审计失败 → 禁止写业务代码**
+   - 条件：design_artifact_pack.status 不是 implementation_ready
+   - 阻断：sf_execute
+   - 必须先通过设计审计复验
+
+2. **配置未确认 → 区分自动修复与业务确认**
+   - 条件：项目阶段为 configuration_pending
+   - 阻断：除 sf_init、config_confirm 外的所有动作
+   - version 数字/字符串、scope 字符串/数组、config.evidence.json 缺失/过期/不匹配属于自动修复项，必须提示 soloforge config repair
+   - 产品类型、技术栈选择、仓库边界、业务范围等语义口径才进入 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 状态"然后自由发挥**
+- **不得把取消、归档或 Bash 写入当作恢复路径**
+- 必须从三个选项中选择：恢复旧任务 / 归档旧任务 / 开始新任务
+- 旧任务文件不得静默删除，只处理 current-task 指针
+- 选择必须留有审计痕迹
+
+## 阻断恢复协议
+
+当 SoloForge 的 Edit/Write/Bash hook 或 MCP 工具返回阻断时：
+
+- 不得建议“取消任务后直接写代码”。
+- 不得建议“先用 Bash 直接修改业务代码”。
+- 不得建议手动删除或清理 `.soloforge/state`。
+- 不得把“先实现后补验证”作为恢复路径。
+- 必须按工具返回的 `recovery_command`、`soloforge next`、`sf_expand`、`sf_verify` 或经用户确认的 `sf_status action=archive_stale confirm=true` 恢复。
+- 只有 `soloforge next` 或 `sf_status` 明确判定 current-task 陈旧时才允许归档；归档后仍必须重新 `sf_classify -> sf_expand` 建立受控任务，不能直接写代码。
+
+## 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、confirmation_decisions、recommended_commands、recommended_prompt、disallowed_next_actions、work_package。
+
+`confirmation_decisions` 必须包含：
+
+- `must_confirm`
+- `should_confirm`
+- `auto_resolvable`
+- `blocked_reason`
+- `recommended_action`

package/templates/internal/rules//345/267/245/344/275/234/346/265/201/346/250/241/346/235/277/345/214/205/350/247/204/345/210/231.md

@@ -0,0 +1,48 @@
+---
+name: 工作流模板包规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-工作流模板包规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-workflow-template-pack
+routes:
+  - code_execution
+  - multi_stage_plan
+primary_triggers:
+  - 模板消费
+  - 工作流模板
+secondary_triggers: []
+negative_triggers: []
+priority: P1
+specificity: 4
+consumes:
+  - ka-hard-rule-核心工程执行原则
+hard_blocks:
+  - 模板消费卡在中间状态
+  - 消费证据缺失
+  - 未注册直接注入
+fallback: manual_required
+required_evidence:
+  - template_pipeline_status
+  - consumption_trace_log
+version: 1.0.0
+last_reviewed: '2026-05-24'
+---
+
+# 工作流模板包规则
+
+## 硬规则
+
+1. **模板消费 pipeline 必须完整** — missing → file_created → indexed → registered → injected → consumed → verified
+2. **不可停在中间状态** — 模板消费不可卡在 registered 而不 injected
+3. **消费证据必须记录** — 每次状态推进都需要证据
+
+## 检查项
+
+- [ ] 模板消费 pipeline 完整
+- [ ] 无中间状态停滞
+- [ ] 消费证据已记录

package/templates/internal/rules//345/267/245/345/205/267/350/260/203/347/224/250/350/247/204/345/210/231.md

@@ -0,0 +1,61 @@
+---
+name: 工具调用规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-工具调用规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-tool-invocation-contract
+routes:
+  - 工具调用规则
+primary_triggers:
+  - 工具调用规则
+secondary_triggers: []
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - mc-workflow-contract
+hard_blocks:
+  - forbidden_next_tool
+  - strict_controlled未审批
+fallback: manual_required
+required_evidence:
+  - tool_trace
+  - invocation_violations
+version: 1.0.0
+last_reviewed: '2026-05-22'
+migration_note: 知识资产标准化迁移
+type: hard_rule
+when: 工具调用规则
+status: active
+---
+
+# 工具调用规则
+
+## 核心原则
+
+MCP 工具调用必须遵守契约约束: 工具链顺序、权限等级、禁止转换。
+
+## 工具分类
+
+1. **strict_controlled**: 严格管控工具，需要前置审批
+2. **read_only_bypass**: 只读工具，可自由调用
+3. **normal_controlled**: 常规管控工具，需遵守转换规则
+
+## 规则
+
+1. 每个工具必须声明 default_next_tools 和 forbidden_next_tools
+2. forbidden_next_tools 中的转换必须被阻断
+3. strict_controlled 工具不可跳过审批流程
+4. 工具调用链必须可追踪 (tool_trace)
+
+## 验收标准
+
+- [ ] 所有 MCP 工具在 Tool Invocation Contract Registry 中已注册
+- [ ] forbidden_next_tools 转换被正确阻断
+- [ ] validateToolInvocation() 返回 0 hard_fail
+- [ ] tool_trace 包含完整调用链

package/templates/internal/rules//346/204/217/345/233/276/350/267/257/347/224/261/350/247/204/345/210/231.md

@@ -0,0 +1,62 @@
+---
+name: 意图路由规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-意图路由规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-intent-router
+routes:
+  - 意图路由规则
+primary_triggers:
+  - 意图路由规则
+secondary_triggers: []
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - mc-classifier
+hard_blocks:
+  - 路由未裁决
+  - degraded未记录
+fallback: manual_required
+required_evidence:
+  - route_decision
+  - execution_shape
+version: 1.0.0
+last_reviewed: '2026-05-22'
+migration_note: 知识资产标准化迁移
+type: hard_rule
+when: 意图路由规则
+status: active
+---
+
+# 意图路由规则
+
+## 核心原则
+
+意图路由是 SoloForge 的入口裁决机制。所有用户意图必须先经过 intent_router 裁决，再进入后续流程。
+
+## 规则
+
+1. **入口唯一性**: routeIntent 是入口裁决的唯一来源，classifier 不可重新夺回入口裁决权
+2. **路由完整性**: 每个用户意图必须产出一个有效的 route_decision，包含 route、execution_shape、mutation_allowed
+3. **降级处理**: 路由失败时默认降级为 code_change，写入 `route_decision.degraded=true`
+4. **只读保护**: source_extraction 路由必须为 read-only，不允许 mutation
+5. **产物区分**: direct_answer 与 artifact_generation 必须严格区分
+
+## 失败模式
+
+- artifact_generation 被 skip → 应路由到 code_change 或 artifact_generation
+- source_extraction 允许 mutation → 应为 read-only
+- direct_answer 与产物语义混淆 → 应区分回答与生成
+
+## 验收标准
+
+- [ ] 所有 IntentRoute 类型都有对应的路由分支
+- [ ] route_decision 包含完整字段
+- [ ] degraded 路由标记为 degraded=true
+- [ ] read-only 路由不包含 mutation 指令

package/templates/internal/rules//346/211/247/350/241/214/345/256/210/345/215/253/350/257/204/344/274/260/350/247/204/345/210/231.md

@@ -0,0 +1,60 @@
+---
+name: 执行守卫评估规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-执行守卫评估规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-guard-evaluation
+routes:
+  - 执行守卫评估规则
+primary_triggers:
+  - 执行守卫评估规则
+secondary_triggers: []
+negative_triggers: []
+priority: P0
+specificity: 5
+consumes:
+  - mc-task-context-lifecycle
+hard_blocks:
+  - 非法状态转换
+  - failed→done
+fallback: manual_required
+required_evidence:
+  - guard_evaluation
+  - diagnostic_codes
+version: 1.0.0
+last_reviewed: '2026-05-22'
+migration_note: 知识资产标准化迁移
+type: hard_rule
+when: 执行守卫评估规则
+status: active
+---
+
+# 执行守卫评估规则
+
+## 核心原则
+
+执行守卫评估是 SoloForge 验证阶段的关键机制。它在 sf_verify 时评估各契约守卫的执行状态，确保验证计划覆盖所有必要的检查。
+
+## 规则
+
+1. **守卫覆盖**: 验证计划必须覆盖所有相关契约的守卫（隐私、命令、scope、artifact）
+2. **评估集成**: 守卫评估集成在各契约的验证逻辑内，不独立执行
+3. **结果传导**: 守卫评估失败必须传导到 VerificationResult，影响最终状态判定
+4. **降级安全**: 守卫评估不可用时，验证应降级为 advisory 而非跳过
+
+## 失败模式
+
+- 验证计划缺少隐私守卫 → 应在 generateVerifyCommands 中补充
+- 守卫评估结果被忽略 → 应传导到 sf_learn 状态判定
+- 守卫降级未通知用户 → 应通过 user_feedback 通知
+
+## 验收标准
+
+- [ ] generateVerifyCommands 包含隐私和命令守卫评估
+- [ ] 守卫评估失败时 core_principles.overall_passed 为 false
+- [ ] sf_learn 正确处理守卫评估失败的状态转移

package/templates/internal/rules//346/211/251/345/261/225/347/224/237/345/221/275/345/221/250/346/234/237/350/247/204/345/210/231.md

@@ -0,0 +1,48 @@
+---
+name: 扩展生命周期规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-扩展生命周期规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-extension-contract
+routes:
+  - code_execution
+  - multi_stage_plan
+primary_triggers:
+  - 扩展注册
+  - 权限申请
+secondary_triggers: []
+negative_triggers: []
+priority: P1
+specificity: 4
+consumes:
+  - ka-hard-rule-核心工程执行原则
+hard_blocks:
+  - 第三方扩展自称 enforced
+  - 高风险权限未审批
+  - 生命周期跳跃转移
+fallback: manual_required
+required_evidence:
+  - extension_manifest
+  - permission_approval_record
+version: 1.0.0
+last_reviewed: '2026-05-24'
+---
+
+# 扩展生命周期规则
+
+## 硬规则
+
+1. **第三方扩展不可自称 enforced** — 只有内置机制可以是 enforced 状态
+2. **高风险权限必须审批** — 文件写入、命令执行等权限需显式授权
+3. **生命周期转移必须合法** — registered → active → disabled → removed，不可跳跃
+
+## 检查项
+
+- [ ] 扩展 manifest 格式正确
+- [ ] 权限声明完整
+- [ ] 生命周期转移合法

package/templates/internal/rules//346/212/200/346/234/257/345/206/263/347/255/226/344/270/273/346/235/203/350/247/204/345/210/231.md

@@ -0,0 +1,64 @@
+---
+name: 技术决策主权规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-技术决策主权规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-decision-sovereignty
+asset_role: required
+consumed_by:
+  - mc-decision-sovereignty
+  - consumable_asset_registry
+  - workflow_template
+routes:
+  - 技术决策主权规则
+primary_triggers:
+  - 技术决策主权规则
+secondary_triggers:
+  - 技术选型
+  - 目录确认
+  - 架构不确定项
+  - 风险动作
+negative_triggers: []
+priority: P1
+specificity: 5
+consumes:
+  - mc-decision-sovereignty
+hard_blocks:
+  - 高影响决策无 human gate 自动执行
+  - 推荐状态（recommended）允许直接执行
+  - 不确定项只报告不给推荐和理由
+fallback: manual_required
+required_evidence:
+  - decision_contract
+  - human_confirmation
+version: 1.0.0
+last_reviewed: '2026-05-23'
+---
+
+# 技术决策主权规则
+
+## hard_rules
+
+- 不确定项必须给出推荐（recommendation）、理由（reasoning）、备选（alternatives）、风险（risks），并进入用户确认或计划闭环。
+- 决策状态流：proposed → recommended → confirmed / rejected / deferred。只有 `confirmed` 状态允许执行。
+- 高影响决策（架构变更、数据模型修改、外部依赖引入）必须经过 human gate 确认，不得自动执行。
+- 推荐状态（recommended）不得直接执行，必须转为 confirmed（含人类签署证据）后方可实施。
+- 用户项目中技术选型、目录确认、架构不确定项、风险动作都必须可消费该机制规则。
+
+## not_done_if_missing
+
+- 高风险无 human gate 自动执行 → hard fail。
+- heuristic 单独支撑高影响决策 → hard fail。
+- 不确定项只报告不给推荐和理由 → hard fail。
+- 推荐状态绕过确认直接执行 → hard fail。
+
+## verification_evidence
+
+- `TechnologyDecisionContract` 包含 decision_scope、recommendation、reasoning、alternatives、risks 字段。
+- `validateTechnologyDecision()` 检查 human gate 对高影响决策的必需性。
+- `diagnostic_codes`: no-human-gate, executing-recommended, missing-recommendation。