devlog-tracker 0.27.0 → 0.30.0

package/core/scripts/tests/test-enforce-devlog-session-handoff.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# Self-check for Session Handoff enforce + handoff.md sync.
+# docs/design/session-handoff-file.md
+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"
+mkdir -p "$DEVLOG_DIR"
+touch "$DEVLOG_DIR/.enabled"
+
+git -C "$TMP_ROOT" init -q -b main
+git -C "$TMP_ROOT" config user.email test@example.com
+git -C "$TMP_ROOT" config user.name test
+echo '.devlog/' > "$TMP_ROOT/.gitignore"
+git -C "$TMP_ROOT" add .gitignore
+git -C "$TMP_ROOT" commit -q -m init
+HASH="$(git -C "$TMP_ROOT" rev-parse --short HEAD)"
+
+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
+}
+
+SESSION_OK='
+### Session Handoff
+
+#### 決策
+- pick route A
+
+#### 待解問題
+- still wiring enforce
+
+#### 失敗嘗試
+- （無）
+'
+
+write_unfinished() {
+  local status="$1" session="$2"
+  {
+    echo "## Round 1 — 2026-09-22T00:00:00+08:00"
+    echo ""
+    echo "### Summary"
+    echo "fixture"
+    echo ""
+    echo "### Reply"
+    echo "fixture reply."
+    echo ""
+    echo "### Handoff"
+    echo "#### 工作區"
+    echo "main @ ${HASH}，工作樹乾淨"
+    echo "#### 現況"
+    if [ "$status" = "BLOCKED" ]; then
+      echo "缺使用者提供的 token（出現即繼續）"
+    else
+      echo "fixture"
+    fi
+    echo "#### 完成條件"
+    echo "observable done via test."
+    echo "#### 下一步"
+    if [ "$status" = "BLOCKED" ]; then
+      echo "等使用者提供 token 後改 hooks/foo.sh"
+    else
+      echo "edit core/scripts/enforce-devlog.sh"
+    fi
+    if [ -n "$session" ]; then
+      printf '%s\n' "$session"
+    fi
+    echo ""
+    echo "### Status"
+    echo "$status"
+  } > "$DEVLOG_DIR/.round-current.md"
+}
+
+# 1) IN_PROGRESS without Session Handoff -> blocked
+bash "$SCRIPT_DIR/round-start.sh" < /dev/null
+write_unfinished IN_PROGRESS ""
+MSG="$(echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" 2>&1)"
+assert_exit "IN_PROGRESS without Session Handoff -> blocked" 2 $?
+case "$MSG" in
+  *"Session Handoff"*) echo "PASS: message mentions Session Handoff" ;;
+  *) echo "FAIL: expected Session Handoff in message, got: $MSG"; FAIL=1 ;;
+esac
+
+# 2) IN_PROGRESS with Session Handoff -> write handoff.md
+bash "$SCRIPT_DIR/round-start.sh" < /dev/null
+write_unfinished IN_PROGRESS "$SESSION_OK"
+echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" >/dev/null 2>&1
+assert_exit "IN_PROGRESS with Session Handoff -> allowed" 0 $?
+if [ -f "$DEVLOG_DIR/handoff.md" ] && grep -q 'pick route A' "$DEVLOG_DIR/handoff.md" \
+  && grep -q '^## Session Handoff' "$DEVLOG_DIR/handoff.md"; then
+  echo "PASS: handoff.md written from Session Handoff"
+else
+  echo "FAIL: handoff.md missing or wrong"; FAIL=1
+fi
+
+# 3) BLOCKED with Session Handoff -> updates file
+bash "$SCRIPT_DIR/round-start.sh" < /dev/null
+write_unfinished BLOCKED "
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- waiting on token
+
+#### 失敗嘗試
+- （無）
+"
+echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" >/dev/null 2>&1
+assert_exit "BLOCKED with Session Handoff -> allowed" 0 $?
+if grep -q 'waiting on token' "$DEVLOG_DIR/handoff.md" 2>/dev/null; then
+  echo "PASS: handoff.md updated on BLOCKED"
+else
+  echo "FAIL: handoff.md not updated on BLOCKED"; FAIL=1
+fi
+
+# 4) DONE clears handoff.md
+echo "stale" > "$DEVLOG_DIR/handoff.md"
+bash "$SCRIPT_DIR/round-start.sh" < /dev/null
+{
+  echo "## Round 1 — 2026-09-22T01:00:00+08:00"
+  echo ""
+  echo "### Summary"
+  echo "done"
+  echo ""
+  echo "### Reply"
+  echo "done reply."
+  echo ""
+  echo "### Handoff"
+  echo "#### 現況"
+  echo "finished"
+  echo ""
+  echo "### Status"
+  echo "DONE"
+} > "$DEVLOG_DIR/.round-current.md"
+echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" >/dev/null 2>&1
+assert_exit "DONE -> allowed" 0 $?
+if [ ! -f "$DEVLOG_DIR/handoff.md" ]; then
+  echo "PASS: DONE deletes handoff.md"
+else
+  echo "FAIL: handoff.md survived DONE"; FAIL=1
+fi
+
+# 5) wrong order -> blocked; existing handoff unchanged
+echo "keep-me" > "$DEVLOG_DIR/handoff.md"
+bash "$SCRIPT_DIR/round-start.sh" < /dev/null
+write_unfinished IN_PROGRESS "
+### Session Handoff
+
+#### 待解問題
+- x
+
+#### 決策
+- y
+
+#### 失敗嘗試
+- z
+"
+echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" >/dev/null 2>&1
+assert_exit "wrong Session Handoff order -> blocked" 2 $?
+if [ -f "$DEVLOG_DIR/handoff.md" ] && grep -q 'keep-me' "$DEVLOG_DIR/handoff.md"; then
+  echo "PASS: handoff.md unchanged on validation failure"
+else
+  echo "FAIL: handoff.md should be untouched on validation failure"; FAIL=1
+fi
+
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

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

