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

package/ds-canonical/hooks/retired/check_spec_iteration_tag.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# PostToolUse hook: when editing a *.spec.md, detect iteration residue tags that
+# indicate incomplete consolidation — 「2026-XX-XX 第 N 次 refine」, v2/v3 markers,
+# date-tagged canonical headings, or「final」labels stacking up.
+#
+# Why: canonical specs iterate multiple times during a session. Each iteration
+# leaves tag residue (「第 3 次 refine」/「v2」/「2026-04-22 final」) that accumulates
+# and muddies the spec. Clean canonical should read as **the** answer, not a
+# history log. CLAUDE.md Meta-Pattern M8 pairs with this: benchmark before
+# writing to reduce iteration count.
+#
+# Action: warn (exit 0, not block) — user / AI decides whether consolidation is
+# needed. If genuinely final, the tag can be kept; if residue, clean it.
+#
+# Trigger: PostToolUse on Edit/Write/MultiEdit where file_path ends in `.spec.md`.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+
+case "$FILE_PATH" in
+  *.spec.md) ;;
+  *) exit 0 ;;
+esac
+
+[ -f "$FILE_PATH" ] || exit 0
+
+# Detect iteration residue patterns. Each pattern emits a line if matched.
+RESIDUE=""
+
+# Pattern 1: 「第 N 次 refine」or「refine 第 N」
+if grep -qE "第[[:space:]]*[0-9]+[[:space:]]*次[[:space:]]*(refine|修訂|revision)" "$FILE_PATH" 2>/dev/null; then
+  COUNT=$(grep -cE --no-messages "第[[:space:]]*[0-9]+[[:space:]]*次[[:space:]]*(refine|修訂|revision)" "$FILE_PATH" || echo 0)
+  RESIDUE="${RESIDUE}  • 「第 N 次 refine」tag × ${COUNT}\n"
+fi
+
+# Pattern 2: 「v2」/「v3」version markers in headings or body
+if grep -qE "\b[vV][0-9]+\b.*(canonical|final|rule|規則|預設)" "$FILE_PATH" 2>/dev/null; then
+  COUNT=$(grep -cE --no-messages "\b[vV][0-9]+\b.*(canonical|final|rule|規則|預設)" "$FILE_PATH" || echo 0)
+  RESIDUE="${RESIDUE}  • 「v2/v3」version marker × ${COUNT}\n"
+fi
+
+# Pattern 3: Date-tagged canonical headings (「2026-04-22 final canonical」)
+if grep -qE "20[0-9]{2}-[0-9]{2}-[0-9]{2}.*(final|canonical|revision|refine|revised|重訂|新增)" "$FILE_PATH" 2>/dev/null; then
+  COUNT=$(grep -cE --no-messages "20[0-9]{2}-[0-9]{2}-[0-9]{2}.*(final|canonical|revision|refine|revised|重訂|新增)" "$FILE_PATH" || echo 0)
+  RESIDUE="${RESIDUE}  • Date-tagged canonical heading × ${COUNT}\n"
+fi
+
+# Pattern 4: Stacked 「final」labels (more than one 「final」 is suspicious)
+FINAL_COUNT=$(grep -cE --no-messages "\b(final|最終|定案)\b" "$FILE_PATH" 2>/dev/null | head -1)
+FINAL_COUNT="${FINAL_COUNT:-0}"
+if [ "$FINAL_COUNT" -gt 2 ] 2>/dev/null; then
+  RESIDUE="${RESIDUE}  • 「final/最終」label × ${FINAL_COUNT}(>2 suspicious — 可能 iterate 殘留)\n"
+fi
+
+# Pattern 5: 「(舊) / (新) / (deprecated) 」 label pairs without cleanup
+if grep -qE "(舊|legacy|deprecated|舊版)" "$FILE_PATH" 2>/dev/null; then
+  COUNT=$(grep -cE --no-messages "(舊|legacy|deprecated|舊版)" "$FILE_PATH" || echo 0)
+  RESIDUE="${RESIDUE}  • 「舊/legacy/deprecated」label × ${COUNT}(考慮 consolidate)\n"
+fi
+
+# No residue? exit quietly.
+if [ -z "$RESIDUE" ]; then
+  exit 0
+fi
+
+cat <<EOF
+⚠️  Spec iteration residue — ${FILE_PATH}
+
+發現 spec.md 有 iterate 疊代殘留標記:
+$(printf "%b" "$RESIDUE")
+Suggestion:
+  1. 若 canonical 已穩定 → clean 掉 tag(「第 N 次 refine」/「v2」/ date-tagged
+     / 多個「final」/「舊 vs 新」對比)讓 spec 讀起來是**這個就是答案**,
+     而不是 history log
+  2. 若仍在 iterate → 先完成 consolidate 再 commit
+
+對齊 CLAUDE.md Meta-Pattern M8(訂 canonical 前先 world-class benchmark,
+降低 iterate 次數)。
+
+(warning only, no block)
+EOF
+
+exit 0

