devlog-tracker 0.25.1 → 0.29.2

package/{hooks → core}/scripts/tests/test-lessons-drift-set.sh

@@ -14,23 +14,32 @@ OUT="$(CLAUDE_PROJECT_DIR="$TMP" bash "$SCRIPT_DIR/lessons-drift-set.sh" 5)"
 [ "$OUT" = "LESSONS_NOT_ENABLED" ] && echo "PASS: lessons not enabled" || { echo "FAIL: $OUT"; FAIL=1; }
 
 touch "$TMP/.devlog/.lessons-enabled"
-printf '%s\n' '{"mismatch_count": 2, "threshold": 3}' > "$TMP/.devlog/.lessons-drift-state"
+printf '%s\n' '{"count": 2, "threshold": 3}' > "$TMP/.devlog/.lessons-advisory-state"
 
 OUT="$(CLAUDE_PROJECT_DIR="$TMP" bash "$SCRIPT_DIR/lessons-drift-set.sh" 5)"
 case "$OUT" in *LESSONS_DRIFT_THRESHOLD=5*) echo "PASS: set 5" ;; *) echo "FAIL: $OUT"; FAIL=1 ;; esac
-grep -q '"mismatch_count": 2' "$TMP/.devlog/.lessons-drift-state" \
+grep -q '"count": 2' "$TMP/.devlog/.lessons-advisory-state" \
   && echo "PASS: count preserved" || { echo "FAIL: count reset"; FAIL=1; }
-grep -q '"threshold": 5' "$TMP/.devlog/.lessons-drift-state" \
+grep -q '"threshold": 5' "$TMP/.devlog/.lessons-advisory-state" \
   && echo "PASS: threshold written" || { echo "FAIL: threshold"; FAIL=1; }
 
 CLAUDE_PROJECT_DIR="$TMP" bash "$SCRIPT_DIR/lessons-drift-set.sh" 0 >/dev/null 2>&1
 [ $? -eq 1 ] && echo "PASS: reject 0" || { echo "FAIL: accepted 0"; FAIL=1; }
 
-rm -f "$TMP/.devlog/.lessons-drift-state"
+rm -f "$TMP/.devlog/.lessons-advisory-state"
 OUT="$(CLAUDE_PROJECT_DIR="$TMP" bash "$SCRIPT_DIR/lessons-drift-set.sh" 7)"
 case "$OUT" in *LESSONS_DRIFT_THRESHOLD=7*) echo "PASS: create 7" ;; *) echo "FAIL: create $OUT"; FAIL=1 ;; esac
-grep -q '"mismatch_count": 0' "$TMP/.devlog/.lessons-drift-state" \
+grep -q '"count": 0' "$TMP/.devlog/.lessons-advisory-state" \
   && echo "PASS: create count 0" || { echo "FAIL: create count"; FAIL=1; }
 
+# --- migrates an old .lessons-drift-state before applying the new threshold
+rm -f "$TMP/.devlog/.lessons-advisory-state"
+printf '%s\n' '{"mismatch_count": 4, "threshold": 3}' > "$TMP/.devlog/.lessons-drift-state"
+OUT="$(CLAUDE_PROJECT_DIR="$TMP" bash "$SCRIPT_DIR/lessons-drift-set.sh" 9)"
+case "$OUT" in *LESSONS_DRIFT_THRESHOLD=9*) echo "PASS: migrate then set 9" ;; *) echo "FAIL: $OUT"; FAIL=1 ;; esac
+[ ! -f "$TMP/.devlog/.lessons-drift-state" ] && echo "PASS: old file removed after migrate+set" || { echo "FAIL: old file still present"; FAIL=1; }
+grep -q '"count": 4' "$TMP/.devlog/.lessons-advisory-state" && echo "PASS: migrated count preserved through set" || { echo "FAIL: migrated count lost"; FAIL=1; }
+grep -q '"threshold": 9' "$TMP/.devlog/.lessons-advisory-state" && echo "PASS: new threshold applied after migrate" || { echo "FAIL: threshold not applied"; FAIL=1; }
+
 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-lessons-on-off.sh

@@ -44,11 +44,21 @@ case "$OUT" in
   *"LESSONS_ENABLED="*) echo "PASS: reports LESSONS_ENABLED" ;;
   *) echo "FAIL: expected LESSONS_ENABLED=..., got $OUT"; FAIL=1 ;;
 esac
