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

skill-workbench/docs/sm-flow/design-review.md

@@ -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"，降低执行复杂度同时保留核心约束。

skill-workbench/docs/sm-flow/workflow.md

@@ -1,4 +1,62 @@
-# 增强版工作流总结
+# SM-Flow 工作流
+
+## 当前设计理念（v4 方向）
+
+**核心定位**：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 + 归档确认） |
+
+**内部阶段（9 个，英文动词命名）**：
+
+```
+clarify → context → propose → grill → specify → audit → commit → apply → archive
+入口澄清   上下文     轻量提案   澄清    细化      审计    提交     执行    归档
+```
+
+阶段名是 harness 的内部协议词汇（用于 checkpoint 汇报和进度通知），不是用户 API。用户只需知道 4 个命令，其余通过自然语言交互，由 harness 识别意图后编排。
+
+**关键设计决策**：
+
+- **真理源分层**：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**：快速模式合并 gate（clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill 最少 1 个问题 → commit 简化检查），但保留最关键的门控。
+- **质量约束可观测**：质量约束必须转化为可观测产出（写入文件 + checkpoint 检查），否则不是约束而是建议。
+
+**使用方式**：
+
+详细的使用说明见 [使用方式.md](./使用方式.md)，包括：
+
+- 4 个用户命令的典型场景
+- 完整规划 → 执行 → 归档的分次调用示例
+- 自然语言交互方式
+- 规模分档（micro / standard / complex）
+- devflow 自动维护机制
+- OpenSpec 集成与 Draft/Committed 分离
+- 常见问题解答
+
+---
+
+## 演进历史
+
+以下是 sm-flow 工作流的历史演进记录，从 v1 到当前 v4 方向。每一版都从真实执行失败中提炼，不是理论推演。
 
 ## 旧工作流 vs 新工作流
 
@@ -583,8 +641,157 @@ references/operating-rules.md
 - 修正 fallback 锚点，避免 skill 指向不存在的章节名
 - 统一 `operating-rules.md` 的语言风格，避免在主协议是中文时夹着一整份英文运行规则
 
-这轮修正说明一件事：协议产品化不只是“把规则写出来”，还要保证**入口、逐阶段契约、fallback 和运行规则之间的导航关系始终自洽**。
+这轮修正说明一件事：协议产品化不只是”把规则写出来”，还要保证**入口、逐阶段契约、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） |

skill-workbench/docs/sm-flow/使用方式.md

@@ -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) — 真实痛点收集