# 阶段契约

本文件是 SM Flow 的逐阶段执行准则。核心原则：**sm-flow 编排 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。

执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive。

## 目录

- clarify — 入口澄清
- context — 上下文收集
- propose — 轻量 propose
- grill — 人类对齐澄清
- specify — 细化 + 对齐
- audit — 架构审计
- commit — Commit OpenSpec
- apply — OpenSpec 执行
- archive — 回填 + 归档

## clarify — 入口澄清

**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。

**动作**：
- 收集问题、期望结果、目标用户、涉及代码区域、约束条件和可能的非目标。
- 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
- 如果输入过于模糊，最多追加三轮聚焦问题。
- 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
- 如果需要判断 `micro / standard / complex` 分档，补读 `references/scales.md`。

**退出条件**：
- 问题可以用 1-2 句话说清楚。
- 期望结果可以用 1-2 句话说清楚。
- 已列出已知影响代码或模块；如果未知，也明确标记。
- 可以生成 OpenSpec change slug。

**输出**：
- 入口摘要。
- 初步 slug。
- devflow 规模分档：`micro` / `standard` / `complex`。

## context — 上下文收集

**进入条件**：clarify 已经有足够信息定位领域、项目或变更方向。

**动作**：
- 优先读取 `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。
- 记录哪些上下文会影响 OpenSpec proposal、设计产物、specs 或 tasks。
- 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。

**退出条件**：
- 已形成"OpenSpec 输入上下文摘要"。
- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
- 已列出相关 ADR 和不能违反的历史决策。
- 已列出需要写入或修正 OpenSpec 的上下文点。

**输出**：
- 上下文摘要，写入 `decisions.md`（过程日志）。会影响实现的上下文必须标记为"需进入 OpenSpec"。

## propose — 轻量 propose

**进入条件**：clarify + context 已经足够生成轻量 proposal。

**执行者**：sm-flow 内置协议。**不调用 openspec-propose**（完整 OpenSpec 产物留待 specify 阶段生成）。

**动作**：
- 创建或识别 `openspec/changes/{slug}/`。
- 写入 `proposal.md`，包含：问题、建议方案、范围、非目标、来自 devflow 的上下文约束、风险。
- **不生成 design.md、specs/、tasks.md**——这些留待 grill 澄清需求后在 specify 阶段补全。
- 用 context 阶段的 devflow 上下文增强 proposal。
- 在承诺方案方向前，先检查相关仓库代码。

**退出条件**：
- `openspec/changes/{slug}/proposal.md` 存在。
- 关键假设已显式记录。

**输出**：
- Draft OpenSpec proposal.md（轻量版）。

**Human checkpoint**：
- 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。
- 作为 Discover checkpoint 的中间状态汇报；询问是否继续完成 Discover 的人类澄清部分。用户明确要求"全自动执行"时可跳过等待。

## grill — 人类对齐澄清

**进入条件**：propose 已有轻量 proposal.md。

**能力来源**：优先使用 `grill-with-docs`；不可用时使用 `references/fallbacks.md#grill-内置协议`，并在 `decisions.md` 标注 fallback。

**动作**：
- 优先使用 `grill-with-docs`。
- 进入 grill 时先建立一个 question pool，并记录到 `decisions.md`：
  - 默认至少覆盖术语、边界、验收三个维度。
  - **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
    - 参考实现的具体文件路径是什么？
    - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
    - 有哪些技术点需要先调研或新建？
  - 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。
- 逐项标记每个问题的模式：
  - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
  - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
- evidence-driven 和 user-interview 的推进节奏：先批量查证 evidence-driven 并一次性汇报结论，再逐个处理 user-interview 问题。不要把所有问题攒到最后一起问。
- 一次只问一个 `user-interview` 问题。
- 每个 `user-interview` 问题必须等待用户显式回答，并在 decisions.md 中记录：问题原文、用户原话、确认状态（已确认/未确认）。未确认的问题不能从 question pool 移除。
- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 apply 或修改执行目标文件的授权。
- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
- 如果澄清结果影响实现，必须回写 proposal.md。
- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。

**退出条件**：
- question pool 已建立并覆盖当前 change 所需维度。
- 已满足 `references/scales.md` 中当前分档的 grill 要求。每个问题都必须记录属于 `evidence-driven` 还是 `user-interview`。
- 所有 evidence-driven 结论已向用户汇报。
- 所有 user-interview 决策已获得用户确认。
- 没有未解决或代理代确认的 user-interview 问题。
- 没有未判级或未确认的接口影响问题。
- 影响实现的结论已回写 proposal.md。
- 单个 grill 决策确认不等于 apply 授权；grill 完成后必须停在 commit，等待用户明确要求进入 apply。
- question pool、evidence-driven 结论、user-interview 确认必须写入 `decisions.md` 文件，不能只记录在对话中。

