Memory Lint

memory-lint — Memory 品質健檢

Phase 1  唯讀掃描 ──► 報告（預設只做這段，不動任何檔案）
                        │  user 逐條拍板要修哪些
Phase 2  執行修正 ──► commit（開工前先記回退點）
                        │  改完全部提交 = 凍結
Phase 3  獨立複驗 ──► 過 → 收工　／　不過 → 回退到 Phase 2 前

🔴 收到 lint 觸發詞的預設動作是出報告。 user 必須明確點名要修哪幾條 （或明說「全部修掉」）才准進 Phase 2。Phase 1 期間不准順手合併、順手刪、順手歸檔。

跟 llm-wiki-lint 差異：本 skill 針對 memory 目錄（prefix-based 平鋪結構）； llm-wiki-lint 針對 Karpathy LLM Wiki repo（wiki/ + raw/ + SCHEMA.md 三層）。

Phase 1 — 唯讀掃描

Step 1: 找到 memory 目錄

依序嘗試，命中第一個就用：

第 3 條要看當前設定目錄（多帳號並存時 $CLAUDE_CONFIG_DIR 會指到別處）：

CFG="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
MEMORY_PATH=$(jq -r '.autoMemoryDirectory // empty' "$CFG/settings.json" | envsubst)

Step 2: 跑機械掃描

# <skill_dir> = 本 SKILL.md 所在的目錄；掃描標的由參數帶入，
# 所以在哪個工作目錄呼叫都不影響結果
python3 <skill_dir>/scripts/scan.py "$MEMORY_PATH"

只用標準函式庫、唯讀、輸出 JSON。目標目錄由參數帶入，所以在哪個工作目錄呼叫都一樣。 沒有 MEMORY.md 會回 {"fatal": ...} 並以 exit 1 結束。

腳本已經處理掉幾個會讓檢查靜默失效的坑，不要自己在對話裡改寫成 shell 一行流：

• 不用 shell glob（zsh 未匹配 glob 會在指令執行前中止，而且 2>/dev/null 擋不住）
• 不用固定路徑暫存檔（並行執行會互相覆蓋、失敗留髒資料）
• 不 import 第三方套件（唯讀階段不該動 user 的 Python 環境；離線環境也裝不了）
• [[...]] 掃描先剝掉 fenced 與行內 code，且檔名與 frontmatter name 兩種都算解析成功
• 索引目標的 ./ 前綴會正規化

輸出欄位：

🔴 兩層結構下若只拿 MEMORY.md 當索引來源，會把整庫誤判成 orphan。 腳本已處理， 但若你另外手寫檢查，這是最容易踩的一個。

Step 3: 判讀（這段才是本 skill 的價值）

腳本只給事實，嚴重度與去留由你判斷。判斷前先讀 MEMORY.md 與相關索引的說明文字， 很多「異常」其實是既定決策。

不確定就降一級。推測與語意相似一律不得標 Error。

這些不是缺陷，別報

• wiki_external 多半是刻意的 —— 指向 archive/ 的歸檔檔案，或指向另一台機器上的 外部知識庫。報之前先看那個目標像不像檔案路徑，並問 user 一次就好，不要每次重報。 ⚠️ wiki_broken 裡也可能混著刻意的外部連結。 腳本靠「目標裡有沒有路徑分隔符」分類， 所以像 [[某個外部條目]] 這種沒有路徑特徵的外部參照會落到 wiki_broken。 這無法自動判斷，一律當成「需要人確認」，確認過就記進已接受例外清單，別每輪重報。

• 超過 300 行有時是刻意的 —— 若某份 canonical 規則檔明文要求「使用前必須完整讀完」， 拆開就破壞用途。標成「刻意例外」並寫明理由。

• 語意相近的一組規則可能是刻意不合併的 —— 為了精準 recall 而把同一原則拆成多個觸發點 是常見設計，索引裡通常有明文宣告。看到就標明是既定決策，不要建議合併。

