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

package/ds-canonical/rules/self-verify.md

@@ -1,6 +1,11 @@
+---
+paths:
+  - "**/*"
+---
+
 # Self-verify canonical(path-scoped)
 
-僅在編輯任何 file(`src/**` / `.claude/**` / `*.spec.md` / `*.tsx` / `*.css`)時 load。
+僅在編輯任何 file(`src/**` / canonical governance paths / `*.spec.md` / `*.tsx` / `*.css`)時 load。
 
 **Why**:M10/M11/M20/M32 散在 meta-patterns,缺單一「改檔前中後該驗什麼」canonical。本 rule SSOT。對齊 Linux kernel patch checklist / Toyota TPS 自働化 / Google CL pre-submit。
 
@@ -8,17 +13,17 @@
 
 | 階段 | 動作 | 工具 / cmd |
 |---|---|---|
-| **Pre-edit** | (1) M29 3-column owner table(grep `*.spec.md` 找 anchor)(2) M23 既有 canonical 優先(`# SSOT 消費 canonical` 清單)(3) Touched file inventory + Read 真讀(非憑記憶)(4) 若 SSOT-UI/UX substantive → STOP 用中文 propose 等 user 拍板 | grep / Read / propose-options skill |
-| **Mid-edit** | (1) 每 5-8 個檔案或跨新 domain 跑 scoped invariant grep(2) 發現 spec/code 衝突 STOP,不選邊(3) Hook 自動 intercept(check_substantive_edit_approval_preflight / check_solo_workflow / check_story_invariants 等)| auto-fire hooks |
-| **Post-edit** | (1) `npx tsc -b`(任何 tsx/ts 改)(2) 相關 invariant script(`node scripts/data-table-invariants.mjs` 若動 DataTable / `node scripts/audit-content-quality.mjs --check` 若動 spec)(3) M10 proactive scan(`/scan-similar-bugs` 或 manual grep 同 pattern DS-wide)(4) UI 改動加 visual probe(`/visual-audit --scope=changed` 或 Playwright screenshot)(5) M14 5-layer pipeline(spec / hook / SKILL / CLAUDE.md / memory 該動的同步)| `tsc` / `*.mjs` 腳本 / visual-audit |
-| **Pre-commit / Pre-final** | (1) Claim-verify table:每「已修」「已驗」對應具體 command + artifact + file:line(2) 過 `scripts/audit-content-quality.mjs --check`(3) Stop hook BLOCKER 紅燈通過(claim-verify-gap / codex-verify / codex-transport)(4) Commit message 含 cite + verdict keyword 滿足 `check_codex_collab_5step.sh` | claim-verify table + content-quality + stop hook |
+| **Pre-edit** | (1) M29 3-column owner table(grep `*.spec.md` 找 anchor)(2) M23 既有 canonical 優先(`# SSOT 消費 canonical` 清單)(3) Touched file inventory + Read 真讀(非憑記憶)(4) 以 target-bound authority classifier 區分：純工程 AUTO；只有產品／UI／UX SSOT 真取捨才 STOP、用中文提出 exact decision | grep / Read / propose-options skill |
+| **Mid-edit** | (1) 每 5-8 個檔案或跨新 domain 跑 scoped invariant grep(2) 發現 spec/code 衝突先以 owner/evidence/tests 收斂；task／deliverable 明確要求時才加 independent review。唯一工程解 AUTO，產品／UI／UX真取捨才 STOP，unknown fail closed(3) Hook 自動 intercept(check_substantive_edit_approval_preflight / check_solo_workflow / check_story_invariants 等)| auto-fire hooks |
+| **Post-edit** | (1) `npx tsc -b`(任何 tsx/ts 改);**⚠️ 動 export/型別 surface(interface/type/cva variant union/discriminated union/新 export)必加跑 `npm run build:lib`** —— `tsc -b`(composite/build mode)**不做 declaration emit**,漏 TS4023「cannot be named」等 declaration-emit 錯;Netlify build.command = `build:lib && build-storybook`(`build:lib` 含 `build:dts` = `tsc -p` emit .d.ts)才會炸。**tsc -b PASS ≠ deploy-safe**(2026-06-05 anchor:Badge discriminated union BadgeDotProps 沒 export → Sidebar SidebarMenuBadge .d.ts TS4023 → Netlify build 連掛 3 commit,tsc -b 全綠騙過)。type-surface deploy-safety 證明 = `build:lib` exit 0,非 tsc -b。(2) 相關 invariant script(`node scripts/data-table-invariants.mjs` 若動 DataTable / `node scripts/audit-content-quality.mjs --check` 若動 spec)(3) M10 proactive scan(`/scan-similar-bugs` 或 manual grep 同 pattern DS-wide)(4) UI 改動加 visual probe(`/visual-audit --scope=changed` 或 Playwright screenshot)(5) M14 5-layer pipeline(spec / hook / SKILL / AGENTS.md / memory 該動的同步)| `tsc` / `*.mjs` 腳本 / visual-audit |
+| **Pre-commit / Pre-final** | (0) **結論相容性掃描(M10 sub-rule,兩維度缺一不可)**:除了逐句驗證據,必須另跑一遍——把本文件／本次改動的**所有結論列成清單**,逐對問「這兩條能同時為真嗎」;並確認**每條已成立的結論都登記進總帳／決策表**。只驗單句 = 假檢查(矛盾在單句層級恆為隱形)(1) Claim-verify table:每「已修」「已驗」對應具體 command + artifact + file:line(2) 過 `scripts/audit-content-quality.mjs --check`(3) Stop hook BLOCKER 紅燈通過(claim-verify-gap / codex-verify / codex-transport)(4) Commit message 含 cite + verdict keyword 滿足 `check_codex_collab_5step.sh` | claim-verify table + content-quality + stop hook |
 
 ## 強制 trigger condition(滿足任一 → 整 4 階段必跑)
 
 - 動 `packages/design-system/src/**`(production code)
 - 動 `*.spec.md`(canonical text)
-- 動 `.claude/{rules,skills,hooks,memory,commands}/**`(governance)
-- 動 `CLAUDE.md`
+- 動 `packages/design-system/ds-canonical/{rules,skills,hooks,references,commands}/**` 或 `governance/memory/**`(governance canonical owner；generated provider views 禁手改)
+- 動 `AGENTS.md`
 - 動 token(`packages/design-system/src/tokens/**`)
 - 動 component primitive consumer 行為
 
@@ -31,23 +36,28 @@
 
 ## Mechanical enforcement
 
-- **Pre-edit**:`check_substantive_edit_approval_preflight.sh`(production code)+ `stop_self_audit.sh`(spec/canonical 補位)+ `check_ds_anchor_preflight.sh`(M29 anchor)
+- **Pre-edit**:`check_substantive_edit_approval_preflight.sh`(production code)+ `stop_self_audit.sh`(spec/canonical 補位 — 僅覆蓋 codex-collab turn(Mechanism 4 嵌在 codex-reply 閘內);非 codex turn 的 spec.md edit 靠 discipline)+ `check_ds_anchor_preflight.sh`(M29 anchor)
 - **Post-edit**:`stop_self_audit.sh` Mechanism 1(claim-verify-gap)BLOCKER
