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

package/ds-canonical/references/failure-class-registry.json

@@ -0,0 +1,160 @@
+{
+ "_meta": {
+  "owner": "packages/design-system/ds-canonical/references/failure-class-registry.json",
+  "invariant": "每類被抓過的 failure class 必須終有 ship 到 consumer 的機械防線(user 2026-07-10 verbatim「建立治理的基本原則」)。status 三態:protected(已有 MECHANICAL_CONSUMER / DS_API_FIXED 防線)/ remediating(必帶 plan 指標)/ judgment(regex 不可判,必帶 auditDim 兜底)。gate = scripts/audit-failure-class-coverage.mjs --check(deep-audit dim 91 chain)。",
+  "legacyProvenance": ".claude/logs/failure-class-coverage-matrix.json(2026-07-10 historical snapshot,non-authority；41-agent 對抗 workflow,每 verdict cite 驗證)",
+  "addRule": "新 failure class(deep-audit / user 抓 / codex 抓)→ 本 registry 加 row;沒 row 或 status 缺 = gate 紅燈。remediation 落地後把 status 升 protected 並記 landedAt。"
+ },
+ "classes": [
+  {
+   "id": "phantom-layout-token",
+   "name": "幻覺 layout token / utility",
+   "status": "protected",
+   "note": "check_layout_space_magic_numbers PHANTOM 白名單(SHIP_AS_IS)+ opacity hook 第 10 類幻覺 state 尾綴(2026-07-10)"
+  },
+  {
+   "id": "handcraft-mini-table",
+   "name": "手刻 mini-table(grid-cols 黏死欄寬)",
+   "status": "protected",
+   "note": "r3 偽表格簽名 + magic-hook grid-cols px(皆 SHIP_AS_IS)"
+  },
+  {
+   "id": "handcraft-menu-item-row",
+   "name": "手刻 menu-item 可點列",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "根因 MenuItem startContent(beta.84)+ r3 nav-row 簽名(hover+selected 成對)"
+  },
+  {
+   "id": "export-chain-break",
+   "name": "export 斷鏈逼手刻(R2)",
+   "status": "protected",
+   "note": "DS_API_FIXED — barrel generator + preflight --check drift gate;beta.84 發版後 consumer 正式接上"
+  },
+  {
+   "id": "contrast-pair-violation",
+   "name": "對比配對違規(亮色底 × text-white)",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "r3 C5 簽名 → CAT_SOLID pair"
+  },
+  {
+   "id": "handcraft-form-validation",
+   "name": "手刻表單驗證 state",
+   "status": "protected",
+   "note": "r3 useFormValidation 零消費簽名(SHIP_AS_IS)"
+  },
+  {
+   "id": "selectmenu-direct-use",
+   "name": "SelectMenu internal 直用",
+   "status": "protected",
+   "note": "r3 C7 簽名(<SelectMenu 直用 → BLOCK,escape @selectmenu-direct-ok:;select-menu.spec.md:53 明文禁直用特例)",
+   "landedAt": "2026-07-10"
+  },
+  {
+   "id": "handcraft-header-tabs",
+   "name": "頁內手刻 header+TabsList(未走 tabsSlot)",
+   "status": "judgment",
+   "note": "dialog/surface 半邊已有 check_tabs_content_chrome_body_double_gap P0(SHIP_AS_IS);頁內 h2+TabsList 存在合法場景(TypeSettings 內容層分頁 @tabs-content-gap-ok 錨例)= context 判斷,倉促 regex = 誤殺",
+   "auditDim": "product-ui-audit + header-canonical.spec.md Rule W4"
+  },
+  {
+   "id": "spacing-tier-semantic",
+   "name": "spacing 親疏語義誤用(tier 選錯)",
+   "status": "judgment",
+   "auditDim": "90(layout-space macro judgment sweep)+ product-ui-audit",
+   "note": "合法 token 用錯 tier = context 判斷,regex 不可判;magic/phantom 機械半邊已 protected"
+  },
+  {
+   "id": "search-action-position",
+   "name": "業務 search 被推工具層位置",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "r3 C10 簽名(spacer+Search Input);業務 vs 工具判定本身 judgment → escape @search-right-ok"
+  },
+  {
+   "id": "dialog-chrome-double-x",
+   "name": "dialog chrome 雙 X / header 操作不走 actions",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "r3 C11 簽名(DialogHeader 250 字窗)"
+  },
+  {
+   "id": "field-width-misuse",
+   "name": "Field 家族硬寬 / hug-fill 語義",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "硬寬 w-N 機械(r3 C12);hug vs fill 語義選擇 = judgment 半邊歸 product-ui-audit"
+  },
+  {
+   "id": "handcraft-section-header",
+   "name": "手刻可收合 section header",
+   "status": "protected",
+   "note": "R3-7 拍板 codify 進 item-anatomy.spec.md「可收合 section header 組合 canonical」(組合非元件,隨 npm ship)+ r3 C13 簽名(Chevron+justify-between+可點且無共用元件 → BLOCK)",
+   "landedAt": "2026-07-10"
+  },
+  {
+   "id": "avatar-anatomy-misuse",
+   "name": "avatar row-context 直用(未走 ItemAvatar/PersonValue 鏈)",
+   "status": "judgment",
+   "note": "前置已清:PersonValue/PersonDisplay/PersonAvatarTag 2026-07-10 補進 export 面(probe 驗 root barrel 解析)= 正道可 import;「row context 內 raw Avatar」判定 = context 判斷,regex 不可判(Avatar 合法 standalone 場景遍地)",
+   "auditDim": "product-ui-audit + item-anatomy.spec.md:178(Prefix 垂直對齊)"
+  },
+  {
+   "id": "datatable-density-structure",
+   "name": "DataTable 密度/tree 佔位/inline-create idle 未消費",
+   "status": "judgment",
+   "note": "tree 佔位半邊 DS_API_FIXED(data-table.tsx sibling-aware,beta.84 生效);size 密度選擇與 idle 列樣式 = context 判斷(嵌入式 vs 主表格),spec 隨 npm ship 供讀",
+   "auditDim": "product-ui-audit + data-table.spec.md:71/80(size 密度)+ :360(inline-create idle)"
+  },
+  {
+   "id": "always-edit-cell",
+   "name": "恆-edit cell(display 態渲染 edit 控件)",
+   "status": "judgment",
+   "note": "機械半邊已上:story-baseline-registry antiPattern datatable-always-edit-cell(cell: 直渲 edit 控件 → R8 BLOCK,unless onCellCommit/editable/display);custom cell 元件包裹子集 regex 看不進去 + RoleCell 拍板反例證實 context 判斷 → judgment 兜底",
+   "auditDim": "product-ui-audit + data-table.spec.md:373(indicator A 案)"
+  },
+  {
+   "id": "separator-geometry",
+   "name": "分隔線幾何(黏按鈕無 mx)",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "r3 C17 簽名 + magic-hook divider 行豁免(治理自我打架修正)"
+  },
+  {
+   "id": "count-label-concat",
+   "name": "計數括號串接(children 層)",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "r3 C18 簽名(children 錨定,aria attr 合法)"
+  },
+  {
+   "id": "two-pane-dialog",
+   "name": "兩欄 dialog 版型 canonical 缺席",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "user 拍板:組合非元件(對齊 Atlassian/MUI composition verdict)→ overlay-surface.spec.md「兩欄 dialog 組合 canonical」(隨 npm ship)+ r3 C19 簽名(共用捲軸機械攔)"
+  },
+  {
+   "id": "handcraft-link-underline",
+   "name": "連結字手刻 underline",
+   "status": "protected",
+   "landedAt": "2026-07-10",
+   "note": "r3 C20 簽名(no-underline / hover:underline 形不誤殺)"
+  },
+  {
+   "id": "arbitrary-variant-contract-broken-by-wrapper",
+   "name": "CSS arbitrary-variant 契約被中間 wrapper 斷鏈",
+   "status": "protected",
+   "landedAt": "2026-07-30",
+   "note": "direct-child 結構選擇器 vs primitive 內部 DOM 巢狀(beta.86 tabsSlot W2 迴歸錨例);防線 = scripts/header-tabs-slot-invariants.mjs render-level gate + data-slot attribute contract"
+  },
+  {
+   "id": "component-spec-benchmark-evidence-debt",
+   "name": "Component spec 以未驗證 benchmark marker 取代可追溯證據",
+   "status": "protected",
+   "landedAt": "2026-08-02",
+   "note": "beta.107 清零 components/**/*.spec.md 的 @benchmark-unverified debt；check_benchmark_citation.sh 在 PreToolUse 禁止 component spec 新增逐句／blanket／citation-allow escape，外部 claim 必附 direct inline evidence，否則改寫成 DS-internal rationale"
+  }
+ ]
+}

