devlog-tracker 0.27.0 → 0.30.0

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/core/scripts/lessons-append.sh

@@ -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

package/core/scripts/lessons-drift-set.sh

@@ -1,15 +1,18 @@
 #!/usr/bin/env bash
 # User-invoked: /devlog-tracker:lessons-drift filesystem side.
-# Sets the workspace-drift nudge's threshold (docs/design/lessons-mode.md
-# 「機制性訊號：工作區漂移重複發生」): how many cumulative 工作區-mismatch
-# occurrences (round-start.sh) before printing one advisory suggestion to
-# write a Lessons Mode entry. Nested under Lessons Mode, which is itself
-# nested under the main switch. $1 is required: a positive integer.
+# Sets the shared advisory-signal threshold (docs/design/lessons-mode.md
+# 「機制性訊號：共用計數器」): how many cumulative occurrences — workspace-
+# drift mismatches or accumulated BLOCKED rounds (both round-start.sh) —
+# before printing one advisory suggestion to write a Lessons Mode entry.
+# Nested under Lessons Mode, which is itself nested under the main switch.
+# $1 is required: a positive integer.
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=json-field.sh
 . "$SCRIPT_DIR/json-field.sh"
+# shellcheck source=lessons-advisory-state.sh
+. "$SCRIPT_DIR/lessons-advisory-state.sh"
 
 PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
@@ -31,12 +34,13 @@ case "$COUNT_ARG" in
     ;;
 esac
 
-if [ -f "$DEVLOG_DIR/.lessons-drift-state" ]; then
-  json_int_set "$DEVLOG_DIR/.lessons-drift-state" threshold "$COUNT_ARG"
+lessons_advisory_migrate "$DEVLOG_DIR"
+if [ -f "$DEVLOG_DIR/.lessons-advisory-state" ]; then
+  json_int_set "$DEVLOG_DIR/.lessons-advisory-state" threshold "$COUNT_ARG"
 else
-  printf '%s\n' "{\"mismatch_count\": 0, \"threshold\": ${COUNT_ARG}}" \
-    > "$DEVLOG_DIR/.lessons-drift-state" || exit 1
+  printf '%s\n' "{\"count\": 0, \"threshold\": ${COUNT_ARG}}" \
+    > "$DEVLOG_DIR/.lessons-advisory-state" || exit 1
 fi
 
-echo "LESSONS_DRIFT_THRESHOLD=$(json_int_get "$DEVLOG_DIR/.lessons-drift-state" threshold)"
+echo "LESSONS_DRIFT_THRESHOLD=$(json_int_get "$DEVLOG_DIR/.lessons-advisory-state" threshold)"
 exit 0

package/core/scripts/lessons-on.sh

@@ -4,6 +4,10 @@
 # disable」): refuses if .enabled is absent, since there is no Round/Status
 # history to detect a BLOCKED->resolved transition against.
 set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=lessons-advisory-state.sh
+. "$SCRIPT_DIR/lessons-advisory-state.sh"
 PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
@@ -13,9 +17,10 @@ fi
 if [ ! -f "$DEVLOG_DIR/.lessons-enabled" ]; then
   date -Iseconds > "$DEVLOG_DIR/.lessons-enabled" 2>/dev/null || echo enabled > "$DEVLOG_DIR/.lessons-enabled"
 fi
-if [ ! -f "$DEVLOG_DIR/.lessons-drift-state" ]; then
-  printf '%s\n' '{"mismatch_count": 0, "threshold": 3}' \
-    > "$DEVLOG_DIR/.lessons-drift-state" 2>/dev/null || true
+lessons_advisory_migrate "$DEVLOG_DIR"
+if [ ! -f "$DEVLOG_DIR/.lessons-advisory-state" ]; then
+  printf '%s\n' '{"count": 0, "threshold": 3}' \
+    > "$DEVLOG_DIR/.lessons-advisory-state" 2>/dev/null || true
 fi
 echo "LESSONS_ENABLED=$DEVLOG_DIR/.lessons-enabled"
 exit 0

