schema

Schema 變更日誌

Append-only。追蹤 AGENTS.md、CLAUDE.md 與 00-規範/ 的演進。每筆變更以 ### 變更 N：標題 為小節，內含 Before / After / 動機 / 修訂的檔案 / 影響。

不分月，因 schema 變更頻率低、需要完整歷史一覽。

歷史：變更 1-3 發生於 2026-04-28、本檔建立前，未抽出，仍保留於 log/2026-04.md 的「Schema 變更」區段。本檔自變更 4 起為 schema 變更的單一事實來源。

2026-04-28

變更 4：log 從單檔改為 folder

結構變更：

• Before：根目錄 log.md 單檔承載所有 ingest / lint / schema / 系統備忘條目
• After：
  • log/YYYY-MM.md 月度檔承載 ingest / lint / 系統備忘
  • log/schema.md 單檔承載 schema 變更
  • 根目錄 log.md 廢除

動機：

• 預期 ingest 高頻（每天多條），單檔長期會膨脹到 LLM 每次讀取吃大量 context
• 月度切片讓 query 只需讀近 1-2 個月；pipeline 路徑可預測（log/YYYY-MM.md）
• schema 變更頻率低、需要完整歷史一覽，獨立成單檔比按月切片更利於掃描
• 避免雙真相：根目錄不再保留 log.md，monthly 檔即唯一來源

修訂的檔案：

• CLAUDE.md §2、§5.1.8、§5.2.3、§5.3、§8、§9
• 新建 log/2026-04.md（從 log.md 整批複製）、log/schema.md
• 刪除根目錄 log.md

Migration 計畫 / 影響：

• 既有 log.md 內容整批複製到 log/2026-04.md（保留 2026-04-28 當日所有條目原時間軸）
• 變更 1-3 留在 log/2026-04.md 內未抽出，因 1-3 確實發生於 2026-04-28，原始位置即正確時間軸；schema.md 從變更 4 起為單一事實來源
• vault 內 wiki / 來源頁未引用根目錄 log.md，無 wikilink 斷裂風險（10-來源/文章/2026-04-28-Karpathy-LLM-Wiki-gist.md 提到的 log.md 是 Karpathy gist 內文摘要，屬不可變層的 frozen quote，不受影響）

2026-05-02

變更 5：§5.4 完成後 commit

結構變更：

• Before：CLAUDE.md §5 三個操作（ingest / query / lint）做完後沒有規定要 commit——LLM 維護者完成工作後，等使用者下指令才 commit；實務上常常多個 ingest 累積成一個巨大的 commit，難以審計。
• After：新增 §5.4「完成後 commit」——任何修改 vault 內容的操作完成後，自動 commit；一次操作 = 一個 commit；commit message 格式約定（ingest: / lint: / schema: / wiki:）。

動機：

• 可審計：每個 ingest 變成獨立 commit，未來回頭看「這條 wiki 條目是哪份來源帶進來的」可直接 git log / git blame 定位，不用翻 log/YYYY-MM.md。
• 減少使用者負擔：使用者不用每次操作後再下「commit」指令；落地與 5.1-5.3 一氣呵成。
• Pipeline-readiness：未來腳本化跑 ingest 時，每個 ingest 自動 commit 是 batch 化的前提（CLAUDE.md §1「現在的每個決定都應假設未來會被腳本呼叫」）。
• 真實案例觸發：2026-05-02 一日內 ingest 兩份 李宏毅 來源（2026-05-02-Harness-Engineering駕馭工程 + 2026-05-02-AI-Agent-Context-Engineering系統化），兩個 ingest 改動的檔案在 git working tree 中混雜，事後拆分困難——這個事件直接觸發本規則制定。

修訂的檔案：

• CLAUDE.md 新增 §5.4
• 本檔（log/schema.md）追加變更 5

Migration 計畫 / 影響：

• 歷史不追溯：規則生效前的未 commit 工作（截至 2026-05-02 git working tree 中堆積的兩個 ingest）作為「規則前最後一次手動清理」整批處理——兩個 ingest 在 working tree 中已彼此混雜（多個 wiki 頁兩次 ingest 都改過），事後乾淨拆分代價高且易出錯，整批一個 ingest commit；schema 變更獨立一個 commit。規則生效後（即 commit b 之後）的 ingest 嚴格一一對應 commit。
• 無 wiki 結構影響：本規則不涉及任何頁的 frontmatter / heading / 路徑變更，wiki 層完全不受影響。
• .obsidian/ 噪音檔處理：本規則明示 .obsidian/app.json / .obsidian/graph.json 等 Obsidian 自動寫入的 UI 狀態檔不納入 ingest commit——這些檔目前在 git tracking 內但屬於環境噪音；長期可考慮加入 .gitignore，但本次規則僅規範 commit 行為，不動 tracking 設定（gitignore 由使用者主導決定）。

