專案生命週期

本檔角色：判定 Open4WD 目前所處階段，以及變更是否需要公開相容、遷移、重算或緊急復原。 本檔同時定義首次公開的候選門檻與跨 repo 發布順序；逐項執行證據仍由 open-4wd-workflow issue registry 保存。

目前狀態：runtime_phase = pre_launch；階段只由本檔定義的可稽核事件轉換。

1. 四條互不替代的狀態軸

狀態軸	值	決定什麼
repo 可見性	local／private／public	每個 repo 的 Git 歷史由誰可讀
candidate 成熟度	iterating／asset_ready／release_candidate	首次公開候選是否已有一致證據
runtime 階段	pre_launch／live	是否已開始公開相容與遷移義務
live 作業模式	normal／emergency	上線後採一般版更或緊急復原

repo 公開不會一律觸發 live：specs、文檔站與三個 service template 會先公開。只有主 repo open-4wd 成功轉為 public，才是 pre_launch → live 的不可逆觸發事件。public_contract_freeze 不另設第二個布林權威；是否承擔公開相容義務直接由 runtime_phase == live 推導。

2. 權威與證據

• 本檔 frontmatter 的 runtime_phase 是日常判讀入口；phase_decision 指向核准轉換的 ADR， phase_evidence 指向可稽核的外部事件或本機保存紀錄。
• GitHub 的實際 visibility 與 production origin 的實際可達性是外部事實。若 main 已 public、 本檔仍因記錄延遲顯示 pre_launch，一律採較保守的 live 規則並立即補記，不可藉漂移恢復 開發期自由窗。
• 日期與重大事件只供閱讀，不可依預定日期自動切階段。
• Candidate、測試與人工驗收的細節屬執行狀態，保存在 open-4wd-workflow；本檔只保存規則、 粗粒度里程碑與現行 runtime 階段。
• 純生命週期狀態或歷史紀錄更新不改變產品契約，不要求 main 重鎖 specs SHA。Main dependency lock 仍代表該 build 實際驗證過的 immutable specs 契約快照。
• Main dependency lock 是一組聯合快照：specs commit、authoring Release tag 與其三個 digest， 加上 main 自有的 authoring manifest join。任何一項變動都要整組重新推導，只換 commit 會讓 採用檢查以 fingerprint、digest、tag 或 exact-set 漂移中止。
• 消費端 CI 會 checkout 鎖定的 specs 並直接執行其中的檢查腳本、讀取其中的常數與資產 manifest， 因此 specs 的變更類型決定消費端是否必須同批更新：

specs 變更類型	消費端必要動作	不更新的後果
文檔敘述、歷史紀錄、runtime 階段狀態	無	無；鎖定快照續用
Authoring Release 資源或其 source manifest	main 同批更新 dependency lock 四欄位與自有 authoring manifest join	採用檢查中止；Release 若已被取代或移除，鎖定 tag 的下載直接失敗
specs 檢查腳本或其 runtime 需求	執行該腳本的 repo 在改鎖時同步 workflow 的 runtime 與相依安裝步驟	腳本要求的 runtime 缺席，消費端 CI 失敗
規則登錄、常數表、材質表等被消費的權威資料	依採用時機改鎖，並修正因規則更動而失效的標註或常數	不失敗，但消費端持續對舊快照驗證，形成靜默過時

• 靜默過時由排程、非阻斷的 specs-lock-drift workflow 補訊號：main、pinning、signaling 各自比對釘定 commit 與 specs master，只對該 repo 實際消費的內容差異發 warning 與 job summary（資料型路徑整檔比對； main 對 toolchain.md、程式架構.md、testing.md 這類文件型消費者只比對實際讀取的表與章節，散文修訂不提醒）； 提醒不取代上表判斷，改鎖仍依上表整組重推導。

3. Pre-launch 的開發自由與公開責任

pre_launch 期間沒有既有正式 client、正式 Ledger 活動或玩家持久資料需要相容；必要時可直接 重構 schema、protocol、物理、builtin 與本機資料格式，不為未公開中間版本建立 migration、 dual-read 或相容 shim。

