@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/ds-canonical/hooks/check_dim_count_drift.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: enforce audit dim count SSOT integrity.
+#
+# SSOT: `.claude/skills/design-system-audit/SKILL.md` `## The N audit dimensions` 段。
+# 任何 chain it 的 skill / spec / rule / hook 禁 hardcode 具體 dim 數字
+# (e.g. `46 dim` / `53 dim` / `53-dim` / `53 audit dimensions`)— 用「全 dim」/
+# 「Group A-P」/「per design-system-audit SSOT」表達。
+#
+# Why: 2026-05-18 user-mandated SSOT integrity after `deep-audit-cross-codex` skill
+# hardcode `53 dim` 9 處 → 若 design-system-audit 升 54 dim,chain skill 漂移。
+#
+# P1 soft warn (stderr exit 0) — Claude decides revert or escape with rationale.
+# SSOT file itself (design-system-audit/SKILL.md) is allowed to write the count.
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo 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
+
+# Skip the SSOT itself
+case "$FILE_PATH" in
+  */design-system-audit/SKILL.md) exit 0 ;;
+  */design-system-audit/references/*) exit 0 ;;
+esac
+
+# Only check files that potentially chain audit dim list
+case "$FILE_PATH" in
+  */deep-audit-cross-codex/*|*/rules/meta-patterns.md|*/CLAUDE.md|*/skills/*/SKILL.md|*/skills/*/references/*) ;;
+  *) 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
+
+# Detect hardcoded numeric dim count
+# Patterns: "53 dim" / "53-dim" / "53 audit dim" / "53 audit dimensions" / "46 dim" / "46-dim"
+# Exclude legitimate uses: "N dim" / "全 dim" / "<N>" placeholder / "1 dim" thru "9 dim" (could be reasonable refs)
+HARDCODE_HITS=$(echo "$NEW_CONTENT" | grep -oE '\b[1-9][0-9]+[ -]?(dim|audit dim|audit dimension)' | sort -u || true)
+
+# Allow if line contains "SSOT" / "禁" / "forbidden" / "example" / "anti-pattern" — these are invariant doc references
+ALLOWED_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b[1-9][0-9]+[ -]?(dim|audit dim|audit dimension)' 2>/dev/null | grep -E '(SSOT|禁|forbidden|example|anti-pattern|invariant|hardcode)' || true)
+
+if [ -n "$HARDCODE_HITS" ]; then
+  # Filter out allowed lines (invariant doc context)
+  VIOLATION_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b[1-9][0-9]+[ -]?(dim|audit dim|audit dimension)' 2>/dev/null | grep -vE '(SSOT|禁|forbidden|example|anti-pattern|invariant|hardcode)' || true)
+
+  if [ -n "$VIOLATION_LINES" ]; then
+    printf '⚠️ AUDIT DIM COUNT DRIFT(P1 soft):\n' >&2
+    printf '   File: %s\n' "$FILE_PATH" >&2
+    printf '   偵測到 hardcoded audit dim count:\n%s\n' "$VIOLATION_LINES" >&2
+    printf '\n  SSOT: `.claude/skills/design-system-audit/SKILL.md` `## The N audit dimensions`\n' >&2
+    printf '  修法: 改用「全 dim」/「Group A-P」/「per design-system-audit SSOT」表達\n' >&2
+    printf '       而非寫死「53 dim / 46 dim」等具體數字。\n' >&2
+    printf '  Why: chain skill 自動繼承 SSOT 變動,避免 design-system-audit 升 54 dim 時下游漂移。\n' >&2
+  fi
+fi
+
+exit 0

package/ds-canonical/hooks/check_field_controls_contracts.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# check_field_controls_contracts.sh — Stream C shared contracts(a)(b)(c) consolidated guardrail
+#
+# 2026-05-13 prune consolidation(per knowledge-prune Phase 2 P1):3 hook 合 1:
+#   - 原 check_field_placeholder_vocabulary.sh — contract (b)
+#   - 原 check_selected_renderer_symmetry.sh — contract (a)
+#   - 原 check_cell_metric_escape_hatches.sh — contract (c)
+# 同 PostToolUse Edit/Write target(Field family packages/design-system/src/components/*.tsx),
+# 合 1 hook 減少 hook count 從 27 → 25 回 soft cap 內,單一 entry settings.json。
+# 對齊 field-controls.spec.md 共享 contract (a) Selected value renderer / (b) Placeholder vocabulary /
+# (c) Cell surface metrics 3 段 canonical。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+[ "$EVENT" != "PostToolUse" ] && exit 0
+[ ! -f "$FILE_PATH" ] && exit 0
+
+VIOLATIONS=""
+
+# ── Contract (b) Placeholder vocabulary ───────────────────────────────────────
+# Scope: 所有 packages/design-system/src/components/*.tsx
+case "$FILE_PATH" in
+  */packages/design-system/src/components/*.tsx)
+    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@placeholder-vocabulary-allow:'; then
+      HITS=$(grep -nE 'emptyPlaceholder=\{(emptyText|searchEmpty|noResults|notFound)' "$FILE_PATH" 2>/dev/null)
+      if [ -n "$HITS" ]; then
+        VIOLATIONS="${VIOLATIONS}
+[contract (b) placeholder vocabulary]:
+${HITS}
+  → 違反 field-controls.spec.md「共享 contract (b)」:不可 silent 把 emptyText forward 成 emptyPlaceholder(trigger-empty)。
+  Fix:wrapper 加 \`placeholder\` prop(trigger empty SSOT)+ \`emptyText\` 僅傳 SelectMenu noResultsText。
+  Allow:檔首加 \`// @placeholder-vocabulary-allow: <reason>\`。"
+      fi
+    fi
+    ;;
+esac
+
+# ── Contract (a) Selected value renderer symmetry ─────────────────────────────
+# Scope:Combobox / Select / PeoplePicker only
+case "$FILE_PATH" in
+  */packages/design-system/src/components/Combobox/*.tsx|*/packages/design-system/src/components/Select/*.tsx|*/packages/design-system/src/components/PeoplePicker/*.tsx)
+    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@renderer-symmetry-allow:'; then
+      DEFINES_RENDERER=$(grep -cE '(tagRenderer|selectedItemRenderer)\?:\s*\(' "$FILE_PATH" 2>/dev/null || echo 0)
+      DEFINES_RENDERER=${DEFINES_RENDERER:-0}
+      if [ "$DEFINES_RENDERER" -gt 0 ]; then
+        EDIT_HITS=$(grep -cE 'tagRenderer\(.*\)|selectedItemRenderer\(.*\)' "$FILE_PATH" 2>/dev/null || echo 0)
+        EDIT_HITS=${EDIT_HITS:-0}
+        DISPLAY_LINES=$(grep -nE "mode\s*=*\s*'display'|resolvedMode\s*==*\s*'display'" "$FILE_PATH" 2>/dev/null | cut -d: -f1)
+        if [ "$EDIT_HITS" -gt 0 ] && [ -n "$DISPLAY_LINES" ]; then
+          HAS_RENDERER_IN_DISPLAY=0
+          for LN in $DISPLAY_LINES; do
+            END=$((LN + 60))
+            if awk -v s="$LN" -v e="$END" 'NR>=s && NR<=e' "$FILE_PATH" | grep -qE 'tagRenderer|selectedItemRenderer'; then
+              HAS_RENDERER_IN_DISPLAY=1
+              break
+            fi
+          done
+          if [ "$HAS_RENDERER_IN_DISPLAY" -eq 0 ]; then
+            VIOLATIONS="${VIOLATIONS}
+[contract (a) renderer symmetry]:
+${FILE_PATH}
+  → tagRenderer/selectedItemRenderer 定義於 props 但 display branch 沒消費 → edit-only。
+  違反 field-controls.spec.md「共享 contract (a)」:rich-display renderer 必被 display/readonly/disabled/edit 4 mode 共享。
+  Allow:檔首加 \`// @renderer-symmetry-allow: <reason>\`。"
+          fi
+        fi
+      fi
+    fi
+    ;;
+esac
+
+# ── Contract (c) Cell metric escape hatches ───────────────────────────────────
+# Scope:Combobox / Select / PeoplePicker only
+case "$FILE_PATH" in
+  */packages/design-system/src/components/Combobox/*.tsx|*/packages/design-system/src/components/PeoplePicker/*.tsx|*/packages/design-system/src/components/Select/*.tsx)
+    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@cell-metric-escape-allow:'; then
+      HARDCODE_HITS=$(grep -nE 'tagAreaPaddingLeftPx=\{[0-9]+\}' "$FILE_PATH" 2>/dev/null)
+      COND_NO_SURFACE=$(grep -nE 'tagAreaPaddingLeftPx=\{[^}]*\?[^}]*[0-9]+[^}]*\}' "$FILE_PATH" 2>/dev/null | grep -v "surface")
+      WARN=""
+      [ -n "$HARDCODE_HITS" ] && WARN="${WARN}
+[hardcode numeric without surface guard]:
+${HARDCODE_HITS}"
+      [ -n "$COND_NO_SURFACE" ] && WARN="${WARN}
+[conditional without surface check]:
+${COND_NO_SURFACE}"
+      if [ -n "$WARN" ]; then
+        VIOLATIONS="${VIOLATIONS}
+[contract (c) cell metric escape hatch]:
+${FILE_PATH}${WARN}
+  → 違反 field-controls.spec.md「共享 contract (c)」:cell 內禁 hardcode padding magic,改 \`useFieldSurface()\` + \`--table-cell-px\` 推導。
+  Fix pattern: tagAreaPaddingLeftPx={(!isEmpty && surface === 'form') ? 8 : undefined}
+  Allow:檔首加 \`// @cell-metric-escape-allow: <reason>\`。"
+      fi
+    fi
+    ;;
+esac
+
+if [ -n "$VIOLATIONS" ]; then
+  CTX="⚠️ Field controls shared contracts violation(consolidated check):${VIOLATIONS}"
+  jq -n --arg ctx "$CTX" '{
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+  }'
+fi

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