sm-flow v4.2: add verifiable checkpoints and gate file mechanism

Based on real execution review (lookup-knowledge-integration), discovered that constraints are "soft" - rules are clear but lack enforcement mechanism. Core problem: Agent can skip stages despite explicit rules saying "must not skip" Changes: 1. Commit phase: add verifiable checkpoint - File completeness check: proposal ≥50 words, design ≥1 data structure, specs ≥3 requirements, tasks ≥5 items - Consistency check: proposal concepts → design mapping, design decisions → tasks implementation - Gate file: create .committed after passing all checks 2. Apply phase: add pre-gate check - Hard constraint: check .committed file existence - If missing: report, list gaps, ask user to fix or explicitly skip - Block implementation based on incomplete OpenSpec 3. Archive phase: add mandatory execution order - 5-step checklist: devflow files → index → .archive-ready → report → archive - Self-check: verify Step 1-3 before Step 4 - Prevent "handoff first, devflow forgotten" issue New gate files: - .committed: created by commit phase, checked by apply phase - .archive-ready: created by archive Step 3 Expected impact: - Commit skip rate: -100% (explicit checklist prevents fuzzy pass) - Apply on incomplete OpenSpec: -100% (gate blocks) - Archive devflow omission: -100% (mandatory order) Design principles: - Verifiability: "executable state" → "≥50 words + ≥1 structure + ≥3 requirements" - Gate files: soft judgment → file existence check - Mandatory order: advisory "should do" → 5-step checklist "must do" Complexity: +80 lines (phase-contracts.md +40, archive-rules.md +40) Approach: turn soft constraints into hard checks, no new stages Relation to v4.1: - v4.1: solve "insufficient research causes rework" (quality issue) - v4.2: solve "lack of enforcement causes stage skipping" (process issue) Docs: - phase-contracts.md: enhanced commit + apply phases - archive-rules.md: added mandatory execution order at top - workflow.md: added v4.2 evolution chapter - phase-contracts-v4.2-changelog.md: detailed change log - sm-flow-optimization-suggestions.md: source review
sm-flow v4.1: add pre-apply research checkpoint to reduce rework
2026-06-24 14:51:45 +08:00 · 2026-06-23 11:27:32 +08:00 · 2026-05-26 10:14:25 +08:00 · 2026-05-26 09:59:24 +08:00 · 2026-05-25 17:28:15 +08:00 · 2026-05-25 11:44:20 +08:00
68 changed files with 5056 additions and 1485 deletions
@@ -1,132 +1,83 @@
---
+---
 name: sm-flow
-description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
+description: OpenSpec-first 的结构化工程开发协议层 harness。编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用。
 ---
 # 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        → 编排层（harness）：阶段、门控、产物约束、人类对齐
  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
      code     → 实现结果：apply 的产出
 ```
- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。
+- OpenSpec 是唯一执行真理源：apply 阶段只能基于 OpenSpec 执行，不能绕过 OpenSpec 直接写代码。
- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
+- devflow 是上下文真理源：术语、历史决策、验收记录来自 devflow，用于增强 OpenSpec，不替代 OpenSpec。
- 代码是实现结果：只能在执行真理源足够明确后修改。
+- 如果 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**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。
- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
+4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
+5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
+6. **子 skill 必须显式调用**。每个阶段指定的子 skill 必须显式调用；如果子 skill 不存在，流程失败，不得静默跳过或降级执行。
- 不得猜测式修 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 识别意图后，自动补做最小前置检查，然后从指定阶段继续。
 ## 首次加载
 执行前只读取当前任务需要的 reference 文件：
- 需要逐阶段执行时，读取 `references/phase-contracts.md`。
+- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.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。
@@ -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 提取：背景、目标、范围、非目标）
 - [ ] 创建 `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 | archived |`
 ### 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 阶段创建以下文件：
- `brief.md`
+- `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
- `evidence.md`
+- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。
- `decisions.md`
+- `decisions.md`：保持为最终版，整理格式。
- `acceptance.md`
+- `acceptance.md`：从实现结果和验证结果提取。
 同时维护仓库级索引：
 - `devflow/index.md`
 按需创建以下扩展文件：
@@ -40,15 +87,34 @@ devflow/projects/YYYY-MM-DD-{slug}/
 | 来源 | 提取内容 | 写入位置 |
 | --- | --- | --- |
 | `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 +129,7 @@ devflow/projects/YYYY-MM-DD-{slug}/
 - 如果验证通过，记录命令/步骤和覆盖范围。
 - 如果验证失败，记录失败摘要和是否阻塞验收。
- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。
+- 如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。
 ## ADR 规则
@@ -89,18 +155,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？
@@ -1,101 +0,0 @@
 # Fallback 协议
 当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。
 ## OpenSpec 提案 fallback
 1. 创建或识别 `openspec/changes/{slug}/`。
 2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。
 3. 写入 `proposal.md`，包含：
   - 问题
   - 建议方案
   - 范围
   - 非目标
   - 来自 devflow 的上下文约束
   - 风险
 4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。
 5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。
 6. 只为外部可见行为或发生变化的需求编写 specs。
 7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。
 ## OpenSpec 修正 fallback
 当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：
 1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。
 2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。
 3. 向用户汇报冲突和推荐修正。
 4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
 5. 再同步更新 devflow 文档；不要只改 devflow。
 ## OpenSpec 执行 fallback
 仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。
 1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
 2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
 3. 修改前先检查现有代码。
 4. 一次实现一个 OpenSpec task 的纵向切片。
 5. 用最窄但有效的命令验证每个切片。
 6. 只有验证通过或明确记录原因后，才更新 task 状态。
 7. 如果失败原因不确定，停止并进入 diagnose。
 8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
 ## PRD fallback
 优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。
 规则：
 - 从当前上下文、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 行为重复以上步骤。
@@ -0,0 +1,111 @@
 # 运行规则
 本文件承载稳定但不必放在顶层 `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 + 归档确认。
   - 自然语言指定阶段继续：识别意图后，自动补做最小前置检查，然后从指定阶段继续。
 2. 判断启动模式：
   - 完整模式：用户提供粗略想法或初始 PRD。
   - Research 模式：用户已有 research，需要转成或修正 OpenSpec。
   - PRD 文件模式：用户提供已有 PRD 路径。
   - 恢复模式：用户希望从某个阶段继续（补做最小前置检查）。
   - 快速模式：小改动，合并 gate（见下文）。
 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 不可用，不要直接绕过；使用内置执行协议（见 `references/fallbacks.md`），并在 apply 前向用户说明。
 ## 项目标识规则
 - 整个流程使用同一个 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 结论和汇报状态。
 - `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`：小且低风险，gate 合并（见快速模式），最终档案同 standard。
 - `standard`：默认模式。
 - `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加扩展产物。
 ## 快速模式
 快速模式适用于小而低风险的变更。它合并 gate 而不仅仅是压缩产物：
 ```
 standard 流程：clarify → context → propose checkpoint → grill → specify → audit checkpoint → commit
 micro 流程：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题） → commit（简化检查）
 ```
 micro 的定位：**gate 变少但保留最关键的**（grill 最小澄清 + commit gate）。
 无论什么模式，以下内容必须保留：
 - context 最小上下文收集：至少检查 glossary 和相关 ADR。
 - grill 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报。
 - commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
 - apply 仍由 OpenSpec tasks/specs 驱动执行。
 - archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。
 ## 完成标准
 只有同时满足以下条件，流程才算完成：
 - OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态。
 - 实现或规划工作已完成，且执行依据来自 OpenSpec。
 - 已运行验证，或已记录未运行验证的原因。
 - `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md。
 - 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。
@@ -1,8 +1,10 @@
-# 阶段契约
+# 阶段契约
-本文件是 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 — 入口澄清
 **进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。
@@ -11,6 +13,7 @@
 - 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
 - 如果输入过于模糊，最多追加三轮聚焦问题。
 - 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
 - 如果需要判断 `micro / standard / complex` 分档，补读 `references/operating-rules.md`。
 **退出条件**：
 - 问题可以用 1-2 句话说清楚。
@@ -23,11 +26,13 @@
 - 初步 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。
@@ -35,101 +40,130 @@
 - 如果发现旧根目录 `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 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。
+- 询问是否继续进入 grill 澄清阶段；用户明确要求"全自动执行"时可跳过等待。
-## 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。
+**显式子 skill**：`grill-with-docs`。进入本阶段必须调用 `.agents/skills/grill-with-docs/SKILL.md`。
 **动作**：
 - 如果没有结构化 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。
 **退出条件**：
 - question pool 已建立并覆盖当前 change 所需维度。
 - 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `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 更新。
 - 询问是否继续进入 specify 细化阶段。
-**进入条件**：Phase 2 已解决主要产品、领域和验收问题。
+## specify — 细化 + 对齐
-**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。
+**进入条件**：grill 已退出，需求已通过澄清稳定下来。
 **显式子 skill**：`openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；`to-prd`（按需生成 PRD）。进入本阶段必须先声明调用方式。
 **动作**：
 - 基于已稳定的 proposal.md 补全 design.md、specs/、tasks.md：
  - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需补全 design/specs/tasks"。
  - 如果不可用，执行 `references/fallbacks.md#openspec-提案-降级`。
 - 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
 - `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级。
 - 用 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 文档。
 **退出条件**：
 - `design.md`、`specs/`、`tasks.md` 存在且与 proposal 对齐。
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。
 - 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。
 - 所有已知冲突已修正或等待用户决策。
 **输出**：
 - 完整的 Draft OpenSpec：proposal.md + design.md + specs/ + tasks.md。
 - `brief.md`，以及按需创建的 `prd.md`。
 - cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。
 - 必要的 OpenSpec 修正。
 ## audit — 架构审计
 **进入条件**：specify 已退出，完整 OpenSpec 产物已存在。
 **显式子 skill**：`zoom-out`。进入本阶段必须调用 `.agents/skills/zoom-out/SKILL.md`。
 **动作**：
 - 画出输入 → 处理 → 输出的模块链路。
@@ -137,63 +171,170 @@
 - 检查是否与既有架构、ADR、OpenSpec design 冲突。
 - 用不超过五句话写出架构风险评估。
 - 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
 - 审计结论写入 `decisions.md`。
 **退出条件**：
- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。
+- 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。
 - OpenSpec design/tasks 已反映会影响实现的架构审计结论。
 **输出**：
- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。
+- 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。
 - 必要的 OpenSpec design/tasks 修正。
 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
+- 询问是否进入 commit。
-## Phase 3 — OpenSpec apply
+## commit — Commit OpenSpec
 **进入条件**：
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
+- grill 已解决术语、边界、验收三个维度的高价值问题。
- 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 → design → 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。
 - **文件完整性检查**（必须全部通过）：
  - [ ] `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
 - 所有 preflight 风险已消除或明确记录为已接受。
 **输出**：
 - Committed OpenSpec 状态说明。
 - preflight 检查结果，写入 `decisions.md` 或 `acceptance.md`。
 **Human checkpoint**：
 - 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
 - 询问是否进入 apply；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
 - 不得把 grill 的单个决策确认当作本 checkpoint 的授权。
 ## apply — OpenSpec 执行
 **进入条件**：
 - `openspec/changes/{slug}/` 中 proposal/design/specs/tasks 已通过 commit，成为 Committed OpenSpec。
 - **前置门控检查**（硬约束）：
  - 检查 `openspec/changes/{slug}/.committed` 文件是否存在
  - 如不存在，执行以下流程：
    1. 汇报：Draft OpenSpec 未通过 commit 检查
    2. 列出缺失的 checkpoint 项（文件完整性、一致性检查）
    3. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
 - commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。
 - devflow 与 OpenSpec 没有未解决冲突。
 - 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
 **显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须调用指定子 skill，不得静默跳过。
 **动作**：
 ### Pre-apply Checkpoint（15-20 分钟）
 **触发条件**：当 OpenSpec 涉及以下任一情况时必须执行
 - design 或 tasks 中提到"参考 XXX 实现"
 - 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
 - 技术栈不熟悉或第一次在该项目实现类似功能
 **执行步骤**：
 1. **完整阅读所有参考实现**（约 10 分钟）
   - 从 OpenSpec design 或 tasks 中定位参考实现文件
   - 如果路径不明确，通过 Grep 搜索关键类名或模式
   - 逐行理解关键逻辑，提取可复用代码片段和模式
 2. **Grep 关键技术栈**（约 5 分钟）
   - 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范）
   - 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板）
   - 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具）
   - 异常处理和日志记录标准
 3. **形成技术栈清单并写入 decisions.md**
   - 项目使用的请求/响应结构标准
   - MQ 消息定义和发送标准
   - Consumer 标准位置和写法
   - 加密/验签/工具类的标准用法
   - 识别需要新建的工具类或基础设施
 **输出要求**：
 - 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节 ✅
 - 已列出所有参考实现的文件路径 ✅
 - 已识别需要新建的工具类/基础设施 ✅
 **快速模式**：micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单。
 ### 实现过程
 - 优先调用 `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。
+**显式子 skill**：`openspec-archive-change` 在用户确认 archive 后调用；archive 回填由 `sm-flow` 执行。必须调用子 skill，不得静默跳过。
 **动作**：
 - 遵循 `references/archive-rules.md`。
- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
+- 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案：
  - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
  - `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。
  - `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}/` 包含 brief.md、evidence.md、decisions.md、acceptance.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。
