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

package/ds-canonical/hooks/check_propose_plain_chinese.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# check_propose_plain_chinese.sh — Stop hook: scan AI 本 turn reply 含「要 user 決策」pattern 但用 jargon 違 propose-in-plain-chinese canonical。
+#
+# 對應 SSOT:.claude/memory/feedback_propose_in_plain_chinese.md
+#         + CLAUDE.md `# 自主執行 canonical`「SSOT-UI/UX 中文具體人話」明文
+#
+# User 原話 2026-05-15:「已經跟你說過任何要我決策的東西請講具體人話,為何又跟智障一樣講人聽不懂的話呢?」
+#
+# Mechanism:
+# 1. Tail transcript 取 AI 本 turn 最後 assistant text content
+# 2. Detect 決策 prompt pattern(「回 A / B / C」/「→ 選 A」/「等你拍板」/「user 決策」)
+# 3. Count jargon density(「M[0-9]+」/「Dim [0-9]+」/「SSOT」/「@watch」/「frontmatter」/「stub」/etc)
+# 4. Density > threshold + 含決策 prompt → warn(P1 soft inject)
+#
+# 不 BLOCK turn,只 inject context warning(避免 false-positive 中斷 work)
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+
+[ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ] && exit 0
+
+# 找最新 user msg line 之後的 assistant text(本 turn AI reply)
+LAST_USER_LINE=$(grep -n '"role":"user"' "$TRANSCRIPT_PATH" 2>/dev/null | tail -1 | cut -d: -f1)
+[ -z "$LAST_USER_LINE" ] && exit 0
+
+AI_REPLY_TEXT=$(tail -n +$((LAST_USER_LINE+1)) "$TRANSCRIPT_PATH" 2>/dev/null | \
+  jq -r 'select(.message.role=="assistant") | .message.content // empty | if type=="string" then . else (.[]? | select(.type=="text") | .text // empty) end' 2>/dev/null)
+
+[ -z "$AI_REPLY_TEXT" ] && exit 0
+
+# Decision prompt pattern(reply 結尾含 ASK)
+DECISION_RE='(回 [A-Z]|→ ?選 [A-Z]|等你(拍板|決策|回|看)|user 決策|user 拍板|拍板.{0,5}決|決策.{0,5}選|一字回|回 OK)'
+HAS_DECISION=$(echo "$AI_REPLY_TEXT" | grep -cE "$DECISION_RE" 2>/dev/null)
+HAS_DECISION=${HAS_DECISION:-0}
+
+[ "$HAS_DECISION" -eq 0 ] && exit 0
+
+# GAP 4 fix(2026-05-18 M34 codify):升級 narrow 17-keyword fixed list 到
+# Python unicode 中英夾雜 density detector(對齊 check_story_invariants.sh R5.5 fix template)。
+# Spec wording「任何沒中譯的縮寫 / 內部代號 / hook 名」廣義,hook 過去窄 keyword list 漏:
+# Earn-existence / compound-component / Polaris-aligned / wrapper-vs-primitive / Anchor preflight
+# / *-canonical-allow / L42-58 / check_xxx.sh 等。
+#
+# 升級邏輯:
+# (a) EXEMPT list:legitimate retained-English(framework/brand/DS API)
+# (b) Density measure:jargon-word count / total Chinese-char count ratio
+# (c) jargon = 英文 token 不在 EXEMPT(任何 alphanumeric word ≥ 3 char)
+JARGON_COUNT=$(python3 -c "
+import re, sys
+text = sys.stdin.read()
+EXEMPT = re.compile(r'\b(cva|Radix|Polaris|Material|Atlassian|Carbon|Ant|Apple|MUI|TanStack|shadcn|Recharts|cmdk|dnd-kit|TypeScript|JavaScript|API|UI|UX|Jira|Stripe|Notion|Figma|Linear|GitHub|Gmail|Dropbox|Slack|Spotify|Discord|Storybook|Tailwind|ARIA|WCAG|FAQ|HSL|CSS|HTML|DOM|DS|F[1-9]|TODO|FIXME|XXX|NOTE|README|MIT|JSON|YAML|TSX|CSS|HTTP|HTTPS|URL|UUID|REST|GraphQL|SDK|CDN|CI|CD|PR|RFC|MR|UI/UX|primary|secondary|tertiary|hover|focus|active|disabled|invalid|readonly|null|true|false|undefined|void)\b', re.I)
+words = re.findall(r'\b[a-zA-Z][a-zA-Z\-_]{2,}\b', text)
+jargon = [w for w in words if not EXEMPT.fullmatch(w)]
+print(len(jargon))
+" <<< "$AI_REPLY_TEXT" 2>/dev/null)
+JARGON_COUNT=${JARGON_COUNT:-0}
+
+# Threshold:含決策 prompt + jargon count ≥ 10 → warn(Python 計數較廣,threshold 提高)
+THRESHOLD=10
+
+if [ "$JARGON_COUNT" -ge "$THRESHOLD" ]; then
+  echo "🟡 check_propose_plain_chinese WARN:本 turn reply 含 user 決策 prompt + jargon 密度 ${JARGON_COUNT}(threshold ${THRESHOLD})" >&2
+  echo "" >&2
+  echo "→ 違反 propose-in-plain-chinese canonical(memory/feedback_propose_in_plain_chinese.md SSOT)" >&2
+  echo "→ User 原話「請講具體人話,為何又跟智障一樣講人聽不懂的話」" >&2
+  echo "→ Rewrite reply:必含 3 段(發生什麼 / 影響什麼 / 各選項 outcome — 全中文具體,禁 jargon)" >&2
+  echo "" >&2
+  # Soft warn,不 BLOCK turn(exit 0)— 讓 AI 看到 stderr 後 self-correct
+fi
+
+exit 0

package/ds-canonical/hooks/check_propose_pre_grep_verify.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: enforce M18 Q0「Pre-ASK self-verify problem 真存在」.
+#
+# 2026-05-18 user-mandated codify after Sheet/inline-action/SurfaceBody 三題誤判事件:
+# Claude propose 給 user 拍板前必先 grep DS-wide + Read 相關 spec.md 確認 problem 真存在,
+# 沒 grep 就斷言「N 元件缺 X / 該 migrate」= 撤回 propose。
+#
+# Detection:Edit/Write content 含「propose / 請拍板 / 等你拍板 / 待你拍板 /
+# 決策 N / 我推 A/B/C / 選項」keywords,**但 content 內無 file:line cite 證據**
+# → P1 warn(stderr exit 0,Claude 自決撤回 OR 在 reply 補 cite)。
+#
+# SSOT: `.claude/skills/propose-options/SKILL.md` Q0 段 + meta-patterns.md M18。
+
+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 fires on planning docs / commit-style summaries / reply-style markdown
+# (避 false positive on production code / 一般 spec edit)
+case "$FILE_PATH" in
+  */planning/*.md|*/reports/*.md|*/handoff/*.md) ;;
+  *) 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 propose keywords
+HAS_PROPOSE=$(echo "$NEW_CONTENT" | grep -cE '(請拍板|等你拍板|待你拍板|決策 [0-9N]|我推 [ABC]|選項[::]|propose for user|你決定|讓我判斷決策)' || true)
+
+[ "$HAS_PROPOSE" = "0" ] && exit 0
+
+# Allowed escape:檔頭 `<!-- @propose-pre-verified -->` 例外
+if echo "$NEW_CONTENT" | head -3 | grep -qE '@propose-pre-verified'; then
+  exit 0
+fi
+
+# Check for file:line cite evidence
+HAS_CITE=$(echo "$NEW_CONTENT" | grep -cE '`[a-z][a-z0-9/-]+\.(tsx|ts|css|md):[0-9]+`|`[a-z][a-z0-9/-]+\.(tsx|ts|css|md)`|`packages/design-system/src/' || true)
+
+if [ "$HAS_CITE" = "0" ]; then
+  printf '⚠️ PRE-ASK SELF-VERIFY GAP(M18 Q0,P1 soft):\n' >&2
+  printf '   File: %s\n' "$FILE_PATH" >&2
+  printf '   偵測到 propose 給 user 拍板 keyword,但 content 無 file:line cite 證據。\n' >&2
+  printf '\n  M18 Q0 強制檢查:\n' >&2
+  printf '   1. grep 既有 code DS-wide 確認 problem 真存在 (file:line)\n' >&2
+  printf '   2. Read 相關 spec.md 找 canonical cite\n' >&2
+  printf '   3. Read consumer usage 確認該 pattern 已在 N 處 work fine\n' >&2
+  printf '   4. propose 給 user 前列具體 file:line 證據\n' >&2
+  printf '\n  錨例:2026-05-18 Sheet/inline-action/SurfaceBody 三題誤判 propose 浪費 user 時間\n' >&2
+  printf '  SSOT: .claude/skills/propose-options/SKILL.md Q0 段\n' >&2
+  printf '  Escape: 檔頭加 <!-- @propose-pre-verified --> 若已 verify(rationale 必明示)\n' >&2
+fi
+
+exit 0

package/ds-canonical/hooks/check_select_all_canonical.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: Select All ordering SSOT drift guard(2026-05-16 user verbatim
+# 「以後遇到此類設計都有相同邏輯不會偏移」)
+#
+# 攔截 packages/design-system/src/** edit 時,如果新內容含「Select All」 / 「checkAll」 / 「全選」 等 bulk-select
+# 動作 + 自寫 ordering logic(`onValueChange?.(options.map(...))` / `[...prev, ...]` 等),
+# 要求消費 `@/design-system/lib/multi-select-ordering` SSOT primitive 而非自刻。
+#
+# 規則 SSOT:`packages/design-system/src/lib/multi-select-ordering.ts`(applySelectAll / clearSelection)。
+# 對應 Ant Transfer + Table rowSelection canonical(Layer A + Codex M31 Round 4 共識)。
+#
+# Soft warn(stderr,non-blocking)— 給開發者警示但不擋 ship。Edge case 真需自刻 → 在
+# new content 加 `// @select-all-canonical-allow: <reason>` allowlist escape。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')
+
+[ -z "$FILE_PATH" ] && exit 0
+[[ "$TOOL" != "Edit" && "$TOOL" != "Write" ]] && exit 0
+[[ "$FILE_PATH" != *packages/design-system/src/* ]] && exit 0
+# 本 SSOT primitive 檔自己不查
+[[ "$FILE_PATH" == *multi-select-ordering.ts ]] && exit 0
+# Allowlist
+echo "$NEW_CONTENT" | grep -q "@select-all-canonical-allow" && exit 0
+
+# Detect Select-All-like pattern:
+#   - function name contains SelectAll / CheckAll
+#   - `[...prev`-style append with `options.map`-style source values
+#   - 顯式「全部」 button click → onValueChange
+HAS_SELECTALL_HANDLER=$(echo "$NEW_CONTENT" | grep -cE "(handleSelectAll|onSelectAll|onCheckAll|handleCheckAll|全選|checkAll\s*=|selectAll\s*=)" || true)
+
+if [ "$HAS_SELECTALL_HANDLER" -gt 0 ]; then
+  USES_SSOT=$(echo "$NEW_CONTENT" | grep -cE "(applySelectAll|multi-select-ordering)" || true)
+  if [ "$USES_SSOT" -eq 0 ]; then
+    cat >&2 <<EOF
+⚠️  Select All ordering SSOT drift warning
+File: $FILE_PATH
+
+偵測「Select All」/「checkAll」/「全選」 handler 但無 import \`applySelectAll\` from
+\`@/design-system/lib/multi-select-ordering\`。
+
+SSOT canonical(per Ant Transfer + Table rowSelection,Layer A + Codex M31 Round 4 共識):
+  preserve existing user click order + append unselected options in source order(dedup)
+  → \`applySelectAll(selectedValues, allOptionValues)\`
+
+若刻意自刻 → 加 \`// @select-all-canonical-allow: <reason>\` 在 new content 中。
+EOF
+  fi
+fi
+
+exit 0

package/ds-canonical/hooks/check_solo_workflow.sh

@@ -0,0 +1,258 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse hook: enforce solo-work canonical (M28)
+# SSOT: .claude/memory/feedback_solo_dev_workflow.md + CLAUDE.md # Git solo-work canonical
+#
+# Blocks 3 violations:
+#   R1. `git checkout -b claude/*` 第 2+ 次 in same session
+#       (1 chat = 1 working branch — even after merge,reuse 同 branch name)
+#   R2. PR creation (Bash gh / mcp__github__create_pull_request)
+#       (solo work = no PR ceremony)
+#   R3. Push to main / merge PR without recent user "push" trigger keyword
+#       (AI 不自決 push main,等 user 「push / OK / 好 / 合 main」 trigger)
+#
+# Override: CLAUDE_BYPASS_SOLO_WORKFLOW=1 (audit-logged to .claude/logs/solo-workflow-bypass.jsonl)
+#
+# 違反歷史:本 hook 2026-05-08 codified — 同 session AI 開 5 個 branch + 2 PR
+# 後 user 第 3 次糾正才升 mechanical (markdown rule + memory file 都不夠)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+# SSOT approval regex(M17 + M34 + GAP 6 codify 2026-05-18)
+source "$(dirname "$0")/lib/_approval_re.sh"
+
+set -uo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+TRACK_FILE="$PROJECT_DIR/.claude/logs/session-branch-track.jsonl"
+BYPASS_LOG="$PROJECT_DIR/.claude/logs/solo-workflow-bypass.jsonl"
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+
+# === Override flag ===
+if [ "${CLAUDE_BYPASS_SOLO_WORKFLOW:-0}" = "1" ]; then
+  mkdir -p "$(dirname "$BYPASS_LOG")"
+  printf '{"ts":"%s","tool":"%s","session":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$TOOL_NAME" "$SESSION_ID" >> "$BYPASS_LOG"
+  exit 0
+fi
+
+# Helper: scan recent user messages for "push" trigger keywords
+has_push_trigger() {
+  [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ] && return 1
+  # Transcript JSONL schema:每 line 一 message。real user text msg = `type:"user"` AND
+  # `message.role:"user"` AND `message.content` is STRING(tool_results 的 content 是 array)。
+  jq -r 'select(.type=="user" and .message.role=="user" and (.message.content | type == "string")) | .message.content' \
+    "$TRANSCRIPT" 2>/dev/null \
+    | tail -10 \
+    | grep -qE "$APPROVAL_KEYWORD_RE"
+}
+
+# Helper: shell-aware token detect — git checkout -b claude/X(quoted-string-safe)
+# 用 shlex 真 tokenize bash command,echo "git checkout -b claude/foo" 這類
+# quoted text 內的「git checkout -b」是單一 token(arg)不會誤判為新 command。
+detect_git_checkout_b_claude() {
+  python3 -c "
+import shlex, sys
+try:
+    tokens = shlex.split(sys.stdin.read(), comments=True)
+except Exception:
+    sys.exit(1)
+for i in range(len(tokens) - 3):
+    if tokens[i] == 'git' and tokens[i+1] == 'checkout' and tokens[i+2] == '-b' and tokens[i+3].startswith('claude/'):
+        print(tokens[i+3])
+        sys.exit(0)
+sys.exit(1)
+" 2>/dev/null
+}
+
+# Helper: shell-aware push to main detect
+detect_push_main() {
+  python3 -c "
+import shlex, sys
+try:
+    tokens = shlex.split(sys.stdin.read(), comments=True)
+except Exception:
+    sys.exit(1)
+for i in range(len(tokens) - 2):
+    # git push origin main / git push origin xxx:main / git push HEAD:main
+    if tokens[i] == 'git' and tokens[i+1] == 'push':
+        # Look for 'main' or 'X:main' as ref arg
+        for j in range(i+2, min(i+6, len(tokens))):
+            t = tokens[j]
+            if t == 'main' or t.endswith(':main') or t.endswith(' main'):
+                sys.exit(0)
+sys.exit(1)
+" 2>/dev/null
+}
+
+# Helper: shell-aware gh pr create / gh api pulls **WRITE** detect
+# 2026-05-09 fix(user-authorized):區分 read(default GET)vs write(POST/PATCH/PUT/DELETE)。
+# `gh api repos/.../pulls/N/comments` 預設 GET = read,**不** block;
+# `gh api -X POST repos/.../pulls`(or `-f`/`-F` field flags 暗示 POST)= 真 PR write 才 block。
+# Why:read-only API(check codex reply / read PR meta)是合法 collab,不該被 R2 PR-create 規則攔。
+detect_gh_pr_create() {
+  python3 -c "
+import shlex, sys
+try:
+    tokens = shlex.split(sys.stdin.read(), comments=True)
+except Exception:
+    sys.exit(1)
+WRITE_METHODS = {'POST', 'PATCH', 'PUT', 'DELETE'}
+for i in range(len(tokens) - 2):
+    if tokens[i] == 'gh':
+        # gh pr create — always block(create 本身是 write)
+        if tokens[i+1] == 'pr' and tokens[i+2] == 'create':
+            sys.exit(0)
+        # gh api ... pulls ... — only block if write method OR form fields(-f/-F = POST default)
+        if tokens[i+1] == 'api':
+            cmd_tokens = tokens[i:]
+            has_pulls = any('pulls' in t for t in cmd_tokens[:8])
+            if not has_pulls:
+                continue
+            # Detect explicit write method
+            for k in range(len(cmd_tokens)):
+                t = cmd_tokens[k]
+                if t in ('-X', '--method') and k + 1 < len(cmd_tokens):
+                    if cmd_tokens[k+1].upper() in WRITE_METHODS:
+                        sys.exit(0)
+                if t.startswith('--method=') and t.split('=', 1)[1].upper() in WRITE_METHODS:
+                    sys.exit(0)
+                # -f / -F flags imply POST(form fields)
+                if t in ('-f', '-F'):
+                    sys.exit(0)
+            # GET(default)= read,allow through
+sys.exit(1)
+" 2>/dev/null
+}
+
+if [ "$TOOL_NAME" = "Bash" ]; then
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+  # === Rule 1: git checkout -b claude/* — 1 session = 1 branch ===
+  # Use shlex tokenizer (quoted-string-safe) — echo "git checkout -b ..." 不誤判
+  NEW_BRANCH=$(echo "$COMMAND" | detect_git_checkout_b_claude)
+  if [ -n "$NEW_BRANCH" ]; then
+
+    if [ -f "$TRACK_FILE" ] && [ -n "$SESSION_ID" ]; then
+      EXISTING=$(jq -r --arg s "$SESSION_ID" 'select(.session_id == $s) | .branch' "$TRACK_FILE" 2>/dev/null | head -1)
+      if [ -n "$EXISTING" ] && [ "$EXISTING" != "null" ] && [ "$EXISTING" != "$NEW_BRANCH" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ check_solo_workflow — R1 BLOCKER (M28) ┄┄┄
+
+[P0 BLOCKER] git checkout -b $NEW_BRANCH
+
+本 session ($SESSION_ID) 已有 working branch:
+  → $EXISTING
+
+❌ 1 session = 1 working branch (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
+   即使既有 branch 已 merged + deleted,本 session 內**不再開新 branch**。
+
+修法:
+  1. 重用既有 branch:
+       git checkout $EXISTING
+     (若 local 已 -d 刪除,recreate from main:)
+       git checkout main && git checkout -b $EXISTING
+  2. 或 doc-only / governance-only 改 → commit 直接 main(無 Netlify preview 需求)
+  3. 例外 override:CLAUDE_BYPASS_SOLO_WORKFLOW=1 (audit logged)
+
+違反史:本 session 已開 5 branch + 2 PR,M13 trigger 升 hook 防線。
+EOF
+        exit 2
+      fi
+    fi
+
+    # Record new session branch (first creation OK)
+    if [ -n "$SESSION_ID" ] && [ -n "$NEW_BRANCH" ]; then
+      mkdir -p "$(dirname "$TRACK_FILE")"
+      printf '{"session_id":"%s","branch":"%s","created_at":"%s"}\n' \
+        "$SESSION_ID" "$NEW_BRANCH" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$TRACK_FILE"
+    fi
+    exit 0
+  fi
+
+  # === Rule 2 (Bash gh): PR creation — shlex-aware ===
+  if echo "$COMMAND" | detect_gh_pr_create; then
+    cat >&2 <<EOF
+
+┄┄┄ check_solo_workflow — R2 BLOCKER (M28) ┄┄┄
+
+[P0 BLOCKER] PR creation via gh
+
+❌ Solo work = NO PR (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
+
+修法 — 直接 squash merge:
+  git checkout main
+  git merge --squash <working-branch>
+  git commit -m "..."
+  git push origin main
+
+或 doc-only 改 → commit 直接 main。
+EOF
+    exit 2
+  fi
+
+  # === Rule 3 (Bash): push to main without user "push" trigger — shlex-aware ===
+  if echo "$COMMAND" | detect_push_main; then
+    if ! has_push_trigger; then
+      cat >&2 <<EOF
+
+┄┄┄ check_solo_workflow — R3 BLOCKER (M28) ┄┄┄
+
+[P0 BLOCKER] git push origin main
+
+❌ AI 不自決 push main (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
+   近 10 條 user message 無「push / OK / 好 / 合 main / merge / 可以」 trigger keyword。
+
+正確流程:
+  1. AI 改 code → commit + push working branch (Netlify auto-preview)
+  2. 告訴 user 主要改動 (or preview URL)
+  3. 等 user 明確 trigger 「push」/「OK」 才 merge to main
+
+例外 override:CLAUDE_BYPASS_SOLO_WORKFLOW=1 (audit logged)
+EOF
+      exit 2
+    fi
+  fi
+fi
+
+# === Rule 2 (MCP): create_pull_request ===
+if [ "$TOOL_NAME" = "mcp__github__create_pull_request" ]; then
+  cat >&2 <<EOF
+
+┄┄┄ check_solo_workflow — R2 BLOCKER (M28) ┄┄┄
+
+[P0 BLOCKER] mcp__github__create_pull_request
+
+❌ Solo work = NO PR (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
+
+修法 — 直接 squash merge to main (per Git solo-work canonical 7 步):
+  git checkout main && git merge --squash <branch> && git commit && git push origin main
+
+或 doc-only 改 → commit 直接 main。
+EOF
+  exit 2
+fi
+
+# === Rule 3 (MCP): merge_pull_request without user trigger ===
+if [ "$TOOL_NAME" = "mcp__github__merge_pull_request" ]; then
+  if ! has_push_trigger; then
+    cat >&2 <<EOF
+
+┄┄┄ check_solo_workflow — R3 BLOCKER (M28) ┄┄┄
+
+[P0 BLOCKER] mcp__github__merge_pull_request
+
+❌ AI 不自決 merge PR (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
+   近 10 條 user message 無「push / OK / 好 / 合 main / merge」 trigger。
+
+等 user 明確 trigger 才 merge。Override:CLAUDE_BYPASS_SOLO_WORKFLOW=1
+EOF
+    exit 2
+  fi
+fi
+
+exit 0

package/ds-canonical/hooks/check_spec_class_drift.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# Audit Dim 53 — Code-to-spec reverse drift check(2026-05-17 ship per M31 codex 共識)。
+#
+# 背景:Phase 1 我把 FileViewer spec.md L103 寫成「h-14 硬寫 known drift」,
+# 實際 code 已是 `h-[var(--chrome-header-height)]` — 反向 drift。本 hook 補。
+#
+# Allow escape:檔頭 `// @spec-class-drift-allow: <reason>` 整檔豁免。
+#
+# 2026-05-17 Round 3 修(per M31 codex Round 2 catch + 自跑 smoke test catch):
+#   set -u 在 zsh 下 PHRASE UTF-8 變數 unbound — 完全不用 set -u,只用 default-empty。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+# 不用 set -e / set -u(grep find-nothing 返回 1 + zsh UTF-8 變數 unbound issue)
+# 全部 defensive `|| true` + ${VAR:-default} 處理
+
+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/*/[a-z-]*.spec.md) ;;
+  *) 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
+')
+
+if echo "${NEW_CONTENT:-}" | grep -qE '@spec-class-drift-allow:'; then
+  exit 0
+fi
+
+TSX_PATH="${FILE_PATH%.spec.md}.tsx"
+if [ ! -f "$TSX_PATH" ]; then
+  exit 0
+fi
+
+TSX_CONTENT=$(cat "$TSX_PATH" 2>/dev/null)
+TSX_CONTENT="${TSX_CONTENT:-}"
+
+WARNINGS=""
+
+# Pattern 1: spec 寫「固定 h-NN」/「h-NN 寫死」/「h-NN 硬寫」keyword
+# Extract phrase + check tsx
+PHRASES=$(echo "${NEW_CONTENT:-}" | grep -oE '(固定|寫死|硬寫|hardcode)[[:space:]]+h-[0-9]+' || true)
+if [ -n "$PHRASES" ]; then
+  while IFS= read -r phrase; do
+    [ -z "$phrase" ] && continue
+    class=$(echo "$phrase" | grep -oE 'h-[0-9]+' | head -1)
+    [ -z "$class" ] && continue
+    if ! echo "$TSX_CONTENT" | grep -qE "[\"' ]$class[\"' \]]"; then
+      WARNINGS="${WARNINGS}   • spec 寫「$phrase」但 tsx 不含 $class(可能已 migrate to token)
+"
+    fi
+  done <<EOF
+$PHRASES
+EOF
+fi
+
+# Pattern 2: tsx 已消費 --chrome-header-height,spec 仍寫「固定 h-NN」
+HAS_TOKEN_TSX=$(echo "$TSX_CONTENT" | grep -c 'chrome-header-height' 2>/dev/null | head -1)
+HAS_TOKEN_TSX="${HAS_TOKEN_TSX:-0}"
+HAS_DRIFT_SPEC=$(echo "${NEW_CONTENT:-}" | grep -cE '(固定|寫死|硬寫)[[:space:]]+h-(12|14|16)' 2>/dev/null | head -1)
+HAS_DRIFT_SPEC="${HAS_DRIFT_SPEC:-0}"
+if [ "$HAS_TOKEN_TSX" -gt 0 ] 2>/dev/null && [ "$HAS_DRIFT_SPEC" -gt 0 ] 2>/dev/null; then
+  WARNINGS="${WARNINGS}   • tsx 已消費 --chrome-header-height token,但 spec 仍寫「固定 h-NN」— 反向 drift
+"
+fi
+
+if [ -n "$WARNINGS" ]; then
+  printf '⚠️ SPEC-CODE REVERSE DRIFT(audit Dim 53,soft P1):\n' >&2
+  printf '   Spec: %s\n' "$FILE_PATH" >&2
+  printf '   Code: %s\n' "$TSX_PATH" >&2
+  printf '%s' "$WARNINGS" >&2
+  printf '  SSOT: .claude/skills/design-system-audit/SKILL.md Group P Dim 53\n' >&2
+  printf '  修方向: 改 spec.md wording 對齊 code 實況\n' >&2
+  printf '  Escape: spec 頭加 // @spec-class-drift-allow: <rationale>\n' >&2
+fi
+
+exit 0