chore(sdd): SDD 生命週期鐵律遷移(canonical template v1.15.0)

- 鋪檔 SDD-LIFECYCLE.md / pending-changes.md / 新版 sdd-guard.sh / sdd-check.md / sdd-active-check.sh
- ingest-pipeline design.md 掛 status: paused(實作 18/19 完成、部署收尾懸置、無現行開發)→ 0 active 合法
- CLAUDE.md 加 SDD 鐵律段(濃縮五條+現況註記)
- wiki status 更新+記 PR #3 src 管線只在 github-dead/main 的斷層

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-17 17:05:49 +08:00
parent 6500d7fda4
commit 4137043be2
8 changed files with 240 additions and 28 deletions
+20
View File
@@ -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
⚖️ 待裁決 proposalM
```
若出現**兩份 active=規則已被違反,當場糾正**(收斂到一份,其餘 paused/closed)。
---
## 執行流程
### 第一步:理解任務
+82 -14
View File
@@ -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 的 PreToolUsematcher: 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 / closedclosed 且被取代者填 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
cat >&2 <<EOF
🚫 SDD 協議攔截:要動 code 檔 ($FILE_PATH),但 system-dev/docs/3-specs/ 下找不到任何 SDD。
if [ "$SDD_COUNT" -eq 0 ]; then
cat >&2 <<EOF
🚫 SDD 協議攔截:要動 code 檔 ($FILE_PATH),但 ${SPECS_DIR}/ 下找不到任何 SDD。
絕對鐵律:任何 code 變動前必須有對應 SDDdesign.md
絕對鐵律:任何 code 變動前必須有對應 SDDdesign.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
+12
View File
@@ -9,6 +9,18 @@
---
## 📐 SDD 生命週期鐵律(全文:`system-dev/docs/3-specs/SDD-LIFECYCLE.md`2026-07-17 leo 拍板)
1. **單一活性**:全 repo 任何時刻最多一份 `status: active` 的 SDD,所有開發任務唯一對應它的 tasks;找不到對應任務→停下來問。
2. **禁止自建 SDD**:CC 任何情況不得主動開新 SDD;任務層變更改現行 tasks 標日期,規格層變更走第 3 條。
3. **規格變更只有一條路**proposal 寫入 `system-dev/docs/3-specs/pending-changes.md` 後**停止**,等使用者明說 confirm;沒 confirm 就照現行 SDD 繼續。
4. **開新 SDD 先搬任務**confirm 後先把舊 SDD 未完成任務逐條搬入新 SDD——搬完前不准寫任何程式碼;舊的標 closed+superseded_by 移入 archive/。
5. **session 開始三數字回報**:「現行規格〈名稱〉+未完成任務 N+待裁決 proposal M」,回報出現兩份 active=當場糾正。
> **本 repo 現況(2026-07-17**:唯一 SDD `ingest-pipeline` 標 `status: paused`(實作 18/19 完成,剩 Worker 部署+端到端驗證懸置)→ **目前 0 份 active,合法**(無現行開發)。要恢復開發=由人把 ingest-pipeline 升回 active。硬約束:`.claude/hooks/sdd-guard.sh`PreToolUse 擋無 active 時寫 code 檔)+ `system-dev/scripts/sdd-active-check.sh`(獨立檢查,可掛 pre-commit/CI)。
---
## 🔒 ingest 鐵律(leo 2026-06-26 拍板)
1. **純餵食器,不碰儲存** — ingest 只 POST 候選 envelope 給 graph 的寫入 API**不直連 base、不碰 D1/Vectorize、不碰任何表**。牆是「儲存」不是「運算」:准做萃取(LLM 呼叫),不准碰儲存。
+39
View File
@@ -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 只擋語法層明顯違規,繞道可行但留痕可審;不聲稱不可繞過。
@@ -1,3 +1,12 @@
---
status: paused
superseded_by: ""
---
<!-- status 判定(2026-07-17 SDD 生命週期遷移):實作 18/19 完成(PR #3 merge 於舊 GitHub main、
gitea main 另有 CLI 路徑 B 07-05),剩「Worker 部署+端到端 ingest→graph 驗證」自 06-26 懸置,
目前無進行中開發 session → paused。恢復部署收尾時由人升回 active(全 repo 同時最多一份 active)。 -->
# ingest pipeline — Design
> 對應 requirements.md。**架構設計(envelope 契約、職責切割、normalize 歸屬、MCP 邊界、模型策略)在 InkStoneCo `docs/3-specs/mira-dissolve/design.md`。本檔只放 ingest 內部設計。**
@@ -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 日期。)
+49
View File
@@ -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.mddesign.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 / closedclosed 且被取代者填 superseded_by 並移入 archive/)。
規則見 system-dev/docs/3-specs/SDD-LIFECYCLE.md。
EOF
exit 1
fi
exit 0
+14 -14
View File
@@ -1,32 +1,32 @@
# 當前狀態
> 更新時間:2026-06-26
> 更新時間:2026-07-17
> 每次 session 結束必須更新此檔。
---
## 正在做
T0.5T5 ingest 純餵食器管線**實作完成**issue #2,已 close)。程式碼在兩個待 merge 的 PR
- **PR #3**(核心管線):`src/**`index/source-adapter/harvest/extract/graph-client/weave/pipeline/endpoint-check/envelope/types+ `tests/**`28 passed+ contract + CLI + config。mergeable/CLEAN,待總管 merge
- **PR #4**template 1.9.x 遷移,本分支):`system-dev/**` + `.claude/**` + SDD 搬 `docs/3-specs/``system-dev/docs/3-specs/`。本 repo 自行 merge。
**SDD 生命週期鐵律遷移完成(2026-07-17canonicalsystem-dev-template v1.15.0**
- 鋪檔:`SDD-LIFECYCLE.md``pending-changes.md`3-specs/)、新版 `sdd-guard.sh`hooks/)、`sdd-check.md`commands/)、`sdd-active-check.sh`system-dev/scripts/
- `ingest-pipeline/design.md` 掛 frontmatter **`status: paused`**(實作 18/19 完成、剩部署+端到端驗證懸置、無進行中開發)→ 目前 **0 active,合法**。恢復開發=人升回 active。
- CLAUDE.md 新增 SDD 鐵律段(濃縮五條+現況註記)。
- **PR #4template 1.9.x 遷移分支)已併入 main 收尾**6500d7f,舊 status 懸了三週的 merge),HANDOFF-cloud-worker 隨遷移搬進 `system-dev/docs/`
gate 全綠:vitest 28 / tsc clean / wrangler dry-run 只 env-var 綁定 / 零直連 base·SQL·migration。
## ⚠️ 已知斷層:PR #3 的 src 管線不在 gitea main
PR #3T0.5T5 src/** 管線+testscommit 34869bc)只 merge 進**已死的 GitHub main**github-dead remote),gitea main 上沒有 `src/`。gitea main 後來另長出 `scripts/ingest-cli.mjs`07-03 walking skeleton、07-05 路徑 B 萃取),與 PR #3`scripts/ingest-cli.mjs` 是**兩套不同實作**。34869bc 本機 remote-tracking 還在,救援(cherry-pick + 解 CLI 衝突)需另案,恢復 active 時一併裁決。
## 下次 session 第一件事
1. **merge 順序**:先請總管 merge PR #3(核心),再 rebase + merge PR #4(遷移)——#4 對 tasks.md 做位置搬移,#3 在原位更新它,先後 merge 免衝突
2. merge 後進**部署待驗**:部署 ingest Workerwrangler,繞 Actions+ 設 `GRAPH_BASE_URL` → 跑端到端 `GitHub→ingest→graph`(需 leo21c
## 待負責人確認
- PR #3 merge(總管)|PR #4 merge(本 repo / leo)。
1. 照 SDD-LIFECYCLE.md 第 5 條回報三數字(現行規格=無 activeingest-pipeline paused
2. 若要恢復部署收尾(Worker 部署+端到端 ingest→graph):人先把 ingest-pipeline 升回 active,並裁決 PR #3 src 管線救援
## 已知問題
| 問題 | 優先級 | 狀態 |
|------|--------|------|
| 端到端 ingest→graph 未實證 | 🟡 | 待部署 + `GRAPH_BASE_URL`graph receiver 已補對齊 full contract |
| refresh 端 extractWorkers AI)未接 | | 第一版只走採取(路徑 A);深萃留 CLI/CC |
| PR #3 src 管線只在 github-dead/maingitea main 缺 src/ | 🟡 | 待救援裁決(34869bc 本機可查 |
| 端到端 ingest→graph 未實證 | 🟡 | 待部署 + `GRAPH_BASE_URL`SDD paused 中 |
| embed 實際 embedding | ⚪ | 只打標;等 base vectorizeArcrun #7 |
| T3.3 模型測試集(中文+暗示樣本) | ⚪ | deferred;護欄 + parse 已單元測試 |
| T3.3 模型測試集(中文+暗示樣本) | ⚪ | deferred |