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 · 2026-05-26 10:14:25 +08:00 · 2026-05-26 09:59:24 +08:00
56 changed files with 5012 additions and 358 deletions
@@ -1,159 +1,107 @@
 ---
 name: sm-flow
-description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
+description: OpenSpec-first 工程流程 harness。仅在用户显式调用 /sm-flow、/sm-flow explore、/sm-flow apply、/sm-flow archive，或明确要求使用 sm-flow 流程时使用；不要根据需求类型自动触发。
 ---
 # SM Flow
-SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作流。它不替代 OpenSpec，而是用 `devflow/` 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 `devflow/` 作为长期记忆。
+SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周期。它通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。
-## 角色定位
+sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。
-你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。
+## 触发规则
-## 真理源分层
+只在用户显式调用时使用 sm-flow：
- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。
+- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。
- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
+- 用户用自然语言明确要求"使用 sm-flow"、"走 sm-flow 流程"或等价表达。
- 代码是实现结果：只能在执行真理源足够明确后修改。
+
- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
+不要根据需求类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。
- Phase 1 产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 Phase 3 的执行许可。
+
- 只有通过 Phase 2.9 提交检查后的 OpenSpec 才是 **Committed OpenSpec**；Phase 3 只能执行 Committed OpenSpec。
+## 四层架构
 ```
 sm-flow        → 编排层（harness）：阶段、门控、产物约束、人类对齐
  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
      code     → 实现结果：apply 的产出
 ```
 - OpenSpec 是唯一执行真理源：apply 阶段只能基于 OpenSpec 执行，不能绕过 OpenSpec 直接写代码。
 - devflow 是上下文真理源：术语、历史决策、验收记录来自 devflow，用于增强 OpenSpec，不替代 OpenSpec。
 - 如果 devflow 和 OpenSpec 冲突，先汇报冲突、让用户确认、修正 OpenSpec，再继续执行。
 - propose 阶段产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 apply 的执行许可。
 - 只有通过 commit 检查后的 OpenSpec 才是 **Committed OpenSpec**；apply 只能执行 Committed OpenSpec。
 ## 核心规则
- Phase 3 默认必须通过 OpenSpec apply 执行；禁止直接依赖 devflow 文档绕过 OpenSpec 写代码。
+以下 6 条是硬约束，违反即流程失败。其余约束按阶段定义在 `references/phase-contracts.md`。
 - devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。
 - devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
 - 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
 - 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
 - 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。
 - `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
 - `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
 - grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
 - 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。
 - 接口影响按 L1-L4 分级处理；接口内部判断逻辑如果改变调用方可观察行为，也属于接口影响，不能因签名未变而降级。
 - Phase 3 实现期冲突必须先分类再处理：实现偏差修代码；规格遗漏修 OpenSpec；设计冲突暂停并请用户确认；用户变更更新 proposal/specs/tasks 后再继续。
 - 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
 - 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
 - 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 2.9 后、Phase 3 前必须给用户一个简短检查点；除非用户在启动时明确要求“全自动执行”，否则不得把单个决策确认推断为执行授权。
 - Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
 - 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
 - 子 skill 绑定能力契约，不绑定单一平台路径。显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应能力的本地 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
 - fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
-## 接口影响分级
+1. **OpenSpec 是唯一执行真理源**。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。
 2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
 3. **不得跳过 grill**。必须按 `references/scales.md` 的当前分档要求完成澄清或验证。
 4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
 5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
 6. **能力来源必须显式声明**。每个阶段先声明使用外部子 skill / OpenSpec CLI / sm-flow 内置协议；外部能力不可用时可使用 `references/fallbacks.md` 的内置协议，但必须标注为 fallback。若外部能力和内置协议都不可用，流程失败。
-接口影响分级判断的是“记录在哪里、是否需要独立文档”，不是判断“是否需要关注”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或接口内部判断逻辑变化，都必须先判断接口影响。
+每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。
-| 级别 | 判断条件 | 产物要求 |
+## 用户命令
 | --- | --- | --- |
 | L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
 | L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
 | L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
 | L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
-判断策略：
+| 命令 | 用户意图 | harness 内部行为 |
 |---|---|---|
 | `/sm-flow` | 完整流程 | clarify → context → propose → grill → specify → audit → commit → apply → archive |
 | `/sm-flow explore` | 先想想 | 带上下文的探索模式 |
 | `/sm-flow apply` | 只执行 | 检查 commit gate → apply |
 | `/sm-flow archive` | 收尾 | 回填 devflow + 归档确认 |
- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
+用户也可以用自然语言指定从某个阶段继续，例如"ops-message-support 的 grill 已经做完了，继续"。harness 识别意图后，自动补做最小前置检查，然后从指定阶段继续。
- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
+
- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
+## 可见 Checkpoint
- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
+
 内部阶段不是用户 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/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`。
- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
+- archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
 - 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。
-## 启动检查
+## 内部阶段
-1. 判断启动模式：
+9 个内部阶段，按执行顺序：
   - 完整模式：用户提供粗略想法或初始 PRD。
   - Research 模式：用户已有 research，需要转成或修正 OpenSpec。
   - PRD 文件模式：用户提供已有 PRD 路径。
   - 指定阶段模式：用户要求从某个 Phase 恢复。
   - 快速模式：小改动，Phase 2 和 Phase 4 可以轻量化，但不能省略。
 2. 如果缺少 `devflow/`，初始化：
   - `devflow/projects/`
   - `devflow/glossary/CONTEXT.md`
   - `devflow/compound/`
   - `devflow/reference/`
 3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
 4. 检查 OpenSpec 和子 skill 是否可用：
   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。可由平台原生 skill、`.claude/skills/.../SKILL.md` 或 fallback 协议提供。
   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。可由平台原生 skill、`.agents/skills/.../SKILL.md` 或 fallback 协议提供。
 5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
-## 项目标识
+1. clarify — 入口澄清：接收初始需求，澄清到可生成轻量 proposal。
-
+2. context — 上下文收集：读取 devflow 的 glossary、ADR、历史项目、compound knowledge。
-整个流程使用同一个 slug：
+3. propose — 轻量 propose：只生成 proposal.md，不调用 openspec-propose。
-
+4. grill — 人类对齐澄清：evidence-driven 查证 + user-interview one-at-a-time，回写 proposal。
- 优先使用 OpenSpec change name。
+5. specify — 细化 + 对齐：基于已稳定的 proposal 补全 design/specs/tasks，做 cross-artifact 对齐。
- 如果还没有 change name，则从功能标题生成 kebab-case slug。
+6. audit — 架构审计：审计结果如果影响实现，回写 OpenSpec design/tasks。
- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
+7. commit — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
- 如果目录已存在，默认恢复该项目，不要重复创建；除非用户明确要求新开一轮。
+8. apply — OpenSpec 执行：基于 Committed OpenSpec 实现代码。
-
+9. archive — 回填 + 归档：从 OpenSpec 产物和 decisions.md 提炼长期档案，询问是否归档。
 ## Devflow 产物分层
 devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的执行产物。默认只创建必要文件；扩展文件必须有明确理由。
 **必须产物**：
 - `brief.md`：背景、目标、范围、非目标、变更规模、关联 OpenSpec change。
 - `evidence.md`：代码证据、文档证据、历史决策、evidence-driven 结论和汇报状态。
 - `decisions.md`：user-interview 问题、用户确认、关键取舍、风险接受、OpenSpec 回写记录。
 - `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
 **按需产物**：
 - `prd.md`：需求复杂、用户明确要求 PRD、或需要对外协作时创建；小需求并入 `brief.md`。
 - `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较时创建。
 - `design.md`：仅记录 OpenSpec design 不适合承载的人类背景、架构审计摘要或长期决策索引；实现设计仍以 OpenSpec design 为准。
 - `tasks.md`：仅记录跨轮次追踪或人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
 - `alignment.md` / `clarifications.md`：问题很多或冲突复杂时单独创建；否则并入 `decisions.md`。
 - `adr/*.md` 和 `compound/*.md`：仅在满足 ADR/复合知识规则时创建。
 **规模分档**：
 - `micro`：小且低风险，使用 `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md`。
 - `standard`：默认模式，使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。
 - `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加 PRD/research/design/tasks/alignment。
 ## 阶段总览
 1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
 2. Phase 0.5 — Devflow 上下文收集：先查 `devflow/index.md`，再读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
 3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 Draft OpenSpec proposal/design/specs/tasks。
 4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
 5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
 6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
 7. Phase 2.9 — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
 8. Phase 3 — OpenSpec apply：默认依赖 Committed OpenSpec 执行；devflow 只作为上下文参考。
 9. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，更新 `devflow/index.md`，并询问是否 archive OpenSpec change。
 每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
 关键阶段的完成判断也以 `references/phase-contracts.md` 为准；如果缺少显式 checkpoint 或能力来源声明，该阶段不得视为已完成。
 ## 快速模式
-快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留：
+快速模式的具体约束见 `references/operating-rules.md`。
 - Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
 - Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
 - Phase 2.9 提交检查：即使快速模式也必须确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
 - Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
 - Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
 ## 完成标准
-一次流程只有在满足以下条件时才算完成：
+流程完成标准见 `references/operating-rules.md`。
 - OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。
 - 实现或规划任务已经完成，且执行依据来自 OpenSpec。
 - 已运行验证，或明确记录未运行验证的原因。
 - `devflow/projects/YYYY-MM-DD-{slug}/` 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。
 - 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。
@@ -1,6 +1,49 @@
-# 归档规则
+# 归档规则
-Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。
+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,12 +53,12 @@ Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为
 devflow/projects/YYYY-MM-DD-{slug}/
 ```
-默认创建以下必要文件：
+archive 阶段按 `references/scales.md` 的当前分档创建以下文件：
- `brief.md`
+- `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
- `evidence.md`
+- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取；是否独立创建按 `references/scales.md` 执行。
- `decisions.md`
+- `decisions.md`：保持为最终版，整理格式。
- `acceptance.md`
+- `acceptance.md`：从实现结果和验证结果提取。
 同时维护仓库级索引：
@@ -34,21 +77,18 @@ devflow/projects/YYYY-MM-DD-{slug}/
 ## 产物分档
-| 分档 | 适用场景 | 必须文件 | 扩展文件 |
+分档的适用场景和必须文件见 `references/scales.md`。本文件只定义 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` |
 ## 提取映射
 | 来源 | 提取内容 | 写入位置 |
 | --- | --- | --- |
 | `decisions.md`（过程日志） | question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍 | `decisions.md`（整理格式为最终版） |
 | `decisions.md`（过程日志） | evidence-driven 结论、代码/文档证据 | `evidence.md` |
 | `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` |
 | `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` |
 | `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 |
 | `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` |
 | 澄清记录 | evidence-driven/user-interview、证据、结论、确认状态 | `evidence.md` + `decisions.md` |
 | 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` |
 | diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
 | 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
@@ -57,7 +97,7 @@ devflow/projects/YYYY-MM-DD-{slug}/
 ## 索引维护规则
-`devflow/index.md` 是 Phase 0.5 的默认入口，Phase 4 回填时必须维护。
+`devflow/index.md` 是 context 阶段的默认入口，archive 阶段回填时必须维护。
 最小字段：
@@ -67,9 +107,9 @@ devflow/projects/YYYY-MM-DD-{slug}/
 规则：
 - 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
- Phase 4 新建或更新项目档案时，必须新增或更新对应行。
+- archive 阶段新建或更新项目档案时，必须新增或更新对应行。
 - 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
- 关键词只放能帮助 Phase 0.5 定位的术语，不复制 brief 内容。
+- 关键词只放能帮助 context 阶段定位的术语，不复制 brief 内容。
 - 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。
 ## 验收记录规则
@@ -85,7 +125,7 @@ devflow/projects/YYYY-MM-DD-{slug}/
 - 如果验证通过，记录命令/步骤和覆盖范围。
 - 如果验证失败，记录失败摘要和是否阻塞验收。
- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。
+- 如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。
 ## ADR 规则
@@ -111,19 +151,17 @@ devflow/compound/YYYY-MM-DD-decision-{slug}.md
 OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息：
- Phase 4 可以建议 archive，但必须先询问用户。
+- archive 阶段可以建议 archive，但必须先询问用户。
 - 在用户确认前，不要执行 archive。
 - 如果用户暂不归档，在 acceptance 中记录原因或状态。
 - 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。
 ## 归档交接
-Phase 4 结束时告诉用户：
+archive 阶段结束时告诉用户：
 - 创建或更新了哪些档案文件。
 - `devflow/index.md` 是否已更新。
 - 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
 - 还剩哪些风险或后续事项。
 - 明确询问：是否现在 archive OpenSpec change？
@@ -1,109 +1,49 @@
-# Fallback 协议
+# 内置执行协议
-当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。
+本文件只在外部 OpenSpec CLI 或子 skill 不可用时使用。fallback 不是跳过阶段，而是由 sm-flow 用文件方式完成同等最小产物。每次使用 fallback 都必须写入 `decisions.md` 或 `acceptance.md`，说明能力来源、缺失能力、影响和剩余风险。
-## OpenSpec 提案 fallback
+## 通用规则
-1. 创建或识别 `openspec/changes/{slug}/`。
+- 优先使用外部能力；只有不可用、不可发现或无法在当前环境调用时才使用内置协议。
-2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。
+- 不得因为使用 fallback 跳过 context、grill、commit、apply 授权或 archive 确认。
-3. 写入 `proposal.md`，包含：
+- fallback 产物仍写入 `openspec/changes/{slug}/` 和 `devflow/projects/YYYY-MM-DD-{slug}/`。
-   - 问题
+- 如果内置协议也无法满足阶段退出条件，暂停并向用户说明阻塞项。
   - 建议方案
   - 范围
   - 非目标
   - 来自 devflow 的上下文约束
   - 风险
 4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。
 5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。
 6. 只为外部可见行为或发生变化的需求编写 specs。
 7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。
-## OpenSpec 修正 fallback
+## grill 内置协议
-当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：
+- 建立 question pool，至少覆盖术语、边界、验收；涉及参考实现或项目基础设施时加入技术实现问题。
 - 将问题标记为 `evidence-driven` 或 `user-interview`。
 - 先查证 evidence-driven 问题并汇报结论，再逐个询问 user-interview 问题。
 - 按 `references/scales.md` 的当前分档满足 grill 要求。
 - 将 question pool、证据结论、用户原话和确认状态写入 `decisions.md`；影响实现的结论回写 `proposal.md`。
-1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。
+## openspec 提案内置协议
 2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。
 3. 向用户汇报冲突和推荐修正。
 4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
 5. 再同步更新 devflow 文档；不要只改 devflow。
-## OpenSpec 执行 fallback
+- 在 `openspec/changes/{slug}/` 创建或更新：
  - `proposal.md`：问题、方案、范围、非目标、上下文约束、风险。
  - 设计产物：实现设计、接口影响、关键决策、架构风险；形式按 `references/scales.md` 的当前分档要求执行。
  - `specs/*/spec.md` 或等价 functional spec：描述用户可观察行为和验收场景。
  - `tasks.md`：按可执行切片拆分任务，并给每项写可验证验收标准。
 - 运行 cross-artifact 对齐检查：proposal → 设计产物 → specs → tasks。
 - 如果发现 gap，先修正 OpenSpec，再进入 commit。
-仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。
+## audit 内置协议
-1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
+- 用 5 句话以内说明模块链路、数据所有权、跨模块依赖、架构风险和是否需要回写 OpenSpec。
-2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
+- 如果风险影响实现，修正设计产物或 `tasks.md`。
-3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
+- 将结论写入 `decisions.md`。
 4. 确认 Phase 2.9 后已经获得用户明确的 Phase 3 apply 授权；单个 grill 决策确认不能替代 apply 授权。
 5. 修改前先检查现有代码。
 6. 一次实现一个 OpenSpec task 的纵向切片。
 7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，先分类：
   - 实现偏差：OpenSpec 正确，代码偏离；修代码。
   - 规格遗漏：OpenSpec 未覆盖真实边界、接口影响或验收；暂停执行，修正 OpenSpec 并重新提交后继续。
   - 设计冲突：OpenSpec 与架构、ADR、历史验收或模块边界冲突；暂停并等待用户确认。
   - 用户变更：用户改变目标、范围、验收或风险接受度；更新 proposal/specs/tasks 后继续。
 8. 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
 9. 用最窄但有效的命令验证每个切片。
 10. 只有验证通过或明确记录原因后，才更新 task 状态。
 11. 如果失败原因不确定，停止并进入 diagnose。
 12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
-## PRD fallback
+## openspec apply 内置协议
-优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。
+- 只依据 Committed OpenSpec 的 specs/tasks 实现；devflow 只作上下文参考。
 - 开始前检查 `.committed` 文件；缺失则返回 commit。
 - 如触发 pre-apply checkpoint，先阅读参考实现、grep 项目基础设施模式，并把技术栈清单写入 `decisions.md`。
 - 按 tasks 的纵向切片实现、验证并更新任务状态。
 - 发现冲突时按三类处理：OpenSpec 不准则修 OpenSpec，代码偏离则修代码，不确定则暂停等用户确认。
-规则：
+## openspec archive 内置协议
 - 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。
 - `brief.md` 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。
 - 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。
 ## 文档化追问 fallback
 1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。
 2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。
 3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。
 4. 对 user-interview 问题，一次只问一个并等待用户确认。
 5. 术语确认后立即更新词汇表。
 6. 影响实现的澄清必须回写 OpenSpec。
 7. 只为难以逆转的真实权衡创建 ADR。
 快速模式的最小问题：
 - 术语：这个概念应该使用哪个领域术语？证据是什么？
 - 边界：哪些内容明确不在范围内？是否需要用户确认？
 - 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？
 ## 架构审计 fallback
 产出一份短架构审计：
 1. 画出输入 → 处理 → 输出。
 2. 列出相关模块和调用方。
 3. 识别耦合、数据所有权和生命周期风险。
 4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。
 5. 用不超过五句话总结最大风险。
 6. 如果影响实现，回写 OpenSpec design/tasks。
 ## Diagnose fallback
 1. 复现问题，或捕获准确失败信息。
 2. 最小化失败案例。
 3. 生成 3-5 个假设，并按可能性和验证成本排序。
 4. 修改代码前，先添加仪器化或定向检查。
 5. 判断根因属于实现问题还是 OpenSpec 规格问题。
 6. 如果是实现问题，修复被证明的最小原因。
 7. 如果是规格问题，先修正 OpenSpec，再继续 apply。
 8. 运行回归验证。
 ## TDD fallback
 使用纵向切片，不要水平批量写测试：
 1. 从 OpenSpec specs 中选择一个外部可见行为。
 2. 写一个失败测试。
 3. 实现刚好让测试通过的最小代码。
 4. 只在测试通过时重构。
 5. 对下一个 OpenSpec 行为重复以上步骤。
 - 不删除或移动 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 |
@@ -0,0 +1,120 @@
 # 运行规则
 本文件承载稳定但不必放在顶层 `SKILL.md` 的运行规则。
 ## 接口影响分级
 接口影响分级判断的是"记录在哪里、是否需要独立文档"，不是判断"是否需要关注"。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或内部决策逻辑变化，都必须先做分级。
 | 级别 | 判断条件 | 产物要求 |
 | --- | --- | --- |
 | L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
 | L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
 | L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
 | L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
 判断策略：
 - 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
 - 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
 - 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
 - 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
 ## 启动检查
 1. 识别用户命令意图：
   - `/sm-flow`（无参数）：完整流程，从 clarify 开始。
   - `/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；具体分档规则见 `references/scales.md`。
 3. 如果缺少 `devflow/`，初始化：
   - `devflow/projects/`
   - `devflow/glossary/CONTEXT.md`
   - `devflow/compound/`
 4. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
 5. 检查 OpenSpec 和子 skill 是否可用：
   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。
   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。
 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`；无论分档如何，都不要把内部阶段名当作用户操作入口。
 ## 项目标识规则
 - 整个流程使用同一个 slug。
 - 优先使用 OpenSpec change name。
 - 如果还没有，则从功能标题生成 kebab-case slug。
 - 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
 - 如果目录已存在，默认恢复该项目；除非用户明确要求新开一轮。
 ## Devflow 产物分层
 Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec 的执行产物。
 **过程日志**（clarify → apply 期间维护）：
 - `decisions.md`：question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍、风险接受、OpenSpec 回写记录、冲突分类记录。
 **最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）：
 - `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。
 - `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态；分档要求见 `references/scales.md` 和 `references/archive-rules.md`。
 - `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
 **按需产物**（archive 阶段按需创建）：
 - `prd.md`：需求复杂、用户明确要求、或需要对外协作。
 - `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较。
 - `design.md`：不适合放进 OpenSpec design 的长期背景或架构审计摘要。
 - `tasks.md`：跨会话的人类追踪；执行任务仍属于 OpenSpec。
 - `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用。
 - `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用。
 **规模分档**：`micro / standard / complex` 的唯一规则源是 `references/scales.md`。
 ## 快速模式
 快速模式适用于 `references/scales.md` 定义的 micro 变更。它合并 gate 而不仅仅是压缩产物；具体覆盖规则见 `references/scales.md`。
 无论什么模式，以下内容必须保留：
 - context 最小上下文收集：至少检查 glossary 和相关 ADR。
 - grill 最小澄清：按 `references/scales.md` 当前分档要求执行；evidence-driven 结论仍需汇报。
 - commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行；完整性检查按 `references/scales.md` 当前分档要求执行。
 - apply 仍由 OpenSpec tasks/specs 驱动执行。
 - archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。
 ## 完成标准
 只有同时满足以下条件，流程才算完成：
 - 用户可见的 Discover、Commit、Apply、Archive checkpoint 已完成，或未完成项已明确标记为暂停/不适用。
 - OpenSpec proposal、设计产物、specs、tasks 已按当前分档生成或更新到可执行状态。
 - 实现或规划工作已完成，且执行依据来自 OpenSpec。
 - 已运行验证，或已记录未运行验证的原因。
 - `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案。
 - 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。
