devlog-tracker 0.25.1 → 0.29.2

package/commands/lessons-off.md

@@ -4,10 +4,10 @@ description: 關閉 Lessons Mode。不會刪除任何已寫的 devlog.lessons.*.
 
 請執行：
 
-1. 先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+1. 先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
-   PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-   CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/lessons-off.sh"
+   PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+   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

@@ -4,10 +4,10 @@ description: 開啟 Lessons Mode（開發歷程教訓，預設關閉）。隸屬
 
 請執行：
 
-1. 先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+1. 先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
-   PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-   CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/lessons-on.sh"
+   PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+   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/lessons.md

@@ -2,11 +2,11 @@
 description: 查看 Lessons 索引，或讀某個主題的完整教訓紀錄（純讀取，不核對工作區、不等確認）。
 ---
 
-取得使用者是否有給 `<topic>`（可能沒有，代表只看索引）。記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1）。先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
+取得使用者是否有給 `<topic>`（可能沒有，代表只看索引）。記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1）。先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/hooks/scripts/lessons-read.sh" "<topic，沒有就留空>"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/core/scripts/lessons-read.sh" "<topic，沒有就留空>"
 ```
 
 沒有 `<topic>`：

package/commands/overview.md

@@ -8,11 +8,11 @@ description: 把已 keep 的具名檔（devlog.<name>.md）整合成一份跨主
 
 ## 1. 取得已 keep 的檔案清單
 
-記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1）。先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
+記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1）。先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/hooks/scripts/kept-list.sh"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/core/scripts/kept-list.sh"
 ```
 
 - `NO_INDEX`：告知「目前沒有已 keep 的舊檔」，結束。

package/commands/pause.md

@@ -6,11 +6,11 @@ description: 暫停這個專案的 devlog 強制記錄機制。不會刪除任
 
 1. 跑：
    ```bash
-   先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+   先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/pause-devlog.sh"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/pause-devlog.sh"
 ```
    ```
    不要自己刪 `.enabled`。

package/commands/resume.md

@@ -2,11 +2,11 @@
 description: 讀取具名保存的 devlog，核對最後一輪 Handoff 工作區後再接續該段工作。
 ---
 
-取得使用者提供的 `<name>`；沒有名稱時先詢問。記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1：Bash 工具的工作目錄會在對話裡持續累積前面呼叫的 `cd`，用當下的 `pwd` 可能已經不是這個專案根目錄）。先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
+取得使用者提供的 `<name>`；沒有名稱時先詢問。記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1：Bash 工具的工作目錄會在對話裡持續累積前面呼叫的 `cd`，用當下的 `pwd` 可能已經不是這個專案根目錄）。先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/hooks/scripts/resume-devlog.sh" --name "<name>"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/resume-devlog.sh" --name "<name>"
 ```
 
 若回傳 `MISSING`，列出 `CANDIDATES` 讓使用者選，不要自動執行工作。

package/commands/search.md

@@ -0,0 +1,22 @@
+---
+description: 在 devlog.md／archive／keep 檔／lessons 檔裡搜尋關鍵字，讀完命中後用自己的話回答（純讀取，不核對工作區、不等確認）。
+---
+
+取得使用者提供的 `<關鍵字>`（或自然語言查詢裡的關鍵片語）；沒有給的話先問。這是純讀取，不做 `commands/continue.md`／`commands/resume.md` 那套「核對工作區、等確認才動手」流程——搜尋結果是導航用的參考，不是暫停中的工作主題。讀完之後不要自動據此修改任何檔案，除非使用者接著明確要求。
+
+記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 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="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/core/scripts/search-devlog.sh" "<關鍵字>"
+```
+
+這支腳本會掃過 `.devlog/devlog*.md`（含 `devlog.md`、`devlog.archive.md`、已 keep 的 `devlog.<name>.md`、`devlog.lessons.<topic>.md`，以及分支各自的 `devlog.<branch>.md`——一個 glob 涵蓋所有種類，不分別處理），做不分大小寫的字串比對，不是正則、不含 vector/LLM。自然語言查詢由你先抽出要搜的關鍵片語再丟給腳本；腳本本身不做 NLP。
+
+- `NO_INDEX`：告知目前還沒有任何 devlog 檔案，結束。
+- `NO_MATCH`：告知這個關鍵字沒有命中，結束。
+- 其他輸出：每個有命中的檔案先印一行 `FILE=.devlog/<檔名>`，接著是該檔案裡每一行命中，格式 `HEADING="<離命中最近的上方 ## 或 ### 標題>" LINE=<行號>: <命中行原文>`。
+
+**回答姿勢（跟 `/devlog-tracker:overview` 不同，也跟「原樣貼出列表」不同）：** 讀完腳本輸出後，用自己的話回答使用者在問什麼（決策、現況、誰提過什麼），把命中當依據串成敘事；必要時附上檔名、最近標題、行號當出處。不要把 `FILE=`／`HEADING=` 原始輸出整段貼給使用者當主回答。命中很多時先摘要再說細節，不要機械 dump。若命中落在具名檔或 lessons 檔，可提醒再用 `/devlog-tracker:resume <name>` 或 `/devlog-tracker:lessons <topic>` 看全文。
+
+標題比對不是圍欄感知的（不特別處理 ``` 區塊），命中或標題落在程式碼區塊裡時仍會照樣列出；這是刻意的簡化，換取不用重新實作 `devlog-md.sh` 的圍欄邏輯。