package/ds-canonical/references/governance-audit-coverage.md

@@ -0,0 +1,34 @@
+# 治理 home × 稽核者覆蓋表（2026-08-01 重驗）
+
+**觸發**:user verbatim「綜觀來看,deep audit 到底會不會稽核**所有** DS 的治理?」— 不是單軸,是全部。本表 = 逐 home 盤點「誰稽核它、怎麼稽核、多常跑」,誠實標出弱軸。**消費點:`design-system-audit/SKILL.md` Phase 4.5 deep mode**— 同一 run 的 full knowledge-prune 後必逐 row 對照本表並產 evidence／UNOBSERVED receipt；新治理物無 row 或漏 row = deep run 不完整。Default audit 只跑 light prune，不冒充全治理覆蓋。
+
+## 覆蓋表(逐 home,cite 查證過)
+
+| 治理 home | 稽核者(機械) | 跑的時機 | 覆蓋度 |
+|---|---|---|---|
+| `AGENTS.md` + canonical `packages/design-system/ds-canonical/rules/*.md` + 計數 snapshot | `sync-governance-counters --check`(數字 drift,fail-closed)+ session-start Check 7 + `_governance_coverage_check` PostToolUse(原則→dim 對映)+ knowledge-prune D1/D4(重複/矛盾) | 每 session + 每發版 + 季度 | ✅ 強 |
+| `packages/design-system/ds-canonical/rules/*.md`(M-rules 等) | counters(M-rule 數)+ `extract-canonical-rules --check` + canonical-reviewer agent(edit 時)+ knowledge-prune D1/D3/D4 | 每 edit + 每發版 + 季度 | ✅ 強 |
+| `*.spec.md` | deep-audit dims 6/7/8(NO-SAMPLE judgment)+ A.1b claim-vs-code 逐句 + `audit-spec-deadlinks --check` + `add-reciprocal-pointers --check` + `check_spec_class_drift` hook + `audit-content-quality --check`(**scope 註:此 script 只掃 components/ 的 spec/story,非治理 md**) | 每 deep-audit + 每發版 | ✅ 強 |
+| registered hooks | `audit:hook-quality`(有可信 telemetry 時才判 fire 活性/假死；缺資料 = unobserved)+ `audit-hook-test-coverage --check`(BLOCKER hook 必有 test)+ `tests/run-all` + fork classification gate(`build-fork-governance --check`,新 hook 未分類 = 擋發版)+ dynamic counters(數量 cap) | 每 deep-audit + 每發版 + 季度 | ✅ 結構強 / ⚠️ live telemetry 視環境可為 UNOBSERVED |
+| canonical skills | knowledge-prune D7(只在有可信 invoke telemetry 時判活性)+ file-size hook + deep-audit A.0 全讀 + governance-health 月度；inventory 由 canonical tree 動態枚舉 | 每 deep-audit + 季度 + 月度 | ⚠️ 中(read 層有了;逐句 claim-vs-behavior 仍無機械閘 = 弱軸 2) |
+| committed memory SSOT + provider cache | session-start 對 repo SSOT cap 檢查(≤20)+ `sync-memory --check` content-hash drift + knowledge-prune D8(recency/orphan) | 每 session + 季度 | ✅ 強 |
+| `references/`(registry / 對照表) | dim 91 registry gate(failure-class)+ `check_story_invariants` R8(story-baseline-registry 消費)+ repo-hygiene exact inventory/duplicate gate + prune D1/D4/D2 references-orphan | 每 deep-audit + 每發版 + 季度 | ⚠️ 中(結構/registry 強；純文字語意仍靠季度 judgment) |
+| `planning/`(Level 9 plan doc) | `validate-planning-registry.mjs` 驗 exact inventory/status/executable contract；knowledge-prune D8 驗 active memory pointer、stale/orphan | 每 deep-audit + 每發版 + 季度 | ⚠️ 中(狀態機械；內容 recency 仍是 judgment) |
+| repository folder/file topology(含 authority + available registered consumer repos) | `repository-hygiene-invariant.mjs` + paired mutation meta-test + `references/repository-hygiene.md` 全檔語意分類；未掛載 repo = unobserved | 每 full/deep audit + 每發版 | ✅ 結構強 / ⚠️ ambiguous future-use 需 evidence judgment |
+| checker gates(discovery-derived) | `audit-coverage-matrix --check`(每 dim 的 tier/mechanism 封閉分類、deterministic plan 與 active hook edge 綁定)+ `audit-gate-meta-test-coverage --check`(發現數 = paired owner 數、zero debt)+ `run-gate-meta-tests.mjs`(一次性 disposable snapshot 內執行 paired mutation tests)。Harness registry 從 checker inventory + execution owner 即時重算；任一 test 改成 external-only 就立即產生 gap 並 fail closed，不靠人工維護總數。 | 每 deep-audit + 每發版 + All-Harness | ✅ 強(只證明本機 mutation closure；不冒充 browser/registry/model/CI/managed-host live certification) |
+| plugin / marketplace / fork corpus | `plugin-structure-validate` + `build-fork-governance --check` + `test-fork-governance` 假 fork harness(防 false-green/brick)+ counters | 每發版 | ✅ 強 |
+| eslint-plugin | 自帶 node --test(50 case)| 手跑/CI 無(**未發佈 = 對 consumer 零效**,plan doc 批次 B) | ⚠️ 已知缺口(tracked) |
+| commands / agents(稀住戶) | knowledge-prune D2(2026-07-10 補 bullet:commands 對照 skill-invokes log / agents 用 git recency + transcript grep — 原 D2 零掃描此二 home) | 季度 | ⚠️ 低(住戶少、變動少) |
+| failure-class(病根→防線) | **dim 91 `audit-failure-class-coverage --check`(2026-07-10 新)** | 每 deep-audit + 每發版 | ✅ 強 |
+| provider/runtime/model 與獨立第二意見綁定 | Provider-neutral authority = `packages/governance/canonical/providers.json` + `infra/governance/providers/model-release-registry.json` + `provider-review-binding.mjs` + managed-CI model-release authority/readback。`check-codex-freshness.mjs` 僅是 **Codex local adapter diagnostic**(config/CODEX_HOME/CLI/evidence TTL/model identity fail closed)，不是 Claude/未來 provider 共通 workflow，也不再宣稱已接入 legacy deep-audit B.0 或 codex-collab Step 0.4。 | 每次 independent-review/deep-audit provider binding；Codex diagnostic 只在對應 adapter 明確執行 | ✅ contract 強 / ⚠️ live model/provider certification 仍以外部 readback 為準 |
+
+## 誠實結論(回答「所有?」)
+
+**所有已登記治理 home 都有稽核路徑，能機械化的結構／計數／引用／拓撲／mutation closure 均 fail closed。**仍有 4 個不能冒充全自動真值的弱軸（全部 tracked，非隱藏）：
+
+1. **live 外部執行/啟用**:discovery-derived 本機 paired mutation 已保持 zero-gap，但 GitHub rulesets/App identities、registry/npm、真實 model provider、cloud runner 與 managed-host 仍必須用簽署且鮮度受控的 live readback 認證；`Unverified` 不能當 PASS。
+2. **SKILL.md 內容 claim-vs-behavior**:skill 文字宣稱的流程 vs 實際 hook/script 行為,無逐句機械比對(A.1b 只對 component spec)。季度 prune D5 部分覆蓋。
+3. **eslint-plugin 未發佈**(批次 B tracked)。
+4. **planning / 純文字 reference 靜置漂移**:by-design 低頻,D1/D4/D8 季度兜底;規則 = 活的內容必有 memory pointer。
+
+**加新治理物時的規矩**:新 home / 新 artifact 類型 → 本表加 row(誰稽核它、多常跑);沒 row = deep-audit C.0b 抓(已接線)。

