Files

T

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

2026-06-24 14:51:45 +08:00

6.8 KiB

Raw Blame History

归档规则

archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转化为持久、可读、可复用的项目记忆。sm-flow 在 clarify → apply 期间只维护 decisions.md 作为过程日志，archive 阶段从中提取完整 devflow 档案。

Archive 强制执行顺序

Archive 阶段必须按以下顺序执行，不得跳过或重排：

Step 1: 创建 devflow 档案（必需）

创建 devflow/projects/YYYY-MM-DD-{slug}/brief.md （从 proposal.md 提取：背景、目标、范围、非目标）
创建 devflow/projects/YYYY-MM-DD-{slug}/evidence.md （从 decisions.md 提取：evidence-driven 记录）
创建 devflow/projects/YYYY-MM-DD-{slug}/decisions.md （整理为最终版：关键决策、权衡、风险）
创建 devflow/projects/YYYY-MM-DD-{slug}/acceptance.md （记录：静态验证、脚本验证、浏览器/人工验证、未验证）

Step 2: 更新索引（必需）

在 devflow/index.md 末尾追加或更新一行： | YYYY-MM-DD | slug | 领域 | 关键词 | openspec/changes/xxx | archived |

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/projects/YYYY-MM-DD-{slug}/

archive 阶段创建以下文件：

brief.md：从 proposal.md 提取背景、目标、范围、非目标。
evidence.md：从 decisions.md 中的 evidence-driven 记录提取。
decisions.md：保持为最终版，整理格式。
acceptance.md：从实现结果和验证结果提取。

同时维护仓库级索引：

devflow/index.md

按需创建以下扩展文件：

prd.md
research.md
design.md
tasks.md
alignment.md
adr/*.md

不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。

产物分档

分档	适用场景	必须文件	扩展文件
`micro`	小改动、低风险、需求明确	`brief.md`、`decisions.md`、`acceptance.md`	证据少时并入 `brief.md`
`standard`	默认模式	`brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`	按需 ADR/compound
`complex`	高风险、跨模块、需求不清、多人协作	standard 全部文件	按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`

提取映射

来源	提取内容	写入位置
`decisions.md`（过程日志）	question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍	`decisions.md`（整理格式为最终版）
`decisions.md`（过程日志）	evidence-driven 结论、代码/文档证据	`evidence.md`
`proposal.md`	为什么做、做什么、范围、非目标	`brief.md`
`design.md`	技术方案、关键决策、风险；只提炼长期有用内容	`evidence.md` / 按需 `design.md`
`specs/*/.md`	requirement 标题和 scenario 意图	`brief.md` 或 `acceptance.md` 的验收追踪
`tasks.md`	checkbox 状态、剩余工作、执行切片	`acceptance.md`；复杂项目可拆 `tasks.md`
测试/构建输出	验证命令、结果、验证类型	`acceptance.md`
diagnose 记录	根因、修复、回归验证	`acceptance.md`
词汇表更新	术语和业务规则	`devflow/glossary/CONTEXT.md`
可复用经验	持久工程知识	`devflow/compound/YYYY-MM-DD-{type}-{slug}.md`
项目索引	日期、slug、领域、关键词、关联 OpenSpec、状态	`devflow/index.md`

索引维护规则

devflow/index.md 是 context 阶段的默认入口，archive 阶段回填时必须维护。

最小字段：

日期	slug	领域	关键词	关联 OpenSpec	状态

规则：

每个 devflow/projects/YYYY-MM-DD-{slug}/ 默认对应一行索引。
archive 阶段新建或更新项目档案时，必须新增或更新对应行。
如果项目仍在进行，状态写 active；已验收但未 archive 写 accepted-unarchived；已 archive 写 archived；暂停写 paused。
关键词只放能帮助 context 阶段定位的术语，不复制 brief 内容。
如果无法准确判断领域或状态，写 unknown，并在 acceptance.md 记录待补。

验收记录规则

必须真实记录验证情况，并按类型分类：

静态验证：语法检查、grep/rg 检查、结构检查、类型检查等不运行完整功能的验证。
脚本验证：生成脚本、测试命令、构建命令、自动化检查等可重复命令。
浏览器/人工验证：需要用户或代理在界面中点击、观察、确认的行为验证。
未验证：未运行的验证必须记录原因、风险和建议补验步骤。

记录要求：

如果验证通过，记录命令/步骤和覆盖范围。
如果验证失败，记录失败摘要和是否阻塞验收。
如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。

ADR 规则

同时满足以下条件时创建 ADR：

决策难以逆转。
缺少上下文会让未来维护者困惑。
决策来自真实权衡，而不是简单偏好。

项目内 ADR 存放于：

devflow/projects/YYYY-MM-DD-{slug}/adr/

跨项目可复用决策或经验存放于：

devflow/compound/YYYY-MM-DD-decision-{slug}.md

归档确认

OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息：

archive 阶段可以建议 archive，但必须先询问用户。
在用户确认前，不要执行 archive。
如果用户暂不归档，在 acceptance 中记录原因或状态。
如果用户确认归档，执行后记录 archive 结果和剩余档案位置。

归档交接

archive 阶段结束时告诉用户：

创建或更新了哪些档案文件。
devflow/index.md 是否已更新。
运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
还剩哪些风险或后续事项。
明确询问：是否现在 archive OpenSpec change？

6.8 KiB Raw Blame History Unescape Escape