@qijenchen/design-system 0.1.0-beta.82 → 0.1.0-beta.84

package/ds-canonical/references/build-ui-canonicals.md

@@ -18,6 +18,7 @@
 | 資料表格(含 header / sorting / sticky) | `<table><thead>...</thead><tbody>...</tbody></table>` | `<DataTable columns={...} data={...} />` |
 | 檔案上傳列表 | `<div>filename</div><ProgressBar /><Paperclip />` | `<FileItem mode="compact" />` or `<FileUpload>` |
 | 表單欄位(label + control + error) | `<label>...</label><input/><span className="text-error">...</span>` | `<Field><FieldLabel>...<Input />...<FieldError/>` |
+| 表單提交驗證(何時顯錯 / 提交可點性) | 手刻 `useState(showErrors)` + `submitAttempt` 旗標自組顯錯時機 | `useFormValidation`(Field 家族 hook,`intent:'create'` = 提交恆可點、點擊時 validate 顯錯;搭 `<FieldError>`)|
 | 全頁 / 區域 loading | `<div className="absolute inset-0 flex center"><Spinner /></div>` | `<Empty icon={<CircularProgress />} description="..." />` |
 | 確認對話框 | raw `<div className="fixed inset-0 bg-black/50">...<button>OK</button>` | `<Dialog>` + `<DialogHeader>` etc |
 | 分隔線 | `<hr className="..." />` or `<div className="h-px bg-..."/>` | `<Separator />`(必要時)or CSS border(見 separator.spec) |
@@ -60,7 +61,7 @@
 - 以上都沒命中 → 才可自建,但 **建完要立刻回來加行**(防下一個人又重造輪子)
 - **本規則同樣適用 story / consumer / exploration code**:不 hand-craft 已有 prop 能做的事(如 Input loading 走 `loading` prop 不自刻 `<div className="relative"><input/><div className="absolute">` / 全頁 loading 走 `<Empty icon={<CircularProgress/>}/>` 不自刻 `absolute inset-0`)。遇缺口**回元件 spec 擴 API**,不自刻繞過 — hand-craft 視覺對齊 bug 上游
 
-具體 anti-pattern signals → `/design-system-audit` Dim 21;pixel-level 視覺 regression(API 用對但視覺仍跑掉)→ `/visual-audit`(D5)抓(原 memory `project_pending_tasks` 已 retire)。
+具體 anti-pattern signals → `design-system-audit/references/audit-prompts.md`「L1. 手刻繞 DS canonical」+ Dim 71 consumer 手刻(Pattern 10;現行 Dim 21 已是「連續 item list wrapper gap」,勿誤指);pixel-level 視覺 regression(API 用對但視覺仍跑掉)→ `/visual-audit`(D5)抓(原 memory `project_pending_tasks` 已 retire)。
 
 ---
 

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

@@ -0,0 +1,145 @@
+{
+  "_meta": {
+    "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)。",
+    "source": ".claude/logs/failure-class-coverage-matrix.json(2026-07-10 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 形不誤殺)"
+    }
+  ]
+}

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

@@ -0,0 +1,33 @@
+# 治理 home × 稽核者 覆蓋表(2026-07-10)
+
+**觸發**:user verbatim「綜觀來看,deep audit 到底會不會稽核**所有** DS 的治理?」— 不是單軸,是全部。本表 = 逐 home 盤點「誰稽核它、怎麼稽核、多常跑」,誠實標出弱軸。**機械消費點:deep-audit SKILL C.0b(2026-07-10 接線)— 每輪收尾必逐 row 對照本表,新治理物無 row = C 階段不完整**;另 knowledge-prune 季度掃時參照。
+
+## 覆蓋表(逐 home,cite 查證過)
+
+| 治理 home | 稽核者(機械) | 跑的時機 | 覆蓋度 |
+|---|---|---|---|
+| `CLAUDE.md` ×2 + 計數 snapshot | `sync-governance-counters --check`(數字 drift,fail-closed)+ session-start Check 7 + `_governance_coverage_check` PostToolUse(原則→dim 對映)+ knowledge-prune D1/D4(重複/矛盾) | 每 session + 每發版 + 季度 | ✅ 強 |
+| `.claude/rules/*.md`(M-rules 等) | counters(M-rule 數)+ `extract-canonical-rules --check` + canonical-reviewer agent(edit 時)+ knowledge-prune D1/D3/D4 | 每 edit + 每發版 + 季度 | ✅ 強 |
+| `*.spec.md`(83+) | 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 + 每發版 | ✅ 強 |
+| hooks(56) | `audit:hook-quality`(fire 活性/假死)+ `audit-hook-test-coverage --check`(BLOCKER hook 必有 test;**2026-07-10 進 preflight fail-closed**)+ `tests/run-all` + fork classification gate(`build-fork-governance --check`,新 hook 未分類 = 擋發版)+ counters(數量 cap) | 每發版 + 季度 | ✅ 強 |
+| skills(SKILL.md ×22) | knowledge-prune D7(invoke 活性)+ file-size hook + deep-audit A.0 第 7 項全讀(2026-07-10 補真 — 原宣稱超前)+ governance-health 月度 | 每 deep-audit + 季度 + 月度 | ⚠️ 中(read 層有了;逐句 claim-vs-behavior 仍無機械閘 = 弱軸 2) |
+| memory(SSOT + mirror) | session-start cap 檢查(≤20)+ `sync-memory` drift + knowledge-prune D8(recency/orphan) | 每 session + 季度 | ✅ 強 |
+| `references/`(registry / 對照表) | dim 91 registry gate(failure-class)+ `check_story_invariants` R8(story-baseline-registry 消費)+ prune D1/D4 + **D2 references-orphan 掃(2026-07-10 加)** | 每發版 + 季度 | ⚠️ 中(2026-07-10 修:原誤引 canonical_propagation/counters — 兩者實際不掃本目錄;純文字 reference 靠季度) |
+| `planning/`(Level 9 plan doc) | 設計上 = 歷史 SSOT 存檔;**D8 planning-orphan 掃(2026-07-10 補 — 原 D8 只掃 memory 方向相反)** | 季度 | ⚠️ 低-by-design(存檔性質;活的必有 memory pointer,無引用 → D8 列 orphan 候選) |
+| scripts/ gates(76 .mjs) | `audit-coverage-matrix --check`(每 dim 的 mechanism script 必存在於 disk)+「DETERMINISTIC dim 必驗 mode 真跑」鐵律(2026-06-11)+ 引入時 breadth-test 鐵律(注入違規→抓到→revert) | 每 deep-audit + 每發版 | ⚠️ 中(**gate script 自身正確性**只有 3 支有專屬 meta-test〔fork harness / DataTable invariants / story-manifest〕;其餘靠引入時 breadth-test + dim 真跑證據。系統性 meta-test = roadmap 候選,見下) |
+| 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 + 每發版 | ✅ 強 |
+| codex 鏈(CLI/model 新鮮度) | **`check-codex-freshness.mjs`(2026-07-10;deep-audit B.0 前置 + codex-collab Step 0.4 同日補接 = 兩條 codex 路徑皆 gate;CLI 落後自動升 + 禁 model pin + effort probe top)** | 每次 codex 使用(兩路徑)| ✅ 強 |
+
+## 誠實結論(回答「所有?」)
+
+**主幹 9 軸已全機械化 + fail-closed**(內容/計數/機械化程度/hook 活性+測試/膨脹矛盾/fork 出貨/病根覆蓋/codex 新鮮度/dim 自身反抽樣)。**「所有」還不成立的 4 個弱軸**(全部 tracked,非隱藏):
+
+1. **gate script 自身正確性**:多數 .mjs gate 無 meta-test(靠引入時 breadth-test + deep-audit「真跑證據」規則)。升級路 = 對 fail-closed gate 逐支補「注入違規必 exit 1」self-test(fork harness 模式推廣)。歸 governance-evolution roadmap 方向 5 品質回灌。
+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

@@ -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/scenario-definition.md

