devlog-tracker 0.30.0 → 0.31.1

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

package/core/scripts/tests/test-close-open-round.sh

@@ -316,6 +316,60 @@ fi
 rm -rf "$REC_DIR"
 export CLAUDE_PROJECT_DIR="$TMP_ROOT"
 
+# --- L1: run as a child of the lock holder (round-start.sh's dangling heal)
+#         -> no wait on the parent's lock, still stamps, and its EXIT-trap
+#         release leaves the parent's lock in place ----------------------
+# shellcheck source=../devlog-lock.sh
+. "$SCRIPT_DIR/devlog-lock.sh"
+write_skeleton
+devlog_lock_acquire
+START="$(date +%s)"
+bash "$SCRIPT_DIR/close-open-round.sh" "dangling:next_prompt"
+ELAPSED=$(( $(date +%s) - START ))
+if [ "$ELAPSED" -le 1 ]; then
+  echo "PASS: child of lock holder doesn't wait (${ELAPSED}s)"
+else
+  echo "FAIL: child of lock holder waited ${ELAPSED}s"
+  FAIL=1
+fi
+assert_contains "child of lock holder still stamps" $'### Status\nINTERRUPTED' "$(cat "$DEVLOG_DIR/devlog.md")"
+if [ -d "$DEVLOG_DIR/.lock" ] && [ "$(cat "$DEVLOG_DIR/.lock/pid" 2>/dev/null)" = "$$" ]; then
+  echo "PASS: child's exit leaves the holder's lock"
+else
+  echo "FAIL: holder's lock removed by child"
+  FAIL=1
+fi
+devlog_lock_release
+assert_file_absent "holder release removes lock" "$DEVLOG_DIR/.lock/pid"
+
+# --- L2: lock held by an unrelated live process (no inherited owner) ->
+#         still waits out the contention timeout, stamps fail-open, and
+#         leaves the foreign lock alone --------------------------------------
+write_skeleton
+sleep 5 &
+LIVE_PID=$!
+mkdir "$DEVLOG_DIR/.lock"
+echo "$LIVE_PID" > "$DEVLOG_DIR/.lock/pid"
+START="$(date +%s)"
+bash "$SCRIPT_DIR/close-open-round.sh" "dangling:next_prompt"
+ELAPSED=$(( $(date +%s) - START ))
+if [ "$ELAPSED" -ge 2 ]; then
+  echo "PASS: unrelated holder still contends (${ELAPSED}s)"
+else
+  echo "FAIL: unrelated holder skipped contention (${ELAPSED}s)"
+  FAIL=1
+fi
+assert_contains "contended run still stamps (fail-open)" $'### Status\nINTERRUPTED' "$(cat "$DEVLOG_DIR/devlog.md")"
+if [ "$(cat "$DEVLOG_DIR/.lock/pid" 2>/dev/null)" = "$LIVE_PID" ]; then
+  echo "PASS: foreign lock left in place"
+else
+  echo "FAIL: foreign lock touched"
+  FAIL=1
+fi
+kill "$LIVE_PID" 2>/dev/null || true
+wait "$LIVE_PID" 2>/dev/null || true
+rm -rf "$DEVLOG_DIR/.lock"
+
 if [ "$FAIL" -eq 0 ]; then
   echo "All checks passed."
   exit 0

package/core/scripts/tests/test-devlog-lock.sh

@@ -72,5 +72,49 @@ kill "$LIVE_PID" 2>/dev/null || true
 wait "$LIVE_PID" 2>/dev/null || true
 rm -rf "$DEVLOG_DIR/.lock"
 
+# Re-entry from a child process: a script run by the lock holder (e.g.
+# round-start.sh -> close-open-round.sh) sees the lock as already its own —
+# returns at once, and its release leaves the parent's lock in place.
+devlog_lock_acquire
+START="$(date +%s)"
+CHILD="$(bash -c '. "$1"; DEVLOG_DIR="$2"; devlog_lock_acquire; echo "held=${LOCK_HELD:-0} by=${LOCK_CONTENDED_BY:-}"; devlog_lock_release' _ "$SCRIPT_DIR/devlog-lock.sh" "$DEVLOG_DIR")"
+ELAPSED=$(( $(date +%s) - START ))
+[ "$ELAPSED" -le 1 ] && [ "$CHILD" = "held=0 by=" ] \
+  && echo "PASS: child of holder re-enters without waiting" \
+  || { echo "FAIL: child re-entry elapsed=$ELAPSED child='$CHILD'"; FAIL=1; }
+[ -d "$DEVLOG_DIR/.lock" ] && [ "$(cat "$DEVLOG_DIR/.lock/pid")" = "$$" ] \
+  && echo "PASS: child release leaves parent's lock" \
+  || { echo "FAIL: parent's lock gone after child release"; FAIL=1; }
+# Grandchild (holder -> script -> script) inherits the owner too.
+START="$(date +%s)"
+GRAND="$(bash -c 'bash -c ". \"\$1\"; DEVLOG_DIR=\"\$2\"; devlog_lock_acquire; echo held=\${LOCK_HELD:-0}; devlog_lock_release" _ "$1" "$2"' _ "$SCRIPT_DIR/devlog-lock.sh" "$DEVLOG_DIR")"
+ELAPSED=$(( $(date +%s) - START ))
+[ "$GRAND" = "held=0" ] && [ "$ELAPSED" -le 1 ] && [ -d "$DEVLOG_DIR/.lock" ] \
+  && echo "PASS: grandchild of holder re-enters" || { echo "FAIL: grandchild got '$GRAND' elapsed=$ELAPSED"; FAIL=1; }
+devlog_lock_release
+[ -z "${DEVLOG_LOCK_OWNER:-}" ] && [ ! -d "$DEVLOG_DIR/.lock" ] \
+  && echo "PASS: release clears owner" || { echo "FAIL: owner=${DEVLOG_LOCK_OWNER:-} survives release"; FAIL=1; }
+
+# After the holder releases, a child it spawns later no longer carries the
+# owner, so it would contend on a lock someone else took meanwhile.
+OUT="$(bash -c 'echo "owner=${DEVLOG_LOCK_OWNER:-}"')"
+[ "$OUT" = "owner=" ] && echo "PASS: owner not exported after release" \
+  || { echo "FAIL: child still sees $OUT"; FAIL=1; }
+
+# A process that did not inherit the owner (another hook launched by the
+# agent while the lock is held) still waits out the timeout.
+sleep 5 &
+LIVE_PID=$!
+mkdir "$DEVLOG_DIR/.lock"
+echo "$LIVE_PID" > "$DEVLOG_DIR/.lock/pid"
+START="$(date +%s)"
+OUT="$(DEVLOG_LOCK_OWNER=12345 bash -c '. "$1"; DEVLOG_DIR="$2"; devlog_lock_acquire; echo "${LOCK_HELD:-0}"' _ "$SCRIPT_DIR/devlog-lock.sh" "$DEVLOG_DIR")"
+ELAPSED=$(( $(date +%s) - START ))
+[ "$OUT" = "0" ] && [ "$ELAPSED" -ge 2 ] \
+  && echo "PASS: unrelated owner still contends" || { echo "FAIL: unrelated owner out=$OUT elapsed=$ELAPSED"; FAIL=1; }
+kill "$LIVE_PID" 2>/dev/null || true
+wait "$LIVE_PID" 2>/dev/null || true
+rm -rf "$DEVLOG_DIR/.lock"
+
 if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
 else echo "Some checks FAILED."; exit 1; fi

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