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