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

package/ds-canonical/hooks/check_plugin_fork_health.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+# check_plugin_fork_health.sh — SessionStart ×2 — fork-user repo plugin 健康(DS repo 內 by-design 早退)
+#
+# 2026-06-11 prune merge(user 拍板「照你建議做」;59→51 headroom):
+# #   r1_plugin_install = 原 check_fork_user_plugin_install.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+#   r2_plugin_freshness = 原 check_plugin_freshness.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+# 原檔 → .claude/hooks/retired/2026-06-11-prune-merge/
+# 各規則跑在 pipeline 子 shell:規則內 exit 不中斷其他規則;任一 exit 2 → 整體 exit 2。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+
+r1_plugin_install() {
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+[ "$EVENT" != "SessionStart" ] && exit 0
+
+CWD=$(pwd)
+
+# (a) 不是 DS repo:無 packages/design-system/src
+[ -d "$CWD/packages/design-system/src" ] && exit 0
+
+# (b) package.json 含 DS dep?
+[ ! -f "$CWD/package.json" ] && exit 0
+if ! grep -q '"@qijenchen/design-system"' "$CWD/package.json" 2>/dev/null; then
+  exit 0
+fi
+
+# (c) Plugin 已安裝?Anthropic plugin install 可能使用 <plugin> 或
+# <plugin>@<marketplace> directory name;accept both.
+PLUGIN_INSTALLED=0
+# 2026-05-31 fix(infra-audit P1):真實 Claude Code layout = ~/.claude/plugins/marketplaces/<name>/
+# + known_marketplaces.json(keyed by marketplace name)。原查 plugins/design-system + 錯的
+# .claude/marketplaces(漏 plugins/)= 裝了仍誤判未裝。marketplace name = qijenchen-ds。
+MARKETPLACE="qijenchen-ds"
+KM="$HOME/.claude/plugins/known_marketplaces.json"
+[ -d "$HOME/.claude/plugins/marketplaces/$MARKETPLACE" ] && PLUGIN_INSTALLED=1
+[ -d "$CWD/.claude/plugins/marketplaces/$MARKETPLACE" ] && PLUGIN_INSTALLED=1
+{ [ -f "$KM" ] && grep -q "\"$MARKETPLACE\"" "$KM"; } && PLUGIN_INSTALLED=1
+# legacy / 舊 layout fallback
+[ -d "$HOME/.claude/plugins/design-system" ] && PLUGIN_INSTALLED=1
+[ -d "$CWD/.claude/plugins/design-system" ] && PLUGIN_INSTALLED=1
+
+if [ "$PLUGIN_INSTALLED" = "1" ]; then
+  exit 0
+fi
+
+# All YES → fork-user 沒裝 plugin → context inject(SessionStart additional context)
+cat <<EOF
+🚨 Fork-user plugin not installed — DS governance hooks 不會 fire,憑記憶寫 mock 不會被攔。
+
+偵測:
+  cwd = $CWD
+  package.json 含 @qijenchen/design-system dep ✅
+  ~/.claude/plugins/design-system@qijenchen-ds/ 或 .claude/plugins/design-system@qijenchen-ds/ 不存在 ❌
+
+→ 後果(2026-05-26 anchor event):憑記憶寫 App.tsx mock(漏 SidebarTrigger / collapsible / startIcon /
+  tooltip / SidebarFooter)= production-grade fork-user 跑版 anti-pattern。
+
+修法:**session 開始第一件事必跑**
+  1. \`/plugin marketplace add github:ajenchen/design-system\`
+  2. \`/plugin install design-system@qijenchen-ds\`(or 對應 plugin name per marketplace.json)
+
+跑完 plugin install 後:
+  - 59 個 DS governance hooks 自動 fire(M29 anchor preflight / approval-preflight / story_invariants / inject_deploy_url_after_push 等;count snapshot 2026-05-29)
+  - DS canonical / rules / skills 從 ~/.claude/plugins/ 可 cross-load
+  - Fork-user 寫 App.tsx 時憑記憶寫 mock 會被 mechanical BLOCKER 攔
+
+對應 canonical:
+  - product-workspace CLAUDE.md「Fork-and-go onboarding」step 2-3
+  - .claude-plugin/marketplace.json
+EOF
+exit 0
+}
+
+r2_plugin_freshness() {
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+case "${EVENT:-}" in
+  SessionStart) ;;
+  *) exit 0 ;;
+esac
+
+# Find local plugin.json (DS plugin install path)
+PLUGIN_JSON=""
+for candidate in \
+  "$HOME/.claude/plugins/design-system@qijenchen-ds/plugin.json" \
+  "$HOME/.claude/plugins/cache/design-system/plugin.json" \
+  "${CLAUDE_PROJECT_DIR:-.}/.claude-plugin/plugin.json"
+do
+  if [ -f "$candidate" ]; then PLUGIN_JSON="$candidate"; break; fi
+done
+
+if [ -z "$PLUGIN_JSON" ]; then exit 0; fi
+
+LOCAL_VERSION=$(jq -r '.version // ""' "$PLUGIN_JSON" 2>/dev/null)
+if [ -z "$LOCAL_VERSION" ]; then exit 0; fi
+
+# Fetch latest marketplace.json from GitHub raw (5s timeout, fail silently if offline)
+REMOTE_VERSION=$(curl -sS --max-time 5 \
+  "https://raw.githubusercontent.com/ajenchen/design-system/main/.claude-plugin/marketplace.json" \
+  2>/dev/null | jq -r '.metadata.version // ""' 2>/dev/null)
+
+if [ -z "$REMOTE_VERSION" ] || [ "$REMOTE_VERSION" = "null" ]; then exit 0; fi
+
+if [ "$LOCAL_VERSION" != "$REMOTE_VERSION" ]; then
+  cat << EOF
+
+📦 DS governance update available:
+   Local installed: $LOCAL_VERSION
+   Latest published: $REMOTE_VERSION
+
+Run in terminal (1 command):
+  npm run sync-all  # npm install @beta(治理本體)+ 刷新接線骨架(committed launchers + settings + skills);npm-only,免 plugin
+
+
+(Per user 2026-05-27 directive「DS 增刪改自動同步」— this hook detects staleness on session start.)
+
+EOF
+fi
+
+exit 0
+}
+
+for _rule in r1_plugin_install r2_plugin_freshness; do
+  echo "$INPUT" | "$_rule"
+  _rc=$?
+  if [ "$_rc" -eq 2 ]; then exit 2; fi
+done
+exit 0

package/ds-canonical/hooks/check_post_main_ssot_propagate.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# check_post_main_ssot_propagate.sh — PostToolUse Bash: 偵測 `git push origin main` 後
+# diff HEAD~..HEAD 含 SSOT-affecting paths → inject context 提議 npm version bump 啟動 cross-repo sync chain。
+#
+# Per user verbatim 2026-05-26:「Ds repo 在 deep audit cross codex 後或是 knowledge prune deep 後,
+# 並把所有增刪改都 push main 之後,所有 repo 是否也都能獲得更新?不是只要一 knowledge audit deep 之後
+# 就要,是等我 push main 後才要」
+#
+# Architecture canonical:
+#   - **Trigger = push to main**(NOT skill completion)— 因為 SSOT-affecting changes 可能來自任何 source
+#     (/knowledge-prune deep / /deep-audit-cross-codex Phase C / 一般 bug fix / 新元件 ship / governance edit)
+#   - 統一在 push main 後 detect SSOT diff → 觸發 cross-repo sync chain
+#   - 對應 CLAUDE.md `# Git solo-work canonical` Step 5.5 SSOT propagation
+#
+# SSOT-affecting paths(改這些 = consumer 需要 bump npm dep 才能拿到):
+#   - packages/design-system/src/**         (DS production code → npm package)
+#   - packages/storybook-config/{addons,addons-preset.ts,preview.tsx,package.json}  (storybook addon config → npm;無 src/ dir,真 regex 見 L56)
+#   - .claude/{rules,hooks,skills,commands,references}/** (governance plugin → ships via ds-canonical/)
+#   - .claude-plugin/{plugin,marketplace}.json (plugin metadata)
+#   - hooks/hooks.json                        (plugin hook registration)
+#   - CLAUDE.md                               (governance instructions ship via npm package files)
+#
+# Non-SSOT paths(改這些 don't trigger):
+#   - scripts/**                              (DS internal tooling)
+#   - .claude/{logs,memory,planning}/**       (session-specific / not shipped)
+#   - .github/**                              (DS internal CI)
+#   - *.test.* / docs / README                (non-functional changes)
+#
+# 對齊:CLAUDE.md `# Git solo-work canonical` Step 5.5 +
+#       .claude/skills/{knowledge-prune,deep-audit-cross-codex}/SKILL.md(now point to canonical 不重複)
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+[ "$EVENT" != "PostToolUse" ] && exit 0
+[ "$TOOL" != "Bash" ] && exit 0
+
+# Match: git push origin main(NOT push to working branch, NOT push --delete)
+if ! echo "$CMD" | grep -qE '\bgit\s+push\s+(-u\s+)?origin\s+main\b'; then
+  exit 0
+fi
+if echo "$CMD" | grep -qE 'push\s+origin\s+--delete'; then
+  exit 0
+fi
+
+# Only fire when in DS repo(packages/design-system/src/ exists);non-DS repo silent skip
+CWD=$(pwd)
+[ ! -d "$CWD/packages/design-system/src" ] && exit 0
+
+# Detect SSOT-affecting diff between HEAD~1 and HEAD
+SSOT_DIFF=$(git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -E '^(packages/design-system/src/|packages/storybook-config/(addons/|addons-preset\.ts|preview\.tsx|package\.json)|\.claude/(rules|hooks|skills|commands|references)/|\.claude-plugin/(plugin|marketplace)\.json|hooks/hooks\.json|CLAUDE\.md)' || true)
+
+[ -z "$SSOT_DIFF" ] && exit 0
+
+# Count touched files
+SSOT_COUNT=$(echo "$SSOT_DIFF" | wc -l | tr -d ' ')
+
+# Read current package version
+PKG_VERSION=$(jq -r '.version' "$CWD/packages/design-system/package.json" 2>/dev/null || echo "unknown")
+
+cat <<EOF
+🔄 SSOT propagation gate(post push origin main):
+
+📊 偵測:HEAD~1..HEAD 含 $SSOT_COUNT 個 SSOT-affecting file changes
+📦 目前 npm version:$PKG_VERSION
+🎯 AI 必「全自動執行」(不需 user 再問 / 再確認 — per Step 5.5 2026-06-02 user directive Option A):
+   bump → release:preflight → tag → push tag → Release workflow → npm publish → npm view 驗證
+   → 24h 內 product-workspace + 所有 fork repo 自動拿最新
+
+Touched(top 5):
+$(echo "$SSOT_DIFF" | head -5 | sed 's/^/  - /')
+
+AI 全自動執行步驟(user 已給 merge trigger → 以下不需再問;user 隨時可喊停):
+  1. bump packages/design-system/package.json → node scripts/sync-version-to-all-manifests.mjs(同步全 5 manifest)
+  2. npm run release:preflight(全過才寫 HEAD-bound pass-marker;R4 hook 認它才放行 tag)
+  3. git tag v0.1.0-beta.<N+1> + git push origin main + git push origin v0.1.0-beta.<N+1>
+  4. Release workflow auto-fire → npm publish + Dependabot 日常 cross-repo sweep
+  5. npm view <pkg> version 驗證真上架(非看 CI 綠燈)
+
+對應 canonical:
+  - CLAUDE.md \`# Git solo-work canonical\` Step 5.5
+  - .claude/skills/knowledge-prune/SKILL.md「Phase Z」reference
+  - .claude/skills/deep-audit-cross-codex/SKILL.md「Phase C」reference
+EOF
+exit 0

package/ds-canonical/hooks/check_propose_discipline.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# check_propose_discipline.sh — Stop ×2 — propose 紀律(中文人話 + file:line cite;SSOT memory/feedback_propose_discipline.md)
+#
+# 2026-06-11 prune merge(user 拍板「照你建議做」;59→51 headroom):
+# #   r1_plain_chinese = 原 check_propose_plain_chinese.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+#   r2_cite_required = 原 check_propose_cite_required.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+# 原檔 → .claude/hooks/retired/2026-06-11-prune-merge/
+# 各規則跑在 pipeline 子 shell:規則內 exit 不中斷其他規則;任一 exit 2 → 整體 exit 2。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+
+r1_plain_chinese() {
+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_discipline.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
+}
+
+r2_cite_required() {
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+# Only fire on stop events (post-assistant turn)
+case "${EVENT:-}" in
+  Stop|SubagentStop) ;;
+  *) exit 0 ;;
+esac
+
+# Read last assistant message
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+[ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ] && exit 0
+
+LAST_REPLY=$(tail -200 "$TRANSCRIPT" 2>/dev/null | grep -E '"role":"assistant"|"type":"text"' | tail -50 | tr -d '\n' | head -c 8000)
+
+# Escape clause
+if echo "$LAST_REPLY" | grep -q 'propose-cite-skip'; then
+  exit 0
+fi
+
+# Detect claim keywords
+HAS_CLAIM=""
+for kw in '規定' '必配' '必須用' '必須是' '一定要' 'canonical 寫' 'spec 寫' '強制' 'DS spec 規定' '明文' 'mandate'; do
+  if echo "$LAST_REPLY" | grep -qF "$kw"; then
+    HAS_CLAIM="$kw"
+    break
+  fi
+done
+
+if [ -z "$HAS_CLAIM" ]; then
+  exit 0
+fi
+
+# Detect cite patterns
+# Accept: file.spec.md:42 | file.css:42 | file.tsx:42 | file.ts:42 | L42 | line 42 | semantic.css#L42
+HAS_CITE=""
+if echo "$LAST_REPLY" | grep -qE '\.(spec\.md|css|tsx|ts|json):[0-9]+|#L[0-9]+|line[[:space:]]+[0-9]+|L[0-9]+-[0-9]+|L[0-9]+'; then
+  HAS_CITE="found"
+fi
+
+if [ -z "$HAS_CITE" ]; then
+  cat >&2 << 'EOF'
+🚨 PROPOSE-WITHOUT-CITE BLOCKER(2026-05-27 user verbatim「沒有好好按照規則和 ssot 跑設計」)
+
+  你 reply 含 claim keyword(規定 / 必配 / 必須用 / canonical 寫 / spec 寫 / 強制)
+  但**無 file:line cite**(`.spec.md:42` / `.css:42` / `.tsx:42` / `L42` / `line 42` 任一)。
+
+  Anchor 2026-05-27:我憑印象斷言「DS spec 規定 caption + muted」,user grep verify
+  發現 semantic.css L49 只是 token use-case 描述,**沒「必配」rule**。瞎掰造成 user
+  接受錯誤 propose 風險。
+
+  修方向 2 選 1:
+    (a) 補 cite — 把 spec / source path:line 補進 reply,讓 user verify
+    (b) 撤回 claim — 顯式打「撤回 claim:此條無 SSOT 依據」
+
+  Escape(極罕見):reply 含 `<!-- @propose-cite-skip: <rationale> -->`
+
+  對齊 M22 cite invariant 延伸到對話層 + mindset #2「不憑直覺發明」mechanical 強制。
+EOF
+  exit 2
+fi
+
+exit 0
+}
+
+for _rule in r1_plain_chinese r2_cite_required; do
+  echo "$INPUT" | "$_rule"
+  _rc=$?
+  if [ "$_rc" -eq 2 ]; then exit 2; fi
+done
+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_propose_without_benchmark.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# check_propose_without_benchmark.sh — M26 mechanical enforcement(2026-05-26 backfill per
+# user verbatim「該程式化的都沒程式化」)。
+#
+# Purpose:UserPromptSubmit — 偵測 AI 在 next reply 將 propose visual/behavior decision
+# (出現「建議」「方案 A/B」「propose」「應該改成」keyword)but 過去 ~20 turns 無 WebFetch / WebSearch
+# tool call trace → inject soft BLOCKER 要求先 fetch ≥ 3 source 才 propose。
+#
+# 對齊 meta-patterns.md M26「Behavior/visual canonical decision 前必跑 WebFetch + WebSearch 取 ≥3
+# source,不可憑印象 propose」+ propose-options/SKILL.md。
+#
+# 注意:本 hook 走 UserPromptSubmit(在 AI reply 前 inject context),
+# 跟 check_propose_pre_grep_verify.sh(走 PostToolUse 偵測 propose 已成型後再警示)互補。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null)
+
+[ "$EVENT" != "UserPromptSubmit" ] && exit 0
+[ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ] && exit 0
+
+# Heuristic:user prompt 含 specific visual / behavior decision trigger keyword(2026-05-26 tighten — 拿掉「應該/是否/改成/design/behavior/互動」太籠統的 false-positive triggers)
+PROPOSE_TRIGGER_RE='(propose me|give me options|列.{0,5}option|建議.{0,5}方案|建議.{0,5}做法|哪個比較|對齊哪家|比稿|要怎麼設計|該用哪個|design tradeoff|recommend|world-class.{0,10}(對照|比較))'
+if ! echo "$PROMPT" | grep -qE "$PROPOSE_TRIGGER_RE"; then
+  exit 0
+fi
+
+# Scan past ~20 turns(~400 lines)看是否有 WebFetch / WebSearch tool_use
+RECENT=$(tail -400 "$TRANSCRIPT_PATH" 2>/dev/null)
+HAS_FETCH=$(echo "$RECENT" | \
+  jq -r 'select(.message.content != null) |
+    .message.content // empty |
+    if type == "array" then
+      (.[]? | select(.type == "tool_use") | select(.name == "WebFetch" or .name == "WebSearch") | .name)
+    else empty end' 2>/dev/null | wc -l)
+HAS_FETCH=${HAS_FETCH:-0}
+
+if [ "$HAS_FETCH" -ge 2 ]; then
+  exit 0
+fi
+
+# Soft inject
+cat <<EOF
+⚠️ M26 Propose-without-benchmark gate
+
+→ User prompt 含 propose / visual / behavior decision trigger keyword,但過去 ~20 turns
+  Web fetch / WebSearch tool_use count = $HAS_FETCH(< 2)。
+
+M26 要求:visual / behavior canonical decision 前必跑 WebFetch + WebSearch 取 ≥ 3 source
+  (Atlassian / Material / Polaris / Ant / Carbon / Apple HIG / shadcn / Radix),不可憑印象。
+
+Pipeline(propose 前 inline 跑):
+  1. WebFetch 3 家世界級 source
+  2. 全 403 → WebSearch fallback 用 snippet,明示「search-only confidence」
+  3. WebFetch + WebSearch 都失敗 → STOP propose,告知 user「無法 verify,要看 screenshot / 實機」
+
+對應:meta-patterns.md M26 / propose-options/SKILL.md Step B-3。
+EOF
+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_sidebar_menu_button_implicit_wrap.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# check_sidebar_menu_button_implicit_wrap.sh — PreToolUse Edit/Write 攔 SidebarMenuButton 沒 asChild + children 含 ItemAvatar/Avatar/Icon 致隱式 wrap 垂直 stack(2026-05-27)
+#
+# Per user 2026-05-27 抓 UserFooter Avatar 垂直 stack drift:
+#   SidebarMenuButton(sidebar.tsx L1036-1043)在沒 asChild 時把所有 children 塞進 <ItemLabel> 單一 span,
+#   Avatar + text-span 都在同 span 內 → 強迫垂直堆疊。
+#
+# Canonical:含 Avatar/ItemAvatar/icon prefix 的 SidebarMenuButton 必用 asChild + <div> wrap,
+#   per sidebar.tsx:1025-1027 docblock:「asChild 的 consumer 自行放 icon + label」+ DS canonical
+#   sidebar.stories.tsx#UserFooter 範例 L76-104。
+#
+# Detection:
+#   `<SidebarMenuButton ...>` (no asChild) ... `<ItemAvatar` or `<Avatar` inside → BLOCKER
+#   ALLOW:`<SidebarMenuButton startIcon={X}>label</SidebarMenuButton>`(用 startIcon prop 不 wrap)
+#   ALLOW:`<SidebarMenuButton asChild>...</SidebarMenuButton>`(consumer 自管 layout)
+
+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)
+NEW=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null)
+
+[ "$EVENT" != "PreToolUse" ] && exit 0
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.tsx) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.test.tsx) exit 0 ;; esac
+
+# Python multiline regex:`<SidebarMenuButton` 不含 `asChild` 的 block + 內含 Avatar/ItemAvatar prefix
+HAS_DRIFT=$(printf '%s' "$NEW" | python3 -c '
+import sys, re
+content = sys.stdin.read()
+# Find SidebarMenuButton blocks(opening tag → closing tag,non-greedy multiline)
+# match opening `<SidebarMenuButton ...>` capture full open tag
+for m in re.finditer(r"<SidebarMenuButton\b([^>]*)>(.*?)</SidebarMenuButton>", content, re.DOTALL):
+    open_tag, body = m.group(1), m.group(2)
+    # Skip if asChild present
+    if re.search(r"\basChild\b", open_tag):
+        continue
+    # Drift = body 含 <ItemAvatar 或 <Avatar(both = avatar prefix)
+    if re.search(r"<(ItemAvatar|Avatar)\b", body):
+        print("DRIFT")
+        sys.exit(0)
+' 2>/dev/null)
+
+[ "$HAS_DRIFT" != "DRIFT" ] && exit 0
+
+# Override env(audit-logged)
+if [ "${CLAUDE_BYPASS_SIDEBAR_MENU_BUTTON_WRAP:-0}" = "1" ]; then
+  mkdir -p "$(dirname "$0")/../logs" 2>/dev/null
+  printf '{"ts":"%s","event":"sidebar-menu-button-wrap-bypass","file":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$FILE_PATH" >> "$(dirname "$0")/../logs/governance-bypass.jsonl" 2>/dev/null
+  exit 0
+fi
+
+REL=${FILE_PATH#*/my-project/}
+
+cat >&2 <<'EOF'
+🚨 SidebarMenuButton implicit-wrap canonical violation(per user 2026-05-27 UserFooter 垂直 stack 事件):
+
+🔍 偵測:SidebarMenuButton 內含 ItemAvatar 或 Avatar 但 **無 asChild**
+
+⚠️ 後果(per sidebar.tsx:1036-1043 source code):
+  SidebarMenuButton 沒 asChild → children 全塞進 ItemLabel(單 span)
+  → Avatar + text 在同 span 內 → 強迫垂直堆疊(user 抓的 bug)
+
+修法(per DS canonical sidebar.stories.tsx#UserFooter):
+
+  ❌ SidebarMenuButton id="..." 直接放 ItemAvatar + span 為 children
+
+  ✅ SidebarMenuButton asChild 包 div role="group" 內含 ItemAvatar + span data-sidebar="menu-label" min-w-0 flex-1 truncate
+
+Or use startIcon prop(自動 layout,不 wrap):
+  ✅ SidebarMenuButton startIcon={SomeLucideIcon} 直接 children 為純文字
+
+Bypass(極罕見):CLAUDE_BYPASS_SIDEBAR_MENU_BUTTON_WRAP=1 env var(audit-logged)。
+
+Citation:
+  - packages/design-system/src/components/Sidebar/sidebar.tsx:1025-1043(asChild docblock)
+  - packages/design-system/src/components/Sidebar/sidebar.stories.tsx UserFooter L76-104(canonical)
+EOF
+# 2026-05-31:exit 0 → exit 2(folded-hook-audit:原宣稱 BLOCKER 但 exit 0 = 假 enforcement;
+# SidebarMenuButton implicit-wrap 是 SSOT canonical,verified clean on 現有 sidebar code + 有 env escape)。
+exit 2