@@ -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 回写：不需要 / 已回写 / 待回写
 - 代码处理：
 - 验证方式：
 ```
 ## PRD 模板
 ```markdown
@@ -267,6 +343,26 @@
 - OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用}
 ```
 ## Cross-Artifact 对齐检查表模板
 specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"或"存在 gap"。
 ```markdown
 ## Cross-Artifact 对齐检查
 | 上游 → 下游 | 检查内容 | 状态 |
 |---|---|---|
 | brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap |
 | proposal → design | 范围、约束、关键承诺是否进入 design | 已对齐 / 存在 gap |
 | design → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
 | specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap |
 ### Gap 详情（如有）
 - gap 1：{描述哪个字段/约束/行为/切片只停留在上游，未进入下游}
  - 修复：{如何修正 OpenSpec}
 ```
 ## 复合知识模板
 ```markdown
@@ -1,4 +1,5 @@
 skill-workbench/validation/project/
 superpowers/
 .claude/
 .codex/
 *.stackdump
@@ -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 已同步 |
 **总体验收结论：通过。** 文档、边界、行为三者一致。
@@ -0,0 +1,12 @@
 # Devflow Index
 `devflow/index.md` 是 Phase 0.5 的默认上下文入口。每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认维护一行，帮助代理先定位相关项目，再读取具体 brief、acceptance、ADR 或 compound knowledge。
 | 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
 | --- | --- | --- | --- | --- | --- |
 | 2026-05-18 | knowledge-index-panel | knowledge-index | knowledge-index, search, tags, static-html | `openspec/changes/knowledge-index-panel/` | active |
 | 2026-05-19 | add-clear-filters | knowledge-index | clear-filters, search, tags, year-filter | `openspec/changes/archive/2026-05-19-add-clear-filters/` | archived |
 | 2026-05-19 | add-year-filter | knowledge-index | year-filter, index-panel, frontmatter | `openspec/changes/add-year-filter/` | active |
 | 2026-05-19 | dev-flow-skill-evaluation | sm-flow | dev-flow, sm-flow, skill-evaluation, fallback, phase-contracts | 未关联 | accepted-unarchived |
 | 2026-05-21 | sm-flow-v3-1-upgrade | sm-flow | interface-impact, commit-gate, devflow-index, apply-conflict, skill-compatibility | `openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/` | archived |
 | 2026-05-22 | sm-flow-execution-hardening | sm-flow | execution-hardening, checklist, phase-gate, cross-artifact, question-pool | 未关联 | active |
@@ -0,0 +1,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 中。
@@ -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 的关键设计。
@@ -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 接受。
@@ -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 重点。
@@ -0,0 +1,40 @@
 # SM Flow Execution Hardening Acceptance
 ## Result
 Implemented `sm-flow-execution-hardening` as protocol/document changes only.
 Updated artifacts:
 - `.agents/skills/sm-flow/SKILL.md`
 - `.agents/skills/sm-flow/references/phase-contracts.md`
 - `.agents/skills/sm-flow/references/fallbacks.md`
 - `skill-workbench/docs/sm-flow/workflow.md`
 - `openspec/changes/sm-flow-execution-hardening/tasks.md`
 ## Verification
 - Static verification:
  - Confirmed explicit phase checkpoint and stage-completion rules exist in `SKILL.md`.
  - Confirmed Phase 2 question-pool behavior and Phase 1.5 / 2.9 cross-artifact checks exist in `phase-contracts.md`.
  - Confirmed fallback declaration and recording requirements exist in `fallbacks.md`.
  - Confirmed `workflow.md` explains the same execution-hardening model without introducing mandatory output templates.
 - OpenSpec verification:
  - Implementation/documentation tasks `1.1` to `3.2` are complete.
  - Validation tasks `4.1` to `4.4` are complete.
 ## Acceptance Scope Check
 - Satisfied by protocol/document changes alone: yes
 - Requires standardized phase-report output format: no
 - Requires fixed checkpoint/alignment templates: no
 ## Unverified
 - OpenSpec CLI validation passed: `openspec validate sm-flow-execution-hardening`.
 - No automated tests were needed because this change only modifies protocol and documentation artifacts.
 ## Archive Status
 - OpenSpec change is not archived.
 - User still needs to be asked whether to archive after validation is complete.
@@ -0,0 +1,31 @@
 # SM Flow Execution Hardening Brief
 ## 背景
 - 用户目标：把 `sm-flow` 在真实项目执行中暴露出的流程失真问题，提炼为下一轮协议硬化需求。
 - 当前问题：`sm-flow` 已经具备完整阶段规则，但实际执行时仍会出现跳过检查点、弱化显式声明、问题池不足、Cross-artifact 一致性检查不充分等情况。
 - 关联 OpenSpec：`openspec/changes/sm-flow-execution-hardening/`
 - devflow 分档：complex
 ## 范围
 - 本次要做：把复盘中的执行问题整理为结构化需求，明确目标、非目标、用户故事、验收口径和建议改进方向。
 - 本次不做：立即修改 `sm-flow` 协议、直接创建 OpenSpec change、重写 `sm-flow` 主设计。
 - 影响区域：
  - `.agents/skills/sm-flow/SKILL.md`
  - `.agents/skills/sm-flow/references/phase-contracts.md`
  - `.agents/skills/sm-flow/references/fallbacks.md`
  - `.agents/skills/sm-flow/references/templates.md`
  - `skill-workbench/docs/sm-flow/workflow.md`
  - `skill-workbench/docs/sm-flow/retrospective.md`
 ## OpenSpec 对齐
 - proposal 覆盖状态：已覆盖
 - specs 覆盖状态：已覆盖
 - tasks 覆盖状态：已覆盖
 ## 入口摘要
 - 这次需求关注的不是 `sm-flow` 的理念是否成立，而是它在真实执行中为什么仍然会“按代码习惯行动”，而不是“按 phase gate 行动”。
 - 目标是把这些问题固化为更强的执行约束，让后续代理在 `micro` 或 `standard` 模式下也不再轻易跳过关键阶段。
@@ -0,0 +1,76 @@
 # SM Flow Execution Hardening Decisions
 ## User-interview
 | 问题 | 用户回答 | 决策 | OpenSpec 回写 |
 | --- | --- | --- | --- |
 | 这次是否将复盘问题提炼为正式需求？ | “[$sm-flow] 提炼成需求” | 创建 `sm-flow-execution-hardening` 需求档案，先收敛需求，再决定是否进入 OpenSpec。 | 不影响 |
 | 是否必须产出固定 checkpoint / alignment 模板？ | “确认 1” | 不强制固定模板；协议只要求必填字段和检查动作。 | 已回写 |
 | 验收是否要求统一阶段汇报格式？ | “确认1” | 验收停在协议明确 gate、问题池和对齐规则，不要求统一阶段汇报格式。 | 已回写 |
 ## Phase 2 Tracking
 | 问题池项 | 模式 | 状态 | 备注 |
 | --- | --- | --- | --- |
 | Q1：是否必须产出固定 checkpoint / alignment 模板 | user-interview | 待确认 | 会影响 templates.md 与 tasks 范围 |
 | Q2：协议主术语采用 checkpoint 还是 checklist | evidence-driven | 待整理 | 优先由现有文档术语一致性决定 |
 | Q3：验收是否要求统一阶段汇报格式 | user-interview | 已确认 | 验收停在规则层，不扩到统一输出格式 |
 | Q4：workflow 是否需要保留复盘案例示例 | evidence-driven | 待整理 | 主要影响 workflow 文档粒度 |
 ## Phase 2.5 审计结论
 - 决策：主术语采用 `checkpoint`，`checklist` 作为内部核对动作描述。
  - 原因：仓库现有 `phase-contracts.md` 已使用 `Human checkpoint`，继续沿用能减少术语漂移。
  - 影响：后续协议修改应优先写“phase checkpoint”，避免在规则层混用主术语。
  - 风险接受：当前接受
 - 决策：`workflow.md` 不扩成案例手册，继续保留规则抽象和演进说明；具体复盘案例留在 `retrospective.md`。
  - 原因：如果把案例并入 workflow，规则与示例会双份维护，后续更容易漂移。
  - 影响：执行真理源继续留在 `SKILL.md` / `phase-contracts.md` / OpenSpec，而不是 workflow 长文。
  - 风险接受：当前接受
 ## Phase 2.9 Commit Result
 - 决策：`sm-flow-execution-hardening` 当前 Draft OpenSpec 通过 commit gate，视为 Committed OpenSpec。
  - 原因：proposal、design、specs、tasks 已完整；user-interview 已确认；evidence-driven 结论已汇报；未发现 devflow/OpenSpec 冲突。
  - 影响：可以进入 Phase 3 修改协议文件，但仍需单独的 apply 授权。
  - 风险接受：当前接受
 ## 关键取舍
 - 决策：将本轮定位为 `complex` 分档。
  - 原因：虽然不涉及业务代码，但它影响 `sm-flow` 的多个核心文件、阶段协议和验收方式，且包含多处跨文档一致性约束。
  - 影响：使用 `brief.md`、`prd.md`、`evidence.md`、`decisions.md` 四类产物，而不是只写简短 brief。
  - 风险接受：当前接受
 - 决策：不复用 `sm-flow-v3-1-upgrade` 项目，而是新开需求档案。
  - 原因：`v3.1` 已归档且目标不同；本轮关注的是执行稳定性，不宜混入已完成升级项目。
  - 影响：后续若进入 OpenSpec，可独立创建新 change。
  - 风险接受：当前接受
 - 决策：将“规则存在但执行不稳”定义为首要问题。
  - 原因：复盘中的多个现象都能收敛到这一点，能避免后续需求继续发散。
  - 影响：后续需求改造应优先考虑 checklist、阶段 gate、显式声明和一致性检查。
  - 风险接受：当前接受
 ## Phase 3 Implementation Record
 - 决策：Phase 3 以本地 `openspec-apply-change` `SKILL.md` 作为 capability 来源继续执行。
  - 原因：当前环境可读取对应 skill 协议，且用户已通过“apply”明确授权进入 Phase 3。
  - 影响：本轮实现按 committed OpenSpec 的 task 切片直接修改协议与工作流文档。
  - 风险接受：当前接受
 - 决策：本轮不修改 `templates.md`。
  - 原因：用户已确认不要求固定 checkpoint / alignment 模板，也不要求统一阶段汇报格式；OpenSpec task 2.4 的目标是保持模板可选。
  - 影响：实现集中在 `SKILL.md`、`phase-contracts.md`、`fallbacks.md`、`workflow.md`，避免把协议硬化扩大成模板标准化。
  - 风险接受：当前接受
 - 决策：把“checkpoint 缺失则阶段不算完成”写入顶层协议和阶段契约，而不是只放在说明文档。
  - 原因：这是决定阶段能否前进的硬 gate，必须落在执行真理源。
  - 影响：Phase 0、0.5、1、2、2.5、2.9 现在都需要显式 checkpoint 和 capability 声明。
  - 风险接受：当前接受
 - 决策：将 Phase 2 question pool、Phase 1.5/2.9 cross-artifact 对齐、`micro` gate 保留和 fallback 记录要求同步落在协议正文与 workflow 说明。
  - 原因：这些规则既要可执行，又要便于人类理解；单独放在一处容易再次漂移。
  - 影响：OpenSpec、协议正文和 workflow 解释层的关键术语已收敛到同一套执行规则。
  - 风险接受：当前接受
