# 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 新工作流

```
旧：                       新：
Phase 1  手动整理PRD        Phase 0   手动初始PRD（入口，保留人的判断）
Phase 2  openspec:explore   Phase 1    openspec:propose → research
Phase 3  grill-me           Phase 1.5  to-prd → 结构化PRD（替代初始PRD）
Phase 4  openspec:apply     Phase 2    grill-with-docs → CONTEXT.md + ADR
                            Phase 2.5  zoom-out → 架构审计
                            Phase 3    openspec:apply → 执行
                                       diagnose → bug排查
                                       tdd → 质量闭环
横切：                     横切：
       无                            git-guardrails → 安全锁
```

关键变化：**手动 PRD 从"整个流程的全部输入"降级为"Phase 0 的启动草稿"**——你仍然需要手写初始 PRD（这是人的判断力不可替代的部分），但它不再直接喂给 openspec apply，而是先经过 research → 精化 → grill → 架构审计，最终执行的是层层校验后的方案。

## 旧工作流的三个关键缺口

1. **需求澄清后缺少可行性验证**
   - 旧：grill-me 追问后 → 直接进入 apply。如果方案有架构问题，到了编码阶段才发现
   - 新：grill-with-docs 追问后 → zoom-out 拉高视角做架构审计。grill 问的是"需求对不对"，zoom-out 问的是"方案行不行"

2. **openspec 产出不能沉淀到长期记忆**
   - 旧：openspec archive 只归档需求，项目的术语、业务规则、架构决策散落在对话中，下次新对话全丢
   - 新：grill-with-docs 的 CONTEXT.md 沉淀领域词汇表，ADR 沉淀架构决策。换会话重启 AI 也不丢失上下文

3. **apply 完成后缺少验证闭环**
   - 旧：apply → 完成。功能对不对取决于人肉测试
   - 新：apply 过程中遇到 bug → diagnose（假说→验证→修复→回归测试），写代码时 → tdd（Red→Green→Refactor）

## 新增技能的投入产出

| 技能 | 接入成本 | 主要收益 | 什么时候用 |
|------|--------|-----------|-----------|
| to-prd | 自动综合 | 结构化需求 | openspec research 结束后 |
| grill-with-docs | 替换已有 grill-me | 产出文档化澄清 | 需求澄清阶段 |
| zoom-out | 低 | 避免方向性返工 | grill 完成后、apply 前 |
| diagnose | 低 | 减少猜测式 bug 修复 | apply 中遇到问题 |
| tdd | 低 | 减少回归 bug | apply 中写代码 |
| git-guardrails | 被动生效 | 防止灾难性操作 | 全程自动 |

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

openspec 管控的是"流程"——先出 proposal，再写 specs，再排 tasks。但它不解决三个问题：

- **领域知识沉淀**：openspec 归档后只剩需求文档，术语表、架构决策全丢了 → grill-with-docs 补齐
- **质量验证**：openspec 把 tasks 勾完就算完成 → diagnose + tdd 补齐验证闭环  
- **流程安全**：openspec 不管 AI 误操作 → git-guardrails 补齐安全层

一句话：**openspec 管"按什么步骤走"，mattpocock 技能管"每一步走得好不好"。**

## v2.0：devflow/ 产物聚合层

### 问题

v1.0 一次完整流程的产物散落在 **5 个位置**：

```
CONTEXT.md                 ← Phase 2 (根目录)
docs/adr/                  ← Phase 2 (docs/)
docs/agents/               ← Phase 1.5 (docs/)
openspec/changes/          ← Phase 1+3 (openspec/)
knowledge/entries/         ← /knowledge-absorber
```

三个月后想回溯"knowledge-index-panel 这个项目到底做了什么决策"，需要同时翻 4 个目录。产物按**工具来源**组织（openspec 写哪、grill 写哪、to-prd 写哪），而非按**项目本身**组织。

### 借鉴 CodeStable 的单一聚合根设计

CodeStable 的核心设计决策：所有产物集中在 `codestable/` 一个目录下，按"软件实体类型"（需求/架构/特性/问题/知识）分子目录，而非按"哪个工具产生的"。

