devlog-tracker 0.29.2 → 0.31.0

package/core/scripts/lessons-subagent-start.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# SubagentStart hook（Claude Code）：Lessons Mode 開著時，把「可以自己呼叫
+# lessons-append.sh」的說明注入 sub agent／Workflow agent 的 context
+# （docs/design/lessons-mode.md「sub agent／workflow 情境」）。
+# sub agent 的 Bash 裡沒有 CLAUDE_PROJECT_DIR，isolation: "worktree" 時 cwd
+# 還是 worktree（沒有 .devlog/），所以專案目錄跟腳本路徑都在這裡寫死成
+# 主專案的絕對路徑。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"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+[ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
+[ -f "$PROJECT_DIR/.devlog/.lessons-enabled" ] || exit 0
+PROJECT_DIR="$(cd "$PROJECT_DIR" 2>/dev/null && pwd)" || exit 0
+cat >/dev/null 2>&1 || true
+
+MSG="[devlog-tracker Lessons Mode] 這個專案開著 Lessons Mode：記錄開發**過程**踩過的坑（不是架構知識）。如果這次任務中你繞了一大圈才找到對的做法、先前的 fix／claim 被驗證推翻、或卡在某個值得後人避開的坑，可以直接記一筆（非強制，沒有就不用記）：
+
+DEVLOG_PROJECT_DIR='${PROJECT_DIR}' bash '${HOOKS_DIR}/lessons-append.sh' --topic '<kebab-case 主題，2–4 段>' --text '<一段自由散文：卡在哪、怎麼解開、下次怎麼避免>'
+
+路徑都是絕對路徑，在 worktree 裡也照原樣用，不要改成相對路徑。有記的話，在最終回報裡用一句話說明記了哪個主題；腳本回報 NEW_TOPIC 時可改用它列出的既有主題重跑。"
+
+printf '{"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"%s"}}\n' "$(json_escape "$MSG")"
+exit 0

package/core/scripts/pr-context.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Context for /devlog-tracker:pr (docs/design/read-side-and-promote.md A).
+# Plain read only: git is only queried, and gh is only asked `auth status`
+# and `pr view` -- creating/editing the PR is the command doc's job, after
+# the user confirms.
+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="$(cd "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}" 2>/dev/null && pwd)" || { echo "NOT_A_REPO"; exit 0; }
+git -C "$PROJECT_DIR" rev-parse --git-dir >/dev/null 2>&1 || { echo "NOT_A_REPO"; exit 0; }
+
+BRANCH="$(git -C "$PROJECT_DIR" symbolic-ref --quiet --short HEAD 2>/dev/null || echo '')"
+case "$BRANCH" in
+  '') echo "DETACHED_HEAD"; exit 0 ;;
+  [Mm][Aa][Ii][Nn]|[Mm][Aa][Ss][Tt][Ee][Rr]) echo "ON_DEFAULT_BRANCH"; exit 0 ;;
+esac
+
+BASE=""
+BASE_REF=""
+ORIGIN_HEAD="$(git -C "$PROJECT_DIR" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || echo '')"
+if [ -n "$ORIGIN_HEAD" ]; then
+  BASE="${ORIGIN_HEAD#origin/}"
+  BASE_REF="$ORIGIN_HEAD"
+else
+  for candidate in main master; do
+    if git -C "$PROJECT_DIR" rev-parse --verify --quiet "refs/heads/$candidate" >/dev/null; then
+      BASE="$candidate"
+      BASE_REF="$candidate"
+      break
+    fi
+  done
+fi
+
+echo "BRANCH=$BRANCH"
+[ -n "$BASE" ] || { echo "NO_BASE"; exit 0; }
+echo "BASE=$BASE"
+echo "BASE_REF=$BASE_REF"
+
+devlog_resolve_paths "$PROJECT_DIR"
+echo "DEVLOG_FILE=$DEVLOG_FILE"
+ROUNDS=""
+if [ -f "$DEVLOG_FILE" ]; then
+  ROUNDS="$(devlog_list_round_starts "$DEVLOG_FILE" | awk '{ printf "%s%s", (n++ ? " " : ""), $1 }')"
+fi
+if [ -n "$ROUNDS" ]; then echo "ROUNDS=$ROUNDS"; else echo "NO_BRANCH_DEVLOG"; fi
+
+COMMITS="$(git -C "$PROJECT_DIR" rev-list --count "$BASE_REF..HEAD" 2>/dev/null || echo 0)"
+echo "COMMITS=$COMMITS"
+
+GH=no
+PR=none
+if command -v gh >/dev/null 2>&1 && (cd "$PROJECT_DIR" && gh auth status >/dev/null 2>&1); then
+  GH=yes
+  n="$(cd "$PROJECT_DIR" && gh pr view --json number -q .number 2>/dev/null || echo '')"
+  case "$n" in ''|*[!0-9]*) ;; *) PR="$n" ;; esac
+fi
+echo "GH=$GH"
+echo "PR=$PR"

