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

package/ds-canonical/hooks/check_tabs_content_chrome_body_double_gap.sh

@@ -0,0 +1,241 @@
+#!/bin/bash
+# check_tabs_content_chrome_body_double_gap.sh — P0 BLOCKER(overlay-body layout-space guardian,2 checks)
+#
+# **Check 1**(tabs double-gap):`<TabsContent>` 被放進 chrome scroll body(`<DialogBody>` /
+#   `<SheetBody>` / `<SurfaceBody>`)內卻沒 `mt-0` override → 雙重 gap owner。
+# **Check 2**(overlay-body fixed macro gap,2026-07-01 Sheet gap-4 錨例):浮層 body 自身 className
+#   用固定 `gap-[4-9]`(macro)而非 layout-space token → lg density 不縮放,drift。詳見下方 Check 2 段。
+#
+# 兩者同屬「overlay-body layout-space 合規」domain,折進一 hook(不增 hook 數)。
+#
+# Root invariant(item-anatomy.spec.md「垂直 padding 歸屬 / 禁雙重 padding」+ layoutSpace.spec.md
+# 規則 2「Header → element = 單一 tight」):兩元素之間的 gap 只能有一個 owner。
+# - DialogBody/SheetBody/SurfaceBody 內層 padded div 已用 `pt-/py-[var(--layout-space-tight)]`
+#   擁有 header→content 的 chrome gap。
+# - TabsContent 預設帶 `mt-[var(--layout-space-tight)]`(tabs.tsx,為「緊接 tab bar 下方」而設)。
+# - tabsSlot composition 把 tab bar 抬進 header,TabsContent 留在 body → 兩 owner 疊加 =
+#   雙重 tight(md 24 / lg 32)。修法 = chrome body 內的 TabsContent 加 `className="mt-0"`
+#   把 ownership 轉移給 body(對齊 AppShell 前例 app-shell.stories.tsx + Carbon/Radix「panel
+#   單一 owner」benchmark)。
+#
+# Anchor:2026-07-01 user 在「專案設定」Dialog(dialog.stories.tsx WithTabsInHeader)DevTools
+#   抓到「專案名稱」上方兩個 --layout-space-tight。歷次稽核漏抓,因既有
+#   check_layout_space_magic_numbers.sh **明確 skip packages/design-system/src/**(該 hook L34)。
+#   本 hook **反轉 scope** 專掃 DS src + apps composition,補該盲區。
+#
+# Scope:只掃 packages/design-system/src/** + apps/** 的 .tsx(含 .stories.tsx)。
+# Level:P0 BLOCKER exit 2(layout-space SSOT 一律 P0,非 P1 WARN — per
+#   feedback_ssot_mechanical_p0_not_p1_warn_2026_05_27)。窄 gate(必同時含 chrome body + TabsContent)
+#   控 false-positive。Escape:`// @tabs-content-gap-ok: <rationale>`(同行或前一註解行)。
+
+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 awk cat grep head sed
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'tabs-body tool extraction failed'
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.notebook_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'tabs-body path extraction failed'
+
+# Scope:DS source + apps,.tsx only(INVERSE of check_layout_space_magic_numbers.sh 的 DS-src skip)
+if ! governance_hook_grep_q 'tabs-body extension matcher failed' "$FILE" -qE '\.tsx$'; then exit 0; fi
+if ! governance_hook_grep_q 'tabs-body scope matcher failed' "$FILE" -qE '(packages/design-system/src/|/apps/|(^|/)apps/)'; then exit 0; fi
+
+# PostToolUse:file 已寫入磁碟,讀「完整檔」做 containment 分析(避免 hunk-only partial-edit 盲區 —
+# 部分 edit 的 new_string 可能只含 TabsContent 行不含外層 DialogBody,window 分析會漏)。
+FILE=$(governance_hook_project_file_path "$FILE" 2>/dev/null) \
+  || governance_hook_integrity_fail 'tabs-body target escapes the project or crosses a symlink'
+if [ -L "$FILE" ] || [ ! -f "$FILE" ] || [ ! -r "$FILE" ]; then
+  governance_hook_integrity_fail 'tabs-body target is unavailable or unsafe'
+fi
+CONTENT=$(cat "$FILE" 2>/dev/null) || governance_hook_integrity_fail 'tabs-body target read failed'
+[ -z "$CONTENT" ] && exit 0
+
+# ── Check 3(2026-07-08 WM 戰役 R4:root 偵測,不只 symptom)──
+# WM 實證:app 把 TabsList 塞 DialogBody + `!pt-0` hack 對抗 primitive,TabsContent 加了 mt-0
+# 就繞過 Check 2 —— 但 root 錯誤是「沒用 DialogHeader tabsSlot canonical」(雙線 + 底線內縮 +
+# spacing owner 自組)。偵測兩個 root 簽名(任一 → BLOCK 指路 tabsSlot):
+#   (a) DialogBody/SheetBody/SurfaceBody className 含 `!pt-0`(important 對抗 primitive 的 pt owner)
+#   (b) <TabsList 出現在含 DialogBody 的同段 new content 且無 tabsSlot 字樣
+governance_hook_grep_capture ROOT_SIG_A_CANDIDATES 'tabs-body root signature matcher failed' \
+  "$CONTENT" -nE '(DialogBody|SheetBody|SurfaceBody)[^>]*className=[^>]*!pt-0'
+governance_hook_grep_capture ROOT_SIG_A 'tabs-body root signature escape filter failed' \
+  "$ROOT_SIG_A_CANDIDATES" -v '@tabs-content-gap-ok:'
+ROOT_SIG_B=""
+if governance_hook_grep_q 'tabs-body TabsList matcher failed' "$CONTENT" -q '<TabsList' \
+  && governance_hook_grep_q 'tabs-body chrome-body matcher failed' "$CONTENT" -qE '<(DialogBody|SheetBody|SurfaceBody)\b' \
+  && ! governance_hook_grep_q 'tabs-body tabsSlot matcher failed' "$CONTENT" -q 'tabsSlot' \
+  && ! governance_hook_grep_q 'tabs-body root escape matcher failed' "$CONTENT" -q '@tabs-content-gap-ok:'; then
+  ROOT_SIG_B="found"
+fi
+if [ -n "$ROOT_SIG_A" ] || [ -n "$ROOT_SIG_B" ]; then
+  cat >&2 << 'EOF_C3'
+🚨 TABS-IN-BODY ROOT BLOCKER(P0,2026-07-08 WM 戰役 — 攔 root 非 symptom)
+
+  偵測到「TabsList 手塞 chrome body / body 用 !pt-0 hack」簽名 —— 這是「沒用 header tabsSlot
+  canonical」的 root 錯誤(後果:header 與 TabsList 雙底線、tabs 底線被 body padding 內縮不滿寬、
+  spacing owner 鏈自組)。WM ProjectSettings/TypeSettings 錨例。
+
+  ── 正解 ──
+  <Tabs> wrap → <DialogHeader tabsSlot={<TabsList/>}> → <DialogBody><TabsContent className="mt-0">
+  照 dialog.stories.tsx#WithTabsInHeader 逐字結構(header-canonical.spec.md Rule W2)。
+  Escape:`// @tabs-content-gap-ok: <rationale>`(例:tabs 本來就不屬 header 的內容分頁場景)
+EOF_C3
+  exit 2
+fi
+
+
+# ══ Check 2:overlay body 自身用固定 macro gap-N → 該用 layout-space token(2026-07-01 Sheet gap-4 錨例)══
+# Root(layoutSpace.spec.md 規則 2/3):浮層 body 直接堆疊內容的垂直 gap 屬 macro layout-space,該用
+#   density-scaling token(並列 = loose / functional 交互 = tight),非固定 gap-N(lg 不縮放 → 跟 DS
+#   自己 dialog.stories 的 gap-[var(--layout-space-loose)] 不一致)。窄 gate:只抓 overlay body 自身
+#   className 的固定 gap-[4-9](macro range;排除 gap-1/2/3 micro + 已 tokenize 的 gap-[var)。
+#   全庫掃證實零現存假陽性(純防未來 drift)。Escape:同行或前一註解行 @overlay-body-gap-ok:。
+GAP_MARKER='@overlay-body-gap-ok:'
+governance_hook_grep_capture GAP_CANDIDATES 'tabs-body fixed-gap matcher failed' "$CONTENT" -nE \
+  '<(DialogBody|SheetBody|PopoverBody|SurfaceBody)[^>]*gap-[4-9]([^0-9]|$)'
+governance_hook_grep_capture GAP_HITS 'tabs-body tokenized-gap filter failed' \
+  "$GAP_CANDIDATES" -v 'gap-\[var'
+GAP_UNJUSTIFIED=""
+if [ -n "$GAP_HITS" ]; then
+  while IFS= read -r hit; do
+    [ -z "$hit" ] && continue
+    ln="${hit%%:*}"
+    cur="${hit#*:}"
+    if governance_hook_grep_q 'tabs-body gap escape matcher failed' "$cur" -qF "$GAP_MARKER"; then continue; fi
+    if [ "$ln" -gt 1 ] 2>/dev/null; then
+      prev=$(sed -n "$((ln-1))p" <<< "$CONTENT" 2>/dev/null) \
+        || governance_hook_integrity_fail 'tabs-body gap preceding-line extraction failed'
+      if governance_hook_grep_q 'tabs-body preceding gap escape matcher failed' "$prev" -qF "$GAP_MARKER" \
+        && governance_hook_grep_q 'tabs-body preceding gap comment matcher failed' "$prev" -qE '^[[:space:]]*(//|\{?/\*|\*)'; then
+        continue
+      fi
+    fi
+    GAP_UNJUSTIFIED="${GAP_UNJUSTIFIED}${ln}: $(echo "$cur" | sed 's/^[[:space:]]*//')\n"
+  done <<< "$GAP_HITS"
+fi
+if [ -n "$GAP_UNJUSTIFIED" ]; then
+  cat >&2 << EOF
+🚨 OVERLAY-BODY FIXED-GAP BLOCKER(P0,2026-07-01 Sheet demo gap-4 錨例)
+
+  在 $FILE 偵測到浮層 body(Dialog/Sheet/Popover/Surface Body)自身用固定 macro gap-N:
+$(printf '%b' "$GAP_UNJUSTIFIED" | sed 's/^/    /' | awk 'NR <= 10')
+
+  ── 為什麼 ──
+  浮層 body 直接堆疊內容(並列表單欄位 / 區塊)的垂直 gap 屬 macro layout-space,該用
+  density-scaling token(並列 = loose / functional 交互 = tight),非固定 gap-N(lg 不縮放 →
+  跟 DS 自己 dialog.stories 的 gap-[var(--layout-space-loose)] 不一致)。
+
+  ── 修法 2 選 1 ──
+    (a) gap-N → gap-[var(--layout-space-loose)](並列)/ gap-[var(--layout-space-tight)](functional 交互)
+    (b) Escape:該行或前一註解行加 \`// @overlay-body-gap-ok: <rationale>\`(刻意 list 間距 / 視覺平衡)
+
+  canonical → tokens/layoutSpace/layoutSpace.spec.md 規則 2/3
+EOF
+  exit 2
+fi
+
+# ══ Check 1:<TabsContent> 在 chrome body 內雙重 gap(原 beta.78 邏輯)══
+# Gate:必同時含 chrome body open tag 且 TabsContent 才啟動(narrow surface,絕大多數 edit 靜默)
+if ! governance_hook_grep_q 'tabs-body containment gate matcher failed' "$CONTENT" -qE '<(DialogBody|SheetBody|SurfaceBody)[ />]'; then exit 0; fi
+if ! governance_hook_grep_q 'tabs-content gate matcher failed' "$CONTENT" -q '<TabsContent'; then exit 0; fi
+
+ESCAPE_MARKER='@tabs-content-gap-ok:'
+
+# 逐行 depth-counter(awk):進 chrome body +1、出 -1;TabsContent 在 depth>0 = 在 chrome body 內。
+# - 註解行(JSDoc `*` / `//` / `{/*` / `/*` / `*/`)整行跳過,不計 depth 也不判 TabsContent
+#   (避免 JSDoc 內 `<DialogBody>` 範例污染 depth / 內含的 mt-0 example 被誤判)。
+# - 同行 open 先加 depth 再判 TabsContent 再減 close → 同行 `<DialogBody><TabsContent>` 與
+#   `<TabsContent>...</DialogBody>` 都正確歸屬「inside」。
+# - TabsContent opening tag 可能跨行:accumulate 到 `>` 再驗 className 有無 canonical `mt-0`
+#   (class-boundary anchored;非-0 / arbitrary 值需 escape marker)。
+# 輸出:每個「chrome body 內且無 mt-0 override」的 TabsContent 起始行號(供 bash escape 過濾)。
+CANDIDATES=$(printf '%s\n' "$CONTENT" | awk '
+  function check_tag(tag, ln) {
+    # 只認 canonical `mt-0`(class-boundary anchored):排除 `mt-0.5` / `mt-04` 等 substring 假通過
+    # (mt-0.5 是本 DS 真實 class,item-anatomy.stories.tsx:766;2px 不抵銷 pt-tight → 仍雙重)。
+    # arbitrary `mt-[...]` / 非-0 值 = 非 canonical → 需 escape marker 明示 documented(非靜默通過)。
+    if (tag ~ /(^|[^a-zA-Z0-9])mt-0([^a-zA-Z0-9.]|$)/) return
+    print ln
+  }
+  BEGIN { depth=0; collecting=0; buf=""; startline=0 }
+  {
+    raw=$0
+    if (collecting) {
+      buf = buf " " raw
+      if (raw ~ />/) { collecting=0; check_tag(buf, startline); buf="" }
+      next
+    }
+    t=raw; sub(/^[ \t]+/,"",t)
+    if (t ~ /^(\*|\/\/|\{?\/\*|\*\/)/) next          # skip comment-only lines
+    tmp=raw;  o=gsub(/<(DialogBody|SheetBody|SurfaceBody)[ \t\/>]/,"X",tmp)
+    tmpc=raw; c=gsub(/<\/(DialogBody|SheetBody|SurfaceBody)>/,"X",tmpc)
+    depth += o
+    if (raw ~ /<TabsContent/ && depth > 0) {
+      idx = index(raw, "<TabsContent")
+      rest = substr(raw, idx)
+      if (rest ~ />/) { gt = index(rest, ">"); check_tag(substr(rest, 1, gt), NR) }
+      else { collecting=1; buf=rest; startline=NR }
+    }
+    depth -= c
+  }
+') || governance_hook_integrity_fail 'tabs-body containment parser failed'
+
+if [ -z "$CANDIDATES" ]; then exit 0; fi
+
+# Escape 過濾:同行 OR 前一「註解專用行」含 @tabs-content-gap-ok: → 豁免(對齊
+# check_layout_space_magic_numbers.sh L57-69 已 debug 過的 preceding-line marker 邏輯)。
+UNJUSTIFIED=""
+while IFS= read -r ln; do
+  [ -z "$ln" ] && continue
+  cur=$(sed -n "${ln}p" <<< "$CONTENT" 2>/dev/null) \
+    || governance_hook_integrity_fail 'tabs-body candidate-line extraction failed'
+  if governance_hook_grep_q 'tabs-body same-line escape matcher failed' "$cur" -qF "$ESCAPE_MARKER"; then continue; fi
+  if [ "$ln" -gt 1 ] 2>/dev/null; then
+    prev=$(sed -n "$((ln-1))p" <<< "$CONTENT" 2>/dev/null) \
+      || governance_hook_integrity_fail 'tabs-body preceding-line extraction failed'
+    if governance_hook_grep_q 'tabs-body preceding escape matcher failed' "$prev" -qF "$ESCAPE_MARKER" \
+      && governance_hook_grep_q 'tabs-body preceding comment matcher failed' "$prev" -qE '^[[:space:]]*(//|\{?/\*|\*)'; then
+      continue
+    fi
+  fi
+  UNJUSTIFIED="${UNJUSTIFIED}${ln}: $(echo "$cur" | sed 's/^[[:space:]]*//')\n"
+done <<< "$CANDIDATES"
+
+
+if [ -z "$UNJUSTIFIED" ]; then exit 0; fi
+
+cat >&2 << EOF
+🚨 TABS-CONTENT-CHROME-BODY DOUBLE-GAP BLOCKER(P0,2026-07-01 user「專案名稱上方兩個 space-tight」)
+
+  在 $FILE 偵測到 <TabsContent> 放在 chrome scroll body(DialogBody/SheetBody/SurfaceBody)內
+  但未 override margin-top:
+$(printf '%b' "$UNJUSTIFIED" | sed 's/^/    /' | awk 'NR <= 10')
+
+  ── 為什麼是 bug ──
+  DialogBody/SheetBody/SurfaceBody 內層已用 pt-/py-[var(--layout-space-tight)] 擁有 header→content
+  的 chrome gap;TabsContent 預設又帶 mt-[var(--layout-space-tight)](tabs.tsx,為緊接 tab bar 而設)。
+  tabsSlot composition 把 tab bar 抬進 header 後,兩個 owner 疊加 = 雙重 tight(md 24 / lg 32)。
+  一軸只能有一個 spacing owner(item-anatomy.spec.md「垂直 padding 歸屬 / 禁雙重 padding」)。
+
+  ── 修法 2 選 1 ──
+    (a) chrome body 內的 TabsContent 加 \`className="mt-0"\` 把 ownership 轉移給 body
+        (對齊 AppShell 前例 app-shell.stories.tsx + Carbon/Radix「panel 單一 owner」benchmark)
+    (b) Escape:該行或前一註解行加 \`// @tabs-content-gap-ok: <rationale>\`(顯式 documented 例外)
+
+  完整 canonical → components/Tabs/tabs.spec.md「出現在 Dialog」段
+                 + tokens/layoutSpace/layoutSpace.spec.md 規則 2
+EOF
+exit 2

package/ds-canonical/hooks/check_tailwind_wildcard_in_docs.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# check_tailwind_wildcard_in_docs.sh — P0 BLOCKER
+#
+# Per 2026-05-28 beta.27 release fail anchor(6+ CI iterations 燒):
+# Tailwind v4 vite plugin scans .md / .spec.md / docs by default。
+# 文件範例 like `shadow-[var(--elevation-*)]` 或 `var(--field-height-*)` /
+# `var(--elevation-100/200/300)` 是給 dev 看的 shorthand notation(`*` /  `/` 代表
+# enumeration placeholder),但 Tailwind 不知 → 當 literal class string 抓 → 產
+# invalid CSS `var(--X-*)` `var(--X-A/B/C)` → Storybook FULL smoke 死。
+#
+# 機械強制 PreToolUse Edit/Write:阻止寫入新檔含此 anti-pattern。
+# 改用 math notation:`var(--X-N) N∈{a,b,c}` Tailwind 不會誤判。
+#
+# Scope:所有 .md / .spec.md / .sh / .ts / .tsx 寫入時 grep new_string。
+# Exit 2 BLOCKER + cite this anchor。Escape:`@tailwind-wildcard-allow:` comment。
+
+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 grep sed sort
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'Tailwind wildcard tool extraction failed'
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'Tailwind wildcard path extraction failed'
+# Self-exemption:本 hook help-text 合法含 anti-pattern literal 作為文件範例(且 .sh 不被 Tailwind
+# vite plugin 掃,無 build 風險)→ 不掃自己,避免 self-trigger false-positive(2026-05-30 test-surfaced)。
+case "$FILE" in */check_tailwind_wildcard_in_docs.sh) exit 0 ;; esac
+# Provider runtime artifacts no longer live inside the checkout. Do not add provider-specific path
+# exemptions here: a future provider receives the same Tailwind protection without hook changes.
+# Only check files Tailwind v4 might scan
+if ! governance_hook_grep_q 'Tailwind wildcard scope matcher failed' "$FILE" -qE '\.(md|spec\.md|sh|ts|tsx|css|json)$'; then exit 0; fi
+
+CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'Tailwind wildcard content extraction failed'
+[ -z "$CONTENT" ] && exit 0
+
+# Escape clause
+if governance_hook_grep_q 'Tailwind wildcard escape matcher failed' "$CONTENT" -qE '@tailwind-wildcard-allow:'; then exit 0; fi
+
+# Detect anti-patterns(class form with wildcard / slash enumeration in CSS var)
+# 2026-05-30 fix(test-surfaced M34 over-narrow):slash-segment 改 repeatable,
+# 否則漏多段斜線列舉形式(beta.27 anchor 的 N-段 enum,hook header 列為必擋 anti-pattern)。
+governance_hook_grep_capture ANTI_PATTERNS_UNSORTED 'Tailwind wildcard matcher failed' \
+  "$CONTENT" -oE 'var\(--[a-z][a-z0-9-]*([\*/]+[a-z0-9-]*)+\)'
+ANTI_PATTERNS=$(sort -u <<< "$ANTI_PATTERNS_UNSORTED" 2>/dev/null) \
+  || governance_hook_integrity_fail 'Tailwind wildcard sorter failed'
+
+if [ -n "$ANTI_PATTERNS" ]; then
+  cat >&2 << EOF
+🚨 TAILWIND v4 WILDCARD-IN-DOCS BLOCKER(P0,2026-05-28 beta.27 anchor)
+
+  File: $FILE
+  Detected anti-pattern(s):
+$(echo "$ANTI_PATTERNS" | sed 's/^/    /')
+
+  Why blocked:
+    Tailwind v4 vite plugin scans .md/.ts/etc → 把 \`var(--X-*)\` / \`var(--X-A/B/C)\`
+    當 literal class string 抓 → 產 invalid CSS(CSS 變數名禁 \`*\` / \`/\`)→ Storybook
+    build 死 → release CI fail。本 anchor:beta.27 6+ CI iteration 燒此問題。
+
+  改用 math notation(Tailwind 不誤判):
+    var(--elevation-*)         → var(--elevation-N) N∈{100,200}
+    var(--elevation-100/200) → var(--elevation-N) N∈{100,200}
+    var(--field-height-*)      → var(--field-height-N) N∈{sm,md,lg}
+    var(--layout-space-*)      → var(--layout-space-N) N∈{loose,tight}
+    var(--radix-*-available-height) → var(--radix-{popover|hover-card|dialog}-content-available-height)
+
+  Escape(極罕見,本 file 真需要 wildcard token literal):
+    add \`// @tailwind-wildcard-allow: <rationale>\` to file content
+EOF
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_wrapper_primitive_schema_drift.sh

@@ -41,18 +41,19 @@ NEW_CONTENT=$(echo "$INPUT" | jq -r '
 ')
 
 # Allow escape
-if echo "$NEW_CONTENT" | grep -qE '@wrapper-schema-allow:'; then
+if grep -qE '@wrapper-schema-allow:' <<<"$NEW_CONTENT"; then
   exit 0
 fi
 
 # Check 1: new file declares `export interface XxxOption {` ?
-DECLARES=$(echo "$NEW_CONTENT" | grep -oE 'export interface [A-Z][a-zA-Z]*Option\b[^{]*\{' || true)
+DECLARES=$(grep -oE 'export interface [A-Z][a-zA-Z]*Option\b[^{]*\{' <<<"$NEW_CONTENT" || true)
 if [ -z "$DECLARES" ]; then
   exit 0
 fi
 
 # For each declared OptionLike interface, check if same name declared elsewhere
-DS_COMPONENTS_DIR="$(dirname "$0")/../../packages/design-system/src/components"
+PROJECT_DIR="${GOVERNANCE_PROJECT_DIR:-$(pwd)}"
+DS_COMPONENTS_DIR="$PROJECT_DIR/packages/design-system/src/components"
 
 # normalize FILE_PATH relative to project for self-skip
 SELF_BASENAME="$(basename "$FILE_PATH")"
@@ -61,26 +62,26 @@ WARNINGS=()
 BLOCKERS=()
 
 while IFS= read -r decl; do
-  IFACE_NAME=$(echo "$decl" | grep -oE '[A-Z][a-zA-Z]*Option' | head -1)
+  IFACE_NAME=$(grep -m 1 -oE '[A-Z][a-zA-Z]*Option' <<<"$decl")
   [ -z "$IFACE_NAME" ] && continue
   # Skip if extends another OptionLike interface(M30 compliant)
-  if echo "$NEW_CONTENT" | grep -qE "interface $IFACE_NAME\b.*extends [A-Z][a-zA-Z]*Option"; then
+  if grep -qE "interface $IFACE_NAME\b.*extends [A-Z][a-zA-Z]*Option" <<<"$NEW_CONTENT"; then
     continue
   fi
   # Find other files declaring same name(skip self by basename — imperfect but Edit context is single-file)
   OTHER_DECLS=$(grep -rlE "export interface $IFACE_NAME\b" "$DS_COMPONENTS_DIR" 2>/dev/null | grep -v "/$SELF_BASENAME$" || true)
   if [ -n "$OTHER_DECLS" ]; then
-    BLOCKERS+=("M30 schema drift: \`$IFACE_NAME\` declared in this file (no extends) + also in: $(echo "$OTHER_DECLS" | head -3 | xargs -n1 basename | tr '\n' ',' | sed 's/,$//')")
+    BLOCKERS+=("M30 schema drift: \`$IFACE_NAME\` declared in this file (no extends) + also in: $(sed -n '1,3p' <<<"$OTHER_DECLS" | xargs -n1 basename | tr '\n' ',' | sed 's/,$//')")
   fi
 done <<< "$DECLARES"
 
 # Check 2: imports SelectMenuOption but menuOptions mapping drops fields(WARN)
-if echo "$NEW_CONTENT" | grep -qE 'import.*SelectMenuOption.*from.*SelectMenu'; then
+if grep -qE 'import.*SelectMenuOption.*from.*SelectMenu' <<<"$NEW_CONTENT"; then
   # Look for `menuOptions: SelectMenuOption[]` mapping that misses fields
-  MAP_BLOCK=$(echo "$NEW_CONTENT" | grep -A5 -E 'menuOptions.*SelectMenuOption\[\]' | head -30)
+  MAP_BLOCK=$(grep -A5 -E 'menuOptions.*SelectMenuOption\[\]' <<<"$NEW_CONTENT" | awk 'NR <= 30')
   if [ -n "$MAP_BLOCK" ]; then
     # Heuristic: should forward at least `avatar` OR `description` OR `disabled` field
-    if ! echo "$MAP_BLOCK" | grep -qE '(avatar|description|disabled)'; then
+    if ! grep -qE '(avatar|description|disabled)' <<<"$MAP_BLOCK"; then
       WARNINGS+=("M30 schema partial-forward: \`menuOptions\` mapping seems to drop avatar/description/disabled. Forward 全 SelectMenuOption surface or annotate \`// @wrapper-schema-allow: <reason>\`.")
     fi
   fi
@@ -92,13 +93,15 @@ if [ ${#BLOCKERS[@]} -gt 0 ]; then
   for b in "${BLOCKERS[@]}"; do echo "  • $b" >&2; done
   echo "" >&2
   echo "Fix: declare \`interface $IFACE_NAME extends <PrimitiveSSoT>\` (e.g. \`extends SelectMenuOption\`)" >&2
-  echo "  詳 .claude/rules/meta-patterns.md M30 + Polaris ChoiceList / Material Autocomplete idiom" >&2
+  echo "  詳 packages/design-system/ds-canonical/rules/meta-patterns.md M30 + Polaris ChoiceList / Material Autocomplete idiom" >&2
   exit 2
 fi
 
 if [ ${#WARNINGS[@]} -gt 0 ]; then
-  echo "⚠️  M30 wrapper schema forward warning:" >&2
-  for w in "${WARNINGS[@]}"; do echo "  • $w" >&2; done
+  CONTEXT="⚠️  M30 wrapper schema forward warning:"
+  for w in "${WARNINGS[@]}"; do CONTEXT="${CONTEXT}"$'\n'"  • $w"; done
+  jq -nc --arg ctx "$CONTEXT" \
+    '{governanceContext:{hookEventName:"PreToolUse",message:$ctx}}'
 fi
 
 exit 0

package/ds-canonical/hooks/chrome_header_dispatcher.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+# chrome_header_dispatcher.sh — orchestrate 4 ChromeHeader-canonical lib helpers
+#
+# 2026-05-26 fold per Track C hook retire(39 → 36):4 個 PreToolUse hook 都
+# enforce header-canonical.spec.md sub-invariants(consumption / app-shell / tabs-border / token-equal)。
+# fold pattern 對齊 post_edit_dispatcher.sh 已建立的 lib/_*.sh helper convention(_ prefix 不計 hook 數)。
+#
+# SSOT canonical deterministic 4 helpers 均為 blocking enforcement。helper 缺失、被 symlink
+# 取代或回傳未定義的非零 exit code 都是 enforcement integrity failure，必須 fail closed。
+#
+# 4 lib helpers:
+#   _chrome_header_handcraft.sh        — Layer 3 consumption enforcement(自刻 chrome header className)
+#   _app_shell_primary_header_consistency.sh — primary-header layout 必傳 globalHeader prop
+#   _header_with_tabs_border.sh        — Header + Tabs 必標 withTabs prop(border auto-suppress)
+#   _tab_lg_chrome_header_equal.sh     — `--tab-height-lg` 必等 `--chrome-header-height` token
+#
+# Each helper:reads stdin INPUT,jq-parses tool_input.file_path,scope-filters。
+# 本 dispatcher 把同一 stdin pipe 給 4 helpers 依序跑，不 aggregate stdout。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null) || {
+  printf '🚨 GOVERNANCE_INTEGRITY: CHROME HEADER ENFORCEMENT FAILURE: 無法讀取 hook input\n' >&2
+  exit 70
+}
+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
+  printf '🚨 GOVERNANCE_INTEGRITY: CHROME HEADER ENFORCEMENT FAILURE: hook input 不是有效的 provider-neutral event\n' >&2
+  exit 70
+fi
+
+LIB_DIR="$(dirname "$0")/lib"
+
+WORST=0
+CAPTURE_DIR=$(mktemp -d "${TMPDIR:-/tmp}/chrome-header-dispatch.XXXXXX") || {
+  printf '🚨 GOVERNANCE_INTEGRITY: CHROME HEADER ENFORCEMENT FAILURE: 無法建立 output contract capture\n' >&2
+  exit 70
+}
+trap 'rm -rf "$CAPTURE_DIR"' EXIT
+HELPER_INDEX=0
+
+# Blocking helpers(SSOT canonical deterministic:primary-header / withTabs border /
+# token pixel equal / chrome-header handcraft)。
+for helper in \
+  "$LIB_DIR/_app_shell_primary_header_consistency.sh" \
+  "$LIB_DIR/_header_with_tabs_border.sh" \
+  "$LIB_DIR/_tab_lg_chrome_header_equal.sh" \
+  "$LIB_DIR/_chrome_header_handcraft.sh"; do
+  if [ ! -f "$helper" ] || [ -L "$helper" ]; then
+    printf '🚨 GOVERNANCE_INTEGRITY: CHROME HEADER ENFORCEMENT FAILURE: required helper 缺失或不是一般檔案: %s\n' \
+      "$(basename "$helper")" >&2
+    WORST=70
+    continue
+  fi
+  HELPER_INDEX=$((HELPER_INDEX + 1))
+  CHILD_STDOUT="$CAPTURE_DIR/$HELPER_INDEX.stdout"
+  CHILD_STDERR="$CAPTURE_DIR/$HELPER_INDEX.stderr"
+  printf '%s' "$INPUT" | bash "$helper" >"$CHILD_STDOUT" 2>"$CHILD_STDERR"
+  rc=$?
+  case "$rc" in
+    0)
+      if [ -s "$CHILD_STDOUT" ] || [ -s "$CHILD_STDERR" ]; then
+        printf '🚨 GOVERNANCE_INTEGRITY: CHROME HEADER ENFORCEMENT FAILURE: helper %s rc0 必須完全 silent\n' \
+          "$(basename "$helper")" >&2
+        WORST=70
+      fi
+      ;;
+    2)
+      if [ -s "$CHILD_STDERR" ] && [ ! -s "$CHILD_STDOUT" ]; then
+        cat "$CHILD_STDERR" >&2
+        if grep -qF 'GOVERNANCE_INTEGRITY' "$CHILD_STDERR"; then
+          WORST=70
+        else
+          [ "$WORST" -eq 0 ] && WORST=2
+        fi
+      else
+        printf '🚨 GOVERNANCE_INTEGRITY: CHROME HEADER ENFORCEMENT FAILURE: helper %s rc2 必須是 stderr-only nonempty blocker\n' \
+          "$(basename "$helper")" >&2
+        WORST=70
+      fi
+      ;;
+    70)
+      if [ -s "$CHILD_STDERR" ] && [ ! -s "$CHILD_STDOUT" ]; then
+        cat "$CHILD_STDERR" >&2
+      else
+        printf '🚨 GOVERNANCE_INTEGRITY: CHROME HEADER ENFORCEMENT FAILURE: helper %s rc70 必須是 stderr-only nonempty integrity failure\n' \
+          "$(basename "$helper")" >&2
+      fi
+      WORST=70
+      ;;
+    *)
+      printf '🚨 GOVERNANCE_INTEGRITY: CHROME HEADER ENFORCEMENT FAILURE: helper %s 回傳未定義 exit code %s\n' \
+        "$(basename "$helper")" "$rc" >&2
+      WORST=70
+      ;;
+  esac
+done
+
+exit $WORST

package/ds-canonical/hooks/enforce_home_charter.sh

@@ -1,11 +1,15 @@
 #!/bin/bash
 # PreToolUse Write hook: gate new files in classification dirs.
-# 確保新檔放對 home(8-home flowchart canonical)。
+# 確保新檔放對 home(Level 1–9 rule-placement taxonomy canonical)。
 #
 # Silent on pass(2026-04-26 noise reduction):only fire if charter README
 # missing OR file-name pattern violates dir convention(no charter inject).
 
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$(dirname "$0")/lib/_provider_paths.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY:HOME_CHARTER_PROVIDER_RESOLVER_UNAVAILABLE\n' >&2
+  exit 70
+}
 
 set -uo pipefail
 
@@ -16,29 +20,46 @@ TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
 [ -n "$FILE_PATH" ] && [ ! -e "$FILE_PATH" ] || exit 0  # only NEW files
 
-# Classification dirs requiring charter
-DIRS=(.claude/hooks .claude/skills .claude/agents .claude/commands .claude/rules packages/design-system/src/components packages/design-system/src/patterns packages/design-system/src/tokens)
+PROJECT_DIR="${GOVERNANCE_PROJECT_DIR:-$(pwd)}"
+REL="$(governance_project_relative_path "$FILE_PATH" 2>/dev/null)" || exit 0
+governance_provider_string_field instructionEntry >/dev/null 2>&1 || {
+  printf 'GOVERNANCE_INTEGRITY:HOME_CHARTER_ACTIVE_PROVIDER_UNREGISTERED\n' >&2
+  exit 70
+}
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
-REL=$(echo "$FILE_PATH" | sed "s|$PROJECT_DIR/||")
+# Classification homes come from the canonical/provider registry. Adding a concrete future
+# provider therefore requires only registry data + generated surfaces,not a new shell branch.
+DIRS=(packages/design-system/src/components packages/design-system/src/patterns packages/design-system/src/tokens)
+for key in hooks skills contextForkAgents commands rules references; do
+  root="$(governance_canonical_relative_root "$key" 2>/dev/null)" || {
+    printf 'GOVERNANCE_INTEGRITY:HOME_CHARTER_CANONICAL_ROOT_UNAVAILABLE:%s\n' "$key" >&2
+    exit 70
+  }
+  DIRS+=("$root")
+done
+MANAGED_ROOTS="$(governance_provider_managed_roots 2>/dev/null)" || {
+  printf 'GOVERNANCE_INTEGRITY:HOME_CHARTER_MANAGED_ROOTS_UNAVAILABLE\n' >&2
+  exit 70
+}
+while IFS= read -r root; do
+  [ -n "$root" ] && DIRS+=("$root")
+done <<< "$MANAGED_ROOTS"
 
 for d in "${DIRS[@]}"; do
-  case "$REL" in
-    "$d"/*)
+  if governance_path_is_under "$REL" "$d"; then
       # Charter README itself escape(2026-05-17 chicken-and-egg fix):
       # 不能擋 README 本身建立(否則 charter 永遠無法被 init)
       case "$REL" in "$d"/README.md) exit 0 ;; esac
       CHARTER="$PROJECT_DIR/$d/README.md"
       if [ ! -f "$CHARTER" ]; then
         # P0:charter missing → block via stderr + exit 2
-        echo "❌ Charter missing for $d/. Create $CHARTER first per # 治理 canonical 8-home flowchart." >&2
+        echo "❌ Charter missing for $d/. Create $CHARTER first per the Level 1–9 rule-placement taxonomy." >&2
         exit 2
       fi
       # Charter exists → silent pass(content placement is AI's responsibility,
       # audit Dim 19 periodic verify;no per-write nag)
       exit 0
-      ;;
-  esac
+  fi
 done
 
 exit 0

package/ds-canonical/hooks/governance_control_plane.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Thin native-feedback adapter for generated control-plane artifacts. Policy stays in
+# @qijenchen/governance; protected CI remains authoritative when native hooks are unavailable.
+set -uo pipefail
+fail_integrity() {
+  printf 'GOVERNANCE_INTEGRITY: governance control plane %s\n' "$1" >&2
+  exit 70
+}
+ROOT="${GOVERNANCE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+PROVIDER="${GOVERNANCE_PROVIDER:-generic}"
+case "$PROVIDER" in *[!a-z0-9-]*|'') fail_integrity "provider id is invalid:$PROVIDER" ;; esac
+ADAPTER="$ROOT/governance/generated/adapters/${PROVIDER}-hook.mjs"
+[ -f "$ADAPTER" ] && [ ! -L "$ADAPTER" ] \
+  || fail_integrity "generated adapter is missing or unsafe:$ADAPTER"
+exec node "$ADAPTER"