package/commands/segment-watch.md

@@ -6,11 +6,11 @@ description: 調整 Segment Watch 的沉默門檻——同一輪連續多久沒
 換算成整數秒數 `<seconds>`，跑：
 
 ```bash
-先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/segment-watch-set.sh" <seconds>
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+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 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），設 `PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"`，再跑 `CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/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`，再跑
-  `CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/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

@@ -4,10 +4,10 @@ description: 啟動這個專案的 devlog 強制記錄機制。之後每一輪
 
 請執行以下步驟：
 
-1. 先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+1. 先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
-   PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-   CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/start-devlog.sh"
+   PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+   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

@@ -4,11 +4,12 @@ description: 查看這個專案 devlog 強制記錄是否開著、span / checkpo
 
 跑：
 ```bash
-先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/status-devlog.sh"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/status-devlog.sh"
 ```
 ```
-把 stdout 翻譯成給人看的幾行（含 `LESSONS=yes/no`：Lessons Mode 開關狀態；`LESSONS_DRIFT=<count>/<threshold>`：Lessons Mode 開著時，工作區漂移不符的累積次數／門檻）。不要改任何檔。`NOT_STARTED` 就說還沒 `/devlog-tracker:start`。
+把 stdout 翻譯成給人看的幾行（含 `LESSONS=yes/no`：Lessons Mode 開關狀態；`LESSONS_ADVISORY=<count>/<threshold>`：Lessons Mode 開著時，機制性訊號（工作區漂移不符、或
+BLOCKED 輪次累積）的共用累積次數／門檻）。不要改任何檔。`NOT_STARTED` 就說還沒 `/devlog-tracker:start`。

package/{hooks → core}/scripts/await-open.sh

@@ -9,7 +9,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-path.sh
 . "$SCRIPT_DIR/devlog-path.sh"
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 [ -f "$DEVLOG_DIR/.enabled" ] || { echo "NOT_ENABLED"; exit 1; }
 [ ! -e "$DEVLOG_DIR/.awaiting-reply" ] || { echo "ALREADY_OPEN"; exit 1; }
 ROUND=""

package/{hooks → core}/scripts/checkpoint-set.sh

@@ -8,7 +8,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=json-field.sh
 . "$SCRIPT_DIR/json-field.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then

package/{hooks → core}/scripts/clean-devlog.sh

@@ -13,7 +13,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # replacement for that confirmation.
 [ "${1:-}" = "--confirmed" ] || { echo "需要 --confirmed（使用者尚未確認，不要呼叫這支腳本）" >&2; exit 1; }
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_lock_acquire
 trap 'devlog_lock_release' EXIT
 MAIN="$DEVLOG_FILE"
@@ -60,6 +60,7 @@ else
 fi
 
 rm -f "$DEVLOG_DIR/.span-open" "$DEVLOG_DIR/.interrupted" "$DEVLOG_DIR/.awaiting-reply"
