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
This commit is contained in:
zhuyongxin
@@ -953,3 +953,165 @@ ROI = (60 - 20) / 20 = 200%
|
||||
- 执行复盘：`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
Block a user