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

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

@@ -1,74 +1,75 @@
 ---
 name: sm-flow
-description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
+description: OpenSpec-first 的结构化工程开发协议层 harness。编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用。
 ---
 
 # 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        → 编排层（harness）：阶段、门控、产物约束、人类对齐
+  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
+    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
+      code     → 实现结果：apply 的产出
+```
 
-- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。
-- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
-- 代码是实现结果：只能在执行真理源足够明确后修改。
-- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
-- Phase 1 产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 Phase 3 的执行许可。
-- 只有通过 Phase 2.9 提交检查后的 OpenSpec 才是 **Committed OpenSpec**；Phase 3 只能执行 Committed OpenSpec。
+- 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 写代码。
-- devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。
-- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
-- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
-- 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。
-- Phase 0、0.5、1、2、2.5、2.9 只有在显式 checkpoint 后才算完成；checkpoint 至少汇报当前阶段、能力来源、产出物、已满足退出条件和未解决阻塞。
-- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
-- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
-- Phase 1.5 必须显式检查 `brief/prd -> proposal -> design -> specs -> tasks` 的 cross-artifact 对齐；发现缺口时先修 OpenSpec，再继续后续阶段。
-- Phase 2 必须先建立 question pool，再按 one-at-a-time 规则消费 `user-interview` 问题；问题池至少覆盖术语、边界、验收，复杂变更还要补充模块、接口、权限、消费者、响应结构或生命周期维度。
-- grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
-- 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。
-- 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 调用。
-- `micro` 只能压缩产物重量，不能跳过关键 gate；Phase 0.5 最小上下文收集、Phase 2 最小澄清、Phase 2.9 commit gate 和 Phase 4 轻量回填必须保留。
-- devflow 记录必须按阶段就近更新；Phase 4 主要做 consolidation，而不是第一次补写 `brief.md`、`evidence.md`、`decisions.md` 或 `acceptance.md`。
+以下 6 条是硬约束，违反即流程失败。其余约束按阶段定义在 `references/phase-contracts.md`。
+
+1. **OpenSpec 是唯一执行真理源**。apply 只能基于 Committed OpenSpec 执行。Draft OpenSpec 是讨论对象，不是执行许可。
+2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
+3. **不得跳过 grill**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。
+4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
+5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
+6. **降级执行必须标注**。fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
+
+每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。
+
+## 用户命令
+
+| 命令 | 用户意图 | 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 + 归档确认 |
+
+用户也可以用自然语言指定从某个阶段继续，例如"ops-message-support 的 grill 已经做完了，继续"。harness 识别意图后，自动补做最小前置检查，然后从指定阶段继续。
 
 ## 首次加载
 
 执行前只读取当前任务需要的 reference 文件：
 
-- 需要逐阶段执行时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。
+- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。
 - 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
-- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
-- 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。
+- archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
+- 子 skill 无法直接调用时，读取 `references/fallbacks.md`。
 
-## 启动检查
+## 内部阶段
 
-按 `references/operating-rules.md` 执行启动检查、项目 slug 规则和 devflow 产物分层。
+9 个内部阶段，按执行顺序：
 
-## 阶段总览
-
-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。
+1. clarify — 入口澄清：接收初始需求，澄清到可生成轻量 proposal。
+2. context — 上下文收集：读取 devflow 的 glossary、ADR、历史项目、compound knowledge。
+3. propose — 轻量 propose：只生成 proposal.md，不调用 openspec-propose。
+4. grill — 人类对齐澄清：evidence-driven 查证 + user-interview one-at-a-time，回写 proposal。
+5. specify — 细化 + 对齐：基于已稳定的 proposal 补全 design/specs/tasks，做 cross-artifact 对齐。
+6. audit — 架构审计：审计结果如果影响实现，回写 OpenSpec design/tasks。
+7. commit — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
+8. apply — OpenSpec 执行：基于 Committed OpenSpec 实现代码。
+9. archive — 回填 + 归档：从 OpenSpec 产物和 decisions.md 提炼长期档案，询问是否归档。
 
 每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
 
@@ -81,4 +82,3 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 ## 完成标准
 
 流程完成标准见 `references/operating-rules.md`。
-