# Wishlist

system-dev-template 自身要補的功能。

---

## 1. 接關機制（開新對話自動恢復進度） ✅ 已完成（commit 39783cc）

**問題**：template 現在「接關」只靠 `CLAUDE.md` 的軟提醒「Wiki 讀取順序：status.md = session 開始第一件事」，期待 CC 開新對話自己去讀。但軟提醒擋不住「CC 讀了 CLAUDE.md 卻沒真讀 status」，使用者也無法確定它讀了沒。

**設計：雙保險（hook 自動 + 命令兜底）**

| 機制 | 角色 | 何時 |
|---|---|---|
| **SessionStart hook** | 主路徑：開 session 自動注入 status 重點，不靠 CC 自覺、不用人說 | 每次 startup/resume/clear 自動 |
| **`/wiki-recall` 命令** | Fallback：hook 沒啟動時手動接關；要完整脈絡時也用 | 使用者見沒自動接關 → 打一句 |

主路徑不靠人；命令應對 hook 失效。沒有 fallback，hook 一失效就靜默回到「全靠 CC 自覺」（正是要解決的問題）。

**要做**：
- `template/.claude/hooks/session-start-recall.sh`：注入 status.md 的「正在做 / 下次第一件事」。
- `template/.claude/settings.json`：掛 `SessionStart`（matcher `startup|resume|clear`）。
- `template/.claude/commands/wiki-recall.md`：手動接關命令（讀 status → decisions → wishlist → HANDOFF）。
- `install.sh`：偵測已有 settings.json 則不覆蓋，提示手動加 SessionStart（比照 CLAUDE.md 處理）。

**命名閉環**：init(建) → update(存,session 末) ↔ recall(接,session 初) → capture(隨時存結論)。

**配套鐵律（寫進 wiki-recall + 文件）**：status/wiki 是 **point-in-time 快照非即時狀態**。接關＝讀快照 **+ 核實快照**，不盲信。實例：某專案 status 曾寫「待 A 收尾 X」，實際 X 早完成，照舊資訊會催已完成的事。

---

## 2. Hook 強制機制（軟規範 → 硬攔截） ✅ 已完成（commit 39783cc）

**問題**：template 現在**完全沒有 hook**，所有規範（SDD 協議、wiki 維護）都是 CLAUDE.md 的軟提醒。CC 想跳過就跳過，沒有東西抓得到。

**對照 arcrun（值得 template 借鑑）**：arcrun 有一套 hook 把鐵律變強制——
- `pre-write-guard.sh` / `pre-bash-guard.sh`：違反禁令（沒讀 SDD 就動 code、寫違規檔）→ **exit 2 直接 block**，CC 跳不過。
- `session-start-load-sdd.sh`：開 session 強制注入進度 + 禁令。
- 效果：「想跳過 SDD 協議就會被抓到」，不靠自覺。

**要做（template 標配一個最小 hook 集）**：
- **SDD 協議 hook**：動 code（.ts/.go/...）前若沒對應 SDD / 沒在回覆宣告已讀 → 擋或警告。對應 template 既有的 `/sdd-check`，但從「命令要人打」升級成「hook 自動攔」。
- **SessionStart hook**：見上 §1（接關 + 注入規範）。
- **可選 pre-write guard**：讓使用者自訂專案禁令（如本 InkStoneCo 的「KBDB 禁動表」hook），template 給範本骨架。

**設計原則（抄 arcrun 的誠實限制）**：hook 擋語法層明顯違規，擋不了藏在 helper 裡的繞道 → **文檔（mindset）+ hook（底線）都不可省**，絕不在文件聲稱「不可能繞過」。hook 的價值是「想跳過會被抓到」+ 留痕可審，不是技術防偽。

**為何重要**：template 的兩大賣點（SDD 強制先設計 + wiki 持久記憶）現在都只是「請你照做」。加 hook 才從「建議」變「機制」——這正是 template 區別於「就是寫幾個 markdown」的關鍵。

---

## 3. Wiki 機敏內容防護（不想被編入的內容） ✅ 已完成

**問題**：wiki 是會被 CC 反覆讀取、可能進版控的記憶空間。有些內容不該被編入——密碼、API 金鑰、私鑰、個資。只靠口頭約束太危險：密碼/個資外洩是**不可逆**後果，光提醒 CC「別記機敏資訊」擋不住意外。

**設計：三層防護（協議 + 機械底線）**

| 層 | 機制 | 擋什麼 | 性質 |
|---|---|---|---|
| **L1** | `.claude/wiki/.wikiignore`（glob，像 .gitignore） | 整個機敏檔不編入 | 協議（CC 遵守） |
| **L2** | 行內標記 `<!-- wiki:ignore -->`…`<!-- wiki:end -->` | 檔案內某段不編入 | 協議（CC 遵守） |
| **L3** | `wiki-secret-scan.sh` hook（PreToolUse） | 機敏值真寫進 `.claude/wiki/` → exit 2 擋 | **硬攔截（機械偵測）** |

L1/L2 是使用者主動標記，L3 是自動兜底——前兩層漏掉時，寫進 wiki 那一刻 regex 攔下（密碼賦值、PEM 私鑰、AWS/GitHub/Slack/Google/Stripe 金鑰、JWT、連線字串帳密、台灣身分證、信用卡號）。

**已做**：
- `template/.claude/wiki/.wikiignore`：L1 範本（預設排除 `.env`/`*.pem`/`*secret*` 等）。
- `template/.claude/hooks/wiki-secret-scan.sh`：L3 hook，只掃 `.claude/wiki/**` 寫入，`wiki-secret-ok` 行尾標記可豁免誤判。
- `settings.json`：PreToolUse(Write|Edit) 加掛。
- `wiki-init.md` / `wiki-capture.md` / `SKILL.md`：寫入 L1+L2 協議。

**設計原則（抄 §2 的誠實限制）**：L1/L2 靠 CC 自律、L3 靠 regex 特徵（有偽陽/偽陰）。這是「減少**意外**外洩」的機制，不是保險箱——真正的密鑰本就不該進版控。絕不聲稱「不可能繞過」。

---

## 4. 模組化安裝（Wiki / SDD 可分開裝） ✅ 已完成

**問題**：有時只需要 wiki，不需要 SDD（反之亦然）。原 install.sh 一律全裝。

**決策（為何不 fork）**：使用者多半非工程背景，最怕「我要去哪個 repo」。一個入口 + 模組選單最友善。fork 成獨立 repo 維護成本翻倍、現在只有 2 個功能略嫌早。等未來功能多到 3+ 個再演進成「模板組合器」（meta-template 把子模板拉進來）——模組邊界先在 install.sh 劃好，當作拆分前置。

**已做**：
- `install.sh` 支援 `--wiki` / `--sdd` / `--all`（預設），無參數 + 有 tty 則互動詢問 1/2/3；`curl|bash` 無 tty 安全預設 `--all`。
- settings.json 的 hooks 依選的模組**自動組裝**（不再下載單一靜態檔）。
- README 補上模組安裝與 `.wikiignore` 三層防護說明。

**未來演進**：功能達 3+ 個 → 拆成獨立模板 repo，本 repo 轉「組合器」把它們拉進來。