@@ -75,6 +75,17 @@ write_round() {
     echo "#### 下一步"
     echo "edit hooks/scripts/enforce-devlog.sh"
     echo ""
+    echo "### Session Handoff"
+    echo ""
+    echo "#### 決策"
+    echo "- （無）"
+    echo ""
+    echo "#### 待解問題"
+    echo "- fixture open"
+    echo ""
+    echo "#### 失敗嘗試"
+    echo "- （無）"
+    echo ""
     echo "### Status"
     echo "IN_PROGRESS"
   } > "$DEVLOG_DIR/.round-current.md"
@@ -193,6 +204,18 @@ bash "$SCRIPT_DIR/round-start.sh" < /dev/null
   echo "#### 下一步"
   echo "edit hooks/scripts/enforce-devlog.sh"
   echo ""
+  echo ""
+  echo "### Session Handoff"
+  echo ""
+  echo "#### 決策"
+  echo "- （無）"
+  echo ""
+  echo "#### 待解問題"
+  echo "- fixture open"
+  echo ""
+  echo "#### 失敗嘗試"
+  echo "- （無）"
+  echo ""
   echo "### Status"
   echo "IN_PROGRESS"
 } > "$DEVLOG_DIR/.round-current.md"
@@ -229,6 +252,18 @@ bash "$SCRIPT_DIR/round-start.sh" < /dev/null
   echo "#### 下一步"
   echo "edit hooks/scripts/enforce-devlog.sh"
   echo ""
+  echo ""
+  echo "### Session Handoff"
+  echo ""
+  echo "#### 決策"
+  echo "- （無）"
+  echo ""
+  echo "#### 待解問題"
+  echo "- fixture open"
+  echo ""
+  echo "#### 失敗嘗試"
+  echo "- （無）"
+  echo ""
   echo "### Status"
   echo "IN_PROGRESS"
 } > "$DEVLOG_DIR/.round-current.md"

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

@@ -793,6 +793,18 @@ cat > "$DEVLOG_DIR/.round-current.md" <<'EOF'
 esc
 ```
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -909,6 +921,18 @@ cat > "$DEVLOG_DIR/.round-current.md" <<'EOF'
 stale interrupt
 ```
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -930,6 +954,18 @@ assert_exit "after stale interrupt cleared -> normal enforcement blocks (hash eq
 cat > "$DEVLOG_DIR/devlog.md" <<'EOF'
 ## Round 1 — 2026-09-09T12:00:00+08:00
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -999,6 +1035,18 @@ fixture reply.
 #### 現況
 做到一半。
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -1026,6 +1074,18 @@ fixture reply.
 #### 下一步
 打開 foo.ts 繼續。
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -1074,6 +1134,18 @@ fixture reply.
 #### 下一步
 繼續完成
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -1103,6 +1175,18 @@ fixture reply.
 #### 下一步
 持續優化。
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 BLOCKED
 EOF
@@ -1131,6 +1215,18 @@ fixture reply.
 #### 下一步
 先繼續完成 foo.ts 的錯誤處理，再跑一次測試。
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -1162,6 +1258,18 @@ fixture reply.
 繼續完成
 打開 bar.ts 補上測試。
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -1212,6 +1320,18 @@ cat > "$DEVLOG_DIR/.round-current.md" <<'EOF'
 #### 下一步
 再想一下怎麼做比較好
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 IN_PROGRESS
 EOF
