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

package/ds-canonical/hooks/block_prototype_imports.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+import json
+import os
+import re
+import sys
+import time
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+# Resolve project root from this script's location(stable; cwd may be anywhere
+# depending on how Claude Code invokes the hook)to avoid stray .claude/ trees.
+try:
+    _project_root = os.environ.get('CLAUDE_PROJECT_DIR') or os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    _log_dir = os.path.join(_project_root, '.claude', 'logs')
+    os.makedirs(_log_dir, exist_ok=True)
+    with open(os.path.join(_log_dir, 'hook-fires-per-hook.jsonl'), 'a') as _f:
+        _f.write(json.dumps({'ts': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()), 'hook': os.path.basename(__file__)}) + '\n')
+except Exception:
+    pass
+
+EXPLORATION_PREFIX = "src/explorations/"
+SRC_PREFIX = "src/"
+
+def load_event():
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return None
+
+def collect_file_paths(tool_input):
+    paths = []
+
+    if not isinstance(tool_input, dict):
+        return paths
+
+    file_path = tool_input.get("file_path")
+    if isinstance(file_path, str):
+        paths.append(file_path)
+
+    edits = tool_input.get("edits")
+    if isinstance(edits, list):
+        for item in edits:
+            if isinstance(item, dict):
+                p = item.get("file_path")
+                if isinstance(p, str):
+                    paths.append(p)
+
+    files = tool_input.get("files")
+    if isinstance(files, list):
+        for item in files:
+            if isinstance(item, dict):
+                p = item.get("file_path")
+                if isinstance(p, str):
+                    paths.append(p)
+
+    return list(dict.fromkeys(paths))
+
+def should_check(path):
+    if not path.startswith(SRC_PREFIX):
+        return False
+    if path.startswith(EXPLORATION_PREFIX):
+        return False
+    if not (path.endswith(".ts") or path.endswith(".tsx")):
+        return False
+    return True
+
+def contains_exploration_import(content):
+    patterns = [
+        r'from\s+[\'"].*src/explorations/.*[\'"]',
+        r'from\s+[\'"].*explorations/.*[\'"]',
+        r'import\s+[\'"].*src/explorations/.*[\'"]',
+        r'import\s+[\'"].*explorations/.*[\'"]'
+    ]
+    return any(re.search(p, content) for p in patterns)
+
+def main():
+    event = load_event()
+    if not event:
+        sys.exit(0)
+
+    tool_input = event.get("tool_input", {})
+    touched_paths = collect_file_paths(tool_input)
+
+    offenders = []
+
+    for path in touched_paths:
+        if not should_check(path):
+            continue
+        if not os.path.exists(path):
+            continue
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except Exception:
+            continue
+
+        if contains_exploration_import(content):
+            offenders.append(path)
+
+    if offenders:
+        lines = [
+            "Blocked: 正式程式碼不得 import src/explorations/ 內的檔案。"
+        ]
+        lines.extend(f"- {p}" for p in offenders)
+        print("\n".join(lines))
+        sys.exit(2)
+
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/ds-canonical/hooks/check_app_shell_primary_header_consistency.sh

