devlog-tracker 0.31.1 → 0.32.0

package/README.md

@@ -2,7 +2,7 @@
 
 *English | [繁體中文](README.zh-TW.md)*
 
-**Version** 0.31.1
+**Version** 0.32.0
 
 Maintains a `.devlog/devlog.md` in your project, turning each conversation round's requests, decisions, and outcomes into a permanent record. A conversation disappears the moment you `/clear` or switch sessions; this file fills that gap so work can pause and resume. Nothing is touched until you explicitly run `/devlog-tracker:start` — installing the plugin alone doesn't create or modify any files.
 
@@ -233,7 +233,7 @@ When Claude ends a turn with a plain-text question and the next message is the a
 
 #### Per-branch devlog files
 
-Switching branches within the same working directory automatically splits the main file by the checked-out branch: `main`/`master` keeps using `.devlog/devlog.md`, while other branches each use `.devlog/devlog.<branch>.md` (slashes converted to `-`). A separate `git worktree` (a different directory) already has its own independent `.devlog/` and is unaffected by this mechanism. The first time a branch is detected without its own file while `devlog.md` already has content, it gets renamed (not copied) into that branch's file. See [`docs/design/branch-scoped-devlog.md`](docs/design/branch-scoped-devlog.md).
+Switching branches within the same working directory automatically splits the main file by the checked-out branch: `main`/`master` keeps using `.devlog/devlog.md`, while other branches each use `.devlog/devlog.<branch>.md` (slashes converted to `-`). A separate `git worktree` (a different directory) already has its own independent `.devlog/` and is unaffected by this mechanism. The first time a branch is detected without its own file, only the unfinished tail of `devlog.md` (the Rounds after the last `DONE`, plus `handoff.md`) is cut into that branch's file; `main`'s own history, project summary, Checkpoints, and Kept/Lessons indexes stay in `devlog.md`. If the last Round is already `DONE`, or the branch checked out doesn't contain the current `main` tip (an older branch), nothing moves and the branch starts with an empty file. See [`docs/design/branch-scoped-devlog.md`](docs/design/branch-scoped-devlog.md).
 
 #### Lessons Mode (off by default, not automatic)
 

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 *[English](README.md) | 繁體中文*
 
-**版本** 0.31.1
+**版本** 0.32.0
 
 在專案中維護一份 `.devlog/devlog.md`，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 `/clear` 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 `/devlog-tracker:start` 時，裝著也不會動任何檔案。
 
@@ -233,7 +233,7 @@ Claude 用純文字結尾提出問題、下一則訊息才拿到答案時，不
 
 #### 分支各自的 devlog 檔
 
-同一個工作目錄裡切換分支時，主檔會依目前 checkout 的分支自動分開：`main`／`master` 繼續用 `.devlog/devlog.md`，其他分支各自用 `.devlog/devlog.<branch>.md`（斜線轉成 `-`）。另開一個 `git worktree`（不同目錄）本來就有自己獨立的 `.devlog/`，不受這個機制影響。第一次在某分支偵測到還沒有專屬檔案、且 `devlog.md` 已有內容時，會把它改名（非複製）成該分支的檔案。細節見 [`docs/design/branch-scoped-devlog.md`](docs/design/branch-scoped-devlog.md)。
+同一個工作目錄裡切換分支時，主檔會依目前 checkout 的分支自動分開：`main`／`master` 繼續用 `.devlog/devlog.md`，其他分支各自用 `.devlog/devlog.<branch>.md`（斜線轉成 `-`）。另開一個 `git worktree`（不同目錄）本來就有自己獨立的 `.devlog/`，不受這個機制影響。第一次在某分支偵測到還沒有專屬檔案時，只會把 `devlog.md` 裡還沒完成的尾巴（最後一個 `DONE` 之後的 Round，連同 `handoff.md`）剪到該分支的檔案；`main` 自己的歷史、專案摘要、Checkpoint、Kept／Lessons 索引都留在 `devlog.md`。最後一輪已經是 `DONE`，或切到的是不含目前 `main` 最新 commit 的舊分支時，什麼都不搬，新分支從空檔開始。細節見 [`docs/design/branch-scoped-devlog.md`](docs/design/branch-scoped-devlog.md)。
 
 #### Lessons Mode（預設關閉，不自動）
 

