tarrragon broken-link-check
掃描 .claude/ 目錄下所有 Markdown 文件中的路徑引用，偵測失效連結。
背景
.claude/ 目錄中的規則、方法論、代理人定義文件大量交叉引用彼此。
當文件被重命名或移動時，舊的引用路徑會變成 broken link。
此工具用於定期偵測此類問題，防止 broken links 長期未被發現。
權威 gate：scan_links.py CLI
broken-link 計數的唯一權威來源是 scan_links.py 確定性 CLI，不是 LLM 手動判讀。LLM 手動 Glob/Grep 流程對同一 repo 會產出浮動計數（實測顯示相同專案產出 258 vs 155 的差異），無法作為跨框架完成 gate。CLI 以固定排除規則與穩定排序保證同一 repo 連續執行 byte-for-byte 一致，因此作為權威 gate。
立即掃描（權威）
python3 .claude/skills/broken-link-check/scan_links.py .
- 位置參數為 repo root（預設 cwd），預設掃描
<root>/.claude/**/*.md --scan-root SUBTREE（可重複指定）疊加額外子樹（如docs），使規劃文件（ticket body、spec、usecases、proposals）一併納入偵測；不帶此 flag 時行為與擴充前逐字一致（向後相容，既有 gate 用法不受影響）- exit code：
0=零 broken（gate pass）/1=偵測到 broken（gate fail）/2=執行錯誤（root 不存在、I/O 失敗） - gate 用途可直接接
&&或 CI：broken>0 即非零 exit，與工具自身錯誤（exit 2）區隔
# 擴充掃描 docs/ 下規劃文件（疊加於預設 .claude/，不取代）
python3 .claude/skills/broken-link-check/scan_links.py . --scan-root docs
輸出格式
| flag | 用途 |
|---|---|
--format text（預設） |
人類可讀：摘要 + 分組 broken 清單 |
--format json |
穩定 schema，供下游清理工具消費（含 source_file/line/raw_ref/resolved_path/category + categories 分類計數） |
四排除旋鈕（預設皆排除，flag 顯式覆寫納入）
| 旋鈕 | 預設 | 覆寫 flag |
|---|---|---|
| 程式碼區塊內引用 | 排除 | --include-code-block |
| migration-backups / hook-logs 下路徑 | 排除（歸 excluded_backup） |
--include-migration-backups |
placeholder 範例路徑（如 path/file.md） |
排除（歸 placeholder） |
--include-placeholder |
| documented-error 豁免 marker 行 | 排除（歸 excluded_documented） |
--include-documented |
覆寫旋鈕用於 triage/debug，gate 預設一律不加 flag。
documented-error 豁免 marker
error-pattern 案例表會刻意記錄不存在的路徑——例如 confabulation 案例的「錯誤參照」欄、或已遷移/刪除檔案的歷史軌跡。這些路徑的文獻價值正在於保留原貌，redirect/刪除會毀損案例資料。在含該引用的行尾（或同 table cell 內）加上行內 marker，scanner 即將該行所有引用歸 excluded_documented 不計 broken：
<!-- broken-link-exempt: documented-error -->
- 顯式 opt-in（per-occurrence），無 marker 的真實 broken 不受影響。
- marker 僅作用於所在行（PC-146 放置精確性），不會誤豁免他行。
- 僅取消「不存在」引用的 broken 計列；該行若有存在的引用仍歸
ok，不遮蔽存在事實。 --include-documented可在 triage 時顯式納入計數。
opt-in fence 稽核模式（非 gate）
--include-code-block 預設維持 False 是刻意判定：fence（程式碼區塊）內
broken 引用大量為歷史實作報告與教學/語法示範，翻預設會使多數變成誤報，淹
沒真實 drift。但維持預設不代表放棄偵測——--fence-audit 開一條獨立稽核
通道，讓 fence 內失效引用能被人定期複查，防止 drift 在無人偵測的射程外
累積。
python3 .claude/skills/broken-link-check/scan_links.py . --fence-audit
定位：這不是 gate。 --fence-audit 恆 exit 0，不參與既有命令的 exit
code 語意，也不接 CI 阻擋——即使找到大量發現，指令本身不失敗。用途是產出
「供人判讀的清單」，不是「必須降為零的計數」。
不做的事：不嘗試自動判定「語法示範」vs「操作指引」。兩者差別是語氣
（「例如」「格式如下」vs「執行以下步驟」），機器判不了；全量逐筆分類的實
測結果與抽樣外推值有數倍落差（詳見
docs/work-logs/v0/v0.2/v0.2.1/fence-ref-triage.md），印證語意分類不可
靠。稽核模式只輸出機器可靠取得的分組訊號：
| 欄位 | 說明 |
|---|---|
carrier_nature |
依來源檔路徑段判定的載體性質：可執行指令載體（commands/）、案例敘事載體（error-patterns/）、歷史報告載體（hook-specs/）、未分類（其餘目錄，性質混雜不構成可靠訊號） |
has_marker |
該行是否已有 broken-link-exempt / portability-allow 豁免 marker（category 對應 excluded_documented），供人複核既有 marker 是否仍合法 |
merge_successor |
沿用既有合併型遷移反查索引，有值者為高信心可直接改指 |
彙總層另提供 by_carrier_nature 與 marker_counts 兩組計數，取代語意
三分類統計（「歷史報告 / 語法示範 / 真實 drift」機器判不了，改以可靠訊號
分組呈現）。
--format json 輸出額外欄位：scanned_files / fence_entries_count /
by_carrier_nature / marker_counts / entries（每筆含
source_file/line/raw_ref/resolved_path/category/carrier_nature/
has_marker/merge_successor）。與既有 gate 路徑（無 --fence-audit
時）完全不共用輸出 schema，不影響原有 --format json 欄位。
--scan-root 對 --fence-audit 同樣生效（疊加額外子樹）。
搭配 /loop 定期掃描
/loop 1h python3 .claude/skills/broken-link-check/scan_links.py .
偵測規則（CLI 內建，供理解輸出用）
CLI 已內建以下規則，本節僅供閱讀輸出時對照，非需手動執行的步驟。
偵測的路徑格式：
| 格式 | 範例 | 解析基準 |
|---|---|---|
@.claude/path/file.md |
@.claude/pm-rules/decision-tree.md |
repo root |
.claude/path/file.md |
.claude/agents/incident-responder.md |
repo root |
../path/file.md |
../agents/lavender-interface-designer.md |
引用文件所在目錄 |
./path/file.md |
./references/detail.md |
引用文件所在目錄 |
排除：http(s)://（外部 URL）、#section（錨點）、預設四旋鈕涵蓋的程式碼區塊 / 備份目錄 / placeholder 範例 / documented-error marker 行。
Fallback：手動流程（非權威，僅 CLI 不可用時參考）
以下手動 Glob/Grep 流程為 scan_links.py 無法執行時（如環境缺 Python）的降級參考，計數可能浮動，不可作為完成 gate。權威結果一律以 CLI 輸出為準。
- Glob 找出
.claude/**/*.md，排除.claude/hook-logs/ - Grep 找出上述四種前綴的路徑引用，排除 URL / 錨點 / 程式碼區塊
- 依解析基準轉為實際路徑
- Read/Glob 確認路徑存在，不存在者記為 broken link（含文件名與行號）
- 輸出 broken 清單
修復建議
發現 broken link 時，建議的修復步驟：
- 搜尋相似文件名（文件可能被重命名）
- 確認文件是否已移至其他目錄
- 更新引用路徑（使用 Edit 工具）
- 如文件確實已刪除，移除引用或更新為替代文件
注意事項
- 此工具預設只掃描
.claude/目錄；--scan-root docs可疊加docs/，其他目錄（ui/、server/等）仍不在掃描範圍 - 只偵測文件引用，不偵測 URL 有效性
- 相對路徑解析基於文件所在目錄，需正確計算層級
- 大型
.claude/目錄（100+ 文件）掃描可能需要數分鐘
版本紀錄在同目錄的 CHANGELOG.md。