package/core/scripts/lessons-subagent-done.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# PostToolUse hook（Claude Code，matcher Agent|Task）：前景 sub agent 跑完、
+# 結果回到主 session 時，Lessons Mode 開著就用 additionalContext 提示主
+# session 檢查 sub agent 訊號（docs/design/lessons-mode.md「sub agent／
+# workflow 情境」）。背景 agent 在這裡只是剛啟動（tool_response.status 為
+# async_launched），完成時改由 round-start.sh 的 task-notification 分支提示，
+# 這裡略過；sub agent 自己再派 agent（payload 帶 agent_id）也略過。
+# fail-open：任何問題都 exit 0、不輸出。
+
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$HOOKS_DIR/json-field.sh"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+[ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
+[ -f "$PROJECT_DIR/.devlog/.lessons-enabled" ] || exit 0
+
+INPUT="$(cat 2>/dev/null || true)"
+[ -n "$(json_str_field "$INPUT" agent_id)" ] && exit 0
+
+ASYNC=0
+if command -v jq >/dev/null 2>&1; then
+  if printf '%s' "$INPUT" | jq -e '(.tool_response.status? == "async_launched") or (.tool_response.isAsync? == true)' >/dev/null 2>&1; then
+    ASYNC=1
+  fi
+else
+  case "$INPUT" in
+    *'"status":"async_launched"'*|*'"isAsync":true'*) ASYNC=1 ;;
+  esac
+fi
+[ "$ASYNC" -eq 1 ] && exit 0
+
+printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"[Lessons Mode 提示] sub agent 完成。讀完回報後檢查：verify 推翻先前的 fix／claim、sub agent 自陳繞路、多個 agent 卡在類似問題、成果被打回票——有的話可考慮用 lessons-append.sh 記一筆（sub agent 若已自己記過就不用重複），非強制。"}}'
+exit 0

