devlog-tracker 0.22.0

package/skills/devlog-tracker/references/round-segments.md

@@ -0,0 +1,55 @@
+# Round Segments：單輪內的階段性記錄
+
+一輪如果包含好幾個明顯階段（先探索、再做決策、再實作、再驗證），不要全部
+憋到最後才寫一次 Summary／Handoff——那樣中途 crash 會整輪的過程全部遺失，事後也
+看不出中間走過的路。改成邊做邊在這輪底下追加階段性子區塊，插在 User Input 和
+收尾的 Summary／Handoff 之間：
+
+`````markdown
+## Round 15 — 2026-09-09T09:00:00+08:00
+
+### User Input
+幫我重構 XXX 模組
+
+### 段落 1 - 09:12
+讀完現有程式碼，發現三個地方耦合...
+
+### 段落 2 - 09:20
+決定拆成 A/B 兩個檔案，理由...
+
+### 段落 3 - 09:35
+完成拆分，跑測試全過
+
+### Summary
+把 XXX 模組拆成 A/B 兩個檔案，測試全過。
+
+### Handoff
+#### 決策
+拆成 A/B，理由是三處耦合都集中在同一個檔。
+#### 檔案
+新增 a.ts、b.ts；刪除 xxx.ts。尚未 commit。
+#### 現況
+拆分完成，測試全過。
+
+### Status
+DONE
+`````
+
+這個範例是 DONE 且沒有後續，所以沒有 `#### 工作區` 與 `#### 下一步`；這兩節只有 IN_PROGRESS／BLOCKED 才寫。
+
+**什麼時候該寫一個段落**：跟判斷 `Status: IN_PROGRESS` 用的同一套標準——「有意義的
+階段性結果」，不是照時間或工具呼叫次數機械觸發。短的、沒什麼階段可言的一輪，
+照舊只寫 Summary／Handoff 就好，不用硬湊段落。不要把段落內容再抄進 Summary 或 Handoff。
+
+主路徑仍是判斷何時寫段落，不是照時間機械切段。另外有一道保底：`/devlog-tracker:start`
+之後，同一輪若連續 10 分鐘（`max_silent_seconds`，預設 600）都沒改
+`.devlog/.round-current.md`（目前開著的這一輪，見 `docs/design/round-current-split.md`），
+下一個工具會被 PreToolUse hook 擋住。被擋時先 **Read** `.devlog/.round-current.md`，再用
+Edit／StrReplace **追加**一段 `### 段落`（一行也可以）；**禁止**用 Write 覆寫整份檔。
+寫了任何內容計時就歸零。不要用 Bash 繞過。沒呼叫工具就不會響。Claude Code
+dynamic workflow／subagent 的 PreToolUse 若帶非空 `agent_id`，此閥門會跳過（它們
+與主對話共用 `session_id`，不該被逼寫父輪段落）。門檻用
+`/devlog-tracker:segment-watch <時間長度>`（例如 `/devlog-tracker:segment-watch 5 分鐘`）
+調整，不用手改 `.devlog/.segment-state` 的 `max_silent_seconds`。
+
+收尾時 Stop hook 仍會要求最後一個 Round 上看得到 `### Summary` 與 `### Handoff`。

package/skills/devlog-tracker/references/span-mode.md

@@ -0,0 +1,65 @@
+# Span Mode：橫跨多次自動續接的長任務
+
+`/loop` 動態模式、`Workflow`、或任何會讓 Claude 被自己排程（`ScheduleWakeup`、
+背景 agent 完成通知）反覆喚醒、而不是被使用者手動打字觸發的長任務，如果每次
+自動喚醒都被當成一輪、強制要求完整寫入 devlog.md，會逼出很多沒有意義的紀錄，
+或是卡住整個自動化流程。Span Mode 是這種情境下的例外機制。
+
+設計動機、hook 機制細節見 `docs/design/span-mode.md`；這裡只講操作規則。
+
+## 什麼時候該開一個 span
+
+只有在**確定接下來會進入一連串自動續接**時才開（例如剛要開始跑 `/loop` 動態
+模式、或剛派出一個 `Workflow`），不是每輪隨便判斷。一般的互動式對話不需要，
+也不應該開 span。
+
+## 怎麼開一個 span
+
+寫完這一輪正常的 Round 區塊（Status 用 `IN_PROGRESS`）之後，使用
+`/devlog-tracker:span`（或跑 `span-open.sh`）建立 `.devlog/.span-open`。
+除非腳本不可用，否則不要手寫 JSON。檔案格式如下：
+
+```json
+{
+  "round": 12,
+  "opened_at": "2026-09-08T21:40:00+08:00",
+  "ticks_since_checkin": 0,
+  "max_silent_ticks": 5
+}
+```
+
+- `round`：剛寫的那個 Round 的編號
+- `opened_at`：現在的 ISO 8601 時間戳
+- `ticks_since_checkin`：固定從 0 開始
+- `max_silent_ticks`：這個 span 容許連續幾次自動 tick 都不寫 devlog.md，自己
+  依任務性質挑一個合理值（沒有標準答案，抓 5 這類量級即可）
+
+## span 開著的時候會自動發生什麼事
+
+不用手動維護——`round-start.sh` 每次自動續接觸發時會自己把 `ticks_since_checkin`
++1，`enforce-devlog.sh` 只要這個數字還沒到 `max_silent_ticks` 就直接放行，
+devlog.md 完全不用動。一旦累積到門檻，Stop hook 會退回正常模式，**這一輪就
+會被要求寫東西才能結束**——看到這種擋下來的訊息，代表這個 span 的「安靜額度」
+用完了，寫點輕量的進度（不用完整 Round，一行都可以）就能讓它繼續運作。
+前提是最後一個 Round 裡已經有 `### Summary` 與 `### Handoff`——一行是追加到那個 Round，不是新開一個缺標題的 Round。若這輪是新開的 Round，兩個標題都要有。
+
+## 怎麼關掉一個 span
+
+整個 Ask 真的做完時：**開一個新的 Round**（不要回頭改寫當初開 span 那個
+Round），User Input 可以寫「（自動續接收尾，接續 Round 12）」；Summary 用 2–4 句
+給人看這段自動化的結論；Handoff 依小節總結整段期間做了什麼（決策／檔案／工作區／現況／
+下一步；`DONE` 省略工作區與下一步）；Status 正常寫 `DONE`／`IN_PROGRESS`／`BLOCKED`；然後刪掉 `.devlog/.span-open`。
+
+## 已知限制：分辨不出「這是自動續接還是真人插話」
+
+Claude Code 目前沒有任何 hook 欄位能分辨一個 tick 是自動排程觸發的，還是使用
+者真的手動打了新訊息——這兩種在 span 開著時會被一視同仁地當成一個 tick。如果
+span 開著時你發現進來的其實是一個跟自動任務無關的新請求，應該自己先關掉 span
+（刪除 `.span-open`、補寫收尾的 Round）再處理新請求，不要讓它悄悄被吞進正在
+開著的 span 裡。
+
+## 崩潰時的風險
+
+span 開著時 session 如果崩潰，最壞會漏記最近 `max_silent_ticks` 個 tick 的
+活動——不是整段 span，風險有明確上限。這是跟「回合進行到一半被砍斷」（見
+SKILL.md「需要誠實說明的邊界」）同一類、但用 tick 數量而不是單一回合為界的風險。