dev-flow v2.0 借鉴这一点，在不改变 openspec 工作区的前提下，增加一个**人类可读的档案层**：

```
devflow/                              ← 单一入口
├── projects/YYYY-MM-DD-{slug}/       ← 一个 PRD→实现 闭环
│   ├── {slug}-prd.md                 # Phase 0+1.5 需求文档
│   ├── {slug}-research.md            # Phase 1 技术方案（从 openspec 提取）
│   ├── {slug}-design.md              # Phase 1+2.5 设计 + 架构审计
│   ├── {slug}-tasks.md               # Phase 1 任务清单（从 openspec 提取）
│   ├── {slug}-acceptance.md          # Phase 3+4 验收报告
│   └── adr/                          # Phase 2 架构决策
├── glossary/
│   └── CONTEXT.md                    # 跨项目领域词汇表
├── compound/                         # 跨项目知识沉淀
│   └── YYYY-MM-DD-{type}-{slug}.md   # type ∈ {learning, trick, decision, explore}
└── reference/                        # 共享模板/规范
```

### 两层架构

| | openspec/changes/ | devflow/projects/ |
|------|-----------|-------------------|
| 角色 | 工具工作区（WAL） | 人类档案层（Tables） |
| 谁读 | 机器 | 人 |
| 生命周期 | 活跃变更期 → Archive 后清空 | 永久保留 |
| 组织方式 | 按变更名 | 按日期 + 项目 |

**关键**：openspec archive 后 `openspec/changes/` 清空，但 `devflow/projects/` 不受影响。Phase 4 收尾时从 openspec 提取关键内容到 devflow。

### 各 Phase 产物路径变化

| Phase | v1.0 | v2.0 |
|-------|------|------|
| 1.5 PRD | `docs/agents/<name>-prd.md` | `devflow/projects/{date}-{slug}/{slug}-prd.md` |
| 2 CONTEXT | 根目录 `CONTEXT.md` | `devflow/glossary/CONTEXT.md` |
| 2 ADR | `docs/adr/` | `devflow/projects/{slug}/adr/` |
| 2.5 架构审计 | 对话中，丢失 | `devflow/projects/{slug}/{slug}-design.md` |
| 4 验收 | `docs/agents/lessons/` | `devflow/projects/{slug}/{slug}-acceptance.md` |
| 4 经验沉淀 | 无 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
| 4 从 openspec 提取 | 无 | 提炼到 `{slug}-research.md` + `{slug}-tasks.md` |

## 一键启动

已固化为 skill：**`/dev-flow`**

```
/dev-flow                     # Phase 0 开始：粘贴初始 PRD 草稿 → 走完后续全流程
/dev-flow --prd docs/my-idea.md  # 跳过 Phase 0，直接用已有 PRD 文件 → Phase 1
/dev-flow --from phase2       # 已有 research，从 grill 开始
/dev-flow --from apply        # 已有 PRD + 文档，直接执行
/dev-flow --quick             # 小需求，跳 PRD 精化 + zoom-out
```

Skill 位置：`.claude/skills/dev-flow/SKILL.md`

## Skill 评估结论（2026-05-19）

详细评估报告见：`devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md`。

### 总体判断

`dev-flow` 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。

最有价值的设计是 `devflow/` 产物聚合层：

- `openspec/changes/` 负责机器可执行的变更工作区。
- `devflow/projects/` 负责人类可回溯的项目档案。
- `devflow/glossary/CONTEXT.md` 负责跨项目领域词汇。
- `devflow/compound/` 负责沉淀可复用工程知识。

评估中发现的核心问题是：早期 `SKILL.md` 更像设计说明书，而不是代理可稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。

### 已确认的亮点

1. **产物聚合层设计清晰**
   - `devflow/projects/YYYY-MM-DD-{slug}/` 解决了 openspec archive 后上下文难以回溯的问题。
   - 工具工作区和人类档案层分离，职责边界明确。

2. **阶段顺序合理**
   - Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。

3. **Phase 4 很有价值**
   - 从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。
   - 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。

4. **文档化追问方向正确**
   - Phase 2 要求一次只问一个问题，并即时更新 `CONTEXT.md` / ADR。
   - 这符合“边澄清边沉淀”的工作方式。