-assert_file ".lessons-drift-state created alongside .lessons-enabled" "$TMP_ROOT/.devlog/.lessons-drift-state"
-grep -q '"mismatch_count": 0' "$TMP_ROOT/.devlog/.lessons-drift-state" \
-  && echo "PASS: drift count starts at 0" || { echo "FAIL: drift count not 0"; FAIL=1; }
-grep -q '"threshold": 3' "$TMP_ROOT/.devlog/.lessons-drift-state" \
-  && echo "PASS: drift threshold defaults to 3" || { echo "FAIL: drift threshold not 3"; FAIL=1; }
+assert_file ".lessons-advisory-state created alongside .lessons-enabled" "$TMP_ROOT/.devlog/.lessons-advisory-state"
+grep -q '"count": 0' "$TMP_ROOT/.devlog/.lessons-advisory-state" \
+  && echo "PASS: advisory count starts at 0" || { echo "FAIL: advisory count not 0"; FAIL=1; }
+grep -q '"threshold": 3' "$TMP_ROOT/.devlog/.lessons-advisory-state" \
+  && echo "PASS: advisory threshold defaults to 3" || { echo "FAIL: advisory threshold not 3"; FAIL=1; }
+
+# --- lessons-on migrates an old .lessons-drift-state on re-run -------------
+rm -f "$TMP_ROOT/.devlog/.lessons-advisory-state"
+printf '%s\n' '{"mismatch_count": 2, "threshold": 7}' > "$TMP_ROOT/.devlog/.lessons-drift-state"
+OUT="$(bash "$SCRIPT_DIR/lessons-on.sh")"
+assert_exit "lessons-on migrates old state file -> 0" 0 $?
+assert_file "migration produced .lessons-advisory-state" "$TMP_ROOT/.devlog/.lessons-advisory-state"
+assert_not_file "migration removed .lessons-drift-state" "$TMP_ROOT/.devlog/.lessons-drift-state"
+grep -q '"count": 2' "$TMP_ROOT/.devlog/.lessons-advisory-state" && echo "PASS: migrated count preserved" || { echo "FAIL: migrated count lost"; FAIL=1; }
+grep -q '"threshold": 7' "$TMP_ROOT/.devlog/.lessons-advisory-state" && echo "PASS: migrated threshold preserved" || { echo "FAIL: migrated threshold lost"; FAIL=1; }
 
 # --- lessons-off disables, leaves main switch and any lessons files alone --
 echo 'keep me' > "$TMP_ROOT/.devlog/devlog.lessons.foo.md"
@@ -61,7 +71,7 @@ esac
 assert_not_file ".lessons-enabled removed" "$TMP_ROOT/.devlog/.lessons-enabled"
 assert_file "main .enabled untouched" "$TMP_ROOT/.devlog/.enabled"
 assert_file "lessons file untouched" "$TMP_ROOT/.devlog/devlog.lessons.foo.md"
-assert_file ".lessons-drift-state untouched by lessons-off" "$TMP_ROOT/.devlog/.lessons-drift-state"
+assert_file ".lessons-advisory-state untouched by lessons-off" "$TMP_ROOT/.devlog/.lessons-advisory-state"
 
 # --- lessons-off when already off -> reports NOT_ENABLED, no error --------
 OUT="$(bash "$SCRIPT_DIR/lessons-off.sh")"

package/core/scripts/tests/test-project-dir.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -uo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BASH_BIN="$(command -v bash)"
+FAIL=0
+
+run_case() {
+  local desc="$1" expected="$2"
+  shift 2
+  local actual
+  actual="$(env -i PATH="$PATH" "$@" "$BASH_BIN" -c '. "'"$DIR"'/project-dir.sh"; devlog_project_dir')"
+  if [ "$actual" = "$expected" ]; then
+    echo "PASS: $desc"
+  else
+    echo "FAIL: $desc (expected [$expected], got [$actual])"
+    FAIL=1
+  fi
+}
+
+run_case "neither var set falls back to ." "."
+run_case "CLAUDE_PROJECT_DIR alone is honored" "/legacy" \
+  CLAUDE_PROJECT_DIR=/legacy
+run_case "DEVLOG_PROJECT_DIR alone is honored" "/neutral" \
+  DEVLOG_PROJECT_DIR=/neutral
+run_case "DEVLOG_PROJECT_DIR wins over CLAUDE_PROJECT_DIR" "/neutral" \
+  DEVLOG_PROJECT_DIR=/neutral CLAUDE_PROJECT_DIR=/legacy
+
+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-round-start.sh

@@ -634,6 +634,49 @@ fi
 assert_file_absent "task-notification during open span: no .round-open" "$DEVLOG_DIR/.round-open"
 rm -f "$DEVLOG_DIR/.span-open"
 
