devlog-tracker 0.25.0 → 0.27.0

package/commands/lessons.md

@@ -2,11 +2,11 @@
 description: 查看 Lessons 索引，或讀某個主題的完整教訓紀錄（純讀取，不核對工作區、不等確認）。
 ---
 
-取得使用者是否有給 `<topic>`（可能沒有，代表只看索引）。記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1）。先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
+取得使用者是否有給 `<topic>`（可能沒有，代表只看索引）。記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1）。先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/hooks/scripts/lessons-read.sh" "<topic，沒有就留空>"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/core/scripts/lessons-read.sh" "<topic，沒有就留空>"
 ```
 
 沒有 `<topic>`：

package/commands/overview.md

@@ -8,11 +8,11 @@ description: 把已 keep 的具名檔（devlog.<name>.md）整合成一份跨主
 
 ## 1. 取得已 keep 的檔案清單
 
-記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1）。先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
+記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1）。先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/hooks/scripts/kept-list.sh"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑>" bash "${PLUGIN_ROOT}/core/scripts/kept-list.sh"
 ```
 
 - `NO_INDEX`：告知「目前沒有已 keep 的舊檔」，結束。

package/commands/pause.md

@@ -6,11 +6,11 @@ description: 暫停這個專案的 devlog 強制記錄機制。不會刪除任
 
 1. 跑：
    ```bash
-   先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+   先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/pause-devlog.sh"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/pause-devlog.sh"
 ```
    ```
    不要自己刪 `.enabled`。

package/commands/resume.md

@@ -2,11 +2,11 @@
 description: 讀取具名保存的 devlog，核對最後一輪 Handoff 工作區後再接續該段工作。
 ---
 
-取得使用者提供的 `<name>`；沒有名稱時先詢問。記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1：Bash 工具的工作目錄會在對話裡持續累積前面呼叫的 `cd`，用當下的 `pwd` 可能已經不是這個專案根目錄）。先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
+取得使用者提供的 `<name>`；沒有名稱時先詢問。記下你目前已經確認的專案根目錄絕對路徑（後面步驟都要用這個值，不要用 `$(pwd)` 重新推——理由同 `commands/continue.md` 步驟 1：Bash 工具的工作目錄會在對話裡持續累積前面呼叫的 `cd`，用當下的 `pwd` 可能已經不是這個專案根目錄）。先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），再跑：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/hooks/scripts/resume-devlog.sh" --name "<name>"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="<剛才記下的專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/resume-devlog.sh" --name "<name>"
 ```
 
 若回傳 `MISSING`，列出 `CANDIDATES` 讓使用者選，不要自動執行工作。

package/commands/segment-watch.md

@@ -6,11 +6,11 @@ description: 調整 Segment Watch 的沉默門檻——同一輪連續多久沒
 換算成整數秒數 `<seconds>`，跑：
 
 ```bash
-先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/segment-watch-set.sh" <seconds>
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/segment-watch-set.sh" <seconds>
 ```
 ```
 

package/commands/span.md

@@ -5,9 +5,9 @@ description: 開啟或關閉 Span Mode，讓自動續接的長任務定期記錄
 先判斷使用者要開啟或關閉：
 
 - 使用者明確要求關閉，或 `.devlog/.span-open` 已存在且沒有明確要求重新開啟：
-  先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），設 `PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"`，再跑 `CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/span-close.sh"`，
+  先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄），設 `PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"`，再跑 `DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/span-close.sh"`，
   再依 SKILL 的 span 收尾規則寫一個**新的 Round**，總結整段 span。
 - 使用者要求開啟：先把目前 Round 正常寫完，`Status` 設為 `IN_PROGRESS`，再跑
-  `CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/span-open.sh"`。
+  `DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/span-open.sh"`。
 
 不要手寫 `.span-open` JSON。腳本 exit 1 時顯示 stderr，停止操作。

package/commands/start.md

@@ -4,10 +4,10 @@ description: 啟動這個專案的 devlog 強制記錄機制。之後每一輪
 
 請執行以下步驟：
 