5. **质量闭环意识强**
   - Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。
   - TDD 被设计为可选增强，避免对所有任务强制套用重流程。

### 主要改进点

| 问题 | 改进方向 |
| --- | --- |
| 触发描述不够完整 | 明确覆盖需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程等场景 |
| Claude 工具耦合较强 | 保留 Claude 版本兼容，同时在 skill 正文中提供环境无关 fallback |
| 依赖安装状态写死 | 改为启动时检查 required / optional / fallback |
| 子 skill 调用方式不稳 | 优先调用子 skill；不可调用时读取对应 `SKILL.md`；不存在时执行最小协议 |
| 缺少初始化算法 | 明确 `devflow/` 目录骨架、slug 生成、重名处理和旧 `CONTEXT.md` 迁移规则 |
| 缺少模板 | 拆出 PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 模板 |
| quick 模式与约束冲突 | quick 只能跳 Phase 1.5 和 2.5，不能跳 Phase 2 最小澄清和 Phase 4 轻量归档 |
| Phase 退出条件不足 | 为每个 Phase 增加进入条件、动作、输出、退出条件和失败回退路径 |

### 产品化方向

评估结论不是继续增加理念，而是把 workflow 产品化为“代理稳定执行协议”：

- `SKILL.md` 保持短而硬：角色、触发场景、阶段总览、核心规则、关键分支。
- `references/` 承载长内容：Phase 契约、模板、归档规则、fallback 协议。
- 每个 Phase 都要有明确的进入条件和退出条件。
- quick 模式、fallback、归档确认、人类检查点必须写成硬规则。
- `devflow/` 只做长期记忆和上下文增强，不应与 openspec 抢执行真理源。

### 后续演进：sm-flow 产品化

基于这次评估，`dev-flow` 的设计被重构为 `.agents/skills/sm-flow/`。这一步仍属于 **v2 产品化**：目标不是改变 v2 的“devflow 聚合层”定位，而是把早期设计说明书拆成代理可执行的 skill 结构。

```
.agents/skills/sm-flow/
├── SKILL.md                         # 短执行协议
└── references/
    ├── phase-contracts.md           # Phase 输入/动作/输出/退出条件
    ├── templates.md                 # PRD/ADR/验收等模板
    ├── archive-rules.md             # 从 openspec 提取到 devflow 的规则
    └── fallbacks.md                 # 子 skill 不可用时的最小协议
```

v2 的核心仍然是：在不改变 openspec 工作区的前提下，增加 `devflow/` 作为人类可读档案层，并让 Phase 4 把 openspec、实现、验证结果提炼回长期记忆。

## v3.0：OpenSpec-first / Devflow-assisted

### 背景

v2 跑通后暴露出一个更深的问题：`devflow/` 产物越来越完整，容易让代理在执行阶段直接依赖 PRD、design、tasks、acceptance 等档案写代码，从而弱化 openspec 的执行真理源地位。

这会导致两套“执行依据”并存：

```
devflow/projects/{slug}/...     # 人类档案层，也包含 PRD/design/tasks
openspec/changes/{change}/...    # 工具工作区，也包含 proposal/design/specs/tasks
```

如果没有主从关系，Phase 3 执行时代理可能不知道到底听 devflow tasks，还是听 openspec tasks。文档越多，不一定越准确；没有唯一执行真理源时，反而更容易漂移。

### v3 的核心判断

v3 不重新设计一套替代 openspec 的工作流，而是明确：

> **devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow。**

职责分层变为：

| 层 | 角色 | 负责回答 |
| --- | --- | --- |
| `devflow/` | 上下文真理源 / 长期记忆 | 为什么这样做？术语是什么？历史决策是什么？之前怎么验收？ |
| `openspec/changes/` | 执行真理源 / 当前变更规格 | 这次到底改什么？验收标准是什么？任务是否完成？ |
| code | 实现结果 | OpenSpec apply 后实际落地的代码 |

### v2 vs v3