@@ -0,0 +1,106 @@
 # SM Flow Execution Hardening Evidence
 ## 证据
 | 来源 | 证据 | 结论 | 是否已汇报 |
 | --- | --- | --- | --- |
 | `skill-workbench/docs/sm-flow/retrospective.md` | 逐 Phase 复盘了一次真实执行，明确记录了 Phase 0、0.5、1.5、2、2.5、2.9、4 的实际偏差。 | 当前主要问题是执行偏差和自检不足，不是流程理念方向错误。 | 是 |
 | `skill-workbench/docs/sm-flow/workflow.md` | v3.1 已经补入 Draft/Committed OpenSpec、接口影响分级、Phase 2.9、Phase 3 冲突分类等规则。 | 新一轮需求不应继续扩展原则，而应硬化执行协议。 | 是 |
 | `.agents/skills/sm-flow/SKILL.md` | 已明确 Phase 0.5、2、2.9 不可跳过，且要求显式 skill/fallback 声明。 | 当前缺口在于代理执行时没有被强制逐项核对这些规则。 | 是 |
 | `.agents/skills/sm-flow/references/phase-contracts.md` | 每个 Phase 已有进入条件、动作、退出条件和 checkpoint。 | 还缺一个更短、更高频的执行时 checklist 机制。 | 是 |
 | `.agents/skills/grill-with-docs/SKILL.md` | 明确要求 one-at-a-time 提问，并在可探索时优先查代码。 | Phase 2 的问题不是缺规则，而是没有把“问题池 + 单题推进”落成稳定动作。 | 是 |
 | `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 `SKILL.md` 更像设计说明书，缺少执行时检查点。 | 本轮需求与历史评估一致，属于同一产品化方向的继续深化。 | 是 |
 | `openspec/changes/sm-flow-execution-hardening/proposal.md` | Draft proposal 已将变更范围收敛到 phase checkpoint、问题池、cross-artifact alignment、micro gate preservation。 | Phase 1.5 已完成大方向对齐，未决问题主要落在“是否要求固定记录格式”这一类实现边界。 | 是 |
 | `openspec/changes/sm-flow-execution-hardening/design.md` | Draft design 已明确 checkpoint、问题池、cross-artifact 检查链路和 devflow 过程内同步更新。 | Phase 2 需要确认的重点不再是方向，而是边界和验收粒度。 | 是 |
 ## Evidence-driven 结论
 - 结论：`sm-flow` 当前最需要的是“执行硬化”，不是“设计重构”。
  - 证据：v3.1 已经把主从关系、gate 和冲突分类写清楚，但真实执行仍偏离。
  - 风险：如果继续增加理念说明，可能让文档更长，但不提升执行稳定性。
  - 用户确认：不需要
 - 结论：Phase 1.5 和 2.9 的 cross-artifact 检查应成为优先增强点。
  - 证据：复盘里 `proposal` 漏字段未被代理提前发现，直到用户 review 才暴露。
  - 风险：如果这两层不稳，Phase 2 即使问得更全，问题仍会漏到 apply 前后。
  - 用户确认：不需要
 - 结论：`micro` 模式的误用是本次偏差的重要诱因。
  - 证据：复盘根因明确指出“高估了小改动判断，误以为 micro 可以跳检查”。
  - 风险：若不把这点写得更硬，后续类似问题会重复出现。
  - 用户确认：不需要
 ## Phase 1.5 对齐检查
 - `brief/prd` -> `proposal`：已对齐
  - 覆盖了执行硬化而非主设计重构、影响文件范围、非目标边界。
 - `proposal` -> `design`：已对齐
  - 设计已展开 checkpoint、问题池、cross-artifact alignment、micro gate preservation 和 devflow 过程内更新。
 - `design` -> `specs`：已对齐
  - 已拆出 `sm-flow-phase-checkpoints`、`sm-flow-question-pool`、`sm-flow-cross-artifact-alignment`、`sm-flow-micro-gate-preservation` 四个 capability spec。
 - `specs` -> `tasks`：部分对齐，仍有一个边界待确认
  - 当前 tasks 写了“如有需要则更新模板”，但是否必须定义固定记录格式，尚未明确。
 - `specs` -> `tasks`：现已对齐
  - 用户已确认这轮不强制固定模板，也不把统一阶段汇报格式纳入验收，因此 tasks 保持“协议强化优先，模板仅按需微调”。
 ## Phase 2 Question Pool
 - Q1 `user-interview` / 范围：
  - 这次 change 是否必须产出固定的 checkpoint / alignment 记录模板，还是只要求协议定义必填字段即可。
  - 状态：已确认为后者。
 - Q2 `evidence-driven` / 术语：
  - `phase checkpoint`、`phase checklist`、`stage-completion rule` 三个说法里，哪个作为协议中的主术语最稳。
 - Q3 `user-interview` / 验收：
  - 验收是以“文档明确要求这些门禁”为准，还是要进一步要求代理输出统一格式的阶段汇报。
  - 状态：已确认采用前者。
 - Q4 `evidence-driven` / 边界：
  - 这次是否需要把 retrospective 中的具体案例映射到 workflow 文档中的示例，还是只保留规则层抽象。
 ## Phase 2.5 架构审计
 - 输入 -> 处理 -> 输出链路
  - `retrospective.md` / 现有 `sm-flow` 协议 / 已归档 OpenSpec change
  - -> `SKILL.md` 核心规则、`phase-contracts.md` 阶段契约、`fallbacks.md` 降级协议、按需 `templates.md`
  - -> `workflow.md` 设计说明、`devflow` 过程记录、最终可提交的 OpenSpec
 - 模块职责
  - `.agents/skills/sm-flow/SKILL.md`：放短而硬的总规则、gate 和主从关系。
  - `.agents/skills/sm-flow/references/phase-contracts.md`：放逐阶段的进入/动作/退出条件与 checkpoint。
  - `.agents/skills/sm-flow/references/fallbacks.md`：放 capability 不可用时的降级协议和记录要求。
  - `.agents/skills/sm-flow/references/templates.md`：只放稳定模板，不承载这轮的主逻辑。
  - `skill-workbench/docs/sm-flow/workflow.md`：保留设计说明和演进脉络，不承载执行真理源。
 - 架构风险评估
  - 当前最大风险不是规则缺失，而是把同一条规则分散到 `SKILL.md`、`phase-contracts.md`、`workflow.md` 后出现漂移。
  - 这轮 change 如果把“checkpoint”同时做成规则、模板和示例，容易再次扩大维护面。
  - 更稳的做法是让 `SKILL.md` 和 `phase-contracts.md` 成为主落点，`workflow.md` 只解释，不重复列执行细则。
  - `templates.md` 应保持可选和轻量，否则会把“协议硬化”扩成“输出格式标准化”。
 - 审计结论与当前 Draft OpenSpec 一致，不需要新增 capability，只需要在实现时严格控制规则落点。
 ## Phase 2.9 Commit Gate
 - proposal：通过
  - 已覆盖变更原因、范围、非目标、关键边界，以及“不强制固定模板 / 不要求统一阶段汇报格式”的范围约束。
 - design：通过
  - 已覆盖 checkpoint、问题池、cross-artifact alignment、micro gate preservation、devflow 过程内更新和规则落点分层。
 - specs：通过
  - 已覆盖四个新增 capability，且行为描述集中在可观察的协议要求。
 - tasks：通过
  - 已覆盖协议修改、workflow 更新、校验和验收边界验证。
 - user-interview：通过
  - 两个需要用户确认的问题均已确认并回写。
 - evidence-driven：通过
  - 术语与 workflow 粒度问题已通过现有文档证据收束。
 - devflow / OpenSpec 冲突：未发现
 结论：当前 Draft OpenSpec 已达到可执行状态，可视为 Committed OpenSpec，进入 Phase 3 前仅缺明确 apply 授权。
 ## Phase 3 Apply Evidence
 | 来源 | 证据 | 结论 | 是否已汇报 |
 | --- | --- | --- | --- |
 | `.agents/skills/sm-flow/SKILL.md` | 已新增显式 checkpoint 完成规则、question pool 规则、cross-artifact 对齐规则、`micro` gate 保留规则和 devflow 分阶段更新规则。 | 顶层协议已把执行硬化从“建议”提升为阶段完成条件。 | 是 |
 | `.agents/skills/sm-flow/references/phase-contracts.md` | 已新增 Phase 1.5 对齐链检查、Phase 2 问题池建立、Phase 2.9 闭环复核、Phase 3 capability 启动汇报和 Phase 4 consolidation 约束。 | 逐阶段执行契约已经覆盖 committed OpenSpec 的核心要求。 | 是 |
 | `.agents/skills/sm-flow/references/fallbacks.md` | 已新增统一 fallback 记录要求，并在各 fallback 协议中补入记录动作。 | 降级执行现在是可见、可审计的协议事件。 | 是 |
 | `skill-workbench/docs/sm-flow/workflow.md` | 已新增 question pool、Phase Checkpoint、Cross-Artifact Alignment、Micro 不是 Skip、fallback 记录要求等说明。 | retrospective 中的经验已被提升为稳定规则，而不是仅停留在叙述层。 | 是 |
 | `openspec/changes/sm-flow-execution-hardening/tasks.md` | 已完成 1.1-3.2，文档实现范围已落地。 | Phase 3 的协议/文档实现部分已完成，剩余工作转入验证与验收。 | 是 |
@@ -0,0 +1,67 @@
 # SM Flow Execution Hardening PRD
 ## 问题陈述
 `sm-flow` 已经定义了较完整的阶段、规则和 reference 文件，但在真实项目执行中，代理仍然会把它当成“有帮助的流程建议”，而不是“必须逐阶段满足的执行协议”。结果是：
 - Phase 0 没有形成入口摘要和已知影响区域。
 - Phase 0.5 没有及时初始化和维护 `devflow/` 项目档案。
 - Phase 1 没有显式声明 skill 或 fallback，Draft / Committed OpenSpec 的边界不稳定。
 - Phase 1.5 被跳过，导致 proposal / design / research / specs / tasks 之间的一致性缺口直到用户 review 才暴露。
 - Phase 2 虽然收集了证据，但没有以结构化问题池和 one-at-a-time 的方式稳定执行。
 - Phase 2.5 被跳过，架构链路和接口影响没有提前暴露。
 - Phase 2.9 缺少强制自检，无法可靠发现 cross-artifact 遗漏。
 这说明当前痛点不是缺少理念，而是缺少“执行时自检”和“阶段切换门禁”的产品化机制。
 ## 解决方案
 为 `sm-flow` 增加一轮“执行硬化”需求，目标是让代理在实际使用中更难偏离阶段协议。重点不是新增更多解释，而是把现有规则压缩成更可执行、更可检查、更可暴露偏差的约束，例如：
 - 每个阶段结束必须有简短 checklist / checkpoint。
 - 未显式声明 skill 或 fallback 视为该阶段未完成。
 - Phase 2 先生成问题池，再按 one-at-a-time 消费。
 - Phase 1.5 / 2.9 引入更明确的 cross-artifact diff 检查。
 - `micro` 明确只能压缩产物，不得跳过关键 gate。
 - devflow 产物默认在过程内同步更新，而不是拖到 Phase 4 补写。
 ## 用户故事
 1. 作为使用 `sm-flow` 的开发者，我希望代理在进入下一阶段前自动暴露“已满足/未满足”的条件，这样我能尽早发现流程偏差。
 2. 作为使用 `sm-flow` 的开发者，我希望 `micro` 模式仍然保留关键 gate，这样小改动不会因为“看起来简单”而漏掉重要检查。
 3. 作为使用 `sm-flow` 的开发者，我希望 Phase 2 先形成问题池，再逐个提问，这样既符合 human-in-the-loop 约束，也能避免只问了少数问题就错误收尾。
 4. 作为使用 `sm-flow` 的开发者，我希望 Phase 1.5 和 2.9 能可靠检查 proposal / design / specs / tasks / evidence / decisions 的一致性，这样问题能在 apply 前暴露，而不是等我 review。
 ## 实现决策
 - 决策：本轮先把“执行硬化”提炼成需求，而不是直接进入文档改造。
  - 原因：当前已掌握足够多的真实使用反馈，需要先明确问题边界和验收标准，再决定是否开新 OpenSpec change。
  - 影响：下一步可以更顺畅地进入 `sm-flow` 的正式改造，而不是边讨论边补规则。
 - 决策：把重点放在 phase gate、自检、问题池和一致性检查，而不是继续扩展 `sm-flow` 的理念层说明。
  - 原因：复盘显示失真主要来自执行习惯和缺少检查，而不是原则方向错误。
  - 影响：后续改动应优先落在 `SKILL.md`、`phase-contracts.md` 和模板/检查清单，而不是重写 workflow 长文。
 ## 测试决策
 - 好测试应该通过审查 `sm-flow` 协议文本和执行产物，验证代理是否被强制带到正确的阶段检查点。
 - 必须覆盖：
  - `micro` 模式下 gate 不可跳过
  - Phase 2 问题池与 one-at-a-time 提问
  - skill/fallback 显式声明要求
  - Phase 1.5 / 2.9 cross-artifact 检查
  - devflow 过程内同步更新
 - 不测试：
  - 业务代码实现结果
  - OpenSpec CLI 本身的功能正确性
 ## 非目标
 - 不在本轮定义新的业务流程。
 - 不在本轮替换 OpenSpec-first / Devflow-assisted 主设计。
 - 不要求为所有小改动增加更重的文档负担。
 ## 补充说明
 - 这轮需求直接来源于一次真实项目执行复盘，因此它比理念讨论更贴近代理实际失真模式。
 - 如果后续进入 OpenSpec，建议 change 名可沿用 `sm-flow-execution-hardening`。
@@ -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 归档确认：待询问
@@ -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 退出条件文件验证）。
@@ -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 的执行依据
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-05-21
@@ -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 冲突分类会暂停执行 → 这是刻意设计；暂停一次比悄悄把规格改歪更便宜。
@@ -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/` 索引功能。
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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` |
 ## 架构审计
 - **风险**：无跨模块依赖，纯前端改动
 - **缓解**：不适用
@@ -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 事件）
 - 清空筛选时重置所有控件（包括排序）
@@ -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** 不需要点击"应用"按钮
@@ -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] 浏览器验证：测试清空筛选重置排序
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-05-22
@@ -0,0 +1,115 @@
 ## Context
 这次 change 处理的是 `sm-flow` 的执行稳定性，而不是流程理念重构。已有文档已经定义了阶段顺序、Phase 2.9、接口影响、实现期冲突分类和 devflow 索引，但真实使用表明，规则如果没有变成“阶段切换前必须显式满足的条件”，就会在执行中被代理惯性绕开。
 受影响的主要文件位于：
 - `.agents/skills/sm-flow/SKILL.md`
 - `.agents/skills/sm-flow/references/phase-contracts.md`
 - `.agents/skills/sm-flow/references/fallbacks.md`
 - `.agents/skills/sm-flow/references/templates.md`
 - `skill-workbench/docs/sm-flow/workflow.md`
 这次改造的规则落点也需要明确分层：
 - `SKILL.md` 承载短而硬的总规则和 gate。
 - `phase-contracts.md` 承载逐阶段进入、动作、退出和 checkpoint。
 - `fallbacks.md` 承载 capability 不可用时的降级协议与记录要求。
 - `templates.md` 只在确有必要时提供轻量字段提示，不承载主逻辑。
 - `workflow.md` 只解释设计与演进背景，不重复执行细则或承担执行真理源职责。
 ## Design
 ### 1. Phase checkpoints as executable gates
 为每个关键阶段引入最小 checkpoint，要求代理在阶段结束时显式汇报：
 1. 当前阶段名称。
 2. 本阶段调用的 skill / 本地 `SKILL.md` / fallback。
 3. 本阶段产物。
 4. 已满足的退出条件。
 5. 未满足但仍阻塞下一阶段的问题。
 这个 checkpoint 不是替代现有 `phase-contracts.md`，而是把长契约压缩成执行中更容易遵守的门禁动作。
 本次设计只要求这些 checkpoint 具备明确字段和动作，不要求新增统一模板或统一展示格式。
 ### 2. Skill/fallback declaration becomes a completion condition
 现有规则要求进入某些阶段时说明 skill 或 fallback，但执行中容易被忽略。硬化后：
 - 若本阶段未显式声明使用的能力来源，则阶段不得视为完成。
 - 若发生 fallback，必须同时记录：目标 skill、不可用原因、采用的 fallback 协议、降级风险。
 ### 3. Phase 2 uses a question pool
 现有规则强调 one-at-a-time，但没有约束问题覆盖面。硬化后，Phase 2 先生成问题池，再逐个消费：
 - 问题池至少覆盖术语、边界、验收。
 - 对复杂任务，可继续覆盖权限、上下游触发、前端返回结构、兼容性、生命周期等。
 - `user-interview` 问题仍然一次只问一个，但问题池必须先暴露计划覆盖面。
 这样既保留 human-in-the-loop 约束，也降低“只问了几个问题就误以为够了”的风险。
 ### 4. Cross-artifact alignment becomes explicit
 Phase 1.5 和 2.9 需要明确检查的对齐关系：
 - `brief/prd` -> `proposal`
 - `proposal` -> `design`
 - `design` -> `specs`
 - `specs` -> `tasks`
 - `evidence/decisions` -> OpenSpec 回写状态
 如果任何链路出现信息缺失、术语不一致、能力未落到 spec、spec 未落到 task，都必须在进入下一阶段前暴露。
 ### 5. Micro mode preserves gates
 `micro` 继续允许合并产物，但明确禁止跳过：
 - Phase 0.5 最小上下文检查
 - Phase 2 最小澄清
 - Phase 2.9 commit gate
 - Phase 4 轻量归档
 这次 change 不增加 `micro` 的文档负担，而是把“不能跳哪些 gate”写得更硬。
 ### 6. Devflow updates happen during the flow
 `devflow` 不再被视为“最后补文档”。设计上要求：
 - Phase 0 写入口摘要到 `brief.md`
 - Phase 2 写 evidence / decisions
 - Phase 2.5 写架构审计摘要
 - Phase 2.9 写 commit gate 结果
 - Phase 4 只做汇总和归档收尾
 这样 Phase 4 变成收敛，而不是返工。
 ### 7. Rule placement avoids duplication drift
 本次 change 的一个隐含架构约束是避免同一规则在多个层面双份维护：
 - 如果某条规则属于执行门禁，应优先落在 `SKILL.md` 或 `phase-contracts.md`。
 - 如果某条规则属于 capability 降级，应优先落在 `fallbacks.md`。
 - `workflow.md` 可以解释为什么这样设计，但不应再逐条复制执行细则。
 - `templates.md` 保持可选和轻量，否则会把“协议硬化”扩大成“格式标准化”。
 这能降低 v3.1 之后再次出现“规则已经写了，但代理仍然执行漂移”的维护风险。
 ## Risks / Trade-offs
 - 更强的 checkpoint 会增加少量流程显式成本，但可以换来更低的遗漏率。
 - 问题池可能让 Phase 2 看起来更正式，但如果不先暴露覆盖面，one-at-a-time 容易退化成随机追问。
 - 更硬的 cross-artifact 检查会让 change 前期更慢，但比在 apply 前后由用户兜底更可靠。
 - 如果把同一规则同时写进协议、模板和案例说明，后续维护面会再次变大，因此这轮需要严格控制规则落点。
 ## Validation
 需要通过文档与 OpenSpec 产物验证以下结果：
 - `sm-flow` 明确要求阶段 checkpoint。
 - `micro` 明确禁止跳过关键 gate。
 - Phase 2 明确先形成问题池，再一次一问推进。
 - Phase 1.5 / 2.9 明确 cross-artifact 检查链路。
 - devflow 的过程内同步更新要求被写入协议。
 - 不要求代理额外输出统一格式的阶段汇报示例。
@@ -0,0 +1,47 @@
 ## Why
 `sm-flow` 已经建立了 `OpenSpec-first / Devflow-assisted` 的主从关系，也补入了 Draft/Committed OpenSpec、接口影响分级、Phase 2.9 和实现期冲突分类等关键规则。但真实项目复盘显示，代理仍然会按“先读代码、先形成方案、尽快推进实现”的习惯行动，而不是稳定经过 phase gate、自检和一致性检查。
 当前问题不是主设计方向错误，而是执行协议还不够“硬”：
 - `micro` 模式容易被误解为可以跳过关键阶段。
 - skill/fallback 声明存在规则，但没有成为阶段完成条件。
 - Phase 2 有 one-at-a-time 约束，但没有先形成问题池，导致问题覆盖不足。
 - Phase 1.5 和 2.9 的 cross-artifact 检查缺少更明确的执行清单，遗漏只能等用户 review 才暴露。
 - devflow 产物容易被拖到 Phase 4 补写，而不是在过程内同步更新。
 因此需要新增一轮“执行硬化”改造，把现有规则收敛成更明确的阶段检查点、问题池机制和一致性检查要求。
 ## What Changes
 - 为 `sm-flow` 增加更短、更高频的 phase checklist / checkpoint 规则。
 - 明确“未显式声明 skill 或 fallback = 本阶段未完成”。
 - 为 Phase 2 增加“先形成问题池，再一次一问推进”的要求。
 - 强化 Phase 1.5 / 2.9 的 cross-artifact diff 检查，覆盖 proposal、design、specs、tasks、brief、evidence、decisions 的一致性。
 - 明确 `micro` 只能压缩产物，不能跳过 Phase 0.5、Phase 2、Phase 2.9 等关键 gate。
 - 明确 devflow 默认在各阶段同步更新，而不是拖到 Phase 4 统一补写。
 - 明确本次改造不强制固定 checkpoint / alignment 模板，也不把统一阶段汇报格式纳入验收范围。
 ## Capabilities
 ### New Capabilities
 - `sm-flow-phase-checkpoints`: 定义各阶段的最小检查点和阶段完成条件。
 - `sm-flow-question-pool`: 定义 Phase 2 的问题池生成与单题推进规则。
 - `sm-flow-cross-artifact-alignment`: 定义 Phase 1.5 / 2.9 的跨产物一致性检查要求。
 - `sm-flow-micro-gate-preservation`: 定义 `micro` 模式下不可跳过的关键 gate。
 ### Modified Capabilities
 - `sm-flow-commit-gate`: 增强提交前检查，补充 cross-artifact diff 和阶段状态显式确认。
 - `sm-flow-context-indexing`: 补充 devflow 过程内同步更新要求。
 ## Impact
 - 修改 `.agents/skills/sm-flow/SKILL.md`
 - 修改 `.agents/skills/sm-flow/references/phase-contracts.md`
 - 修改 `.agents/skills/sm-flow/references/fallbacks.md`
 - 可能修改 `.agents/skills/sm-flow/references/templates.md`
 - 修改 `skill-workbench/docs/sm-flow/workflow.md`
 - 不修改业务代码
 - 不改变 `OpenSpec-first / Devflow-assisted` 主设计
@@ -0,0 +1,29 @@
 ## ADDED Requirements
 ### Requirement: Phase 1.5 checks cross-artifact alignment explicitly
 SM Flow SHALL explicitly check alignment across requirement, design, specification, and execution artifacts during Phase 1.5.
 #### Scenario: Alignment check runs
 - **WHEN** Phase 1.5 reviews the current Draft OpenSpec
 - **THEN** it checks that `brief/prd` aligns with `proposal`, `proposal` aligns with `design`, `design` aligns with `specs`, and `specs` align with `tasks`
 #### Scenario: Alignment gap is found
 - **WHEN** an expected behavior, term, field, constraint, or implementation slice appears in one artifact but not its downstream artifact
 - **THEN** the flow marks the gap explicitly and repairs OpenSpec before entering the next phase
 ### Requirement: Phase 2.9 validates cross-artifact closure
 SM Flow SHALL re-check cross-artifact closure during Phase 2.9 before implementation.
 #### Scenario: Commit gate runs
 - **WHEN** Phase 2.9 evaluates whether Draft OpenSpec can become Committed OpenSpec
 - **THEN** it verifies that `evidence.md` and `decisions.md` findings that affect implementation are reflected in proposal, design, specs, or tasks
 #### Scenario: User review would otherwise catch the gap
 - **WHEN** a field, scope item, acceptance behavior, or design constraint is missing from the downstream OpenSpec artifacts
 - **THEN** the flow SHALL fail the commit gate and return to the earlier phase that owns the missing update
@@ -0,0 +1,30 @@
 ## ADDED Requirements
 ### Requirement: Micro mode compresses artifacts but preserves critical gates
 SM Flow SHALL allow `micro` mode to reduce artifact weight without skipping critical gates.
 #### Scenario: Micro mode starts
 - **WHEN** a change is classified as `micro`
 - **THEN** the flow may merge or simplify devflow artifacts
 - **AND** it SHALL still perform Phase 0.5 minimum context harvest, Phase 2 minimum clarification, Phase 2.9 commit gate, and Phase 4 lightweight backfill
 #### Scenario: Micro mode is treated as skip permission
 - **WHEN** the agent attempts to skip a critical gate because the change is small or low-risk
 - **THEN** the flow SHALL treat that as a protocol deviation rather than a valid micro-mode optimization
 ### Requirement: Devflow updates happen during the flow
 SM Flow SHALL update devflow artifacts during the relevant phases rather than deferring all updates to Phase 4.
 #### Scenario: Phase-local information is produced
 - **WHEN** a phase produces entry summary, evidence, decisions, architecture findings, or commit-gate conclusions
 - **THEN** the corresponding devflow artifact is updated in or near that phase
 #### Scenario: Phase 4 begins
 - **WHEN** the flow enters Phase 4
 - **THEN** devflow backfill is primarily a consolidation step rather than the first time those records are written
@@ -0,0 +1,34 @@
 ## ADDED Requirements
 ### Requirement: Each critical phase has an explicit checkpoint
 SM Flow SHALL require an explicit checkpoint before a critical phase can be considered complete.
 #### Scenario: Phase completes normally
 - **WHEN** the agent finishes a critical phase such as Phase 0, Phase 0.5, Phase 1, Phase 2, Phase 2.5, or Phase 2.9
 - **THEN** it reports the current phase, the capability source used, the produced artifacts, the satisfied exit conditions, and any unresolved blockers
 #### Scenario: Checkpoint is missing
 - **WHEN** a critical phase has produced artifacts or conclusions but no explicit checkpoint summary
 - **THEN** the phase SHALL NOT be treated as complete for purposes of entering the next phase
 ### Requirement: Capability declaration is part of phase completion
 SM Flow SHALL treat skill or fallback declaration as part of the phase completion condition.
 #### Scenario: Native skill or local protocol is used
 - **WHEN** a phase depends on a named capability such as `openspec-propose`, `grill-with-docs`, `zoom-out`, or `openspec-apply-change`
 - **THEN** the agent states whether it used a native skill, a local `SKILL.md`, or a fallback protocol
 #### Scenario: Fallback is used
 - **WHEN** a phase falls back from a named capability
 - **THEN** the agent records the target capability, the reason it was unavailable, the fallback protocol name, and the downgrade risk
 #### Scenario: Declaration is omitted
 - **WHEN** no capability source is declared for a phase that requires one
 - **THEN** that phase SHALL NOT be considered complete
@@ -0,0 +1,29 @@
 ## ADDED Requirements
 ### Requirement: Phase 2 builds a question pool before interviewing
 SM Flow SHALL build a Phase 2 question pool before consuming `user-interview` questions one at a time.
 #### Scenario: Phase 2 starts
 - **WHEN** the flow enters Phase 2
 - **THEN** it defines a question pool that covers at least terminology, scope boundaries, and acceptance
 #### Scenario: Complex change needs deeper coverage
 - **WHEN** the change affects multiple modules, interfaces, permissions, downstream consumers, response structures, or lifecycle rules
 - **THEN** the Phase 2 question pool also includes those dimensions before user-interview consumption begins
 ### Requirement: User-interview questions remain one-at-a-time
 SM Flow SHALL preserve the one-question-at-a-time rule while using a question pool.
 #### Scenario: User-interview question is asked
 - **WHEN** the next unresolved `user-interview` item is selected from the question pool
 - **THEN** the flow asks exactly one question, waits for the explicit user answer, records the result, and only then advances to the next `user-interview` item
 #### Scenario: Question pool exists but answer is missing
 - **WHEN** there are remaining question-pool items and the current `user-interview` question is unanswered
 - **THEN** the flow SHALL NOT ask another `user-interview` question until the current one is resolved
@@ -0,0 +1,24 @@
 ## 1. OpenSpec artifacts
 - [x] 1.1 Write proposal for `sm-flow-execution-hardening`
 - [x] 1.2 Write design for execution hardening rules
 - [x] 1.3 Add specs for checkpoints, question pool, cross-artifact alignment, and micro gate preservation
 ## 2. Protocol hardening
 - [x] 2.1 Update `.agents/skills/sm-flow/SKILL.md` with explicit phase checkpoint and stage-completion rules
 - [x] 2.2 Update `.agents/skills/sm-flow/references/phase-contracts.md` with question pool, cross-artifact alignment, and micro gate preservation rules
 - [x] 2.3 Update `.agents/skills/sm-flow/references/fallbacks.md` so fallback declaration is mandatory and recorded
 - [x] 2.4 Keep templates optional; only adjust them if existing references need minimal field hints rather than mandatory fixed formats
 ## 3. Workflow documentation
 - [x] 3.1 Update `skill-workbench/docs/sm-flow/workflow.md` with the execution-hardening model
 - [x] 3.2 Ensure retrospective learnings are reflected as protocol rules rather than only narrative notes
 ## 4. Validation
 - [x] 4.1 Validate the OpenSpec change
 - [x] 4.2 Verify key terms are consistently documented across skill, references, and workflow docs
 - [x] 4.3 Backfill devflow records after implementation if the change proceeds beyond Draft
 - [x] 4.4 Verify acceptance is satisfied by protocol/document changes alone, without requiring a standardized phase-report output format
@@ -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
@@ -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"，降低执行复杂度同时保留核心约束。
@@ -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: 待补充)
@@ -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 跳过阶段"问题，提升流程可靠性。
@@ -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 一次性补。两者是同一件事的两面，不是先后关系
@@ -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 阶段规范即可生效。
@@ -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 和门控文件后，我就很难"偷懒"了。
@@ -1,4 +1,62 @@
-# 增强版工作流总结
+# SM-Flow 工作流
 ## 当前设计理念（v4 方向）
 **核心定位**：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 + 归档确认） |
 **内部阶段（9 个，英文动词命名）**：
 ```
 clarify → context → propose → grill → specify → audit → commit → apply → archive
 入口澄清   上下文     轻量提案   澄清    细化      审计    提交     执行    归档
 ```
 阶段名是 harness 的内部协议词汇（用于 checkpoint 汇报和进度通知），不是用户 API。用户只需知道 4 个命令，其余通过自然语言交互，由 harness 识别意图后编排。
 **关键设计决策**：
 - **真理源分层**：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**：快速模式合并 gate（clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill 最少 1 个问题 → commit 简化检查），但保留最关键的门控。
 - **质量约束可观测**：质量约束必须转化为可观测产出（写入文件 + checkpoint 检查），否则不是约束而是建议。
 **使用方式**：
 详细的使用说明见 [使用方式.md](./使用方式.md)，包括：
 - 4 个用户命令的典型场景
 - 完整规划 → 执行 → 归档的分次调用示例
 - 自然语言交互方式
 - 规模分档（micro / standard / complex）
 - devflow 自动维护机制
 - OpenSpec 集成与 Draft/Committed 分离
 - 常见问题解答
 ---
 ## 演进历史
 以下是 sm-flow 工作流的历史演进记录，从 v1 到当前 v4 方向。每一版都从真实执行失败中提炼，不是理论推演。
 ## 旧工作流 vs 新工作流
@@ -378,6 +436,682 @@ 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 阶段开始前增加 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 实现过程增强
 **分步实现**：建议按 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% |
 | 实现时间（含返工） | 2 小时 | 1.5 小时 | -25% |
 | 前置调研时间 | 0 分钟 | 15-20 分钟 | +20 分钟 |
 **ROI 分析**：
 ```
 投入：15-20 分钟调研
 回报：节省 60 分钟返工 + 避免核心功能遗漏
 ROI = (60 - 20) / 20 = 200%
 ```
 ### 复杂度评估
 **本次修改复杂度**：中等
 - 文本增量：+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 分档的简单需求（可缩短为 5-10 分钟）
 - 纯数据处理或工具脚本（技术栈熟悉）
 ❌ **不推荐**：
 - 紧急热修复（时间紧急）
 - 一次性脚本（不涉及项目标准）
 ### 相关文档
 - 执行复盘：`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，或明确跳过（需显式确认）
 #### 修改 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`
