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

package/ds-canonical/hooks/check_benchmark_citation.sh

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

package/ds-canonical/hooks/check_canonical_propagation.sh

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

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