@@ -1,8 +1,22 @@
-# 阶段契约
+# 阶段契约
-本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：**devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。
+本文件是 SM Flow 的逐阶段执行准则。核心原则：**sm-flow 编排 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。
-## Phase 0 — 入口澄清
+执行顺序：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。
@@ -11,6 +25,7 @@
 - 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
 - 如果输入过于模糊，最多追加三轮聚焦问题。
 - 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
 - 如果需要判断 `micro / standard / complex` 分档，补读 `references/scales.md`。
 **退出条件**：
 - 问题可以用 1-2 句话说清楚。
@@ -23,9 +38,9 @@
 - 初步 slug。
 - devflow 规模分档：`micro` / `standard` / `complex`。
-## Phase 0.5 — Devflow 上下文收集
+## context — 上下文收集
-**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
+**进入条件**：clarify 已经有足够信息定位领域、项目或变更方向。
 **动作**：
 - 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
@@ -33,117 +48,134 @@
 - 读取 `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` 冲突，暂停并向用户汇报。
 **退出条件**：
- 已形成“OpenSpec 输入上下文摘要”。
+- 已形成"OpenSpec 输入上下文摘要"。
 - 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
 - 已列出相关 ADR 和不能违反的历史决策。
 - 已列出需要写入或修正 OpenSpec 的上下文点。
 **输出**：
- 上下文摘要，默认写入 `brief.md` 或 `evidence.md`；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。
+- 上下文摘要，写入 `decisions.md`（过程日志）。会影响实现的上下文必须标记为"需进入 OpenSpec"。
-## Phase 1 — OpenSpec propose
+## propose — 轻量 propose
-**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
+**进入条件**：clarify + context 已经足够生成轻量 proposal。
-**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 `openspec-propose` 的 `SKILL.md` / fallback 降级。
+**执行者**：sm-flow 内置协议。**不调用 openspec-propose**（完整 OpenSpec 产物留待 specify 阶段生成）。
 **动作**：
- 优先调用 `openspec-propose`。
+- 创建或识别 `openspec/changes/{slug}/`。
- 如果不可用，执行 `references/fallbacks.md#openspec-propose-fallback`，但仍必须产出 OpenSpec 文件。
+- 写入 `proposal.md`，包含：问题、建议方案、范围、非目标、来自 devflow 的上下文约束、风险。
- 用 Phase 0.5 的 devflow 上下文增强 OpenSpec：
+- **不生成 design.md、specs/、tasks.md**——这些留待 grill 澄清需求后在 specify 阶段补全。
-  - proposal 写清为什么做、做什么、范围和非目标。
+- 用 context 阶段的 devflow 上下文增强 proposal。
-  - design 写入上下文约束、历史 ADR、关键技术决策。
+- 在承诺方案方向前，先检查相关仓库代码。
  - specs 写成可验收的外部行为。
  - tasks 写成可执行的纵向切片。
 - 在承诺设计细节前，先检查相关仓库代码。
 **退出条件**：
- `openspec/changes/<slug>/proposal.md` 存在。
+- `openspec/changes/{slug}/proposal.md` 存在。
- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。
+- 关键假设已显式记录。
 - 关键假设已显式记录在 OpenSpec 或 research 中。
 **输出**：
- Draft OpenSpec proposal、design、specs 和 task list。
+- Draft OpenSpec proposal.md（轻量版）。
 **Human checkpoint**：
- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
+- 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。
- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。
+- 作为 Discover checkpoint 的中间状态汇报；询问是否继续完成 Discover 的人类澄清部分。用户明确要求"全自动执行"时可跳过等待。
-## Phase 1.5 — PRD / OpenSpec 对齐
+## grill — 人类对齐澄清
-**进入条件**：Phase 1 已有 OpenSpec 产物。
+**进入条件**：propose 已有轻量 proposal.md。
-**显式子 skill**：`to-prd` + `sm-flow`。进入本阶段必须先声明是否读取 `.agents/skills/to-prd/SKILL.md`；如果使用内置模板，标记为 PRD fallback。
+**能力来源**：优先使用 `grill-with-docs`；不可用时使用 `references/fallbacks.md#grill-内置协议`，并在 `decisions.md` 标注 fallback。
 **动作**：
 - 如果没有结构化 PRD，则优先按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
 - `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 `brief.md`。
 - 检查 PRD、devflow 上下文和 OpenSpec 是否一致：
  - OpenSpec 是否覆盖 PRD 的用户故事和验收预期。
  - OpenSpec 是否使用 glossary 中的正确术语。
  - OpenSpec 是否遵守相关 ADR。
  - specs 是否能表达可观察行为。
  - tasks 是否能驱动实现，而不是泛泛描述。
 - 检查是否涉及接口影响：
  - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
  - 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
  - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 `user-interview` 问题。
 - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
 **退出条件**：
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - OpenSpec 与 PRD/devflow 上下文没有已知冲突。
 - 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
 - 所有已知冲突已修正或等待用户决策。
 **输出**：
 - `brief.md`，以及按需创建的 `prd.md`。
 - OpenSpec 对齐检查记录。
 - 必要的 OpenSpec 修正。
 ## Phase 2 — Human-in-the-loop 澄清
 **进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。
 **显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。
 **动作**：
 - 优先使用 `grill-with-docs`。
- 先声明本阶段采用的澄清模式，并逐项标记：
+- 进入 grill 时先建立一个 question pool，并记录到 `decisions.md`：
  - 默认至少覆盖术语、边界、验收三个维度。
  - **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
    - 参考实现的具体文件路径是什么？
    - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
    - 有哪些技术点需要先调研或新建？
  - 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。
 - 逐项标记每个问题的模式：
  - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
  - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
- 至少覆盖三个维度：术语、边界、验收。
+- evidence-driven 和 user-interview 的推进节奏：先批量查证 evidence-driven 并一次性汇报结论，再逐个处理 user-interview 问题。不要把所有问题攒到最后一起问。
 - 一次只问一个 `user-interview` 问题。
- 每个 `user-interview` 问题必须等待用户显式回答，并把回答、决策和 OpenSpec 回写状态记录到 `decisions.md`；不能由代理代替用户确认。
+- 每个 `user-interview` 问题必须等待用户显式回答，并在 decisions.md 中记录：问题原文、用户原话、确认状态（已确认/未确认）。未确认的问题不能从 question pool 移除。
- 未获得用户确认的 `user-interview` 问题必须保持未解决状态，不能进入 Phase 2.9 或 Phase 3。
+- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 apply 或修改执行目标文件的授权。
 - 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 Phase 3 或修改执行目标文件的授权。
 - 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
+- 如果澄清结果影响实现，必须回写 proposal.md。
 - 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
 - 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
 **退出条件**：
- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
+- question pool 已建立并覆盖当前 change 所需维度。
 - 已满足 `references/scales.md` 中当前分档的 grill 要求。每个问题都必须记录属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
 - 没有未解决或代理代确认的 user-interview 问题。
 - 没有未判级或未确认的接口影响问题。
- 影响实现的结论已回写 OpenSpec。
+- 影响实现的结论已回写 proposal.md。
 - 单个 grill 决策确认不等于 apply 授权；grill 完成后必须停在 commit，等待用户明确要求进入 apply。
 - question pool、evidence-driven 结论、user-interview 确认必须写入 `decisions.md` 文件，不能只记录在对话中。
 **输出**：
- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。
+- 更新后的 proposal.md。
- 更新后的 OpenSpec。
+- 澄清记录：写入 `decisions.md`。包含 question pool、evidence-driven 汇报状态、user-interview 确认状态。
 - 更新后的词汇表和 ADR。
-## Phase 2.5 — 架构审计
+**Human checkpoint**：
 - 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。
 - 汇报 Discover checkpoint 完成情况，并询问是否继续进入 Commit checkpoint。
-**进入条件**：Phase 2 已解决主要产品、领域和验收问题。
+## specify — 细化 + 对齐
-**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。
+**进入条件**：grill 已退出，需求已通过澄清稳定下来。
 **能力来源**：优先使用 `openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；按需使用 `to-prd`。进入本阶段必须先声明调用方式；外部能力不可用时使用 `references/fallbacks.md#openspec-提案-内置协议`，并在 `decisions.md` 标注 fallback。
 **动作**：
 - 基于已稳定的 proposal.md 补全设计产物、specs/、tasks.md：
  - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需按当前分档补全设计产物/specs/tasks"。
  - 如果不可用，执行 `references/fallbacks.md#openspec-提案-内置协议`。
 - 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
 - 独立 PRD 是否需要按 `references/scales.md` 的当前分档和用户要求判断。
 - 用 grill 阶段的 decisions.md 记录增强 OpenSpec 产物：确保 design/specs/tasks 反映所有已确认的决策。
 - **显式 cross-artifact 对齐检查**——在 checkpoint 中输出对齐检查表：
  - `brief/prd` 中的目标、范围、非目标和验收预期 → `proposal` 是否覆盖。
  - `proposal` 中的范围、约束和关键承诺 → `design` 是否覆盖。
  - `design` 中影响实现的约束、接口影响和架构结论 → `specs` 或 `tasks` 是否覆盖。
  - `specs` 中的可观察行为 → `tasks` 是否覆盖为可执行切片。
  - 每项标记：已对齐 / 存在 gap。
 - 检查是否涉及接口影响：
  - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
  - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
  - 接口内部判断逻辑是否改变调用方可观察行为。
  - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 `user-interview` 问题。
 - 如果存在 gap，在进入下一阶段前修复 OpenSpec。
 - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
 **退出条件**：
 - OpenSpec 细化产物存在且与 proposal 对齐；产物形态按 `references/scales.md` 的当前分档要求执行。
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。
 - 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。
 - 所有已知冲突已修正或等待用户决策。
 **输出**：
 - Draft OpenSpec：按 `references/scales.md` 的当前分档要求生成 proposal、设计、specs 和 tasks。
 - `brief.md`，以及按需创建的 `prd.md`。
 - cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。
 - 必要的 OpenSpec 修正。
 ## audit — 架构审计
 **进入条件**：specify 已退出，完整 OpenSpec 产物已存在。
 **能力来源**：优先使用 `zoom-out`；不可用时使用 `references/fallbacks.md#audit-内置协议`，并在 `decisions.md` 标注 fallback。
 **动作**：
 - 画出输入 → 处理 → 输出的模块链路。
@@ -151,25 +183,26 @@
 - 检查是否与既有架构、ADR、OpenSpec design 冲突。
 - 用不超过五句话写出架构风险评估。
 - 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
 - 审计结论写入 `decisions.md`。
 **退出条件**：
- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。
+- 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。
- OpenSpec design/tasks 已反映会影响实现的架构审计结论。
+- OpenSpec 设计产物/tasks 已反映会影响实现的架构审计结论。
 **输出**：
- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。
+- 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。
- 必要的 OpenSpec design/tasks 修正。
+- 必要的 OpenSpec 设计产物/tasks 修正。
 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
- 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。
+- 作为 Commit checkpoint 的中间状态汇报；询问是否继续完成 commit gate。
-## Phase 2.9 — Commit OpenSpec
+## commit — Commit OpenSpec
 **进入条件**：
- Phase 2 已解决术语、边界、验收三个维度的高价值问题。
+- grill 已满足 `references/scales.md` 中当前分档要求。
 - 所有 `user-interview` 问题都已获得用户显式确认。
- Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因。
+- audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。
 - Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
 **动作**：
@@ -177,51 +210,110 @@
 - 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
 - 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
 - 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
- 检查接口影响是否已按 L1/L2/L3/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
+- 复核 cross-artifact 对齐：`brief/prd → proposal → 设计产物 → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。
 - 检查 `decisions.md` 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。
 - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
 - 检查接口影响是否已按 L1/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
 - 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
- 如果检查失败，返回 Phase 1、Phase 2 或 Phase 2.5 修正 Draft OpenSpec。
+- 如果检查失败，返回 propose、grill、specify 或 audit 修正 Draft OpenSpec。
 **退出条件**：
 - Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
- Phase 3 所需的 proposal、design、specs 和 tasks 均存在且一致。
+- **文件完整性检查**（按 `references/scales.md` 的当前分档要求执行）：
- 所有 Phase 3 preflight 风险已消除或明确记录为已接受。
+  - [ ] proposal 存在，且足以说明问题、建议方案、范围和非目标。
  - [ ] 设计产物存在，形式符合当前分档要求。
  - [ ] specs 存在，且表达用户可观察行为。
  - [ ] tasks 存在，且任务可执行、验收标准可验证。
 - **一致性检查**（必须通过）：
  - [ ] proposal 中的核心概念在设计产物中有对应设计
  - [ ] 设计产物中的关键决策在 tasks 中有对应实现任务
  - [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
 - **标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
 - 所有 preflight 风险已消除或明确记录为已接受。
 **输出**：
 - Committed OpenSpec 状态说明。
- Phase 3 preflight 检查结果，默认写入 `decisions.md` 或 `acceptance.md`。
+- preflight 检查结果，写入 `decisions.md` 或 `acceptance.md`。
 **Human checkpoint**：
 - 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
- 询问是否进入 Phase 3 OpenSpec apply；除非用户在启动时明确要求“全自动执行”，必须等待用户明确说出进入 apply、开始实现、执行修改、继续 Phase 3 或等价授权。
+- 汇报 Commit checkpoint 完成情况，并询问是否进入 Apply checkpoint；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
- 不得把 Phase 2 的单个 grill 决策确认当作本 checkpoint 的授权。
+- 不得把 grill 的单个决策确认当作本 checkpoint 的授权。
-## Phase 3 — OpenSpec apply
+## apply — OpenSpec 执行
 **进入条件**：
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已通过 Phase 2.9，成为 Committed OpenSpec。
+- `openspec/changes/{slug}/` 中 proposal、设计产物、specs、tasks 已通过 commit，成为 Committed OpenSpec。
- Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。
+- **前置门控检查**（硬约束）：
  - 检查 `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`。进入本阶段必须先声明调用方式，不能静默 fallback。
+**能力来源**：优先使用 `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 的纵向切片实现。
- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续：
+- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
-  - 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。
+- 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 apply 不算真正开始。
-  - 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。
+- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
-  - 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。
+- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，做三类判断：
-  - 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。
+  - OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停 apply，修正 OpenSpec 后重新提交。
- 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
+  - 代码偏离（实现没按 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 占位。
 - 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。
@@ -229,26 +321,32 @@
 **输出**：
 - 代码变更、必要测试和实现说明。
 - 更新后的 OpenSpec task 状态。
 - 冲突记录写入 `decisions.md`。
-## Phase 4 — 回填 Devflow
+## archive — 回填 + 归档
 **进入条件**：实现或规划工作已经达到可交接状态。
-**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。
+**能力来源**：`openspec-archive-change` 在用户确认 archive 后优先调用；不可用时使用 `references/fallbacks.md#openspec-archive-内置协议`，并在 `acceptance.md` 标注 fallback。archive 回填由 `sm-flow` 执行。
 **动作**：
 - 遵循 `references/archive-rules.md`。
- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
+- 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案：
  - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
  - `evidence.md`：按 `references/scales.md` 和 `references/archive-rules.md` 的当前分档要求处理。
  - `decisions.md`：保持为最终版，整理格式。
  - `acceptance.md`：从实现结果和验证结果提取。
 - 只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
 - 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
 - 如果本次流程产生可复用经验，写入 compound knowledge。
 - 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。
 **退出条件**：
- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
+- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
 - `devflow/index.md` 已包含或更新本项目条目。
 - 用户已被询问是否 archive OpenSpec change。
 **输出**：