package/ds-canonical/references/item-anatomy-recipe.md

@@ -194,7 +194,7 @@ const isActive = variant === "meta" ? false : (... 同上)
 - 看 `item-layout.tsx` 的 export → 找到 `ICON_SIZE` / `AVATAR_SIZE` / `ItemPrefix` / `ItemLabel` / `ItemIcon` / `ItemAvatar` / `ItemInlineAction` / `ItemInlineActionButton` / `ItemSuffix` / `RowSizeProvider` / `useRowSize` / `getUniformPrefixSlotStyle` / `INLINE_ACTION_HOVER_BG_SIZE` ✓
 - 看本 spec 的 Recipe → 7 步 copy-paste ✓
 - 看 `MenuItem` / `SidebarMenuButton` / `TreeItem` 三個現成 row primitive → canonical 實作參考 ✓
-- 跨檔案 grep 規則 → CLAUDE.md「Row primitives 共用 item-layout 公式」節列出禁止事項 ✓
+- 跨檔案 grep 規則 → `patterns/element-anatomy/item-anatomy.spec.md`「Row primitives item-layout 公式」節列出禁止事項 ✓
 
 如果以上四條任何一條斷掉,就是 spec / code drift,該補。
 
@@ -204,14 +204,14 @@ const isActive = variant === "meta" ? false : (... 同上)
 
 ```bash
 # 找出可疑的 raw ItemPrefix wrap 用法（應該幾乎沒有）
-rg '<ItemPrefix>\s*<[A-Z]' src/design-system
+rg '<ItemPrefix>\s*<[A-Z]' packages/design-system/src
 
 # 找出硬寫 size 的 Avatar / Icon（在 row primitive 內應該為零）
 rg '<Avatar[^>]*size=\{[0-9]+\}' packages/design-system/src/components/{Sidebar,TreeView,SelectMenu,DropdownMenu}
 rg 'size=\{16\}|size=\{20\}|size=\{24\}' packages/design-system/src/components/{Sidebar,TreeView}
 
 # 找出沒走 ItemInlineAction 的 inline action button
-rg "group/action.*relative grid place-content-center" src/design-system
+rg "group/action.*relative grid place-content-center" packages/design-system/src
 ```
 
 任何一條結果非空就是 drift，要修。