+rm -f "$HANDOFF_FILE"
 if [ -f "$DEVLOG_DIR/.checkpoint-state" ]; then
   json_int_set "$DEVLOG_DIR/.checkpoint-state" rounds_since_checkpoint 0
   json_int_set "$DEVLOG_DIR/.checkpoint-state" checkpoint_marker_count 0

package/{hooks → core}/scripts/close-open-round.sh

@@ -32,7 +32,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-md.sh
 . "$SCRIPT_DIR/devlog-md.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 ENABLED_FLAG="$DEVLOG_DIR/.enabled"
 ROUND_OPEN="$DEVLOG_DIR/.round-open"

package/{hooks → core}/scripts/compact-devlog.sh

@@ -7,7 +7,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 . "$SCRIPT_DIR/devlog-lock.sh"
 . "$SCRIPT_DIR/devlog-path.sh"
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_lock_acquire
 trap 'devlog_lock_release' EXIT
 MAIN="$DEVLOG_FILE"

package/{hooks → core}/scripts/devlog-lock.sh

@@ -2,8 +2,9 @@
 # Sourced helper for serializing writes under .devlog.
 devlog_lock_acquire() {
   local dir="${DEVLOG_DIR:-.}/.lock"
-  local start now
+  local start now pid
   LOCK_HELD=0
+  LOCK_CONTENDED_BY=""
   command -v mkdir >/dev/null 2>&1 || return 0
   command -v rmdir >/dev/null 2>&1 || return 0
   command -v date >/dev/null 2>&1 || return 0
@@ -12,10 +13,24 @@ devlog_lock_acquire() {
   while true; do
     if mkdir "$dir" 2>/dev/null; then
       LOCK_HELD=1
+      printf '%s\n' "$$" > "$dir/pid" 2>/dev/null || true
       return 0
     fi
+    pid="$(cat "$dir/pid" 2>/dev/null || true)"
+    case "$pid" in
+      ''|*[!0-9]*) pid='' ;;
+    esac
+    # Stale lock: the pid that created it is no longer running (a crashed
+    # session), so reclaim it immediately instead of waiting out the full
+    # contention timeout below.
+    if [ -n "$pid" ] && ! kill -0 "$pid" 2>/dev/null; then
+      rm -rf "$dir" 2>/dev/null || true
+      continue
+    fi
     now="$(date +%s 2>/dev/null || echo 0)"
     if [ $((now - start)) -ge 2 ]; then
+      # shellcheck disable=SC2034 # consumed by callers (e.g. enforce-devlog.sh), not used in this file
+      LOCK_CONTENDED_BY="$pid"
       return 0
     fi
     sleep 0.1 2>/dev/null || true
@@ -24,6 +39,7 @@ devlog_lock_acquire() {
 
 devlog_lock_release() {
   if [ "${LOCK_HELD:-0}" -eq 1 ]; then
+    rm -f "${DEVLOG_DIR:-.}/.lock/pid" 2>/dev/null || true
     rmdir "${DEVLOG_DIR:-.}/.lock" 2>/dev/null || true
     LOCK_HELD=0
   fi

package/{hooks → core}/scripts/devlog-path.sh

@@ -14,18 +14,23 @@ _devlog_sanitize_name() {
   printf '%s' "$1" | sed -E 's/[^A-Za-z0-9._-]/-/g; s/-+/-/g; s/^-+//; s/-+$//'
 }
 
-# Sets DEVLOG_DIR and DEVLOG_FILE for the branch currently checked out in
-# $1 (defaults to "."). main/master (any case) and anything that isn't a
-# git repo or has no resolvable branch keep the shared devlog.md. Any
-# other branch gets devlog.<sanitized-branch>.md; a detached HEAD (or an
-# unborn branch, which git also reports as "HEAD" here) falls back to the
-# working directory's own basename. The first time a branch resolves to a
-# file that doesn't exist yet while devlog.md already has content, the
-# existing devlog.md is renamed (not copied) into that branch's file.
+# Sets DEVLOG_DIR, DEVLOG_FILE, and HANDOFF_FILE for the branch currently
+# checked out in $1 (defaults to "."). main/master (any case) and anything
+# that isn't a git repo or has no resolvable branch keep the shared
+# devlog.md / handoff.md. Any other branch gets
+# devlog.<sanitized-branch>.md and handoff.<sanitized-branch>.md; a
+# detached HEAD (or an unborn branch, which git also reports as "HEAD"
+# here) falls back to the working directory's own basename. The first
+# time a branch resolves to a file that doesn't exist yet while
+# devlog.md already has content, the existing devlog.md is renamed (not
+# copied) into that branch's file. handoff.md is never renamed on first
+# resolve (current-state snapshot, not history).
 devlog_resolve_paths() {
   local dir="${1:-.}"
   DEVLOG_DIR="$dir/.devlog"
   DEVLOG_FILE="$DEVLOG_DIR/devlog.md"
+  # shellcheck disable=SC2034 # consumed by callers (e.g. enforce-devlog.sh), not used in this file
+  HANDOFF_FILE="$DEVLOG_DIR/handoff.md"
 
   local branch raw name
   branch="$(git -C "$dir" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')"
@@ -67,4 +72,6 @@ devlog_resolve_paths() {
     devlog_lock_release
   fi
   DEVLOG_FILE="$resolved"
+  # shellcheck disable=SC2034 # consumed by callers (e.g. enforce-devlog.sh), not used in this file
+  HANDOFF_FILE="$DEVLOG_DIR/handoff.$name.md"
 }

package/{hooks → core}/scripts/enforce-devlog.sh

@@ -31,13 +31,15 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 . "$SCRIPT_DIR/files-snapshot.sh"
 # shellcheck source=devlog-md.sh
 . "$SCRIPT_DIR/devlog-md.sh"
+# shellcheck source=handoff-file.sh
+. "$SCRIPT_DIR/handoff-file.sh"
 
 # --- loop guard -------------------------------------------------------
 # 有 jq 就用 jq 精準解析；沒有 jq 就退化成字串比對（沒有更嚴謹的 parse，但
 # 足以涵蓋 Claude Code 實際送出的 stop_hook_active 欄位形狀），兩種環境都要生效。
 INPUT="$(cat 2>/dev/null || true)"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 # 沒下過 /devlog-tracker:start，代表這個專案沒啟動強制記錄，直接放行。
 # 這是唯一的判斷依據——不猜這輪是否呼叫了某個 skill，也不解析 transcript。
 # 這個 gate 放在路徑解析之前，沒啟用時就不必付 git rev-parse 的成本；
@@ -89,6 +91,10 @@ TURN_MARKER="$DEVLOG_DIR/.turn-start"
 
 devlog_lock_acquire
 trap 'devlog_lock_release' EXIT
+if [ -n "${LOCK_CONTENDED_BY:-}" ]; then
+  echo "另一個 session（pid ${LOCK_CONTENDED_BY}）目前正在寫 ${DEVLOG_FILE}，稍後再結束這一輪重試一次。" >&2
+  exit 2
+fi
 
 # --- span 檢查（Span Mode：橫跨多次自動續接的長任務）---------------------
 # Claude 主動宣告的 .devlog/.span-open 存在時（見 SKILL.md），這個 tick 不
@@ -550,6 +556,15 @@ ${ACTUAL_DIRTY:-（沒有，工作樹乾淨）}"
       exit 2
     fi
   fi
+
+  # Session Handoff → .devlog/handoff.md（docs/design/session-handoff-file.md）
+  # 放在其他 IN_PROGRESS／BLOCKED 檢查之後，避免搶先蓋掉既有失敗訊息。
+  if [ "$STATUS_VAL" = "IN_PROGRESS" ] || [ "$STATUS_VAL" = "BLOCKED" ]; then
+    if ! handoff_session_section_ok "$LAST_ROUND"; then
+      echo "Status 是 IN_PROGRESS 或 BLOCKED 時，必須有 \`### Session Handoff\`，且依序包含 \`#### 決策\`／\`#### 待解問題\`／\`#### 失敗嘗試\`（可寫 \`- （無）\`）。寫完後 hook 會覆寫 .devlog/handoff.md 給下一 session。" >&2
+      exit 2
+    fi
+  fi
 fi
 
 rm -f "$DEVLOG_DIR/.workspace-mismatch" 2>/dev/null || true
@@ -573,6 +588,16 @@ rm -f "$DEVLOG_DIR/.workspace-mismatch" 2>/dev/null || true
 if [ -n "$LAST_ROUND" ]; then
   if devlog_merge_round_current "$DEVLOG_FILE" "$ROUND_CURRENT"; then
     rm -f "$DEVLOG_DIR/.round-open" 2>/dev/null || true
+    case "${STATUS_VAL:-}" in
+      IN_PROGRESS|BLOCKED)
+        handoff_write "$HANDOFF_FILE" "$LAST_ROUND" 2>/dev/null || \
+          echo "警告：無法寫入 Session Handoff 檔（$HANDOFF_FILE），本輪仍已收尾。" >&2
+        ;;
+      DONE)
+        handoff_clear "$HANDOFF_FILE" 2>/dev/null || \
+          echo "警告：無法清除 Session Handoff 檔（$HANDOFF_FILE），本輪仍已收尾。" >&2
+        ;;
+    esac
   fi
 else
   rm -f "$DEVLOG_DIR/.round-open" 2>/dev/null || true

package/core/scripts/handoff-file.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Sourced helper: validate / extract / write / clear Session Handoff file.
+# See docs/design/session-handoff-file.md.
+
+# Odd ``` count → treat as no fence (same fail-open as enforce-devlog.sh).
+_handoff_nofence_flag() {
+  local blob="$1" n
+  n="$(printf '%s\n' "$blob" | grep -c '^[ \t]*```' 2>/dev/null || echo 0)"
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  if [ $((n % 2)) -eq 1 ]; then
+    echo 1
+  else
+    echo 0
+  fi
+}
+
+# Returns 0 if $1 (a Round blob) has ### Session Handoff with #### 決策 /
+# #### 待解問題 / #### 失敗嘗試 in that order, each with a non-empty body.
+handoff_session_section_ok() {
+  local blob="$1" nofence
+  nofence="$(_handoff_nofence_flag "$blob")"
+  printf '%s\n' "$blob" | awk -v nofence="$nofence" '
+    BEGIN { ok = 0 }
+    /^[ \t]*```/ { if (!nofence) fence = !fence; next }
+    fence { next }
+    /^### Session Handoff[ \t]*$/ { in_sh = 1; next }
+    in_sh && /^### / { exit }
+    in_sh && /^## / { exit }
+    in_sh && /^#### / {
+      name = $0
+      sub(/^#### [ \t]*/, "", name)
+      sub(/[ \t]+$/, "", name)
+      if (name == "決策" || name == "待解問題" || name == "失敗嘗試") {
+        if (expecting_body) { exit }
+        if (name == "決策") {
+          if (seen_decision || seen_open || seen_failed) exit
+          seen_decision = 1
+          expecting_body = 1
+        } else if (name == "待解問題") {
+          if (!seen_decision || seen_open || seen_failed) exit
+          seen_open = 1
+          expecting_body = 1
+        } else {
+          if (!seen_decision || !seen_open || seen_failed) exit
+          seen_failed = 1
+          expecting_body = 1
+        }
+      }
+      next
+    }
+    in_sh && expecting_body {
+      if ($0 ~ /[^[:space:]]/) {
+        expecting_body = 0
+        if (seen_decision && seen_open && seen_failed) ok = 1
+      }
+      next
+    }
+    END { exit(ok && seen_decision && seen_open && seen_failed && !expecting_body ? 0 : 1) }
+  '
+}
+
+# Print independent-file markdown from Round blob $1. Exit 1 if invalid.
+handoff_extract_file_body() {
+  local blob="$1" nofence
+  handoff_session_section_ok "$blob" || return 1
+  nofence="$(_handoff_nofence_flag "$blob")"
+  printf '%s\n' "$blob" | awk -v nofence="$nofence" '
+    BEGIN { print "## Session Handoff"; print "" }
+    /^[ \t]*```/ { if (!nofence) fence = !fence; next }
+    fence { next }
+    /^### Session Handoff[ \t]*$/ { in_sh = 1; next }
+    in_sh && /^### / { exit }
+    in_sh && /^## / { exit }
+    in_sh && /^#### / {
+      name = $0
+      sub(/^#### [ \t]*/, "", name)
+      sub(/[ \t]+$/, "", name)
+      if (name == "決策" || name == "待解問題" || name == "失敗嘗試") {
+        if (printing) print ""
+        print "### " name
+        printing = 1
+        grab = 1
+        next
+      }
+      grab = 0
+      next
+    }
+    in_sh && grab { print }
+  '
+}
+
+# Atomic write of extracted body to $1 from Round blob $2.
+handoff_write() {
+  local path="$1" blob="$2" dir tmp body
+  body="$(handoff_extract_file_body "$blob")" || return 1
+  dir="$(dirname "$path")"
+  mkdir -p "$dir" 2>/dev/null || true
+  tmp="$(mktemp "$dir/.handoff.XXXXXX")" || return 1
+  printf '%s\n' "$body" > "$tmp" || { rm -f "$tmp"; return 1; }
+  mv "$tmp" "$path" || { rm -f "$tmp"; return 1; }
+  return 0
+}
+
+handoff_clear() {
+  rm -f "$1"
+}

package/{hooks → core}/scripts/keep-move.sh

@@ -33,7 +33,7 @@ NAME="$(slugify "$NAME")"
   || { echo "檔名無效" >&2; exit 1; }
 [ "${#NAME}" -le 64 ] || { echo "檔名超過 64 字元" >&2; exit 1; }
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_lock_acquire
 trap 'devlog_lock_release' EXIT
 MAIN="$DEVLOG_FILE"

package/{hooks → core}/scripts/kept-list.sh

@@ -13,7 +13,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-path.sh
 . "$SCRIPT_DIR/devlog-path.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 MAIN="$DEVLOG_FILE"
 

package/core/scripts/lessons-advisory-state.sh

@@ -0,0 +1,51 @@
+# shellcheck shell=bash
+# Sourced by round-start.sh / lessons-on.sh / lessons-drift-set.sh. Owns the shared
+# `.lessons-advisory-state` file (docs/design/lessons-mode.md 「機制性訊號：
+# 共用計數器」): a `count`/`threshold` pair fed by more than one mechanical
+# signal (workspace drift, accumulated BLOCKED rounds), so the file and
+# function names are signal-agnostic rather than "drift"-specific.
+_lessons_advisory_state_src="${BASH_SOURCE[0]}"
+_LESSONS_ADVISORY_STATE_DIR="$(cd "${_lessons_advisory_state_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$_LESSONS_ADVISORY_STATE_DIR/json-field.sh"
+
+# One-time migration from the old, drift-only file name/fields. No-op unless
+# the old file exists and the new one doesn't; safe to call on every
+# invocation (idempotent, cheap after the first migration).
+lessons_advisory_migrate() {
+  local devlog_dir="$1"
+  local old="$devlog_dir/.lessons-drift-state"
+  local new="$devlog_dir/.lessons-advisory-state"
+  [ -f "$new" ] && return 0
+  [ -f "$old" ] || return 0
+  local count threshold
+  count="$(json_int_get "$old" mismatch_count)"
+  threshold="$(json_int_get "$old" threshold)"
+  case "$count" in ''|*[!0-9]*) count=0 ;; esac
+  case "$threshold" in ''|*[!0-9]*) threshold=3 ;; esac
+  printf '{"count": %s, "threshold": %s}\n' "$count" "$threshold" > "$new" 2>/dev/null || return 0
+  rm -f "$old" 2>/dev/null || true
+}
+
+# Increments $1 (the advisory-state file, created with defaults if missing),
+# printing the shared advisory line and resetting to 0 once the threshold is
+# reached. Callers call this once per mechanical signal occurrence; a
+# printed line means "surface this to Claude" (round-start.sh's stdout is
+# the only place a non-blocking hook message reaches Claude's context).
+lessons_advisory_bump() {
+  local file="$1" count max newcount
+  if [ ! -f "$file" ]; then
+    printf '%s\n' '{"count": 0, "threshold": 3}' > "$file" 2>/dev/null || true
+  fi
+  count="$(json_int_get "$file" count)"
+  max="$(json_int_get "$file" threshold)"
+  case "$count" in ''|*[!0-9]*) count=0 ;; esac
+  case "$max" in ''|*[!0-9]*) max=3 ;; esac
+  newcount=$((count + 1))
+  if [ "$newcount" -ge "$max" ]; then
+    json_int_set "$file" count 0
+    printf '\n[Lessons Mode 提示] 流程訊號已累積出現 %s 次（門檻 %s）。可考慮用 lessons-append.sh 記一筆流程教訓，非強制。\n' "$newcount" "$max"
+  else
+    json_int_set "$file" count "$newcount"
+  fi
+}

