Refine sm-flow trigger and scale rules

.agents/skills/sm-flow/references/phase-contracts.md

@@ -4,6 +4,18 @@
 
 执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive。
 
+## 目录
+
+- clarify — 入口澄清
+- context — 上下文收集
+- propose — 轻量 propose
+- grill — 人类对齐澄清
+- specify — 细化 + 对齐
+- audit — 架构审计
+- commit — Commit OpenSpec
+- apply — OpenSpec 执行
+- archive — 回填 + 归档
+
 ## clarify — 入口澄清
 
 **进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。
@@ -13,7 +25,7 @@
 - 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
 - 如果输入过于模糊，最多追加三轮聚焦问题。
 - 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
-- 如果需要判断 `micro / standard / complex` 分档，补读 `references/operating-rules.md`。
+- 如果需要判断 `micro / standard / complex` 分档，补读 `references/scales.md`。
 
 **退出条件**：
 - 问题可以用 1-2 句话说清楚。
@@ -36,7 +48,7 @@
 - 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
 - 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
 - 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
-- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。
+- 记录哪些上下文会影响 OpenSpec proposal、设计产物、specs 或 tasks。
 - 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。
 
 **退出条件**：
@@ -70,13 +82,13 @@
 
 **Human checkpoint**：
 - 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。
-- 询问是否继续进入 grill 澄清阶段；用户明确要求"全自动执行"时可跳过等待。
+- 作为 Discover checkpoint 的中间状态汇报；询问是否继续完成 Discover 的人类澄清部分。用户明确要求"全自动执行"时可跳过等待。
 
 ## grill — 人类对齐澄清
 
 **进入条件**：propose 已有轻量 proposal.md。
 
-**显式子 skill**：`grill-with-docs`。进入本阶段必须调用 `.agents/skills/grill-with-docs/SKILL.md`。
+**能力来源**：优先使用 `grill-with-docs`；不可用时使用 `references/fallbacks.md#grill-内置协议`，并在 `decisions.md` 标注 fallback。
 
 **动作**：
 - 优先使用 `grill-with-docs`。
@@ -101,7 +113,7 @@
 
 **退出条件**：
 - question pool 已建立并覆盖当前 change 所需维度。
-- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
+- 已满足 `references/scales.md` 中当前分档的 grill 要求。每个问题都必须记录属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
 - 没有未解决或代理代确认的 user-interview 问题。
@@ -117,20 +129,20 @@
 
 **Human checkpoint**：
 - 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。
-- 询问是否继续进入 specify 细化阶段。
+- 汇报 Discover checkpoint 完成情况，并询问是否继续进入 Commit checkpoint。
 
 ## specify — 细化 + 对齐
 
 **进入条件**：grill 已退出，需求已通过澄清稳定下来。
 
-**显式子 skill**：`openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；`to-prd`（按需生成 PRD）。进入本阶段必须先声明调用方式。
+**能力来源**：优先使用 `openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；按需使用 `to-prd`。进入本阶段必须先声明调用方式；外部能力不可用时使用 `references/fallbacks.md#openspec-提案-内置协议`，并在 `decisions.md` 标注 fallback。
 
 **动作**：
-- 基于已稳定的 proposal.md 补全 design.md、specs/、tasks.md：
-  - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需补全 design/specs/tasks"。
-  - 如果不可用，执行 `references/fallbacks.md#openspec-提案-降级`。
+- 基于已稳定的 proposal.md 补全设计产物、specs/、tasks.md：
+  - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需按当前分档补全设计产物/specs/tasks"。
+  - 如果不可用，执行 `references/fallbacks.md#openspec-提案-内置协议`。
 - 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
-- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级。
+- 独立 PRD 是否需要按 `references/scales.md` 的当前分档和用户要求判断。
 - 用 grill 阶段的 decisions.md 记录增强 OpenSpec 产物：确保 design/specs/tasks 反映所有已确认的决策。
 - **显式 cross-artifact 对齐检查**——在 checkpoint 中输出对齐检查表：
   - `brief/prd` 中的目标、范围、非目标和验收预期 → `proposal` 是否覆盖。
