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
2026-06-24 14:51:45 +08:00
parent b94ee31cb1
commit c9a6777340
5 changed files with 1032 additions and 1 deletions
@@ -207,7 +207,16 @@
**退出条件**:
- Draft OpenSpec 已达到可执行状态,并记录为 Committed OpenSpec。
- apply 所需的 proposal、design、specs 和 tasks 均存在且一致;commit checkpoint 必须验证文件实际存在于磁盘,如果任一文件不存在,commit 失败,返回 specify 补写。
- **文件完整性检查**(必须全部通过):
- [ ] `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
- 所有 preflight 风险已消除或明确记录为已接受。
**输出**:
@@ -223,6 +232,12 @@
**进入条件**:
- `openspec/changes/{slug}/` 中 proposal/design/specs/tasks 已通过 commit,成为 Committed OpenSpec。
- **前置门控检查**(硬约束):
- 检查 `openspec/changes/{slug}/.committed` 文件是否存在
- 如不存在,执行以下流程:
1. 汇报:Draft OpenSpec 未通过 commit 检查
2. 列出缺失的 checkpoint 项(文件完整性、一致性检查)
3. 询问用户:是否补做 commit 检查,或明确跳过(需显式确认)
- commit 后已获得用户明确的 apply 授权,除非用户在启动时要求"全自动执行"。
- devflow 与 OpenSpec 没有未解决冲突。
- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。