所有 Open4WD 自有的 schema、wire、snapshot、receipt、persistence、tooling manifest 與 asset current baseline 在本階段一律維持 1；內部候選改用 candidate_epoch、prepub-rcN、digest、 CID、golden 或明確 revision。CI 依機器可讀 authority 清單逐項驗證 source、生成物與 vendored copy；第三方標準版本及未知版本拒絕 fixture 不屬於 current baseline。

但 repo 一旦 public，立即開始承擔以下責任：

• Git 歷史、文件、issue、圖片 metadata、授權與 provenance 必須可安全公開。
• 公開 README 與 docs.open4wd.org 首頁必須明示「開發中／主遊戲尚未正式公開」；內頁不重複 投影這項狀態。
• 公開內容可供閱讀、介紹、教學與 fork，但 runtime／schema／API 的正式相容承諾到 main 進入 live 才開始。
• 公開頁面路徑盡量穩定；搬移已供外部引用的文檔時提供 redirect。內容本身仍可依現行 canon 修訂，不把早期錯誤永久化。
• Private Git 歷史日後轉 public 時會整批公開，因此不得把 secret、個資或部署憑證先寫進 private commit 再期待公開前清除。

4. 首次公開候選是迭代，不是單線工序

美術方向檢查、Editor 正式匯出 GLB、資產／物理／效能驗證、E2E／playtest 與視覺／物理／ 平衡調整可以反覆交錯。每次 materially different 的輸入形成新的內部 candidate；它使用 prepub-rcN 或 candidate_epoch 識別，不得挪用 builtin_assets_version 製造未公開的 v2、v3。

美術檢查分為兩層：

1. 方向檢查：概念、比例、辨識性與風格，可在 GLB 尚未完成時提早進行。
2. 最終驗收：針對正式 Editor 匯出的 exact GLB、遊戲內畫面與必要視角，具有 release-gate 效力。

4.1 Asset-ready gate

同一 candidate 必須同時滿足：

• 公版清單完整，沒有假 GLB、缺檔或以 placeholder 冒充正式資產。
• 全部資產經正式 Editor 路徑產生。
• manifest、SHA-256、CID、extras、PhysicsManifest 與 provenance 一致。
• 嚴格資產檢查、production build、載入與資源預算驗證通過。
• 遊戲內最終美術驗收通過。
• 資產相關物理、決定性、效能、主要 E2E 與 playtest 通過。
• 沒有仍要求重製資產的公開阻擋項。

4.2 Pre-launch baseline gate

Asset-ready 後進入穩定期。只有下列證據都指向同一 release subject，才可接受 release_candidate：

main source commit
+ specs candidate
+ builtin manifest digest
+ GLB bytes／CID 集合
+ 自動測試證據
+ 人工美術／playtest 驗收

通過後只處理阻擋首次公開的問題。任何修改依影響範圍使舊證據失效，不以「曾經通過」沿用到 不同 candidate。

修改內容	必須失效並重驗
純文檔且不改產品契約	文檔檢查與公開內容複核
材質或純視覺 bytes	美術驗收、資產完整性、畫面 E2E、載入效能與 provenance
mesh、壓縮或 GLB bytes	hash／CID／manifest、嚴格資產 gate、載入與效能
collider、掛點、材質能力或 physics extras	物理、決定性、相關 E2E 與 playtest
物理公式或平衡常數	決定性、物理測試、相關完整 playtest
specs 公開契約	specs lock 與受影響的跨 repo conformance gate

5. 首次公開的跨 repo 順序

在正式發布序列之外，可對不含權利來源未證實暫行 GLB 的 open-4wd 建立 private source backup。 它只保存程式來源，不是發布、baseline 或依賴驗證步驟，也不指定與下列正式序列的先後依賴； 不得據此宣稱 Asset-ready、release candidate 或 main_source_baseline_sha。每個 repo 的完整歷史 公開安全檢查屬於該 repo 轉 public 前的必要 gate，不是獨立的全域發布步驟。

