devlog-tracker 0.29.2 → 0.31.0

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

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

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# Self-check for report-devlog.sh (docs/design/read-side-and-promote.md B).
+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"
+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 line [$expected] in: $out)"; FAIL=1; fi
+}
+assert_no_line_prefix() {
+  local desc="$1" prefix="$2" out="$3"
+  if printf '%s\n' "$out" | grep -q "^$prefix"; then echo "FAIL: $desc (found $prefix)"; FAIL=1
+  else echo "PASS: $desc"; fi
+}
+jcheck() {
+  local desc="$1" json="$2" expr="$3"
+  if ! command -v node >/dev/null 2>&1; then echo "SKIP: $desc (no node)"; return 0; fi
+  if printf '%s' "$json" | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8')); process.exit(($expr)?0:1)"; then
+    echo "PASS: $desc"
+  else echo "FAIL: $desc"; FAIL=1; fi
+}
+
+# --- No .devlog -> NOT_STARTED ----------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/report-devlog.sh")"
+assert_line "no .devlog -> NOT_STARTED" "NOT_STARTED" "$OUT"
+
+# --- Fixture ------------------------------------------------------------------
+mkdir -p "$DEVLOG_DIR"
+{
+  cat <<'EOF'
+## Round 1 — 2026-09-01T10:00:00+0800
+
+### User Input
+secret-input-text
+
+### Summary
+EOF
+  printf 'first "quoted" \\ back\ttab 中文\n'
+  cat <<'EOF'
+
+### Handoff
+#### 現況
+x
+
+### Status
+DONE
+
+## Round 2 — 2026-09-02T10:00:00+0800
+
+### Summary
+blocked one
+```
+## Round 9 fake inside fence
+```
+
+### Status
+BLOCKED
+
+## Checkpoint（Round 1-2）
+### 決策
+- keep it
+
+## Round 3 — 2026-09-03T10:00:00+0800
+
+### Summary
+in progress
+
+### 段落 探索
+seg body
+
+### Status
+INTERRUPTED
+[reason: dangling:next_prompt]
+
+## Kept 索引
+- `devlog.topic-a.md`：Round 5-5，kept_at 2026-09-05T00:00:00+0800，topic a
+EOF
+} > "$DEVLOG_DIR/devlog.md"
+cat > "$DEVLOG_DIR/devlog.archive.md" <<'EOF'
+## Round 0 — 2026-08-31T10:00:00+0800
+
+### Summary
+archived
+
+### Status
+DONE
+EOF
+cat > "$DEVLOG_DIR/devlog.topic-a.md" <<'EOF'
+## Round 5 — 2026-09-05T10:00:00+0800
+
+### Summary
+kept topic
+
+### Status
+DONE
+EOF
+cat > "$DEVLOG_DIR/devlog.feat-x.md" <<'EOF'
+## Round 1 — 2026-09-04T10:00:00+0800
+
+### Summary
+branch work
+
+### Status
+IN_PROGRESS
+EOF
+printf '# Lessons: foo\n\n## 2026-09-01T00:00:00+0800\nlesson.\n' > "$DEVLOG_DIR/devlog.lessons.foo.md"
+
+# --- Default KEY=VALUE --------------------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/report-devlog.sh")"
+assert_line "branch" "BRANCH=main" "$OUT"
+assert_line "total rounds = archive + main, fenced fake ignored" "ROUNDS_TOTAL=4" "$OUT"
+assert_line "main rounds" "ROUNDS_MAIN=3" "$OUT"
+assert_line "archive rounds" "ROUNDS_ARCHIVE=1" "$OUT"
+assert_line "done count" "STATUS_DONE=2" "$OUT"
+assert_line "in-progress count (branch file not scanned)" "STATUS_IN_PROGRESS=0" "$OUT"
+assert_line "blocked count" "STATUS_BLOCKED=1" "$OUT"
+assert_line "interrupted count despite reason line" "STATUS_INTERRUPTED=1" "$OUT"
+assert_line "blocked ratio" "BLOCKED_RATIO=25" "$OUT"
+assert_line "checkpoints" "CHECKPOINTS=1" "$OUT"
+assert_line "kept topics" "KEPT_TOPICS=1" "$OUT"
+assert_line "lessons topics" "LESSONS_TOPICS=1" "$OUT"
+assert_line "first round at" "FIRST_ROUND_AT=2026-08-31T10:00:00+0800" "$OUT"
+assert_line "last round at" "LAST_ROUND_AT=2026-09-03T10:00:00+0800" "$OUT"
+assert_no_line_prefix "no advisory state -> no LESSONS_ADVISORY" "LESSONS_ADVISORY=" "$OUT"
+
+printf '%s\n' '{"count": 2, "threshold": 3}' > "$DEVLOG_DIR/.lessons-advisory-state"
+OUT="$(bash "$SCRIPT_DIR/report-devlog.sh")"
+assert_line "advisory state present" "LESSONS_ADVISORY=2/3" "$OUT"
+rm -f "$DEVLOG_DIR/.lessons-advisory-state"
+
+# --- Empty devlog dir: zeros and none ----------------------------------------
+EMPTY_ROOT="$(mktemp -d)"
+mkdir -p "$EMPTY_ROOT/.devlog"
+OUT="$(CLAUDE_PROJECT_DIR="$EMPTY_ROOT" bash "$SCRIPT_DIR/report-devlog.sh")"
+assert_line "empty: zero rounds" "ROUNDS_TOTAL=0" "$OUT"
+assert_line "empty: zero ratio" "BLOCKED_RATIO=0" "$OUT"
+assert_line "empty: first none" "FIRST_ROUND_AT=none" "$OUT"
+rm -rf "$EMPTY_ROOT"
+
+# --- Unknown arg -> exit 2 ------------------------------------------------------
+bash "$SCRIPT_DIR/report-devlog.sh" --bogus >/dev/null 2>&1
+RC=$?
+if [ "$RC" -eq 2 ]; then echo "PASS: unknown arg exits 2"; else echo "FAIL: unknown arg exit $RC"; FAIL=1; fi
+
+# --- --json (no rounds) -------------------------------------------------------
+J="$(bash "$SCRIPT_DIR/report-devlog.sh" --json)"
+jcheck "json: started + counts are numbers" "$J" 'd.started===true && d.rounds_total===4 && d.status_blocked===1 && d.blocked_ratio===25'
+jcheck "json: branch + times" "$J" 'd.branch==="main" && d.first_round_at==="2026-08-31T10:00:00+0800"'
+jcheck "json: no advisory -> null" "$J" 'd.lessons_advisory===null'
+jcheck "json: no rounds array without --rounds" "$J" '!("rounds" in d) && !("checkpoint_blocks" in d)'
+
+# --- --json --rounds ------------------------------------------------------------
+J="$(bash "$SCRIPT_DIR/report-devlog.sh" --json --rounds)"
+jcheck "rounds: 4 entries, archive first" "$J" 'd.rounds.length===4 && d.rounds[0].branch==="archive" && d.rounds[0].n===0'
+jcheck "rounds: escaping survives quote/backslash/tab/CJK" "$J" 'd.rounds[1].summary.includes("\"quoted\"") && d.rounds[1].summary.includes("\\") && d.rounds[1].summary.includes("\t") && d.rounds[1].summary.includes("中文")'
+jcheck "rounds: fenced fake heading stays inside summary" "$J" 'd.rounds[2].summary.includes("## Round 9 fake inside fence")'
+jcheck "rounds: status parsed despite reason line" "$J" 'd.rounds[3].status==="INTERRUPTED"'
+jcheck "rounds: segments captured" "$J" 'd.rounds[3].segments.length===1 && d.rounds[3].segments[0]==="段落 探索\nseg body"'
+jcheck "rounds: handoff keeps #### lines" "$J" 'd.rounds[1].handoff.startsWith("#### 現況")'
+jcheck "rounds: line numbers" "$J" 'd.rounds[1].line===1 && d.rounds[1].file==="devlog.md"'
+jcheck "rounds: no input by default" "$J" 'd.rounds.every(r => !("input" in r))'
+jcheck "checkpoint_blocks: one block with body" "$J" 'd.checkpoint_blocks.length===1 && d.checkpoint_blocks[0].heading==="Checkpoint（Round 1-2）" && d.checkpoint_blocks[0].body.includes("keep it")'
+
+J="$(bash "$SCRIPT_DIR/report-devlog.sh" --json --rounds --with-input)"
+jcheck "with-input: input field present" "$J" 'd.rounds[1].input==="secret-input-text"'
+
+# --- --json on NOT_STARTED ------------------------------------------------------
+NS_ROOT="$(mktemp -d)"
+J="$(CLAUDE_PROJECT_DIR="$NS_ROOT" bash "$SCRIPT_DIR/report-devlog.sh" --json)"
+jcheck "json NOT_STARTED" "$J" 'd.started===false'
+rm -rf "$NS_ROOT"
+
+# --- --all-branches ---------------------------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/report-devlog.sh" --all-branches)"
+assert_line "all-branches: branch file added, kept file excluded" "ROUNDS_TOTAL=5" "$OUT"
+assert_line "all-branches: in-progress from branch file" "STATUS_IN_PROGRESS=1" "$OUT"
+assert_line "all-branches: last round from branch file" "LAST_ROUND_AT=2026-09-04T10:00:00+0800" "$OUT"
+J="$(bash "$SCRIPT_DIR/report-devlog.sh" --json --rounds --all-branches)"
+jcheck "all-branches: feat-x rounds tagged" "$J" 'd.rounds.some(r => r.branch==="feat-x" && r.summary==="branch work")'
+jcheck "all-branches: no kept or lessons rounds" "$J" 'd.rounds.every(r => r.branch!=="topic-a" && !r.branch.startsWith("lessons."))'
+
+# --- control chars outside \t\r\n (e.g. pasted ANSI \033) escape to \uXXXX ------
+CTRL_ROOT="$(mktemp -d)"
+mkdir -p "$CTRL_ROOT/.devlog"
+printf '## Round 1 — 2026-09-06T10:00:00+0800\n\n### Summary\nboom\033[31mred\n\n### Status\nDONE\n' \
+  > "$CTRL_ROOT/.devlog/devlog.md"
+J="$(CLAUDE_PROJECT_DIR="$CTRL_ROOT" bash "$SCRIPT_DIR/report-devlog.sh" --json --rounds)"
+jcheck "control char (ESC) escapes to \\u001b, JSON still parses" "$J" 'd.rounds[0].summary.includes("\x1b")'
+rm -rf "$CTRL_ROOT"
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/core/scripts/tests/test-round-start.sh