package/ds-canonical/references/naming-conventions.md

@@ -1,6 +1,6 @@
 # 命名與語言一致性 — 詳表
 
-CLAUDE.md `# 命名與語言一致性` 詳細展開。主章留 meta rule + 三重 test,本檔放完整對照表 + 禁止清單。
+AGENTS.md `# 命名與語言一致性` 詳細展開。主章留 meta rule + 三重 test,本檔放完整對照表 + 禁止清單。
 
 ## 檔案 / 資料夾
 
@@ -11,6 +11,7 @@ CLAUDE.md `# 命名與語言一致性` 詳細展開。主章留 meta rule + 三
 | Pattern 資料夾 | kebab-case | `item-anatomy/`、`action-bar/`、`horizontal-overflow/` |
 | Pattern spec 檔 | kebab-case(與資料夾同名) | `item-anatomy.spec.md`、`action-bar.spec.md` |
 | Pattern 內多檔 flat 並列 | folder 為 topic 領域,含 overview + 具體 topic 各自檔案 | `element-anatomy/` folder 內 flat 放 `element-anatomy.spec.md`(taxonomy overview)+ `item-anatomy.spec.md / .tsx / .stories.tsx`(F1/F2 具體) |
+| Demo / non-export helper 檔 | `_` prefix + kebab-case;不進 index.ts barrel / 不 export 給 consumer,只供同資料夾 stories / anatomy 消費(2026-06-12 codify)| `AppShell/_demo-helpers.tsx` |
 | Hooks 資料夾 | lowercase | `hooks/` |
 | Hooks 檔案 | kebab-case(對齊 shadcn) | `use-is-mobile.ts`、`use-overflow-items.ts` |
 | Token 資料夾 | 單字 lowercase / 多字 camelCase | `color/`、`radius/`;`uiSize/`、`layoutSpace/` |

package/ds-canonical/references/principle-dim-map.json