+# --- 19: devlog-tracker admin slash commands are exempt from Round logging -
+rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md" "$DEVLOG_DIR/.checkpoint-state"
+printf '%s\n' '{"rounds_since_checkpoint": 3, "max_silent_rounds": 20, "checkpoint_marker_count": 0}' > "$DEVLOG_DIR/.checkpoint-state"
+ADMIN_PROMPT='<command-name>/devlog-tracker:status</command-name><command-message>status</command-message><command-args></command-args>'
+printf '{"prompt":"%s"}' "$ADMIN_PROMPT" | bash "$SCRIPT_DIR/round-start.sh"
+assert_file_absent "admin command: no .round-current.md" "$DEVLOG_DIR/.round-current.md"
+assert_file_absent "admin command: no .round-open" "$DEVLOG_DIR/.round-open"
+assert_file_absent "admin command: no .turn-start" "$DEVLOG_DIR/.turn-start"
+assert_file_absent "admin command: no devlog.md created" "$DEVLOG_DIR/devlog.md"
+CP="$(grep -o '"rounds_since_checkpoint"[[:space:]]*:[[:space:]]*[0-9]\+' "$DEVLOG_DIR/.checkpoint-state" | grep -o '[0-9]\+$')"
+if [ "$CP" = "3" ]; then
+  echo "PASS: admin command does not increment rounds_since_checkpoint"
+else
+  echo "FAIL: expected rounds_since_checkpoint to stay 3, got $CP"
+  FAIL=1
+fi
+rm -f "$DEVLOG_DIR/.checkpoint-state"
+
+# --- 20: a namespaced-but-different command name is not falsely exempted ---
+# "lessons-on" must not match the "lessons" case arm (prefix collision guard).
+LESSONS_ON_PROMPT='<command-name>/devlog-tracker:lessons-on</command-name><command-message>lessons-on</command-message><command-args></command-args>'
+printf '{"prompt":"%s"}' "$LESSONS_ON_PROMPT" | bash "$SCRIPT_DIR/round-start.sh"
+if [ -f "$DEVLOG_DIR/.round-current.md" ]; then
+  echo "FAIL: lessons-on command should still be exempt (matched its own arm)"
+  FAIL=1
+else
+  echo "PASS: lessons-on command exempt via its own case arm"
+fi
+
+# --- 21: /devlog-tracker:continue is NOT exempt -- real work may follow ----
+rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
+CONTINUE_PROMPT='<command-name>/devlog-tracker:continue</command-name><command-message>continue</command-message><command-args></command-args>'
+printf '{"prompt":"%s"}' "$CONTINUE_PROMPT" | bash "$SCRIPT_DIR/round-start.sh"
+CUR_BODY="$(cat "$DEVLOG_DIR/.round-current.md" 2>/dev/null || echo '')"
+assert_contains "continue command still opens a Round" "## Round 1 —" "$CUR_BODY"
+if [ -f "$DEVLOG_DIR/.round-open" ]; then
+  echo "PASS: continue command still sets .round-open"
+else
+  echo "FAIL: continue command should still set .round-open"
+  FAIL=1
+fi
+rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
+
 # --- workspace claim on next prompt ----------------------------------------
 WS="$TMP_ROOT/ws"
 mkdir -p "$WS/.devlog"
@@ -674,6 +717,10 @@ OUT="$(printf '%s' '{"prompt":"keep going"}' | bash "$SCRIPT_DIR/round-start.sh"
 grep -q '^## Round 2' "$WS/.devlog/.round-current.md" && echo "PASS: still opened Round 2" || { echo "FAIL: no round 2"; FAIL=1; }
 
 rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md"
+# This fixture is reused below by the drift-only counter assertions (1 -> 2 ->
+# reset-at-3). Its ### Status must stay non-BLOCKED: if it were BLOCKED, the
+# BLOCKED-round bump would also fire on the same invocation and double-count
+# the shared counter, breaking those assertions with a confusing failure.
 cat > "$WS/.devlog/devlog.md" <<EOF
 ## Round 1 — 2026-09-11T00:00:00+08:00
 
@@ -708,35 +755,35 @@ MARKER="$(cat "$WS/.devlog/.workspace-mismatch")"
 # --- lessons drift counter: mechanical nudge on repeated mismatch --------
 rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md" "$WS/.devlog/.workspace-mismatch"
 touch "$WS/.devlog/.lessons-enabled"
-printf '%s\n' '{"mismatch_count": 0, "threshold": 3}' > "$WS/.devlog/.lessons-drift-state"
+printf '%s\n' '{"count": 0, "threshold": 3}' > "$WS/.devlog/.lessons-advisory-state"
 
 OUT="$(printf '%s' '{"prompt":"keep going"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
 assert_not_contains "drift count 1/3: no nudge yet" "[Lessons Mode 提示]" "$OUT"
