soloforge 1.1.40 → 1.1.43

package/templates/procedures//346/225/260/346/215/256/345/272/223/350/277/201/347/247/273/346/265/201/347/250/213.md

@@ -1,56 +0,0 @@
----
-name: database-migration
-type: procedure
-scope:
-  - backend
-products:
-  - '*'
-id: ka-procedure-数据库迁移流程
-lifecycle_status: active
-authority: supporting
-owner_mechanism_id: mc-knowledge-asset-governance
-priority: P1
-consumes:
-  - mc-knowledge-asset-governance
-emits:
-  - migration_script
-  - rollback_script
-  - migration_compatibility_check
-required_evidence:
-  - execution_evidence
-version: 1.1.0
-last_reviewed: '2026-06-01'
-stages: ["编码与单元测试", "联调验证"]
-triggers: ["数据库变更","表结构修改","migration","DDL","加字段","建表","索引","数据迁移","表结构变更"]
----
-
-## 适用场景
-数据库表结构变更（新增表、加字段、改字段、加索引、数据迁移等）。所有 DDL 变更必须通过 migration 脚本管理，禁止手动执行。
-
-## 步骤
-1. 评估变更类型：加列、改列、删列、加索引、数据迁移、新建表
-2. 确认向前兼容性：新列必须有默认值或允许 NULL，不删除正在使用的列
-3. 编写 migration 脚本（Flyway/MyBatis Migrations），DDL 脚本放 resources/db，文件名 V{version}__{description}.sql（正向）和 U{version}__{description}.sql（回滚）
-4. 确保 migration 脚本幂等（重复执行不出错）
-5. 编写回滚脚本（每个 migration 必须有对应的 rollback）
-6. 禁止在 migration 脚本中写业务逻辑（业务变更走应用代码）
-7. 大表加列必须指定默认值或使用分批更新
-8. 在开发环境执行 migration，验证表结构变更正确
-9. 检查数据迁移逻辑：大数据量迁移需分批执行（每批 1000 条）
-10. 在测试环境验证：运行应用 + 执行全量测试
-11. 评估执行时间：大表加索引按锁表风险处理，需在低峰期执行并准备回滚窗口
-12. 生产执行前备份数据库（全量或变更表）
-
-## 检查点
-- [ ] migration 脚本有对应回滚脚本
-- [ ] migration 脚本幂等（可重复执行）
-- [ ] 新增列有默认值或允许 NULL（向前兼容）
-- [ ] migration 脚本无业务逻辑
-- [ ] 大数据量迁移使用分批策略
-- [ ] 生产执行前已完成数据库备份
-
-## 注意事项
-- 禁止使用 DROP COLUMN（应标记为 deprecated 后续清理）
-- 加索引在 >100 万行表上使用 ONLINE DDL 或 pt-online-schema-change
-- migration 脚本一旦执行到生产不可修改（只能新增补偿脚本）
-- 字段兼容策略必须同时覆盖四层：数据库、接口契约、前端展示、导出逻辑

package/templates/procedures//346/234/254/345/234/260/346/265/217/350/247/210/345/231/250/351/252/214/346/224/266/345/267/245/344/275/234/346/265/201.md