@@ -147,14 +159,14 @@
 - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
 
 **退出条件**：
-- `design.md`、`specs/`、`tasks.md` 存在且与 proposal 对齐。
+- OpenSpec 细化产物存在且与 proposal 对齐；产物形态按 `references/scales.md` 的当前分档要求执行。
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。
 - 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。
 - 所有已知冲突已修正或等待用户决策。
 
 **输出**：
-- 完整的 Draft OpenSpec：proposal.md + design.md + specs/ + tasks.md。
+- Draft OpenSpec：按 `references/scales.md` 的当前分档要求生成 proposal、设计、specs 和 tasks。
 - `brief.md`，以及按需创建的 `prd.md`。
 - cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。
 - 必要的 OpenSpec 修正。
@@ -163,7 +175,7 @@
 
 **进入条件**：specify 已退出，完整 OpenSpec 产物已存在。
 
-**显式子 skill**：`zoom-out`。进入本阶段必须调用 `.agents/skills/zoom-out/SKILL.md`。
+**能力来源**：优先使用 `zoom-out`；不可用时使用 `references/fallbacks.md#audit-内置协议`，并在 `decisions.md` 标注 fallback。
 
 **动作**：
 - 画出输入 → 处理 → 输出的模块链路。
@@ -175,20 +187,20 @@
 
 **退出条件**：
 - 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。
-- OpenSpec design/tasks 已反映会影响实现的架构审计结论。
+- OpenSpec 设计产物/tasks 已反映会影响实现的架构审计结论。
 
 **输出**：
 - 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。
-- 必要的 OpenSpec design/tasks 修正。
+- 必要的 OpenSpec 设计产物/tasks 修正。
 
 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
-- 询问是否进入 commit。
+- 作为 Commit checkpoint 的中间状态汇报；询问是否继续完成 commit gate。
 
 ## commit — Commit OpenSpec
 
 **进入条件**：
-- grill 已解决术语、边界、验收三个维度的高价值问题。
+- grill 已满足 `references/scales.md` 中当前分档要求。
 - 所有 `user-interview` 问题都已获得用户显式确认。
 - audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。
 - Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
@@ -198,7 +210,7 @@
 - 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
 - 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
 - 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
-- 复核 cross-artifact 对齐：`brief/prd → proposal → design → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。
+- 复核 cross-artifact 对齐：`brief/prd → proposal → 设计产物 → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。
 - 检查 `decisions.md` 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。
 - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
 - 检查接口影响是否已按 L1/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
@@ -207,14 +219,14 @@
 
 **退出条件**：
 - Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
