plugins/tea-sdlc
2
0
Fork 0
Code Issues 3 Pull Requests Actions Releases Activity
89 Commits 1 Branch 0 Tags
ba714b0a008305eff3d6fa739bdbc60b81f8a328
Commit Graph
34 Commits
Author SHA1 Message Date
jiantw83andClaude Opus 5 ba714b0a00 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 15:54:27 +08:00
jiantw83andClaude Opus 5 feaf40ab78 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 15:54:27 +08:00
jiantw83andClaude Opus 5 865561c63b 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 15:54:27 +08:00
jiantw83andClaude Opus 5 67528dde5f fix(README): 安裝指令補上 git+ 前綴，否則 npm 會把它當壓縮檔 
npm 只有看到 git/git+ssh/git+http/git+https/git+file 才會當成 git repo。
寫成 https://….git 會被歸類成遠端 tarball，下載回來解壓失敗，錯誤是
TAR_BAD_ARCHIVE: Unrecognized archive format——看起來完全不像「網址寫法錯了」，
使用者只會以為套件壞了。

先前那條「README 指令逐字執行得動」的測試沒抓到，因為它只跑 tea-sdlc 開頭的
行，npm 那行從來沒被執行過。補一條規則把 .git 網址必須帶 git+ 前綴釘住：
真的去跑一次 npm 全域安裝要開網路、要三秒，不適合放進這套向來密封的測試裡，
但「前綴在不在」這條規則本身就足以擋掉這個錯。

議題 #25

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 15:30:27 +08:00
jiantw83andClaude Opus 5 cbf4c3df36 docs(README): 前置需求分開講安裝與跑流程，並把指令是否真的跑得動釘住 
前置需求表原本一句「缺少時腳本印出指引並中止」套在所有需求上，但 install 只
警告不中止——文件描述的是一個不存在的行為。改成逐項寫「缺了會怎樣」，並把
「安裝只需要 Node」提到表前面：使用者不該為了裝 plugin 先去裝 tea。

另外補上三條把 #30 驗收標準真的驗起來的測試。其中一條把 README bash 區塊裡的
tea-sdlc 指令逐行拿去真的執行（家目錄指向空的暫存，所以一個檔都不會寫），
失敗理由若是「這個指令／參數我不認得」就算 README 寫錯——這比用眼睛核對可靠。

議題 #30

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 07:11:18 +00:00
jiantw83andClaude Opus 5 002511ce45 test(sdlc-feat): 覆蓋領取鎖決策表、分支命名規則與三處不覆蓋他人進度 
領取鎖的四種狀態各一例，而且每一種擋的情況都驗「一個字都沒寫進 Gitea」——擋下來卻已經
改了一半，比直接放行更難收拾。

分支命名是純字串規則，表格驅動：開發分支三種寫法、功能分支兩層，加上中文、超長、大寫、
底線與連續連字號的輸入驗證。

git 的部分在臨時 repo 上跑真的 git，釘住三件事後來由 code review 抓出來的實際缺陷：
遠端分支的比對必須用全名（否則 feat/x/main 會冒名頂替 main）、工作區不乾淨要在動手前
就擋、來源分支與遠端分歧要回可區分的錯誤碼而不是 git 的原始訊息。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 07:07:02 +00:00
jiantw83andClaude Opus 5 e1897f2d33 test(helpers): 加上「有遠端」的臨時 repo，並收掉三份重複的 git 執行器 
branch-prep 的重點行為都繞著遠端打轉——來源分支在遠端已存在時要 pull 而不是重建、
目標分支已存在時不能覆蓋他人進度。這些事沒有遠端就驗不出來，所以補一個 bare origin
加工作用 clone，並附 pushFromElsewhere 模擬「別人推了東西上去」。

順手把 makeTempRepo 與新 helper 各自重寫一次的 git 執行器與 seed 收成共用的兩支。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 07:07:01 +00:00
jiantw83andClaude Opus 5 17178f0c4d feat(佈署): 以 npm 裝出 tea-sdlc 指令並產生各平台轉接檔 
單一入口 bin/tea-sdlc.js 認四個子指令。第一個位置參數是子指令，其餘 argv 原樣
交出去——既有的 flag 解析拒絕位置參數，所以子指令必須在那之前就被取走。

轉接檔裡沒有路徑，只有一句 tea-sdlc prompt --name <指令名>。正本在哪由 PATH 上
的 tea-sdlc 自己回推：fnm 把 Node 版號寫進全域安裝路徑，寫死路徑的話升一次
Node，七個平台的轉接檔會同時指向不存在的檔案，而且不會有任何錯誤訊息。