@@ -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) — 真实痛点收集
@@ -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实施过程中的沟通？
@@ -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 产物链接和是否归档。
@@ -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？
@@ -34,12 +34,20 @@
 1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
 2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
-3. 修改前先检查现有代码。
+3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
-4. 一次实现一个 OpenSpec task 的纵向切片。
+4. 确认 Phase 2.9 后已经获得用户明确的 Phase 3 apply 授权；单个 grill 决策确认不能替代 apply 授权。
-5. 用最窄但有效的命令验证每个切片。
+5. 修改前先检查现有代码。
-6. 只有验证通过或明确记录原因后，才更新 task 状态。
+6. 一次实现一个 OpenSpec task 的纵向切片。
-7. 如果失败原因不确定，停止并进入 diagnose。
+7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，先分类：
-8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
+   - 实现偏差：OpenSpec 正确，代码偏离；修代码。
   - 规格遗漏：OpenSpec 未覆盖真实边界、接口影响或验收；暂停执行，修正 OpenSpec 并重新提交后继续。
   - 设计冲突：OpenSpec 与架构、ADR、历史验收或模块边界冲突；暂停并等待用户确认。
   - 用户变更：用户改变目标、范围、验收或风险接受度；更新 proposal/specs/tasks 后继续。
 8. 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
 9. 用最窄但有效的命令验证每个切片。
 10. 只有验证通过或明确记录原因后，才更新 task 状态。
 11. 如果失败原因不确定，停止并进入 diagnose。
 12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
 ## PRD fallback