- 默认输出 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`；按需输出 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`、ADR 和 compound knowledge。
+- 完整 devflow 档案。
-
+- 归档交接清单：创建或更新了哪些文件、验证分类、剩余风险、是否 archive。
@@ -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。
@@ -51,11 +51,25 @@
 ```markdown
 # {标题} Decisions
 ## Question Pool
 | # | 维度 | 问题 | 模式 | 状态 |
 |---|---|---|---|---|
 | Q1 | 术语 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
 | Q2 | 边界 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
 | Q3 | 验收 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
 ## Evidence-driven
 | 结论 | 证据来源 | 是否已汇报用户 |
 |---|---|---|
 | {conclusion} | {file/doc/test/ADR} | 已汇报 / 待汇报 |
 ## User-interview
-| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
+| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
-| --- | --- | --- | --- |
+|---|---|---|---|
-| {question} | {answer} | {decision} | 已回写 / 不影响 / 待回写 |
+| {question} | {user's exact words} | 已确认 / 未确认 | 已回写 / 不影响 / 待回写 |
 ## 关键取舍
@@ -110,7 +124,7 @@
 - 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
 - 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更
+- 分类：OpenSpec 不准 / 代码偏离 / 不确定
 ## 证据
@@ -122,7 +136,7 @@
 - 决策：
 - 是否需要用户确认：是 / 否
- OpenSpec 回写：不需要 / 已回写 / 待回写
+- OpenSpec 回写：不需要 / 已回写 / 待回写 / 等待用户确认
 - 代码处理：
 - 验证方式：
 ```
@@ -329,6 +343,26 @@
 - OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用}
 ```
 ## Cross-Artifact 对齐检查表模板
 specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"或"存在 gap"。
 ```markdown
 ## Cross-Artifact 对齐检查
 | 上游 → 下游 | 检查内容 | 状态 |
 |---|---|---|
 | brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap |
 | proposal → 设计产物 | 范围、约束、关键承诺是否进入 design.md 或等价设计小节 | 已对齐 / 存在 gap |
 | 设计产物 → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
 | specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap |
 ### Gap 详情（如有）
 - gap 1：{描述哪个字段/约束/行为/切片只停留在上游，未进入下游}
  - 修复：{如何修正 OpenSpec}
 ```
 ## 复合知识模板
 ```markdown
@@ -1,4 +1,5 @@
 skill-workbench/validation/project/
 superpowers/
 .claude/
 .codex/
 *.stackdump
@@ -9,3 +9,6 @@
 | 2026-05-19 | add-year-filter | knowledge-index | year-filter, index-panel, frontmatter | `openspec/changes/add-year-filter/` | active |
 | 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,40 @@
 # SM Flow Execution Hardening Acceptance
 ## Result
 Implemented `sm-flow-execution-hardening` as protocol/document changes only.
 Updated artifacts:
 - `.agents/skills/sm-flow/SKILL.md`
 - `.agents/skills/sm-flow/references/phase-contracts.md`
 - `.agents/skills/sm-flow/references/fallbacks.md`
 - `skill-workbench/docs/sm-flow/workflow.md`
 - `openspec/changes/sm-flow-execution-hardening/tasks.md`
 ## Verification
 - Static verification:
  - Confirmed explicit phase checkpoint and stage-completion rules exist in `SKILL.md`.
  - Confirmed Phase 2 question-pool behavior and Phase 1.5 / 2.9 cross-artifact checks exist in `phase-contracts.md`.
  - Confirmed fallback declaration and recording requirements exist in `fallbacks.md`.
  - Confirmed `workflow.md` explains the same execution-hardening model without introducing mandatory output templates.
 - OpenSpec verification:
  - Implementation/documentation tasks `1.1` to `3.2` are complete.
  - Validation tasks `4.1` to `4.4` are complete.
 ## Acceptance Scope Check
 - Satisfied by protocol/document changes alone: yes
 - Requires standardized phase-report output format: no
 - Requires fixed checkpoint/alignment templates: no
 ## Unverified
 - OpenSpec CLI validation passed: `openspec validate sm-flow-execution-hardening`.
 - No automated tests were needed because this change only modifies protocol and documentation artifacts.
 ## Archive Status
 - OpenSpec change is not archived.
 - User still needs to be asked whether to archive after validation is complete.
@@ -0,0 +1,31 @@
 # SM Flow Execution Hardening Brief
 ## 背景
 - 用户目标：把 `sm-flow` 在真实项目执行中暴露出的流程失真问题，提炼为下一轮协议硬化需求。
 - 当前问题：`sm-flow` 已经具备完整阶段规则，但实际执行时仍会出现跳过检查点、弱化显式声明、问题池不足、Cross-artifact 一致性检查不充分等情况。
 - 关联 OpenSpec：`openspec/changes/sm-flow-execution-hardening/`
 - devflow 分档：complex
 ## 范围
 - 本次要做：把复盘中的执行问题整理为结构化需求，明确目标、非目标、用户故事、验收口径和建议改进方向。
 - 本次不做：立即修改 `sm-flow` 协议、直接创建 OpenSpec change、重写 `sm-flow` 主设计。
 - 影响区域：
  - `.agents/skills/sm-flow/SKILL.md`
  - `.agents/skills/sm-flow/references/phase-contracts.md`
  - `.agents/skills/sm-flow/references/fallbacks.md`
  - `.agents/skills/sm-flow/references/templates.md`
  - `skill-workbench/docs/sm-flow/workflow.md`
  - `skill-workbench/docs/sm-flow/retrospective.md`
 ## OpenSpec 对齐
 - proposal 覆盖状态：已覆盖
 - specs 覆盖状态：已覆盖
 - tasks 覆盖状态：已覆盖
 ## 入口摘要
 - 这次需求关注的不是 `sm-flow` 的理念是否成立，而是它在真实执行中为什么仍然会“按代码习惯行动”，而不是“按 phase gate 行动”。
 - 目标是把这些问题固化为更强的执行约束，让后续代理在 `micro` 或 `standard` 模式下也不再轻易跳过关键阶段。
@@ -0,0 +1,76 @@
 # SM Flow Execution Hardening Decisions
 ## User-interview
 | 问题 | 用户回答 | 决策 | OpenSpec 回写 |
 | --- | --- | --- | --- |
 | 这次是否将复盘问题提炼为正式需求？ | “[$sm-flow] 提炼成需求” | 创建 `sm-flow-execution-hardening` 需求档案，先收敛需求，再决定是否进入 OpenSpec。 | 不影响 |
 | 是否必须产出固定 checkpoint / alignment 模板？ | “确认 1” | 不强制固定模板；协议只要求必填字段和检查动作。 | 已回写 |
 | 验收是否要求统一阶段汇报格式？ | “确认1” | 验收停在协议明确 gate、问题池和对齐规则，不要求统一阶段汇报格式。 | 已回写 |
 ## Phase 2 Tracking
 | 问题池项 | 模式 | 状态 | 备注 |
 | --- | --- | --- | --- |
 | Q1：是否必须产出固定 checkpoint / alignment 模板 | user-interview | 待确认 | 会影响 templates.md 与 tasks 范围 |
 | Q2：协议主术语采用 checkpoint 还是 checklist | evidence-driven | 待整理 | 优先由现有文档术语一致性决定 |
 | Q3：验收是否要求统一阶段汇报格式 | user-interview | 已确认 | 验收停在规则层，不扩到统一输出格式 |
 | Q4：workflow 是否需要保留复盘案例示例 | evidence-driven | 待整理 | 主要影响 workflow 文档粒度 |
 ## Phase 2.5 审计结论
 - 决策：主术语采用 `checkpoint`，`checklist` 作为内部核对动作描述。
  - 原因：仓库现有 `phase-contracts.md` 已使用 `Human checkpoint`，继续沿用能减少术语漂移。
  - 影响：后续协议修改应优先写“phase checkpoint”，避免在规则层混用主术语。
  - 风险接受：当前接受
 - 决策：`workflow.md` 不扩成案例手册，继续保留规则抽象和演进说明；具体复盘案例留在 `retrospective.md`。
  - 原因：如果把案例并入 workflow，规则与示例会双份维护，后续更容易漂移。
  - 影响：执行真理源继续留在 `SKILL.md` / `phase-contracts.md` / OpenSpec，而不是 workflow 长文。
  - 风险接受：当前接受
 ## Phase 2.9 Commit Result
 - 决策：`sm-flow-execution-hardening` 当前 Draft OpenSpec 通过 commit gate，视为 Committed OpenSpec。
  - 原因：proposal、design、specs、tasks 已完整；user-interview 已确认；evidence-driven 结论已汇报；未发现 devflow/OpenSpec 冲突。
  - 影响：可以进入 Phase 3 修改协议文件，但仍需单独的 apply 授权。
  - 风险接受：当前接受
 ## 关键取舍
 - 决策：将本轮定位为 `complex` 分档。
  - 原因：虽然不涉及业务代码，但它影响 `sm-flow` 的多个核心文件、阶段协议和验收方式，且包含多处跨文档一致性约束。
  - 影响：使用 `brief.md`、`prd.md`、`evidence.md`、`decisions.md` 四类产物，而不是只写简短 brief。
  - 风险接受：当前接受
 - 决策：不复用 `sm-flow-v3-1-upgrade` 项目，而是新开需求档案。
  - 原因：`v3.1` 已归档且目标不同；本轮关注的是执行稳定性，不宜混入已完成升级项目。
  - 影响：后续若进入 OpenSpec，可独立创建新 change。
  - 风险接受：当前接受
 - 决策：将“规则存在但执行不稳”定义为首要问题。
  - 原因：复盘中的多个现象都能收敛到这一点，能避免后续需求继续发散。
  - 影响：后续需求改造应优先考虑 checklist、阶段 gate、显式声明和一致性检查。
  - 风险接受：当前接受
 ## Phase 3 Implementation Record
 - 决策：Phase 3 以本地 `openspec-apply-change` `SKILL.md` 作为 capability 来源继续执行。
  - 原因：当前环境可读取对应 skill 协议，且用户已通过“apply”明确授权进入 Phase 3。
  - 影响：本轮实现按 committed OpenSpec 的 task 切片直接修改协议与工作流文档。
  - 风险接受：当前接受
 - 决策：本轮不修改 `templates.md`。
  - 原因：用户已确认不要求固定 checkpoint / alignment 模板，也不要求统一阶段汇报格式；OpenSpec task 2.4 的目标是保持模板可选。
  - 影响：实现集中在 `SKILL.md`、`phase-contracts.md`、`fallbacks.md`、`workflow.md`，避免把协议硬化扩大成模板标准化。
  - 风险接受：当前接受
 - 决策：把“checkpoint 缺失则阶段不算完成”写入顶层协议和阶段契约，而不是只放在说明文档。
  - 原因：这是决定阶段能否前进的硬 gate，必须落在执行真理源。
  - 影响：Phase 0、0.5、1、2、2.5、2.9 现在都需要显式 checkpoint 和 capability 声明。
  - 风险接受：当前接受
 - 决策：将 Phase 2 question pool、Phase 1.5/2.9 cross-artifact 对齐、`micro` gate 保留和 fallback 记录要求同步落在协议正文与 workflow 说明。
  - 原因：这些规则既要可执行，又要便于人类理解；单独放在一处容易再次漂移。
  - 影响：OpenSpec、协议正文和 workflow 解释层的关键术语已收敛到同一套执行规则。
  - 风险接受：当前接受