prompt 是全專案唯一輸出非 JSON 的路徑，理由只有一個：它的輸出要餵給模型讀。
失敗仍走 envelope——成功是內容，失敗才需要結構。

status 的 ok 不兼差表達環境好壞，健康與否放在 data.healthy：呼叫端要分得出
「status 掛了」與「status 成功查到你環境有問題」。

install 只寫進偵測得到的平台；缺 git／tea 只警告不中止，因為那兩個完全不影響
轉接檔產生，硬擋等於逼使用者為了裝 plugin 先去裝 tea。uninstall 只刪帶產生標記
的檔案，使用者自己寫的同名檔案一律留著並在輸出裡交代。裝哪些指令以 prompts/ 裡
實際存在的正本為準，不是寫死的六個名字——裝出指向不存在正本的轉接檔，使用者只會
看到 PROMPT_NOT_FOUND。

流程正本的 description 前綴在抄進轉接檔之前就檢查：有三個平台關不掉自動觸發，
全靠那句話把 description 窄到不會被誤判，不能等使用者發現誤觸才知道漏了。

議題 #26 #27 #28 #29 #17

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:59:37 +00:00
jiantw83andClaude Opus 5 b56216e0f0 test(工時報表): 釘住週次歸屬的跨月、跨年與五個週五 
時區在測試裡固定為 Asia/Taipei：週界是以人在的時區切的，不釘住時區就等於沒釘住答案。
--today 讓「本週」在 CLI 接縫上釘得住，否則預設期間會跟著系統時鐘漂走。

寫入請求那則斷言誠實列出唯一的非 GET——四層前置檢查的寫入權探針，
而不是先把它濾掉再宣稱整趟沒有寫入。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:50:35 +00:00
jiantw83andClaude Opus 5 74930b0571 test(wp-extract): 覆蓋契約欄位、模板變體、活狀態與 CRLF 
解析是整條鏈的上游，解析錯則下游全錯，所以模板變體餵得雜一些：缺段落、巢狀驗收為空、
checkbox 已勾、中英混排、圍欄裡的假待辦、只寫一格的表格列。

另外釘住三件容易在日後鬆掉的事：
- `raw` 逐行出現在原始 body 裡，包括 CRLF 的 body 連行尾的 \r 都留著，否則下游替換
  時對不上原文。
- 相依與留言都逐頁讀完，不是只讀第一頁。
- --dry-run 預告的請求順序與實跑一致，且完全不碰 Gitea。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:30:24 +00:00
jiantw83andClaude Opus 5 a460d7e661 test(總覽網頁): 把三條驗不出東西的斷言改成驗得出來的 
- mermaid 那條原本只比對「有出現 mermaid 字樣」，而 CDN 網址裡就有這個字，
  整段渲染腳本刪掉也照樣通過。改成驗 mermaid.initialize 真的被呼叫。
- 新增一條守住例外的範圍：模板裡只能有那一段腳本，且不得夾帶網路或儲存操作。
- sdlc-plan 的七條斷言原本拿整份正本比對，任何一處撞到就算過。改成只看第 6 步，
  與 sdlc-analyze 那邊的做法一致。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:22:31 +00:00
jiantw83andClaude Opus 5 0aa0439061 test(總覽網頁): 釘住模板結構與兩份正本的規則 
模板的檢查重點是「樣式與內容分離」與「全景段落能整段消失」，兩者壞掉時規劃版會
留下空標題或行內樣式散落各處，肉眼不容易發現。

