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

package/ds-canonical/hooks/check_propose_discipline.sh

@@ -0,0 +1,255 @@
+#!/bin/bash
+# check_propose_discipline.sh — Stop ×2 — propose 紀律(中文人話 + file:line cite;SSOT memory/feedback_propose_discipline.md)
+#
+# 2026-06-11 prune merge(user 拍板「照你建議做」;59→51 headroom):
+# #   r1_plain_chinese = 原 check_propose_plain_chinese.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+#   r2_cite_required = 原 check_propose_cite_required.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+# 原檔 → packages/design-system/ds-canonical/hooks/retired/2026-06-11-prune-merge/
+# 各規則跑在 pipeline 子 shell:規則內 exit 不中斷其他規則;任一 exit 2 → 整體 exit 2。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null) || {
+  printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: 無法讀取 canonical input\n' >&2
+  exit 70
+}
+if ! printf '%s' "$INPUT" | jq -e 'type == "object"' >/dev/null 2>&1; then
+  printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: invalid input envelope\n' >&2
+  exit 70
+fi
+
+r1_plain_chinese() {
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+TRANSCRIPT_PATH=$(jq -r '.transcript_path // ""' <<<"$INPUT" 2>/dev/null)
+AI_REPLY_TEXT=$(jq -r '.last_assistant_message // ""' <<<"$INPUT" 2>/dev/null)
+if [ -z "$AI_REPLY_TEXT" ] && [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+  # Legacy/versioned transcript fallback.  Native Stop last_assistant_message is the primary,
+  # provider-neutral contract and does not require an unstable transcript.
+  LAST_USER_LINE=$(grep -n '"role":"user"' "$TRANSCRIPT_PATH" 2>/dev/null | tail -1 | cut -d: -f1)
+  if [ -n "$LAST_USER_LINE" ]; then
+    AI_REPLY_TEXT=$(tail -n +$((LAST_USER_LINE+1)) "$TRANSCRIPT_PATH" 2>/dev/null | \
+      jq -r 'select(.message.role=="assistant") | .message.content // empty | if type=="string" then . else (.[]? | select(.type=="text") | .text // empty) end' 2>/dev/null)
+  fi
+fi
+
+[ -z "$AI_REPLY_TEXT" ] && exit 0
+
+# Decision prompt pattern(reply 結尾含 ASK)
+DECISION_RE='(回 [A-Z]|→ ?選 [A-Z]|等你(拍板|決策|回|看)|user 決策|user 拍板|拍板.{0,5}決|決策.{0,5}選|一字回|回 OK)'
+HAS_DECISION=$(echo "$AI_REPLY_TEXT" | grep -cE "$DECISION_RE" 2>/dev/null)
+HAS_DECISION=${HAS_DECISION:-0}
+
+[ "$HAS_DECISION" -eq 0 ] && exit 0
+
+# GAP 4 fix(2026-05-18 M34 codify):升級 narrow 17-keyword fixed list 到
+# Python unicode 中英夾雜 density detector(對齊 check_story_invariants.sh R5.5 fix template)。
+# Spec wording「任何沒中譯的縮寫 / 內部代號 / hook 名」廣義,hook 過去窄 keyword list 漏:
+# Earn-existence / compound-component / Polaris-aligned / wrapper-vs-primitive / Anchor preflight
+# / *-canonical-allow / L42-58 / check_xxx.sh 等。
+#
+# 升級邏輯:
+# (a) EXEMPT list:legitimate retained-English(framework/brand/DS API)
+# (b) Density measure:jargon-word count / total Chinese-char count ratio
+# (c) jargon = 英文 token 不在 EXEMPT(任何 alphanumeric word ≥ 3 char)
+JARGON_COUNT=$(python3 -c "
+import re, sys
+text = sys.stdin.read()
+EXEMPT = re.compile(r'\b(cva|Radix|Polaris|Material|Atlassian|Carbon|Ant|Apple|MUI|TanStack|shadcn|Recharts|cmdk|dnd-kit|TypeScript|JavaScript|API|UI|UX|Jira|Stripe|Notion|Figma|Linear|GitHub|Gmail|Dropbox|Slack|Spotify|Discord|Storybook|Tailwind|ARIA|WCAG|FAQ|HSL|CSS|HTML|DOM|DS|F[1-9]|TODO|FIXME|XXX|NOTE|README|MIT|JSON|YAML|TSX|CSS|HTTP|HTTPS|URL|UUID|REST|GraphQL|SDK|CDN|CI|CD|PR|RFC|MR|UI/UX|primary|secondary|tertiary|hover|focus|active|disabled|invalid|readonly|null|true|false|undefined|void)\b', re.I)
+words = re.findall(r'\b[a-zA-Z][a-zA-Z\-_]{2,}\b', text)
+jargon = [w for w in words if not EXEMPT.fullmatch(w)]
+print(len(jargon))
+" <<< "$AI_REPLY_TEXT" 2>/dev/null)
+JARGON_COUNT=${JARGON_COUNT:-0}
+
+# Threshold:含決策 prompt + jargon count ≥ 10 → warn(Python 計數較廣,threshold 提高)
+THRESHOLD=10
+
+if [ "$JARGON_COUNT" -ge "$THRESHOLD" ]; then
+  MESSAGE=$(printf '🟡 check_propose_plain_chinese WARN:本 turn reply 含 user 決策 prompt + jargon 密度 %s(threshold %s)\n\n→ 違反 propose-in-plain-chinese canonical(memory/feedback_propose_discipline.md SSOT)\n→ User 原話「請講具體人話,為何又跟智障一樣講人聽不懂的話」\n→ Rewrite reply:必含 3 段(發生什麼 / 影響什麼 / 各選項 outcome — 全中文具體,禁 jargon)' "$JARGON_COUNT" "$THRESHOLD")
+  printf '{"governanceContext":{"hookEventName":"Stop","message":%s}}\n' "$(printf '%s' "$MESSAGE" | jq -Rs .)"
+fi
+
+exit 0
+}
+
+r2_cite_required() {
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(jq -r '.hook_event_name // ""' <<<"$INPUT" 2>/dev/null)
+
+# Only fire on stop events (post-assistant turn)
+case "${EVENT:-}" in
+  Stop|SubagentStop) ;;
+  *) exit 0 ;;
+esac
+
+# Read the native provider-neutral final reply first; only use a versioned transcript as fallback.
+TRANSCRIPT=$(jq -r '.transcript_path // ""' <<<"$INPUT" 2>/dev/null)
+LAST_REPLY=$(jq -r '.last_assistant_message // ""' <<<"$INPUT" 2>/dev/null)
+if [ -z "$LAST_REPLY" ] && [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
+  LAST_REPLY_RAW=$(tail -200 "$TRANSCRIPT" 2>/dev/null | grep -E '"role":"assistant"|"type":"text"' | tail -50 | tr -d '\n')
+  LAST_REPLY="${LAST_REPLY_RAW:0:8000}"
+fi
+[ -z "$LAST_REPLY" ] && exit 0
+
+# Escape clause
+if grep -q 'propose-cite-skip' <<<"$LAST_REPLY"; then
+  exit 0
+fi
+
+# Detect claim keywords
+HAS_CLAIM=""
+for kw in '規定' '必配' '必須用' '必須是' '一定要' 'canonical 寫' 'spec 寫' '強制' 'DS spec 規定' '明文' 'mandate'; do
+  if grep -qF "$kw" <<<"$LAST_REPLY"; then
+    HAS_CLAIM="$kw"
+    break
+  fi
+done
+
+if [ -z "$HAS_CLAIM" ]; then
+  exit 0
+fi
+
+# Detect cite patterns.
+# The rule's intent is "a claim must be verifiable", so the accepted forms must cover every place a
+# verifiable claim can live — not only design-system file types. Governance and CI claims live in
+# .mjs/.sh/.yml/.json, and claims about provider behaviour can only be sourced to external product
+# documentation, which has no repo line number. Keeping the narrow list turned honest citations into
+# BLOCKERs (2026-08-02: citing run-provider-hook.mjs and the official sandboxing docs was rejected),
+# which is the same "predicate narrower than intent" defect M7 warns about.
+# Accept: <file>.<ext>:42 for the source types below | L42 | L42-50 | #L42 | line 42 | https://… URL
+#
+# Deploy previews are not sources. Every solo-workflow reply carries a per-branch Netlify preview URL
+# (AGENTS.md, Git solo-work canonical step 2/5), so counting any URL as a citation would switch this
+# check off for exactly the replies it is meant to police. Negative-list rather than allowlist: an
+# allowlist of "real" documentation hosts drifts and reproduces the too-narrow predicate this hook
+# was widened to fix.
+# Blank out the URL text only. Dropping whole lines would also discard a real file:line citation that
+# happens to share a line with the preview link. Host-anchored: `[^/[:space:]]*` before the
+# alternation means the match must land in the authority component, so a documentation URL that
+# merely mentions "localhost" in its path or fragment is not blanked (2026-08-04 adversarial
+# review). ajenchen.github.io is this repo's own deployed Storybook — a deploy artifact, not a
+# source; scoped to the exact host so genuinely external *.github.io documentation still counts.
+NON_SOURCE_URL='https?://[^/[:space:]]*(\.netlify\.app|localhost|127\.0\.0\.1|0\.0\.0\.0|ajenchen\.github\.io)[^[:space:]]*'
+CITE_CANDIDATES=$(sed -E "s#${NON_SOURCE_URL}#(deploy-preview)#g" <<<"$LAST_REPLY")
+HAS_CITE=""
+if grep -qE '\.(spec\.md|md|css|tsx|ts|mjs|cjs|js|json|sh|ya?ml|toml):[0-9]+|#L[0-9]+|line[[:space:]]+[0-9]+|L[0-9]+-[0-9]+|L[0-9]+|https?://[^[:space:]]+' <<<"$CITE_CANDIDATES"; then
+  HAS_CITE="found"
+fi
+
+if [ -z "$HAS_CITE" ]; then
+  cat >&2 << 'EOF'
+🚨 PROPOSE-WITHOUT-CITE BLOCKER(2026-05-27 user verbatim「沒有好好按照規則和 ssot 跑設計」)
+
+  你 reply 含 claim keyword(規定 / 必配 / 必須用 / canonical 寫 / spec 寫 / 強制)
+  但**無可驗證 cite**(`.spec.md:42` / `.tsx:42` / `.mjs:42` / `.sh:42` / `.yml:42` /
+  `L42` / `line 42` / 外部官方文件 URL 任一)。
+
+  Anchor 2026-05-27:我憑印象斷言「DS spec 規定 caption + muted」,user grep verify
+  發現 semantic.css L49 只是 token use-case 描述,**沒「必配」rule**。瞎掰造成 user
+  接受錯誤 propose 風險。
+
+  修方向 2 選 1:
+    (a) 補 cite — 把 spec / source path:line 補進 reply,讓 user verify
+    (b) 撤回 claim — 顯式打「撤回 claim:此條無 SSOT 依據」
+
+  Escape(極罕見):reply 含 `<!-- @propose-cite-skip: <rationale> -->`
+
+  對齊 M22 cite invariant 延伸到對話層 + mindset #2「不憑直覺發明」mechanical 強制。
+EOF
+  exit 2
+fi
+
+exit 0
+}
+
+_CAPTURE_DIR=$(mktemp -d "${TMPDIR:-/tmp}/check-propose-discipline.XXXXXX") || {
+  printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: output capture unavailable\n' >&2
+  exit 70
+}
+trap 'rm -rf -- "$_CAPTURE_DIR"' EXIT
+_CONTEXTS=""
+_RULE_INDEX=0
+
+for _rule in r1_plain_chinese r2_cite_required; do
+  _RULE_INDEX=$((_RULE_INDEX + 1))
+  _stdout="$_CAPTURE_DIR/$_RULE_INDEX.stdout"
+  _stderr="$_CAPTURE_DIR/$_RULE_INDEX.stderr"
+  printf '%s' "$INPUT" | "$_rule" >"$_stdout" 2>"$_stderr"
+  _rc=$?
+  case "$_rc" in
+    0)
+      if [ -s "$_stderr" ]; then
+        printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: rule %s rc0 產生 raw stderr\n' \
+          "$_rule" >&2
+        exit 70
+      fi
+      if [ -s "$_stdout" ]; then
+        if ! jq -e -s '
+          length == 1
+          and (.[0] |
+            type == "object"
+            and keys == ["governanceContext"]
+            and (.governanceContext |
+              type == "object"
+              and (keys | sort) == ["hookEventName", "message"]
+              and .hookEventName == "Stop"
+              and (.message | type == "string" and length > 0)
+            )
+          )
+        ' "$_stdout" >/dev/null 2>&1; then
+          printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: rule %s 輸出 malformed context\n' \
+            "$_rule" >&2
+          exit 70
+        fi
+        _ctx=$(jq -er '.governanceContext.message' "$_stdout") || {
+          printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: rule %s context 無法解碼\n' \
+            "$_rule" >&2
+          exit 70
+        }
+        if [ -n "$_CONTEXTS" ]; then
+          _CONTEXTS="${_CONTEXTS}"$'\n\n────────\n\n'"$_ctx"
+        else
+          _CONTEXTS="$_ctx"
+        fi
+      fi
+      ;;
+    2)
+      if [ ! -s "$_stdout" ] && [ -s "$_stderr" ] \
+        && ! grep -qF 'GOVERNANCE_INTEGRITY:' "$_stderr"; then
+        cat "$_stderr" >&2
+        exit 2
+      fi
+      printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: rule %s rc2 必須是 stderr-only nonempty policy blocker\n' \
+        "$_rule" >&2
+      exit 70
+      ;;
+    70)
+      if [ ! -s "$_stdout" ] && [ -s "$_stderr" ] \
+        && grep -qF 'GOVERNANCE_INTEGRITY:' "$_stderr"; then
+        cat "$_stderr" >&2
+      else
+        printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: rule %s rc70 必須是 stderr-only marker\n' \
+          "$_rule" >&2
+      fi
+      exit 70
+      ;;
+    *)
+      printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: rule %s 回傳未定義 exit code %s\n' \
+        "$_rule" "$_rc" >&2
+      exit 70
+      ;;
+  esac
+done
+
+if [ -n "$_CONTEXTS" ]; then
+  _encoded=$(printf '%s' "$_CONTEXTS" | jq -Rs .) || {
+    printf '🚨 GOVERNANCE_INTEGRITY: PROPOSE DISCIPLINE FAILURE: combined context 無法編碼\n' >&2
+    exit 70
+  }
+  printf '{"governanceContext":{"hookEventName":"Stop","message":%s}}\n' "$_encoded"
+fi
+exit 0

