devlog-tracker 0.33.2 → 0.33.4

package/README.md

@@ -2,7 +2,7 @@
 
 *English | [繁體中文](README.zh-TW.md)*
 
-**Version** 0.33.2
+**Version** 0.33.4
 
 Maintains a `.devlog/devlog.md` in your project, turning each conversation round's requests, decisions, and outcomes into a permanent record. A conversation disappears the moment you `/clear` or switch sessions; this file fills that gap so work can pause and resume. Nothing is touched until you explicitly run `/devlog-tracker:start` — installing the plugin alone doesn't create or modify any files.
 

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 *[English](README.md) | 繁體中文*
 
-**版本** 0.33.2
+**版本** 0.33.4
 
 在專案中維護一份 `.devlog/devlog.md`，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 `/clear` 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 `/devlog-tracker:start` 時，裝著也不會動任何檔案。
 

package/commands/checkpoint.md

@@ -7,7 +7,7 @@ description: 調整 Checkpoint Mode 的沉默門檻——累積多少輪沒寫 #
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/checkpoint-set.sh" <rounds>
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/checkpoint-set.sh" <rounds>
 ```
 
 不要自己手改 `.devlog/.checkpoint-state`。

package/commands/clean.md

@@ -34,7 +34,7 @@ description: 無條件清空 .devlog/devlog.md（含專案摘要與所有 Round
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/clean-devlog.sh" --confirmed
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/clean-devlog.sh" --confirmed
 ```
 ```
 

package/commands/compact.md

@@ -16,7 +16,7 @@ description: 把 .devlog/devlog.md 裡已完成且較舊的紀錄搬到 devlog.a
    先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
    PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-   DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/compact-devlog.sh"
+   DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/compact-devlog.sh"
    ```
    檔案不存在時腳本 exit 1：告知沒有東西可壓縮。
 5. 用 stdout 的 `MOVED` / `REMAINING` / `ARCHIVE` 回報一句話。

package/commands/keep.md

@@ -84,7 +84,7 @@ description: 掃描整份 devlog.md，把值得留名的主題段落一次分別
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/keep-move.sh" \
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/keep-move.sh" \
   --from <from> --to <to> --name "<name>" --desc "<這段在做什麼的一句話>"
 ```
 

package/commands/lessons-drift.md

@@ -6,7 +6,7 @@ description: 調整 Lessons Mode 機制性提醒的共用門檻——工作區
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/lessons-drift-set.sh" <次數>
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/lessons-drift-set.sh" <次數>
 ```
 
 不要自己手改 `.devlog/.lessons-advisory-state`。

package/commands/lessons-off.md

@@ -7,7 +7,7 @@ description: 關閉 Lessons Mode。不會刪除任何已寫的 devlog.lessons.*.
 1. 先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
    PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-   DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/lessons-off.sh"
+   DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/lessons-off.sh"
    ```
    不要自己刪 `.lessons-enabled`。
 2. stdout 是 `NOT_ENABLED`：告知 Lessons Mode 本來就沒開，結束。

package/commands/lessons-on.md

@@ -7,7 +7,7 @@ description: 開啟 Lessons Mode（開發歷程教訓，預設關閉）。隸屬
 1. 先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
    PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-   DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/lessons-on.sh"
+   DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/lessons-on.sh"
    ```
    不要自己用手建 `.lessons-enabled`。
 2. stdout 是 `NOT_ENABLED`：告知這個專案還沒下過 `/devlog-tracker:start`，Lessons Mode 隸屬主開關，沒有 Round/Status 紀錄可判斷「BLOCKED→解開」，請先 `/devlog-tracker:start` 再開這個。

package/commands/pause.md

@@ -10,7 +10,7 @@ description: 暫停這個專案的 devlog 強制記錄機制。不會刪除任
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/pause-devlog.sh"
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/pause-devlog.sh"
 ```
    ```
    不要自己刪 `.enabled`。

package/commands/report.md

@@ -6,7 +6,7 @@ description: 查看 devlog 統計：Round 數、各 Status、BLOCKED 比例、Ch
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/report-devlog.sh"
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/report-devlog.sh"
 ```
 
 使用者要看所有 branch 的合計時加 `--all-branches`。

package/commands/segment-watch.md

@@ -10,7 +10,7 @@ description: 調整 Segment Watch 的沉默門檻——同一輪連續多久沒
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/segment-watch-set.sh" <seconds>
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/segment-watch-set.sh" <seconds>
 ```
 ```
 

package/commands/span.md

@@ -5,9 +5,9 @@ description: 開啟或關閉 Span Mode，讓自動續接的長任務定期記錄
 先判斷使用者要開啟或關閉：
 
 - 使用者明確要求關閉，或 `.devlog/.span-open` 已存在且沒有明確要求重新開啟：
-  先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），設 `PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"`，再跑 `DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/span-close.sh"`，
+  先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），設 `PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"`，再跑 `DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/span-close.sh"`，
   再依 SKILL 的 span 收尾規則寫一個**新的 Round**，總結整段 span。
 - 使用者要求開啟：先把目前 Round 正常寫完，`Status` 設為 `IN_PROGRESS`，再跑
-  `DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/span-open.sh"`。
+  `DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/span-open.sh"`。
 
 不要手寫 `.span-open` JSON。腳本 exit 1 時顯示 stderr，停止操作。