-grep -q '"mismatch_count": 1' "$WS/.devlog/.lessons-drift-state" && echo "PASS: drift count -> 1" || { echo "FAIL: drift count not 1"; FAIL=1; }
+grep -q '"count": 1' "$WS/.devlog/.lessons-advisory-state" && echo "PASS: drift count -> 1" || { echo "FAIL: drift count not 1"; FAIL=1; }
 
 rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md"
 OUT="$(printf '%s' '{"prompt":"keep going"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
 assert_not_contains "drift count 2/3: no nudge yet" "[Lessons Mode 提示]" "$OUT"
-grep -q '"mismatch_count": 2' "$WS/.devlog/.lessons-drift-state" && echo "PASS: drift count -> 2" || { echo "FAIL: drift count not 2"; FAIL=1; }
+grep -q '"count": 2' "$WS/.devlog/.lessons-advisory-state" && echo "PASS: drift count -> 2" || { echo "FAIL: drift count not 2"; FAIL=1; }
 
 rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md"
 OUT="$(printf '%s' '{"prompt":"keep going"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
 assert_contains "drift count hits threshold: prints nudge" "[Lessons Mode 提示]" "$OUT"
-grep -q '"mismatch_count": 0' "$WS/.devlog/.lessons-drift-state" && echo "PASS: drift count reset after nudge" || { echo "FAIL: drift count not reset"; FAIL=1; }
+grep -q '"count": 0' "$WS/.devlog/.lessons-advisory-state" && echo "PASS: drift count reset after nudge" || { echo "FAIL: drift count not reset"; FAIL=1; }
 
 # without .lessons-enabled: no counting, no nudge, state file untouched
 rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md" "$WS/.devlog/.lessons-enabled"
-printf '%s\n' '{"mismatch_count": 2, "threshold": 3}' > "$WS/.devlog/.lessons-drift-state"
+printf '%s\n' '{"count": 2, "threshold": 3}' > "$WS/.devlog/.lessons-advisory-state"
 OUT="$(printf '%s' '{"prompt":"keep going"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
 assert_not_contains "lessons off: no nudge even near threshold" "[Lessons Mode 提示]" "$OUT"
-grep -q '"mismatch_count": 2' "$WS/.devlog/.lessons-drift-state" && echo "PASS: drift count untouched when lessons off" || { echo "FAIL: drift count changed when lessons off"; FAIL=1; }
-rm -f "$WS/.devlog/.lessons-drift-state" "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md"
+grep -q '"count": 2' "$WS/.devlog/.lessons-advisory-state" && echo "PASS: drift count untouched when lessons off" || { echo "FAIL: drift count changed when lessons off"; FAIL=1; }
+rm -f "$WS/.devlog/.lessons-advisory-state" "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md"
 
 # --- lessons drift counter: upgrade path — .lessons-enabled exists (from
-# before this branch) but .lessons-drift-state was never created. round-start.sh
+# before this branch) but .lessons-advisory-state was never created. round-start.sh
 # must create it with defaults and still act on this same invocation's
 # mismatch, not require a second message ------------------------------------
-rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md" "$WS/.devlog/.workspace-mismatch" "$WS/.devlog/.lessons-drift-state"
+rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md" "$WS/.devlog/.workspace-mismatch" "$WS/.devlog/.lessons-advisory-state"
 touch "$WS/.devlog/.lessons-enabled"
 cat > "$WS/.devlog/devlog.md" <<EOF
 ## Round 1 — 2026-09-11T00:00:00+08:00
@@ -761,11 +808,11 @@ do x
 IN_PROGRESS
 EOF
 OUT="$(printf '%s' '{"prompt":"keep going"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
-[ -f "$WS/.devlog/.lessons-drift-state" ] && echo "PASS: upgrade path creates .lessons-drift-state on first drift" || { echo "FAIL: .lessons-drift-state not created for pre-existing lessons-enabled"; FAIL=1; }
-grep -q '"mismatch_count": 1' "$WS/.devlog/.lessons-drift-state" 2>/dev/null && echo "PASS: newly-created state already counted this invocation's mismatch (1)" || { echo "FAIL: mismatch_count not 1 in newly-created state"; FAIL=1; }
-grep -q '"threshold": 3' "$WS/.devlog/.lessons-drift-state" 2>/dev/null && echo "PASS: newly-created state has default threshold 3" || { echo "FAIL: threshold not 3 in newly-created state"; FAIL=1; }
+[ -f "$WS/.devlog/.lessons-advisory-state" ] && echo "PASS: upgrade path creates .lessons-advisory-state on first drift" || { echo "FAIL: .lessons-advisory-state not created for pre-existing lessons-enabled"; FAIL=1; }
+grep -q '"count": 1' "$WS/.devlog/.lessons-advisory-state" 2>/dev/null && echo "PASS: newly-created state already counted this invocation's mismatch (1)" || { echo "FAIL: count not 1 in newly-created state"; FAIL=1; }
+grep -q '"threshold": 3' "$WS/.devlog/.lessons-advisory-state" 2>/dev/null && echo "PASS: newly-created state has default threshold 3" || { echo "FAIL: threshold not 3 in newly-created state"; FAIL=1; }
 assert_not_contains "upgrade path: no nudge yet on first-ever drift (1 < 3)" "[Lessons Mode 提示]" "$OUT"
-rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md" "$WS/.devlog/.lessons-enabled" "$WS/.devlog/.lessons-drift-state"
+rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md" "$WS/.devlog/.lessons-enabled" "$WS/.devlog/.lessons-advisory-state"
 
 cat > "$WS/.devlog/devlog.md" <<EOF
 ## Round 1 — 2026-09-11T00:00:00+08:00
@@ -816,6 +863,193 @@ printf '%s' '{"prompt":"tick"}' | bash "$SCRIPT_DIR/round-start.sh" >/dev/null
 [ ! -f "$WS/.devlog/.workspace-mismatch" ] && echo "PASS: span skip writes no marker" || { echo "FAIL: span marker"; FAIL=1; }
 rm -f "$WS/.devlog/.span-open"
 
+# --- BLOCKED-round accumulation shares the advisory counter -----------------
+BLK_DIR="$(mktemp -d)"
+export CLAUDE_PROJECT_DIR="$BLK_DIR"
+mkdir -p "$BLK_DIR/.devlog"
+touch "$BLK_DIR/.devlog/.enabled" "$BLK_DIR/.devlog/.lessons-enabled"
+printf '%s\n' '{"count": 0, "threshold": 3}' > "$BLK_DIR/.devlog/.lessons-advisory-state"
+cat > "$BLK_DIR/.devlog/devlog.md" <<'EOF'
+## Round 1 — 2026-09-20T00:00:00+08:00
+
+### Summary
+s
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 現況
+waiting
+#### 完成條件
+缺的外部輸入已出現，且可觀察條件達成。
+#### 下一步
+apply the answer
+
+### Status
+BLOCKED
+EOF
+OUT="$(printf '%s' '{"prompt":"next"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "BLOCKED round 1/3: no advisory yet" "[Lessons Mode 提示]" "$OUT"
+grep -q '"count": 1' "$BLK_DIR/.devlog/.lessons-advisory-state" && echo "PASS: BLOCKED round bumped counter to 1" || { echo "FAIL: counter not bumped to 1"; FAIL=1; }
+
+rm -f "$BLK_DIR/.devlog/.round-open" "$BLK_DIR/.devlog/.round-current.md"
+cat >> "$BLK_DIR/.devlog/devlog.md" <<'EOF'
+
+## Round 2 — 2026-09-20T00:05:00+08:00
+
+### Summary
+s
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 現況
+waiting
+#### 完成條件
+缺的外部輸入已出現，且可觀察條件達成。
+#### 下一步
+apply the answer
+
+### Status
+BLOCKED
+EOF
+OUT="$(printf '%s' '{"prompt":"next again"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "BLOCKED round 2/3: no advisory yet" "[Lessons Mode 提示]" "$OUT"
+grep -q '"count": 2' "$BLK_DIR/.devlog/.lessons-advisory-state" && echo "PASS: BLOCKED round bumped counter to 2" || { echo "FAIL: counter not bumped to 2"; FAIL=1; }
+
+rm -f "$BLK_DIR/.devlog/.round-open" "$BLK_DIR/.devlog/.round-current.md"
+cat >> "$BLK_DIR/.devlog/devlog.md" <<'EOF'
+
+## Round 3 — 2026-09-20T00:10:00+08:00
+
+### Summary
+s
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 現況
+waiting
+#### 完成條件
+缺的外部輸入已出現，且可觀察條件達成。
+#### 下一步
+apply the answer
+
+### Status
+BLOCKED
+EOF
+OUT="$(printf '%s' '{"prompt":"next once more"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "BLOCKED round 3/3: hits threshold" "[Lessons Mode 提示]" "$OUT"
+grep -q '"count": 0' "$BLK_DIR/.devlog/.lessons-advisory-state" && echo "PASS: counter reset after threshold" || { echo "FAIL: counter not reset"; FAIL=1; }
+rm -rf "$BLK_DIR"
+
+# --- BLOCKED->resolved: mechanical, one-shot print, not counted -------------
+RES_DIR="$(mktemp -d)"
+export CLAUDE_PROJECT_DIR="$RES_DIR"
+mkdir -p "$RES_DIR/.devlog"
+touch "$RES_DIR/.devlog/.enabled" "$RES_DIR/.devlog/.lessons-enabled"
+cat > "$RES_DIR/.devlog/devlog.md" <<'EOF'
+## Round 1 — 2026-09-20T00:00:00+08:00
+
+### Summary
+s
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 現況
+waiting
+#### 完成條件
+缺的外部輸入已出現，且可觀察條件達成。
+#### 下一步
+apply the answer
+
+### Status
+BLOCKED
+
+## Round 2 — 2026-09-20T00:05:00+08:00
+
+### Summary
+resolved it
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 現況
+done
+
+### Status
+DONE
+EOF
+OUT="$(printf '%s' '{"prompt":"whats next"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "BLOCKED->resolved prints a one-shot advisory" "上一輪從 BLOCKED 解開了" "$OUT"
+[ ! -f "$RES_DIR/.devlog/.lessons-advisory-state" ] && echo "PASS: resolved-transition print does not touch the shared counter" || { echo "FAIL: resolved-transition print created/touched the counter file"; FAIL=1; }
+
+# resolved print requires two rounds of history: with only one round of
+# history (regardless of its own status) there's no "second-to-last" round
+# to compare against.
+rm -rf "$RES_DIR"
+RES2_DIR="$(mktemp -d)"
+export CLAUDE_PROJECT_DIR="$RES2_DIR"
+mkdir -p "$RES2_DIR/.devlog"
+touch "$RES2_DIR/.devlog/.enabled" "$RES2_DIR/.devlog/.lessons-enabled"
+cat > "$RES2_DIR/.devlog/devlog.md" <<'EOF'
+## Round 1 — 2026-09-20T00:00:00+08:00
+
+### Summary
+s
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 現況
+done
+
+### Status
+DONE
+EOF
+OUT="$(printf '%s' '{"prompt":"go"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "cold start (one round of history): no resolved print" "上一輪從 BLOCKED 解開了" "$OUT"
+rm -rf "$RES2_DIR"
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+
+# --- without .lessons-enabled: BLOCKED accumulation does not run at all ----
+NOLES_DIR="$(mktemp -d)"
+export CLAUDE_PROJECT_DIR="$NOLES_DIR"
+mkdir -p "$NOLES_DIR/.devlog"
+touch "$NOLES_DIR/.devlog/.enabled"
+cat > "$NOLES_DIR/.devlog/devlog.md" <<'EOF'
+## Round 1 — 2026-09-20T00:00:00+08:00
+
+### Summary
+s
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 現況
+waiting
+#### 完成條件
+缺的外部輸入已出現，且可觀察條件達成。
+#### 下一步
+apply the answer
+
+### Status
+BLOCKED
+EOF
+OUT="$(printf '%s' '{"prompt":"next"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "lessons off: no BLOCKED-accumulation advisory" "[Lessons Mode 提示]" "$OUT"
+[ ! -f "$NOLES_DIR/.devlog/.lessons-advisory-state" ] && echo "PASS: lessons off leaves no advisory-state file" || { echo "FAIL: advisory-state file created while lessons off"; FAIL=1; }
+rm -rf "$NOLES_DIR"
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+
 if [ "$FAIL" -eq 0 ]; then
   echo "All checks passed."
   exit 0

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

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Self-check for search-devlog.sh (/devlog-tracker:search), a pure-read
+# lightweight grep across every devlog*.md file under .devlog/ -- devlog.md,
+# devlog.archive.md, kept devlog.<name>.md, devlog.lessons.<topic>.md, and
+# branch-scoped files all match the same glob, so there is no per-type logic
+# to keep in sync.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+DEVLOG_DIR="$TMP_ROOT/.devlog"
+
+FAIL=0
+assert_exit() {
+  local desc="$1" expected="$2" actual="$3"
+  if [ "$actual" -eq "$expected" ]; then
+    echo "PASS: $desc"
+  else
+    echo "FAIL: $desc (expected exit $expected, got $actual)"
+    FAIL=1
+  fi
+}
+assert_contains() {
+  local desc="$1" needle="$2" haystack="$3"
+  case "$haystack" in
+    *"$needle"*) echo "PASS: $desc" ;;
+    *) echo "FAIL: $desc (expected to contain '$needle', got: $haystack)"; FAIL=1 ;;
+  esac
+}
+assert_not_contains() {
+  local desc="$1" needle="$2" haystack="$3"
+  case "$haystack" in
+    *"$needle"*) echo "FAIL: $desc (expected NOT to contain '$needle')"; FAIL=1 ;;
+    *) echo "PASS: $desc" ;;
+  esac
+}
+
+# --- No .devlog/ at all -> NO_INDEX ----------------------------------------
+OUT="$(bash "$SCRIPT_DIR/search-devlog.sh" "foo" 2>&1)"
+RC=$?
+assert_exit "no .devlog/ -> exit 0" 0 "$RC"
+[ "$OUT" = "NO_INDEX" ] && echo "PASS: no .devlog/ -> NO_INDEX" || { echo "FAIL: expected NO_INDEX, got: $OUT"; FAIL=1; }
+
+mkdir -p "$DEVLOG_DIR"
+
+# --- Missing keyword argument -> error, no files touched -------------------
+bash "$SCRIPT_DIR/search-devlog.sh" >/dev/null 2>&1
+assert_exit "missing keyword -> exit 1" 1 $?
+
+# --- .devlog/ exists but has no devlog*.md files yet -> NO_INDEX -----------
+OUT="$(bash "$SCRIPT_DIR/search-devlog.sh" "foo" 2>&1)"
+[ "$OUT" = "NO_INDEX" ] && echo "PASS: empty .devlog/ -> NO_INDEX" || { echo "FAIL: expected NO_INDEX, got: $OUT"; FAIL=1; }
+
+# --- Matches across main, archive, kept and lessons files -------------------
+cat > "$DEVLOG_DIR/devlog.md" <<'EOF'
+## Round 1 — 2026-09-08T00:00:00+08:00
+
+### Summary
+討論 span mode 的門檻設計。
+
+### Status
+DONE
+EOF
+
+cat > "$DEVLOG_DIR/devlog.archive.md" <<'EOF'
+## Round 0 — 2026-09-01T00:00:00+08:00
+
+### Summary
+舊的 span mode 討論，已封存。
+
+### Status
+DONE
+EOF
+
+cat > "$DEVLOG_DIR/devlog.keep-plan.md" <<'EOF'
+## Round 5 — 2026-09-05T00:00:00+08:00
+
+### Summary
+跟 keep 完全無關的一輪，內容是別的主題。
+
+### Status
+DONE
+EOF
+
+cat > "$DEVLOG_DIR/devlog.lessons.span-mode.md" <<'EOF'
+## 2026-09-10T00:00:00+08:00
+
+Span Mode 的門檻一開始設太低，導致誤判。
+EOF
+
+OUT="$(bash "$SCRIPT_DIR/search-devlog.sh" "span mode" 2>&1)"
+RC=$?
+assert_exit "search finds hits -> exit 0" 0 "$RC"
+assert_contains "hit in devlog.md" "FILE=.devlog/devlog.md" "$OUT"
+assert_contains "hit in devlog.archive.md" "FILE=.devlog/devlog.archive.md" "$OUT"
+assert_contains "hit in devlog.lessons.span-mode.md" "FILE=.devlog/devlog.lessons.span-mode.md" "$OUT"
+assert_not_contains "no hit in unrelated kept file" "FILE=.devlog/devlog.keep-plan.md" "$OUT"
+assert_contains "match line reports nearest (###) heading" 'HEADING="### Summary"' "$OUT"
+assert_contains "match line reports the matched text" "討論 span mode 的門檻設計" "$OUT"
+
+# --- Heading context falls back to the nearest ## when no ### is closer ----
+cat > "$DEVLOG_DIR/devlog.no-sub.md" <<'EOF'
+## Round 9 — 2026-09-12T00:00:00+08:00
+span mode 直接寫在 Round 標題底下，沒有任何 ### 子標題。
+EOF
+OUT_NOSUB="$(bash "$SCRIPT_DIR/search-devlog.sh" "span mode" 2>&1)"
+assert_contains "falls back to nearest ## heading" 'HEADING="## Round 9' "$OUT_NOSUB"
+
+# --- Case-insensitive match --------------------------------------------------
+OUT_UPPER="$(bash "$SCRIPT_DIR/search-devlog.sh" "SPAN MODE" 2>&1)"
+assert_contains "case-insensitive match" "FILE=.devlog/devlog.md" "$OUT_UPPER"
+
+# --- No hits anywhere -> NO_MATCH -------------------------------------------
+OUT_NONE="$(bash "$SCRIPT_DIR/search-devlog.sh" "找不到的關鍵字xyz" 2>&1)"
+[ "$OUT_NONE" = "NO_MATCH" ] && echo "PASS: no hits -> NO_MATCH" || { echo "FAIL: expected NO_MATCH, got: $OUT_NONE"; FAIL=1; }
+
+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-session-start-devlog.sh

