Refine sm-flow trigger and scale rules

Merge pull request 'emdash/cuddly-rockets-rhyme-d5jo4' (#1 ) from emdash/cuddly-rockets-rhyme-d5jo4 into master
Reviewed-on: #1
2026-07-05 14:30:15 +08:00 · 2026-07-05 03:16:12 +08:00 · 2026-06-24 14:51:45 +08:00 · 2026-06-23 11:27:32 +08:00
32 changed files with 2623 additions and 72 deletions
@@ -1,6 +1,6 @@
 ---
 name: sm-flow
-description: OpenSpec-first 的结构化工程开发协议层 harness。编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用。
+description: OpenSpec-first 工程流程 harness。仅在用户显式调用 /sm-flow、/sm-flow explore、/sm-flow apply、/sm-flow archive，或明确要求使用 sm-flow 流程时使用；不要根据需求类型自动触发。
 ---

 # SM Flow
@@ -9,6 +9,15 @@ SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周

 sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。

+## 触发规则
+
+只在用户显式调用时使用 sm-flow：
+
+- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。
+- 用户用自然语言明确要求"使用 sm-flow"、"走 sm-flow 流程"或等价表达。
+
+不要根据需求类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。
+
 ## 四层架构

 ```
@@ -30,10 +39,10 @@ sm-flow        → 编排层（harness）：阶段、门控、产物约束、人

 1. **OpenSpec 是唯一执行真理源**。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。
 2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
-3. **不得跳过 grill**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。
+3. **不得跳过 grill**。必须按 `references/scales.md` 的当前分档要求完成澄清或验证。
 4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
 5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
-6. **子 skill 必须显式调用**。每个阶段指定的子 skill 必须显式调用；如果子 skill 不存在，流程失败，不得静默跳过或降级执行。
+6. **能力来源必须显式声明**。每个阶段先声明使用外部子 skill / OpenSpec CLI / sm-flow 内置协议；外部能力不可用时可使用 `references/fallbacks.md` 的内置协议，但必须标注为 fallback。若外部能力和内置协议都不可用，流程失败。

 每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。

@@ -48,11 +57,26 @@ sm-flow        → 编排层（harness）：阶段、门控、产物约束、人

 用户也可以用自然语言指定从某个阶段继续，例如"ops-message-support 的 grill 已经做完了，继续"。harness 识别意图后，自动补做最小前置检查，然后从指定阶段继续。

+## 可见 Checkpoint
+
+内部阶段不是用户 API。对用户汇报进度时，默认只暴露 4 个 checkpoint：
+
+| Checkpoint | 覆盖内部阶段 | 用户可见含义 |
+|---|---|---|
+| Discover | clarify + context + propose + grill | 澄清目标、读取 devflow、形成轻量 proposal、解决关键问题 |
+| Commit | specify + audit + commit | 补全 OpenSpec、做架构/产物对齐、生成 Committed OpenSpec |
+| Apply | apply | 基于 Committed OpenSpec 实现和验证 |
+| Archive | archive | 回填 devflow、汇报验收、询问是否归档 OpenSpec |
+
+除非用户要求看细节，进度汇报、暂停点和恢复提示应使用 checkpoint 名称，而不是逐个暴露 9 个内部阶段。内部阶段仍按顺序执行，并以 `references/phase-contracts.md` 为准。
+
 ## 首次加载

 执行前只读取当前任务需要的 reference 文件：

- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。
+- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`；如果外部 OpenSpec 能力或子 skill 不可用，再补读 `references/fallbacks.md`。
+- 判断或执行 `micro / standard / complex` 分档时，读取 `references/scales.md`；其它文件不得重复定义分档细节。
+- 当 checkpoint / gate / fallback / Draft / Committed 等术语含义不清，或需要统一对用户说明时，读取 `references/glossary.md`。
 - 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
 - archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。

@@ -2,6 +2,49 @@

 archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转化为持久、可读、可复用的项目记忆。sm-flow 在 clarify → apply 期间只维护 `decisions.md` 作为过程日志，archive 阶段从中提取完整 devflow 档案。

+## Archive 强制执行顺序
+
+Archive 阶段必须按以下顺序执行，不得跳过或重排：
+
+### Step 1: 创建 devflow 档案（必需）
+
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
+      （从 proposal.md 提取：背景、目标、范围、非目标）
+      
+- [ ] 按 `references/scales.md` 的当前分档决定是否创建 `devflow/projects/YYYY-MM-DD-{slug}/evidence.md`
+      （创建时从 decisions.md 提取 evidence-driven 记录）
+      
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
+      （整理为最终版：关键决策、权衡、风险）
+      
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
+      （记录：静态验证、脚本验证、浏览器/人工验证、未验证）
+
+### Step 2: 更新索引（必需）
+
+- [ ] 在 `devflow/index.md` 末尾追加或更新一行：
+      `| YYYY-MM-DD | slug | 领域 | 关键词 | openspec/changes/xxx | {status} |`
+
+### Step 3: 标记 OpenSpec（必需）
+
+- [ ] 创建 `openspec/changes/{slug}/.archive-ready` 文件
+
+### Step 4: 向用户汇报（必需）
+
+- [ ] 列出创建的 devflow 档案文件路径（验证文件实际存在于磁盘）
+- [ ] 汇报验证情况（按静态验证、脚本验证、浏览器/人工验证、未验证分类）
+- [ ] 列出剩余风险或后续事项
+- [ ] 询问：**是否现在归档 OpenSpec？**
+
+### Step 5: 用户确认后执行 OpenSpec Archive（可选）
+
+- [ ] 调用 `openspec-archive-change`
+- [ ] 记录 archive 结果
+
+**自检**：在执行 Step 4 前，检查 Step 1-3 是否都完成。
+
+---
+
 ## 目录规则

 项目档案路径：
@@ -10,10 +53,10 @@ archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转
 devflow/projects/YYYY-MM-DD-{slug}/
 ```

-archive 阶段创建以下文件：
+archive 阶段按 `references/scales.md` 的当前分档创建以下文件：

 - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。
+- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取；是否独立创建按 `references/scales.md` 执行。
 - `decisions.md`：保持为最终版，整理格式。
 - `acceptance.md`：从实现结果和验证结果提取。

@@ -34,11 +77,7 @@ archive 阶段创建以下文件：

 ## 产物分档

-| 分档 | 适用场景 | 必须文件 | 扩展文件 |
-| --- | --- | --- | --- |
-| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md` | 证据少时并入 `brief.md` |
-| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | 按需 ADR/compound |
-| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 全部文件 | 按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md` |
+分档的适用场景和必须文件见 `references/scales.md`。本文件只定义 archive 阶段的创建顺序、提取映射和索引规则。

 ## 提取映射

@@ -0,0 +1,49 @@
+# 内置执行协议
+
+本文件只在外部 OpenSpec CLI 或子 skill 不可用时使用。fallback 不是跳过阶段，而是由 sm-flow 用文件方式完成同等最小产物。每次使用 fallback 都必须写入 `decisions.md` 或 `acceptance.md`，说明能力来源、缺失能力、影响和剩余风险。
+
+## 通用规则
+
+- 优先使用外部能力；只有不可用、不可发现或无法在当前环境调用时才使用内置协议。
+- 不得因为使用 fallback 跳过 context、grill、commit、apply 授权或 archive 确认。
+- fallback 产物仍写入 `openspec/changes/{slug}/` 和 `devflow/projects/YYYY-MM-DD-{slug}/`。
+- 如果内置协议也无法满足阶段退出条件，暂停并向用户说明阻塞项。
+
+## grill 内置协议
+
+- 建立 question pool，至少覆盖术语、边界、验收；涉及参考实现或项目基础设施时加入技术实现问题。
+- 将问题标记为 `evidence-driven` 或 `user-interview`。
+- 先查证 evidence-driven 问题并汇报结论，再逐个询问 user-interview 问题。
+- 按 `references/scales.md` 的当前分档满足 grill 要求。
+- 将 question pool、证据结论、用户原话和确认状态写入 `decisions.md`；影响实现的结论回写 `proposal.md`。
+
+## openspec 提案内置协议
+
+- 在 `openspec/changes/{slug}/` 创建或更新：
+  - `proposal.md`：问题、方案、范围、非目标、上下文约束、风险。
+  - 设计产物：实现设计、接口影响、关键决策、架构风险；形式按 `references/scales.md` 的当前分档要求执行。
+  - `specs/*/spec.md` 或等价 functional spec：描述用户可观察行为和验收场景。
+  - `tasks.md`：按可执行切片拆分任务，并给每项写可验证验收标准。
+- 运行 cross-artifact 对齐检查：proposal → 设计产物 → specs → tasks。
+- 如果发现 gap，先修正 OpenSpec，再进入 commit。
+
+## audit 内置协议
+
+- 用 5 句话以内说明模块链路、数据所有权、跨模块依赖、架构风险和是否需要回写 OpenSpec。
+- 如果风险影响实现，修正设计产物或 `tasks.md`。
+- 将结论写入 `decisions.md`。
+
+## openspec apply 内置协议
+
+- 只依据 Committed OpenSpec 的 specs/tasks 实现；devflow 只作上下文参考。
+- 开始前检查 `.committed` 文件；缺失则返回 commit。
+- 如触发 pre-apply checkpoint，先阅读参考实现、grep 项目基础设施模式，并把技术栈清单写入 `decisions.md`。
+- 按 tasks 的纵向切片实现、验证并更新任务状态。
+- 发现冲突时按三类处理：OpenSpec 不准则修 OpenSpec，代码偏离则修代码，不确定则暂停等用户确认。
+
+## openspec archive 内置协议
+
+- 不删除或移动 OpenSpec change；只标记归档准备状态。
+- 完成 devflow 回填、更新 `devflow/index.md`、创建 `.archive-ready`。
+- 向用户汇报已创建文件、验证分类、剩余风险，并询问是否需要真实 OpenSpec archive。
+- 如果外部 archive 能力仍不可用，在 `acceptance.md` 标记 `accepted-unarchived`。
@@ -0,0 +1,21 @@
+# 术语表
+
+本文件统一 sm-flow 协议中的核心词。优先使用这些词，避免同一概念多种说法。
+
+| 术语 | 含义 | 使用边界 |
+| --- | --- | --- |
+| sm-flow | 协议层 harness | 编排 OpenSpec 生命周期，不替代 OpenSpec |
+| OpenSpec | 当前变更的执行真理源 | apply 只能依据 Committed OpenSpec |
+| devflow | 长期记忆和上下文层 | 提供术语、历史决策、验收记录，不直接指挥实现 |
+| checkpoint | 用户可见检查点 | 默认只暴露 Discover / Commit / Apply / Archive |
+| gate | 硬门控 | 不满足就不能进入下一关键动作，如 commit gate |
+| Draft OpenSpec | 讨论和审计对象 | propose/specify 期间产生，不能直接 apply |
+| Committed OpenSpec | 已通过 commit gate 的 OpenSpec | apply 的唯一执行依据 |
+| fallback | 内置执行协议 | 外部 OpenSpec CLI 或子 skill 不可用时使用，必须标注 |
+| decisions.md | 过程日志 | clarify 到 apply 期间记录问题、证据、决策、冲突和回写 |
+| .committed | commit gate 标记文件 | 存在才可进入合规 apply |
+| .archive-ready | archive 准备标记文件 | 表示 devflow 已回填，等待用户确认是否 archive |
+| Discover | 用户可见 checkpoint | 覆盖 clarify + context + propose + grill |
+| Commit | 用户可见 checkpoint | 覆盖 specify + audit + commit |
+| Apply | 用户可见 checkpoint | 覆盖 apply |
+| Archive | 用户可见 checkpoint | 覆盖 archive |
@@ -27,13 +27,14 @@
   - `/sm-flow apply [change]`：只执行，检查 commit gate → apply。
   - `/sm-flow explore`：带上下文的探索模式，不走标准阶段链。
   - `/sm-flow archive [change]`：收尾，回填 devflow + 归档确认。
+   - 明确要求"使用 sm-flow"或"走 sm-flow 流程"：按显式调用处理。
   - 自然语言指定阶段继续：识别意图后，自动补做最小前置检查，然后从指定阶段继续。
 2. 判断启动模式：
   - 完整模式：用户提供粗略想法或初始 PRD。
   - Research 模式：用户已有 research，需要转成或修正 OpenSpec。
   - PRD 文件模式：用户提供已有 PRD 路径。
   - 恢复模式：用户希望从某个阶段继续（补做最小前置检查）。
-   - 快速模式：小改动，合并 gate（见下文）。
+   - 快速模式：小改动，合并 gate；具体分档规则见 `references/scales.md`。
 3. 如果缺少 `devflow/`，初始化：
   - `devflow/projects/`
   - `devflow/glossary/CONTEXT.md`
@@ -42,7 +43,25 @@
 5. 检查 OpenSpec 和子 skill 是否可用：
   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。
   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。
-6. 如果 OpenSpec 不可用，不要直接绕过；使用内置执行协议（见 `references/fallbacks.md`），并在 apply 前向用户说明。
+6. 如果 OpenSpec 或子 skill 不可用，不要静默跳过；使用内置执行协议（见 `references/fallbacks.md`），并在当前 checkpoint 说明 fallback 来源、影响和剩余风险。
+
+## 进度汇报
+
+用户可见进度默认折叠为 4 个 checkpoint：
+
+| Checkpoint | 内部阶段 |
+| --- | --- |
+| Discover | clarify + context + propose + grill |
+| Commit | specify + audit + commit |
+| Apply | apply |
+| Archive | archive |
+
+汇报规则：
+
+- 面向用户时优先使用 checkpoint 名称，不逐个汇报 9 个内部阶段。
+- 内部阶段只在 checkpoint 摘要中作为证据列出，例如"Discover 已完成：读取了 devflow、生成 proposal、解决 2 个问题"。
+- 只有发生阻塞、冲突、fallback、用户要求继续某个内部阶段，或需要解释恢复位置时，才暴露内部阶段名。
+- 当前分档的汇报压缩规则见 `references/scales.md`；无论分档如何，都不要把内部阶段名当作用户操作入口。

 ## 项目标识规则

@@ -63,7 +82,7 @@ Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec
 **最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）：

 - `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。
- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态。
+- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态；分档要求见 `references/scales.md` 和 `references/archive-rules.md`。
 - `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。

 **按需产物**（archive 阶段按需创建）：
@@ -75,28 +94,17 @@ Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec
 - `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用。
 - `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用。

-**规模分档**：
-
- `micro`：小且低风险，gate 合并（见快速模式），最终档案同 standard。
- `standard`：默认模式。
- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加扩展产物。
+**规模分档**：`micro / standard / complex` 的唯一规则源是 `references/scales.md`。

 ## 快速模式

-快速模式适用于小而低风险的变更。它合并 gate 而不仅仅是压缩产物：
-
-```
-standard 流程：clarify → context → propose checkpoint → grill → specify → audit checkpoint → commit
-micro 流程：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题） → commit（简化检查）
-```
-
-micro 的定位：**gate 变少但保留最关键的**（grill 最小澄清 + commit gate）。
+快速模式适用于 `references/scales.md` 定义的 micro 变更。它合并 gate 而不仅仅是压缩产物；具体覆盖规则见 `references/scales.md`。

 无论什么模式，以下内容必须保留：

 - context 最小上下文收集：至少检查 glossary 和相关 ADR。
- grill 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报。
- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
+- grill 最小澄清：按 `references/scales.md` 当前分档要求执行；evidence-driven 结论仍需汇报。
+- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行；完整性检查按 `references/scales.md` 当前分档要求执行。
 - apply 仍由 OpenSpec tasks/specs 驱动执行。
 - archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。

@@ -104,8 +112,9 @@ micro 的定位：**gate 变少但保留最关键的**（grill 最小澄清 + co

 只有同时满足以下条件，流程才算完成：

- OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态。
+- 用户可见的 Discover、Commit、Apply、Archive checkpoint 已完成，或未完成项已明确标记为暂停/不适用。
+- OpenSpec proposal、设计产物、specs、tasks 已按当前分档生成或更新到可执行状态。
 - 实现或规划工作已完成，且执行依据来自 OpenSpec。
 - 已运行验证，或已记录未运行验证的原因。
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md。
+- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案。
 - 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。
@@ -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,18 +82,22 @@

 **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`。
 - 进入 grill 时先建立一个 question pool，并记录到 `decisions.md`：
  - 默认至少覆盖术语、边界、验收三个维度。
+  - **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
+    - 参考实现的具体文件路径是什么？
+    - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
+    - 有哪些技术点需要先调研或新建？
  - 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。
 - 逐项标记每个问题的模式：
  - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
@@ -97,7 +113,7 @@

 **退出条件**：
 - question pool 已建立并覆盖当前 change 所需维度。
- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
+- 已满足 `references/scales.md` 中当前分档的 grill 要求。每个问题都必须记录属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
 - 没有未解决或代理代确认的 user-interview 问题。
@@ -113,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` 是否覆盖。
@@ -143,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 修正。
@@ -159,7 +175,7 @@

 **进入条件**：specify 已退出，完整 OpenSpec 产物已存在。

-**显式子 skill**：`zoom-out`。进入本阶段必须调用 `.agents/skills/zoom-out/SKILL.md`。
+**能力来源**：优先使用 `zoom-out`；不可用时使用 `references/fallbacks.md#audit-内置协议`，并在 `decisions.md` 标注 fallback。

 **动作**：
 - 画出输入 → 处理 → 输出的模块链路。
@@ -171,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 已回写所有会影响实现的澄清、接口影响和架构审计结论。
@@ -194,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 是否有独立接口文档或等价独立章节。
@@ -203,7 +219,16 @@

 **退出条件**：
 - Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
- apply 所需的 proposal、design、specs 和 tasks 均存在且一致；commit checkpoint 必须验证文件实际存在于磁盘，如果任一文件不存在，commit 失败，返回 specify 补写。
+- **文件完整性检查**（按 `references/scales.md` 的当前分档要求执行）：
+  - [ ] proposal 存在，且足以说明问题、建议方案、范围和非目标。
+  - [ ] 设计产物存在，形式符合当前分档要求。
+  - [ ] specs 存在，且表达用户可观察行为。
+  - [ ] tasks 存在，且任务可执行、验收标准可验证。
+- **一致性检查**（必须通过）：
+  - [ ] proposal 中的核心概念在设计产物中有对应设计
+  - [ ] 设计产物中的关键决策在 tasks 中有对应实现任务
+  - [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
+- **标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
 - 所有 preflight 风险已消除或明确记录为已接受。

 **输出**：
@@ -212,36 +237,83 @@

 **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 检查；如用户要求不补做，则中止 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
+
+**触发条件**：当 OpenSpec 涉及以下任一情况时必须执行
+- design 或 tasks 中提到"参考 XXX 实现"
+- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
+- 技术栈不熟悉或第一次在该项目实现类似功能
+
+**执行步骤**：
+1. **阅读所有参考实现**
+   - 从 OpenSpec design 或 tasks 中定位参考实现文件
+   - 如果路径不明确，通过 Grep 搜索关键类名或模式
+   - 理解关键逻辑，提取可复用代码片段和模式
+
+2. **Grep 关键技术栈**
+   - 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范）
+   - 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板）
+   - 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具）
+   - 异常处理和日志记录标准
+
+3. **形成技术栈清单并写入 decisions.md**
+   - 项目使用的请求/响应结构标准
+   - MQ 消息定义和发送标准
+   - Consumer 标准位置和写法
+   - 加密/验签/工具类的标准用法
+   - 识别需要新建的工具类或基础设施
+
+**输出要求**：
+- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节。
+- 已列出所有参考实现的文件路径。
+- 已识别需要新建的工具类/基础设施。
+
+**按风险执行**：执行深度按 `references/scales.md` 的当前分档和实现风险决定；退出判断以清单是否足以指导实现为准。
+
+### 实现过程
+
 - 优先调用 `openspec-apply-change`。
 - 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
 - 按 OpenSpec tasks 的纵向切片实现。
+- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
 - 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 apply 不算真正开始。
+- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
 - 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，做三类判断：
  - OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停 apply，修正 OpenSpec 后重新提交。
  - 代码偏离（实现没按 OpenSpec 做）→ 修正代码，不改 OpenSpec。
  - 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。
 - 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。
+- **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
 - 当用户要求、行为复杂或回归风险高时使用 TDD。
 - 当测试失败、行为意外或原因不确定时使用 diagnose。
 - 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
 - 修改文件前遵守仓库指令，例如 `AGENTS.md`。

 **退出条件**：
+- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`。
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
+- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位。
 - 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。
@@ -255,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。
@@ -271,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。

@@ -0,0 +1,42 @@
+# 分档规则
+
+本文件是 `micro / standard / complex` 的唯一规则源。其它文件只引用本文件，不重复定义分档细节。
+
+## standard 基准
+
+standard 是默认分档，适用于普通功能、明确但有一定实现范围的变更。
+
+- 用户可见 checkpoint：Discover → Commit → Apply → Archive。
+- OpenSpec 产物：`proposal.md`、独立 `design.md`、`specs/`、`tasks.md`。
+- grill：解决术语、边界、验收三个维度的高价值问题。
+- commit gate：检查 proposal、design、specs、tasks 的完整性和一致性。
+- devflow 档案：`brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。
+
+## micro 覆盖
+
+micro 适用于小改动、低风险、需求明确的变更。micro 是 standard 的减法，不是跳过流程。
+
+- checkpoint 可合并：Discover + Commit 可在无阻塞时合并汇报。
+- micro 内部流程压缩为：clarify+context 合并 checkpoint → 轻量 propose → grill → specify+commit 合并 checkpoint。
+- context 保留最小收集：至少检查 glossary 和相关 ADR。
+- grill 保留最小澄清：至少解决一个高价值问题，并记录术语、边界、验收三类是否明确；不明确项必须补问或标记风险。
+- OpenSpec 仍需要 `proposal.md`、`specs/`、`tasks.md`。
+- `design.md` 可不独立创建；允许在 `proposal.md` 或 `tasks.md` 中写等价设计小节。
+- `specs/` 和 `tasks.md` 可轻量，但必须表达可观察行为和可执行任务。
+- commit gate 仍必须通过，并创建 `.committed`。
+- devflow 档案至少包含 `brief.md`、`decisions.md`、`acceptance.md`；证据少时可并入 `brief.md` 或 `decisions.md`。
+- apply 仍只能依据 Committed OpenSpec。
+- archive 仍要轻量回填 devflow，并询问是否归档 OpenSpec。
+
+micro 不适用于接口影响不清、跨团队消费者、迁移/回滚、复杂状态机、长期架构决策或需求边界不清的变更；遇到这些情况应升级为 standard 或 complex。
+
+## complex 增量
+
+complex 适用于高风险、跨模块、需求不清、多人协作或长期架构影响明显的变更。complex 是 standard 的加法。
+
+- 需要更完整的 Discover：增加需求澄清、证据查证、范围确认和风险接受。
+- checkpoint 内可补充关键内部阶段结果，但不要把内部阶段名当作用户操作入口。
+- 按需创建 `prd.md`、`research.md`、`alignment.md`、接口文档、ADR 或 compound knowledge。
+- 接口影响、迁移、灰度、回滚、兼容性和消费者边界必须显式记录。
+- audit 需要覆盖模块链路、数据所有权、生命周期、耦合风险和 ADR 冲突。
+- archive 在 standard 档案基础上按需提炼长期 design、research、tasks、ADR 和 compound knowledge。
@@ -124,7 +124,7 @@

 - 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
 - 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更
+- 分类：OpenSpec 不准 / 代码偏离 / 不确定

 ## 证据

@@ -136,7 +136,7 @@

 - 决策：
 - 是否需要用户确认：是 / 否
- OpenSpec 回写：不需要 / 已回写 / 待回写
+- OpenSpec 回写：不需要 / 已回写 / 待回写 / 等待用户确认
 - 代码处理：
 - 验证方式：
 ```
@@ -353,8 +353,8 @@ specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"
 | 上游 → 下游 | 检查内容 | 状态 |
 |---|---|---|
 | brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap |
-| proposal → design | 范围、约束、关键承诺是否进入 design | 已对齐 / 存在 gap |
-| design → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
+| proposal → 设计产物 | 范围、约束、关键承诺是否进入 design.md 或等价设计小节 | 已对齐 / 存在 gap |
+| 设计产物 → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
 | specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap |

 ### Gap 详情（如有）
@@ -10,3 +10,5 @@
 | 2026-05-19 | dev-flow-skill-evaluation | sm-flow | dev-flow, sm-flow, skill-evaluation, fallback, phase-contracts | 未关联 | accepted-unarchived |
 | 2026-05-21 | sm-flow-v3-1-upgrade | sm-flow | interface-impact, commit-gate, devflow-index, apply-conflict, skill-compatibility | `openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/` | archived |
 | 2026-05-22 | sm-flow-execution-hardening | sm-flow | execution-hardening, checklist, phase-gate, cross-artifact, question-pool | 未关联 | active |
+| 2026-07-05 | validate-sm-flow-explicit-trigger | sm-flow | explicit-trigger, scale-source, fallback, validation | `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/` | archived |
+| 2026-07-05 | validate-sm-flow-standard-change | sm-flow | standard-change, full-artifacts, evidence, validation | `openspec/archive/2026-07-05-validate-sm-flow-standard-change/` | archived |
@@ -0,0 +1,48 @@
+# Validate SM Flow Explicit Trigger Acceptance
+
+## Result
+
+Accepted and archived.
+
+## Static Validation
+
+- Trigger rule verification:
+  - `SKILL.md` frontmatter says sm-flow is only used for explicit `/sm-flow` commands or explicit natural-language requests.
+  - `SKILL.md` trigger section says task type alone must not auto-trigger sm-flow.
+  - `operating-rules.md` startup checks now include explicit natural-language requests.
+
+- Scale source verification:
+  - Scale definition scan found `standard`, `micro`, and `complex` definition headings and definition phrases only in `references/scales.md`.
+  - Other files refer to `references/scales.md` instead of redefining the scale rules.
+
+- Obsolete wording verification:
+  - No matches for minute/hour/second/timebox metrics.
+  - No matches for old skip semantics or old fixed `proposal.md + design.md` expression.
+  - No matches for old conflict wording targeted by this validation.
+
+## Script Validation
+
+- Passed: `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow`
+- Passed: reference integrity scan for `references/*.md`.
+
+## Browser Or Manual Validation
+
+- Not applicable. This change only modifies skill protocol text and validation records.
+
+## Unverified
+
+- Real external OpenSpec CLI integration was not executed because the current tool surface does not expose those child commands.
+- Forward-testing with an independent subagent was not run in this pass.
+
+## Fixed During Apply
+
+- Replaced remaining hard-coded `design.md` wording in phase/audit fallback rules where the protocol must respect scale-specific design artifacts.
+- Added explicit natural-language sm-flow requests to startup checks.
+
+## OpenSpec Archive
+
+- `.archive-ready` is present.
+- User confirmed archive.
+- Archived location: `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/`.
+- Status: `archived`.
+- Archive method: local filesystem archive following existing repository convention because external `openspec-archive-change` is not directly callable in the current tool surface.
@@ -0,0 +1,29 @@
+# Validate SM Flow Explicit Trigger Brief
+
+## Background
+
+`sm-flow` was simplified so it should only run on explicit user invocation. Related cleanup centralized scale rules, removed time-based metrics, and separated fallback/glossary details into references.
+
+## Goal
+
+Validate the current `sm-flow` design by running a real micro OpenSpec change through Discover, Commit, Apply, and Archive.
+
+## Scope
+
+- Validate `.agents/skills/sm-flow/SKILL.md`.
+- Validate `.agents/skills/sm-flow/references/*.md`.
+- Fix any protocol inconsistency found during validation.
+- Record fallback capability source because external OpenSpec commands are unavailable in the current tool surface.
+
+## Non-Goals
+
+- No business code changes.
+- No changes to the four visible checkpoints or nine internal phases.
+- No automatic trigger heuristics.
+- No historical archive rewrites.
+
+## Scale
+
+- Scale: `micro`.
+- Evidence is folded into `decisions.md`.
+- Linked OpenSpec change: `openspec/changes/validate-sm-flow-explicit-trigger/`.
@@ -0,0 +1,72 @@
+# Validate SM Flow Explicit Trigger Decisions
+
+## Capability Source
+
+- Discover: sm-flow built-in protocol.
+- Propose/specify/apply/archive: fallback protocol from `.agents/skills/sm-flow/references/fallbacks.md`.
+- Missing external capability: OpenSpec CLI and OpenSpec child skills are not directly callable from the current tool surface.
+- Impact: validation is file-based and static; it can verify current protocol text and artifacts but cannot exercise a real external OpenSpec command.
+- Remaining risk: future tool availability may require rechecking integration behavior.
+
+## Context
+
+- `devflow/index.md` contains related sm-flow history:
+  - `dev-flow-skill-evaluation`
+  - `sm-flow-v3-1-upgrade`
+  - `sm-flow-execution-hardening`
+- `devflow/glossary/CONTEXT.md` is project-level glossary and does not define sm-flow protocol terms.
+- Current validation change is new: `validate-sm-flow-explicit-trigger`.
+
+## Scale Decision
+
+- Scale: `micro`.
+- Reason: documentation/protocol validation only, no business code, no external interface contract change.
+- Interface impact: L1 internal documentation/protocol validation.
+- Micro constraints retained: proposal, specs, tasks, commit gate, apply verification, devflow archive, archive confirmation.
+
+## Question Pool
+
+| Question | Mode | Status | Result |
+| --- | --- | --- | --- |
+| Does top-level trigger text require explicit sm-flow invocation only? | evidence-driven | confirmed | `SKILL.md` frontmatter and trigger section both state explicit invocation only. |
+| Are scale definitions centralized in `references/scales.md`? | evidence-driven | confirmed | Scan for scale definition headings and definition phrases only matched `references/scales.md`. |
+| Are time/minute metrics absent from skill rules? | evidence-driven | confirmed | Obsolete time metric scan returned no matches. |
+| Does fallback usage remain explicit and recorded? | evidence-driven | confirmed | This file records fallback source, impact, and remaining risk. |
+| Is user confirmation needed for product scope? | user-interview | not required | User already requested this validation run; no unresolved product preference blocks this micro validation. |
+
+## Cross-Artifact Alignment
+
+| Link | Status | Notes |
+| --- | --- | --- |
+| brief/prd -> proposal | not applicable | Micro validation has no separate brief/prd before archive. |
+| proposal -> design artifact | aligned | Proposal contains inline micro design notes. |
+| design artifact -> specs | aligned | Specs cover explicit trigger, scale source, no time metrics, and fallback recording. |
+| specs -> tasks | aligned | Tasks include scans, validation, patching if needed, and archive handoff. |
+
+## Commit Gate
+
+- Passed.
+- Proposal explains why, what, scope, non-goals, inline design, and risks.
+- Specs describe observable validation behavior.
+- Tasks are executable and have validation evidence.
+- Cross-artifact alignment has no unresolved gap.
+- `.committed` created.
+
+## Apply Log
+
+- Validation found one consistency issue: `phase-contracts.md` still hard-coded `design.md` in specify/audit wording even though `scales.md` allows micro changes to use an equivalent inline design section.
+- Fix applied: changed those references to "设计产物" where the rule must respect the current scale.
+- Fix applied: `fallbacks.md` audit fallback now says to repair the design artifact instead of only `design.md`.
+- Fix applied: `operating-rules.md` startup checks now include explicit natural-language requests to use sm-flow.
+- Validation commands passed:
+  - `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow`
+  - reference integrity scan for `references/*.md`
+  - obsolete wording scan for time metrics, old skip semantics, old conflict wording, and fixed `design.md` expressions.
+  - scale definition duplication scan.
+
+## Archive Log
+
+- User confirmed OpenSpec archive.
+- External `openspec-archive-change` was not directly callable in the current tool surface.
+- Archived by moving the OpenSpec change to `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/`, matching existing repository archive convention.
+- `devflow/index.md` status updated to `archived`.
@@ -0,0 +1,33 @@
+# Validate SM Flow Standard Change Acceptance
+
+## Result
+
+Accepted and archived.
+
+## Static Validation
+
+- Scale rule centralization passed.
+- Obsolete wording scan passed.
+- Standard artifact completeness passed.
+- Cross-artifact alignment passed.
+
+## Script Validation
+
+- Passed: skill quick validation.
+- Passed: reference integrity scan.
+
+## Browser Or Manual Validation
+
+- Not applicable. This validation covers skill protocol files and OpenSpec/devflow records.
+
+## Unverified
+
+- External OpenSpec CLI integration.
+- Independent forward-testing by a separate agent.
+
+## OpenSpec Archive
+
+- User confirmed archive.
+- Archived location: `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`.
+- Status: `archived`.
+- Archive method: local filesystem archive following existing repository convention because external `openspec-archive-change` is not directly callable in the current tool surface.
@@ -0,0 +1,25 @@
+# Validate SM Flow Standard Change Brief
+
+## Background
+
+The micro validation confirmed the reduced path. This record validates the normal standard path, where independent design and separate evidence are required.
+
+## Goal
+
+Confirm that the current `sm-flow` skill supports a standard change with complete OpenSpec and devflow artifacts.
+
+## Scope
+
+- Validate standard artifact requirements.
+- Validate scale rule centralization.
+- Validate skill structure and reference integrity.
+
+## Non-Goals
+
+- No business code changes.
+- No archive move without user confirmation.
+- No complex migration, rollback, or cross-team interface test.
+
+## Linked OpenSpec
+
+`openspec/changes/validate-sm-flow-standard-change/`
@@ -0,0 +1,52 @@
+# Validate SM Flow Standard Change Decisions
+
+## Capability Source
+
+- This is an ordinary engineering validation, not an explicit sm-flow invocation.
+- External OpenSpec child commands are not directly callable in the current tool surface.
+- Validation uses file-based OpenSpec fixtures and static/script checks.
+
+## Scale Decision
+
+- Scale: `standard`.
+- Reason: this validation intentionally exercises the full normal artifact set: proposal, independent design, specs, tasks, and separate evidence.
+- Interface impact: L1 internal documentation/protocol validation.
+
+## Question Pool
+
+| Question | Mode | Status | Result |
+| --- | --- | --- | --- |
+| Does standard require independent `design.md`? | evidence-driven | confirmed | `references/scales.md` defines independent `design.md` for standard. |
+| Does standard require separate `evidence.md` in devflow? | evidence-driven | confirmed | `references/scales.md` defines `brief.md`, `evidence.md`, `decisions.md`, `acceptance.md`. |
+| Are standard scale definitions duplicated outside `scales.md`? | evidence-driven | confirmed | Scale definition scan matched complete scale definitions only in `references/scales.md`. |
+| Is user scope confirmation needed? | user-interview | not required | User asked to validate a regular change; no product scope choice is blocked. |
+
+## Cross-Artifact Alignment
+
+| Link | Status | Notes |
+| --- | --- | --- |
+| proposal -> design | aligned | Proposal asks for standard artifact validation; design defines standard artifact model. |
+| design -> specs | aligned | Specs require full OpenSpec artifacts, evidence archive, and centralized scale definitions. |
+| specs -> tasks | aligned | Tasks include fixture creation, validation scans, commit gate, and devflow records. |
+
+## Findings
+
+- Standard OpenSpec artifact completeness passed: `proposal.md`, independent `design.md`, spec file, and `tasks.md` exist.
+- Cross-artifact alignment passed: proposal -> design -> specs -> tasks.
+- Scale duplication scan passed.
+- Obsolete wording scan passed.
+- Skill quick validation passed.
+- Reference integrity scan passed.
+
+## Commit Gate
+
+- `.committed` created.
+- Status: committed standard validation fixture.
+
+## Archive Status
+
+- Devflow standard records created.
+- User confirmed OpenSpec archive.
+- External `openspec-archive-change` was not directly callable in the current tool surface.
+- Archived by moving the OpenSpec change to `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`, matching existing repository archive convention.
+- `devflow/index.md` status updated to `archived`.
@@ -0,0 +1,34 @@
+# Validate SM Flow Standard Change Evidence
+
+## Static Evidence
+
+- Scale definition scan found complete `standard / micro / complex` definition headings and definition phrases only in `.agents/skills/sm-flow/references/scales.md`.
+- Obsolete wording scan returned no matches for:
+  - minute/hour/second/timebox metrics
+  - old skip semantics
+  - old fixed `proposal.md + design.md` expression
+  - old conflict wording targeted by prior validation
+
+## Script Evidence
+
+- Passed: `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow`
+- Passed: `references/*.md` integrity scan.
+
+## Artifact Evidence
+
+- OpenSpec standard artifacts exist:
+  - `openspec/changes/validate-sm-flow-standard-change/proposal.md`
+  - `openspec/changes/validate-sm-flow-standard-change/design.md`
+  - `openspec/changes/validate-sm-flow-standard-change/specs/sm-flow-standard-change/spec.md`
+  - `openspec/changes/validate-sm-flow-standard-change/tasks.md`
+- Devflow standard artifacts exist:
+  - `brief.md`
+  - `evidence.md`
+  - `decisions.md`
+  - `acceptance.md`
+
+## Limits
+
+- This validation is static/file-based.
+- It does not run a real external OpenSpec CLI command.
+- It does not include independent subagent forward-testing.
@@ -0,0 +1 @@
+Devflow archive files are ready for validate-sm-flow-explicit-trigger.
@@ -0,0 +1 @@
+Committed OpenSpec for validate-sm-flow-explicit-trigger.
@@ -0,0 +1,44 @@
+# Validate SM Flow Explicit Trigger
+
+## Why
+
+Recent edits simplified `sm-flow` so it should only run when the user explicitly invokes it. The same cleanup also centralized scale rules in `references/scales.md`, removed time-based metrics, and split fallback/glossary concepts out of the top-level skill.
+
+This change validates those protocol decisions through a real micro `sm-flow` run instead of another informal review.
+
+## What Changes
+
+- Verify `sm-flow` only triggers on `/sm-flow`, `/sm-flow explore`, `/sm-flow apply`, `/sm-flow archive`, or an explicit natural-language request to use sm-flow.
+- Verify task type alone does not trigger `sm-flow`, even when the task mentions OpenSpec, devflow, cross-module work, or clarification.
+- Verify `micro / standard / complex` definitions live only in `references/scales.md`.
+- Verify the skill has no time/minute-based metrics.
+- Verify fallback usage is recorded when external OpenSpec capabilities are unavailable.
+
+## Design Notes
+
+- Scale: `micro`.
+- Interface impact: L1 internal documentation/protocol validation only.
+- No business code changes.
+- Independent `design.md` is intentionally omitted; this section is the micro design artifact.
+- OpenSpec CLI and external OpenSpec child skills are not directly callable in the current tool surface, so this run uses `references/fallbacks.md` and records that capability source in devflow.
+
+## Scope
+
+In scope:
+
+- `.agents/skills/sm-flow/SKILL.md`
+- `.agents/skills/sm-flow/references/*.md`
+- Validation OpenSpec and devflow records for this change
+
+Out of scope:
+
+- Business code
+- Rewriting historical OpenSpec archives
+- Changing the four visible checkpoints or nine internal phases
+- Adding automatic trigger heuristics
+
+## Risks
+
+- A future edit may duplicate scale rules outside `references/scales.md`.
+- The frontmatter description may drift from the top-level trigger rule.
+- Validation can prove current text consistency, but cannot force future agents to obey it without continued review.
@@ -0,0 +1,53 @@
+# sm-flow Explicit Trigger Spec
+
+## ADDED Requirements
+
+### Requirement: Explicit Trigger Only
+
+`sm-flow` SHALL be used only when the user explicitly invokes `/sm-flow`, `/sm-flow explore`, `/sm-flow apply`, `/sm-flow archive`, or clearly asks to use the sm-flow process in natural language.
+
+#### Scenario: Plain engineering request
+
+- **Given** a user asks for an engineering task that mentions OpenSpec, devflow, cross-module work, or clarification
+- **When** the user does not explicitly request sm-flow
+- **Then** the agent handles the task as ordinary engineering work
+- **And** the agent does not auto-trigger sm-flow based on task type
+
+#### Scenario: Explicit sm-flow request
+
+- **Given** a user invokes `/sm-flow` or clearly asks to use sm-flow
+- **When** the agent starts the process
+- **Then** the agent follows the visible checkpoints Discover, Commit, Apply, and Archive
+- **And** the internal phase order remains clarify, context, propose, grill, specify, audit, commit, apply, archive
+
+### Requirement: Scale Rules Have One Source
+
+The `micro / standard / complex` scale definitions SHALL be defined in `references/scales.md`; other files may only reference that file instead of redefining scale details.
+
+#### Scenario: Scale guidance is needed
+
+- **Given** a phase needs to choose or enforce a scale
+- **When** the rule is read
+- **Then** it points to `references/scales.md`
+- **And** no other reference file carries a competing full definition of the three scales
+
+### Requirement: No Time-Based Skill Metrics
+
+The skill SHALL NOT use minute, hour, second, or timebox metrics to define scale, effort, or validation thresholds.
+
+#### Scenario: Protocol text is scanned
+
+- **Given** the sm-flow skill files are scanned
+- **When** obsolete time metrics are searched
+- **Then** no matching scale or effort rule remains
+
+### Requirement: Fallback Capability Is Explicit
+
+When OpenSpec CLI or child skill capabilities are unavailable, `sm-flow` SHALL use `references/fallbacks.md` only as an explicit fallback and record the capability source in the current devflow process log.
+
+#### Scenario: External capability unavailable
+
+- **Given** OpenSpec child skills are not directly callable
+- **When** a change is still executed
+- **Then** the decisions log records fallback source, impact, and remaining risk
+- **And** the fallback does not skip context, grill, commit, apply, or archive gates
@@ -0,0 +1,26 @@
+# Tasks
+
+## 1. Discover
+
+- [x] 1.1 Read current `sm-flow` top-level trigger rule and relevant references.
+- [x] 1.2 Read `devflow/index.md` and glossary context for related history.
+- [x] 1.3 Classify this validation as `micro` and record capability fallback.
+
+## 2. Commit
+
+- [x] 2.1 Create micro OpenSpec proposal with inline design notes.
+- [x] 2.2 Create specs that express the observable validation expectations.
+- [x] 2.3 Create executable validation tasks.
+- [x] 2.4 Run cross-artifact alignment and create `.committed`.
+
+## 3. Apply
+
+- [x] 3.1 Scan `sm-flow` files for obsolete trigger, scale, time metric, and fallback wording.
+- [x] 3.2 Patch any discovered inconsistency in the skill files.
+- [x] 3.3 Run skill validation and reference integrity checks.
+
+## 4. Archive
+
+- [x] 4.1 Create micro devflow archive files.
+- [x] 4.2 Update `devflow/index.md`.
+- [x] 4.3 Create `.archive-ready` and ask whether to archive OpenSpec.
@@ -0,0 +1 @@
+Devflow archive files are ready for validate-sm-flow-standard-change.
@@ -0,0 +1 @@
+Committed OpenSpec for validate-sm-flow-standard-change.
@@ -0,0 +1,35 @@
+# Design
+
+## Scale
+
+Scale: `standard`.
+
+Rationale: this validation has a clear target and no business-code risk, but it intentionally exercises the full normal artifact set rather than the reduced micro path.
+
+## Interface Impact
+
+Interface impact: L1 internal documentation/protocol validation.
+
+No API, DTO, database, event, service, or cross-module runtime contract changes are expected.
+
+## Artifact Model
+
+Standard validation requires:
+
+- OpenSpec: `proposal.md`, independent `design.md`, `specs/`, `tasks.md`.
+- Devflow archive: `brief.md`, `evidence.md`, `decisions.md`, `acceptance.md`.
+
+The validation checks that current skill rules point to `references/scales.md` for the exact standard artifact requirements instead of redefining them elsewhere.
+
+## Execution Design
+
+1. Build the standard OpenSpec fixture.
+2. Run static scans for standard artifact wording and duplicated scale definitions.
+3. Run skill validation and reference integrity checks.
+4. Record evidence separately in `devflow/.../evidence.md`.
+5. Mark the fixture as committed only if artifact completeness and alignment pass.
+
+## Risks
+
+- The external OpenSpec archive/apply commands are not exposed in the current tool surface; this validation uses file-based checks.
+- File presence does not prove independent-agent usability; forward-testing remains a separate optional validation surface.
@@ -0,0 +1,39 @@
+# Validate SM Flow Standard Change
+
+## Why
+
+The previous validation covered a micro change. A standard change has stricter expectations: an independent `design.md`, complete OpenSpec artifacts, and a separate `evidence.md` in devflow.
+
+This validation checks whether the current `sm-flow` skill can still describe and validate a normal standard change after the recent simplification work.
+
+## What Changes
+
+- Create a standard-scale validation fixture for `sm-flow`.
+- Verify standard OpenSpec artifacts exist and are aligned: `proposal.md`, `design.md`, `specs/`, and `tasks.md`.
+- Verify standard devflow archive artifacts exist: `brief.md`, `evidence.md`, `decisions.md`, and `acceptance.md`.
+- Verify standard still uses the same four visible checkpoints and nine internal phases without exposing phase names as user commands.
+
+## Scope
+
+In scope:
+
+- Standard-scale validation records.
+- Static checks over `.agents/skills/sm-flow`.
+- Narrow fixes to the skill if standard validation reveals inconsistency.
+
+Out of scope:
+
+- Business code changes.
+- Reworking archived historical changes.
+- Changing the current trigger policy.
+
+## Non-Goals
+
+- This change does not test a complex migration, rollback, or cross-team interface change.
+- This change does not require independent browser/manual validation.
+- This change does not replace the micro validation already archived.
+
+## Risks
+
+- A standard validation fixture can become noise if left unarchived; status must be explicit.
+- If standard rules are only validated by file presence, semantic drift may still require future forward-testing.
@@ -0,0 +1,36 @@
+# sm-flow Standard Change Spec
+
+## ADDED Requirements
+
+### Requirement: Standard Change Has Full OpenSpec Artifacts
+
+A standard `sm-flow` change SHALL have `proposal.md`, independent `design.md`, `specs/`, and `tasks.md`.
+
+#### Scenario: Standard fixture is committed
+
+- **Given** a change is classified as `standard`
+- **When** commit validation runs
+- **Then** `proposal.md`, `design.md`, at least one spec file, and `tasks.md` exist
+- **And** the artifacts are aligned from proposal to design to specs to tasks
+
+### Requirement: Standard Archive Has Evidence
+
+A standard `sm-flow` archive SHALL include `brief.md`, `evidence.md`, `decisions.md`, and `acceptance.md` in devflow.
+
+#### Scenario: Standard fixture is archived or accepted
+
+- **Given** a standard validation change has completed apply checks
+- **When** devflow records are written
+- **Then** `evidence.md` exists as a separate file
+- **And** it records the static and script validation evidence used for acceptance
+
+### Requirement: Scale Definitions Remain Centralized
+
+Standard-specific artifact requirements SHALL be defined by `references/scales.md`; other files may reference those requirements but not carry a competing full definition.
+
+#### Scenario: Standard wording is scanned
+
+- **Given** sm-flow references mention standard behavior
+- **When** scale definition phrases are scanned
+- **Then** complete standard definitions appear only in `references/scales.md`
+- **And** operational files defer to the current scale rather than hard-coding alternative standard rules
@@ -0,0 +1,29 @@
+# Tasks
+
+## 1. Standard OpenSpec Fixture
+
+- [x] 1.1 Create `proposal.md`.
+- [x] 1.2 Create independent `design.md`.
+- [x] 1.3 Create at least one spec under `specs/`.
+- [x] 1.4 Create `tasks.md`.
+
+## 2. Standard Validation
+
+- [x] 2.1 Run scale duplication scan.
+- [x] 2.2 Run obsolete wording scan.
+- [x] 2.3 Run skill quick validation.
+- [x] 2.4 Run reference integrity scan.
+
+## 3. Commit Gate
+
+- [x] 3.1 Confirm OpenSpec artifact completeness.
+- [x] 3.2 Confirm proposal -> design -> specs -> tasks alignment.
+- [x] 3.3 Create `.committed`.
+
+## 4. Devflow Records
+
+- [x] 4.1 Create `brief.md`.
+- [x] 4.2 Create separate `evidence.md`.
+- [x] 4.3 Create `decisions.md`.
+- [x] 4.4 Create `acceptance.md`.
+- [x] 4.5 Update `devflow/index.md`.
@@ -0,0 +1,216 @@
+# SM Flow Phase Contracts v4.1 更新日志
+
+> 更新日期: 2026-06-23  
+> 更新原因: 基于"山东商客意向单同步接口"执行复盘  
+> 更新方案: 方案 B（简化版）
+
+---
+
+## 更新概览
+
+**核心目标**: 减少 apply 阶段的返工次数（从 4-5 次降低到 0-1 次）
+
+**更新范围**:
+- ✅ grill 阶段：增加技术实现维度
+- ✅ apply 阶段：增加 Pre-apply Checkpoint
+
+**文本增量**: +55 行（从 281 行 → 336 行，+20%）
+
+---
+
+## 详细修改
+
+### 1. grill 阶段 — 增加技术实现维度
+
+**修改位置**: `phase-contracts.md` 第 85-88 行
+
+**新增内容**:
+```markdown
+- **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
+  - 参考实现的具体文件路径是什么？
+  - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
+  - 有哪些技术点需要先调研或新建？
+```
+
+**目的**: 在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
+
+---
+
+### 2. apply 阶段 — 增加 Pre-apply Checkpoint
+
+**修改位置**: `phase-contracts.md` 第 234-265 行
+
+**新增章节**: Pre-apply Checkpoint（15-20 分钟）
+
+#### 触发条件（3 条）
+- design 或 tasks 中提到"参考 XXX 实现"
+- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
+- 技术栈不熟悉或第一次在该项目实现类似功能
+
+#### 执行步骤（3 步）
+1. **完整阅读所有参考实现**（约 10 分钟）
+   - 从 OpenSpec design 或 tasks 中定位参考实现文件
+   - 如果路径不明确，通过 Grep 搜索关键类名或模式
+   - 逐行理解关键逻辑，提取可复用代码片段和模式
+
+2. **Grep 关键技术栈**（约 5 分钟）
+   - 请求/响应结构模式
+   - 消息队列模式
+   - 统一工具类
+   - 异常处理和日志记录标准
+
+3. **形成技术栈清单并写入 decisions.md**
+   - 项目使用的请求/响应结构标准
+   - MQ 消息定义和发送标准
+   - Consumer 标准位置和写法
+   - 加密/验签/工具类的标准用法
+   - 识别需要新建的工具类或基础设施
+
+#### 输出要求（3 条）
+- ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
+- ✅ 已列出所有参考实现的文件路径
+- ✅ 已识别需要新建的工具类/基础设施
+
+#### 快速模式支持
+- micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单
+
+---
+
+### 3. apply 阶段 — 实现过程增强
+
+**修改位置**: `phase-contracts.md` 第 267-284 行
+
+**新增要求**:
+- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序
+- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能不允许空实现或纯 TODO 注释
+- **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报
+
+---
+
+### 4. apply 阶段 — 退出条件增强
+
+**修改位置**: `phase-contracts.md` 第 286-292 行
+
+**新增退出条件**:
+- ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
+- ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
+
+---
+
+## 简化对比
+
+### 与完整方案对比
+
+| 维度 | 完整方案 | 简化方案 B | 差异 |
+|------|----------|-----------|------|
+| 文本增量 | +100 行 | +55 行 | -45% |
+| 子阶段数 | 3 个（Phase 1/2/3） | 1 个（Pre-apply Checkpoint） | -67% |
+| 强制规则 | 9 条 | 5 条 | -44% |
+| 检查清单 | 2 个详细清单 | 1 个简化清单 | -50% |
+| 时间分档 | 3 档（15/20/30 分钟） | 1 档（15-20 分钟） | -67% |
+
+### 保留核心价值
+
+✅ **保留**（解决返工问题）:
+- 前置调研（最重要）
+- 技术栈清单（防止想当然）
+- 核心功能不能空实现（保证质量）
+- 快速失败机制
+
+❌ **简化**（去掉过度约束）:
+- 严格的执行顺序
+- 频繁的检查点
+- 详细的操作指南模板
+
+---
+
+## 预期效果
+
+### 量化指标
+
+| 指标 | 当前 | 目标 | 改善 |
+|------|------|------|------|
+| 返工次数 | 4-5 次 | 0-1 次 | -80% |
+| 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% |
+| 实现时间（含返工） | 2 小时 | 1.5 小时 | -25% |
+| 前置调研时间 | 0 分钟 | 15-20 分钟 | +20 分钟 |
+
+### ROI 分析
+
+```
+投入: 15-20 分钟调研
+回报: 节省 60 分钟返工 + 避免核心功能遗漏
+ROI = (60 - 20) / 20 = 200%
+```
+
+---
+
+## 适用场景
+
+### ✅ 强烈推荐
+
+- 中等及以上规模需求（3+ 接口或涉及多模块）
+- 涉及项目现有基础设施（MQ/统一请求结构/工具类）
+- 第一次在该项目实现类似功能
+- 设计文档提到"参考 XXX 实现"
+
+### 🟡 可选执行
+
+- micro 分档的简单需求（可缩短为 5-10 分钟）
+- 纯数据处理或工具脚本（技术栈熟悉）
+
+### ❌ 不推荐
+
+- 紧急热修复（时间紧急）
+- 一次性脚本（不涉及项目标准）
+
+---
+
+## 后续优化方向
+
+### 短期（1-2 个需求后）
+
+- 收集数据：实际调研时间、返工次数、遗漏率
+- 验证效果：是否达到预期 ROI
+- 调整参数：时间要求、触发条件
+
+### 中期（观察 5+ 个需求后）
+
+如果效果显著，考虑升级为完整方案：
+- 增加 Alignment Checkpoint（每模块对齐检查）
+- 增加详细的技术栈清单模板
+- 增加分步实现的每步验证要求
+
+### 长期（跨项目验证后）
+
+- 提取通用技术栈清单模板（Java/Go/Python 等）
+- 建立参考实现库（常见模式的最佳实践）
+- 自动化部分调研步骤（Grep 脚本、清单生成）
+
+---
+
+## 实施检查清单
+
+### 立即验证
+
+- [ ] `phase-contracts.md` 文件已更新
+- [ ] grill 阶段增加了技术实现维度
+- [ ] apply 阶段增加了 Pre-apply Checkpoint
+- [ ] apply 退出条件增加了 2 条新检查
+- [ ] 文件语法无误，可以正常解析
+
+### 下次执行验证
+
+- [ ] agent 是否正确识别触发条件
+- [ ] agent 是否执行了完整的 3 步调研
+- [ ] 技术栈清单是否写入 decisions.md
+- [ ] 是否有效减少了返工次数
+- [ ] 核心功能是否避免了空实现
+
+---
+
+## 附录：复盘案例链接
+
+- 原始复盘文档: `skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
+- 修改前版本: phase-contracts.md (commit: 待补充)
+- 修改后版本: phase-contracts.md (commit: 待补充)
@@ -0,0 +1,307 @@
+# SM Flow Phase Contracts v4.2 更新日志
+
+> 更新日期: 2026-06-24  
+> 更新原因: 基于"lookup-knowledge-integration"执行复盘  
+> 更新方案: 增强执行机制，引入可验证 checkpoint
+
+---
+
+## 更新概览
+
+**核心目标**: 解决"约束是软性的"问题，增加可执行的检查机制
+
+**更新范围**:
+- ✅ commit 阶段：增加文件完整性和一致性检查清单
+- ✅ apply 阶段：增加前置门控（.committed 文件检查）
+- ✅ archive 阶段：增加强制执行顺序（5 步 checklist）
+
+**文本增量**: +80 行
+
+---
+
+## 核心问题诊断
+
+### 问题根源：约束是"软性"的，缺少执行机制
+
+| 问题 | 现象 | 影响 | 根本原因 |
+|------|------|------|----------|
+| **Commit 检查缺标准** | 不知道如何判断"通过 commit 检查" | agent 跳过 commit 直接进入 apply | 只说"检查是否可执行"，没说具体检查什么 |
+| **Apply 缺前置门控** | 用户说"修复"就直接开始实现 | 可能基于不完整的 OpenSpec | 进入条件是软性描述，没有文件检查 |
+| **Archive 无 Checklist** | 先创建 handoff，忘记 devflow | 归档流程不完整 | 没有强制执行顺序 |
+
+---
+
+## 详细修改
+
+### 1. Commit 阶段 — 增加可验证 Checkpoint
+
+**修改位置**: `phase-contracts.md` 第 208-221 行
+
+**新增内容**:
+
+#### 文件完整性检查（必须全部通过）
+
+- [ ] `proposal.md` 存在，包含问题描述（至少 50 字）、建议方案（至少 100 字）、范围/非目标
+- [ ] `design.md` 存在，包含架构设计（文字或图）、数据结构定义（至少 1 个）、关键决策记录（至少 2 条）
+- [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
+- [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准
+
+#### 一致性检查（必须通过）
+
+- [ ] proposal 中的核心概念在 design 中有对应设计
+- [ ] design 中的关键决策在 tasks 中有对应实现任务
+- [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
+
+#### 标记文件
+
+检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
+
+**目的**: 
+- 提供明确的"可执行状态"判断标准
+- 强制 agent 完成所有检查项
+- 通过 `.committed` 文件提供下游门控依据
+
+---
+
+### 2. Apply 阶段 — 增加前置门控检查
+
+**修改位置**: `phase-contracts.md` 第 233-244 行
+
+**新增内容**:
+
+#### 前置门控检查（硬约束）
+
+1. 检查 `openspec/changes/{slug}/.committed` 文件是否存在
+2. 如不存在，执行以下流程：
+   - 汇报：Draft OpenSpec 未通过 commit 检查
+   - 列出缺失的 checkpoint 项（文件完整性、一致性检查）
+   - 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
+
+**目的**:
+- 强制 apply 依赖 Committed OpenSpec
+- 阻止基于不完整 OpenSpec 的实现
+- 提供补救路径（补做 commit 或显式跳过）
+
+---
+
+### 3. Archive 阶段 — 增加强制执行顺序
+
+**修改位置**: `archive-rules.md` 第 5-41 行
+
+**新增章节**: Archive 强制执行顺序
+
+#### Step 1: 创建 devflow 档案（必需）
+
+- [ ] 创建 `brief.md`（从 proposal.md 提取）
+- [ ] 创建 `evidence.md`（从 decisions.md 提取）
+- [ ] 创建 `decisions.md`（整理为最终版）
+- [ ] 创建 `acceptance.md`（记录验证情况）
+
+#### Step 2: 更新索引（必需）
+
+- [ ] 在 `devflow/index.md` 末尾追加或更新一行
+
+#### Step 3: 标记 OpenSpec（必需）
+
+- [ ] 创建 `openspec/changes/{slug}/.archive-ready` 文件
+
+#### Step 4: 向用户汇报（必需）
+
+- [ ] 列出创建的 devflow 档案文件路径（验证文件实际存在）
+- [ ] 汇报验证情况（按类型分类）
+- [ ] 列出剩余风险
+- [ ] 询问：**是否现在归档 OpenSpec？**
+
+#### Step 5: 用户确认后执行 OpenSpec Archive（可选）
+
+- [ ] 调用 `openspec-archive-change`
+- [ ] 记录 archive 结果
+
+**自检**: 在执行 Step 4 前，检查 Step 1-3 是否都完成。
+
+**目的**:
+- 强制 devflow 档案优先（不再先创建 handoff）
+- 提供明确的执行顺序，避免遗漏
+- 通过 `.archive-ready` 文件标记完成状态
+
+---
+
+## 新增门控文件
+
+| 文件 | 创建时机 | 用途 |
+|------|----------|------|
+| `.committed` | commit 阶段退出时 | apply 阶段前置门控 |
+| `.archive-ready` | archive Step 3 | 标记归档准备就绪 |
+
+---
+
+## 预期效果
+
+### 量化指标
+
+| 指标 | v4.1 | v4.2 目标 | 改善 |
+|------|------|-----------|------|
+| Commit 阶段跳过率 | 高（无明确标准） | 0%（有 checklist） | -100% |
+| Apply 基于不完整 OpenSpec | 可能发生 | 0%（门控阻止） | -100% |
+| Archive 遗漏 devflow | 可能发生 | 0%（强制顺序） | -100% |
+
+### 质量提升
+
+**Commit 阶段**:
+- ✅ 明确什么叫"可执行状态"
+- ✅ agent 无法跳过检查清单
+- ✅ 提供 `.committed` 文件作为凭证
+
+**Apply 阶段**:
+- ✅ 强制检查 `.committed` 文件存在
+- ✅ 阻止基于不完整 OpenSpec 的实现
+- ✅ 提供补救路径
+
+**Archive 阶段**:
+- ✅ 强制 devflow 优先（不再先创建 handoff）
+- ✅ 5 步 checklist 避免遗漏
+- ✅ 自检机制确保完整性
+
+---
+
+## 与 v4.1 的关系
+
+| 版本 | 核心改进 | 解决问题 |
+|------|----------|----------|
+| v4.1 | Pre-apply Research Checkpoint | apply 阶段前置调研不足，导致返工 |
+| v4.2 | 可验证 Checkpoint + 门控文件 | 约束是软性的，agent 容易跳过阶段 |
+
+**互补关系**:
+- v4.1 解决"调研不充分导致返工"
+- v4.2 解决"缺少执行机制导致跳过阶段"
+
+---
+
+## 设计原则
+
+### 1. 可验证性
+
+**Before**: "检查 OpenSpec 是否可执行"（模糊）  
+**After**: "proposal ≥50字、design ≥1个数据结构、specs ≥3个 requirement"（具体）
+
+### 2. 门控文件
+
+**Before**: 软性描述"已通过 commit"  
+**After**: 硬性检查 `.committed` 文件存在
+
+### 3. 强制顺序
+
+**Before**: 建议性"应该先 devflow 后 handoff"  
+**After**: 5 步 checklist，不得跳过或重排
+
+---
+
+## 复杂度评估
+
+**本次修改复杂度**: 低-中等
+- 文本增量: +80 行（phase-contracts.md +40 行，archive-rules.md +40 行）
+- 概念增加: 2 个门控文件（.committed, .archive-ready）
+- 规则增强: 3 个阶段的检查清单
+
+**整体复杂度**: 高（但更可靠）
+- 总行数: ~700 行 → ~780 行（+11%）
+- 门控数: 6 个 → 8 个（+commit 文件完整性 + apply 前置门控）
+- 强制清单: +3 个（commit 文件完整性、commit 一致性、archive 5 步）
+
+**权衡**:
+- ✅ 收益: 彻底解决"跳过阶段"问题
+- ⚠️ 成本: 增加 80 行文本，agent 需检查更多项
+
+---
+
+## 适用场景
+
+### ✅ 所有场景（无例外）
+
+v4.2 的改进是**执行机制**层面的，不涉及业务逻辑：
+- 无论 micro/standard/complex，都需要 commit 检查
+- 无论需求大小，都需要 apply 前置门控
+- 无论项目规模，都需要 archive 强制顺序
+
+### 快速模式
+
+快速模式可以简化产物（如 tasks 只需 3 个子任务），但**不能跳过门控**：
+- ✅ 仍需 commit 检查（即使 tasks 数量少）
+- ✅ 仍需 apply 前置门控
+- ✅ 仍需 archive 强制顺序
+
+---
+
+## 实施验证
+
+### 验证计划
+
+下次完整执行 sm-flow 时，检查：
+
+1. **Commit 阶段**:
+   - [ ] agent 是否执行了文件完整性检查？
+   - [ ] agent 是否执行了一致性检查？
+   - [ ] agent 是否创建了 `.committed` 文件？
+
+2. **Apply 阶段**:
+   - [ ] agent 是否检查了 `.committed` 文件存在？
+   - [ ] 如不存在，agent 是否汇报并询问用户？
+
+3. **Archive 阶段**:
+   - [ ] agent 是否按 5 步顺序执行？
+   - [ ] agent 是否在 Step 4 前自检了 Step 1-3？
+   - [ ] agent 是否创建了 `.archive-ready` 文件？
+
+### 成功标准
+
+- ✅ 无未经检查的 commit → apply 跳转
+- ✅ 无基于不完整 OpenSpec 的实现
+- ✅ 无先创建 handoff 后补 devflow 的情况
+
+---
+
+## 后续演进方向
+
+### v5.0 候选特性（观察 3+ 次执行后决定）
+
+如果 v4.2 执行良好，但仍有问题，考虑：
+
+1. **流程状态文件** `.sm-flow-state`
+   - 记录当前阶段、已完成阶段、时间戳
+   - 支持断点续做
+
+2. **更多门控文件**
+   - `.context-done`（context 阶段完成）
+   - `.grill-done`（grill 阶段完成）
+   - `.apply-done`（apply 阶段完成）
+
+3. **违规自检机制**
+   - 每个阶段退出前，自动检查是否违反 6 条硬约束
+
+4. **进度可视化**
+   - 每次开始时，汇报进度条（9 个阶段的完成情况）
+
+**判断依据**: 如果 v4.2 后仍频繁出现跳过阶段，再引入更重的机制。
+
+---
+
+## 相关文档
+
+- 执行复盘: `skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`
+- 修改文件: 
+  - `.agents/skills/sm-flow/references/phase-contracts.md`
+  - `.agents/skills/sm-flow/references/archive-rules.md`
+
+---
+
+## 总结
+
+**v4.2 的核心理念**: 把"软性约束"变成"硬性检查"
+
+| 改进点 | Before | After |
+|--------|--------|-------|
+| Commit 标准 | "可执行状态"（模糊） | 文件完整性 + 一致性检查清单 |
+| Apply 门控 | "已通过 commit"（软性） | 检查 `.committed` 文件存在（硬性） |
+| Archive 顺序 | "应该先 devflow"（建议） | 5 步强制顺序 + 自检 |
+
+**预期效果**: 彻底解决"agent 跳过阶段"问题，提升流程可靠性。
@@ -0,0 +1,293 @@
+# SM Flow 执行复盘 - 山东商客意向单同步接口
+
+> 项目: yingke-platform  
+> 需求: 385 山东公司商机信息同步接口  
+> 执行日期: 2026-06-23  
+> 复盘人: Claude Code
+
+---
+
+## 执行概况
+
+- **需求规模**: 中等（3个接口 + Kafka消费 + 数据库变更）
+- **总耗时**: 约 2 小时（含多次返工）
+- **返工次数**: 4-5 次重大返工
+- **最终状态**: 核心代码完成，但验签/解密/查询接口未实现
+
+---
+
+## 发现的问题
+
+### 1. 前置调研不足，导致多次返工
+
+#### 问题表现
+
+| 返工点 | 初次实现（错误） | 返工后（正确） | 浪费时间 |
+|--------|------------------|----------------|----------|
+| RequestMsg 结构 | 自创 `SyncIntentOrderReq/Resp` | 使用项目标准 `RequestMsg<T>` | 15 分钟 |
+| Kafka 发送方式 | `SendMessageTunnel` + `TaskTypeEnum` | `ykMqTemplate` + `@YkMsg` | 20 分钟 |
+| Consumer 模块位置 | order-service 模块 | web 模块（参考案例位置） | 10 分钟 |
+| 透传字段结构 | Map → DTO → 最终平铺 | 应一次到位平铺到 Msg | 15 分钟 |
+
+**根本原因**: apply 阶段直接开始写代码，没有充分调研现有代码模式。
+
+#### 改进建议
+
+**在 apply 阶段前增加强制调研步骤**（pre-apply research checkpoint）：
+
+1. **阅读所有参考实现**（设计文档中明确提到的）
+   - 完整阅读参考代码，而不是凭想象
+   - 提取关键模式：请求结构、Kafka 使用、模块划分
+   
+2. **Grep 关键技术栈**
+   ```bash
+   grep -r "@YkMsg" --include="*.java"
+   grep -r "ykMqTemplate" --include="*.java"
+   grep -r "RequestMsg<" --include="*.java"
+   ```
+   
+3. **形成"技术栈清单"文档**（临时产物）
+   ```markdown
+   - 项目使用 RequestMsg<T> 作为统一请求包装
+   - Kafka 消息使用 @YkMsg + MsgData + ykMqTemplate.sendAsync()
+   - Consumer 统一放在 web 模块的 manager/stream/consumer
+   ```
+
+4. **调研时间要求**: 不少于 15 分钟，复杂需求可延长至 30 分钟
+
+---
+
+### 2. 设计文档与实现偏离，缺少一致性检查
+
+#### 问题表现
+
+| 设计文档要求 | 实际实现 | 偏离程度 |
+|--------------|----------|----------|
+| Controller 层 SM3 验签 | 只有 TODO 注释 | ❌ 核心功能缺失 |
+| Service 层 AES256-GCM 解密 | 只有 TODO 注释 | ❌ 核心功能缺失 |
+| queryIntentOrder 调用一体化客服 | 空实现 | ❌ 核心功能缺失 |
+| syncIntentOrder 同步调用 | 改为 Kafka 异步 | ⚠️ 架构差异（可能合理） |
+
+**根本原因**: apply 阶段没有"设计-实现对齐检查点"。
+
+#### 改进建议
+
+**在 apply 阶段中增加对齐检查点**（alignment checkpoint）：
+
+1. **每完成 1 个接口/模块，立即对比设计文档**
+   - 逐条核对设计文档的任务清单
+   - 标记"已完成/部分完成/TODO"
+   
+2. **核心功能不允许"TODO 占位"直接通过**
+   - 加密/解密、验签、核心业务逻辑必须实现或明确标注"待联调"
+   - 区分"框架完整但待联调"（✅） vs "空实现"（❌）
+
+3. **架构差异必须显式记录并询问用户**
+   - 设计说同步，实现改异步 → 必须记录原因并确认
+   - 创建 `decisions.md` 记录所有偏离设计的架构决策
+
+---
+
+### 3. 分步验证不足，一次写太多代码
+
+#### 问题表现
+
+- 一次性写完 Controller + Service + Kafka + Consumer，然后发现 RequestMsg 结构错了
+- 没有"写一点 → 编译 → 确认方向"的小步迭代
+
+#### 改进建议
+
+**强制分步验证**（incremental validation）：
+
+1. **Controller 层先行**
+   - 只写 Controller + 最小 Service 骨架
+   - 确认请求/响应结构正确
+   - 编译通过后再继续
+
+2. **Kafka 发送独立验证**
+   - 写完发送逻辑，先打印 JSON 确认消息格式
+   - 再写 Consumer
+
+3. **Consumer 最后实现**
+   - 基于已确认的消息格式实现
+
+---
+
+### 4. 参考案例利用不充分
+
+#### 问题表现
+
+- 设计文档明确提到"参考 AddIntentOrderOutSystemDealTunnel"
+- 但实际执行时，直到用户提醒才去看参考实现
+- 之前都在凭想象写，导致返工
+
+#### 改进建议
+
+**强制参考案例优先**（reference-first approach）：
+
+1. **grill 阶段就应该找出所有参考案例**
+   - 不要只记录"参考 XXX"，而是实际阅读并提取模式
+   
+2. **apply 前必须完整阅读参考实现**
+   - 不是"扫一眼"，而是逐行理解关键逻辑
+   - 提取可复用的代码片段
+
+3. **参考案例模式提取清单**（临时文档）
+   ```markdown
+   ## AddIntentOrderOutSystemDealTunnel 关键模式
+   
+   1. Consumer 方法签名: `public void onXXX(XXXMsg msgBO)`
+   2. 调用链: msg → AES加密 → OnlineOpportunityApi → 回填状态
+   3. 异常处理: try-catch → updateStatus(EXCEPTION) → throw
+   4. 成功判断: isSyncSuccess() 三层校验
+   ```
+
+---
+
+### 5. grill 阶段澄清不够深入
+
+#### 问题表现
+
+- grill 阶段问了业务问题（省份校验、透传字段），但没有问技术实现问题
+- 导致后续实现时才发现技术栈不熟悉
+
+#### 改进建议
+
+**grill 阶段增加技术实现澄清**：
+
+除了业务澄清，还应该包括：
+
+1. **技术栈确认问题**
+   - "项目现有的 Kafka 消息怎么定义和发送？"
+   - "RequestMsg/ResponseMsg 的标准用法是什么？"
+   - "类似接口的 Controller/Service 是怎么写的？"
+
+2. **参考实现确认**
+   - "设计文档提到的参考实现是哪些文件？"
+   - "这些参考实现的核心模式是什么？"
+
+3. **技术风险识别**
+   - "有哪些技术点我不熟悉，需要先调研？"
+
+---
+
+## 改造建议汇总
+
+### 方案 A: 在现有 9 阶段中增强（保守）
+
+```
+clarify → context → propose → grill+ → specify → audit → commit → pre-apply+ → apply+ → archive
+                                  ↑                                      ↑        ↑
+                           增加技术澄清                             增加调研  增加检查点
+```
+
+**修改点**：
+
+1. **grill 阶段**：增加技术实现澄清问题模板
+2. **apply 阶段前**：增加 pre-apply research checkpoint（15-30分钟）
+3. **apply 阶段中**：增加 alignment checkpoint（每完成1个模块对比设计文档）
+
+### 方案 B: 新增独立调研阶段（激进）
+
+```
+clarify → context → propose → grill → research → specify → audit → commit → apply → archive
+                                                    ↑
+                                          新增独立调研阶段
+```
+
+**新阶段 research**：
+
+- **输入**: proposal + 参考实现列表
+- **输出**: 技术栈清单 + 参考模式提取 + 风险评估
+- **时间**: 15-30 分钟
+- **产物**: `research.md`（临时文档，archive 时删除）
+
+**research.md 结构**：
+
+```markdown
+# 技术调研 - [需求名称]
+
+## 参考实现分析
+
+### AddIntentOrderOutSystemDealTunnel
+- 文件位置: web/manager/stream/consumer/...
+- 关键模式:
+  - Consumer 定义: @YkMqConsumer + MsgData 子类
+  - 调用链: ...
+
+## 技术栈清单
+
+- 请求结构: RequestMsg<T> / ResponseMsg<T>
+- Kafka: @YkMsg + ykMqTemplate.sendAsync()
+- 加密: AESUtil.encryptAES() (AES-128 ECB)
+
+## 风险点
+
+- AES256-GCM 工具类不存在，需要新建
+- 验签逻辑没有现成拦截器，需要在 Service 层实现
+```
+
+### 推荐方案
+
+**方案 A**（渐进增强）：
+
+1. 对现有流程影响小
+2. 实施成本低
+3. 可以立即生效
+
+**具体实施**：
+
+- 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范
+- 增加 checkpoint 描述
+- 更新 question pool 增加技术澄清问题
+
+---
+
+## 其他建议
+
+### 1. 增加"快速失败"机制
+
+当发现以下情况，立即暂停并询问用户：
+
+- 需要创建的类/接口在参考实现中有类似的（防止重复造轮）
+- 实现方式与设计文档明显偏离
+- 连续返工超过 2 次（说明方向可能错了）
+
+### 2. 产物可观测性增强
+
+在 apply 阶段，定期输出：
+
+```markdown
+## 实现进度（每 30 分钟更新）
+
+✅ Controller 层（已完成）
+  - ShandongSyncController.syncIntentOrder
+  - 请求结构使用 RequestMsg<ShandongIntentOrderData>
+  
+🚧 Service 层（进行中）
+  - ShandongSyncService 接口完成
+  - 实现类 70% 完成
+  - ⚠️ 验签解密未实现（TODO）
+  
+⏳ Kafka 层（待开始）
+```
+
+### 3. 设计文档质量要求
+
+设计文档应该包含：
+
+- ✅ 参考实现的具体文件路径（而不是只说"参考 XXX"）
+- ✅ 关键技术栈的使用示例（而不是只说"使用 Kafka"）
+- ✅ 数据流图（清晰展示同步/异步边界）
+
+---
+
+## 总结
+
+**核心问题**: apply 阶段"想当然"开始写代码，缺少充分调研和分步验证。
+
+**解决方向**: 在 apply 前增加强制调研步骤，在 apply 中增加对齐检查点。
+
+**预期效果**: 返工次数从 4-5 次降低到 0-1 次，实现质量与设计文档一致性提升。
+
+**立即可做**: 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范即可生效。
@@ -0,0 +1,504 @@
+# SM Flow Skill - 使用情况分析与优化建议
+
+## 执行概况
+
+**项目**: lookup-knowledge-integration  
+**执行日期**: 2026-06-24  
+**执行模式**: 手动跳阶段（用户直接要求"修复问题"）
+
+### 实际执行的阶段
+
+1. ❌ **Clarify** - 跳过（用户直接给了 handoff 文档）
+2. ❌ **Context** - 跳过（未读取 devflow 历史）
+3. ❌ **Propose** - 跳过（OpenSpec 已存在）
+4. ❌ **Grill** - 跳过（未进行澄清）
+5. ❌ **Specify** - 跳过（OpenSpec 已完整）
+6. ❌ **Audit** - 跳过（未进行架构审计）
+7. ❌ **Commit** - **跳过（关键遗漏）**
+8. ✅ **Apply** - 执行（实现代码）
+9. ⚠️ **Archive** - 部分执行（先创建 handoff，后补 devflow）
+
+---
+
+## 做得好的地方 ✅
+
+### 1. Archive 规则详细且可执行
+
+**优点**：
+- `archive-rules.md` 提供了清晰的提取映射表
+- 目录结构规范（devflow/projects/YYYY-MM-DD-{slug}/）
+- 产物分档（micro/standard/complex）明确
+- 索引维护规则具体
+
+**证据**：被提醒后，我能快速创建符合规范的 devflow 档案
+
+### 2. 硬约束明确
+
+**优点**：
+- 6 条核心规则写在 SKILL.md 顶部，醒目
+- 规则表述清晰（不得跳过 context/grill/commit）
+
+**问题**：虽然规则清晰，但缺少执行机制（见后续建议）
+
+### 3. Phase 契约结构清晰
+
+**优点**：
+- `phase-contracts.md` 定义了进入/退出条件
+- 每个阶段的职责明确
+
+---
+
+## 关键问题 ❌
+
+### 问题 1: Commit 检查缺少可执行标准
+
+**现象**：
+- 我不知道如何判断"通过 commit 检查"
+- phase-contracts.md 说了要做 commit，但没说具体怎么判断
+
+**影响**：
+- 我直接跳过 commit，进入 apply
+- 违反了硬约束规则 4："不得跳过 commit"
+
+**根本原因**：
+```
+phase-contracts.md:
+  "Commit 阶段：检查 Draft OpenSpec 是否达到可执行状态"
+  
+但没有说：
+  - 什么叫"可执行状态"？
+  - 需要检查哪些文件？
+  - 每个文件的必需内容是什么？
+  - 如何标记"已通过"？
+```
+
+### 问题 2: Apply 阶段缺少前置门控
+
+**现象**：
+- 用户说"修复问题"，我直接开始实现
+- 没有检查是否存在 Committed OpenSpec
+
+**影响**：
+- 可能基于不完整的 OpenSpec 执行
+- 违反了 "apply 必须基于 Committed OpenSpec" 的约束
+
+**根本原因**：
+- Apply 阶段的"进入条件"是软性描述
+- 没有强制的文件检查机制（如 `.committed` 文件）
+
+### 问题 3: Archive 阶段缺少 Checklist
+
+**现象**：
+- 我先创建了 handoff 文档
+- 忘记了 devflow 才是核心记忆层
+- 被提醒后才补创建 devflow 档案
+
+**影响**：
+- 归档流程不完整
+- 需要用户纠正
+
+**根本原因**：
+- archive-rules.md 有详细说明，但没有强制执行顺序
+- 我容易按"直觉"操作，而不是按"规范"操作
+
+### 问题 4: 缺少流程状态追踪
+
+**现象**：
+- 我不知道当前在哪个阶段
+- 每次执行都像"全新开始"
+
+**影响**：
+- 容易跳过中间阶段
+- 无法断点续做
+
+---
+
+## 优化建议（按优先级）
+
+### High Priority（立即修复）
+
+#### 建议 1: Commit 检查增加可执行 Checkpoint
+
+**位置**：`references/phase-contracts.md` - Commit 阶段
+
+**增加内容**：
+```markdown
+## Commit 阶段退出条件
+
+必须完成以下 checkpoint：
+
+### 文件完整性检查
+- [ ] `proposal.md` 存在且包含：
+  - 问题描述（至少 50 字）
+  - 建议方案（至少 100 字）
+  - 范围/非范围
+
+- [ ] `design.md` 存在且包含：
+  - 架构设计（文字或图）
+  - 数据结构定义（至少 1 个）
+  - 关键决策记录（至少 2 条）
+
+- [ ] `specs/functional-specs.md` 存在且包含：
+  - 至少 3 个 requirement
+  - 每个 requirement 有 scenario
+
+- [ ] `tasks.md` 存在且包含：
+  - 至少 5 个可执行子任务
+  - 每个任务有验收标准
+
+### 一致性检查
+- [ ] proposal 中的核心概念在 design 中有对应设计
+- [ ] design 中的关键决策在 tasks 中有对应实现任务
+- [ ] tasks 的验收标准可验证（不是"正确实现"这种模糊描述）
+
+### 标记
+通过后创建 `.committed` 文件：
+```bash
+echo "committed at $(date)" > openspec/changes/{slug}/.committed
+```
+
+**执行指令**：
+在 apply 阶段入口，必须先执行此检查。
+```
+
+#### 建议 2: Apply 阶段增加前置门控
+
+**位置**：`references/phase-contracts.md` - Apply 阶段
+
+**修改"进入条件"**：
+```markdown
+## Apply 阶段进入条件
+
+**硬约束**：
+1. 必须存在 `.committed` 文件
+2. 如果不存在，执行以下流程：
+   a. 汇报：Draft OpenSpec 未通过 commit 检查
+   b. 列出缺失的 checkpoint
+   c. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
+
+**检查代码**：
+```bash
+if [ ! -f "openspec/changes/{slug}/.committed" ]; then
+    echo "错误：Draft OpenSpec 未通过 commit 检查"
+    echo "请先完成 commit 阶段，或显式确认跳过"
+    exit 1
+fi
+```
+```
+
+#### 建议 3: Archive 阶段增加强制 Checklist
+
+**位置**：`references/archive-rules.md` 顶部
+
+**增加内容**：
+```markdown
+## Archive 阶段强制执行顺序
+
+**按以下顺序执行，不得跳过或重排**：
+
+### Step 1: 创建 devflow 档案（必需）
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
+      （从 proposal.md 提取：背景、目标、范围、非目标）
+      
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
+      （从 decisions.md 整理：关键决策、权衡、风险）
+      
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
+      （记录：静态验证、脚本验证、人工验证、未验证）
+
+### Step 2: 更新索引（必需）
+- [ ] 在 `devflow/index.md` 末尾追加一行：
+      `| YYYY-MM-DD | slug | 领域 | 关键词 | OpenSpec路径 | archived |`
+
+### Step 3: 标记 OpenSpec（必需）
+- [ ] 创建 `openspec/changes/{slug}/.completed` 文件
+
+### Step 4: 创建 Handoff（可选）
+- [ ] 创建 `handoff/YYYY-MM-DD-{slug}.md`
+      （运维交接文档，给未来开发者）
+
+### Step 5: 向用户汇报
+- [ ] 列出创建的 devflow 档案
+- [ ] 汇报验证情况（按类型分类）
+- [ ] 列出剩余风险
+- [ ] 询问：**是否现在归档 OpenSpec？**
+
+**自检**：在执行 Step 5 前，检查 Step 1-4 是否都完成。
+```
+
+---
+
+### Medium Priority（下个版本）
+
+#### 建议 4: 增加流程状态文件
+
+**目标**：让我知道当前在哪个阶段
+
+**实现**：在 OpenSpec 目录维护 `.sm-flow-state` 文件
+
+```json
+{
+  "change": "lookup-knowledge-integration",
+  "currentPhase": "apply",
+  "completed": ["clarify", "context", "propose", "grill", "specify", "audit", "commit"],
+  "nextPhase": "archive",
+  "committed": true,
+  "timestamps": {
+    "commit": "2026-06-24T10:00:00Z",
+    "apply_start": "2026-06-24T10:05:00Z"
+  }
+}
+```
+
+**使用方式**：
+- 每个阶段开始时：读取此文件，确认前置阶段已完成
+- 每个阶段结束时：更新此文件，标记当前阶段完成
+- 用户下次调用时：直接从 `nextPhase` 继续
+
+**集成到 SKILL.md**：
+```markdown
+## 执行前检查
+
+1. 读取 `.sm-flow-state` 文件
+2. 确认当前阶段的前置阶段已完成
+3. 如有缺失，汇报并询问是否补做
+```
+
+#### 建议 5: Context 阶段增加必读清单
+
+**位置**：`references/phase-contracts.md` - Context 阶段
+
+**增加内容**：
+```markdown
+## Context 阶段必读文件
+
+按顺序读取（即使文件不存在也要尝试）：
+
+1. **devflow/index.md** - 项目索引
+   - 查找相关领域的历史项目
+   - 识别可能相关的关键词
+   
+2. **devflow/glossary/CONTEXT.md** - 术语表
+   - 提取项目术语和业务规则
+   
+3. **相关项目的 decisions.md** - 历史决策
+   - 从 index.md 中识别的相关项目
+   - 读取其决策，避免重复或冲突
+   
+4. **devflow/compound/*.md** - 可复用知识
+   - 查找可复用的设计模式、经验
+
+**如果文件不存在**：
+- 记录"无历史上下文"
+- 在 proposal.md 中标注"首次相关实现"
+- 继续执行
+```
+
+#### 建议 6: 增加"违规自检"机制
+
+**目标**：每个阶段结束前，自动检查是否违反硬约束
+
+**实现**：在每个阶段的退出条件后增加"自检清单"
+
+```markdown
+## [阶段名] 退出前自检
+
+检查以下硬约束是否违反：
+
+- [ ] 是否跳过了 context？
+      检查：是否读取了 devflow/index.md？
+      
+- [ ] 是否跳过了 grill？
+      检查：decisions.md 中是否记录了至少 3 个澄清问题？
+      
+- [ ] 是否跳过了 commit？
+      检查：是否存在 .committed 文件？
+      
+- [ ] apply 是否基于 Committed OpenSpec？
+      检查：apply 开始前是否读取了 OpenSpec 文件？
+      
+- [ ] 遇到冲突是否先分类？
+      检查：冲突记录是否标记了类型（规格遗漏/实现偏差）？
+      
+- [ ] 是否调用了所有必需的子 skill？
+      检查：阶段定义中要求的 skill 是否都调用了？
+
+如有违规项，停止执行并汇报。
+```
+
+---
+
+### Low Priority（可选增强）
+
+#### 建议 7: Grill 阶段增加 Question Pool 模板
+
+**目标**：帮助我提出高质量的澄清问题
+
+**位置**：`references/phase-contracts.md` - Grill 阶段
+
+**增加内容**：
+```markdown
+## Grill Question Pool 模板
+
+必须覆盖至少 3 个维度：
+
+### 维度 1: 范围边界
+模板问题：
+- "Out of scope 里的 X 功能，为什么不在这次做？有什么依赖或风险？"
+- "如果用户要求 Y，这个方案能扩展支持吗？需要改动多少？"
+- "边界场景 Z 应该怎么处理？报错还是降级？"
+
+### 维度 2: 技术风险
+模板问题：
+- "如果依赖的 A 服务挂了，这个方案有降级策略吗？"
+- "为什么选择技术方案 B 而不是 C？主要考虑什么？"
+- "数据量增长到 N 倍，性能瓶颈在哪里？"
+
+### 维度 3: 用户验证
+模板问题：
+- "这个方案解决的核心痛点是什么？有真实场景吗？"
+- "有没有现成的替代方案？为什么不用？"
+- "如果上线后发现不符合预期，回滚成本多大？"
+
+### 维度 4: 实现可行性
+模板问题：
+- "最复杂的部分是什么？有没有技术预研？"
+- "需要改动哪些核心模块？影响面多大？"
+- "有没有类似的历史实现可以参考？"
+```
+
+#### 建议 8: 增加"快速模式"明确定义
+
+**当前问题**：`operating-rules.md` 提到快速模式，但没说具体怎么做
+
+**建议**：明确快速模式的简化规则
+
+```markdown
+## 快速模式
+
+### 触发条件
+满足以下所有条件时，可使用快速模式：
+- 变更小于 5 个文件
+- 无架构变更
+- 无数据库迁移
+- 用户明确要求"快速"
+
+### 简化规则
+1. Grill 阶段：至少 1 个问题（而非 3 个）
+2. Specify 阶段：tasks.md 可简化为 3 个子任务
+3. Audit 阶段：可跳过（标注"快速模式跳过审计"）
+4. Archive 阶段：使用 micro 分档（brief/decisions/acceptance）
+
+### 不得简化
+- Context 阶段：仍需读取 devflow
+- Commit 阶段：仍需检查 OpenSpec 完整性
+- Apply 阶段：仍需基于 Committed OpenSpec
+```
+
+---
+
+## 执行机制优化建议
+
+### 当前问题：约束是"软性"的
+
+**现象**：
+- 规则写得很清楚："不得跳过 commit"
+- 但我仍然能跳过，没有强制机制
+
+**根本原因**：
+- 规则是"描述性"的（说应该做什么）
+- 缺少"执行性"的机制（强制检查、文件依赖）
+
+### 解决方案：引入"门控文件"
+
+**设计**：
+```
+每个阶段完成后，创建一个标记文件：
+- .context-done
+- .grill-done
+- .commit-done (即 .committed)
+- .apply-done
+- .archive-done
+
+下一个阶段开始前，检查前置文件是否存在。
+```
+
+**示例**：Apply 阶段入口检查
+```bash
+if [ ! -f ".committed" ]; then
+    echo "错误：Commit 阶段未完成"
+    echo "缺失文件：.committed"
+    echo "请先完成 commit 阶段，或显式跳过（需用户确认）"
+    exit 1
+fi
+```
+
+**好处**：
+1. 强制执行顺序（无法跳过）
+2. 可视化进度（ls 就能看到哪些阶段完成了）
+3. 支持断点续做（下次执行自动识别位置）
+
+---
+
+## 用户体验优化
+
+### 当前问题：用户不知道"现在在哪"
+
+**场景**：
+- 用户说"继续"
+- 我不知道该从哪个阶段继续
+
+**建议**：每次开始时，主动汇报状态
+
+```
+开始执行 SM Flow...
+
+当前状态：
+✅ Context 已完成
+✅ Propose 已完成
+⏸️ Grill 未开始 ← 当前阶段
+
+下一步：执行 Grill 阶段（人类对齐澄清）
+预计耗时：5-10 分钟
+```
+
+### 建议：增加"进度条"
+
+```
+SM Flow 进度：
+[✅] Clarify
+[✅] Context
+[✅] Propose
+[⏸️] Grill ← 当前
+[ ] Specify
+[ ] Audit
+[ ] Commit
+[ ] Apply
+[ ] Archive
+```
+
+---
+
+## 总结
+
+### 核心问题
+1. **Commit 检查缺少可执行标准**（导致容易跳过）
+2. **Apply 阶段缺少前置门控**（没有强制检查 .committed）
+3. **Archive 阶段缺少 Checklist**（容易遗漏 devflow）
+4. **缺少流程状态追踪**（不知道当前在哪）
+
+### 优先修复（High Priority）
+- ✅ Commit 检查增加 Checkpoint
+- ✅ Apply 增加前置门控
+- ✅ Archive 增加 Checklist
+
+这三个修复后，绝大多数"跳过阶段"问题都能解决。
+
+### 框架本身很好
+- 架构清晰（9 个阶段、4 层架构）
+- 规则明确（6 条硬约束）
+- 文档详细（phase-contracts, archive-rules）
+
+**问题不是"约束不够"，而是"执行机制不够明确"。**
+
+增加可验证的 checkpoint 和门控文件后，我就很难"偷懒"了。
@@ -1,6 +1,6 @@
 # SM-Flow 工作流

-## 当前设计理念（v4 方向）
+## 当前设计理念（v4.3）

 **核心定位**：sm-flow 是一个**用提示词实现的协议层 harness**——编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。

@@ -22,6 +22,15 @@ sm-flow        → 编排层（harness）：阶段、门控、产物约束、人
 | `/sm-flow apply` | 只执行（已有 Committed OpenSpec） |
 | `/sm-flow archive` | 收尾（回填 devflow + 归档确认） |

+**触发边界**：
+
+sm-flow 只在用户显式调用时使用：
+
+- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。
+- 用户用自然语言明确要求“使用 sm-flow”“走 sm-flow 流程”或等价表达。
+
+不要根据任务类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。
+
 **内部阶段（9 个，英文动词命名）**：

 ```
@@ -29,7 +38,7 @@ clarify → context → propose → grill → specify → audit → commit → a
 入口澄清   上下文     轻量提案   澄清    细化      审计    提交     执行    归档
 ```

-阶段名是 harness 的内部协议词汇（用于 checkpoint 汇报和进度通知），不是用户 API。用户只需知道 4 个命令，其余通过自然语言交互，由 harness 识别意图后编排。
+阶段名是 harness 的内部协议词汇，不是用户 API。面向用户默认只暴露 4 个可见 checkpoint：Discover、Commit、Apply、Archive；内部阶段仍按顺序执行。

 **关键设计决策**：

@@ -37,7 +46,9 @@ clarify → context → propose → grill → specify → audit → commit → a
 - **Draft / Committed 分离**：propose 产出 Draft OpenSpec（讨论对象），commit gate 后成为 Committed OpenSpec（执行许可）。apply 只执行 Committed OpenSpec。
 - **grill 在 specify 前**：先澄清需求再细化产物，避免"细化 → grill → 回写细化"的返工循环。propose 只写轻量 proposal.md，grill 稳定需求后 specify 才补全 design/specs/tasks。
 - **devflow 延迟写入**：clarify → apply 期间只维护 `decisions.md` 作为过程日志，archive 阶段从中提取完整 devflow 档案（brief/evidence/acceptance）。
- **micro ≠ skip**：快速模式合并 gate（clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill 最少 1 个问题 → commit 简化检查），但保留最关键的门控。
+- **micro ≠ skip**：micro 是 standard 的减法，不是跳过流程。它可以合并 checkpoint、减少独立产物，但仍保留 context、grill、commit、apply 和 archive gate。
+- **分档单一来源**：`micro / standard / complex` 的完整定义只放在 `.agents/skills/sm-flow/references/scales.md`，其它文件只引用当前分档要求。
+- **能力来源显式声明**：每个阶段都要说明使用外部子 skill、OpenSpec CLI 还是 sm-flow 内置 fallback；fallback 不是跳过阶段，必须写入 `decisions.md` 或 `acceptance.md`。
 - **质量约束可观测**：质量约束必须转化为可观测产出（写入文件 + checkpoint 检查），否则不是约束而是建议。

 **使用方式**：
@@ -92,14 +103,14 @@ Phase 4  openspec:apply     Phase 2    grill-with-docs → CONTEXT.md + ADR

 ## 新增技能的投入产出

-| 技能 | 学多久 | 一次省多少 | 什么时候用 |
+| 技能 | 接入成本 | 主要收益 | 什么时候用 |
 |------|--------|-----------|-----------|
-| to-prd | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 |
-| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 |
-| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 |
-| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 |
-| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 |
-| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 |
+| to-prd | 自动综合 | 结构化需求 | openspec research 结束后 |
+| grill-with-docs | 替换已有 grill-me | 产出文档化澄清 | 需求澄清阶段 |
+| zoom-out | 低 | 避免方向性返工 | grill 完成后、apply 前 |
+| diagnose | 低 | 减少猜测式 bug 修复 | apply 中遇到问题 |
+| tdd | 低 | 减少回归 bug | apply 中写代码 |
+| git-guardrails | 被动生效 | 防止灾难性操作 | 全程自动 |

 ## 为什么这套组合优于单纯依赖 openspec

@@ -804,7 +815,7 @@ v4：

 | # | 问题 | 具体表现 | 分析结论 |
 |---|------|----------|----------|
-| 1 | propose 阶段越界 | 在 propose 阶段一次性生成了 proposal + design + specs + tasks，跳过 grill 和 specify | 需求小时 agent 本能跳过门控。现有硬约束 #3（不得跳过 grill）和阶段流程顺序已覆盖，属于执行层面问题，不需要改协议 |
+| 1 | propose 阶段越界 | 在 propose 阶段一次性生成了 proposal + design + specs + tasks，跳过 grill 和 specify | 需求较小场景下 agent 本能跳过门控。现有硬约束 #3（不得跳过 grill）和阶段流程顺序已覆盖，属于执行层面问题，不需要改协议 |
 | 2 | 子 skill 伪调用 | grill 阶段读了 grill-with-docs 的 SKILL.md 后自行执行，audit 阶段跳过了 zoom-out | Skill 工具调用和 Read 后执行效果等价，关键是"不能跳过"而非"用什么工具调用"。硬约束 #6 已覆盖，不需要改协议 |
 | 3 | spec 遗漏用户行为 | spec 写的是"添加 .expanded class"（实现细节），没有写"展开后显示完整正文"（用户可观察行为） | 导致第一版实现只切换了 CSS class，正文内容仍显示截断文本。spec 应描述用户可观察的结果而非实现方式 |

@@ -819,3 +830,406 @@ v4：
 ### 后续观察项

 问题 1 和 2 暂不改协议，如果多次验证中反复出现再考虑加约束。问题 3 需要在下次 specify 阶段验证：spec scenario 是否自然地描述用户行为而非实现细节。
+
+## v4.1：Apply 阶段前置调研增强（2026-06-23）
+
+### 背景
+
+基于"山东商客意向单同步接口"的执行复盘（`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`），发现 apply 阶段存在严重的返工问题：
+
+- **返工次数**：4-5 次重大返工
+- **核心问题**：apply 阶段"想当然"开始写代码，缺少充分调研和分步验证
+- **主要表现**：
+  - 参考实现利用不充分（设计文档提到参考实现，但直到用户提醒才去看）
+  - 技术栈不熟悉（RequestMsg 结构、Kafka 发送方式、Consumer 位置全部返工）
+  - 设计-实现偏离（验签/解密/查询接口只有 TODO 注释）
+
+### 核心改进：Pre-apply Checkpoint
+
+在 apply 阶段开始前增加强制性调研检查点（方案 B 简化版）：
+
+#### 修改 1：grill 阶段增加技术实现维度
+
+在 question pool 中新增"技术实现维度"：
+
+```markdown
+**技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
+- 参考实现的具体文件路径是什么？
+- 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
+- 有哪些技术点需要先调研或新建？
+```
+
+**目的**：在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
+
+#### 修改 2：apply 阶段增加 Pre-apply Checkpoint
+
+在 apply 阶段开始前增加强制调研步骤：
+
+**触发条件**（3 条）：
+- design 或 tasks 中提到"参考 XXX 实现"
+- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
+- 技术栈不熟悉或第一次在该项目实现类似功能
+
+**执行步骤**（3 步）：
+1. **完整阅读所有参考实现**
+   - 从 OpenSpec design 或 tasks 中定位参考实现文件
+   - 如果路径不明确，通过 Grep 搜索关键类名或模式
+   - 逐行理解关键逻辑，提取可复用代码片段和模式
+
+2. **Grep 关键技术栈**
+   - 请求/响应结构模式
+   - 消息队列模式
+   - 统一工具类
+   - 异常处理和日志记录标准
+
+3. **形成技术栈清单并写入 decisions.md**
+   - 项目使用的请求/响应结构标准
+   - MQ 消息定义和发送标准
+   - Consumer 标准位置和写法
+   - 加密/验签/工具类的标准用法
+   - 识别需要新建的工具类或基础设施
+
+**输出要求**（3 条）：
+- ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
+- ✅ 已列出所有参考实现的文件路径
+- ✅ 已识别需要新建的工具类/基础设施
+
+**快速模式支持**：micro 分档可按风险缩小调研范围，但仍需形成清单。
+
+#### 修改 3：apply 实现过程增强
+
+**分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
+
+**首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
+
+**快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
+
+#### 修改 4：apply 退出条件增强
+
+新增退出条件：
+- ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
+- ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
+
+### 预期效果
+
+| 指标 | 当前 | 目标 | 改善 |
+|------|------|------|------|
+| 返工次数 | 4-5 次 | 0-1 次 | -80% |
+| 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% |
+
+**ROI 分析**：
+
+前置调研的收益来自减少返工和避免核心功能遗漏。v4.3 之后不再用固定投入指标定义投入或收益，改按风险和实现复杂度决定调研深度。
+
+### 复杂度评估
+
+**本次修改复杂度**：中等
+- 文本增量：+55 行（从 281 行 → 336 行，+20%）
+- 概念层级：+1 层（apply 内部增加 Pre-apply Checkpoint 子阶段）
+- 强制规则：+5 条（pre-apply 触发条件、执行步骤、输出要求）
+
+**整体复杂度**：高（但合理）
+- 总行数：606 行 → ~700 行（+15%）
+- 阶段数：9 个（不变）
+- 门控数：4 个 → 6 个（+propose checkpoint, +pre-apply checkpoint）
+
+**简化设计**：
+- 采用方案 B（简化版），相比完整方案减少 45% 文本量和 44% 规则数
+- 保留核心价值（前置调研、技术栈清单、核心功能质量保证）
+- 去掉过度约束（严格执行顺序、频繁检查点、详细操作模板）
+
+### 适用场景
+
+✅ **强烈推荐**：
+- 中等及以上规模需求（3+ 接口或涉及多模块）
+- 涉及项目现有基础设施（MQ/统一请求结构/工具类）
+- 第一次在该项目实现类似功能
+- 设计文档提到"参考 XXX 实现"
+
+🟡 **可选执行**：
+- micro 分档的简单需求（可按风险缩小范围）
+- 纯数据处理或工具脚本（技术栈熟悉）
+
+❌ **不推荐**：
+- 紧急热修复（时间紧急）
+- 一次性脚本（不涉及项目标准）
+
+### 相关文档
+
+- 执行复盘：`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
+- 更新日志：`skill-workbench/docs/sm-flow/phase-contracts-v4.1-changelog.md`
+- 修改文件：`.agents/skills/sm-flow/references/phase-contracts.md`
+
+## v4.2：可验证 Checkpoint 与执行机制增强（2026-06-24）
+
+### 背景
+
+基于"lookup-knowledge-integration"的执行复盘（`skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`），发现一个结构性问题：
+
+**约束是"软性"的，缺少执行机制**
+
+- **规则清楚但可绕过**：6 条硬约束写得很清楚"不得跳过 commit"，但 agent 仍然能跳过
+- **标准模糊无法判断**：commit 阶段说"检查是否可执行"，但不知道具体检查什么
+- **流程无强制顺序**：archive 建议"先 devflow 后 handoff"，但 agent 可能先创建 handoff
+
+**核心认知**：规则是"描述性"的（说应该做什么），缺少"执行性"的机制（强制检查、文件依赖）。
+
+### 核心改进：从软性约束到硬性检查
+
+v4.2 不增加新阶段或新规则，而是**把现有约束变成可验证的 checkpoint**：
+
+| 改进点 | Before（v4.1） | After（v4.2） |
+|--------|---------------|--------------|
+| Commit 标准 | "检查是否可执行"（模糊） | 文件完整性 + 一致性检查清单（具体） |
+| Apply 门控 | "已通过 commit"（软性） | 检查 `.committed` 文件存在（硬性） |
+| Archive 顺序 | "应该先 devflow"（建议） | 5 步强制顺序 + 自检（必须） |
+
+### 详细修改
+
+#### 修改 1：Commit 阶段增加可验证 Checkpoint
+
+**文件完整性检查**（必须全部通过）：
+- [ ] `proposal.md` 存在，包含问题描述（≥50字）、建议方案（≥100字）、范围/非目标
+- [ ] `design.md` 存在，包含架构设计、数据结构（≥1个）、关键决策（≥2条）
+- [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
+- [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准
+
+**一致性检查**（必须通过）：
+- [ ] proposal 核心概念 → design 有对应设计
+- [ ] design 关键决策 → tasks 有对应实现
+- [ ] tasks 验收标准可验证（非"正确实现"这类模糊描述）
+
+**标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件
+
+#### 修改 2：Apply 阶段增加前置门控
+
+**前置门控检查**（硬约束）：
+1. 检查 `openspec/changes/{slug}/.committed` 文件是否存在
+2. 如不存在：
+   - 汇报：Draft OpenSpec 未通过 commit 检查
+   - 列出缺失的 checkpoint 项
+   - 询问用户：是否补做 commit；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`
+
+#### 修改 3：Archive 阶段增加强制执行顺序
+
+**5 步 Checklist**（不得跳过或重排）：
+1. **创建 devflow 档案**（必需）：brief.md + evidence.md + decisions.md + acceptance.md
+2. **更新索引**（必需）：在 `devflow/index.md` 追加一行
+3. **标记 OpenSpec**（必需）：创建 `.archive-ready` 文件
+4. **向用户汇报**（必需）：列出文件、验证分类、剩余风险，询问是否归档
+5. **执行 OpenSpec Archive**（可选）：用户确认后调用 `openspec-archive-change`
+
+**自检**：Step 4 前检查 Step 1-3 是否都完成
+
+### 新增门控文件
+
+| 文件 | 创建时机 | 用途 |
+|------|----------|------|
+| `.committed` | commit 阶段退出时 | apply 阶段前置门控依据 |
+| `.archive-ready` | archive Step 3 | 标记归档准备就绪 |
+
+### 预期效果
+
+**解决的问题**：
+- ❌ Commit 标准不明确 → ✅ 有具体检查清单，无法模糊通过
+- ❌ Apply 可能基于不完整 OpenSpec → ✅ 门控文件强制阻止
+- ❌ Archive 容易遗漏 devflow → ✅ 强制顺序确保完整
+
+**量化指标**：
+- Commit 阶段跳过率：-100%（有 checklist 无法跳过）
+- Apply 基于不完整 OpenSpec：-100%（门控阻止）
+- Archive 遗漏 devflow：-100%（强制顺序）
+
+### 设计原则
+
+#### 1. 可验证性
+将模糊标准转为可测量的具体要求：
+- Before: "检查 OpenSpec 是否可执行"
+- After: "proposal ≥50字、design ≥1个数据结构、specs ≥3个 requirement"
+
+#### 2. 门控文件
+用文件存在性替代软性判断：
+- Before: 描述"已通过 commit"
+- After: 检查 `.committed` 文件存在
+
+#### 3. 强制顺序
+用 checklist 替代建议性描述：
+- Before: "应该先创建 devflow"
+- After: "Step 1 devflow → Step 2 索引 → Step 3 标记 → Step 4 汇报"
+
+### 复杂度评估
+
+**本次修改复杂度**：低-中等
+- 文本增量：+80 行（phase-contracts.md +40 行，archive-rules.md +40 行）
+- 概念增加：2 个门控文件
+- 规则增强：3 个阶段的检查清单
+
+**整体复杂度**：高（但更可靠）
+- 总行数：~700 行 → ~780 行（+11%）
+- 门控数：6 个 → 8 个
+
+**权衡**：
+- ✅ 收益：彻底解决"跳过阶段"问题
+- ⚠️ 成本：增加 80 行文本，更多检查项
+
+### 与 v4.1 的关系
+
+| 版本 | 核心改进 | 解决问题 |
+|------|----------|----------|
+| v4.1 | Pre-apply Research Checkpoint | apply 前置调研不足，导致返工（4-5次 → 0-1次） |
+| v4.2 | 可验证 Checkpoint + 门控文件 | 约束是软性的，agent 容易跳过阶段 |
+
+**互补关系**：
+- v4.1 解决"调研不充分导致返工"（质量问题）
+- v4.2 解决"缺少执行机制导致跳过阶段"（流程问题）
+
+### 适用场景
+
+**✅ 所有场景（无例外）**
+
+v4.2 的改进是执行机制层面的，不涉及业务逻辑：
+- 无论 micro/standard/complex，都需要 commit 检查
+- 无论需求大小，都需要 apply 前置门控
+- 无论项目规模，都需要 archive 强制顺序
+
+**快速模式**：可以简化产物（如 tasks 只需 3 个），但**不能跳过门控**。
+
+### 后续演进方向（v5.0 候选）
+
+如果 v4.2 执行良好但仍有问题，考虑：
+
+1. **流程状态文件** `.sm-flow-state`
+   - 记录当前阶段、已完成阶段、时间戳
+   - 支持断点续做
+
+2. **更多门控文件**
+   - `.context-done`、`.grill-done`、`.apply-done`
+   - 形成完整的阶段间依赖链
+
+3. **违规自检机制**
+   - 每个阶段退出前，自动检查 6 条硬约束
+
+4. **进度可视化**
+   - 每次开始时，汇报进度条
+
+**判断依据**：如果 v4.2 后仍频繁出现跳过阶段，再引入更重的机制。
+
+### 相关文档
+
+- 执行复盘：`skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`
+- 更新日志：`skill-workbench/docs/sm-flow/phase-contracts-v4.2-changelog.md`
+- 修改文件：
+  - `.agents/skills/sm-flow/references/phase-contracts.md`
+  - `.agents/skills/sm-flow/references/archive-rules.md`
+
+## v4.3：显式触发、分档单一来源与验证闭环（2026-07-05）
+
+### 背景
+
+v4.2 之后，流程门控更可靠，但 skill 本身开始显得庞大：frontmatter、触发规则、分档规则、fallback、术语解释和阶段契约交织在一起。实际 review 中发现几个风险：
+
+- 触发范围容易被写宽，导致任务只要涉及 OpenSpec、跨模块或 devflow 就自动触发 sm-flow。
+- `micro / standard / complex` 的规则散落在多个文件里，后续维护容易不一致。
+- `micro`、`standard`、`complex` 的要求同时分布在不同文件中，review 时很难判断哪个是权威。
+- 规则中出现固定投入估算，容易把经验值误读成流程标准。
+- fallback、checkpoint、Draft/Committed 等词缺少统一词条，解释容易漂移。
+
+### 核心结论
+
+v4.3 保留 v4 的精华，但收紧触发面、降低重复定义，并用真实 change 验证 micro 和 standard 两条路径：
+
+- **只显式触发**：sm-flow 只在用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`，或自然语言明确要求“使用 sm-flow / 走 sm-flow 流程”时触发。
+- **不按需求类型自动触发**：OpenSpec、跨模块、接口契约、需求澄清、devflow 归档都不是自动触发条件。
+- **4 个用户可见 checkpoint 保留**：Discover、Commit、Apply、Archive。
+- **9 个内部阶段保留**：clarify → context → propose → grill → specify → audit → commit → apply → archive。
+- **分档单一来源**：`references/scales.md` 是 `micro / standard / complex` 的唯一完整规则源。
+- **fallback 独立成文**：外部 OpenSpec 能力或子 skill 不可用时，使用 `references/fallbacks.md`，并记录 capability source、影响和剩余风险。
+- **词条独立成文**：`references/glossary.md` 统一 checkpoint、fallback、Draft、Committed、gate、scale 等术语。
+- **不使用固定投入指标**：skill 规则不再用具体投入单位或时间盒定义分档、努力程度或验证阈值。
+
+### 文件结构调整
+
+新增 reference：
+
+```text
+.agents/skills/sm-flow/references/
+├── fallbacks.md     # 外部 OpenSpec/子 skill 不可用时的内置协议
+├── glossary.md      # checkpoint/gate/fallback/Draft/Committed/scale 等术语
+└── scales.md        # micro / standard / complex 的唯一完整定义
+```
+
+职责调整：
+
+- `SKILL.md`：只保留触发边界、四层架构、6 条硬约束、4 个用户命令、4 个 checkpoint、9 个内部阶段和首次加载规则。
+- `phase-contracts.md`：保留阶段进入条件、动作、输出和退出条件；涉及分档时只引用 `scales.md`。
+- `operating-rules.md`：保留启动检查、进度汇报、接口影响、devflow 分层和完成标准；不再重复定义分档细节。
+- `archive-rules.md`：只定义归档顺序、提取映射和索引规则；产物分档引用 `scales.md`。
+- `templates.md`：保留模板和检查表，不再作为分档规则来源。
+
+### 分档验证
+
+#### micro 验证
+
+验证 change：`validate-sm-flow-explicit-trigger`
+
+归档位置：
+
+```text
+openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/
+devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/
+```
+
+验证内容：
+
+- 显式触发规则生效：没有 `/sm-flow` 或明确“使用 sm-flow”时，不自动触发正式 sm-flow。
+- micro 可以使用内联设计小节，但仍需要 `proposal.md`、`specs/`、`tasks.md`、`.committed` 和 devflow 回填。
+- 发现并修复一个真实不一致：部分阶段契约仍硬编码 `design.md`，与 micro 允许等价设计小节冲突；已改为“设计产物”。
+- devflow micro 档案使用 `brief.md`、`decisions.md`、`acceptance.md`；证据并入过程日志。
+
+#### standard 验证
+
+验证 change：`validate-sm-flow-standard-change`
+
+归档位置：
+
+```text
+openspec/archive/2026-07-05-validate-sm-flow-standard-change/
+devflow/projects/2026-07-05-validate-sm-flow-standard-change/
+```
+
+验证内容：
+
+- standard 需要完整 OpenSpec 四件套：`proposal.md`、独立 `design.md`、`specs/`、`tasks.md`。
+- standard devflow 档案需要 `brief.md`、独立 `evidence.md`、`decisions.md`、`acceptance.md`。
+- 分档定义扫描只命中 `references/scales.md`，没有发现其它文件重新定义 standard/micro/complex。
+- standard 路径未发现新的规则不一致。
+
+### 验证命令与结果
+
+本轮验证通过：
+
+- `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow`
+- `references/*.md` 引用完整性扫描
+- 旧问题词扫描：固定投入指标、旧跳过语义、旧 conflict 表达、旧固定设计文件组合表达
+- 分档重复定义扫描
+- micro 和 standard OpenSpec/devflow 文件存在性检查
+
+### 当前取舍
+
+- 保留 3 个分档：`micro`、`standard`、`complex`。它们不是三套流程，而是同一流程在产物和审查强度上的三档覆盖。
+- 不引入显式状态文件，例如 `.sm-flow-state`。当前只保留 `.committed` 和 `.archive-ready` 两个必要 gate 文件。
+- 不把内部 9 阶段暴露成用户 API。用户交互继续以 4 个 checkpoint 为主。
+- 不默认做 OpenSpec archive；archive 仍是用户确认后的动作。
+
+### 对 v4.1/v4.2 的修正
+
+v4.1 的 Pre-apply Research 仍然保留，但不再用固定投入指标描述执行深度。当前规则是：按 `references/scales.md` 的当前分档和实现风险决定调研深度，退出判断以技术栈清单是否足以指导实现为准。
+
+v4.2 的 `.committed` 和 `.archive-ready` 继续保留。v4.3 只是把文件完整性检查改为“按当前分档要求执行”，避免 standard 的独立 `design.md` 要求误套到 micro。
+
+### 相关档案
+
+- `devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/`
+- `devflow/projects/2026-07-05-validate-sm-flow-standard-change/`
+- `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/`
+- `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`
Author	SHA1	Message	Date
aruo	e4f6e013a5	Refine sm-flow trigger and scale rules	2026-07-05 14:30:15 +08:00
osiman	433f7a93a4	Merge pull request 'emdash/cuddly-rockets-rhyme-d5jo4' (#1 ) from emdash/cuddly-rockets-rhyme-d5jo4 into master Reviewed-on: #1	2026-07-05 03:16:12 +08:00
zhuyongxin	c9a6777340	sm-flow v4.2: add verifiable checkpoints and gate file mechanism Based on real execution review (lookup-knowledge-integration), discovered that constraints are "soft" - rules are clear but lack enforcement mechanism. Core problem: Agent can skip stages despite explicit rules saying "must not skip" Changes: 1. Commit phase: add verifiable checkpoint - File completeness check: proposal ≥50 words, design ≥1 data structure, specs ≥3 requirements, tasks ≥5 items - Consistency check: proposal concepts → design mapping, design decisions → tasks implementation - Gate file: create .committed after passing all checks 2. Apply phase: add pre-gate check - Hard constraint: check .committed file existence - If missing: report, list gaps, ask user to fix or explicitly skip - Block implementation based on incomplete OpenSpec 3. Archive phase: add mandatory execution order - 5-step checklist: devflow files → index → .archive-ready → report → archive - Self-check: verify Step 1-3 before Step 4 - Prevent "handoff first, devflow forgotten" issue New gate files: - .committed: created by commit phase, checked by apply phase - .archive-ready: created by archive Step 3 Expected impact: - Commit skip rate: -100% (explicit checklist prevents fuzzy pass) - Apply on incomplete OpenSpec: -100% (gate blocks) - Archive devflow omission: -100% (mandatory order) Design principles: - Verifiability: "executable state" → "≥50 words + ≥1 structure + ≥3 requirements" - Gate files: soft judgment → file existence check - Mandatory order: advisory "should do" → 5-step checklist "must do" Complexity: +80 lines (phase-contracts.md +40, archive-rules.md +40) Approach: turn soft constraints into hard checks, no new stages Relation to v4.1: - v4.1: solve "insufficient research causes rework" (quality issue) - v4.2: solve "lack of enforcement causes stage skipping" (process issue) Docs: - phase-contracts.md: enhanced commit + apply phases - archive-rules.md: added mandatory execution order at top - workflow.md: added v4.2 evolution chapter - phase-contracts-v4.2-changelog.md: detailed change log - sm-flow-optimization-suggestions.md: source review	2026-06-24 14:51:45 +08:00
zhuyongxin	b94ee31cb1	sm-flow v4.1: add pre-apply research checkpoint to reduce rework Based on real execution review (shandong-intent-sync), apply phase suffered from 4-5 rework cycles due to insufficient upfront research. Changes: - grill: add technical implementation dimension to question pool - apply: add mandatory pre-apply checkpoint (15-20min research) - read reference implementations thoroughly - grep key tech stack patterns - form tech stack checklist in decisions.md - apply: add incremental implementation guidance - apply: add first-module alignment check - apply: add fast-fail rule (≥2 rework → pause) Expected impact: - Rework: 4-5 cycles → 0-1 cycle (-80%) - Core feature empty impl: 100% → 0% - ROI: 200% (invest 20min, save 60min) Complexity: +55 lines to phase-contracts.md (+20%) Approach: simplified version (plan B) to balance value vs overhead Docs: - phase-contracts.md: updated grill + apply phases - workflow.md: added v4.1 evolution chapter - phase-contracts-v4.1-changelog.md: detailed change log - sm-flow-execution-review-shandong-intent-sync.md: source review	2026-06-23 11:27:32 +08:00
				`@@ -0,0 +1 @@`
				`Devflow archive files are ready for validate-sm-flow-explicit-trigger.`
				`@@ -0,0 +1 @@`
				`Committed OpenSpec for validate-sm-flow-explicit-trigger.`