@@ -1,90 +0,0 @@
----
-name: local-browser-acceptance-workflow
-type: procedure
-scope:
-  - backend
-  - frontend
-  - infrastructure
-products:
-  - '*'
-owner_mechanism_id: mc-local-acceptance
-consumed_contracts:
-  - local_acceptance_contract_entry
-  - coding_readiness_contract_entry
-  - detail_discipline_contract
-required_sections:
-  - 服务运行规格
-  - 浏览器验收计划
-  - 修复循环策略
-  - 最终访问交付
-hard_rules:
-  - 有可运行前端/全栈服务时，不得只停在单测、静态检查或审查报告
-  - 项目已有 docker-compose 时必须优先使用
-  - 必须识别 frontend、backend、database、env、ports 和 health checks
-  - 服务启动后必须等待 container healthy、backend health、frontend reachable
-  - >-
-    浏览器验收失败必须 capture → classify → map owner → repair → rebuild → redeploy →
-    rerun
-  - 最终必须给用户本地可访问 URL、运行状态、启动/停止命令
-  - 未给最终本地 URL 不得 delivered
-acceptance_checks:
-  - requiresLocalAcceptance 判断正确
-  - ServiceRuntimeSpec 已识别所有服务
-  - 浏览器验收计划覆盖任务相关页面和路由
-  - 修复循环策略包含 max_iterations 和 stop_conditions
-  - FinalLocalReviewAccess 包含 frontend_urls/backend_urls/docs_or_swagger_urls
-  - validateFinalAccess passed
-id: ka-procedure-本地浏览器验收工作流
-lifecycle_status: active
-authority: supporting
-priority: P1
-consumes:
-  - mc-local-acceptance
-emits:
-  - browser_acceptance_report
-  - service_urls
-required_evidence:
-  - workflow_id
-  - required_mechanisms
-version: 1.1.0
-last_reviewed: '2026-06-01'
-stages: ["联调验证"]
-triggers: ["本地验收","浏览器验收","Docker 验收","本地测试","local acceptance","browser test","docker compose"]
----
-
-## 适用场景
-含前端/全栈服务的项目完成开发后，必须在本地启动服务并通过浏览器验收。适用于有 docker-compose、npm start 或类似启动方式的项目。
-
-## 步骤
-1. **判断是否需要本地验收**: requiresLocalAcceptance 判断
-2. **服务运行规格**:
-   - 识别 frontend、backend、database/cache、env、ports、health checks
-   - docker-compose 优先，否则用项目启动命令
-3. **启动服务**:
-   - 启动所有服务
-   - 等待 container healthy、backend health endpoint、frontend reachable、DB migrated
-   - 检查 logs 无关键错误、port open
-4. **浏览器验收**:
-   - 覆盖任务相关页面、路由、核心交互
-   - API 联动、登录/权限、错误提示、空状态/loading
-   - 检查控制台关键错误和 network 关键失败
-5. **失败处理** (修复循环):
-   - capture failure → classify failure → map owner files
-   - repair within scope → rebuild → redeploy → rerun
-   - retry budget 内循环；超预算 → manual_required
-6. **最终交付**:
-   - 给用户 frontend/backend/docs/swagger 本地 URL
-   - 给用户运行状态、启动/停止命令、测试账号说明、人工查验步骤、未覆盖风险
-
-## 检查点
-- [ ] requiresLocalAcceptance 判断正确
-- [ ] 所有服务启动且 healthy
-- [ ] 浏览器验收覆盖关键页面
-- [ ] 修复循环有预算和停止条件
-- [ ] 最终 URL 交付完整
-
-## 禁止退化
-- 不得只停在单测或审查报告
-- 无 URL 不得 delivered
-- CI 环境无 Docker 时 not_applicable_with_reason，但不能把 runnable 项目判为 delivered
-- retry budget 超出或 scope 不足必须 manual_required

package/templates/procedures//346/236/266/346/236/204/345/206/263/347/255/226/347/240/224/350/256/250/345/267/245/344/275/234/346/265/201.md