@@ -28,6 +28,8 @@
 **进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
 **动作**：
 - 优先读取 `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。
@@ -36,6 +38,7 @@
 **退出条件**：
 - 已形成“OpenSpec 输入上下文摘要”。
 - 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
 - 已列出相关 ADR 和不能违反的历史决策。
 - 已列出需要写入或修正 OpenSpec 的上下文点。
@@ -46,7 +49,7 @@
 **进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
-**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
+**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 `openspec-propose` 的 `SKILL.md` / fallback 降级。
 **动作**：
 - 优先调用 `openspec-propose`。
@@ -64,7 +67,7 @@
 - 关键假设已显式记录在 OpenSpec 或 research 中。
 **输出**：
- OpenSpec proposal、design、specs 和 task list。
+- Draft OpenSpec proposal、design、specs 和 task list。
 **Human checkpoint**：
 - 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
@@ -85,11 +88,16 @@
  - OpenSpec 是否遵守相关 ADR。
  - specs 是否能表达可观察行为。
  - tasks 是否能驱动实现，而不是泛泛描述。
 - 检查是否涉及接口影响：
  - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
  - 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
  - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 `user-interview` 问题。
 - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
 **退出条件**：
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - OpenSpec 与 PRD/devflow 上下文没有已知冲突。
 - 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
 - 所有已知冲突已修正或等待用户决策。
 **输出**：
@@ -110,6 +118,10 @@
  - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
 - 至少覆盖三个维度：术语、边界、验收。
 - 一次只问一个 `user-interview` 问题。
 - 每个 `user-interview` 问题必须等待用户显式回答，并把回答、决策和 OpenSpec 回写状态记录到 `decisions.md`；不能由代理代替用户确认。
 - 未获得用户确认的 `user-interview` 问题必须保持未解决状态，不能进入 Phase 2.9 或 Phase 3。
 - 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 Phase 3 或修改执行目标文件的授权。
 - 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
 - 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
 - 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
 - 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
@@ -118,6 +130,8 @@
 - 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
 - 没有未解决或代理代确认的 user-interview 问题。
 - 没有未判级或未确认的接口影响问题。
 - 影响实现的结论已回写 OpenSpec。
 **输出**：
@@ -148,14 +162,46 @@
 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
+- 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。
 ## Phase 2.9 — Commit OpenSpec
 **进入条件**：
 - Phase 2 已解决术语、边界、验收三个维度的高价值问题。
 - 所有 `user-interview` 问题都已获得用户显式确认。
 - Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因。
 - Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
 **动作**：
 - 检查 proposal 是否说明为什么做、做什么、范围和非目标。
 - 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
 - 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
 - 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
 - 检查接口影响是否已按 L1/L2/L3/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
 - 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
 - 如果检查失败，返回 Phase 1、Phase 2 或 Phase 2.5 修正 Draft OpenSpec。
 **退出条件**：
 - Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
 - Phase 3 所需的 proposal、design、specs 和 tasks 均存在且一致。
 - 所有 Phase 3 preflight 风险已消除或明确记录为已接受。
 **输出**：
 - Committed OpenSpec 状态说明。
 - Phase 3 preflight 检查结果，默认写入 `decisions.md` 或 `acceptance.md`。
 **Human checkpoint**：
 - 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
 - 询问是否进入 Phase 3 OpenSpec apply；除非用户在启动时明确要求“全自动执行”，必须等待用户明确说出进入 apply、开始实现、执行修改、继续 Phase 3 或等价授权。
 - 不得把 Phase 2 的单个 grill 决策确认当作本 checkpoint 的授权。
 ## Phase 3 — OpenSpec apply
 **进入条件**：
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
+- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已通过 Phase 2.9，成为 Committed OpenSpec。
- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
+- Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。
 - devflow 与 OpenSpec 没有未解决冲突。
 - 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
 **显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
@@ -163,6 +209,12 @@
 - 优先调用 `openspec-apply-change`。
 - 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
 - 按 OpenSpec tasks 的纵向切片实现。
 - 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续：
  - 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。
  - 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。
  - 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。
  - 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。
 - 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
 - 当用户要求、行为复杂或回归风险高时使用 TDD。
 - 当测试失败、行为意外或原因不确定时使用 diagnose。
 - 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
@@ -170,6 +222,7 @@
 **退出条件**：
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
 - 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。
@@ -188,10 +241,12 @@
 - 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
 - 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
 - 如果本次流程产生可复用经验，写入 compound knowledge。
 - 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。
 **退出条件**：
 - `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
 - `devflow/index.md` 已包含或更新本项目条目。
 - 用户已被询问是否 archive OpenSpec change。
 **输出**：
@@ -65,6 +65,68 @@
  - 风险接受：{accepted by whom/when}
 ```
 ## 接口影响记录模板
 ```markdown
 # {标题} 接口影响记录
 ## 分级
 - 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口
 - 判级原因：{why this level}
 - 是否需要独立接口文档：是 / 否
 ## 变更对象
 - 接口/字段/DTO/事件/回调/数据库契约：
 - 判断逻辑变化：
 - 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无
 ## 影响范围
 - 调用方/消费者：
 - 是否跨模块/跨服务/跨团队：
 - 旧调用方是否需要改动：
 ## 兼容与迁移
 - 是否向后兼容：
 - 迁移/灰度/回滚要求：
 - 风险接受：
 ## 验收方式
 - 如何证明新行为正确：
 - 如何证明旧行为未破坏：
 - 需要用户确认的问题：
 ```
 ## 实现期冲突记录模板
 ```markdown
 # {标题} 实现期冲突记录
 ## 冲突摘要
 - 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
 - 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
 - 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更
 ## 证据
 - OpenSpec 依据：
 - 代码或测试证据：
 - 用户反馈：
 ## 处理
 - 决策：
 - 是否需要用户确认：是 / 否
 - OpenSpec 回写：不需要 / 已回写 / 待回写
 - 代码处理：
 - 验证方式：
 ```
 ## PRD 模板
 ```markdown
