Arcrun/CLAUDE.md

# CLAUDE.md — arcrun

> **上游約束（InkStoneCo 總管）**：本 repo 是 InkStoneCo 大專案的子專案，受頂層知識庫約束。
> 動工前讀 `github.com/uncle6me-web/InkStoneCo` 的 CLAUDE.md + `docs/3-specs/`。
> 關鍵鐵律：禁止跨 repo 同步 Actions / Mira≠Arcrun 分層（arcrun.dev 是框架域名，非產品入口）/ self-hosted 用 namespace 明碼非 api key / 部署繞開 GitHub（wrangler 直推）。
> 本 repo 的待整合交棒見 `docs/HANDOFF-matrix-rearrange.md`。

> **與 InkStoneCo 總管的溝通走本 repo 的 GitHub issue**：總管交辦框架 bug / 跨專案需求 →
> 在本 repo 開 issue；CC 用 `gh` 讀（`gh issue list/view`）、修完在同一 issue `comment` 回報修法 + 驗證證據。
> issue thread = 雙向溝通 + 永久記錄。**有事才讀，禁自動輪詢**（flag 安全界線）。
> 結案時機由「end-to-end 實證綠燈」決定——尚待人/總管確認的留 open。詳見 `/issue-handle` skill。
> 發 issue 給**別的 repo** 要先問人類，不可擅自。

> 本檔是**索引 + 最高原則**，詳細規範拆到 `.claude/rules/`。
> Hook 強制機制在 `.claude/hooks/`，違反會直接 block（exit 2）。

---

## 絕對鐵律（違反 = 停手）

1. **任何 code 變動前必須先讀對應 SDD**，在回覆開頭宣告已讀清單與對應 task 編號（格式見 `.claude/rules/00-sdd-protocol.md`）
2. **零件只能用 TinyGo 或 AssemblyScript 編譯成 WASM**；`registry/components/` 下禁止 TypeScript
3. **cypher-executor TS 禁止實作 credential / auth / JWT / template 展開業務邏輯**；這些全在 WASM 零件
4. **Cypher binding = YAML 裡的 URL 清單**，不是 Cloudflare service binding；零件串接走 HTTP URL（含 auth primitive）。self-hosted same-zone 1042 用 `global_fetch_strictly_public` flag 解，不新增 binding（來源：credential-primitives-wasm Phase 7，該卷已封存，規則仍有效）
5. **每個 WASM 零件 = 獨立 Worker = 公開 URL**；不從 R2 動態讀（R2 只 Phase 5 啟用）
6. **修改現有程式碼，不是新建資料夾重做**
7. **每完成一個 task 立刻更新 tasks.md 的 `[x]`**，不批次
8. **薄殼原則**：能力只實作一次放在 API；CLI/MCP/lib 是薄殼，不得自帶業務邏輯 / 拼裝 API / 用 recipe 補 API 缺口（見 `.claude/rules/07-thin-shell.md`，hook 7.x 部分強制）

---

## SDD 生命週期鐵律（2026-07-17 leo 拍板，全文見 `system-dev/docs/3-specs/SDD-LIFECYCLE.md`）

> 現行規格以 design.md frontmatter `status: active` 為準（機器可查），
> hook `.claude/hooks/sdd-guard.sh` ＋ `system-dev/scripts/sdd-active-check.sh` 強制。

1. **單一活性**：任何時刻整個 repo 最多一份 `status: active` 的 SDD；所有開發任務必須對應這份 SDD 的 tasks，找不到對應 → 停下來問。
2. **CC 禁止自行建立 SDD**：任何情況下不得主動建新 SDD（既有 hook 規則 4.3 同源）。
3. **規格層變更只有一條路**：寫 change proposal 進 `system-dev/docs/3-specs/pending-changes.md`（變更摘要＋影響分析）然後**停止**，等使用者明說「confirm」；沒 confirm 就照現行 SDD 繼續。任務層小改直接更新現行 tasks 並標日期原因。
4. **開新 SDD（confirm 後）**：先把舊 SDD 未完成且仍有效的任務**逐條搬入**新 SDD——搬完前不准寫任何程式碼；舊 SDD 改 `closed` 填 `superseded_by` 並移入 `3-specs/archive/`；向使用者列「已搬移／已作廢」清單請最終確認。
5. **每次 session 開始**：先讀現行 active SDD 與 pending-changes.md，回報三個數字——「現行規格〈名稱〉＋未完成任務 N＋待裁決 proposal M」——再開工。

---

## 工作流程（強制）

開始任一任務，按順序：

1. **讀 wiki**（3 分鐘快速進度）→ `.claude/wiki/status.md`
2. 讀 `docs/3-specs/arcrun/arcrun.md`（總進度）
3. 讀對應的 SDD `design.md` + `tasks.md`
4. 在回覆開頭貼出：
   ```
   📋 已讀 SDD：<清單>
   🎯 本次對應 task：<編號>
   📐 本次 task 的 SDD 規範摘要：<重點>
   🚧 執行範圍：修改/建立/刪除 <檔案>
   ```
5. 動手前把 tasks.md 對應 task 標為 `[🔄]`，完成後標 `[x]`
6. 完成後確認：是否需要同步更新 design.md？

找不到對應 SDD → **停手問 richblack**，不要自行建立。

---

## 🔴 第一鐵律：wiki 是判準，不准跳過（2026-07-20/21 leo 兩度點破）