@@ -1,8 +1,12 @@
 {
   "_meta": {
     "purpose": "Explicit semantic mapping: principle (M-rule / trait / hook) → audit dim cover",
-    "ssot": ".claude/memory/feedback_audit_preflight_全盤查.md + design-system-audit/SKILL.md",
-    "updated": "2026-05-18",
+    "ssot": "packages/design-system/ds-canonical/references/principle-dim-map.json",
+    "governedBy": [
+      "governance/memory/feedback_audit_discipline_full_sweep_deterministic_preflight.md",
+      "packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md"
+    ],
+    "updated": "2026-07-16",
     "version": "1.0",
     "_principle": "禁 heuristic match;每原則必 explicit dim list。新原則加入必同 commit 加 entry,違 = hook BLOCK"
   },
@@ -24,10 +28,8 @@
     },
     "M4": {
       "name": "_Group fieldCtx 隔離",
-      "dims": [
-        34
-      ],
-      "note": "Dim 34 disabled state precedence 隱含驗 group context"
+      "dims": [],
+      "note": "2026-05-31 infra-audit 修假覆蓋:原宣稱 dim 34「隱含驗」是假 — dim 34 hook(check_field_family_invariants A.2 FieldControlGroup wrapper + A.4 disabled color)不驗 M4 的 fieldCtx.id 隔離 invariant(_Group child 不共用 fieldCtx.id,否則 label 全抑制+點擊只 toggle 第一個)。無 dedicated mechanical check;靠 runtime story + manual review。queued:考慮加 dim/hook 驗 _Group 建自己 context"
     },
     "M5": {
       "name": "State 疊加 spec coverage",
@@ -190,6 +192,11 @@
       "dims": [],
       "note": "hook check_pixel_quantified_audit;對 audit scripts 自身,不對 component"
     },