package/ds-canonical/hooks/retired/check_ssot_consultation.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# check_ssot_consultation.sh
+#
+# Purpose: When writing a NEW .tsx file to packages/design-system/src/components/ or
+# src/explorations/, warn if the file lacks the canonical SSOT Consultation
+# comment block. This enforces CLAUDE.md `# SSOT 消費 canonical` — the
+# mechanical guardrail for Mindset #2 ("不憑直覺發明 / 優先消費既有").
+#
+# Input: $CLAUDE_TOOL_INPUT contains JSON with file_path + content for Write tool.
+# Output: stderr warning if missing; exit 0 (non-blocking by design — AI decides
+# whether to re-edit and add the block).
+
+# 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
+
+# Read stdin JSON payload (Claude Code hook input)
+INPUT=$(cat)
+
+# Only fire on Write tool, not Edit (Edit implies existing file, checklist should already be there)
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys, json; d = json.load(sys.stdin); print(d.get('tool_name', ''))" 2>/dev/null || echo "")
+if [[ "$TOOL_NAME" != "Write" ]]; then
+  exit 0
+fi
+
+# Extract file_path + content
+FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; d = json.load(sys.stdin); print(d.get('tool_input', {}).get('file_path', ''))" 2>/dev/null || echo "")
+CONTENT=$(echo "$INPUT" | python3 -c "import sys, json; d = json.load(sys.stdin); print(d.get('tool_input', {}).get('content', ''))" 2>/dev/null || echo "")
+
+# Only .tsx files in design-system components or explorations
+case "$FILE_PATH" in
+  */packages/design-system/src/components/*/*.tsx) ;;
+  */src/explorations/*/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+# Skip .stories.tsx, .anatomy.stories.tsx, .principles.stories.tsx (stories have own anatomy checks)
+case "$FILE_PATH" in
+  *.stories.tsx) exit 0 ;;
+  *.test.tsx) exit 0 ;;
+esac
+
+# Check if content contains the SSOT Consultation marker.
+# Canonical markers (any of):
+#   - `── 消費的 SSOT ──`  (zh canonical block)
+#   - `── 實作基礎 ──`      (loose form, existing elements in code)
+#   - `## Consumes SSOT`   (future English form)
+if echo "$CONTENT" | grep -qE "(消費的 SSOT|實作基礎|Consumes SSOT)"; then
+  exit 0
+fi
+
+# Missing — emit warning to stderr (non-blocking)
+cat >&2 <<EOF
+⚠️  SSOT Consultation 檢查:新 tsx 檔缺少消費宣告
+
+路徑: $FILE_PATH
+
+CLAUDE.md \`# SSOT 消費 canonical\` 要求新元件 / 新 feature 的 tsx 開頭必含
+消費宣告 comment block。這是 Mindset #2「不憑直覺發明」+ Meta-Pattern M1 的
+機械化 guardrail。
+
+建議模板(加到 file top 的 JSDoc):
+
+/**
+ * {Component} — {定位一句話}
+ *
+ * ── 定位 ──
+ * {one-liner purpose}
+ *
+ * ── 實作基礎 ──
+ * 消費: [Button, Input, ItemInlineAction, ...]  // DS components used
+ * 對應 pattern: [item-anatomy, action-bar]
+ *
+ * ── 消費的 SSOT ──
+ * - components: [...]
+ * - patterns: [patterns/xxx/spec.md]
+ * - tokens: [--layout-space-loose, --chrome-header-height]
+ * - spec refs: {nearest kin specs}
+ */
+
+若檔案不是新增元件(例:test / helper / type-only),可忽略本警告。
+若是新元件或重大 feature,請補齊再 commit。
+
+(本 hook 非 blocking,只是提醒。)
+EOF
+
+exit 0

