git-learn/skill-workbench/docs/sm-flow/phase-contracts-v4.2-changelog.md

SM Flow Phase Contracts v4.2 更新日志

更新日期: 2026-06-24
更新原因: 基于"lookup-knowledge-integration"执行复盘
更新方案: 增强执行机制，引入可验证 checkpoint

---

更新概览

核心目标: 解决"约束是软性的"问题，增加可执行的检查机制

更新范围:

• ✅ commit 阶段：增加文件完整性和一致性检查清单
• ✅ apply 阶段：增加前置门控（.committed 文件检查）
• ✅ archive 阶段：增加强制执行顺序（5 步 checklist）

文本增量: +80 行

---

核心问题诊断

问题根源：约束是"软性"的，缺少执行机制

问题	现象	影响	根本原因
Commit 检查缺标准	不知道如何判断"通过 commit 检查"	agent 跳过 commit 直接进入 apply	只说"检查是否可执行"，没说具体检查什么
Apply 缺前置门控	用户说"修复"就直接开始实现	可能基于不完整的 OpenSpec	进入条件是软性描述，没有文件检查
Archive 无 Checklist	先创建 handoff，忘记 devflow	归档流程不完整	没有强制执行顺序

---

详细修改

1. Commit 阶段 — 增加可验证 Checkpoint

修改位置: phase-contracts.md 第 208-221 行

新增内容:

文件完整性检查（必须全部通过）

• proposal.md 存在，包含问题描述（至少 50 字）、建议方案（至少 100 字）、范围/非目标
• design.md 存在，包含架构设计（文字或图）、数据结构定义（至少 1 个）、关键决策记录（至少 2 条）
• specs/ 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
• tasks.md 存在，包含 ≥5 个可执行子任务，每个任务有验收标准

一致性检查（必须通过）

• proposal 中的核心概念在 design 中有对应设计
• design 中的关键决策在 tasks 中有对应实现任务
• tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）

标记文件

检查通过后，创建 openspec/changes/{slug}/.committed 文件标记为 Committed OpenSpec

目的:

• 提供明确的"可执行状态"判断标准
• 强制 agent 完成所有检查项
• 通过 .committed 文件提供下游门控依据

---

2. Apply 阶段 — 增加前置门控检查

修改位置: phase-contracts.md 第 233-244 行

新增内容:

前置门控检查（硬约束）

1. 检查 openspec/changes/{slug}/.committed 文件是否存在
2. 如不存在，执行以下流程：
   • 汇报：Draft OpenSpec 未通过 commit 检查
   • 列出缺失的 checkpoint 项（文件完整性、一致性检查）
   • 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）

目的:

• 强制 apply 依赖 Committed OpenSpec
• 阻止基于不完整 OpenSpec 的实现
• 提供补救路径（补做 commit 或显式跳过）

---

3. Archive 阶段 — 增加强制执行顺序

修改位置: archive-rules.md 第 5-41 行

新增章节: Archive 强制执行顺序

Step 1: 创建 devflow 档案（必需）

• 创建 brief.md（从 proposal.md 提取）
• 创建 evidence.md（从 decisions.md 提取）
• 创建 decisions.md（整理为最终版）
• 创建 acceptance.md（记录验证情况）

Step 2: 更新索引（必需）

• 在 devflow/index.md 末尾追加或更新一行

Step 3: 标记 OpenSpec（必需）

• 创建 openspec/changes/{slug}/.archive-ready 文件

Step 4: 向用户汇报（必需）

• 列出创建的 devflow 档案文件路径（验证文件实际存在）
• 汇报验证情况（按类型分类）
• 列出剩余风险
• 询问：是否现在归档 OpenSpec？

Step 5: 用户确认后执行 OpenSpec Archive（可选）

• 调用 openspec-archive-change
• 记录 archive 结果

自检: 在执行 Step 4 前，检查 Step 1-3 是否都完成。

目的:

• 强制 devflow 档案优先（不再先创建 handoff）
• 提供明确的执行顺序，避免遗漏
• 通过 .archive-ready 文件标记完成状态

---

新增门控文件

文件	创建时机	用途
.committed	commit 阶段退出时	apply 阶段前置门控
.archive-ready	archive Step 3	标记归档准备就绪

---

预期效果

量化指标

指标	v4.1	v4.2 目标	改善
Commit 阶段跳过率	高（无明确标准）	0%（有 checklist）	-100%
Apply 基于不完整 OpenSpec	可能发生	0%（门控阻止）	-100%
Archive 遗漏 devflow	可能发生	0%（强制顺序）	-100%

质量提升

Commit 阶段:

• ✅ 明确什么叫"可执行状态"
• ✅ agent 无法跳过检查清单
• ✅ 提供 .committed 文件作为凭证

