ISEP 0.1.0：環境設定收成一個 plugin，本機與雲端共用一份

leo 2026-08-20：「同一個 plugin 你用，薄殼也用，保證兩邊同步」
              「我要你幫雲端做薄殼，永遠都有問題，你要做的就是這組設定
                你自己可以 dogfooding」

搬進來：41 支 hook（51 條註冊）／7 支 command／2 支 skill／23 支腳本。
不搬 .env、wiki、docs——那些是知識不是環境。

51 條 hook 路徑全部從 $CLAUDE_PROJECT_DIR/.claude/hooks/ 改成 ${CLAUDE_PLUGIN_ROOT}/hooks/，
零漏網。那正是薄殼一直壞掉的根：雲端 cwd 不是真身，寫死路徑就斷。

尚未驗證：Claude Code 能不能從私有 Gitea repo 裝 marketplace（要憑證）。
下一步就是在本機實際裝一次，通了才動雲端 bootstrap.sh。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

commands/cp-write.md

@@ -0,0 +1,306 @@
+---
+name: cp-write
+description: |
+  要寫或改任何 CP（Critical Path）檔案之前必讀——動 system-dev/docs/3-specs/critical-paths/
+  底下任何檔案、標記某關卡 ✅/◐/❌、或新增一條 CP 時自動載入。
+  leo 2026-07-30：「上次已經跟你討論一次並且寫了正確範本，立刻全部忘光了」。
+  三條鐵律：寫目的不寫功能／每步交出 deliverable／code 寫完沒部署不准標 ✅。
+  另含 Logseq outliner 格式（給 leo 讀的 md 一律巢狀 bullet、禁表格平攤）。
+---
+
+# /cp-write — 寫或改一條 CP（Critical Path）
+
+**要動 `system-dev/docs/3-specs/critical-paths/` 底下任何檔案之前，先跑這個。**
+
+---
+
+## 為什麼有這支 skill
+
+leo 2026-07-30：「你去把寫 cp 的方法寫成 skill，**上次已經跟你討論一次並且寫了正確範本，立刻全部忘光了**。」
+
+- **忘光的機制**（結構問題，不是記性問題）
+  - 規範住在 `TEMPLATE-critical-path.md`（209 行）
+  - CC 不會在動筆前主動讀 209 行文件 → 憑印象寫 → 寫成功能清單
+  - 「該讀的文件存在」≠「會被讀到」
+- **同一天內 leo 糾正四次**
+  - 「不是有定義 CP 的寫法？outliner，步驟，有關任務」
+  - 「你不要再去寫一個個功能，**要寫的是目的**，每次交出 deliverable」
+  - 「上次說過，CP 有順序的跟無序的兩種」
+  - 「CP 每個步驟要拉哪些任務，**不是自己編一堆新任務**…你去搜尋先前的你寫的範本」
+- ⇒ 規範要在**動筆那一刻**被載入，不是躺在檔案裡等人想起來
+
+---
+
+## 六條鐵律
+
+違反就是寫錯，不是風格問題。
+
+### 1. 寫目的，不寫功能
+
+> leo：「你不要再去寫一個個功能，要寫的是目的，達成那個目的，**每次交出 deliverable**，而不是交出一個程式碼打勾就完成了。」
+
+- ❌ 錯：「`/cypher/search` 接 registry」
+- ✅ 對：
+  - **目的**：AI 拿到的答案必須是真的——假信號比沒答案更糟
+  - **交付物**：查詢回應含 found/missing/unknown，found 附 input_schema
+- **檢查法**：每步唸出來，聽起來像「我要改哪個檔案」→ 重寫成「達成什麼、交出什麼」
+
+### 2. 從 tasks 池子撈任務，不在 CP 裡編新任務
+
+> leo 2026-07-30：「**如果在這裡編任務，不就是廢掉了原本的 SDD，那到底要照 SDD 做事還是照 CP？**」
+
+🔴 **2026-08-10 leo 定調：CP 只標編號，不重抄條目。原話——**
+
+> 「CP 寫大計劃，加上描述，然後在 issues 寫明，**在 CP 標示 issue 編號**，
+>   如果是在 issue 的內部 MD，一樣寫 `issue #2, task #?`，在 issue 從**標題層級**來找，
+>   只要能 mapping 某 task。CP 一向就是寫計劃，把所需的 task 標示，**避免同一條目重抄一次**。」
+
+> leo 2026-08-10（同日補充，這句是骨架）：
+> 「**SDD 的 tasks 指向 issues，CP 的 tasks 指向 issues，永遠管理 issues。**」
+
+- **三層，只有一層可寫**
+  ```
+  SDD tasks ──指向──┐
+                    ├──▶  issue  ← 唯一管理處（勾選／s/* 狀態／執行細節／往返對話）
+  CP  tasks ──指向──┘
+  ```
+  - **issue＝任務池子**（`issue-handle` 2026-08-09 定調）：任務本體、勾選、狀態都只住這裡
+  - **SDD＝規格與設計**（為什麼要做、怎麼做）；它的 tasks 是**指向 issue 的清單**，不自己養 checkbox
+  - **CP＝大計劃＋排序**（現在先做哪些）；寫目的與描述，任務只放**編號 pointer**＋`w=`
+- **⇒ 兩邊都只是視角，動狀態一律回 issue。**
+- 🔴 **CP 裡不准出現 `- [ ]` / `- [x]`**——checkbox 就是「在發號」，而 CP 不發號
+  - 要知道做到哪 → 去看票。CP 只回答「這一步通不通」（三態）
+  - **同一條目寫兩次 = 兩份真相 = 必然漂移**（2026-08-10 實錯：CP 四筆停在事發前的世界，
+    issue 那邊才是對的；總管花一整輪在對帳）
+- **定址：指到「一張票」，不指票裡的某一行**（D58，leo 2026-08-10）
+  > leo：「**充分利用 gitea 的機制，不要硬做個不支援的機制，容易出錯。**」
+
+  Gitea 原生就會把 issue 引用自動變成可點連結 ⇒ **CP 不必手貼網址、不必造錨點。**
+
+  ```markdown
+  - `w=9` Leo/arcrun-rag#52 — 重裝到已有資料的帳號，登入與資料庫一起壞
+  ```
+
+  - 🔴 **最好用的判準**：**需要指到票裡的某一行 ＝ 那張票該拆了。**
+    這個限制反而**強迫出正確的顆粒度**
+  - **票的刀口不是「大小」，是「狀態」**：問「它會不會需要跟隔壁那條不同的狀態？」
+    會 → 獨立成執行票；不會 → 留在該票裡當 checkbox
+  - **討論票 vs 執行票**：討論票是脈絡（不當工單追），執行票才是 CP 該指的東西
+  - ⚠️ **已作廢：隱形錨點 `<a id="tNNN">`**（D53，同日上線同日推翻）——**不要撿回去**。
+    它整段推理嚴謹，**但沒有先問「這個平台原生支援嗎」**。
+    造任何機制前先問：「原生支援嗎？」「不支援是不是在說我方向錯了？」
+- **自檢**：CP 上任何一行任務，拿它的編號去票裡找得到唯一一條嗎？
+  - 找不到 → 你違規了。要嘛去票裡補，要嘛從 CP 刪掉
+  - **絕不能留在 CP 裡當「CP 專屬任務」**
+- **`w=` 的正確用法**（leo 原話）
+  - 「從**很多任務**中找到跟現在目的**最近**的是誰，**把它排序到前面**」
+  - 「**w 是標在 task 裡，這個任務原本在 SDD 的 tasks 中，跟現在的優先級有關，我把它拉出來到前面**」
+  - ⇒ `w=` 的意思＝**這個 task 原本躺在 SDD 池子裡，因為跟當前目的相關，被拉到前面**
+  - ⇒ 是池子任務**互相比較**後的排序，**不是對單一任務憑感覺打分**
+  - ⇒ 同一步內的任務**依 `w=` 由高到低列**，高的先做
+  - 🔴 **`w=` 只能標在任務表的任務上，不能標在步驟標題上**
+    - leo 2026-07-30：「這個只是標題，不是從 SDD 拉出來的，**它的 w 是跟誰比是 9?**」
+    - 【有序】卷的每步都是必經 ⇒ **不需要排序** ⇒ 標了就是假數字
+    - 【無序】卷的並列項才需要 `w=`（那時它們互相比較，有意義）
+  - 🔴 **`w=` 只排順序，不決定誰進 CP**——進 CP 的門檻是鐵律 5 的反事實測試（最小待辦）
+
+> leo：「**tasks 是一個任務池子，CP 是編訂 sprint 的原則。**」
+
+- **動筆前先做兩件事**
+  - 看先前範本：`system-dev/docs/3-specs/autonomy-dispatch/sprint-2026-07a.md`
+    （里程碑表 ＋ `P1>P2>P3` 任務板，做法一致，別重新發明）
+  - 撈池子＝撈 issue（不是 grep `tasks.md` 的 checkbox，那份已經只是 pointer 了）：
+    ```bash
+    TOKEN=$(git remote get-url gitea | sed -E 's|.*//[^:]+:([^@]+)@.*|\1|')
+    curl -s -H "Authorization: token $TOKEN" \
+      "https://git.uncle6.me/api/v1/repos/Leo/<repo>/issues?state=open&labels=s/todo"
+    ```
+    - 🔴 **不帶 token 打私有 repo 回 `{"message":"not found"}`**，長得像「這裡沒東西」
+      （2026-08-09 實錯：據此把 24 個 open issue 宣告成不存在）
+- **怎麼列**：一律 outliner 清單（鐵律 6），**必要資訊是「編號 ＋ 一句話 ＋ w ＋ 執行者」**：
+  ```markdown
+  - `w=9` #2 task 3 — 讓 notify_leo 重新發得出訊息
+  - `w=7` #2 task 7 — 👤 leo：拿你知道答案的東西查一次
+  ```
+  - 🔴 **沒有 checkbox**（鐵律 2，leo 08-10）——要看做到哪去點那張票
+  - 🔴 **一句話是「指路」不是「複製」**：只寫到足以認出是哪一條，
+    細節、實測輸出、踩到的坑**一律留在票上**
+  - 🔴 **不用表格**（leo 07-31 拍板，見鐵律 6）——07-30 曾說「寫表格也可以」，已被此裁定取代
+- **撈不到才是真缺口** → **去開票**（或在既有票裡加一條 task），然後 CP 標它的編號
+  - 在**票**裡加，**不在 CP 裡加**
+- **為什麼特別容易忘**：CP 看起來像 todo list，很自然就在裡面寫「我要做 A、B、C」
+  - 那樣做 → 同一任務在票與 CP 各一份 → 必然漂移 → 兩邊都不可信
+  - 2026-08-10 實錯：CP 四筆停在事發前的世界（已完成的還空著、已解除的還標危險），
+    而票那邊是對的。總管花一整輪對帳，leo 當場問「**我到底要看什麼？**」
+
+### 3. 每步有可執行的驗法
+
+- 沒有驗法的步驟不算數——那是「宣告完成」的溫床
+- 驗法要是**可執行的動作**（跑什麼指令、看什麼回應），不是「檢查是否完成」
+- **考試三要素必須定義**（leo 2026-07-31：「誰主動、誰被動、正確答案是什麼，這些角色你沒有定義」）
+  - **考生（主動）／受測物（被動）／正確答案**——三者寫在每步的「考試角色」行
+  - **考不過＝迭代受測物**，不改題目、不怪考生
+    - 受測物是環境（指引/引導）→ 考不過改環境（例：步驟 1「我給它一個環境它考不過，就是我的環境要迭代」）
+    - 受測物是系統 → 回應不正確改系統（例：「haiku 給它一個需求回應不正確，就是系統要迭代」）
+- **有前端的關，`HTTP 200` 不算驗過**
+  - 要抓實際畫面內容：`curl <網址> | grep <該出現的字串>`
+
+### 4. 用 PM 的態度定狀態：**deliver 才算通，不是我實測過就算**
+
+> leo 2026-07-30：「最終不是要實測，**是要 deliver**，你在本地實測完沒推沒 deploy 也用不了，
+> **最後要讓收的人可以實測**，你要抱着 **PM 的態度**，不是開發者的態度。」
+
+- **判準只有一句**：**收的人現在能不能自己驗到？** 不能 → 沒通
+  - 「收的人」＝leo／封測者／下一個 AI，看這條 CP 服務誰
+- 三種狀態
+  - `✅ 通` — **收的人已經驗到了**（貼他驗到的證據，不是我的）
+  - `◐ 半通` — 我這端做完且驗過，但**還沒到收的人手上**；必須標明「卡在哪一段運送」
+  - `❌ 斷` — 沒接上／沒發佈／沒人能用
+- 🔴 **開發者態度 vs PM 態度**（開發者會說 → PM 要追問）
+  - 「`tsc` 零錯誤、測試綠」→ 部署了嗎？
+  - 「commit 了」→ push 了嗎？
+  - 「push 了」→ 收的人拿得到嗎？（要不要重裝／解保險）
+  - 「部署成功」→ 他點下去看到對的東西嗎？
+- **運送鏈缺一段就不算通**：改完 → commit → push → 打包 → 部署 → **收的人重裝／重連** → 他驗到
+  - 反覆的失敗模式：registry 機制完整但沒觸發／`acr search` 寫好沒發佈／
+    ingest 通了沒人餵／daemon 修好但 leo 手上還是舊版
+  - 每件都「做完了」，**收的人手上沒有**
+
+### 5. 拉的是「最小待辦」（MVP），不是「相關任務清單」
+
+> leo 2026-07-31：「CP 是要達成這個目標而**從池子裡拉出的最小待辦**，
+> 如果不做這些也通過，就表示這些任務不屬於最小待辦。」
+> 「最小待辦類似 **MVP** 概念——如果有 500 個任務，全部做完要很久，但現在要的是最小待辦。」
+
+- **成員資格測試（反事實）**：拉任務進 CP 前問一句——
+  「**不做這個，該步的驗法（考試）會不會掛？**」會掛才進。
+  只是「跟目的相關」不夠：**相關 ≠ 必要**。
+- **步驟驗法通過時，逐筆對帳還沒完成的**，三選一（leo 原話給的處置）：
+  1. **評估出錯** → 檢討選任務的方法（寫進 mistakes.md）
+  2. **移出 CP，以後完成**（票留著照常排，CP 刪掉那行 pointer）
+  3. **已無需要** → 回票上結案
+  - 🔴 非必要任務掛在 CP 上會**稀釋整個儀表板的訊號**——leo 看 CP 判「還差多遠」
+- 🔴 **勾選一律回票上做，不在 CP**（鐵律 2，leo 08-10）
+  - 舊版寫「做完就勾」（leo 08-01），指的是**別把做完的事留白**——那個意圖沒變，
+    只是**勾的地方換了**：從 CP 換到票
+  - CP 這一側對應的動作＝**該步的三態現況要更新**（✅／◐／❌），那才是 CP 的本職
+- **要 leo 做的也是待辦**（leo：「如果有要我做什麼，這也是待辦，但**執行者是我**」）
+  - 🔴 **它必須是一張撈得到的票，不能只住 CP**（leo 08-10：「執行到要我 input 時要標示 Stage，
+    我去完成，**但 CP 的無法標示**」）
+    - CP 是 markdown，**沒有 label 可掛 ⇒ leo 的看板撈不到 ⇒ 對他等於不存在**
+    - ⇒ 人閘動作（arm／confirm／真機驗）一律**掛 `s/stage`**（規格見 `issue-handle`），
+      CP 這邊只留一行 `👤 leo` 的 pointer
+  - 標 `s/stage` **不等於交棒完成**——回覆裡要帶「打開什麼／該看到什麼／什麼算失敗」三件，
+    且指令自己先打過（`issue-handle` 有全文）
+  - 並同步 status「待 leo」清單＋每日催辦——不是只寫在對話裡
+  - 🚚 「合主線／發版／部署／等 arm」＝**運送殘項**，另起一行標 🚚，不佔任務位
+  - 🔴 **一筆待辦只准一個執行者**（leo 07-31：「這不是一個任務，是 2 個，
+    兩個主詞不同怎麼寫在一起？」）——主詞不同就拆成多筆，各自標執行者；
+    有先後依賴用「A 之後」寫在後筆開頭，不用「→」把兩人的事串成一筆
+- **踩雷實例（2026-07-31 arcrun-usable 步驟 1）**：掛了 4 筆 `w=` 高的任務，
+  一筆都沒做完、考試照樣 10/10 ＝全非最小待辦；而真擋 ✅ 的那筆
+  （安裝器 seed skills）**反而不在清單上**。
+  病根＝用「關鍵字相關度」順撈池子（語意相近的多半是同 SDD 的鄰居工單），
+  但真最小待辦常在**別的環節**（交付鏈／安裝器／人閘）
+  ⇒ **從驗法反推需要什麼，不從池子順撈相關的**。
+
+### 6. 格式＝Logseq outliner，不用表格
+
+> leo 2026-07-31：「我是個 Logseq 用戶……表格 + header 對閱讀不利，我看不出記錄彼此的層級，
+> 全部平攤。**全部用 logseq outliner，可以用 outline + header，不要太花，保持乾淨簡潔。**」
+> 「skill 寫明用 outliner，**不要一改版整個跑掉**。」
+
+- **層級用巢狀 bullet 呈現**，不用表格——表格把層級平攤掉，Logseq 讀不出結構
+- header 可以用，但只切大段（卷名／成功標準／六步／總驗收），不要每小節都開 header
+- 不要太花：emoji／粗體節制，狀態記號（✅◐❌／👤）保留因為有功能
+- 適用範圍：**CP、給 leo 讀的一切 md**（wiki、報告、交棒文件同此）
+- 🔴 此條取代 07-30「寫表格也可以」——**改版時不准把格式改回表格**，本鐵律就是防跑掉的錨
+
+---
+
+## 執行流程
+
+### 第一步 — 確認這是哪一條 CP
+
+```bash
+ls system-dev/docs/3-specs/critical-paths/
+cat system-dev/docs/3-specs/critical-paths/README.md
+```
+
+- **新主題要另立一卷**，不塞進既有卷（leo：「你只有一個，這樣太大了」）
+- **行數門檻**（07-30 實測後修正）
+  - 目標 **100 行內**；**上限 200 行**（六步以上的卷，池子任務表格本身就佔百餘行）
+  - 超過先問：**多出來的是「池子任務表格」還是「執行細節」？**
+    - 池子任務表格 → **留著**，那是 CP 的核心（拉任務＋距離）
+    - 執行細節／實測全文／糾正史 → 搬 `_evidence/`，CP 只留一行結論＋指針
+
+### 第二步 — 判斷【有序】還是【無序】，標在標題上
+
+- **【有序】** — 前步不通，後步沒意義
+  - 寫法：步驟 1→N 鏈狀；斷點按順序列、標「前置」
+  - 例：安裝→萃取→查詢→MCP／AI 想到→查詢→替換→執行
+- **【無序】** — 並列能力，各自算分
+  - 寫法：每項獨立標 `w=`／狀態；**不寫「前置」**
+  - 例：「知識可收集、可查、可追」＝三種能力並列
+- **判斷法**：把第 2 步拿掉，第 3 步還有意義嗎？
+  - 沒意義 → 有序
+  - 還有意義 → 無序
+- **可混合**：有序主鏈 ＋ 無序支線（支線另開一段標【無序】，別硬塞進鏈裡）
+
+### 第三步 — 每步寫四件事
+
+```markdown
+### 步驟 N｜<一句話目的>　`w=9`　◐ 半通
+
+**目的**：<達成什麼。沒參與的人也看得懂>
+**交付物**：<交出什麼可驗的東西。不是「改好某個檔案」>
+**驗法**：<可執行的動作。有前端要抓畫面內容>
+**現況**：<實測到什麼。附證據>
+
+**最小待辦**（鐵律 5：過反事實測試才進；要 leo 做的標 👤 leo）
+- [ ] <任務——出處 SDD>
+- [ ] 👤 leo：<人閘動作>
+
+**移回 SDD 池**（曾拉進來但驗證非必要的，留一行去向）
+```
+
+### 第四步 — 斷點與「不在 CP 上」
+
+- 🔴 斷點段（outliner，一行一斷點）：`- 步 N <斷點>——前置：<步>；<為什麼卡>`
+- ⚪ 不在 CP 上：`- <項目>（<為什麼不阻斷>）`
+  - **一定要寫**——不寫下來就會反覆被它吸走注意力
+
+### 第五步 — 進度數字
+
+- 卷尾一行：`**進度：N 完成／M 進行中／K 未做（共 T）**`
+- 有機械驗收（如 `verify.sh`）→ **以它為準**，並註明「此清單是人看的」
+
+---
+
+## 收工檢查
+
+逐條自問，答不出來就是沒寫完。
+
+1. 每步都是「目的＋交付物」，不是「改哪個檔案」？
+2. 子項是**從池子撈的**（有「出處」欄）？撈不到的標了 `➕ 待加 <SDD>`？
+3. 動筆前**看過先前範本**（`autonomy-dispatch/sprint-2026-07a.md`）？
+4. 標了【有序】／【無序】？
+5. 每步驗法**可執行**？有前端的抓了畫面內容？
+6. **有 `✅` 的，是「收的人驗到」的證據，不是我自己測過？**
+   - 運送鏈走完了嗎：改完 → commit → push → 打包 → 部署 → **收的人重裝** → 他驗到
+   - 缺任一段 → 最多 `◐`，且要標「卡在哪一段」
+7. 寫了「不在 CP 上」？
+8. 這一卷在 200 行內？超過的部分是「池子任務表格」（可留）還是「執行細節」（要搬）？
+9. **CP 檔真的改了**？（leo 07-26：「我看 CP 也沒用，因為你執行時沒去更新」）
+10. **每筆任務都過了反事實測試**（不做它驗法會掛）？要 leo 做的標了 👤 並進催辦？
+    驗法通過的步驟，空 checkbox 對帳完了（檢討／移回池子／標完成或刪）？
+11. **全卷 Logseq outliner、零表格**（鐵律 6）？層級縮排看得出來？沒有太花？
+
+---
+
+## 相關
+
+- 完整規範（含踩雷案例）：`system-dev/docs/3-specs/TEMPLATE-critical-path.md`
+- 分卷規則：`system-dev/docs/3-specs/critical-paths/README.md`
+- 先前範本（拉任務＋標距離）：`system-dev/docs/3-specs/autonomy-dispatch/sprint-2026-07a.md`
+- 執行細節該放哪：`system-dev/docs/3-specs/critical-paths/_evidence/`