@@ -652,6 +652,13 @@ else
 fi
 rm -f "$DEVLOG_DIR/.checkpoint-state"
 
+# --- 19b: report / timeline are admin (read-side) commands too -------------
+for ADMIN_CMD in report timeline; do
+  rm -f "$DEVLOG_DIR/.round-current.md" "$DEVLOG_DIR/.round-open"
+  printf '{"prompt":"<command-name>/devlog-tracker:%s</command-name>"}' "$ADMIN_CMD" | bash "$SCRIPT_DIR/round-start.sh"
+  assert_file_absent "admin $ADMIN_CMD: no .round-current.md" "$DEVLOG_DIR/.round-current.md"
+done
+
 # --- 20: a namespaced-but-different command name is not falsely exempted ---
 # "lessons-on" must not match the "lessons" case arm (prefix collision guard).
 LESSONS_ON_PROMPT='<command-name>/devlog-tracker:lessons-on</command-name><command-message>lessons-on</command-message><command-args></command-args>'
@@ -677,6 +684,15 @@ else
 fi
 rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
 
+# --- 21b: /devlog-tracker:pr and :promote are NOT exempt (outward / file writes)
+for WORK_CMD in pr promote; do
+  rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
+  printf '{"prompt":"<command-name>/devlog-tracker:%s</command-name>"}' "$WORK_CMD" | bash "$SCRIPT_DIR/round-start.sh"
+  CUR_BODY="$(cat "$DEVLOG_DIR/.round-current.md" 2>/dev/null || echo '')"
+  assert_contains "$WORK_CMD command still opens a Round" "## Round 1 —" "$CUR_BODY"
+done
+rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
+
 # --- workspace claim on next prompt ----------------------------------------
 WS="$TMP_ROOT/ws"
 mkdir -p "$WS/.devlog"