@@ -1,50 +0,0 @@
----
-name: architecture-decision-workshop
-type: procedure
-scope:
-  - backend
-  - frontend
-  - infrastructure
-products:
-  - '*'
-owner_mechanism_id: mc-architecture-decision-workshop
-id: ka-procedure-architecture-decision-workshop
-lifecycle_status: active
-authority: supporting
-priority: P0
-version: 1.2.0
-last_reviewed: '2026-06-04'
-required_evidence:
-  - architecture_decision_workshop
-  - user_confirmation_ref
-consumes:
-  - user_intent
-  - project_context_detection
-  - existing_system_analysis
-  - 不确定时头脑风暴流程
-  - 第一性原理推理规则
-emits:
-  - architecture_decision_workshop
-  - docs/architecture/00-架构决策记录.md
-stages: ["架构设计"]
-triggers: ["架构设计","技术架构","系统设计","平台建设","服务拆分"]
----
-
-# 架构决策研讨工作流
-
-## 顺序
-
-1. 判断项目为现有系统、新系统、空项目或重构升级。
-2. 现有系统先获取现状与差距证据；空项目先确认业务目标和约束。
-2a. **头脑风暴触发**：若方案选项 ≥ 3 个且无明确最优，或 AI 自检不确定：
-   → 进入「不确定时头脑风暴流程」（templates/procedures/不确定时头脑风暴流程.md）
-   → 若 fundamental_need 为空 → 先触发 FP-01
-3. 默认按业务流程、数据、安全、后端、前端、基础设施逐域讨论。
-4. 每域提供方案、推荐、风险与需要确认的问题；确认后记录 decision ref。
-5. 全部必要域确认后生成 `docs/architecture/00-架构决策记录.md`。
-6. 仅以该决策记录驱动正式架构设计与设计产物包。
-
-## 失败处理
-
-- 缺证据、缺确认或决策返工时，停止生成正式文档并说明下一项待决事项。
-- 不得用模版默认值或模型偏好替代项目事实与用户决定。

package/templates/procedures//346/236/266/346/236/204/350/256/276/350/256/241/345/267/245/344/275/234/346/265/201.md