commands/issue-handle.md

@@ -0,0 +1,346 @@
+---
+description: Gitea issue／milestone／看板的實際操作流程——issue 是 tasks 池、milestone 是 sprint、label 是狀態、看板是 leo 的畫面
+---
+
+# /issue-handle — issue 就是 tasks 池子（Gitea 版，2026-08-09 leo 定調）
+
+> 🔴 **本檔 2026-08-09 整份重寫。**舊版寫的是 GitHub ＋ `gh` CLI——
+> 那條路 D20 擋著（機器寫入 GitHub 要 leo 開閘），而真實世界早就在 **Gitea** 上。
+> `gh` 打不到 Gitea。**照舊版做會什麼都做不成。**
+
+## 世界觀（先讀這段，其餘都是它的細節）
+
+- **issue ＝ tasks 池子**——不管從哪來，所有要做的事都是 issue
+  - SDD 定案推導出來的、外面回報進來的、開發中才發現的，**三種都是 issue**
+  - 差別只在 body 裡標來源，不在「住哪裡」
+- **milestone ＝ sprint**（一次交貨）——**AI 建得了，所以 AI 管**
+- **project（看板）＝ 大目標的視覺**——**AI 建不了，leo 建、leo 拖**
+- **label `s/*` ＝ 狀態**——機器的真相住這裡，不住看板欄位
+- **CP ＝ 選擇 tasks 的指南**——決定「這次交貨先拿哪幾張」，**它自己不發號**
+- **wiki ＝ 過程、證據、為什麼**——引用 `#號`，不重複任務狀態
+
+> **一句話**：leo 拖畫面，AI 管資料。兩邊看同一批 issue，不各養一份清單。
+
+## 認證（最容易安靜出錯的一步）
+
+token 從該 repo 的 gitea remote URL 取，不另存：
+
+```bash
+TOKEN=$(git remote get-url gitea | sed -E 's|.*//[^:]+:([^@]+)@.*|\1|')
+```
+
+- 🔴 **不帶 token 打私有 repo 會回 `{"message":"not found"}`**——長得像「這裡沒東西」
+  - 2026-08-09 實錯：據此把 **24 個 open issue 宣告成不存在**，還寫了一份錯的提案
+  - ⇒ **「查不到」有兩種：真的沒有 vs 我沒權限看見。分不出來就不准下結論**
+- 分辨法：沒權限回 **JSON** `{"message":"not found"}`；路由不存在回**純文字** `404 page not found`
+
+## 三條標準作業流程
+
+- **① SDD 定案 → tasks 寫進 issues**
+  - `POST /api/v1/repos/{o}/{r}/issues`
+  - 🔴 `labels` 吃 **label id（int）**，傳名字會 422 ⇒ 先 `GET /labels` 拿 id
+  - body 標來源：`design 推導` ／ `修改自 #42` ／ `原生`
+- **② 外面進來的先驗傷，再決定要不要進 sprint**
+  - 新 issue **預設不掛 `s/`**，先用內建 `bug`／`question`／`invalid`／`duplicate` 分類
+  - 確認「要做、且屬於某次交貨」才掛 `s/todo` ＋ 掛 milestone
+  - ⇒ **不是每個 issue 都是 task**（查完是設定問題就 close，不進 SDD）
+- **③ 先決條件（issue 之間的關聯）**
+  - `POST /issues/{n}/dependencies`（我被誰擋）／`/issues/{n}/blocks`（我擋誰）
+  - 🔴 **body 是 `IssueMeta`，要三個欄位：`{"index":22,"owner":"Leo","repo":"arcrun-rag"}`**
+    - 只傳 `index` 會回 **404 `IsErrRepoNotExist`**（同 repo 也一樣要帶 owner/repo）
+    - 📌 這條原本是我憑 swagger 路徑列表寫進本 skill 的，**沒實測**，一測就錯。
+      **端點存在 ≠ 我知道怎麼呼叫它**——寫進 skill 前要真跑一次。
+  - 實測通過（2026-08-09）：`#21 blocked by #22` 建立後，
+    `GET /issues/21/dependencies` → `[22]`、`GET /issues/22/blocks` → `[21]`
+  - 派工前先檢查前置是否 `closed`，**不要靠人記得順序**
+
+## 狀態標籤：互斥 scope label
+
+**一條線走完，從進池子到用戶拿得到：**
+
+```
+s/triage → s/backlog → s/todo → s/doing → s/stage →（leo 蓋章 + arm + 推 prod）→ closed
+                                     ↘ s/pending（卡住／等外部／等人）
+```
+
+- `s/triage`　新進來的，**還沒驗傷**——還沒決定要不要做
+  - 🔴 **為什麼不用「留白」代表未驗傷**（2026-08-09 leo 建 Triage 看板時暴露）：
+    留白**查不出來**。撈得到 `s/todo`，卻撈不到「所有還沒驗傷的」，只能肉眼掃
+    ——那正是這套要拔掉的東西。**沒有標籤 ≠ 一種狀態，它是查詢的死角。**
+- `s/backlog`　驗過了、**確定要做**，但還沒排進任何 sprint
+  - ＝ leo 說的「**wishlist／功能需求／後續要規劃的**」
+  - 與 `s/triage` 的差別：**要不要做，已經有答案了**
+  - 與 milestone 的關係：`s/backlog` ＝ 沒掛 milestone；掛上 milestone 就該進 `s/todo`
+- `s/todo`　　**已排進 sprint**，等開工
+- `s/doing`　現在有人在做
+- `s/stage`　**已推上 stage，等 leo 去 youlin 的 stage 環境驗收**（出貨流程第⑤步）
+  - leo 2026-08-09 提：「就知道哪些要驗收」
+  - 🔑 **它的價值是可查詢**：leo 問「我今天要驗什麼」＝撈 `labels=s/stage` 一次答完，
+    不必總管回想、不必翻對話
+- `s/pending`　卡住——等外部／等人，**不是沒人做**（例：`#8` 等 leo 在真 Windows 截圖）
+- `closed`　　**用戶拿得到了**——不是「程式碼寫完」，也不是「leo 看過 stage」
+
+## 優先級是另一個軸：`p/` scope
+
+`p/high`（擋住交付或有時間壓力）／`p/low`（想做，但晚一點沒關係）。
+
+- 🔴 **為什麼不併進 `s/`**：`s/` 回答「它走到哪」，`p/` 回答「它多重要」——
+  **一個 `s/backlog` 的東西也可以是 `p/high`**（想做很久、很重要、只是還沒排進這次 sprint）。
+  併成一組就表達不出來。
+- 兩組各自 exclusive，互不干擾：一個 issue 同時有一個 `s/` 和至多一個 `p/`
+
+## 對照 leo 的 Triage 看板欄位
+
+- `Needs Triage` ← `s/triage`
+- `Backlog` ← `s/backlog`
+- `High Priority`／`Low Priority` ← `p/high`／`p/low`
+- `Closed` ← issue 的 `closed` 狀態
+
+⇒ **欄位仍是 leo 的視覺、標籤仍是機器的真相**，兩邊講同一件事但各自可用。
+
+🔴 **為什麼用 `s/stage` 不用 `s-stage`**：
+`s-stage` 是**平名**標籤，會跟 `s/doing` **同時掛著**；
+`s/stage` 在同一個 scope 內，貼上去舊狀態自動掉 ⇒ **才是狀態機**。
+狀態標籤一律走 `s/` 前綴，別建平名的。
+
+- 建法：`POST /labels`，body 帶 `{"name":"s/doing","exclusive":true}`
+- **`scope/name` 格式 ＋ `exclusive` ⇒ 同一 scope 下一個 issue 只能掛一個**
+  ```
+  貼 s/todo   → ['bug', 's/todo']
+  再貼 s/doing → ['bug', 's/doing']   ← 舊狀態自動掉，不相干的 bug 留著
+  ```
+- 🔴 **不建 `s/done`**：`closed` 就是 done，多一個就是同一件事兩個真相
+- 🔴 **label 是 repo-scoped，沒有跨 repo 繼承**——新 repo 要自己補
+
+## AI 做得到 / 做不到（別浪費時間試）
+
+- ✅ 做得到：開 issue、改 issue、掛／換 `s/*` 標籤、**建 milestone**、把 issue 掛進 milestone、
+  建先決條件、留言、結案、從 `GET /issues/{n}/timeline` 讀出「這張卡在哪個看板」
+- ❌ 做不到：**建 project**、**把卡拖進 project**、**知道卡在哪一欄**
+  - `POST …/projects` 回**純文字** `404 page not found`＝路由不存在
+  - **對照組證法**：同一把 token 打 `POST /labels` 回 201
+    ⇒ 證明「不是我沒權限，是 Gitea 沒開這條路」。**這個手法值得複用。**
+  - issue 物件無 project 欄位；`timeline` 的 `project_board` 事件也沒有欄位名／id
+- ❌ **不採**：直寫 Gitea 的 `project_issue` 表、web-only 路由
+  `POST /{owner}/{repo}/issues/projects/column`（吃 session cookie＋CSRF）
+  - 理由不只是升級風險：**那是別人家 app 的內部 schema／未公開契約**，
+    用了等於在系統裡多一條沒人維護的隱性契約——與「兩份真相」同病
+
+## 兩個會咬人的坑
+
+- **`labels` 在兩支 API 是兩種型別**
+  - 建 issue `POST /issues` → 吃 **id（int）**，傳名字會 422：
+    `json: cannot unmarshal JSON string into Go int64 within "/labels/0"`
+  - 貼標籤 `POST /issues/{n}/labels` → 吃 **名字（string）**
+- **本機是 zsh，不做參數字串切分**（bash 才會）
+  - `for n in $LIST` 在 zsh 會把整串當成一個字 ⇒ 用 `${=LIST}` 或逐一傳參
+
+## 🔴 怎麼寫一張 issue（leo 2026-08-09 連罵三次立的）
+
+leo：「**請問這個是人話嗎？誰看得懂？**」
+「你的 issues 要寫清楚 **5W1H**，你會做重複工，表示你不知道自己在幹嘛」
+「**先寫問題，再寫解法，不是先寫一堆細節**」
+
+### 🔴 為什麼要寫人話——不是為了友善，是為了讓 leo 抓得到我的錯
+
+leo 2026-08-09：
+> 「**你搞不清楚的時候，我也無法幫你看，因為我看不懂你在寫說明。**」
+
+這是所有「白話鐵律」底下真正的理由：
+**看不懂 ＝ 審查失效。** 我今天在同一個 session 裡錯了好幾次
+（把 24 個 open issue 讀成 0、給 leo 一台他根本沒在用的機器的網址）——
+如果我寫的東西他看得懂，這些會更早被擋下來。
+
+⇒ **用內部代號寫票，等於把唯一能發現我出錯的人的眼睛關掉。**
+
+### 🔴 修好的當下就關票（今天一天撞三次）
+
+2026-08-09 派工做 `#9`／`#14`／`#17`，**三張都是早就修好、只是沒人關**
+⇒ 三個 subagent 的時間全花在確認「這件其實已經好了」。
+
+- **不是那三張票的問題，是「修好時沒有人回來關」的問題**
+- ⇒ 改完 → push → **當場回票寫清楚怎麼驗的、然後 close**
+- ⇒ 撈任務前先問「這張票的日期多久了？」，超過一週的**先驗現況再派工**
+
+### 起點：issue 是「報告」，不是「工單」
+
+leo 2026-08-09：
+> 「如果我要丟，我會寫『**我遇到一個問題是…**』『**發現一個 bug 是…**』
+>   『**我希望有一個功能是…**』，**怎麼會寫成這樣？**」
+
+⇒ **一張 issue 應該長得像一個人開口講話。**
+先用第一人稱把事情講一遍，再談要做什麼。寫成規格條目就沒人看得下去。
+
+**那三種開頭正好就是三種類型，驗傷就是在判斷它是哪一種：**
+
+- 「我遇到一個問題是…」→ 卡住了 → `question`
+- 「我發現一個 bug 是…」→ 壞掉了 → `bug`
+- 「我希望有一個功能是…」→ 願望／功能需求 → `enhancement`（多半配 `s/backlog`）
+
+範例（#7 現在的樣子）：
+> 我遇到一個問題是：我要把 AI 接上我的知識庫，claude.ai 第一格就要我填 MCP 網址，
+> 但我不知道我的是什麼。那串網址是安裝的時候長出來的，每個人都不一樣，我沒地方查。
+
+### 標題：寫症狀，不寫修法
+
+反例（真的誤導了好幾個月的那一句）：
+```
+t151 收尾：安裝器要生成並下發 arcrun-mcp 的 MCP_OWNER_SECRET（擋封測，缺它每個封測者都死在同意頁）
+└代號┘ └────────── 這整段是「怎麼修」，而且是後來被推翻的舊解法 ──────────┘ └─ 唯一人話在括號裡 ─┘
+```
+改成：**「用戶不知道自己的 MCP 網址是什麼，所以接不上 AI」**
+
+- **① 標題寫症狀不寫修法**——**修法會變，症狀不會**。
+  上面那句最毒的地方不是難懂，是它把「當時以為的修法」寫死在標題上；
+  後來 owner secret 這條路被 portal 帳密取代，**標題還停在舊解法，於是持續指錯方向**。
+- **② 標題裡不准出現只有我們懂的字**：代號（`t151`）、零件名（`MCP_OWNER_SECRET`）、
+  檔名（`build-bundles.mjs`）一律降到細節區。
+- **③ 一句話講完「誰＋卡在哪」**，看標題就知道要不要點進去。
+
+### 內文：問題 → 解法 → 細節（細節收進 `<details>`）
+
+```markdown
+## 問題
+<用戶視角一句話：他想做什麼、卡在哪、結果怎樣>
+
+## 解法
+<一句話：要做出什麼>
+
+## 怎麼驗
+<走用戶真的會走的那條路；貼實際畫面，HTTP 200 不算>
+
+---
+<details><summary>細節</summary>
+現況實查（指令＋輸出）／真身在哪個 repo 哪個檔／可照抄的既有寫法／
+leo 原話／不屬於本 issue 的（已拆到 #N）
+</details>
+```
+
+**為什麼細節要收起來**：leo 掃 issue 是在決定「這件要不要現在做」，
+細節是做的人才需要的。攤開來就掃不動 ⇒ 他掃不動 ⇒ 這件事不會發生。
+
+## 🔴 討論票 → 執行票；追蹤大的（2026-08-10 定案，D58）
+
+> leo：「這個 issue 是對於**某個建議的討論過程**，中間會產生一個**新的 issue 就是依照討論執行某個修正**，**追蹤大的**。」
+> leo：「**充分利用 gitea 的機制，不要硬做個不支援的機制，容易出錯。**」
+
+- **討論票**＝一個建議的討論過程（脈絡、來回、為什麼）。**不當工單追。**
+- **執行票**＝從討論裡長出來的「去做某個修正」。有自己的擋點、驗收、`s/*` 狀態。
+- **追蹤執行票**；孫任務留在執行票裡當 checkbox（見下一段，那條沒變）。
+
+### 定址：用 Gitea 原生的 issue 引用，不要自製結構
+
+Gitea 原生就會把 issue 引用自動變成可點連結 ⇒ **CP／SDD 不必手貼網址、不必造錨點。**
+
+- 🔴 **最好用的判準**：**需要指到票裡的某一行 ＝ 那張票該拆了。**
+  這個限制反而**強迫出正確的顆粒度**。
+- **刀口不是「大小」，是「狀態」**：問「**它會不會需要跟隔壁那條不同的狀態？**」
+	- 會 → 獨立成執行票
+	- 不會 → 留在票裡當 checkbox
+
+### 兩個極端都撞過，別再撞
+
+- **太大**：`Leo/mira#2` 一張票 29 個 checkbox、五個段落**五種狀態**，卻只掛得了一個 `s/pending`
+	- ⇒ `⑤-1`～`⑤-3` 整段作廢了好幾小時沒人發現——**29 條的票不會有人逐條稽核**
+- **太小**：08-09 把 stage 一件事拆成五張（`#27`／`#29`～`#32`），**leo 打開就看不下去**
+
+### ⚠️ 已作廢：隱形錨點 `<a id="tNNN">`（D53，同日上線同日推翻）
+
+**不要撿回去。** 它是塞 raw HTML 偽造 checkbox 錨點，靠渲染器願意保留、
+靠沒人用網頁編輯器把它洗掉——**脆弱，而且壞掉時看不出來**。
+
+📌 **它錯在哪值得記**：整段推理是嚴謹的（實測三則、對照兩個反例、接上既有鐵律），
+**但沒有先問「這個平台原生支援嗎」**。與 08-09「平台已經做了的事我又做一次」同族，
+只是這次是**平台沒做的事我硬做**。
+⇒ **造任何機制之前先問兩句**：「原生支援嗎？」「不支援是不是在告訴我方向錯了？」
+
+## 🔴 子任務用 issue 內的工作項目清單，不要開成一堆票（2026-08-09 實撞）
+
+leo：「**子任務在這裏寫就好了**」（指 Gitea 編輯器的工作項目清單按鈕）「**現在這樣太亂了**」
+
+- **一件事 ＝ 一張票**，票裡用 `- [ ]` 列子任務（**每條帶錨點，見上一段**）
+- ❌ **不要把每個子任務開成獨立的票**
+  - 2026-08-09 實錯：總管把 stage 這一件事拆成 `#27`／`#29`／`#30`／`#31`／`#32` 五張，
+    leo 打開就看不下去。已收攏回 `#27` 一張，其餘關閉
+  - 病根：把 leo 說的「寫在 issues 裡的**新增工作項目清單**」讀成「開新 issue」，
+    而他指的是**編輯器裡那顆 checkbox 按鈕**
+- 🔑 **規則（leo 原話）**：
+  > 「**整個 tasks 內容用 markdown 寫進去，除非某個任務開始工作後變大了，就要獨立成一張票。**」
+  - ⇒ **預設全部寫成 checkbox**，包含整份 SDD 的 tasks
+  - ⇒ **獨立成票是「事後」的動作**，不是規劃時就先拆
+    - 觸發時機＝**開始做了之後才發現它變大**（要多輪、要另一個 repo、要另一個人）
+    - 那時再把那一條抽出來開票，並在原票的該行改成 `- [ ] 見 #NN`
+  - ⇒ **不要在規劃階段就預先拆票**——那正是 2026-08-09 弄亂的做法
+- **另開一張的另一個正當理由**：**主詞不同**（見下一段）
+  ——例如「網址看得到」vs「進得去」是兩個人在抱怨兩件不同的事，那本來就不是同一件
+
+## 🔴 一筆 issue 只做一件事（2026-08-09 實撞）
+
+leo：「#18 其實是 2 個分開的任務⋯⋯**一半已經完成卡在另一半，但另一半根本不相依**」
+
+- **綁在一起的代價**：做完的那半被沒做的那半拖著，**看起來像沒完成**
+  ⇒ 進度儀表失真，而 leo 是靠這個判斷還剩什麼
+- **判準（同 `cp-write` 鐵律 5）**：**主詞不同就拆**
+  - 「把設定搬進應用視窗」＝設定放哪的問題
+  - 「新增 onboarding」＝第一次的人怎麼上手的問題
+  - 兩者互不依賴 ⇒ 一定是兩張
+- 🔴 **不准用「併入此案」把別的 issue 吞進來**
+  - #18 原本寫「併入此案：狀態顯示（見另一 issue）」，而那是獨立存在的 #17
+  - ⇒ 同一件事在兩張票上，**又是兩份真相**；要關聯用 `dependencies`／`blocks`，不用文字吞併
+- **拆單時要留痕**：兩邊都寫明「從 #N 拆出」與「為什麼不相依」，
+  否則下一個人會以為是重複開單
+
+## 🔴 設計寫在票上——不要每次回去 grep 源碼（leo 2026-08-09 立）
+
+> leo：「你應該**把 design 寫在 issues 裡**，你就可以**去查 issues，而不是每次去查源碼**。」
+
+**為了回答問題而查出來的「它現在怎麼運作」，當場寫回那張票，附 `檔案:行` 當出處。**
+
+- **當天實錄**：同一個 session 裡，為了回答四個問題各翻了一次源碼——
+  console 現在用來做什麼（`installer/oauth-prototype/worker.js:3237`）／
+  迎新引導為什麼看不到（`main.js:73` 只在零帳號時出現）／
+  重裝會不會重設密碼（`/console/setup` 已存在回 409）／
+  bundle 是快照還是連結（manifest 的 `source` 欄與 `js_bytes`）。
+  **四題的答案都值得留在票上，卻只留在對話裡** ⇒ 對話結束就沒了，下次再翻一次。
+- 🔴 **而且翻源碼拿到的是「稿子」**：它反映「還沒清乾淨」，不等於「還在用」。
+  同一天就因為讀源碼推論而把兩台實例的定位講反（geek＝prod／youlin＝stage）。
+- **票上該有的三件**：**它現在怎麼運作／為什麼這樣設計／動它會影響誰**——不只是「要做什麼」。
+- **順序**：先查票 → 查不到才翻源碼 → **翻完回頭補進票**（與 wiki 同一階梯）。
+- **判準一句話**：**如果我剛剛翻了源碼才知道答案，那就是一條該補進票的設計記錄。**
+
+## 界線（沿用，未變）
+
+- **跨 repo 的 issue／comment 一律開頭署名** `[<本 repo> CC]`／`[InkStoneCo 總管]`
+  - 所有 repo 共用同一個帳號，author 看不出是誰發的，身份只能在內容層自報
+- **發 issue 給別的 repo 要先問人**；對自己 repo 開 issue 記待辦則直接做
+- 🔴 **有事才讀，禁止自動輪詢**——禁 Actions／cron／webhook 因 issue 事件 fan-out
+  （那正是當初害 GitHub 帳號被 flag 的流量模式；換成 Gitea 也不放寬）
+
+## 🔴 標 `s/stage` 不等於交棒完成——要附「怎麼測」
+
+leo 2026-08-09：「**要我來測試是嗎？如果這樣，你要在總管回覆中說明測試方式，
+而不是『要測試』，我就會按照它來測試。**」
+
+- 把票改成 `s/stage`／`s/pending` 只是**改了一個欄位**，leo 看到的是「該你了」卻不知道怎麼做
+  ⇒ 等於把找路的成本丟給他，正是 principles「不增加 leo 負擔」要防的
+- **每一件推給 leo 的事，回覆裡必須帶三樣**：
+  - **他要打開什麼**（確切網址／確切指令，**不是「去 portal 設定頁找」**）
+  - **他該看到什麼**（正確的樣子長怎樣）
+  - **什麼情況算失敗**（看到什麼就是壞的，回一個詞給我）
+- 🔴 **指令必須自己先打過**。給沒驗過的網址／指令 ＝ 把除錯成本丟給他
+  - 2026-08-09 實例：我差點把 `arcrun-mcp.yuga3bse.workers.dev` 給他——
+    **實打是 HTTP 000（DNS 不解析）**。正確的是 `WORKER_SUBDOMAIN`
+    （`deployment-map.md:176` ＝ `youlin-hsieh-dev`），實打回 401 `unauthorized`
+    ＝端點在、要 OAuth，**這才是對的行為**
+  - ⇒ **401 和 000 都不是 200，但意義天差地遠**：前者證明東西在，後者證明我在瞎猜
+
+## 收工判準
+
+回覆 issue 要寫**做了什麼、為什麼這樣決定、動了哪些檔**，不是只回「done」。
+結案要有**實測證據**——「程式碼寫完了」不是狀態（見 `CRITICAL-PATH.md`）。
+
+## ⏳ 尚未驗證的一條（別當成已知）
+
+**把卡拖到 Done 欄，Gitea 會不會自動 close 那個 issue？**
+2026-08-09 想測，但那張測試卡被刪掉了 ⇒ **無證據，不編**。
+若答案是「會」，拖拉就天然被機器看見，這條縫自動消失。

