devlog-tracker 0.33.5 → 1.0.0

package/core/scripts/handoff-fields.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# Sourced helper: field access for ### Handoff／### Session Handoff in both
+# the legacy `#### 決策` form and the line-based XML form. Tag name == key.
+# Not real XML — see docs/design/handoff-xml.md before changing anything.
+
+# shellcheck disable=SC2034 # consumed by sourcing scripts
+HANDOFF_KEYS="decisions files workspace state done-when next"
+# shellcheck disable=SC2034
+SESSION_HANDOFF_KEYS="decisions open-questions failed-attempts"
+
+handoff_key_heading() {
+  case "$1" in
+    decisions) printf '決策' ;;
+    files) printf '檔案' ;;
+    workspace) printf '工作區' ;;
+    state) printf '現況' ;;
+    done-when) printf '完成條件' ;;
+    next) printf '下一步' ;;
+    open-questions) printf '待解問題' ;;
+    failed-attempts) printf '失敗嘗試' ;;
+    *) return 1 ;;
+  esac
+}
+
+# 1 when $1 has an odd number of ``` markers (unclosed fence): callers then
+# stop tracking fences, same fail-open as devlog-md.sh／enforce-devlog.sh.
+_hf_nofence() {
+  local n
+  n="$(printf '%s\n' "$1" | grep -c '^[ \t]*```' 2>/dev/null || true)"
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  if [ $((n % 2)) -eq 1 ]; then echo 1; else echo 0; fi
+}
+
+handoff_section_of() {
+  local blob="$1" name="$2" nofence
+  nofence="$(_hf_nofence "$blob")"
+  printf '%s\n' "$blob" | awk -v h="### $name" -v nofence="$nofence" '
+    /^[ \t]*```/ { if (!nofence) fence = !fence; if (grab) print; next }
+    !fence && !grab { t = $0; sub(/[ \t]+$/, "", t); if (t == h) { grab = 1; next } }
+    grab && !fence && /^###? / { exit }
+    grab { print }
+  '
+}
+
+handoff_format() {
+  local first nofence
+  first="$(printf '%s\n' "$1" | awk 'NF { sub(/^[ \t]+/, ""); sub(/[ \t]+$/, ""); print; exit }')"
+  case "$first" in
+    '<handoff>'|'<session-handoff>') echo xml; return 0 ;;
+  esac
+  nofence="$(_hf_nofence "$1")"
+  if printf '%s\n' "$1" | awk -v nofence="$nofence" '
+    /^[ \t]*```/ { if (!nofence) fence = !fence; next }
+    !fence && /^#### / { found = 1; exit }
+    END { exit(found ? 0 : 1) }
+  '; then
+    echo md
+  else
+    echo none
+  fi
+}
+
+handoff_field() {
+  local body="$1" key="$2" heading nofence
+  case "$(handoff_format "$body")" in
+    xml)
+      printf '%s\n' "$body" | awk -v tag="$key" '
+        { t = $0; sub(/^[ \t]+/, "", t); sub(/[ \t]+$/, "", t) }
+        !grab && t == "<" tag ">" { grab = 1; next }
+        grab && t == "</" tag ">" { exit }
+        grab { print }
+      '
+      ;;
+    md)
+      heading="$(handoff_key_heading "$key")" || return 0
+      nofence="$(_hf_nofence "$body")"
+      printf '%s\n' "$body" | awk -v h="$heading" -v nofence="$nofence" '
+        /^[ \t]*```/ { if (!nofence) fence = !fence; if (grab) print; next }
+        !fence && /^#### / {
+          if (grab) exit
+          name = $0; sub(/^#### [ \t]*/, "", name); sub(/[ \t]+$/, "", name)
+          if (name == h) grab = 1
+          next
+        }
+        grab && !fence && /^###? / { exit }
+        grab { print }
+      '
+      ;;
+  esac
+}
+
+handoff_xml_check() {
+  local body="$1" kind="$2" keys
+  case "$kind" in
+    handoff) keys="$HANDOFF_KEYS" ;;
+    session-handoff) keys="$SESSION_HANDOFF_KEYS" ;;
+    *) return 1 ;;
+  esac
+  printf '%s\n' "$body" | awk -v kind="$kind" -v keys="$keys" '
+    function fail(msg) { print msg; failed = 1; exit 1 }
+    function order_str(   i, s) { s = k[1]; for (i = 2; i <= n; i++) s = s " → " k[i]; return s }
+    BEGIN { n = split(keys, k, " "); for (i = 1; i <= n; i++) ord[k[i]] = i; st = "before"; cur = ""; last = 0 }
+    {
+      t = $0; sub(/^[ \t]+/, "", t); sub(/[ \t]+$/, "", t)
+      if (st == "before") {
+        if (t == "") next
+        if (t == "<" kind ">") { st = "in"; next }
+        fail("第一個非空行必須是 <" kind ">（標籤自己一行），目前是：" t)
+      }
+      if (st == "after") {
+        if (t == "") next
+        fail("</" kind "> 外面不能有其他內容：" t)
+      }
+      if (cur != "") {
+        if (t == "</" cur ">") {
+          if (!body) fail("<" cur "> 是空的；沒有內容就整個標籤省略")
+          cur = ""; next
+        }
+        if (match(t, /^<\/?[a-z][a-z_-]*>/)) {
+          tag = substr(t, 1, RLENGTH); name = tag; gsub(/[<\/>]/, "", name)
+          if ((name in ord) || name == kind) {
+            if (t == tag) fail("<" cur "> 還沒用 </" cur "> 關閉就出現了 " tag)
+            fail(tag " 要自己一行：內容寫在下一行，結尾標籤另起一行。看不懂這一行：" t)
+          }
+        }
+        if (t != "") body = 1
+        next
+      }
+      if (t == "") next
+      if (t == "</" kind ">") { st = "after"; next }
+      if (t ~ /^<[a-z][a-z_-]*>$/) {
+        name = substr(t, 2, length(t) - 2)
+        if (!(name in ord)) fail("不認得的標籤 <" name ">；<" kind "> 裡可用的標籤：" keys)
+        if (seen[name]) fail("<" name "> 出現超過一次，請合併成一個")
+        if (ord[name] < last) fail("標籤順序錯了（應該是 " order_str() "）：<" name "> 寫在 <" prev "> 後面")
+        seen[name] = 1; last = ord[name]; prev = name; cur = name; body = 0
+        next
+      }
+      if (t ~ /^<\/[a-z][a-z_-]*>$/) fail(t " 前面沒有對應的開頭標籤")
+      if (match(t, /^<\/?[a-z][a-z_-]*>/)) {
+        tag = substr(t, 1, RLENGTH); name = tag; gsub(/[<\/>]/, "", name)
+        if (name in ord) fail(tag " 要自己一行：內容寫在下一行，結尾標籤另起一行。看不懂這一行：" t)
+        fail("不認得的標籤 " tag "；<" kind "> 裡可用的標籤：" keys)
+      }
+      fail("<" kind "> 裡的內容要放在欄位標籤裡面，看不懂這一行：" t)
+    }
+    END {
+      if (failed) exit 1
+      if (st == "before") { print "缺少 <" kind "> 區塊"; exit 1 }
+      if (cur != "") { print "<" cur "> 還沒用 </" cur "> 關閉"; exit 1 }
+      if (st == "in") { print "缺少結尾的 </" kind ">"; exit 1 }
+      if (kind == "session-handoff") {
+        for (i = 1; i <= n; i++) if (!seen[k[i]]) { print "<session-handoff> 必須依序有 " keys "（沒有就寫 - （無）），缺 <" k[i] ">"; exit 1 }
+      }
+    }
+  '
+}
+
+handoff_xml_template() {
+  case "$1" in
+    handoff)
+      cat <<'EOF'
+### Handoff
+<handoff>
+<decisions>
+影響後續方向的選擇與理由（沒做選擇就整個標籤省略）
+</decisions>
+<files>
+尚未 commit：
+修改：path/to/file
+</files>
+<workspace>
+main @ a1b2c3d，工作樹乾淨
+</workspace>
+<state>
+任務做到哪、卡在哪
+</state>
+<done-when>
+可觀察的做完判準（IN_PROGRESS／BLOCKED 必寫）
+</done-when>
+<next>
+下一輪第一件具體要做的事（IN_PROGRESS／BLOCKED 必寫）
+</next>
+</handoff>
+EOF
+      ;;
+    session-handoff)
+      cat <<'EOF'
+### Session Handoff
+<session-handoff>
+<decisions>
+- 仍影響後續方向的選擇；沒有就寫 - （無）
+</decisions>
+<open-questions>
+- 下一 session 最該先看的卡點；沒有就寫 - （無）
+</open-questions>
+<failed-attempts>
+- 試過但放棄的做法；沒有就寫 - （無）
+</failed-attempts>
+</session-handoff>
+EOF
+      ;;
+  esac
+}
+
+handoff_legacy_message() {
+  local migrate="$1" project="$2"
+  printf '%s\n' "Handoff 還是舊的「#### 小節」格式，這一輪要改用 XML 標籤。先跑下面的指令，把 devlog 裡的舊格式 Handoff 一次轉好，再結束這一輪一次："
+  printf '\n'
+  printf 'DEVLOG_PROJECT_DIR="%s" bash "%s"\n' "$project" "$migrate"
+  printf '\n'
+  printf '%s\n' "輸出的 SKIP 若列出這一輪，就照下面的模板手動改寫（標籤自己一行、沒有的欄位整個省略）："
+  printf '\n'
+  handoff_xml_template handoff
+  printf '\n'
+  handoff_xml_template session-handoff
+  printf '\n'
+  printf '%s\n' "給使用者：如果 agent 每一輪都還是寫舊格式，代表專案裡的 devlog-tracker skill／指令文件是舊版。請重跑 \`npx devlog-tracker init\`（Claude Code plugin 使用者改成更新 plugin），再執行 \`/devlog-tracker:start\`。"
+}

package/core/scripts/handoff-file.sh

@@ -1,98 +1,29 @@
 #!/usr/bin/env bash
-# Sourced helper: validate / extract / write / clear Session Handoff file.
-# See docs/design/session-handoff-file.md.
+# Sourced helper: write / clear the Session Handoff file. Content is the
+# round's <session-handoff> block verbatim (docs/design/handoff-xml.md,
+# docs/design/session-handoff-file.md).
 
-# Odd ``` count → treat as no fence (same fail-open as enforce-devlog.sh).
-_handoff_nofence_flag() {
-  local blob="$1" n
-  n="$(printf '%s\n' "$blob" | grep -c '^[ \t]*```' 2>/dev/null || echo 0)"
-  case "$n" in ''|*[!0-9]*) n=0 ;; esac
-  if [ $((n % 2)) -eq 1 ]; then
-    echo 1
-  else
-    echo 0
-  fi
-}
-
-# Returns 0 if $1 (a Round blob) has ### Session Handoff with #### 決策 /
-# #### 待解問題 / #### 失敗嘗試 in that order, each with a non-empty body.
-handoff_session_section_ok() {
-  local blob="$1" nofence
-  nofence="$(_handoff_nofence_flag "$blob")"
-  printf '%s\n' "$blob" | awk -v nofence="$nofence" '
-    BEGIN { ok = 0 }
-    /^[ \t]*```/ { if (!nofence) fence = !fence; next }
-    fence { next }
-    /^### Session Handoff[ \t]*$/ { in_sh = 1; next }
-    in_sh && /^### / { exit }
-    in_sh && /^## / { exit }
-    in_sh && /^#### / {
-      name = $0
-      sub(/^#### [ \t]*/, "", name)
-      sub(/[ \t]+$/, "", name)
-      if (name == "決策" || name == "待解問題" || name == "失敗嘗試") {
-        if (expecting_body) { exit }
-        if (name == "決策") {
-          if (seen_decision || seen_open || seen_failed) exit
-          seen_decision = 1
-          expecting_body = 1
-        } else if (name == "待解問題") {
-          if (!seen_decision || seen_open || seen_failed) exit
-          seen_open = 1
-          expecting_body = 1
-        } else {
-          if (!seen_decision || !seen_open || seen_failed) exit
-          seen_failed = 1
-          expecting_body = 1
-        }
-      }
-      next
-    }
-    in_sh && expecting_body {
-      if ($0 ~ /[^[:space:]]/) {
-        expecting_body = 0
-        if (seen_decision && seen_open && seen_failed) ok = 1
-      }
-      next
-    }
-    END { exit(ok && seen_decision && seen_open && seen_failed && !expecting_body ? 0 : 1) }
-  '
-}
+_HANDOFF_FILE_DIR="$(cd "${BASH_SOURCE[0]%/*}" && pwd)"
+# shellcheck source=handoff-fields.sh
+. "$_HANDOFF_FILE_DIR/handoff-fields.sh"
 
-# Print independent-file markdown from Round blob $1. Exit 1 if invalid.
-handoff_extract_file_body() {
-  local blob="$1" nofence
-  handoff_session_section_ok "$blob" || return 1
-  nofence="$(_handoff_nofence_flag "$blob")"
-  printf '%s\n' "$blob" | awk -v nofence="$nofence" '
-    BEGIN { print "## Session Handoff"; print "" }
-    /^[ \t]*```/ { if (!nofence) fence = !fence; next }
-    fence { next }
-    /^### Session Handoff[ \t]*$/ { in_sh = 1; next }
-    in_sh && /^### / { exit }
-    in_sh && /^## / { exit }
-    in_sh && /^#### / {
-      name = $0
-      sub(/^#### [ \t]*/, "", name)
-      sub(/[ \t]+$/, "", name)
-      if (name == "決策" || name == "待解問題" || name == "失敗嘗試") {
-        if (printing) print ""
-        print "### " name
-        printing = 1
-        grab = 1
-        next
-      }
-      grab = 0
-      next
-    }
-    in_sh && grab { print }
-  '
+# Prints the trimmed <session-handoff> block of Round blob $1; exit 1 when
+# absent or invalid.
+handoff_session_block() {
+  local body
+  body="$(handoff_section_of "$1" 'Session Handoff' | awk '
+    { l[NR] = $0 } NF && !s { s = NR } NF { e = NR }
+    END { for (i = s; s && i <= e; i++) print l[i] }
+  ')"
+  [ -n "$body" ] || return 1
+  [ "$(handoff_format "$body")" = xml ] || return 1
+  handoff_xml_check "$body" session-handoff >/dev/null || return 1
+  printf '%s\n' "$body"
 }
 
-# Atomic write of extracted body to $1 from Round blob $2.
 handoff_write() {
   local path="$1" blob="$2" dir tmp body
-  body="$(handoff_extract_file_body "$blob")" || return 1
+  body="$(handoff_session_block "$blob")" || return 1
   dir="$(dirname "$path")"
   mkdir -p "$dir" 2>/dev/null || true
   tmp="$(mktemp "$dir/.handoff.XXXXXX")" || return 1

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SubagentStart hook（Claude Code）：Lessons Mode 開著時，把「可以自己呼叫
+# SubagentStart hook（Claude Code／Codex）：Lessons Mode 開著時，把「可以自己呼叫
 # lessons-append.sh」的說明注入 sub agent／Workflow agent 的 context
 # （docs/design/lessons-mode.md「sub agent／workflow 情境」）。
 # sub agent 的 Bash 裡沒有 CLAUDE_PROJECT_DIR，isolation: "worktree" 時 cwd

package/core/scripts/migrate-handoff.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Converts legacy `#### ` Handoff／Session Handoff in the live devlog files to
+# XML (docs/design/handoff-xml.md「Migrate」). Run by the agent when Stop
+# blocks on a legacy Handoff, or by /devlog-tracker:migrate.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=handoff-convert.sh
+. "$SCRIPT_DIR/handoff-convert.sh"
+# shellcheck source=devlog-lock.sh
+. "$SCRIPT_DIR/devlog-lock.sh"
+
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+DEVLOG_DIR="$PROJECT_DIR/.devlog"
+[ -d "$DEVLOG_DIR" ] || { echo NO_DEVLOG; exit 1; }
+
+# The current branch's files, even when they predate the devlog-origin
+# marker. Resolved before taking the lock: devlog_resolve_paths may take it
+# itself. Outside git this just yields devlog.md／handoff.md.
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+devlog_resolve_paths "$PROJECT_DIR" 2>/dev/null || true
+CUR_DEVLOG="${DEVLOG_FILE:-}"
+CUR_HANDOFF="${HANDOFF_FILE:-}"
+DEVLOG_DIR="$PROJECT_DIR/.devlog"
+
+devlog_lock_acquire
+trap 'devlog_lock_release' EXIT
+if [ -n "${LOCK_CONTENDED_BY:-}" ]; then echo "LOCKED ${LOCK_CONTENDED_BY}"; exit 1; fi
+
+MIGRATED=0
+SKIPPED=0
+LINES=""
+add_line() { LINES="${LINES}${1}"$'\n'; }
+
+migrate_round_file() {
+  local f="$1" name rep n
+  name="${f##*/}"
+  rep="$(mktemp "$DEVLOG_DIR/.migrate.XXXXXX")" || return 0
+  handoff_convert_file "$f" "$f.migrate-tmp" "$rep" || { rm -f "$f.migrate-tmp" "$rep"; return 0; }
+  n="$(grep -c '^MIGRATED ' "$rep" || true)"
+  while read -r tag round reason; do
+    [ "$tag" = SKIP ] || continue
+    SKIPPED=$((SKIPPED + 1))
+    add_line "SKIP $name Round $round: $reason"
+  done < "$rep"
+  rm -f "$rep"
+  if [ "${n:-0}" -gt 0 ]; then
+    cp "$f" "$f.pre-migrate" && mv "$f.migrate-tmp" "$f" || { rm -f "$f.migrate-tmp"; return 0; }
+    MIGRATED=$((MIGRATED + n))
+    add_line "BACKUP=$f.pre-migrate"
+  else
+    rm -f "$f.migrate-tmp"
+  fi
+}
+
+migrate_snapshot_file() {
+  local f="$1" rc
+  handoff_convert_snapshot "$f" "$f.migrate-tmp"; rc=$?
+  if [ "$rc" -eq 0 ]; then
+    cp "$f" "$f.pre-migrate" && mv "$f.migrate-tmp" "$f" || { rm -f "$f.migrate-tmp"; return 0; }
+    add_line "BACKUP=$f.pre-migrate"
+  else
+    rm -f "$f.migrate-tmp"
+    [ "$rc" -eq 1 ] && add_line "SKIP ${f##*/}: 看不懂的 handoff 快照格式，保留原樣"
+  fi
+}
+
+# Each file at most once (the current branch file may also carry a marker).
+DONE_FILES=$'\n'
+first_visit() {
+  case "$DONE_FILES" in *$'\n'"$1"$'\n'*) return 1 ;; esac
+  DONE_FILES="${DONE_FILES}${1}"$'\n'
+}
+
+for f in "$DEVLOG_DIR/.round-current.md" "$DEVLOG_DIR/devlog.md" "$CUR_DEVLOG"; do
+  [ -n "$f" ] && [ -s "$f" ] && first_visit "$f" && migrate_round_file "$f"
+done
+for f in "$DEVLOG_DIR"/devlog.*.md; do
+  [ -s "$f" ] || continue
+  head -n 1 "$f" | grep -q '^<!-- devlog-origin: ' || continue
+  first_visit "$f" && migrate_round_file "$f"
+done
+for f in "$DEVLOG_DIR"/handoff.md "$CUR_HANDOFF" "$DEVLOG_DIR"/handoff.*.md; do
+  [ -n "$f" ] && [ -s "$f" ] && first_visit "$f" && migrate_snapshot_file "$f"
+done
+
+echo "MIGRATED=$MIGRATED"
+echo "SKIPPED=$SKIPPED"
+printf '%s' "$LINES"
+exit 0

package/core/scripts/round-start.sh

@@ -94,8 +94,19 @@ case "$PROMPT" in
     CMD_NAME="${CMD_NAME#/}"
     ;;
 esac
+# Codex exposes project commands as skills. An explicit $devlog-name mention
+# is the first token of the submitted prompt, rather than a command-name tag.
+if [ -z "$CMD_NAME" ]; then
+  case "$PROMPT" in
+    \$devlog-*)
+      CMD_NAME="${PROMPT%%[[:space:]]*}"
+      CMD_NAME="${CMD_NAME#\$devlog-}"
+      CMD_NAME="devlog-tracker:$CMD_NAME"
+      ;;
+  esac
+fi
 case "$CMD_NAME" in