1. open-4wd-specs 通過完整歷史公開安全檢查後轉 public，啟用 branch protection 與 immutable releases，取得 immutable specs SHA；pre-launch 期間不公開一般 Q&A，specs Discussions 維持 關閉，但啟用 GitHub private vulnerability reporting，逐一確認 Issue Forms 保留的安全 contact link 可由未登入讀者到達； 大型 authoring payload 先由本機 prepare 工具封裝與人工審查， 再確認對應 Draft 已完整下載回讀並發布為 immutable Release。
2. 同批設定 docs.open4wd.org、HTTPS 與 GitHub Pages；完整建置、連結、圖片、Mermaid、搜尋與 smoke 通過後正式提供閱讀、介紹與教學。文檔站可被搜尋引擎索引，首頁固定明示 pre-launch 狀態；它不連接正式 Ledger、不接受遊戲資料寫入，也不觸發 live。
3. 依序公開 open-4wd-pinning → open-4wd-signaling → open-4wd-turn。每個 repo 先通過 self-contained build／test、完整歷史公開安全檢查與已版控 vendored content-hash provenance； main 尚 private 時不使用暫時 PAT 或 GitHub App 啟用 remote raw gate，也不等待尚未形成的 main_source_baseline_sha。
4. open-4wd 保持 private，鎖定公開 specs SHA；dependency lock 同時綁 authoring Release tag、 manifest digest，從 Release 下載原始 GLB 並通過 Editor adoption journey。正式 builtin GLB、 rights provenance、strict 資產 gate、載入／物理／效能／E2E 與人工驗收全部完成後，通過 Asset-ready 並形成 main_source_baseline_sha。
5. 執行 one-shot Ledger genesis，保存 receipt，填入 exact address 與 governance signers；保持 genesis provider 可達，並以不同 identity、空資料目錄完成 replica 驗證。
6. 形成包含正式部署值的 main_release_sha，完成 production release gate 與完整歷史安全檢查。 若 source baseline 形成後的阻擋修復改到任何 vendored path，必須重跑 service repo 同步、 package contract、0-drift 與 provenance；不得沿用首次公開時的舊 content-hash 證據。
7. open-4wd 成功轉 public；此事件不可逆地觸發 runtime_phase = live。Main 轉為 public 後立即 啟用 branch protection 與 Main Discussions 的 Q&A 分類，把 specs、pinning、signaling、TURN 的一般問題 contact link 一次同步指向 Main Discussions，並補記 phase_decision、 phase_evidence、時間與 main_release_sha。
8. 啟用 pinning／signaling 對 final main SHA 的公開 remote provenance gate；任何 vendored path 漂移都重開同步。全量 CI 綠燈後部署 open4wd.org、Enforce HTTPS，完成首次公開 smoke。
9. Main 上線穩定後再公開 open-4wd-workflow。它仍是維護者治理工具，不成為第六個外部 issue intake；issues/private/ 是 Git-ignored 本機資料，公開前必須另行驗證備份。

上列步驟建立的部分狀態存在於帳號或 repository 設定，而不在版控內：GHCR package 對 repository 的 寫入授權、repository variables（GRAPHIFY_RELEASE_ENABLED、DEPLOY_ENABLED 與各部署值）、branch protection、immutable releases 與 Pages 設定皆是。repo 一旦刪除重建，這些都不會跟著回來：以 variable 為閘的 job 會靜默略過，其餘會在使用時才失敗。跨 repo 引用同樣受影響——main 的 dependency lock 綁定 specs 的 authoring Release tag，該 Release 隨 repo 重建消失即無法通過採用檢查。重建任一 repo 後，必須逐項確認上述狀態已復原，再重跑對應的 gate。

main_source_baseline_sha 是周邊 vendoring 使用的程式來源基線；main_release_sha 是加入正式 Ledger address、signers 與最終 release metadata 後實際公開的 commit。兩者不得再以「private main 定稿」一詞混稱。Main 公開後的 remote provenance gate 負責驗證 final SHA 中的 vendored 來源仍與 source baseline 相同。

