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
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-22
@@ -0,0 +1,115 @@
+## Context
+
+这次 change 处理的是 `sm-flow` 的执行稳定性，而不是流程理念重构。已有文档已经定义了阶段顺序、Phase 2.9、接口影响、实现期冲突分类和 devflow 索引，但真实使用表明，规则如果没有变成“阶段切换前必须显式满足的条件”，就会在执行中被代理惯性绕开。
+
+受影响的主要文件位于：
+
+- `.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.md` 承载短而硬的总规则和 gate。
+- `phase-contracts.md` 承载逐阶段进入、动作、退出和 checkpoint。
+- `fallbacks.md` 承载 capability 不可用时的降级协议与记录要求。
+- `templates.md` 只在确有必要时提供轻量字段提示，不承载主逻辑。
+- `workflow.md` 只解释设计与演进背景，不重复执行细则或承担执行真理源职责。
+
+## Design
+
+### 1. Phase checkpoints as executable gates
+
+为每个关键阶段引入最小 checkpoint，要求代理在阶段结束时显式汇报：
+
+1. 当前阶段名称。
+2. 本阶段调用的 skill / 本地 `SKILL.md` / fallback。
+3. 本阶段产物。
+4. 已满足的退出条件。
+5. 未满足但仍阻塞下一阶段的问题。
+
+这个 checkpoint 不是替代现有 `phase-contracts.md`，而是把长契约压缩成执行中更容易遵守的门禁动作。
+本次设计只要求这些 checkpoint 具备明确字段和动作，不要求新增统一模板或统一展示格式。
+
+### 2. Skill/fallback declaration becomes a completion condition
+
+现有规则要求进入某些阶段时说明 skill 或 fallback，但执行中容易被忽略。硬化后：
+
+- 若本阶段未显式声明使用的能力来源，则阶段不得视为完成。
+- 若发生 fallback，必须同时记录：目标 skill、不可用原因、采用的 fallback 协议、降级风险。
+
+### 3. Phase 2 uses a question pool
+
+现有规则强调 one-at-a-time，但没有约束问题覆盖面。硬化后，Phase 2 先生成问题池，再逐个消费：
+
+- 问题池至少覆盖术语、边界、验收。
+- 对复杂任务，可继续覆盖权限、上下游触发、前端返回结构、兼容性、生命周期等。
+- `user-interview` 问题仍然一次只问一个，但问题池必须先暴露计划覆盖面。
+
+这样既保留 human-in-the-loop 约束，也降低“只问了几个问题就误以为够了”的风险。
+
+### 4. Cross-artifact alignment becomes explicit
+
+Phase 1.5 和 2.9 需要明确检查的对齐关系：
+
+- `brief/prd` -> `proposal`
+- `proposal` -> `design`
+- `design` -> `specs`
+- `specs` -> `tasks`
+- `evidence/decisions` -> OpenSpec 回写状态
+
+如果任何链路出现信息缺失、术语不一致、能力未落到 spec、spec 未落到 task，都必须在进入下一阶段前暴露。
+
+### 5. Micro mode preserves gates
+
+`micro` 继续允许合并产物，但明确禁止跳过：
+
+- Phase 0.5 最小上下文检查
+- Phase 2 最小澄清
+- Phase 2.9 commit gate
+- Phase 4 轻量归档
+
+这次 change 不增加 `micro` 的文档负担，而是把“不能跳哪些 gate”写得更硬。
+
+### 6. Devflow updates happen during the flow
+
+`devflow` 不再被视为“最后补文档”。设计上要求：
+
+- Phase 0 写入口摘要到 `brief.md`
+- Phase 2 写 evidence / decisions
+- Phase 2.5 写架构审计摘要
+- Phase 2.9 写 commit gate 结果
+- Phase 4 只做汇总和归档收尾
+
+这样 Phase 4 变成收敛，而不是返工。
+
+### 7. Rule placement avoids duplication drift
+
+本次 change 的一个隐含架构约束是避免同一规则在多个层面双份维护：
+
+- 如果某条规则属于执行门禁，应优先落在 `SKILL.md` 或 `phase-contracts.md`。
+- 如果某条规则属于 capability 降级，应优先落在 `fallbacks.md`。
+- `workflow.md` 可以解释为什么这样设计，但不应再逐条复制执行细则。
+- `templates.md` 保持可选和轻量，否则会把“协议硬化”扩大成“格式标准化”。
+
+这能降低 v3.1 之后再次出现“规则已经写了，但代理仍然执行漂移”的维护风险。
+
+## Risks / Trade-offs
+
+- 更强的 checkpoint 会增加少量流程显式成本，但可以换来更低的遗漏率。
+- 问题池可能让 Phase 2 看起来更正式，但如果不先暴露覆盖面，one-at-a-time 容易退化成随机追问。
+- 更硬的 cross-artifact 检查会让 change 前期更慢，但比在 apply 前后由用户兜底更可靠。
+- 如果把同一规则同时写进协议、模板和案例说明，后续维护面会再次变大，因此这轮需要严格控制规则落点。
+
+## Validation
+
+需要通过文档与 OpenSpec 产物验证以下结果：
+
+- `sm-flow` 明确要求阶段 checkpoint。
+- `micro` 明确禁止跳过关键 gate。
+- Phase 2 明确先形成问题池，再一次一问推进。
+- Phase 1.5 / 2.9 明确 cross-artifact 检查链路。
+- devflow 的过程内同步更新要求被写入协议。
+- 不要求代理额外输出统一格式的阶段汇报示例。
@@ -0,0 +1,47 @@
+## Why
+
+`sm-flow` 已经建立了 `OpenSpec-first / Devflow-assisted` 的主从关系，也补入了 Draft/Committed OpenSpec、接口影响分级、Phase 2.9 和实现期冲突分类等关键规则。但真实项目复盘显示，代理仍然会按“先读代码、先形成方案、尽快推进实现”的习惯行动，而不是稳定经过 phase gate、自检和一致性检查。
+
+当前问题不是主设计方向错误，而是执行协议还不够“硬”：
+
+- `micro` 模式容易被误解为可以跳过关键阶段。
+- skill/fallback 声明存在规则，但没有成为阶段完成条件。
+- Phase 2 有 one-at-a-time 约束，但没有先形成问题池，导致问题覆盖不足。
+- Phase 1.5 和 2.9 的 cross-artifact 检查缺少更明确的执行清单，遗漏只能等用户 review 才暴露。
+- devflow 产物容易被拖到 Phase 4 补写，而不是在过程内同步更新。
+
+因此需要新增一轮“执行硬化”改造，把现有规则收敛成更明确的阶段检查点、问题池机制和一致性检查要求。
+
+## What Changes
+
+- 为 `sm-flow` 增加更短、更高频的 phase checklist / checkpoint 规则。
+- 明确“未显式声明 skill 或 fallback = 本阶段未完成”。
+- 为 Phase 2 增加“先形成问题池，再一次一问推进”的要求。
+- 强化 Phase 1.5 / 2.9 的 cross-artifact diff 检查，覆盖 proposal、design、specs、tasks、brief、evidence、decisions 的一致性。
+- 明确 `micro` 只能压缩产物，不能跳过 Phase 0.5、Phase 2、Phase 2.9 等关键 gate。
+- 明确 devflow 默认在各阶段同步更新，而不是拖到 Phase 4 统一补写。
+- 明确本次改造不强制固定 checkpoint / alignment 模板，也不把统一阶段汇报格式纳入验收范围。
+
+## Capabilities
+
+### New Capabilities
+
+- `sm-flow-phase-checkpoints`: 定义各阶段的最小检查点和阶段完成条件。
+- `sm-flow-question-pool`: 定义 Phase 2 的问题池生成与单题推进规则。
+- `sm-flow-cross-artifact-alignment`: 定义 Phase 1.5 / 2.9 的跨产物一致性检查要求。
+- `sm-flow-micro-gate-preservation`: 定义 `micro` 模式下不可跳过的关键 gate。
+
+### Modified Capabilities
+
+- `sm-flow-commit-gate`: 增强提交前检查，补充 cross-artifact diff 和阶段状态显式确认。
+- `sm-flow-context-indexing`: 补充 devflow 过程内同步更新要求。
+
+## Impact
+
+- 修改 `.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`
+- 不修改业务代码
+- 不改变 `OpenSpec-first / Devflow-assisted` 主设计
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Phase 1.5 checks cross-artifact alignment explicitly
+
+SM Flow SHALL explicitly check alignment across requirement, design, specification, and execution artifacts during Phase 1.5.
+
+#### Scenario: Alignment check runs
+
+- **WHEN** Phase 1.5 reviews the current Draft OpenSpec
+- **THEN** it checks that `brief/prd` aligns with `proposal`, `proposal` aligns with `design`, `design` aligns with `specs`, and `specs` align with `tasks`
+
+#### Scenario: Alignment gap is found
+
+- **WHEN** an expected behavior, term, field, constraint, or implementation slice appears in one artifact but not its downstream artifact
+- **THEN** the flow marks the gap explicitly and repairs OpenSpec before entering the next phase
+
+### Requirement: Phase 2.9 validates cross-artifact closure
+
+SM Flow SHALL re-check cross-artifact closure during Phase 2.9 before implementation.
+
+#### Scenario: Commit gate runs
+
+- **WHEN** Phase 2.9 evaluates whether Draft OpenSpec can become Committed OpenSpec
+- **THEN** it verifies that `evidence.md` and `decisions.md` findings that affect implementation are reflected in proposal, design, specs, or tasks
+
+#### Scenario: User review would otherwise catch the gap
+
+- **WHEN** a field, scope item, acceptance behavior, or design constraint is missing from the downstream OpenSpec artifacts
+- **THEN** the flow SHALL fail the commit gate and return to the earlier phase that owns the missing update
@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Micro mode compresses artifacts but preserves critical gates
+
+SM Flow SHALL allow `micro` mode to reduce artifact weight without skipping critical gates.
+
+#### Scenario: Micro mode starts
+
+- **WHEN** a change is classified as `micro`
+- **THEN** the flow may merge or simplify devflow artifacts
+- **AND** it SHALL still perform Phase 0.5 minimum context harvest, Phase 2 minimum clarification, Phase 2.9 commit gate, and Phase 4 lightweight backfill
+
+#### Scenario: Micro mode is treated as skip permission
+
+- **WHEN** the agent attempts to skip a critical gate because the change is small or low-risk
+- **THEN** the flow SHALL treat that as a protocol deviation rather than a valid micro-mode optimization
+
+### Requirement: Devflow updates happen during the flow
+
+SM Flow SHALL update devflow artifacts during the relevant phases rather than deferring all updates to Phase 4.
+
+#### Scenario: Phase-local information is produced
+
+- **WHEN** a phase produces entry summary, evidence, decisions, architecture findings, or commit-gate conclusions
+- **THEN** the corresponding devflow artifact is updated in or near that phase
+
+#### Scenario: Phase 4 begins
+
+- **WHEN** the flow enters Phase 4
+- **THEN** devflow backfill is primarily a consolidation step rather than the first time those records are written
@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Each critical phase has an explicit checkpoint
+
+SM Flow SHALL require an explicit checkpoint before a critical phase can be considered complete.
+
+#### Scenario: Phase completes normally
+
+- **WHEN** the agent finishes a critical phase such as Phase 0, Phase 0.5, Phase 1, Phase 2, Phase 2.5, or Phase 2.9
+- **THEN** it reports the current phase, the capability source used, the produced artifacts, the satisfied exit conditions, and any unresolved blockers
+
+#### Scenario: Checkpoint is missing
+
+- **WHEN** a critical phase has produced artifacts or conclusions but no explicit checkpoint summary
+- **THEN** the phase SHALL NOT be treated as complete for purposes of entering the next phase
+
+### Requirement: Capability declaration is part of phase completion
+
+SM Flow SHALL treat skill or fallback declaration as part of the phase completion condition.
+
+#### Scenario: Native skill or local protocol is used
+
+- **WHEN** a phase depends on a named capability such as `openspec-propose`, `grill-with-docs`, `zoom-out`, or `openspec-apply-change`
+- **THEN** the agent states whether it used a native skill, a local `SKILL.md`, or a fallback protocol
+
+#### Scenario: Fallback is used
+
+- **WHEN** a phase falls back from a named capability
+- **THEN** the agent records the target capability, the reason it was unavailable, the fallback protocol name, and the downgrade risk
+
+#### Scenario: Declaration is omitted
+
+- **WHEN** no capability source is declared for a phase that requires one
+- **THEN** that phase SHALL NOT be considered complete
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Phase 2 builds a question pool before interviewing
+
+SM Flow SHALL build a Phase 2 question pool before consuming `user-interview` questions one at a time.
+
+#### Scenario: Phase 2 starts
+
+- **WHEN** the flow enters Phase 2
+- **THEN** it defines a question pool that covers at least terminology, scope boundaries, and acceptance
+
+#### Scenario: Complex change needs deeper coverage
+
+- **WHEN** the change affects multiple modules, interfaces, permissions, downstream consumers, response structures, or lifecycle rules
+- **THEN** the Phase 2 question pool also includes those dimensions before user-interview consumption begins
+
+### Requirement: User-interview questions remain one-at-a-time
+
+SM Flow SHALL preserve the one-question-at-a-time rule while using a question pool.
+
+#### Scenario: User-interview question is asked
+
+- **WHEN** the next unresolved `user-interview` item is selected from the question pool
+- **THEN** the flow asks exactly one question, waits for the explicit user answer, records the result, and only then advances to the next `user-interview` item
+
+#### Scenario: Question pool exists but answer is missing
+
+- **WHEN** there are remaining question-pool items and the current `user-interview` question is unanswered
+- **THEN** the flow SHALL NOT ask another `user-interview` question until the current one is resolved
@@ -0,0 +1,24 @@
+## 1. OpenSpec artifacts
+
+- [x] 1.1 Write proposal for `sm-flow-execution-hardening`
+- [x] 1.2 Write design for execution hardening rules
+- [x] 1.3 Add specs for checkpoints, question pool, cross-artifact alignment, and micro gate preservation
+
+## 2. Protocol hardening
+
+- [x] 2.1 Update `.agents/skills/sm-flow/SKILL.md` with explicit phase checkpoint and stage-completion rules
+- [x] 2.2 Update `.agents/skills/sm-flow/references/phase-contracts.md` with question pool, cross-artifact alignment, and micro gate preservation rules
+- [x] 2.3 Update `.agents/skills/sm-flow/references/fallbacks.md` so fallback declaration is mandatory and recorded
+- [x] 2.4 Keep templates optional; only adjust them if existing references need minimal field hints rather than mandatory fixed formats
+
+## 3. Workflow documentation
+
+- [x] 3.1 Update `skill-workbench/docs/sm-flow/workflow.md` with the execution-hardening model
+- [x] 3.2 Ensure retrospective learnings are reflected as protocol rules rather than only narrative notes
+
+## 4. Validation
+
+- [x] 4.1 Validate the OpenSpec change
+- [x] 4.2 Verify key terms are consistently documented across skill, references, and workflow docs
+- [x] 4.3 Backfill devflow records after implementation if the change proceeds beyond Draft
+- [x] 4.4 Verify acceptance is satisfied by protocol/document changes alone, without requiring a standardized phase-report output format