變更 6：§5.3 加入執行策略 + 死連豁免區

結構變更：

• Before：§5.3 只列檢查項清單（孤兒 / 死連 / 矛盾 / 過時 / frontmatter / 重複），未指定執行策略；上一輪 lint（log/2026-05.md，2026-05-01）發現 cluster-based subagent 並行掃描漏抓 項目盒子 死連，已自承「下次 lint 應追加死連專項掃描」的觀察，但未進 schema。
• After：§5.3 新增「執行策略」三步：(1) 死連專項先掃（消除跨 cluster 隱性 cluster 盲點）→ (2) cluster-based 並行掃描 → (3) 主 agent 收斂；同時新增「死連豁免區」三類（規範示例占位 / log+index narrative placeholder / 來源中觀察清單級的未 ingest 對象），明確哪些 grep 命中不算 lint 違規。

動機：

• 承接觀察結論：log/2026-05.md 已自承 cluster-based 漏網的根因，本次正式進 schema，避免下次 lint 重蹈覆轍。
• 降低 lint 噪音：vault 全域死連 grep 共 410 處，但其中 240 處在 log/index narrative（描述未來建頁）+ 11 處在規範示例（教學用占位）= 251 處（61%）是工作流副產品而非真死連。豁免區明示後，lint 工具能聚焦在真正的 108 wiki + 51 來源死連。
• Pipeline-readiness：未來腳本化跑 lint 時，豁免區就是 grep 過濾規則的可執行 docstring（CLAUDE.md §1：「現在的每個決定都應假設未來會被腳本呼叫」）。

修訂的檔案：

• CLAUDE.md §5.3（含 last-updated）
• 本檔追加變更 6

Migration 計畫 / 影響：

• 無 wiki 結構影響：本規則僅補強 lint 程序描述，不動任何頁的 frontmatter / heading / 路徑。
• 歷史 lint 結果不追溯重評：log/2026-04.md 的「全 vault 死連專項掃描」已是這個策略的 ad-hoc 實作；log/2026-05.md 的「項目盒子死連修正」已是其產物。歷史 lint 仍按當時規則理解。
• 觸發本次變更的 vault 狀態：2026-05-02 「分析 wiki 可優化部分」操作中，量化掃描出 410 處死連——若沒有豁免區，下次 lint 會被噪音淹沒。本變更是這個操作的副產品。

變更 7：§5.1.8 ingest narrative 重定位 + 來源模板新增 Ingest 筆記段

結構變更：

• Before：§5.1.8「追加 log/YYYY-MM.md」未限制條目體積；實踐中 ingest narrative 全寫進 log（每筆 200-800 字 / 2026-05.md 月才過 2 天就破 158KB / 1898 行 / 已超出 LLM 一次 read 上限）。同時 index.md 開頭也累積層層 nested 「最近修補」blockquote（已在同日 commit 17d3f57 砍除）。同一份 narrative 同時存在於 log + index + 來源頁三處，違反 §8「單一事實來源」精神。
• After：§5.1.8 拆分為「決策摘要」（≤ 1KB，寫進 log 月度檔：時間 / 來源路徑 / 新建頁 / 大幅更新頁 / 元命題 / 觀察清單）vs「narrative 主體」（詳細推理 / 跨頁影響鏈 / ASR-OCR 修訂註解 / 觀察清單長文，寫進來源頁的 ## Ingest 筆記 段）。五個來源模板（文章 / PDF / bundle / 圖片 / 手寫）皆新增該段，位於「## 提取概念」之後。

動機：

• 可讀性：log 月度檔回歸時間軸索引（pipeline 一次 grep 就拿到時間線），詳細推理留在來源頁（讀一份來源就看到完整 ingest 決策上下文，不用再跨檔追線索）。
• 不違反 §8 append-only：歷史月度檔不追溯瘦身；只規範未來 ingest 的寫法。
• 單一事實來源：未來 ingest narrative 只在來源頁的 ## Ingest 筆記 段一處；index.md 已於同日 commit 17d3f57 砍除「最近修補 narrative」+「最近 ingest 來源 段每筆 200-800 字」改為一行 pointer，配合本變更形成「log = 時間軸索引 / index = 結構導覽 / 來源頁 = ingest narrative 單一事實」三檔分工。
• Pipeline-readiness：log 條目 ≤ 1KB 之後，腳本可期望「一次 read 拿到整月 ingest 時間線」；來源頁 narrative 有穩定 heading（## Ingest 筆記），可被切片。

