Introduce dev-flow: lightweight 3-phase flow with decision archive

Merge pull request 'Refine sm-flow trigger and scale rules' (#2 ) from emdash/tasty-fans-dress-9sc8f into master
Reviewed-on: #2
2026-09-16 20:06:09 +08:00 · 2026-07-06 10:00:37 +08:00 · 2026-07-05 14:30:15 +08:00 · 2026-07-05 03:16:12 +08:00
32 changed files with 2056 additions and 105 deletions
@@ -0,0 +1,187 @@
+---
+name: dev-flow
+description: 轻量开发流程:想清楚 → 做出来 → 收好尾。编排 OpenSpec 的 propose / apply / archive 三个能力,并为每个非平凡变更留下 decision.md——记录为什么这么做、否决了哪些备选、代价是什么。在用户显式调用 /dev-flow,或明确要求走开发流程时使用。
+---
+
+# Dev Flow
+
+三个阶段,两个确认点,不分档。
+
+```text
+Think 想清楚   →   Build 做出来   →   Close 收好尾
+       ⏸ 确认点 1                          ⏸ 确认点 2
+     授权进入实现                          是否归档
+```
+
+**每个非平凡变更留下一份 `decision.md`**——记录代码和规格承载不了的东西:**为什么这么做,以及放弃了什么。**
+
+## 能力来源
+
+dev-flow 编排已有能力,**不重复实现它们**:
+
+| 阶段 | 能力 | 用途 |
+|---|---|---|
+| Think | `grill-with-docs` | 澄清:一次一问、能查代码的自己查、术语沉淀进 `CONTEXT.md` |
+| Think | `openspec-propose` | 生成 `proposal.md` / `design.md` / `specs/` / `tasks.md` |
+| Build | `openspec-apply-change` | 按规格实现 |
+| Build | `diagnose` / `tdd` | 按需:bug 排查 / 测试驱动 |
+| Close | `openspec-archive-change` | 归档 |
+
+**按能力绑定,不按路径绑定**:优先用平台原生 skill;不可用时读本地 `SKILL.md` 并按其协议执行;仍不可用时按最小等价协议直接产出文件。**不可用时在 `decision.md` 里注明。**
+
+**不使用 `to-prd`**:它把 PRD 发布到 issue tracker(本仓库没有),且内容与 `proposal.md` + `specs/` 重复。
+**不设 `audit` 阶段**:`zoom-out` 保留为按需能力(不熟悉代码区域时拉高视角),但它不是一个必须走的关卡。
+
+### 冲突裁决
+
+被组合的子 skill 与本流程会冲突——这是组合的固有代价。**靠规则裁决,不靠内置。**
+
+> **子 skill 管"这一步怎么做";dev-flow 管"做多少、结果放哪"。**
+> **冲突时,流程赢。**
+
+当前组合里,由 dev-flow 覆盖子 skill 默认的有三处:
+
+| 子 skill 的默认 | dev-flow 的覆盖 |
+|---|---|
+| `grill-with-docs` 要求 relentlessly 追问 | **范围收窄**:只问答案会改变产物的问题 |
+| ADR 写入 `docs/adr/`,用 `ADR-FORMAT.md` | **落点改为 `decision.md`**,格式用 `decision-note.md`,**不创建 `docs/adr/`** |
+| 假设根目录 `CONTEXT.md` | 用 **`devflow/glossary/CONTEXT.md`** |
+
+**归属规则解决不了的冲突,不要靠内置解决,而是不组合它。**
+
+> 理由:内置只在被组合 skill **消失**时才消除冲突。只要它还装在目录里(用户可以直接调用),
+> 内置就只是让 dev-flow 多出一份**会漂移的私有副本**——重复实现加上版本漂移,两个问题。
+> `to-prd` 就是这么处理的:直接排除,而不是改造成 dev-flow 的版本。
+
+## Think — 想清楚
+
+**进入**:用户给出需求——粗略想法、issue、草稿、已有 PRD 都算。
+
+**动作**:
+
+1. **澄清** —— 用 `grill-with-docs` 的方法,但按上面的 **「冲突裁决」** 覆盖它的默认:
+   范围收窄(只问答案会改变产物的问题)、ADR 落点为 `decision.md`、`CONTEXT.md` 用 `devflow/glossary/` 下那份。
+2. **读上下文**:`devflow/glossary/CONTEXT.md`,并搜索 `devflow/rejected/` 与已归档的 `decision.md`——
+   **避免重新提出已经被否决过的方案。**
+3. 写 `openspec/changes/<slug>/proposal.md`,并用 OpenSpec 补全 `design.md` / `specs/` / `tasks.md`。
+4. **写下 `decision.md` 的 `## Problem` 和 `## Alternatives considered`。**
+   理由在这一刻最新鲜;留到事后补写会变成回忆录。
+
+**退出**:proposal 能说清做什么、范围、非目标;`decision.md` 有 `## Problem` 和至少一条备选(或用 `<!-- alternatives-not-recorded -->` 显式声明没有)。
+
+**⏸ 确认点 1** —— 向用户汇报方案方向、关键假设、主要风险,然后**等待明确的实现授权**。
+
+> 未获授权不得进入 Build。
+> **方案讨论中的任何一次确认,都不等于实现授权。**
+
+## Build — 做出来
+
+**进入**:确认点 1 已过。
+
+**动作**:
+
+- 按 `tasks.md` 的纵向切片实现,按 `specs/` 验收。
+- **分步验证**:每完成一层再继续,不要一次写完再验。
+- **冲突先分类再处理**:
+
+| 分类 | 处理 |
+|---|---|
+| 规格不准(遗漏、边界未覆盖、验收口径缺失) | 暂停,修正 OpenSpec,再继续 |
+| 代码偏离(实现没按规格做) | 修正代码,不改 OpenSpec |
+| 不确定、或涉及设计方向 | **暂停,问用户** |
+
+- 遇到 bug 或行为不明 → 用 `diagnose`;需要测试驱动 → 用 `tdd`。两者都不强制。
+
+**退出**:tasks 完成或剩余已明确记录;已运行验证,或记录了未验证的原因;已知限制已列出。
+
+Build 结束**自动进入 Close**,中间不设确认点。
+
+## Close — 收好尾
+
+**进入**:实现达到可交接状态。
+
+**动作**:
+
+1. **补齐 `decision.md`**——把 `## Decision` 校准为**实际发布的做法**(现在时),补 `## Consequences` 和 `## Verification`。
+2. **执行收尾检查**(见下)。
+3. 有新术语 → 更新 `devflow/glossary/CONTEXT.md`。
+4. 有被否决的提案 → 写入 `devflow/rejected/<class>/`。
+5. **⏸ 确认点 2** —— 汇报产物、验证情况、剩余风险,询问是否归档。
+
+**退出**:`decision.md` 五节齐全;收尾检查通过;用户已被询问是否归档。
+
+## 核心规则
+
+| 规则 | 说明 |
+|---|---|
+| **必须写 `decision.md`** | 每个非平凡变更 |
+| **`## Alternatives considered` 强制** | 没有记录"打败了什么"的决策会招来重新争论 |
+| **备选是记录的,不是编造的** | 当时没记录就写 `<!-- alternatives-not-recorded -->` |
+| **实现前必须有授权** | 确认点 1 |
+| **冲突先分类再处理** | 三分法 |
+| **一个事实只有一个权威** | 见下表 |
+
+**"非平凡"的判据**:改变行为、架构、跨文件或跨包的契约、流程或工具、测试策略、磁盘/线缆/配置格式,或其他维护者可能重新考察的决策。
+**豁免**:纯机械或局部编辑。
+
+### 事实的唯一权威
+
+| 内容 | 权威 |
+|---|---|
+| 为什么这么做、放弃了什么、代价 | `decision.md` |
+| 实现设计、接口影响 | `design.md` |
+| 可观察行为、验收场景 | `specs/` |
+| 执行切片与完成状态 | `tasks.md` |
+| 跨项目术语 | `devflow/glossary/CONTEXT.md` |
+| 未实施的提案 | `devflow/rejected/` |
+
+**任何一句话只能在一个地方是权威。出现第二处,就是错**——两边会各自腐化,而且没人知道以哪边为准。
+
+## 为什么这么轻
+
+这三条是有意为之。**不要"补全"它们。**
+
+1. **义务挂在已有动作上。** 写规划产物的时刻,就是写 `decision.md` 的时刻。不设独立的归档阶段,不做事后提取。
+2. **确认点只有两个。** 进入实现、是否归档。不新增。
+3. **"是否该写"是判断。** 规则 + 收尾看一眼。机器只校验**已经写下**的东西是否合规,不用脚本强制这件事本身。
+
+## 收尾检查
+
+1. `openspec/changes/<slug>/decision.md` 存在
+2. 含 `## Alternatives considered`,或显式的 `<!-- alternatives-not-recorded -->`
+3. `## Verification` 里没有"已确认 X 存在"这类**不可重跑的结论**
+
+纯机械改动可以豁免。**豁免必须显式,但可以廉价**——目的是让"跳过"变成有意识的选择,而不是静默遗忘。
+
+> **计划中的自动化**:`scripts/check-dev-flow.sh`,遵循仓库现有脚本约定(`scripts/*.sh`)。
+> 在它落盘之前,上面三步手动执行。
+
+## 目录
+
+```text
+openspec/changes/<slug>/
+├── proposal.md   design.md   specs/   tasks.md
+└── decision.md              ← 人向:为什么、放弃了什么、代价
+       ↓ 随归档一起冻存
+
+devflow/
+├── glossary/CONTEXT.md      ← 跨项目术语
+├── rejected/<class>/        ← 未实施的提案
+└── index.md                 ← 由脚本扫描归档生成,不手写
+```
+
+`rejected/` 的保留条件:它**仍能防止一个诱人的、有意义的错误**。否则整体删除。
+
+## 触发规则
+
+- 用户输入 `/dev-flow`。
+- 用户明确要求走开发流程。
+
+不要因为任务涉及 OpenSpec、跨模块、架构决策或 devflow 目录就自动触发。
+未被这样要求之前,按普通工程任务处理。
+
+## 相关文档
+
+- `references/phases.md` — 三阶段契约与判断细则
+- `references/decision-note.md` — `decision.md` 格式规范、校准案例、反模式
+- `skill-workbench/docs/dev-flow/background-and-evolution.md` — 背景、技术演进、设计取舍
@@ -0,0 +1,230 @@
+# 决策档案格式
+
+本文件定义 `decision.md` 的格式、每节的要求、校准案例和反模式。
+
+## 骨架
+
+```markdown
+# Decision: <一句话标题>
+
+## Problem
+## Decision
+## Alternatives considered
+## Consequences
+## Verification
+```
+
+小节顺序固定。固定顺序不是为了机器,是为了**人能跳转**——任何时候你想知道"代价是什么",往下翻到 `## Consequences` 就行。
+
+节名是规范名,不要用近义词替代(`## 背景` / `## 方案` / `## 风险`)。
+需要额外内容时,在 `## Decision` 和 `## Alternatives considered` 之间插入自定义小节。
+
+### 各节在哪个阶段写下
+
+| 节 | 写下时机 | 原因 |
+|---|---|---|
+| `## Problem` | **Think** | 动机在需求刚澄清时最准确 |
+| `## Alternatives considered` | **Think** | 备选是在方案讨论中被否决的,当时记最真实;事后补写会变成回忆录 |
+| `## Decision` | Think 记意图,**Close 校准为事实** | 见下 |
+| `## Consequences` | **Close** | 代价要等实现完才知道 |
+| `## Verification` | **Close** | 验证要跑过才能写成可重跑的命令 |
+
+**`## Decision` 的两段式**:Think 时写"打算怎么做",Close 时校准为"实际做了什么"。
+
+**如果两者不一致,不要静默改写。** 把差异写进正文——计划与现实的偏差,本身往往是最有价值的一条决策信息。
+
+---
+
+## 逐节要求
+
+### `## Problem` —— 动机
+
+**要求**:必须能**脱离方案独立成立**。读者只读这一节,就该明白为什么值得做。
+
+**反模式**:
+
+| 反模式 | 为什么不行 |
+|---|---|
+| 在 Problem 里提到方案名或实现手段 | 循环论证——说明动机没想清,只是把方案重述了一遍 |
+| 写成"当前代码的缺陷清单" | 那是 bug 报告,不是动机 |
+| 一句话带过 | 读者无法判断这个决策是否还成立 |
+
+**自检**:把 `## Decision` 整节删掉,`## Problem` 还读得通吗?读不通就重写。
+
+### `## Decision` —— 做法
+
+**要求**:现在时,描述**已经采用的做法**。如果变更还在进行中,写"将要采用的做法"并保持它随后更新为事实。
+
+**反模式**:
+
+- 写成任务清单(那是 `tasks.md`)
+- 复述 `design.md` 的实现细节(那是 `design.md`)
+- 用"我们计划"而不说"我们决定"
+
+### `## Alternatives considered` —— 备选(强制)
+
+**要求**:每个**真实存在过**的备选一段,加粗开头,说明它**为什么输了**。
+
+```markdown
+**新增 year 字段到条目数据。** 冗余且需要同步维护——`date` 已是唯一来源,
+派生成本为零,多一个字段就多一处会不一致的地方。
+```
+
+**反模式**:
+
+| 反模式 | 为什么不行 |
+|---|---|
+| **稻草人备选** | 编一个明显更差的选项来凑数。这会让真实读者对整个文档失去信任 |
+| 只列备选,不说为什么输 | 等于没写——读者无法判断它现在是否仍然输 |
+| 把"什么都不做"当默认备选 | 除非当时真的认真考虑过维持现状,否则它只是修辞 |
+| 备选写成一堆标签 | 没有推理链,未来无法复用 |
+
+**"什么都不做"什么时候是真的备选**:当维持现状确实是一个被权衡过的选项时(例如"暂不修复这个边界,先观察")。
+
+**没有可记录的备选时**,写这一行注释而不是编造:
+
+```markdown
+<!-- alternatives-not-recorded -->
+```
+
+宁可承认"当时没记录",也不许发明一个假备选。**读者读到一条备选时,必须能相信它真的发生过。**
+
+### `## Consequences` —— 代价
+
+**要求**:同时写清**买到了什么**和**付出了什么**。包含已知限制。
+
+**反模式**:
+
+- 只写收获(那是营销文案,不是档案)
+- 不写已知限制("目前不支持 X")
+- 不写被放弃的能力
+
+**这是全文第二有价值的一节。** 未来维护者最常需要判断的正是"这个代价现在还能接受吗"。
+
+### `## Verification` —— 验证
+
+**要求**:写**可重跑的命令**,或**明确的人工步骤**。并且**标明哪些是只读的、哪些有副作用**。
+
+```markdown
+**只读(可直接跑)**
+- `grep -c 'id="year-filter"' knowledge-index.html` → 1
+- `bash -n scripts/update-knowledge-index.sh` → exit=0
+
+**有副作用(会重写文件,收尾时不必跑)**
+- `bash scripts/update-knowledge-index.sh`,然后复跑上面两条
+
+**人工**
+- 选择 2026,只显示 date 以 2026 开头的条目
+```
+
+**为什么必须分**:收尾检查发生在变更即将落地的时候,**那时最不愿意再改文件**。如果把最有说服力的验证写成有副作用的命令,执行者只有两个选择——跑(有风险)或者跳(失去验证)。
+分开之后,只读的那部分**每次都能跑**。
+
+**反模式**:
+
+| 反模式 | 为什么不行 |
+|---|---|
+| `已确认年份筛选控件存在` | **结论不可重跑**。三个月后没人知道当时确认了什么 |
+| `手动测试一下` | 不是步骤,是托付 |
+| 只写"测试通过" | 哪个测试?覆盖率多少? |
+| 只读命令与有副作用命令混在一起 | 执行者要么全跑(有风险),要么全不跑(失去验证) |
+
+**判据**:换一个人拿着这一节,能不能在 5 分钟内重跑一遍——**而且不必担心它改坏什么?**
+
+---
+
+## 校准案例
+
+校准判断用真实案例,**不用字数阈值**。字数从来不是标准。
+
+### 值得写的备选(真实)
+
+来自 `devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md`:
+
+```markdown
+## 替代方案
+
+| 方案 | 被拒原因 |
+|------|---------|
+| YAML 全优先 | 字段名不一致（date vs created） |
+| 目录名全优先 | 标题中的语义信息在下划线转空格后丢失 |
+```
+
+只有 39 行,但它是本仓库 37 篇档案里**唯一**记录了备选的一篇——也是唯一读完之后还记得住内容的一篇。
+
+**注意它的形式**:两条备选,每条一句被拒理由,没有废话。**短不等于差。**
+
+### 应当补录备选(真实)
+
+`openspec/changes/add-year-filter/` 那次变更,实际发生过两条备选,但一条都没记:
+
+```markdown
+## Alternatives considered
+
+**引入第三方筛选组件(Select2 等)。** 为 4 行原生 `<select>` 代码引入依赖,
+与仓库"单文件静态 HTML"的约束冲突。
+
+**只改 knowledge-index.html,不改生成脚本。** 更快,但重建即丢功能——
+生成脚本才是真理源,这条诱惑在本次实现中差点导致返工。
+```
+
+第二条特别值得记:**它在现有的 `design.md` 里其实被写成了"架构审计:主要风险是……"**。
+风险的痕迹在,但它没有被记成一条可查、可复用的决策。**这就是备选被浪费的典型形态。**
+
+### 备选的粒度
+
+一条备选**值得记录**当且仅当:**它现在仍然可能被重新提出。**
+
+- "用 X 库"—— 如果 X 库还在、还流行,值得记
+- "用某个已下线的内部服务"—— 除非它是诱人的错误,否则不必记
+
+---
+
+## 与 ADR 的关系:`decision.md` 就是它
+
+**本仓库不另建 `adr/` 目录。`decision.md` 承担 ADR 的角色**——它的骨架(Problem / Decision / Alternatives considered / Consequences)本来就是 ADR 的形态。
+
+`grill-with-docs` 会在同时满足三个条件时提议创建 ADR:
+
+1. **难以逆转** —— 以后改主意的代价可观
+2. **缺少上下文会令人困惑** —— 未来读者会想"他们为什么这么做?"
+3. **源自真实权衡** —— 确实存在备选,并且有具体理由选了其中一个
+
+**在本流程里,这个提议的落点是 `decision.md`,不是 `docs/adr/` 或 `devflow/*/adr/`。**
+
+> **不要同时产出两份。** 同一决策只有一个权威——两份文档必然各自腐化,而且没人知道以哪边为准。
+
+当一个变更**只**满足部分条件(很日常、并不难逆转),仍然要写 `decision.md`——它是每个非平凡变更的义务。
+**ADR 三条件在这里的作用,是判断这篇笔记值不值得写深,而不是判断要不要写。**
+
+---
+
+## 与 DSH Agent Notes 的差异
+
+本格式参考了 DeepSeek Harness 的 `.agents/notes/` 范式,但有三处**简化**,原因是本仓库的约束不同:
+
+| | DSH Agent Notes | 本协议 | 为什么 |
+|---|---|---|---|
+| 生命周期 | 路径含 `{lifecycle}/{class}/`,需手动移动 | **路径由 OpenSpec 表达**(在 `changes/` = 进行中,在 `archive/` = 已完成) | 文件随 change 一起走,不需要自己维护生命周期 |
+| 词汇表 | `proposed/` 与 `implemented/` 有**两套不同的合法小节名**,由 gate 强制 | **单一骨架** | 两套骨架需要一次"翻转"动作,而翻转要靠记得;单骨架零维护 |
+| 多语言 | en + zh + `i18n.yaml` 三元组 + 哈希 | **单语** | 那是公开仓库的需求;本仓库少两个文件 |
+| `Status:` 行 | 强制,且与目录交叉校验 | **不需要** | 路径已经表达了状态,不引入需要同步的冗余字段 |
+
+**保留自 DSH 的**:强制备选、反稻草人规则("recorded, never invented")、以真实案例校准而非阈值、冻结归档不当作当前权威。
+
+**可选的升级路径**:如果将来发现"计划写在 `decision.md` 里但从未更新为事实"这个问题反复出现,
+可以引入 DSH 的两套骨架(`## Proposal` → `## Decision`),代价是需要一个收尾步骤负责翻转。
+在观察到这个问题之前不引入。
+
+---
+
+## 交付前自检
+
+写完 `decision.md` 后,逐条对照:
+
+- [ ] 删掉 `## Decision`,`## Problem` 还读得通吗?
+- [ ] `## Alternatives considered` 里的每一条,**当时真的被考虑过**吗?
+- [ ] 每条备选都写了**为什么输**吗?
+- [ ] `## Consequences` 同时写了收获和代价吗?
+- [ ] `## Verification` 里的每一项,换个人能在 5 分钟内重跑吗?
+- [ ] 有没有一句话在两个地方都是权威?(有就是错)
@@ -0,0 +1,130 @@
+# 三阶段契约
+
+本文件是三阶段的判断细则。**它只规定"怎么判断",不新增检查点**——检查只有收尾那一次。
+
+---
+
+## Think — 想清楚
+
+### 澄清:借用 grill-with-docs,但收窄范围
+
+**方法来自 `grill-with-docs`** —— 一次只问一个问题并等待回答、能通过探索代码回答的自己去探索、术语确认后立即写入 `CONTEXT.md`。这些不在这里重复。
+
+**范围由本流程收窄**:
+
+> `grill-with-docs` 自身的取向是 "interview me **relentlessly** … until we reach a shared understanding"。
+> **relentless 是对问题质量的,不是对数量的。**
+> 只问**答案会改变** `proposal.md` / `specs/` / `tasks.md` 的问题;不会改变产物的疑问,自己判断即可。
+
+**先自己查证,再问用户。** 查证时格外看两处——它们专门用来避免重复劳动:
+
+1. 搜 `devflow/rejected/` —— 这个方案是不是已经被否决过?
+2. 搜已归档的 `decision.md` —— 相关决策的历史理由是什么?
+3. 读相关代码 / 配置 / 测试;看 `openspec/specs/` 有没有既有规格
+4. **能复现的问题先复现**——一次成功的复现比一轮追问更有信息量
+
+**什么时候算够**:你能写出一份 proposal,别人读了知道要做什么、不做什么。**没有"至少 N 个问题"的要求**——问题数不是质量指标。
+
+### 上下文读取顺序
+
+```text
+devflow/glossary/CONTEXT.md          ← 术语,先对齐语言
+devflow/rejected/                    ← 有没有被否决过的相似方案
+已归档的 decision.md                 ← 有没有相关的历史决策
+openspec/specs/                      ← 相关的既有能力规格
+```
+
+**第二步和第三步最重要。** 一个已经被否决过的方案,如果你不知道,就会重新提出一遍、重新争论一遍——这正是决策档案存在的理由。
+
+### 确认点 1 的汇报格式
+
+**向用户汇报时不超过 10 行:**
+
+- 方案方向(1–2 句)
+- 关键假设(没有验证、但方案依赖它的部分)
+- 主要风险
+- **放弃的备选**(1–2 条,连同为什么)
+- 请求实现授权
+
+**不要**复述 proposal、不要列产物清单、不要贴对齐表格。用户要的是判断依据,不是工作汇报。
+
+---
+
+## Build — 做出来
+
+### 分步实现与验证
+
+按 `tasks.md` 的纵向切片推进。**每完成一层先验证,再进下一层**——一次写完再验,出了问题无法定位是哪一层。
+
+第一个切片完成后,对照 `specs/` 检查一次:验收场景是否真的成立。**规格写得含糊会在这里第一次暴露。**
+
+### 冲突三分法的判断细则
+
+先分类,再动手。分类的错误比不分类更糟。
+
+**怎么区分"规格不准"和"代码偏离"**:问一句——**"如果完全按规格做出来,行为对不对?"**
+
+| 回答 | 分类 | 处理 |
+|---|---|---|
+| 对,但我没按规格做 | **代码偏离** | 改代码,不动 OpenSpec |
+| 不对,规格本身就写错了 | **规格不准** | 暂停,改 OpenSpec,再继续 |
+| 说不清 / 涉及设计方向 | **不确定** | 暂停,问用户 |
+
+**"不确定"这一类必须真的停下来问。** 判断设计方向是用户的权力,不是 agent 可以代劳的——
+把设计问题当成实现问题自行消化,是返工最常见的来源。
+
+冲突的分类、证据和处置结果写进 `decision.md` 的正文。
+
+---
+
+## Close — 收好尾
+
+### 补齐 decision.md
+
+Think 阶段已经写下了 `## Problem` 和 `## Alternatives considered`。Close 要补的是后三节:
+
+**`## Decision`** —— 校准为**实际发布的做法**(现在时)。
+
+> Think 时写的是"打算怎么做",Close 要把它改成"实际做了什么"。
+> **如果两者不一致,不要偷偷改成后者**——把差异写出来,它本身就是有价值的决策记录。
+
+**`## Consequences`** —— 必须同时写**收获**和**代价**,包括已知限制。
+
+只写收获的是营销文案,不是档案。未来维护者最需要判断的,恰恰是"这个代价现在还接受得了吗"。
+
+**`## Verification`** —— 写成**可重跑的命令**或**明确的人工步骤**。
+
+| 不写 | 写 |
+|---|---|
+| 已确认年份筛选控件存在 | `grep -c 'year-filter' knowledge-index.html` → ≥1 |
+| 手动测试一下 | 选择 2026,只显示 date 以 2026 开头的条目 |
+
+判据:换一个人拿着这一节,能不能在 5 分钟内重跑一遍?
+
+格式细则与校准案例见 `decision-note.md`。
+
+### 收尾检查
+
+三步,一次做完:
+
+1. `decision.md` 存在
+2. 含 `## Alternatives considered`,或显式的 `<!-- alternatives-not-recorded -->`
+3. `## Verification` 里没有不可重跑的结论
+
+**豁免**:纯机械或局部编辑(不改变行为、契约、结构、流程或理由)。豁免要**显式**——在 `decision.md` 或提交信息里写出来,让"跳过"是有意识的选择。
+
+---
+
+## 中断与恢复
+
+**流程状态全部在文件里,不依赖对话记忆。** 换会话、隔天继续时,按下面的顺序读一下就知道停在哪:
+
+| 观察到 | 当前在 |
+|---|---|
+| 没有 `openspec/changes/<slug>/` | Think 之前 |
+| 有 `proposal.md`,但 `decision.md` 缺 `## Problem` | Think 进行中 |
+| 有 `proposal.md` 和 `decision.md`,但没有实现授权 | **确认点 1** |
+| 有实现,但 `decision.md` 缺 `## Decision` / `## Consequences` / `## Verification` | Close 进行中 |
+| `decision.md` 五节齐全 | 收尾检查 + 确认点 2 |
+
+**恢复时不重新提问已经解决的问题。** 先读 `decision.md` 和 `proposal.md`——已经确认过的内容就在里面。
@@ -1,6 +1,6 @@
 ---
 name: sm-flow
-description: OpenSpec-first 的结构化工程开发协议层 harness。编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用。
+description: OpenSpec-first 工程流程 harness。仅在用户显式调用 /sm-flow、/sm-flow explore、/sm-flow apply、/sm-flow archive，或明确要求使用 sm-flow 流程时使用；不要根据需求类型自动触发。
 ---

 # SM Flow
@@ -9,6 +9,15 @@ SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周

 sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。

+## 触发规则
+
+只在用户显式调用时使用 sm-flow：
+
+- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。
+- 用户用自然语言明确要求"使用 sm-flow"、"走 sm-flow 流程"或等价表达。
+
+不要根据需求类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。
+
 ## 四层架构

 ```
@@ -30,10 +39,10 @@ sm-flow        → 编排层（harness）：阶段、门控、产物约束、人

 1. **OpenSpec 是唯一执行真理源**。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。
 2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
-3. **不得跳过 grill**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。
+3. **不得跳过 grill**。必须按 `references/scales.md` 的当前分档要求完成澄清或验证。
 4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
 5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
-6. **子 skill 必须显式调用**。每个阶段指定的子 skill 必须显式调用；如果子 skill 不存在，流程失败，不得静默跳过或降级执行。
+6. **能力来源必须显式声明**。每个阶段先声明使用外部子 skill / OpenSpec CLI / sm-flow 内置协议；外部能力不可用时可使用 `references/fallbacks.md` 的内置协议，但必须标注为 fallback。若外部能力和内置协议都不可用，流程失败。

 每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。

@@ -48,11 +57,26 @@ sm-flow        → 编排层（harness）：阶段、门控、产物约束、人

 用户也可以用自然语言指定从某个阶段继续，例如"ops-message-support 的 grill 已经做完了，继续"。harness 识别意图后，自动补做最小前置检查，然后从指定阶段继续。

+## 可见 Checkpoint
+
+内部阶段不是用户 API。对用户汇报进度时，默认只暴露 4 个 checkpoint：
+
+| Checkpoint | 覆盖内部阶段 | 用户可见含义 |
+|---|---|---|
+| Discover | clarify + context + propose + grill | 澄清目标、读取 devflow、形成轻量 proposal、解决关键问题 |
+| Commit | specify + audit + commit | 补全 OpenSpec、做架构/产物对齐、生成 Committed OpenSpec |
+| Apply | apply | 基于 Committed OpenSpec 实现和验证 |
+| Archive | archive | 回填 devflow、汇报验收、询问是否归档 OpenSpec |
+
+除非用户要求看细节，进度汇报、暂停点和恢复提示应使用 checkpoint 名称，而不是逐个暴露 9 个内部阶段。内部阶段仍按顺序执行，并以 `references/phase-contracts.md` 为准。
+
 ## 首次加载

 执行前只读取当前任务需要的 reference 文件：

- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。
+- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`；如果外部 OpenSpec 能力或子 skill 不可用，再补读 `references/fallbacks.md`。
+- 判断或执行 `micro / standard / complex` 分档时，读取 `references/scales.md`；其它文件不得重复定义分档细节。
+- 当 checkpoint / gate / fallback / Draft / Committed 等术语含义不清，或需要统一对用户说明时，读取 `references/glossary.md`。
 - 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
 - archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。

@@ -11,8 +11,8 @@ Archive 阶段必须按以下顺序执行，不得跳过或重排：
 - [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
      （从 proposal.md 提取：背景、目标、范围、非目标）
      
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/evidence.md`
-      （从 decisions.md 提取：evidence-driven 记录）
+- [ ] 按 `references/scales.md` 的当前分档决定是否创建 `devflow/projects/YYYY-MM-DD-{slug}/evidence.md`
+      （创建时从 decisions.md 提取 evidence-driven 记录）
      
 - [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
      （整理为最终版：关键决策、权衡、风险）
@@ -23,7 +23,7 @@ Archive 阶段必须按以下顺序执行，不得跳过或重排：
 ### Step 2: 更新索引（必需）

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

 ### Step 3: 标记 OpenSpec（必需）

@@ -53,10 +53,10 @@ Archive 阶段必须按以下顺序执行，不得跳过或重排：
 devflow/projects/YYYY-MM-DD-{slug}/
 ```

-archive 阶段创建以下文件：
+archive 阶段按 `references/scales.md` 的当前分档创建以下文件：

 - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。
+- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取；是否独立创建按 `references/scales.md` 执行。
 - `decisions.md`：保持为最终版，整理格式。
 - `acceptance.md`：从实现结果和验证结果提取。

@@ -77,11 +77,7 @@ archive 阶段创建以下文件：

 ## 产物分档

-| 分档 | 适用场景 | 必须文件 | 扩展文件 |
-| --- | --- | --- | --- |
-| `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` |
+分档的适用场景和必须文件见 `references/scales.md`。本文件只定义 archive 阶段的创建顺序、提取映射和索引规则。

 ## 提取映射

@@ -0,0 +1,49 @@
+# 内置执行协议
+
+本文件只在外部 OpenSpec CLI 或子 skill 不可用时使用。fallback 不是跳过阶段，而是由 sm-flow 用文件方式完成同等最小产物。每次使用 fallback 都必须写入 `decisions.md` 或 `acceptance.md`，说明能力来源、缺失能力、影响和剩余风险。
+
+## 通用规则
+
+- 优先使用外部能力；只有不可用、不可发现或无法在当前环境调用时才使用内置协议。
+- 不得因为使用 fallback 跳过 context、grill、commit、apply 授权或 archive 确认。
+- fallback 产物仍写入 `openspec/changes/{slug}/` 和 `devflow/projects/YYYY-MM-DD-{slug}/`。
+- 如果内置协议也无法满足阶段退出条件，暂停并向用户说明阻塞项。
+
+## grill 内置协议
+
+- 建立 question pool，至少覆盖术语、边界、验收；涉及参考实现或项目基础设施时加入技术实现问题。
+- 将问题标记为 `evidence-driven` 或 `user-interview`。
+- 先查证 evidence-driven 问题并汇报结论，再逐个询问 user-interview 问题。
+- 按 `references/scales.md` 的当前分档满足 grill 要求。
+- 将 question pool、证据结论、用户原话和确认状态写入 `decisions.md`；影响实现的结论回写 `proposal.md`。
+
+## openspec 提案内置协议
+
+- 在 `openspec/changes/{slug}/` 创建或更新：
+  - `proposal.md`：问题、方案、范围、非目标、上下文约束、风险。
+  - 设计产物：实现设计、接口影响、关键决策、架构风险；形式按 `references/scales.md` 的当前分档要求执行。
+  - `specs/*/spec.md` 或等价 functional spec：描述用户可观察行为和验收场景。
+  - `tasks.md`：按可执行切片拆分任务，并给每项写可验证验收标准。
+- 运行 cross-artifact 对齐检查：proposal → 设计产物 → specs → tasks。
+- 如果发现 gap，先修正 OpenSpec，再进入 commit。
+
+## audit 内置协议
+
+- 用 5 句话以内说明模块链路、数据所有权、跨模块依赖、架构风险和是否需要回写 OpenSpec。
+- 如果风险影响实现，修正设计产物或 `tasks.md`。
+- 将结论写入 `decisions.md`。
+
+## openspec apply 内置协议
+
+- 只依据 Committed OpenSpec 的 specs/tasks 实现；devflow 只作上下文参考。
+- 开始前检查 `.committed` 文件；缺失则返回 commit。
+- 如触发 pre-apply checkpoint，先阅读参考实现、grep 项目基础设施模式，并把技术栈清单写入 `decisions.md`。
+- 按 tasks 的纵向切片实现、验证并更新任务状态。
+- 发现冲突时按三类处理：OpenSpec 不准则修 OpenSpec，代码偏离则修代码，不确定则暂停等用户确认。
+
+## openspec archive 内置协议
+
+- 不删除或移动 OpenSpec change；只标记归档准备状态。
+- 完成 devflow 回填、更新 `devflow/index.md`、创建 `.archive-ready`。
+- 向用户汇报已创建文件、验证分类、剩余风险，并询问是否需要真实 OpenSpec archive。
+- 如果外部 archive 能力仍不可用，在 `acceptance.md` 标记 `accepted-unarchived`。
@@ -0,0 +1,21 @@
+# 术语表
+
+本文件统一 sm-flow 协议中的核心词。优先使用这些词，避免同一概念多种说法。
+
+| 术语 | 含义 | 使用边界 |
+| --- | --- | --- |
+| sm-flow | 协议层 harness | 编排 OpenSpec 生命周期，不替代 OpenSpec |
+| OpenSpec | 当前变更的执行真理源 | apply 只能依据 Committed OpenSpec |
+| devflow | 长期记忆和上下文层 | 提供术语、历史决策、验收记录，不直接指挥实现 |
+| checkpoint | 用户可见检查点 | 默认只暴露 Discover / Commit / Apply / Archive |
+| gate | 硬门控 | 不满足就不能进入下一关键动作，如 commit gate |
+| Draft OpenSpec | 讨论和审计对象 | propose/specify 期间产生，不能直接 apply |
+| Committed OpenSpec | 已通过 commit gate 的 OpenSpec | apply 的唯一执行依据 |
+| fallback | 内置执行协议 | 外部 OpenSpec CLI 或子 skill 不可用时使用，必须标注 |
+| decisions.md | 过程日志 | clarify 到 apply 期间记录问题、证据、决策、冲突和回写 |
+| .committed | commit gate 标记文件 | 存在才可进入合规 apply |
+| .archive-ready | archive 准备标记文件 | 表示 devflow 已回填，等待用户确认是否 archive |
+| Discover | 用户可见 checkpoint | 覆盖 clarify + context + propose + grill |
+| Commit | 用户可见 checkpoint | 覆盖 specify + audit + commit |
+| Apply | 用户可见 checkpoint | 覆盖 apply |
+| Archive | 用户可见 checkpoint | 覆盖 archive |
@@ -27,13 +27,14 @@
   - `/sm-flow apply [change]`：只执行，检查 commit gate → apply。
   - `/sm-flow explore`：带上下文的探索模式，不走标准阶段链。
   - `/sm-flow archive [change]`：收尾，回填 devflow + 归档确认。
+   - 明确要求"使用 sm-flow"或"走 sm-flow 流程"：按显式调用处理。
   - 自然语言指定阶段继续：识别意图后，自动补做最小前置检查，然后从指定阶段继续。
 2. 判断启动模式：
   - 完整模式：用户提供粗略想法或初始 PRD。
   - Research 模式：用户已有 research，需要转成或修正 OpenSpec。
   - PRD 文件模式：用户提供已有 PRD 路径。
   - 恢复模式：用户希望从某个阶段继续（补做最小前置检查）。
-   - 快速模式：小改动，合并 gate（见下文）。
+   - 快速模式：小改动，合并 gate；具体分档规则见 `references/scales.md`。
 3. 如果缺少 `devflow/`，初始化：
   - `devflow/projects/`
   - `devflow/glossary/CONTEXT.md`
@@ -42,7 +43,25 @@
 5. 检查 OpenSpec 和子 skill 是否可用：
   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。
   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。
-6. 如果 OpenSpec 不可用，不要直接绕过；使用内置执行协议（见 `references/fallbacks.md`），并在 apply 前向用户说明。
+6. 如果 OpenSpec 或子 skill 不可用，不要静默跳过；使用内置执行协议（见 `references/fallbacks.md`），并在当前 checkpoint 说明 fallback 来源、影响和剩余风险。
+
+## 进度汇报
+
+用户可见进度默认折叠为 4 个 checkpoint：
+
+| Checkpoint | 内部阶段 |
+| --- | --- |
+| Discover | clarify + context + propose + grill |
+| Commit | specify + audit + commit |
+| Apply | apply |
+| Archive | archive |
+
+汇报规则：
+
+- 面向用户时优先使用 checkpoint 名称，不逐个汇报 9 个内部阶段。
+- 内部阶段只在 checkpoint 摘要中作为证据列出，例如"Discover 已完成：读取了 devflow、生成 proposal、解决 2 个问题"。
+- 只有发生阻塞、冲突、fallback、用户要求继续某个内部阶段，或需要解释恢复位置时，才暴露内部阶段名。
+- 当前分档的汇报压缩规则见 `references/scales.md`；无论分档如何，都不要把内部阶段名当作用户操作入口。

 ## 项目标识规则

@@ -63,7 +82,7 @@ Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec
 **最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）：

 - `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。
- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态。
+- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态；分档要求见 `references/scales.md` 和 `references/archive-rules.md`。
 - `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。

 **按需产物**（archive 阶段按需创建）：
@@ -75,28 +94,17 @@ Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec
 - `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用。
 - `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用。

-**规模分档**：
-
- `micro`：小且低风险，gate 合并（见快速模式），最终档案同 standard。
- `standard`：默认模式。
- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加扩展产物。
+**规模分档**：`micro / standard / complex` 的唯一规则源是 `references/scales.md`。

 ## 快速模式

-快速模式适用于小而低风险的变更。它合并 gate 而不仅仅是压缩产物：
-
-```
-standard 流程：clarify → context → propose checkpoint → grill → specify → audit checkpoint → commit
-micro 流程：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题） → commit（简化检查）
-```
-
-micro 的定位：**gate 变少但保留最关键的**（grill 最小澄清 + commit gate）。
+快速模式适用于 `references/scales.md` 定义的 micro 变更。它合并 gate 而不仅仅是压缩产物；具体覆盖规则见 `references/scales.md`。

 无论什么模式，以下内容必须保留：

 - context 最小上下文收集：至少检查 glossary 和相关 ADR。
- grill 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报。
- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
+- grill 最小澄清：按 `references/scales.md` 当前分档要求执行；evidence-driven 结论仍需汇报。
+- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行；完整性检查按 `references/scales.md` 当前分档要求执行。
 - apply 仍由 OpenSpec tasks/specs 驱动执行。
 - archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。

@@ -104,8 +112,9 @@ micro 的定位：**gate 变少但保留最关键的**（grill 最小澄清 + co

 只有同时满足以下条件，流程才算完成：

- OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态。
+- 用户可见的 Discover、Commit、Apply、Archive checkpoint 已完成，或未完成项已明确标记为暂停/不适用。
+- OpenSpec proposal、设计产物、specs、tasks 已按当前分档生成或更新到可执行状态。
 - 实现或规划工作已完成，且执行依据来自 OpenSpec。
 - 已运行验证，或已记录未运行验证的原因。
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md。
+- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案。
 - 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。
@@ -4,6 +4,18 @@

 执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive。

+## 目录
+
+- clarify — 入口澄清
+- context — 上下文收集
+- propose — 轻量 propose
+- grill — 人类对齐澄清
+- specify — 细化 + 对齐
+- audit — 架构审计
+- commit — Commit OpenSpec
+- apply — OpenSpec 执行
+- archive — 回填 + 归档
+
 ## clarify — 入口澄清

 **进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。
@@ -13,7 +25,7 @@
 - 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
 - 如果输入过于模糊，最多追加三轮聚焦问题。
 - 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
- 如果需要判断 `micro / standard / complex` 分档，补读 `references/operating-rules.md`。
+- 如果需要判断 `micro / standard / complex` 分档，补读 `references/scales.md`。

 **退出条件**：
 - 问题可以用 1-2 句话说清楚。
@@ -36,7 +48,7 @@
 - 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
 - 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
 - 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。
+- 记录哪些上下文会影响 OpenSpec proposal、设计产物、specs 或 tasks。
 - 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。

 **退出条件**：
@@ -70,13 +82,13 @@

 **Human checkpoint**：
 - 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。
- 询问是否继续进入 grill 澄清阶段；用户明确要求"全自动执行"时可跳过等待。
+- 作为 Discover checkpoint 的中间状态汇报；询问是否继续完成 Discover 的人类澄清部分。用户明确要求"全自动执行"时可跳过等待。

 ## grill — 人类对齐澄清

 **进入条件**：propose 已有轻量 proposal.md。

-**显式子 skill**：`grill-with-docs`。进入本阶段必须调用 `.agents/skills/grill-with-docs/SKILL.md`。
+**能力来源**：优先使用 `grill-with-docs`；不可用时使用 `references/fallbacks.md#grill-内置协议`，并在 `decisions.md` 标注 fallback。

 **动作**：
 - 优先使用 `grill-with-docs`。
@@ -101,7 +113,7 @@

 **退出条件**：
 - question pool 已建立并覆盖当前 change 所需维度。
- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
+- 已满足 `references/scales.md` 中当前分档的 grill 要求。每个问题都必须记录属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
 - 没有未解决或代理代确认的 user-interview 问题。
@@ -117,20 +129,20 @@

 **Human checkpoint**：
 - 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。
- 询问是否继续进入 specify 细化阶段。
+- 汇报 Discover checkpoint 完成情况，并询问是否继续进入 Commit checkpoint。

 ## specify — 细化 + 对齐

 **进入条件**：grill 已退出，需求已通过澄清稳定下来。

-**显式子 skill**：`openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；`to-prd`（按需生成 PRD）。进入本阶段必须先声明调用方式。
+**能力来源**：优先使用 `openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；按需使用 `to-prd`。进入本阶段必须先声明调用方式；外部能力不可用时使用 `references/fallbacks.md#openspec-提案-内置协议`，并在 `decisions.md` 标注 fallback。

 **动作**：
- 基于已稳定的 proposal.md 补全 design.md、specs/、tasks.md：
-  - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需补全 design/specs/tasks"。
-  - 如果不可用，执行 `references/fallbacks.md#openspec-提案-降级`。
+- 基于已稳定的 proposal.md 补全设计产物、specs/、tasks.md：
+  - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需按当前分档补全设计产物/specs/tasks"。
+  - 如果不可用，执行 `references/fallbacks.md#openspec-提案-内置协议`。
 - 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级。
+- 独立 PRD 是否需要按 `references/scales.md` 的当前分档和用户要求判断。
 - 用 grill 阶段的 decisions.md 记录增强 OpenSpec 产物：确保 design/specs/tasks 反映所有已确认的决策。
 - **显式 cross-artifact 对齐检查**——在 checkpoint 中输出对齐检查表：
  - `brief/prd` 中的目标、范围、非目标和验收预期 → `proposal` 是否覆盖。
@@ -147,14 +159,14 @@
 - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。

 **退出条件**：
- `design.md`、`specs/`、`tasks.md` 存在且与 proposal 对齐。
+- OpenSpec 细化产物存在且与 proposal 对齐；产物形态按 `references/scales.md` 的当前分档要求执行。
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。
 - 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。
 - 所有已知冲突已修正或等待用户决策。

 **输出**：
- 完整的 Draft OpenSpec：proposal.md + design.md + specs/ + tasks.md。
+- Draft OpenSpec：按 `references/scales.md` 的当前分档要求生成 proposal、设计、specs 和 tasks。
 - `brief.md`，以及按需创建的 `prd.md`。
 - cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。
 - 必要的 OpenSpec 修正。
@@ -163,7 +175,7 @@

 **进入条件**：specify 已退出，完整 OpenSpec 产物已存在。

-**显式子 skill**：`zoom-out`。进入本阶段必须调用 `.agents/skills/zoom-out/SKILL.md`。
+**能力来源**：优先使用 `zoom-out`；不可用时使用 `references/fallbacks.md#audit-内置协议`，并在 `decisions.md` 标注 fallback。

 **动作**：
 - 画出输入 → 处理 → 输出的模块链路。
@@ -175,20 +187,20 @@

 **退出条件**：
 - 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。
- OpenSpec design/tasks 已反映会影响实现的架构审计结论。
+- OpenSpec 设计产物/tasks 已反映会影响实现的架构审计结论。

 **输出**：
 - 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。
- 必要的 OpenSpec design/tasks 修正。
+- 必要的 OpenSpec 设计产物/tasks 修正。

 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
- 询问是否进入 commit。
+- 作为 Commit checkpoint 的中间状态汇报；询问是否继续完成 commit gate。

 ## commit — Commit OpenSpec

 **进入条件**：
- grill 已解决术语、边界、验收三个维度的高价值问题。
+- grill 已满足 `references/scales.md` 中当前分档要求。
 - 所有 `user-interview` 问题都已获得用户显式确认。
 - audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。
 - Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
@@ -198,7 +210,7 @@
 - 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
 - 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
 - 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
- 复核 cross-artifact 对齐：`brief/prd → proposal → design → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。
+- 复核 cross-artifact 对齐：`brief/prd → proposal → 设计产物 → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。
 - 检查 `decisions.md` 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。
 - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
 - 检查接口影响是否已按 L1/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
@@ -207,14 +219,14 @@

 **退出条件**：
 - Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
- **文件完整性检查**（必须全部通过）：
-  - [ ] `proposal.md` 存在，包含问题描述（至少 50 字）、建议方案（至少 100 字）、范围/非目标
-  - [ ] `design.md` 存在，包含架构设计（文字或图）、数据结构定义（至少 1 个）、关键决策记录（至少 2 条）
-  - [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
-  - [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准
+- **文件完整性检查**（按 `references/scales.md` 的当前分档要求执行）：
+  - [ ] proposal 存在，且足以说明问题、建议方案、范围和非目标。
+  - [ ] 设计产物存在，形式符合当前分档要求。
+  - [ ] specs 存在，且表达用户可观察行为。
+  - [ ] tasks 存在，且任务可执行、验收标准可验证。
 - **一致性检查**（必须通过）：
-  - [ ] proposal 中的核心概念在 design 中有对应设计
-  - [ ] design 中的关键决策在 tasks 中有对应实现任务
+  - [ ] proposal 中的核心概念在设计产物中有对应设计
+  - [ ] 设计产物中的关键决策在 tasks 中有对应实现任务
  - [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
 - **标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
 - 所有 preflight 风险已消除或明确记录为已接受。
@@ -225,28 +237,28 @@

 **Human checkpoint**：
 - 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
- 询问是否进入 apply；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
+- 汇报 Commit checkpoint 完成情况，并询问是否进入 Apply checkpoint；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
 - 不得把 grill 的单个决策确认当作本 checkpoint 的授权。

 ## apply — OpenSpec 执行

 **进入条件**：
- `openspec/changes/{slug}/` 中 proposal/design/specs/tasks 已通过 commit，成为 Committed OpenSpec。
+- `openspec/changes/{slug}/` 中 proposal、设计产物、specs、tasks 已通过 commit，成为 Committed OpenSpec。
 - **前置门控检查**（硬约束）：
  - 检查 `openspec/changes/{slug}/.committed` 文件是否存在
  - 如不存在，执行以下流程：
    1. 汇报：Draft OpenSpec 未通过 commit 检查
    2. 列出缺失的 checkpoint 项（文件完整性、一致性检查）
-    3. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
+    3. 询问用户：是否补做 commit 检查；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`，且本次流程不得视为合规 sm-flow apply
 - commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。
 - devflow 与 OpenSpec 没有未解决冲突。
 - 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。

-**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须调用指定子 skill，不得静默跳过。
+**能力来源**：优先使用 `openspec-apply-change`；不可用时使用 `references/fallbacks.md#openspec-apply-内置协议`，并在 `decisions.md` 标注 fallback。遇到 bug/不确定行为时优先使用 `diagnose`；需要测试驱动时优先使用 `tdd`。不可用时执行对应最小协议并记录原因，不得静默跳过。

 **动作**：

-### Pre-apply Checkpoint（15-20 分钟）
+### Pre-apply Checkpoint

 **触发条件**：当 OpenSpec 涉及以下任一情况时必须执行
 - design 或 tasks 中提到"参考 XXX 实现"
@@ -254,12 +266,12 @@
 - 技术栈不熟悉或第一次在该项目实现类似功能

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

-2. **Grep 关键技术栈**（约 5 分钟）
+2. **Grep 关键技术栈**
   - 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范）
   - 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板）
   - 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具）
@@ -273,11 +285,11 @@
   - 识别需要新建的工具类或基础设施

 **输出要求**：
- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节 ✅
- 已列出所有参考实现的文件路径 ✅
- 已识别需要新建的工具类/基础设施 ✅
+- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节。
+- 已列出所有参考实现的文件路径。
+- 已识别需要新建的工具类/基础设施。

-**快速模式**：micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单。
+**按风险执行**：执行深度按 `references/scales.md` 的当前分档和实现风险决定；退出判断以清单是否足以指导实现为准。

 ### 实现过程

@@ -299,9 +311,9 @@
 - 修改文件前遵守仓库指令，例如 `AGENTS.md`。

 **退出条件**：
- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md` ✅
+- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`。
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位 ✅
+- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位。
 - 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。
@@ -315,13 +327,13 @@

 **进入条件**：实现或规划工作已经达到可交接状态。

-**显式子 skill**：`openspec-archive-change` 在用户确认 archive 后调用；archive 回填由 `sm-flow` 执行。必须调用子 skill，不得静默跳过。
+**能力来源**：`openspec-archive-change` 在用户确认 archive 后优先调用；不可用时使用 `references/fallbacks.md#openspec-archive-内置协议`，并在 `acceptance.md` 标注 fallback。archive 回填由 `sm-flow` 执行。

 **动作**：
 - 遵循 `references/archive-rules.md`。
 - 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案：
  - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
-  - `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。
+  - `evidence.md`：按 `references/scales.md` 和 `references/archive-rules.md` 的当前分档要求处理。
  - `decisions.md`：保持为最终版，整理格式。
  - `acceptance.md`：从实现结果和验证结果提取。
 - 只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
@@ -331,7 +343,7 @@
 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。

 **退出条件**：
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
+- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
 - `devflow/index.md` 已包含或更新本项目条目。
 - 用户已被询问是否 archive OpenSpec change。

@@ -0,0 +1,42 @@
+# 分档规则
+
+本文件是 `micro / standard / complex` 的唯一规则源。其它文件只引用本文件，不重复定义分档细节。
+
+## standard 基准
+
+standard 是默认分档，适用于普通功能、明确但有一定实现范围的变更。
+
+- 用户可见 checkpoint：Discover → Commit → Apply → Archive。
+- OpenSpec 产物：`proposal.md`、独立 `design.md`、`specs/`、`tasks.md`。
+- grill：解决术语、边界、验收三个维度的高价值问题。
+- commit gate：检查 proposal、design、specs、tasks 的完整性和一致性。
+- devflow 档案：`brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。
+
+## micro 覆盖
+
+micro 适用于小改动、低风险、需求明确的变更。micro 是 standard 的减法，不是跳过流程。
+
+- checkpoint 可合并：Discover + Commit 可在无阻塞时合并汇报。
+- micro 内部流程压缩为：clarify+context 合并 checkpoint → 轻量 propose → grill → specify+commit 合并 checkpoint。
+- context 保留最小收集：至少检查 glossary 和相关 ADR。
+- grill 保留最小澄清：至少解决一个高价值问题，并记录术语、边界、验收三类是否明确；不明确项必须补问或标记风险。
+- OpenSpec 仍需要 `proposal.md`、`specs/`、`tasks.md`。
+- `design.md` 可不独立创建；允许在 `proposal.md` 或 `tasks.md` 中写等价设计小节。
+- `specs/` 和 `tasks.md` 可轻量，但必须表达可观察行为和可执行任务。
+- commit gate 仍必须通过，并创建 `.committed`。
+- devflow 档案至少包含 `brief.md`、`decisions.md`、`acceptance.md`；证据少时可并入 `brief.md` 或 `decisions.md`。
+- apply 仍只能依据 Committed OpenSpec。
+- archive 仍要轻量回填 devflow，并询问是否归档 OpenSpec。
+
+micro 不适用于接口影响不清、跨团队消费者、迁移/回滚、复杂状态机、长期架构决策或需求边界不清的变更；遇到这些情况应升级为 standard 或 complex。
+
+## complex 增量
+
+complex 适用于高风险、跨模块、需求不清、多人协作或长期架构影响明显的变更。complex 是 standard 的加法。
+
+- 需要更完整的 Discover：增加需求澄清、证据查证、范围确认和风险接受。
+- checkpoint 内可补充关键内部阶段结果，但不要把内部阶段名当作用户操作入口。
+- 按需创建 `prd.md`、`research.md`、`alignment.md`、接口文档、ADR 或 compound knowledge。
+- 接口影响、迁移、灰度、回滚、兼容性和消费者边界必须显式记录。
+- audit 需要覆盖模块链路、数据所有权、生命周期、耦合风险和 ADR 冲突。
+- archive 在 standard 档案基础上按需提炼长期 design、research、tasks、ADR 和 compound knowledge。
@@ -124,7 +124,7 @@

 - 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
 - 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更
+- 分类：OpenSpec 不准 / 代码偏离 / 不确定

 ## 证据

@@ -136,7 +136,7 @@

 - 决策：
 - 是否需要用户确认：是 / 否
- OpenSpec 回写：不需要 / 已回写 / 待回写
+- OpenSpec 回写：不需要 / 已回写 / 待回写 / 等待用户确认
 - 代码处理：
 - 验证方式：
 ```
@@ -353,8 +353,8 @@ specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"
 | 上游 → 下游 | 检查内容 | 状态 |
 |---|---|---|
 | brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap |
-| proposal → design | 范围、约束、关键承诺是否进入 design | 已对齐 / 存在 gap |
-| design → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
+| proposal → 设计产物 | 范围、约束、关键承诺是否进入 design.md 或等价设计小节 | 已对齐 / 存在 gap |
+| 设计产物 → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
 | specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap |

 ### Gap 详情（如有）
@@ -10,3 +10,5 @@
 | 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 |
+| 2026-07-05 | validate-sm-flow-explicit-trigger | sm-flow | explicit-trigger, scale-source, fallback, validation | `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/` | archived |
+| 2026-07-05 | validate-sm-flow-standard-change | sm-flow | standard-change, full-artifacts, evidence, validation | `openspec/archive/2026-07-05-validate-sm-flow-standard-change/` | archived |
@@ -0,0 +1,48 @@
+# Validate SM Flow Explicit Trigger Acceptance
+
+## Result
+
+Accepted and archived.
+
+## Static Validation
+
+- Trigger rule verification:
+  - `SKILL.md` frontmatter says sm-flow is only used for explicit `/sm-flow` commands or explicit natural-language requests.
+  - `SKILL.md` trigger section says task type alone must not auto-trigger sm-flow.
+  - `operating-rules.md` startup checks now include explicit natural-language requests.
+
+- Scale source verification:
+  - Scale definition scan found `standard`, `micro`, and `complex` definition headings and definition phrases only in `references/scales.md`.
+  - Other files refer to `references/scales.md` instead of redefining the scale rules.
+
+- Obsolete wording verification:
+  - No matches for minute/hour/second/timebox metrics.
+  - No matches for old skip semantics or old fixed `proposal.md + design.md` expression.
+  - No matches for old conflict wording targeted by this validation.
+
+## Script Validation
+
+- Passed: `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow`
+- Passed: reference integrity scan for `references/*.md`.
+
+## Browser Or Manual Validation
+
+- Not applicable. This change only modifies skill protocol text and validation records.
+
+## Unverified
+
+- Real external OpenSpec CLI integration was not executed because the current tool surface does not expose those child commands.
+- Forward-testing with an independent subagent was not run in this pass.
+
+## Fixed During Apply
+
+- Replaced remaining hard-coded `design.md` wording in phase/audit fallback rules where the protocol must respect scale-specific design artifacts.
+- Added explicit natural-language sm-flow requests to startup checks.
+
+## OpenSpec Archive
+
+- `.archive-ready` is present.
+- User confirmed archive.
+- Archived location: `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/`.
+- Status: `archived`.
+- Archive method: local filesystem archive following existing repository convention because external `openspec-archive-change` is not directly callable in the current tool surface.
@@ -0,0 +1,29 @@
+# Validate SM Flow Explicit Trigger Brief
+
+## Background
+
+`sm-flow` was simplified so it should only run on explicit user invocation. Related cleanup centralized scale rules, removed time-based metrics, and separated fallback/glossary details into references.
+
+## Goal
+
+Validate the current `sm-flow` design by running a real micro OpenSpec change through Discover, Commit, Apply, and Archive.
+
+## Scope
+
+- Validate `.agents/skills/sm-flow/SKILL.md`.
+- Validate `.agents/skills/sm-flow/references/*.md`.
+- Fix any protocol inconsistency found during validation.
+- Record fallback capability source because external OpenSpec commands are unavailable in the current tool surface.
+
+## Non-Goals
+
+- No business code changes.
+- No changes to the four visible checkpoints or nine internal phases.
+- No automatic trigger heuristics.
+- No historical archive rewrites.
+
+## Scale
+
+- Scale: `micro`.
+- Evidence is folded into `decisions.md`.
+- Linked OpenSpec change: `openspec/changes/validate-sm-flow-explicit-trigger/`.
@@ -0,0 +1,72 @@
+# Validate SM Flow Explicit Trigger Decisions
+
+## Capability Source
+
+- Discover: sm-flow built-in protocol.
+- Propose/specify/apply/archive: fallback protocol from `.agents/skills/sm-flow/references/fallbacks.md`.
+- Missing external capability: OpenSpec CLI and OpenSpec child skills are not directly callable from the current tool surface.
+- Impact: validation is file-based and static; it can verify current protocol text and artifacts but cannot exercise a real external OpenSpec command.
+- Remaining risk: future tool availability may require rechecking integration behavior.
+
+## Context
+
+- `devflow/index.md` contains related sm-flow history:
+  - `dev-flow-skill-evaluation`
+  - `sm-flow-v3-1-upgrade`
+  - `sm-flow-execution-hardening`
+- `devflow/glossary/CONTEXT.md` is project-level glossary and does not define sm-flow protocol terms.
+- Current validation change is new: `validate-sm-flow-explicit-trigger`.
+
+## Scale Decision
+
+- Scale: `micro`.
+- Reason: documentation/protocol validation only, no business code, no external interface contract change.
+- Interface impact: L1 internal documentation/protocol validation.
+- Micro constraints retained: proposal, specs, tasks, commit gate, apply verification, devflow archive, archive confirmation.
+
+## Question Pool
+
+| Question | Mode | Status | Result |
+| --- | --- | --- | --- |
+| Does top-level trigger text require explicit sm-flow invocation only? | evidence-driven | confirmed | `SKILL.md` frontmatter and trigger section both state explicit invocation only. |
+| Are scale definitions centralized in `references/scales.md`? | evidence-driven | confirmed | Scan for scale definition headings and definition phrases only matched `references/scales.md`. |
+| Are time/minute metrics absent from skill rules? | evidence-driven | confirmed | Obsolete time metric scan returned no matches. |
+| Does fallback usage remain explicit and recorded? | evidence-driven | confirmed | This file records fallback source, impact, and remaining risk. |
+| Is user confirmation needed for product scope? | user-interview | not required | User already requested this validation run; no unresolved product preference blocks this micro validation. |
+
+## Cross-Artifact Alignment
+
+| Link | Status | Notes |
+| --- | --- | --- |
+| brief/prd -> proposal | not applicable | Micro validation has no separate brief/prd before archive. |
+| proposal -> design artifact | aligned | Proposal contains inline micro design notes. |
+| design artifact -> specs | aligned | Specs cover explicit trigger, scale source, no time metrics, and fallback recording. |
+| specs -> tasks | aligned | Tasks include scans, validation, patching if needed, and archive handoff. |
+
+## Commit Gate
+
+- Passed.
+- Proposal explains why, what, scope, non-goals, inline design, and risks.
+- Specs describe observable validation behavior.
+- Tasks are executable and have validation evidence.
+- Cross-artifact alignment has no unresolved gap.
+- `.committed` created.
+
+## Apply Log
+
+- Validation found one consistency issue: `phase-contracts.md` still hard-coded `design.md` in specify/audit wording even though `scales.md` allows micro changes to use an equivalent inline design section.
+- Fix applied: changed those references to "设计产物" where the rule must respect the current scale.
+- Fix applied: `fallbacks.md` audit fallback now says to repair the design artifact instead of only `design.md`.
+- Fix applied: `operating-rules.md` startup checks now include explicit natural-language requests to use sm-flow.
+- Validation commands passed:
+  - `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow`
+  - reference integrity scan for `references/*.md`
+  - obsolete wording scan for time metrics, old skip semantics, old conflict wording, and fixed `design.md` expressions.
+  - scale definition duplication scan.
+
+## Archive Log
+
+- User confirmed OpenSpec archive.
+- External `openspec-archive-change` was not directly callable in the current tool surface.
+- Archived by moving the OpenSpec change to `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/`, matching existing repository archive convention.
+- `devflow/index.md` status updated to `archived`.
@@ -0,0 +1,33 @@
+# Validate SM Flow Standard Change Acceptance
+
+## Result
+
+Accepted and archived.
+
+## Static Validation
+
+- Scale rule centralization passed.
+- Obsolete wording scan passed.
+- Standard artifact completeness passed.
+- Cross-artifact alignment passed.
+
+## Script Validation
+
+- Passed: skill quick validation.
+- Passed: reference integrity scan.
+
+## Browser Or Manual Validation
+
+- Not applicable. This validation covers skill protocol files and OpenSpec/devflow records.
+
+## Unverified
+
+- External OpenSpec CLI integration.
+- Independent forward-testing by a separate agent.
+
+## OpenSpec Archive
+
+- User confirmed archive.
+- Archived location: `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`.
+- Status: `archived`.
+- Archive method: local filesystem archive following existing repository convention because external `openspec-archive-change` is not directly callable in the current tool surface.
@@ -0,0 +1,25 @@
+# Validate SM Flow Standard Change Brief
+
+## Background
+
+The micro validation confirmed the reduced path. This record validates the normal standard path, where independent design and separate evidence are required.
+
+## Goal
+
+Confirm that the current `sm-flow` skill supports a standard change with complete OpenSpec and devflow artifacts.
+
+## Scope
+
+- Validate standard artifact requirements.
+- Validate scale rule centralization.
+- Validate skill structure and reference integrity.
+
+## Non-Goals
+
+- No business code changes.
+- No archive move without user confirmation.
+- No complex migration, rollback, or cross-team interface test.
+
+## Linked OpenSpec
+
+`openspec/changes/validate-sm-flow-standard-change/`
@@ -0,0 +1,52 @@
+# Validate SM Flow Standard Change Decisions
+
+## Capability Source
+
+- This is an ordinary engineering validation, not an explicit sm-flow invocation.
+- External OpenSpec child commands are not directly callable in the current tool surface.
+- Validation uses file-based OpenSpec fixtures and static/script checks.
+
+## Scale Decision
+
+- Scale: `standard`.
+- Reason: this validation intentionally exercises the full normal artifact set: proposal, independent design, specs, tasks, and separate evidence.
+- Interface impact: L1 internal documentation/protocol validation.
+
+## Question Pool
+
+| Question | Mode | Status | Result |
+| --- | --- | --- | --- |
+| Does standard require independent `design.md`? | evidence-driven | confirmed | `references/scales.md` defines independent `design.md` for standard. |
+| Does standard require separate `evidence.md` in devflow? | evidence-driven | confirmed | `references/scales.md` defines `brief.md`, `evidence.md`, `decisions.md`, `acceptance.md`. |
+| Are standard scale definitions duplicated outside `scales.md`? | evidence-driven | confirmed | Scale definition scan matched complete scale definitions only in `references/scales.md`. |
+| Is user scope confirmation needed? | user-interview | not required | User asked to validate a regular change; no product scope choice is blocked. |
+
+## Cross-Artifact Alignment
+
+| Link | Status | Notes |
+| --- | --- | --- |
+| proposal -> design | aligned | Proposal asks for standard artifact validation; design defines standard artifact model. |
+| design -> specs | aligned | Specs require full OpenSpec artifacts, evidence archive, and centralized scale definitions. |
+| specs -> tasks | aligned | Tasks include fixture creation, validation scans, commit gate, and devflow records. |
+
+## Findings
+
+- Standard OpenSpec artifact completeness passed: `proposal.md`, independent `design.md`, spec file, and `tasks.md` exist.
+- Cross-artifact alignment passed: proposal -> design -> specs -> tasks.
+- Scale duplication scan passed.
+- Obsolete wording scan passed.
+- Skill quick validation passed.
+- Reference integrity scan passed.
+
+## Commit Gate
+
+- `.committed` created.
+- Status: committed standard validation fixture.
+
+## Archive Status
+
+- Devflow standard records created.
+- User confirmed OpenSpec archive.
+- External `openspec-archive-change` was not directly callable in the current tool surface.
+- Archived by moving the OpenSpec change to `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`, matching existing repository archive convention.
+- `devflow/index.md` status updated to `archived`.
@@ -0,0 +1,34 @@
+# Validate SM Flow Standard Change Evidence
+
+## Static Evidence
+
+- Scale definition scan found complete `standard / micro / complex` definition headings and definition phrases only in `.agents/skills/sm-flow/references/scales.md`.
+- Obsolete wording scan returned no matches for:
+  - minute/hour/second/timebox metrics
+  - old skip semantics
+  - old fixed `proposal.md + design.md` expression
+  - old conflict wording targeted by prior validation
+
+## Script Evidence
+
+- Passed: `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow`
+- Passed: `references/*.md` integrity scan.
+
+## Artifact Evidence
+
+- OpenSpec standard artifacts exist:
+  - `openspec/changes/validate-sm-flow-standard-change/proposal.md`
+  - `openspec/changes/validate-sm-flow-standard-change/design.md`
+  - `openspec/changes/validate-sm-flow-standard-change/specs/sm-flow-standard-change/spec.md`
+  - `openspec/changes/validate-sm-flow-standard-change/tasks.md`
+- Devflow standard artifacts exist:
+  - `brief.md`
+  - `evidence.md`
+  - `decisions.md`
+  - `acceptance.md`
+
+## Limits
+
+- This validation is static/file-based.
+- It does not run a real external OpenSpec CLI command.
+- It does not include independent subagent forward-testing.
@@ -0,0 +1 @@
+Devflow archive files are ready for validate-sm-flow-explicit-trigger.
@@ -0,0 +1 @@
+Committed OpenSpec for validate-sm-flow-explicit-trigger.
@@ -0,0 +1,44 @@
+# Validate SM Flow Explicit Trigger
+
+## Why
+
+Recent edits simplified `sm-flow` so it should only run when the user explicitly invokes it. The same cleanup also centralized scale rules in `references/scales.md`, removed time-based metrics, and split fallback/glossary concepts out of the top-level skill.
+
+This change validates those protocol decisions through a real micro `sm-flow` run instead of another informal review.
+
+## What Changes
+
+- Verify `sm-flow` only triggers on `/sm-flow`, `/sm-flow explore`, `/sm-flow apply`, `/sm-flow archive`, or an explicit natural-language request to use sm-flow.
+- Verify task type alone does not trigger `sm-flow`, even when the task mentions OpenSpec, devflow, cross-module work, or clarification.
+- Verify `micro / standard / complex` definitions live only in `references/scales.md`.
+- Verify the skill has no time/minute-based metrics.
+- Verify fallback usage is recorded when external OpenSpec capabilities are unavailable.
+
+## Design Notes
+
+- Scale: `micro`.
+- Interface impact: L1 internal documentation/protocol validation only.
+- No business code changes.
+- Independent `design.md` is intentionally omitted; this section is the micro design artifact.
+- OpenSpec CLI and external OpenSpec child skills are not directly callable in the current tool surface, so this run uses `references/fallbacks.md` and records that capability source in devflow.
+
+## Scope
+
+In scope:
+
+- `.agents/skills/sm-flow/SKILL.md`
+- `.agents/skills/sm-flow/references/*.md`
+- Validation OpenSpec and devflow records for this change
+
+Out of scope:
+
+- Business code
+- Rewriting historical OpenSpec archives
+- Changing the four visible checkpoints or nine internal phases
+- Adding automatic trigger heuristics
+
+## Risks
+
+- A future edit may duplicate scale rules outside `references/scales.md`.
+- The frontmatter description may drift from the top-level trigger rule.
+- Validation can prove current text consistency, but cannot force future agents to obey it without continued review.
@@ -0,0 +1,53 @@
+# sm-flow Explicit Trigger Spec
+
+## ADDED Requirements
+
+### Requirement: Explicit Trigger Only
+
+`sm-flow` SHALL be used only when the user explicitly invokes `/sm-flow`, `/sm-flow explore`, `/sm-flow apply`, `/sm-flow archive`, or clearly asks to use the sm-flow process in natural language.
+
+#### Scenario: Plain engineering request
+
+- **Given** a user asks for an engineering task that mentions OpenSpec, devflow, cross-module work, or clarification
+- **When** the user does not explicitly request sm-flow
+- **Then** the agent handles the task as ordinary engineering work
+- **And** the agent does not auto-trigger sm-flow based on task type
+
+#### Scenario: Explicit sm-flow request
+
+- **Given** a user invokes `/sm-flow` or clearly asks to use sm-flow
+- **When** the agent starts the process
+- **Then** the agent follows the visible checkpoints Discover, Commit, Apply, and Archive
+- **And** the internal phase order remains clarify, context, propose, grill, specify, audit, commit, apply, archive
+
+### Requirement: Scale Rules Have One Source
+
+The `micro / standard / complex` scale definitions SHALL be defined in `references/scales.md`; other files may only reference that file instead of redefining scale details.
+
+#### Scenario: Scale guidance is needed
+
+- **Given** a phase needs to choose or enforce a scale
+- **When** the rule is read
+- **Then** it points to `references/scales.md`
+- **And** no other reference file carries a competing full definition of the three scales
+
+### Requirement: No Time-Based Skill Metrics
+
+The skill SHALL NOT use minute, hour, second, or timebox metrics to define scale, effort, or validation thresholds.
+
+#### Scenario: Protocol text is scanned
+
+- **Given** the sm-flow skill files are scanned
+- **When** obsolete time metrics are searched
+- **Then** no matching scale or effort rule remains
+
+### Requirement: Fallback Capability Is Explicit
+
+When OpenSpec CLI or child skill capabilities are unavailable, `sm-flow` SHALL use `references/fallbacks.md` only as an explicit fallback and record the capability source in the current devflow process log.
+
+#### Scenario: External capability unavailable
+
+- **Given** OpenSpec child skills are not directly callable
+- **When** a change is still executed
+- **Then** the decisions log records fallback source, impact, and remaining risk
+- **And** the fallback does not skip context, grill, commit, apply, or archive gates
@@ -0,0 +1,26 @@
+# Tasks
+
+## 1. Discover
+
+- [x] 1.1 Read current `sm-flow` top-level trigger rule and relevant references.
+- [x] 1.2 Read `devflow/index.md` and glossary context for related history.
+- [x] 1.3 Classify this validation as `micro` and record capability fallback.
+
+## 2. Commit
+
+- [x] 2.1 Create micro OpenSpec proposal with inline design notes.
+- [x] 2.2 Create specs that express the observable validation expectations.
+- [x] 2.3 Create executable validation tasks.
+- [x] 2.4 Run cross-artifact alignment and create `.committed`.
+
+## 3. Apply
+
+- [x] 3.1 Scan `sm-flow` files for obsolete trigger, scale, time metric, and fallback wording.
+- [x] 3.2 Patch any discovered inconsistency in the skill files.
+- [x] 3.3 Run skill validation and reference integrity checks.
+
+## 4. Archive
+
+- [x] 4.1 Create micro devflow archive files.
+- [x] 4.2 Update `devflow/index.md`.
+- [x] 4.3 Create `.archive-ready` and ask whether to archive OpenSpec.
@@ -0,0 +1 @@
+Devflow archive files are ready for validate-sm-flow-standard-change.
@@ -0,0 +1 @@
+Committed OpenSpec for validate-sm-flow-standard-change.
@@ -0,0 +1,35 @@
+# Design
+
+## Scale
+
+Scale: `standard`.
+
+Rationale: this validation has a clear target and no business-code risk, but it intentionally exercises the full normal artifact set rather than the reduced micro path.
+
+## Interface Impact
+
+Interface impact: L1 internal documentation/protocol validation.
+
+No API, DTO, database, event, service, or cross-module runtime contract changes are expected.
+
+## Artifact Model
+
+Standard validation requires:
+
+- OpenSpec: `proposal.md`, independent `design.md`, `specs/`, `tasks.md`.
+- Devflow archive: `brief.md`, `evidence.md`, `decisions.md`, `acceptance.md`.
+
+The validation checks that current skill rules point to `references/scales.md` for the exact standard artifact requirements instead of redefining them elsewhere.
+
+## Execution Design
+
+1. Build the standard OpenSpec fixture.
+2. Run static scans for standard artifact wording and duplicated scale definitions.
+3. Run skill validation and reference integrity checks.
+4. Record evidence separately in `devflow/.../evidence.md`.
+5. Mark the fixture as committed only if artifact completeness and alignment pass.
+
+## Risks
+
+- The external OpenSpec archive/apply commands are not exposed in the current tool surface; this validation uses file-based checks.
+- File presence does not prove independent-agent usability; forward-testing remains a separate optional validation surface.
@@ -0,0 +1,39 @@
+# Validate SM Flow Standard Change
+
+## Why
+
+The previous validation covered a micro change. A standard change has stricter expectations: an independent `design.md`, complete OpenSpec artifacts, and a separate `evidence.md` in devflow.
+
+This validation checks whether the current `sm-flow` skill can still describe and validate a normal standard change after the recent simplification work.
+
+## What Changes
+
+- Create a standard-scale validation fixture for `sm-flow`.
+- Verify standard OpenSpec artifacts exist and are aligned: `proposal.md`, `design.md`, `specs/`, and `tasks.md`.
+- Verify standard devflow archive artifacts exist: `brief.md`, `evidence.md`, `decisions.md`, and `acceptance.md`.
+- Verify standard still uses the same four visible checkpoints and nine internal phases without exposing phase names as user commands.
+
+## Scope
+
+In scope:
+
+- Standard-scale validation records.
+- Static checks over `.agents/skills/sm-flow`.
+- Narrow fixes to the skill if standard validation reveals inconsistency.
+
+Out of scope:
+
+- Business code changes.
+- Reworking archived historical changes.
+- Changing the current trigger policy.
+
+## Non-Goals
+
+- This change does not test a complex migration, rollback, or cross-team interface change.
+- This change does not require independent browser/manual validation.
+- This change does not replace the micro validation already archived.
+
+## Risks
+
+- A standard validation fixture can become noise if left unarchived; status must be explicit.
+- If standard rules are only validated by file presence, semantic drift may still require future forward-testing.
@@ -0,0 +1,36 @@
+# sm-flow Standard Change Spec
+
+## ADDED Requirements
+
+### Requirement: Standard Change Has Full OpenSpec Artifacts
+
+A standard `sm-flow` change SHALL have `proposal.md`, independent `design.md`, `specs/`, and `tasks.md`.
+
+#### Scenario: Standard fixture is committed
+
+- **Given** a change is classified as `standard`
+- **When** commit validation runs
+- **Then** `proposal.md`, `design.md`, at least one spec file, and `tasks.md` exist
+- **And** the artifacts are aligned from proposal to design to specs to tasks
+
+### Requirement: Standard Archive Has Evidence
+
+A standard `sm-flow` archive SHALL include `brief.md`, `evidence.md`, `decisions.md`, and `acceptance.md` in devflow.
+
+#### Scenario: Standard fixture is archived or accepted
+
+- **Given** a standard validation change has completed apply checks
+- **When** devflow records are written
+- **Then** `evidence.md` exists as a separate file
+- **And** it records the static and script validation evidence used for acceptance
+
+### Requirement: Scale Definitions Remain Centralized
+
+Standard-specific artifact requirements SHALL be defined by `references/scales.md`; other files may reference those requirements but not carry a competing full definition.
+
+#### Scenario: Standard wording is scanned
+
+- **Given** sm-flow references mention standard behavior
+- **When** scale definition phrases are scanned
+- **Then** complete standard definitions appear only in `references/scales.md`
+- **And** operational files defer to the current scale rather than hard-coding alternative standard rules
@@ -0,0 +1,29 @@
+# Tasks
+
+## 1. Standard OpenSpec Fixture
+
+- [x] 1.1 Create `proposal.md`.
+- [x] 1.2 Create independent `design.md`.
+- [x] 1.3 Create at least one spec under `specs/`.
+- [x] 1.4 Create `tasks.md`.
+
+## 2. Standard Validation
+
+- [x] 2.1 Run scale duplication scan.
+- [x] 2.2 Run obsolete wording scan.
+- [x] 2.3 Run skill quick validation.
+- [x] 2.4 Run reference integrity scan.
+
+## 3. Commit Gate
+
+- [x] 3.1 Confirm OpenSpec artifact completeness.
+- [x] 3.2 Confirm proposal -> design -> specs -> tasks alignment.
+- [x] 3.3 Create `.committed`.
+
+## 4. Devflow Records
+
+- [x] 4.1 Create `brief.md`.
+- [x] 4.2 Create separate `evidence.md`.
+- [x] 4.3 Create `decisions.md`.
+- [x] 4.4 Create `acceptance.md`.
+- [x] 4.5 Update `devflow/index.md`.
@@ -0,0 +1,572 @@
+# Dev Flow:背景与技术演进
+
+**状态**:设计中
+**日期**:2026-07-05
+**范围**:说明 `dev-flow` skill 为什么存在、从哪来、为什么是现在这个形态
+
+---
+
+## 1. 这份文档解决什么
+
+`dev-flow` 的核心只有一条规则:**每个非平凡变更必须留下 `decision.md`**。
+
+这个规则看起来很轻,但它是从五次设计迭代、一次完整协议重写、以及和三个外部实现的对比里收敛出来的。**如果只看结论,很容易觉得它"太简单了,不够"**——所以这份文档把推理链完整留下来。
+
+配套文档:
+
+- `.agents/skills/dev-flow/SKILL.md` — 运行协议
+- `.agents/skills/dev-flow/references/decision-note.md` — 格式规范与校准案例
+
+---
+
+## 2. 背景:为什么需要一层"决策档案"
+
+### 2.1 原始动机(2026-05-18 前后)
+
+第一次完整跑通一个 AI 驱动的开发流程后,暴露的问题是**产物散落**:
+
+```text
+CONTEXT.md                 ← 根目录
+docs/adr/                  ← 架构决策
+docs/agents/               ← PRD
+openspec/changes/          ← 提案与规格
+knowledge/entries/         ← 知识条目
+```
+
+三个月后想回溯"这个项目到底做了什么决策",需要同时翻 4 个目录。**产物按"工具来源"组织,而不是按"项目"组织。**
+
+这是 `devflow/` 聚合层的直接起因,设计上借鉴了 CodeStable 的**单一聚合根**。
+
+### 2.2 当时确立的两层分工
+
+| | `openspec/changes/` | `devflow/projects/` |
+|---|---|---|
+| 角色 | 工具工作区(WAL) | **人类可读档案层(Tables)** |
+| 谁读 | 机器 | **人** |
+| 生命周期 | 活跃变更期 | 永久保留 |
+| 组织方式 | 按变更名 | 按日期 + 项目 |
+
+**"给人看"是明确的设计目标**,不是副产品。这一点在后来的讨论中被反复确认,也是最终形态的关键约束。
+
+### 2.3 但有一个前提,后来被证伪
+
+原始设计文档里写着:
+
+> `openspec/changes/` 是工具工作区(WAL),**archive 后清空**;`devflow/projects/` 永久保留。
+
+**在真实仓库里这个前提不成立。** 实测:
+
+```text
+openspec/archive/2026-05-19-add-clear-filters/
+openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/
+openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/
+openspec/changes/archive/2026-05-25-knowledge-index-sort/
+```
+
+归档内容**没有被清空**,而且历史上出现过两个归档位置(`openspec/archive/` 与 `openspec/changes/archive/`)。
+
+后来设计文档自己把真正丢失的东西说清楚了:
+
+> 旧:`openspec archive` 只归档需求,项目的**术语、业务规则、架构决策**散落在对话中,下次新对话全丢
+
+关键点:**丢的不是变更产物,是 `why`。** 术语有 `devflow/glossary/CONTEXT.md` 承载;而"架构决策"就是决策档案本身。
+
+**结论:"需要一层新目录"这个判断,建立在错误的前提上。**
+
+---
+
+## 3. 技术演进
+
+### 3.1 v1 — `dev-flow` 骨架
+
+`.claude/skills/dev-flow/` 的最早形态:Phase 1-4 流水线(手动 PRD → openspec propose → to-prd → grill → apply),外加一个 `devflow/` 目录约定。
+
+### 3.2 v2.0.0 — 产物聚合层(现存 213 行)
+
+现行 `.claude/skills/dev-flow/SKILL.md` 的版本。核心贡献:
+
+```text
+devflow/
+├── projects/YYYY-MM-DD-{slug}/
+│   ├── {slug}-prd.md        {slug}-research.md
+│   ├── {slug}-design.md     {slug}-tasks.md
+│   ├── {slug}-acceptance.md
+│   └── adr/
+├── glossary/CONTEXT.md
+├── compound/
+└── reference/
+```
+
+确立了两层架构与"Phase 4 从 OpenSpec 提取到 devflow"的回填模式。
+
+**它已经埋下了后来的两个问题**:
+
+1. **数量不封顶**——一个项目 5 个文件起,`adr/` 与 `compound/` 还可再长
+2. **提取 = 有损转换**——`{slug}-tasks.md` 是从 openspec `tasks.md` **提炼**出来的,同一事实两个权威
+
+### 3.3 sm-flow v2 — 产品化
+
+`dev-flow` 被重构为 `.agents/skills/sm-flow/`,把设计说明书拆成代理可执行的 skill 结构(`SKILL.md` + `references/`)。
+
+### 3.4 sm-flow v3 / v3.1 — 真理源分层与产物瘦身
+
+v3 解决的问题:**devflow 产物越来越完整,agent 开始直接拿 devflow 写代码,OpenSpec 被架空。**
+
+确立分层:
+
+```text
+devflow = 上下文真理源     OpenSpec = 执行真理源     代码 = 结果
+```
+
+v3.1 进一步明确 **devflow 不复制 OpenSpec**,只保存它不擅长表达的人类上下文、证据、决策和验收归档。默认产物收敛为 `brief` / `evidence` / `decisions` / `acceptance`。
+
+**这一步方向是对的,但执行没有一致性保障**——见第 5 节的实测。
+
+### 3.5 sm-flow v4.0 — 协议层 harness 重设计
+
+一次设计评审后做了一次**结构性重写**(不是加规则):
+
+| 改动 | 性质 |
+|---|---|
+| 19 条规则 → 6 条硬约束 | 删减 |
+| `SKILL.md` ~85 行 → ~50 行 | 删减 |
+| **grill 提到 specify 之前** | 消除"细化 → 澄清 → 回写"的必然返工 |
+| devflow 延迟写入:过程只维护 `decisions.md` | 消除双重记录 |
+| 阶段改英文动词命名,4 个用户命令 | 接口收窄 |
+
+设计文档自己写下了这次重写最重要的判断:
+
+> **这不是 agent 执行问题,是流程顺序决定了返工必然存在。**
+
+**v4.0 是这条演进线上唯一一次"减法生效"的版本。**
+
+### 3.6 sm-flow v4.1 / v4.2 — 两次应激加码
+
+| 版本 | 触发原因 | 成本 |
+|---|---|---|
+| v4.1 | 山东商客意向单同步接口返工 4-5 次 | +55 行,门控 4→6 |
+| v4.2 | `lookup-knowledge-integration` 跳过 7 个阶段 | +80 行,门控 6→8,新增 `.committed` / `.archive-ready` |
+
+v4.2 的核心主张是**把软性约束变成硬性检查**——但形式上仍然是提示词里的检查清单。
+
+两个值得记录的问题:
+
+1. **v4.0 的验证复盘已经观察到同类跳过行为,并明确决定"暂不改协议"**(原文:"问题 1 和 2 暂不改协议,如果多次验证中反复出现再考虑加约束")。**v4.1/v4.2 违反了自己定下的门槛。**
+2. **v4.2 的动机案例按 v4.3 的触发规则根本不算 sm-flow 运行**——优化建议文档自己标注"执行模式:手动跳阶段(用户直接要求修复问题)"。
+
+### 3.7 sm-flow v4.3 — 回到减法
+
+| 改动 | 性质 |
+|---|---|
+| **只显式触发**(不再按需求类型自动触发) | 砍掉常驻税与假阳性违规 |
+| `.agents/skills/sm-flow/references/scales.md` 成为分档**唯一**来源 | 消除重复定义 |
+| 新增 `.agents/skills/sm-flow/references/glossary.md` | 统一术语 |
+| **拒绝**引入 `.sm-flow-state` 状态文件 | 主动不做 |
+| 删掉固定投入指标 | 去掉会腐化的经验值 |
+
+**v4.3 是自 v4.0 以来第一个走简化方向的版本。** 它证明这条演进线是活的。
+
+### 3.8 现状实测(截至本文)
+
+`sm-flow` skill 本体:
+
+| 指标 | 实测 |
+|---|---|
+| 文件数 / 体积 | 8 个 / 58,597 B |
+| 总行数 | **1,253 行** |
+| "必须 \| 不得" | **52 处** |
+| 列表项 | **454 个** |
+| 首次加载(SKILL.md + phase-contracts) | ≈ 8.5k tokens(**占全量一半**) |
+| 单次 standard 变更产物 | OpenSpec 7 文件 14.8 KB + devflow 5 文件 20.3 KB = **35 KB** |
+
+设计文档自己给出的成本表:
+
+| 规模 | 代码工作量 | 流程开销 | 占比 | 自评 |
+|---|---|---|---|---|
+| micro | 30 min | 40–60 min | **~60%** | **太重** |
+| standard | 2 h | 1–1.5 h | ~40% | 还行 |
+| complex | 1–2 d | 2–3 h | ~20% | 值得 |
+
+---
+
+## 4. 对照外部实现
+
+为了让判断不建立在自我推演上,对三个外部实现做了一手对照。
+
+### 4.1 三个外部实现的做法
+
+| | 状态持有者 | 强制力在哪 | 约束对象 |
+|---|---|---|---|
+| **OpenSpec**(v1.13) | 产物依赖图,**CLI 计算** readiness | `status --json` 与 schema | 一次变更的产物 |
+| **Trellis**(0.7) | `task.json.status` + **hook 每轮注入** | 平台 hook | 一轮该做什么 |
+| **DSH Agent Notes** | **文件路径** | **CI 脚本 + PR 原子性** | 一个决策必须留下理由 |
+| *sm-flow* | *agent 的 checkpoint 陈述* | *提示词自查* | *阶段顺序* |
+
+**三家都把强制力移出了提示词,sm-flow 是唯一没移的。**
+
+### 4.2 关键发现一:DSH 并不强制"必须写"
+
+DSH 有 19 个 CI workflow、110+ 个 `verify-*` 脚本,其中与 Agent Notes 相关的只有三个:
+
+| 脚本 | 管什么 |
+|---|---|
+| `verify-agent-note-classification.ts` | 路径是否在关闭集内 |
+| `verify-agent-note-format.ts` | 三行头 + 骨架 + **`## Alternatives considered` 必须存在** |
+| `verify-archived-agent-notes.ts` | 冻结三元组 + 哈希 manifest |
+
+检索确认:**没有任何脚本强制"改了代码就必须有笔记"。** 那条规则靠约定与人工 review。
+
+**一个 1,026 篇笔记、110 个校验脚本的项目,把所有机器能查的东西都做成了脚本,却单独把这一条留给了判断。**
+
+原因是"非平凡"本身是判断,机器强制会产生假阳性——正是 pre-commit hook 拦琐碎提交的那个问题。
+
+**结论:任何"三条时机不变量 + hook"的方案都比业界最成熟的实现更重。这个方向的复杂度应当被否决。**
+
+### 4.3 关键发现二:devflow 层的前提被证伪
+
+见第 2.3 节。归档不丢数据,丢的是 `why`。
+
+### 4.4 收敛出的三条原则
+
+**① 不新增检查点,把义务挂在已有的动作上。**
+
+- DSH:写新笔记 → 顺手检查旧笔记是否被取代
+- DSH:改代码 → 同一次变更里更新笔记的事实
+- `triage`:决定拒绝 → 同时写 `.out-of-scope/`
+- *反面*:sm-flow 现在新增 4 个 checkpoint + 8 个门控文件 + 各类自检清单
+
+**② 检查只有一个,放在收尾边界。**
+
+- OpenSpec:archive 时检查完整性
+- Trellis:finish 时拒绝在不一致状态下完成
+
+两家独立收敛——不是"全过程多条不变量",而是"收尾时一次检查"。
+
+**③ "是否该写"是判断,不强行机器强制。** 见 4.2。
+
+---
+
+## 5. devflow 现状实测:问题不是"文件太多"
+
+`devflow/` 现状:
+
+| 指标 | 实测 |
+|---|---|
+| 文件数 / 体积 | **37 个 / 85.0 KB** |
+| 项目数 | 9 |
+| 每项目文件数 | **2 – 7,无规律** |
+| 命名约定 | **4 套并存** |
+| **含"替代方案"的文件** | **1 / 37** |
+
+### 5.1 四套命名约定并存
+
+| 世代 | 形态 |
+|---|---|
+| 早期 | `{slug}-{prd,design,research,tasks,acceptance}.md` |
+| 早期 | 自由式(`dev-flow-skill-evaluation.md` + `todo.md`) |
+| 早期 | `adr/` 子目录 |
+| v3.1 后 | `{brief,evidence,decisions,acceptance}.md` |
+
+**没有任何机制阻止格式漂移**,因为格式从未被校验。
+
+### 5.2 真正的病:同一个"5 个文件",两种质量
+
+| 项目 | 文件数 | 与 OpenSpec 的关系 |
+|---|---|---|
+| `add-year-filter` | 5 | **严重重复**——`-design.md` 与 `design.md` 同一件事写两遍;`-tasks.md` 与 `tasks.md` 任务核对两遍 |
+| `sm-flow-execution-hardening` | 5 | **做对了**——`brief.md` 写的是"OpenSpec 对齐:已覆盖",用引用代替复制 |
+
+**两种质量共存,而文件名看不出区别。** 只能靠打开和回忆。
+
+### 5.3 最稀缺的内容几乎为零
+
+在整个 `devflow/` 里检索 `备选|替代方案|放弃了|代价|alternatives|trade-off|权衡|否决`:
+
+```text
+Found 1 match
+devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md
+Line 21: ## 替代方案
+```
+
+**37 个文件、85 KB,只有一篇文章记录了"我们放弃了什么"。** 而它的骨架恰好就是决策档案的骨架:
+
+```markdown
+## 背景        ← Problem
+## 决策        ← Decision
+## 替代方案     ← Alternatives considered
+## 后果        ← Consequences（正面 / 负面分开）
+```
+
+**正确答案在 2026-05-18 就被写出过一次,此后 9 个项目再没出现第二次——因为没有机制要求它。**
+
+---
+
+## 6. 决策:三个方案
+
+| | A:devflow 分层 + 同步机械 | B:devflow 只给 agent 读 | **C:取消 devflow 层** |
+|---|---|---|---|
+| 决策笔记落点 | `devflow/decisions/<lifecycle>/<class>/` | 同 A,但格式机器优先 | **`openspec/changes/<slug>/decision.md`** |
+| 受众 | 人 + agent | 只 agent | **人 + agent** |
+| 同步问题 | 有,需 3 条不变量 + hook 解 | 有,且对 agent 更严重 | **不存在** |
+| 新增机械 | ~200 行 + hook | ~60 行 | **~0 行** |
+| 写入时机 | 需要保证 | 需要保证 | **天然正确**(写变更产物的同一时刻) |
+| 人的可读性 | 是 | 否 | **是** |
+
+### 为什么否决 A
+
+A 要新增三条时机不变量 + pre-commit hook。**4.2 的发现表明这比 DSH 更重**,而 DSH 是靠约定解决的。
+
+更根本的是:A 是在**解决同步问题**;而 4.3 表明这个同步问题**本来不需要存在**。
+
+### 为什么否决 B
+
+B 的直觉是"只给 agent 读就不用管可读性和索引,复杂度就降了"。但:
+
+- 省掉的只是 `index.md` 和文笔(**便宜**)
+- 省不掉时机同步(**昂贵**),而且对 agent 阅读**更关键**——agent 会照着过时的记忆干活
+
+而且 A/B 是超集关系:一份写好的人类可读决策档案**同时**是 agent 能读的;反过来不成立。
+
+**唯一支持 B 的论证是"没人读的档案会腐烂"——而这一点已被 5.3 实测证明:覆盖率 1/37,无人校对。**
+
+### 为什么选 C
+
+1. **它消除问题而不是解决问题**——同步复杂度归零
+2. **它纠正了事实错误**:devflow 层的主要理由(archive 后清空)不成立
+3. **它符合设计原则 ①**:写入义务挂在"写变更产物"这个已有动作上
+4. **它满足原始设计目标**:`decision.md` 是给人看的,而且和它描述的那次变更放在一起,人类读起来上下文最完整
+
+保留下来的是三样最有价值的东西:
+
+- **强制 `## Alternatives considered`**(ADR-001 就是范例)
+- **`glossary/CONTEXT.md`**(真正的跨项目知识)
+- **`rejected/`**(未实施提案的归宿,DSH 与 `triage` 独立收敛的机制)
+
+放弃的是:devflow 作为独立"人类档案层"的存在感,以及 A 的那套同步机械。
+
+---
+
+## 7. 新 dev-flow 的设计
+
+### 7.1 定位:替代 sm-flow
+
+**dev-flow 是一套轻量开发流程,并且替代 sm-flow。** 这不是"两套正交工具",而是一次替换:
+
+| | sm-flow | dev-flow |
+|---|---|---|
+| 身份 | 协议层 harness,编排 9 阶段 | **轻量开发流程,3 阶段** |
+| 人类确认点 | 4 | **2** |
+| 分档 | micro / standard / complex | **无** |
+| 协议行数 | 1,253 | **~150** |
+| 单次变更产物 | OpenSpec 7 文件 + devflow 5 文件 = 35 KB | **OpenSpec 4 件 + `decision.md`** |
+| 强制内容 | "按顺序做 9 件事并逐项自查" | **"放弃了什么"** |
+| 强制力 | 提示词 + 8 个自查清单 | **1 个收尾检查** |
+
+**sm-flow 的归档由用户手动执行**,在 dev-flow 实现完成之后。
+
+### 7.2 三阶段流程
+
+```text
+Think 想清楚   →   Build 做出来   →   Close 收好尾
+       ⏸ 确认点 1                          ⏸ 确认点 2
+     授权进入实现                          是否归档
+```
+
+| 阶段 | 做什么 | 用 OpenSpec 的 |
+|---|---|---|
+| **Think** | 澄清 → 读上下文 → 写 proposal/design/specs/tasks → **写下 `decision.md` 的 Problem 与 Alternatives** | `openspec-propose` |
+| **Build** | 按 tasks 分步实现 + 验证;冲突三分法 | `openspec-apply-change` |
+| **Close** | 补齐 Decision / Consequences / Verification → 收尾检查 → 归档确认 | `openspec-archive-change` |
+
+**为什么是 3 个而不是 9 个**:sm-flow 的 9 阶段里有一半是"为了防止 agent 偷懒"而设的编排层。当强制力改由文件与收尾检查承担之后,这些中间阶段失去了存在理由。**Trellis 用 Plan / Execute / Finish 三段跑通,是同一判断的独立佐证。**
+
+**为什么不分档**:sm-flow 的分档设计者自己评分 micro 开销约 60%、"太重"。**流程本身就轻的时候,分档是多余的**——它只是在给一个重流程寻找减负的借口。
+
+### 7.3 产物布局
+
+```text
+openspec/changes/<slug>/
+├── proposal.md
+├── design.md            ← 实现设计（执行向）
+├── specs/
+├── tasks.md
+└── decision.md          ← why + 备选 + 代价 + 验证（人向）
+
+devflow/
+├── glossary/CONTEXT.md  ← 跨项目术语
+├── rejected/<class>/    ← 未实施的提案
+└── index.md             ← 脚本扫描归档生成,不手写
+```
+
+### 7.4 保留了 sm-flow 的什么
+
+dev-flow 不是全盘重写。三样东西被完整继承:
+
+- **Draft / Committed 思想** → 变成**确认点 1**("未获授权不得进入 Build")。这是三家外部实现独立收敛到同一处的设计。
+- **冲突三分法** → 完整保留,是四家对比里唯一没找到对应物的原创资产。
+- **显式触发** → 保留,v4.3 唯一一次生效的减法。
+
+放弃的是:9 阶段编排、micro / standard / complex 分档、8 个自查清单、`.committed` / `.archive-ready` 门控文件、每阶段声明 capability 来源的仪式、以及 devflow 的 4–5 件套档案。
+
+### 7.5 三条设计原则
+
+见 `SKILL.md`。**① 义务挂在已有动作上 ② 确认点只有两个 ③ "是否该写"是判断。**
+
+### 7.6 能力来源:编排,而不是重写
+
+dev-flow 和 sm-flow 一样是**元技能**——由多个子 skill 实现。但组合的务实程度不同:
+
+| | sm-flow | dev-flow |
+|---|---|---|
+| 组合的子 skill | 8 个(3 个 OpenSpec + grill / to-prd / zoom-out / diagnose / tdd) | **5 个**(3 个 OpenSpec + grill-with-docs + diagnose / tdd) |
+| 能力声明 | 每个阶段显式声明 capability 来源 | **一张表,不逐阶段声明** |
+| 不可用时 | `references/fallbacks.md`,8 个内置协议(49 行) | **一行规则**:按能力绑定;不可用时读本地 `SKILL.md`;仍不可用时按最小等价协议直接产出文件并注明 |
+| 不使用 | — | `to-prd`(发布到 issue tracker,且与 `proposal.md` + `specs/` 重复) |
+| 不设阶段 | — | `audit`。`zoom-out` 降为按需能力,不再是关卡 |
+
+**设计期间发生的三次修正,值得记录:**
+
+1. **澄清环节一度被重写。** 初版 `phases.md` 把"一次一问、能查代码的自己查、术语沉淀进 `CONTEXT.md`"又写了一遍——而这三条 `grill-with-docs` 已经实现了。
+   这正是 sm-flow v2 自己修过的错(元技能复述子技能逻辑)。现已改为**引用 + 只保留 dev-flow 特有的部分**。
+
+2. **`grill-with-docs` 的取向与本流程有张力。** 它要求 "interview me **relentlessly** … until we reach a shared understanding",而 dev-flow 要轻。
+   解法是分层:**relentless 是对问题质量的,不是对数量的**——方法借用,范围收窄。
+
+3. **ADR 与 `decision.md` 原本会重复。** `grill-with-docs` 会提议创建 ADR(需同时满足难以逆转 / 缺少上下文会困惑 / 源自真实权衡),而 dev-flow 要求每个变更写 `decision.md`,两者形态几乎相同。
+   处置:**`decision.md` 吸收 ADR**,不再另建 `adr/` 目录。ADR 三条件从"要不要写"降级为"值不值得写深"。
+   (DSH Agent Notes 用 `architecture` class 承担 ADR 角色,是同一思路。)
+
+4. **冲突面比预想的宽。** 逐一实测后,`grill-with-docs` 有**三处**默认与本仓库不符:
+
+   | 它的默认 | 本仓库实际 |
+   |---|---|
+   | ADR 写入 `docs/adr/` | `docs/adr/` **不存在**;实际在 `devflow/projects/*/adr/`(3 个目录) |
+   | 用 `ADR-FORMAT.md` | dev-flow 用 `decision-note.md` |
+   | 假设根目录 `CONTEXT.md` | 用 `devflow/glossary/CONTEXT.md`(根目录是 235 B 重定向 stub) |
+
+#### 裁决:都不内置
+
+理由是结构性的,不是偏好:
+
+> **内置只在被组合 skill "消失"时才消除冲突。** 只要它还装在目录里(用户可以直接调用),
+> 内置就只是让 dev-flow 多出一份**会漂移的私有副本**——重复实现加上版本漂移,两个问题。
+
+改成一条**可判定的归属规则**,它能覆盖未来还没组合的 skill:
+
+> **子 skill 管"这一步怎么做";dev-flow 管"做多少、结果放哪"。冲突时,流程赢。**
+> 归属规则解决不了的 → **不组合它**(`to-prd` 就是这么处理的)。
+
+| 内容 | 归属 |
+|---|---|
+| 一次一问、先查代码、场景压测 | `grill-with-docs`(方法,引用不内联) |
+| 问多少、何时停、要不要写 ADR | **dev-flow** |
+| `CONTEXT.md` 在哪、ADR 落哪、用什么格式 | **dev-flow** |
+
+#### 为什么 `openspec-*` 尤其不能内置
+
+它们由 `openspec update` 生成,同时存在于 `.claude/skills/` 和 `.codex/skills/`,是**外部管理的多副本产物**。只能按能力名引用。
+
+**顺带发现**:`.agents/skills/` 下**没有** `openspec-*`,所以在本环境里"优先用平台原生 skill"会失败,必须降级到"读本地 `SKILL.md`"(`.claude/` 或 `.codex/` 下有)。这正好验证了"能力绑定而非路径绑定"这条规则在**兜住一个真实的不一致**——而不是一条装饰性的设计原则。
+
+---
+
+## 8. 验证记录
+
+### 8.1 `openspec validate` 是否容忍 change 目录内的 `decision.md` —— ✅ 容忍
+
+这是方案 C 的硬前提。**已实测确认。**
+
+| 步骤 | 结果 |
+|---|---|
+| 基线:`validate knowledge-index-panel` | `is valid` / exit=0 |
+| **探针:加入 `decision.md`** | `is valid` / **exit=0** ✅ |
+| **反向对照:抽掉 `proposal.md`** | **exit=1** ✅ 证明探针可信 |
+| 恢复后复验 | exit=0 |
+| 工作区洁净度 | 干净,无残留 |
+
+**反向对照是必须的。** 第一次探测只跑出 exit=0 就下结论,那是假阳性——CLI 当时根本没执行。
+
+### 8.2 环境约束:受限沙箱下无法捕获外部程序输出
+
+本次踩到的坑,记录下来避免重复:
+
+```powershell
+$x = & openspec validate foo        # ❌ 捕获 -> 命令静默不执行,仍返回 0
+& openspec validate foo | Select-Object -First 5   # ❌ 管道 -> 同样失效
+& openspec validate foo             # ✅ 直连控制台 -> 正常
+```
+
+**后果**:所有 CLI 验证必须让输出直连控制台。否则会得到"永远通过"的假象——**而且比没有验证更危险**,因为它会让人相信一个不存在的结论。
+
+### 8.3 顺带发现:`add-year-filter` 通不过校验——根因是 UTF-8 BOM
+
+```text
+Change 'add-year-filter' has issues
+✗ [ERROR] knowledge-filtering/spec.md: No delta sections found.
+✗ [ERROR] file: Change must have at least one delta.
+```
+
+**这个报错会误导。** `specs/knowledge-filtering/spec.md` 第 1 行**就是** `## ADDED Requirements`,完全按要求写的。
+真正的原因是文件带 **UTF-8 BOM**——解析器把行首标题读成了 `\ufeff## ADDED Requirements`,匹配不上。
+
+字节级实测,相关性完美:
+
+| change | 首 4 字节 | BOM | validate |
+|---|---|---|---|
+| `add-year-filter`(4 个文件全部) | `EF BB BF 23` | **有** | ❌ 失败 |
+| `knowledge-index-panel` | `23 23 20 57`(`## W`) | 无 | ✅ 通过 |
+| `sm-flow-execution-hardening` | `23 23 20 57` | 无 | ✅ 通过 |
+
+**这个结论差点写错。** 第一版是从报错**推断**出"它的 spec 用的是普通 `##` 小节",而没有实际读那个文件——
+读进去才发现推断是错的。**报错信息描述的是解析器看到的东西,不是文件里实际写的东西。**
+
+本地 CLI 版本 **1.3.1**(官网最新 1.13.0),偏旧,但 BOM 不兼容与版本关系不大——这是一个**可机械修复**的问题(去掉 BOM 即可)。
+
+### 8.4 dev-flow 首次验证(retrofit)
+
+用 `add-year-filter` 做了一次 **retrofit** 验证:Think 与 Build 在历史上已发生,所以本次验证的是 **Close 阶段与产物格式**。
+
+产物:`openspec/changes/add-year-filter/decision.md`(4,198 B)
+
+| 验证项 | 结果 |
+|---|---|
+| 五节骨架齐备 | ✅ |
+| 新文件无 BOM | ✅ |
+| **收尾检查 3 项** | ✅ **全部机械通过** |
+| 加入 `decision.md` 后 validate 报错集合未变 | ✅ 未引入新问题 |
+| **补出被丢弃的备选** | ✅ 第 3 条「只改 HTML 不改生成脚本」原本藏在 `design.md` 的"架构风险"里 |
+
+**未被验证的部分**(本次覆盖不到):Think 的澄清、确认点 1、Build 的冲突三分法,以及**冲突裁决**——retrofit 没有调用 `grill-with-docs`,所以三项覆盖一次都没触发。
+
+**本次暴露的一个格式缺口**:`## Verification` 要求"可重跑的命令",但**最有说服力的那条验证会修改文件**(重建 `knowledge-index.html`),导致收尾时不敢跑,只好把它拆成"已实测"和"需执行"两段。
+→ 应补充约定:**区分只读命令与有副作用的命令**。这是格式需要补的第一处。
+
+---
+
+## 9. 尚未解决
+
+| # | 问题 | 处置 |
+|---|---|---|
+| 1 | 旧的 `.claude/skills/dev-flow/`(2.0.0,213 行)同名但设计相反 | **用户后续处理** |
+| 2 | `sm-flow` 归档 | **用户后续处理**(dev-flow 实现完成之后) |
+| 3 | 现有 3 个活跃 change(`knowledge-index-panel` / `add-year-filter` / `sm-flow-execution-hardening`) | **本次忽略** |
+| 4 | 现有 9 个项目 37 个 devflow 文件的迁移 | 未定;建议先做单样本再定规则 |
+| 5 | `rejected/` 是否照搬 DSH 的 6 类关闭集 | 沿用,未验证 |
+| 6 | "计划写在 `decision.md` 却从未更新为事实"会不会出现 | 观察到再引入 DSH 的两套骨架 |
+| 7 | `devflow/index.md` 与 `scripts/check-dev-flow.sh` 尚未编写 | 脚本待写;index 暂手工 |
+
+---
+
+## 10. 附录:对照结论一览
+
+| 收敛的设计 | 出现处 |
+|---|---|
+| 状态必须外化到文件 | 全部四家 |
+| **强制力不该放在提示词** | OpenSpec(CLI 计算)/ Trellis(hook 注入)/ DSH(CI 脚本) |
+| 保留被否决的方案以防重新争论 | DSH `rejected/` / `triage` `.out-of-scope/` / OpenSpec archive |
+| 单一来源,不建中央索引 | DSH(明令禁 INDEX)/ Trellis(hook parser-only,零文案副本) |
+| 角色/上下文隔离靠进程 | Trellis(research/implement/check 子代理)/ OpenSpec(规划 skill "Never code") |
+| 按需加载 | OpenSpec(optional skills)/ Trellis(JSONL manifest) |
+| 不新增检查点,义务挂在已有动作上 | DSH(supersession)/ `triage`(决定即写) |
+| 检查只在收尾一次 | OpenSpec(archive)/ Trellis(finish) |
+| 用真实案例校准,不用阈值 | DSH("word count is never the test") |
@@ -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/`
Author	SHA1	Message	Date
zhuyongxin	d607861c6a	Introduce dev-flow: lightweight 3-phase flow with decision archive	2026-09-16 20:06:09 +08:00
osiman	ca6ae1ee0f	Merge pull request 'Refine sm-flow trigger and scale rules' (#2 ) from emdash/tasty-fans-dress-9sc8f into master Reviewed-on: #2	2026-07-06 10:00:37 +08:00
aruo	e4f6e013a5	Refine sm-flow trigger and scale rules	2026-07-05 14:30:15 +08:00
osiman	433f7a93a4	Merge pull request 'emdash/cuddly-rockets-rhyme-d5jo4' (#1 ) from emdash/cuddly-rockets-rhyme-d5jo4 into master Reviewed-on: #1	2026-07-05 03:16:12 +08:00
				`@@ -0,0 +1 @@`
				`Devflow archive files are ready for validate-sm-flow-explicit-trigger.`
				`@@ -0,0 +1 @@`
				`Committed OpenSpec for validate-sm-flow-explicit-trigger.`