devlog-tracker 0.22.0

package/hooks/scripts/redact-prompt.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Sourced helper: redact_prompt reads stdin and writes sanitized prompt text.
+redact_prompt() {
+  awk '
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/ { skip=1; print "（已遮罩）"; next }
+    skip && /-----END [A-Z ]*PRIVATE KEY-----/ { skip=0; next }
+    skip { next }
+    { print }
+  ' | sed -E \
+    -e 's/sk-ant-api03-[A-Za-z0-9_-]+/（已遮罩）/g' \
+    -e 's/sk-ant-[A-Za-z0-9_-]{20,}/（已遮罩）/g' \
+    -e 's/sk-[A-Za-z0-9]{20,}/（已遮罩）/g' \
+    -e 's/ghp_[A-Za-z0-9]{20,}/（已遮罩）/g' \
+    -e 's/github_pat_[A-Za-z0-9_]{20,}/（已遮罩）/g' \
+    -e 's/xox[baprs]-[A-Za-z0-9-]{10,}/（已遮罩）/g' \
+    -e 's/AKIA[A-Z0-9]{16}/（已遮罩）/g' \
+    -e 's/Bearer [A-Za-z0-9._+=/-]{20,}/（已遮罩）/g' \
+    -e 's/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/（已遮罩）/g'
+}

package/hooks/scripts/resume-devlog.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$SCRIPT_DIR/json-field.sh"
+
+NAME=""
+if [ "${1:-}" = "--name" ]; then
+  NAME="${2:-}"
+else
+  echo "MISSING_NAME" >&2
+  exit 1
+fi
+case "$NAME" in devlog.md|*'/'*|*'\'*|*'..'*) echo "INVALID_NAME" >&2; exit 1 ;; esac
+case "$NAME" in devlog.*) NAME="${NAME#devlog.}" ;; esac
+case "$NAME" in *.md) NAME="${NAME%.md}" ;; esac
+NAME="$(slugify "$NAME")"
+[ -n "$NAME" ] && [ "$NAME" != "archive" ] && [ "${#NAME}" -le 64 ] \
+  || { echo "INVALID_NAME" >&2; exit 1; }
+
+DEVLOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.devlog"
+FILE="$DEVLOG_DIR/devlog.$NAME.md"
+if [ ! -f "$FILE" ]; then
+  candidates=""
+  shopt -s nullglob
+  for path in "$DEVLOG_DIR"/devlog.*.md; do
+    leaf="${path##*/}"
+    case "$leaf" in devlog.md|devlog.archive.md) continue ;; esac
+    candidate="${leaf#devlog.}"
+    candidate="${candidate%.md}"
+    [ -z "$candidates" ] || candidates="$candidates,"
+    candidates="$candidates$candidate"
+  done
+  echo "MISSING"
+  echo "CANDIDATES=$candidates"
+  exit 1
+fi
+printf 'PATH=.devlog/devlog.%s.md\n' "$NAME"
+cat "$FILE"

package/hooks/scripts/round-start.sh