修訂的檔案：

• CLAUDE.md §5.1.8（含 last-updated）
• 00-規範/模板/來源-文章.md
• 00-規範/模板/來源-PDF.md
• 00-規範/模板/來源-bundle.md
• 00-規範/模板/來源-圖片.md
• 00-規範/模板/來源-手寫筆記.md
• 本檔追加變更 7

Migration 計畫 / 影響：

• 既有 77 個來源頁不主動加 ## Ingest 筆記 段：lazy migration——下次該頁因 ingest / lint 被觸碰時補；保留 git history 乾淨、不污染歷史 commit。
• 既有 log/2026-04.md / log/2026-05.md narrative 不動：合 §8 append-only；視為「規則前歷史 narrative」，下次寫起按新規則。歷史 narrative 雖長但仍是有效資料，只是 LLM 讀取時要分頁——可接受。
• 現有 ingest 範式不破壞：本變更只規範條目體積與位置，不改 ingest 步驟序列（仍是辨識類型 → 建來源頁 → 抽取候選 → 掃描 wiki → 更新 / 新建 → 互相連結 → 更新 index → 追加 log）。
• 本日 commit 17d3f57（index.md 結構重整）為配套變更：兩個 commit 邏輯耦合——index 砍掉的 narrative 與本變更要寫進來源頁 Ingest 筆記段的內容，是同一份 narrative 在 vault 中的兩個出口；commit 17d3f57 砍出口、本 commit 開新出口。

2026-05-03

變更 8：§5.5 觀察清單規範 + §3/§7 meta-concept 類型 + §8 衍生視圖原則

結構變更：

• Before：
  • 觀察清單散落在 log/YYYY-MM.md 各 ingest 區段內（log/2026-05.md 累積到 2828 行 / 30+ 個觀察清單 section / 96+ 條開放條目），無集中查詢點。
  • 跨期重複條目沒有 dedup 機制（例：Paul-Graham 在曼報 EP63 + EP163 各列一次、SaaS 案例 cluster 在 BVP + OpenView 雙 ingest 各列 N 次）。
  • 已超門檻的 MOC 候選（視覺設計 / 品牌設計 / 組織管理 / 個人品牌）沒有自動浮現機制——埋在 log 中無人盯。
  • vault 既有頁類型只有 concept / entity / moc / source-*，無法承載「散在多頁但尚未統合的元層命題」（如 Why-first-家族 / 迭代精神 / 降低防禦反應）——pilot 收割時這類候選 9 條，明顯需要獨立分類。
• After：
  • 新建 觀察清單.md（vault 根目錄，wiki 元層；§5.5 規範）作為當前狀態快照，與 log 月度檔（時間軸歷史）互補。
  • §5.5 定義六類分類（死連 stub / MOC 候選 / 待 ingest 外部資源 / 拆頁候選 / entity 升格 / Umbrella 元命題）+ 條目欄位（候選 / 加入日 / 來源 ingest / 觸發條件 / 當前進度）+ cluster 級條目格式 + ingest 同步規則 + 邊界釐清（與「未來累積方向」/ §5.3 死連豁免區的關係）。
  • §7 frontmatter type 列舉值新增 meta-concept；§3 20-Wiki/概念/ 註明可承載 meta-concept 子類型。
  • §8 新增「衍生視圖明示性」原則：當前狀態快照型檔（如 觀察清單.md）必須可從 append-only 來源重生，不視為獨立事實來源；對應未來 lint 階段自動產出機制（roadmap Phase 3）。

動機：

• 使用者體驗：vault 才 60 天就累積到「散落式追蹤已成本過高」的拐點——log/2026-05.md 30+ 觀察清單 section / 96+ 開放條目；4 個已超門檻 MOC 沒人盯（pilot 中浮現）。本變更前無法回答「目前還在追蹤什麼？」這個基本查詢。
• 不違反 §8 單一事實來源：透過明示「衍生視圖」性質區隔——log 月度檔仍是事件歷史的單一事實來源（不可改），觀察清單.md 是當前狀態的衍生視圖（可重生）。兩者性質不同、互補存在；衍生視圖原則進 §8 確保未來腳本化時不會誤把它當作獨立事實。
• 預埋 cross-period dedup 機制：跨期重複條目（同候選在多次 ingest 中出現）的合併規則進 §5.5，避免 N 次 ingest = N 條死連條目的清單暴增。
• Pipeline-readiness：六類分類 + 條目欄位定義為機器可解析的表格化格式（CLAUDE.md §1：「現在的每個決定都應假設未來會被腳本呼叫」）。Phase 3 lint 階段直接以此 schema 自動產出。
• 預埋 meta-concept 類型：pilot 9 條第六類候選的密度暴露 vault 既有頁類型不足；登錄類型佔位後，Phase 2 試做第一個 meta-concept（候選 Why-first-家族）時不需再動 schema。
• 觸發本次變更的具體事件：2026-05-03 與使用者討論「觀察清單散落 log 中的優化方向」→ 派 subagent 跑 pilot 收割（96+ 條開放、13+ 已消化、第六類浮現）→ 確認集中化值得做且 schema 改進信號明確 → 本變更落地。

