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

package/ds-canonical/hooks/lib/_provider_paths.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# Provider/canonical path resolver for canonical hooks.
+#
+# This file is sourced. Keep provider facts in packages/governance/canonical/providers.json;
+# hooks consume those facts through these functions instead of naming .claude/.codex homes.
+
+governance_corpus_root() {
+  local root="${GOVERNANCE_CORPUS_ROOT:-}"
+  if [ -z "$root" ]; then
+    local helper_dir
+    helper_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd -P)" || return 1
+    root="$(git -C "$helper_dir" rev-parse --show-toplevel 2>/dev/null || true)"
+  fi
+  [ -n "$root" ] && [ -d "$root" ] || return 1
+  (cd "$root" 2>/dev/null && pwd -P)
+}
+
+governance_provider_registry_file() {
+  local corpus registry
+  corpus="$(governance_corpus_root)" || return 1
+  registry="${GOVERNANCE_PROVIDER_REGISTRY:-$corpus/packages/governance/canonical/providers.json}"
+  registry="$(python3 - "$corpus" "$registry" <<'PY'
+import os
+import sys
+
+root = os.path.abspath(sys.argv[1])
+raw = sys.argv[2]
+target = os.path.abspath(raw if os.path.isabs(raw) else os.path.join(root, raw))
+try:
+    if os.path.commonpath([root, target]) != root:
+        raise ValueError('outside corpus')
+except ValueError:
+    raise SystemExit(2)
+cursor = root
+for segment in os.path.relpath(target, root).split(os.sep):
+    if segment == '.':
+        continue
+    cursor = os.path.join(cursor, segment)
+    if not os.path.lexists(cursor):
+        break
+    if os.path.islink(cursor):
+        raise SystemExit(2)
+print(target)
+PY
+)" || return 1
+  [ -f "$registry" ] && [ ! -L "$registry" ] || return 1
+  printf '%s\n' "$registry"
+}
+
+governance_registry_repository_path() {
+  local value="$1"
+  [ -n "$value" ] || return 1
+  case "$value" in
+    /*|*\\*|*//*|*$'\n'*|*$'\r'*) return 1 ;;
+  esac
+  case "/$value/" in
+    */../*|*/./*) return 1 ;;
+  esac
+  printf '%s\n' "${value#./}"
+}
+
+governance_canonical_relative_root() {
+  local key="$1" registry value
+  registry="$(governance_provider_registry_file)" || return 1
+  value=$(jq -er --arg key "$key" '.canonical.roots[$key] | select(type == "string" and length > 0)' "$registry" 2>/dev/null) || return 1
+  governance_registry_repository_path "$value"
+}
+
+governance_canonical_root() {
+  local corpus relative
+  corpus="$(governance_corpus_root)" || return 1
+  relative="$(governance_canonical_relative_root "$1")" || return 1
+  printf '%s\n' "$corpus/$relative"
+}
+
+governance_provider_string_field() {
+  local field="$1" registry provider value
+  provider="${GOVERNANCE_PROVIDER:-${GOVERNANCE_SELF_PROVIDER:-}}"
+  printf '%s' "$provider" | grep -qE '^[a-z][a-z0-9-]*$' || return 1
+  registry="$(governance_provider_registry_file)" || return 1
+  case "$field" in
+    instructionEntry|sharedInstructionEntry|skillDirectory|hookConfig) ;;
+    *) return 1 ;;
+  esac
+  value=$(jq -er --arg id "$provider" --arg field "$field" '
+    first(.providers[] | select(.id == $id) | .[$field])
+    | select(type == "string" and length > 0)
+  ' "$registry" 2>/dev/null) || return 1
+  governance_registry_repository_path "$value"
+}
+
+governance_provider_managed_roots() {
+  local registry provider values value count index=0
+  provider="${GOVERNANCE_PROVIDER:-${GOVERNANCE_SELF_PROVIDER:-}}"
+  printf '%s' "$provider" | grep -qE '^[a-z][a-z0-9-]*$' || return 1
+  registry="$(governance_provider_registry_file)" || return 1
+  values=$(jq -cer --arg id "$provider" '
+    first(.providers[] | select(.id == $id)) as $provider
+    | select($provider != null)
+    | [
+        $provider.skillDirectory,
+        ($provider.adapter.repositoryManagedTrees // {} | to_entries[]?.value)
+      ]
+    | map(select(type == "string" and length > 0))
+    | unique
+  ' "$registry" 2>/dev/null) || return 1
+  count=$(printf '%s' "$values" | jq -er 'length' 2>/dev/null) || return 1
+  while [ "$index" -lt "$count" ]; do
+    value=$(printf '%s' "$values" | jq -er --argjson index "$index" '.[$index]' 2>/dev/null) || return 1
+    governance_registry_repository_path "$value" || return 1
+    index=$((index + 1))
+  done
+}
+
+governance_provider_skill_entry_file() {
+  local registry provider
+  provider="${GOVERNANCE_PROVIDER:-${GOVERNANCE_SELF_PROVIDER:-}}"
+  printf '%s' "$provider" | grep -qE '^[a-z][a-z0-9-]*$' || return 1
+  registry="$(governance_provider_registry_file)" || return 1
+  jq -er --arg id "$provider" '
+    first(.providers[] | select(.id == $id)) as $provider
+    | $provider.adapter.skillView.materializerId as $materializer
+    | select($materializer | type == "string")
+    | .canonical.materializers.skillViews[$materializer].entryFile
+    | select(type == "string" and test("^[A-Z][A-Z0-9_-]*\\.md$"))
+  ' "$registry" 2>/dev/null
+}
+
+governance_project_root() {
+  local project="${GOVERNANCE_PROJECT_DIR:-$(pwd)}"
+  [ -n "$project" ] && [ -d "$project" ] || return 1
+  (cd "$project" 2>/dev/null && pwd -P)
+}
+
+governance_project_relative_path() {
+  local project target="$1"
+  project="$(governance_project_root)" || return 1
+  python3 - "$project" "$target" <<'PY'
+import os
+import sys
+
+root = os.path.realpath(os.path.abspath(sys.argv[1]))
+raw = sys.argv[2]
+target = os.path.realpath(os.path.abspath(raw if os.path.isabs(raw) else os.path.join(root, raw)))
+try:
+    if os.path.commonpath([root, target]) != root:
+        raise ValueError('outside project')
+except ValueError:
+    raise SystemExit(2)
+print(os.path.relpath(target, root).replace(os.sep, '/'))
+PY
+}
+
+governance_path_is_under() {
+  local candidate="${1#./}" root="${2#./}"
+  root="${root%/}"
+  [ -n "$root" ] || return 1
+  case "$candidate" in
+    "$root"|"$root"/*) return 0 ;;
+    *) return 1 ;;
+  esac
+}

package/ds-canonical/hooks/lib/_story_compile_drift.sh

@@ -12,7 +12,7 @@ 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')
+FILE_PATH=$(jq -r '.tool_input.file_path // empty' <<<"$INPUT")
 
 [ -z "$FILE_PATH" ] && exit 0
 
@@ -24,10 +24,10 @@ case "$FILE_PATH" in
 esac
 
 # Extract component name from path
-COMP_NAME=$(echo "$FILE_PATH" | grep -oE 'components/[^/]+/' | head -1 | sed 's|components/||' | sed 's|/||')
+COMP_NAME=$(grep -m 1 -oE 'components/[^/]+/' <<<"$FILE_PATH" | sed -n '1p' | sed 's|components/||' | sed 's|/||')
 [ -z "$COMP_NAME" ] && exit 0
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PROJECT_DIR="${GOVERNANCE_PROJECT_DIR:-$(pwd)}"
 COMPILE_SCRIPT="$PROJECT_DIR/scripts/compile-stories.mjs"
 
 # Skip if compile script not yet built(graceful for pre-Phase-4 state)
@@ -38,10 +38,10 @@ cd "$PROJECT_DIR" || exit 0
 OUTPUT=$(node "$COMPILE_SCRIPT" "$COMP_NAME" --check 2>&1 || true)
 
 # Check if drift detected(exit 1 or has 「spec/tsx canonical drift」 in output)
-if echo "$OUTPUT" | grep -qE "spec/tsx canonical drift|spec-only|tsx-only"; then
+if grep -qE "spec/tsx canonical drift|spec-only|tsx-only" <<<"$OUTPUT"; then
   MSG="📐 Story canonical drift detected in ${COMP_NAME}:\n\n${OUTPUT}\n\nFix tsx componentMeta export 或 spec frontmatter 讓 keys 對齊。"
   ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
-  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+  printf '{"governanceContext":{"hookEventName":"PostToolUse","message":%s}}\n' "$ESCAPED"
 fi
 
 # Skip graceful(migration 未做的元件)不報

package/ds-canonical/hooks/lib/_tab_lg_chrome_header_equal.sh

@@ -0,0 +1,290 @@
+#!/bin/bash
+set -uo pipefail
+# Header canonical W3 Token alignment enforcement(per header-canonical.spec.md W3):
+#   --tab-height-lg 與 --chrome-header-height(uiSize.css)必像素相等。
+#   兩 token scope 不同(uiSize 是 component-size reset / chrome-header-height 是 app-density)
+#   不該 CSS alias(綁死兩個不同 scope)— 改用 assert: parse 兩檔 md/lg 值對等。
+#
+# PreToolUse(Edit / Write)hook —— 編輯 `packages/design-system/src/tokens/uiSize/uiSize.css` 或
+# `src/globals.css` 時 assert 兩值仍相等。動一方未同步 = BLOCKER。
+#
+# 對齊 M31 codex 比稿 Step 5「保留 duplicated literals + audit hook assert equality」decision。
+
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+fail_integrity() {
+  printf '🚨 GOVERNANCE_INTEGRITY: TAB_LG vs CHROME_HEADER_HEIGHT ENFORCEMENT FAILURE: %s\n' "$1" >&2
+  exit 70
+}
+
+INPUT=$(cat) || fail_integrity '無法讀取 hook input'
+if ! printf '%s' "$INPUT" | jq -e '
+  type == "object"
+  and (.tool_name | type == "string")
+  and (.tool_input | type == "object")
+  and (.tool_input.file_path | type == "string")
+' >/dev/null 2>&1; then
+  fail_integrity 'hook input 不是有效的 provider-neutral event'
+fi
+
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name')
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path')
+
+case "$TOOL" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+case "$FILE_PATH" in
+  packages/design-system/src/tokens/uiSize/uiSize.css|*/packages/design-system/src/tokens/uiSize/uiSize.css|src/globals.css|*/src/globals.css) ;;
+  *) exit 0 ;;
+esac
+
+# Provider-neutral runner 會供應已驗證的 GOVERNANCE_PROJECT_DIR。直接執行 canonical
+# source 時以 Git root 回退；只有無 Git metadata 的獨立測試沙箱才使用 legacy 投影深度。
+# 不可只從 $0 固定上溯：同一 SSOT 在 ds-canonical 與 provider projection 的深度不同。
+if [ -n "${GOVERNANCE_PROJECT_DIR:-}" ]; then
+  PROJECT_ROOT="$(cd "$GOVERNANCE_PROJECT_DIR" 2>/dev/null && pwd -P)" || {
+    fail_integrity 'GOVERNANCE_PROJECT_DIR 無法解析'
+  }
+elif PROJECT_ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel 2>/dev/null)" \
+  && [ -n "$PROJECT_ROOT" ]; then
+  PROJECT_ROOT="$(cd "$PROJECT_ROOT" 2>/dev/null && pwd -P)" || {
+    fail_integrity 'Git root 無法解析'
+  }
+else
+  PROJECT_ROOT="$(cd "$(dirname "$0")/../../.." 2>/dev/null && pwd -P)" || {
+    fail_integrity 'project root 無法解析'
+  }
+fi
+
+UISIZE_REL='packages/design-system/src/tokens/uiSize/uiSize.css'
+UISIZE_CSS="$PROJECT_ROOT/$UISIZE_REL"
+TOKEN_CONTENT=''
+
+path_matches() {
+  local actual="$1"
+  local expected="$2"
+  [[ "$actual" == "$expected" || "$actual" == */"$expected" ]]
+}
+
+read_canonical_tokens() {
+  if [ ! -f "$UISIZE_CSS" ] || [ -L "$UISIZE_CSS" ] || [ ! -r "$UISIZE_CSS" ]; then
+    fail_integrity 'canonical token source 缺失、不可讀或不是一般非 symlink 檔案'
+  fi
+  TOKEN_CONTENT=$(cat -- "$UISIZE_CSS") \
+    || fail_integrity 'canonical token source 讀取失敗'
+}
+
+# runner-v1 是唯一可把 in-memory proposed state 標成可信的 transport。uiSize
+# 自身被改時絕不可讀 pre-edit disk；globals.css 只是 trigger path，token SSOT 沒被
+# 這次 mutation 改動，故仍安全讀 canonical uiSize.css。
+if [ "${GOVERNANCE_WRITE_STATE_TRUST:-}" = 'runner-v1' ]; then
+  if ! printf '%s' "$INPUT" | jq -e '
+    .tool_input.governance_write_state as $state
+    | ($state | type == "object")
+      and ($state.schemaVersion == 1)
+      and ($state.path | type == "string" and length > 0)
+      and (
+        ($state.kind == "text" and ($state.content | type == "string"))
+        or ($state.kind == "deleted" and ($state | has("content") | not))
+      )
+  ' >/dev/null 2>&1; then
+    fail_integrity 'trusted proposed write state 缺失或 malformed'
+  fi
+  STATE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.governance_write_state.path')
+  STATE_KIND=$(printf '%s' "$INPUT" | jq -r '.tool_input.governance_write_state.kind')
+  if ! path_matches "$FILE_PATH" "$STATE_PATH"; then
+    fail_integrity 'trusted proposed write state 與 hook target 不相符'
+  fi
+  if path_matches "$STATE_PATH" "$UISIZE_REL"; then
+    [ "$STATE_KIND" = 'text' ] \
+      || fail_integrity 'canonical token source 不可由 proposed mutation 刪除'
+    TOKEN_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.governance_write_state.content')
+  else
+    read_canonical_tokens
+  fi
+else
+  read_canonical_tokens
+fi
+
+# CSS comments 不具 runtime declarations；parser 必先移除完整 block comments，且
+# unclosed comment 要 fail closed。否則把全部 token blocks 包進 `/* ... */` 仍會
+# 被純 regex 誤算為有效。
+if ! TOKEN_CODE=$(
+  printf '%s\n' "$TOKEN_CONTENT" | awk '
+    BEGIN { in_comment = 0 }
+    {
+      rest = $0
+      output = ""
+      while (length(rest) > 0) {
+        if (in_comment) {
+          comment_end = index(rest, "*/")
+          if (comment_end == 0) {
+            rest = ""
+          } else {
+            rest = substr(rest, comment_end + 2)
+            in_comment = 0
+          }
+        } else {
+          comment_start = index(rest, "/*")
+          if (comment_start == 0) {
+            output = output rest
+            rest = ""
+          } else {
+            output = output substr(rest, 1, comment_start - 1)
+            rest = substr(rest, comment_start + 2)
+            in_comment = 1
+          }
+        }
+      }
+      print output
+    }
+    END {
+      if (in_comment) exit 2
+    }
+  '
+); then
+  fail_integrity 'canonical token source 含未閉合 CSS block comment'
+fi
+
+# 只接受三個既定 scope，且 declaration 必依 root → lg override → md-reset
+# 順序各出現一次。這同時拒絕寬鬆 `[0-9.]+` 曾接受的 `.5`、`1..2` 等值。
+# 先做全文 occurrence guard，避免把同一行 inline declaration 或額外 override
+# 藏在 canonical line parser 看不到的位置。
+TAB_DECLARATION_COUNT=$(
+  printf '%s\n' "$TOKEN_CODE" \
+    | awk '
+        {
+          rest = $0
+          while (match(rest, /--tab-height-lg[[:space:]]*:/)) {
+            count += 1
+            rest = substr(rest, RSTART + RLENGTH)
+          }
+        }
+        END { print count + 0 }
+      '
+) || fail_integrity '無法計數 --tab-height-lg declarations'
+CHROME_DECLARATION_COUNT=$(
+  printf '%s\n' "$TOKEN_CODE" \
+    | awk '
+        {
+          rest = $0
+          while (match(rest, /--chrome-header-height[[:space:]]*:/)) {
+            count += 1
+            rest = substr(rest, RSTART + RLENGTH)
+          }
+        }
+        END { print count + 0 }
+      '
+) || fail_integrity '無法計數 --chrome-header-height declarations'
+if [ "$TAB_DECLARATION_COUNT" != '3' ] || [ "$CHROME_DECLARATION_COUNT" != '3' ]; then
+  fail_integrity 'canonical token extraction 不完整、重複或 scope/order 非預期'
+fi
+
+RECORDS=()
+while IFS= read -r record; do
+  [ -n "$record" ] && RECORDS+=("$record")
+done < <(
+  printf '%s\n' "$TOKEN_CODE" | awk '
+    BEGIN { context = ""; pending = "" }
+    /^[[:space:]]*:root[[:space:]]*\{/ {
+      context = "root"
+      next
+    }
+    /^[[:space:]]*\[data-ui-size="lg"\][[:space:]]*,[[:space:]]*$/ {
+      pending = "lg"
+      next
+    }
+    pending == "lg" && /^[[:space:]]*\[data-density="lg"\][[:space:]]*\{/ {
+      context = "lg"
+      pending = ""
+      next
+    }
+    /^[[:space:]]*\[data-ui-size="md"\][[:space:]]*,[[:space:]]*$/ {
+      pending = "md-reset"
+      next
+    }
+    pending == "md-reset" && /^[[:space:]]*\[data-density="md"\][[:space:]]*\{/ {
+      context = "md-reset"
+      pending = ""
+      next
+    }
+    /^[[:space:]]*}/ {
+      context = ""
+      pending = ""
+      next
+    }
+    /^[[:space:]]*--(tab-height-lg|chrome-header-height)[[:space:]]*:/ {
+      line = $0
+      if (context == "" || line !~ /^[[:space:]]*--(tab-height-lg|chrome-header-height):[[:space:]]*(0|[1-9][0-9]*)(\.[0-9]+)?rem[[:space:]]*;[[:space:]]*$/) {
+        print "INVALID"
+        next
+      }
+      name = line
+      sub(/^[[:space:]]*--/, "", name)
+      sub(/:.*/, "", name)
+      value = line
+      sub(/^[^:]*:[[:space:]]*/, "", value)
+      sub(/rem[[:space:]]*;.*/, "", value)
+      print context "|" name "|" value
+    }
+  '
+)
+
+EXPECTED_RECORDS=(
+  'root|tab-height-lg'
+  'root|chrome-header-height'
+  'lg|tab-height-lg'
+  'lg|chrome-header-height'
+  'md-reset|tab-height-lg'
+  'md-reset|chrome-header-height'
+)
+
+if [ "${#RECORDS[@]}" -ne "${#EXPECTED_RECORDS[@]}" ]; then
+  fail_integrity 'canonical token extraction 不完整、重複或 scope/order 非預期'
+fi
+
+VALUES=()
+for index in "${!EXPECTED_RECORDS[@]}"; do
+  record="${RECORDS[$index]}"
+  expected="${EXPECTED_RECORDS[$index]}"
+  if [ "$record" = 'INVALID' ] || [ "${record%|*}" != "$expected" ]; then
+    fail_integrity 'canonical token declaration 的 scope、順序或 decimal rem syntax 非預期'
+  fi
+  VALUES+=("${record##*|}")
+done
+
+ERRORS=()
+CONTEXTS=('root' 'lg' 'md-reset')
+normalize_decimal() {
+  local value="$1"
+  if [[ "$value" == *.* ]]; then
+    while [[ "$value" == *0 ]]; do value="${value%0}"; done
+    value="${value%.}"
+  fi
+  printf '%s' "$value"
+}
+for pair_index in 0 1 2; do
+  value_index=$((pair_index * 2))
+  tab_value="${VALUES[$value_index]}"
+  chrome_value="${VALUES[$((value_index + 1))]}"
+  if [ "$(normalize_decimal "$tab_value")" != "$(normalize_decimal "$chrome_value")" ]; then
+    ERRORS+=("${CONTEXTS[$pair_index]}: --tab-height-lg=$tab_value rem ≠ --chrome-header-height=$chrome_value rem")
+  fi
+done
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+  printf '🚨 TAB_LG vs CHROME_HEADER_HEIGHT EQUAL BLOCKER(header-canonical.spec.md W3):\n' >&2
+  for E in "${ERRORS[@]}"; do
+    printf '   • %s\n' "$E" >&2
+  done
+  printf '\n  動一方必同步另一方(三個 scope 的兩 token 像素相等是 SSOT linkage 鐵證)\n' >&2
+  printf '  SSOT: packages/design-system/src/patterns/header-canonical/header-canonical.spec.md W3\n' >&2
+  printf '  修方向:在 uiSize.css 同步 --tab-height-lg 與 --chrome-header-height\n' >&2
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/lib/_token_hygiene.sh

@@ -1,13 +1,14 @@
 #!/bin/bash
-# PostToolUse hook: catch 4 classes of token hygiene / cross-OS violations on component/pattern tsx edits.
+# PostToolUse hook: catch 5 classes of token hygiene / cross-OS violations on component/pattern tsx edits.
 #
-# Detects (ALL are silent-fail or cross-OS drift bug classes per CLAUDE.md):
+# Detects (ALL are silent-fail or cross-OS drift bug classes per canonical token/rule corpus):
 # 1. shadcn compat alias 回流 — bg-popover / text-muted-foreground / bg-accent / text-accent-foreground / text-popover-foreground / bg-destructive / bg-background / bg-card / border-input / text-primary-foreground
 #    (these are shadcn safety-net aliases; our DS code MUST use direct tokens)
 # 2. Tailwind v4 `[--foo]` shorthand — must be `var(--foo)` wrapped; historical bug:
 #    Sidebar's `w-[--sidebar-width]` broke 8 places (silent fail, no error)
-# 3. Hardcoded Tailwind shadow — `shadow-sm/md/lg/xl/2xl` is forbidden; must use `shadow-[var(--elevation-*)]`
-# 4. Native overflow-{auto,scroll} without ScrollArea — cross-OS scrollbar drift
+# 3. Hardcoded Tailwind shadow — `shadow-sm/md/lg/xl/2xl` is forbidden; must use `shadow-[var(--elevation-N)] N∈{100,200}`
+# 4. primitive color name used as Tailwind utility — bg-neutral-3 / text-blue-6 silent-fail; use semantic utility or var()
+# 5. Native overflow-{auto,scroll} without ScrollArea — cross-OS scrollbar drift
 #    (macOS overlay 不吃寬 / Windows always-visible 吃 17px = 跨 OS 跑版)
 #    應改用 ScrollArea(Components/ScrollArea/)— overlay scrollbar 跨 OS 一致
 #
@@ -15,14 +16,18 @@
 
 # Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
 source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$(dirname "$0")/_provider_paths.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: token hygiene corpus resolver unavailable\n' >&2
+  exit 70
+}
 
 FILE_PATH=$(jq -r '.tool_input.file_path // empty')
 
 # Scope: only design-system component / pattern .tsx files (not stories, not specs)
-if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/(components|patterns)/.*\.tsx$'; then
+if ! grep -qE 'packages/design-system/src/(components|patterns)/.*\.tsx$' <<<"$FILE_PATH"; then
   exit 0
 fi
-if echo "$FILE_PATH" | grep -qE '\.stories\.tsx$'; then
+if grep -qE '\.stories\.tsx$' <<<"$FILE_PATH"; then
   exit 0
 fi
 if [ ! -f "$FILE_PATH" ]; then
@@ -34,10 +39,35 @@ VIOLATIONS=""
 # ── Check 1: shadcn compat alias 回流 ─────────────────────────────────────────
 # These are all shadcn safety-net aliases. Our code must use direct tokens instead.
 # bg-muted / bg-secondary / ring-ring are OUR tokens (kept), not listed here.
-SHADCN_PATTERN='\b(bg-popover|text-popover-foreground|text-muted-foreground|bg-accent|text-accent-foreground|bg-destructive|bg-background|bg-card|text-card-foreground|border-input|text-primary-foreground)\b'
-SHADCN_HITS=$(grep -nE "$SHADCN_PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
+# SSOT-drive(#87 2026-07-11):deny-list SSOT = the runner-authenticated utility registry.
+# Missing/malformed policy is an integrity failure; a hardcoded fallback would silently create a
+# second authority and let a mutable project installation weaken the canonical verdict.
+_CORPUS_ROOT=$(governance_corpus_root 2>/dev/null) || {
+  printf 'GOVERNANCE_INTEGRITY: token hygiene corpus root unavailable\n' >&2
+  exit 70
+}
+_REG="$_CORPUS_ROOT/packages/design-system/src/tokens/utility-registry.json"
+if [ -L "$_REG" ] || [ ! -f "$_REG" ] || [ ! -r "$_REG" ]; then
+  printf 'GOVERNANCE_INTEGRITY: token hygiene utility registry unavailable or unsafe\n' >&2
+  exit 70
+fi
+_SHADCN_LIST=$(jq -er '
+  select(
+    .schemaVersion == 1
+    and ._meta.owner == "packages/design-system/src/tokens/utility-registry.json"
+    and (._meta.provider_view_policy | type == "string" and length > 0)
+  )
+  | .shadcn_alias.block.color_alias
+  | select(type == "array" and length > 0 and (unique | length) == length)
+  | join("|")
+' "$_REG" 2>/dev/null) || {
+  printf 'GOVERNANCE_INTEGRITY: token hygiene utility registry invalid\n' >&2
+  exit 70
+}
+SHADCN_PATTERN="\\b(${_SHADCN_LIST})\\b"
+SHADCN_HITS=$(grep -m 5 -nE "$SHADCN_PATTERN" "$FILE_PATH" 2>/dev/null)
 if [ -n "$SHADCN_HITS" ]; then
-  VIOLATIONS="${VIOLATIONS}\n⚠️ shadcn compat alias found (必須遷移為 direct token):\n${SHADCN_HITS}\n  映射: bg-popover→bg-surface-raised / text-popover-foreground→text-foreground / text-muted-foreground→text-fg-muted / bg-accent→bg-neutral-hover / text-accent-foreground→text-foreground / bg-destructive→bg-error / bg-background→bg-canvas / bg-card→bg-surface / border-input→border-border / text-primary-foreground→text-white"
+  VIOLATIONS="${VIOLATIONS}\n⚠️ shadcn compat alias found (必須遷移為 direct token):\n${SHADCN_HITS}\n  映射: bg-popover→bg-surface-raised / text-popover-foreground→text-foreground / text-muted-foreground→text-fg-muted / bg-accent→bg-neutral-hover / text-accent-foreground→text-foreground / bg-destructive→bg-error / bg-background→bg-canvas / bg-card→bg-surface / text-card-foreground→text-foreground / border-input→border-border / text-primary-foreground→text-white /（其餘 registry alias → 對應 semantic token,見 tokens/color/semantic.css）"
 fi
 
 # ── Check 2: Tailwind v4 [--foo] shorthand (silent fail) ─────────────────────
@@ -45,18 +75,18 @@ fi
 # Matches: w-[--foo], h-[--bar-baz], shadow-[--elevation-100] 等
 # False positive exclusion: [&[data-...]] / [&:hover] 等 arbitrary variants (open bracket 後跟 & 或冒號)
 TWV4_PATTERN='\[--[a-z][a-z0-9-]*\]'
-TWV4_HITS=$(grep -nE "$TWV4_PATTERN" "$FILE_PATH" 2>/dev/null | grep -v '\[&' | head -5)
+TWV4_HITS=$(grep -nE "$TWV4_PATTERN" "$FILE_PATH" 2>/dev/null | grep -v '\[&' | awk 'NR <= 5')
 if [ -n "$TWV4_HITS" ]; then
   VIOLATIONS="${VIOLATIONS}\n⚠️ Tailwind v4 [--foo] shorthand found (silent fail,必須 var() 包覆):\n${TWV4_HITS}\n  修法:將 [--foo] 改為 [var(--foo)]"
 fi
 
 # ── Check 3: Hardcoded Tailwind shadow ────────────────────────────────────────
 # shadow-sm/md/lg/xl/2xl 是 Tailwind 預設,繞過 elevation token 系統——禁止.
-# 允許:shadow-none / shadow-[var(--elevation-*)] / shadow-[calc(...)]
+# 允許:shadow-none / shadow-[var(--elevation-N)] N∈{100,200} / shadow-[calc(...)]
 SHADOW_PATTERN='\bshadow-(sm|md|lg|xl|2xl|inner)\b'
-SHADOW_HITS=$(grep -nE "$SHADOW_PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
+SHADOW_HITS=$(grep -m 5 -nE "$SHADOW_PATTERN" "$FILE_PATH" 2>/dev/null)
 if [ -n "$SHADOW_HITS" ]; then
-  VIOLATIONS="${VIOLATIONS}\n⚠️ Tailwind default shadow found (禁用,必須用 elevation token):\n${SHADOW_HITS}\n  修法:shadow-sm→shadow-[var(--elevation-100)] / shadow-md→shadow-[var(--elevation-200)] / shadow-lg→shadow-[var(--elevation-300)]"
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Tailwind default shadow found (禁用,必須用 elevation token):\n${SHADOW_HITS}\n  修法:shadow-sm→shadow-[var(--elevation-100)] / shadow-md→shadow-[var(--elevation-200)] / shadow-lg→shadow-[var(--elevation-200)](2026-05-31 修:elevation-300 不存在,最高 tier 是 200)"
 fi
 
 # ── Check 4: primitive color name used as Tailwind utility (silent fail) ─────
@@ -68,7 +98,7 @@ fi
 # 歷史 bug:2026-04-22 FileItem compact static bg 用 `bg-neutral-3` 完全沒底色,
 # user 對照 Badge low 可見才發現;spec layer + 本 hook 同步修。
 PRIMITIVE_PATTERN='\b(bg|text|border|ring|fill|stroke|shadow|outline|decoration|divide|placeholder|caret|accent)-(neutral|blue|red|green|yellow|orange|purple|pink|cyan|teal|indigo|violet|deep-orange)-[0-9]+\b'
-PRIMITIVE_HITS=$(grep -nE "$PRIMITIVE_PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
+PRIMITIVE_HITS=$(grep -m 5 -nE "$PRIMITIVE_PATTERN" "$FILE_PATH" 2>/dev/null)
 if [ -n "$PRIMITIVE_HITS" ]; then
   VIOLATIONS="${VIOLATIONS}\n⚠️ Primitive color name used as Tailwind utility (silent fail):\n${PRIMITIVE_HITS}\n  修法:改用 semantic utility(bg-secondary / bg-muted / bg-surface / text-fg-muted 等)或 arbitrary value(bg-[var(--color-neutral-3)] 給 Tag categorical 色用)。理由:primitive token 沒經 @theme inline 橋接,bg-neutral-3 等會 silent 失效。"
 fi
@@ -79,17 +109,22 @@ fi
 # 應改用 ScrollArea(Components/ScrollArea/)。
 # 允許:horizontal-overflow pattern(有 scrollbar-none / fade-mask 特殊 UX)/
 #      use-overflow-items hook consumers(Tabs/ChipGroup hiding scroll)
+# 2026-06-11 deep-audit R2(n=29):豁免 regex 補認 [scrollbar-width:none] arbitrary 語法 —
+# Tabs(tabs.tsx:211,307)/ Chip(chip.tsx:173,298)hidden-scrollbar 實寫
+# `overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden`,與 FileViewer 的
+# `scrollbar-none` utility 同語意;舊 regex 只認後者 → 豁免失效噪音 warn。
+# 同輪補:剝離純註解行(grep -n 輸出 `N:content` 前綴)— Tabs tabs.tsx:126,173,176,239 等
+# rationale 註解提及 overflow-x-auto 屬說明文字,非 className 用法,不構成跨 OS scrollbar drift。
 OVERFLOW_PATTERN='\boverflow-(auto|scroll|x-auto|x-scroll|y-auto|y-scroll)\b'
-OVERFLOW_HITS=$(grep -nE "$OVERFLOW_PATTERN" "$FILE_PATH" 2>/dev/null | grep -vE 'scrollbar-none|useOverflow|horizontal-overflow' | head -5)
+# 2026-06-11 R2 Phase B(codex b3 抓縫):hidden-scrollbar 豁免限水平(overflow-x;canonical =
+# horizontal-overflow pattern)— vertical overflow-y-auto 配 scrollbar-width:none 不在 canonical,照 warn。
+OVERFLOW_HITS=$(grep -nE "$OVERFLOW_PATTERN" "$FILE_PATH" 2>/dev/null | grep -vE '^[0-9]+:[[:space:]]*(//|\*|/\*|\{/\*)' | grep -vE 'overflow-x-[a-z]+[^\n]*(scrollbar-none|\[scrollbar-width:none\])|(scrollbar-none|\[scrollbar-width:none\])[^\n]*overflow-x-[a-z]+' | grep -vE 'useOverflow|horizontal-overflow' | awk 'NR <= 5')
 if [ -n "$OVERFLOW_HITS" ]; then
   VIOLATIONS="${VIOLATIONS}\n⚠️ Native overflow-auto/scroll found (可能造成跨 OS 跑版):\n${OVERFLOW_HITS}\n  考慮改用 ScrollArea(\`@/design-system/components/ScrollArea/scroll-area\`)取得跨 OS 一致 overlay 捲軸。例外:刻意隱藏捲軸(scrollbar-none)+ fade-mask UX 屬 horizontal-overflow pattern,不套用本規則。"
 fi
 
 # ── Emit warning if any violation found ────────────────────────────────────
 if [ -n "$VIOLATIONS" ]; then
-  # Escape for JSON (newlines)
-  ESCAPED=$(printf "%b" "$VIOLATIONS" | jq -Rs .)
-  cat <<EOJSON
-{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Token hygiene 檢查發現違規 (CLAUDE.md 明文禁止項):${ESCAPED}\n\n這些是 silent-fail bug classes——不會造成 compile error,但 runtime 視覺或行為會壞。下個 Edit 回去修。"}}
-EOJSON
+  CTX=$(printf 'Token hygiene 檢查發現違規 (provider-neutral canonical 禁止項):%b\n\n這些是 silent-fail bug classes——不會造成 compile error,但 runtime 視覺或行為會壞。下個 Edit 回去修。' "$VIOLATIONS")
+  jq -n --arg ctx "$CTX" '{governanceContext:{hookEventName:"PostToolUse",message:$ctx}}'
 fi