docs(sdd): SDD 生命週期鐵律遷移 + SDD 位置統一到 system-dev/docs/3-specs/

- 位置統一:舊 docs/3-specs/ 五份 SDD git mv 到 system-dev/docs/3-specs/,舊位置留 README 指針
- 狀態判定:0 份 active(無現行開發,合法);paused×3(ingest-contract/kbdb-graph-extraction/plugin-install,等跨 repo 接通);closed×2 入 archive/(arcrun-key-auth/blocks-edit-api 死件,附封存原因)
- 鋪檔(自 system-dev-template v1.15.0):SDD-LIFECYCLE.md、pending-changes.md、sdd-guard.sh 新版、sdd-check.md、sdd-active-check.sh
- hook 掛載:settings.json PreToolUse Write|Edit 加 sdd-guard.sh
- CLAUDE.md:SDD 鐵律段(濃縮五條+0-active 註明重啟先升 active)+修正遷移後舊路徑
- 驗證:sdd-active-check exit 0;guard pipe-test 0-active 擋 code 寫入(exit 2)/md 放行(exit 0)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-17 17:03:58 +08:00
parent b53c5c94a9
commit d2618758e2
20 changed files with 279 additions and 21 deletions
+18 -6
View File
@@ -3,12 +3,24 @@
> **上游約束(InkStoneCo 總管)**:此目錄(原 matrix/kbdb,已改名 kbdb-graph-plugin)是 InkStoneCo 子專案,受頂層知識庫約束。
> 動工前讀 `github.com/uncle6me-web/InkStoneCo` 的 CLAUDE.md + `docs/3-specs/matrix-rearrange/`。
> **定位(leo 2026-06-13**:此 repo = **KBDB-graph 插件**triplet 採集 + graph 查詢),類比 **Apache AGE 之於 Postgres**。基本盤 = `arcrun/kbdb`D1 三表 + CRUD API),**不在這裡、不動它**。
> **本目錄專屬交棒見 `docs/HANDOFF-kbdb-plugin.md`**SDD 見 `docs/3-specs/kbdb-graph-extraction/`
> **本目錄專屬交棒見 `docs/HANDOFF-kbdb-plugin.md`**SDD 見 `system-dev/docs/3-specs/`2026-07-17 已從舊 `docs/3-specs/` 遷移統一)
> 本檔案由 Claude Code 自動讀取。所有在此目錄下的開發必須遵守以下規則。
---
## 📐 SDD 生命週期鐵律(leo 2026-07-17 拍板,全文見 `system-dev/docs/3-specs/SDD-LIFECYCLE.md`
1. **單一活性**:任何時刻整個 repo 最多一份 `status: active` 的 SDD,所有開發任務唯一對應它的 tasks;找不到對應任務 → 停下來問,不准直接做。
2. **禁止自行建立 SDD**:澄清問題→回答不動文件;任務層變更→更新現行 SDD 的 tasks(標日期原因);規格層變更→走第 3 條。
3. **規格變更只有一條路**proposal 寫進 `system-dev/docs/3-specs/pending-changes.md`(摘要+原因+影響分析)→ **停止**等使用者「confirm」。
4. **開新 SDD 的唯一時機**confirm 後——先把舊 SDD 未完成任務逐條搬入新 SDD(做完前不准寫 code)→ 舊的標 closed + superseded_by 移入 `archive/` → 列搬移/作廢清單請最終確認。
5. **每次 session 開始**:讀 active SDD 與 pending-changes.md,回報三個數字(現行規格〈名稱〉/未完成任務 N/待裁決 proposal M)。
> **本 repo 現況(2026-07-17****0 份 active**(無現行開發,實作面已收斂、剩跨 repo 接通)——0 份 active 合法。三份 `paused`ingest-contract / kbdb-graph-extraction / plugin-install,等基本盤部署/跨 repo 接通),兩份 `closed` 入 `archive/`。**重啟開發時先挑一份升 active**(一份、只能一份),再動 code——sdd-guard hook 會擋 0-active 下的 code 寫入。
---
## 🔒 KBDB 鐵律(leo 2026-06-14 拍板,最高原則,違反會被 hook exit 2 擋下)
決策全文:`InkStoneCo/docs/3-specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md`
@@ -33,7 +45,7 @@
GET /records/by-template/:tpl ─ entity 正規化 → template='entity'exact match
─ 唯一對外通道 = src/lib/kbdb-client.ts
```
基本盤 API 契約詳見 `docs/3-specs/kbdb-graph-extraction/design.md`
基本盤 API 契約詳見 `system-dev/docs/3-specs/kbdb-graph-extraction/design.md`
**基本盤缺口**base 無 `PUT/DELETE /records/:id`、無 vectorize 語意搜尋)標 `[→arcrun]`,不得為此自建表。embedding/語意搜尋屬基本盤 optional embed 模組,**不是插件職責**。
---
@@ -42,11 +54,11 @@
| 檔案 | 時機 | 用途 |
|------|------|------|
| `.claude/wiki/status.md` | session 開始第一件事 | 當前進度、下一步 |
| `.claude/wiki/mistakes.md` | 做新功能前 | 已知誤解、避坑清單 |
| `.claude/wiki/decisions-summary.md` | 設計判斷時 | 架構決策摘要 |
| `system-dev/wiki/status.md` | session 開始第一件事 | 當前進度、下一步 |
| `system-dev/wiki/mistakes.md` | 做新功能前 | 已知誤解、避坑清單 |
| `system-dev/wiki/decisions-summary.md` | 設計判斷時 | 架構決策摘要 |
文件分類規則見 `docs/README.md`SDD 在 `docs/3-specs/[子系統]/`design.md + tasks.md),動手前必須有這兩個檔案。
文件分類規則見 `docs/README.md`SDD 在 `system-dev/docs/3-specs/[子系統]/`design.md + tasks.md),動手前必須有這兩個檔案,且遵守上方生命週期鐵律
session 結束用 `/wiki-update` 更新 status.md,被糾正後 `/wiki-capture` 寫進 mistakes.md。
---