devlog-tracker 0.25.1 → 0.29.2

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

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# User-invoked: /devlog-tracker:lessons-drift filesystem side.
+# 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"
+
+if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
+  echo "NOT_STARTED"
+  exit 0
+fi
+if [ ! -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+  echo "LESSONS_NOT_ENABLED"
+  exit 0
+fi
+
+COUNT_ARG="${1:-}"
+case "$COUNT_ARG" in
+  ''|*[!0-9]*|0)
+    echo "threshold must be a positive integer number of occurrences, got: $COUNT_ARG" >&2
+    exit 1
+    ;;
+esac
+
+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' "{\"count\": 0, \"threshold\": ${COUNT_ARG}}" \
+    > "$DEVLOG_DIR/.lessons-advisory-state" || exit 1
+fi
+
+echo "LESSONS_DRIFT_THRESHOLD=$(json_int_get "$DEVLOG_DIR/.lessons-advisory-state" threshold)"
+exit 0

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

@@ -4,7 +4,7 @@
 # or the "## Lessons 索引" block (docs/design/lessons-mode.md), same
 # non-destructive posture as pause-devlog.sh toward devlog.md.
 set -uo pipefail
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 if [ ! -f "$DEVLOG_DIR/.lessons-enabled" ]; then
   echo "NOT_ENABLED"

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

@@ -4,7 +4,11 @@
 # disable」): refuses if .enabled is absent, since there is no Round/Status
 # history to detect a BLOCKED->resolved transition against.
 set -uo pipefail
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+_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
   echo "NOT_ENABLED"
@@ -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/{hooks → core}/scripts/lessons-read.sh

@@ -14,7 +14,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/{hooks → core}/scripts/on-tool-failure.sh

@@ -2,7 +2,7 @@
 # PostToolUseFailure: remember user Esc so Stop can stamp without blocking.
 set -uo pipefail
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 ENABLED_FLAG="$DEVLOG_DIR/.enabled"
 [ -f "$ENABLED_FLAG" ] || exit 0

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 set -uo pipefail
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
   echo "NOT_ENABLED"

package/core/scripts/project-dir.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Sourced helper: the single documented definition of "which project
+# directory is a hook/script operating in". Precedence:
+#   1. DEVLOG_PROJECT_DIR — neutral name, harness-agnostic
+#   2. CLAUDE_PROJECT_DIR — Claude Code's own variable, kept as a
+#      compatibility fallback so anything that already exports it
+#      (Claude Code itself, or an external script) keeps working
+#      unmodified
+#   3. "." — current directory, when neither is set
+#
+# Most core/scripts/*.sh scripts inline the equivalent expression
+# (`${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}`) directly rather than
+# sourcing this file, to keep each entry-point script a single self-
+# contained line. This file is the canonical statement of that precedence
+# and is exercised by core/scripts/tests/test-project-dir.sh; source it
+# instead of re-deriving the fallback chain in new code.
+devlog_project_dir() {
+  printf '%s\n' "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+}

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

@@ -20,7 +20,7 @@ NAME="$(slugify "$NAME")"
 [ -n "$NAME" ] && [ "$NAME" != "archive" ] && [ "${#NAME}" -le 64 ] \
   || { echo "INVALID_NAME" >&2; exit 1; }
 
-DEVLOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.devlog"
+DEVLOG_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}/.devlog"
 FILE="$DEVLOG_DIR/devlog.$NAME.md"
 if [ ! -f "$FILE" ]; then
   candidates=""

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

@@ -24,7 +24,9 @@ HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
 . "$HOOKS_DIR/detect-pending-question.sh"
 # shellcheck source=devlog-path.sh
 . "$HOOKS_DIR/devlog-path.sh"
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# 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"
 ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"