@@ -1,259 +0,0 @@
 ---
 name: essence
 description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups.
 metadata:
  version: "0.5.0"
 ---
 # Essence: Extract Core Design Patterns
 Prefix your first line with 🥷 inline, not as its own paragraph.
 You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing.
 **This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else.
 ## Mode Selection
 First, check whether an `/explore` result exists:
 - `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode.
 - No `/explore` result → this is an independent launch, default to **Auto-detect**.
 Always confirm before proceeding:
 | Mode | When | Entry |
 |---|---|---|
 | **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for |
 | **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design |
 | **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens |
 ### Lens definitions
 | Lens | Core question | Guided behavior |
 |---|---|---|
 | **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces |
 | **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs |
 | **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers |
 A lens shapes which sources to read and how to frame the output, but does not add separate phases.
 ### Auto-detect signals
 A design is "essence" if it passes 2 or more of these signals:
 | Signal | Evidence |
 |---|---|
 | README highlights it prominently | "Built on a plugin architecture" as a headline feature |
 | Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author |
 | Heavily discussed in Issues/PRs | Design decisions debated by community |
 | Unique among similar projects | Competitors don't do it this way |
 | Rich design comments in code | JSDoc/TSDoc explaining why, not what |
 | Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. |
 | File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic |
 | Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths |
 **"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is.
 If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead."
 ## Phase 1: Locate
 **User-directed mode:**
 - Go directly to the directory or file the user names.
 - If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative.
 **Auto-detect mode:**
 - Scan README, CLAUDE.md, and top-level docs for architecture claims.
 - Identify 1-2 standout design directions.
 - Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?"
 - If user doesn't choose, pick the strongest one and state why.
 **Lens-guided mode:**
 - Confirm the lens with the user (Mechanical/Intentional/Evolution).
 - Frame the search in terms of the lens.
 - Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern."
 **Output:** 1-2 design directions to analyze + lens confirmation.
 **Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project.
 ## Phase 2: Deep Dive
 Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides.
 **For each file:**
 - What role does it play in this design?
 - What interfaces does it expose?
 - How does it connect to other parts of the system?
 **Trace the call chain:**
 - Start from the entry point that uses this design.
 - Follow the flow until you understand the full pattern.
 - Stop when you hit boilerplate, config, or test files.
 **Output:** Core file list (≤10) + call chain + lens-specific annotations.
 **Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead.
 ## Phase 3: Extract Pattern
 Analyze the design at a higher level. Let the lens shape the analysis angle:
 - **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts
 - **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale)
 - **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events
 **Universal analysis dimensions** (all lenses):
 - **Problem:** What specific problem does this design solve? What was the pain before?
 - **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.)
 - **Alternatives:** What simpler or more complex approaches could solve the same problem?
 - **Tradeoffs:** Why did the author choose this? What does it give up?
 - **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.)
 **Output:** Design pattern card (lens-framed).
 **Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report.
 ## Phase 4: Migrate
 Make the learning actionable. Let the lens tailor the output:
 - **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs)
 - **Intentional** → decision framework (checklist for evaluating tradeoffs)
 - **Evolution** → migration path (step-by-step refactor plan)
 **Universal deliverables** (all lenses):
 - **Can you use this?** Is the design applicable to the user's own projects? If not, why?
 - **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example.
 - **Pitfalls:** What context does this design depend on? What would break if you copy it blindly?
 **Output:** Migration example + pitfall list (lens-tailored).
 **Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code.
 ## Phase 5: Self-review
 Check the report is honest:
 **All modes:**
 - [ ] The design is real (not inferred, not imagined). Evidence: specific files cited.
 - [ ] The analysis is deep enough that you could explain it out loud.
 - [ ] The migration example captures the core idea, not surface syntax.
 - [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere").
 **Stall signals (any one → return to relevant phase):**
 - Cannot name a file that proves the pattern → back to Phase 2
 - Cannot explain why it's better than alternatives → back to Phase 3
 - Migration example is over 20 lines → simplify, back to Phase 4
 - Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase
 **Output:** Essence report with lens annotation.
 ## Optional: HTML Card
 **Only when the user explicitly requests it.**
 Generate an HTML visualization card as a shareable deliverable.
 ### HTML Card Structure (Glassmorphism 2.0 - Essence Variant)
 ```html
 <!DOCTYPE html>
 <html lang="zh-CN">
 <head>
  <meta charset="UTF-8">
  <title>{Project Name} - Essence Report</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
  <style>
    /* Same glassmorphism styles as /explore */
    :root { --glass-bg: rgba(255,255,255,0.4); --primary: #8b5cf6; }
    [data-theme="dark"] { --glass-bg: rgba(15,23,42,0.6); --primary: #a78bfa; }
    .glass-panel { backdrop-filter: blur(12px); border-radius: 1rem; }
    .pattern-diagram { font-family: monospace; background: rgba(0,0,0,0.03); }
  </style>
 </head>
 <body class="p-8">
  <nav class="fixed top-4 left-1/2 -translate-x-1/2 w-[90%] max-w-4xl glass-panel z-50 px-6 py-3">
    <span class="font-bold text-xl">💎 {Project Name} 精华</span>
    <span class="text-sm opacity-70">Lens: {lens} | Pattern: {pattern_name}</span>
  </nav>
  <main class="max-w-4xl mx-auto mt-24 space-y-6">
    <section class="glass-panel p-6">
      <h2 class="text-xl font-bold mb-4">🎯 Design Analyzed</h2>
      <p>{one-line description}</p>
    </section>
    <section class="glass-panel p-6">
      <h2 class="text-xl font-bold mb-4">🔷 Pattern ({lens})</h2>
      <!-- Lens-framed pattern card -->
    </section>
    <section class="glass-panel p-6">
      <h2 class="text-xl font-bold mb-4">🔗 Call Chain</h2>
      <pre class="mermaid">{diagram}</pre>
    </section>
    <section class="glass-panel p-6">
      <h2 class="text-xl font-bold mb-4">📦 Migration Example</h2>
      <pre class="pattern-diagram"><code>{code_example}</code></pre>
      <p class="text-sm opacity-70 mt-2">Pitfalls: {pitfalls}</p>
    </section>
  </main>
  <script>mermaid.initialize({ startOnLoad: true });</script>
 </body>
 </html>
 ```
 ### Output Format
 ```markdown
 ### HTML Card Generated
 - **Path:** `outputs/{project}-essence.html`
 - **Theme:** {modern/ink}
 - **Accent Color:** Purple (essence = jewel)
 ```
 **When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead.
 ---
 ## Hard Rules
 - **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment.
 - **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough.
 - **Stop after the report.** Do not modify the user's project or the target project.
 - **HTML is optional.** Do not block analysis on HTML generation.
 ## Gotchas
 | What happened | Rule |
 |---|---|
 | 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 |
 | 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 |
 | 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` |
 | Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 |
 | 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 |
 | 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 |
 | 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 |
 | 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 |
 | HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 |
 ## Outcome
 ```
 Essence Report: {project name}
 Lens: mechanical / intentional / evolution
 Design analyzed: {one-line description}
 Files examined: {count}
 Pattern: {pattern name or custom description}
 Migration: {steal-it example, ≤20 lines}
 HTML generated: yes / no
 Status: complete
 ```
 After the report, stop. No modifications. No follow-ups.
@@ -1,79 +0,0 @@
 # Essence Detection Signals
 How to identify the standout design in a project when the user doesn't specify a direction.
 ## Signal Strength
 A design passes the "essence" threshold if it scores 2+ signals.
 ### Strong Signals (score = 1 each)
 | Signal | How to detect | Example |
 |---|---|---|
 | **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" |
 | **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` |
 | **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts |
 | **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments |
 | **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning |
 ### Objective Signals (score = 1 each, no subjective judgment needed)
 | Signal | How to detect | Example |
 |---|---|---|
 | **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package |
 | **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic |
 | **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" |
 ### Weak Signals (score = 0.5 each)
 | Signal | How to detect | Example |
 |---|---|---|
 | **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence |
 | **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" |
 | **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine |
 | **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object |
 ## Not Signals
 These do NOT count as essence:
 - "Clean code" or "well organized" — that's quality, not design
 - "Uses TypeScript" — that's a language choice, not architecture
 - "Has good tests" — that's engineering discipline, not design
 - "Many stars on the repo" — popularity ≠ design quality
 - "Uses the latest framework" — following trends ≠ standing out
 - Utility functions — even well-written ones are tools, not designs
 ## Auto-detect Procedure
 When the user says "find the essence":
 1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate.
 2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate.
 3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core.
 4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity.
 5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently?
 6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest.
 ### Example Output Format
 ```
 Standout designs in {project}:
 A) {Design A name} — evidenced by {README claim / file / doc}
   What it does: {one sentence}
 B) {Design B name} — evidenced by {code comment / unique feature / community discussion}
   What it does: {one sentence}
 Which should we dive into? (or I can pick the strongest)
 ```
 ## Failure Modes
 | Situation | Response |
 |---|---|
 | No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." |
 | User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. |
 | Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." |
 | Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." |
@@ -1,87 +0,0 @@
 ---
 name: explore
 description: Invoke when you need project-level understanding and an onboarding path. Produces a project learning report for code and non-code repositories with fixed phases for positioning, structure, flow, start path, and core designs. Not for deep code extraction or interactive teaching.
 metadata:
  version: "0.5.0"
 ---
 # Explore: Project Understanding and Onboarding
 Prefix your first line with 🥷 inline, not as its own paragraph.
 You are a project cartographer. Your job is to help the user understand what a project is, why it is worth studying, how it is organized, and where to start.
 `/explore` is the entry point for first contact with a repository or project-like artifact. It builds global understanding. It does not perform code-level essence extraction and it does not run interactive teaching.
 ## Project Type Detection
 After the initial scan, classify the target before continuing:
 | Type | Signals | What changes |
 |---|---|---|
 | **Code repository** | `go.mod`, `pyproject.toml`, `Cargo.toml`, source directories, executable entrypoints | Run all 4 phases |
 | **Skill / docs / knowledge repository** | `SKILL.md`, mostly Markdown, docs-first structure, no runnable application entrypoint | Skip Phase 2 (Flow) and Phase 3 (Start Path) |
 | **Template / scaffold repository** | Starter files, minimal logic, setup-first repo | Phase 2 may stay structural and Phase 3 may be minimal |
 State the detected type before proceeding. If uncertain, say what evidence is missing and continue with the closest matching type.
 ## Phase 1: Positioning & Structure
 - What this project is, why it is worth studying, and who it is for.
 - Top-level structure: main modules, documents, directories, and the likely learning entry area.
 - Tradeoffs vs alternatives when evidence exists.
 ## Phase 2: Flow
 **Code repositories only.**
 - Skip for non-code and template repositories.
 - Trace the main runtime or request flow.
 - Produce at least one architecture or core-flow diagram.
 - Keep the trace focused on the golden path rather than exhaustive coverage.
 ## Phase 3: Start Path
 **Code repositories only when runnable or meaningfully inspectable.**
 - Provide the minimal path to start learning or running the project.
 - Give the first command or first inspection step.
 - Suggest one safe first modification or observation point when appropriate.
 ## Phase 4: Core Designs
 - Summarize 2-3 core implementations or ideas.
 - Keep this at overview depth.
 - For each item, include what it is, where it lives, and why it matters.
 ## Minimum Deliverables
 The final `/explore` report must include:
 - Project positioning
 - Why it is worth studying
 - 2-3 core implementations or core ideas
 - Tradeoffs or comparisons when applicable
 - At least 1 diagram:
  - code repository → architecture diagram or core flow diagram
  - non-code repository → structure diagram, idea map, or workflow diagram
 ## Boundary Rules
 `/explore` may:
 - scan structure
 - explain the main flow
 - provide a minimal start path
 - summarize 2-3 core designs
 `/explore` must not:
 - perform `/essence`-level deep extraction
 - act as `/follow`-style guided teaching
 - include Verify, Deep Fission, or HTML Output phases
 - preserve no retired lightweight fallback behavior
 ## Outcome
 ```
 Explore Report: {project name}
 Project type: code / skill-docs / template
 Phases completed: 4/4 (or note skipped code-only phases)
 Diagram included: yes / no
 Core designs: 2-3
 Status: complete
 ```
 After the report, stop. Do not proceed to `/essence` or `/follow` automatically.
@@ -1,98 +0,0 @@
 # Project Analysis Methods
 How to read and understand an unfamiliar code project.
 ## 1. Identify the Entry Point
 Every project has a door. Find it first.
 ### By Language
 | Language | Look for |
 |---|---|
 | **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` |
 | **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` |
 | **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` |
 | **Rust** | `src/main.rs` or `src/bin/*.rs` |
 | **Java** | Class with `public static void main(String[] args)` |
 | **C/C++** | `main()` function, conventionally in `src/main.c` |
 | **Swift** | `main.swift` or file with `@main` attribute |
 ### In Frameworks
 | Framework | Entry point |
 |---|---|
 | Next.js | `app/` or `pages/` directory, `next.config.js` |
 | React (Vite) | `src/main.tsx` or `src/main.jsx` |
 | Vue (Vite) | `src/main.ts` or `src/main.js` |
 | Express | File that calls `app.listen()` |
 | FastAPI | File that creates `FastAPI()` instance |
 | Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` |
 | Flask | `app.py` or `app/__init__.py` |
 | Spring Boot | `*Application.java` with `@SpringBootApplication` |
 ## 2. Judge Project Complexity
 Don't over-engineer simple projects. Don't under-analyze complex ones.
 ### Simple (<50 files, single language)
 - Read every source file.
 - No need for flow diagrams beyond a simple sequence.
 - A light `/explore` pass is probably enough.
 ### Standard (50-500 files, 1-2 languages)
 - Read entry point + core modules + 1-2 feature files.
 - Build 1-2 flow diagrams.
 - `/explore` is the right level.
 ### Complex (>500 files, multi-language, monorepo)
 - Read entry point + architecture docs + one representative module.
 - Use `/essence` to find standout designs, or `/explore` for one package at a time.
 - Do NOT try to understand the whole project in one pass.
 ## 3. Separate Core Code from Scaffolding
 Not all files are worth reading.
 ### Ignore (scaffolding)
 - `*.config.js`, `*.config.ts` — configuration, not logic
 - `dist/`, `build/`, `out/` — generated output
 - `node_modules/`, `vendor/`, `.venv/` — dependencies
 - `*.lock`, `yarn.lock`, `go.sum` — lock files
 - `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta
 - `test/fixtures/`, `test/data/` — test data
 ### Read (core)
 - Entry point file
 - Router/middleware/config handlers
 - Model/entity/schema definitions
 - Core algorithm or business logic files
 - Files referenced most in imports
 ### Hint: Follow imports
 ```
 entry file → import A → import B → core logic
 ```
 Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core.
 ## 4. Read Unfamiliar Framework Code
 You don't know every framework. That's fine.
 ### Strategy
 1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities.
 2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response.
 3. **Identify the framework's conventions.** Most frameworks follow a pattern:
   - MVC: Controller → Model → View
   - Middleware: Request → Middleware chain → Handler → Response
   - Component: Parent renders children, props flow down, events flow up
   - Plugin: Core calls hooks, plugins register handlers
 4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose.
 5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented.
