文檔工程¶
本檔角色：把本 repo 的隱性文檔紀律寫成顯性方法論＋貢獻者指南——這是本專案的文檔北極星：一份可複用的開源文檔工程範例。三件套：結構化決策記錄（ADR）、本機可建置且機器可驗的靜態站（MkDocs）、知識圖導航（graphify）。 每條紀律都指向執行它的機器看守或權威檔；讀者能複製的是「紀律＋看守」，而非只有口號。
靜態站現況：本機靜態站建置與驗證能力已存在，public site 尚未部署。Canonical origin 為
docs.open4wd.org（D-20260727-02）；它會在open-4wd-specs轉 public 的同一批次啟用並通過 smoke，不等待主open-4wd公開。公開後允許搜尋引擎索引，供隨時閱讀、專案介紹與教學；首頁明示開發狀態並連到生命週期權威，內頁不重複 banner、更新時間或 commit。實際上線前仍不得宣稱站點可用；時序以 專案生命週期 為準。
1. 單一權威原則¶
每一類事實只有一個權威來源；其他檔要用就連結、不重述。改一個共用值＝先 grep 全 corpus 找出所有 copy、逐處更新（否則就是 cross-doc drift）。
| 事實類別 | 單一權威 |
|---|---|
| 公式（物理／武器／經濟／信譽） | 算式表.md |
| 共用常數／可治理 config | 程式參數/各分冊（根頁只導覽；程式側＝@open4wd/system-constants） |
| 材質欄位 | 材質表.md |
| 抽象介面／模組依賴 | 程式架構.md 及 程式架構/ 實作檔 |
| 規範性規則 | 業務域 canon（掛 〔ID〕，見 §5.1） |
| 跨模組流程 | 流程.md 及 流程/ 各檔 |
自有版本契約（schema、wire format、snapshot、asset 或 persistence）在現行 canon 一律寫 current，不複製數字版號；current 精確版本值只由 版本規範.md 與 程式參數/對應分冊承接，程式參數根頁只提供導覽。第三方標準／套件、ADR 與歷史快照可保留其實際版本，以便辨識外部契約或當時狀態。
機器看守：§ 引用與連結錨點完整性由 pnpm check:refs 看守；規則的 canon anchor、
rule-contracts.json 與生成式 rules.json 由 pnpm check:rules 看守；逐層測試追溯由 Specs
check-trace.mjs 依 owner scope 驗證。材質 spec↔程式常數由主 repo pnpm check:materials 逐欄比對。
2. 現況與歷史分離¶
canon 各檔只寫現況（「現在是什麼」）；變更流水帳進 歷史記錄.md，決策檔（§4）補「為什麼」，並以 deprecates 記錄具名契約的移除、改名與取代關係，由 決策索引 生成完整表。三者互不重複。
首頁專案沿革是每日歷史的生成式摘要，不是第四份權威。入選條目才加
<!-- homepage-milestone importance=N -->，未入選條目與 ADR 不補空欄位。標記時機依事件本身：
- 決策本身就是重大事件時，與已接受 ADR 同批標記。
- ADR 只設計未來實作或發布時，等實作、部署或發布真的發生後才標記。
-
沒有 ADR 的實際事件仍可獨立標記，但必須符合專案身份、階段、核心架構或公開營運邊界的門檻。
-
好處：讀 canon 的人永遠看到當前真相，不必在「這還算數嗎」裡考古。
- 反面鐵則：canon 內不留 deprecated 註記、不留裁決日期戳、不寫「先做 X 之後再 Y」。
3. 圖表規範¶
全 corpus 圖表一律 mermaid（GitHub 原生渲染）。完整樣板與色彩／形狀語意的單一權威在 流程.md §3，此處不重複、只述核心紀律：
- 圖是骨架、文字是權威：公式、門檻、參數、§ 引用不進節點標籤；規範細節放圖下方清單或既有章節，嚴禁圖文兩份規範文字。
- 五類 classDef 固定語意：本地（綠）／共識（黃）／鏈（藍）／失敗（紅）／UI（紫）。
- GitHub 相容紅線：禁
fa:圖示、不用 ELK、顏色以 classDef 明示。
4. 決策記錄（ADR）與兩層制¶
架構決策以 MADR 中文化的決策檔記錄於 decisions/INDEX.md。核心制度（完整鐵則見 decisions/README.md）：
- 不可變：
accepted的決策檔內容不再改；改變決策＝建新檔supersedes舊檔（舊檔轉superseded）。部分修訂用amends、目標維持accepted。 - 三面分工：canon 寫現況、決策檔寫為什麼與結構化
deprecates、歷史記錄.md 維持流水帳；三者互不重複。流水帳條目升格決策檔時，原條目僅補 ID 引用。 - 機器看守：
pnpm check:decisions（frontmatter 可解析、id 唯一、status 鏈雙向一致、amends目標存在、domains 合法）；INDEX 由同腳本生成。
5. 機器執法清單¶
方法論靠機器看守才不腐壞。specs repo 的 pnpm check 是本機與 CI docs-ci 的共同權威；子命令與順序由 package.json 的 scripts.check 定義：
| 檢查 | 看守什麼 |
|---|---|
test:docs |
文檔工具鏈行為與 CI／package 聚合 parity |
check:prelaunch-versions |
Pre-launch 自有 schema／wire／snapshot／asset／persistence authority 維持 1，並掃全部 active canon 禁止自有 v2+；歷史、ADR、fixture、生成物與明列第三方標準排除 |
check:conformance |
Conformance fixture envelope、權威路徑、provenance 與家族索引 parity |
lint:md |
Markdown 結構（markdownlint-cli2） |
lint:terms |
用語鐵則（textlint o4-terms，見 §6） |
lint:zh:strict |
中英排版（zhlint；標題／frontmatter 凍結豁免） |
check:refs |
§ 引用／連結／錨點完整性 |
check:history |
每日流水帳與月份／全域歷史索引凍結 |
check:decisions |
決策檔 frontmatter／status 鏈／索引 |
check:frontmatter |
corpus frontmatter（type／domain／summary／authority） |
check:workflows |
Docs CI 外部 GitHub Actions 必須鎖完整 commit SHA |
check:docs |
生成式索引凍結（總覽區塊／docs-map／graph.json） |
check:rules |
九域規則 ID、canon anchor 與 rule-contracts.json exact set，並生成 registry |
check:mermaid |
Mermaid 圖語法解析＋節點內數字單位／量詞／運算式／§ 政策值禁入（僅白名單插值示意例外） |
跨 repo 看守依實際可執行入口分工：
| 命令 | 執行處／證據 |
|---|---|
Specs check:trace:workspace |
以命令列顯式 targets 聚合 owner-scoped 規則→測試追溯；不自動發現 sibling repo |
main check:trace |
驗 open-4wd 所有 required layers 與 literal conformance calls |
| pinning conformance spec | open-4wd-pinning 提供其 service-layer ruleConformance 證據，由 workspace aggregate 掃描 |
main check:materials／check:constants |
材質與共用常數的 specs 交叉比對 |
specs check:authoring-source |
維護者本機／發布前驗 release-input/ GLB bytes、desired-state manifest 與 candidate epoch exact-set；因投遞目錄不受版控，不納入一般 docs CI 聚合 |
rules.json[].implementationRepos 雖保留陣列格式，但目前必須恰有一項，表示規則的唯一實作責任
repo。ownership 直接來自 rule-contracts.json；rule-ownership.json 只留歷史標記，不被生成器或檢查器讀取。
真正需要多 repo 共同執法時必須另立逐 repo 的後續契約，不得讓任一 repo 的證據替其他 repo 補 coverage。
Specs 公開後的 CI 只允許各 implementation repo checkout immutable Specs，不得為追溯 checkout 其他
implementation repo（D-20260729-01、
D-20260813-02）。
5.1 規則 ID 與執法契約¶
九個 ID 前綴是 LEDGER、ECON、MOD、PHYS、TRACK、PART、UGC、VERSION、
SEC。每個規則的 canon anchor 與 rule-contracts.json contract 必須形成 exact set：缺 contract、
ghost contract 或重複主錨都失敗。contract 必須完整宣告：
kind：reject、derive、behavior、invariant或calibration。requiredLayers：從authoring、finalizer、admission、fold、room、runtime、service、schema-static選非空、不重複集合。implementationRepos：目前恰一個 owner repo。testContracts：與requiredLayerskeys exact match，每層使用全域唯一 contract ID。
新規則的順序是：在業務域 canon 以 **〔PREFIX-R-nnn〕** 掛 append-only 主錨 → 於
rule-contracts.json 建完整 contract → 執行 pnpm rules:generate → 在 owner repo
*.conformance.spec.ts 匯入 rule-conformance helper，用 literal ruleConformance({ ruleId, layer,
contract, run }) 為每個 required layer 提供證據 → 主 repo owner 跑 check:trace，pinning 證據
由 Specs check:trace:workspace 掃描。一般註解、檔名或非 conformance 測試都不能滿足 required layer。
6. 用語鐵則¶
顯示用詞與技術識別符分離、易混淆處固定一種寫法。部分由 textlint o4-terms 機器看守（違反＝CI 紅），部分為約定（列於命名約定、尚未機器化）：
| 正寫 | 說明 | 看守 |
|---|---|---|
| 黑名單（全域）／封鎖清單（個人） | 全域帳本推導 vs 個人本地清單，不可互換 | o4-terms（CI 紅） |
| （禁用）MVP／v1.x 分階段措辭 | 開源專案無版本階段概念 | o4-terms（CI 紅） |
晶片（顯示）／chip（識別符） |
顯示文字一律「晶片」 | 約定（總覽.md 命名約定） |
| 衍生／衍生流程 | 散文用「衍生」，識別符可留 fork |
約定（流程.md §4） |
| Match／Round／Race 三層 | 比賽／回合／單場，勿混稱 | 約定 |
7. 貢獻者指南¶
| 情境 | 該做什麼 |
|---|---|
| 改一個共用值（公式／常數／enum） | 先 grep 全 corpus 找所有 copy → 逐處更新 → 跑 check:refs／相關比對 |
| 做出架構決策 | canon 更新現況＋建決策檔寫為什麼（§4）＋歷史記錄補流水帳 |
| 新增規範性規則 | 依 §5.1：主錨 → rule-contracts.json 完整 contract → rules:generate → owner *.conformance.spec.ts 逐層 ruleConformance → 對應 trace gate |
| 新增跨模組流程 | 依 流程.md §5 程序（流程/ 新檔＋索引＋玩家旅程引用＋cross-ref） |
| 提交前 | specs 跑 pnpm check；主 repo 跑其驗證鏈（含 check:trace） |
8. 跨 repo 知識圖發布¶
Graphify 是衍生的檢索／導覽層，不是 canon 權威。四個產品 repo 各自發布綁 exact source SHA 的 immutable Graphify Release；specs 只從固定 allowlist 獨立驗證各 repo 最新有效 Release，不要求 跨 repo 版本對齊。缺少、私有、抓取失敗或無效成品必須在知識圖頁明示，不能靜默省略或阻斷 canon docs。Release contract、GitHub App 最小權限、公開內容 gate 與復原程序見 Graphify Release 聚合。