devlog-tracker 0.27.0 → 0.30.0

package/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/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-lessons-subagent-hooks.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Self-check for lessons-subagent-start.sh (SubagentStart) and
+# lessons-subagent-done.sh (PostToolUse Agent|Task). Run:
+#   bash core/scripts/tests/test-lessons-subagent-hooks.sh
+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"
+
+FAIL=0
+assert_contains() {
+  local desc="$1" needle="$2" haystack="$3"
+  case "$haystack" in
+    *"$needle"*) echo "PASS: $desc" ;;
+    *) echo "FAIL: $desc (missing: $needle)"; FAIL=1 ;;
+  esac
+}
+assert_empty() {
+  local desc="$1" out="$2"
+  if [ -z "$out" ]; then echo "PASS: $desc"; else echo "FAIL: $desc (got: $out)"; FAIL=1; fi
+}
+assert_valid_json() {
+  local desc="$1" out="$2"
+  if ! command -v jq >/dev/null 2>&1; then echo "SKIP: $desc (no jq)"; return 0; fi
+  if printf '%s' "$out" | jq -e . >/dev/null 2>&1; then echo "PASS: $desc"; else echo "FAIL: $desc (invalid JSON: $out)"; FAIL=1; fi
+}
+
+START_IN='{"session_id":"s1","cwd":"/elsewhere/.claude/worktrees/agent-x","agent_id":"a1","agent_type":"general-purpose","hook_event_name":"SubagentStart"}'
+SYNC_DONE='{"session_id":"s1","hook_event_name":"PostToolUse","tool_name":"Agent","tool_input":{"prompt":"p"},"tool_response":{"status":"completed","content":[{"type":"text","text":"done"}]}}'
+ASYNC_DONE='{"session_id":"s1","hook_event_name":"PostToolUse","tool_name":"Agent","tool_input":{"prompt":"p"},"tool_response":{"isAsync":true,"status":"async_launched","agentId":"a1"}}'
+NESTED_DONE='{"session_id":"s1","agent_id":"a1","hook_event_name":"PostToolUse","tool_name":"Agent","tool_input":{"prompt":"p"},"tool_response":{"status":"completed"}}'
+
+# --- disabled: both hooks silent -------------------------------------------
+OUT="$(printf '%s' "$START_IN" | bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+assert_empty "start: .enabled absent -> silent" "$OUT"
+OUT="$(printf '%s' "$SYNC_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_empty "done: .enabled absent -> silent" "$OUT"
+
+touch "$DEVLOG_DIR/.enabled"
+OUT="$(printf '%s' "$START_IN" | bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+assert_empty "start: lessons off -> silent" "$OUT"
+OUT="$(printf '%s' "$SYNC_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_empty "done: lessons off -> silent" "$OUT"
+
+touch "$DEVLOG_DIR/.lessons-enabled"
+
+# --- SubagentStart: inject lessons-append.sh instructions with absolute paths
+OUT="$(printf '%s' "$START_IN" | bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+assert_valid_json "start: output is valid JSON" "$OUT"
+assert_contains "start: hookEventName SubagentStart" '"hookEventName":"SubagentStart"' "$OUT"
+assert_contains "start: additionalContext present" '"additionalContext":' "$OUT"
+assert_contains "start: pins the main project dir, not the agent cwd" "DEVLOG_PROJECT_DIR='$TMP_ROOT'" "$OUT"
+assert_contains "start: absolute lessons-append.sh path" "$SCRIPT_DIR/lessons-append.sh" "$OUT"
+assert_contains "start: asks to mention it in the final report" "最終回報" "$OUT"
+
+# relative CLAUDE_PROJECT_DIR still resolves to an absolute path
+(cd "$TMP_ROOT" && OUT="$(printf '%s' "$START_IN" | CLAUDE_PROJECT_DIR=. bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+ case "$OUT" in *"DEVLOG_PROJECT_DIR='$TMP_ROOT'"*|*"DEVLOG_PROJECT_DIR='$(pwd -P)'"*) echo "PASS: start: relative project dir made absolute" ;;
+   *) echo "FAIL: start: relative project dir not made absolute ($OUT)"; exit 1 ;; esac) || FAIL=1
+
+# path needing JSON escaping stays valid JSON
+QDIR="$TMP_ROOT/we\"ird"
+mkdir -p "$QDIR/.devlog"
+touch "$QDIR/.devlog/.enabled" "$QDIR/.devlog/.lessons-enabled"
+OUT="$(printf '%s' "$START_IN" | CLAUDE_PROJECT_DIR="$QDIR" bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+assert_valid_json "start: quote in project path still valid JSON" "$OUT"
+
+# --- PostToolUse(Agent): foreground completion only -------------------------
+OUT="$(printf '%s' "$SYNC_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_valid_json "done: output is valid JSON" "$OUT"
+assert_contains "done: hookEventName PostToolUse" '"hookEventName":"PostToolUse"' "$OUT"
+assert_contains "done: sub agent advisory" "[Lessons Mode 提示] sub agent 完成" "$OUT"
+
+OUT="$(printf '%s' "$ASYNC_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_empty "done: async launch -> silent (task-notification covers it)" "$OUT"
+
+OUT="$(printf '%s' "$NESTED_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_empty "done: nested (agent_id set) -> silent" "$OUT"
+
+OUT="$(printf '%s' 'not json' | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+RC=$?
+[ "$RC" -eq 0 ] && echo "PASS: done: garbage stdin fails open" || { echo "FAIL: done: garbage stdin exit $RC"; 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-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,242 @@ 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"
+
+# --- lessons: background agent / workflow task-notification advisory ------
+TN_DIR="$(mktemp -d)"
+mkdir -p "$TN_DIR/.devlog"
+touch "$TN_DIR/.devlog/.enabled" "$TN_DIR/.devlog/.lessons-enabled"
+export CLAUDE_PROJECT_DIR="$TN_DIR"
+tn_notif() {
+  printf '{"prompt":"<task-notification><task-id>t9</task-id><status>%s</status><summary>Agent \\"x\\" finished</summary></task-notification>"}' "$1"
+}
+tn_reset() {
+  rm -f "$TN_DIR/.devlog/.round-open" "$TN_DIR/.devlog/.round-current.md"
+  printf '## Round 1 — 2026-09-23T00:00:00+0800\n\n### User Input\n```text\nx\n```\n\n### Summary\ns\n\n### Status\nDONE\n' > "$TN_DIR/.devlog/devlog.md"
+}
+
+tn_reset
+printf '%s\n' '{"count": 0, "threshold": 3}' > "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif completed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif completed: sub agent advisory printed" "[Lessons Mode 提示] 背景任務完成（status=completed）" "$OUT"
+grep -q '"count": 0' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif completed does not bump counter" || { echo "FAIL: completed bumped counter"; FAIL=1; }
+
+tn_reset
+OUT="$(tn_notif failed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif failed: advisory printed" "背景任務完成（status=failed）" "$OUT"
+grep -q '"count": 1' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif failed bumps counter" || { echo "FAIL: failed did not bump counter"; FAIL=1; }
+
+tn_reset
+printf '%s\n' '{"count": 2, "threshold": 3}' > "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif killed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif killed at threshold: shared nudge printed" "流程訊號已累積出現 3 次" "$OUT"
+grep -q '"count": 0' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif killed resets counter at threshold" || { echo "FAIL: killed did not reset counter"; FAIL=1; }
+
+tn_reset
+printf '%s\n' '{"round": 1, "ticks_since_checkin": 0, "max_silent_ticks": 5}' > "$TN_DIR/.devlog/.span-open"
+OUT="$(tn_notif completed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif during span: advisory still printed" "背景任務完成（status=completed）" "$OUT"
+rm -f "$TN_DIR/.devlog/.span-open"
+
+tn_reset
+rm -f "$TN_DIR/.devlog/.lessons-enabled" "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif failed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "task-notif with lessons off: no advisory" "[Lessons Mode 提示]" "$OUT"
+[ ! -f "$TN_DIR/.devlog/.lessons-advisory-state" ] && echo "PASS: task-notif with lessons off leaves no advisory-state" || { echo "FAIL: advisory-state created while lessons off"; FAIL=1; }
+
+touch "$TN_DIR/.devlog/.lessons-enabled"
+tn_reset
+OUT="$(printf '%s' '{"prompt":"plain message"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "plain prompt: no background-task advisory" "背景任務完成" "$OUT"
+rm -rf "$TN_DIR"
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+
 if [ "$FAIL" -eq 0 ]; then
   echo "All checks passed."
   exit 0