plugins/tea-sdlc
2
0
Fork 0
Code Issues 3 Pull Requests Actions Releases Activity
151 Commits 1 Branch 0 Tags
46c6db8c705ac50e1587eec0d2b53fa882a93b7d
Commit Graph
151 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
jiantw83andClaude Opus 5 46c6db8c70 feat(time-log): 對既有議題重跑時補到當下，每一輪各記一筆 
原本的終點一律是議題的建立時間，所以對既有議題重跑時相減為負，補登直接 no-op——
那一輪的規劃時間就這樣掉了，而那正是這顆議題要修的毛病，只是換個位置出現。

終點改成看議題是不是這一輪建立的：是就補到議題建立那一刻（第一次跑），不是就補到
補登的當下（重跑）。回報多出 `迄` 與 `依據` 兩個欄位，讓人一眼看出這一筆補的是哪一段。

「這顆議題上已經有工時就跳過」這條規則拿掉了，它與累計互斥。防重複只剩一條：錶已經
跑在這顆議題上——那一段已經有錶在記，補下去會與錶涵蓋的區間重疊。連帶把 lib 的
listIssueTimes 一起移除，沒有人再用它。

實跑驗過（議題 #57）：補登 121 秒、起錶、停錶 7 秒，兩筆都進得了週報，驗完刪除。
議題 #57 的規格同步更正，另外兩處過期的敘述也一併改掉。

議題 #57

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-18 08:46:27 +08:00
jiantw83andClaude Opus 5 7ee050de2f docs(sdlc-plan,sdlc-analyze): 兩份正本各自起停自己的錶 
起錶與停錶寫在同一份正本裡成對出現，讀的人一眼看得出這段計時涵蓋到哪；兩份各加一節
「計時範圍」把兩端指出來。

sdlc-plan 記兩段：議題建立之前那段在第一步記下開始時間、議題建立之後以補登記上去；
之後起錶，回報那一步停錶。補登排在議題建立之後、起錶之前，順序反過來的話補登會被
time-log 當成「這一步做過了」而跳過。

sdlc-analyze 在它分析的那顆需求議題上起錶，起點放在第一段開頭——分析最耗時的正是
共識之前那一段，從第二段才起的話那段時間永遠是零。因此「共識摘要之前不對 Gitea
產生任何寫入」改寫成「不寫入任何**內容**」，並把碼錶明文除外、寫上理由：它記的是
工時，不是內容。這一條與 repo 擁有者確認過。

sdlc-feat 的「碼錶一律由使用者自己停」收斂成「**別顆議題上的**錶一律由使用者自己停」
——它原本讀起來像全域規則，而現在每道指令都會停自己起的那一支。

正本之間改以步驟**名稱**互指，不用編號：編號會整批位移，名字不會。測試跟著改用新的
promptStep 輔助函式，以名字框出某一步的內容，別人插一步時不會無聲地框到另一段上。

議題 #57

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 19:32:37 +08:00
jiantw83andClaude Opus 5 81d02bffcf feat(timer,time-log): 起錶配上停錶，並補登議題建立之前的時間 
碼錶只在領取工作包時起動，所以工時報表上規劃與分析永遠是零。久了會讓人以為
規劃不花時間，而那正是估算失準最常見的來源。

timer 加上 --stop，而且**只停 --index 指的那一顆**。每個階段停掉自己起的那一支，
錶就不會跨階段跑——跑完就去開會而錶跑一整天，報表當場失真。反過來，別顆議題上的錶
一律不碰：Gitea 在別顆議題上起新錶會靜默地停掉並記錄前一顆，那種靜默結算正是領取鎖
那條規則當初要擋的，不能在這裡反過來製造它。錶本來就沒在跑不算失敗，這一步多半排在
回報之前，報成失敗只會讓人以為前面那件事沒做成而重跑一次。

time-log 補登議題建立之前那一段——讀齊輸入、逐項詢問、組出議題內容，往往是整個 plan
最耗時的部分，而那時候議題還不存在，沒有標的可起錶。長度由腳本自己算（議題的建立時間
減掉 --since），交給 agent 做減法等於讓兩邊的時鐘各算一次，而算錯了報表上看不出來。
**不設時間上限、照實補登**：中途去開會的兩小時會一起算進去，換來這個流程不必為此
多長一題出來問使用者。

補登不是冪等的動作，所以兩種情況跳過不補：錶已經跑在這顆議題上（補登排在起錶之前，
錶在跑就代表這一段補過了），以及這顆議題上已經有工時（整個流程跑完過一次）。工時記
重複比記不到更難在報表上被發現，所以判斷偏向不補。

時間追蹤在現有環境下可能是關著的，真實路徑跑不起來；兩支都靠 --dry-run 與 stub
server 測，共 27 條。

