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:
@@ -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 ＋ 日期。）
|
||||
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
|
||||
+14
-14
@@ -1,32 +1,32 @@
|
||||
# 當前狀態
|
||||
|
||||
> 更新時間：2026-06-26
|
||||
> 更新時間：2026-07-17
|
||||
> 每次 session 結束必須更新此檔。
|
||||
|
||||
---
|
||||
|
||||
## 正在做
|
||||
|
||||
T0.5–T5 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-17，canonical＝system-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 #4（template 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 #3（T0.5–T5 src/** 管線＋tests，commit 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 Worker（wrangler，繞 Actions）+ 設 `GRAPH_BASE_URL` → 跑端到端 `GitHub→ingest→graph`（需 leo21c）。
|
||||
|
||||
## 待負責人確認
|
||||
|
||||
- PR #3 merge（總管）｜PR #4 merge（本 repo / leo）。
|
||||
1. 照 SDD-LIFECYCLE.md 第 5 條回報三數字（現行規格＝無 active／ingest-pipeline paused）。
|
||||
2. 若要恢復部署收尾（Worker 部署＋端到端 ingest→graph）：人先把 ingest-pipeline 升回 active，並裁決 PR #3 src 管線救援。
|
||||
|
||||
## 已知問題
|
||||
|
||||
| 問題 | 優先級 | 狀態 |
|
||||
|------|--------|------|
|
||||
| 端到端 ingest→graph 未實證 | 🟡 | 待部署 + `GRAPH_BASE_URL`（graph receiver 已補對齊 full contract） |
|
||||
| refresh 端 extract（Workers AI）未接 | ⚪ | 第一版只走採取（路徑 A）；深萃留 CLI/CC |
|
||||
| PR #3 src 管線只在 github-dead/main，gitea main 缺 src/ | 🟡 | 待救援裁決（34869bc 本機可查） |
|
||||
| 端到端 ingest→graph 未實證 | 🟡 | 待部署 + `GRAPH_BASE_URL`；SDD paused 中 |
|
||||
| embed 實際 embedding | ⚪ | 只打標；等 base vectorize（Arcrun #7） |
|
||||
| T3.3 模型測試集（中文+暗示樣本） | ⚪ | deferred；護欄 + parse 已單元測試 |
|
||||
| T3.3 模型測試集（中文+暗示樣本） | ⚪ | deferred |
|
||||
|
||||
Reference in New Issue
Block a user