@@ -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
@@ -133,21 +155,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/{hooks → core}/scripts/run-tests.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Run every hook self-check. Usage: bash hooks/scripts/run-tests.sh
+# Run every hook self-check. Usage: bash core/scripts/run-tests.sh
 set -uo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 FAIL=0

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/{hooks → core}/scripts/segment-watch-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/segment-watch.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:-.}}"
 [ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
 devlog_resolve_paths "$PROJECT_DIR"
 ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"

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

@@ -33,7 +33,7 @@ HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-path.sh
 . "$HOOKS_DIR/devlog-path.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"
 SPAN_FILE="$DEVLOG_DIR/.span-open"
@@ -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/{hooks → core}/scripts/span-close.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 set -uo pipefail
-DEVLOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.devlog"
+DEVLOG_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}/.devlog"
 if [ ! -e "$DEVLOG_DIR/.span-open" ]; then
   echo "NOT_OPEN"
   exit 0

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

@@ -6,7 +6,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 . "$SCRIPT_DIR/devlog-md.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" >&2; exit 1; }
 [ ! -e "$DEVLOG_DIR/.span-open" ] || { echo "ALREADY_OPEN" >&2; exit 1; }
 ROUND=""

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # User-invoked: /devlog-tracker:start filesystem side.
 set -uo pipefail
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 mkdir -p "$DEVLOG_DIR" || exit 1
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then

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

