health-check

Wiki Health Check

執行時 CWD 須在 vault 根目錄（所有路徑皆為相對路徑）。

Vault 結構

vault/
├── raw/                 # 唯讀來源（不寫入）
│   ├── 00_inbox/        # 待處理素材：新剪藏、逐字稿
│   ├── 02_literature/   # 已處理的文獻存檔
│   └── 03_daily/        # 每日原始日誌（依年份子資料夾）
├── wiki/                # Claude 維護的知識頁
│   ├── People/          # 人物頁
│   ├── Projects/        # 專案頁
│   ├── Themes/          # 概念與合成頁
│   ├── Events/          # 活動與聚會頁
│   ├── Decisions/       # 決策記錄
│   ├── Retro/           # 回顧頁
│   └── Indexes/         # 分類索引（All-People、All-Themes 等）
├── brainstorming/       # 草稿與健康報告（monthly-reviews/、health/）
├── scripts/             # 輔助腳本（compile_state.py、check_vault.py 等）
├── index.md             # 總目錄
└── CHANGELOG.md         # 操作記錄

原則：raw/ 永遠唯讀，只寫 wiki/、brainstorming/、artifacts/。

流程

0. 機械契約驗收（先跑，硬性 gate）

先執行 python3 scripts/check_vault.py。這支腳本確定性地驗收 vault contract，取代靠記憶的人工檢查：

• FAIL（exit 1）：frontmatter 必填欄位缺漏、佔位符／資料夾型連結、log 格式或假時間、索引與檔案不同步、索引指向不存在的頁。FAIL 視為 blocking，先修到綠再做下面判斷類檢查。
• WARN：dangling wiki 連結（無頁面/alias）。刻意保留的（工具／組織／利基書作者）加進 scripts/.vault_dangling_allow.txt；其餘列入缺口建議。

腳本結果直接填進報告「機械契約」區塊；下面第 1–3 步是腳本不做的判斷類檢查（孤兒、語意衝突、缺口優先序）。第 4 步佔位符、index 同步已由腳本涵蓋，不需重做；第 5 步 alias 缺口仍須人工比對 daily 變體。

1. 孤兒檢查

找出 wiki/ 目錄下所有 .md 頁面。
對每個頁面，搜尋其他 .md 檔案中是否有對應的 [[頁面名]] wikilink。
沒有任何入站連結的頁面 → 孤兒。

2. 衝突檢查

比對近期建立的頁面（date frontmatter 在近 30 天內）與既有頁面。
若同一概念出現明顯矛盾立場，列為衝突候選，不自動修改，詢問用戶調解方式。

3. 缺口建議

掃描所有 wiki/ 頁面中出現的 [[頁面名]]，找出目標頁面不存在的 wikilink（broken link）。
被 3 處以上引用但無頁面的概念 → 列為高優先缺口建議。

4. 佔位符／資料夾型 broken link

掃描全 vault，找出年份或資料夾型的假連結：[[YYYY]]、[[raw/03_daily/YYYY]] 等指向資料夾而非具體 .md 的連結。這類多半是 compile／遷移沒填真實日期的殘留（見 rules/formats.md），列為資料缺陷，附來源檔:行。

5. People alias 缺口

對每個 wiki/People/ 頁面，比對 daily note 裡實際出現的人名變體（全名、短名、稱謂、大小寫）是否都能解析到該頁（檔名大小寫不敏感 + aliases，inline 與 block 都要解析）。daily 用了某變體卻指不到既有人物頁 → alias 缺口，列出「頁面 ← 未解析變體（次數）」。這是改名或遷移後最常見的斷鏈來源。

統計與連結比對用 Python 或 grep，rg 在部分 vault 環境行為異常不可信。

輸出報告

建立 brainstorming/health/YYYY-MM-DD-health.md：

---
date: YYYY-MM-DD
---

# Wiki Health Check — YYYY-MM-DD

## 機械契約（check_vault.py）
- FAIL：N（frontmatter X／佔位符 X／log X／index-sync X）
- WARN：N（dangling，已 allowlist X）

## 孤兒頁面（N 個）
- [[頁面名]] — 建立日期，無任何入站連結

## 知識衝突（N 個）
- [[頁面A]] vs [[頁面B]]：衝突描述

## 缺口建議（高優先 N 個）
- `概念名`：被 X 處引用，建議建立 [[wiki/Themes/概念名]]

## 佔位符／資料夾型 broken link（N 個）
- `來源檔:行` → `[[壞連結]]`

## People alias 缺口（N 個）
- [[People/頁面]] ← `未解析變體`（X 次）

## 統計
- 掃描頁面：N 個
- 孤兒：N 個
- 衝突：N 個
- 高優先缺口：N 個
- 佔位符 broken link：N 個
- alias 缺口：N 個

完成後在 CHANGELOG.md 追加（header + bullets，header 不接 | 說明）。寫入前必須先執行 date '+%Y-%m-%d %H:%M:%S' 取得真實時間，不可填假時間或 00:00:00。格式：

## [YYYY-MM-DD HH:MM:SS] health-check
- 機械 gate：FAIL N、WARN N
- 孤兒 N、衝突 N、缺口 N、alias 缺口 N