-1. 先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+1. 先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
-   PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-   CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/start-devlog.sh"
+   PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+   DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/start-devlog.sh"
    ```
    不要自己用手建 `.enabled` / `.checkpoint-state` / `.segment-state`。
 2. 若 stdout 有 `GITIGNORE_DEVLOG=no`：鄭重提醒——`.devlog/` 會寫入使用者原文（遮罩只覆蓋常見 token 前綴，不是通用掃密）。**強烈建議**把 `.devlog/` 加進專案 `.gitignore`。問要不要現在加。只有使用者明確說要，才在 `.gitignore` 末尾追加一行 `.devlog/`（檔案不存在就建立）。不要改其他行。若使用者拒絕，再警告一次「之後若不小心 commit，prompt／殘留密鑰可能進版控」，然後繼續步驟 3。

package/commands/status.md

@@ -4,11 +4,11 @@ description: 查看這個專案 devlog 強制記錄是否開著、span / checkpo
 
 跑：
 ```bash
-先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/status-devlog.sh"
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/status-devlog.sh"
 ```
 ```
 把 stdout 翻譯成給人看的幾行（含 `LESSONS=yes/no`：Lessons Mode 開關狀態；`LESSONS_DRIFT=<count>/<threshold>`：Lessons Mode 開著時，工作區漂移不符的累積次數／門檻）。不要改任何檔。`NOT_STARTED` 就說還沒 `/devlog-tracker:start`。

package/{hooks → core}/scripts/await-open.sh

@@ -9,7 +9,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-path.sh
 . "$SCRIPT_DIR/devlog-path.sh"
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 [ -f "$DEVLOG_DIR/.enabled" ] || { echo "NOT_ENABLED"; exit 1; }
 [ ! -e "$DEVLOG_DIR/.awaiting-reply" ] || { echo "ALREADY_OPEN"; exit 1; }
 ROUND=""

package/{hooks → core}/scripts/checkpoint-set.sh

@@ -8,7 +8,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=json-field.sh
 . "$SCRIPT_DIR/json-field.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then

package/{hooks → core}/scripts/clean-devlog.sh

@@ -13,7 +13,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # replacement for that confirmation.
 [ "${1:-}" = "--confirmed" ] || { echo "需要 --confirmed（使用者尚未確認，不要呼叫這支腳本）" >&2; exit 1; }
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_lock_acquire
 trap 'devlog_lock_release' EXIT
 MAIN="$DEVLOG_FILE"

package/{hooks → core}/scripts/close-open-round.sh

@@ -32,7 +32,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-md.sh
 . "$SCRIPT_DIR/devlog-md.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 ENABLED_FLAG="$DEVLOG_DIR/.enabled"
 ROUND_OPEN="$DEVLOG_DIR/.round-open"

package/{hooks → core}/scripts/compact-devlog.sh

@@ -7,7 +7,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 . "$SCRIPT_DIR/devlog-lock.sh"
 . "$SCRIPT_DIR/devlog-path.sh"
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_lock_acquire
 trap 'devlog_lock_release' EXIT
 MAIN="$DEVLOG_FILE"

package/{hooks → core}/scripts/enforce-devlog.sh

@@ -37,7 +37,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # 足以涵蓋 Claude Code 實際送出的 stop_hook_active 欄位形狀），兩種環境都要生效。
 INPUT="$(cat 2>/dev/null || true)"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 # 沒下過 /devlog-tracker:start，代表這個專案沒啟動強制記錄，直接放行。
 # 這是唯一的判斷依據——不猜這輪是否呼叫了某個 skill，也不解析 transcript。
 # 這個 gate 放在路徑解析之前，沒啟用時就不必付 git rev-parse 的成本；

package/{hooks → core}/scripts/keep-move.sh

@@ -33,7 +33,7 @@ NAME="$(slugify "$NAME")"
   || { echo "檔名無效" >&2; exit 1; }
 [ "${#NAME}" -le 64 ] || { echo "檔名超過 64 字元" >&2; exit 1; }
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_lock_acquire
 trap 'devlog_lock_release' EXIT
 MAIN="$DEVLOG_FILE"

package/{hooks → core}/scripts/kept-list.sh

