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

package/ds-canonical/skills/scan-similar-bugs/SKILL.md

@@ -8,27 +8,27 @@ description: Auto-invoke after fix commits — extracts root-cause anti-pattern,
 **目的**:任何 bug fix 提交後,**機械化掃 DS-wide 找同 pattern**,而非靠 model 記得 M10。
 
 **對齊**:
-- CLAUDE.md M10 「Proactive exhaustive scan」mechanical 落地
+- `packages/design-system/ds-canonical/rules/meta-patterns.md` M10 「Proactive exhaustive scan」mechanical 落地
 - mindset #1「不取巧」+ #2「優先消費既有」+ #6「meta 抽象」
 - 對齊 IDE「find similar / find references」+ Chrome DevTools「find usages」+ GitHub Copilot「related code」3+ 家世界級 idiom
 
 **對位其他 skill**:
-- `/design-system-audit` 是**定期 batch** 7 維 audit
+- `/design-system-audit` 是**定期 batch** full-dim audit
 - `/visual-audit` 是**單次視覺對齊** check
-- 本 skill 是 **batch-end-only root-pattern scan**(2026-05-12 codex 抓 infra conflict 重構:per-fix → batch-end,對齊 `/bug-fix-rhythm` Phase 2-3 batch fix + single end-verify canonical;M32 split 後 batch-end home 移至 bug-fix-rhythm skill)
+- 本 skill 是 **batch-end-only root-pattern scan**(2026-05-12 independent review 抓 infra conflict 重構:per-fix → batch-end,對齊 `/bug-fix-rhythm` Phase 2-3 batch fix + single end-verify canonical;M32 split 後 batch-end home 移至 bug-fix-rhythm skill)
 
 ## When to invoke
 
-**強制(auto-chain)— batch-end only**(2026-05-12 重構,per codex):
+**強制(auto-chain)— batch-end only**(2026-05-12 重構,per independent review):
 - multi-issue session 結束後**一次**(不是每 fix 一次)
 - session 內 ≥ 2 fix commit 觸發批次 root-pattern scan
-- session_start_governance_check.sh 偵測 上 session 有 ≥ 2 fix commit 但 batch-end scan 沒跑 → 提醒
+- session_start_governance_check.sh Check 6 偵測 24h 內 ≥1 fix commit 且 skill-invokes log 24h 無 scan-similar-bugs invoke → soft 提醒
 
 **手動 invoke**:
 - user 明言「掃同類 bug / 看其他元件有沒有 / 全 DS scan」
 - multi-issue batch session 結束想驗 root-pattern DS-wide
 
-**不 invoke**(對齊 Anthropic Best Practice 小修 skip plan):
+**不 invoke**(對齊 provider-neutral best practice 小修 skip plan):
 - **Surgical visual bug**(user 列 N 個 visual defects + 無 canonical / API / cross-component → 批 fix + final verify only,不必 scan-similar)
 - pure refactor(無 bug 修復語義)
 - spec.md / docs only commit
@@ -36,9 +36,9 @@ description: Auto-invoke after fix commits — extracts root-cause anti-pattern,
 
 ## Non-goals
 
-- 不擴展 scope 到「audit 7 維品質」(那是 `/design-system-audit`)
+- 不擴展 scope 到「audit full-dim品質」(那是 `/design-system-audit`)
 - 不做視覺 regression baseline diff(那是 `/visual-audit`)
-- 不改 canonical(找到 pattern 後修是 surgical fix,動 canonical 走 audit / Checkpoint)
+- 不在本 skill 擴張成 full canonical redesign；工程治理 canonical remediation 轉交 audit 自主處理，只有產品／UI／UX SSOT 真取捨才是 human boundary
 
 ---
 
@@ -84,26 +84,27 @@ node scripts/scan-asymmetric-icons.mjs   # 已存在,iconOnly visual scan templa
 
 **Output**:候選清單(file:line + 樣本)。
 
-### ⚠️ Checkpoint 1 — Triage
+### Phase 1.5 — Authority classification + triage receipt
 
-向 user present:
+產出:
 ```
 Phase 1 found N candidates of same anti-pattern:
 - packages/design-system/src/components/A/a.tsx:42  > grep match
 - packages/design-system/src/components/B/b.tsx:18  > grep match
 - packages/design-system/src/components/C/c.tsx:55  > 視覺 14×16
 
-Proceed?
-- (a) Auto-fix all N(若修法 deterministic 例 token rename)
-- (b) Review per-file(若 fix 需個別判斷)
-- (c) 留 N 個 tech debt 後續處理(寫 memory + 不修)
+Execution:
+- deterministic fix → Auto-fix all confirmed N
+- engineering judgment → 依 owning spec + highest certified capability 逐檔收斂；task／deliverable 明確要求時才加 independent review
+- 不屬 frozen scope → Backlog with evidence；不得用 defer 逃避 scope 內修復
+- 會改產品／UI／UX SSOT 且仍有真取捨 → batch-at-end human-only decision
 ```
 
-不可 silent 跳過 user — fix scope 影響 N 元件,**M10 + 稽核 vs 執行 分權**要求 user 拍板。
+不可 silent 跳過 confirmed scope；影響 N 檔是工程 blast radius，不是 user approval gate。必記錄 scope、evidence、tests 與 rollback。
 
 ### Phase 2 — 批量 / 個別 fix
 