順帶把 work-package 測試的 phase2 切法收斂到第三段之前——原本切到檔尾，第三段
新增的編號清單會混進段落順序的斷言裡。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:22:29 +00:00
jiantw83andClaude Opus 5 47529d33c2 test(issue-update): 覆蓋總覽網址的寫回與就地更新 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:22:29 +00:00
jiantw83andClaude Opus 5 97d0afac38 test(project-add): 把「不建立專案」改成驗得出東西的斷言 
原本的條件是「沒有非 GET 請求打到路徑含 project 的端點」，但 Gitea 的專案根本
沒有 API 路徑，這個條件恆真，壞掉的實作也會通過。改成斷言真正的寫入只有議題本身
那一次 PATCH、而且只帶 projects 欄位。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:12 +00:00
jiantw83andClaude Opus 5 15da38a460 test(issue-update): 封住估算那一行的三種污染 
三條測試都先確認過會在舊版實作上失敗。第一版寫出來時有兩條其實是陪跑的——
情境裡沒有後續段落，正確與錯誤的結果剛好都落在 body 結尾，分不出來。加上一個
真正的後續段落之後才有鑑別力。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:11 +00:00
jiantw83andClaude Opus 5 b09746a309 test(排程): 覆蓋重複 index 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:11 +00:00
jiantw83andClaude Opus 5 257642cb1c test(sdlc-analyze): 釘住第三段的腳本順序與已知限制那一節 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:08 +00:00
jiantw83andClaude Opus 5 5327f5882e test(project-add): 覆蓋反查、貼網址、既有看板不被覆蓋 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:07 +00:00
jiantw83andClaude Opus 5 3f97fe0901 test(issue-update): 覆蓋 Milestone 解析、日期格式與估算的就地更新 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:06 +00:00
jiantw83andClaude Opus 5 b45437e527 test(issue-link): 覆蓋兩種相依、冪等與自我相依 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:05 +00:00
jiantw83andClaude Opus 5 be477a4391 test(排程): 覆蓋拓撲順序、多重先決與成環 
除了逐例比對日期，另有一條測試直接驗「所有先決關係都滿足」這個不變式，
而不是只比對硬編的日期字串——不變式壞掉時它會指出是哪一對。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 06:06:04 +00:00
jiantw83andClaude Opus 5 6457d68874 refactor(測試): 模板結構的三項檢查抽到共用斷言 
段落順序、正本的編號清單、圖表段落不寫死圍欄——這三件事需求議題與工作包議題
都要驗，第二份模板出現時就該抽出來。兩份測試原本各抄一份，其中佔位數的斷言
還悄悄長成不同寫法（一邊 >=、一邊 ==）；抽出來之後這種分歧會被逼著講清楚。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:43:26 +00:00
jiantw83andClaude Opus 5 f0beb1ff64 test(工作包): 釘住模板與「產生工作包」那一段的規則 
模板的段落順序決定 wp-extract 解析得到什麼，待辦的巢狀寫法決定實作階段勾得到
哪一行——這兩件事寫死在測試裡，改動時才會被逼著一起改。

巢狀範例的斷言不比對固定縮排量，而是比對「最深的一層比最淺的深」，這樣重排
外層清單的縮排不會弄壞測試。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:43:25 +00:00
jiantw83andClaude Opus 5 0cd25d49d4 feat(sdlc-analyze): 擴充為兩段式，第二段把共識變成工作包議題 
第一段到共識摘要為止仍然完全不寫入；使用者點頭之後才進入第二段建立議題。
邊界條文隨之改寫成「共識摘要之前不對 Gitea 產生任何寫入」，並明列第二段
不做的事：不建相依、不掛 Milestone、不加看板、不寫人天估算——那些是後續
流程的工作，寫在這裡會讓兩顆工作包互相踩。

工作包的切法、標題規則（動詞加名詞、禁止 WP-01 這類流水編號）、待辦與驗收
的巢狀寫法（附可照抄的範例）、架構圖依性質三選一，都在這一段定下來。

邊界的斷言跟著條文一起改，因為條文換了語意；分開成兩顆 commit 的話中間那顆
會是紅的。另補一條斷言：第一段不得出現任何寫入型腳本的名字。

Closes #7

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:43:24 +00:00
jiantw83andClaude Opus 5 8a405de189 test(sdlc-analyze): 覆蓋時程清單的估算前提 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:11:07 +00:00
jiantw83andClaude Opus 5 2b06dfd663 test(sdlc-analyze): 釘住四份清單與正本的結構 
這一顆沒有腳本，交付的就是文件本身，所以驗的是文件的結構：四份清單各有足夠
的檢查項與提問指引、正本逐一指名它們且順序為架構→邏輯→資料→時程、一次一題、
兩個固定選項、共識摘要只印不寫，以及「不對 Gitea 寫入」有被寫成明確邊界。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:11:06 +00:00
jiantw83andClaude Opus 5 930270f545 refactor(測試): 正本的共用檢查抽到 helpers 
description 前綴、沒有 frontmatter、不出現平台專屬字樣——這三件事每一份流程
正本都要驗，第二份正本出現時就該抽出來，而不是再抄一次。順帶把讀正本、讀規則
正本、讀模板三個路徑組合也收在同一處。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:11:06 +00:00
jiantw83andClaude Opus 5 06de8980ca test(issue-extract): 封住圍欄、表格與分頁的回頭路 
八條新案例，每一條都對應一個實際重現過的缺陷：~~~ 圍欄、圍欄內的假清單項、
混用圍欄標記、未閉合圍欄的歸屬、逸脫的直線、第二條分隔列、巢狀攤平，以及
留言分頁。

