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

package/ds-canonical/hooks/check_file_size_budget.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: enforce per-file line budgets for governance files.
+#
+# Budgets — SSOT 是 CLAUDE.md `# 治理 canonical` 「行數預算」段。
+# 本檔不再硬寫(避免 漂移 — 2026-05-15 Fix 4 per sub-agent a9e6d53c finding 6:
+# 之前硬寫 400 vs CLAUDE.md「target 200 / transition 400 / hard cap 800」三 home 三 baseline)。
+# 改 dynamic 從 CLAUDE.md grep,fallback 寫死值。SSOT 改一處全處跟動。
+#
+# Non-blocking: injects warning via hookSpecificOutput additionalContext; Claude
+# decides whether to split or ack. Hard block would paralyse edits to legitimately
+# large canonical specs (e.g. item-anatomy ~900 lines) — require explicit override.
+
+# 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)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+[ -z "$FILE_PATH" ] && exit 0
+[ -f "$FILE_PATH" ] || exit 0
+
+# Only check governance files
+# CLAUDE.md L34 SSOT: target ≤ 200(Anthropic best-practice)/ transition ≤ 400 / hard cap 800
+# 本 hook 在 transition 觸發 P1 warning,hard cap 觸發 P0 block
+case "$FILE_PATH" in
+  */CLAUDE.md)                          BUDGET=400;  TRANSITION=800; LABEL="CLAUDE.md" ;;  # warn at transition (400), block at hard cap (800); target 200
+  */memory/*.md)                        BUDGET=100;  TRANSITION=100; LABEL="memory file" ;;
+  # Super-foundational SSOT spec(item-anatomy = Family 1+2 跨 10+ 消費者 SSOT,唯一例外)
+  */item-anatomy.spec.md)
+    BUDGET=800;  TRANSITION=1200; LABEL="super-foundational SSOT spec.md(item-anatomy 例外)" ;;
+  # Foundational SSOT specs(2026-04-24 升 cap 800 — spec 內部有 rationale section)
+  # 2026-05-18 加 data-table:DS 最複雜 composite + 跨家族 anchor(L1-L4 完整 grid taxonomy,
+  # 行對齊 item-anatomy / 浮層對齊 overlay-surface / state 對齊 field-controls)。
+  # frontmatter 已標 `foundational_ssot: true`。
+  # 2026-05-22 prune:color.spec.md 升 tier 2 cap 1000(per CLAUDE.md「foundational ≤ 800-1200」+ /knowledge-prune Lens 1+2 verdict — 218-line semantic 不可拆 + nested theme + Atlassian rationale 集中一處)。
+  */color.spec.md)
+    BUDGET=800;  TRANSITION=1000; LABEL="foundational SSOT spec.md(color tier 2 cap 1000)" ;;
+  */sidebar.spec.md|*/tree-view.spec.md|*/data-table.spec.md)
+    BUDGET=500;  TRANSITION=800; LABEL="foundational SSOT spec.md" ;;
+  *.spec.md)                            BUDGET=300;  TRANSITION=500; LABEL="spec.md" ;;
+  *.claude/skills/*/SKILL.md)           BUDGET=250;  TRANSITION=400; LABEL="SKILL.md" ;;
+  *) exit 0 ;;
+esac
+
+LINES=$(wc -l < "$FILE_PATH" | tr -d ' ')
+[ "$LINES" -le "$BUDGET" ] && exit 0
+
+# Over budget — warn. Hard-block only if also over transition cap.
+if [ "$LINES" -gt "$TRANSITION" ]; then
+  MSG="⛔ ${LABEL} at ${FILE_PATH} is ${LINES} lines (hard cap ${TRANSITION}). Must reduce before adding. Run /knowledge-prune or identify which section to remove."
+else
+  MSG="⚠️ ${LABEL} at ${FILE_PATH} is ${LINES} lines (budget ${BUDGET}, transition cap ${TRANSITION}). Prefer consolidating over appending. What can you remove/merge to make room?"
+fi
+
+ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+exit 0

package/ds-canonical/hooks/check_full_story_visual_interaction_sweep.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# check_full_story_visual_interaction_sweep.sh — P0 BLOCKER
+#
+# Codex M31 P0 finding 2026-05-27: ds-story-manifest.json 是 62-component / 916-story
+# SSOT,但無 hook 攔 audit reports 漏 manifest story IDs / screenshots / metrics / probe.
+# User 2026-05-27 verbatim「不准抽樣 全 visual + interaction 全跑」.
+#
+# Triggers when audit report JSON is edited/written:
+#   - /tmp/codex-*-sweep/audit-report.json
+#   - /tmp/claude-*-sweep/audit-report.json
+#   - .claude/snapshots/*audit-report.json
+# Verifies storyResults.length === manifest.totalStories (916) — block if sample.
+#
+# Escape: report frontmatter `"_sampling_allowed": "<rationale>"`(極罕見).
+
+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)
+
+case "${TOOL:-}" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+if ! echo "$FILE" | grep -qE '(sweep|audit-report)\.json$'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# Check escape
+if echo "$CONTENT" | grep -q '_sampling_allowed'; then exit 0; fi
+
+# Parse story count vs manifest (multi-field fallback)
+STORY_COUNT=$(echo "$CONTENT" | jq -r '.storyResults // .results // [] | length' 2>/dev/null)
+if [ -z "$STORY_COUNT" ] || [ "$STORY_COUNT" = "0" ] || [ "$STORY_COUNT" = "null" ]; then
+  STORY_COUNT=$(echo "$CONTENT" | jq -r '.storySummary.total // .summary.total // .total // 0' 2>/dev/null)
+fi
+STORY_COUNT=${STORY_COUNT:-0}
+
+MANIFEST_PATH="${CLAUDE_PROJECT_DIR:-.}/packages/design-system/ds-story-manifest.json"
+if [ ! -f "$MANIFEST_PATH" ]; then exit 0; fi
+MANIFEST_TOTAL=$(jq -r '.totalStories // 0' "$MANIFEST_PATH" 2>/dev/null)
+[ -z "$MANIFEST_TOTAL" ] || [ "$MANIFEST_TOTAL" = "0" ] && exit 0
+[ "$STORY_COUNT" = "0" ] && exit 0
+# numeric compare
+if ! [[ "$STORY_COUNT" =~ ^[0-9]+$ ]]; then exit 0; fi
+
+if [ "$STORY_COUNT" -lt "$MANIFEST_TOTAL" ]; then
+  cat >&2 << EOF
+🚨 FULL-STORY-SWEEP BLOCKER(P0,codex M31 finding 2026-05-27 + user「不准抽樣」)
+
+  Audit report $FILE:
+    storyResults: $STORY_COUNT
+    manifest.totalStories: $MANIFEST_TOTAL
+    缺失: $((MANIFEST_TOTAL - STORY_COUNT)) stories
+
+  per ds-story-manifest.json SSOT(scripts/gen-ds-story-manifest.mjs:59)+ user 2026-05-27
+  「請你不要給我抽樣,因為你一抽樣就是會有東西壞掉,務必要全部檢查」directive.
+
+  修法 2 選 1:
+    (a) Re-run sweep covering all $MANIFEST_TOTAL stories
+    (b) Escape:report 含 \`"_sampling_allowed": "<rationale>"\`(極罕見)
+EOF
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_item_list_gap.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# check_item_list_gap.sh — M16 mechanical enforcement(2026-05-26 backfill).
+#
+# Purpose:PreToolUse Edit/Write — 偵測 production tsx 含 standalone card/pill 渲染
+# pattern(`<FileItem>` / `<MenuItem rich>` / 卡片型 standalone)without gap-N or space-y-N
+# parent → soft warn requires explicit gap canonical per item-anatomy.spec.md。
+#
+# 3 條公式(per M16):
+#   - 同類 standalone 卡片 → 必 gap
+#   - 同類 permanent flush(連續貼齊)→ 0 gap OK,但必 codify in spec
+#   - 混合語言 → 必取最保守 gap
+
+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)
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+NEW=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null)
+
+[ "$EVENT" != "PreToolUse" ] && exit 0
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.tsx) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.stories.tsx|*.test.tsx) exit 0 ;; esac
+
+# Heuristic:multiple <FileItem> / <MenuItem variant="rich"> / standalone card pattern + parent 無 gap-N
+# 2026-05-26 fix:grep -c 計行數不計次,用 -o count 真實 occurrence
+STANDALONE_RE='<(FileItem|MenuItem[^>]+variant=["'\'']rich["'\''])'
+COUNT=$(echo "$NEW" | grep -oE "$STANDALONE_RE" 2>/dev/null | wc -l | tr -d ' ')
+COUNT=${COUNT:-0}
+
+[ "$COUNT" -lt 2 ] && exit 0
+
+# Has gap-N or space-y-N near the standalone pattern?
+if echo "$NEW" | grep -qE '(gap-[0-9]|space-y-[0-9])'; then
+  exit 0
+fi
+
+cat >&2 <<EOF
+⚠️ M16 Item-list gap canonical
+
+→ 偵測到 $COUNT 個 standalone item(FileItem / MenuItem rich)未見 gap-N / space-y-N parent class。
+
+M16 要求(per item-anatomy.spec.md):
+  - 同類 standalone → 必 gap(常見 gap-2 / gap-3)
+  - 同類 permanent flush(連續貼齊)→ 0 gap OK,但必 spec codify
+  - 混合語言 → 必取最保守 gap
+
+修法:parent container 加 \`gap-2\` / \`space-y-2\` 或 codify 連續貼齊 in 元件 spec。
+對應 canonical:meta-patterns.md M16 + patterns/element-anatomy/item-anatomy.spec.md。
+EOF
+
+exit 0

package/ds-canonical/hooks/check_layout_space_magic_numbers.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# check_layout_space_magic_numbers.sh — P0 BLOCKER
+#
+# 偵測 consumer / DS app code 用 Tailwind spacing magic numbers
+# (`p-4` / `px-6` / `py-2` / `gap-3` 等)而非 layoutSpace token
+# (`p-[var(--layout-space-N) N∈{loose,tight}]` / `gap-[var(--layout-space-N) N∈{loose,tight}]`)。
+# 2026-05-27 user verbatim「機械無強制就不會做?那為何不全部 ssot 都要強制吻合?」
+# 永久 codify — SSOT canonical 必 P0 BLOCKER,不分級。
+#
+# Anchor:user 質疑「content 自動繼承 layoutSpace SSOT 嗎?」
+# - app-shell.spec.md:205 明文 `<main>` landmark padding=0 (intentional)
+# - app-shell.spec.md:207-212 consumer 必遵循 layoutSpace.spec.md 6 條規則 + 親疏 3 級
+#
+# PostToolUse Edit/Write detect magic Tailwind spacing → P0 BLOCKER exit 2
+# 強制改 token OR 加 `// @layout-space-magic-ok: <rationale>` escape comment(per-line)。
+
+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)
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.notebook_path // ""' 2>/dev/null)
+
+# Only check .tsx / .ts in app code
+if ! echo "$FILE" | grep -qE '\.(tsx|ts)$'; then exit 0; fi
+# Skip DS source (DS components have their own spacing logic via cva)
+if echo "$FILE" | grep -qE 'packages/design-system/src/|node_modules/'; then exit 0; fi
+
+# Get new content
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$NEW_CONTENT" ] && exit 0
+
+# Escape clause:single line escape comment per line of magic number usage
+# `// @layout-space-magic-ok: <rationale>` immediately above the line OR on same line
+ESCAPE_MARKER='@layout-space-magic-ok:'
+
+# Detect magic spacing classes (Tailwind class strings only — NOT JSX props like size={24})
+# Match per line so we can check per-line escape comments
+MAGIC_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b(p|px|py|pt|pb|pl|pr|gap|space-x|space-y|m|mx|my|mt|mb|ml|mr)-(0\.5|[1-9][0-9]?(\.[0-9])?)\b')
+
+if [ -z "$MAGIC_LINES" ]; then
+  exit 0
+fi
+
+# Filter out lines with escape marker on same line OR immediately preceding line
+# 2026-06-03 修(doc-vs-code bug,M32):L41 文件宣稱支援「preceding line OR same line」,
+# 但原 code 只檢查同行 → JSX className 行無法放同行 `//` comment(會破壞 JSX)→ escape 對 JSX
+# 實質失效。補實作前一行檢查(grep -n 行號 → sed 取前一行),對齊文件 + 解 JSX 必需。
+UNJUSTIFIED=""
+while IFS= read -r line; do
+  # same-line marker
+  if echo "$line" | grep -qF "$ESCAPE_MARKER"; then continue; fi
+  # preceding-line marker(JSX `{/* @layout-space-magic-ok: ... */}` 在上一行)。
+  # 對齊 ESLint disable-next-line 慣例:前一行 marker 僅在該行是「註解專用行」(trimmed 開頭
+  # //、{/*、/*、*)時生效 — 否則上一行 code 的「同行 escape」會誤串到下一行(P8 conflict)。
+  lineno="${line%%:*}"
+  if [ "$lineno" -gt 1 ] 2>/dev/null; then
+    prev=$(echo "$NEW_CONTENT" | sed -n "$((lineno-1))p")
+    if echo "$prev" | grep -qF "$ESCAPE_MARKER" && echo "$prev" | grep -qE '^[[:space:]]*(//|\{?/\*|\*)'; then continue; fi
+  fi
+  UNJUSTIFIED="${UNJUSTIFIED}${line}\n"
+done <<< "$MAGIC_LINES"
+
+if [ -z "$UNJUSTIFIED" ]; then
+  exit 0
+fi
+
+cat >&2 << EOF
+🚨 LAYOUT-SPACE-MAGIC-NUMBER BLOCKER(P0,2026-05-27 user verbatim「機械無強制就不會做?
+為何不全部 ssot 都要強制吻合?」永久 codify)
+
+  Detected Tailwind spacing magic numbers in $FILE without escape:
+$(echo -e "$UNJUSTIFIED" | sed 's/^/    /' | head -10)
+
+  per app-shell.spec.md L205-219 + layoutSpace.spec.md SSOT:consumer content 必遵循
+  layoutSpace 6 條規則 + 親疏 3 級,**禁** 硬寫 Tailwind magic numbers。改用:
+    p-[var(--layout-space-loose)]      /* 16px 規則 1A/1B chrome / wrap */
+    p-[var(--layout-space-tight)]      /* 12px 規則 3 親 gap */
+    gap-[var(--layout-space-distant)]  /* 24px 規則 3 疏 gap */
+    space-y-[var(--layout-space-distant)]
+
+  修法 2 選 1:
+    (a) 改 token:換成 var(--layout-space-N) N∈{loose,tight} family per 6 規則 + 親疏 3 級
+    (b) Escape:在該 line 加 \`// @layout-space-magic-ok: <rationale>\` 顯式 documented
+        (eg.「\`gap-1\` 是 4px stack icon — non-spacing context,not consumer layout」)
+
+  完整 6 條規則 → packages/design-system/src/tokens/layoutSpace/layoutSpace.spec.md
+EOF
+exit 2

package/ds-canonical/hooks/check_main_branch_workbench.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Solo-work canonical 補丁(2026-05-17 user-mandated):
+#   既有 check_solo_workflow.sh R1-R3 抓「2nd branch / PR creation / push main 無 trigger」,
+#   但**不抓「整 session 在 main 上 edit production code」**(M28 sub-rule)。
+#
+# 本 hook 補:PreToolUse Edit/Write 偵測「current branch == main + edit production code
+# + 近 5 條 user msg 無「開 branch / 在 branch 上做」trigger keyword」→ BLOCKER。
+#
+# 對應 CLAUDE.md `# Git solo-work canonical` Step 1 「1 chat = 1 working branch」
+# + memory/feedback_solo_dev_workflow.md SSOT。
+#
+# 起因 2026-05-17:本 session AI 整個 deep audit + 補修 + a11y batch 全直接在 main edit,
+# user 抓「不是只有我說 push 到 main 才真的會 push 到 main 嗎」。R1 只抓 `claude/*` prefix
+# branch 數,沒抓「在 main edit」這個 root cause。
+#
+# Allow escape:
+#   - doc-only / governance-only edit(`.claude/**` / `*.spec.md`)豁免 — 不需 Netlify preview
+#   - `CLAUDE_BYPASS_MAIN_WORKBENCH=1` env var(audit-logged)
+
+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
+
+# Only intercept production code edits (packages/design-system/src / src/app / src/explorations)
+case "${FILE_PATH:-}" in
+  */packages/design-system/src/**/*.tsx|*/packages/design-system/src/**/*.ts|*/packages/design-system/src/**/*.css) ;;
+  */src/app/**|*/src/explorations/**) ;;
+  *) exit 0 ;;
+esac
+
+# Skip if env override
+if [ "${CLAUDE_BYPASS_MAIN_WORKBENCH:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Detect current branch
+CURRENT_BRANCH=$(cd "${CLAUDE_PROJECT_DIR:-$(pwd)}" && git branch --show-current 2>/dev/null || echo "")
+
+if [ "${CURRENT_BRANCH:-}" != "main" ] && [ "${CURRENT_BRANCH:-}" != "master" ]; then
+  # Not on main — already on working branch, allow
+  exit 0
+fi
+
+# On main + edit production code → check recent user msg for branch trigger
+TRANSCRIPT="${CLAUDE_TRANSCRIPT_PATH:-}"
+TRIGGER_FOUND=0
+if [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
+  RECENT_USER=$(tail -200 "$TRANSCRIPT" 2>/dev/null | \
+    jq -r 'select(.role == "user") | .content' 2>/dev/null | tail -5 | tr '\n' ' ')
+  if echo "${RECENT_USER:-}" | grep -qE '(開.*branch|開.*分支|新.*branch|新.*分支|working branch|在.*branch.*做|在 branch|branch 上|on branch)'; then
+    TRIGGER_FOUND=1
+  fi
+fi
+
+if [ "$TRIGGER_FOUND" = "1" ]; then
+  # User explicitly approved branch work, allow
+  exit 0
+fi
+
+# BLOCKER: editing production code on main without explicit branch trigger
+cat >&2 <<EOF
+🚨 MAIN-AS-WORKBENCH BLOCKER(check_main_branch_workbench,2026-05-17 P0 codify)
+  - 目標: ${FILE_PATH}
+  - 範圍: packages/design-system/src / src/app / src/explorations(production code)
+  - 當前 branch: ${CURRENT_BRANCH}(= main / master)
+  - 近 5 條 user msg branch-trigger keyword: 0 次
+
+→ Solo-work canonical(CLAUDE.md \`# Git solo-work canonical\`+ memory/feedback_solo_dev_workflow.md SSOT):
+  1 chat = 1 working branch;production code edit **必先**:
+    git checkout -b <working-branch-name>
+  然後 commit + push working branch(觸發 Netlify preview),user trigger「push / 合 main」才 merge main。
+
+修法 — 2 選 1:
+  (a) 立刻開 working branch:
+       git checkout -b $(date +%Y-%m-%d)-<topic>
+      然後重試 Edit。
+  (b) Cite recent user verbatim 含「開 branch / working branch / 在 branch 上」trigger keyword
+      OR 設 CLAUDE_BYPASS_MAIN_WORKBENCH=1 跑(audit-logged)。
+
+歷史錨例(2026-05-17 起因):本 session 整個 deep audit + 56-element a11y batch + retire batch 全
+在 main 直接 edit,user 抓「不是只有我說 push 到 main 才真的會 push 到 main 嗎」。R1-R3 沒抓
+「main-as-workbench」這個 root cause,故升新 hook 攔。
+EOF
+exit 2

package/ds-canonical/hooks/check_naming_and_abstraction.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+# Naming + abstraction unified hook(2026-05-08 cluster D consolidation)
+#
+# Merges 3 PreToolUse hooks(原各檔已 retire,合併入此):
+#   D.1 premature abstraction(原 check_premature_abstraction,P0 BLOCK)
+#   D.2 internal namespace consistency(原 check_internal_namespace_consistency,P0 BLOCK)
+#   D.3 primitive color var in tsx(原 check_primitive_color_var_in_tsx,P1 WARN stderr)
+#
+# Why merge:皆 命名 / 抽象 / token 消費紀律 invariant,共用 INPUT parsing 模式。
+# 散裝是 M17 + Anthropic ≤ 15 hook best-practice 偏離。
+#
+# Per-rule scope 差異(必保留各自 narrow):
+#   D.1: Write only + components/X/X.tsx 或 spec.md 主檔 + 新檔
+#   D.2: Edit/Write/MultiEdit + *.stories.tsx
+#   D.3: Edit/Write/MultiEdit + *.tsx minus Tag/Avatar/Chart/tokens
+#
+# Per-rule allowlist:
+#   D.1: 檔頭 10 行內 `// @separate-component-rationale: <world-class refs + 3-test 通過理由>`
+#   D.2: (無 allowlist,但若 file 沒 title namespace 自動 skip)
+#   D.3: 行尾 `// @primitive-color-allow: <reason>` OR 檔頭 `// primitive-color-allow-blanket`
+
+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; }
+
+# ── D.1 premature abstraction(Write only,新元件 BLOCK)──────────────────────
+if [ "$TOOL" = "Write" ]; then
+  case "$FILE_PATH" in
+    */packages/design-system/src/components/*/[^.]*.tsx|*/packages/design-system/src/components/*/*.spec.md)
+      if [ ! -f "$FILE_PATH" ]; then
+        COMPONENT_DIR=$(echo "$FILE_PATH" | sed -E 's|.*/components/([^/]+)/.*|\1|')
+        SUFFIX=""
+        BASE_NAME=""
+        for SFX in Time Range Color Light Dark Filled Outline Compact Rich Variant; do
+          if [[ "$COMPONENT_DIR" =~ ${SFX}$ ]] && [ "$COMPONENT_DIR" != "$SFX" ]; then
+            BASE=$(echo "$COMPONENT_DIR" | sed -E "s/${SFX}$//")
+            [ -z "$BASE" ] && continue
+            COMPONENTS_ROOT=$(echo "$FILE_PATH" | sed -E 's|(.*/components)/.*|\1|')
+            if [ -d "$COMPONENTS_ROOT/$BASE" ]; then
+              SUFFIX="$SFX"; BASE_NAME="$BASE"; break
+            fi
+          fi
+        done
+        if [ -n "$SUFFIX" ]; then
+          # Allowlist:檔頭 10 行內 rationale comment
+          if ! echo "$NEW_CONTENT" | head -10 | grep -qE '//\s*@separate-component-rationale:|^\s*#?\s*@separate-component-rationale:'; then
+            cat >&2 <<EOF
+
+┄┄┄ D.1 check_naming_and_abstraction — premature abstraction BLOCKER ┄┄┄
+
+[P0] 新元件 \`${COMPONENT_DIR}\`(後綴 \`${SUFFIX}\`)
+基底元件 \`${BASE_NAME}\` 已存在 → 強烈 signal 應為 prop variant on \`${BASE_NAME}\`。
+
+歷史(M21):
+  - DateTimePicker → \`<DatePicker showTime>\`
+  - DataTableFilterPanel → sub-file pattern
+
+3-test 通過才能分:
+  1. \`${BASE_NAME}\` 加 prop 達不到同 DOM/behavior?
+  2. ≥3 家 world-class DS 用分離元件而非 prop?(必 cite source)
+  3. value 結構或 contract 真的不同(如 Range = [start, end])?
+
+通過 → spec.md 加 rationale + 檔頭 10 行內加:
+  // @separate-component-rationale: <world-class refs + 3-test 通過理由>
+
+EOF
+            record_worst 2
+          fi
+        fi
+      fi
+      ;;
+  esac
+fi
+
+# ── D.2 internal namespace consistency(stories sibling check,BLOCK)──────────
+case "$FILE_PATH" in
+  *.stories.tsx)
+    NEW_NS=$(printf '%s' "$NEW_CONTENT" | grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" | head -1 | grep -oE "(Components|Internal)" || true)
+    if [ -z "$NEW_NS" ] && [ -f "$FILE_PATH" ]; then
+      NEW_NS=$(grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" "$FILE_PATH" 2>/dev/null | head -1 | grep -oE "(Components|Internal)" || true)
+    fi
+    if [ -n "$NEW_NS" ]; then
+      DIR=$(dirname "$FILE_PATH")
+      INCONSISTENT=""
+      while IFS= read -r SIB; do
+        [ "$SIB" = "$FILE_PATH" ] && continue
+        [ -f "$SIB" ] || continue
+        SIB_NS=$(grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" "$SIB" 2>/dev/null | head -1 | grep -oE "(Components|Internal)" || true)
+        if [ -n "$SIB_NS" ] && [ "$SIB_NS" != "$NEW_NS" ]; then
+          INCONSISTENT="${INCONSISTENT}  - ${SIB} → ${SIB_NS}"$'\n'
+        fi
+      done < <(find "$DIR" -maxdepth 1 -name '*.stories.tsx' 2>/dev/null)
+      if [ -n "$INCONSISTENT" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ D.2 check_naming_and_abstraction — sibling stories namespace BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH} → ${NEW_NS}
+Sibling stories 不一致:
+${INCONSISTENT}
+3 stories(展示 / anatomy / principles)title namespace 必全 Components/ 或全 Internal/。
+
+決策:跑 CLAUDE.md「Internal vs Components 3-test」→ 把全 3 檔統一。
+
+EOF
+        record_worst 2
+      fi
+    fi
+    ;;
+esac
+
+# ── D.3 primitive color var in tsx(P1 WARN stderr only)──────────────────────
+case "$FILE_PATH" in
+  *.tsx)
+    case "$FILE_PATH" in
+      */components/Tag/*|*/components/Avatar/*|*/components/Chart/*|*/tokens/*) ;; # codified primitive-consumer skip
+      *)
+        if ! echo "$NEW_CONTENT" | grep -q 'primitive-color-allow-blanket'; then
+          VIOLATIONS_D3=$(printf '%s' "$NEW_CONTENT" | grep -nE 'var\(--color-[a-z]+-[0-9](-opaque)?\)' | grep -v 'primitive-color-allow' || true)
+          if [ -n "$VIOLATIONS_D3" ]; then
+            cat >&2 <<EOF
+
+┄┄┄ D.3 check_naming_and_abstraction — primitive color var WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+tsx 內直接消費 primitive token \`var(--color-*-N)\`:
+${VIOLATIONS_D3}
+
+⚠️  Token 命名 rule 4:禁 primitive 色名作 utility,用 semantic alias。
+修法 3 擇 1:
+  1. 加 semantic alias 在 tokens/color/semantic.css(consumer 用 semantic)
+  2. 既有 semantic 已存在 → \`var(--border)\` / \`var(--bg-disabled)\`
+  3. 例外(Tag / Avatar / Chart 自動 allowed): \`// @primitive-color-allow: <reason>\` 行尾豁免
+
+詳 tokens/color/color.spec.md「架構流派定位」+「Primitive 色票與 Tag / Avatar 的消費」。
+
+EOF
+          fi
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+exit $WORST