-按 Checkpoint 1 user 選的路執行。每修一檔:
+按 Phase 1.5 authority classifier 執行。每修一檔:
 - 用 Edit(不 Write,降風險)
 - 修完 grep 該 anti-pattern 應 0 match
 - npx tsc --noEmit 必過
@@ -130,7 +131,7 @@ Proceed?
 - {K} deferred(spec rationale 已記)
 
 ### New defense layer(防 future regression)
-- 加 hook:`.claude/hooks/check_<pattern>.sh`(若 pattern 易 grep)
+- 加 canonical hook:`packages/design-system/ds-canonical/hooks/check_<pattern>.sh`(若 pattern 易 grep)，再由 generator 投影到各 provider；禁止直接新增 provider-owned hook。
 - 加 visual test:`scripts/scan-<pattern>.mjs`(若需 Playwright)
 - 加 spec rule:{spec.md anchor}
 
@@ -146,16 +147,16 @@ Proceed?
 
 ---
 
-## ⚠️ Checkpoints(禁止跳)
+## Authority gates(禁止跳 classifier)
 
-### Checkpoint 1 — Phase 1 後 Triage
-N 個 candidate 的修法 scope。**禁止 auto-fix 超過 5 檔不 ask user**。
+### Gate 1 — Phase 1 後 Triage
+N 個 candidate 的修法 scope由 agent 依 frozen scope、canonical、tests 與 rollback 自行收斂；檔案數量不構成人類工程核准門檻。
 
-### Checkpoint 2 — 動 canonical
-若 N candidates 都 violate 同 canonical,但 canonical 本身可能 outdated → 走 audit 重訂(不在本 skill scope)。
+### Gate 2 — 動 canonical
+若 N candidates 都 violate 同 canonical,但 canonical 本身可能 outdated → 走 audit 重訂。工程／治理決策 AUTO；只有重訂會改產品／UI／UX SSOT 且存在真取捨才停。
 
-### Checkpoint 3 — Defer 的 tech debt
-若 user 選 (c) 留 tech debt → 必寫 memory + 標明「deferred at <date>,reason: <reason>」。`/codify-corrections` 季度會 review。
+### Gate 3 — Backlog
+只有不屬 frozen scope 的 improvement 才放 Backlog，必寫 memory + evidence + reason；Scope 內可修復項不得因 milestone 或工程偏好 defer。
 
 ---
 
@@ -163,17 +164,17 @@ N 個 candidate 的修法 scope。**禁止 auto-fix 超過 5 檔不 ask user**
 
 | Tool | scope | 跟本 skill 關係 |
 |---|---|---|
-| `/design-system-audit` | 7 維 batch audit | 本 skill 抓不到的 architectural pattern audit 補位 |
+| `/design-system-audit` | full-dim batch audit | 本 skill 抓不到的 architectural pattern audit 補位 |
 | `/visual-audit` | 單次視覺對齊 | Phase 3 verify 用 |
 | `/scan-similar-bugs`(本) | **immediate-after-fix grep + verify** | M10 mechanical 落地 |
 | `/knowledge-prune` | 季度 governance prune | 不重複 |
-| `check_l3_primitive_import.sh`(hook) | L3 import 違規 | 即時 detect,本 skill 是 batch retro scan |
-| `pre_write_subsumption_check.sh`(hook)| 新 file / M-row | 不重複 |
+| `check_canonical_propagation.sh` E.2(hook;原 check_l3_primitive_import.sh folded 折入,P0 BLOCK) | L3 primitive import 違規 | 即時 detect,本 skill 是 batch retro scan |
+| `pre_write_subsumption_check.sh`(retired 2026-06 → canonical `hooks/retired/`;新 file / M-row 治理由 `session_start_governance_check.sh` + `enforce_home_charter.sh` 現役防線接手)| 新 file / M-row | 不重複 |
 
 **3 層 防線**:
 - Hook(pre/post tool):**寫的瞬間** detect
 - 本 skill(fix-time):**修完瞬間** scan DS-wide
-- `/design-system-audit`(periodic):**季度** 7 維 sweep
+- `/design-system-audit`(periodic):**季度** full-dim sweep
 
 ---
 

package/ds-canonical/skills/story-auto-compile-migrate/SKILL.md

@@ -1,25 +1,25 @@
 ---
 name: story-auto-compile-migrate
-description: Batch-migrate design system components to Story Auto-Compile Phase 1+2 structure (tsx `componentMeta` export + spec.md YAML frontmatter). Mechanical steps auto (parse cva → generate componentMeta / infer sizes from cva / extract 禁止事項 from spec). Judgment fills (world-class 對照 / when descriptions) go to checkpoint for user/AI sign-off. Invoke via /story-auto-compile-migrate when user says「migrate 元件到 auto-compile / phase 4 migration / 把 X 元件加 componentMeta」OR auto-chained by /design-system-audit Dim 23 when un-migrated components found.
+description: Batch-migrate design system components to Story Auto-Compile Phase 1+2 structure (tsx `componentMeta` export + spec.md YAML frontmatter). Mechanical steps auto (parse cva → generate componentMeta / infer sizes from cva / extract 禁止事項 from spec). Judgment fills use existing canonical evidence plus the highest certified capability; independent review is added only when the task or deliverable explicitly requires it, and only a genuine product/UI/UX SSOT tradeoff stops. Invoke via /story-auto-compile-migrate when user says「migrate 元件到 auto-compile / phase 4 migration / 把 X 元件加 componentMeta」OR auto-chained by /design-system-audit Dim 23 when un-migrated components found.
 ---
 
 # Story Auto-Compile Migrate — 批次將元件移到 Phase 1+2 結構
 