package/core/scripts/devlog-path.sh

@@ -6,6 +6,8 @@
 _DEVLOG_PATH_DIR="$(cd "${BASH_SOURCE[0]%/*}" && pwd)"
 # shellcheck source=devlog-lock.sh
 . "$_DEVLOG_PATH_DIR/devlog-lock.sh"
+# shellcheck source=devlog-md.sh
+. "$_DEVLOG_PATH_DIR/devlog-md.sh"
 
 # Turns an arbitrary branch/worktree name into a safe devlog.<name>.md
 # filename segment: anything outside [A-Za-z0-9._-] becomes '-', repeats
@@ -14,6 +16,74 @@ _devlog_sanitize_name() {
   printf '%s' "$1" | sed -E 's/[^A-Za-z0-9._-]/-/g; s/-+/-/g; s/^-+//; s/-+$//'
 }
 
+# Cuts the unfinished tail of $2 (the shared devlog.md) into $3 (a branch
+# file that doesn't exist yet): every "## Round" block after the last one
+# whose Status is DONE. Nothing moves when the last round is DONE, when
+# there are no rounds, or when HEAD doesn't contain the local main/master
+# tip (an older branch being checked out, not one just forked from the
+# work in progress). The project header, Checkpoints, and Kept/Lessons
+# indexes always stay in $2. When rounds move, $4 (handoff.md) moves to
+# $5 too, since it snapshots that same unfinished work. Caller holds the
+# devlog lock.
+_devlog_migrate_unfinished_tail() {
+  local dir="$1" src="$2" dst="$3" src_handoff="$4" dst_handoff="$5"
+  [ -s "$src" ] || return 0
+
+  # Cheap early exit first: until the branch file exists, every hook
+  # re-resolves, so the common "main ended DONE" case must not scan every
+  # round each time.
+  local start end status
+  start="$(devlog_list_round_starts "$src" | awk 'END { print $1 }')"
+  [ -n "$start" ] || return 0
+  end="$(devlog_block_end "$src" "$start")"
+  status="$(devlog_round_status "$src" "$start" "$end" | tr -d '[:space:]')"
+  [ "$status" != DONE ] || return 0
+
+  local base
+  base="$(git -C "$dir" for-each-ref --format='%(refname:short)' refs/heads/ 2>/dev/null \
+    | grep -ixE 'main|master' | head -1)"
+  [ -n "$base" ] || return 0
+  git -C "$dir" merge-base --is-ancestor "$base" HEAD 2>/dev/null || return 0
+
+  local ranges=""
+  for start in $(devlog_list_round_starts "$src" | awk '{ print $1 }'); do
+    end="$(devlog_block_end "$src" "$start")"
+    status="$(devlog_round_status "$src" "$start" "$end" | tr -d '[:space:]')"
+    if [ "$status" = DONE ]; then ranges=""; else ranges="$ranges $start:$end"; fi
+  done
+  [ -n "$ranges" ] || return 0
+
+  # Split in one pass: lines inside a moved range go to $dst, the rest stay.
+  # Trailing blank lines are dropped from both so later appends keep the
+  # usual single-blank-line separator.
+  local drop_trailing_blanks='
+    /^[ \t]*$/ { pending = pending $0 ORS; next }
+    { printf "%s", pending; pending = ""; print }
+  '
+  awk -v ranges="$ranges" '
+    BEGIN {
+      n = split(ranges, r, " ")
+      for (i = 1; i <= n; i++) { split(r[i], se, ":"); s[i] = se[1]; e[i] = se[2] }
+    }
+    {
+      moved = 0
+      for (i = 1; i <= n; i++) if (NR >= s[i] && NR <= e[i]) { moved = 1; break }
+      print moved ? "M" $0 : "K" $0
+    }
+  ' "$src" > "$src.split" 2>/dev/null || { rm -f "$src.split"; return 0; }
+  sed -n 's/^M//p' "$src.split" | awk "$drop_trailing_blanks" > "$dst.tmp" 2>/dev/null
+  sed -n 's/^K//p' "$src.split" | awk "$drop_trailing_blanks" > "$src.tmp" 2>/dev/null
+  rm -f "$src.split"
+
+  # Branch file first: if the second mv fails the tail is duplicated, never lost.
+  if mv "$dst.tmp" "$dst" 2>/dev/null && mv "$src.tmp" "$src" 2>/dev/null; then
+    if [ -f "$src_handoff" ] && [ ! -f "$dst_handoff" ]; then
+      mv "$src_handoff" "$dst_handoff" 2>/dev/null || true
+    fi
+  fi
+  rm -f "$dst.tmp" "$src.tmp" 2>/dev/null || true
+}
+
 # Sets DEVLOG_DIR, DEVLOG_FILE, and HANDOFF_FILE for the branch currently
 # checked out in $1 (defaults to "."). main/master (any case) and anything
 # that isn't a git repo or has no resolvable branch keep the shared
@@ -21,10 +91,9 @@ _devlog_sanitize_name() {
 # devlog.<sanitized-branch>.md and handoff.<sanitized-branch>.md; a
 # detached HEAD (or an unborn branch, which git also reports as "HEAD"
 # here) falls back to the working directory's own basename. The first
-# time a branch resolves to a file that doesn't exist yet while
-# devlog.md already has content, the existing devlog.md is renamed (not
-# copied) into that branch's file. handoff.md is never renamed on first
-# resolve (current-state snapshot, not history).
+# time a branch resolves to a file that doesn't exist yet, only
+# devlog.md's unfinished tail is cut into it (see
+# _devlog_migrate_unfinished_tail); main's own history stays in devlog.md.
 devlog_resolve_paths() {
   local dir="${1:-.}"
   DEVLOG_DIR="$dir/.devlog"
@@ -66,12 +135,14 @@ devlog_resolve_paths() {
   esac
 
   local resolved="$DEVLOG_DIR/devlog.$name.md"
-  if [ -f "$DEVLOG_DIR/.enabled" ] && [ ! -f "$resolved" ] && [ -f "$DEVLOG_FILE" ]; then
+  local resolved_handoff="$DEVLOG_DIR/handoff.$name.md"
+  if [ -f "$DEVLOG_DIR/.enabled" ] && [ ! -f "$resolved" ] && [ -s "$DEVLOG_FILE" ]; then
     devlog_lock_acquire
-    mv "$DEVLOG_FILE" "$resolved" 2>/dev/null || true
+    [ -f "$resolved" ] || _devlog_migrate_unfinished_tail \
+      "$dir" "$DEVLOG_FILE" "$resolved" "$HANDOFF_FILE" "$resolved_handoff"
     devlog_lock_release
   fi
   DEVLOG_FILE="$resolved"
   # shellcheck disable=SC2034 # consumed by callers (e.g. enforce-devlog.sh), not used in this file
-  HANDOFF_FILE="$DEVLOG_DIR/handoff.$name.md"
+  HANDOFF_FILE="$resolved_handoff"
 }

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

@@ -69,35 +69,124 @@ devlog_resolve_paths "$DETACHEDREPO"
   && echo "PASS: detached HEAD falls back to worktree dirname" \
   || { echo "FAIL: detached got $DEVLOG_FILE"; FAIL=1; }
 
-# --- migration: existing devlog.md content moves to branch file ----------
-MIGREPO="$TMP/migrepo"
-mkdir -p "$MIGREPO/.devlog"
-: > "$MIGREPO/.devlog/.enabled"
-git_setup "$MIGREPO"
-git -C "$MIGREPO" checkout -q -b feature-y
-echo "## Round 1 existing content" > "$MIGREPO/.devlog/devlog.md"
-devlog_resolve_paths "$MIGREPO"
-if [ "$DEVLOG_FILE" = "$MIGREPO/.devlog/devlog.feature-y.md" ] \
+# Writes a devlog.md with a project header, the given rounds (as
+# "<n>:<STATUS>" pairs), a Checkpoint between rounds 1 and 2, and a
+# trailing Kept 索引.
+write_main_devlog() {
+  local file="$1"; shift
+  {
+    printf '# 專案摘要\n\nheader line\n'
+    local pair n st
+    for pair in "$@"; do
+      n="${pair%%:*}"; st="${pair#*:}"
+      printf '\n## Round %s — t\n\n### Summary\nround %s body\n\n### Status\n%s\n' "$n" "$n" "$st"
+      [ "$n" = 1 ] && printf '\n## Checkpoint — t\n\ncheckpoint body\n'
+    done
+    printf '\n## Kept 索引\n\n- devlog.old.md — kept topic\n'
+  } > "$file"
+}
+
+# New repo on main with .enabled; leaves the caller on main.
+mig_repo() {
+  mkdir -p "$1/.devlog"
+  : > "$1/.devlog/.enabled"
+  git_setup "$1"
+  git -C "$1" branch -M main
+}
+
+# --- main's last round DONE: new branch starts empty, devlog.md untouched --
+DONEREPO="$TMP/donerepo"
+mig_repo "$DONEREPO"
+write_main_devlog "$DONEREPO/.devlog/devlog.md" 1:DONE 2:DONE
+cp "$DONEREPO/.devlog/devlog.md" "$TMP/done-before.md"
+echo "main handoff" > "$DONEREPO/.devlog/handoff.md"
+git -C "$DONEREPO" checkout -q -b feature-done
+devlog_resolve_paths "$DONEREPO"
+if [ "$DEVLOG_FILE" = "$DONEREPO/.devlog/devlog.feature-done.md" ] \
+  && [ ! -f "$DEVLOG_FILE" ] \
+  && cmp -s "$DONEREPO/.devlog/devlog.md" "$TMP/done-before.md" \
+  && [ -f "$DONEREPO/.devlog/handoff.md" ] \
+  && [ ! -f "$DONEREPO/.devlog/handoff.feature-done.md" ]; then
+  echo "PASS: main ending DONE leaves devlog.md alone, branch starts empty"
+else
+  echo "FAIL: DONE-tail migration moved something (file=$DEVLOG_FILE)"
+  FAIL=1
+fi
+
+# --- unfinished tail: rounds after the last DONE are cut into branch file --
+TAILREPO="$TMP/tailrepo"
+mig_repo "$TAILREPO"
+write_main_devlog "$TAILREPO/.devlog/devlog.md" 1:DONE 2:DONE 3:BLOCKED 4:IN_PROGRESS
+echo "main handoff" > "$TAILREPO/.devlog/handoff.md"
+git -C "$TAILREPO" checkout -q -b feature-y
+devlog_resolve_paths "$TAILREPO"
+MAINF="$TAILREPO/.devlog/devlog.md"
+if [ "$DEVLOG_FILE" = "$TAILREPO/.devlog/devlog.feature-y.md" ] \
   && [ -f "$DEVLOG_FILE" ] \
-  && [ ! -f "$MIGREPO/.devlog/devlog.md" ] \
-  && grep -q "existing content" "$DEVLOG_FILE"; then
-  echo "PASS: migration renames devlog.md into branch file"
+  && [ "$(devlog_list_round_starts "$DEVLOG_FILE" | awk '{print $2}' | tr '\n' ' ')" = "3 4 " ] \
+  && [ "$(devlog_list_round_starts "$MAINF" | awk '{print $2}' | tr '\n' ' ')" = "1 2 " ] \
+  && ! grep -q "round 3 body\|round 4 body" "$MAINF" \
+  && grep -q "^# 專案摘要" "$MAINF" && ! grep -q "^# 專案摘要" "$DEVLOG_FILE" \
+  && grep -q "^## Checkpoint" "$MAINF" && ! grep -q "^## Checkpoint" "$DEVLOG_FILE" \
+  && grep -q "^## Kept 索引" "$MAINF" && ! grep -q "^## Kept 索引" "$DEVLOG_FILE" \
+  && [ ! -f "$TAILREPO/.devlog/handoff.md" ] \
+  && grep -q "main handoff" "$TAILREPO/.devlog/handoff.feature-y.md"; then
+  echo "PASS: unfinished tail (rounds after last DONE) cut into branch file with handoff"
 else
-  echo "FAIL: migration file=$DEVLOG_FILE"
+  echo "FAIL: tail migration (file=$DEVLOG_FILE)"
+  echo "--- devlog.md"; cat "$MAINF"; echo "--- branch"; cat "$DEVLOG_FILE" 2>/dev/null
   FAIL=1
 fi
 
-# --- migration is idempotent: second call doesn't re-move or error -------
-echo "## Round 2 written after migration" >> "$MIGREPO/.devlog/devlog.feature-y.md"
-devlog_resolve_paths "$MIGREPO"
-if [ "$DEVLOG_FILE" = "$MIGREPO/.devlog/devlog.feature-y.md" ] \
-  && grep -q "Round 2 written after migration" "$DEVLOG_FILE"; then
+# --- tail migration is idempotent: branch file exists, nothing re-moves ----
+echo "## Round 5 written after migration" >> "$TAILREPO/.devlog/devlog.feature-y.md"
+cp "$MAINF" "$TMP/tail-main-after.md"
+devlog_resolve_paths "$TAILREPO"
+if [ "$DEVLOG_FILE" = "$TAILREPO/.devlog/devlog.feature-y.md" ] \
+  && grep -q "Round 5 written after migration" "$DEVLOG_FILE" \
+  && cmp -s "$MAINF" "$TMP/tail-main-after.md"; then
   echo "PASS: second resolve is a no-op, content preserved"
 else
   echo "FAIL: second resolve altered state, got $DEVLOG_FILE"
   FAIL=1
 fi
 
+# --- no DONE round at all: every round moves, header/index stay ----------
+NODONEREPO="$TMP/nodonerepo"
+mig_repo "$NODONEREPO"
+write_main_devlog "$NODONEREPO/.devlog/devlog.md" 1:INTERRUPTED 2:IN_PROGRESS
+git -C "$NODONEREPO" checkout -q -b feature-n
+devlog_resolve_paths "$NODONEREPO"
+if [ "$(devlog_list_round_starts "$DEVLOG_FILE" 2>/dev/null | awk '{print $2}' | tr '\n' ' ')" = "1 2 " ] \
+  && [ -z "$(devlog_list_round_starts "$NODONEREPO/.devlog/devlog.md")" ] \
+  && grep -q "^## Kept 索引" "$NODONEREPO/.devlog/devlog.md" \
+  && grep -q "^## Checkpoint" "$NODONEREPO/.devlog/devlog.md"; then
+  echo "PASS: with no DONE round, all rounds move and non-round sections stay"
+else
+  echo "FAIL: no-DONE migration (file=$DEVLOG_FILE)"
+  FAIL=1
+fi
+
+# --- stale branch (doesn't contain main's tip): nothing moves -------------
+STALEREPO="$TMP/stalerepo"
+mig_repo "$STALEREPO"
+git -C "$STALEREPO" branch old-branch
+git -C "$STALEREPO" -c user.email=t@t.t -c user.name=t commit -q --allow-empty -m "main moves on"
+write_main_devlog "$STALEREPO/.devlog/devlog.md" 1:DONE 2:IN_PROGRESS
+cp "$STALEREPO/.devlog/devlog.md" "$TMP/stale-before.md"
+echo "main handoff" > "$STALEREPO/.devlog/handoff.md"
+git -C "$STALEREPO" checkout -q old-branch
+devlog_resolve_paths "$STALEREPO"
+if [ "$DEVLOG_FILE" = "$STALEREPO/.devlog/devlog.old-branch.md" ] \
+  && [ ! -f "$DEVLOG_FILE" ] \
+  && cmp -s "$STALEREPO/.devlog/devlog.md" "$TMP/stale-before.md" \
+  && [ -f "$STALEREPO/.devlog/handoff.md" ]; then
+  echo "PASS: checking out a branch that lacks main's tip moves nothing"
+else
+  echo "FAIL: stale branch took main's tail (file=$DEVLOG_FILE)"
+  FAIL=1
+fi
+
 # --- migration does NOT fire when .devlog/.enabled is absent (Fix 6) -----
 NOENABLEDREPO="$TMP/noenabledrepo"
 mkdir -p "$NOENABLEDREPO/.devlog"
@@ -140,23 +229,5 @@ devlog_resolve_paths "$DETACHEDREPO"
   && echo "PASS: detached HANDOFF_FILE uses worktree dirname" \
   || { echo "FAIL: detached HANDOFF_FILE=$HANDOFF_FILE"; FAIL=1; }
 
-# migration must NOT move handoff.md
-MIGHO="$TMP/mighandoff"
-mkdir -p "$MIGHO/.devlog"
-: > "$MIGHO/.devlog/.enabled"
-git_setup "$MIGHO"
-git -C "$MIGHO" checkout -q -b feature-h
-echo "old handoff" > "$MIGHO/.devlog/handoff.md"
-echo "## Round 1" > "$MIGHO/.devlog/devlog.md"
-devlog_resolve_paths "$MIGHO"
-if [ -f "$MIGHO/.devlog/handoff.md" ] \
-  && [ ! -f "$MIGHO/.devlog/handoff.feature-h.md" ] \
-  && [ "$HANDOFF_FILE" = "$MIGHO/.devlog/handoff.feature-h.md" ]; then
-  echo "PASS: handoff.md is not renamed on first branch resolve"
-else
-  echo "FAIL: handoff migration diverged (HANDOFF_FILE=$HANDOFF_FILE)"
-  FAIL=1
-fi
-
 if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
 else echo "Some checks FAILED."; exit 1; fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlog-tracker",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "npx installer for devlog-tracker's Claude Code, Cursor and Codex adapters.",
   "bin": {
     "devlog-tracker": "bin/devlog-tracker.js"

package/skills/devlog-tracker/SKILL.md

@@ -70,7 +70,7 @@ Summary/Handoff」——後面這句要整句刪掉，不是縮短。
 ## 檔案位置
 
 - 主檔：`.devlog/devlog.md`——在 `main`／`master` 分支上工作時使用
-- 分支主檔：`.devlog/devlog.<branch>.md`——在同一個 worktree 裡切換到其他分支時，主檔會依目前 checkout 的分支自動分開（斜線轉成 `-`）；detached HEAD 退回用 worktree 目錄名。另開一個 `git worktree`（不同目錄）本來就有自己獨立的 `.devlog/`，不受這個機制影響。第一次在某分支偵測到還沒有專屬檔案、且 `.devlog/devlog.md` 已有內容時，會把它改名（非複製）成該分支的檔案。細節見 `docs/design/branch-scoped-devlog.md`。
+- 分支主檔：`.devlog/devlog.<branch>.md`——在同一個 worktree 裡切換到其他分支時，主檔會依目前 checkout 的分支自動分開（斜線轉成 `-`）；detached HEAD 退回用 worktree 目錄名。另開一個 `git worktree`（不同目錄）本來就有自己獨立的 `.devlog/`，不受這個機制影響。第一次在某分支偵測到還沒有專屬檔案時，只會把 `devlog.md` 裡還沒完成的尾巴（最後一個 `DONE` 之後的 Round，連同 `handoff.md`）剪到該分支的檔案；`main` 自己的歷史、專案摘要、Checkpoint、Kept／Lessons 索引都留在 `devlog.md`。最後一輪已經是 `DONE`，或切到的是不含目前 `main` 最新 commit 的舊分支時，什麼都不搬，新分支從空檔開始。細節見 `docs/design/branch-scoped-devlog.md`。
 - 歸檔：`.devlog/devlog.archive.md`
 - 具名保存：`.devlog/devlog.<name>.md`（`/devlog-tracker:keep` 搬走的主題檔；SessionStart 不讀這些檔）
 - 當輪暫存：`.devlog/.round-current.md`（目前開著的那一輪，Claude 該讀寫的是這個檔，不是 `devlog.md`；