package/{hooks → core}/scripts/lessons-append.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Claude-invoked only (docs/design/lessons-mode.md), never wired into
-# hooks/hooks.json — same posture as keep-move.sh. Appends one free-prose
+# claude/hooks.json — same posture as keep-move.sh. Appends one free-prose
 # entry to .devlog/devlog.lessons.<topic>.md (creating it if new), then
 # rebuilds the trailing "## Lessons 索引" block in devlog.md.
 set -uo pipefail
@@ -26,7 +26,7 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 MAIN="$DEVLOG_FILE"
 
@@ -52,8 +52,10 @@ trap 'devlog_lock_release' EXIT
 TARGET="$DEVLOG_DIR/devlog.lessons.$TOPIC.md"
 TS="$(date -Iseconds 2>/dev/null || date '+%Y-%m-%dT%H:%M:%S%z')"
 
+IS_NEW_TOPIC=0
 if [ ! -f "$TARGET" ]; then
   printf '# Lessons: %s\n\n- source: `.devlog/devlog.md`\n' "$TOPIC" > "$TARGET" || exit 1
+  IS_NEW_TOPIC=1
 fi
 {
   printf '\n## %s\n' "$TS"
@@ -66,6 +68,7 @@ fi
 # heading in that file, truncated at the first 。/. (whichever comes
 # first); no truncation if neither appears.
 INDEX_LINES=""
+OTHER_TOPICS=""
 shopt -s nullglob
 for f in "$DEVLOG_DIR"/devlog.lessons.*.md; do
   [ -f "$f" ] || continue
@@ -73,6 +76,13 @@ for f in "$DEVLOG_DIR"/devlog.lessons.*.md; do
   n="$(grep -c '^## ' "$f" 2>/dev/null || echo 0)"
   case "$n" in ''|*[!0-9]*) n=0 ;; esac
   [ "$n" -gt 0 ] || continue