@@ -1,173 +0,0 @@
 # Flow Pattern Library
 Common architecture patterns and how to identify them in code.
 ## MVC / MVVM / MVX
 ### What it is
 Separation of data (Model), UI/presentation (View), and coordination logic (Controller/ViewModel).
 ### File signatures
 | Pattern | Directories/Files |
 |---|---|
 | **MVC** | `controllers/`, `models/`, `views/` |
 | **MVVM** | `viewmodels/`, `views/`, `models/` |
 | **Layered** | `app/`, `domain/`, `infrastructure/` (Clean/Hexagonal) |
 ### Flow
 ```
 Request → Controller → Model (data) → View (render) → Response
 ```
 ### Key question
 "Does the file handle data, display, or coordination?" If yes → MVC-family.
 ---
 ## Middleware Chain
 ### What it is
 Each handler processes the request and passes it to the next. Like an assembly line.
 ### File signatures
 | Framework | Indicator |
 |---|---|---|
 | **Express/Koa** | `app.use(...)`, `app.get('/', handler)` |
 | **FastAPI** | `@app.middleware("http")`, `Depends()` |
 | **Next.js** | `middleware.ts` at root or in `app/` |
 | **Gin (Go)** | `router.Use(middleware1, middleware2)` |
 | **Koa** | `app.use(async (ctx, next) => { ... })` |
 ### Flow
 ```
 Request → Middleware A → Middleware B → Handler → Response
               ↓              ↓
          auth check     log request
 ```
 ### Key question
 "Does this function call `next()` or pass control to something else?" If yes → middleware.
 ### Common middleware order
 ```
 1. CORS / Security headers
 2. Logging / Request ID
 3. Authentication / Authorization
 4. Body parsing / Validation
 5. Rate limiting
 6. Route handler
 7. Error handler (catches everything above)
 ```
 ---
 ## Plugin / Extension System
 ### What it is
 Core provides hooks or interfaces. External code registers handlers. The core doesn't know about specific plugins.
 ### File signatures
 | Pattern | Indicator |
 |---|---|
 | **Hook-based** | `registerHook('eventName', handler)`, `hooks.on('event', fn)` |
 | **Interface-based** | Abstract class or interface that plugins implement |
 | **Discovery-based** | Directory scan (`plugins/`), import all, register by convention |
 | **VSCode-style** | `contributes` in `package.json`, activation events |
 ### Flow
 ```
 Core starts
    ↓
 Scans for plugins
    ↓
 Each plugin registers itself
    ↓
 Core fires hooks → plugins respond
    ↓
 Core runs with extended capabilities
 ```
 ### Key question
 "Can I add functionality without modifying core code?" If yes → plugin architecture.
 ---
 ## Event-Driven
 ### What it is
 Components communicate through events, not direct calls. Publishers emit, subscribers listen.
 ### File signatures
 | Pattern | Indicator |
 |---|---|
 | **Node EventEmitter** | `eventEmitter.on('event', handler)`, `eventEmitter.emit('event', data)` |
 | **Pub/Sub** | `pubsub.subscribe('channel', handler)`, `pubsub.publish('channel', data)` |
 | **Redux-style** | `dispatch(action)`, `reducer(state, action) → newState` |
 | **Observable** | `observable.subscribe(fn)`, `pipe(map, filter)` |
 | **Signals (Python)** | `@signal.connect`, `signal.send()` |
 ### Flow
 ```
 Component A emits "user.created"
    ↓
 Listener B hears it → sends welcome email
 Listener C hears it → creates default settings
 Listener D hears it → logs analytics
 ```
 ### Key question
 "Does code communicate without importing or calling each other directly?" If yes → event-driven.
 ---
 ## State Management
 ### What it is
 Centralized storage for application state. Components read and update through defined interfaces.
 ### File signatures
 | Pattern | Indicator |
 |---|---|
 | **Redux** | `createStore()`, `dispatch()`, `useSelector()`, `@reduxjs/toolkit` |
 | **Zustand** | `create((set) => ({ ... }))` |
 | **Jotai** | `atom(value)`, `useAtom(atom)` |
 | **MobX** | `@observable`, `@action`, `@computed` |
 | **React Context** | `createContext()`, `useContext()`, `Provider` |
 | **Pinia (Vue)** | `defineStore()`, `state`, `actions` |
 ### Flow
 ```
 Component dispatches action
    ↓
 Reducer processes action + current state
    ↓
 New state emitted
    ↓
 Subscribed components re-render
 ```
 ### Key question
 "Where does the app store data that multiple components need?" If it's a single store → state management pattern.
 ---
 ## Pipeline / Chain of Responsibility
 ### What it is
 Data flows through a series of processors. Each processor transforms the data and passes it on.
 ### File signatures
 | Pattern | Indicator |
 |---|---|
 | **Stream processing** | `.pipe(transform1).pipe(transform2)` |
 | **Compiler/lexer** | Source → Tokenize → Parse → Transform → Generate |
 | **Data pipeline** | `input → transform → validate → output` |
 | **Makefile** | Target depends on prerequisites, each is a step |
 ### Flow
 ```
 Raw input → Tokenizer → Parser → Transformer → Generator → Output
 ```
 ### Key question
 "Does data get progressively transformed through a fixed sequence of steps?" If yes → pipeline.
@@ -1,120 +0,0 @@
 #!/usr/bin/env bash
 # Collect project structure for /explore analysis.
 # Usage: Run from project root, or pass project path as argument.
 # Output: Structured text with directory tree, file counts, language distribution.
 set -euo pipefail
 PROJECT_DIR="${1:-.}"
 cd "$PROJECT_DIR"
 echo "=== PROJECT STRUCTURE ==="
 echo ""
 # Directory tree (depth 3, exclude common noise)
 echo "--- Directory Tree (depth 3) ---"
 if command -v tree &>/dev/null; then
    tree -L 3 \
        -I "node_modules|vendor|.git|dist|build|out|.venv|__pycache__|*.egg-info|coverage|.nyc_output" \
        --dirsfirst
 elif command -v find &>/dev/null; then
    find . -maxdepth 3 \
        -not -path "./.git/*" \
        -not -path "./node_modules/*" \
        -not -path "./vendor/*" \
        -not -path "./dist/*" \
        -not -path "./build/*" \
        -not -path "./out/*" \
        -not -path "./.venv/*" \
        -not -path "*/__pycache__/*" \
        -not -path "*/.egg-info/*" \
        -not -path "*/coverage/*" \
        -not -path "./.nyc_output/*" \
        -print | head -100 | sort
 fi
 echo ""
 echo "=== FILE COUNTS ==="
 echo ""
 # Count files by extension (top 10)
 echo "--- Top 10 File Types ---"
 find . -type f \
    -not -path "./.git/*" \
    -not -path "./node_modules/*" \
    -not -path "./vendor/*" \
    -not -path "./dist/*" \
    -not -path "./build/*" \
    -not -path "./out/*" \
    -not -path "./.venv/*" \
    -not -path "*/__pycache__/*" \
    -printf '%f\n' | \
    sed 's/.*\.//' | \
    grep -v '^\.[^/]*$' | \
    sort | uniq -c | sort -rn | head -10
 echo ""
 echo "=== TOTAL FILE COUNT ==="
 echo ""
 # Total files (excluding noise)
 total=$(find . -type f \
    -not -path "./.git/*" \
    -not -path "./node_modules/*" \
    -not -path "./vendor/*" \
    -not -path "./dist/*" \
    -not -path "./build/*" \
    -not -path "./out/*" \
    -not -path "./.venv/*" \
    | wc -l)
 echo "Total source files: $total"
 echo ""
 echo "=== DEPENDENCY FILES ==="
 echo ""
 # List dependency declaration files found
 for dep_file in "package.json" "requirements.txt" "pyproject.toml" "setup.py" "go.mod" "go.sum" "Cargo.toml" "Cargo.lock" "pom.xml" "build.gradle" "Gemfile" "Gemfile.lock" "composer.json"; do
    if [ -f "$dep_file" ]; then
        echo "FOUND: $dep_file"
    fi
 done
 # Check for workspace/monorepo configs
 echo ""
 echo "=== WORKSPACE / MONOREPO ==="
 echo ""
 for ws_file in "turbo.json" "nx.json" "lerna.json" "pnpm-workspace.yaml" "go.work"; do
    if [ -f "$ws_file" ]; then
        echo "FOUND: $ws_file"
    fi
 done
 # Check Cargo.toml for workspace
 if [ -f "Cargo.toml" ] && grep -q '\[workspace\]' Cargo.toml 2>/dev/null; then
    echo "FOUND: Cargo.toml [workspace]"
 fi
 echo ""
 echo "=== ENTRY POINTS ==="
 echo ""
 # Try to identify entry points
 if [ -f "package.json" ]; then
    main=$(node -e "try{const p=require('./package.json');console.log(p.main||'');}catch(e){}" 2>/dev/null || echo "")
    bin=$(node -e "try{const p=require('./package.json');console.log(typeof p.bin==='string'?p.bin:JSON.stringify(p.bin));}catch(e){}" 2>/dev/null || echo "")
    dev=$(node -e "try{const p=require('./package.json');console.log(p.scripts?.dev||p.scripts?.start||'');}catch(e){}" 2>/dev/null || echo "")
    [ -n "$main" ] && echo "package.json main: $main"
    [ -n "$bin" ] && echo "package.json bin: $bin"
    [ -n "$dev" ] && echo "package.json dev/start: $dev"
 fi
 for entry in "src/main.ts" "src/main.tsx" "src/main.js" "src/main.jsx" "src/index.ts" "src/index.js" "src/main.py" "app/main.py" "main.go" "src/main.rs" "app.py" "index.js" "index.ts"; do
    if [ -f "$entry" ]; then
        echo "FOUND: $entry"
    fi
 done
 echo ""
 echo "=== COLLECTED ==="