@@ -1243,6 +1363,18 @@ cat > "$DEVLOG_DIR/.round-current.md" <<'EOF'
 #### 下一步
 改 hooks/foo.sh
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 BLOCKED
 EOF
@@ -1274,12 +1406,54 @@ cat > "$DEVLOG_DIR/.round-current.md" <<'EOF'
 #### 下一步
 等使用者提供 key 後改 hooks/foo.sh
 
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- fixture open
+
+#### 失敗嘗試
+- （無）
+
 ### Status
 BLOCKED
 EOF
 echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" >/dev/null 2>&1
 assert_exit "BLOCKED with 缺件句式 -> allowed" 0 $?
 
+# --- Lock contention: another live session holds .devlog/.lock -----------
+# Must block (exit 2, distinct message) instead of proceeding to read/merge
+# a devlog.md that the other session might be mid-write on, and must leave
+# .round-current.md / devlog.md untouched so the retry has something to
+# validate.
+bash "$SCRIPT_DIR/round-start.sh" < /dev/null
+append_minimal_round 102 "2026-09-15T10:04:00+08:00"
+PRE_ROUND_CURRENT="$(cat "$DEVLOG_DIR/.round-current.md" 2>/dev/null || true)"
+PRE_DEVLOG="$(cat "$DEVLOG_DIR/devlog.md" 2>/dev/null || true)"
+sleep 5 &
+LOCK_HOLDER_PID=$!
+mkdir "$DEVLOG_DIR/.lock"
+echo "$LOCK_HOLDER_PID" > "$DEVLOG_DIR/.lock/pid"
+CONTENTION_MSG="$(echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" 2>&1 >/dev/null)"
+assert_exit "another live session holds the lock -> blocked" 2 $?
+case "$CONTENTION_MSG" in
+  *"$LOCK_HOLDER_PID"*) echo "PASS: contention message names the holder pid" ;;
+  *) echo "FAIL: expected holder pid $LOCK_HOLDER_PID in message, got: $CONTENTION_MSG"; FAIL=1 ;;
+esac
+assert_contains "lock contention: .round-current.md left untouched" "$PRE_ROUND_CURRENT" "$(cat "$DEVLOG_DIR/.round-current.md" 2>/dev/null || true)"
+[ "$(cat "$DEVLOG_DIR/devlog.md" 2>/dev/null || true)" = "$PRE_DEVLOG" ] \
+  && echo "PASS: lock contention: devlog.md left untouched" \
+  || { echo "FAIL: devlog.md should be untouched while the lock is contended"; FAIL=1; }
+kill "$LOCK_HOLDER_PID" 2>/dev/null || true
+wait "$LOCK_HOLDER_PID" 2>/dev/null || true
+rm -rf "$DEVLOG_DIR/.lock"
+echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" >/dev/null 2>&1
+assert_exit "retry once the lock is free -> allowed (no lasting side effect)" 0 $?
+assert_round_merged "retry once the lock is free" "fixture"
+
 if [ "$FAIL" -eq 0 ]; then
   echo "All checks passed."
   exit 0