-**目的**:把 44+ 元件從 hand-written stories 遷到 auto-compile-able 結構(tsx `componentMeta` export + spec YAML frontmatter)。分「mechanical auto」+「judgment checkpoint」兩層。
+**目的**:把全部元件從 hand-written stories 遷到 auto-compile-able 結構(tsx `componentMeta` export + spec YAML frontmatter)。分「mechanical auto」+「evidence-bound judgment」兩層。元件總數由 Phase 0 inventory 動態計，禁止 hardcode。
 
-**不含**:不改元件實作(cva / tsx logic 不動);不產 stories(compile-stories 負責)。只加 metadata。
+**不含**:不改元件實作(cva / tsx logic 不動);不寫入 stories files。`compile-stories.mjs` 只在 stdout 編譯 canonical rows並驗 drift；本 skill 只加 metadata。
 
 ## When to run
 
 - User 明言「migrate X 元件 / 批次 migrate / phase 4 migration」
-- `/design-system-audit --deep` Dim 23 發現未 migrated 元件 + user 在 Checkpoint 1 sign-off
+- `/design-system-audit --deep` Dim 23 發現未 migrated 元件後自動 chain
 - 新建元件 via `/new-component` 時 Phase X 自動跑(未來延伸)
 
 ## Non-goals
 
 - 不改 cva variants / defaults(變體結構不動)
 - 不動 stories.tsx 實作
-- 不填 judgment 欄位(world-class / when)— 只擺 TODO placeholder,跑 Phase 2 checkpoint
+- Phase 1 不憑空填 judgment 欄位(world-class / when)；Phase 2 必以 owning spec、primary-source benchmark補齊，不留 TODO；task／deliverable 明確要求時才加 independent review
 
 ---
 
@@ -28,10 +28,10 @@ description: Batch-migrate design system components to Story Auto-Compile Phase
 ### Phase 0 — Scan 未 migrated 元件
 
 ```bash
-node scripts/compile-stories.mjs --all --check 2>&1 | grep "skipped"
+node scripts/compile-stories.mjs --all 2>&1 | grep "Skipped"
 ```
 
-得清單:每元件 `{Name}(reason: no componentMeta export | no frontmatter)`。
+得清單(default 模式 `Skipped(N):` 行):每元件 `{Name}(reason: no componentMeta export | no frontmatter)`。(`--check` 模式只印 drift / skipped 總數,不含 per-component reason。)
 
 Output:待 migration 元件清單 + 每元件缺哪層(tsx only / spec only / 兩層都缺)。
 
@@ -82,20 +82,19 @@ related:
 
 Phase 1 output:N 元件成功 mechanical migrated / M 元件遇特殊 cva 邏輯需 Phase 2 手動 mapping。
 
-### ⚠️ Checkpoint 1 — 批量 sign-off
+### Phase 1.5 — Batch evidence receipt
 
-Present user:
+記錄並回報:
 ```
 Phase 1 完成:
 - ✅ {N} 元件 mechanical migrated(componentMeta + frontmatter placeholders in,compile --check passed)
 - ⚠️ {M} 元件 needs manual cva mapping(列出 + 原因)
 - TODO: {N+M} 元件 frontmatter 的 variants[].when / world-class[] / sizes[].when / related[] 是 judgment 欄位,Phase 2 填
 
-Proceed Phase 2 judgment fill?(scope big)
-OR commit Phase 1 先(mechanical only)讓後續 session 漸進 fill?
+Authority:ENGINEERING-AUTO；直接進 Phase 2。只有填值會創造新的產品／UI／UX SSOT 語意且仍有真取捨才列 human-only decision。
 ```
 
-### Phase 2 — Judgment fill(STOP per component)
+### Phase 2 — Judgment fill(AUTO, evidence-bound)
 
 對每個 migrated 元件:
 - `variants[].when` — 從 spec 現有「variants」section 或近親元件同名 variant 抄
@@ -103,7 +102,7 @@ OR commit Phase 1 先(mechanical only)讓後續 session 漸進 fill?
 - `sizes[].when` — 從 spec size table 抄
 - `related.近親` — grep SSOT reciprocal pointers
 
-每元件過 Checkpoint(user 可快速看 frontmatter diff,approve 或 reject 單題)。
+每元件過 owning-spec、benchmark、cross-field consistency 與 compile check；工程 mapping 自主收斂。若現有 SSOT 無法回答且選擇會改產品／UI／UX語意，集中成一次 human-only decision，不逐元件詢問。
 
 ### Phase 3 — Verify + commit
 
@@ -121,22 +120,24 @@ Commit 每批 5-10 元件一個(不一次全推,好 review)。
 ## Self-improvement capture
 - 新發現 cva patterns: {特殊邏輯整理到 planning/story-auto-compile.md 供未來參考}
 - Mechanical migration 失敗 case: {列出 + 手動 workaround 紀錄}