-- **Pre-commit**:`scripts/audit-content-quality.mjs --check` + `scripts/extract-canonical-rules.mjs` 各 fail = block
+- **Pre-final(宣告完成前)**:`stop_self_audit.sh` Mechanism 7(完整性宣告閘)BLOCKER — 宣告「全做完 / 全部完成」+ 本 turn 實質改動但**無全庫 stale-ref 掃描證據** → block。**觸發器 = 「宣告完成」本身,非等 user 問第二次**(2026-06-03 user-authorized,根治重複 failure)
+- **Optional adversarial review**:中型以上改動可用 multi-agent review 增加 assurance，但只有 task／deliverable 明確要求時才是 completion condition；user waiver 必記錄且不得冒充已做。一般工程以 M7 自掃、targeted tests、required CI 與 live readback收斂，optional reviewer 缺席不阻擋。
+- **Pre-commit / release gate**:`scripts/audit-content-quality.mjs --check` 由 current required CI / deterministic audit chain fail closed；Stop hook 每 turn跑相關檢查僅報告時不得冒充 CI。Standard release唯一圖 = `infra/governance/release-workflow.json`，retired `release:preflight` 不得回流。
 
 ## Anti-pattern(永久 ban)
 
 - ❌「我感覺修好了」沒跑 tsc / invariant 就 claim done
+- ❌ 動 export/型別 surface 只跑 `tsc -b` 就宣告 deploy-safe(必 `npm run build:lib`,詳上方 Post-edit row — 單一住所)
 - ❌ 動 spec / src 沒先 grep owner anchor(M29 違反)
 - ❌ 改 hook 沒跑 syntax check + smoke test
 - ❌「下個 session 補」defer 可做的 verify(M33 違反)
 - ❌ pass-through Explore / codex propose 沒 own-version 比稿
-
-## 對齊歷史
+- ❌ 宣告「全做完 / 全部完成」前沒自己跑 M10「改一處看三處」全庫 stale-ref 掃描 → 等 user 問「真的做完?」才補掃出 loose end(M7 BLOCKER;anchor:CF model 改完漏 3 ref / iceberg)
+- ❌ **宣告「已全盤稽核 / 邏輯都對過」但只驗了單句層級**(cite / 數字 / 引文),沒跑結論兩兩相容性掃描 → 假檢查。anchor:2026-08-09 agent UI 規格連跑數次「全盤稽核」全漏,user 抓「你在檢查的時候難道都沒有發現他們邏輯不通嗎」
+- (溝通紀律——**問句必正面回答**、**禁自己虛構矛盾再自己否掉**——owner 在 `governance/memory/feedback_propose_discipline.md` Sub-rule 3,本檔不複述)
+- ❌ **重大 / SSOT / 模型改動只靠自 grep 就宣告完成** → 漏 fragility / 沒貫徹到 consumer。必跑 target-specific deterministic tests、required CI 與 applicable live readback；若 task／deliverable 明確要求 independent review 才把 reviewer receipt 列為 required，waived run 不得冒充已做
 
 - Linux kernel:`scripts/checkpatch.pl` pre-submit + `git log --oneline | head -3` 後 sign-off
 - Toyota TPS:Jidoka(自働化)— 機器發現異常自己停,人別繼續(對應 hook BLOCKER)
 - Google CL:LGTM + 必跑 presubmit(對應 Pre-commit table)
 - Atlassian RFC:cite + counter-example scan 必過 reviewer round
 
-對應 CLAUDE.md `# 自主執行 canonical` + meta-patterns M10/M11/M20/M32。
+對應 AGENTS.md `# 自主執行 canonical` + meta-patterns M10/M11/M20/M32。

package/ds-canonical/rules/spec-rules.md

@@ -15,11 +15,11 @@ paths:
 - 編輯 spec 或建新元件時必對照 **Polaris / Material / Ant / Atlassian / Carbon / Apple HIG** 的 7 維度:何時用 / 何時不用 / 近親分界 / 常見誤解 / 相關 links / 空值 / 驗證 / Loading / a11y 預設。SegmentedControl spec 是本專案 template
 - 編輯 spec 必交叉比對相關 spec + Storybook,確認無矛盾 / 術語一致 / 無重複
 - 與既有 spec 有邏輯衝突 / 概念混淆 → 主動提出討論,不默默改 / 不迴避
-- 所有元件遵循 shadcn 框架(forwardRef / Slot / data-* / cva),不從零重寫
+- 所有元件遵循 shadcn 框架(forwardRef / Slot / data-* / cva),不從零重寫——**「框架」= 結構 idiom,非「必須消費 shadcn 目錄每個元件」;目錄後續新增 vs DS 既有等價物 → 見 ui-development.md「shadcn 目錄後續新增元件 vs DS 既有」**(2026-07-07 clarifier,防「FileItem 是 Attachment 的從零重寫」類誤讀)
 - 每個元件 spec「定位」段必明確宣告實作基礎:`基於 Radix X` / `基於 cmdk / sonner` / native / `自建 + 理由`(自建必說明為何不用現有 primitive)
 - Spec 文字品質:不描述視覺形狀 / 實作細節(「窄長形」「會變寬」「zero layout shift」屬 story 不進 spec);術語一致;「禁止事項(❌)」列所有常見誤用
 - **a11y 段強制**:互動元件 spec.md 必含 `## A11y 預設` 段(列 ARIA + Keyboard map);純視覺 indicator(Badge / Tag / Separator / Skeleton)豁免明文寫「本元件無互動」
 
 ## SSOT + 邊界案例覆蓋 + 職責分離
 
-詳 `.claude/references/spec-rules.md` — SSOT 深度判斷 / reciprocal 規則 / 目前 6 個 SSOT anchors / 邊界案例 scope 預設(Field 家族 / dark mode / density / 純 wrapper)/ spec 與 tsx 職責分離 / calc() 公式表達。
+詳 `packages/design-system/ds-canonical/references/spec-rules.md` — SSOT 深度判斷 / reciprocal 規則 / 目前 6 個 SSOT anchors / 邊界案例 scope 預設(Field 家族 / dark mode / density / 純 wrapper)/ spec 與 tsx 職責分離 / calc() 公式表達。

package/ds-canonical/rules/story-rules.md

@@ -12,27 +12,52 @@ paths:
 
 | 層 | 檔案 | Canonical | Hook | Audit Dim |
 |---|------|-----------|------|-----------|
-| 1 展示 | `*.stories.tsx` | trait-based v2 | `check_story_category.sh` | 29 |
-| 2 設計規格 | `*.anatomy.stories.tsx` | 6-canonical(Overview / Inspector / ColorMatrix / SizeMatrix / StateBehavior / Accessibility)| `check_story_anatomy.sh` | 13 |
-| 3 設計原則 | `*.principles.stories.tsx` | Polaris-aligned ≥ 2 of {WhenToUse / WhenNotToUse / Vs*Rule / ContentGuidelines};v3 預設整合 `UsageGuidance` 單一 export(Polaris/Material/Ant 共識) | `check_principles_canonical.sh` | 30 |
+| 1 展示 | `*.stories.tsx` | trait-based v2 | `check_story_invariants.sh` R3 category | 29 |
+| 2 設計規格 | `*.anatomy.stories.tsx` | 6-canonical(Overview / Inspector / ColorMatrix / SizeMatrix / StateBehavior / Accessibility)| —(6-canonical 由 Dim 13 batch verify + `compile-stories.mjs --check` 兜底;`check_story_invariants.sh` R1 = 展示層 hand-craft 偵測,2026-06-11 起豁免 anatomy 檔)| 13 |
+| 3 設計原則 | `*.principles.stories.tsx` | ONE complete `UsageGuidance` sufficient；split style 才需 ≥ 2 個 distinct decision dimensions；額外 story 必須 earn existence | `check_canonical_propagation.sh` E.1 principles | 30 |
 
 ## Title 命名
 
-`Design System/{Tokens|Patterns|Components|Internal}/{Name}/{展示|設計規格|設計原則}`。
+**2 namespace canonical**(2026-05-28 codify per template create-app duplicate-id bug anchor):
 
