Refine sm-flow trigger and scale rules

2026-07-05 14:30:15 +08:00
parent 433f7a93a4
commit e4f6e013a5
28 changed files with 937 additions and 105 deletions
@@ -1,6 +1,6 @@
 # SM-Flow 工作流

-## 当前设计理念（v4 方向）
+## 当前设计理念（v4.3）

 **核心定位**：sm-flow 是一个**用提示词实现的协议层 harness**——编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。

@@ -22,6 +22,15 @@ sm-flow        → 编排层（harness）：阶段、门控、产物约束、人
 | `/sm-flow apply` | 只执行（已有 Committed OpenSpec） |
 | `/sm-flow archive` | 收尾（回填 devflow + 归档确认） |

+**触发边界**：
+
+sm-flow 只在用户显式调用时使用：
+
+- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。
+- 用户用自然语言明确要求“使用 sm-flow”“走 sm-flow 流程”或等价表达。
+
+不要根据任务类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。
+
 **内部阶段（9 个，英文动词命名）**：

 ```
@@ -29,7 +38,7 @@ clarify → context → propose → grill → specify → audit → commit → a
 入口澄清   上下文     轻量提案   澄清    细化      审计    提交     执行    归档
 ```

-阶段名是 harness 的内部协议词汇（用于 checkpoint 汇报和进度通知），不是用户 API。用户只需知道 4 个命令，其余通过自然语言交互，由 harness 识别意图后编排。
+阶段名是 harness 的内部协议词汇，不是用户 API。面向用户默认只暴露 4 个可见 checkpoint：Discover、Commit、Apply、Archive；内部阶段仍按顺序执行。

 **关键设计决策**：

@@ -37,7 +46,9 @@ clarify → context → propose → grill → specify → audit → commit → a
 - **Draft / Committed 分离**：propose 产出 Draft OpenSpec（讨论对象），commit gate 后成为 Committed OpenSpec（执行许可）。apply 只执行 Committed OpenSpec。
 - **grill 在 specify 前**：先澄清需求再细化产物，避免"细化 → grill → 回写细化"的返工循环。propose 只写轻量 proposal.md，grill 稳定需求后 specify 才补全 design/specs/tasks。
 - **devflow 延迟写入**：clarify → apply 期间只维护 `decisions.md` 作为过程日志，archive 阶段从中提取完整 devflow 档案（brief/evidence/acceptance）。
- **micro ≠ skip**：快速模式合并 gate（clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill 最少 1 个问题 → commit 简化检查），但保留最关键的门控。
+- **micro ≠ skip**：micro 是 standard 的减法，不是跳过流程。它可以合并 checkpoint、减少独立产物，但仍保留 context、grill、commit、apply 和 archive gate。
+- **分档单一来源**：`micro / standard / complex` 的完整定义只放在 `.agents/skills/sm-flow/references/scales.md`，其它文件只引用当前分档要求。
+- **能力来源显式声明**：每个阶段都要说明使用外部子 skill、OpenSpec CLI 还是 sm-flow 内置 fallback；fallback 不是跳过阶段，必须写入 `decisions.md` 或 `acceptance.md`。
 - **质量约束可观测**：质量约束必须转化为可观测产出（写入文件 + checkpoint 检查），否则不是约束而是建议。

 **使用方式**：
@@ -92,14 +103,14 @@ Phase 4  openspec:apply     Phase 2    grill-with-docs → CONTEXT.md + ADR

 ## 新增技能的投入产出

-| 技能 | 学多久 | 一次省多少 | 什么时候用 |
+| 技能 | 接入成本 | 主要收益 | 什么时候用 |
 |------|--------|-----------|-----------|
-| to-prd | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 |
-| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 |
-| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 |
-| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 |
-| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 |
-| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 |
+| to-prd | 自动综合 | 结构化需求 | openspec research 结束后 |
+| grill-with-docs | 替换已有 grill-me | 产出文档化澄清 | 需求澄清阶段 |
+| zoom-out | 低 | 避免方向性返工 | grill 完成后、apply 前 |
+| diagnose | 低 | 减少猜测式 bug 修复 | apply 中遇到问题 |
+| tdd | 低 | 减少回归 bug | apply 中写代码 |
+| git-guardrails | 被动生效 | 防止灾难性操作 | 全程自动 |

 ## 为什么这套组合优于单纯依赖 openspec

@@ -804,7 +815,7 @@ v4：

 | # | 问题 | 具体表现 | 分析结论 |
 |---|------|----------|----------|
