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:
@@ -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 结论或未接受架构风险。
|
||||
|
||||
Reference in New Issue
Block a user