-- Migration 覆蓋率:{N migrated / 44 total}
+- Migration 覆蓋率:{N migrated / total}(total = Phase 0 動態計 `ls -d packages/design-system/src/components/*/ | wc -l`)
 ```
 
 ---
 
-## Checkpoints(禁止跳)
+## Authority gates(禁止跳 evidence，不設 blanket sign-off)
 
-### ⚠️ Checkpoint 1 — Phase 1 batch sign-off
+### Gate 1 — Phase 1 batch evidence
 
-### ⚠️ Checkpoint 2 — Phase 2 judgment 單題 sign-off(per element × per field)
+確認 keys、source citations、input digest 與 rollback；receipt 不停止 execution。
 
-可 user 批准「全預設套 AI 推斷」模式加速,但每批後 stop 檢查 5-10 element 產出。
+### Gate 2 — Phase 2 judgment(per element × per field)
 
-### ⚠️ Checkpoint 3 — 特殊 cva 遇到 mechanical 無法 map
+禁止無證據套預設。每批後 agent review 5-10 element 產出；全部元件仍須 complete-bytes／protocol coverage，不取樣判全域完成。
 
-STOP 提議 user:(a) 修 cva 對齊標準形;(b) componentMeta 特殊寫法;(c) 跳過該元件到下一個。
+### Gate 3 — 特殊 cva 遇到 mechanical 無法 map
+
+Agent 依 public contract、owning spec、consumer evidence與 rollback 自行選出唯一工程方案；若方案會改 public component 的產品／UI／UX語意且存在真取捨才 STOP，否則不可把(a)修 cva／(b)metadata 特例／(c)skip 的工程選擇丟給 user。
 
 ---
 
@@ -147,13 +148,13 @@ STOP 提議 user:(a) 修 cva 對齊標準形;(b) componentMeta 特殊寫法;(c)
 | 偵測未 migrated | `/design-system-audit --deep` Dim 23 |
 | 批次 mechanical migrate | **本 skill Phase 1** |
 | Judgment fill | 本 skill Phase 2(CP 2) |
-| Drift detection(已 migrated)| hook `check_story_compile_drift.sh` + Dim 23 |
+| Drift detection(已 migrated)| hook `post_edit_dispatcher.sh` → `lib/_story_compile_drift.sh`(原 check_story_compile_drift.sh folded)+ Dim 23 |
 
-**Chain**:user 說「ds 完整 audit」→ `/design-system-audit --deep` Phase 1 跑 Dim 23 → 發現 N 未 migrated → CP 1 提報 user → user sign-off → Phase 3 auto-chain 本 skill → mechanical migrate + judgment CP → 全 migrated + 0 drift。
+**Chain**:user 說「ds 完整 audit」→ `/design-system-audit --deep` Phase 1 跑 Dim 23 → 發現 N 未 migrated → 自動 chain 本 skill → mechanical migrate + evidence-bound judgment → 全 migrated + 0 drift；中途 report 只是 receipt。
 
 ## References
 
-- `.claude/planning/story-auto-compile.md` — 完整 4-phase plan
+- `governance/planning/story-auto-compile.md` — historical 4-phase plan + current non-executable status
 - `scripts/compile-stories.mjs` — compile + verify
-- `.claude/skills/story-writing/references/anatomy-standard.md` — 6-story canonical
-- `.claude/skills/new-component/SKILL.md` — 新建元件流程(本 skill 為已建元件 migration)
+- `packages/design-system/ds-canonical/skills/story-writing/references/anatomy-standard.md` — 6-story canonical
+- `packages/design-system/ds-canonical/skills/new-component/SKILL.md` — 新建元件流程(本 skill 為已建元件 migration)

package/ds-canonical/skills/story-writing/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: story-writing
-description: Guide for writing Storybook stories (.stories.tsx / .principles.stories.tsx / .anatomy.stories.tsx) with world-class example quality. Enforces real-product scenarios, 「人」+「舉一反三」tests, Rule-note 原則>結論, and anatomy 6-story structure(含 A11y,2026-04-24). Invoke when user says「寫 story」「新增範例」「補 anatomy」「principles story」or is about to create/edit any `.stories.tsx` file in design-system.
+description: Guide for writing Storybook stories (.stories.tsx / .principles.stories.tsx / .anatomy.stories.tsx) with world-class example quality. Enforces real-product scenarios, 「人」+「舉一反三」tests, Rule-note 原則優先於結論, and anatomy 6-story structure(含 A11y,2026-04-24). Invoke when user says「寫 story」「新增範例」「補 anatomy」「principles story」or is about to create/edit any `.stories.tsx` file in design-system.
 ---
 
 # Story Writing
 
-Purpose: Storybook 是公開文件,範例 = 設計系統品質。本 skill 把「怎麼挑範例 / 怎麼寫 anatomy / 三方連動怎麼不漂移」集中成 invoke-time playbook,CLAUDE.md 只留最高準則 + 禁止清單。
+Purpose: Storybook 是公開文件,範例 = 設計系統品質。本 skill 把「怎麼挑範例 / 怎麼寫 anatomy / 三方連動怎麼不漂移」集中成 invoke-time playbook,shared governance 只留最高準則 + 禁止清單。
 
 ## When to run
 
@@ -15,21 +15,21 @@ Purpose: Storybook 是公開文件,範例 = 設計系統品質。本 skill 把
 
 ## Preconditions
 
-- 讀過 `.claude/rules/story-rules.md`(三層定位 + title 命名 + 範例最高準則)
+- 讀過 `packages/design-system/ds-canonical/rules/story-rules.md`(三層定位 + title 命名 + 範例最高準則)
 - 該元件的 `.spec.md` 已存在且本 session 已讀(stories 必須反映 spec,不發明新規則)
 - 若寫 anatomy:元件 `.tsx` 的 cva 定義已看過(TOKEN_MAP / SIZE_SPECS 必須與 code 一致)
 
 ## Workflow
 
-### Phase 0.0 — Registry-driven baseline grep(2026-05-20 升級 per codex Layer B D4)
+### Phase 0.0 — Registry-driven baseline grep(2026-05-20 升級 per independent review Layer B D4)
 
 **MUST 在 Phase 0 / 0.5 / 1+ 之前先跑**:
 
-1. **Load registry**:Read `.claude/references/story-baseline-registry.json`。檔內列每個 primitive(Sidebar / DataTable / ChromeHeader / etc.)的:
+1. **Load registry**:Read `packages/design-system/ds-canonical/references/story-baseline-registry.json`。檔內列每個 primitive(Sidebar / DataTable / ChromeHeader / etc.)的:
    - `baseline`:production-grade canonical story path#StoryName
    - `requiredHelpers`:必 import 的 helper list(WorkspaceBrand / MAIN_NAV / etc.)
    - `antiPatterns`:regex + severity(block / warn)+ rationale
-   - `variantRules`:variant + size + prop combo canonical(eg. DataTable toolbar = text + sm + iconOnly + pressed)
+   - per-primitive 補充欄(欄名依 primitive):`toolbar.buttonCanonical`(DataTable — variant + size + prop combo canonical,eg. toolbar = text + sm + iconOnly + pressed)/ `requiredStructure`(ChromeHeader)
 2. **Read baseline + helpers**:跑 grep + Read 取真實 production canonical 用法,Read 對應 helper source code
 3. **Produce diff table**:`primitive → baseline path → copied structure → deviations(if any with rationale)`
 4. **No registry entry?**:STOP,先 add registry entry 才能寫 story。不能憑直覺寫 simplified mock。
@@ -41,7 +41,7 @@ Purpose: Storybook 是公開文件,範例 = 設計系統品質。本 skill 把
 
 ### Phase 0.5 — 展示層拆分原則 mapping(展示 stories 必走)
 
-對 `{name}.stories.tsx`(展示)層,寫前必走 4 步(對齊 memory `feedback_proactive_5layer_pipeline.md`「5-step pre-check」— 若寫 stories 時消費其他元件 tsx,該層也適用):
+對 `{name}.stories.tsx`(展示)層,寫前必走 4 步(對齊 `packages/design-system/ds-canonical/references/ssot-consultation.md`「5-step pre-check」— 若寫 stories 時消費其他元件 tsx,該層也適用):
 
 1. **對 category**(see `references/category-templates.md`)— 元件屬 A-G 哪 category,suggested core stories 是什麼?
 2. **讀 spec.md** 列該元件 distinct rules(每 variant / prop / state 一條)+ 對照 category core list 補缺
@@ -51,9 +51,9 @@ Purpose: Storybook 是公開文件,範例 = 設計系統品質。本 skill 把
    - AllVariants / AllSizes 對照各 1
    - Compound 有 new constraint(prop 名變 + 必某 affordance)→ 必分(`OverlayBadgeOnIconOnly`)
    - 真實業務情境 → 1 場景 1 故事
-4. **present mapping** 給 user sign-off(若走 skill);user 拍板才寫;反 pattern 在 step 3 即可避免
+4. **authority classify + apply**:mapping 若只是把既有 spec/code mechanically 投影成 story，依 Standing Authorization AUTO 寫入；只有 mapping 會新增或改變產品／UI／UX SSOT，且證據收斂後仍有真實選擇／取捨，才將 exact target-bound decision batch 給 user。反 pattern 在 step 3 即可避免。
 
-Hook `check_story_slot_split.sh` write-time block 同源反 pattern。Audit `/design-system-audit` Dim 28 後驗。
+Hook `check_story_invariants.sh` R2 slot_split write-time block 同源反 pattern。Audit `/design-system-audit` Dim 28 後驗。
 
 ### Phase 1 — 定位(決定寫哪層 story)
 
@@ -82,7 +82,7 @@ Hook `check_story_slot_split.sh` write-time block 同源反 pattern。Audit `/de
 
 **參考 `references/anatomy-standard.md`**——每個元件 anatomy 必備 **6 件套**(`export const Overview / Inspector / ColorMatrix / SizeMatrix / StateBehavior / Accessibility`,一字不差;Accessibility 第 6 章 2026-04-24+ 對齊 Material / Polaris / Atlassian) + Inspect 面板規格 + token-first 原則 + 值溯源完整性。
 
