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

package/ds-canonical/hooks/check_chrome_header_handcraft.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+set -uo pipefail
+# Header canonical Layer 3 ChromeHeader consumption enforcement(per header-canonical.spec.md Layer 3):
+#   Production chrome header 必消費 `<ChromeHeader>` primitive,
+#   不可自寫 `h-[var(--chrome-header-height)] border-b border-divider px-loose` 那一套 className。
+#
+# PreToolUse(Edit / Write)hook —— 編輯 `packages/design-system/src/components/**/*.tsx`(非 stories)時掃:
+#   檔內若有完整手刻 chrome header className signature → P1 soft warning(stderr,exit 0)。
+#   Migration 完成後升 P0 BLOCKER(exit 2)。
+#
+# 當前期(2026-05-17 land Phase 2):Sidebar / FileViewer 已 migrate 完,其他元件若新加 chrome
+# header 自刻 = drift,本 hook 攔。
+#
+# Allow escape:檔頭 `// @chrome-header-handcraft-allow: <reason>` 豁免(Tabs cva-on-pattern 等
+# 不適合用 primitive 的 case);本 hook 本身與 ChromeHeader / SurfaceHeader / SidebarHeader.tsx
+# 不攔(那些是 primitive 自己)。
+
+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
+  */packages/design-system/src/components/**/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+# Skip stories
+case "$FILE_PATH" in
+  *.stories.tsx|*.anatomy.stories.tsx|*.principles.stories.tsx) exit 0 ;;
+esac
+
+# Skip primitive home(SidebarHeader 內部消費 ChromeHeader,但仍有 className signature 引用)
+case "$FILE_PATH" in
+  */ChromeHeader/*|*/header-canonical/*|*/overlay-surface/*) exit 0 ;;
+esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  if .tool_input.new_string then .tool_input.new_string
+  elif .tool_input.content then .tool_input.content
+  else "" end
+')
+
+# Allow escape
+if echo "$NEW_CONTENT" | grep -qE '@chrome-header-handcraft-allow:'; then
+  exit 0
+fi
+
+# Detect handcraft signature: h-[var(--chrome-header-height)] paired with border-b border-divider
+HANDCRAFT_HIT=$(echo "$NEW_CONTENT" | grep -cE 'h-\[var\(--chrome-header-height\)\][^"]*border-b[^"]*border-divider' || true)
+
+if [ "$HANDCRAFT_HIT" -gt "0" ]; then
+  printf '⚠️ CHROME HEADER HANDCRAFT(soft P1,Phase 3 將升 P0):\n' >&2
+  printf '   File: %s\n' "$FILE_PATH" >&2
+  printf '   偵測到自刻 `h-[var(--chrome-header-height)] ... border-b border-divider`\n' >&2
+  printf '\n  SSOT: patterns/header-canonical/header-canonical.spec.md Layer 3\n' >&2
+  printf '  修方向: import { ChromeHeader } from "@/design-system/patterns/header-canonical/chrome-header"\n' >&2
+  printf '          替換 <div className="..."> → <ChromeHeader withTabs? lockDensity?>\n' >&2
+  printf '  Escape: 檔頭加 // @chrome-header-handcraft-allow: <rationale>\n' >&2
+fi
+
+exit 0

package/ds-canonical/hooks/check_codex_brief_invariants.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Codex brief invariants enforcement(2026-05-23 永久 per user verbatim「codex 跑的稽核流程理應要跟你跑的深度稽核流程是一模一樣 SSOT 的不能偏移」)
+#
+# PreToolUse(Bash)hook:catch codex exec / cat ... | codex exec / 任何 codex CLI invocation
+# Scan codex brief content for 3 mandatory invariants(per feedback_codex_brief_invariants_2026_05_23.md):
+#   1. 全盤閱讀(全部 source 列舉 or 「DS-wide」「全盤閱讀」「全 N files」 keyword)
+#   2. Triple-verify(「triple-verify」/「三重驗證」/「grep + Read + canonical exception」 keyword)
+#   3. 禁抽樣(「禁抽樣」/「禁 sample」/「NO-SAMPLE」/「DS-wide ALL files」 keyword)
+#
+# 缺任一 → exit 2 BLOCKER(stop codex 啟動)。Escape:brief 含 `// @codex-brief-invariant-skip: <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)
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+case "${TOOL:-}" in
+  Bash) ;;
+  *) exit 0 ;;
+esac
+
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+# Only fire on codex CLI invocations
+if ! echo "$CMD" | grep -qE 'codex[[:space:]]+(exec|review)|node_modules/.bin/codex'; then
+  exit 0
+fi
+
+# Extract brief content — handles `cat /tmp/file | codex exec` OR `codex exec "inline"` patterns
+BRIEF_CONTENT=""
+if echo "$CMD" | grep -qE 'cat[[:space:]]+[^|]+\|[[:space:]]*[^|]*codex'; then
+  # cat-pipe pattern — try reading the cat'd file
+  BRIEF_FILE=$(echo "$CMD" | grep -oE 'cat[[:space:]]+[^[:space:]|]+' | head -1 | sed 's/^cat[[:space:]]*//')
+  if [ -n "$BRIEF_FILE" ] && [ -f "$BRIEF_FILE" ]; then
+    BRIEF_CONTENT=$(cat "$BRIEF_FILE" 2>/dev/null)
+  fi
+fi
+# Inline prompt pattern fallback — grab everything after `codex exec` quotes
+if [ -z "$BRIEF_CONTENT" ]; then
+  BRIEF_CONTENT="$CMD"
+fi
+
+# Escape clause
+if echo "$BRIEF_CONTENT" | grep -qE '@codex-brief-invariant-skip:'; then
+  exit 0
+fi
+
+# Detect 3 invariants
+MISSING=""
+
+# 1. 全盤閱讀 invariant
+if ! echo "$BRIEF_CONTENT" | grep -qiE '全盤閱讀|全部 source|DS-wide ALL|read all files|全部.*spec\.md|全[[:space:]]*[0-9]+[[:space:]]*spec|全[[:space:]]*[0-9]+[[:space:]]*stories|全[[:space:]]*[0-9]+[[:space:]]*components'; then
+  MISSING="${MISSING}  • 1️⃣ 全盤閱讀 invariant 缺(「全盤閱讀全部 source」/「DS-wide ALL files」/「全 N spec.md」keyword)\n"
+fi
+
+# 2. Triple-verify invariant
+if ! echo "$BRIEF_CONTENT" | grep -qiE 'triple-verify|三重驗證|grep.*Read.*canonical|grep DS-wide.*Read.*exception|前必先 inline 跑|再三確認問題|無病呻吟'; then
+  MISSING="${MISSING}  • 2️⃣ Triple-verify invariant 缺(「triple-verify」/「三重驗證」/「禁無病呻吟」keyword)\n"
+fi
+
+# 3. 禁抽樣 invariant
+if ! echo "$BRIEF_CONTENT" | grep -qiE '禁抽樣|禁 sample|NO-SAMPLE|不抽樣|sub-agent.*sampled.*reject|sample.*reject|spot-check.*reject|不應該抽樣'; then
+  MISSING="${MISSING}  • 3️⃣ 禁抽樣 invariant 缺(「禁抽樣」/「NO-SAMPLE」/「sample = reject」keyword)\n"
+fi
+
+if [ -n "$MISSING" ]; then
+  printf '🚨 CODEX BRIEF MISSING INVARIANTS BLOCKER(2026-05-23 user verbatim:「codex 會跑的稽核流程理應要跟你跑的深度稽核流程是一模一樣 SSOT 的不能偏移」):\n' >&2
+  printf '\n  Brief 缺以下 invariant:\n' >&2
+  printf '%b' "$MISSING" >&2
+  printf '\n  Per memory/feedback_codex_brief_invariants_2026_05_23.md + codex-collab/references/brief-template.md:\n' >&2
+  printf '  必含三 invariant 明文(verbatim):\n' >&2
+  printf '    1. 全盤閱讀全部 source(列舉 N files / DS-wide / 禁憑記憶)\n' >&2
+  printf '    2. Triple-verify per finding(grep + Read + canonical exception check)\n' >&2
+  printf '    3. 禁抽樣(DS-wide ALL files / sub-agent sample admission = reject)\n' >&2
+  printf '\n  修方向:brief content 補上三 invariant 文字。\n' >&2
+  printf '  Escape(極罕見): brief 含 `// @codex-brief-invariant-skip: <rationale>`\n' >&2
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_codex_collab_5step.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+set -uo pipefail
+# M31 機械強制:Adversarial dual-track 5-step canonical — claude / codex 每次 collab 必走完整
+# 5-step(各自熟讀 / 各自驗證 / 各自視覺稽核 / cite-based propose / 整合完美版本)。
+#
+# PreToolUse(Bash git commit)hook — 攔截 commit message 含 codex / Layer A / Layer B keyword
+# 但**未同時**含以下 3 必備 marker:
+#   (a) spec.md cite — regex `spec.md:L\d+` OR `spec.md` + 引文 OR `canonical`
+#   (b) verify run — regex `tsc|audit|invariant|visual|playwright|grep verify`
+#   (c) verdict — regex `agree|disagree-with-cite|synthesize|approve|cite battle|counter-cite`
+#
+# Bug 史(2026-05-10):
+#   Issue 8 cell border:codex propose「Field edit border 透明」,Claude pass-through ship,
+#   無 spec cite + 無 verify + 直接 commit → user 強烈糾正「被 codex 牽著走」。M31 universal
+#   mindset 應每題啟動,不只 disagree。Hook 機械強制 commit message 含 3 必備 marker,逼
+#   Claude 跑完整 5-step 才能 commit codex-collab work。
+#
+# Allow escape:
+#   commit message 含 `@codex-collab-allow: <reason>` 整 commit 豁免(緊急 hotfix etc)
+#
+# Soft warning(P1):exit 0 但 stderr 印警告 — 不 block commit(因 commit message 自由 draft,
+# false-positive 太高 hard-block 會困住)。但 stop hook + session start hook 會撈 fire log
+# 後續 raise 為 BLOCKER。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+
+# Only Bash tool with git commit
+case "$TOOL" in
+  Bash) ;;
+  *) exit 0 ;;
+esac
+
+# Match git commit -m with HEREDOC or inline message
+if ! echo "$COMMAND" | grep -qE 'git commit'; then
+  exit 0
+fi
+
+# Extract commit message text(rough — supports HEREDOC `<<'EOF' ... EOF` + inline -m '...')
+# HEREDOC pattern:`cat <<'EOF'` ... `EOF`
+MSG=$(echo "$COMMAND" | sed -nE "s/.*-m \"(.*)\"$/\\1/p; /cat <<'?EOF'?/,/^EOF$/p" 2>/dev/null || true)
+# Fallback:整個 command string(若 HEREDOC parse 失敗)
+if [ -z "$MSG" ]; then
+  MSG="$COMMAND"
+fi
+
+# Allow escape
+if echo "$MSG" | grep -qE '@codex-collab-allow:'; then
+  exit 0
+fi
+
+# Trigger check:does message mention codex collab?
+TRIGGER_REGEX='codex|Layer A own|Layer B codex|dual-track|據理力爭|据理力爭|cite battle'
+if ! echo "$MSG" | grep -qE "$TRIGGER_REGEX"; then
+  # Not a codex-collab commit — skip
+  exit 0
+fi
+
+# Required markers
+MISSING=()
+
+# (a) spec cite
+SPEC_CITE_REGEX='spec\.md[:L0-9]|spec\.md.*L[0-9]|canonical[ 的引文]|RFC.*L[0-9]'
+if ! echo "$MSG" | grep -qE "$SPEC_CITE_REGEX"; then
+  MISSING+=("spec.md cite(規格 path:line / 引文)")
+fi
+
+# (b) verify
+VERIFY_REGEX='tsc|audit|invariant|visual|playwright|grep verify|grep .*confirm'
+if ! echo "$MSG" | grep -qiE "$VERIFY_REGEX"; then
+  MISSING+=("verify run(tsc / audit / invariant / visual / playwright)")
+fi
+
+# (c) verdict keyword
+VERDICT_REGEX='agree|disagree-with-cite|disagree.*cite|approve|synthesize|cite battle|counter-cite|verdict'
+if ! echo "$MSG" | grep -qiE "$VERDICT_REGEX"; then
+  MISSING+=("verdict keyword(agree / disagree-with-cite / synthesize)")
+fi
+
+if [ ${#MISSING[@]} -eq 0 ]; then
+  exit 0
+fi
+
+# Soft warning(stderr only,exit 0 — 不 block 因 false-positive 風險)
+echo "⚠️  M31 codex-collab 5-step canonical 違反(P1 soft warn):" >&2
+echo "   Commit 含 codex collab keyword 但缺以下 marker:" >&2
+for m in "${MISSING[@]}"; do
+  echo "   ✗ $m" >&2
+done
+echo "" >&2
+echo "   M31 universal mindset:每次 codex collab 都該完整 5-step:" >&2
+echo "     (1) 各自熟讀 spec.md / canonical" >&2
+echo "     (2) 各自驗證 tsc / audit / playwright" >&2
+echo "     (3) 各自視覺稽核 screenshot / DOM" >&2
+echo "     (4) 各自 cite-based propose" >&2
+echo "     (5) 整合完美版本(not pass-through)" >&2
+echo "" >&2
+echo "   Commit message 補 cite + verify + verdict marker 再 commit。" >&2
+echo "   或加 \`@codex-collab-allow: <reason>\` 緊急豁免。" >&2
+echo "   詳 .claude/rules/meta-patterns.md M31 + .claude/skills/codex-collab/SKILL.md" >&2
+
+# Soft warning — exit 0,不 block(per M31 hook design note)
+exit 0

package/ds-canonical/hooks/check_datatable_invariants.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# DataTable unified invariant hook(2026-05-08 cluster B consolidation)
+#
+# Merges 3 DataTable hooks(原各檔已 retire,合併入此):
+#   B.1 row drag getRowId(原 check_data_table_row_drag_get_row_id,P2 stderr)
+#   B.2 column size NUMBER → meta.width(原 check_data_table_size_num_to_meta_width,P2 stderr)
+#   B.3 filter↔sort sibling sync reminder(原 check_data_table_sort_parallel,P2 reminder)
+#
+# Why merge:皆 DataTable-family invariant,共用 INPUT parsing + tsx filter pattern。
+# 散裝是 M17 SSOT 違反 + Anthropic ≤ 15 hook best-practice 偏離。
+#
+# 全 3 sub-rules 都是 P2 stderr-only(原檔皆 exit 0),所以本 hook 統一 exit 0。
+# 同時掛 PreToolUse + PostToolUse OK(reminder 性質,雙 event fire 不 break 任何流程,
+# 但本實作 settings.json 只 register PreToolUse 避免 fire 重複)。
+
+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
+
+case "$FILE_PATH" in
+  *.tsx) ;;
+  *) exit 0 ;;
+esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""')
+
+# ── B.1 row drag getRowId(P2 stderr)─────────────────────────────────────────
+# Skip DataTable internal source(本身 implement enableRowDrag)
+case "$FILE_PATH" in
+  */data-table.tsx|*/data-table.spec.md) ;; # skip B.1 + B.2 internal
+  *)
+    if echo "$NEW_CONTENT" | grep -q "enableRowDrag"; then
+      EXISTING=""
+      [ -f "$FILE_PATH" ] && EXISTING=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+      COMBINED="$EXISTING
+$NEW_CONTENT"
+      if ! echo "$COMBINED" | grep -q "getRowId"; then
+        cat >&2 <<EOF
+
+┄┄┄ B.1 check_datatable_invariants — row drag getRowId WARN ┄┄┄
+
+[P2] ${FILE_PATH}
+使用 enableRowDrag 但 file 內無 getRowId — dnd 會退化用 row.index 導致 reorder 錯位。
+詳 data-table.spec.md「L4 Row drag 必填 getRowId」段。
+
+EOF
+      fi
+    fi
+    ;;
+esac
+
+# ── B.2 column size NUMBER → meta.width(P2 stderr)────────────────────────────
+case "$FILE_PATH" in
+  */data-table.tsx|*/cell-registry.tsx|*/column-types.ts) ;; # skip DS internal
+  *)
+    if echo "$NEW_CONTENT" | grep -qE "accessor[Key]?|createColumnHelper"; then
+      HITS=$(echo "$NEW_CONTENT" | grep -nE "size:\s*[0-9]+" | grep -v "size:\s*['\"]" || true)
+      if [ -n "$HITS" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ B.2 check_datatable_invariants — column size NUMBER WARN ┄┄┄
+
+[P2] ${FILE_PATH}
+DataTable column def 用 root \`size: NUMBER\`(TanStack 慣例)。
+DS canonical 走 \`meta.width\`(2026-05-06 v14.3,M23 命名衝突修)。
+
+修法:
+  before: { accessorKey: 'name', size: 240, meta: { type: 'string' } }
+  after:  { accessorKey: 'name', meta: { type: 'string', width: 240 } }
+
+命中 lines:
+$(echo "$HITS" | sed 's/^/  /')
+
+詳 data-table.spec.md「六之二、Column 寬度 API」。
+
+EOF
+      fi
+    fi
+    ;;
+esac
+
+# ── B.3 filter↔sort sibling sync reminder(P2 reminder)────────────────────────
+case "$FILE_PATH" in
+  *data-table-filter-panel.tsx)
+    cat >&2 <<EOF
+
+┄┄┄ B.3 check_datatable_invariants — sibling sync reminder ┄┄┄
+
+[P2] 動到 filter panel → 是否需要對應修 data-table-sort-manager.tsx?
+Self-check:row gap / row layout / row meta button / chrome corner action /
+empty state 行為 / CTA button variant — sort row 是否同步?
+
+EOF
+    ;;
+  *data-table-sort-manager.tsx)
+    cat >&2 <<EOF
+
+┄┄┄ B.3 check_datatable_invariants — sibling sync reminder ┄┄┄
+
+[P2] 動到 sort manager → 是否需要對應修 data-table-filter-panel.tsx?
+Self-check:row gap / row layout / row meta button / chrome corner action /
+empty state 行為 / CTA button variant — filter row 是否同步?
+
+EOF
+    ;;
+esac
+
+exit 0

package/ds-canonical/hooks/check_dim_count_drift.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: enforce audit dim count SSOT integrity.
+#
+# SSOT: `.claude/skills/design-system-audit/SKILL.md` `## The N audit dimensions` 段。
+# 任何 chain it 的 skill / spec / rule / hook 禁 hardcode 具體 dim 數字
+# (e.g. `46 dim` / `53 dim` / `53-dim` / `53 audit dimensions`)— 用「全 dim」/
+# 「Group A-P」/「per design-system-audit SSOT」表達。
+#
+# Why: 2026-05-18 user-mandated SSOT integrity after `deep-audit-cross-codex` skill
+# hardcode `53 dim` 9 處 → 若 design-system-audit 升 54 dim,chain skill 漂移。
+#
+# P1 soft warn (stderr exit 0) — Claude decides revert or escape with rationale.
+# SSOT file itself (design-system-audit/SKILL.md) is allowed to write the count.
+
+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
+
+# Skip the SSOT itself
+case "$FILE_PATH" in
+  */design-system-audit/SKILL.md) exit 0 ;;
+  */design-system-audit/references/*) exit 0 ;;
+esac
+
+# Only check files that potentially chain audit dim list
+case "$FILE_PATH" in
+  */deep-audit-cross-codex/*|*/rules/meta-patterns.md|*/CLAUDE.md|*/skills/*/SKILL.md|*/skills/*/references/*) ;;
+  *) 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
+
+# Detect hardcoded numeric dim count
+# Patterns: "53 dim" / "53-dim" / "53 audit dim" / "53 audit dimensions" / "46 dim" / "46-dim"
+# Exclude legitimate uses: "N dim" / "全 dim" / "<N>" placeholder / "1 dim" thru "9 dim" (could be reasonable refs)
+HARDCODE_HITS=$(echo "$NEW_CONTENT" | grep -oE '\b[1-9][0-9]+[ -]?(dim|audit dim|audit dimension)' | sort -u || true)
+
+# Allow if line contains "SSOT" / "禁" / "forbidden" / "example" / "anti-pattern" — these are invariant doc references
+ALLOWED_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b[1-9][0-9]+[ -]?(dim|audit dim|audit dimension)' 2>/dev/null | grep -E '(SSOT|禁|forbidden|example|anti-pattern|invariant|hardcode)' || true)
+
+if [ -n "$HARDCODE_HITS" ]; then
+  # Filter out allowed lines (invariant doc context)
+  VIOLATION_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b[1-9][0-9]+[ -]?(dim|audit dim|audit dimension)' 2>/dev/null | grep -vE '(SSOT|禁|forbidden|example|anti-pattern|invariant|hardcode)' || true)
+
+  if [ -n "$VIOLATION_LINES" ]; then
+    printf '⚠️ AUDIT DIM COUNT DRIFT(P1 soft):\n' >&2
+    printf '   File: %s\n' "$FILE_PATH" >&2
+    printf '   偵測到 hardcoded audit dim count:\n%s\n' "$VIOLATION_LINES" >&2
+    printf '\n  SSOT: `.claude/skills/design-system-audit/SKILL.md` `## The N audit dimensions`\n' >&2
+    printf '  修法: 改用「全 dim」/「Group A-P」/「per design-system-audit SSOT」表達\n' >&2
+    printf '       而非寫死「53 dim / 46 dim」等具體數字。\n' >&2
+    printf '  Why: chain skill 自動繼承 SSOT 變動,避免 design-system-audit 升 54 dim 時下游漂移。\n' >&2
+  fi
+fi
+
+exit 0

package/ds-canonical/hooks/check_field_controls_contracts.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# check_field_controls_contracts.sh — Stream C shared contracts(a)(b)(c) consolidated guardrail
+#
+# 2026-05-13 prune consolidation(per knowledge-prune Phase 2 P1):3 hook 合 1:
+#   - 原 check_field_placeholder_vocabulary.sh — contract (b)
+#   - 原 check_selected_renderer_symmetry.sh — contract (a)
+#   - 原 check_cell_metric_escape_hatches.sh — contract (c)
+# 同 PostToolUse Edit/Write target(Field family packages/design-system/src/components/*.tsx),
+# 合 1 hook 減少 hook count 從 27 → 25 回 soft cap 內,單一 entry settings.json。
+# 對齊 field-controls.spec.md 共享 contract (a) Selected value renderer / (b) Placeholder vocabulary /
+# (c) Cell surface metrics 3 段 canonical。
+
+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)
+
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+[ "$EVENT" != "PostToolUse" ] && exit 0
+[ ! -f "$FILE_PATH" ] && exit 0
+
+VIOLATIONS=""
+
+# ── Contract (b) Placeholder vocabulary ───────────────────────────────────────
+# Scope: 所有 packages/design-system/src/components/*.tsx
+case "$FILE_PATH" in
+  */packages/design-system/src/components/*.tsx)
+    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@placeholder-vocabulary-allow:'; then
+      HITS=$(grep -nE 'emptyPlaceholder=\{(emptyText|searchEmpty|noResults|notFound)' "$FILE_PATH" 2>/dev/null)
+      if [ -n "$HITS" ]; then
+        VIOLATIONS="${VIOLATIONS}
+[contract (b) placeholder vocabulary]:
+${HITS}
+  → 違反 field-controls.spec.md「共享 contract (b)」:不可 silent 把 emptyText forward 成 emptyPlaceholder(trigger-empty)。
+  Fix:wrapper 加 \`placeholder\` prop(trigger empty SSOT)+ \`emptyText\` 僅傳 SelectMenu noResultsText。
+  Allow:檔首加 \`// @placeholder-vocabulary-allow: <reason>\`。"
+      fi
+    fi
+    ;;
+esac
+
+# ── Contract (a) Selected value renderer symmetry ─────────────────────────────
+# Scope:Combobox / Select / PeoplePicker only
+case "$FILE_PATH" in
+  */packages/design-system/src/components/Combobox/*.tsx|*/packages/design-system/src/components/Select/*.tsx|*/packages/design-system/src/components/PeoplePicker/*.tsx)
+    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@renderer-symmetry-allow:'; then
+      DEFINES_RENDERER=$(grep -cE '(tagRenderer|selectedItemRenderer)\?:\s*\(' "$FILE_PATH" 2>/dev/null || echo 0)
+      DEFINES_RENDERER=${DEFINES_RENDERER:-0}
+      if [ "$DEFINES_RENDERER" -gt 0 ]; then
+        EDIT_HITS=$(grep -cE 'tagRenderer\(.*\)|selectedItemRenderer\(.*\)' "$FILE_PATH" 2>/dev/null || echo 0)
+        EDIT_HITS=${EDIT_HITS:-0}
+        DISPLAY_LINES=$(grep -nE "mode\s*=*\s*'display'|resolvedMode\s*==*\s*'display'" "$FILE_PATH" 2>/dev/null | cut -d: -f1)
+        if [ "$EDIT_HITS" -gt 0 ] && [ -n "$DISPLAY_LINES" ]; then
+          HAS_RENDERER_IN_DISPLAY=0
+          for LN in $DISPLAY_LINES; do
+            END=$((LN + 60))
+            if awk -v s="$LN" -v e="$END" 'NR>=s && NR<=e' "$FILE_PATH" | grep -qE 'tagRenderer|selectedItemRenderer'; then
+              HAS_RENDERER_IN_DISPLAY=1
+              break
+            fi
+          done
+          if [ "$HAS_RENDERER_IN_DISPLAY" -eq 0 ]; then
+            VIOLATIONS="${VIOLATIONS}
+[contract (a) renderer symmetry]:
+${FILE_PATH}
+  → tagRenderer/selectedItemRenderer 定義於 props 但 display branch 沒消費 → edit-only。
+  違反 field-controls.spec.md「共享 contract (a)」:rich-display renderer 必被 display/readonly/disabled/edit 4 mode 共享。
+  Allow:檔首加 \`// @renderer-symmetry-allow: <reason>\`。"
+          fi
+        fi
+      fi
+    fi
+    ;;
+esac
+
+# ── Contract (c) Cell metric escape hatches ───────────────────────────────────
+# Scope:Combobox / Select / PeoplePicker only
+case "$FILE_PATH" in
+  */packages/design-system/src/components/Combobox/*.tsx|*/packages/design-system/src/components/PeoplePicker/*.tsx|*/packages/design-system/src/components/Select/*.tsx)
+    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@cell-metric-escape-allow:'; then
+      HARDCODE_HITS=$(grep -nE 'tagAreaPaddingLeftPx=\{[0-9]+\}' "$FILE_PATH" 2>/dev/null)
+      COND_NO_SURFACE=$(grep -nE 'tagAreaPaddingLeftPx=\{[^}]*\?[^}]*[0-9]+[^}]*\}' "$FILE_PATH" 2>/dev/null | grep -v "surface")
+      WARN=""
+      [ -n "$HARDCODE_HITS" ] && WARN="${WARN}
+[hardcode numeric without surface guard]:
+${HARDCODE_HITS}"
+      [ -n "$COND_NO_SURFACE" ] && WARN="${WARN}
+[conditional without surface check]:
+${COND_NO_SURFACE}"
+      if [ -n "$WARN" ]; then
+        VIOLATIONS="${VIOLATIONS}
+[contract (c) cell metric escape hatch]:
+${FILE_PATH}${WARN}
+  → 違反 field-controls.spec.md「共享 contract (c)」:cell 內禁 hardcode padding magic,改 \`useFieldSurface()\` + \`--table-cell-px\` 推導。
+  Fix pattern: tagAreaPaddingLeftPx={(!isEmpty && surface === 'form') ? 8 : undefined}
+  Allow:檔首加 \`// @cell-metric-escape-allow: <reason>\`。"
+      fi
+    fi
+    ;;
+esac
+
+if [ -n "$VIOLATIONS" ]; then
+  CTX="⚠️ Field controls shared contracts violation(consolidated check):${VIOLATIONS}"
+  jq -n --arg ctx "$CTX" '{
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+  }'
+fi