@@ -0,0 +1,333 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook：每次使用者送出新訊息時執行。
+# 互動輪次：先（如有）把上一輪未收尾標成 INTERRUPTED，再追加本輪 User Input
+# skeleton，然後把 .turn-start 設成「寫完 skeleton 之後」的雜湊，供 Stop hook
+# 判斷 Claude 有沒有再寫 Summary/Handoff。
+# Span 開著且檔案格式有效時不開新 Round。
+# fail-open：這支腳本本身出任何問題都不該影響使用者送出訊息，一律 exit 0。
+
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$HOOKS_DIR/json-field.sh"
+# shellcheck source=redact-prompt.sh
+. "$HOOKS_DIR/redact-prompt.sh"
+# shellcheck source=devlog-lock.sh
+. "$HOOKS_DIR/devlog-lock.sh"
+# shellcheck source=devlog-md.sh
+. "$HOOKS_DIR/devlog-md.sh"
+# shellcheck source=workspace-snapshot.sh
+. "$HOOKS_DIR/workspace-snapshot.sh"
+# shellcheck source=detect-pending-question.sh
+. "$HOOKS_DIR/detect-pending-question.sh"
+# shellcheck source=devlog-path.sh
+. "$HOOKS_DIR/devlog-path.sh"
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+[ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
+devlog_resolve_paths "$PROJECT_DIR"
+ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"
+SPAN_FILE="$DEVLOG_DIR/.span-open"
+CHECKPOINT_FILE="$DEVLOG_DIR/.checkpoint-state"
+SEGMENT_FILE="$DEVLOG_DIR/.segment-state"
+ROUND_OPEN="$DEVLOG_DIR/.round-open"
+AWAITING_FILE="$DEVLOG_DIR/.awaiting-reply"
+DRIFT_FILE="$DEVLOG_DIR/.lessons-drift-state"
+
+devlog_lock_acquire
+trap 'devlog_lock_release' EXIT
+
+INPUT="$(cat 2>/dev/null || true)"
+SESSION_ID="$(json_str_field "$INPUT" session_id)"
+
+if [ -f "$ROUND_OPEN" ]; then
+  DANGLING_DETAIL=""
+  if [ -n "$(detect_pending_question "$(json_str_field "$INPUT" transcript_path)")" ]; then
+    DANGLING_DETAIL="awaiting_question"
+  fi
+  bash "$HOOKS_DIR/close-open-round.sh" "dangling:next_prompt" "$DANGLING_DETAIL" || true
+fi
+
+FOLD_ROUND=""
+FOLD_NOTE="（回覆上一輪的問題）"
+if [ -f "$AWAITING_FILE" ]; then
+  AWAIT_ROUND="$(json_int_get "$AWAITING_FILE" round)"
+  rm -f "$AWAITING_FILE" 2>/dev/null || true
+  case "$AWAIT_ROUND" in
+    ''|*[!0-9]*) AWAIT_ROUND='' ;;
+  esac
+  if [ -n "$AWAIT_ROUND" ] && [ -f "$DEVLOG_FILE" ]; then
+    CURRENT_LAST="$(devlog_list_round_starts "$DEVLOG_FILE" | awk 'END { print $2 }')"
+    if [ "$CURRENT_LAST" = "$AWAIT_ROUND" ]; then
+      FOLD_ROUND="$AWAIT_ROUND"
+    fi
+  fi
+fi
+
+SPAN_SKIP=0
+if [ -f "$SPAN_FILE" ]; then
+  SPAN_TICKS="$(json_int_get "$SPAN_FILE" ticks_since_checkin)"
+  SPAN_MAX="$(json_int_get "$SPAN_FILE" max_silent_ticks)"
+  case "$SPAN_TICKS" in ''|*[!0-9]*) SPAN_TICKS='' ;; esac
+  case "$SPAN_MAX" in ''|*[!0-9]*) SPAN_MAX='' ;; esac
+  if [ -n "$SPAN_TICKS" ] && [ -n "$SPAN_MAX" ]; then
+    SPAN_SKIP=1
+  fi
+fi
+
+PROMPT="$(json_str_field "$INPUT" prompt)"
+
+# 背景 task-notification（例如子 agent 完成通知）不是使用者真的打字：不留原始
+# XML，換成精簡摘要；也不當成新話題開新 Round，改折進最後一個 Round 當段落。
+TASK_NOTIF=0
+case "$PROMPT" in
+  *'<task-notification>'*'</task-notification>'*) TASK_NOTIF=1 ;;
+esac
+if [ "$TASK_NOTIF" -eq 1 ]; then
+  NOTIF_SUMMARY="$(printf '%s\n' "$PROMPT" | sed -n 's/.*<summary>\(.*\)<\/summary>.*/\1/p' | head -1)"
+  NOTIF_STATUS="$(printf '%s\n' "$PROMPT" | sed -n 's/.*<status>\(.*\)<\/status>.*/\1/p' | head -1)"
+  NOTIF_TASKID="$(printf '%s\n' "$PROMPT" | sed -n 's/.*<task-id>\(.*\)<\/task-id>.*/\1/p' | head -1)"
+  [ -n "$NOTIF_SUMMARY" ] || NOTIF_SUMMARY="背景任務通知"
+  NOTIF_META=""
+  [ -n "$NOTIF_STATUS" ] && NOTIF_META="status=$NOTIF_STATUS"
+  if [ -n "$NOTIF_TASKID" ]; then
+    if [ -n "$NOTIF_META" ]; then NOTIF_META="$NOTIF_META, task-id=$NOTIF_TASKID"
+    else NOTIF_META="task-id=$NOTIF_TASKID"
+    fi
+  fi
+  if [ -n "$NOTIF_META" ]; then
+    PROMPT="${NOTIF_SUMMARY}（${NOTIF_META}）"
+  else
+    PROMPT="$NOTIF_SUMMARY"
+  fi
+fi
+
+if [ "$SPAN_SKIP" -eq 1 ]; then
+  FOLD_ROUND=""
+fi
+
+if [ "$TASK_NOTIF" -eq 1 ] && [ -z "$FOLD_ROUND" ] && [ "$SPAN_SKIP" -eq 0 ] && [ -f "$DEVLOG_FILE" ]; then
+  TASK_NOTIF_LAST="$(devlog_list_round_starts "$DEVLOG_FILE" | awk 'END { print $2 }')"
+  case "$TASK_NOTIF_LAST" in
+    ''|*[!0-9]*) : ;;
+    *)
+      FOLD_ROUND="$TASK_NOTIF_LAST"
+      FOLD_NOTE="（背景任務通知）"
+      ;;
+  esac
+fi
+
+MISMATCH_FILE="$DEVLOG_DIR/.workspace-mismatch"
+rm -f "$MISMATCH_FILE" 2>/dev/null || true
+if [ "$SPAN_SKIP" -eq 0 ] && [ "$TASK_NOTIF" -eq 0 ] && [ -f "$DEVLOG_FILE" ]; then
+  CLAIM_ST="$(workspace_claim_state "$PROJECT_DIR" "$DEVLOG_FILE" 2>/dev/null || echo NO_CLAIM)"
+  if [ "$CLAIM_ST" = "MISMATCH" ]; then
+    LAST_START="$(devlog_list_round_starts "$DEVLOG_FILE" | awk 'END { print $1 }')"
+    LAST_END="$(devlog_block_end "$DEVLOG_FILE" "$LAST_START")"
+    CLAIMED_WS="$(devlog_round_workspace_body "$DEVLOG_FILE" "$LAST_START" "$LAST_END")"
+    LIVE_WS="$(workspace_snapshot "$PROJECT_DIR")"
+    if [ -n "$LIVE_WS" ]; then
+      printf '%s\n' "$LIVE_WS" > "$MISMATCH_FILE" 2>/dev/null || true
+      printf '%s\n' "上一輪 Handoff「#### 工作區」跟目前 git 不符。先在這一輪追加 ### 段落，寫宣稱 vs 實際（實際用下面「實際」逐字內容），再依實際工作樹行動，不要照上一輪「現況／下一步」的字面。"
+      printf '\n宣稱：\n%s\n\n實際：\n%s\n' "$CLAIMED_WS" "$LIVE_WS"
+
+      if [ -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+        if [ ! -f "$DRIFT_FILE" ]; then
+          printf '%s\n' '{"mismatch_count": 0, "threshold": 3}' \
+            > "$DRIFT_FILE" 2>/dev/null || true
+        fi
+        DRIFT_COUNT="$(json_int_get "$DRIFT_FILE" mismatch_count)"
+        DRIFT_MAX="$(json_int_get "$DRIFT_FILE" threshold)"
+        case "$DRIFT_COUNT" in ''|*[!0-9]*) DRIFT_COUNT=0 ;; esac
+        case "$DRIFT_MAX" in ''|*[!0-9]*) DRIFT_MAX=3 ;; esac
+        NEW_DRIFT_COUNT=$((DRIFT_COUNT + 1))
+        if [ "$NEW_DRIFT_COUNT" -ge "$DRIFT_MAX" ]; then
+          json_int_set "$DRIFT_FILE" mismatch_count 0
+          printf '\n[Lessons Mode 提示] 工作區宣稱與實際不符已累積出現 %s 次（門檻 %s）。可考慮用 lessons-append.sh 記一筆流程教訓，非強制。\n' "$NEW_DRIFT_COUNT" "$DRIFT_MAX"
+        else
+          json_int_set "$DRIFT_FILE" mismatch_count "$NEW_DRIFT_COUNT"
+        fi
+      fi
+    fi
+  fi
+fi
+
+if [ -n "$FOLD_ROUND" ]; then
+  devlog_reopen_last_round "$DEVLOG_FILE" "$ROUND_CURRENT" || : > "$ROUND_CURRENT"
+  if [ -z "$PROMPT" ]; then
+    PROMPT="（無 prompt）"
+  fi
+  TRUNC_NOTE=""
+  if [ "${#PROMPT}" -gt 4000 ]; then
+    PROMPT="${PROMPT:0:4000}"
+    TRUNC_NOTE="（後略，已截斷至 4000 字）"
+  fi
+  PROMPT="$(printf '%s' "$PROMPT" | sed 's/```/⟨fence⟩/g')"
+  PROMPT="$(printf '%s' "$PROMPT" | redact_prompt)"
+
+  TS="$(date +%H:%M 2>/dev/null || echo unknown)"
+  FULL_TS="$(date +%Y-%m-%dT%H:%M:%S%z 2>/dev/null || echo unknown)"
+  START_LINE="$(devlog_list_round_starts "$ROUND_CURRENT" | awk 'END { print $1 }')"
+  END_LINE="$(devlog_block_end "$ROUND_CURRENT" "$START_LINE")"
+  SEG_N=$(( $(devlog_count_segments "$ROUND_CURRENT" "$START_LINE" "$END_LINE") + 1 ))
+
+  SEG_TMP="$DEVLOG_DIR/.segment-insert.tmp"
+  {
+    printf '### 段落 %s - %s%s\n' "$SEG_N" "$TS" "$FOLD_NOTE"
+    printf '```text\n'
+    printf '%s\n' "$PROMPT"
+    printf '```\n'
+    if [ -n "$TRUNC_NOTE" ]; then
+      printf '%s\n' "$TRUNC_NOTE"
+    fi
+    printf '\n'
+  } > "$SEG_TMP" 2>/dev/null || true
+
+  if [ -f "$SEG_TMP" ]; then
+    devlog_insert_before_summary "$ROUND_CURRENT" "$START_LINE" "$END_LINE" "$SEG_TMP" > "$ROUND_CURRENT.tmp" 2>/dev/null \
+      && mv "$ROUND_CURRENT.tmp" "$ROUND_CURRENT" 2>/dev/null || rm -f "$ROUND_CURRENT.tmp" 2>/dev/null || true
+    rm -f "$SEG_TMP" 2>/dev/null || true
+  fi
+
+  printf '{"round": %s, "opened_at": "%s", "file": "%s"}\n' "$FOLD_ROUND" "$FULL_TS" "${DEVLOG_FILE##*/}" > "$ROUND_OPEN" 2>/dev/null || true
+elif [ "$SPAN_SKIP" -eq 0 ]; then
+  if [ -z "$PROMPT" ]; then
+    PROMPT="（無 prompt）"
+  fi
+  TRUNC_NOTE=""
+  if [ "${#PROMPT}" -gt 4000 ]; then
+    PROMPT="${PROMPT:0:4000}"
+    TRUNC_NOTE="（後略，已截斷至 4000 字）"
+  fi
+  PROMPT="$(printf '%s' "$PROMPT" | sed 's/```/⟨fence⟩/g')"
+  PROMPT="$(printf '%s' "$PROMPT" | redact_prompt)"
+
+  # 救孤兒：正常情況下這裡 .round-current.md 應該已經是空的／不存在（上一輪
+  # 已經正常收尾併回 devlog.md）。如果不是——例如上一次 Stop 或
+  # close-open-round.sh 併入失敗，內容被孤立在這裡卻沒有任何機制知道要去
+  # 救它——在下面用 `>` 蓋掉新 skeleton 之前，先把它搶救併回 devlog.md，
+  # 而不是讓 `>` 直接蓋掉遺失。正常情況（檔案已空/不存在）這裡是 no-op。
+  # 必須放在下面的 LAST_N 掃描之前：這樣被搶救回來的孤兒 Round 才會被算進
+  # 編號，下一輪不會意外沿用它的號碼。
+  devlog_merge_round_current "$DEVLOG_FILE" "$ROUND_CURRENT"
+
+  LAST_N=0
+  if [ -f "$DEVLOG_FILE" ]; then
+    LAST_N="$(awk '
+      /^[ \t]*```/ { fence = !fence }
+      !fence && /^## Round / {
+        split($0, parts, /[ \t]+/)
+        n = parts[3] + 0
+        if (n > last) last = n
+      }
+      END { print last + 0 }
+    ' "$DEVLOG_FILE" 2>/dev/null || echo 0)"
+    case "$LAST_N" in ''|*[!0-9]*) LAST_N=0 ;; esac
+  fi
+  NEXT_N=$((LAST_N + 1))
+  TS="$(date +%Y-%m-%dT%H:%M:%S%z 2>/dev/null || echo unknown)"
+
+  {
+    printf '## Round %s — %s\n\n' "$NEXT_N" "$TS"
+    printf '### User Input\n'
+    printf '```text\n'
+    printf '%s\n' "$PROMPT"
+    printf '```\n'
+    if [ -n "$TRUNC_NOTE" ]; then
+      printf '%s\n' "$TRUNC_NOTE"
+    fi
+    printf '\n### Status\nIN_PROGRESS\n'
+  } > "$ROUND_CURRENT" 2>/dev/null || true
+
+  if [ -f "$ROUND_CURRENT" ]; then
+    printf '{"round": %s, "opened_at": "%s", "file": "%s"}\n' "$NEXT_N" "$TS" "${DEVLOG_FILE##*/}" > "$ROUND_OPEN" 2>/dev/null || true
+  fi
+fi
+
+if [ -f "$ROUND_CURRENT" ]; then
+  cksum < "$ROUND_CURRENT" > "$DEVLOG_DIR/.turn-start" 2>/dev/null || true
+else
+  echo "MISSING" > "$DEVLOG_DIR/.turn-start" 2>/dev/null || true
+fi
+
+SPAN_WILL_PASS_THROUGH=0
+if [ -f "$SPAN_FILE" ]; then
+  SPAN_TICKS="$(json_int_get "$SPAN_FILE" ticks_since_checkin)"
+  SPAN_MAX="$(json_int_get "$SPAN_FILE" max_silent_ticks)"
+  case "$SPAN_TICKS" in ''|*[!0-9]*) SPAN_TICKS='' ;; esac
+  case "$SPAN_MAX" in ''|*[!0-9]*) SPAN_MAX='' ;; esac
+  if [ -n "$SPAN_TICKS" ]; then
+    NEW_TICKS=$((SPAN_TICKS + 1))
+    json_int_set "$SPAN_FILE" ticks_since_checkin "$NEW_TICKS"
+    if [ -n "$SPAN_MAX" ] && [ "$NEW_TICKS" -lt "$SPAN_MAX" ]; then
+      SPAN_WILL_PASS_THROUGH=1
+    fi
+  fi
+fi
+
+if [ "$SPAN_WILL_PASS_THROUGH" -eq 0 ] && [ -z "$FOLD_ROUND" ] && [ -f "$CHECKPOINT_FILE" ]; then
+  CP_ROUNDS="$(json_int_get "$CHECKPOINT_FILE" rounds_since_checkpoint)"
+  case "$CP_ROUNDS" in
+    ''|*[!0-9]*) : ;;
+    *)
+      NEW_CP_ROUNDS=$((CP_ROUNDS + 1))
+      json_int_set "$CHECKPOINT_FILE" rounds_since_checkpoint "$NEW_CP_ROUNDS"
+      ;;
+  esac
+fi
+
+if [ -f "$SEGMENT_FILE" ]; then
+  SEG_EPOCH="$(json_int_get "$SEGMENT_FILE" last_change_epoch)"
+  SEG_MAX="$(json_int_get "$SEGMENT_FILE" max_silent_seconds)"
+  SEG_SUM_KEY="$(grep -o '"last_seen_cksum"[[:space:]]*:' "$SEGMENT_FILE" 2>/dev/null || echo '')"
+  case "$SEG_EPOCH" in ''|*[!0-9]*) SEG_EPOCH='' ;; esac
+  case "$SEG_MAX" in ''|*[!0-9]*) SEG_MAX='' ;; esac
+  if [ -n "$SEG_EPOCH" ] && [ -n "$SEG_MAX" ] && [ -n "$SEG_SUM_KEY" ]; then
+    SEG_NOW="$(date +%s 2>/dev/null || echo '')"
+    case "$SEG_NOW" in
+      ''|*[!0-9]*) : ;;
+      *)
+        if [ -f "$ROUND_CURRENT" ]; then
+          SEG_CUR="$(cksum < "$ROUND_CURRENT" 2>/dev/null | tr -d '\n' || echo '')"
+        else
+          SEG_CUR="MISSING"
+        fi
+        if [ -n "$SEG_CUR" ]; then
+          json_int_set "$SEGMENT_FILE" last_change_epoch "$SEG_NOW"
+          json_str_set "$SEGMENT_FILE" last_seen_cksum "$SEG_CUR"
+          SEG_MT=""; SEG_SZ=""
+          if [ -f "$ROUND_CURRENT" ]; then
+            if SEG_ID="$(stat -f '%m %z' "$ROUND_CURRENT" 2>/dev/null || stat -c '%Y %s' "$ROUND_CURRENT" 2>/dev/null || true)"; then
+              SEG_MT="${SEG_ID%% *}"
+              SEG_SZ="${SEG_ID#* }"
+            fi
+          fi
+          if [ -n "$SEG_MT" ] && [ -n "$SEG_SZ" ]; then
+            if ! grep -q '"last_seen_mtime"' "$SEGMENT_FILE" 2>/dev/null; then
+              SEG_SID="$(json_str_get "$SEGMENT_FILE" session_id 2>/dev/null || true)"
+              if [ -n "$SESSION_ID" ]; then SEG_SID="$SESSION_ID"; fi
+              printf '{"last_change_epoch": %s, "last_seen_cksum": "%s", "last_seen_mtime": "%s", "last_seen_size": "%s", "max_silent_seconds": %s, "session_id": "%s"}\n' \
+                "$SEG_NOW" "$SEG_CUR" "$SEG_MT" "$SEG_SZ" "$SEG_MAX" "${SEG_SID}" > "$SEGMENT_FILE" 2>/dev/null || true
+            else
+              json_str_set "$SEGMENT_FILE" last_seen_mtime "$SEG_MT"
+              json_str_set "$SEGMENT_FILE" last_seen_size "$SEG_SZ"
+              if [ -n "$SESSION_ID" ]; then
+                json_str_set "$SEGMENT_FILE" session_id "$SESSION_ID"
+              fi
+            fi
+          elif [ -n "$SESSION_ID" ]; then
+            json_str_set "$SEGMENT_FILE" session_id "$SESSION_ID"
+            SEG_SESSION="$(json_str_get "$SEGMENT_FILE" session_id)"
+            if [ "$SEG_SESSION" != "$SESSION_ID" ]; then
+              printf '{"last_change_epoch": %s, "last_seen_cksum": "%s", "max_silent_seconds": %s, "session_id": "%s"}\n' \
+                "$SEG_NOW" "$SEG_CUR" "$SEG_MAX" "$SESSION_ID" > "$SEGMENT_FILE" 2>/dev/null || true
+            fi
+          fi
+        fi
+        ;;
+    esac
+  fi
+fi
+
+exit 0