@@ -0,0 +1,68 @@
+#!/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 2 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 一致)
+#
+# 對齊 .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"
+
+# 只看 Edit / Write tool
+TOOL_NAME=$(echo "${CLAUDE_TOOL_INPUT:-}" | python3 -c "import sys,json; d=json.load(sys.stdin) if sys.stdin.isatty()==False else {}; print(d.get('tool_name',''))" 2>/dev/null || echo "")
+if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then exit 0; fi
+
+TARGET=$(echo "${CLAUDE_TOOL_INPUT:-}" | python3 -c "import sys,json; d=json.load(sys.stdin) if sys.stdin.isatty()==False else {}; print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null || echo "")
+# 只查 .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"
+if ! grep -q 'layout="primary-header"\|layout={["\047]primary-header["\047]}' "$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 不重複
+if grep -q '<SidebarHeader' "$TARGET"; then
+  VIOLATIONS+=("V2 Sidebar 內含 SidebarHeader:primary-header mode WorkspaceBrand 該在 globalHeader,sidebar 內不該重複(per spec.md「WorkspaceBrand 放置 SSOT」+ world-class GitHub/Gmail/Figma 共識)。若 sidebar header 是其他內容(非 brand),加 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
+  log_fire "check_app_shell_primary_header_consistency"
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_audit_post_report_validator.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# PostToolUse hook: validate `/design-system-audit` final report quality.
+# 2026-05-17 ship — codex Q4 verdict「post-audit stop hook / final report validator」最合理 trigger 位置。
+#
+# Triggers: 任何 Write/Edit 到 `.claude/logs/audit-report-*.json` OR `.claude/memory/project_audit_progress.md`
+#
+# 驗證:
+#   (a) NO-SAMPLE invariant — report 不含「sample top N / subset / pick top X」keyword
+#   (b) 46-dim full dispatch — report 應列 ≥ 46 dim coverage 紀錄(或明示 N/A 跳過理由)
+#   (c) audit-prompts.md coverage — 若 missing dim prompt → flag prune-chain-trigger
+#   (d) `@benchmark-unverified-blanket` count drift — vs last audit baseline
+#   (e) prune-chain-trigger signal → emit additionalContext 進下一 turn,inject_pending_self_audit 吸
+#
+# 對應 SKILL.md `/design-system-audit` Phase 4.5 機械化 trigger(2026-05-17 加)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+
+# Only fire on audit report writes
+case "$FILE_PATH" in
+  */audit-report-*.json) ;;
+  */project_audit_progress.md) ;;
+  *) exit 0 ;;
+esac
+
+case "$TOOL" in Write|Edit|MultiEdit) ;; *) exit 0 ;; esac
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+[ -f "$FILE_PATH" ] || exit 0
+
+WARNINGS=""
+TRIGGER_PRUNE=0
+
+# ─ Validator A: NO-SAMPLE ─────────────────────────────────────────────────
+if grep -qE 'sample top [0-9]+|sampled top|subset|pick top [0-9]+|top hot|sampled components' "$FILE_PATH" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ❌ [A] NO-SAMPLE violation:report 含 sample subset keyword,違反 audit-full-sweep canonical(memory/feedback_audit_full_sweep_not_sample.md)"
+fi
+
+# ─ Validator B: 46-dim coverage ───────────────────────────────────────────
+DIM_COUNT=$(grep -cE '(Dim|dim) ([1-9]|[1-4][0-9]|5[01])(\b|:)' "$FILE_PATH" 2>/dev/null || echo 0)
+DIM_COUNT=${DIM_COUNT:-0}
+if [ "$DIM_COUNT" -lt 46 ]; then
+  WARNINGS="${WARNINGS}\n  ⚠️ [B] Dim coverage:report 提到 ${DIM_COUNT} dim,< 46 期望。確認跑了 46-dim 全 dispatch 還是漏 group"
+fi
+
+# ─ Validator C: audit-prompts.md coverage ─────────────────────────────────
+AUDIT_PROMPTS="$PROJECT_DIR/.claude/skills/design-system-audit/references/audit-prompts.md"
+if [ -f "$AUDIT_PROMPTS" ]; then
+  PROMPT_DIM_COUNT=$(grep -cE '^###[[:space:]]*Dim[[:space:]]+[1-9][0-9]?(\b|:|[[:space:]])' "$AUDIT_PROMPTS" 2>/dev/null || echo 0)
+  PROMPT_DIM_COUNT=${PROMPT_DIM_COUNT:-0}
+  if [ "$PROMPT_DIM_COUNT" -lt 46 ]; then
+    WARNINGS="${WARNINGS}\n  🔴 [C] audit-prompts.md prompt coverage:${PROMPT_DIM_COUNT}/46 — 紙上 dim 無 prompt,sub-agent 跑不動。下輪 prune Phase 1 D5 candidate(canonical drift:SKILL.md 46-dim vs audit-prompts.md prompt 數差距)"
+    TRIGGER_PRUNE=1
+  fi
+fi
+
+# ─ Validator D: @benchmark-unverified-blanket count drift ─────────────────
+BENCH_DEBT=$(grep -rc '@benchmark-unverified-blanket' "$PROJECT_DIR/packages/design-system/src/" 2>/dev/null | awk -F: '{s+=$2} END{print s+0}')
+BENCH_DEBT=${BENCH_DEBT:-0}
+if [ "$BENCH_DEBT" -gt 0 ]; then
+  WARNINGS="${WARNINGS}\n  ⚠️ [D] Benchmark cite debt:${BENCH_DEBT} 處 `@benchmark-unverified-blanket` marker — 對應 prune D9(M22 cite debt)"
+  TRIGGER_PRUNE=1
+fi
+
+# ─ Validator E: prune-chain-trigger emit ──────────────────────────────────
+if [ "$TRIGGER_PRUNE" -eq 1 ] || [ -n "$WARNINGS" ]; then
+  mkdir -p "$PROJECT_DIR/.claude/logs" 2>/dev/null
+  printf '{"ts":"%s","file":"%s","trigger_prune":%d,"warnings":%s}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$FILE_PATH" \
+    "$TRIGGER_PRUNE" \
+    "$(printf '%b' "$WARNINGS" | jq -Rs .)" \
+    >> "$PROJECT_DIR/.claude/logs/audit-post-report-validator.jsonl" 2>/dev/null || true
+
+  if [ "$TRIGGER_PRUNE" -eq 1 ]; then
+    CTX=$(printf '🚨 audit post-report validator: prune-chain-trigger fire。下輪 invoke /knowledge-prune scope=full(triggers: audit-prompts coverage < 100%% / @benchmark-unverified-blanket count > 0)。\n%b' "$WARNINGS")
+    jq -n --arg ctx "$CTX" '{
+      hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+    }'
+  fi
+fi
+
+exit 0

