harden and streamline sm-flow protocol

2026-05-25 11:44:20 +08:00
parent 54741dd6c0
commit 1f01e30c4e
20 changed files with 1102 additions and 88 deletions
@@ -9,3 +9,4 @@
 | 2026-05-19 | add-year-filter | knowledge-index | year-filter, index-panel, frontmatter | `openspec/changes/add-year-filter/` | active |
 | 2026-05-19 | dev-flow-skill-evaluation | sm-flow | dev-flow, sm-flow, skill-evaluation, fallback, phase-contracts | 未关联 | accepted-unarchived |
 | 2026-05-21 | sm-flow-v3-1-upgrade | sm-flow | interface-impact, commit-gate, devflow-index, apply-conflict, skill-compatibility | `openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/` | archived |
+| 2026-05-22 | sm-flow-execution-hardening | sm-flow | execution-hardening, checklist, phase-gate, cross-artifact, question-pool | 未关联 | active |
@@ -0,0 +1,40 @@
+# SM Flow Execution Hardening Acceptance
+
+## Result
+
+Implemented `sm-flow-execution-hardening` as protocol/document changes only.
+
+Updated artifacts:
+
+- `.agents/skills/sm-flow/SKILL.md`
+- `.agents/skills/sm-flow/references/phase-contracts.md`
+- `.agents/skills/sm-flow/references/fallbacks.md`
+- `skill-workbench/docs/sm-flow/workflow.md`
+- `openspec/changes/sm-flow-execution-hardening/tasks.md`
+
+## Verification
+
+- Static verification:
+  - Confirmed explicit phase checkpoint and stage-completion rules exist in `SKILL.md`.
+  - Confirmed Phase 2 question-pool behavior and Phase 1.5 / 2.9 cross-artifact checks exist in `phase-contracts.md`.
+  - Confirmed fallback declaration and recording requirements exist in `fallbacks.md`.
+  - Confirmed `workflow.md` explains the same execution-hardening model without introducing mandatory output templates.
+- OpenSpec verification:
+  - Implementation/documentation tasks `1.1` to `3.2` are complete.
+  - Validation tasks `4.1` to `4.4` are complete.
+
+## Acceptance Scope Check
+
+- Satisfied by protocol/document changes alone: yes
+- Requires standardized phase-report output format: no
+- Requires fixed checkpoint/alignment templates: no
+
+## Unverified
+
+- OpenSpec CLI validation passed: `openspec validate sm-flow-execution-hardening`.
+- No automated tests were needed because this change only modifies protocol and documentation artifacts.
+
+## Archive Status
+
+- OpenSpec change is not archived.
+- User still needs to be asked whether to archive after validation is complete.
@@ -0,0 +1,31 @@
+# SM Flow Execution Hardening Brief
+
+## 背景
+
+- 用户目标：把 `sm-flow` 在真实项目执行中暴露出的流程失真问题，提炼为下一轮协议硬化需求。
+- 当前问题：`sm-flow` 已经具备完整阶段规则，但实际执行时仍会出现跳过检查点、弱化显式声明、问题池不足、Cross-artifact 一致性检查不充分等情况。
+- 关联 OpenSpec：`openspec/changes/sm-flow-execution-hardening/`
+- devflow 分档：complex
+
+## 范围
+
+- 本次要做：把复盘中的执行问题整理为结构化需求，明确目标、非目标、用户故事、验收口径和建议改进方向。
+- 本次不做：立即修改 `sm-flow` 协议、直接创建 OpenSpec change、重写 `sm-flow` 主设计。
+- 影响区域：
+  - `.agents/skills/sm-flow/SKILL.md`
+  - `.agents/skills/sm-flow/references/phase-contracts.md`
+  - `.agents/skills/sm-flow/references/fallbacks.md`
+  - `.agents/skills/sm-flow/references/templates.md`
+  - `skill-workbench/docs/sm-flow/workflow.md`
+  - `skill-workbench/docs/sm-flow/retrospective.md`
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖
+- specs 覆盖状态：已覆盖
+- tasks 覆盖状态：已覆盖
+
+## 入口摘要
+
+- 这次需求关注的不是 `sm-flow` 的理念是否成立，而是它在真实执行中为什么仍然会“按代码习惯行动”，而不是“按 phase gate 行动”。
+- 目标是把这些问题固化为更强的执行约束，让后续代理在 `micro` 或 `standard` 模式下也不再轻易跳过关键阶段。
@@ -0,0 +1,76 @@
+# SM Flow Execution Hardening Decisions
+
+## User-interview
+
+| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
+| --- | --- | --- | --- |
+| 这次是否将复盘问题提炼为正式需求？ | “[$sm-flow] 提炼成需求” | 创建 `sm-flow-execution-hardening` 需求档案，先收敛需求，再决定是否进入 OpenSpec。 | 不影响 |
+| 是否必须产出固定 checkpoint / alignment 模板？ | “确认 1” | 不强制固定模板；协议只要求必填字段和检查动作。 | 已回写 |
+| 验收是否要求统一阶段汇报格式？ | “确认1” | 验收停在协议明确 gate、问题池和对齐规则，不要求统一阶段汇报格式。 | 已回写 |
+
+## Phase 2 Tracking
+
+| 问题池项 | 模式 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| Q1：是否必须产出固定 checkpoint / alignment 模板 | user-interview | 待确认 | 会影响 templates.md 与 tasks 范围 |
+| Q2：协议主术语采用 checkpoint 还是 checklist | evidence-driven | 待整理 | 优先由现有文档术语一致性决定 |
+| Q3：验收是否要求统一阶段汇报格式 | user-interview | 已确认 | 验收停在规则层，不扩到统一输出格式 |
+| Q4：workflow 是否需要保留复盘案例示例 | evidence-driven | 待整理 | 主要影响 workflow 文档粒度 |
+
+## Phase 2.5 审计结论
+
+- 决策：主术语采用 `checkpoint`，`checklist` 作为内部核对动作描述。
+  - 原因：仓库现有 `phase-contracts.md` 已使用 `Human checkpoint`，继续沿用能减少术语漂移。
+  - 影响：后续协议修改应优先写“phase checkpoint”，避免在规则层混用主术语。
+  - 风险接受：当前接受
+
+- 决策：`workflow.md` 不扩成案例手册，继续保留规则抽象和演进说明；具体复盘案例留在 `retrospective.md`。
+  - 原因：如果把案例并入 workflow，规则与示例会双份维护，后续更容易漂移。
+  - 影响：执行真理源继续留在 `SKILL.md` / `phase-contracts.md` / OpenSpec，而不是 workflow 长文。
+  - 风险接受：当前接受
+
+## Phase 2.9 Commit Result
+
+- 决策：`sm-flow-execution-hardening` 当前 Draft OpenSpec 通过 commit gate，视为 Committed OpenSpec。
+  - 原因：proposal、design、specs、tasks 已完整；user-interview 已确认；evidence-driven 结论已汇报；未发现 devflow/OpenSpec 冲突。
+  - 影响：可以进入 Phase 3 修改协议文件，但仍需单独的 apply 授权。
+  - 风险接受：当前接受
+
+## 关键取舍
+
+- 决策：将本轮定位为 `complex` 分档。
+  - 原因：虽然不涉及业务代码，但它影响 `sm-flow` 的多个核心文件、阶段协议和验收方式，且包含多处跨文档一致性约束。
+  - 影响：使用 `brief.md`、`prd.md`、`evidence.md`、`decisions.md` 四类产物，而不是只写简短 brief。
+  - 风险接受：当前接受
+
+- 决策：不复用 `sm-flow-v3-1-upgrade` 项目，而是新开需求档案。
+  - 原因：`v3.1` 已归档且目标不同；本轮关注的是执行稳定性，不宜混入已完成升级项目。
+  - 影响：后续若进入 OpenSpec，可独立创建新 change。
+  - 风险接受：当前接受
+
+- 决策：将“规则存在但执行不稳”定义为首要问题。
+  - 原因：复盘中的多个现象都能收敛到这一点，能避免后续需求继续发散。
+  - 影响：后续需求改造应优先考虑 checklist、阶段 gate、显式声明和一致性检查。
+  - 风险接受：当前接受
+
+## Phase 3 Implementation Record
+
+- 决策：Phase 3 以本地 `openspec-apply-change` `SKILL.md` 作为 capability 来源继续执行。
+  - 原因：当前环境可读取对应 skill 协议，且用户已通过“apply”明确授权进入 Phase 3。
+  - 影响：本轮实现按 committed OpenSpec 的 task 切片直接修改协议与工作流文档。
+  - 风险接受：当前接受
+
+- 决策：本轮不修改 `templates.md`。
+  - 原因：用户已确认不要求固定 checkpoint / alignment 模板，也不要求统一阶段汇报格式；OpenSpec task 2.4 的目标是保持模板可选。
+  - 影响：实现集中在 `SKILL.md`、`phase-contracts.md`、`fallbacks.md`、`workflow.md`，避免把协议硬化扩大成模板标准化。
+  - 风险接受：当前接受
+
+- 决策：把“checkpoint 缺失则阶段不算完成”写入顶层协议和阶段契约，而不是只放在说明文档。
+  - 原因：这是决定阶段能否前进的硬 gate，必须落在执行真理源。
+  - 影响：Phase 0、0.5、1、2、2.5、2.9 现在都需要显式 checkpoint 和 capability 声明。
+  - 风险接受：当前接受
+
+- 决策：将 Phase 2 question pool、Phase 1.5/2.9 cross-artifact 对齐、`micro` gate 保留和 fallback 记录要求同步落在协议正文与 workflow 说明。
+  - 原因：这些规则既要可执行，又要便于人类理解；单独放在一处容易再次漂移。
+  - 影响：OpenSpec、协议正文和 workflow 解释层的关键术语已收敛到同一套执行规则。
+  - 风险接受：当前接受
@@ -0,0 +1,106 @@
+# SM Flow Execution Hardening Evidence
+
+## 证据
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| `skill-workbench/docs/sm-flow/retrospective.md` | 逐 Phase 复盘了一次真实执行，明确记录了 Phase 0、0.5、1.5、2、2.5、2.9、4 的实际偏差。 | 当前主要问题是执行偏差和自检不足，不是流程理念方向错误。 | 是 |
+| `skill-workbench/docs/sm-flow/workflow.md` | v3.1 已经补入 Draft/Committed OpenSpec、接口影响分级、Phase 2.9、Phase 3 冲突分类等规则。 | 新一轮需求不应继续扩展原则，而应硬化执行协议。 | 是 |
+| `.agents/skills/sm-flow/SKILL.md` | 已明确 Phase 0.5、2、2.9 不可跳过，且要求显式 skill/fallback 声明。 | 当前缺口在于代理执行时没有被强制逐项核对这些规则。 | 是 |
+| `.agents/skills/sm-flow/references/phase-contracts.md` | 每个 Phase 已有进入条件、动作、退出条件和 checkpoint。 | 还缺一个更短、更高频的执行时 checklist 机制。 | 是 |
+| `.agents/skills/grill-with-docs/SKILL.md` | 明确要求 one-at-a-time 提问，并在可探索时优先查代码。 | Phase 2 的问题不是缺规则，而是没有把“问题池 + 单题推进”落成稳定动作。 | 是 |
+| `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 `SKILL.md` 更像设计说明书，缺少执行时检查点。 | 本轮需求与历史评估一致，属于同一产品化方向的继续深化。 | 是 |
+| `openspec/changes/sm-flow-execution-hardening/proposal.md` | Draft proposal 已将变更范围收敛到 phase checkpoint、问题池、cross-artifact alignment、micro gate preservation。 | Phase 1.5 已完成大方向对齐，未决问题主要落在“是否要求固定记录格式”这一类实现边界。 | 是 |
+| `openspec/changes/sm-flow-execution-hardening/design.md` | Draft design 已明确 checkpoint、问题池、cross-artifact 检查链路和 devflow 过程内同步更新。 | Phase 2 需要确认的重点不再是方向，而是边界和验收粒度。 | 是 |
+
+## Evidence-driven 结论
+
+- 结论：`sm-flow` 当前最需要的是“执行硬化”，不是“设计重构”。
+  - 证据：v3.1 已经把主从关系、gate 和冲突分类写清楚，但真实执行仍偏离。
+  - 风险：如果继续增加理念说明，可能让文档更长，但不提升执行稳定性。
+  - 用户确认：不需要
+
+- 结论：Phase 1.5 和 2.9 的 cross-artifact 检查应成为优先增强点。
+  - 证据：复盘里 `proposal` 漏字段未被代理提前发现，直到用户 review 才暴露。
+  - 风险：如果这两层不稳，Phase 2 即使问得更全，问题仍会漏到 apply 前后。
+  - 用户确认：不需要
+
+- 结论：`micro` 模式的误用是本次偏差的重要诱因。
+  - 证据：复盘根因明确指出“高估了小改动判断，误以为 micro 可以跳检查”。
+  - 风险：若不把这点写得更硬，后续类似问题会重复出现。
+  - 用户确认：不需要
+
+## Phase 1.5 对齐检查
+
+- `brief/prd` -> `proposal`：已对齐
+  - 覆盖了执行硬化而非主设计重构、影响文件范围、非目标边界。
+- `proposal` -> `design`：已对齐
+  - 设计已展开 checkpoint、问题池、cross-artifact alignment、micro gate preservation 和 devflow 过程内更新。
+- `design` -> `specs`：已对齐
+  - 已拆出 `sm-flow-phase-checkpoints`、`sm-flow-question-pool`、`sm-flow-cross-artifact-alignment`、`sm-flow-micro-gate-preservation` 四个 capability spec。
+- `specs` -> `tasks`：部分对齐，仍有一个边界待确认
+  - 当前 tasks 写了“如有需要则更新模板”，但是否必须定义固定记录格式，尚未明确。
+- `specs` -> `tasks`：现已对齐
+  - 用户已确认这轮不强制固定模板，也不把统一阶段汇报格式纳入验收，因此 tasks 保持“协议强化优先，模板仅按需微调”。
+
+## Phase 2 Question Pool
+
+- Q1 `user-interview` / 范围：
+  - 这次 change 是否必须产出固定的 checkpoint / alignment 记录模板，还是只要求协议定义必填字段即可。
+  - 状态：已确认为后者。
+- Q2 `evidence-driven` / 术语：
+  - `phase checkpoint`、`phase checklist`、`stage-completion rule` 三个说法里，哪个作为协议中的主术语最稳。
+- Q3 `user-interview` / 验收：
+  - 验收是以“文档明确要求这些门禁”为准，还是要进一步要求代理输出统一格式的阶段汇报。
+  - 状态：已确认采用前者。
+- Q4 `evidence-driven` / 边界：
+  - 这次是否需要把 retrospective 中的具体案例映射到 workflow 文档中的示例，还是只保留规则层抽象。
+
+## Phase 2.5 架构审计
+
+- 输入 -> 处理 -> 输出链路
+  - `retrospective.md` / 现有 `sm-flow` 协议 / 已归档 OpenSpec change
+  - -> `SKILL.md` 核心规则、`phase-contracts.md` 阶段契约、`fallbacks.md` 降级协议、按需 `templates.md`
+  - -> `workflow.md` 设计说明、`devflow` 过程记录、最终可提交的 OpenSpec
+
+- 模块职责
+  - `.agents/skills/sm-flow/SKILL.md`：放短而硬的总规则、gate 和主从关系。
+  - `.agents/skills/sm-flow/references/phase-contracts.md`：放逐阶段的进入/动作/退出条件与 checkpoint。
+  - `.agents/skills/sm-flow/references/fallbacks.md`：放 capability 不可用时的降级协议和记录要求。
+  - `.agents/skills/sm-flow/references/templates.md`：只放稳定模板，不承载这轮的主逻辑。
+  - `skill-workbench/docs/sm-flow/workflow.md`：保留设计说明和演进脉络，不承载执行真理源。
+
+- 架构风险评估
+  - 当前最大风险不是规则缺失，而是把同一条规则分散到 `SKILL.md`、`phase-contracts.md`、`workflow.md` 后出现漂移。
+  - 这轮 change 如果把“checkpoint”同时做成规则、模板和示例，容易再次扩大维护面。
+  - 更稳的做法是让 `SKILL.md` 和 `phase-contracts.md` 成为主落点，`workflow.md` 只解释，不重复列执行细则。
+  - `templates.md` 应保持可选和轻量，否则会把“协议硬化”扩成“输出格式标准化”。
+- 审计结论与当前 Draft OpenSpec 一致，不需要新增 capability，只需要在实现时严格控制规则落点。
+
+## Phase 2.9 Commit Gate
+
+- proposal：通过
+  - 已覆盖变更原因、范围、非目标、关键边界，以及“不强制固定模板 / 不要求统一阶段汇报格式”的范围约束。
+- design：通过
+  - 已覆盖 checkpoint、问题池、cross-artifact alignment、micro gate preservation、devflow 过程内更新和规则落点分层。
+- specs：通过
+  - 已覆盖四个新增 capability，且行为描述集中在可观察的协议要求。
+- tasks：通过
+  - 已覆盖协议修改、workflow 更新、校验和验收边界验证。
+- user-interview：通过
+  - 两个需要用户确认的问题均已确认并回写。
+- evidence-driven：通过
+  - 术语与 workflow 粒度问题已通过现有文档证据收束。
+- devflow / OpenSpec 冲突：未发现
+
+结论：当前 Draft OpenSpec 已达到可执行状态，可视为 Committed OpenSpec，进入 Phase 3 前仅缺明确 apply 授权。
+
+## Phase 3 Apply Evidence
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| `.agents/skills/sm-flow/SKILL.md` | 已新增显式 checkpoint 完成规则、question pool 规则、cross-artifact 对齐规则、`micro` gate 保留规则和 devflow 分阶段更新规则。 | 顶层协议已把执行硬化从“建议”提升为阶段完成条件。 | 是 |
+| `.agents/skills/sm-flow/references/phase-contracts.md` | 已新增 Phase 1.5 对齐链检查、Phase 2 问题池建立、Phase 2.9 闭环复核、Phase 3 capability 启动汇报和 Phase 4 consolidation 约束。 | 逐阶段执行契约已经覆盖 committed OpenSpec 的核心要求。 | 是 |
+| `.agents/skills/sm-flow/references/fallbacks.md` | 已新增统一 fallback 记录要求，并在各 fallback 协议中补入记录动作。 | 降级执行现在是可见、可审计的协议事件。 | 是 |
+| `skill-workbench/docs/sm-flow/workflow.md` | 已新增 question pool、Phase Checkpoint、Cross-Artifact Alignment、Micro 不是 Skip、fallback 记录要求等说明。 | retrospective 中的经验已被提升为稳定规则，而不是仅停留在叙述层。 | 是 |
+| `openspec/changes/sm-flow-execution-hardening/tasks.md` | 已完成 1.1-3.2，文档实现范围已落地。 | Phase 3 的协议/文档实现部分已完成，剩余工作转入验证与验收。 | 是 |
@@ -0,0 +1,67 @@
+# SM Flow Execution Hardening PRD
+
+## 问题陈述
+
+`sm-flow` 已经定义了较完整的阶段、规则和 reference 文件，但在真实项目执行中，代理仍然会把它当成“有帮助的流程建议”，而不是“必须逐阶段满足的执行协议”。结果是：
+
+- Phase 0 没有形成入口摘要和已知影响区域。
+- Phase 0.5 没有及时初始化和维护 `devflow/` 项目档案。
+- Phase 1 没有显式声明 skill 或 fallback，Draft / Committed OpenSpec 的边界不稳定。
+- Phase 1.5 被跳过，导致 proposal / design / research / specs / tasks 之间的一致性缺口直到用户 review 才暴露。
+- Phase 2 虽然收集了证据，但没有以结构化问题池和 one-at-a-time 的方式稳定执行。
+- Phase 2.5 被跳过，架构链路和接口影响没有提前暴露。
+- Phase 2.9 缺少强制自检，无法可靠发现 cross-artifact 遗漏。
+
+这说明当前痛点不是缺少理念，而是缺少“执行时自检”和“阶段切换门禁”的产品化机制。
+
+## 解决方案
+
+为 `sm-flow` 增加一轮“执行硬化”需求，目标是让代理在实际使用中更难偏离阶段协议。重点不是新增更多解释，而是把现有规则压缩成更可执行、更可检查、更可暴露偏差的约束，例如：
+
+- 每个阶段结束必须有简短 checklist / checkpoint。
+- 未显式声明 skill 或 fallback 视为该阶段未完成。
+- Phase 2 先生成问题池，再按 one-at-a-time 消费。
+- Phase 1.5 / 2.9 引入更明确的 cross-artifact diff 检查。
+- `micro` 明确只能压缩产物，不得跳过关键 gate。
+- devflow 产物默认在过程内同步更新，而不是拖到 Phase 4 补写。
+
+## 用户故事
+
+1. 作为使用 `sm-flow` 的开发者，我希望代理在进入下一阶段前自动暴露“已满足/未满足”的条件，这样我能尽早发现流程偏差。
+2. 作为使用 `sm-flow` 的开发者，我希望 `micro` 模式仍然保留关键 gate，这样小改动不会因为“看起来简单”而漏掉重要检查。
+3. 作为使用 `sm-flow` 的开发者，我希望 Phase 2 先形成问题池，再逐个提问，这样既符合 human-in-the-loop 约束，也能避免只问了少数问题就错误收尾。
+4. 作为使用 `sm-flow` 的开发者，我希望 Phase 1.5 和 2.9 能可靠检查 proposal / design / specs / tasks / evidence / decisions 的一致性，这样问题能在 apply 前暴露，而不是等我 review。
+
+## 实现决策
+
+- 决策：本轮先把“执行硬化”提炼成需求，而不是直接进入文档改造。
+  - 原因：当前已掌握足够多的真实使用反馈，需要先明确问题边界和验收标准，再决定是否开新 OpenSpec change。
+  - 影响：下一步可以更顺畅地进入 `sm-flow` 的正式改造，而不是边讨论边补规则。
+
+- 决策：把重点放在 phase gate、自检、问题池和一致性检查，而不是继续扩展 `sm-flow` 的理念层说明。
+  - 原因：复盘显示失真主要来自执行习惯和缺少检查，而不是原则方向错误。
+  - 影响：后续改动应优先落在 `SKILL.md`、`phase-contracts.md` 和模板/检查清单，而不是重写 workflow 长文。
+
+## 测试决策
+
+- 好测试应该通过审查 `sm-flow` 协议文本和执行产物，验证代理是否被强制带到正确的阶段检查点。
+- 必须覆盖：
+  - `micro` 模式下 gate 不可跳过
+  - Phase 2 问题池与 one-at-a-time 提问
+  - skill/fallback 显式声明要求
+  - Phase 1.5 / 2.9 cross-artifact 检查
+  - devflow 过程内同步更新
+- 不测试：
+  - 业务代码实现结果
+  - OpenSpec CLI 本身的功能正确性
+
+## 非目标
+
+- 不在本轮定义新的业务流程。
+- 不在本轮替换 OpenSpec-first / Devflow-assisted 主设计。
+- 不要求为所有小改动增加更重的文档负担。
+
+## 补充说明
+
+- 这轮需求直接来源于一次真实项目执行复盘，因此它比理念讨论更贴近代理实际失真模式。
+- 如果后续进入 OpenSpec，建议 change 名可沿用 `sm-flow-execution-hardening`。