-**偏離 canonical 規則**(CLAUDE.md 「Consistency Audit 原則」):
+**偏離 canonical 規則**(shared governance `# 稽核 canonical`「Consistency 類稽核必 Phase 0 全掃再判」;偏離需 rationale 由 design-system-audit Dim 13 enforce):
 - 追加第 7+ 個元件特有 story → OK,免 rationale
 - 取代 6-canonical 中某個 → **必須在元件 spec.md 寫 rationale**
 - 同概念改名(如 `VisualTokens` 取代 `ColorMatrix`) → **禁止**
@@ -102,12 +102,23 @@ Checkpoint: 寫完後必驗:
 - spec 新加 rule → principles stories 必有對應 do/don't 範例
 - 元件改 variant/size → anatomy TOKEN_MAP / SIZE_SPECS 同步
 
-**STOP 條件**:若三方(code / spec / story)任一有矛盾且原因不清楚 → 停下問 user,不默默改一邊。
+**STOP 條件**:若三方(code / spec / story)任一有矛盾且原因不清楚 → 先以 canonical owner、repo evidence 與 tests 分類；只有 task／deliverable 明確要求時才加 independent review。可唯一推導的工程 drift 自主修復；只有涉及產品／UI／UX SSOT 真取捨才交 user；仍無法分類則 fail closed，不默默選邊。
 
 ### Phase 5 — 自我檢查 checklist
 
 **參考 `references/self-check.md`**——7 題 checklist 全部打勾才算完成:範例真實性 / 「人」test / 舉一反三 / 無極端案例 / 無代號 / Rule note 原則>結論 / 無中英夾雜。
 