commands/sdd-check.md

@@ -0,0 +1,65 @@
+---
+name: sdd-check
+description: |
+  開始任何開發任務前確認有沒有對應的 SDD——要寫 code、開新功能、
+  或不確定「這件事屬於哪份規格」時自動載入。
+  依 D35 SDD 生命週期鐵律：任何時刻只允許一份 status: active 的 SDD，
+  所有開發任務對應它的 tasks，找不到就停下來問（不得自行建 SDD）；
+  規格層變更改開 Gitea 票（Human＋指派 Leo）後停止等 confirm——pending-changes.md 已於 2026-08-19 廢除，禁止寫入。
+---
+
+# /sdd-check — 確認當前任務有沒有對應 SDD
+
+動手前執行。確保 CC 有全局觀，不會在沒有設計文件的情況下猛衝。
+
+---
+
+## 執行流程
+
+### 第一步：理解任務
+
+確認使用者要做什麼：
+- 涉及哪個子系統？
+- 是新功能還是修改現有功能？
+- 影響範圍？
+
+### 第二步：尋找對應 SDD
+
+在 `docs/3-specs/` 下尋找對應的子系統目錄，確認有沒有：
+- `design.md`（設計文件）
+- `tasks.md`（任務清單）
+
+### 第三步：根據結果回應
+
+**情況 A：找到對應 SDD**
+```
+✅ 找到 SDD：docs/3-specs/[子系統]/
+📋 design.md：[確認]
+📋 tasks.md：[確認，列出相關 task]
+🎯 對應 task：[編號和描述]
+繼續嗎？
+```
+
+**情況 B：找不到 SDD，任務明確**
+```
+⚠️ 找不到對應 SDD
+任務：[描述]
+建議在 docs/3-specs/[建議子系統名]/ 建立 SDD
+
+要我幫你起草 design.md 嗎？（需要你確認後才動手）
+```
+
+**情況 C：找不到 SDD，任務模糊**
+```
+⚠️ 找不到對應 SDD，而且任務範圍不夠清楚
+請先回答：
+1. 這個功能屬於哪個子系統？
+2. 完成的標準是什麼？
+3. 有沒有不能動的邊界？
+```
+
+### 注意
+
+- 找不到 SDD **不等於可以直接動手**
+- 小修改（修 bug、改文字）可以豁免，但要明確說「這是小修改，範圍是 X」
+- 新功能、架構變動、跨模組的修改 → 一定要有 SDD