@@ -6,15 +6,15 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 . "$SCRIPT_DIR/devlog-md.sh"
 . "$SCRIPT_DIR/devlog-path.sh"
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 [ -d "$DEVLOG_DIR" ] || { echo "NOT_STARTED"; exit 0; }
 
 [ -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/{hooks → 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-cli-init-e2e.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAIL=0
+
+command -v node >/dev/null 2>&1 || { echo "SKIP: node not installed"; exit 0; }
+
+PROJECT="$TMP/project"
+mkdir -p "$PROJECT"
+
+cd "$PROJECT" || exit 1
+NODE_BIN="$(command -v node)"
+"$NODE_BIN" "$REPO_ROOT/bin/devlog-tracker.js" init --claude --codex --cursor >/dev/null 2>"$TMP/stderr" \
+  || { echo "FAIL: init exited non-zero"; cat "$TMP/stderr"; FAIL=1; }
+
+[ -f "$PROJECT/.devlog-tracker/VERSION" ] && echo "PASS: vendored VERSION exists" || { echo "FAIL: no VERSION"; FAIL=1; }
+[ -f "$PROJECT/.devlog-tracker/env.sh" ] && echo "PASS: vendored env.sh exists" || { echo "FAIL: no env.sh"; FAIL=1; }
+[ -f "$PROJECT/.claude/settings.local.json" ] && echo "PASS: .claude/settings.local.json written" || { echo "FAIL: no .claude/settings.local.json"; FAIL=1; }
+[ -f "$PROJECT/.claude/skills/devlog-start/SKILL.md" ] && echo "PASS: Claude start skill written" || { echo "FAIL: no Claude start skill"; FAIL=1; }
+[ -f "$PROJECT/CLAUDE.md" ] && grep -q 'devlog-tracker:begin' "$PROJECT/CLAUDE.md" \
+  && echo "PASS: CLAUDE.md fallback block written" || { echo "FAIL: no devlog-tracker block in CLAUDE.md"; FAIL=1; }
+[ -f "$PROJECT/.codex/hooks.json" ] && echo "PASS: .codex/hooks.json written" || { echo "FAIL: no .codex/hooks.json"; FAIL=1; }
+[ -f "$PROJECT/.agents/skills/devlog-start/SKILL.md" ] && echo "PASS: Codex start skill written" || { echo "FAIL: no Codex start skill"; FAIL=1; }
+[ -f "$PROJECT/.cursor/hooks.json" ] && echo "PASS: .cursor/hooks.json written" || { echo "FAIL: no .cursor/hooks.json"; FAIL=1; }
+
+# Controller addition 1a: Check vendored core scripts exist
+[ -f "$PROJECT/.devlog-tracker/core/scripts/enforce-devlog.sh" ] && echo "PASS: vendored core/scripts/enforce-devlog.sh exists" || { echo "FAIL: no core/scripts/enforce-devlog.sh"; FAIL=1; }
+[ -f "$PROJECT/.devlog-tracker/claude/hooks.json" ] && echo "PASS: vendored claude/hooks.json exists" || { echo "FAIL: no claude/hooks.json"; FAIL=1; }
+
+# Controller addition 1b: Check merged Claude hook commands are resolved (no placeholders)
+if grep -q '\${CLAUDE_PLUGIN_ROOT\|${DEVLOG_TRACKER_ROOT' "$PROJECT/.claude/settings.local.json"; then
+  echo "FAIL: unresolved placeholders in .claude/settings.local.json"; FAIL=1
+else
+  echo "PASS: no unresolved placeholders in .claude/settings.local.json"
+fi
+
+# Verify that Stop hook command references .devlog-tracker/core/scripts/
+STOP_CMD=$("$NODE_BIN" -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.claude/settings.local.json')).hooks.Stop[0].hooks[0].command)")
+if echo "$STOP_CMD" | grep -q '\.devlog-tracker/core/scripts/enforce-devlog\.sh'; then
+  echo "PASS: Claude Stop hook references .devlog-tracker/core/scripts/enforce-devlog.sh"
+else
+  echo "FAIL: Claude Stop hook does not reference .devlog-tracker/core/scripts/enforce-devlog.sh"; FAIL=1
+fi
+
+# re-running must not duplicate entries
+COUNT_BEFORE_CODEX=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.codex/hooks.json')).hooks.Stop.length)")
+COUNT_BEFORE_CLAUDE=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.claude/settings.local.json')).hooks.Stop.length)")
+"$NODE_BIN" "$REPO_ROOT/bin/devlog-tracker.js" init --claude --codex --cursor >/dev/null 2>"$TMP/stderr" \
+  || { echo "FAIL: second init exited non-zero"; cat "$TMP/stderr"; FAIL=1; }
+COUNT_AFTER_CODEX=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.codex/hooks.json')).hooks.Stop.length)")
+COUNT_AFTER_CLAUDE=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.claude/settings.local.json')).hooks.Stop.length)")
+if [ "$COUNT_BEFORE_CODEX" = "$COUNT_AFTER_CODEX" ]; then
+  echo "PASS: re-running init does not duplicate Codex hook entries"
+else
+  echo "FAIL: Codex hook entries duplicated ($COUNT_BEFORE_CODEX -> $COUNT_AFTER_CODEX)"; FAIL=1
+fi
+if [ "$COUNT_BEFORE_CLAUDE" = "$COUNT_AFTER_CLAUDE" ]; then
+  echo "PASS: re-running init does not duplicate Claude hook entries"
+else
+  echo "FAIL: Claude hook entries duplicated ($COUNT_BEFORE_CLAUDE -> $COUNT_AFTER_CLAUDE)"; 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-devlog-lock.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+. "$SCRIPT_DIR/devlog-lock.sh"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+DEVLOG_DIR="$TMP/.devlog"
+mkdir -p "$DEVLOG_DIR"
+FAIL=0
+
+devlog_lock_acquire
+[ "${LOCK_HELD:-0}" -eq 1 ] && [ -d "$DEVLOG_DIR/.lock" ] \
+  && echo "PASS: acquired" || { echo "FAIL: acquire"; FAIL=1; }
+mkdir "$DEVLOG_DIR/.lock" >/dev/null 2>&1
+[ "$?" -ne 0 ] && echo "PASS: second mkdir excluded" || { echo "FAIL: duplicate mkdir"; FAIL=1; }
+devlog_lock_release
+devlog_lock_acquire
+[ "${LOCK_HELD:-0}" -eq 1 ] && echo "PASS: reacquired after release" || { echo "FAIL: reacquire"; FAIL=1; }
+devlog_lock_release
+
+mkdir "$DEVLOG_DIR/.lock"
+START="$(date +%s)"
+devlog_lock_acquire
+END="$(date +%s)"
+ELAPSED=$((END - START))
+[ "${LOCK_HELD:-0}" -eq 0 ] && [ "$ELAPSED" -ge 2 ] && [ "$ELAPSED" -le 3 ] \
+  && echo "PASS: contention fails open" || { echo "FAIL: contention held=$LOCK_HELD elapsed=$ELAPSED"; FAIL=1; }
+rmdir "$DEVLOG_DIR/.lock"
+
+MIN_PATH="$TMP/min-path"
+mkdir "$MIN_PATH"
+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/{hooks → 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/{hooks → 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"