+  if [ "$leaf" = "devlog.lessons.$TOPIC.md" ]; then
+    THIS_TOPIC_COUNT="$n"
+  else
+    OTHER_TOPIC_NAME="${leaf#devlog.lessons.}"
+    OTHER_TOPIC_NAME="${OTHER_TOPIC_NAME%.md}"
+    OTHER_TOPICS="${OTHER_TOPICS:+$OTHER_TOPICS, }${OTHER_TOPIC_NAME}"
+  fi
   last_ln="$(grep -n '^## ' "$f" | tail -1 | cut -d: -f1)"
   updated_at="$(sed -n "${last_ln}p" "$f" | sed -E 's/^## //')"
   title="$(awk -v start="$last_ln" 'NR>start && $0 ~ /[^[:space:]]/ {print; exit}' "$f")"
@@ -91,3 +101,9 @@ devlog_strip_lessons_index "$MAIN" "$STRIPPED"
 } > "$STRIPPED.new" && mv "$STRIPPED.new" "$MAIN" || exit 1
 
 printf 'PATH=.devlog/devlog.lessons.%s.md\n' "$TOPIC"
+if [ -n "${THIS_TOPIC_COUNT:-}" ] && [ $((THIS_TOPIC_COUNT % 3)) -eq 0 ]; then
+  printf '[Lessons Mode 提示] 這個主題已經累積 %s 則。可考慮升級成 docs/design/*.md 的正式決策，不強制。\n' "$THIS_TOPIC_COUNT"
+fi
+if [ "$IS_NEW_TOPIC" -eq 1 ] && [ -n "${OTHER_TOPICS:-}" ]; then
+  printf 'NEW_TOPIC。既有主題：%s（如果內容其實屬於這些主題之一，改用 --topic 該名稱重跑，避免同一件事分裂成兩個檔案）。\n' "$OTHER_TOPICS"
+fi