commands/wiki-capture.md

@@ -0,0 +1,69 @@
+# /wiki-capture — 把對話結論存進 wiki
+
+把這次對話中產生的決策、誤解釐清、或重要結論存入 wiki。
+解決「討論過了但知識消失」的問題。
+
+---
+
+## 執行流程
+
+### 第零步：機敏檢查（寫入前一律先過）
+
+把任何內容寫進 wiki 前，先確認**不含**密碼 / API 金鑰 / 私鑰 / 連線字串帳密 / 個資（身分證、信用卡）。
+- 命中 → 不要記「值」，改記「位置」（例：「DB 密碼放 `.env`，不入 wiki」）
+- 來源整檔機敏 → 提醒使用者加進 `system-dev/wiki/.wikiignore`
+- 真要保留示範格式 → 該行尾加 `wiki-secret-ok` 標記
+> 這是協議層自律。最後一道 `wiki-secret-scan.sh` hook 會在寫入 `system-dev/wiki/` 時機械攔截，但別依賴它兜底——當場就不要把機敏值帶進來。
+
+### 第一步：辨識對話中的可記錄內容
+
+掃描當前對話，找出：
+
+| 類型 | 判斷標準 | 存到哪 |
+|------|---------|-------|
+| 架構決策 | 「為什麼選A不選B」「我們決定用X」 | `decisions-summary.md` + `system-dev/docs/2-architecture/decisions/` |
+| CC 的誤解被糾正 | CC 說了某件事，使用者說「不是，是...」 | `mistakes.md` |
+| 重要狀態更新 | 完成了某件事、阻擋了某件事 | `status.md` |
+| 技術發現 | 踩到坑、找到解法、重要行為確認 | `mistakes.md` 或對應 SDD |
+
+### 第二步：列出清單給使用者確認
+
+格式：
+```
+這次對話我整理了以下內容要存入 wiki：
+
+1. [MISTAKE] CC 誤解了 X，正確是 Y
+2. [DECISION] 決定用 A 不用 B，原因是 C
+3. [STATUS] 完成了 task 2.3，下一步是 2.4
+
+確認後存入，有需要修改的嗎？
+```
+
+**停下來等確認。**
+
+### 第三步：寫入
+
+確認後，依照格式寫入對應檔案：
+
+**mistakes.md 格式：**
+```
+⚠️ MISTAKE: [錯誤描述]
+   症狀: [CC 的表現]
+   正確做法: [應該怎麼做]
+   原因: [背景]
+   日期: [YYYY-MM-DD]
+```
+
+**decisions-summary.md 格式：**
+```
+## [主題] — [YYYY-MM-DD]
+**結論**：[一句話]
+**原因**：[簡短說明]
+**詳細**：system-dev/docs/2-architecture/decisions/[檔名]
+```
+
+重大決策同時在 `system-dev/docs/2-architecture/decisions/` 建立 ADR 檔案。
+
+### 第四步：確認
+
+告知存到哪些檔案，共幾條記錄。