Main 在 private 階段可保留 Discussions，供已獲存取權的協作者預先整理分類；這不是公開 Q&A 入口。Main 尚未 public 時，已公開的 specs、pinning、signaling、TURN 不得把 Issue Forms 或說明 文字連到 Main Discussions，也不另開各 repo 的一般問答區。安全通報不受此限制：各公開 repo 保持 private vulnerability reporting，公開 contact link 統一指向 specs 的安全通報 canon。

6. Docs site 的公開定位

open-4wd-specs public 與 docs.open4wd.org 上線是同一發布批次。Docs site 是正式、可分享、 可索引的說明與教學面，不是遊戲 production runtime。首頁以一般內文明示 Open4WD 仍在開發中、 主遊戲尚未正式公開，並連回本檔說明首次 live 前仍可能發生的不相容重構；內頁不重複顯示 狀態 banner、最後更新時間或 specs commit。

runtime_phase 的 current 值、轉換依據與詳細相容規則只由本檔承接；更新稽核與 exact commit 由 Git 歷史保存，不投影成每頁 banner 或站內 commit 標籤。

Specs public 後，通過 docs CI 的受保護主分支可自動部署，方便維護者與外部讀者持續閱讀。公開 Graphify /graph/ 產物仍須獨立通過路徑、內部查詢內容與公開安全檢查，不是初次 docs 上線的必要 條件。

docs.open4wd.org 先於主站公開，不違反「第一個公開 production origin 直接使用 https://open4wd.org/」：該句的主詞是遊戲 client runtime；獨立 origin 的 docs 不承載 PWA、 Ledger、玩家身分或 origin-bound 遊戲資料。此適用範圍由 D-20260811-17 明定，文件發布不構成主站遷移或 live 啟動。

7. Live 後的正常變更

進入 live 後仍可重構內部實作；是否需要相容取決於公開面，而不是「有沒有重構」：

• 純內部實作且不改 persistent／wire／共識／公開 API：正常 PR、測試與版更。
• 公開但相容的新增：依 minor 或相應公開版本規則出貨。
• persistent、wire、共識、資產或公開 API 的不相容變更：另立 ADR，提供版本區隔、遷移、重算、 dual-read 或明確拒絕舊資料策略，不得沿用 pre-launch 的直接破壞方式。
• 普通 production rollback 回復舊 commit 內容，但版本號仍向前，不把專案退回 pre_launch。

8. Live 緊急模式與經濟復原

emergency 是 live 內的作業模式，不是第三個生命週期，也不授權跳過安全或共識守門：

1. 參數失衡：以新的治理 ConfigUpdate 把值設回良好設定，保留事件史。
2. derive／結算規則缺陷：修法、升不相容版本，從已核准 checkpoint／event anchor 全網重算。
3. 事件史本身壞損到不可解讀：最後手段才鏈重生；從最後良好帳本檢查點建立新 address，以 client major 出貨並封存舊鏈。

上述任何復原都保持 runtime_phase = live。日期只幫助人定位事件；經濟、帳本與共識回溯一律 使用 checkpoint CID、event position、release SHA 或治理決議作可驗證錨。

9. 里程碑紀錄規則

本檔只記已發生的重大事件，不以預定日期冒充完成：

事件	必要證據
specs／docs public	repo visibility、branch protection、Pages deploy 與 smoke、specs SHA
service template public	各 repo release SHA、自包含 CI 與公開安全檢查
Ledger trust root	genesis receipt、exact address、signers、不同 identity replica 證據
main public／進入 live	main release SHA、visibility event、phase ADR 與 production gate
production activation	open4wd.org Pages artifact、DNS／TLS／PWA／deep-link／version smoke
workflow public	visibility、安全檢查與 private buffer 備份證據

實際執行前仍須核實遠端 visibility；本機存在 origin 或 origin/master tracking 不能單獨證明 GitHub repo 目前是 private 或 public。