Files

T

Leo d2618758e2 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>

2026-07-17 17:04:12 +08:00

7.2 KiB

Raw Blame History

當前狀態

更新時間：2026-07-17 每次 session 結束必須更新此檔（用 /wiki-update）。

最新（2026-07-17：SDD 生命週期鐵律遷移 + SDD 位置統一）

leo 2026-07-17 拍板全體系「單一活性 SDD」制度（canonical：system-dev-template v1.15.0），本 repo 已遷移：

位置統一：舊 docs/3-specs/ 的 5 份 SDD 全數 git mv 到 system-dev/docs/3-specs/，舊位置留 README 指針。
狀態判定：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 取代）。
鋪檔：SDD-LIFECYCLE.md／pending-changes.md／sdd-guard.sh（新版，掛進 settings.json PreToolUse Write|Edit）／sdd-check.md／sdd-active-check.sh。
驗證：sdd-active-check exit 0；guard pipe-test——0 active 下寫 code 檔擋（exit 2）、寫 md 放行。
CLAUDE.md：加 SDD 鐵律段（濃縮五條＋0-active 註明「重啟開發先挑一份升 active」），並修正遷移後的舊路徑指針（wiki 路徑、SDD 路徑）。

最新（2026-06-26：issue #1 補對齊 — receiver Zod 追上 contract，PR #3 已 merge）

PR #3 已 merge 進 main（commit 13db97b）。對應 issue #1 總管補對齊 comment。

起因（契約漂移）：T3 的 strict Zod 鏡射【當時】contract；contract 之後升格（ingest#1 向量化規範）加打標欄位 → ingest 照新 contract 送會被 .strict() 擋 422。總管裁定方向 A：graph 追上 contract（contract 是凍結單一真相源，實作追它）。

完成：

✅ contracts/ingest-candidate.json 副本同步到頂層單一真相源（InkStoneCo/system-dev/docs/3-specs/mira-dissolve/）。
✅ Zod 加契約合法新欄位（保留 .strict()）：NodeSchema+id?/aliases?/embed?；EdgeSchema+predicate_embed?。
✅ 落地（向量化分工：ingest 打標、base 讀標執行、graph 不算向量）：predicate_embed 透傳進 triplet slot；node 打標（embed/gloss/aliases）存進 entity slot；id 作 node 去重鍵（同卡多邊只一筆）。persistNodes 拆獨立 action（src/actions/node-persist.ts）。
✅ 測試 +4：帶向量化欄位【通過】、bridge_score/clusters 仍【422】、同 id 去重。

新增 plugin slot（非改表、非改 contract）：triplet predicate_embed；entity embed/node_id。驗證：vitest run 23 passed；零 SQL / 無 D1·Vectorize·AI；dry-run 乾淨；action ≤100 行。

過程教訓（已記 mistakes）：PR#3 初版從 PR#2 merge 前切 → 混進 PR#2 已做的 template 1.9.x 遷移 40 檔 → 撞 main 衝突。解法＝從最新 main 重切、只 cherry-pick 補對齊那筆 code commit、瘦身後 force-push。補對齊/功能 PR 別混 template 基建遷移。

前一筆（2026-06-26：issue #1 T3 — ingest 寫入端 + graph 端 API，PR #2 已 merge）

PR #2 已 merge（commit 7a29dee，squash）。

完成：

✅ wiki 合併：舊 .claude/wiki/ → system-dev/wiki/（導入 system-dev-template）。
✅ ingest-contract SDD（docs/3-specs/ingest-contract/）+ 搬入 contracts/ingest-candidate.json（T3.1/3.8）。
✅ 寫入端 + 取代（T3.2–3.5）：POST /triplets/ingest、ensureTemplate slot-diff 補丁、updateRecord、idempotency、先 append 後 deprecate、active-only 查詢。
✅ get_source + refresh（T3.6/3.7）：GET /graph/source/:name、POST /graph/refresh（純被動代轉，未設 KBDB_INGEST_URL 時誠實回 forwarded:false）、keyword 收斂（3.6d）。

