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

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

@@ -0,0 +1,61 @@
+#!/bin/bash
+# PreToolUse Write: 任何治理檔(新 skill / hook / CLAUDE.md 章節)寫入前,
+# 強制 AI 跑 governance compliance self-check — 防 M7 violation 再次發生。
+#
+# 根源:AI 設計新 skill/hook/rule 時常忘 cross-check 既有 meta-pattern
+# + 2-home canonical(spec/tsx)+ Rule-of-3 + audit-vs-execute 分權,
+# 導致後續需要 refactor(見 2026-04-24 `/knowledge-prune` 錯搬 canonical 事件)。
+#
+# 本 hook 在 Write 時注入強制 self-check prompt,AI 必逐條答。
+# 非 blocking(只注入 context),但 AI 必在 response 裡提出 audit 結果。
+
+# 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" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only fire for new governance files
+[ -z "$FILE_PATH" ] && exit 0
+[ "$TOOL_NAME" != "Write" ] && exit 0
+
+# File path scope
+case "$FILE_PATH" in
+  */CLAUDE.md)                          SCOPE="CLAUDE.md section/rule" ;;
+  */.claude/skills/*/SKILL.md)          SCOPE="new skill" ;;
+  */.claude/skills/*/references/*.md)   SCOPE="skill reference doc" ;;
+  */.claude/hooks/*.sh|*/.claude/hooks/*.py)  SCOPE="new hook" ;;
+  */.claude/planning/*.md)              SCOPE="planning doc" ;;
+  *) exit 0 ;;
+esac
+
+# Only fire for NEW files(Write 新檔;既存 edit 不注入,減噪音)
+[ -f "$FILE_PATH" ] && exit 0
+
+MSG=$(cat <<EOF
+🛡️ Governance compliance self-check(${SCOPE})— 寫入前必回答以下 7 題,答不過停下重設計:
+
+1. M7 cross-check:本規則 / skill / hook 跟既有 Meta-Pattern M1-M17 有牴觸 / 漏用嗎?特別 M10(proactive exhaustive scan)/ M14(AUTO integrate pipeline)/ M17(SSOT 必可傳播)— 有受影響嗎?
+
+2. 2-Home canonical(spec.md = 不可程式化 judgment / tsx = 可程式化):本規則會把 canonical judgment 推到 references/ 嗎?若是違反 2-home,該留 spec/tsx。
+
+3. Rule-of-3:本規則概念已在 ≥ 3 處出現?若是,選 SSOT 其他 pointer only。
+
+4. Audit-vs-execute 分權:動到 canonical substantive meaning 嗎?若是,走 STOP 提議不 AUTO。
+
+5. 既有 SSOT 整合(對齊 CLAUDE.md SSOT 消費 canonical):本規則該 cross-link 到哪個現有 spec / hook / skill?
+
+6. hook / skill 重複偵測:.claude/hooks/ 跟 .claude/skills/ 有既存類似功能嗎?若是擴充既有,而非新建。
+
+7. Phase F Self-improvement capture:本 skill 若是 audit 類,Phase F 有無 Self-improvement capture step?
+
+規則:在 response 明確列出 7 題答案(可簡短)。有任一題 fail → 停下重設計不寫入。通過才寫。
+EOF
+)
+
+ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+exit 0

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

@@ -0,0 +1,104 @@
+#!/bin/bash
+# PreToolUse hook: 偵測 icon-only host 用 padding-formula `(field-height - <iconPx>) / 2`
+# 派(舊 idiom),warn 改用 padding-free `ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'`。
+#
+# Motivation(2026-04-25 user 在 Safari mobile DS Devmode 抓到 14×16 asymmetric):
+#   舊 padding-formula 公式沒扣 border 2px → SVG 被 flex `min-w-0` 擠成 width<intrinsic
+#   asymmetric(width=14px / height=16px,對齊 `--font-body-size` / `--font-body-lg-size`)。
+#   修法 = padding-free idiom(Polaris/Atlassian 派),消除 magic number 完全。
+#
+# SSOT:`tokens/uiSize/uiSize.spec.md`「Icon-only 元件的 padding canonical」節。
+# 已 migrate consumers:Button + SegmentedControl(2026-04-25)。
+#
+# Detection 規則(同時滿足才 fire):
+#   1. .tsx 含 `iconOnly` keyword(prop / variant / variable name)
+#   2. AND 含 `(var(--field-height-X) - <iconPx>px)` 公式 — iconPx ∈ {14,16,20,24}
+#      (vertical centering 公式 `(field-height - 1lh)/2` 不觸發,因為 1lh 不是 px 數字)
+#
+# Allowlist:
+#   //  @icon-only-padding-allow: <reason>(整檔豁免)
+#
+# Exit codes:
+#   exit 0(non-blocking,injected context only)— PreToolUse 注入 warning,
+#     依 user 判斷是否 migrate;不 hard block 因為某些舊 layer 公式可能仍合法。
+
+# 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
+
+# 只查 design-system tsx(不查 stories 不查 test)
+case "$FILE_PATH" in
+  */packages/design-system/src/components/*.tsx|*/packages/design-system/src/patterns/*.tsx) ;;
+  *) exit 0 ;;
+esac
+case "$FILE_PATH" in
+  *.stories.tsx|*.test.tsx|*.spec.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
+
+# Allowlist
+FIRST=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,5p')
+if echo "$FIRST" | grep -qE '//[[:space:]]*@icon-only-padding-allow:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK=$(sed -n '1,5p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK" | grep -qE '//[[:space:]]*@icon-only-padding-allow:'; then
+    exit 0
+  fi
+fi
+
+# Combine new content with existing on-disk(若 Edit 局部改不一定包含 iconOnly)
+COMBINED="$NEW_CONTENT"
+if [ -f "$FILE_PATH" ]; then
+  COMBINED="${COMBINED}
+$(cat "$FILE_PATH" 2>/dev/null || echo "")"
+fi
+
+HAS_ICONONLY=0
+HAS_FORMULA=0
+FORMULA_SAMPLE=""
+
+if echo "$COMBINED" | grep -qE 'iconOnly|ICON_ONLY|icon-only'; then
+  HAS_ICONONLY=1
+fi
+
+# Match `(var(--field-height-X) - <iconPx>px ...) / 2` where iconPx ∈ 14/16/20/24
+MATCH=$(printf '%s\n' "$COMBINED" | grep -oE 'calc\(\(var\(--field-height-(xs|sm|md|lg)\)\s*-\s*(14|16|20|24)px[^)]*\)\s*/\s*2\)' | head -1 || true)
+if [ -n "$MATCH" ]; then
+  HAS_FORMULA=1
+  FORMULA_SAMPLE="$MATCH"
+fi
+
+if [ "$HAS_ICONONLY" = "1" ] && [ "$HAS_FORMULA" = "1" ]; then
+  MSG="🚨 iconOnly host 用 padding-formula(舊 idiom)— $(basename "$FILE_PATH")\n\n"
+  MSG="${MSG}偵測到:${FORMULA_SAMPLE}\n\n"
+  MSG="${MSG}Canonical(2026-04-25):iconOnly 必用 padding-free idiom\n\n"
+  MSG="${MSG}\`\`\`tsx\nconst ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'\n\`\`\`\n\n"
+  MSG="${MSG}舊 idiom bug origin:公式沒扣 border 2px → SVG 被 flex min-w-0 擠成 14×16 不對稱。\n"
+  MSG="${MSG}World-class 派(Polaris / Atlassian)走 padding-free,我們對齊。\n\n"
+  MSG="${MSG}SSOT:tokens/uiSize/uiSize.spec.md「Icon-only 元件的 padding canonical」\n"
+  MSG="${MSG}參照 migrated consumers:components/Button/button.tsx + components/SegmentedControl/segmented-control.tsx\n\n"
+  MSG="${MSG}若此檔屬刻意保留舊公式(極罕見、需 spec rationale),檔首加 // @icon-only-padding-allow: <reason>"
+  ESCAPED=$(printf '%b' "$MSG" | jq -Rs .)
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+fi
+
+exit 0

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