package/hooks/scripts/run-tests.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Run every hook self-check. Usage: bash hooks/scripts/run-tests.sh
+set -uo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FAIL=0
+shopt -s nullglob
+for t in "$DIR"/tests/test-*.sh; do
+  echo "=== $(basename "$t") ==="
+  if ! bash "$t"; then
+    FAIL=1
+  fi
+done
+echo "=== test-adapters.sh ==="
+if ! bash "$DIR/../../cursor/hooks/test-adapters.sh"; then
+  FAIL=1
+fi
+echo "=== codex/test-adapters.sh ==="
+if ! bash "$DIR/../../codex/hooks/test-adapters.sh"; then
+  FAIL=1
+fi
+if [ "$FAIL" -ne 0 ]; then
+  echo "Some hook self-checks FAILED."
+  exit 1
+fi
+echo "All hook self-checks passed."
+exit 0

package/hooks/scripts/segment-watch-set.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# User-invoked: /devlog-tracker:segment-watch filesystem side.
+# Sets Segment Watch's max_silent_seconds threshold. $1 is required: a
+# positive integer number of seconds.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$SCRIPT_DIR/json-field.sh"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DEVLOG_DIR="$PROJECT_DIR/.devlog"
+
+if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
+  echo "NOT_STARTED"
+  exit 0
+fi
+
+SECONDS_ARG="${1:-}"
+case "$SECONDS_ARG" in
+  ''|*[!0-9]*|0)
+    echo "max_silent_seconds must be a positive integer number of seconds, got: $SECONDS_ARG" >&2
+    exit 1
+    ;;
+esac
+
+if [ -f "$DEVLOG_DIR/.segment-state" ]; then
+  json_int_set "$DEVLOG_DIR/.segment-state" max_silent_seconds "$SECONDS_ARG"
+  APPLIED="$(json_int_get "$DEVLOG_DIR/.segment-state" max_silent_seconds)"
+  if [ "$APPLIED" != "$SECONDS_ARG" ]; then
+    # Existing file didn't have a matching max_silent_seconds key to patch
+    # (malformed / hand-edited) -- rebuild it fresh rather than leave the
+    # requested value silently unapplied.
+    LAST_EPOCH="$(json_int_get "$DEVLOG_DIR/.segment-state" last_change_epoch)"
+    LAST_SUM="$(json_str_get "$DEVLOG_DIR/.segment-state" last_seen_cksum)"
+    SESSION="$(json_str_get "$DEVLOG_DIR/.segment-state" session_id)"
+    case "$LAST_EPOCH" in ''|*[!0-9]*) LAST_EPOCH=0 ;; esac
+    printf '%s\n' "{\"last_change_epoch\": ${LAST_EPOCH}, \"last_seen_cksum\": \"${LAST_SUM}\", \"max_silent_seconds\": ${SECONDS_ARG}, \"session_id\": \"${SESSION}\"}" \
+      > "$DEVLOG_DIR/.segment-state" || exit 1
+  fi
+else
+  printf '%s\n' "{\"last_change_epoch\": 0, \"last_seen_cksum\": \"\", \"max_silent_seconds\": ${SECONDS_ARG}, \"session_id\": \"\"}" \
+    > "$DEVLOG_DIR/.segment-state" || exit 1
+fi
+
+echo "SEGMENT_MAX_SILENT_SECONDS=$(json_int_get "$DEVLOG_DIR/.segment-state" max_silent_seconds)"
+exit 0

