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:
@@ -4,6 +4,26 @@
|
||||
|
||||
---
|
||||
|
||||
## 生命週期（單一活性鐵律，全文見 `system-dev/docs/3-specs/SDD-LIFECYCLE.md`）
|
||||
|
||||
五條鐵律摘要：
|
||||
|
||||
1. **單一活性**：任何時刻整個 repo 只允許一份 `status: active` 的 SDD；所有開發任務對應它的 tasks，找不到對應任務 → 停下來問，不准直接做。
|
||||
2. **禁止自行建立 SDD**：澄清問題→回答不動文件；任務層變更→更新現行 SDD 的 tasks（標日期與原因）；規格層變更→走第 3 條。
|
||||
3. **規格變更只有一條路**：change proposal 寫進 `system-dev/docs/3-specs/pending-changes.md`（摘要＋觸發原因＋影響分析），然後**停止**等使用者「confirm」。
|
||||
4. **開新 SDD 的唯一時機**：使用者 confirm 後——先把舊 SDD 未完成任務逐條搬入新 SDD（做完前不准寫 code）→ 舊的標 `closed` + `superseded_by` 移入 `archive/` → 新 SDD changelog 記繼承 → 列搬移/作廢清單請最終確認。
|
||||
5. **每次 session 開始**先讀 active SDD 與 pending-changes.md，回報三個數字：
|
||||
|
||||
```
|
||||
📐 現行規格：〈SDD 名稱〉
|
||||
📋 未完成任務：N
|
||||
⚖️ 待裁決 proposal：M
|
||||
```
|
||||
|
||||
若出現**兩份 active＝規則已被違反，當場糾正**（收斂到一份，其餘 paused/closed）。
|
||||
|
||||
---
|
||||
|
||||
## 執行流程
|
||||
|
||||
### 第一步：理解任務
|
||||
|
||||
+81
-13
@@ -1,10 +1,16 @@
|
||||
#!/bin/bash
|
||||
# PreToolUse hook — 動 code 前檢查有沒有對應 SDD
|
||||
# PreToolUse hook — 動 code 前檢查 SDD ＋ 單一活性 SDD 鐵律（issue #6）
|
||||
# wishlist §2：把 /sdd-check 從「命令要人打」升級成「hook 自動攔」。
|
||||
# 生命週期規則全文：system-dev/docs/3-specs/SDD-LIFECYCLE.md
|
||||
#
|
||||
# 掛在 settings.json 的 PreToolUse（matcher: Write|Edit）。
|
||||
# stdin 收到 JSON：{ tool_name, tool_input: { file_path, ... } }
|
||||
# 行為：動到 code 檔（.ts/.go/...）但 system-dev/docs/3-specs/ 下沒有任何 SDD → 警告（exit 2 擋）。
|
||||
# 行為：
|
||||
# 1. status: active 的 SDD > 1 份 → 單一活性鐵律已被違反，**不論寫什麼檔**一律擋（exit 2），
|
||||
# 先收斂到一份再說。
|
||||
# 2. 動 code 檔（.ts/.go/...）→ 需要「恰好 1 份」active SDD；0 份 → 擋。
|
||||
# 3. 向下相容：3-specs 下完全沒有任何 design.md 帶 frontmatter（老 repo 尚未遷移生命週期制度）
|
||||
# → 退回舊行為：有 design.md 就放行＋提醒，沒有才擋。避免 template update 後老 repo 立刻全紅。
|
||||
#
|
||||
# 誠實限制（抄 arcrun）：只擋語法層明顯違規（直接寫 code 檔）。
|
||||
# 藏在 helper 裡、用 bash 繞道的改動擋不到。
|
||||
@@ -24,6 +30,42 @@ fi
|
||||
# 拿不到路徑 → 不擋（容錯，寧可放過也不誤殺）
|
||||
[ -z "$FILE_PATH" ] && exit 0
|
||||
|
||||
SPECS_DIR="system-dev/docs/3-specs"
|
||||
|
||||
# ── 統計 active / frontmatter ──────────────────────
|
||||
# 排除 archive/（已封存）與 TEMPLATE（範本自帶 status: draft frontmatter，不算數——
|
||||
# 否則 update 一鋪新版 TEMPLATE-sdd，老 repo 就被誤判「已遷移」而全紅，向下相容破功）。
|
||||
# frontmatter 判定＝design.md 前 10 行有 ^status: 行（機器可查，見 SDD-LIFECYCLE.md）。
|
||||
ACTIVE_COUNT=0
|
||||
FM_COUNT=0
|
||||
ACTIVE_LIST=""
|
||||
if [ -d "$SPECS_DIR" ]; then
|
||||
while IFS= read -r f; do
|
||||
[ -n "$f" ] || continue
|
||||
HEAD10=$(head -10 "$f" 2>/dev/null || true)
|
||||
if printf '%s\n' "$HEAD10" | grep -q '^status:[[:space:]]*'; then
|
||||
FM_COUNT=$((FM_COUNT + 1))
|
||||
if printf '%s\n' "$HEAD10" | grep -q '^status:[[:space:]]*active'; then
|
||||
ACTIVE_COUNT=$((ACTIVE_COUNT + 1))
|
||||
ACTIVE_LIST="${ACTIVE_LIST} • ${f}
|
||||
"
|
||||
fi
|
||||
fi
|
||||
done < <(find "$SPECS_DIR" -name 'design.md' -not -path '*TEMPLATE*' -not -path '*/archive/*' 2>/dev/null)
|
||||
fi
|
||||
|
||||
# ── 鐵律 1：單一活性被違反（active > 1）→ 不論寫什麼檔一律擋 ──
|
||||
if [ "$ACTIVE_COUNT" -gt 1 ]; then
|
||||
cat >&2 <<EOF
|
||||
🚫 SDD 單一活性鐵律違反：偵測到 ${ACTIVE_COUNT} 份 status: active 的 SDD（任何時刻整個 repo 最多一份）：
|
||||
${ACTIVE_LIST}
|
||||
請先收斂到一份：其餘改 status: paused / closed（closed 且被取代者填 superseded_by 並移入 3-specs/archive/）。
|
||||
規則全文見 system-dev/docs/3-specs/SDD-LIFECYCLE.md。收斂前擋下所有寫檔。
|
||||
（本 hook 攔 Write/Edit；修 frontmatter 可用 bash 直改，或由人裁決哪份是現行。）
|
||||
EOF
|
||||
exit 2
|
||||
fi
|
||||
|
||||
# 只管 code 檔。docs/markdown/設定檔等放行。
|
||||
case "$FILE_PATH" in
|
||||
*.ts|*.tsx|*.js|*.jsx|*.go|*.py|*.rs|*.java|*.rb|*.php|*.c|*.cpp|*.h|*.hpp|*.swift|*.kt) ;;
|
||||
@@ -36,28 +78,54 @@ case "$FILE_PATH" in
|
||||
*_test.*|*.test.*|*.spec.*|*/tests/*|*/test/*) exit 0 ;;
|
||||
esac
|
||||
|
||||
# system-dev/docs/3-specs/ 下完全沒有 design.md → 攔
|
||||
SDD_COUNT=0
|
||||
if [ -d "system-dev/docs/3-specs" ]; then
|
||||
SDD_COUNT=$(find system-dev/docs/3-specs -name 'design.md' -not -path '*TEMPLATE*' 2>/dev/null | wc -l | tr -d ' ')
|
||||
fi
|
||||
# ── 向下相容：整個 3-specs 沒有任何帶 frontmatter 的 design.md ──
|
||||
# ＝老 repo 還沒遷移生命週期制度 → 退回舊行為（有 design.md 就放行＋提醒），
|
||||
# 避免 template update 一裝新 hook，老 repo 所有 code 寫入立刻全紅。
|
||||
if [ "$FM_COUNT" -eq 0 ]; then
|
||||
SDD_COUNT=0
|
||||
if [ -d "$SPECS_DIR" ]; then
|
||||
SDD_COUNT=$(find "$SPECS_DIR" -name 'design.md' -not -path '*TEMPLATE*' -not -path '*/archive/*' 2>/dev/null | wc -l | tr -d ' ')
|
||||
fi
|
||||
|
||||
if [ "$SDD_COUNT" -eq 0 ]; then
|
||||
if [ "$SDD_COUNT" -eq 0 ]; then
|
||||
cat >&2 <<EOF
|
||||
🚫 SDD 協議攔截：要動 code 檔 ($FILE_PATH)，但 system-dev/docs/3-specs/ 下找不到任何 SDD。
|
||||
🚫 SDD 協議攔截：要動 code 檔 ($FILE_PATH)，但 ${SPECS_DIR}/ 下找不到任何 SDD。
|
||||
|
||||
絕對鐵律：任何 code 變動前必須有對應 SDD（design.md）。
|
||||
絕對鐵律：任何 code 變動前必須有對應 SDD（design.md），且遵守單一活性生命週期
|
||||
（system-dev/docs/3-specs/SDD-LIFECYCLE.md）。
|
||||
|
||||
請先：
|
||||
1. 確認這個改動屬於哪個子系統
|
||||
2. 在 system-dev/docs/3-specs/[子系統]/ 建立 design.md（可用 /sdd-check 協助）
|
||||
2. 在 ${SPECS_DIR}/[子系統]/ 建立 design.md（可用 /sdd-check 協助），frontmatter 標 status: active
|
||||
3. 在回覆開頭宣告已讀 SDD + 對應 task
|
||||
|
||||
小修改（修 bug、改文字）若確定豁免，請明確說明範圍後由人放行。
|
||||
EOF
|
||||
exit 2
|
||||
fi
|
||||
|
||||
# 舊行為放行 + 提醒遷移（stderr 警告，不擋）
|
||||
echo "📋 提醒：${SPECS_DIR}/ 有 SDD 但尚未掛生命週期 frontmatter（老結構）。動手前確認已讀對應 design.md；建議依 SDD-LIFECYCLE.md 補 status 標記（現行那份標 active）。" >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ── 新行為：寫 code 檔需「恰好 1 份」active SDD ──
|
||||
if [ "$ACTIVE_COUNT" -eq 0 ]; then
|
||||
cat >&2 <<EOF
|
||||
🚫 SDD 協議攔截：要動 code 檔 ($FILE_PATH)，但 ${SPECS_DIR}/ 下沒有任何 status: active 的 SDD。
|
||||
|
||||
單一活性鐵律：所有開發任務唯一對應源＝那份 active SDD（規則見 system-dev/docs/3-specs/SDD-LIFECYCLE.md）。
|
||||
|
||||
請先（擇一，都是人的決定，CC 不得自行建 SDD）：
|
||||
1. 把現行規格的 design.md frontmatter 標成 status: active（一份、只能一份）
|
||||
2. 或依 SDD-LIFECYCLE.md 第 3、4 條：proposal 進 pending-changes.md → 使用者 confirm → 開新 SDD 標 active
|
||||
然後在回覆開頭宣告已讀 active SDD + 對應 task。
|
||||
|
||||
小修改（修 bug、改文字）若確定豁免，請明確說明範圍後由人放行。
|
||||
EOF
|
||||
exit 2
|
||||
fi
|
||||
|
||||
# 有 SDD：放行，但留痕提醒要宣告（stderr 警告，不擋）
|
||||
echo "📋 提醒：system-dev/docs/3-specs/ 下有 SDD。動手前請確認已讀對應 design.md 並在回覆宣告。" >&2
|
||||
# 恰好 1 份 active：放行，留痕提醒要宣告（stderr 警告，不擋）
|
||||
printf '📋 提醒：現行 active SDD＝\n%s動手前請確認已讀它的 design.md、對應到 tasks，並在回覆宣告。\n' "$ACTIVE_LIST" >&2
|
||||
exit 0
|
||||
|
||||
@@ -8,6 +8,11 @@
|
||||
"type": "command",
|
||||
"command": "bash .claude/hooks/pre-write-guard-no-table.sh",
|
||||
"timeout": 5
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"command": "bash .claude/hooks/sdd-guard.sh",
|
||||
"timeout": 5
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -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。
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
# 已遷移
|
||||
|
||||
本目錄的 SDD 已於 2026-07-17 全數遷移至 **`system-dev/docs/3-specs/`**（依 2026-06-14 位置統一規則）。
|
||||
|
||||
- 現行/暫停 SDD：`system-dev/docs/3-specs/`（ingest-contract / kbdb-graph-extraction / plugin-install）
|
||||
- 已封存死件：`system-dev/docs/3-specs/archive/`（arcrun-key-auth / blocks-edit-api）
|
||||
- 生命週期鐵律：`system-dev/docs/3-specs/SDD-LIFECYCLE.md`
|
||||
|
||||
請勿在此新增 SDD。
|
||||
@@ -0,0 +1,39 @@
|
||||
# SDD 生命週期鐵律（不可違反）
|
||||
|
||||
> 來源：leo 2026-07-17 拍板。
|
||||
> 適用：`system-dev/docs/3-specs/` 下的「規格 SDD」（requirements/design/tasks 三件式資料夾）。
|
||||
> **不適用**：派工表／sprint 檔、journeys/ 卷宗、TEMPLATE-sdd、README、pending-changes.md——它們不是 SDD，不掛 status。
|
||||
|
||||
## 狀態標記（機器可查）
|
||||
|
||||
每個 SDD 資料夾的 `design.md` 最上方掛 YAML frontmatter：
|
||||
|
||||
```yaml
|
||||
---
|
||||
status: active # active | draft | paused | closed
|
||||
superseded_by: "" # closed 且被取代時填接替的 SDD 資料夾名
|
||||
---
|
||||
```
|
||||
|
||||
- `active`：現行規格，全 repo 開發任務唯一對應源。**任何時刻整個 repo 最多一份。**
|
||||
- `draft`：起草中，尚未採納。
|
||||
- `paused`：動過工、暫停中；恢復＝升回 active（先收掉現任 active）或被新 SDD 繼承。
|
||||
- `closed`：已完成或被取代；被取代者填 `superseded_by` 並移入 `3-specs/archive/`。
|
||||
|
||||
## 五條鐵律
|
||||
|
||||
1. **單一活性**：任何時刻只允許一份 `status: active`。所有開發任務必須對應這份 SDD 的 tasks。找不到對應任務 → 停下來問，不准直接做。
|
||||
2. **禁止自行建立 SDD**：CC 在任何情況下不得主動建新 SDD。收到使用者意見先分類：澄清問題→回答即可不動文件；任務層變更（不影響核心設計）→更新現行 SDD 的 tasks 區段並標日期與原因；規格層變更（核心設計/方向改變）→走第 3 條，不准直接改 spec。
|
||||
3. **規格變更只有一條路**：產出 change proposal 寫入 `system-dev/docs/3-specs/pending-changes.md`（變更摘要與觸發原因＋影響分析：現行 SDD 哪些任務作廢/修改/不受影響/尚未完成），然後**停止**，等使用者明說「confirm」。沒 confirm 就繼續依現行 SDD 工作。多個 proposal 可並存緩衝區、由人一次裁決——CC 的速度導向影響分析，不是規格增生。
|
||||
4. **開新 SDD 的唯一時機**：使用者 confirm 一份規格層 proposal 時，依序：
|
||||
a. 舊 SDD 未完成且仍有效的任務**逐條搬入**新 SDD 的 tasks——**這步做完前不准寫任何程式碼**（強迫顯式盤點，遺漏會在 d 的清單被看到，而不是三天後才發現）。
|
||||
b. 舊 SDD frontmatter 改 `status: closed, superseded_by: <新SDD>`，資料夾移入 `3-specs/archive/`。
|
||||
c. 新 SDD 的 changelog 首行記錄：繼承自哪份、為何取代。
|
||||
d. 向使用者列出「已搬移任務清單」與「已作廢任務清單」請求最終確認。
|
||||
5. **每次 session 開始**：先讀現行 active SDD 與 pending-changes.md，回報三個數字——「現行規格〈名稱〉＋未完成任務 N＋待裁決 proposal M」——再開始工作。若回報出現兩份 active＝規則已被違反，當場糾正。
|
||||
|
||||
## 硬約束（不信任單點自律，用結構保證不變量）
|
||||
|
||||
- `.claude/hooks/sdd-guard.sh`（PreToolUse Write|Edit）：active 數 >1 → 任何寫檔一律擋；寫 code 檔需恰好 1 份 active。
|
||||
- `scripts/sdd-active-check.sh`：獨立檢查，pre-commit / CI 可掛，違反 exit 1。
|
||||
- 誠實限制：hook 只擋語法層明顯違規，繞道可行但留痕可審；不聲稱不可繞過。
|
||||
+7
@@ -1,3 +1,10 @@
|
||||
---
|
||||
status: closed # active | draft | paused | closed（生命週期鐵律見 ../../SDD-LIFECYCLE.md）
|
||||
superseded_by: ""
|
||||
---
|
||||
|
||||
> **封存（2026-07-17）**：舊 KBDB 時代草稿（等 richblack review，帳號已 suspend）。key auth 屬基本盤 arcrun/kbdb 職責，非本插件範圍（2026-06-14 API-as-Wall 改寫後失效）。
|
||||
|
||||
# KBDB — Arcrun Key Auth
|
||||
|
||||
> 建立：2026-05-05
|
||||
+7
@@ -1,3 +1,10 @@
|
||||
---
|
||||
status: closed # active | draft | paused | closed（生命週期鐵律見 ../../SDD-LIFECYCLE.md）
|
||||
superseded_by: ""
|
||||
---
|
||||
|
||||
> **封存（2026-07-17）**：基於舊「萬物皆 Block／blocks 表」架構，該架構已判定為違規殘留並刪除（2026-06-14 改寫）；base `PATCH /records/:id` 已由 Arcrun #6 實作取代本需求。
|
||||
|
||||
# KBDB — Blocks Edit API
|
||||
|
||||
> **建立**：2026-05-06
|
||||
+5
@@ -1,3 +1,8 @@
|
||||
---
|
||||
status: paused # active | draft | paused | closed（生命週期鐵律見 ../SDD-LIFECYCLE.md）
|
||||
superseded_by: ""
|
||||
---
|
||||
|
||||
# ingest-contract — 設計
|
||||
|
||||
> **藍圖在頂層**：本 SDD 只放 **kbdb-graph-plugin 內部實作細節**。跨專案脈絡（為什麼拆 ingest/graph、mira 蒸發、整體資料流）見 InkStoneCo `docs/3-specs/mira-dissolve/`（design + requirements）。
|
||||
+5
@@ -1,3 +1,8 @@
|
||||
---
|
||||
status: paused # active | draft | paused | closed（生命週期鐵律見 ../SDD-LIFECYCLE.md）
|
||||
superseded_by: ""
|
||||
---
|
||||
|
||||
# KBDB-graph 抽出 — Design
|
||||
|
||||
> 建立：2026-06-14
|
||||
@@ -0,0 +1,15 @@
|
||||
# Pending Changes（規格變更緩衝區）
|
||||
|
||||
> 規則來源：`SDD-LIFECYCLE.md` 第 3、4 條。
|
||||
> 規格層變更（核心設計/方向改變）**只有這一條路**：CC 把 change proposal 寫進「待裁決」——
|
||||
> 變更摘要與觸發原因＋影響分析（現行 SDD 哪些任務作廢/修改/不受影響/尚未完成）——然後**停止**，
|
||||
> 等使用者明說「confirm」才依第 4 條開新 SDD；沒 confirm 就繼續依現行 SDD 工作。
|
||||
> 多個 proposal 可並存，由人一次裁決。本檔不是 SDD，不掛 status。
|
||||
|
||||
## 待裁決
|
||||
|
||||
（無）
|
||||
|
||||
## 已裁決
|
||||
|
||||
（無——裁決後從「待裁決」移到這裡留底，標 confirmed / rejected ＋ 日期。）
|
||||
+5
@@ -1,3 +1,8 @@
|
||||
---
|
||||
status: paused # active | draft | paused | closed（生命週期鐵律見 ../SDD-LIFECYCLE.md）
|
||||
superseded_by: ""
|
||||
---
|
||||
|
||||
# KBDB-graph 插件安裝 — Design
|
||||
|
||||
## 目標
|
||||
Executable
+49
@@ -0,0 +1,49 @@
|
||||
#!/bin/bash
|
||||
# sdd-active-check.sh — 單一活性 SDD 獨立硬約束（SDD 生命週期鐵律，issue #6）
|
||||
# 規則全文：system-dev/docs/3-specs/SDD-LIFECYCLE.md
|
||||
#
|
||||
# 用法：bash sdd-active-check.sh [specs目錄]
|
||||
# 參數 1（可選）＝specs 目錄，預設 system-dev/docs/3-specs
|
||||
#
|
||||
# 行為：統計 status: active 的 design.md（design.md 前 10 行有 ^status: active，
|
||||
# 排除 archive/ 與 TEMPLATE）——
|
||||
# >1 份 → stderr 列出清單，exit 1（違反單一活性）
|
||||
# ≤1 份 → exit 0
|
||||
#
|
||||
# pre-commit 掛法（.git/hooks/pre-commit，記得 chmod +x）：
|
||||
# #!/bin/sh
|
||||
# bash system-dev/scripts/sdd-active-check.sh || exit 1
|
||||
# CI 也是同一行，違反即紅。
|
||||
#
|
||||
# 誠實限制：與 sdd-guard.sh 同精神——只做語法層機械檢查，繞道可行但留痕可審，
|
||||
# 不聲稱不可繞過。價值是「不變量被違反時一定有機器出聲」。
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SPECS_DIR="${1:-system-dev/docs/3-specs}"
|
||||
|
||||
# 沒有 specs 目錄（沒裝 SDD 模組）→ 無事可查，放行
|
||||
[ -d "$SPECS_DIR" ] || exit 0
|
||||
|
||||
ACTIVE_COUNT=0
|
||||
ACTIVE_LIST=""
|
||||
while IFS= read -r f; do
|
||||
[ -n "$f" ] || continue
|
||||
if head -10 "$f" 2>/dev/null | grep -q '^status:[[:space:]]*active'; then
|
||||
ACTIVE_COUNT=$((ACTIVE_COUNT + 1))
|
||||
ACTIVE_LIST="${ACTIVE_LIST} • ${f}
|
||||
"
|
||||
fi
|
||||
done < <(find "$SPECS_DIR" -name 'design.md' -not -path '*TEMPLATE*' -not -path '*/archive/*' 2>/dev/null)
|
||||
|
||||
if [ "$ACTIVE_COUNT" -gt 1 ]; then
|
||||
cat >&2 <<EOF
|
||||
🚫 SDD 單一活性鐵律違反：${SPECS_DIR}/ 下有 ${ACTIVE_COUNT} 份 status: active 的 SDD（任何時刻最多一份）：
|
||||
${ACTIVE_LIST}
|
||||
請收斂到一份：其餘改 status: paused / closed（closed 且被取代者填 superseded_by 並移入 archive/）。
|
||||
規則見 system-dev/docs/3-specs/SDD-LIFECYCLE.md。
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -1,10 +1,22 @@
|
||||
# 當前狀態
|
||||
|
||||
> 更新時間：2026-06-26
|
||||
> 更新時間：2026-07-17
|
||||
> 每次 session 結束必須更新此檔（用 /wiki-update）。
|
||||
|
||||
---
|
||||
|
||||
## 最新（2026-07-17：SDD 生命週期鐵律遷移 + SDD 位置統一）
|
||||
|
||||
leo 2026-07-17 拍板全體系「單一活性 SDD」制度（canonical：system-dev-template v1.15.0），本 repo 已遷移：
|
||||
|
||||
1. **位置統一**：舊 `docs/3-specs/` 的 5 份 SDD 全數 `git mv` 到 `system-dev/docs/3-specs/`，舊位置留 README 指針。
|
||||
2. **狀態判定**：**0 份 active**（無現行開發——實作面 2026-06-26 已收斂，剩跨 repo 接通，合法）。三份 `paused`：ingest-contract／kbdb-graph-extraction／plugin-install（等基本盤部署／跨 repo）。兩份 `closed` 入 `archive/`：arcrun-key-auth（舊 KBDB 時代死件）、blocks-edit-api（舊 blocks 表架構死件，已被 Arcrun #6 取代）。
|
||||
3. **鋪檔**：SDD-LIFECYCLE.md／pending-changes.md／sdd-guard.sh（新版，掛進 settings.json PreToolUse Write|Edit）／sdd-check.md／sdd-active-check.sh。
|
||||
4. **驗證**：sdd-active-check exit 0；guard pipe-test——0 active 下寫 code 檔擋（exit 2）、寫 md 放行。
|
||||
5. **CLAUDE.md**：加 SDD 鐵律段（濃縮五條＋0-active 註明「重啟開發先挑一份升 active」），並修正遷移後的舊路徑指針（wiki 路徑、SDD 路徑）。
|
||||
|
||||
---
|
||||
|
||||
## 最新（2026-06-26：issue #1 補對齊 — receiver Zod 追上 contract，PR #3 已 merge）
|
||||
|
||||
[PR #3](https://github.com/uncle6me-web/kbdb-graph-plugin/pull/3) 已 merge 進 main（commit `13db97b`）。對應 [issue #1](https://github.com/uncle6me-web/kbdb-graph-plugin/issues/1) 總管補對齊 comment。
|
||||
|
||||
Reference in New Issue
Block a user