upgrade sm-flow v3.1 workflow

2026-05-21 19:55:23 +08:00
parent f45122dafb
commit 6a5520db33
26 changed files with 955 additions and 40 deletions
@@ -378,6 +378,98 @@ Phase 4    回填 devflow，并确认是否 archive

 `sm-flow` 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。

+## v3.1：可执行 gate 与使用摩擦修正
+
+v3.1 来自一次真实使用复盘：接口变更文档粒度、propose 后再 grill 的返工感、devflow 增长后的检索成本、子 skill 路径兼容，以及 Phase 3 中用户质疑和代码发现与原设计冲突时的处理方式，都需要变成可执行规则。
+
+v3.1 不改变 v3 的主轴：
+
+> `devflow/` 提供上下文，OpenSpec 提供执行依据，代码只是实现结果。
+
+### Draft / Committed OpenSpec
+
+Phase 1 产出的 OpenSpec 统一视为 **Draft OpenSpec**。它是后续 PRD 对齐、grill 和架构审计的讨论对象，不是实现许可。
+
+Phase 2 和 Phase 2.5 的结论必须回写 OpenSpec。随后新增 Phase 2.9：
+
+```text
+Phase 2.9 Commit OpenSpec
+```
+
+Phase 2.9 检查：
+
+- proposal 是否说明范围、非目标和原因。
+- design 是否记录关键约束、架构风险和接口影响。
+- specs 是否覆盖可观察行为和验收口径。
+- tasks 是否是可执行的纵向切片。
+- 是否还有未确认的 user-interview、未汇报的 evidence-driven 结论、未判级接口影响或 devflow/OpenSpec 冲突。
+
+只有通过 Phase 2.9 的 OpenSpec 才是 **Committed OpenSpec**，Phase 3 只能执行 Committed OpenSpec。
+
+### Grill 必须人工确认
+
+Phase 2 的 `grill-with-docs` 不是代理自问自答。`user-interview` 问题必须一次只问一个，等待用户显式回答，并记录到 `decisions.md`。未获得用户确认的问题不能视为已解决，也不能进入 Phase 2.9 或 Phase 3。
+
+`evidence-driven` 问题可以由代理先查证，但也必须汇报证据、结论和是否需要用户确认。
+
+单个 grill 决策确认不等于 Phase 3 apply 授权。用户在 Phase 2 回答“可以”只表示该问题已确认；代理必须先回写 OpenSpec/devflow，停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply、开始实现、执行修改或继续 Phase 3。
+
+### 接口影响分级
+
+v3.1 区分“接口影响记录”和“独立接口文档”：
+
+- 所有接口变更都必须记录影响范围。
+- 只有 L3/L4 才强制独立接口文档或等价独立章节。
+
+分级规则：
+
+| 级别 | 判断条件 | 产物要求 |
+| --- | --- | --- |
+| L1 内部实现 | 不改变调用方可观察行为 | tasks / acceptance 记录验证 |
+| L2 内部接口 | 内部 DTO、service 方法、内部事件、内部判断逻辑变化，消费者仍在同一实现范围内 | 内联接口影响记录 |
+| L3 协作接口 | 影响前端、其他模块/服务、跨团队消费者、数据库契约、事件、回调或 SDK | 独立接口文档或独立章节 |
+| L4 破坏性接口 | 旧调用方可能失败、数据/状态/错误码不同，或需要迁移/灰度/回滚 | 独立接口文档 + 迁移/回滚说明，必要时 ADR |
+
+接口内部判断逻辑也按可观察行为评估。即使签名和字段不变，只要返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用变化，也属于接口影响。
+
+### Devflow Index
+
+`devflow/index.md` 成为 Phase 0.5 的默认入口。上下文查找顺序为：
+
+```text
+devflow/index.md
+devflow/glossary/CONTEXT.md
+相关项目 brief / acceptance / ADR
+devflow/compound/
+```
+
+Phase 4 回填项目档案时必须更新 `devflow/index.md`。最小字段为日期、slug、领域、关键词、关联 OpenSpec 和状态。
+
+### 实现期冲突处理
+
+Phase 3 中，如果用户质疑、用户修改、代码发现、测试失败或运行行为与 Committed OpenSpec 冲突，必须先分类：
+
+| 分类 | 含义 | 处理 |
+| --- | --- | --- |
+| 实现偏差 | OpenSpec 正确，代码没有按规格做 | 修代码，不改 OpenSpec |
+| 规格遗漏 | OpenSpec 没覆盖真实边界、接口影响、验收或外部行为 | 暂停 apply，修正 OpenSpec，重新 commit |
+| 设计冲突 | OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突 | 暂停并请用户确认设计方向 |
+| 用户变更 | 用户改变目标、范围、验收或风险接受度 | 更新 proposal/specs/tasks 后继续 |
+
+冲突分类、证据、用户确认和 OpenSpec 回写状态必须进入 `decisions.md` 或 `acceptance.md`。
+
+### 子 skill 兼容
+
+v3.1 将子 skill 从“路径绑定”改为“能力绑定”。例如 `openspec-propose`、`openspec-apply-change`、`to-prd`、`grill-with-docs` 都是能力契约。
+
+调用优先级：
+
+1. 平台原生 skill。
+2. 本地 `SKILL.md`，例如 `.claude/skills/...` 或 `.agents/skills/...`。
+3. `sm-flow` 的 fallback 协议。
+
+这样 `sm-flow` 可以在 Claude、Codex 或其他代理环境中迁移，而不会被某个固定目录锁死。
+



@@ -0,0 +1,8 @@
+1. 如果涉及接口，需要额外产出一份影响接口范围文档
+	1. ❯ 只要涉及到接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中 
+2. 涉及接口变更，需要产出一份接口文档
+3. 顺序问题，目前的顺序是propose之后在，生成了task、design之后，再用grill去澄清需求，这样当澄清完需求后，又得回去更新task、design、proposal等文档，现在的流程，是propose之后，再通过to-prd，生成devflow的产物，然后再grill来更新，哪种设计更合理？
+4. 如果devflow数量多了，如何快速定位需要的上下文
+5. 子skill现在是固定了claude，要考虑兼容情况
+6. 当在开发阶段，我发起质疑或者修改，和原来设计冲突时，不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到，要提出反馈
+	1. 可能需要加多一个步骤，apply实施过程中的沟通？