# SM Flow Execution Hardening PRD ## 问题陈述 `sm-flow` 已经定义了较完整的阶段、规则和 reference 文件，但在真实项目执行中，代理仍然会把它当成“有帮助的流程建议”，而不是“必须逐阶段满足的执行协议”。结果是： - Phase 0 没有形成入口摘要和已知影响区域。 - Phase 0.5 没有及时初始化和维护 `devflow/` 项目档案。 - Phase 1 没有显式声明 skill 或 fallback，Draft / Committed OpenSpec 的边界不稳定。 - Phase 1.5 被跳过，导致 proposal / design / research / specs / tasks 之间的一致性缺口直到用户 review 才暴露。 - Phase 2 虽然收集了证据，但没有以结构化问题池和 one-at-a-time 的方式稳定执行。 - Phase 2.5 被跳过，架构链路和接口影响没有提前暴露。 - Phase 2.9 缺少强制自检，无法可靠发现 cross-artifact 遗漏。 这说明当前痛点不是缺少理念，而是缺少“执行时自检”和“阶段切换门禁”的产品化机制。 ## 解决方案 为 `sm-flow` 增加一轮“执行硬化”需求，目标是让代理在实际使用中更难偏离阶段协议。重点不是新增更多解释，而是把现有规则压缩成更可执行、更可检查、更可暴露偏差的约束，例如： - 每个阶段结束必须有简短 checklist / checkpoint。 - 未显式声明 skill 或 fallback 视为该阶段未完成。 - Phase 2 先生成问题池，再按 one-at-a-time 消费。 - Phase 1.5 / 2.9 引入更明确的 cross-artifact diff 检查。 - `micro` 明确只能压缩产物，不得跳过关键 gate。 - devflow 产物默认在过程内同步更新，而不是拖到 Phase 4 补写。 ## 用户故事 1. 作为使用 `sm-flow` 的开发者，我希望代理在进入下一阶段前自动暴露“已满足/未满足”的条件，这样我能尽早发现流程偏差。 2. 作为使用 `sm-flow` 的开发者，我希望 `micro` 模式仍然保留关键 gate，这样小改动不会因为“看起来简单”而漏掉重要检查。 3. 作为使用 `sm-flow` 的开发者，我希望 Phase 2 先形成问题池，再逐个提问，这样既符合 human-in-the-loop 约束，也能避免只问了少数问题就错误收尾。 4. 作为使用 `sm-flow` 的开发者，我希望 Phase 1.5 和 2.9 能可靠检查 proposal / design / specs / tasks / evidence / decisions 的一致性，这样问题能在 apply 前暴露，而不是等我 review。 ## 实现决策 - 决策：本轮先把“执行硬化”提炼成需求，而不是直接进入文档改造。 - 原因：当前已掌握足够多的真实使用反馈，需要先明确问题边界和验收标准，再决定是否开新 OpenSpec change。 - 影响：下一步可以更顺畅地进入 `sm-flow` 的正式改造，而不是边讨论边补规则。 - 决策：把重点放在 phase gate、自检、问题池和一致性检查，而不是继续扩展 `sm-flow` 的理念层说明。 - 原因：复盘显示失真主要来自执行习惯和缺少检查，而不是原则方向错误。 - 影响：后续改动应优先落在 `SKILL.md`、`phase-contracts.md` 和模板/检查清单，而不是重写 workflow 长文。 ## 测试决策 - 好测试应该通过审查 `sm-flow` 协议文本和执行产物，验证代理是否被强制带到正确的阶段检查点。 - 必须覆盖： - `micro` 模式下 gate 不可跳过 - Phase 2 问题池与 one-at-a-time 提问 - skill/fallback 显式声明要求 - Phase 1.5 / 2.9 cross-artifact 检查 - devflow 过程内同步更新 - 不测试： - 业务代码实现结果 - OpenSpec CLI 本身的功能正确性 ## 非目标 - 不在本轮定义新的业务流程。 - 不在本轮替换 OpenSpec-first / Devflow-assisted 主设计。 - 不要求为所有小改动增加更重的文档负担。 ## 补充说明 - 这轮需求直接来源于一次真实项目执行复盘，因此它比理念讨论更贴近代理实际失真模式。 - 如果后续进入 OpenSpec，建议 change 名可沿用 `sm-flow-execution-hardening`。