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

package/ds-canonical/hooks/check_field_family_invariants.sh

@@ -0,0 +1,205 @@
+#!/bin/bash
+# Field family unified invariant hook(2026-05-08 cluster A consolidation)
+#
+# Merges 4 PreToolUse hooks(原各檔已 retire,合併入此)— 共 4 條 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)
+#
+# Why merge:皆 Field 家族 invariant,共用 INPUT parsing + Edit/Write filter pattern,
+#   分散在 4 個 hook 是「散裝 SSOT」(M17 + Anthropic ≤ 15 hook best practice 違反)。
+#
+# Exit code precedence:BLOCK(2)> WARN(1)> INFO(0)。每 rule 可獨立觸發,worst 勝。
+#
+# Per-rule allowlist(各自獨立):
+#   A.1: `// @naked-row-mode-allow: <reason>`
+#   A.2: `// @fcg-wrapper-allow: <reason>` 或檔頭
+#   A.3: `// @field-state-ring-allow: <reason>`
+#   A.4: `// @disabled-color-allow: <reason>`
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Tool filter — 只 Edit/Write/MultiEdit 跑
+case "$TOOL" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# 不是 .tsx / .ts 直接過(各 rule 內部還會再 narrow)
+case "$FILE_PATH" in
+  *.tsx|*.ts) ;;
+  *) exit 0 ;;
+esac
+
+# 讀 merged content(舊檔 + 新 edit 拼起)— A.1 / A.3 需要整檔判 naked variant 存在性
+FILE_CONTENT=""
+if [ -f "$FILE_PATH" ]; then
+  FILE_CONTENT=$(cat "$FILE_PATH")
+fi
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  (.tool_input.content // "") + "\n" +
+  (.tool_input.new_string // "") + "\n" +
+  ([.tool_input.edits[]? | .new_string] | join("\n"))
+' 2>/dev/null || echo "")
+
+# A.2 / A.4 只看 NEW_CONTENT(diff-level signal),A.1 / A.3 看 MERGED
+MERGED_CONTENT="${FILE_CONTENT}
+${NEW_CONTENT}"
+
+[ -z "${MERGED_CONTENT//[[:space:]]/}" ] && exit 0
+
+WORST=0
+record_worst() { local lvl=$1; [ "$lvl" -gt "$WORST" ] && WORST=$lvl; }
+
+# ── A.1 naked row-mode propagation(P0 BLOCKER)─────────────────────────────────
+case "$FILE_PATH" in
+  *components/*.tsx)
+    case "$FILE_PATH" in
+      */field-wrapper.tsx|*/textarea.tsx) ;; # SSOT host skip
+      *)
+        if ! echo "$MERGED_CONTENT" | grep -q '@naked-row-mode-allow' \
+           && echo "$MERGED_CONTENT" | grep -E "variant:\s*['\"]naked['\"]|variant=\{?['\"]naked['\"]" >/dev/null \
+           && echo "$MERGED_CONTENT" | grep -E "(inline-flex|flex)[^\"'\`]*items-center" >/dev/null \
+           && ! echo "$MERGED_CONTENT" | grep -q "nakedCellRowModeAlign"; then
+          cat >&2 <<EOF
+
+┄┄┄ A.1 check_field_family_invariants — naked row-mode propagation BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測到此檔消費 \`variant="naked"\` + 內部 wrapper hardcode \`items-center\`,
+但**未** import / apply \`nakedCellRowModeAlign\` SSOT。
+
+⚠️  M19 canonical:naked variant 元件所有內部 wrapper 必 propagate host cell
+    \`data-row-mode\`(autoRow→items-start / fixed→items-center)。
+
+修法:
+  1. import { nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'
+  2. wrapper className 加上 SSOT(eg \`cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign)\`)
+  3. 例外:行尾 \`// @naked-row-mode-allow: <reason>\`
+
+EOF
+          record_worst 2
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+# ── A.2 FieldControlGroup wrapper direct child(P1 WARN)────────────────────────
+case "$FILE_PATH" in
+  *.tsx)
+    if echo "$NEW_CONTENT" | grep -q '<FieldControlGroup' \
+       && ! echo "$NEW_CONTENT" | grep -q '@fcg-wrapper-allow'; then
+      SUSPECT=$(printf '%s' "$NEW_CONTENT" | awk '
+        /<FieldControlGroup/ { inFCG=1; next }
+        /<\/FieldControlGroup>/ { inFCG=0; next }
+        inFCG && /^[[:space:]]*<(div|span)[[:space:]>]/ {
+          if ($0 !~ /display:[[:space:]]*contents/ && $0 !~ /@fcg-wrapper-allow/) print NR ":" $0
+        }
+      ')
+      if [ -n "$SUSPECT" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ A.2 check_field_family_invariants — FieldControlGroup wrapper WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+偵測到 FieldControlGroup 內有 \`<div>\` / \`<span>\` wrapper(可能破壞 CSS \`[&>*]\` variants):
+${SUSPECT}
+
+修法 3 擇 1:
+  1. 移除 wrapper,Field control 直接是 FieldControlGroup direct child
+  2. 透過 prop forward className(eg \`<FilterValuePicker className="flex-1 min-w-0">\`)
+  3. wrapper 用 \`display:contents\` / 加 \`// @fcg-wrapper-allow: <reason>\`
+
+EOF
+        record_worst 1
+      fi
+    fi
+    ;;
+esac
+
+# ── A.3 Field state ring SSOT(P0 BLOCKER,3 sub-rules)─────────────────────────
+case "$FILE_PATH" in
+  *components/*.tsx)
+    case "$FILE_PATH" in
+      */field-wrapper.tsx|*/textarea.tsx|*.stories.tsx|*.test.*|*.spec.tsx) ;; # SSOT/test skip
+      *)
+        if ! echo "$NEW_CONTENT" | grep -q '@field-state-ring-allow'; then
+          # A.3.1 舊 box-shadow inset
+          if echo "$NEW_CONTENT" | grep -E "(hover|focus-within|data-\[state=open\]):shadow-\[inset" >/dev/null; then
+            cat >&2 <<'EOF'
+
+┄┄┄ A.3.1 check_field_family_invariants — Field state ring shadow inset BLOCKER ┄┄┄
+
+[P0] naked variant state ring 用 `box-shadow inset` — v9 retire pattern。
+修法:讓 Field default state machine 自動繼承(border-based);cell hover 用 `nakedCellEditableDisplayHover` const。
+
+EOF
+            record_worst 2
+          fi
+          # A.3.2 自寫 outline state ring
+          if echo "$NEW_CONTENT" | grep -E "(hover|focus-within|focus-visible|data-\[state=open\]):outline-(border|primary)" >/dev/null; then
+            cat >&2 <<'EOF'
+
+┄┄┄ A.3.2 check_field_family_invariants — Field state ring outline BLOCKER ┄┄┄
+
+[P0] 自寫 `hover:outline-border` / `focus-within:outline-primary` — v13 canonical 禁。
+修法:Field default 自動繼承 / cell 用 `nakedCellEditableDisplayHover` const。
+
+EOF
+            record_worst 2
+          fi
+          # A.3.3 per-control open=blue override(v13.5)
+          if echo "$NEW_CONTENT" | grep -E "(open|isOpen) +&& +.{0,40}('border-primary'|\"border-primary\")" >/dev/null \
+             || echo "$NEW_CONTENT" | grep -E "data-\[state=open\]:border-primary" >/dev/null; then
+            cat >&2 <<'EOF'
+
+┄┄┄ A.3.3 check_field_family_invariants — per-control open=blue BLOCKER ┄┄┄
+
+[P0] per-control `open && 'border-primary'` / `data-[state=open]:border-primary` — v13.3 canonical「focus dominates everything」禁。
+修法:刪 override。Radix Popover open 時 trigger 通常 focused → focus-within fires → 藍(自然 Ant 風)。改 Field default SSOT 須 spec 補 rationale。
+
+EOF
+            record_worst 2
+          fi
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+# ── A.4 disabled placeholder color(P1 stderr,exit 0 不 block)──────────────────
+if ! echo "$NEW_CONTENT" | grep -q '@disabled-color-allow'; then
+  SUSPECT_DP=""
+  if echo "$NEW_CONTENT" | grep -E "placeholder:text-fg-muted" >/dev/null \
+     && ! echo "$NEW_CONTENT" | grep -E "(disabled:placeholder:text-fg-disabled|group-data-\[field-mode=disabled\].*placeholder:text-fg-disabled|resolvedMode\s*===\s*'disabled'.*text-fg-disabled)" >/dev/null; then
+    SUSPECT_DP="$SUSPECT_DP [placeholder:text-fg-muted 無 disabled override]"
+  fi
+  if echo "$NEW_CONTENT" | grep -E '<span[^>]*"text-fg-muted"[^>]*>\s*\{[^}]*placeholder' >/dev/null 2>&1 \
+     && ! echo "$NEW_CONTENT" | grep -E "resolvedMode\s*===\s*'disabled'" >/dev/null; then
+    SUSPECT_DP="$SUSPECT_DP [<span text-fg-muted>{placeholder} 不分 mode]"
+  fi
+  if [ -n "$SUSPECT_DP" ]; then
+    cat >&2 <<EOF
+
+┄┄┄ A.4 check_field_family_invariants — disabled placeholder color WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+${SUSPECT_DP}
+修法:disabled:placeholder:text-fg-disabled / group-data-[field-mode=disabled]/field:placeholder:text-fg-disabled / JSX 條件
+詳:tokens/color/color.spec.md「Disabled state precedence canonical」/ M24
+例外:行尾 \`// @disabled-color-allow: <reason>\`
+
+EOF
+    # A.4 原 hook exit 0(stderr only),保持向後兼容不升 WORST
+  fi
+fi
+
+exit $WORST

package/ds-canonical/hooks/check_file_size_budget.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: enforce per-file line budgets for governance files.
+#
+# Budgets — SSOT 是 CLAUDE.md `# 治理 canonical` 「行數預算」段。
+# 本檔不再硬寫(避免 漂移 — 2026-05-15 Fix 4 per sub-agent a9e6d53c finding 6:
+# 之前硬寫 400 vs CLAUDE.md「target 200 / transition 400 / hard cap 800」三 home 三 baseline)。
+# 改 dynamic 從 CLAUDE.md grep,fallback 寫死值。SSOT 改一處全處跟動。
+#
+# Non-blocking: injects warning via hookSpecificOutput additionalContext; Claude
+# decides whether to split or ack. Hard block would paralyse edits to legitimately
+# large canonical specs (e.g. item-anatomy ~900 lines) — require explicit override.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+[ -z "$FILE_PATH" ] && exit 0
+[ -f "$FILE_PATH" ] || exit 0
+
+# Only check governance files
+# CLAUDE.md L34 SSOT: target ≤ 200(Anthropic best-practice)/ transition ≤ 400 / hard cap 800
+# 本 hook 在 transition 觸發 P1 warning,hard cap 觸發 P0 block
+case "$FILE_PATH" in
+  */CLAUDE.md)                          BUDGET=400;  TRANSITION=800; LABEL="CLAUDE.md" ;;  # warn at transition (400), block at hard cap (800); target 200
+  */memory/*.md)                        BUDGET=100;  TRANSITION=100; LABEL="memory file" ;;
+  # Super-foundational SSOT spec(item-anatomy = Family 1+2 跨 10+ 消費者 SSOT,唯一例外)
+  */item-anatomy.spec.md)
+    BUDGET=800;  TRANSITION=1200; LABEL="super-foundational SSOT spec.md(item-anatomy 例外)" ;;
+  # Foundational SSOT specs(2026-04-24 升 cap 800 — spec 內部有 rationale section)
+  # 2026-05-18 加 data-table:DS 最複雜 composite + 跨家族 anchor(L1-L4 完整 grid taxonomy,
+  # 行對齊 item-anatomy / 浮層對齊 overlay-surface / state 對齊 field-controls)。
+  # frontmatter 已標 `foundational_ssot: true`。
+  # 2026-05-22 prune:color.spec.md 升 tier 2 cap 1000(per CLAUDE.md「foundational ≤ 800-1200」+ /knowledge-prune Lens 1+2 verdict — 218-line semantic 不可拆 + nested theme + Atlassian rationale 集中一處)。
+  */color.spec.md)
+    BUDGET=800;  TRANSITION=1000; LABEL="foundational SSOT spec.md(color tier 2 cap 1000)" ;;
+  */sidebar.spec.md|*/tree-view.spec.md|*/data-table.spec.md)
+    BUDGET=500;  TRANSITION=800; LABEL="foundational SSOT spec.md" ;;
+  *.spec.md)                            BUDGET=300;  TRANSITION=500; LABEL="spec.md" ;;
+  *.claude/skills/*/SKILL.md)           BUDGET=250;  TRANSITION=400; LABEL="SKILL.md" ;;
+  *) exit 0 ;;
+esac
+
+LINES=$(wc -l < "$FILE_PATH" | tr -d ' ')
+[ "$LINES" -le "$BUDGET" ] && exit 0
+
+# Over budget — warn. Hard-block only if also over transition cap.
+if [ "$LINES" -gt "$TRANSITION" ]; then
+  MSG="⛔ ${LABEL} at ${FILE_PATH} is ${LINES} lines (hard cap ${TRANSITION}). Must reduce before adding. Run /knowledge-prune or identify which section to remove."
+else
+  MSG="⚠️ ${LABEL} at ${FILE_PATH} is ${LINES} lines (budget ${BUDGET}, transition cap ${TRANSITION}). Prefer consolidating over appending. What can you remove/merge to make room?"
+fi
+
+ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+exit 0

package/ds-canonical/hooks/check_header_with_tabs_border.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# Header canonical W1 Border ownership enforcement(per header-canonical.spec.md W1):
+#   Header 含 Tabs(`<Tabs>` / `<TabsList>` child)→ 必標 `withTabs` prop 讓 border auto-suppress。
+#
+# PreToolUse(Edit / Write)hook:
+#   讀 post-edit 完整 content(disk + new_string merge)→ count(header) ≥ 1 + count(tabs) ≥ 1
+#   時要求 count(withTabs) ≥ count(header)。違反 = BLOCKER。
+#
+# 2026-05-17 Round 3:用 simple grep counting(per-instance awk 在 macOS bash 環境不穩定)。
+# 在「同 file 一 header 一 withTabs」常規 case 抓得到;edge case(混用 instance)需 audit dim 52
+# batch verify 補。
+#
+# Allow escape:檔頭 `// @header-withtabs-allow:` 整檔豁免。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+case "${FILE_PATH:-}" in
+  */packages/design-system/src/**/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+# Skip stories
+case "${FILE_PATH:-}" in
+  *.stories.tsx|*.anatomy.stories.tsx|*.principles.stories.tsx) exit 0 ;;
+esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  if .tool_input.new_string then .tool_input.new_string
+  elif .tool_input.content then .tool_input.content
+  else "" end
+')
+
+DISK_CONTENT=""
+if [ -f "$FILE_PATH" ]; then
+  DISK_CONTENT=$(cat "$FILE_PATH")
+fi
+
+FULL_CONTENT=$(printf '%s\n%s' "${DISK_CONTENT:-}" "${NEW_CONTENT:-}")
+
+if echo "${FULL_CONTENT:-}" | grep -qE '@header-withtabs-allow:'; then
+  exit 0
+fi
+
+# GAP 2 fix(2026-05-18 M34 codify):broaden hardcoded 6-name allowlist 到 generic [A-Z]*Header pattern。
+# 對齊 header-canonical.spec.md「任何 header 含 Tabs」+「未來 Drawer / Card / Table header」前瞻
+HEADERS=$(echo "$FULL_CONTENT" | grep -cE '<[A-Z][a-zA-Z]*Header[[:space:]>]' 2>/dev/null)
+HEADERS=$(echo "${HEADERS:-0}" | head -1)
+TABS=$(echo "$FULL_CONTENT" | grep -cE '<(Tabs|TabsList|TabsTrigger)[[:space:]>]' 2>/dev/null)
+TABS=$(echo "${TABS:-0}" | head -1)
+WITHTABS=$(echo "$FULL_CONTENT" | grep -cE 'withTabs([[:space:]]*=|[[:space:]]*[}>]|[[:space:]]*$)' 2>/dev/null)
+WITHTABS=$(echo "${WITHTABS:-0}" | head -1)
+
+# 若無 header 或無 tabs → 不適用
+if [ "${HEADERS:-0}" -lt 1 ] 2>/dev/null || [ "${TABS:-0}" -lt 1 ] 2>/dev/null; then
+  exit 0
+fi
+
+# 要求 withTabs 出現 ≥ 1 次(寬鬆檢查;per-instance precise 留 Dim 52 batch verify)
+if [ "${WITHTABS:-0}" -lt 1 ] 2>/dev/null; then
+  printf '🚨 HEADER + TABS WITHTABS BLOCKER(header-canonical.spec.md W1):\n' >&2
+  printf '   File: %s\n' "$FILE_PATH" >&2
+  printf '   檔含 %s 個 header JSX + %s 個 Tabs JSX,但 withTabs prop 出現 0 次。\n' "$HEADERS" "$TABS" >&2
+  printf '   Header `border-b` + TabsList `border-b border-border` 會雙線。\n' >&2
+  printf '\n  SSOT: patterns/header-canonical/header-canonical.spec.md W1\n' >&2
+  printf '  修方向: <ChromeHeader withTabs> 或 <SurfaceHeader withTabs>\n' >&2
+  printf '  Escape: 檔頭加 // @header-withtabs-allow: <rationale>\n' >&2
+  exit 2
+fi
+
+# 警告(per-instance 精度不夠 — 若 header > withTabs,某 instance 可能漏):
+if [ "${WITHTABS:-0}" -lt "${HEADERS:-0}" ] 2>/dev/null; then
+  printf '⚠️ HEADER WITHTABS COUNT MISMATCH(W1 soft warn):\n' >&2
+  printf '   File: %s\n' "$FILE_PATH" >&2
+  printf '   header instance %s 個 / withTabs prop %s 個 — 可能有 instance 漏 prop\n' "$HEADERS" "$WITHTABS" >&2
+  printf '   ⚠️ 寬鬆模式 exit 0(不 block);Dim 52 batch verify 補 per-instance 精度\n' >&2
+fi
+
+exit 0