+若 meta 使用 `tags: ['autodocs']`，另確認 `parameters.docs.description.component` 已用人話說清
+用途與何時用／近親分界；這是 Docs 首屏導讀，不是貼 component 名或 API 摘要。最後跑
+`node scripts/audit-content-quality.mjs --check`，缺導讀、stub、抽象名稱、可見符號圖或 raw Markdown
+任一項都不得交付。
+
+若 story 只供 automation probe(hover/focus/open snapshot、效能量測、import smoke)，在 story-level
+標 `tags: ['test-only']`：shared runtime 只把它從 sidebar + Autodocs 隱藏，仍保留 direct URL、index
+與 a11y/interaction runner。不得用 `!autodocs`，也不得搭配 `!dev` / `!test`；reader-facing scenario
+不得為了縮短目錄而誤標 test-only。語意與 regression 由 `story-rules.md` +
+`scripts/test-storybook-test-only-semantics.mjs` 看守。
+
 ## References
 
 - `references/category-templates.md` — 7 category(A-G)suggested core stories(展示層 emergent typology)
@@ -117,6 +128,6 @@ Checkpoint: 寫完後必驗:
 
 ## 相關
 
-- `.claude/rules/story-rules.md`:三層定位 + title 命名(high-level signal)
-- CLAUDE.md `# 失敗記憶索引` → 三方漂移:SegmentedControl cva defaultVariants bug
-- `.claude/hooks/check_sync_update.sh`:Edit 後自動提醒三方連動
+- `packages/design-system/ds-canonical/rules/story-rules.md`:三層定位 + title 命名(high-level signal)
+- shared governance `# 失敗記憶索引` → 三方漂移:SegmentedControl cva defaultVariants bug
+- M3 mindset #3「改一處看三處」:三方連動改靠 mindset(retired canonical `pre_edit_spec_check.sh`;`check_sync_update.sh` 亦 retired/未實作)

package/ds-canonical/skills/story-writing/references/anatomy-standard.md