| 维度 | v2：devflow 聚合层 | v3：OpenSpec-first / Devflow-assisted |
| --- | --- | --- |
| 核心目标 | 防止 openspec archive 后上下文丢失 | 防止 devflow 与 openspec 成为并列执行源 |
| devflow 角色 | 人类可读档案层 | 上下文增强层 + 归档层 |
| openspec 角色 | 工具工作区 | 当前变更的唯一默认执行真理源 |
| Phase 1 | openspec propose 产出 research | 基于 devflow 上下文生成/修正 OpenSpec 产物 |
| Phase 2 | grill-with-docs 更新 glossary/ADR | human-in-the-loop 澄清后必须回写 OpenSpec |
| Phase 2.5 | zoom-out 产出架构审计 | 架构审计若影响实现，必须回写 OpenSpec design/tasks |
| Phase 3 | openspec apply + diagnose/tdd | 默认只能依赖 OpenSpec apply；devflow 只作参考上下文 |
| Phase 4 | 从 openspec 提炼到 devflow | 轻量回填 devflow 必要档案，避免重复 OpenSpec |

### v3.1：Devflow 产物瘦身

v3 继续跑完整流程后，又暴露出一个实践问题：`devflow` 作为辅助和人类阅读层时，如果默认生成 PRD、research、design、tasks、alignment、clarifications、acceptance，会和 OpenSpec 的 proposal、design、specs、tasks 大量重叠。

因此 v3.1 明确：**devflow 不复制 OpenSpec，只保存 OpenSpec 不擅长表达的人类上下文、证据、决策和验收归档。**

默认必要产物收敛为：

```text
devflow/projects/YYYY-MM-DD-{slug}/
├── brief.md        # 背景、目标、范围、非目标、关联 OpenSpec
├── evidence.md     # 代码/文档证据、evidence-driven 结论和汇报状态
├── decisions.md    # user-interview 确认、关键取舍、OpenSpec 回写记录
└── acceptance.md   # 实现结果、验证、未验证项、archive 状态
```

扩展产物只在有明确理由时创建：

- `prd.md`：复杂需求、对外协作或用户明确要求。
- `research.md`：真实调研、代码考古、竞品/API 对比或复杂方案比较。
- `design.md`：长期架构背景、架构审计摘要或决策索引；实现设计仍以 OpenSpec design 为准。
- `tasks.md`：跨轮次人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
- `alignment.md` / `clarifications.md`：冲突或澄清问题很多时拆出；否则并入 `decisions.md`。

规模分档：