package/core/scripts/tests/test-handoff-file.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=../handoff-file.sh
+. "$SCRIPT_DIR/handoff-file.sh"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAIL=0
+
+GOOD_ROUND='## Round 1 — 2026-09-22T00:00:00+08:00
+
+### Summary
+s
+
+### Reply
+r
+
+### Handoff
+#### 現況
+c
+#### 完成條件
+done when tests pass
+#### 下一步
+edit core/scripts/handoff-file.sh
+
+### Session Handoff
+
+#### 決策
+- pick route A
+
+#### 待解問題
+- （無）
+
+#### 失敗嘗試
+- tried parse-in-place
+
+### Status
+IN_PROGRESS
+'
+
+BAD_ORDER='### Session Handoff
+#### 待解問題
+- x
+#### 決策
+- y
+#### 失敗嘗試
+- z
+'
+
+MISSING='### Session Handoff
+#### 決策
+- x
+#### 失敗嘗試
+- z
+'
+
+if handoff_session_section_ok "$GOOD_ROUND"; then
+  echo "PASS: good round validates"
+else
+  echo "FAIL: good round should validate"; FAIL=1
+fi
+
+if handoff_session_section_ok "$BAD_ORDER"; then
+  echo "FAIL: bad order should fail"; FAIL=1
+else
+  echo "PASS: bad order rejected"
+fi
+
+if handoff_session_section_ok "$MISSING"; then
+  echo "FAIL: missing 待解問題 should fail"; FAIL=1
+else
+  echo "PASS: missing subsection rejected"
+fi
+
+OUT="$(handoff_extract_file_body "$GOOD_ROUND")" || { echo "FAIL: extract exited $?"; FAIL=1; OUT=""; }
+if printf '%s\n' "$OUT" | grep -q '^## Session Handoff' \
+  && printf '%s\n' "$OUT" | grep -q '^### 決策' \
+  && printf '%s\n' "$OUT" | grep -q 'pick route A' \
+  && printf '%s\n' "$OUT" | grep -q '^### 待解問題' \
+  && printf '%s\n' "$OUT" | grep -q '（無）' \
+  && printf '%s\n' "$OUT" | grep -q '^### 失敗嘗試' \
+  && printf '%s\n' "$OUT" | grep -q 'tried parse-in-place'; then
+  echo "PASS: extract shape"
+else
+  echo "FAIL: extract shape, got: $OUT"; FAIL=1
+fi
+
+TARGET="$TMP/handoff.md"
+handoff_write "$TARGET" "$GOOD_ROUND" || { echo "FAIL: write"; FAIL=1; }
+[ -s "$TARGET" ] && grep -q 'pick route A' "$TARGET" \
+  && echo "PASS: write creates file" \
+  || { echo "FAIL: write"; FAIL=1; }
+
+handoff_clear "$TARGET"
+[ ! -f "$TARGET" ] && echo "PASS: clear removes file" \
+  || { echo "FAIL: clear left file"; FAIL=1; }
+
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=../lessons-advisory-state.sh
+. "$SCRIPT_DIR/lessons-advisory-state.sh"
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+FAIL=0
+
+# --- migrate: neither file present -> no-op --------------------------------
+lessons_advisory_migrate "$TMP_ROOT"
+if [ ! -f "$TMP_ROOT/.lessons-advisory-state" ] && [ ! -f "$TMP_ROOT/.lessons-drift-state" ]; then
+  echo "PASS: migrate no-op when neither file exists"
+else
+  echo "FAIL: migrate created a file when neither existed"; FAIL=1
+fi
+
+# --- migrate: old exists, new doesn't -> migrates and removes old ----------
+printf '%s\n' '{"mismatch_count": 2, "threshold": 5}' > "$TMP_ROOT/.lessons-drift-state"
+lessons_advisory_migrate "$TMP_ROOT"
+if [ -f "$TMP_ROOT/.lessons-advisory-state" ]; then echo "PASS: migrate creates new file"; else echo "FAIL: new file missing after migrate"; FAIL=1; fi
+grep -q '"count": 2' "$TMP_ROOT/.lessons-advisory-state" && echo "PASS: migrate preserves count" || { echo "FAIL: count not migrated"; FAIL=1; }
+grep -q '"threshold": 5' "$TMP_ROOT/.lessons-advisory-state" && echo "PASS: migrate preserves threshold" || { echo "FAIL: threshold not migrated"; FAIL=1; }
+if [ ! -f "$TMP_ROOT/.lessons-drift-state" ]; then echo "PASS: migrate removes old file"; else echo "FAIL: old file still present after migrate"; FAIL=1; fi
+
+# --- migrate: new already exists -> leaves it alone, doesn't touch old -----
+rm -f "$TMP_ROOT/.lessons-advisory-state" "$TMP_ROOT/.lessons-drift-state"
+printf '%s\n' '{"count": 9, "threshold": 9}' > "$TMP_ROOT/.lessons-advisory-state"
+printf '%s\n' '{"mismatch_count": 1, "threshold": 1}' > "$TMP_ROOT/.lessons-drift-state"
+lessons_advisory_migrate "$TMP_ROOT"
+grep -q '"count": 9' "$TMP_ROOT/.lessons-advisory-state" && echo "PASS: migrate leaves existing new file untouched" || { echo "FAIL: existing new file was overwritten"; FAIL=1; }
+
+# --- migrate: idempotent (second call after migration is a no-op) ----------
+rm -f "$TMP_ROOT/.lessons-advisory-state" "$TMP_ROOT/.lessons-drift-state"
+printf '%s\n' '{"mismatch_count": 1, "threshold": 3}' > "$TMP_ROOT/.lessons-drift-state"
+lessons_advisory_migrate "$TMP_ROOT"
+lessons_advisory_migrate "$TMP_ROOT"
+grep -q '"count": 1' "$TMP_ROOT/.lessons-advisory-state" && echo "PASS: second migrate call is a no-op" || { echo "FAIL: second migrate call changed state"; FAIL=1; }
+
+# --- bump: creates file with defaults, increments, no print below threshold
+rm -f "$TMP_ROOT/.lessons-advisory-state"
+OUT="$(lessons_advisory_bump "$TMP_ROOT/.lessons-advisory-state")"
+[ -z "$OUT" ] && echo "PASS: bump 1/3 prints nothing" || { echo "FAIL: bump 1/3 printed [$OUT]"; FAIL=1; }
+grep -q '"count": 1' "$TMP_ROOT/.lessons-advisory-state" && echo "PASS: bump creates file with count=1" || { echo "FAIL: bump did not create count=1"; FAIL=1; }
+grep -q '"threshold": 3' "$TMP_ROOT/.lessons-advisory-state" && echo "PASS: bump defaults threshold to 3" || { echo "FAIL: bump did not default threshold"; FAIL=1; }
+
+# --- bump: reaching threshold prints and resets -----------------------------
+OUT="$(lessons_advisory_bump "$TMP_ROOT/.lessons-advisory-state")"
+[ -z "$OUT" ] && echo "PASS: bump 2/3 prints nothing" || { echo "FAIL: bump 2/3 printed [$OUT]"; FAIL=1; }
+OUT="$(lessons_advisory_bump "$TMP_ROOT/.lessons-advisory-state")"
+case "$OUT" in *"[Lessons Mode 提示]"*) echo "PASS: bump 3/3 prints the advisory" ;; *) echo "FAIL: bump 3/3 did not print, got [$OUT]"; FAIL=1 ;; esac
+grep -q '"count": 0' "$TMP_ROOT/.lessons-advisory-state" && echo "PASS: bump resets count to 0 after printing" || { echo "FAIL: count not reset"; 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-lessons-append.sh

@@ -134,5 +134,23 @@ case "$INDEX_BLOCK3" in
   *) echo "FAIL: expected title truncated at first 。, got: $INDEX_BLOCK3"; FAIL=1 ;;
 esac
 
