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

package/ds-canonical/hooks/check_pattern_invariants.sh

@@ -2,27 +2,90 @@
 # Pattern invariants unified hook(2026-05-08 cluster C consolidation)
 #
 # Merges 4 PreToolUse hooks(原各檔已 retire,合併入此):
-#   C.1 overlay panel scroll chain(原 check_overlay_panel_scroll_chain,P1 WARN stderr)
-#   C.2 inline-action canonical gap(原 check_inline_action_canonical_gap,P1 WARN stderr)
+#   C.1 overlay panel scroll chain(原 check_overlay_panel_scroll_chain,P1 WARN context)
+#   C.2 inline-action canonical gap(原 check_inline_action_canonical_gap,P1 WARN context)
 #   C.3 primitive wrapper padding(原 check_primitive_wrapper_padding,P0 BLOCK exit 2)
 #   C.4 row slot handcraft(原 check_row_slot_handcraft,P0 BLOCK exit 2)
+#   C.5 弱化 icon hover 階梯(2026-07-30 user 拍板,P0 BLOCK exit 2)
+#   C.6 selected token 狀態語意(2026-08-11 user 拍板,P0 BLOCK exit 2)
 #
 # Why merge:皆 element-anatomy / overlay-surface SSOT 消費紀律 invariant,共用 INPUT
 # parsing + tsx filter,散裝是 M17 + Anthropic ≤ 15 hook best-practice 偏離。
 #
-# Exit precedence:BLOCK(2)> WARN-stderr(0)。每 rule 獨立 fire,worst 勝。
+# Output precedence:BLOCK(2,stderr)> WARN(0,單一 governanceContext)> silent(0)。
 #
 # Per-rule allowlist:
 #   C.1: `// @scroll-chain-allow: <reason>`(any line)
 #   C.2: `// @inline-action-gap-allow: <reason>`(any line)
 #   C.3: `// @primitive-padding-allow: <reason>`(檔案前 5 行)
 #   C.4: `// @row-slot-handcraft-allow: <reason>`(any line)
+#   C.5: `// @hover-ramp-allow: <reason>`(any line)
+#   C.6: `// @token-state-allow: <reason>`(any line)
 
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
 
 set -uo pipefail
 
+_HOOK_CONTEXT_EVENT="PreToolUse"
+_HOOK_OUTPUT_CAPTURE=$(mktemp "${TMPDIR:-/tmp}/check-pattern-invariants.XXXXXX") || {
+  printf 'GOVERNANCE_INTEGRITY: pattern invariants output capture unavailable\n' >&2
+  exit 70
+}
+exec 3>&1 4>&2
+exec >"$_HOOK_OUTPUT_CAPTURE" 2>&1
+
+_finalize_hook_output() {
+  _hook_rc=$?
+  trap - EXIT
+  exec 1>&3 2>&4
+  _hook_output=$(cat "$_HOOK_OUTPUT_CAPTURE" 2>/dev/null || true)
+  rm -f "$_HOOK_OUTPUT_CAPTURE" 2>/dev/null || true
+
+  case "$_hook_rc" in
+    0)
+      [ -z "$_hook_output" ] && exit 0
+      if ! jq -cn \
+        --arg event "$_HOOK_CONTEXT_EVENT" \
+        --arg message "$_hook_output" \
+        '{governanceContext:{hookEventName:$event,message:$message}}'; then
+        printf 'GOVERNANCE_INTEGRITY: pattern invariants warning envelope encoding failed\n' >&2
+        exit 70
+      fi
+      exit 0
+      ;;
+    2)
+      if grep -q 'GOVERNANCE_INTEGRITY:' <<<"$_hook_output"; then
+        printf '%s\n' "$_hook_output" >&2
+        exit 70
+      elif [ -n "$_hook_output" ]; then
+        printf '%s\n' "$_hook_output" >&2
+      else
+        printf 'pattern invariants hook blocked without diagnostic\n' >&2
+      fi
+      exit 2
+      ;;
+    70)
+      if [ -n "$_hook_output" ]; then
+        printf '%s\n' "$_hook_output" >&2
+      else
+        printf 'GOVERNANCE_INTEGRITY: pattern invariants failed without diagnostic\n' >&2
+      fi
+      exit 70
+      ;;
+    *)
+      printf 'GOVERNANCE_INTEGRITY: pattern invariants undefined exit code %s\n' "$_hook_rc" >&2
+      [ -n "$_hook_output" ] && printf '%s\n' "$_hook_output" >&2
+      exit 70
+      ;;
+  esac
+}
+trap _finalize_hook_output EXIT
+
 INPUT=$(cat)