@@ -1,115 +0,0 @@
----
-name: architecture-design-workflow
-type: procedure
-scope:
-  - backend
-  - frontend
-  - infrastructure
-products:
-  - '*'
-owner_mechanism_id: mc-architecture-design
-consumed_contracts:
-  - architecture_decision_workshop_contract
-  - design_artifact_pack_contract
-  - architecture_design_contract_entry
-  - technology_decision_contract
-  - brainstorm_contract
-  - detail_discipline_contract
-  - first_principles_contract
-required_sections:
-  - 输入集确认
-  - 输出目录决策
-  - 技术栈策略
-  - 前端仓库策略
-  - 不确定项决策
-  - Mermaid 图要求
-  - 架构设计审查
-  - 约束条件分析
-  - NFR 启发与权衡
-  - 架构范式选择
-hard_rules:
-  - 正式架构设计前必须完成六类架构决策研讨并引用用户确认的决策记录
-  - 架构设计必须进入包含数据库、API、OpenAPI/SQL 和一致性报告的设计产物包复验流程
-  - 输出目录名必须给推荐并进入用户确认；未确认时不得 delivered
-  - 后端必须默认优先 Java，除非存在项目证据或用户确认 override
-  - 前端必须默认优先最新稳定 Vue 生态 + TypeScript，除非存在项目证据或用户确认 override
-  - 不同前端端必须默认不同项目仓库或独立应用边界；合并仓库必须用户确认
-  - 不确定项必须包含推荐、理由、备选、风险和用户确认问题
-  - 架构级不确定项必须接 Brainstorm / Decision Sovereignty / User Confirmation
-  - 关键业务流程必须有 Mermaid sequenceDiagram
-  - Mermaid 必须可渲染
-acceptance_checks:
-  - ArchitectureDesignContract 已创建且 status 非 pending
-  - 输出目录决策 status 为 confirmed
-  - 所有 required_source_artifacts 已覆盖
-  - Mermaid 图 render_check_status 为 passed
-  - 架构设计审查 review.passed 为 true
-id: ka-procedure-架构设计工作流
-lifecycle_status: active
-authority: supporting
-priority: P1
-consumes:
-  - mc-architecture-design
-  - 不确定时头脑风暴流程
-  - 第一性原理推理规则
-emits:
-  - architecture_design_contract
-  - design_artifact_pack
-  - architecture_decision_records
-required_evidence:
-  - workflow_id
-  - required_mechanisms
-version: 1.2.0
-last_reviewed: '2026-06-04'
-stages: ["架构设计", "详细设计"]
-triggers: ["架构设计","架构","architecture","设计系统","多端设计","系统设计","技术方案设计","模块划分","技术方案","方案设计","架构评审"]
----
-
-## 适用场景
-从多个 task 输入（原型说明、需求文档等）到完整架构设计产出的工作流。适用于多端、多模块、有不确定项的系统设计。
-
-## 步骤
-1. **输入集确认**: 识别所有 task-* 目录下的原型说明及需求文档，确认覆盖所有端
-2. **架构决策研讨**: 逐域闭合业务流程、数据、安全、后端、前端和基础设施决策，生成 `00-架构决策记录.md`
-   - 每条决策使用 MADR 格式记录（标题/状态/上下文/决策/候选方案/理由/后果）
-   - ADR 状态管理：Proposed → Accepted → Superseded（被新 ADR 替代时标注 Superseded-By）
-   - 跨域权衡检测：某个域的决策可能影响其他域时，自动标记需重新确认的域
-2a. **头脑风暴触发**：若架构决策存在 ≥ 3 个候选方案且无明确最优，或 AI 自检不确定：
-   → 进入「不确定时头脑风暴流程」（templates/procedures/不确定时头脑风暴流程.md）
-   → 若 fundamental_need 为空 → 先触发 FP-01
-2b. **约束条件分析**: 读取需求文档中的约束、技术栈限制、合规要求，按技术/组织/法规/预算分类填充 Ch3a
-3. **输出目录决策**: 给出推荐目录名，等待用户确认
-4. **技术栈策略**:
-   - 后端默认 Java 优先（项目证据或用户确认可 override）
-   - 前端默认最新稳定 Vue 生态 + TypeScript（语言、构建工具、路由、状态管理、接口类型、测试、lint/format）
-   - 项目已有技术栈优先于 SoloForge 默认
-4a. **架构范式选择**（可选）: 参考七范式栈启发式菜单（DDD/Clean Architecture/Hexagonal/Modular Monolith/GRASP/SOLID/ADR），Agent 推荐 + 用户选择，填充 Ch4a。跳过条件：用户明确表示不需要范式指导
-5. **前端仓库策略**: 不同前端端默认不同仓库；合并仓库需用户确认
-6. **不确定项决策**: 每个不确定项包含推荐、理由、备选、风险和用户确认问题
-7. **架构级不确定项**: 接入 Brainstorm → Decision Sovereignty → User Confirmation
-8. **设计产物包**: 架构、数据库、API、OpenAPI/SQL 和一致性报告按权威来源联动生成/升级
-9. **Mermaid 图**: 关键业务流程、登录鉴权、跨端协作、前后端交互、异步任务必须有 sequenceDiagram
-9a. **NFR 启发与权衡**: 按 4 类 13+ 质量属性启发（性能/可靠性/安全性/可维护性），每项 NFR 须有量化目标值 + 验证方式，填充 Ch10.1 性能预算表 + Ch10.4 验证策略表
-10. **架构设计审查**: reviewArchitectureDesign 与 DesignArtifactPack 真实复验通过
-
-## 检查点
-- [ ] 所有 task-* 输入已识别并覆盖
-- [ ] 六类架构决策均已确认并记录 decision refs
-- [ ] 输出目录已用户确认
-- [ ] 技术栈有项目证据或用户确认支撑
-- [ ] 不确定项全部有推荐和用户确认问题
-- [ ] Mermaid sequenceDiagram 覆盖关键流程
-- [ ] reviewArchitectureDesign passed
-- [ ] 设计产物包进入 implementation_ready
-- [ ] 约束条件 4 类各至少 1 条
-- [ ] NFR 每项有量化目标值
-- [ ] 架构范式选择（若启用）有用户确认
-
-## 禁止退化
-- 未确认目录不得 delivered
-- 缺少 Mermaid 图不得 completed
-- 六类决策未确认或设计产物包未复验不得 completed
-- 架构级决策无 human gate 不得 approved
-- 模版章节缺失不得 completed
-- ADR 状态变更未经用户确认不得推进
-- 六域确认后不得推翻已确认域的决策（推翻须记录 ADR 并重新确认受影响域）