+    "M36": {
+      "name": "Provenance 不得升格 + 禁自鎖",
+      "dims": [],
+      "note": "非元件維度:作用於 AI 產出的文件與回覆(標『user 拍板』必附原話)與 governance 自鎖判斷。以文件內『來源總帳』格式 + PR review 落實,無 component-scope audit dim"
+    },
     "_retired": {
       "M27": "2026-05-15 → folded into M23(c)(framework prop name conflict child)",
       "M33": "2026-05-22 → folded into M20(AI self-correction sub-rule)",
@@ -429,7 +436,7 @@
     },
     "main_branch_workbench": {
       "dims": [],
-      "note": "2026-05-17 ship(Solo-work canonical infra,M28 sub-rule):PreToolUse Edit/Write 偵測 current branch=main + edit production code(packages/design-system/src/src/app/src/explorations)+ 近 5 條 user msg 無 branch-trigger keyword → BLOCKER。補 R1(2nd branch)R2(PR)R3(push main)沒抓的「main-as-workbench」case。起因 user verbatim 2026-05-17「不是只有我說 push 到 main 才真的會 push 到 main 嗎」,本 session AI 整個 deep audit 都在 main 上 edit。escape:doc-only(spec.md) / CLAUDE_BYPASS_MAIN_WORKBENCH=1"
+      "note": "M28 protected-main feedback gate:PreToolUse Edit/Write 對 repo 內任何檔案偵測 current branch=main/master 即 BLOCKER；文件/治理也無 direct-main 豁免。Claude/Codex tool 欄位正規化，task branch 才放行。CLAUDE_BYPASS_MAIN_WORKBENCH=1 僅 recovery，本地 override 不能繞 GitHub ruleset。"
     },
     "dim_count_drift": {
       "dims": [],
@@ -438,6 +445,126 @@
     "propose_pre_grep_verify": {
       "dims": [],
       "note": "2026-05-18 ship(M18 Q0 Pre-ASK self-verify governance infra):PreToolUse Edit/Write planning/reports/handoff *.md 偵測 propose keyword(請拍板 / 等你拍板 / 決策 N / 我推 A/B/C / 選項)但 content 無 file:line cite 證據 → P1 stderr warn。Escape:檔頭 <!-- @propose-pre-verified --> 含 rationale。起因 2026-05-18 Sheet/inline-action/SurfaceBody 三題 propose 給 user 拍板,grep 後 0 個真 gap;user verbatim「不是老早就跟你說過要我決策前請先基於我們所有的檔案包括設計原則包括 ssot 包括所有實作代碼,自主自動驗證這些問題是否真的是問題」"
+    },
+    "tabs_content_chrome_body_double_gap": {
+      "dims": [
+        89,
+        90
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:write-time P0(Check1 tabs double-gap + Check2 overlay-body fixed macro gap);audit-time dim 89 sweep + dim 90 judgment"
+    },
+    "storybook_addon_packaging": {
+      "dims": [
+        87
+      ],
+      "note": "2026-07-03 entry add:packaging 事故家族(beta.27-31)write-time P0;audit-time 由 dim 87 dogfood prepublish(npm install + build-storybook consumer view)deterministic cover"
+    },
+    "tailwind_wildcard_in_docs": {
+      "dims": [],
+      "note": "2026-07-03 entry add:beta.27 release-fail anchor write-time P0;audit-time 由 release preflight build gate(build:lib + build-storybook)deterministic cover,無獨立 dim"
+    },
+    "chrome_header_avatar_canonical": {
+      "dims": [],
+      "note": "2026-07-03 entry add per audit-preflight gap:write-time P0 攔 chrome header 內 ItemAvatar 誤用(header-canonical 消費紀律);audit-time 由 dim 1 design-language + A.1b per-component cover,無獨立 dim"
+    },
+    "codex_brief_invariants": {
+      "dims": [],
+      "note": "2026-07-03 entry add per audit-preflight gap:codex-collab runtime 紀律(brief 三 invariant);governance-only,solo mode 不涉"
+    },
+    "consumer_app_invariants": {
+      "dims": [
+        69,
+        70,
+        71,
+        82
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:consumer app DS 使用紀律 write-time ×4;audit-time dim 69-71(no-catalog/@story-baseline/primitive misuse)+ 82(app story title)"
+    },
+    "consumer_code_quality": {
+      "dims": [
+        27,
+        56,
+        71
+      ],
+      "note": "Provider-neutral consumer source gate:any/file-size 由 dim 27 code-quality 對應；AppShell primary-header chain 由 dim 56；overlay/menu-row primitive misuse 由 dim 71。"
+    },
+    "ds_anchor_preflight": {
+      "dims": [
+        57
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:M29 anchor preflight;dim 57 直接對應(enforcement coverage)"
+    },
+    "escape_marker_abuse": {
+      "dims": [
+        76
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:dim 76 escape marker abuse 直接對應"
+    },
+    "full_story_visual_interaction_sweep": {
+      "dims": [
+        73
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:dim 73 full-story sweep 直接對應"
+    },
+    "item_list_gap": {
+      "dims": [
+        21
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:M16 standalone gap;dim 21 直接對應"
+    },
+    "layout_space_magic_numbers": {
+      "dims": [
+        90
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:app-code write-time P0(skip DS-src by design);DS-src 由 dim 90 judgment sweep cover"
+    },
+    "orphan_ds_css": {
+      "dims": [],
+      "note": "2026-07-03 entry add per audit-preflight gap:write-time P0(css 不在 aggregator 也沒被 import = orphan;失敗記憶索引條目);audit-time 由 build + visual 間接,無獨立 dim"
+    },
+    "overlay_open_focus_escape_probe": {
+      "dims": [
+        74
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:dim 74 overlay probe 直接對應"
+    },
+    "plugin_fork_health": {
+      "dims": [
+        58
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:dim 58 plugin install enforcement 直接對應"
+    },
+    "propose_discipline": {
+      "dims": [],
+      "note": "2026-07-03 entry add per audit-preflight gap:Stop hook runtime 紀律(中文人話 + cite);governance-only"
+    },
+    "propose_without_benchmark": {
+      "dims": [],
+      "note": "2026-07-03 entry add per audit-preflight gap:M26 runtime 紀律(propose 前 WebFetch);governance-only"
+    },
+    "sidebar_menu_button_implicit_wrap": {
+      "dims": [
+        71
+      ],
+      "note": "2026-07-03 entry add per audit-preflight gap:write-time 攔隱式 wrap;audit-time dim 71 primitive misuse + A.1b composition cover"
+    },
+    "dynamic_tailwind_class": {
+      "dims": [
+        18
+      ],
+      "note": "動態拼 Tailwind class 不被掃描 silent 失效(2026-07-09 hook;dim 18 token hygiene 家族 cover;2026-07-16 PNG 補 entry)"
+    },
+    "ssot_header_declaration": {
+      "dims": [
+        5
+      ],
+      "note": "新 production tsx 必帶「── 消費的 SSOT ──」段(2026-07-07 hook;dim 5 SSOT 消費 cover;2026-07-16 補 entry)"
+    },
+    "story_determinism": {
+      "dims": [
+        46
+      ],
+      "note": "story 禁 Date.now/Math.random 非決定性(2026-07-09 hook;dim 46 cover;2026-07-16 補 entry)"
     }
   },
   "newDims_2026_05_17": {
@@ -474,7 +601,7 @@
     },
     "53": {
       "name": "Code-to-spec reverse drift check",
-      "ssot": ".claude/skills/design-system-audit/SKILL.md Group P",
+      "ssot": "packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md Group P",
       "hook": "spec_class_drift",
       "note": "新加(2026-05-17):反向 grep tsx hardcoded class → 對應 spec.md 是否仍寫舊值。Phase 1 漏抓 FileViewer h-14 spec drift 升 dim,對齊 Layer A own Phase 0 全掃 + codex 共識"
     }
@@ -512,4 +639,4 @@
       }
     ]
   }
-}
+}

package/ds-canonical/references/props-naming.md

@@ -1,6 +1,6 @@
 # 元件 Props 命名 — 詳細對照表
 
-`.claude/rules/ui-development.md`「元件 Props 命名」的詳細展開(callback / Badge / icon canonical)。
+Canonical `packages/design-system/ds-canonical/rules/ui-development.md`「元件 Props 命名」的詳細展開(callback / Badge / icon canonical)。
 
 ## 關閉 / 移除類 callback canonical(按語意分層,不合併)
 
@@ -12,8 +12,9 @@
 | `onDismiss` | **通知被忽略** — 暫時訊息被關,不影響流程 | Alert / Notice / Toast / Coachmark | Polaris `Toast.onDismiss` / iOS `dismiss()` |
 | `onRemove` | **從集合移除 item** — parent collection 狀態變化 | PeoplePicker / Combobox multi-select tag / Tag(in list) | Material `Chip.onDelete` / React Aria `onRemove` |
 | `onClear` | **欄位內容清空** — value 設 empty,元件不關 | Input / Select / Combobox / DatePicker clear | Ant `allowClear` + `onClear` / Polaris `clearButton` |
+| `onClearSelection` | **清空多選集合** — 取消所有勾選項(非清欄位內容)| BulkActionBar | Polaris `ResourceList` bulk clear / Material DataGrid `onRowSelectionModelChange([])` |
 
-**禁止**:用同一名 cover 多語意(`onClose` 同時表達 Tag 的 `onRemove`)。spec 寫 callback 時必明示哪一類。
+**禁止**:用同一名 cover 多語意(`onClose` 同時表達 Tag 的 `onRemove`;`onClear` 同時表達「清欄位」與「清勾選」→ 後者必用 `onClearSelection`,2026-07-18 決策12)。spec 寫 callback 時必明示哪一類。
 
 ## Badge 類 prop 名 canonical(按放置,不按「是 badge」籠統命名)
 
@@ -24,12 +25,26 @@ Badge 在不同 anchor 有兩種截然不同視覺 / 語意,prop 名區分:
 | `badge` | **Pill 內 inline badge** — label 右側 flex | Button(有 label)/ Tab item / Chip | inline count |
 | `overlayBadge` | **疊視覺重心** — absolute 於 icon/avatar 角 | iconOnly Button / pure Icon | top-right count overlay |
 | `badgeCount`(Avatar 專用) | count overlay,內部用 `<Badge variant="critical">`,貼 avatar 右上 | Avatar | overlay but Avatar 語意 |
-| `status`(Avatar 專用) | **非 Badge** — SVG presence dot,貼右下 | Avatar | presence indicator |
+| `status`(presence dot — Avatar / ProfileCard / PeoplePicker) | **非 Badge** — SVG presence dot,貼右下 | Avatar | presence indicator |
 
 **禁止**:同 prop 名兼 inline + overlay。世界級 Material `BadgedBox`(overlay)vs `Chip.label`(inline)分開;Ant `<Badge overflowCount>` vs `<Tag>` 分開。
 
+**`status` 兩個 value-set family(刻意 overload,非隱性衝突)**:(1) **presence** `'online' | 'away' | 'busy' | 'offline'` — Avatar / ProfileCard / PeoplePicker;(2) **lifecycle** `'uploading' | 'completed' | 'error'`(FileItem / FileUpload)/ `'inProgress' | 'success' | 'error'`(ProgressBar)。兩 family 各自 self-consistent,prop 名沿用同一 presence/lifecycle 軸。
+
 **禁止組合**:有 label 的 Button / Chip 疊 `overlayBadge`(badge 飄到 chrome 邊緣遠離 icon 語義) → 計數改用 `badge` inline。詳 `badge.spec.md`「Overlay 適用元件 canonical」。
 
+## `prefix` / `suffix` canonical(按「prop 型別」判,非按位置一刀切)
+
+`prefix` / `suffix` 這對字在 DS 有 3 種身份,**只有當它是「放 ReactNode 的內容插槽 prop」時才禁**:
+
+| 形態 | 判定 | 改用 / 對齊 |
+|------|------|-----------|
+| **ReactNode 內容插槽 prop**(`prefix?: ReactNode`)| ❌ **禁** — 位置名不傳達放什麼 | 內容描述名:`startIcon`/`endIcon`(icon)、`avatar`(ReactNode)、`endContent`/`endAction`(trailing slot)。對齊 Material `startIcon`/`endIcon`、Atlassian `iconBefore`/`iconAfter` |
+| **值格式 affix 字串 prop**(`prefix?: string`)| ✅ **允許** — 黏在值上的貨幣/單位符號,屬格式化非插槽 | `NumberInput.prefix='$'`/`suffix='kg'`。對齊 Ant `InputNumber.prefix` |
+| **結構 anatomy 詞彙 / 內部原語 / CSS 變數**(`ItemPrefix`/`ItemSuffix`、`--item-prefix-slot`、`data-prefix-type`、spec 的 `[prefix][content][suffix]` 骨架)| ✅ **允許** — 位置就是結構槽的身分(類比 CSS `::before`/`::after`),非 consumer 內容 prop | item-anatomy SSOT(`item-anatomy.spec.md`)|
+
+**一句話判準**:**「是 ReactNode 內容插槽 consumer prop 嗎?是 → 禁(改內容名);否(格式字串 / 結構原語)→ 合法。」** `ui-development.md`「Props 命名」禁令的標的是**內容插槽**,非格式字串或結構詞彙——三者程式碼裡 0 衝突(全庫掃證實無任何元件暴露 ReactNode prefix/suffix 插槽 prop)。
+
 ## 常用 icon canonical
 
 | 語義 | Icon | 反例 |

package/ds-canonical/references/repository-hygiene-policy.json

@@ -0,0 +1,143 @@
+{
+  "schemaVersion": 2,
+  "authority": "packages/design-system/ds-canonical/references/repository-hygiene.md",
+  "transientExemptPrefixes": [
+    ".claude/logs/",
+    ".claude/scratch/",
+    "governance/archive/",
+    "infra/governance/test/fixtures/",
+    "packages/design-system/ds-canonical/hooks/retired/"
+  ],
+  "duplicateExcludedPrefixes": [
+    ".agents/",
+    ".claude/",
+    "generated/",
+    "governance/archive/",
+    "governance/generated/",
+    "packages/design-system/ds-canonical/fork/",
+    "scripts/package-role-sources/",
+    "template/"
+  ],
+  "duplicateExcludedSegments": [
+    "archive",
+    "baseline",
+    "fixtures",
+    "retired"
+  ],
+  "profiles": {
+    "authority": {
+      "topLevelPurposes": {
+        ".agents": "generated Codex agent discovery view",
+        ".changeset": "future-reserved optional release authoring declarations; never a standard-path gate",
+        ".claude": "generated Claude provider view and retained provider evidence",
+        ".claude-plugin": "Claude plugin manifest",
+        ".codex": "Codex provider configuration",
+        ".devcontainer": "portable development environment",
+        ".github": "GitHub workflows and repository policy",
+        ".gitignore": "Git ignore policy",
+        ".husky": "local Git hook entrypoints",
+        ".npmrc": "npm policy",
+        ".storybook": "Storybook host configuration",
+        "AGENTS.md": "provider-neutral agent bootstrap",
+        "CLAUDE.md": "Claude import shell",
+        "CONTRIBUTING.md": "contributor guide",
+        "apps": "first-party consumer applications",
+        "commands": "compatibility symlink to provider commands",
+        "components.json": "component tooling configuration",
+        "docs": "repository documentation",
+        "generated": "committed generated repository views",
+        "governance": "repository governance state and projections",
+        "hooks": "provider hook compatibility surface",
+        "index.html": "Vite application entry document",
+        "infra": "shared governance control plane",
+        "netlify.toml": "Netlify deployment configuration",
+        "package-lock.json": "exact npm dependency lock",
+        "package.json": "workspace manifest",
+        "packages": "workspace packages and canonical design-system authority",
+        "scripts": "repository automation and deterministic gates",
+        "skills": "compatibility symlink to provider skills",
+        "snapshots-baseline": "compatibility symlink to curated visual baselines",
+        "src": "root demo application source",
+        "template": "published consumer template projection",
+        "tsconfig.app.json": "root application TypeScript configuration",
+        "tsconfig.json": "workspace TypeScript configuration",
+        "tsconfig.node.json": "Node/tooling TypeScript configuration",
+        "vite.config.ts": "root Vite configuration"
+      },
+      "declaredSymlinks": {
+        ".claude/snapshots-baseline": "../infra/governance/baseline/visual/targeted",
+        "commands": ".claude/commands",
+        "hooks/scripts": "../packages/design-system/ds-canonical/hooks",
+        "skills": ".claude/skills",
+        "snapshots-baseline": "infra/governance/baseline/visual/curated"
+      },
+      "futureReservedEntries": [
+        {
+          "pathPrefix": ".changeset/",
+          "owner": "infra/governance/release-workflow.json",
+          "purpose": "Retain the reviewed Changesets configuration as an optional version-authoring surface without inserting it into the standard five-step release graph.",
+          "activationCondition": "infra/governance/release-workflow.json must explicitly declare a Changesets version-authoring step and the root package scripts must wire that exact step before these files become active release input.",
+          "lifecycle": {
+            "mode": "review-by",
+            "date": "2026-11-02",
+            "onLapse": "reclassify-or-remove"
+          }
+        }
+      ],
+      "duplicateExemptGroups": [
+        {
+          "paths": [
+            "apps/template/src/App.tsx",
+            "packages/design-system/ds-canonical/templates/dashboard-app.tsx"
+          ],
+          "reason": "first-party dogfood app intentionally proves the canonical dashboard template byte-for-byte"
+        }
+      ]
+    },
+    "product-consumer": {
+      "topLevelPurposes": {
+        ".agents": "generated Codex agent discovery view",
+        ".claude": "generated Claude provider view",
+        ".codex": "Codex provider configuration",
+        ".devcontainer": "portable development environment",
+        ".env.example": "non-secret environment variable contract",
+        ".gitattributes": "Git path behavior",
+        ".github": "GitHub workflows and repository policy",
+        ".gitignore": "Git ignore policy",
+        ".npmrc": "npm policy",
+        ".storybook": "Storybook host configuration",
+        "AGENTS.md": "provider-neutral agent bootstrap",
+        "CLAUDE.md": "Claude import shell",
+        "README.md": "product repository guide",
+        "apps": "product and template applications",
+        "docs": "product documentation",
+        "governance": "installed governance state",
+        "netlify": "Netlify functions and runtime assets",
+        "netlify.toml": "Netlify deployment configuration",
+        "npm-shrinkwrap.json": "installed governance dependency lock",
+        "package-lock.json": "exact npm dependency lock",
+        "package.json": "workspace manifest",
+        "patches": "versioned dependency patches",
+        "schemas": "installed governance schemas",
+        "scripts": "product and governance automation",
+        "tsconfig.json": "workspace TypeScript configuration"
+      },
+      "declaredSymlinks": {},
+      "futureReservedEntries": [],
+      "duplicateExemptGroups": [
+        {
+          "paths": ["apps/template/src/main.tsx", "apps/work/src/main.tsx"],
+          "reason": "template and product retain the same minimal React bootstrap while their application roots diverge"
+        },
+        {
+          "paths": ["apps/template/tsconfig.json", "apps/work/tsconfig.json"],
+          "reason": "both workspace applications intentionally consume the shared TypeScript profile"
+        },
+        {
+          "paths": ["apps/template/vite.config.ts", "apps/work/vite.config.ts"],
+          "reason": "template canary and product intentionally share the deployment-compatible Vite host"
+        }
+      ]
+    }
+  }
+}