+if ! printf '%s' "$INPUT" | jq -e 'type == "object"' >/dev/null 2>&1; then
+  printf 'GOVERNANCE_INTEGRITY: pattern invariants invalid input envelope\n' >&2
+  exit 70
+fi
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
 
@@ -42,14 +105,52 @@ NEW_CONTENT=$(echo "$INPUT" | jq -r '
   ([.tool_input.edits[]? | .new_string] | join("\n"))
 ' 2>/dev/null || echo "")
 
-[ -z "${NEW_CONTENT//[[:space:]]/}" ] && exit 0
+grep -q '[^[:space:]]' <<<"$NEW_CONTENT" || exit 0
 
 WORST=0
 record_worst() { local lvl=$1; [ "$lvl" -gt "$WORST" ] && WORST=$lvl; }
 
-# ── C.1 overlay panel scroll chain(P1 WARN stderr only)──────────────────────
-if ! echo "$NEW_CONTENT" | grep -q '@scroll-chain-allow' \
-   && echo "$NEW_CONTENT" | grep -q '<SurfaceBody'; then
+# ── C.6 selected token 狀態語意(P0 BLOCK exit 2;2026-08-11 user 拍板)──────────
+# 教義(semantic.css + color.spec.md「Selected state family」):
+#   -active = 按壓專屬 / -hover = 可取消切換鈕變淺專屬 / 反白·鍵盤焦點深化 = -focus。
+# 兩年偏移錨:2026-07-05 D4 借 -active 裝反白、滑鼠搭便車,選單 vs sidebar 因此不一致。
+# 本規則攔「-active/-hover 出現在 hover/焦點/反白修飾鏈」的借用寫法(零誤判:合法用途已窮舉排除)。
+if ! grep -q '@token-state-allow' <<<"$NEW_CONTENT"; then
+  SUSPECT_C6=$(printf '%s' "$NEW_CONTENT" | grep -oE "[][A-Za-z0-9_=:.-]*bg-neutral-selected-(active|hover)" | while IFS= read -r tok; do
+    case "$tok" in
+      (*active:*) ;;                                # 修飾鏈含按壓(active:)= 合法按壓用途
+      (*hover:*bg-neutral-selected-hover) ;;        # 切換鈕 pressed 上 hover 變淺 = 誕生語意,合法
+      (*)
+        case "$tok" in
+          (*hover:*|*focus-visible:*|*focus:*|*data-\[highlighted*|*data-\[selected*)
+            printf '%s\n' "$tok" ;;
+        esac ;;
+    esac
+  done | sort -u)
+  if [ -n "$SUSPECT_C6" ]; then
+    cat >&2 <<EOF
+
+┄┄┄ C.6 check_pattern_invariants — selected token 狀態語意 BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測按壓/切換鈕專屬 token 被借用到反白·焦點·hover 修飾鏈:
+$SUSPECT_C6
+
+教義(item-anatomy.spec.md「選中 × 互動疊加」+ color.spec.md「Selected state family」):
+  滑鼠 hover 選中列 → 釘住 bg-neutral-selected 不變
+  鍵盤反白/焦點停在選中列 → bg-neutral-selected-focus(深一階)
+  bg-neutral-selected-active → 只准出現在含 active:(按壓)的修飾鏈
+  bg-neutral-selected-hover  → 只准切換鈕 pressed 上 hover(變淺)
+例外:行尾 \\`// @token-state-allow: <reason>\\`
+
+EOF
+    record_worst 2
+  fi
+fi
+
+# ── C.1 overlay panel scroll chain(P1 WARN context)──────────────────────────
+if ! grep -q '@scroll-chain-allow' <<<"$NEW_CONTENT" \
+   && grep -q '<SurfaceBody' <<<"$NEW_CONTENT"; then
   SUSPECT_C1=$(printf '%s' "$NEW_CONTENT" | awk '
     /^[[:space:]]*<div[[:space:]]/ {
       line = $0
@@ -84,15 +185,15 @@ EOF
   fi
 fi
 
-# ── C.2 inline-action canonical gap(P1 WARN stderr only)─────────────────────
+# ── C.2 inline-action canonical gap(P1 WARN context)─────────────────────────
 case "$FILE_PATH" in
   *components/*.tsx|*patterns/*.tsx)
     case "$FILE_PATH" in
       */item-anatomy.tsx|*.stories.tsx|*.test.*) ;; # SSOT/test skip
       *)
-        if ! echo "$NEW_CONTENT" | grep -q '@inline-action-gap-allow' \
-           && echo "$NEW_CONTENT" | grep -qE '<ItemInlineAction(Button)?\b|DropdownMenuTrigger.*ItemInlineAction'; then
-          WRONG_GAP=$(echo "$NEW_CONTENT" | grep -nE 'className=.*\bgap-(1|3|4|5|6|8|10|12)\b' | head -3 || true)
+        if ! grep -q '@inline-action-gap-allow' <<<"$NEW_CONTENT" \
+           && grep -qE '<ItemInlineAction(Button)?\b|DropdownMenuTrigger.*ItemInlineAction' <<<"$NEW_CONTENT"; then
+          WRONG_GAP=$(grep -m 3 -nE 'className=.*\bgap-(1|3|4|5|6|8|10|12)\b' <<<"$NEW_CONTENT" || true)
           if [ -n "$WRONG_GAP" ]; then
             cat >&2 <<EOF
 
@@ -115,16 +216,58 @@ EOF
     ;;
 esac
 
+
+# ── C.5 弱化 icon hover 階梯(P0 BLOCK exit 2;2026-07-30 user 拍板)─────────────
+# Root invariant:hover 往前一階,不跳階。rest \`text-fg-muted\`(neutral-7)的弱化 icon
+# hover 必 \`text-fg-secondary\`(neutral-8),不得直接跳 \`text-foreground\`(neutral-9)。
+# rule owner = inline-action.spec.md「Icon 色彩」段 + tokens/color/semantic.css:53。
+# 世界級:Fluent 2 neutralForeground3Hover === neutralForeground2 / MUI Chip deleteIcon .26→.4。
+# 錨例:2026-04-08 97e62a80 為修「colored Tag 上 fg-muted 不連貫」而 unified 全 variant 繼承文字色,
+# 連中性宿主一起改且未經 user 拍板;primitive 本身也一直跳兩階,四個月無機械防線。
+# rest 已是 fg-secondary 的整列/文字 hover(→ foreground)本身就是一階,不在射程內。
+case "$FILE_PATH" in
+  *components/*.tsx|*patterns/*.tsx|*.css)
+    if ! grep -q '@hover-ramp-allow' <<<"$NEW_CONTENT"; then
+      SKIP_RAMP=$(grep -m 3 -nE 'text-fg-muted[^"'"'"'\`]*hover:text-foreground|hover:text-foreground[^"'"'"'\`]*text-fg-muted' <<<"$NEW_CONTENT" || true)
+      if [ -n "$SKIP_RAMP" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ C.5 check_pattern_invariants — 弱化 icon hover 跳階 BLOCK ┄┄┄
+
+[P0] ${FILE_PATH}
+rest \`text-fg-muted\` 的弱化 icon 直接 hover 到 \`text-foreground\`(跳兩階):
+${SKIP_RAMP}
+
+❌ inline-action.spec.md「Icon 色彩」+ tokens/color/semantic.css:53:
+   弱化 icon hover 後變 \`fg-secondary\`(neutral-8),不是 \`foreground\`(neutral-9)。
+   世界級對照:Fluent 2 neutralForeground3Hover = neutralForeground2 / MUI Chip deleteIcon .26→.4。
+
+修法:\`hover:text-foreground\` → \`hover:text-fg-secondary\`(active 同步);
+      優先直接消費 \`ItemInlineActionButton\`(primitive 已內建正確階梯)而非手刻。
+      真有理由跳階 → 加 \`// @hover-ramp-allow: <rationale>\` 行豁免。
+
+EOF
+        exit 2
+      fi
+    fi
+    ;;
+esac
+
 # ── C.3 primitive wrapper padding(P0 BLOCK exit 2)───────────────────────────
 # File-level allowlist:檔頭前 5 行
 ALLOW_C3=0
 FIRST_LINES_NEW=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,5p')
-echo "$FIRST_LINES_NEW" | grep -qE '//[[:space:]]*@primitive-padding-allow:' && ALLOW_C3=1
+grep -qE '//[[:space:]]*@primitive-padding-allow:' <<<"$FIRST_LINES_NEW" && ALLOW_C3=1
 if [ -f "$FILE_PATH" ] && [ "$ALLOW_C3" = "0" ]; then
   ON_DISK_FIRST=$(sed -n '1,5p' "$FILE_PATH" 2>/dev/null || true)
-  echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@primitive-padding-allow:' && ALLOW_C3=1
+  grep -qE '//[[:space:]]*@primitive-padding-allow:' <<<"$ON_DISK_FIRST" && ALLOW_C3=1
 fi
 if [ "$ALLOW_C3" = "0" ]; then
+  # 缺 perl = C3 防線無法判 → 明確 BLOCK,不得靜默放行(fail-closed;cloud 前提宣告)。
+  if ! command -v perl >/dev/null 2>&1; then
+    echo '🚨 check_pattern_invariants: required interpreter perl is unavailable — C3 gate cannot run(fail-closed)' >&2
+    exit 2
+  fi
   PRIMITIVES_REGEX='DateGrid|Calendar|Surface|SurfaceHeader|SurfaceBody|SurfaceFooter'
   VIOLATIONS_C3=$(printf '%s' "$NEW_CONTENT" | perl -0777 -ne '
     while (/<div\b[^>]*className\s*=\s*["\x27`][^"\x27`]*\bp-\d+[^"\x27`]*["\x27`][^>]*>(?:[^<]*<(?!\/div\b)){0,8}\s*<('"$PRIMITIVES_REGEX"')\b/gs) {
@@ -165,8 +308,10 @@ case "$FILE_PATH" in
     case "$FILE_PATH" in
       */item-anatomy.tsx|*/field-wrapper.tsx|*.stories.tsx|*.test.*|*.spec.tsx) ;; # SSOT/test skip
       *)
-        if ! echo "$NEW_CONTENT" | grep -q '@row-slot-handcraft-allow' \
-           && echo "$NEW_CONTENT" | grep -E 'h-\[1lh\][^"]*shrink-0[^"]*flex[^"]*items-center|shrink-0[^"]*h-\[1lh\][^"]*flex[^"]*items-center|flex[^"]*items-center[^"]*h-\[1lh\][^"]*shrink-0' >/dev/null; then
+        # 2026-05-30(dim 39 M7/M34 fix):order-INDEPENDENT — extract className attrs,require ALL 4 tokens
+        # present(natural Tailwind 序 `flex items-center gap-2 shrink-0 h-[1lh]` 之前漏抓)。BSD/GNU grep 通用。
+        if ! grep -q '@row-slot-handcraft-allow' <<<"$NEW_CONTENT" \
+           && echo "$NEW_CONTENT" | grep -oE 'class(Name)?="[^"]*"' | grep -F 'h-[1lh]' | grep -F 'shrink-0' | grep -F 'flex' | grep -F 'items-center' >/dev/null 2>&1; then
           cat >&2 <<EOF
 
 ┄┄┄ C.4 check_pattern_invariants — row slot handcraft BLOCKER ┄┄┄

package/ds-canonical/hooks/check_peoplepicker_ssot_drift.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 set -uo pipefail
-# PreToolUse Edit/Write: PeoplePicker SSOT drift guard(2026-05-15 user verbatim「避免下次再度偏移」)
+# PostToolUse Edit/Write: PeoplePicker SSOT drift guard(2026-05-15 user verbatim「避免下次再度偏移」)
 #
 # 攔截:`people-picker.tsx` / `person-display.tsx` / `combobox.tsx` 動以下 PeoplePicker SSOT-bearing
 # code 路徑時,要求 commit message / new content 包含 cite 對應 spec.md SSOT table row 的 marker。
@@ -31,9 +31,9 @@ esac
 # Patterns that touch SSOT-bearing render logic
 SSOT_KEYWORDS='tagRenderer|overflowShape|tagWrapperClassName|selectedItemRenderer|MultiPersonDisplay|PersonAvatarTag|PersonDisplay|searchIn|searchPlaceholder|placeholder=\\{'
 
-if echo "$NEW_CONTENT" | grep -qE "$SSOT_KEYWORDS"; then
+if grep -qE "$SSOT_KEYWORDS" <<<"$NEW_CONTENT"; then
   # Check if new content cites spec.md SSOT table
-  if ! echo "$NEW_CONTENT" | grep -qE "(spec\\.md.*(§[A-F]|canonical table|Trigger display SSOT)|people-picker\\.spec\\.md.*L9[0-9])"; then
+  if ! grep -qE "(spec\\.md.*(§[A-F]|canonical table|Trigger display SSOT)|people-picker\\.spec\\.md.*L9[0-9])" <<<"$NEW_CONTENT"; then
     MSG="⚠️ PeoplePicker SSOT-bearing edit detected at ${FILE_PATH}
 
 動到 (tagRenderer / overflowShape / tagWrapperClassName / placeholder logic / MultiPersonDisplay 等) — 這些是 PeoplePicker SSOT-bearing API,不是 Combobox / Select 純繼承。
@@ -49,7 +49,7 @@ if echo "$NEW_CONTENT" | grep -qE "$SSOT_KEYWORDS"; then
   §F Cell-edit ↔ Field-edit 一致性 - 動 cell-registry MultiPersonCell / form PeoplePicker → 此處"
 
     ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
-    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+    printf '{"governanceContext":{"hookEventName":"PostToolUse","message":%s}}\n' "$ESCAPED"
   fi
 fi
 

package/ds-canonical/hooks/check_pixel_quantified_audit.sh

@@ -6,7 +6,8 @@
 #   `getAttribute('data-state')` / `class.includes('items-start')` attribute-existence
 #   = false-positive trap(DOM-structure-pass ≠ visual-pass)。
 #
-# Mechanical rule:scripts/visual-audit-*.mjs(or *.js)若有 `getAttribute(` 但沒 paired
+# Mechanical rule:scripts/visual-audit*.mjs(or *.js;含 canonical scripts/visual-audit.mjs,
+# 舊 visual-audit-<target>.mjs 家族已於 2026-05-30 a2360e99 整批 retire)若有 `getAttribute(` 但沒 paired
 # `getBoundingClientRect(` 或 `offsetTop/.offsetHeight` 量化 measurement → warn。
 #
 # 對齊 Material X-DataGrid visual regression / AG Grid playwright pixel snapshot canonical。
@@ -21,14 +22,15 @@ EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
 
 case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
 case "$FILE_PATH" in
-  */scripts/visual-audit-*.mjs|*/scripts/visual-audit-*.js) ;;
+  */scripts/visual-audit*.mjs|*/scripts/visual-audit*.js) ;;
   *) exit 0 ;;
 esac
 [ "$EVENT" != "PostToolUse" ] && exit 0
 [ ! -f "$FILE_PATH" ] && exit 0
 
 # Allowlist