| 分档 | 适用场景 | devflow 默认产物 |
| --- | --- | --- |
| `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 |

### v3 新增 Phase 0.5

v3 在 Phase 0 和 Phase 1 之间增加：

```
Phase 0.5  Devflow Context Harvest
```

读取：

- `devflow/glossary/CONTEXT.md`
- 相关项目 PRD/design/tasks/acceptance
- 相关 ADR
- `devflow/compound/` 中的 learning、trick、decision、explore

目的不是直接指导编码，而是给 Phase 1 的 OpenSpec propose 提供更准确的上下文输入。读取旧项目时可以参考历史 PRD/design/tasks，但新项目不再默认生成这些重复产物。


### v3 中各 skill 的参与方式

这些 skill 仍然参与，但职责从“并列执行流程”调整为“服务 OpenSpec 产物质量”：

| 阶段 | 主要 skill / 工具 | 作用 | 产物去向 |
| --- | --- | --- | --- |
| Phase 0 初始需求 / PRD / research | `sm-flow` | 收集原始需求、已有 PRD 或 research，判断启动模式 | 入口摘要、初步 slug |
| Phase 0.5 Devflow Context Harvest | `sm-flow` | 读取 `devflow/` 的 glossary、ADR、历史 PRD、acceptance、compound knowledge | 作为 Phase 1 的 OpenSpec 输入上下文 |
| Phase 1 OpenSpec propose | `openspec-propose` | 生成或修正 `proposal.md`、`design.md`、`specs/**/*.md`、`tasks.md` | `openspec/changes/<change>/` |
| Phase 1.5 PRD / OpenSpec 对齐 | `to-prd` + `sm-flow` | 检查 brief/devflow/OpenSpec 是否一致；复杂需求才生成独立 PRD | `brief.md` / 按需 `prd.md`；冲突回写 OpenSpec |
| Phase 2 Human-in-the-loop 澄清 | `grill-with-docs` | 追问术语、边界、验收；区分 `evidence-driven` 和 `user-interview` | `evidence.md` / `decisions.md`；影响实现的结论回写 OpenSpec |
| Phase 2.5 架构审计 | `zoom-out` | 拉高视角审查模块、数据流、耦合、架构风险 | 默认写入 decisions/evidence；复杂审计才拆 `design.md`；影响实现则回写 OpenSpec |
| Phase 3 OpenSpec apply | `openspec-apply-change` | 按 OpenSpec specs/tasks 执行实现 | 代码变更、OpenSpec task 状态 |
| Phase 3 bug/不确定行为 | `diagnose` | 复现 → 最小化 → 假设排序 → 仪器化 → 修复 → 回归 | 根因若是规格问题，先修 OpenSpec；修复记录进入 acceptance |
| Phase 3 高风险/复杂行为 | `tdd` | 按 OpenSpec specs 做纵向切片测试驱动 | 测试与实现代码 |
| Phase 4 回填 devflow | `sm-flow` + `openspec-archive-change` | 从 OpenSpec、实现和验证提炼长期档案，并询问是否 archive | `devflow/projects/`、`devflow/compound/`；用户确认后 archive |

说明：`grill-me` 在 v3 中不再作为主要入口，已被 `grill-with-docs` 替代。原因是 v3 需要把澄清结果沉淀到 glossary/ADR，并把影响实现的结论回写 OpenSpec；纯对话式 grill 容易丢失上下文。

### v3 的执行规则

1. **OpenSpec 是执行真理源**
   - Phase 3 默认必须依赖 `openspec/changes/<change>/proposal.md`、`design.md`、`specs/**/*.md`、`tasks.md`。
   - 不允许直接基于 `devflow/projects/...` 绕过 OpenSpec 写代码。

2. **Devflow 是上下文真理源**
   - 术语、历史决策、项目背景、踩坑记录来自 `devflow/`。
   - 这些内容用于增强和修正 OpenSpec，而不是替代 OpenSpec。

3. **冲突先修 OpenSpec**
   - 如果 devflow 和 OpenSpec 冲突，不能直接执行。
   - 必须汇报冲突、让用户确认、更新 OpenSpec，再进入 apply。

4. **evidence-driven 也必须汇报**
   - 证据驱动不是“AI 自己确认完就继续”。
   - 代理必须汇报查了什么、得出什么结论、是否需要用户确认。

5. **user-interview 必须等待确认**
   - 涉及范围、偏好、验收口径、风险接受度时，必须问用户。

6. **归档仍回到 devflow**
   - OpenSpec 完成后，从 OpenSpec、实现结果、验证结果中提炼长期档案。
   - Phase 4 询问是否 archive OpenSpec change，不默认执行。

7. **devflow 产物按需生成**
   - 默认只生成 brief、evidence、decisions、acceptance。
   - PRD、research、design、tasks、alignment、clarifications 只有在复杂度或协作需要时才生成。
   - 小需求走 `micro`，不能让文档成本超过实现成本。

### v3 流程图

```
Phase 0    初始需求 / PRD / research
           skill: sm-flow
   ↓
Phase 0.5  读取 devflow 上下文
           skill: sm-flow
   ↓
Phase 1    生成或修正 OpenSpec proposal/design/specs/tasks
           skill: openspec-propose
   ↓
Phase 1.5  PRD / Devflow / OpenSpec 对齐检查
           skill: to-prd + sm-flow
   ↓
Phase 2    human-in-the-loop 澄清，并回写 OpenSpec
           skill: grill-with-docs
   ↓
Phase 2.5  架构审计；影响实现则回写 OpenSpec
           skill: zoom-out
   ↓
Phase 3    OpenSpec apply 执行
           skill: openspec-apply-change；按需 diagnose / tdd
   ↓
Phase 4    回填 devflow，并确认是否 archive
           skill: sm-flow；用户确认后 openspec-archive-change
