@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

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

@@ -0,0 +1,196 @@
+---
+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」。
+---
+
+# 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」共識。
+
+## When to run
+
+**自動 trigger keywords**(英中):
+- 「確保 X / 確保所有 / 一定要 / 一律 / 永不漂移 / 不可繞過 / 不准 silent」
+- 「ensure X always / X must / X required / never bypass / no silent X」
+- 「規矩」+「發生 / 觸發 / enforce」
+- 「自動 X / X must auto」
+
+**手動 invoke**:`/ensure-canonical` 後接規則描述。
+
+## When NOT to run
+
+- 純資訊請求(「告訴我 X 是什麼」)
+- 一次性 ad-hoc 操作(「修這 1 個 bug」)
+- 已 codified rule 的 enforcement(走 audit 不走本 skill)
+
+## Preconditions
+
+- 讀 CLAUDE.md M14 / M19(本 skill SSOT 上游)
+- 讀 `# 資訊治理 canonical`(8 home)
+- 該 rule 的 substantive meaning 還沒 finalize → 必走 Phase 5 user sign-off
+
+## Workflow(8 phases)
+
+### Phase 0 — Parse user rule(必跑)
+
+從 user prompt 抽出:
+- **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)
+
+Output:1 句結構化 rule。
+
+### Phase 1 — M8 World-class benchmark(必跑)
+
+≥ 3 家 world-class DS / engineering org 對照:
+- Polaris / Material / Atlassian / Ant / Carbon / Apple HIG / VS Code / Figma / Storybook 官方 / Spotify Backstage
+- 每家寫具體實作名 + URL or source(closed source 標 closed)
+
+通過條件:**3 家 verified + AI 不假裝對齊不存在的 source**(對齊 M8 「無對照 = 未成熟」)。
+
+### Phase 2 — M17 SSOT 識別(必跑)
+
+問 4 題:
+- 此 rule 屬哪 home?(CLAUDE.md / spec.md / token / hook / skill / 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)有無相同概念
+- 若 ≥ 3 處出現 → 選 SSOT owner,其他 pointer only(避免 drift)
+- 新 rule 落地後,既有哪些 spec / memory / bug case 變冗餘?明寫「可刪 X」或「無下游」
+
+### Phase 4 — 5-Layer enforcement plan(必跑)
+
+對應 M14 pipeline,plan 對齊以下 5+1 層,**至少 3 層真落地**:
+
+| Layer | 用途 | 範例 |
+|------|------|------|
+| **1 CLAUDE.md / spec.md** | Canonical SSOT,文字規則 | 加段、加 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 |
+| **5 Audit dim** | Periodic mechanical batch verify | /design-system-audit Group X |
+| **6 Memory / verify** | Cross-session state + 每次 verify | tsc / build / visual / hook test |
+
+**選擇邏輯**:
+- 機械可判斷 + 高頻寫 → 必加 Hook
+- 多步驟 + 需 user 介入 → 必加 Skill
+- 既有元件需驗 → 必加 Audit dim
+- 規則本身 → 必加 CLAUDE.md / spec.md
+- 無 user-reported pain 的層 → 跳過(M6 反 vanity)
+
+### ⚠️ Phase 5 — Checkpoint:Plan sign-off(必跑)
+
+呈給 user:
+```
+Rule: <Phase 0 結構化>
+Benchmark: <Phase 1 3 家對照>
+SSOT: <Phase 2 home + 是否 SSOT 本身>
+下游影響: <Phase 3 retire 候選>
+落地 plan(5+1 層,至少 3 落地):
+  1. CLAUDE.md: ✓ <加哪段>
+  2. Hook: ✓ <檔名 + 抓什麼 pattern>
+  3. Hook test: ✓ <case 數>
+  4. Skill: ✓ / ✗ <為什麼>
+  5. Audit dim: ✓ / ✗
+  6. Verify: ✓ <tsc / build / visual>
+Substantive 動議: <若有 → STOP wait sign-off>
+```
+
+User 拍板才 Phase 6 起執行。
+
+### 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
+5. Batch fix 既有違規(grep + perl/sed rename + Visual diff)
+6. Commit `feat(scope): <rule> + N-layer enforcement(M19)`
+7. Push + GitHub Pages deploy verify
+
+### Phase 7 — Verify
+
+- `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
+- `git status --short` → clean
+- `git log origin/main..HEAD` → empty(全 push)
+
+任一 fail → 回 Phase 6 修。
+
+### Phase F — Self-improvement capture(必跑)
+
+```markdown
+## Self-improvement capture
+- 新發現 trigger pattern: ... OR 「無」
+- 新確立 enforce template: ... OR 「無」
+- 修完的 trigger 漂移 / user 糾正: ... OR 「無糾正」
+```
+
+回填:
+- 新 trigger phrase → 加進 SKILL.md「When to run」
+- enforce template 抽象化 → 加進 references/patterns.md(若 ≥ 3 次同 pattern)
+- user 糾正 → memory feedback / CLAUDE.md M-row
+
+## Checkpoints
+
+### ⚠️ Checkpoint 1 — Phase 5 plan sign-off(永遠 mandatory)
+
+未 user 拍板**不可** start Phase 6。即使 user 已說「全做」「馬不停蹄」,仍要呈 plan(可短),抓「我以為 user 要 X 但其實要 Y」風險。
+
+### ⚠️ Checkpoint 2 — Substantive 動議遇 STOP
+
+- 動 canonical 既有 substantive meaning(改 rule、刪 rule、改 SSOT 位置)→ STOP
+- 對齊 / 表達層調整 / 補 pointer → AUTO
+
+### ⚠️ Checkpoint 3 — Layer 數不足
+
+至少 3 層落地。若計算只有 2 層(e.g. 只 spec + hook,無 skill / audit / verify)→ 重 Phase 4 plan 補。
+
+### ⚠️ Checkpoint 4 — User 沒明確 trigger phrase 但 implicit ensure 意圖
+
+例:user 說「為什麼之前都漏這個」「下次怎麼確保不再發生」 → trigger M19 但表達 implicit。**主動問 user**「要走 /ensure-canonical 規劃完整 5-layer 嗎?」不假裝沒看到。
+
+## 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)
+
+## 與其他 skill 分工
+
+| Skill | Trigger | Scope |
+|-------|---------|-------|
+| **/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 |
+| `/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)
+- Story splitting principle(2026-04-26 本 skill template 案例,4-layer 落地)
+
+## 世界級對照(template 細節)
+
+| Org | 4-layer pattern |
+|-----|---------------|
+| **Spotify Backstage** | Catalog rules + tech docs + hooks + integration tests |
+| **Polaris** | Spec.md + storybook tests + lint rules + contribution gate |
+| **Material 3** | Rule docs + linter + test suite + design token |
+| **Carbon** | Storybook + a11y test + style lint + contribution check |
+
+我們的 5-layer 對齊 + 加 audit dim(periodic verify drift)。

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

