osiman/git-learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

harden sm-flow protocol and archive v4.0 validation runs

Browse Source 
- 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
This commit is contained in:
zhuyongxin
2026-05-26 09:59:24 +08:00
parent 71e0b7f801
commit 63994b6440
11 changed files with 342 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/sm-flow/SKILL.md
+2 -3
View File
@@ -28,12 +28,12 @@ sm-flow → 编排层（harness）：阶段、门控、产物约束、人
以下 6 条是硬约束，违反即流程失败。其余约束按阶段定义在 `references/phase-contracts.md`。
1. **OpenSpec 是唯一执行真理源**。apply 只能基于 Committed OpenSpec 执行。Draft OpenSpec 是讨论对象，不是执行许可。
1. **OpenSpec 是唯一执行真理源**。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。
2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
3. **不得跳过 grill**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。
4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
6. **降级执行必须标注**。fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
6. **子 skill 必须显式调用**。每个阶段指定的子 skill 必须显式调用；如果子 skill 不存在，流程失败，不得静默跳过或降级执行。
每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。
@@ -55,7 +55,6 @@ sm-flow → 编排层（harness）：阶段、门控、产物约束、人
- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。
- 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
- archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
- 子 skill 无法直接调用时，读取 `references/fallbacks.md`。
## 内部阶段
.agents/skills/sm-flow/references/fallbacks.md
-134
View File
@@ -1,134 +0,0 @@
# 降级协议
当子 skill 无法直接调用时，sm-flow 使用内置执行协议接管。这不是能力缺失，而是 harness 的正常能力切换。
使用任何降级前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称。产物中也必须记录"本阶段为降级执行"。
## 降级记录要求
任何降级都必须同时满足以下记录要求：
1. 在对用户的阶段汇报里声明：
- 目标 capability
- 不可用原因
- 使用的降级协议名
2. 在 `decisions.md` 中留下同样的降级记录。
3. 如果当前阶段需要 checkpoint，则降级声明是 checkpoint 完成条件的一部分。
4. 如果没有完成这些声明和记录，该阶段不得视为已完成。
除非某个降级额外说明，否则下面各节默认继承这组通用记录要求，不再重复。
## OpenSpec 提案降级
specify 阶段调用 `openspec-propose` 不可用时使用。propose 阶段使用 sm-flow 内置协议（轻量 proposal），不需要降级。
1. 确认 `openspec/changes/{slug}/proposal.md` 已存在（propose 阶段产出）。
2. 读取 grill 阶段的 decisions.md 记录，获取已确认的需求和决策。
3. 写入 `design.md`，包含：
- 关键技术决策
- 来自 devflow 的上下文约束
- 架构约束和风险
4. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。
5. 只为外部可见行为或发生变化的需求编写 specs。
6. 确保 design/specs/tasks 与 proposal 对齐。
7. 如果存在高风险假设，在 specify checkpoint 中向用户汇报。
## OpenSpec 修正降级
当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：
1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。
2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。
3. 向用户汇报冲突和推荐修正。
4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
5. 再同步更新 devflow 文档；不要只改 devflow。
6. 额外记录冲突修正状态到 decisions.md。
## OpenSpec 执行降级
apply 阶段调用 `openspec-apply-change` 不可用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。
1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
4. 确认 commit 后已经获得用户明确的 apply 授权；单个 grill 决策确认不能替代 apply 授权。
5. 修改前先检查现有代码。
6. 一次实现一个 OpenSpec task 的纵向切片。
7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，做三类判断：
- OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停执行，修正 OpenSpec 并重新提交后继续。
- 代码偏离（实现没按 OpenSpec 做）→ 修代码。
- 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。
8. 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。
9. 用最窄但有效的命令验证每个切片。
10. 只有验证通过或明确记录原因后，才更新 task 状态。
11. 如果失败原因不确定，停止并进入 diagnose。
12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
13. 额外记录任务推进状态和验证状态。
## PRD 降级
specify 阶段调用 `to-prd` 不可用时使用。优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。
规则：
- 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。
- `brief.md` 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。
- 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。
- 额外记录是否创建了独立 `prd.md`。
## 文档化追问降级
grill 阶段调用 `grill-with-docs` 不可用时使用。
1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。
2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。
3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。
4. 对 user-interview 问题，一次只问一个并等待用户确认。
5. evidence-driven 和 user-interview 交替推进，避免攒到一起汇报。
6. 术语确认后立即更新词汇表。
7. 影响实现的澄清必须回写 proposal.md。
8. 只为难以逆转的真实权衡创建 ADR。
9. 额外记录 question pool 和已消费问题。
快速模式的最小问题：
- 术语：这个概念应该使用哪个领域术语？证据是什么？
- 边界：哪些内容明确不在范围内？是否需要用户确认？
- 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？
## 架构审计降级
audit 阶段调用 `zoom-out` 不可用时使用。产出一份短架构审计：
1. 画出输入 → 处理 → 输出。
2. 列出相关模块和调用方。
3. 识别耦合、数据所有权和生命周期风险。
4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。
5. 用不超过五句话总结最大风险。
6. 如果影响实现，回写 OpenSpec design/tasks。
7. 额外记录审计结论回写状态。
## Diagnose 降级
apply 阶段调用 `diagnose` 不可用时使用。
1. 复现问题，或捕获准确失败信息。
2. 最小化失败案例。
3. 生成 3-5 个假设，并按可能性和验证成本排序。
4. 修改代码前，先添加仪器化或定向检查。
5. 判断根因属于实现问题还是 OpenSpec 规格问题。
6. 如果是实现问题，修复被证明的最小原因。
7. 如果是规格问题，先修正 OpenSpec，再继续 apply。
8. 运行回归验证。
9. 额外记录根因分类和回归结果。
## TDD 降级
apply 阶段调用 `tdd` 不可用时使用。使用纵向切片，不要水平批量写测试：
1. 从 OpenSpec specs 中选择一个外部可见行为。
2. 写一个失败测试。
3. 实现刚好让测试通过的最小代码。
4. 只在测试通过时重构。
5. 对下一个 OpenSpec 行为重复以上步骤。
6. 额外记录当前行为切片的测试状态。
.agents/skills/sm-flow/references/phase-contracts.md
+7 -6
View File
@@ -76,7 +76,7 @@
**进入条件**：propose 已有轻量 proposal.md。
**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；降级必须标记为"文档化追问降级"。
**显式子 skill**：`grill-with-docs`。进入本阶段必须调用 `.agents/skills/grill-with-docs/SKILL.md`。
**动作**：
- 优先使用 `grill-with-docs`。
@@ -104,6 +104,7 @@
- 没有未判级或未确认的接口影响问题。
- 影响实现的结论已回写 proposal.md。
- 单个 grill 决策确认不等于 apply 授权；grill 完成后必须停在 commit，等待用户明确要求进入 apply。
- question pool、evidence-driven 结论、user-interview 确认必须写入 `decisions.md` 文件，不能只记录在对话中。
**输出**：
- 更新后的 proposal.md。
@@ -158,7 +159,7 @@
**进入条件**：specify 已退出，完整 OpenSpec 产物已存在。
**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；降级必须标记为"架构审计降级"。
**显式子 skill**：`zoom-out`。进入本阶段必须调用 `.agents/skills/zoom-out/SKILL.md`。
**动作**：
- 画出输入 → 处理 → 输出的模块链路。
@@ -202,7 +203,7 @@
**退出条件**：
- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
- apply 所需的 proposal、design、specs 和 tasks 均存在且一致。
- apply 所需的 proposal、design、specs 和 tasks 均存在且一致；commit checkpoint 必须验证文件实际存在于磁盘，如果任一文件不存在，commit 失败，返回 specify 补写。
- 所有 preflight 风险已消除或明确记录为已接受。
**输出**：
@@ -222,7 +223,7 @@
- devflow 与 OpenSpec 没有未解决冲突。
- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默降级。
**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须调用指定子 skill，不得静默跳过。
**动作**：
- 优先调用 `openspec-apply-change`。
@@ -254,7 +255,7 @@
**进入条件**：实现或规划工作已经达到可交接状态。
**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；archive 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动降级。
**显式子 skill**：`openspec-archive-change` 在用户确认 archive 后调用；archive 回填由 `sm-flow` 执行。必须调用子 skill，不得静默跳过。
**动作**：
- 遵循 `references/archive-rules.md`。
@@ -270,7 +271,7 @@
- 询问用户是否要 archive OpenSpec change；不要默认执行归档。
**退出条件**：
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md。
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
- `devflow/index.md` 已包含或更新本项目条目。
- 用户已被询问是否 archive OpenSpec change。