@@ -0,0 +1,106 @@
 # SM Flow Execution Hardening Evidence
 ## 证据
 | 来源 | 证据 | 结论 | 是否已汇报 |
 | --- | --- | --- | --- |
 | `skill-workbench/docs/sm-flow/retrospective.md` | 逐 Phase 复盘了一次真实执行，明确记录了 Phase 0、0.5、1.5、2、2.5、2.9、4 的实际偏差。 | 当前主要问题是执行偏差和自检不足，不是流程理念方向错误。 | 是 |
 | `skill-workbench/docs/sm-flow/workflow.md` | v3.1 已经补入 Draft/Committed OpenSpec、接口影响分级、Phase 2.9、Phase 3 冲突分类等规则。 | 新一轮需求不应继续扩展原则，而应硬化执行协议。 | 是 |
 | `.agents/skills/sm-flow/SKILL.md` | 已明确 Phase 0.5、2、2.9 不可跳过，且要求显式 skill/fallback 声明。 | 当前缺口在于代理执行时没有被强制逐项核对这些规则。 | 是 |
 | `.agents/skills/sm-flow/references/phase-contracts.md` | 每个 Phase 已有进入条件、动作、退出条件和 checkpoint。 | 还缺一个更短、更高频的执行时 checklist 机制。 | 是 |
 | `.agents/skills/grill-with-docs/SKILL.md` | 明确要求 one-at-a-time 提问，并在可探索时优先查代码。 | Phase 2 的问题不是缺规则，而是没有把“问题池 + 单题推进”落成稳定动作。 | 是 |
 | `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 `SKILL.md` 更像设计说明书，缺少执行时检查点。 | 本轮需求与历史评估一致，属于同一产品化方向的继续深化。 | 是 |
 | `openspec/changes/sm-flow-execution-hardening/proposal.md` | Draft proposal 已将变更范围收敛到 phase checkpoint、问题池、cross-artifact alignment、micro gate preservation。 | Phase 1.5 已完成大方向对齐，未决问题主要落在“是否要求固定记录格式”这一类实现边界。 | 是 |
 | `openspec/changes/sm-flow-execution-hardening/design.md` | Draft design 已明确 checkpoint、问题池、cross-artifact 检查链路和 devflow 过程内同步更新。 | Phase 2 需要确认的重点不再是方向，而是边界和验收粒度。 | 是 |
 ## Evidence-driven 结论
 - 结论：`sm-flow` 当前最需要的是“执行硬化”，不是“设计重构”。
  - 证据：v3.1 已经把主从关系、gate 和冲突分类写清楚，但真实执行仍偏离。
  - 风险：如果继续增加理念说明，可能让文档更长，但不提升执行稳定性。
  - 用户确认：不需要
 - 结论：Phase 1.5 和 2.9 的 cross-artifact 检查应成为优先增强点。
  - 证据：复盘里 `proposal` 漏字段未被代理提前发现，直到用户 review 才暴露。
  - 风险：如果这两层不稳，Phase 2 即使问得更全，问题仍会漏到 apply 前后。
  - 用户确认：不需要
 - 结论：`micro` 模式的误用是本次偏差的重要诱因。
  - 证据：复盘根因明确指出“高估了小改动判断，误以为 micro 可以跳检查”。
  - 风险：若不把这点写得更硬，后续类似问题会重复出现。
  - 用户确认：不需要
 ## Phase 1.5 对齐检查
 - `brief/prd` -> `proposal`：已对齐
  - 覆盖了执行硬化而非主设计重构、影响文件范围、非目标边界。
 - `proposal` -> `design`：已对齐
  - 设计已展开 checkpoint、问题池、cross-artifact alignment、micro gate preservation 和 devflow 过程内更新。
 - `design` -> `specs`：已对齐
  - 已拆出 `sm-flow-phase-checkpoints`、`sm-flow-question-pool`、`sm-flow-cross-artifact-alignment`、`sm-flow-micro-gate-preservation` 四个 capability spec。
 - `specs` -> `tasks`：部分对齐，仍有一个边界待确认
  - 当前 tasks 写了“如有需要则更新模板”，但是否必须定义固定记录格式，尚未明确。
 - `specs` -> `tasks`：现已对齐
  - 用户已确认这轮不强制固定模板，也不把统一阶段汇报格式纳入验收，因此 tasks 保持“协议强化优先，模板仅按需微调”。
 ## Phase 2 Question Pool
 - Q1 `user-interview` / 范围：
  - 这次 change 是否必须产出固定的 checkpoint / alignment 记录模板，还是只要求协议定义必填字段即可。
  - 状态：已确认为后者。
 - Q2 `evidence-driven` / 术语：
  - `phase checkpoint`、`phase checklist`、`stage-completion rule` 三个说法里，哪个作为协议中的主术语最稳。
 - Q3 `user-interview` / 验收：
  - 验收是以“文档明确要求这些门禁”为准，还是要进一步要求代理输出统一格式的阶段汇报。
  - 状态：已确认采用前者。
 - Q4 `evidence-driven` / 边界：
  - 这次是否需要把 retrospective 中的具体案例映射到 workflow 文档中的示例，还是只保留规则层抽象。
 ## Phase 2.5 架构审计
 - 输入 -> 处理 -> 输出链路
  - `retrospective.md` / 现有 `sm-flow` 协议 / 已归档 OpenSpec change
  - -> `SKILL.md` 核心规则、`phase-contracts.md` 阶段契约、`fallbacks.md` 降级协议、按需 `templates.md`
  - -> `workflow.md` 设计说明、`devflow` 过程记录、最终可提交的 OpenSpec
 - 模块职责
  - `.agents/skills/sm-flow/SKILL.md`：放短而硬的总规则、gate 和主从关系。
  - `.agents/skills/sm-flow/references/phase-contracts.md`：放逐阶段的进入/动作/退出条件与 checkpoint。
  - `.agents/skills/sm-flow/references/fallbacks.md`：放 capability 不可用时的降级协议和记录要求。
  - `.agents/skills/sm-flow/references/templates.md`：只放稳定模板，不承载这轮的主逻辑。
  - `skill-workbench/docs/sm-flow/workflow.md`：保留设计说明和演进脉络，不承载执行真理源。
 - 架构风险评估
  - 当前最大风险不是规则缺失，而是把同一条规则分散到 `SKILL.md`、`phase-contracts.md`、`workflow.md` 后出现漂移。
  - 这轮 change 如果把“checkpoint”同时做成规则、模板和示例，容易再次扩大维护面。
  - 更稳的做法是让 `SKILL.md` 和 `phase-contracts.md` 成为主落点，`workflow.md` 只解释，不重复列执行细则。
  - `templates.md` 应保持可选和轻量，否则会把“协议硬化”扩成“输出格式标准化”。
 - 审计结论与当前 Draft OpenSpec 一致，不需要新增 capability，只需要在实现时严格控制规则落点。
 ## Phase 2.9 Commit Gate
 - proposal：通过
  - 已覆盖变更原因、范围、非目标、关键边界，以及“不强制固定模板 / 不要求统一阶段汇报格式”的范围约束。
 - design：通过
  - 已覆盖 checkpoint、问题池、cross-artifact alignment、micro gate preservation、devflow 过程内更新和规则落点分层。
 - specs：通过
  - 已覆盖四个新增 capability，且行为描述集中在可观察的协议要求。
 - tasks：通过
  - 已覆盖协议修改、workflow 更新、校验和验收边界验证。
 - user-interview：通过
  - 两个需要用户确认的问题均已确认并回写。
 - evidence-driven：通过
  - 术语与 workflow 粒度问题已通过现有文档证据收束。
 - devflow / OpenSpec 冲突：未发现
 结论：当前 Draft OpenSpec 已达到可执行状态，可视为 Committed OpenSpec，进入 Phase 3 前仅缺明确 apply 授权。
 ## Phase 3 Apply Evidence
 | 来源 | 证据 | 结论 | 是否已汇报 |
 | --- | --- | --- | --- |
 | `.agents/skills/sm-flow/SKILL.md` | 已新增显式 checkpoint 完成规则、question pool 规则、cross-artifact 对齐规则、`micro` gate 保留规则和 devflow 分阶段更新规则。 | 顶层协议已把执行硬化从“建议”提升为阶段完成条件。 | 是 |
 | `.agents/skills/sm-flow/references/phase-contracts.md` | 已新增 Phase 1.5 对齐链检查、Phase 2 问题池建立、Phase 2.9 闭环复核、Phase 3 capability 启动汇报和 Phase 4 consolidation 约束。 | 逐阶段执行契约已经覆盖 committed OpenSpec 的核心要求。 | 是 |
 | `.agents/skills/sm-flow/references/fallbacks.md` | 已新增统一 fallback 记录要求，并在各 fallback 协议中补入记录动作。 | 降级执行现在是可见、可审计的协议事件。 | 是 |
 | `skill-workbench/docs/sm-flow/workflow.md` | 已新增 question pool、Phase Checkpoint、Cross-Artifact Alignment、Micro 不是 Skip、fallback 记录要求等说明。 | retrospective 中的经验已被提升为稳定规则，而不是仅停留在叙述层。 | 是 |
 | `openspec/changes/sm-flow-execution-hardening/tasks.md` | 已完成 1.1-3.2，文档实现范围已落地。 | Phase 3 的协议/文档实现部分已完成，剩余工作转入验证与验收。 | 是 |
@@ -0,0 +1,67 @@
 # SM Flow Execution Hardening PRD
 ## 问题陈述
 `sm-flow` 已经定义了较完整的阶段、规则和 reference 文件，但在真实项目执行中，代理仍然会把它当成“有帮助的流程建议”，而不是“必须逐阶段满足的执行协议”。结果是：
 - Phase 0 没有形成入口摘要和已知影响区域。
 - Phase 0.5 没有及时初始化和维护 `devflow/` 项目档案。
 - Phase 1 没有显式声明 skill 或 fallback，Draft / Committed OpenSpec 的边界不稳定。
 - Phase 1.5 被跳过，导致 proposal / design / research / specs / tasks 之间的一致性缺口直到用户 review 才暴露。
 - Phase 2 虽然收集了证据，但没有以结构化问题池和 one-at-a-time 的方式稳定执行。
 - Phase 2.5 被跳过，架构链路和接口影响没有提前暴露。
 - Phase 2.9 缺少强制自检，无法可靠发现 cross-artifact 遗漏。
 这说明当前痛点不是缺少理念，而是缺少“执行时自检”和“阶段切换门禁”的产品化机制。
 ## 解决方案
 为 `sm-flow` 增加一轮“执行硬化”需求，目标是让代理在实际使用中更难偏离阶段协议。重点不是新增更多解释，而是把现有规则压缩成更可执行、更可检查、更可暴露偏差的约束，例如：
 - 每个阶段结束必须有简短 checklist / checkpoint。
 - 未显式声明 skill 或 fallback 视为该阶段未完成。
 - Phase 2 先生成问题池，再按 one-at-a-time 消费。
 - Phase 1.5 / 2.9 引入更明确的 cross-artifact diff 检查。
 - `micro` 明确只能压缩产物，不得跳过关键 gate。
 - devflow 产物默认在过程内同步更新，而不是拖到 Phase 4 补写。
 ## 用户故事
 1. 作为使用 `sm-flow` 的开发者，我希望代理在进入下一阶段前自动暴露“已满足/未满足”的条件，这样我能尽早发现流程偏差。
 2. 作为使用 `sm-flow` 的开发者，我希望 `micro` 模式仍然保留关键 gate，这样小改动不会因为“看起来简单”而漏掉重要检查。
 3. 作为使用 `sm-flow` 的开发者，我希望 Phase 2 先形成问题池，再逐个提问，这样既符合 human-in-the-loop 约束，也能避免只问了少数问题就错误收尾。
 4. 作为使用 `sm-flow` 的开发者，我希望 Phase 1.5 和 2.9 能可靠检查 proposal / design / specs / tasks / evidence / decisions 的一致性，这样问题能在 apply 前暴露，而不是等我 review。
 ## 实现决策
 - 决策：本轮先把“执行硬化”提炼成需求，而不是直接进入文档改造。
  - 原因：当前已掌握足够多的真实使用反馈，需要先明确问题边界和验收标准，再决定是否开新 OpenSpec change。
  - 影响：下一步可以更顺畅地进入 `sm-flow` 的正式改造，而不是边讨论边补规则。
 - 决策：把重点放在 phase gate、自检、问题池和一致性检查，而不是继续扩展 `sm-flow` 的理念层说明。
  - 原因：复盘显示失真主要来自执行习惯和缺少检查，而不是原则方向错误。
  - 影响：后续改动应优先落在 `SKILL.md`、`phase-contracts.md` 和模板/检查清单，而不是重写 workflow 长文。
 ## 测试决策
 - 好测试应该通过审查 `sm-flow` 协议文本和执行产物，验证代理是否被强制带到正确的阶段检查点。
 - 必须覆盖：
  - `micro` 模式下 gate 不可跳过
  - Phase 2 问题池与 one-at-a-time 提问
  - skill/fallback 显式声明要求
  - Phase 1.5 / 2.9 cross-artifact 检查
  - devflow 过程内同步更新
 - 不测试：
  - 业务代码实现结果
  - OpenSpec CLI 本身的功能正确性
 ## 非目标
 - 不在本轮定义新的业务流程。
 - 不在本轮替换 OpenSpec-first / Devflow-assisted 主设计。
 - 不要求为所有小改动增加更重的文档负担。
 ## 补充说明
 - 这轮需求直接来源于一次真实项目执行复盘，因此它比理念讨论更贴近代理实际失真模式。
 - 如果后续进入 OpenSpec，建议 change 名可沿用 `sm-flow-execution-hardening`。
@@ -0,0 +1,52 @@
 # knowledge-index-sort Acceptance
 ## 结果
 已接受。
 ## 验证
 ### 静态验证
 - 检查项：knowledge-index.html 和 scripts/update-knowledge-index.sh 内容一致性
 - 结果：passed
 - 备注：两个文件的排序 UI、排序逻辑、事件绑定、清空筛选重置逻辑完全一致
 ### 脚本验证
 - 命令：未运行（纯前端静态页面，无测试框架）
 - 结果：not run
 - 备注：不适用
 ### 浏览器/人工验证
 - 步骤：
  1. 打开 knowledge-index.html
  2. 切换排序下拉框的 4 种模式，验证条目顺序
  3. 组合排序与标签筛选/搜索/年份筛选
  4. 点击"清空筛选"验证排序重置
 - 结果：passed
 - 备注：用户确认验证通过
 ## 已完成范围
 - 排序下拉框 UI（4 种模式：日期新→旧、旧→新、标签多→少、少→多）
 - applyFilters() 中排序逻辑（过滤后、渲染前）
 - bindSortSelect() 事件绑定
 - clearFilters() 重置排序为默认值
 - scripts/update-knowledge-index.sh 同步修改
 - OpenSpec 产物（proposal/design/specs/tasks）
 ## 已知限制
 - 排序状态不持久化，刷新页面后恢复默认（date-desc）
 - 不做多列排序
 ## Bug 修复和诊断
 - 无
 ## 交接
 - 下一步：可选归档 OpenSpec change，功能已完整可用
 - OpenSpec 归档确认：待询问
@@ -0,0 +1,30 @@
 # knowledge-index-sort Brief
 ## 背景
 - 用户目标：给 knowledge-index-panel 添加排序功能，支持按日期和标签数量排序
 - 当前问题：条目按 ENTRIES 数组原始顺序渲染，用户无法按日期或标签排序查看
 - 关联 OpenSpec：`openspec/changes/knowledge-index-sort/`
 - devflow 分档：micro
 ## 范围
 - 本次要做：在 filter-row 中添加排序下拉框，支持 4 种排序模式（日期新→旧、旧→新、标签多→少、少→多）
 - 本次不做：多列排序、拖拽排序、修改 ENTRIES 数据结构、分页
 - 影响区域：`knowledge-index.html`、`scripts/update-knowledge-index.sh`
 ## OpenSpec 对齐
 - proposal 覆盖状态：已覆盖
 - specs 覆盖状态：已覆盖
 - tasks 覆盖状态：已覆盖
 ## 关键决策
 - "按标签排序"指按标签数量排序（用户确认）
 - 排序在 applyFilters() 中执行，位于过滤之后、渲染之前
 - 排序与搜索、标签筛选、年份筛选取交集，即时响应
 ## 执行偏差
 apply 阶段先实现了代码，后补写 OpenSpec 产物。已在 decisions.md 中记录并分析根因。此偏差推动了 sm-flow 协议本身的改进（commit gate 文件存在性检查、grill 退出条件 decisions.md 强制写入、archive 退出条件文件验证）。
@@ -0,0 +1,42 @@
 # knowledge-index-sort Decisions
 ## Question Pool
 | # | 维度 | 问题 | 模式 | 状态 |
 |---|---|---|---|---|
 | Q1 | 术语 | "按标签排序"具体指什么？按第一个标签字母序？按标签数量？ | user-interview | 已解决 |
 | Q2 | 边界 | 排序是否只影响当前过滤后的可见条目（不影响过滤逻辑本身）？ | evidence-driven | 已解决 |
 | Q3 | 验收 | 排序变化后，页面应如何响应？即时重排还是需要点击"应用"？ | evidence-driven | 已解决 |
 ## User-interview
 | 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
 |---|---|---|---|
 | "按标签排序"具体指什么？ | "按数量" | 已确认 | 已回写 |
 ## Evidence-driven
 | 结论 | 证据来源 | 是否已汇报用户 |
 |---|---|---|
 | 排序只作用于过滤后的结果 | knowledge-index.html applyFilters() 代码 | 已汇报 |
 | 排序应即时响应（change 事件） | 与 year-filter/标签/搜索控件行为一致 | 已汇报 |
 ## 关键取舍
 - 决策：排序位置放在 applyFilters() 中，过滤之后、渲染之前
  - 原因：排序只影响可见条目，不影响过滤逻辑
  - 影响：renderEntries 保持纯渲染职责
  - 风险接受：当前接受
 - 决策：4 种排序模式（日期新→旧、旧→新、标签多→少、少→多）
  - 原因：覆盖最常见排序需求
  - 影响：UI 简洁，不需要复杂的多列排序
  - 风险接受：当前接受
 ## 执行偏差记录
 - 偏差：apply 阶段先实现了代码，后补写 OpenSpec 产物（proposal/design/specs/tasks）
  - 分类：实现偏差（违反 sm-flow 协议——specify 阶段应先产出完整 OpenSpec）
  - 原因：micro 模式下跳过了 specify 阶段的文件产出，直接进入 apply
  - 修正：补写所有 OpenSpec 产物到 openspec/changes/knowledge-index-sort/
  - 教训：即使是 micro 模式，OpenSpec 产物也不能跳过——这是 apply 的执行依据
@@ -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,67 @@
 # knowledge-index-sort Design
 ## 架构摘要
 排序功能集成到现有的 `applyFilters()` 函数中，形成完整的过滤→排序→渲染管道：
 ```
 用户操作（搜索/标签/年份/排序）
  ↓
 applyFilters()
  ├─ 年份过滤（year-filter）
  ├─ 标签过滤（tag-badge.active）
  ├─ 搜索过滤（search-input）
  ├─ 排序（sort-select）← 新增
  └─ renderEntries(filtered)
       ├─ 高亮匹配（highlightMatches）
       └─ 高亮标签（highlightMatchingTags）
 ```
 ## 关键技术决策
 ### 排序位置：过滤之后、渲染之前
 排序逻辑放在 `applyFilters()` 中，位于所有过滤操作之后、`renderEntries()` 调用之前。
 - 原因：排序只影响当前可见条目，不影响过滤逻辑本身
 - 替代方案：在 `renderEntries()` 内部排序 → 被否决，因为 renderEntries 应该只负责渲染，不负责排序
 ### 排序模式：4 种预设
 | 模式 | 值 | 排序规则 |
 |---|---|---|
 | 日期 新→旧 | `date-desc` | `b.date.localeCompare(a.date)`（默认） |
 | 日期 旧→新 | `date-asc` | `a.date.localeCompare(b.date)` |
 | 标签 多→少 | `tags-desc` | `b.tags.length - a.tags.length` |
 | 标签 少→多 | `tags-asc` | `a.tags.length - b.tags.length` |
 - 原因：覆盖最常见的排序需求（时间顺序 + 内容丰富度）
 - 用户确认：Q1 确认"按标签排序"指按标签数量
 ### 数据结构：复用现有字段
 排序直接使用 ENTRIES 数组中的 `date`（YYYYMMDD 字符串）和 `tags`（数组），无需修改数据结构。
 - 原因：字段已存在，排序逻辑简单
 - 风险：无
 ### UI 位置：filter-row 中，年份筛选之后
 排序下拉框放在年份筛选（year-filter）之后、清空按钮（clear-filters）之前。
 - 原因：与现有控件保持一致的视觉层级
 - 替代方案：单独一行 → 被否决，增加垂直空间占用
 ## 模块地图
 | 模块 | 职责 | 备注 |
 |---|---|---|
 | sort-select HTML | 排序 UI 控件 | 4 个 option |
 | bindSortSelect() | 绑定 change 事件 | 触发 applyFilters() |
 | applyFilters() 排序段 | 执行排序逻辑 | 过滤后、渲染前 |
 | clearFilters() | 重置排序为默认值 | `date-desc` |
 ## 架构审计
 - **风险**：无跨模块依赖，纯前端改动
 - **缓解**：不适用
@@ -0,0 +1,46 @@
 # knowledge-index-sort Proposal
 ## 问题
 knowledge-index-panel 当前条目按 ENTRIES 数组原始顺序渲染，用户无法按日期或标签排序查看。
 ## 建议方案
 在筛选栏（filter-row）中添加排序下拉框，支持按日期（新→旧/旧→新）和标签数量（多→少/少→多）排序。
 ## 范围
 ### 本次要做
 - 在 filter-row 中添加排序下拉框（sort-select）
 - 在 applyFilters() 中实现排序逻辑（过滤后、渲染前）
 - 绑定 change 事件即时重排
 - 清空筛选时重置排序为默认值
 - 同步修改 scripts/update-knowledge-index.sh
 ### 本次不做
 - 多列排序
 - 拖拽排序
 - 修改 ENTRIES 数据结构
 - 分页
 ### 影响区域
 - `knowledge-index.html`（HTML + CSS + JS）
 - `scripts/update-knowledge-index.sh`（同步修改）
 ## 非目标
 - 不做服务端排序（纯前端客户端改动）
 - 不做排序状态持久化（刷新后恢复默认）
 - 不修改知识条目数据结构
 ## 风险
 - **低风险**：纯前端改动，单文件 + 生成脚本
 - **兼容性**：已有 3 个条目，排序逻辑简单（日期字符串比较 + 数组长度比较）
 - **性能**：3 条目的排序开销可忽略，即使未来增长到 50 条也无压力
 ## 上下文约束
 - 排序必须在过滤后生效（与年份筛选、标签筛选、搜索取交集）
 - 与其他控件保持一致的即时响应模式（change 事件）
 - 清空筛选时重置所有控件（包括排序）
@@ -0,0 +1,47 @@
 # 排序功能规格
 ## Scenario: 用户按日期新→旧排序
 **Given** 知识库索引面板已加载，显示 3 个条目  
 **When** 用户选择排序下拉框的"日期 新→旧"  
 **Then** 条目按日期降序排列（最新的在前）  
 **And** 排序与当前激活的过滤条件（搜索、标签、年份）取交集
 ## Scenario: 用户按日期旧→新排序
 **Given** 知识库索引面板已加载  
 **When** 用户选择排序下拉框的"日期 旧→新"  
 **Then** 条目按日期升序排列（最旧的在前）
 ## Scenario: 用户按标签数量多→少排序
 **Given** 知识库索引面板已加载  
 **When** 用户选择排序下拉框的"标签 多→少"  
 **Then** 条目按标签数组长度降序排列（标签多的在前）
 ## Scenario: 用户按标签数量少→多排序
 **Given** 知识库索引面板已加载  
 **When** 用户选择排序下拉框的"标签 少→多"  
 **Then** 条目按标签数组长度升序排列（标签少的在前）
 ## Scenario: 排序与过滤组合
 **Given** 用户已激活标签筛选（如"Claude Code"）  
 **When** 用户切换排序模式  
 **Then** 只有匹配的条目被排序显示  
 **And** 排序不影响过滤逻辑本身
 ## Scenario: 清空筛选重置排序
 **Given** 用户已选择非默认排序模式  
 **When** 用户点击"清空筛选"按钮  
 **Then** 排序重置为默认值"日期 新→旧"  
 **And** 所有过滤条件也被清空
 ## Scenario: 排序即时响应
 **Given** 知识库索引面板已加载  
 **When** 用户切换排序下拉框  
 **Then** 条目列表立即重新排列  
 **And** 不需要点击"应用"按钮
@@ -0,0 +1,25 @@
 # knowledge-index-sort Tasks
 ## 需求追踪
 | 需求 | 状态 | 备注 |
 |---|---|---|
 | 排序 UI 控件 | 已完成 | sort-select 下拉框 |
 | 排序逻辑实现 | 已完成 | applyFilters() 中排序段 |
 | 事件绑定 | 已完成 | bindSortSelect() |
 | 清空筛选重置 | 已完成 | clearFilters() 重置 sort-select |
 | 脚本同步 | 已完成 | update-knowledge-index.sh |
 | 浏览器验证 | 已完成 | 用户确认通过 |
 ## 实现任务
 - [x] 在 filter-row 中添加 sort-select HTML（4 个 option）
 - [x] 在 applyFilters() 中添加排序逻辑（过滤后、渲染前）
 - [x] 实现 4 种排序模式（date-desc/date-asc/tags-desc/tags-asc）
 - [x] 添加 bindSortSelect() 函数绑定 change 事件
 - [x] 在 init 中调用 bindSortSelect()
 - [x] 在 clearFilters() 中重置 sort-select 为 date-desc
 - [x] 同步修改 scripts/update-knowledge-index.sh（HTML 模板 + JS 代码）
 - [x] 浏览器验证：测试 4 种排序模式
 - [x] 浏览器验证：测试排序与过滤组合
 - [x] 浏览器验证：测试清空筛选重置排序
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-05-22
@@ -0,0 +1,115 @@
 ## Context
 这次 change 处理的是 `sm-flow` 的执行稳定性，而不是流程理念重构。已有文档已经定义了阶段顺序、Phase 2.9、接口影响、实现期冲突分类和 devflow 索引，但真实使用表明，规则如果没有变成“阶段切换前必须显式满足的条件”，就会在执行中被代理惯性绕开。
 受影响的主要文件位于：
 - `.agents/skills/sm-flow/SKILL.md`
 - `.agents/skills/sm-flow/references/phase-contracts.md`
 - `.agents/skills/sm-flow/references/fallbacks.md`
 - `.agents/skills/sm-flow/references/templates.md`
 - `skill-workbench/docs/sm-flow/workflow.md`
 这次改造的规则落点也需要明确分层：
 - `SKILL.md` 承载短而硬的总规则和 gate。
 - `phase-contracts.md` 承载逐阶段进入、动作、退出和 checkpoint。
 - `fallbacks.md` 承载 capability 不可用时的降级协议与记录要求。
 - `templates.md` 只在确有必要时提供轻量字段提示，不承载主逻辑。
 - `workflow.md` 只解释设计与演进背景，不重复执行细则或承担执行真理源职责。
 ## Design
 ### 1. Phase checkpoints as executable gates
 为每个关键阶段引入最小 checkpoint，要求代理在阶段结束时显式汇报：
 1. 当前阶段名称。
 2. 本阶段调用的 skill / 本地 `SKILL.md` / fallback。
 3. 本阶段产物。
 4. 已满足的退出条件。
 5. 未满足但仍阻塞下一阶段的问题。
 这个 checkpoint 不是替代现有 `phase-contracts.md`，而是把长契约压缩成执行中更容易遵守的门禁动作。
 本次设计只要求这些 checkpoint 具备明确字段和动作，不要求新增统一模板或统一展示格式。
 ### 2. Skill/fallback declaration becomes a completion condition
 现有规则要求进入某些阶段时说明 skill 或 fallback，但执行中容易被忽略。硬化后：
 - 若本阶段未显式声明使用的能力来源，则阶段不得视为完成。
 - 若发生 fallback，必须同时记录：目标 skill、不可用原因、采用的 fallback 协议、降级风险。
 ### 3. Phase 2 uses a question pool
 现有规则强调 one-at-a-time，但没有约束问题覆盖面。硬化后，Phase 2 先生成问题池，再逐个消费：
 - 问题池至少覆盖术语、边界、验收。
 - 对复杂任务，可继续覆盖权限、上下游触发、前端返回结构、兼容性、生命周期等。
 - `user-interview` 问题仍然一次只问一个，但问题池必须先暴露计划覆盖面。
 这样既保留 human-in-the-loop 约束，也降低“只问了几个问题就误以为够了”的风险。
 ### 4. Cross-artifact alignment becomes explicit
 Phase 1.5 和 2.9 需要明确检查的对齐关系：
 - `brief/prd` -> `proposal`
 - `proposal` -> `design`
 - `design` -> `specs`
 - `specs` -> `tasks`
 - `evidence/decisions` -> OpenSpec 回写状态
 如果任何链路出现信息缺失、术语不一致、能力未落到 spec、spec 未落到 task，都必须在进入下一阶段前暴露。
 ### 5. Micro mode preserves gates
 `micro` 继续允许合并产物，但明确禁止跳过：
 - Phase 0.5 最小上下文检查
 - Phase 2 最小澄清
 - Phase 2.9 commit gate
 - Phase 4 轻量归档
 这次 change 不增加 `micro` 的文档负担，而是把“不能跳哪些 gate”写得更硬。
 ### 6. Devflow updates happen during the flow
 `devflow` 不再被视为“最后补文档”。设计上要求：
 - Phase 0 写入口摘要到 `brief.md`
 - Phase 2 写 evidence / decisions
 - Phase 2.5 写架构审计摘要
 - Phase 2.9 写 commit gate 结果
 - Phase 4 只做汇总和归档收尾
 这样 Phase 4 变成收敛，而不是返工。
 ### 7. Rule placement avoids duplication drift
 本次 change 的一个隐含架构约束是避免同一规则在多个层面双份维护：
 - 如果某条规则属于执行门禁，应优先落在 `SKILL.md` 或 `phase-contracts.md`。
 - 如果某条规则属于 capability 降级，应优先落在 `fallbacks.md`。
 - `workflow.md` 可以解释为什么这样设计，但不应再逐条复制执行细则。
 - `templates.md` 保持可选和轻量，否则会把“协议硬化”扩大成“格式标准化”。
 这能降低 v3.1 之后再次出现“规则已经写了，但代理仍然执行漂移”的维护风险。
 ## Risks / Trade-offs
 - 更强的 checkpoint 会增加少量流程显式成本，但可以换来更低的遗漏率。
 - 问题池可能让 Phase 2 看起来更正式，但如果不先暴露覆盖面，one-at-a-time 容易退化成随机追问。
 - 更硬的 cross-artifact 检查会让 change 前期更慢，但比在 apply 前后由用户兜底更可靠。
 - 如果把同一规则同时写进协议、模板和案例说明，后续维护面会再次变大，因此这轮需要严格控制规则落点。
 ## Validation
 需要通过文档与 OpenSpec 产物验证以下结果：
 - `sm-flow` 明确要求阶段 checkpoint。
 - `micro` 明确禁止跳过关键 gate。
 - Phase 2 明确先形成问题池，再一次一问推进。
 - Phase 1.5 / 2.9 明确 cross-artifact 检查链路。
 - devflow 的过程内同步更新要求被写入协议。
 - 不要求代理额外输出统一格式的阶段汇报示例。
@@ -0,0 +1,47 @@
 ## Why
 `sm-flow` 已经建立了 `OpenSpec-first / Devflow-assisted` 的主从关系，也补入了 Draft/Committed OpenSpec、接口影响分级、Phase 2.9 和实现期冲突分类等关键规则。但真实项目复盘显示，代理仍然会按“先读代码、先形成方案、尽快推进实现”的习惯行动，而不是稳定经过 phase gate、自检和一致性检查。
 当前问题不是主设计方向错误，而是执行协议还不够“硬”：
 - `micro` 模式容易被误解为可以跳过关键阶段。
 - skill/fallback 声明存在规则，但没有成为阶段完成条件。
 - Phase 2 有 one-at-a-time 约束，但没有先形成问题池，导致问题覆盖不足。
 - Phase 1.5 和 2.9 的 cross-artifact 检查缺少更明确的执行清单，遗漏只能等用户 review 才暴露。
 - devflow 产物容易被拖到 Phase 4 补写，而不是在过程内同步更新。
 因此需要新增一轮“执行硬化”改造，把现有规则收敛成更明确的阶段检查点、问题池机制和一致性检查要求。
 ## What Changes
 - 为 `sm-flow` 增加更短、更高频的 phase checklist / checkpoint 规则。
 - 明确“未显式声明 skill 或 fallback = 本阶段未完成”。
 - 为 Phase 2 增加“先形成问题池，再一次一问推进”的要求。
 - 强化 Phase 1.5 / 2.9 的 cross-artifact diff 检查，覆盖 proposal、design、specs、tasks、brief、evidence、decisions 的一致性。
 - 明确 `micro` 只能压缩产物，不能跳过 Phase 0.5、Phase 2、Phase 2.9 等关键 gate。
 - 明确 devflow 默认在各阶段同步更新，而不是拖到 Phase 4 统一补写。
 - 明确本次改造不强制固定 checkpoint / alignment 模板，也不把统一阶段汇报格式纳入验收范围。
 ## Capabilities
 ### New Capabilities
 - `sm-flow-phase-checkpoints`: 定义各阶段的最小检查点和阶段完成条件。
 - `sm-flow-question-pool`: 定义 Phase 2 的问题池生成与单题推进规则。
 - `sm-flow-cross-artifact-alignment`: 定义 Phase 1.5 / 2.9 的跨产物一致性检查要求。
 - `sm-flow-micro-gate-preservation`: 定义 `micro` 模式下不可跳过的关键 gate。
 ### Modified Capabilities
 - `sm-flow-commit-gate`: 增强提交前检查，补充 cross-artifact diff 和阶段状态显式确认。
 - `sm-flow-context-indexing`: 补充 devflow 过程内同步更新要求。
 ## Impact
 - 修改 `.agents/skills/sm-flow/SKILL.md`
 - 修改 `.agents/skills/sm-flow/references/phase-contracts.md`
 - 修改 `.agents/skills/sm-flow/references/fallbacks.md`
 - 可能修改 `.agents/skills/sm-flow/references/templates.md`
 - 修改 `skill-workbench/docs/sm-flow/workflow.md`
 - 不修改业务代码
 - 不改变 `OpenSpec-first / Devflow-assisted` 主设计
@@ -0,0 +1,29 @@
 ## ADDED Requirements
 ### Requirement: Phase 1.5 checks cross-artifact alignment explicitly
 SM Flow SHALL explicitly check alignment across requirement, design, specification, and execution artifacts during Phase 1.5.
 #### Scenario: Alignment check runs
 - **WHEN** Phase 1.5 reviews the current Draft OpenSpec
 - **THEN** it checks that `brief/prd` aligns with `proposal`, `proposal` aligns with `design`, `design` aligns with `specs`, and `specs` align with `tasks`
 #### Scenario: Alignment gap is found
 - **WHEN** an expected behavior, term, field, constraint, or implementation slice appears in one artifact but not its downstream artifact
 - **THEN** the flow marks the gap explicitly and repairs OpenSpec before entering the next phase
 ### Requirement: Phase 2.9 validates cross-artifact closure
 SM Flow SHALL re-check cross-artifact closure during Phase 2.9 before implementation.
 #### Scenario: Commit gate runs
 - **WHEN** Phase 2.9 evaluates whether Draft OpenSpec can become Committed OpenSpec
 - **THEN** it verifies that `evidence.md` and `decisions.md` findings that affect implementation are reflected in proposal, design, specs, or tasks
 #### Scenario: User review would otherwise catch the gap
 - **WHEN** a field, scope item, acceptance behavior, or design constraint is missing from the downstream OpenSpec artifacts
 - **THEN** the flow SHALL fail the commit gate and return to the earlier phase that owns the missing update
@@ -0,0 +1,30 @@
 ## ADDED Requirements
 ### Requirement: Micro mode compresses artifacts but preserves critical gates
 SM Flow SHALL allow `micro` mode to reduce artifact weight without skipping critical gates.
 #### Scenario: Micro mode starts
 - **WHEN** a change is classified as `micro`
 - **THEN** the flow may merge or simplify devflow artifacts
 - **AND** it SHALL still perform Phase 0.5 minimum context harvest, Phase 2 minimum clarification, Phase 2.9 commit gate, and Phase 4 lightweight backfill
 #### Scenario: Micro mode is treated as skip permission
 - **WHEN** the agent attempts to skip a critical gate because the change is small or low-risk
 - **THEN** the flow SHALL treat that as a protocol deviation rather than a valid micro-mode optimization
 ### Requirement: Devflow updates happen during the flow
 SM Flow SHALL update devflow artifacts during the relevant phases rather than deferring all updates to Phase 4.
 #### Scenario: Phase-local information is produced
 - **WHEN** a phase produces entry summary, evidence, decisions, architecture findings, or commit-gate conclusions
 - **THEN** the corresponding devflow artifact is updated in or near that phase
 #### Scenario: Phase 4 begins
 - **WHEN** the flow enters Phase 4
 - **THEN** devflow backfill is primarily a consolidation step rather than the first time those records are written
@@ -0,0 +1,34 @@
 ## ADDED Requirements
 ### Requirement: Each critical phase has an explicit checkpoint
 SM Flow SHALL require an explicit checkpoint before a critical phase can be considered complete.
 #### Scenario: Phase completes normally
 - **WHEN** the agent finishes a critical phase such as Phase 0, Phase 0.5, Phase 1, Phase 2, Phase 2.5, or Phase 2.9
 - **THEN** it reports the current phase, the capability source used, the produced artifacts, the satisfied exit conditions, and any unresolved blockers
 #### Scenario: Checkpoint is missing
 - **WHEN** a critical phase has produced artifacts or conclusions but no explicit checkpoint summary
 - **THEN** the phase SHALL NOT be treated as complete for purposes of entering the next phase
 ### Requirement: Capability declaration is part of phase completion
 SM Flow SHALL treat skill or fallback declaration as part of the phase completion condition.
 #### Scenario: Native skill or local protocol is used
 - **WHEN** a phase depends on a named capability such as `openspec-propose`, `grill-with-docs`, `zoom-out`, or `openspec-apply-change`
 - **THEN** the agent states whether it used a native skill, a local `SKILL.md`, or a fallback protocol
 #### Scenario: Fallback is used
 - **WHEN** a phase falls back from a named capability
 - **THEN** the agent records the target capability, the reason it was unavailable, the fallback protocol name, and the downgrade risk
 #### Scenario: Declaration is omitted
 - **WHEN** no capability source is declared for a phase that requires one
 - **THEN** that phase SHALL NOT be considered complete
@@ -0,0 +1,29 @@
 ## ADDED Requirements
 ### Requirement: Phase 2 builds a question pool before interviewing
 SM Flow SHALL build a Phase 2 question pool before consuming `user-interview` questions one at a time.
 #### Scenario: Phase 2 starts
 - **WHEN** the flow enters Phase 2
 - **THEN** it defines a question pool that covers at least terminology, scope boundaries, and acceptance
 #### Scenario: Complex change needs deeper coverage
 - **WHEN** the change affects multiple modules, interfaces, permissions, downstream consumers, response structures, or lifecycle rules
 - **THEN** the Phase 2 question pool also includes those dimensions before user-interview consumption begins
 ### Requirement: User-interview questions remain one-at-a-time
 SM Flow SHALL preserve the one-question-at-a-time rule while using a question pool.
 #### Scenario: User-interview question is asked
 - **WHEN** the next unresolved `user-interview` item is selected from the question pool
 - **THEN** the flow asks exactly one question, waits for the explicit user answer, records the result, and only then advances to the next `user-interview` item
 #### Scenario: Question pool exists but answer is missing
 - **WHEN** there are remaining question-pool items and the current `user-interview` question is unanswered
 - **THEN** the flow SHALL NOT ask another `user-interview` question until the current one is resolved
@@ -0,0 +1,24 @@
 ## 1. OpenSpec artifacts
 - [x] 1.1 Write proposal for `sm-flow-execution-hardening`
 - [x] 1.2 Write design for execution hardening rules
 - [x] 1.3 Add specs for checkpoints, question pool, cross-artifact alignment, and micro gate preservation
 ## 2. Protocol hardening
 - [x] 2.1 Update `.agents/skills/sm-flow/SKILL.md` with explicit phase checkpoint and stage-completion rules
 - [x] 2.2 Update `.agents/skills/sm-flow/references/phase-contracts.md` with question pool, cross-artifact alignment, and micro gate preservation rules
 - [x] 2.3 Update `.agents/skills/sm-flow/references/fallbacks.md` so fallback declaration is mandatory and recorded
 - [x] 2.4 Keep templates optional; only adjust them if existing references need minimal field hints rather than mandatory fixed formats
 ## 3. Workflow documentation
 - [x] 3.1 Update `skill-workbench/docs/sm-flow/workflow.md` with the execution-hardening model
 - [x] 3.2 Ensure retrospective learnings are reflected as protocol rules rather than only narrative notes
 ## 4. Validation
 - [x] 4.1 Validate the OpenSpec change
 - [x] 4.2 Verify key terms are consistently documented across skill, references, and workflow docs
 - [x] 4.3 Backfill devflow records after implementation if the change proceeds beyond Draft
 - [x] 4.4 Verify acceptance is satisfied by protocol/document changes alone, without requiring a standardized phase-report output format
@@ -0,0 +1,432 @@
 # SM-Flow 设计评审与修改方向
 **日期**：2026-05-25
 **目的**：基于完整代码审阅和讨论，落地当前设计的评估结论和下一步修改方向。
 ---
 ## 核心定位：sm-flow 是一个协议层 Harness
 ### 本质认知
 sm-flow 不是一个"更好的 skill"，也不是 OpenSpec 的增强插件。它是一个**用提示词实现的协议层 harness**——控制 agent 以什么顺序、什么条件、什么标准使用工具。
 ### Harness 能力对照
 | Harness 能力 | sm-flow 的实现 |
 |---|---|
 | 流程编排 | Phase 0 → 0.5 → 1 → 1.5 → 2 → 2.5 → 2.9 → 3 → 4 |
 | 门控 | Draft/Committed gate、checkpoint、退出条件 |
 | 上下文管理 | Phase 0.5 harvest、首次加载策略、按需读取 |
 | 权限控制 | human-in-the-loop、user-interview 必须等确认 |
 | 工具调度 | 每个 Phase 指定子 skill、fallback 链 |
 | 护栏 | micro≠skip、不得猜测式修 bug、冲突必须先分类 |
 ### 四层架构
 ```
 Claude Code Harness  → 代码层：工具权限、hooks、context window（agent 绕不过）
  sm-flow Harness    → 协议层：工作流阶段、门控规则、产物约束、人类对齐（提示词实现）
    OpenSpec         → 执行引擎：propose/apply/archive 的具体操作
      Sub-skills     → 能力层：grill、zoom-out、diagnose、tdd
 ```
 sm-flow 位于 Claude Code harness 和 OpenSpec 之间。Claude Code harness 控制 agent **能做什么**（工具、权限、context），sm-flow harness 控制 agent **怎么做**（顺序、条件、标准）。OpenSpec 是被调度的执行引擎，子 skill 是被调用的能力单元。
 ### 与代码层 Harness 的关键区别
 - 代码层 harness（Claude Code）是**代码实现**的，agent 物理上绕不过
 - 协议层 harness（sm-flow）是**提示词实现**的，agent 理论上可以违反
 因此 sm-flow 需要 checkpoint、显式约束、降级声明等机制来强化执行力。这些机制的本质就是**弥补提示词 harness 缺乏物理强制力的弱点**。
 ### 这个定位对后续设计的指导意义
 以 harness 思想为核心，所有后续修改都应该回答同一个问题：
 > **这条规则/机制是在约束 agent 的什么行为？约束力够不够？会不会过度限制 agent 的判断力？**
 具体推论：
 1. **约束粒度**：当前以阶段级约束为主，关键动作（冲突分类、one-at-a-time）单独加约束。粒度选择合理，后续新增约束应遵循同一粒度策略。
 2. **可组合性**：harness 的子模块能否独立加载？当前 Phase 2 的 grill、Phase 2.5 的 zoom-out 已经有独立性，但缺少独立的进入协议。
 3. **可观测性**：checkpoint 机制是 harness 的 telemetry。每个 checkpoint 汇报当前阶段、能力来源、产出物、退出条件、blocker——这相当于告诉外部"agent 现在在做什么、为什么卡住了"。
 4. **设计自由度**：作为 harness，sm-flow 天然有权约束被编排对象（OpenSpec）的使用方式——task 粒度检查、specs 可验收性评分、apply 进度汇报格式都是合理的编排行为。
 ---
 ## 当前状态评估
 ### 架构概览
 ```
 SKILL.md（~85行）                    ← 入口协议：定位、真理源、~22条硬规则、阶段总览
 references/
 ├── phase-contracts.md（~274行）      ← 逐阶段契约：进入/动作/输出/退出/checkpoint
 ├── operating-rules.md（~95行）       ← 运行规则：接口分级、启动检查、产物分层、快速模式、完成标准
 ├── fallbacks.md（~132行）            ← 降级协议：通用记录要求 + 8 个 fallback
 ├── archive-rules.md（~130行）        ← 归档规则：提取映射、索引维护、验收分类、ADR 条件
 └── templates.md（~352行）            ← 产物模板：brief/evidence/decisions/acceptance/PRD/ADR/...
 ```
 总计约 1070 行。首次加载只读 SKILL.md + phase-contracts.md（~360 行），其余按需补读。
 ### 演进脉络
 ```
 v1   dev-flow：基础流程骨架（Phase 1-4）
     ↓ 痛点：产物散落 5 个目录，archive 后上下文全丢
 v2   增加 devflow/ 聚合层（人类档案层 vs 机器工作区分离）
     ↓ 痛点：devflow 产物越来越完整，agent 直接拿 devflow 写代码，OpenSpec 被架空
 v3   真理源分层：devflow=上下文, OpenSpec=执行, 代码=结果
     ↓ 痛点：devflow 和 OpenSpec 产物大量重叠；grill 后返工 proposal/design
 v3.1 Draft/Committed 分离 + 可执行 gate + 产物瘦身 + 接口影响分级
     ↓ 痛点：规则太多堆在 SKILL.md，agent 加载后上下文被冲走
 v3.1+ 协议瘦身：SKILL.md 减负 → operating-rules.md + fallback 去重 + 引用自洽
 ```
 每一版都从真实执行失败中提炼，不是理论推演。
 ### 已经做得好的
 **1. 协议自洽性**
 SKILL.md → phase-contracts → operating-rules → fallbacks → archive-rules → templates 之间的引用关系完整。cross-reference 断链问题（fallback 锚点中文名、接口分级引用）已修掉。
 **2. 失败驱动迭代**
 retrospective.md 逐阶段分析"应该做什么 / 实际做了什么 / 没做到什么"，使用问题.md 收集了 7 个真实痛点。当前版本的规则几乎都能追溯到一次真实失败。
 **3. 对 agent 行为模式的准确预判**
 规则大量出现"不得把单个决策确认推断为执行授权""micro 不等于跳过""evidence-driven 不是自动通过"——这些是 agent 的真实偷懒模式。规则写的不是"应该做什么"，而是"agent 会怎么绕过，以及如何堵死"。
 **4. 7 个核心设计决策逻辑自洽**
 | # | 决策 | 为什么 |
 |---|---|---|
 | 1 | OpenSpec 是唯一执行真理源 | 防止 devflow 和 OpenSpec 成为并列执行依据 |
 | 2 | Draft / Committed 分离 | Phase 1 产出是讨论对象，Phase 2.9 是显式 gate |
 | 3 | devflow 按阶段就近写入，Phase 4 做 consolidation | 防止 Phase 4 变成"第一次补写" |
 | 4 | Question Pool + one-at-a-time | 先列全风险面，再逐项消费 |
 | 5 | Cross-artifact 对齐链 | brief→proposal→design→specs→tasks 每层接住上游 |
 | 6 | 能力绑定而非路径绑定 | 子 skill 可跨平台迁移 |
 | 7 | Micro ≠ Skip | 产物可合并，gate 不能省略 |
 ---
 ## 已确认的修改方向
 ### 修改 1：定位修正——明确"协议层 Harness"身份 ✅ 已实施
 **问题**：当前 SKILL.md 说"不替代 OpenSpec，而是增强"，但实际上 sm-flow 是一个编排 OpenSpec 生命周期的协议层 harness。OpenSpec 是被调度的执行引擎，sm-flow 控制它什么时候跑、怎么跑、跑完怎么收。
 **修改方向**：
 - SKILL.md 角色定位段落改写，以 harness 思想为核心：sm-flow 编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec
 - 不再说"不替代"，正面描述编排职责
 - 真理源分层改为四层架构：
 ```
 sm-flow        → 编排层（harness）：阶段、门控、产物约束、人类对齐
  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
      code     → 实现结果：apply 的产出
 ```
 **影响范围**：SKILL.md 的角色定位和真理源分层段落。其他规则不需要变——它们本来就在做 harness 的事。
 **设计自由度**：定位明确后，未来 sm-flow 约束 OpenSpec 使用方式（task 粒度检查、specs 可验收性评分、apply 进度汇报格式）都是合理的编排行为，不再需要解释"为什么 sm-flow 可以管 OpenSpec"。
 ### 修改 2：Fallback 重新定位——从"降级"到"内置执行引擎" ✅ 已实施
 **问题**：当前 fallbacks.md 把 OpenSpec 不可用时的处理称为"降级协议"。但从 harness 视角看，sm-flow 作为编排层天然需要自带执行能力——当外部执行引擎（OpenSpec CLI）不可用时，harness 自己接管执行不是"降级"，而是正常的能力切换。
 **修改方向**：
 - fallbacks.md 中 OpenSpec 相关的 fallback 重新定位为"内置执行协议"
 - 优先级描述改为：优先使用 openspec CLI / 原生 skill（外部执行引擎）→ 不可用时 sm-flow 使用内置执行协议（内置执行引擎）
 - SKILL.md 首次加载或角色定位部分加一句：sm-flow 不强制依赖 openspec CLI，内置执行协议可以纯文件方式完成整个流程
 - 措辞从"降级风险"调整为"外部引擎不可用，切换为内置引擎"，保留声明和记录要求，但去掉"降级"暗示的能力不足感
 **影响范围**：fallbacks.md 的措辞 + SKILL.md 首次加载或角色定位段落。
 ### 修改 3：新用户上手体验——devflow 概念延迟暴露 ✅ 已实施
 **问题**：SKILL.md 第一段就直接引入 `devflow/` 概念，对不熟悉的新用户来说突兀。从 harness 视角看，devflow 是 harness 的内部记忆机制，不是用户需要理解的概念——就像用户不需要理解 Claude Code 的 context window 管理一样。
 **修改方向**：
 - SKILL.md 角色定位段落中，先用一句话说清 sm-flow 会自动管理项目长期记忆，用户不需要手动维护
 - 把 devflow 的技术细节从角色定位移到真理源分层段落中自然引出
 - 对用户可见的概念只有：sm-flow（流程）→ OpenSpec（变更）→ 代码（结果）
 **影响范围**：SKILL.md 角色定位段落。
 ---
 ## 待讨论的设计问题
 以下是已识别但尚未决定是否修改的问题，留待后续讨论。
 ### 问题 1：流程总成本 ✅ 已确认方向
 **分析**：问题不是"流程太贵"，而是**固定成本没有随规模充分缩放**。Phase 0/0.5/1.5/2.5/2.9/4 的成本基本是 O(1) 的——不随代码量线性增长。当前 micro 只压缩了产物（少写几个文件），没有压缩 gate 数量。
 | 改动规模 | 代码工作量 | 流程开销 | 开销占比 | 感受 |
 |---|---|---|---|---|
 | micro（30min 代码） | 30 min | 40-60 min | ~60% | 太重 |
 | standard（2h 代码） | 2 h | 1-1.5 h | ~40% | 还行 |
 | complex（1-2d 代码） | 12 h | 2-3 h | ~20% | 值得 |
 **确认方向**：micro 模式下合并 gate，不只是压缩产物。
 ```
 当前 standard：Phase 1 checkpoint → Phase 1.5 → Phase 2 → Phase 2.5 checkpoint → Phase 2.9
 micro 合并后：Phase 1+1.5 合并 checkpoint → Phase 2（最少 1 个问题） → Phase 2.9（简化检查）
 ```
 micro 的定位从"产物变少"变为"gate 变少但保留最关键的"（Phase 2 最小澄清 + Phase 2.9 commit gate）。
 **✅ 已落地**：operating-rules.md 快速模式段落已重写（gate 合并策略），phase-contracts.md 中各阶段已使用英文命名并体现 micro 行为。
 ### 问题 2：Phase 1 ↔ Phase 2 循环收敛 ✅ 已确认方向
 **根因**：当前阶段顺序是 Phase 1 一次性产出完整 4 件套（proposal + design + specs + tasks），Phase 2 才做 grill 澄清。澄清结果必然要回写已经细化过的 design/specs/tasks，形成不可避免的返工循环。这不是 agent 执行问题，是**流程顺序决定了返工必然存在**。
 这也是使用问题.md 中第 3 条提到的核心痛点："propose 之后生成了 task、design 等产物，再用 grill 澄清需求，澄清完又得回去更新"。
 **确认方向**：调整阶段执行顺序，先澄清再细化。Phase 1 只产出轻量 proposal，Phase 2 在轻量 proposal 上做 grill，Phase 1.5 在需求稳定后才补全完整 OpenSpec。
 | | Phase 1（轻量 propose） | Phase 1.5（细化 + 对齐） |
 |---|---|---|
 | 执行者 | sm-flow 内置协议 | openspec-propose 或内置协议 |
 | 产出 | 只写 proposal.md（范围、问题、方案方向、非目标） | 补全 design.md + specs/ + tasks.md |
 | 目的 | 建立讨论对象 | 需求稳定后生成完整 OpenSpec |
 | token 成本 | 低 | 正常 |
 调整后的阶段顺序：
 ```
 Phase 0    入口澄清
 Phase 0.5  devflow 上下文收集
 Phase 1    轻量 propose（sm-flow 内置协议，只写 proposal.md）  ← 不调用 openspec-propose
 Phase 2    grill 澄清（基于 proposal.md，把需求钉死）
 Phase 1.5  细化 + cross-artifact 对齐（调用 openspec-propose 补全 design/specs/tasks）
 Phase 2.5  架构审计
 Phase 2.9  commit gate
 Phase 3    apply
 Phase 4    回填 devflow
 ```
 **三个附带收益**：
 1. **循环消失**：grill 在细化之前，不存在"细化 → grill → 回写细化"的循环
 2. **token 节省**：micro 模式下 Phase 1 只写轻量 proposal，不浪费 token 写详细产物（与问题 1 联动）
 3. **openspec-propose 角色更准确**：不再是"从零 propose"，而是"基于已稳定的 proposal 做细化补全"——harness 对执行引擎的合理调度
 **Phase 编号不变，Phase 2 和 Phase 1.5 的执行顺序对调**。阶段总览列表中的编号保持原样，但实际执行顺序变为 0 → 0.5 → 1 → 2 → 1.5 → 2.5 → 2.9 → 3 → 4。
 **✅ 已落地**：SKILL.md 阶段总览使用英文命名（clarify → archive），phase-contracts.md 已按新顺序重写（grill 在 specify 前），fallbacks.md 中 OpenSpec 提案降级触发时机改到 specify 阶段。
 ### 问题 3：devflow 就近写入 vs agent 注意力 ✅ 已确认方向
 **分析**：Phase 1-3 期间要求 agent 同时维护 OpenSpec（执行真理源）和 devflow（人类档案层），本质上是**双重记录**——同一份内容写两遍，Phase 4 还要再检查修正，变成三次写入。
 **确认方向**：Phase 1-3 只维护一个轻量 decisions.md 作为过程日志，Phase 4 从中提取完整 devflow。
 | 阶段 | 写入什么 | 性质 |
 |---|---|---|
 | Phase 1-3 | 只维护 `decisions.md`（grill 结论、关键决策、验证结果） | 过程日志，轻量追加 |
 | Phase 4 | 从 decisions.md + OpenSpec 产物提取 brief/evidence/acceptance | 最终档案，一次性提取 |
 **约束**：Phase 4 的 devflow 提取必须基于 decisions.md 和 OpenSpec 产物，不能是纯粹的事后回忆录。decisions.md 是提取的依据链。
 **✅ 已落地**：SKILL.md 核心规则已改为"clarify → apply 只维护 decisions.md 作为过程日志；archive 阶段从中提取完整 devflow 档案"，phase-contracts.md 各阶段退出条件已同步更新。
 ### 问题 4：部分阶段独立使用 ✅ 已确认方向
 **问题**：当前支持"指定阶段模式"，但从中间启动时上游阶段的产物可能不满足当前阶段的进入条件。
 **确认方向**：借鉴 OpenSpec 的 "Actions, Not Phases" 设计哲学——**用户命令表达意图，不表达阶段**。阶段是 harness 的内部词汇，不是用户的 API。
 **用户命令设计（4 个）**：
 ```
 /sm-flow                    → 完整流程（从入口到归档）
 /sm-flow explore            → 先聊聊（需求不清楚）
 /sm-flow apply              → 直接执行（已有 Committed OpenSpec）
 /sm-flow archive            → 归档（执行完了，回填 devflow + 归档 OpenSpec）
 ```
 | 命令 | 用户意图 | harness 内部行为 |
 |---|---|---|
 | `/sm-flow` | 从头到尾 | 完整编排 9 个阶段 |
 | `/sm-flow explore` | 先想想 | 带上下文的探索模式 |
 | `/sm-flow apply` | 只执行 | 检查 commit gate → apply |
 | `/sm-flow archive` | 收尾 | backfill devflow + 归档确认 |
 **典型使用场景**：
 ```
 # 第一次：完整规划
 /sm-flow 给站内消息加 OMC 支持
 → 走完 propose → grill → specify → audit → commit
 → 停在 apply 前，用户说"先不执行了"
 # 第二次：继续执行
 /sm-flow apply ops-message-support
 → 进入 apply，执行完 tasks
 # 第三次：归档
 /sm-flow archive ops-message-support
 → 回填 devflow，询问是否归档 OpenSpec change
 ```
 三个阶段，三次调用，每次只做一个用户意图的事。
 **阶段命名（内部协议）**：
 借鉴 OpenSpec 的动词式命名风格，阶段名称保留为 **agent 的词汇表**（用于 checkpoint 汇报和进度通知），不作为用户命令：
 ```
 旧编号      →  描述名（内部）    做什么
 Phase 0    →  clarify          入口澄清
 Phase 0.5  →  context          上下文收集
 Phase 1    →  propose          轻量 propose（只写 proposal）
 Phase 2    →  grill            人类对齐澄清
 Phase 1.5  →  specify          细化 + 对齐（补全 design/specs/tasks）
 Phase 2.5  →  audit            架构审计
 Phase 2.9  →  commit           commit gate
 Phase 3    →  apply            OpenSpec 执行
 Phase 4    →  archive          回填 devflow + 归档确认
 ```
 **agent 用阶段名做 telemetry**：
 - "当前在 grill 阶段，已解决 2/5 个问题"
 - "grill 完成，进入 specify"
 **用户用自然语言交互**：
 - "/sm-flow" → 启动完整流程
 - "ops-message-support 的 grill 已经做完了，继续" → harness 识别意图，自动补做最小前置检查
 - "帮我检查一下 add-dark-mode 的 OpenSpec 对齐" → harness 识别意图，只做 specify 阶段的对齐检查
 **核心原则**：用户只需要知道四件事（完整流程 / explore / apply / archive），其余全部通过自然语言交互，由 harness 识别意图后编排。
 **✅ 已落地**：SKILL.md 用户命令表格（4 个命令），operating-rules.md 启动检查已识别用户命令意图，phase-contracts.md 所有阶段已使用英文命名。
 ### 问题 5：workflow.md 的维护方式 ✅ 已确认方向
 **问题**：workflow.md 是 590 行的设计演进文档，混合了三类内容：设计理念（稳定）、变更日志（每次迭代追加）、历史对比（写完不动）。读者需要翻 590 行才能理解"现在的设计是什么"。
 **确认方向**：方向 A——顶部加"当前设计理念"摘要，历史部分作为审计轨迹保留。
 ```markdown
 # SM-Flow 工作流
 ## 当前设计理念（v4 方向）
 - sm-flow 是协议层 harness，编排 OpenSpec 生命周期
 - 四层架构：harness → OpenSpec → devflow → code
 - 用户命令 4 个：/sm-flow / explore / apply / archive
 - 9 个内部阶段（英文描述命名）：clarify → context → propose → grill → specify → audit → commit → apply → archive
 - 阶段名是内部协议，不是用户 API
 - 真理源分层：devflow=上下文, OpenSpec=执行, 代码=结果
 - Draft/Committed 分离
 - ...（20-30 行）
 ---
 ## 演进历史
 （原有的 v1→v3.1+ 内容不动）
 ```
 **来源**：design-review.md 的"核心定位"章节可以直接作为摘要的草稿。
 **⏳ 待落地**：在 workflow.md 顶部插入当前设计理念摘要段落（本项属于文档维护，不在 skill 文件范围内）。
 ### 问题 6：SKILL.md 核心规则分类 ✅ 已确认方向
 **问题**：当前 ~22 条核心规则平铺在一个列表里，混合了三种不同性质的约束。agent 读到第 15 条已经记不清前 5 条的优先级。
 **确认方向**：三类分组 + 英文阶段命名 + 质量约束必须有可观测产出。
 **A. 三类分组**
 ```markdown
 ## 核心规则
 ### 硬约束（违反即流程失败）
 - apply 必须通过 OpenSpec apply 执行
 - 不得跳过 context
 - 不得跳过 grill（至少三个高价值问题）
 - 不得跳过 commit
 - 不得猜测式修 bug
 - fallback 产物必须标注
 - micro 不能跳过关键 gate
 ### 流程约束（必须按顺序做）
 - 先建 question pool，再消费 user-interview
 - 单个 grill 决策确认不等于 apply 授权
 - 冲突必须先分类再处理
 - 影响实现的发现必须先回写 OpenSpec
 - 子 skill 必须显式调用或显式降级
 - clarify → apply 只维护 decisions.md，archive 阶段提取完整档案
 - archive 前必须询问是否归档
 ### 质量约束（必须有可观测产出）
 - specify 的 checkpoint 必须包含 cross-artifact 对齐检查表（4 行，每行标记已对齐/存在 gap）
 - evidence-driven 结论必须写入 decisions.md，且 checkpoint 必须列出汇报状态
 - user-interview 必须在 decisions.md 中记录问题原文、用户原话、确认状态；未确认的不能从 question pool 移除
 - checkpoint 必须包含：当前阶段、能力来源、产出物清单、已满足退出条件、未解决阻塞
 - human-in-the-loop 检查点：propose 后、audit 后、commit 后、apply 前
 > 三类约束都不可违反。分类的目的是帮助快速定位规则类型。
 > 质量约束必须转化为可观测的产出（写入文件 + checkpoint 检查），否则不是约束而是建议。
 ```
 **B. 阶段编号改为英文描述名**
 去掉 Phase 0/0.5/1/1.5/2/2.5/2.9/3/4 的数字编号，全部用英文动词：
 ```
 clarify  → 入口澄清
 context  → 上下文收集
 propose  → 轻量 propose（只写 proposal）
 grill    → 人类对齐澄清
 specify  → 细化 + cross-artifact 对齐
 audit    → 架构审计
 commit   → commit gate
 apply    → OpenSpec 执行
 archive  → 回填 devflow + 归档确认
 ```
 执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive
 用户命令是 API（4 个），阶段名是内部协议（9 个）。风格统一（英文动词），职责分离。
 **C. 质量约束的可观测产出原则**
 协议层 harness 的核心弱点：质量约束如果没有可观测的产出，agent 一定会跳过。
 | 约束 | 原写法（软） | 改为（硬） |
 |---|---|---|
 | evidence-driven 汇报 | "必须向用户汇报" | 写入 decisions.md + checkpoint 列出汇报状态 |
 | user-interview 确认 | "必须等待用户显式回答" | decisions.md 记录问题原文/用户原话/确认状态 |
 | cross-artifact 对齐 | "必须显式检查" | checkpoint 包含 4 行对齐检查表，每行标记已对齐/存在 gap |
 **✅ 已落地**：SKILL.md 核心规则已按三类分组重写（硬约束 / 流程约束 / 质量约束），phase-contracts.md 所有阶段使用英文命名，各 checkpoint 退出条件已加可观测产出检查。
 ### 问题 7：grill 阶段 evidence-driven 和 user-interview 的节奏 ✅ 已确认方向
 **问题**：当前规则说"可以并行整理 evidence-driven 证据，但 user-interview 仍然必须 one-at-a-time"。但 agent 可能把所有 evidence-driven 结论一口气汇报完，然后才问 user-interview 问题，导致用户被动接收大量信息后再被采访。
 **确认方向**：在 grill 阶段的动作描述里明确"交替推进"。
 ```markdown
 grill 阶段的推进节奏：
 - evidence-driven 和 user-interview 应交替推进，避免把所有证据结论攒到一起汇报
 - 典型模式：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续
 - evidence-driven 可以并行查证（不需要用户参与），但汇报和 user-interview 穿插进行
 ```
 **实际落地**：phase-contracts.md grill 阶段动作描述已调整。经评估后，"交替推进"对 agent 的要求过高（LLM 天然倾向批量处理），改为更务实的"先批量查证 evidence-driven 并一次性汇报，再逐个处理 user-interview"，降低执行复杂度同时保留核心约束。
@@ -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,208 @@
 # SM Flow 首次执行回顾
 **日期**：2026-05-21
 **变更**：[ops-message-support](projects/2026-05-21-ops-message-support/) — 站内消息新增 OMC 支持
 **目的**：以本次交互为例，逐阶段复盘实际执行与 SM Flow 预期的差距，作为后续执行的改进依据。
 ---
 ## Phase 0 — 入口澄清
 ### 应该做的
 - 收集问题、期望结果、目标用户、涉及代码区域、约束条件
 - 输出入口摘要、slug、规模分档
 ### 实际做的
 - 用户输入需求后，直接开始读代码和查数据库
 - 输出了 slug（`ops-message-support`）和分档（micro）
 ### 没做到的
 - 没有输出入口摘要（清晰的 1-2 句话问题 + 1-2 句话期望结果）
 - 没有列已知影响代码或模块清单
 ### 改进建议
 - Phase 0 结束时花 1 分钟写 3-5 行入口摘要到 `brief.md`，而不是等用户问再补
 ---
 ## Phase 0.5 — Devflow 上下文收集
 ### 应该做的
 - 初始化 devflow 目录结构
 - 读取 glossary、ADR、历史项目
 - 形成上下文摘要写入 brief.md
 ### 实际做的
 - 等用户质疑 devflow 无产物时才在 Phase 2.9 补创建
 ### 没做到的
 - ❌ **没有在 Phase 0.5 创建 devflow 项目目录和任何文件**
 - 没检查 glossary（当时为空也正常，但应该初始化和告知）
 ### 改进建议
 - 进入 Phase 0.5 就执行 `mkdir devflow/projects/{slug}/` 并创建 `brief.md` 骨架
 - Devflow 是"思考记录"不是"文档任务"，哪怕只写 3 行也比事后补强
 ---
 ## Phase 1 — OpenSpec propose
 ### 应该做的
 - 声明"本阶段调用 openspec-propose skill"
 - 如果不可用，降级为 fallback 并说明原因
 - 产出 proposal / design / specs / tasks
 ### 实际做的
 - 调用了 `openspec new change` 创建了 change 目录
 - openspec CLI 模板不匹配时报错，**没有声明降级**，直接手动创建文件
 - 手动创建了 research、proposal、design、specs、tasks
 ### 没做到的
 - ❌ **没有声明"openspec CLI 模板不匹配，降级为 manual fallback"**
 - ❌ **没有区分 Draft OpenSpec 和 Committed OpenSpec**（两者在流程中意义不同）
 - 产出顺序按了 research-first schema，但未验证 artifacts 间的依赖一致性
 ### 改进建议
 - Skill 不可用时必须说清楚：什么 skill + 什么原因不可用 + 降级方式
 - Draft OpenSpec 阶段标记为 draft，和 Committed OpenSpec 区分
 ---
 ## Phase 1.5 — PRD / OpenSpec 对齐
 ### 应该做的
 - 检查 proposal 是否覆盖 research 范围
 - 检查 design 是否满足 proposal 承诺的能力
 - 检查接口影响等级（L1-L4）
 ### 实际做的
 - **直接跳过**，没有做任何 formal 的对齐检查
 ### 没做到的
 - ❌ 对齐检查完全缺失
 - 后果：proposal.md 漏了 type 字段，design.md 和 research.md 都已包含但 proposal 没更新，直到用户 review 才发现
 ### 改进建议
 - 即使 micro 模式，至少做一次快速交叉检查：research 范围 ↔ proposal 变更 ↔ design 决策 ↔ specs 场景
 ---
 ## Phase 2 — Human-in-the-loop 澄清
 ### 应该做的
 - 声明"本阶段调用 grill-with-docs skill"，按结构化方式追问
 - 至少覆盖术语、边界、验收三个维度
 - evidence-driven 的先查证再汇报
 - user-interview 的**一次只问一个问题**，等用户确认后再问下一个
 - 用户确认后回写 OpenSpec
 - 对模糊的术语（如"运管"）通过 grill 确认其准确定义
 ### 实际做的
 - **没有调用 grill-with-docs** ❌
 - **一次问了 3 个 user-interview 问题**，违反规则 ❌
 - 收集了充分的 evidence（代码和数据库分析到位）✓
 - 用户确认后及时回写了 OpenSpec ✓
 ### 没做到的
 - ❌ 没有使用 grill 或任何结构化追问工具，自己随意问了几个问题
 - ❌ 一次多问被用户 reject
 - 问题数量太少：只用了 3 个问题（编码、子分类、字段范围），远不足以覆盖所有盲区
 - 以下该问但没有问的问题：
  - OMC 消息从哪里发送？通过什么 identifier/messageCode 触发投递？
  - OMC 用户侧的权限体系是怎样的？和 APP 用户在同一张权限表吗？
  - OMC 前端需要怎样的响应结构？只要总数还是要子分类列表？
  - 现有 APP 端有 hasUnread/readAll 等功能，OMC 端是否也需要？
  - OMC 消息的创建时间和保留策略？
 - "运管"这个概念从一开始就模棱两可，没有通过 grilling 追根究底，到用户主动纠正为 OMC 时才明确
 ### 改进建议
 - 必须调用 grill-with-docs，不调用就是跳过
 - 问题数量下限：至少 5-8 个尝试性提问，覆盖：术语定义、发送来源、权限模型、前端需求、功能对标
 - 一次一问，等回复后再继续
 - 在 Phase 2 开始时创建 Task 跟踪 grill 进度："Q1[术语]...→Q2[边界]...→Q3[验收]..."，每问一个更新一次
 ---
 ## Phase 2.5 — 架构审计
 ### 应该做的
 - 画出输入 → 处理 → 输出的模块链路
 - 识别跨模块依赖、数据所有权、生命周期和耦合风险
 - 用不超过五句话写出架构风险评估
 - 影响实现的结论回写 OpenSpec design/tasks
 ### 实际做的
 - **直接跳过**
 - 做了代码分析但未输出正式的架构审计记录
 ### 没做到的
 - ❌ 模块链路图缺失
 - ❌ 接口影响分析表是用户追问后才补的
 - ❌ listMessageCategory 泄漏 OMC 的问题在架构审计中本应发现，但跳过后留到了用户 review 才发现
 ### 改进建议
 - Phase 2.5 至少画一张文本链路图：`User → Controller → Service → Mapper → DB`
 - 然后问自己：新增的 type 字段会影响哪些链路节点？
 ---
 ## Phase 2.9 — Commit OpenSpec
 ### 应该做的
 - 检查所有 artifacts 的一致性
 - 检查所有 user-interview 都已确认
 - 检查接口影响已记录
 - 向用户汇报并请求 Phase 3 授权
 ### 实际做的
 - 做了检查，但不够彻底（proposal 漏了 type）
 - 接口影响分析是补的
 - 汇报了，但用户先发现了 type 字段问题
 ### 没做到的
 - 没能在用户发现问题前自己找出 proposal 遗漏
 - 自检清单没有对照执行
 ### 改进建议
 - Phase 2.9 不能光靠头脑检查，要逐行对比 research ↔ proposal ↔ design ↔ specs ↔ tasks 的关键断言
 ---
 ## Phase 3 — OpenSpec apply
 尚未开始
 ---
 ## Phase 4 — 回填 Devflow
 ### 应该做的
 - 验收记录
 - 更新 devflow/index.md
 - 询问是否归档 OpenSpec change
 ### 实际做的
 - devflow 产物在用户要求下补创建
 - index.md 在用户质疑后创建
 ### 改进建议
 - Phase 4 的 devflow 产物应该是最轻松的，因为内容已经在各阶段产出过，只需要汇总
 ---
 ## 根因总结
 ### 约束是否到位？
 SM Flow 的 rules 在 SKILL.md 和 reference 中写得很清楚。问题**不是约束不到位**，而是：
 1. **高估了小改动的判断** — micro 分档让我误以为"可以跳过检查"，实际 micro 只合并产物不跳过阶段
 2. **按代码习惯而非按流程执行** — 作为习惯于输出代码的 agent，对流程节点的重视度天然低于代码
 3. **缺少执行中的自检机制** — rules 只在加载时读一次，被上下文冲走后就没有对照检查
 ### 核心教训
 - **Devflow 是思考过程，不是文档任务** — 写文档的过程就是做架构审计和一致性检查的过程
 - **Micro 不等于跳过** — 产物可以合并，但检查点不能省略
 - **声明即约束** — 把"本阶段调用 X / 降级为 Y"说出来，是对自己的提醒也是对用户的透明
 - **Devflow 和 OpenSpec 同步更新** — 更新 OpenSpec 时同步更新 devflow，不要把 devflow 留到 Phase 4 一次性补。两者是同一件事的两面，不是先后关系
@@ -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,4 +1,73 @@
-# 增强版工作流总结
+# SM-Flow 工作流
 ## 当前设计理念（v4.3）
 **核心定位**：sm-flow 是一个**用提示词实现的协议层 harness**——编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。
 **四层架构**：
 ```
 sm-flow        → 编排层（harness）：阶段、门控、产物约束、人类对齐
  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
      code     → 实现结果：apply 的产出
 ```
 **用户命令（4 个）**：
 | 命令 | 用户意图 |
 |---|---|
 | `/sm-flow` | 完整流程 |
 | `/sm-flow explore` | 先想想（需求不清楚） |
 | `/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 个，英文动词命名）**：
 ```
 clarify → context → propose → grill → specify → audit → commit → apply → archive
 入口澄清   上下文     轻量提案   澄清    细化      审计    提交     执行    归档
 ```
 阶段名是 harness 的内部协议词汇，不是用户 API。面向用户默认只暴露 4 个可见 checkpoint：Discover、Commit、Apply、Archive；内部阶段仍按顺序执行。
 **关键设计决策**：
 - **真理源分层**：devflow = 上下文（术语、历史决策、验收记录），OpenSpec = 执行（唯一执行真理源），代码 = 结果。devflow 增强 OpenSpec，不替代 OpenSpec。
 - **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**：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 检查），否则不是约束而是建议。
 **使用方式**：
 详细的使用说明见 [使用方式.md](./使用方式.md)，包括：
 - 4 个用户命令的典型场景
 - 完整规划 → 执行 → 归档的分次调用示例
 - 自然语言交互方式
 - 规模分档（micro / standard / complex）
 - devflow 自动维护机制
 - OpenSpec 集成与 Draft/Committed 分离
 - 常见问题解答
 ---
 ## 演进历史
 以下是 sm-flow 工作流的历史演进记录，从 v1 到当前 v4 方向。每一版都从真实执行失败中提炼，不是理论推演。
 ## 旧工作流 vs 新工作流