package/hooks/scripts/segment-watch.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# PreToolUse hook：同一輪若太久沒改 .round-current.md，擋住下一個工具，逼補 ### 段落。
+# fail-open：這支腳本自己出錯一律 exit 0，不該卡死使用者的 session。
+
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$SCRIPT_DIR/json-field.sh"
+# shellcheck source=devlog-md.sh
+. "$SCRIPT_DIR/devlog-md.sh"
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+[ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
+devlog_resolve_paths "$PROJECT_DIR"
+ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"
+SEGMENT_FILE="$DEVLOG_DIR/.segment-state"
+
+INPUT="$(cat 2>/dev/null || true)"
+[ -n "$INPUT" ] || exit 0
+
+TOOL_NAME="$(json_str_field "$INPUT" tool_name)"
+FILE_PATH=""
+COMMAND=""
+if command -v jq >/dev/null 2>&1; then
+  FILE_PATH="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || echo '')"
+  [ "$FILE_PATH" = "null" ] && FILE_PATH=""
+  COMMAND="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo '')"
+  [ "$COMMAND" = "null" ] && COMMAND=""
+else
+  FILE_PATH="$(printf '%s' "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || echo '')"
+  if [ -z "$FILE_PATH" ]; then
+    FILE_PATH="$(printf '%s' "$INPUT" | grep -o '"path"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || echo '')"
+  fi
+  COMMAND="$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || echo '')"
+fi
+
+# Blocked-and-stuck recovery: Bash itself is denied while blocked, so there
+# was no way to run `git status`/`git diff` to see what actually changed —
+# exactly the thing both valves below are asking Claude to reconcile against.
+# Allow a small allowlist of git subcommands that are non-mutating in every
+# documented invocation form (no flag combination writes). Reject anything
+# with shell metacharacters first — chaining/redirection/substitution could
+# otherwise smuggle a second, unrelated command past the git-prefix match.
+is_safe_readonly_git_command() {
+  local cmd
+  cmd="$(printf '%s' "$1" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
+  [ -n "$cmd" ] || return 1
+  case "$cmd" in
+    *';'*|*'&'*|*'|'*|*'`'*|*'$('*|*'>'*|*'<'*|*$'\n'*) return 1 ;;
+  esac
+  case "$cmd" in
+    git\ status|git\ status\ *) return 0 ;;
+    git\ diff|git\ diff\ *) return 0 ;;
+    git\ log|git\ log\ *) return 0 ;;
+    git\ show|git\ show\ *) return 0 ;;
+    git\ rev-parse|git\ rev-parse\ *) return 0 ;;
+  esac
+  return 1
+}
+
+is_devlog_tool_allowed() {
+  case "$1" in
+    Write|Edit|StrReplace|Read|Grep)
+      case "$2" in
+        .devlog/.round-current.md|*/.devlog/.round-current.md) return 0 ;;
+      esac
+      ;;
+    Bash)
+      is_safe_readonly_git_command "$3" && return 0
+      ;;
+  esac
+  return 1
+}
+
+AGENT_ID="$(json_str_field "$INPUT" agent_id)"
+[ "$AGENT_ID" = "null" ] && AGENT_ID=""
+if [ -n "$AGENT_ID" ]; then
+  exit 0
+fi
+
+MISMATCH_FILE="$DEVLOG_DIR/.workspace-mismatch"
+if [ -f "$MISMATCH_FILE" ]; then
+  LIVE_MARK="$(cat "$MISMATCH_FILE" 2>/dev/null || true)"
+  if [ -z "$LIVE_MARK" ]; then
+    rm -f "$MISMATCH_FILE" 2>/dev/null || true
+  else
+    SEGMENTS=""
+    if [ -f "$ROUND_CURRENT" ]; then
+      LAST_START="$(devlog_list_round_starts "$ROUND_CURRENT" | awk 'END { print $1 }')"
+      if [ -n "$LAST_START" ]; then
+        LAST_END="$(devlog_block_end "$ROUND_CURRENT" "$LAST_START")"
+        SEGMENTS="$(devlog_round_segments_body "$ROUND_CURRENT" "$LAST_START" "$LAST_END")"
+      fi
+    fi
+    segments_flat="$(printf '%s' "$SEGMENTS" | tr '\n' '\036')"
+    mark_flat="$(printf '%s' "$LIVE_MARK" | tr '\n' '\036')"
+    # "$mark_flat" is quoted so it is literal; dirty paths with *?[ do not glob.
+    case "$segments_flat" in
+      *"$mark_flat"*) rm -f "$MISMATCH_FILE" 2>/dev/null || true ;;
+      *)
+        if ! is_devlog_tool_allowed "$TOOL_NAME" "$FILE_PATH" "$COMMAND"; then
+          echo "上一輪「#### 工作區」跟目前 git 不符。請先 Read .devlog/.round-current.md，再用 Edit／StrReplace 在這一輪追加 ### 段落，把下面「實際」逐字貼進段落（宣稱 vs 實際）。寫完再呼叫其他工具。不要照上一輪 Handoff「現況／下一步」的字面行動。（唯讀的 git status／diff／log／show／rev-parse 仍可執行，方便自行核對。）" >&2
+          echo "" >&2
+          echo "實際：" >&2
+          printf '%s\n' "$LIVE_MARK" >&2
+          exit 2
+        fi
+        ;;
+    esac
+  fi
+fi
+
+[ -f "$SEGMENT_FILE" ] || exit 0
+
+STORED="$(json_str_get "$SEGMENT_FILE" session_id 2>/dev/null || true)"
+INCOMING="$(json_str_field "$INPUT" session_id)"
+if [ -n "$STORED" ] && [ -n "$INCOMING" ] && [ "$STORED" != "$INCOMING" ]; then
+  exit 0
+fi
+
+SEG_EPOCH="$(json_int_get "$SEGMENT_FILE" last_change_epoch)"
+SEG_MAX="$(json_int_get "$SEGMENT_FILE" max_silent_seconds)"
+SEG_SUM="$(json_str_get "$SEGMENT_FILE" last_seen_cksum)"
+SEG_SUM_KEY="$(grep -o '"last_seen_cksum"[[:space:]]*:' "$SEGMENT_FILE" 2>/dev/null || echo '')"
+
+case "$SEG_EPOCH" in ''|*[!0-9]*) exit 0 ;; esac
+case "$SEG_MAX" in ''|*[!0-9]*) exit 0 ;; esac
+[ -n "$SEG_SUM_KEY" ] || exit 0
+
+persist_seen() {
+  local epoch="$1" sum="$2" mt="$3" sz="$4"
+  json_int_set "$SEGMENT_FILE" last_change_epoch "$epoch"
+  json_str_set "$SEGMENT_FILE" last_seen_cksum "$sum"
+  [ -n "$mt" ] && json_str_set "$SEGMENT_FILE" last_seen_mtime "$mt"
+  [ -n "$sz" ] && json_str_set "$SEGMENT_FILE" last_seen_size "$sz"
+}
+
+devlog_file_identity() {
+  # prints: "<mtime_epoch> <size_bytes>" or empty on failure
+  local f="$1" mt sz
+  if mt="$(stat -f '%m' "$f" 2>/dev/null)" && sz="$(stat -f '%z' "$f" 2>/dev/null)"; then
+    printf '%s %s\n' "$mt" "$sz"
+    return 0
+  fi
+  if mt="$(stat -c '%Y' "$f" 2>/dev/null)" && sz="$(stat -c '%s' "$f" 2>/dev/null)"; then
+    printf '%s %s\n' "$mt" "$sz"
+    return 0
+  fi
+  return 1
+}
+
+NOW="$(date +%s 2>/dev/null || echo '')"
+case "$NOW" in ''|*[!0-9]*) exit 0 ;; esac
+
+ID_MT=""; ID_SZ=""
+if [ -f "$ROUND_CURRENT" ]; then
+  ID="$(devlog_file_identity "$ROUND_CURRENT" || true)"
+  ID_MT="${ID%% *}"
+  ID_SZ="${ID#* }"
+  STORED_MT="$(json_str_get "$SEGMENT_FILE" last_seen_mtime 2>/dev/null || true)"
+  STORED_SZ="$(json_str_get "$SEGMENT_FILE" last_seen_size 2>/dev/null || true)"
+  if [ -n "$ID_MT" ] && [ -n "$ID_SZ" ] && [ "$ID_MT" = "$STORED_MT" ] && [ "$ID_SZ" = "$STORED_SZ" ] && [ -n "$SEG_SUM" ]; then
+    CURRENT="$SEG_SUM"
+  else
+    CURRENT="$(cksum < "$ROUND_CURRENT" 2>/dev/null | tr -d '\n' || echo '')"
+    ID="$(devlog_file_identity "$ROUND_CURRENT" || true)"
+    ID_MT="${ID%% *}"
+    ID_SZ="${ID#* }"
+  fi
+else
+  CURRENT="MISSING"
+  ID_MT=""; ID_SZ=""
+fi
+[ -n "$CURRENT" ] || exit 0
+
+if [ "$CURRENT" != "$SEG_SUM" ]; then
+  persist_seen "$NOW" "$CURRENT" "$ID_MT" "$ID_SZ"
+  exit 0
+fi
+
+[ -n "$TOOL_NAME" ] || exit 0
+
+if is_devlog_tool_allowed "$TOOL_NAME" "$FILE_PATH" "$COMMAND"; then
+  exit 0
+fi
+
+ELAPSED=$((NOW - SEG_EPOCH))
+if [ "$ELAPSED" -ge "$SEG_MAX" ]; then
+  echo "這一輪已經 ${ELAPSED} 秒沒有更新 .devlog/.round-current.md（門檻 ${SEG_MAX} 秒）。請先 Read .devlog/.round-current.md，再用 Edit 或 StrReplace **追加**一段「### 段落」（一行也可以）；禁止用 Write 覆寫整份檔。寫完再繼續呼叫其他工具。（唯讀的 git status／diff／log／show／rev-parse 仍可執行。）" >&2
+  exit 2
+fi
+
+exit 0