package/templates/procedures//346/246/202/345/277/265/351/252/214/350/257/201/346/265/201/346/260/264/347/272/277.md

@@ -1,45 +0,0 @@
----
-name: poc-pipeline
-type: pipeline_procedure
-scope:
-  - backend
-  - frontend
-products:
-  - '*'
-id: ka-procedure-概念验证流水线
-lifecycle_status: active
-authority: supporting
-owner_mechanism_id: mc-brainstorm-contract
-priority: P1
-consumes:
-  - mc-brainstorm-contract
-  - 不确定时头脑风暴流程
-  - 第一性原理推理规则
-emits:
-  - poc_research_report
-  - poc_prototype
-  - poc_conclusion
-required_evidence:
-  - execution_evidence
-version: 1.1.0
-last_reviewed: '2026-06-01'
-stages: ["架构设计"]
-triggers: ["技术验证","POC","可行性验证","技术选型","技术调研","原型验证","spike"]
----
-
-# 技术验证管线
-
-## 第1步：调研分析
-明确验证目标和成功标准。调研候选方案的生态成熟度、社区活跃度、性能基准、与现有技术栈兼容性。列出关键评估维度和权重。
-产出保存到：.soloforge/output/01-调研报告.md
-工具：sf_command
-
-## 第2步：原型实现
-选择 1-2 个最有前景的方案实现最小原型。原型聚焦核心验证点，不追求完整功能。记录实现过程中的关键发现（坑、限制、惊喜）。
-工具：sf_stage_execute, sf_scaffold
-
-## 第3步：评估结论
-对比各方案在关键维度的表现（附量化数据）。给出推荐方案和理由。列出遗留风险和后续关注点。明确结论：推荐采用/需进一步验证/不建议采用。
-模版：POC结论模版.md
-产出保存到：.soloforge/output/03-POC结论.md
-工具：sf_gate_check, sf_stage_advance

package/templates/procedures//346/265/213/350/257/225/344/274/230/345/205/210/347/274/226/347/240/201/345/267/245/344/275/234/346/265/201.md