@@ -58,7 +58,7 @@ export const Overview = {
 
 **嚴格警告**:曾經被誤用「applicable-where-meaningful」放行大量元件跳 Inspector,造成 anatomy 紙本文件不如世界級。**2026-04-21 audit 重修:policy 改回「6-canonical 預設全建(含 Accessibility),N/A 要硬 rationale」**。N/A 不是省工通行證。
 
-### 允許的偏離(CLAUDE.md「Consistency Audit 原則」公式)
+### 允許的偏離(shared governance `# 稽核 canonical`「Consistency 類稽核」公式;design-system-audit Dim 13 enforce)
 
 #### `@anatomy-rationale:` 檔頭註解(scope-N/A 的 canonical escape)
 
@@ -76,7 +76,7 @@ import type { Meta, StoryObj } from '@storybook/react'
 **何時不用**:section 只是還沒填完 — 補完內容,不要拿 escape 規避。
 **世界級對照**:對齊 ESLint `eslint-disable-next-line {rule}` 的 per-line allowlist idiom — 每個豁免必有具名 rule + 一行 rationale,不允許整檔默默繞過。
 
-`check_story_anatomy.sh` 識別 `@anatomy-rationale:` block:列出的 section 視為 legitimately N/A;未列出的 missing section 仍 violation。
+`check_story_invariants.sh` R1 anatomy 識別 `@anatomy-rationale:` block:列出的 section 視為 legitimately N/A;未列出的 missing section 仍 violation。
 
 #### 其他允許的偏離
 

package/ds-canonical/skills/story-writing/references/category-templates.md

@@ -2,7 +2,7 @@
 
 世界級 DS(Polaris / Material / Atlassian / Ant / Carbon / Storybook 官方)的 Storybook story 結構**不是** category-based prescription(「button-likes 必有 5 stories」),是**trait-based**——元件依自身能力宣告 traits,required stories 由 trait 衍生。本 doc 是本 DS canonical typology v2,取代 v1 7-category。
 
-對應 `.claude/rules/story-rules.md`「拆分原則」+ M8 world-class benchmark。
+對應 `packages/design-system/ds-canonical/rules/story-rules.md`「拆分原則」+ M8 world-class benchmark。
 
 ## 為什麼 v2 trait-based(取代 v1 category-based)
 
@@ -17,8 +17,8 @@ v1 7 categories(A 視覺 variant / B field control / C selection / D structural
 - **Polaris Button**:24 stories(variant × tone matrix,但 sizes 散在 per-variant)
 - **MUI Button**:18 example files,trait-driven(BasicButtons / OutlinedButtons / IconLabelButtons / LoadingButtons)
 - **Ant Button**:22 demos,one demo = one focused trait
-- **Storybook 官方**:推薦 Default first + CSF3 args,**不 prescribe count or required set**
-- **共識**:`Default` 必有 / `WithIcon` merged grid 不拆 / overlay default-open `useState(true)` / Disabled 多數有但非絕對 / scenarios 多寡看 component 性質
+- **Storybook 官方**:推薦把代表性 baseline 放前面 + CSF3 args,**不 prescribe exact export name、count or required set**
+- **共識**:每個 showcase 至少一個 reader-facing 代表範例；`Default` 只有在 minimal baseline 本身值得獨立存在時才用 / `WithIcon` merged grid 不拆 / overlay default-open `useState(true)` / Disabled 多數有但非絕對 / scenarios 多寡看 component 性質
 
 → trait-based 對齊 5/5 benchmark systems(M8 ≥ 3 ✓ overshot)。
 
@@ -26,7 +26,7 @@ v1 7 categories(A 視覺 variant / B field control / C selection / D structural
 
 ### Universal(每元件必有)
 
-- **Default** — 最 minimal 代表性範例(對齊 Storybook 官方 + Carbon idiom)
+- **至少一個 reader-facing representative story** — export 名按它真正教的情境命名；`Default` 是可選名稱，不是 compliance token。只有最小 baseline 能獨立教會讀者時才開 `Default`，否則由第一個完整 scenario／matrix 擔任代表範例。
 
 ### Conditional traits → required stories
 
@@ -43,7 +43,7 @@ v1 7 categories(A 視覺 variant / B field control / C selection / D structural
 | `isSelectionSingle` | Switch / 單一 toggle(無群組概念) | `States` only(對齊 Material/Polaris/Carbon Switch idiom — 無 group story) |
 | `isMatrixHeavy` | Avatar / Skeleton / Spinner / Badge / Slider 等 token × size 正交視覺軸 | ≥ 4 matrix stories(`Modes` / `Shapes` / `Colors` / `AllSizes` 任 4) |
 | `isStructural` | DataTable / Steps / Tabs / Accordion 結構主導 | 每結構變體 1 story(無固定數,過 earn-existence) |
-| `isInternal` | L3 building block(被其他元件消費) | 1 `Default` + ≤ 1 composition scenario(寬鬆,Internal/ 命名空間下) |
+| `isInternal` | L3 building block(被其他元件消費) | 1 個代表性 primitive story + ≤ 1 composition scenario(寬鬆,Internal/ 命名空間下；不強迫命名 `Default`) |
 
 ### Optional universal
 
@@ -85,7 +85,8 @@ v1 7 categories(A 視覺 variant / B field control / C selection / D structural
 
 - **多 trait 元件**(e.g. Button = `hasVariants` + `hasSizes` + `hasInteractiveStates`)→ 各 trait required 都有
 - **Family 跨界**(Field control 同時 isInputLike + hasInteractiveStates)→ Union of all traits
-- **新 trait 提議**:跑 M8(≥ 3 家 DS benchmark)+ Checkpoint user sign-off,不孤立發明
+- **新 trait 提議**:跑 M8(≥ 3 家 DS benchmark)；若仍涉及 public component/UI
+  semantics 真取捨才進 exact P2H checkpoint，工程 metadata／治理調整則 P2E AUTO。
 
 ## Typology 演進規則(對齊 user mandate「除非調整標準」)
 
@@ -93,14 +94,14 @@ v1 7 categories(A 視覺 variant / B field control / C selection / D structural
 
 1. 提案 invoke `/ensure-canonical` skill(M19 trigger)
 2. 跑 M8 benchmark(≥ 3 家 DS)
-3. Checkpoint sign-off
+3. 依 authority classifier 處理:P2E 自主決策；只有產品／UI／UX SSOT 真取捨才 exact P2H sign-off
 4. 落地 5-layer pipeline(typology + hook + audit + scaffold + memory)
 
 ## Cross-link
 
-- `.claude/rules/story-rules.md`「拆分原則」— canonical 上游 one-liner
+- `packages/design-system/ds-canonical/rules/story-rules.md`「拆分原則」— canonical 上游 one-liner
 - `/story-writing` SKILL.md Phase 0 — write-time mapping
-- Hook `check_story_category.sh` — pre-write enforcement(攔不符 trait core)
+- Hook `check_story_invariants.sh` R3 category — pre-write enforcement(攔不符 trait core)
 - `/design-system-audit` Dim 29 — periodic verify
 - `/new-component` Phase 5 — 新元件 trait-based scaffold
 - `scripts/compile-stories.mjs` — runtime trait → required stories check
@@ -134,10 +135,10 @@ v1 7 categories(A 視覺 variant / B field control / C selection / D structural
 - `ContentGuidelines` 永遠獨立(文案 vs 元件選擇 是不同主題)
 
 **Legacy aliases 接受**(不強制 rename 既存 stories):
-- `WhenToUse` / `WhenNotToUse` / `Vs*Rule` 任 1 已存在 = 算「has core」
-- 新元件用 `UsageGuidance` 整合單一 story
+- split style 必涵蓋至少 2 個不同 decision dimensions:`WhenToUse` / `WhenNotToUse` / `Vs*Rule` / `ContentGuidelines`
+- 新元件預設用單一完整 `UsageGuidance`(何時用 + 何時不用 + sibling boundary)
 
-**規則**:每元件 principles 至少 **2 個 stories**(任意 combo:canonical 4 + component-specific `*Rule` + 描述性名稱如 `BlueConnectorLogic` / `ParentControlled` 都算 valid)。**全 4 個必有** = over-engineer(Polaris 4/4,但 Carbon Ant 都不到);**少於 2 stories** = principles 太薄無教學價值。Audit `audit-content-quality.mjs` 採寬鬆 ≥ 2 exports 標準(承認既有 component-specific naming idiom)。
+**規則**:**ONE complete `UsageGuidance` is sufficient**。不得為了湊數再開第二篇；額外 principles story 只有在教 distinct topic 且通過 earn-existence 2-test 時才保留。若採 split style，至少需要 2 個不同 decision dimensions；任意兩個 implementation notes／視覺重演不能靠 export 數量取得 compliance。Audit `audit-content-quality.mjs` 與 hook `check_canonical_propagation.sh` E.1 同規則。
 
 ## Canonical naming(取代既有 drift 變體)
 
@@ -168,7 +169,6 @@ v1 7 categories(A 視覺 variant / B field control / C selection / D structural
 
 ## 強制機制
 
-- **Hook** `check_principles_canonical.sh`:PreToolUse 攔不符 ≥ 2 universal core
+- **Hook** `check_canonical_propagation.sh` E.1 principles:PreToolUse 接受單一完整 `UsageGuidance`，split style 則攔少於 2 個 decision dimensions
 - **Audit Dim 30**:periodic verify
-- **`/new-component` Phase 5.3**:scaffold 4 universal stories template
-
+- **`/new-component` Phase 5.3**:預設 scaffold 單一完整 `UsageGuidance`；只有 distinct topic 才加第二篇

package/ds-canonical/skills/ux-audit/SKILL.md

@@ -13,7 +13,7 @@ description: UX behavior audit for design-system components and product UI. Chec
 
 本 skill 是稽核 6 維度的 **D4 UX 行為** canonical home。
 
-## 觸發時機(對齊 CLAUDE.md 稽核 canonical)
+## 觸發時機(對齊 shared governance 稽核 canonical)
 
 | 情境 | 模式 | 本 skill 跑什麼 |
 |------|------|----------------|
@@ -71,7 +71,7 @@ description: UX behavior audit for design-system components and product UI. Chec
 1. **Animation duration**:< 200ms(micro)或 200-400ms(macro);超過 400ms 主畫面 → 可能 block 輸入
 2. **Reduce-motion respect**:`@media (prefers-reduced-motion: reduce)` 下動畫減到 0 或極短
 3. **Wheel zoom step 細緻**:> 10% 離散 = 非世界級(對齊 Figma / Preview.app ~3-5%)
-4. **Hover delay**:tooltip / hover-card 的 open delay(700ms for tooltip, 500ms for hover-card per DS canonical)
+4. **Hover delay**:tooltip / hover-card 的 open delay(500ms for tooltip, 700ms for hover-card,per `tokens/motion/motion.spec.md` 三層 tier SSOT)
 5. **Drag / pan**:pointer capture 正確;release on blur
 
 ### Phase 5 — Data / state coverage 五態(2026-04-24 擴充,補 24-checklist #23 edge case gap)
@@ -91,7 +91,7 @@ description: UX behavior audit for design-system components and product UI. Chec
 - 從 uncontrolled 中途變 controlled(React warning 必出,或元件明文不支援)
 - Modal 關閉瞬間 async 回調仍 setState(unmount 後 setState warning)
 
-### Phase F — Report(必 STOP,對齊分權 canonical)
+### Phase F — Report and route
 
 產出:
 
@@ -110,11 +110,14 @@ description: UX behavior audit for design-system components and product UI. Chec
 ### P1(嚴重影響 UX)
 ### P2(建議改善)
 
-## 提議討論(待 user sign-off)
-- {若發現 DS canonical 本身有問題,列於此,不自改}
+## Authority classification
+- P2E:{工程／治理 finding，交 canonical owner 自主修復}
+- P2H:{只有真正產品／UI／UX SSOT 取捨才列 exact target-bound decision}
 ```
 
-**STOP 點**:report 寫完**不自動修**。分權對齊 CLAUDE.md `# 稽核 canonical`(內含「Audit-vs-execute 分權」inline rule)。
+本 skill 保持 read-only，report 是 evidence receipt；caller／canonical owner 對 P2E 直接接續
+修復與驗證，不把 read-only skill boundary 誤當 user checkpoint。只有 P2H 或
+shared-governance human-only boundary 才停止。
 
 ## Non-goals
 
@@ -124,7 +127,7 @@ description: UX behavior audit for design-system components and product UI. Chec
 
 ## 相關
 
-- `.claude/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D4 補位
-- `.claude/skills/visual-audit/SKILL.md` — pixel 層(D5)
-- `.claude/skills/performance-audit/SKILL.md` — 效能層(D3)
-- `.claude/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill
+- `packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D4 補位
+- `packages/design-system/ds-canonical/skills/visual-audit/SKILL.md` — pixel 層(D5)
+- `packages/design-system/ds-canonical/skills/performance-audit/SKILL.md` — 效能層(D3)
+- `packages/design-system/ds-canonical/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill