Leo/Arcrun

Files

T

Leo 8d8b01d240 docs(sdd): credential-primitives-wasm 封存進 archive（T10 完成，卷已結案）

leo 2026-07-21 明令封存：卷已完成，留主目錄會讓未來 session 誤以為進行中。
最後一項 T10（廢除自管加密金鑰）已於 20c7610 完成（移除約 2500 行）。

- git mv 整卷 → system-dev/docs/3-specs/archive/credential-primitives-wasm/
  design.md status: closed；superseded_by 留空（據實：非被另一卷取代，是機制整個換掉）
- 卷首補「封存時仍未完成的項目」——逐條查 code 核實，不當作完成：
  真缺口＝auth_mtls 從未實作、7.6 self-hosted auth 鏈端到端從未驗；
  另有勾選過期（auth_oauth2 其實已完成）與驗收條件已作廢（與現行 rule 07 牴觸）者
- 修好 14 處引用（原盤點 10 處，實際更多）：session-start-load-sdd.sh 內容嚴重過期
  （把已完成 Phase 寫成進行中）→ 改為以 frontmatter 為判準；四份 rules、CLAUDE.md、
  BACKLOG、3-specs/README、deploy.ts、credentials.ts、wrangler.toml 逐一按性質處理
- 額外：system-dev/docs/2-architecture/ 有四個規則檔重複副本（06-08 遷移遺留）
  → 同步修好，否則留一份過期真相（今日第三次撞到「同一資訊兩份副本」的債）
- 02-forbidden.md §2.1 列的三個「待刪違規 TS」其實早已不存在
  → 改標刪除線＋禁止重新引入（過期文件同時製造假待辦與假進行中）

驗證：sdd-active-check exit 0（active 仍恰一份＝portal-auth）；
session-start-load-sdd.sh exit 0；cypher-executor 與 cli typecheck 全綠；
測試 187/188（唯一 fail 為 pre-existing，stash 覆驗相同）。

未動：pre-write-guard.sh 的 KNOWN_SDDS 白名單不含 archive 路徑
（放寬 guardrail 需明確授權，留待決定）。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-21 01:57:34 +08:00

4.5 KiB

Raw Permalink Blame History

SDD 協議（每次啟動必讀）

第零原則：沒讀 SDD 不准動 code

任何 .go / .ts / .tsx / .wasm 相關變動，必須按以下順序執行。不得簡化，不得跳過。

步驟 1：讀總進度

先讀 docs/3-specs/arcrun/arcrun.md，了解當前 Phase。

步驟 2：定位對應 SDD

根據任務性質找對應 SDD：

任務類型	對應 SDD
Auth primitive WASM 零件 / credential 儲存 / WASI shim host functions	已封存（`system-dev/docs/3-specs/archive/credential-primitives-wasm/`，`status: closed`）。現行規範見 `.claude/rules/01-tech-stack.md`「Credential 儲存規範」；新工作需另立 SDD（含未實作的 `auth_mtls`），不得掛在已封存的卷上
Auth Recipe 系統（recipe schema、KV 格式）	`docs/3-specs/arcrun/auth-recipe.md`
Landing Page	`docs/3-specs/arcrun/landing-page.md`
CLI / SDK（Python/JS）	`docs/3-specs/arcrun/sdk-and-website/`
arcrun-core-mvp 整體架構	`docs/3-specs/arcrun-core-mvp/`
Platform Evolution	`docs/3-specs/arcrun-platform-evolution/`
Credential 長期規格（需求源）	`docs/user_requirements/credential_parts.md`

讀 design.md 和 tasks.md 兩份。

步驟 3：宣告（強制格式）

開始動手前，在回覆開頭逐字貼出以下宣告：

📋 已讀 SDD：
- docs/3-specs/arcrun/arcrun.md（當前 Phase：<phase 名稱>）
- <對應 SDD 的 design.md 路徑>
- <對應 SDD 的 tasks.md 路徑>

🎯 本次對應 task：<task 編號，例如 "Phase 1.3 實作 auth_static_key main.go">

📐 本次 task 的 SDD 規範摘要：
- <重點 1>
- <重點 2>
- <重點 3>

🚧 執行範圍：
- 會修改：<檔案清單>
- 會建立：<檔案清單>
- 會刪除：<檔案清單>

不做這個宣告 = 違反 SDD 協議 = 停手等 richblack。

步驟 4：check tasks.md 狀態

動手前：在 tasks.md 把對應 task 的 - [ ] 改成 - [🔄]（進行中標記）。完成後：改成 - [x]，不批次更新，每完成一個就立刻改。

什麼算「任務超出 SDD 範圍」？

以下情況屬於 change，不是 modify，必須停手並與 richblack 確認：

SDD 沒寫到的新功能
新增頂層目錄
新增新的 Worker（不管是 cypher-executor / registry / 零件 worker）
修改架構決策（例如「改用 xxx 取代 yyy」）
跨多個子系統的連鎖修改

停手不是怯懦，是專業。猜錯方向比慢一小時更糟。

新增 SDD 的完整程序（richblack 確認後怎麼往下走）

2026-06-03 補：之前協議只寫「停手等確認」，沒寫「確認後怎麼做」，導致 CC 被 pre-write-guard.sh 規則 4.3 擋下後不知正路、卡死。這節補完整程序。

當「新增一個 SDD 子系統」（在 docs/3-specs/ 下開新頂層目錄）：

停手，向 richblack 說明要新建哪個 SDD、為什麼（change，見上節）。
取得 richblack 明確確認後，依序：
1. 更新白名單：在 .claude/hooks/pre-write-guard.sh 的 KNOWN_SDDS 陣列加一行 "docs/3-specs/<新目錄名>" # YYYY-MM-DD richblack 確認新建（<一句用途>）。（這步是「執行 richblack 已授權任務的必要步驟」，不是 AI 擅自放寬 guardrail—— 授權脈絡要明確，分類器才放行；沒有明確授權就改白名單 = 越界。）
2. 建目錄 + 寫 design.md / tasks.md（白名單放行後才寫得進去）。
若沒先更新白名單就 Write → 規則 4.3 會擋你（這是對的，表示你跳了步驟 2.i）。

為什麼白名單而非全放行：開新 SDD 子系統 = 宣告新架構範圍，是稀有的人類決策點。白名單讓「AI 自己無中生有開子系統」必停下（AI 改不了白名單，除非 richblack 明確授權該任務）。已許可的目錄內寫檔零摩擦。

發現 SDD 本身有問題怎麼辦？

SDD 和實作不一致 → 停手，列出矛盾點，與 richblack 確認哪一邊是對的
SDD 規範之間互相矛盾（例如禁令 A 和設計 B 衝突）→ 停手，引用矛盾原文，與 richblack 確認
不可以自行猜哪個是對的。CC 之前兩天就是這樣走錯的。

為什麼這個協議存在

arcrun 規範已經足夠細緻，CC 之前出錯不是因為不懂，而是因為沒讀或讀了覺得「大概是這個意思」就動手。SDD 協議強制把「先讀 → 定位 → 宣告 → 執行 → 更新」做成一條死規矩，沒有繞過去的路徑。

4.5 KiB Raw Permalink Blame History Unescape Escape