devlog-tracker 0.22.0

package/hooks/scripts/files-snapshot.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# Sourced by enforce-devlog.sh (docs/design/files-verify.md, devlog ssot
+# Phase 4). Computes the canonical #### 檔案 category lines — 新增/修改/刪除,
+# comma-joined per category, omitting empty ones — for either the current
+# uncommitted tree state or a single commit, so enforce-devlog.sh can
+# compare Claude's claim against something computed independently.
+#
+# Usage:
+#   files_snapshot "$PROJECT_DIR"          # uncommitted branch (git status)
+#   files_snapshot "$PROJECT_DIR" "$HASH"  # committed branch (git diff-tree)
+#
+# Echoes up to three lines in fixed order (新增, then 修改, then 刪除).
+# Echoes nothing if there's nothing to report outside .devlog/, or if $dir
+# isn't a git repo, or (committed branch) $HASH doesn't resolve to a commit
+# — all fail-open, matching this hook suite's design.
+#
+# Renames are never detected: no -M/--find-renames anywhere below (per
+# docs/design/files-verify.md Decision 5), so git reports a rename as a
+# plain delete+add pair, which is exactly the desired 刪除+新增 split.
+# A status code this function doesn't specifically recognize (e.g. a copy,
+# git status's `C`) is categorized conservatively as 修改 — see
+# docs/design/files-verify.md's Known Limitations.
+#
+# Known limitation: a changed path containing a space is not exactly
+# reversible from the comma-joined output below — same limitation
+# workspace-snapshot.sh's 未提交 list already has.
+files_snapshot() {
+  local dir="${1:-.}" hash="${2:-}"
+  if ! git -C "$dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    return 0
+  fi
+
+  local raw
+  if [ -n "$hash" ]; then
+    git -C "$dir" rev-parse --verify -q "${hash}^{commit}" >/dev/null 2>&1 || return 0
+    raw="$(git -C "$dir" diff-tree --no-commit-id --name-status -r --root "$hash" 2>/dev/null || true)"
+  else
+    raw="$(git -C "$dir" status --short --no-renames 2>/dev/null || true)"
+  fi
+  [ -n "$raw" ] || return 0
+
+  local added='' modified='' deleted='' line code path
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    if [ -n "$hash" ]; then
+      # diff-tree --name-status: "<code>\t<path>" (single-letter code)
+      code="${line%%$'\t'*}"
+      path="${line#*$'\t'}"
+    else
+      # git status --short: "<XY> <path>" (XY is always exactly 2 chars)
+      code="${line:0:2}"
+      path="${line:3}"
+    fi
+    case "$path" in
+      .devlog/*) continue ;;
+    esac
+    case "$code" in
+      '??') added="${added:+$added, }$path" ;;
+      *A*) added="${added:+$added, }$path" ;;
+      *D*) deleted="${deleted:+$deleted, }$path" ;;
+      *) modified="${modified:+$modified, }$path" ;;
+    esac
+  done <<< "$raw"
+
+  [ -n "$added" ] && printf '新增：%s\n' "$added"
+  [ -n "$modified" ] && printf '修改：%s\n' "$modified"
+  [ -n "$deleted" ] && printf '刪除：%s\n' "$deleted"
+  return 0
+}

package/hooks/scripts/json-field.sh

@@ -0,0 +1,76 @@
+# shellcheck shell=bash
+# sourced by hook scripts. Do not execute.
+json_int_get() {
+  local file="$1" key="$2" raw=""
+  [ -f "$file" ] || { echo ''; return 0; }
+  # Read digits from the file text first so leading-zero values like 08
+  # stay visible (jq would coerce them and bash would treat them as octal).
+  raw="$(grep -o "\"${key}\"[[:space:]]*:[[:space:]]*[0-9]\+" "$file" 2>/dev/null | grep -o '[0-9]\+$' || echo '')"
+  if [ -z "$raw" ] && command -v jq >/dev/null 2>&1; then
+    raw="$(jq -r --arg k "$key" '.[$k] | tostring' "$file" 2>/dev/null || echo '')"
+    [ "$raw" = "null" ] && raw=""
+  fi
+  case "$raw" in
+    ''|*[!0-9]*) echo ''; return 0 ;;
+    0) echo 0; return 0 ;;
+    0*) echo ''; return 0 ;;
+    *) echo "$raw"; return 0 ;;
+  esac
+}
+
+json_str_get() {
+  local file="$1" key="$2" raw=""
+  [ -f "$file" ] || { echo ''; return 0; }
+  if command -v jq >/dev/null 2>&1; then
+    raw="$(jq -r --arg k "$key" '.[$k] // empty' "$file" 2>/dev/null || echo '')"
+    [ "$raw" = "null" ] && raw=""
+    printf '%s' "$raw"
+    echo
+    return 0
+  fi
+  raw="$(grep -o "\"${key}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$file" 2>/dev/null | head -1 || echo '')"
+  printf '%s' "$raw" | sed -E "s/^.*\"${key}\"[[:space:]]*:[[:space:]]*\"//; s/\"$//"
+  echo
+}
+
+json_int_set() {
+  local file="$1" key="$2" val="$3"
+  [ -f "$file" ] || return 0
+  case "$val" in ''|*[!0-9]*) return 0 ;; esac
+  awk -v key="$key" -v val="$val" '{
+    pat = "\"" key "\"[[:space:]]*:[[:space:]]*[0-9]+"
+    repl = "\"" key "\": " val
+    gsub(pat, repl)
+    print
+  }' "$file" > "$file.tmp" 2>/dev/null && mv "$file.tmp" "$file" 2>/dev/null || true
+}
+
+json_str_set() {
+  local file="$1" key="$2" val="$3"
+  [ -f "$file" ] || return 0
+  case "$val" in *\"*|*[$'\n']*) return 0 ;; esac
+  awk -v key="$key" -v val="$val" '{
+    pat = "\"" key "\"[[:space:]]*:[[:space:]]*\"[^\"]*\""
+    repl = "\"" key "\": \"" val "\""
+    gsub(pat, repl)
+    print
+  }' "$file" > "$file.tmp" 2>/dev/null && mv "$file.tmp" "$file" 2>/dev/null || true
+}
+
+json_str_field() {
+  local json="$1" key="$2" raw=""
+  if command -v jq >/dev/null 2>&1; then
+    raw="$(printf '%s' "$json" | jq -r --arg k "$key" '.[$k] // empty' 2>/dev/null || echo '')"
+    [ "$raw" = "null" ] && raw=""
+    printf '%s' "$raw"
+    echo
+    return 0
+  fi
+  raw="$(printf '%s' "$json" | grep -o "\"${key}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" 2>/dev/null | head -1 || echo '')"
+  printf '%s' "$raw" | sed -E "s/^.*\"${key}\"[[:space:]]*:[[:space:]]*\"//; s/\"$//"
+  echo
+}
+
+slugify() {
+  printf '%s' "$1" | tr ' ' '-' | sed -E 's/-+/-/g; s/^-//; s/-$//'
+}

package/hooks/scripts/keep-move.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+. "$SCRIPT_DIR/devlog-md.sh"
+. "$SCRIPT_DIR/json-field.sh"
+. "$SCRIPT_DIR/devlog-lock.sh"
+. "$SCRIPT_DIR/devlog-path.sh"
+
+FROM=""
+TO=""
+NAME=""
+DESC=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --from) FROM="${2:-}"; shift 2 ;;
+    --to) TO="${2:-}"; shift 2 ;;
+    --name) NAME="${2:-}"; shift 2 ;;
+    --desc) DESC="${2:-}"; shift 2 ;;
+    *) echo "未知參數：$1" >&2; exit 1 ;;
+  esac
+done
+DESC="$(printf '%s' "$DESC" | tr '\n' ' ')"
+case "$FROM:$TO" in *[!0-9:]*|:*) echo "範圍無效" >&2; exit 1 ;; esac
+[ "$FROM" -le "$TO" ] || { echo "範圍起點不可大於終點" >&2; exit 1; }
+
+case "$NAME" in devlog.md|*'/'*|*'\'*|*'..'*) echo "檔名無效" >&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" != "devlog.md" ] \
+  || { echo "檔名無效" >&2; exit 1; }
+[ "${#NAME}" -le 64 ] || { echo "檔名超過 64 字元" >&2; exit 1; }
+
+devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_lock_acquire
+trap 'devlog_lock_release' EXIT
+MAIN="$DEVLOG_FILE"
+TARGET="$DEVLOG_DIR/devlog.$NAME.md"
+[ -f "$MAIN" ] || { echo "devlog.md 不存在" >&2; exit 1; }
+[ ! -e "$TARGET" ] || { echo "目標檔案已存在：$TARGET" >&2; exit 1; }
+
+OPEN=""
+[ ! -f "$DEVLOG_DIR/.round-open" ] || OPEN="$(json_int_get "$DEVLOG_DIR/.round-open" round)"
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/devlog-keep.XXXXXX")" || exit 1
+trap 'rm -rf "$TMP"; devlog_lock_release' EXIT
+STARTS="$TMP/starts"
+MOVE_ROUNDS="$TMP/move-rounds"
+MOVE_BLOCKS="$TMP/move-blocks"
+H2="$TMP/h2"
+NEW_MAIN="$TMP/main"
+devlog_list_round_starts "$MAIN" > "$STARTS"
+: > "$MOVE_ROUNDS"
+: > "$MOVE_BLOCKS"
+
+HISTORICAL=0
+FIRST_ROUND=""
+LAST_MOVED_END=""
+while read -r start round; do
+  [ -n "${start:-}" ] || continue
+  [ -n "$FIRST_ROUND" ] || FIRST_ROUND="$start"
+  [ "$round" = "$OPEN" ] && continue
+  HISTORICAL=$((HISTORICAL + 1))
+  if [ "$round" -ge "$FROM" ] && [ "$round" -le "$TO" ]; then
+    printf '%s %s\n' "$start" "$round" >> "$MOVE_ROUNDS"
+    printf '%s\n' "$start" >> "$MOVE_BLOCKS"
+    LAST_MOVED_END="$(devlog_block_end "$MAIN" "$start")"
+  fi
+done < "$STARTS"
+
+EXPECTED=$((TO - FROM + 1))
+MOVED="$(wc -l < "$MOVE_ROUNDS" | tr -d ' ')"
+[ "$MOVED" -eq "$EXPECTED" ] || { echo "範圍內有不存在或非歷史的 Round" >&2; exit 1; }
+[ "$HISTORICAL" -gt 0 ] || { echo "目前沒有東西可 keep" >&2; exit 1; }
+FULL=0
+[ "$MOVED" -eq "$HISTORICAL" ] && FULL=1
+FIRST_MOVED="$(awk 'NR == 1 { print $1 }' "$MOVE_ROUNDS")"
+
+awk '
+  /^[ \t]*```/ { fence = !fence }
+  !fence && /^## / { print NR "\t" $0 }
+' "$MAIN" > "$H2"
+while IFS="$(printf '\t')" read -r start heading; do
+  case "$heading" in
+    "## Checkpoint"*)
+      span="$(printf '%s' "$heading" | sed -nE 's/.*Round ([0-9]+)-([0-9]+).*/\1 \2/p')"
+      if [ -n "$span" ]; then
+        x="${span%% *}"; y="${span##* }"
+        if [ "$x" -ge "$FROM" ] && [ "$y" -le "$TO" ]; then
+          printf '%s\n' "$start" >> "$MOVE_BLOCKS"
+        fi
+      elif [ "$start" -gt "$FIRST_MOVED" ] && [ "$start" -le "$LAST_MOVED_END" ]; then
+        printf '%s\n' "$start" >> "$MOVE_BLOCKS"
+      fi
+      ;;
+  esac
+done < "$H2"
+
+KEPT_AT="$(date -Iseconds 2>/dev/null || date '+%Y-%m-%dT%H:%M:%S%z')"
+{
+  printf '# Kept log\n\n- source: `.devlog/devlog.md`\n- rounds: %s-%s\n- kept_at: %s\n\n' \
+    "$FROM" "$TO" "$KEPT_AT"
+  awk -v selected="$MOVE_BLOCKS" -v full="$FULL" -v first_round="$FIRST_ROUND" '
+    BEGIN { while ((getline n < selected) > 0) move[n] = 1 }
+    /^[ \t]*```/ { fence = !fence }
+    !fence && /^## / { moving = (NR in move) }
+    full && NR < first_round { print; next }
+    moving { print }
+  ' "$MAIN"
+} > "$TARGET" || exit 1
+
+while read -r start round; do
+  heading="$(awk -v n="$start" 'NR == n { print; exit }' "$MAIN")"
+  grep -Fqx "$heading" "$TARGET" || { echo "具名檔驗證失敗" >&2; exit 1; }
+done < "$MOVE_ROUNDS"
+
+awk -v selected="$MOVE_BLOCKS" -v full="$FULL" -v first_round="$FIRST_ROUND" -v open="$OPEN" '
+  BEGIN { while ((getline n < selected) > 0) move[n] = 1 }
+  /^[ \t]*```/ { fence = !fence }
+  !fence && /^## / { moving = (NR in move) }
+  full && NR < first_round { next }
+  moving { next }
+  full && open != "" && $0 ~ ("^## Round " open "([^0-9]|$)") {
+    sub("^## Round " open, "## Round 1")
+  }
+  { print }
+' "$MAIN" > "$NEW_MAIN" || exit 1
+mv "$NEW_MAIN" "$MAIN" || exit 1
+
+KEPT_LINE="- \`devlog.${NAME}.md\`：Round ${FROM}-${TO}，kept_at ${KEPT_AT}"
+[ -z "$DESC" ] || KEPT_LINE="${KEPT_LINE}，${DESC}"
+KEPT_STRIPPED="$TMP/kept-stripped"
+devlog_strip_kept_index "$MAIN" "$KEPT_STRIPPED"
+EXISTING_KEPT_LINES="$(devlog_kept_index_lines "$MAIN")"
+{
+  cat "$KEPT_STRIPPED"
+  printf '\n## Kept 索引\n'
+  [ -n "$EXISTING_KEPT_LINES" ] && printf '%s\n' "$EXISTING_KEPT_LINES"
+  printf '%s\n' "$KEPT_LINE"
+} > "$KEPT_STRIPPED.new" && mv "$KEPT_STRIPPED.new" "$MAIN" || exit 1
+
+if [ "$FULL" -eq 1 ]; then
+  rm -f "$DEVLOG_DIR/.span-open"
+  [ ! -f "$DEVLOG_DIR/.round-open" ] || json_int_set "$DEVLOG_DIR/.round-open" round 1
+  [ ! -f "$DEVLOG_DIR/.checkpoint-state" ] || json_int_set "$DEVLOG_DIR/.checkpoint-state" rounds_since_checkpoint 0
+elif [ -f "$DEVLOG_DIR/.span-open" ]; then
+  SPAN_ROUND="$(json_int_get "$DEVLOG_DIR/.span-open" round)"
+  if [ -n "$SPAN_ROUND" ] && [ "$SPAN_ROUND" -ge "$FROM" ] && [ "$SPAN_ROUND" -le "$TO" ]; then
+    rm -f "$DEVLOG_DIR/.span-open"
+  fi
+fi
+
+REMAINING="$(devlog_list_round_starts "$MAIN" | wc -l | tr -d ' ')"
+printf 'KEPT=%s ROUNDS=%s-%s REMAINING=%s\n' "$TARGET" "$FROM" "$TO" "$REMAINING"

package/hooks/scripts/kept-list.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Filesystem side of /devlog-tracker:overview (docs/design/keep.md "Kept
+# index"). Plain read only -- parses the `## Kept 索引` block for the list
+# of devlog.<name>.md files kept so far, checking each against disk so a
+# manually-deleted file is reported as a ghost row instead of silently
+# dropped (same tolerance as the index itself).
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# 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:-.}"
+devlog_resolve_paths "$PROJECT_DIR"
+MAIN="$DEVLOG_FILE"
+
+if [ ! -f "$MAIN" ]; then
+  echo "NO_INDEX"
+  exit 0
+fi
+
+LINES="$(devlog_kept_index_lines "$MAIN")"
+if [ -z "$LINES" ]; then
+  echo "NO_INDEX"
+  exit 0
+fi
+
+printf '%s\n' "$LINES" | while IFS= read -r line; do
+  name="$(printf '%s' "$line" | sed -nE 's/.*`devlog\.([^`]+)\.md`.*/\1/p')"
+  [ -n "$name" ] || continue
+  file="$DEVLOG_DIR/devlog.$name.md"
+  if [ -f "$file" ]; then
+    printf 'FILE=%s EXISTS=1\n' "$file"
+  else
+    printf 'FILE=%s EXISTS=0\n' "$file"
+  fi
+done

package/hooks/scripts/lessons-append.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Claude-invoked only (docs/design/lessons-mode.md), never wired into
+# hooks/hooks.json — same posture as keep-move.sh. Appends one free-prose
+# entry to .devlog/devlog.lessons.<topic>.md (creating it if new), then
+# rebuilds the trailing "## Lessons 索引" block in devlog.md.
+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-lock.sh
+. "$SCRIPT_DIR/devlog-lock.sh"
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+
+TOPIC=""
+TEXT=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --topic) TOPIC="${2:-}"; shift 2 ;;
+    --text) TEXT="${2:-}"; shift 2 ;;
+    *) echo "未知參數：$1" >&2; exit 1 ;;
+  esac
+done
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "$PROJECT_DIR"
+MAIN="$DEVLOG_FILE"
+
+[ -f "$DEVLOG_DIR/.enabled" ] || { echo "NOT_ENABLED" >&2; exit 1; }
+[ -f "$DEVLOG_DIR/.lessons-enabled" ] || { echo "LESSONS_NOT_ENABLED" >&2; exit 1; }
+[ -n "$TEXT" ] || { echo "缺少 --text" >&2; exit 1; }
+[ -f "$MAIN" ] || { echo "devlog.md 不存在" >&2; exit 1; }
+
+# --- Normalize <topic>，跟 keep/resume 的 <name> 同一套規則
+# (docs/design/keep.md「Filenames」/ docs/design/lessons-mode.md「Storage」),
+# 外加保留 lessons 這個 infix 本身當名字。
+case "$TOPIC" in *'/'*|*'\'*|*'..'*) echo "TOPIC 無效" >&2; exit 1 ;; esac
+case "$TOPIC" in devlog.lessons.*) TOPIC="${TOPIC#devlog.lessons.}" ;; esac
+case "$TOPIC" in devlog.*) TOPIC="${TOPIC#devlog.}" ;; esac
+case "$TOPIC" in *.md) TOPIC="${TOPIC%.md}" ;; esac
+TOPIC="$(slugify "$TOPIC")"
+[ -n "$TOPIC" ] && [ "$TOPIC" != "archive" ] && [ "$TOPIC" != "lessons" ] && [ "${#TOPIC}" -le 64 ] \
+  || { echo "TOPIC 無效" >&2; exit 1; }
+
+devlog_lock_acquire
+trap 'devlog_lock_release' EXIT
+
+TARGET="$DEVLOG_DIR/devlog.lessons.$TOPIC.md"
+TS="$(date -Iseconds 2>/dev/null || date '+%Y-%m-%dT%H:%M:%S%z')"
+
+if [ ! -f "$TARGET" ]; then
+  printf '# Lessons: %s\n\n- source: `.devlog/devlog.md`\n' "$TOPIC" > "$TARGET" || exit 1
+fi
+{
+  printf '\n## %s\n' "$TS"
+  printf '%s\n' "$TEXT"
+} >> "$TARGET" || exit 1
+
+# --- Rebuild "## Lessons 索引" in devlog.md: one line per topic file,
+# re-derived from disk each call (docs/design/lessons-mode.md「## Lessons
+# 索引」). Title = first non-empty line after the LAST "## <timestamp>"
+# heading in that file, truncated at the first 。/. (whichever comes
+# first); no truncation if neither appears.
+INDEX_LINES=""
+shopt -s nullglob
+for f in "$DEVLOG_DIR"/devlog.lessons.*.md; do
+  [ -f "$f" ] || continue
+  leaf="${f##*/}"
+  n="$(grep -c '^## ' "$f" 2>/dev/null || echo 0)"
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  [ "$n" -gt 0 ] || continue
+  last_ln="$(grep -n '^## ' "$f" | tail -1 | cut -d: -f1)"
+  updated_at="$(sed -n "${last_ln}p" "$f" | sed -E 's/^## //')"
+  title="$(awk -v start="$last_ln" 'NR>start && $0 ~ /[^[:space:]]/ {print; exit}' "$f")"
+  title="$(printf '%s' "$title" | sed -E 's/([。.]).*$/\1/')"
+  LINE="- \`${leaf}\`：${n} 則，最新一則「${title}」（updated_at ${updated_at}）"
+  INDEX_LINES="${INDEX_LINES:+$INDEX_LINES$'\n'}$LINE"
+done
+
+STRIPPED="$(mktemp "${TMPDIR:-/tmp}/devlog-lessons.XXXXXX")" || exit 1
+trap 'rm -f "$STRIPPED"; devlog_lock_release' EXIT
+devlog_strip_lessons_index "$MAIN" "$STRIPPED"
+{
+  cat "$STRIPPED"
+  printf '\n## Lessons 索引\n'
+  [ -n "$INDEX_LINES" ] && printf '%s\n' "$INDEX_LINES"
+} > "$STRIPPED.new" && mv "$STRIPPED.new" "$MAIN" || exit 1
+
+printf 'PATH=.devlog/devlog.lessons.%s.md\n' "$TOPIC"

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# User-invoked: /devlog-tracker:lessons-drift filesystem side.
+# Sets the workspace-drift nudge's threshold (docs/design/lessons-mode.md
+# 「機制性訊號：工作區漂移重複發生」): how many cumulative 工作區-mismatch
+# occurrences (round-start.sh) before printing one advisory suggestion to
+# write a Lessons Mode entry. Nested under Lessons Mode, which is itself
+# nested under the main switch. $1 is required: a positive integer.
+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
+if [ ! -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+  echo "LESSONS_NOT_ENABLED"
+  exit 0
+fi
+
+COUNT_ARG="${1:-}"
+case "$COUNT_ARG" in
+  ''|*[!0-9]*|0)
+    echo "threshold must be a positive integer number of occurrences, got: $COUNT_ARG" >&2
+    exit 1
+    ;;
+esac
+
+if [ -f "$DEVLOG_DIR/.lessons-drift-state" ]; then
+  json_int_set "$DEVLOG_DIR/.lessons-drift-state" threshold "$COUNT_ARG"
+else
+  printf '%s\n' "{\"mismatch_count\": 0, \"threshold\": ${COUNT_ARG}}" \
+    > "$DEVLOG_DIR/.lessons-drift-state" || exit 1
+fi
+
+echo "LESSONS_DRIFT_THRESHOLD=$(json_int_get "$DEVLOG_DIR/.lessons-drift-state" threshold)"
+exit 0

package/hooks/scripts/lessons-off.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# User-invoked: /devlog-tracker:lessons-off filesystem side.
+# Removes .lessons-enabled only -- never touches devlog.lessons.*.md files
+# or the "## Lessons 索引" block (docs/design/lessons-mode.md), same
+# non-destructive posture as pause-devlog.sh toward devlog.md.
+set -uo pipefail
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DEVLOG_DIR="$PROJECT_DIR/.devlog"
+if [ ! -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+  echo "NOT_ENABLED"
+  exit 0
+fi
+rm -f "$DEVLOG_DIR/.lessons-enabled"
+echo "LESSONS_DISABLED"
+exit 0

package/hooks/scripts/lessons-on.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# User-invoked: /devlog-tracker:lessons-on filesystem side.
+# Nested under the main switch (docs/design/lessons-mode.md「Enable /
+# disable」): refuses if .enabled is absent, since there is no Round/Status
+# history to detect a BLOCKED->resolved transition against.
+set -uo pipefail
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DEVLOG_DIR="$PROJECT_DIR/.devlog"
+if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
+  echo "NOT_ENABLED"
+  exit 0
+fi
+if [ ! -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+  date -Iseconds > "$DEVLOG_DIR/.lessons-enabled" 2>/dev/null || echo enabled > "$DEVLOG_DIR/.lessons-enabled"
+fi
+if [ ! -f "$DEVLOG_DIR/.lessons-drift-state" ]; then
+  printf '%s\n' '{"mismatch_count": 0, "threshold": 3}' \
+    > "$DEVLOG_DIR/.lessons-drift-state" 2>/dev/null || true
+fi
+echo "LESSONS_ENABLED=$DEVLOG_DIR/.lessons-enabled"
+exit 0

package/hooks/scripts/lessons-read.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Filesystem side of /devlog-tracker:lessons [<topic>] (docs/design/
+# lessons-mode.md「Reading lessons on demand」). Plain read only -- no
+# workspace verification, no wait-for-confirmation flow (a lessons file is
+# reference material, not a paused work topic, unlike resume-devlog.sh).
+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:-.}"
+devlog_resolve_paths "$PROJECT_DIR"
+MAIN="$DEVLOG_FILE"
+
+TOPIC="${1:-}"
+
+if [ -z "$TOPIC" ]; then
+  if [ ! -f "$MAIN" ]; then
+    echo "NO_INDEX"
+    exit 0
+  fi
+  LINES="$(devlog_lessons_index_lines "$MAIN")"
+  if [ -z "$LINES" ]; then
+    echo "NO_INDEX"
+  else
+    printf '%s' "$LINES"
+  fi
+  exit 0
+fi
+
+case "$TOPIC" in *'/'*|*'\'*|*'..'*) echo "INVALID_TOPIC" >&2; exit 1 ;; esac
+case "$TOPIC" in devlog.lessons.*) TOPIC="${TOPIC#devlog.lessons.}" ;; esac
+case "$TOPIC" in devlog.*) TOPIC="${TOPIC#devlog.}" ;; esac
+case "$TOPIC" in *.md) TOPIC="${TOPIC%.md}" ;; esac
+TOPIC="$(slugify "$TOPIC")"
+[ -n "$TOPIC" ] && [ "${#TOPIC}" -le 64 ] || { echo "INVALID_TOPIC" >&2; exit 1; }
+
+FILE="$DEVLOG_DIR/devlog.lessons.$TOPIC.md"
+if [ ! -f "$FILE" ]; then
+  candidates=""
+  shopt -s nullglob
+  for path in "$DEVLOG_DIR"/devlog.lessons.*.md; do
+    leaf="${path##*/}"
+    candidate="${leaf#devlog.lessons.}"
+    candidate="${candidate%.md}"
+    [ -z "$candidates" ] || candidates="$candidates,"
+    candidates="$candidates$candidate"
+  done
+  echo "MISSING"
+  echo "CANDIDATES=$candidates"
+  exit 1
+fi
+printf 'PATH=.devlog/devlog.lessons.%s.md\n' "$TOPIC"
+cat "$FILE"