@@ -0,0 +1,150 @@
+#!/bin/bash
+# PreToolUse hook: detect hard-coded `mt-0.5` / `gap-0.5` in component .tsx(非 stories)
+# 應改用 `var(--item-gap-label-desc)` token OR `<ItemContent>` primitive。
+#
+# Motivation (2026-04-23 SSOT architecture · item-anatomy「Label ↔ Desc 間距」token/primitive):
+#   User 指出 mt-0.5 canonical 是 markdown 文字 / 13+ 消費者各自 hard-code = 非真 SSOT。
+#   已建 `--item-gap-label-desc` token + `<ItemContent>` primitive,消費者應:
+#     (a) 直接消費 token:`mt-[var(--item-gap-label-desc)]`
+#     (b) 消費 primitive:`<ItemContent label desc ...>`
+#   Hard-code `mt-0.5` / `gap-0.5` 會讓改值時漏同步 → DS drift
+#
+# 檢查 pattern:
+#   P1 WARN  .tsx 有 `mt-0.5` / `gap-0.5` 字面 class → warn 改 token / primitive
+#
+# Scope: component / pattern .tsx(跳過 stories、跳過已知例外 Calendar event / FileViewer zoom)
+#
+# Allowlist:
+#   // @item-gap-exempt: <reason>(整檔豁免 — consumer 有明文 rationale)
+#   // @item-gap-exempt-next(下一行豁免)
+#
+# Exit codes:
+#   exit 0 — pass OR warn only(不 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
+
+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 check .tsx in components/ or patterns/(不查 stories / markdown / css)
+case "$FILE_PATH" in
+  */packages/design-system/src/components/*.tsx|*/packages/design-system/src/patterns/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+# Skip stories
+case "$FILE_PATH" in
+  *.stories.tsx|*.anatomy.stories.tsx|*.principles.stories.tsx) exit 0 ;;
+esac
+
+# Skip known-exempt files(Calendar event column / FileViewer zoom pill — 非 label-desc 語義)
+case "$FILE_PATH" in
+  */Calendar/calendar.tsx|*/FileViewer/file-viewer.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 "")
+
+if [ -z "${NEW_CONTENT//[[:space:]]/}" ]; then
+  exit 0
+fi
+
+# File-level allowlist
+FIRST_LINES=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,3p')
+if echo "$FIRST_LINES" | grep -qE '//[[:space:]]*@item-gap-exempt:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK_FIRST=$(sed -n '1,3p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@item-gap-exempt:'; then
+    exit 0
+  fi
+fi
+
+WARN_VIOLATIONS=""
+
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+printf '%s\n' "$NEW_CONTENT" > "$TMP"
+
+ROW=0
+SKIP_NEXT=0
+while IFS= read -r LINE || [ -n "$LINE" ]; do
+  ROW=$((ROW+1))
+
+  if [ "$SKIP_NEXT" = "1" ]; then
+    SKIP_NEXT=0
+    continue
+  fi
+  if echo "$LINE" | grep -qE '//[[:space:]]*@item-gap-exempt-next|\{/\*[[:space:]]*@item-gap-exempt-next'; then
+    SKIP_NEXT=1
+    continue
+  fi
+
+  # P1 WARN: `mt-0.5` or `gap-0.5` 硬寫(非 comment)
+  # heuristic:line 含 className=".*mt-0\.5|.*gap-0\.5" 且非純 comment
+  if echo "$LINE" | grep -qE 'className\s*=\s*\{?[^}]*"[^"]*\b(mt-0\.5|gap-0\.5)\b' \
+     || echo "$LINE" | grep -qE "'[^']*\b(mt-0\.5|gap-0\.5)\b[^']*'"; then
+    WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P1 hard-coded mt-0.5 / gap-0.5(warn)] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  建議修法(擇一):
+    (a) 用 token:改成 \`mt-[var(--item-gap-label-desc)]\` / \`gap-[var(--item-gap-label-desc)]\`
+    (b) 用 primitive:改用 \`<ItemContent label description descriptionTone mode>\`
+        (from \`@/design-system/patterns/element-anatomy/item-anatomy\`)
+  若此處刻意 hard-code 有 rationale,在該 tsx 檔首加 // @item-gap-exempt: <reason>
+  SSOT: tokens/layoutSpace/layoutSpace.css + patterns/element-anatomy/item-anatomy.tsx(ItemContent)"
+  fi
+
+  # P2 WARN: suffix block formula `calc(1lh+2px+...)` 硬寫 2px(應用 token)
+  if echo "$LINE" | grep -qE 'calc\(1lh\+2px\+'; then
+    WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P2 hard-coded 2px in calc formula(warn)] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  建議修法:\`calc(1lh+2px+...)\` → \`calc(1lh+var(--item-gap-label-desc)+...)\`
+  Rationale:block formula 的 gap 2px 應跟 inline label↔desc gap 共用 SSOT token,
+  確保「改 token 一處 → inline + block 兩層 formula 同步」。
+  SSOT: tokens/layoutSpace/layoutSpace.css(\`--item-gap-label-desc\`)"
+  fi
+
+  # P3 WARN: `h-[1lh] shrink-0 flex items-center` 手刻 prefix wrapper(應用 ItemPrefix primitive)
+  if echo "$LINE" | grep -qE '"[^"]*\bh-\[1lh\]\s+shrink-0\s+flex\s+items-center\b'; then
+    WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P3 hard-coded prefix wrapper(warn)] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  建議修法:改用 \`<ItemPrefix>\` primitive
+    (from \`@/design-system/patterns/element-anatomy/item-anatomy\`)
+  Rationale:\`h-[1lh] shrink-0 flex items-center\` 是 item-anatomy「Prefix 垂直對齊」
+  canonical 的實作細節,ItemPrefix 已封裝(+ \`min-w-[var(--item-prefix-slot,auto)]\` 對齊行為)。
+  手刻 = 未來改 prefix wrapper 規則需手動 grep 26+ 檔。
+  若本 span 有 **特殊 width / justify-content 需求**(例如 TreeView 固定 iconPx 寬):
+  加 // @item-gap-exempt-next 到此行上一行(必須附 rationale 在 spec.md)。
+  SSOT: patterns/element-anatomy/item-anatomy.tsx(ItemPrefix)"
+  fi
+
+done < "$TMP"
+
+if [ -n "$WARN_VIOLATIONS" ]; then
+  {
+    echo ""
+    echo "┄┄┄┄ check_item_content_primitive — hard-coded mt-0.5 / gap-0.5(warn) ┄┄┄┄"
+    printf '%s\n' "$WARN_VIOLATIONS"
+  } >&2
+fi
+
+exit 0

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

@@ -0,0 +1,153 @@
+#!/bin/bash
+# PreToolUse hook: detect FileItem list wrapper 加外框(P2 block)或 likely-missing gap(P1 warn)。
+#
+# Motivation(CLAUDE.md「連續 item 貼邊合法性」v2 canonical · 2026-04-22):
+#   Permanent standalone card/pill(bg + radius + inset)→ 必 gap(防融合)
+#   Permanent flush full-width / transparent → 0 gap 合法(靠 border-b / progress bar / separator)
+#
+#   FileItem rich    → permanent border card → standalone → 必 gap-2
+#   FileItem compact no status(Type B form attachment) → permanent bg-secondary pill → 必 gap-1
+#   FileItem compact with status(Type A upload manager) → flush + progress bar 分隔線型 → 0 gap 合法
+#
+# 檢查 patterns(scope: FileItem MVP,未來可擴其他 standalone card 類元件):
+#   P1  list wrapper `flex-col` 無 `gap-*` + FileItem map 內 → **WARN**(exit 0 + stderr)
+#       靜態 grep 難 reliably 區分 Type A / Type B,交給人判斷
+#   P2  list wrapper 加 `border` / `overflow-hidden` / `rounded-lg` + FileItem map 內 → **BLOCK**(exit 2)
+#       無論 Type A / B / rich,外框 + overflow-hidden 都是 wrong(強制邊框相黏、雙重 card)
+#
+# Allowlist:
+#   // @item-gap-exempt: <reason>
+#
+# Exit codes:
+#   exit 0 — pass(OR P1 warn only,stderr has 訊息但不 block)
+#   exit 2 + stderr — P2 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
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+case "$TOOL" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+case "$FILE_PATH" in
+  *.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 "")
+
+if [ -z "${NEW_CONTENT//[[:space:]]/}" ]; then
+  exit 0
+fi
+
+# Allowlist
+FIRST_LINES=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,3p')
+if echo "$FIRST_LINES" | grep -qE '//[[:space:]]*@item-gap-exempt:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK_FIRST=$(sed -n '1,3p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@item-gap-exempt:'; then
+    exit 0
+  fi
+fi
+
+# 需要全檔內容上下文(map 外層 wrapper 通常在 FileItem 上方幾行),用合併後的檔案新狀態掃描
+if [ -f "$FILE_PATH" ]; then
+  FULL_CONTENT=$(cat "$FILE_PATH" 2>/dev/null)
+  # Edit 類: 檔案修改後的實際樣子(簡化:直接讀 on-disk + incoming content 合併判斷)
+  # 這裡保守用 NEW_CONTENT 為主(incoming changes)
+  CONTENT="$NEW_CONTENT"
+else
+  CONTENT="$NEW_CONTENT"
+fi
+
+BLOCK_VIOLATIONS=""   # P2 — always wrong(block)
+WARN_VIOLATIONS=""    # P1 — likely wrong but depends on Type A/B(warn,不 block)
+
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+printf '%s\n' "$CONTENT" > "$TMP"
+
+ROW=0
+while IFS= read -r LINE || [ -n "$LINE" ]; do
+  ROW=$((ROW+1))
+
+  # P2 BLOCK: wrapper 有 border / overflow-hidden / rounded-lg 外框 + FileItem map → 總是錯
+  if echo "$LINE" | grep -qE '<div[^>]*className="[^"]*\bflex-col\b[^"]*\b(border|overflow-hidden|rounded-lg)\b'; then
+    END=$((ROW+6))
+    LOOKAHEAD=$(sed -n "$((ROW+1)),${END}p" "$TMP" 2>/dev/null || true)
+    if echo "$LOOKAHEAD" | grep -qE '<FileItem\b'; then
+      BLOCK_VIOLATIONS="${BLOCK_VIOLATIONS}
+────────────────────────────────
+[P2 list wrapper 加外框] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  修法: FileItem rich 自帶 border card、compact 自帶 bg-secondary(Type B)或 progress bar(Type A)。
+        list wrapper **不應**再加 border / rounded-lg / overflow-hidden。
+        (overflow-hidden 會強制邊框合併、雙重外框破壞 card 自立)
+        改用:<div className=\"flex flex-col [gap-*]\">
+        SSOT: components/FileItem/file-item.spec.md「List wrapper canonical」"
+    fi
+  fi
+
+  # P1 WARN: wrapper flex-col 無 gap + FileItem map → 可能缺 gap(Type A / B 判斷由人)
+  if echo "$LINE" | grep -qE '<div[^>]*className="[^"]*\bflex-col\b[^"]*"' \
+     && ! echo "$LINE" | grep -qE '\bgap-[0-9]' \
+     && ! echo "$LINE" | grep -qE 'gap-\[var\(--'; then
+    END=$((ROW+6))
+    LOOKAHEAD=$(sed -n "$((ROW+1)),${END}p" "$TMP" 2>/dev/null || true)
+    if echo "$LOOKAHEAD" | grep -qE '<FileItem\b'; then
+      WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P1 list wrapper 可能缺 gap(warn)] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  判斷: FileItem 依 mode / status 有不同 gap 需求:
+          rich(任何 status)        → standalone card → 必 gap-2
+          compact + 無 status(Type B) → standalone pill(bg-secondary)→ 必 gap-1
+          compact + 有 status(Type A) → flush + progress bar 分隔線 → 0 gap 合法
+        若此處是 Type A(compact 上傳狀態,progress bar 作分隔)→ 合法,可忽略。
+        若是 rich / Type B → 補 gap-2 / gap-1。
+        SSOT: patterns/element-anatomy/item-anatomy.spec.md「連續 item 貼邊合法性 v2」"
+    fi
+  fi
+
+done < "$TMP"
+
+# Emit warnings(stderr but continue)
+if [ -n "$WARN_VIOLATIONS" ]; then
+  {
+    echo ""
+    echo "┄┄┄┄ check_item_list_gap — P1 warn(可能缺 gap,依 mode/status 判斷) ┄┄┄┄"
+    printf '%s\n' "$WARN_VIOLATIONS"
+  } >&2
+fi
+
+# Emit block only for P2
+if [ -n "$BLOCK_VIOLATIONS" ]; then
+  {
+    echo ""
+    echo "╔════════════════════════════════════════════════════════════════"
+    echo "║ check_item_list_gap — list wrapper 加外框(P2 block)"
+    echo "╚════════════════════════════════════════════════════════════════"
+    printf '%s\n' "$BLOCK_VIOLATIONS"
+    echo ""
+    echo "────────────────────────────────"
+    echo "SSOT canonical:"
+    echo "  - patterns/element-anatomy/item-anatomy.spec.md「連續 item 貼邊合法性 v2」"
+    echo "  - components/FileItem/file-item.spec.md「List wrapper canonical」"
+  } >&2
+  exit 2
+fi
+
+exit 0

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

@@ -0,0 +1,65 @@
+#!/bin/bash
+# PostToolUse hook: catch non-canonical sideOffset overrides on overlay primitives.
+#
+# DS canonical: all overlay primitives (Popover / Tooltip / DropdownMenu / HoverCard /
+# SelectMenu / Coachmark) use sideOffset=8 (Notion / Linear / Figma 6-8px idiom).
+# Consumers should NEVER override sideOffset — if they think they need to, the
+# visual is fighting the DS and the right fix is to discuss, not to patch locally.
+#
+# This hook warns when a file sets sideOffset to anything other than 8 (the DS
+# canonical). Overlay primitive SOURCE files are exempt (they set the default).
+#
+# Trigger: PostToolUse on Edit/Write/MultiEdit for any .tsx/.md file that
+# contains `sideOffset=`.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+
+# Only .tsx / .md files
+case "$FILE_PATH" in
+  *.tsx|*.md) ;;
+  *) exit 0 ;;
+esac
+
+[ -f "$FILE_PATH" ] || exit 0
+
+# Exempt the overlay primitive source files themselves (they set defaults).
+case "$FILE_PATH" in
+  */Popover/popover.tsx) exit 0 ;;
+  */Tooltip/tooltip.tsx) exit 0 ;;
+  */DropdownMenu/dropdown-menu.tsx) exit 0 ;;
+  */HoverCard/hover-card.tsx) exit 0 ;;
+  */SelectMenu/select-menu.tsx) exit 0 ;;
+  */Coachmark/coachmark.tsx) exit 0 ;;
+esac
+
+# Look for sideOffset set to a literal number != 8
+# Matches: sideOffset={4}  sideOffset = 4  sideOffset={12}  etc.
+# Does NOT match:
+#   sideOffset={8}                                                (canonical)
+#   sideOffset={sideOffset}                                       (prop passthrough)
+#   sideOffset (mentioned in prose / tables / comments)
+VIOLATIONS=$(grep -nE 'sideOffset[[:space:]]*=[[:space:]]*\{[[:space:]]*[0-9]+[[:space:]]*\}' "$FILE_PATH" 2>/dev/null \
+  | grep -vE 'sideOffset[[:space:]]*=[[:space:]]*\{[[:space:]]*8[[:space:]]*\}' || true)
+
+if [ -n "$VIOLATIONS" ]; then
+  cat <<EOF
+⚠️  Non-canonical \`sideOffset\` override — $FILE_PATH
+
+$VIOLATIONS
+
+DS canonical: all overlay primitives use \`sideOffset={8}\` (世界級 idiom, Notion /
+Linear / Figma / Stripe 6-8px). Consumer should NOT override. If the default
+feels wrong visually, the fix is to discuss & change the canonical — NOT to
+sprinkle \`sideOffset={4}\` locally.
+
+Remove the override unless you have a documented exception. See
+\`components/Popover/popover.spec.md\` 「觸發距離 canonical」.
+EOF
+fi
+
+exit 0

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