tarrragon /version-bootstrap — 版本規劃波 Orchestrator
把版本提案展開成可執行的 ticket，中間不漏教學比對。
定位
| 工具 | 問的問題 | 關係 |
|---|---|---|
| /version-bootstrap | 「這個版本要做什麼？怎麼拆成可執行單位？」 | 規劃波 orchestrator |
| /doc | 「文件建好了沒？格式對嗎？」 | 文件系統工具（被呼叫） |
| /spec validate | 「規格夠清楚嗎？和教學一致嗎？」 | 品質閘門（被呼叫） |
| /tdd | 「測試怎麼設計？」 | TDD 流程（Phase 2 被呼叫） |
| /ticket | 「工作怎麼追蹤？」 | 票務系統（被呼叫） |
使用方式
/version-bootstrap --version <version>
PM 執行後，依 6 步流程逐步推進。每步有 checkpoint（PM 確認後才進下一步），不是全自動 pipeline。
6 步流程
Step 1：列出提案清單（全自動）
動作：讀取 docs/todolist.yaml 中指定版本的 proposals 欄位，列出提案清單和摘要。
doc list proposals # 確認提案狀態
輸出：提案 ID + 標題 + 狀態表格。
跨提案依賴檢查（強制）：接著執行依賴檢查腳本，偵測「本版提案依賴的提案排在更晚版本」的排序矛盾。
uv run .claude/skills/version-bootstrap/scripts/check_proposal_dependencies.py --version <version>
腳本讀 docs/proposals-tracking.yaml 各提案的 depends_on 欄位（選填，list of str，元素為本提案依賴的前置提案 id）比對 target_version 排序；若專案已採用 doc skill，該欄位格式定義的權威來源見 doc skill 的 tracking_schema.py（PROPOSALS_TRACKING_SCHEMA["proposal_entry_optional"]），非本 yaml 檔案本身的頭部註解。若未採用 doc skill，本腳本仍可正常運作（腳本本身不 import 該檔，以執行期讀取的 list 格式驗證取代靜態 import），只是欄位格式需自行依上方括號說明推斷，無法查閱該權威定義檔案。輸出 [WARNING] 時，PM 必須在本 Checkpoint 前二擇一處理：(1) 把依賴提案移入本版或更早版本一起排入，(2) 把本提案移至依賴提案完成之後的版本。動機案例：曾有版本以雙提案啟動，其中一提案依賴另一個排在更晚版本的提案，卻仍排入本版，矛盾拖到規劃波中段才由用戶手動發現，最終將該提案移至依賴對象所在的版本節點。若此檢查在 Step 1 就位，矛盾可在提案確認階段被攔截。
Checkpoint：PM 確認版本範圍——哪些提案納入本版、哪些延後；依賴檢查腳本無 [WARNING] 輸出，或警告已處理（移版/補前置）。
Step 2：建 Spec 骨架（半自動）
動作：用 /doc batch-init 批量建立 spec 骨架。
doc batch-init --proposals PROP-XXX,PROP-YYY --domain <domain>
輸出：每個提案對應 1 份 spec 骨架檔案。
PM 工作：填寫每份 spec 的 FR 列表、介面定義、約束條件。這是規劃波最耗時的人工步驟。
UI 類提案元件庫前置檢查（強制，元件庫雙向約束方法論落地）：Why——UI 類提案若跳過 design token 層與元件庫規劃直接進入實作，設計端與工程端會各自決定元件形狀，產生重複造輪與樣式漂移，已上線元件難以回溯套用 token 體系。Consequence——未在本步驟攔截，UI 實作票會在 Step 6 匯總建票時直接開出，等到 Phase 3b 實作階段才發現缺 token 層或元件庫章節，需回頭補規劃甚至推翻已完成的實作。Action——填寫 spec FR 時逐一判別提案是否涉及 UI/頁面/元件（FR 描述含「畫面」「頁面」「元件」「介面」「UI」等關鍵字），判為 UI 類提案者須先確認下列兩項存在，缺則先補齊才可繼續本提案的 UI 實作票規劃：
| 檢查項 | 對應載體 | 缺失時動作 |
|---|---|---|
| design token 層 | 專案 design-system 樣式檔（顏色/間距/字體/圓角/陰影參數集中管理） | 先建立 design token 層 |
| L3 元件庫章節 | spec 文件的元件庫章節（元件清單 + 原生元件禁用對照表 + 豁免清單；本步驟得先只到此，逐元件元件契約欄位表與容器條目於 Step 4.5 第 3 塊後補齊） | 先建立或補齊 L3 元件庫章節（用 doc skill component-library-spec-template） |
| design-system spec 文件 | 用 doc skill design-system-spec-template 產出的 design system 專屬 spec（如 docs/spec/design-system-spec.md），非混入一般功能 spec |
用 design-system-spec-template 補產 |
判準與分層依據（L1/L2/L3 分層、狀態綁定判準、流程整合點）見 .claude/methodologies/component-library-bidirectional-constraint-methodology.md。非 UI 類提案略過本檢查。
Why 加 design-system spec 檢查：doc skill 已提供
design-system-spec-template，但batch-init只產一般功能 spec，UI 版本易漏產 design system 專屬 spec。Consequence：漏產則 Step 4.5 地基波的 design-system 實作無契約可依（實證：PM 用 batch-init 產一般功能 spec 卻未產 design-system spec，經指正後才補）。Action：UI 版本填 spec 時一併用 design-system-spec-template 產出 design system spec，作為 Step 4.5 design-system 實作的契約。
Checkpoint：所有 spec FR 填寫完成；UI 類提案已完成元件庫前置檢查（design token 層、L3 元件庫章節、design-system spec 三者存在或已補齊），非 UI 類提案略過本項。
Step 2.5：Domain 規劃（半自動）
Why：spec 定義 FR（系統做什麼）、UC 定義使用者場景（誰怎麼用），兩者皆為垂直視角，不界定 domain 的水平聚合邊界——aggregate / kernel / read-model 分類、依賴方向、層測試策略。Consequence：跳過本步驟，domain 邊界會在實作階段臨場拍板（退化為「哪個檔案太大就拆」），依賴方向底線無文件可依，易出現 read-model 互相耦合、持久化細節混入 domain；測試設計（Step 5）也無 per-bundle 依據。需事後補 domain map（實證：某個移動應用實作案例中於實作前補建）。Action：spec FR 填完後、測試設計前，為每個 domain 產出或更新 domain map。
動作：用 doc skill 的 domain-map-template 為每個 domain 產出 domain map（多 domain 專案放 domain 子目錄，單 domain 專案放 docs/ 根層）：
# 多 domain 專案：放對應 domain 子目錄
cp .claude/skills/doc/templates/domain-map-template.md docs/spec/{domain}/domain-map.md
# 單 domain 專案：放 docs/ 根層
cp .claude/skills/doc/templates/domain-map-template.md docs/domain-map.md
PM 工作：依模板從 spec FR 反推 bundle 邊界（切分判準見 .claude/methodologies/domain-bundle-mapping-methodology.md）——界定 aggregate / kernel / read-model 分類、依賴方向 DAG（用實際 import 鏈驗證，不憑心智模型宣告——如 grep -rn "import.*<lower_layer>" lib/<domain_dir>/ 或 codegraph callers，確認 import 集合不含被禁層）、每 bundle 的目標路徑與測試層、FR→bundle 全覆蓋表。
產出或更新語意：saas 起手的版本，saas Stage 1/2 的 DDD 切分已餵入 domain map 的產出端，本步驟將其精修為層/依賴/測試 map；非 saas 起手（提案 / handoff 起手）則從模板新建。此語意消除「domain 規劃綁死 saas 起手」——標準化為所有規劃波的通用步驟。
被誰消費：Step 5 測試設計依 domain map 逐 bundle 決定測試層（domain unit / data repository / presentation widget）；Step 6 建票依 domain / data / presentation 分層切分。
Checkpoint：每個 domain 有 domain map；依賴方向底線經 import 鏈驗證；spec 全部 FR 在 FR→bundle 覆蓋表有歸屬（含標為非 domain 的 presentation / data FR）。
Step 2.6：資料契約產出（半自動）
Why：spec FR 定義欄位存在，不定義欄位的值域、狀態責任分層、不變式、交易邊界、錯誤語意與恢復模型；domain map §3 Bundle 界定表的 data/infrastructure 列只標「持久化細節屬 data 層」，未展開細節。Consequence：跳過本步驟，資料層設計意圖（為何選這個約束、哪些不變式由 DB 保證）無專屬載體，散落於 DDL 註解與 repository 程式碼各處；Step 5 測試設計對資料層契約條目無盤點依據，覆蓋缺口不可審計（見
.claude/methodologies/data-layer-contract-methodology.md第 6 節）。Action：spec FR 與 domain map 完成後、紅燈測試設計前，依兩旗標判準決定是否產出資料契約文件。
動作：先依 .claude/methodologies/data-layer-contract-methodology.md 第 2 節兩正交旗標（契約文件 / migration 治理）判定（本步驟不複寫判準內容，僅引用）。兩旗標皆否時，僅維持 schema 約束 + DDL 註解即為合法終態，本步驟到此結束（合法跳過文件產出，非偷懶）。任一旗標為要時，cp 模板產出：
# 沿用 SPEC-NNN 編號體系，subdomain 固定為 data-contract
cp .claude/skills/doc/templates/data-contract-template.md docs/spec/{domain}/{name}-data-contract.md
消費來源：spec FR 列表（欄位語意/值域）+ domain map data 層（§3 Bundle 界定表 Infrastructure/data 列的「資料契約文件引用連結」欄）。
PM 工作：依模板填寫 A 區（邏輯契約，DB-agnostic）與 B 區（實作綁定，DB-specific），完成後執行 doc query <SPEC-ID> 做 doc CLI 驗證——確認 frontmatter 有效、文件可被查詢發現。
被誰消費（feed Step 5）：每條契約條目（不變式/欄位語意/邊界行為）登錄至 docs/traceability.yaml 第三軸 data_contract_tests；Step 5 派發 sage 時一併帶入此軸，供測試設計逐條盤點覆蓋缺口，避免資料層規則只靠「剛好被某測試涵蓋」被動覆蓋。
Checkpoint：兩旗標已判定並記錄理由（含合法跳過情形）；旗標=要時，資料契約文件已產出且 doc query 查詢成功；traceability.yaml 第三軸 data_contract_tests 已初始化，契約條目與測試對應無 TODO 佔位。
Step 3：教學比對（半自動）
動作：對每份完成的 spec 執行 /spec validate（Full 模式，含維度 4 教學一致性）。
前置：確認 CLAUDE.md「教學模組對應表」中有對應模組。
PM 工作：
- 偏移（高/中）：對齊教學設計或先在 blog 補完
- 教學缺口：在 blog 對應模組補完後再回來
Checkpoint：維度 4 無高嚴重度偏移。教學缺口已處理或標記 sync-pending。
Step 4：建 UC + traceability（半自動）
動作：Step 2 的 batch-init 已同時建立 UC 骨架和 traceability 映射佔位。
PM 工作：填寫每份 UC 的 GWT 場景、更新 traceability 映射（spec FR → UC scenario）。
Checkpoint：所有 UC 場景填寫完成，traceability 映射無 TODO 佔位。
Step 4.5：地基波（半自動，僅含 UI 提案的版本）
Why：測試設計（Step 5）需驗 zh/en overflow 與元件互動反應，這些依賴 i18n 系統與元件實體先存在；若 Step 4 後直接進 Step 5，UI 版本會在 i18n / design-system / 元件庫尚未 build 時進測試設計，無可驗對象。Consequence：跳過本步驟，測試票會假設不存在的 i18n key 與元件，Phase 3b 才暴露缺地基，需回頭補甚至推翻測試設計（實證：地基波經指正後手動插入）。Action：對含 UI 提案的版本，於測試設計前編排地基波實作波。
動作：依 component-library 方法論〈地基波 build 順序〉為權威，編排四塊地基實作：
| 順序 | 地基塊 | 產出 |
|---|---|---|
| 1 | i18n 系統 | 多語系資源檔 + 產生器（元件文字取 i18n key，測試可驗 zh/en overflow） |
| 2 | design-system 實作 | design token 集中檔（消費 Step 2 的 design-system spec） |
| 3 | UX 審查 | 每個互動元件的反應/動畫/提示 + 頁面跳轉/退出/生命週期完整性審查（產出反應規格供元件庫與測試點） |
| 3.5 | 元件契約 | L3 元件庫章節補齊逐元件元件契約欄位表與容器條目（程序見 component-contract-design skill，判準見方法論〈元件契約判準〉）；checkpoint 為該 skill 的〈契約齊全的定義〉 |
| 4 | 元件庫實作 | 集中元件庫（套 token + i18n + UX 反應，依契約實作），barrel 匯出 |
PM 工作：為四塊各建實作票，另為元件契約建 DOC 票——i18n 與 design-system 可並行；UX 審查產出反應規格；元件契約依賴 UX 審查；元件庫依賴前三塊與元件契約為 blockedBy。順序與依賴依方法論〈地基波 build 順序〉，本 skill 不重複判準只做 orchestration。
Checkpoint：UI 版本的 i18n / design-system / UX 審查 / 元件庫四塊實作完成並測試綠；非 UI 版本略過本步驟（比照 Step 2 UI 判別）。
Step 5：紅燈測試設計（半自動，可並行）
動作：對每份 spec 派發 sage-test-architect 做 Phase 2 紅燈測試設計，依紅燈層級順序分兩段產出：
- 5a 外圈驗收紅燈（先）：對
runtime_surface: yes的 UC 場景產出整合層測試描述，含 on-device / 端對端層級；外圈定義「什麼叫做完」，以 wip tag 與 gate 隔離。runtime_surface: no的場景豁免本段（豁免判準見權威節，此處不複寫）。 - 5b 內圈單元紅燈（後）：規格分解的單元測試設計，驅動實作紅綠循環。
順序規則、豁免判準與 wip tag 共存機制的權威定義見 /tdd skill references/phase2/rules.md「紅燈層級順序」節，此處不複寫。
多 spec 可並行派發（每個 spec 1 張子票）。派發時使用 /tdd Phase 2 流程，sage 產出紅燈測試規格（5a + 5b 兩段皆屬同一 Phase 2 產出）。
消費 Step 2.5 domain map（兩軸測試設計）：
- 層軸：依 domain map 逐 bundle 決定測試層——domain bundle 走純函式 unit test、data 走 repository test、presentation 走 widget test（分層測試策略見
.claude/methodologies/hybrid-testing-strategy-methodology.md）。 - 不變式軸：依 domain map 的「Bundle 不變式清單」節逐 bundle 列舉 domain 行為不變式測試（例：某項缺漏沿用前值、比率分母為 0 的定義值、依賴方向不成環等各專案自己的 domain 不變式），與 UC 場景測試並存去重——UC 場景測試涵蓋垂直使用者行為，不變式測試涵蓋水平 domain 規則，兩軸交集去重、聯集為完整覆蓋。避免 domain 規則只靠「剛好出現於某 UC 場景」被動覆蓋。
sage 派發 prompt 應同時帶 spec FR / UC 場景（既有）與 domain map 的 bundle 不變式清單（新增），使兩軸都被系統列舉。traceability 的 domain-bundle→test 軸（見下）記錄不變式軸覆蓋。
PM 工作：驗收 sage 產出——確認 FR↔AC 覆蓋矩陣（Q12）無空行。
Checkpoint：所有 spec 的 Phase 2 完成，紅燈測試規格已提交。
Step 6：匯總建票（半自動）
動作：根據 Step 2-5 的產出，建立 W2/W3/W4 的 IMP ticket。
- W2/W3：GREEN 實作票（每個 spec FR 或功能模組 1 張）
- W4：驗收票（E2E + Phase 4）
建票來源：
- spec FR 列表 → IMP ticket
- Phase 2 紅燈規格 → 確認 ticket 粒度（每張 ticket 的紅燈數）
- UC 場景 → 整合測試 ticket
- domain map bundle 分層 → 按 domain / data / presentation 切分實作票，並依 domain map §5「對實作票切分指引」對齊各票的層歸屬與依賴方向底線
PM 工作：確認 Wave 分配、並行安全（共用檔案需整合票）。
Checkpoint：所有 ticket 建立完成，Wave 分配確認。
反應式工作（不納入 bootstrap）
以下工作在規劃波過程中可能發生，但不屬於 bootstrap pipeline：
| 類型 | 處理方式 |
|---|---|
| 既有測試回歸 | incident-responder 分析，建 ANA/IMP ticket |
| Spec 約束邊界發現 | 建 ANA ticket，可在 Step 2 填寫時順帶處理 |
| 流程改善發現 | 建 ANA ticket，排入後續 Wave |
移版硬耦合盤點 SOP
提案因跨提案依賴矛盾（Step 1 檢查結果）或其他理由決定移版時，禁止整包提案原封不動搬到新版本——必須先盤點該提案在本版留下的 schema / DDL / 契約級殘留耦合，比照下方動機案例「契約先定形、業務邏輯後移版」的模式先行定形，斬斷後才能讓移出的主體與留在本版的部分變成獨立軌道。
動機：曾有版本規劃雙提案，其中一提案因依賴另一個排在更晚版本的提案而整體移版，但其變更清單第一項會動到契約 SOT 檔案（如 schema 定義）並牽動資料庫 DDL——若放任不管、等本版 DDL 凍結後才在移版目標版本定形該欄位，會重演過往「先上線、後補契約定義」造成的多階段漂移。提前在 DDL 凍結前定形該欄位形狀，才讓兩個提案真正解耦。
盤點步驟：
| 步驟 | 動作 | 產出 |
|---|---|---|
| 1. 契約掃描 | 對照移版提案的 checklist，逐項檢查是否觸及 schema/*.schema.json、docs/spec/**/*.md 的 DDL 章節、或其他跨版本共用契約檔案 |
觸及項清單 |
| 2. 凍結時序確認 | 確認本版是否有「DDL 凍結」「schema 定案」類的既定時間點（通常在 PG/儲存實作票之前） | 凍結時間點 + 是否早於移版提案原訂完成時間 |
| 3. 硬耦合分級 | 觸及項逐一判斷：純程式邏輯（無耦合，可整包移版）vs 契約形狀（硬耦合，需本版先定形） | 硬耦合項清單 |
| 4. 定形票建立 | 對每個硬耦合項建立獨立 IMP ticket（比照上方動機案例的定形票模式），範圍限定「只定形契約形狀，不含業務邏輯實作」 | 定形 ticket（本版 Wave 排入） |
| 5. 教學比對 | 依 CLAUDE.md 強制操作 2，定形前讀 blog 對應模組確認欄位設計是否已有教學定義；有則優先採用，無則先在 blog 補完 | Solution 段落記錄教學比對結論 |
| 6. Ticket 交叉標記 | 定形票 why 欄位引用移版提案 ID + 目標版本；移版提案的 checklist 對應項標記 verified_by 指向定形票 |
雙向可追溯 |
判斷準則（步驟 3 分級）：
| 觸及類型 | 是否硬耦合 | 處理方式 |
|---|---|---|
修改 schema/event.schema.json 等契約 SOT 檔案 |
是 | 建定形票，本版執行 |
修改 DDL（CREATE TABLE 欄位定義） |
是 | 建定形票，本版執行 |
| 純業務邏輯（middleware、演算法、UI） | 否 | 整包隨提案移版 |
| 僅讀取既有契約、不新增欄位 | 否 | 整包隨提案移版 |
與早期手動流程的對照
| 早期手動流程 | /version-bootstrap |
|---|---|
| 手動 cp 模板建 spec | Step 2 /doc batch-init |
| 手動讀 blog 比對 | Step 3 /spec validate --dim 4 |
| 手動 cp 模板建 UC | Step 2 /doc batch-init（同步建立） |
| 手動編輯 traceability | Step 2 自動佔位 + Step 4 填寫 |
| 逐一派 sage | Step 5 批量並行派發 |
| 手動建票 | Step 6 依產出匯總 |
版本紀錄在同目錄的 CHANGELOG.md。