package/core/scripts/promote-sources.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Sources for /devlog-tracker:promote (docs/design/read-side-and-promote.md D):
+# kept files, lessons files, and Checkpoint headings in the current branch's
+# devlog. Plain read only. compact never moves Checkpoints, so the archive has
+# none to list.
+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="$(cd "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}" 2>/dev/null && pwd)" || { echo "NO_SOURCES"; exit 0; }
+devlog_resolve_paths "$PROJECT_DIR"
+MAIN="$DEVLOG_FILE"
+[ -f "$MAIN" ] || { echo "NO_SOURCES"; exit 0; }
+
+OUT=""
+add() { OUT="$OUT$1"$'\n'; }
+exists_flag() { if [ -f "$1" ]; then printf '1'; else printf '0'; fi; }
+
+while IFS= read -r name; do
+  [ -n "$name" ] || continue
+  f="$DEVLOG_DIR/devlog.$name.md"
+  add "FILE=$f KIND=kept EXISTS=$(exists_flag "$f")"
+done < <(devlog_kept_index_lines "$MAIN" | sed -nE 's/.*`devlog\.([^`]+)\.md`.*/\1/p')
+
+while IFS= read -r topic; do
+  [ -n "$topic" ] || continue
+  f="$DEVLOG_DIR/devlog.lessons.$topic.md"
+  add "FILE=$f KIND=lessons EXISTS=$(exists_flag "$f")"
+done < <(devlog_lessons_index_lines "$MAIN" | sed -nE 's/.*`devlog\.lessons\.([^`]+)\.md`.*/\1/p')
+
+while IFS= read -r ln; do
+  [ -n "$ln" ] && add "CHECKPOINT=$MAIN:$ln"
+done < <(awk '/^[ \t]*```/ { fence = !fence; next } !fence && /^## Checkpoint/ { print NR }' "$MAIN")
+
+if [ -z "$OUT" ]; then echo "NO_SOURCES"; else printf '%s' "$OUT"; fi

package/core/scripts/promote-target.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Picks the file /devlog-tracker:promote writes rules into
+# (docs/design/read-side-and-promote.md D). Plain read only.
+#   1. Codex-only project (no CLAUDE.md, Codex hooks or devlog skills present) -> AGENTS.md
+#   2. CLAUDE.md that is nothing but "@AGENTS.md"                              -> AGENTS.md
+#   3. otherwise                                                               -> CLAUDE.md
+set -uo pipefail
+
+PROJECT_DIR="$(cd "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}" 2>/dev/null && pwd)" || exit 1
+CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
+AGENTS_MD="$PROJECT_DIR/AGENTS.md"
+BEGIN_MARK='<!-- devlog-tracker:rules:begin -->'
+END_MARK='<!-- devlog-tracker:rules:end -->'
+
+HAS_CODEX=0
+[ -f "$PROJECT_DIR/.codex/hooks.json" ] && HAS_CODEX=1
+for d in "$PROJECT_DIR"/.agents/skills/devlog-*; do
+  [ -d "$d" ] && HAS_CODEX=1
+done
+
+TARGET="$CLAUDE_MD"
+if [ ! -f "$CLAUDE_MD" ] && [ "$HAS_CODEX" -eq 1 ]; then
+  TARGET="$AGENTS_MD"
+elif [ -f "$CLAUDE_MD" ] && [ "$(tr -d '[:space:]' < "$CLAUDE_MD")" = "@AGENTS.md" ]; then
+  TARGET="$AGENTS_MD"
+fi
+echo "TARGET=$TARGET"
+
+if [ -f "$TARGET" ] && grep -qxF "$BEGIN_MARK" "$TARGET"; then
+  n="$(awk -v b="$BEGIN_MARK" -v e="$END_MARK" '
+    $0 == b { g = 1; next }
+    $0 == e { g = 0 }
+    g && /^- / { c++ }
+    END { print c + 0 }
+  ' "$TARGET")"
+  echo "EXISTING=$n"
+fi