package/ds-canonical/hooks/check_main_branch_workbench.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Solo-work canonical 補丁(2026-05-17 user-mandated):
+#   既有 check_solo_workflow.sh R1-R3 抓「2nd branch / PR creation / push main 無 trigger」,
+#   但**不抓「整 session 在 main 上 edit production code」**(M28 sub-rule)。
+#
+# 本 hook 補:PreToolUse Edit/Write 偵測「current branch == main + edit production code
+# + 近 5 條 user msg 無「開 branch / 在 branch 上做」trigger keyword」→ BLOCKER。
+#
+# 對應 CLAUDE.md `# Git solo-work canonical` Step 1 「1 chat = 1 working branch」
+# + memory/feedback_solo_dev_workflow.md SSOT。
+#
+# 起因 2026-05-17:本 session AI 整個 deep audit + 補修 + a11y batch 全直接在 main edit,
+# user 抓「不是只有我說 push 到 main 才真的會 push 到 main 嗎」。R1 只抓 `claude/*` prefix
+# branch 數,沒抓「在 main edit」這個 root cause。
+#
+# Allow escape:
+#   - doc-only / governance-only edit(`.claude/**` / `*.spec.md`)豁免 — 不需 Netlify preview
+#   - `CLAUDE_BYPASS_MAIN_WORKBENCH=1` env var(audit-logged)
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# Only intercept production code edits (packages/design-system/src / src/app / src/explorations)
+case "${FILE_PATH:-}" in
+  */packages/design-system/src/**/*.tsx|*/packages/design-system/src/**/*.ts|*/packages/design-system/src/**/*.css) ;;
+  */src/app/**|*/src/explorations/**) ;;
+  *) exit 0 ;;
+esac
+
+# Skip if env override
+if [ "${CLAUDE_BYPASS_MAIN_WORKBENCH:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Detect current branch
+CURRENT_BRANCH=$(cd "${CLAUDE_PROJECT_DIR:-$(pwd)}" && git branch --show-current 2>/dev/null || echo "")
+
+if [ "${CURRENT_BRANCH:-}" != "main" ] && [ "${CURRENT_BRANCH:-}" != "master" ]; then
+  # Not on main — already on working branch, allow
+  exit 0
+fi
+
+# On main + edit production code → check recent user msg for branch trigger
+TRANSCRIPT="${CLAUDE_TRANSCRIPT_PATH:-}"
+TRIGGER_FOUND=0
+if [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
+  RECENT_USER=$(tail -200 "$TRANSCRIPT" 2>/dev/null | \
+    jq -r 'select(.role == "user") | .content' 2>/dev/null | tail -5 | tr '\n' ' ')
+  if echo "${RECENT_USER:-}" | grep -qE '(開.*branch|開.*分支|新.*branch|新.*分支|working branch|在.*branch.*做|在 branch|branch 上|on branch)'; then
+    TRIGGER_FOUND=1
+  fi
+fi
+
+if [ "$TRIGGER_FOUND" = "1" ]; then
+  # User explicitly approved branch work, allow
+  exit 0
+fi
+
+# BLOCKER: editing production code on main without explicit branch trigger
+cat >&2 <<EOF
+🚨 MAIN-AS-WORKBENCH BLOCKER(check_main_branch_workbench,2026-05-17 P0 codify)
+  - 目標: ${FILE_PATH}
+  - 範圍: packages/design-system/src / src/app / src/explorations(production code)
+  - 當前 branch: ${CURRENT_BRANCH}(= main / master)
+  - 近 5 條 user msg branch-trigger keyword: 0 次
+
+→ Solo-work canonical(CLAUDE.md \`# Git solo-work canonical\`+ memory/feedback_solo_dev_workflow.md SSOT):
+  1 chat = 1 working branch;production code edit **必先**:
+    git checkout -b <working-branch-name>
+  然後 commit + push working branch(觸發 Netlify preview),user trigger「push / 合 main」才 merge main。
+
+修法 — 2 選 1:
+  (a) 立刻開 working branch:
+       git checkout -b $(date +%Y-%m-%d)-<topic>
+      然後重試 Edit。
+  (b) Cite recent user verbatim 含「開 branch / working branch / 在 branch 上」trigger keyword
+      OR 設 CLAUDE_BYPASS_MAIN_WORKBENCH=1 跑(audit-logged)。
+
+歷史錨例(2026-05-17 起因):本 session 整個 deep audit + 56-element a11y batch + retire batch 全
+在 main 直接 edit,user 抓「不是只有我說 push 到 main 才真的會 push 到 main 嗎」。R1-R3 沒抓
+「main-as-workbench」這個 root cause,故升新 hook 攔。
+EOF
+exit 2

package/ds-canonical/hooks/check_naming_and_abstraction.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+# Naming + abstraction unified hook(2026-05-08 cluster D consolidation)
+#
+# Merges 3 PreToolUse hooks(原各檔已 retire,合併入此):
+#   D.1 premature abstraction(原 check_premature_abstraction,P0 BLOCK)
+#   D.2 internal namespace consistency(原 check_internal_namespace_consistency,P0 BLOCK)
+#   D.3 primitive color var in tsx(原 check_primitive_color_var_in_tsx,P1 WARN stderr)
+#
+# Why merge:皆 命名 / 抽象 / token 消費紀律 invariant,共用 INPUT parsing 模式。
+# 散裝是 M17 + Anthropic ≤ 15 hook best-practice 偏離。
+#
+# Per-rule scope 差異(必保留各自 narrow):
+#   D.1: Write only + components/X/X.tsx 或 spec.md 主檔 + 新檔
+#   D.2: Edit/Write/MultiEdit + *.stories.tsx
+#   D.3: Edit/Write/MultiEdit + *.tsx minus Tag/Avatar/Chart/tokens
+#
+# Per-rule allowlist:
+#   D.1: 檔頭 10 行內 `// @separate-component-rationale: <world-class refs + 3-test 通過理由>`
+#   D.2: (無 allowlist,但若 file 沒 title namespace 自動 skip)
+#   D.3: 行尾 `// @primitive-color-allow: <reason>` OR 檔頭 `// primitive-color-allow-blanket`
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+case "$TOOL" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  (.tool_input.content // "") + "\n" +
+  (.tool_input.new_string // "") + "\n" +
+  ([.tool_input.edits[]? | .new_string] | join("\n"))
+' 2>/dev/null || echo "")
+
+[ -z "${NEW_CONTENT//[[:space:]]/}" ] && exit 0
+
+WORST=0
+record_worst() { local lvl=$1; [ "$lvl" -gt "$WORST" ] && WORST=$lvl; }
+
+# ── D.1 premature abstraction(Write only,新元件 BLOCK)──────────────────────
+if [ "$TOOL" = "Write" ]; then
+  case "$FILE_PATH" in
+    */packages/design-system/src/components/*/[^.]*.tsx|*/packages/design-system/src/components/*/*.spec.md)
+      if [ ! -f "$FILE_PATH" ]; then
+        COMPONENT_DIR=$(echo "$FILE_PATH" | sed -E 's|.*/components/([^/]+)/.*|\1|')
+        SUFFIX=""
+        BASE_NAME=""
+        for SFX in Time Range Color Light Dark Filled Outline Compact Rich Variant; do
+          if [[ "$COMPONENT_DIR" =~ ${SFX}$ ]] && [ "$COMPONENT_DIR" != "$SFX" ]; then
+            BASE=$(echo "$COMPONENT_DIR" | sed -E "s/${SFX}$//")
+            [ -z "$BASE" ] && continue
+            COMPONENTS_ROOT=$(echo "$FILE_PATH" | sed -E 's|(.*/components)/.*|\1|')
+            if [ -d "$COMPONENTS_ROOT/$BASE" ]; then
+              SUFFIX="$SFX"; BASE_NAME="$BASE"; break
+            fi
+          fi
+        done
+        if [ -n "$SUFFIX" ]; then
+          # Allowlist:檔頭 10 行內 rationale comment
+          if ! echo "$NEW_CONTENT" | head -10 | grep -qE '//\s*@separate-component-rationale:|^\s*#?\s*@separate-component-rationale:'; then
+            cat >&2 <<EOF
+
+┄┄┄ D.1 check_naming_and_abstraction — premature abstraction BLOCKER ┄┄┄
+
+[P0] 新元件 \`${COMPONENT_DIR}\`(後綴 \`${SUFFIX}\`)
+基底元件 \`${BASE_NAME}\` 已存在 → 強烈 signal 應為 prop variant on \`${BASE_NAME}\`。
+
+歷史(M21):
+  - DateTimePicker → \`<DatePicker showTime>\`
+  - DataTableFilterPanel → sub-file pattern
+
+3-test 通過才能分:
+  1. \`${BASE_NAME}\` 加 prop 達不到同 DOM/behavior?
+  2. ≥3 家 world-class DS 用分離元件而非 prop?(必 cite source)
+  3. value 結構或 contract 真的不同(如 Range = [start, end])?
+
+通過 → spec.md 加 rationale + 檔頭 10 行內加:
+  // @separate-component-rationale: <world-class refs + 3-test 通過理由>
+
+EOF
+            record_worst 2
+          fi
+        fi
+      fi
+      ;;
+  esac
+fi
+
+# ── D.2 internal namespace consistency(stories sibling check,BLOCK)──────────
+case "$FILE_PATH" in
+  *.stories.tsx)
+    NEW_NS=$(printf '%s' "$NEW_CONTENT" | grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" | head -1 | grep -oE "(Components|Internal)" || true)
+    if [ -z "$NEW_NS" ] && [ -f "$FILE_PATH" ]; then
+      NEW_NS=$(grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" "$FILE_PATH" 2>/dev/null | head -1 | grep -oE "(Components|Internal)" || true)
+    fi
+    if [ -n "$NEW_NS" ]; then
+      DIR=$(dirname "$FILE_PATH")
+      INCONSISTENT=""
+      while IFS= read -r SIB; do
+        [ "$SIB" = "$FILE_PATH" ] && continue
+        [ -f "$SIB" ] || continue
+        SIB_NS=$(grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" "$SIB" 2>/dev/null | head -1 | grep -oE "(Components|Internal)" || true)
+        if [ -n "$SIB_NS" ] && [ "$SIB_NS" != "$NEW_NS" ]; then
+          INCONSISTENT="${INCONSISTENT}  - ${SIB} → ${SIB_NS}"$'\n'
+        fi
+      done < <(find "$DIR" -maxdepth 1 -name '*.stories.tsx' 2>/dev/null)
+      if [ -n "$INCONSISTENT" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ D.2 check_naming_and_abstraction — sibling stories namespace BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH} → ${NEW_NS}
+Sibling stories 不一致:
+${INCONSISTENT}
+3 stories(展示 / anatomy / principles)title namespace 必全 Components/ 或全 Internal/。
+
+決策:跑 CLAUDE.md「Internal vs Components 3-test」→ 把全 3 檔統一。
+
+EOF
+        record_worst 2
+      fi
+    fi
+    ;;
+esac
+
+# ── D.3 primitive color var in tsx(P1 WARN stderr only)──────────────────────
+case "$FILE_PATH" in
+  *.tsx)
+    case "$FILE_PATH" in
+      */components/Tag/*|*/components/Avatar/*|*/components/Chart/*|*/tokens/*) ;; # codified primitive-consumer skip
+      *)
+        if ! echo "$NEW_CONTENT" | grep -q 'primitive-color-allow-blanket'; then
+          VIOLATIONS_D3=$(printf '%s' "$NEW_CONTENT" | grep -nE 'var\(--color-[a-z]+-[0-9](-opaque)?\)' | grep -v 'primitive-color-allow' || true)
+          if [ -n "$VIOLATIONS_D3" ]; then
+            cat >&2 <<EOF
+
+┄┄┄ D.3 check_naming_and_abstraction — primitive color var WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+tsx 內直接消費 primitive token \`var(--color-*-N)\`:
+${VIOLATIONS_D3}
+
+⚠️  Token 命名 rule 4:禁 primitive 色名作 utility,用 semantic alias。
+修法 3 擇 1:
+  1. 加 semantic alias 在 tokens/color/semantic.css(consumer 用 semantic)
+  2. 既有 semantic 已存在 → \`var(--border)\` / \`var(--bg-disabled)\`
+  3. 例外(Tag / Avatar / Chart 自動 allowed): \`// @primitive-color-allow: <reason>\` 行尾豁免
+
+詳 tokens/color/color.spec.md「架構流派定位」+「Primitive 色票與 Tag / Avatar 的消費」。
+
+EOF
+          fi
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+exit $WORST