@@ -34,14 +103,14 @@ Phase 4  openspec:apply     Phase 2    grill-with-docs → CONTEXT.md + ADR
 ## 新增技能的投入产出
-| 技能 | 学多久 | 一次省多少 | 什么时候用 |
+| 技能 | 接入成本 | 主要收益 | 什么时候用 |
 |------|--------|-----------|-----------|
-| to-prd | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 |
+| to-prd | 自动综合 | 结构化需求 | openspec research 结束后 |
-| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 |
+| grill-with-docs | 替换已有 grill-me | 产出文档化澄清 | 需求澄清阶段 |
-| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 |
+| zoom-out | 低 | 避免方向性返工 | grill 完成后、apply 前 |
-| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 |
+| diagnose | 低 | 减少猜测式 bug 修复 | apply 中遇到问题 |
-| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 |
+| tdd | 低 | 减少回归 bug | apply 中写代码 |
-| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 |
+| git-guardrails | 被动生效 | 防止灾难性操作 | 全程自动 |
 ## 为什么这套组合优于单纯依赖 openspec
@@ -412,8 +481,56 @@ Phase 2 的 `grill-with-docs` 不是代理自问自答。`user-interview` 问题
 `evidence-driven` 问题可以由代理先查证，但也必须汇报证据、结论和是否需要用户确认。
 Phase 2 在开始追问前，还应该先建立一个 question pool。最小问题池至少覆盖：
 - 术语
 - 范围边界
 - 验收口径
 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，再把这些维度补进问题池。问题池的作用是先把风险面列全，再继续保持 one-at-a-time 的 `user-interview` 消费节奏，而不是一次把所有问题都抛给用户。
 单个 grill 决策确认不等于 Phase 3 apply 授权。用户在 Phase 2 回答“可以”只表示该问题已确认；代理必须先回写 OpenSpec/devflow，停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply、开始实现、执行修改或继续 Phase 3。
 ### Phase Checkpoint
 v3.1 的另一个收紧点是：关键阶段不再靠“看起来做完了”判断完成，而是靠显式 checkpoint。
 关键阶段至少包括：
 - Phase 0
 - Phase 0.5
 - Phase 1
 - Phase 2
 - Phase 2.5
 - Phase 2.9
 每个 checkpoint 至少说明：
 - 当前阶段
 - 调用的 capability 来源
 - 产出的关键 artifact
 - 已满足的退出条件
 - 尚未解决的 blocker
 如果没有这些信息，就不应该把阶段视为已完成，更不应该直接进入下一阶段。
 ### Cross-Artifact Alignment
 v3.1 之后，Phase 1.5 和 Phase 2.9 不只是“看看文档差不多”，而是要显式检查一条对齐链：
 ```text
 brief/prd -> proposal -> design -> specs -> tasks
 ```
 检查重点不是格式，而是下游产物有没有把上游已经确定的内容接住，例如：
 - `brief/prd` 里的范围和非目标有没有进入 `proposal`
 - `proposal` 的关键承诺有没有进入 `design`
 - `design` 里的实现约束和接口影响有没有进入 `specs` 或 `tasks`
 - `specs` 里的可观察行为有没有被 `tasks` 切成可执行工作
 如果字段、术语、约束、行为或切片只停留在上游文档里，就应该视为对齐缺口，先修 OpenSpec，再继续流程。
 ### 接口影响分级
 v3.1 区分“接口影响记录”和“独立接口文档”：