-第一層英 / PascalCase / 子頁中文 / 子頁前不加元件名(❌ `MenuItem 展示` → ✅ `展示`)。
+| Repo / Path | Title pattern | 用途 |
+|---|---|---|
+| **DS repo** `packages/design-system/**/*.stories.tsx` | `Design System/{Tokens|Patterns|Components|Internal|Internal Patterns}/{Name}/{展示|設計規格|設計原則}` | DS 元件 / token / pattern building block |
+| **Consumer apps**(template / fork repos)`apps/**/*.stories.tsx` | `Apps/{app-kebab-name}/{Page Purpose}` | 產品 UI composition demo(eg. `Apps/order-dashboard/AppShell Dashboard`)|
+
+**Why 不統一**:DS 是 building block library(可重用元件),consumer apps 是 product UI 真實 composition demo(整頁、整 flow)。Namespace 不同 = Storybook sidebar 兩塊清楚分區。
+
+**Universal rule**:第一層英 / PascalCase 或 kebab-name / 子頁中文 / 子頁前不加元件名(❌ `MenuItem 展示` → ✅ `展示`)。
+
+**Template create-app 機械強制**(2026-05-28 ship):`scripts/create-app.mjs:patchStoryTitles()` 遞迴改 copied apps 內所有 `*.stories.{tsx,ts,mdx}` 的 `title: 'Apps/template/...'` → `Apps/<new-name>/...`,**防 Storybook duplicate id**(e2e verify-flow-test anchor 抓到 4 collisions)。
 
 **Internal vs Components 三 test**:(1) 有預設視覺?(2) 直接 `<X>` 有視覺?(3) 所有消費者都包 wrapper?三題傾向 Internal → `Internal/`。**例外:compound-component public API**(`Dialog.Root/Trigger/Content` / `Field + FieldLabel + FieldError + FieldDescription` 等定義 sub-component 給 consumer 拼的 documented composition pattern)豁免三-test — 它**定義** sub-components,不是被 wrap 的零件。對齊 Radix Dialog / MUI FormControl + InputLabel + FormHelperText / Mantine Input.Wrapper compound idiom。
 
 **Title canonical 4-part exemption**(2026-05-16 codified):**Tokens / Patterns** 為 single-file showcase(無 anatomy/principles 對應)→ 3-part title 是 intentional convention(`Design System/Tokens/{Name}` / `Design System/Patterns/{Name}`),不是違反。**Components / Internal** 必 4-part(`/{Name}/{展示|設計規格|設計原則}`)因有 3 stories 對應 file 需 subpage 分流。
 
+**Patterns `{Name}` 必 spaced Title Case**(2026-06-12 codify,命名 3 重 test 全過):多字 pattern title 用人話 spaced(`Action Bar` / `Item Anatomy` / `Resize Handle`),非 PascalCase — title 是 reader-facing label,與 code identifier(`ResizeHandle`)雙軌分工;對齊 Atlassian「Avatar group」/ Polaris「Empty state」/ Carbon「Date picker」catalog spaced idiom。Tokens 第三層維持與 token 資料夾同名構詞(`LayoutSpace` ← `layoutSpace/`),不在此 rule scope。
+
 **MenuItem-as-listbox-child 鍵盤 delegation 例外**(2026-05-16 codified per Combobox spec.md L130-142):MenuItem `<div role="option">` 不需自帶 Enter/Space handler — 由 parent listbox(Combobox / SelectMenu / DropdownMenu)的 hidden native `<select>` handle 鍵盤導覽(對齊 Material/Atlassian/GitHub mixed-control「單 native tab stop + 多 mouse click surface」 canonical)。MenuItem 為 building block 不該重複 handler。
 
-**Story `name:` field 必中文人話**(no auto-compile 豁免):`compile-stories.mjs` auto-generate 已產生中文 name(如 `'元件總覽'`)。Manually-written stories `name:` 用純英文 implementation label(`'Default'` / `'Pressed'` / `'SizeMatrix'`)= drift,**必 humanize 中文**。Export const 維持 PascalCase(英)為 code identifier,**`name:` field 為 reader-facing 必中文**(術語例外:`FAQ` / 元件名 `Avatar/Tooltip` 等專有可保英)。
+**Story `name:` field 必中文人話**(no auto-compile 豁免):anatomy 6-story canonical 的中文 name(如 `'元件總覽'`)為 checked-in convention(`check_story_invariants.sh` R4 title_canonical / R5 name_jargon 看守);`compile-stories.mjs` 僅做 spec/tsx componentMeta key drift `--check`(stdout POC markdown),**不**產生 stories 或 name 欄。Manually-written stories `name:` 用純英文 implementation label(`'Default'` / `'Pressed'` / `'SizeMatrix'`)= drift,**必 humanize 中文**。Export const 維持 PascalCase(英)為 code identifier,**`name:` field 為 reader-facing 必中文**(術語例外:`FAQ` / 元件名 `Avatar/Tooltip` 等專有可保英)。
+
+**Autodocs component 導讀必寫**:reader-facing、非 anatomy 的 meta 只要標
+`tags: ['autodocs']`，就必在 `parameters.docs.description.component` 用 1–3 句人話回答
+「這個單元解決什麼」與「何時用／何時改用近親」。不可只重複 component 名、props 或內部代號，
+也不可用 TODO/WIP stub。機械 gate=`scripts/audit-content-quality.mjs --check`；語意是否真的提供
+用途與選擇判準仍由 Deep Audit Storybook content judgment 全量判讀。
+
+**Technical probe visibility**:只服務 hover/focus/open snapshot、效能量測、import smoke 等
+automation 的 story，在該 story 本身標 `tags: ['test-only']`。Shared Storybook runtime 會把它從
+sidebar 與 Autodocs 教學內容排除，但仍保留在 story index、direct URL、a11y/interaction runner。
+禁止用 `!autodocs` 代替，也禁止再加 `!dev` / `!test` 把 probe 從 index 或測試面移除；真正
+reader-facing 的 scenario 不得標 `test-only`。機械 gate=`scripts/audit-content-quality.mjs --check`，
+回歸 inventory=`scripts/test-storybook-test-only-semantics.mjs`。
 
 ## 範例最高準則
 
-精簡幹練、0 重複、每 story earn its existence(audit Dim 24/25/28/29/30 抓)。
+精簡幹練、0 重複、每 story earn its existence；Autodocs 先有用途/選擇導讀，再讓各 story
+各教一件新事(audit Dim 24/25/28/29/30/43 抓)。
 
 **Earn-existence 2 test**:(a) 教別 story 沒教的原則?(b) 移除後 spec 理解 degrade?兩題皆 NO → retire。
 
@@ -47,9 +72,11 @@ paths:
 - 同 affordance 內 prop variations 用 Controls 不另開(❌ `WithStartIcon`+`WithEndIcon` → ✓ `WithIcon` grid)
 - Compound 有 new constraint 才分
 
-**展示 v2 trait-based**:spec.md frontmatter `traits:` array → required core stories 衍生 + hook `check_story_category.sh` 攔。
+**展示 v2 trait-based**:spec.md frontmatter `traits:` array → required core stories 衍生 + hook `check_story_invariants.sh` R3 category 攔。
+
+**Showcase representative canonical**:每檔至少一個 reader-facing 代表範例；不強迫 exact `Default` export。`Default` 只有在 minimal baseline 本身通過 earn-existence 時才開。
 
-**Principles canonical**(Polaris-aligned):universal core ≥ 2 of `WhenToUse`/`WhenNotToUse`/`Vs*Rule`/`ContentGuidelines` + hook 攔。SSOT → `/story-writing` skill `references/category-templates.md`。
+**Principles canonical**(Polaris-aligned):ONE complete `UsageGuidance` sufficient；split style 才需 ≥ 2 個 distinct decision dimensions。額外 story 只有教不同主題且通過 earn-existence 才保留。SSOT → `/story-writing` skill `references/category-templates.md`。
 
 ## 禁止
 

package/ds-canonical/rules/ui-development.md

