git-learn/openspec/changes/sm-flow-execution-hardening/design.md

Context

这次 change 处理的是 sm-flow 的执行稳定性，而不是流程理念重构。已有文档已经定义了阶段顺序、Phase 2.9、接口影响、实现期冲突分类和 devflow 索引，但真实使用表明，规则如果没有变成“阶段切换前必须显式满足的条件”，就会在执行中被代理惯性绕开。

受影响的主要文件位于：

• .agents/skills/sm-flow/SKILL.md
• .agents/skills/sm-flow/references/phase-contracts.md
• .agents/skills/sm-flow/references/fallbacks.md
• .agents/skills/sm-flow/references/templates.md
• skill-workbench/docs/sm-flow/workflow.md

这次改造的规则落点也需要明确分层：

• SKILL.md 承载短而硬的总规则和 gate。
• phase-contracts.md 承载逐阶段进入、动作、退出和 checkpoint。
• fallbacks.md 承载 capability 不可用时的降级协议与记录要求。
• templates.md 只在确有必要时提供轻量字段提示，不承载主逻辑。
• workflow.md 只解释设计与演进背景，不重复执行细则或承担执行真理源职责。

Design

1. Phase checkpoints as executable gates

为每个关键阶段引入最小 checkpoint，要求代理在阶段结束时显式汇报：

1. 当前阶段名称。
2. 本阶段调用的 skill / 本地 SKILL.md / fallback。
3. 本阶段产物。
4. 已满足的退出条件。
5. 未满足但仍阻塞下一阶段的问题。

这个 checkpoint 不是替代现有 phase-contracts.md，而是把长契约压缩成执行中更容易遵守的门禁动作。 本次设计只要求这些 checkpoint 具备明确字段和动作，不要求新增统一模板或统一展示格式。

2. Skill/fallback declaration becomes a completion condition

现有规则要求进入某些阶段时说明 skill 或 fallback，但执行中容易被忽略。硬化后：

• 若本阶段未显式声明使用的能力来源，则阶段不得视为完成。
• 若发生 fallback，必须同时记录：目标 skill、不可用原因、采用的 fallback 协议、降级风险。

3. Phase 2 uses a question pool

现有规则强调 one-at-a-time，但没有约束问题覆盖面。硬化后，Phase 2 先生成问题池，再逐个消费：

• 问题池至少覆盖术语、边界、验收。
• 对复杂任务，可继续覆盖权限、上下游触发、前端返回结构、兼容性、生命周期等。
• user-interview 问题仍然一次只问一个，但问题池必须先暴露计划覆盖面。

这样既保留 human-in-the-loop 约束，也降低“只问了几个问题就误以为够了”的风险。

4. Cross-artifact alignment becomes explicit

Phase 1.5 和 2.9 需要明确检查的对齐关系：

• brief/prd -> proposal
• proposal -> design
• design -> specs
• specs -> tasks
• evidence/decisions -> OpenSpec 回写状态

如果任何链路出现信息缺失、术语不一致、能力未落到 spec、spec 未落到 task，都必须在进入下一阶段前暴露。

5. Micro mode preserves gates

micro 继续允许合并产物，但明确禁止跳过：

• Phase 0.5 最小上下文检查
• Phase 2 最小澄清
• Phase 2.9 commit gate
• Phase 4 轻量归档

这次 change 不增加 micro 的文档负担，而是把“不能跳哪些 gate”写得更硬。

6. Devflow updates happen during the flow

devflow 不再被视为“最后补文档”。设计上要求：

• Phase 0 写入口摘要到 brief.md
• Phase 2 写 evidence / decisions
• Phase 2.5 写架构审计摘要
• Phase 2.9 写 commit gate 结果
• Phase 4 只做汇总和归档收尾

这样 Phase 4 变成收敛，而不是返工。

7. Rule placement avoids duplication drift

本次 change 的一个隐含架构约束是避免同一规则在多个层面双份维护：

• 如果某条规则属于执行门禁，应优先落在 SKILL.md 或 phase-contracts.md。
• 如果某条规则属于 capability 降级，应优先落在 fallbacks.md。
• workflow.md 可以解释为什么这样设计，但不应再逐条复制执行细则。
• templates.md 保持可选和轻量，否则会把“协议硬化”扩大成“格式标准化”。

这能降低 v3.1 之后再次出现“规则已经写了，但代理仍然执行漂移”的维护风险。

Risks / Trade-offs

• 更强的 checkpoint 会增加少量流程显式成本，但可以换来更低的遗漏率。
• 问题池可能让 Phase 2 看起来更正式，但如果不先暴露覆盖面，one-at-a-time 容易退化成随机追问。
• 更硬的 cross-artifact 检查会让 change 前期更慢，但比在 apply 前后由用户兜底更可靠。
• 如果把同一规则同时写进协议、模板和案例说明，后续维护面会再次变大，因此这轮需要严格控制规则落点。

Validation

需要通过文档与 OpenSpec 产物验证以下结果：

• sm-flow 明确要求阶段 checkpoint。
• micro 明确禁止跳过关键 gate。
• Phase 2 明确先形成问题池，再一次一问推进。
• Phase 1.5 / 2.9 明确 cross-artifact 检查链路。
• devflow 的过程内同步更新要求被写入协议。
• 不要求代理额外输出统一格式的阶段汇报示例。