commands/wiki-init.md

@@ -0,0 +1,230 @@
+# /wiki-init — 初始化或接入 LLM Wiki 系統
+
+初始化這個專案的 LLM Wiki 記憶系統。
+新專案建立空白結構，已有專案掃描現有文件並**改寫**成 wiki。
+
+---
+
+## 核心概念：wiki 是 AI 改寫過的記憶，不是原文索引
+
+記憶系統的目的，是讓 AI **之後讀得快**。但人類寫的原始文件——不管是 vault 的隨手記、開發專案的會議記錄、規格草稿、散落的 `.md`——天生是亂的：重複、流水帳、半成品、口語。
+
+如果 wiki 只是一份 `[[原文檔名]]` 指回原文的**索引**，那每次未來要用都得重新解析那團亂，等於沒省到。**wiki 的價值在於「改寫一次，之後每次讀都便宜」**。
+
+所以原則對**所有專案**一致（不分 vault 或一般開發）：
+
+> 人類寫的原文是 **SSoT**（真理來源，永遠唯讀）。
+> 但實際要長期保存、被 AI 反覆讀的是 **AI 改寫整理過的 wiki**。
+> **AI 是總編輯**——把原文改寫成自包含、概念原子化、互相連結、適於 AI 讀的知識條目。
+
+唯一例外：原文是**不可改動的正式文件**（簽署過的規格、法規、合約），必須逐字讀原文——這種才在 wiki 裡用指針指回去，並註明「逐字依原文」。除此之外，一律改寫。
+
+**raw source 永遠唯讀**：所有產出只往 `system-dev/wiki/` 寫，絕不改動、搬移、重新命名原文。
+
+---
+
+## 執行流程
+
+### 第一步：偵測專案狀態
+
+檢查以下項目，判斷是新專案還是已有專案：
+- 根目錄有沒有 `system-dev/wiki/`
+- 根目錄有沒有 `docs/`（或 vault 的 `pages/`、`journals/`、根目錄 `.md`）
+- 有沒有散落的 `.md` 檔案
+
+同時**偵測 raw source 路徑**（同 install.sh 邏輯）：
+- 根目錄有 `logseq/` → Logseq vault，raw source = `pages/` + `journals/`
+- 根目錄有 `.obsidian/` → Obsidian vault，raw source = 根目錄所有 `.md`
+- 都沒有 → 一般專案，raw source = `docs/` 下所有 `.md`（及散落的 `.md`）
+
+**新專案**（幾乎空的）→ 直接建立結構，跳到第三步
+**已有專案**（有文件）→ 執行第二步
+
+### 第二步：已有專案的掃描（已有專案才執行）
+
+1. 遞迴找出 raw source 裡所有 `.md` 檔案
+2. **先套用 `system-dev/wiki/.wikiignore`**：命中 pattern 的檔案整個排除，不讀不編入。
+   - 若 `.wikiignore` 不存在，從範本建立一份（預設排除 `.env`/`*.pem`/`*secret*` 等）
+   - 被排除的檔案在清單裡標「🚫 .wikiignore 排除」，**不可被覆蓋**
+3. 對其餘檔案標注**改寫計畫**：會萃取成哪些 wiki 條目。一份原文可能拆成多個概念原子條目，多份相關原文也可能合併成一條。
+4. 列出清單給使用者確認，**停下來等確認**
+
+> **量大時建議用 Haiku 改寫**：逐份原文「改寫成 wiki 格式」是重複、機械、判斷成本低的工作——正適合 Haiku。原文數量多（如數十、上百份）時，主動建議：
+> 「共 N 份原文要改寫，這類逐份萃取很適合用 Haiku 並行處理（便宜、夠快）。要我派 Haiku subagent 改寫嗎？」
+> 得同意後，用 Task / subagent 把每份原文（或每批）丟給 Haiku 改寫，主模型只負責切分概念、定條目邊界、最後審稿與互連。
+
+> 機敏防護（三層）：
+> - **L1 .wikiignore**：整檔排除（這一步）
+> - **L2 行內標記**：檔案要編入但某段不要 → 遇到 `<!-- wiki:ignore -->` … `<!-- wiki:end -->` 之間的內容**略過**，只留「（此處機敏，已略過）」
+> - **L3 hook**：萬一機敏值仍被寫進 wiki，`wiki-secret-scan.sh` 會 exit 2 擋下
+> 編入任何檔案前，先檢查是否含密碼/金鑰/個資——有就改記「位置」而非「值」。
+
+### 第三步：建立缺少的結構
+
+只建立不存在的目錄和檔案，**已有的一律不動**。
+
+wiki 採**三層 + 標籤橫切**架構（183 卡實證，issue #8）：
+
+```
+system-dev/wiki/
+├── INDEX.md              ← 索引：多角度視圖的家（標籤角度、決策角度、…）
+├── TAXONOMY.md           ← 標籤字典（cards 的分類元資料，受控擴充）
+├── status.md             ← [push] 時態狀態：當前進度、下一步
+├── mistakes.md           ← [push] 踩過的坑、被糾正的誤解（防不自覺盲區）
+├── principles.md         ← [push] 跨全局的設計原則（行動前必服從）
+└── cards/                ← [pull] 一切知識內容：原文摘要、AI 筆記、決策、概念…
+    └── <bucket>/         ← 儲存桶（分類由 frontmatter 標籤承載）
+        ├── 00-INDEX.md   ← 桶子索引（固定名，容器：只連不重寫，H2/H3 分節）
+        └── <概念全名>.md  ← 概念原子卡（一概念一檔，自包含）
+```
+
+> **[push] / [pull] 是這套 wiki 的核心判準——因為 wiki 主要是給 AI（CC）看的。**
+> 見下方「核心判準：push vs pull」。`decisions-summary.md` 已**降級為 cards + INDEX 決策視圖**（決策是知識內容＝card）；既有的 decisions-summary 若存在，保留為相容，不刪。
+
+關鍵原則：**資料夾只是儲存桶，分類由 frontmatter 標籤承載**。資料夾名不該硬繼承原稿目錄——原稿目錄是「人為了整理草稿」分的，wiki 連分類都該由 AI 重新組織。
+
+> **桶子索引固定叫 `00-INDEX.md`**（issue #6）：`00-` 前綴讓它排序最前、一眼可辨（像 README 之於資料夾），AI 載入任何 `cards/<bucket>/` 一律先讀它，不必猜。檔內 H1 仍寫主題名（如 `# PKM 知識管理`），語意不丟。
+
+一般專案仍可同時建 `system-dev/docs/` 分類樹（SDD 等）：
+```
+system-dev/docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,test-reports},6-user}
+```
+（純 PKM vault 不需要 `system-dev/docs/` 分類樹時，只建 `system-dev/wiki/`。）
+
+檔案（不存在才建）：
+- `system-dev/wiki/INDEX.md`、`TAXONOMY.md`
+- `system-dev/wiki/status.md`、`mistakes.md`、`principles.md`（三個 push 檔）
+- `system-dev/docs/README.md`（一般專案才需要）
+
+---
+
+## 核心判準：push vs pull（wiki 是給 AI 看的）
+
+整理任何內容前，先判斷它該 **push** 還 **pull**——判準是「**CC 做事時會不會被動看見**」：
+
+- **push**：CC 行動前必須主動出現在 context（session 開始就由 hook 注入）。給「CC 不會主動去查、但不看就出事」的東西。
+- **pull**：CC 想到要查、或載入相關卡時才看見。給「CC 面對它時自然會查」的知識。
+
+**為什麼這是核心**：mistakes 防的是 CC「不自覺的盲區」——一個你不知道存在的錯，你不會主動去檢索它。靠 CC 自覺去查自己沒自覺的盲區是自相矛盾的，所以 pull 對盲區失效，**必須 push**。原則同理：沒被推到眼前的準繩，CC 設計時很可能沒想到要服從就做了。
+
+| 內容 | push/pull | 注入形態（hook）|
+|------|-----------|----------------|
+| **status** | push | **全文**——CC 必須知道精確的下一步，摘要會漏 task 編號 |
+| **principles** | push | **全文（一行一條）**——短而硬的約束，漏一條就違反；≤15 條，超過代表該下放成 card |
+| **mistakes** | push | **標題清單 + 一行症狀**，全文按需 pull——量可能大，摘要足以觸發「我正撞到某條」的認出 |
+| **decisions、原文摘要、概念知識、一切其餘** | pull | 寫成 cards；CC 面對時自然會查，INDEX 提供角度入口 |
+
+**principles 維護規則**：一行一條精煉準繩（如「不污染用戶根目錄」「目標用戶 low-code」「wiki 主要給 AI 看」）。發現新的跨全局原則 → append 一行；超過 ~15 條代表某些該合併或下放成 card。**累積原則只改 principles.md，不必問用戶開新檔。**
+
+### 第四步：訪談（每次一個問題）
+
+依序問：
+1. 這個專案做什麼？（一句話）
+2. 有哪些絕對不能違反的限制？（技術棧、架構原則等）
+3. 現在進行到哪個階段？
+4. 有沒有 CC 曾經犯過的錯要先記下來？
+
+把答案填進 `CLAUDE.md`（如果存在）或建立新的。
+
+### 第五步：改寫成 wiki（AI 當總編輯）
+
+（第二步確認後執行）
+
+**不搬動原文**。逐份讀 raw source，改寫萃取成 `cards/<bucket>/` 裡的自包含原子卡：
+
+- **概念原子化**：一張卡講一個概念，不是一篇原文對一張卡。原文太雜就拆，多份相關原文就合。
+- **自包含**：讀卡就懂，不必回去翻原文。把口語、重複、流水帳改寫成結構化知識，**不寫「詳見原文」**。
+- **保留來源指針**：每卡標 `**來源**：原文相對路徑`，為可追溯，不是要使用者回去讀。
+- **frontmatter 標籤分類**（見下方）：分類走 frontmatter `tags:`，不靠資料夾、不靠行內 `#tag`。
+- **互相連結（typed-edge 三元組）**：`## 關聯` 不只列裸 `[[頁面]]`，改寫成帶語義的三元組（見下方）。
+- **萃 gloss（node 一句說明）**：frontmatter 放 `gloss:` —— 這張卡（= 一個 entity / graph node）的一句話定義，供下游語義 normalize（見下方）。
+
+卡片格式（每張卡）：
+```markdown
+---
+tags: [知識管理, AI協作, 方法論]
+gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用，選填、deep tier 才產）
+---
+# 概念全名
+
+← [[<bucket>/00-INDEX]]
+
+**來源**：`[raw source 相對路徑]`
+**最後更新**：YYYY-MM-DD
+
+## 摘要
+[一句話核心]
+
+## 重點
+- [自包含改寫的要點，不依賴原文]
+
+## 實體
+> 本卡內文的關鍵實體（也是 graph node）。名＋描述供下游 embedding normalize。集中放、一行一個、不縮排、不重複。
+- **原子筆記**（atomic note／卡片原子化）— 每張卡只承載一個不可再分論點的知識記錄單元。
+- **傳統筆記**（大鍋炒筆記）— 把多主題混雜在同一篇、難精確引用的記錄方式。
+
+## 關聯
+### 內文知識關係（內文實體間；端點＝上方 `## 實體` 正規名，一字不差）
+- 原子筆記 >> 對立於 >> 傳統筆記
+### 卡片關係（卡對卡）
+- [[本卡]] >> 謂詞（動詞短語） >> [[他卡]]
+```
+
+**麵包屑用帶路徑 wikilink**（issue #7）：H1 次行放 `← [[<bucket>/00-INDEX]]` 指回桶子索引。
+桶子索引固定名 `00-INDEX` 跨桶會撞名，故**指 00-INDEX 一律帶路徑**（`[[pkm/00-INDEX]]`，Logseq 原生支援、下游 ingest 也能對應到具體檔）。普通卡片間連結仍用裸 `[[卡名]]`（卡名唯一，不需路徑）。
+
+**frontmatter 標籤分類**（issue #8）：
+- **用 frontmatter `tags:` 而非行內 `#tag`**：卡片內文常大量用 `#`（講筆記法時的 `#猜想`、`#book100`），分類標籤若也行內 `#`，下游 ingest 無法區分「分類」與「內文範例」會污染 graph。frontmatter 與內文完全分開，零歧義。
+- **用標籤而非資料夾分類**：資料夾＝強制單一歸屬；標籤＝多重歸屬。一張卡可同時屬知識管理＋AI協作＋架構設計，硬塞一個資料夾會在其他檢索角度漏掉。
+- **雙軸 taxonomy**（寫進 `TAXONOMY.md` 當字典；**受控擴充**，非凍結）：
+  - 領域（主軸，1-3 個）：如 知識管理／學習認知／AI協作／生產力／系統設計／工具教學
+  - 形態（副軸，0-2 個）：方法論／工具實作／觀點主張／架構設計／案例經驗
+  - 一般開發專案的軸可不同（如 子系統／層級／決策類型），由 AI 依專案性質提出、寫進 TAXONOMY.md。
+  - **遇到現有軸裝不下的內容**：先查是否只是現有標籤的同義詞；確實是新軸才加進 TAXONOMY.md（附定義）再用——**禁止繞過字典在卡片直接冒新標籤**。字典是 per-repo，跨 repo 不必共用。
+
+**typed-edge 規則**（issue #5/#11，把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）：
+- **重點抓內文實體關係，不只卡對卡**：卡對卡（`[[卡A]] >> 謂詞 >> [[卡B]]`）只是既有雙鏈加動詞、資訊量幾乎沒增加；價值在內文概念關係（`原子筆記 >> 對立於 >> 傳統筆記`，A/B 是內文概念非卡標題）。
+1. **方向性**：`A >> 謂詞 >> B` 必須讀成「A（謂詞）B」一句通順的話；A、B 順序就是主→賓真實方向。
+2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、犧牲）。**禁名詞當謂詞**——`>> 存儲格式 >>`、`>> 操作體驗 >>` 讀不通，是錯的。
+3. **謂詞自由但別太天馬行空**：「參考／參照」皆可（下游 embed 自動聚類），別寫「瞄了一眼」這種抓不到同義的。
+4. **內文三元組端點用裸文字**（非 `[[wikilink]]`），避免 Logseq 紅色斷鏈；卡對卡那層才用 `[[]]`。
+5. **向後相容**：純 `[[A]]` 仍合法（視為無類型邊），盡量補謂詞。
+
+> **★ 硬自檢（Haiku 量產必備）★** 內文三元組端點必須與 `## 實體` 某粗體正規名【一字不差】。**寫完逐條把 A、B 拿去 `## 實體` 比對**，沒有完全相同的 → 這條錯了，改用實體表已有的詞、或把端點補進 `## 實體` 再指它。禁止端點帶括號註解／整句補語／形容詞短語。（實證：光寫規則 Haiku 會略過，端點對不齊 14 條；寫成自檢動作後 14→0。跑 12 張才暴露。）
+> `>>` 是分隔語法，repo 可自選符號，但全程一致。
+
+**萃 gloss 規則**（issue #9/#11，把「node 的一句說明」也預編譯，供下游 KBDB 語義 normalize）：
+- **gloss = 這個 entity / graph node 是什麼的一句話**。下游對「entity 名 + gloss」一起做 embedding 求相似度，自動歸一同義詞（比只對名字準、比手維護 alias 表自動）。
+- **兩層 gloss**：① frontmatter `gloss:` 描述卡標題這個 node；② `## 實體` 每行描述句描述內文實體 node。**內文實體也是 graph node、也需描述句**才能 normalize（`黃仁勳` vs `Jensen Huang` 靠描述拉近向量）。
+- **實體要描述、謂詞不用**：實體同義詞字面差遠需描述拉近；謂詞同義詞字面本就近，裸詞 embed 自動聚類。
+- **在知識生產的當下、由 local CC 建**：gloss 跟三元組同階段萃，**不留給下游 ingest 臨時補**——下游只有單檔 / 跨庫視角，編不出貼合的 gloss（＝胡扯）。
+- **選填、deep tier 才產**：淺萃（只要結構）時不浪費；deep 改寫時每張卡補。
+- **gloss ≠ 摘要**：`gloss` 是給機器 normalize 的定義句（「X 是…」）；`## 摘要` 是給人讀的核心一句。
+- **格式對齊下游 envelope**：frontmatter `gloss:` 與 `## 實體` 詞條對應下游 ingest envelope 的 `nodes[].gloss`，ingest 直接取用。
+
+**INDEX.md 是標籤視圖**（非資料夾列表），`00-INDEX.md` 是桶內容器（只連不重寫，H2/H3 分節）。
+頂層索引指桶子索引帶路徑：`[[pkm/00-INDEX]]`。
+
+> 與 claude.ai Cowork 的 `system-dev/docs/SKILL.md` 改寫邏輯一致，兩條路徑（CC / Cowork）產出同一種 wiki。
+
+### 第六步：完成報告 + 驗證
+
+完成後**驗證原文 0 動**（踩過的坑，issue #8）：
+```
+git status --short pages/ journals/    # 或一般專案的 docs/ ——須 0 新增 0 修改
+```
+
+> **改寫時必守**（subagent 尤其）：
+> 1. **絕不寫入 raw source**：subagent 目標一律給絕對路徑到 `cards/<bucket>/`，明寫「絕不寫入 pages/journals/docs 原稿」；事後用上面的 `git status` 驗。
+> 2. **檔名 = 卡片全名**，否則 `[[全名]]` 對不到檔。冒號用全形「：」、斜線用全形「／」，**全程一種字元**，避免 `/`、`∕`、`：` 混用斷鏈。
+> 3. **量大用 Haiku 並行改寫**，主模型只切概念邊界＋審稿＋修跨資料夾斷鏈。
+
+告知：
+```
+✅ wiki-init 完成
+建立了：[列出新建的目錄和檔案]
+跳過了：[列出已有因此不動的]
+改寫了：[N 份原文 → M 張原子卡、K 條 typed-edge、M 條 gloss（deep tier）]
+原文驗證：pages/ journals/ git status 0 異動 ✅
+下一步：用 /wiki-capture 把重要決策存進 wiki
+```