package/commands/start.md

@@ -7,7 +7,7 @@ description: 啟動這個專案的 devlog 強制記錄機制。之後每一輪
 1. 先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
    PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-   DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/start-devlog.sh"
+   DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/start-devlog.sh"
    ```
    不要自己用手建 `.enabled` / `.checkpoint-state` / `.segment-state`。
 2. 若 stdout 有 `GITIGNORE_DEVLOG=no`：鄭重提醒——`.devlog/` 會寫入使用者原文（遮罩只覆蓋常見 token 前綴，不是通用掃密）。**強烈建議**把 `.devlog/` 加進專案 `.gitignore`。問要不要現在加。只有使用者明確說要，才在 `.gitignore` 末尾追加一行 `.devlog/`（檔案不存在就建立）。不要改其他行。若使用者拒絕，再警告一次「之後若不小心 commit，prompt／殘留密鑰可能進版控」，然後繼續步驟 3。

package/commands/status.md

@@ -8,7 +8,7 @@ description: 查看這個專案 devlog 強制記錄是否開著、span / checkpo
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/status-devlog.sh"
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/status-devlog.sh"
 ```
 ```
 把 stdout 翻譯成給人看的幾行（含 `LESSONS=yes/no`：Lessons Mode 開關狀態；`LESSONS_ADVISORY=<count>/<threshold>`：Lessons Mode 開著時，機制性訊號（工作區漂移不符、或

package/commands/timeline.md

@@ -6,7 +6,7 @@ description: 把 devlog 產生成一份離線可開的 HTML 時間軸（.devlog/
 
 ```bash
 PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
-DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/timeline-devlog.sh"
+DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/timeline-devlog.sh"
 ```
 
 使用者要看所有 branch 時加 `--all-branches`；要寫到別的位置時加 `--out <路徑>`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlog-tracker",
-  "version": "0.33.2",
+  "version": "0.33.4",
   "description": "npx installer for devlog-tracker's Claude Code, Cursor and Codex adapters.",
   "bin": {
     "devlog-tracker": "bin/devlog-tracker.js"

package/skills/devlog-tracker/SKILL.md

@@ -3,10 +3,7 @@ name: devlog-tracker
 description: 在專案的 .devlog/devlog.md 維護逐輪對話紀錄。使用者下 /devlog-tracker:start 後 Stop hook 強制每輪寫入；SessionStart 在 startup / resume / compact / fork 注入進度，/clear 不注入；要接續用 /devlog-tracker:continue。當使用者提到「devlog-tracker」「.devlog/devlog.md」「/devlog-tracker:continue」或明確要寫／接續這份紀錄時使用。
 ---
 
-# Devlog Tracker（簡化版）
-
-參考 agfnow/agentflow 的 devlog 基礎協定做的簡化版，只保留「逐輪對話紀錄」這一層，
-不含原版的 10 步驟 SDD pipeline、多模型對抗審查、external worker 外包等進階機制。
+# Devlog Tracker
 
 ## Contract
 
@@ -104,9 +101,7 @@ Claude Code 目前沒有正式、穩定的方式讓 hook 知道「這一輪有
 
 1. 使用者送出新訊息時，`UserPromptSubmit` hook（`core/scripts/round-start.sh`）
    若開關開著，就在 `.devlog/.round-current.md` 寫入這一輪的 skeleton（`### User Input`
-   + `Status: IN_PROGRESS`），並寫 `.devlog/.round-open`。`.turn-start` 雜湊是
-   **寫完 skeleton 之後**才對 `.round-current.md` 拍的，所以 Stop 仍能判斷 Claude
-   有沒有再補收尾。
+   + `Status: IN_PROGRESS`），並寫 `.devlog/.round-open`。
 2. Claude 編輯**同一個** Round：不要再 append 一個新的 `## Round`。不要改 User Input
    （除非裡面是 hook 的 `（無 prompt）` 占位）。補上 `### Summary` / `### Reply` / `### Handoff`，
    把 Status 改成 `DONE` / `IN_PROGRESS` / `BLOCKED`。這一輪還開著的時候，編輯的對象
@@ -123,21 +118,14 @@ Claude Code 目前沒有正式、穩定的方式讓 hook 知道「這一輪有
 這個事件上。
 
 需要誠實說明的邊界：User Input 在送出當下就已經在 `.devlog/.round-current.md`