package/core/scripts/lessons-subagent-start.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# SubagentStart hook（Claude Code）：Lessons Mode 開著時，把「可以自己呼叫
+# lessons-append.sh」的說明注入 sub agent／Workflow agent 的 context
+# （docs/design/lessons-mode.md「sub agent／workflow 情境」）。
+# sub agent 的 Bash 裡沒有 CLAUDE_PROJECT_DIR，isolation: "worktree" 時 cwd
+# 還是 worktree（沒有 .devlog/），所以專案目錄跟腳本路徑都在這裡寫死成
+# 主專案的絕對路徑。fail-open：任何問題都 exit 0、不輸出。
+
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+[ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
+[ -f "$PROJECT_DIR/.devlog/.lessons-enabled" ] || exit 0
+PROJECT_DIR="$(cd "$PROJECT_DIR" 2>/dev/null && pwd)" || exit 0
+cat >/dev/null 2>&1 || true
+
+MSG="[devlog-tracker Lessons Mode] 這個專案開著 Lessons Mode：記錄開發**過程**踩過的坑（不是架構知識）。如果這次任務中你繞了一大圈才找到對的做法、先前的 fix／claim 被驗證推翻、或卡在某個值得後人避開的坑，可以直接記一筆（非強制，沒有就不用記）：
+
+DEVLOG_PROJECT_DIR='${PROJECT_DIR}' bash '${HOOKS_DIR}/lessons-append.sh' --topic '<kebab-case 主題，2–4 段>' --text '<一段自由散文：卡在哪、怎麼解開、下次怎麼避免>'
+
+路徑都是絕對路徑，在 worktree 裡也照原樣用，不要改成相對路徑。有記的話，在最終回報裡用一句話說明記了哪個主題；腳本回報 NEW_TOPIC 時可改用它列出的既有主題重跑。"
+
+json_escape() {
+  printf '%s' "$1" | awk '
+    BEGIN { ORS = "" }
+    {
+      gsub(/\\/, "\\\\"); gsub(/"/, "\\\""); gsub(/\t/, "\\t"); gsub(/\r/, "\\r")
+      if (NR > 1) print "\\n"
+      print
+    }'
+}
+
+printf '{"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"%s"}}\n' "$(json_escape "$MSG")"
+exit 0

package/core/scripts/round-start.sh

@@ -24,6 +24,8 @@ HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
 . "$HOOKS_DIR/detect-pending-question.sh"
 # shellcheck source=devlog-path.sh
 . "$HOOKS_DIR/devlog-path.sh"
+# shellcheck source=lessons-advisory-state.sh
+. "$HOOKS_DIR/lessons-advisory-state.sh"
 PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 [ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
 devlog_resolve_paths "$PROJECT_DIR"
@@ -33,7 +35,7 @@ CHECKPOINT_FILE="$DEVLOG_DIR/.checkpoint-state"
 SEGMENT_FILE="$DEVLOG_DIR/.segment-state"
 ROUND_OPEN="$DEVLOG_DIR/.round-open"
 AWAITING_FILE="$DEVLOG_DIR/.awaiting-reply"
-DRIFT_FILE="$DEVLOG_DIR/.lessons-drift-state"
+ADVISORY_FILE="$DEVLOG_DIR/.lessons-advisory-state"
 
 devlog_lock_acquire
 trap 'devlog_lock_release' EXIT
@@ -78,6 +80,26 @@ fi
 
 PROMPT="$(json_str_field "$INPUT" prompt)"
 
+# devlog-tracker 自己的純管理指令（讀狀態或操作 devlog 系統本身，不做開發工作）：
+# 這一輪完全不開 Round、不動任何計數器，整輪直接放行，等於這個 tick 沒發生過。
+# 不包含 continue／resume——這兩個會接著做實際開發工作，仍要照常強制記錄。
+# 偵測依據：Claude Code 呼叫 slash command／skill 時，這一輪的 prompt 內容會帶
+# 一個 <command-name> 標籤（本專案這些指令都是以 skill 形式提供給 Claude）。
+# 抓不到就落回正常流程（fail-open，不影響一般訊息）。
+CMD_NAME=""
+case "$PROMPT" in
+  *'<command-name>'*)
+    CMD_NAME="${PROMPT#*<command-name>}"
+    CMD_NAME="${CMD_NAME%%</command-name>*}"
+    CMD_NAME="${CMD_NAME#/}"
+    ;;
+esac
+case "$CMD_NAME" in
+  devlog-tracker:checkpoint|devlog-tracker:clean|devlog-tracker:compact|devlog-tracker:keep|devlog-tracker:lessons|devlog-tracker:lessons-drift|devlog-tracker:lessons-off|devlog-tracker:lessons-on|devlog-tracker:overview|devlog-tracker:pause|devlog-tracker:search|devlog-tracker:segment-watch|devlog-tracker:span|devlog-tracker:start|devlog-tracker:status)
+    exit 0
+    ;;
+esac
+
 # 背景 task-notification（例如子 agent 完成通知）不是使用者真的打字：不留原始
 # XML，換成精簡摘要；也不當成新話題開新 Round，改折進最後一個 Round 當段落。
 TASK_NOTIF=0
@@ -101,6 +123,20 @@ if [ "$TASK_NOTIF" -eq 1 ]; then
   else
     PROMPT="$NOTIF_SUMMARY"
   fi
+
+  # Lessons Mode：背景 sub agent／Workflow 完成時機械提示主 session 檢查
+  # sub agent 訊號（docs/design/lessons-mode.md「sub agent／workflow 情境」）；
+  # failed／killed 另外算進共用計數器。span 開著也照印——長任務正是會派
+  # 背景 agent 的場景。
+  if [ -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+    printf '\n[Lessons Mode 提示] 背景任務完成（status=%s）。讀完回報後檢查：verify 推翻先前的 fix／claim、sub agent 自陳繞路、多個 agent 卡在類似問題、成果被打回票——有的話可考慮用 lessons-append.sh 記一筆（sub agent 若已自己記過就不用重複），非強制。\n' "${NOTIF_STATUS:-unknown}"
+    case "$NOTIF_STATUS" in
+      failed|killed)
+        lessons_advisory_migrate "$DEVLOG_DIR"
+        lessons_advisory_bump "$ADVISORY_FILE"
+        ;;
+    esac
+  fi
 fi
 
 if [ "$SPAN_SKIP" -eq 1 ]; then
@@ -133,21 +169,34 @@ if [ "$SPAN_SKIP" -eq 0 ] && [ "$TASK_NOTIF" -eq 0 ] && [ -f "$DEVLOG_FILE" ]; t
       printf '\n宣稱：\n%s\n\n實際：\n%s\n' "$CLAIMED_WS" "$LIVE_WS"
 
       if [ -f "$DEVLOG_DIR/.lessons-enabled" ]; then
