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

package/ds-canonical/hooks/tests/test_block_prototype_imports.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# Tests for block_prototype_imports.py
+#
+# This hook is PostToolUse — reads files from disk via os.path.exists, so we
+# create real temp files inside src/ tree to drive each scenario.
+#
+# Usage: bash test_block_prototype_imports.sh
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../block_prototype_imports.py"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+if [ ! -f "$HOOK" ]; then
+  echo "FATAL: hook not found: $HOOK"
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+# Sandbox dir for temp files inside src/ (so should_check passes prefix gate)
+SANDBOX="$PROJECT_ROOT/src/.test-block-prototype-imports-$$"
+mkdir -p "$SANDBOX"
+trap 'rm -rf "$SANDBOX"' EXIT
+
+run_hook() {
+  local file_path="$1"
+  local payload
+  payload=$(jq -n --arg fp "$file_path" \
+    '{tool_name: "Write", tool_input: {file_path: $fp}}')
+
+  STDOUT=$(mktemp)
+  STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | python3 "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDOUT_TEXT=$(cat "$STDOUT")
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass() {
+  local name="$1"
+  if [ "$EXIT" = "0" ]; then
+    echo "  PASS  $name"
+    PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit 0, got $EXIT)"
+    echo "$STDOUT_TEXT" | sed 's/^/    /'
+    FAIL=$((FAIL+1))
+    FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_block() {
+  local name="$1"
+  local needle="$2"
+  if [ "$EXIT" = "2" ]; then
+    if echo "$STDOUT_TEXT" | grep -qF "$needle"; then
+      echo "  PASS  $name"
+      PASS=$((PASS+1))
+    else
+      echo "  FAIL  $name (exit 2 OK but stdout missing '$needle')"
+      echo "$STDOUT_TEXT" | sed 's/^/    /'
+      FAIL=$((FAIL+1))
+      FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+    fi
+  else
+    echo "  FAIL  $name (expected exit 2, got $EXIT)"
+    echo "$STDOUT_TEXT" | sed 's/^/    /'
+    FAIL=$((FAIL+1))
+    FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+cd "$PROJECT_ROOT"
+
+# ── Test 1: clean import → pass ──────────────────────────────────────────────
+echo "Test 1: clean tsx with non-explorations import → pass"
+F1="$SANDBOX/clean.tsx"
+cat >"$F1" <<'EOF'
+import { Button } from '@/design-system/components/Button/button'
+export const X = () => <Button>OK</Button>
+EOF
+run_hook "${F1#$PROJECT_ROOT/}"
+expect_pass "Test 1 clean import"
+
+# ── Test 2: import from src/explorations → block ─────────────────────────────
+echo ""
+echo "Test 2: tsx imports from src/explorations/ → block"
+F2="$SANDBOX/violation.tsx"
+cat >"$F2" <<'EOF'
+import { ProtoX } from '@/explorations/foo/bar'
+import { Button } from '@/design-system/components/Button/button'
+export const X = () => <ProtoX />
+EOF
+run_hook "${F2#$PROJECT_ROOT/}"
+expect_block "Test 2 explorations import blocked" "Blocked"
+
+# ── Test 3: file inside src/explorations/ itself → exempt (pass) ──────────────
+echo ""
+echo "Test 3: file IN src/explorations/ importing from explorations → pass (allowed)"
+EXPL_DIR="$PROJECT_ROOT/src/explorations/.test-block-prototype-imports-$$"
+mkdir -p "$EXPL_DIR"
+F3="$EXPL_DIR/proto.tsx"
+cat >"$F3" <<'EOF'
+import { Other } from '@/explorations/other'
+export const Y = () => <Other />
+EOF
+run_hook "${F3#$PROJECT_ROOT/}"
+EXIT_CAPTURED=$EXIT
+rm -rf "$EXPL_DIR"
+EXIT=$EXIT_CAPTURED
+expect_pass "Test 3 explorations file is exempt"
+
+# ── Test 4: non-tsx file (md) → pass ─────────────────────────────────────────
+echo ""
+echo "Test 4: .md file (out of scope) → pass"
+F4="$SANDBOX/note.md"
+echo "import from src/explorations/foo (just text)" >"$F4"
+run_hook "${F4#$PROJECT_ROOT/}"
+expect_pass "Test 4 non-tsx out of scope"
+
+# ── Test 5: nonexistent path → pass (silently skip) ──────────────────────────
+echo ""
+echo "Test 5: nonexistent path → pass (silently skip)"
+run_hook "src/does-not-exist-$$.tsx"
+expect_pass "Test 5 nonexistent path"
+
+# ── Summary ──────────────────────────────────────────────────────────────────
+echo ""
+echo "════════════════════════════════════════"
+echo "  Results: $PASS PASS, $FAIL FAIL"
+echo "════════════════════════════════════════"
+if [ "$FAIL" -gt 0 ]; then
+  printf "Failed tests:%b\n" "$FAILED_TESTS"
+  exit 1
+fi
+exit 0

package/ds-canonical/hooks/tests/test_check_app_shell_primary_header_consistency.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# Tests for check_app_shell_primary_header_consistency.sh
+#
+# Hook(PreToolUse Edit/Write):偵測 AppShell consumer 2 violations:
+#   V1 layout="primary-header" 缺 globalHeader prop
+#   V2 layout="primary-header" + 同 file 含 <SidebarHeader>
+#
+# Hook 透過 CLAUDE_TOOL_INPUT env var 讀 tool_input(JSON {tool_name, tool_input})
+# 且需 TARGET file 真實存在於 disk(`[[ ! -f "$TARGET" ]] && exit 0`)。
+# 排除:.spec.md / *test* / app-shell.tsx 自身 / `@app-shell-primary-header-allow:` escape。
+# Violation 時 stderr「🚨 AppShell primary-header consistency violation」+ exit 2。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../check_app_shell_primary_header_consistency.sh"
+TMPDIR_TEST=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_TEST"' EXIT
+
+if [ ! -x "$HOOK" ]; then chmod +x "$HOOK" 2>/dev/null || true; fi
+if [ ! -f "$HOOK" ]; then echo "FATAL: hook not found: $HOOK"; exit 1; fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+# Helper: write file to test temp dir, run hook with that path
+run_hook_on_file() {
+  local rel="$1"; local content="$2"
+  local fp="$TMPDIR_TEST/$rel"
+  mkdir -p "$(dirname "$fp")"
+  printf '%s' "$content" > "$fp"
+  local payload
+  payload=$(jq -n --arg fp "$fp" --arg tn "Edit" \
+    '{tool_name: $tn, tool_input: {file_path: $fp, new_string: ""}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  CLAUDE_TOOL_INPUT="$payload" bash "$HOOK" >"$STDOUT" 2>"$STDERR" </dev/null
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+# Helper: run with arbitrary path (non-existent) for skip tests
+run_hook_no_file() {
+  local fp="$1"; local tool="${2:-Edit}"
+  local payload
+  payload=$(jq -n --arg fp "$fp" --arg tn "$tool" \
+    '{tool_name: $tn, tool_input: {file_path: $fp, new_string: ""}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  CLAUDE_TOOL_INPUT="$payload" bash "$HOOK" >"$STDOUT" 2>"$STDERR" </dev/null
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent, exit=$EXIT, stderr non-empty=$([ -n "$STDERR_TEXT" ] && echo yes))"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_block() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "2" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit=2 + needle '$needle', got exit $EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_app_shell_primary_header_consistency tests ==="
+
+# 1. Non-tsx file → skip
+run_hook_no_file "$TMPDIR_TEST/foo.md" "Edit"
+expect_pass_silent "1. non-tsx file → skip"
+
+# 2. Non-Edit/Write tool → skip
+run_hook_no_file "$TMPDIR_TEST/foo.tsx" "Read"
+expect_pass_silent "2. Read tool → skip"
+
+# 3. layout="primary-header" with globalHeader + no SidebarHeader → silent (compliant)
+run_hook_on_file "src/app.tsx" '
+<AppShell layout="primary-header" globalHeader={<GlobalHeader />}>
+  <Sidebar />
+</AppShell>
+'
+expect_pass_silent "3. primary-header + globalHeader + no SidebarHeader → silent"
+
+# 4. layout="primary-header" missing globalHeader → block (V1)
+run_hook_on_file "src/missing-gh.tsx" '
+<AppShell layout="primary-header">
+  <Sidebar />
+</AppShell>
+'
+expect_block "4. V1 missing globalHeader → block" "V1 缺 globalHeader prop"
+
+# 5. layout="primary-header" + <SidebarHeader> with globalHeader → V2 only block
+run_hook_on_file "src/dup-header.tsx" '
+<AppShell layout="primary-header" globalHeader={<GH />}>
+  <Sidebar>
+    <SidebarHeader>brand</SidebarHeader>
+  </Sidebar>
+</AppShell>
+'
+expect_block "5. V2 SidebarHeader duplicate → block" "V2 Sidebar 內含 SidebarHeader"
+
+# 6. Escape allowlist → silent
+run_hook_on_file "src/escape.tsx" '// @app-shell-primary-header-allow: legacy migration in progress
+<AppShell layout="primary-header">
+  <SidebarHeader>brand</SidebarHeader>
+</AppShell>
+'
+expect_pass_silent "6. escape allowlist → silent"
+
+# 7. No primary-header layout at all → skip
+run_hook_on_file "src/other.tsx" '
+<AppShell layout="primary-sidebar">
+  <Sidebar />
+</AppShell>
+'
+expect_pass_silent "7. layout != primary-header → skip"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:$FAILED_TESTS"
+  exit 1
+fi

package/ds-canonical/hooks/tests/test_check_audit_post_report_validator.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# Tests for check_audit_post_report_validator.sh
+#
+# Hook(PostToolUse Write/Edit/MultiEdit):驗 audit report quality:
+#   A) NO-SAMPLE keyword 偵測
+#   B) Dim ≥ 46 coverage
+#   C) audit-prompts.md prompt count
+#   D) @benchmark-unverified-blanket count drift
+#   E) prune-chain-trigger → emit additionalContext JSON
+#
+# 只 fire 在 file_path matches `*/audit-report-*.json` 或 `*/project_audit_progress.md`,
+# 且 file 必須真實存在於 disk(`[ -f "$FILE_PATH" ] || exit 0`)。
+# 輸出至 stdout(JSON additionalContext)時是 trigger_prune=1 路徑;非 prune trigger 走 silent。
+# 注意:hook 內 WARNINGS 累積但 stderr 不直接 print(只 stdout JSON);此測試 verify stdout JSON。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../check_audit_post_report_validator.sh"
+TMPDIR_TEST=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_TEST"' EXIT
+
+if [ ! -f "$HOOK" ]; then echo "FATAL: hook not found: $HOOK"; exit 1; fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+run_hook() {
+  local file_path="$1"; local tool="$2"
+  local payload
+  payload=$(jq -n --arg fp "$file_path" --arg tn "$tool" \
+    '{tool_name: $tn, tool_input: {file_path: $fp}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  export CLAUDE_PROJECT_DIR="$TMPDIR_TEST"
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDOUT_TEXT=$(cat "$STDOUT")
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDOUT_TEXT" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (exit=$EXIT, stdout=[$STDOUT_TEXT], stderr non-empty=$([ -n "$STDERR_TEXT" ] && echo yes))"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_stdout_contains() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "0" ] && echo "$STDOUT_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected stdout contains '$needle', got exit $EXIT)"
+    echo "  --- stdout ---"; echo "$STDOUT_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_audit_post_report_validator tests ==="
+
+# 1. Non-audit file path → skip silently
+run_hook "/tmp/random.txt" "Write"
+expect_silent "1. non-audit path → skip"
+
+# 2. Non-Write/Edit tool → skip silently
+run_hook "$TMPDIR_TEST/.claude/logs/audit-report-foo.json" "Read"
+expect_silent "2. Read tool → skip"
+
+# 3. Audit-report path but file not on disk → skip
+run_hook "$TMPDIR_TEST/.claude/logs/audit-report-missing.json" "Write"
+expect_silent "3. missing file → skip"
+
+# 4. project_audit_progress.md with NO-SAMPLE keyword but no audit-prompts.md → no prune trigger, silent stdout
+mkdir -p "$TMPDIR_TEST/.claude/memory"
+cat > "$TMPDIR_TEST/.claude/memory/project_audit_progress.md" <<'EOF'
+# Audit progress
+Dim 1: pass
+Dim 2: pass
+Dim 3: pass
+EOF
+run_hook "$TMPDIR_TEST/.claude/memory/project_audit_progress.md" "Write"
+# B fires (DIM_COUNT < 46) but no TRIGGER_PRUNE since audit-prompts.md absent + no bench debt
+# stdout should be silent (TRIGGER_PRUNE=0)
+expect_silent "4. valid file no prune trigger → silent stdout"
+
+# 5. audit-prompts.md present but only 2 prompts → TRIGGER_PRUNE=1, stdout JSON
+mkdir -p "$TMPDIR_TEST/.claude/skills/design-system-audit/references"
+cat > "$TMPDIR_TEST/.claude/skills/design-system-audit/references/audit-prompts.md" <<'EOF'
+### Dim 1: foo
+prompt
+
+### Dim 2: bar
+prompt
+EOF
+cat > "$TMPDIR_TEST/.claude/memory/project_audit_progress.md" <<'EOF'
+# Audit progress
+Dim 1: pass
+EOF
+run_hook "$TMPDIR_TEST/.claude/memory/project_audit_progress.md" "Edit"
+expect_stdout_contains "5. audit-prompts coverage low → prune trigger JSON" "prune-chain-trigger"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:$FAILED_TESTS"
+  exit 1
+fi

package/ds-canonical/hooks/tests/test_check_audit_sample_escape.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Tests for check_audit_sample_escape.sh
+#
+# Hook(PreToolUse Agent):dispatch prompt 含 sample escape clause → BLOCK(exit 2)。
+# Only enforce on prompt containing audit-related keyword(audit / Dim N / DS-wide / sub-agent / sweep)。
+# Escape:prompt 含 `@audit-sample-allow:` 整 prompt 豁免。
+# 違規 stderr「🚨 AUDIT NO-SAMPLE ESCAPE CLAUSE BLOCKER」+ exit 2。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../check_audit_sample_escape.sh"
+
+if [ ! -f "$HOOK" ]; then echo "FATAL: hook not found: $HOOK"; exit 1; fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+run_hook() {
+  local tool="$1"; local prompt="$2"
+  local payload
+  payload=$(jq -n --arg tn "$tool" --arg p "$prompt" \
+    '{tool_name: $tn, tool_input: {prompt: $p}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent, exit=$EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_block() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "2" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit=2 + needle '$needle', got exit $EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_audit_sample_escape tests ==="
+
+# 1. Non-Agent tool → skip
+run_hook "Bash" "audit DS-wide sample top 5"
+expect_pass_silent "1. non-Agent tool → skip"
+
+# 2. Agent dispatch without audit keyword → skip
+run_hook "Agent" "refactor this function please"
+expect_pass_silent "2. non-audit prompt → skip"
+
+# 3. Agent + audit keyword + NO sample keyword → silent
+run_hook "Agent" "audit Dim 12 DS-wide full sweep all components"
+expect_pass_silent "3. audit prompt without sample escape → silent"
+
+# 4. Agent + audit + 'sample top 10' → BLOCK
+run_hook "Agent" "audit Dim 24 DS-wide sample top 10 components"
+expect_block "4. sample top N → block" "AUDIT NO-SAMPLE ESCAPE CLAUSE BLOCKER"
+
+# 5. Agent + audit + 'sampled components' → BLOCK
+run_hook "Agent" "Dim 40 DS-wide sub-agent dispatch, sampled components only"
+expect_block "5. sampled components → block" "AUDIT NO-SAMPLE ESCAPE CLAUSE BLOCKER"
+
+# 6. Agent + audit + 'heavy agent needed' → BLOCK
+run_hook "Agent" "audit sweep all 53 dim, heavy agent needed for Dim 25"
+expect_block "6. heavy agent needed → block" "AUDIT NO-SAMPLE ESCAPE CLAUSE BLOCKER"
+
+# 7. Escape allowlist → silent
+run_hook "Agent" "// @audit-sample-allow: rare integration test scope
+audit Dim 99 sample top 3"
+expect_pass_silent "7. @audit-sample-allow escape → silent"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:$FAILED_TESTS"
+  exit 1
+fi

package/ds-canonical/hooks/tests/test_check_benchmark_citation.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# Tests for check_benchmark_citation.sh
+#
+# Hook(PreToolUse Edit/Write/MultiEdit):spec.md / .tsx in packages/design-system/src/
+# 含 world-class benchmark claim(Ant / Material / Polaris ...)必附 inline citation
+# (URL / GitHub #L / snapshots/ / @benchmark-unverified)。違 P1 soft warn(exit 1)。
+# 整檔 escape:前 5 行含 @benchmark-citation-allow: 或 @benchmark-unverified-blanket:。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../check_benchmark_citation.sh"
+
+if [ ! -f "$HOOK" ]; then echo "FATAL: hook not found: $HOOK"; exit 1; fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+# tool_input.content 用於 Write;tool_input.new_string 用於 Edit
+run_hook_write() {
+  local file_path="$1"; local content="$2"
+  local payload
+  payload=$(jq -n --arg fp "$file_path" --arg c "$content" \
+    '{tool_name: "Write", tool_input: {file_path: $fp, content: $c}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent, exit=$EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_warn() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "1" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit=1 + needle '$needle', got exit $EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_benchmark_citation tests ==="
+
+# 1. Non-DS path → skip
+run_hook_write "/tmp/random.tsx" '對齊 Ant Design'
+expect_pass_silent "1. non-DS path → skip"
+
+# 2. DS path no benchmark claim → silent
+run_hook_write "/repo/packages/design-system/src/components/Foo/foo.spec.md" '
+# Foo spec
+普通文字無 world-class claim
+'
+expect_pass_silent "2. no benchmark claim → silent"
+
+# 3. DS path Ant Design claim WITH inline URL → silent
+run_hook_write "/repo/packages/design-system/src/components/Foo/foo.spec.md" '
+對齊 Ant Design 設計
+參考 https://ant-design.com/components/foo
+'
+expect_pass_silent "3. claim + ant-design URL → silent"
+
+# 4. DS path Material claim with GitHub #L cite → silent
+run_hook_write "/repo/packages/design-system/src/components/Foo/foo.tsx" '
+// 對齊 Material UI button(https://github.com/mui/material-ui/blob/master/Button.tsx#L42)
+const x = 1
+'
+expect_pass_silent "4. claim + github #L cite → silent"
+
+# 5. DS path Polaris claim WITHOUT citation → warn
+run_hook_write "/repo/packages/design-system/src/components/Foo/foo.spec.md" '
+# Foo spec
+
+對齊 Polaris 設計派,確保視覺一致。
+'
+expect_warn "5. Polaris claim missing cite → warn" "check_benchmark_citation"
+
+# 6. DS path Atlassian claim with @benchmark-unverified → silent (撤回 marker)
+run_hook_write "/repo/packages/design-system/src/components/Foo/foo.spec.md" '
+# Foo spec
+
+對齊 Atlassian Design @benchmark-unverified 待補 source
+'
+expect_pass_silent "6. claim with @benchmark-unverified → silent"
+
+# 7. File-level @benchmark-citation-allow escape → silent
+run_hook_write "/repo/packages/design-system/src/components/Foo/foo.spec.md" '// @benchmark-citation-allow: legacy migration backlog
+# Foo
+
+對齊 Carbon Design 內部共識。
+對齊 Polaris 派系。
+'
+expect_pass_silent "7. file-level @benchmark-citation-allow → silent"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:$FAILED_TESTS"
+  exit 1
+fi