• 子目錄不在掃描範圍 —— 腳本只掃根層。archive/ 是歸檔；其他子目錄可能是某則 memory 的附屬資料（例如一份 memory 指向 ref/ 底下的參考檔）。它們沒被索引是正常的。 自己補查時記得也要限制在根層，別寫成遞迴：

  find "$MEMORY_PATH" -maxdepth 1 -name '*.md' -type f     # ✅
  rg --files -g '*.md' "$MEMORY_PATH"                       # ❌ 會遞迴讀到 archive/ 與其他子目錄
  

這些要另外用眼睛看（腳本測不出來）

• 過時狀態：project_* 超過 30 天沒動、dashboard 超過 7 天沒更新、內文寫「進行中」 但檔案很久沒改。🔴 先確認時間來源可不可信：檔案的 mtime 一經複製、還原、 重新 clone 就會全部變成當下時間。是 git repo 就改用 git -C "$MEMORY_PATH" log -1 --format=%ad -- <file>； 不是 git 又剛搬過家，就明講這項檢查在本次環境不可靠，不要拿一批假的日期去下判斷。⚠️ 這是低訊號檢查 —— 黑名單、已完工的側專案、機器後路天生就不會動。 而且「進行中」命中的可能只是待辦清單裡一個帶日期的項目，不是整個專案的狀態。 報告要引出命中的那一行原文，讓 user 看得出是哪一種。
• 規則直接衝突：🔴 不要對全部檔案兩兩比對。 規則檔一多（例如 80 份以上）， 輸出會直接撐爆而被截斷 —— 那時你既審不完、也不知道漏了什麼，卻很容易誤以為審過了。 改成兩段：先用 description 的字元 bigram 做 Jaccard 粗篩（門檻約 0.16）取出候選配對， 只對候選配對讀原文；一輪最多看 10 對，超過就明講「本輪只看了前 N 對、其餘未檢查」。 命中後並列兩邊原句讓 user 自判，不要自己拍板「這是衝突」。 🔴 絕對不要因為輸出被截斷就當作「沒發現問題」 —— 那是沒檢查，不是通過。

Step 4: 出報告

繁體中文（語言跟 memory 對齊）。每個 finding 必須有具體檔名 ＋ 行為描述 ＋ 建議動作（Error 必附）。結尾主動問要不要進 Phase 2，並建議優先序： 一行就能修的（斷鏈、索引缺漏）→ 每個 session 都會載入的檔 → 大型重構。

Phase 2 — 執行修正（需明確授權）

開工前四項，缺一不進

1. 判斷是不是 git repo。 Step 1 只要求有 MEMORY.md，而預設的 ~/.claude/memory/ 常常不是 repo。整套回退機制不能預設 git 存在。

# 🔴 要比對 top-level 是不是它自己，不能只問「這裡有沒有 git」——
#    rev-parse --git-dir 會往上找父層 repo，memory 目錄只要剛好放在某個 repo 底下
#    就會被誤判成 git 模式，接著把 memory 的改動提交進那個不相干的 repo
top=$(git -C "$MEMORY_PATH" rev-parse --show-toplevel 2>/dev/null)
[ -n "$top" ] && [ "$top" = "$(cd "$MEMORY_PATH" && pwd -P)" ] && echo git || echo 非git

2. 依上一步建立回退點：

# 建備份：碰撞就停，不要覆蓋既有備份
BAK="$MEMORY_PATH.bak.$(date +%Y%m%d-%H%M%S)"
[ -e "$BAK" ] && { echo "備份路徑已存在，停止"; exit 1; }
cp -R "$MEMORY_PATH" "$BAK" && echo "回退點：$BAK"

# 回復：一定要用 --delete，否則 Phase 2 新增的檔案不會被移除
rsync -a --delete "$BAK/" "$MEMORY_PATH/"
diff -rq "$BAK" "$MEMORY_PATH" && echo "回復完成且內容一致"

🔴 「把備份複製回去」不等於回復。 單純覆蓋複製移不掉 Phase 2 新增的檔案， 回復後會是舊檔與新檔的混合體，而且看起來像成功了。一定要用 rsync --delete （或等效做法）並用 diff -rq 驗過。

3. 確認工作區乾淨（git 情況）：有未提交的改動先問 user。

4. 把 Phase 3 的驗證管道先定下來並試跑一次。 三件事都要做完才算過：