修訂的檔案：

• CLAUDE.md 頂部 last-updated / §3 (20-Wiki/概念/ 描述) / §5.5 新增 / §7 type 列舉 / §8 第 6 條
• 本檔（log/schema.md）追加變更 8

Migration 計畫 / 影響：

• 本變更不獨立產出 觀察清單.md——schema 條文與檔案產出拆兩個 commit：本 commit 只動 schema；下個 commit「wiki: 新建 觀察清單.md」基於 pilot 結果產出 v1。
• 既有 log 月度檔的觀察清單條目不追溯遷移：合 §8 append-only。觀察清單.md v1 一次性從 pilot 結果建立、之後由 ingest 過程同步；歷史 log 內的觀察清單條目仍是時間軸事實，新檔是當前狀態快照，兩者並存無衝突。
• 既有 wiki 頁無結構影響：本變更不動既有 concept / entity / moc / source 頁的 frontmatter / heading / 路徑。meta-concept 類型雖然登錄，但實作模板與第一個 meta-concept 頁延後到 Phase 2（觸發時機：首個 meta-concept 試做）。
• 與 §5.3 lint 死連豁免區的耦合：第 3 類「觀察清單級提及」的判定來源原本只看 log；本變更後也涵蓋 觀察清單.md 內條目。lint 工具未來實作時應以 觀察清單.md 為主要豁免來源（更準）+ log 為輔。
• Roadmap 對接：本變更為 Phase 1（schema 骨架 + 手動同步）；Phase 2 補 cross-period dedup 細則 + 「未來累積方向」vs 觀察清單邊界實戰修正 + 第一個 meta-concept 試做；Phase 3 觀察清單.md 改為 lint 衍生產出。Phase 規劃見 2026-05-03 對話記錄（未進 schema，因規劃本身會隨實作微調）。

2026-07-11

變更 9：§5.4 Git 操作邊界

結構變更：

• Before：AGENTS.md / CLAUDE.md §5.4 要求任何修改 vault 內容的操作完成後自動建立 git commit；secbrain-vault skill 也把 commit behavior 納入 vault write 必遵規則。
• After：§5.4 改為「Git 操作邊界」：SecBrain vault 維護規則不要求 LLM agent 自動執行 git 相關動作；除非使用者明確要求，agent 不執行 git status、git diff、git add、git commit、git push，也不把 commit 當作完成條件。

動機：

• 使用者明確確認：SecBrain 相關 agent 不應因角色腳本而主動執行 git 動作。
• 2026-07-11 ingest Reading Outpost《焦慮的意義》時，agent 依舊規則嘗試檢查 git commit 條件，因 vault 內 .git metadata 不可用而把 issue 標為 blocked。根因不是內容 ingest 失敗，而是角色規則把 commit 誤設為完成條件。
• 對 SecBrain 這類 iCloud / rclone 掛載 vault，版本控制狀態不一定穩定暴露給 runtime；git 行為應改由使用者明確要求時才處理。

修訂的檔案：

• AGENTS.md 頂部 last-updated / §5.4
• CLAUDE.md 頂部 last-updated / §5.4
• log/schema.md frontmatter / 變更 9
• secbrain-vault skill：移除 commit behavior 要求，新增不主動跑 git 的邊界
• /root/holo_os/memories/projects/secbrain.md：更新專案記憶，標記 SecBrain 維護預設不主動執行 git

Migration 計畫 / 影響：

• 未來 SecBrain ingest / lint / schema / 直接建頁完成後，只需完成內容驗證與結果回報；不再自動跑 git，也不因沒有 commit 而標記 blocked。
• 若使用者明確要求 commit / diff / status，agent 可依該次指令處理；若 repo metadata 不可用，只回報原因，不自行初始化或修復 repo。
• 既有 schema 變更 5 保留為歷史紀錄，不追溯改寫；本變更是對舊規則的明確覆蓋。