devlog-tracker 0.22.0

package/hooks/scripts/tests/test-files-snapshot.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# Self-check for files-snapshot.sh's files_snapshot(), covering the
+# uncommitted branch (git status), the committed branch (git diff-tree),
+# rename-as-delete+add, and .devlog/ exclusion in both branches.
+# No framework — plain assert-and-exit, matching this repo's existing style.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+. "$SCRIPT_DIR/files-snapshot.sh"
+
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+
+FAIL=0
+assert_eq() {
+  local desc="$1" expected="$2" actual="$3"
+  if [ "$actual" = "$expected" ]; then
+    echo "PASS: $desc"
+  else
+    echo "FAIL: $desc"
+    printf '  expected: %s\n' "$expected"
+    printf '  actual:   %s\n' "$actual"
+    FAIL=1
+  fi
+}
+
+# --- non-git directory ----------------------------------------------------
+NONGIT="$TMP_ROOT/nongit"
+mkdir -p "$NONGIT"
+OUT="$(files_snapshot "$NONGIT")"
+assert_eq "non-git directory" "" "$OUT"
+
+# --- repo setup -------------------------------------------------------------
+REPO="$TMP_ROOT/repo"
+mkdir -p "$REPO/.devlog"
+git -C "$REPO" init -q -b main
+git -C "$REPO" config user.email test@example.com
+git -C "$REPO" config user.name test
+echo one > "$REPO/a.txt"
+echo two > "$REPO/b.txt"
+echo bookkeeping > "$REPO/.devlog/devlog.md"
+git -C "$REPO" add a.txt b.txt .devlog/devlog.md
+git -C "$REPO" commit -q -m init
+
+# --- clean tree -> empty ------------------------------------------------------
+OUT="$(files_snapshot "$REPO")"
+assert_eq "clean tree" "" "$OUT"
+
+# --- untracked file -> 新增 ----------------------------------------------------
+echo new > "$REPO/c.txt"
+OUT="$(files_snapshot "$REPO")"
+assert_eq "untracked file" "新增：c.txt" "$OUT"
+rm -f "$REPO/c.txt"
+
+# --- modified tracked file -> 修改 ---------------------------------------------
+echo changed >> "$REPO/a.txt"
+OUT="$(files_snapshot "$REPO")"
+assert_eq "modified tracked file" "修改：a.txt" "$OUT"
+git -C "$REPO" checkout -q -- a.txt
+
+# --- deleted tracked file -> 刪除 ----------------------------------------------
+rm -f "$REPO/b.txt"
+OUT="$(files_snapshot "$REPO")"
+assert_eq "deleted tracked file" "刪除：b.txt" "$OUT"
+git -C "$REPO" checkout -q -- b.txt
+
+# --- mixed: new + modified + deleted, fixed category order --------------------
+echo new > "$REPO/c.txt"
+echo changed >> "$REPO/a.txt"
+rm -f "$REPO/b.txt"
+OUT="$(files_snapshot "$REPO")"
+EXPECTED="新增：c.txt
+修改：a.txt
+刪除：b.txt"
+assert_eq "mixed changes, fixed category order" "$EXPECTED" "$OUT"
+rm -f "$REPO/c.txt"
+git -C "$REPO" checkout -q -- a.txt b.txt
+
+# --- .devlog/ excluded, real change still reported -----------------------------
+echo bookkeeping change >> "$REPO/.devlog/devlog.md"
+echo real change >> "$REPO/a.txt"
+OUT="$(files_snapshot "$REPO")"
+assert_eq ".devlog/ excluded (uncommitted branch)" "修改：a.txt" "$OUT"
+git -C "$REPO" checkout -q -- a.txt .devlog/devlog.md
+
+# --- rename shows as delete+add (no -M anywhere) --------------------------------
+git -C "$REPO" mv a.txt a-renamed.txt
+OUT="$(files_snapshot "$REPO")"
+EXPECTED="新增：a-renamed.txt
+刪除：a.txt"
+assert_eq "rename -> delete+add" "$EXPECTED" "$OUT"
+git -C "$REPO" reset -q --hard HEAD
+
+# --- committed branch: add + modify + delete in one commit -----------------------
+echo new-committed > "$REPO/d.txt"
+echo changed-committed >> "$REPO/a.txt"
+rm -f "$REPO/b.txt"
+git -C "$REPO" add -A
+git -C "$REPO" commit -q -m "mixed commit"
+HASH="$(git -C "$REPO" rev-parse --short HEAD)"
+OUT="$(files_snapshot "$REPO" "$HASH")"
+EXPECTED="新增：d.txt
+修改：a.txt
+刪除：b.txt"
+assert_eq "committed branch, mixed" "$EXPECTED" "$OUT"
+
+# --- committed branch: .devlog/ excluded there too --------------------------------
+echo bookkeeping2 >> "$REPO/.devlog/devlog.md"
+echo e > "$REPO/e.txt"
+git -C "$REPO" add -A
+git -C "$REPO" commit -q -m "with devlog bookkeeping"
+HASH2="$(git -C "$REPO" rev-parse --short HEAD)"
+OUT="$(files_snapshot "$REPO" "$HASH2")"
+assert_eq ".devlog/ excluded (committed branch)" "新增：e.txt" "$OUT"
+
+# --- root commit with --root flag (should show files, not empty) ------------------
+ROOTREPO="$TMP_ROOT/root"
+mkdir -p "$ROOTREPO/.devlog"
+git -C "$ROOTREPO" init -q -b main
+git -C "$ROOTREPO" config user.email test@example.com
+git -C "$ROOTREPO" config user.name test
+echo file1 > "$ROOTREPO/file1.txt"
+echo file2 > "$ROOTREPO/file2.txt"
+echo bookkeeping > "$ROOTREPO/.devlog/devlog.md"
+git -C "$ROOTREPO" add file1.txt file2.txt .devlog/devlog.md
+git -C "$ROOTREPO" commit -q -m "initial root commit"
+ROOT_HASH="$(git -C "$ROOTREPO" rev-parse --short HEAD)"
+OUT="$(files_snapshot "$ROOTREPO" "$ROOT_HASH")"
+EXPECTED="新增：file1.txt, file2.txt"
+assert_eq "root commit with multiple files (--root)" "$EXPECTED" "$OUT"
+
+# --- unresolvable hash -> empty (fail-open) ---------------------------------------
+OUT="$(files_snapshot "$REPO" "0000000")"
+assert_eq "unresolvable hash -> empty" "" "$OUT"
+
+if [ "$FAIL" -eq 0 ]; then
+  echo "All checks passed."
+  exit 0
+else
+  echo "Some checks FAILED."
+  exit 1
+fi

