devlog-tracker 0.30.0 → 0.31.0

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-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-pr-context.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Self-check for pr-context.sh (docs/design/read-side-and-promote.md A).
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+FAIL=0
+assert_line() {
+  local desc="$1" expected="$2" out="$3"
+  if printf '%s\n' "$out" | grep -qxF "$expected"; then echo "PASS: $desc"
+  else echo "FAIL: $desc (missing [$expected] in: $out)"; FAIL=1; fi
+}
+assert_eq() {
+  local desc="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "PASS: $desc"
+  else echo "FAIL: $desc (expected [$expected] got [$actual])"; FAIL=1; fi
+}
+
+# gh stubs: one that is not logged in, one that is and has PR #42.
+GH_OFF="$TMP_ROOT/gh-off"; GH_ON="$TMP_ROOT/gh-on"
+mkdir -p "$GH_OFF" "$GH_ON"
+printf '#!/usr/bin/env bash\nexit 1\n' > "$GH_OFF/gh"
+cat > "$GH_ON/gh" <<'EOF'
+#!/usr/bin/env bash
+case "$1 $2" in
+  "auth status") exit 0 ;;
+  "pr view") echo 42 ;;
+  *) echo "unexpected gh call: $*" >&2; exit 9 ;;
+esac
+EOF
+chmod +x "$GH_OFF/gh" "$GH_ON/gh"
+ctx() { PATH="$1:$PATH" CLAUDE_PROJECT_DIR="$2" bash "$SCRIPT_DIR/pr-context.sh"; }
+
+# --- Not a git repo -------------------------------------------------------------
+PLAIN="$TMP_ROOT/plain"; mkdir -p "$PLAIN"
+assert_eq "not a repo" "NOT_A_REPO" "$(ctx "$GH_OFF" "$PLAIN")"
+
+# --- Repo fixture ------------------------------------------------------------------
+REPO="$TMP_ROOT/repo"; mkdir -p "$REPO"
+gitc() { git -C "$REPO" -c user.email=t@example.com -c user.name=t -c commit.gpgsign=false "$@"; }
+gitc init -q -b main
+echo a > "$REPO/a.txt"; gitc add a.txt; gitc commit -qm init
+
+assert_eq "on main" "ON_DEFAULT_BRANCH" "$(ctx "$GH_OFF" "$REPO")"
+gitc checkout -q -b MASTER
+assert_eq "on MASTER (case-insensitive)" "ON_DEFAULT_BRANCH" "$(ctx "$GH_OFF" "$REPO")"
+gitc checkout -q main
+gitc checkout -q --detach
+assert_eq "detached" "DETACHED_HEAD" "$(ctx "$GH_OFF" "$REPO")"
+gitc checkout -q main
+
+# --- Feature branch, no devlog, gh logged out --------------------------------------
+gitc checkout -q -b feat/x
+echo b > "$REPO/b.txt"; gitc add b.txt; gitc commit -qm "feat: b"
+OUT="$(ctx "$GH_OFF" "$REPO")"
+assert_line "branch" "BRANCH=feat/x" "$OUT"
+assert_line "base from local main" "BASE=main" "$OUT"
+assert_line "base ref" "BASE_REF=main" "$OUT"
+assert_line "devlog file is branch-scoped + absolute" "DEVLOG_FILE=$(cd "$REPO" && pwd)/.devlog/devlog.feat-x.md" "$OUT"
+assert_line "no branch devlog" "NO_BRANCH_DEVLOG" "$OUT"
+assert_line "commit count" "COMMITS=1" "$OUT"
+assert_line "gh logged out" "GH=no" "$OUT"
+assert_line "no pr" "PR=none" "$OUT"
+
+# --- Branch devlog with rounds + gh logged in -------------------------------------
+mkdir -p "$REPO/.devlog"
+cat > "$REPO/.devlog/devlog.feat-x.md" <<'EOF'
+## Round 1 — 2026-09-01T10:00:00+0800
+
+### Summary
+one
+
+### Status
+DONE
+
+## Round 2 — 2026-09-02T10:00:00+0800
+
+### Summary
+two
+
+### Status
+DONE
+EOF
+OUT="$(ctx "$GH_ON" "$REPO")"
+assert_line "round start lines" "ROUNDS=1 9" "$OUT"
+assert_line "gh logged in" "GH=yes" "$OUT"
+assert_line "existing pr number" "PR=42" "$OUT"
+
+# --- origin/HEAD wins over local main ---------------------------------------------
+gitc update-ref refs/remotes/origin/main main
+gitc symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
+OUT="$(ctx "$GH_OFF" "$REPO")"
+assert_line "base from origin/HEAD" "BASE=main" "$OUT"
+assert_line "base ref is remote" "BASE_REF=origin/main" "$OUT"
+
+# --- No main/master and no origin/HEAD -> NO_BASE ------------------------------
+REPO2="$TMP_ROOT/repo2"; mkdir -p "$REPO2"
+git -C "$REPO2" -c user.email=t@example.com -c user.name=t init -q -b trunk
+echo a > "$REPO2/a.txt"; git -C "$REPO2" add a.txt
+git -C "$REPO2" -c user.email=t@example.com -c user.name=t -c commit.gpgsign=false commit -qm init
+git -C "$REPO2" checkout -q -b dev
+OUT="$(ctx "$GH_OFF" "$REPO2")"
+assert_line "no base: branch still printed" "BRANCH=dev" "$OUT"
+assert_line "no base" "NO_BASE" "$OUT"
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/core/scripts/tests/test-promote.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Self-check for promote-{sources,target,write}.sh
+# (docs/design/read-side-and-promote.md D).
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+FAIL=0
+assert_line() {
+  local desc="$1" expected="$2" out="$3"
+  if printf '%s\n' "$out" | grep -qxF "$expected"; then echo "PASS: $desc"
+  else echo "FAIL: $desc (missing [$expected] in: $out)"; FAIL=1; fi
+}
+assert_eq() {
+  local desc="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "PASS: $desc"
+  else echo "FAIL: $desc (expected [$expected] got [$actual])"; FAIL=1; fi
+}
+new_project() { local d; d="$(mktemp -d "$TMP_ROOT/p.XXXXXX")"; (cd "$d" && pwd); }
+
+# === promote-sources.sh =========================================================
+P="$(new_project)"
+assert_eq "sources: no devlog -> NO_SOURCES" "NO_SOURCES" "$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-sources.sh")"
+
+mkdir -p "$P/.devlog"
+cat > "$P/.devlog/devlog.md" <<'EOF'
+## Round 1 — 2026-09-01T10:00:00+0800
+
+### Summary
+x
+
+### Status
+DONE
+EOF
+assert_eq "sources: devlog without index/checkpoint -> NO_SOURCES" "NO_SOURCES" "$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-sources.sh")"
+
+cat >> "$P/.devlog/devlog.md" <<'EOF'
+
+```
+## Checkpoint fake inside fence
+```
+
+## Checkpoint（Round 1-1）
+### 決策
+- always run shellcheck
+
+## Kept 索引
+- `devlog.topic-a.md`：Round 1-1，kept_at 2026-09-05T00:00:00+0800，topic a
+- `devlog.ghost.md`：Round 2-2，kept_at 2026-09-05T00:00:00+0800，gone
+
+## Lessons 索引
+- `devlog.lessons.lock-files.md`：1 則，最新一則「x。」（updated_at 2026-09-01T00:00:00+0800）
+EOF
+printf 'kept\n' > "$P/.devlog/devlog.topic-a.md"
+printf '# Lessons: lock-files\n' > "$P/.devlog/devlog.lessons.lock-files.md"
+OUT="$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-sources.sh")"
+assert_line "sources: kept file exists" "FILE=$P/.devlog/devlog.topic-a.md KIND=kept EXISTS=1" "$OUT"
+assert_line "sources: kept ghost row" "FILE=$P/.devlog/devlog.ghost.md KIND=kept EXISTS=0" "$OUT"
+assert_line "sources: lessons file" "FILE=$P/.devlog/devlog.lessons.lock-files.md KIND=lessons EXISTS=1" "$OUT"
+CP_LINE="$(grep -n '^## Checkpoint（Round 1-1）' "$P/.devlog/devlog.md" | cut -d: -f1)"
+assert_line "sources: real checkpoint line" "CHECKPOINT=$P/.devlog/devlog.md:$CP_LINE" "$OUT"
+assert_eq "sources: fenced checkpoint ignored" "1" "$(printf '%s\n' "$OUT" | grep -c '^CHECKPOINT=')"
+
+# === promote-target.sh ==========================================================
+P="$(new_project)"
+assert_eq "target: empty project -> CLAUDE.md" "TARGET=$P/CLAUDE.md" "$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-target.sh")"
+
+printf '@AGENTS.md\n\n' > "$P/CLAUDE.md"
+assert_eq "target: CLAUDE.md only imports AGENTS.md -> AGENTS.md" "TARGET=$P/AGENTS.md" "$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-target.sh")"
+
+printf '# Rules\n\n@AGENTS.md\n' > "$P/CLAUDE.md"
+assert_eq "target: CLAUDE.md with own content -> CLAUDE.md" "TARGET=$P/CLAUDE.md" "$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-target.sh")"
+
+P="$(new_project)"
+mkdir -p "$P/.codex"; printf '{}\n' > "$P/.codex/hooks.json"
+assert_eq "target: codex-only (hooks.json) -> AGENTS.md" "TARGET=$P/AGENTS.md" "$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-target.sh")"
+
+P="$(new_project)"
+mkdir -p "$P/.agents/skills/devlog-start"
+assert_eq "target: codex-only (skills) -> AGENTS.md" "TARGET=$P/AGENTS.md" "$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-target.sh")"
+
+P="$(new_project)"
+printf '# Mine\n\n<!-- devlog-tracker:rules:begin -->\n## devlog-tracker 沉澱的規範\n\n- a\n- b\n<!-- devlog-tracker:rules:end -->\n' > "$P/CLAUDE.md"
+OUT="$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-target.sh")"
+assert_line "target: existing block counted" "EXISTING=2" "$OUT"
+
+# === promote-write.sh ==========================================================
+BEGIN_MARK='<!-- devlog-tracker:rules:begin -->'
+END_MARK='<!-- devlog-tracker:rules:end -->'
+P="$(new_project)"
+RULES="$TMP_ROOT/rules.txt"
+
+# --- target missing -> created with header ---------------------------------------
+printf '  改核心腳本後跑 run-tests.sh  \n\n- 一般 PR 不改版號\n' > "$RULES"
+OUT="$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$RULES")"
+assert_eq "write: new file result" "ADDED=2 SKIPPED_DUP=0 TARGET=$P/CLAUDE.md" "$OUT"
+EXPECTED="$(printf '%s\n## devlog-tracker 沉澱的規範\n\n- 改核心腳本後跑 run-tests.sh\n- 一般 PR 不改版號\n%s' "$BEGIN_MARK" "$END_MARK")"
+assert_eq "write: new file content (trimmed, '- ' prefixed, blank skipped)" "$EXPECTED" "$(cat "$P/CLAUDE.md")"
+
+# --- existing content without block -> appended after a blank line -------------------
+P="$(new_project)"
+printf '# Mine\nkeep me' > "$P/CLAUDE.md"
+printf 'rule one\n' > "$RULES"
+CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$RULES" >/dev/null
+EXPECTED="$(printf '# Mine\nkeep me\n\n%s\n## devlog-tracker 沉澱的規範\n\n- rule one\n%s' "$BEGIN_MARK" "$END_MARK")"
+assert_eq "write: appended after existing content (missing trailing newline handled)" "$EXPECTED" "$(cat "$P/CLAUDE.md")"
+
+# --- existing block -> inserted before end mark; content after block kept -----------
+printf '\n## After\ntail\n' >> "$P/CLAUDE.md"
+printf 'rule two\n' > "$RULES"
+CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$RULES" >/dev/null
+EXPECTED="$(printf '# Mine\nkeep me\n\n%s\n## devlog-tracker 沉澱的規範\n\n- rule one\n- rule two\n%s\n\n## After\ntail' "$BEGIN_MARK" "$END_MARK")"
+assert_eq "write: appended inside existing block" "$EXPECTED" "$(cat "$P/CLAUDE.md")"
+
+# --- exact duplicates (existing + within input) skipped; file unchanged -------------
+BEFORE="$(cat "$P/CLAUDE.md")"
+printf -- '- rule one\nrule two\n' > "$RULES"
+OUT="$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$RULES")"
+assert_eq "write: all duplicates" "ADDED=0 SKIPPED_DUP=2 TARGET=$P/CLAUDE.md" "$OUT"
+assert_eq "write: file unchanged on all-dup" "$BEFORE" "$(cat "$P/CLAUDE.md")"
+printf 'rule three\nrule three\n' > "$RULES"
+OUT="$(CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$RULES")"
+assert_eq "write: duplicate within input counted once" "ADDED=1 SKIPPED_DUP=1 TARGET=$P/CLAUDE.md" "$OUT"
+
+# --- symlink target: write-in-place preserves the link, rules land in the real file --
+P="$(new_project)"
+printf '# Base\n' > "$P/AGENTS.md"
+ln -s AGENTS.md "$P/CLAUDE.md"
+printf 'rule via symlink\n' > "$RULES"
+CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$RULES" >/dev/null
+if [ -L "$P/CLAUDE.md" ]; then echo "PASS: write: symlink target stays a symlink"
+else echo "FAIL: write: symlink was replaced by a regular file"; FAIL=1; fi
+if grep -qF "rule via symlink" "$P/AGENTS.md"; then echo "PASS: write: rules land in the symlink's real target"
+else echo "FAIL: write: rules missing from AGENTS.md"; FAIL=1; fi
+
+# --- mode is preserved on a plain (non-symlink) target -------------------------------
+P="$(new_project)"
+printf '# Mode\n' > "$P/CLAUDE.md"
+chmod 640 "$P/CLAUDE.md"
+printf 'rule mode\n' > "$RULES"
+CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$RULES" >/dev/null
+assert_eq "write: mode preserved (640)" "-rw-r-----" "$(ls -l "$P/CLAUDE.md" | cut -c1-10)"
+
+# --- lock released ------------------------------------------------------------------
+mkdir -p "$P/.devlog"
+CLAUDE_PROJECT_DIR="$P" bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$RULES" >/dev/null
+[ ! -e "$P/.devlog/.lock" ] && echo "PASS: write: lock released" || { echo "FAIL: write: .lock left behind"; FAIL=1; }
+
+# --- usage errors ---------------------------------------------------------------------
+bash "$SCRIPT_DIR/promote-write.sh" >/dev/null 2>&1
+RC=$?
+assert_eq "write: no args exits 2" "2" "$RC"
+bash "$SCRIPT_DIR/promote-write.sh" "$P/CLAUDE.md" "$TMP_ROOT/missing.txt" >/dev/null 2>&1
+RC=$?
+assert_eq "write: missing rules file exits 2" "2" "$RC"
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi