feat(log): 每完成一個任務就寫一筆日誌，暫存改三段式 #16

2026-08-27T03:20:55Z

jiantw83 commented

2026-08-27 03:20:55 +00:00

摘要

需求描述：落實「SDLC 執行流程」規則群的第一條——每完成一個任務就立刻寫工作日誌。任務有三種：一個工作包、一輪 PR 留言修正、一個獨立的修正提交。stage-report.sh --pending-file 只是暫存，要併進同一次日誌寫入，寫成功之後才清除。決策紀錄在 wiki 存取庫 knowledges/QUESTION 的 QUESTION_FB8DF0B5，2026-08-27 那一節。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`tools/worklog-pending.sh`	原本只有一個 `clear`，呼叫端只能先清再寫（寫失敗兩邊都沒有）或寫完清全部（把中途新存進來的內容一起刪掉）。新增 `merge`、`commit`、`abort` 三段式，把「清除」綁在 wiki 寫入的結果上
`skills/worklog/SKILL.md`	原本一個階段寫一筆，五輪留言修正被攤成一個總數，看不出哪一輪花掉多少，沒改到檔案的那一輪更是整段消失。改成一個任務一筆，寫入流程換成三段式
`templates/log-entry.md`	頁首說明還寫著「每完成一項工作附加一個條目」，與新粒度對不上
`README.md`	技能說明與工具表同步改寫，不然使用者會照舊以為一個階段寫一筆、清暫存用 `clear`
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	行為變更要 bump 版本；三份同步升到 0.1.1

設計重點

一個任務一筆，下一個任務開始前寫完。這是整條粒度規則的全部；五輪留言修正就是同一頁上的五筆，各自帶自己的花費時間與 token 用量。
沒改到檔案的那一輪也要留。它燒掉的時間正是最容易消失、也最值得留下的事實，條目裡寫清楚試了什麼、為什麼放棄。
每筆條目一個標題，寫明是哪個工作包、第幾輪或哪個提交，五筆並排才讀得下去；條目一律附加在頁尾，既有條目不動。
merge 只讀不刪，刪檔一律等 commit。只刪併入清單上那幾個檔，是為了保住 merge 之後、commit 之前另一個工作階段新存進來的內容。
commit 只認 merge 產出的清單，而且清單上的路徑必須落在該 hash 的暫存目錄底下，否則當用法錯誤擋下來——這道護欄擋的是拿別處的清單來刪檔。
abort 一個暫存都不刪，下一次 merge 會再把它們併進去，所以失敗重試不會掉內容。
merge 在沒有暫存時仍然回 0：合併檔至少有本次條目，呼叫端不必為「有沒有暫存」分兩條路走。

測試結果

sh -n tools/worklog-pending.sh：語法檢查通過。
用暫時的 $JSC_HOME 走過完整流程：add 存一份暫存後 merge，印出 MERGED=、CLAIM=、PENDING=1，合併檔內容確認是「暫存在前、本次條目在後」。
失敗路徑：abort 之後印「暫存保留 1 個檔案」，list 仍列得出那份暫存，內容沒掉。
成功路徑：重跑 merge 後 commit，印「已清除暫存 1 個檔案」，再 list 回 3（沒有暫存內容）。
護欄：commit ABCD1234 /etc/passwd 回 2 並印繁中訊息，指出併入清單必須是 merge 產出的那一份。
ste100-lint.sh .：全庫零命中。
三份 manifest 以 JSON 解析器讀過，格式正確且版本一致為 0.1.1。
未測：worklog 技能實際寫進 wiki 的往返，需要可連線的 Gitea 與設定好的 JSC_WIKI_REPO_LOG，本次在沒有 Gitea 存取的環境進行。

前置 Push Request

無

