git-learn/.agents/skills/sm-flow/references/phase-contracts.md

阶段契约

本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow。

Phase 0 — 入口澄清

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

动作：

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

退出条件：

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

输出：

• 入口摘要。
• 初步 slug。
• devflow 规模分档：micro / standard / complex。

Phase 0.5 — Devflow 上下文收集

进入条件：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。
• 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。
• 如果发现旧根目录 CONTEXT.md 与 devflow/glossary/CONTEXT.md 冲突，暂停并向用户汇报。

退出条件：

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

输出：

• 上下文摘要，默认写入 brief.md 或 evidence.md；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。

Phase 1 — OpenSpec propose

进入条件：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。

显式子 skill：openspec-propose。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 openspec-propose 的 SKILL.md / fallback 降级。

动作：

• 优先调用 openspec-propose。
• 如果不可用，执行 references/fallbacks.md#openspec-提案-fallback，但仍必须产出 OpenSpec 文件。
• 用 Phase 0.5 的 devflow 上下文增强 OpenSpec：
  • proposal 写清为什么做、做什么、范围和非目标。
  • design 写入上下文约束、历史 ADR、关键技术决策。
  • specs 写成可验收的外部行为。
  • tasks 写成可执行的纵向切片。
• 在承诺设计细节前，先检查相关仓库代码。

退出条件：

• openspec/changes/<slug>/proposal.md 存在。
• 对需要正式 OpenSpec 产物的变更，design.md、tasks.md 和 specs 存在。
• 关键假设已显式记录在 OpenSpec 或 research 中。

输出：

• Draft OpenSpec proposal、design、specs 和 task list。

Human checkpoint：

• 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
• 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。

Phase 1.5 — PRD / OpenSpec 对齐

进入条件：Phase 1 已有 OpenSpec 产物。

显式子 skill：to-prd + sm-flow。进入本阶段必须先声明是否读取 .agents/skills/to-prd/SKILL.md；如果使用内置模板，标记为 PRD fallback。

动作：

• 如果没有结构化 PRD，则优先按 to-prd 协议生成 brief.md；复杂需求、对外协作或用户明确要求时再生成 prd.md。
• micro 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 brief.md。
• 显式检查 brief/prd -> proposal -> design -> specs -> tasks 的 cross-artifact 对齐关系：
  • brief/prd 中的目标、范围、非目标和验收预期是否进入 proposal。
  • proposal 中的范围、约束和关键承诺是否进入 design。
  • design 中影响实现的约束、接口影响和架构结论是否进入 specs 或 tasks。
  • specs 中的可观察行为是否被 tasks 覆盖为可执行切片。
• 检查 PRD、devflow 上下文和 OpenSpec 是否一致：
  • OpenSpec 是否覆盖 PRD 的用户故事和验收预期。
  • OpenSpec 是否使用 glossary 中的正确术语。
  • OpenSpec 是否遵守相关 ADR。
  • specs 是否能表达可观察行为。
  • tasks 是否能驱动实现，而不是泛泛描述。
• 检查是否涉及接口影响：
  • 接口影响分级定义见 references/operating-rules.md#接口影响分级。
  • 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
  • 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
  • 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 user-interview 问题。
• 如果某个行为、术语、字段、约束或实现切片只出现在上游产物，必须显式标记 gap，并在进入下一阶段前修复 OpenSpec。
• 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。

退出条件：

• brief.md 已覆盖背景、目标、范围和非目标；复杂需求存在独立 prd.md 或用户明确不需要 PRD。
• OpenSpec 与 PRD/devflow 上下文没有已知冲突。
• brief/prd -> proposal -> design -> specs -> tasks 的下游链路没有未处理 gap。
• 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
• 所有已知冲突已修正或等待用户决策。

输出：

• brief.md，以及按需创建的 prd.md。
• OpenSpec 对齐检查记录。
• 必要的 OpenSpec 修正。

Phase 2 — Human-in-the-loop 澄清

进入条件：已有 OpenSpec 产物和 PRD/上下文对齐记录。

显式子 skill：grill-with-docs。进入本阶段必须先声明是否读取 .agents/skills/grill-with-docs/SKILL.md；fallback 必须标记为“文档化追问 fallback”。

动作：

• 优先使用 grill-with-docs。
• 进入 Phase 2 时先建立一个 question pool，并记录到 decisions.md 或 evidence.md：
  • 默认至少覆盖术语、边界、验收三个维度。
  • 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。