@@ -1,96 +0,0 @@
----
-name: test-first-coding-workflow
-type: procedure
-scope:
-  - backend
-  - frontend
-products:
-  - '*'
-owner_mechanism_id: mc-coding-readiness
-consumed_contracts:
-  - coding_readiness_contract_entry
-  - existing_system_analysis_contract_entry
-  - architecture_design_contract_entry
-  - detail_discipline_contract
-  - first_principles_contract
-required_sections:
-  - 编码准备门
-  - 测试优先计划
-  - 约束消费报告
-  - 主线消费检查
-  - 编码完成审查
-hard_rules:
-  - coding workflow 不得直接进入实现
-  - 必须先生成 CodingReadinessGate
-  - 必须先生成 TestFirstPlan 或合法 not_applicable_with_reason
-  - 有测试框架且行为可断言时，必须先写失败测试或回归测试
-  - readiness_status=blocked/manual_required 时不得写实现代码
-  - 现有项目新需求必须消费 ExistingSystemAnalysis 和 RequirementGapAnalysis
-  - 根据架构设计编码时必须消费 ArchitectureDesignContract
-  - 测试失败不得删除测试、降低断言、skip 后声称通过
-  - 每个切片至少覆盖 ≥9 个测试场景（≥3 正常路径 + ≥3 边界条件 + ≥3 异常路径）
-  - 模式 B 不得用于支付/状态流转/权限/跨系统同步逻辑
-acceptance_checks:
-  - CodingReadinessGate status 非 blocked
-  - TestFirstPlan 已创建且 status 为 written 或 expected_failure_recorded
-  - 约束消费报告无 blocking_missing_constraints
-  - 主线消费检查无 orphan_findings
-  - 编码完成审查 review.passed 为 true
-id: ka-procedure-测试优先编码工作流
-lifecycle_status: active
-authority: supporting
-priority: P1
-consumes:
-  - mc-coding-readiness
-  - 不确定时头脑风暴流程
-  - 第一性原理推理规则
-emits:
-  - test_first_plan
-  - coding_completion_review
-required_evidence:
-  - workflow_id
-  - required_mechanisms
-version: 1.2.0
-last_reviewed: '2026-06-04'
-stages: ["编码与单元测试"]
-triggers: ["实现需求","编码","开发功能","写代码","coding","test first","测试优先","先写测试"]
----
-
-## 适用场景
-任何编码实现前必须先通过编码准备门和测试优先计划。适用于有测试框架和可断言业务逻辑的项目。
-
-## 步骤
-1. **编码准备门**:
-   - 检查是否有验证计划 (verification_plan_ref)
-   - 检查前置条件（现有项目需差距分析，架构设计需 ArchitectureDesignContract）
-   - 检查约束消费
-2. **测试优先计划**:
-   - 有测试框架且行为可断言 → test_first（先写失败测试）
-   - 不能自动测试 → verification_case_first 或 manual_acceptance_first
-   - TestFirstPlan 绑定需求、主链路入口和验收标准
-2a. **头脑风暴触发**：若实现方案选择存在不确定性（模式 A/B 不确定、模块间依赖不清晰、反复修复同一逻辑）：
-   → 进入「不确定时头脑风暴流程」（templates/procedures/不确定时头脑风暴流程.md）
-   → 若 fundamental_need 为空 → 先触发 FP-01
-3. **编码实现**: 按 TestFirstPlan 选择模式：
-   - **模式 A**：严格测试先行（red→green→refactor）——推荐核心逻辑
-     1. 编写失败测试（red）
-     2. 编写最小实现使测试通过（green）
-     3. 重构优化（refactor）
-   - **模式 B**：红绿合并（同时编写测试和实现）——适用简单逻辑/CRUD
-     - 约束：不降低覆盖率（≥9 场景）；不适用于支付/状态流转/权限/跨系统同步
-   - **模式 B 约束**：不降低覆盖率（≥9 场景）；禁止用于支付/状态流转/权限/跨系统同步逻辑
-4. **主线消费检查**: 新增文件、组件、API、service 被真实消费
-5. **编码完成审查**: reviewCodingCompletion 验证所有硬规则
-
-## 检查点
-- [ ] CodingReadinessGate allowed
-- [ ] TestFirstPlan status 为 written
-- [ ] 约束消费无 blocking_missing
-- [ ] 主线消费无 orphan
-- [ ] 编码完成审查 passed
-
-## 禁止退化
-- 缺验证计划不得编码
-- blocked/manual_required 不得写实现代码
-- 测试失败不得删测试或降断言
-- 未消费前置条件不得编码

package/templates/procedures//346/272/220/347/240/201/345/216/237/345/236/213/344/272/244/344/273/230/346/265/201/347/250/213.md