-  devlog-tracker:checkpoint|devlog-tracker:clean|devlog-tracker:compact|devlog-tracker:keep|devlog-tracker:keep-all|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)
+  devlog-tracker:checkpoint|devlog-tracker:clean|devlog-tracker:compact|devlog-tracker:keep|devlog-tracker:keep-all|devlog-tracker:lessons|devlog-tracker:lessons-drift|devlog-tracker:lessons-off|devlog-tracker:lessons-on|devlog-tracker:migrate|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
@@ -165,7 +176,7 @@ if [ "$SPAN_SKIP" -eq 0 ] && [ "$TASK_NOTIF" -eq 0 ] && [ -f "$DEVLOG_FILE" ]; t
     LIVE_WS="$(workspace_snapshot "$PROJECT_DIR")"
     if [ -n "$LIVE_WS" ]; then
       printf '%s\n' "$LIVE_WS" > "$MISMATCH_FILE" 2>/dev/null || true
-      printf '%s\n' "上一輪 Handoff「#### 工作區」跟目前 git 不符。先在這一輪追加 ### 段落，寫宣稱 vs 實際（實際用下面「實際」逐字內容），再依實際工作樹行動，不要照上一輪「現況／下一步」的字面。"
+      printf '%s\n' "上一輪 Handoff 的工作區（\`<workspace>\`；舊格式是 \`#### 工作區\`）跟目前 git 不符。先在這一輪追加 ### 段落，寫宣稱 vs 實際（實際用下面「實際」逐字內容），再依實際工作樹行動，不要照上一輪「現況／下一步」的字面。"
       printf '\n宣稱：\n%s\n\n實際：\n%s\n' "$CLAIMED_WS" "$LIVE_WS"
 
       if [ -f "$DEVLOG_DIR/.lessons-enabled" ]; then

