跳到主要内容

ADR-0003 文档 frontmatter status 词表统一为 3 值

背景​

2026-06-11 FinBayes 知识治理库整改（W1-W8 八波次 cleanup）盘点 232 份 .md 文档时发现，frontmatter status: 字段实际取值高达 19 种且中英混排：

draft (63)  active (52)  accepted (30)  草稿 (29)  complete (17)
stable (11)  legacy (6)  已确认 (5)  pending (4)  已确认（M0 最小版）(3)
superseded (2)  signed (2)  working (1)  ready-to-dispatch (1)
proposed (1)  live (1)  in-progress (1)  deprecated-partial (1)
accepted-pending-research (1)

owner 反映 "FinBayes 文档分不清哪个最新、哪个废、哪个工作中"。盘点诊断：status 词表无统一定义是 owner 困惑的直接根因（详见 FinBayes 项目目录下 .cleanup-status.md §2026-06-11 重组 cleanup）。

整改期间 owner 2026-06-11 拍板：词表精简为 3 值 active / draft / archived，并由本 ADR 在 L4 治理层立法对齐所有项目。

W3（projects/finbayes）+ W6（governance/workstreams/finbayes-*）已批量执行迁移；本 ADR 把执行结果立法为协议，并对齐 governance/change-protocol.md §5 既有提到的 deprecated 状态。

级别判定​

按 变更协议 §1：影响 governance/ 且改变跨项目协议契约，定级 L4，需要 ADR + 7 天公示。

target_paths 5 个文件全部 ≤ L2，但词表本身约束所有项目，按 §1.1"取涉及级别中的最高级"裁定 L4。

决策​

1. 词表（3 值）​

文档 frontmatter status: 字段取值仅可取以下 3 个值：

值语义
activecanonical 且在用（已签字 / 已稳定 / 正在被引用且代表当前事实源）
draft工作中，未成为 canonical
archived不再活跃（已被取代 / 退役至 legacy/ / 物理迁至 _archive/ / workstream 收尾过程产物）

2. "被取代"语义改用指针表达​

取消独立 superseded 值。被取代时 status 改为 archived，文末加：

Replaced-by: <canonical-path-or-ADR>

与 变更协议 §5 既有 Replaced-by 约定一致；§5 提到的 deprecated 一并由本 ADR 改为 archived（见 §决策 5）。

3. 不适用范围（专属 status 状态机保留）​

文档类型专属 status 词表不变理由
顶层治理 ADR（仅 governance/decisions/ADR-NNNN--*.md，四位序号双横线命名）proposed / accepted / rejected / superseded / deprecated表达"流程状态机位置"而非"文档生命周期"，两套语义不能合并
提案（governance/proposals/inbox/*.md）open / accepted / rejected / superseded同上

顶层治理 ADR 与提案的 status 表达流程状态机；文档生命周期通过物理位置（_archive/ vs 原位 + Replaced-by 指针）表达。豁免仅限上表两类：governance/workstreams/*/decisions/ 下的 workstream 级 ADR / MP 不豁免，其 status: 表达文档生命周期，用 3 值词表（已签字 = active，被 supersede = archived + Replaced-by 指针）——与 W6 已执行的迁移一致。

4. 词表事实源​

立词表 canonical 事实源：commons/templates/frontmatter-status-vocabulary.md，含 19 → 3 值完整迁移映射 + 适用 / 不适用范围。

5. 同步修改的协议条款​

governance/change-protocol.md §5 当前文本：

文档要弃用时改 frontmatter status: deprecated，并在文末加 "Replaced-by: <path>"

更新为：

文档要弃用时改 frontmatter status: archived（取值参见 frontmatter status 词表），并在文末加 "Replaced-by: <path>"

6. 既有违例与历史迁移​

2026-06-11 W3 + W6 已在 FinBayes 范围内完成 ~140 份违例迁移（见仓库 projects/finbayes/.cleanup-status.md W3 / W6 行）。本 ADR 公示通过后，剩余其他项目（如果存在）由各 Controller 在下次该项目 cleanup 时同步对齐；不强制本 ADR 通过后立即批量扫整个仓库。

7. 强制执行（机器校验）​

下一步在 scripts/verify-kb.mjs content-hygiene 子检查里加规则：frontmatter status: 取值不在 {active, draft, archived} 中（且非 ADR / 提案专属白名单）报错。规则落地不在本 ADR 同步进行，留作下一步 PR；本 ADR 完成立法 + 词表事实源 + 协议对齐即收口。

结果​

  • 词表事实源建立，新文档约束有处可查
  • change-protocol.md §5 与新词表对齐，无悬空 deprecated 残留
  • 19 → 3 值迁移有审计追溯（W3/W6 commit + 本 ADR 记录）
  • 后续 verify:kb 规则强制执行有立法依据

备选方案​

A. 5 值词表（draft / active / stable / superseded / deprecated）。否决理由：owner 整改期间显式 "状态太多了，再精简一下"；5 值与 3 值的差别只在 stable / superseded / deprecated 三处，而这些都可用 active（含义已稳定）或 archived + Replaced-by 指针准确表达，5 值是过度区分。

B. 不立法，让各项目自定。否决理由：232 文档 19 值乱象正是无统一词表的直接结果；不立法等于把 2026-06-11 整改成果留作 FinBayes 项目内部约定，跨项目仍会复现混乱。

C. 保留独立 superseded 值。否决理由：与 archived 在归档处置上完全一样，唯一区别是"被替代 vs 被弃用"，但这层语义可由文末 Replaced-by: 指针有/无表达，省一个值。变更协议 §5 既有 Replaced-by 约定也支持这种方式。

关联​

L4 公示窗口​

  • start: 2026-06-12
  • end: 2026-06-19
  • 公示完成后由生态发起人将本 ADR status: 由 proposed 改为 accepted。