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
@@ -0,0 +1,37 @@
# ingest-contract — tasks
> **唯一進度來源**,不靠對話記憶。對應 [issue #1](https://github.com/uncle6me-web/kbdb-graph-plugin/issues/1)(頂層 mira-dissolve T3)。
> 完成一項即時打勾 + 註記證據。端到端需 leo21c 部署的,標「待部署驗」,不假綠。
## A. 契約 + template slot
- [x] **3.1**`contracts/ingest-candidate.json` 進本 repo + `contracts/README.md` 標明候選≠已存(2026-06-26
- [x] **3.2** `ensureTemplate` 改 slot-diff 補丁(命中既有 → base `PATCH /templates/:id` 補缺 slot,不再 early-return);`TRIPLET_SLOTS``status`+`superseded_by`+`source_uri`+`content_hash`2026-06-26`kbdb-client.ts`+`templates.ts`
- [x] **3.2b** `ENTITY_SLOTS``gloss`(已核實現無)(2026-06-26
- [ ] **3.2c** normalize 分層 fallback 接口:exact-only 先做;semantic 留接口(待 base embedArcrun #7
## B. 寫入端 + 取代(核心)
- [x] **3.3a** `KbdbClient.updateRecord(id, values)` → base `PATCH /records/:id`2026-06-26mock 同步)
- [x] **3.3b** `src/actions/triplet-ingest.ts`Zod strict 驗證 → idempotencyuri+hash)→ **先 append 後 deprecate**。88 行純函式(2026-06-26
- [x] **3.3c** `POST /triplets/ingest` route(驗證失敗 → 422 hook,只驗證+呼叫 action)(2026-06-26
- [x] **3.4** 測試 6 案全綠:正常 / 同 hash no-op / 新 hash deprecate / 污染(bridge_score+頂層 id) 422 / rollback`vitest run` 16 passed)(2026-06-26
- [x] **3.5** 查詢 active-only`queryTriplets` 缺省 filter `status==='active'`traverse/search/neighbors 皆經此;`includeDeprecated` opt-out 供 rollback/考古)(2026-06-26
## C. MCP(⚠️ 跨 repo,需 arcrun 配合 → issue 標清)
- [x] **3.6** 圖查詢 + `refresh` **HTTP API/邏輯備好(graph 端)**`GET /graph/source/:name``POST /graph/refresh`、既有 traverse/neighbors/path/relation。**MCP 註冊薄殼仍待 arcrun 配合**(不另起 graph MCP)(2026-06-26
- [x] **3.6b** `refresh` 紅線:`graph-refresh.ts` 純被動代轉,只人發起調用觸發;無排程/webhook2026-06-26
- [x] **3.6d** 移除 graph **公開** keyword 端點(`POST /search` 收斂為 suggest-onlykeywordSearch helper 留作 suggest 內部建構塊)(2026-06-26
- [x] **3.7** `get_source``graph-source.ts` + `GET /graph/source/:name`(回 uri+anchor+block_id+content_hashactive-only,去重)。連帶加 `source_anchor` slot2026-06-26
- [x] **3.7b** ~~graph CLI~~ 延後不做(人少用、AI 用不到 → 不誤導)
> **跨 repo 待接(總管協調)**:圖工具(traverse/neighbors/source+ refresh 的 **MCP 註冊薄殼**併入 arcrun `u6u-mcp-server`KBDB MCP),待 arcrun #7 落地後兩邊接。graph 端 HTTP API 已就緒。
> **refresh 待部署**`KBDB_INGEST_URL` 未設時 `refresh` 誠實回 `forwarded:false`ingest repo T4 未就緒)。端到端待 ingest 部署驗。
## 完成準則
- 全程 zero SQL / zero migration / 無 D1·Vectorize·AI 綁定(`wrangler deploy --dry-run` bundle 乾淨)
- 所有 action ≤100 行;`vitest run` 全綠(mock client
- 端到端 ingest→graph 走通需 base 上線 + ingest repoT4)就緒 → 標「待部署驗」
- issue #1 留 open,待實證綠燈才結案