harden and streamline sm-flow protocol

.agents/skills/sm-flow/SKILL.md

@@ -24,15 +24,16 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 
 - Phase 3 默认必须通过 OpenSpec apply 执行；禁止直接依赖 devflow 文档绕过 OpenSpec 写代码。
 - devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。
-- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
 - 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
 - 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
 - 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。
+- Phase 0、0.5、1、2、2.5、2.9 只有在显式 checkpoint 后才算完成；checkpoint 至少汇报当前阶段、能力来源、产出物、已满足退出条件和未解决阻塞。
 - `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
 - `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
+- Phase 1.5 必须显式检查 `brief/prd -> proposal -> design -> specs -> tasks` 的 cross-artifact 对齐；发现缺口时先修 OpenSpec，再继续后续阶段。
+- Phase 2 必须先建立 question pool，再按 one-at-a-time 规则消费 `user-interview` 问题；问题池至少覆盖术语、边界、验收，复杂变更还要补充模块、接口、权限、消费者、响应结构或生命周期维度。
 - grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
 - 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。
-- 接口影响按 L1-L4 分级处理；接口内部判断逻辑如果改变调用方可观察行为，也属于接口影响，不能因签名未变而降级。
 - Phase 3 实现期冲突必须先分类再处理：实现偏差修代码；规格遗漏修 OpenSpec；设计冲突暂停并请用户确认；用户变更更新 proposal/specs/tasks 后再继续。
 - 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
 - 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
@@ -41,87 +42,21 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 - 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
 - 子 skill 绑定能力契约，不绑定单一平台路径。显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应能力的本地 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
 - fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
-
-## 接口影响分级
-
-接口影响分级判断的是“记录在哪里、是否需要独立文档”，不是判断“是否需要关注”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或接口内部判断逻辑变化，都必须先判断接口影响。
-
-| 级别 | 判断条件 | 产物要求 |
-| --- | --- | --- |
-| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
-| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
-| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
-| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
-
-判断策略：
-
-- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
-- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
-- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
-- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
+- `micro` 只能压缩产物重量，不能跳过关键 gate；Phase 0.5 最小上下文收集、Phase 2 最小澄清、Phase 2.9 commit gate 和 Phase 4 轻量回填必须保留。
+- devflow 记录必须按阶段就近更新；Phase 4 主要做 consolidation，而不是第一次补写 `brief.md`、`evidence.md`、`decisions.md` 或 `acceptance.md`。
 
 ## 首次加载
 
 执行前只读取当前任务需要的 reference 文件：
 
-- 需要逐阶段执行时，读取 `references/phase-contracts.md`。
+- 需要逐阶段执行时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。
 - 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
 - Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
 - 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。
 
 ## 启动检查
 
-1. 判断启动模式：
-   - 完整模式：用户提供粗略想法或初始 PRD。
-   - Research 模式：用户已有 research，需要转成或修正 OpenSpec。
-   - PRD 文件模式：用户提供已有 PRD 路径。
-   - 指定阶段模式：用户要求从某个 Phase 恢复。
-   - 快速模式：小改动，Phase 2 和 Phase 4 可以轻量化，但不能省略。
-2. 如果缺少 `devflow/`，初始化：
-   - `devflow/projects/`
-   - `devflow/glossary/CONTEXT.md`
-   - `devflow/compound/`
-   - `devflow/reference/`
-3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
-4. 检查 OpenSpec 和子 skill 是否可用：
-   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。可由平台原生 skill、`.claude/skills/.../SKILL.md` 或 fallback 协议提供。
-   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。可由平台原生 skill、`.agents/skills/.../SKILL.md` 或 fallback 协议提供。
-5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
-
-## 项目标识
-
-整个流程使用同一个 slug：
-
-- 优先使用 OpenSpec change name。
-- 如果还没有 change name，则从功能标题生成 kebab-case slug。
-- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
-- 如果目录已存在，默认恢复该项目，不要重复创建；除非用户明确要求新开一轮。
-
-## Devflow 产物分层
-
-devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的执行产物。默认只创建必要文件；扩展文件必须有明确理由。
-
-**必须产物**：
-
-- `brief.md`：背景、目标、范围、非目标、变更规模、关联 OpenSpec change。
-- `evidence.md`：代码证据、文档证据、历史决策、evidence-driven 结论和汇报状态。
-- `decisions.md`：user-interview 问题、用户确认、关键取舍、风险接受、OpenSpec 回写记录。
-- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
-
-**按需产物**：
-
-- `prd.md`：需求复杂、用户明确要求 PRD、或需要对外协作时创建；小需求并入 `brief.md`。
-- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较时创建。
-- `design.md`：仅记录 OpenSpec design 不适合承载的人类背景、架构审计摘要或长期决策索引；实现设计仍以 OpenSpec design 为准。
-- `tasks.md`：仅记录跨轮次追踪或人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
-- `alignment.md` / `clarifications.md`：问题很多或冲突复杂时单独创建；否则并入 `decisions.md`。
-- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR/复合知识规则时创建。
-
-**规模分档**：
-
-- `micro`：小且低风险，使用 `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md`。
-- `standard`：默认模式，使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。
-- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加 PRD/research/design/tasks/alignment。
+按 `references/operating-rules.md` 执行启动检查、项目 slug 规则和 devflow 产物分层。
 
 ## 阶段总览
 
@@ -137,23 +72,13 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
 
 每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
 
+关键阶段的完成判断也以 `references/phase-contracts.md` 为准；如果缺少显式 checkpoint 或能力来源声明，该阶段不得视为已完成。
+
 ## 快速模式
 
-快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留：
-
-- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
-- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
-- Phase 2.9 提交检查：即使快速模式也必须确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
-- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
-- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
+快速模式的具体约束见 `references/operating-rules.md`。
 
 ## 完成标准
 
-一次流程只有在满足以下条件时才算完成：
-
-- OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。
-- 实现或规划任务已经完成，且执行依据来自 OpenSpec。
-- 已运行验证，或明确记录未运行验证的原因。
-- `devflow/projects/YYYY-MM-DD-{slug}/` 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。
-- 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。
+流程完成标准见 `references/operating-rules.md`。