@@ -1,56 +0,0 @@
----
-name: source-prototype-to-delivery
-type: pipeline_procedure
-scope:
-  - backend
-  - frontend
-products:
-  - '*'
-id: ka-procedure-源码原型交付流程
-lifecycle_status: active
-authority: supporting
-owner_mechanism_id: mc-artifact-contract
-priority: P1
-consumes:
-  - mc-artifact-contract
-emits:
-  - prototype_specification
-  - source_code_delivery
-required_evidence:
-  - execution_evidence
-version: 1.1.0
-last_reviewed: '2026-06-01'
-stages: ["架构设计"]
-triggers: ["用户提供需求文档、原型源码"]
----
-
-# 源码原型需求到交付
-
-## 第1步：原型抓取
-只能从导出的源码包（如 React/Vite zip）或已解压源码目录提取原型信息：路由、页面组件、布局结构、状态变量、事件处理、弹窗/导航/表单交互、样式令牌和导入的业务说明。禁止使用 Figma MCP、浏览器运行态、figma.site 或截图作为补充来源。若未提供源码包或源码目录，停止原型抓取并要求补充源码输入。对每个端或页面独立输出原型说明。
-模版：原型说明模版.md
-产出保存到：.soloforge/output/01-原型说明.md
-工具：source
-
-## 第2步：架构设计
-根据原型说明和需求文档，设计系统模块划分、数据流向、技术选型与依据、风险点与应对方案。
-产出保存到：.soloforge/output/02-架构设计.md
-
-## 第3步：详细设计
-根据架构设计产出，把数据结构和接口契约落到正式设计载体。
-默认产出：
-- docs/architecture/02-数据库设计文档.md
-- docs/architecture/03-API接口规格文档.md
-- docs/api/openapi.yaml
-- db/migration 或 db/migrations 下的 SQL/migration 权威资产
-
-## 第4步：接口设计
-设计 API 路径、请求/响应结构、错误码、鉴权方案。接口契约必须写入 `docs/architecture/03-API接口规格文档.md` 并与 `docs/api/openapi.yaml` 对齐。
-
-## 第5步：编码实现
-根据切片计划和追踪矩阵绑定的 `SLICE-*`、`DD-*`、`AC-*` 进行前后端编码实现。可使用脚手架生成骨架代码。
-工具：sf_scaffold, sf_stage_execute
-
-## 第6步：测试与审查验收
-执行自动验证（构建 + 测试）、代码审查（质量/安全/性能/架构/技术债务五维度）、学习记录。
-工具：sf_gate_check, sf_review, sf_stage_advance

package/templates/procedures//347/216/260/346/234/211/347/263/273/347/273/237/345/267/256/350/267/235/345/210/206/346/236/220/345/267/245/344/275/234/346/265/201.md