**输出**：
- 更新后的 proposal.md。
- 澄清记录：写入 `decisions.md`。包含 question pool、evidence-driven 汇报状态、user-interview 确认状态。
- 更新后的词汇表和 ADR。

**Human checkpoint**：
- 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。
- 汇报 Discover checkpoint 完成情况，并询问是否继续进入 Commit checkpoint。

## specify — 细化 + 对齐

**进入条件**：grill 已退出，需求已通过澄清稳定下来。

**能力来源**：优先使用 `openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；按需使用 `to-prd`。进入本阶段必须先声明调用方式；外部能力不可用时使用 `references/fallbacks.md#openspec-提案-内置协议`，并在 `decisions.md` 标注 fallback。

**动作**：
- 基于已稳定的 proposal.md 补全设计产物、specs/、tasks.md：
  - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需按当前分档补全设计产物/specs/tasks"。
  - 如果不可用，执行 `references/fallbacks.md#openspec-提案-内置协议`。
- 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
- 独立 PRD 是否需要按 `references/scales.md` 的当前分档和用户要求判断。
- 用 grill 阶段的 decisions.md 记录增强 OpenSpec 产物：确保 design/specs/tasks 反映所有已确认的决策。
- **显式 cross-artifact 对齐检查**——在 checkpoint 中输出对齐检查表：
  - `brief/prd` 中的目标、范围、非目标和验收预期 → `proposal` 是否覆盖。
  - `proposal` 中的范围、约束和关键承诺 → `design` 是否覆盖。
  - `design` 中影响实现的约束、接口影响和架构结论 → `specs` 或 `tasks` 是否覆盖。
  - `specs` 中的可观察行为 → `tasks` 是否覆盖为可执行切片。
  - 每项标记：已对齐 / 存在 gap。
- 检查是否涉及接口影响：
  - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
  - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
  - 接口内部判断逻辑是否改变调用方可观察行为。
  - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 `user-interview` 问题。
- 如果存在 gap，在进入下一阶段前修复 OpenSpec。
- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。

**退出条件**：
- OpenSpec 细化产物存在且与 proposal 对齐；产物形态按 `references/scales.md` 的当前分档要求执行。
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
- cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。
- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。
- 所有已知冲突已修正或等待用户决策。

**输出**：
- Draft OpenSpec：按 `references/scales.md` 的当前分档要求生成 proposal、设计、specs 和 tasks。
- `brief.md`，以及按需创建的 `prd.md`。
- cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。
- 必要的 OpenSpec 修正。

## audit — 架构审计

**进入条件**：specify 已退出，完整 OpenSpec 产物已存在。

**能力来源**：优先使用 `zoom-out`；不可用时使用 `references/fallbacks.md#audit-内置协议`，并在 `decisions.md` 标注 fallback。

**动作**：
- 画出输入 → 处理 → 输出的模块链路。
- 识别跨模块依赖、数据所有权、生命周期和耦合风险。
- 检查是否与既有架构、ADR、OpenSpec design 冲突。
- 用不超过五句话写出架构风险评估。
- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
- 审计结论写入 `decisions.md`。

**退出条件**：
- 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。
- OpenSpec 设计产物/tasks 已反映会影响实现的架构审计结论。

**输出**：
- 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。
- 必要的 OpenSpec 设计产物/tasks 修正。

**Human checkpoint**：
- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
- 作为 Commit checkpoint 的中间状态汇报；询问是否继续完成 commit gate。

## commit — Commit OpenSpec

**进入条件**：
- grill 已满足 `references/scales.md` 中当前分档要求。
- 所有 `user-interview` 问题都已获得用户显式确认。
- audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。
- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。