-（收尾成功或被判定中斷後才會併回 `devlog.md`）。正常結束時 Stop 仍保證有 Summary / Handoff。
+（收尾成功或被判定中斷後才會併回 `devlog.md`）。正常結束時 Stop 仍保證有 Summary / Reply / Handoff。
 意外中斷會把同一塊標成 `INTERRUPTED`（process 被殺、或 mid-turn 取消時，Status 通常要等
 **下一則訊息**或**下次 SessionStart（startup / resume / clear / fork）**才補上）。
 `PostToolUseFailure` 的 `is_interrupt` 若有觸發，只是 best-effort 的額外路徑，不能當成 Esc
 會立刻蓋章。中間沒寫成 `### 段落` 的過程仍會丟——Segment Watch 只在還有下一個工具呼叫時催促。
 
-### 兩個穩健性設計（參考 agfnow/agentflow 的 stop-hook.js）
-
-- **loop guard**：`enforce-devlog.sh` 一開始會讀 stdin 的 `stop_hook_active` 欄位——這是
-  Claude Code 官方標準欄位，代表「這輪已經被本支 hook 擋下來一次、Claude 正在重跑」，
-  此時直接放行，不會一直卡住同一輪。Claude Code 本身也有連續擋 8 次的上限保護，這是多
-  一層保險。
-- **fail-open**：三支 hook 腳本都不用 `set -e`，每一步可能失敗的地方（讀不到檔案、雜湊
-  算不出來）都明確接住、失敗就直接放行。這些腳本的職責是「檢查」，不該因為自己的臭蟲
-  就意外把使用者的 session 卡死。
+hook 本身出錯時一律放行（fail-open），同一輪被 Stop 擋過一次後重跑也會放行（loop guard）；
+設計說明見 `core/scripts/enforce-devlog.sh` 開頭註解。
 
 ## 自動接續與 `/clear`
 
@@ -149,8 +137,8 @@ matcher 設為 `startup|resume|clear|compact|fork`。**開新 session、resume
 
 1. 若目前分支的 `.devlog/handoff.md`（或 `handoff.<branch>.md`）非空，先注入這份 Session Handoff 快照
 2. 再讀取 `.devlog/devlog.md`，注入最後一個 `## Checkpoint`（若有）、最後一個 `## Kept 索引`（若有；不是具名檔內容）、最後一個 `## Lessons 索引`（若有），加上最近 2 輪的 Summary / Handoff / Status（沒有 Summary 的 skeleton 才帶 User Input）
-3. 印到 stdout，Claude Code 會把這段文字當成這次 session 的 additionalContext 自動注入
-4. Claude 收到這段 context 後，開場就已經知道目前進度
+
+這段摘要會出現在 session 開頭的 context 裡。
 
 `/clear` 時 hook 仍可能把殘留的開著 Round 標成 `INTERRUPTED`，但 stdout 什麼都不印。
 之後只有使用者下 `/devlog-tracker:continue`，或明確說「continue」「接續」「繼續上一題」時，

package/skills/devlog-tracker/references/contract.md

@@ -50,7 +50,7 @@
 | Hard：上一輪工作區漂移擋工具 | PreToolUse（continue 同 session） | `SKILL.md`「接續」；`commands/continue.md` |
 | Hard：Segment Watch 逾時先補段落 | PreToolUse | `references/round-segments.md` |
 | Soft：Checkpoint／Lessons 建議 | hook 提示，不強制寫入本身 | `references/checkpoint-mode.md`／`lessons-mode.md` |
-| fail-open／loop guard | hook 穩健性 | `SKILL.md`「兩個穩健性設計」 |
+| fail-open／loop guard | hook 穩健性 | `core/scripts/enforce-devlog.sh` 開頭註解 |
 
 ## Transformation
 

package/skills/devlog-tracker/references/reply-fold.md

@@ -58,7 +58,7 @@ DEVLOG_PROJECT_DIR="<專案根目錄絕對路徑，不要用 $(pwd)>" bash "${DE
 這會寫入 `.devlog/.awaiting-reply`，記住「下一則訊息大概是在回答這個
 Round」。不需要使用者下任何指令，也不用手寫這個 JSON。
 
-上面第 2 步已經讓這一輪正常收尾（Summary／Handoff／Status 都有效），所以
+上面第 2 步已經讓這一輪正常收尾（Summary／Reply／Handoff／Status 都有效），所以
 這個 turn 結束時它會照一般流程併回 `.devlog/devlog.md`。也就是說，**提問
 出去、答案還沒進來的這段期間**（使用者可能過很久才回覆），這一輪確實已經
 完整躺在 `devlog.md` 的歷史裡，不是懸在 `.devlog/.round-current.md` 裡假裝