package/core/scripts/segment-watch.sh

@@ -103,7 +103,7 @@ if [ -f "$MISMATCH_FILE" ]; then
       *"$mark_flat"*) rm -f "$MISMATCH_FILE" 2>/dev/null || true ;;
       *)
         if ! is_devlog_tool_allowed "$TOOL_NAME" "$FILE_PATH" "$COMMAND"; then
-          echo "上一輪「#### 工作區」跟目前 git 不符。請先 Read .devlog/.round-current.md，再用 Edit／StrReplace 在這一輪追加 ### 段落，把下面「實際」逐字貼進段落（宣稱 vs 實際）。寫完再呼叫其他工具。不要照上一輪 Handoff「現況／下一步」的字面行動。（唯讀的 git status／diff／log／show／rev-parse 仍可執行，方便自行核對。）" >&2
+          echo "上一輪 Handoff 的工作區（\`<workspace>\`；舊格式是 \`#### 工作區\`）跟目前 git 不符。請先 Read .devlog/.round-current.md，再用 Edit／StrReplace 在這一輪追加 ### 段落，把下面「實際」逐字貼進段落（宣稱 vs 實際）。寫完再呼叫其他工具。不要照上一輪 Handoff「現況／下一步」的字面行動。（唯讀的 git status／diff／log／show／rev-parse 仍可執行，方便自行核對。）" >&2
           echo "" >&2
           echo "實際：" >&2
           printf '%s\n' "$LIVE_MARK" >&2

