以 worktree 建立工作包分支並備妥隔離環境 #40

New Issue

2026-09-17T07:12:24Z

jiantw83 commented

2026-09-17 07:12:24 +00:00

母議題

#38 — 以 worktree 隔離平行工作包的實作與修正

要做出什麼

開發者領取工作包時，不再在原地切換分支，而是拿到一棵屬於這顆工作包的獨立工作樹（worktree）。從此他同時持有幾顆工作包都互不干擾：各自的未提交變更、各自的建置產物，而 agent 無論什麼時候去讀檔，都只會讀到它該讀的那份程式碼。

工作樹一律建立，沒有例外。建立失敗時明確報錯中止，不默默退回原地切分支——靜默降級會讓使用者以為自己在隔離環境裡，其實在原地改。

建分支與建工作樹是同一個原子動作：先 git fetch 更新遠端引用，再以一次 git worktree add -b {新分支} {推導路徑} origin/{來源分支} 完成。一律從遠端的來源分支長出，起點永遠是最新的；遠端不存在該來源分支時明確中止，不退回本機同名分支。不設 upstream——此刻遠端還沒有這個新分支，設了會誤指到來源分支，之後 git pull 會把來源分支的提交拉進來。

工作樹路徑由 owner/repo/分支名 正規化後取雜湊推導，不需要任何本機對照表或狀態檔，換機器推導結果一樣。

碼錶要等工作樹建成之後才起動。現行流程把起錶排在分支處理之前，而工作樹建立失敗會中止——錶已經起了才失敗，使用者會被計一段什麼都沒做的時間，而工時要準正是工時報表的立足點。

工作樹建好後印出提示：它是乾淨的，沒有依賴也沒有建置產物。安裝指令依專案檔偵測產生，偵測不到就只說明它是乾淨的。機密檔案一律不自動複製。

本工作包取代 #11 驗收標準第 4 條（「來源分支在遠端已存在時執行 pull 而非重建」），#11 本身不修改，實作時以 #38 為準。

驗收標準

領取工作包時一律建立工作樹，無例外
工作樹路徑為 ~/.tea-sdlc/worktrees/{hash}，hash 為正規化後 owner/repo/分支名 的 sha256 前 12 碼
路徑推導有表格驅動測試：大小寫與空白的變體推導出同一路徑；分支名含斜線；feat/a-b/main 與 feat/a/b/main 不撞名
建立前先 git fetch 更新遠端引用
以單一 git worktree add -b {新分支} {推導路徑} origin/{來源分支} 完成，不拆成先建分支再建工作樹
遠端不存在指定的來源分支時明確中止，錯誤訊息指出該推分支或改指定來源
建立失敗時不留下任何分支或工作樹的半成品
不為新分支設定 upstream
碼錶在工作樹建成之後才起動；建立失敗的情境中不得發出任何起錶請求
工作樹建好後印出「乾淨工作樹」提示，安裝指令依專案檔偵測產生，偵測不到時只說明它是乾淨的
不複製或連結 node_modules、vendor、建置快取或任何機密檔案
分支命名規則不變，仍依 #11 第 5 條
--dry-run 輸出將執行的 git 指令而不實際執行
測試在臨時 git repo 上跑真實 git，以本機裸 repo 充當遠端，不需網路

阻擋於

#11 — 以 sdlc-feat 領取工作包、起錶並備妥分支

## 母議題 #38 — 以 worktree 隔離平行工作包的實作與修正 ## 要做出什麼開發者領取工作包時，不再在原地切換分支，而是拿到一棵屬於這顆工作包的獨立工作樹（worktree）。從此他同時持有幾顆工作包都互不干擾：各自的未提交變更、各自的建置產物，而 agent 無論什麼時候去讀檔，都只會讀到它該讀的那份程式碼。工作樹一律建立，沒有例外。建立失敗時**明確報錯中止**，不默默退回原地切分支——靜默降級會讓使用者以為自己在隔離環境裡，其實在原地改。建分支與建工作樹是**同一個原子動作**：先 `git fetch` 更新遠端引用，再以一次 `git worktree add -b {新分支} {推導路徑} origin/{來源分支}` 完成。一律從遠端的來源分支長出，起點永遠是最新的；遠端不存在該來源分支時明確中止，不退回本機同名分支。不設 upstream——此刻遠端還沒有這個新分支，設了會誤指到來源分支，之後 `git pull` 會把來源分支的提交拉進來。工作樹路徑由 `owner/repo/分支名` 正規化後取雜湊推導，不需要任何本機對照表或狀態檔，換機器推導結果一樣。碼錶要**等工作樹建成之後**才起動。現行流程把起錶排在分支處理之前，而工作樹建立失敗會中止——錶已經起了才失敗，使用者會被計一段什麼都沒做的時間，而工時要準正是工時報表的立足點。工作樹建好後印出提示：它是乾淨的，沒有依賴也沒有建置產物。安裝指令依專案檔偵測產生，偵測不到就只說明它是乾淨的。機密檔案一律不自動複製。本工作包**取代** #11 驗收標準第 4 條（「來源分支在遠端已存在時執行 pull 而非重建」），#11 本身不修改，實作時以 #38 為準。 ## 驗收標準 - [x] 領取工作包時一律建立工作樹，無例外 - [x] 工作樹路徑為 `~/.tea-sdlc/worktrees/{hash}`，`hash` 為正規化後 `owner/repo/分支名` 的 sha256 前 12 碼 - [x] 路徑推導有表格驅動測試：大小寫與空白的變體推導出同一路徑；分支名含斜線；`feat/a-b/main` 與 `feat/a/b/main` 不撞名 - [x] 建立前先 `git fetch` 更新遠端引用 - [x] 以單一 `git worktree add -b {新分支} {推導路徑} origin/{來源分支}` 完成，不拆成先建分支再建工作樹 - [x] 遠端不存在指定的來源分支時明確中止，錯誤訊息指出該推分支或改指定來源 - [x] 建立失敗時不留下任何分支或工作樹的半成品 - [x] 不為新分支設定 upstream - [x] 碼錶在工作樹建成之後才起動；建立失敗的情境中不得發出任何起錶請求 - [x] 工作樹建好後印出「乾淨工作樹」提示，安裝指令依專案檔偵測產生，偵測不到時只說明它是乾淨的 - [x] 不複製或連結 `node_modules`、`vendor`、建置快取或任何機密檔案 - [x] 分支命名規則不變，仍依 #11 第 5 條 - [x] `--dry-run` 輸出將執行的 git 指令而不實際執行 - [x] 測試在臨時 git repo 上跑真實 git，以本機裸 repo 充當遠端，不需網路 ## 阻擋於 - #11 — 以 sdlc-feat 領取工作包、起錶並備妥分支

jiantw83 added the ready-for-agent label 2026-09-17 07:12:24 +00:00

jiantw83 added a new dependency 2026-09-17 07:12:25 +00:00

#11 以 sdlc-feat 領取工作包、起錶並備妥分支

jiantw83 added a new dependency 2026-09-17 07:12:26 +00:00

#41 以 pr-watch 回報 PR 現況並清理工作樹

jiantw83 added a new dependency 2026-09-17 07:12:26 +00:00

#42 以 sdlc-fix 定位工作包的工作樹

jiantw83 referenced this issue

2026-09-17 07:12:36 +00:00

以 pr-watch 回報 PR 現況並清理工作樹 #41

jiantw83 referenced this issue

2026-09-17 07:12:36 +00:00