@@ -11,21 +11,27 @@ paths:
 
 僅在編 `.tsx` / `.ts` 或 DS / explorations / app code 時 load。
 
-## Public component vs Internal primitive canonical(SSOT,2026-05-23 user 永久拍板)
+## Public component vs Internal primitive canonical(SSOT,2026-05-23 user 拍板;**2026-06-06 refine 為 intent-based,retire 舊「空 render 測試」**)
 
-**Public component**(consumer-facing):**end-user app 直接寫 `<X />` 就能 render 出有意義的 UI**,不需要再 wrap / 不需要再 compose 其他 DS 元件。Examples:`<Button>` / `<Avatar>` / `<Dialog>` / `<DataTable>` / `<MenuItem>` / `<ActionBar>` / `<ResizeHandle>`。
+**唯一判準 = 「DS 是否想讓 consumer 直接 import 來用它」(public-API intent)** —— **不是**「空 `<X/>` 能不能 render 出有意義 UI」。世界級實證:MUI Base 官方「**requiring composition and styling does NOT make something internal — these are explicitly public primitives**」;Atlassian Primitives(Box/Stack/Inline)/ Bootstrap input-group / Ant Space.Compact 皆 public 卻需 compose。
 
-**Internal primitive**:**供 DS 內部其他元件 wrap / compose 用**。end-user app 直接 render 無 functioning UI,或必須先 import 多個 DS 元件一起組才有結果。Examples:`<ChromeHeader>`(Sidebar 內部消費)/ `<SurfaceHeader/Body/Footer>`(Dialog 內部)/ `useOverflowItems` hook / `<ItemIcon>` / `<ItemAvatar>`(MenuItem 內部 slot)。
+**Public**(consumer-facing):DS 想讓 consumer 直接用的東西,**包含**:(a) 成品元件 `<Button>` / `<Avatar>` / `<Dialog>` / `<DataTable>` / `<Select>`;(b) **組合 primitive —— consumer 把自己內容塞進去 / 自接 callback 才完整**:`<FieldControlGroup>`(塞 field controls = Bootstrap input-group idiom)/ `<ResizeHandle>`(接 drag math = VS Code/Figma resize idiom)/ `<ChromeHeader>`(自建 chrome header chrome,follow `header-canonical` anatomy = 對標 item-anatomy 的公開 anatomy primitive)/ `<ItemIcon>` `<ItemAvatar>`(row context 內 consumer 塞 icon/avatar 的公開 named slot —— item-anatomy.spec.md「Helper 程式化封裝」段 mandate consumer 必用 + root barrel 匯出;對齊 Material ListItemIcon/ListItemAvatar、Primer ActionList.LeadingVisual 公開 named-slot 模型;**row-context-scoped**:離開 row primitive 子樹無意義,如 Material ListItemIcon 離開 List 無意義)。**「需要 children / 接線 / 組合」是正常 public 用法,不是 internal**。判斷訊號:benchmark 對標 consumer-facing primitive / spec「何時用」是 consumer 場景 / 有 standalone 用法 / export 給 consumer。
 
-**Mechanical test(verifiable)**:
-- 問:end-user app `<X />`(空 children / 無 props / 無 wrapper context)render → 有 functioning visible UI 嗎?
-  - YES → **public**
-  - NO → **internal**
+**Internal primitive**:**主要給 DS 內部其他元件用;不進 root barrel front-door、consumer 不「直接裸用」——但 internal ≠ 禁用:consumer 可經 per-component subpath(`@qijenchen/design-system/{components,patterns}/<Dir>`)「另外包裝過 + 自行確認」後消費**(見下方「Root barrel front-door 排除」2026-06-05 user Q2 拍板 SSOT = 權威定義,取代舊「永遠不碰」絕對措辭 —— 2026-07-10 修此 spec-internal 矛盾,該矛盾曾誤導判定 `<MenuItem>`「consumer 不可用」)。Examples:`<SurfaceHeader/Body/Footer>`(只 Dialog 內部)/ `useOverflowItems` hook / `<RowSizeProvider>` `<ItemInlineAction(Button)>`(item-anatomy.tsx `@internal` 標記的 L3 row-size / inline-action primitive,經 MenuItem/Row 消費)。⚠️ `<ItemIcon>` / `<ItemAvatar>` **不是** internal —— 是 public 組合 primitive(見上方 (b);2026-07-14 修 stale drift:spec mandate + root barrel 匯出 + app template 實用四處一致 public,本行舊列法與其全牴觸)。判斷訊號:無 standalone consumer 直用場景 / 主要被其他 DS 元件 import / 是別元件的 sub-part/slot/chrome。**`isInternal` = 需 subpath + 包裝後才用(如 `<MenuItem>` 之於 nav row),非「禁止 consumer 使用」。**
+
+**決策(verifiable)**:
+- 問:DS 想讓 end-user 在自己 app 直接 import 並用它嗎(看 benchmark / 何時用 / 是否 export 給 consumer)?
+  - YES(**即使需要 compose/wire**)→ **public**
+  - 只有 DS 內部元件用、consumer 用 wrapper 不碰它 → **internal**
+- ⚠️ **禁用舊「空 render 測試」當判準**(2026-06-06 retire):它把 composition primitive(`<FieldControlGroup>` 空 = 透明 div)誤判 internal。anchor:2026-06-06 我用機械測試(空 render / 0-current-usage / 需接線)連環誤判 FieldControlGroup·ResizeHandle 為 internal,user 抓「它明明是 Bootstrap input-group / VS Code resize 那種 consumer 直接用的 primitive」。**「現在 DS 自家沒用到」≠ internal**。
+- **note(pattern guidance / anatomy 參照)**:`action-bar`(組合指南,**無 component**)、`item-anatomy`(anatomy 參照 doc)不是「元件」,不走本判準 —— 它們是**可見的設計參照 Pattern**(per `patterns/README.md` charter)。
 
 **Folder + storybook canonical**:
 - public:`components/<Name>/` OR `patterns/<name>/`(frontmatter 無 `internal: true`),storybook title `Design System/Components/<Name>/...` OR `Design System/Patterns/<Name>`
-- internal:`components/Internal/<Name>/` OR `patterns/<name>/`(frontmatter `internal: true`),storybook title `Design System/Internal/<Name>/...` OR `Design System/Internal Patterns/<Name>`(end-user 設計師 default 過濾掉,DS contributor 看 reference 用)
+- internal:in-place `components/<Name>/` 或 `patterns/<name>/` + frontmatter `internal: true` / `- isInternal`(主路徑;現行 10 個 internal 單元全走 frontmatter,`components/Internal/<Name>/` folder 路線同樣支援但目前無住戶),storybook title `Design System/Internal/<Name>/...` OR `Design System/Internal Patterns/<Name>`(end-user 設計師 default 過濾掉,DS contributor 看 reference 用)
 - export jsDoc 加 `@internal` marker(IDE intellisense 警示 end-user)