-| 1 | propose 阶段越界 | 在 propose 阶段一次性生成了 proposal + design + specs + tasks，跳过 grill 和 specify | 需求小时 agent 本能跳过门控。现有硬约束 #3（不得跳过 grill）和阶段流程顺序已覆盖，属于执行层面问题，不需要改协议 |
+| 1 | propose 阶段越界 | 在 propose 阶段一次性生成了 proposal + design + specs + tasks，跳过 grill 和 specify | 需求较小场景下 agent 本能跳过门控。现有硬约束 #3（不得跳过 grill）和阶段流程顺序已覆盖，属于执行层面问题，不需要改协议 |
 | 2 | 子 skill 伪调用 | grill 阶段读了 grill-with-docs 的 SKILL.md 后自行执行，audit 阶段跳过了 zoom-out | Skill 工具调用和 Read 后执行效果等价，关键是"不能跳过"而非"用什么工具调用"。硬约束 #6 已覆盖，不需要改协议 |
 | 3 | spec 遗漏用户行为 | spec 写的是"添加 .expanded class"（实现细节），没有写"展开后显示完整正文"（用户可观察行为） | 导致第一版实现只切换了 CSS class，正文内容仍显示截断文本。spec 应描述用户可观察的结果而非实现方式 |

@@ -852,7 +863,7 @@ v4：

 #### 修改 2：apply 阶段增加 Pre-apply Checkpoint

-在 apply 阶段开始前增加 15-20 分钟的强制调研步骤：
+在 apply 阶段开始前增加强制调研步骤：

 **触发条件**（3 条）：
 - design 或 tasks 中提到"参考 XXX 实现"
@@ -860,12 +871,12 @@ v4：
 - 技术栈不熟悉或第一次在该项目实现类似功能

 **执行步骤**（3 步）：
-1. **完整阅读所有参考实现**（约 10 分钟）
+1. **完整阅读所有参考实现**
   - 从 OpenSpec design 或 tasks 中定位参考实现文件
   - 如果路径不明确，通过 Grep 搜索关键类名或模式
   - 逐行理解关键逻辑，提取可复用代码片段和模式

-2. **Grep 关键技术栈**（约 5 分钟）
+2. **Grep 关键技术栈**
   - 请求/响应结构模式
   - 消息队列模式
   - 统一工具类
@@ -883,7 +894,7 @@ v4：
 - ✅ 已列出所有参考实现的文件路径
 - ✅ 已识别需要新建的工具类/基础设施

-**快速模式支持**：micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单。
+**快速模式支持**：micro 分档可按风险缩小调研范围，但仍需形成清单。

 #### 修改 3：apply 实现过程增强

@@ -905,15 +916,10 @@ v4：
 |------|------|------|------|
 | 返工次数 | 4-5 次 | 0-1 次 | -80% |
 | 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% |
-| 实现时间（含返工） | 2 小时 | 1.5 小时 | -25% |
-| 前置调研时间 | 0 分钟 | 15-20 分钟 | +20 分钟 |

 **ROI 分析**：
-```
-投入：15-20 分钟调研
-回报：节省 60 分钟返工 + 避免核心功能遗漏
-ROI = (60 - 20) / 20 = 200%
-```
+
+前置调研的收益来自减少返工和避免核心功能遗漏。v4.3 之后不再用固定投入指标定义投入或收益，改按风险和实现复杂度决定调研深度。

 ### 复杂度评估

@@ -941,7 +947,7 @@ ROI = (60 - 20) / 20 = 200%
 - 设计文档提到"参考 XXX 实现"

 🟡 **可选执行**：
- micro 分档的简单需求（可缩短为 5-10 分钟）
+- micro 分档的简单需求（可按风险缩小范围）
 - 纯数据处理或工具脚本（技术栈熟悉）

 ❌ **不推荐**：
@@ -1002,7 +1008,7 @@ v4.2 不增加新阶段或新规则，而是**把现有约束变成可验证的
 2. 如不存在：
   - 汇报：Draft OpenSpec 未通过 commit 检查
   - 列出缺失的 checkpoint 项