@@ -445,6 +562,21 @@ devflow/compound/
 Phase 4 回填项目档案时必须更新 `devflow/index.md`。最小字段为日期、slug、领域、关键词、关联 OpenSpec 和状态。
 另外，v3.1 也把一个实践经验写成硬规则：devflow 不是等到 Phase 4 才第一次补写。`brief.md`、`evidence.md`、`decisions.md` 这类过程内档案应该随阶段就近更新，Phase 4 主要负责 consolidation 和归档口径收束。
 ### Micro 不是 Skip
 `micro` 的目标是降低文档重量，不是给代理发放“可以跳 gate”的许可证。
 因此即使是 `micro` 变更，也仍然要保留：
 - Phase 0.5 最小上下文收集
 - Phase 2 最小澄清
 - Phase 2.9 commit gate
 - Phase 4 轻量回填
 如果因为“改动很小”就跳过这些 gate，应该视为协议偏差，而不是合法优化。
 ### 实现期冲突处理
 Phase 3 中，如果用户质疑、用户修改、代码发现、测试失败或运行行为与 Committed OpenSpec 冲突，必须先分类：
@@ -470,6 +602,634 @@ v3.1 将子 skill 从“路径绑定”改为“能力绑定”。例如 `opensp
 这样 `sm-flow` 可以在 Claude、Codex 或其他代理环境中迁移，而不会被某个固定目录锁死。
 一旦进入 fallback，代理还必须把这次降级本身记录下来。也就是说，fallback 不只是“内部换个做法”，而是一个需要显式声明 capability 缺失、降级原因和风险的协议事件。
 ## v3.1 后续收口：协议瘦身与 review 修正
 在执行硬化规则落地后，又做了一轮非常实际的收口：不是再增加新规则，而是把已经确认的规则放到更稳定、可维护的位置，并修掉瘦身过程中暴露的引用问题。
 ### 顶层 skill 瘦身
 `SKILL.md` 不再同时承担“入口协议”和“大段运行手册”两种职责，而是收敛为：
 - 工作流定位
 - 真理源分层
 - 核心硬规则
 - reference 加载入口
 - 阶段总览
 原来放在顶层但更适合按需读取的内容，被下沉到新的：
 ```text
 references/operating-rules.md
 ```
 这里集中放：
 - 接口影响分级
 - 启动检查
 - 项目标识规则
 - devflow 产物分层
 - 快速模式细则
 - 完成标准
 这样做的目标不是减少规则，而是减少“启动时一次读太多”和“顶层协议与 reference 抢职责”的问题。
 ### Fallback 去重复
 `fallbacks.md` 也做了第二轮整理：
 - 顶部统一定义 fallback 通用记录要求
 - 各 fallback 小节只保留自己的额外记录义务
 这样可以避免每个 fallback 都重复写一遍“要声明 fallback、要记录 fallback”，同时不丢失协议要求。
 ### Review 驱动的自洽性修正
 瘦身后又发现了一类很典型的问题：**规则本身没错，但 cross-reference 可能断掉**。因此又补了一轮 review 驱动修正，重点包括：
 - `phase-contracts.md` 在首次使用接口分级、分档、快速模式时，显式指向 `operating-rules.md`
 - 修正 fallback 锚点，避免 skill 指向不存在的章节名
 - 统一 `operating-rules.md` 的语言风格，避免在主协议是中文时夹着一整份英文运行规则
 这轮修正说明一件事：协议产品化不只是”把规则写出来”，还要保证**入口、逐阶段契约、fallback 和运行规则之间的导航关系始终自洽**。
 ## v4.0：协议层 Harness 重设计
 ### 背景
 v3.1+ 的规则已经比较完整，但一次完整设计评审暴露出三个结构性问题：
 1. **定位模糊**：SKILL.md 说”不替代 OpenSpec，而是增强”，但实际上 sm-flow 已经在编排 OpenSpec 的完整生命周期——包括 propose 时机、grill 顺序、commit gate、apply 授权。这不是”增强”，这是”编排”。
 2. **阶段顺序导致返工**：Phase 1 一次性产出完整 4 件套（proposal + design + specs + tasks），Phase 2 才做 grill 澄清。澄清结果必然回写已细化的产物，形成不可避免的返工循环。
 3. **规则过载**：19 条核心规则平铺在一个列表里，混合了硬约束、流程约束和质量约束。agent 读到第 15 条已经记不清前 5 条的优先级。
 ### 核心认知转变
 sm-flow 不是一个”更好的 skill”，也不是 OpenSpec 的增强插件。它是一个**用提示词实现的协议层 harness**——控制 agent 以什么顺序、什么条件、什么标准使用工具。
 这个认知来自一个类比：Claude Code harness 是**代码实现**的（工具权限、hooks、context window），agent 物理上绕不过。sm-flow 是**提示词实现**的，agent 理论上可以违反。因此 sm-flow 需要 checkpoint、显式约束、降级声明等机制来强化执行力——这些机制的本质就是弥补提示词 harness 缺乏物理强制力的弱点。
 ### 四层架构
 ```
 Claude Code Harness  → 代码层：工具权限、hooks、context window（agent 绕不过）
  sm-flow Harness    → 协议层：工作流阶段、门控规则、产物约束、人类对齐（提示词实现）
    OpenSpec         → 执行引擎：propose/apply/archive 的具体操作
      Sub-skills     → 能力层：grill、zoom-out、diagnose、tdd
 ```
 ### 用户命令：Actions, Not Phases
 借鉴 OpenSpec 的 “Actions, Not Phases” 设计哲学——用户命令表达意图，不表达阶段。阶段是 harness 的内部词汇，不是用户的 API。
 v3.1 有 9 个阶段编号（Phase 0 / 0.5 / 1 / 1.5 / 2 / 2.5 / 2.9 / 3 / 4），用户需要记住每个编号对应的含义。v4 收敛为 4 个用户命令：
 | 命令 | 用户意图 |
 |---|---|
 | `/sm-flow` | 完整流程（从入口到归档） |
 | `/sm-flow explore` | 先聊聊（需求不清楚） |
 | `/sm-flow apply` | 只执行（已有 Committed OpenSpec） |
 | `/sm-flow archive` | 收尾（回填 devflow + 归档确认） |
 内部阶段全部改为英文动词命名：
 ```
 clarify → context → propose → grill → specify → audit → commit → apply → archive
 ```
 ### 阶段顺序调整：grill 在 specify 前
 v3.1 的执行顺序：propose（完整 4 件套）→ grill → specify → audit → commit → apply
 v4 的执行顺序：propose（只写轻量 proposal）→ grill → specify（补全 design/specs/tasks）→ audit → commit → apply
 核心改变：propose 只写轻量 proposal.md，不调用 openspec-propose。grill 在需求稳定前完成澄清。specify 在需求稳定后才调用 openspec-propose 补全完整 OpenSpec。
 这消除了返工循环——grill 在细化之前，不存在”细化 → grill → 回写细化”的问题。
 ### devflow 延迟写入
 v3.1 要求 devflow 产物按阶段就近更新（brief、evidence、decisions 随阶段写入），Phase 4 做 consolidation。实践中 agent 同时维护 OpenSpec 和 devflow 形成双重记录。
 v4 改为：clarify → apply 期间只维护 `decisions.md` 作为过程日志。archive 阶段从 decisions.md + OpenSpec 产物提取完整档案（brief.md、evidence.md、decisions.md、acceptance.md）。
 ### 规则精简：19 条 → 6 条硬约束
 v3.1 的 19 条规则按三类分组（硬约束 7 条 / 流程约束 7 条 / 质量约束 5 条）。v4 进一步精简为 6 条硬约束留在 SKILL.md，其余约束下沉到 phase-contracts.md 各阶段退出条件。
 ```
 v3.1：SKILL.md 包含 19 条三类规则 → agent 需要同时记住所有规则
 v4：SKILL.md 只放 6 条硬约束 → agent 按阶段加载对应的过程约束和质量约束
 ```
 6 条硬约束：
 1. OpenSpec 是唯一执行真理源
 2. 不得跳过 context
 3. 不得跳过 grill（至少 3 个问题）
 4. 不得跳过 commit
 5. 冲突必须先分类再处理
 6. 降级执行必须标注
 ### 冲突分类简化
 v3.1 的四分类（实现偏差 / 规格遗漏 / 设计冲突 / 用户变更）在实际执行中边界模糊，agent 需要同时判断类型、选择处理方式、记录到 decisions.md、考虑是否回写 OpenSpec。判断链过长。
 v4 简化为 2+1：
 - OpenSpec 不准 → 修 OpenSpec
 - 代码偏离 → 修代码
 - 不确定 → 暂停等用户确认
 ### 质量约束可观测化
 v3.1 的质量约束（如”evidence-driven 必须汇报””user-interview 必须等确认”）缺乏可观测产出，agent 可能形式化地填写而不真正验证。
 v4 要求质量约束必须有可观测产出：写入文件 + checkpoint 检查。例如：
 | 约束 | v3.1（软） | v4（硬） |
 |---|---|---|
 | evidence-driven 汇报 | “必须向用户汇报” | 写入 decisions.md + checkpoint 列出汇报状态 |
 | user-interview 确认 | “必须等待用户回答” | decisions.md 记录问题原文/用户原话/确认状态 |
 | cross-artifact 对齐 | “必须显式检查” | checkpoint 包含 4 行对齐检查表 |
 ### Micro 模式升级
 v3.1 的 micro 只压缩产物（少写几个文件），没有压缩 gate 数量。v4 的 micro 合并 gate：
 ```
 v3.1 micro：仍然走完整阶段，只是产物变少
 v4 micro：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题）→ commit（简化检查）
 ```
 ### 文件结构变化
 ```
 v3.1：
 .agents/skills/sm-flow/
 ├── SKILL.md                         # ~85行，入口协议 + 19条规则 + 阶段总览
 └── references/
    ├── phase-contracts.md           # 阶段契约（Phase 0-4 编号）
    ├── operating-rules.md           # 运行规则
    ├── fallbacks.md                 # 降级协议
    ├── archive-rules.md             # 归档规则
    └── templates.md                 # 产物模板
 v4：
 .agents/skills/sm-flow/
 ├── SKILL.md                         # ~50行，入口协议 + 6条硬约束 + 4命令 + 9阶段总览
 └── references/
    ├── phase-contracts.md           # 阶段契约（英文命名，grill 在 specify 前）
    ├── operating-rules.md           # 运行规则（启动识别 4 命令，micro 合并 gate）
    ├── fallbacks.md                 # 内置执行协议（冲突 2+1 分类）
    ├── archive-rules.md             # 归档规则（decisions.md 过程日志提取）
    └── templates.md                 # 产物模板（+cross-artifact 对齐检查表）
 ```
 ### 新增文档
 - `skill-workbench/docs/sm-flow/使用方式.md`：面向用户的使用指南
 - `skill-workbench/docs/sm-flow/design-review.md`：设计评审记录
 ### v3.1 → v4 变更对照
 | 维度 | v3.1 | v4 |
 |---|---|---|
 | 定位 | “OpenSpec 的上下文增强层和归档闭环层” | “协议层 harness，编排 OpenSpec 完整生命周期” |
 | 阶段命名 | Phase 0/0.5/1/1.5/2/2.5/2.9/3/4 | clarify/context/propose/grill/specify/audit/commit/apply/archive |
 | 用户命令 | 无（用户需要知道阶段编号） | 4 个命令（Actions, Not Phases） |
 | propose 产出 | 完整 4 件套（proposal+design+specs+tasks） | 只写轻量 proposal.md |
 | grill 时机 | specify 之后 | specify 之前 |
 | devflow 写入策略 | 按阶段就近更新多个文件 | 只维护 decisions.md，archive 提取 |
 | 核心规则数量 | 19 条三类分组 | 6 条硬约束 |
 | 冲突分类 | 4 类（实现偏差/规格遗漏/设计冲突/用户变更） | 2+1（OpenSpec 不准/代码偏离/不确定） |
 | micro 模式 | 压缩产物 | 合并 gate |
 | 质量约束 | 文字描述 | 可观测产出（写入文件 + checkpoint） |
 ## v4.0 验证执行复盘（2026-05-25）
 用 entry-expand-collapse 需求跑了一轮完整 sm-flow 流程，验证 v4.0 协议的可执行性。功能变更已回滚，仅保留验证发现。
 ### 暴露的问题
 | # | 问题 | 具体表现 | 分析结论 |
 |---|------|----------|----------|
 | 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 应描述用户可观察的结果而非实现方式 |
 ### 做对的部分
 - clarify + context 合并执行正确（micro 模式）
 - grill 的 evidence-driven / user-interview 分类和 one-at-a-time 节奏执行到位
 - commit gate 的文件存在性检查生效
 - apply 阶段的冲突分类（代码偏离）处理正确
 - devflow 延迟写入（只维护 decisions.md）降低了维护成本
 ### 后续观察项
 问题 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/`