• 先声明本阶段采用的澄清模式，并逐项标记：
  • evidence-driven：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
  • user-interview：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
• 至少覆盖三个维度：术语、边界、验收。
• 从问题池中选择下一个未解决问题推进；可以并行整理 evidence-driven 证据，但 user-interview 仍然必须 one-at-a-time。
• 一次只问一个 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。

退出条件：

• question pool 已建立并覆盖当前 change 所需维度。
• 至少解决三个高价值澄清或验证问题，并记录每个问题属于 evidence-driven 还是 user-interview。
• 所有 evidence-driven 结论已向用户汇报。
• 所有 user-interview 决策已获得用户确认。
• 没有未解决或代理代确认的 user-interview 问题。
• 没有未判级或未确认的接口影响问题。
• 影响实现的结论已回写 OpenSpec。

输出：

• 澄清记录：默认写入 decisions.md；问题很多时可拆出 clarifications.md。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。
• 更新后的 OpenSpec。
• 更新后的词汇表和 ADR。

Phase 2.5 — 架构审计

进入条件：Phase 2 已解决主要产品、领域和验收问题。

显式子 skill：zoom-out。进入本阶段必须先声明是否读取 .agents/skills/zoom-out/SKILL.md；fallback 必须标记为“架构审计 fallback”。

动作：

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

退出条件：

• 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。
• OpenSpec design/tasks 已反映会影响实现的架构审计结论。

输出：

• 架构审计记录，默认写入 decisions.md 或 evidence.md；复杂架构审计可拆出 design.md。
• 必要的 OpenSpec design/tasks 修正。

Human checkpoint：

• 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
• 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。

Phase 2.9 — Commit OpenSpec

进入条件：

• Phase 2 已解决术语、边界、验收三个维度的高价值问题。
• 所有 user-interview 问题都已获得用户显式确认。
• Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因；快速模式定义见 references/operating-rules.md#快速模式。
• Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。

动作：

• 检查 proposal 是否说明为什么做、做什么、范围和非目标。
• 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
• 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
• 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
• 复核 brief/prd -> proposal -> design -> specs -> tasks 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。
• 检查 evidence.md 和 decisions.md 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。
• 接口影响分级定义见 references/operating-rules.md#接口影响分级。
• 检查接口影响是否已按 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.9，成为 Committed OpenSpec。
• Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。
• devflow 与 OpenSpec 没有未解决冲突。
• 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。

显式子 skill：openspec-apply-change；遇到 bug/不确定行为时显式调用 diagnose；需要测试驱动时显式调用 tdd。进入本阶段必须先声明调用方式，不能静默 fallback。

动作：

• 优先调用 openspec-apply-change。
• 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
• 按 OpenSpec tasks 的纵向切片实现。
• 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 Phase 3 不算真正开始。
• 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续：
  • 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。
  • 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。
  • 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。
  • 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。
• 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 decisions.md 或 acceptance.md。
• 当用户要求、行为复杂或回归风险高时使用 TDD。
• 当测试失败、行为意外或原因不确定时使用 diagnose。
• 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
• 修改文件前遵守仓库指令，例如 AGENTS.md。

退出条件：

• OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
• 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
• 已运行验证，或记录了未验证原因。
• 已列出已知限制。

输出：

• 代码变更、必要测试和实现说明。
• 更新后的 OpenSpec task 状态。

Phase 4 — 回填 Devflow

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

显式子 skill：openspec-archive-change 只在用户确认 archive 后调用；Phase 4 回填由 sm-flow 执行。必须记录 archive 是真实调用还是手动 fallback。

动作：

• 遵循 references/archive-rules.md。
• 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
• 把 Phase 0 到 Phase 3 已经形成的过程内记录整理为最终档案；不要把 Phase 4 当作第一次补写这些记录。
• 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
• 如果本次流程产生可复用经验，写入 compound knowledge。
• 更新 devflow/index.md，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
• 询问用户是否要 archive OpenSpec change；不要默认执行归档。

退出条件：

• devflow/projects/YYYY-MM-DD-{slug}/ 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
• devflow/index.md 已包含或更新本项目条目。
• 用户已被询问是否 archive OpenSpec change。

输出：

• 默认输出 brief.md、evidence.md、decisions.md、acceptance.md；按需输出 prd.md、research.md、design.md、tasks.md、alignment.md、ADR 和 compound knowledge。