4.0 KiB
4.0 KiB
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 补写。
用户故事
- 作为使用
sm-flow的开发者，我希望代理在进入下一阶段前自动暴露“已满足/未满足”的条件，这样我能尽早发现流程偏差。 - 作为使用
sm-flow的开发者，我希望micro模式仍然保留关键 gate，这样小改动不会因为“看起来简单”而漏掉重要检查。 - 作为使用
sm-flow的开发者，我希望 Phase 2 先形成问题池，再逐个提问，这样既符合 human-in-the-loop 约束，也能避免只问了少数问题就错误收尾。 - 作为使用
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。