@@ -2,7 +2,7 @@
 # Self-check for session-start-devlog.sh, including the Span Mode
 # resume-context note. No framework — plain assert-and-exit, matching this
 # repo's existing style. Run directly:
-#   bash hooks/scripts/test-session-start-devlog.sh
+#   bash core/scripts/tests/test-session-start-devlog.sh
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -181,7 +181,7 @@ echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" >/dev/null 2>&1
 assert_exit "after compact skip-heal, Stop still enforces (hash equal) -> exit 2" 2 $?
 
 # --- Scenario 7: hooks.json SessionStart matcher includes fork -------------
-HOOKS_JSON="$SCRIPT_DIR/../hooks.json"
+HOOKS_JSON="$SCRIPT_DIR/../../claude/hooks.json"
 if grep -q '"matcher": "startup|resume|clear|compact|fork"' "$HOOKS_JSON"; then
   echo "PASS: SessionStart matcher includes fork"
 else
@@ -499,6 +499,65 @@ else
   FAIL=1
 fi
 
+# --- handoff.md present: printed before excerpt header --------------------
+rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/handoff.md" "$DEVLOG_DIR/.span-open"
+cat > "$DEVLOG_DIR/devlog.md" <<'EOF'
+## Round 1 — 2026-09-22T00:00:00+08:00
+
+### Summary
+summary 1
+
+### Handoff
+#### 現況
+handoff 1
+
+### Status
+DONE
+EOF
+cat > "$DEVLOG_DIR/handoff.md" <<'EOF'
+## Session Handoff
+
+### 決策
+- keep route A
+
+### 待解問題
+- open Q
+
+### 失敗嘗試
+- （無）
+EOF
+OUTPUT="$(echo '{"source":"startup"}' | bash "$SCRIPT_DIR/session-start-devlog.sh" 2>&1)"
+assert_contains "handoff header present" "Session Handoff" "$OUTPUT"
+assert_contains "handoff body present" "open Q" "$OUTPUT"
+assert_contains "excerpt still present" "接手摘要" "$OUTPUT"
+HOFF_POS="$(printf '%s\n' "$OUTPUT" | grep -n 'open Q' | head -1 | cut -d: -f1)"
+EX_POS="$(printf '%s\n' "$OUTPUT" | grep -n '接手摘要' | head -1 | cut -d: -f1)"
+if [ -n "$HOFF_POS" ] && [ -n "$EX_POS" ] && [ "$HOFF_POS" -lt "$EX_POS" ]; then
+  echo "PASS: handoff prints before devlog excerpt"
+else
+  echo "FAIL: handoff should precede excerpt (hoff=$HOFF_POS ex=$EX_POS)"
+  FAIL=1
+fi
+
+# --- no handoff.md: excerpt only -----------------------------------------
+rm -f "$DEVLOG_DIR/handoff.md"
+OUTPUT="$(echo '{"source":"startup"}' | bash "$SCRIPT_DIR/session-start-devlog.sh" 2>&1)"
+assert_not_contains "no handoff file -> no open Q" "open Q" "$OUTPUT"
+assert_contains "excerpt still works" "接手摘要" "$OUTPUT"
+
+# --- clear: still silent even with handoff.md ----------------------------
+cat > "$DEVLOG_DIR/handoff.md" <<'EOF'
+## Session Handoff
+### 決策
+- should not inject
+EOF
+OUTPUT="$(echo '{"source":"clear"}' | bash "$SCRIPT_DIR/session-start-devlog.sh" 2>&1)"
+if [ -z "$OUTPUT" ]; then
+  echo "PASS: clear stays silent with handoff.md present"
+else
+  echo "FAIL: clear should be silent, got: $OUTPUT"; FAIL=1
+fi
+
 if [ "$FAIL" -eq 0 ]; then
   echo "All checks passed."
   exit 0