1. 寫下你打算在 Phase 3 用的那一行完整指令（含唯讀旗標與標的目錄），記進回報。
2. 用那一行實際發一次最小的唯讀請求（例如請它回報某個檔案的行數），確認拿得到回應。
3. 拿不到回應就停下來問 user，讓他選：換一個管道、接受「只做自檢、不做外部複驗」， 或不要進 Phase 2。user 選了「只做自檢」也可以繼續，但要在最終回報裡明講 這次沒有外部複驗。

🔴 只看執行檔在不在是不夠的。 裝了但沒登入、設定壞掉，command -v 一樣會過， 然後你會在 Phase 2 已經改完並提交之後才撞到 —— 正好是這道閘門要防的狀態。

🔴 本 skill 不指定用哪一套工具。 只要求它是獨立行程、可唯讀執行、 可把標的目錄寫死。至於是哪一套 CLI agent，由執行者依環境決定並記錄下來。

動手紀律

🔴 所有 git 指令一律帶 -C "$MEMORY_PATH"。 裸的 git add / git commit / git status 會作用在呼叫端的專案上（子行程裡的 cd 不會改變父行程的工作目錄）， 結果是把別人的檔案提交掉，而 memory 的改動還躺在那裡沒進版控。

🔴 Edit / Write 可能被背景 session 的隔離守衛擋住。 memory 目錄常伴隨一個 「Edit/Write 後自動 commit」的 hook，而用 Bash 改檔不會觸發那個 hook。 被擋時的正解：用 Bash 寫檔，最後手動 git -C "$MEMORY_PATH" add -A && git -C "$MEMORY_PATH" commit， 改完 git -C "$MEMORY_PATH" status -s 確認乾淨才算數。

🔴 git push 要另外問過，不含在 Phase 2 的授權範圍。 user 同意的是「修這幾條」， 不是「把 memory 發佈到遠端」。memory 內容通常私密，而推送在多數託管服務上不可逆 （就算之後刪掉，中間狀態可能已被同步或快取）。commit 完停手，明確問一句再動。 例外：該目錄若本來就掛著自動推送的 hook，那是既有行為 —— 但仍要在回報裡講明。

🔴 不要在 memory 目錄內開 worktree。 若該目錄的 hook 跑的是 git add -A， worktree 會被當成 gitlink 提交進版控。

🔴 「規則漂移」類發現一律先逐檔讀過再決定。 例如「這幾個檔依規則不該存在」—— 這種規則幾乎都留有例外（文件查不到、跨 session 才需要知道的操作性事實）。 報告階段只能標「待判斷」、禁止寫「建議刪除」；Phase 2 也禁止照單無腦刪。

🔴 改名要連帶處理入站引用，[[...]] 與 markdown 連結都要掃，含 archive/ 底下的。

收尾

重跑一次 scan.py，全綠才進 Phase 3。自檢就不過的東西不要浪費一次外部複驗。

🔴 「全綠」不是「JSON 完全是空的」。 已經跟 user 確認過、決定不處理的項目 （刻意的外部連結、刻意超長的 canonical 檔、刻意不合併的規則群組）會一直留在輸出裡。 定義是：輸出裡每一條剩餘項目，都在你這輪明確記錄下來的「已接受例外」清單上。 把那份清單寫進回報，Phase 3 的 brief 也要附上，否則外部驗證者會把它們當成新缺陷報回來。

⚠️ 腳本全綠不代表語意層也通過。 它只驗結構，改掉一處內容矛盾之後 JSON 完全不會變。 語意層的判斷（矛盾、過時、重複）沒有機械證據，回報時要分開講。

Phase 3 — 獨立複驗

🔴 先凍結

Phase 2 的改動要全部完成並提交（git）或備份定版（非 git）之後，才准派複驗。 一邊改一邊驗等於叫對方驗一個會動的目標，結論無效、還浪費一輪。

🔴 要外部行程，不能用同 session 的 subagent

