git-learn/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/decisions.md

# SM Flow v3.1 Upgrade Decisions

## User-interview

| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
| --- | --- | --- | --- |
| 是否启动 v3.1 改造？ | “开始这次的v3.1改造” | 创建 `sm-flow-v3-1-upgrade` OpenSpec change 并进入改造。 | 已回写 |
| grill 过程中是否必须人工确认？ | 用户要求“如果 skill 里并没有强调 grill 的过程中一定要人工确认的话，加上这个约束”。 | Phase 2 的 user-interview 问题必须一问一答等待用户显式确认；未确认不能进入 Phase 2.9 / Phase 3。 | 已回写 |
| 接口变更是否需要记录影响范围？ | 用户要求“只要涉及接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中”。 | 所有接口变更必须有影响记录。 | 已回写 |
| 接口影响采用什么分级策略？ | 用户确认“可以，先按照分级来实现”。 | 采用 L1-L4 分级：L1 内部实现、L2 内部接口、L3 协作接口、L4 破坏性接口；接口内部判断逻辑按可观察行为评估。 | 已回写 |
| devflow 上下文索引是否强制维护？ | 用户确认“可以”。 | 强制维护轻量 `devflow/index.md`；Phase 0.5 先查 index，Phase 4 回填时必须更新 index。 | 已回写 |
| 实现阶段遇到与原设计冲突的质疑或修改时如何处理？ | 用户确认“可以”。 | Phase 3 采用四类实现期冲突分类：实现偏差、规格遗漏、设计冲突、用户变更；先分类和确认，再继续代码或 OpenSpec 修正。 | 已回写 |
| 子 skill 兼容规则是否采用能力优先？ | 用户确认“可以”。 | 子 skill 绑定能力契约，不绑定单一平台路径；调用优先级为平台原生 skill、本地 `SKILL.md`、sm-flow fallback。 | 已回写 |
| 单个 grill 决策确认是否等于 apply 授权？ | 用户确认“可以”。 | 单个 `user-interview` 的“可以”只确认该决策；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，等待明确 Phase 3 apply 授权。 | 已回写 |

## Evidence-driven 澄清

| 维度 | 模式 | 问题 | 证据 / 用户反馈 | 结论 | 是否回写 OpenSpec |
| --- | --- | --- | --- | --- | --- |
| 术语 | evidence-driven | “接口影响范围文档”和“接口文档”是否同一产物？ | 用户分别列为两个问题；流程需要降低文档重复。 | 区分“接口影响记录”和“独立接口文档”。 | 是 |
| 边界 | evidence-driven | v3.1 是否要改变 OpenSpec-first 主轴？ | v3 skill 本体和历史评估都把 OpenSpec 定义为执行真理源。 | 不改变主轴，只补 gate。 | 是 |
| 验收 | evidence-driven | 如何证明 v3.1 改造完成？ | OpenSpec specs 已覆盖接口影响、commit gate、上下文索引和 apply 冲突处理。 | 验收以文档规则可检索、OpenSpec status 完成、tasks 勾选为准。 | 是 |

## 关键取舍

- 决策：采用 Draft / Committed OpenSpec，而不是把 grill 移到 propose 前。
  - 原因：Draft 给澄清提供结构化对象，Committed 防止草稿直接执行。
  - 影响：新增 Phase 2.9，但减少 Phase 3 规格漂移。
  - 风险接受：本次 v3.1 接受。

- 决策：接口变更采用 L1-L4 分级。
  - 原因：所有接口影响都需要追踪，但只有高影响变更需要独立接口文档。
  - 影响：templates 和 phase contracts 需要增加接口影响记录。
  - 风险接受：本次 v3.1 接受。

- 决策：为 devflow 增加 `devflow/index.md`。
  - 原因：项目档案增长后，需要索引而不是每次全量翻阅。
  - 影响：Phase 0.5 和 Phase 4 都需要维护索引。
  - 风险接受：本次 v3.1 接受。