upgrade sm-flow v3.1 workflow

2026-05-21 19:55:23 +08:00
parent f45122dafb
commit 6a5520db33
26 changed files with 955 additions and 40 deletions
@@ -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,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