@@ -0,0 +1,191 @@
 # SM-Flow 使用方式
 本文档面向 sm-flow 的用户，说明如何启动、交互和使用 sm-flow。
 ## 快速开始
 sm-flow 通过 4 个用户命令覆盖完整生命周期。你不需要了解内部阶段，只需表达意图。
 | 命令 | 意图 | 典型场景 |
 |---|---|---|
 | `/sm-flow` | 完整流程 | 有粗略想法，从头规划到执行 |
 | `/sm-flow explore` | 先聊聊 | 需求不清楚，带上下文探索 |
 | `/sm-flow apply [change]` | 只执行 | 已有 Committed OpenSpec，直接实现 |
 | `/sm-flow archive [change]` | 收尾 | 执行完了，回填 devflow + 归档 |
 你也可以用自然语言指定阶段继续，例如：
 ```
 ops-message-support 的 grill 已经做完了，继续
 帮我检查一下 add-dark-mode 的 OpenSpec 对齐
 ```
 sm-flow 会识别意图，自动补做最小前置检查，然后从指定阶段继续。
 ## 典型使用流程
 ### 场景 1：完整规划 → 执行 → 归档（分三次调用）
 ```bash
 # 第一次：完整规划
 /sm-flow 给站内消息加 OMC 支持
 → 走完 clarify → context → propose → grill → specify → audit → commit
 → 停在 apply 前，你说"先不执行了"
 # 第二次：继续执行
 /sm-flow apply ops-message-support
 → 进入 apply，执行完 tasks
 # 第三次：归档
 /sm-flow archive ops-message-support
 → 回填 devflow，询问是否归档 OpenSpec change
 ```
 三个阶段，三次调用，每次只做一个用户意图的事。
 ### 场景 2：需求不清楚，先探索
 ```bash
 /sm-flow explore 我们在考虑是否要重构消息队列
 → sm-flow 读取 devflow 上下文，和你讨论需求边界、风险、替代方案
 → 不生成 OpenSpec，只帮你理清思路
 → 如果讨论出明确方向，下次可以用 /sm-flow 启动完整流程
 ```
 ### 场景 3：小改动，快速模式
 ```bash
 /sm-flow 修复按钮的拼写错误
 → sm-flow 识别为 micro 规模
 → 合并 gate：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题）→ commit（简化检查）
 → 保留最关键的门控，但流程更轻量
 ```
 ### 场景 4：从中间继续
 ```bash
 # 上次对话停在 grill 阶段
 add-dark-mode 的 grill 已经做完了，继续
 → sm-flow 识别意图，自动补做 specify 的最小前置检查
 → 从 specify 阶段继续
 ```
 ## 交互模式
 ### Human Checkpoint
 sm-flow 在关键节点会暂停并询问你：
 - **propose 后**：说明 proposal 范围、关键假设、主要风险，询问是否继续 grill
 - **grill 后**：汇报已解决和未解决的问题、proposal 变更，询问是否继续 specify
 - **audit 后**：说明架构风险、OpenSpec 修正点，询问是否进入 commit
 - **commit 后**：说明 Committed OpenSpec 范围、接口影响、剩余风险，询问是否进入 apply
 - **archive 前**：询问是否归档 OpenSpec change
 你可以选择继续、暂停、或要求返回上一阶段。
 ### Grill 阶段的一对一澄清
 grill 阶段会建立一个 question pool，覆盖术语、边界、验收三个维度。问题分两类：
 - **evidence-driven**：sm-flow 先查证代码、文档、OpenSpec 或 ADR，再向你汇报证据和结论
 - **user-interview**：sm-flow 一次只问一个问题，等你确认后才继续
 典型节奏：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续。
 ### 自然语言交互
 除了 4 个命令，你可以用自然语言与 sm-flow 交互：
 ```
 # 指定 change name
 继续 ops-message-support
 # 指定阶段
 add-dark-mode 的 specify 做完了吗？
 # 指定动作
 帮我检查一下 add-dark-mode 的 cross-artifact 对齐
 # 混合表达
 ops-message-support 的 grill 已经确认了术语和边界，继续 specify
 ```
 sm-flow 会识别意图，自动编排后续阶段。
 ## 规模分档
 sm-flow 根据变更规模自动分档，调整流程重量：
 | 分档 | 适用场景 | 流程特点 |
 |---|---|---|
 | `micro` | 小改动、低风险、需求明确 | gate 合并，grill 最少 1 个问题，commit 简化检查 |
 | `standard` | 默认模式 | 完整 9 阶段流程 |
 | `complex` | 高风险、跨模块、需求不清、多人协作 | standard 基础上增加扩展产物（PRD/research/design/tasks/alignment） |
 你不需要显式指定分档，sm-flow 会在 clarify 阶段自动判断。如果判断不准，会作为 user-interview 问题等待你确认。
 ## devflow：自动维护的项目长期记忆
 sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。你不需要手动管理它。
 ```
 devflow/
 ├── projects/YYYY-MM-DD-{slug}/       ← 项目档案（brief/evidence/decisions/acceptance）
 ├── glossary/CONTEXT.md                ← 领域词汇表
 ├── compound/                          ← 跨项目知识沉淀
 ├── reference/                         ← 共享模板
 └── index.md                           ← 项目索引
 ```
 **clarify → apply 期间**：sm-flow 只维护 `decisions.md` 作为过程日志（grill 结论、关键决策、验证结果）。
 **archive 阶段**：从 decisions.md + OpenSpec 产物提取完整档案（brief.md、evidence.md、decisions.md、acceptance.md）。
 **下次使用时**：sm-flow 会自动读取 devflow 上下文，增强 OpenSpec 产物。术语、历史决策、验收记录不会丢失。
 ## OpenSpec 集成
 sm-flow 编排 OpenSpec 的生命周期，但不强制依赖 OpenSpec CLI：
 - **优先使用 OpenSpec CLI**：如果 `openspec-propose`、`openspec-apply-change`、`openspec-archive-change` 可用，sm-flow 会调用它们
 - **内置执行协议**：如果 OpenSpec CLI 不可用，sm-flow 使用内置协议接管（标注为降级执行）
 Draft / Committed 分离：
 - **Draft OpenSpec**：propose 阶段产出，是讨论对象，不是执行许可
 - **Committed OpenSpec**：通过 commit gate 后，成为 apply 的执行依据
 - **apply 只执行 Committed OpenSpec**：防止未经澄清的方案直接进入实现
 ## 常见问题
 ### Q: 我需要在启动前准备什么？
 不需要。sm-flow 会从你的粗略想法、issue、PRD 或已有 research 开始。如果信息不足，clarify 阶段会追问。
 ### Q: 我可以跳过某个阶段吗？
 不可以。sm-flow 的门控是硬约束（grill 至少 3 个问题、commit gate 必须通过）。但 micro 模式会合并 gate，减少流程开销。
 ### Q: 如果 OpenSpec 不可用怎么办？
 sm-flow 会使用内置执行协议接管，标注为降级执行。产物仍然写入 `openspec/changes/{slug}/`，只是不通过 OpenSpec CLI。
 ### Q: devflow 和 OpenSpec 冲突怎么办？
 sm-flow 会先汇报冲突，等你确认，然后修正 OpenSpec，再继续执行。devflow 是上下文，OpenSpec 是执行真理源。
 ### Q: 我可以修改已经 commit 的 OpenSpec 吗？
 可以。如果 apply 阶段发现规格遗漏、设计冲突或用户变更，sm-flow 会暂停 apply，修正 OpenSpec 后重新提交。
 ### Q: archive 阶段会自动归档 OpenSpec 吗？
 不会。archive 阶段会回填 devflow，然后询问你是否归档 OpenSpec change。在你说"是"之前，不会执行归档。
 ## 参考文档
 - **设计理念**：[workflow.md](./workflow.md) — 当前设计理念（v4 方向）和演进历史
 - **设计评审**：[design-review.md](./design-review.md) — 核心定位、状态评估、已确认修改方向
 - **回溯分析**：[retrospective.md](./retrospective.md) — 历史执行失败分析
 - **使用问题**：[使用问题.md](./使用问题.md) — 真实痛点收集
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
zhuyongxin	9b44dc1395	remove unused devflow/reference and ignore .codex - devflow/reference/ was a placeholder from initial design with no write/read rules defined across v2-v4 iterations - .codex/ is tool-generated and should not be tracked	2026-05-26 10:14:25 +08:00
zhuyongxin	63994b6440	harden sm-flow protocol and archive v4.0 validation runs - Rewrite hard constraint #1: apply must read Committed OpenSpec files as the execution source of truth - Promote sub-skill invocation to hard constraint #6; remove fallbacks.md and all degradation paths - Add file existence verification at commit and archive exit gates - Require grill question pool, evidence-driven conclusions, and user-interview confirmations to be written to decisions.md - Record v4.0 validation retrospective in workflow.md: propose overreach, sub-skill pseudo-calling, spec omitting user behavior - Archive knowledge-index-sort OpenSpec and devflow entries from prior run	2026-05-26 09:59:24 +08:00
zhuyongxin	71e0b7f801	redesign sm-flow v4.0 as protocol-layer harness - Reposition sm-flow as orchestration harness over OpenSpec lifecycle - Adopt 4 user commands (Actions, Not Phases) instead of phase numbers - Rename all stages to English verbs (clarify through archive) - Reorder execution: grill before specify to eliminate rework loops - Simplify core rules from 19 to 6 hard constraints in SKILL.md - Simplify conflict classification from 4 categories to 2+1 - Switch devflow strategy to decisions.md-only process log during execution - Upgrade micro mode from artifact compression to gate merging - Add observable outputs for quality constraints - Add design review doc and user guide - Append v4.0 changelog to workflow.md	2026-05-25 17:28:15 +08:00
zhuyongxin	1f01e30c4e	harden and streamline sm-flow protocol	2026-05-25 11:44:20 +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.`