package/{hooks → core}/scripts/tests/test-status-span.sh

@@ -30,10 +30,10 @@ OUT="$(bash "$SCRIPT_DIR/status-devlog.sh")"
 case "$OUT" in *"LESSONS=yes"*) pass "lessons on when flag present" ;; *) fail "lessons on when flag present [$OUT]" ;; esac
 rm -f "$TMP/.devlog/.lessons-enabled"
 
-printf '%s\n' '{"mismatch_count": 1, "threshold": 3}' > "$TMP/.devlog/.lessons-drift-state"
+printf '%s\n' '{"count": 1, "threshold": 3}' > "$TMP/.devlog/.lessons-advisory-state"
 OUT="$(bash "$SCRIPT_DIR/status-devlog.sh")"
-case "$OUT" in *"LESSONS_DRIFT=1/3"*) pass "lessons drift status line" ;; *) fail "lessons drift status line [$OUT]" ;; esac
-rm -f "$TMP/.devlog/.lessons-drift-state"
+case "$OUT" in *"LESSONS_ADVISORY=1/3"*) pass "lessons advisory status line" ;; *) fail "lessons advisory status line [$OUT]" ;; esac
+rm -f "$TMP/.devlog/.lessons-advisory-state"
 
 OUT="$(bash "$SCRIPT_DIR/span-open.sh")"
 [ "$OUT" = "OPENED=1" ] && pass "span opened" || fail "span open [$OUT]"