**要查任何東西之前，先照索引走：`system-dev/wiki/INDEX.md` → 下層 `00-INDEX.md` → 卡片。**

🔴 **2026-08-15 leo 糾正：本條原本寫的是「用 grep」，那是錯的。**
grep 是平面搜尋，它繞過索引，於是**索引永遠不會被驗證、也永遠不會變準**——
而 AI 又用「索引可能不準」當理由繼續 grep。這是自我實現的。
實測那天：`matrix/arcrun` 的 wiki 有 64 張卡，**只有 1 張走得到索引**
（唯一那張是 leo 手寫的；63 張機器產的卡從沒加入任何索引），
而 AI 從沒發現——**因為 grep 找得到，破損就永遠不會浮現。**

**grep 不是禁令，是異常訊號**：
1. 先照索引走
2. 索引走不到 → **那是索引壞了，先講出來**（哪一層缺、缺什麼）
3. 講完才准 fallback 用 `grep -rin "<關鍵字>" system-dev/wiki/`

⇒ 每一次 grep 都該留下一筆「索引缺陷」，而不是變成習慣。
（全面禁止 grep 也是錯的——索引壞掉那天 AI 會瞎掉，而且沒人知道。）

> leo：「花很多力氣去產生 wiki，最重要的就是要可以查詢，**結果要查的時候就跳過，那就白寫了**。」
> 「重點是你自己的記憶對嗎？而你有按照規定去切實讀 wiki 嗎？」

**三條硬規則**：
1. **wiki 與程式碼/歷史文件衝突 → 以 wiki 為準**。程式碼反映「還沒清乾淨」，不等於「還在用」。
2. wiki 寫「不可動／待廢除／進行中」→ **讀它的解除條件並逐條核對**。那是當時狀態，不是永久禁令。
3. 翻原文後得到新結論 → **回頭更新 wiki**（wiki 過時是債，要還）。

**動外部系統（部署／curl／wrangler／acr／gh）前**：先找 repo 有沒有**現成腳本或 README 部署段**，
別自創方法。（實例：2026-07-21 明明有 `npx wrangler deploy` 這條驗過的路，卻自己 curl 硬幹踩坑。）

> hook `wiki-first-search.sh` 會在你查 code／下高風險指令時自動推 wiki 命中行；
> **但機制只是提醒，判斷是你的責任**。


## Wiki（每次 session 的讀取順序）

| 檔案 | 時機 | 用途 |
|------|------|------|
| `.claude/wiki/status.md` | session 開始第一件事 | 當前 Phase、進度、下一步 |
| `.claude/wiki/mistakes.md` | 做新功能前 | 10 大常犯錯誤 + 快速檢查清單 |
| `.claude/wiki/decisions-summary.md` | 遇到設計判斷時 | 6 大架構決策 + trade-off |
| `.claude/wiki/INDEX.md` | 找不到東西時 | wiki 導引 + 快速導航 |

---

## 詳細規範索引

| 檔案 | 內容 |
|-----|------|
| `.claude/rules/00-sdd-protocol.md` | SDD 讀取協議（強制流程） |
| `.claude/rules/01-tech-stack.md` | 技術棧硬限制（語言/儲存/加解密） |
| `.claude/rules/02-forbidden.md` | 禁止清單（hook 強制執行） |
| `.claude/rules/03-component-architecture.md` | 零件架構（R2 用途 / cypher binding / service binding 邊界） |
| `.claude/rules/04-current-progress.md` | 當前進度 + SDD 索引 |
| `.claude/rules/05-deploy-convention.md` | 部署慣例（新 Worker = 新目錄 + wrangler.toml） |
| `.claude/rules/06-mindset.md` | mindset（為什麼層） |
| `.claude/rules/07-thin-shell.md` | 薄殼原則鐵律（能力長在 API，介面只暴露） |

---

## SDD 位置速查

> **現行（active）SDD 唯一判準＝frontmatter `status: active`**（2026-07-17 起），查法：`bash system-dev/scripts/sdd-active-check.sh`。下表僅路徑索引，「進行中」標記以 frontmatter 為準。

| 子系統 | 路徑 |
|-------|------|
| **現行 active** RAG Portal 多人授權 | `system-dev/docs/3-specs/portal-auth/` |
| ~~Credential Primitives WASM~~（**closed，已封存**） | `system-dev/docs/3-specs/archive/credential-primitives-wasm/` — credential 現行做法見 `.claude/rules/01-tech-stack.md`；殘留缺口（`auth_mtls` 未實作等）要做需另立新 SDD |
| arcrun 總進度 | `docs/3-specs/arcrun/arcrun.md` |
| Auth Recipe 系統 | `docs/3-specs/arcrun/auth-recipe.md` |
| Landing Page | `docs/3-specs/arcrun/landing-page.md` |
| SDK + Website | `docs/3-specs/arcrun/sdk-and-website/` |
| arcrun MVP 整體 | `docs/3-specs/arcrun-core-mvp/` |
| Platform Evolution | `docs/3-specs/arcrun-platform-evolution/` |
| Credential 長期規格（需求源） | `docs/user_requirements/credential_parts.md` |
| Tech Stack 詳細 | `docs/3-specs/tech.md` |

---

## 封測狀態

**推遲**（richblack 2026-04-19 決定）。先完成 Phase 1-3 清除違規 TS，再啟動封測。