```

### v3 一句话定位

`sm-flow` 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。

## v3.1：可执行 gate 与使用摩擦修正

v3.1 来自一次真实使用复盘：接口变更文档粒度、propose 后再 grill 的返工感、devflow 增长后的检索成本、子 skill 路径兼容，以及 Phase 3 中用户质疑和代码发现与原设计冲突时的处理方式，都需要变成可执行规则。

v3.1 不改变 v3 的主轴：

> `devflow/` 提供上下文，OpenSpec 提供执行依据，代码只是实现结果。

### Draft / Committed OpenSpec

Phase 1 产出的 OpenSpec 统一视为 **Draft OpenSpec**。它是后续 PRD 对齐、grill 和架构审计的讨论对象，不是实现许可。

Phase 2 和 Phase 2.5 的结论必须回写 OpenSpec。随后新增 Phase 2.9：

```text
Phase 2.9 Commit OpenSpec
```

Phase 2.9 检查：

- proposal 是否说明范围、非目标和原因。
- design 是否记录关键约束、架构风险和接口影响。
- specs 是否覆盖可观察行为和验收口径。
- tasks 是否是可执行的纵向切片。
- 是否还有未确认的 user-interview、未汇报的 evidence-driven 结论、未判级接口影响或 devflow/OpenSpec 冲突。

只有通过 Phase 2.9 的 OpenSpec 才是 **Committed OpenSpec**，Phase 3 只能执行 Committed OpenSpec。

### Grill 必须人工确认

Phase 2 的 `grill-with-docs` 不是代理自问自答。`user-interview` 问题必须一次只问一个，等待用户显式回答，并记录到 `decisions.md`。未获得用户确认的问题不能视为已解决，也不能进入 Phase 2.9 或 Phase 3。

`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 区分“接口影响记录”和“独立接口文档”：

- 所有接口变更都必须记录影响范围。
- 只有 L3/L4 才强制独立接口文档或等价独立章节。

分级规则：

| 级别 | 判断条件 | 产物要求 |
| --- | --- | --- |
| L1 内部实现 | 不改变调用方可观察行为 | tasks / acceptance 记录验证 |
| L2 内部接口 | 内部 DTO、service 方法、内部事件、内部判断逻辑变化，消费者仍在同一实现范围内 | 内联接口影响记录 |
| L3 协作接口 | 影响前端、其他模块/服务、跨团队消费者、数据库契约、事件、回调或 SDK | 独立接口文档或独立章节 |
| L4 破坏性接口 | 旧调用方可能失败、数据/状态/错误码不同，或需要迁移/灰度/回滚 | 独立接口文档 + 迁移/回滚说明，必要时 ADR |

接口内部判断逻辑也按可观察行为评估。即使签名和字段不变，只要返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用变化，也属于接口影响。

### Devflow Index

`devflow/index.md` 成为 Phase 0.5 的默认入口。上下文查找顺序为：

```text
devflow/index.md
devflow/glossary/CONTEXT.md
相关项目 brief / acceptance / ADR
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 冲突，必须先分类：

| 分类 | 含义 | 处理 |
| --- | --- | --- |
| 实现偏差 | OpenSpec 正确，代码没有按规格做 | 修代码，不改 OpenSpec |
| 规格遗漏 | OpenSpec 没覆盖真实边界、接口影响、验收或外部行为 | 暂停 apply，修正 OpenSpec，重新 commit |
| 设计冲突 | OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突 | 暂停并请用户确认设计方向 |
| 用户变更 | 用户改变目标、范围、验收或风险接受度 | 更新 proposal/specs/tasks 后继续 |

冲突分类、证据、用户确认和 OpenSpec 回写状态必须进入 `decisions.md` 或 `acceptance.md`。

### 子 skill 兼容

v3.1 将子 skill 从“路径绑定”改为“能力绑定”。例如 `openspec-propose`、`openspec-apply-change`、`to-prd`、`grill-with-docs` 都是能力契约。

调用优先级：

1. 平台原生 skill。
2. 本地 `SKILL.md`，例如 `.claude/skills/...` 或 `.agents/skills/...`。
3. `sm-flow` 的 fallback 协议。

这样 `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/`