## 摘要 - 需求描述：落實「SDLC 執行流程」規則群的第一條——每完成一個任務就立刻寫工作日誌。任務有三種：一個工作包、一輪 PR 留言修正、一個獨立的修正提交。`stage-report.sh --pending-file` 只是暫存，要併進同一次日誌寫入，寫成功之後才清除。決策紀錄在 wiki 存取庫 `knowledges/QUESTION` 的 `QUESTION_FB8DF0B5`，2026-08-27 那一節。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/worklog-pending.sh` | 原本只有一個 `clear`，呼叫端只能先清再寫（寫失敗兩邊都沒有）或寫完清全部（把中途新存進來的內容一起刪掉）。新增 `merge`、`commit`、`abort` 三段式，把「清除」綁在 wiki 寫入的結果上 | | `skills/worklog/SKILL.md` | 原本一個階段寫一筆，五輪留言修正被攤成一個總數，看不出哪一輪花掉多少，沒改到檔案的那一輪更是整段消失。改成一個任務一筆，寫入流程換成三段式 | | `templates/log-entry.md` | 頁首說明還寫著「每完成一項工作附加一個條目」，與新粒度對不上 | | `README.md` | 技能說明與工具表同步改寫，不然使用者會照舊以為一個階段寫一筆、清暫存用 `clear` | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 行為變更要 bump 版本；三份同步升到 0.1.1 | ## 設計重點 - 一個任務一筆，下一個任務開始前寫完。這是整條粒度規則的全部；五輪留言修正就是同一頁上的五筆，各自帶自己的花費時間與 token 用量。 - 沒改到檔案的那一輪也要留。它燒掉的時間正是最容易消失、也最值得留下的事實，條目裡寫清楚試了什麼、為什麼放棄。 - 每筆條目一個標題，寫明是哪個工作包、第幾輪或哪個提交，五筆並排才讀得下去；條目一律附加在頁尾，既有條目不動。 - `merge` 只讀不刪，刪檔一律等 `commit`。只刪併入清單上那幾個檔，是為了保住 `merge` 之後、`commit` 之前另一個工作階段新存進來的內容。 - `commit` 只認 `merge` 產出的清單，而且清單上的路徑必須落在該 hash 的暫存目錄底下，否則當用法錯誤擋下來——這道護欄擋的是拿別處的清單來刪檔。 - `abort` 一個暫存都不刪，下一次 `merge` 會再把它們併進去，所以失敗重試不會掉內容。 - `merge` 在沒有暫存時仍然回 `0`：合併檔至少有本次條目，呼叫端不必為「有沒有暫存」分兩條路走。 ## 測試結果 - `sh -n tools/worklog-pending.sh`：語法檢查通過。 - 用暫時的 `$JSC_HOME` 走過完整流程：`add` 存一份暫存後 `merge`，印出 `MERGED=`、`CLAIM=`、`PENDING=1`，合併檔內容確認是「暫存在前、本次條目在後」。 - 失敗路徑：`abort` 之後印「暫存保留 1 個檔案」，`list` 仍列得出那份暫存，內容沒掉。 - 成功路徑：重跑 `merge` 後 `commit`，印「已清除暫存 1 個檔案」，再 `list` 回 `3`（沒有暫存內容）。 - 護欄：`commit ABCD1234 /etc/passwd` 回 `2` 並印繁中訊息，指出併入清單必須是 `merge` 產出的那一份。 - `ste100-lint.sh .`：全庫零命中。 - 三份 manifest 以 JSON 解析器讀過，格式正確且版本一致為 0.1.1。 - 未測：`worklog` 技能實際寫進 wiki 的往返，需要可連線的 Gitea 與設定好的 `JSC_WIKI_REPO_LOG`，本次在沒有 Gitea 存取的環境進行。 ## 前置 Push Request - 無

jiantw83 added 4 commits 2026-08-27 03:20:55 +00:00

feat(worklog-pending): 暫存改三段式的 merge、commit、abort 416fb916cb

What：`tools/worklog-pending.sh` 新增 `merge {hash} {本次條目檔}`、`commit {hash} {併入清單}`、`abort {hash} {併入清單}` 三個子命令。`merge` 合成「暫存內容在前、本次條目在後」的檔案並印出 `MERGED=`、`CLAIM=`、`PENDING=`；`commit` 只刪併入清單上那幾個檔；`abort` 暫存一個都不刪，只丟掉合併檔與清單。原本的 `clear` 保留，改為清掉全部暫存。

Why：暫存只能在 wiki 寫入成功之後才清，但原本只有一個 `clear`，呼叫端要嘛先清再寫（寫失敗就兩邊都沒有），要嘛寫完清全部（把 `merge` 之後才存進來的內容一起刪掉）。兩種都會弄丟工作紀錄。

