plugins/tea-sdlc
2
0
Fork 0
Code Issues 3 Pull Requests Actions Releases Activity
167 Commits 1 Branch 0 Tags
db138446227bc91ded1d238754079a9b15e94758
Commit Graph
167 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
jiantw83 db13844622 chore: bump version to 0.0.2 2026-09-21 17:44:57 +08:00
jiantw83 7f723adff8 feat: 移除計時並停用報表預覽 2026-09-21 17:41:44 +08:00
jiantw83 5a259a95af feat(install): validate agent CLI runtime registries 2026-09-18 16:42:09 +08:00
jiantw83 867a23497f feat(overview-artifact): 產生可預覽總覽與截圖 fallback 2026-09-18 15:59:34 +08:00
admin c545f11ec1 Merge pull request 'feat/delegation-markers/main' (#64) from feat/delegation-markers/main into master 
Reviewed-on: #64
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-18 01:19:38 +00:00
jiantw83andClaude Opus 5 f61ef3fa78 test(delegation): 把標記與判準正本雙向綁住 
沒有這條斷言，兩邊會慢慢漂開，而漂開時不會有任何東西報錯：正本上多標一步不會壞，
判準表少列一項也不會壞，只是下一個讀的人會以為自己讀到的是全部。

十三條，重點在三處：正本上被標記的集合等於判準表列出的集合；會問使用者的步驟一律
未被標記（判準第二條的迴歸保護，四個點名的步驟加上一次全域掃描）；被標記的步驟碰得到
寫入時要寫明哪一半不委派（第四條）。

掃描類的斷言都補上自我檢查，因為這種測試最常見的壞法是「一條都沒掃到」而它照樣是綠的：
提問語至少要認出四個步驟、至少要掃過四十個步驟。標記位置那一條原本把三種合法位置寫成
`/^#{2,3} /`，那條會把「### 沒編號的標題 〔可委派〕」也放過去，改成三條互斥的規則。

helpers 新增 promptSteps（名字、有沒有標記、內文），promptStep 改建在它上面，
順帶讓步驟標題容得下後綴。

議題 #58

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-18 09:12:08 +08:00
jiantw83andClaude Opus 5 84cd8fc41f docs(prompts): 六個只在意結果的步驟標上〔可委派〕 
三份正本各加一節說明這個後綴是什麼意思，只留能力描述那一句與指回判準正本的指路，
判準本身不複寫——抄過去就會有兩份各自演化的規則（AGENTS.md 的 references/ 那一列）。

標的是六個：sdlc-plan 的產生圖解版總覽；sdlc-analyze 的對四份清單列出疑點、算出截止日、
產生分析版的圖解總覽；sdlc-feat 的把議題標題翻成英文、分批提交。

其中三步是部分委派，各自在該步寫明哪一半留給主流程：兩份圖解總覽委派的是產出 HTML，
寫回議題的 issue-update 不委派；分批提交委派的是方案計算，實際跑 commit-split.js 不委派。
理由不在這裡複述，指回判準第四條。

**「認出語言，讀規則正本」不標**，儘管議題的列舉點了它。那一步的核心動作含「認不出語言
就停下來問、不要猜」，正是判準第二條硬排除的事；排掉它之後剛好是議題所寫的六個。
這一條與 repo 擁有者確認過。

AGENTS.md 的 references/ 那一列補上「委派判準」，否則那串括號裡的列舉會漏掉新的一份。

議題 #58

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-18 09:12:08 +08:00
jiantw83andClaude Opus 5 3da822adc6 docs(references): 新增委派判準，四條全部成立才可委派 
只在意結果的步驟——翻譯分支名、算截止日、逐條比對可行性清單、產生 HTML 總覽——
它們的中間產物目前全部留在主脈絡裡，把後面真正需要判斷力的步驟愈擠愈窄。要把這些
交出去，得先說清楚「哪些交得出去」，否則下一個人只能憑感覺標。

四條判準裡有兩條是硬排除，各自寫上理由，因為沒有理由的規則遲早會被繞過去：
第二條（步驟中不會詢問使用者）是因為子代理問不到使用者，一旦卡在提問就只能自行決定；
第四條（不直接寫入 Gitea 或 git）不是因為子代理做不好，而是**它的失敗沒有人看著**
——備妥工作樹失敗會中止整個領取、實際提交失敗會留下半套 git 歷史。

委派一律以**能力描述**表達，不指名任何平台的工具：子代理是平台專屬能力，而流程正本
必須保持平台中立（#4 的驗收標準）。能力描述對不支援的平台是自然降級，同一份正本兩邊
都讀得通，不必維護兩份。這份正本明寫「不要把它改寫成工具名」，因為那是讀到它的人
最可能動手改的地方。

那張「目前標記為〔可委派〕的步驟」表與正本上的標記互為正本，由資產測試雙向綁住。

議題 #58

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-18 09:12:08 +08:00
admin 7995e74332 Merge pull request 'feat/plan-analyze-timing/main' (#63) from feat/plan-analyze-timing/main into master 
Reviewed-on: #63
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-18 00:52:27 +00:00
admin ad980fafc6 Merge pull request 'feat/install-verify/main' (#62) from feat/install-verify/main into master 
Reviewed-on: #62
 2026-09-18 00:52:13 +00:00
admin c06c327104 Merge pull request 'feat/sdlc-fix-accepts-issue/main' (#61) from feat/sdlc-fix-accepts-issue/main into master 
Reviewed-on: #61
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-18 00:52:00 +00:00
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
JefferyandClaude Opus 5 73b9cd9f75 feat(install): 安裝完成等於驗過能用 
install 寫完轉接檔後，把叫用鏈真的走一遍：轉接檔 → PATH 上的 tea-sdlc → 流程正本。

最脆弱的是中間那一環。套件裝在某個 Node 版本底下，換個版本就找不到了，而轉接檔本身
看起來完全正常——沒有這道驗證，使用者要到第一次打 /sdlc-plan 才發現，那時他已經離開
安裝的心智狀態很久了。所以不是查檔案在不在，而是真的到 PATH 上把 tea-sdlc 找出來執行
一次，再把取回的正本跟套件裡的那一份逐字比對：找不到、叫不動、或叫到的是另一份安裝，
三種都驗得出來。轉接檔則逐一回磁碟讀，比對存在且內容含正確的叫用行。

驗證不碰網路，也與 Gitea 登入、時間追蹤無關，所以無條件執行。

驗不過回 ok:false，但已經寫好的轉接檔一份都不刪。回滾在升級情境下是淨損失：原本有一組
能用的舊轉接檔，覆蓋後驗證失敗再刪掉，使用者就從「有點舊但能用」變成什麼都沒有；何況
最可能的病灶是「PATH 上找不到 tea-sdlc」，那不是轉接檔的問題。

為此 lib 多一個 Failure：有一種失敗是事情做完了、檔案也寫出去了，只是驗不過，那時最該
交出去的正是「已經寫了哪些、哪一段不通」。envelope 形狀不變，只是 {ok:false, error}
旁邊多一個 data，只讀 error.code 的呼叫端照常運作。

--dry-run 不寫入，也就沒有東西可驗，verify 標成 skipped。

Closes #59

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 18:25:32 +08:00
jiantw83andClaude Opus 5 a279591232 fix(sdlc-fix): 需求議題本來就沒有未整併留言時照樣列出工作包 
原本只寫「未處理數大於 0 就先整併」，零則的入口從沒明寫，讀起來會變成
「沒有留言要處理就到此為止」，正好與「無未整併留言時要列出工作包」相反。
另把交棒的另一端補在 sdlc-feat 的輸入上——機制只有一邊寫得出來，
另一邊就只是散文承諾。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 18:21:36 +08:00
jiantw83andClaude Opus 5 03ce382220 refactor(issue-body): 工作包的歸屬判準收成一個函式 
wp-extract 與 wp-list 都在問「這顆工作包掛在哪顆需求底下」。規則寫兩份，
某天只會有一邊被改到，而分岔的樣子是「清單裡看得到、抽取卻說不是」。
順手把測試裡兩種取段落的寫法統一，並刪掉沒有人傳過的參數。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 18:19:33 +08:00
jiantw83andClaude Opus 5 a5f36ed14c feat(sdlc-fix): 輸入放寬為 PR 編號或議題編號 
議題不自己重做一遍實作流程，而是交棒給 /sdlc-feat：工作包議題直接交棒，
需求議題先讓 /sdlc-sync 整併決策留言，剩下確實要改碼的才列出底下的工作包
讓使用者挑一顆。交棒複用 sdlc-sync 已經定好的接回機制，使用者不必重打指令。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 18:16:23 +08:00
jiantw83andClaude Opus 5 09d880e6f2 feat(wp-list): 列出一顆需求議題底下的工作包 
歸屬判準沿用工作包抽取那一套（關聯段落的「需求議題：#N」），不另發明一套；
PR 的描述也有那一行，所以先擋掉 PR。清單逐頁讀完，讀不完寧可報錯——
使用者會從缺了幾顆的清單裡挑，而且看不出缺的是哪幾顆。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 18:16:23 +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