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
@@ -0,0 +1,59 @@
+# SM Flow v3.1 Upgrade Acceptance
+
+## 结果
+
+已接受。
+
+## 验证
+
+### 静态验证
+
+- 命令/检查：`openspec status --change "sm-flow-v3-1-upgrade"`
+- 结果：passed
+- 备注：proposal、design、specs、tasks 均为 complete。
+
+- 命令/检查：`rg -n "Draft OpenSpec|Committed OpenSpec|Phase 2.9|devflow/index.md|接口影响|实现期冲突|能力契约|平台原生 skill|user-interview" ...`
+- 结果：passed
+- 备注：关键术语已覆盖 `.agents/skills/sm-flow/`、OpenSpec change、workflow 文档和 devflow 项目档案。
+
+### 脚本验证
+
+- 命令：`openspec instructions apply --change "sm-flow-v3-1-upgrade" --json`
+- 结果：passed
+- 备注：所有 17 个 OpenSpec tasks 已完成。
+
+### 浏览器/人工验证
+
+- 步骤：不适用，本次是流程文档和 OpenSpec 规则改造。
+- 结果：not run
+- 备注：无 UI 行为。
+
+## 已完成范围
+
+- 增加 Draft OpenSpec / Committed OpenSpec / Phase 2.9 commit gate。
+- 强化 Phase 2 grill 的显式人工确认约束。
+- 增加“单个 grill 决策确认不等于 Phase 3 apply 授权”的硬约束。
+- 增加接口影响 L1-L4 分级和接口影响记录模板。
+- 增加 `devflow/index.md` 和 Phase 0.5 / Phase 4 索引维护规则。
+- 增加 Phase 3 实现期冲突四分类和 fallback 执行规则。
+- 将子 skill 兼容规则改为能力契约优先、路径其次。
+- 更新 `skill-workbench/docs/sm-flow/workflow.md` 的 v3.1 说明。
+
+## 已知限制
+
+- `openspec/config.yaml` 由 OpenSpec CLI 创建并保持未跟踪状态。
+- 工作区存在与本次无关的已删除文件，未处理。
+
+## 流程偏差记录
+
+- 偏差：本次执行中，Phase 2 grill 决策确认后曾直接进入执行文件修改，没有显式停在 Phase 2.9 checkpoint 等待 Phase 3 apply 授权。
+- 分类：实现偏差。v3.1 规格方向正确，但执行过程没有严格遵守“grill 确认 ≠ apply 授权”的门禁。
+- 修正：已回写 OpenSpec，新增 requirement 和 task，要求 Phase 2/2.5 回写后必须停在 Phase 2.9，并等待明确 Phase 3 apply 授权。
+- 当前状态：用户已明确授权“执行apply”，该新增 requirement 已应用到 `.agents/skills/sm-flow/*` 和 workflow 文档。
+
+## 交接
+
+- 下一步：已归档，后续可从 devflow 档案和 OpenSpec archive 回溯。
+- OpenSpec 归档确认：用户已确认归档。
+- OpenSpec 归档位置：`openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/`
+- Specs 同步：未执行；本仓库 `openspec/specs/` 当前无主 spec 文件，本次保留 delta specs 于 archive 中。
@@ -0,0 +1,30 @@
+# SM Flow v3.1 Upgrade Brief
+
+## 背景
+
+- 用户目标：把 `sm-flow` v3 使用中暴露的接口文档、流程顺序、上下文定位、子 skill 兼容和实现期冲突问题固化为 v3.1 协议。
+- 当前问题：v3 已经确立 OpenSpec-first，但缺少接口影响分级、Draft/Committed OpenSpec gate、devflow 索引和 Phase 3 冲突沟通规则。
+- 关联 OpenSpec：`openspec/changes/sm-flow-v3-1-upgrade/`
+- devflow 分档：standard
+
+## 范围
+
+- 本次要做：更新 `sm-flow` skill 本体、phase contracts、fallbacks、templates、workflow 说明，并创建/维护 devflow 索引。
+- 本次不做：修改业务代码、重写 OpenSpec CLI、把 devflow 变成执行真理源、强制所有接口变更都独立产出接口文档。
+- 影响区域：
+  - `.agents/skills/sm-flow/SKILL.md`
+  - `.agents/skills/sm-flow/references/*.md`
+  - `skill-workbench/docs/sm-flow/workflow.md`
+  - `devflow/index.md`
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖
+- specs 覆盖状态：已覆盖
+- tasks 覆盖状态：已覆盖
+
+## OpenSpec 输入上下文摘要
+
+- v3 历史决策：`devflow/` 是上下文真理源，OpenSpec 是执行真理源，代码是实现结果。
+- 用户问题来源：`skill-workbench/docs/sm-flow/使用问题.md`，共 6 个问题，集中在接口产物、流程顺序、上下文检索、子 skill 兼容和实现期冲突。
+- 历史评估来源：`devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md`，已确认子 skill fallback、quick 模式、Phase 退出条件和 OpenSpec-first 是 v3 的关键设计。
@@ -0,0 +1,39 @@
+# 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 接受。
@@ -0,0 +1,28 @@
+# SM Flow v3.1 Upgrade Evidence
+
+## 证据
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| `skill-workbench/docs/sm-flow/使用问题.md` | 用户列出 6 个实践问题，包含接口文档、propose/grill 顺序、devflow 检索、子 skill 兼容、Phase 3 设计冲突。 | v3.1 应围绕这些使用摩擦改协议，而不是重写整个流程。 | 是 |
+| `.agents/skills/sm-flow/SKILL.md` | 当前核心规则已要求 Phase 0.5、Phase 2、Phase 2.5、Phase 3、Phase 4，但没有 Draft/Committed OpenSpec 和接口影响分级。 | 新规则应补 gate，不应推翻 v3 的 OpenSpec-first 主从关系。 | 是 |
+| `.agents/skills/sm-flow/references/phase-contracts.md` | Phase 1 生成 OpenSpec 后进入 Phase 1.5/2/2.5，Phase 3 以 OpenSpec 执行；缺少 Phase 2.9 提交检查。 | “propose 后 grill 返工”应通过草稿/提交分离解释和治理。 | 是 |
+| `.agents/skills/sm-flow/references/fallbacks.md` | 执行 fallback 已要求失败原因不确定时 diagnose，规格不准先修 OpenSpec。 | 可扩展为 Phase 3 实现期冲突分类，不需要新建完全独立流程。 | 是 |
+| `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 Claude 工具耦合、子 skill 调用方式不稳、Phase 退出条件不足。 | v3.1 的兼容规则应绑定能力契约，而不是绑定具体平台路径。 | 是 |
+
+## Evidence-driven 结论
+
+- 结论：v3.1 应保留 v3 主轴，只增加 gate 和分级规则。
+  - 证据：当前 skill 文件和 phase contracts 已经清楚表达 OpenSpec-first。
+  - 风险：如果重写阶段顺序，容易引入新的执行歧义。
+  - 用户确认：已通过“开始这次的 v3.1 改造”确认推进。
+
+- 结论：接口文档应分级，不应一刀切。
+  - 证据：用户同时提出“接口影响范围文档”和“接口文档”，说明需要区分影响记录与独立文档。
+  - 风险：分级阈值不清会导致代理低估外部契约风险。
+  - 用户确认：需要在实现时以不确定则确认为规则。
+
+- 结论：Phase 3 应增加实现期沟通规则，而不是让代码建议直接覆盖 OpenSpec。
+  - 证据：用户明确要求“不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到”。
+  - 风险：沟通 gate 会暂停执行，但能保护规格真理源。
+  - 用户确认：已确认这是 v3.1 重点。