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
zhuyongxin
c9a6777340