package/core/scripts/tests/lib/xml-fixture.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Test helper: convert a legacy-format fixture file to XML in place.
+_XML_FIXTURE_DIR="$(cd "${BASH_SOURCE[0]%/*}/../.." && pwd)"
+# shellcheck source=../../handoff-convert.sh
+. "$_XML_FIXTURE_DIR/handoff-convert.sh"
+xml_fixture() {
+  local f="$1"
+  handoff_convert_file "$f" "$f.xml" "$f.xmlrep" && mv "$f.xml" "$f"
+  rm -f "$f.xmlrep"
+}

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

@@ -88,7 +88,8 @@ BODY="$(cat "$DEVLOG_DIR/devlog.md")"
 assert_contains "status INTERRUPTED" $'### Status\nINTERRUPTED' "$BODY"
 assert_contains "reason line" "StopFailure:server_error" "$BODY"
 assert_contains "summary stub (not recovered)" "devlog.md 沒有留下任何後續處理紀錄就結束了" "$BODY"
-assert_contains "handoff stub heading" "#### 現況" "$BODY"
+assert_contains "handoff stub open" "<handoff>" "$BODY"
+assert_contains "handoff stub block" "<state>" "$BODY"
 assert_contains "handoff stub body (not recovered)" "這一輪沒有留下任何處理紀錄" "$BODY"
 assert_contains "user input kept" "hello" "$BODY"
 

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

@@ -352,6 +352,27 @@ EXPECTED_BODY='feat/foo @ abc1234
 未提交：a.txt'
 assert_eq "workspace body two lines" "$EXPECTED_BODY" "$WS_BODY"
 
+cat > "$TMP_ROOT/xmlws.md" <<'EOF'
+## Round 1 — t
+
+### Handoff
+<handoff>
+<workspace>
+main @ abc1234
+未提交：a.txt
+</workspace>
+<next>
+x
+</next>
+</handoff>
+
+### Status
+IN_PROGRESS
+EOF
+XMLWS_END="$(wc -l < "$TMP_ROOT/xmlws.md" | tr -d ' ')"
+assert_eq "workspace body from XML" "main @ abc1234
+未提交：a.txt" "$(devlog_round_workspace_body "$TMP_ROOT/xmlws.md" 1 "$XMLWS_END")"
+
 cat > "$TMP_ROOT/segments.md" <<'EOF'
 ## Round 1 — 2026-09-11T00:00:00+08:00
 

package/core/scripts/tests/test-enforce-devlog-files.sh

@@ -1,11 +1,13 @@
 #!/usr/bin/env bash
-# Self-check for enforce-devlog.sh's #### 檔案 machine-verify (Phase 4,
+# Self-check for enforce-devlog.sh's <files> machine-verify (Phase 4,
 # docs/design/files-verify.md). Separate file from test-enforce-devlog.sh
 # and test-enforce-devlog-workspace.sh; still auto-discovered by
 # run-tests.sh's tests/test-*.sh glob.
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=lib/xml-fixture.sh
+. "$SCRIPT_DIR/tests/lib/xml-fixture.sh"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
@@ -96,6 +98,7 @@ write_round() {
     echo "### Status"
     echo "$status"
   } > "$DEVLOG_DIR/.round-current.md"
+  xml_fixture "$DEVLOG_DIR/.round-current.md"
 }
 
 ws_clean() {