devlog-tracker 0.33.4 → 0.34.0

package/core/scripts/tests/test-migrate-handoff.sh

@@ -0,0 +1,278 @@
+#!/usr/bin/env bash
+# Self-check for handoff-convert.sh + migrate-handoff.sh (docs/design/handoff-xml.md).
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=../handoff-convert.sh
+. "$SCRIPT_DIR/handoff-convert.sh"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAIL=0
+eq() {
+  if [ "$2" = "$3" ]; then echo "PASS: $1"; else printf 'FAIL: %s\n--- expected\n%s\n--- actual\n%s\n' "$1" "$2" "$3"; FAIL=1; fi
+}
+
+cat > "$TMP/in.md" <<'EOF'
+# Project
+
+## Round 1 — t1
+
+### Summary
+s1
+
+### Handoff
+#### 決策
+pick A
+
+#### 工作區
+main @ abc1234，工作樹乾淨
+#### 下一步
+run `x`
+```
+#### 下一步
+fenced, not a heading
+```
+
+### Session Handoff
+
+#### 決策
+- （無）
+
+#### 待解問題
+- q
+
+#### 失敗嘗試
+- （無）
+
+### Status
+IN_PROGRESS
+
+## Checkpoint（Round 1-1 摘要）
+### 決策
+untouched
+
+## Round 2 — t2
+
+### Handoff
+#### 自訂小節
+x
+
+### Status
+DONE
+
+## Round 3 — t3
+
+### Handoff
+<handoff>
+<state>
+already xml
+</state>
+</handoff>
+
+### Status
+DONE
+EOF
+
+cat > "$TMP/want.md" <<'EOF'
+# Project
+
+## Round 1 — t1
+
+### Summary
+s1
+
+### Handoff
+<handoff>
+<decisions>
+pick A
+</decisions>
+<workspace>
+main @ abc1234，工作樹乾淨
+</workspace>
+<next>
+run `x`
+```
+#### 下一步
+fenced, not a heading
+```
+</next>
+</handoff>
+
+### Session Handoff
+<session-handoff>
+<decisions>
+- （無）
+</decisions>
+<open-questions>
+- q
+</open-questions>
+<failed-attempts>
+- （無）
+</failed-attempts>
+</session-handoff>
+
+### Status
+IN_PROGRESS
+
+## Checkpoint（Round 1-1 摘要）
+### 決策
+untouched
+
+## Round 2 — t2
+
+### Handoff
+#### 自訂小節
+x
+
+### Status
+DONE
+
+## Round 3 — t3
+
+### Handoff
+<handoff>
+<state>
+already xml
+</state>
+</handoff>
+
+### Status
+DONE
+EOF
+
+handoff_convert_file "$TMP/in.md" "$TMP/out.md" "$TMP/report"
+eq "convert output" "$(cat "$TMP/want.md")" "$(cat "$TMP/out.md")"
+eq "report" "MIGRATED 1
+SKIP 2 不認得的小節「#### 自訂小節」" "$(cat "$TMP/report")"
+
+handoff_convert_file "$TMP/out.md" "$TMP/out2.md" "$TMP/report2"
+eq "idempotent output" "$(cat "$TMP/out.md")" "$(cat "$TMP/out2.md")"
+eq "idempotent report only repeats skip" "SKIP 2 不認得的小節「#### 自訂小節」" "$(cat "$TMP/report2")"
+
+printf '## Round 4 — t\n\n### Handoff\n#### 現況\na\n#### 決策\nb\n' > "$TMP/order.md"
+handoff_convert_file "$TMP/order.md" "$TMP/order.out" "$TMP/order.rep"
+eq "bad order untouched" "$(cat "$TMP/order.md")" "$(cat "$TMP/order.out")"
+case "$(cat "$TMP/order.rep")" in SKIP\ 4\ *) echo "PASS: bad order reported" ;; *) echo "FAIL: bad order report"; FAIL=1 ;; esac
+
+printf '## Round 5 — t\n\n### Handoff\n#### 現況\n```\nunclosed\n' > "$TMP/fence.md"
+handoff_convert_file "$TMP/fence.md" "$TMP/fence.out" "$TMP/fence.rep"
+eq "odd fence untouched" "$(cat "$TMP/fence.md")" "$(cat "$TMP/fence.out")"
+
+printf '## Session Handoff\n\n### 決策\n- a\n\n### 待解問題\n- b\n\n### 失敗嘗試\n- （無）\n' > "$TMP/h.md"
+handoff_convert_snapshot "$TMP/h.md" "$TMP/h.out"; RC=$?
+eq "snapshot rc" 0 "$RC"
+eq "snapshot xml" "<session-handoff>
+<decisions>
+- a
+</decisions>
+<open-questions>
+- b
+</open-questions>
+<failed-attempts>
+- （無）
+</failed-attempts>
+</session-handoff>" "$(cat "$TMP/h.out")"
+handoff_convert_snapshot "$TMP/h.out" "$TMP/h.out2"; RC=$?
+eq "snapshot already xml rc" 2 "$RC"
+
+# ---- migrate-handoff.sh (Task 3 appends below this line) ----
+
+P="$TMP/proj"; D="$P/.devlog"; mkdir -p "$D"
+cp "$TMP/in.md" "$D/devlog.md"
+{ printf '<!-- devlog-origin: branch=feat/x -->\n\n'; cat "$TMP/in.md"; } > "$D/devlog.feat-x.md"
+cp "$TMP/in.md" "$D/devlog.archive.md"
+cp "$TMP/in.md" "$D/devlog.mytopic.md"
+cp "$TMP/h.md" "$D/handoff.md"
+OUT="$(DEVLOG_PROJECT_DIR="$P" bash "$SCRIPT_DIR/migrate-handoff.sh")"; RC=$?
+eq "migrate rc" 0 "$RC"
+case "$OUT" in *"MIGRATED=2"*) echo "PASS: migrated count (main + branch)" ;; *) echo "FAIL: migrated count: $OUT"; FAIL=1 ;; esac
+case "$OUT" in *"SKIP devlog.md Round 2: "*) echo "PASS: skip line" ;; *) echo "FAIL: skip line: $OUT"; FAIL=1 ;; esac
+eq "main converted" "$(cat "$TMP/want.md")" "$(cat "$D/devlog.md")"
+eq "backup kept original" "$(cat "$TMP/in.md")" "$(cat "$D/devlog.md.pre-migrate")"
+grep -q '^<handoff>$' "$D/devlog.feat-x.md" && echo "PASS: branch file converted" || { echo "FAIL: branch file"; FAIL=1; }
+eq "archive untouched" "$(cat "$TMP/in.md")" "$(cat "$D/devlog.archive.md")"
+eq "keep file untouched" "$(cat "$TMP/in.md")" "$(cat "$D/devlog.mytopic.md")"
+grep -q '^<session-handoff>$' "$D/handoff.md" && echo "PASS: handoff.md converted" || { echo "FAIL: handoff.md"; FAIL=1; }
+OUT2="$(DEVLOG_PROJECT_DIR="$P" bash "$SCRIPT_DIR/migrate-handoff.sh")"
+case "$OUT2" in *"MIGRATED=0"*) echo "PASS: second run migrates nothing" ;; *) echo "FAIL: second run: $OUT2"; FAIL=1 ;; esac
+[ ! -d "$D/.lock" ] && echo "PASS: lock released" || { echo "FAIL: lock left behind"; FAIL=1; }
+OUT3="$(DEVLOG_PROJECT_DIR="$TMP/nope" bash "$SCRIPT_DIR/migrate-handoff.sh")"; RC=$?
+eq "no devlog rc" 1 "$RC"
+eq "no devlog out" "NO_DEVLOG" "$OUT3"
+
+# Coverage gap 1: a duplicated `#### 現況` inside one Handoff leaves that
+# round byte-for-byte untouched and is reported as SKIP mentioning 重複.
+printf '## Round 10 — dup\n\n### Handoff\n#### 現況\na\n#### 現況\nb\n\n### Status\nIN_PROGRESS\n' > "$TMP/dup.md"
+handoff_convert_file "$TMP/dup.md" "$TMP/dup.out" "$TMP/dup.rep"
+eq "duplicate section untouched" "$(cat "$TMP/dup.md")" "$(cat "$TMP/dup.out")"
+case "$(cat "$TMP/dup.rep")" in SKIP\ 10\ *重複*) echo "PASS: duplicate section reported" ;; *) echo "FAIL: duplicate section report: $(cat "$TMP/dup.rep")"; FAIL=1 ;; esac
+
+# Coverage gap 2: Handoff is valid legacy but Session Handoff has an unknown
+# `#### 其他` subsection — the WHOLE round (including the convertible
+# Handoff) is left byte-for-byte untouched and reported SKIP.
+printf '## Round 11 — mixed\n\n### Handoff\n#### 決策\npick\n\n### Session Handoff\n#### 其他\nx\n\n### Status\nDONE\n' > "$TMP/mixed.md"
+handoff_convert_file "$TMP/mixed.md" "$TMP/mixed.out" "$TMP/mixed.rep"
+eq "unknown session-handoff subsection leaves whole round untouched" "$(cat "$TMP/mixed.md")" "$(cat "$TMP/mixed.out")"
+case "$(cat "$TMP/mixed.rep")" in SKIP\ 11\ *) echo "PASS: mixed round skipped" ;; *) echo "FAIL: mixed round report: $(cat "$TMP/mixed.rep")"; FAIL=1 ;; esac
+
+# Odd fence (a): the open round's User Input pasted an unbalanced fence (3
+# ``` lines). Stop's NOFENCE gate still sees the legacy Handoff, so migrate
+# must report it SKIP instead of silently finding nothing.
+P2="$TMP/proj-odd"; D2="$P2/.devlog"; mkdir -p "$D2"
+printf '## Round 7 — t\n\n### User Input\npaste:\n```\ncode\n```\n```\nunclosed\n\n### Summary\ns\n\n### Reply\nr\n\n### Handoff\n#### 現況\na\n\n#### 下一步\nb\n' > "$D2/.round-current.md"
+cp "$D2/.round-current.md" "$TMP/odd-a.orig"
+OUT4="$(DEVLOG_PROJECT_DIR="$P2" bash "$SCRIPT_DIR/migrate-handoff.sh")"
+case "$OUT4" in *"SKIP .round-current.md Round 7: fence 沒有成對"*) echo "PASS: odd fence in open round reported SKIP" ;; *) echo "FAIL: odd fence open round: $OUT4"; FAIL=1 ;; esac
+case "$OUT4" in *"SKIPPED=1"*) echo "PASS: odd fence open round counted" ;; *) echo "FAIL: odd fence open round count: $OUT4"; FAIL=1 ;; esac
+eq "odd fence open round untouched" "$(cat "$TMP/odd-a.orig")" "$(cat "$D2/.round-current.md")"
+
+# Odd fence (b): an unbalanced fence in an old round's Summary must not
+# swallow every later `## Round` heading.
+printf '## Round 1 — old\n\n### Summary\n```\nunclosed\n\n### Handoff\n#### 現況\na\n\n### Status\nDONE\n\n## Round 2 — new\n\n### Handoff\n#### 現況\nb\n\n### Status\nDONE\n' > "$TMP/odd-b.md"
+handoff_convert_file "$TMP/odd-b.md" "$TMP/odd-b.out" "$TMP/odd-b.rep"
+eq "odd fence (b) report" "SKIP 1 fence 沒有成對
+MIGRATED 2" "$(cat "$TMP/odd-b.rep")"
+eq "odd fence (b) output" "## Round 1 — old
+
+### Summary
+\`\`\`
+unclosed
+
+### Handoff
+#### 現況
+a
+
+### Status
+DONE
+
+## Round 2 — new
+
+### Handoff
+<handoff>
+<state>
+b
+</state>
+</handoff>
+
+### Status
+DONE" "$(cat "$TMP/odd-b.out")"
+
+# migrate_snapshot_file rc=1: an unrecognised handoff.md is reported, untouched.
+P3="$TMP/proj-snap"; D3="$P3/.devlog"; mkdir -p "$D3"
+printf 'random notes\n' > "$D3/handoff.md"
+OUT5="$(DEVLOG_PROJECT_DIR="$P3" bash "$SCRIPT_DIR/migrate-handoff.sh")"
+case "$OUT5" in *"SKIP handoff.md: "*) echo "PASS: unknown snapshot reported" ;; *) echo "FAIL: unknown snapshot: $OUT5"; FAIL=1 ;; esac
+eq "unknown snapshot untouched" "random notes" "$(cat "$D3/handoff.md")"
+
+# Branch file from before the devlog-origin marker existed: still migrated
+# when that branch is checked out (resolved via devlog_resolve_paths).
+P4="$TMP/proj-git"; D4="$P4/.devlog"; mkdir -p "$D4"
+git -C "$P4" init -q
+git -C "$P4" -c user.email=t@t -c user.name=t commit -q --allow-empty -m init
+git -C "$P4" checkout -q -b feat/y
+cp "$TMP/in.md" "$D4/devlog.feat-y.md"
+OUT6="$(DEVLOG_PROJECT_DIR="$P4" bash "$SCRIPT_DIR/migrate-handoff.sh")"
+eq "markerless current branch file converted" "$(cat "$TMP/want.md")" "$(cat "$D4/devlog.feat-y.md")"
+case "$OUT6" in *"MIGRATED=1"*) echo "PASS: markerless branch file converted once" ;; *) echo "FAIL: markerless branch count: $OUT6"; FAIL=1 ;; esac
+
+[ "$FAIL" -eq 0 ] || exit 1
+echo "All migrate-handoff checks passed."

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

@@ -6,6 +6,8 @@ set -uo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 # shellcheck source=../json-field.sh
 . "$SCRIPT_DIR/json-field.sh"
+# shellcheck source=lib/xml-fixture.sh
+. "$SCRIPT_DIR/tests/lib/xml-fixture.sh"
 TMP_ROOT="$(mktemp -d)"
 trap 'rm -rf "$TMP_ROOT"' EXIT
 
@@ -664,6 +666,16 @@ else
 fi
 rm -f "$DEVLOG_DIR/.checkpoint-state"
 
+# Codex invokes project skills through $devlog-<name> in the prompt.
+for ADMIN_PROMPT in '$devlog-status' '$devlog-report --json'; do
+  printf '{"prompt":"%s"}' "$ADMIN_PROMPT" | bash "$SCRIPT_DIR/round-start.sh"
+  assert_file_absent "Codex admin $ADMIN_PROMPT: no .round-current.md" "$DEVLOG_DIR/.round-current.md"
+done
+printf '{"prompt":"%s"}' '$devlog-continue' | bash "$SCRIPT_DIR/round-start.sh"
+CUR_BODY="$(cat "$DEVLOG_DIR/.round-current.md" 2>/dev/null || echo '')"
+assert_contains "Codex continue still opens a Round" "## Round 1 —" "$CUR_BODY"
+rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
+
 # --- 19b: report / timeline / keep-all are admin commands too -------------
 for ADMIN_CMD in report timeline keep-all; do
   rm -f "$DEVLOG_DIR/.round-current.md" "$DEVLOG_DIR/.round-open"
@@ -772,7 +784,7 @@ do x
 IN_PROGRESS
 EOF
 OUT="$(printf '%s' '{"prompt":"keep going"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
-assert_contains "mismatch stdout names 工作區" "#### 工作區" "$OUT"
+assert_contains "mismatch stdout names 工作區（<workspace>）" "工作區（\`<workspace>\`" "$OUT"
 assert_contains "mismatch stdout has 宣稱" "宣稱：" "$OUT"
 assert_contains "mismatch stdout has 實際" "實際：" "$OUT"
 assert_contains "mismatch stdout has live snapshot" "$LIVE" "$OUT"
@@ -780,6 +792,47 @@ assert_contains "mismatch stdout has live snapshot" "$LIVE" "$OUT"
 MARKER="$(cat "$WS/.devlog/.workspace-mismatch")"
 [ "$MARKER" = "$LIVE" ] && echo "PASS: marker is live snapshot" || { echo "FAIL: marker [$MARKER]"; FAIL=1; }
 
+# --- same MISMATCH injection, Handoff in XML form (docs/design/handoff-xml.md) --
+WS2="$TMP_ROOT/ws-xml"
+mkdir -p "$WS2/.devlog"
+touch "$WS2/.devlog/.enabled"
+git -C "$WS2" init -q -b main
+git -C "$WS2" config user.email test@example.com
+git -C "$WS2" config user.name test
+echo hello > "$WS2/a.txt"
+git -C "$WS2" add a.txt
+git -C "$WS2" commit -q -m init
+cat > "$WS2/.devlog/devlog.md" <<EOF
+## Round 1 — 2026-09-11T00:00:00+08:00
+
+### Summary
+s
+
+### Reply
+fixture reply.
+
+### Handoff
+#### 工作區
+main @ deadbeef，工作樹乾淨
+#### 現況
+going
+#### 完成條件
+`bash hooks/scripts/tests/test-enforce-devlog.sh` 相關情境通過。
+#### 下一步
+do x
+
+### Status
+IN_PROGRESS
+EOF
+xml_fixture "$WS2/.devlog/devlog.md"
+export CLAUDE_PROJECT_DIR="$WS2"
+XML_OUT="$(printf '%s' '{"prompt":"keep going"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "XML Handoff mismatch stdout names 工作區（<workspace>）" "工作區（\`<workspace>\`" "$XML_OUT"
+assert_contains "XML Handoff mismatch stdout has 宣稱" "宣稱：" "$XML_OUT"
+assert_contains "XML Handoff mismatch stdout has 實際" "實際：" "$XML_OUT"
+[ -f "$WS2/.devlog/.workspace-mismatch" ] && echo "PASS: XML Handoff mismatch writes marker" || { echo "FAIL: XML Handoff mismatch: no marker"; FAIL=1; }
+export CLAUDE_PROJECT_DIR="$WS"
+
 # --- lessons drift counter: mechanical nudge on repeated mismatch --------
 rm -f "$WS/.devlog/.round-open" "$WS/.devlog/.round-current.md" "$WS/.devlog/.workspace-mismatch"
 touch "$WS/.devlog/.lessons-enabled"

package/core/scripts/tests/test-session-start-devlog.sh

@@ -539,6 +539,51 @@ else
   FAIL=1
 fi
 
+# --- XML Handoff + XML handoff.md: both injected --------------------------
+rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/handoff.md"
+cat > "$DEVLOG_DIR/devlog.md" <<'EOF'
+## Round 1 — 2026-09-22T00:00:00+08:00
+
+### Summary
+summary 1
+
+### Reply
+fixture reply.
+
+### Handoff
+<handoff>
+<state>
+xml state line
+</state>
+<done-when>
+tests pass
+</done-when>
+<next>
+edit xml-next-target.sh
+</next>
+</handoff>
+
+### Status
+IN_PROGRESS
+EOF
+cat > "$DEVLOG_DIR/handoff.md" <<'EOF'
+<session-handoff>
+<decisions>
+- keep route A
+</decisions>
+<open-questions>
+- xml open Q
+</open-questions>
+<failed-attempts>
+- （無）
+</failed-attempts>
+</session-handoff>
+EOF
+OUTPUT="$(echo '{"source":"startup"}' | bash "$SCRIPT_DIR/session-start-devlog.sh" 2>&1)"
+assert_contains "XML handoff <next> content injected" "edit xml-next-target.sh" "$OUTPUT"
+assert_contains "XML handoff.md block injected" "<session-handoff>" "$OUTPUT"
+assert_contains "XML handoff.md body injected" "xml open Q" "$OUTPUT"
+
 # --- no handoff.md: excerpt only -----------------------------------------
 rm -f "$DEVLOG_DIR/handoff.md"
 OUTPUT="$(echo '{"source":"startup"}' | bash "$SCRIPT_DIR/session-start-devlog.sh" 2>&1)"

package/core/scripts/tests/test-workspace-snapshot.sh

@@ -83,6 +83,38 @@ CLI_UNBORN="$(bash "$SCRIPT_DIR/workspace-snapshot.sh" "$UNBORN")"
 FUNC_UNBORN="$(workspace_snapshot "$UNBORN")"
 assert_eq "cli matches function (unborn dirty)" "$FUNC_UNBORN" "$CLI_UNBORN"
 
+# --- .devlog/ changes are ignored (same rule as files-snapshot.sh) ----------
+# The devlog is rewritten every round, so counting it would make every
+# snapshot dirty and every Handoff 工作區 drift on its own write.
+DL="$TMP_ROOT/devlog-ignored"
+mkdir -p "$DL"
+git -C "$DL" init -q -b main
+git -C "$DL" config user.email test@example.com
+git -C "$DL" config user.name test
+echo hello > "$DL/a.txt"
+mkdir -p "$DL/.devlog"
+echo tracked > "$DL/.devlog/devlog.md"
+git -C "$DL" add a.txt .devlog/devlog.md
+git -C "$DL" commit -q -m init
+DL_HASH="$(git -C "$DL" rev-parse --short HEAD)"
+echo more >> "$DL/.devlog/devlog.md"
+echo round > "$DL/.devlog/.round-current.md"
+OUT="$(workspace_snapshot "$DL")"
+assert_eq ".devlog-only changes count as clean" "main @ ${DL_HASH}，工作樹乾淨" "$OUT"
+
+echo change >> "$DL/a.txt"
+OUT="$(workspace_snapshot "$DL")"
+EXPECTED="main @ ${DL_HASH}
+未提交：a.txt"
+assert_eq ".devlog changes omitted from 未提交" "$EXPECTED" "$OUT"
+
+DL_UNBORN="$TMP_ROOT/devlog-unborn"
+mkdir -p "$DL_UNBORN/.devlog"
+git -C "$DL_UNBORN" init -q -b main
+echo x > "$DL_UNBORN/.devlog/devlog.md"
+OUT="$(workspace_snapshot "$DL_UNBORN")"
+assert_eq "unborn with untracked .devlog/ only is clean" "main @ (尚無 commit)，工作樹乾淨" "$OUT"
+
 # --- executable entry matches the sourced function --------------------------
 CLI_NONGIT="$(bash "$SCRIPT_DIR/workspace-snapshot.sh" "$NONGIT")"
 assert_eq "cli non-git directory" "非 git 工作區" "$CLI_NONGIT"

package/core/scripts/timeline-render.js

@@ -136,6 +136,30 @@ function renderMarkdown(md) {
   return out.join('\n');
 }
 
+const HANDOFF_FIELDS = {
+  decisions: '決策', files: '檔案', workspace: '工作區', state: '現況',
+  'done-when': '完成條件', next: '下一步', 'open-questions': '待解問題', 'failed-attempts': '失敗嘗試',
+};
+const HANDOFF_BLOCK_TAG = /^\s*<\/?(handoff|session-handoff)>\s*$/;
+const HANDOFF_TAG = /^\s*<(\/?)([a-z-]+)>\s*$/;
+
+// Line-based XML Handoff (docs/design/handoff-xml.md) → `#### 中文名`
+// headings so renderMarkdown shows it like the legacy form. Legacy text
+// passes through unchanged.
+function handoffToMarkdown(text) {
+  const out = [];
+  for (const line of String(text).split('\n')) {
+    if (HANDOFF_BLOCK_TAG.test(line)) continue;
+    const m = HANDOFF_TAG.exec(line);
+    if (m && HANDOFF_FIELDS[m[2]]) {
+      if (!m[1]) out.push(`#### ${HANDOFF_FIELDS[m[2]]}`);
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join('\n').trim();
+}
+
 function statusOf(s) {
   return STATUSES.includes(s) ? s : 'NONE';
 }
@@ -145,7 +169,7 @@ function roundCard(r) {
   const parts = [];
   if (r.input) parts.push(`<h4>User Input</h4><pre><code>${escapeHtml(r.input)}</code></pre>`);
   if (r.reply) parts.push(`<h4>Reply</h4>${renderMarkdown(r.reply)}`);
-  if (r.handoff) parts.push(`<h4>Handoff</h4>${renderMarkdown(r.handoff)}`);
+  if (r.handoff) parts.push(`<h4>Handoff</h4>${renderMarkdown(handoffToMarkdown(r.handoff))}`);
   for (const seg of r.segments || []) parts.push(`<div class="seg">${renderMarkdown('#### ' + seg)}</div>`);
   const details = parts.length ? `<details><summary>詳細</summary>${parts.join('\n')}</details>` : '';
   return `<article class="card round" data-status="${st}" data-branch="${escapeHtml(r.branch)}">
@@ -244,4 +268,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { render, renderMarkdown, inline, escapeHtml, safeHref, timelineItems };
+module.exports = { render, renderMarkdown, inline, escapeHtml, safeHref, timelineItems, handoffToMarkdown, HANDOFF_FIELDS };

package/core/scripts/timeline-render.test.js

@@ -3,7 +3,7 @@ const test = require('node:test');
 const assert = require('node:assert/strict');
 const path = require('path');
 const { spawnSync } = require('child_process');
-const { render, renderMarkdown, safeHref, escapeHtml } = require('./timeline-render');
+const { render, renderMarkdown, safeHref, escapeHtml, handoffToMarkdown, HANDOFF_FIELDS } = require('./timeline-render');
 
 function round(extra) {
   return { branch: 'main', file: 'devlog.md', line: 1, n: 1, at: '2026-09-01T10:00:00+0800',
@@ -90,6 +90,28 @@ test('render: empty data shows an empty-state message', () => {
   assert.ok(render({ started: true, rounds: [], checkpoint_blocks: [] }).includes('沒有 Round 可顯示'));
 });
 
+test('handoffToMarkdown turns XML fields into headings and drops block tags', () => {
+  const md = handoffToMarkdown('<handoff>\n<state>\nok\n</state>\n<next>\nrun `x`\n</next>\n</handoff>');
+  assert.equal(md, '#### 現況\nok\n#### 下一步\nrun `x`');
+});
+
+test('handoffToMarkdown leaves legacy Handoff untouched', () => {
+  assert.equal(handoffToMarkdown('#### 現況\nok'), '#### 現況\nok');
+});
+
+test('XML Handoff renders as headings, never as raw tags', () => {
+  const html = render({ rounds: [round({ handoff: '<handoff>\n<state>\nok\n</state>\n</handoff>' })], checkpoint_blocks: [] });
+  assert.ok(!html.includes('&lt;state&gt;'));
+  assert.ok(html.includes('現況'));
+});
+
+test('HANDOFF_FIELDS matches handoff-fields.sh', () => {
+  const script = path.join(__dirname, 'handoff-fields.sh');
+  const r = spawnSync('bash', ['-c', `. "${script}"; for k in $HANDOFF_KEYS $SESSION_HANDOFF_KEYS; do printf '%s=%s\\n' "$k" "$(handoff_key_heading "$k")"; done`], { encoding: 'utf8' });
+  const fromBash = Object.fromEntries(r.stdout.trim().split('\n').map((l) => l.split('=')));
+  assert.deepEqual(fromBash, HANDOFF_FIELDS);
+});
+
 test('CLI: stdin JSON -> stdout HTML; invalid JSON -> exit 1', () => {
   const script = path.join(__dirname, 'timeline-render.js');
   const ok = spawnSync(process.execPath, [script], { input: JSON.stringify({ rounds: [round({})] }), encoding: 'utf8' });

package/core/scripts/workspace-snapshot.sh

@@ -15,6 +15,19 @@
 # Known limitation: a dirty file path containing a space is not exactly
 # reversible from `git status --short`'s last-field extraction below — same
 # limitation the hand-written 工作區 convention already has.
+#
+# Paths under .devlog/ are left out (same rule as files-snapshot.sh): the
+# devlog is rewritten every round, so counting it would make the snapshot
+# dirty by its own write. A tree whose only changes are under .devlog/
+# reports as clean.
+
+# `git status --short` minus .devlog/ entries. Lines are "<XY> <path>".
+_ws_status_short() {
+  git -C "$1" status --short 2>/dev/null \
+    | awk '{ p = substr($0, 4) } p == ".devlog" || p ~ /^\.devlog\// { next } { print }' \
+    || true
+}
+
 workspace_snapshot() {
   local dir="${1:-.}"
   if ! git -C "$dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
@@ -37,7 +50,7 @@ workspace_snapshot() {
       printf '非 git 工作區\n'
       return 0
     fi
-    status_out="$(git -C "$dir" status --short 2>/dev/null || echo '')"
+    status_out="$(_ws_status_short "$dir")"
     if [ -z "$status_out" ]; then
       printf '%s @ (尚無 commit)，工作樹乾淨\n' "$unborn_branch"
     else
@@ -51,7 +64,7 @@ workspace_snapshot() {
   else
     label="$branch"
   fi
-  status_out="$(git -C "$dir" status --short 2>/dev/null || echo '')"
+  status_out="$(_ws_status_short "$dir")"
   if [ -z "$status_out" ]; then
     if [ "$label" = "HEAD detached" ]; then
       printf '%s @ %s\n' "$label" "$hash"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlog-tracker",
-  "version": "0.33.4",
+  "version": "0.34.0",
   "description": "npx installer for devlog-tracker's Claude Code, Cursor and Codex adapters.",
   "bin": {
     "devlog-tracker": "bin/devlog-tracker.js"
@@ -21,8 +21,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test cli/*.test.js cli/platforms/*.test.js scripts/*.test.js core/scripts/*.test.js",
-    "version": "node scripts/sync-version.js && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json README.md README.zh-TW.md"
+    "test": "node scripts/sync-codex-plugin.js --check && node --test cli/*.test.js cli/platforms/*.test.js scripts/*.test.js core/scripts/*.test.js",
+    "version": "node scripts/sync-version.js && git add .claude-plugin/plugin.json .codex-plugin/plugin.json .claude-plugin/marketplace.json README.md README.zh-TW.md"
   },
   "license": "Apache-2.0",
   "author": {