package/ds-canonical/hooks/check_propose_pre_grep_verify.sh

@@ -10,7 +10,8 @@ set -uo pipefail
 # 決策 N / 我推 A/B/C / 選項」keywords,**但 content 內無 file:line cite 證據**
 # → P1 warn(stderr exit 0,Claude 自決撤回 OR 在 reply 補 cite)。
 #
-# SSOT: `.claude/skills/propose-options/SKILL.md` Q0 段 + meta-patterns.md M18。
+# SSOT: `packages/design-system/ds-canonical/skills/propose-options/SKILL.md` Q0 段 +
+# `packages/design-system/ds-canonical/rules/meta-patterns.md` M18。
 
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
 
@@ -38,7 +39,7 @@ NEW_CONTENT=$(echo "$INPUT" | jq -r '
   ([.tool_input.edits[]? | .new_string] | join("\n"))
 ' 2>/dev/null || echo "")
 
-[ -z "${NEW_CONTENT//[[:space:]]/}" ] && exit 0
+grep -q '[^[:space:]]' <<<"$NEW_CONTENT" || exit 0
 
 # Detect propose keywords
 HAS_PROPOSE=$(echo "$NEW_CONTENT" | grep -cE '(請拍板|等你拍板|待你拍板|決策 [0-9N]|我推 [ABC]|選項[::]|propose for user|你決定|讓我判斷決策)' || true)
@@ -46,7 +47,8 @@ HAS_PROPOSE=$(echo "$NEW_CONTENT" | grep -cE '(請拍板|等你拍板|待你拍
 [ "$HAS_PROPOSE" = "0" ] && exit 0
 
 # Allowed escape:檔頭 `<!-- @propose-pre-verified -->` 例外
-if echo "$NEW_CONTENT" | head -3 | grep -qE '@propose-pre-verified'; then
+FIRST_THREE=$(sed -n '1,3p' <<<"$NEW_CONTENT")
+if grep -qE '@propose-pre-verified' <<<"$FIRST_THREE"; then
   exit 0
 fi
 
@@ -63,7 +65,7 @@ if [ "$HAS_CITE" = "0" ]; then
   printf '   3. Read consumer usage 確認該 pattern 已在 N 處 work fine\n' >&2
   printf '   4. propose 給 user 前列具體 file:line 證據\n' >&2
   printf '\n  錨例:2026-05-18 Sheet/inline-action/SurfaceBody 三題誤判 propose 浪費 user 時間\n' >&2
-  printf '  SSOT: .claude/skills/propose-options/SKILL.md Q0 段\n' >&2
+  printf '  SSOT: packages/design-system/ds-canonical/skills/propose-options/SKILL.md Q0 段\n' >&2
   printf '  Escape: 檔頭加 <!-- @propose-pre-verified --> 若已 verify(rationale 必明示)\n' >&2
 fi
 

package/ds-canonical/hooks/check_propose_without_benchmark.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# check_propose_without_benchmark.sh — M26 mechanical enforcement(2026-05-26 backfill per
+# user verbatim「該程式化的都沒程式化」)。
+#
+# Purpose:UserPromptSubmit — 偵測 AI 在 next reply 將 propose visual/behavior decision
+# (出現「建議」「方案 A/B」「propose」「應該改成」keyword)but 過去 ~20 turns 無 WebFetch / WebSearch
+# tool call trace → inject soft BLOCKER 要求先 fetch ≥ 3 source 才 propose。
+#
+# 對齊 meta-patterns.md M26「Behavior/visual canonical decision 前必跑 WebFetch + WebSearch 取 ≥3
+# source,不可憑印象 propose」+ propose-options/SKILL.md。
+#
+# 注意:本 hook 走 UserPromptSubmit(在 AI reply 前 inject context),
+# ⚠️ fail-closed 設計約束(2026-07-07 治理進化方向 2 稽核結論):UserPromptSubmit 的 exit 2
+# 擋的是 user 輸入本身 = 錯誤工具語義,本 hook **不可**升 exit 2。propose 家族的 fail-closed
+# 端 = check_propose_pre_grep_verify.sh(M18 Q0 配對)+ stop_self_audit claim-verify 閘;
+# 本 hook 職責 = 事前 P0 措辭 directive 注入(非 soft 建議)。
+# 跟 check_propose_pre_grep_verify.sh(走 PostToolUse 偵測 propose 已成型後再警示)互補。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(jq -r '.hook_event_name // ""' <<<"$INPUT" 2>/dev/null)
+TRANSCRIPT_PATH=$(jq -r '.transcript_path // ""' <<<"$INPUT" 2>/dev/null)
+PROMPT=$(jq -r '.prompt // ""' <<<"$INPUT" 2>/dev/null)
+
+[ "$EVENT" != "UserPromptSubmit" ] && exit 0
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# Heuristic:user prompt 含 specific visual / behavior decision trigger keyword(2026-05-26 tighten — 拿掉「應該/是否/改成/design/behavior/互動」太籠統的 false-positive triggers)
+PROPOSE_TRIGGER_RE='(propose me|give me options|列.{0,5}option|建議.{0,5}方案|建議.{0,5}做法|哪個比較|對齊哪家|比稿|要怎麼設計|該用哪個|design tradeoff|recommend|world-class.{0,10}(對照|比較))'
+if ! grep -qE "$PROPOSE_TRIGGER_RE" <<<"$PROMPT"; then
+  exit 0
+fi
+
+# Scan past ~20 turns(~400 lines)看是否有 WebFetch / WebSearch tool_use
+RECENT=$(tail -400 "$TRANSCRIPT_PATH" 2>/dev/null)
+HAS_FETCH=$(echo "$RECENT" | \
+  jq -r 'select(.message.content != null) |
+    .message.content // empty |
+    if type == "array" then
+      (.[]? | select(.type == "tool_use") | select(.name == "WebFetch" or .name == "WebSearch") | .name)
+    else empty end' 2>/dev/null | wc -l)
+HAS_FETCH=${HAS_FETCH:-0}
+
+if [ "$HAS_FETCH" -ge 2 ]; then
+  exit 0
+fi
+
+# P0-directive inject(exit 0 by design — 見檔頭 fail-closed 設計約束)
+MSG=$(cat <<EOF
+🚨 M26 Propose-without-benchmark gate(P0 directive — 未 fetch 就 propose = M26 違規,非建議)
+
+→ User prompt 含 propose / visual / behavior decision trigger keyword,但過去 ~20 turns
+  Web fetch / WebSearch tool_use count = $HAS_FETCH(< 2)。
+
+M26 要求:visual / behavior canonical decision 前必跑 WebFetch + WebSearch 取 ≥ 3 source
+  (Atlassian / Material / Polaris / Ant / Carbon / Apple HIG / shadcn / Radix),不可憑印象。
+
+Pipeline(propose 前 inline 跑):
+  1. WebFetch 3 家世界級 source
+  2. 全 403 → WebSearch fallback 用 snippet,明示「search-only confidence」
+  3. WebFetch + WebSearch 都失敗 → STOP propose,告知 user「無法 verify,要看 screenshot / 實機」
+
+對應:meta-patterns.md M26 / propose-options/SKILL.md Step B-3。
+EOF
+)
+jq -n --arg ctx "$MSG" '{governanceContext:{hookEventName:"UserPromptSubmit",message:$ctx}}'
+exit 0

package/ds-canonical/hooks/check_select_all_canonical.sh

@@ -28,7 +28,7 @@ NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.conte
 # 本 SSOT primitive 檔自己不查
 [[ "$FILE_PATH" == *multi-select-ordering.ts ]] && exit 0
 # Allowlist
-echo "$NEW_CONTENT" | grep -q "@select-all-canonical-allow" && exit 0
+grep -q "@select-all-canonical-allow" <<<"$NEW_CONTENT" && exit 0
 
 # Detect Select-All-like pattern:
 #   - function name contains SelectAll / CheckAll

package/ds-canonical/hooks/check_sidebar_menu_button_implicit_wrap.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# check_sidebar_menu_button_implicit_wrap.sh — PreToolUse Edit/Write 攔 SidebarMenuButton 沒 asChild + children 含 ItemAvatar/Avatar/Icon 致隱式 wrap 垂直 stack(2026-05-27)
+#
+# Per user 2026-05-27 抓 UserFooter Avatar 垂直 stack drift:
+#   SidebarMenuButton(sidebar.tsx L1036-1043)在沒 asChild 時把所有 children 塞進 <ItemLabel> 單一 span,
+#   Avatar + text-span 都在同 span 內 → 強迫垂直堆疊。
+#
+# Canonical:含 Avatar/ItemAvatar/icon prefix 的 SidebarMenuButton 必用 asChild + 單一 wrapper
+#   (互動觸發行 <button type="button">,如 UserFooter 帳號選單;純展示 row <div role="group">),
+#   per sidebar.tsx:1025-1027 docblock:「asChild 的 consumer 自行放 icon + label」+ DS canonical
+#   sidebar.stories.tsx#UserFooter 範例。
+#
+# Detection:
+#   `<SidebarMenuButton ...>` (no asChild) ... `<ItemAvatar` or `<Avatar` inside → BLOCKER
+#   ALLOW:`<SidebarMenuButton startIcon={X}>label</SidebarMenuButton>`(用 startIcon prop 不 wrap)
+#   ALLOW:`<SidebarMenuButton asChild>...</SidebarMenuButton>`(consumer 自管 layout)
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$(dirname "$0")/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: hook integrity helper unavailable\n' >&2
+  exit 70
+}
+
+set -uo pipefail
+governance_hook_load_input
+governance_hook_require_commands python3
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'sidebar-wrap tool extraction failed'
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'sidebar-wrap path extraction failed'
+EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'sidebar-wrap event extraction failed'
+NEW=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'sidebar-wrap content extraction failed'
+
+[ "$EVENT" != "PreToolUse" ] && exit 0
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.tsx) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.test.tsx) exit 0 ;; esac
+
+# Python multiline regex:`<SidebarMenuButton` 不含 `asChild` 的 block + 內含 Avatar/ItemAvatar prefix
+HAS_DRIFT=$(printf '%s' "$NEW" | python3 -c '
+import sys, re
+content = sys.stdin.read()
+# Find SidebarMenuButton blocks(opening tag → closing tag,non-greedy multiline)
+# match opening `<SidebarMenuButton ...>` capture full open tag
+for m in re.finditer(r"<SidebarMenuButton\b([^>]*)>(.*?)</SidebarMenuButton>", content, re.DOTALL):
+    open_tag, body = m.group(1), m.group(2)
+    # Skip if asChild present
+    if re.search(r"\basChild\b", open_tag):
+        continue
+    # Drift = body 含 <ItemAvatar 或 <Avatar(both = avatar prefix)
+    if re.search(r"<(ItemAvatar|Avatar)\b", body):
+        print("DRIFT")
+        sys.exit(0)
+' 2>/dev/null) || governance_hook_integrity_fail 'sidebar-wrap parser failed'
+
+[ "$HAS_DRIFT" != "DRIFT" ] && exit 0
+
+# Override env(audit-logged)
+if [ "${GOVERNANCE_BYPASS_SIDEBAR_MENU_BUTTON_WRAP:-0}" = "1" ]; then
+  if STATE_DIR="$(governance_runtime_state_dir 2>/dev/null)"; then
+    mkdir -p "$STATE_DIR" 2>/dev/null
+    jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg file "$FILE_PATH" \
+      '{ts:$ts,event:"sidebar-menu-button-wrap-bypass",file:$file}' >> "$STATE_DIR/governance-bypass.jsonl" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+REL=${FILE_PATH#*/my-project/}
+
+cat >&2 <<'EOF'
+🚨 SidebarMenuButton implicit-wrap canonical violation(per user 2026-05-27 UserFooter 垂直 stack 事件):
+
+🔍 偵測:SidebarMenuButton 內含 ItemAvatar 或 Avatar 但 **無 asChild**
+
+⚠️ 後果(per sidebar.tsx:1036-1043 source code):
+  SidebarMenuButton 沒 asChild → children 全塞進 ItemLabel(單 span)
+  → Avatar + text 在同 span 內 → 強迫垂直堆疊(user 抓的 bug)
+
+修法(per DS canonical sidebar.stories.tsx#UserFooter):
+
+  ❌ SidebarMenuButton id="..." 直接放 ItemAvatar + span 為 children
+
+  ✅ SidebarMenuButton asChild 包單一 wrapper 內含 ItemAvatar + span data-sidebar="menu-label" min-w-0 flex-1 truncate
+     (wrapper:互動觸發行用 <button type="button">,如 UserFooter 帳號選單;純展示 row 用 <div role="group">)
+
+Or use startIcon prop(自動 layout,不 wrap):
+  ✅ SidebarMenuButton startIcon={SomeLucideIcon} 直接 children 為純文字
+
+Bypass(極罕見):GOVERNANCE_BYPASS_SIDEBAR_MENU_BUTTON_WRAP=1 env var(audit-logged)。
+
+Citation:
+  - packages/design-system/src/components/Sidebar/sidebar.tsx:1025-1043(asChild docblock)
+  - packages/design-system/src/components/Sidebar/sidebar.stories.tsx UserFooter(canonical;帳號選單觸發行)
+EOF
+# 2026-05-31:exit 0 → exit 2(folded-hook-audit:原宣稱 BLOCKER 但 exit 0 = 假 enforcement;
+# SidebarMenuButton implicit-wrap 是 SSOT canonical,verified clean on 現有 sidebar code + 有 env escape)。
+exit 2