@@ -1,116 +0,0 @@
----
-name: existing-system-gap-analysis-workflow
-type: procedure
-scope:
-  - backend
-  - frontend
-  - infrastructure
-products:
-  - '*'
-owner_mechanism_id: mc-existing-system-analysis
-consumed_contracts:
-  - existing_system_analysis_contract_entry
-  - architecture_design_contract_entry
-  - technology_decision_contract
-  - brainstorm_contract
-  - detail_discipline_contract
-  - first_principles_contract
-required_sections:
-  - 项目上下文检测
-  - 现有系统分析
-  - 需求差距分析
-  - 回归风险评估
-  - 主线集成计划
-  - 验证计划
-hard_rules:
-  - >-
-    existing_system + new_requirement 必须先生成 ExistingSystemAnalysisContract 和
-    RequirementGapAnalysis
-  - new_system / empty_project 不得强制执行 ExistingSystemAnalysis
-  - unknown 必须 manual_required，不能猜测继续
-  - 现有系统分析必须读取真实代码和相关文档，不能只读需求文档
-  - >-
-    分析结论必须区分 fact / inference / assumption / unknown，并带 confidence 和
-    evidence_refs
-  - 差距分析必须列出现有能力、缺失能力、复用模块、required_changes、兼容/数据/权限/集成风险
-  - 实现前必须有 MainlineIntegrationPlan
-  - VerificationPlan 必须从 RequirementGapAnalysis 生成
-  - >-
-    回归风险评估须产出高回归风险区域列表和 AI 能力边界评估表，每项改造有风险等级
-  - >-
-    环境验证须通过（编译 + 测试套件 + 接口调用），未通过不得进入设计或编码；无测试套件时降级为编译通过 + 关键接口可调通
-acceptance_checks:
-  - project_context_type 已检测且非 unknown
-  - ExistingSystemAnalysisContract 已创建
-  - RequirementGapAnalysis 已创建
-  - 现有项目已有技术栈和项目约定优先于 SoloForge 默认
-  - 分析结论包含 fact/inference/assumption/unknown 分类
-  - 回归风险评估已产出（高回归风险区域 + AI 能力边界评估）
-  - 环境验证已通过（编译 PASS + 测试 PASS + 接口可调通）
-  - 高回归风险区域已有缓解措施或人工确认记录
-id: ka-procedure-现有系统差距分析工作流
-lifecycle_status: active
-authority: supporting
-priority: P1
-consumes:
-  - mc-existing-system-analysis
-  - 不确定时头脑风暴流程
-  - 第一性原理推理规则
-emits:
-  - existing_system_analysis
-  - requirement_gap_analysis
-  - mainline_integration_plan
-  - verification_plan
-  - regression_risk_assessment
-required_evidence:
-  - workflow_id
-  - required_mechanisms
-version: 1.2.0
-last_reviewed: '2026-06-04'
-stages: ["现有系统分析"]
-triggers: ["现有项目","新需求","已有系统","现有系统","差距分析","gap analysis","existing system","现有源码"]
----
-
-## 适用场景
-已有源码、路由、API、前端页面、权限模型和测试脚本的项目中开发新需求。必须先分析现有系统、再做差距分析、最后才进入设计或编码。
-
-## 步骤
-1. **项目上下文检测**: detectProjectContext 判断 project_context_type
-2. **现有系统分析**:
-   - 读取真实代码和相关文档
-   - 识别技术栈、路由、API、前端页面、权限模型、测试脚本
-   - 区分 fact / inference / assumption / unknown
-   - 同时读取 `历史遗留雷区清单` 和 `数据血缘图`，将发现标注到差距分析
-   - 雷区中"高风险"项 → 差距分析 required_changes 中标注 `minefield:high`
-   - 数据血缘图中受影响接口 → 差距分析中标注 `lineage:affected`
-3. **需求差距分析**:
-   - 列出现有能力、缺失能力、复用模块
-   - 列出 required_changes、optional_changes、out_of_scope
-   - 列出兼容/数据/权限/集成风险、前后端影响、测试回归范围
-3a. **头脑风暴触发**：若改造方案存在多种路径且无明确最优，或复用/重写决策不确定：
-   → 进入「不确定时头脑风暴流程」（templates/procedures/不确定时头脑风暴流程.md）
-   → 若 fundamental_need 为空 → 先触发 FP-01
-3b. **回归风险评估**（基于 SWE-CI 研究：75% AI 引入回归）:
-   - 量化每项改造的回归风险（高/中/低），产出结构化表格
-   - 评估每项改造的 AI 自主能力（低级编辑/接口调整/架构重构）
-   - 执行环境验证（编译 + 测试 + 接口调用），建立回归基线
-4. **主线集成计划**: 新增文件、组件、API、service、DTO/model、配置必须被真实消费
-5. **验证计划**: VerificationPlan 从 RequirementGapAnalysis 生成
-
-## 检查点
-- [ ] project_context_type 已检测
-- [ ] 现有系统分析读取了真实代码
-- [ ] 差距分析包含完整风险列表
-- [ ] MainlineIntegrationPlan 已创建
-- [ ] VerificationPlan 已从差距分析生成
-- [ ] 回归风险评估已产出（每项改造有风险等级 + AI 能力评估）
-- [ ] 环境验证已通过（编译 + 测试 + 接口调用）
-- [ ] 高回归风险区域已有缓解措施
-
-## 禁止退化
-- existing_system 未分析不得进入设计或编码
-- unknown 类型不得猜测继续，必须 manual_required
-- 不能只读需求文档，必须读代码
-- 缺差距分析不得 coding
-- 回归风险评估未产出不得进入设计或编码
-- 环境验证未通过不得进入设计或编码（降级策略按规则执行）