Harden dev-flow: pre-authorization marker, alternatives log, check script
- Record rejected answers in decision.md at the moment they are rejected - Allow explicit pre-authorized Build via a pre-authorized marker line - Land scripts/check-dev-flow.sh and derive devflow/index.md from archives - Add dev-flow process artifacts (decisions, prd) for open changes
This commit is contained in:
@@ -61,6 +61,7 @@ dev-flow 编排已有能力,**不重复实现它们**:
|
||||
|
||||
1. **澄清** —— 用 `grill-with-docs` 的方法,但按上面的 **「冲突裁决」** 覆盖它的默认:
|
||||
范围收窄(只问答案会改变产物的问题)、ADR 落点为 `decision.md`、`CONTEXT.md` 用 `devflow/glossary/` 下那份。
|
||||
**被否决的答案当场记进 `decision.md` 的 `## Alternatives considered`**(一行一条:问过什么、为什么输)——这是 Q&A 形态,见 `references/decision-note.md`)。
|
||||
2. **读上下文**:`devflow/glossary/CONTEXT.md`,并搜索 `devflow/rejected/` 与已归档的 `decision.md`——
|
||||
**避免重新提出已经被否决过的方案。**
|
||||
3. 写 `openspec/changes/<slug>/proposal.md`,并用 OpenSpec 补全 `design.md` / `specs/` / `tasks.md`。
|
||||
@@ -73,6 +74,9 @@ dev-flow 编排已有能力,**不重复实现它们**:
|
||||
|
||||
> 未获授权不得进入 Build。
|
||||
> **方案讨论中的任何一次确认,都不等于实现授权。**
|
||||
> 快节奏交付下可以预授权,但必须显式:Think 退出时在 `decision.md` 写下
|
||||
> `<!-- pre-authorized: 日期 + 范围/原因 -->`。静默跳过不允许——旁路是有意识的选择,不是遗忘。
|
||||
> 授权状态以这行标记为准,恢复会话时读它,不靠对话记忆。
|
||||
|
||||
## Build — 做出来
|
||||
|
||||
@@ -82,6 +86,7 @@ dev-flow 编排已有能力,**不重复实现它们**:
|
||||
|
||||
- 按 `tasks.md` 的纵向切片实现,按 `specs/` 验收。
|
||||
- **分步验证**:每完成一层再继续,不要一次写完再验。
|
||||
- **tasks/design 里提到"参考 XXX 实现"的,实现前先完整读它**——设计文档点名参考而实现时没看,是返工最常见的来源。
|
||||
- **冲突先分类再处理**:
|
||||
|
||||
| 分类 | 处理 |
|
||||
@@ -104,9 +109,8 @@ Build 结束**自动进入 Close**,中间不设确认点。
|
||||
|
||||
1. **补齐 `decision.md`**——把 `## Decision` 校准为**实际发布的做法**(现在时),补 `## Consequences` 和 `## Verification`。
|
||||
2. **执行收尾检查**(见下)。
|
||||
3. 有新术语 → 更新 `devflow/glossary/CONTEXT.md`。
|
||||
4. 有被否决的提案 → 写入 `devflow/rejected/<class>/`。
|
||||
5. **⏸ 确认点 2** —— 汇报产物、验证情况、剩余风险,询问是否归档。
|
||||
3. 检查澄清阶段的新术语**已**沉淀进 `devflow/glossary/CONTEXT.md`(写入时机在术语确认的当场,见「冲突裁决」;这里只查漏)。
|
||||
4. 有被否决的提案 → 确认**已在否决发生时**写入 `devflow/rejected/<class>/`(这里只兜底检查)。
|
||||
|
||||
**退出**:`decision.md` 五节齐全;收尾检查通过;用户已被询问是否归档。
|
||||
|
||||
@@ -122,7 +126,7 @@ Build 结束**自动进入 Close**,中间不设确认点。
|
||||
| **一个事实只有一个权威** | 见下表 |
|
||||
|
||||
**"非平凡"的判据**:改变行为、架构、跨文件或跨包的契约、流程或工具、测试策略、磁盘/线缆/配置格式,或其他维护者可能重新考察的决策。
|
||||
**豁免**:纯机械或局部编辑。
|
||||
**豁免**:纯机械或局部编辑。**小修不值得触发本流程**——dev-flow 是显式触发的 opt-in 流程,轻的第一道防线是不进来;后来发现重要时,允许事后补录 `decision.md`(retrofit 已验证)。
|
||||
|
||||
### 事实的唯一权威
|
||||
|
||||
@@ -153,8 +157,7 @@ Build 结束**自动进入 Close**,中间不设确认点。
|
||||
|
||||
纯机械改动可以豁免。**豁免必须显式,但可以廉价**——目的是让"跳过"变成有意识的选择,而不是静默遗忘。
|
||||
|
||||
> **计划中的自动化**:`scripts/check-dev-flow.sh`,遵循仓库现有脚本约定(`scripts/*.sh`)。
|
||||
> 在它落盘之前,上面三步手动执行。
|
||||
> **已落地**:`scripts/check-dev-flow.sh <slug>` 执行上述三项检查;`--index` 扫描归档派生 `devflow/index.md`(不手写);`--all` 检查全部活跃 change。
|
||||
|
||||
## 目录
|
||||
|
||||
@@ -166,11 +169,12 @@ openspec/changes/<slug>/
|
||||
|
||||
devflow/
|
||||
├── glossary/CONTEXT.md ← 跨项目术语
|
||||
├── rejected/<class>/ ← 未实施的提案
|
||||
└── index.md ← 由脚本扫描归档生成,不手写
|
||||
├── rejected/<class>/ ← 未实施的提案(否决发生时写入,不是 Close 时)
|
||||
└── index.md ← scripts/check-dev-flow.sh --index 派生,不手写
|
||||
```
|
||||
|
||||
`rejected/` 的保留条件:它**仍能防止一个诱人的、有意义的错误**。否则整体删除。
|
||||
**边界**:`decision.md` 的 Alternatives 记"变更内"的方案备选;`rejected/` 收"整个提案被否决"的方向。提案在确认点 1 被整个否决时,当场写入 `rejected/`——那时流程已终止,Close 不会执行。
|
||||
|
||||
## 触发规则
|
||||
|
||||
@@ -179,6 +183,7 @@ devflow/
|
||||
|
||||
不要因为任务涉及 OpenSpec、跨模块、架构决策或 devflow 目录就自动触发。
|
||||
未被这样要求之前,按普通工程任务处理。
|
||||
**`decision.md` 义务只覆盖经本流程的非平凡变更**——不经 dev-flow 的普通工程任务没有这个义务。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
Reference in New Issue
Block a user