commands/wiki-recall.md

@@ -0,0 +1,58 @@
+# /wiki-recall — Session 開始，手動接關
+
+開新對話時接上次進度。**Fallback 命令**：SessionStart hook 沒啟動時手動接關；要完整脈絡時也用。
+
+> 主路徑是 SessionStart hook 自動注入 status 重點，不靠你打命令。
+> 這支命令應對 hook 失效，以及需要比「status 重點」更完整脈絡的時候。
+
+---
+
+## 命名閉環
+
+init(建) → update(存，session 末) ↔ **recall(接，session 初)** → capture(隨時存結論)
+
+---
+
+## 執行流程
+
+### 第一步：讀 status.md（當前進度）
+
+讀 `system-dev/wiki/status.md`，掌握：
+- 正在做什麼、阻擋點
+- 下次 session 第一件事
+- 待負責人確認、已知問題
+
+### 第二步：讀 decisions-summary.md（為什麼這樣做）
+
+讀 `system-dev/wiki/decisions-summary.md`，掌握相關的架構決策——避免重新討論已定案的事。
+
+### 第三步：讀 mistakes.md（別重犯）
+
+讀 `system-dev/wiki/mistakes.md`，掌握已知誤解 + 快速檢查清單。
+
+### 第四步：掃 wishlist / HANDOFF（如果有）
+
+- `docs/wishlist.md`：待補功能
+- 任何 `HANDOFF.md` / 交接note：上一棒留下的脈絡
+
+### 第五步：回報接關結果
+
+```
+📍 接關完成
+🔄 上次正在做：[status 的「正在做」]
+🎯 下次第一件事：[status 的「下次 session 第一件事」]
+⚠️ 待確認：[如有]
+```
+
+---
+
+## 鐵律：快照非即時狀態
+
+status / wiki 是 **point-in-time 快照，不是即時狀態**。
+
+接關 ＝ 讀快照 **＋ 核實快照**，**不盲信**。
+
+> 實例：某專案 status 曾寫「待 A 收尾 X」，實際 X 早已完成。
+> 照舊資訊行動會去催一件已完成的事。
+
+動手前，先用當前 code / git / 檔案核實快照寫的事項是否仍成立。發現落差 → 先更新 status，再動手。