+# --- Topic-repeat advisory: prints on every 3rd entry in the same topic ----
+OUT_R1="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic "repeat-topic" --text "第一次。")"
+case "$OUT_R1" in *"[Lessons Mode 提示]"*) echo "FAIL: unexpected advisory on 1st entry: $OUT_R1"; FAIL=1 ;; *) echo "PASS: no advisory on 1st entry" ;; esac
+OUT_R2="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic "repeat-topic" --text "第二次。")"
+case "$OUT_R2" in *"[Lessons Mode 提示]"*) echo "FAIL: unexpected advisory on 2nd entry: $OUT_R2"; FAIL=1 ;; *) echo "PASS: no advisory on 2nd entry" ;; esac
+OUT_R3="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic "repeat-topic" --text "第三次。")"
+case "$OUT_R3" in *"[Lessons Mode 提示] 這個主題已經累積 3 則"*) echo "PASS: advisory on 3rd entry" ;; *) echo "FAIL: expected advisory on 3rd entry, got: $OUT_R3"; FAIL=1 ;; esac
+OUT_R4="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic "repeat-topic" --text "第四次。")"
+case "$OUT_R4" in *"[Lessons Mode 提示]"*) echo "FAIL: unexpected advisory on 4th entry: $OUT_R4"; FAIL=1 ;; *) echo "PASS: no advisory on 4th entry" ;; esac
+
+# --- New-topic hint: lists existing topics, only on first-ever append -----
+OUT_NEW="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic "brand-new-topic" --text "第一次，全新主題。")"
+case "$OUT_NEW" in *"NEW_TOPIC"*"既有主題："*) echo "PASS: new-topic hint lists existing topics" ;; *) echo "FAIL: expected NEW_TOPIC hint, got: $OUT_NEW"; FAIL=1 ;; esac
+case "$OUT_NEW" in *"repeat-topic"*) echo "PASS: new-topic hint includes a real existing topic name" ;; *) echo "FAIL: expected existing topic name in hint, got: $OUT_NEW"; FAIL=1 ;; esac
+
+OUT_AGAIN="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic "brand-new-topic" --text "第二次，同一個主題。")"
+case "$OUT_AGAIN" in *"NEW_TOPIC"*) echo "FAIL: unexpected NEW_TOPIC hint on repeat append: $OUT_AGAIN"; FAIL=1 ;; *) echo "PASS: no NEW_TOPIC hint once the topic already exists" ;; esac
+
 if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
 else echo "Some checks FAILED."; exit 1; fi