@@ -23,7 +23,7 @@
 **他拿到**:scaffold + 治理 via C-prime committed-config(.claude hooks + SessionStart preamble 注入)+ DS + 治理本體 via npm
 **DS 取得方式**:`@qijenchen/design-system` npm registry(`^X.Y.Z`)
 **Governance 取得**:committed `.claude/settings.json`(dispatcher hooks + fail-open bootstrap)+ SessionStart 注入 npm-current preamble;本體在 npm `ds-canonical/fork`(`npm install` / `npm run sync-all` 同步)。**不需 /plugin install**(雲端不可靠 #62174/#63028)
-**E2E 流程**:`fork → npm install(治理本體隨 npm + committed hook 自動生效,免 plugin)→ claude → npm run setup:netlify(Netlify env var 設 STORYBOOK_BASIC_AUTH = user:password,免費機制走 edge function basic-auth)→ npm run create-app order-dashboard → npm install → npm run storybook → git push`
+**E2E 流程**:`fork → npm install(治理本體隨 npm + committed hook 自動生效,免 plugin)→ claude → npm run setup:netlify(自動 site create/link + 引導在 Netlify dashboard 設 STORYBOOK_BASIC_AUTH = user:password env var — CLI 不提供 one-shot setup,script 印 dashboard URL + step-by-step;免費機制走 edge function basic-auth)→ npm run create-app order-dashboard → npm install → npm run storybook → git push`
 **禁**:import `@qijenchen/design-system/src/**` 或 `/dist/**`(`lint:imports` 攔)
 
 ## 2. SSOT Architecture
@@ -56,12 +56,9 @@ ajenchen/ds-product-template (published repo) ← Mirror artifact ────
 
 ## 3. Mirror Workflow Chain(Scenario B 自動同步)
 
-**Trigger**:DS push main + template-affecting paths(per `.github/workflows/mirror-to-published-template.yml`):
-- `apps/template/**`
-- `scripts/create-app.mjs` + `scripts/setup-netlify-access.mjs` + `scripts/check-plugin-installed.mjs` + `scripts/build-published-template-mirror.mjs`
-- `.devcontainer/**`
-- `template/ds-product-template/**`
-- `package.json`
+**Trigger**(雙觸發,2026-06-16 起):
+- `workflow_run: Release completed` = **發版主路徑**(Release 成功 → npm 已有新版本 → mirror 內部 poll 第一輪即過,零等待)
+- DS push main + template-affecting paths(scaffold 改動路徑;版本未上 npm 時 graceful skip 不長等)— path 列表以 `.github/workflows/mirror-to-published-template.yml` `paths:` 為準(含 apps/template、consumer scripts、.devcontainer、template/ds-product-template、package.json 等),不在此逐條複寫
 
 **Build**:`scripts/build-published-template-mirror.mjs` 用 ALLOWLIST(non denylist,per codex r5)+ transform:
 - Flatten `template/ds-product-template/*` → mirror root
@@ -69,7 +66,7 @@ ajenchen/ds-product-template (published repo) ← Mirror artifact ────
 - Transform `apps/template/package.json`:`@qijenchen/design-system: "*"` → `^X.Y.Z`
 - 4 integrity scans:DS source residue / secret leak / Storybook glob / package dep
 
-**Push**:`workflow + CROSS_REPO_TOKEN PAT(user one-time setup,workflow 印中文指引若 missing)` force-push to `ajenchen/ds-product-template` main
+**Push**:`workflow + CROSS_REPO_TOKEN PAT(user one-time setup,workflow 印中文指引若 missing + fail-loud exit 1)` clone-and-overlay push to `ajenchen/ds-product-template` main — git clone + `rsync --checksum --delete --exclude='.github/workflows'`(保留 published repo 既有 workflows)+ fetch-rebase-retry 迴圈(非 force-push;2026-06-07 競態修)
 
 ## 4. Test Cases(Claude 19 + codex 18 union → 20 canonical)
 
@@ -106,7 +103,7 @@ ajenchen/ds-product-template (published repo) ← Mirror artifact ────
 | M4 | Storybook glob apps-only(no `../packages/**`)| build script integrity scan 3 |
 | M5 | package.json workspaces apps-only + DS dep transformed | build script integrity scan 4 |
 | M6 | `apps/template/package.json` DS dep `*` → `^X.Y.Z` | build script auto transform |
-| M7 | Force-push idempotent(reproducible)| `node scripts/build-published-template-mirror.mjs --out=/tmp/x` 多次 = 相同 output |
+| M7 | Clone-and-overlay push idempotent(reproducible)| `node scripts/build-published-template-mirror.mjs --out=/tmp/x` 多次 = 相同 output |
 
 ## 5. Verify Checkpoints — 後續增刪改 reference 此 SSOT
 

package/ds-canonical/references/ssot-consultation.md

@@ -50,7 +50,7 @@ CLAUDE.md `# SSOT 消費 canonical` 的詳表 + 反例。主章留核心 + point
  */
 ```
 
-Hook `check_ssot_consultation.sh`(retired;改靠 mindset #2 + `check_canonical_propagation.sh`)(原 Write 新 tsx 到 `packages/design-system/src/components/` 或 `src/explorations/` → 若檔內無上述註解區 → warn 要求補齊)。
+Hook `check_ssot_consultation.sh` retired;**2026-07-07 以 `check_ssot_header_declaration.sh` 精簡復活**(新建 production tsx 必帶「── 消費的 SSOT ──」段,P0 BLOCKER)+ mindset #2 + `check_canonical_propagation.sh`。(2026-07-10 hunt 修 stale 描述)
 
 ## 禁止:隱性自創
 
@@ -60,4 +60,4 @@ Hook `check_ssot_consultation.sh`(retired;改靠 mindset #2 + `check_canonical_p
 - 自寫 `<button aria-label="Close"><X /></button>` 作 dismiss(應用 `ItemInlineAction`)
 - 自寫 Row `<div><Icon /><span>label</span><Button /></div>`(應用 `<MenuItem>` + slot)
 - 自訂 Input `variant="custom-name"` 未先 grep 既有 variant 值
-- 在 Toolbar 用 `<input className="bg-transparent border-0 ...">`(應用 `<Input variant="bare">` 若既有;無 → Ambiguity Protocol)
+- 在 Toolbar 用 `<input className="bg-transparent border-0 ...">`(應用 `<Input size="sm" autoWidth>` 標準 default variant;`variant="bare"` 已於 2026-07-09 退役,不再使用)

package/ds-canonical/references/ssot-index.md

@@ -12,29 +12,30 @@
 
 | Interface | Owner spec | Canonical sentence | Drift status | Last divergence event |
 |---|---|---|---|---|
-| **DataTable body cell internal indicator**(display endAction / clear / edit indicator)| `data-table.spec.md`「Body cell internal」row + `inline-action.spec.md`「DataTable body cell internal」row | 「Body cell internal = Field family endAction(自動繼承)」「Field display 元件已對齊」 | ✅ aligned:2026-05-09 D-path retired — `getEditIndicator(colType)` parallel system 移除,indicator authority 移交 Field naked-display `showDisplayEndIcon` opt-in,cellEl 不再 render parallel indicator(見 data-table.tsx「D-path retired」註解)| 2026-05-08 round 5 → 2026-05-09 resolved |
+| **DataTable body cell internal indicator**(display endAction / clear / edit indicator)| `data-table.spec.md`「Body cell internal」row + `inline-action.spec.md`「DataTable body cell internal」row | 「Body cell internal = Field family endAction(自動繼承)」「Field display 元件已對齊」 | ✅ aligned:2026-05-09 D-path retired — `getEditIndicator(colType)` parallel system 移除,indicator authority 移交 Field naked-display `showDisplayEndIcon` opt-in,cellEl 不再 render parallel indicator(見 data-table.tsx「D-path retired」註解);2026-07-08 A 案:cell-registry 預設不再傳(display 態零恆顯 icon,prop 留 opt-in 逃生門,見 field.spec L6 v16)| 2026-05-08 round 5 → 2026-05-09 resolved |
 | **Field naked variant state ring**(hover / focus / open / error)| `field-wrapper.tsx` cva compoundVariants(v13.3)+ `field.spec.md`「focus dominates」段 | 「SSOT 在 field-wrapper.tsx 三 compoundVariant — 改一處全 control + cell + variant 跟動」 | ✅ aligned(2026-05-08 D path canary 違反後 revert)| 2026-05-08 round 4(D path canary 違反 SSOT,已 revert `f0faab9`)|
 | **Row prefix/suffix slot**(`<ItemPrefix>` / `<ItemSuffix>`)| `patterns/element-anatomy/item-anatomy.spec.md:175+190` | 「row prefix/suffix slot 必走 patterns/element-anatomy L1 primitive」「`h-[1lh] shrink-0 flex items-center` 普世正確」 | ✅ aligned(hook `check_pattern_invariants.sh` C.4 enforce)| — |
 | **Inline action gap**(ItemInlineAction sibling spacing)| `patterns/element-anatomy/inline-action.spec.md`「多個 inline action 間距」段 | 「inline-action 跟 sibling gap 必 = `gap-2`(8px)」 | ✅ aligned(hook C.2 enforce)| — |
 | **Drag visual**(drop indicator / drag overlay)| `lib/drag-visual.ts`(2026-05-06 v14.5)+ `tree-view.spec.md:265` | 「TreeView 是 DS 內最早 codified 的 drag canonical,DataTable row drag + column reorder 都 inherit via drag-visual.ts SSOT module」 | ✅ aligned | — |
-| **Color tokens**(primitive vs semantic)| `tokens/color/color.spec.md`(架構流派定位)+ `tokens/color/semantic.css` | 「禁 primitive 色名作 utility,用 semantic alias」 | ✅ aligned(hook D.3 enforce)| — |
+| **Color tokens**(primitive vs semantic)| `tokens/color/color.spec.md`(架構流派定位)+ `tokens/color/semantic.css` | 「禁 primitive 色名作 utility,用 semantic alias」 | ✅ aligned(hook `check_naming_and_abstraction.sh` D.3 enforce)| — |
 | **Layout space**(region/element + 親疏三級)| `tokens/layoutSpace/layoutSpace.spec.md` v6(原 memory `feedback_layout_v6_canonical.md` 已 retire)| 「region/element + bounded/unbounded + 親疏三級」 | ✅ aligned(2026-05-01 flush variant retire)| 2026-05-01 |
 | **DataTable scroll**(3-region synced + cross-OS scrollbar)| `data-table.spec.md:245-251` | 「center body 用 native overflow-x-auto(非 ScrollArea),pinned column 三 region 同步」 | ✅ aligned(v15.13 interim CSS parity for Windows Bug H,deferred ScrollArea full migration)| 2026-04-30 / 2026-05-07 |
 | **Cell display vs edit content position**(picker offset)| `field.spec.md`「Layout Family 4」段 + `data-table.spec.md`「Body cell internal」row | 「Field control display + edit 共用同 wrapper geometry」 | ⚠ partial:DataTable cell 場景已對齊(D-path `showDisplayEndIcon` opt-in 走 Field naked-display);standalone `mode="display"` 仍 bare-span(documented deferral,見 select.tsx 檔頭 `@renderer-symmetry-allow`)| 2026-05-07~08 round 1-5 → 2026-05-09 D-path 部分解決 |
 | **Field state machine focus dominates**(v13.3)| `field-wrapper.tsx` cva compoundVariants + `field.spec.md`「focus dominates」段 + `check_field_family_invariants.sh` A.3 | 「focus dominates everything;naked 不寫平行 outline ring」 | ✅ aligned;hook A.3 enforce | 2026-05-06 v9-v13.3 5 round refinement |
 | **Solo dev workflow**(1 chat = 1 branch / Netlify gate / squash merge)| `feedback_solo_dev_workflow.md` + CLAUDE.md「Git solo-work canonical」 | 「1 chat = 1 working branch;Netlify preview = user gate;『push / OK』trigger 才 merge main」 | ✅ aligned(M28 + hook `check_solo_workflow.sh`)| 2026-05-08 M28 codify |
 | **Wrapper-vs-primitive schema unify**(SelectOption / MenuItemProps 等)| `SelectMenu/select-menu.tsx` SelectMenuOption + `Combobox/combobox.tsx` extends + `PeoplePicker/people-picker.tsx` extends | 「wrapper API schema 必 `extends primitive`,wrapper 內部 mapping 必 forward 全 primitive surface field(M30)」 | ✅ aligned(2026-05-10 Round 1 commit `561945b` Combobox extends + forward 全 field;PeoplePicker 對齊 + hook `check_wrapper_primitive_schema_drift.sh` BLOCKER)| 2026-05-10 M30 codify |
+| **空值顯示符號 + 分流**(empty value display)| `field-context.ts` `useFieldEmptyDisplay()`(分流 hook)+ `field-wrapper.tsx` `EMPTY_DISPLAY = '-'`(半形常數)+ `field-controls.spec.md`「null / undefined 值」段 | 「符號 = 半形 hyphen `-`(U+002D),**非**全形 em dash;`surface==='table-cell' && isEditable ? '' : '-'`;可編輯 form edit 走 native placeholder。全 Field family 空值渲染必經 hook,consumer 禁直引 `EMPTY_DISPLAY`」 | ✅ aligned(2026-07-08 user 拍板半形;hook `check_field_family_invariants.sh` A.6 BLOCKER — 禁非 owner 直引常數 + 禁 hardcode 全形 em dash;DescriptionList / ProfileCard / FileViewer consumer 同步半形)| 2026-07-08 user directive |
 
 ## How to maintain
 
 - 新 interface 第一次 surface → 加進本 index
 - 新 divergence 發現 → 加 row + 標 ⚠ DRIFT
 - Drift 解決 → 改 ✅ aligned
-- 重大 round 結束 → 跑 audit Dim 38 反 grep verify
+- 重大 round 結束 → 逐 row 反 grep owner spec/code 驗仍一致(`/deep-audit-cross-codex` Phase A 必讀清單已含本檔,見 `phase-a-workflow.md:15`;無專屬 audit dim 機械化)
 
 ## 與 hook 關係
 
-- `check_ds_anchor_preflight.sh`(live,soft warn)— 偵測編 Field / DataTable / patterns code 時 stderr 提醒「先 grep ssot-index.md」
+- `check_ds_anchor_preflight.sh`(live,P0 BLOCKER exit 2,2026-07-07 升級)— 偵測 production tsx / apps consumer 內 DS primitive wrap 而無 canonical read trace → block;bypass `CLAUDE_BYPASS_DS_ANCHOR=1`(audit-logged)
 - `check_field_family_invariants.sh` A.3 — 機械化 enforce v13.3 SSOT
 - `check_pattern_invariants.sh` C.4 — 機械化 enforce row slot SSOT
 - `check_canonical_propagation.sh` E.2 — 機械化 enforce L3 primitive import

package/ds-canonical/references/story-baseline-registry.json

@@ -1,7 +1,6 @@
 {
-  "$schema": "./story-baseline-registry.schema.json",
   "_meta": {
-    "purpose": "Anti-drift registry for stories wrap既有 primitive(Sidebar / ChromeHeader / DataTable / Dialog / Sheet / Popover)— machine-readable canonical archetype。Hook `check_story_invariants.sh R8` reads this(not grep spec.md / not憑 Claude judgment)to enforce nearest same-purpose canonical usage(per codex Layer B D4 2026-05-20)。新增 primitive entry 必先寫 baseline + helper list + antiPatterns regex + variantRules。",
+    "purpose": "Anti-drift registry for stories wrap既有 primitive(Sidebar / ChromeHeader / DataTable / Dialog / Sheet / Popover)— machine-readable canonical archetype。Hook `check_story_invariants.sh R8` reads this(not grep spec.md / not憑 Claude judgment)to enforce nearest same-purpose canonical usage(per codex Layer B D4 2026-05-20)。新增 primitive entry 必先寫 baseline + helper list + antiPatterns regex + buttonCanonical。",
     "owner": ".claude/references/story-baseline-registry.json",
     "consumed_by": [
       ".claude/hooks/check_story_invariants.sh#R8(story_archetype_registry)",
@@ -83,6 +82,13 @@
           "severity": "warn",
           "rationale": "DataTable toolbar filter/sort button 必包在 Popover 內,內含真 DataTableFilterPanel / DataTableSortManager primitive(2026-07-04 dim 54:原 PCRE lookahead 在 ERE grep exit 2 永不 fire → 改兩段式 regex+unlessRegex)",
           "unlessRegex": "DataTableFilterPanel|DataTableSortManager"
+        },
+        {
+          "id": "datatable-always-edit-cell",
+          "regex": "cell:[^;]{0,160}<(DS\\.)?(Select|Combobox|PeoplePicker|DatePicker|TimePicker)\\b",
+          "unlessRegex": "onCellCommit|editable|mode=[\"']display",
+          "severity": "block",
+          "rationale": "cell: 直接渲染恆-edit 控件 = display 態渲染 edit chrome,違 data-table.spec.md:373 indicator A 案(display 零恆顯 + hover outline + meta.editable/onCellCommit)。custom cell 元件包裹的同違規 regex 看不進去 → 由 product-ui-audit judgment 兜底(failure-class registry always-edit-cell)"
         }
       ]
     },

package/ds-canonical/references/structural-token-retention.md

@@ -1,6 +1,6 @@
-# 結構性保留 token canonical(audit Dim 48 SSOT,2026-05-17 codified)
+# 結構性保留 token canonical(2026-05-17 codified;2026-07-10 對齊現制)
 
-某些 token 看起來「0 consumer」但屬**結構性保留**,不該 retire。**Sub-agent 跑 audit Dim 48 抓 0-consumer candidate 時必先過此 table,屬下列 6 類則 retract finding(不列為 violation)**。
+某些 token 看起來「0 consumer」但屬**結構性保留**,不該 retire。**現制**:Dim 48 = `scripts/audit-orphan-tokens.mjs --check`(2026-05-21 升級 chain deterministic script,structural-keep 分類器內建於 script,分類 SSOT → `tokens/orphan-tokens.spec.md`);**本檔 6 類 table 供全 dim sub-agent findings cross-check**(design-system-audit SKILL dispatch template triple-verify layer (c)),屬下列 6 類則 retract finding(不列為 violation)。
 
 ## 6 類結構性保留(對齊 Radix Color / Atlassian @atlaskit/tokens / Polaris polaris-tokens 三家共識)
 
@@ -18,13 +18,10 @@
 - 真實 0 consumer + **0 forward-looking reservation** + **0 dark-mode pair** + **0 palette completeness role**
 - 對齊 Radix Color / Atlassian `@atlaskit/tokens` / Polaris polaris-tokens 三家 retire 政策共識
 
-## Sub-agent 強制 triple-verify before propose retire
+## Retire 判定與 findings cross-check(現制 pointer)
 
-對每 candidate retire token,sub-agent 必 verify 3 layer:
-
-1. **`grep -rn var(--TOKEN_NAME)` DS-wide**(含 `packages/design-system/src/**` + `src/app/**` + `src/explorations/**`)— 抓 direct `var()` consumption
-2. **`grep -rn "TOKEN_NAME"` 排除 css/spec.md 定義 + template literal usage**(eg. `\`h-table-row-${size}\``)— 抓動態 utility class generation
-3. **Cross-check 上 6 類**:屬任一 → retract finding,**不列 retire candidate**
+- **Retire 判定**走 `scripts/audit-orphan-tokens.mjs --check`(5 消費路徑:`var()` direct / `@theme inline` bridge / `@utility` body / Tailwind class-name match / JS literal mirror;+ structural-keep 分類器 + baseline gate)— 取代舊 sub-agent 手動 grep 協議。
+- **Sub-agent findings 通用 triple-verify**(file:line cite / spec 禁止事項 / canonical cross-check 含本檔 6 類)見 `design-system-audit/SKILL.md` sub-agent dispatch template。
 
 **任一 layer 顯示「有 consumer / 屬結構保留」→ 從 retire report 中拿掉**(不要送 user 拍板浪費時間)。
 
@@ -39,4 +36,4 @@ User verbatim 2026-05-17:「每次抓出的問題你他媽要給我基於我們
 ## 引用
 
 - `tokens/color/color.spec.md`「結構性保留 token canonical」(pointer 段)
-- `.claude/skills/design-system-audit/SKILL.md` Dim 48(sub-agent prompt 必 cite 本檔)
+- `.claude/skills/design-system-audit/SKILL.md:305` sub-agent dispatch template triple-verify layer (c)(全 dim findings cross-check 通用;Dim 48 本體已改走 `audit-orphan-tokens.mjs`,分類 SSOT = `tokens/orphan-tokens.spec.md`)

package/ds-canonical/rules/meta-patterns.md

@@ -33,7 +33,7 @@
 
 **Marginal merge candidate**(留 user 後續 explicit approve):`codify-principle` + `codify-corrections` 都產 5-layer artifact,trigger 不同(live propose vs batch log)— 可合 `codify` 一統 skill。**不執行原因**:codex Q-13 sharp-rule preference + auto-mode 不 destructive 風險 + 兩 skill SKILL.md 各自 250 lines budget 內。User 後續 invoke `/knowledge-prune` 並 explicit approve 才動。
 
-**RFC**:Anthropic「~10 sweet spot」是 typical CRUD app benchmark;DS governance complexity(31 active M-rules + 全 dim audit per design-system-audit SSOT + dual-track codex collab + 8-home 治理)justified higher skill count。每 skill 都過 knowledge-prune retire rule(6 月 fire 或 rare-event 豁免)。
+**RFC**:Anthropic「~10 sweet spot」是 typical CRUD app benchmark;DS governance complexity(31 active M-rules + 全 dim audit per design-system-audit SSOT + dual-track codex collab + 8-home 治理)justified higher skill count。每 skill 都過 knowledge-prune retire rule(3 月 invoke 或 rare-event 豁免;hooks 才是 6 月 fire,SSOT → knowledge-prune/SKILL.md)。
 
 
 | # | Meta-Principle | 能吸收的 bug 類型(舉例,非窮舉) |
@@ -47,7 +47,7 @@
 | **M7** | **新 protocol / skill / rule 寫完,必反向 cross-check 既有 Meta-Principle 是否該套用**。尤其:consistency-class 的 protocol 必走「一致性類稽核必先全掃再判」(本章節);audit skill 必加「Self-improvement capture」Phase F step;Rule 觸及「canonical」「SSOT」「rationale」keyword → 必明示 substantive vs 表達層分權。**+ Sub-rule M34 (folded 2026-05-22)**:Hook detection regex 必對齊 spec wording 廣度。Triple test before merge new hook — (1) Spec rule wording 是「一般類別」(broad)還是「特定 keyword」(narrow)?(2) Hook regex 匹配「一般類別」還是只「特定 keyword subset」?(3) Spec broad + Hook narrow → **gap**,必擴 hook regex(unicode pattern / negative-list approach / counter-example DS-wide scan)。Propose 新 hook 必先寫 3-column table:`Spec wording` / `Hook regex` / `Gap?(broad-vs-narrow)`。 | principle-audit-protocol v1 漏套既有 Phase 0 全掃;2026-05-17 story name `照妳` `決策N` 等中英人話 detection regex 漏 |
 | **M8** | **訂立 / 修改 cross-component canonical 前必 world-class benchmark**。任何 predicate / decision tree / taxonomy 類 spec,**必先 grep 至少 3 家世界級 DS**(Polaris / Material / Atlassian / Ant Design / Carbon / Apple HIG / VS Code / Figma 等)列對照表,再訂 rule。**絕對禁止**憑直覺開場寫 predicate,user 問才補對照。每個 category / variant / case 必附世界級 reference(實作名或 API 指向),沒有對照的 rule 視同未成熟,走 Checkpoint 3。 | item-anatomy Inline Action 疊代 4 次才有世界級對照 |
 | **M9** | **Predicate / decision tree 寫完,present 前必 4 題自測**,防 membership drift。(a) 每 example 回跑決策樹;(b) cap / constraint cross-check;(c) 每 example 對 ≥3 家 world-class DS;(d) 每 category ≥1 example。任一題失敗 → 重收斂,**禁止 present**。 | Cat 1 IA 塞 endAction / FileItem sm 違 ≤24 cap |
-| **M10** | **Proactive exhaustive scan**:canonical migration 完成前禁止只改「直覺相關」元件;final report 前禁止省略「我知道但沒講」的 tech debt。**Mechanical 落地**:每 fix commit 後 `/scan-similar-bugs` skill 強制 grep DS-wide。 | dismiss migration 漏 FileViewer / 7 題 silent tech debt user 一次炸 |
+| **M10** | **Proactive exhaustive scan**:canonical migration 完成前禁止只改「直覺相關」元件;final report 前禁止省略「我知道但沒講」的 tech debt。**Mechanical 落地**:batch-end(session ≥2 fix commits)跑一次 `/scan-similar-bugs` grep DS-wide(2026-05-12 per-fix → batch-end 重構);`session_start_governance_check.sh` Check 6 偵測 24h 內 fix commit 漏跑 → soft 提醒。 | dismiss migration 漏 FileViewer / 7 題 silent tech debt user 一次炸 |
 | **M11** | **User-perspective interactive state walk**:改完 UI 後 present 前必親自走 7 題 self-test(static / hover / focus-visible / active / keyboard / 範例真實性 / CSS 對稱)。每 UI 改動未跑 7 題就 commit = 違反。 | ListBody 修完 user 連抓 5 波 |
 | **M12** | **Binary strict rule + fix-time root-invariant pre-question(「必 X」/「禁 Y」/ bug fix)前必 benchmark + invariant test**。3 題自測:≥3 家世界級一致 / counter-example scan / root invariant vs surface observation。震盪症狀(A→not A→A)= meta invariant 沒抓到,**停下 present**。**Fix-time 延伸**(2026-05-12 absorbs 原 M32(b)):visual / behavior bug 改前必 inline 答 3 題 — Q1「root invariant 是什麼?」Q2「symptom 在哪 layer?」Q3「fix 是 root-layer 還是 surface-layer?」。surface-only 修(改 symptom 不動 invariant)違反。對齊 5-whys / Toyota TPS / Linux kernel「fix the root not symptom」canonical。 | hover bg 震盪 4 次(bg-edge vs content-padding invariant);2026-05-12 cell-align fix surface-modify Field padding 不動 inline-flex `!h-full` root invariant |
 | **M13** | **User 第 2 次提相關問題 → 自動截圖 verify**。當 user 就同一視覺 / 行為主題第 2 次問 / 糾正,AI 必 invoke 截圖 verify(`visual-audit.mjs --scope=component:XXX`)。第 3 次才 verify = 違反。**Corollary**:user 指定「所有 X 都要 Y」,同 session 全部做完 + 建 hook 防線。 | avatar-NameCard migration 分批拖延 user 第 2 次催才全改 |
@@ -55,11 +55,11 @@
 | **M15** | **Product UI flow 必須 visual-audit coverable**。任何 stakeholder-facing flow 必含 OpenSnapshot 類 stories(`defaultOpen` / `useState(true)` / `play()`)。禁留「需真人點擊才能看到的 state」未截圖。 | Sheet / FileViewer 只截 trigger 缺 OpenSnapshot |
 | **M16** | **訂 standalone card/pill 容器 canonical 必同步訂 multi-instance gap canonical**(`@watch` 2026-05-22)。3 條公式:同類 standalone → 必 gap;同類 permanent flush → 0 gap OK;混合語言 → 必取最保守 gap。Hook `check_item_list_gap.sh` 預警 + audit dim verify。**@watch 2026-05-22**:單 bug source(FileItem rich/compact)— 1 quarter 觀察是否 absorb ≥3 同類 bug,否則 demote 為 item-anatomy.spec.md 子規則。 | FileItem rich card + compact bg 連續相連 |
 | **M17** | **SSOT 必可傳播**(非僅 markdown)。同值 / 同公式 hard-code 在 3+ consumer = 必抽成 token / primitive / utility class。**兩層 SSOT 架構**:底層 token(值可調)+ primitive(結構封裝 + 消費 token);世界級對照 Material/Carbon/Ant/Polaris 共識。 | mt-0.5 canonical 13 consumer hard-code 假 SSOT |
-| **M18** | **Propose-time 6 題自檢 gate**(2026-05-18 升 4→6 加 Q0 + Q5)。列 option / 建議前必 inline 跑 **Q0 Pre-ASK self-verify problem 真存在**(2026-05-18 加,absorbs Sheet/inline-action/SurfaceBody 三題誤判)/ Q1 M8 benchmark / Q1' M23 DS canonical / Q2 M17 SSOT / Q3 Rule-of-3 / Q4 M10 下游吸收 / Q5 Issue 100% mapped。Reject 不列出,通過寫 6-Q 證據表。**Q0 強制動作**:propose 給 user 拍板前必 grep DS-wide + Read 相關 spec.md + Read consumer usage 確認 problem 真存在,沒 grep 就斷言「N 元件缺 X / 該 migrate」= 撤回 propose。SSOT → `.claude/skills/propose-options/SKILL.md`。Hook `check_propose_pre_grep_verify.sh` 機械強制 Q0。 | 2026-05-18:Sheet 補 / 5 元件 inline-action migrate / 5 元件 SurfaceBody migrate 三題全錯誤 propose 給 user 拍板,grep 後 0 個真 gap(Sheet 已完整 / 6 元件全消費 inline action / Dialog 走 ScrollArea canonical 不該用 SurfaceBody / HoverCard 是 behavior primitive / DatePicker TimePicker 是專用 layout / Sidebar 是 chrome 不是浮層)。User verbatim「不是老早就跟你說過要我決策前請先基於我們所有的檔案包括設計原則包括 ssot 包括所有實作代碼,自主自動驗證這些問題是否真的是問題」 |
+| **M18** | **Propose-time 6 題自檢 gate**(2026-05-18 升 4→6 加 Q0 + Q5)。列 option / 建議前必 inline 跑 **Q0 Pre-ASK self-verify problem 真存在**(2026-05-18 加,absorbs Sheet/inline-action/SurfaceBody 三題誤判)/ Q1 M8 benchmark / Q1' M23 DS canonical / Q2 M17 SSOT / Q3 Rule-of-3 / Q4 M10 下游吸收 / Q5 Issue 100% mapped。Reject 不列出,通過寫 6-Q 證據表。**Q0 強制動作**:propose 給 user 拍板前必 grep DS-wide + Read 相關 spec.md + Read consumer usage 確認 problem 真存在,沒 grep 就斷言「N 元件缺 X / 該 migrate」= 撤回 propose。SSOT → `.claude/skills/propose-options/SKILL.md`。Hook `check_propose_pre_grep_verify.sh` 機械化警告 Q0(P1 soft,scope 僅 planning/reports/handoff md 的 cite-presence;chat reply propose 靠 discipline)。 | 2026-05-18:Sheet 補 / 5 元件 inline-action migrate / 5 元件 SurfaceBody migrate 三題全錯誤 propose 給 user 拍板,grep 後 0 個真 gap(Sheet 已完整 / 6 元件全消費 inline action / Dialog 走 ScrollArea canonical 不該用 SurfaceBody / HoverCard 是 behavior primitive / DatePicker TimePicker 是專用 layout / Sidebar 是 chrome 不是浮層)。User verbatim「不是老早就跟你說過要我決策前請先基於我們所有的檔案包括設計原則包括 ssot 包括所有實作代碼,自主自動驗證這些問題是否真的是問題」 |
 | **M19** | **Trigger phrase auto-pipeline**。「確保 / 一定 / 永不漂移 / ensure / always」trigger → 自動 5-layer ≥ 3 層落地 + M8 + M17 + M10。Substantive 走 STOP。SSOT → `.claude/skills/ensure-canonical/SKILL.md`。 | story splitting 2026-04-26 user 第 N 次強調才落地 |
-| **M20** | **AI 自問 best-practice + 自動 self-improve**(不靠 user 提醒)。Stop hook `rule_infra_best_practice_score`(R5 in `stop_passive_logging.sh`,2026-05-13 folded from retired `stop_meta_self_audit.sh`)每 turn 跑 score → < 80 / regression ≥ 5 log to `score-history.jsonl`;next-turn UserPromptSubmit `inject_pending_self_audit.sh` 注入 BLOCKER prompt。**Threshold 數值 SSOT**:`session_start_governance_check.sh`(檔頭「Checks + thresholds」註解 + Check 7)+ CLAUDE.md `# 治理 canonical` 行數預算表;本 M-rule 不重述具體 cap,避免多 home 漂移(2026-05-22 prune codify per Rule-of-3 violation fix)。**+ Sub-rule M33 (folded 2026-05-22)**:Stop hook overfire → AI conservative-defer 反 pattern。同 stop hook fire ≥ 5 次 within session → AI 自動 hedge / 撤回 claim / 「下個 session」defer **可做工作**。真理由 vs 偽 prereq 區辨 — (a)真 prereq 缺(cross-frame test fixture 等)= 具體 deliverable need;(b)偽 prereq(「context budget」「省工」「下個 session」)= conditioned hedge,user 反覆催 = 真理由不存在。**Rule**:AI reply 含「下個 session」「context budget」「省工」keyword 且前 1 turn user 已拍板「全部做完」/「繼續」/「沒理由不做」→ BLOCKER。對齊 Atlassian「stop using vague defer」+ Linux kernel patch review。 | user 10 次問「best-practice 嗎」直到外部 benchmark 確認真 gap;2026-05-13 claim-verify-gap stop hook fire 12+ 次 → 我每 reply 自動 hedge → user 多次糾正「沒理由不做」 |
-| **M21** | **新元件 / 新 sub-component 抽象前必過 prop variant test**。當新元件名 = `<Existing>+suffix`(Time / Range / Color / Light / Dark / Filled / Outline / Compact / Rich)→ 強烈 signal 應為 prop variant on `<Existing>`。3-test 通過才能分(全失敗 → prop):(1) `<Existing>` 加 prop 無法達成同 DOM/behavior?(2) ≥3 家 world-class DS 用分離元件而非 prop(必 cite source)?(3) value 結構或 contract 真的不同(如 Range = [start, end])?Hook check_premature_abstraction(retired/未實作;mindset enforcement)。 | DateTimePicker 從 DatePicker 拆 → 撤回合併 `<DatePicker showTime>`(2026-05-02);DataTableFilterPanel 5-file → 撤回 sub-file pattern |
-| **M22** | **Benchmark claim 必附 inline source citation**(不可憑印象)。寫 spec / tsx 含「Ant / Material / Polaris / Atlassian / Carbon / shadcn / Radix」等 world-class DS claim,必同段附:(a) inline URL(domain 對應 DS 官網 / GitHub source);(b) GitHub source path + line ref `#L42`;(c) screenshot reference `snapshots/...`;(d) 顯式撤回 `@benchmark-unverified`。Hook `check_benchmark_citation.sh` 機械化警告(P1 soft)。每次 implement 前跑 WebFetch 取真 source,不憑印象解碼。 | claim「Ant showTime range = 2 calendars」憑印象,實證 source code `multiplePanel = false` = 1 calendar(2026-05-02 鬼話事件)|
+| **M20** | **AI 自問 best-practice + 自動 self-improve**(不靠 user 提醒)。Stop hook `rule_infra_best_practice_score`(R5 in `stop_passive_logging.sh`,2026-05-13 folded from retired `stop_meta_self_audit.sh`)每 turn 跑 score → < 80 / regression ≥ 5 log to `score-history.jsonl`;next-turn UserPromptSubmit `inject_pending_self_audit.sh` 注入 BLOCKER prompt。**Threshold 數值 SSOT**:`session_start_governance_check.sh`(檔頭「Checks + thresholds」註解 + Check 7)+ CLAUDE.md `# 治理 canonical` 行數預算表;本 M-rule 不重述具體 cap,避免多 home 漂移(2026-05-22 prune codify per Rule-of-3 violation fix)。**+ Sub-rule M33 (folded 2026-05-22)**:Stop hook overfire → AI conservative-defer 反 pattern。同 stop hook fire ≥ 5 次 within session → AI 自動 hedge / 撤回 claim / 「下個 session」defer **可做工作**。真理由 vs 偽 prereq 區辨 — (a)真 prereq 缺(cross-frame test fixture 等)= 具體 deliverable need;(b)偽 prereq(「context budget」「省工」「下個 session」)= conditioned hedge,user 反覆催 = 真理由不存在。**Rule**:AI reply 含「下個 session」「context budget」「省工」keyword 且前 1 turn user 已拍板「全部做完」/「繼續」/「沒理由不做」→ WARN + next-turn inject(stop_self_audit.sh Mechanism 4)。對齊 Atlassian「stop using vague defer」+ Linux kernel patch review。 | user 10 次問「best-practice 嗎」直到外部 benchmark 確認真 gap;2026-05-13 claim-verify-gap stop hook fire 12+ 次 → 我每 reply 自動 hedge → user 多次糾正「沒理由不做」 |
+| **M21** | **新元件 / 新 sub-component 抽象前必過 prop variant test**。當新元件名 = `<Existing>+suffix`(Time / Range / Color / Light / Dark / Filled / Outline / Compact / Rich)→ 強烈 signal 應為 prop variant on `<Existing>`。3-test 通過才能分(全失敗 → prop):(1) `<Existing>` 加 prop 無法達成同 DOM/behavior?(2) ≥3 家 world-class DS 用分離元件而非 prop(必 cite source)?(3) value 結構或 contract 真的不同(如 Range = [start, end])?Hook:folded 入 `check_naming_and_abstraction.sh` D.1(P0 BLOCK,2026-05-08 cluster D consolidation;escape @separate-component-rationale)。 | DateTimePicker 從 DatePicker 拆 → 撤回合併 `<DatePicker showTime>`(2026-05-02);DataTableFilterPanel 5-file → 撤回 sub-file pattern |
+| **M22** | **Benchmark claim 必附 inline source citation**(不可憑印象)。寫 spec / tsx 含「Ant / Material / Polaris / Atlassian / Carbon / shadcn / Radix」等 world-class DS claim,必同段附:(a) inline URL(domain 對應 DS 官網 / GitHub source);(b) GitHub source path + line ref `#L42`;(c) screenshot reference `snapshots/...`;(d) 顯式撤回 `@benchmark-unverified`。Hook `check_benchmark_citation.sh` 機械強制(P0 BLOCKER exit 2,2026-07-07 升級;escape @benchmark-unverified 逐句 / @benchmark-citation-allow / @benchmark-unverified-blanket 檔級)。每次 implement 前跑 WebFetch 取真 source,不憑印象解碼。 | claim「Ant showTime range = 2 calendars」憑印象,實證 source code `multiplePanel = false` = 1 calendar(2026-05-02 鬼話事件)|
 | **M23** | **DS 內既有 canonical 優先於外部 benchmark**。寫 visual decision(color / size / spacing / typography / state)/ prop name namespace 前必先 grep DS 既有 codified token / variant / pattern / prop;命中 → 必對齊;沒命中 → 才引 world-class + 同步補 canonical。**禁止**:外部 benchmark(M22 cite OK)直接覆蓋 DS 內已有 canonical。Mindset #2「優先消費既有」的 visual layer。判斷流程:(a) grep 該屬性 / prop 既有 token/variant/usage;(b) 命中 canonical?有 → 用,沒 → 走 M22 cite 然後 codify;(c) **prop name conflict 子規則**(former M27,2026-05-15 collapsed):外部 framework prop name(TanStack `size` / Radix `disabled` / dnd-kit attrs 等)跟 DS 既有 prop 同字不同義 → wrap-and-rename(DS-internal naming + pre-process map);(d) **nearest same-purpose canonical wins 子規則**(former M35,2026-05-22 folded):寫 stories / UI composition wrap 既有 primitive 前必先 grep + Read primitive 的「完整佈局」production canonical story(eg. `sidebar.stories.tsx#IconCollapse`)抄 archetype 結構 / helper / variant — 不准憑記憶寫 simplified mock。**Cite 存在 ≠ consume 落實**(codex 2026-05-20 verdict)。最相近同目的 canonical 用法 > 泛用 component spec / 寬鬆 pattern wording。**手刻浮層 / chrome header 子規則(2026-06-04 加)**:做「像 popover / dialog 的浮層面板」前必先 grep + Read `patterns/overlay-surface`(SurfaceHeader/Body/Footer)+ `Popover`(chrome token + PopoverHeader/PopoverTitle)SSOT;**手刻 `<div px-loose border-b border-divider>` header 或 `<div rounded bg-surface shadow-elevation>` 殼 = drift**,必消費 primitive。Registry SSOT `.claude/references/story-baseline-registry.json` + hook `check_story_invariants.sh R8 story_archetype_registry` **+ R9 hand_craft_overlay_header(零誤判 px-loose+border-divider 簽名,BLOCKER)**。**forcing-function 教訓**:M1/M23(d) 是 mindset,但 mindset 沒有完整 hook 兜底 = 紙老虎(會憑印象手刻);新場景若既有 hook 無 antiPattern 覆蓋 → 補 hook rule 才算落地。 | 2026-05-03 chevron color:DS `text-foreground` (icon-only Button neutral-9 85%) vs 我憑「Ant 5 家 muted」覆蓋 → 自開新 tier 違反一致設計語言。2026-05-06 column width:DS 49+ 處 `size: 'sm'\|'md'\|'lg'` density vs TanStack `size: 280` px = 同 prop 不同義 → `meta.width` wrap。2026-05-20 AppShell-vs-Sidebar drift:simplified mock + jargon + wrong variant + 不消費 primitive props。**2026-06-04 upload-manager 面板手刻 header + 殼**(`py-2`≠`py-tight` / `rounded-md`≠`lg` / `border-divider`≠`border` / `bg-surface`≠`raised`),既有 3 道網全漏(R1-C 要 absolute+dismiss / `_chrome_header_handcraft` skip stories / R7-R8 只比已註冊 primitive 名)→ adversarial workflow 抓 + 加 R9 補洞。Hook `check_datatable_invariants.sh(r2 folded,2026-06-11)` + `check_story_invariants.sh R8/R9` |
 | **M24** | **State 顯著性 precedence:disabled > muted > emphasis**。元件在 disabled state 時,內部所有文字載體(label / value / placeholder / icon)統一切 disabled token(`text-fg-disabled` neutral-6),**不**繼續 muted token(`text-fg-muted` neutral-7)。muted 是裝飾,disabled 是語意 state — state 勝 emphasis。同理:error / warning state 內 placeholder 應對應 state token。Hook `check_field_family_invariants.sh` A.4(原 check_disabled_placeholder_color folded,live P1 stderr)。 | 2026-05-04 5+ violation:`bareInputStyles` 永遠 muted / `select.tsx` 3 處 plain&tag empty 不分 mode / `textarea.tsx` 同;Input.tsx 唯一做對。User 5+ 次糾正才 codify |
 | **M25** | **Layered chain invariant 必整鏈 forward(viewport-aware overlay scroll 範例)**。Overlay surface(Popover / HoverCard / Dialog / Sheet)的 viewport-aware scroll 機制要求 root → SurfaceBody 之間**所有中間 wrapper 都 forward `flex flex-col h-full`**;任何中間 div 沒 forward → SurfaceBody flex-1 失效 → body 不 scroll。同類 chain pattern:density 透傳 / fieldCtx 鏈 / theme subtree(M3 portal 逃逸對偶)。Hook `check_pattern_invariants.sh` C.1(原 check_overlay_panel_scroll_chain folded,live P1 WARN)。 | 2026-05-04:Filter / Sort panel root `<div w-[640px]>` 無 flex-col → user 縮 viewport 時 body 不 scroll。NameCard 因自設 max-h flex-col 才繞過(無中間 wrapper) |
@@ -67,11 +67,11 @@
 <!-- M27 retired 2026-05-15(per /knowledge-prune D3 audit):self-flagged「M23 子規則」 → collapsed into M23 sub-bullet (c) "framework prop name namespace conflict"。Original case (TanStack size vs DS density) + hook `check_datatable_invariants.sh(r2 folded,2026-06-11)` retained 在 M23 children。 -->
 
 | **M28** | **Solo-work git ops 必先 grep canonical**(mindset #2 AI-ops 子規則)。AI 自己 git/branch/PR/merge ops(`git checkout -b` / `gh pr create` / `git push origin main` / `mcp__github__create_pull_request` / `mcp__github__merge_pull_request`)前必 grep `.claude/memory/feedback_solo_dev_workflow.md` + CLAUDE.md `# Git solo-work canonical`,**不憑直覺反射開新 branch / 開 PR / 自決 merge**。Solo work 鐵律:1 chat = 1 working branch / no PR / 等 user「push」 trigger 才 merge main。Hook `check_solo_workflow.sh` 機械化攔(R1 第 2 個 branch / R2 PR creation / R3 merge 無 user trigger keyword)+ override `CLAUDE_BYPASS_SOLO_WORKFLOW=1` audit-logged。 | 2026-05-08:同 session AI 開 5 branch + 2 PR (#7 #8),user 第 3 次糾正才升 mechanical;memory file 2026-05-04 codified 但 markdown 級 + AI 沒 grep 直接憑印象 = mindset #2 違反 |
-| **M29** | **DS Anchor Preflight invariant — 視覺 / 結構 propose 前必 grep `*.spec.md` 找 owner SSOT**。動 component / pattern / token 視覺結構前,**必先**:(a) `rg <touched component> + <behavior keyword>` in `packages/design-system/src/**/*.spec.md` (b) 出 **3-column owner table**(`candidate owner spec` / `canonical sentence/table row` / `conflicting code/comment if any`)(c) 若 spec ≠ code → STOP 寫 RFC 不直接 propose implementation。沒 3-column = anti-pattern,提案不被接受。SSOT index `.claude/references/ssot-index.md`(high-risk interface owner mapping)Step 0.1 先查再 grep verify。Hook `check_ds_anchor_preflight.sh` soft warn。codex-collab/SKILL.md Step 0.1 mandatory pre-grep。對齊 Carbon「design spec is source of truth」+ Atlassian「system-wide coordination first」。 | 2026-05-08:Claude+Codex 連 5 round 跳過 spec anchor pre-grep,直覺加 primitive(D path / Path A);user 抓「為何沒研讀設計原則」 |
+| **M29** | **DS Anchor Preflight invariant — 視覺 / 結構 propose 前必 grep `*.spec.md` 找 owner SSOT**。動 component / pattern / token 視覺結構前,**必先**:(a) `rg <touched component> + <behavior keyword>` in `packages/design-system/src/**/*.spec.md` (b) 出 **3-column owner table**(`candidate owner spec` / `canonical sentence/table row` / `conflicting code/comment if any`)(c) 若 spec ≠ code → STOP 寫 RFC 不直接 propose implementation。沒 3-column = anti-pattern,提案不被接受。SSOT index `.claude/references/ssot-index.md`(high-risk interface owner mapping)Step 0.1 先查再 grep verify。Hook `check_ds_anchor_preflight.sh` P0 BLOCKER(exit 2,2026-07-07 升級;bypass CLAUDE_BYPASS_DS_ANCHOR=1 audit-logged)。codex-collab/SKILL.md Step 0.1 mandatory pre-grep。對齊 Carbon「design spec is source of truth」+ Atlassian「system-wide coordination first」。 | 2026-05-08:Claude+Codex 連 5 round 跳過 spec anchor pre-grep,直覺加 primitive(D path / Path A);user 抓「為何沒研讀設計原則」 |
 | **M30** | **Wrapper-vs-primitive schema unify invariant — wrapper API option / config schema 必 `extends` primitive SSOT,且 wrapper 內部轉換 mapping 必 forward 全 primitive surface field**。Primitive(`SelectMenuOption` / `MenuItemProps` / `ItemAnatomyProps` 等)宣告 SSOT 後,所有 wrapper(`Select.SelectOption` / `Combobox.SelectOption` / `PeoplePicker` 等)若有同類 schema,(a) 用 TypeScript `extends primitive` 機械繼承,**不可平行 declare** weak schema(同名 / 部分欄位)(b) wrapper 內部 `xxxToYyy()` mapping 必 forward 全 primitive surface field(不可只 forward `value` + `label`,silently drop avatar / description / disabled 等)(c) wrapper-only field 加在 `extends body`(不污染 primitive)。Hook `check_wrapper_primitive_schema_drift.sh` 機械強制(P0 BLOCKER):grep `export interface .*Option \{` cross components/,同名 ≥ 2 處且未 `extends` primitive → BLOCK。對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown wrapper-vs-primitive schema-extension idiom。 | 2026-05-10 PeoplePicker multi-mode 漏 avatar:`Combobox.SelectOption = { value, label }` weak schema(跟 `Select.SelectOption` 同名不同 fields)+ `Combobox.menuOptions` mapping 只 forward 2 fields → dropdown rows 永遠純文字。user 抓「為什麼之前會把 people picker 改壞 + 還有沒有其他東西也改壞」。Round 1 commit `561945b` 修(Combobox extends + forward 全 field)+ Round 2 codify。 |
 | **M32** | **Audit script 必 pixel-quantified verify ≠ attribute existence**(2026-05-12)。Audit 必驗 `rect.top / .left / .height` numeric pixel,**不**可只驗 `getAttribute('data-state')` / `class.includes(...)` = false-positive trap(DOM-pass ≠ visual-pass)。對齊 Material X-DataGrid / AG Grid playwright pixel snapshot / Polaris visual diff canonical。Hook `check_pixel_quantified_audit.sh` 機械強制(scans `getAttribute(` without paired `getBoundingClientRect(`)。**+ Sub-invariant(2026-05-30,doc-claim layer)**:story/anatomy/a11y/spec 的**文字宣稱 ≠ code 真實**——audit 必 adversarial **讀元件 .tsx +(其 wrap 的 Radix/cmdk/react-day-picker 等 lib)source**,逐句驗 keyboard map/ARIA role/focus 行為/prop 存在性/native-vs-custom;prose-skim「looks fine」= false-pass(prose-pass ≠ source-verified)。**「無 code 改動」≠ 可跳過**。`/deep-audit-cross-codex` A.1b + CP-A1b + report-validator F 機械強制。Anchor:2026-05-30 獨立 adversarial 抓 403 findings/64 單元/202 FALSE_CLAIM(前期 prose-skim story dim 全漏);prop-existence deterministic detector 因 passthrough over-flag 證實此類本質需 LLM 讀 source → 用 mandatory-dim + report-validator 保證真跑。**Split note**:原 mega 8 sub-invariants 拆 4 home — (b) fix-time root-invariant → M12 extension / (c)(d)(h) batch + parallel + claim-verify → `/bug-fix-rhythm` skill / (e) tool preflight(CLI binary 必跑 4-test discovery:which / npx / package.json / auth.json,禁短路「not installed」假警報)— 原 memory `feedback_tool_binary_preflight_sweep.md` 已 retire,invariant 一行收容於此 / (f) ship gate → CLAUDE.md `# 稽核 canonical` / (g) Layer marker → M31 + hook。git blame 2026-05-12 commit 留 audit trail。 | 2026-05-12 4 audit-vs-visual gap absorbed:cell-align / divider 2px / breadcrumb tooltip / row-alignment 全 audit「Δ=0 ALL PASS」但 user 抓視覺壞(詳 historical-bugs.md)。|
 | **M31** | **Adversarial dual-track 5-step canonical**(2026-05-10 user directive,verbatim quotes → `memory/feedback_codex_dual_track_synthesizer.md`)。**Step 0 入口 gate**:Claude 自試(grep / read source / cite DS canonical / WebFetch)完;啟 codex collab criteria 兩種:(a)自試卡 root cause / design tradeoff,OR(b)user 明確 keyword「跟 codex 討論 / 比稿 / 辯論 / dual-track」。**禁** auto-fire。**Step 1-5**(啟動後每題必過):(1)各自熟讀 spec/canonical/source(M29 anchor pre-grep + M23 既有 canonical 優先)(2)各自驗證(`tsc -b` + invariant + audit;codex `exec -s read-only`)— **不可只一方 verify**(M20)(3)各自視覺稽核(playwright + DOM inspect + pixel-level)(4)各自 3-column cite propose(`spec.md path:line / 引文 quote / reasoning`)— hand-wave 無 cite 自動撤回(5)整合「完美完整版本」**not pass-through**:agree → synthesize 補對方缺漏;disagree → cite battle,evidence stronger 勝。**禁**:pass-through codex propose(M28「被牽著走」);commit 無 3-column cite verdict。Hook `check_codex_collab_5step.sh` 機械化攔(P1 soft)。對齊 RFC 學術同儕審查 / Linux kernel-mailinglist cite source / Google ML eng-design-review。 | 2026-05-10 Issue 8 cell border:codex propose「Field edit border 透明」Claude pass-through ship → user「被 codex 牽著走」→ cite battle: `field-controls.spec.md` state machine + `item-anatomy.spec.md` cell 4-edge grid not in Field scope → 落地雙 owner;Issue 11 同 pattern cite battle ship retire + RFC backfill。 |
-<!-- M33 retired 2026-05-22(per /knowledge-prune deep audit Lens 1+2):folded into M20 as sub-rule「Stop hook overfire defer anti-pattern」。Original session context(2026-05-13 claim-verify-gap)+ hook `stop_self_audit.sh` P0 detection retained at M20 entry。Single-bug rule → 與 M20 同類「AI self-correction under feedback signals」合併。 -->
+<!-- M33 retired 2026-05-22(per /knowledge-prune deep audit Lens 1+2):folded into M20 as sub-rule「Stop hook overfire defer anti-pattern」。Original session context(2026-05-13 claim-verify-gap)+ hook `stop_self_audit.sh` P1 warn detection(Mechanism 4 + 次 turn auto-inject)retained at M20 entry。Single-bug rule → 與 M20 同類「AI self-correction under feedback signals」合併。 -->
 
 <!-- M34 retired 2026-05-22(per /knowledge-prune deep audit Lens 1+2):folded into M7 as sub-rule「Hook detection regex 必對齊 spec wording 廣度」。Original Triple test + 錨例(story-rules.md name field detection)retained at M7 entry。Single-bug rule + same-class「rule-authoring hygiene」與 M7 合併。 -->
 

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

@@ -31,11 +31,12 @@
 
 ## 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-final(宣告完成前)**:`stop_self_audit.sh` Mechanism 7(完整性宣告閘)BLOCKER — 宣告「全做完 / 全部完成」+ 本 turn 實質改動但**無全庫 stale-ref 掃描證據** → block。**觸發器 = 「宣告完成」本身,非等 user 問第二次**(2026-06-03 user-authorized,根治重複 failure)
-- **Pre-final(重大 / SSOT / 模型 / 跨多檔改動)**:除 M7 自掃外,**宣告完成前必跑「獨立對抗稽核」**(multi-agent Workflow,每路假設「還有 loose end」主動去找 + cite 證據)。**理由**:self-grep 系統性漏(self-assessment unreliable,對齊 `feedback_ai_ground_truth_unreliable_mechanical_primary`)+ 信任機械閘(preflight / R4 / hook BLOCKER)勝於自評。**小改 = M7 自掃即可**,不需對抗稽核(避免過度)。2026-06-03 user-authorized,根治「宣告做完 → user 問第 N 次 → 才補掃出 loose end」
-- **Pre-commit**:`scripts/audit-content-quality.mjs --check` + `scripts/extract-canonical-rules.mjs` 各 fail = block
+- **⚠️ 紀律條(非本段機械閘 — #39 2026-07-11 誠實標註,原誤置於機械段暗示有 hook 強制,實為零機械消費點)Pre-final(中型以上 = 跨 ≥3 檔 substantive、任何 canonical/SSOT/模型改動、或宣告「殘項/債歸零」類完整性 claim)**:除 M7 自掃外,**宣告完成前應跑「獨立對抗稽核」**(multi-agent Workflow,每路假設「還有 loose end」主動去找 + cite 證據)。**理由**:self-grep 系統性漏(self-assessment unreliable,對齊 `feedback_ai_ground_truth_unreliable_mechanical_primary`)+ 信任機械閘(preflight / R4 / hook BLOCKER)勝於自評。**小改 = M7 自掃即可**,不需對抗稽核(避免過度)。2026-06-03 user-authorized。
+  **為何不機械化(#39 決策記錄)**:硬做成 BLOCKER 會**自我 brick** —— subagent 額度耗盡時無法 dispatch Workflow,則每個中型以上「宣告完成」都被擋(含修此條的 turn 本身);即使有額度,強制每次 ≥3 檔改動都 dispatch adversarial Workflow 亦過重。故本條**保持紀律**,不進 stop_self_audit BLOCKER。**未來可選**:額度穩定後加「completion claim + ≥3 檔 diff + transcript 無 Workflow/Agent dispatch → **soft WARN**(非 block)」溫和提醒,不走 BLOCKER。
+- **Pre-commit / release gate**:`scripts/audit-content-quality.mjs --check` 於 `release:preflight` fail-closed 阻擋(release-preflight.mjs);Stop hook 每 turn 跑兩支僅報告(command 尾 `|| true`,non-blocking);`scripts/extract-canonical-rules.mjs` 目前無 blocking 消費點(.husky/pre-commit 未接兩支)
 
 ## Anti-pattern(永久 ban)
 

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

@@ -15,7 +15,7 @@ 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)豁免明文寫「本元件無互動」

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

@@ -13,7 +13,7 @@ paths:
 | 層 | 檔案 | Canonical | Hook | Audit Dim |
 |---|------|-----------|------|-----------|
 | 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)| `check_story_invariants.sh` R1 anatomy | 13 |
+| 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` | Polaris-aligned ≥ 2 of {WhenToUse / WhenNotToUse / Vs*Rule / ContentGuidelines};v3 預設整合 `UsageGuidance` 單一 export(Polaris/Material/Ant 共識) | `check_canonical_propagation.sh` E.1 principles | 30 |
 
 ## Title 命名
@@ -39,7 +39,7 @@ paths:
 
 **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` 等專有可保英)。
 
 ## 範例最高準則
 

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

@@ -15,9 +15,9 @@ paths:
 
 **唯一判準 = 「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。
 
-**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)。**「需要 children / 接線 / 組合」是正常 public 用法,不是 internal**。判斷訊號:benchmark 對標 consumer-facing primitive / spec「何時用」是 consumer 場景 / 有 standalone 用法 / export 給 consumer。
+**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。
 
-**Internal primitive**:**只有 DS 內部其他元件會用、consumer 永遠不碰**(consumer 用 wrapper 而非它)。Examples:`<SurfaceHeader/Body/Footer>`(只 Dialog 內部)/ `useOverflowItems` hook / `<ItemIcon>` / `<ItemAvatar>`(只 MenuItem 內部 slot,consumer 用 `<MenuItem>` 不用裸 slot)。判斷訊號:無 consumer 場景 / 只被其他 DS 元件 import / 是別元件的 sub-part/slot/chrome。
+**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)?
@@ -90,3 +90,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)。