How：`merge` 只讀不刪，刪檔一律等 `commit`，也就是等 wiki 回報成功。只刪清單上的檔案，是為了保住 `merge` 之後、`commit` 之前另一個工作階段新存進來的內容。`commit` 只認 `merge` 產出的清單，而且清單上的路徑必須落在該 hash 的暫存目錄底下，不然當用法錯誤擋下來——這道護欄擋的是拿別處的清單來刪檔。`merge` 在沒有暫存時仍然回 `0`，合併檔至少有本次條目，呼叫端不必分兩條路走。

Who：`jsc-log:worklog` 寫日誌那一步，以及用 `stage-report.sh --pending-file` 暫存過內容的 SDLC 階段。

feat(worklog): 每完成一個任務就寫一筆日誌 5e61528ad0

What：`worklog` 技能改成一個任務一筆條目，任務有三種——一個工作包、一輪 PR 留言修正、一個獨立的修正提交，並新增「What counts as one task」一表寫明各自何時結束；寫入步驟改走 `merge`、`commit`、`abort` 三段式，十項資訊裡的花費時間、token 用量、任務狀態、執行細節四項改成只算這一個任務。`templates/log-entry.md` 的頁首說明同步改寫。

Why：原本一個階段只寫一筆，同一個工作包跑五輪留言修正也只留下一筆。花費時間與 token 用量被攤成一個總數，看不出哪一輪花掉多少；連「試了卻沒改到檔案」的那一輪也整段消失，而那段時間正是最該被看見的。

How：下一個任務開始前先把這一筆寫完，五輪就是五筆，各自帶自己的花費時間與 token 用量，一律附加到同一頁 `LOG_{HASH}`，既有條目不動。每筆的標題要寫清楚是哪一個任務（工作包代號、第幾輪、或提交標題），五筆並排才讀得下去。花費時間在任務結束的當下讀，token 用量傳同一個 session id，兩個數字才描述同一件事。

Who：`jsc-sdlc:implement` 與 `jsc-sdlc:maintain` 收尾時呼叫日誌的每一個工作階段。

docs(log): README 同步日誌粒度與三段式暫存 7eb93af733

What：README 的 `worklog` 技能說明改寫成「每完成一個任務就寫一筆」並列出三種任務，工具表的 `worklog-pending.sh` 一列補上 `merge`、`commit`、`abort` 三個子命令與各自的時機。

Why：粒度與暫存流程都變了，README 是對外說明。說明沒跟上，使用者會照舊以為一個階段寫一筆、清暫存用 `clear`。

How：技能說明拆成兩段，第一段講粒度、第二段講十項資訊與寫入流程；工具表那一列把「寫進 wiki 成功之後才清」這句留著，因為三段式要守的正是這一條。

Who：讀 `jsc-log` 說明的人，以及要接 `worklog-pending.sh` 的 `jsc-sdlc`。

chore(manifest): 三份 manifest 版本升到 0.1.1 52b35a2d6b

What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 的 `version` 由 0.1.0 改為 0.1.1。

Why：本次改了日誌粒度並新增三個暫存子命令，屬於行為變更，版本要跟著往上走，各 CLI 才知道要更新。

How：三份只改 `version` 一個欄位，其餘內容不動，三份保持同一版號。

Who：`jsc-log` 外掛的套件描述檔。

jiantw83 referenced this pull request from plugins/sdlc

2026-08-27 03:21:24 +00:00

feat(sdlc): 工作包隔離、留言取得共識後再修、盯 PR 到合併與每任務一筆日誌 #29

jiantw83 added a new dependency 2026-08-27 03:21:32 +00:00

plugins/sdlc#29 - feat(sdlc): 工作包隔離、留言取得共識後再修、盯 PR 到合併與每任務一筆日誌

admin merged commit c513f6a4e9 into feat/sdlc-flow-rules/main

2026-08-27 03:26:14 +00:00

admin deleted branch feat/sdlc-flow-rules/worklog-per-task

2026-08-27 03:26:14 +00:00

jiantw83 referenced this pull request

2026-08-27 03:38:54 +00:00

feat(log): 每完成一個任務就寫一筆日誌，暫存改三段式寫入 #17