把修正還原成舊版解析器後，這批測試有五條會失敗；修正回來則全綠——確認測試
真的抓得到，不是陪跑。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:00:29 +00:00
jiantw83andClaude Opus 5 fd80d9772a test(issue-extract): 以模板變體覆蓋抽取契約 
解析是整條鏈的上游，解析錯則下游全錯，所以模板變體餵得比別處雜：缺段落、
段落在但列表是空的、checkbox 已勾與未勾、中英混排、編號清單、名詞表只有
表頭、body 全空、出現契約外的段落。

留言的部分驗兩件事：未整併則數只算沒有 +1 的，以及留言內容一個字都不得出現
在輸出裡——後者用整份 stdout 做子字串比對，比逐欄檢查更難繞過。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 05:00:27 +00:00
jiantw83andClaude Opus 5 9b9ab33a53 test(issue-create): 覆蓋建立議題與試跑預覽的契約 
沿用既有接縫：子行程執行、stub server 錄下每一筆請求。涵蓋標籤名稱解析、
未知標籤中止、不碰 labels 的寫入端點、同標題不重建、前後空白視為同一顆，
以及寫入型腳本一樣跑滿前置檢查。

試跑的部分特別驗「預覽要忠實」：預覽的 body 必須看得出標籤會被貼上、標籤
錯字在試跑就該擋下、同名議題已存在時預覽不得預告要建立議題，且全程不發出
任何寫入請求。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 04:44:47 +00:00
jiantw83andClaude Opus 5 9e57a5db99 test(sdlc-plan): 釘住正本與模板的結構 
正本與模板是檔案而非程式，卻是本工作包實際交付的東西：模板段落順序決定下游
解析得到什麼，正本的平台中立性決定轉接檔能不能一份寫到底。以測試釘住段落
順序、佔位格式、description 前綴、平台專屬字樣的缺席、流程圖的上限，以及
模板不得寫死 mermaid 圍欄。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 04:44:47 +00:00
jiantw83andClaude Opus 5 b0bd061852 refactor(測試): 共用假 Gitea 的啟動與環境變數 
每支測試各自寫一次「啟動 stub、登記 close、組環境變數」已經重複三次，抽到
helpers 之後新增測試檔只要一行。各檔仍保留自己的預設路由，因為那是該檔的
情境設定，不該共用。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 04:44:45 +00:00
jiantw83andClaude Opus 5 4ae097f1e1 fix(腳本契約): 長輸出不再被截斷，查重翻頁加上上限 
process.stdout.write 之後立刻 process.exit 會截斷輸出——stdout 接到 pipe 時
寫入是非同步的。改為等 write 的 callback 回來再退出。實測舊寫法在約 83KB 處
被切斷，新增的回歸測試以 8000 筆標籤覆蓋這條路徑。

findIssueByTitle 的翻頁原本沒有上限，Gitea 若持續回滿一頁就會無限打下去。
加上 200 頁上限，超過即以 DEDUPE_LIMIT 報錯而非無聲回 null——無聲回 null 會
讓呼叫端把既有議題再建一次，正好是冪等查重要防的事。

parseFlags 取值時不再於三元運算式內遞增迴圈變數，改為獨立敘述。

測試工具的 maxBuffer 調高到 64MB：預設 1MB 會在長輸出時砍掉子行程，那是測試
工具的限制而非腳本的問題。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 04:26:51 +00:00
jiantw83andClaude Opus 5 28dec83498 test(腳本契約): 以子行程與 stub server 驗證契約與四層前置檢查 
測試一律以子行程執行腳本、比對 stdout 的單行 JSON 與 exit code，因為那正是
七個平台共用的實際呼叫方式，不會因內部重構而破碎。

Gitea 以本機 stub server 替身並錄下每一筆請求，藉此斷言「腳本到底發了哪些
請求」——包含 --dry-run 不得發出任何請求、前一層檢查沒過就不再往下打、
寫入權探針不得挾帶任何要寫入的欄位。git 則在 .tmp/ 下的臨時 repo 跑真實
指令，比 mock 可信且成本低。

lib-exports.test.js 是唯一直接 import lib 的例外：冪等查重與 git 執行點在
CLI 邊界上還沒有消費者，檔頭已註明等 #4 與 #10 落地後即可縮小或移除。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-17 04:26:51 +00:00