package/core/scripts/promote-write.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Writes rules chosen in /devlog-tracker:promote into the managed block
+# <!-- devlog-tracker:rules:begin/end --> of <target>
+# (docs/design/read-side-and-promote.md D). Append-only: never edits or
+# removes a rule already in the block, never touches anything outside it.
+# Exact-line duplicates (against the block, and within the input) are skipped.
+# Usage: promote-write.sh <target> <rules-file>
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+
+TARGET="${1:-}"
+RULES="${2:-}"
+if [ -z "$TARGET" ] || [ ! -f "$RULES" ]; then
+  echo "USAGE: promote-write.sh <target> <rules-file>" >&2
+  exit 2
+fi
+BEGIN_MARK='<!-- devlog-tracker:rules:begin -->'
+END_MARK='<!-- devlog-tracker:rules:end -->'
+
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+NEW="$(mktemp "${TMPDIR:-/tmp}/devlog-promote.XXXXXX")" || exit 1
+EXISTING="$(mktemp "${TMPDIR:-/tmp}/devlog-promote.XXXXXX")" || exit 1
+TO_ADD="$(mktemp "${TMPDIR:-/tmp}/devlog-promote.XXXXXX")" || exit 1
+trap 'rm -f "$NEW" "$EXISTING" "$TO_ADD" "$TARGET.tmp"; devlog_lock_release' EXIT
+[ -d "$DEVLOG_DIR" ] && devlog_lock_acquire
+
+# Normalise: trim, drop blank lines, ensure a "- " list prefix.
+awk '
+  { sub(/^[ \t]+/, ""); sub(/[ \t]+$/, "") }
+  $0 != "" { if ($0 !~ /^- /) $0 = "- " $0; print }
+' "$RULES" > "$NEW"
+
+if [ -f "$TARGET" ]; then
+  awk -v b="$BEGIN_MARK" -v e="$END_MARK" '$0 == b { g = 1; next } $0 == e { g = 0 } g' "$TARGET" > "$EXISTING"
+fi
+
+# FILENAME, not NR==FNR: an empty $EXISTING would make NR==FNR true for $NEW too.
+awk -v ex="$EXISTING" 'FILENAME == ex { seen[$0] = 1; next } !seen[$0]++' "$EXISTING" "$NEW" > "$TO_ADD"
+
+TOTAL="$(awk 'END { print NR }' "$NEW")"
+ADDED="$(awk 'END { print NR }' "$TO_ADD")"
+SKIPPED=$((TOTAL - ADDED))
+
+if [ "$ADDED" -gt 0 ]; then
+  if [ -f "$TARGET" ] && grep -qxF "$BEGIN_MARK" "$TARGET" && grep -qxF "$END_MARK" "$TARGET"; then
+    awk -v e="$END_MARK" -v add="$TO_ADD" '
+      $0 == e && !done { while ((getline l < add) > 0) print l; done = 1 }
+      { print }
+    ' "$TARGET" > "$TARGET.tmp" || exit 1
+  else
+    {
+      if [ -s "$TARGET" ]; then
+        cat "$TARGET"
+        [ -n "$(tail -c 1 "$TARGET")" ] && printf '\n'
+        printf '\n'
+      fi
+      printf '%s\n## devlog-tracker 沉澱的規範\n\n' "$BEGIN_MARK"
+      cat "$TO_ADD"
+      printf '%s\n' "$END_MARK"
+    } > "$TARGET.tmp" || exit 1
+  fi
+  # Write back in place (not mv): TARGET may be a symlink (e.g. CLAUDE.md ->
+  # AGENTS.md) or have a non-default mode; mv would replace it with a plain
+  # 644 file and break the link. $TARGET.tmp is fully built above already,
+  # so this is the only step that touches TARGET.
+  cat "$TARGET.tmp" > "$TARGET" || exit 1
+  rm -f "$TARGET.tmp"
+fi
+
+echo "ADDED=$ADDED SKIPPED_DUP=$SKIPPED TARGET=$TARGET"