-   - 询问用户：是否补做 commit，或明确跳过（需显式确认）
+   - 询问用户：是否补做 commit；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`

 #### 修改 3：Archive 阶段增加强制执行顺序

@@ -1115,3 +1121,115 @@ v4.2 的改进是执行机制层面的，不涉及业务逻辑：
 - 修改文件：
  - `.agents/skills/sm-flow/references/phase-contracts.md`
  - `.agents/skills/sm-flow/references/archive-rules.md`
+
+## v4.3：显式触发、分档单一来源与验证闭环（2026-07-05）
+
+### 背景
+
+v4.2 之后，流程门控更可靠，但 skill 本身开始显得庞大：frontmatter、触发规则、分档规则、fallback、术语解释和阶段契约交织在一起。实际 review 中发现几个风险：
+
+- 触发范围容易被写宽，导致任务只要涉及 OpenSpec、跨模块或 devflow 就自动触发 sm-flow。
+- `micro / standard / complex` 的规则散落在多个文件里，后续维护容易不一致。
+- `micro`、`standard`、`complex` 的要求同时分布在不同文件中，review 时很难判断哪个是权威。
+- 规则中出现固定投入估算，容易把经验值误读成流程标准。
+- fallback、checkpoint、Draft/Committed 等词缺少统一词条，解释容易漂移。
+
+### 核心结论
+
+v4.3 保留 v4 的精华，但收紧触发面、降低重复定义，并用真实 change 验证 micro 和 standard 两条路径：
+
+- **只显式触发**：sm-flow 只在用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`，或自然语言明确要求“使用 sm-flow / 走 sm-flow 流程”时触发。
+- **不按需求类型自动触发**：OpenSpec、跨模块、接口契约、需求澄清、devflow 归档都不是自动触发条件。
+- **4 个用户可见 checkpoint 保留**：Discover、Commit、Apply、Archive。
+- **9 个内部阶段保留**：clarify → context → propose → grill → specify → audit → commit → apply → archive。
+- **分档单一来源**：`references/scales.md` 是 `micro / standard / complex` 的唯一完整规则源。
+- **fallback 独立成文**：外部 OpenSpec 能力或子 skill 不可用时，使用 `references/fallbacks.md`，并记录 capability source、影响和剩余风险。
+- **词条独立成文**：`references/glossary.md` 统一 checkpoint、fallback、Draft、Committed、gate、scale 等术语。
+- **不使用固定投入指标**：skill 规则不再用具体投入单位或时间盒定义分档、努力程度或验证阈值。
+
+### 文件结构调整
+
+新增 reference：
+
+```text
+.agents/skills/sm-flow/references/
+├── fallbacks.md     # 外部 OpenSpec/子 skill 不可用时的内置协议
+├── glossary.md      # checkpoint/gate/fallback/Draft/Committed/scale 等术语
+└── scales.md        # micro / standard / complex 的唯一完整定义
+```
+
+职责调整：
+
+- `SKILL.md`：只保留触发边界、四层架构、6 条硬约束、4 个用户命令、4 个 checkpoint、9 个内部阶段和首次加载规则。
+- `phase-contracts.md`：保留阶段进入条件、动作、输出和退出条件；涉及分档时只引用 `scales.md`。
+- `operating-rules.md`：保留启动检查、进度汇报、接口影响、devflow 分层和完成标准；不再重复定义分档细节。
+- `archive-rules.md`：只定义归档顺序、提取映射和索引规则；产物分档引用 `scales.md`。
+- `templates.md`：保留模板和检查表，不再作为分档规则来源。
+
+### 分档验证
+
+#### micro 验证
+
+验证 change：`validate-sm-flow-explicit-trigger`
+
+归档位置：
+
+```text
+openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/
+devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/
+```
+
+验证内容：
+
+- 显式触发规则生效：没有 `/sm-flow` 或明确“使用 sm-flow”时，不自动触发正式 sm-flow。
+- micro 可以使用内联设计小节，但仍需要 `proposal.md`、`specs/`、`tasks.md`、`.committed` 和 devflow 回填。
+- 发现并修复一个真实不一致：部分阶段契约仍硬编码 `design.md`，与 micro 允许等价设计小节冲突；已改为“设计产物”。
+- devflow micro 档案使用 `brief.md`、`decisions.md`、`acceptance.md`；证据并入过程日志。
+
+#### standard 验证
+
+验证 change：`validate-sm-flow-standard-change`
+
+归档位置：
+
+```text
+openspec/archive/2026-07-05-validate-sm-flow-standard-change/
+devflow/projects/2026-07-05-validate-sm-flow-standard-change/
+```
+
+验证内容：
+
+- standard 需要完整 OpenSpec 四件套：`proposal.md`、独立 `design.md`、`specs/`、`tasks.md`。
+- standard devflow 档案需要 `brief.md`、独立 `evidence.md`、`decisions.md`、`acceptance.md`。
+- 分档定义扫描只命中 `references/scales.md`，没有发现其它文件重新定义 standard/micro/complex。
+- standard 路径未发现新的规则不一致。
+
+### 验证命令与结果
+
+本轮验证通过：
+
+- `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow`
+- `references/*.md` 引用完整性扫描
+- 旧问题词扫描：固定投入指标、旧跳过语义、旧 conflict 表达、旧固定设计文件组合表达
+- 分档重复定义扫描
+- micro 和 standard OpenSpec/devflow 文件存在性检查
+
+### 当前取舍
+
+- 保留 3 个分档：`micro`、`standard`、`complex`。它们不是三套流程，而是同一流程在产物和审查强度上的三档覆盖。
+- 不引入显式状态文件，例如 `.sm-flow-state`。当前只保留 `.committed` 和 `.archive-ready` 两个必要 gate 文件。
+- 不把内部 9 阶段暴露成用户 API。用户交互继续以 4 个 checkpoint 为主。
+- 不默认做 OpenSpec archive；archive 仍是用户确认后的动作。
+
+### 对 v4.1/v4.2 的修正
+
+v4.1 的 Pre-apply Research 仍然保留，但不再用固定投入指标描述执行深度。当前规则是：按 `references/scales.md` 的当前分档和实现风险决定调研深度，退出判断以技术栈清单是否足以指导实现为准。
+
+v4.2 的 `.committed` 和 `.archive-ready` 继续保留。v4.3 只是把文件完整性检查改为“按当前分档要求执行”，避免 standard 的独立 `design.md` 要求误套到 micro。
+
+### 相关档案
+
+- `devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/`
+- `devflow/projects/2026-07-05-validate-sm-flow-standard-change/`
+- `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/`
+- `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`