-        if [ ! -f "$DRIFT_FILE" ]; then
-          printf '%s\n' '{"mismatch_count": 0, "threshold": 3}' \
-            > "$DRIFT_FILE" 2>/dev/null || true
-        fi
-        DRIFT_COUNT="$(json_int_get "$DRIFT_FILE" mismatch_count)"
-        DRIFT_MAX="$(json_int_get "$DRIFT_FILE" threshold)"
-        case "$DRIFT_COUNT" in ''|*[!0-9]*) DRIFT_COUNT=0 ;; esac
-        case "$DRIFT_MAX" in ''|*[!0-9]*) DRIFT_MAX=3 ;; esac
-        NEW_DRIFT_COUNT=$((DRIFT_COUNT + 1))
-        if [ "$NEW_DRIFT_COUNT" -ge "$DRIFT_MAX" ]; then
-          json_int_set "$DRIFT_FILE" mismatch_count 0
-          printf '\n[Lessons Mode 提示] 工作區宣稱與實際不符已累積出現 %s 次（門檻 %s）。可考慮用 lessons-append.sh 記一筆流程教訓，非強制。\n' "$NEW_DRIFT_COUNT" "$DRIFT_MAX"
-        else
-          json_int_set "$DRIFT_FILE" mismatch_count "$NEW_DRIFT_COUNT"
-        fi
+        lessons_advisory_migrate "$DEVLOG_DIR"
+        lessons_advisory_bump "$ADVISORY_FILE"
+      fi
+    fi
+  fi
+fi
+
+if [ "$SPAN_SKIP" -eq 0 ] && [ "$TASK_NOTIF" -eq 0 ] && [ -f "$DEVLOG_FILE" ] && [ -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+  BLOCKED_ROUND_STARTS="$(devlog_list_round_starts "$DEVLOG_FILE")"
+  BLOCKED_ROUND_COUNT="$(printf '%s\n' "$BLOCKED_ROUND_STARTS" | grep -c '.' || true)"
+  BLOCKED_LAST_LINE="$(printf '%s\n' "$BLOCKED_ROUND_STARTS" | awk 'END { print }')"
+  BLOCKED_LAST_START="$(printf '%s\n' "$BLOCKED_LAST_LINE" | awk '{ print $1 }')"
+  if [ -n "$BLOCKED_LAST_START" ]; then
+    BLOCKED_LAST_END="$(devlog_block_end "$DEVLOG_FILE" "$BLOCKED_LAST_START")"
+    BLOCKED_LAST_STATUS="$(devlog_round_status "$DEVLOG_FILE" "$BLOCKED_LAST_START" "$BLOCKED_LAST_END")"
+
+    if [ "$BLOCKED_LAST_STATUS" = "BLOCKED" ]; then
+      lessons_advisory_migrate "$DEVLOG_DIR"
+      lessons_advisory_bump "$ADVISORY_FILE"
+    fi
+
+    if [ "$BLOCKED_ROUND_COUNT" -ge 2 ]; then
+      BLOCKED_PREV_LINE="$(printf '%s\n' "$BLOCKED_ROUND_STARTS" | tail -2 | head -1)"
+      BLOCKED_PREV_START="$(printf '%s\n' "$BLOCKED_PREV_LINE" | awk '{ print $1 }')"
+      BLOCKED_PREV_END="$(devlog_block_end "$DEVLOG_FILE" "$BLOCKED_PREV_START")"
+      BLOCKED_PREV_STATUS="$(devlog_round_status "$DEVLOG_FILE" "$BLOCKED_PREV_START" "$BLOCKED_PREV_END")"
+      if [ "$BLOCKED_PREV_STATUS" = "BLOCKED" ] && [ "$BLOCKED_LAST_STATUS" != "BLOCKED" ]; then
+        printf '\n[Lessons Mode 提示] 上一輪從 BLOCKED 解開了。可考慮用 lessons-append.sh 記一筆這次卡在哪、怎麼解開，非強制。\n'
       fi
     fi
   fi

package/core/scripts/search-devlog.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Filesystem side of /devlog-tracker:search <關鍵字>. Plain read only -- no
+# workspace verification, no wait-for-confirmation flow, same posture as
+# overview.md / lessons.md. Greps every devlog*.md file under .devlog/:
+# devlog.md, devlog.archive.md, kept devlog.<name>.md, and
+# devlog.lessons.<topic>.md all match this one glob, so there is no
+# per-file-type logic to keep in sync when a new kind of devlog file is
+# added. Case-insensitive fixed-string match; not fence-aware (a match or a
+# heading inside a ``` block is still reported) -- this is a navigation aid,
+# not a Stop-grade verifier.
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+devlog_resolve_paths "$PROJECT_DIR"
+
+KEYWORD="${1:-}"
+if [ -z "$KEYWORD" ]; then
+  echo "MISSING_KEYWORD" >&2
+  exit 1
+fi
+
+if [ ! -d "$DEVLOG_DIR" ]; then
+  echo "NO_INDEX"
+  exit 0
+fi
+
+shopt -s nullglob
+FILES=("$DEVLOG_DIR"/devlog*.md)
+if [ ${#FILES[@]} -eq 0 ]; then
+  echo "NO_INDEX"
+  exit 0
+fi
+
+FOUND=0
+for f in "${FILES[@]}"; do
+  [ -f "$f" ] || continue
+  leaf="${f##*/}"
+  MATCHES="$(awk -v kw="$KEYWORD" '
+    BEGIN { heading = "" }
+    /^#{2,3} / { heading = $0 }
+    {
+      if (index(tolower($0), tolower(kw)) > 0) {
+        h = heading
+        gsub(/"/, "\\\"", h)
+        printf "HEADING=\"%s\" LINE=%d: %s\n", h, NR, $0
+      }
+    }
+  ' "$f")"
+  if [ -n "$MATCHES" ]; then
+    FOUND=1
+    printf 'FILE=.devlog/%s\n' "$leaf"
+    printf '%s\n' "$MATCHES"
+  fi
+done
+
+if [ "$FOUND" -eq 0 ]; then
+  echo "NO_MATCH"
+fi

package/core/scripts/session-start-devlog.sh

@@ -69,6 +69,13 @@ if [ -f "$SPAN_FILE" ]; then
   fi
 fi
 
+if [ -s "${HANDOFF_FILE:-}" ]; then
+  echo "以下是目前的 Session Handoff 快照（.devlog/${HANDOFF_FILE##*/}；精簡狀態，不是全文）："
+  echo ""
+  cat "$HANDOFF_FILE" 2>/dev/null || true
+  echo ""
+fi
+
 if [ -f "$DEVLOG_FILE" ]; then
   echo "以下是本專案 .devlog/${DEVLOG_FILE##*/} 的接手摘要（不是全文；完整紀錄請自行讀取原檔）："
   echo ""

package/core/scripts/status-devlog.sh

@@ -11,10 +11,10 @@ devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 
 [ -f "$DEVLOG_DIR/.enabled" ] && echo "ENABLED=yes" || echo "ENABLED=no"
 [ -f "$DEVLOG_DIR/.lessons-enabled" ] && echo "LESSONS=yes" || echo "LESSONS=no"
-if [ -f "$DEVLOG_DIR/.lessons-drift-state" ]; then
-  drift_count="$(json_int_get "$DEVLOG_DIR/.lessons-drift-state" mismatch_count)"
-  drift_max="$(json_int_get "$DEVLOG_DIR/.lessons-drift-state" threshold)"
-  printf 'LESSONS_DRIFT=%s/%s\n' "${drift_count:-0}" "${drift_max:-3}"
+if [ -f "$DEVLOG_DIR/.lessons-advisory-state" ]; then
+  advisory_count="$(json_int_get "$DEVLOG_DIR/.lessons-advisory-state" count)"
+  advisory_max="$(json_int_get "$DEVLOG_DIR/.lessons-advisory-state" threshold)"
+  printf 'LESSONS_ADVISORY=%s/%s\n' "${advisory_count:-0}" "${advisory_max:-3}"
 fi
 if [ -f "$DEVLOG_DIR/.span-open" ]; then
   r="$(json_int_get "$DEVLOG_DIR/.span-open" round)"

package/core/scripts/tests/test-clean-devlog.sh

@@ -156,5 +156,17 @@ printf '%s\n' '{"round": 1, "opened_at": "now"}' > "$ENAB/.devlog/.round-open"
 bash "$SCRIPT_DIR/clean-devlog.sh" --confirmed >/dev/null
 [ -f "$ENAB/.devlog/.enabled" ] && echo "PASS: .enabled untouched" || { echo "FAIL: .enabled removed"; FAIL=1; }
 
+# clean removes handoff.md
+HOFF="$TMP/handoffclean"
+mkdir -p "$HOFF/.devlog"
+export CLAUDE_PROJECT_DIR="$HOFF"
+printf '# project\n\n' > "$HOFF/.devlog/devlog.md"
+make_round "$HOFF/.devlog/devlog.md" 1 DONE
+echo "## Session Handoff" > "$HOFF/.devlog/handoff.md"
+bash "$SCRIPT_DIR/clean-devlog.sh" --confirmed >/dev/null
+[ ! -f "$HOFF/.devlog/handoff.md" ] \
+  && echo "PASS: clean removes handoff.md" \
+  || { echo "FAIL: handoff.md survived clean"; FAIL=1; }
+
 if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
 else echo "Some checks FAILED."; exit 1; fi

package/core/scripts/tests/test-devlog-lock.sh

@@ -33,5 +33,44 @@ ln -s "$(command -v bash)" "$MIN_PATH/bash"
 HELD="$(PATH="$MIN_PATH" bash -c '. "$1"; DEVLOG_DIR="$2"; devlog_lock_acquire; echo "${LOCK_HELD:-0}"' _ "$SCRIPT_DIR/devlog-lock.sh" "$DEVLOG_DIR")"
 [ "$HELD" = "0" ] && echo "PASS: missing lock tools fails open" || { echo "FAIL: restricted path held=$HELD"; FAIL=1; }
 
+# Acquire writes its own pid into the lock dir; release removes the whole
+# dir (pid file included), not just an empty rmdir.
+devlog_lock_acquire
+[ -f "$DEVLOG_DIR/.lock/pid" ] && [ "$(cat "$DEVLOG_DIR/.lock/pid")" = "$$" ] \
+  && echo "PASS: acquire writes own pid" || { echo "FAIL: pid file missing/wrong"; FAIL=1; }
+devlog_lock_release
+[ ! -d "$DEVLOG_DIR/.lock" ] && echo "PASS: release removes dir incl. pid file" \
+  || { echo "FAIL: lock dir survives release"; FAIL=1; }
+
+# Stale lock (pid file names a process that is no longer running): reclaimed
+# near-instantly instead of waiting out the full contention timeout.
+mkdir "$DEVLOG_DIR/.lock"
+echo 999999 > "$DEVLOG_DIR/.lock/pid"
+START="$(date +%s)"
+devlog_lock_acquire
+END="$(date +%s)"
+ELAPSED=$((END - START))
+[ "${LOCK_HELD:-0}" -eq 1 ] && [ "$ELAPSED" -le 1 ] \
+  && echo "PASS: stale lock reclaimed fast" || { echo "FAIL: stale reclaim held=$LOCK_HELD elapsed=$ELAPSED"; FAIL=1; }
+devlog_lock_release
+
+# Live contention (pid file names a still-running process): fails open after
+# the timeout as before, but now reports who is holding it.
+sleep 5 &
+LIVE_PID=$!
+mkdir "$DEVLOG_DIR/.lock"
+echo "$LIVE_PID" > "$DEVLOG_DIR/.lock/pid"
+START="$(date +%s)"
+devlog_lock_acquire
+END="$(date +%s)"
+ELAPSED=$((END - START))
+[ "${LOCK_HELD:-0}" -eq 0 ] && [ "$ELAPSED" -ge 2 ] && [ "$ELAPSED" -le 3 ] \
+  && [ "${LOCK_CONTENDED_BY:-}" = "$LIVE_PID" ] \
+  && echo "PASS: live contention reports holder pid" \
+  || { echo "FAIL: live contention held=$LOCK_HELD elapsed=$ELAPSED by=${LOCK_CONTENDED_BY:-}"; FAIL=1; }
+kill "$LIVE_PID" 2>/dev/null || true
+wait "$LIVE_PID" 2>/dev/null || true
+rm -rf "$DEVLOG_DIR/.lock"
+
 if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
 else echo "Some checks FAILED."; exit 1; fi

package/core/scripts/tests/test-devlog-path.sh

@@ -114,5 +114,49 @@ else
   FAIL=1
 fi
 
+# --- HANDOFF_FILE mirrors DEVLOG_FILE naming (no rename migration) --------
+devlog_resolve_paths "$NONGIT"
+[ "$HANDOFF_FILE" = "$NONGIT/.devlog/handoff.md" ] \
+  && echo "PASS: non-git HANDOFF_FILE is handoff.md" \
+  || { echo "FAIL: non-git HANDOFF_FILE=$HANDOFF_FILE"; FAIL=1; }
+
+devlog_resolve_paths "$MAINREPO"
+[ "$HANDOFF_FILE" = "$MAINREPO/.devlog/handoff.md" ] \
+  && echo "PASS: main HANDOFF_FILE is handoff.md" \
+  || { echo "FAIL: main HANDOFF_FILE=$HANDOFF_FILE"; FAIL=1; }
+
+devlog_resolve_paths "$FEATREPO"
+[ "$HANDOFF_FILE" = "$FEATREPO/.devlog/handoff.feature-x.md" ] \
+  && echo "PASS: feature HANDOFF_FILE is handoff.feature-x.md" \
+  || { echo "FAIL: feature HANDOFF_FILE=$HANDOFF_FILE"; FAIL=1; }
+
+devlog_resolve_paths "$SLASHREPO"
+[ "$HANDOFF_FILE" = "$SLASHREPO/.devlog/handoff.feature-foo.md" ] \
+  && echo "PASS: slash branch HANDOFF_FILE sanitized" \
+  || { echo "FAIL: slash HANDOFF_FILE=$HANDOFF_FILE"; FAIL=1; }
+
+devlog_resolve_paths "$DETACHEDREPO"
+[ "$HANDOFF_FILE" = "$DETACHEDREPO/.devlog/handoff.detached-repo.md" ] \
+  && echo "PASS: detached HANDOFF_FILE uses worktree dirname" \
+  || { echo "FAIL: detached HANDOFF_FILE=$HANDOFF_FILE"; FAIL=1; }
+
+# migration must NOT move handoff.md
+MIGHO="$TMP/mighandoff"
+mkdir -p "$MIGHO/.devlog"
+: > "$MIGHO/.devlog/.enabled"
+git_setup "$MIGHO"
+git -C "$MIGHO" checkout -q -b feature-h
+echo "old handoff" > "$MIGHO/.devlog/handoff.md"
+echo "## Round 1" > "$MIGHO/.devlog/devlog.md"
+devlog_resolve_paths "$MIGHO"
+if [ -f "$MIGHO/.devlog/handoff.md" ] \
+  && [ ! -f "$MIGHO/.devlog/handoff.feature-h.md" ] \
+  && [ "$HANDOFF_FILE" = "$MIGHO/.devlog/handoff.feature-h.md" ]; then
+  echo "PASS: handoff.md is not renamed on first branch resolve"
+else
+  echo "FAIL: handoff migration diverged (HANDOFF_FILE=$HANDOFF_FILE)"
+  FAIL=1
+fi
+
 if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
 else echo "Some checks FAILED."; exit 1; fi

package/core/scripts/tests/test-enforce-devlog-files.sh

@@ -80,6 +80,17 @@ write_round() {
       echo "observable done via test."
       echo "#### 下一步"
       echo "edit hooks/scripts/enforce-devlog.sh"
+      echo ""
+      echo "### Session Handoff"
+      echo ""
+      echo "#### 決策"
+      echo "- （無）"
+      echo ""
+      echo "#### 待解問題"
+      echo "- fixture open"
+      echo ""
+      echo "#### 失敗嘗試"
+      echo "- （無）"
     fi
     echo ""
     echo "### Status"