議題 #57

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 19:32:20 +08:00
jiantw83andClaude Opus 5 5638593c4c refactor(lib): 停錶與議題工時清單下沉到 lib 
停錶原本只長在 pr-create 裡，而規劃與分析接下來也要停自己的錶（議題 #57）。
那段容錯邏輯——「錶沒在跑」的狀態碼隨站台版本而異，認的是狀態碼在 409/500
這一組**且**訊息說的是碼錶——各寫一份遲早會在某一邊漏掉一種狀態碼，而它漏掉的
症狀正是「事情做完了卻回報失敗」。

順手把簽章改成與同伴一致的 (login, repo, index)：fetchIssue、listIssueTimes、
stopwatchOnIssue 都這樣收，只有它收一條手組的路徑字串。

新增 listIssueTimes 供補登判斷「這顆議題上已經有工時了嗎」。它在議題讀得到卻
404 時報 TIME_TRACKER_OFF，與四層前置檢查第四層說同一句話——試跑不跑前置檢查，
那句話得由它自己說，否則試跑看到的是一句看不懂的 404。

議題 #57

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 19:32:01 +08:00
admin c2ca7fbf07 Merge pull request 'fix/pr-create-stopwatch-and-docs/main' (#55) from fix/pr-create-stopwatch-and-docs/main into master 
Reviewed-on: #55
 2026-09-17 09:54:55 +00:00
jiantw83andClaude Opus 5 9ed719a4d7 fix(pr-create): 錶沒在跑時 409 與 500 都不算失敗 
Gitea 回「cannot stop a non-existent stopwatch」時用的狀態碼隨站台而異：這台回 409，
而腳本只認 500。結果是 PR 已經開出去了，卻以 exit 1 與 HTTP_ERROR 收場——照它自己
寫下的理由，那會讓人以為 PR 沒開成而重跑一次。三次重現（議題 #41、#50、#42）。

認的是「狀態碼在 409/500 這一組 **且** 訊息說的是碼錶」：只看訊息會把真的伺服器錯誤
一起吞掉，只看狀態碼會把別的衝突也當成沒錶。兩種狀態碼各一條測試，另加一條
「訊息對不上的 409 照常拋出」。

README 與 AGENTS.md 的「六個流程正本尚未到齊」也一併改掉——六份都在了，那句話會讓
使用者以為裝了也沒指令可用，在 AGENTS.md 裡還會誤導下一個 agent。並補一條測試把說法
與 prompts/ 的實際份數釘在一起，免得下次又走鐘。

議題 #54

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:46:43 +08:00
admin 1c678d311a Merge pull request 'feat/sdlc-fix-worktree/main' (#53) from feat/sdlc-fix-worktree/main into master 
Reviewed-on: #53
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-17 09:35:40 +00:00
jiantw83andClaude Opus 5 66064a751e fix(lib): 補回搬家時掉了的 rmSync，並讓 origin 檢查只有一份 
review 抓到一個沉默的失效：rollback 最後那一手「git 清不乾淨時把目錄本身也清掉」呼叫
rmSync，但把這段從 branch-prep 搬進 lib 時，import 留在了原處。那一行落在自己的
try/catch 裡，所以 ReferenceError 被吞掉——註解承諾的事從來沒發生過，而且測試全綠。
下一次重跑會撞上 WORKTREE_PATH_TAKEN，人看到的是一句與真正原因無關的錯誤。

順手收掉兩支腳本各寫一次的 origin 檢查（只有「為什麼需要它」那一句不同，由呼叫端給），
並把 lib 檔頭「負責六件事」改成七件——工作樹的一生現在整個住在這裡。

正本三處跟著改：
- 查現況那一行補上 --dry-run。pr-watch 在 PR 已終止時會順手清掉工作樹，而「我想看一下
  留言」不該把清理順便做掉——清不清理是使用者的決定。
- 拿掉「使用者堅持要繼續就繼續」：它與同一份正本的邊界（已合併或關閉時不繼續處理留言）
  直接矛盾，而在一棵該被清掉的工作樹上改東西，那些改動不會進到任何 PR 裡。
- worktree-ensure 的指令補上 --path：目標專案多半不是當前目錄，而「不必先手動 cd」
  正是這一步要解決的問題。

議題 #42

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:33:44 +08:00
jiantw83andClaude Opus 5 0dd8d7b7bb docs(sdlc-fix): 第一步先看 PR 現況，再定位工作樹 
補上 #14 沒有的工作樹概念：它預設在當前目錄處理留言，而留言要改的程式碼在那顆工作包
自己的工作樹裡。新的第一步先問 pr-watch 現況——PR 已經合併或關閉就停下來，在一棵該被
清掉的工作樹上處理留言是白做工——再用 worktree-ensure 定位，不在就重建。

邊界同時擋住兩件事：不回主工作區處理留言（它可能停在別的分支上），以及推導路徑上有
別的東西時不自己刪。原有的五個步驟整體往後移一號，內容不變。

議題 #42

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:33:44 +08:00
jiantw83andClaude Opus 5 2562555058 feat(worktree-ensure): 定位工作包的工作樹，不在就重建 
處理 PR 留言的人不必先手動 cd 到正確的目錄：路徑由 owner/repo/分支名 純函式推導，
問這一支就知道該在哪裡動手。

「不在就重建」是常態不是防禦性程式設計。進度完全不寫在本機——換一台機器或換一個
agent 接手時，工作樹本來就不存在，而重建的成本就是一次 git worktree add。

兩種情況明確中止而不是硬幹：分支在本機與遠端都不見時報 BRANCH_NOT_FOUND（憑空長一棵
空的工作樹只會讓人以為進度還在），推導出的路徑上是別的東西時報 WORKTREE_PATH_TAKEN。

議題 #42

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:33:44 +08:00
jiantw83andClaude Opus 5 7196385c5e refactor(branch-prep): 建立工作樹的「算」與「做」收進 lib 
重建工作樹（下一個 commit 的 worktree-ensure）要走的是與開工時完全同一套：一樣先
git fetch 更新遠端引用，一樣不設 upstream，分支已經存在就接上去而不是長一棵空的。
兩邊各寫一份，遲早會在「起點取自哪裡」這種地方分岔——而那種分岔要等到有人的進度
不見了才會被發現。

planWorktree 多接受一種用法：不給來源分支就是「重建既有分支的工作樹」，沒有「從來源
長一支新的」那條路，走到那裡就是 BRANCH_NOT_FOUND。branch-prep 的行為完全不變。

議題 #42

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:33:44 +08:00
admin 643293b21c Merge pull request 'feat/comments-merge/main' (#52) from feat/comments-merge/main into master 
Reviewed-on: #52
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-17 09:22:58 +00:00
admin 3a435bf2d9 Merge pull request 'fix/pr-head-after-merge/main' (#51) from fix/pr-head-after-merge/main into master 
Reviewed-on: #51
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-17 09:19:25 +00:00
jiantw83andClaude Opus 5 ceb723c63e test(流程正本): 新增 sdlc-sync，並讓另外兩份正本整併完自動接回 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:11 +00:00
jiantw83andClaude Opus 5 f85fabb758 feat(流程正本): 新增 sdlc-sync，並讓另外兩份正本整併完自動接回 
挑出哪些留言真的是決策、寫回去之前讓使用者點頭、略過的保持未標記——三件都只有正本做得到。

analyze 與 feat 原本寫「建議先執行 /sdlc-sync，再回來」，那等於要使用者重打指令。改成直接走
sync 的流程、做完自動接回，並在接回前重新抽取一次——接著用舊的那一份做事，這一整段就白做了。

略過的留言會讓未處理留言數停在大於 0，於是 analyze 與 feat 每次都會再停一次。這是驗收標準
本身的兩條放在一起的結果，正本把它講明白，讓使用者分得出「沒整併乾淨」與「我選了略過」。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:10 +00:00
jiantw83andClaude Opus 5 3ad08be14f test(comments-merge): 把留言裡的決策整併回議題描述並標記 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:10 +00:00
jiantw83andClaude Opus 5 16f93f6e8b feat(comments-merge): 把留言裡的決策整併回議題描述並標記 
判斷「哪幾則有決策、該併進哪一段」是讀得懂內容的人的事；這一支只負責把結果安全地寫回去。

先寫描述再標記，描述寫失敗就不標記：反過來的話，那幾則已經被標成處理過，再也不會被提出來。
--merged 只收真的併進去的那幾則，略過的保持未標記。標記之前先核對那幾則確實在這顆議題上——
打錯 id 的 reaction 會落在別顆議題的留言上，而那幾乎不會有人發現。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:09 +00:00
jiantw83andClaude Opus 5 5ef25d3ee9 test(抽取契約): 未整併的判定改成只認自己打的 +1 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:08 +00:00
jiantw83andClaude Opus 5 c1ab712afd feat(議題解析): 換掉一個段落的內容，標題與其餘段落一字不動 
整併留言裡的決策時用它。不整份重寫的理由跟 upsertLineInSection 一樣，只是代價更大：
重寫會把別人在其他段落的編輯一起蓋掉，而議題的編輯紀錄沒有人會去比對。

三件事照著同檔既有的規矩做：圍欄裡的假標題不算段落；同名標題出現不只一次時交回 ambiguous
而不賭第一個（蓋掉的是一整段，猜錯的代價比 tickLine 更高）；換行沿用 body 原本的那一種，
CRLF 的 body 裡混進 LF 會讓抽取契約交出的 raw 對不上原文，之後就勾不動那幾行。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:08 +00:00
jiantw83andClaude Opus 5 3b7e3bdfc7 test(pr-comments): 議題也讀得了，不再先打 PR 端點 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:07 +00:00
jiantw83andClaude Opus 5 051fe0ded4 fix(pr-comments): 議題也讀得了，不再先打 PR 端點 
每個 PR 都是議題，議題不一定是 PR——原本的註解把這句話講反了，程式也照著反過來寫：
先打 /pulls/{index}，對純議題回 404，於是 /sdlc-sync 在讀到第一則留言之前就斷了。

改成先讀 /issues/{index}（兩種都有），看它有沒有 pull_request 才決定要不要去翻 review。
輸出加上「類型」讓下游知道拿到的是議題還是 PR。

讀取的共用結構沿用 pr-threads（#48 為了讓 pr-watch 數同一件事而抽出來的）：readGeneral
改名 readGeneralComments 並導出，純議題只叫它；pr-threads 自己那份 markedByMe 拿掉，
改用 lib 的 mergedByMe。#48 的檔頭擔心「規則寫兩份遲早會各自演化」，現在三處共用一份。

試跑改印 commonRequests：pr-comments 收得下兩種輸入，而試跑階段還沒讀過議題、不知道是
哪一種。與其假設是 PR 而列出五個（對純議題有三個根本不會發），不如只列一定會發的。
pr-watch 的輸入一定是 PR，繼續用 plannedRequests。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:06 +00:00
jiantw83andClaude Opus 5 b263915afc test(pr-create): 讀檔與列留言收進 lib，並讓已整併只認自己打的 +1 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:05 +00:00
jiantw83andClaude Opus 5 ee474d0439 refactor(lib): 讀檔與列留言收進 lib，並讓已整併只認自己打的 +1 
「讀一個 --xxx-file 或直接失敗」原本在四支腳本各寫一份，錯誤碼還有三種拼法
（BODY_FILE_NOT_FOUND／BODY_FILE_MISSING／CONTENT_FILE_NOT_FOUND）。同一種情況要有同一個
碼，呼叫端才分辨得出是哪一步壞了。留言分頁的那段咒語也是第三份，一併收成 listIssueComments。

countUnmergedComments 原本接受任何人的 +1，而讀留言那邊只認自己的——兩端對「已整併」的
定義不一致。後果是隊友對決策留言按個讚，未處理留言數就掉到 0，analyze 與 feat 再也不提示，
那則決策永遠不會被收進描述。統一成只認自己打的：別人按讚是「我同意」，不是「已經收進去了」。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 09:19:05 +00:00
jiantw83andClaude Opus 5 695694b3fd fix(pr-watch): 來源分支被刪掉之後，改從 head.label 取分支名 
PR 合併而來源分支被刪掉之後，Gitea 把 head.ref 換成 refs/pull/{編號}/head，分支名
退到 head.label。pr-watch 用的是 head.ref，於是推導出一條根本不存在的工作樹路徑，
回報「工作樹不在、沒事要做」——而合併正是唯一該清理工作樹的時機，等於自動清理在真實
情況下從來不會成立，而且靜悄悄的，沒有人會發現。

實測 #48（合併後）推導出 bb4f5127f641，真正的那一棵在 bd457620184e。

fork 來的 PR 的 label 是 owner:branch，只取分支那一段。兩邊都取不到時明確中止
（PULL_HEAD_MISSING），並指出手動出口怎麼指名那一棵，不拿空字串去推導路徑。

測試先前沒抓到，是因為假的 PR 一律照「開著的 PR」寫，head.ref 永遠是分支名。
補上「已合併且來源分支已刪」與 fork 兩種 head 的樣子。

議題 #50

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:16:44 +08:00
admin d0e7e569a3 Merge pull request 'feat/pr-watch-and-cleanup/main' (#48) from feat/pr-watch-and-cleanup/main into master 
Reviewed-on: #48
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-17 09:09:53 +00:00
jiantw83andClaude Opus 5 617a3eef72 fix(pr-watch): 試跑的預告與實跑的守門對齊，並說出路徑被佔住這件事 
review 抓到一處落差：試跑判「終止且工作樹乾淨」就預告 git worktree remove，
但實跑多判一件事——那條路徑上的東西是不是真的一棵工作樹。別的 clone 在同一條路徑上
留下目錄時（路徑由 owner/repo/分支名 推導，不含本機 clone 的位置），試跑會預告一行
實跑必然拒絕的指令，而回報裡完全看不出原因。

判斷收進 lib 的 inspectWorktree，由它直接給出 reason（missing／foreign／dirty／
removable）：試跑與實跑、自動與手動四條路徑從此擋在同一個判斷上，worktree-remove 裡
那份重算的副本也跟著刪掉。回報多一個「是工作樹」欄位，手動出口的 NOT_A_WORKTREE
不再是使用者第一次聽到這件事。

順帶兩件同源的修正：
- 「是不是工作樹」改認 .git 為**檔案**。獨立 clone 的 .git 是目錄，先前會被當成工作樹，
  然後在 git worktree remove 那一步炸出一句原始錯誤。
- 兩支腳本的 --dry-run 請求預告收進 pr-threads 的 plannedRequests，並補上 pr-watch
  先前漏掉的那句說明（逐則 reaction 與逐個 review 的行內留言事前列不完）。預告與實際
  發出的請求分開寫，加一個端點就會有一邊忘了改。
- PR 讀不到 head 分支時給出 PULL_HEAD_MISSING，而不是拿空字串去推導一條路徑。

議題 #41

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 17:06:07 +08:00
jiantw83andClaude Opus 5 32edd65962 docs(sdlc-feat): 第三段收尾指向 pr-watch 與手動清理 
PR 開出去之後流程就斷在那裡，使用者不會知道有東西可以查現況、也不會知道工作樹會被
自動清掉。收尾補一步，把兩支腳本講給使用者聽，並明講「多久跑一次由他自己排」。

邊界同時擋住兩件事：agent 不自己反覆跑 pr-watch，也不因為它建議了 run-sdlc-fix 就
自己去跑 /sdlc-fix——流程只由使用者明確叫用。

議題 #41

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:59:30 +08:00
jiantw83andClaude Opus 5 d331bef1ed feat(pr-watch): 回報 PR 現況，並在它結束時清掉工作樹 
開發者要能隨時問一句「這個 PR 現在怎麼樣、我還有什麼要做」。回報 PR 狀態、還有幾則
留言沒處理、工作樹在哪、裡面有沒有沒提交的東西，以及固定列舉值的 suggestedAction
——用列舉值而不是一段文字，呼叫端才能程式化判斷。

一次性、無狀態：不做變化偵測。已處理的判定基準是 Gitea 上的 +1 與 resolve，那個狀態
不在本機記憶裡，所以一份現況快照就足以回答「還有沒有事要做」，不必跟上次比較，也就
不必留任何游標或狀態檔。不做常駐程序也不做 daemon，排程交給呼叫端。

只通知，不動手：偵測到未處理留言只給建議，不自動執行 /sdlc-fix——流程不該被模型自動
觸發，而 /sdlc-fix 要求「不確定時詢問使用者」，非互動模式下那個詢問無處可去。

四種狀態的處置不一致，所以表格驅動測：merged 與 closed 終止並清理；open 繼續監看；
draft 繼續監看且**不清理**——被退回草稿代表還要繼續改，這時候那棵工作樹更需要留著。

議題 #41

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:59:30 +08:00
jiantw83andClaude Opus 5 9e049580bb feat(worktree-remove): 手動清掉一棵工作樹，絕不 --force 
pr-watch 會在 PR 合併或關閉時自動清理，但永遠不會被合併也不會被關閉的 PR 沒有出口
——沒有這一支，那些工作樹只能靠使用者自己記得去刪。兩條路共用 lib 的 removeWorktree，
不互相開子行程：守門的規則只有一份，自動的那條與手動的這條不該長出兩種行為。

**絕不 --force。** 清理會被自動執行，而自動執行的東西只能做可逆的事：工作樹重建得回來，
被刪掉的未提交變更救不回來。所以有東西沒提交就中止並報出路徑與檔名。只移除工作樹，
本機分支與遠端分支都留著。

輸入是 owner/repo 與分支名而不是一條路徑：要刪哪一棵由「哪顆工作包」決定，
使用者不必自己去記 12 碼的雜湊目錄名。

順手修掉一個測試抓出來的解析錯誤：git status --porcelain 的第一行前導空白會被 runGit
的 trim 修掉，固定切前三個字元會讓已修改檔案的檔名少一個字（README.md 變成 EADME.md），
人照著訊息去找會找不到。改成認「狀態欄一到兩個字元 + 空白」。

議題 #41

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:59:30 +08:00
jiantw83andClaude Opus 5 43764f457e refactor(pr-comments): 三類留言的讀取收進 pr-threads 
pr-watch 要數「還有幾則沒處理」，數的是與 pr-comments 完全同一件事：三類留言分散在
三個端點，一般留言與總評看自己打的 +1、行內留言看有沒有被 resolve，而總評的 reaction
掛在它的 issue comment id 上。這套規則寫兩份，遲早會一邊認自己的 +1、另一邊認任何人的
——而那個差異要等到有留言被靜靜跳過才會被發現。

pr-comments 只留輸入輸出，行為不變。

議題 #41

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:59:30 +08:00
admin 86bdfd9007 Merge pull request 'feat/pr-comments-and-fix/main' (#47) from feat/pr-comments-and-fix/main into master 
Reviewed-on: #47
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-17 08:48:23 +00:00
jiantw83 a1bbd78cb4 test(sdlc-fix-assets): 新增 sdlc-fix 流程正本 
分類必改／建議、不確定時停下來問、最後那則摘要——這三件腳本擋不住，只有正本做得到。

標不了的那幾則要在摘要裡單獨點出來，否則 reviewer 掃 reaction 與 resolve 時會以為它們
被跳過了。留言指向的程式碼已被改掉時不要硬試，列進「無法處理」讓使用者自己回。
 2026-09-17 08:46:35 +00:00
jiantw83 6453c78fd1 feat(sdlc-fix): 新增 sdlc-fix 流程正本 
分類必改／建議、不確定時停下來問、最後那則摘要——這三件腳本擋不住，只有正本做得到。

標不了的那幾則要在摘要裡單獨點出來，否則 reviewer 掃 reaction 與 resolve 時會以為它們
被跳過了。留言指向的程式碼已被改掉時不要硬試，列進「無法處理」讓使用者自己回。
 2026-09-17 08:46:35 +00:00
jiantw83 8d9bcd65e3 test(pr-reply): 回覆一則 PR 留言並標記已處理 
「回在原本那一串底下」對三類是三件不同的事。行內留言沒有「回覆某一則」的端點，
把新留言指向同一個檔案與同一行，Gitea 才會把它排在原留言底下——位置是串的識別。位置不由
呼叫端給而是拿 id 查出來：手抄行號是這一段最容易錯的地方。回覆還帶上原留言的 commit_id，
否則 PR 之後又推了新 commit 時，同一個行號指的是別的程式碼。

標記排在回覆之後，回覆沒成功就不標記：沒回就標記等於謊稱處理過。

輸出三類同形：用不到的欄位填 null 而不是讓它消失，下游不必為了少一欄多寫一種分支。
 2026-09-17 08:46:34 +00:00
jiantw83 759b53adeb feat(pr-reply): 回覆一則 PR 留言並標記已處理 
「回在原本那一串底下」對三類是三件不同的事。行內留言沒有「回覆某一則」的端點，
把新留言指向同一個檔案與同一行，Gitea 才會把它排在原留言底下——位置是串的識別。位置不由
呼叫端給而是拿 id 查出來：手抄行號是這一段最容易錯的地方。回覆還帶上原留言的 commit_id，
否則 PR 之後又推了新 commit 時，同一個行號指的是別的程式碼。

標記排在回覆之後，回覆沒成功就不標記：沒回就標記等於謊稱處理過。

輸出三類同形：用不到的欄位填 null 而不是讓它消失，下游不必為了少一欄多寫一種分支。
 2026-09-17 08:46:34 +00:00
jiantw83 de1fd08efa test(pr-comments): 讀 PR 上的三類留言 
一般留言、review 總評、行內留言分散在三個端點，漏掉任何一類就會有意見沒被處理——
而那正是 /sdlc-fix 存在的理由。只讀不寫，必改／建議的分類由讀到內容的人判斷。

三類的「已處理」機制不同：一般留言與總評看自己打的 +1，行內留言看有沒有被 resolve。
總評的 reaction 掛在它在 issue comment 表裡那一份的 id 上，由 timeline 對應得出來；
拿 review 自己的 id 去打會 404，兩個 id 不同命名空間。

reaction 要是自己打的才算已處理：reviewer 對留言按讚是「我同意」，不是「這則處理過了」，
當成已處理會讓那一則被靜靜跳過。

行內留言的位置分兩側：新檔那側在 position，被刪掉的那行在 original_position，Gitea 只填
其中一個。輸出把兩者收斂成「行」與「側」，回覆時才知道該送哪個欄位。也帶出 commit，
讓回覆落在原留言的那個 commit 上。

三種清單都逐頁讀完：這個站台的預設頁大小是 30，沒分頁的話第 31 個 review 之後整批消失。
 2026-09-17 08:46:33 +00:00
jiantw83 cc29b5bc21 feat(pr-comments): 讀 PR 上的三類留言 
一般留言、review 總評、行內留言分散在三個端點，漏掉任何一類就會有意見沒被處理——
而那正是 /sdlc-fix 存在的理由。只讀不寫，必改／建議的分類由讀到內容的人判斷。

三類的「已處理」機制不同：一般留言與總評看自己打的 +1，行內留言看有沒有被 resolve。
總評的 reaction 掛在它在 issue comment 表裡那一份的 id 上，由 timeline 對應得出來；
拿 review 自己的 id 去打會 404，兩個 id 不同命名空間。

reaction 要是自己打的才算已處理：reviewer 對留言按讚是「我同意」，不是「這則處理過了」，
當成已處理會讓那一則被靜靜跳過。

行內留言的位置分兩側：新檔那側在 position，被刪掉的那行在 original_position，Gitea 只填
其中一個。輸出把兩者收斂成「行」與「側」，回覆時才知道該送哪個欄位。也帶出 commit，
讓回覆落在原留言的那個 commit 上。

三種清單都逐頁讀完：這個站台的預設頁大小是 30，沒分頁的話第 31 個 review 之後整批消失。
 2026-09-17 08:46:33 +00:00
admin 3084c91041 Merge pull request '以 worktree 建立工作包分支並備妥隔離環境' (#46) from feat/worktree-branch-prep/main into master 
Reviewed-on: #46
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-17 08:31:54 +00:00
jiantw83andClaude Opus 5 d3ce364727 docs(sdlc-feat): description 跟著改成「備妥工作樹、起錶」 
轉接檔的一行說明是從這裡取的，順序寫錯會讓人以為錶還是在領取那一步起。

議題 #40

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:30:00 +08:00
jiantw83andClaude Opus 5 0154cf59d4 fix(claim): 被碼錶擋下時明說停錶不會動到既有的工作樹 
議題 #38 的使用者故事第 30 條：使用者常以為停錶等於放棄那顆工作包，於是寧可
不停——工時就記到別顆議題去了。碼錶只管時間、工作樹只管檔案，兩者互不相干，
這件事要在擋下來的當下就講，不能指望使用者自己推論。

領取與起錶會撞到同一個擋路理由，訊息收進 lib 只寫一份。順手收掉 review 指出的
三處：planWorktree 沒用到的 repo 參數、與 path.resolve 同名而誤導的區域函式、
以及只有 lib 自己用得到卻對外 export 的兩支路徑函式。

回滾補上最後一道：git 清不掉時把目錄本身也刪掉。那條路徑在這次執行之前不存在
（不存在正是建立的前提），裡面不可能有使用者的東西，而留著它下一次重跑會直接
撞上 WORKTREE_PATH_TAKEN——一次失敗的建立不該讓人從此開不了工。

議題 #40

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:29:12 +08:00
jiantw83andClaude Opus 5 4583a5f210 docs(sdlc-feat): 第一段改成領取、備妥工作樹、最後起錶 
正本跟著實作走：分支那一步改成工作樹，新增起錶那一步排在它後面，
並把三處「不要自己決定」寫明——來源分支不存在時不自己換一支、路徑被佔住時
不自己刪、工作樹建不起來時不退回原地切分支。工作區不乾淨的處置整段拿掉：
工作樹本來就是為了讓未提交的變更不再擋路。

AGENTS.md 補上兩條邊界。git worktree add 一定會在目標 repo 的 .git/worktrees/
底下寫中繼資料，這是 git 的機制，無法避免——「不改目標專案」指的是專案的內容檔，
把這件事明說，免得下一個人以為實作違規。

議題 #40

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:29:12 +08:00
jiantw83andClaude Opus 5 74b4ca130e feat(timer): 碼錶移出領取，等工作樹建成之後才起 
原本的順序是「放行 → 設 assignee 與標籤 → 起錶 → 處理分支」，而工作樹建立
失敗會中止整個領取——錶已經起了才失敗，使用者會被計一段什麼都沒做的時間，
而工時要準正是工時報表的立足點。

claim 只留領取鎖的兩件事（assignee 與標籤），起錶交給新的 timer.js，由流程
正本排在 branch-prep 之後。timer 已經跑在這顆議題上時什麼都不做：中斷後重跑
是它最常見的處境，重新起錶會把已經累積的時間切成兩段；跑在別顆上則照舊擋下，
不代勞停錶。

三支腳本讀碼錶的那段各留一份，趁這次收進 lib。

議題 #40

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:27:43 +08:00
jiantw83andClaude Opus 5 5b740c236b feat(branch-prep): 一律在獨立的工作樹上開工，不在原地切換分支 
同一份 clone 上同時持有多顆工作包時，原地切分支有三種損耗，一種比一種難查：
未提交的變更擋路、建置產物跨分支混淆，以及 agent 讀到不屬於它那顆工作包的
程式碼——agent 是非同步的，它可能在分支已經被切走之後才去讀檔，而且不會察覺，
產出看起來完全合理，只是接錯了上下文。前兩種人會當場發現，第三種不會，
所以工作樹一律建立，不是「有衝突才用」。

建不起來就中止，不退回原地切分支：靜默降級會讓使用者以為自己在隔離環境裡，
其實在原地改。

分支與工作樹合併為一個原子動作（fetch 後一次 worktree add），並補上回滾——
git 在 worktree add 失敗時仍會把分支留下來，那是最難查的半成品：下一次重跑
會走到「目標分支已存在」那條路，起點從此不再是遠端的來源分支。

起點一律取自 origin/{來源分支}，遠端沒有就中止，不退回本機同名分支；
本機分支可能落後好幾天，而這件事從輸出上完全看不出來。原「來源分支在遠端
已存在時 pull 而非重建」那條，用更強的方式達成同一個目的：根本不碰本機分支，
就沒有覆蓋他人進度的可能。

不設 upstream：此刻遠端還沒有這個新分支，--track 會把 upstream 指到來源分支，
之後 git pull 會把來源分支的提交拉進來。留給第一次 push -u 自然建立。

路徑由 owner/repo/分支名 正規化後取雜湊推導（lib 的 worktreePath），不查表、
不寫狀態檔，換機器算出來一樣。取雜湊而不是把斜線攤平成 -，是因為攤平會讓
feat/a-b/main 與 feat/a/b/main 撞成同一個目錄，而現行的分支命名規則恰好讓
這種形狀有機會出現。

議題 #40

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 16:27:43 +08:00
admin 03c368b6de Merge pull request 'feat/commit-split-and-pr/main' (#45) from feat/commit-split-and-pr/main into master 
Reviewed-on: #45
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-17 08:25:36 +00:00
jiantw83 997d4ec280 docs(sdlc-feat): 第三段補上兩個 repo 的區別與重跑的行為 
說明 --repo 與 --issue-repo 的差別、--base 要明講不讓腳本猜、重跑不會開出第二顆 PR，
以及提交中途失敗時不要自己回捲歷史。
 2026-09-17 08:23:28 +00:00
jiantw83 013947630f test(sdlc-feat-assets): 第三段補上兩個 repo 的區別與重跑的行為 
說明 --repo 與 --issue-repo 的差別、--base 要明講不讓腳本猜、重跑不會開出第二顆 PR，
以及提交中途失敗時不要自己回捲歷史。
 2026-09-17 08:23:28 +00:00
jiantw83 da5b670f29 test(script-contract): 讓 --key=value 的值可以本身以 -- 開頭 
commit 訊息與 PR 描述裡出現 --flag 是常態，而原本的檢查對兩種寫法一視同仁：值只要以
-- 開頭就報「需要一個值」。空格分隔的寫法確實分不出「值」與「打錯的 flag」，但等號寫法
沒有這個歧義，不該一起擋掉。

這是實際撞到的：拿 commit-split 提交它自己時，--body 的內容第一行就是「--repo 與
--issue-repo 的差別」，整個 commit 因此做不出來。空格寫法的錯誤訊息現在會指路到等號寫法。
 2026-09-17 08:23:27 +00:00
jiantw83 1c6e7f85bb fix(lib): 讓 --key=value 的值可以本身以 -- 開頭 
commit 訊息與 PR 描述裡出現 --flag 是常態，而原本的檢查對兩種寫法一視同仁：值只要以
-- 開頭就報「需要一個值」。空格分隔的寫法確實分不出「值」與「打錯的 flag」，但等號寫法
沒有這個歧義，不該一起擋掉。

這是實際撞到的：拿 commit-split 提交它自己時，--body 的內容第一行就是「--repo 與
--issue-repo 的差別」，整個 commit 因此做不出來。空格寫法的錯誤訊息現在會指路到等號寫法。
 2026-09-17 08:23:27 +00:00
jiantw83 95e6026950 refactor(lib): 開啟目標專案 git repo 的那幾行收進 lib 
「路徑不是 repo 就報 NOT_A_GIT_REPO」加上「把 cwd 綁進 runGit」原本在 branch-prep 與
commit-split 各寫一份。錯誤碼要一致，而這件事寫第三遍就該收起來了。
 2026-09-17 08:23:26 +00:00
jiantw83 fbc80f286f test(pr-create): 錶停在議題的 repo，並讓重跑不會開出第二顆 PR 
claim 在工作包議題上起錶，而 PR 開在目標專案上——議題在需求的 repo，程式碼在 repos 列的
那幾個，兩者常常不是同一個。先前用同一個 --repo 同時指 PR 與停錶，停到的會是別人的議題
（或 404 而在 PR 已建立之後才拋錯），而自己的錶還在跑。新增 --issue-repo，預設與 --repo 相同。

--index 與 --base 改為必填：停錶是這一步的一部分，忘了給會讓工時算不準；而目標專案的開發
分支可能叫 master、main 或 develop，猜錯會開到不存在的 base。

重跑先查同一個 head 有沒有開著的 PR，有就回傳它並把 created 設為 false，然後照樣停錶——
那一步可能正是上次中斷的地方。先前重跑會撞上 Gitea 的 422，而那個錯誤看不出 PR 其實已經開好。

停錶的 500 改為只在訊息確實提到 stopwatch 時才視為「本來就沒在跑」，免得把真的伺服器錯誤
吞掉；未經證實的 409 那一支拿掉。測試結果的空話檢查改成整段每一行都是空話才擋，段落也改用
行首標題切，描述裡引用到「## 測試結果」這幾個字不會再讓檢查看錯地方。
 2026-09-17 08:23:25 +00:00