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 跳过阶段"问题，提升流程可靠性。