@@ -0,0 +1,146 @@
+---
+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).
+---
+
+# Governance Health — 持續 metric 監控 + auto-propose
+
+**目的**:從 aspirational「會有大腦」升級到 **operational 自我優化**。/knowledge-prune 是季度深度重構;本 skill 是**月度 metric scan + 自動提議 rule 升級 / retire 候選**。
+
+## When to run
+
+- 月度 check(預設 cadence)
+- CLAUDE.md 行數突增(> 100 行/month)→ trigger
+- `.claude/logs/hook-fires.jsonl` > 5MB → trigger
+- audit Phase F 報告 sprawl 時 auto-chain
+- user 說「governance 健康嗎」/「有沒有 rule 該 retire」/「哪條 rule 該升級」
+
+## Non-goals
+
+- 不改 canonical substantive(只提議,STOP 等 user sign-off)
+- 不做深度 prune(那是 `/knowledge-prune`)
+- 不 retire 有 active consumer 的規則(只列候選,不執行)
+
+---
+
+## 5-Phase Workflow
+
+### Phase 0 — Log freshness check
+
+```bash
+ls -la .claude/logs/*.jsonl
+```
+
+若任一 log > 1MB → 確認已 rotate(`*.jsonl.YYYYMM` 檔存在)。無 log → Phase 0 回報「instrumentation 未積累資料,需 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 |
+| **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 天 = 過期 |
+
+### Phase 2 — Analysis(fire-driven auto-propose)
+
+三類 auto-propose:
+
+#### 2a. Hot rule → Meta-Pattern upgrade candidate
+
+規則 fire > 50 次 / 6 月 = 該 rule 反覆觸發 = 問題普遍 = 值得上升 Meta-Pattern layer 收斂(對齊 mindset #6「大原則吸收瑣碎」)。
+
+Output: 「`check_item_list_gap.sh` 6 月 fired 78 次 → 提議擴充到 CLAUDE.md Meta-Pattern 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 才執行)」
+
+#### 2c. Pending corrections → codify 候選
+
+`user-corrections.jsonl` > 10 條未 codify = user 反覆糾正類似錯誤,該升級到 canonical。
+
+Output: 「過去 4 週 user 糾正 15 條,sample: ..., 提議:升級 M19「XX pattern」或擴充 `# Meta-Pattern 預警`」
+
+### Phase 3 — Health report(produce report to user)
+
+```markdown
+# Governance Health Report — {YYYY-MM-DD}
+
+## Metrics
+| | 本月 | 前月 | Trend |
+|--|------|------|-------|
+| CLAUDE.md 行數 | 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)
+- {hook/skill name} — 0 fire / N mo — rationale
+- ...
+
+## Meta-Pattern upgrade 候選(auto-propose)
+- {rule name} — {fire count}/6mo — propose: 升級 M{N} 「...」
+- ...
+
+## Codify 候選(pending corrections)
+- {topic} — {count} user corrections — propose: 擴充 CLAUDE.md {section}
+- ...
+
+## 外部 benchmark
+- Last fetch: {date} ({days} days ago)
+- 若過期 → 提議 run `.claude/benchmarks/fetch.sh`
+```
+
+### Phase 4 — Checkpoint 1(MUST ASK)— user sign-off
+
+report 給 user 後 **STOP**:
+- P0 retire(confirmed dead + 無 reference):AUTO OK 可執行
+- P1 Meta-Pattern upgrade / codify:STOP,需 user sign-off(動 canonical)
+- P2 外部 benchmark 過期:AUTO run fetcher
+
+### Phase 5 — Self-improvement capture + snapshot
+
+報告尾加:
+
+```markdown
+## Self-improvement capture
+- 新發現 governance pattern: {...} OR "無"
+- 新確立 monitoring rule: {...} OR "無"
+- 修完的矛盾 / user 糾正: {list}
+```
+
+Snapshot 本次 metric 到 `.claude/logs/metric-snapshots.jsonl` append:
+```json
+{"ts":"2026-04-24","claude_md_lines":686,"hook_fires_total":N,"skill_invokes_total":M}
+```
+
+下次 Phase 1 對比 trend。
+
+---
+
+## 與 `/knowledge-prune` 分工
+
+| Skill | Cadence | Focus | Scope |
+|-------|---------|-------|-------|
+| `/governance-health` | 月度 / auto-triggered | **Metric-driven 自動提議**(retire / upgrade / codify) | 全 governance files(CLAUDE.md / skills / hooks / memory / logs)|
+| `/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
+- 不刪 memory 檔(只提議)
+- 不動元件 / spec
+- 不處理 git log / commits
+
+## References
+
+- `.claude/logs/` — metric source
+- `.claude/benchmarks/` — external signal
+- CLAUDE.md `# 資訊治理 canonical` — governance rules (本 skill 執行)

package/ds-canonical/skills/knowledge-prune/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: knowledge-prune
+description: Prune governance sprawl across CLAUDE.md / specs / skills / hooks / memory / settings. Finds duplicate rules (Rule-of-3), dead hooks (6mo 0 fire via `.claude/logs/hook-fires-per-hook.jsonl`), stale memories, over-concrete bug case studies that should abstract to meta, and contradictions across homes. Enforces per-file budget (CLAUDE.md target ≤ 200 / transition ≤ 400, spec ≤ 300, SKILL ≤ 250, memory ≤ 100) and retire rate ≥ 5% / quarter. Invoke via /knowledge-prune quarterly or when CLAUDE.md > 800 / MEMORY.md > 20 entries / audit Phase F reports sprawl. Auto-chained by /design-system-audit --deep Phase 4.5.
+---
+
+# Knowledge Prune — 治理反膨脹 skill
+
+**目的**:本 DS governance 自身是活的知識庫,若只 append 會讓 CLAUDE.md 載入成本失控、MEMORY.md 條目爆炸、hook 變殭屍、spec.md 重複。本 skill 掃 8 個 home 找冗贅,提議 retire 候選,加嚴執行 Rule-of-3 SSOT + 行數預算。
+
+**對齊 CLAUDE.md `# 資訊治理 canonical`**:本 skill 是 L3(Periodic deep)實作。L1(pre-write hook)+ L2(fire log)自動執行,L3 需人決策 canonical retire,走 checkpoint。
+
+**對齊 CLAUDE.md `# 稽核 canonical`「Audit-vs-execute 分權」**:動 canonical substantive meaning → **STOP 提議**;對齊 / 清 duplicate / 回填 pointer → **AUTO**。
+
+## When to run
+
+- CLAUDE.md 超過 800 行(hook 硬 cap 觸發)
+- MEMORY.md 超過 20 條 index
+- 季度健檢(每 3 個月跑 1 次)
+- `/design-system-audit --deep` Phase 4.5 自動 chain
+- 單一 spec.md 超過 500 行(hook 硬 cap 觸發)
+
+## Non-goals
+
+- 不動 code(`.tsx` / `.css` / `.ts`)— 只動 governance 文件
+- 不 retire 被 hook / skill 仍引用的 rule(先改 consumer,再 retire)
+- 不刪歷史 commit / git log
+- 不 rewrite spec.md 內容(只刪 duplicate / 提議合併,實質改寫走 `/design-system-audit`)
+
+---
+
+## Workflow(5 phases)
+
+### Phase 0 — Baseline scan(AUTO)
+
+掃 8 個 home 建立基準表:
+
+```
+Home              Size           Over-budget?
+─────────────────────────────────────────────
+CLAUDE.md         N lines        [target ≤ 200 / transition ≤ 400 / hard cap 800]
+MEMORY.md         N entries      [≤20]
+spec.md total     N files        per-file ≤300
+SKILL.md total    N files        per-file ≤250
+hooks             N scripts      (count only, Phase 3 看 fire log)
+memory files      N              per-file ≤100
+.claude/logs/     parse existing  (feed Phase 3)
+```
+
+**Output**:`phase0-baseline.md`(session-local,不 commit)
+
+### Phase 0.5 — 讀 external signal(AUTO)
+
+讀 `.claude/logs/` + `.claude/benchmarks/`(Commit 5 後):
+
+- `hook-fires.jsonl` — governance-file edits(tool/path per event);用於 hot governance files 分析
+- `hook-fires-per-hook.jsonl` — per-hook fire count(2026-04-25 起);via shared helper `.claude/hooks/_log-fire.sh`;啟用 D2 dead-hook detection
+- `skill-invokes.jsonl`(若存在)— 過去 3 月每 skill invoke 次數
+- `user-corrections.jsonl`(若存在)— pending codification 清單
+- `benchmarks/claude-code-features.jsonl` — 新 CC feature 採用提議
+- `benchmarks/external-ds-snapshots/*.md` — Polaris / Material / Atlassian 近期更動
+
+**Output**:外部 signal 摘要(送 Phase 3 judging)
+
+### Phase 1 — 4 維 scan(並行 sub-agent)
+
+4 個 sub-agent 並行跑,每個產 finding 清單:
+
+#### D1 — Duplicate across homes(Rule-of-3)
+
+Scan:同概念(同 keyword / 同 canonical)出現在 ≥ 3 個不同 home 寫完整 rule?
+
+Example violations(historic — 2026-05-22 prune verify 後均已收斂為 pointer 模式,僅留作教學範例):
+- `Portal 逃脫 theme`:過去在 hover-card.spec.md / avatar.spec.md / color.spec.md 各重述;現只 M3 SSOT + 各 spec pointer。2026-05-22 audit verify 為已對齊(僅 ui-development.md / meta-patterns.md 2 home 涉及,clean pointer)
+- `Inline Action vs Button predicate`:過去 CLAUDE.md / item-anatomy.spec.md / button.spec.md 各完整;現 `inline-action.spec.md` 為 SSOT,其他 cross-link
+- 新範例(2026-05-22 抓):**hook count threshold** 在 CLAUDE.md L35 / meta-patterns M14 / M20 / `session_start_governance_check.sh:173` 4 處 drift 3 值(40/35/30)→ M14/M20 strip 數字改 pointer SSOT 修
+
+**Output**:duplicate cluster 清單 + 建議 SSOT home。
+
+#### D2 — Dead & stale(fire / edit recency)
+
+- **Dead hooks**:讀 `.claude/logs/hook-fires-per-hook.jsonl`(2026-04-25 起 instrumented via `_log-fire.sh` helper),6 月 0 fire 的 hook 名 → retire 提名
+- **Stale memories**:`ls -la ~/.claude/.../memory/*.md`,6 月無 git log 變動且不在 MEMORY.md index head = stale
+- **Unused skills**:`skill-invokes.jsonl` 3 月 0 invoke(除非是 rare-event skill,例 `delivery-handoff`)
+
+**Output**:retire 候選 + rationale(`fire=0 / last_edit=2025-10 / 被 M14 吸收`)
+
+#### D3 — Over-concrete case studies
+
+Scan:Meta-Pattern / spec / memory 條目是「單次 bug 敘述」而非「meta 抽象」?
+
+Example:
+- M-row 是「2026-04-22 Dialog autoFocus tooltip 洩漏 / body 未用 ScrollArea / ... 7 題炸」這種純敘述 → 是否該抽成「凡 overlay + subtree context,必 self-scan N 題」的 meta rule?
+- feedback memory 條目:「2026-04-21 User 抓到 applicable-where-meaningful」→ 是否已被 M10 / M14 吸收?
+
+**Output**:候選 abstract proposal + 被吸收後可刪的下游條目
+
+#### D4 — Cross-home contradiction
+
+Scan:CLAUDE.md canonical vs spec.md vs skill reference 描述同概念時**語義衝突**(非表達差異)?
+
+Example:
+- CLAUDE.md M3 說「Portal 必繼承 data-theme」;但 avatar.spec.md 說「Portal 必繼承 data-theme + data-density」— 差 `data-density`,看誰真 SSOT
+- CLAUDE.md `# 稽核 canonical` 列 D4 UX 同時也談 3-tier scope — 2026-04-24 已合併為一章(原本 2 章重疊)
+
+**Output**:matrix of 衝突點 + 誰該讓步
+
+#### D5 — Canonical drift(spec vs code 語義漂移)— 2026-05-17 加
+
+Scan:`*.spec.md` 寫的 canonical vs `*.tsx` 實際 code 行為衝突 / spec 寫禁止但 code 仍用 / spec 升級但 code 沒跟。
+
+Example:
+- `radius.spec.md:57-71` 禁 `rounded-xl/2xl/3xl` → grep `packages/design-system/src/**/*.tsx` 仍有用 → drift
+- `field-controls.spec.md` v13 state machine 升級 → 但 Combobox.tsx 還是 v12 behavior → drift
+
+**Output**:per (spec, code) drift entry + 對應 commit hash 追溯 last alignment 時點
+
+#### D6 — Hook-fire health(log-driven)— 2026-05-17 加
+
+讀 `.claude/logs/hook-fires-per-hook.jsonl`,3 大病徵:
+- **Dead**:6 月 0 fire(retire 候選,per `# Retire rules` Hook 規則)
+- **Hot**(過 fire):fire / day > 50 → 可能 false positive 多 / regex 太鬆
+- **Toggle pattern**:同 fire 反覆 inject + retract → hook design 不穩
+
+**Output**:dead retire list + hot tune list + toggle re-design list
+
+#### D7 — Skill-invoke health(log-driven)— 2026-05-17 加
+
+讀 `.claude/logs/skill-invokes.jsonl`,2 大病徵:
+- **Unused**:3 月 0 invoke(除 rare-event skill 如 delivery-handoff)
+- **Always co-invoked**:Skill A 永遠跟 Skill B 一起 invoke → 該合 1 skill 或 chain auto
+
+**Output**:retire list + merge candidate list
+
+#### D8 — Memory recency / orphan— 2026-05-17 加
+
+Scan `~/.claude/.../memory/*.md`:
+- 6 月無 git log 變動 + 不在 MEMORY.md index head = stale candidate(per existing D2 retire rule)
+- file 存在但 MEMORY.md 沒 entry = orphan(可能 retire 漏刪)
+- entry 存在但 file 不在 = broken pointer
+
+**Output**:stale / orphan / broken pointer 3-class list
+
+#### D9 — Benchmark / citation debt(2026-05-17 加,對應 M22)
+
+Scan 全 repo:
+- `@benchmark-unverified-blanket` marker(per file retraction;codify 後該 backfill cite 變 verified)
+- spec.md / tsx 含 world-class DS keyword(Material / Polaris / Carbon / Ant / Atlassian / Apple)但無 inline URL / GitHub path / screenshot ref
+- 過期 benchmark(cite URL 是 v3 但 framework 已 v5)
+
+**Output**:per (file, claim) cite debt entry + 建議 WebFetch 補 source
+
+#### D10 — Verification artifact rot(2026-05-17 加,對應 M32)
+
+Scan 全 audit / test infra:
+- audit script 只驗 `getAttribute(...)` / `class.includes(...)` 不驗 `getBoundingClientRect()` numeric(pixel-quantified 缺)
+- `*.spec.md` 寫 visual canonical 但無對應 playwright snapshot 或 visual-audit 覆蓋
+- stale screenshot ref(snapshot file 6 月未更新)
+
+**Output**:per audit script 升 pixel-quantified 提名 + 缺 visual coverage 列表
+
+### Phase 2 — Triage + Checkpoint 1(MUST ASK)
+
+```
+Phase 1 findings:
+- D1 duplicate: M clusters
+- D2 dead/stale: N items
+- D3 over-concrete: K items (abstract proposals)
+- D4 contradiction: L pairs
+
+Priority:
+- P0 (AUTO): 對齊 SSOT / 補 pointer / 刪 confirmed dead hook / retire unused skill — 表達層調整,不動 canonical 意思
+- P1 (AUTO with brief report): 合併 duplicate(保 semantic)/ 刪 6+ 月 stale memory(非 critical)/ 編號 renumber
+- P2 (STOP / CHECKPOINT): 抽新 meta / 合併 contradiction 要選哪邊 / 撤 Meta-Pattern / 改 SSOT ownership
+
+Proceed with P0+P1 as atomic commit? Then discuss P2?
+```
+
+**Do NOT skip**:P2 動 canonical substantive,per `# 稽核 vs 執行 分權`,必 user sign-off。
+
+### Phase 3 — Apply P0 + P1 fixes(分組 commit)
+
+- 每個 cluster 一個 commit(`prune: duplicate X → SSOT owner Y / pointers elsewhere`)
+- 每次 commit 後 `npx tsc -b` 驗證(prune 不動 code,但防 spec path 斷)
+- 每 commit 後重跑 Phase 0 baseline,確認 size 有下降
+
+### Phase 4 — P2 discussion + apply(user sign-off 後)
+
+- 每 P2 item 一個獨立 commit(animation trail 可回溯)
+- 新 meta-pattern 加進 CLAUDE.md `# Meta-Pattern 預警` → 同時**必檢討哪些下游條目冗餘**(上游加 = 下游減)
+
+### Phase 5 — Final report + **quantified retire rate** + baseline update
+
+**Retire rate 計算公式**(從 aspirational 轉 quantified,2026-04-24):
+
+```
+total_governance_items_before = 
+  count(CLAUDE.md 章節) 
+  + count(Meta-Pattern 條目)
+  + count(.claude/skills/)
+  + count(.claude/hooks/)
+  + count(MEMORY.md entries)
+  + count(memory files)
+  + count(spec.md SSOT anchors)
+
+retired_this_quarter = items 本次 /knowledge-prune 刪 / 合併 / 撤
+
+retire_rate = retired_this_quarter / total_governance_items_before
+```
+
+**Target**:≥ 5% / quarter。< 5% 不一定壞(系統已成熟 / 無冗贅),但必在 report 明寫 rationale(「成熟 — 無 retire 候選 / stable ecosystem」),不可空白。
+
+```markdown
+## Prune report(N 日期)
+
+### Metric delta
+- CLAUDE.md: B → A(-X 行)
+- MEMORY.md: B → A(-Y 條目 / -Z 檔)
+- Total spec.md: B → A(-Z 行)
+- Hooks: B → A(-N 個 hook retired)
+- Skills: B → A(-N 個 skill retired)
+- **Retire rate: X% = retired N / total M**(target ≥ 5%)
+  - 公式套用見本 Phase 頂部
+  - 若 < 5% 必附 rationale(成熟 / 無冗贅 / deferred 等)
+
+### Retired(實際)
+- {list of retired items + why + grep 確認無 reference}
+
+### 未達 retire target rationale(若 < 5%)
+- {e.g. "governance ecosystem stable, 上季已大幅 prune,本季無重大冗贅"}
+
+### Still deferred(P2 pending user sign-off)
+- {list}
+
+## Self-improvement capture
+- 新發現 prune pattern: {...} OR "無"
+- 新確立 anti-bloat rule: {...} OR "無"
+- 下次 prune trigger 建議: {...}
+```
+
+Update `.claude/logs/metric-snapshots.jsonl`:
+
+```json
+{"ts":"2026-04-24","retire_rate":0.07,"retired":5,"total_before":71,"claude_md_lines":612,"hooks_total":18,"skills_total":13,"memory_entries":29}
+```
+
+**本 snapshot 讓 `/governance-health` trend 分析:**若 3 季連續 retire rate < 5% 且 governance 行數仍增 → auto-propose「有隱性冗贅未抓,考慮換 /knowledge-prune 掃描策略」。
+
+---
+
+## Checkpoints(禁止跳)
+
+### ⚠️ Checkpoint 1 — Phase 2 triage(見上)
+
+### ⚠️ Checkpoint 2 — 動 Meta-Pattern(P2)
+
+提議撤 / 合併 / 改寫 Meta-Pattern 條目前 STOP。Meta-Pattern 是 CLAUDE.md 最上游,動意思必 user 拍板。
+
+### ⚠️ Checkpoint 3 — 抽新 canonical
+
+Phase 1 D3 發現 5+ 條下游條目可被新 meta 吸收 → 提議新 Meta-Pattern 前走命名三 test + world-class benchmark(對齊 CLAUDE.md M8 / M12)。
+
+### ⚠️ Checkpoint 4 — Retire 率 < 5%
+
+季度 prune 若 retire 不到 5%,表示:(a) 真沒冗餘(罕見),OR (b) judgment 太保守。STOP 跟 user 確認哪邊。
+
+---
+
+## Retire rules(執行規則)
+
+| 項目 | Retire criteria |
+|------|-----------------|
+| Hook | 6 月 `hook-fires-per-hook.jsonl` 0 fire + 無 future-planned consumer |
+| Skill | 3 月 0 invoke + 非 rare-event skill(release-cut 類可例外) |
+| Meta-Pattern 條目 | 被新上游 meta 完全吸收 + grep 無引用 |
+| Memory file | 6 月未更新 + 現況已不符 + MEMORY.md 無 head pointer |
+| Spec 段落 | 被 SSOT pointer 取代 + grep 無外部引用 |
+
+**Hard rule**:retire 前必 grep 全 repo 無 reference,避免斷鏈。
+
+---
+
+## 世界級對照
+
+本 skill 是本 DS 原創的自我 prune 機制,但對齊:
+
+- **Elasticsearch Index Lifecycle Management**:hot / warm / cold 階段自動降級 + delete old data — 類 retire rate
+- **Linux kernel doc policy**:Sphinx deprecation warnings + removal schedule — 類 transition period 過渡期
+- **Python PEP 387 Backwards Compatibility Policy**:明定哪些改動需 deprecation 期,哪些可立刻刪 — 類 P0 vs P2 triage
+
+## 與其他 skill 的分工
+
+| Skill | Scope | 不重疊點 |
+|-------|-------|---------|
+| `/design-system-audit` | **33 維 DS code + spec audit**(Phase 0 自建 baseline) | 不管治理文件冗贅 — 找 bug / drift,不 prune governance 大小 |
+| `/knowledge-prune` | **治理文件冗贅 + 行數 + 矛盾** | 不 audit DS code 本體 — 管 governance 不管 DS |
+
+---
+
+## Non-goals 重申
+
+- 不 refactor spec.md 內容(改寫走 `/design-system-audit`)
+- 不 retire 有 active consumer 的 rule(必先改 consumer)
+- 不處理 `git log` 歷史 / 歷史 commit 訊息