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

package/ds-canonical/fork/hooks/check_consumer_app_invariants.sh

@@ -14,6 +14,31 @@ source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
 set -uo pipefail
 INPUT=$(cat 2>/dev/null || echo "{}")
 
+# ── Shared: 中和 consumer 自有 local 元件的裸 tag(named-import 除鏽的反向保護,2026-07-10 N6 根治)──
+# 多數 r2/r3 pattern 用 `<(DS\.)?X`(named-import 除鏽,抓 fork 用 named import `<Dialog>` 繞過
+# `<DS.>` 前綴)→ 但會誤殺 consumer 自有的同名 local 元件。判準:裸 <X> 只在「明確 named-import
+# 自非 DS 模組」(local './x' 或他 package)時才確定是 consumer 自有 → 中和成 <LOCAL_X;
+# 無 import(fixture 慣例)或 DS-package import → 視為 DS,保留(維持除鏽 intent)。
+# namespace <DS.X>(capture 到 "DS" token → skip)/ raw 小寫 HTML tag 不受影響。
+neutralize_local_tags() {
+  local content="$1"
+  # LOCAL_NAMED extraction 用 flattened 副本(抓跨行 import block);但**回傳保留原換行**
+  # (r2 的空 @story-baseline: marker 偵測是逐行的,flatten 會讓下一行內容誤填空 marker → P4)。
+  local local_named
+  local_named=$(printf '%s' "$content" | tr '\n' ' ' \
+    | grep -oE "import[[:space:]]*\{[^}]*\}[[:space:]]*from[[:space:]]*['\"][^'\"]+['\"]" \
+    | grep -vE "from[[:space:]]*['\"]@qijenchen/design-system" \
+    | grep -oE '\{[^}]*\}' | tr -d '{}' | tr ',' '\n' \
+    | sed -E 's/.*[[:space:]]as[[:space:]]+([A-Za-z0-9_]+).*/\1/; s/[[:space:]]//g' \
+    | grep -E '^[A-Z]' | sort -u)
+  local T
+  for T in $local_named; do
+    [ "$T" = "DS" ] && continue
+    content=$(printf '%s' "$content" | sed -E "s#<(/?)$T([[:space:]/>])#<\\1LOCAL_$T\\2#g")
+  done
+  printf '%s' "$content"
+}
+
 r1_no_ds_catalog() {
 set -uo pipefail
 
@@ -117,11 +142,15 @@ CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content /
 # Escape clauses
 if echo "$CONTENT" | grep -qE '@story-baseline-allow:|@consumer-catalog-allow:'; then exit 0; fi
 
+# 中和 consumer 自有 local 元件的裸 tag(N6 over-broad guard;shared helper SSOT)
+CONTENT=$(neutralize_local_tags "$CONTENT")
+
 # High-risk DS primitives requiring baseline marker
 HIGH_RISK_PRIMITIVES='DataTable|Dialog|Sheet|Popover|DropdownMenu|Tooltip|HoverCard|LinkInput|RadioGroup|CircularProgress|AppShell|Sidebar'
 
-# Detect usage
-USED=$(echo "$CONTENT" | grep -oE "<DS\.($HIGH_RISK_PRIMITIVES)\\b" | sort -u | head -10)
+# Detect usage(named-import 除鏽:namespace <DS.X> + DS-named-import 的裸 <X> 皆計入;
+# consumer 自有 local 元件已由 neutralize_local_tags 中和成 <LOCAL_X 不會誤匹配)
+USED=$(echo "$CONTENT" | grep -oE "<(DS\.)?($HIGH_RISK_PRIMITIVES)\\b" | sort -u | head -10)
 
 if [ -z "$USED" ]; then exit 0; fi
 
@@ -179,33 +208,36 @@ CONTENT=$(echo "$CONTENT" | tr '\n' ' ')
 # Global escape — file-wide allowlist
 if echo "$CONTENT" | grep -q '@ds-misuse-allow:'; then exit 0; fi
 
+# 中和 consumer 自有 local 元件的裸 tag(N6 over-broad guard;shared helper SSOT,對齊 r2_story_baseline)
+CONTENT=$(neutralize_local_tags "$CONTENT")
+
 VIOLATIONS=""
 
 # Pattern 1: <CircularProgress size={N}> with literal number (override default 24)
-if echo "$CONTENT" | grep -qE '<DS\.CircularProgress[^>]+size=\{[0-9]+\}'; then
+if echo "$CONTENT" | grep -qE '<(DS\.)?CircularProgress[^>]+size=\{[0-9]+\}'; then
   VIOLATIONS="${VIOLATIONS}  - <CircularProgress size={N}> hardcoded number override default 24 (per circular-progress.spec.md:101)\n"
 fi
 
 # Pattern 2: <RadioGroupItem> NOT wrapped in <SelectionItem control={...}>
 # Approximation: file uses RadioGroupItem but doesn't reference SelectionItem
-if echo "$CONTENT" | grep -qE '<DS\.RadioGroupItem\b' && ! echo "$CONTENT" | grep -qE 'SelectionItem|<DS\.RadioGroupItem[^>]+label='; then
+if echo "$CONTENT" | grep -qE '<(DS\.)?RadioGroupItem\b' && ! echo "$CONTENT" | grep -qE 'SelectionItem|<(DS\.)?RadioGroupItem[^>]+label='; then
   VIOLATIONS="${VIOLATIONS}  - <RadioGroupItem> 沒 wrap <SelectionItem control={<RadioGroupItem>}> (per selection-item.spec.md:23 SSOT spacing/padding)\n"
 fi
 
 # Pattern 3: <DataTable columns={[…]}> with literal single column
-if echo "$CONTENT" | grep -qE '<DS\.DataTable[^>]+columns=\{\[\s*\{[^}]+\}\s*\]\}' && ! echo "$CONTENT" | grep -qE 'columns=\{[^}]*\},\s*\{'; then
+if echo "$CONTENT" | grep -qE '<(DS\.)?DataTable[^>]+columns=\{\[\s*\{[^}]+\}\s*\]\}' && ! echo "$CONTENT" | grep -qE 'columns=\{[^}]*\},\s*\{'; then
   VIOLATIONS="${VIOLATIONS}  - <DataTable columns={[single-col]}> minimal one-column = 違反 data-table.spec.md canonical(min 2 cols for meaningful render)\n"
 fi
 
 # Pattern 4: <LinkInput placeholder=...> without value prop
-if echo "$CONTENT" | grep -qE '<DS\.LinkInput[^>]+placeholder=' && ! echo "$CONTENT" | grep -qE '<DS\.LinkInput[^>]+(value|defaultValue)='; then
+if echo "$CONTENT" | grep -qE '<(DS\.)?LinkInput[^>]+placeholder=' && ! echo "$CONTENT" | grep -qE '<(DS\.)?LinkInput[^>]+(value|defaultValue)='; then
   VIOLATIONS="${VIOLATIONS}  - <LinkInput placeholder=...> 沒 value prop = placeholder-only mode 抹平 link/edit canonical (per link-input.spec.md:18,48-58)\n"
 fi
 
 # Pattern 5: <Empty title=...> without icon and without description
-if echo "$CONTENT" | grep -qE '<DS\.Empty[^>]+title=' && \
-   ! echo "$CONTENT" | grep -qE '<DS\.Empty[^>]+icon=' && \
-   ! echo "$CONTENT" | grep -qE '<DS\.Empty[^>]+description='; then
+if echo "$CONTENT" | grep -qE '<(DS\.)?Empty[^>]+title=' && \
+   ! echo "$CONTENT" | grep -qE '<(DS\.)?Empty[^>]+icon=' && \
+   ! echo "$CONTENT" | grep -qE '<(DS\.)?Empty[^>]+description='; then
   VIOLATIONS="${VIOLATIONS}  - <Empty title=...> 無 icon 無 description = 違反 Empty.tsx:11「預設只需 description」minimal mock looks weird\n"
 fi
 
@@ -219,12 +251,12 @@ if echo "$CONTENT" | grep -qE '\b[a-z][a-z-]*-\[(#[0-9a-fA-F]{3,8}|rgb|rgba|hsl|
 fi
 
 # Pattern 9(2026-06-12,user 抓 fork「四不像」G4 補洞):AppShell slot 餵 raw HTML element。
-# app-shell.spec.md:296-299 明文禁 sidebar={<div>}/header={<header>},原註「靠 audit 把關」
+# app-shell.spec.md「Consumer 紀律」段明文禁 sidebar={<div>}/header={<header>},原註「靠 audit 把關」
 # 無機械閘 → 兌現成 P0(per memory feedback_ssot_mechanical_p0_not_p1_warn)。
 # 零誤判:雙條件 = 同檔有 <DS.AppShell> + slot 屬性直接餵 raw tag(div/header/nav/aside/section)。
-if echo "$CONTENT" | grep -qE '<DS\.AppShell\b' && \
+if echo "$CONTENT" | grep -qE '<(DS\.)?AppShell\b' && \
    echo "$CONTENT" | grep -qE '\b(header|sidebar|aside)=\{ *<(div|header|nav|aside|section)\b'; then
-  VIOLATIONS="${VIOLATIONS}  - <AppShell header/sidebar/aside={<raw element>}> — slot 必餵 DS 元件(ChromeHeader / Sidebar / AppShellAside),raw div/header 漏接 border/scroll/responsive canonical(per app-shell.spec.md:296-299)\n"
+  VIOLATIONS="${VIOLATIONS}  - <AppShell header/sidebar/aside={<raw element>}> — slot 必餵 DS 元件(ChromeHeader / Sidebar / AppShellAside),raw div/header 漏接 border/scroll/responsive canonical(per app-shell.spec.md「Consumer 紀律」段)\n"
 fi
 
 # Pattern 10(2026-06-16,user 抓 fork prototype 手刻 table 不用 DataTable):RAW PRIMITIVE 手刻
@@ -236,21 +268,121 @@ fi
 if echo "$CONTENT" | grep -qE '<table\b' && echo "$CONTENT" | grep -qE '<thead\b|<tbody\b|<th\b'; then
   VIOLATIONS="${VIOLATIONS}  - 手刻 raw <table><thead>/<tbody> 資料表 → 必用 <DataTable columns={...} data={...} />(build-ui-canonicals.md:18 ❌→✅ SSOT;這是「優先消費既有元件」大原則,無理由不得手刻)\n"
 fi
+# 2026-07-08 WM 戰役 R4:偽表格視覺簽名(div-grid 表格繞過字面 <table> 偵測 — WM 5 檔
+# MINI_TABLE grid-cols + header bg + row 常數重複宣告實證,spec broad / hook narrow M34 gap)。
+# 簽名 = 同段 content 有 grid-cols-[ 且(bg-muted|bg-neutral-selected 當 header 底 或 自創
+# ROW_PAD 類常數)。escape:@handcraft-table-ok:(真非表格的 grid 佈局)。
+if echo "$CONTENT" | grep -qE 'grid-cols-\[' && echo "$CONTENT" | grep -qE '(bg-muted|bg-neutral-selected)[^a-z-]' && echo "$CONTENT" | grep -qiE 'ROW_PAD|MINI_TABLE|<div[^>]*grid[^>]*font-medium' && ! echo "$CONTENT" | grep -q '@handcraft-table-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - 偽表格簽名(div grid-cols + header bg + row 常數):div-grid 手刻資料表 → 必用 <DataTable size=\"sm\" height=\"auto\">(data-table.spec「嵌入式表格」canonical;WM MembersTab 等 5 檔錨例)。真非表格 grid 佈局 → 行內 @handcraft-table-ok: <rationale>\n"
+fi
 if echo "$CONTENT" | grep -qE '<img\b[^>]*rounded-full'; then
   VIOLATIONS="${VIOLATIONS}  - 手刻 <img ... rounded-full> 頭像 → 必用 <Avatar>(build-ui-canonicals.md:25)\n"
 fi
 if echo "$CONTENT" | grep -qE '<select\b'; then
   VIOLATIONS="${VIOLATIONS}  - native <select> 手刻下拉 → 必用 <Select> / <DropdownMenu>(build-ui-canonicals.md:15)\n"
 fi
+# 2026-07-08 WM 戰役 R4:手刻表單 validation 簽名(WM CreateWorkItemDialog 註解引 canonical
+# 卻手刻 showErrors state = M23(d)「cite 存在 ≠ consume」;useFormValidation hook 零消費偵測缺口)。
+# 簽名 = 檔內有 showErrors/submitAttempt 類 state + FieldError 渲染,但無 useFormValidation import。
+if echo "$CONTENT" | grep -q 'useState' && echo "$CONTENT" | grep -qE '\b(showErrors|showError|submitAttempt|attemptedSubmit)\b' && echo "$CONTENT" | grep -q 'FieldError' && ! echo "$CONTENT" | grep -q 'useFormValidation' && ! echo "$CONTENT" | grep -q '@form-validation-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - 手刻表單 validation state(showErrors/submitAttempt + FieldError)→ 必消費 useFormValidation hook(form-validation.spec 規則 1 blur/7 全驗/8 DOM 序 anchor 隨 hook 自帶;root barrel 有 export)。特殊表單 → 行內 @form-validation-ok: <rationale>\n"
+fi
 if echo "$CONTENT" | grep -qE '<hr\b'; then
   VIOLATIONS="${VIOLATIONS}  - 手刻 <hr> 分隔線 → 用 <Separator>(或 separator.spec 允許的 CSS border)(build-ui-canonicals.md:23)\n"
 fi
+# 2026-07-10 WM 戰役收官:手刻 menu-item 可點列簽名(WM TypeSettingsDialog 左 rail 錨例 —
+# 手刻 <button hover:bg-neutral-hover + bg-neutral-selected> nav row,未消費 MenuItem)。
+# 前置:DS API 根因已修(MenuItem startContent slot,beta.84)→ 有合法替代才上機械攔(避免
+# fork 無路可走 brick)。簽名 = hover:bg-neutral-hover 與 bg-neutral-selected 成對出現
+# (= menu-item family 狀態語義)+ 可點訊號(<button/<a/onClick),且沒在消費 <MenuItem。
+# 注意:不 tag-anchor className(WM 錨例把 class 抽 const 再 className={cls} 引用,
+# tag-anchored regex 會漏 — test 27 抓到的真實 shape)。
+if echo "$CONTENT" | grep -q 'hover:bg-neutral-hover' && \
+   echo "$CONTENT" | grep -q 'bg-neutral-selected' && \
+   echo "$CONTENT" | grep -qE '<button\b|<a\b|onClick=' && \
+   ! echo "$CONTENT" | grep -q '<MenuItem' && \
+   ! echo "$CONTENT" | grep -q '@nav-row-handcraft-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - 手刻 menu-item 可點列(hover:bg-neutral-hover + bg-neutral-selected 成對)→ 必包 <MenuItem>(subpath @qijenchen/design-system/components/Menu;selected prop + startIcon/avatar/startContent slot;menu-item.spec.md「結構」)。非 menu-item 語義 → 行內 @nav-row-handcraft-ok: <rationale>\n"
+fi
+
+# ── 2026-07-10 批次 A(治理覆蓋 matrix 收官;來源 .claude/planning/2026-07-10-consumer-coverage-remediation.md)──
+# C5 對比配對:深字桶 hue(yellow/amber/orange/lime step-6)配 text-white — 各自合法、組合對比違規
+# (tag.spec.md 深字桶 = text-on-emphasis-dark)。修 → 消費 CAT_SOLID token pair。
+if echo "$CONTENT" | grep -q 'text-white' && \
+   echo "$CONTENT" | grep -qE 'bg-\[var\(--color-(yellow|amber|orange|lime)-[0-9]' && \
+   ! echo "$CONTENT" | grep -q '@cat-solid-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - 亮色底(yellow/amber/orange/lime step-6)配 text-white = 對比違規 → 消費 CAT_SOLID / CAT_SOLID_TOKENS pair(深字桶自帶 text-on-emphasis-dark;tokens/categorical-color.ts)。特例 → @cat-solid-ok: <rationale>\n"
+fi
+# C18 計數串接:element children 出現 {label} ({count/length/total})。attr(aria-label)字串層合法
+# — regex 錨 children 的 > 前綴,attribute 不中(item-anatomy.spec.md:176 禁括號串接)。
+if echo "$CONTENT" | grep -qE '>[^<]*\{[a-zA-Z0-9_.]+\} *\(\{[a-zA-Z0-9_.]*(count|Count|length|total)[a-zA-Z0-9_.]*\}\)' && \
+   ! echo "$CONTENT" | grep -q '@count-in-label-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - 計數括號串接 {label} ({count}) → row header 用「標題左、純數字右 space-between + tabular-nums」(item-anatomy.spec.md:176);互動元素(tab/chip/button)用 badge slot。aria/純文字匯出層 → @count-in-label-ok: <rationale>\n"
+fi
+# C17 分隔線幾何:vertical Separator 無 mx- = 黏按鈕(action-bar.spec.md「分隔線幾何」h-6 mx-1;
+# ButtonGroup 內用 <ButtonDivider/>(mx built-in))。
+SEP_TAGS=$(echo "$CONTENT" | grep -oE '<(DS\.)?Separator[^>]*orientation=["'"'"']vertical["'"'"'][^>]*' || true)
+if [ -n "$SEP_TAGS" ] && echo "$SEP_TAGS" | grep -qv 'mx-' && \
+   ! echo "$CONTENT" | grep -q '@separator-geometry-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - vertical <Separator> 無 mx- = 分隔線黏按鈕 → toolbar 用 className=\"h-6 mx-1\"(dense h-5 mx-1);ButtonGroup 內用 <ButtonDivider/>(action-bar.spec.md「分隔線幾何」)。版面切分 divider → @separator-geometry-ok: <rationale>\n"
+fi
+# C20 連結字手刻 underline:color.spec.md「Action — Primary」= hover 換色不用底線;
+# dropzone 連結走 FileUpload children slot。no-underline / hover:underline 皆不中此 regex 形。
+if echo "$CONTENT" | grep -qE '<(span|a|button|div)[^>]*className="([^"]* )?underline( [^"]*)?"'; then
+  VIOLATIONS="${VIOLATIONS}  - 手刻 underline 連結字 → Action—Primary canonical = text-primary + hover 換色(text-primary-hover),不用底線(color.spec.md「Action — Primary」);dropzone 連結走 <FileUpload> children slot\n"
+fi
+# C10 業務 search 被推最右:spacer(flex-1 自閉合 / ml-auto)緊接 Search Input。
+# 過濾當前檢視的 search = 業務層,與其他操作同區(action-bar.spec.md:69/76);無標題 toolbar 靠左(:109)。
+if echo "$CONTENT" | grep -qE '(flex-1[^>]*/>|ml-auto)[^<]{0,80}<(DS\.)?Input[^>]{0,200}placeholder="(Search|搜尋)' && \
+   ! echo "$CONTENT" | grep -q '@search-right-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - 業務 search(過濾當前檢視)被 spacer 推到最右 → 歸業務層與其他操作同區(action-bar.spec.md:69/76;無標題 toolbar 業務層靠左 :109)。工具型跨頁 search 置最右合法 → @search-right-ok: <rationale>\n"
+fi
+# C11 dialog chrome 雙 X:DialogHeader 之後 250 字窗內手放 startIcon={X} 且窗內無 actions=
+# (DialogHeader 自帶 Close;header 操作走 actions slot — action-bar.spec.md:281)。
+DH_WIN=$(echo "$CONTENT" | grep -oE '<(DS\.)?DialogHeader.{0,250}' || true)  # BSD grep bound 上限 255
+if [ -n "$DH_WIN" ] && echo "$DH_WIN" | grep -qE 'startIcon=\{X\}' && ! echo "$DH_WIN" | grep -q 'actions=' && \
+   ! echo "$CONTENT" | grep -q '@dialog-chrome-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - DialogHeader 內手放 X 關閉鈕(DialogHeader 已自帶 Close = 雙 X)→ header 操作走 actions slot(自動 ButtonDivider 分隔,action-bar.spec.md:281)。特例 → @dialog-chrome-ok: <rationale>\n"
+fi
+# C7 SelectMenu internal 直用(select-menu.spec.md:53 明文禁 consumer 直用 — 它是 Select/
+# Combobox 的內部選單面,consumer 用 <Select>/<Combobox>;此為「internal 且 spec 明文禁直用」
+# 特例,非一般 internal 包裝即可)。
+if echo "$CONTENT" | grep -qE '<SelectMenu\b' && \
+   ! echo "$CONTENT" | grep -q '@selectmenu-direct-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - <SelectMenu> 直用(internal 選單面,select-menu.spec.md:53 明文禁)→ 用 <Select> / <Combobox>(自帶 trigger + 選單接線)。極特例 → @selectmenu-direct-ok: <rationale>\n"
+fi
+# C13 手刻可收合 section header(2026-07-10 收官:R3-7 拍板 SectionHeader 留產品客製、但 layout
+# 全消費 canonical — 組合鐵律 codify 於 item-anatomy.spec.md「可收合 section header」;簽名 =
+# Chevron toggle + justify-between + 可點,且檔內無 SectionHeader 共用元件)。
+if echo "$CONTENT" | grep -qE 'Chevron(Down|Right|Up)' && \
+   echo "$CONTENT" | grep -q 'justify-between' && \
+   echo "$CONTENT" | grep -qE '<button\b|onClick=' && \
+   ! echo "$CONTENT" | grep -q 'SectionHeader' && \
+   ! echo "$CONTENT" | grep -q '@section-header-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - 手刻可收合 section 標題列(Chevron + justify-between + 可點)→ 抽共用 SectionHeader 元件並照 item-anatomy.spec.md「可收合 section header 組合 canonical」(chevron = title 後 suffix inline action / desc 用 item-gap token / endSlot 垂直置中;WM SectionHeader 錨例)。非 section 標題語義 → @section-header-ok: <rationale>\n"
+fi
+# C19 兩欄 dialog 共用捲軸(2026-07-10 user 拍板:兩欄是組合非元件;組合鐵律 = 各欄自帶
+# ScrollArea,overlay-surface.spec.md「兩欄 dialog 組合 canonical」)。簽名 = Dialog body +
+# 欄分隔 border-l + ScrollArea 少於 2 = 兩欄共用單一捲軸。
+if echo "$CONTENT" | grep -qE '<(DS\.)?Dialog(Body|Content)\b' && \
+   echo "$CONTENT" | grep -q 'border-l' && \
+   echo "$CONTENT" | grep -qE 'className="[^"]*flex[^"]*"' && \
+   [ "$(echo "$CONTENT" | grep -o '<ScrollArea' | wc -l | tr -d ' ')" -lt 2 ] && \
+   ! echo "$CONTENT" | grep -q '@two-pane-dialog-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - 兩欄 dialog(border-l 欄分隔)但 ScrollArea < 2 = 共用單一捲軸 → 各欄自帶 <ScrollArea> 獨立捲(overlay-surface.spec.md「兩欄 dialog 組合 canonical」;archetype = WM WorkItemDetailDialog / FileViewer InfoPanel)。非兩欄語義 → @two-pane-dialog-ok: <rationale>\n"
+fi
+# C12 Field family 硬寬:Select/Combobox/DatePicker/PeoplePicker 帶 w-N / w-[Npx] 硬寬
+# → width="hug"/"fill" 語義軸(field-controls.spec.md「寬度」)。
+if echo "$CONTENT" | grep -qE '<(DS\.)?(Select|Combobox|DatePicker|PeoplePicker)\b[^>]*className="[^"]*\bw-([0-9]+|\[[0-9]+(px|rem)\])' && \
+   ! echo "$CONTENT" | grep -q '@field-width-ok:'; then
+  VIOLATIONS="${VIOLATIONS}  - Field 家族控件 className 硬寬(w-N / w-[Npx])→ 用 width=\"hug\"(內容自適)或預設 fill(field-controls.spec.md「寬度」;WM 詳情 metadata 全 hug 拍板錨例)。特例 → @field-width-ok: <rationale>\n"
+fi
 
 # Pattern 6: Overlay trigger without defaultOpen state for visual demo
 # (Skip in production .tsx; only enforce in .stories.tsx where visual snapshot matters)
 if echo "$FILE" | grep -qE '\.stories\.tsx$'; then
   for overlay in Tooltip Popover Dialog Sheet DropdownMenu; do
-    if echo "$CONTENT" | grep -qE "<DS\.${overlay}\b" && \
+    if echo "$CONTENT" | grep -qE "<(DS\.)?${overlay}\b" && \
        ! echo "$CONTENT" | grep -qE "(defaultOpen|open=\{(true|isOpen)\})"; then
       VIOLATIONS="${VIOLATIONS}  - Story uses <${overlay}> without defaultOpen — visual audit can't see overlay content\n"
     fi

package/ds-canonical/fork/hooks/check_ds_anchor_preflight.sh

@@ -4,7 +4,8 @@
 #
 # Purpose: PreToolUse Edit/Write/MultiEdit 偵測 production tsx wrap DS primitive
 # (`<Sidebar>` / `<AppShell>` / `<DataTable>` / `<Dialog>` / `<Field>` 等)
-# 沒同 turn 跑過 Grep / Read DS canonical baseline → 軟 BLOCKER 提醒 propose 前必出 3-column owner table。
+# 沒同 turn 跑過 Grep / Read DS canonical baseline → P0 BLOCKER(exit 2,2026-07-07 治理進化方向 2 升級;
+# escape CLAUDE_BYPASS_DS_ANCHOR=1 audit-logged),propose 前必出 3-column owner table。
 #
 # Scope:同 check_substantive_edit_approval_preflight.sh extended scope
 #   - node_modules/@qijenchen/design-system/src/**.tsx (DS internal)

package/ds-canonical/fork/hooks/check_dynamic_tailwind_class.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# check_dynamic_tailwind_class — 攔「動態 Tailwind utility class」脆弱寫法(2026-07-09 root-cause 防線)
+#
+# 病根(user 以 GitHub Pages 對比抓出的 DataTable row-height regression):
+#   `h-table-row-${size}` 這種「class 名本身含 ${...} 插值」的模板字串,Tailwind **靜態掃描看不到**
+#   完整 class → 只能靠專案別處剛好有 literal(如 spec.md)被 content-detection 掃到才生成。
+#   一旦那個脆弱 literal 消失 / 掃描樹變動(本 case 是 .gitignore 加 reference/)→ 整組 `.h-table-row-*`
+#   規則不生成 → 元件靜默塌成內容高度(non-editable 33px / editable 44px 而非 token 40px)+ 選取控件走位。
+#   tsc / build 全綠、CI 不紅 = 沉默陷阱。
+#
+# 正解(對齊 fieldWrapperStyles 的 `h-field-md` cva-literal 慣例):class 名必須是**完整 literal**;
+#   要隨變數選 class 用 literal map:`{ sm:'h-table-row-sm', md:'h-table-row-md', lg:'h-table-row-lg' }[size]`。
+#
+# Scope:production tsx/ts(packages/design-system/src + apps)。CSS var 插值(`var(--x-${y})` / arbitrary
+#   value `[...${...}]`)不在此列(那是值,不是 class 名;且 CSS var 真存在,fail-loud 不同機制)。
+# Escape:`// @dynamic-tailwind-allow: <理由>` per-line。
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+set -euo pipefail
+INPUT=$(cat)
+fp=$(printf '%s' "$INPUT" | python3 -c "import sys,json;print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))" 2>/dev/null || true)
+content=$(printf '%s' "$INPUT" | python3 -c "import sys,json;d=json.load(sys.stdin).get('tool_input',{});print(d.get('content') or d.get('new_string') or '')" 2>/dev/null || true)
+[ -z "$fp" ] && exit 0
+case "$fp" in
+  *packages/design-system/src/*.tsx|*packages/design-system/src/*.ts|*apps/*/src/*.tsx|*apps/*/src/*.ts) ;;
+  *) exit 0 ;;
+esac
+[ -z "$content" ] && exit 0
+
+# 抓:backtick 字串內、Tailwind 尺寸/間距 utility 前綴 + 之後含 `${` 讓 class 名不完整。
+#   e.g. `h-table-row-${size}` / `h-${x}` / `min-h-${y}` / `w-col-${i}` / `gap-${g}` / `py-${p}`
+# 排除:`[` 之後(arbitrary value,如 `h-[var(--x-${y})]`)、`var(` 內。
+hits=$(printf '%s' "$content" | grep -nE '`[^`]*\b(h|w|min-h|max-h|min-w|max-w|size|gap|space-[xy]|p[xytblr]?|m[xytblr]?)-[a-z0-9-]*\$\{' 2>/dev/null \
+  | grep -vE '@dynamic-tailwind-allow' \
+  | grep -vE '\[[^]]*\$\{|var\(' || true)
+
+if [ -n "$hits" ]; then
+  echo "🚨 BLOCKER: 動態 Tailwind class(class 名含 \${...} 插值)— Tailwind 靜態掃描看不到 → 靜默不生成規則" >&2
+  echo "  file: $fp" >&2
+  echo "$hits" | sed 's/^/    /' >&2
+  echo "" >&2
+  echo "  病根:2026-07-09 DataTable row-height regression(h-table-row-\${size} → utility 消失 → row 塌 + 選取走位)" >&2
+  echo "  正解:改 literal map,class 名寫完整字面 —" >&2
+  echo "    const cls = { sm: 'h-table-row-sm', md: 'h-table-row-md', lg: 'h-table-row-lg' }[size]" >&2
+  echo "  逃生:確實非 class(CSS var 值等)→ 行尾加 // @dynamic-tailwind-allow: <理由>" >&2
+  exit 2
+fi
+exit 0

package/ds-canonical/fork/hooks/check_escape_marker_abuse.sh

@@ -135,6 +135,33 @@ $(echo "$MARKERS_FOUND" | sed 's/^/    /')
 EOF
     exit 2
   fi
+
+  # ── Repo 級累計 ratchet(2026-07-08 WM 戰役 R4)──────────────────────────────
+  # per-file gate(≥3 distinct/≥5 total)可被「每檔 1-2 個、散多檔」繞過 → repo 級 ceiling。
+  # Ratchet 精神(Polaris stylelint migrator):存量 ≥ cap 後只擋「本次 edit 再新增 marker」,
+  # 不因存量 brick 無關 edit(本次內容無 marker → 直接放行)。
+  EDIT_ADDS_MARKER=$(echo "$CONTENT" | grep -cE "$MARKER_RE" || true)
+  if [ "${EDIT_ADDS_MARKER:-0}" -gt 0 ]; then
+    APPS_ROOT="${CLAUDE_PROJECT_DIR:-.}/apps"
+    REPO_CAP=10
+    if [ -d "$APPS_ROOT" ]; then
+      REPO_TOTAL=$(grep -rhoE "$MARKER_RE" "$APPS_ROOT" --include='*.tsx' --include='*.ts' 2>/dev/null | wc -l | tr -d ' ')
+      if [ "${REPO_TOTAL:-0}" -ge "$REPO_CAP" ]; then
+        cat >&2 << EOF
+🚨 ESCAPE-MARKER-REPO-RATCHET BLOCKER(P0,2026-07-08 WM 戰役 R4)
+
+  apps/** 全 repo escape marker 存量已 $REPO_TOTAL 個(ceiling $REPO_CAP),本次 edit 又要新增 $EDIT_ADDS_MARKER 個。
+  每檔 1-2 個散多檔 = 繞 per-file gate 的同型濫用 — repo 級 ratchet 攔。
+
+  修法 2 選 1:
+    (a) 先清既有 escape 的根因(重構走 DS canonical),存量 < $REPO_CAP 後再加真必要的
+    (b) Override env(極罕見,commit msg 必記 rationale):
+        CLAUDE_BYPASS_ESCAPE_MARKER_AUDIT=1
+EOF
+        exit 2
+      fi
+    fi
+  fi
 fi
 
 exit 0

package/ds-canonical/fork/hooks/check_field_family_invariants.sh

@@ -1,12 +1,13 @@
 #!/bin/bash
 # Field family unified invariant hook(2026-05-08 cluster A consolidation)
 #
-# Merges PreToolUse hooks(原各檔已 retire,合併入此)— 共 5 條 sub-rules:
+# Merges PreToolUse hooks(原各檔已 retire,合併入此)— 共 6 條 sub-rules:
 #   A.1 naked row-mode propagation(原 check_naked_row_mode_propagation,P0 BLOCKER)
 #   A.2 FieldControlGroup wrapper direct child(原 check_field_control_group_direct_child,P1 WARN)
 #   A.3 Field state ring SSOT(原 check_field_state_token_consume 3 sub-rules,P0 BLOCKER)
 #   A.4 disabled placeholder color(原 check_disabled_placeholder_color,P1 stderr only)
 #   A.5 _Group child fieldCtx.id 隔離(2026-05-31 折入,M4 AR34 regression detector,P0 BLOCKER)
+#   A.6 空值顯示 SSOT(2026-07-08 user 拍板半形 hyphen,P0 BLOCKER)
 #
 # Why merge:皆 Field 家族 invariant,共用 INPUT parsing + Edit/Write filter pattern,
 #   分散在 4 個 hook 是「散裝 SSOT」(M17 + Anthropic ≤ 15 hook best practice 違反)。
@@ -19,6 +20,7 @@
 #   A.3: `// @field-state-ring-allow: <reason>`
 #   A.4: `// @disabled-color-allow: <reason>`
 #   A.5: `// @group-fieldctx-allow: <reason>`
+#   A.6: `// @empty-display-allow: <reason>`
 
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
 
@@ -247,4 +249,62 @@ EOF
     ;;
 esac
 
+# ── A.6 空值顯示 SSOT(P0 BLOCKER,2026-07-08 user 拍板半形 hyphen)────────────────
+# user verbatim「我從頭到尾哪裡有說要用全形的」+ 五情境空值框架。SSOT:符號常數 =
+#   field-wrapper.tsx `EMPTY_DISPLAY = '-'`(U+002D 半形);分流 hook = field-context.ts
+#   `useFieldEmptyDisplay()`。禁 2 shape:
+#   A.6.1 非 owner 檔直接 import `EMPTY_DISPLAY` 常數(應消費 hook 分流,否則 table-cell
+#         editable→'' 分流會漏);
+#   A.6.2 components/ tsx display 路徑 hardcode 全形 em dash `'—'`/`"—"`(U+2014)字面。
+# M7 broad-vs-narrow:spec wording 廣(「禁 hardcode 空值符號」);hook 取「quoted em dash 字面」
+#   高信號 subset + owner skip + comment 剝離 + `@empty-display-allow` escape,零誤判導向。
+if ! echo "$NEW_CONTENT" | grep -q '@empty-display-allow'; then
+  # A.6.1 非 owner 檔 import EMPTY_DISPLAY 常數(剝離註解行)
+  case "$FILE_PATH" in
+    */field-context.ts|*/field-wrapper.tsx) ;; # SSOT owner(定義 + 分流 hook)skip
+    *)
+      A61_CONTENT=$(echo "$NEW_CONTENT" | grep -vE '^[[:space:]]*(//|\*|/\*)')
+      if printf '%s' "$A61_CONTENT" | grep -E "import.*EMPTY_DISPLAY|EMPTY_DISPLAY.*from" >/dev/null; then
+        cat >&2 <<EOF
+
+┄┄┄ A.6.1 check_field_family_invariants — EMPTY_DISPLAY 直引 BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測到直接 import \`EMPTY_DISPLAY\` 常數(非 field-context.ts owner)。
+空值顯示必經 \`useFieldEmptyDisplay()\` hook 分流(table-cell 可編輯→空白 / 其餘→半形 '-'),
+直引常數會漏 surface × editable 分流。
+
+修法:import { useFieldEmptyDisplay } from '@/design-system/components/Field/field-context'
+      const emptyDisplay = useFieldEmptyDisplay()
+例外:行尾 \`// @empty-display-allow: <reason>\`
+
+EOF
+        record_worst 2
+      fi
+      ;;
+  esac
+  # A.6.2 components/ tsx hardcode 全形 em dash 空值字面(剝離註解行 + owner/story skip)
+  case "$FILE_PATH" in
+    *.stories.tsx|*/field-context.ts|*/field-wrapper.tsx) ;; # doc N/A marker + SSOT owner skip
+    *components/*.tsx)
+      A62_CONTENT=$(echo "$NEW_CONTENT" | grep -vE '^[[:space:]]*(//|\*|/\*)')
+      if printf '%s' "$A62_CONTENT" | grep -E "['\"]—['\"]" >/dev/null; then
+        cat >&2 <<EOF
+
+┄┄┄ A.6.2 check_field_family_invariants — 全形 em dash 空值 BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測到 components/ 實作檔 hardcode 全形 em dash \`'—'\`(U+2014)字面。
+user 2026-07-08 拍板:空值符號 = **半形 hyphen '-'(U+002D)**,禁全形。
+
+修法:空值一律 \`{value ?? emptyDisplay}\`(emptyDisplay = useFieldEmptyDisplay()),不 hardcode 符號。
+例外:行尾 \`// @empty-display-allow: <reason>\`
+
+EOF
+        record_worst 2
+      fi
+      ;;
+  esac
+fi
+
 exit $WORST

package/ds-canonical/fork/hooks/check_layout_space_magic_numbers.sh

@@ -43,7 +43,31 @@ ESCAPE_MARKER='@layout-space-magic-ok:'
 
 # Detect magic spacing classes (Tailwind class strings only — NOT JSX props like size={24})
 # Match per line so we can check per-line escape comments
-MAGIC_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b(p|px|py|pt|pb|pl|pr|gap|space-x|space-y|m|mx|my|mt|mb|ml|mr)-(0\.5|[1-9][0-9]?(\.[0-9])?)\b')
+# 2026-07-08 WM 戰役 R4 擴 scope(broad-vs-narrow gap 實證修補):
+#   (a) logical properties ps-/pe-/ms-/me-(WM 6 筆 ps-4 漏網實證)
+#   (b) arbitrary bracket 固定 px:gap-[7px] / p-[13px] 類(spacing 家族)
+#   (c) 固定寬度 w-[Npx](WM w-[640px] 丟失 min() viewport clamp 實證;w-[min(...)]/var()/% 不攔)
+#   (d) grid-template 固定 px 欄寬:grid-cols-[...Npx...](WM mini-table 88px/72px 黏死實證)
+MAGIC_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b(p|px|py|pt|pb|pl|pr|ps|pe|gap|space-x|space-y|m|mx|my|mt|mb|ml|mr|ms|me)-(0\.5|[1-9][0-9]?(\.[0-9])?)\b|\b(p|px|py|pt|pb|pl|pr|ps|pe|gap|m|mx|my|mt|mb|ml|mr|ms|me)-\[[0-9]+(\.[0-9]+)?px\]|\bw-\[[0-9]+(\.[0-9]+)?px\]|\bgrid-(cols|rows)-\[[^]]*[0-9]+px[^]]*\]')
+
+# ── 幻覺 token 攔截(2026-07-08 WM 戰役:app 自創 var(--layout-space-distant) → CSS 未定義
+# silent 解析 0 → 區塊全黏死,PDF「全部擠在一起」根因之一。白名單 = loose|tight|bottom
+# (layoutSpace.css SSOT 僅此三顆;新增 tier 走 DS token 流程,不在 consumer 端發明)──
+PHANTOM=$(echo "$NEW_CONTENT" | grep -nE 'var\(--layout-space-[a-z-]+\)' | grep -vE 'var\(--layout-space-(loose|tight|bottom)\)' || true)
+if [ -n "$PHANTOM" ]; then
+  cat >&2 <<EOF_PH
+🚨 [P0 BLOCKER] 幻覺 layout-space token(CSS 未定義 = silent 0 = 佈局黏死):
+$PHANTOM
+→ 白名單只有 --layout-space-{loose,tight,bottom}(layoutSpace.css SSOT)。
+  要更大一級間距 → 用 loose;真需新 tier → 走 DS token 新增流程(layoutSpace.spec),禁 consumer 端自創。
+  Anchor:2026-07-08 WM --layout-space-distant ×4 處,整個 detail modal 區塊黏死。
+EOF_PH
+  exit 2
+fi
+
+# 2026-07-10 批次 A:divider 幾何 canonical(h-6 mx-1 / h-5 mx-1,action-bar.spec.md「分隔線幾何」)
+# 是**正解**,不該被 magic-number 攔(原本懲罰 canonical 修法、放行違規 = 治理自我打架)。
+MAGIC_LINES=$(echo "$MAGIC_LINES" | grep -vE '(Separator|ButtonDivider)' || true)
 
 if [ -z "$MAGIC_LINES" ]; then
   exit 0
@@ -82,9 +106,9 @@ $(echo -e "$UNJUSTIFIED" | sed 's/^/    /' | head -10)
   per app-shell.spec.md L205-219 + layoutSpace.spec.md SSOT:consumer content 必遵循
   layoutSpace 6 條規則 + 親疏 3 級,**禁** 硬寫 Tailwind magic numbers。改用:
     p-[var(--layout-space-loose)]      /* 16px 規則 1A/1B chrome / wrap */
-    p-[var(--layout-space-tight)]      /* 12px 規則 3 親 gap */
-    gap-[var(--layout-space-distant)]  /* 24px 規則 3 疏 gap */
-    space-y-[var(--layout-space-distant)]
+    gap-[var(--layout-space-tight)]    /* 12px 規則 3 親 gap(跨範疇相關) */
+    gap-[var(--layout-space-loose)]    /* 16px 規則 3 疏 gap(跨範疇 parallel;lg 密度自動 24px) */
+    (token 全集 = loose/tight/bottom,無其他級 — 自創 --layout-space-distant 類 = 幻覺 token,本 hook 會攔)
 
   修法 2 選 1:
     (a) 改 token:換成 var(--layout-space-N) N∈{loose,tight} family per 6 規則 + 親疏 3 級

package/ds-canonical/fork/hooks/check_opacity_token_usage.sh

@@ -135,6 +135,24 @@ if [ -n "$HITS_PRIMITIVE" ]; then
   VIOLATIONS="${VIOLATIONS}\n   [primitive color as utility] $(echo "$HITS_PRIMITIVE" | tr '\n' ' ')"
 fi
 
+# 10) 幻覺 semantic state 尾綴(2026-07-10 批次 A C1:WM hover:bg-neutral-hovered ×3 檔 silent no-op 實證。
+#     真尾綴只有 -hover/-active/-selected(+ selected-hover/selected-active);過去式/-pressed 全幻覺,
+#     Tailwind 靜默不生成 → hover 無效果、build 不報錯)
+HITS_PHANTOM_STATE=$(echo "$NEW_CONTENT" | grep -oE "\b(hover:|active:|focus:)?(bg|text|border|ring)-[a-z][a-z-]*-(hovered|actived|focussed|pressed)\b" | sort -u || true)
+if [ -n "$HITS_PHANTOM_STATE" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [phantom state suffix(silent no-op)] $(echo "$HITS_PHANTOM_STATE" | tr '\n' ' ')"
+fi
+
+# 11) micro gap(<4px)+ registry fraction width(#71 2026-07-11 接線)——
+#     registry micro_gap / fraction 的 rationale 明寫「flag for human review」(非硬禁)→ 走
+#     SOFT WARN 非 block(避免誤殺 Calendar/Chart/FileViewer/Carousel 等 4 個既有合法 micro-gap 用途)。
+#     fraction 用 registry 明列 14 條(w-1/3.. 不含 w-1/2 = 合法留白),避免廣捕 w-N/M 誤殺。
+HITS_MICROGAP=$(echo "$NEW_CONTENT" | grep -oE "\bgap-(px|0\.5|1\.5)\b" | sort -u || true)
+HITS_FRACTION=$(echo "$NEW_CONTENT" | grep -oE "\bw-(1/3|2/3|1/4|3/4|1/5|2/5|3/5|4/5|1/6|5/6|1/12|5/12|7/12|11/12)\b" | sort -u || true)
+SOFT_NOTES=""
+[ -n "$HITS_MICROGAP" ] && SOFT_NOTES="${SOFT_NOTES}\n   [micro gap <4px] $(echo "$HITS_MICROGAP" | tr '\n' ' ')"
+[ -n "$HITS_FRACTION" ] && SOFT_NOTES="${SOFT_NOTES}\n   [fraction width] $(echo "$HITS_FRACTION" | tr '\n' ' ')"
+
 if [ -n "$VIOLATIONS" ]; then
   cat >&2 <<'EOF_HEAD'
 
@@ -160,7 +178,17 @@ EOF_HEAD
 EOF_BODY
   # P0 BLOCKER(2026-07-07 治理進化方向 2:對齊 user 2026-05-27「SSOT canonical 必 P0」doctrine;
   # 檔級豁免(anatomy/principles stories / token 自家)+ 行級 escape 已備,升級不增誤殺)
+  # micro-gap/fraction soft note 附在硬 block 訊息尾(一起讓 AI 看到,但不影響 exit code 判定)
+  [ -n "$SOFT_NOTES" ] && { echo "" >&2; echo "   （另有 soft flag,非 block 原因）:" >&2; echo -e "$SOFT_NOTES" >&2; }
   exit 2
 fi
 
+# 只有 micro-gap / fraction soft note(無硬 violation)→ WARN 非 block(registry rationale「flag for human review」)
+if [ -n "$SOFT_NOTES" ]; then
+  echo "" >&2
+  echo "⚠️  Dim 47 soft flag(registry micro_gap / fraction「flag for human review」— 非 block,#71 接線):" >&2
+  echo -e "$SOFT_NOTES" >&2
+  echo "   <4px gap / registry fraction width 常違反 item-anatomy slot 幾何 / layout SSOT → 人工 review。合理則行尾 @token-registry-ok: <rationale>。" >&2
+fi
+
 exit 0

package/ds-canonical/fork/hooks/check_story_determinism.sh

@@ -11,6 +11,8 @@
 # 第一期 WARN(exit 0):存量 10 檔(dry-run 2026-07-07,DateGrid 家族為主)未清,
 # 誤殺率驗證期後升 P0(對齊 handcraft 偵測同節奏;roadmap 方向 1 KPI 隨頻回顧)。
 
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
 set -euo pipefail
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')