@@ -13,7 +13,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-path.sh
 . "$SCRIPT_DIR/devlog-path.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 MAIN="$DEVLOG_FILE"
 

package/{hooks → core}/scripts/lessons-append.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Claude-invoked only (docs/design/lessons-mode.md), never wired into
-# hooks/hooks.json — same posture as keep-move.sh. Appends one free-prose
+# claude/hooks.json — same posture as keep-move.sh. Appends one free-prose
 # entry to .devlog/devlog.lessons.<topic>.md (creating it if new), then
 # rebuilds the trailing "## Lessons 索引" block in devlog.md.
 set -uo pipefail
@@ -26,7 +26,7 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 MAIN="$DEVLOG_FILE"
 

package/{hooks → core}/scripts/lessons-drift-set.sh

@@ -11,7 +11,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=json-field.sh
 . "$SCRIPT_DIR/json-field.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then

package/{hooks → core}/scripts/lessons-off.sh

@@ -4,7 +4,7 @@
 # or the "## Lessons 索引" block (docs/design/lessons-mode.md), same
 # non-destructive posture as pause-devlog.sh toward devlog.md.
 set -uo pipefail
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 if [ ! -f "$DEVLOG_DIR/.lessons-enabled" ]; then
   echo "NOT_ENABLED"

package/{hooks → core}/scripts/lessons-on.sh

@@ -4,7 +4,7 @@
 # disable」): refuses if .enabled is absent, since there is no Round/Status
 # history to detect a BLOCKED->resolved transition against.
 set -uo pipefail
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
   echo "NOT_ENABLED"

package/{hooks → core}/scripts/lessons-read.sh

@@ -14,7 +14,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-path.sh
 . "$SCRIPT_DIR/devlog-path.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 MAIN="$DEVLOG_FILE"
 

package/{hooks → core}/scripts/on-tool-failure.sh

@@ -2,7 +2,7 @@
 # PostToolUseFailure: remember user Esc so Stop can stamp without blocking.
 set -uo pipefail
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 ENABLED_FLAG="$DEVLOG_DIR/.enabled"
 [ -f "$ENABLED_FLAG" ] || exit 0

package/{hooks → core}/scripts/pause-devlog.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 set -uo pipefail
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
   echo "NOT_ENABLED"

package/core/scripts/project-dir.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Sourced helper: the single documented definition of "which project
+# directory is a hook/script operating in". Precedence:
+#   1. DEVLOG_PROJECT_DIR — neutral name, harness-agnostic
+#   2. CLAUDE_PROJECT_DIR — Claude Code's own variable, kept as a
+#      compatibility fallback so anything that already exports it
+#      (Claude Code itself, or an external script) keeps working
+#      unmodified
+#   3. "." — current directory, when neither is set
+#
+# Most core/scripts/*.sh scripts inline the equivalent expression
+# (`${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}`) directly rather than
+# sourcing this file, to keep each entry-point script a single self-
+# contained line. This file is the canonical statement of that precedence
+# and is exercised by core/scripts/tests/test-project-dir.sh; source it
+# instead of re-deriving the fallback chain in new code.
+devlog_project_dir() {
+  printf '%s\n' "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+}

package/{hooks → core}/scripts/resume-devlog.sh

@@ -20,7 +20,7 @@ NAME="$(slugify "$NAME")"
 [ -n "$NAME" ] && [ "$NAME" != "archive" ] && [ "${#NAME}" -le 64 ] \
   || { echo "INVALID_NAME" >&2; exit 1; }
 
-DEVLOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.devlog"
+DEVLOG_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}/.devlog"
 FILE="$DEVLOG_DIR/devlog.$NAME.md"
 if [ ! -f "$FILE" ]; then
   candidates=""

package/{hooks → core}/scripts/round-start.sh