**动作**：
- 检查 proposal 是否说明为什么做、做什么、范围和非目标。
- 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
- 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
- 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
- 复核 cross-artifact 对齐：`brief/prd → proposal → 设计产物 → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。
- 检查 `decisions.md` 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。
- 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
- 检查接口影响是否已按 L1/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
- 如果检查失败，返回 propose、grill、specify 或 audit 修正 Draft OpenSpec。

**退出条件**：
- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
- **文件完整性检查**（按 `references/scales.md` 的当前分档要求执行）：
  - [ ] proposal 存在，且足以说明问题、建议方案、范围和非目标。
  - [ ] 设计产物存在，形式符合当前分档要求。
  - [ ] specs 存在，且表达用户可观察行为。
  - [ ] tasks 存在，且任务可执行、验收标准可验证。
- **一致性检查**（必须通过）：
  - [ ] proposal 中的核心概念在设计产物中有对应设计
  - [ ] 设计产物中的关键决策在 tasks 中有对应实现任务
  - [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
- **标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
- 所有 preflight 风险已消除或明确记录为已接受。

**输出**：
- Committed OpenSpec 状态说明。
- preflight 检查结果，写入 `decisions.md` 或 `acceptance.md`。

**Human checkpoint**：
- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
- 汇报 Commit checkpoint 完成情况，并询问是否进入 Apply checkpoint；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
- 不得把 grill 的单个决策确认当作本 checkpoint 的授权。

## apply — OpenSpec 执行

**进入条件**：
- `openspec/changes/{slug}/` 中 proposal、设计产物、specs、tasks 已通过 commit，成为 Committed OpenSpec。
- **前置门控检查**（硬约束）：
  - 检查 `openspec/changes/{slug}/.committed` 文件是否存在
  - 如不存在，执行以下流程：
    1. 汇报：Draft OpenSpec 未通过 commit 检查
    2. 列出缺失的 checkpoint 项（文件完整性、一致性检查）
    3. 询问用户：是否补做 commit 检查；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`，且本次流程不得视为合规 sm-flow apply
- commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。
- devflow 与 OpenSpec 没有未解决冲突。
- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。

**能力来源**：优先使用 `openspec-apply-change`；不可用时使用 `references/fallbacks.md#openspec-apply-内置协议`，并在 `decisions.md` 标注 fallback。遇到 bug/不确定行为时优先使用 `diagnose`；需要测试驱动时优先使用 `tdd`。不可用时执行对应最小协议并记录原因，不得静默跳过。

**动作**：

### Pre-apply Checkpoint

**触发条件**：当 OpenSpec 涉及以下任一情况时必须执行
- design 或 tasks 中提到"参考 XXX 实现"
- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
- 技术栈不熟悉或第一次在该项目实现类似功能

**执行步骤**：
1. **阅读所有参考实现**
   - 从 OpenSpec design 或 tasks 中定位参考实现文件
   - 如果路径不明确，通过 Grep 搜索关键类名或模式
   - 理解关键逻辑，提取可复用代码片段和模式

2. **Grep 关键技术栈**
   - 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范）
   - 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板）
   - 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具）
   - 异常处理和日志记录标准

3. **形成技术栈清单并写入 decisions.md**
   - 项目使用的请求/响应结构标准
   - MQ 消息定义和发送标准
   - Consumer 标准位置和写法
   - 加密/验签/工具类的标准用法
   - 识别需要新建的工具类或基础设施

**输出要求**：
- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节。
- 已列出所有参考实现的文件路径。
- 已识别需要新建的工具类/基础设施。

**按风险执行**：执行深度按 `references/scales.md` 的当前分档和实现风险决定；退出判断以清单是否足以指导实现为准。

### 实现过程

- 优先调用 `openspec-apply-change`。
- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
- 按 OpenSpec tasks 的纵向切片实现。
- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
- 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 apply 不算真正开始。
- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，做三类判断：
  - OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停 apply，修正 OpenSpec 后重新提交。
  - 代码偏离（实现没按 OpenSpec 做）→ 修正代码，不改 OpenSpec。
  - 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。
- 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。
- **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
- 当用户要求、行为复杂或回归风险高时使用 TDD。
- 当测试失败、行为意外或原因不确定时使用 diagnose。
- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
- 修改文件前遵守仓库指令，例如 `AGENTS.md`。

**退出条件**：
- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`。
- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位。
- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
- 已运行验证，或记录了未验证原因。
- 已列出已知限制。

**输出**：
- 代码变更、必要测试和实现说明。
- 更新后的 OpenSpec task 状态。
- 冲突记录写入 `decisions.md`。

## archive — 回填 + 归档

**进入条件**：实现或规划工作已经达到可交接状态。

**能力来源**：`openspec-archive-change` 在用户确认 archive 后优先调用；不可用时使用 `references/fallbacks.md#openspec-archive-内置协议`，并在 `acceptance.md` 标注 fallback。archive 回填由 `sm-flow` 执行。

**动作**：
- 遵循 `references/archive-rules.md`。
- 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案：
  - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
  - `evidence.md`：按 `references/scales.md` 和 `references/archive-rules.md` 的当前分档要求处理。
  - `decisions.md`：保持为最终版，整理格式。
  - `acceptance.md`：从实现结果和验证结果提取。
- 只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
- 如果本次流程产生可复用经验，写入 compound knowledge。
- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
- 询问用户是否要 archive OpenSpec change；不要默认执行归档。

**退出条件**：
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
- `devflow/index.md` 已包含或更新本项目条目。
- 用户已被询问是否 archive OpenSpec change。

**输出**：
- 完整 devflow 档案。
- 归档交接清单：创建或更新了哪些文件、验证分类、剩余风险、是否 archive。