@@ -1,101 +0,0 @@
 ---
 name: follow
 description: Invoke when the user wants an interactive learning session based on an existing `/explore` or `/essence` report. Guides runnable or reader-style follow-along sessions. Not for fresh project analysis or pattern-only extraction.
 metadata:
  version: "0.5.0"
 ---
 # Follow: Guided Learning Session
 Prefix your first line with 🥷 inline, not as its own paragraph.
 You are a guide. The user wants to learn from a project step by step with help, context, and correction. You guide the learning process, but you do not replace it.
 `/follow` is not a fresh project analyzer. It only works from an existing `/explore` or `/essence` result.
 ## Pre-check
 `/follow` only works when there is already an `/explore` report or an `/essence` report.
 - `/explore` report exists → use it as the main learning path
 - `/essence` report exists → use it for design-focused guided study
 - Neither exists → refuse clearly
 Refusal behavior:
 "I need an existing `/explore` or `/essence` result before I can guide a follow-along session. Please run `/explore` for project understanding or `/essence` for a focused deep dive first."
 Load the existing report before continuing.
 ## Mode Selection
 After the pre-check, select one mode based on the prerequisite report:
 - From `/explore` + code repository → default **Runnable**
 - From `/explore` + non-code repository → force **Reader**
 - From `/essence` → default **Reader** (user is in design-analysis state)
 | Mode | When | Entry |
 |---|---|---|
 | **Runnable** | Report confirms the project is a runnable code repository and the user wants to learn by running and changing it | Start from environment and first execution |
 | **Reader** | Project has no runtime, or the user is studying design/architecture, or the prerequisite report is from `/essence` | Start from guided reading |
 State the selected mode before proceeding. Do not re-scan the project — use the prerequisite report to decide.
 ## Teaching Interaction Rules
 `/follow` must teach by guidance, not by dumping answers:
 - explain the purpose of the current step first
 - give the user an observation point or action point
 - ask the user to predict, try, or explain before revealing the answer
 - then reveal, correct, or deepen the explanation
 - never say "go read the code" as a standalone instruction. When referencing code, always start with: what design idea this code embodies, why it matters in the overall architecture, and what the user should pay attention to
 ## Runnable Check
 Before Runnable mode, confirm from the **prerequisite report** (do not re-scan the project):
 - If the report identified the target as a code repository with a recognized runtime (`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile`, `build.gradle`, `pom.xml`, `CMakeLists.txt`, etc.), proceed with Runnable.
 - If the report classified it as non-code, or no runtime entrypoint was found, switch to Reader and explain why.
 - If the prerequisite is `/essence`, confirm with the user: essence is design-focused, Reader is the natural fit. Allow Runnable only if the user explicitly insists.
 - Do not introduce a third mode.
 ## Runnable Mode Flow
 1. Confirm environment and prerequisites.
 2. Let the user run the project.
 3. Let the user make one safe change.
 4. Walk the main flow together.
 5. Give one small exercise.
 6. Review what they learned.
 ## Reader Mode Flow
 1. Frame the learning goal around a core design or architectural idea, not a single file.
 2. Walk through the design concept layer by layer: problem → approach → implementation → tradeoff.
 3. Ask the user questions that probe understanding ("Why did the author choose this approach over a simpler one?"), not just prediction ("What happens next?").
 4. Use diagrams or structured summaries to connect the dots between files and design ideas.
 5. Give one reasoning exercise that tests whether the user can apply the design pattern elsewhere.
 6. Review what they learned.
 ## Boundary Rules
 `/follow` must:
 - depend on `/explore` or `/essence`
 - guide the user interactively
 - adapt between code and non-code repositories through Runnable or Reader emphasis
 `/follow` must not:
 - rescan the whole project as a new analyzer
 - reference retired skills as prerequisites
 - add any third learning mode
 - execute commands or write code for the user
 ## Outcome
 ```
 Follow Session: {project name}
 Mode: runnable / reader
 Prerequisite report: /explore or /essence
 Exercise result: completed / partial / too hard
 Next direction: {suggested follow-up}
 Status: complete
 ```
 After the review, stop. Ask whether the user wants another exercise or wants to end the session.
@@ -1,113 +0,0 @@
 # Environment Detection Rules
 How to detect the runtime environment and guide the user through setup in `/follow`.
 ## Language Detection from Config
 Check these files in order. The first match is the primary language.
 | Config file | Language | Runtime check | Install command |
 |---|---|---|---|
 | `package.json` | JavaScript/TypeScript | `node --version` | nvm or official installer |
 | `pyproject.toml` | Python | `python --version` | pyenv or python.org |
 | `go.mod` | Go | `go version` | golang.org/dl |
 | `Cargo.toml` | Rust | `rustc --version` | rustup |
 | `pom.xml` | Java | `java -version` | SDKMAN or official |
 | `build.gradle` / `build.gradle.kts` | Java/Kotlin | `java -version` | SDKMAN |
 | `Gemfile` | Ruby | `ruby --version` | rvm or rbenv |
 | `*.csproj` | C#/.NET | `dotnet --version` | .NET SDK |
 | `CMakeLists.txt` | C/C++ | `gcc --version` or `clang --version` | System package manager |
 | `swift package.json` | Swift | `swift --version` | Xcode or swift.org |
 ## Dependency Installation
 Once language is detected, guide the user:
 ### JavaScript/TypeScript
 ```bash
 # Check which package manager is used
 if [ -f "yarn.lock" ]; then yarn install
 elif [ -f "pnpm-lock.yaml" ]; then pnpm install
 elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then bun install
 else npm install
 fi
 ```
 ### Python
 ```bash
 # Modern Python projects
 pip install -e .
 # Or with requirements
 pip install -r requirements.txt
 # Or with poetry
 poetry install
 # Or with uv
 uv pip install -r requirements.txt
 ```
 ### Go
 ```bash
 go mod download
 ```
 ### Rust
 ```bash
 cargo build
 ```
 ### Java (Maven)
 ```bash
 mvn install
 ```
 ### Java (Gradle)
 ```bash
 ./gradlew build
 # or
 gradle build
 ```
 ## Run Command Detection
 How to start the project:
 | Source | Command |
 |---|---|
 | `package.json` → `scripts.dev` | `npm run dev` |
 | `package.json` → `scripts.start` | `npm start` |
 | `Makefile` → `dev` target | `make dev` |
 | `Makefile` → `run` target | `make run` |
 | `pyproject.toml` (Poetry) | `poetry run python main.py` |
 | `go.mod` → `package main` | `go run main.go` |
 | `Cargo.toml` → `[[bin]]` | `cargo run` |
 | `docker-compose.yml` exists | `docker-compose up` |
 | `Dockerfile` exists, no compose | `docker build -t app . && docker run app` |
 ## Common Environment Issues
 | Error | Cause | Fix |
 |---|---|---|
 | `command not found: node` | Node.js not installed | Install Node.js (recommend LTS) |
 | `ModuleNotFoundError` | Python deps not installed | Run `pip install -r requirements.txt` |
 | `EACCES: permission denied` | Global install without sudo | Use nvm/fnm, or prefix with sudo |
 | `ENOENT: no such file` | Wrong working directory | `cd` to project root first |
 | `port already in use` | Another process on same port | Kill the process or use different port |
 | `go: cannot find main module` | Outside Go module | `cd` to directory with `go.mod` |
 | `error: could not find Cargo.toml` | Outside Rust project | `cd` to directory with `Cargo.toml` |
 | `java.lang.UnsupportedClassVersionError` | Wrong Java version | Match JDK version to project requirement |
 | `npm ERR! code ERESOLVE` | Dependency conflict | Try `npm install --legacy-peer-deps` |
 ## Detection Script for /follow
 ```bash
 # Quick environment check
 echo "=== Environment ==="
 node --version 2>/dev/null || echo "Node.js: not installed"
 python --version 2>/dev/null || echo "Python: not installed"
 go version 2>/dev/null || echo "Go: not installed"
 rustc --version 2>/dev/null || echo "Rust: not installed"
 java -version 2>/dev/null || echo "Java: not installed"
 echo "PWD: $(pwd)"
 ```
 Run this at the start of `/follow` Step 1 to understand what's available.
Author	SHA1	Message	Date
zhuyongxin	c9a6777340	sm-flow v4.2: add verifiable checkpoints and gate file mechanism Based on real execution review (lookup-knowledge-integration), discovered that constraints are "soft" - rules are clear but lack enforcement mechanism. Core problem: Agent can skip stages despite explicit rules saying "must not skip" Changes: 1. Commit phase: add verifiable checkpoint - File completeness check: proposal ≥50 words, design ≥1 data structure, specs ≥3 requirements, tasks ≥5 items - Consistency check: proposal concepts → design mapping, design decisions → tasks implementation - Gate file: create .committed after passing all checks 2. Apply phase: add pre-gate check - Hard constraint: check .committed file existence - If missing: report, list gaps, ask user to fix or explicitly skip - Block implementation based on incomplete OpenSpec 3. Archive phase: add mandatory execution order - 5-step checklist: devflow files → index → .archive-ready → report → archive - Self-check: verify Step 1-3 before Step 4 - Prevent "handoff first, devflow forgotten" issue New gate files: - .committed: created by commit phase, checked by apply phase - .archive-ready: created by archive Step 3 Expected impact: - Commit skip rate: -100% (explicit checklist prevents fuzzy pass) - Apply on incomplete OpenSpec: -100% (gate blocks) - Archive devflow omission: -100% (mandatory order) Design principles: - Verifiability: "executable state" → "≥50 words + ≥1 structure + ≥3 requirements" - Gate files: soft judgment → file existence check - Mandatory order: advisory "should do" → 5-step checklist "must do" Complexity: +80 lines (phase-contracts.md +40, archive-rules.md +40) Approach: turn soft constraints into hard checks, no new stages Relation to v4.1: - v4.1: solve "insufficient research causes rework" (quality issue) - v4.2: solve "lack of enforcement causes stage skipping" (process issue) Docs: - phase-contracts.md: enhanced commit + apply phases - archive-rules.md: added mandatory execution order at top - workflow.md: added v4.2 evolution chapter - phase-contracts-v4.2-changelog.md: detailed change log - sm-flow-optimization-suggestions.md: source review	2026-06-24 14:51:45 +08:00
zhuyongxin	b94ee31cb1	sm-flow v4.1: add pre-apply research checkpoint to reduce rework Based on real execution review (shandong-intent-sync), apply phase suffered from 4-5 rework cycles due to insufficient upfront research. Changes: - grill: add technical implementation dimension to question pool - apply: add mandatory pre-apply checkpoint (15-20min research) - read reference implementations thoroughly - grep key tech stack patterns - form tech stack checklist in decisions.md - apply: add incremental implementation guidance - apply: add first-module alignment check - apply: add fast-fail rule (≥2 rework → pause) Expected impact: - Rework: 4-5 cycles → 0-1 cycle (-80%) - Core feature empty impl: 100% → 0% - ROI: 200% (invest 20min, save 60min) Complexity: +55 lines to phase-contracts.md (+20%) Approach: simplified version (plan B) to balance value vs overhead Docs: - phase-contracts.md: updated grill + apply phases - workflow.md: added v4.1 evolution chapter - phase-contracts-v4.1-changelog.md: detailed change log - sm-flow-execution-review-shandong-intent-sync.md: source review	2026-06-23 11:27:32 +08:00
zhuyongxin	9b44dc1395	remove unused devflow/reference and ignore .codex - devflow/reference/ was a placeholder from initial design with no write/read rules defined across v2-v4 iterations - .codex/ is tool-generated and should not be tracked	2026-05-26 10:14:25 +08:00
zhuyongxin	63994b6440	harden sm-flow protocol and archive v4.0 validation runs - Rewrite hard constraint #1: apply must read Committed OpenSpec files as the execution source of truth - Promote sub-skill invocation to hard constraint #6; remove fallbacks.md and all degradation paths - Add file existence verification at commit and archive exit gates - Require grill question pool, evidence-driven conclusions, and user-interview confirmations to be written to decisions.md - Record v4.0 validation retrospective in workflow.md: propose overreach, sub-skill pseudo-calling, spec omitting user behavior - Archive knowledge-index-sort OpenSpec and devflow entries from prior run	2026-05-26 09:59:24 +08:00
zhuyongxin	71e0b7f801	redesign sm-flow v4.0 as protocol-layer harness - Reposition sm-flow as orchestration harness over OpenSpec lifecycle - Adopt 4 user commands (Actions, Not Phases) instead of phase numbers - Rename all stages to English verbs (clarify through archive) - Reorder execution: grill before specify to eliminate rework loops - Simplify core rules from 19 to 6 hard constraints in SKILL.md - Simplify conflict classification from 4 categories to 2+1 - Switch devflow strategy to decisions.md-only process log during execution - Upgrade micro mode from artifact compression to gate merging - Add observable outputs for quality constraints - Add design review doc and user guide - Append v4.0 changelog to workflow.md	2026-05-25 17:28:15 +08:00
zhuyongxin	1f01e30c4e	harden and streamline sm-flow protocol	2026-05-25 11:44:20 +08:00
zhuyongxin	54741dd6c0	clean obsolete skill workspace files	2026-05-21 20:17:15 +08:00
zhuyongxin	6a5520db33	upgrade sm-flow v3.1 workflow	2026-05-21 19:55:23 +08:00