@@ -24,7 +24,7 @@ HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
 . "$HOOKS_DIR/detect-pending-question.sh"
 # shellcheck source=devlog-path.sh
 . "$HOOKS_DIR/devlog-path.sh"
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 [ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
 devlog_resolve_paths "$PROJECT_DIR"
 ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"

package/{hooks → core}/scripts/run-tests.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Run every hook self-check. Usage: bash hooks/scripts/run-tests.sh
+# Run every hook self-check. Usage: bash core/scripts/run-tests.sh
 set -uo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 FAIL=0

package/{hooks → core}/scripts/segment-watch-set.sh

@@ -8,7 +8,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=json-field.sh
 . "$SCRIPT_DIR/json-field.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then

package/{hooks → core}/scripts/segment-watch.sh

@@ -13,7 +13,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-path.sh
 . "$SCRIPT_DIR/devlog-path.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 [ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
 devlog_resolve_paths "$PROJECT_DIR"
 ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"

package/{hooks → core}/scripts/session-start-devlog.sh

@@ -33,7 +33,7 @@ HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
 # shellcheck source=devlog-path.sh
 . "$HOOKS_DIR/devlog-path.sh"
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 devlog_resolve_paths "$PROJECT_DIR"
 ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"
 SPAN_FILE="$DEVLOG_DIR/.span-open"

package/{hooks → core}/scripts/span-close.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 set -uo pipefail
-DEVLOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.devlog"
+DEVLOG_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}/.devlog"
 if [ ! -e "$DEVLOG_DIR/.span-open" ]; then
   echo "NOT_OPEN"
   exit 0

package/{hooks → core}/scripts/span-open.sh

@@ -6,7 +6,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 . "$SCRIPT_DIR/devlog-md.sh"
 . "$SCRIPT_DIR/devlog-path.sh"
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 [ -f "$DEVLOG_DIR/.enabled" ] || { echo "NOT_ENABLED" >&2; exit 1; }
 [ ! -e "$DEVLOG_DIR/.span-open" ] || { echo "ALREADY_OPEN" >&2; exit 1; }
 ROUND=""

package/{hooks → core}/scripts/start-devlog.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # User-invoked: /devlog-tracker:start filesystem side.
 set -uo pipefail
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 DEVLOG_DIR="$PROJECT_DIR/.devlog"
 mkdir -p "$DEVLOG_DIR" || exit 1
 if [ ! -f "$DEVLOG_DIR/.enabled" ]; then

package/{hooks → core}/scripts/status-devlog.sh

@@ -6,7 +6,7 @@ SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 . "$SCRIPT_DIR/devlog-md.sh"
 . "$SCRIPT_DIR/devlog-path.sh"
 
-devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
 [ -d "$DEVLOG_DIR" ] || { echo "NOT_STARTED"; exit 0; }
 
 [ -f "$DEVLOG_DIR/.enabled" ] && echo "ENABLED=yes" || echo "ENABLED=no"

