diff --git a/.agents/specs/component-gatekeeping/design.md b/.agents/specs/component-gatekeeping/design.md index cceb3e6..ce50d20 100644 --- a/.agents/specs/component-gatekeeping/design.md +++ b/.agents/specs/component-gatekeeping/design.md @@ -1,6 +1,34 @@ # Design: Component Gatekeeping(零件投稿真把關) -> 2026-05-29。實作 requirements.md 的 R1-R6。**本 design 需 richblack 確認後才動 registry code。** +> 2026-05-29。實作 requirements.md 的 R1-R6。 + +--- + +## ⚠️ 方向修正(richblack 2026-05-30):投稿走 GitHub PR,廢 registry self-service + +**零件投稿管道 = GitHub PR,不是 registry submit API。** 理由與影響見下;以下 §0-§9 的 registry submit 設計, +凡屬「self-service 投稿管道」者**作廢**,凡屬「把關邏輯」者**搬到 CI(PR check)跑**。 + +**為何改:** primitive 極少、未來絕大部分是 recipe → 新增零件是稀有低頻事件,不需 self-service 自動化管道。 +PR 天然滿足每道閘門: + +| 設計的閘門 | PR 怎麼天然滿足 | +|---|---| +| G0 人類閘門 | PR 必須有人 merge(richblack approve);AI 偽造不了 GitHub approve | +| 舉證「為何不是工作流」 | PR description,review 時看 | +| G1 假零件 / G3 純WASI / G4 Gherkin / 覆蓋檢查 / 黃金向量 | **CI(PR check)跑** —— CI 有 tinygo + 能 runtime 跑 wasm,**繞開 CF Workers 不能 runtime 編譯 wasm 的 venue 牆** | + +**§8 衝突釐清:** DECISIONS §8「不依賴 GitHub Actions」指**執行鏈路**(init/push/run/recipe,常態高頻, +用戶機器+CF)。**零件投稿是稀有低頻、該由 PR 治理**,用 PR/CI 不違反 §8——反而更對(CI 能跑 wasm, +registry Worker 不能)。需在 DECISIONS 補這個區別(待 richblack 確認改穩定文件)。 + +**哪些作廢 / 哪些保留:** +- ❌ 作廢:registry submit API 當主投稿管道、四路(CLI/MCP/py/js)self-service 投稿、平台端 sandbox 重跑、`acr parts publish` 加人類閘門(投稿不走 CLI 了)。 +- ✅ 保留並搬 CI:G1 假零件偵測邏輯(detectFakeComponent.ts)、G3 純WASI(wasmImports.ts)、G4 Gherkin 真跑(CI 能跑 wasm)、B 覆蓋檢查、黃金向量人工核對。 +- ✅ 已 commit 的 registry G0/G1/G3 程式碼**保留不刪**(無害,且 G1/G3 邏輯被 CI 複用),但 registry submit 不再是主管道。 +- ✅ R5 本機 hook(擋 CC 直接造零件目錄)仍要 —— 它擋的是「繞過 PR 直接改 repo」,與 PR 管道互補。 + +**以下 §0-§9 為原 design,閱讀時套用上述修正。** --- @@ -139,12 +167,27 @@ interface SubmitRequest { - cold_start / runtime_compat 保留 mock,但 **SandboxResult 增 `unimplemented_steps: string[]`**,回傳時明列 `["cold_start","runtime_compat"]`,submit 回應與文件明示「這兩步未實作、未真正驗證」。不回 `success:true` 假裝全綠——回 success 但附 unimplemented 清單。 +## 5.5 黃金向量:人工核對 + B 覆蓋檢查(richblack 2026-05-30 定) + +Claude.ai 建議用「黃金向量 + 把關自己重跑」自動驗收,防放水的 Gherkin。**價值保留,實作降級**,理由: + +- **primitive 極少、未來絕大部分是 recipe**(人類閘門 + 工作流優先把零件擋在源頭)。現役 17 白名單 + cron/platform_crypto,未來極少新增。 +- 「把關自動重跑向量」是為「零件大量增加」做的規模化基建——但零件不會大量增加 → 為不存在的規模做自動化 = 過度工程(DECISIONS 附錄「會不會累積成債」判準)。 +- 且「把關自己重跑 wasm」撞 venue 牆(CF 不能 runtime 編譯 wasm,同 §4.0)→ 需平台端 sandbox(第一期沒有)。 + +**降級後做法:** +- **A 黃金向量 conformance → 人工核對**:黃金向量當「人類閘門時用 CC 核對 primitive 的對照表」。新增 primitive(極稀有)時,人類閘門已要你親自確認,那一刻用 CC 本地跑向量核對(本地有 tinygo + 能跑 wasm,繞開 venue 牆)、人工凍結。**不做機器自動重跑。** +- **B 覆蓋檢查 hook → 現在做(純靜態、不可造假、成本低、價值與零件數無關)**:靜態 parse contract:`input_schema` 每個 required 欄位至少出現在一個 Gherkin given、`output_schema` 每個欄位至少被一個 then_contains 斷言。缺 → exit 2 指出漏哪個欄位。擋「只測 happy path、不碰宣告過的行為面」。 +- **初始向量來源(信任根:寫向量≠寫實作)**:另起 session 從 contract 語義寫、不看實作原碼(primitive 語義客觀如 add(2,2)=4)。人工核對用,不急、新增 primitive 時逐個補,不必 21 個一次到位。 +- 殘留(誠實):向量/覆蓋檢查擋不住「列出的 case 全對、沒列到的 case 錯」。交給「用」——出 bug 補進向量,永不 regress。是會長大的網,非設一次完美。 + ## 6. R5 白名單 + 本機 hook - `registry/MVP_COMPONENTS.txt`:一行一個白名單 canonical_id(現役 22 個)。 - `pre-write-guard.sh` 增規則:寫入 `registry/components/{name}/...` 且 `{name}` 不在 MVP_COMPONENTS.txt → exit 2,訊息「新增零件需走 submit API 人類閘門,不可直接造 repo 目錄」。 - `pre-bash-guard.sh` 增規則:`mkdir .../registry/components/{白名單外}` → exit 2。 - `.ts` 偵測現有 hook 已做(rule 1.1)。 +- **B 覆蓋檢查**(5.5):可放 registry submit 的靜態驗收(不需跑 wasm,CF 可跑)或 pre-write hook,擋宣告過的欄位沒被 Gherkin 測到。 ## 7. 範圍邊界