osiman/git-learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c9a6777340ca79fbabc054c4712c8dc409cc5e3c
git-learn/skill-workbench/docs/sm-flow/workflow.md
T
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

1118 lines
53 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 新工作流
```
旧： 新：
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 | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 |
| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 |
| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 |
| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 |
| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 |
| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 |
## 为什么这套组合优于单纯依赖 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 阶段开始前增加 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 实现过程增强
**分步实现**：建议按 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% |
| 实现时间（含返工） | 2 小时 | 1.5 小时 | -25% |
| 前置调研时间 | 0 分钟 | 15-20 分钟 | +20 分钟 |
**ROI 分析**：
```
投入：15-20 分钟调研
回报：节省 60 分钟返工 + 避免核心功能遗漏
ROI = (60 - 20) / 20 = 200%
```
### 复杂度评估
**本次修改复杂度**：中等
- 文本增量：+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 分档的简单需求（可缩短为 5-10 分钟）
- 纯数据处理或工具脚本（技术栈熟悉）
❌ **不推荐**：
- 紧急热修复（时间紧急）
- 一次性脚本（不涉及项目标准）
### 相关文档
- 执行复盘：`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，或明确跳过（需显式确认）
#### 修改 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`
Reference in New Issue View Git Blame Copy Permalink