package/core/scripts/tests/test-cli-init-e2e.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAIL=0
+
+command -v node >/dev/null 2>&1 || { echo "SKIP: node not installed"; exit 0; }
+
+PROJECT="$TMP/project"
+mkdir -p "$PROJECT"
+
+cd "$PROJECT" || exit 1
+NODE_BIN="$(command -v node)"
+"$NODE_BIN" "$REPO_ROOT/bin/devlog-tracker.js" init --claude --codex --cursor >/dev/null 2>"$TMP/stderr" \
+  || { echo "FAIL: init exited non-zero"; cat "$TMP/stderr"; FAIL=1; }
+
+[ -f "$PROJECT/.devlog-tracker/VERSION" ] && echo "PASS: vendored VERSION exists" || { echo "FAIL: no VERSION"; FAIL=1; }
+[ -f "$PROJECT/.devlog-tracker/env.sh" ] && echo "PASS: vendored env.sh exists" || { echo "FAIL: no env.sh"; FAIL=1; }
+[ -f "$PROJECT/.claude/settings.local.json" ] && echo "PASS: .claude/settings.local.json written" || { echo "FAIL: no .claude/settings.local.json"; FAIL=1; }
+[ -f "$PROJECT/.claude/skills/devlog-start/SKILL.md" ] && echo "PASS: Claude start skill written" || { echo "FAIL: no Claude start skill"; FAIL=1; }
+[ -f "$PROJECT/CLAUDE.md" ] && grep -q 'devlog-tracker:begin' "$PROJECT/CLAUDE.md" \
+  && echo "PASS: CLAUDE.md fallback block written" || { echo "FAIL: no devlog-tracker block in CLAUDE.md"; FAIL=1; }
+[ -f "$PROJECT/.codex/hooks.json" ] && echo "PASS: .codex/hooks.json written" || { echo "FAIL: no .codex/hooks.json"; FAIL=1; }
+[ -f "$PROJECT/.agents/skills/devlog-start/SKILL.md" ] && echo "PASS: Codex start skill written" || { echo "FAIL: no Codex start skill"; FAIL=1; }
+[ -f "$PROJECT/.cursor/hooks.json" ] && echo "PASS: .cursor/hooks.json written" || { echo "FAIL: no .cursor/hooks.json"; FAIL=1; }
+
+# Controller addition 1a: Check vendored core scripts exist
+[ -f "$PROJECT/.devlog-tracker/core/scripts/enforce-devlog.sh" ] && echo "PASS: vendored core/scripts/enforce-devlog.sh exists" || { echo "FAIL: no core/scripts/enforce-devlog.sh"; FAIL=1; }
+[ -f "$PROJECT/.devlog-tracker/claude/hooks.json" ] && echo "PASS: vendored claude/hooks.json exists" || { echo "FAIL: no claude/hooks.json"; FAIL=1; }
+
+# Controller addition 1b: Check merged Claude hook commands are resolved (no placeholders)
+if grep -q '\${CLAUDE_PLUGIN_ROOT\|${DEVLOG_TRACKER_ROOT' "$PROJECT/.claude/settings.local.json"; then
+  echo "FAIL: unresolved placeholders in .claude/settings.local.json"; FAIL=1
+else
+  echo "PASS: no unresolved placeholders in .claude/settings.local.json"
+fi
+
+# Verify that Stop hook command references .devlog-tracker/core/scripts/
+STOP_CMD=$("$NODE_BIN" -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.claude/settings.local.json')).hooks.Stop[0].hooks[0].command)")
+if echo "$STOP_CMD" | grep -q '\.devlog-tracker/core/scripts/enforce-devlog\.sh'; then
+  echo "PASS: Claude Stop hook references .devlog-tracker/core/scripts/enforce-devlog.sh"
+else
+  echo "FAIL: Claude Stop hook does not reference .devlog-tracker/core/scripts/enforce-devlog.sh"; FAIL=1
+fi
+
+# re-running must not duplicate entries
+COUNT_BEFORE_CODEX=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.codex/hooks.json')).hooks.Stop.length)")
+COUNT_BEFORE_CLAUDE=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.claude/settings.local.json')).hooks.Stop.length)")
+"$NODE_BIN" "$REPO_ROOT/bin/devlog-tracker.js" init --claude --codex --cursor >/dev/null 2>"$TMP/stderr" \
+  || { echo "FAIL: second init exited non-zero"; cat "$TMP/stderr"; FAIL=1; }
+COUNT_AFTER_CODEX=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.codex/hooks.json')).hooks.Stop.length)")
+COUNT_AFTER_CLAUDE=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$PROJECT/.claude/settings.local.json')).hooks.Stop.length)")
+if [ "$COUNT_BEFORE_CODEX" = "$COUNT_AFTER_CODEX" ]; then
+  echo "PASS: re-running init does not duplicate Codex hook entries"
+else
+  echo "FAIL: Codex hook entries duplicated ($COUNT_BEFORE_CODEX -> $COUNT_AFTER_CODEX)"; FAIL=1
+fi
+if [ "$COUNT_BEFORE_CLAUDE" = "$COUNT_AFTER_CLAUDE" ]; then
+  echo "PASS: re-running init does not duplicate Claude hook entries"
+else
+  echo "FAIL: Claude hook entries duplicated ($COUNT_BEFORE_CLAUDE -> $COUNT_AFTER_CLAUDE)"; FAIL=1
+fi
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1
+fi

package/core/scripts/tests/test-project-dir.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -uo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BASH_BIN="$(command -v bash)"
+FAIL=0
+
+run_case() {
+  local desc="$1" expected="$2"
+  shift 2
+  local actual
+  actual="$(env -i PATH="$PATH" "$@" "$BASH_BIN" -c '. "'"$DIR"'/project-dir.sh"; devlog_project_dir')"
+  if [ "$actual" = "$expected" ]; then
+    echo "PASS: $desc"
+  else
+    echo "FAIL: $desc (expected [$expected], got [$actual])"
+    FAIL=1
+  fi
+}
+
+run_case "neither var set falls back to ." "."
+run_case "CLAUDE_PROJECT_DIR alone is honored" "/legacy" \
+  CLAUDE_PROJECT_DIR=/legacy
+run_case "DEVLOG_PROJECT_DIR alone is honored" "/neutral" \
+  DEVLOG_PROJECT_DIR=/neutral
+run_case "DEVLOG_PROJECT_DIR wins over CLAUDE_PROJECT_DIR" "/neutral" \
+  DEVLOG_PROJECT_DIR=/neutral CLAUDE_PROJECT_DIR=/legacy
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1
+fi

package/{hooks → core}/scripts/tests/test-session-start-devlog.sh

@@ -2,7 +2,7 @@
 # Self-check for session-start-devlog.sh, including the Span Mode
 # resume-context note. No framework — plain assert-and-exit, matching this
 # repo's existing style. Run directly:
-#   bash hooks/scripts/test-session-start-devlog.sh
+#   bash core/scripts/tests/test-session-start-devlog.sh
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -181,7 +181,7 @@ echo '{}' | bash "$SCRIPT_DIR/enforce-devlog.sh" >/dev/null 2>&1
 assert_exit "after compact skip-heal, Stop still enforces (hash equal) -> exit 2" 2 $?
 
 # --- Scenario 7: hooks.json SessionStart matcher includes fork -------------
-HOOKS_JSON="$SCRIPT_DIR/../hooks.json"
+HOOKS_JSON="$SCRIPT_DIR/../../claude/hooks.json"
 if grep -q '"matcher": "startup|resume|clear|compact|fork"' "$HOOKS_JSON"; then
   echo "PASS: SessionStart matcher includes fork"
 else

package/{hooks → core}/scripts/workspace-snapshot.sh

@@ -7,7 +7,7 @@
 #
 # Usage (sourced): workspace_snapshot "$PROJECT_DIR"
 # Usage (executed): bash workspace-snapshot.sh [dir]
-#   dir defaults to ${CLAUDE_PROJECT_DIR:-.}
+#   dir defaults to ${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}
 # Echoes 1 line (clean / non-git / detached-clean / unborn-clean) or 2 lines
 # (dirty / detached-dirty / unborn-dirty). Never fails: any git command error
 # degrades toward "非 git 工作區", matching this hook suite's fail-open design.
@@ -65,5 +65,5 @@ workspace_snapshot() {
 }
 
 if [ "${BASH_SOURCE[0]}" = "$0" ]; then
-  workspace_snapshot "${1:-${CLAUDE_PROJECT_DIR:-.}}"
+  workspace_snapshot "${1:-${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}}"
 fi

package/cursor/hooks/on-pre-tool.sh

@@ -2,10 +2,10 @@
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" && pwd)"
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 ERR_FILE="$(mktemp "${TMPDIR:-/tmp}/cursor-pre-tool.XXXXXX")" || { echo '{}'; exit 0; }
 printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/segment-watch.sh" >/dev/null 2>"$ERR_FILE"
 RESULT=$?

package/cursor/hooks/on-session-end.sh

@@ -2,10 +2,10 @@
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" && pwd)"
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/on-session-end.sh" >/dev/null 2>&1 || true
 echo '{}'
 exit 0

package/cursor/hooks/on-session-start.sh

@@ -2,10 +2,10 @@
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" && pwd)"
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 EXCERPT="$(printf '%s' '{"source":"startup"}' | bash "$PLUGIN_SCRIPTS/session-start-devlog.sh" 2>/dev/null || true)"
 if command -v jq >/dev/null 2>&1; then
   jq -n --arg c "$EXCERPT" '{additional_context:$c}'

package/cursor/hooks/on-stop.sh

@@ -2,10 +2,10 @@
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" && pwd)"
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 STATUS=""
 LOOP_COUNT=0
 if command -v jq >/dev/null 2>&1; then