package/ds-canonical/hooks/check_audit_sample_escape.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Audit NO-SAMPLE strict enforcement(2026-05-17 P0 user-mandated):
+#   /design-system-audit --deep dispatch sub-agent prompt 禁含 sample escape clause。
+#   違 = BLOCKER 不允 dispatch。
+#
+# 背景:audit Dim 24/25/40-43/45/46/48 sub-agent 多次 sampled 不全掃 → user 抓「你他媽是不是又再搞抽樣」。
+# 加 mechanical hook 攔截 dispatch prompt 含 sample escape keyword。
+#
+# PreToolUse(Agent)hook:讀 tool_input.prompt,grep escape keyword 命中 → exit 2 BLOCKER。
+#
+# Allow escape:dispatch prompt 加 `// @audit-sample-allow: <rationale>` 整 prompt 豁免(極罕見場景)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""')
+
+case "${TOOL:-}" in
+  Agent) ;;
+  *) exit 0 ;;
+esac
+
+# 2026-05-23 P0 升級 per user verbatim「幹你娘就叫你他媽所有稽核都要完整執行不要再抽樣,到底要講幾次?...把全部要稽核的東西都給我避免抽樣」:
+# - PreToolUse:scan tool_input.prompt(dispatch prompt)阻 escape clause
+# - PostToolUse:scan tool_response.content(sub-agent OUTPUT)阻 sub-agent 自報「I sampled / spot-check / representative」admission
+case "${EVENT:-}" in
+  PostToolUse)
+    # Sub-agent OUTPUT scan — catch post-fact admission
+    OUTPUT=$(echo "$INPUT" | jq -r '.tool_response.content // .tool_response // ""' 2>/dev/null)
+    # Only fire on audit-related agent runs(by output keyword)
+    if ! echo "$OUTPUT" | grep -qiE 'audit|Dim [0-9]+|D[0-9]+ CLEAN|DS-wide|sub-agent'; then exit 0; fi
+    PROMPT="$OUTPUT" # reuse PROMPT var for downstream grep
+    ;;
+  *)
+    # PreToolUse(default existing logic):scan dispatch prompt
+    PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // ""')
+    ;;
+esac
+
+# Allow escape(極罕見)
+if echo "$PROMPT" | grep -qE '@audit-sample-allow:'; then
+  exit 0
+fi
+
+# Only enforce on audit-related dispatch(detect by prompt keyword)
+if ! echo "$PROMPT" | grep -qE 'audit|Dim [0-9]+|DS-wide|sub-agent|sweep'; then
+  exit 0
+fi
+
+# Detect sample escape clause keyword
+# 2026-05-23 M34 fix per user verbatim「抽樣幾百次了到底要怎樣才能百分百避免」+「我要你他媽所有稽核都不能抽樣」:
+# 原 regex 太窄(narrow) 漏抓 my own dispatch keyword「Sample-based scan OK」+「cover 20+ random samples」+「too many components for exhaustive」。
+# 升 grep -i case-insensitive + 廣 pattern coverage(spec wording「NO-SAMPLE」是 broad category)。
+ESCAPE_HITS=$(echo "$PROMPT" | grep -oiE 'sample[ -]?based|sample-N|sample-only|sample evidence|sample top [0-9]+|sample[s]?[[:space:]]+(scan|OK|allowed|fine|enough|sufficient|recommended|sub|covering)|covering[[:space:]]+[0-9]+\+?[[:space:]]*sample|covers[[:space:]]+[0-9]+\+?[[:space:]]*sample|cover[[:space:]]+[0-9]+\+?[[:space:]]*(random[[:space:]]+)?sample|pick top [0-9]+|top hot|sampled[[:space:]]*(components|elements|files|Button|button|story|stories)|sample-?based|sampling[[:space:]]+(scan|approach|method)|heavy agent needed|full sweep deferred|defer.*heavy|cite.*heavy agent|exhaustive[[:space:]]+too[[:space:]]+(many|much)|too[[:space:]]+many[[:space:]]+for[[:space:]]+exhaustive|random[[:space:]]+sample|skip[[:space:]]+rest|skip[[:space:]]+remaining|spot[[:space:]]*[-]?[[:space:]]*check(ed|ing)?|spot[[:space:]]*sample|representative[[:space:]]+(sample|subset)|i[[:space:]]+sampled|only[[:space:]]+sampled|sampled[[:space:]]+only|sample[[:space:]]+sized?|sub-agent[[:space:]]+self-judg|self-judgment[[:space:]]+per[[:space:]]+Dim|AI[[:space:]]+judgment[[:space:]]+per[[:space:]]+Dim|sample-based[[:space:]]+AI[[:space:]]+judgment|sampled[[:space:]]+(Button|button|first|few|several)' | sort -u)
+
+if [ -n "$ESCAPE_HITS" ]; then
+  printf '🚨 AUDIT NO-SAMPLE ESCAPE CLAUSE BLOCKER(audit canonical 2026-05-17 user-mandated):\n' >&2
+  printf '   Dispatch prompt 含 sample escape clause:\n' >&2
+  echo "$ESCAPE_HITS" | while IFS= read -r hit; do
+    printf '   • "%s"\n' "$hit" >&2
+  done
+  printf '\n  Per CLAUDE.md `# 稽核 canonical` + design-system-audit/SKILL.md Phase 1 NO-SAMPLE invariant:\n' >&2
+  printf '  禁含「sample / top N / heavy agent needed / full sweep deferred」escape clause。\n' >&2
+  printf '  每 dim 必 DS-wide ALL components 全掃,context 不夠拆 stage 分批,**不 sample**。\n' >&2
+  printf '\n  修方向:從 prompt 移除 escape clause,改寫「拆 N-stage(每 stage 10-15 元件)所有 stages 必跑完」。\n' >&2
+  printf '  Escape(極罕見): prompt 加 // @audit-sample-allow: <rationale>\n' >&2
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_benchmark_citation.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse hook:阻止「沒 source citation 的 world-class benchmark claim」(對齊 M22)。
+#
+# Bug 史(2026-05-02):
+#   AI 在 spec.md / tsx comment 寫「對齊 Ant Design」「Material 共識」「Polaris 派」
+#   但沒附 source URL / screenshot / specific impl reference → 寫 code 時憑印象解讀,
+#   常常**錯誤**(e.g., 我寫 Ant showTime range 是 2 calendar,實證是 1 calendar)。
+#
+# 機械化規則:
+#   寫 spec / tsx 含 benchmark 關鍵詞 → 必同段含**至少一條** citation:
+#     - Inline URL(`https://...` 包含 ant-design / material / polaris / atlassian / carbon / shadcn / radix-ui domain)
+#     - GitHub issue / PR / source path(`#L42` line ref)
+#     - Screenshot reference(`snapshots/...`)
+#     - Marked `@benchmark-unverified`(顯式撤回)
+#
+# 允許 escape:
+#   檔頭加 `// @benchmark-citation-allow: <reason>` 整檔豁免(legacy,M22 hook 上線過渡期)
+#   檔頭加 `// @benchmark-unverified-blanket: <reason>` 整檔 M22 (d) 撤回(file-level unverified)
+
+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 spec.md / .tsx in design-system
+case "$FILE_PATH" in
+  */packages/design-system/src/**/*.spec.md|*/packages/design-system/src/**/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  (.tool_input.content // "") + "\n" +
+  (.tool_input.new_string // "") + "\n" +
+  ([.tool_input.edits[]? | .new_string] | join("\n"))
+' 2>/dev/null || echo "")
+
+[ -z "${NEW_CONTENT//[[:space:]]/}" ] && exit 0
+
+# File-level allowlist
+FIRST_LINES=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,5p')
+if echo "$FIRST_LINES" | grep -qE '@benchmark-citation-allow:|@benchmark-unverified-blanket:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK_FIRST=$(sed -n '1,5p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK_FIRST" | grep -qE '@benchmark-citation-allow:|@benchmark-unverified-blanket:'; then
+    exit 0
+  fi
+fi
+
+# Detect benchmark claim keywords + check inline citation in same paragraph
+# 用 perl -0777 slurp 比 awk simpler;每個含 benchmark keyword 的「段」(連續非空行)
+# 必含 citation evidence。
+VIOLATIONS=$(printf '%s' "$NEW_CONTENT" | perl -0777 -ne '
+  my $bench = qr/(Ant Design|Material(\s+X|\s+Design|\s+UI|\s+3)?|Polaris|Atlassian|Carbon|shadcn|Radix UI?|Apple HIG|Notion|Airtable|ClickUp|Figma|Linear)/;
+  my $cite = qr/(https?:\/\/(www\.)?(ant-design|material|polaris\.shopify|atlassian\.design|carbon|shadcn|ui\.shadcn|radix-ui|github|developer\.apple)|#L\d|snapshots\/|@benchmark-unverified)/;
+  # Iterate paragraphs(separated by blank lines)
+  for my $para (split /\n\s*\n/) {
+    next unless $para =~ $bench;
+    # Skip paragraphs that ARE source citations(URL line itself)
+    next if $para =~ /^\s*[\*-]?\s*https?:\/\//;
+    # Has citation? OK
+    next if $para =~ $cite;
+    # Violation:claim 但沒 cite
+    my $first_line = (split /\n/, $para)[0];
+    print "  - " . substr($first_line, 0, 80) . "...\n";
+  }
+'
+)
+
+if [ -n "$VIOLATIONS" ]; then
+  cat >&2 <<EOF
+
+┄┄┄┄ check_benchmark_citation — world-class benchmark claim 缺 source ┄┄┄┄
+
+[P1 WARN] ${FILE_PATH}
+偵測到 benchmark claim 段缺 inline citation:
+${VIOLATIONS}
+M22 canonical(2026-05-02):**寫 spec / code 含「Ant / Material / Polaris / ...」claim 必附**:
+  (a) Inline URL(domain 含 ant-design / material / polaris / atlassian / radix-ui / github 等)
+  (b) GitHub source path + line ref(\`#L42\`)
+  (c) Screenshot reference(\`snapshots/...\`)
+  (d) 顯式撤回 \`@benchmark-unverified\`
+
+歷史教訓(2026-05-02):
+  - 我 claim「Ant showTime range = 2 calendars」憑印象 → 實證是 1 calendar,白忙一場
+  - User: 「下次到底該如何完全避免你自己不斷說鬼話?」→ M22 + 本 hook
+
+整檔豁免:
+  - \`// @benchmark-citation-allow: <reason>\`(legacy 過渡期暫掛)
+  - \`// @benchmark-unverified-blanket: <reason>\`(M22 (d) file-level 撤回)
+EOF
+  # Soft warning(P1)— print to stderr, don't block(exit 1 vs exit 2)
+  exit 1
+fi
+
+exit 0

package/ds-canonical/hooks/check_canonical_propagation.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+# Canonical propagation unified hook(2026-05-08 cluster E consolidation)
+#
+# Merges 3 PreToolUse hooks(原各檔已 retire,合併入此):
+#   E.1 principles canonical(原 check_principles_canonical,P0 BLOCK new file / P1 warn existing)
+#   E.2 L3 primitive import(原 check_l3_primitive_import,P0 BLOCK)
+#   E.3 spec-impl default alignment(原 check_spec_impl_default_alignment,P1 stderr)
+#
+# Why merge:皆 canonical SSOT propagation invariant — principles structure / L3 layer 邊界 /
+# spec→impl 一致性,共用 INPUT parsing 模式。散裝是 M17 + Anthropic ≤ 15 hook 偏離。
+#
+# File scope per rule:
+#   E.1: *.principles.stories.tsx
+#   E.2: *.ts / *.tsx outside packages/design-system/src/{components,patterns,tokens,hooks}
+#   E.3: *.spec.md
+#
+# Allowlist tags:
+#   E.1: `// @principles-rationale: <reason>`
+#   E.2: 檔頭 5 行 `// @l3-import-allow: <reason>`
+#   E.3: 檔頭 5 行 `// @spec-impl-allow: <reason>`
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo 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
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  (.tool_input.content // "") + "\n" +
+  (.tool_input.new_string // "") + "\n" +
+  ([.tool_input.edits[]? | .new_string] | join("\n"))
+' 2>/dev/null || echo "")
+
+[ -z "${NEW_CONTENT//[[:space:]]/}" ] && exit 0
+
+WORST=0
+record_worst() { local lvl=$1; [ "$lvl" -gt "$WORST" ] && WORST=$lvl; }
+
+# ── E.1 principles canonical(*.principles.stories.tsx)──────────────────────
+case "$FILE_PATH" in
+  *.principles.stories.tsx)
+    if ! echo "$NEW_CONTENT" | grep -q "@principles-rationale:"; then
+      EXISTING_CONTENT=""
+      [ -f "$FILE_PATH" ] && EXISTING_CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+      FULL_CONTENT="${EXISTING_CONTENT}
+${NEW_CONTENT}"
+      STORY_EXPORTS=$(echo "$FULL_CONTENT" | grep -oE "^export const [A-Z][a-zA-Z]+" | awk '{print $3}' | sort -u)
+
+      VIOLATIONS_E1=""
+      WARNINGS_E1=""
+
+      DEPRECATED_NAMES=("Forbidden" "Donts" "Pitfalls" "Prohibitions" "NonGoals" "VisualDonts")
+      for deprecated in "${DEPRECATED_NAMES[@]}"; do
+        if echo "$STORY_EXPORTS" | grep -qE "^${deprecated}"; then
+          if [ -z "$EXISTING_CONTENT" ]; then
+            VIOLATIONS_E1="${VIOLATIONS_E1}\n  • [P0] Deprecated naming '${deprecated}*' — rename to 'WhenNotToUse'"
+          else
+            WARNINGS_E1="${WARNINGS_E1}\n  • [P1] Deprecated '${deprecated}*' — migrate to 'WhenNotToUse'"
+          fi
+        fi
+      done
+
+      HAS_WHEN_TO_USE=0; HAS_WHEN_NOT_TO_USE=0; HAS_VS_RULE=0; HAS_CONTENT_GUIDELINES=0; HAS_USAGE_GUIDANCE=0
+      echo "$STORY_EXPORTS" | grep -qE "^WhenToUse$" && HAS_WHEN_TO_USE=1
+      echo "$STORY_EXPORTS" | grep -qE "^WhenNotToUse$" && HAS_WHEN_NOT_TO_USE=1
+      echo "$STORY_EXPORTS" | grep -qE "^Vs[A-Z].*Rule$|^.+Vs.+Rule$" && HAS_VS_RULE=1
+      echo "$STORY_EXPORTS" | grep -qE "^ContentGuidelines$" && HAS_CONTENT_GUIDELINES=1
+      echo "$STORY_EXPORTS" | grep -qE "^(UsageScenarioRule|WhatItIs)$" && HAS_WHEN_TO_USE=1
+      for deprecated in "${DEPRECATED_NAMES[@]}"; do
+        echo "$STORY_EXPORTS" | grep -qE "^${deprecated}" && HAS_WHEN_NOT_TO_USE=1
+      done
+      echo "$STORY_EXPORTS" | grep -qE "^UsageGuidance$" && HAS_USAGE_GUIDANCE=1
+
+      CORE_COUNT=$((HAS_WHEN_TO_USE + HAS_WHEN_NOT_TO_USE + HAS_VS_RULE + HAS_CONTENT_GUIDELINES))
+      [ "$HAS_USAGE_GUIDANCE" -eq 1 ] && CORE_COUNT=2
+
+      if [ "$CORE_COUNT" -lt 2 ]; then
+        if [ -z "$EXISTING_CONTENT" ]; then
+          VIOLATIONS_E1="${VIOLATIONS_E1}\n  • [P0] Universal core ≥ 2 required: have ${CORE_COUNT} of {WhenToUse, WhenNotToUse, Vs*Rule, ContentGuidelines}"
+        else
+          WARNINGS_E1="${WARNINGS_E1}\n  • [P1] Universal core ${CORE_COUNT}/2 — add WhenToUse / WhenNotToUse / Vs*Rule / ContentGuidelines"
+        fi
+      fi
+
+      if [ -n "$VIOLATIONS_E1" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ E.1 check_canonical_propagation — principles canonical BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+Violations:$(echo -e "$VIOLATIONS_E1")
+
+Per category-templates.md「Principles canonical」:
+  ‣ Universal core ≥ 2 of {WhenToUse, WhenNotToUse, Vs*Rule, ContentGuidelines}
+  ‣ Anti-pattern naming → WhenNotToUse(Forbidden/Donts/Pitfalls/Prohibitions/NonGoals/VisualDonts deprecated)
+  ‣ 例外:加 \`// @principles-rationale: <reason>\`
+
+EOF
+        record_worst 2
+      fi
+      [ -n "$WARNINGS_E1" ] && echo "⚠️  E.1 principles canonical warning:$(echo -e "$WARNINGS_E1")" >&2
+    fi
+    ;;
+esac
+
+# ── E.2 L3 primitive import(*.ts/.tsx outside DS internal)───────────────────
+case "$FILE_PATH" in
+  *.ts|*.tsx)
+    case "$FILE_PATH" in
+      */packages/design-system/src/components/*|*/packages/design-system/src/patterns/*|*/packages/design-system/src/tokens/*|*/packages/design-system/src/hooks/*) ;; # DS internal skip
+      *)
+        # File-level allowlist:檔頭 5 行
+        ALLOW_E2=0
+        FIRST_LINES_E2=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,5p')
+        echo "$FIRST_LINES_E2" | grep -qE '//[[:space:]]*@l3-import-allow:' && ALLOW_E2=1
+        if [ -f "$FILE_PATH" ] && [ "$ALLOW_E2" = "0" ]; then
+          ON_DISK_FIRST=$(sed -n '1,5p' "$FILE_PATH" 2>/dev/null || true)
+          echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@l3-import-allow:' && ALLOW_E2=1
+        fi
+        if [ "$ALLOW_E2" = "0" ]; then
+          L3_IMPORT_PATTERN='from\s+["'"'"'][^"'"'"']*patterns/element-anatomy/item-anatomy["'"'"']'
+          if printf '%s\n' "$NEW_CONTENT" | grep -qE "$L3_IMPORT_PATTERN"; then
+            MATCHED_LINE=$(printf '%s\n' "$NEW_CONTENT" | grep -nE "$L3_IMPORT_PATTERN" | head -1)
+            cat >&2 <<EOF
+
+┄┄┄ E.2 check_canonical_propagation — L3 primitive import BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+  > ${MATCHED_LINE}
+
+L3 internal primitives(\`ItemInlineAction\` / \`ItemContent\` / \`RowSizeProvider\` 等)
+是給 DS 作者建 host 元件用的 building block,不是 app code 用的。
+
+修法(擇一):
+  (a) host config API(90%):<Input endAction={...} /> / <TreeItem inlineActions={...} />
+  (b) host slot escape(10%):<Input endSlot={<Custom/>} />
+  (c) 獨立 button(非 inline):<Button iconOnly variant="text" />
+
+刻意 import L3:檔首 5 行加 \`// @l3-import-allow: <reason + spec.md anchor>\`
+
+EOF
+            record_worst 2
+          fi
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+# ── E.3 spec-impl default alignment(*.spec.md)──────────────────────────────
+case "$FILE_PATH" in
+  *.spec.md)
+    FIRST_LINES_E3=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,5p')
+    if ! echo "$FIRST_LINES_E3" | grep -q '@spec-impl-allow'; then
+      DEFAULT_LINES=$(printf '%s' "$NEW_CONTENT" | grep -nE '預設|預値|default[ \t]*[=:]|`default`|預設值' | head -3)
+      if [ -n "$DEFAULT_LINES" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ E.3 check_canonical_propagation — spec-impl default alignment WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+偵測「default」/「預設」keyword:
+${DEFAULT_LINES}
+
+⚠️  spec 寫預設值 → 必對應 impl 驗證一致(M14 + 真實案例:SelectMenu spec 寫
+   「width 預設 = trigger-width」但 PopoverContent w-72 hardcode override,canonical 失效)
+
+Self-check:
+  - 找對應 implementation file
+  - grep 該 default value 是否 hardcode / 是否被外層 override
+  - 不一致 → 修 impl OR 修 spec 對齊
+  - 一致 → impl 加 inline comment 「Default per spec L<N>」回扣
+
+整檔豁免:檔頭 5 行 \`// @spec-impl-allow: <reason>\`(soft warn 不擋 commit)
+
+EOF
+      fi
+    fi
+    ;;
+esac
+
+exit $WORST