@@ -1050,6 +1066,55 @@ assert_not_contains "lessons off: no BLOCKED-accumulation advisory" "[Lessons Mo
 rm -rf "$NOLES_DIR"
 export CLAUDE_PROJECT_DIR="$TMP_ROOT"
 
+# --- lessons: background agent / workflow task-notification advisory ------
+TN_DIR="$(mktemp -d)"
+mkdir -p "$TN_DIR/.devlog"
+touch "$TN_DIR/.devlog/.enabled" "$TN_DIR/.devlog/.lessons-enabled"
+export CLAUDE_PROJECT_DIR="$TN_DIR"
+tn_notif() {
+  printf '{"prompt":"<task-notification><task-id>t9</task-id><status>%s</status><summary>Agent \\"x\\" finished</summary></task-notification>"}' "$1"
+}
+tn_reset() {
+  rm -f "$TN_DIR/.devlog/.round-open" "$TN_DIR/.devlog/.round-current.md"
+  printf '## Round 1 — 2026-09-23T00:00:00+0800\n\n### User Input\n```text\nx\n```\n\n### Summary\ns\n\n### Status\nDONE\n' > "$TN_DIR/.devlog/devlog.md"
+}
+
+tn_reset
+printf '%s\n' '{"count": 0, "threshold": 3}' > "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif completed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif completed: sub agent advisory printed" "[Lessons Mode 提示] 背景任務完成（status=completed）" "$OUT"
+grep -q '"count": 0' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif completed does not bump counter" || { echo "FAIL: completed bumped counter"; FAIL=1; }
+
+tn_reset
+OUT="$(tn_notif failed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif failed: advisory printed" "背景任務完成（status=failed）" "$OUT"
+grep -q '"count": 1' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif failed bumps counter" || { echo "FAIL: failed did not bump counter"; FAIL=1; }
+
+tn_reset
+printf '%s\n' '{"count": 2, "threshold": 3}' > "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif killed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif killed at threshold: shared nudge printed" "流程訊號已累積出現 3 次" "$OUT"
+grep -q '"count": 0' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif killed resets counter at threshold" || { echo "FAIL: killed did not reset counter"; FAIL=1; }
+
+tn_reset
+printf '%s\n' '{"round": 1, "ticks_since_checkin": 0, "max_silent_ticks": 5}' > "$TN_DIR/.devlog/.span-open"
+OUT="$(tn_notif completed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif during span: advisory still printed" "背景任務完成（status=completed）" "$OUT"
+rm -f "$TN_DIR/.devlog/.span-open"
+
+tn_reset
+rm -f "$TN_DIR/.devlog/.lessons-enabled" "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif failed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "task-notif with lessons off: no advisory" "[Lessons Mode 提示]" "$OUT"
+[ ! -f "$TN_DIR/.devlog/.lessons-advisory-state" ] && echo "PASS: task-notif with lessons off leaves no advisory-state" || { echo "FAIL: advisory-state created while lessons off"; FAIL=1; }
+
+touch "$TN_DIR/.devlog/.lessons-enabled"
+tn_reset
+OUT="$(printf '%s' '{"prompt":"plain message"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "plain prompt: no background-task advisory" "背景任務完成" "$OUT"
+rm -rf "$TN_DIR"
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+
 if [ "$FAIL" -eq 0 ]; then
   echo "All checks passed."
   exit 0

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

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Self-check for timeline-devlog.sh (docs/design/read-side-and-promote.md C).
+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"
+FAIL=0
+pass() { echo "PASS: $1"; }
+fail() { echo "FAIL: $1"; FAIL=1; }
+
+# --- NO_NODE: node missing from PATH (checked before anything else) ----------
+EMPTY_BIN="$TMP_ROOT/empty-bin"
+mkdir -p "$EMPTY_BIN"
+BASH_BIN="$(command -v bash)"
+OUT="$(PATH="$EMPTY_BIN" "$BASH_BIN" "$SCRIPT_DIR/timeline-devlog.sh" 2>&1)"
+[ "$OUT" = "NO_NODE" ] && pass "no node -> NO_NODE" || fail "no node -> NO_NODE (got $OUT)"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "SKIP: remaining timeline checks need node"
+  if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0; else echo "Some checks FAILED."; exit 1; fi
+fi
+
+# --- NOT_STARTED --------------------------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/timeline-devlog.sh")"
+[ "$OUT" = "NOT_STARTED" ] && pass "no .devlog -> NOT_STARTED" || fail "NOT_STARTED (got $OUT)"
+[ ! -e "$DEVLOG_DIR" ] && pass "NOT_STARTED creates nothing" || fail "NOT_STARTED created .devlog"
+
+# --- End to end -----------------------------------------------------------------
+mkdir -p "$DEVLOG_DIR"
+cat > "$DEVLOG_DIR/devlog.md" <<'EOF2'
+## Round 1 — 2026-09-01T10:00:00+0800
+
+### User Input
+secret-input-text
+
+### Summary
+<script>alert(1)</script> 中文摘要
+
+### Status
+DONE
+EOF2
+OUT="$(bash "$SCRIPT_DIR/timeline-devlog.sh")"
+case "$OUT" in
+  "OUT=$(cd "$DEVLOG_DIR" && pwd)/timeline.html") pass "default OUT path is absolute .devlog/timeline.html" ;;
+  *) fail "default OUT (got $OUT)" ;;
+esac
+HTML="$DEVLOG_DIR/timeline.html"
+grep -q '中文摘要' "$HTML" && pass "summary rendered" || fail "summary missing"
+grep -q '<script>alert' "$HTML" && fail "raw script tag leaked" || pass "script tag escaped"
+grep -q 'secret-input-text' "$HTML" && fail "User Input leaked" || pass "User Input not included"
+[ ! -e "$HTML.tmp" ] && pass "no leftover tmp file" || fail "leftover $HTML.tmp"
+
+# --- --out ------------------------------------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/timeline-devlog.sh" --out "$TMP_ROOT/custom.html")"
+[ -s "$TMP_ROOT/custom.html" ] && pass "--out writes the given path" || fail "--out ($OUT)"
+
+# --- unknown arg ------------------------------------------------------------------
+bash "$SCRIPT_DIR/timeline-devlog.sh" --bogus >/dev/null 2>&1
+RC=$?
+[ "$RC" -eq 2 ] && pass "unknown arg exits 2" || fail "unknown arg exit $RC"
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/core/scripts/timeline-devlog.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# /devlog-tracker:timeline and `npx devlog-tracker timeline`
+# (docs/design/read-side-and-promote.md C): report-devlog.sh --json --rounds
+# piped into timeline-render.js, written to .devlog/timeline.html (gitignored).
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+
+# Checked before sourcing anything: Claude plugin users may not have Node.
+command -v node >/dev/null 2>&1 || { echo "NO_NODE"; exit 0; }
+
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+
+ALL=0
+OUT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --all-branches) ALL=1 ;;
+    --out) shift; OUT="${1:-}" ;;
+    *) echo "UNKNOWN_ARG=$1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+[ -d "$DEVLOG_DIR" ] || { echo "NOT_STARTED"; exit 0; }
+[ -n "$OUT" ] || OUT="$DEVLOG_DIR/timeline.html"
+
+ARGS=(--json --rounds)
+[ "$ALL" -eq 1 ] && ARGS+=(--all-branches)
+
+JSON_TMP="$(mktemp "${TMPDIR:-/tmp}/devlog-timeline.XXXXXX")" || exit 1
+trap 'rm -f "$JSON_TMP" "$OUT.tmp"' EXIT
+bash "$SCRIPT_DIR/report-devlog.sh" "${ARGS[@]}" > "$JSON_TMP" || exit 1
+node "$SCRIPT_DIR/timeline-render.js" < "$JSON_TMP" > "$OUT.tmp" || exit 1
+mv "$OUT.tmp" "$OUT" || exit 1
+
+OUT_DIR="$(cd "$(dirname "$OUT")" && pwd)"
+echo "OUT=$OUT_DIR/$(basename "$OUT")"