package/core/scripts/report-devlog.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# Stats + structured Round data for /devlog-tracker:report, `npx devlog-tracker
+# report`, and timeline-devlog.sh (docs/design/read-side-and-promote.md B).
+# Plain read only: never edits a devlog file. devlog_resolve_paths may still
+# do its documented first-resolve rename, same as every other reader.
+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"
+
+JSON=0
+ROUNDS=0
+ALL=0
+WITH_INPUT=0
+for arg in "$@"; do
+  case "$arg" in
+    --json) JSON=1 ;;
+    --rounds) ROUNDS=1 ;;
+    --all-branches) ALL=1 ;;
+    --with-input) WITH_INPUT=1 ;;
+    *) echo "UNKNOWN_ARG=$arg" >&2; exit 2 ;;
+  esac
+done
+
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+if [ ! -d "$DEVLOG_DIR" ]; then
+  if [ "$JSON" -eq 1 ]; then echo '{"started":false}'; else echo "NOT_STARTED"; fi
+  exit 0
+fi
+
+# devlog.md -> main, devlog.archive.md -> archive, devlog.<x>.md -> <x>.
+branch_of_file() {
+  local leaf="${1##*/}"
+  case "$leaf" in
+    devlog.md) printf 'main' ;;
+    devlog.archive.md) printf 'archive' ;;
+    *) leaf="${leaf#devlog.}"; printf '%s' "${leaf%.md}" ;;
+  esac
+}
+
+# Archive first (oldest), then the branch file(s).
+FILES=()
+[ -f "$DEVLOG_DIR/devlog.archive.md" ] && FILES+=("$DEVLOG_DIR/devlog.archive.md")
+if [ "$ALL" -eq 1 ]; then
+  shopt -s nullglob
+  KEPT_NAMES=" "
+  for f in "$DEVLOG_DIR"/devlog*.md; do
+    while IFS= read -r name; do
+      [ -n "$name" ] && KEPT_NAMES="$KEPT_NAMES$name "
+    done < <(devlog_kept_index_lines "$f" | sed -nE 's/.*`devlog\.([^`]+)\.md`.*/\1/p')
+  done
+  for f in "$DEVLOG_DIR"/devlog*.md; do
+    case "${f##*/}" in devlog.archive.md|devlog.lessons.*.md) continue ;; esac
+    case "$KEPT_NAMES" in *" $(branch_of_file "$f") "*) continue ;; esac
+    FILES+=("$f")
+  done
+  shopt -u nullglob
+else
+  [ -f "$DEVLOG_FILE" ] && FILES+=("$DEVLOG_FILE")
+fi
+
+SCAN="$(mktemp "${TMPDIR:-/tmp}/devlog-report.XXXXXX")" || exit 1
+trap 'rm -f "$SCAN"' EXIT
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  awk -v branch="$(branch_of_file "$f")" -v label="${f##*/}" -v with_input="$WITH_INPUT" \
+    -f "$SCRIPT_DIR/report-scan.awk" "$f" >> "$SCAN"
+done
+
+count_status() { awk -F'\t' -v s="$1" '$1 == "R" && $2 == s { c++ } END { print c + 0 }' "$SCAN"; }
+BRANCH="$(branch_of_file "$DEVLOG_FILE")"
+ROUNDS_TOTAL="$(awk -F'\t' '$1 == "R" { c++ } END { print c + 0 }' "$SCAN")"
+ROUNDS_ARCHIVE="$(awk -F'\t' '$1 == "R" && $4 == "archive" { c++ } END { print c + 0 }' "$SCAN")"
+ROUNDS_MAIN=$((ROUNDS_TOTAL - ROUNDS_ARCHIVE))
+STATUS_DONE="$(count_status DONE)"
+STATUS_IN_PROGRESS="$(count_status IN_PROGRESS)"
+STATUS_BLOCKED="$(count_status BLOCKED)"
+STATUS_INTERRUPTED="$(count_status INTERRUPTED)"
+BLOCKED_RATIO=0
+[ "$ROUNDS_TOTAL" -gt 0 ] && BLOCKED_RATIO=$((STATUS_BLOCKED * 100 / ROUNDS_TOTAL))
+CHECKPOINTS="$(awk -F'\t' '$1 == "C" { c++ } END { print c + 0 }' "$SCAN")"
+KEPT_TOPICS=0
+if [ -f "$DEVLOG_FILE" ]; then
+  KEPT_TOPICS="$(devlog_kept_index_lines "$DEVLOG_FILE" | grep -c '^- `devlog\.' || true)"
+fi
+LESSONS_TOPICS=0
+for f in "$DEVLOG_DIR"/devlog.lessons.*.md; do
+  [ -f "$f" ] && LESSONS_TOPICS=$((LESSONS_TOPICS + 1))
+done
+ADVISORY=""
+if [ -f "$DEVLOG_DIR/.lessons-advisory-state" ]; then
+  a_count="$(json_int_get "$DEVLOG_DIR/.lessons-advisory-state" count)"
+  a_max="$(json_int_get "$DEVLOG_DIR/.lessons-advisory-state" threshold)"
+  ADVISORY="${a_count:-0}/${a_max:-3}"
+fi
+FIRST_ROUND_AT="$(awk -F'\t' '$1 == "R" && $3 != "" { print $3 }' "$SCAN" | sort | head -1)"
+LAST_ROUND_AT="$(awk -F'\t' '$1 == "R" && $3 != "" { print $3 }' "$SCAN" | sort | tail -1)"
+[ -n "$FIRST_ROUND_AT" ] || FIRST_ROUND_AT=none
+[ -n "$LAST_ROUND_AT" ] || LAST_ROUND_AT=none
+
+if [ "$JSON" -eq 0 ]; then
+  printf 'BRANCH=%s\n' "$BRANCH"
+  printf 'ROUNDS_TOTAL=%s\nROUNDS_MAIN=%s\nROUNDS_ARCHIVE=%s\n' "$ROUNDS_TOTAL" "$ROUNDS_MAIN" "$ROUNDS_ARCHIVE"
+  printf 'STATUS_DONE=%s\nSTATUS_IN_PROGRESS=%s\nSTATUS_BLOCKED=%s\nSTATUS_INTERRUPTED=%s\n' \
+    "$STATUS_DONE" "$STATUS_IN_PROGRESS" "$STATUS_BLOCKED" "$STATUS_INTERRUPTED"
+  printf 'BLOCKED_RATIO=%s\nCHECKPOINTS=%s\nKEPT_TOPICS=%s\nLESSONS_TOPICS=%s\n' \
+    "$BLOCKED_RATIO" "$CHECKPOINTS" "$KEPT_TOPICS" "$LESSONS_TOPICS"
+  [ -n "$ADVISORY" ] && printf 'LESSONS_ADVISORY=%s\n' "$ADVISORY"
+  printf 'FIRST_ROUND_AT=%s\nLAST_ROUND_AT=%s\n' "$FIRST_ROUND_AT" "$LAST_ROUND_AT"
+  exit 0
+fi
+
+jstr() {
+  if [ -z "$1" ] || [ "$1" = none ]; then printf 'null'
+  else printf '"%s"' "$(json_escape "$1")"; fi
+}
+{
+  printf '{"started":true,"branch":"%s"' "$(json_escape "$BRANCH")"
+  printf ',"rounds_total":%s,"rounds_main":%s,"rounds_archive":%s' "$ROUNDS_TOTAL" "$ROUNDS_MAIN" "$ROUNDS_ARCHIVE"
+  printf ',"status_done":%s,"status_in_progress":%s,"status_blocked":%s,"status_interrupted":%s' \
+    "$STATUS_DONE" "$STATUS_IN_PROGRESS" "$STATUS_BLOCKED" "$STATUS_INTERRUPTED"
+  printf ',"blocked_ratio":%s,"checkpoints":%s,"kept_topics":%s,"lessons_topics":%s' \
+    "$BLOCKED_RATIO" "$CHECKPOINTS" "$KEPT_TOPICS" "$LESSONS_TOPICS"
+  printf ',"lessons_advisory":%s,"first_round_at":%s,"last_round_at":%s' \
+    "$(jstr "$ADVISORY")" "$(jstr "$FIRST_ROUND_AT")" "$(jstr "$LAST_ROUND_AT")"
+  if [ "$ROUNDS" -eq 1 ]; then
+    printf ',"rounds":['
+    awk -F'\t' '$1 == "R" { printf "%s%s", (n++ ? "," : ""), $5 }' "$SCAN"
+    printf '],"checkpoint_blocks":['
+    awk -F'\t' '$1 == "C" { printf "%s%s", (n++ ? "," : ""), $3 }' "$SCAN"
+    printf ']'
+  fi
+  printf '}\n'
+}
+exit 0

