.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-log",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "工作日誌（LOG_{HASH} wiki 頁）、技能使用統計與教訓紀錄（LEARN_{HASH} wiki 頁）",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-log",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "工作日誌（LOG_{HASH} wiki 頁）、技能使用統計與教訓紀錄（LEARN_{HASH} wiki 頁）",
   "skills": "./skills",
   "jsc": {

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-log",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "工作日誌（LOG_{HASH} wiki 頁）、技能使用統計與教訓紀錄（LEARN_{HASH} wiki 頁）",
   "skills": "./skills/",
   "jsc": {

references/behaviors.md

@@ -37,7 +37,7 @@
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | implement 或 maintain 階段每結束一項任務就寫一筆。一項任務是一個工作包、一輪 PR 意見修正，或一次獨立的修正提交。下一項任務開始前就要寫完。規劃階段的筆記不走這支 |
-| 關鍵步驟 | 全程由 sub agent 收集與寫入、平行取得十項事實（`git remote get-url origin` 的 repo、`git branch --show-current` 的分支、PLAN 頁絕對連結、ANALYZE 頁工作包絕對連結、`session-timer.sh report` 的花費時間、`token-usage.sh` 的各 CLI Token、任務狀態、細節與產出、困難與解法、PR 目標分支）、平行解出 LOG wiki repo（只供內容頁）與完整 40 碼大寫的 `{HASH}`、跑 `tools/worklog-target.sh` 取得頁名與本週五日期、用 `templates/log-entry.md` 填出單筆條目檔、跑 `tools/worklog-pending.sh merge` 併入待寫內容、讀 `PAGE` 後依退出碼分支（0 追加在頁尾、4 才建頁、7 與 8 停止且不建頁）、寫入前把 `MERGED` 裡的每個連結交給 `link-check.sh` 驗證（0 才寫入、1 有 DEAD 就不寫並回報那幾筆、2 沒給網址、3 未設 `GITEA_HOST`、7 金鑰被拒就停下）、同一輪用 `wiki-repo CONTENTS` 解出目錄頁存取庫、取 `wiki-url` 的絕對網址並寫成 `[{頁名}]({絕對網址})`、同樣先過 `link-check.sh` 才跑 `wiki-contents.sh upsert LOG 2 {HASH}` 更新 `LOG_CONTENTS`（鍵取第 2 欄的裸 HASH，不取第 1 欄那個帶主機名的連結）並依 0、1、2、3、4、7、8 各自分流、最後依成敗跑 `worklog-pending.sh commit` 或 `abort` |
+| 關鍵步驟 | 全程由 sub agent 收集與寫入、平行取得十項事實（`git remote get-url origin` 的 repo、`git branch --show-current` 的分支、PLAN 頁絕對連結、ANALYZE 頁工作包絕對連結、`session-timer.sh report` 的花費時間、`token-usage.sh` 的各 CLI Token、任務狀態、細節與產出、困難與解法、PR 目標分支）、平行解出 LOG wiki repo（只供內容頁）與完整 40 碼大寫的 `{HASH}`、跑 `tools/worklog-target.sh` 取得頁名與本週五日期、用 `templates/log-entry.md` 填出單筆條目檔、跑 `tools/worklog-pending.sh merge` 併入待寫內容（同時收編同一個 `{HASH}` 的「`H` 加前 7 碼」舊目錄）、跑 `tools/worklog-pending.sh orphans` 掃出現行規則定址不到的暫存目錄（0 就安靜帶過，4 就把每一列回報給使用者並繼續本輪）、讀 `PAGE` 後依退出碼分支（0 追加在頁尾、4 才建頁、7 與 8 停止且不建頁）、寫入前把 `MERGED` 裡的每個連結交給 `link-check.sh` 驗證（0 才寫入、1 有 DEAD 就不寫並回報那幾筆、2 沒給網址、3 未設 `GITEA_HOST`、7 金鑰被拒就停下）、同一輪用 `wiki-repo CONTENTS` 解出目錄頁存取庫、取 `wiki-url` 的絕對網址並寫成 `[{頁名}]({絕對網址})`、同樣先過 `link-check.sh` 才跑 `wiki-contents.sh upsert LOG 2 {HASH}` 更新 `LOG_CONTENTS`（鍵取第 2 欄的裸 HASH，不取第 1 欄那個帶主機名的連結）並依 0、1、2、3、4、7、8 各自分流、最後依成敗跑 `worklog-pending.sh commit` 或 `abort` |
 | 外部呼叫 | `jsc-hooks/hooks/session-timer.sh report`、`tools/token-usage.sh`、`tools/worklog-target.sh`、`tools/worklog-pending.sh`、`jsc-gitea/tools/gitea.sh wiki-repo`（LOG 與 CONTENTS）與 `wiki-url`、`jsc-gitea/tools/link-check.sh`（寫入前驗證連結）、`jsc-gitea/tools/wiki-contents.sh upsert`（目錄頁那一列）、`jsc-gitea/tools/hash-id`、`jsc-gitea:wiki`、`jsc-ask:ask`、`git remote get-url origin`、`git branch --show-current`、`templates/log-entry.md`、`templates/log-contents.md` |
-| 完成條件 | 兩次寫入前 `link-check.sh` 都回 0，`MERGED` 的每一筆條目都在 `PAGE` 上，原有條目逐字不動，`wiki-contents.sh upsert` 回 0 且 `CONTENTS` 該列帶著本週五日期、其他列不動，`worklog-pending.sh` 的 `commit` 或 `abort` 其中一個跑過並回報退出碼。`link-check.sh` 回 1 或 `upsert` 回非 0 就照該碼回報，並把步驟七當成失敗處理，讓待寫內容留著 |
+| 完成條件 | 兩次寫入前 `link-check.sh` 都回 0，`MERGED` 的每一筆條目都在 `PAGE` 上，原有條目逐字不動，`wiki-contents.sh upsert` 回 0 且 `CONTENTS` 該列帶著本週五日期、其他列不動，`worklog-pending.sh` 的 `commit` 或 `abort` 其中一個跑過並回報退出碼，`orphans` 也跑過且回 0 或已把孤兒清單回報出去。`link-check.sh` 回 1 或 `upsert` 回非 0 就照該碼回報，並把步驟七當成失敗處理，讓待寫內容留著 |
-| 可驗證跡象 | LOG 存取庫的 `LOG_{HASH}` 頁尾多一筆條目，條目裡的計畫名稱、工作包編號、PR 目標分支三欄都是 `[{文字}]({絕對網址})`；CONTENTS 存取庫的 `LOG_CONTENTS` 該列的「條目數」與「最後更新」換新，且「日誌頁」欄是 `[{頁名}]({絕對網址})`，頁面上沒有 `[[...]]` 這種同 wiki 寫法，「HASH」欄是不帶連結的裸 HASH。連結驗證不過就兩頁都沒有新內容，待寫檔原樣保留。重跑同一頁只換掉那一列，不會多出第二列。`$JSC_HOME/worklog-pending/{HASH}` 底下的待寫檔在 `commit` 後清空，`abort` 後原樣保留；該目錄名是 40 碼大寫十六進位，或尚未遷移的舊暫存那種 8 碼大寫十六進位、`H` 加 7 碼大寫十六進位。本機留下填好的條目檔 |
+| 可驗證跡象 | LOG 存取庫的 `LOG_{HASH}` 頁尾多一筆條目，條目裡的計畫名稱、工作包編號、PR 目標分支三欄都是 `[{文字}]({絕對網址})`；CONTENTS 存取庫的 `LOG_CONTENTS` 該列的「條目數」與「最後更新」換新，且「日誌頁」欄是 `[{頁名}]({絕對網址})`，頁面上沒有 `[[...]]` 這種同 wiki 寫法，「HASH」欄是不帶連結的裸 HASH。連結驗證不過就兩頁都沒有新內容，待寫檔原樣保留。重跑同一頁只換掉那一列，不會多出第二列。`$JSC_HOME/worklog-pending/{HASH}` 底下的待寫檔在 `commit` 後清空，`abort` 後原樣保留；該目錄名是 40 碼大寫十六進位，或尚未遷移的舊暫存那種 8 碼大寫十六進位、`H` 加 7 碼大寫十六進位；推得出對映的舊目錄會連同新目錄一起被清掉。暫存區留下非 40 碼的目錄時，該輪的回報上看得到 `orphans` 印出的那幾列。本機留下填好的條目檔 |

skills/worklog/SKILL.md

@@ -49,7 +49,7 @@ The `{HASH}` in every page name above is computed with `jsc-gitea/tools/hash-id`
    Done when the hosting `{owner}/{repo}` and the full 40-character uppercase `{HASH}` are both known.
 2. Run `tools/worklog-target.sh "{HASH}" all` and `tools/worklog-target.sh friday` in parallel. `all` prints `PAGE=LOG_{HASH}` and `CONTENTS=LOG_CONTENTS`; `friday` prints the Friday of the current work week as `yyyy-MM-dd`, which drives the page content and the row dates. Exit 2 means the arguments were rejected, so fix them and rerun. Exit 4 from `friday` means this machine's `date` does no date arithmetic: stop and report it, because a hand-picked Friday is exactly what goes wrong across a month or year boundary. Done when both page names and that Friday date are known.
 3. Fill `templates/log-entry.md` with the ten facts of this one task and save it to a file. Done when that file holds exactly one entry.
-4. Run `tools/worklog-pending.sh merge {HASH} {entry file}`. It prints `MERGED=` (pending content in time order, then this task's entry), `CLAIM=` (the pending files it took) and `PENDING=` (how many). Pending content was written by an earlier stage that ended without a work log, so it belongs in **this** write.
+4. Run `tools/worklog-pending.sh merge {HASH} {entry file}`. It prints `MERGED=` (pending content in time order, then this task's entry), `CLAIM=` (the pending files it took) and `PENDING=` (how many). Pending content was written by an earlier stage that ended without a work log, so it belongs in **this** write. `merge` also picks up the legacy `H` + first 7 characters directory of the same `{HASH}`, so pending content stored under the previous hash rule still reaches the wiki.
 
    | Exit | Do |
    | --- | --- |
@@ -58,6 +58,11 @@ The `{HASH}` in every page name above is computed with `jsc-gitea/tools/hash-id`
    | 2 | The `{HASH}` is none of the three accepted shapes — 40 uppercase hex characters, 8 uppercase hex characters, or `H` plus 7 uppercase hex characters — or the entry file argument is missing. The last two are old pending directories left by the previous hash rule and are accepted only until the migration finishes. Pass the value `hash-id` printed, unshortened, and rerun from step 1 |
 
    Done when `MERGED` and `CLAIM` are known.
+4.5. Run `tools/worklog-pending.sh orphans`. It takes no `{HASH}` and scans the whole pending area for directories that are not 40 uppercase hex characters. Exit 0 means there are none, so carry on silently. Exit 4 prints one `{directory}<TAB>{file count}<TAB>{path}` line per orphan: report every line to the user and carry on with this run — an orphan belongs to some other repository, so it never blocks this one.
+
+   Why this runs at all: a directory the current rule cannot address holds work-log entries that no run will ever write, and nothing else reports them. "No pending content" and "pending content stranded under a name this rule cannot address" both reach the caller as success, so without this scan the entries stay invisible until somebody reads the directory by hand. Step 4 already adopts the one legacy shape that can be derived from `{HASH}`; this scan covers every shape that cannot.
+
+   Done when the scan exited 0, or its lines were reported to the user.
 5. Read `PAGE` from the LOG wiki repo of step 1 via `jsc-gitea:wiki`, and branch on the exit code the underlying `gitea.sh wiki-get` returned. **Only exit 4 means the page is not there yet.** Reading any other code as "it does not exist" builds a fresh page from `templates/log-entry.md` and appends to that — which replaces the whole existing work log with this one entry, and no entry on it can be recovered from the wiki afterwards.
 
    | Exit | Do |

tools/worklog-pending.sh

@@ -29,9 +29,22 @@
 # 合併檔: $JSC_HOME/worklog-pending/.merge/{hash}-{UTC 時間}-{pid}.md
 # 併入清單: 同名換副檔名 .claim，一行一個被併走的暫存檔路徑
 #
-# 結束碼: 0=成功 1=讀寫失敗 2=用法錯誤 3=該 hash 沒有暫存內容
+# 結束碼: 0=成功 1=讀寫失敗 2=用法錯誤 3=該 hash 沒有暫存內容 4=orphans 掃到孤兒目錄
 # merge 沒有暫存內容時仍然 exit 0：合併檔至少有本次條目，呼叫端不必分兩條路走。
 #
+# 舊目錄自動收編:
+#   拿 40 碼來查時，一併收「H 加前 7 碼」那個舊目錄。雜湊規則從 8 碼改成 40 碼那一刻，
+#   還沒寫進 wiki 的暫存會留在舊名底下；不收的話它查不到，而且沒有人會說查不到——
+#   「沒有暫存」與「暫存卡在舊名底下」對呼叫端長得一模一樣，兩種都是成功。日誌就這樣消失。
+#   只認「舊名等於 H 加新名前 7 碼」這一種對映，推導唯一，不會收到別的專案。
+#   list、cat、merge 讀兩個目錄，clear 清兩個，commit 也放行舊目錄的路徑——
+#   放行漏掉的話，已經寫進 wiki 的暫存清不掉，下一輪會整批重複寫一次。
+#
+# orphans 子命令（不吃 hash）:
+#   掃暫存區根目錄，印出每一個不是 40 碼的目錄：{目錄名}<TAB>{檔數}<TAB>{路徑}。
+#   沒有就 exit 0，有就 exit 4。上面那條自動收編只救得到推得出對映的舊目錄，
+#   推不出來的要有人看到才處理得掉，所以另外給一支掃描。
+#
 # 陷阱:
 #   - clear 與 commit 都只在日誌確實寫進 wiki 之後才呼叫。先清再寫，寫失敗就兩邊都沒有。
 #   - commit 只認 merge 產出的併入清單，且清單上的路徑必須落在該 hash 的暫存目錄底下，
@@ -99,6 +112,11 @@ valid_hash() {
   exit 2
 }
 
+claim_reject() { # 併入清單上出現不該清的路徑，一律當用法錯誤擋下
+  echo "[jsc][工作日誌暫存][ERR]：併入清單裡的「$1」不在這個 hash 的暫存目錄底下，不清。" >&2
+  exit 2
+}
+
 valid_claim() { # 併入清單只認 merge 產出的那一份，擋掉拿別處的清單來刪檔
   case "$1" in
     "$MERGE_DIR"/*.claim) ;;
@@ -109,10 +127,55 @@ valid_claim() { # 併入清單只認 merge 產出的那一份，擋掉拿別處
 
 cmd="${1:-}"; [ -n "$cmd" ] || usage
 shift || true
+
+# orphans 不吃 hash：它要掃的就是「算不出對應 hash」的那些目錄。
+if [ "$cmd" = orphans ]; then
+  [ -d "$ROOT" ] || exit 0
+  found=0
+  for d in "$ROOT"/*/; do
+    [ -d "$d" ] || continue
+    name=$(basename "$d")
+    [ "$name" = .merge ] && continue
+    case "$name" in
+      ????????????????????????????????????????) continue ;;
+    esac
+    n=0
+    for f in "$d"*.md; do [ -f "$f" ] && n=$((n + 1)); done
+    printf '%s\t%s\t%s\n' "$name" "$n" "$d"
+    found=1
+  done
+  [ "$found" -eq 0 ] && exit 0
+  echo "[jsc][工作日誌暫存][ERR]：上列暫存目錄不是現行的 40 碼頁名，現行程式查不到它們，裡面的日誌永遠寫不進 wiki。舊名是新名的「H 加前 7 碼」，把目錄改成完整 40 碼即可。" >&2
+  exit 4
+fi
+
 hash="${1:-}"; [ -n "$hash" ] || usage
 valid_hash "$hash"
 dir="$ROOT/$hash"
 
+# 舊規則的同一個專案會落在「H 加前 7 碼」那個目錄。拿 40 碼來查時一併收，否則規則改版
+# 那一刻還沒寫進 wiki 的暫存就成為孤兒——查不到、也沒有人會說查不到，日誌就這樣消失。
+# 只認這一種對映：舊名完全等於 H 加新名前 7 碼，推導唯一，不會收錯別的專案。
+legacy_dir=""
+case "$hash" in
+  ????????????????????????????????????????)
+    _cand="$ROOT/H$(printf '%s' "$hash" | cut -c1-7)"
+    [ -d "$_cand" ] && legacy_dir="$_cand" ;;
+esac
+
+# 兩個目錄的暫存檔一起排。檔名開頭是 UTC 時間戳，字典序等同時間序，所以跨目錄排完
+# 仍然是「舊的在前」。分開接的話，舊目錄那幾筆會整批插到新目錄最舊那一筆前面。
+pending_files() {
+  for _d in "$dir" "$legacy_dir"; do
+    [ -n "$_d" ] && [ -d "$_d" ] || continue
+    for _f in "$_d"/*.md; do
+      [ -f "$_f" ] || continue
+      # 先印檔名再印全路徑，排完再把檔名那一欄切掉：排序的鍵是檔名，不是目錄。
+      printf '%s\t%s\n' "$(basename "$_f")" "$_f"
+    done
+  done | sort | cut -f2-
+}
+
 case "$cmd" in
   add)
     src="${2:-}"
@@ -125,30 +188,26 @@ case "$cmd" in
     printf '%s\n' "$target"
     ;;
   list)
-    [ -d "$dir" ] || exit 3
     found=0
-    for f in "$dir"/*.md; do
+    pending_files | while IFS= read -r f; do printf '%s\n' "$f"; done
-      [ -f "$f" ] || continue
+    pending_files | grep -q . && found=1
-      printf '%s\n' "$f"
-      found=1
-    done
     [ "$found" -eq 1 ] || exit 3
     ;;
   cat)
-    [ -d "$dir" ] || exit 3
     found=0
-    for f in "$dir"/*.md; do
+    pending_files | while IFS= read -r f; do cat "$f"; printf '\n'; done
-      [ -f "$f" ] || continue
+    pending_files | grep -q . && found=1
-      cat "$f"
-      printf '\n'
-      found=1
-    done
     [ "$found" -eq 1 ] || exit 3
     ;;
   clear)
-    [ -d "$dir" ] || exit 3
+    cleared=0
-    rm -rf "$dir" || { echo "[jsc][工作日誌暫存][ERR]：清不掉「$dir」。" >&2; exit 1; }
+    for d in "$dir" "$legacy_dir"; do
-    printf '已清除暫存：%s\n' "$dir"
+      [ -n "$d" ] && [ -d "$d" ] || continue
+      rm -rf "$d" || { echo "[jsc][工作日誌暫存][ERR]：清不掉「$d」。" >&2; exit 1; }
+      printf '已清除暫存：%s\n' "$d"
+      cleared=1
+    done
+    [ "$cleared" -eq 1 ] || exit 3
     ;;
   merge)
     # 合成這一次要寫進 wiki 的內容：暫存的在前（依時間），本次條目在後。
@@ -163,15 +222,13 @@ case "$cmd" in
     : > "$merged" || { echo "[jsc][工作日誌暫存][ERR]：寫不進「$merged」。" >&2; exit 1; }
     : > "$claim" || { echo "[jsc][工作日誌暫存][ERR]：寫不進「$claim」。" >&2; exit 1; }
     taken=0
-    if [ -d "$dir" ]; then
+    pending_files > "$claim" || { echo "[jsc][工作日誌暫存][ERR]：列不出暫存檔。" >&2; exit 1; }
-      for f in "$dir"/*.md; do
+    while IFS= read -r f; do
-        [ -f "$f" ] || continue
+      [ -n "$f" ] || continue
       cat "$f" >> "$merged" || { echo "[jsc][工作日誌暫存][ERR]：讀不到「$f」。" >&2; exit 1; }
       printf '\n' >> "$merged"
-        printf '%s\n' "$f" >> "$claim"
       taken=$((taken + 1))
-      done
+    done < "$claim"
-    fi
     cat "$src" >> "$merged" || { echo "[jsc][工作日誌暫存][ERR]：併不進本次條目「$src」。" >&2; exit 1; }
     printf '\n' >> "$merged"
     printf 'MERGED=%s\n' "$merged"
@@ -187,15 +244,20 @@ case "$cmd" in
     cleared=0
     while IFS= read -r f; do
       [ -n "$f" ] || continue
+      # 舊目錄也要放行：merge 會把「H 加前 7 碼」那個舊目錄的暫存一起併走，
+      # 這裡不認的話，寫進 wiki 的內容清不掉，下一輪會整批重複寫一次。
       case "$f" in
         "$dir"/*) ;;
-        *) echo "[jsc][工作日誌暫存][ERR]：併入清單裡的「$f」不在「$dir」底下，不清。" >&2; exit 2 ;;
+        *) if [ -n "$legacy_dir" ]; then
+             case "$f" in "$legacy_dir"/*) ;; *) claim_reject "$f" ;; esac
+           else claim_reject "$f"; fi ;;
       esac
       [ -e "$f" ] || continue
       rm -f "$f" || { echo "[jsc][工作日誌暫存][ERR]：清不掉「$f」。" >&2; exit 1; }
       cleared=$((cleared + 1))
     done < "$claim"
     rmdir "$dir" 2>/dev/null || true
+    [ -n "$legacy_dir" ] && rmdir "$legacy_dir" 2>/dev/null || true
     rm -f "$claim" "${claim%.claim}.md"
     printf '已清除暫存 %s 個檔案（wiki 寫入成功後才做）。\n' "$cleared"
     ;;