-head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@pixel-quantified-allow:' && exit 0
+FILE_HEAD3=$(sed -n '1,3p' "$FILE_PATH")
+grep -qE '//[[:space:]]*@pixel-quantified-allow:' <<<"$FILE_HEAD3" && exit 0
 
 # Count getAttribute calls vs getBoundingClientRect / offsetTop / offsetHeight calls
 # 2026-05-23 bug fix:`grep -c ... 2>/dev/null || echo 0` 當 zero match 時 grep exit 1 + fallback echo,
@@ -48,6 +50,6 @@ ${FILE_PATH}:
     加 numeric pixel measurement(rect.top / .left / .height)真實 verify 視覺,
     或檔首加 // @pixel-quantified-allow: <reason>(structural-only audit 例如 schema check)。"
   jq -n --arg ctx "$CTX" '{
-    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+    governanceContext: { hookEventName: "PostToolUse", message: $ctx }
   }'
 fi

package/ds-canonical/hooks/check_plugin_fork_health.sh

@@ -0,0 +1,282 @@
+#!/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 標記不變)
+# 原檔 → packages/design-system/ds-canonical/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
+_PROVIDER_PATHS="$(dirname "$0")/lib/_provider_paths.sh"
+if [ ! -f "$_PROVIDER_PATHS" ] || [ -L "$_PROVIDER_PATHS" ]; then
+  printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: canonical provider resolver 缺失、symlink 或不是一般檔案\n' >&2
+  exit 70
+fi
+source "$_PROVIDER_PATHS" 2>/dev/null || {
+  printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: canonical provider resolver unavailable\n' >&2
+  exit 70
+}
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null) || {
+  printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: 無法讀取 canonical input\n' >&2
+  exit 70
+}
+if ! printf '%s' "$INPUT" | jq -e 'type == "object"' >/dev/null 2>&1; then
+  printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: invalid input envelope\n' >&2
+  exit 70
+fi
+ACTIVE_PROVIDER="${GOVERNANCE_PROVIDER:-${GOVERNANCE_SELF_PROVIDER:-}}"
+governance_provider_string_field instructionEntry >/dev/null 2>&1 || {
+  printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: provider is absent from canonical registry:%s\n' "${ACTIVE_PROVIDER:-<missing>}" >&2
+  exit 70
+}
+PROJECT_ROOT="$(governance_project_root)" || {
+  printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: project root is unavailable\n' >&2
+  exit 70
+}
+
+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="$PROJECT_ROOT"
+
+# (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) C-prime committed 治理鏈健康?(2026-07-04 dim 58 對齊:主路徑 = committed-config + npm,
+# 免 plugin — 2026-06-17 C-prime 改版,plugin 路線不可靠 per memory reference_cloud_governance_loading)
+# dispatcher(committed 啟動器)+ manifest(npm ship 治理本體)都在 → 官方 fork hooks 會 fire → 健康。
+DISPATCHER="$CWD/governance/bin/fork-governance-dispatcher.sh"
+MANIFEST="$CWD/node_modules/@qijenchen/design-system/ds-canonical/fork/manifest.json"
+if [ -f "$DISPATCHER" ] && [ -f "$MANIFEST" ]; then
+  exit 0
+fi
+
+# (d) A legacy provider plugin is compatibility feedback only. It never satisfies the shared
+# runtime health contract and must not hide a missing dispatcher/manifest on one provider while
+# every other provider correctly reports degraded. r2 may inspect it only for a non-authoritative
+# compatibility notice after this neutral health result is established.
+
+# 治理鏈缺失 → context inject(SessionStart additional context),修法 = canonical one-command setup(免 plugin)
+if jq -e '.scripts["setup:all"]' "$CWD/package.json" >/dev/null 2>&1; then
+  PUBLIC_SETUP_CMD="npm run setup:all"
+elif jq -e '.scripts["setup:governance"]' "$CWD/package.json" >/dev/null 2>&1; then
+  PUBLIC_SETUP_CMD="npm run setup:governance   # legacy consumer fallback;current template uses setup:all"
+else
+  PUBLIC_SETUP_CMD="GOVERNANCE-SETUP-MISSING:以 reviewed full-snapshot template bootstrap PR 恢復 setup/lock 後再執行"
+fi
+if [ -f "$DISPATCHER" ]; then
+  MISSING_DESC="接線骨架(dispatcher)已 commit ✅,但治理本體 manifest 不在 node_modules ❌(setup:all 尚未完成)"
+  FIX_CMD="$PUBLIC_SETUP_CMD   # 依 committed exact lock 安裝、驗簽、跑 role hard gate 並 provision peer CLI"
+else
+  MISSING_DESC="C-prime 接線骨架(governance/bin/fork-governance-dispatcher.sh)不存在 ❌(fork 尚未 adopt provider-neutral runtime)"
+  FIX_CMD="先以 reviewed full-snapshot template bootstrap PR 補齊接線;merge 後跑 npm run setup:all(禁止 mutable tag 自助 bootstrap)"
+fi
+
+cat <<EOF
+🚨 Fork-user DS 治理鏈未就位 — 官方 fork governance hooks 不會 fire,憑記憶寫 mock 不會被攔。
+
+偵測:
+  cwd = $CWD
+  package.json 含 @qijenchen/design-system dep ✅
+  $MISSING_DESC
+
+→ 後果(2026-05-26 anchor event):憑記憶寫 App.tsx mock(漏 SidebarTrigger / collapsible / startIcon /
+  tooltip / SidebarFooter)= production-grade fork-user 跑版 anti-pattern。
+
+修法(**免 /plugin install;正確 template checkout 只需 1 條 setup 指令**):
+  $FIX_CMD
+
+就位後:
+  - fork-governance-dispatcher.sh 每 event 讀 node_modules 官方 manifest 跑全部 fork 治理 hooks(BLOCKER 會轉發攔截)
+  - DS canonical / rules / skills 從 node_modules/@qijenchen/design-system/ds-canonical/ cross-load
+  - 憑記憶寫 mock 會被 mechanical BLOCKER 攔
+
+對應 canonical:
+  - template AGENTS.md「🚀 Onboarding(C-prime)」段(provider adapter 可建立自己的 instruction view)
+  - ds-canonical/fork/manifest.json(build-fork-governance.mjs 生成)
+EOF
+exit 0
+}
+
+r2_plugin_freshness() {
+set -uo pipefail
+
+# Remote marketplace freshness belongs to the Claude plugin compatibility surface. The neutral
+# npm runtime is version-pinned by manifest/lock checks elsewhere, so non-Claude providers neither
+# read Claude HOME nor perform this legacy network probe.
+[ "$ACTIVE_PROVIDER" = "claude" ] || exit 0
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+case "${EVENT:-}" in
+  SessionStart) ;;
+  *) exit 0 ;;
+esac
+
+# 2026-07-16 dim 75 修:DS repo 本身 early-exit(對齊 r1 guard (a))。原本無此 guard →
+# candidate 3(.claude-plugin/plugin.json 在 DS repo 存在)讓 r2 在 DS repo fire,
+# 印 `npm run sync-all` 但 DS root package.json 無此 script(sync-all 是 fork/template 的
+# consumer script,見 template/ds-product-template/package.json)= 指引斷鏈;
+# 且 DS repo 是 SSOT 源頭,local 版本領先 published 是開發常態,不該 nag。
+[ -d "$PROJECT_ROOT/packages/design-system/src" ] && exit 0
+
+# Only DS consumers participate in this control plane. A globally installed
+# legacy plugin must not make unrelated repositories perform network checks or
+# receive governance upgrade guidance.
+[ -f "$PROJECT_ROOT/package.json" ] || exit 0
+grep -q '"@qijenchen/design-system"' "$PROJECT_ROOT/package.json" 2>/dev/null || exit 0
+
+# Find local plugin.json (DS plugin install path)
+PLUGIN_JSON=""
+CLAUDE_HOME="${HOME:-}"
+PLUGIN_CANDIDATES=("$PROJECT_ROOT/.claude-plugin/plugin.json")
+if [ -n "$CLAUDE_HOME" ]; then
+  PLUGIN_CANDIDATES=(
+    "$CLAUDE_HOME/.claude/plugins/design-system@qijenchen-ds/plugin.json"
+    "$CLAUDE_HOME/.claude/plugins/cache/design-system/plugin.json"
+    "${PLUGIN_CANDIDATES[@]}"
+  )
+fi
+for candidate in "${PLUGIN_CANDIDATES[@]}"
+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). Network failure, timeout, an empty
+# response, or malformed/nonconforming JSON is an explicit compatibility-probe skip. Keep each
+# fallible command in a conditional so an inherited errexit/pipefail state cannot turn this
+# non-authoritative probe into an undefined child exit.
+REMOTE_BODY=""
+if ! REMOTE_BODY=$(curl -sS --max-time 5 \
+  "https://raw.githubusercontent.com/ajenchen/design-system/main/.claude-plugin/marketplace.json" \
+  2>/dev/null); then
+  exit 0
+fi
+[ -n "$REMOTE_BODY" ] || exit 0
+REMOTE_VERSION=""
+if ! REMOTE_VERSION=$(printf '%s' "$REMOTE_BODY" \
+  | jq -er 'if type == "object" and (.metadata | type == "object") and (.metadata.version | type == "string") and (.metadata.version | length > 0) then .metadata.version else empty end' \
+      2>/dev/null); then
+  exit 0
+fi
+
+if [ "$LOCAL_VERSION" != "$REMOTE_VERSION" ]; then
+  # Dim 75 current contract:the marketplace version is a Claude-only compatibility diagnostic,
+  # never an upgrade authority. Verify the repository's committed exact version; package upgrades
+  # arrive only through a reviewed exact-version PR.
+  if jq -e '.scripts["setup:all"]' "$PROJECT_ROOT/package.json" >/dev/null 2>&1; then
+    SETUP_CMD="npm run setup:all"
+  elif jq -e '.scripts["setup:governance"]' "$PROJECT_ROOT/package.json" >/dev/null 2>&1; then
+    SETUP_CMD="npm run setup:governance   # legacy consumer fallback"
+  elif [ -f "$PROJECT_ROOT/scripts/setup-governance.mjs" ]; then
+    SETUP_CMD="node scripts/setup-governance.mjs"
+  elif jq -e '.scripts["sync-all"]' "$PROJECT_ROOT/package.json" >/dev/null 2>&1; then
+    SETUP_CMD="npm run sync-all   # 僅接受 authenticated exact-version transition"
+  elif [ -f "$PROJECT_ROOT/scripts/sync-all.mjs" ]; then
+    SETUP_CMD="node scripts/sync-all.mjs   # 僅接受 authenticated exact-version transition"
+  else
+    SETUP_CMD="GOVERNANCE-SETUP-MISSING:以 reviewed full-snapshot template bootstrap PR 恢復 setup/lock 後再執行"
+  fi
+  cat << EOF
+
+📦 Legacy Claude plugin compatibility version differs(non-authoritative):
+   Local legacy plugin: $LOCAL_VERSION
+   Marketplace metadata: $REMOTE_VERSION
+
+Verify the repository's committed exact governance version:
+  $SETUP_CMD
+
+Package/provider upgrades must arrive through a reviewed exact-version PR. Never install a mutable
+dist-tag from this notice; marketplace metadata is not current governance certification.
+
+(This compatibility notice does not replace governance/lock.json, the installed checker, or protected CI.)
+
+EOF
+fi
+
+exit 0
+}
+
+_CAPTURE_DIR=$(mktemp -d "${TMPDIR:-/tmp}/check-plugin-fork-health.XXXXXX") || {
+  printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: output capture unavailable\n' >&2
+  exit 70
+}
+trap 'rm -rf -- "$_CAPTURE_DIR"' EXIT
+CONTEXTS=""
+_RULE_INDEX=0
+for _rule in r1_plugin_install r2_plugin_freshness; do
+  _RULE_INDEX=$((_RULE_INDEX + 1))
+  _stdout="$_CAPTURE_DIR/$_RULE_INDEX.stdout"
+  _stderr="$_CAPTURE_DIR/$_RULE_INDEX.stderr"
+  printf '%s' "$INPUT" | "$_rule" >"$_stdout" 2>"$_stderr"
+  _rc=$?
+  case "$_rc" in
+    0)
+      if [ -s "$_stderr" ]; then
+        printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: rule %s rc0 產生 raw stderr\n' \
+          "$_rule" >&2
+        exit 70
+      fi
+      if [ -s "$_stdout" ]; then
+        _output=$(cat "$_stdout")
+        if [ -n "$CONTEXTS" ]; then
+          CONTEXTS="${CONTEXTS}"$'\n\n'"$_output"
+        else
+          CONTEXTS="$_output"
+        fi
+      fi
+      ;;
+    2)
+      if [ ! -s "$_stdout" ] && [ -s "$_stderr" ] \
+        && ! grep -qF 'GOVERNANCE_INTEGRITY:' "$_stderr"; then
+        cat "$_stderr" >&2
+        exit 2
+      fi
+      printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: rule %s rc2 必須是 stderr-only nonempty policy blocker\n' \
+        "$_rule" >&2
+      exit 70
+      ;;
+    70)
+      if [ ! -s "$_stdout" ] && [ -s "$_stderr" ] \
+        && grep -qF 'GOVERNANCE_INTEGRITY:' "$_stderr"; then
+        cat "$_stderr" >&2
+      else
+        printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: rule %s rc70 必須是 stderr-only marker\n' \
+          "$_rule" >&2
+      fi
+      exit 70
+      ;;
+    *)
+      printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: rule %s 回傳未定義 exit code %s\n' \
+        "$_rule" "$_rc" >&2
+      exit 70
+      ;;
+  esac
+done
+if [ -n "$CONTEXTS" ]; then
+  _encoded_contexts=$(printf '%s' "$CONTEXTS" | jq -Rs .) || {
+    printf '🚨 GOVERNANCE_INTEGRITY: PLUGIN/FORK HEALTH FAILURE: combined context 無法編碼\n' >&2
+    exit 70
+  }
+  printf '{"governanceContext":{"hookEventName":"SessionStart","message":%s}}\n' "$_encoded_contexts"
+fi
+exit 0