package/core/scripts/report-scan.awk

@@ -0,0 +1,74 @@
+# One pass over one devlog file for report-devlog.sh
+# (docs/design/read-side-and-promote.md B). POSIX awk only (mawk / BSD awk).
+# Vars: branch, label (file leaf name), with_input (0|1).
+# Emits one line per block:
+#   R<TAB>status<TAB>at<TAB>branch<TAB>round-json
+#   C<TAB>branch<TAB>checkpoint-json
+# Headings inside ``` fences are content, not structure (same rule as
+# devlog-md.sh).
+BEGIN {
+  # Build the 0x01-0x1F control bytes once; \t \r \n get their short escapes
+  # below, the rest (e.g. pasted ANSI \033) fall back to \u00XX.
+  for (ci = 1; ci <= 31; ci++) { cchar[ci] = sprintf("%c", ci); cesc[ci] = sprintf("\\u%04x", ci) }
+}
+function esc(s,    ci) {
+  gsub(/\\/, "\\\\", s); gsub(/"/, "\\\"", s)
+  gsub(/\t/, "\\t", s); gsub(/\r/, "\\r", s); gsub(/\n/, "\\n", s)
+  for (ci = 1; ci <= 31; ci++) if (index(s, cchar[ci]) > 0) gsub(cchar[ci], cesc[ci], s)
+  return s
+}
+function trim_nl(s) { sub(/^\n+/, "", s); sub(/\n+$/, "", s); return s }
+function flush_section() {
+  if (sec == "") return
+  if (sec == "segment") segs[nseg++] = trim_nl(buf)
+  else part[sec] = trim_nl(buf)
+  sec = ""; buf = ""
+}
+function flush_block(   i, st, js) {
+  flush_section()
+  if (kind == "round") {
+    st = part["status"]; sub(/\n.*/, "", st); gsub(/[ \t`*]/, "", st)
+    if (st !~ /^(DONE|IN_PROGRESS|BLOCKED|INTERRUPTED)$/) st = ""
+    js = "{\"branch\":\"" esc(branch) "\",\"file\":\"" esc(label) "\",\"line\":" rline ",\"n\":" rn
+    js = js ",\"at\":\"" esc(at) "\",\"status\":\"" st "\""
+    js = js ",\"summary\":\"" esc(part["summary"]) "\",\"reply\":\"" esc(part["reply"]) "\""
+    js = js ",\"handoff\":\"" esc(part["handoff"]) "\",\"segments\":["
+    for (i = 0; i < nseg; i++) js = js (i ? "," : "") "\"" esc(segs[i]) "\""
+    js = js "]"
+    if (with_input) js = js ",\"input\":\"" esc(part["input"]) "\""
+    js = js "}"
+    printf "R\t%s\t%s\t%s\t%s\n", st, at, branch, js
+  } else if (kind == "checkpoint") {
+    printf "C\t%s\t{\"branch\":\"%s\",\"file\":\"%s\",\"line\":%d,\"heading\":\"%s\",\"body\":\"%s\"}\n", \
+      branch, esc(branch), esc(label), cline, esc(cheading), esc(trim_nl(buf_cp))
+  }
+  kind = ""; split("", part); split("", segs); nseg = 0; buf_cp = ""
+}
+/^[ \t]*```/ { fence = !fence }
+!fence && /^## / {
+  flush_block()
+  if ($0 ~ /^## Round [0-9]+/) {
+    kind = "round"; rline = NR
+    rn = $0; sub(/^## Round /, "", rn); sub(/[^0-9].*$/, "", rn)
+    at = ""
+    if (index($0, "— ")) at = substr($0, index($0, "— ") + length("— "))
+  } else if ($0 ~ /^## Checkpoint/) {
+    kind = "checkpoint"; cline = NR; cheading = substr($0, 4)
+  }
+  next
+}
+kind == "checkpoint" { buf_cp = buf_cp $0 "\n"; next }
+kind == "round" && !fence && /^### / {
+  flush_section()
+  h = substr($0, 5)
+  if (h ~ /^User Input[ \t]*$/) sec = "input"
+  else if (h ~ /^Summary[ \t]*$/) sec = "summary"
+  else if (h ~ /^Reply[ \t]*$/) sec = "reply"
+  else if (h ~ /^Handoff[ \t]*$/) sec = "handoff"
+  else if (h ~ /^Status[ \t]*$/) sec = "status"
+  else if (h ~ /^段落 /) { sec = "segment"; buf = h "\n"; next }
+  else sec = "other"
+  next
+}
+kind == "round" && sec != "" { buf = buf $0 "\n" }
+END { flush_block() }

package/core/scripts/round-start.sh

@@ -95,7 +95,7 @@ case "$PROMPT" in
     ;;
 esac
 case "$CMD_NAME" in
-  devlog-tracker:checkpoint|devlog-tracker:clean|devlog-tracker:compact|devlog-tracker:keep|devlog-tracker:lessons|devlog-tracker:lessons-drift|devlog-tracker:lessons-off|devlog-tracker:lessons-on|devlog-tracker:overview|devlog-tracker:pause|devlog-tracker:search|devlog-tracker:segment-watch|devlog-tracker:span|devlog-tracker:start|devlog-tracker:status)
+  devlog-tracker:checkpoint|devlog-tracker:clean|devlog-tracker:compact|devlog-tracker:keep|devlog-tracker:lessons|devlog-tracker:lessons-drift|devlog-tracker:lessons-off|devlog-tracker:lessons-on|devlog-tracker:overview|devlog-tracker:pause|devlog-tracker:report|devlog-tracker:search|devlog-tracker:segment-watch|devlog-tracker:span|devlog-tracker:start|devlog-tracker:status|devlog-tracker:timeline)
     exit 0
     ;;
 esac
@@ -123,6 +123,20 @@ if [ "$TASK_NOTIF" -eq 1 ]; then
   else
     PROMPT="$NOTIF_SUMMARY"
   fi
+
+  # Lessons Mode：背景 sub agent／Workflow 完成時機械提示主 session 檢查
+  # sub agent 訊號（docs/design/lessons-mode.md「sub agent／workflow 情境」）；
+  # failed／killed 另外算進共用計數器。span 開著也照印——長任務正是會派
+  # 背景 agent 的場景。
+  if [ -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+    printf '\n[Lessons Mode 提示] 背景任務完成（status=%s）。讀完回報後檢查：verify 推翻先前的 fix／claim、sub agent 自陳繞路、多個 agent 卡在類似問題、成果被打回票——有的話可考慮用 lessons-append.sh 記一筆（sub agent 若已自己記過就不用重複），非強制。\n' "${NOTIF_STATUS:-unknown}"
+    case "$NOTIF_STATUS" in
+      failed|killed)
+        lessons_advisory_migrate "$DEVLOG_DIR"
+        lessons_advisory_bump "$ADVISORY_FILE"
+        ;;
+    esac
+  fi
 fi
 
 if [ "$SPAN_SKIP" -eq 1 ]; then

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

@@ -70,5 +70,10 @@ 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 ')"
 
+assert_eq "json_escape quotes and backslash" 'a \"q\" \\ b' "$(json_escape 'a "q" \ b')"
+assert_eq "json_escape tab" 'x\ty' "$(json_escape "$(printf 'x\ty')")"
+assert_eq "json_escape newline" 'l1\nl2' "$(json_escape "$(printf 'l1\nl2')")"
+assert_eq "json_escape CJK passthrough" '中文' "$(json_escape '中文')"
+
 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-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