跳轉到

D-20260724-03｜ADR 制度與 conformance 權威模型

背景與驅動力

spec corpus 長期把「現況規格」與「當初為什麼這樣定」寫在同一批檔案裡：權威檔為了說明 取捨會夾帶歷史語氣，流水帳又只留結果、不留被否決的選項。廢棄資訊鐵則（權威檔只寫現況、 見 D-20260604-01）解決了前者，卻讓決策理由在每次 改寫時一併消失——查「為什麼是現在這樣」只剩全檔掃描一途。

同時，共識面的位元組級約定（簽章摘要、matchId 推導、面板抽選）只以敘述存在。跨 repo 的 多個實作各自解讀同一段文字，沒有共同的機器可驗採樣可以證明彼此一致。

考慮過的選項

  • 在各 canon 檔內保留「決策沿革」段落：與廢棄資訊鐵則直接衝突，且會隨改寫再度流失，棄。
  • 只靠流水帳承載理由：按時間排序、無穩定 ID、無取代鏈，回答不了「這條現況由哪次裁決 定下、後來被誰改過」，棄。
  • 另立 decisions 決策層與 conformance 契約層，與 canon、流水帳三分工（採納）。

決定

  • 三層分工鐵則：canon 各檔寫「現況是什麼」、決策檔寫「當初為什麼」、歷史記錄維持全量 流水帳，三者互不重複；流水帳條目升格為決策檔時，原條目僅補 ID 引用、內容不動。
  • 決策檔採 MADR 中文化：id 與檔名同為 D-YYYYMMDD-nn，accepted 後內容不可變（僅允許 回填反向關聯與錯字修正），改變決策等於建新檔取代；完整取代用 supersedes、部分修訂用 amends。制度細節見 README.md。
  • 首批 106 筆源自 2026-04-29 至 2026-07-24 歷史條目的全量升格裁決。入選標準是架構級或 規則級定案、鐵則建立與翻案；純實作里程碑與 drift 修正批留在流水帳。
  • conformance 權威模型三條：語意權威永遠在 spec 敘述；向量是該敘述的機器可驗採樣；生成器 是工具而非權威，其產值由採納閘賦權。向量不得反過來定義行為。
  • 首波 v1 五家族涵蓋帳本側的簽章摘要、matchId 推導、loadout 簽章訊息與寫入門檻，以及 moderation 的面板抽選；主 repo 以預設回放消費同一批向量。
  • specs 檢查鏈以 CI 硬閘承載，主桶違規非 0 即紅燈。

後果與影響

決策理由自此有穩定 ID 與取代鏈可查，canon 得以只寫現況而不流失脈絡；跨 repo 實作有了 可執行的共同採樣，「照 spec 寫的」變成可驗證的宣稱。

代價有二。其一，決策層與 canon 的邊界必須人為維持：決策檔一旦重述規格細節就會產生第二 權威，與單一權威原則衝突。其二，向量只是採樣：未被家族涵蓋的行為仍以 spec 敘述為唯一 權威，不得由「沒有向量」推論無約束。家族的擴充由後續實作驅動，不預先鋪滿。