# Design 補充：recipe 入庫把關（push 那一刻）

> 2026-06-01。本檔是 `component-gatekeeping/design.md` 的單檔補充（規則 02 §4.3 允許）。
> **狀態：待 richblack review 才動 code（這是 change）。**
> 背景：richblack 2026-06-01 方向修正（見下「方向定調」）+ docs/HANDOFF-self-host-harness.md。

---

## 0. 方向定調（richblack 2026-06-01）

把關的對象與位置整個移位了，先講清楚才不會做歪：

### 0.1 零件這條路 = 封鎖，且「不再有假零件這件事」
- 零件由維護者（richblack）管理，**CC 不能自製/修改零件**。
- 封鎖機制 = **零件投稿走 GitHub PR + 人 merge**（DECISIONS §8 / design 頂部方向修正）。
  AI 偽造不了 GitHub approve，這是天然人類閘門。CC 在本機產不出能進庫的零件。
- → 因此「擋假零件」（原 W1）這件事**不存在了**：CC 根本造不出零件，workflow 引用 recipe
  （如 `component: kbdb_get`）是**合法且未來唯一的擴充方式**，不該被當假零件擋。

### 0.2 零件 PR 把關 = 人工，不自動化（除非未來爆量）
- richblack 2026-06-01 澄清 BACKLOG 步驟5「不做 hook/自動化」的真意：
  **零件真實數量很少、絕大多數是 recipe** → 原本想做的「驗證零件 PR 的自動化機制」
  （CI 跑 Gherkin/沙箱/向量）**不需要**，量少 → **有 PR 進來就人工檢查**。
  **只有零件開發量變很大時**才回頭想自動化。
- → component-gatekeeping 的 G4/覆蓋檢查/黃金向量自動化 = **不做**（人工取代），與既有 tasks 收尾一致。

### 0.3 真正的 harness 把關 = recipe 入庫（push）那一刻
CC 唯一能擴充的是 recipe。recipe 一律用「**推（push）**」，**自有庫與公共庫同一套指令**。
把關依庫別分強度：

| 庫別 | 能做到的把關 | 機制 |
|---|---|---|
| **自有庫（self-hosted）** | 只能**提醒**（無法在別人機器強制） | (1) 資料外流提醒 (2) 打通檢查 |
| **公共庫** | 維護者機制**檢核實際打通、真收到成功回傳** | PR/CI relay（DECISIONS §3c，第一期後）|

---

## 1. 自有庫 push 把關（self-hosted，第一期做）

`acr recipe push` 的兩個提醒。**提醒級 = 告知 + 需人類明示同意，不硬擋**（self-hosted 是用戶自己的庫，
他同意後就是他的責任 — mindset §6 / data-exfil-warning 既有原則）。

### 1.1 資料外流提醒（W2.2）
- **觸發**：push 的 recipe / 或部署的 workflow 會讓「資料對外可見」——主要是產生**對外可被呼叫的 webhook**
  （`POST /webhooks/named/...` 對外 trigger URL），或 recipe 把本地資料 POST 到外部服務。
- **行為**：CLI 印明確警示「這個動作會讓 X 對外界可見/可呼叫，確認要繼續嗎？」→ 需人類明示同意（y/N）。
  非 TTY（AI 直跑）→ 拒絕，提示「需人類確認」（mindset §7：絕不代替人類做暴露確認）。
- **與既有 data-exfil-warning 的關係**：已有 API 層 + pre-bash hook（commit 51d40ee 等）。
  本項確認**涵蓋 recipe push 這條路徑**；若已涵蓋則只補文件，若沒涵蓋則補上 push 路徑的提醒。
- **誠實限制**：AI 技術上能偽造 exposure_consent。價值是法律歸責 + 軌跡可審，不聲稱不可繞過（mindset §7）。

### 1.2 打通檢查（W2.3）
- **目的**：recipe 是「指向外部 API 的指針」，正確性一半在「打不打得通」（DECISIONS §1 recipe 驗收標準 = 2xx）。
- **行為**：push 時（或 push 後）對 recipe 的 endpoint **實打一次**，回報 HTTP status。
  - 2xx → 「✓ recipe 打通（HTTP 200）」
  - 4xx/5xx → 「⚠️ recipe 未打通（HTTP 401/404/...）」+ 誠實標原因（如「缺 credential → 先 acr creds push」）
  - 連不上 → 「⚠️ 無法連線」
- **self-hosted 是提醒級**：打不通**不硬擋 push**（用戶可能就是要先 push 再設 credential），只如實回報。
- **誠實**（mindset §7）：缺 credential 打不到 2xx 就誠實標「未驗收：缺 X」，不 mock 充綠燈。

### 1.3 動到的檔案（待 review 後）
| 檔案 | 動作 |
|---|---|
| `cli/src/commands/recipe.ts` | push 流程加 (1) 資料外流提醒 prompt (2) 打通檢查（實打 endpoint 回報 status） |
| `.claude/hooks/*`（如需）| 確認 data-exfil pre-bash hook 涵蓋 recipe push；缺則補 |

**不動**：cypher-executor 執行路徑、零件、credential 解密邏輯。

---

## 2. 公共庫 push 把關（第一期後）

- recipe 進公共庫 = 別人會用 → 需維護者機制檢核「**實際打通、真收到成功回傳**」（不是投稿者自報）。
- 機制：DECISIONS §3c 的 **test/relay**——push 公共庫走 relay，維護者當下親見真實打通記錄
  （執行者不能驗證自己，§7 閉環）。
- **範圍**：依賴公共庫 + relay 基建，**第一期不做**（第一期是 self-hosted + 提醒級）。
- 本檔只記框架，第一期不實作。

---

## 3. 同一套指令、不同把關強度的切分（W2.4）

- `acr recipe push`（自有庫，預設）→ §1 提醒級。
- `acr recipe push --public`（公共庫，未來）→ §2 relay 檢核級。
- 同一指令、旗標分流（呼應 design §4.3 公私庫分流：`-p`/`--public`）。
- 第一期只實作預設（自有庫）路徑。

---

## 4. 驗收標準（客觀證據，mindset §7）

第一期（自有庫提醒級）：
1. `acr recipe push` 一個會產對外 webhook 的東西 → CLI 印資料外流警示 + 要人類同意；非 TTY → 拒絕。
2. `acr recipe push` 一個 endpoint 可達的 recipe → 打通檢查回報「✓ HTTP 2xx」。
3. `acr recipe push` 一個缺 credential 的 recipe → 回報「⚠️ 未打通：缺 credential」（誠實，不假綠），但仍允許 push。
4. 確認 workflow 引用 recipe（`component: kbdb_get`）**不再被任何 validate 步驟當假零件擋**（W1 已作廢）。

---

## 5. 與既有 SDD 的一致性確認（無新矛盾）

- 不動「零件投稿走 PR + 人工檢查」（§0.1/0.2，與 design 頂部方向修正、DECISIONS §8 一致）。
- 不重啟「零件 PR 自動化把關」（§0.2，與 BACKLOG 步驟5 真意一致）。
- 資料外流提醒延續既有 data-exfil-warning 原則（mindset §6），只確認涵蓋 recipe push 路徑。
- 打通檢查 = recipe 驗收標準 2xx 的落地（DECISIONS §1）。