+- **Root barrel front-door 排除(2026-06-05 dim-72 SSOT,user Q2 拍板)**:internal 元件/pattern **不進** `packages/design-system/src/index.ts`(root barrel = 直接 front-door),**只**經 per-component subpath `@qijenchen/design-system/{components,patterns}/<Dir>` 取用 —— 對應 user 原則「internal 要**另外包裝過 + 自行確認**才可用,不得直接 front-door 使用;public 才可直接用」。SSOT = spec frontmatter isInternal;機械 = `gen-design-system-barrel.mjs`(生成時自動排除)+ `--check`(current required CI / deterministic audit gate)。改 public/internal → 改 frontmatter 後重跑 generator。
+  - **符號級 `@internal` 排除(2026-07-18 決策3)**:public 元件內個別 export 若帶 `/** @internal */` JSDoc tag(如 `ButtonGroupContext` / `floatingLayerClass` / `RowSizeProvider` / `ItemInlineAction(Button)` 等私有 context/helper/primitive),generator 亦排除出 root front-door(subpath `export *` 仍有,DS 內部 relative import 不受影響)。對齊 TS `stripInternal` / MUI `@ignore` / API-Extractor `@internal` release tag。**偵測鐵律**:`@internal` 必為 JSDoc(`/** */`)tag(行首),`//` line-comment prose 提及不算(否則自身 doc 提及兄弟 `@internal` 的 public 型別如 `FieldVariant` 會被誤殺)。加/移私有符號的 front-door 排除 → 改該 export 的 `@internal` marker 後重跑 generator。
 
 **對齊世界級**:Polaris 「Building blocks」(public) vs「layout primitives」(internal)/ Material UI `@mui/material`(public)vs `@mui/utils` `@mui/system`(internal hooks/primitives)/ Atlassian `@atlaskit/<component>`(public)vs internal `<unstyled>` primitives / Carbon turnkey components + internal utilities / Apple HIG「Presented controls」vs「implementation primitives」 共識。
 
@@ -33,13 +39,13 @@ paths:
 
 **先 `ls packages/design-system/src/{components,patterns}/`**。必查 spec:Tokens(`tokens/{color|typography|density|uiSize|layoutSpace|elevation|radius}/*.spec.md`)/ Row + List item(`item-anatomy.spec.md` Family 1+2 SSOT)/ Action bar / Overflow / Overlay(`patterns/{action-bar,horizontal-overflow,overlay-surface}/*.spec.md`)/ Field(`components/Field/*.spec.md`)。
 
-**既有 primitive 優先消費**:命中既有 → 必消費不 hand-craft。**自我檢查**:icon+text 垂直 → `<Empty>`;橫向 row → `<MenuItem>` + slot;浮層 → `overlay-surface`;跨 OS 捲軸 → `<ScrollArea>`;鎖長寬比 → `<AspectRatio>`。完整對照 → `.claude/references/build-ui-canonicals.md`。
+**既有 primitive 優先消費**:命中既有 → 必消費不 hand-craft。**自我檢查**:icon+text 垂直 → `<Empty>`;橫向 row → `<MenuItem>` + slot(消費 item-anatomy);chrome header(toolbar / page top bar / panel 標題列)→ `<ChromeHeader>`(消費 header-canonical,讀其 spec + `Patterns/Header Anatomy` story);浮層 → `overlay-surface`;跨 OS 捲軸 → `<ScrollArea>`;鎖長寬比 → `<AspectRatio>`。完整對照 → `packages/design-system/ds-canonical/references/build-ui-canonicals.md`。
 
 ## UI 開發 4 條核心
 
 必重用既有 `components/` / 必用 design tokens(禁硬寫色/字/間距/圓角)/ 建新 UI 前查 pattern / 用 `cn()`(`@/lib/utils`)合併 Tailwind class。
 
-深度規則 → `.claude/references/ui-dev-rules.md`(slot 幾何 / Padding source / Icon size 3 層)。
+深度規則 → `packages/design-system/ds-canonical/references/ui-dev-rules.md`(slot 幾何 / Padding source / Icon size 3 層)。
 
 **一句話 pointer**:
 - 新 row 元件 → `patterns/element-anatomy/item-anatomy.spec.md`「自我檢查」
@@ -48,11 +54,11 @@ paths:
 - 陰影:必 `--elevation-*`;禁 `shadow-sm/md/lg/xl/2xl`
 - 視覺容器 breathing:有邊界 → 必 inner padding
 
-## Tailwind 5 條核心(每條過真實 bug,詳 `.claude/references/tailwind-gotchas.md`)
+## Tailwind 5 條核心(每條過真實 bug,詳 `packages/design-system/ds-canonical/references/tailwind-gotchas.md`)
 
 1. **CSS variable 必 `var()` 包覆** — `w-[var(--foo)]` 而非 `w-[--foo]`(v4 silent 失效)
 2. **自訂 utility 必在 `lib/utils.ts` 註冊 group** — 否則 tailwind-merge 誤判 strip
-3. **禁 `shadow-sm/md/lg` / `text-xs/sm/base` / 硬寫色值** — 用 `shadow-[var(--elevation-*)]` / `text-body`
+3. **禁 `shadow-sm/md/lg` / `text-xs/sm/base` / 硬寫色值** — 用 `shadow-[var(--elevation-N)]` (N ∈ {100,200},+`-hover` 變體) / `text-body`
 4. **禁 shadcn compat alias**(`bg-popover` / `text-muted-foreground` / `bg-accent` 等)— 用 direct token
 5. **禁 primitive 色名作 utility**(`bg-neutral-3` / `text-blue-6`)— 用 semantic utility 或 `bg-[var(--color-blue-6)]`
 
@@ -69,12 +75,12 @@ paths:
 - slot 只接 icon → `startIcon` / `endIcon`(型別 `LucideIcon`,元件控尺寸)
 - slot 接任意視覺 → 描述內容類型(`avatar`,型別 `ReactNode`)
 - slot 是行為 → callback(`onDismiss`,元件渲染互動 + 樣式)
-- ❌ 禁 `prefix` / `suffix` / `left` / `right`(位置名不傳達本質)
+- ❌ 禁 `prefix` / `suffix` / `left` / `right` 當**內容插槽** prop(位置名不傳達本質)→ 用 `startIcon`/`endContent`。**例外**:值格式 affix 字串(`NumberInput.prefix='$'`)+ 結構 anatomy 詞彙合法,判準見 `packages/design-system/ds-canonical/references/props-naming.md`「prefix/suffix canonical」
 
-**4 名關閉 / 移除 callback**(詳 `.claude/references/props-naming.md`):
+**4 名關閉 / 移除 callback**(詳 `packages/design-system/ds-canonical/references/props-naming.md`):
 `onClose` / `onDismiss` / `onRemove` / `onClear` 各有語意不合併。
 
-**Badge 命名按放置**:`badge`(inline)/ `overlayBadge`(疊視覺重心 iconOnly)/ `badgeCount`(Avatar count)/ `status`(Avatar presence dot)。
+**Badge 命名按放置**:`badge`(inline)/ `overlayBadge`(疊視覺重心 iconOnly)/ `badgeCount`(Avatar count)/ `status`(presence dot — Avatar / ProfileCard / PeoplePicker;另有 lifecycle value-set 用於 FileItem / FileUpload / ProgressBar,詳 `props-naming.md`)。
 
 **Icon canonical**:Overflow `MoreVertical` / Breadcrumb ellipsis `MoreHorizontal` / Close `X` / 成功 `Check` / 警告 `TriangleAlert` / 資訊 `Info`。
 
@@ -85,3 +91,5 @@ paths:
 **cva 適用**:className-only 差異 → cva;style 物件 → object map + `style={{}}`;不同 JSX 樹 → conditional rendering。
 
 **元件不得自包全域 Provider**(Tooltip / Theme / Toast / Portal)— 由應用層統一設定。**判斷**:Context 是行為狀態(open / size)→ 可包;全域外觀配置(delay / theme / portal / variant defaults)→ 禁止。
+
+**shadcn 目錄後續新增元件 vs DS 既有(2026-07-07 codify,anchor:Attachment vs FileItem)**:「遵循 shadcn 框架」= 結構 idiom(forwardRef / Slot / data-* / cva),**非**「必須消費目錄每個元件」。shadcn 是 copy-in scaffold 非 runtime 依賴——遷移無上游更新流入。目錄新增元件時二分:(a) 帶 primitive / behavior 增益(Radix core、新 interaction model)且 DS 無等價 → 走 `/new-component` 近親評估;(b) **純組合式且 DS 已有 Family-compliant 等價物 → 不換架構、不改名**(M23 禁外部覆蓋既有 canonical),只做 API 對照:值得的 state / pattern 逐項評估為 DS prop 演進(SSOT-affecting → ASK),該元件 spec 補 M22 benchmark 對照行 + known-gap 記錄。同類先例:Empty / Item(≈item-anatomy)/ Field / Spinner(≈CircularProgress)/ InputGroup(≈FieldControlGroup)。