package/hooks/scripts/on-session-end.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# SessionEnd: stamp INTERRUPTED if a Round is still open.
+set -uo pipefail
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=json-field.sh
+. "$HOOKS_DIR/json-field.sh"
+INPUT="$(cat 2>/dev/null || true)"
+
+REASON="$(json_str_field "$INPUT" reason)"
+[ -n "$REASON" ] || REASON="other"
+
+bash "$HOOKS_DIR/close-open-round.sh" "SessionEnd:${REASON}" || true
+exit 0

package/hooks/scripts/on-stop-failure.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# StopFailure: stamp INTERRUPTED unless this is a usage-exhaustion error.
+set -uo pipefail
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=json-field.sh
+. "$HOOKS_DIR/json-field.sh"
+INPUT="$(cat 2>/dev/null || true)"
+
+ERROR="$(json_str_field "$INPUT" error)"
+
+case "$ERROR" in
+  rate_limit|billing_error|account_on_hold) exit 0 ;;
+  '') ERROR="unknown" ;;
+esac
+
+bash "$HOOKS_DIR/close-open-round.sh" "StopFailure:${ERROR}" || true
+exit 0

package/hooks/scripts/on-tool-failure.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# PostToolUseFailure: remember user Esc so Stop can stamp without blocking.
+set -uo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DEVLOG_DIR="$PROJECT_DIR/.devlog"
+ENABLED_FLAG="$DEVLOG_DIR/.enabled"
+[ -f "$ENABLED_FLAG" ] || exit 0
+
+INPUT="$(cat 2>/dev/null || true)"
+IS_INT="false"
+if command -v jq >/dev/null 2>&1; then
+  IS_INT="$(printf '%s' "$INPUT" | jq -r '.is_interrupt // false' 2>/dev/null || echo false)"
+else
+  case "$INPUT" in
+    *'"is_interrupt":true'*|*'"is_interrupt": true'*) IS_INT=true ;;
+    *) IS_INT=false ;;
+  esac
+fi
+
+if [ "$IS_INT" = "true" ]; then
+  mkdir -p "$DEVLOG_DIR" 2>/dev/null || true
+  : > "$DEVLOG_DIR/.interrupted" 2>/dev/null || true
+fi
+exit 0

package/hooks/scripts/pause-devlog.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -uo pipefail
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DEVLOG_DIR="$PROJECT_DIR/.devlog"
+if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
+  echo "NOT_ENABLED"
+  exit 0
+fi
+rm -f "$DEVLOG_DIR/.enabled" "$DEVLOG_DIR/.span-open" \
+  "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.interrupted" \
+  "$DEVLOG_DIR/.awaiting-reply"
+echo "PAUSED"
+exit 0