Apply 阶段:

• ✅ 强制检查 .committed 文件存在
• ✅ 阻止基于不完整 OpenSpec 的实现
• ✅ 提供补救路径

Archive 阶段:

• ✅ 强制 devflow 优先（不再先创建 handoff）
• ✅ 5 步 checklist 避免遗漏
• ✅ 自检机制确保完整性

---

与 v4.1 的关系

版本	核心改进	解决问题
v4.1	Pre-apply Research Checkpoint	apply 阶段前置调研不足，导致返工
v4.2	可验证 Checkpoint + 门控文件	约束是软性的，agent 容易跳过阶段

互补关系:

• v4.1 解决"调研不充分导致返工"
• v4.2 解决"缺少执行机制导致跳过阶段"

---

设计原则

1. 可验证性

Before: "检查 OpenSpec 是否可执行"（模糊）
After: "proposal ≥50字、design ≥1个数据结构、specs ≥3个 requirement"（具体）

2. 门控文件

Before: 软性描述"已通过 commit"
After: 硬性检查 .committed 文件存在

3. 强制顺序

Before: 建议性"应该先 devflow 后 handoff"
After: 5 步 checklist，不得跳过或重排

---

复杂度评估

本次修改复杂度: 低-中等

• 文本增量: +80 行（phase-contracts.md +40 行，archive-rules.md +40 行）
• 概念增加: 2 个门控文件（.committed, .archive-ready）
• 规则增强: 3 个阶段的检查清单

整体复杂度: 高（但更可靠）

• 总行数: ~700 行 → ~780 行（+11%）
• 门控数: 6 个 → 8 个（+commit 文件完整性 + apply 前置门控）
• 强制清单: +3 个（commit 文件完整性、commit 一致性、archive 5 步）

权衡:

• ✅ 收益: 彻底解决"跳过阶段"问题
• ⚠️ 成本: 增加 80 行文本，agent 需检查更多项

---

适用场景

✅ 所有场景（无例外）

v4.2 的改进是执行机制层面的，不涉及业务逻辑：

• 无论 micro/standard/complex，都需要 commit 检查
• 无论需求大小，都需要 apply 前置门控
• 无论项目规模，都需要 archive 强制顺序

快速模式

快速模式可以简化产物（如 tasks 只需 3 个子任务），但不能跳过门控：

• ✅ 仍需 commit 检查（即使 tasks 数量少）
• ✅ 仍需 apply 前置门控
• ✅ 仍需 archive 强制顺序

---

实施验证

验证计划

下次完整执行 sm-flow 时，检查：

1. Commit 阶段:

   • agent 是否执行了文件完整性检查？
   • agent 是否执行了一致性检查？
   • agent 是否创建了 .committed 文件？

2. Apply 阶段:

   • agent 是否检查了 .committed 文件存在？
   • 如不存在，agent 是否汇报并询问用户？

3. Archive 阶段:

   • agent 是否按 5 步顺序执行？
   • agent 是否在 Step 4 前自检了 Step 1-3？
   • agent 是否创建了 .archive-ready 文件？

成功标准

• ✅ 无未经检查的 commit → apply 跳转
• ✅ 无基于不完整 OpenSpec 的实现
• ✅ 无先创建 handoff 后补 devflow 的情况

---

后续演进方向

v5.0 候选特性（观察 3+ 次执行后决定）

如果 v4.2 执行良好，但仍有问题，考虑：

1. 流程状态文件 .sm-flow-state

   • 记录当前阶段、已完成阶段、时间戳
   • 支持断点续做

2. 更多门控文件

   • .context-done（context 阶段完成）
   • .grill-done（grill 阶段完成）
   • .apply-done（apply 阶段完成）

3. 违规自检机制

   • 每个阶段退出前，自动检查是否违反 6 条硬约束

4. 进度可视化

   • 每次开始时，汇报进度条（9 个阶段的完成情况）

判断依据: 如果 v4.2 后仍频繁出现跳过阶段，再引入更重的机制。

---

相关文档

• 执行复盘: skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md
• 修改文件:
  • .agents/skills/sm-flow/references/phase-contracts.md
  • .agents/skills/sm-flow/references/archive-rules.md

---

总结

v4.2 的核心理念: 把"软性约束"变成"硬性检查"

改进点	Before	After
Commit 标准	"可执行状态"（模糊）	文件完整性 + 一致性检查清单
Apply 门控	"已通过 commit"（软性）	检查 .committed 文件存在（硬性）
Archive 顺序	"应该先 devflow"（建议）	5 步强制顺序 + 自检

预期效果: 彻底解决"agent 跳过阶段"问题，提升流程可靠性。