package/hooks/scripts/tests/test-json-field.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=json-field.sh
+. "$SCRIPT_DIR/json-field.sh"
+TMP="$(mktemp)"
+trap 'rm -f "$TMP"' EXIT
+FAIL=0
+assert_eq() {
+  local desc="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "PASS: $desc"
+  else echo "FAIL: $desc (expected [$expected] got [$actual])"; FAIL=1; fi
+}
+
+printf '%s\n' '{"ticks_since_checkin": 2, "max_silent_ticks": 5}' > "$TMP"
+assert_eq "int get" "2" "$(json_int_get "$TMP" ticks_since_checkin)"
+assert_eq "int get max" "5" "$(json_int_get "$TMP" max_silent_ticks)"
+assert_eq "missing key" "" "$(json_int_get "$TMP" no_such)"
+
+printf '%s\n' '{"ticks_since_checkin": 08}' > "$TMP"
+assert_eq "reject octal pad" "" "$(json_int_get "$TMP" ticks_since_checkin)"
+
+printf '%s\n' '{"opened_at": "2026-09-08T21:40:00+08:00", "round": 12}' > "$TMP"
+assert_eq "str get" "2026-09-08T21:40:00+08:00" "$(json_str_get "$TMP" opened_at)"
+assert_eq "int round" "12" "$(json_int_get "$TMP" round)"
+
+printf '%s\n' '{"ticks_since_checkin": 2, "max_silent_ticks": 5}' > "$TMP"
+json_int_set "$TMP" ticks_since_checkin 0
+assert_eq "int set" "0" "$(json_int_get "$TMP" ticks_since_checkin)"
+assert_eq "int set preserves sibling" "5" "$(json_int_get "$TMP" max_silent_ticks)"
+
+printf '%s\n' '{"last_seen_cksum": "old", "last_change_epoch": 1}' > "$TMP"
+json_str_set "$TMP" last_seen_cksum "123 2"
+assert_eq "str set" "123 2" "$(json_str_get "$TMP" last_seen_cksum)"
+assert_eq "str set preserves epoch" "1" "$(json_int_get "$TMP" last_change_epoch)"
+
+printf '%s\n' 'not json' > "$TMP"
+assert_eq "malformed int" "" "$(json_int_get "$TMP" round)"
+assert_eq "malformed str" "" "$(json_str_get "$TMP" opened_at)"
+
+INPUT='{"session_id": "abc-123", "prompt": "hello world"}'
+assert_eq "str field get" "abc-123" "$(json_str_field "$INPUT" session_id)"
+assert_eq "str field get other key" "hello world" "$(json_str_field "$INPUT" prompt)"
+assert_eq "str field missing key" "" "$(json_str_field "$INPUT" no_such)"
+
+INPUT='{"reason": null}'
+assert_eq "str field null" "" "$(json_str_field "$INPUT" reason)"
+
+INPUT='not json'
+assert_eq "str field malformed" "" "$(json_str_field "$INPUT" reason)"
+
+assert_eq "slugify basic" "foo-bar" "$(slugify 'foo bar')"
+assert_eq "slugify collapses runs" "foo-bar" "$(slugify 'foo   bar')"
+assert_eq "slugify trims edges" "foo" "$(slugify ' foo ')"
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/hooks/scripts/tests/test-keep-move.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAIL=0
+assert_eq() {
+  local d="$1" e="$2" a="$3"
+  if [ "$e" = "$a" ]; then echo "PASS: $d"; else echo "FAIL: $d expected [$e] got [$a]"; FAIL=1; fi
+}
+make_round() {
+  local file="$1" n="$2" status="$3"
+  cat >> "$file" <<EOF
+## Round $n — 2026-09-09T12:00:00+08:00
+
+### Status
+$status
+EOF
+}
+
+export CLAUDE_PROJECT_DIR="$TMP/missing"
+bash "$SCRIPT_DIR/keep-move.sh" --from 1 --to 1 --name x >/dev/null 2>&1
+assert_eq "missing log exit 1" 1 "$?"
+
+BAD="$TMP/bad-name"
+mkdir -p "$BAD/.devlog"
+export CLAUDE_PROJECT_DIR="$BAD"
+make_round "$BAD/.devlog/devlog.md" 1 DONE
+bash "$SCRIPT_DIR/keep-move.sh" --from 1 --to 1 --name devlog.md >/dev/null 2>&1
+assert_eq "devlog.md name rejected" 1 "$?"
+[ ! -e "$BAD/.devlog/devlog.md.md" ] || { echo "FAIL: devlog.md.md created"; FAIL=1; }
+
+EP="$TMP/episode"
+mkdir -p "$EP/.devlog"
+export CLAUDE_PROJECT_DIR="$EP"
+printf '# project\n\n' > "$EP/.devlog/devlog.md"
+make_round "$EP/.devlog/devlog.md" 1 DONE
+make_round "$EP/.devlog/devlog.md" 2 DONE
+make_round "$EP/.devlog/devlog.md" 3 IN_PROGRESS
+printf '%s\n' '{"round": 3, "opened_at": "now"}' > "$EP/.devlog/.round-open"
+bash "$SCRIPT_DIR/keep-move.sh" --from 1 --to 1 --name first >/dev/null
+assert_eq "episode keep exits 0" 0 "$?"
+grep -q '^# Kept log' "$EP/.devlog/devlog.first.md" && echo "PASS: provenance written" || { echo "FAIL: provenance"; FAIL=1; }
+grep -q '^## Round 1' "$EP/.devlog/devlog.first.md" && echo "PASS: named file has round" || { echo "FAIL: named round"; FAIL=1; }
+grep -q '^## Round 1' "$EP/.devlog/devlog.md" && { echo "FAIL: moved round remains"; FAIL=1; } || echo "PASS: moved round removed"
+grep -q '^## Round 3' "$EP/.devlog/devlog.md" && echo "PASS: open round remains" || { echo "FAIL: open moved"; FAIL=1; }
+bash "$SCRIPT_DIR/keep-move.sh" --from 3 --to 3 --name open >/dev/null 2>&1
+assert_eq "open round rejected" 1 "$?"
+bash "$SCRIPT_DIR/keep-move.sh" --from 2 --to 2 --name first >/dev/null 2>&1
+assert_eq "overwrite rejected" 1 "$?"
+
+FULL="$TMP/full"
+mkdir -p "$FULL/.devlog"
+export CLAUDE_PROJECT_DIR="$FULL"
+printf '# project\n\n' > "$FULL/.devlog/devlog.md"
+make_round "$FULL/.devlog/devlog.md" 1 DONE
+make_round "$FULL/.devlog/devlog.md" 2 DONE
+make_round "$FULL/.devlog/devlog.md" 3 IN_PROGRESS
+printf '%s\n' '{"round": 3, "opened_at": "now"}' > "$FULL/.devlog/.round-open"
+printf '%s\n' '{"round": 2, "ticks": 1, "max_silent_ticks": 5}' > "$FULL/.devlog/.span-open"
+printf '%s\n' '{"rounds_since_checkpoint": 19, "max_silent_rounds": 20, "checkpoint_marker_count": 0}' > "$FULL/.devlog/.checkpoint-state"
+bash "$SCRIPT_DIR/keep-move.sh" --from 1 --to 2 --name episode >/dev/null
+assert_eq "full keep exits 0" 0 "$?"
+grep -q '^## Round 1 ' "$FULL/.devlog/devlog.md" && echo "PASS: open round renumbered" || { echo "FAIL: full renumber"; FAIL=1; }
+grep -q '"round": 1' "$FULL/.devlog/.round-open" && echo "PASS: round state reset" || { echo "FAIL: round state"; FAIL=1; }
+grep -q '"rounds_since_checkpoint": 0' "$FULL/.devlog/.checkpoint-state" && echo "PASS: checkpoint reset" || { echo "FAIL: checkpoint state"; FAIL=1; }
+grep -q '"max_silent_rounds": 20' "$FULL/.devlog/.checkpoint-state" && echo "PASS: checkpoint max kept" || { echo "FAIL: checkpoint max"; FAIL=1; }
+[ ! -e "$FULL/.devlog/.span-open" ] && echo "PASS: span removed" || { echo "FAIL: span remains"; FAIL=1; }
+
+grep -q '^## Kept 索引' "$FULL/.devlog/devlog.md" && echo "PASS: full keep wrote a Kept 索引 block" || { echo "FAIL: full keep should write a Kept 索引 block"; FAIL=1; }
+grep -q 'devlog.episode.md' "$FULL/.devlog/devlog.md" && echo "PASS: full keep index line names devlog.episode.md" || { echo "FAIL: full keep index line missing devlog.episode.md"; FAIL=1; }
+
+INDEX="$TMP/index"
+mkdir -p "$INDEX/.devlog"
+export CLAUDE_PROJECT_DIR="$INDEX"
+printf '# project\n\n' > "$INDEX/.devlog/devlog.md"
+make_round "$INDEX/.devlog/devlog.md" 1 DONE
+make_round "$INDEX/.devlog/devlog.md" 2 DONE
+make_round "$INDEX/.devlog/devlog.md" 3 DONE
+# Keep an open round so the 3rd keep below (--from 3 --to 3) stays a *partial*
+# keep — a full keep drops everything before the first round, which would
+# leave ## Kept 索引 at line 1 and silently stop testing the blank-line
+# separator regression checked below.
+make_round "$INDEX/.devlog/devlog.md" 4 IN_PROGRESS
+printf '%s\n' '{"round": 4, "opened_at": "now"}' > "$INDEX/.devlog/.round-open"
+bash "$SCRIPT_DIR/keep-move.sh" --from 1 --to 1 --name topic-a >/dev/null
+KEPT_COUNT_1="$(grep -c '^- ' "$INDEX/.devlog/devlog.md")"
+[ "$KEPT_COUNT_1" -eq 1 ] && echo "PASS: first partial keep adds exactly one index line" || { echo "FAIL: expected 1 index line, got $KEPT_COUNT_1"; FAIL=1; }
+bash "$SCRIPT_DIR/keep-move.sh" --from 2 --to 2 --name topic-b >/dev/null
+KEPT_COUNT_2="$(grep -c '^- ' "$INDEX/.devlog/devlog.md")"
+[ "$KEPT_COUNT_2" -eq 2 ] && echo "PASS: second partial keep accumulates to two index lines" || { echo "FAIL: expected 2 index lines, got $KEPT_COUNT_2"; FAIL=1; }
+KEPT_BLOCKS="$(grep -c '^## Kept 索引' "$INDEX/.devlog/devlog.md")"
+[ "$KEPT_BLOCKS" -eq 1 ] && echo "PASS: exactly one Kept 索引 heading after two keeps" || { echo "FAIL: expected exactly 1 Kept 索引 heading, got $KEPT_BLOCKS"; FAIL=1; }
+grep -q 'devlog.topic-a.md' "$INDEX/.devlog/devlog.md" && echo "PASS: first line survives the second keep's rewrite" || { echo "FAIL: devlog.topic-a.md line lost after second keep"; FAIL=1; }
+bash "$SCRIPT_DIR/keep-move.sh" --from 3 --to 3 --name topic-c >/dev/null
+KEPT_COUNT_3="$(grep -c '^- ' "$INDEX/.devlog/devlog.md")"
+[ "$KEPT_COUNT_3" -eq 3 ] && echo "PASS: third partial keep accumulates to three index lines" || { echo "FAIL: expected 3 index lines, got $KEPT_COUNT_3"; FAIL=1; }
+HEADING_LINE="$(grep -n '^## Kept 索引' "$INDEX/.devlog/devlog.md" | head -1 | cut -d: -f1)"
+PREV_LINE="$(sed -n "$((HEADING_LINE - 1))p" "$INDEX/.devlog/devlog.md")"
+PREV2_LINE="$(sed -n "$((HEADING_LINE - 2))p" "$INDEX/.devlog/devlog.md")"
+if [ -z "$PREV_LINE" ] && [ -n "$PREV2_LINE" ]; then
+  echo "PASS: exactly one blank line separates content from ## Kept 索引 after three keep-move.sh calls"
+else
+  echo "FAIL: expected exactly one blank line before ## Kept 索引 after three keep-move.sh calls, got [$PREV_LINE] then [$PREV2_LINE]"
+  FAIL=1
+fi
+
+DESC="$TMP/desc"
+mkdir -p "$DESC/.devlog"
+export CLAUDE_PROJECT_DIR="$DESC"
+printf '# project\n\n' > "$DESC/.devlog/devlog.md"
+make_round "$DESC/.devlog/devlog.md" 1 DONE
+make_round "$DESC/.devlog/devlog.md" 2 DONE
+make_round "$DESC/.devlog/devlog.md" 3 IN_PROGRESS
+printf '%s\n' '{"round": 3, "opened_at": "now"}' > "$DESC/.devlog/.round-open"
+bash "$SCRIPT_DIR/keep-move.sh" --from 1 --to 1 --name with-desc --desc "調整 span 模式的門檻" >/dev/null
+grep -q '調整 span 模式的門檻' "$DESC/.devlog/devlog.md" && echo "PASS: --desc text written into Kept 索引 line" || { echo "FAIL: expected desc text in index line"; FAIL=1; }
+bash "$SCRIPT_DIR/keep-move.sh" --from 2 --to 2 --name no-desc >/dev/null
+LINE_NO_DESC="$(grep 'devlog.no-desc.md' "$DESC/.devlog/devlog.md")"
+case "$LINE_NO_DESC" in
+  *"kept_at "*","*) echo "FAIL: unexpected extra trailing segment without --desc: $LINE_NO_DESC"; FAIL=1 ;;
+  *"kept_at "*) echo "PASS: omitting --desc keeps the plain kept_at-only line" ;;
+  *) echo "FAIL: index line for no-desc missing: $LINE_NO_DESC"; FAIL=1 ;;
+esac
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/hooks/scripts/tests/test-kept-list.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Self-check for kept-list.sh (docs/design/keep.md "Kept index" +
+# /devlog-tracker:overview). Plain read only -- no workspace verification.
+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_exit() {
+  local desc="$1" expected="$2" actual="$3"
+  if [ "$actual" -eq "$expected" ]; then echo "PASS: $desc"
+  else echo "FAIL: $desc (expected $expected got $actual)"; FAIL=1; fi
+}
+
+# --- No devlog.md at all -> NO_INDEX ----------------------------------------
+OUT="$(bash "$SCRIPT_DIR/kept-list.sh" 2>&1)"
+assert_exit "no devlog.md -> 0" 0 $?
+case "$OUT" in
+  *"NO_INDEX"*) echo "PASS: reports NO_INDEX when devlog.md is absent" ;;
+  *) echo "FAIL: expected NO_INDEX, got $OUT"; FAIL=1 ;;
+esac
+
+# --- devlog.md exists but no Kept 索引 -> NO_INDEX --------------------------
+echo '## Round 1 — 2026-09-12T00:00:00+08:00
+
+### Summary
+fixture
+
+### Handoff
+#### 現況
+fixture
+
+### Status
+DONE' > "$DEVLOG_DIR/devlog.md"
+OUT="$(bash "$SCRIPT_DIR/kept-list.sh" 2>&1)"
+assert_exit "devlog.md with no index -> 0" 0 $?
+case "$OUT" in
+  *"NO_INDEX"*) echo "PASS: reports NO_INDEX when no Kept 索引 block exists" ;;
+  *) echo "FAIL: expected NO_INDEX, got $OUT"; FAIL=1 ;;
+esac
+
+# --- Kept 索引 present, target file exists -> EXISTS=1 ----------------------
+printf 'kept content\n' > "$DEVLOG_DIR/devlog.foo-bar.md"
+printf '\n## Kept 索引\n- `devlog.foo-bar.md`：Round 1-1，kept_at 2026-09-12T00:00:00+08:00，foo bar 主題\n' >> "$DEVLOG_DIR/devlog.md"
+OUT="$(bash "$SCRIPT_DIR/kept-list.sh" 2>&1)"
+assert_exit "index with one existing file -> 0" 0 $?
+case "$OUT" in
+  *"FILE="*"devlog.foo-bar.md"*"EXISTS=1"*) echo "PASS: existing kept file reported with EXISTS=1" ;;
+  *) echo "FAIL: expected FILE=...devlog.foo-bar.md EXISTS=1, got $OUT"; FAIL=1 ;;
+esac
+
+# --- Ghost row: index line present, file missing on disk -> EXISTS=0 -------
+rm -f "$DEVLOG_DIR/devlog.foo-bar.md"
+OUT="$(bash "$SCRIPT_DIR/kept-list.sh" 2>&1)"
+assert_exit "ghost row -> 0" 0 $?
+case "$OUT" in
+  *"FILE="*"devlog.foo-bar.md"*"EXISTS=0"*) echo "PASS: ghost kept file reported with EXISTS=0" ;;
+  *) echo "FAIL: expected FILE=...devlog.foo-bar.md EXISTS=0, got $OUT"; FAIL=1 ;;
+esac
+
+# --- Multiple entries listed, one per line -----------------------------------
+printf 'kept content two\n' > "$DEVLOG_DIR/devlog.second-topic.md"
+sed -i.bak '$ a\
+- `devlog.second-topic.md`：Round 2-2，kept_at 2026-09-13T00:00:00+08:00
+' "$DEVLOG_DIR/devlog.md"
+rm -f "$DEVLOG_DIR/devlog.md.bak"
+OUT="$(bash "$SCRIPT_DIR/kept-list.sh" 2>&1)"
+assert_exit "index with two entries -> 0" 0 $?
+LINE_COUNT="$(printf '%s\n' "$OUT" | grep -c '^FILE=')"
+[ "$LINE_COUNT" -eq 2 ] && echo "PASS: two FILE= lines printed for two index entries" || { echo "FAIL: expected 2 FILE= lines, got $LINE_COUNT"; FAIL=1; }
+case "$OUT" in
+  *"devlog.second-topic.md"*"EXISTS=1"*) echo "PASS: second-topic file reported with EXISTS=1" ;;
+  *) echo "FAIL: expected devlog.second-topic.md EXISTS=1, got $OUT"; FAIL=1 ;;
+esac
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/hooks/scripts/tests/test-lessons-append.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# Self-check for lessons-append.sh (docs/design/lessons-mode.md "Storage" /
+# "## Lessons 索引" / "Write mechanism"). No framework, plain
+# assert-and-exit, matching this repo's existing style.
+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_exit() {
+  local desc="$1" expected="$2" actual="$3"
+  if [ "$actual" -eq "$expected" ]; then echo "PASS: $desc"
+  else echo "FAIL: $desc (expected $expected got $actual)"; FAIL=1; fi
+}
+
+echo '## Round 1 — 2026-09-12T00:00:00+08:00
+
+### Summary
+fixture
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 現況
+fixture
+
+### Status
+DONE' > "$DEVLOG_DIR/devlog.md"
+
+# --- Refused without the main switch ---------------------------------------
+OUT="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic foo --text "x" 2>&1)"
+assert_exit "no .enabled -> exit 1" 1 $?
+case "$OUT" in
+  *"NOT_ENABLED"*) echo "PASS: reports NOT_ENABLED" ;;
+  *) echo "FAIL: expected NOT_ENABLED, got $OUT"; FAIL=1 ;;
+esac
+
+touch "$DEVLOG_DIR/.enabled"
+
+# --- Refused without lessons-enabled ---------------------------------------
+OUT="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic foo --text "x" 2>&1)"
+assert_exit "enabled but lessons off -> exit 1" 1 $?
+case "$OUT" in
+  *"LESSONS_NOT_ENABLED"*) echo "PASS: reports LESSONS_NOT_ENABLED" ;;
+  *) echo "FAIL: expected LESSONS_NOT_ENABLED, got $OUT"; FAIL=1 ;;
+esac
+
+touch "$DEVLOG_DIR/.lessons-enabled"
+
+# --- Missing --text ----------------------------------------------------------
+bash "$SCRIPT_DIR/lessons-append.sh" --topic foo >/dev/null 2>&1
+assert_exit "missing --text -> exit 1" 1 $?
+
+# --- Invalid topic (path traversal) -----------------------------------------
+bash "$SCRIPT_DIR/lessons-append.sh" --topic "../etc" --text "x" >/dev/null 2>&1
+assert_exit "path-traversal topic -> exit 1" 1 $?
+
+# --- Reserved topic names ----------------------------------------------------
+bash "$SCRIPT_DIR/lessons-append.sh" --topic "archive" --text "x" >/dev/null 2>&1
+assert_exit "topic 'archive' rejected -> exit 1" 1 $?
+bash "$SCRIPT_DIR/lessons-append.sh" --topic "lessons" --text "x" >/dev/null 2>&1
+assert_exit "topic 'lessons' rejected -> exit 1" 1 $?
+
+# --- First entry creates the topic file and the header ----------------------
+OUT="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic "keep-move-bug" --text "第一次卡在 keep-move.sh 沒處理缺號範圍。後來改成逐一檢查連續性。")"
+assert_exit "first entry -> 0" 0 $?
+case "$OUT" in
+  *"PATH=.devlog/devlog.lessons.keep-move-bug.md"*) echo "PASS: reports PATH" ;;
+  *) echo "FAIL: expected PATH=..., got $OUT"; FAIL=1 ;;
+esac
+TARGET="$DEVLOG_DIR/devlog.lessons.keep-move-bug.md"
+if [ -f "$TARGET" ]; then echo "PASS: topic file created"; else echo "FAIL: topic file missing"; FAIL=1; fi
+grep -q '^# Lessons: keep-move-bug$' "$TARGET" && echo "PASS: header present" || { echo "FAIL: header missing"; FAIL=1; }
+grep -q '^## 2026-\|^## [0-9]' "$TARGET" && echo "PASS: timestamped entry heading present" || { echo "FAIL: no entry heading"; FAIL=1; }
+grep -q '第一次卡在 keep-move.sh' "$TARGET" && echo "PASS: entry text present" || { echo "FAIL: entry text missing"; FAIL=1; }
+
+# --- devlog.<name>.md / .md normalization on --topic input ------------------
+OUT2="$(bash "$SCRIPT_DIR/lessons-append.sh" --topic "devlog.lessons.keep-move-bug.md" --text "第二筆，測試正規化。")"
+assert_exit "prefixed/suffixed topic input normalizes to the same file -> 0" 0 $?
+case "$OUT2" in
+  *"PATH=.devlog/devlog.lessons.keep-move-bug.md"*) echo "PASS: normalized-input call reports the same PATH" ;;
+  *) echo "FAIL: expected PATH=.devlog/devlog.lessons.keep-move-bug.md, got: $OUT2"; FAIL=1 ;;
+esac
+ENTRY_COUNT="$(grep -c '^## ' "$TARGET")"
+if [ "$ENTRY_COUNT" = "2" ]; then
+  echo "PASS: second call appended to the SAME file (normalization collapsed devlog.lessons.<x>.md to <x>)"
+else
+  echo "FAIL: expected 2 entries in one file, got $ENTRY_COUNT (normalization likely created a second file)"
+  FAIL=1
+fi
+
+# --- Lessons 索引 rebuilt: one line, correct count and latest title ---------
+INDEX_BLOCK="$(awk '/^## Lessons 索引/{grab=1;next} grab{print}' "$DEVLOG_DIR/devlog.md")"
+case "$INDEX_BLOCK" in
+  *"devlog.lessons.keep-move-bug.md"*"2 則"*"第二筆，測試正規化。"*)
+    echo "PASS: index line has file, count=2, and latest entry's title" ;;
+  *)
+    echo "FAIL: unexpected index block: $INDEX_BLOCK"; FAIL=1 ;;
+esac
+
+# --- A second topic gets its own file and its own index line ----------------
+bash "$SCRIPT_DIR/lessons-append.sh" --topic "span-mode-detour" --text "一開始想在 hook 裡分辨自動續接跟真人插話，後來確認做不到，改成明確標記。" >/dev/null
+INDEX_BLOCK2="$(awk '/^## Lessons 索引/{grab=1;next} grab{print}' "$DEVLOG_DIR/devlog.md")"
+LINE_COUNT="$(printf '%s\n' "$INDEX_BLOCK2" | grep -c '^- `devlog.lessons\.')"
+if [ "$LINE_COUNT" = "2" ]; then
+  echo "PASS: index has one line per topic file (2 topics -> 2 lines)"
+else
+  echo "FAIL: expected 2 index lines, got $LINE_COUNT: $INDEX_BLOCK2"
+  FAIL=1
+fi
+case "$INDEX_BLOCK2" in
+  *"devlog.lessons.span-mode-detour.md"*"1 則"*) echo "PASS: second topic's own line present" ;;
+  *) echo "FAIL: second topic missing from index: $INDEX_BLOCK2"; FAIL=1 ;;
+esac
+
+# --- Index rebuild never duplicates the heading -----------------------------
+HEADING_COUNT="$(grep -c '^## Lessons 索引' "$DEVLOG_DIR/devlog.md")"
+if [ "$HEADING_COUNT" = "1" ]; then
+  echo "PASS: exactly one '## Lessons 索引' heading after multiple appends"
+else
+  echo "FAIL: expected exactly one heading, got $HEADING_COUNT"
+  FAIL=1
+fi
+
+# --- Title truncates at the first 。/. -------------------------------------
+bash "$SCRIPT_DIR/lessons-append.sh" --topic "punct" --text "先卡住了。後來才發現是路徑問題，多寫了一段沒用的重試邏輯。" >/dev/null
+INDEX_BLOCK3="$(awk '/^## Lessons 索引/{grab=1;next} grab{print}' "$DEVLOG_DIR/devlog.md")"
+case "$INDEX_BLOCK3" in
+  *"「先卡住了。」"*) echo "PASS: title truncated at first 。" ;;
+  *) echo "FAIL: expected title truncated at first 。, got: $INDEX_BLOCK3"; FAIL=1 ;;
+esac
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/hooks/scripts/tests/test-lessons-drift-set.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FAIL=0
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+OUT="$(CLAUDE_PROJECT_DIR="$TMP" bash "$SCRIPT_DIR/lessons-drift-set.sh" 5)"
+[ "$OUT" = "NOT_STARTED" ] && echo "PASS: not started" || { echo "FAIL: $OUT"; FAIL=1; }
+
+mkdir -p "$TMP/.devlog"
+touch "$TMP/.devlog/.enabled"
+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"
+
+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" \
+  && echo "PASS: count preserved" || { echo "FAIL: count reset"; FAIL=1; }
+grep -q '"threshold": 5' "$TMP/.devlog/.lessons-drift-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"
+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" \
+  && echo "PASS: create count 0" || { echo "FAIL: create count"; FAIL=1; }
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi