@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

package/ds-canonical/skills/design-system-audit/references/rule-placement.md

@@ -1,22 +1,22 @@
-# 規則分層(8 個 home)— 完整參考
+# 規則分層（Level 1–9）— 唯一 taxonomy owner
 
-**CLAUDE.md 已留**:8 個 home 名稱清單 + decision flowchart + signal-to-noise 原則(high-level)。**本檔 own**:每個 home 的 scope 完整展開 + 現行 skill 生態 + 歷史放置案例 + 未採納的 Claude Code 能力評估。
+**Canonical owner**:本檔唯一擁有 Level 1–9 home taxonomy、scope 與 decision flowchart；`packages/design-system/ds-canonical/` 擁有固定規則、references、skills、hooks、commands，`governance/memory/` 與 `governance/planning/` 分別擁有短狀態與完整計畫。`AGENTS.md` 只是 shared bootstrap navigator，`CLAUDE.md` 與其他 provider views 只是 delivery/discovery projection；兩者都不是 taxonomy 或 semantic owner。
 
-寫規則 / audit 規則分層時,走 CLAUDE.md 的 flowchart 先決定 home,然後查本檔對應 home 的完整 scope 描述。
+寫規則 / audit 規則分層時,走本檔 flowchart 先決定 home；固定治理內容落 `packages/design-system/ds-canonical/`，provider adapter 再單向產生 discovery/delivery view。
 
 ---
 
-## 8 個 home 的完整 scope
+## Level 1–9 homes 的完整 scope
 
 ### 設計規則層(DS 設計知識,按影響範圍分層)
 
-### Level 1 — `CLAUDE.md`(專案層跨元件設計規則 SSOT)
+### Level 1 — `packages/design-system/ds-canonical/rules/` + `references/`(專案層跨元件設計規則 SSOT)
 
 - 跨元件架構判斷框架(Props 命名、Family 分類、token 消費紀律)
 - AI 反覆踩的**技術陷阱**(Tailwind v4 `var()`、tailwind-merge、Provider 放置、shadcn alias 回流)
 - 系統級 meta 規則(命名三重 test、cva 適用範圍、Story 三層定位)
-- **短指標**指向 spec 深度細節(一行連結不展開)
-- **判斷法**:AI 每次執行都需要的提醒 → CLAUDE.md;查閱特定 spec 就找得到 → spec
+- **短指標**指向 spec 深度細節(一行連結不展開)；shared bootstrap 只放 canonical pointer
+- **判斷法**:跨 provider 固定治理規則 → canonical `rules/`；長表與深層解說 → canonical `references/`；查閱特定 spec 就找得到 → spec
 - **不適合**:超過 5 行的對照表 / 場景列舉 / 公式推導
 
 ### Level 2 — 元件 `spec.md`(單元件設計規則)
@@ -25,8 +25,8 @@
 - variant / size / state 的「何時用 / 不用」與理由
 - 元件特有的設計決策 + do/don't 原則
 - 對 cross-cutting 規則的**例外**(documented 理由)
-- 指向 CLAUDE.md / pattern spec 的反向引用
-- **不適合**:適用多個元件的規則(應升級到 pattern spec 或 CLAUDE.md)
+- 指向 canonical rule / pattern spec 的反向引用
+- **不適合**:適用多個元件的規則(應升級到 pattern spec 或 `packages/design-system/ds-canonical/rules/`)
 
 ### Level 3 — Pattern `spec.md`(跨元件佈局 / 互動公式)
 
@@ -44,60 +44,63 @@
 
 ### 執行與狀態層(DS 設計之外的知識)
 
-### Level 5 — Skill (`.claude/skills/*/SKILL.md` + `references/`)
+### Level 5 — Skill (`packages/design-system/ds-canonical/skills/*/SKILL.md` + `references/`)
 
-- **Audit / 稽核協議**(如 `design-system-audit` 的 22 個 audits / `product-ui-audit` 的 6 維度檢核)
+- **Audit / 稽核協議**(如 `design-system-audit` 的 full-dim per design-system-audit SSOT / `product-ui-audit` 的 7 維度檢核)
 - **AI↔user 對話 protocol**(checkpoint 範本:「先不管」vs tech debt / 新 rule 提議 / 分類模糊等)
 - **特定工作流 playbook**(only-when-invoked 的多步驟流程)
 - **文件撰寫指南**(story-writing 等)
 - **pre-merge quality gate**(component-quality-gate 等)
-- **判斷法**:這條規則是否「只在某個 invoke 情境才需要」? 是 → Skill;否(每次都要)→ CLAUDE.md
-- **不適合**:設計規則(放 CLAUDE.md / spec)、session 狀態(放 memory)、runtime primitive(放 patterns/)
+- **判斷法**:這條規則是否「只在某個 invoke 情境才需要」? 是 → canonical Skill;否(每次都要)→ canonical rule/spec
+- **不適合**:設計規則(放 canonical rule / spec)、session 狀態(放 memory)、runtime primitive(放 patterns/)
 
-### Level 6 — Memory (`~/.claude/projects/.../memory/*.md`)
+### Level 6 — Memory (`governance/memory/*.md`)
 
 - **跨 session 狀態**(audit progress、tech debt 清單、決策紀錄)
 - user 偏好 / 角色 / 專案 goal
-- **每次 session 開啟時載入**
-- **判斷法**:這是「會變化的狀態」還是「固定的規則」? state → memory;rule → CLAUDE.md/spec/skill
+- `governance/memory/MEMORY.md` 是 index authority；各 provider 可載入由 `npm run sync-memory` 產生的可刪除 discovery cache
+- **每次 session 開啟時載入** index 與工作所需條目，不把 provider cache 當 SSOT
+- **判斷法**:這是「會變化的狀態」還是「固定的規則」? state → memory;rule → canonical rule/spec/skill
 - **不適合**:固定規則、跑得出的資訊(git log / 現行 code 有就不用記)、user 明確「先不管」的事項
 
-### Level 7 — Hook (`.claude/hooks/*.sh` / `*.py`)
+### Level 7 — Hook (`packages/design-system/ds-canonical/hooks/*.sh` / `*.py`)
 
 - **Pre/post-tool 自動化**(邊界守衛、sync check 提醒、token hygiene、import guard、charter gate)
-- **判斷法**:這條規則能「機械化在 tool 執行前後自動跑」嗎? 是 → hook;否 → CLAUDE.md 或 spec
-- **當前 hooks**(7 個):
-  - `pre_edit_spec_check.sh` — 編輯 tsx 前讀 spec
-  - `check_sync_update.sh` — 改 spec 後連動提醒
-  - `check_token_hygiene.sh` — 硬寫 shadow / shadcn alias / raw overflow 抓違規
-  - `block_prototype_imports.py` — 產品 code 禁 import explorations
-  - `enforce_home_charter.sh` — Write 到 classification-sensitive dir 時注入 charter(本 audit 設計時新增)
+- **判斷法**:這條規則能「機械化在 tool 執行前後自動跑」嗎? 是 → canonical hook + `registrations.json`;否 → canonical rule 或 spec
+- **當前 inventory**:以 `packages/design-system/ds-canonical/hooks/registrations.json`、canonical hook tree 與 `scripts/sync-governance-counters.mjs --check` 動態結果為準；本文件不硬寫數量或複製 hook 清單。
 
-### Level 8 — Slash Command (`.claude/commands/*.md`)
+### Level 8 — Command workflow (`packages/design-system/ds-canonical/commands/*.md`)
 
 - **輕量 user-invokable shortcut**(單步 action,無 workflow / checkpoints)
 - 跟 Skill 的差別:Skill 是多步驟 workflow + user 決策點;Command 是一次性 scaffold / 單步觸發
 - **判斷法**:這是「一次性 scaffold 或單步 action」嗎? 是且**重複使用 ≥ 3 次** → Command;否 → 需要 workflow → Skill
-- **當前狀態**:無 commands(評估後認為 scaffold 流程太僵化,改回用 CLAUDE.md 清單 + AI 判斷)
+- **當前狀態**:以 canonical commands inventory 為準；provider command view 只能由 adapter 產生，不能成為 semantic owner
+
+### Level 9 — Planning (`governance/planning/`)
+
+- 完整 execution plan、RFC、proposal、跨 session handoff ledger 與 point-in-time audit evidence
+- `governance/planning/registry.json` 是 inventory／status／executable contract；只有 `active + executable` 可驅動續作
+- Memory 只保留短 pointer 與 current-state 摘要；completed／reference／superseded／rejected 文件保留 provenance，不得重新當待辦
+- **判斷法**:資訊若超出 memory 的短索引、需要完整步驟／驗收／rollback／歷史證據 → Planning；可由 code／live readback 即時取得的狀態不得複寫成另一份 current truth
 
 ---
 
-## 當前 skill 生態(5 skills)
+## 當前 skill 生態(代表性；完整 inventory 見 `packages/design-system/ds-canonical/skills/README.md`)
 
 | Skill | Invoke 時機 | Scope |
 |-------|------------|-------|
-| `design-system-audit` | 稽核 DS 本身(spec/cva/SSOT 漂移 18 audits) | design-system/ 內部 |
-| `product-ui-audit` | 「audit X feature」「DS 用對了嗎」/ prototype Phase 3.5 自動 | consumer UI code 6 維檢核 |
+| `design-system-audit` | 稽核 DS 本身(spec/cva/SSOT 漂移 full-dim per SSOT) | design-system/ 內部 |
+| `product-ui-audit` | 「audit X feature」「DS 用對了嗎」/ prototype Phase 3.5 自動 | consumer UI code 7 維檢核 |
 | `prototype` | user 明言「做 prototype / MVP / 原型」 | 建 exploration candidates(Phase 3.5 強制 audit gate) |
 | `delivery-handoff` | 產品 final 後「要交付 / handoff」 | 產 figma-like 交付包 |
-| `component-quality-gate` | 元件即將合入 DS | 45 項 spec+code+story+ship checklist |
+| `component-quality-gate` | 元件即將合入 DS | 35 項 spec+code+story+ship checklist |
 | `story-writing` | 寫 / 審 story | 範例選擇 + anatomy 5-story + 三方連動 |
 
 **不走 skill 的情境**:user 日常對話「比幾個版本 / 世界級怎麼做」等模糊語,AI 先 clarify 再決定走 skill 還是直接口頭討論。
 
 ---
 
-## 放哪裡 decision flowchart(CLAUDE.md 已留,這裡重述供查閱)
+## 放哪裡 decision flowchart(本檔 canonical)
 
 ```
 Q1. 是設計規則嗎?(如何寫 spec / code / token / story / pattern)
@@ -105,21 +108,22 @@ Q1. 是設計規則嗎?(如何寫 spec / code / token / story / pattern)
     → NO: 繼續 Q2
 
 Q2. 只在「特定 invoke 情境」才需要嗎?(audit / code review / setup 等)
-    → YES 且是**多步驟 workflow + user 決策點**: Skill(SKILL.md + references/)
+    → YES 且是**可重複 workflow**: Skill(SKILL.md + references/；只有產品/UI/UX SSOT 真取捨設 user checkpoint)
     → YES 且是**一次性單步 action**(scaffold / 單一 check): Slash Command
     → NO: 繼續 Q3
 
-Q3. 是「隨時間變化的狀態」嗎?(已完成 / 待辦 / 決策紀錄 / user 偏好)
-    → YES: Memory
+Q3. 是「隨時間變化的狀態」或完整計畫嗎?(已完成 / 待辦 / 決策紀錄 / user 偏好 / RFC / handoff)
+    → 短 current-state / user preference: Memory(index + pointer)
+    → 完整 plan / RFC / handoff / evidence ledger: Planning(registry 決定是否 executable)
     → NO: 繼續 Q4
 
 Q4. 能用 script「機械化自動執行」嗎?(pre/post tool)
     → YES: Hook
     → NO: 繼續 Q5
 
-Q5. 是 CLAUDE.md / SKILL.md 已有項目的「深層細節」嗎?
+Q5. 是 canonical rule / SKILL.md 已有項目的「深層細節」嗎?
     → YES: Skill `references/*.md` 或 spec.md(視上層所在)
-    → NO: **不合任何 home——重新思考 scope 或 ask user**
+    → NO: **不合任何 home——依 Engineering Decision Policy 重新思考 scope/home；只有產品/UI/UX SSOT 真取捨才 ask user，純工程/治理分類不得轉問 user**
 ```
 
 **硬輔助:README charter gate**(本 audit 新增)
@@ -137,39 +141,39 @@ Q5. 是 CLAUDE.md / SKILL.md 已有項目的「深層細節」嗎?
 
 | 規則 | 原本想放 | 最終放 | 理由 |
 |------|---------|--------|------|
-| 命名三重 test | CLAUDE.md ✓ | CLAUDE.md | 每次新 variant/prop 都觸發,Level 1 |
-| cva 適用範圍 | CLAUDE.md ✓ | CLAUDE.md | 寫元件 code 的 pattern 決策,Level 1 |
-| 4-Family Model 頂層 taxonomy | CLAUDE.md + item-layout SSOT(舊) | `patterns/element-anatomy/element-anatomy.spec.md`(taxonomy overview)+ `patterns/element-anatomy/item-anatomy.spec.md`(F1/F2 deep)flat 並列 | 2026-04-20 refactor:folder `element-anatomy` = topic home,flat 多檔 topical pattern(overview + 具體 topic),對齊 Material / Polaris Foundations 組織法;不用 nested / 不用頂層飛地 |
-| 「先不管」語意區分 | CLAUDE.md(❌ 錯放) | **`design-system-audit` Checkpoint 7** | AI↔user 對話 protocol,不是設計規則;只在 audit triage 情境需要 |
-| 22 個 audits | CLAUDE.md(❌ 若放這會污染) | **`design-system-audit` skill** | 只在 `/design-system-audit` invoke 時需要 |
-| Tech debt 清單 | CLAUDE.md(❌ 會過期變誤導) | **Memory** | 隨時間變化的 session 狀態 |
-| Spec 寫作要交叉比對 | CLAUDE.md 或 spec 或 Hook | **Hook `check_sync_update.sh`** | 能機械化在 Edit 後自動提醒 |
+| 命名三重 test | provider bootstrap(舊) | `packages/design-system/ds-canonical/references/naming-conventions.md` | 每次新 variant/prop 都觸發,Level 1 |
+| cva 適用範圍 | provider bootstrap(舊) | `packages/design-system/ds-canonical/references/cva-patterns.md` | 寫元件 code 的 pattern 決策,Level 1 |
+| 4-Family Model 頂層 taxonomy | provider bootstrap + item-layout SSOT(舊) | `patterns/element-anatomy/element-anatomy.spec.md`(taxonomy overview)+ `patterns/element-anatomy/item-anatomy.spec.md`(F1/F2 deep)flat 並列 | 2026-04-20 refactor:folder `element-anatomy` = topic home,flat 多檔 topical pattern(overview + 具體 topic),對齊 Material / Polaris Foundations 組織法;不用 nested / 不用頂層飛地 |
+| 「先不管」語意區分 | provider bootstrap(❌ 錯放) | **`design-system-audit` Checkpoint 7** | AI↔user 對話 protocol,不是設計規則;只在 audit triage 情境需要 |
+| full-dim per design-system-audit SSOT | provider bootstrap(❌ 若放這會污染) | **`design-system-audit` skill** | 只在 `/design-system-audit` invoke 時需要 |
+| Tech debt 清單 | provider bootstrap(❌ 會過期變誤導) | **Memory** | 隨時間變化的 session 狀態 |
+| Spec 寫作要交叉比對 | bootstrap 或 spec 或 Hook(舊) | **M3 mindset #3**(`pre_edit_spec_check.sh` retired,現居 `packages/design-system/ds-canonical/hooks/retired/`;`check_sync_update.sh` retired/未實作)| Edit 前讀 spec + mindset 連動 |
 | `ItemLayout` export(ghost) | 本來以為是 industry idiom | **移除,改用 `<MenuItem>` + slot components** | 實查 Material 用 `<ListItem>` / Polaris `<ResourceItem>` / Ant `<List.Item>`——都無 Layout 後綴。ItemLayout 違反「element-level 不用 layout 字」鐵律 + 不是 idiom。只是 doc 裡 ghost reference,真實 exports 是 `ItemIcon / ItemAvatar / ItemLabel / ItemSuffix / ItemInlineAction`(slot pattern)+ `MenuItem`(canonical F1) |
 | Element anatomy 放哪 / item anatomy 結構 | 3 次 iteration:nested(X)→ 頂層飛地(F)→ 合併 merge(Y)→ flat topical(Z,final) | **`patterns/element-anatomy/` flat 多檔** | Z 比 X 少一層、比 Y 保 scope 純淨(taxonomy 和 deep SSOT 分檔);對齊 Material / Polaris 的 flat topical foundations 組織法 |
-| Story 寫作完整指南 | CLAUDE.md(過度膨脹) / patterns/(類別錯) | **`story-writing` skill** | 文件撰寫 workflow,invoke-only 多步驟;不是 runtime primitive 所以不屬 patterns |
-| 元件完成 checklist | CLAUDE.md(過度膨脹) / components/ 根目錄(破壞慣例) | **`component-quality-gate` skill** | pre-merge gate,invoke-only 多步驟;components/ 只收 PascalCase folder |
-| 規則分層 scope 完整展開 | CLAUDE.md(佔 140 行) | **本檔(`design-system-audit/references/rule-placement.md`)** | governance reference,只在 audit 規則放置時查 |
+| Story 寫作完整指南 | provider bootstrap(過度膨脹) / patterns/(類別錯) | **`story-writing` skill** | 文件撰寫 workflow,invoke-only 多步驟;不是 runtime primitive 所以不屬 patterns |
+| 元件完成 checklist | provider bootstrap(過度膨脹) / components/ 根目錄(破壞慣例) | **`component-quality-gate` skill** | pre-merge gate,invoke-only 多步驟;components/ 只收 PascalCase folder |
+| 規則分層 scope 完整展開 | provider bootstrap(舊,佔 140 行) | **本檔(`design-system-audit/references/rule-placement.md`)** | governance reference,只在 audit 規則放置時查 |
 
 ---
 
-## 已知但未採納的 Claude Code 能力(future-ready)
+## 已知但未採納的 Claude Code adapter 能力(future-ready)
 
-僅供參考,**目前專案未使用**——寫新規則前先用上述 8 個 home,用盡才考慮這些。
+僅供 provider adapter 參考,**目前專案未使用，亦不構成 authority/edit target**——寫新規則仍先用上述 Level 1–9 canonical taxonomy。
 
 | 能力 | 路徑 | 何時該採納 |
 |------|------|-----------|
-| Custom sub-agent | `.claude/agents/*.md` | 需要 persona 化的 specialized agent,且會重複使用(目前用 generic + 客製 prompt 就夠) |
+| Custom sub-agent | Claude generated delivery view(非 authority、禁止手改) | 需要 persona 化的 specialized agent,且會重複使用(目前用 generic + 客製 prompt 就夠) |
 | MCP server | 外部 server | 需要對接外部工具 / 資料(e.g., Figma token sync)——屬整合層,非規則放置 |
 | Output style | `.claude/output-styles/*.md` | 特定場合需要自訂輸出格式(對 DS 工作無關) |
 | Custom statusline | settings.json `statusLine` | 需要持續在狀態列顯示 session health(如 audit progress / 未解 tech debt 數) |
 | ScheduleWakeup / CronCreate | 內建 tool | 需要 scheduled recurring task(目前無此需求) |
 
-採納新能力前先走:能力真的解決問題嗎? → 目前 8 個 home 是否已涵蓋?(若是 → 不加) → 採納成本 vs 收益?
+採納新能力前先走:能力真的解決問題嗎? → 目前 Level 1–9 taxonomy 是否已涵蓋?(若是 → 不加) → 採納成本 vs 收益?
 
 ---
 
-## CLAUDE.md vs Skill 的 signal-to-noise 原則
+## Shared bootstrap vs canonical Skill 的 signal-to-noise 原則
 
-- **CLAUDE.md 每次對話都載入**——每加一條規則都增加 AI 掃描成本。**只放每次都需要 signal 的 DS 規則**。
+- **Shared bootstrap 每次對話都載入**——只放最小 canonical pointer 與每次都需要的 signal；固定內容仍由 `packages/design-system/ds-canonical/` 擁有。
 - **Skill 只在 invoke 時載入**——audit / workflow / interaction protocols 放這裡不污染每次對話。
-- **不對家**:把 audit protocol 放 CLAUDE.md → 每次對話都讀 audit-only 內容 = 噪音;把 DS 規則放 Skill → audit 以外的 session 讀不到 = 遺失 signal。
+- **不對家**:把 audit protocol 塞進 bootstrap → 每次對話都讀 audit-only 內容 = 噪音;把每次都需要的 DS rule 只放 Skill → audit 以外的 session 讀不到 = 遺失 signal。

package/ds-canonical/skills/ensure-canonical/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: ensure-canonical
-description: User 說「確保 X 一定要 / 不可繞過 / 永不漂移 / ensure X always」trigger phrase → 自動規劃完整 defense-in-depth pipeline(M14 5-layer + M8 benchmark + M17 SSOT + M10 下游),至少 3 層落地。對應 CLAUDE.md M19。Invoke via /ensure-canonical OR auto-recognize trigger keywords(確保 / 一定 / 不可繞過 / 不准 silent / 永不漂移 / ensure / always / never bypass / never silent)。本 skill 把 reactive「user 講 N 次才完整落地」改 proactive「trigger phrase auto plan 5-layer」。
+description: User 說「確保 X 一定要 / 不可繞過 / 永不漂移 / ensure X always」trigger phrase → 自動規劃完整 defense-in-depth pipeline(M14 5-layer + M8 benchmark + M17 SSOT + M10 下游),至少 3 層落地。對應 canonical meta-pattern M19。Invoke via /ensure-canonical OR auto-recognize trigger keywords(確保 / 一定 / 不可繞過 / 不准 silent / 永不漂移 / ensure / always / never bypass / never silent)。本 skill 把 reactive「user 講 N 次才完整落地」改 proactive「trigger phrase auto plan 5-layer」。
 ---
 
 # Ensure Canonical — User Trigger Phrase → Auto Defense-in-Depth
 
 **目的**: User 提出「某事 X 一定要照規矩發生」類 request → 自動套 5-layer defense-in-depth(canonical / hook / skill / audit / verify),不靠 AI 自律,不靠多次糾正,不留 silent bypass。
 
-**對應**: CLAUDE.md `# Meta-Pattern 預警` M19。世界級對照 Spotify Backstage / Polaris / Material / Carbon 4 家「rule + lint + test + doc」共識。
+**對應**:`packages/design-system/ds-canonical/rules/meta-patterns.md` M19。世界級對照 Spotify Backstage / Polaris / Material / Carbon 4 家「rule + lint + test + doc」共識。
 
 ## When to run
 
@@ -27,9 +27,9 @@ description: User 說「確保 X 一定要 / 不可繞過 / 永不漂移 / ensur
 
 ## Preconditions
 
-- 讀 CLAUDE.md M14 / M19(本 skill SSOT 上游)
-- 讀 `# 資訊治理 canonical`(8 home)
-- 該 rule 的 substantive meaning 還沒 finalize → 必走 Phase 5 user sign-off
+- 讀 `packages/design-system/ds-canonical/rules/meta-patterns.md` M14 / M19(本 skill SSOT 上游)
+- 讀 `packages/design-system/ds-canonical/skills/design-system-audit/references/rule-placement.md`(home placement)
+- 該 rule 若仍有會改變產品／UI／UX SSOT 的真取捨 → Phase 5 列 human-only decision；純工程／治理 substantive 依 Standing Authorization 自主 finalize
 
 ## Workflow(8 phases)
 
@@ -39,7 +39,7 @@ description: User 說「確保 X 一定要 / 不可繞過 / 永不漂移 / ensur
 - **Subject**: 「什麼事」(e.g. story splitting principle)
 - **Constraint**: 「必 X」「禁 Y」(e.g. start+end icon 必合 WithIcon,不准拆兩 story)
 - **Scope**: 全 DS / 特定元件 / 特定情境
-- **Existing state**: 已有相關 canonical 嗎?(grep CLAUDE.md / spec.md)
+- **Existing state**: 已有相關 canonical 嗎?(grep `packages/design-system/ds-canonical/{rules,references,skills,hooks}` / spec.md)
 
 Output:1 句結構化 rule。
 
@@ -54,14 +54,14 @@ Output:1 句結構化 rule。
 ### Phase 2 — M17 SSOT 識別(必跑)
 
 問 4 題:
-- 此 rule 屬哪 home?(CLAUDE.md / spec.md / token / hook / skill / memory)
+- 此 rule 屬哪 canonical home?(`packages/design-system/ds-canonical/{rules,references,hooks,skills}` / spec.md / token / governance memory)
 - 該 rule 是 SSOT 本身還是 pointer?
 - 是否 token / primitive / utility class 三擇一可程式化(M17)?
 - 若仍 markdown-only canonical → flag 為「假 SSOT」風險
 
 ### Phase 3 — Rule-of-3 + M10 下游檢查(必跑)
 
-- grep 既有 canonical(CLAUDE.md / specs / skills)有無相同概念
+- grep 既有 canonical(`packages/design-system/ds-canonical/` / specs / governance memory)有無相同概念
 - 若 ≥ 3 處出現 → 選 SSOT owner,其他 pointer only(避免 drift)
 - 新 rule 落地後,既有哪些 spec / memory / bug case 變冗餘?明寫「可刪 X」或「無下游」
 
@@ -71,7 +71,7 @@ Output:1 句結構化 rule。
 
 | Layer | 用途 | 範例 |
 |------|------|------|
-| **1 CLAUDE.md / spec.md** | Canonical SSOT,文字規則 | 加段、加 row,定義 rule + rationale |
+| **1 ds-canonical rule / spec.md** | Canonical SSOT,文字規則 | 在 `packages/design-system/ds-canonical/rules/` 或 owning spec 加段、加 row,定義 rule + rationale |
 | **2 Hook** | Write-time mechanical block | exit 2 + 訊息 + allowlist |
 | **3 Hook test** | Regression 防護 | 8+ scenario test_*.sh |
 | **4 Skill workflow** | invoke 時 phase gate | /story-writing Phase 0 mapping |
@@ -80,38 +80,39 @@ Output:1 句結構化 rule。
 
 **選擇邏輯**:
 - 機械可判斷 + 高頻寫 → 必加 Hook
-- 多步驟 + 需 user 介入 → 必加 Skill
+- 多步驟或含平台 human-only action → 必加 Skill；human action 不轉移工程決策權
 - 既有元件需驗 → 必加 Audit dim
-- 規則本身 → 必加 CLAUDE.md / spec.md
+- 規則本身 → 必加 canonical rule / owning spec.md
 - 無 user-reported pain 的層 → 跳過(M6 反 vanity)
 
-### ⚠️ Phase 5 — Checkpoint:Plan sign-off(必跑)
+### Phase 5 — Authority classification + plan receipt(必跑但非 blanket stop)
 
-呈給 user:
+產出並回報:
 ```
 Rule: <Phase 0 結構化>
 Benchmark: <Phase 1 3 家對照>
 SSOT: <Phase 2 home + 是否 SSOT 本身>
 下游影響: <Phase 3 retire 候選>
 落地 plan(5+1 層,至少 3 落地):
-  1. CLAUDE.md: ✓ <加哪段>
+  1. Canonical rule/spec: ✓ <加哪個 ds-canonical/spec owner>
   2. Hook: ✓ <檔名 + 抓什麼 pattern>
   3. Hook test: ✓ <case 數>
   4. Skill: ✓ / ✗ <為什麼>
   5. Audit dim: ✓ / ✗
   6. Verify: ✓ <tsc / build / visual>
-Substantive 動議: <若有 → STOP wait sign-off>
+Authority: <ENGINEERING-AUTO | PRODUCT-UIUX-DECISION | HUMAN-PLATFORM-ACTION>
+Substantive 動議: <工程 → evidence/review/rollback；產品 UI/UX 真取捨 → batch-at-end decision>
 ```
 
-User 拍板才 Phase 6 起執行。
+`ENGINEERING-AUTO` 直接進 Phase 6，不等 milestone 確認。只有 `PRODUCT-UIUX-DECISION` 或 shared governance 定義的平台／credential／額外付費／法律帳號商業 human-only boundary 才停；平台 action 前仍先完成唯一工程方案與可做 preflight。
 
 ### Phase 6 — Execute(每層 commit / verify)
 
 每層分批 commit(M11 user-perspective walk + governance check):
-1. CLAUDE.md edit + 7-Q hook self-check 過
-2. Hook write + 8 scenario test + register `.claude/settings.json`
-3. Skill workflow 加 phase
-4. Audit dim 加到 `/design-system-audit` SKILL.md
+1. Canonical rule/spec edit + 7-Q hook self-check 過
+2. Hook write + 8 scenario test + register `packages/design-system/ds-canonical/hooks/registrations.json`
+3. Canonical skill workflow 加 phase
+4. Audit dim 加到 `packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md`
 5. Batch fix 既有違規(grep + perl/sed rename + Visual diff)
 6. Commit `feat(scope): <rule> + N-layer enforcement(M19)`
 7. Push + GitHub Pages deploy verify
@@ -120,7 +121,7 @@ User 拍板才 Phase 6 起執行。
 
 - `npx tsc -b 2>&1 | tail -3` → 0 error
 - `npm run build-storybook 2>&1 | tail -3` → ✓ built
-- `bash .claude/hooks/tests/run-all.sh` → all suites pass
+- `bash packages/design-system/ds-canonical/hooks/tests/run-all.sh` → all suites pass
 - `git status --short` → clean
 - `git log origin/main..HEAD` → empty(全 push)
 
@@ -138,33 +139,34 @@ User 拍板才 Phase 6 起執行。
 回填:
 - 新 trigger phrase → 加進 SKILL.md「When to run」
 - enforce template 抽象化 → 加進 references/patterns.md(若 ≥ 3 次同 pattern)
-- user 糾正 → memory feedback / CLAUDE.md M-row
+- user 糾正 → `governance/memory/feedback_*.md` / `packages/design-system/ds-canonical/rules/meta-patterns.md` M-row
 
-## Checkpoints
+## Authority gates
 
-### ⚠️ Checkpoint 1 — Phase 5 plan sign-off(永遠 mandatory)
+### Gate 1 — Phase 5 plan receipt
 
-未 user 拍板**不可** start Phase 6。即使 user 已說「全做」「馬不停蹄」,仍要呈 plan(可短),抓「我以為 user 要 X 但其實要 Y」風險。
+Plan 與 scope classifier 必記錄，但純工程不得停等 user 拍板。只有 plan 暴露出新的產品／UI／UX SSOT 真取捨才請 user 決策。
 
-### ⚠️ Checkpoint 2 — Substantive 動議遇 STOP
+### Gate 2 — Substantive 動議
 
-- 動 canonical 既有 substantive meaning(改 rule、刪 rule、改 SSOT 位置)→ STOP
+- 工程／治理 canonical 既有 substantive meaning(改 rule、刪 rule、改 SSOT 位置)→ AUTO，綁 evidence；task／deliverable 明確要求時才加 maximum-assurance independent review
+- 改變產品／UI／UX SSOT 且仍有真取捨 → STOP
 - 對齊 / 表達層調整 / 補 pointer → AUTO
 
-### ⚠️ Checkpoint 3 — Layer 數不足
+### Gate 3 — Layer 數不足
 
 至少 3 層落地。若計算只有 2 層(e.g. 只 spec + hook,無 skill / audit / verify)→ 重 Phase 4 plan 補。
 
-### ⚠️ Checkpoint 4 — User 沒明確 trigger phrase 但 implicit ensure 意圖
+### Gate 4 — User 沒明確 trigger phrase但有 implicit ensure 意圖
 
-例:user 說「為什麼之前都漏這個」「下次怎麼確保不再發生」 → trigger M19 但表達 implicit。**主動問 user**「要走 /ensure-canonical 規劃完整 5-layer 嗎?」不假裝沒看到。
+例:user 說「為什麼之前都漏這個」「下次怎麼確保不再發生」 → 自動 trigger M19 並走完整 pipeline，不另問是否啟動。
 
 ## Non-goals
 
 - 不負責 single-file refactor(走 /design-system-audit)
 - 不負責 ad-hoc bug fix(走 /scan-similar-bugs)
 - 不替代 propose-options 4-Q gate(M18 不同階段:propose vs ensure)
-- 不自動執行 substantive 動議(必 sign-off)
+- 不自行發明產品／UI／UX SSOT；純工程／治理 substantive 依 Standing Authorization 自動執行
 
 ## 與其他 skill 分工
 
@@ -173,15 +175,15 @@ User 拍板才 Phase 6 起執行。
 | **/ensure-canonical** | 「確保 X 一定要」trigger phrase | 規劃 N-layer enforcement |
 | `/propose-options` | 列 options 給 user 前 | 4-Q gate per option |
 | `/design-system-audit` | 已 codified rule batch verify | audit 既有元件 |
-| `/knowledge-prune` | governance bloat | 8-home retire |
+| `/knowledge-prune` | governance bloat | Level 1–9 taxonomy retire / consolidate |
 | `/scan-similar-bugs` | 修 bug 後 | M10 exhaustive scan |
 | `/story-writing` | 寫 / 編 stories | rule-mapping workflow |
 
 ## References
 
-- CLAUDE.md M14(對話結論 → integrate pipeline)
-- CLAUDE.md M19(本 skill SSOT 上游)
-- CLAUDE.md `# 資訊治理 canonical`(8 home)
+- `packages/design-system/ds-canonical/rules/meta-patterns.md` M14(對話結論 → integrate pipeline)
+- `packages/design-system/ds-canonical/rules/meta-patterns.md` M19(本 skill SSOT 上游)
+- `packages/design-system/ds-canonical/skills/design-system-audit/references/rule-placement.md`(home placement)
 - Story splitting principle(2026-04-26 本 skill template 案例,4-layer 落地)
 
 ## 世界級對照(template 細節)

package/ds-canonical/skills/governance-health/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: governance-health
-description: Monthly metric-driven governance health scan. Reads .claude/logs/{hook-fires,hook-fires-per-hook,skill-invokes,user-corrections}.jsonl → detects dead hooks(6mo 0 fire)/ hot files / Meta-Pattern candidates / stale memories / pending corrections. Auto-proposes retire + rule upgrades. Complement to /knowledge-prune(quarterly deep restructure).
+description: Monthly provider-neutral governance health scan. Reads opt-in Git-owned telemetry through the canonical runtime resolver, detects dead hooks/hot files/Meta-Pattern candidates/stale memories/pending corrections, and proposes retire or rule upgrades without mutating policy. Complement to /knowledge-prune.
 ---
 
 # Governance Health — 持續 metric 監控 + auto-propose
@@ -10,14 +10,14 @@ description: Monthly metric-driven governance health scan. Reads .claude/logs/{h
 ## When to run
 
 - 月度 check(預設 cadence)
-- CLAUDE.md 行數突增(> 100 行/month)→ trigger
-- `.claude/logs/hook-fires.jsonl` > 5MB → trigger
+- repository instruction 行數突增(> 100 行/month)→ trigger
+- Git-owned `hook-fires.jsonl` > 5MB → trigger
 - audit Phase F 報告 sprawl 時 auto-chain
 - user 說「governance 健康嗎」/「有沒有 rule 該 retire」/「哪條 rule 該升級」
 
 ## Non-goals
 
-- 不改 canonical substantive(只提議,STOP 等 user sign-off)
+- 本次 health scan 保持 read-only；confirmed engineering remediation 交給 canonical owner skill 自動執行，不因 canonical substantive 而等 user sign-off
 - 不做深度 prune(那是 `/knowledge-prune`)
 - 不 retire 有 active consumer 的規則(只列候選,不執行)
 
@@ -28,20 +28,26 @@ description: Monthly metric-driven governance health scan. Reads .claude/logs/{h
 ### Phase 0 — Log freshness check
 
 ```bash
-ls -la .claude/logs/*.jsonl
+for NAME in hook-fires.jsonl hook-fires-per-hook.jsonl skill-invokes.jsonl user-corrections.jsonl metric-snapshots.jsonl; do
+  SAFE_FILE="$(node scripts/lib/governance-runtime-evidence.mjs --repo-root . --telemetry --path "$NAME")" || exit 2
+  [ ! -e "$SAFE_FILE" ] || ls -la "$SAFE_FILE"
+done
+GOVERNANCE_TELEMETRY_DIR="$(dirname "$(node scripts/lib/governance-runtime-evidence.mjs --repo-root . --telemetry --path hook-fires.jsonl)")"
 ```
 
-若任一 log > 1MB → 確認已 rotate(`*.jsonl.YYYYMM` 檔存在)。無 log → Phase 0 回報「instrumentation 未積累資料,需 1-2 個月 baseline」,退出。
+resolver 只允許真實 Git directory 下的 `governance-runtime/`，並逐檔拒絕 escape/symlink/hardlink；禁止自行改讀 `.claude`、`.codex` 或 workspace runtime。若任一 log > 1MB → 提議由 canonical telemetry writer 實作受測 rotation，不能自行搬檔。無 log → Phase 0 回報「instrumentation 未 opt-in 或尚未積累 1-2 個月 baseline」,退出。
 
 ### Phase 1 — Metric harvest(parallel)
 
 | Metric | Source | 判斷 |
 |--------|--------|------|
-| **Hook fire count**(per hook,6 月窗)| `hook-fires.jsonl` parse path column | 0 fire = retire 候選;>50 fire = hot rule |
+| **Hook fire count**(per hook,6 月窗)| `hook-fires-per-hook.jsonl`(+ `.jsonl.YYYYMM` rotation 檔)或 `npm run audit:hook-quality`(產 hook-quality-report.json 含 fire_count_6mo/dead 分類);**`hook-fires.jsonl` 記的是 governance-file 編輯軌跡(hot files 分析用),無 hook 名欄** | 0 fire = retire 候選;>50 fire = hot rule |
 | **Skill invoke count**(per skill,3 月窗)| `skill-invokes.jsonl`(若存在)| 0 = dead;< 3 = under-used |
 | **User correction signals**(per session)| `user-corrections.jsonl` count + sample | 總累積 > 20 = 需 codify |
-| **File size trend**(weekly snapshot)| `metric-snapshots.jsonl`(若存在)| CLAUDE.md 增速 > 5 line/week = sprawl alert |
-| **Benchmark freshness**(external)| `.claude/benchmarks/last-fetch.txt` | > 30 天 = 過期 |
+| **File size trend**(weekly snapshot)| `$GOVERNANCE_TELEMETRY_DIR/metric-snapshots.jsonl`(若存在)| repository instruction 增速 > 5 line/week = sprawl alert |
+| **Benchmark freshness**(external)| `infra/governance/runtime/benchmarks/last-fetch.txt` | > 30 天 = 過期 |
+| **Infra-ref integrity**(2026-05-30 加,根因防線)| `node scripts/check-dangling-infra-ref.mjs` + `node scripts/check-skill-deadref.mjs`(fail-open report)| bucket-B > 0(死 hook ref)OR removed-section/line-number ref > 0 OR product spec cite generated provider instruction adapter = infra-self drift → 提議 repoint。錨例:2026-05-30 抓 40 處死 hook ref + env-smoke set-e bug；2026-08-02 抓 33 specs / 41 refs authority drift |
+| **判準化佔比 trend**(2026-07-07 加,治理進化方向 1 KPI)| `node scripts/audit-coverage-matrix.mjs`(PURE-JUDGMENT / HOOK / DETERMINISTIC 三級計數)| PURE-JUDGMENT 佔比應逐月持平或降;連 2 月上升 = deep-audit C.0b 判準化 harvest 沒在跑 → flag。SSOT → `governance/planning/2026-07-07-governance-evolution-roadmap.md` |
 
 ### Phase 2 — Analysis(fire-driven auto-propose)
 
@@ -51,13 +57,13 @@ ls -la .claude/logs/*.jsonl
 
 規則 fire > 50 次 / 6 月 = 該 rule 反覆觸發 = 問題普遍 = 值得上升 Meta-Pattern layer 收斂(對齊 mindset #6「大原則吸收瑣碎」)。
 
-Output: 「`check_item_list_gap.sh` 6 月 fired 78 次 → 提議擴充到 CLAUDE.md Meta-Pattern M18?」
+Output: 「`check_item_list_gap.sh` 6 月 fired 78 次 → 提議擴充到 `packages/design-system/ds-canonical/rules/meta-patterns.md` M18?」
 
 #### 2b. Dead rule → retire 候選
 
 Hook 0 fire / 6 月 OR skill 0 invoke / 3 月 = 無 consumer = retire 候選。
 
-Output: 「`check_sideoffset_canonical.sh` 6 月 0 fire → retire 候選(先 grep 全 repo 確認無 reference 才執行)」
+Output: 「`check_sideoffset_canonical.sh`(retired;已移入 hooks/retired/,此為 dead-rule 偵測示例)6 月 0 fire → retire 候選(先 grep 全 repo 確認無 reference 才執行)」
 
 #### 2c. Pending corrections → codify 候選
 
@@ -73,13 +79,13 @@ Output: 「過去 4 週 user 糾正 15 條,sample: ..., 提議:升級 M19「XX p
 ## Metrics
 | | 本月 | 前月 | Trend |
 |--|------|------|-------|
-| CLAUDE.md 行數 | N | M | ↑/↓/→ |
+| repository instruction 行數 | N | M | ↑/↓/→ |
 | Hook fire total | N | M | ↑/↓/→ |
 | Skill invoke total | N | M | ↑/↓/→ |
 | Pending corrections | N | — | — |
 | Benchmark freshness | X days | — | — |
 
-## Retire 候選(auto-propose,需 user sign-off)
+## Retire 候選(auto-propose → engineering remediation queue)
 - {hook/skill name} — 0 fire / N mo — rationale
 - ...
 
@@ -88,19 +94,19 @@ Output: 「過去 4 週 user 糾正 15 條,sample: ..., 提議:升級 M19「XX p
 - ...
 
 ## Codify 候選(pending corrections)
-- {topic} — {count} user corrections — propose: 擴充 CLAUDE.md {section}
+- {topic} — {count} user corrections — propose: 擴充 AGENTS.md / `packages/design-system/ds-canonical/rules/meta-patterns.md` {section}
 - ...
 
 ## 外部 benchmark
 - Last fetch: {date} ({days} days ago)
-- 若過期 → 提議 run `.claude/benchmarks/fetch.sh`
+- 若過期 → 提議 run `bash governance/benchmarks/fetch.sh`
 ```
 
-### Phase 4 — Checkpoint 1(MUST ASK)— user sign-off
+### Phase 4 — Authority routing(no blanket checkpoint)
 
-report 給 user 後 **STOP**:
-- P0 retire(confirmed dead + 無 reference):AUTO OK 可執行
-- P1 Meta-Pattern upgrade / codify:STOP,需 user sign-off(動 canonical)
+report 是 receipt，不是 approval milestone；完成後直接 routing:
+- P0 retire(confirmed dead + 無 reference):AUTO chain `/knowledge-prune`
+- P1 Meta-Pattern upgrade / codify:若純工程治理，AUTO chain canonical remediation；task／deliverable 明確要求時才加 maximum-assurance independent review。只有會改產品／UI／UX SSOT 的真取捨才 batch 到 human-only boundary
 - P2 外部 benchmark 過期:AUTO run fetcher
 
 ### Phase 5 — Self-improvement capture + snapshot
@@ -114,7 +120,7 @@ report 給 user 後 **STOP**:
 - 修完的矛盾 / user 糾正: {list}
 ```
 
-Snapshot 本次 metric 到 `.claude/logs/metric-snapshots.jsonl` append:
+本 skill 保持 read-only，不直接 append telemetry。若 trusted adapter 已明示 `GOVERNANCE_TELEMETRY_OPT_IN=1`，canonical `stop_passive_logging.sh` 會把同一 schema 寫入 `$GOVERNANCE_TELEMETRY_DIR/metric-snapshots.jsonl`：
 ```json
 {"ts":"2026-04-24","claude_md_lines":686,"hook_fires_total":N,"skill_invokes_total":M}
 ```
@@ -127,20 +133,20 @@ Snapshot 本次 metric 到 `.claude/logs/metric-snapshots.jsonl` append:
 
 | Skill | Cadence | Focus | Scope |
 |-------|---------|-------|-------|
-| `/governance-health` | 月度 / auto-triggered | **Metric-driven 自動提議**(retire / upgrade / codify) | 全 governance files(CLAUDE.md / skills / hooks / memory / logs)|
+| `/governance-health` | 月度 / auto-triggered | **Metric-driven 自動提議**(retire / upgrade / codify) | canonical governance files + Git-owned opt-in telemetry |
 | `/knowledge-prune` | 季度 / release cut | **深度結構重構**(duplicate / dead / contradiction / over-concrete abstraction) | 同上 |
 
 **Chain 關係**:`/knowledge-prune --deep` 可 auto-chain `/governance-health` 產 metric baseline,但 health 不自動 chain prune。
 
 ## Non-goals 重申
 
-- 不改 canonical substantive meaning
+- 本 skill 自身不 mutate canonical；工程 substantive finding 必 route 到 canonical owner 自主 remediation
 - 不刪 memory 檔(只提議)
 - 不動元件 / spec
 - 不處理 git log / commits
 
 ## References
 
-- `.claude/logs/` — metric source
-- `.claude/benchmarks/` — external signal
-- CLAUDE.md `# 資訊治理 canonical` — governance rules (本 skill 執行)
+- `<real-git-dir>/governance-runtime/` — metric source；只能透過 canonical resolver 解析
+- `governance/benchmarks/` — provider-neutral fetch policy；`infra/governance/runtime/benchmarks/` — disposable external signal cache
+- AGENTS.md `# 治理 canonical` — provider-neutral governance rules (本 skill 執行)

package/ds-canonical/skills/governance-status/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: governance-status
+description: Fast, provider-neutral governance health check for this repository. Use when asked for governance status, adapter drift, provider parity, or whether generated governance surfaces are current.
+---
+
+# Governance status
+
+Run the repository-owned deterministic checks below. This skill is intentionally provider-neutral and contains no user-home paths or provider-specific state.
+
+## Checks
+
+Run every check even when an earlier one fails:
+
+1. `npm run --silent governance:doctor`
+2. `node scripts/gen-codex-adapter.mjs --check`
+3. `node scripts/build-fork-governance.mjs --check`
+4. `node --test infra/governance/test/provider-surface.test.mjs`
+
+Do not regenerate, repair, install, publish, or modify anything unless the user separately asks for a fix.
+
+## Output
+
+Return one compact table with each command marked `PASS`, `FAIL`, or `BLOCKED`, followed by exactly one overall state:
+
+- `HEALTHY`: all checks pass.
+- `DRIFTED`: a generated projection or snapshot differs from its authority.
+- `INVALID`: a contract, provider surface, or inventory check fails.
+- `BLOCKED`: required tooling or files are unavailable.
+
+Include the first actionable diagnostic for every non-pass result. Never call the repository healthy based only on hook availability; deterministic checks and CI are authoritative.