-- **文件完整性检查**（必须全部通过）：
-  - [ ] `proposal.md` 存在，包含问题描述（至少 50 字）、建议方案（至少 100 字）、范围/非目标
-  - [ ] `design.md` 存在，包含架构设计（文字或图）、数据结构定义（至少 1 个）、关键决策记录（至少 2 条）
-  - [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
-  - [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准
+- **文件完整性检查**（按 `references/scales.md` 的当前分档要求执行）：
+  - [ ] proposal 存在，且足以说明问题、建议方案、范围和非目标。
+  - [ ] 设计产物存在，形式符合当前分档要求。
+  - [ ] specs 存在，且表达用户可观察行为。
+  - [ ] tasks 存在，且任务可执行、验收标准可验证。
 - **一致性检查**（必须通过）：
-  - [ ] proposal 中的核心概念在 design 中有对应设计
-  - [ ] design 中的关键决策在 tasks 中有对应实现任务
+  - [ ] proposal 中的核心概念在设计产物中有对应设计
+  - [ ] 设计产物中的关键决策在 tasks 中有对应实现任务
   - [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
 - **标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
 - 所有 preflight 风险已消除或明确记录为已接受。
@@ -225,28 +237,28 @@
 
 **Human checkpoint**：
 - 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
-- 询问是否进入 apply；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
+- 汇报 Commit checkpoint 完成情况，并询问是否进入 Apply checkpoint；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
 - 不得把 grill 的单个决策确认当作本 checkpoint 的授权。
 
 ## apply — OpenSpec 执行
 
 **进入条件**：
-- `openspec/changes/{slug}/` 中 proposal/design/specs/tasks 已通过 commit，成为 Committed OpenSpec。
+- `openspec/changes/{slug}/` 中 proposal、设计产物、specs、tasks 已通过 commit，成为 Committed OpenSpec。
 - **前置门控检查**（硬约束）：
   - 检查 `openspec/changes/{slug}/.committed` 文件是否存在
   - 如不存在，执行以下流程：
     1. 汇报：Draft OpenSpec 未通过 commit 检查
     2. 列出缺失的 checkpoint 项（文件完整性、一致性检查）
-    3. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
+    3. 询问用户：是否补做 commit 检查；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`，且本次流程不得视为合规 sm-flow apply
 - commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。
 - devflow 与 OpenSpec 没有未解决冲突。
 - 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
 
-**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须调用指定子 skill，不得静默跳过。
+**能力来源**：优先使用 `openspec-apply-change`；不可用时使用 `references/fallbacks.md#openspec-apply-内置协议`，并在 `decisions.md` 标注 fallback。遇到 bug/不确定行为时优先使用 `diagnose`；需要测试驱动时优先使用 `tdd`。不可用时执行对应最小协议并记录原因，不得静默跳过。
 
 **动作**：
 
-### Pre-apply Checkpoint（15-20 分钟）
+### Pre-apply Checkpoint
 
 **触发条件**：当 OpenSpec 涉及以下任一情况时必须执行
 - design 或 tasks 中提到"参考 XXX 实现"
@@ -254,12 +266,12 @@
 - 技术栈不熟悉或第一次在该项目实现类似功能
 
 **执行步骤**：
-1. **完整阅读所有参考实现**（约 10 分钟）
+1. **阅读所有参考实现**
    - 从 OpenSpec design 或 tasks 中定位参考实现文件
    - 如果路径不明确，通过 Grep 搜索关键类名或模式
-   - 逐行理解关键逻辑，提取可复用代码片段和模式
+   - 理解关键逻辑，提取可复用代码片段和模式
 
-2. **Grep 关键技术栈**（约 5 分钟）
+2. **Grep 关键技术栈**
    - 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范）
    - 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板）
    - 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具）
@@ -273,11 +285,11 @@
    - 识别需要新建的工具类或基础设施
 
 **输出要求**：
-- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节 ✅
-- 已列出所有参考实现的文件路径 ✅
-- 已识别需要新建的工具类/基础设施 ✅
+- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节。
+- 已列出所有参考实现的文件路径。
+- 已识别需要新建的工具类/基础设施。
 
-**快速模式**：micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单。
+**按风险执行**：执行深度按 `references/scales.md` 的当前分档和实现风险决定；退出判断以清单是否足以指导实现为准。
 
 ### 实现过程
 
@@ -299,9 +311,9 @@
 - 修改文件前遵守仓库指令，例如 `AGENTS.md`。
 
 **退出条件**：
-- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md` ✅
+- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`。
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
-- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位 ✅
+- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位。
 - 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。
@@ -315,13 +327,13 @@
 
 **进入条件**：实现或规划工作已经达到可交接状态。
 
-**显式子 skill**：`openspec-archive-change` 在用户确认 archive 后调用；archive 回填由 `sm-flow` 执行。必须调用子 skill，不得静默跳过。
+**能力来源**：`openspec-archive-change` 在用户确认 archive 后优先调用；不可用时使用 `references/fallbacks.md#openspec-archive-内置协议`，并在 `acceptance.md` 标注 fallback。archive 回填由 `sm-flow` 执行。
 
 **动作**：
 - 遵循 `references/archive-rules.md`。
 - 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案：
   - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
-  - `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。
+  - `evidence.md`：按 `references/scales.md` 和 `references/archive-rules.md` 的当前分档要求处理。
   - `decisions.md`：保持为最终版，整理格式。
   - `acceptance.md`：从实现结果和验证结果提取。
 - 只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
@@ -331,7 +343,7 @@
 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。
 
 **退出条件**：
-- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
+- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
 - `devflow/index.md` 已包含或更新本项目条目。
 - 用户已被询问是否 archive OpenSpec change。