commands/wiki-update.md

@@ -0,0 +1,50 @@
+# /wiki-update — Session 結束，更新狀態
+
+每次 session 結束時執行。更新 status.md，確保下次 session 能無縫接上。
+
+---
+
+## 執行流程
+
+### 第一步：整理這次 session 的結果
+
+從對話中提取：
+- 完成了哪些 tasks（標記為 [x]）
+- 進行中但未完成的（標記為 [🔄]）
+- 遇到什麼問題或阻擋
+- 下次應該從哪裡開始
+
+### 第二步：更新 tasks.md
+
+把對應 SDD 的 tasks.md 狀態更新（如果這次有動到的話）。
+
+### 第三步：更新 status.md
+
+用以下格式覆蓋 status.md：
+
+```markdown
+# 當前狀態
+> 更新時間：[YYYY-MM-DD]
+
+## 正在做
+- [🔄] [task 描述] — 阻擋點：[如果有]
+
+## 下次 session 第一件事
+[具體的第一個動作，越具體越好]
+
+## 待負責人確認
+- [描述] — 等待：[什麼決定]
+
+## 已知問題
+| 問題 | 優先級 | 狀態 |
+|------|--------|------|
+| [問題] | 🔴/🟡/⚪ | [狀態] |
+```
+
+### 第四步：如果有新的誤解或決策
+
+順帶執行 `/wiki-capture` 的邏輯，把這次的誤解和決策也存進去。
+
+### 第五步：確認
+
+告知 status.md 更新完成，下次 session 從哪裡開始。