subagent 繼承這個 session 的記憶注入，而那是 session 開始那一刻的快照 —— 剛改完的東西不在裡面，連檔名都可能還是舊的。拿吃著舊快照的 agent 去驗磁碟真值， 邏輯上不成立。 用獨立行程（例如另一套 CLI agent），它不吃這份注入才算外部視角。

派工時要把標的目錄寫死、把寫入權關掉，否則它可能檢查錯的目錄，或動到剛凍結的檔案。

兩種驗證題，抓的東西不重疊

A. 機械事實查核 —— 答案非黑即白：MEMORY.md 結構與行數、改名前後的檔名各自存不存在、 索引差集是否為空、[[...]] 解析失敗數是否為零、frontmatter 是否全數完整。

B. Recall 可用性測試 —— 測「找不找得到」，設計比題目重要：

• 只准從 MEMORY.md 起步，之後自行決定往下讀什麼
• 🔴 禁用 grep / find / ls 暴力掃目錄 —— 不禁的話它繞過索引也答得出來，等於沒測到路由
• 每組夾一題負面對照（問一個確定沒有記憶的主題），看它會不會憑常識編一個答案
• 要求回報走過的路徑：讀了哪些檔、是索引裡哪一行導過去的
• 要求給索引好不好用的評語，並明講不要客套

🔴 brief 要先寫明「哪些是刻意的」

外部驗證者沒有脈絡。不先講，它一定會把既定決策當成缺陷報回來，然後你得逐條解釋 —— 那正是審查迴圈燒時間的燃料。至少要先交代：刻意的外部連結、刻意超長的 canonical 檔、 刻意不合併的規則群組、已知但這次不處理的待辦、以及不在掃描範圍的子目錄。

判定與回退

⚠️ 驗證結果是輸入、不是結論。 它報的每一條先自己複核再決定改不改， 別因為「外部工具說的」就照做。特別留意三種誤判：把 user 刻意的決策當缺陷、 把不在它視野內的東西（其他機器、已歸檔）當斷鏈、把「規則說不該存在」直接推成「該刪」。

⚠️ 「審到沒問題為止」不是終止條件。 每修一次 diff 就更大，下一輪就有更多表面可挑， 這是正回饋不是收斂。要收斂就把 diff 變小 —— 與其逐條硬補，不如把出錯表面整類移除 （例如把散落的檢查邏輯收進一支測過的腳本）。判準改成「這條在實際使用路徑上打得到嗎」， 打不到就記錄進文件、不動手。

Anti-patterns

• ❌ 沒經 user 同意就進 Phase 2
• ❌ Phase 1 期間修改 / 刪除 / 合併任何 memory 檔案
• ❌ 把 scan.py 的邏輯改寫成對話裡的 shell 一行流（glob、暫存檔、cwd 那幾類坑會全部回來）
• ❌ 只把 MEMORY.md 當索引來源
• ❌ 一邊改一邊派複驗
• ❌ 用同 session 的 subagent 當「獨立」對照組
• ❌ 看到「規則漂移」就建議刪檔
• ❌ 裸 git 指令不帶 -C "$MEMORY_PATH"
• ❌ 把 git push 當成 Phase 2 授權的一部分
• ❌ 在唯讀階段安裝套件
• ❌ 把「語意相似」標成 Error
• ❌ 掃 archive/ 或其他子目錄（除非 user 明確要求）
• ❌ 沒 prefix 慣例的目錄硬套命名檢查
• ❌ 路徑偵測不到時瞎猜
• ❌ 報告用英文模板套中文 memory
• ❌ 把結果 append 到任何 ledger 檔

Important rules

1. Phase 1 唯讀不可協商 —— 報告階段禁用 Edit / Write / mv / rm / git
2. Phase 2 需明確授權，且開工前四項前置缺一不可
3. Phase 3 先凍結、要外部行程、標的寫死、寫入關掉
4. Path 偵測順序固定 —— 5 級依序，找不到就停
5. Severity 寧降勿升
6. 每個 finding 必須有具體檔名
7. 衝突永遠並列原句，不替 user 判定
8. 報告印到對話即可，不另存檔
9. 外部驗證是輸入不是結論，逐條複核
10. 未來功能（cron 定排、跨機器比對）目前不存在 —— user 問起就說 v0.x 還沒做