驗證：vitest run 19 passed（mock）；zero SQL / 無 D1·Vectorize·AI；dry-run 乾淨；action ≤100 行。

註：base PATCH /records/:id 已就緒（Arcrun #6 closed），ingest deprecate 即用此。

已完成（2026-06-14：按 leo 鐵律全面改寫 + 獨立成 repo）

HANDOFF 5 項待辦全做完：

✅ 改寫成走基本盤 API（核心）：21 個違規直接 SQL action 全改走 src/lib/kbdb-client.ts。寫 triplet=POST /records(template=triplet)；查圖=取 triplet records 在插件層記憶體組鄰接表跑演算法（不靠 DB VIEW）。entity 正規化降級 exact match。
✅ 刪所有 migrations（插件零建表）+ 清基本盤 action/route（block-*/entry-crud/record-crud/tag/profile/admin/partner/convert/tasks/personality）。
✅ 獨立成 repo：git init + 推 public uncle6me-web/kbdb-graph-plugin（無 Actions）。
✅ 裁剪 CLAUDE.md：移除 KBDB v3 基本盤規範，只留 graph 插件 + 🔒 鐵律 + 安裝契約。
✅ 部署繞開 GitHub：scripts/install.sh（wrangler 直推），無 .github/workflows。

驗證：wrangler deploy --dry-run 通過（bundle 無 D1/AI/Vectorize）；vitest run 10 passed（mock client）；全違規掃描零命中；所有 action ≤100 行。

同場修正的 SDD 錯誤判斷

design.md 原本「讀現狀（21 個直接 SQL）推翻鐵律、問要不要共用 D1」是讀違規現狀推翻規則的錯。已改正為 API-as-Wall（走 API，非共用 D1，零建表/零 SQL），並記進 mistakes.md。

正在做 / 阻擋

✅ PR #2（T3）、PR #3（補對齊）皆已 merge 進 main。graph repo 端實作面收斂，本 repo 無剩餘可單獨做的 task。
[🔄] 剩三項皆「不在 graph 手上」，等跨 repo 接通 / 部署（見下）。

下次 session 第一件事

main 已含 T3 + 補對齊。本 repo 端無待辦——下次動工多半是新交辦或跨 repo 接通就緒後接 MCP 薄殼。若要實際部署：等基本盤 arcrun-kbdb 上線有網址後跑 bash scripts/install.sh（自動查 CF subdomain 拼 KBDB_BASE_URL → secret → deploy）。現不空跑（避免上線打不到基本盤的殼）。

待負責人確認 / 跨 repo 接通（全通才結 issue #1）

MCP 註冊薄殼 — 圖工具（traverse/neighbors/source/refresh）併入 arcrun u6u-mcp-server。等：總管協調 arcrun，不另起 graph MCP；待 Arcrun #7 部署驗。graph 端 HTTP API 已備好。
refresh 端到端 — 等：ingest repo（T4）部署 + 設 KBDB_INGEST_URL；未設時誠實回 forwarded:false。
semantic normalize — 仍 exact-only，留接口；等：base embed（Arcrun #7，code done 待部署）。補對齊已把向量化打標（embed/predicate_embed/gloss/aliases）落地進 slot 供 base 讀，base 模組就緒即可接。

已知缺口（[→arcrun]，待基本盤補）

base PATCH /records/:id ✅ 已就緒（Arcrun #6 closed）；但 base 仍無 DELETE /records/:id → triplet/entity delete、pending confirm/reject 為 soft（不硬刪）。
語意搜尋 / embedding 屬基本盤 optional embed 模組，插件只做 keyword/exact（graph 不算向量，鐵律）。
arcrun 端 MCP/CLI 的 KBDB 薄殼仍待補；插件目前直打基本盤 HTTP API。

7.2 KiB Raw Blame History Unescape Escape