package/ds-canonical/hooks/retired/check_sync_update.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# PostToolUse hook: remind to check sync when editing design-system files
+# 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')
+
+# Component .tsx edited → check spec + stories
+if echo "$FILE_PATH" | grep -q 'packages/design-system/src/components/.*\.tsx$' && \
+   ! echo "$FILE_PATH" | grep -q '\.stories\.tsx$'; then
+  echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Sync check: you just edited a design-system component .tsx file. Check if the corresponding .spec.md and .stories.tsx need updates (see CLAUDE.md sync rules)."}}'
+
+# Spec .md edited → check stories
+elif echo "$FILE_PATH" | grep -q 'packages/design-system/src/.*\.spec\.md$'; then
+  echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Sync check: you just edited a spec.md. Check if the corresponding .principles.stories.tsx and .anatomy.stories.tsx need updates to reflect the new rules."}}'
+
+# Pattern spec/code edited → check all consumers
+elif echo "$FILE_PATH" | grep -q 'packages/design-system/src/patterns/.*\.\(tsx\|md\)$'; then
+  echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Sync check: you just edited a pattern file. Check ALL consumer components listed in the pattern spec to ensure they still comply."}}'
+fi

package/ds-canonical/hooks/retired/check_third_party_dom_verified.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# check_third_party_dom_verified.sh
+#
+# Purpose: Warn when .tsx uses `[&[data-xxx]]:` attribute selector targeting
+# a 3rd-party library's internal DOM state. History: react-day-picker v9
+# DateGrid used `[&[data-range-middle]]:bg-...` assuming `data-range-middle`
+# existed, but v9 only emits `data-selected`/`data-disabled` etc. Attribute
+# selector silently failed.
+#
+# This is the CLAUDE.md Meta-Pattern M2 mechanical guardrail:
+# "消費 3rd-party lib 必驗 rendered DOM".
+#
+# Exit 0 always (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_NAME=$(echo "$INPUT" | python3 -c "import sys, json; d = json.load(sys.stdin); print(d.get('tool_name', ''))" 2>/dev/null || echo "")
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; d = json.load(sys.stdin); print(d.get('tool_input', {}).get('file_path', ''))" 2>/dev/null || echo "")
+
+case "$FILE_PATH" in
+  *.tsx) ;;
+  *.ts) ;;
+  *) exit 0 ;;
+esac
+
+# Extract new content from tool input (content for Write, new_string for Edit)
+NEW_CONTENT=$(echo "$INPUT" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+ti = d.get('tool_input', {})
+# Write: content;  Edit: new_string;  MultiEdit: edits[].new_string joined
+if 'content' in ti:
+    print(ti.get('content', ''))
+elif 'new_string' in ti:
+    print(ti.get('new_string', ''))
+elif 'edits' in ti:
+    print('\n'.join([e.get('new_string', '') for e in ti.get('edits', [])]))
+else:
+    print('')
+" 2>/dev/null || echo "")
+
+# Detect pattern: attribute selector targeting data-* that could be 3rd-party
+# Matches:  [&[data-xxx]]  or  [&[data-xxx=yyy]]  inside className or cva strings
+if ! echo "$NEW_CONTENT" | grep -qE '\[&\[data-[a-z-]+'; then
+  exit 0
+fi
+
+# Only warn if the file imports a known 3rd-party UI library
+THIRD_PARTY_LIBS="react-day-picker|@radix-ui|cmdk|sonner|embla-carousel|react-zoom-pan-pinch|@tanstack/react-virtual|@tanstack/react-table|recharts|react-aria"
+
+if ! echo "$NEW_CONTENT" | grep -qE "from ['\"]($THIRD_PARTY_LIBS)"; then
+  exit 0
+fi
+
+# Emit warning
+cat >&2 <<'EOF'
+⚠️  3rd-party DOM 驗證檢查:attribute selector 針對第三方 lib 內部 DOM
+
+偵測到 `[&[data-xxx]]:` 類 attribute selector,且檔案 import 了第三方 UI lib。
+
+Meta-Pattern M2 canonical(CLAUDE.md):**消費 3rd-party lib 必驗 rendered DOM
+(不信 docs)**。第三方 lib 的內部 DOM attribute 常跟 docs 不符,或在不同
+version 行為漂移。
+
+歷史 bug anchor:
+  react-day-picker v9 的 Day CELL 只有 data-selected / data-disabled /
+  data-today / data-outside / data-focused;**data-range-start / data-range-middle
+  / data-range-end 不存在**。用 `[&[data-range-middle]]:bg-...` 是靜默失效。
+
+驗證步驟(寫這類 selector 之前)──
+
+  1. 開 Storybook 或 dev server
+  2. Inspect element 看實際 rendered DOM 有哪些 data-* attribute
+  3. 或查 lib 源碼 `node_modules/{lib}/dist/` 找 emit 的 attribute 清單
+  4. 確認 attribute 存在 + 在當前 version 穩定 + document 過,再寫 selector
+
+替代做法(若 attribute 不存在):
+  - 透過 lib 官方 API(classNames / components props)傳 class
+  - 例:react-day-picker 用 `classNames={{ range_middle: 'bg-...' }}`,
+    lib 內部 `getClassNamesForModifiers` 會附加到 cell
+
+(本 hook 非 blocking,只是提醒。寫下 selector 前,請確認已驗過 DOM。)
+EOF
+
+exit 0

package/ds-canonical/hooks/retired/enforce_home_charter.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+# PreToolUse hook for Write:
+# When creating a NEW file in a classification-sensitive dir (patterns / skills / hooks /
+# components / tokens), inject the home's README.md charter as additionalContext so AI
+# cannot skip seeing it before creating new classification.
+#
+# Design choice — non-blocking context injection (not exit 2 block):
+#   - Correct placements must not get blocked → zero friction when AI classifies well
+#   - Incorrect placements: AI sees charter, the「這裡不收」table tells AI where to go instead
+#   - The injection happens on EVERY Write to sensitive dirs, so AI cannot「forget」the charter
+#
+# Exit codes (Claude Code hook protocol):
+#   0 + stdout JSON — inject additionalContext (non-blocking)
+
+# 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 // ""')
+
+[ "$TOOL" = "Write" ] || exit 0
+[ -n "$FILE_PATH" ] || exit 0
+
+# Skip if file already exists (overwrite, not classification event).
+[ -e "$FILE_PATH" ] && exit 0
+
+# README.md itself — the charter file, no self-reference needed.
+case "$(basename "$FILE_PATH")" in
+  README.md) exit 0 ;;
+esac
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Longest prefix first for nested matches.
+SENSITIVE_DIRS=(
+  "$PROJECT_ROOT/packages/design-system/src/patterns"
+  "$PROJECT_ROOT/packages/design-system/src/components"
+  "$PROJECT_ROOT/packages/design-system/src/tokens"
+  "$PROJECT_ROOT/packages/design-system/src"
+  "$PROJECT_ROOT/.claude/skills"
+  "$PROJECT_ROOT/.claude/hooks"
+  "$PROJECT_ROOT/.claude/commands"
+  "$PROJECT_ROOT/.claude/agents"
+)
+
+MATCHED_DIR=""
+for dir in "${SENSITIVE_DIRS[@]}"; do
+  if [[ "$FILE_PATH" == "$dir/"* ]]; then
+    MATCHED_DIR="$dir"
+    break
+  fi
+done
+
+[ -n "$MATCHED_DIR" ] || exit 0
+
+README_PATH="$MATCHED_DIR/README.md"
+[ -f "$README_PATH" ] || exit 0
+
+REL_IN_HOME="${FILE_PATH#$MATCHED_DIR/}"
+FIRST_SEGMENT="${REL_IN_HOME%%/*}"
+NEW_SUBDIR_PATH="$MATCHED_DIR/$FIRST_SEGMENT"
+
+IS_FLAT_FILE="false"
+[ "$REL_IN_HOME" = "$FIRST_SEGMENT" ] && IS_FLAT_FILE="true"
+
+# Flat files are CONVENTION for these dirs (per Claude Code native format):
+#   .claude/hooks/       — individual hook scripts
+#   .claude/commands/    — individual command .md files
+#   .claude/agents/      — individual agent .md files
+# For these, flat file is not a classification anomaly; exit silently.
+case "$MATCHED_DIR" in
+  */.claude/hooks|*/.claude/commands|*/.claude/agents)
+    if [ "$IS_FLAT_FILE" = "true" ]; then
+      exit 0
+    fi
+    ;;
+esac
+
+IS_NEW_SUBDIR="false"
+if [ "$IS_FLAT_FILE" = "false" ] && [ ! -d "$NEW_SUBDIR_PATH" ]; then
+  IS_NEW_SUBDIR="true"
+fi
+
+# Only fire on classification events:
+#   - flat file directly under sensitive dir root (usually wrong — breaks convention)
+#   - new sub-folder creation (first time this classification exists)
+# Nested writes into existing sub-folders are not classification events; stay silent.
+if [ "$IS_FLAT_FILE" = "false" ] && [ "$IS_NEW_SUBDIR" = "false" ]; then
+  exit 0
+fi
+
+HOME_NAME="${MATCHED_DIR#$PROJECT_ROOT/}"
+CHARTER_CONTENT=$(cat "$README_PATH")
+
+if [ "$IS_FLAT_FILE" = "true" ]; then
+  HEADER="⚠️  FLAT FILE at $HOME_NAME/ root — convention requires sub-folder structure. Verify this is not a misplacement before proceeding."
+else
+  HEADER="🚪 NEW SUB-FOLDER being created in $HOME_NAME/ (classification event). Verify against the charter below BEFORE the Write proceeds."
+fi
+
+cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":$(jq -Rs . <<<"HOME CHARTER GATE — $HOME_NAME/
+
+$HEADER
+
+Path being written: $FILE_PATH
+
+=== CHARTER ($README_PATH) ===
+$CHARTER_CONTENT
+=== END CHARTER ===
+
+Three-question verification BEFORE proceeding with Write:
+  1. Does your content match 「這裡只收」?
+  2. Does it match any row of 「這裡不收」 (i.e. belongs elsewhere)?
+  3. Does it pass all 「新增 criteria」?
+
+If misplaced → STOP, cancel this Write, redirect to correct home.
+If charter is outdated → update README.md first.
+If placement is correct → proceed.")}}
+EOJSON
+
+exit 0