package/ds-canonical/skills/README.md

@@ -1,20 +1,22 @@
-# .claude/skills/ Charter
+# Provider-neutral Agent Skills charter
 
-## 這裡只收:多步驟 workflow + user 決策點
+**Canonical owner:** `packages/design-system/ds-canonical/skills/**`. Runtime skill directories are deterministic provider views. Shared workflow meaning belongs here; provider identity, peer transport, discovery paths, and role bindings belong only to the provider registry.
+
+## 這裡只收:可重複、可延遲載入的 Agent Skills workflow
 
 每個 skill 一個 folder,內含:
 - `SKILL.md` — frontmatter(`name` / `description`) + 完整 workflow body
 - `references/` — 深度細節檔(AI 在跑 workflow 時按需讀)
 
-**核心特徵**:**只在 user invoke 時載入**(不佔每 session context);流程包含 checkpoint 讓 user 介入決策。
+**核心特徵**:只在相關或 user invoke 時載入(不佔每 session context)；採 Agent Skills 共用形式，並投影到所有已認證 provider surface。只有改變產品／UI／UX SSOT 且仍有真實選擇或取捨時才設 user checkpoint；純工程／治理決策依 shared governance 的 Engineering Decision Policy 與 Standing Authorization 自動收斂，純讀、deterministic 的 one-shot 檢查可無 checkpoint。
 
-## 當前居民(22 skills,2026-05-14 update)
+## 當前居民(25 skills,2026-07-22 update)
 
 **Audit / Quality(5)**:
 | Skill | Invoke 時機 | Scope |
 |-------|-----------|-------|
-| `design-system-audit/` | user 要求 audit DS 本身 | DS 內部 spec/cva/SSOT 33 維度(Phase 0 自建 baseline)|
-| `product-ui-audit/` | 「audit 這個 UI / 檢查 DS 用對嗎」| consumer UI 6 維檢核 |
+| `design-system-audit/` | user 要求 audit DS 本身 | DS 內部 spec/cva/SSOT full-dim(Phase 0 自建 baseline)|
+| `product-ui-audit/` | 「audit 這個 UI / 檢查 DS 用對嗎」| consumer UI 7 維檢核 |
 | `component-quality-gate/` | 元件 merge / ready / check | 45+ 項 checklist + Phase 4 Ship 6 項 |
 | `visual-audit/` | 視覺對齊 / 排版問題 / gap 錯 | pixel-level Layer A + B |
 | `code-quality-audit/` | 量化 clean code(any / dead export / file-size / long fn / circular dep / magic number)| chained by /design-system-audit Dim 27 |
@@ -32,33 +34,43 @@
 | `story-writing/` | 「寫 story / 補 anatomy / principles story」 | 6-story 結構 + 範例品質 |
 | `story-auto-compile-migrate/` | 「migrate 元件到 auto-compile」/ auto-chained by audit Dim 23 | 批次加 `componentMeta` export + spec YAML frontmatter(Phase 1+2 migration) |
 
-**Governance(6)**:
-| `knowledge-prune/` | 季度 / CLAUDE.md > 800 / MEMORY.md > 20 / audit 報 sprawl | 治理冗贅深度 prune |
+**Governance(8)**:
+| `knowledge-prune/` | 季度 / shared instructions 超過預算 / memory index 超過預算 / audit 報 sprawl | 治理冗贅深度 prune |
 | `governance-health/` | 月度 / auto-chain by audit | continuous metric monitor + auto-propose |
 | `propose-options/` | 給 option A/B/C 前必走 M18 4-Q gate | M8 benchmark / M17 SSOT / Rule-of-3 / M10 下游 |
 | `scan-similar-bugs/` | 修 bug 後 M10 mechanical exhaustive scan | DS-wide 同類 bug 全清 |
-| `codify-corrections/` | user 糾正後 codify 到正確 home(memory / CLAUDE.md / spec / hook) | 跨 home 路由 |
+| `codify-corrections/` | user 糾正後 codify 到正確 home(memory / shared instructions / spec / hook) | 跨 home 路由 |
 | `ensure-canonical/` | user 說「確保 X 一定要 / 永不漂移」trigger phrase(M19)| 自動規劃 5-layer defense-in-depth(canonical+hook+skill+audit+verify),至少 3 層落地 |
+| `canonical-reviewer/` | 治理檔案實質變更後 / 詢問 SSOT 位置 | 唯讀 7-Q SSOT/provider/downstream 審查；所有已認證 provider 共用同一 rubric |
+| `governance-status/` | 詢問 governance 狀態 / adapter drift / provider parity | 快速、deterministic、不修檔的健康檢查 |
+
+**Cross-provider collaboration(5)**:
+| `codex-collab/` | 需要獨立 provider 交叉審查 / 合作 | 跨 provider 合作流程 |
+| `deep-audit-cross-codex/` | 需要獨立 deep audit | 將審查與 author 分離 |
+| `independent-review/` | product consumer 的重大改動需要第二意見 | provider-adaptive、只讀、角色隔離；無 DS-author/release 權限 |
+| `codify-principle/` | 將重複原則收旂為 canonical | 判準化與下游吸收 |
+| `bug-fix-rhythm/` | bug fix 完成後 | 修正、同類掃描、驗證節奏 |
 
 ## 這裡**不收**(反例 + 正確去處)
 
 | 疑似要放這但其實不是 | 實際應去 | 為什麼 |
 |-------------------|---------|--------|
-| 單步驟 scaffold / one-shot action | `.claude/commands/` | skill 是多步驟 + checkpoints,命令是單步 |
-| 自動機械檢查(pre/post tool) | `.claude/hooks/` | skill 需 AI 走流程,hook 是 tool-level 自動 |
-| 每 session 都要的 signal rule | `CLAUDE.md` | skill 只在 invoke 時載入,會 miss signal |
+| 無需 AI 判斷的單次機械操作 | `scripts/` + package script | 可執行程式比 prompt workflow 可驗證 |
+| 自動機械檢查(pre/post tool) | canonical hooks | skill 需 AI 走流程,hook 是 tool-level 自動 |
+| 每 session 都要的 signal rule | shared governance instructions | skill 只在 invoke 時載入,會 miss signal |
 | 隨時間變化的狀態(audit progress) | `memory/` | skill 是不變的 workflow,state 屬 memory |
 | 元件 runtime primitive | `packages/design-system/src/patterns/` | skill 是 AI workflow,不是 UI code |
 
 ## 新 skill 的 criteria(必須全部通過)
 
-1. **多步驟 workflow**(不只是單一 check,有明確 phase)
-2. **有 user 決策 checkpoint**(AI 需要停下問 user)
+1. **可重複 workflow**(單步 deterministic check 或明確多階段流程)
+2. **權限路由明確**：產品／UI／UX SSOT 真取捨設 user checkpoint；純工程／治理決策不得設 user approval checkpoint
 3. **只在特定 invoke 情境需要**(不是每 session signal)
 4. **重複使用 ≥ 3 次**(一次性任務不建 skill)
 5. **invoke trigger 明確**(frontmatter description 裡清楚列出 user 說什麼會觸發)
+6. **provider-neutral core**；provider 專屬執行面只能是 thin adapter
 
-任一不過 → 改建 command / hook / spec / CLAUDE.md rule,不硬塞。
+任一不過 → 改建 script / hook / spec / shared-governance rule,不硬塞。
 
 ## SKILL.md 必須包含
 
