harden and streamline sm-flow protocol

2026-05-25 11:44:20 +08:00
parent 54741dd6c0
commit 1f01e30c4e
20 changed files with 1102 additions and 88 deletions
@@ -412,8 +412,56 @@ Phase 2 的 `grill-with-docs` 不是代理自问自答。`user-interview` 问题

 `evidence-driven` 问题可以由代理先查证，但也必须汇报证据、结论和是否需要用户确认。

+Phase 2 在开始追问前，还应该先建立一个 question pool。最小问题池至少覆盖：
+
+- 术语
+- 范围边界
+- 验收口径
+
+如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，再把这些维度补进问题池。问题池的作用是先把风险面列全，再继续保持 one-at-a-time 的 `user-interview` 消费节奏，而不是一次把所有问题都抛给用户。
+
 单个 grill 决策确认不等于 Phase 3 apply 授权。用户在 Phase 2 回答“可以”只表示该问题已确认；代理必须先回写 OpenSpec/devflow，停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply、开始实现、执行修改或继续 Phase 3。

+### Phase Checkpoint
+
+v3.1 的另一个收紧点是：关键阶段不再靠“看起来做完了”判断完成，而是靠显式 checkpoint。
+
+关键阶段至少包括：
+
+- Phase 0
+- Phase 0.5
+- Phase 1
+- Phase 2
+- Phase 2.5
+- Phase 2.9
+
+每个 checkpoint 至少说明：
+
+- 当前阶段
+- 调用的 capability 来源
+- 产出的关键 artifact
+- 已满足的退出条件
+- 尚未解决的 blocker
+
+如果没有这些信息，就不应该把阶段视为已完成，更不应该直接进入下一阶段。
+
+### Cross-Artifact Alignment
+
+v3.1 之后，Phase 1.5 和 Phase 2.9 不只是“看看文档差不多”，而是要显式检查一条对齐链：
+
+```text
+brief/prd -> proposal -> design -> specs -> tasks
+```
+
+检查重点不是格式，而是下游产物有没有把上游已经确定的内容接住，例如：
+
+- `brief/prd` 里的范围和非目标有没有进入 `proposal`
+- `proposal` 的关键承诺有没有进入 `design`
+- `design` 里的实现约束和接口影响有没有进入 `specs` 或 `tasks`
+- `specs` 里的可观察行为有没有被 `tasks` 切成可执行工作
+
+如果字段、术语、约束、行为或切片只停留在上游文档里，就应该视为对齐缺口，先修 OpenSpec，再继续流程。
+
 ### 接口影响分级

 v3.1 区分“接口影响记录”和“独立接口文档”：
@@ -445,6 +493,21 @@ devflow/compound/

 Phase 4 回填项目档案时必须更新 `devflow/index.md`。最小字段为日期、slug、领域、关键词、关联 OpenSpec 和状态。

+另外，v3.1 也把一个实践经验写成硬规则：devflow 不是等到 Phase 4 才第一次补写。`brief.md`、`evidence.md`、`decisions.md` 这类过程内档案应该随阶段就近更新，Phase 4 主要负责 consolidation 和归档口径收束。
+
+### Micro 不是 Skip
+
+`micro` 的目标是降低文档重量，不是给代理发放“可以跳 gate”的许可证。
+
+因此即使是 `micro` 变更，也仍然要保留：
+
+- Phase 0.5 最小上下文收集
+- Phase 2 最小澄清
+- Phase 2.9 commit gate
+- Phase 4 轻量回填
+
+如果因为“改动很小”就跳过这些 gate，应该视为协议偏差，而不是合法优化。
+
 ### 实现期冲突处理

 Phase 3 中，如果用户质疑、用户修改、代码发现、测试失败或运行行为与 Committed OpenSpec 冲突，必须先分类：
@@ -470,6 +533,58 @@ v3.1 将子 skill 从“路径绑定”改为“能力绑定”。例如 `opensp

 这样 `sm-flow` 可以在 Claude、Codex 或其他代理环境中迁移，而不会被某个固定目录锁死。

+一旦进入 fallback，代理还必须把这次降级本身记录下来。也就是说，fallback 不只是“内部换个做法”，而是一个需要显式声明 capability 缺失、降级原因和风险的协议事件。
+
+## v3.1 后续收口：协议瘦身与 review 修正
+
+在执行硬化规则落地后，又做了一轮非常实际的收口：不是再增加新规则，而是把已经确认的规则放到更稳定、可维护的位置，并修掉瘦身过程中暴露的引用问题。
+
+### 顶层 skill 瘦身
+
+`SKILL.md` 不再同时承担“入口协议”和“大段运行手册”两种职责，而是收敛为：
+
+- 工作流定位
+- 真理源分层
+- 核心硬规则
+- reference 加载入口
+- 阶段总览
+
+原来放在顶层但更适合按需读取的内容，被下沉到新的：
+
+```text
+references/operating-rules.md
+```
+
+这里集中放：
+
+- 接口影响分级
+- 启动检查
+- 项目标识规则
+- devflow 产物分层
+- 快速模式细则
+- 完成标准
+
+这样做的目标不是减少规则，而是减少“启动时一次读太多”和“顶层协议与 reference 抢职责”的问题。
+
+### Fallback 去重复
+
+`fallbacks.md` 也做了第二轮整理：
+
+- 顶部统一定义 fallback 通用记录要求
+- 各 fallback 小节只保留自己的额外记录义务
+
+这样可以避免每个 fallback 都重复写一遍“要声明 fallback、要记录 fallback”，同时不丢失协议要求。
+
+### Review 驱动的自洽性修正
+
+瘦身后又发现了一类很典型的问题：**规则本身没错，但 cross-reference 可能断掉**。因此又补了一轮 review 驱动修正，重点包括：
+
+- `phase-contracts.md` 在首次使用接口分级、分档、快速模式时，显式指向 `operating-rules.md`
+- 修正 fallback 锚点，避免 skill 指向不存在的章节名
+- 统一 `operating-rules.md` 的语言风格，避免在主协议是中文时夹着一整份英文运行规则
+
+这轮修正说明一件事：协议产品化不只是“把规则写出来”，还要保证**入口、逐阶段契约、fallback 和运行规则之间的导航关系始终自洽**。
+