package/ds-canonical/hooks/retired/post_edit_canonical_interrogate.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# PostToolUse Edit|Write|MultiEdit: 對 canonical 文件的「新增 rule/section」
+# 注入 3 題短 interrogation,補 M8 benchmark / Rule-of-3 / M10 下游吸收的
+# runtime adherence(不是 infra,是 model 自律)。
+#
+# Scope(極窄,避免噪音):
+#   - CLAUDE.md Edit/Write
+#   - packages/design-system/src/**/*.spec.md Edit/Write
+#   - .claude/skills/*/SKILL.md Edit/Write
+#
+# 觸發條件(只在真正「加新 rule」時 fire):
+#   - Write(新檔)- 一律 fire
+#   - Edit:new_string 淨增 > 200 chars OR 含新 `##` heading OR 含「**M\d+**」
+#     (M-row 由 pre_write_subsumption_check 處理,本 hook skip 以免 double fire)
+#
+# Non-blocking(PostToolUse 僅注 context,AI 讀到 3 題自律回答)。
+#
+# Per-hook fire logging
+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
+
+# Scope gate
+IN_SCOPE=0
+case "$FILE_PATH" in
+  */CLAUDE.md) IN_SCOPE=1 ;;
+  */packages/design-system/src/*/*.spec.md) IN_SCOPE=1 ;;
+  */.claude/skills/*/SKILL.md) IN_SCOPE=1 ;;
+esac
+[ "$IN_SCOPE" = "0" ] && exit 0
+
+# Extract new content
+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 "")
+OLD_CONTENT=$(echo "$INPUT" | jq -r '
+  (.tool_input.old_string // "") + "\n" +
+  ([.tool_input.edits[]? | .old_string] | join("\n"))
+' 2>/dev/null || echo "")
+
+# Skip if M-row addition(pre_write_subsumption_check 已處理)
+if echo "$NEW_CONTENT" | grep -qE '\|\s*\*\*M[0-9]+\*\*\s*\|'; then
+  exit 0
+fi
+
+# Trigger heuristics
+TRIGGER=0
+TRIGGER_REASON=""
+
+# (a) Write(新檔)
+if [ "$TOOL" = "Write" ]; then
+  TRIGGER=1
+  TRIGGER_REASON="new file"
+else
+  # (b) Edit 淨增 > 200 chars
+  NEW_LEN=$(printf '%s' "$NEW_CONTENT" | wc -c | tr -d ' ')
+  OLD_LEN=$(printf '%s' "$OLD_CONTENT" | wc -c | tr -d ' ')
+  NET_ADD=$(( NEW_LEN - OLD_LEN ))
+  if [ "$NET_ADD" -gt 200 ]; then
+    TRIGGER=1
+    TRIGGER_REASON="net +${NET_ADD} chars"
+  fi
+  # (c) new_string 含新 `##` heading 而 old_string 不含
+  if echo "$NEW_CONTENT" | grep -qE '^## '; then
+    if ! echo "$OLD_CONTENT" | grep -qE '^## '; then
+      TRIGGER=1
+      TRIGGER_REASON="new ## section"
+    fi
+  fi
+fi
+
+[ "$TRIGGER" = "0" ] && exit 0
+
+# Tailor prompt by file type
+case "$FILE_PATH" in
+  */CLAUDE.md)
+    HOME_LABEL="CLAUDE.md"
+    SCOPE_NOTE="canonical 最高層;任何新規則必 benchmark + 下游吸收"
+    ;;
+  */packages/design-system/src/*/*.spec.md)
+    HOME_LABEL="spec.md"
+    SCOPE_NOTE="spec SSOT;新規則必對齊 7 維 + 近親 spec cross-check"
+    ;;
+  */.claude/skills/*/SKILL.md)
+    HOME_LABEL="SKILL.md"
+    SCOPE_NOTE="skill workflow;新步驟 / checkpoint 必 world-class 對照 + skill 重複 check"
+    ;;
+esac
+
+MSG="🧭 Canonical interrogation(${HOME_LABEL} ${TRIGGER_REASON})— ${SCOPE_NOTE}。3 題短 self-check:\n\n"
+MSG="${MSG}1. **World-class benchmark**(M8):新 rule / pattern 有 ≥ 3 家 DS 對照嗎?列具體實作名或「無」(無 = rule 未成熟,考慮 ship 前先調研)。\n\n"
+MSG="${MSG}2. **Rule-of-3**(資訊治理):本概念已在別處出現?若 ≥ 3 處 → 選 SSOT owner,其他 pointer only。確認是 SSOT 新寫還是應該 pointer?\n\n"
+MSG="${MSG}3. **M10 下游吸收**:新 rule 是否讓既有某條 rule / memory / bug case 變冗餘?明寫「可刪 X」或「無下游變動」。空白不算。\n\n"
+MSG="${MSG}⚠️ 回答上述 3 題(even 簡短)再繼續,避免 silent append-only 膨脹。"
+
+ESCAPED=$(printf '%b' "$MSG" | jq -Rs .)
+printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":%s}}\n' "$ESCAPED"
+exit 0

package/ds-canonical/hooks/retired/pre_edit_spec_check.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# PreToolUse hook: before editing a design-system component .tsx,
+# remind AI to read the spec first.
+#
+# Diff-aware: skip if the edit is purely import cleanup / type-only / typo —
+# spec reading not required for those. Only fire if edit touches render body,
+# cva, variants, tokens, or other design-meaningful regions.
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only trigger for design-system component .tsx files (not stories, not specs)
+if ! echo "$FILE_PATH" | grep -q 'packages/design-system/src/components/.*\.tsx$'; then
+  exit 0
+fi
+echo "$FILE_PATH" | grep -q '\.stories\.tsx$' && exit 0
+
+# Diff-aware: extract old+new content. Skip if it's purely import / export-list
+# manipulation or type-alias tweaks (not design-meaningful).
+DIFF_TEXT=$(echo "$INPUT" | jq -r '
+  (.tool_input.old_string // "") + "\n---\n" +
+  (.tool_input.new_string // "") + "\n---\n" +
+  (.tool_input.content    // "") + "\n---\n" +
+  ([.tool_input.edits[]? | (.old_string + "\n---\n" + .new_string + "\n---\n")] | join(""))
+' 2>/dev/null || echo "")
+
+# If diff is non-empty and consists ONLY of import lines / export lines /
+# pure type annotations — skip.
+if [ -n "$DIFF_TEXT" ]; then
+  # Strip lines that are imports / exports / type declarations / whitespace.
+  MEANINGFUL=$(echo "$DIFF_TEXT" | grep -vE '^[[:space:]]*(import |export (type )?\{|export type |type [A-Z]|interface [A-Z]|//|---|[[:space:]]*$|\}|\{)' | head -5)
+  # If nothing substantive remains, skip the nag.
+  [ -z "$MEANINGFUL" ] && exit 0
+fi
+
+COMP_DIR=$(echo "$FILE_PATH" | sed -n 's|.*packages/design-system/src/components/\([^/]*\)/.*|\1|p')
+[ -z "$COMP_DIR" ] && exit 0
+
+SPEC_BASENAME=$(echo "$COMP_DIR" | sed 's/\([a-z]\)\([A-Z]\)/\1-\2/g; s/\([A-Z]\)\([A-Z][a-z]\)/\1-\2/g' | tr '[:upper:]' '[:lower:]')
+SPEC_PATH="${CLAUDE_PROJECT_DIR}/packages/design-system/src/components/${COMP_DIR}/${SPEC_BASENAME}.spec.md"
+
+# Extract 禁止事項 section(如 spec 存在且有該 section)— inject 到 additionalContext
+# 讓 AI 改 tsx 前機械上讀到 forbid list,不靠記憶。2026-04-24 FileUpload `files` prop
+# 事件根因:spec 禁止事項寫「不在 FileUpload 自己畫 list」AI 未讀就加 prop。
+FORBID_SECTION=""
+if [ -f "$SPEC_PATH" ]; then
+  # awk 抓從「## 禁止事項」到下個 H2 前的內容(最多 40 行 cap,避免爆量)
+  FORBID_SECTION=$(awk '
+    /^## (禁止事項|Forbidden|❌)/ { in_section=1; print; next }
+    in_section && /^## / { exit }
+    in_section { print }
+  ' "$SPEC_PATH" 2>/dev/null | head -40)
+fi
+
+CONTEXT="⚠️ Editing ${COMP_DIR} (design-meaningful region). READ ${SPEC_BASENAME}.spec.md full 禁止事項 + Props 行為 sections before proceeding."
+if [ -n "$FORBID_SECTION" ]; then
+  # 用 jq 安全 escape multiline content into JSON string
+  ESCAPED=$(printf '%s\n\n---\n\n%s' "$CONTEXT" "$FORBID_SECTION" | jq -Rs .)
+  cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":${ESCAPED}}}
+EOJSON
+else
+  cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"${CONTEXT}"}}
+EOJSON
+fi

package/ds-canonical/hooks/retired/pre_new_component_spec.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# PreToolUse hook for Write:
+# When creating a NEW {name}.spec.md under packages/design-system/src/components/{Name}/,
+# inject a Layout Family declaration reminder. Prevents silent drift where
+# a new component spec is created without Family 1/2/3/4 or exception declared —
+# which bypasses the 4-Family Model taxonomy and accumulates classification debt.
+#
+# Exit: 0 + stdout JSON additionalContext (non-blocking)
+
+# 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 // ""')
+
+[ "$TOOL" = "Write" ] || exit 0
+[ -n "$FILE_PATH" ] || exit 0
+[ -e "$FILE_PATH" ] && exit 0   # only fire on NEW file
+
+# Match: packages/design-system/src/components/{Name}/{name}.spec.md (exclude nested sub-specs)
+if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/components/[^/]+/[^/]+\.spec\.md$'; then
+  exit 0
+fi
+
+# Exclude Field sub-specs (field-controls.spec.md, form-validation.spec.md — these are
+# Field-system shared specs, not single-component specs — they inherit from field.spec.md)
+BASE_NAME=$(basename "$FILE_PATH" .spec.md)
+case "$BASE_NAME" in
+  field-controls|form-validation|field-types) exit 0 ;;
+esac
+
+cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"🏛️ NEW COMPONENT SPEC — Layout Family declaration REQUIRED in first paragraph.\n\nPath: $FILE_PATH\n\nMANDATORY first-paragraph declaration (see CLAUDE.md '# 系統內部 Layout — 4-Family Model' + patterns/element-anatomy/item-anatomy.spec.md):\n\n  **Layout Family**: <one of>\n    - Family 1 (Menu item layout, scanning mode)\n    - Family 2 (List item layout, reading mode)\n    - Family 3 (Pill layout, action trigger OR data indicator sub-profile)\n    - Family 4 (Field control layout)\n    - Non-family (self-contained primitive OR composite multi-section) + rationale\n\nIf Family 1/2 → consume <MenuItem> or compose item-anatomy slot primitives (<ItemIcon>, <ItemAvatar>, <ItemLabel>, <ItemSuffix>, <ItemInlineAction>), don't reinvent.\nIf Family 3 → follow Button Pill Layout.\nIf Family 4 → follow field-controls.spec.md.\nIf Non-family → spec MUST justify why (self-contained vs composite).\n\nForgetting this declaration accumulates taxonomy debt. Also consider invoking /component-quality-gate before merging this component into DS."}}
+EOJSON
+
+exit 0