# thin-shell-alignment — Requirements

> **來源**：InkStoneCo 總管 GitHub issue #11（[全面對齊] CLI/MCP 薄殼漂移系統性盤點 + 防複發機制，leo 發起）。
> **狀態**：草案，待總管/richblack 確認方向後實作。
> **建立**：2026-06-27
> **白名單**：`.claude/hooks/pre-write-guard.sh` KNOWN_SDDS 已加（2026-06-27 issue #11 授權）。

---

## 1. 問題：CLI/MCP 系統性漂移，根因＝假綠

不是單點 bug，是**系統性漂移**。總管盤查 + 本 SDD 核實確認。

**根因（issue #11 git 史盤查）＝假綠**：MCP deploy 工具建於 2026-06-06 commit「薄殼原則落地 + 部署一致性」——在宣稱「一致性落地」的**同一次 commit** 裡，MCP deploy 卻打了一個不存在的端點 `/workflows/deploy`（必 404、從未端到端跑過）。違 mindset §7「完成＝客觀證據非口頭宣布」。**這就是要防複發機制的理由**——光靠「宣稱對齊」會再犯。

---

## 2. 盤點結果（總管盤 + 本 SDD 核實，file:line）

### 🔴 P0 死端點（打的 route 不存在 → 404）

| 能力 | 介面 | 打的端點 | 真端點 | file:line | 歸屬 |
|------|------|---------|--------|-----------|------|
| 部署 | MCP | `/workflows/deploy` | `/webhooks/named`（吃 graph） | `mcp/u6u_deploy_workflow.ts:22` | **#8 ①-a + #10 ①-b**（本 SDD 不重複改）|
| 執行已部署 | CLI | `/webhooks/<name>` | `/webhooks/named/:name/trigger` | `cli/run.ts:102` | **本 SDD P0** |

✅ 核實 CLI run 死端點：`run.ts:102` 打 `${executorUrl}/webhooks/${workflowName}`（缺 `/named/` 與 `/trigger`）；真端點 `webhooks-named.ts:279` 是 `/webhooks/named/:name/trigger`。確認 404。

### 🟡 P1 架構分歧（同能力不同來源）

| 能力 | CLI | MCP | 問題 |
|------|-----|-----|------|
| list workflow | 直連 CF KV 讀 `workflow:` 前綴（`cli/list.ts:35`，`CfKvClient`）| 讀 KBDB `/records?template=workflow_metadata`（`mcp/u6u_list_workflows.ts:26`）| 讀不同源 → 列出的東西不一樣，違 rule 07 §4 |

> **本 SDD 核實補充（比總管盤點更深，2 個額外問題）**：
> 1. **key 前綴對不上**：CLI list 讀 `workflow:{name}`，但部署（`webhooks-named.ts` kvKey）寫的是 **`{apiKey}:wf:{name}`** → CLI list **永遠列不到新部署的 workflow**（前綴根本不匹配，不只是「來源不同」）。
> 2. **CLI list 直連底層儲存**：`CfKvClient` 直打 Cloudflare KV REST API（繞過 cypher）→ 違薄殼更深一層（薄殼不該直碰儲存），且 self-hosted 用戶得有 CF API token 才能 list。

### 🟢 P2 單邊能力（一邊有一邊無）

- CLI only：`acr validate`（/cypher/search）、`acr creds push`（/credentials）。
- MCP only：`u6u_search_workflows`（/workflows/search，#8 新增）。
- 已對齊✅：recipe 6 能力、execute 本機 YAML（兩邊都打 /cypher/execute）。

---

## 3. 需求（issue #11 任務 → 可驗收條目）

### R1：P0 死端點修掉
- **R1.1** CLI run 改打 `/webhooks/named/:name/trigger`（真端點），不再 404。
- **R1.2** MCP deploy 死端點**不在本 SDD 修**（歸 #8 ①-a / #10 ①-b，避免三方重複改 deploy）；本 SDD 僅記其存在 + 防複發機制要能攔它。

### R2：P1 list 來源統一
- **R2.1** CLI 與 MCP list 都讀**同一個 API 端點** `GET /webhooks/named`（KV 源，`webhooks-named.ts`），CLI 停止直連 CF KV。
- **R2.2** list 讀 KV 源（部署寫入處），**KBDB search-entry 只供 search 不供 list**（職責分：list=KV 精確列舉、search=entry 語意檢索）。對齊 #8 雙寫設計。
- **R2.3** CLI list 改走 cypher proxy（薄殼不直碰儲存），self-hosted 用戶不需 CF API token 即可 list。

### R3：P2 單邊能力盤點決策
- **R3.1** 逐項決定：該補齊對稱的（薄殼出貨標 §5「CLI+MCP 覆蓋同組能力」）vs 刻意單邊的（記明原因，如 `creds push` 屬 CLI 慣例）。
- **R3.2** 不強求每個端點兩邊各開（齊的單位是「能力」非「端點」，decisions-summary 2026-06-15 釐清）。

### R4 ⭐：防複發機制（本 issue 治本核心，不可省）
- **R4.1** 設計一個讓「假綠」無法再悄悄發生的機制。候選（design 評估擇一/組合）：
  - **能力對照清單**：一張表「能力 × CLI 端點 × MCP 端點 × 同源?」，新增能力必填、review 對照。
  - **end-to-end smoke test**：每個薄殼能力對真實端點跑一次（非 tsc 綠），死端點當場現形。
  - **PR 證據要求**：新薄殼工具必附「打的端點在 server route 清單裡存在」的證據。
- **R4.2** 守 flag 紅線：smoke test 本機/手動跑，**非 CI 高頻輪詢**。
- **R4.3** 機制本身要可驗：能攔住一個**故意的死端點**（驗收標準，issue #11 明列）。

---

## 4. 約束（頂層鐵律）

- **C1 框架級**：改全 arcrun 用戶 → 先 SDD 確認方向。
- **C2 守 rule 07**：能力只實作一次；薄殼讀同一份來源、不直碰儲存。
- **C3 守 mindset §7**：完成＝leo21c 端到端客觀證據（CLI/MCP 真打通 200 非 404），非 tsc 綠。
- **C4 三方協調**：#11（全面盤點+防複發）/ #8（deploy 強制+search）/ #10（編排下沉）有交集，**deploy 那條不重複改**（本 SDD 只盤點 + 防複發涵蓋它）。
- **C5 署名**：跨 repo comment 開頭 `[arcrun CC]`。

---

## 5. 非目標

- ❌ 改 deploy 死端點（歸 #8/#10）。
- ❌ 把防複發機制做成 CI 高頻 gate（C2 flag 紅線、rule 05 §3）。
- ❌ 強求 CLI/MCP 端點 1:1（齊的單位是能力非端點）。

---

## 6. 開放問題（design 回答 / 待拍板）

- **Q1**：R4 防複發機制採哪個/哪幾個組合？（design 給推薦 + 為何）
- **Q2**：CLI list 改走 cypher proxy，需不需要新 proxy 端點，還是複用 `GET /webhooks/named`？（後者已存在，傾向複用）
- **Q3**：P2 單邊能力，哪些補對稱、哪些刻意單邊？（design 逐項給判準）
- **Q4**：smoke test 放哪（CLI 自帶 `acr selftest`？獨立 script？）、怎麼「本機手動跑非輪詢」？