Leo/Arcrun
1
0
Fork 0
Code Issues 49 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
Files
8d8b01d2407f265e8288b66dc13ba9ce8f28f57c
Arcrun/CLAUDE.md
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

6.7 KiB
Raw Blame History

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（每次 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，再啟動封測。

Reference in New Issue View Git Blame Copy Permalink