system-dev-template/CHANGELOG.md

# 更新紀錄 CHANGELOG

> 每次改了什麼，都記在這。版號對應 `template/.claude/VERSION`。
> 想更新到最新版？看 [README → 一鍵更新](README.md#-已安裝舊版一鍵更新)。

版號規則（語意化版本，簡化版）：
- **大版號**（1.x → 2.x）：破壞性變動，舊專案更新後可能要手動調整。
- **中版號**（1.0 → 1.1）：加了新功能，向下相容，更新即用。
- **小版號**（1.1.0 → 1.1.1）：修 bug、改文件，無新功能。

---

## 1.19.0 — 一套模板，兩種身分：總管版與成員版

**這一版你會多出什麼**

- **裝的時候可以選「這是什麼」**：`--profile=repo`（實際寫程式的專案）或
  `--profile=orchestrator`（管一群專案的上層資料夾）。不選就自動偵測、問你一次，
  之後記住不再問。**兩種身分讀到的規則完全不同**——總管版看不到技術細節那一套，
  成員版會帶一行指回上游。
- **CLAUDE.md 從此分成兩區**：上面是「模板維護的」、下面是「你自己寫的」，
  中間有看不見的分隔標記。以前這兩者混在一起，導致更新**永遠不敢覆蓋**，
  模板後來改的規則就送不到你手上。現在上面那區可以安全更新，下面那區永遠不動。
- **更新會告訴你「哪些檔被手改過」**：改過的**不覆蓋**，新版另存 `.new` 讓你自己比對。
  （實測一個真實使用中的專案：6 支模板 hook 裡 **4 支已被手改**，而在這之前
  沒有任何機制知道這件事——那 4 支從此收不到任何修正。）
- **PM 那一套工作方法有了現成範本**（總管版才裝）：白話需求卡、使用者旅程與考題、
  以站為單位的衝刺表、能力域分派表。填了之後更新永遠不會覆蓋你的內容。
- **多了六道自動攔截**，全部是「做錯的當下就擋」而不是事後提醒：
  - 寫程式的人**改不了驗收考題**（改考題就能「通過」的漏洞堵住了）
  - 當 PM 的**寫不了程式、改不了任務清單**
  - 專案**改不了模板發下來的機制**（要改就回上游提案，一次修好所有人的）
  - 需求卡如果是「賭注」卻沒寫對帳日 → 擋
  - 新任務沒說它服務哪一站 → 擋
  - 給人看的文件混進技術術語 → 擋
  - 動了程式 → 主動告訴你要重驗哪幾題
- **收工的判準換了**：不再是「任務都關了」，而是「**指定的那幾站考題全綠**」。

**修掉的老問題（都是靜默失敗，你不會收到錯誤訊息的那種）**

- **新安裝的人拿不到最近三版的招牌功能**：安裝和更新各有一份手抄的檔案清單、
  早就對不上——更新會裝的四個檔，安裝從來不裝。**先裝舊版再更新的人反而拿得比較多。**
  現在兩邊讀同一份清單，這種漂移在結構上不可能再發生。
- **更新會被「找不到頁面」騙**：以前只檢查「下載回來的檔案不是空的」，
  但錯誤頁面也不是空的 ⇒ **好檔案被無聲覆寫成一行垃圾**（曾經有份文件從 260 行變 1 行）。
- **更新遇到新資料夾會失敗，但版本號照升**（典型的假成功，半年前就被記下來、一直沒修）。

**給模板維護者**

- 安裝清單改成資料表（`template/manifest/*.tsv`），加產物 = 加一行，不必改腳本
- 兩道機械閘：範本混入特定專案名 → 擋；已發佈的檔案路徑被搬走 → 擋
  （後者防的是「舊版使用者更新時整排失敗，而且不會有下一次更新來修它」）
- `git config core.hooksPath .githooks` 啟用 commit 前自動檢查

---

## 1.18.0 — 提醒你「改好的東西還沒發佈出去」

> 📌 補記於 2026-08-06：這一版當時發佈了（版號升了、功能也出貨了），
> **但漏了寫這則紀錄**。而更新跑完的最後一行正是叫你「改了什麼看 CHANGELOG.md」——
> 版號動了卻查不到動了什麼，等於沒交代。依實際 commit 內容補回。

**這一版你會多出什麼**

- **開啟工作階段時，會告訴你「公開版落後了」**：
  草稿區與公開區是**手動同步**的，改完東西若沒人記得發佈，
  外部使用者抓到的還是舊版——**而且不會有任何錯誤訊息，只是行為不對**，
  所以自己人永遠測不出來。這個提醒就是來消滅「忘了發佈」這個失敗模式。
- 如果這批改動含編譯產物，會**額外標紅**（因為安裝器是直接去公開位址抓那個檔的）。
- **只提醒、不阻擋**——發不發佈是人的決定。

---

## 1.17.0 — 查詢一律從最強的查法開始（語意 → 關鍵字 → grep）

**leo 2026-07-21**：「它一定是用最好的搜尋，如果沒有才 fallback，
**但那不是你要指定的**——對搜尋者來說，我就是要去搜尋，如果你沒這個機制才降。」

**事故**：查「CF 上的 git 託管」時只用 grep，搜 Gitea/freeze 等字面詞 → 零命中，
結論寫成「這件事沒查過、申請表沒送」＝指控負責人沒做他早就做過的事。
事後用**同一個問題**跑語意搜尋，**第一筆就命中**（score 0.858）：
「Cloudflare Artifacts：假設內建 git 倉庫機制的 CF 功能，成立則可全 CF 化」，
還帶出三元組「Artifacts >> 若提供 git 倉庫則可取代 >> Gitea」——負責人 15 天前就記了。

**根因不是「關鍵字選錯」，是「用了三種查詢裡最弱的那種」**——
grep 只認字面，**要求你先猜對那個詞**；語意搜尋不需要你猜對。

修正：
- `subagent-wiki-guard`：注入的指示改為**分級查法**——
  ①語意搜尋（`kbdb_search mode=semantic`，用自然語言問句）②關鍵字 ③grep（最後手段）
- `wiki-first-search`：① **grep 零命中不再靜默退出**（那正是最該改用語意搜尋的時刻，
  查不到 ≠ 沒記載，只代表沒猜中用詞）② 有命中時明說「這是最弱的查法、
  搜尋詞是猜的，重要判斷請補語意搜尋」
- 兩處都附真實案例，讓讀到的人知道代價

---

## 1.16.1 — 補破口：wiki-first-search 漏掉 Bash（隔天就被自己繞過）

**1.16.0 上線隔天即實證失效**：hook 只掛 `Grep|Glob|Read`，但「用 curl/wrangler
亂試部署方法」走的是 **Bash** → 整支 hook 不觸發。

leo 當場點破：「昨天我已經發信給你看了，你今天還說系統不對，**就表示這件事沒記錄下來？
還是你凡是要查就會去查 wiki？**」
→ 查證：wiki `status.md` 早記著「landing 寄信 live、實測 leo21c 連 4 次成功」，
**記錄在、我沒查**；而昨天做的 hook **蓋不到我實際用的工具**。

修正：
- matcher 加 `Bash`；只認會動外部系統的高風險指令
  （`wrangler|curl|npx|acr|gh|deploy|push`），避免每個 `ls` 洗版
- 從指令中取最具識別度的詞當搜尋詞（濾掉 https/accounts/workers 等雜訊）
- `update.sh` 對**既有註冊**就地補 `Bash`（不只新裝才有）

> 教訓：**防「跳過 wiki」的機制，本身要蓋到所有實際查詢途徑**，
> 否則就是換個工具照樣跳過。

---

## 1.16.0 — 讓 wiki 真的被讀到：查詢即搜尋＋subagent 自動注入

**病根（leo 2026-07-20 點破，真實事故）**：總管三次擋回 leo「某機制早已棄用」的正確判斷，
查證後 leo 全對。根因不是知識不足，是**讀取流程**：
① wiki 只讀開頭就開工（關鍵記載在第 56 行，答案一直在那裡）
② 派 subagent 只叫它讀 code、沒叫讀 wiki → agent 從稿子推論，**必然**得出過時結論
③ 把 wiki 的「當時狀態」當永久事實（沒核對解除條件）

leo：「我需要的不是你記住，而是如何解這題不再發生，**機制面的解法**」
「如果你不是讀而是**搜尋** wiki，就不會只讀 50 行就下定論，而是像 cmd+F 那樣高亮。」

**新增兩支 hook（皆不依賴任何人自覺）**：

- **`wiki-first-search.sh`**（PreToolUse: `Grep|Glob|Read`）
  在「正要去翻 code/文件」的當下，用同一組關鍵字 grep `system-dev/wiki/`，
  **只推命中行**（非開場 push 全文——那必然只被讀開頭）。提醒不阻擋：
  wiki 沒記載時本來就該翻原文，唯一目的是消滅「不知道 wiki 有寫」。

- **`subagent-wiki-guard.sh`**（PreToolUse: `Task`）
  偵測查證/實作類任務 → **注入**「先查 wiki」指示給 subagent。
  ⚠️ 第一版設計為「上游 prompt 沒交代就擋下」，經 leo 指正改為注入式：
  「subagent 的問題跟你一樣——**它只要聽到查，就應該主動查 wiki**，
  因為每個 repo 都有維護自己的 wiki。」依賴上游記得寫指示 = 同一個病。

**安裝行為**：`update.sh` 除同步兩支 hook 外，**自動註冊進 settings.json**（不只提醒）。
理由同上——靠人看提醒手動補，等於把同一個病搬到安裝環節。

**注入給 subagent 的三條硬規則**：
1. wiki 與程式碼衝突 → **以 wiki 為準**，回報衝突，不自行用 code 推翻 wiki
2. wiki 寫「不可動／待廢除／進行中」→ 讀它的**解除條件**逐條核對（那是當時狀態，非永久禁令）
3. 翻原文後得到新結論 → 回報「wiki 該更新」（wiki 過時是債，要還）

---

## 1.15.0 — SDD 生命週期鐵律：單一活性 SDD（issue #6）

leo 拍板全體系採「單一活性 SDD」制度：任何時刻每個 repo 只有一份現行 SDD（`status: active`），所有開發任務唯一對應它的 tasks。prompt 軟約束＋檔案系統硬約束（hook）雙層。

- **新增 `system-dev/docs/3-specs/SDD-LIFECYCLE.md`**：規則真相源。frontmatter 狀態標記（`active | draft | paused | closed` + `superseded_by`，機器可查）＋五條鐵律（單一活性／禁止 CC 自建 SDD／規格變更只有 pending-changes.md → confirm 一條路／開新 SDD 先逐條搬舊任務才准寫 code／session 開始回報「現行規格＋未完成任務 N＋待裁決 proposal M」三數字）。
- **新增 `system-dev/docs/3-specs/pending-changes.md`**：規格變更緩衝區骨架（待裁決／已裁決留底）。update 走 `add_if_missing`——proposal 是用戶資料，絕不覆蓋。
- **TEMPLATE-sdd/design.md 掛 frontmatter**：`status: draft` 起手，原「> 狀態：」blockquote 移除（被 frontmatter 取代）。
- **`sdd-guard.sh` 升級**：① active >1 → **不論寫什麼檔一律 exit 2**（先收斂）② 寫 code 檔需「恰好 1 份」active，=0 擋並指向 SDD-LIFECYCLE.md ③ **向下相容**：3-specs 下沒有任何 design.md 帶 frontmatter（老 repo 未遷移）→ 退回舊行為（有 design.md 就放行＋提醒補標記），避免 update 後老 repo 立刻全紅；統計一律排除 archive/ 與 TEMPLATE（否則 update 鋪新 TEMPLATE 就誤判已遷移）。
- **新增 `template/scripts/sdd-active-check.sh`**：獨立硬約束，pre-commit / CI 可掛（掛法見檔頭），active >1 → 列清單 exit 1。下游落地 `system-dev/scripts/`。
- **`/sdd-check` 加「生命週期」段**：五條鐵律摘要＋session 開始三數字回報格式＋「兩份 active＝違規，當場糾正」。
- **template/CLAUDE.md 絕對鐵律更新**：指向 SDD-LIFECYCLE.md，濃縮五條。
- install / update 均鋪齊新檔（SDD-LIFECYCLE.md、pending-changes.md、sdd-active-check.sh、新版 hook），杜絕 1.12 時代「update 不補新檔→結構斷層」（issue #13 教訓）。
- 誠實限制不變：hook 只擋語法層明顯違規，繞道可行但留痕可審，不聲稱不可繞過。

---

## 1.14.0 — vault 萃取能力：raw Logseq 筆記 → system-dev/wiki（知識一庫 ingest 前段；issue #5）

筆記 vault（Logseq graph 如 `notes`/`kb`、或 Obsidian）只有原文、需要萃。新增可**重跑、冪等**的 vault 增量萃取，把原始筆記萃成 `system-dev/wiki/` 的精耕卡＋`[[wikilink]]`，供下游 Arcrun ingest 從 wikilink 機械拉三元組進 KBDB。**AI 只產卡片檔，不寫 KBDB、不拉三元組**（那是下游的事）。

- **新增 `/wiki-extract` 命令**（`template/.claude/commands/wiki-extract.md`）：vault 專用的增量重萃入口，給 Routine / cloud-worker 反覆跑。跟 `/wiki-init`（一次性首萃）分工——首萃後 vault 持續進新筆記，改用這支做增量。跑它的是 CC/Routine＝LLM 本人，**不需任何 token**。
  - **content_hash 冪等**：讀 `system-dev/wiki/.extract-manifest.json`，逐檔比 sha256；hash 沒變的檔**完全不進 AI**（先擋、不是讀了才發現）。**重跑沒變動的 vault ＝ 零 AI 呼叫、零 diff**。省 run。
  - **卡片格式不重造**：完全沿用 `/wiki-init` 第五步（frontmatter tags/gloss、`## 實體`、`## 關聯` typed-edge、麵包屑、TAXONOMY 受控標籤）——讓 dev repo 與 vault repo 產出同一種卡，下游一套 ingest 通吃。
  - **原文唯讀 + D16**：只寫 `system-dev/wiki/`，`journals/`/`pages/` git status 須 0 異動（改了會被 Syncthing 推回 leo 手機污染筆記）；精耕知識點、不地毯灌全文。
- **新增 Logseq 任務 marker 解析（單一真相源）**：`template/system-dev/docs/4-guides/logseq-markers.md`。Logseq 原生任務是**大寫 marker** block（`- TODO …`／`- DOING …`／`- DONE …`），**不是** GFM `- [ ]`；只抓 checkbox 會漏抓 notes/kb 全部任務（leo 2026-07-04 發現，issue #4 更正）。狀態映射：TODO/LATER→`todo`、DOING/NOW→`in-progress`、WAITING→`blocked`、DONE→`done`、CANCELED/CANCELLED→`closed`；跳過 `:LOGBOOK:…:END:` 與 `key:: value` 屬性行。**這份是唯一權威**——vault 萃取（#5）與 tasks→Project 投影（#4）**共用同一套解析，不各寫一份**。marker → 任務卡 frontmatter `task_status`。
- install/update 隨 WIKI 模組帶下 `/wiki-extract`；`logseq-markers.md` 放共用區，wiki 或 sdd 任一模組在用都拿得到。
- ⚠️ **邊界**：本能力只產 `system-dev/wiki/` 卡片給下游機械撈；三元組拉取、KBDB 寫入歸下游 Arcrun ingest（另立 issue），不在此。頂層 SDD：`kb-ingest-architecture`（R1 AI 只萃／R2 萃冪等／R5 Logseq 正確性歸 template）。

---

## 1.13.0 — tasks.md ⇄ GitHub Project 單向投影（optional 模組，需 Arcrun；issue #16）

裝了 SDD 的專案可把 `system-dev/docs/3-specs/*/tasks.md` 的待辦**單向投影**成唯讀 GitHub Project（看板/dashboard 好抓）。md 唯一真相源、Project 永遠唯讀，不存在反向同步、不會兩個真相源打架。

- **新增投影 workflow**：`template/system-dev/workflows/tasks-project-sync.yaml`（Arcrun workflow：`foreach` 增量 → `switch` 動作 → `http_request` 零件打 GitHub API：新 task→issue create / `[ ]→[x]`→close / 文字改→edit / 行刪→archive，並投影進 Projects v2）。auth 走 `{{creds.github_token}}`（acr creds push）。**每個 component 經 `acr parts` 核實存在**（防複發：registry 沒有 `github` 零件，用 `http_request` 打 REST/GraphQL）。`acr validate --offline` 通過。
- **新增本地觸發端**：`tasks-project-sync.local.sh`——因 Arcrun workflow 跑在遠端 CF Workers、沒本地 fs/git，「讀 tasks.md / git diff / 回寫 `<!-- gh:id -->`」由本地端做完再 `acr run` 餵增量。職責邊界清楚：本地一半 + 遠端一半。
- **啟用判準＝對話 + 能力，不掃檔**：原設計想抄 `HAS_WIKI`/`HAS_SDD` 掃檔指紋，但 Arcrun workflow 存遠端 KV、零本地檔也能在用 → 掃檔會 false negative。改成裝/init 時 CC 問一句「要不要同步」→ 查環境有沒有 Arcrun（mcp/`acr`）→ 有就 `acr push` 啟用、沒有就**一次性溫和廣告**、答不要就閉嘴。**帶檔 ≠ 啟用**。
- **守 flag 紅線**：push 後本機觸發單次，禁定期輪詢、禁 GitHub Actions fan-out。
- **預設不逼**：沒裝 Arcrun／答「不好」的用戶完全 no-op，純 md 不受影響。
- install/update 隨 SDD 模組帶下 workflow 檔（`add_if_missing`，覆蓋不會關掉誰的同步——啟用狀態存遠端）。
- ⚠️ **端到端（`acr push` 真部署 + `acr run` 真投影）待 leo21c 驗證**；本版為 code-done 骨架，GitHub Projects v2 GraphQL 的欄位細節真部署時可能微調。SDD：`docs/3-specs/tasks-project-projection/`。

---

## 1.12.0 — 跨 repo issue/comment 署名鐵律：`[<本 repo> CC]`（issue #12）

當生態系裡多個 repo 共用**同一個 GitHub 帳號**發 issue/comment 時，author 全顯示同一帳號、看不出是哪個 repo 的 CC 發的。GitHub 沒有 per-repo 身份設定，`git config user.name` 只影響 commit、不影響 issue/comment author，多開帳號又會踩「避免被 flag」鐵律——身份只能在**內容層**自報。

- **`/issue-handle` 新增第 3 節「跨 repo 署名（鐵律）」**：跨 repo 的 issue/comment 開頭一律署名 `[<本 repo> CC]`（如 `[graph-plugin CC]`、`[mira CC]`），下令角色用 `[InkStoneCo 總管]`；署名放第一行或標題式開頭。靠內容溯源，不靠平台。
- **第 1 節「讀/回/結案」comment 範例帶上署名**：讓署名在最常用路徑就被看見，不只躲在後面的鐵律節。原「flag 安全界線」節順延為第 4 節。
- 規則寫在 skill 內文（非 CLAUDE.md，導航牌不增長），所有 repo 透過 template 繼承；下游 repo 下次 `update` 即取得。

## 1.11.0 — 採集規範升級：三元組抓內文實體關係 + `## 實體` 區塊（issue #11）

從 Logseq vault 183 卡落地暴露：現行三元組只示範「卡對卡」（既有雙鏈加動詞、資訊量沒增加）；gloss 只描述卡標題一個 node，內文實體無處放描述。本升級只談採集端（卡片該寫什麼），ingest 端另立 kbdb-ingest-plugin#1。對應 SDD：wiki-architecture。

- **三元組改抓內文實體關係**：`原子筆記 >> 對立於 >> 傳統筆記`（A/B 是內文概念非卡標題）；卡對卡只是其中一類。
- **卡片新增 `## 實體` 區塊**：集中列內文關鍵實體 `正規名（同義詞）— 一句描述`，供下游 embedding normalize（內文實體也是 graph node、也需描述句）。集中放、不縮排、不重複（生產者是 AI 不會邊寫邊漏）。
- **`## 關聯` 拆兩層**：內文知識關係（端點裸文字，對應實體表）+ 卡片關係（卡對卡 `[[]]`）。內文端點裸文字避免 Logseq 紅色斷鏈。
- **★ 端點硬自檢（Haiku 量產護欄）★**：端點必須與 `## 實體` 正規名一字不差，寫完逐條比對。實證：光寫規則 Haiku 略過、端點對不齊 14 條；寫成自檢動作後 14→0。跑 12 張才暴露的盲點。
- **謂詞限定動詞、禁名詞**：否則 Haiku 寫出 `>> 存儲格式 >>` 讀不通的名詞謂詞。
- 兩路徑同步：SKILL.md（Cowork）+ wiki-init.md（CC）。

## 1.10.1 — install 防重複安裝：已裝過一律導去 update（杜絕 wiki 並存）

實測踩到：一個裝過舊版的專案，「先跑 install、發現裝過、再跑 update」→ install 先在 system-dev/ 建了空白範本，update 的遷移看到「目的地已存在」就冪等跳過 → 真資料卡在舊 .claude/wiki/、空殼佔新位置，兩套 wiki 並存內容不同。

職責切分：**install 只管全新安裝，一切已裝過的後續（更新/遷移/補新檔）歸 update。**

- **install 防呆**：偵測「裝過沒」（system-dev/ 或 .claude/wiki/ 或 .claude/VERSION 任一存在，不分新舊版）→ 不動任何東西，導去 update 並 exit。從源頭杜絕「重複 install 製造並存」。
- **update 偵測並存**：migrate_dir 遇「目的地已存在但舊位置仍有真資料」→ 警告 COEXIST「並存需合併」，不靜默跳過、不自動合併（絕不覆蓋用戶資料），引導叫 CC 逐檔合併。
- install↔update 互相導向（update 遇全新專案也導回 install），閉環無死結。

## 1.10.0 — wiki 資訊架構：push/pull 判準 + principles（原則）push 檔

從「用戶所有檔案一律改寫成 wiki」的新前提，用 **push（CC 行動前必主動看見）vs pull（按需檢索）** 重新推導 wiki/ 每個檔的存廢——因為 wiki 主要是給 AI 看的，判準是「CC 做事時會不會被動看見」，不是分類美學。對應 SDD：wiki-architecture。

- **新增 `principles.md`（push 全文）**：收「跨全局設計原則」（如不污染用戶根目錄、目標用戶 low-code）。原則是「會被遺忘的盲區」——沒推到眼前 CC 設計時不會服從。一行一條、≤15 條，累積只改此檔不開新檔。
- **mistakes 改 push 摘要**：session-start hook 注入標題清單+一行症狀，全文按需展開（量大不撐爆 context）。
- **decisions-summary 降級為 cards + INDEX 決策視圖**：決策是知識內容＝card；既有的保留相容。
- **INDEX 升級為「多角度視圖」的家**：標籤角度、決策角度…新增角度只改 INDEX 一節，不開實體檔、不問用戶。
- **session-start hook 三類 push**：principles 全文（最前）→ status 全文 → mistakes 標題；principles >15 條警告。
- install.sh 補 principles download；update.sh 新增 `add_if_missing`（舊用戶升級補範本、已有則保留不覆蓋）。
- push/pull 判準寫進 wiki-init.md 與 SKILL.md，CC/Cowork 共用。

## 1.9.3 — 遷移後 CLAUDE.md 殘留舊路徑：hook 偵測並提示 CC 代修

升級到 1.9.x 後 wiki 已搬到 system-dev/，但 update.sh 鐵則「絕不碰 CLAUDE.md」（用戶資料），導致 CLAUDE.md 內仍寫舊路徑 `.claude/wiki/`，CC 照它找錯位置（KB 端升級後發現）。

- session-start-recall.sh 加偵測：wiki 已遷移、但 CLAUDE.md 內還有 `.claude/wiki` → 接關後附帶提示，請 CC 主動幫使用者把 CLAUDE.md 的舊路徑改成 system-dev/（raw source 宣告的 `docs/` 保留不動）。
- 由 CC 代改而非腳本盲 sed：避免誤傷用戶自寫內容、不破壞「絕不碰 CLAUDE.md」鐵則。

## 1.9.2 — 修 SKILL.md「typed-edge 三元組」整節重複貼兩次（issue #10）

加 gloss 節時複製貼上沒清掉舊段，`### 使用 typed-edge 三元組` 在 SKILL.md 出現兩次、byte-identical（KB 端讀 skill 時發現）。

- 刪掉重複的第二份，保留第一份（在卡片模板+架構說明之後，順序合理；gloss 節緊接其後）。
- 兩個來源檔同步修：`docs/SKILL.md` 與 `template/system-dev/docs/SKILL.md`。

## 1.9.1 — 修舊版（1.8.x）升級到 1.9.0 撞 404 + VERSION 被污染

1.9.0 把 VERSION 從 `template/.claude/VERSION` 搬到 `template/system-dev/VERSION`，但 1.8.x 舊用戶**本機的** update.sh 寫死抓舊路徑 → `curl` 對 404 會把「404: Not Found」當內容回傳（非空），舊腳本沒驗證就把它寫進 `.claude/VERSION`，畫面顯示 `Latest version: 404:NotFound`、且第一次跑不會遷移（要再跑一次）。

- **發佈源保留相容墊片** `template/.claude/VERSION`：讓 1.8.x 舊腳本仍抓得到版號、不再 404。（bump 時與 `system-dev/VERSION` 同步）
- **新版 update.sh 加版號格式驗證**：`REMOTE_VER` 必須像 `X.Y.Z`，否則（404 字串／HTML 錯誤頁／空）一律視為「取不到」，永不寫進 VERSION。未來任何路徑變動都不會再污染版號檔。
- 提醒：照 README 那行 `curl … main/scripts/update.sh | bash` 升級的人本就抓遠端新腳本、一次遷移成功不受影響；只有手動跑**本機舊** `bash scripts/update.sh` 才會遇到，這版一併修掉。

## 1.9.0 — 安裝結構收進 `system-dev/`（不再污染用戶根目錄）+ 舊版自動遷移

工具產物原本散在用戶根目錄（`docs/` 七層、update 時的 `scripts/`），又把 `wiki/`、`VERSION` 寄生在 CC 原生的 `.claude/` 裡，用戶分不清「哪個 docs 是工具的、哪個是我的」。這版徹底收斂：除了 CC 死綁的 `.claude/`（settings/commands/hooks）和 `CLAUDE.md` 留根，**工具所有資料收進 `system-dev/`**。對應 SDD：`system-dev/docs/3-specs/install-layout/`。

- **新結構**：`system-dev/{VERSION, wiki/, docs/, scripts/}`。`.claude/` 只剩 CC 機制檔。
- **wiki 改寫產物落點正式化**：install 直接建 `system-dev/wiki/cards/`（含 `.gitkeep`），不再讓用戶自己長出來、自行 git init。
- **docs 雙語義拆開**：工具文件 → `system-dev/docs/`；**用戶 raw source（原始文件來源）維持原處**（用戶的 `docs/`、Logseq `pages/+journals/`、Obsidian vault），工具只讀、不搬。
- **scripts 一開始就裝**：install 把 install.sh/update.sh 放進 `system-dev/scripts/`，之後更新直接 `bash system-dev/scripts/update.sh`。
- **舊版自動遷移（雙保險）**：① update.sh 偵測舊位置 → 冪等搬進 `system-dev/`（wiki 含 `cards/` 與內含 `.git` 一起搬，docs 只搬工具白名單、不動用戶自填內容）；② session-start hook 偵測到舊結構未遷移 → 出聲提示，CC 可當場代為遷移。給「只會叫 CC 做事」的 low-code 用戶兜底。
- **機敏防護路徑跟進**：`wiki-secret-scan.sh` 觸發路徑改 `system-dev/wiki/**`（否則新結構下寫入不啟動、防護失效）。
- 全套路徑引用同步更新：CLAUDE.md、SKILL.md、wiki-init、wiki-recall、wiki-capture、sdd-check、sdd-guard、session-start-recall、INDEX、decisions-summary、README（中英）。

> **升級提醒**：舊用戶跑一次 `update.sh` 即自動遷移；沒跑也會在開 session 時被 hook 提示。屬向下相容的中版號（非破壞性手動遷移）。

## 1.8.2 — 修 update.sh 在 `curl | bash` 下崩潰（bash 3.2 多位元組字元，1.7.0 漏修到的同類 bug）

1.7.0 修了 install.sh 的「多位元組字元旁變數要用 `${VAR}` 包」，但 update.sh 第 54 行漏網：
`已是最新版（$LOCAL_VER）` 的中文全形括號緊貼裸變數 `$LOCAL_VER`，`curl | bash` 串流在多位元組
邊界切斷時，bash 3.2 把後續位元組誤當變數名 → `LOCAL_VER�: unbound variable` 崩潰。偏偏觸發點在
「本機版本＝遠端版本」分支，所以「以為沒更新、再跑一次」必中。

- 第 54-55 行 `$LOCAL_VER` → `${LOCAL_VER}`。已用 bash `set -u` 模擬該分支驗證不再崩。

## 1.8.1 — 補裝 Cowork 的 wiki skill（`docs/SKILL.md`）+ CLAUDE.md 加 wiki/gloss 導航

發現 Cowork（claude.ai）整理 wiki 的規則檔 `docs/SKILL.md`（含 typed-edge、frontmatter 標籤、**gloss**）**從來沒被安裝到用戶端**：install.sh 沒下載它，連 `template/docs/` 發佈源都缺這檔 → claude.ai 來掃時身上沒任何 wiki 規則。同時 CC 平時讀的 CLAUDE.md 沒指向採集規則，導致「CC 說找不到 gloss 指引」。這版把兩條路徑都補上。

- **補發佈源**：`template/docs/SKILL.md` 新增（從根 docs 同步），install.sh 才有得下載。
- **install.sh**：wiki 模組加一行下載 `docs/SKILL.md`。
- **update.sh**：加 `update_file docs/SKILL.md`，舊專案更新會帶上（規則檔，可覆蓋）。
- **CLAUDE.md 模板**：新增「整理 wiki 的方法」導航段，明示 CC（`/wiki-init`）與 Cowork（`docs/SKILL.md`）的採集規則所在地，gloss 不再「藏」在指令內文裡讓 CC 找不到。

## 1.8.0 — wiki 採集加「萃 gloss」（每個 node 一句說明，供下游語義 normalize）

下游 KBDB 要做語義 normalize：對「entity 名 + gloss（一句說明）」一起 embedding 求相似度自動歸一同義詞。但本地 wiki 採集只萃三元組、沒萃 gloss。原則是 gloss 該在知識生產當下由 local CC/Cowork 建（下游只有單檔／跨庫視角編不出好 gloss），不留給下游 ingest 臨時補。（issue #9）

- **卡片 frontmatter 加 `gloss:`**：每張卡＝一個 entity/graph node，補一句機器可 normalize 的定義句。
- **選填、deep tier 才產**：淺萃不浪費；deep 改寫時每卡補一句。
- **gloss ≠ 摘要**：`gloss` 是 frontmatter 給機器的定義句，`## 摘要` 是給人讀的核心句，兩處兩用途。
- **對齊下游 envelope**：`gloss:` 對應 ingest envelope 的 `nodes[].gloss`，ingest 直接取用。
- **兩條路徑同步**：`wiki-init.md`（CC）與 `docs/SKILL.md`（Cowork）都加上，產出一致。

## 1.7.0 — install/update 雙語化 + 修 macOS bash 3.2 安裝崩潰

非台灣使用者看不懂中文安裝訊息（`curl | bash` 出來整片中文），加上 macOS 內建 bash 3.2 在 `set -u` 下會崩。這版一起修：

- **修崩潰**：`install.sh` 在 macOS bash 3.2 下會噴 `VAULT_TYPE…: unbound variable` / `SKIPPED[*]: unbound variable`。根因是 bash 3.2 + `set -u` 展開「空陣列」會炸，加上一行多餘的 `${SKIPPED[*]}` no-op。修法：空陣列展開前先檢查、移除廢行、多位元組字串旁的變數一律用 `${VAR}` 包好（避免 `curl | bash` 串流在多位元組字元邊界被切斷而誤判變數名）。
- **install/update 訊息雙語**：依 locale 自動選語言，**預設英文**（`curl | bash` 常是 `LANG=C`，外國人預設就看得懂），`zh_TW` 自動切回繁中。
- **寫進 CLAUDE.md 的 raw source 宣告也雙語**：依 locale **只寫一種語言**進 CLAUDE.md（雙語會讓每個 session 的 context 更滿）。
- **修措辭**：一般開發案不再顯示誤導的「偵測到 vault 類型：docs」。偵測到 logseq/obsidian 筆記庫 → 出聲「會保留你的筆記結構」；不是筆記 → 默默裝完。
- **README 多語**：新增 `README.en.md`，頂部繁中 ↔ English 切換連結，利於被搜尋到。

## 1.6.1 — 釐清 taxonomy 是「受控擴充」非「凍結」

1.6.0 把標籤字典寫成「禁止自創」，措辭過嚴：碰到現有軸裝不下的新內容時，會逼 AI 硬塞錯標籤或偷偷自創，兩者都比受控擴充差。改成正確的機制：

- **禁止的是「繞過字典在卡片直接冒新標籤」，不是「新增標籤」**。字典**可擴充**。
- 流程：遇到裝不下的內容 → ① 先查既有（是真新軸還是同義詞？`知識管理` vs `KM` 別重造）→ ② 確實是新軸才登記進字典（附定義）再用。不必停下來問人，但「先查重再登記」不能省。
- **字典是 per-repo**：跨 repo 引擎靠各 repo 自己一致的 taxonomy 接合，不是逼所有 repo 共用一份。
- **新增領域軸要慎**（影響全庫聚類），形態軸擴充較安全；不確定就先用最接近的並註記「待人類複核」。

同步 `wiki-init.md`、`docs/SKILL.md`、`TAXONOMY.md` 三處措辭。

---

## 1.6.0 — wiki 完整規劃方式（183 卡實證）：三層架構 + frontmatter 標籤 + 多層索引（issue #8/#6/#7）

在一個中文 Logseq vault（234 篇 pages + journals → 183 張原子卡、571 條 typed-edge）完整跑了一輪 LLM Wiki，把「對 AI 最優」的規劃方式定案。一次納入 `wiki-init.md` 與 `docs/SKILL.md`（CC / Cowork 兩路徑一致）：

**新增**
- **三層 + 標籤橫切架構**：頂層 `INDEX.md`（標籤視圖）→ `cards/<bucket>/00-INDEX.md`（桶子索引）→ 概念原子卡。資料夾只是儲存桶，**分類由標籤承載**，不繼承原稿目錄。
- **frontmatter 標籤分類**（issue #8）：分類走 frontmatter `tags:`，不靠資料夾、不靠行內 `#tag`——內文常用 `#`（如 `#猜想`），行內標籤會讓下游 ingest 分不清「分類」與「內文範例」污染 graph。雙軸 taxonomy（領域 + 形態）寫進新檔 **`TAXONOMY.md`** 當字典，**禁止自創標籤**。
- **桶子索引固定名 `00-INDEX.md`**（issue #6）：`00-` 排序最前、一眼可辨，AI 載入任何桶一律先讀它。
- **麵包屑帶路徑 wikilink**（issue #7）：卡片 H1 次行 `← [[<bucket>/00-INDEX]]`。固定名 `00-INDEX` 跨桶撞名，故指它一律帶路徑；卡片間連結仍用裸 `[[卡名]]`。
- **新檔 `template/.claude/wiki/TAXONOMY.md`**：標籤字典範本。install.sh `download_if_missing`、update.sh `keep_file`（使用者客製，永不覆蓋）。

**踩坑警語寫進 wiki-init**
- subagent 改寫時會誤把卡寫進 raw source → 目標一律給絕對路徑到 `cards/<bucket>/`，事後 `git status --short pages/ journals/` 驗證原文 0 異動。
- 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。
- 量大用 Haiku 並行改寫，主模型只切概念邊界 + 審稿 + 修斷鏈。

---

## 1.5.0 — wiki 連結升級成 typed-edge 三元組（issue #5）

**背景**：`## 關聯` 原本只列裸 `[[頁面]]`（沿用 Karpathy LLM Wiki）。但裸 `[[A]]` 是**弱連結**——只說「A 和本卡有關」，沒說關係是什麼。下游要從 wiki 抽 knowledge graph 時，拿到一堆無類型 edges，仍得回讀兩張卡才知道關係，等於關係沒被預編譯、退回 O(N²)。

**變更**
- `wiki-init.md` 與 `docs/SKILL.md` 的 `## 關聯` 升級成 **typed-edge 三元組**：`[[A]] >> 謂詞 >> [[B]]`。下游 ingest 可直接 parse 出帶類型的有向邊，全局 graph 不必再讀卡片內容就知道關係。
- 規則：① 方向性——`A >> 謂詞 >> B` 須讀成「A（謂詞）B」一句通順的話，順序＝主→賓真實方向；② 謂詞用動詞/動詞短語（天然帶方向）；③ 謂詞自由書寫不受控詞彙（下游 embedding 會聚類同義謂詞，但方向靠書寫順序保證）；④ 向後相容：純 `[[A]]` 仍合法（無類型邊）。
- `>>` 為分隔語法，repo 可自選符號，全程一致即可。

---

## 1.4.1 — wiki = AI 改寫的記憶（拿掉索引模式）+ 量大建議 Haiku（issue #4）

**修正 1.4.0 的方向**：1.4.0 把「索引 vs 改寫」做成兩種並列模式，預設一般專案走索引、只有 vault 走改寫。這方向錯了——

> **記憶系統的目的是讓 AI 之後讀得快。** 不管 vault 還是一般開發專案，人類原文都是亂的（重複、流水帳、半成品）。若 wiki 只是指回原文的索引，每次未來用都得重新解析那團亂＝沒省到。**wiki 的價值就在「改寫一次，之後每次讀都便宜」。**

**變更**
- `wiki-init.md` **拿掉索引模式**，改寫成 wiki 是**所有專案的唯一預設**（vault 與一般開發一致）。原文＝唯讀 SSoT，wiki＝AI 改寫過的記憶，AI 是總編輯。
- 唯一例外：原文是不可改動的正式文件（簽署規格／法規／合約，須逐字讀）才用指針指回原文並註明「逐字依原文」。
- **量大建議用 Haiku**：逐份原文改寫成 wiki 格式是重複、機械、判斷成本低的工作，正適合 Haiku。原文數量多時，命令會主動建議派 Haiku subagent 並行改寫，主模型只負責切概念、定條目邊界、審稿與互連。
- `INDEX.md` 範本：統一成「概念索引指向 wiki 內部條目」，不再提索引模式。

---

## 1.4.0 — wiki-init 新增「草稿改寫模式」：AI 當總編輯（issue #4）

**背景**：在 Logseq vault（234 篇 pages + journals）壓測 `/wiki-init`，發現它整套指令語言只有「分類歸檔／導航」，把人和 AI 都導向做出一個 `[[原文檔名]]` 指回原文的**索引**。但 PKM / vault 使用者的心智模型常是相反的——原文只是**草稿**（轉錄稿、隨手記），要 AI **改寫萃取成自包含 wiki**，之後讀 wiki 就好、不必回原文。template 沒區分這兩種，且預設了「原文是成品」。

**新增**
- `wiki-init.md` 開頭新增**模式分岔（第零步）**：索引模式 vs **草稿改寫模式（AI 當總編輯）**，附對照表講清楚原文角色、INDEX 連結、回答方式的差異。
  - **偵測到 PKM vault（Logseq/Obsidian）→ 預設草稿改寫模式**，但明確問一句讓使用者可切回索引模式。
  - **一般專案 → 預設索引模式**（維持原行為，向下相容）。
- 草稿改寫模式的產出規則（第五步）：概念原子化、自包含、保留來源指針（可追溯但不必回讀）、`[[wikilink]]` 互連——與 claude.ai Cowork 的 `docs/SKILL.md` 改寫邏輯**一致**，CC / Cowork 兩條路徑產出同一種 wiki。
- `INDEX.md` 範本：草稿模式下改成「概念索引」指向 wiki **內部**改寫條目，而非指回原文。

**不變**：raw source 永遠唯讀，兩種模式都只往 `.claude/wiki/` 寫，絕不搬移/改名原文。

---

## 1.3.1 — 修：update.sh 不再覆蓋客製的 pre-write-guard.sh（issue #3）

**修正**
- `scripts/update.sh` 原本把 `pre-write-guard.sh` 列在「覆蓋更新」區，**無條件**用模板空殼蓋掉。
  但此檔的定位是「使用者手填的 guardrail 客製檔」（CHANGELOG 1.2.0），下游通常已塞滿自己的 enforcement，
  且 `update_file` 覆蓋**無 `.bak` 備份**——跑一次 update 等於無聲關掉整套 guardrail（如 Arcrun 的 KNOWN_SDDS 白名單、薄殼原則強制等數百行）。
- 改法（issue 建議方案 1）：新增 `keep_with_template()`，把 `pre-write-guard.sh` 移出覆蓋區。
  **原檔永不覆蓋**，改把最新模板版另存成 `pre-write-guard.template.sh` 旁邊，更新結尾印出 `diff` 指令供使用者自行採納。
  首次安裝（原檔不存在）才會直接抓本體。`install.sh` 路徑本就用 `download_if_missing`（已存在即跳過），無此問題。

---

## 1.3.0 — vault 偵測（Logseq / Obsidian）+ Cowork 整理 skill

**新增**
- `install.sh` 在建立 `CLAUDE.md` 前**自動偵測資料夾類型**，把對應的「原始文件來源（raw source）」寫進 `CLAUDE.md`：
  - `logseq/` → raw source `pages/`、`journals/`
  - `.obsidian/` → raw source 根目錄下所有 `.md`
  - 都沒有 → `docs/`（維持原行為）
  寫入的宣告是給 AI 讀的指令，對 vault **明令不得搬動/改名/重新分類 `.md`**，整理結果一律只寫進 `.claude/wiki/`，
  面對筆記 vault 不會破壞它原本的結構。已有 `CLAUDE.md` 一律不覆蓋，改在結尾列出該補的宣告提醒手動貼。
- `docs/SKILL.md`：給 **claude.ai Cowork** 的 `wiki-cowork-scan` skill。
  與 CC 的 `/wiki-init`、`/wiki-capture` 共用同一套規則，用**與 install.sh 一致的偵測邏輯**掃描
  `~/Documents` 下所有裝了本模板的資料夾，只讀 raw source、只往 `.claude/wiki/` 增補（不覆蓋、不刪除），
  絕不動 raw source、`CLAUDE.md`、`logseq/`、`.obsidian/`、`assets/`。讓整理 wiki 不再只限終端機裡的 CC。

**變更**
- README 新增「不只程式碼，也認得 Logseq / Obsidian vault」「Cowork 也能整理 wiki」兩節，並更新目錄樹。

---

## 1.2.0 — GitHub issue 指引 + pre-write-guard 定位釐清

**新增**
- `/issue-handle` slash command（`template/.claude/commands/issue-handle.md`）：
  CC 處理 GitHub issue 的普世指引，三層界線——
  ①讀/回/結案自己 repo 的 issue（直接做）；
  ②發 issue 給別的 repo（先問人，不擅自）；
  ③**禁止掛 Actions/cron/webhook 自動輪詢 issue**（會觸發 GitHub 異常偵測、被 rate limit）。
  屬共用指引，install/update 不分模組都裝。（issue #1）

**變更**
- `pre-write-guard.sh` 釐清定位（issue #2）：它是「按需手填的空插槽」，不是裝上就生效的警察。
  - 檔頭明講：**有 CC 在場時，直接叫 CC 寫貼合的 guard hook 更好**，這個空殼範本只對「手動 DIY」用戶有價值。
  - 解決安全錯覺：install.sh / update.sh 安裝它時提示「預設不攔任何東西，要手填+掛 settings 才生效」，
    讓用戶不會誤以為裝了就有保護。（hook 執行時維持安靜，避免每次 Write 洗版。）

---

## 1.1.0 — 一鍵更新

**新增**
- `scripts/update.sh`：已安裝舊版的人，一行指令更新到最新版。
  只覆蓋模板/邏輯檔（hooks、commands、TEMPLATE-*），**完全不碰**使用者資料
  （`wiki/status.md`、`mistakes.md`、`decisions-summary.md`、`.wikiignore`、`settings.json`、`CLAUDE.md`）。
  會先比對版本、列出新功能、依已裝模組自動偵測該更新什麼，跑完自我更新。
- `template/.claude/VERSION`：版本基準檔，讓「檢查新版」有依據。
- `CHANGELOG.md`（本檔）。

**第一次更新的雞生蛋問題**：舊版本機還沒有 `update.sh`，所以第一次靠 README 那行
`curl` 從遠端抓更新器來跑；跑完它把自己裝進 `scripts/update.sh`，之後直接跑本機的即可。

---

## 1.0.0 — 模組化安裝（基準版）

此版本之前無 VERSION 檔，以下為依 git 歷史回溯的功能基準。

- `scripts/install.sh` 模組化安裝：`--wiki` / `--sdd` / `--all`，無參數則互動詢問。
- **LLM Wiki**：CC 記憶系統（INDEX / status / mistakes / decisions-summary）
  + 接關 hook（session-start-recall）+ 對應 slash commands。
- **wiki 機敏防護三層**：`.wikiignore`（檔案層）＋行內標記（局部）＋
  `wiki-secret-scan.sh`（機械兜底攔截）。
- **SDD 強制**：動 code 前必須有 `design.md`，由 `sdd-guard.sh` hook 把關，附 TEMPLATE 範本。
- docs 分類結構（1-vision ~ 6-user）與 ADR 範本。