@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# check_app_shell_primary_header_consistency.sh — PreToolUse Edit/Write
+#
+# 2026-05-21 ship per user directive「該程式化的就程式化」+「確認當有 global header 時,
+# sidebar 內的 header 應該要拿掉」+ world-class GitHub/Gmail/Figma 共識。
+#
+# Detects 3 violations in AppShell consumer code:
+#   V1) `layout="primary-header"` without `globalHeader=...` prop
+#       → 缺 globalHeader 而 layout=primary-header 是邏輯矛盾(per app-shell.spec.md
+#         「primary-header = primary-sidebar + 一條 global header」)
+#
+#   V2) `layout="primary-header"` + 任何 `<SidebarHeader>...</SidebarHeader>` 在同 file
+#       → WorkspaceBrand 已該在 globalHeader,sidebar 內不該再有 SidebarHeader
+#         (per app-shell.spec.md「WorkspaceBrand 放置 SSOT」+ world-class GitHub/Gmail/Figma 一致)
+#         例外:同 file 用 useSidebar/isMobile = mobile-only 補品牌的正確 responsive fork(豁免)
+#
+#   V3) `layout="primary-header"` + 任何 `<SidebarFooter>...</SidebarFooter>` 在同 file(2026-06-18 beta.74)
+#       → primary-header 帳號入口家在 globalHeader 右(收成 Sheet 鏡像到 Sheet header 右),**不該**用
+#         sidebar footer〔那是 primary-sidebar 帳號家慣例〕→ 誤用 = 模式混淆
+#         (per app-shell.spec.md「帳號入口(Account entry)放置 SSOT」+ Material modal nav drawer
+#         「account switcher 放 drawer header」)。與 V2 不同:primary-header 任何 breakpoint(含 mobile
+#         Sheet)帳號家都在 header 區 → V3 不設 isMobile 豁免;非帳號用途 footer 走 escape allowlist。
+#
+# 對齊 .claude/rules/self-verify.md「Pre-edit」階段 + check_chrome_header_handcraft.sh /
+# check_overlay_handcraft.sh 等既有 SSOT-enforcement hook idiom。
+# Exception escape:`// @app-shell-primary-header-allow: <reason>` 檔頭。
+
+set -uo pipefail
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+# 只看 Edit / Write / MultiEdit tool
+# 2026-05-31 fix(folded-hook-audit):原從 $CLAUDE_TOOL_INPUT env + isatty 讀 → 經 chrome_header_dispatcher
+# 的 stdin pipe 呼叫時 env 為空 → 此 helper 永不 fire(dead)。改標準 INPUT=$(cat) + jq,對齊 sibling helper。
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "MultiEdit" ]]; then exit 0; fi
+
+TARGET=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+# 只查 .tsx / .stories.tsx consumer file
+if [[ ! "$TARGET" =~ \.(tsx)$ ]]; then exit 0; fi
+if [[ ! -f "$TARGET" ]]; then exit 0; fi
+
+# 排除 spec / test / SSOT 檔
+case "$TARGET" in
+  *.spec.md|*test*|*/AppShell/app-shell.tsx) exit 0 ;;
+esac
+
+# Escape allowlist
+if grep -q "@app-shell-primary-header-allow:" "$TARGET"; then exit 0; fi
+
+# 偵測 layout="primary-header"(三種 JSX 形式:layout="x" / layout={"x"} / layout={'x'})
+# 2026-06-18 beta.74 fix(adversarial audit P1):舊 `["\047]` 想用 octal \047 表單引號,但 BRE char-class
+# **不** interpret octal → 單引號 JSX `layout={'primary-header'}` 整個 hook 靜默 skip(false-negative)。
+# 改 grep -E + 字面單/雙引號 alternation(`('\''|")`)— 三種引號形式皆match。⚠️ 驗證用 /usr/bin/grep,
+# 互動 shell 的 wrapped grep 對 octal 給相反結果會藏 bug。
+if ! grep -Eq 'layout="primary-header"|layout=\{('\''|")primary-header('\''|")\}' "$TARGET"; then exit 0; fi
+
+VIOLATIONS=()
+
+# V1:layout="primary-header" 但無 globalHeader=
+if ! grep -q 'globalHeader\s*=' "$TARGET"; then
+  VIOLATIONS+=("V1 缺 globalHeader prop:layout=\"primary-header\" 必傳 globalHeader 否則邏輯矛盾(per app-shell.spec.md「primary-header = primary-sidebar + 一條 global header」)")
+fi
+
+# V2:layout="primary-header" + <SidebarHeader> 同 file → WorkspaceBrand 該在 globalHeader 不重複。
+# 例外(2026-06-18 responsive 精修,M34 hook-intent 對齊):同 file 也用 useSidebar/isMobile =
+# mobile-only 補品牌的「正確 responsive fork」(小螢幕 Sheet 蓋住 globalHeader → Sheet 內補同組 primitive,
+# desktop 仍無 SidebarHeader,非真重複)→ 不 flag。見 app-shell.spec.md WorkspaceBrand SSOT「Responsive 精修」子句。
+# ⚠️ 限制(2026-06-18 beta.74 audit 記錄):V2 是 token-presence 啟發式(file 含 useSidebar/isMobile 即豁免),
+#    非「isMobile 真的 guard 該 <SidebarHeader>」的 AST 級判斷 → 罕見假陰性(unguarded SidebarHeader 但 file
+#    因別處用 isMobile → 漏擋)。bash 無法精準 AST;靠 code review + escape allowlist 兜底,目前唯一 consumer(stories)正確。
+#    要嚴格需 TS AST lint rule(future)。
+# tag boundary `([^A-Za-z]|$)`(2026-06-18 audit P2#4):避免 prefix-extended 名(<SidebarHeaderXyz>)誤觸
+if grep -Eq '<SidebarHeader([^A-Za-z]|$)' "$TARGET" && ! grep -qE 'useSidebar|isMobile' "$TARGET"; then
+  VIOLATIONS+=("V2 Sidebar 內含 SidebarHeader:primary-header mode WorkspaceBrand 該在 globalHeader,sidebar 內不該重複(per spec.md「WorkspaceBrand 放置 SSOT」+ world-class GitHub/Gmail/Figma 共識)。若是 mobile-only responsive 補品牌請用 useSidebar().isMobile 條件渲染(自動豁免);若 sidebar header 是其他內容(非 brand),加 escape allowlist `// @app-shell-primary-header-allow:` 並說明 reason")
+fi
+
+# V3:layout="primary-header" + <SidebarFooter> 同 file → 帳號入口家在 globalHeader 右,不該用 sidebar footer。
+# 與 V2 不同 — primary-header 收成 Sheet 時帳號鏡像到 Sheet **header** 右(非 footer),故任何 breakpoint 都不該
+# 有 SidebarFooter 放帳號 → V3 不設 isMobile 豁免(per app-shell.spec.md「帳號入口(Account entry)放置 SSOT」
+# Responsive 精修「不放 SidebarFooter」+ Material modal nav drawer「account switcher 放 drawer header」)。
+# demo 天然不誤觸:layout="primary-header" 在 stories,<SidebarFooter> 在 _demo-helpers.tsx,分檔。
+# 非帳號用途 footer(storage meter / collapse 等)→ escape allowlist 兜底。
+if grep -Eq '<SidebarFooter([^A-Za-z]|$)' "$TARGET"; then
+  VIOLATIONS+=("V3 Sidebar 內含 SidebarFooter:primary-header mode 帳號入口家在 globalHeader 右(收成 Sheet 鏡像到 Sheet header 右),不該用 sidebar footer〔那是 primary-sidebar 慣例〕(per spec.md「帳號入口(Account entry)放置 SSOT」+ Material modal nav drawer)。若 footer 是非帳號用途,加 escape allowlist \`// @app-shell-primary-header-allow:\` 並說明 reason")
+fi
+
+if [[ ${#VIOLATIONS[@]} -gt 0 ]]; then
+  echo "🚨 AppShell primary-header consistency violation" >&2
+  echo "Target: $TARGET" >&2
+  for v in "${VIOLATIONS[@]}"; do echo "  • $v" >&2; done
+  echo "" >&2
+  echo "修法:" >&2
+  echo "  (a) 傳 globalHeader prop / 撤掉 SidebarHeader" >&2
+  echo "  (b) 改 layout=\"primary-sidebar\"(若不需要 global header)" >&2
+  echo "  (c) Escape 允許:檔首加 \`// @app-shell-primary-header-allow: <rationale>\`" >&2
+  exit 2
+fi
+
+exit 0

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

@@ -0,0 +1,33 @@
+#!/bin/bash
+# SSOT approval keyword regex(M17 + M34,2026-05-18 codify per audit GAP 6)
+#
+# Used by:
+#   - check_substantive_edit_approval_preflight.sh(pre-flight Edit/Write production)
+#   - stop_self_audit.sh Mechanism 4(post-flight codex-design ship verify)
+#   - check_solo_workflow.sh R3(push main trigger detect)
+#
+# Background:GAP 6 audit(2026-05-18) found approval regex duplicated 3 places + drift:
+# preflight 已加 `#[N] A` numbered directive + 照建議 / 照共識 reference-style
+# 但 stop_self_audit / solo_workflow 沒 sync。
+# 抽出 single SSOT,source from all consumers,確保未來 update 自動 propagate。
+
+# 完整 approval keyword regex(extended POSIX)
+#
+# 涵蓋:
+# (1) 明確同意:同意 / 採用 / 採納 / 拍板 / 可以 / OK / 好 / approved / approve / 沒問題
+# (2) 動作指令:改成 / 改為 / 執行 / 上吧 / push / implement / go ahead / ship / 上 main
+# (3) 大批做:做一做 / 就做 / 做吧 / 做完 / 全部做完 / 做到完 / 馬不停蹄 / 全部照建議做
+# (4) 建議認可:建議做 / 照你建議 / 照建議 / 照共識 / 照我的 / 按照(代詞 reference)
+# (5) Numbered directive:#1 A / #2 B / 1. B / 2. A 類 user 點選 option
+# (6) 合 main trigger(R3 solo workflow specific):合進去 / 合 main / merge / 上 main
+# (7) Past-tense 認可:好了 / OK 了 / 可以了 / 沒問題了 / 同意了 / 拍板了
+# 2026-05-18 syntactic fix:加 closing `)` 收尾(原 `grep: parentheses not balanced`
+# 錯誤造成 hook silent fail-closed BLOCKER。純語法 bug,**不** widen 偵測 scope —
+# 既有 keyword list 不動。
+export APPROVAL_KEYWORD_RE='(同意|採用|採納|拍板|可以|改成|改為|執行|上吧|push|publish|release|implement|go ahead|approved|approve|OK|好|沒問題|做一做|就做|做吧|做完|全部做完|做到完|馬不停蹄|全部照建議做|建議做|照你建議|照建議|照共識|照我的|按照|合進去|合\s*main|merge|上\s*main|ship|好了|OK\s*了|可以了|沒問題了|同意了|拍板了|#[0-9]+\s*[A-Za-z]|^[0-9]+\.\s*[A-Za-z])'
+
+# Helper:check input string contains approval keyword
+# Usage: if has_approval "$user_msg"; then ...
+has_approval() {
+  echo "$1" | grep -qE "$APPROVAL_KEYWORD_RE"
+}

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

@@ -0,0 +1,75 @@
+#!/bin/bash
+set -uo pipefail
+# Header canonical Layer 3 ChromeHeader consumption enforcement(per header-canonical.spec.md Layer 3):
+#   Production chrome header 必消費 `<ChromeHeader>` primitive,
+#   不可自寫 `h-[var(--chrome-header-height)] border-b border-divider px-loose` 那一套 className。
+#
+# PreToolUse(Edit / Write)hook —— 編輯 `packages/design-system/src/components/**/*.tsx`(非 stories)時掃:
+#   檔內若有完整手刻 chrome header className signature → **P0 BLOCKER(exit 2)**。
+#   2026-06-06 升 P0:migration 完成(header-canonical.spec.md L245「grep 全 repo 已無此手刻 signature
+#   除 primitive 本身」)+ 0 殘留手刻 verified → 跟 item-anatomy C.4 row-handcraft P0 對稱。Escape 仍在。
+#
+# 當前期(2026-05-17 land Phase 2):Sidebar / FileViewer 已 migrate 完,其他元件若新加 chrome
+# header 自刻 = drift,本 hook 攔。
+#
+# Allow escape:檔頭 `// @chrome-header-handcraft-allow: <reason>` 豁免(Tabs cva-on-pattern 等
+# 不適合用 primitive 的 case);本 hook 本身與 ChromeHeader / SurfaceHeader / SidebarHeader.tsx
+# 不攔(那些是 primitive 自己)。
+
+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
+
+case "$FILE_PATH" in
+  */packages/design-system/src/components/**/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+# Skip stories
+case "$FILE_PATH" in
+  *.stories.tsx|*.anatomy.stories.tsx|*.principles.stories.tsx) exit 0 ;;
+esac
+
+# Skip primitive home(SidebarHeader 內部消費 ChromeHeader,但仍有 className signature 引用)
+case "$FILE_PATH" in
+  */ChromeHeader/*|*/header-canonical/*|*/overlay-surface/*) 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
+')
+
+# Allow escape
+if echo "$NEW_CONTENT" | grep -qE '@chrome-header-handcraft-allow:'; then
+  exit 0
+fi
+
+# Detect handcraft signature: h-[var(--chrome-header-height)] paired with border-b border-divider
+# 2026-06-03 修(同 R8 multiline bug class,對抗稽核抓到):tr 換行→空格 flatten。真實 JSX className
+# 跨行(h-[...] 與 border-b 分行)+ [^"]* 跨屬性匹配 → 不 flatten 的話多行靜默漏(現 warn-only,但
+# Phase 3 升 P0 後會 false-negative)。tr 後整段成單行,[^"]* 才能跨原換行匹配。
+HANDCRAFT_HIT=$(echo "$NEW_CONTENT" | tr '\n' ' ' | grep -cE 'h-\[var\(--chrome-header-height\)\][^"]*border-b[^"]*border-divider' || true)
+
+if [ "$HANDCRAFT_HIT" -gt "0" ]; then
+  printf '❌ CHROME HEADER HANDCRAFT(P0 BLOCKER):\n' >&2
+  printf '   File: %s\n' "$FILE_PATH" >&2
+  printf '   偵測到自刻 `h-[var(--chrome-header-height)] ... border-b border-divider`\n' >&2
+  printf '\n  SSOT: patterns/header-canonical/header-canonical.spec.md Layer 3\n' >&2
+  printf '  修方向: import { ChromeHeader } from "@/design-system/patterns/header-canonical/chrome-header"\n' >&2
+  printf '          替換 <div className="..."> → <ChromeHeader withTabs? leadingRail? lockDensity?>\n' >&2
+  printf '  Escape: 檔頭加 // @chrome-header-handcraft-allow: <rationale>\n' >&2
+  exit 2
+fi
+
+exit 0

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

@@ -0,0 +1,73 @@
+#!/bin/bash
+# PostToolUse hook: lightweight code quality check on tsx/ts edit.
+# Only runs the 2 fastest checks:
+#   1. `any` usage without `// any-allow:` escape hatch
+#   2. tsx file-size P0 (> 800 transition cap)
+#
+# Full audit (dead export / circular / long function) — use `/code-quality-audit` skill.
+
+# 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
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+
+# Scope: only src/ .tsx / .ts files (not stories, not specs)
+if ! echo "$FILE_PATH" | grep -qE 'src/.*\.tsx?$'; then
+  exit 0
+fi
+if echo "$FILE_PATH" | grep -qE '\.(stories|anatomy\.stories|principles\.stories)\.tsx$'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+VIOLATIONS=""
+
+# ── Check 1: `any` usage ────────────────────────────────────────────────────
+# Flag `: any` / `as any` / `<any>` / `any[]` / `Record<X, any>`
+# Skip lines with `any-allow` OR previous line with `any-allow`.
+ANY_HITS=$(perl -ne '
+  BEGIN { our $prev_allow = 0; }
+  my $has_allow = /any-allow/;
+  my $line = $_;
+  if (!$prev_allow && !$has_allow) {
+    next if m{^\s*//};
+    next if m{^\s*\*};
+    next if m{/\* ?@ts-};
+    # Patterns
+    if (/:\s*any\b/ || /\bas\s+any\b/ || /<any>/ || /\bany\[\]/ || /Record<[^,]+,\s*any>/) {
+      # String literal FPs
+      unless (/[\x27"](any|many)[\x27"]/i) {
+        print "$.:$line";
+      }
+    }
+  }
+  $prev_allow = $has_allow;
+' "$FILE_PATH" 2>/dev/null | head -5)
+
+if [ -n "$ANY_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ TypeScript \`any\` usage(無 \`// any-allow: {rationale}\`):\n${ANY_HITS}\n  修法:改 proper type;真沒辦法(e.g. 3rd-party 類型外部化)→ 在同行或上一行加 \`// any-allow: {具體 rationale}\`"
+fi
+
+# ── Check 2: tsx file size ──────────────────────────────────────────────────
+if echo "$FILE_PATH" | grep -qE '\.tsx$'; then
+  LINES=$(wc -l < "$FILE_PATH" | tr -d ' ')
+  # Exemption marker in top 20 lines: `// code-quality-allow: file-size {rationale}`
+  EXEMPT=$(head -20 "$FILE_PATH" | grep -cE 'code-quality-allow:\s*file-size' || true)
+  if [ "$LINES" -gt 800 ] && [ "$EXEMPT" -eq 0 ]; then
+    VIOLATIONS="${VIOLATIONS}\n⚠️ tsx file-size P0:${LINES} 行 > 800 transition cap(budget 500)。架構性拆分考慮:分 sub-component tsx(e.g. sidebar.tsx → sidebar.tsx + sidebar-menu.tsx + sidebar-group.tsx)。若係 foundational composite(Sidebar/TreeView 等),tsx 頂部加 \`// code-quality-allow: file-size {rationale}\` 明文豁免。"
+  fi
+fi
+
+# ── Emit warning ─────────────────────────────────────────────────────────
+if [ -n "$VIOLATIONS" ]; then
+  ESCAPED=$(printf "%b" "$VIOLATIONS" | jq -Rs .)
+  cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Code quality lite check(full audit via /code-quality-audit):${ESCAPED}"}}
+EOJSON
+fi
+
+exit 0

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

@@ -0,0 +1,69 @@
+#!/bin/bash
+# PostToolUse hook for Edit/Write on component .tsx:
+# When a change touches cva() defaultVariants, grep for 3-way consistency across
+# spec.md + docblock + anatomy.stories.tsx and warn if any disagree on the default.
+#
+# Prevents the SegmentedControl bug class: cva says 'md', spec/docblock/anatomy say
+# 'sm ★default' — silently drifts until audit catches it.
+#
+# Exit: 0 + stdout JSON additionalContext (non-blocking warning)
+
+# 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)
+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 target component .tsx files (not stories, not specs)
+if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/components/[^/]+/[^/]+\.tsx$'; then
+  exit 0
+fi
+echo "$FILE_PATH" | grep -qE '\.stories\.tsx$' && exit 0
+
+# Only fire if the file actually contains defaultVariants (post-edit state)
+[ -f "$FILE_PATH" ] || exit 0
+grep -q "defaultVariants" "$FILE_PATH" || exit 0
+
+# Diff-aware: only fire if this edit actually touched cva / defaultVariants content.
+# Extract old_string + new_string (Edit / MultiEdit) or content (Write) — if none
+# mention cva(, defaultVariants, or variants: , skip noise.
+DIFF_TEXT=$(echo "$INPUT" | jq -r '
+  (.tool_input.old_string // "") + "\n" +
+  (.tool_input.new_string // "") + "\n" +
+  (.tool_input.content    // "") + "\n" +
+  ([.tool_input.edits[]? | (.old_string + "\n" + .new_string + "\n")] | join(""))
+' 2>/dev/null || echo "")
+if [ -n "$DIFF_TEXT" ] && ! echo "$DIFF_TEXT" | grep -qE 'cva\(|defaultVariants|variants:[[:space:]]*\{'; then
+  exit 0
+fi
+
+COMP_DIR=$(dirname "$FILE_PATH")
+COMP_NAME=$(basename "$COMP_DIR")
+SPEC_FILE="$COMP_DIR/$(basename "$FILE_PATH" .tsx).spec.md"
+ANATOMY_FILE="$COMP_DIR/$(basename "$FILE_PATH" .tsx).anatomy.stories.tsx"
+
+# Extract default values from each source (best-effort grep; signal not proof)
+CVA_DEFAULTS=$(grep -A5 "defaultVariants" "$FILE_PATH" 2>/dev/null | grep -E "(size|variant|state):" | head -3 | tr -d ' "' | sed 's/,$//' || echo "")
+SPEC_DEFAULTS=""
+[ -f "$SPEC_FILE" ] && SPEC_DEFAULTS=$(grep -E "★|預設|default" "$SPEC_FILE" 2>/dev/null | head -5 || echo "")
+ANATOMY_DEFAULTS=""
+[ -f "$ANATOMY_FILE" ] && ANATOMY_DEFAULTS=$(grep -E "★|default|defaultVariants" "$ANATOMY_FILE" 2>/dev/null | head -5 || echo "")
+
+WARNING="⚠️ $COMP_NAME cva/defaultVariants touched — verify 3-way sync: tsx cva ↔ spec.md default markers ↔ anatomy SIZE_SPECS. Ref: SegmentedControl drift bug. Grep \"★|預設|default\" in $COMP_DIR/."
+
+# Escape for JSON via jq
+ESCAPED=$(printf '%s' "$WARNING" | jq -Rs .)
+
+cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":$ESCAPED}}
+EOJSON
+
+exit 0

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

@@ -0,0 +1,49 @@
+#!/bin/bash
+# _governance_coverage_check.sh — PostToolUse helper:
+# 偵測 governance file edit(meta-patterns / spec.md frontmatter / hook / SKILL / rules)
+# → 跑 audit-preflight.mjs --check 比 baseline 是否新增 coverage gap
+# → 有 gap → stderr inject 警告:user 必補 audit dim or 撤原則
+#
+# 對應 SSOT:
+# - memory/feedback_audit_preflight_全盤查.md(2026-05-15 codified)
+# - design-system-audit/SKILL.md Phase 0.5 invariant
+# - user 原話「確保現在和未來都會自動涵蓋,當有新的準則就務必更新設計系統進階稽核的內容」
+#
+# 由 post_edit_dispatcher.sh orchestrate,non-standalone hook(不算 hook count)
+
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+[ -z "$FILE_PATH" ] && exit 0
+
+# Governance file scope:M-rule / spec.md frontmatter / hook check / SKILL / rules
+GOV_RE='(meta-patterns\.md|/spec\.md$|check_.*\.sh$|/SKILL\.md$|\.claude/rules/.*\.md$|CLAUDE\.md$)'
+echo "$FILE_PATH" | grep -qE "$GOV_RE" || exit 0
+
+# Pre-check audit-preflight 存在
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PREFLIGHT="$PROJECT_DIR/scripts/audit-preflight.mjs"
+[ -f "$PREFLIGHT" ] || exit 0
+
+# 跑 preflight check mode(silent;exit 1 if gap)
+PREFLIGHT_OUT=$(cd "$PROJECT_DIR" && node scripts/audit-preflight.mjs --check 2>&1)
+PREFLIGHT_EXIT=$?
+
+if [ "$PREFLIGHT_EXIT" -eq 1 ]; then
+  TODAY=$(date +%Y-%m-%d)
+  LOG_FILE="$PROJECT_DIR/.claude/logs/audit-preflight-${TODAY}.json"
+  GAP_COUNT=0
+  GAP_SAMPLE=""
+  if [ -f "$LOG_FILE" ]; then
+    GAP_COUNT=$(jq -r '.coverageGaps // 0' "$LOG_FILE" 2>/dev/null || echo 0)
+    GAP_SAMPLE=$(jq -r '.gaps[:3] | .[]' "$LOG_FILE" 2>/dev/null | head -3 | tr '\n' ',' | sed 's/,$//')
+  fi
+
+  ADDITIONAL_CONTEXT="⚠️ Governance coverage gap(audit-preflight): ${FILE_PATH##*/} edit 後 ${GAP_COUNT} 原則無 audit dim cover(包含: ${GAP_SAMPLE})。若新加入的原則 → 必補 audit dim 進 design-system-audit/SKILL.md。若既有 false-positive(heuristic 不準)→ sub-agent semantic verify。SSOT: memory/feedback_audit_preflight_全盤查.md"
+
+  jq -n --arg ctx "$ADDITIONAL_CONTEXT" '{
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+  }'
+fi
+
+exit 0

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

@@ -0,0 +1,163 @@
+#!/bin/bash
+# PostToolUse hook: flag hardcoded user-facing strings in DS component tsx
+# (CJK ≥ 3 chars or English ≥ 8 chars that look like sentence-case labels).
+#
+# Rationale(CLAUDE.md # Internationalization / 24-checklist #13 gap):
+#   DS primitive 的文案若 hardcode,consumer 換語言 / A/B test label 時要 forkDS。
+#   正確路線:prop 接收 + `loadingText` / `emptyText` 等 slot,或走 i18n 層。
+#
+# Scope:
+#   - ONLY packages/design-system/src/components/**/*.tsx(primitives)
+#   - ONLY patterns/ 如果出現 user-facing string
+#   - SKIP stories.tsx(stories 用真實 Jira/Stripe 範例 = 刻意)
+#   - SKIP spec.md / anatomy
+#
+# Whitelist(不 flag):
+#   - 註解 // /* */
+#   - `aria-label` / `title` 等 a11y prop 若無對應 prop 可接收 → 仍 flag(warn 改成 prop)
+#   - 標示 `// i18n-allow: {rationale}` 該行白名單
+#
+# WARN-style, 不 block.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+
+# Scope: only design-system components/patterns .tsx
+if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/(components|patterns)/.*\.tsx$'; then
+  exit 0
+fi
+if echo "$FILE_PATH" | grep -qE '\.(stories|principles|anatomy\.stories)\.tsx$'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Detect hardcoded user-facing CJK / English labels via perl oneliner
+# (macOS-portable: perl is always present; grep -P / pcregrep / rg 不一定有)
+#
+# Perl logic(per line):
+#  1. 跳過 `// ...` 單行註解(但不影響行內其他 content 判斷 — 我們直接跳整行簡化)
+#  2. 跳過 `/* ... */` 一行註解
+#  3. 跳過該行含 `i18n-allow` 白名單標記
+#  4. 對剩餘行偵測 JSX 文字節點 `>...<` 或字串字面量 `"..."` / `'...'`
+#     內含 ≥ 3 個 CJK 字元(\p{Han} / \p{Hiragana} / \p{Katakana} / \p{Hangul})
+#  5. English:narrow detection,僅當 JSX 文字節點或屬性值含 ≥ 2 個 sentence-case 詞
+#
+# Output: "line_num:matched_snippet"(每 file 最多 5 條)
+
+VIOLATIONS=""
+
+CJK_HITS=$(perl -CSD -ne '
+  BEGIN {
+    our $jsdoc = 0; our $console_open = 0; our $jsx_comment = 0;
+    our $allow_pending = 0; our $allow_depth = 0;
+  }
+  # ── block-level i18n-allow:上一行有 `// i18n-allow-block` 或
+  # `// i18n-allow`(單獨 comment 行)→ 標記下一個 `{...}` 區塊整個 skip ──
+  if (m{^\s*(?://|/\*+)\s*i18n-allow(-block)?\b}) { $allow_pending = 1; next }
+  if ($allow_pending && m{[\{\[]}) {
+    $allow_pending = 0;
+    my $opens = () = /[\{\[]/g; my $closes = () = /[\}\]]/g;
+    $allow_depth = $opens - $closes;
+    next if $allow_depth > 0;  # only enter block if net positive opens
+  }
+  if ($allow_depth > 0) {
+    my $opens = () = /[\{\[]/g; my $closes = () = /[\}\]]/g;
+    $allow_depth += $opens - $closes;
+    next;
+  }
+  # ── JSDoc block(多行 /** ... */)── stateful ──
+  if (!$jsdoc && m{/\*\*}) { $jsdoc = 1 }
+  if ($jsdoc) {
+    if (m{\*/}) { $jsdoc = 0 }
+    next;
+  }
+  # ── JSX block comment(多行 {/* ... */})── stateful ──
+  if (!$jsx_comment && m{\{/\*}) { $jsx_comment = 1 }
+  if ($jsx_comment) {
+    if (m{\*/\s*\}}) { $jsx_comment = 0 }
+    next;
+  }
+  # ── Line-level 註解 skip ──────────────
+  next if m{^\s*//};                    # single-line comment
+  next if m{^\s*/\*.*\*/\s*$};          # single-line block comment
+  next if m{^\s*\*};                    # stray JSDoc line
+  next if m{i18n-allow};
+  # ── strip trailing `//` comments(naïve:不處理 URL 等 string 內 `//`)─
+  # Fix FP:`code() // CJK comment` 被誤匹配 comment 內的 CJK
+  # 注意:不能用 `[^\x27"]` 限制,comment 內可能有 `"` 被 CJK 夾住
+  # 簡單策略 — `//` 後到 EOL 全 strip(string 內的 `//` 罕見 → 可接受 FP trade)
+  $_ =~ s{\s+//.*$}{};
+  # ── dev-only console.* / throw new Error() multi-line — stateful ─
+  # 這些是 DS internal dev / developer-facing diagnostics,consumer 看不到
+  if (!$console_open && m{(console\.(warn|error|log|info|debug)|throw\s+new\s+(Error|TypeError|RangeError))\s*\(}) {
+    $console_open = 1;
+    if (m{\)\s*[;,]?\s*$}) { $console_open = 0 }
+    next;
+  }
+  if ($console_open) {
+    if (m{\)\s*[;,]?\s*$}) { $console_open = 0 }
+    next;
+  }
+  # ── DS-internal metadata keys(designer-facing,非 end-user-facing)──
+  # 典型:buttonMeta / componentMeta / story args 的 `purpose:` / `description:` / `rationale:` / `when:` / `dont:` / `note:` / `text:`(stories)
+  # 匹配「行內任何位置出現 `{metadata_key}: "..."`」:如 `primary: { purpose: "..." }` 的 purpose
+  next if m{\b(purpose|description|rationale|when|dont|note|tip|detail|explanation|summary)\s*:\s*[\x27"]};
+  # ── JSX text node or string literal with CJK ≥ 3 ─
+  if (m{([>"\047])([^<"\047]*?[\p{Han}\p{Hiragana}\p{Katakana}\p{Hangul}]{3,}[^<"\047]*?)([<"\047])}) {
+    my $snippet = $2;
+    $snippet =~ s/^\s+|\s+$//g;
+    $snippet = substr($snippet, 0, 80) . "…" if length($snippet) > 80;
+    print "$.:$snippet\n";
+  }
+' "$FILE_PATH" 2>/dev/null | head -5)
+
+if [ -n "$CJK_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Hardcoded CJK strings in DS primitive(consumer 換語言要 fork 元件):\n${CJK_HITS}\n  修法:改成 prop 接收(e.g. \`loadingText / emptyText / label\` slot)。若確實 DS 層預設(如 internal debug),在該行末加 \`// i18n-allow: {rationale}\` 白名單。"
+fi
+
+# English sentence-case labels — narrow detection
+ENG_HITS=$(perl -CSD -ne '
+  BEGIN { our $allow_pending = 0; our $allow_depth = 0; }
+  # ── block-level i18n-allow(同 CJK block)─
+  if (m{^\s*(?://|/\*+)\s*i18n-allow(-block)?\b}) { $allow_pending = 1; next }
+  if ($allow_pending && m{[\{\[]}) {
+    $allow_pending = 0;
+    my $opens = () = /[\{\[]/g; my $closes = () = /[\}\]]/g;
+    $allow_depth = $opens - $closes;
+    next if $allow_depth > 0;  # only enter block if net positive opens
+  }
+  if ($allow_depth > 0) {
+    my $opens = () = /[\{\[]/g; my $closes = () = /[\}\]]/g;
+    $allow_depth += $opens - $closes;
+    next;
+  }
+  # ── 註解 skip(line-level)─────────────────────
+  next if m{^\s*//};
+  next if m{^\s*/\*.*\*/\s*$};
+  next if m{^\s*\*};
+  next if m{^\s*/\*\*?\s*$};
+  next if m{i18n-allow};
+  next if m{console\.(warn|error|log|info|debug)\s*\(};
+  next if m{className=|aria-label=|data-\w+=|href=|key=};
+  if (m{>([A-Z][a-z]+ [a-z]+(?: [a-z]+)+)<} || m{[\"\047]([A-Z][a-z]+ [a-z]+(?: [a-z]+)+)[\"\047]}) {
+    print "$.:$1\n";
+  }
+' "$FILE_PATH" 2>/dev/null | head -3)
+
+if [ -n "$ENG_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Hardcoded English sentence-case labels:\n${ENG_HITS}\n  若是 user-facing label,改 prop 接收;若是 internal,加 \`// i18n-allow\` 白名單。"
+fi
+
+# ── Emit warning if any violation ────────────────────────────────────────────
+if [ -n "$VIOLATIONS" ]; then
+  ESCAPED=$(printf "%b" "$VIOLATIONS" | jq -Rs .)
+  cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"i18n hygiene 檢查(24-checklist #13 gap):${ESCAPED}\n\nDS primitive 應 prop-driven,hardcoded 文案讓 consumer 換語言時要 fork。"}}
+EOJSON
+fi
+
+exit 0

package/ds-canonical/hooks/lib/_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