upgrade sm-flow v3.1 workflow

skill-workbench/generated-skills/sm-flow/references/phase-contracts.md

@@ -28,6 +28,8 @@
 **进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
 
 **动作**：
+- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
+- 如果 `devflow/index.md` 不存在，先从 `devflow/projects/` 现有目录初始化轻量索引，再继续本次上下文收集。
 - 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
 - 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
 - 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
@@ -36,6 +38,7 @@
 
 **退出条件**：
 - 已形成“OpenSpec 输入上下文摘要”。
+- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
 - 已列出相关 ADR 和不能违反的历史决策。
 - 已列出需要写入或修正 OpenSpec 的上下文点。
 
@@ -46,7 +49,7 @@
 
 **进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
 
-**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
+**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 `openspec-propose` 的 `SKILL.md` / fallback 降级。
 
 **动作**：
 - 优先调用 `openspec-propose`。
@@ -64,7 +67,7 @@
 - 关键假设已显式记录在 OpenSpec 或 research 中。
 
 **输出**：
-- OpenSpec proposal、design、specs 和 task list。
+- Draft OpenSpec proposal、design、specs 和 task list。
 
 **Human checkpoint**：
 - 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
@@ -85,11 +88,16 @@
   - OpenSpec 是否遵守相关 ADR。
   - specs 是否能表达可观察行为。
   - tasks 是否能驱动实现，而不是泛泛描述。
+- 检查是否涉及接口影响：
+  - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
+  - 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
+  - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 `user-interview` 问题。
 - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
 
 **退出条件**：
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - OpenSpec 与 PRD/devflow 上下文没有已知冲突。
+- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
 - 所有已知冲突已修正或等待用户决策。
 
 **输出**：
@@ -110,6 +118,10 @@
   - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
 - 至少覆盖三个维度：术语、边界、验收。
 - 一次只问一个 `user-interview` 问题。
+- 每个 `user-interview` 问题必须等待用户显式回答，并把回答、决策和 OpenSpec 回写状态记录到 `decisions.md`；不能由代理代替用户确认。
+- 未获得用户确认的 `user-interview` 问题必须保持未解决状态，不能进入 Phase 2.9 或 Phase 3。
+- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 Phase 3 或修改执行目标文件的授权。
+- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
 - 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
 - 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
 - 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
@@ -118,6 +130,8 @@
 - 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
+- 没有未解决或代理代确认的 user-interview 问题。
+- 没有未判级或未确认的接口影响问题。
 - 影响实现的结论已回写 OpenSpec。
 
 **输出**：
@@ -148,14 +162,46 @@
 
 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
-- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
+- 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。
+
+## Phase 2.9 — Commit OpenSpec
+
+**进入条件**：
+- Phase 2 已解决术语、边界、验收三个维度的高价值问题。
+- 所有 `user-interview` 问题都已获得用户显式确认。
+- Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因。
+- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
+
+**动作**：
+- 检查 proposal 是否说明为什么做、做什么、范围和非目标。
+- 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
+- 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
+- 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
+- 检查接口影响是否已按 L1/L2/L3/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
+- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
+- 如果检查失败，返回 Phase 1、Phase 2 或 Phase 2.5 修正 Draft OpenSpec。
+
+**退出条件**：
+- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
+- Phase 3 所需的 proposal、design、specs 和 tasks 均存在且一致。
+- 所有 Phase 3 preflight 风险已消除或明确记录为已接受。
+
+**输出**：
+- Committed OpenSpec 状态说明。
+- Phase 3 preflight 检查结果，默认写入 `decisions.md` 或 `acceptance.md`。
+
+**Human checkpoint**：
+- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
+- 询问是否进入 Phase 3 OpenSpec apply；除非用户在启动时明确要求“全自动执行”，必须等待用户明确说出进入 apply、开始实现、执行修改、继续 Phase 3 或等价授权。
+- 不得把 Phase 2 的单个 grill 决策确认当作本 checkpoint 的授权。
 
 ## Phase 3 — OpenSpec apply
 
 **进入条件**：
-- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
-- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
+- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已通过 Phase 2.9，成为 Committed OpenSpec。
+- Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。
 - devflow 与 OpenSpec 没有未解决冲突。
+- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
 
 **显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
 
@@ -163,6 +209,12 @@
 - 优先调用 `openspec-apply-change`。
 - 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
 - 按 OpenSpec tasks 的纵向切片实现。
+- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续：
+  - 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。
+  - 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。
+  - 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。
+  - 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。
+- 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
 - 当用户要求、行为复杂或回归风险高时使用 TDD。
 - 当测试失败、行为意外或原因不确定时使用 diagnose。
 - 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
@@ -170,6 +222,7 @@
 
 **退出条件**：
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
+- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。
 
@@ -188,10 +241,12 @@
 - 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
 - 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
 - 如果本次流程产生可复用经验，写入 compound knowledge。
+- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。
 
 **退出条件**：
 - `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
+- `devflow/index.md` 已包含或更新本项目条目。
 - 用户已被询问是否 archive OpenSpec change。
 
 **输出**：