Add value-scan and value-dig skills for reverse-engineering value points

- value-scan: read-only breadth inventory of mechanisms in delivered code,

  stopping at the human selection gate

- value-dig: depth write-up of chosen points (feature list, design review,

  refactor plan) with templates and mechanical checkers

- Add skill-workbench design doc for the pair

.agents/skills/dev-flow/SKILL.md

@@ -0,0 +1,192 @@
+---
+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/` 下那份。
+   **被否决的答案当场记进 `decision.md` 的 `## Alternatives considered`**(一行一条:问过什么、为什么输)——这是 Q&A 形态,见 `references/decision-note.md`)。
+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。
+> **方案讨论中的任何一次确认,都不等于实现授权。**
+> 快节奏交付下可以预授权,但必须显式:Think 退出时在 `decision.md` 写下
+> `<!-- pre-authorized: 日期 + 范围/原因 -->`。静默跳过不允许——旁路是有意识的选择,不是遗忘。
+> 授权状态以这行标记为准,恢复会话时读它,不靠对话记忆。
+
+## Build — 做出来
+
+**进入**:确认点 1 已过。
+
+**动作**:
+
+- 按 `tasks.md` 的纵向切片实现,按 `specs/` 验收。
+- **分步验证**:每完成一层再继续,不要一次写完再验。
+- **tasks/design 里提到"参考 XXX 实现"的,实现前先完整读它**——设计文档点名参考而实现时没看,是返工最常见的来源。
+- **冲突先分类再处理**:
+
+| 分类 | 处理 |
+|---|---|
+| 规格不准(遗漏、边界未覆盖、验收口径缺失) | 暂停,修正 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>/`(这里只兜底检查)。
+
+**退出**:`decision.md` 五节齐全;收尾检查通过;用户已被询问是否归档。
+
+## 核心规则
+
+| 规则 | 说明 |
+|---|---|
+| **必须写 `decision.md`** | 每个非平凡变更 |
+| **`## Alternatives considered` 强制** | 没有记录"打败了什么"的决策会招来重新争论 |
+| **备选是记录的,不是编造的** | 当时没记录就写 `<!-- alternatives-not-recorded -->` |
+| **实现前必须有授权** | 确认点 1 |
+| **冲突先分类再处理** | 三分法 |
+| **一个事实只有一个权威** | 见下表 |
+
+**"非平凡"的判据**:改变行为、架构、跨文件或跨包的契约、流程或工具、测试策略、磁盘/线缆/配置格式,或其他维护者可能重新考察的决策。
+**豁免**:纯机械或局部编辑。**小修不值得触发本流程**——dev-flow 是显式触发的 opt-in 流程,轻的第一道防线是不进来;后来发现重要时,允许事后补录 `decision.md`(retrofit 已验证)。
+
+### 事实的唯一权威
+
+| 内容 | 权威 |
+|---|---|
+| 为什么这么做、放弃了什么、代价 | `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 <slug>` 执行上述三项检查;`--index` 扫描归档派生 `devflow/index.md`(不手写);`--all` 检查全部活跃 change。
+
+## 目录
+
+```text
+openspec/changes/<slug>/
+├── proposal.md   design.md   specs/   tasks.md
+└── decision.md              ← 人向:为什么、放弃了什么、代价
+       ↓ 随归档一起冻存
+
+devflow/
+├── glossary/CONTEXT.md      ← 跨项目术语
+├── rejected/<class>/        ← 未实施的提案(否决发生时写入,不是 Close 时)
+└── index.md                 ← scripts/check-dev-flow.sh --index 派生,不手写
+```
+
+`rejected/` 的保留条件:它**仍能防止一个诱人的、有意义的错误**。否则整体删除。
+**边界**:`decision.md` 的 Alternatives 记"变更内"的方案备选;`rejected/` 收"整个提案被否决"的方向。提案在确认点 1 被整个否决时,当场写入 `rejected/`——那时流程已终止,Close 不会执行。
+
+## 触发规则
+
+- 用户输入 `/dev-flow`。
+- 用户明确要求走开发流程。
+
+不要因为任务涉及 OpenSpec、跨模块、架构决策或 devflow 目录就自动触发。
+未被这样要求之前,按普通工程任务处理。
+**`decision.md` 义务只覆盖经本流程的非平凡变更**——不经 dev-flow 的普通工程任务没有这个义务。
+
+## 相关文档
+
+- `references/phases.md` — 三阶段契约与判断细则
+- `references/decision-note.md` — `decision.md` 格式规范、校准案例、反模式
+- `skill-workbench/docs/dev-flow/background-and-evolution.md` — 背景、技术演进、设计取舍

.agents/skills/dev-flow/references/decision-note.md

@@ -0,0 +1,259 @@
+# 决策档案格式
+
+本文件定义 `decision.md` 的格式、每节的要求、校准案例和反模式。
+
+## 骨架
+
+```markdown
+# Decision: <一句话标题>
+
+## Problem
+## Decision
+## Alternatives considered
+## Consequences
+## Verification
+```
+
+小节顺序固定。固定顺序不是为了机器,是为了**人能跳转**——任何时候你想知道"代价是什么",往下翻到 `## Consequences` 就行。
+
+节名是规范名,不要用近义词替代(`## 背景` / `## 方案` / `## 风险`)。
+需要额外内容时,在 `## Decision` 和 `## Alternatives considered` 之间插入自定义小节。
+
+### 各节在哪个阶段写下
+
+| 节 | 写下时机 | 原因 |
+|---|---|---|
+| `## Problem` | **Think** | 动机在需求刚澄清时最准确 |
+| `## Alternatives considered` | **Think**,grill 问答当场 | 备选是在方案讨论中被否决的,当时记最真实;事后补写会变成回忆录 |
+| `<!-- pre-authorized: ... -->` | **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` —— 备选(强制)
+
+**要求**:每个**真实存在过**的备选一段,加粗开头,说明它**为什么输了**。
+
+**首选形态是压缩 Q&A——一行一条**。grill 问答中被否决的答案,就是备选;当场一行记下,转写成本接近零:
+
+```markdown
+## Alternatives considered
+
+- Q: 上完整 BM25 schema? A: 不——先 sparse-lite + RRF,schema 重建是后续变更。
+- Q: 默认用 hybrid? A: 不——dense 默认,hybrid 显式 opt-in。
+```
+
+(SuperBizAgent 实测:180 个档案文件里,段落式备选记录率为 0;唯一自然发生的高质量备选记录就是这个 Q&A 形态。)
+
+**值得写深时**(难以逆转的架构决策)才展开成段落,并要求写出推理链:
+
+```markdown
+**新增 year 字段到条目数据。** 冗余且需要同步维护——`date` 已是唯一来源,
+派生成本为零,多一个字段就多一处会不一致的地方。
+```
+
+**反模式**:
+
+| 反模式 | 为什么不行 |
+|---|---|
+| **稻草人备选** | 编一个明显更差的选项来凑数。这会让真实读者对整个文档失去信任 |
+| 只列备选,不说为什么输 | 等于没写——读者无法判断它现在是否仍然输 |
+| 把"什么都不做"当默认备选 | 除非当时真的认真考虑过维持现状,否则它只是修辞 |
+| 备选写成一堆标签 | 没有推理链,未来无法复用 |
+| **段落式凑字数** | Q&A 一行能说清的,不要为了"看起来正式"展开成三段 |
+
+**"什么都不做"什么时候是真的备选**:当维持现状确实是一个被权衡过的选项时(例如"暂不修复这个边界,先观察")。
+
+**没有可记录的备选时**,写这一行注释而不是编造:
+
+```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 篇档案里**唯一**记录了备选的一篇——也是唯一读完之后还记得住内容的一篇。
+
+**注意它的形式**:两条备选,每条一句被拒理由,没有废话。**短不等于差。**
+
+### 值得写深的备选(真实)
+
+SuperBizAgent 的 `phase1-infrastructure/decisions.md` ADR-001(Flyway):
+
+```markdown
+### 后果
+- 表结构修改必须通过 SQL 迁移脚本
+- 开发环境首次启动需要执行 Flyway 迁移
+- 生产环境部署自动执行未执行的迁移脚本
+```
+
+难以逆转的基础设施决策,后果写得具体到"改表必须走迁移脚本"——三个月后最需要读的就是这几行。
+**这是 Q&A 一行记不住的那种备选,值得整段。**
+
+### 应当补录备选(真实)
+
+`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 分钟内重跑吗?
+- [ ] 有没有一句话在两个地方都是权威?(有就是错)

.agents/skills/dev-flow/references/phases.md

@@ -0,0 +1,139 @@
+# 三阶段契约
+
+本文件是三阶段的判断细则。**它只规定"怎么判断",不新增检查点**——检查只有收尾那一次。
+
+---
+
+## 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 条,连同为什么)
+- 请求实现授权(或记录 `<!-- pre-authorized: 日期 + 范围/原因 -->`)
+
+**不要**复述 proposal、不要列产物清单、不要贴对齐表格。用户要的是判断依据,不是工作汇报。
+
+**pre-authorized 是显式旁路,不是默认。** 它适合用户已在对话中明确说"直接做"的快节奏场景。写它 = 承认确认点被有意识地跳过;不写而直接进 Build = 违规。授权状态的唯一载体是这行标记——恢复会话时以它为准。
+
+---
+
+## Build — 做出来
+
+### 分步实现与验证
+
+按 `tasks.md` 的纵向切片推进。**每完成一层先验证,再进下一层**——一次写完再验,出了问题无法定位是哪一层。
+
+第一个切片完成后,对照 `specs/` 检查一次:验收场景是否真的成立。**规格写得含糊会在这里第一次暴露。**
+
+### 参考实现先读,再动手
+
+`tasks.md` / `design.md` 点名"参考 XXX 实现"的,**实现前完整读它**。路径不明确时按类名/模式 Grep 定位。
+设计文档点名参考而实现时没看,是返工最常见的来源(SuperBizAgent 复盘:山东商客接口因此返工 4-5 次)。
+第一次在某区域写代码、或要用项目现有基础设施(MQ/统一请求结构/工具类)时,同此处理。
+
+### 冲突三分法的判断细则
+
+先分类,再动手。分类的错误比不分类更糟。
+
+**怎么区分"规格不准"和"代码偏离"**:问一句——**"如果完全按规格做出来,行为对不对?"**
+
+| 回答 | 分类 | 处理 |
+|---|---|---|
+| 对,但我没按规格做 | **代码偏离** | 改代码,不动 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`,但没有 `<!-- pre-authorized` 也没有对话中的明确授权 | **确认点 1** |
+| 有 `<!-- pre-authorized: ... -->` 或已获授权,实现未完成 | Build 进行中 |
+| 实现完成,`decision.md` 缺 `## Decision` / `## Consequences` / `## Verification` | Close 进行中 |
+| `decision.md` 五节齐全 | 收尾检查 + 确认点 2 |
+
+**恢复时不重新提问已经解决的问题。** 先读 `decision.md` 和 `proposal.md`——已经确认过的内容就在里面。

.agents/skills/sm-flow/SKILL.md

@@ -1,132 +1,107 @@
----
+---
 name: sm-flow
-description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
+description: OpenSpec-first 工程流程 harness。仅在用户显式调用 /sm-flow、/sm-flow explore、/sm-flow apply、/sm-flow archive，或明确要求使用 sm-flow 流程时使用；不要根据需求类型自动触发。
 ---
 
 # SM Flow
 
-SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作流。它不替代 OpenSpec，而是用 `devflow/` 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 `devflow/` 作为长期记忆。
+SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周期。它通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。
 
-## 角色定位
+sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。
 
-你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。
+## 触发规则
 
-## 真理源分层
+只在用户显式调用时使用 sm-flow：
 
-- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。
+- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。
-- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
+- 用户用自然语言明确要求"使用 sm-flow"、"走 sm-flow 流程"或等价表达。
-- 代码是实现结果：只能在执行真理源足够明确后修改。
+
-- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
+不要根据需求类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。
+
+## 四层架构
+
+```
+sm-flow        → 编排层（harness）：阶段、门控、产物约束、人类对齐
+  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
+    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
+      code     → 实现结果：apply 的产出
+```
+
+- OpenSpec 是唯一执行真理源：apply 阶段只能基于 OpenSpec 执行，不能绕过 OpenSpec 直接写代码。
+- devflow 是上下文真理源：术语、历史决策、验收记录来自 devflow，用于增强 OpenSpec，不替代 OpenSpec。
+- 如果 devflow 和 OpenSpec 冲突，先汇报冲突、让用户确认、修正 OpenSpec，再继续执行。
+- propose 阶段产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 apply 的执行许可。
+- 只有通过 commit 检查后的 OpenSpec 才是 **Committed OpenSpec**；apply 只能执行 Committed OpenSpec。
 
 ## 核心规则
 
-- Phase 3 默认必须通过 OpenSpec apply 执行；禁止直接依赖 devflow 文档绕过 OpenSpec 写代码。
+以下 6 条是硬约束，违反即流程失败。其余约束按阶段定义在 `references/phase-contracts.md`。
-- devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。
+
-- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
+1. **OpenSpec 是唯一执行真理源**。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。
-- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
+2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
-- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
+3. **不得跳过 grill**。必须按 `references/scales.md` 的当前分档要求完成澄清或验证。
-- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
+4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
-- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
+5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
-- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
+6. **能力来源必须显式声明**。每个阶段先声明使用外部子 skill / OpenSpec CLI / sm-flow 内置协议；外部能力不可用时可使用 `references/fallbacks.md` 的内置协议，但必须标注为 fallback。若外部能力和内置协议都不可用，流程失败。
-- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
+
-- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
+每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。
-- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
+
-- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
+## 用户命令
-- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
+
-- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
+| 命令 | 用户意图 | harness 内部行为 |
+|---|---|---|
+| `/sm-flow` | 完整流程 | clarify → context → propose → grill → specify → audit → commit → apply → archive |
+| `/sm-flow explore` | 先想想 | 带上下文的探索模式 |
+| `/sm-flow apply` | 只执行 | 检查 commit gate → apply |
+| `/sm-flow archive` | 收尾 | 回填 devflow + 归档确认 |
+
+用户也可以用自然语言指定从某个阶段继续，例如"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/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`。
-- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
+- archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
-- 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。
 
-## 启动检查
+## 内部阶段
 
-1. 判断启动模式：
+9 个内部阶段，按执行顺序：
-   - 完整模式：用户提供粗略想法或初始 PRD。
-   - Research 模式：用户已有 research，需要转成或修正 OpenSpec。
-   - PRD 文件模式：用户提供已有 PRD 路径。
-   - 指定阶段模式：用户要求从某个 Phase 恢复。
-   - 快速模式：小改动，Phase 2 和 Phase 4 可以轻量化，但不能省略。
-2. 如果缺少 `devflow/`，初始化：
-   - `devflow/projects/`
-   - `devflow/glossary/CONTEXT.md`
-   - `devflow/compound/`
-   - `devflow/reference/`
-3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
-4. 检查 OpenSpec 和子 skill 是否可用：
-   - OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
-   - 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
-5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
 
-## 项目标识
+1. clarify — 入口澄清：接收初始需求，澄清到可生成轻量 proposal。
-
+2. context — 上下文收集：读取 devflow 的 glossary、ADR、历史项目、compound knowledge。
-整个流程使用同一个 slug：
+3. propose — 轻量 propose：只生成 proposal.md，不调用 openspec-propose。
-
+4. grill — 人类对齐澄清：evidence-driven 查证 + user-interview one-at-a-time，回写 proposal。
-- 优先使用 OpenSpec change name。
+5. specify — 细化 + 对齐：基于已稳定的 proposal 补全 design/specs/tasks，做 cross-artifact 对齐。
-- 如果还没有 change name，则从功能标题生成 kebab-case slug。
+6. audit — 架构审计：审计结果如果影响实现，回写 OpenSpec design/tasks。
-- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
+7. commit — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
-- 如果目录已存在，默认恢复该项目，不要重复创建；除非用户明确要求新开一轮。
+8. apply — OpenSpec 执行：基于 Committed OpenSpec 实现代码。
-
+9. archive — 回填 + 归档：从 OpenSpec 产物和 decisions.md 提炼长期档案，询问是否归档。
-## Devflow 产物分层
-
-devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的执行产物。默认只创建必要文件；扩展文件必须有明确理由。
-
-**必须产物**：
-
-- `brief.md`：背景、目标、范围、非目标、变更规模、关联 OpenSpec change。
-- `evidence.md`：代码证据、文档证据、历史决策、evidence-driven 结论和汇报状态。
-- `decisions.md`：user-interview 问题、用户确认、关键取舍、风险接受、OpenSpec 回写记录。
-- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
-
-**按需产物**：
-
-- `prd.md`：需求复杂、用户明确要求 PRD、或需要对外协作时创建；小需求并入 `brief.md`。
-- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较时创建。
-- `design.md`：仅记录 OpenSpec design 不适合承载的人类背景、架构审计摘要或长期决策索引；实现设计仍以 OpenSpec design 为准。
-- `tasks.md`：仅记录跨轮次追踪或人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
-- `alignment.md` / `clarifications.md`：问题很多或冲突复杂时单独创建；否则并入 `decisions.md`。
-- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR/复合知识规则时创建。
-
-**规模分档**：
-
-- `micro`：小且低风险，使用 `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md`。
-- `standard`：默认模式，使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。
-- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加 PRD/research/design/tasks/alignment。
-
-## 阶段总览
-
-1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
-2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
-3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
-4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
-5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
-6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
-7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
-8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
 
 每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
 
+关键阶段的完成判断也以 `references/phase-contracts.md` 为准；如果缺少显式 checkpoint 或能力来源声明，该阶段不得视为已完成。
+
 ## 快速模式
 
-快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留：
+快速模式的具体约束见 `references/operating-rules.md`。
-
-- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
-- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
-- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
-- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
 
 ## 完成标准
 
-一次流程只有在满足以下条件时才算完成：
+流程完成标准见 `references/operating-rules.md`。
-
-- OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。
-- 实现或规划任务已经完成，且执行依据来自 OpenSpec。
-- 已运行验证，或明确记录未运行验证的原因。
-- `devflow/projects/YYYY-MM-DD-{slug}/` 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。
-- 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。
-

.agents/skills/sm-flow/references/archive-rules.md

@@ -1,6 +1,49 @@
-# 归档规则
+# 归档规则
 
-Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。
+archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转化为持久、可读、可复用的项目记忆。sm-flow 在 clarify → apply 期间只维护 `decisions.md` 作为过程日志，archive 阶段从中提取完整 devflow 档案。
+
+## Archive 强制执行顺序
+
+Archive 阶段必须按以下顺序执行，不得跳过或重排：
+
+### Step 1: 创建 devflow 档案（必需）
+
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
+      （从 proposal.md 提取：背景、目标、范围、非目标）
+      
+- [ ] 按 `references/scales.md` 的当前分档决定是否创建 `devflow/projects/YYYY-MM-DD-{slug}/evidence.md`
+      （创建时从 decisions.md 提取 evidence-driven 记录）
+      
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
+      （整理为最终版：关键决策、权衡、风险）
+      
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
+      （记录：静态验证、脚本验证、浏览器/人工验证、未验证）
+
+### Step 2: 更新索引（必需）
+
+- [ ] 在 `devflow/index.md` 末尾追加或更新一行：
+      `| YYYY-MM-DD | slug | 领域 | 关键词 | openspec/changes/xxx | {status} |`
+
+### Step 3: 标记 OpenSpec（必需）
+
+- [ ] 创建 `openspec/changes/{slug}/.archive-ready` 文件
+
+### Step 4: 向用户汇报（必需）
+
+- [ ] 列出创建的 devflow 档案文件路径（验证文件实际存在于磁盘）
+- [ ] 汇报验证情况（按静态验证、脚本验证、浏览器/人工验证、未验证分类）
+- [ ] 列出剩余风险或后续事项
+- [ ] 询问：**是否现在归档 OpenSpec？**
+
+### Step 5: 用户确认后执行 OpenSpec Archive（可选）
+
+- [ ] 调用 `openspec-archive-change`
+- [ ] 记录 archive 结果
+
+**自检**：在执行 Step 4 前，检查 Step 1-3 是否都完成。
+
+---
 
 ## 目录规则
 
@@ -10,12 +53,16 @@ Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为
 devflow/projects/YYYY-MM-DD-{slug}/
 ```
 
-默认创建以下必要文件：
+archive 阶段按 `references/scales.md` 的当前分档创建以下文件：
 
-- `brief.md`
+- `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
-- `evidence.md`
+- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取；是否独立创建按 `references/scales.md` 执行。
-- `decisions.md`
+- `decisions.md`：保持为最终版，整理格式。
-- `acceptance.md`
+- `acceptance.md`：从实现结果和验证结果提取。
+
+同时维护仓库级索引：
+
+- `devflow/index.md`
 
 按需创建以下扩展文件：
 
@@ -30,25 +77,40 @@ devflow/projects/YYYY-MM-DD-{slug}/
 
 ## 产物分档
 
-| 分档 | 适用场景 | 必须文件 | 扩展文件 |
+分档的适用场景和必须文件见 `references/scales.md`。本文件只定义 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` |
 
 ## 提取映射
 
 | 来源 | 提取内容 | 写入位置 |
 | --- | --- | --- |
+| `decisions.md`（过程日志） | question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍 | `decisions.md`（整理格式为最终版） |
+| `decisions.md`（过程日志） | evidence-driven 结论、代码/文档证据 | `evidence.md` |
 | `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` |
 | `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` |
 | `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 |
 | `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` |
-| 澄清记录 | evidence-driven/user-interview、证据、结论、确认状态 | `evidence.md` + `decisions.md` |
 | 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` |
 | diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
 | 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
 | 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
+| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` |
+
+## 索引维护规则
+
+`devflow/index.md` 是 context 阶段的默认入口，archive 阶段回填时必须维护。
+
+最小字段：
+
+| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
+| --- | --- | --- | --- | --- | --- |
+
+规则：
+
+- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
+- archive 阶段新建或更新项目档案时，必须新增或更新对应行。
+- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
+- 关键词只放能帮助 context 阶段定位的术语，不复制 brief 内容。
+- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。
 
 ## 验收记录规则
 
@@ -63,7 +125,7 @@ devflow/projects/YYYY-MM-DD-{slug}/
 
 - 如果验证通过，记录命令/步骤和覆盖范围。
 - 如果验证失败，记录失败摘要和是否阻塞验收。
-- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。
+- 如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。
 
 ## ADR 规则
 
@@ -89,18 +151,17 @@ devflow/compound/YYYY-MM-DD-decision-{slug}.md
 
 OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息：
 
-- Phase 4 可以建议 archive，但必须先询问用户。
+- archive 阶段可以建议 archive，但必须先询问用户。
 - 在用户确认前，不要执行 archive。
 - 如果用户暂不归档，在 acceptance 中记录原因或状态。
 - 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。
 
 ## 归档交接
 
-Phase 4 结束时告诉用户：
+archive 阶段结束时告诉用户：
 
 - 创建或更新了哪些档案文件。
+- `devflow/index.md` 是否已更新。
 - 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
 - 还剩哪些风险或后续事项。
 - 明确询问：是否现在 archive OpenSpec change？
-
-

.agents/skills/sm-flow/references/fallbacks.md

@@ -1,101 +1,49 @@
-# Fallback 协议
+# 内置执行协议
 
-当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。
+本文件只在外部 OpenSpec CLI 或子 skill 不可用时使用。fallback 不是跳过阶段，而是由 sm-flow 用文件方式完成同等最小产物。每次使用 fallback 都必须写入 `decisions.md` 或 `acceptance.md`，说明能力来源、缺失能力、影响和剩余风险。
 
-## OpenSpec 提案 fallback
+## 通用规则
 
-1. 创建或识别 `openspec/changes/{slug}/`。
+- 优先使用外部能力；只有不可用、不可发现或无法在当前环境调用时才使用内置协议。
-2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。
+- 不得因为使用 fallback 跳过 context、grill、commit、apply 授权或 archive 确认。
-3. 写入 `proposal.md`，包含：
+- fallback 产物仍写入 `openspec/changes/{slug}/` 和 `devflow/projects/YYYY-MM-DD-{slug}/`。
-   - 问题
+- 如果内置协议也无法满足阶段退出条件，暂停并向用户说明阻塞项。
-   - 建议方案
-   - 范围
-   - 非目标
-   - 来自 devflow 的上下文约束
-   - 风险
-4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。
-5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。
-6. 只为外部可见行为或发生变化的需求编写 specs。
-7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。
 
-## OpenSpec 修正 fallback
+## grill 内置协议
 
-当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：
+- 建立 question pool，至少覆盖术语、边界、验收；涉及参考实现或项目基础设施时加入技术实现问题。
+- 将问题标记为 `evidence-driven` 或 `user-interview`。
+- 先查证 evidence-driven 问题并汇报结论，再逐个询问 user-interview 问题。
+- 按 `references/scales.md` 的当前分档满足 grill 要求。
+- 将 question pool、证据结论、用户原话和确认状态写入 `decisions.md`；影响实现的结论回写 `proposal.md`。
 
-1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。
+## openspec 提案内置协议
-2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。
-3. 向用户汇报冲突和推荐修正。
-4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
-5. 再同步更新 devflow 文档；不要只改 devflow。
 
-## OpenSpec 执行 fallback
+- 在 `openspec/changes/{slug}/` 创建或更新：
+  - `proposal.md`：问题、方案、范围、非目标、上下文约束、风险。
+  - 设计产物：实现设计、接口影响、关键决策、架构风险；形式按 `references/scales.md` 的当前分档要求执行。
+  - `specs/*/spec.md` 或等价 functional spec：描述用户可观察行为和验收场景。
+  - `tasks.md`：按可执行切片拆分任务，并给每项写可验证验收标准。
+- 运行 cross-artifact 对齐检查：proposal → 设计产物 → specs → tasks。
+- 如果发现 gap，先修正 OpenSpec，再进入 commit。
 
-仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。
+## audit 内置协议
 
-1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
+- 用 5 句话以内说明模块链路、数据所有权、跨模块依赖、架构风险和是否需要回写 OpenSpec。
-2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
+- 如果风险影响实现，修正设计产物或 `tasks.md`。
-3. 修改前先检查现有代码。
+- 将结论写入 `decisions.md`。
-4. 一次实现一个 OpenSpec task 的纵向切片。
-5. 用最窄但有效的命令验证每个切片。
-6. 只有验证通过或明确记录原因后，才更新 task 状态。
-7. 如果失败原因不确定，停止并进入 diagnose。
-8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
 
-## PRD fallback
+## openspec apply 内置协议
 
-优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。
+- 只依据 Committed OpenSpec 的 specs/tasks 实现；devflow 只作上下文参考。
+- 开始前检查 `.committed` 文件；缺失则返回 commit。
+- 如触发 pre-apply checkpoint，先阅读参考实现、grep 项目基础设施模式，并把技术栈清单写入 `decisions.md`。
+- 按 tasks 的纵向切片实现、验证并更新任务状态。
+- 发现冲突时按三类处理：OpenSpec 不准则修 OpenSpec，代码偏离则修代码，不确定则暂停等用户确认。
 
-规则：
+## openspec archive 内置协议
-
-- 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。
-- `brief.md` 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。
-- 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。
-
-## 文档化追问 fallback
-
-1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。
-2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。
-3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。
-4. 对 user-interview 问题，一次只问一个并等待用户确认。
-5. 术语确认后立即更新词汇表。
-6. 影响实现的澄清必须回写 OpenSpec。
-7. 只为难以逆转的真实权衡创建 ADR。
-
-快速模式的最小问题：
-
-- 术语：这个概念应该使用哪个领域术语？证据是什么？
-- 边界：哪些内容明确不在范围内？是否需要用户确认？
-- 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？
-
-## 架构审计 fallback
-
-产出一份短架构审计：
-
-1. 画出输入 → 处理 → 输出。
-2. 列出相关模块和调用方。
-3. 识别耦合、数据所有权和生命周期风险。
-4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。
-5. 用不超过五句话总结最大风险。
-6. 如果影响实现，回写 OpenSpec design/tasks。
-
-## Diagnose fallback
-
-1. 复现问题，或捕获准确失败信息。
-2. 最小化失败案例。
-3. 生成 3-5 个假设，并按可能性和验证成本排序。
-4. 修改代码前，先添加仪器化或定向检查。
-5. 判断根因属于实现问题还是 OpenSpec 规格问题。
-6. 如果是实现问题，修复被证明的最小原因。
-7. 如果是规格问题，先修正 OpenSpec，再继续 apply。
-8. 运行回归验证。
-
-## TDD fallback
-
-使用纵向切片，不要水平批量写测试：
-
-1. 从 OpenSpec specs 中选择一个外部可见行为。
-2. 写一个失败测试。
-3. 实现刚好让测试通过的最小代码。
-4. 只在测试通过时重构。
-5. 对下一个 OpenSpec 行为重复以上步骤。
 
+- 不删除或移动 OpenSpec change；只标记归档准备状态。
+- 完成 devflow 回填、更新 `devflow/index.md`、创建 `.archive-ready`。
+- 向用户汇报已创建文件、验证分类、剩余风险，并询问是否需要真实 OpenSpec archive。
+- 如果外部 archive 能力仍不可用，在 `acceptance.md` 标记 `accepted-unarchived`。

.agents/skills/sm-flow/references/glossary.md

@@ -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 |

.agents/skills/sm-flow/references/operating-rules.md

@@ -0,0 +1,120 @@
+# 运行规则
+
+本文件承载稳定但不必放在顶层 `SKILL.md` 的运行规则。
+
+## 接口影响分级
+
+接口影响分级判断的是"记录在哪里、是否需要独立文档"，不是判断"是否需要关注"。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或内部决策逻辑变化，都必须先做分级。
+
+| 级别 | 判断条件 | 产物要求 |
+| --- | --- | --- |
+| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
+| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
+| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
+| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
+
+判断策略：
+
+- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
+- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
+- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
+- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
+
+## 启动检查
+
+1. 识别用户命令意图：
+   - `/sm-flow`（无参数）：完整流程，从 clarify 开始。
+   - `/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；具体分档规则见 `references/scales.md`。
+3. 如果缺少 `devflow/`，初始化：
+   - `devflow/projects/`
+   - `devflow/glossary/CONTEXT.md`
+   - `devflow/compound/`
+4. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
+5. 检查 OpenSpec 和子 skill 是否可用：
+   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。
+   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。
+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`；无论分档如何，都不要把内部阶段名当作用户操作入口。
+
+## 项目标识规则
+
+- 整个流程使用同一个 slug。
+- 优先使用 OpenSpec change name。
+- 如果还没有，则从功能标题生成 kebab-case slug。
+- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
+- 如果目录已存在，默认恢复该项目；除非用户明确要求新开一轮。
+
+## Devflow 产物分层
+
+Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec 的执行产物。
+
+**过程日志**（clarify → apply 期间维护）：
+
+- `decisions.md`：question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍、风险接受、OpenSpec 回写记录、冲突分类记录。
+
+**最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）：
+
+- `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。
+- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态；分档要求见 `references/scales.md` 和 `references/archive-rules.md`。
+- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
+
+**按需产物**（archive 阶段按需创建）：
+
+- `prd.md`：需求复杂、用户明确要求、或需要对外协作。
+- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较。
+- `design.md`：不适合放进 OpenSpec design 的长期背景或架构审计摘要。
+- `tasks.md`：跨会话的人类追踪；执行任务仍属于 OpenSpec。
+- `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用。
+- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用。
+
+**规模分档**：`micro / standard / complex` 的唯一规则源是 `references/scales.md`。
+
+## 快速模式
+
+快速模式适用于 `references/scales.md` 定义的 micro 变更。它合并 gate 而不仅仅是压缩产物；具体覆盖规则见 `references/scales.md`。
+
+无论什么模式，以下内容必须保留：
+
+- context 最小上下文收集：至少检查 glossary 和相关 ADR。
+- grill 最小澄清：按 `references/scales.md` 当前分档要求执行；evidence-driven 结论仍需汇报。
+- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行；完整性检查按 `references/scales.md` 当前分档要求执行。
+- apply 仍由 OpenSpec tasks/specs 驱动执行。
+- archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。
+
+## 完成标准
+
+只有同时满足以下条件，流程才算完成：
+
+- 用户可见的 Discover、Commit、Apply、Archive checkpoint 已完成，或未完成项已明确标记为暂停/不适用。
+- OpenSpec proposal、设计产物、specs、tasks 已按当前分档生成或更新到可执行状态。
+- 实现或规划工作已完成，且执行依据来自 OpenSpec。
+- 已运行验证，或已记录未运行验证的原因。
+- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案。
+- 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。

.agents/skills/sm-flow/references/phase-contracts.md

@@ -1,8 +1,22 @@
-# 阶段契约
+# 阶段契约
 
-本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：**devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。
+本文件是 SM Flow 的逐阶段执行准则。核心原则：**sm-flow 编排 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。
 
-## Phase 0 — 入口澄清
+执行顺序：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。
 
@@ -11,6 +25,7 @@
 - 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
 - 如果输入过于模糊，最多追加三轮聚焦问题。
 - 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
+- 如果需要判断 `micro / standard / complex` 分档，补读 `references/scales.md`。
 
 **退出条件**：
 - 问题可以用 1-2 句话说清楚。
@@ -23,113 +38,144 @@
 - 初步 slug。
 - devflow 规模分档：`micro` / `standard` / `complex`。
 
-## Phase 0.5 — Devflow 上下文收集
+## context — 上下文收集
 
-**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
+**进入条件**：clarify 已经有足够信息定位领域、项目或变更方向。
 
 **动作**：
+- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
+- 如果 `devflow/index.md` 不存在，先从 `devflow/projects/` 现有目录初始化轻量索引，再继续本次上下文收集。
 - 读取 `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` 冲突，暂停并向用户汇报。
 
 **退出条件**：
-- 已形成“OpenSpec 输入上下文摘要”。
+- 已形成"OpenSpec 输入上下文摘要"。
+- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
 - 已列出相关 ADR 和不能违反的历史决策。
 - 已列出需要写入或修正 OpenSpec 的上下文点。
 
 **输出**：
-- 上下文摘要，默认写入 `brief.md` 或 `evidence.md`；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。
+- 上下文摘要，写入 `decisions.md`（过程日志）。会影响实现的上下文必须标记为"需进入 OpenSpec"。
 
-## Phase 1 — OpenSpec propose
+## propose — 轻量 propose
 
-**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
+**进入条件**：clarify + context 已经足够生成轻量 proposal。
 
-**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
+**执行者**：sm-flow 内置协议。**不调用 openspec-propose**（完整 OpenSpec 产物留待 specify 阶段生成）。
 
 **动作**：
-- 优先调用 `openspec-propose`。
+- 创建或识别 `openspec/changes/{slug}/`。
-- 如果不可用，执行 `references/fallbacks.md#openspec-propose-fallback`，但仍必须产出 OpenSpec 文件。
+- 写入 `proposal.md`，包含：问题、建议方案、范围、非目标、来自 devflow 的上下文约束、风险。
-- 用 Phase 0.5 的 devflow 上下文增强 OpenSpec：
+- **不生成 design.md、specs/、tasks.md**——这些留待 grill 澄清需求后在 specify 阶段补全。
-  - proposal 写清为什么做、做什么、范围和非目标。
+- 用 context 阶段的 devflow 上下文增强 proposal。
-  - design 写入上下文约束、历史 ADR、关键技术决策。
+- 在承诺方案方向前，先检查相关仓库代码。
-  - specs 写成可验收的外部行为。
-  - tasks 写成可执行的纵向切片。
-- 在承诺设计细节前，先检查相关仓库代码。
 
 **退出条件**：
-- `openspec/changes/<slug>/proposal.md` 存在。
+- `openspec/changes/{slug}/proposal.md` 存在。
-- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。
+- 关键假设已显式记录。
-- 关键假设已显式记录在 OpenSpec 或 research 中。
 
 **输出**：
-- OpenSpec proposal、design、specs 和 task list。
+- Draft OpenSpec proposal.md（轻量版）。
 
 **Human checkpoint**：
-- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
+- 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。
-- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。
+- 作为 Discover checkpoint 的中间状态汇报；询问是否继续完成 Discover 的人类澄清部分。用户明确要求"全自动执行"时可跳过等待。
 
-## Phase 1.5 — PRD / OpenSpec 对齐
+## grill — 人类对齐澄清
 
-**进入条件**：Phase 1 已有 OpenSpec 产物。
+**进入条件**：propose 已有轻量 proposal.md。
 
-**显式子 skill**：`to-prd` + `sm-flow`。进入本阶段必须先声明是否读取 `.agents/skills/to-prd/SKILL.md`；如果使用内置模板，标记为 PRD fallback。
+**能力来源**：优先使用 `grill-with-docs`；不可用时使用 `references/fallbacks.md#grill-内置协议`，并在 `decisions.md` 标注 fallback。
-
-**动作**：
-- 如果没有结构化 PRD，则优先按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
-- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 `brief.md`。
-- 检查 PRD、devflow 上下文和 OpenSpec 是否一致：
-  - OpenSpec 是否覆盖 PRD 的用户故事和验收预期。
-  - OpenSpec 是否使用 glossary 中的正确术语。
-  - OpenSpec 是否遵守相关 ADR。
-  - specs 是否能表达可观察行为。
-  - tasks 是否能驱动实现，而不是泛泛描述。
-- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
-
-**退出条件**：
-- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
-- OpenSpec 与 PRD/devflow 上下文没有已知冲突。
-- 所有已知冲突已修正或等待用户决策。
-
-**输出**：
-- `brief.md`，以及按需创建的 `prd.md`。
-- OpenSpec 对齐检查记录。
-- 必要的 OpenSpec 修正。
-
-## Phase 2 — Human-in-the-loop 澄清
-
-**进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。
-
-**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。
 
 **动作**：
 - 优先使用 `grill-with-docs`。
-- 先声明本阶段采用的澄清模式，并逐项标记：
+- 进入 grill 时先建立一个 question pool，并记录到 `decisions.md`：
+  - 默认至少覆盖术语、边界、验收三个维度。
+  - **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
+    - 参考实现的具体文件路径是什么？
+    - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
+    - 有哪些技术点需要先调研或新建？
+  - 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。
+- 逐项标记每个问题的模式：
   - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
   - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
-- 至少覆盖三个维度：术语、边界、验收。
+- evidence-driven 和 user-interview 的推进节奏：先批量查证 evidence-driven 并一次性汇报结论，再逐个处理 user-interview 问题。不要把所有问题攒到最后一起问。
 - 一次只问一个 `user-interview` 问题。
-- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
+- 每个 `user-interview` 问题必须等待用户显式回答，并在 decisions.md 中记录：问题原文、用户原话、确认状态（已确认/未确认）。未确认的问题不能从 question pool 移除。
+- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 apply 或修改执行目标文件的授权。
+- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
+- 如果澄清结果影响实现，必须回写 proposal.md。
 - 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
 - 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
 
 **退出条件**：
-- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
+- question pool 已建立并覆盖当前 change 所需维度。
+- 已满足 `references/scales.md` 中当前分档的 grill 要求。每个问题都必须记录属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
-- 影响实现的结论已回写 OpenSpec。
+- 没有未解决或代理代确认的 user-interview 问题。
+- 没有未判级或未确认的接口影响问题。
+- 影响实现的结论已回写 proposal.md。
+- 单个 grill 决策确认不等于 apply 授权；grill 完成后必须停在 commit，等待用户明确要求进入 apply。
+- question pool、evidence-driven 结论、user-interview 确认必须写入 `decisions.md` 文件，不能只记录在对话中。
 
 **输出**：
-- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。
+- 更新后的 proposal.md。
-- 更新后的 OpenSpec。
+- 澄清记录：写入 `decisions.md`。包含 question pool、evidence-driven 汇报状态、user-interview 确认状态。
 - 更新后的词汇表和 ADR。
 
-## Phase 2.5 — 架构审计
+**Human checkpoint**：
+- 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。
+- 汇报 Discover checkpoint 完成情况，并询问是否继续进入 Commit checkpoint。
 
-**进入条件**：Phase 2 已解决主要产品、领域和验收问题。
+## specify — 细化 + 对齐
 
-**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。
+**进入条件**：grill 已退出，需求已通过澄清稳定下来。
+
+**能力来源**：优先使用 `openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；按需使用 `to-prd`。进入本阶段必须先声明调用方式；外部能力不可用时使用 `references/fallbacks.md#openspec-提案-内置协议`，并在 `decisions.md` 标注 fallback。
+
+**动作**：
+- 基于已稳定的 proposal.md 补全设计产物、specs/、tasks.md：
+  - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需按当前分档补全设计产物/specs/tasks"。
+  - 如果不可用，执行 `references/fallbacks.md#openspec-提案-内置协议`。
+- 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
+- 独立 PRD 是否需要按 `references/scales.md` 的当前分档和用户要求判断。
+- 用 grill 阶段的 decisions.md 记录增强 OpenSpec 产物：确保 design/specs/tasks 反映所有已确认的决策。
+- **显式 cross-artifact 对齐检查**——在 checkpoint 中输出对齐检查表：
+  - `brief/prd` 中的目标、范围、非目标和验收预期 → `proposal` 是否覆盖。
+  - `proposal` 中的范围、约束和关键承诺 → `design` 是否覆盖。
+  - `design` 中影响实现的约束、接口影响和架构结论 → `specs` 或 `tasks` 是否覆盖。
+  - `specs` 中的可观察行为 → `tasks` 是否覆盖为可执行切片。
+  - 每项标记：已对齐 / 存在 gap。
+- 检查是否涉及接口影响：
+  - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
+  - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
+  - 接口内部判断逻辑是否改变调用方可观察行为。
+  - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 `user-interview` 问题。
+- 如果存在 gap，在进入下一阶段前修复 OpenSpec。
+- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
+
+**退出条件**：
+- OpenSpec 细化产物存在且与 proposal 对齐；产物形态按 `references/scales.md` 的当前分档要求执行。
+- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
+- cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。
+- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。
+- 所有已知冲突已修正或等待用户决策。
+
+**输出**：
+- Draft OpenSpec：按 `references/scales.md` 的当前分档要求生成 proposal、设计、specs 和 tasks。
+- `brief.md`，以及按需创建的 `prd.md`。
+- cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。
+- 必要的 OpenSpec 修正。
+
+## audit — 架构审计
+
+**进入条件**：specify 已退出，完整 OpenSpec 产物已存在。
+
+**能力来源**：优先使用 `zoom-out`；不可用时使用 `references/fallbacks.md#audit-内置协议`，并在 `decisions.md` 标注 fallback。
 
 **动作**：
 - 画出输入 → 处理 → 输出的模块链路。
@@ -137,63 +183,170 @@
 - 检查是否与既有架构、ADR、OpenSpec design 冲突。
 - 用不超过五句话写出架构风险评估。
 - 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
+- 审计结论写入 `decisions.md`。
 
 **退出条件**：
-- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。
+- 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。
-- OpenSpec design/tasks 已反映会影响实现的架构审计结论。
+- OpenSpec 设计产物/tasks 已反映会影响实现的架构审计结论。
 
 **输出**：
-- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。
+- 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。
-- 必要的 OpenSpec design/tasks 修正。
+- 必要的 OpenSpec 设计产物/tasks 修正。
 
 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
-- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
+- 作为 Commit checkpoint 的中间状态汇报；询问是否继续完成 commit gate。
 
-## Phase 3 — OpenSpec apply
+## commit — Commit OpenSpec
 
 **进入条件**：
-- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
+- grill 已满足 `references/scales.md` 中当前分档要求。
-- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
+- 所有 `user-interview` 问题都已获得用户显式确认。
-- devflow 与 OpenSpec 没有未解决冲突。
+- audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。
-
+- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
-**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
 
 **动作**：
+- 检查 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 是否有独立接口文档或等价独立章节。
+- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
+- 如果检查失败，返回 propose、grill、specify 或 audit 修正 Draft OpenSpec。
+
+**退出条件**：
+- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
+- **文件完整性检查**（按 `references/scales.md` 的当前分档要求执行）：
+  - [ ] proposal 存在，且足以说明问题、建议方案、范围和非目标。
+  - [ ] 设计产物存在，形式符合当前分档要求。
+  - [ ] specs 存在，且表达用户可观察行为。
+  - [ ] tasks 存在，且任务可执行、验收标准可验证。
+- **一致性检查**（必须通过）：
+  - [ ] proposal 中的核心概念在设计产物中有对应设计
+  - [ ] 设计产物中的关键决策在 tasks 中有对应实现任务
+  - [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
+- **标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
+- 所有 preflight 风险已消除或明确记录为已接受。
+
+**输出**：
+- Committed OpenSpec 状态说明。
+- preflight 检查结果，写入 `decisions.md` 或 `acceptance.md`。
+
+**Human checkpoint**：
+- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
+- 汇报 Commit checkpoint 完成情况，并询问是否进入 Apply checkpoint；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
+- 不得把 grill 的单个决策确认当作本 checkpoint 的授权。
+
+## apply — OpenSpec 执行
+
+**进入条件**：
+- `openspec/changes/{slug}/` 中 proposal、设计产物、specs、tasks 已通过 commit，成为 Committed OpenSpec。
+- **前置门控检查**（硬约束）：
+  - 检查 `openspec/changes/{slug}/.committed` 文件是否存在
+  - 如不存在，执行以下流程：
+    1. 汇报：Draft OpenSpec 未通过 commit 检查
+    2. 列出缺失的 checkpoint 项（文件完整性、一致性检查）
+    3. 询问用户：是否补做 commit 检查；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`，且本次流程不得视为合规 sm-flow apply
+- commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。
+- devflow 与 OpenSpec 没有未解决冲突。
+- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
+
+**能力来源**：优先使用 `openspec-apply-change`；不可用时使用 `references/fallbacks.md#openspec-apply-内置协议`，并在 `decisions.md` 标注 fallback。遇到 bug/不确定行为时优先使用 `diagnose`；需要测试驱动时优先使用 `tdd`。不可用时执行对应最小协议并记录原因，不得静默跳过。
+
+**动作**：
+
+### Pre-apply Checkpoint
+
+**触发条件**：当 OpenSpec 涉及以下任一情况时必须执行
+- design 或 tasks 中提到"参考 XXX 实现"
+- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
+- 技术栈不熟悉或第一次在该项目实现类似功能
+
+**执行步骤**：
+1. **阅读所有参考实现**
+   - 从 OpenSpec design 或 tasks 中定位参考实现文件
+   - 如果路径不明确，通过 Grep 搜索关键类名或模式
+   - 理解关键逻辑，提取可复用代码片段和模式
+
+2. **Grep 关键技术栈**
+   - 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范）
+   - 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板）
+   - 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具）
+   - 异常处理和日志记录标准
+
+3. **形成技术栈清单并写入 decisions.md**
+   - 项目使用的请求/响应结构标准
+   - MQ 消息定义和发送标准
+   - Consumer 标准位置和写法
+   - 加密/验签/工具类的标准用法
+   - 识别需要新建的工具类或基础设施
+
+**输出要求**：
+- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节。
+- 已列出所有参考实现的文件路径。
+- 已识别需要新建的工具类/基础设施。
+
+**按风险执行**：执行深度按 `references/scales.md` 的当前分档和实现风险决定；退出判断以清单是否足以指导实现为准。
+
+### 实现过程
+
 - 优先调用 `openspec-apply-change`。
 - 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
 - 按 OpenSpec tasks 的纵向切片实现。
+- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
+- 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 apply 不算真正开始。
+- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
+- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，做三类判断：
+  - OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停 apply，修正 OpenSpec 后重新提交。
+  - 代码偏离（实现没按 OpenSpec 做）→ 修正代码，不改 OpenSpec。
+  - 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。
+- 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。
+- **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
 - 当用户要求、行为复杂或回归风险高时使用 TDD。
 - 当测试失败、行为意外或原因不确定时使用 diagnose。
 - 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
 - 修改文件前遵守仓库指令，例如 `AGENTS.md`。
 
 **退出条件**：
+- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`。
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
+- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位。
+- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。
 
 **输出**：
 - 代码变更、必要测试和实现说明。
 - 更新后的 OpenSpec task 状态。
+- 冲突记录写入 `decisions.md`。
 
-## Phase 4 — 回填 Devflow
+## archive — 回填 + 归档
 
 **进入条件**：实现或规划工作已经达到可交接状态。
 
-**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。
+**能力来源**：`openspec-archive-change` 在用户确认 archive 后优先调用；不可用时使用 `references/fallbacks.md#openspec-archive-内置协议`，并在 `acceptance.md` 标注 fallback。archive 回填由 `sm-flow` 执行。
 
 **动作**：
 - 遵循 `references/archive-rules.md`。
-- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
+- 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案：
+  - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
+  - `evidence.md`：按 `references/scales.md` 和 `references/archive-rules.md` 的当前分档要求处理。
+  - `decisions.md`：保持为最终版，整理格式。
+  - `acceptance.md`：从实现结果和验证结果提取。
+- 只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
 - 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
 - 如果本次流程产生可复用经验，写入 compound knowledge。
+- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。
 
 **退出条件**：
-- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
+- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
+- `devflow/index.md` 已包含或更新本项目条目。
 - 用户已被询问是否 archive OpenSpec change。
 
 **输出**：
-- 默认输出 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`；按需输出 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`、ADR 和 compound knowledge。
+- 完整 devflow 档案。
-
+- 归档交接清单：创建或更新了哪些文件、验证分类、剩余风险、是否 archive。

.agents/skills/sm-flow/references/scales.md

@@ -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。

.agents/skills/sm-flow/references/templates.md

@@ -51,11 +51,25 @@
 ```markdown
 # {标题} Decisions
 
+## Question Pool
+
+| # | 维度 | 问题 | 模式 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
+| Q2 | 边界 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
+| Q3 | 验收 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
+
+## Evidence-driven
+
+| 结论 | 证据来源 | 是否已汇报用户 |
+|---|---|---|
+| {conclusion} | {file/doc/test/ADR} | 已汇报 / 待汇报 |
+
 ## User-interview
 
-| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
+| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
-| --- | --- | --- | --- |
+|---|---|---|---|
-| {question} | {answer} | {decision} | 已回写 / 不影响 / 待回写 |
+| {question} | {user's exact words} | 已确认 / 未确认 | 已回写 / 不影响 / 待回写 |
 
 ## 关键取舍
 
@@ -65,6 +79,68 @@
   - 风险接受：{accepted by whom/when}
 ```
 
+## 接口影响记录模板
+
+```markdown
+# {标题} 接口影响记录
+
+## 分级
+
+- 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口
+- 判级原因：{why this level}
+- 是否需要独立接口文档：是 / 否
+
+## 变更对象
+
+- 接口/字段/DTO/事件/回调/数据库契约：
+- 判断逻辑变化：
+- 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无
+
+## 影响范围
+
+- 调用方/消费者：
+- 是否跨模块/跨服务/跨团队：
+- 旧调用方是否需要改动：
+
+## 兼容与迁移
+
+- 是否向后兼容：
+- 迁移/灰度/回滚要求：
+- 风险接受：
+
+## 验收方式
+
+- 如何证明新行为正确：
+- 如何证明旧行为未破坏：
+- 需要用户确认的问题：
+```
+
+## 实现期冲突记录模板
+
+```markdown
+# {标题} 实现期冲突记录
+
+## 冲突摘要
+
+- 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
+- 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
+- 分类：OpenSpec 不准 / 代码偏离 / 不确定
+
+## 证据
+
+- OpenSpec 依据：
+- 代码或测试证据：
+- 用户反馈：
+
+## 处理
+
+- 决策：
+- 是否需要用户确认：是 / 否
+- OpenSpec 回写：不需要 / 已回写 / 待回写 / 等待用户确认
+- 代码处理：
+- 验证方式：
+```
+
 ## PRD 模板
 
 ```markdown
@@ -267,6 +343,26 @@
 - OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用}
 ```
 
+## Cross-Artifact 对齐检查表模板
+
+specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"或"存在 gap"。
+
+```markdown
+## Cross-Artifact 对齐检查
+
+| 上游 → 下游 | 检查内容 | 状态 |
+|---|---|---|
+| brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap |
+| proposal → 设计产物 | 范围、约束、关键承诺是否进入 design.md 或等价设计小节 | 已对齐 / 存在 gap |
+| 设计产物 → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
+| specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap |
+
+### Gap 详情（如有）
+
+- gap 1：{描述哪个字段/约束/行为/切片只停留在上游，未进入下游}
+  - 修复：{如何修正 OpenSpec}
+```
+
 ## 复合知识模板
 
 ```markdown

.gitignore

@@ -1,4 +1,5 @@
 skill-workbench/validation/project/
 superpowers/
 .claude/
+.codex/
 *.stackdump

changelog/2026-04-30-skills-v0.5.0-consolidation.md

@@ -1,136 +0,0 @@
-# Skills v0.5.0 整合修复记录
-
-**日期：** 2026-04-30
-**来源：** grill-me 逐项审查，基于 v0.5.0 changelog 和 design doc 对比实际实现发现的不一致
-
----
-
-## 一句话摘要
-
-在前次 v0.5.0 slim architecture 改造的基础上，逐文件对比 design doc、proposal、plan、实际实现，修复了 `/essence` 遗漏项、`/follow` 旧引用残留、`/explore` 阶段冗余、references 死文件、docs 目录垃圾等问题。
-
----
-
-## 已完成的改动
-
-### 1. `/essence` — 补齐 v0.5.0 改造（之前遗漏）
-
-| 位置 | 修改内容 |
-|---|---|
-| 版本号 | `0.3.0` → `0.5.0` |
-| 透镜定义 | 删除 `(borrowed from /explore)`，声明为 `/essence` 自有 |
-| 透镜相关 Phase 2/3/4/5 表格 | 从独立 3 列表格瘦身为内联 bullet point |
-| HTML Card | `## Phase 6: Output (Optional HTML Card)` → `## Optional: HTML Card`；去 "production-critical" 条件，改为 `Only when the user explicitly requests it` |
-| HTML Card 死链接 | 删除 `Same as /explore.` 两处，改为自包含内容 |
-| Mode Selection 上下文感知 | 新增检测逻辑：来自 `/explore` → 默认 User-directed；独立启动 → 默认 Auto-detect |
-| Auto-detect 信号 | `Most imported file` → `Cross-module contract`（后端项目更准确） |
-
-### 2. `/follow` — 消除旧引用和设计偏差
-
-| 位置 | 修改内容 |
-|---|---|
-| Mode Selection | 新增前置报告感知：来自 `/explore` + 代码仓库 → Runnable；来自 `/explore` + 非代码 → Reader；来自 `/essence` → Reader |
-| Runnable Check | 删除重新扫描逻辑，改为从前置报告读取结论；运行时信号改为后端导向（`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile` 等） |
-| Reader Mode Flow | 从文件级 "Walk one core file" 提升为设计级 "Frame the learning goal around a core design" |
-| 教学规则 | `do not use "go read the code" as the default instruction without context` → `never say "go read the code" as a standalone instruction`；引用代码必须先交代设计上下文 |
-
-### 3. `/explore` — 合并冗余阶段
-
-| 位置 | 修改内容 |
-|---|---|
-| Phase 1+2 | `Phase 1: Positioning` + `Phase 2: Structure` 合并为 `Phase 1: Positioning & Structure` |
-| 阶段总数 | 5 Phase → 4 Phase |
-| Project Type Detection | 信号列表同步（`package.json` 不再为首例）；阶段跳过的编号更新 |
-| Outcome 模板 | `5/5` → `4/4` |
-
-### 4. References 清理
-
-| 文件 | 操作 |
-|---|---|
-| `skills/explore/references/deep-fission.md` | **删除** — 描述已移除的 Deep Fission 功能，引用不存在的 `/fission` 技能 |
-| `skills/essence/references/essence-signals.md` | `Most imported file` → `Cross-module contract`，与 SKILL.md 同步 |
-
-### 5. docs 存档清理
-
-| 文件 | 操作 | 原因 |
-|---|---|---|
-| `docs/superpowers/proposal.md` | 删除 | 原始 4-skill 提案，已过时 |
-| `docs/superpowers/plan.md` | 删除 | 实施模板与实际实现不一致 |
-| `docs/superpowers/plans/` | 删除 | 456 行 task-by-task 计划，含 `/map` 引用 |
-| `docs/superpowers/README.md` | 删除 | `superpowers/README.md` 的副本，不属于历史存档 |
-
----
-
-## docs 存档最终结构
-
-```
-docs/superpowers/
-├── specs/
-│   ├── issue.md                                    # 原始需求
-│   ├── 2026-04-21-skills-v0.5.0-slim-architecture-design.md
-│   └── 2026-04-21-skills-v0.5.0-changelog-design.md
-└── changelog/
-    ├── 2026-04-21-skills-v0.5.0-slim-architecture.md   # 第一次改造 changelog
-    ├── 2026-04-21-skills-v0.5.0-validation-handoff.txt # 交接指令
-    └── 2026-04-30-skills-v0.5.0-consolidation.md       # 本次整合（本文件）
-```
-
----
-
-## 当前 skill 状态
-
-| 技能 | 版本 | Phase/Mode | 备注 |
-|---|---|---|---|
-| `/explore` | v0.5.0 | 4 Phase | 支持代码/非代码仓库；合并 Positioning+Structure |
-| `/essence` | v0.5.0 | 5 Phase + Optional HTML | 透镜自有；上下文感知 Mode Selection |
-| `/follow` | v0.5.0 | Runnable / Reader | 来源感知；不再重新扫描项目 |
-
----
-
-## 实践验证结果
-
-**日期：** 2026-04-30  
-**测试目标仓库：**
-- 非代码仓库：explore-skill-family（自身）
-- 代码仓库：SuperBizAgent-java（Spring Boot + AI Agent）
-
-| # | 验证路径 | 目标 | 结果 |
-|---|---|---|---|
-| 1 | `/follow` 拒绝无前置报告 | 直接模拟 | ✅ |
-| 2 | `/explore` 非代码仓库 | 自身 skill family | ✅ — 正确识别 skill-docs，跳过 Flow/Start |
-| 3 | `/essence` 深挖 | "硬边界"设计 | ✅ — 结论-证据-解释，可迁移 |
-| 4 | `/explore` → `/follow` | 自身 | ✅ — Reader 分流，引用报告内容 |
-| 5 | `/essence` → `/follow` | 自身 | ✅ — design-focused，未重扫 |
-| 6 | 三技能职责边界 | 综合矩阵检查 | ✅ — 核心问题/深度/前置依赖/产出均无重叠 |
-| 7 | `/explore` 代码仓库 | SuperBizAgent-java | ✅ — 4 Phase 全流程，后端信号检测正常 |
-
-### 验证发现的额外修复
-
-验证过程中对 SKILL.md 的追加修改（已在代码中反映）：
-- `/essence` Phase 6 → Optional: HTML Card
-- `/essence` Mode Selection 上下文感知
-- `/essence` Most imported file → Cross-module contract
-- `/follow` Mode Selection 来源感知
-- `/follow` Runnable Check 不再重扫，引用前置报告
-- `/follow` Reader Mode Flow 提升到设计层
-- `/follow` Teaching Interaction Rules 收紧
-- `/explore` Phase 1+2 合并，5→4 Phase
-- `/explore` Project Type Detection 信号改为后端导向
-- 删除 `skills/explore/references/deep-fission.md`
-
-### handoff 10 条检查清单逐项结论
-
-| # | 问题 | 结论 |
-|---|---|---|
-| 1 | `/explore` 对代码/非代码给出不同输出？ | ✅ Phase 2/3 对非代码跳过 |
-| 2 | `/explore` 保持在项目级理解？ | ✅ Phase 4 概览深度 |
-| 3 | `/essence` 稳定找最高价值设计？ | ✅ "硬边界"提取到 pattern 层 |
-| 4 | `/follow` 无前置报告明确拒绝？ | ✅ 拒绝并引导 |
-| 5 | `/follow` 基于 /explore 或 /essence 结果？ | ✅ 两次测试均基于前置报告 |
-| 6 | `/follow` 避免重新扫描？ | ✅ 三次验证均未重扫 |
-| 7 | `/follow` 真正引导式教学？ | ✅ 先问后讲 |
-| 8 | 三技能职责重叠/模糊？ | ✅ 边界清晰 |
-| 9 | README 与实际行为一致？ | ✅ 三技能描述与 SKILL.md 一致 |
-| 10 | references 与 v0.5.0 一致？ | ✅ deep-fission 已删，signals 已同步 |
-
-**总体验收结论：通过。** 文档、边界、行为三者一致。

devflow/glossary/CONTEXT.md

@@ -16,7 +16,7 @@
 ### 真理源 (Source of Truth)
 - **日期**和**短标识符 (slug)**：由目录名 `knowledge_YYYYMMDD_Slug/` 提取。
 - **显示标题**、**tags**、**author**：由 YAML frontmatter 提取。
-详见 [ADR-001](./adr/0001-directory-name-as-truth-source.md)。
+详见 [decision.md](../../openspec/changes/knowledge-index-panel/decision.md)（原 ADR-001，2026-09-18 迁移）。
 
 ### 短标识符 (Slug)
 目录名中 `YYYYMMDD_` 之后的部分。用于脚本定位目录和构建文件路径。不用于显示（显示标题来自 YAML frontmatter 的 `title` 字段）。

devflow/index.md

@@ -0,0 +1,13 @@
+# devflow 索引
+
+> 本文件由 scripts/check-dev-flow.sh --index 派生生成,**不要手写**。
+> 存储层是 openspec/archive/ 下的归档目录;此处只是浏览视图。
+
+| 日期 | 标题 | 归档位置 |
+|---|---|---|
+| 2026-05-25 | knowledge-index-sort Proposal | openspec/changes/archive/2026-05-25-knowledge-index-sort |
+| 2026-09-18 | Decision: 建立旧 devflow 档案的迁移规则 | openspec/changes/archive/2026-09-18-migrate-devflow-archives |
+| 2026-05-19 | 2026-05-19-add-clear-filters | openspec/archive/2026-05-19-add-clear-filters |
+| 2026-05-21 | 2026-05-21-sm-flow-v3-1-upgrade | openspec/archive/2026-05-21-sm-flow-v3-1-upgrade |
+| 2026-07-05 | Validate SM Flow Explicit Trigger | openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger |
+| 2026-07-05 | Validate SM Flow Standard Change | openspec/archive/2026-07-05-validate-sm-flow-standard-change |

devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/acceptance.md

@@ -0,0 +1,59 @@
+# SM Flow v3.1 Upgrade Acceptance
+
+## 结果
+
+已接受。
+
+## 验证
+
+### 静态验证
+
+- 命令/检查：`openspec status --change "sm-flow-v3-1-upgrade"`
+- 结果：passed
+- 备注：proposal、design、specs、tasks 均为 complete。
+
+- 命令/检查：`rg -n "Draft OpenSpec|Committed OpenSpec|Phase 2.9|devflow/index.md|接口影响|实现期冲突|能力契约|平台原生 skill|user-interview" ...`
+- 结果：passed
+- 备注：关键术语已覆盖 `.agents/skills/sm-flow/`、OpenSpec change、workflow 文档和 devflow 项目档案。
+
+### 脚本验证
+
+- 命令：`openspec instructions apply --change "sm-flow-v3-1-upgrade" --json`
+- 结果：passed
+- 备注：所有 17 个 OpenSpec tasks 已完成。
+
+### 浏览器/人工验证
+
+- 步骤：不适用，本次是流程文档和 OpenSpec 规则改造。
+- 结果：not run
+- 备注：无 UI 行为。
+
+## 已完成范围
+
+- 增加 Draft OpenSpec / Committed OpenSpec / Phase 2.9 commit gate。
+- 强化 Phase 2 grill 的显式人工确认约束。
+- 增加“单个 grill 决策确认不等于 Phase 3 apply 授权”的硬约束。
+- 增加接口影响 L1-L4 分级和接口影响记录模板。
+- 增加 `devflow/index.md` 和 Phase 0.5 / Phase 4 索引维护规则。
+- 增加 Phase 3 实现期冲突四分类和 fallback 执行规则。
+- 将子 skill 兼容规则改为能力契约优先、路径其次。
+- 更新 `skill-workbench/docs/sm-flow/workflow.md` 的 v3.1 说明。
+
+## 已知限制
+
+- `openspec/config.yaml` 由 OpenSpec CLI 创建并保持未跟踪状态。
+- 工作区存在与本次无关的已删除文件，未处理。
+
+## 流程偏差记录
+
+- 偏差：本次执行中，Phase 2 grill 决策确认后曾直接进入执行文件修改，没有显式停在 Phase 2.9 checkpoint 等待 Phase 3 apply 授权。
+- 分类：实现偏差。v3.1 规格方向正确，但执行过程没有严格遵守“grill 确认 ≠ apply 授权”的门禁。
+- 修正：已回写 OpenSpec，新增 requirement 和 task，要求 Phase 2/2.5 回写后必须停在 Phase 2.9，并等待明确 Phase 3 apply 授权。
+- 当前状态：用户已明确授权“执行apply”，该新增 requirement 已应用到 `.agents/skills/sm-flow/*` 和 workflow 文档。
+
+## 交接
+
+- 下一步：已归档，后续可从 devflow 档案和 OpenSpec archive 回溯。
+- OpenSpec 归档确认：用户已确认归档。
+- OpenSpec 归档位置：`openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/`
+- Specs 同步：未执行；本仓库 `openspec/specs/` 当前无主 spec 文件，本次保留 delta specs 于 archive 中。

devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/brief.md

@@ -0,0 +1,30 @@
+# SM Flow v3.1 Upgrade Brief
+
+## 背景
+
+- 用户目标：把 `sm-flow` v3 使用中暴露的接口文档、流程顺序、上下文定位、子 skill 兼容和实现期冲突问题固化为 v3.1 协议。
+- 当前问题：v3 已经确立 OpenSpec-first，但缺少接口影响分级、Draft/Committed OpenSpec gate、devflow 索引和 Phase 3 冲突沟通规则。
+- 关联 OpenSpec：`openspec/changes/sm-flow-v3-1-upgrade/`
+- devflow 分档：standard
+
+## 范围
+
+- 本次要做：更新 `sm-flow` skill 本体、phase contracts、fallbacks、templates、workflow 说明，并创建/维护 devflow 索引。
+- 本次不做：修改业务代码、重写 OpenSpec CLI、把 devflow 变成执行真理源、强制所有接口变更都独立产出接口文档。
+- 影响区域：
+  - `.agents/skills/sm-flow/SKILL.md`
+  - `.agents/skills/sm-flow/references/*.md`
+  - `skill-workbench/docs/sm-flow/workflow.md`
+  - `devflow/index.md`
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖
+- specs 覆盖状态：已覆盖
+- tasks 覆盖状态：已覆盖
+
+## OpenSpec 输入上下文摘要
+
+- v3 历史决策：`devflow/` 是上下文真理源，OpenSpec 是执行真理源，代码是实现结果。
+- 用户问题来源：`skill-workbench/docs/sm-flow/使用问题.md`，共 6 个问题，集中在接口产物、流程顺序、上下文检索、子 skill 兼容和实现期冲突。
+- 历史评估来源：`devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md`，已确认子 skill fallback、quick 模式、Phase 退出条件和 OpenSpec-first 是 v3 的关键设计。

devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/decisions.md

@@ -0,0 +1,39 @@
+# SM Flow v3.1 Upgrade Decisions
+
+## User-interview
+
+| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
+| --- | --- | --- | --- |
+| 是否启动 v3.1 改造？ | “开始这次的v3.1改造” | 创建 `sm-flow-v3-1-upgrade` OpenSpec change 并进入改造。 | 已回写 |
+| grill 过程中是否必须人工确认？ | 用户要求“如果 skill 里并没有强调 grill 的过程中一定要人工确认的话，加上这个约束”。 | Phase 2 的 user-interview 问题必须一问一答等待用户显式确认；未确认不能进入 Phase 2.9 / Phase 3。 | 已回写 |
+| 接口变更是否需要记录影响范围？ | 用户要求“只要涉及接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中”。 | 所有接口变更必须有影响记录。 | 已回写 |
+| 接口影响采用什么分级策略？ | 用户确认“可以，先按照分级来实现”。 | 采用 L1-L4 分级：L1 内部实现、L2 内部接口、L3 协作接口、L4 破坏性接口；接口内部判断逻辑按可观察行为评估。 | 已回写 |
+| devflow 上下文索引是否强制维护？ | 用户确认“可以”。 | 强制维护轻量 `devflow/index.md`；Phase 0.5 先查 index，Phase 4 回填时必须更新 index。 | 已回写 |
+| 实现阶段遇到与原设计冲突的质疑或修改时如何处理？ | 用户确认“可以”。 | Phase 3 采用四类实现期冲突分类：实现偏差、规格遗漏、设计冲突、用户变更；先分类和确认，再继续代码或 OpenSpec 修正。 | 已回写 |
+| 子 skill 兼容规则是否采用能力优先？ | 用户确认“可以”。 | 子 skill 绑定能力契约，不绑定单一平台路径；调用优先级为平台原生 skill、本地 `SKILL.md`、sm-flow fallback。 | 已回写 |
+| 单个 grill 决策确认是否等于 apply 授权？ | 用户确认“可以”。 | 单个 `user-interview` 的“可以”只确认该决策；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，等待明确 Phase 3 apply 授权。 | 已回写 |
+
+## Evidence-driven 澄清
+
+| 维度 | 模式 | 问题 | 证据 / 用户反馈 | 结论 | 是否回写 OpenSpec |
+| --- | --- | --- | --- | --- | --- |
+| 术语 | evidence-driven | “接口影响范围文档”和“接口文档”是否同一产物？ | 用户分别列为两个问题；流程需要降低文档重复。 | 区分“接口影响记录”和“独立接口文档”。 | 是 |
+| 边界 | evidence-driven | v3.1 是否要改变 OpenSpec-first 主轴？ | v3 skill 本体和历史评估都把 OpenSpec 定义为执行真理源。 | 不改变主轴，只补 gate。 | 是 |
+| 验收 | evidence-driven | 如何证明 v3.1 改造完成？ | OpenSpec specs 已覆盖接口影响、commit gate、上下文索引和 apply 冲突处理。 | 验收以文档规则可检索、OpenSpec status 完成、tasks 勾选为准。 | 是 |
+
+## 关键取舍
+
+- 决策：采用 Draft / Committed OpenSpec，而不是把 grill 移到 propose 前。
+  - 原因：Draft 给澄清提供结构化对象，Committed 防止草稿直接执行。
+  - 影响：新增 Phase 2.9，但减少 Phase 3 规格漂移。
+  - 风险接受：本次 v3.1 接受。
+
+- 决策：接口变更采用 L1-L4 分级。
+  - 原因：所有接口影响都需要追踪，但只有高影响变更需要独立接口文档。
+  - 影响：templates 和 phase contracts 需要增加接口影响记录。
+  - 风险接受：本次 v3.1 接受。
+
+- 决策：为 devflow 增加 `devflow/index.md`。
+  - 原因：项目档案增长后，需要索引而不是每次全量翻阅。
+  - 影响：Phase 0.5 和 Phase 4 都需要维护索引。
+  - 风险接受：本次 v3.1 接受。

devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/evidence.md

@@ -0,0 +1,28 @@
+# SM Flow v3.1 Upgrade Evidence
+
+## 证据
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| `skill-workbench/docs/sm-flow/使用问题.md` | 用户列出 6 个实践问题，包含接口文档、propose/grill 顺序、devflow 检索、子 skill 兼容、Phase 3 设计冲突。 | v3.1 应围绕这些使用摩擦改协议，而不是重写整个流程。 | 是 |
+| `.agents/skills/sm-flow/SKILL.md` | 当前核心规则已要求 Phase 0.5、Phase 2、Phase 2.5、Phase 3、Phase 4，但没有 Draft/Committed OpenSpec 和接口影响分级。 | 新规则应补 gate，不应推翻 v3 的 OpenSpec-first 主从关系。 | 是 |
+| `.agents/skills/sm-flow/references/phase-contracts.md` | Phase 1 生成 OpenSpec 后进入 Phase 1.5/2/2.5，Phase 3 以 OpenSpec 执行；缺少 Phase 2.9 提交检查。 | “propose 后 grill 返工”应通过草稿/提交分离解释和治理。 | 是 |
+| `.agents/skills/sm-flow/references/fallbacks.md` | 执行 fallback 已要求失败原因不确定时 diagnose，规格不准先修 OpenSpec。 | 可扩展为 Phase 3 实现期冲突分类，不需要新建完全独立流程。 | 是 |
+| `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 Claude 工具耦合、子 skill 调用方式不稳、Phase 退出条件不足。 | v3.1 的兼容规则应绑定能力契约，而不是绑定具体平台路径。 | 是 |
+
+## Evidence-driven 结论
+
+- 结论：v3.1 应保留 v3 主轴，只增加 gate 和分级规则。
+  - 证据：当前 skill 文件和 phase contracts 已经清楚表达 OpenSpec-first。
+  - 风险：如果重写阶段顺序，容易引入新的执行歧义。
+  - 用户确认：已通过“开始这次的 v3.1 改造”确认推进。
+
+- 结论：接口文档应分级，不应一刀切。
+  - 证据：用户同时提出“接口影响范围文档”和“接口文档”，说明需要区分影响记录与独立文档。
+  - 风险：分级阈值不清会导致代理低估外部契约风险。
+  - 用户确认：需要在实现时以不确定则确认为规则。
+
+- 结论：Phase 3 应增加实现期沟通规则，而不是让代码建议直接覆盖 OpenSpec。
+  - 证据：用户明确要求“不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到”。
+  - 风险：沟通 gate 会暂停执行，但能保护规格真理源。
+  - 用户确认：已确认这是 v3.1 重点。

devflow/projects/2026-05-22-sm-flow-execution-hardening/acceptance.md

@@ -0,0 +1,40 @@
+# SM Flow Execution Hardening Acceptance
+
+## Result
+
+Implemented `sm-flow-execution-hardening` as protocol/document changes only.
+
+Updated artifacts:
+
+- `.agents/skills/sm-flow/SKILL.md`
+- `.agents/skills/sm-flow/references/phase-contracts.md`
+- `.agents/skills/sm-flow/references/fallbacks.md`
+- `skill-workbench/docs/sm-flow/workflow.md`
+- `openspec/changes/sm-flow-execution-hardening/tasks.md`
+
+## Verification
+
+- Static verification:
+  - Confirmed explicit phase checkpoint and stage-completion rules exist in `SKILL.md`.
+  - Confirmed Phase 2 question-pool behavior and Phase 1.5 / 2.9 cross-artifact checks exist in `phase-contracts.md`.
+  - Confirmed fallback declaration and recording requirements exist in `fallbacks.md`.
+  - Confirmed `workflow.md` explains the same execution-hardening model without introducing mandatory output templates.
+- OpenSpec verification:
+  - Implementation/documentation tasks `1.1` to `3.2` are complete.
+  - Validation tasks `4.1` to `4.4` are complete.
+
+## Acceptance Scope Check
+
+- Satisfied by protocol/document changes alone: yes
+- Requires standardized phase-report output format: no
+- Requires fixed checkpoint/alignment templates: no
+
+## Unverified
+
+- OpenSpec CLI validation passed: `openspec validate sm-flow-execution-hardening`.
+- No automated tests were needed because this change only modifies protocol and documentation artifacts.
+
+## Archive Status
+
+- OpenSpec change is not archived.
+- User still needs to be asked whether to archive after validation is complete.

devflow/projects/2026-05-22-sm-flow-execution-hardening/brief.md

@@ -0,0 +1,31 @@
+# SM Flow Execution Hardening Brief
+
+## 背景
+
+- 用户目标：把 `sm-flow` 在真实项目执行中暴露出的流程失真问题，提炼为下一轮协议硬化需求。
+- 当前问题：`sm-flow` 已经具备完整阶段规则，但实际执行时仍会出现跳过检查点、弱化显式声明、问题池不足、Cross-artifact 一致性检查不充分等情况。
+- 关联 OpenSpec：`openspec/changes/sm-flow-execution-hardening/`
+- devflow 分档：complex
+
+## 范围
+
+- 本次要做：把复盘中的执行问题整理为结构化需求，明确目标、非目标、用户故事、验收口径和建议改进方向。
+- 本次不做：立即修改 `sm-flow` 协议、直接创建 OpenSpec change、重写 `sm-flow` 主设计。
+- 影响区域：
+  - `.agents/skills/sm-flow/SKILL.md`
+  - `.agents/skills/sm-flow/references/phase-contracts.md`
+  - `.agents/skills/sm-flow/references/fallbacks.md`
+  - `.agents/skills/sm-flow/references/templates.md`
+  - `skill-workbench/docs/sm-flow/workflow.md`
+  - `skill-workbench/docs/sm-flow/retrospective.md`
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖
+- specs 覆盖状态：已覆盖
+- tasks 覆盖状态：已覆盖
+
+## 入口摘要
+
+- 这次需求关注的不是 `sm-flow` 的理念是否成立，而是它在真实执行中为什么仍然会“按代码习惯行动”，而不是“按 phase gate 行动”。
+- 目标是把这些问题固化为更强的执行约束，让后续代理在 `micro` 或 `standard` 模式下也不再轻易跳过关键阶段。

devflow/projects/2026-05-22-sm-flow-execution-hardening/decisions.md

@@ -0,0 +1,76 @@
+# SM Flow Execution Hardening Decisions
+
+## User-interview
+
+| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
+| --- | --- | --- | --- |
+| 这次是否将复盘问题提炼为正式需求？ | “[$sm-flow] 提炼成需求” | 创建 `sm-flow-execution-hardening` 需求档案，先收敛需求，再决定是否进入 OpenSpec。 | 不影响 |
+| 是否必须产出固定 checkpoint / alignment 模板？ | “确认 1” | 不强制固定模板；协议只要求必填字段和检查动作。 | 已回写 |
+| 验收是否要求统一阶段汇报格式？ | “确认1” | 验收停在协议明确 gate、问题池和对齐规则，不要求统一阶段汇报格式。 | 已回写 |
+
+## Phase 2 Tracking
+
+| 问题池项 | 模式 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| Q1：是否必须产出固定 checkpoint / alignment 模板 | user-interview | 待确认 | 会影响 templates.md 与 tasks 范围 |
+| Q2：协议主术语采用 checkpoint 还是 checklist | evidence-driven | 待整理 | 优先由现有文档术语一致性决定 |
+| Q3：验收是否要求统一阶段汇报格式 | user-interview | 已确认 | 验收停在规则层，不扩到统一输出格式 |
+| Q4：workflow 是否需要保留复盘案例示例 | evidence-driven | 待整理 | 主要影响 workflow 文档粒度 |
+
+## Phase 2.5 审计结论
+
+- 决策：主术语采用 `checkpoint`，`checklist` 作为内部核对动作描述。
+  - 原因：仓库现有 `phase-contracts.md` 已使用 `Human checkpoint`，继续沿用能减少术语漂移。
+  - 影响：后续协议修改应优先写“phase checkpoint”，避免在规则层混用主术语。
+  - 风险接受：当前接受
+
+- 决策：`workflow.md` 不扩成案例手册，继续保留规则抽象和演进说明；具体复盘案例留在 `retrospective.md`。
+  - 原因：如果把案例并入 workflow，规则与示例会双份维护，后续更容易漂移。
+  - 影响：执行真理源继续留在 `SKILL.md` / `phase-contracts.md` / OpenSpec，而不是 workflow 长文。
+  - 风险接受：当前接受
+
+## Phase 2.9 Commit Result
+
+- 决策：`sm-flow-execution-hardening` 当前 Draft OpenSpec 通过 commit gate，视为 Committed OpenSpec。
+  - 原因：proposal、design、specs、tasks 已完整；user-interview 已确认；evidence-driven 结论已汇报；未发现 devflow/OpenSpec 冲突。
+  - 影响：可以进入 Phase 3 修改协议文件，但仍需单独的 apply 授权。
+  - 风险接受：当前接受
+
+## 关键取舍
+
+- 决策：将本轮定位为 `complex` 分档。
+  - 原因：虽然不涉及业务代码，但它影响 `sm-flow` 的多个核心文件、阶段协议和验收方式，且包含多处跨文档一致性约束。
+  - 影响：使用 `brief.md`、`prd.md`、`evidence.md`、`decisions.md` 四类产物，而不是只写简短 brief。
+  - 风险接受：当前接受
+
+- 决策：不复用 `sm-flow-v3-1-upgrade` 项目，而是新开需求档案。
+  - 原因：`v3.1` 已归档且目标不同；本轮关注的是执行稳定性，不宜混入已完成升级项目。
+  - 影响：后续若进入 OpenSpec，可独立创建新 change。
+  - 风险接受：当前接受
+
+- 决策：将“规则存在但执行不稳”定义为首要问题。
+  - 原因：复盘中的多个现象都能收敛到这一点，能避免后续需求继续发散。
+  - 影响：后续需求改造应优先考虑 checklist、阶段 gate、显式声明和一致性检查。
+  - 风险接受：当前接受
+
+## Phase 3 Implementation Record
+
+- 决策：Phase 3 以本地 `openspec-apply-change` `SKILL.md` 作为 capability 来源继续执行。
+  - 原因：当前环境可读取对应 skill 协议，且用户已通过“apply”明确授权进入 Phase 3。
+  - 影响：本轮实现按 committed OpenSpec 的 task 切片直接修改协议与工作流文档。
+  - 风险接受：当前接受
+
+- 决策：本轮不修改 `templates.md`。
+  - 原因：用户已确认不要求固定 checkpoint / alignment 模板，也不要求统一阶段汇报格式；OpenSpec task 2.4 的目标是保持模板可选。
+  - 影响：实现集中在 `SKILL.md`、`phase-contracts.md`、`fallbacks.md`、`workflow.md`，避免把协议硬化扩大成模板标准化。
+  - 风险接受：当前接受
+
+- 决策：把“checkpoint 缺失则阶段不算完成”写入顶层协议和阶段契约，而不是只放在说明文档。
+  - 原因：这是决定阶段能否前进的硬 gate，必须落在执行真理源。
+  - 影响：Phase 0、0.5、1、2、2.5、2.9 现在都需要显式 checkpoint 和 capability 声明。
+  - 风险接受：当前接受
+
+- 决策：将 Phase 2 question pool、Phase 1.5/2.9 cross-artifact 对齐、`micro` gate 保留和 fallback 记录要求同步落在协议正文与 workflow 说明。
+  - 原因：这些规则既要可执行，又要便于人类理解；单独放在一处容易再次漂移。
+  - 影响：OpenSpec、协议正文和 workflow 解释层的关键术语已收敛到同一套执行规则。
+  - 风险接受：当前接受

devflow/projects/2026-05-22-sm-flow-execution-hardening/evidence.md

@@ -0,0 +1,106 @@
+# SM Flow Execution Hardening Evidence
+
+## 证据
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| `skill-workbench/docs/sm-flow/retrospective.md` | 逐 Phase 复盘了一次真实执行，明确记录了 Phase 0、0.5、1.5、2、2.5、2.9、4 的实际偏差。 | 当前主要问题是执行偏差和自检不足，不是流程理念方向错误。 | 是 |
+| `skill-workbench/docs/sm-flow/workflow.md` | v3.1 已经补入 Draft/Committed OpenSpec、接口影响分级、Phase 2.9、Phase 3 冲突分类等规则。 | 新一轮需求不应继续扩展原则，而应硬化执行协议。 | 是 |
+| `.agents/skills/sm-flow/SKILL.md` | 已明确 Phase 0.5、2、2.9 不可跳过，且要求显式 skill/fallback 声明。 | 当前缺口在于代理执行时没有被强制逐项核对这些规则。 | 是 |
+| `.agents/skills/sm-flow/references/phase-contracts.md` | 每个 Phase 已有进入条件、动作、退出条件和 checkpoint。 | 还缺一个更短、更高频的执行时 checklist 机制。 | 是 |
+| `.agents/skills/grill-with-docs/SKILL.md` | 明确要求 one-at-a-time 提问，并在可探索时优先查代码。 | Phase 2 的问题不是缺规则，而是没有把“问题池 + 单题推进”落成稳定动作。 | 是 |
+| `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 `SKILL.md` 更像设计说明书，缺少执行时检查点。 | 本轮需求与历史评估一致，属于同一产品化方向的继续深化。 | 是 |
+| `openspec/changes/sm-flow-execution-hardening/proposal.md` | Draft proposal 已将变更范围收敛到 phase checkpoint、问题池、cross-artifact alignment、micro gate preservation。 | Phase 1.5 已完成大方向对齐，未决问题主要落在“是否要求固定记录格式”这一类实现边界。 | 是 |
+| `openspec/changes/sm-flow-execution-hardening/design.md` | Draft design 已明确 checkpoint、问题池、cross-artifact 检查链路和 devflow 过程内同步更新。 | Phase 2 需要确认的重点不再是方向，而是边界和验收粒度。 | 是 |
+
+## Evidence-driven 结论
+
+- 结论：`sm-flow` 当前最需要的是“执行硬化”，不是“设计重构”。
+  - 证据：v3.1 已经把主从关系、gate 和冲突分类写清楚，但真实执行仍偏离。
+  - 风险：如果继续增加理念说明，可能让文档更长，但不提升执行稳定性。
+  - 用户确认：不需要
+
+- 结论：Phase 1.5 和 2.9 的 cross-artifact 检查应成为优先增强点。
+  - 证据：复盘里 `proposal` 漏字段未被代理提前发现，直到用户 review 才暴露。
+  - 风险：如果这两层不稳，Phase 2 即使问得更全，问题仍会漏到 apply 前后。
+  - 用户确认：不需要
+
+- 结论：`micro` 模式的误用是本次偏差的重要诱因。
+  - 证据：复盘根因明确指出“高估了小改动判断，误以为 micro 可以跳检查”。
+  - 风险：若不把这点写得更硬，后续类似问题会重复出现。
+  - 用户确认：不需要
+
+## Phase 1.5 对齐检查
+
+- `brief/prd` -> `proposal`：已对齐
+  - 覆盖了执行硬化而非主设计重构、影响文件范围、非目标边界。
+- `proposal` -> `design`：已对齐
+  - 设计已展开 checkpoint、问题池、cross-artifact alignment、micro gate preservation 和 devflow 过程内更新。
+- `design` -> `specs`：已对齐
+  - 已拆出 `sm-flow-phase-checkpoints`、`sm-flow-question-pool`、`sm-flow-cross-artifact-alignment`、`sm-flow-micro-gate-preservation` 四个 capability spec。
+- `specs` -> `tasks`：部分对齐，仍有一个边界待确认
+  - 当前 tasks 写了“如有需要则更新模板”，但是否必须定义固定记录格式，尚未明确。
+- `specs` -> `tasks`：现已对齐
+  - 用户已确认这轮不强制固定模板，也不把统一阶段汇报格式纳入验收，因此 tasks 保持“协议强化优先，模板仅按需微调”。
+
+## Phase 2 Question Pool
+
+- Q1 `user-interview` / 范围：
+  - 这次 change 是否必须产出固定的 checkpoint / alignment 记录模板，还是只要求协议定义必填字段即可。
+  - 状态：已确认为后者。
+- Q2 `evidence-driven` / 术语：
+  - `phase checkpoint`、`phase checklist`、`stage-completion rule` 三个说法里，哪个作为协议中的主术语最稳。
+- Q3 `user-interview` / 验收：
+  - 验收是以“文档明确要求这些门禁”为准，还是要进一步要求代理输出统一格式的阶段汇报。
+  - 状态：已确认采用前者。
+- Q4 `evidence-driven` / 边界：
+  - 这次是否需要把 retrospective 中的具体案例映射到 workflow 文档中的示例，还是只保留规则层抽象。
+
+## Phase 2.5 架构审计
+
+- 输入 -> 处理 -> 输出链路
+  - `retrospective.md` / 现有 `sm-flow` 协议 / 已归档 OpenSpec change
+  - -> `SKILL.md` 核心规则、`phase-contracts.md` 阶段契约、`fallbacks.md` 降级协议、按需 `templates.md`
+  - -> `workflow.md` 设计说明、`devflow` 过程记录、最终可提交的 OpenSpec
+
+- 模块职责
+  - `.agents/skills/sm-flow/SKILL.md`：放短而硬的总规则、gate 和主从关系。
+  - `.agents/skills/sm-flow/references/phase-contracts.md`：放逐阶段的进入/动作/退出条件与 checkpoint。
+  - `.agents/skills/sm-flow/references/fallbacks.md`：放 capability 不可用时的降级协议和记录要求。
+  - `.agents/skills/sm-flow/references/templates.md`：只放稳定模板，不承载这轮的主逻辑。
+  - `skill-workbench/docs/sm-flow/workflow.md`：保留设计说明和演进脉络，不承载执行真理源。
+
+- 架构风险评估
+  - 当前最大风险不是规则缺失，而是把同一条规则分散到 `SKILL.md`、`phase-contracts.md`、`workflow.md` 后出现漂移。
+  - 这轮 change 如果把“checkpoint”同时做成规则、模板和示例，容易再次扩大维护面。
+  - 更稳的做法是让 `SKILL.md` 和 `phase-contracts.md` 成为主落点，`workflow.md` 只解释，不重复列执行细则。
+  - `templates.md` 应保持可选和轻量，否则会把“协议硬化”扩成“输出格式标准化”。
+- 审计结论与当前 Draft OpenSpec 一致，不需要新增 capability，只需要在实现时严格控制规则落点。
+
+## Phase 2.9 Commit Gate
+
+- proposal：通过
+  - 已覆盖变更原因、范围、非目标、关键边界，以及“不强制固定模板 / 不要求统一阶段汇报格式”的范围约束。
+- design：通过
+  - 已覆盖 checkpoint、问题池、cross-artifact alignment、micro gate preservation、devflow 过程内更新和规则落点分层。
+- specs：通过
+  - 已覆盖四个新增 capability，且行为描述集中在可观察的协议要求。
+- tasks：通过
+  - 已覆盖协议修改、workflow 更新、校验和验收边界验证。
+- user-interview：通过
+  - 两个需要用户确认的问题均已确认并回写。
+- evidence-driven：通过
+  - 术语与 workflow 粒度问题已通过现有文档证据收束。
+- devflow / OpenSpec 冲突：未发现
+
+结论：当前 Draft OpenSpec 已达到可执行状态，可视为 Committed OpenSpec，进入 Phase 3 前仅缺明确 apply 授权。
+
+## Phase 3 Apply Evidence
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| `.agents/skills/sm-flow/SKILL.md` | 已新增显式 checkpoint 完成规则、question pool 规则、cross-artifact 对齐规则、`micro` gate 保留规则和 devflow 分阶段更新规则。 | 顶层协议已把执行硬化从“建议”提升为阶段完成条件。 | 是 |
+| `.agents/skills/sm-flow/references/phase-contracts.md` | 已新增 Phase 1.5 对齐链检查、Phase 2 问题池建立、Phase 2.9 闭环复核、Phase 3 capability 启动汇报和 Phase 4 consolidation 约束。 | 逐阶段执行契约已经覆盖 committed OpenSpec 的核心要求。 | 是 |
+| `.agents/skills/sm-flow/references/fallbacks.md` | 已新增统一 fallback 记录要求，并在各 fallback 协议中补入记录动作。 | 降级执行现在是可见、可审计的协议事件。 | 是 |
+| `skill-workbench/docs/sm-flow/workflow.md` | 已新增 question pool、Phase Checkpoint、Cross-Artifact Alignment、Micro 不是 Skip、fallback 记录要求等说明。 | retrospective 中的经验已被提升为稳定规则，而不是仅停留在叙述层。 | 是 |
+| `openspec/changes/sm-flow-execution-hardening/tasks.md` | 已完成 1.1-3.2，文档实现范围已落地。 | Phase 3 的协议/文档实现部分已完成，剩余工作转入验证与验收。 | 是 |

devflow/projects/2026-05-22-sm-flow-execution-hardening/prd.md

@@ -0,0 +1,67 @@
+# SM Flow Execution Hardening PRD
+
+## 问题陈述
+
+`sm-flow` 已经定义了较完整的阶段、规则和 reference 文件，但在真实项目执行中，代理仍然会把它当成“有帮助的流程建议”，而不是“必须逐阶段满足的执行协议”。结果是：
+
+- Phase 0 没有形成入口摘要和已知影响区域。
+- Phase 0.5 没有及时初始化和维护 `devflow/` 项目档案。
+- Phase 1 没有显式声明 skill 或 fallback，Draft / Committed OpenSpec 的边界不稳定。
+- Phase 1.5 被跳过，导致 proposal / design / research / specs / tasks 之间的一致性缺口直到用户 review 才暴露。
+- Phase 2 虽然收集了证据，但没有以结构化问题池和 one-at-a-time 的方式稳定执行。
+- Phase 2.5 被跳过，架构链路和接口影响没有提前暴露。
+- Phase 2.9 缺少强制自检，无法可靠发现 cross-artifact 遗漏。
+
+这说明当前痛点不是缺少理念，而是缺少“执行时自检”和“阶段切换门禁”的产品化机制。
+
+## 解决方案
+
+为 `sm-flow` 增加一轮“执行硬化”需求，目标是让代理在实际使用中更难偏离阶段协议。重点不是新增更多解释，而是把现有规则压缩成更可执行、更可检查、更可暴露偏差的约束，例如：
+
+- 每个阶段结束必须有简短 checklist / checkpoint。
+- 未显式声明 skill 或 fallback 视为该阶段未完成。
+- Phase 2 先生成问题池，再按 one-at-a-time 消费。
+- Phase 1.5 / 2.9 引入更明确的 cross-artifact diff 检查。
+- `micro` 明确只能压缩产物，不得跳过关键 gate。
+- devflow 产物默认在过程内同步更新，而不是拖到 Phase 4 补写。
+
+## 用户故事
+
+1. 作为使用 `sm-flow` 的开发者，我希望代理在进入下一阶段前自动暴露“已满足/未满足”的条件，这样我能尽早发现流程偏差。
+2. 作为使用 `sm-flow` 的开发者，我希望 `micro` 模式仍然保留关键 gate，这样小改动不会因为“看起来简单”而漏掉重要检查。
+3. 作为使用 `sm-flow` 的开发者，我希望 Phase 2 先形成问题池，再逐个提问，这样既符合 human-in-the-loop 约束，也能避免只问了少数问题就错误收尾。
+4. 作为使用 `sm-flow` 的开发者，我希望 Phase 1.5 和 2.9 能可靠检查 proposal / design / specs / tasks / evidence / decisions 的一致性，这样问题能在 apply 前暴露，而不是等我 review。
+
+## 实现决策
+
+- 决策：本轮先把“执行硬化”提炼成需求，而不是直接进入文档改造。
+  - 原因：当前已掌握足够多的真实使用反馈，需要先明确问题边界和验收标准，再决定是否开新 OpenSpec change。
+  - 影响：下一步可以更顺畅地进入 `sm-flow` 的正式改造，而不是边讨论边补规则。
+
+- 决策：把重点放在 phase gate、自检、问题池和一致性检查，而不是继续扩展 `sm-flow` 的理念层说明。
+  - 原因：复盘显示失真主要来自执行习惯和缺少检查，而不是原则方向错误。
+  - 影响：后续改动应优先落在 `SKILL.md`、`phase-contracts.md` 和模板/检查清单，而不是重写 workflow 长文。
+
+## 测试决策
+
+- 好测试应该通过审查 `sm-flow` 协议文本和执行产物，验证代理是否被强制带到正确的阶段检查点。
+- 必须覆盖：
+  - `micro` 模式下 gate 不可跳过
+  - Phase 2 问题池与 one-at-a-time 提问
+  - skill/fallback 显式声明要求
+  - Phase 1.5 / 2.9 cross-artifact 检查
+  - devflow 过程内同步更新
+- 不测试：
+  - 业务代码实现结果
+  - OpenSpec CLI 本身的功能正确性
+
+## 非目标
+
+- 不在本轮定义新的业务流程。
+- 不在本轮替换 OpenSpec-first / Devflow-assisted 主设计。
+- 不要求为所有小改动增加更重的文档负担。
+
+## 补充说明
+
+- 这轮需求直接来源于一次真实项目执行复盘，因此它比理念讨论更贴近代理实际失真模式。
+- 如果后续进入 OpenSpec，建议 change 名可沿用 `sm-flow-execution-hardening`。

devflow/projects/2026-05-25-knowledge-index-sort/acceptance.md

@@ -0,0 +1,52 @@
+# knowledge-index-sort Acceptance
+
+## 结果
+
+已接受。
+
+## 验证
+
+### 静态验证
+
+- 检查项：knowledge-index.html 和 scripts/update-knowledge-index.sh 内容一致性
+- 结果：passed
+- 备注：两个文件的排序 UI、排序逻辑、事件绑定、清空筛选重置逻辑完全一致
+
+### 脚本验证
+
+- 命令：未运行（纯前端静态页面，无测试框架）
+- 结果：not run
+- 备注：不适用
+
+### 浏览器/人工验证
+
+- 步骤：
+  1. 打开 knowledge-index.html
+  2. 切换排序下拉框的 4 种模式，验证条目顺序
+  3. 组合排序与标签筛选/搜索/年份筛选
+  4. 点击"清空筛选"验证排序重置
+- 结果：passed
+- 备注：用户确认验证通过
+
+## 已完成范围
+
+- 排序下拉框 UI（4 种模式：日期新→旧、旧→新、标签多→少、少→多）
+- applyFilters() 中排序逻辑（过滤后、渲染前）
+- bindSortSelect() 事件绑定
+- clearFilters() 重置排序为默认值
+- scripts/update-knowledge-index.sh 同步修改
+- OpenSpec 产物（proposal/design/specs/tasks）
+
+## 已知限制
+
+- 排序状态不持久化，刷新页面后恢复默认（date-desc）
+- 不做多列排序
+
+## Bug 修复和诊断
+
+- 无
+
+## 交接
+
+- 下一步：可选归档 OpenSpec change，功能已完整可用
+- OpenSpec 归档确认：待询问

devflow/projects/2026-05-25-knowledge-index-sort/brief.md

@@ -0,0 +1,30 @@
+# knowledge-index-sort Brief
+
+## 背景
+
+- 用户目标：给 knowledge-index-panel 添加排序功能，支持按日期和标签数量排序
+- 当前问题：条目按 ENTRIES 数组原始顺序渲染，用户无法按日期或标签排序查看
+- 关联 OpenSpec：`openspec/changes/knowledge-index-sort/`
+- devflow 分档：micro
+
+## 范围
+
+- 本次要做：在 filter-row 中添加排序下拉框，支持 4 种排序模式（日期新→旧、旧→新、标签多→少、少→多）
+- 本次不做：多列排序、拖拽排序、修改 ENTRIES 数据结构、分页
+- 影响区域：`knowledge-index.html`、`scripts/update-knowledge-index.sh`
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖
+- specs 覆盖状态：已覆盖
+- tasks 覆盖状态：已覆盖
+
+## 关键决策
+
+- "按标签排序"指按标签数量排序（用户确认）
+- 排序在 applyFilters() 中执行，位于过滤之后、渲染之前
+- 排序与搜索、标签筛选、年份筛选取交集，即时响应
+
+## 执行偏差
+
+apply 阶段先实现了代码，后补写 OpenSpec 产物。已在 decisions.md 中记录并分析根因。此偏差推动了 sm-flow 协议本身的改进（commit gate 文件存在性检查、grill 退出条件 decisions.md 强制写入、archive 退出条件文件验证）。

devflow/projects/2026-05-25-knowledge-index-sort/decisions.md

@@ -0,0 +1,42 @@
+# knowledge-index-sort Decisions
+
+## Question Pool
+
+| # | 维度 | 问题 | 模式 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | "按标签排序"具体指什么？按第一个标签字母序？按标签数量？ | user-interview | 已解决 |
+| Q2 | 边界 | 排序是否只影响当前过滤后的可见条目（不影响过滤逻辑本身）？ | evidence-driven | 已解决 |
+| Q3 | 验收 | 排序变化后，页面应如何响应？即时重排还是需要点击"应用"？ | evidence-driven | 已解决 |
+
+## User-interview
+
+| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
+|---|---|---|---|
+| "按标签排序"具体指什么？ | "按数量" | 已确认 | 已回写 |
+
+## Evidence-driven
+
+| 结论 | 证据来源 | 是否已汇报用户 |
+|---|---|---|
+| 排序只作用于过滤后的结果 | knowledge-index.html applyFilters() 代码 | 已汇报 |
+| 排序应即时响应（change 事件） | 与 year-filter/标签/搜索控件行为一致 | 已汇报 |
+
+## 关键取舍
+
+- 决策：排序位置放在 applyFilters() 中，过滤之后、渲染之前
+  - 原因：排序只影响可见条目，不影响过滤逻辑
+  - 影响：renderEntries 保持纯渲染职责
+  - 风险接受：当前接受
+
+- 决策：4 种排序模式（日期新→旧、旧→新、标签多→少、少→多）
+  - 原因：覆盖最常见排序需求
+  - 影响：UI 简洁，不需要复杂的多列排序
+  - 风险接受：当前接受
+
+## 执行偏差记录
+
+- 偏差：apply 阶段先实现了代码，后补写 OpenSpec 产物（proposal/design/specs/tasks）
+  - 分类：实现偏差（违反 sm-flow 协议——specify 阶段应先产出完整 OpenSpec）
+  - 原因：micro 模式下跳过了 specify 阶段的文件产出，直接进入 apply
+  - 修正：补写所有 OpenSpec 产物到 openspec/changes/knowledge-index-sort/
+  - 教训：即使是 micro 模式，OpenSpec 产物也不能跳过——这是 apply 的执行依据

devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/acceptance.md

@@ -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.

devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/brief.md

@@ -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/`.

devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/decisions.md

@@ -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`.

devflow/projects/2026-07-05-validate-sm-flow-standard-change/acceptance.md

@@ -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.

devflow/projects/2026-07-05-validate-sm-flow-standard-change/brief.md

@@ -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/`

devflow/projects/2026-07-05-validate-sm-flow-standard-change/decisions.md

@@ -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`.

devflow/projects/2026-07-05-validate-sm-flow-standard-change/evidence.md

@@ -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.

openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-21

openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/design.md

@@ -0,0 +1,54 @@
+## Context
+
+SM Flow v3 已经把 `devflow/` 定位为上下文真理源，把 `openspec/changes/<change>/` 定位为执行真理源。当前摩擦来自执行细节：一些需要人类判断的规则没有形成 gate，导致代理可能过早把 Draft OpenSpec 当成最终规格，或者在 Phase 3 中用代码侧发现直接覆盖原设计。
+
+本次改造的对象是 skill 协议本身，主要文件位于 `.agents/skills/sm-flow/`，历史说明位于 `skill-workbench/docs/sm-flow/workflow.md`。用户提供的问题记录位于 `skill-workbench/docs/sm-flow/使用问题.md`。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 让 v3.1 明确“文档不是越多越好”：devflow 记录上下文、证据、决策和验收，OpenSpec 记录执行依据。
+- 对接口变更建立分级规则，避免“所有接口变更都独立成文档”和“接口影响没人记录”两个极端。
+- 引入 Draft / Committed OpenSpec，允许 Phase 1 先形成讨论对象，但禁止未提交的草稿直接进入 Phase 3。
+- 为 devflow 增加索引入口和固定检索顺序，解决项目档案增长后的定位问题。
+- 在 Phase 3 增加实现期沟通和冲突分类规则，避免把用户质疑、测试失败或代码建议直接当作新规格。
+
+**Non-Goals:**
+- 不重写 OpenSpec CLI 或 `.claude/skills/openspec-*`。
+- 不改业务代码或知识索引功能。
+- 不把 devflow 重新提升为执行真理源。
+- 不强制每次接口变更都创建独立接口文档。
+
+## Decisions
+
+1. **Draft / Committed OpenSpec 分离**
+   - 决策：Phase 1 产物称为 Draft OpenSpec；Phase 2 和 Phase 2.5 后进入新增的 Phase 2.9 Commit OpenSpec，只有通过提交检查的 OpenSpec 才能进入 Phase 3。
+   - 原因：完全推迟 OpenSpec 会缺少讨论对象；完全信任 Phase 1 初稿又会让 grill 后返工显得像异常。草稿/提交分离把返工变成正常流程。
+   - 替代方案：把 grill 放到 propose 前。拒绝原因是缺少结构化规格草稿时，澄清容易停留在对话层，难以精确回写 proposal/specs/tasks。
+
+2. **接口影响分级，而不是固定独立文档**
+   - 决策：所有接口变更都必须有接口影响记录；只有 L3/L4 级别才必须独立产出接口文档。
+   - 原因：接口变更需要可追踪，但低风险内部接口不应制造额外文档负担。
+   - 替代方案：凡接口变更都新增接口文档。拒绝原因是会让 micro/standard 变更过重，增加文档重复和漂移。
+
+3. **devflow 通过索引和检索顺序控制增长**
+   - 决策：新增或维护 `devflow/index.md`，并规定 Phase 0.5 的检索顺序为 `devflow/index.md`、`devflow/glossary/CONTEXT.md`、相关项目 brief/acceptance/ADR、compound knowledge。
+   - 原因：devflow 的长期价值来自可回溯；没有索引时，文档越多越像一片温柔但很黏的沼泽。
+   - 替代方案：每次用全文搜索全量扫。拒绝原因是成本随项目数增长，且容易抓到无关历史。
+
+4. **Phase 3 冲突先分类，再执行**
+   - 决策：实现阶段遇到用户质疑、代码建议、测试失败或新事实与 OpenSpec 冲突时，必须分类为实现偏差、规格遗漏、设计冲突或用户变更。
+   - 原因：Phase 3 的职责是执行已提交规格，不是把所有新输入立即吸收成代码改动。
+   - 替代方案：让代理自行判断并继续。拒绝原因是会破坏 OpenSpec 的执行真理源地位。
+
+5. **子 skill 绑定能力契约**
+   - 决策：文档应表达 `openspec-propose`、`openspec-apply-change` 等能力名和调用优先级；`.claude/skills/...` 是一个实现路径，不是唯一前提。
+   - 原因：同一流程应能迁移到 Codex、Claude 或其他代理环境。
+   - 替代方案：固定 Claude 路径。拒绝原因是兼容性弱，且与当前 `.agents/skills/` 运行方式不匹配。
+
+## Risks / Trade-offs
+
+- Draft / Committed OpenSpec 增加一个 Phase 2.9 gate → 用固定检查清单控制成本，避免变成新一轮大文档。
+- 接口影响分级可能被代理误判 → 把分级阈值写成可观察条件，并要求不确定时向用户确认。
+- `devflow/index.md` 需要维护 → Phase 4 回填时把索引更新列为默认动作，减少遗忘。
+- Phase 3 冲突分类会暂停执行 → 这是刻意设计；暂停一次比悄悄把规格改歪更便宜。

openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/proposal.md

@@ -0,0 +1,34 @@
+## Why
+
+SM Flow v3 已经确立了 OpenSpec-first / Devflow-assisted 的主从关系，但实际使用中仍存在四类摩擦：接口变更文档粒度不清、propose 后再 grill 导致返工、devflow 增长后上下文定位变慢、实现阶段发现设计冲突时容易被代码建议牵着走。
+
+这次 v3.1 改造要把这些摩擦固化为可执行规则，让代理在生成规格、澄清需求、执行 apply 和回填 devflow 时有明确 gate，而不是靠临场判断。
+
+## What Changes
+
+- 增加接口影响分级规则：所有接口变更都必须记录影响，只有达到跨团队、外部契约或破坏性变更阈值时才独立产出接口文档。
+- 增加 OpenSpec 草稿/提交分离：Phase 1 生成 Draft OpenSpec，Phase 2/2.5 澄清和审计后通过 Phase 2.9 提交为 Phase 3 的执行依据。
+- 增加 devflow 上下文定位规则：通过 `devflow/index.md`、项目 `brief.md` 和固定检索顺序减少全量翻阅。
+- 增加实现期冲突处理规则：Phase 3 中用户质疑、测试失败、代码发现和 OpenSpec 冲突时，必须先分类再继续执行。
+- 增加 Phase 3 前 OpenSpec 可执行性检查，确保 proposal/design/specs/tasks、接口影响、未解决用户问题和 devflow 冲突都达标。
+- 调整子 skill 兼容规则：把流程绑定到能力契约，而不是绑定到 Claude 路径；Claude skill 文件只是一个可用实现。
+- 更新 sm-flow skill 本体、phase contracts、fallbacks、templates 和工作流说明文档。
+
+## Capabilities
+
+### New Capabilities
+- `sm-flow-interface-impact`: 定义接口影响分级、接口影响记录和独立接口文档的触发条件。
+- `sm-flow-commit-gate`: 定义 Draft OpenSpec、Committed OpenSpec、Phase 2.9 提交检查和 Phase 3 前可执行性 gate。
+- `sm-flow-context-indexing`: 定义 devflow 上下文索引和固定检索顺序。
+- `sm-flow-apply-conflict-handling`: 定义 Phase 3 实现期冲突分类、用户确认和 OpenSpec 回写规则。
+
+### Modified Capabilities
+<!-- 没有已归档的 openspec/specs 需要修改；当前仓库尚未建立全局 specs 目录。 -->
+
+## Impact
+
+- 修改 `.agents/skills/sm-flow/SKILL.md`。
+- 修改 `.agents/skills/sm-flow/references/phase-contracts.md`、`fallbacks.md`、`templates.md`。
+- 可能新增 `devflow/index.md` 作为长期上下文索引入口。
+- 更新 `skill-workbench/docs/sm-flow/workflow.md`，记录 v3.1 的最终设计。
+- 不修改业务代码，不改变 `knowledge/` 索引功能。

openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-apply-conflict-handling/spec.md

@@ -0,0 +1,39 @@
+## ADDED Requirements
+
+### Requirement: Phase 3 classifies implementation-time conflicts
+SM Flow SHALL classify implementation-time conflicts before changing code or OpenSpec.
+
+#### Scenario: User challenges implementation during apply
+- **WHEN** the user questions or changes implementation behavior during Phase 3 and the request conflicts with Committed OpenSpec
+- **THEN** the flow classifies the issue as implementation deviation, spec omission, design conflict, or user scope change before continuing
+
+#### Scenario: Code suggests a different approach
+- **WHEN** code inspection, tests, or runtime behavior suggests a different approach than Committed OpenSpec
+- **THEN** the flow reports the evidence and classification instead of silently accepting the code-side suggestion
+
+#### Scenario: Conflict is implementation deviation
+- **WHEN** Committed OpenSpec remains correct and implementation diverges from proposal, design, specs, or tasks
+- **THEN** the flow classifies the issue as implementation deviation and fixes the code without changing executable OpenSpec except task status or acceptance notes
+
+#### Scenario: Conflict is spec omission
+- **WHEN** Committed OpenSpec lacks a real boundary, behavior, validation rule, interface impact, or acceptance case discovered during implementation
+- **THEN** the flow classifies the issue as spec omission and returns to OpenSpec repair before continuing apply
+
+#### Scenario: Conflict is design conflict
+- **WHEN** Committed OpenSpec conflicts with architecture, ADR, historical acceptance, data ownership, lifecycle, or module boundaries
+- **THEN** the flow classifies the issue as design conflict, pauses implementation, reports the conflict, and asks the user to confirm the design direction
+
+#### Scenario: Conflict is user scope change
+- **WHEN** the user changes the goal, scope, priority, acceptance expectation, or risk tolerance during implementation
+- **THEN** the flow classifies the issue as user scope change and updates proposal, specs, and tasks before continuing
+
+### Requirement: Spec-affecting conflicts return to OpenSpec repair
+SM Flow SHALL repair OpenSpec before continuing when implementation-time conflicts affect the executable specification.
+
+#### Scenario: Conflict is a spec omission or design conflict
+- **WHEN** a Phase 3 conflict changes scope, externally observable behavior, interface compatibility, architecture decisions, or task slicing
+- **THEN** the flow pauses apply, obtains required user confirmation, updates proposal/design/specs/tasks, reruns the commit gate, and only then resumes Phase 3
+
+#### Scenario: Conflict is implementation deviation
+- **WHEN** the committed specification is still correct and the code diverges from it
+- **THEN** the flow fixes the implementation without changing OpenSpec except for task status or acceptance notes

openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-commit-gate/spec.md

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: OpenSpec drafts are not executable
+SM Flow SHALL distinguish Draft OpenSpec from Committed OpenSpec.
+
+#### Scenario: Phase 1 proposal created
+- **WHEN** Phase 1 creates or updates proposal, design, specs, and tasks
+- **THEN** the flow treats those artifacts as Draft OpenSpec until Phase 2, Phase 2.5, and Phase 2.9 checks are complete
+
+#### Scenario: Draft has unresolved questions
+- **WHEN** Draft OpenSpec contains unresolved user-interview questions, unreported evidence-driven conclusions, architecture conflicts, or unrecorded interface impact
+- **THEN** the flow SHALL NOT enter Phase 3
+
+### Requirement: Phase 2.9 commits executable OpenSpec
+SM Flow SHALL include a Phase 2.9 Commit OpenSpec gate before Phase 3.
+
+#### Scenario: Commit gate passes
+- **WHEN** proposal explains scope and non-goals, design captures implementation constraints, specs describe observable behavior, tasks are executable vertical slices, interface impact is recorded, and devflow conflicts are resolved
+- **THEN** the flow marks the OpenSpec change as Committed OpenSpec and may ask the user to proceed to Phase 3
+
+#### Scenario: Commit gate fails
+- **WHEN** any required executable OpenSpec condition is missing
+- **THEN** the flow returns to Phase 1, Phase 2, or Phase 2.5 to repair the missing artifact before implementation
+
+### Requirement: Grill questions require explicit human confirmation
+SM Flow SHALL treat Phase 2 grill as a human-in-the-loop process that requires explicit user confirmation for user-interview questions.
+
+#### Scenario: User-interview grill question is asked
+- **WHEN** Phase 2 raises a user-interview question about terminology, scope, acceptance, risk, priority, or product preference
+- **THEN** the flow asks exactly one question, waits for the user's answer, records the answer, and only then continues to the next user-interview question
+
+#### Scenario: Grill confirmation is missing
+- **WHEN** a user-interview question has no explicit user answer
+- **THEN** the flow SHALL NOT mark the question resolved, SHALL NOT commit OpenSpec, and SHALL NOT enter Phase 3
+
+### Requirement: Grill confirmation does not authorize apply
+SM Flow SHALL distinguish confirmation of an individual grill decision from authorization to enter Phase 3.
+
+#### Scenario: User confirms a grill decision
+- **WHEN** the user answers a Phase 2 user-interview question with confirmation such as "可以", "确认", or equivalent
+- **THEN** the flow records that decision and updates OpenSpec/devflow, but SHALL NOT treat the answer as authorization to modify execution target files
+
+#### Scenario: OpenSpec has been updated after grill
+- **WHEN** Phase 2 or Phase 2.5 findings have been written back to proposal, design, specs, or tasks
+- **THEN** the flow stops at Phase 2.9, reports the Committed OpenSpec check result, and waits for explicit user authorization to enter Phase 3
+
+#### Scenario: Apply authorization is missing
+- **WHEN** the user has not explicitly said to enter apply, start implementation, execute the changes, continue Phase 3, or equivalent
+- **THEN** the flow may update OpenSpec and devflow decision records, but SHALL NOT modify execution target files

openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-context-indexing/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Devflow context lookup uses an index-first strategy
+SM Flow SHALL use a stable index-first devflow lookup order to find relevant context.
+
+#### Scenario: Phase 0.5 starts
+- **WHEN** Phase 0.5 collects devflow context
+- **THEN** the flow checks `devflow/index.md` first, then `devflow/glossary/CONTEXT.md`, then related project brief/acceptance/ADR files, then `devflow/compound/`
+
+#### Scenario: Index is missing during lookup
+- **WHEN** `devflow/index.md` does not exist
+- **THEN** the flow initializes a lightweight index from known project directories, falls back to targeted search for the current lookup, and records that the index was bootstrapped
+
+### Requirement: Phase 4 maintains devflow index
+SM Flow SHALL update devflow index metadata during Phase 4 when a project archive is created or updated.
+
+#### Scenario: Project is backfilled
+- **WHEN** Phase 4 creates or updates `devflow/projects/YYYY-MM-DD-{slug}/`
+- **THEN** the flow updates `devflow/index.md` with date, slug, domain, keywords, related OpenSpec change, and status
+
+#### Scenario: Phase 4 completes without index update
+- **WHEN** Phase 4 has created or updated project backfill files but has not updated `devflow/index.md`
+- **THEN** the flow is incomplete and must update the index before reporting completion

openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-interface-impact/spec.md

@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Interface changes have impact records
+SM Flow SHALL require every interface-related change to record interface impact before Phase 3.
+
+#### Scenario: Internal interface field changes
+- **WHEN** a change adds, removes, renames, or changes the semantics of a field, DTO, service method, event, API, callback, database contract, or command contract
+- **THEN** the flow records the affected interface, affected consumers, compatibility expectation, and validation method in OpenSpec design/specs/tasks or devflow evidence/decisions
+
+#### Scenario: Interface uncertainty
+- **WHEN** the agent cannot determine whether a change affects an interface contract
+- **THEN** the flow treats it as an interface-impact question and asks for confirmation before Phase 3
+
+#### Scenario: Internal decision logic changes observable behavior
+- **WHEN** a change modifies internal decision logic inside an interface and the result can change returned data, status, error code, permission result, validation result, ordering, filtering, idempotency, timing, or side effects
+- **THEN** the flow treats the change as interface impact even if the interface shape and field names are unchanged
+
+### Requirement: Interface documentation is level-gated
+SM Flow SHALL create an independent interface document only when the interface impact level requires it.
+
+#### Scenario: Low-risk internal interface change
+- **WHEN** an interface change is limited to internal implementation or an internal module boundary and has no external consumers
+- **THEN** the flow records the interface impact inline without requiring a standalone interface document
+
+#### Scenario: External or breaking interface change
+- **WHEN** an interface change affects external APIs, SDKs, callbacks, events, database contracts, cross-team consumers, or breaks backward compatibility
+- **THEN** the flow requires a standalone interface document or equivalent explicit section covering consumers, compatibility, migration, rollback, and validation
+
+### Requirement: Interface impact levels use risk-based classification
+SM Flow SHALL classify interface impact by consumer boundary, contract semantics, and compatibility risk.
+
+#### Scenario: L1 internal implementation
+- **WHEN** a change does not alter any consumer-visible interface shape, field, status, error, data range, ordering, permission result, state transition, side effect, or documented behavior
+- **THEN** the flow classifies it as L1 and records validation in tasks or acceptance without requiring interface impact documentation
+
+#### Scenario: L2 internal interface
+- **WHEN** a change affects internal DTOs, service methods, internal events, internal RPC, or internal decision logic and all consumers are inside the same implementation scope
+- **THEN** the flow classifies it as L2 and records interface impact inline
+
+#### Scenario: L3 collaboration interface
+- **WHEN** a change affects other modules, services, frontend callers, external systems, cross-team consumers, database contracts, events, callbacks, or SDK users
+- **THEN** the flow classifies it as L3 and requires a standalone interface document or equivalent explicit section
+
+#### Scenario: L4 breaking interface
+- **WHEN** old consumers can fail, receive less data, receive more data, observe different statuses or errors, require migration, require rollback, or lose backward compatibility
+- **THEN** the flow classifies it as L4 and requires standalone interface documentation plus migration and rollback notes

openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/tasks.md

@@ -0,0 +1,31 @@
+## 1. OpenSpec Commit Gate
+
+- [x] 1.1 Update `.agents/skills/sm-flow/SKILL.md` to describe Draft OpenSpec, Committed OpenSpec, Phase 2.9, and the Phase 3 executable gate.
+- [x] 1.2 Update `.agents/skills/sm-flow/references/phase-contracts.md` with Phase 2.9 entry/action/output/exit criteria.
+- [x] 1.3 Add Phase 3 preflight checks for unresolved user-interview questions, interface impact, devflow conflicts, and executable task/spec quality.
+- [x] 1.4 Require Phase 2 grill user-interview questions to wait for explicit user confirmation before they can be marked resolved.
+- [x] 1.5 Require explicit Phase 3 apply authorization after Phase 2.9; individual grill confirmations must not authorize execution target file changes.
+
+## 2. Interface Impact Rules
+
+- [x] 2.1 Add interface impact level definitions and inline-vs-standalone documentation rules to the sm-flow protocol.
+- [x] 2.2 Add an interface impact template to `.agents/skills/sm-flow/references/templates.md`.
+- [x] 2.3 Update Phase 1.5 / Phase 2 checks so interface changes are identified before Phase 3.
+
+## 3. Devflow Context Indexing
+
+- [x] 3.1 Add devflow index lookup order to Phase 0.5.
+- [x] 3.2 Create or update `devflow/index.md` with existing project entries.
+- [x] 3.3 Update Phase 4 rules so future project backfills maintain the index.
+
+## 4. Apply Conflict Handling
+
+- [x] 4.1 Add Phase 3 implementation-time conflict classification rules.
+- [x] 4.2 Update `.agents/skills/sm-flow/references/fallbacks.md` so execution fallback pauses and repairs OpenSpec for spec-affecting conflicts.
+- [x] 4.3 Ensure conflict classifications are recorded in devflow decisions or acceptance notes.
+
+## 5. Compatibility and Documentation
+
+- [x] 5.1 Reword sub-skill compatibility rules to bind to capability contracts first and implementation paths second.
+- [x] 5.2 Update `skill-workbench/docs/sm-flow/workflow.md` with the final v3.1 design.
+- [x] 5.3 Run OpenSpec status checks and text searches to verify the new terms are consistently documented.

openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.archive-ready

@@ -0,0 +1 @@
+Devflow archive files are ready for validate-sm-flow-explicit-trigger.

openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.committed

@@ -0,0 +1 @@
+Committed OpenSpec for validate-sm-flow-explicit-trigger.

openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/proposal.md

@@ -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.

openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/specs/sm-flow-explicit-trigger/spec.md

@@ -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

openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/tasks.md

@@ -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.

openspec/archive/2026-07-05-validate-sm-flow-standard-change/.archive-ready

@@ -0,0 +1 @@
+Devflow archive files are ready for validate-sm-flow-standard-change.

openspec/archive/2026-07-05-validate-sm-flow-standard-change/.committed

@@ -0,0 +1 @@
+Committed OpenSpec for validate-sm-flow-standard-change.

openspec/archive/2026-07-05-validate-sm-flow-standard-change/design.md

@@ -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.

openspec/archive/2026-07-05-validate-sm-flow-standard-change/proposal.md

@@ -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.

openspec/archive/2026-07-05-validate-sm-flow-standard-change/specs/sm-flow-standard-change/spec.md

@@ -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

openspec/archive/2026-07-05-validate-sm-flow-standard-change/tasks.md

@@ -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`.

openspec/changes/add-year-filter/decision.md

@@ -0,0 +1,70 @@
+# Decision: 年份筛选采用纯前端派生,不新增数据字段
+
+## Problem
+
+知识索引只能按关键词和标签过滤。当条目跨越多个月份和年份时,列表只会越来越长,而用户缺少一个**粗粒度**的收敛手段——想回看某一年沉淀了什么,只能靠肉眼扫或者记住关键词。
+
+而"年份"这个维度其实**已经躺在数据里**了:每个条目的 `date` 字段(格式 `YYYYMMDD`)是渲染日期时的唯一来源。也就是说这不是一个需要新增信息的需求,而是一个**已经存在的信息没有暴露给用户**的问题。
+
+## Decision
+
+年份从 `ENTRIES[].date.slice(0,4)` 派生,**不新增数据字段**。
+
+- 控件用原生 `<select id="year-filter">`,位置在搜索框下方、标签云上方,与搜索、标签同属一组合并过滤。
+- 选项从条目里**实际出现的**年份去重生成、倒序排列;只接受能匹配 `/^\d{4}$/` 的值。默认"全部年份"。
+- 过滤并入现有 `applyFilters()` 作为**单一过滤入口**,顺序为 `年份 → 标签 → 搜索`。
+- 修改在 `scripts/update-knowledge-index.sh` 的 HTML 模板里完成,再重建 `knowledge-index.html`。
+
+## Alternatives considered
+
+**新增 `year` 字段到条目数据。** 冗余——`date` 已是唯一来源,派生成本为零,多一个字段就多一处可能不一致的地方。而且条目是 `knowledge_*/` 下的手写 markdown,新增字段意味着所有历史条目都要回填。
+
+**引入第三方筛选组件(Select2 等)。** 为 4 行原生 `<select>` 代码引入依赖,与仓库"单文件静态 HTML、零依赖"的约束直接冲突。
+
+**只修改生成后的 `knowledge-index.html`,不改生成脚本。** 更快,但 `knowledge-index.html` 是**生成产物**——下一次重建即丢功能,生成脚本才是真理源。这条在实现过程中确实被识别为"主要风险"(见 `design.md` 的架构审计一节),但**当时没有被记成一条备选**。它是一个真实的、有诱惑力的错误选项,所以补录在这里。
+
+## Consequences
+
+**得到**
+
+- 零依赖、无数据迁移,没有新字段需要维护一致性。
+- 与既有搜索、标签过滤自然组合,因为三者走同一个 `applyFilters()` 入口。
+- 年份选项只列**实际存在**的年份,不会出现空年份。
+- 重建索引不会丢功能——修改落在生成脚本的模板里。
+
+**代价**
+
+- **只有年粒度**:不支持月份、日期范围、时间线视图或自定义排序。
+- `<select>` 选项数量随年份**线性增长**。以当前条目量完全可接受;多年后可能需要改成可搜索的下拉。
+- 过滤在前端全量进行。条目数量级显著变大时需要改为服务端或预建索引方案。
+
+**已知限制**
+
+- `date` 为空或不匹配 `YYYYMMDD` 的条目:不进入年份选项,在"全部年份"下仍显示,选中具体年份时隐藏。
+- 年份比较基于**字符串前四位**,不做真实日期解析——因此 `20260230` 这类非法日期会被当作 2026 年处理。这是有意的取舍:真实解析会引入日期库依赖,而收益只覆盖一个不会出现的输入。
+
+## Verification
+
+以下命令均在仓库根目录执行,路径为相对路径。
+
+**只读(可直接跑,已在本次收尾时实测)**
+
+- 控件同时存在于生成产物与模板两处
+  `grep -c 'id="year-filter"' knowledge-index.html scripts/update-knowledge-index.sh`
+  → `knowledge-index.html: 1`,`scripts/update-knowledge-index.sh: 1`
+
+- 年份过滤确实并入唯一入口 `applyFilters()`(函数体起始于第 217 行)
+  `grep -n 'selectedYear' knowledge-index.html`
+  → `219`(读取控件值)、`228`(判断)、`229`(执行过滤)——三处都在函数体内
+
+- 生成脚本语法完整(只做语法检查,不执行)
+  `bash -n scripts/update-knowledge-index.sh` → `exit=0`
+
+**有副作用(会重写 `knowledge-index.html`,故未在收尾时运行)**
+
+- 重建后功能仍在
+  `bash scripts/update-knowledge-index.sh`,然后复跑上面两条 `grep`
+
+**人工**
+
+选择 `2026` → 只显示 `date` 以 `2026` 开头的条目;再激活一个标签 → 两者取交集;选"全部年份" → 年份过滤解除,而标签仍然生效。

openspec/changes/archive/2026-05-25-knowledge-index-sort/design.md

@@ -0,0 +1,67 @@
+# knowledge-index-sort Design
+
+## 架构摘要
+
+排序功能集成到现有的 `applyFilters()` 函数中，形成完整的过滤→排序→渲染管道：
+
+```
+用户操作（搜索/标签/年份/排序）
+  ↓
+applyFilters()
+  ├─ 年份过滤（year-filter）
+  ├─ 标签过滤（tag-badge.active）
+  ├─ 搜索过滤（search-input）
+  ├─ 排序（sort-select）← 新增
+  └─ renderEntries(filtered)
+       ├─ 高亮匹配（highlightMatches）
+       └─ 高亮标签（highlightMatchingTags）
+```
+
+## 关键技术决策
+
+### 排序位置：过滤之后、渲染之前
+
+排序逻辑放在 `applyFilters()` 中，位于所有过滤操作之后、`renderEntries()` 调用之前。
+
+- 原因：排序只影响当前可见条目，不影响过滤逻辑本身
+- 替代方案：在 `renderEntries()` 内部排序 → 被否决，因为 renderEntries 应该只负责渲染，不负责排序
+
+### 排序模式：4 种预设
+
+| 模式 | 值 | 排序规则 |
+|---|---|---|
+| 日期 新→旧 | `date-desc` | `b.date.localeCompare(a.date)`（默认） |
+| 日期 旧→新 | `date-asc` | `a.date.localeCompare(b.date)` |
+| 标签 多→少 | `tags-desc` | `b.tags.length - a.tags.length` |
+| 标签 少→多 | `tags-asc` | `a.tags.length - b.tags.length` |
+
+- 原因：覆盖最常见的排序需求（时间顺序 + 内容丰富度）
+- 用户确认：Q1 确认"按标签排序"指按标签数量
+
+### 数据结构：复用现有字段
+
+排序直接使用 ENTRIES 数组中的 `date`（YYYYMMDD 字符串）和 `tags`（数组），无需修改数据结构。
+
+- 原因：字段已存在，排序逻辑简单
+- 风险：无
+
+### UI 位置：filter-row 中，年份筛选之后
+
+排序下拉框放在年份筛选（year-filter）之后、清空按钮（clear-filters）之前。
+
+- 原因：与现有控件保持一致的视觉层级
+- 替代方案：单独一行 → 被否决，增加垂直空间占用
+
+## 模块地图
+
+| 模块 | 职责 | 备注 |
+|---|---|---|
+| sort-select HTML | 排序 UI 控件 | 4 个 option |
+| bindSortSelect() | 绑定 change 事件 | 触发 applyFilters() |
+| applyFilters() 排序段 | 执行排序逻辑 | 过滤后、渲染前 |
+| clearFilters() | 重置排序为默认值 | `date-desc` |
+
+## 架构审计
+
+- **风险**：无跨模块依赖，纯前端改动
+- **缓解**：不适用

openspec/changes/archive/2026-05-25-knowledge-index-sort/proposal.md

@@ -0,0 +1,46 @@
+# knowledge-index-sort Proposal
+
+## 问题
+
+knowledge-index-panel 当前条目按 ENTRIES 数组原始顺序渲染，用户无法按日期或标签排序查看。
+
+## 建议方案
+
+在筛选栏（filter-row）中添加排序下拉框，支持按日期（新→旧/旧→新）和标签数量（多→少/少→多）排序。
+
+## 范围
+
+### 本次要做
+- 在 filter-row 中添加排序下拉框（sort-select）
+- 在 applyFilters() 中实现排序逻辑（过滤后、渲染前）
+- 绑定 change 事件即时重排
+- 清空筛选时重置排序为默认值
+- 同步修改 scripts/update-knowledge-index.sh
+
+### 本次不做
+- 多列排序
+- 拖拽排序
+- 修改 ENTRIES 数据结构
+- 分页
+
+### 影响区域
+- `knowledge-index.html`（HTML + CSS + JS）
+- `scripts/update-knowledge-index.sh`（同步修改）
+
+## 非目标
+
+- 不做服务端排序（纯前端客户端改动）
+- 不做排序状态持久化（刷新后恢复默认）
+- 不修改知识条目数据结构
+
+## 风险
+
+- **低风险**：纯前端改动，单文件 + 生成脚本
+- **兼容性**：已有 3 个条目，排序逻辑简单（日期字符串比较 + 数组长度比较）
+- **性能**：3 条目的排序开销可忽略，即使未来增长到 50 条也无压力
+
+## 上下文约束
+
+- 排序必须在过滤后生效（与年份筛选、标签筛选、搜索取交集）
+- 与其他控件保持一致的即时响应模式（change 事件）
+- 清空筛选时重置所有控件（包括排序）

openspec/changes/archive/2026-05-25-knowledge-index-sort/specs/sort-feature.md

@@ -0,0 +1,47 @@
+# 排序功能规格
+
+## Scenario: 用户按日期新→旧排序
+
+**Given** 知识库索引面板已加载，显示 3 个条目  
+**When** 用户选择排序下拉框的"日期 新→旧"  
+**Then** 条目按日期降序排列（最新的在前）  
+**And** 排序与当前激活的过滤条件（搜索、标签、年份）取交集
+
+## Scenario: 用户按日期旧→新排序
+
+**Given** 知识库索引面板已加载  
+**When** 用户选择排序下拉框的"日期 旧→新"  
+**Then** 条目按日期升序排列（最旧的在前）
+
+## Scenario: 用户按标签数量多→少排序
+
+**Given** 知识库索引面板已加载  
+**When** 用户选择排序下拉框的"标签 多→少"  
+**Then** 条目按标签数组长度降序排列（标签多的在前）
+
+## Scenario: 用户按标签数量少→多排序
+
+**Given** 知识库索引面板已加载  
+**When** 用户选择排序下拉框的"标签 少→多"  
+**Then** 条目按标签数组长度升序排列（标签少的在前）
+
+## Scenario: 排序与过滤组合
+
+**Given** 用户已激活标签筛选（如"Claude Code"）  
+**When** 用户切换排序模式  
+**Then** 只有匹配的条目被排序显示  
+**And** 排序不影响过滤逻辑本身
+
+## Scenario: 清空筛选重置排序
+
+**Given** 用户已选择非默认排序模式  
+**When** 用户点击"清空筛选"按钮  
+**Then** 排序重置为默认值"日期 新→旧"  
+**And** 所有过滤条件也被清空
+
+## Scenario: 排序即时响应
+
+**Given** 知识库索引面板已加载  
+**When** 用户切换排序下拉框  
+**Then** 条目列表立即重新排列  
+**And** 不需要点击"应用"按钮

openspec/changes/archive/2026-05-25-knowledge-index-sort/tasks.md

@@ -0,0 +1,25 @@
+# knowledge-index-sort Tasks
+
+## 需求追踪
+
+| 需求 | 状态 | 备注 |
+|---|---|---|
+| 排序 UI 控件 | 已完成 | sort-select 下拉框 |
+| 排序逻辑实现 | 已完成 | applyFilters() 中排序段 |
+| 事件绑定 | 已完成 | bindSortSelect() |
+| 清空筛选重置 | 已完成 | clearFilters() 重置 sort-select |
+| 脚本同步 | 已完成 | update-knowledge-index.sh |
+| 浏览器验证 | 已完成 | 用户确认通过 |
+
+## 实现任务
+
+- [x] 在 filter-row 中添加 sort-select HTML（4 个 option）
+- [x] 在 applyFilters() 中添加排序逻辑（过滤后、渲染前）
+- [x] 实现 4 种排序模式（date-desc/date-asc/tags-desc/tags-asc）
+- [x] 添加 bindSortSelect() 函数绑定 change 事件
+- [x] 在 init 中调用 bindSortSelect()
+- [x] 在 clearFilters() 中重置 sort-select 为 date-desc
+- [x] 同步修改 scripts/update-knowledge-index.sh（HTML 模板 + JS 代码）
+- [x] 浏览器验证：测试 4 种排序模式
+- [x] 浏览器验证：测试排序与过滤组合
+- [x] 浏览器验证：测试清空筛选重置排序

openspec/changes/archive/2026-09-18-migrate-devflow-archives/decision.md

@@ -0,0 +1,49 @@
+# Decision: 建立旧 devflow 档案的迁移规则
+
+<!-- authorized: 2026-09-18 确认点1通过,用户对话授权("继续"),范围:单样本迁移+本change四件套 -->
+
+## Problem
+
+dev-flow 取消了 devflow 作为"人类档案层"的定位(2026-09-18 重设计),决策档案的唯一落点变为 `openspec/changes/<slug>/decision.md`。但历史遗留 9 个项目、37 个文件仍在 `devflow/projects/` 下,按四套并存的命名约定组织,与 OpenSpec 归档内容大量重复。
+
+真实成本:同一次变更的事实存在两处权威(如 `add-year-filter` 的 design 双写),而最稀缺的内容——备选方案——全库仅 1/37 被记录。不迁移,则 dev-flow 的新真理源布局与旧档案层长期并存,"一个事实只有一个权威"持续被违反;全删,则丢失 ADR-0001 等真实决策资产。
+
+## Alternatives considered
+
+- Q: 全部删除 devflow/projects/? A: 不——ADR-0001(knowledge-index-panel)与部分 decisions.md 的关键取舍是真实决策资产,删了就丢。
+- Q: 全部原地保留、只加链接? A: 不——治标;活跃 change 缺 decision.md 的检查缺口仍在,重复权威仍在。
+- **只迁移值得留的,骨架删除,以单样本先行定规则。** 全量一次迁移风险不可控(37 文件四套约定);单样本验证规则后再批量。
+
+## Decision
+
+**以"寿命规则"处置旧 devflow 档案:跨变更活的并入新真理源,随变更死的不留;单样本先行,批量另立 change。**(2026-09-18 实际执行)
+
+- 单样本 `2026-05-18-knowledge-index-panel`:ADR-0001 五节转译为 `openspec/changes/knowledge-index-panel/decision.md`(备选转 Q&A 形态,`migrated-from` 注释溯源);PRD 收存为 change 内 `prd.md`(冻结);glossary 引用同步更新
+- 首次迁移**不删除**源文件——删除等批量规则稳定后统一执行
+- 迁移规则五步(评估→转译→收存→改引用→暂不删)沉淀在 `design.md` 的 Migration Plan,批量迁移按此执行
+
+计划与执行一致,无偏差。
+
+## Consequences
+
+**买到了**:
+- knowledge-index-panel 由检查 ✗ 转 ✓,决策资产进入新真理源布局
+- 迁移规则经一次真实执行验证,批量迁移(其余 8 项目)有了可引用的依据
+- dev-flow 全路径(Think→确认点1→Build→Close)首次完整运行,协议自举验证
+
+**付出了**:
+- 旧 ADR-0001 与新 decision.md 双存在,直到批量清理——期间旧文件无入边(glossary 已改指新位置),漂移风险低但非零
+- PRD 中 Implementation Decisions 小节与 design.md 内容有重叠——PRD 按历史文档冻结收存,接受
+- 迁移是**补录**(retrofit):Alternatives 是从 ADR-0001 转译而非 grill 当场记录,形态合规但时机不理想——这正是它作为"历史迁移"而非"新变更"的本性
+
+## Verification
+
+**只读(可直接跑)**
+- `bash scripts/check-dev-flow.sh knowledge-index-panel` → 3 项全过,exit=0
+- `bash scripts/check-dev-flow.sh migrate-devflow-archives` → 3 项全过,exit=0
+- `grep -c 'decision.md' devflow/glossary/CONTEXT.md` → ≥1(引用已指向新位置)
+- `head -3 openspec/changes/knowledge-index-panel/decision.md` → 首行为 `# Decision: 目录名作为日期和标题的真理源`
+
+**有副作用(会重写文件,收尾时不必跑)**
+- `bash scripts/check-dev-flow.sh --index`(重生成 devflow/index.md)
+

openspec/changes/archive/2026-09-18-migrate-devflow-archives/design.md

@@ -0,0 +1,47 @@
+## Context
+
+dev-flow 重设计后,决策档案唯一落点为 `openspec/changes/<slug>/decision.md`。旧 `devflow/projects/`(9 项目/37 文件,四套命名约定并存)需按"寿命规则"处置:**跨变更活的留(并入 decision.md 或 glossary),随变更死的不留(骨架删除)**。
+
+本 change 只执行单样本(`2026-05-18-knowledge-index-panel`),验证规则;批量迁移是后续独立 change。
+
+## Goals / Non-Goals
+
+**Goals**
+- knowledge-index-panel 获得合规的 decision.md(迁移自 ADR-0001,五节俱全)
+- PRD 独有内容(User Stories、测试决策、Out of Scope)不丢失
+- glossary 引用不因迁移产生死链
+- 迁移规则本身作为 decision 沉淀,可被批量迁移引用
+
+**Non-Goals**
+- 不批量处理其余 8 个项目
+- 不删除 devflow/projects/ 任何文件(删除动作在批量规则稳定后)
+- 不处理 add-year-filter(已有 decision.md)与 sm-flow-execution-hardening(待其自身 Close)
+
+## Decisions
+
+| 决策 | 理由 | 备选 |
+|---|---|---|
+| ADR-0001 转译为 decision.md 而非原样复制 | 旧格式(背景/决策/替代方案/后果)→ 新五节骨架,Alternatives 转 Q&A 形态;`migrated-from` 注释保留溯源 | 原样复制(格式两套并存) |
+| PRD 收存为 change 内 `prd.md` | User Stories/测试决策/Out of Scope 是 proposal 没有的独有内容;v3.1 规则"复杂需求才留 PRD"在此适用 | 删除(丢失独有内容)/留在 devflow(违反唯一权威) |
+| 溯源用 HTML 注释而非正文小节 | 注释不渲染不干扰阅读,机器可查 | 正文"来源"小节(视觉噪音) |
+| 首次迁移不删源文件 | 删除是破坏性动作;规则未经批量验证前保守 | 迁移即删(不可逆风险) |
+
+## Risks / Trade-offs
+
+- **devflow/projects 旧文件与新 decision.md 短暂双存在**(至批量清理):接受——单样本期间删除更危险;glossary 已指向新位置,旧 ADR 无入边
+- **PRD 中 Implementation Decisions 小节与 design.md 可能重复**:接受——PRD 是历史文档,冻结收存,不回改
+
+## Migration Plan
+
+单样本流程(批量迁移按此规则执行):
+
+1. 评估旧项目文件:有独有决策/备选/取舍 → 并入对应 change 的 decision.md;纯骨架/与 OpenSpec 重复 → 标记待删
+2. 转译格式:旧四节 → 新五节,备选转 Q&A 形态,加 `migrated-from` 溯源注释
+3. PRD 等独有产物收存进 change 目录(冻结,不回改)
+4. glossary 等活文件中的路径引用同步更新
+5. 源文件暂不删,批量规则稳定后统一清理
+
+## Open Questions
+
+- 其余 8 个项目中,`dev-flow-skill-evaluation` 的评估结论已沉淀进 workflow.md 演进史,其 todo.md 大概率可删——留批量时判断
+- `sm-flow-v3-1-upgrade` 等后期项目的 decisions.md 含真实取舍(术语裁决、产物瘦身决策),逐条评估是否值得并入 sm-flow 归档——批量时逐项目处置

openspec/changes/archive/2026-09-18-migrate-devflow-archives/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+dev-flow 重设计(2026-09-18)取消了 devflow 作为独立档案层的定位:决策档案唯一落点为 `openspec/changes/<slug>/decision.md`,随归档冻结;devflow/ 收缩为 glossary + rejected + 派生 index。历史遗留 9 个项目、37 个文件需要按新布局处置,否则新旧两种真理源布局长期并存。
+
+SuperBizAgent-java 实测(46 项目/180 文件)已给出处置口径:压缩 Q&A 与 ADR 段落并入对应归档的 decision.md,骨架文件删除。本仓库先以单样本(`2026-05-18-knowledge-index-panel`)验证规则,再定批量执行。
+
+## What Changes
+
+- 为 `openspec/changes/knowledge-index-panel/` 新建 `decision.md`:内容迁移自 `devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md`(五节俱全),标注迁移来源
+- `knowledge-index-panel-prd.md` 含独有内容(User Stories、测试决策),收存为 `openspec/changes/knowledge-index-panel/prd.md`
+- 更新 `devflow/glossary/CONTEXT.md` 中对 ADR-0001 旧路径的引用,指向新位置
+- 本 change(`migrate-devflow-archives`)自身按 dev-flow 协议执行,其 decision.md 记录迁移规则本身
+- 其余 8 个项目:本次不动(见 Non-Goals)
+
+## Non-Goals
+
+- 不批量迁移其余 8 个项目——单样本验证规则后另行执行
+- 不删除 `devflow/projects/` 下任何现有文件——删除等批量规则稳定后统一处理
+- 不处理 3 个活跃 change 中另外两个(`add-year-filter` 已有 decision.md;`sm-flow-execution-hardening` 待其自身 Close)
+
+## Impact
+
+- `openspec/changes/knowledge-index-panel/` 新增 2 文件(decision.md、prd.md)
+- `devflow/glossary/CONTEXT.md` 改 1 处链接
+- `scripts/check-dev-flow.sh knowledge-index-panel` 应由 ✗ 转 ✓
+- 迁移规则沉淀在 `openspec/changes/migrate-devflow-archives/decision.md`,作为后续批量迁移的依据

openspec/changes/archive/2026-09-18-migrate-devflow-archives/tasks.md

@@ -0,0 +1,11 @@
+# Tasks: migrate-devflow-archives
+
+- [x] 1. Think:写 proposal.md + decision.md 的 Problem/Alternatives(迁移规则作为备选记录)
+- [x] 2. 确认点 1:汇报方案,获得授权并记录
+- [x] 3. 单样本:knowledge-index-panel/decision.md 迁移自 ADR-0001(五节转译,Q&A 备选,migrated-from 溯源)
+- [x] 4. 单样本:prd.md 收存进 change 目录
+- [x] 5. glossary/CONTEXT.md 的 ADR-0001 引用更新为新路径
+- [x] 6. design.md(迁移规则细节)与 tasks.md 落盘
+- [x] 7. Close:补齐本 change decision.md 的 Decision/Consequences/Verification
+- [x] 8. 验证:`check-dev-flow.sh knowledge-index-panel` 与 `check-dev-flow.sh migrate-devflow-archives` 均通过;`--index` 重生成
+- [x] 9. 确认点 2:汇报产物与剩余风险,用户确认归档(2026-09-18,"继续")

openspec/changes/knowledge-index-panel/decision.md

@@ -0,0 +1,42 @@
+# Decision: 目录名作为日期和标题的真理源
+
+<!-- migrated-from: devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md (2026-09-18, change: migrate-devflow-archives) -->
+
+## Problem
+
+知识吸收器输出目录遵循 `knowledge_YYYYMMDD_Title/` 命名约定。目录内的 `.md` 文件包含 YAML frontmatter,其中也有 `date`/`created` 和 `title` 字段,但实际使用中发现字段名不一致(`date` vs `created`)且格式有差异。
+
+索引重建脚本需要确定日期和标题的权威来源——两个来源都存在且都可能被读到时,不指定权威就必然漂移。
+
+## Decision
+
+**日期和短标识符 (slug) 的真理源是目录名。显示标题、tags、author 的真理源是 YAML frontmatter。**
+
+- 日期从目录名的 `YYYYMMDD` 部分提取
+- 短标识符从目录名的 `Slug` 部分提取(用于文件路径构建,不用于显示)
+- 显示标题从 YAML frontmatter 的 `title` 字段提取
+- `tags` 和 `author` 从 YAML frontmatter 提取
+
+## Alternatives considered
+
+- Q: YAML 字段全优先? A: 不——字段名不一致(date vs created),脚本要处理变体,漂移点更多。
+- Q: 目录名全优先? A: 不——标题中的语义信息在下划线转空格后丢失(如 `mattpocock_skills` → `mattpocock skills`,实际标题更长更精确)。
+
+## Consequences
+
+**买到了**:
+- 索引脚本不需要处理日期字段名变体(date vs created)
+- 目录名是可见的、可审计的——与 `ls` 输出完全一致
+- bash 用 glob 匹配 `knowledge_*` 目录,天然获取了日期和 slug
+- 显示标题从 YAML 取,支持完整的、精确的标题文本(含标点、中文)
+
+**付出了**:
+- 索引脚本需要解析 YAML frontmatter(复杂度比仅取目录名高)
+- 如果目录被重命名,slug 会变化但显示标题不受影响(可接受的行为)
+- 知识吸收器 skill 必须严格遵守 `knowledge_YYYYMMDD_Slug` 命名约定
+
+## Verification
+
+**只读(可直接跑)**
+- `ls knowledge/entries/ | head -3` → 目录名均形如 `knowledge_YYYYMMDD_Slug`
+- `grep -n 'date' scripts/update-knowledge-index.sh | head -5` → 日期提取自目录名而非 YAML

openspec/changes/knowledge-index-panel/prd.md

@@ -0,0 +1,57 @@
+# PRD: 知识库索引面板 (Knowledge Index Panel)
+
+## Problem Statement
+
+用户每次用 `/knowledge-absorber` 学习后，会在项目根目录生成 `knowledge_YYYYMMDD_Title/` 文件夹。目前有 2 个知识条目，预计每月增长 5-10 个。所有条目散落在根目录，没有跨条目的导航或搜索能力。想找之前学过的内容只能手动翻目录，搜索成本随条目数线性上升。
+
+## Solution
+
+在项目根目录生成一个 **纯静态的 `knowledge-index.html`**，浏览器直接打开即可使用。它能自动发现所有 knowledge 条目，提供标签关联和全文搜索。不需要任何服务器、数据库或外部依赖。
+
+## User Stories
+
+1. As a 学习者, I want to see all my knowledge entries on one page with dates, so that I can quickly find what I studied and when
+2. As a 学习者, I want to search across all knowledge entries by keyword, so that I can find "that thing about Redis" in 2 seconds instead of manually opening 10 folders
+3. As a 学习者, I want to click a tag like "Claude Code" and see all related entries, so that I can review interconnected topics
+4. As a 学习者, I want the index to auto-discover new knowledge entries, so that I don't need to manually update anything after running `/knowledge-absorber`
+5. As a 学习者, I want the page to work offline by just double-clicking the HTML file, so that I can use it without internet or any setup
+6. As a 学习者, I want to see which entries are related to each other via shared tags, so that I can discover connections between topics I've studied
+7. As a 学习者, I want the search to highlight matching text, so that I can see at a glance why an entry matched my query
+8. As a 学习者, I want to see a count of entries per tag, so that I know which topics I've studied most
+
+## Implementation Decisions
+
+- **Single HTML file**: All CSS and JS inlined in `knowledge-index.html`. No external files or CDN dependencies
+- **Manifest-based discovery**: A JavaScript array inside the HTML lists all known knowledge directory names. Browser security sandbox prevents dynamic directory listing via `fetch()`
+- **YAML frontmatter parsing**: Regex-based extraction from `.md` files. Simple key:value parsing only — no full YAML spec support
+- **Client-side search**: All `.md` content loaded into memory at page init. Real-time filtering with `String.includes()`, case-insensitive. `<mark>` tags for highlighting
+- **Tag system**: In-memory `Map<tag, entry[]>` built at load time. Click to filter, click again to deselect
+- **Related Content**: Computed from shared tags, displayed per-entry
+- **No pagination**: Designed for < 50 entries. Full list rendered at once
+- **UTF-8 encoding**: All files assumed UTF-8. `fetch()` handles encoding detection
+
+## Testing Decisions
+
+- **What makes a good test**: Test external behavior — "user types keyword → correct entries appear" — not internal state
+- **Test with real data**: Use existing 2 knowledge entries (`knowledge_20260417_Waza`, `knowledge_20260518_mattpocock_skills`) as test fixtures
+- **Edge cases to verify**:
+  - Missing directory (manifest lists a name that doesn't exist) → skip gracefully
+  - Malformed YAML → display directory name as fallback
+  - Empty tags array → no tag badges rendered
+  - No search results → show "没有找到相关条目" message
+  - Browser CORS when opened via `file://` protocol → document the workaround
+
+## Out of Scope
+
+- Google Drive / cloud sync
+- Editing knowledge entries
+- Full YAML 1.2 spec compliance
+- Pagination or virtual scrolling
+- Fuse.js or other fuzzy search libraries (keep it zero-dependency)
+- Dark mode toggle (can add later, not in v1)
+
+## Further Notes
+
+- The manifest maintenance problem (adding new entries) can be solved in a future iteration by modifying the `/knowledge-absorber` skill to auto-append to the manifest array
+- The `file://` protocol CORS limitation on Chrome means users may need to serve via `python -m http.server` or similar for full functionality
+- Tag counts provide a natural "learning heatmap" — most-studied topics bubble to the top

openspec/changes/sm-flow-execution-hardening/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-22

openspec/changes/sm-flow-execution-hardening/design.md

@@ -0,0 +1,115 @@
+## Context
+
+这次 change 处理的是 `sm-flow` 的执行稳定性，而不是流程理念重构。已有文档已经定义了阶段顺序、Phase 2.9、接口影响、实现期冲突分类和 devflow 索引，但真实使用表明，规则如果没有变成“阶段切换前必须显式满足的条件”，就会在执行中被代理惯性绕开。
+
+受影响的主要文件位于：
+
+- `.agents/skills/sm-flow/SKILL.md`
+- `.agents/skills/sm-flow/references/phase-contracts.md`
+- `.agents/skills/sm-flow/references/fallbacks.md`
+- `.agents/skills/sm-flow/references/templates.md`
+- `skill-workbench/docs/sm-flow/workflow.md`
+
+这次改造的规则落点也需要明确分层：
+
+- `SKILL.md` 承载短而硬的总规则和 gate。
+- `phase-contracts.md` 承载逐阶段进入、动作、退出和 checkpoint。
+- `fallbacks.md` 承载 capability 不可用时的降级协议与记录要求。
+- `templates.md` 只在确有必要时提供轻量字段提示，不承载主逻辑。
+- `workflow.md` 只解释设计与演进背景，不重复执行细则或承担执行真理源职责。
+
+## Design
+
+### 1. Phase checkpoints as executable gates
+
+为每个关键阶段引入最小 checkpoint，要求代理在阶段结束时显式汇报：
+
+1. 当前阶段名称。
+2. 本阶段调用的 skill / 本地 `SKILL.md` / fallback。
+3. 本阶段产物。
+4. 已满足的退出条件。
+5. 未满足但仍阻塞下一阶段的问题。
+
+这个 checkpoint 不是替代现有 `phase-contracts.md`，而是把长契约压缩成执行中更容易遵守的门禁动作。
+本次设计只要求这些 checkpoint 具备明确字段和动作，不要求新增统一模板或统一展示格式。
+
+### 2. Skill/fallback declaration becomes a completion condition
+
+现有规则要求进入某些阶段时说明 skill 或 fallback，但执行中容易被忽略。硬化后：
+
+- 若本阶段未显式声明使用的能力来源，则阶段不得视为完成。
+- 若发生 fallback，必须同时记录：目标 skill、不可用原因、采用的 fallback 协议、降级风险。
+
+### 3. Phase 2 uses a question pool
+
+现有规则强调 one-at-a-time，但没有约束问题覆盖面。硬化后，Phase 2 先生成问题池，再逐个消费：
+
+- 问题池至少覆盖术语、边界、验收。
+- 对复杂任务，可继续覆盖权限、上下游触发、前端返回结构、兼容性、生命周期等。
+- `user-interview` 问题仍然一次只问一个，但问题池必须先暴露计划覆盖面。
+
+这样既保留 human-in-the-loop 约束，也降低“只问了几个问题就误以为够了”的风险。
+
+### 4. Cross-artifact alignment becomes explicit
+
+Phase 1.5 和 2.9 需要明确检查的对齐关系：
+
+- `brief/prd` -> `proposal`
+- `proposal` -> `design`
+- `design` -> `specs`
+- `specs` -> `tasks`
+- `evidence/decisions` -> OpenSpec 回写状态
+
+如果任何链路出现信息缺失、术语不一致、能力未落到 spec、spec 未落到 task，都必须在进入下一阶段前暴露。
+
+### 5. Micro mode preserves gates
+
+`micro` 继续允许合并产物，但明确禁止跳过：
+
+- Phase 0.5 最小上下文检查
+- Phase 2 最小澄清
+- Phase 2.9 commit gate
+- Phase 4 轻量归档
+
+这次 change 不增加 `micro` 的文档负担，而是把“不能跳哪些 gate”写得更硬。
+
+### 6. Devflow updates happen during the flow
+
+`devflow` 不再被视为“最后补文档”。设计上要求：
+
+- Phase 0 写入口摘要到 `brief.md`
+- Phase 2 写 evidence / decisions
+- Phase 2.5 写架构审计摘要
+- Phase 2.9 写 commit gate 结果
+- Phase 4 只做汇总和归档收尾
+
+这样 Phase 4 变成收敛，而不是返工。
+
+### 7. Rule placement avoids duplication drift
+
+本次 change 的一个隐含架构约束是避免同一规则在多个层面双份维护：
+
+- 如果某条规则属于执行门禁，应优先落在 `SKILL.md` 或 `phase-contracts.md`。
+- 如果某条规则属于 capability 降级，应优先落在 `fallbacks.md`。
+- `workflow.md` 可以解释为什么这样设计，但不应再逐条复制执行细则。
+- `templates.md` 保持可选和轻量，否则会把“协议硬化”扩大成“格式标准化”。
+
+这能降低 v3.1 之后再次出现“规则已经写了，但代理仍然执行漂移”的维护风险。
+
+## Risks / Trade-offs
+
+- 更强的 checkpoint 会增加少量流程显式成本，但可以换来更低的遗漏率。
+- 问题池可能让 Phase 2 看起来更正式，但如果不先暴露覆盖面，one-at-a-time 容易退化成随机追问。
+- 更硬的 cross-artifact 检查会让 change 前期更慢，但比在 apply 前后由用户兜底更可靠。
+- 如果把同一规则同时写进协议、模板和案例说明，后续维护面会再次变大，因此这轮需要严格控制规则落点。
+
+## Validation
+
+需要通过文档与 OpenSpec 产物验证以下结果：
+
+- `sm-flow` 明确要求阶段 checkpoint。
+- `micro` 明确禁止跳过关键 gate。
+- Phase 2 明确先形成问题池，再一次一问推进。
+- Phase 1.5 / 2.9 明确 cross-artifact 检查链路。
+- devflow 的过程内同步更新要求被写入协议。
+- 不要求代理额外输出统一格式的阶段汇报示例。

openspec/changes/sm-flow-execution-hardening/proposal.md

@@ -0,0 +1,47 @@
+## Why
+
+`sm-flow` 已经建立了 `OpenSpec-first / Devflow-assisted` 的主从关系，也补入了 Draft/Committed OpenSpec、接口影响分级、Phase 2.9 和实现期冲突分类等关键规则。但真实项目复盘显示，代理仍然会按“先读代码、先形成方案、尽快推进实现”的习惯行动，而不是稳定经过 phase gate、自检和一致性检查。
+
+当前问题不是主设计方向错误，而是执行协议还不够“硬”：
+
+- `micro` 模式容易被误解为可以跳过关键阶段。
+- skill/fallback 声明存在规则，但没有成为阶段完成条件。
+- Phase 2 有 one-at-a-time 约束，但没有先形成问题池，导致问题覆盖不足。
+- Phase 1.5 和 2.9 的 cross-artifact 检查缺少更明确的执行清单，遗漏只能等用户 review 才暴露。
+- devflow 产物容易被拖到 Phase 4 补写，而不是在过程内同步更新。
+
+因此需要新增一轮“执行硬化”改造，把现有规则收敛成更明确的阶段检查点、问题池机制和一致性检查要求。
+
+## What Changes
+
+- 为 `sm-flow` 增加更短、更高频的 phase checklist / checkpoint 规则。
+- 明确“未显式声明 skill 或 fallback = 本阶段未完成”。
+- 为 Phase 2 增加“先形成问题池，再一次一问推进”的要求。
+- 强化 Phase 1.5 / 2.9 的 cross-artifact diff 检查，覆盖 proposal、design、specs、tasks、brief、evidence、decisions 的一致性。
+- 明确 `micro` 只能压缩产物，不能跳过 Phase 0.5、Phase 2、Phase 2.9 等关键 gate。
+- 明确 devflow 默认在各阶段同步更新，而不是拖到 Phase 4 统一补写。
+- 明确本次改造不强制固定 checkpoint / alignment 模板，也不把统一阶段汇报格式纳入验收范围。
+
+## Capabilities
+
+### New Capabilities
+
+- `sm-flow-phase-checkpoints`: 定义各阶段的最小检查点和阶段完成条件。
+- `sm-flow-question-pool`: 定义 Phase 2 的问题池生成与单题推进规则。
+- `sm-flow-cross-artifact-alignment`: 定义 Phase 1.5 / 2.9 的跨产物一致性检查要求。
+- `sm-flow-micro-gate-preservation`: 定义 `micro` 模式下不可跳过的关键 gate。
+
+### Modified Capabilities
+
+- `sm-flow-commit-gate`: 增强提交前检查，补充 cross-artifact diff 和阶段状态显式确认。
+- `sm-flow-context-indexing`: 补充 devflow 过程内同步更新要求。
+
+## Impact
+
+- 修改 `.agents/skills/sm-flow/SKILL.md`
+- 修改 `.agents/skills/sm-flow/references/phase-contracts.md`
+- 修改 `.agents/skills/sm-flow/references/fallbacks.md`
+- 可能修改 `.agents/skills/sm-flow/references/templates.md`
+- 修改 `skill-workbench/docs/sm-flow/workflow.md`
+- 不修改业务代码
+- 不改变 `OpenSpec-first / Devflow-assisted` 主设计

openspec/changes/sm-flow-execution-hardening/specs/sm-flow-cross-artifact-alignment/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Phase 1.5 checks cross-artifact alignment explicitly
+
+SM Flow SHALL explicitly check alignment across requirement, design, specification, and execution artifacts during Phase 1.5.
+
+#### Scenario: Alignment check runs
+
+- **WHEN** Phase 1.5 reviews the current Draft OpenSpec
+- **THEN** it checks that `brief/prd` aligns with `proposal`, `proposal` aligns with `design`, `design` aligns with `specs`, and `specs` align with `tasks`
+
+#### Scenario: Alignment gap is found
+
+- **WHEN** an expected behavior, term, field, constraint, or implementation slice appears in one artifact but not its downstream artifact
+- **THEN** the flow marks the gap explicitly and repairs OpenSpec before entering the next phase
+
+### Requirement: Phase 2.9 validates cross-artifact closure
+
+SM Flow SHALL re-check cross-artifact closure during Phase 2.9 before implementation.
+
+#### Scenario: Commit gate runs
+
+- **WHEN** Phase 2.9 evaluates whether Draft OpenSpec can become Committed OpenSpec
+- **THEN** it verifies that `evidence.md` and `decisions.md` findings that affect implementation are reflected in proposal, design, specs, or tasks
+
+#### Scenario: User review would otherwise catch the gap
+
+- **WHEN** a field, scope item, acceptance behavior, or design constraint is missing from the downstream OpenSpec artifacts
+- **THEN** the flow SHALL fail the commit gate and return to the earlier phase that owns the missing update

openspec/changes/sm-flow-execution-hardening/specs/sm-flow-micro-gate-preservation/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Micro mode compresses artifacts but preserves critical gates
+
+SM Flow SHALL allow `micro` mode to reduce artifact weight without skipping critical gates.
+
+#### Scenario: Micro mode starts
+
+- **WHEN** a change is classified as `micro`
+- **THEN** the flow may merge or simplify devflow artifacts
+- **AND** it SHALL still perform Phase 0.5 minimum context harvest, Phase 2 minimum clarification, Phase 2.9 commit gate, and Phase 4 lightweight backfill
+
+#### Scenario: Micro mode is treated as skip permission
+
+- **WHEN** the agent attempts to skip a critical gate because the change is small or low-risk
+- **THEN** the flow SHALL treat that as a protocol deviation rather than a valid micro-mode optimization
+
+### Requirement: Devflow updates happen during the flow
+
+SM Flow SHALL update devflow artifacts during the relevant phases rather than deferring all updates to Phase 4.
+
+#### Scenario: Phase-local information is produced
+
+- **WHEN** a phase produces entry summary, evidence, decisions, architecture findings, or commit-gate conclusions
+- **THEN** the corresponding devflow artifact is updated in or near that phase
+
+#### Scenario: Phase 4 begins
+
+- **WHEN** the flow enters Phase 4
+- **THEN** devflow backfill is primarily a consolidation step rather than the first time those records are written

openspec/changes/sm-flow-execution-hardening/specs/sm-flow-phase-checkpoints/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Each critical phase has an explicit checkpoint
+
+SM Flow SHALL require an explicit checkpoint before a critical phase can be considered complete.
+
+#### Scenario: Phase completes normally
+
+- **WHEN** the agent finishes a critical phase such as Phase 0, Phase 0.5, Phase 1, Phase 2, Phase 2.5, or Phase 2.9
+- **THEN** it reports the current phase, the capability source used, the produced artifacts, the satisfied exit conditions, and any unresolved blockers
+
+#### Scenario: Checkpoint is missing
+
+- **WHEN** a critical phase has produced artifacts or conclusions but no explicit checkpoint summary
+- **THEN** the phase SHALL NOT be treated as complete for purposes of entering the next phase
+
+### Requirement: Capability declaration is part of phase completion
+
+SM Flow SHALL treat skill or fallback declaration as part of the phase completion condition.
+
+#### Scenario: Native skill or local protocol is used
+
+- **WHEN** a phase depends on a named capability such as `openspec-propose`, `grill-with-docs`, `zoom-out`, or `openspec-apply-change`
+- **THEN** the agent states whether it used a native skill, a local `SKILL.md`, or a fallback protocol
+
+#### Scenario: Fallback is used
+
+- **WHEN** a phase falls back from a named capability
+- **THEN** the agent records the target capability, the reason it was unavailable, the fallback protocol name, and the downgrade risk
+
+#### Scenario: Declaration is omitted
+
+- **WHEN** no capability source is declared for a phase that requires one
+- **THEN** that phase SHALL NOT be considered complete

openspec/changes/sm-flow-execution-hardening/specs/sm-flow-question-pool/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Phase 2 builds a question pool before interviewing
+
+SM Flow SHALL build a Phase 2 question pool before consuming `user-interview` questions one at a time.
+
+#### Scenario: Phase 2 starts
+
+- **WHEN** the flow enters Phase 2
+- **THEN** it defines a question pool that covers at least terminology, scope boundaries, and acceptance
+
+#### Scenario: Complex change needs deeper coverage
+
+- **WHEN** the change affects multiple modules, interfaces, permissions, downstream consumers, response structures, or lifecycle rules
+- **THEN** the Phase 2 question pool also includes those dimensions before user-interview consumption begins
+
+### Requirement: User-interview questions remain one-at-a-time
+
+SM Flow SHALL preserve the one-question-at-a-time rule while using a question pool.
+
+#### Scenario: User-interview question is asked
+
+- **WHEN** the next unresolved `user-interview` item is selected from the question pool
+- **THEN** the flow asks exactly one question, waits for the explicit user answer, records the result, and only then advances to the next `user-interview` item
+
+#### Scenario: Question pool exists but answer is missing
+
+- **WHEN** there are remaining question-pool items and the current `user-interview` question is unanswered
+- **THEN** the flow SHALL NOT ask another `user-interview` question until the current one is resolved

openspec/changes/sm-flow-execution-hardening/tasks.md

@@ -0,0 +1,24 @@
+## 1. OpenSpec artifacts
+
+- [x] 1.1 Write proposal for `sm-flow-execution-hardening`
+- [x] 1.2 Write design for execution hardening rules
+- [x] 1.3 Add specs for checkpoints, question pool, cross-artifact alignment, and micro gate preservation
+
+## 2. Protocol hardening
+
+- [x] 2.1 Update `.agents/skills/sm-flow/SKILL.md` with explicit phase checkpoint and stage-completion rules
+- [x] 2.2 Update `.agents/skills/sm-flow/references/phase-contracts.md` with question pool, cross-artifact alignment, and micro gate preservation rules
+- [x] 2.3 Update `.agents/skills/sm-flow/references/fallbacks.md` so fallback declaration is mandatory and recorded
+- [x] 2.4 Keep templates optional; only adjust them if existing references need minimal field hints rather than mandatory fixed formats
+
+## 3. Workflow documentation
+
+- [x] 3.1 Update `skill-workbench/docs/sm-flow/workflow.md` with the execution-hardening model
+- [x] 3.2 Ensure retrospective learnings are reflected as protocol rules rather than only narrative notes
+
+## 4. Validation
+
+- [x] 4.1 Validate the OpenSpec change
+- [x] 4.2 Verify key terms are consistently documented across skill, references, and workflow docs
+- [x] 4.3 Backfill devflow records after implementation if the change proceeds beyond Draft
+- [x] 4.4 Verify acceptance is satisfied by protocol/document changes alone, without requiring a standardized phase-report output format

openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

scripts/check-dev-flow.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# dev-flow 收尾检查 + index 派生
+#   检查模式: check-dev-flow.sh <slug>          → 对 openspec/changes/<slug>/ 执行三项收尾检查
+#   索引模式: check-dev-flow.sh --index         → 扫描 openspec/changes/archive/ 与 openspec/archive/ 生成 devflow/index.md
+#   全量模式: check-dev-flow.sh --all           → 对所有活跃 change 执行检查
+#
+# 三项收尾检查:
+#   1. decision.md 存在(豁免需显式: decision.md 或提交信息中写明)
+#   2. 含 ## Alternatives considered 或显式 <!-- alternatives-not-recorded -->
+#   3. ## Verification 无"已确认 X"类不可重跑结论
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CHANGES_ROOT="$PROJECT_ROOT/openspec/changes"
+
+fail() { echo "✗ $1" >&2; exit 1; }
+
+check_change() {
+    local slug="$1"
+    local dir="$CHANGES_ROOT/$slug"
+    local decision="$dir/decision.md"
+    local errors=0
+
+    [ -d "$dir" ] || fail "change 目录不存在: openspec/changes/$slug"
+
+    echo "== dev-flow 收尾检查: $slug =="
+
+    # 1. decision.md 存在
+    if [ ! -f "$decision" ]; then
+        echo "✗ [1] 缺少 openspec/changes/$slug/decision.md (纯机械改动可豁免,但豁免必须显式写在提交信息里)"
+        errors=$((errors+1))
+    else
+        echo "✓ [1] decision.md 存在"
+
+        # 2. Alternatives 强制
+        if grep -q '^## Alternatives considered' "$decision" || grep -q '<!-- alternatives-not-recorded -->' "$decision"; then
+            echo "✓ [2] 备选已记录或显式声明未记录"
+        else
+            echo "✗ [2] decision.md 缺少 ## Alternatives considered,也没有 <!-- alternatives-not-recorded --> 显式豁免"
+            errors=$((errors+1))
+        fi
+
+        # 3. Verification 无不可重跑结论
+        local vtext
+        vtext="$(awk '/^## Verification/{flag=1;next} /^## /{flag=0} flag' "$decision")"
+        if echo "$vtext" | grep -qE '已确认|已验证[^,。;(]|测试通过$'; then
+            echo "✗ [3] ## Verification 含不可重跑的结论(如\"已确认 X 存在\")——改为可重跑的命令或明确的人工步骤"
+            errors=$((errors+1))
+        elif [ -z "$vtext" ]; then
+            echo "✗ [3] 缺少 ## Verification 小节"
+            errors=$((errors+1))
+        else
+            echo "✓ [3] Verification 通过"
+        fi
+    fi
+
+    if [ "$errors" -gt 0 ]; then
+        echo "== $slug: $errors 项未通过 =="
+        return 1
+    fi
+    echo "== $slug: 全部通过 =="
+    return 0
+}
+
+gen_index() {
+    local out="$PROJECT_ROOT/devflow/index.md"
+    echo "# devflow 索引" > "$out"
+    echo "" >> "$out"
+    echo "> 本文件由 scripts/check-dev-flow.sh --index 派生生成,**不要手写**。" >> "$out"
+    echo "> 存储层是 openspec/archive/ 下的归档目录;此处只是浏览视图。" >> "$out"
+    echo "" >> "$out"
+
+    local found=0
+    local rows=()
+    local arch_dir
+    # 两个历史归档位置都扫:openspec/changes/archive/ 与 openspec/archive/
+    for arch_dir in "$CHANGES_ROOT/archive" "$PROJECT_ROOT/openspec/archive"; do
+        [ -d "$arch_dir" ] || continue
+        local d
+        while IFS= read -r d; do
+            d="${d%/}"
+            [ -d "$d" ] || continue
+            local name; name="$(basename "$d")"
+            local title; title=""
+            local date; date=""
+            local rel; rel="${d#"$PROJECT_ROOT"/}"
+            # 标题取 decision.md 首行,否则 proposal.md 首个 # 标题
+            if [ -f "$d/decision.md" ]; then
+                title="$(head -1 "$d/decision.md" | sed 's/^# *//; s/^[[:space:]]*//; s/[[:space:]]*$//' || true)"
+            elif [ -f "$d/proposal.md" ]; then
+                title="$(grep -m1 '^# ' "$d/proposal.md" | sed 's/^# *//' || true)"
+            fi
+            # 日期取目录名前缀 YYYY-MM-DD
+            if [[ "$name" =~ ^([0-9]{4}-[0-9]{2}-[0-9]{2}) ]]; then
+                date="${BASH_REMATCH[1]}"
+            fi
+            rows+=("| ${date:-—} | ${title:-$name} | ${rel} |")
+            found=$((found+1))
+        done < <(find "$arch_dir" -mindepth 1 -maxdepth 1 -type d | sort)
+    done
+
+    # 写表格(带表头)
+    {
+        echo "| 日期 | 标题 | 归档位置 |"
+        echo "|---|---|---|"
+        if [ ${#rows[@]} -gt 0 ]; then
+            printf '%s\n' "${rows[@]}"
+        fi
+    } >> "$out"
+
+    echo "[index] 生成 $found 个归档条目 → devflow/index.md"
+}
+
+case "${1:-}" in
+    --index)
+        gen_index
+        ;;
+    --all)
+        rc=0
+        for d in "$CHANGES_ROOT"/*/; do
+            d="${d%/}"
+            [ -d "$d" ] || continue
+            name="$(basename "$d")"
+            [ "$name" = "archive" ] && continue
+            check_change "$name" || rc=1
+        done
+        exit $rc
+        ;;
+    "")
+        echo "用法: check-dev-flow.sh <slug> | --all | --index" >&2
+        echo "  <slug>    对单个活跃 change 执行三项收尾检查" >&2
+        echo "  --all     检查所有活跃 change" >&2
+        echo "  --index   扫描归档生成 devflow/index.md" >&2
+        exit 2
+        ;;
+    *)
+        check_change "$1"
+        ;;
+esac

skill-workbench/docs/dev-flow/background-and-evolution.md

@@ -0,0 +1,584 @@
+# 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 行)同名但设计相反 | **已删除**(2026-09-18) |
+| 2 | `sm-flow` 归档 | **改造完成后归档**。完成定义:`scripts/check-dev-flow.sh` 落盘 ✅ + 一次从 Think 开始的全路径真实运行 + 一条旧档案迁移规则(单样本) |
+| 3 | 现有 3 个活跃 change(`knowledge-index-panel` / `add-year-filter` / `sm-flow-execution-hardening`) | **本次忽略** |
+| 4 | 现有 9 个项目 37 个 devflow 文件的迁移 | 未定;先做单样本再定规则。SuperBizAgent 实测(46 项目/180 文件)给出处置口径:压缩 Q&A 与 ADR 段落并入对应归档的 decision.md,骨架文件删除 |
+| 5 | `rejected/` 是否照搬 DSH 的 6 类关闭集 | 沿用,未验证 |
+| 6 | "计划写在 `decision.md` 却从未更新为事实"会不会出现 | 观察到再引入 DSH 的两套骨架 |
+| 7 | `scripts/check-dev-flow.sh` 与 `devflow/index.md` | **已落盘**(2026-09-18):`<slug>` / `--all` / `--index` 三种模式,三项收尾检查 + index 派生均已实测 |
+
+### 9.1 SuperBizAgent 实证带来的协议修订(2026-09-18)
+
+SuperBizAgent-java 是 sm-flow 唯一一次大规模实践(6 周、46 项目、180 档案文件)。实证结论与据此合入的修订:
+
+| 实证 | 据此修订 |
+|---|---|
+| 备选记录率 **0/180**(段落式太贵,没人写) | Alternatives 首选形态改为**压缩 Q&A 一行**,寄生在 grill 问答当场 |
+| 后期 `apply pre-authorized` 常态化静默绕过确认点 | 确认点 1 增加显式旁路 `<!-- pre-authorized: 日期 + 范围/原因 -->`,兼作授权的文件载体 |
+| 手写 index 腐化(死链/自指/状态不符) | index 只由 `check-dev-flow.sh --index` 派生,协议明令不手写 |
+| 4 文件配额在小变更上产出 176B 占位文件 | 不加回分档;触发规则补充"小修不进来,事后可补录" |
+| "参考 XXX 实现"没读导致返工 4-5 次(v4.1 的真实教训) | Build 契约加一行:点名参考的实现,动手前先完整读 |
+
+---
+
+## 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") |

skill-workbench/docs/sm-flow/design-review.md

@@ -0,0 +1,432 @@
+# SM-Flow 设计评审与修改方向
+
+**日期**：2026-05-25
+**目的**：基于完整代码审阅和讨论，落地当前设计的评估结论和下一步修改方向。
+
+---
+
+## 核心定位：sm-flow 是一个协议层 Harness
+
+### 本质认知
+
+sm-flow 不是一个"更好的 skill"，也不是 OpenSpec 的增强插件。它是一个**用提示词实现的协议层 harness**——控制 agent 以什么顺序、什么条件、什么标准使用工具。
+
+### Harness 能力对照
+
+| Harness 能力 | sm-flow 的实现 |
+|---|---|
+| 流程编排 | Phase 0 → 0.5 → 1 → 1.5 → 2 → 2.5 → 2.9 → 3 → 4 |
+| 门控 | Draft/Committed gate、checkpoint、退出条件 |
+| 上下文管理 | Phase 0.5 harvest、首次加载策略、按需读取 |
+| 权限控制 | human-in-the-loop、user-interview 必须等确认 |
+| 工具调度 | 每个 Phase 指定子 skill、fallback 链 |
+| 护栏 | micro≠skip、不得猜测式修 bug、冲突必须先分类 |
+
+### 四层架构
+
+```
+Claude Code Harness  → 代码层：工具权限、hooks、context window（agent 绕不过）
+  sm-flow Harness    → 协议层：工作流阶段、门控规则、产物约束、人类对齐（提示词实现）
+    OpenSpec         → 执行引擎：propose/apply/archive 的具体操作
+      Sub-skills     → 能力层：grill、zoom-out、diagnose、tdd
+```
+
+sm-flow 位于 Claude Code harness 和 OpenSpec 之间。Claude Code harness 控制 agent **能做什么**（工具、权限、context），sm-flow harness 控制 agent **怎么做**（顺序、条件、标准）。OpenSpec 是被调度的执行引擎，子 skill 是被调用的能力单元。
+
+### 与代码层 Harness 的关键区别
+
+- 代码层 harness（Claude Code）是**代码实现**的，agent 物理上绕不过
+- 协议层 harness（sm-flow）是**提示词实现**的，agent 理论上可以违反
+
+因此 sm-flow 需要 checkpoint、显式约束、降级声明等机制来强化执行力。这些机制的本质就是**弥补提示词 harness 缺乏物理强制力的弱点**。
+
+### 这个定位对后续设计的指导意义
+
+以 harness 思想为核心，所有后续修改都应该回答同一个问题：
+
+> **这条规则/机制是在约束 agent 的什么行为？约束力够不够？会不会过度限制 agent 的判断力？**
+
+具体推论：
+
+1. **约束粒度**：当前以阶段级约束为主，关键动作（冲突分类、one-at-a-time）单独加约束。粒度选择合理，后续新增约束应遵循同一粒度策略。
+2. **可组合性**：harness 的子模块能否独立加载？当前 Phase 2 的 grill、Phase 2.5 的 zoom-out 已经有独立性，但缺少独立的进入协议。
+3. **可观测性**：checkpoint 机制是 harness 的 telemetry。每个 checkpoint 汇报当前阶段、能力来源、产出物、退出条件、blocker——这相当于告诉外部"agent 现在在做什么、为什么卡住了"。
+4. **设计自由度**：作为 harness，sm-flow 天然有权约束被编排对象（OpenSpec）的使用方式——task 粒度检查、specs 可验收性评分、apply 进度汇报格式都是合理的编排行为。
+
+---
+
+## 当前状态评估
+
+### 架构概览
+
+```
+SKILL.md（~85行）                    ← 入口协议：定位、真理源、~22条硬规则、阶段总览
+references/
+├── phase-contracts.md（~274行）      ← 逐阶段契约：进入/动作/输出/退出/checkpoint
+├── operating-rules.md（~95行）       ← 运行规则：接口分级、启动检查、产物分层、快速模式、完成标准
+├── fallbacks.md（~132行）            ← 降级协议：通用记录要求 + 8 个 fallback
+├── archive-rules.md（~130行）        ← 归档规则：提取映射、索引维护、验收分类、ADR 条件
+└── templates.md（~352行）            ← 产物模板：brief/evidence/decisions/acceptance/PRD/ADR/...
+```
+
+总计约 1070 行。首次加载只读 SKILL.md + phase-contracts.md（~360 行），其余按需补读。
+
+### 演进脉络
+
+```
+v1   dev-flow：基础流程骨架（Phase 1-4）
+     ↓ 痛点：产物散落 5 个目录，archive 后上下文全丢
+v2   增加 devflow/ 聚合层（人类档案层 vs 机器工作区分离）
+     ↓ 痛点：devflow 产物越来越完整，agent 直接拿 devflow 写代码，OpenSpec 被架空
+v3   真理源分层：devflow=上下文, OpenSpec=执行, 代码=结果
+     ↓ 痛点：devflow 和 OpenSpec 产物大量重叠；grill 后返工 proposal/design
+v3.1 Draft/Committed 分离 + 可执行 gate + 产物瘦身 + 接口影响分级
+     ↓ 痛点：规则太多堆在 SKILL.md，agent 加载后上下文被冲走
+v3.1+ 协议瘦身：SKILL.md 减负 → operating-rules.md + fallback 去重 + 引用自洽
+```
+
+每一版都从真实执行失败中提炼，不是理论推演。
+
+### 已经做得好的
+
+**1. 协议自洽性**
+
+SKILL.md → phase-contracts → operating-rules → fallbacks → archive-rules → templates 之间的引用关系完整。cross-reference 断链问题（fallback 锚点中文名、接口分级引用）已修掉。
+
+**2. 失败驱动迭代**
+
+retrospective.md 逐阶段分析"应该做什么 / 实际做了什么 / 没做到什么"，使用问题.md 收集了 7 个真实痛点。当前版本的规则几乎都能追溯到一次真实失败。
+
+**3. 对 agent 行为模式的准确预判**
+
+规则大量出现"不得把单个决策确认推断为执行授权""micro 不等于跳过""evidence-driven 不是自动通过"——这些是 agent 的真实偷懒模式。规则写的不是"应该做什么"，而是"agent 会怎么绕过，以及如何堵死"。
+
+**4. 7 个核心设计决策逻辑自洽**
+
+| # | 决策 | 为什么 |
+|---|---|---|
+| 1 | OpenSpec 是唯一执行真理源 | 防止 devflow 和 OpenSpec 成为并列执行依据 |
+| 2 | Draft / Committed 分离 | Phase 1 产出是讨论对象，Phase 2.9 是显式 gate |
+| 3 | devflow 按阶段就近写入，Phase 4 做 consolidation | 防止 Phase 4 变成"第一次补写" |
+| 4 | Question Pool + one-at-a-time | 先列全风险面，再逐项消费 |
+| 5 | Cross-artifact 对齐链 | brief→proposal→design→specs→tasks 每层接住上游 |
+| 6 | 能力绑定而非路径绑定 | 子 skill 可跨平台迁移 |
+| 7 | Micro ≠ Skip | 产物可合并，gate 不能省略 |
+
+---
+
+## 已确认的修改方向
+
+### 修改 1：定位修正——明确"协议层 Harness"身份 ✅ 已实施
+
+**问题**：当前 SKILL.md 说"不替代 OpenSpec，而是增强"，但实际上 sm-flow 是一个编排 OpenSpec 生命周期的协议层 harness。OpenSpec 是被调度的执行引擎，sm-flow 控制它什么时候跑、怎么跑、跑完怎么收。
+
+**修改方向**：
+
+- SKILL.md 角色定位段落改写，以 harness 思想为核心：sm-flow 编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec
+- 不再说"不替代"，正面描述编排职责
+- 真理源分层改为四层架构：
+
+```
+sm-flow        → 编排层（harness）：阶段、门控、产物约束、人类对齐
+  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
+    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
+      code     → 实现结果：apply 的产出
+```
+
+**影响范围**：SKILL.md 的角色定位和真理源分层段落。其他规则不需要变——它们本来就在做 harness 的事。
+
+**设计自由度**：定位明确后，未来 sm-flow 约束 OpenSpec 使用方式（task 粒度检查、specs 可验收性评分、apply 进度汇报格式）都是合理的编排行为，不再需要解释"为什么 sm-flow 可以管 OpenSpec"。
+
+### 修改 2：Fallback 重新定位——从"降级"到"内置执行引擎" ✅ 已实施
+
+**问题**：当前 fallbacks.md 把 OpenSpec 不可用时的处理称为"降级协议"。但从 harness 视角看，sm-flow 作为编排层天然需要自带执行能力——当外部执行引擎（OpenSpec CLI）不可用时，harness 自己接管执行不是"降级"，而是正常的能力切换。
+
+**修改方向**：
+
+- fallbacks.md 中 OpenSpec 相关的 fallback 重新定位为"内置执行协议"
+- 优先级描述改为：优先使用 openspec CLI / 原生 skill（外部执行引擎）→ 不可用时 sm-flow 使用内置执行协议（内置执行引擎）
+- SKILL.md 首次加载或角色定位部分加一句：sm-flow 不强制依赖 openspec CLI，内置执行协议可以纯文件方式完成整个流程
+- 措辞从"降级风险"调整为"外部引擎不可用，切换为内置引擎"，保留声明和记录要求，但去掉"降级"暗示的能力不足感
+
+**影响范围**：fallbacks.md 的措辞 + SKILL.md 首次加载或角色定位段落。
+
+### 修改 3：新用户上手体验——devflow 概念延迟暴露 ✅ 已实施
+
+**问题**：SKILL.md 第一段就直接引入 `devflow/` 概念，对不熟悉的新用户来说突兀。从 harness 视角看，devflow 是 harness 的内部记忆机制，不是用户需要理解的概念——就像用户不需要理解 Claude Code 的 context window 管理一样。
+
+**修改方向**：
+
+- SKILL.md 角色定位段落中，先用一句话说清 sm-flow 会自动管理项目长期记忆，用户不需要手动维护
+- 把 devflow 的技术细节从角色定位移到真理源分层段落中自然引出
+- 对用户可见的概念只有：sm-flow（流程）→ OpenSpec（变更）→ 代码（结果）
+
+**影响范围**：SKILL.md 角色定位段落。
+
+---
+
+## 待讨论的设计问题
+
+以下是已识别但尚未决定是否修改的问题，留待后续讨论。
+
+### 问题 1：流程总成本 ✅ 已确认方向
+
+**分析**：问题不是"流程太贵"，而是**固定成本没有随规模充分缩放**。Phase 0/0.5/1.5/2.5/2.9/4 的成本基本是 O(1) 的——不随代码量线性增长。当前 micro 只压缩了产物（少写几个文件），没有压缩 gate 数量。
+
+| 改动规模 | 代码工作量 | 流程开销 | 开销占比 | 感受 |
+|---|---|---|---|---|
+| micro（30min 代码） | 30 min | 40-60 min | ~60% | 太重 |
+| standard（2h 代码） | 2 h | 1-1.5 h | ~40% | 还行 |
+| complex（1-2d 代码） | 12 h | 2-3 h | ~20% | 值得 |
+
+**确认方向**：micro 模式下合并 gate，不只是压缩产物。
+
+```
+当前 standard：Phase 1 checkpoint → Phase 1.5 → Phase 2 → Phase 2.5 checkpoint → Phase 2.9
+micro 合并后：Phase 1+1.5 合并 checkpoint → Phase 2（最少 1 个问题） → Phase 2.9（简化检查）
+```
+
+micro 的定位从"产物变少"变为"gate 变少但保留最关键的"（Phase 2 最小澄清 + Phase 2.9 commit gate）。
+
+**✅ 已落地**：operating-rules.md 快速模式段落已重写（gate 合并策略），phase-contracts.md 中各阶段已使用英文命名并体现 micro 行为。
+
+### 问题 2：Phase 1 ↔ Phase 2 循环收敛 ✅ 已确认方向
+
+**根因**：当前阶段顺序是 Phase 1 一次性产出完整 4 件套（proposal + design + specs + tasks），Phase 2 才做 grill 澄清。澄清结果必然要回写已经细化过的 design/specs/tasks，形成不可避免的返工循环。这不是 agent 执行问题，是**流程顺序决定了返工必然存在**。
+
+这也是使用问题.md 中第 3 条提到的核心痛点："propose 之后生成了 task、design 等产物，再用 grill 澄清需求，澄清完又得回去更新"。
+
+**确认方向**：调整阶段执行顺序，先澄清再细化。Phase 1 只产出轻量 proposal，Phase 2 在轻量 proposal 上做 grill，Phase 1.5 在需求稳定后才补全完整 OpenSpec。
+
+| | Phase 1（轻量 propose） | Phase 1.5（细化 + 对齐） |
+|---|---|---|
+| 执行者 | sm-flow 内置协议 | openspec-propose 或内置协议 |
+| 产出 | 只写 proposal.md（范围、问题、方案方向、非目标） | 补全 design.md + specs/ + tasks.md |
+| 目的 | 建立讨论对象 | 需求稳定后生成完整 OpenSpec |
+| token 成本 | 低 | 正常 |
+
+调整后的阶段顺序：
+
+```
+Phase 0    入口澄清
+Phase 0.5  devflow 上下文收集
+Phase 1    轻量 propose（sm-flow 内置协议，只写 proposal.md）  ← 不调用 openspec-propose
+Phase 2    grill 澄清（基于 proposal.md，把需求钉死）
+Phase 1.5  细化 + cross-artifact 对齐（调用 openspec-propose 补全 design/specs/tasks）
+Phase 2.5  架构审计
+Phase 2.9  commit gate
+Phase 3    apply
+Phase 4    回填 devflow
+```
+
+**三个附带收益**：
+
+1. **循环消失**：grill 在细化之前，不存在"细化 → grill → 回写细化"的循环
+2. **token 节省**：micro 模式下 Phase 1 只写轻量 proposal，不浪费 token 写详细产物（与问题 1 联动）
+3. **openspec-propose 角色更准确**：不再是"从零 propose"，而是"基于已稳定的 proposal 做细化补全"——harness 对执行引擎的合理调度
+
+**Phase 编号不变，Phase 2 和 Phase 1.5 的执行顺序对调**。阶段总览列表中的编号保持原样，但实际执行顺序变为 0 → 0.5 → 1 → 2 → 1.5 → 2.5 → 2.9 → 3 → 4。
+
+**✅ 已落地**：SKILL.md 阶段总览使用英文命名（clarify → archive），phase-contracts.md 已按新顺序重写（grill 在 specify 前），fallbacks.md 中 OpenSpec 提案降级触发时机改到 specify 阶段。
+
+### 问题 3：devflow 就近写入 vs agent 注意力 ✅ 已确认方向
+
+**分析**：Phase 1-3 期间要求 agent 同时维护 OpenSpec（执行真理源）和 devflow（人类档案层），本质上是**双重记录**——同一份内容写两遍，Phase 4 还要再检查修正，变成三次写入。
+
+**确认方向**：Phase 1-3 只维护一个轻量 decisions.md 作为过程日志，Phase 4 从中提取完整 devflow。
+
+| 阶段 | 写入什么 | 性质 |
+|---|---|---|
+| Phase 1-3 | 只维护 `decisions.md`（grill 结论、关键决策、验证结果） | 过程日志，轻量追加 |
+| Phase 4 | 从 decisions.md + OpenSpec 产物提取 brief/evidence/acceptance | 最终档案，一次性提取 |
+
+**约束**：Phase 4 的 devflow 提取必须基于 decisions.md 和 OpenSpec 产物，不能是纯粹的事后回忆录。decisions.md 是提取的依据链。
+
+**✅ 已落地**：SKILL.md 核心规则已改为"clarify → apply 只维护 decisions.md 作为过程日志；archive 阶段从中提取完整 devflow 档案"，phase-contracts.md 各阶段退出条件已同步更新。
+
+### 问题 4：部分阶段独立使用 ✅ 已确认方向
+
+**问题**：当前支持"指定阶段模式"，但从中间启动时上游阶段的产物可能不满足当前阶段的进入条件。
+
+**确认方向**：借鉴 OpenSpec 的 "Actions, Not Phases" 设计哲学——**用户命令表达意图，不表达阶段**。阶段是 harness 的内部词汇，不是用户的 API。
+
+**用户命令设计（4 个）**：
+
+```
+/sm-flow                    → 完整流程（从入口到归档）
+/sm-flow explore            → 先聊聊（需求不清楚）
+/sm-flow apply              → 直接执行（已有 Committed OpenSpec）
+/sm-flow archive            → 归档（执行完了，回填 devflow + 归档 OpenSpec）
+```
+
+| 命令 | 用户意图 | harness 内部行为 |
+|---|---|---|
+| `/sm-flow` | 从头到尾 | 完整编排 9 个阶段 |
+| `/sm-flow explore` | 先想想 | 带上下文的探索模式 |
+| `/sm-flow apply` | 只执行 | 检查 commit gate → apply |
+| `/sm-flow archive` | 收尾 | backfill devflow + 归档确认 |
+
+**典型使用场景**：
+
+```
+# 第一次：完整规划
+/sm-flow 给站内消息加 OMC 支持
+→ 走完 propose → grill → specify → audit → commit
+→ 停在 apply 前，用户说"先不执行了"
+
+# 第二次：继续执行
+/sm-flow apply ops-message-support
+→ 进入 apply，执行完 tasks
+
+# 第三次：归档
+/sm-flow archive ops-message-support
+→ 回填 devflow，询问是否归档 OpenSpec change
+```
+
+三个阶段，三次调用，每次只做一个用户意图的事。
+
+**阶段命名（内部协议）**：
+
+借鉴 OpenSpec 的动词式命名风格，阶段名称保留为 **agent 的词汇表**（用于 checkpoint 汇报和进度通知），不作为用户命令：
+
+```
+旧编号      →  描述名（内部）    做什么
+Phase 0    →  clarify          入口澄清
+Phase 0.5  →  context          上下文收集
+Phase 1    →  propose          轻量 propose（只写 proposal）
+Phase 2    →  grill            人类对齐澄清
+Phase 1.5  →  specify          细化 + 对齐（补全 design/specs/tasks）
+Phase 2.5  →  audit            架构审计
+Phase 2.9  →  commit           commit gate
+Phase 3    →  apply            OpenSpec 执行
+Phase 4    →  archive          回填 devflow + 归档确认
+```
+
+**agent 用阶段名做 telemetry**：
+- "当前在 grill 阶段，已解决 2/5 个问题"
+- "grill 完成，进入 specify"
+
+**用户用自然语言交互**：
+- "/sm-flow" → 启动完整流程
+- "ops-message-support 的 grill 已经做完了，继续" → harness 识别意图，自动补做最小前置检查
+- "帮我检查一下 add-dark-mode 的 OpenSpec 对齐" → harness 识别意图，只做 specify 阶段的对齐检查
+
+**核心原则**：用户只需要知道四件事（完整流程 / explore / apply / archive），其余全部通过自然语言交互，由 harness 识别意图后编排。
+
+**✅ 已落地**：SKILL.md 用户命令表格（4 个命令），operating-rules.md 启动检查已识别用户命令意图，phase-contracts.md 所有阶段已使用英文命名。
+
+### 问题 5：workflow.md 的维护方式 ✅ 已确认方向
+
+**问题**：workflow.md 是 590 行的设计演进文档，混合了三类内容：设计理念（稳定）、变更日志（每次迭代追加）、历史对比（写完不动）。读者需要翻 590 行才能理解"现在的设计是什么"。
+
+**确认方向**：方向 A——顶部加"当前设计理念"摘要，历史部分作为审计轨迹保留。
+
+```markdown
+# SM-Flow 工作流
+
+## 当前设计理念（v4 方向）
+- sm-flow 是协议层 harness，编排 OpenSpec 生命周期
+- 四层架构：harness → OpenSpec → devflow → code
+- 用户命令 4 个：/sm-flow / explore / apply / archive
+- 9 个内部阶段（英文描述命名）：clarify → context → propose → grill → specify → audit → commit → apply → archive
+- 阶段名是内部协议，不是用户 API
+- 真理源分层：devflow=上下文, OpenSpec=执行, 代码=结果
+- Draft/Committed 分离
+- ...（20-30 行）
+
+---
+
+## 演进历史
+（原有的 v1→v3.1+ 内容不动）
+```
+
+**来源**：design-review.md 的"核心定位"章节可以直接作为摘要的草稿。
+
+**⏳ 待落地**：在 workflow.md 顶部插入当前设计理念摘要段落（本项属于文档维护，不在 skill 文件范围内）。
+
+### 问题 6：SKILL.md 核心规则分类 ✅ 已确认方向
+
+**问题**：当前 ~22 条核心规则平铺在一个列表里，混合了三种不同性质的约束。agent 读到第 15 条已经记不清前 5 条的优先级。
+
+**确认方向**：三类分组 + 英文阶段命名 + 质量约束必须有可观测产出。
+
+**A. 三类分组**
+
+```markdown
+## 核心规则
+
+### 硬约束（违反即流程失败）
+- apply 必须通过 OpenSpec apply 执行
+- 不得跳过 context
+- 不得跳过 grill（至少三个高价值问题）
+- 不得跳过 commit
+- 不得猜测式修 bug
+- fallback 产物必须标注
+- micro 不能跳过关键 gate
+
+### 流程约束（必须按顺序做）
+- 先建 question pool，再消费 user-interview
+- 单个 grill 决策确认不等于 apply 授权
+- 冲突必须先分类再处理
+- 影响实现的发现必须先回写 OpenSpec
+- 子 skill 必须显式调用或显式降级
+- clarify → apply 只维护 decisions.md，archive 阶段提取完整档案
+- archive 前必须询问是否归档
+
+### 质量约束（必须有可观测产出）
+- specify 的 checkpoint 必须包含 cross-artifact 对齐检查表（4 行，每行标记已对齐/存在 gap）
+- evidence-driven 结论必须写入 decisions.md，且 checkpoint 必须列出汇报状态
+- user-interview 必须在 decisions.md 中记录问题原文、用户原话、确认状态；未确认的不能从 question pool 移除
+- checkpoint 必须包含：当前阶段、能力来源、产出物清单、已满足退出条件、未解决阻塞
+- human-in-the-loop 检查点：propose 后、audit 后、commit 后、apply 前
+
+> 三类约束都不可违反。分类的目的是帮助快速定位规则类型。
+> 质量约束必须转化为可观测的产出（写入文件 + checkpoint 检查），否则不是约束而是建议。
+```
+
+**B. 阶段编号改为英文描述名**
+
+去掉 Phase 0/0.5/1/1.5/2/2.5/2.9/3/4 的数字编号，全部用英文动词：
+
+```
+clarify  → 入口澄清
+context  → 上下文收集
+propose  → 轻量 propose（只写 proposal）
+grill    → 人类对齐澄清
+specify  → 细化 + cross-artifact 对齐
+audit    → 架构审计
+commit   → commit gate
+apply    → OpenSpec 执行
+archive  → 回填 devflow + 归档确认
+```
+
+执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive
+
+用户命令是 API（4 个），阶段名是内部协议（9 个）。风格统一（英文动词），职责分离。
+
+**C. 质量约束的可观测产出原则**
+
+协议层 harness 的核心弱点：质量约束如果没有可观测的产出，agent 一定会跳过。
+
+| 约束 | 原写法（软） | 改为（硬） |
+|---|---|---|
+| evidence-driven 汇报 | "必须向用户汇报" | 写入 decisions.md + checkpoint 列出汇报状态 |
+| user-interview 确认 | "必须等待用户显式回答" | decisions.md 记录问题原文/用户原话/确认状态 |
+| cross-artifact 对齐 | "必须显式检查" | checkpoint 包含 4 行对齐检查表，每行标记已对齐/存在 gap |
+
+**✅ 已落地**：SKILL.md 核心规则已按三类分组重写（硬约束 / 流程约束 / 质量约束），phase-contracts.md 所有阶段使用英文命名，各 checkpoint 退出条件已加可观测产出检查。
+
+### 问题 7：grill 阶段 evidence-driven 和 user-interview 的节奏 ✅ 已确认方向
+
+**问题**：当前规则说"可以并行整理 evidence-driven 证据，但 user-interview 仍然必须 one-at-a-time"。但 agent 可能把所有 evidence-driven 结论一口气汇报完，然后才问 user-interview 问题，导致用户被动接收大量信息后再被采访。
+
+**确认方向**：在 grill 阶段的动作描述里明确"交替推进"。
+
+```markdown
+grill 阶段的推进节奏：
+- evidence-driven 和 user-interview 应交替推进，避免把所有证据结论攒到一起汇报
+- 典型模式：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续
+- evidence-driven 可以并行查证（不需要用户参与），但汇报和 user-interview 穿插进行
+```
+
+**实际落地**：phase-contracts.md grill 阶段动作描述已调整。经评估后，"交替推进"对 agent 的要求过高（LLM 天然倾向批量处理），改为更务实的"先批量查证 evidence-driven 并一次性汇报，再逐个处理 user-interview"，降低执行复杂度同时保留核心约束。

skill-workbench/docs/sm-flow/phase-contracts-v4.1-changelog.md

@@ -0,0 +1,216 @@
+# SM Flow Phase Contracts v4.1 更新日志
+
+> 更新日期: 2026-06-23  
+> 更新原因: 基于"山东商客意向单同步接口"执行复盘  
+> 更新方案: 方案 B（简化版）
+
+---
+
+## 更新概览
+
+**核心目标**: 减少 apply 阶段的返工次数（从 4-5 次降低到 0-1 次）
+
+**更新范围**:
+- ✅ grill 阶段：增加技术实现维度
+- ✅ apply 阶段：增加 Pre-apply Checkpoint
+
+**文本增量**: +55 行（从 281 行 → 336 行，+20%）
+
+---
+
+## 详细修改
+
+### 1. grill 阶段 — 增加技术实现维度
+
+**修改位置**: `phase-contracts.md` 第 85-88 行
+
+**新增内容**:
+```markdown
+- **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
+  - 参考实现的具体文件路径是什么？
+  - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
+  - 有哪些技术点需要先调研或新建？
+```
+
+**目的**: 在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
+
+---
+
+### 2. apply 阶段 — 增加 Pre-apply Checkpoint
+
+**修改位置**: `phase-contracts.md` 第 234-265 行
+
+**新增章节**: Pre-apply Checkpoint（15-20 分钟）
+
+#### 触发条件（3 条）
+- design 或 tasks 中提到"参考 XXX 实现"
+- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
+- 技术栈不熟悉或第一次在该项目实现类似功能
+
+#### 执行步骤（3 步）
+1. **完整阅读所有参考实现**（约 10 分钟）
+   - 从 OpenSpec design 或 tasks 中定位参考实现文件
+   - 如果路径不明确，通过 Grep 搜索关键类名或模式
+   - 逐行理解关键逻辑，提取可复用代码片段和模式
+
+2. **Grep 关键技术栈**（约 5 分钟）
+   - 请求/响应结构模式
+   - 消息队列模式
+   - 统一工具类
+   - 异常处理和日志记录标准
+
+3. **形成技术栈清单并写入 decisions.md**
+   - 项目使用的请求/响应结构标准
+   - MQ 消息定义和发送标准
+   - Consumer 标准位置和写法
+   - 加密/验签/工具类的标准用法
+   - 识别需要新建的工具类或基础设施
+
+#### 输出要求（3 条）
+- ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
+- ✅ 已列出所有参考实现的文件路径
+- ✅ 已识别需要新建的工具类/基础设施
+
+#### 快速模式支持
+- micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单
+
+---
+
+### 3. apply 阶段 — 实现过程增强
+
+**修改位置**: `phase-contracts.md` 第 267-284 行
+
+**新增要求**:
+- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序
+- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能不允许空实现或纯 TODO 注释
+- **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报
+
+---
+
+### 4. apply 阶段 — 退出条件增强
+
+**修改位置**: `phase-contracts.md` 第 286-292 行
+
+**新增退出条件**:
+- ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
+- ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
+
+---
+
+## 简化对比
+
+### 与完整方案对比
+
+| 维度 | 完整方案 | 简化方案 B | 差异 |
+|------|----------|-----------|------|
+| 文本增量 | +100 行 | +55 行 | -45% |
+| 子阶段数 | 3 个（Phase 1/2/3） | 1 个（Pre-apply Checkpoint） | -67% |
+| 强制规则 | 9 条 | 5 条 | -44% |
+| 检查清单 | 2 个详细清单 | 1 个简化清单 | -50% |
+| 时间分档 | 3 档（15/20/30 分钟） | 1 档（15-20 分钟） | -67% |
+
+### 保留核心价值
+
+✅ **保留**（解决返工问题）:
+- 前置调研（最重要）
+- 技术栈清单（防止想当然）
+- 核心功能不能空实现（保证质量）
+- 快速失败机制
+
+❌ **简化**（去掉过度约束）:
+- 严格的执行顺序
+- 频繁的检查点
+- 详细的操作指南模板
+
+---
+
+## 预期效果
+
+### 量化指标
+
+| 指标 | 当前 | 目标 | 改善 |
+|------|------|------|------|
+| 返工次数 | 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%
+```
+
+---
+
+## 适用场景
+
+### ✅ 强烈推荐
+
+- 中等及以上规模需求（3+ 接口或涉及多模块）
+- 涉及项目现有基础设施（MQ/统一请求结构/工具类）
+- 第一次在该项目实现类似功能
+- 设计文档提到"参考 XXX 实现"
+
+### 🟡 可选执行
+
+- micro 分档的简单需求（可缩短为 5-10 分钟）
+- 纯数据处理或工具脚本（技术栈熟悉）
+
+### ❌ 不推荐
+
+- 紧急热修复（时间紧急）
+- 一次性脚本（不涉及项目标准）
+
+---
+
+## 后续优化方向
+
+### 短期（1-2 个需求后）
+
+- 收集数据：实际调研时间、返工次数、遗漏率
+- 验证效果：是否达到预期 ROI
+- 调整参数：时间要求、触发条件
+
+### 中期（观察 5+ 个需求后）
+
+如果效果显著，考虑升级为完整方案：
+- 增加 Alignment Checkpoint（每模块对齐检查）
+- 增加详细的技术栈清单模板
+- 增加分步实现的每步验证要求
+
+### 长期（跨项目验证后）
+
+- 提取通用技术栈清单模板（Java/Go/Python 等）
+- 建立参考实现库（常见模式的最佳实践）
+- 自动化部分调研步骤（Grep 脚本、清单生成）
+
+---
+
+## 实施检查清单
+
+### 立即验证
+
+- [ ] `phase-contracts.md` 文件已更新
+- [ ] grill 阶段增加了技术实现维度
+- [ ] apply 阶段增加了 Pre-apply Checkpoint
+- [ ] apply 退出条件增加了 2 条新检查
+- [ ] 文件语法无误，可以正常解析
+
+### 下次执行验证
+
+- [ ] agent 是否正确识别触发条件
+- [ ] agent 是否执行了完整的 3 步调研
+- [ ] 技术栈清单是否写入 decisions.md
+- [ ] 是否有效减少了返工次数
+- [ ] 核心功能是否避免了空实现
+
+---
+
+## 附录：复盘案例链接
+
+- 原始复盘文档: `skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
+- 修改前版本: phase-contracts.md (commit: 待补充)
+- 修改后版本: phase-contracts.md (commit: 待补充)

skill-workbench/docs/sm-flow/phase-contracts-v4.2-changelog.md

@@ -0,0 +1,307 @@
+# SM Flow Phase Contracts v4.2 更新日志
+
+> 更新日期: 2026-06-24  
+> 更新原因: 基于"lookup-knowledge-integration"执行复盘  
+> 更新方案: 增强执行机制，引入可验证 checkpoint
+
+---
+
+## 更新概览
+
+**核心目标**: 解决"约束是软性的"问题，增加可执行的检查机制
+
+**更新范围**:
+- ✅ commit 阶段：增加文件完整性和一致性检查清单
+- ✅ apply 阶段：增加前置门控（.committed 文件检查）
+- ✅ archive 阶段：增加强制执行顺序（5 步 checklist）
+
+**文本增量**: +80 行
+
+---
+
+## 核心问题诊断
+
+### 问题根源：约束是"软性"的，缺少执行机制
+
+| 问题 | 现象 | 影响 | 根本原因 |
+|------|------|------|----------|
+| **Commit 检查缺标准** | 不知道如何判断"通过 commit 检查" | agent 跳过 commit 直接进入 apply | 只说"检查是否可执行"，没说具体检查什么 |
+| **Apply 缺前置门控** | 用户说"修复"就直接开始实现 | 可能基于不完整的 OpenSpec | 进入条件是软性描述，没有文件检查 |
+| **Archive 无 Checklist** | 先创建 handoff，忘记 devflow | 归档流程不完整 | 没有强制执行顺序 |
+
+---
+
+## 详细修改
+
+### 1. Commit 阶段 — 增加可验证 Checkpoint
+
+**修改位置**: `phase-contracts.md` 第 208-221 行
+
+**新增内容**:
+
+#### 文件完整性检查（必须全部通过）
+
+- [ ] `proposal.md` 存在，包含问题描述（至少 50 字）、建议方案（至少 100 字）、范围/非目标
+- [ ] `design.md` 存在，包含架构设计（文字或图）、数据结构定义（至少 1 个）、关键决策记录（至少 2 条）
+- [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
+- [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准
+
+#### 一致性检查（必须通过）
+
+- [ ] proposal 中的核心概念在 design 中有对应设计
+- [ ] design 中的关键决策在 tasks 中有对应实现任务
+- [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
+
+#### 标记文件
+
+检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
+
+**目的**: 
+- 提供明确的"可执行状态"判断标准
+- 强制 agent 完成所有检查项
+- 通过 `.committed` 文件提供下游门控依据
+
+---
+
+### 2. Apply 阶段 — 增加前置门控检查
+
+**修改位置**: `phase-contracts.md` 第 233-244 行
+
+**新增内容**:
+
+#### 前置门控检查（硬约束）
+
+1. 检查 `openspec/changes/{slug}/.committed` 文件是否存在
+2. 如不存在，执行以下流程：
+   - 汇报：Draft OpenSpec 未通过 commit 检查
+   - 列出缺失的 checkpoint 项（文件完整性、一致性检查）
+   - 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
+
+**目的**:
+- 强制 apply 依赖 Committed OpenSpec
+- 阻止基于不完整 OpenSpec 的实现
+- 提供补救路径（补做 commit 或显式跳过）
+
+---
+
+### 3. Archive 阶段 — 增加强制执行顺序
+
+**修改位置**: `archive-rules.md` 第 5-41 行
+
+**新增章节**: Archive 强制执行顺序
+
+#### Step 1: 创建 devflow 档案（必需）
+
+- [ ] 创建 `brief.md`（从 proposal.md 提取）
+- [ ] 创建 `evidence.md`（从 decisions.md 提取）
+- [ ] 创建 `decisions.md`（整理为最终版）
+- [ ] 创建 `acceptance.md`（记录验证情况）
+
+#### Step 2: 更新索引（必需）
+
+- [ ] 在 `devflow/index.md` 末尾追加或更新一行
+
+#### Step 3: 标记 OpenSpec（必需）
+
+- [ ] 创建 `openspec/changes/{slug}/.archive-ready` 文件
+
+#### Step 4: 向用户汇报（必需）
+
+- [ ] 列出创建的 devflow 档案文件路径（验证文件实际存在）
+- [ ] 汇报验证情况（按类型分类）
+- [ ] 列出剩余风险
+- [ ] 询问：**是否现在归档 OpenSpec？**
+
+#### Step 5: 用户确认后执行 OpenSpec Archive（可选）
+
+- [ ] 调用 `openspec-archive-change`
+- [ ] 记录 archive 结果
+
+**自检**: 在执行 Step 4 前，检查 Step 1-3 是否都完成。
+
+**目的**:
+- 强制 devflow 档案优先（不再先创建 handoff）
+- 提供明确的执行顺序，避免遗漏
+- 通过 `.archive-ready` 文件标记完成状态
+
+---
+
+## 新增门控文件
+
+| 文件 | 创建时机 | 用途 |
+|------|----------|------|
+| `.committed` | commit 阶段退出时 | apply 阶段前置门控 |
+| `.archive-ready` | archive Step 3 | 标记归档准备就绪 |
+
+---
+
+## 预期效果
+
+### 量化指标
+
+| 指标 | v4.1 | v4.2 目标 | 改善 |
+|------|------|-----------|------|
+| Commit 阶段跳过率 | 高（无明确标准） | 0%（有 checklist） | -100% |
+| Apply 基于不完整 OpenSpec | 可能发生 | 0%（门控阻止） | -100% |
+| Archive 遗漏 devflow | 可能发生 | 0%（强制顺序） | -100% |
+
+### 质量提升
+
+**Commit 阶段**:
+- ✅ 明确什么叫"可执行状态"
+- ✅ agent 无法跳过检查清单
+- ✅ 提供 `.committed` 文件作为凭证
+
+**Apply 阶段**:
+- ✅ 强制检查 `.committed` 文件存在
+- ✅ 阻止基于不完整 OpenSpec 的实现
+- ✅ 提供补救路径
+
+**Archive 阶段**:
+- ✅ 强制 devflow 优先（不再先创建 handoff）
+- ✅ 5 步 checklist 避免遗漏
+- ✅ 自检机制确保完整性
+
+---
+
+## 与 v4.1 的关系
+
+| 版本 | 核心改进 | 解决问题 |
+|------|----------|----------|
+| v4.1 | Pre-apply Research Checkpoint | apply 阶段前置调研不足，导致返工 |
+| v4.2 | 可验证 Checkpoint + 门控文件 | 约束是软性的，agent 容易跳过阶段 |
+
+**互补关系**:
+- v4.1 解决"调研不充分导致返工"
+- v4.2 解决"缺少执行机制导致跳过阶段"
+
+---
+
+## 设计原则
+
+### 1. 可验证性
+
+**Before**: "检查 OpenSpec 是否可执行"（模糊）  
+**After**: "proposal ≥50字、design ≥1个数据结构、specs ≥3个 requirement"（具体）
+
+### 2. 门控文件
+
+**Before**: 软性描述"已通过 commit"  
+**After**: 硬性检查 `.committed` 文件存在
+
+### 3. 强制顺序
+
+**Before**: 建议性"应该先 devflow 后 handoff"  
+**After**: 5 步 checklist，不得跳过或重排
+
+---
+
+## 复杂度评估
+
+**本次修改复杂度**: 低-中等
+- 文本增量: +80 行（phase-contracts.md +40 行，archive-rules.md +40 行）
+- 概念增加: 2 个门控文件（.committed, .archive-ready）
+- 规则增强: 3 个阶段的检查清单
+
+**整体复杂度**: 高（但更可靠）
+- 总行数: ~700 行 → ~780 行（+11%）
+- 门控数: 6 个 → 8 个（+commit 文件完整性 + apply 前置门控）
+- 强制清单: +3 个（commit 文件完整性、commit 一致性、archive 5 步）
+
+**权衡**:
+- ✅ 收益: 彻底解决"跳过阶段"问题
+- ⚠️ 成本: 增加 80 行文本，agent 需检查更多项
+
+---
+
+## 适用场景
+
+### ✅ 所有场景（无例外）
+
+v4.2 的改进是**执行机制**层面的，不涉及业务逻辑：
+- 无论 micro/standard/complex，都需要 commit 检查
+- 无论需求大小，都需要 apply 前置门控
+- 无论项目规模，都需要 archive 强制顺序
+
+### 快速模式
+
+快速模式可以简化产物（如 tasks 只需 3 个子任务），但**不能跳过门控**：
+- ✅ 仍需 commit 检查（即使 tasks 数量少）
+- ✅ 仍需 apply 前置门控
+- ✅ 仍需 archive 强制顺序
+
+---
+
+## 实施验证
+
+### 验证计划
+
+下次完整执行 sm-flow 时，检查：
+
+1. **Commit 阶段**:
+   - [ ] agent 是否执行了文件完整性检查？
+   - [ ] agent 是否执行了一致性检查？
+   - [ ] agent 是否创建了 `.committed` 文件？
+
+2. **Apply 阶段**:
+   - [ ] agent 是否检查了 `.committed` 文件存在？
+   - [ ] 如不存在，agent 是否汇报并询问用户？
+
+3. **Archive 阶段**:
+   - [ ] agent 是否按 5 步顺序执行？
+   - [ ] agent 是否在 Step 4 前自检了 Step 1-3？
+   - [ ] agent 是否创建了 `.archive-ready` 文件？
+
+### 成功标准
+
+- ✅ 无未经检查的 commit → apply 跳转
+- ✅ 无基于不完整 OpenSpec 的实现
+- ✅ 无先创建 handoff 后补 devflow 的情况
+
+---
+
+## 后续演进方向
+
+### v5.0 候选特性（观察 3+ 次执行后决定）
+
+如果 v4.2 执行良好，但仍有问题，考虑：
+
+1. **流程状态文件** `.sm-flow-state`
+   - 记录当前阶段、已完成阶段、时间戳
+   - 支持断点续做
+
+2. **更多门控文件**
+   - `.context-done`（context 阶段完成）
+   - `.grill-done`（grill 阶段完成）
+   - `.apply-done`（apply 阶段完成）
+
+3. **违规自检机制**
+   - 每个阶段退出前，自动检查是否违反 6 条硬约束
+
+4. **进度可视化**
+   - 每次开始时，汇报进度条（9 个阶段的完成情况）
+
+**判断依据**: 如果 v4.2 后仍频繁出现跳过阶段，再引入更重的机制。
+
+---
+
+## 相关文档
+
+- 执行复盘: `skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`
+- 修改文件: 
+  - `.agents/skills/sm-flow/references/phase-contracts.md`
+  - `.agents/skills/sm-flow/references/archive-rules.md`
+
+---
+
+## 总结
+
+**v4.2 的核心理念**: 把"软性约束"变成"硬性检查"
+
+| 改进点 | Before | After |
+|--------|--------|-------|
+| Commit 标准 | "可执行状态"（模糊） | 文件完整性 + 一致性检查清单 |
+| Apply 门控 | "已通过 commit"（软性） | 检查 `.committed` 文件存在（硬性） |
+| Archive 顺序 | "应该先 devflow"（建议） | 5 步强制顺序 + 自检 |
+
+**预期效果**: 彻底解决"agent 跳过阶段"问题，提升流程可靠性。

skill-workbench/docs/sm-flow/retrospective.md

@@ -0,0 +1,208 @@
+# SM Flow 首次执行回顾
+
+**日期**：2026-05-21
+**变更**：[ops-message-support](projects/2026-05-21-ops-message-support/) — 站内消息新增 OMC 支持
+**目的**：以本次交互为例，逐阶段复盘实际执行与 SM Flow 预期的差距，作为后续执行的改进依据。
+
+---
+
+## Phase 0 — 入口澄清
+
+### 应该做的
+- 收集问题、期望结果、目标用户、涉及代码区域、约束条件
+- 输出入口摘要、slug、规模分档
+
+### 实际做的
+- 用户输入需求后，直接开始读代码和查数据库
+- 输出了 slug（`ops-message-support`）和分档（micro）
+
+### 没做到的
+- 没有输出入口摘要（清晰的 1-2 句话问题 + 1-2 句话期望结果）
+- 没有列已知影响代码或模块清单
+
+### 改进建议
+- Phase 0 结束时花 1 分钟写 3-5 行入口摘要到 `brief.md`，而不是等用户问再补
+
+---
+
+## Phase 0.5 — Devflow 上下文收集
+
+### 应该做的
+- 初始化 devflow 目录结构
+- 读取 glossary、ADR、历史项目
+- 形成上下文摘要写入 brief.md
+
+### 实际做的
+- 等用户质疑 devflow 无产物时才在 Phase 2.9 补创建
+
+### 没做到的
+- ❌ **没有在 Phase 0.5 创建 devflow 项目目录和任何文件**
+- 没检查 glossary（当时为空也正常，但应该初始化和告知）
+
+### 改进建议
+- 进入 Phase 0.5 就执行 `mkdir devflow/projects/{slug}/` 并创建 `brief.md` 骨架
+- Devflow 是"思考记录"不是"文档任务"，哪怕只写 3 行也比事后补强
+
+---
+
+## Phase 1 — OpenSpec propose
+
+### 应该做的
+- 声明"本阶段调用 openspec-propose skill"
+- 如果不可用，降级为 fallback 并说明原因
+- 产出 proposal / design / specs / tasks
+
+### 实际做的
+- 调用了 `openspec new change` 创建了 change 目录
+- openspec CLI 模板不匹配时报错，**没有声明降级**，直接手动创建文件
+- 手动创建了 research、proposal、design、specs、tasks
+
+### 没做到的
+- ❌ **没有声明"openspec CLI 模板不匹配，降级为 manual fallback"**
+- ❌ **没有区分 Draft OpenSpec 和 Committed OpenSpec**（两者在流程中意义不同）
+- 产出顺序按了 research-first schema，但未验证 artifacts 间的依赖一致性
+
+### 改进建议
+- Skill 不可用时必须说清楚：什么 skill + 什么原因不可用 + 降级方式
+- Draft OpenSpec 阶段标记为 draft，和 Committed OpenSpec 区分
+
+---
+
+## Phase 1.5 — PRD / OpenSpec 对齐
+
+### 应该做的
+- 检查 proposal 是否覆盖 research 范围
+- 检查 design 是否满足 proposal 承诺的能力
+- 检查接口影响等级（L1-L4）
+
+### 实际做的
+- **直接跳过**，没有做任何 formal 的对齐检查
+
+### 没做到的
+- ❌ 对齐检查完全缺失
+- 后果：proposal.md 漏了 type 字段，design.md 和 research.md 都已包含但 proposal 没更新，直到用户 review 才发现
+
+### 改进建议
+- 即使 micro 模式，至少做一次快速交叉检查：research 范围 ↔ proposal 变更 ↔ design 决策 ↔ specs 场景
+
+---
+
+## Phase 2 — Human-in-the-loop 澄清
+
+### 应该做的
+- 声明"本阶段调用 grill-with-docs skill"，按结构化方式追问
+- 至少覆盖术语、边界、验收三个维度
+- evidence-driven 的先查证再汇报
+- user-interview 的**一次只问一个问题**，等用户确认后再问下一个
+- 用户确认后回写 OpenSpec
+- 对模糊的术语（如"运管"）通过 grill 确认其准确定义
+
+### 实际做的
+- **没有调用 grill-with-docs** ❌
+- **一次问了 3 个 user-interview 问题**，违反规则 ❌
+- 收集了充分的 evidence（代码和数据库分析到位）✓
+- 用户确认后及时回写了 OpenSpec ✓
+
+### 没做到的
+- ❌ 没有使用 grill 或任何结构化追问工具，自己随意问了几个问题
+- ❌ 一次多问被用户 reject
+- 问题数量太少：只用了 3 个问题（编码、子分类、字段范围），远不足以覆盖所有盲区
+- 以下该问但没有问的问题：
+  - OMC 消息从哪里发送？通过什么 identifier/messageCode 触发投递？
+  - OMC 用户侧的权限体系是怎样的？和 APP 用户在同一张权限表吗？
+  - OMC 前端需要怎样的响应结构？只要总数还是要子分类列表？
+  - 现有 APP 端有 hasUnread/readAll 等功能，OMC 端是否也需要？
+  - OMC 消息的创建时间和保留策略？
+- "运管"这个概念从一开始就模棱两可，没有通过 grilling 追根究底，到用户主动纠正为 OMC 时才明确
+
+### 改进建议
+- 必须调用 grill-with-docs，不调用就是跳过
+- 问题数量下限：至少 5-8 个尝试性提问，覆盖：术语定义、发送来源、权限模型、前端需求、功能对标
+- 一次一问，等回复后再继续
+- 在 Phase 2 开始时创建 Task 跟踪 grill 进度："Q1[术语]...→Q2[边界]...→Q3[验收]..."，每问一个更新一次
+
+---
+
+## Phase 2.5 — 架构审计
+
+### 应该做的
+- 画出输入 → 处理 → 输出的模块链路
+- 识别跨模块依赖、数据所有权、生命周期和耦合风险
+- 用不超过五句话写出架构风险评估
+- 影响实现的结论回写 OpenSpec design/tasks
+
+### 实际做的
+- **直接跳过**
+- 做了代码分析但未输出正式的架构审计记录
+
+### 没做到的
+- ❌ 模块链路图缺失
+- ❌ 接口影响分析表是用户追问后才补的
+- ❌ listMessageCategory 泄漏 OMC 的问题在架构审计中本应发现，但跳过后留到了用户 review 才发现
+
+### 改进建议
+- Phase 2.5 至少画一张文本链路图：`User → Controller → Service → Mapper → DB`
+- 然后问自己：新增的 type 字段会影响哪些链路节点？
+
+---
+
+## Phase 2.9 — Commit OpenSpec
+
+### 应该做的
+- 检查所有 artifacts 的一致性
+- 检查所有 user-interview 都已确认
+- 检查接口影响已记录
+- 向用户汇报并请求 Phase 3 授权
+
+### 实际做的
+- 做了检查，但不够彻底（proposal 漏了 type）
+- 接口影响分析是补的
+- 汇报了，但用户先发现了 type 字段问题
+
+### 没做到的
+- 没能在用户发现问题前自己找出 proposal 遗漏
+- 自检清单没有对照执行
+
+### 改进建议
+- Phase 2.9 不能光靠头脑检查，要逐行对比 research ↔ proposal ↔ design ↔ specs ↔ tasks 的关键断言
+
+---
+
+## Phase 3 — OpenSpec apply
+
+尚未开始
+
+---
+
+## Phase 4 — 回填 Devflow
+
+### 应该做的
+- 验收记录
+- 更新 devflow/index.md
+- 询问是否归档 OpenSpec change
+
+### 实际做的
+- devflow 产物在用户要求下补创建
+- index.md 在用户质疑后创建
+
+### 改进建议
+- Phase 4 的 devflow 产物应该是最轻松的，因为内容已经在各阶段产出过，只需要汇总
+
+---
+
+## 根因总结
+
+### 约束是否到位？
+
+SM Flow 的 rules 在 SKILL.md 和 reference 中写得很清楚。问题**不是约束不到位**，而是：
+
+1. **高估了小改动的判断** — micro 分档让我误以为"可以跳过检查"，实际 micro 只合并产物不跳过阶段
+2. **按代码习惯而非按流程执行** — 作为习惯于输出代码的 agent，对流程节点的重视度天然低于代码
+3. **缺少执行中的自检机制** — rules 只在加载时读一次，被上下文冲走后就没有对照检查
+
+### 核心教训
+
+- **Devflow 是思考过程，不是文档任务** — 写文档的过程就是做架构审计和一致性检查的过程
+- **Micro 不等于跳过** — 产物可以合并，但检查点不能省略
+- **声明即约束** — 把"本阶段调用 X / 降级为 Y"说出来，是对自己的提醒也是对用户的透明
+- **Devflow 和 OpenSpec 同步更新** — 更新 OpenSpec 时同步更新 devflow，不要把 devflow 留到 Phase 4 一次性补。两者是同一件事的两面，不是先后关系

skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md

@@ -0,0 +1,293 @@
+# SM Flow 执行复盘 - 山东商客意向单同步接口
+
+> 项目: yingke-platform  
+> 需求: 385 山东公司商机信息同步接口  
+> 执行日期: 2026-06-23  
+> 复盘人: Claude Code
+
+---
+
+## 执行概况
+
+- **需求规模**: 中等（3个接口 + Kafka消费 + 数据库变更）
+- **总耗时**: 约 2 小时（含多次返工）
+- **返工次数**: 4-5 次重大返工
+- **最终状态**: 核心代码完成，但验签/解密/查询接口未实现
+
+---
+
+## 发现的问题
+
+### 1. 前置调研不足，导致多次返工
+
+#### 问题表现
+
+| 返工点 | 初次实现（错误） | 返工后（正确） | 浪费时间 |
+|--------|------------------|----------------|----------|
+| RequestMsg 结构 | 自创 `SyncIntentOrderReq/Resp` | 使用项目标准 `RequestMsg<T>` | 15 分钟 |
+| Kafka 发送方式 | `SendMessageTunnel` + `TaskTypeEnum` | `ykMqTemplate` + `@YkMsg` | 20 分钟 |
+| Consumer 模块位置 | order-service 模块 | web 模块（参考案例位置） | 10 分钟 |
+| 透传字段结构 | Map → DTO → 最终平铺 | 应一次到位平铺到 Msg | 15 分钟 |
+
+**根本原因**: apply 阶段直接开始写代码，没有充分调研现有代码模式。
+
+#### 改进建议
+
+**在 apply 阶段前增加强制调研步骤**（pre-apply research checkpoint）：
+
+1. **阅读所有参考实现**（设计文档中明确提到的）
+   - 完整阅读参考代码，而不是凭想象
+   - 提取关键模式：请求结构、Kafka 使用、模块划分
+   
+2. **Grep 关键技术栈**
+   ```bash
+   grep -r "@YkMsg" --include="*.java"
+   grep -r "ykMqTemplate" --include="*.java"
+   grep -r "RequestMsg<" --include="*.java"
+   ```
+   
+3. **形成"技术栈清单"文档**（临时产物）
+   ```markdown
+   - 项目使用 RequestMsg<T> 作为统一请求包装
+   - Kafka 消息使用 @YkMsg + MsgData + ykMqTemplate.sendAsync()
+   - Consumer 统一放在 web 模块的 manager/stream/consumer
+   ```
+
+4. **调研时间要求**: 不少于 15 分钟，复杂需求可延长至 30 分钟
+
+---
+
+### 2. 设计文档与实现偏离，缺少一致性检查
+
+#### 问题表现
+
+| 设计文档要求 | 实际实现 | 偏离程度 |
+|--------------|----------|----------|
+| Controller 层 SM3 验签 | 只有 TODO 注释 | ❌ 核心功能缺失 |
+| Service 层 AES256-GCM 解密 | 只有 TODO 注释 | ❌ 核心功能缺失 |
+| queryIntentOrder 调用一体化客服 | 空实现 | ❌ 核心功能缺失 |
+| syncIntentOrder 同步调用 | 改为 Kafka 异步 | ⚠️ 架构差异（可能合理） |
+
+**根本原因**: apply 阶段没有"设计-实现对齐检查点"。
+
+#### 改进建议
+
+**在 apply 阶段中增加对齐检查点**（alignment checkpoint）：
+
+1. **每完成 1 个接口/模块，立即对比设计文档**
+   - 逐条核对设计文档的任务清单
+   - 标记"已完成/部分完成/TODO"
+   
+2. **核心功能不允许"TODO 占位"直接通过**
+   - 加密/解密、验签、核心业务逻辑必须实现或明确标注"待联调"
+   - 区分"框架完整但待联调"（✅） vs "空实现"（❌）
+
+3. **架构差异必须显式记录并询问用户**
+   - 设计说同步，实现改异步 → 必须记录原因并确认
+   - 创建 `decisions.md` 记录所有偏离设计的架构决策
+
+---
+
+### 3. 分步验证不足，一次写太多代码
+
+#### 问题表现
+
+- 一次性写完 Controller + Service + Kafka + Consumer，然后发现 RequestMsg 结构错了
+- 没有"写一点 → 编译 → 确认方向"的小步迭代
+
+#### 改进建议
+
+**强制分步验证**（incremental validation）：
+
+1. **Controller 层先行**
+   - 只写 Controller + 最小 Service 骨架
+   - 确认请求/响应结构正确
+   - 编译通过后再继续
+
+2. **Kafka 发送独立验证**
+   - 写完发送逻辑，先打印 JSON 确认消息格式
+   - 再写 Consumer
+
+3. **Consumer 最后实现**
+   - 基于已确认的消息格式实现
+
+---
+
+### 4. 参考案例利用不充分
+
+#### 问题表现
+
+- 设计文档明确提到"参考 AddIntentOrderOutSystemDealTunnel"
+- 但实际执行时，直到用户提醒才去看参考实现
+- 之前都在凭想象写，导致返工
+
+#### 改进建议
+
+**强制参考案例优先**（reference-first approach）：
+
+1. **grill 阶段就应该找出所有参考案例**
+   - 不要只记录"参考 XXX"，而是实际阅读并提取模式
+   
+2. **apply 前必须完整阅读参考实现**
+   - 不是"扫一眼"，而是逐行理解关键逻辑
+   - 提取可复用的代码片段
+
+3. **参考案例模式提取清单**（临时文档）
+   ```markdown
+   ## AddIntentOrderOutSystemDealTunnel 关键模式
+   
+   1. Consumer 方法签名: `public void onXXX(XXXMsg msgBO)`
+   2. 调用链: msg → AES加密 → OnlineOpportunityApi → 回填状态
+   3. 异常处理: try-catch → updateStatus(EXCEPTION) → throw
+   4. 成功判断: isSyncSuccess() 三层校验
+   ```
+
+---
+
+### 5. grill 阶段澄清不够深入
+
+#### 问题表现
+
+- grill 阶段问了业务问题（省份校验、透传字段），但没有问技术实现问题
+- 导致后续实现时才发现技术栈不熟悉
+
+#### 改进建议
+
+**grill 阶段增加技术实现澄清**：
+
+除了业务澄清，还应该包括：
+
+1. **技术栈确认问题**
+   - "项目现有的 Kafka 消息怎么定义和发送？"
+   - "RequestMsg/ResponseMsg 的标准用法是什么？"
+   - "类似接口的 Controller/Service 是怎么写的？"
+
+2. **参考实现确认**
+   - "设计文档提到的参考实现是哪些文件？"
+   - "这些参考实现的核心模式是什么？"
+
+3. **技术风险识别**
+   - "有哪些技术点我不熟悉，需要先调研？"
+
+---
+
+## 改造建议汇总
+
+### 方案 A: 在现有 9 阶段中增强（保守）
+
+```
+clarify → context → propose → grill+ → specify → audit → commit → pre-apply+ → apply+ → archive
+                                  ↑                                      ↑        ↑
+                           增加技术澄清                             增加调研  增加检查点
+```
+
+**修改点**：
+
+1. **grill 阶段**：增加技术实现澄清问题模板
+2. **apply 阶段前**：增加 pre-apply research checkpoint（15-30分钟）
+3. **apply 阶段中**：增加 alignment checkpoint（每完成1个模块对比设计文档）
+
+### 方案 B: 新增独立调研阶段（激进）
+
+```
+clarify → context → propose → grill → research → specify → audit → commit → apply → archive
+                                                    ↑
+                                          新增独立调研阶段
+```
+
+**新阶段 research**：
+
+- **输入**: proposal + 参考实现列表
+- **输出**: 技术栈清单 + 参考模式提取 + 风险评估
+- **时间**: 15-30 分钟
+- **产物**: `research.md`（临时文档，archive 时删除）
+
+**research.md 结构**：
+
+```markdown
+# 技术调研 - [需求名称]
+
+## 参考实现分析
+
+### AddIntentOrderOutSystemDealTunnel
+- 文件位置: web/manager/stream/consumer/...
+- 关键模式:
+  - Consumer 定义: @YkMqConsumer + MsgData 子类
+  - 调用链: ...
+
+## 技术栈清单
+
+- 请求结构: RequestMsg<T> / ResponseMsg<T>
+- Kafka: @YkMsg + ykMqTemplate.sendAsync()
+- 加密: AESUtil.encryptAES() (AES-128 ECB)
+
+## 风险点
+
+- AES256-GCM 工具类不存在，需要新建
+- 验签逻辑没有现成拦截器，需要在 Service 层实现
+```
+
+### 推荐方案
+
+**方案 A**（渐进增强）：
+
+1. 对现有流程影响小
+2. 实施成本低
+3. 可以立即生效
+
+**具体实施**：
+
+- 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范
+- 增加 checkpoint 描述
+- 更新 question pool 增加技术澄清问题
+
+---
+
+## 其他建议
+
+### 1. 增加"快速失败"机制
+
+当发现以下情况，立即暂停并询问用户：
+
+- 需要创建的类/接口在参考实现中有类似的（防止重复造轮）
+- 实现方式与设计文档明显偏离
+- 连续返工超过 2 次（说明方向可能错了）
+
+### 2. 产物可观测性增强
+
+在 apply 阶段，定期输出：
+
+```markdown
+## 实现进度（每 30 分钟更新）
+
+✅ Controller 层（已完成）
+  - ShandongSyncController.syncIntentOrder
+  - 请求结构使用 RequestMsg<ShandongIntentOrderData>
+  
+🚧 Service 层（进行中）
+  - ShandongSyncService 接口完成
+  - 实现类 70% 完成
+  - ⚠️ 验签解密未实现（TODO）
+  
+⏳ Kafka 层（待开始）
+```
+
+### 3. 设计文档质量要求
+
+设计文档应该包含：
+
+- ✅ 参考实现的具体文件路径（而不是只说"参考 XXX"）
+- ✅ 关键技术栈的使用示例（而不是只说"使用 Kafka"）
+- ✅ 数据流图（清晰展示同步/异步边界）
+
+---
+
+## 总结
+
+**核心问题**: apply 阶段"想当然"开始写代码，缺少充分调研和分步验证。
+
+**解决方向**: 在 apply 前增加强制调研步骤，在 apply 中增加对齐检查点。
+
+**预期效果**: 返工次数从 4-5 次降低到 0-1 次，实现质量与设计文档一致性提升。
+
+**立即可做**: 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范即可生效。

skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md

@@ -0,0 +1,504 @@
+# SM Flow Skill - 使用情况分析与优化建议
+
+## 执行概况
+
+**项目**: lookup-knowledge-integration  
+**执行日期**: 2026-06-24  
+**执行模式**: 手动跳阶段（用户直接要求"修复问题"）
+
+### 实际执行的阶段
+
+1. ❌ **Clarify** - 跳过（用户直接给了 handoff 文档）
+2. ❌ **Context** - 跳过（未读取 devflow 历史）
+3. ❌ **Propose** - 跳过（OpenSpec 已存在）
+4. ❌ **Grill** - 跳过（未进行澄清）
+5. ❌ **Specify** - 跳过（OpenSpec 已完整）
+6. ❌ **Audit** - 跳过（未进行架构审计）
+7. ❌ **Commit** - **跳过（关键遗漏）**
+8. ✅ **Apply** - 执行（实现代码）
+9. ⚠️ **Archive** - 部分执行（先创建 handoff，后补 devflow）
+
+---
+
+## 做得好的地方 ✅
+
+### 1. Archive 规则详细且可执行
+
+**优点**：
+- `archive-rules.md` 提供了清晰的提取映射表
+- 目录结构规范（devflow/projects/YYYY-MM-DD-{slug}/）
+- 产物分档（micro/standard/complex）明确
+- 索引维护规则具体
+
+**证据**：被提醒后，我能快速创建符合规范的 devflow 档案
+
+### 2. 硬约束明确
+
+**优点**：
+- 6 条核心规则写在 SKILL.md 顶部，醒目
+- 规则表述清晰（不得跳过 context/grill/commit）
+
+**问题**：虽然规则清晰，但缺少执行机制（见后续建议）
+
+### 3. Phase 契约结构清晰
+
+**优点**：
+- `phase-contracts.md` 定义了进入/退出条件
+- 每个阶段的职责明确
+
+---
+
+## 关键问题 ❌
+
+### 问题 1: Commit 检查缺少可执行标准
+
+**现象**：
+- 我不知道如何判断"通过 commit 检查"
+- phase-contracts.md 说了要做 commit，但没说具体怎么判断
+
+**影响**：
+- 我直接跳过 commit，进入 apply
+- 违反了硬约束规则 4："不得跳过 commit"
+
+**根本原因**：
+```
+phase-contracts.md:
+  "Commit 阶段：检查 Draft OpenSpec 是否达到可执行状态"
+  
+但没有说：
+  - 什么叫"可执行状态"？
+  - 需要检查哪些文件？
+  - 每个文件的必需内容是什么？
+  - 如何标记"已通过"？
+```
+
+### 问题 2: Apply 阶段缺少前置门控
+
+**现象**：
+- 用户说"修复问题"，我直接开始实现
+- 没有检查是否存在 Committed OpenSpec
+
+**影响**：
+- 可能基于不完整的 OpenSpec 执行
+- 违反了 "apply 必须基于 Committed OpenSpec" 的约束
+
+**根本原因**：
+- Apply 阶段的"进入条件"是软性描述
+- 没有强制的文件检查机制（如 `.committed` 文件）
+
+### 问题 3: Archive 阶段缺少 Checklist
+
+**现象**：
+- 我先创建了 handoff 文档
+- 忘记了 devflow 才是核心记忆层
+- 被提醒后才补创建 devflow 档案
+
+**影响**：
+- 归档流程不完整
+- 需要用户纠正
+
+**根本原因**：
+- archive-rules.md 有详细说明，但没有强制执行顺序
+- 我容易按"直觉"操作，而不是按"规范"操作
+
+### 问题 4: 缺少流程状态追踪
+
+**现象**：
+- 我不知道当前在哪个阶段
+- 每次执行都像"全新开始"
+
+**影响**：
+- 容易跳过中间阶段
+- 无法断点续做
+
+---
+
+## 优化建议（按优先级）
+
+### High Priority（立即修复）
+
+#### 建议 1: Commit 检查增加可执行 Checkpoint
+
+**位置**：`references/phase-contracts.md` - Commit 阶段
+
+**增加内容**：
+```markdown
+## Commit 阶段退出条件
+
+必须完成以下 checkpoint：
+
+### 文件完整性检查
+- [ ] `proposal.md` 存在且包含：
+  - 问题描述（至少 50 字）
+  - 建议方案（至少 100 字）
+  - 范围/非范围
+
+- [ ] `design.md` 存在且包含：
+  - 架构设计（文字或图）
+  - 数据结构定义（至少 1 个）
+  - 关键决策记录（至少 2 条）
+
+- [ ] `specs/functional-specs.md` 存在且包含：
+  - 至少 3 个 requirement
+  - 每个 requirement 有 scenario
+
+- [ ] `tasks.md` 存在且包含：
+  - 至少 5 个可执行子任务
+  - 每个任务有验收标准
+
+### 一致性检查
+- [ ] proposal 中的核心概念在 design 中有对应设计
+- [ ] design 中的关键决策在 tasks 中有对应实现任务
+- [ ] tasks 的验收标准可验证（不是"正确实现"这种模糊描述）
+
+### 标记
+通过后创建 `.committed` 文件：
+```bash
+echo "committed at $(date)" > openspec/changes/{slug}/.committed
+```
+
+**执行指令**：
+在 apply 阶段入口，必须先执行此检查。
+```
+
+#### 建议 2: Apply 阶段增加前置门控
+
+**位置**：`references/phase-contracts.md` - Apply 阶段
+
+**修改"进入条件"**：
+```markdown
+## Apply 阶段进入条件
+
+**硬约束**：
+1. 必须存在 `.committed` 文件
+2. 如果不存在，执行以下流程：
+   a. 汇报：Draft OpenSpec 未通过 commit 检查
+   b. 列出缺失的 checkpoint
+   c. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
+
+**检查代码**：
+```bash
+if [ ! -f "openspec/changes/{slug}/.committed" ]; then
+    echo "错误：Draft OpenSpec 未通过 commit 检查"
+    echo "请先完成 commit 阶段，或显式确认跳过"
+    exit 1
+fi
+```
+```
+
+#### 建议 3: Archive 阶段增加强制 Checklist
+
+**位置**：`references/archive-rules.md` 顶部
+
+**增加内容**：
+```markdown
+## Archive 阶段强制执行顺序
+
+**按以下顺序执行，不得跳过或重排**：
+
+### Step 1: 创建 devflow 档案（必需）
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
+      （从 proposal.md 提取：背景、目标、范围、非目标）
+      
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
+      （从 decisions.md 整理：关键决策、权衡、风险）
+      
+- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
+      （记录：静态验证、脚本验证、人工验证、未验证）
+
+### Step 2: 更新索引（必需）
+- [ ] 在 `devflow/index.md` 末尾追加一行：
+      `| YYYY-MM-DD | slug | 领域 | 关键词 | OpenSpec路径 | archived |`
+
+### Step 3: 标记 OpenSpec（必需）
+- [ ] 创建 `openspec/changes/{slug}/.completed` 文件
+
+### Step 4: 创建 Handoff（可选）
+- [ ] 创建 `handoff/YYYY-MM-DD-{slug}.md`
+      （运维交接文档，给未来开发者）
+
+### Step 5: 向用户汇报
+- [ ] 列出创建的 devflow 档案
+- [ ] 汇报验证情况（按类型分类）
+- [ ] 列出剩余风险
+- [ ] 询问：**是否现在归档 OpenSpec？**
+
+**自检**：在执行 Step 5 前，检查 Step 1-4 是否都完成。
+```
+
+---
+
+### Medium Priority（下个版本）
+
+#### 建议 4: 增加流程状态文件
+
+**目标**：让我知道当前在哪个阶段
+
+**实现**：在 OpenSpec 目录维护 `.sm-flow-state` 文件
+
+```json
+{
+  "change": "lookup-knowledge-integration",
+  "currentPhase": "apply",
+  "completed": ["clarify", "context", "propose", "grill", "specify", "audit", "commit"],
+  "nextPhase": "archive",
+  "committed": true,
+  "timestamps": {
+    "commit": "2026-06-24T10:00:00Z",
+    "apply_start": "2026-06-24T10:05:00Z"
+  }
+}
+```
+
+**使用方式**：
+- 每个阶段开始时：读取此文件，确认前置阶段已完成
+- 每个阶段结束时：更新此文件，标记当前阶段完成
+- 用户下次调用时：直接从 `nextPhase` 继续
+
+**集成到 SKILL.md**：
+```markdown
+## 执行前检查
+
+1. 读取 `.sm-flow-state` 文件
+2. 确认当前阶段的前置阶段已完成
+3. 如有缺失，汇报并询问是否补做
+```
+
+#### 建议 5: Context 阶段增加必读清单
+
+**位置**：`references/phase-contracts.md` - Context 阶段
+
+**增加内容**：
+```markdown
+## Context 阶段必读文件
+
+按顺序读取（即使文件不存在也要尝试）：
+
+1. **devflow/index.md** - 项目索引
+   - 查找相关领域的历史项目
+   - 识别可能相关的关键词
+   
+2. **devflow/glossary/CONTEXT.md** - 术语表
+   - 提取项目术语和业务规则
+   
+3. **相关项目的 decisions.md** - 历史决策
+   - 从 index.md 中识别的相关项目
+   - 读取其决策，避免重复或冲突
+   
+4. **devflow/compound/*.md** - 可复用知识
+   - 查找可复用的设计模式、经验
+
+**如果文件不存在**：
+- 记录"无历史上下文"
+- 在 proposal.md 中标注"首次相关实现"
+- 继续执行
+```
+
+#### 建议 6: 增加"违规自检"机制
+
+**目标**：每个阶段结束前，自动检查是否违反硬约束
+
+**实现**：在每个阶段的退出条件后增加"自检清单"
+
+```markdown
+## [阶段名] 退出前自检
+
+检查以下硬约束是否违反：
+
+- [ ] 是否跳过了 context？
+      检查：是否读取了 devflow/index.md？
+      
+- [ ] 是否跳过了 grill？
+      检查：decisions.md 中是否记录了至少 3 个澄清问题？
+      
+- [ ] 是否跳过了 commit？
+      检查：是否存在 .committed 文件？
+      
+- [ ] apply 是否基于 Committed OpenSpec？
+      检查：apply 开始前是否读取了 OpenSpec 文件？
+      
+- [ ] 遇到冲突是否先分类？
+      检查：冲突记录是否标记了类型（规格遗漏/实现偏差）？
+      
+- [ ] 是否调用了所有必需的子 skill？
+      检查：阶段定义中要求的 skill 是否都调用了？
+
+如有违规项，停止执行并汇报。
+```
+
+---
+
+### Low Priority（可选增强）
+
+#### 建议 7: Grill 阶段增加 Question Pool 模板
+
+**目标**：帮助我提出高质量的澄清问题
+
+**位置**：`references/phase-contracts.md` - Grill 阶段
+
+**增加内容**：
+```markdown
+## Grill Question Pool 模板
+
+必须覆盖至少 3 个维度：
+
+### 维度 1: 范围边界
+模板问题：
+- "Out of scope 里的 X 功能，为什么不在这次做？有什么依赖或风险？"
+- "如果用户要求 Y，这个方案能扩展支持吗？需要改动多少？"
+- "边界场景 Z 应该怎么处理？报错还是降级？"
+
+### 维度 2: 技术风险
+模板问题：
+- "如果依赖的 A 服务挂了，这个方案有降级策略吗？"
+- "为什么选择技术方案 B 而不是 C？主要考虑什么？"
+- "数据量增长到 N 倍，性能瓶颈在哪里？"
+
+### 维度 3: 用户验证
+模板问题：
+- "这个方案解决的核心痛点是什么？有真实场景吗？"
+- "有没有现成的替代方案？为什么不用？"
+- "如果上线后发现不符合预期，回滚成本多大？"
+
+### 维度 4: 实现可行性
+模板问题：
+- "最复杂的部分是什么？有没有技术预研？"
+- "需要改动哪些核心模块？影响面多大？"
+- "有没有类似的历史实现可以参考？"
+```
+
+#### 建议 8: 增加"快速模式"明确定义
+
+**当前问题**：`operating-rules.md` 提到快速模式，但没说具体怎么做
+
+**建议**：明确快速模式的简化规则
+
+```markdown
+## 快速模式
+
+### 触发条件
+满足以下所有条件时，可使用快速模式：
+- 变更小于 5 个文件
+- 无架构变更
+- 无数据库迁移
+- 用户明确要求"快速"
+
+### 简化规则
+1. Grill 阶段：至少 1 个问题（而非 3 个）
+2. Specify 阶段：tasks.md 可简化为 3 个子任务
+3. Audit 阶段：可跳过（标注"快速模式跳过审计"）
+4. Archive 阶段：使用 micro 分档（brief/decisions/acceptance）
+
+### 不得简化
+- Context 阶段：仍需读取 devflow
+- Commit 阶段：仍需检查 OpenSpec 完整性
+- Apply 阶段：仍需基于 Committed OpenSpec
+```
+
+---
+
+## 执行机制优化建议
+
+### 当前问题：约束是"软性"的
+
+**现象**：
+- 规则写得很清楚："不得跳过 commit"
+- 但我仍然能跳过，没有强制机制
+
+**根本原因**：
+- 规则是"描述性"的（说应该做什么）
+- 缺少"执行性"的机制（强制检查、文件依赖）
+
+### 解决方案：引入"门控文件"
+
+**设计**：
+```
+每个阶段完成后，创建一个标记文件：
+- .context-done
+- .grill-done
+- .commit-done (即 .committed)
+- .apply-done
+- .archive-done
+
+下一个阶段开始前，检查前置文件是否存在。
+```
+
+**示例**：Apply 阶段入口检查
+```bash
+if [ ! -f ".committed" ]; then
+    echo "错误：Commit 阶段未完成"
+    echo "缺失文件：.committed"
+    echo "请先完成 commit 阶段，或显式跳过（需用户确认）"
+    exit 1
+fi
+```
+
+**好处**：
+1. 强制执行顺序（无法跳过）
+2. 可视化进度（ls 就能看到哪些阶段完成了）
+3. 支持断点续做（下次执行自动识别位置）
+
+---
+
+## 用户体验优化
+
+### 当前问题：用户不知道"现在在哪"
+
+**场景**：
+- 用户说"继续"
+- 我不知道该从哪个阶段继续
+
+**建议**：每次开始时，主动汇报状态
+
+```
+开始执行 SM Flow...
+
+当前状态：
+✅ Context 已完成
+✅ Propose 已完成
+⏸️ Grill 未开始 ← 当前阶段
+
+下一步：执行 Grill 阶段（人类对齐澄清）
+预计耗时：5-10 分钟
+```
+
+### 建议：增加"进度条"
+
+```
+SM Flow 进度：
+[✅] Clarify
+[✅] Context
+[✅] Propose
+[⏸️] Grill ← 当前
+[ ] Specify
+[ ] Audit
+[ ] Commit
+[ ] Apply
+[ ] Archive
+```
+
+---
+
+## 总结
+
+### 核心问题
+1. **Commit 检查缺少可执行标准**（导致容易跳过）
+2. **Apply 阶段缺少前置门控**（没有强制检查 .committed）
+3. **Archive 阶段缺少 Checklist**（容易遗漏 devflow）
+4. **缺少流程状态追踪**（不知道当前在哪）
+
+### 优先修复（High Priority）
+- ✅ Commit 检查增加 Checkpoint
+- ✅ Apply 增加前置门控
+- ✅ Archive 增加 Checklist
+
+这三个修复后，绝大多数"跳过阶段"问题都能解决。
+
+### 框架本身很好
+- 架构清晰（9 个阶段、4 层架构）
+- 规则明确（6 条硬约束）
+- 文档详细（phase-contracts, archive-rules）
+
+**问题不是"约束不够"，而是"执行机制不够明确"。**
+
+增加可验证的 checkpoint 和门控文件后，我就很难"偷懒"了。

skill-workbench/docs/sm-flow/workflow.md

@@ -1,4 +1,73 @@
-# 增强版工作流总结
+# SM-Flow 工作流
+
+## 当前设计理念（v4.3）
+
+**核心定位**：sm-flow 是一个**用提示词实现的协议层 harness**——编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。
+
+**四层架构**：
+
+```
+sm-flow        → 编排层（harness）：阶段、门控、产物约束、人类对齐
+  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
+    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
+      code     → 实现结果：apply 的产出
+```
+
+**用户命令（4 个）**：
+
+| 命令 | 用户意图 |
+|---|---|
+| `/sm-flow` | 完整流程 |
+| `/sm-flow explore` | 先想想（需求不清楚） |
+| `/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 个，英文动词命名）**：
+
+```
+clarify → context → propose → grill → specify → audit → commit → apply → archive
+入口澄清   上下文     轻量提案   澄清    细化      审计    提交     执行    归档
+```
+
+阶段名是 harness 的内部协议词汇，不是用户 API。面向用户默认只暴露 4 个可见 checkpoint：Discover、Commit、Apply、Archive；内部阶段仍按顺序执行。
+
+**关键设计决策**：
+
+- **真理源分层**：devflow = 上下文（术语、历史决策、验收记录），OpenSpec = 执行（唯一执行真理源），代码 = 结果。devflow 增强 OpenSpec，不替代 OpenSpec。
+- **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**：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 检查），否则不是约束而是建议。
+
+**使用方式**：
+
+详细的使用说明见 [使用方式.md](./使用方式.md)，包括：
+
+- 4 个用户命令的典型场景
+- 完整规划 → 执行 → 归档的分次调用示例
+- 自然语言交互方式
+- 规模分档（micro / standard / complex）
+- devflow 自动维护机制
+- OpenSpec 集成与 Draft/Committed 分离
+- 常见问题解答
+
+---
+
+## 演进历史
+
+以下是 sm-flow 工作流的历史演进记录，从 v1 到当前 v4 方向。每一版都从真实执行失败中提炼，不是理论推演。
 
 ## 旧工作流 vs 新工作流
 
@@ -34,14 +103,14 @@ Phase 4  openspec:apply     Phase 2    grill-with-docs → CONTEXT.md + ADR
 
 ## 新增技能的投入产出
 
-| 技能 | 学多久 | 一次省多少 | 什么时候用 |
+| 技能 | 接入成本 | 主要收益 | 什么时候用 |
 |------|--------|-----------|-----------|
-| to-prd | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 |
+| to-prd | 自动综合 | 结构化需求 | openspec research 结束后 |
-| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 |
+| grill-with-docs | 替换已有 grill-me | 产出文档化澄清 | 需求澄清阶段 |
-| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 |
+| zoom-out | 低 | 避免方向性返工 | grill 完成后、apply 前 |
-| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 |
+| diagnose | 低 | 减少猜测式 bug 修复 | apply 中遇到问题 |
-| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 |
+| tdd | 低 | 减少回归 bug | apply 中写代码 |
-| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 |
+| git-guardrails | 被动生效 | 防止灾难性操作 | 全程自动 |
 
 ## 为什么这套组合优于单纯依赖 openspec
 
@@ -378,6 +447,789 @@ Phase 4    回填 devflow，并确认是否 archive
 
 `sm-flow` 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。
 
+## v3.1：可执行 gate 与使用摩擦修正
 
+v3.1 来自一次真实使用复盘：接口变更文档粒度、propose 后再 grill 的返工感、devflow 增长后的检索成本、子 skill 路径兼容，以及 Phase 3 中用户质疑和代码发现与原设计冲突时的处理方式，都需要变成可执行规则。
 
+v3.1 不改变 v3 的主轴：
 
+> `devflow/` 提供上下文，OpenSpec 提供执行依据，代码只是实现结果。
+
+### Draft / Committed OpenSpec
+
+Phase 1 产出的 OpenSpec 统一视为 **Draft OpenSpec**。它是后续 PRD 对齐、grill 和架构审计的讨论对象，不是实现许可。
+
+Phase 2 和 Phase 2.5 的结论必须回写 OpenSpec。随后新增 Phase 2.9：
+
+```text
+Phase 2.9 Commit OpenSpec
+```
+
+Phase 2.9 检查：
+
+- proposal 是否说明范围、非目标和原因。
+- design 是否记录关键约束、架构风险和接口影响。
+- specs 是否覆盖可观察行为和验收口径。
+- tasks 是否是可执行的纵向切片。
+- 是否还有未确认的 user-interview、未汇报的 evidence-driven 结论、未判级接口影响或 devflow/OpenSpec 冲突。
+
+只有通过 Phase 2.9 的 OpenSpec 才是 **Committed OpenSpec**，Phase 3 只能执行 Committed OpenSpec。
+
+### Grill 必须人工确认
+
+Phase 2 的 `grill-with-docs` 不是代理自问自答。`user-interview` 问题必须一次只问一个，等待用户显式回答，并记录到 `decisions.md`。未获得用户确认的问题不能视为已解决，也不能进入 Phase 2.9 或 Phase 3。
+
+`evidence-driven` 问题可以由代理先查证，但也必须汇报证据、结论和是否需要用户确认。
+
+Phase 2 在开始追问前，还应该先建立一个 question pool。最小问题池至少覆盖：
+
+- 术语
+- 范围边界
+- 验收口径
+
+如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，再把这些维度补进问题池。问题池的作用是先把风险面列全，再继续保持 one-at-a-time 的 `user-interview` 消费节奏，而不是一次把所有问题都抛给用户。
+
+单个 grill 决策确认不等于 Phase 3 apply 授权。用户在 Phase 2 回答“可以”只表示该问题已确认；代理必须先回写 OpenSpec/devflow，停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply、开始实现、执行修改或继续 Phase 3。
+
+### Phase Checkpoint
+
+v3.1 的另一个收紧点是：关键阶段不再靠“看起来做完了”判断完成，而是靠显式 checkpoint。
+
+关键阶段至少包括：
+
+- Phase 0
+- Phase 0.5
+- Phase 1
+- Phase 2
+- Phase 2.5
+- Phase 2.9
+
+每个 checkpoint 至少说明：
+
+- 当前阶段
+- 调用的 capability 来源
+- 产出的关键 artifact
+- 已满足的退出条件
+- 尚未解决的 blocker
+
+如果没有这些信息，就不应该把阶段视为已完成，更不应该直接进入下一阶段。
+
+### Cross-Artifact Alignment
+
+v3.1 之后，Phase 1.5 和 Phase 2.9 不只是“看看文档差不多”，而是要显式检查一条对齐链：
+
+```text
+brief/prd -> proposal -> design -> specs -> tasks
+```
+
+检查重点不是格式，而是下游产物有没有把上游已经确定的内容接住，例如：
+
+- `brief/prd` 里的范围和非目标有没有进入 `proposal`
+- `proposal` 的关键承诺有没有进入 `design`
+- `design` 里的实现约束和接口影响有没有进入 `specs` 或 `tasks`
+- `specs` 里的可观察行为有没有被 `tasks` 切成可执行工作
+
+如果字段、术语、约束、行为或切片只停留在上游文档里，就应该视为对齐缺口，先修 OpenSpec，再继续流程。
+
+### 接口影响分级
+
+v3.1 区分“接口影响记录”和“独立接口文档”：
+
+- 所有接口变更都必须记录影响范围。
+- 只有 L3/L4 才强制独立接口文档或等价独立章节。
+
+分级规则：
+
+| 级别 | 判断条件 | 产物要求 |
+| --- | --- | --- |
+| L1 内部实现 | 不改变调用方可观察行为 | tasks / acceptance 记录验证 |
+| L2 内部接口 | 内部 DTO、service 方法、内部事件、内部判断逻辑变化，消费者仍在同一实现范围内 | 内联接口影响记录 |
+| L3 协作接口 | 影响前端、其他模块/服务、跨团队消费者、数据库契约、事件、回调或 SDK | 独立接口文档或独立章节 |
+| L4 破坏性接口 | 旧调用方可能失败、数据/状态/错误码不同，或需要迁移/灰度/回滚 | 独立接口文档 + 迁移/回滚说明，必要时 ADR |
+
+接口内部判断逻辑也按可观察行为评估。即使签名和字段不变，只要返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用变化，也属于接口影响。
+
+### Devflow Index
+
+`devflow/index.md` 成为 Phase 0.5 的默认入口。上下文查找顺序为：
+
+```text
+devflow/index.md
+devflow/glossary/CONTEXT.md
+相关项目 brief / acceptance / ADR
+devflow/compound/
+```
+
+Phase 4 回填项目档案时必须更新 `devflow/index.md`。最小字段为日期、slug、领域、关键词、关联 OpenSpec 和状态。
+
+另外，v3.1 也把一个实践经验写成硬规则：devflow 不是等到 Phase 4 才第一次补写。`brief.md`、`evidence.md`、`decisions.md` 这类过程内档案应该随阶段就近更新，Phase 4 主要负责 consolidation 和归档口径收束。
+
+### Micro 不是 Skip
+
+`micro` 的目标是降低文档重量，不是给代理发放“可以跳 gate”的许可证。
+
+因此即使是 `micro` 变更，也仍然要保留：
+
+- Phase 0.5 最小上下文收集
+- Phase 2 最小澄清
+- Phase 2.9 commit gate
+- Phase 4 轻量回填
+
+如果因为“改动很小”就跳过这些 gate，应该视为协议偏差，而不是合法优化。
+
+### 实现期冲突处理
+
+Phase 3 中，如果用户质疑、用户修改、代码发现、测试失败或运行行为与 Committed OpenSpec 冲突，必须先分类：
+
+| 分类 | 含义 | 处理 |
+| --- | --- | --- |
+| 实现偏差 | OpenSpec 正确，代码没有按规格做 | 修代码，不改 OpenSpec |
+| 规格遗漏 | OpenSpec 没覆盖真实边界、接口影响、验收或外部行为 | 暂停 apply，修正 OpenSpec，重新 commit |
+| 设计冲突 | OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突 | 暂停并请用户确认设计方向 |
+| 用户变更 | 用户改变目标、范围、验收或风险接受度 | 更新 proposal/specs/tasks 后继续 |
+
+冲突分类、证据、用户确认和 OpenSpec 回写状态必须进入 `decisions.md` 或 `acceptance.md`。
+
+### 子 skill 兼容
+
+v3.1 将子 skill 从“路径绑定”改为“能力绑定”。例如 `openspec-propose`、`openspec-apply-change`、`to-prd`、`grill-with-docs` 都是能力契约。
+
+调用优先级：
+
+1. 平台原生 skill。
+2. 本地 `SKILL.md`，例如 `.claude/skills/...` 或 `.agents/skills/...`。
+3. `sm-flow` 的 fallback 协议。
+
+这样 `sm-flow` 可以在 Claude、Codex 或其他代理环境中迁移，而不会被某个固定目录锁死。
+
+一旦进入 fallback，代理还必须把这次降级本身记录下来。也就是说，fallback 不只是“内部换个做法”，而是一个需要显式声明 capability 缺失、降级原因和风险的协议事件。
+
+## v3.1 后续收口：协议瘦身与 review 修正
+
+在执行硬化规则落地后，又做了一轮非常实际的收口：不是再增加新规则，而是把已经确认的规则放到更稳定、可维护的位置，并修掉瘦身过程中暴露的引用问题。
+
+### 顶层 skill 瘦身
+
+`SKILL.md` 不再同时承担“入口协议”和“大段运行手册”两种职责，而是收敛为：
+
+- 工作流定位
+- 真理源分层
+- 核心硬规则
+- reference 加载入口
+- 阶段总览
+
+原来放在顶层但更适合按需读取的内容，被下沉到新的：
+
+```text
+references/operating-rules.md
+```
+
+这里集中放：
+
+- 接口影响分级
+- 启动检查
+- 项目标识规则
+- devflow 产物分层
+- 快速模式细则
+- 完成标准
+
+这样做的目标不是减少规则，而是减少“启动时一次读太多”和“顶层协议与 reference 抢职责”的问题。
+
+### Fallback 去重复
+
+`fallbacks.md` 也做了第二轮整理：
+
+- 顶部统一定义 fallback 通用记录要求
+- 各 fallback 小节只保留自己的额外记录义务
+
+这样可以避免每个 fallback 都重复写一遍“要声明 fallback、要记录 fallback”，同时不丢失协议要求。
+
+### Review 驱动的自洽性修正
+
+瘦身后又发现了一类很典型的问题：**规则本身没错，但 cross-reference 可能断掉**。因此又补了一轮 review 驱动修正，重点包括：
+
+- `phase-contracts.md` 在首次使用接口分级、分档、快速模式时，显式指向 `operating-rules.md`
+- 修正 fallback 锚点，避免 skill 指向不存在的章节名
+- 统一 `operating-rules.md` 的语言风格，避免在主协议是中文时夹着一整份英文运行规则
+
+这轮修正说明一件事：协议产品化不只是”把规则写出来”，还要保证**入口、逐阶段契约、fallback 和运行规则之间的导航关系始终自洽**。
+
+## v4.0：协议层 Harness 重设计
+
+### 背景
+
+v3.1+ 的规则已经比较完整，但一次完整设计评审暴露出三个结构性问题：
+
+1. **定位模糊**：SKILL.md 说”不替代 OpenSpec，而是增强”，但实际上 sm-flow 已经在编排 OpenSpec 的完整生命周期——包括 propose 时机、grill 顺序、commit gate、apply 授权。这不是”增强”，这是”编排”。
+2. **阶段顺序导致返工**：Phase 1 一次性产出完整 4 件套（proposal + design + specs + tasks），Phase 2 才做 grill 澄清。澄清结果必然回写已细化的产物，形成不可避免的返工循环。
+3. **规则过载**：19 条核心规则平铺在一个列表里，混合了硬约束、流程约束和质量约束。agent 读到第 15 条已经记不清前 5 条的优先级。
+
+### 核心认知转变
+
+sm-flow 不是一个”更好的 skill”，也不是 OpenSpec 的增强插件。它是一个**用提示词实现的协议层 harness**——控制 agent 以什么顺序、什么条件、什么标准使用工具。
+
+这个认知来自一个类比：Claude Code harness 是**代码实现**的（工具权限、hooks、context window），agent 物理上绕不过。sm-flow 是**提示词实现**的，agent 理论上可以违反。因此 sm-flow 需要 checkpoint、显式约束、降级声明等机制来强化执行力——这些机制的本质就是弥补提示词 harness 缺乏物理强制力的弱点。
+
+### 四层架构
+
+```
+Claude Code Harness  → 代码层：工具权限、hooks、context window（agent 绕不过）
+  sm-flow Harness    → 协议层：工作流阶段、门控规则、产物约束、人类对齐（提示词实现）
+    OpenSpec         → 执行引擎：propose/apply/archive 的具体操作
+      Sub-skills     → 能力层：grill、zoom-out、diagnose、tdd
+```
+
+### 用户命令：Actions, Not Phases
+
+借鉴 OpenSpec 的 “Actions, Not Phases” 设计哲学——用户命令表达意图，不表达阶段。阶段是 harness 的内部词汇，不是用户的 API。
+
+v3.1 有 9 个阶段编号（Phase 0 / 0.5 / 1 / 1.5 / 2 / 2.5 / 2.9 / 3 / 4），用户需要记住每个编号对应的含义。v4 收敛为 4 个用户命令：
+
+| 命令 | 用户意图 |
+|---|---|
+| `/sm-flow` | 完整流程（从入口到归档） |
+| `/sm-flow explore` | 先聊聊（需求不清楚） |
+| `/sm-flow apply` | 只执行（已有 Committed OpenSpec） |
+| `/sm-flow archive` | 收尾（回填 devflow + 归档确认） |
+
+内部阶段全部改为英文动词命名：
+
+```
+clarify → context → propose → grill → specify → audit → commit → apply → archive
+```
+
+### 阶段顺序调整：grill 在 specify 前
+
+v3.1 的执行顺序：propose（完整 4 件套）→ grill → specify → audit → commit → apply
+
+v4 的执行顺序：propose（只写轻量 proposal）→ grill → specify（补全 design/specs/tasks）→ audit → commit → apply
+
+核心改变：propose 只写轻量 proposal.md，不调用 openspec-propose。grill 在需求稳定前完成澄清。specify 在需求稳定后才调用 openspec-propose 补全完整 OpenSpec。
+
+这消除了返工循环——grill 在细化之前，不存在”细化 → grill → 回写细化”的问题。
+
+### devflow 延迟写入
+
+v3.1 要求 devflow 产物按阶段就近更新（brief、evidence、decisions 随阶段写入），Phase 4 做 consolidation。实践中 agent 同时维护 OpenSpec 和 devflow 形成双重记录。
+
+v4 改为：clarify → apply 期间只维护 `decisions.md` 作为过程日志。archive 阶段从 decisions.md + OpenSpec 产物提取完整档案（brief.md、evidence.md、decisions.md、acceptance.md）。
+
+### 规则精简：19 条 → 6 条硬约束
+
+v3.1 的 19 条规则按三类分组（硬约束 7 条 / 流程约束 7 条 / 质量约束 5 条）。v4 进一步精简为 6 条硬约束留在 SKILL.md，其余约束下沉到 phase-contracts.md 各阶段退出条件。
+
+```
+v3.1：SKILL.md 包含 19 条三类规则 → agent 需要同时记住所有规则
+v4：SKILL.md 只放 6 条硬约束 → agent 按阶段加载对应的过程约束和质量约束
+```
+
+6 条硬约束：
+
+1. OpenSpec 是唯一执行真理源
+2. 不得跳过 context
+3. 不得跳过 grill（至少 3 个问题）
+4. 不得跳过 commit
+5. 冲突必须先分类再处理
+6. 降级执行必须标注
+
+### 冲突分类简化
+
+v3.1 的四分类（实现偏差 / 规格遗漏 / 设计冲突 / 用户变更）在实际执行中边界模糊，agent 需要同时判断类型、选择处理方式、记录到 decisions.md、考虑是否回写 OpenSpec。判断链过长。
+
+v4 简化为 2+1：
+
+- OpenSpec 不准 → 修 OpenSpec
+- 代码偏离 → 修代码
+- 不确定 → 暂停等用户确认
+
+### 质量约束可观测化
+
+v3.1 的质量约束（如”evidence-driven 必须汇报””user-interview 必须等确认”）缺乏可观测产出，agent 可能形式化地填写而不真正验证。
+
+v4 要求质量约束必须有可观测产出：写入文件 + checkpoint 检查。例如：
+
+| 约束 | v3.1（软） | v4（硬） |
+|---|---|---|
+| evidence-driven 汇报 | “必须向用户汇报” | 写入 decisions.md + checkpoint 列出汇报状态 |
+| user-interview 确认 | “必须等待用户回答” | decisions.md 记录问题原文/用户原话/确认状态 |
+| cross-artifact 对齐 | “必须显式检查” | checkpoint 包含 4 行对齐检查表 |
+
+### Micro 模式升级
+
+v3.1 的 micro 只压缩产物（少写几个文件），没有压缩 gate 数量。v4 的 micro 合并 gate：
+
+```
+v3.1 micro：仍然走完整阶段，只是产物变少
+v4 micro：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题）→ commit（简化检查）
+```
+
+### 文件结构变化
+
+```
+v3.1：
+.agents/skills/sm-flow/
+├── SKILL.md                         # ~85行，入口协议 + 19条规则 + 阶段总览
+└── references/
+    ├── phase-contracts.md           # 阶段契约（Phase 0-4 编号）
+    ├── operating-rules.md           # 运行规则
+    ├── fallbacks.md                 # 降级协议
+    ├── archive-rules.md             # 归档规则
+    └── templates.md                 # 产物模板
+
+v4：
+.agents/skills/sm-flow/
+├── SKILL.md                         # ~50行，入口协议 + 6条硬约束 + 4命令 + 9阶段总览
+└── references/
+    ├── phase-contracts.md           # 阶段契约（英文命名，grill 在 specify 前）
+    ├── operating-rules.md           # 运行规则（启动识别 4 命令，micro 合并 gate）
+    ├── fallbacks.md                 # 内置执行协议（冲突 2+1 分类）
+    ├── archive-rules.md             # 归档规则（decisions.md 过程日志提取）
+    └── templates.md                 # 产物模板（+cross-artifact 对齐检查表）
+```
+
+### 新增文档
+
+- `skill-workbench/docs/sm-flow/使用方式.md`：面向用户的使用指南
+- `skill-workbench/docs/sm-flow/design-review.md`：设计评审记录
+
+### v3.1 → v4 变更对照
+
+| 维度 | v3.1 | v4 |
+|---|---|---|
+| 定位 | “OpenSpec 的上下文增强层和归档闭环层” | “协议层 harness，编排 OpenSpec 完整生命周期” |
+| 阶段命名 | Phase 0/0.5/1/1.5/2/2.5/2.9/3/4 | clarify/context/propose/grill/specify/audit/commit/apply/archive |
+| 用户命令 | 无（用户需要知道阶段编号） | 4 个命令（Actions, Not Phases） |
+| propose 产出 | 完整 4 件套（proposal+design+specs+tasks） | 只写轻量 proposal.md |
+| grill 时机 | specify 之后 | specify 之前 |
+| devflow 写入策略 | 按阶段就近更新多个文件 | 只维护 decisions.md，archive 提取 |
+| 核心规则数量 | 19 条三类分组 | 6 条硬约束 |
+| 冲突分类 | 4 类（实现偏差/规格遗漏/设计冲突/用户变更） | 2+1（OpenSpec 不准/代码偏离/不确定） |
+| micro 模式 | 压缩产物 | 合并 gate |
+| 质量约束 | 文字描述 | 可观测产出（写入文件 + checkpoint） |
+
+## v4.0 验证执行复盘（2026-05-25）
+
+用 entry-expand-collapse 需求跑了一轮完整 sm-flow 流程，验证 v4.0 协议的可执行性。功能变更已回滚，仅保留验证发现。
+
+### 暴露的问题
+
+| # | 问题 | 具体表现 | 分析结论 |
+|---|------|----------|----------|
+| 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 应描述用户可观察的结果而非实现方式 |
+
+### 做对的部分
+
+- clarify + context 合并执行正确（micro 模式）
+- grill 的 evidence-driven / user-interview 分类和 one-at-a-time 节奏执行到位
+- commit gate 的文件存在性检查生效
+- apply 阶段的冲突分类（代码偏离）处理正确
+- devflow 延迟写入（只维护 decisions.md）降低了维护成本
+
+### 后续观察项
+
+问题 1 和 2 暂不改协议，如果多次验证中反复出现再考虑加约束。问题 3 需要在下次 specify 阶段验证：spec scenario 是否自然地描述用户行为而非实现细节。
+
+## v4.1：Apply 阶段前置调研增强（2026-06-23）
+
+### 背景
+
+基于"山东商客意向单同步接口"的执行复盘（`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`），发现 apply 阶段存在严重的返工问题：
+
+- **返工次数**：4-5 次重大返工
+- **核心问题**：apply 阶段"想当然"开始写代码，缺少充分调研和分步验证
+- **主要表现**：
+  - 参考实现利用不充分（设计文档提到参考实现，但直到用户提醒才去看）
+  - 技术栈不熟悉（RequestMsg 结构、Kafka 发送方式、Consumer 位置全部返工）
+  - 设计-实现偏离（验签/解密/查询接口只有 TODO 注释）
+
+### 核心改进：Pre-apply Checkpoint
+
+在 apply 阶段开始前增加强制性调研检查点（方案 B 简化版）：
+
+#### 修改 1：grill 阶段增加技术实现维度
+
+在 question pool 中新增"技术实现维度"：
+
+```markdown
+**技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
+- 参考实现的具体文件路径是什么？
+- 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
+- 有哪些技术点需要先调研或新建？
+```
+
+**目的**：在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
+
+#### 修改 2：apply 阶段增加 Pre-apply Checkpoint
+
+在 apply 阶段开始前增加强制调研步骤：
+
+**触发条件**（3 条）：
+- design 或 tasks 中提到"参考 XXX 实现"
+- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
+- 技术栈不熟悉或第一次在该项目实现类似功能
+
+**执行步骤**（3 步）：
+1. **完整阅读所有参考实现**
+   - 从 OpenSpec design 或 tasks 中定位参考实现文件
+   - 如果路径不明确，通过 Grep 搜索关键类名或模式
+   - 逐行理解关键逻辑，提取可复用代码片段和模式
+
+2. **Grep 关键技术栈**
+   - 请求/响应结构模式
+   - 消息队列模式
+   - 统一工具类
+   - 异常处理和日志记录标准
+
+3. **形成技术栈清单并写入 decisions.md**
+   - 项目使用的请求/响应结构标准
+   - MQ 消息定义和发送标准
+   - Consumer 标准位置和写法
+   - 加密/验签/工具类的标准用法
+   - 识别需要新建的工具类或基础设施
+
+**输出要求**（3 条）：
+- ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
+- ✅ 已列出所有参考实现的文件路径
+- ✅ 已识别需要新建的工具类/基础设施
+
+**快速模式支持**：micro 分档可按风险缩小调研范围，但仍需形成清单。
+
+#### 修改 3：apply 实现过程增强
+
+**分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
+
+**首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
+
+**快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
+
+#### 修改 4：apply 退出条件增强
+
+新增退出条件：
+- ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
+- ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
+
+### 预期效果
+
+| 指标 | 当前 | 目标 | 改善 |
+|------|------|------|------|
+| 返工次数 | 4-5 次 | 0-1 次 | -80% |
+| 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% |
+
+**ROI 分析**：
+
+前置调研的收益来自减少返工和避免核心功能遗漏。v4.3 之后不再用固定投入指标定义投入或收益，改按风险和实现复杂度决定调研深度。
+
+### 复杂度评估
+
+**本次修改复杂度**：中等
+- 文本增量：+55 行（从 281 行 → 336 行，+20%）
+- 概念层级：+1 层（apply 内部增加 Pre-apply Checkpoint 子阶段）
+- 强制规则：+5 条（pre-apply 触发条件、执行步骤、输出要求）
+
+**整体复杂度**：高（但合理）
+- 总行数：606 行 → ~700 行（+15%）
+- 阶段数：9 个（不变）
+- 门控数：4 个 → 6 个（+propose checkpoint, +pre-apply checkpoint）
+
+**简化设计**：
+- 采用方案 B（简化版），相比完整方案减少 45% 文本量和 44% 规则数
+- 保留核心价值（前置调研、技术栈清单、核心功能质量保证）
+- 去掉过度约束（严格执行顺序、频繁检查点、详细操作模板）
+
+### 适用场景
+
+✅ **强烈推荐**：
+- 中等及以上规模需求（3+ 接口或涉及多模块）
+- 涉及项目现有基础设施（MQ/统一请求结构/工具类）
+- 第一次在该项目实现类似功能
+- 设计文档提到"参考 XXX 实现"
+
+🟡 **可选执行**：
+- micro 分档的简单需求（可按风险缩小范围）
+- 纯数据处理或工具脚本（技术栈熟悉）
+
+❌ **不推荐**：
+- 紧急热修复（时间紧急）
+- 一次性脚本（不涉及项目标准）
+
+### 相关文档
+
+- 执行复盘：`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
+- 更新日志：`skill-workbench/docs/sm-flow/phase-contracts-v4.1-changelog.md`
+- 修改文件：`.agents/skills/sm-flow/references/phase-contracts.md`
+
+## v4.2：可验证 Checkpoint 与执行机制增强（2026-06-24）
+
+### 背景
+
+基于"lookup-knowledge-integration"的执行复盘（`skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`），发现一个结构性问题：
+
+**约束是"软性"的，缺少执行机制**
+
+- **规则清楚但可绕过**：6 条硬约束写得很清楚"不得跳过 commit"，但 agent 仍然能跳过
+- **标准模糊无法判断**：commit 阶段说"检查是否可执行"，但不知道具体检查什么
+- **流程无强制顺序**：archive 建议"先 devflow 后 handoff"，但 agent 可能先创建 handoff
+
+**核心认知**：规则是"描述性"的（说应该做什么），缺少"执行性"的机制（强制检查、文件依赖）。
+
+### 核心改进：从软性约束到硬性检查
+
+v4.2 不增加新阶段或新规则，而是**把现有约束变成可验证的 checkpoint**：
+
+| 改进点 | Before（v4.1） | After（v4.2） |
+|--------|---------------|--------------|
+| Commit 标准 | "检查是否可执行"（模糊） | 文件完整性 + 一致性检查清单（具体） |
+| Apply 门控 | "已通过 commit"（软性） | 检查 `.committed` 文件存在（硬性） |
+| Archive 顺序 | "应该先 devflow"（建议） | 5 步强制顺序 + 自检（必须） |
+
+### 详细修改
+
+#### 修改 1：Commit 阶段增加可验证 Checkpoint
+
+**文件完整性检查**（必须全部通过）：
+- [ ] `proposal.md` 存在，包含问题描述（≥50字）、建议方案（≥100字）、范围/非目标
+- [ ] `design.md` 存在，包含架构设计、数据结构（≥1个）、关键决策（≥2条）
+- [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
+- [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准
+
+**一致性检查**（必须通过）：
+- [ ] proposal 核心概念 → design 有对应设计
+- [ ] design 关键决策 → tasks 有对应实现
+- [ ] tasks 验收标准可验证（非"正确实现"这类模糊描述）
+
+**标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件
+
+#### 修改 2：Apply 阶段增加前置门控
+
+**前置门控检查**（硬约束）：
+1. 检查 `openspec/changes/{slug}/.committed` 文件是否存在
+2. 如不存在：
+   - 汇报：Draft OpenSpec 未通过 commit 检查
+   - 列出缺失的 checkpoint 项
+   - 询问用户：是否补做 commit；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`
+
+#### 修改 3：Archive 阶段增加强制执行顺序
+
+**5 步 Checklist**（不得跳过或重排）：
+1. **创建 devflow 档案**（必需）：brief.md + evidence.md + decisions.md + acceptance.md
+2. **更新索引**（必需）：在 `devflow/index.md` 追加一行
+3. **标记 OpenSpec**（必需）：创建 `.archive-ready` 文件
+4. **向用户汇报**（必需）：列出文件、验证分类、剩余风险，询问是否归档
+5. **执行 OpenSpec Archive**（可选）：用户确认后调用 `openspec-archive-change`
+
+**自检**：Step 4 前检查 Step 1-3 是否都完成
+
+### 新增门控文件
+
+| 文件 | 创建时机 | 用途 |
+|------|----------|------|
+| `.committed` | commit 阶段退出时 | apply 阶段前置门控依据 |
+| `.archive-ready` | archive Step 3 | 标记归档准备就绪 |
+
+### 预期效果
+
+**解决的问题**：
+- ❌ Commit 标准不明确 → ✅ 有具体检查清单，无法模糊通过
+- ❌ Apply 可能基于不完整 OpenSpec → ✅ 门控文件强制阻止
+- ❌ Archive 容易遗漏 devflow → ✅ 强制顺序确保完整
+
+**量化指标**：
+- Commit 阶段跳过率：-100%（有 checklist 无法跳过）
+- Apply 基于不完整 OpenSpec：-100%（门控阻止）
+- Archive 遗漏 devflow：-100%（强制顺序）
+
+### 设计原则
+
+#### 1. 可验证性
+将模糊标准转为可测量的具体要求：
+- Before: "检查 OpenSpec 是否可执行"
+- After: "proposal ≥50字、design ≥1个数据结构、specs ≥3个 requirement"
+
+#### 2. 门控文件
+用文件存在性替代软性判断：
+- Before: 描述"已通过 commit"
+- After: 检查 `.committed` 文件存在
+
+#### 3. 强制顺序
+用 checklist 替代建议性描述：
+- Before: "应该先创建 devflow"
+- After: "Step 1 devflow → Step 2 索引 → Step 3 标记 → Step 4 汇报"
+
+### 复杂度评估
+
+**本次修改复杂度**：低-中等
+- 文本增量：+80 行（phase-contracts.md +40 行，archive-rules.md +40 行）
+- 概念增加：2 个门控文件
+- 规则增强：3 个阶段的检查清单
+
+**整体复杂度**：高（但更可靠）
+- 总行数：~700 行 → ~780 行（+11%）
+- 门控数：6 个 → 8 个
+
+**权衡**：
+- ✅ 收益：彻底解决"跳过阶段"问题
+- ⚠️ 成本：增加 80 行文本，更多检查项
+
+### 与 v4.1 的关系
+
+| 版本 | 核心改进 | 解决问题 |
+|------|----------|----------|
+| v4.1 | Pre-apply Research Checkpoint | apply 前置调研不足，导致返工（4-5次 → 0-1次） |
+| v4.2 | 可验证 Checkpoint + 门控文件 | 约束是软性的，agent 容易跳过阶段 |
+
+**互补关系**：
+- v4.1 解决"调研不充分导致返工"（质量问题）
+- v4.2 解决"缺少执行机制导致跳过阶段"（流程问题）
+
+### 适用场景
+
+**✅ 所有场景（无例外）**
+
+v4.2 的改进是执行机制层面的，不涉及业务逻辑：
+- 无论 micro/standard/complex，都需要 commit 检查
+- 无论需求大小，都需要 apply 前置门控
+- 无论项目规模，都需要 archive 强制顺序
+
+**快速模式**：可以简化产物（如 tasks 只需 3 个），但**不能跳过门控**。
+
+### 后续演进方向（v5.0 候选）
+
+如果 v4.2 执行良好但仍有问题，考虑：
+
+1. **流程状态文件** `.sm-flow-state`
+   - 记录当前阶段、已完成阶段、时间戳
+   - 支持断点续做
+
+2. **更多门控文件**
+   - `.context-done`、`.grill-done`、`.apply-done`
+   - 形成完整的阶段间依赖链
+
+3. **违规自检机制**
+   - 每个阶段退出前，自动检查 6 条硬约束
+
+4. **进度可视化**
+   - 每次开始时，汇报进度条
+
+**判断依据**：如果 v4.2 后仍频繁出现跳过阶段，再引入更重的机制。
+
+### 相关文档
+
+- 执行复盘：`skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`
+- 更新日志：`skill-workbench/docs/sm-flow/phase-contracts-v4.2-changelog.md`
+- 修改文件：
+  - `.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/`

skill-workbench/docs/sm-flow/使用方式.md

@@ -0,0 +1,191 @@
+# SM-Flow 使用方式
+
+本文档面向 sm-flow 的用户，说明如何启动、交互和使用 sm-flow。
+
+## 快速开始
+
+sm-flow 通过 4 个用户命令覆盖完整生命周期。你不需要了解内部阶段，只需表达意图。
+
+| 命令 | 意图 | 典型场景 |
+|---|---|---|
+| `/sm-flow` | 完整流程 | 有粗略想法，从头规划到执行 |
+| `/sm-flow explore` | 先聊聊 | 需求不清楚，带上下文探索 |
+| `/sm-flow apply [change]` | 只执行 | 已有 Committed OpenSpec，直接实现 |
+| `/sm-flow archive [change]` | 收尾 | 执行完了，回填 devflow + 归档 |
+
+你也可以用自然语言指定阶段继续，例如：
+
+```
+ops-message-support 的 grill 已经做完了，继续
+帮我检查一下 add-dark-mode 的 OpenSpec 对齐
+```
+
+sm-flow 会识别意图，自动补做最小前置检查，然后从指定阶段继续。
+
+## 典型使用流程
+
+### 场景 1：完整规划 → 执行 → 归档（分三次调用）
+
+```bash
+# 第一次：完整规划
+/sm-flow 给站内消息加 OMC 支持
+→ 走完 clarify → context → propose → grill → specify → audit → commit
+→ 停在 apply 前，你说"先不执行了"
+
+# 第二次：继续执行
+/sm-flow apply ops-message-support
+→ 进入 apply，执行完 tasks
+
+# 第三次：归档
+/sm-flow archive ops-message-support
+→ 回填 devflow，询问是否归档 OpenSpec change
+```
+
+三个阶段，三次调用，每次只做一个用户意图的事。
+
+### 场景 2：需求不清楚，先探索
+
+```bash
+/sm-flow explore 我们在考虑是否要重构消息队列
+→ sm-flow 读取 devflow 上下文，和你讨论需求边界、风险、替代方案
+→ 不生成 OpenSpec，只帮你理清思路
+→ 如果讨论出明确方向，下次可以用 /sm-flow 启动完整流程
+```
+
+### 场景 3：小改动，快速模式
+
+```bash
+/sm-flow 修复按钮的拼写错误
+→ sm-flow 识别为 micro 规模
+→ 合并 gate：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题）→ commit（简化检查）
+→ 保留最关键的门控，但流程更轻量
+```
+
+### 场景 4：从中间继续
+
+```bash
+# 上次对话停在 grill 阶段
+add-dark-mode 的 grill 已经做完了，继续
+→ sm-flow 识别意图，自动补做 specify 的最小前置检查
+→ 从 specify 阶段继续
+```
+
+## 交互模式
+
+### Human Checkpoint
+
+sm-flow 在关键节点会暂停并询问你：
+
+- **propose 后**：说明 proposal 范围、关键假设、主要风险，询问是否继续 grill
+- **grill 后**：汇报已解决和未解决的问题、proposal 变更，询问是否继续 specify
+- **audit 后**：说明架构风险、OpenSpec 修正点，询问是否进入 commit
+- **commit 后**：说明 Committed OpenSpec 范围、接口影响、剩余风险，询问是否进入 apply
+- **archive 前**：询问是否归档 OpenSpec change
+
+你可以选择继续、暂停、或要求返回上一阶段。
+
+### Grill 阶段的一对一澄清
+
+grill 阶段会建立一个 question pool，覆盖术语、边界、验收三个维度。问题分两类：
+
+- **evidence-driven**：sm-flow 先查证代码、文档、OpenSpec 或 ADR，再向你汇报证据和结论
+- **user-interview**：sm-flow 一次只问一个问题，等你确认后才继续
+
+典型节奏：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续。
+
+### 自然语言交互
+
+除了 4 个命令，你可以用自然语言与 sm-flow 交互：
+
+```
+# 指定 change name
+继续 ops-message-support
+
+# 指定阶段
+add-dark-mode 的 specify 做完了吗？
+
+# 指定动作
+帮我检查一下 add-dark-mode 的 cross-artifact 对齐
+
+# 混合表达
+ops-message-support 的 grill 已经确认了术语和边界，继续 specify
+```
+
+sm-flow 会识别意图，自动编排后续阶段。
+
+## 规模分档
+
+sm-flow 根据变更规模自动分档，调整流程重量：
+
+| 分档 | 适用场景 | 流程特点 |
+|---|---|---|
+| `micro` | 小改动、低风险、需求明确 | gate 合并，grill 最少 1 个问题，commit 简化检查 |
+| `standard` | 默认模式 | 完整 9 阶段流程 |
+| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 基础上增加扩展产物（PRD/research/design/tasks/alignment） |
+
+你不需要显式指定分档，sm-flow 会在 clarify 阶段自动判断。如果判断不准，会作为 user-interview 问题等待你确认。
+
+## devflow：自动维护的项目长期记忆
+
+sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。你不需要手动管理它。
+
+```
+devflow/
+├── projects/YYYY-MM-DD-{slug}/       ← 项目档案（brief/evidence/decisions/acceptance）
+├── glossary/CONTEXT.md                ← 领域词汇表
+├── compound/                          ← 跨项目知识沉淀
+├── reference/                         ← 共享模板
+└── index.md                           ← 项目索引
+```
+
+**clarify → apply 期间**：sm-flow 只维护 `decisions.md` 作为过程日志（grill 结论、关键决策、验证结果）。
+
+**archive 阶段**：从 decisions.md + OpenSpec 产物提取完整档案（brief.md、evidence.md、decisions.md、acceptance.md）。
+
+**下次使用时**：sm-flow 会自动读取 devflow 上下文，增强 OpenSpec 产物。术语、历史决策、验收记录不会丢失。
+
+## OpenSpec 集成
+
+sm-flow 编排 OpenSpec 的生命周期，但不强制依赖 OpenSpec CLI：
+
+- **优先使用 OpenSpec CLI**：如果 `openspec-propose`、`openspec-apply-change`、`openspec-archive-change` 可用，sm-flow 会调用它们
+- **内置执行协议**：如果 OpenSpec CLI 不可用，sm-flow 使用内置协议接管（标注为降级执行）
+
+Draft / Committed 分离：
+
+- **Draft OpenSpec**：propose 阶段产出，是讨论对象，不是执行许可
+- **Committed OpenSpec**：通过 commit gate 后，成为 apply 的执行依据
+- **apply 只执行 Committed OpenSpec**：防止未经澄清的方案直接进入实现
+
+## 常见问题
+
+### Q: 我需要在启动前准备什么？
+
+不需要。sm-flow 会从你的粗略想法、issue、PRD 或已有 research 开始。如果信息不足，clarify 阶段会追问。
+
+### Q: 我可以跳过某个阶段吗？
+
+不可以。sm-flow 的门控是硬约束（grill 至少 3 个问题、commit gate 必须通过）。但 micro 模式会合并 gate，减少流程开销。
+
+### Q: 如果 OpenSpec 不可用怎么办？
+
+sm-flow 会使用内置执行协议接管，标注为降级执行。产物仍然写入 `openspec/changes/{slug}/`，只是不通过 OpenSpec CLI。
+
+### Q: devflow 和 OpenSpec 冲突怎么办？
+
+sm-flow 会先汇报冲突，等你确认，然后修正 OpenSpec，再继续执行。devflow 是上下文，OpenSpec 是执行真理源。
+
+### Q: 我可以修改已经 commit 的 OpenSpec 吗？
+
+可以。如果 apply 阶段发现规格遗漏、设计冲突或用户变更，sm-flow 会暂停 apply，修正 OpenSpec 后重新提交。
+
+### Q: archive 阶段会自动归档 OpenSpec 吗？
+
+不会。archive 阶段会回填 devflow，然后询问你是否归档 OpenSpec change。在你说"是"之前，不会执行归档。
+
+## 参考文档
+
+- **设计理念**：[workflow.md](./workflow.md) — 当前设计理念（v4 方向）和演进历史
+- **设计评审**：[design-review.md](./design-review.md) — 核心定位、状态评估、已确认修改方向
+- **回溯分析**：[retrospective.md](./retrospective.md) — 历史执行失败分析
+- **使用问题**：[使用问题.md](./使用问题.md) — 真实痛点收集

skill-workbench/docs/sm-flow/使用问题.md

@@ -0,0 +1,8 @@
+1. 如果涉及接口，需要额外产出一份影响接口范围文档
+	1. ❯ 只要涉及到接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中 
+2. 涉及接口变更，需要产出一份接口文档
+3. 顺序问题，目前的顺序是propose之后在，生成了task、design之后，再用grill去澄清需求，这样当澄清完需求后，又得回去更新task、design、proposal等文档，现在的流程，是propose之后，再通过to-prd，生成devflow的产物，然后再grill来更新，哪种设计更合理？
+4. 如果devflow数量多了，如何快速定位需要的上下文
+5. 子skill现在是固定了claude，要考虑兼容情况
+6. 当在开发阶段，我发起质疑或者修改，和原来设计冲突时，不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到，要提出反馈
+	1. 可能需要加多一个步骤，apply实施过程中的沟通？

skill-workbench/docs/value/latest-design.md

@@ -0,0 +1,111 @@
+# value-scan / value-dig · 设计文档（Latest Design）
+
+> **定位**：从**已交付的代码**里逆向萃取「值得讲的价值点」，交人勾选后深挖成可讲、可追问、可被审的文档。
+> **适用**：面试/简历素材重建、模块价值盘点、交接文档提级。
+> **形态**：两个 skill 接力 —— `value-scan`（广度枚举，停在人工勾选门）→ `value-dig`（深度产出，三件套任选）。
+> **战果**（its 仓库实测，2026-09-18）：4 轮扫描产出 9 份文档全部通过机械校验；2 条主链路各带 1 个 P0 级实锤缺陷。
+
+---
+
+## 1. 为什么要有这两个 skill
+
+盘点代码价值时，agent 有三个系统性偏差：
+
+| 偏差 | 表现 | 解药 |
+|---|---|---|
+| **判不了价值** | 把"用了 Redis""有 4 个 handler"当亮点 | 简历行填空测试：`用【机制】解决了【问题】，代价是【取舍】`——机制格填不出就不是价值点 |
+| **缺陷导向** | 扫一遍变成挑毛病大会，清单全是负面 | 阶段隔离：S1 只产亮点，缺陷是深挖链路时自然浮现的副产物，归宿在改造方案 |
+| **自作主张** | 替用户挑完直接开写 | 门控：产出候选清单后**必须停**，勾选权在人 |
+
+一句话设计哲学：**agent 负责采样与结构化，人负责价值判断**。
+
+## 2. 两段流水线
+
+```
+S0 定范围 → S1 枚举 → S2 勾选【硬门：必须停】
+                              ↓（人勾选 / 否决改向 A′）
+                    value-dig：①功能点清单 ②设计复盘 ③改造方案（各自独立，可只做其一）
+```
+
+### value-scan（广度）
+
+- **三层结构**：域 → 链路 → 机制节点。链路按**触发者**拆（谁在改这行数据），不按业务功能拆——收敛点多半是机制所在。
+- **三条硬标准**（全过才进清单）：① 核心链路 ② 高级工程师的设计（非框架常识）③ 简历够硬。
+- **数量闸**：5–8 条为宜，>12 = 颗粒度掉到实现层，退回重并。
+- **两层锚点**：机制级 `路径#方法名`（不写行号，防漂移），深挖级 `文件:行号`（必须读过再写）。
+
+### value-dig（深度）
+
+三份文档三种读者：
+
+| 文档 | 读者 | 灵魂 |
+|---|---|---|
+| ① 功能点清单 | 自己/接手人 | **主干调用骨架**：整条链压成一段伪代码，每行标方式（`[锁]``[幂等]``[MQ]`），功能点互为索引 |
+| ② 设计思路与取舍 | 面试官 | 第一人称复盘 + **"与代码的对照说明"**：判断与代码事实不一致处逐条列出——诚实性是可信度唯一来源 |
+| ③ 改造方案 | 架构评审 | 缺陷唯一归属地；**产出门槛**：必须有②加机制/③重构档改造点才立方案，全是补漏档不立（防灌水） |
+
+跨文档资产复用：`tb_order_anomaly` 台账、token 锁工具、巡检 Job——两链路方案共用一套，是"结构必然"不是"省事"。
+
+## 3. 机制设计要点（为什么这样设计）
+
+### 3.1 门控（S2 必停）
+
+价值判断权如果不在人，整个流水线退化成"agent 自嗨产出没人看的文档"。所以：
+- 候选清单落盘 + 显式请求勾选（"请从 N 条挑 3–6 条"）；
+- 用户禁用提问工具也一样停——请求写成文字；
+- **整批否决且未给新目标 = 流程终点**，不强续。
+
+### 3.2 判据外化为填空
+
+"价值"无法定义，但"简历行填得出来吗"可判定。两级：
+- **准入**：三条硬标准（反例驱动的剔除表）；
+- **表达**：机制+问题两格必填，取舍格留给 value-dig（不误杀）。
+
+被剔除的点不丢弃——进「已剔除」表注明未过哪条标准，供复核筛选口径。
+
+### 3.3 机械校验（check.py）与模板外置
+
+- 模板是**活资产**：产出照模板填空，被纠正过就回写模板；
+- check.py 十余条规则：引号配对 / mermaid 合法性 / 表格列一致+不缩进 / 章节完整性（模板必备节 ⊆ 产出节）/ scan 专属（无代码围栏、锚点格式、候选数 ≤12）/ dig 专属（骨架行必带方式标记、证据必含行号）/ doc 专属（改造方案必有关键片段）；
+- FAIL 必须为 0，WARN 允许保留但写明原因。
+
+### 3.4 缺陷的归宿隔离
+
+缺陷只在改造方案出现，且**不是枚举出来的是贴着链路走出来的**——三把刀（按触发者拆链路 / 竞态矩阵 / 幂等键清单+状态流转图）+ 机制模式库（结构性限制 → 可引入机制对照表）+ 三档尺度（补漏⭐/加机制⭐⭐⭐/重构⭐⭐⭐，每缺陷必追问"能否升一档"）。
+
+## 4. 实战演化记录（its 仓库 4 轮，2026-09-18）
+
+这轮实战暴露的边界案例与回写（模板活资产的实证）：
+
+| # | 事件 | 回写 |
+|---|---|---|
+| 1 | 用户否决 5 条单点："都不够硬，直接分析整链路" | value-dig 新增**入口 A′（否决改向）**：否决原因入清单、按 B 重走、产物声明 |
+| 2 | 权益域首轮以"机制格填不出"剔除，复评翻案（快照轮询机制实存，藏在 2349 行大类的私有方法群） | "机制格填不出"剔除加**硬门槛**：没读过入口方法向下 ~100 行不得定稿剔除；翻案不删行留痕 |
+| 3 | "不够硬"出现两次（单点否决、权益否决） | S2 门控新增**否决即校准**：负反馈记入清单，同域复扫先读否决记录 |
+| 4 | 勾选回写两次压列（3 列变 2 列） | 候选清单模板补**回写示例**（3 列不压列）；check.py 报错**附行内容摘要** |
+| 5 | check.ps1 仅 Windows | 移植 **check.py**（等价回归 8 产物一致）；顺带发现初版 `__name__` 损坏静默 exit 0——校验工具自身的静默通过比报错更危险 |
+
+### 实测产出骨架（可作参考样例）
+
+```
+docs/
+├── 赢客下单-候选价值点.md        S1 清单（5 候选 + 5 剔除）
+├── 赢客下单-功能点清单.md        7 功能点 + 主干骨架
+├── 赢客下单-设计思路与取舍.md    4 不变量 / 7 决策 / 口述版
+├── 赢客下单-改造方案.md          6 缺陷（3🔴）→ 3 阶段
+├── 全仓其余域-候选价值点.md      二轮 8 候选（含翻案 ★7/★8）
+├── 工单全生命周期-{功能点清单,设计思路与取舍,改造方案}.md
+```
+
+两个 P0 实锤（深挖才浮现的典型）：
+- 幂等双关口键不一致：bossOrderId vs requestId，组合穿透 → 重复扣权益；
+- `updateConfirmInfo` 条件更新漏 `status=51`：设计是 DB 仲裁，落地是应用层检查 → 人工确认可被自动确认覆盖。
+
+## 5. 已知限制与下一步
+
+| 限制 | 说明 | 候选方向 |
+|---|---|---|
+| 单域节奏 | 一次一域，全仓扫描靠人反复发起 | 域清单自动切片 + 断点续扫 |
+| 判据主观残留 | "简历够硬"仍依赖人对目标岗位的校准 | 按 JD 关键词加权候选排序 |
+| 深挖成本 | 一个功能点 ≈ 1–2 份 20KB 文档，人工审读压力大 | 功能点清单先行 + 复盘/方案按勾选再出 |
+| 校验器无自检 | check.py 自身损坏会静默通过 | CI 里对已知 BAD 样例断言必 FAIL |

skill-workbench/generated-skills/skills/value-dig/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: value-dig
+description: Use when the user has already chosen which mechanisms or value points matter and now wants them written up in depth — "把这个点写成文档", "把这条链路的实现整理成功能点", "写设计思路与取舍", "出改造方案", or when an existing module's design must be reconstructed layer by layer for an interview walkthrough. Read-only — never modifies the scanned project.
+---
+
+# value-dig · 深度产出（功能点 / 设计复盘 / 改造方案）
+
+## 一句话
+
+把**已经选定的**机制点写成**能讲、能追问、能被审**的文档：按需产出三件套。
+
+**两条原则**
+
+1. **价值优先 → 深入 → 更优方案。** 缺陷与改造只在「改造方案」里出现；功能点清单与设计复盘以"这个设计为什么好、怎么取舍"为主体。
+2. **只读**：不修改被扫描项目的任何文件（新增产物不算）。
+
+## 两种入口
+
+| 入口 | 情形 | 怎么做 |
+|---|---|---|
+| **A · 有候选清单** | 上游 `value-scan` 已产出且人已勾选 | 直接开工；勾选结果回写候选清单「闸门状态」节（`✅ 已勾选：★N…⟨谁/日期⟩`） |
+| **A′ · 候选被否决改向** | 人看了清单说"都不够硬，直接分析整条链路"——否决候选但给出新目标 | 三步：①原清单「闸门状态」记**否决原因原文摘要**（这是筛选口径的校准数据）；②按 B 的最小枚举对准新目标重走；③产物头部声明"入口 A′（否决改向）" |
+| **B · 直接点名** | 用户直接说"把 XX 链路写成文档"，无候选清单 | 只针对该链路按 `value-scan` 的判据做一次**最小枚举**（按触发者拆链路 + 三条硬标准），在产物头部声明"入口 B" |
+
+> **入口 B 不能省粗筛**：跳过判据会把"框架常识/纯业务实现"写成深度文档。
+
+## 三份文档（各自独立，可只做其一）
+
+> 若用户只要"每个点先给个轻理由看看"再决定深挖谁，可用 `assets/价值点报告模板.md` 快速产出一份轻量报告，不必直接进三件套。
+
+| 文档 | 模板 | 内容 | 关键 |
+|---|---|---|---|
+| ① **功能点清单** | `assets/深度模板/功能点清单模板.md` | 链路总览 · **主干调用骨架** · 各功能点 · 推荐组合 · 附录速查 | **只记功能点，不列缺陷** |
+| ② **设计思路与取舍** | `assets/深度模板/设计思路与取舍模板.md` | 第一人称复盘：问题定义 → 不变量 → 怎么拆 → 设计主线 → 逐环节决策表 → 做对的/承接不住的 → 重做改什么 → 面试口述版 | 讲**取舍与代价**，不只讲做法 |
+| ③ **改造方案** | `assets/深度模板/改造方案模板.md` | 缺陷（含严重度）→ **改造前链路骨架**（整体调用关系，伪代码）→ 总体思路 → 分阶段（每点含**关键片段**（伪代码/SQL）+ 验收）→ 迁移灰度 → 不变量由谁保证 | **缺陷的唯一归属地**；复用既有资产，不重复建表。**代码讲解要求：交付标准是"照着能讲代码"**——§1 必有改造前链路骨架（写清谁调谁、每步做了什么，可标类名/方法名，**不写路径与行号**）、每个改造点必有「关键片段」（伪代码/SQL，只示形状）；只有观点没有片段即不达标。**产出门槛：深挖浮现的缺口中至少存在一个②加机制/③重构档的改造点才立方案；全是①档补漏的（加缓存/加判断/加隔离/改配置类），在设计复盘"重做改什么"里带一句即可，不单独成文——硬写就是灌水** |
+
+### ① 功能点清单的必备件：主干调用骨架
+
+把整条链路的 N 段主干压成**一段连续伪代码**，每行右侧标注方式（`[锁]` `[幂等]` `[策略]` `[MQ]` `[外调]` `[落库]` `[兜底]` `[履历]` `[通知]` `[隔离]` `[验签]`）；附方式图例（反向索引）。**每个功能点必须能在骨架上找到**（互为索引）。
+
+### ③ 改造方案的取材工具（深入链路时用）
+
+缺陷**不是枚举出来的，是贴着链路走一遍时浮现的**。深挖时用这三把刀看结构，发现的缺口按「机制模式库」比对出改造方向：
+
+| 刀 | 怎么做 |
+|---|---|
+| **按触发者拆链路** | 找「同一行数据被几个触发者改」→ 判断收敛/防重是否单点 |
+| **竞态矩阵** | 「并发场景 × 后果」穷举表：重复回调 / 回调与兜底并发 / 并发退款… |
+| **幂等键清单 + 状态流转图** | 列出链路上所有幂等键并标层级；画状态机——"重复入账"与"状态与事实不符"的发现入口 |
+
+**机制模式库**（"结构性限制 → 可引入机制"对照表，改造方案的取材清单；**只有这一份，不复制**）：
+
+| 结构性限制（发现） | 可引入的机制 / 重构 |
+|---|---|
+| 业务写 + 发消息不原子 | 本地事务表 / Outbox + 投递器（业务与消息同事务，投递可重放） |
+| 兜底任务不可恢复（poll 即删） | 任务表为权威，队列只做加速（宕机可恢复、积压可观测） |
+| 不一致只有日志、无人知 | 一致性异常台账 + 告警 + 处理台（待处理 → 处理中 → 已处理） |
+| 状态靠应用层"猜测" | CAS 条件更新 + 影响行数判定（把判断交给数据库） |
+| 上游码散落多处、口径不一致 | 码字典化：每码标注「是否受理 / 是否终态 / 可重试」，多处共查一份 |
+| "不确定"没有归宿 | 挂起态 + 巡检 + 重放（重放须走同一套分级，因为对方状态可能已变） |
+| 对外调用有副作用却被重复调用 | 幂等键（业务唯一键）+ 冲突当命中 |
+| 资金出去的方向弱于进来 | 对称化：退款补齐同构的锁 / 短路 / 唯一索引 |
+| 重试责任多点（乘法放大） | 重试责任单点 + 显式关闭其他层（应用重试了，MQ 就不重试） |
+| 状态写入早于事实 | 中间态 + 以权威回调驱动终态（不以"发起成功"为准） |
+| 能力只覆盖一条路径 | 铺开：把一个点的分级铺成一张网（全部写类接口统一） |
+| 跨系统没有事务 | 「幂等 + 可重放 + 对账」三件套替代事务 |
+| 关键参数散落、取值无解释 | 参数登记与解释：汇总阈值 / 退避 / 分片并说明取值依据 |
+
+### 改进的三档尺度
+
+| 档 | 做法 | 简历硬度 |
+|:-:|---|:-:|
+| ① 补漏 | 修一个具体的错：加校验、加索引、补 try-catch | ⭐ |
+| ② 加机制 | 引入一个新机制，替代"靠人 / 靠自觉"的现状 | ⭐⭐⭐ |
+| ③ 重构 / 更合理设计 | 改结构本身：隐式判断变显式判定、口径收敛、方向对称化 | ⭐⭐⭐ |
+
+**硬要求：每个缺陷都追问"能不能上升一档"**；改造方案里 ②③ 档应占多数。改进的固定 5 要素：① 结构性限制 ② 机制/方案 ③ 替代了什么 ④ 代价 ⑤ 为什么不用通用方案。
+
+**缺陷严重度**：🔴 资金/数据错误 · 🟠 静默失败或重复调用 · 🟡 卫生与可维护性。
+**边界**：只做系统级结构问题（一致性·幂等·可运营性·可恢复性·职责漂移·口径分散），不做代码风格/坏味道/命名/注释。
+
+## 硬规则（合并版）
+
+| # | 规则 | 为什么 |
+|:-:|---|---|
+| 1 | **深度闸门**：允许简短的伪代码/关键片段（CAS 语句·锁与短路顺序·状态分支·DDL·Lua 脚本）把机制画实——**行数是参考不是硬限，忠实于机制形状优先**；真正禁止的是大段源码摘录、代码块内行号、逐层讲解。**豁免** = 主干调用骨架（技术地图，压成一行一段） | 禁代码会"太空"，贴源码则成"阅读报告" |
+| 2 | **证据真实性**：锚点 `路径:行号`，**必须读过再写**；拿不准标【待确认】 | 错锚点毁掉可信度 |
+| 3 | **只读**：不改被扫项目任何文件（新增产物不算） | — |
+| 4 | **缺陷只进改造方案**：功能点清单与设计复盘不列缺陷表、不标严重度；设计复盘里"承接不住的地方"自然带出即可，不展开成清单 | 价值优先；缺陷集中一处才成体系 |
+| 5 | **改进不停在补漏档；不写通用套话**（"加监控""上分布式事务"）；必须贴合业务的具体语义/表/状态，优先复用既有资产 | ②③ 档才是简历上能写硬的 |
+| 6 | **诚实性**："设计对了但落地不完整"要明说；判断与代码事实不一致处逐条列出；文档写的方案必须回代码验是否落地 | 深度文档可信度的唯一来源 |
+| 7 | **只做被点单的 1–3 个点**；每点先想清楚归哪份文档，不为凑齐三件套而写 | 实测一个功能点 ≈ 1–2 份 20KB 文档 |
+
+## 格式保证
+
+1. **模板外置**：读 `assets/` 对应模板填空。
+2. **机械校验**（与 `value-scan` 共用 `../value-scan/assets/check.ps1`）：
+
+```powershell
+$ck = .agents/skills/value-scan/assets/check.py
+# ① 功能点清单
+python $ck dig <产物> --template .agents/skills/value-dig/assets/深度模板/功能点清单模板.md
+# ② 设计思路与取舍 / ③ 改造方案
+python $ck doc <产物> --template .agents/skills/value-dig/assets/深度模板/<对应模板>.md
+```
+
+**FAIL 必须为 0**；WARN 允许保留但写明原因。
+3. **偏差回写**：被纠正过就回写模板。
+
+## 触发词与落盘
+
+**触发词**：「把这个点写成文档」「把这条链路整理成功能点」「写设计思路与取舍」「出改造方案」。
+**落盘**：`<项目根>/docs/`，与候选清单同目录（可被用户覆盖）。
+
+**上游**：候选清单由 `value-scan` 产出。

skill-workbench/generated-skills/skills/value-dig/assets/价值点报告模板.md

@@ -0,0 +1,76 @@
+# ⟨域⟩ · 价值点报告（S3 产物）
+
+> **用途**：为 S2 勾选出的每个点写**可讲述的轻理由**（默认交付深度）。
+> **上游**：`⟨域⟩-候选价值点.md`（S1）· **勾选来源**：⟨候选清单「闸门状态」节 / 用户消息直接点名⟩
+> **证据快照**：基于 ⟨仓库名⟩ `⟨commit 短号 / 分支⟩`，⟨读取日期⟩。**换版本要重核**。
+> **判据**：**简历行测试**——填不出机制的退回「附录·待定」
+> **路径简写**：`⟨简写⟩/` = `⟨真实路径⟩`（锚点一律用简写前缀）
+
+---
+
+## 每个点 = 7 类内容
+
+> **7 类不是"行数上限"**。关键片段与偏差附录**另有归属，不占这 7 类**。
+> **点编号沿用 S1 的 ★ 编号**（便于与候选清单对照）。
+
+### ★⟨N⟩ · ⟨机制名⟩
+
+| # | 行 | 内容 |
+|:-:|---|---|
+| 1 | **简历行** | 用【⟨机制⟩】解决了【⟨具体问题/场景⟩】，代价是【⟨取舍⟩】 |
+| 2 | **Problem** | ⟨不做会怎样 / 原来的做法会出什么问题⟩ |
+| 3 | **Pattern** | ⟨机制是什么、怎么起作用⟩ |
+| 4 | **Alternatives** | ⟨当时还能怎么做 / 为什么没选⟩ |
+| 5 | **Tradeoffs** | ⟨代价：新增复杂度 · 依赖 · 运维负担⟩ |
+| 6 | **Evidence** | `⟨简写⟩/⟨路径⟩.java:⟨行号⟩` · ⟨可核对的图/表/配置⟩ |
+| 7 | **追问预判** | **问**：⟨高概率追问 1⟩ **答**：⟨一句话⟩<br/>**问**：⟨高概率追问 2（可选，最多 2 条）⟩ **答**：⟨一句话⟩ |
+
+**关键片段 · ⟨片段名⟩**（≤10 行伪代码，把"只有名词"的地方画实）
+
+```
+⟨CAS 语句 / 锁与短路顺序 / 状态分支 / DDL⟩
+```
+
+**事实强度**（可选，用于区分"已核实"与"推断"）
+
+| 结论 | 强度 |
+|---|---|
+| ⟨…⟩ | **已核实**（读过代码） |
+| ⟨…⟩ | **推断**（未核实，需人工确认） |
+
+⟨重复上面 3 块，每点一节⟩
+
+---
+
+# 附录 · 与候选清单的偏差
+
+> **实读代码后必须回头核对 S1 的表述**。S1 是"候选"不是"事实"——**偏差本身就是高价值材料**（往往是简历上最硬的一条）。
+
+| # | S1 怎么写的 | 代码事实 | 处理 |
+|:-:|---|---|---|
+| 1 | ⟨S1 的原文⟩ | ⟨实读结果 + `路径:行号`⟩ | ⟨纠正 / 标【待确认】/ 升级为独立价值点⟩ |
+
+---
+
+# 报告尾 · 推荐组合
+
+> **先讲哪 3 个**——给"追问密度最高 / 最能体现设计能力"的组合。**内容列必须是上面已写的 ★ 编号。**
+
+| 组合 | 内容（★ 编号） | 适合 |
+|---|---|---|
+| **主线（推荐）** | ⟨★N + ★M⟩ | ⟨最能体现什么能力，追问密度最高⟩ |
+| **完整版** | ⟨★1 + ★2 + ★3 + ★4 + ★5⟩ | ⟨讲清完整链路⟩ |
+| **差异化** | ⟨★K⟩ | ⟨少数人会讲的点⟩ |
+
+**建议讲述顺序**：⟨★N → ★M → ★K，并说明为什么这个顺序⟩
+
+---
+
+# 附录 · 待定
+
+> 简历行**填不出机制**的点落在这里（**不删除**——防灌水，也不误杀）。
+> ⚠️ **闸门二只在本阶段生效**：进入 S4 的点若机制仍未定，改为在其小节头部标 **【待确认：机制未定】**，**不在 S4 新建「待定」节**。
+
+| # | 点 | 为什么填不出 | 需要补什么才能定 |
+|:-:|---|---|---|
+| 1 | | | |

skill-workbench/generated-skills/skills/value-dig/assets/深度模板/功能点清单模板.md

@@ -0,0 +1,174 @@
+# ⟨域⟩ 域 · 功能点清单
+
+> **用途**：把「⟨链路主题⟩」这条链路按其设计文档与代码实读整理成功能点
+> **流程**（与上游一致）：**先记录功能点 → 定稿文档 → 再讨论最佳设计与取舍**
+> **上游**：`⟨域⟩-候选价值点.md`（S1）+ 勾选结果（S2）
+> **素材来源**：`⟨wiki/xxx-spec.md⟩`（⟨N⟩ 行）+ `⟨仓库名⟩` 代码实读
+> **路径简写**：`⟨简写1⟩/` = `⟨真实路径⟩`；`⟨简写2⟩/` = `⟨真实路径⟩`
+
+---
+
+# 一、链路总览
+
+**一句话**：⟨统领句——给出这条链路的**主线判断**，不是复述流程⟩
+
+```mermaid
+flowchart TD
+    A["⟨起点⟩"] --> B["⟨★ 机制节点⟩"]
+    B --> C{"⟨分支⟩"}
+    C -->|"⟨路径⟩"| D["⟨汇合点 / 分级发生地⟩"]
+    C -->|"⟨路径⟩"| D
+    D --> E{"⟨结果类型⟩"}
+    E -->|"⟨可逆⟩"| F["⟨处置⟩"]
+    E -->|"⟨不确定⟩"| G["⟨处置⟩"]
+```
+
+⟨可选⟩**关键差异表（设计的核心）**
+
+| ⟨维度⟩ | ⟨取值1⟩ | ⟨取值2⟩ | ⟨取值3⟩ |
+|---|---|---|---|
+| ⟨例：对方结果⟩ | | | |
+| ⟨例：可逆性⟩ | | | |
+| ⟨例：处置⟩ | | | |
+
+---
+
+## 主干调用骨架（一眼看清哪一步用了什么方式）
+
+> **这是"整条链路的技术地图"**——把 N 段主干压成**一段连续伪代码**，每行标注**用了什么方式**（`[锁]` `[幂等]` `[策略]` `[MQ]` `[兜底]` …）。
+> 局部片段回答"一个机制长什么样"，这一段回答"**哪些地方用了什么**"，以及**哪些地方本该有兜底却没有**。
+
+```java
+// ═══ ① ⟨阶段名⟩ ═══
+⟨方法名⟩():  ⟨动作⟩                                     // [锁]
+             ⟨动作⟩                                     // [幂等]
+             ⟨动作⟩                                     // [策略]
+             ⟨动作⟩                                     // [外调]
+
+// ═══ ② ⟨阶段名⟩ ═══
+⟨方法名⟩():  ⟨动作⟩                                     // [验签]
+             ⟨动作⟩                                     // [MQ]
+             ⟨动作⟩                                     // [落库]
+
+// ═══ ③ ⟨兜底 / 失败处置⟩ ═══
+⟨方法名⟩():  ⟨动作⟩                                     // [兜底]
+             ⟨动作⟩                                     // [重试] 只重超时
+             ⟨动作⟩                                     // [履历]
+```
+
+**方式图例（反向索引：一种方式出现在哪些地方）**
+
+| 标记 | 方式 | 出现在 |
+|---|---|---|
+| `[锁]` | ⟨分布式锁（注解式 / Redisson）⟩ | ⟨…⟩ · ⟨…⟩ |
+| `[幂等]` | ⟨状态短路 + CAS + 一次性消费⟩ | ⟨…⟩ · ⟨…⟩ |
+| `[策略]` | ⟨策略模式 + 工厂⟩ | ⟨…⟩ |
+| `[MQ]` | ⟨Kafka⟩ | ⟨…⟩ |
+| `[兜底]` | ⟨延时队列 + XXL-Job⟩ | ⟨…⟩ |
+| `[重试]` | ⟨`@Retryable`（**只重超时**）⟩ | ⟨…⟩ |
+| `[履历]` | ⟨DB 台账⟩ | ⟨…⟩ |
+| `[验签]` | ⟨网关签名⟩ | ⟨…⟩ |
+| `[隔离]` | ⟨try-catch / 线程池⟩ | ⟨…⟩ |
+| `[外调]` / `[落库]` / `[通知]` | ⟨外部系统调用 / DB 写 / 站内信⟩ | 全链路 |
+
+> **这张骨架的两个用处**：① **评审时一眼看清技术分布**（⟨锁 3 处、幂等 5 处、兜底 4 处⟩）；② **横向对比**"同样的机制在别处有没有用"。
+
+---
+
+# 二、功能点（⟨N⟩ 个）
+
+> 每个点：**核心内容** / **这个点在讲什么** / **一句话价值** / **图** / **关键片段（≤10 行伪代码）** / **关键表与字段** / **关键做法与证据**。
+> **段落式**，不要压成表格（"做了什么"常是 5–7 条，塞进单元格必然被简化）。
+
+## ① ⟨功能点名⟩ ⭐⭐⭐⭐⭐
+
+**核心内容**：⟨1 句，把"形状"说清（一把锁 + 三级短路 + 一条条件更新）⟩
+
+**这个点在讲什么**
+
+- **业务场景**：⟨谁在什么时刻触发了什么，为什么这事难；点出"同一时刻还有谁在改同一行数据"⟩
+- **做了什么**（⟨用一句话概括做法⟩）：
+  1. ⟨…⟩；
+  2. ⟨…⟩；
+  3. ⟨…⟩。
+- **只把 fail 留给"我真的还没处理"**：⟨边界在哪⟩（若适用）
+- **临界场景**：⟨并发 / 乱序 / 迟到时的行为⟩（若适用）
+- **解决了什么问题**：⟨不做会怎样⟩
+
+**一句话价值**：⟨说清"判断权 / 控制权"落在谁手里⟩
+
+**图 · ⟨图名⟩**
+
+```mermaid
+flowchart TD
+    A["⟨入口⟩"] --> B{"⟨判断⟩"}
+    B -->|"⟨…⟩"| B1["⟨抢不到锁：直接回 success，让给持锁方⟩"]
+    B -->|"⟨…⟩"| C["⟨动作⟩"]
+    C --> D["⟨落库⟩"]
+```
+
+**关键片段 · ⟨片段名⟩**（伪代码，只示形状）
+
+```
+⟨CAS 语句 / 锁与短路顺序 / 状态分支 / DDL，≤10 行⟩
+```
+
+**关键表与字段**
+
+| 表 | 关键字段 | 说明 |
+|---|---|---|
+| `⟨表名⟩` | `⟨字段⟩` · **`⟨关键字段⟩`** | ⟨说明⟩ |
+
+**关键做法与证据**
+
+| 做法 | 证据 |
+|---|---|
+| ⟨做法⟩ | `⟨简写⟩/⟨路径⟩.java:⟨行号⟩` |
+| ⟨做法⟩ | 同上 `:⟨行号⟩` |
+
+⟨重复 ① 的结构，每个功能点一节⟩
+
+---
+
+# 三、推荐组合
+
+| 组合 | 内容 | 适合 |
+|---|---|---|
+| **主线（推荐）** | ⟨① + ⑤⟩ | ⟨最能体现什么能力，追问密度最高⟩ |
+| **完整版** | ⟨① + ② + ③ + ④ + ⑤⟩ | ⟨讲清完整链路⟩ |
+| **差异化** | ⟨④⟩ | ⟨少数候选人会讲的点⟩ |
+
+---
+
+# 四、设计亮点
+
+## 4.1 亮点（面试可直接讲）
+
+| # | 亮点 | 价值 |
+|:-:|---|---|
+| 1 | ⟨亮点⟩ | ⟨价值——**逐条对着旧实现的病灶**，不是堆框架⟩ |
+| 2 | | |
+
+> **本模板不设缺陷表**：缺陷、严重度与改进方案统一在《⟨主题⟩-改造方案.md》中呈现。深挖过程中发现的结构缺口先记到工作笔记，写改造方案时再展开。
+
+---
+
+# 附录 A · ⟨状态 / 结果类型⟩速查
+
+| ⟨类型⟩ | 含义 | 终态？ | ⟨处置1⟩ | ⟨处置2⟩ | 重试 |
+|---|---|:-:|:-:|:-:|---|
+| `⟨枚举值⟩` | | ✅ / ❌ | | | |
+
+# 附录 B · 参数速查
+
+| 参数 | 值 | 出处 |
+|---|---|---|
+| ⟨锁 leaseTime⟩ | | `⟨路径⟩.java:⟨行号⟩` |
+| ⟨重试次数⟩ | | |
+| ⟨延时 / 超时⟩ | | |
+
+# 附录 C · 关键类索引
+
+| 类 | 角色 |
+|---|---|
+| `⟨类名⟩` | ⟨在链路里的角色⟩ |

skill-workbench/generated-skills/skills/value-dig/assets/深度模板/改造方案模板.md

@@ -0,0 +1,233 @@
+# ⟨主题⟩ · 改造方案
+
+> **背景**：现状问题登记在本文第 0 节（**缺陷唯一归属地**）；复盘视角的"承接不住"见《⟨主题⟩-设计思路与取舍.md》第 5 节
+> **目标**：⟨把「X」从**一条路的设计**，变成**覆盖全部写接口的事实**⟩
+> **边界**：⟨不改省侧协议、不引入分布式事务（改造点全在本服务内）；DDL 只列关键字段，完整建表脚本另出⟩
+> **与其它方案的关系**：⟨一致性异常台账**复用**《⟨其它⟩-改造方案.md》的 `⟨表名⟩`，**不重复建表**，只新增 `⟨列/取值⟩`⟩
+> **依据**：全部改造点均**对应代码中已核实的缺陷，非推测**
+> **取材**：深挖链路时发现的结构性缺口，按 `value-dig` SKILL 的「机制模式库」（结构性限制 → 可引入机制）比对出改造方向；每个缺陷追问"能否从补漏上升到加机制/重构"
+> **代码讲解要求（必读）**：本文交付标准是"**照着能讲代码**"——① §1 先给**改造前链路骨架**（整体调用关系，用伪代码写清"谁调谁、每一步做了什么"，可标类名/方法名，**不写文件路径与行号**）；② **每个改造点**必带「**关键片段**」（伪代码 / SQL，只示形状、不贴源码）。密度基准：`docs/order-改造方案.md`
+> **产出门槛**：缺口中至少存在一个**②加机制 / ③重构**档的改造点（更好设计、重构、引入中间件级）才立本文档；全是①档补漏（加缓存/加判断/加隔离/改配置）的**不产出**——在设计复盘"重做改什么"小节记录即可
+
+---
+
+## 0. 现状问题登记（缺陷唯一归属地）
+
+> 功能点清单与设计复盘**不承载缺陷表**；深挖中发现的问题全部登记在此，后文逐条消化。
+
+**严重度**：🔴 资金/数据错误 · 🟠 静默失败或重复调用 · 🟡 卫生与可维护性
+
+| # | 缺陷 | 证据 | 后果 | 严重度 |
+|:-:|---|---|---|:-:|
+| 1 | ⟨缺陷⟩ | ⟨可核对的事实：行为 / 字段 / 日志⟩ | ⟨后果⟩ | 🔴 |
+| 2 | ⟨…⟩ | | | 🟠 |
+| 3 | ⟨…⟩ | | | 🟡 |
+
+**归纳**：这些不是孤立的 bug，而是 **⟨N⟩ 处结构性缺口**：
+
+1. **⟨缺口一⟩** —— ⟨…⟩；
+2. **⟨缺口二⟩** —— ⟨…⟩；
+3. **⟨缺口三⟩** —— ⟨…⟩。
+
+---
+
+## 1. 总体思路
+
+**改造前链路骨架**（先定位"改的是链路的哪一段"——用伪代码写清谁调谁、每一步做了什么）：
+
+```java
+⟨入口类#方法⟩()
+  → ⟨A类#方法⟩()          // 这一步做了什么（对应缺陷 #1）
+  → ⟨B类#方法⟩()
+  → ⟨C类#方法⟩()          // 对应缺陷 #3
+```
+
+所以改造是做 N 件事，**而不是调参数**：
+
+1. **⟨把一个点的分级 → 铺成一张网⟩**
+2. **⟨把「不确定」从日志提升为一等状态⟩**
+3. **⟨把状态推进的时机对齐到权威事实⟩**
+
+```mermaid
+flowchart TB
+    subgraph BEFORE["改造前"]
+        B1["⟨…⟩"] --> B2["⟨…⟩"]
+        B3["⟨…⟩"] --> B4["⟨…⟩"]
+    end
+    subgraph AFTER["改造后"]
+        A1["⟨…⟩"] --> A2["⟨…⟩"]
+        A2 --> A3["⟨…⟩"]
+        A4["⟨…⟩"] --> A5["⟨…⟩"]
+    end
+```
+
+---
+
+## 2. 阶段一 · ⟨阶段主题：先说止血/可见⟩
+
+> 成本最低、收益最大，**优先做**。⟨N⟩ 处改动都只动本服务内部。
+
+### 2.1 ⟨改造点名⟩（P0，最重要）
+
+- **现状**：⟨…⟩（对应第 0 节缺陷 #⟨N⟩）。
+- **后果（真金白银）**：⟨…⟩ 这**违反了 ⟨不变量一⟩**。
+- **改造**：⟨…⟩
+
+**关键片段 · ⟨片段名⟩**（伪代码 / SQL，只示形状）
+
+```sql
+⟨改造后的语句或结构；与改造前的旧写法形成对照⟩
+```
+
+| ⟨对象⟩ | ⟨写/读⟩ | 可逆性 | 处置 |
+|---|---|---|---|
+| ⟨接口/动作⟩ | 写 | ⟨拒绝可逆、超时不可逆⟩ | ⟨…⟩ |
+
+- **注意**：⟨切换后**必须同步补"超时不可逆"的判断**，否则只是把"归档超时 → 退款"换成"归档超时 → 抛异常 → 同样退款"，问题原地不动⟩。
+
+```mermaid
+flowchart TD
+    A["⟨入口⟩"] --> B{"⟨判断⟩"}
+    B -->|"改造后"| C{"分类"}
+    B -->|"现状"| Z["⟨旧行为⟩"]
+    C -->|"⟨可逆⟩"| D["⟨处置⟩"]
+    C -->|"⟨不确定⟩"| E["⟨处置⟩"]
+```
+
+### 2.⟨N⟩ ⟨改造点名⟩
+
+- **现状**：⟨…⟩（对应第 0 节缺陷 #⟨N⟩）
+- **改造**：⟨…⟩ **原则：⟨异常类型就是后果分类的载体，不能在中间被抹平⟩。**
+- **验收**：⟨人为造一次 ⟨场景⟩，应出现 ⟨可观测结果⟩⟩。
+
+**关键片段 · ⟨片段名⟩**
+
+```java
+⟨改造后的分支形状，只示形状⟩
+```
+
+### 2.⟨N⟩ 阶段一验收标准
+
+| 指标 | 目标 |
+|---|---|
+| ⟨…⟩ | ⟨100% 不产生 ⟨错误动作⟩，转 ⟨正确处置⟩⟩ |
+| ⟨人为造 X⟩ | ⟨出现可观测的 ⟨证据⟩⟩ |
+
+---
+
+## 3. 阶段二 · ⟨阶段主题：再说可靠/对称/一等状态⟩
+
+> 阶段一保证"不再做错"，阶段二保证"⟨挂起能被收走⟩"。
+
+### 3.1 ⟨幂等键改造⟩
+
+- **现状**：⟨没有幂等键 → 可被重复执行；MQ `maxRetry=3` 在异常路径上会重复调用外部⟩（对应缺陷 #⟨N⟩）
+- **改造**：⟨唯一索引 · 冲突当幂等命中 · 语义："同一 X + 同一动作 = 只允许一次对外调用"⟩
+- **迁移**：⟨先查存量重复，治理后再加索引⟩
+
+**关键片段 · 索引 + 冲突即命中**
+
+```sql
+ALTER TABLE ⟨表名⟩ ADD UNIQUE KEY ⟨uk名⟩ (⟨列⟩, ⟨列⟩);
+```
+
+```java
+try { ⟨对外调用⟩; }
+catch (DuplicateKeyException e) { return; }   // 已执行过 → 直接返回，不再调外部
+```
+
+### 3.2 ⟨挂起态 + 巡检⟩
+
+- **现状**：⟨…⟩（对应缺陷 #⟨N⟩）
+- **改造**：
+  1. **⟨新增挂起态⟩**，与"失败""成功"并列，**不占用失败的语义**；
+  2. **巡检任务**（⟨XXL-Job⟩）按"距离挂起时长"分级：⟨<1h 自动重放一次 / 1–24h 告警 / >24h 人工队列⟩；
+  3. 重放走**同一套分级链路**（不新开代码路径）。
+
+**关键片段 · ⟨片段名⟩**
+
+```java
+⟨挂起态写入 / 巡检取单的形状⟩
+```
+
+```mermaid
+flowchart TD
+    A["⟨不确定⟩"] --> B["⟨挂起 + 台账⟩"]
+    B --> C["告警"]
+    B --> D["巡检任务"]
+    D --> E{"挂起时长"}
+    E -->|"⟨短⟩"| F["自动重放"]
+    E -->|"⟨中⟩"| G["升级告警"]
+    E -->|"⟨长⟩"| H["人工队列"]
+```
+
+**关键设计：重放不是"再调一次接口"，而是"重新走一遍分级"。** 因为对方的状态可能已经变了，重放必须能得出"成功"这个结论。
+
+### 3.⟨N⟩ ⟨改造点名⟩
+
+| `⟨anomaly_type⟩` 取值 | 触发场景 | 处置方向 |
+|---|---|---|
+| `⟨…⟩` | | |
+
+- **收益**：⟨两侧的失败**进同一张台账、走同一套告警和处理台**——运维只需要看一个地方。**这是"复用"而不是"新建"的价值。**⟩
+
+### 3.⟨N⟩ 阶段二验收标准
+
+| 指标 | 目标 |
+|---|---|
+| ⟨重复调用外部⟩ | 0 次 |
+| ⟨挂起单⟩ | 100% 台账可见 + 100% 被巡检捞到 |
+
+---
+
+## 4. 阶段三 · ⟨阶段主题：最后收口卫生问题⟩
+
+| # | 改什么 | 现状证据（缺陷 #⟨N⟩） | 成本 |
+|:-:|---|---|---|
+| 1 | ⟨…⟩ | ⟨可核对的事实⟩ | 低 |
+| 2 | ⟨…⟩ | | 低 |
+
+**⟨某条不是文档工作，是防错工作⟩**：⟨文档漂移会让后来人**按错误的图改代码**，成本远高于改文档。⟩
+
+---
+
+## 5. 实施顺序与成本收益
+
+| 阶段 | 内容 | 成本 | 解决的根问题 | 关键收益 |
+|:-:|---|---|---|---|
+| 一 | ⟨…⟩ | 低 | ⟨…⟩ | **不再出错** |
+| 二 | ⟨…⟩ | 中 | ⟨…⟩ | **不确定可运营** |
+| 三 | ⟨…⟩ | 低 | 卫生与可维护性 | 可观测与可维护 |
+
+**顺序逻辑**：先修**会花错钱**的（阶段一），再修**会重复调用外部系统 / 卡住看不见**的（阶段二），最后才是卫生（阶段三）。
+
+---
+
+## 6. 迁移与灰度
+
+1. **⟨逐项切⟩**：先切**风险最高、问题最实**的 ⟨X⟩，观察一周无异常再切 ⟨Y⟩；每次切换**只改一个调用点**，便于回滚。
+2. **⟨新增状态先"只记录不流转"⟩**：先写台账 + 告警**观察一周**，确认没有误报，再打开自动重放。
+3. **⟨索引先查存量⟩**：先排查存量重复；加索引后**观测冲突命中次数**——这个数就是"原设计漏掉的重复调用次数"。
+4. **回滚**：全部改造以"**新增状态 + 新增列 + 开关**"方式落地，回滚只需关开关/停调度，**不动存量数据**。
+
+---
+
+## 7. 改造后：⟨N⟩ 条不变量由谁保证
+
+| 不变量 | 改造前 | 改造后 |
+|---|---|---|
+| **⟨不变量一⟩** | ⟨只有一条路成立；某路径会被错退⟩ | ⟨全部写类接口统一分类⟩ |
+| **⟨不变量二⟩** | ⟨只有一行日志，库里无痕⟩ | ⟨挂起态 + 台账 + 巡检 + 重放⟩ |
+| **⟨不变量三⟩** | ⟨实际只有两态（超时被降级抹平）⟩ | ⟨异常类型不被中间层改写⟩ |
+
+---
+
+## 附：与《⟨其它⟩-改造方案.md》的关系
+
+| 项 | ⟨其它侧⟩ | ⟨本文⟩ |
+|---|---|---|
+| ⟨一致性异常台账⟩ | **建** `⟨表名⟩` | **复用**，只加取值 |
+| ⟨Outbox⟩ | **建** `⟨表名⟩` | **复用同表**，`⟨biz_type⟩` 区分 |
+| ⟨幂等⟩ | ⟨…⟩ | ⟨…⟩ |
+
+**两边的根因是同一个**：⟨设计了机制，但**没有为"需要人介入"这个信号建自动出口**⟩。所以两套改造共用一套台账与告警，是**结构上的必然，而不是为了省事**。

skill-workbench/generated-skills/skills/value-dig/assets/深度模板/设计思路与取舍模板.md

@@ -0,0 +1,206 @@
+# ⟨主题⟩ · 设计思路与取舍（复盘）（S4 产物 ②）
+
+> **视角**：第一人称复盘——**我拿到「⟨需求名⟩」这个需求时，是怎么想、怎么设计、怎么取舍、预判会遇到什么问题的**。贴合现有实现，末尾给改进建议与可直接口述的版本。
+> **配套文档**：功能点见同目录《⟨主题⟩-功能点清单.md》；⟨可选的关联文档⟩
+> **说明**：文中「我会这样想」是设计时的推理；「实际做法」是代码里的真实实现，**两者不一致处必须标出**。
+> **路径简写**：`⟨简写⟩/` = `⟨真实路径⟩`
+
+---
+
+## 0. 我拿到需求，先不写代码：把问题定义清楚
+
+**需求的一句话**：⟨…⟩
+
+**我第一件事是承认 N 个事实**，它们决定了后面所有设计：
+
+1. **⟨例：对方的回答不是二元的⟩。** ⟨…⟩
+2. **⟨例：几种失败的"可逆性"不同⟩。** ⟨…⟩
+3. **⟨例：我没法从"失败"这个现象本身推出可逆性⟩。** ⟨…⟩
+
+**由此我定下 N 条不变量（当成验收标准）**：
+
+- **不变量一**：⟨例：只有确定对方没接单才退款⟩——⟨为什么⟩；
+- **不变量二**：⟨例：不确定的失败不能当成失败处理⟩——⟨为什么⟩；
+- **不变量三**：⟨例：每一种失败都必须有归属⟩——⟨为什么⟩。
+
+**再看 N 个我不能改变的前提**：⟨省侧是权威 · 对外调用有副作用 · 没有跨系统事务 · …⟩
+
+**结论**：⟨这不是"加个 try-catch 再套个重试框架"的需求，而是「把异常翻译成后果」的需求。⟩——**这句是我做取舍时反复回到的锚点。**
+
+---
+
+## 1. 我怎么拆这个需求
+
+**第一刀，我按「⟨拆解维度⟩」拆，不按「⟨被否决的维度⟩」拆。**
+
+| 为什么否决另一个维度 | ⟨例：按商品类型拆会得到三块，但三种商品的前置动作不同、汇合点却是同一个；各写一套会得到三份可能走偏的代码⟩ |
+|---|---|
+
+拆完是 ⟨N⟩ 条路 + ⟨N⟩ 个汇合点：
+
+| 路径 | ⟨前置动作⟩ | ⟨性质⟩ | 风险 |
+|---|---|---|---|
+| ⟨…⟩ | | 异步 / 同步 | |
+
+**第二刀，我找「⟨关键定位决策⟩」，这是本需求最关键的一个决策。**
+
+**我的判断是**：⟨…⟩。理由：⟨只有那一层同时拿得到 X 和 Y；再往上一层只能看到一个已被包装过的异常，原始信息已经丢了⟩。
+
+**实际做法与我的判断是否一致**：⟨是 / 否⟩，证据 `⟨路径:行号⟩`。
+
+**这个决策的代价**：⟨例：调用层要维护两套调用方式；推广不全会造成覆盖面缺口（实际就漏了）⟩。
+
+---
+
+## 2. 我的设计主线：⟨一句话概括主线⟩
+
+⟨这是我做的最核心的一个决定：不给 A/B/C 各写一套处理，而是让它们沿一条固定的链往下走，每层只做一件事。⟩
+
+```
+① ⟨层名（职责）⟩ → ② ⟨层名（职责）⟩ → ③ ⟨层名（职责）⟩ → ④ ⟨层名（职责）⟩
+```
+
+**⟨N⟩ 层不是我拍脑袋凑的，是从"上一版为什么会漏"反推出来的**——每层都对着一个旧实现的具体病灶：
+
+| 层 | 旧实现的病灶 | 我的做法 | 为什么必须在这一层做 |
+|:-:|---|---|---|
+| ① | | `⟨路径:行号⟩` | ⟨信息只在最底层存在，越往上越不可恢复⟩ |
+| ② | | | |
+| ③ | | | |
+| ④ | | | |
+
+```mermaid
+flowchart TD
+    A["⟨入口⟩"] --> B["① ⟨层⟩"]
+    B --> C{"② ⟨层⟩"}
+    C -->|"⟨…⟩"| D["③ ⟨层⟩"]
+    C -->|"⟨…⟩"| E["③ ⟨层⟩"]
+    D --> F["④ ⟨归集⟩"]
+    E --> F
+    F -->|"⟨可逆⟩"| G["⟨处置⟩"]
+    F -->|"⟨不确定⟩"| H["⟨处置⟩"]
+```
+
+### 2.1 ⟨N⟩ 重判断，才是这个设计的真正内容（标题按实际重数写，如「三重判断…」）
+
+> 比"N 层"更重要的是**层里做的判断**——它们才是经验，层只是载体。
+
+**判断一：⟨…⟩**
+
+⟨用收益 × 概率算的：…⟩ **关键点是"不做什么"比"做什么"更难做对**——⟨因为框架默认什么都做⟩。
+
+**判断二：⟨…⟩**
+
+⟨…⟩ **代价必须自己扛**：⟨你关掉了 X，就必须自己承担 Y 的责任。⟩
+
+**判断三：⟨…⟩**
+
+⟨…⟩ **为什么"⟨反面做法⟩"是错的**：⟨…⟩
+
+**还有一条我特意保留的例外**：⟨…⟩——因为 ⟨…⟩。
+
+### 2.2 ⟨独立工具/组件名⟩ 为什么要写成一个独立⟨工具/组件⟩（若无可删本节）
+
+⟨它看着简单，但它是整个 ⟨机制⟩ 的地基——判错一次，方向就错，后面全走偏。⟩
+
+1. **精确匹配** ⟨…⟩；
+2. **兜底模糊匹配** ⟨…⟩；
+3. **逐层剥 `cause`**——⟨因为异常常被框架层层包装，真实原因往往在第三、四层⟩。
+
+**这里的取舍我很清楚**：⟨选了"宁可多试一次"——因为重试的成本（多一次调用）远低于漏重试的成本（一单卡死）⟩。
+
+---
+
+## 3. 逐环节决策复盘
+
+| # | 当时的问题 | 我的选择 | 为什么 | 代价 / 风险 |
+|:-:|---|---|---|---|
+| 1 | ⟨…⟩ | | | |
+| 2 | | | | |
+| 3 | | | | |
+| … | | | | |
+
+> **代价/风险列不可空**——只讲选择不讲代价，就等于没做取舍。
+
+---
+
+## 4. 我预判会遇到的问题（拿到需求时就能想到的）
+
+1. **⟨…⟩。** ⟨…⟩
+2. **⟨…⟩。** ⟨…⟩
+3. **⟨…⟩。** ⟨这是我设计时预判到了却仍然漏掉的一条⟩
+
+---
+
+## 5. 我做对的 ⟨N⟩ 件事 / 承接不住的 ⟨N⟩ 件事
+
+**做对的**
+
+1. **⟨…⟩**——⟨为什么它最有价值；它是从业务语义推出来的，不是从技术模式套出来的⟩。
+2. **⟨…⟩**——⟨…⟩
+3. **⟨…⟩**——⟨方向是对的，只是推广范围不够⟩
+
+**承接不住的**
+
+1. **⟨…（最严重）⟩**——⟨后果；这是"设计对了但落地不完整"的典型案例⟩。
+2. **⟨…⟩**
+3. **⟨…⟩**
+
+---
+
+## 6. 如果让我重做，我会改什么（按性价比排序）
+
+> 复盘视角只给**优先级判断**；分阶段展开、验收标准与灰度见《⟨主题⟩-改造方案.md》，此处不重复。
+
+| 优先级 | 改什么 | 为什么 | 成本 | 收益 |
+|:-:|---|---|---|---|
+| **P0** | | ⟨**真金白银 / 会花错钱**⟩ | 低 | |
+| **P1** | | | 中 | |
+| **P2** | | | | |
+| **P3** | | ⟨卫生问题⟩ | | |
+
+**一句话排序逻辑**：先修**会花错钱和会重复调用外部系统的**（P0/P1），再做**让"不确定"可运营**（P1/P2），最后才是卫生问题（P3）。**因为前两类是"静默地把事情做错"，后者只是"做得不够漂亮"。**
+
+---
+
+## 7. 这套设计里可以复用的方法论
+
+1. **⟨先判"可逆性"，再决定"要不要补偿"。⟩** ⟨任何跨系统写操作都适用…⟩
+2. **⟨异常分层翻译：真相层 → 重试层 → 履历层 → 归集层。⟩** ⟨每层只做一件事，且必须在能拿到信息的最高层把信息捞住⟩
+3. **⟨重试责任单点。⟩** ⟨否则是乘法关系，不是加法⟩
+4. **⟨"不确定"必须是一等状态。⟩** ⟨否则会退化成一行日志，等于不存在⟩
+5. **⟨分级的上限取决于覆盖面，不是取决于精细度。⟩** ⟨一条路上做四层分级，不如四条路上各做一层⟩
+
+---
+
+## 8. 附：面试口述版
+
+### 8.1 一分钟版（先讲骨架）
+
+> 「⟨需求一句话⟩。我的判断是：⟨核心判断⟩。所以我不能只写 try-catch，得**把 ⟨X⟩ 翻译成 ⟨Y⟩**。
+>
+> 设计上是 N 层：⟨逐层一句话⟩。调用方只做一件事：⟨…⟩。」
+
+### 8.2 三分钟版（加取舍与代价）
+
+在上一段基础上补三段：⟨取舍一（最看重的一点）+ 它的代价⟩ · ⟨取舍二 + 难在哪⟩ · ⟨要坦白的一点（覆盖面 / 落地不完整）⟩。
+
+### 8.3 追问预判（问题 → 一句话答）
+
+| 追问 | 答 |
+|---|---|
+| ⟨为什么…？⟩ | ⟨一句话⟩ |
+| ⟨既然…，那…？⟩ | ⟨一句话，含"坦白说没有"这类诚实回答⟩ |
+| ⟨这套设计最大的风险？⟩ | ⟨一句话⟩ |
+
+---
+
+## 附：与代码的对照说明
+
+| 本文的判断 | 代码事实 | 是否一致 |
+|---|---|---|
+| ⟨分级放最底层⟩ | `⟨路径:行号⟩` | ✅ 一致，但**未推广** |
+| ⟨只重超时⟩ | `⟨路径:行号⟩` | ✅ 一致 |
+| ⟨…⟩ | | ⚠️ 部分一致 |
+
+> **诚实性要求**：本文的判断与代码事实**不一致处必须逐条列出**——这是这份文档可信度的来源。

skill-workbench/generated-skills/skills/value-scan/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: value-scan
+description: Use when the user wants to inventory the mechanisms worth talking about in code that is already delivered — "盘点这个域/模块的价值点", "扫一下 order 域有什么值得讲的", "提取功能点", "这个项目有什么值得讲的设计", or when interview/resume material must be reconstructed backwards from an existing module. Read-only — never modifies the scanned project. Stops at the human selection gate; deep write-up is a separate skill.
+---
+
+# value-scan · 价值点盘点（广度枚举）
+
+## 一句话
+
+从**已交付的代码**里，逆向枚举出**值得讲的机制点**，交人勾选后**停下**。
+
+**三条核心原则**
+
+1. **agent 判不了"价值"**——判据不是分类体系，而是**简历行填空测试**。
+2. **价值优先，本阶段不找缺陷。** 缺陷是深入链路时自然浮现的副产物，归 `value-dig`。
+3. **只读。** 不修改被扫描项目的任何文件。
+
+## 流程
+
+```
+S0 定范围 → S1 枚举 → S2 勾选【终点：产出清单后必须停】
+                          ↓（人勾选后）
+                       value-dig（轻理由 → 设计复盘 / 功能点 / 改造方案）
+```
+
+| 需求 | 该用 |
+|---|---|
+| 盘点 / 扫一遍 / 提取候选价值点 | **本 skill** |
+| 把选中的点写成深度文档 | `value-dig` |
+| 找 bug、修缺陷 | `diagnose` |
+
+## S0 · 定范围
+
+- **快路**：仓库已有域清单（`.aspirecode/sdd/rules.md` §9、`pom.xml`、`wiki/` 目录）→ 直接读。
+- **慢路**：陌生仓库 → 按接口路径前缀、`-api` Feign 接口名、controller 清单切出能力面，一次一个 package。
+- 范围由**人给定**（一个域/模块），不一次扫全库。
+
+**域是入口锚点，不是物理边界。** 完整链路往往跨模块，用两头夹的办法拼：
+
+- **聚合层（web）定链路形状**：controller / Kafka consumer / XxlJob / callback 四类入口全在聚合层，且分包与路径自带业务语义（`/consumer/fulfillment/`、topic 名、请求路径）——从这里正向切出"有哪些触发者、哪些链路"。MQ 消费、定时任务这类**非 Feign 入口**靠反推找不到。
+- **原子域挖机制内容**：锁/幂等/状态机等机制本体大多在原子域的 service 实现，聚合层只有编排——读实现要去原子域。
+- **中间用调用图接**（`gitnexus_route_map` / `gitnexus_cypher`）；被驱动型域也可用"谁 import 了我的 Feign 接口"反查调用方作兜底。
+- 只读链路经过的路径，不通读途径模块。
+
+## S1 · 枚举
+
+### 取材顺序（信噪比递减）
+
+| 顺序 | 来源 | 备注 |
+|:-:|---|---|
+| 1 | `wiki/*.md`、`.claude/docs/**`、`devflow/projects/**` | 先读「设计说明类」，后读「问题分析类」——先读问题分析会把清单带成缺陷导向 |
+| 2 | `git log`：`feat(...)` / `refactor(...)`、带单号、单次大改动 | 有意识的改动藏着设计意图 |
+| 3 | `gitnexus_query` / `gitnexus_route_map` | 用图查结构，不读全文 |
+| 4 | 代码结构统计 + 关键字 grep（锁/重试/MQ/Job/条件更新/状态机/延时/对账） | 只做清单式定位，不通读代码 |
+
+> ⚠️ 读完文档必须回代码验一遍"文档写的方案是否落地"。**"文档 vs 代码分叉"本身就是高价值点**。
+
+### 怎么看结构：按「触发者」拆链路
+
+不按业务功能拆，按**谁触发**拆：找出「**同一行数据被几个触发者改**」（如回调/查单/取消都改同一行支付流水）——收敛点多半就是机制所在。通常 1–4 条链路，被驱动型模块可到 5–6 条（超过要写一句为什么）。
+
+每条链路挂 1–4 个机制节点。**候选颗粒度 = 机制/能力**，不是注解、类、配置项——"用了 `@LockAction`、有 4 个 handler"是实现清单；跨 ≥2 个写类入口或 ≥2 张表的才够"机制"。
+
+### 判据 · 简历行测试
+
+**一级 · 准入（三条硬标准，全过才进清单）**
+
+| 标准 | 反例（据此剔除） |
+|---|---|
+| ① **核心链路**（资金/履约/交付这类业务闭环） | 购物车 key 命名、查询接口 |
+| ② **高级工程师的设计**（设计决策，非框架常识） | Redis `GETDEL`、Spring 自注入修事务自调用 |
+| ③ **简历够硬**（能写成"我设计了 X 机制解决 Y"） | 定长文件 + 签名 + SFTP 的对接实现 |
+
+**二级 · 表达**：`用【机制】解决了【具体问题/场景】，代价是【取舍】`——本阶段只试填"机制+问题"两格；填不出机制 → 并入「已剔除」表（标 `机制格填不出`，待复核）；填不出取舍**不误杀**（取舍归 `value-dig`）。
+
+> ⚠️ **`机制格填不出` 的剔除门槛（防误杀，实测翻案教训）**：机制本体常藏在实现大类（2000+ 行）的私有方法群里，入口类名/Job 类名只是壳——**没读过入口方法向下 ~100 行，不得以此理由定稿剔除**。剔除非此理由的照常。被剔除后复评翻案的，在剔除表原行标注撤销原因与日期（如"2026-09-18 复评撤销：快照轮询机制实存，升级为 ★N"），不删行——翻案记录本身就是筛选口径的进化证据。
+
+被剔除的点进「已剔除」表（注明未过哪条标准），不丢弃。
+
+### 数量
+
+亮点 **5–8 条**为宜。超过 12 条 = 颗粒度掉到实现层，退回重并。
+
+## S2 · 门控（终点，不可跳过）
+
+1. 候选清单**已落盘**（每条含「一句话价值」与锚点），头部「闸门状态」节写明"S1 已完成 · 待勾选"；
+2. 回复里**显式请求勾选**（"请从这 N 条里挑 3–6 条"）。用户禁用提问时也一样停——把请求写成文字，**不是**替他挑完继续写文档。
+3. **否决即校准**：人否决候选（"不够硬"/"一般"）时，把否决原因记入清单（闸门状态或剔除表）——下次扫同域/同仓先读上次的否决记录，同类点不再重复上报；整批否决且未给新目标 = 流程终点，不强续。
+
+## 硬规则（合并版，替代旧的硬规则/反模式/Gotchas 三张表）
+
+| # | 规则 | 为什么 |
+|:-:|---|---|
+| 1 | **深度闸门**：无围栏代码块（Mermaid 除外，行内反引号可用）；不贴源码、不写行号、不逐层拆解、不展开取舍 | 本阶段是广度层 |
+| 2 | **不找缺陷、不读"坏味道报告"**；把克制当设计（"manager 只有 3 个"可能是有意的） | 缺陷导向会摧毁清单 |
+| 3 | **证据真实性**：锚点 `⟨简写⟩/路径#方法名`（机制级可锚到类；不写行号），**读过再写**，拿不准标【待确认】，每条 ≤2 个 | 错锚点毁掉可信度 |
+| 4 | **每条链路（含未入选的）都要写「是什么 + 为什么入选/未入选」**；0 机制先问"真没有，还是采样不到位" | 链路是骨架，不因无亮点而省略 |
+| 5 | **三层结构**：域 → 链路 → 机制节点，机制必须挂在链路图上 | 并列清单会显得"都是散的" |
+| 6 | **只读 + 门控**：不改被扫项目文件；产出后必停 | — |
+
+## 格式保证
+
+1. **模板外置**：读 `assets/候选清单模板.md` 填空，不照印象写。
+2. **机械校验**：产出后跑 `python <skills>/value-scan/assets/check.py scan -Product <产物> -Template <skills>/value-scan/assets/候选清单模板.md`（跨平台 Python 版；Windows 下若中文乱码先设 `PYTHONIOENCODING=utf-8`。旧 `check.ps1` 保留但不再维护）。FAIL 必须为 0；WARN 允许保留但写明原因。
+3. **偏差回写**：被纠正过就回写模板。模板是活资产。
+
+## 触发词与落盘
+
+**触发词**：「盘点这个模块的价值点」「扫一下 X 域有什么值得讲的」「提取功能点」。
+**落盘**：`<项目根>/docs/{域}-候选价值点.md`（可被用户覆盖）。
+
+**下一步**：用户勾选后，用 `value-dig` 接手。

skill-workbench/generated-skills/skills/value-scan/assets/check.ps1

@@ -0,0 +1,268 @@
+<#
+  value-scan / value-dig 产物机械校验（替代人工核对）
+  ------------------------------------------------------------------
+  用法：
+    # S1 候选清单
+    powershell -ExecutionPolicy Bypass -File check.ps1 -Mode scan `
+        -Product <产物路径> -Template <skills>/value-scan/assets/候选清单模板.md
+
+    # S4 功能点清单
+    powershell -ExecutionPolicy Bypass -File check.ps1 -Mode dig `
+        -Product <产物路径> -Template <skills>/value-dig/assets/深度模板/功能点清单模板.md
+
+    # S4 设计思路与取舍 / 改造方案（整篇级文档，只跑通用校验）
+    powershell -ExecutionPolicy Bypass -File check.ps1 -Mode doc -Product <path> -Template <path>
+
+  退出码：0 = 无 FAIL；1 = 有 FAIL
+  说明：FAIL = 必错；WARN = 需人判断
+#>
+param(
+    [Parameter(Mandatory = $true)]
+    [ValidateSet('scan', 'dig', 'doc')]
+    [string]$Mode,
+
+    [Parameter(Mandatory = $true)]
+    [string]$Product,
+
+    [string]$Template
+)
+
+$ErrorActionPreference = 'Stop'
+
+$script:fail = New-Object System.Collections.Generic.List[string]
+$script:warn = New-Object System.Collections.Generic.List[string]
+$script:pass = New-Object System.Collections.Generic.List[string]
+function Fail($m) { $script:fail.Add($m) }
+function Warn($m) { $script:warn.Add($m) }
+function Pass($m) { $script:pass.Add($m) }
+
+$prodPath = (Resolve-Path -LiteralPath $Product).Path
+$text = [System.IO.File]::ReadAllText($prodPath, [System.Text.Encoding]::UTF8)
+if ($text.Length -gt 0 -and [int][char]$text[0] -eq 0xFEFF) { $text = $text.Substring(1) }
+$lines = $text -split "`r?`n"
+
+# ---------------------------------------------------------------- 围栏代码块
+$fences = @()
+$inFence = $false; $fStart = 0; $fLang = ''
+for ($i = 0; $i -lt $lines.Count; $i++) {
+    if ($lines[$i] -match '^\s*```') {
+        if (-not $inFence) {
+            $inFence = $true; $fStart = $i; $fLang = ($lines[$i] -replace '^\s*```', '').Trim()
+        }
+        else {
+            $inFence = $false
+            $fences += [pscustomobject]@{ Start = $fStart; End = $i; Lang = $fLang; Body = ($i - $fStart - 1) }
+        }
+    }
+}
+if ($inFence) { Fail "存在未闭合的代码围栏（起始行 $($fStart + 1)）" }
+
+# ---------------------------------------------------------------- 通用 1：引号逐行配对
+$oddQuoteLines = @()
+for ($i = 0; $i -lt $lines.Count; $i++) {
+    if ((([regex]::Matches($lines[$i], '"')).Count % 2) -ne 0) { $oddQuoteLines += ($i + 1) }
+}
+if ($oddQuoteLines.Count -eq 0) { Pass '引号逐行配对' }
+else { Fail ("引号未配对的行: " + ($oddQuoteLines -join ', ')) }
+
+# ---------------------------------------------------------------- 通用 2：mermaid 合法性
+$mermaidFences = @($fences | Where-Object { $_.Lang -eq 'mermaid' })
+$mmBad = 0
+foreach ($f in $mermaidFences) {
+    $body = ($lines[($f.Start + 1)..($f.End - 1)] -join "`n")
+    $firstLine = (($body -split "`r?`n") | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | Select-Object -First 1)
+    $endCount = ([regex]::Matches($body, '(?m)^\s*end\s*$')).Count
+    if ($firstLine -match 'sequenceDiagram') {
+        # 时序图：end 收的是 alt/opt/loop/par/critical/break/rect
+        $blk = ([regex]::Matches($body, '(?m)^\s*(alt|opt|loop|par|critical|break|rect)\b')).Count
+        if ($blk -ne $endCount) { Fail "mermaid 时序图（第 $($f.Start + 1) 行起）alt/opt/loop 等 $blk 个但 end=$endCount"; $mmBad++ }
+    }
+    else {
+        $sg = ([regex]::Matches($body, '(?m)^\s*subgraph\s')).Count
+        if ($sg -ne $endCount) { Fail "mermaid 流程图（第 $($f.Start + 1) 行起）subgraph=$sg 但 end=$endCount"; $mmBad++ }
+        if ($body -match '(?m)^\s*subgraph\s+\S+\s*\[' -and $body -notmatch '(?m)^\s*subgraph\s+\S+\s*\["') {
+            Fail "mermaid（第 $($f.Start + 1) 行起）subgraph 缺引号标题，必须写 subgraph id[`"标题`"]"; $mmBad++
+        }
+        if ($body -match '(?m)^\s*subgraph\s+\S+\s*\[\(') {
+            Fail "mermaid（第 $($f.Start + 1) 行起）用了 subgraph xxx[(...)]，会解析失败"; $mmBad++
+        }
+    }
+}
+if ($mermaidFences.Count -gt 0 -and $mmBad -eq 0) { Pass "mermaid 块 $($mermaidFences.Count) 个通过" }
+
+# ---------------------------------------------------------------- 通用 3：表格列数一致
+$ti = 0
+while ($ti -lt $lines.Count) {
+    if ($lines[$ti] -match '^\s*\|') {
+        $blk = @(); $bs = $ti
+        while ($ti -lt $lines.Count -and $lines[$ti] -match '^\s*\|') { $blk += $lines[$ti]; $ti++ }
+        $counts = @($blk | ForEach-Object { ([regex]::Matches($_, '\|')).Count } | Sort-Object -Unique)
+        if ($counts.Count -gt 1) { Fail "表格列数不一致（第 $($bs + 1) 行起）：pipe 数 = $($counts -join '/')" }
+    }
+    else { $ti++ }
+}
+
+# ---------------------------------------------------------------- 通用 3b：表格不得缩进（嵌套在列表内的表多数渲染器不显示）
+$indentedTable = @()
+for ($i = 0; $i -lt $lines.Count; $i++) {
+    if ($lines[$i] -match '^[ \t]+\|') { $indentedTable += ($i + 1) }
+}
+if ($indentedTable.Count -eq 0) { Pass '表格均顶格（无嵌套缩进表）' }
+else { Fail ('表格存在缩进（第 ' + ($indentedTable -join ', ') + ' 行起）——嵌套在列表里的表多数渲染器不显示，必须顶格') }
+
+# ---------------------------------------------------------------- 通用 4：章节完整性（模板必备节 ⊆ 产出节）
+if ($Template) {
+    $tPath = (Resolve-Path -LiteralPath $Template).Path
+    $tText = [System.IO.File]::ReadAllText($tPath, [System.Text.Encoding]::UTF8)
+    if ($tText.Length -gt 0 -and [int][char]$tText[0] -eq 0xFEFF) { $tText = $tText.Substring(1) }
+    $tLines = $tText -split "`r?`n"
+    $tHeads = $tLines | Where-Object { $_ -match '^\s*#+\s+\S' }
+    $missingLiteral = @(); $missingPlaceholder = @()
+    foreach ($h in $tHeads) {
+        $t = ($h -replace '^\s*#+\s+', '') -replace '\s+$', ''
+        $hasPh = $t.Contains([string][char]0x27E8)
+        $sentinel = '@@PH@@'
+        $phRx = [string][char]0x27E8 + '[^' + [string][char]0x27E9 + ']*' + [string][char]0x27E9
+        $rx = [regex]::Escape([regex]::Replace($t, $phRx, $sentinel)).Replace($sentinel, '.*')
+        $hit = $false
+        foreach ($pl in $lines) { if ($pl -match ('^\s*#+\s+' + $rx + '\s*$')) { $hit = $true; break } }
+        if (-not $hit) {
+            if ($hasPh) { $missingPlaceholder += $t } else { $missingLiteral += $t }
+        }
+    }
+    if ($missingLiteral.Count -eq 0) { Pass '章节完整性：模板必备节全部存在' }
+    else { Fail ('缺章节（字面量，必错）: ' + ($missingLiteral -join ' | ')) }
+    if ($missingPlaceholder.Count -gt 0) { Warn ('示例性章节未匹配（可能条数不同，需人判）: ' + ($missingPlaceholder -join ' | ')) }
+}
+
+# ---------------------------------------------------------------- 定位辅助
+function Get-HeadIndex($pattern) {
+    for ($i = 0; $i -lt $lines.Count; $i++) { if ($lines[$i] -match $pattern) { return $i } }
+    return -1
+}
+function Get-NextHeadIndex($from) {
+    for ($i = $from + 1; $i -lt $lines.Count; $i++) { if ($lines[$i] -match '^\s*#+\s+\S') { return $i } }
+    return $lines.Count
+}
+
+# ---------------------------------------------------------------- scan 专属
+if ($Mode -eq 'scan') {
+    # 1) 禁止围栏代码块（mermaid 除外）
+    $nonMermaid = @($fences | Where-Object { $_.Lang -ne 'mermaid' })
+    if ($nonMermaid.Count -eq 0) { Pass '深度闸门：S1 无围栏代码块（仅 mermaid）' }
+    else { Fail ("S1 不允许围栏代码块，发现 $($nonMermaid.Count) 个（第 " + (($nonMermaid | ForEach-Object { $_.Start + 1 }) -join ', ') + ' 行起）') }
+
+    # 2) 锚点格式：路径#方法名（不带行号，每条最多 2 个）
+    $badAnchor = @()
+    $anchorCount = 0
+    foreach ($l in $lines) {
+        if ($l -match '^\s*\*\*锚点\*\*\s*[：:]\s*(.+?)\s*$') {
+            $anchorCount++
+            $v = $Matches[1]
+            $items = @($v -split '[、,，]' | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+            if ($items.Count -gt 2) { $badAnchor += ("锚点超过 2 个（$($items.Count) 个）: " + $l.Trim()) }
+            foreach ($it in $items) {
+                $a = $it.Trim().Trim('`')
+                if ($a -match ':\d') { $badAnchor += ("S1 锚点不写行号 -> $a") }
+                elseif ($a -notmatch '\w[/\\]\w') { $badAnchor += ("S1 锚点须为 路径#方法名（机制级可到类名） -> $a") }
+            }
+        }
+    }
+    if ($anchorCount -eq 0) { Warn '未找到 **锚点** 行（若产物为空则忽略）' }
+    elseif ($badAnchor.Count -eq 0) { Pass "锚点格式合规（$anchorCount 处，路径#方法名）" }
+    else { Fail ('锚点格式不合规: ' + ($badAnchor -join ' ; ')) }
+
+    # 3) 闸门状态节
+    if ((Get-HeadIndex '^\s*#+\s*闸门状态') -ge 0) { Pass '有「闸门状态」节（S2 门控有证据）' }
+    else { Fail '缺「闸门状态」节 —— S2 门控没有证据' }
+
+    # 4) 候选条数（提示性：超 12 才 FAIL，无下限硬卡）
+    $starCount = ($lines | Where-Object { $_ -match '^\s*#+\s*★' }).Count
+    if ($starCount -le 12) { Pass "候选条数 $starCount（≤12）" }
+    else { Fail "候选条数 $starCount 超过 12（颗粒度掉到实现层，需重并）" }
+    if ($starCount -lt 5 -and $starCount -gt 0) { Warn "候选条数 $starCount 少于 5——先确认是否采样不到位，而非真没有" }
+}
+
+# ---------------------------------------------------------------- dig 专属
+if ($Mode -eq 'dig') {
+    $skelIdx = Get-HeadIndex '^\s*#+\s*主干调用骨架'
+    $skelEnd = if ($skelIdx -ge 0) { Get-NextHeadIndex $skelIdx } else { -1 }
+    if ($skelIdx -ge 0) { Pass '有「主干调用骨架」节' }
+    else { Warn '未找到「主干调用骨架」节（仅 S4 ① 功能点清单必需）' }
+
+    # 1) 局部代码块 ≤10 行（骨架块豁免）
+    $exempt = 0
+    foreach ($f in $fences) {
+        if ($f.Lang -eq 'mermaid') { continue }
+        $isSkel = ($skelIdx -ge 0 -and $f.Start -gt $skelIdx -and $f.Start -lt $skelEnd)
+        if ($isSkel) { $exempt++; continue }
+        if ($f.Body -gt 10) { Warn "局部代码块超过 10 行（第 $($f.Start + 1) 行起，$($f.Body) 行）——行数非硬限，请人判断是关键片段还是源码摘录" }
+    }
+    Pass ("局部代码块行数检查完成（豁免骨架块 $exempt 个）")
+
+    # 2) 骨架每行必须带方式标记
+    if ($skelIdx -ge 0) {
+        $skelFence = @($fences | Where-Object { $_.Start -gt $skelIdx -and $_.Start -lt $skelEnd }) | Select-Object -First 1
+        if (-not $skelFence) { Warn '骨架节里没有代码块' }
+        else {
+            $missTag = @()
+            foreach ($bl in ($lines[($skelFence.Start + 1)..($skelFence.End - 1)])) {
+                if ([string]::IsNullOrWhiteSpace($bl)) { continue }
+                if ($bl -match '^\s*//') { continue }                       # 分段注释行
+                if ($bl -match ':\s*$') { continue }                        # 块头行（xxx(): ），标"谁"不标"怎么做"
+                if ($bl -notmatch '[(\[]') { continue }                     # 连接词行（↓ 三路汇合）
+                if ($bl -notmatch '//') { $missTag += $bl.Trim() }          # 其余动作行必须有方式标记
+            }
+            if ($missTag.Count -eq 0) { Pass '骨架每行都带方式标记' }
+            else { Fail "骨架有 $($missTag.Count) 行缺方式标记: " + (($missTag | Select-Object -First 3) -join ' ; ') }
+        }
+    }
+
+    # 3) 证据须含 行号
+    if ($text -notmatch '\.(java|xml|yaml|yml|sql):\d+') { Fail '未找到任何 `文件:行号` 证据（本阶段必须有可核对的锚点）' }
+    else { Pass '存在 `文件:行号` 形式的证据' }
+}
+
+# ---------------------------------------------------------------- doc 专属
+if ($Mode -eq 'doc') {
+    # 改造方案识别：含「现状问题登记」节（设计思路与取舍模板不含此节）
+    $isPlan = (Get-HeadIndex '^\s*#+\s*0\.\s*现状问题登记') -ge 0
+    if ($isPlan) {
+        # 1) 必有非 mermaid 代码片段（伪代码 / SQL）
+        $codeFences = @($fences | Where-Object { $_.Lang -ne 'mermaid' })
+        if ($codeFences.Count -ge 1) { Pass "改造方案含关键片段 $($codeFences.Count) 个" }
+        else { Fail '改造方案缺「关键片段」代码块——必须"照着能讲代码"（伪代码/SQL 均可，只禁大段源码摘录）' }
+
+        # 2) 片段应覆盖"骨架 + 改造点"，只给一块多半只在开头充数
+        if ($codeFences.Count -ge 2) { Pass "关键片段 $($codeFences.Count) 个（骨架 + 改造点）" }
+        elseif ($codeFences.Count -eq 1) { Warn '只有 1 个关键片段——可能只有链路骨架，各改造点未给伪代码，需人判' }
+    }
+}
+
+# ---------------------------------------------------------------- 输出
+Write-Output ""
+Write-Output ("=" * 68)
+Write-Output "机械校验  Mode=$Mode"
+Write-Output ("  product  : " + $prodPath)
+if ($Template) { Write-Output ("  template : " + (Resolve-Path -LiteralPath $Template).Path) }
+Write-Output ("=" * 68)
+
+if ($script:pass.Count -gt 0) {
+    Write-Output ""
+    Write-Output "[PASS]"
+    foreach ($m in $script:pass) { Write-Output ("  + " + $m) }
+}
+if ($script:warn.Count -gt 0) {
+    Write-Output ""
+    Write-Output "[WARN] 需人判断"
+    foreach ($m in $script:warn) { Write-Output ("  ! " + $m) }
+}
+if ($script:fail.Count -gt 0) {
+    Write-Output ""
+    Write-Output "[FAIL] 必错"
+    foreach ($m in $script:fail) { Write-Output ("  x " + $m) }
+}
+
+Write-Output ""
+Write-Output ("结果：PASS {0} / WARN {1} / FAIL {2}" -f $script:pass.Count, $script:warn.Count, $script:fail.Count)
+if ($script:fail.Count -gt 0) { exit 1 } else { exit 0 }

skill-workbench/generated-skills/skills/value-scan/assets/check.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+value-scan / value-dig 产物机械校验（Python 版，等价移植自 check.ps1，跨平台）
+------------------------------------------------------------------
+用法：
+  # S1 候选清单
+  python check.py scan <产物路径> --template <skills>/value-scan/assets/候选清单模板.md
+
+  # S4 功能点清单
+  python check.py dig <产物路径> --template <skills>/value-dig/assets/深度模板/功能点清单模板.md
+
+  # S4 设计思路与取舍 / 改造方案（整篇级文档，只跑通用校验）
+  python check.py doc <产物路径> --template <路径>
+
+退出码：0 = 无 FAIL；1 = 有 FAIL；2 = 用法/IO 错误
+说明：FAIL = 必错；WARN = 需人判断
+"""
+import argparse
+import re
+import sys
+from pathlib import Path
+
+FAIL, WARN, PASS = [], [], []
+
+# ⟨ ⟩ 占位符（U+27E8 / U+27E9）
+PH_L, PH_R = '\u27e8', '\u27e9'
+
+
+def fail(m):
+    FAIL.append(m)
+
+
+def warn(m):
+    WARN.append(m)
+
+
+def pass_(m):
+    PASS.append(m)
+
+
+def read_text(path_str):
+    p = Path(path_str)
+    if not p.is_file():
+        print(f"[ERROR] 文件不存在: {path_str}", file=sys.stderr)
+        sys.exit(2)
+    text = p.read_text(encoding='utf-8-sig')  # 自动剥 BOM
+    return text, text.splitlines()
+
+
+def head_index(lines, pattern):
+    for i, line in enumerate(lines):
+        if re.search(pattern, line):
+            return i
+    return -1
+
+
+def next_head_index(lines, start):
+    for i in range(start + 1, len(lines)):
+        if re.match(r'^\s*#+\s+\S', lines[i]):
+            return i
+    return len(lines)
+
+
+def line_snip(line, width=40):
+    """报错附带的行内容摘要（改进：报错不指内容曾导致误诊）"""
+    s = line.strip().replace('|', '\\|')
+    return s[:width] + ('…' if len(s) > width else '')
+
+
+def main():
+    ap = argparse.ArgumentParser(description='value-scan/value-dig 产物机械校验')
+    ap.add_argument('mode', choices=['scan', 'dig', 'doc'])
+    ap.add_argument('product', help='产物路径')
+    ap.add_argument('--template', '-t', help='模板路径')
+    ap.add_argument('-Mode', '-Product', '-Template', dest='legacy', help=argparse.SUPPRESS)
+    args = ap.parse_args()
+
+    prod_path = Path(args.product).resolve()
+    text, lines = read_text(args.product)
+
+    # ------------------------------------------------ 围栏代码块
+    fences = []
+    in_fence = False
+    f_start, f_lang = 0, ''
+    for i, line in enumerate(lines):
+        if re.match(r'^\s*```', line):
+            if not in_fence:
+                in_fence, f_start = True, i
+                f_lang = re.sub(r'^\s*```', '', line).strip()
+            else:
+                in_fence = False
+                fences.append({'start': f_start, 'end': i, 'lang': f_lang,
+                               'body': i - f_start - 1})
+    if in_fence:
+        fail(f'存在未闭合的代码围栏（起始行 {f_start + 1}）')
+
+    # ------------------------------------------------ 通用 1：引号逐行配对
+    odd_quote = [i + 1 for i, line in enumerate(lines)
+                 if line.count('"') % 2 != 0]
+    if not odd_quote:
+        pass_('引号逐行配对')
+    else:
+        fail('引号未配对的行: ' + ', '.join(map(str, odd_quote)))
+
+    # ------------------------------------------------ 通用 2：mermaid 合法性
+    mermaid_fences = [f for f in fences if f['lang'] == 'mermaid']
+    mm_bad = 0
+    for f in mermaid_fences:
+        body_lines = lines[f['start'] + 1:f['end']]
+        body = '\n'.join(body_lines)
+        first = next((l for l in body_lines if l.strip()), '')
+        end_count = len(re.findall(r'(?m)^\s*end\s*$', body))
+        if 'sequenceDiagram' in first:
+            blk = len(re.findall(r'(?m)^\s*(alt|opt|loop|par|critical|break|rect)\b', body))
+            if blk != end_count:
+                fail(f"mermaid 时序图（第 {f['start'] + 1} 行起）alt/opt/loop 等 {blk} 个但 end={end_count}")
+                mm_bad += 1
+        else:
+            sg = len(re.findall(r'(?m)^\s*subgraph\s', body))
+            if sg != end_count:
+                fail(f"mermaid 流程图（第 {f['start'] + 1} 行起）subgraph={sg} 但 end={end_count}")
+                mm_bad += 1
+            if (re.search(r'(?m)^\s*subgraph\s+\S+\s*\[', body)
+                    and not re.search(r'(?m)^\s*subgraph\s+\S+\s*\["', body)):
+                fail(f'mermaid（第 {f["start"] + 1} 行起）subgraph 缺引号标题，必须写 subgraph id["标题"]')
+                mm_bad += 1
+            if re.search(r'(?m)^\s*subgraph\s+\S+\s*\[\(', body):
+                fail(f'mermaid（第 {f["start"] + 1} 行起）用了 subgraph xxx[(...)]，会解析失败')
+                mm_bad += 1
+    if mermaid_fences and mm_bad == 0:
+        pass_(f'mermaid 块 {len(mermaid_fences)} 个通过')
+
+    # ------------------------------------------------ 通用 3：表格列数一致（含行内容摘要）
+    ti = 0
+    while ti < len(lines):
+        if re.match(r'^\s*\|', lines[ti]):
+            bs = ti
+            blk = []
+            while ti < len(lines) and re.match(r'^\s*\|', lines[ti]):
+                blk.append(lines[ti])
+                ti += 1
+            counts = sorted({b.count('|') for b in blk})
+            if len(counts) > 1:
+                fail(f"表格列数不一致（第 {bs + 1} 行起）：pipe 数 = {'/'.join(map(str, counts))}"
+                     f"｜首行内容: {line_snip(blk[0])}")
+        else:
+            ti += 1
+
+    # ------------------------------------------------ 通用 3b：表格不得缩进
+    indented = [i + 1 for i, line in enumerate(lines) if re.match(r'^[ \t]+\|', line)]
+    if not indented:
+        pass_('表格均顶格（无嵌套缩进表）')
+    else:
+        fail('表格存在缩进（第 ' + ', '.join(map(str, indented)) + ' 行起）——嵌套在列表里的表多数渲染器不显示，必须顶格')
+
+    # ------------------------------------------------ 通用 4：章节完整性
+    if args.template:
+        _, t_lines = read_text(args.template)
+        t_heads = [l for l in t_lines if re.match(r'^\s*#+\s+\S', l)]
+        missing_literal, missing_ph = [], []
+        for h in t_heads:
+            t = re.sub(r'\s+$', '', re.sub(r'^\s*#+\s+', '', h))
+            has_ph = PH_L in t
+            ph_rx = re.escape(PH_L) + '[^' + re.escape(PH_R) + ']*' + re.escape(PH_R)
+            rx = re.escape(re.sub(ph_rx, '@@PH@@', t)).replace('@@PH@@', '.*')
+            hit = any(re.match(r'^\s*#+\s+' + rx + r'\s*$', pl) for pl in lines)
+            if not hit:
+                (missing_ph if has_ph else missing_literal).append(t)
+        if not missing_literal:
+            pass_('章节完整性：模板必备节全部存在')
+        else:
+            fail('缺章节（字面量，必错）: ' + ' | '.join(missing_literal))
+        if missing_ph:
+            warn('示例性章节未匹配（可能条数不同，需人判）: ' + ' | '.join(missing_ph))
+
+    # ------------------------------------------------ scan 专属
+    if args.mode == 'scan':
+        non_mermaid = [f for f in fences if f['lang'] != 'mermaid']
+        if not non_mermaid:
+            pass_('深度闸门：S1 无围栏代码块（仅 mermaid）')
+        else:
+            fail('S1 不允许围栏代码块，发现 {} 个（第 {} 行起）'.format(
+                len(non_mermaid),
+                ', '.join(str(f['start'] + 1) for f in non_mermaid)))
+
+        bad_anchor, anchor_count = [], 0
+        for line in lines:
+            m = re.match(r'^\s*\*\*锚点\*\*\s*[：:]\s*(.+?)\s*$', line)
+            if not m:
+                continue
+            anchor_count += 1
+            items = [s for s in re.split(r'[、,，]', m.group(1)) if s.strip()]
+            if len(items) > 2:
+                bad_anchor.append(f'锚点超过 2 个（{len(items)} 个）: {line.strip()}')
+            for it in items:
+                a = it.strip().strip('`')
+                if re.search(r':\d', a):
+                    bad_anchor.append(f'S1 锚点不写行号 -> {a}')
+                elif not re.search(r'\w[/\\]\w', a):
+                    bad_anchor.append(f'S1 锚点须为 路径#方法名（机制级可到类名） -> {a}')
+        if anchor_count == 0:
+            warn('未找到 **锚点** 行（若产物为空则忽略）')
+        elif not bad_anchor:
+            pass_(f'锚点格式合规（{anchor_count} 处，路径#方法名）')
+        else:
+            fail('锚点格式不合规: ' + ' ; '.join(bad_anchor))
+
+        if head_index(lines, r'^\s*#+\s*闸门状态') >= 0:
+            pass_('有「闸门状态」节（S2 门控有证据）')
+        else:
+            fail('缺「闸门状态」节 —— S2 门控没有证据')
+
+        star_count = sum(1 for l in lines if re.match(r'^\s*#+\s*★', l))
+        if star_count <= 12:
+            pass_(f'候选条数 {star_count}（≤12）')
+        else:
+            fail(f'候选条数 {star_count} 超过 12（颗粒度掉到实现层，需重并）')
+        if 0 < star_count < 5:
+            warn(f'候选条数 {star_count} 少于 5——先确认是否采样不到位，而非真没有')
+
+    # ------------------------------------------------ dig 专属
+    if args.mode == 'dig':
+        skel_idx = head_index(lines, r'^\s*#+\s*主干调用骨架')
+        skel_end = next_head_index(lines, skel_idx) if skel_idx >= 0 else -1
+        if skel_idx >= 0:
+            pass_('有「主干调用骨架」节')
+        else:
+            warn('未找到「主干调用骨架」节（仅 S4 ① 功能点清单必需）')
+
+        exempt = 0
+        for f in fences:
+            if f['lang'] == 'mermaid':
+                continue
+            if skel_idx >= 0 and skel_idx < f['start'] < skel_end:
+                exempt += 1
+                continue
+            if f['body'] > 10:
+                warn(f"局部代码块超过 10 行（第 {f['start'] + 1} 行起，{f['body']} 行）"
+                     f"——行数非硬限，请人判断是关键片段还是源码摘录")
+        pass_(f'局部代码块行数检查完成（豁免骨架块 {exempt} 个）')
+
+        if skel_idx >= 0:
+            skel_fences = [f for f in fences if skel_idx < f['start'] < skel_end]
+            if not skel_fences:
+                warn('骨架节里没有代码块')
+            else:
+                sf = skel_fences[0]
+                miss_tag = []
+                for bl in lines[sf['start'] + 1:sf['end']]:
+                    if not bl.strip():
+                        continue
+                    if re.match(r'^\s*//', bl):
+                        continue
+                    if re.search(r':\s*$', bl):
+                        continue
+                    if not re.search(r'[(\[]', bl):
+                        continue
+                    if '//' not in bl:
+                        miss_tag.append(bl.strip())
+                if not miss_tag:
+                    pass_('骨架每行都带方式标记')
+                else:
+                    fail(f"骨架有 {len(miss_tag)} 行缺方式标记: "
+                         + ' ; '.join(miss_tag[:3]))
+        if not re.search(r'\.(java|xml|yaml|yml|sql):\d+', text):
+            fail('未找到任何 `文件:行号` 证据（本阶段必须有可核对的锚点）')
+        else:
+            pass_('存在 `文件:行号` 形式的证据')
+
+    # ------------------------------------------------ doc 专属
+    if args.mode == 'doc':
+        is_plan = head_index(lines, r'^\s*#+\s*0\.\s*现状问题登记') >= 0
+        if is_plan:
+            code_fences = [f for f in fences if f['lang'] != 'mermaid']
+            if len(code_fences) >= 1:
+                pass_(f'改造方案含关键片段 {len(code_fences)} 个')
+            else:
+                fail('改造方案缺「关键片段」代码块——必须"照着能讲代码"（伪代码/SQL 均可，只禁大段源码摘录）')
+            if len(code_fences) >= 2:
+                pass_(f"关键片段 {len(code_fences)} 个（骨架 + 改造点）")
+            elif len(code_fences) == 1:
+                warn('只有 1 个关键片段——可能只有链路骨架，各改造点未给伪代码，需人判')
+
+    # ------------------------------------------------ 输出
+    print()
+    print('=' * 68)
+    print(f'机械校验  Mode={args.mode}')
+    print(f'  product  : {prod_path}')
+    if args.template:
+        print(f"  template : {Path(args.template).resolve()}")
+    print('=' * 68)
+
+    for tag, bucket, mark in (('[PASS]', PASS, '+ '), ('[WARN] 需人判断', WARN, '! '), ('[FAIL] 必错', FAIL, 'x ')):
+        if bucket:
+            print()
+            print(tag)
+            for m in bucket:
+                print(f'  {mark}{m}')
+
+    print()
+    print(f'结果：PASS {len(PASS)} / WARN {len(WARN)} / FAIL {len(FAIL)}')
+    sys.exit(1 if FAIL else 0)
+
+
+if __name__ == '__main__':
+    main()

skill-workbench/generated-skills/skills/value-scan/assets/候选清单模板.md

@@ -0,0 +1,146 @@
+# ⟨域⟩ 域 · 候选价值点（S1 产物）
+
+> **阶段**：S1 枚举（**只产出亮点**；缺陷不在此阶段——它是深入链路时自然浮现的副产物）
+> **域**：`⟨模块名⟩`（走 S0 ⟨快路 / 慢路⟩：⟨域清单来源⟩）
+> **结构**：**域 → 链路 → 链路上的机制节点** 三层
+> **筛选标准（三条，全过才进）**：**① 是否核心链路 ② 是否符合高级工程师的设计 ③ 写到简历上够不够硬**
+> **深度闸门**：允许「**这个点在讲什么**」的业务语言说明；**禁止围栏代码块（行内反引号可用）、禁止逐层拆解、禁止取舍复盘**（那些属深度阶段）
+> **取材**：① 设计说明类文档 ② `git log` ③ 图查询 / 结构统计 ④ 关键字 grep
+
+---
+
+# 闸门状态
+
+> **本节是 S2 门控的证据**——没有它，"停在第几段"无法核查。
+
+| 段 | 状态 | 说明 |
+|:-:|---|---|
+| S0 定范围 | ✅ | ⟨范围声明一句话⟩ |
+| **S1 枚举** | ✅ 已完成 | 候选 ⟨N⟩ 条（**亮点**）+ 剔除 ⟨M⟩ 条 |
+| **S2 勾选** | ⏸ **待人工勾选** | **请从下面挑 3–6 条**；本文件到此为止，**未做深度产出** |
+
+> **勾选/否决后回写本表（保持 3 列不压列）**，两种回写形状：
+>
+> ```
+> | **S2 勾选** | ✅ 已勾选 | ⟨勾了哪些（★N…）/ 谁日期⟩ → 产出《⟨产物名⟩》 |
+> | **S2 勾选** | ↩️ 被否决改向 | 否决原因：⟨用户原话摘要⟩ → 改挖 ⟨新目标⟩（入口 A′） |
+> ```
+
+---
+
+## 一、链路总览
+
+**一句话**：⟨统领句——不是复述流程，而是给出这条链路的**主线判断**。例："这条链路的每一段都在把外部系统给的不确定，收敛成我方的确定状态"⟩
+
+**读法**：⟨一条端到端链路 = …→…→…；下面每个机制都挂在这张图的某个位置上⟩
+**图例**：`★` = 入选的机制节点；**未标 ★ 的链路仍属本链路的一环**（见第二、三节），只是未列为独立机制。
+
+### 端到端链路图（★ = 入选的机制节点）
+
+```mermaid
+flowchart LR
+    subgraph PA["链路 A · ⟨链路名⟩"]
+        A1["⟨起点⟩"] --> A2["⟨机制节点⟩ ★1"]
+        A3["⟨兜底 / 分支⟩ ★2"]
+    end
+    subgraph PB["链路 B · ⟨链路名⟩"]
+        B1["⟨起点⟩"] --> B2["⟨机制节点⟩ ★3"]
+        B2 --> B3["⟨机制节点⟩ ★4"]
+    end
+    subgraph PC["链路 C · ⟨链路名⟩"]
+        C1["⟨起点⟩"] --> C2["⟨终点⟩"]
+    end
+    A2 --> B1
+    A3 -.-> A2
+    B3 --> C1
+    C2 -.-> A2
+```
+
+⟨可选⟩**关键差异表**（若这条链路的核心是"几种结果后果完全不同"，用一张表压住）
+
+| ⟨维度⟩ | ⟨取值1⟩ | ⟨取值2⟩ | ⟨取值3⟩ |
+|---|---|---|---|
+| ⟨例：对方结果⟩ | | | |
+| ⟨例：可逆性⟩ | | | |
+| ⟨例：处置⟩ | | | |
+
+---
+
+## 二、链路上的机制节点（⟨N⟩ 个 ★）
+
+> **按链路分组**。每点 4 段，**段落式**（不要压成表格——"做了什么"常是 5–7 条，塞进单元格必然被简化）。
+
+### 链路 ⟨A⟩ · ⟨链路名⟩
+
+## ★1 · ⟨机制名⟩
+
+**核心内容**：⟨1 句：这个机制是什么，把它的"形状"说清（一把锁 + 三级短路 + 一条条件更新）⟩
+
+**这个点在讲什么**
+
+- **业务场景**：⟨谁在什么时刻触发了什么，为什么这事难；点出"同一时刻还有谁在改同一行数据"⟩
+- **做了什么**（⟨用一句话概括做法⟩）：
+  1. ⟨…⟩；
+  2. ⟨…⟩；
+  3. ⟨…⟩。
+- **解决了什么问题**：⟨不做会怎样⟩
+
+**一句话价值**：⟨1 句，可讲述；说清"判断权 / 控制权"落在谁手里⟩
+
+**锚点**：`⟨简写⟩/⟨路径⟩#⟨方法名⟩`
+
+---
+
+## ★2 · ⟨机制名⟩
+
+⟨同 ★1 的 4 段结构⟩
+
+---
+
+### 链路 ⟨B⟩ · ⟨链路名⟩
+
+## ★3 · ⟨机制名⟩
+
+⟨同 ★1 的 4 段结构⟩
+
+---
+
+### 链路 ⟨C⟩ · ⟨链路名⟩（⟨依附型，未列为独立机制 / 未入选⟩）
+
+> **本链路 0 个独立机制，但说明不可省**——否则图上有个框、没人知道里面在干嘛。
+
+**核心内容**：⟨它是什么⟩
+
+**这个点在讲什么**
+
+- **业务场景**：⟨…⟩
+- **做了什么**：⟨…⟩
+- **依附关系**：⟨它的哪几个设计决策其实是 ★N 在另一个方向 / 另一个域上的复用；判不清就按独立节点处理，不要为了凑数强行依附⟩
+- **为什么未入选 / 为什么依附**：⟨★ 必须写清⟩
+
+**锚点**：`⟨…⟩`
+
+---
+
+## 三、已剔除（附理由，供复核筛选口径）
+
+> **被剔除的点不丢弃**——注明**未过哪条标准**。
+
+**「未过的标准」建议取值**：`①核心链路` · `②非设计决策（框架常识 / 通用工程质量）` · `③简历不硬` · `机制格填不出` · `示例数据 / 字典表 / 配置装配`
+
+| # | 被剔除的点 | 未过的标准 | 理由 |
+|:-:|---|---|---|
+| 1 | ⟨例：key 命名约定⟩ | `①核心链路` | 不落在业务闭环上 |
+| 2 | ⟨例：Redis `GETDEL` 用法⟩ | `②非设计决策` | 框架常识用法，非设计决策 |
+| 3 | ⟨例：契约模式 / CI / Checkstyle⟩ | `②非设计决策` | 通用工程质量，无设计含量 |
+| 4 | ⟨例：表 CRUD / 单表封装⟩ | `机制格填不出` | 弱候选，并入本表待复核 |
+
+---
+
+## 四、待确认 / 覆盖缺口
+
+| # | 项 | 说明 |
+|:-:|---|---|
+| 1 | **⟨链路名⟩ 0 个节点** | ⟨先问"真没亮点，还是采样不到位"（回看该链路的触发者与写类接口）；判不清就写明理由⟩ |
+| 2 | `⟨路径⟩#⟨方法名⟩` | 【待确认】⟨拿不准的锚点必须标出，禁止猜⟩ |
+| 3 | **文档 vs 代码分叉** | ⟨设计文档写的方案在代码里是否落地？不落地本身就是高价值点⟩ |

skill-workbench/generated-skills/sm-flow/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: sm-flow
 description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
 ---
@@ -17,6 +17,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 - `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
 - 代码是实现结果：只能在执行真理源足够明确后修改。
 - 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
+- Phase 1 产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 Phase 3 的执行许可。
+- 只有通过 Phase 2.9 提交检查后的 OpenSpec 才是 **Committed OpenSpec**；Phase 3 只能执行 Committed OpenSpec。
 
 ## 核心规则
 
@@ -25,16 +27,39 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 - devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
 - 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
 - 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
+- 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。
 - `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
 - `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
+- grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
+- 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。
+- 接口影响按 L1-L4 分级处理；接口内部判断逻辑如果改变调用方可观察行为，也属于接口影响，不能因签名未变而降级。
+- Phase 3 实现期冲突必须先分类再处理：实现偏差修代码；规格遗漏修 OpenSpec；设计冲突暂停并请用户确认；用户变更更新 proposal/specs/tasks 后再继续。
 - 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
 - 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
-- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
+- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 2.9 后、Phase 3 前必须给用户一个简短检查点；除非用户在启动时明确要求“全自动执行”，否则不得把单个决策确认推断为执行授权。
 - Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
 - 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
-- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
+- 子 skill 绑定能力契约，不绑定单一平台路径。显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应能力的本地 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
 - fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
 
+## 接口影响分级
+
+接口影响分级判断的是“记录在哪里、是否需要独立文档”，不是判断“是否需要关注”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或接口内部判断逻辑变化，都必须先判断接口影响。
+
+| 级别 | 判断条件 | 产物要求 |
+| --- | --- | --- |
+| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
+| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
+| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
+| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
+
+判断策略：
+
+- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
+- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
+- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
+- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
+
 ## 首次加载
 
 执行前只读取当前任务需要的 reference 文件：
@@ -59,8 +84,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
    - `devflow/reference/`
 3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
 4. 检查 OpenSpec 和子 skill 是否可用：
-   - OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
+   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。可由平台原生 skill、`.claude/skills/.../SKILL.md` 或 fallback 协议提供。
-   - 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
+   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。可由平台原生 skill、`.agents/skills/.../SKILL.md` 或 fallback 协议提供。
 5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
 
 ## 项目标识
@@ -101,13 +126,14 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
 ## 阶段总览
 
 1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
-2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
+2. Phase 0.5 — Devflow 上下文收集：先查 `devflow/index.md`，再读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
-3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
+3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 Draft OpenSpec proposal/design/specs/tasks。
 4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
 5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
 6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
-7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
+7. Phase 2.9 — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
-8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
+8. Phase 3 — OpenSpec apply：默认依赖 Committed OpenSpec 执行；devflow 只作为上下文参考。
+9. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，更新 `devflow/index.md`，并询问是否 archive OpenSpec change。
 
 每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
 
@@ -117,6 +143,7 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
 
 - Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
 - Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
+- Phase 2.9 提交检查：即使快速模式也必须确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
 - Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
 - Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
 

skill-workbench/generated-skills/sm-flow/references/archive-rules.md

@@ -17,6 +17,10 @@ devflow/projects/YYYY-MM-DD-{slug}/
 - `decisions.md`
 - `acceptance.md`
 
+同时维护仓库级索引：
+
+- `devflow/index.md`
+
 按需创建以下扩展文件：
 
 - `prd.md`
@@ -49,6 +53,24 @@ devflow/projects/YYYY-MM-DD-{slug}/
 | diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
 | 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
 | 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
+| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` |
+
+## 索引维护规则
+
+`devflow/index.md` 是 Phase 0.5 的默认入口，Phase 4 回填时必须维护。
+
+最小字段：
+
+| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
+| --- | --- | --- | --- | --- | --- |
+
+规则：
+
+- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
+- Phase 4 新建或更新项目档案时，必须新增或更新对应行。
+- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
+- 关键词只放能帮助 Phase 0.5 定位的术语，不复制 brief 内容。
+- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。
 
 ## 验收记录规则
 
@@ -99,6 +121,7 @@ OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 de
 Phase 4 结束时告诉用户：
 
 - 创建或更新了哪些档案文件。
+- `devflow/index.md` 是否已更新。
 - 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
 - 还剩哪些风险或后续事项。
 - 明确询问：是否现在 archive OpenSpec change？