chore: template 1.9.x 知識庫遷移 → system-dev/

把 system-dev-template 1.9.x 的知識庫基建搬進 git（從功能 PR 拆出，獨立成筆）： - system-dev/wiki/：LLM 記憶系統（principles 鐵律 + 5 張 ingest 卡 + INDEX/TAXONOMY + status/mistakes） - system-dev/docs/：SDD 新家（3-specs/ + 2-architecture/ + README/SKILL）；ingest-pipeline SDD 從 docs/3-specs/ 搬來 - system-dev/scripts/：install/update - .claude/：wiki/SDD harness（commands + hooks：session-recall / sdd-guard / wiki-secret-scan） SDD 位置統一：docs/3-specs/ingest-pipeline → system-dev/docs/3-specs/ingest-pipeline （對齊 SDD guard hook 預期路徑 + template 1.9.x 規約）。純基建遷移，不含任何功能程式碼（src/tests/contracts 在功能 PR #3）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 20:45:18 +08:00
parent dffefdcdc2
commit 06e901f590
36 changed files with 2635 additions and 45 deletions
@@ -0,0 +1,36 @@
+# .wikiignore — 不想被編入 wiki 的內容（像 .gitignore）
+#
+# 三層防護的 L1（檔案層）。CC 在 /wiki-init、/wiki-capture 掃描文件時，
+# 命中這裡 pattern 的「整個檔案」不讀、不編入 wiki。
+#
+# 語法：一行一個 glob pattern，相對專案根目錄。# 開頭是註解。
+#
+# ── 同場另兩層 ──────────────────────────────────────
+# L2 行內標記：檔案要編入，但某段不要 → 在該段前後包：
+#     <!-- wiki:ignore -->
+#     這幾行不會被編入 wiki
+#     <!-- wiki:end -->
+# L3 機械底線：萬一機敏值仍被寫進 .claude/wiki/，wiki-secret-scan.sh 會 exit 2 擋下。
+#
+# 三層的分工：L1 整檔排除（你主動列）｜L2 局部遮蔽（你標記）｜L3 兜底攔截（自動掃）。
+# ────────────────────────────────────────────────────
+
+# ── 機敏檔案（預設就該排除）──────────────────────
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+*credentials*
+*secret*
+**/secrets/**
+
+# ── 個資 / 客戶資料（依專案調整）────────────────
+# customers/**
+# *personal-data*
+
+# ── 草稿 / 暫存（不值得進記憶）──────────────────
+# **/draft/**
+# *.tmp.md
+# SCRATCH.md
@@ -0,0 +1,62 @@
+# system-dev/wiki/ — LLM 記憶系統
+
+> 新 session 開始時從這裡導航。
+> 目的：讓 CC 不需要重新學習已知的事。
+> 維護者：CC（人不手動編輯這裡）
+
+---
+
+## push 檔（session 開始由 hook 主動注入，CC 行動前必看見）
+
+| 檔案 | 注入形態 | 內容 |
+|------|---------|------|
+| `status.md` | 全文 | 當前進度、下一步（時態狀態）|
+| `principles.md` | 全文（一行一條）| 跨全局設計原則，行動前必服從 |
+| `mistakes.md` | 標題+一行症狀，全文按需展開 | 踩過的坑、被糾正的誤解（防不自覺盲區）|
+
+> 為什麼這三個 push 而非 pull：它們是「CC 不會主動查、但不看就出事」的盲區。詳見 `/wiki-init` 的「push vs pull」。
+
+---
+
+## pull：cards/（CC 按需檢索）
+
+一切知識內容——原文摘要、AI 筆記、決策、概念知識——都寫成 `cards/<bucket>/` 的概念原子卡。
+`decisions-summary.md` 已降級為 cards（決策＝知識內容）；既有的保留為相容。
+
+---
+
+## 維護規則
+
+1. 只增不刪——記錄 append，內容改了加新條目說明「舊的已更新」
+2. status.md 每次 session 結束更新；mistakes/principles 一發現就 append
+3. principles 一行一條、≤15 條（超過代表該合併或下放成 card）
+4. **新增一個檢索角度 = 在下方「多角度視圖」加一節，不開新實體檔、不問用戶**
+
+---
+
+## 多角度視圖（由 /wiki-init、/wiki-capture 填入）
+
+INDEX 是**所有檢索角度的入口**，不只標籤。原文是唯讀 SSoT，wiki 是改寫過的記憶。
+新增角度只要在這裡加一節（如「決策角度」「原則角度」），指向對應 cards 或 push 檔——**不必新增實體特殊檔**。
+
+### 標籤角度（按 `TAXONOMY.md` 的軸聚類，指向桶子索引）
+
+#### 掛載架構
+- [[ingest/00-INDEX]] — ingest 餵食器（5 卡）→ [[掛載架構]]、[[跨repo織網]]
+
+#### 契約邊界
+- [[envelope-契約]] — ingest→graph 唯一耦合面
+
+#### 萃取策略
+- [[採取優先於萃取]] — 路徑 A 採取 vs 路徑 B 萃取
+- [[extract-模型策略]] — 模型選擇、品質門檻、升級閘
+
+### 決策角度（取代舊 decisions-summary.md 的視圖）
+
+- [[envelope-契約]] — 向量化分工升格成契約：ingest 打標、base 讀標執行（leo 2026-06-26）
+- [[採取優先於萃取]] — 採取＞萃取：gloss 由 local CC 在生產當下建，不留給 ingest 補（leo 2026-06-26）
+- 純餵食器五鐵律見 `principles.md`（leo 2026-06-26 拍板）
+
+> 結構：INDEX（多角度入口）→ `cards/<bucket>/00-INDEX.md`（桶子索引，固定名）→ 概念原子卡。
+> 指 `00-INDEX` **一律帶路徑** `[[bucket/00-INDEX]]`（固定名跨桶撞名）；卡片間用裸 `[[卡名]]`。
+> 分類由卡片 frontmatter `tags:` 承載，標籤字典見 `TAXONOMY.md`。詳見 `/wiki-init` 規範。
@@ -0,0 +1,46 @@
+# TAXONOMY.md — 標籤字典（本 repo 專屬）
+
+> wiki 卡片的 frontmatter `tags:` **只能用這裡列出的標籤**。
+> 這不是凍結——字典**可以擴充**，只是**禁止繞過字典在卡片裡直接冒新標籤**。
+> 維護者：CC（由 /wiki-init 初始化、隨 wiki 演進受控擴充）。
+>
+> **遇到現有軸都裝不下的內容時，照這個流程（先查、後擴、登記）**：
+> 1. **先查既有**：現有標籤真的都不合，還是只是同義詞？（`知識管理` vs `KM` vs `筆記管理` 是同一軸，別重造）
+> 2. **確實是新軸** → 把新標籤加進本檔（附一句定義），再用。不必停下來問人，但「先登記再使用」這道查核不能省。
+> 3. 自由增生才是要防的——同義標籤散開會讓同類卡片分散、下游聚類失準。受控擴充（先查重、再登記）不會。
+>
+> **字典是每個 repo 各自的**：跨 repo 引擎靠各 repo 自己一致的 taxonomy 接合，不是逼所有 repo 共用一份。
+> 知識型 vault 的領域軸（知識管理／學習認知）和開發 repo（子系統／基礎設施）本來就該不同。
+
+---
+
+## 分類採雙軸（一張卡可多重歸屬）
+
+分類由 **frontmatter `tags:`** 承載，不靠資料夾、不靠行內 `#tag`。
+一張卡同時掛「領域 1-3 個 + 形態 0-2 個」，可從任一軸過濾。
+
+### 領域（主軸，每卡 1-3 個）
+
+> kbdb-ingest-plugin（餵食器）的子系統軸。/wiki-init 2026-06-26 依本 repo 性質定。
+
+- `ingest管線` — 採取/萃取/匯總/輸出的資料流本身
+- `契約邊界` — ingest↔graph 的 envelope 契約、職責切割
+- `萃取策略` — extract 路徑（模型選擇、品質門檻、升級閘）
+- `掛載架構` — base→graph→ingest 堆疊、API 邊界、三守則
+- `部署` — wrangler 部署、繞 Actions、觸發機制
+
+### 形態（副軸，每卡 0-2 個）
+
+- `架構設計` — 結構/邊界/資料流的設計判斷
+- `鐵律約束` — 不可違反的硬規則（與 principles.md 呼應）
+- `模型策略` — LLM 萃取的模型/tier 選擇
+- `契約規格` — 逐字依凍結契約的形式規格
+
+---
+
+## 規則
+
+1. **先查重、再登記、才使用**：禁止繞過字典在卡片直接冒新標籤；新標籤先確認非現有同義詞，加進本檔（附定義）再用。
+2. **領域 vs 形態分開**：領域是「講什麼主題」，形態是「以什麼形式呈現」，不要混。
+3. **頂層 INDEX.md 的標籤視圖依本字典的軸聚類**——字典改了，INDEX 視圖跟著更新。
+4. **新增領域軸要慎**：領域是檢索骨架，動它影響全庫聚類；形態軸（呈現形式）擴充較安全。不確定就先用現有最接近的，並在卡片或本檔註記「待人類複核此分類」。
@@ -0,0 +1,17 @@
+# ingest 餵食器
+
+> 桶子索引（容器：只連不重寫）。kbdb-ingest-plugin 的核心知識卡。
+> 跨專案藍圖：InkStoneCo `docs/3-specs/mira-dissolve/`。SDD：`docs/3-specs/ingest-pipeline/`。
+
+## 架構與定位
+- [[掛載架構]] — base→graph→ingest 三層堆疊、API 邊界、無環
+- [[採取優先於萃取]] — 路徑 A（採取本地三元組）vs 路徑 B（裸原文 extract）
+
+## 契約
+- [[envelope-契約]] — ingest→graph 唯一耦合面：送什麼、禁送什麼、向量化打標分工
+
+## 萃取
+- [[extract-模型策略]] — 用戶選意圖、品質門檻白名單、Haiku/Claude 分層、升級閘
+
+## 主職
+- [[跨repo織網]] — 匯總多 repo 三元組，織單一 repo 看不到的橋與異見
@@ -0,0 +1,43 @@
+---
+tags: [契約邊界, 契約規格, 架構設計]
+gloss: ingest→graph 的唯一耦合面——一個來源檔一次萃取產出的候選 envelope，規定 ingest 能送什麼、禁送什麼。
+---
+# envelope 契約
+
+← [[ingest/00-INDEX]]
+
+**來源**：`contracts/ingest-candidate.json`（凍結形式契約，逐字依原文）、`docs/3-specs/ingest-pipeline/design.md`
+**最後更新**：2026-06-26
+
+> 這是**凍結的形式契約**。欄位的精確 schema 以 `contracts/ingest-candidate.json` 為唯一真相，**逐字依原文**；本卡只距離化「設計意圖與職責切割」，不取代 schema。
+
+## 摘要
+
+`IngestCandidateEnvelope` 是 ingest 與 graph 之間唯一的耦合面：一個 envelope ＝一個 canonical MD 一次萃取的候選產物。
+
+## 重點
+
+- **頂層三必填**：`source`（來自哪個檔 + 快照鍵）、`extractor`（哪個模型/tier 萃的）、`triplets`（邊，至少一條）。另有選填 `nodes[]`（節點層附帶資訊）。`additionalProperties: false` 全程鎖死。
+- **source = 指回原文的指標 + append-only 快照鍵**：`uri`（`github:<owner>/<repo>@<path>`）+ `content_hash`。同一 uri 後續 envelope **取代**前一批（latest-wins），不疊加；同 hash → graph no-op 跳過。
+- **取代語意歸 graph，ingest 一無所知**：同 uri 出新 hash 時，graph 把舊 active 實例 PATCH 成 deprecated、append 新批 active（可查/rollback/清）。ingest 只管送新批。
+- **向量化分工（leo 2026-06-26 升格成契約）**：ingest 在 `nodes[].embed` / `triplets[].predicate_embed` **打標**「要不要向量化、embed 什麼（名+gloss / 謂詞裸詞）」；base/KBDB embed 模組**讀標執行**實際 embedding。**ingest 自己不算向量**（呼應 [[掛載架構]]「准運算不准碰儲存」、principles「不算向量 normalize」）。
+- **ingest 能送**：原始 s/p/o + `source.*` + `extractor.*` + `nodes[].gloss/aliases/entity_type/embed` + `confidence` + 謂詞向量打標。
+- **ingest 禁送（graph 領域，絕不可送）**：`id`（record id）/ `clusters` / `bridge_score` / `created_at` / `updated_at` / triplet 上的 `subject_entity_type|object_entity_type`（類型只走 `nodes[]`）。結構符號（`>>`/`←`）與給人讀的散文（`## 摘要`）也不進 envelope。
+- 這是**【輸入候選】不是【已存三元組】**（後者見 graph 的 triplet.json）。
+
+## 實體
+
+- **IngestCandidateEnvelope**（envelope／凍結契約）— ingest→graph 唯一耦合面，一個來源檔一次萃取的候選產物。
+- **向量化打標**（embed/predicate_embed 標記）— ingest 標哪些 node/謂詞要 embed、embed 什麼，自己不執行 embedding。
+- **讀標執行**（base embed 模組）— base/KBDB 讀 ingest 的標去做實際 embedding 的分工角色。
+- **content_hash**（快照鍵）— 來源檔內容 hash，graph 據此判 no-op 或寫新快照。
+- **禁送欄位**（graph 領域）— id/clusters/bridge_score/時間戳/邊上 type，由 graph 算、ingest 絕不送。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- 向量化打標 >> 配對分工 >> 讀標執行
+- IngestCandidateEnvelope >> 禁止攜帶 >> 禁送欄位
+- content_hash >> 充當 >> IngestCandidateEnvelope
+### 卡片關係（卡對卡）
+- [[envelope-契約]] >> 約束 >> [[掛載架構]]
+- [[envelope-契約]] >> 承載產出於 >> [[extract-模型策略]]
@@ -0,0 +1,41 @@
+---
+tags: [萃取策略, 模型策略]
+gloss: ingest 走路徑 B 萃裸原文時的模型選擇與品質把關策略——用戶選意圖、品質門檻白名單、淺萃預設 Haiku、深萃 Claude、JSON-fail 升級閘。
+---
+# extract 模型策略
+
+← [[ingest/00-INDEX]]
+
+**來源**：`docs/3-specs/ingest-pipeline/{requirements,design}.md`、`CLAUDE.md`、`contracts/ingest-candidate.json`（extractor.tier）
+**最後更新**：2026-06-26
+> 跨專案完整版在 InkStoneCo `docs/3-specs/mira-dissolve/design.md §6.6`。本卡距離 ingest 內部要點。
+
+## 摘要
+
+只在路徑 B（裸原文萃取）才用。模型由用戶選「意圖」非「型號」，有品質門檻白名單把關，預設淺萃、必要時升級深萃。
+
+## 重點
+
+- **用戶選意圖非型號**：像 `/model` 那樣選意圖（要快/要深），不是選具體型號。
+- **品質門檻白名單**：模型要入白名單須過門檻——萃得出「深層暗示」+「中文過關」。難度隨來源分層：AI 報告弱模型夠、人類 vault（口語、暗示多）須好模型。
+- **兩 tier**（對應 envelope `extractor.tier`）：`shallow` = Workers AI 淺萃（預設 Haiku，走 API 便宜）；`deep` = Claude 深萃 via CC（走月費不走 API）。
+- **JSON-fail 升級閘**：淺萃 JSON 解析失敗 / 萃出過稀 → 自動升級到 deep 重萃。
+- **第一版不 embed**：embed 等 base vectorize 就緒（InkStoneCo T2.4）；ingest 本來就不算向量（見 [[envelope-契約]] 打標分工），第一版連打標執行端都還沒接，先跑萃取本身。
+- 模型測試集（中文 + 人類暗示樣本、轉回歸測試）為 deferred（SDD T3.3），先跑預設。
+
+## 實體
+
+- **品質門檻白名單** — 模型須萃得出深層暗示+中文過關才入選的把關機制。
+- **淺萃**（shallow tier／Workers AI／預設 Haiku）— 便宜快速的預設萃取層，走 API。
+- **深萃**（deep tier／Claude via CC）— 較貴較準的萃取層，淺萃失敗時升級，走月費。
+- **JSON-fail 升級閘** — 淺萃解析失敗或過稀時自動升 deep 的閘門。
+- **選意圖非型號** — 用戶像 /model 那樣選萃取意圖、而非指定具體模型的選擇方式。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- JSON-fail 升級閘 >> 觸發升級到 >> 深萃
+- 淺萃 >> 升級為 >> 深萃
+- 品質門檻白名單 >> 把關 >> 選意圖非型號
+### 卡片關係（卡對卡）
+- [[extract-模型策略]] >> 屬於路徑B於 >> [[採取優先於萃取]]
+- [[extract-模型策略]] >> 產物送進 >> [[envelope-契約]]
@@ -0,0 +1,41 @@
+---
+tags: [掛載架構, 架構設計]
+gloss: kbdb-ingest-plugin 在 KBDB 堆疊裡的位置——掛在 graph 上、graph 掛在 base 上的最薄餵食器層。
+---
+# 掛載架構
+
+← [[ingest/00-INDEX]]
+
+**來源**：`CLAUDE.md`、`README.md`、`docs/3-specs/ingest-pipeline/design.md`
+**最後更新**：2026-06-26
+
+## 摘要
+
+KBDB 是三層堆疊：base 管儲存、graph 管三元組領域與查詢、ingest 是最薄的餵食器，只透過 API 往上一層 POST 候選。
+
+## 重點
+
+- 三層由下而上：`base KBDB（arcrun/kbdb）` 管儲存（D1 三表 + CRUD API）→ `kbdb-graph-plugin` 管三元組領域 + 圖查詢，並開 `POST /triplets/ingest` 寫入端 → `kbdb-ingest-plugin`（本 repo）純餵食器：拉 + 採取/萃取 + 跨庫織網。
+- 每層只透過上一層的 **HTTP API** 互動，不碰其內部結構。ingest 只打 graph 的寫入端，從不直連 base。
+- ingest 內部資料流：SourceAdapter（GitHub 拉 + content-hash，`source.uri = github:owner/repo@path`）→ 採取或 extract → 跨 repo 匯總織網 → POST envelope。
+- **無環**：graph 永不回呼 ingest。觸發只能從下游發起方向之外（webhook/排程，或 KBDB MCP `refresh` 代轉），下游圖層不主動驅動上游餵食器。
+- 命名只養一個品牌 Arcrun，本元件功能名當水管：`ingest`。
+
+## 實體
+
+> 本卡關鍵實體（graph node）。
+
+- **kbdb-ingest-plugin**（本 repo／餵食器）— KBDB 堆疊最薄一層，純 POST 候選 envelope 給 graph、不碰儲存。
+- **kbdb-graph-plugin**（graph 層）— 三元組領域與圖查詢層，對 ingest 開 `POST /triplets/ingest` 寫入端。
+- **base KBDB**（arcrun/kbdb／基本盤）— 最底儲存層，D1 三表 + CRUD API，ingest 與 graph 都不繞過它直碰表。
+- **SourceAdapter** — ingest 內部從 GitHub 拉 repo 並算 content-hash 的元件。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- kbdb-ingest-plugin >> 掛載於 >> kbdb-graph-plugin
+- kbdb-graph-plugin >> 掛載於 >> base KBDB
+- kbdb-ingest-plugin >> POST候選給 >> kbdb-graph-plugin
+- SourceAdapter >> 隸屬於 >> kbdb-ingest-plugin
+### 卡片關係（卡對卡）
+- [[掛載架構]] >> 受約束於 >> [[envelope-契約]]
+- [[掛載架構]] >> 展開為 >> [[採取優先於萃取]]
@@ -0,0 +1,39 @@
+---
+tags: [ingest管線, 萃取策略, 架構設計]
+gloss: ingest 取得三元組的兩條路徑——優先「採取」本地 CC 已建好的三元組，無則才自己「萃取」裸原文。
+---
+# 採取優先於萃取
+
+← [[ingest/00-INDEX]]
+
+**來源**：`CLAUDE.md`、`README.md`、`docs/3-specs/ingest-pipeline/{requirements,design}.md`
+**最後更新**：2026-06-26
+
+## 摘要
+
+ingest 拿三元組有兩條路：路徑 A 採取（拉本地已建好的）優先，路徑 B 萃取（自己萃裸原文）是 fallback。
+
+## 重點
+
+- **路徑 A 採取（優先）**：repo 用了 system-dev-template、本地 CC 已建好三元組 + gloss → ingest 直接拉取，不重萃。
+- **路徑 B 萃取（fallback）**：裸原文、本地沒三元組 → ingest 自己 extract 出候選 (s,p,o) + gloss。
+- **為什麼採取優先**：知識連結長在「生產的當下」（local CC 有 LLM Wiki 指引、有完整脈絡），本地萃成效更好；下游 ingest 只有單檔/跨庫視角，臨時補的 gloss 會貼不合（＝胡扯）。所以 gloss 與三元組同階段由 local CC 建，不留給 ingest 補。
+- 兩路共同收斂到：跨 repo 匯總 → 織跨庫關聯 → POST envelope。**跨庫織網才是 ingest 不可取代的主職**（見 [[跨repo織網]]），採取/萃取只是取得素材的前段。
+- extract 的模型與品質細節見 [[extract-模型策略]]。
+
+## 實體
+
+- **採取**（路徑 A／拉）— ingest 直接拉本地 CC 已建好三元組+gloss、不重萃的取得方式。
+- **萃取**（路徑 B／extract／fallback）— 本地無三元組時，ingest 自己從裸原文萃出候選 (s,p,o)+gloss。
+- **gloss** — 一句話描述某 node 是什麼，供下游 base embed normalize 同義詞用。
+- **system-dev-template**（精耕模板）— 讓 local CC 在知識生產當下建好三元組+gloss 的模板，決定一個 repo 走採取或萃取。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- 採取 >> 優先於 >> 萃取
+- 採取 >> 依賴於 >> system-dev-template
+- gloss >> 產出於 >> 採取
+- 萃取 >> 退而求其次補 >> gloss
+### 卡片關係（卡對卡）
+- [[採取優先於萃取]] >> 細節見 >> [[extract-模型策略]]
+- [[採取優先於萃取]] >> 服務於 >> [[跨repo織網]]
@@ -0,0 +1,37 @@
+---
+tags: [ingest管線, 掛載架構, 觀點主張]
+gloss: ingest 的主職與護城河——匯總多 repo 三元組、織出單一 repo 本地看不到的跨庫橋與異見。
+---
+# 跨 repo 織網
+
+← [[ingest/00-INDEX]]
+
+**來源**：`CLAUDE.md`、`README.md`、`docs/3-specs/ingest-pipeline/requirements.md`（R4）
+**最後更新**：2026-06-26
+
+## 摘要
+
+採取/萃取只是取素材；ingest 真正不可取代的價值，是匯總多個 repo 的三元組、織出單一 repo 在本地看不到的跨庫關聯。
+
+## 重點
+
+- **為什麼本地做不到**：單一 repo 的 local CC 只看得到自己庫內的知識；跨庫的「橋」（A 庫概念連到 B 庫概念）和「異見」（兩庫對同一概念說法相左）唯有把多 repo 三元組匯到一處才浮現。這是 ingest 的主職，不是採取/萃取的附屬。
+- **命題（護城河）**：不是「更好的 notes RAG」（紅海），而是**跨所有 vault 的圖**——Obsidian/Logseq 結構上做不到的那層。護城河是累積的圖，不是這份程式碼。
+- 織網發生在採取/萃取**之後**、POST envelope **之前**的匯總階段（見 [[掛載架構]] 資料流）。
+- 與「無環」「純 API」並存：織網是 ingest 端的運算（准），結果仍只透過 [[envelope-契約]] POST 給 graph，不碰儲存。
+
+## 實體
+
+- **跨repo織網**（跨庫織網／主職）— 匯總多 repo 三元組、織出跨庫橋與異見的 ingest 核心職責。
+- **跨庫橋**（bridge）— 一個 repo 概念連到另一 repo 概念的跨庫關聯，單庫本地看不到。
+- **跨庫異見** — 兩個庫對同一概念說法相左之處，匯總後才浮現。
+- **跨所有 vault 的圖**（護城河）— ingest 的命題：累積的跨庫圖，而非程式碼本身，才是護城河。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- 跨repo織網 >> 浮現出 >> 跨庫橋
+- 跨repo織網 >> 浮現出 >> 跨庫異見
+- 跨repo織網 >> 構成 >> 跨所有 vault 的圖
+### 卡片關係（卡對卡）
+- [[跨repo織網]] >> 接續於 >> [[採取優先於萃取]]
+- [[跨repo織網]] >> 輸出走 >> [[envelope-契約]]
@@ -0,0 +1,25 @@
+# CC 已知誤解 + 避坑方法
+
+> 做新功能前讀一遍。
+> 格式：每條必須有症狀 + 正確做法 + 原因。
+
+---
+
+## 快速檢查清單（做任何事前）
+
+- [ ] 有對應 SDD 嗎？沒有 → 停手
+- [ ] 這次修改會影響哪些模組？有沒有連帶破壞？
+- [ ] 驗收標準是什麼？有客觀證據嗎？
+
+---
+
+## 誤解記錄
+
+（初始化時為空，隨專案進行 append）
+
+格式：
+⚠️ MISTAKE: [錯誤描述，一句話]
+   症狀: [CC 通常怎麼表現這個錯]
+   正確做法: [應該怎麼做]
+   原因: [為什麼會錯]
+   日期: [YYYY-MM-DD]
@@ -0,0 +1,20 @@
+# principles — 跨全局設計原則（push：CC 行動前必服從）
+
+> 這個檔由 hook 在 session 開始**全文注入**，讓 CC 設計任何東西前都先看見這些準繩。
+> 為什麼 push 而非寫成 card：原則是「會被遺忘的盲區」——沒推到眼前，CC 設計時很可能沒想到要服從就做了。
+>
+> 規則：**一行一條**，精煉成準繩（不是長篇論述）。≤15 條；超過代表某些該合併、或下放成 card。
+> 發現新的跨全局原則 → append 一行。累積原則只改這個檔，**不必問用戶開新檔**。
+> 區分：原則 = 反覆適用的準繩（這裡）；單次選擇 = 決策（寫成 card）；踩過的坑 = mistakes.md。
+
+---
+
+## 原則
+
+- **純餵食器，不碰儲存**：ingest 只 POST 候選 envelope 給 graph 寫入 API；不直連 base、不碰 D1/Vectorize/任何表。牆是「儲存」不是「運算」（准 LLM 萃取、不准碰儲存）。
+- **不算向量 normalize**：ingest 只「打標」哪些 node/謂詞要 embed，實際 embedding 歸 base embed 模組「讀標執行」（單檔視角算不準跨庫同義）。
+- **不帶查詢 MCP**：ingest 是 ambient 餵食器，沒人互動「問」它；只帶薄 ops CLI（人手動觸發重萃），重萃觸發由 KBDB MCP `refresh` 代轉。
+- **三守則（無環/純 API/凍結契約）**：graph 永不回呼 ingest；只走 graph HTTP 寫入端不碰其內部；`contracts/ingest-candidate.json` 是唯一耦合面。
+- **部署繞 GitHub Actions**：走 wrangler 部署（被 flag 教訓）；runtime 用 GitHub API/webhook 拉 repo 是 runtime 行為、不衝突。
+- **採取優先於萃取**：用了 system-dev-template 的 repo 有本地已建三元組+gloss → 直接拉取，不重萃（本地生產當下建的連結品質更好）。
+- **不污染用戶根目錄**：工具產物收進專屬資料夾，不在用戶根目錄撒檔。
@@ -0,0 +1,23 @@
+# 當前狀態
+
+> 更新時間：2026-06-26
+> 每次 session 結束必須更新此檔。
+
+---
+
+## 正在做
+
+repo 骨架階段（SDD tasks T0）。已有：CLAUDE.md（上游指針+鐵律）、README、`contracts/ingest-candidate.json`（凍結契約）、SDD 三件式骨架（`docs/3-specs/ingest-pipeline/`）、wiki 記憶系統（本輪 /wiki-init 完成）。`src/`、`tests/` 仍空。
+
+## 下次 session 第一件事
+
+接 SDD tasks T0.5：建 `package.json` / `tsconfig` / `wrangler.toml`（參考 kbdb-graph-plugin）。之後進 T1 SourceAdapter（GitHub 拉 + content-hash）。
+
+## 待負責人確認
+
+（無）
+
+## 已知問題
+
+- ⏸ T5.1 POST envelope 依賴 graph `POST /triplets/ingest` 寫入端（InkStoneCo T3，待 graph repo 實作）。
+- ⏸ embed 依賴 base vectorize（InkStoneCo T2.4）。第一版不 embed 可先動。