@@ -77,7 +89,7 @@ description: 一句話說明 skill 做什麼 + 何時 invoke(user 說哪些話
 [必要條件]
 
 ## Workflow
-[Phase 1 / 2 / 3 + 每個 phase 的 checkpoint]
+[單步 deterministic 檢查，或 Phase 1 / 2 / 3；只有產品／UI／UX SSOT 真取捨列 user checkpoint，工程／治理依 Standing Authorization]
 
 ## References
 [指向 references/*.md 的深度細節]
@@ -85,4 +97,4 @@ description: 一句話說明 skill 做什麼 + 何時 invoke(user 說哪些話
 
 ## 建立前必 Read
 
-本 README + CLAUDE.md `# 治理 canonical` 的 Skill 章節 + 最接近的既有 skill 當範本。
+本 README + shared governance instructions 的治理章節 + 最接近的既有 skill 當範本。

package/ds-canonical/skills/bug-fix-rhythm/SKILL.md

@@ -8,9 +8,9 @@ description: Batch-end-verify rhythm + parallel tool batch + user-listed N-rule
 **目的**:當 session 有 ≥ 2 fixes(常見 visual bug session / user 列 N 條 numbered 規則),走 batch-end-verify rhythm,而非 per-fix verify cycle waste。**M32 split 後 (c)(d)(h1)(h2) 的 home**。
 
 **對齊**:
-- CLAUDE.md mindset #6「大原則吸收瑣碎」+ M14「對話結論 AUTO integrate」
+- AGENTS.md mindset #6「大原則吸收瑣碎」+ `packages/design-system/ds-canonical/rules/meta-patterns.md` M14「對話結論 AUTO integrate」
 - Bazel incremental-build / GitHub Actions matrix-batch idiom(per-step incremental = waste,batch-end = canonical)
-- Anthropic Claude Code prompt engineering「single-message multi-tool-call」canonical
+- provider-neutral parallel execution canonical
 - Toyota TPS jidoka(per-station per-item verify,不可 skip 任何 item)
 
 ## When to invoke
@@ -21,16 +21,17 @@ description: Batch-end-verify rhythm + parallel tool batch + user-listed N-rule
 
 **手動 invoke**:user 明言「批 fix」「一次做完」「跑完再驗」「列規則」
 
-**不 invoke**(對齊 Anthropic Best Practice 小修 skip):
+**不 invoke**(對齊 current provider best practice 小修 skip):
 - 單一 surgical fix(無 numbered rule + 無 cross-component)— per-fix verify 即可
 - pure refactor / typo / import cleanup
 - spec.md docs only
 
 ## Non-goals
 
-- 不擴展到「audit 7 維」(那是 `/design-system-audit`)
+- 不擴展到「audit full-dim」(那是 `/design-system-audit`)
 - 不取代 `/scan-similar-bugs`(那是 fix 後 root-pattern scan;本 skill 是 fix-過程 rhythm)
-- 不動 canonical 語意(走 audit-vs-execute STOP 提議)
+- 不在本 skill 自行擴張 canonical scope；若發現 canonical finding，依 shared authority
+  classifier 路由(P2E 自主修正，只有真產品／UI／UX SSOT 取捨才 P2H)
 
 ---
 
@@ -55,6 +56,12 @@ description: Batch-end-verify rhythm + parallel tool batch + user-listed N-rule
 - 漏 N 條中第 K 條當「做完」report
 - 改寫 user wording 為自己 paraphrase(verbatim 保留)
 
+**Sweep-first, edit-second(2026-07-07 治理進化軌道 2 codify)**:任一 fix 屬「跨切面決策」
+(改名 / 詞彙統一 / 規則性改動,可寫成 grep 謂詞者)→ **先跑謂詞產出「sweep manifest」**
+(grep 指令 + 全庫命中清單,artifact 化),照清單做完、驗證清單歸零,才算該 fix 完成。
+**禁**「先改直覺想到的檔、稽核抓漏再補」(anchor:2026-07-07 meta 詞彙統一三波 11→16→9 檔,
+規則在散文裡 → 三輪才收斂;寫成謂詞後一個 grep 掃平)。
+
 ### Phase 1 — Parallel tool batch(原 M32(d))
 
 Read / Grep / Glob 多檔需求 → **single message multi-tool-call**:
@@ -66,7 +73,7 @@ Read / Grep / Glob 多檔需求 → **single message multi-tool-call**:
 
 **Heuristic**:任何 tool call 之間**無 dependency**(後一個不需前一個結果) → 必 parallel。
 
-對齊 Anthropic Claude Code best practice:「Maximize use of parallel tool calls where possible」。
+對齊 provider-neutral best practice:「在依賴關係允許時並行執行」。
 
 ### Phase 2 — Batch fix(原 M32(c))
 
@@ -83,10 +90,16 @@ Read / Grep / Glob 多檔需求 → **single message multi-tool-call**:
 
 每 fix 落地前 inline 判斷:
 
-- **Surgical**(CLAUDE.md「Scope classifier — Surgical visual bug」):pixel / token / class adjustment, no new SSOT / API / cross-component → AUTO ship 此 fix
-- **Substantive**(audit-vs-execute 分權):新 SSOT / 新 prop / 新 canonical meaning / cross-component semantic → **STOP propose**,等 user verbatim 拍板才 ship
+- **Surgical**(AGENTS.md「Scope classifier — Surgical visual bug」):pixel / token / class adjustment, no new SSOT / API / cross-component → AUTO ship 此 fix
+- **P2E engineering substantive**:治理／架構 SSOT、refactor、test、migration、adapter 或
+  不改 public 行為的 cross-component invariant → **AUTO**，依 evidence + independent
+  review + hard gates 自主完成。
+- **P2H product/UI/UX substantive**:新 public prop semantics、產品 workflow／interaction、
+  視覺／文案 canonical meaning 或其他 user-visible tradeoff，且既有 SSOT 無唯一答案
+  → **STOP propose**，只接受 exact target-bound user decision。
 
-混合 batch:surgical 部分 ship,substantive 部分 propose。**禁止**:substantive 偷渡進 surgical batch。
+混合 batch:surgical + P2E 一起自主完成；P2H 保持 proposal-only。**禁止**:把 P2H
+偷渡進 engineering batch，也禁止把 P2E 轉交 user 做工程選擇。
 
 ### Phase 3 — Final batch-end verify(原 M32(c)(h2))
 
@@ -95,7 +108,7 @@ Read / Grep / Glob 多檔需求 → **single message multi-tool-call**:
 ```bash
 npx tsc -b                                    # type
 npm run hooks:test                            # invariant
-node scripts/visual-audit-<target>.mjs        # pixel-quantified per M32(a)
+node scripts/visual-audit.mjs --scope=changed # pixel-quantified per M32(a)(或 --scope=component:<X>)
 ```
 
 **MUST-ALL re-check**(per Phase 0 checklist):
@@ -139,11 +152,11 @@ node scripts/visual-audit-<target>.mjs        # pixel-quantified per M32(a)
 | `/visual-audit` | 單次視覺對齊 | Phase 3 sub-step,本 skill 包它 |
 | `/component-quality-gate` | stakeholder gate | 不重疊(stakeholder vs daily bug fix) |
 | `stop_self_audit.sh`(hook) | claim-verify gap 攔 | 本 skill Phase 3 是 active side;hook 是 passive trip-wire |
-| `check_pixel_quantified_audit.sh`(hook) | M32(a) audit script 必 pixel | 本 skill Phase 3 跑該 audit |
+| `check_pixel_quantified_audit.sh`(hook) | M32(a) audit script(`scripts/visual-audit*.mjs`,canonical = `visual-audit.mjs`)必 pixel | 本 skill Phase 3 跑該 audit |
 
 **3 層 防線**:
 - **本 skill**(active workflow):MUST-ALL checklist + batch-end-verify rhythm
-- **stop_self_audit.sh / check_codex_collab_5step.sh**(passive hook):claim-verify gap 攔
+- **stop_self_audit.sh**(passive hook,claim-verify gap,BLOCKER)+ **check_codex_collab_5step.sh**(passive hook,codex-collab commit 缺 cite+verify+verdict marker,P1 soft stderr 不 block)
 - **M20 / M32(a)**(meta-rule):上游 invariant
 
 ---
@@ -153,7 +166,7 @@ node scripts/visual-audit-<target>.mjs        # pixel-quantified per M32(a)
 - **Bazel `bazel test //...`**:全 target 並行 + final report,而非 per-target sequential
 - **GitHub Actions matrix**:N 個 job 並行,final aggregate verdict
 - **Toyota TPS jidoka**:每 station per-item verify,**但** verify 是 station-end 而非 in-progress checkpoint
-- **Anthropic Claude Code prompt eng**:「Maximize use of parallel tool calls」
+- **Provider-neutral execution discipline**:「依賴關係允許時並行執行」
 - **Stripe / Linear engineering blog**:「batch deploy + single canary verify」over「per-PR canary」
 
 ---

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

@@ -0,0 +1,29 @@
+---
+name: canonical-reviewer
+description: Provider-neutral read-only review of governance changes; use after material canonical edits or when SSOT ownership and downstream propagation must be verified.
+---
+
+# Canonical read-only review workflow
+
+Provider identity, peer routing, transport, and tool restrictions are adapter bindings. This file owns the shared verdict rubric.
+
+## Preconditions
+
+- Require the exact diff/changed files, author provider, reviewer provider, and distinct context identity.
+- Author and reviewer providers must differ for an independent-review claim.
+- Use an immutable snapshot or enforce read-only tools. Fingerprint `git status --porcelain=v1 -z` and `git diff --binary --no-ext-diff` before and after.
+- For design-system findings, apply every relevant dimension in `packages/design-system/ds-canonical/skills/design-system-audit/references/audit-prompts.md`; do not substitute an adapter-local rubric.
+
+## Review questions
+
+1. Is each policy statement located at its true canonical owner rather than copied into an adapter or generated view?
+2. Do all other mentions point to that owner instead of restating mutable semantics?
+3. Are provider roles, transports, commands, hooks, and discovery paths confined to adapter bindings?
+4. Are generated views deterministic, provenance-marked, and protected by a drift check that detects missing, extra, content, and mode changes?
+5. Does every declared provider resolve equivalent canonical outcomes or an explicit machine-readable incompatibility reason?
+6. Are native hooks treated as feedback accelerators while hook-independent CI remains authoritative?
+7. Are downstream templates, packages, consumers, schemas, documentation, and tests updated without creating another owner?
+
+## Verdict
+
+Return `PASS`, findings with file/line evidence, or `REVIEW-BLOCKED`. Missing input, incomplete inventory, same-provider review, absent isolation, mutation, or missing provider identity cannot produce PASS. Suggestions are text only; reviewer mode never edits, stages, commits, pushes, comments, or mutates external state.

package/ds-canonical/skills/code-quality-audit/SKILL.md

@@ -16,11 +16,11 @@ Scope:**tsx / ts code hygiene**,跟 design canonical 正交。
 | # | Check | Severity | 如何判定 |
 |---|-------|---------|---------|
 | 1 | `any` 使用 | P0 | grep `: any` / `as any` / `<any>` / `any[]` / `Record<X, any>`;支援 `// any-allow: {rationale}` 逃生口(同行或上一行) |
-| 2 | File size(.tsx)| P0 > 800 / P1 > 500 | `wc -l`;budget 500 / transition cap 800;spec 同 `check_file_size_budget.sh` policy |
+| 2 | File size(.tsx)| P0 > 800 / P1 > 500 | `wc -l`;budget 500 / transition cap 800(tsx SSOT = `scripts/code-quality-audit.mjs:36-37` + `lib/_code_quality.sh`;`check_file_size_budget.sh` 僅管治理 md,數字精神一致非同一 policy)|
 | 3 | Long function | P1 > 80 行 | naive:`function`/`const` 宣告到 matching `}` indent 行距 |
 | 4 | Dead export | P1 | `export` 名稱在其他 src/ 檔無出現;exempt `*Props/Options/Config/Args/Context/Variants/Value` 型別 API 慣例 |
 | 5 | Circular dep | P0 | DFS import graph,找 cycle |
-| 6 | Magic number | P1 | 覆蓋不完整 → 由 `check_token_hygiene.sh` hook 層負責(primitive color / shadow / Tailwind v4 `[--foo]`);本 skill 不重複 |
+| 6 | Magic number | P1 | 覆蓋不完整 → 由 token 防線(`lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`)層負責(primitive color / shadow / Tailwind v4 `[--foo]`);本 skill 不重複 |
 
 ## When to run
 
@@ -36,16 +36,20 @@ Scope:**tsx / ts code hygiene**,跟 design canonical 正交。
 1. Run `node scripts/code-quality-audit.mjs [--scope=<scope>]`
 2. Triage findings into P0 / P1 / P2
 3. Auto-fix trivial(unused imports,trivial `any` casts with obvious type)
-4. STOP for user decision on:
-   - File-size P0(大 component architectural split)
-   - Circular dep(需設計層面重組)
-   - 無法 auto-type 的 `any`(需 design judgment 訂 proper type)
+4. 依 shared governance 的 Decision Authority classifier 分類並處理:
+   - File-size P0 的 component architectural split、circular-dependency 重組、proper type
+     與 long-function remediation 都是工程決策，依 Standing Authorization 自主完成並驗證。
+   - 只有修法會改變 public component semantics、產品 workflow、interaction 或其他產品／
+     UI／UX SSOT，且證據收斂後仍有真實取捨時，才停下取得 exact target-bound decision。
+   - 無法分類時 fail closed 並補 source/evidence；task／deliverable 明確要求時才加
+     independent review，不得用泛用 user approval 代替工程判斷。
 
 ## 禁止
 
 - 禁 silent 吞 `any`(必加 `// any-allow: {rationale}`)
-- 禁把 dead export 直接刪(可能是 planned API surface);flag → user 決策
-- 禁把 long function 硬拆(拆錯比爆長還糟);只提議,user sign-off
+- Dead export 若只是 implementation residue，依 usage/public-surface evidence 自主移除；若會
+  改變 public component semantics，依 authority classifier 判定是否存在真正 UI/UX 取捨。
+- Long function 依 tests、public API 與行為不變證據自主重構；禁無證據硬拆。
 
 ## Integration points
 
@@ -54,10 +58,10 @@ Scope:**tsx / ts code hygiene**,跟 design canonical 正交。
 | `/design-system-audit` Dim 27 | `--deep` 必 chain 本 skill scope=all |
 | `/component-quality-gate` Ship | chain 本 skill scope=component:{Name} |
 | `/new-component` Phase 4.5 | 元件建完必跑 scope=component:{Name} |
-| Hook `check_code_quality.sh` | PostToolUse Edit/Write on src/ — 只跑 any + file-size(quick) |
+| Hook `post_edit_dispatcher.sh` → `lib/_code_quality.sh` | PostToolUse Edit/Write on src/ — 只跑 any + file-size(quick);原 check_code_quality.sh folded(2026-05-13 dispatcher consolidation)|
 
 ## References
 
 - `scripts/code-quality-audit.mjs` — 實作
-- `.claude/hooks/check_code_quality.sh` — per-edit lite check
-- 相關:`check_token_hygiene.sh`(正交 — token 紀律 vs code 紀律)
+- `packages/design-system/ds-canonical/hooks/lib/_code_quality.sh`(經 canonical post-edit dispatcher chain)— per-edit lite check
+- 相關:token 防線 `lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`(正交 — token 紀律 vs code 紀律)