@qijenchen/design-system 0.1.0-beta.69 → 0.1.0-beta.71

package/ds-canonical/fork/hooks/check_ds_anchor_preflight.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# check_ds_anchor_preflight.sh — M29 mechanical enforcement(2026-05-26 backfill per user verbatim
+# 「該程式化的都沒程式化,導致你他媽那麼容易便宜」+「未來其他人 fork 用其他元件也偏移」)。
+#
+# Purpose: PreToolUse Edit/Write/MultiEdit 偵測 production tsx wrap DS primitive
+# (`<Sidebar>` / `<AppShell>` / `<DataTable>` / `<Dialog>` / `<Field>` 等)
+# 沒同 turn 跑過 Grep / Read DS canonical baseline → 軟 BLOCKER 提醒 propose 前必出 3-column owner table。
+#
+# Scope:同 check_substantive_edit_approval_preflight.sh extended scope
+#   - node_modules/@qijenchen/design-system/src/**.tsx (DS internal)
+#   - apps/**.tsx (consumer fork-user code) ← M29 gap absorption(2026-05-26)
+#   - node_modules/@qijenchen/design-system/** (禁改)
+#
+# Excluded: *.stories.tsx (story_invariants R7/R8 already cover) / *.test.tsx / *.spec.md.
+#
+# Why mechanical:M29 anchor preflight 在 meta-patterns.md 喊很久,5 個文件 reference but file 0,
+# 結果 2026-05-26 product-workspace App.tsx mock-drift 沒被攔 → user 抓「肌肉沒長出來」。
+# 本 hook 將「propose / write 視覺結構 前必 grep DS spec.md / canonical story」從 mindset 升 mechanical。
+#
+# Detection:scan transcript 過去 ~30 turns:
+#   (a) 有 Grep / Read tool call hit `node_modules/@qijenchen/design-system/src/**/*.spec.md` OR
+#       `**/*.stories.tsx`(canonical baseline) → PASS
+#   (b) 無 → soft BLOCKER inject context 提醒 grep canonical 出 3-column owner table。
+#
+# 對齊 meta-patterns.md M29 「視覺/結構 propose 前必 grep DS spec.md 找 owner SSOT(M29)— 出 3-column 表」+
+# .claude/rules/self-verify.md Pre-edit phase「M29 3-column owner table」。
+
+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)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+[ "$EVENT" != "PreToolUse" ] && exit 0
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+
+# Scope:DS production code + consumer fork-user app code(不含 stories / spec / test)
+case "$FILE_PATH" in
+  */node_modules/@qijenchen/design-system/src/*.tsx) ;;
+  */apps/*.tsx) ;;
+  */node_modules/@qijenchen/design-system/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+case "$FILE_PATH" in
+  *.stories.tsx|*.test.tsx|*.spec.md|*.spec.ts) exit 0 ;;
+esac
+
+# Extract content being written/edited
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null)
+
+# DS primitive 名單(wrap 這些就觸發 anchor preflight)
+DS_PRIMITIVES_RE='<(Sidebar|AppShell|DataTable|Dialog|Sheet|Popover|DropdownMenu|Field|FieldControlGroup|MenuItem|ItemAvatar|ItemLabel|ItemIcon|SegmentedControl|Tabs|TabsList|TabsTrigger|Combobox|Select|DatePicker|TimePicker|TreeView|Tooltip|Coachmark|FileViewer|ScrollArea|Avatar|Badge|Button|ChromeHeader|SurfaceHeader|SurfaceBody|SurfaceFooter|OverlaySurface|NameCard|Toast|FileUpload|DescriptionList|Chart|BulkActionBar|ActionBar|Carousel|Breadcrumb)\b'
+
+# 沒 wrap DS primitive → 跳過(可能是純 utility / hook code)
+if ! echo "$NEW_CONTENT" | grep -qE "$DS_PRIMITIVES_RE"; then
+  exit 0
+fi
+
+[ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ] && exit 0
+
+# Scan last ~30 turns(~600 lines transcript)— 找 Grep/Read 對 DS spec.md / canonical story 的 trace
+RECENT_TRANSCRIPT=$(tail -600 "$TRANSCRIPT_PATH" 2>/dev/null)
+
+# Pass condition(a):有 Grep tool call pattern hit spec.md / stories.tsx
+HAS_CANONICAL_READ=$(echo "$RECENT_TRANSCRIPT" | \
+  jq -r 'select(.message.content != null) |
+    .message.content // empty |
+    if type == "array" then
+      (.[]? | select(.type == "tool_use") |
+        select(.name == "Grep" or .name == "Read" or .name == "Glob") |
+        .input | tostring)
+    else empty
+    end' 2>/dev/null | \
+  grep -cE 'node_modules/@qijenchen/design-system/src/.*\.(spec\.md|stories\.tsx)|stories\.tsx#' 2>/dev/null)
+HAS_CANONICAL_READ=${HAS_CANONICAL_READ:-0}
+
+# Pass condition(b):AI 已 written 3-column owner table OR cite `@story-baseline:` marker
+HAS_3COL_OR_MARKER=$(echo "$RECENT_TRANSCRIPT" | \
+  grep -cE '@story-baseline:|owner spec|canonical sentence|3-column' 2>/dev/null)
+HAS_3COL_OR_MARKER=${HAS_3COL_OR_MARKER:-0}
+
+# Pass: 有任一 canonical read OR 3-column marker → silent
+if [ "$HAS_CANONICAL_READ" -gt 0 ] || [ "$HAS_3COL_OR_MARKER" -gt 0 ]; then
+  exit 0
+fi
+
+# Override env var(audit-logged)
+if [ "${CLAUDE_BYPASS_DS_ANCHOR:-0}" = "1" ]; then
+  mkdir -p "$(dirname "$0")/../logs" 2>/dev/null
+  printf '{"ts":"%s","event":"ds-anchor-bypass","file":"%s","tool":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$FILE_PATH" "$TOOL" >> "$(dirname "$0")/../logs/governance-bypass.jsonl" 2>/dev/null
+  exit 0
+fi
+
+REL_PATH=${FILE_PATH#"$CLAUDE_PROJECT_DIR"/}
+
+# Soft BLOCKER(對齊 check_substantive_edit_approval_preflight.sh hybrid pattern)
+cat >&2 <<EOF
+🚨 M29 DS Anchor Preflight — visual/structural edit 偵測
+
+📁 File: $REL_PATH
+🔧 Tool: $TOOL
+🧩 偵測到 DS primitive 在 new content:wrap pattern
+
+⚠️ 過去 ~30 turns 無 Grep/Read 對 \`node_modules/@qijenchen/design-system/src/**/spec.md\` 或
+   \`*.stories.tsx\` baseline 的 trace,且未見 \`@story-baseline:\` marker 或 3-column owner table。
+
+→ 這違反 M29 anchor preflight invariant + story-rules.md「Production-grade composition fidelity」。
+→ 對 fork-user 後果:憑記憶寫 simplified mock(像 2026-05-26 App.tsx SidebarTrigger 漏 / collapsible 漏 / startIcon 漏)。
+
+修法 — 2 選 1(對齊 check_substantive_edit_approval_preflight.sh hybrid):
+  (a) 先 Grep / Read DS canonical:
+        - \`node_modules/@qijenchen/design-system/src/<Component>/*.spec.md\`(找 owner SSOT)
+        - \`node_modules/@qijenchen/design-system/src/<Component>/*.stories.tsx\`(找完整佈局 baseline)
+      然後 inline 寫 3-column owner table(\`owner spec\` / \`canonical sentence\` / \`conflicting code\`)
+      或加 \`// @story-baseline: <path>#<StoryName>\` marker 在檔頭。
+  (b) Bypass:\`CLAUDE_BYPASS_DS_ANCHOR=1\` env var(audit-logged in governance-bypass.jsonl)
+      僅當你**真的**已 Read canonical 但 transcript scan miss 時用,not 規則繞道。
+
+對應 canonical:
+  - \`.claude/rules/meta-patterns.md\` M29
+  - \`.claude/rules/self-verify.md\` Pre-edit phase
+  - \`.claude/references/ssot-index.md\` Step 0.1 high-risk interface owner mapping
+EOF
+
+# Soft warn (exit 0):inject context 讓 AI 自決,Stop hook backstop。
+# 對齊 check_substantive_edit_approval_preflight.sh hybrid pattern(soft pre + hard stop)。
+exit 0

package/ds-canonical/fork/hooks/check_escape_marker_abuse.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# check_escape_marker_abuse.sh — P0 BLOCKER (codify warning)
+#
+# 偵測 consumer code(.tsx/.stories.tsx)濫用 escape markers 跳 SSOT enforcement.
+# Per user 2026-05-27 verbatim「不亂加 escape markers — 加就跳 enforcement」.
+#
+# Escape markers exist for真 exceptions(per-line documented rationale)。但 fork
+# user 若大量加 escape markers (eg. ≥3 同一 file) = 違反 escape philosophy → BLOCK.
+#
+# Detected markers:
+#   - @ds-misuse-allow:    (check_consumer_ds_primitive_misuse.sh escape)
+#   - @story-baseline-allow:(check_consumer_story_baseline.sh escape)
+#   - @consumer-catalog-allow:(check_consumer_no_ds_catalog.sh escape)
+#   - @overlay-open-skip:  (check_overlay_open_focus_escape_probe.sh escape)
+#   - @template-customized (template canonical sync opt-out)
+#   - @layout-space-magic-ok:(check_layout_space_magic_numbers.sh escape)
+#   - @story-trait-allow:  (story-baseline / catalog escape)
+#   - @story-trait-rationale:(check_story_invariants.sh R3 escape)
+#   - @story-split-rationale:(check_story_invariants.sh R2 escape)
+#   - @story-name-canonical-allow:(check_story_invariants.sh R4 escape)
+#   - @propose-cite-skip:  (check_propose_cite_required.sh escape)
+#   - @anatomy-exempt:     (story-rules escape)
+#   - @anatomy-exempt-next:(story-rules per-line escape)
+#   - @benchmark-unverified: (M22 cite)
+#   - @benchmark-citation-allow / @benchmark-unverified-blanket (M22 file-level cite escapes)
+#
+# Threshold:≥3 distinct markers OR ≥5 total occurrences in same file → BLOCK
+# Forces fork user to either (a) fix root cause OR (b) refactor properly OR
+# (c) explicitly cite reason in commit message via env override.
+#
+# 2026-05-31 升級(per 3-hardening-items 調查,折進本 hook 不新增檔):
+#   1. Justification gate:escape marker 後空理由(@x-allow: 後純空白 / bare @benchmark-unverified)
+#      = 靜默繞過 SSOT → BLOCK(consumer + DS source 都跑)。對齊 ESLint require-description / Google NOLINT。
+#   2. Scope 擴 DS source(node_modules/@qijenchen/design-system/src tsx/ts):原整段 skip 讓 DS 內 marker 不受 justification
+#      約束;現 DS 跑 justification gate 但跳過 ≥3/≥5 數量 gate(DS 有大量 legit exception 避免誤殺）。
+#   3. MARKER_RE 廣化(M7/M34 broad):@<x>-allow 家族用廣義 regex 自動納管,免 enum drift。
+
+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)
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+# Scope 分流(2026-05-31 加 DS source — 原整段 skip 讓 DS 內 143 個 marker 不受任何 justification 約束):
+#   IS_CONSUMER=apps/consumer tsx/ts → 跑 justification gate + 數量 gate(≥3/≥5)
+#   IS_DS=node_modules/@qijenchen/design-system/src tsx/ts → 只跑 justification gate(DS 有大量 legit exception,不套數量上限避免誤殺)
+IS_CONSUMER=0; IS_DS=0
+if echo "$FILE" | grep -qE '/(apps|consumer)/.*\.(tsx|ts)$'; then IS_CONSUMER=1; fi
+if echo "$FILE" | grep -qE 'node_modules/@qijenchen/design-system/src/.*\.(tsx|ts)$'; then IS_DS=1; fi
+if [ "$IS_CONSUMER" -eq 0 ] && [ "$IS_DS" -eq 0 ]; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# Global escape — meta-skip(env override OR explicit comment)
+if [ "${CLAUDE_BYPASS_ESCAPE_MARKER_AUDIT:-0}" = "1" ]; then exit 0; fi
+
+# ── Justification gate(2026-05-31,折進本 hook;核心 real gap)──────────────────
+# Escape marker 必帶 per-line rationale。空理由 = 靜默繞過 SSOT enforcement。
+#   (a) @<x>-allow: 後純空白到行尾(有 marker 有冒號但無理由)
+#   (b) bare @benchmark-unverified 後純空白到行尾(非 -blanket / 非 ": 理由" / 非後接說明文字)
+# 對齊 ESLint eslint-comments/require-description + Google NOLINT(category) 必帶說明。
+EMPTY_RATIONALE=$(echo "$CONTENT" | grep -nE '@[a-z][a-z-]+-allow:[[:space:]]*$|@benchmark-unverified[[:space:]]*$' || true)
+if [ -n "$EMPTY_RATIONALE" ]; then
+  cat >&2 << EOF
+🚨 ESCAPE-MARKER-NO-RATIONALE BLOCKER(P0,2026-05-31 folded into check_escape_marker_abuse)
+
+  File $FILE — escape marker 後無 rationale(空理由 = 靜默繞過 SSOT):
+$(echo "$EMPTY_RATIONALE" | sed 's/^/    /')
+
+  修法:marker 冒號後寫具體理由,eg.
+    // @ds-misuse-allow: Notion-style inline edit canonical(Field 在 cell 內編輯)
+    /* @benchmark-unverified: AG Grid pixel-snapshot 共識,待補 URL cite */
+
+  Escape directive 世界級共識(ESLint require-description / Google NOLINT)必帶 rationale。
+EOF
+  exit 2
+fi
+
+# ── Sanctioned portal 檔 allowlist(2026-06-11 R2 held-item #10)──────────────
+# AllDsComponents.stories.tsx 是 documented DS proxy portal(檔頭 @anatomy-exempt +
+# @consumer-catalog-allow per 2026-05-27 M31 codex synthesis + @layout-space-magic-ok
+# dev-artifact 豁免)— 3 個 marker 各帶 rationale 是它的 sanctioned 常態,數量 gate
+# (≥3 distinct)對它必誤擋 = hook-vs-hook 張力。只豁免數量 gate;justification gate
+# (空理由 BLOCK)上方已跑完照常生效,真保護不削弱。
+IS_SANCTIONED_PORTAL=0
+case "$FILE" in
+  *apps/*/src/AllDsComponents.stories.tsx) IS_SANCTIONED_PORTAL=1 ;;
+esac
+
+# ── 數量 gate(≥3 distinct / ≥5 total）— 僅 consumer(DS source 有大量 legit exception,只走上方 justification gate）──
+# 2026-06-11 R2 Phase B(codex b3 抓縫):portal 無限豁免會放走「第 4、5 個新增 marker」——
+# 改為提高閾值(portal ≥6 / 一般 ≥3)保留 ceiling,justification gate 不變。
+if [ "$IS_SANCTIONED_PORTAL" -eq 1 ]; then DISTINCT_CAP=6; else DISTINCT_CAP=3; fi
+if [ "$IS_CONSUMER" -eq 1 ]; then
+  # 2026-05-31 廣化 MARKER_RE(M7/M34:spec wording broad「任何 escape marker」→ hook regex 不該 narrow 只 16 種):
+  # @<x>-allow 家族用廣義 [a-z][a-z-]*-allow 自動納管(免每次補 enum drift)+ 非 -allow markers 顯式列。
+  MARKER_RE='@([a-z][a-z-]*-allow|benchmark-unverified(-blanket)?|template-customized|anatomy-exempt(-next)?|overlay-open-skip|layout-space-magic-ok|propose-cite-skip|story-(trait|split)-rationale)'
+  MARKERS_FOUND=$(echo "$CONTENT" | grep -oE "$MARKER_RE" | sort -u)
+  # 2026-05-30 fix(test-surfaced):空 MARKERS_FOUND 時 grep -c 印 "0" 已 exit 1,原 `|| echo 0`
+  # 會再 append 一個 "0" → "0\n0" → 下方 `[ -ge "$DISTINCT_CAP" ]` integer-expression error。改 `|| true` 不重複。
+  DISTINCT_COUNT=$(echo "$MARKERS_FOUND" | grep -c . || true)
+  [ -z "$DISTINCT_COUNT" ] && DISTINCT_COUNT=0
+  TOTAL_COUNT=$(echo "$CONTENT" | grep -oE "$MARKER_RE" | wc -l | tr -d ' ')
+
+  # Threshold: ≥3 distinct types OR ≥5 total
+  if [ "$DISTINCT_COUNT" -ge 3 ] || [ "$TOTAL_COUNT" -ge 5 ]; then
+    cat >&2 << EOF
+🚨 ESCAPE-MARKER-ABUSE BLOCKER(P0,user 2026-05-27 verbatim「不亂加 escape markers — 加就跳 enforcement」)
+
+  File $FILE:
+    Distinct escape markers: $DISTINCT_COUNT(threshold ≥3)
+    Total occurrences: $TOTAL_COUNT(threshold ≥5)
+
+  Markers detected:
+$(echo "$MARKERS_FOUND" | sed 's/^/    /')
+
+  Escape markers 設計為「rare per-line documented exception」,不該 routine 加。
+  Fork user file 大量加 marker = 違反 SSOT 哲學 — 應該:
+
+  修法 3 選 1:
+    (a) **重構 code** 走 DS canonical pattern(消除根因,不繞)
+    (b) **拆 file**:1 個 escape 對應 1 個 specific case,分散到不同 file
+    (c) **Override env**(極罕見,documented in commit msg):
+        CLAUDE_BYPASS_ESCAPE_MARKER_AUDIT=1 git commit -m "<rationale>"
+
+  per check_consumer_*.sh hooks SSOT — escape 是 emergency exit,不是 daily tool.
+EOF
+    exit 2
+  fi
+fi
+
+exit 0

package/ds-canonical/fork/hooks/check_field_family_invariants.sh

@@ -0,0 +1,250 @@
+#!/bin/bash
+# Field family unified invariant hook(2026-05-08 cluster A consolidation)
+#
+# Merges PreToolUse hooks(原各檔已 retire,合併入此)— 共 5 條 sub-rules:
+#   A.1 naked row-mode propagation(原 check_naked_row_mode_propagation,P0 BLOCKER)
+#   A.2 FieldControlGroup wrapper direct child(原 check_field_control_group_direct_child,P1 WARN)
+#   A.3 Field state ring SSOT(原 check_field_state_token_consume 3 sub-rules,P0 BLOCKER)
+#   A.4 disabled placeholder color(原 check_disabled_placeholder_color,P1 stderr only)
+#   A.5 _Group child fieldCtx.id 隔離(2026-05-31 折入,M4 AR34 regression detector,P0 BLOCKER)
+#
+# Why merge:皆 Field 家族 invariant,共用 INPUT parsing + Edit/Write filter pattern,
+#   分散在 4 個 hook 是「散裝 SSOT」(M17 + Anthropic ≤ 15 hook best practice 違反)。
+#
+# Exit code precedence:BLOCK(2)> WARN(1)> INFO(0)。每 rule 可獨立觸發,worst 勝。
+#
+# Per-rule allowlist(各自獨立):
+#   A.1: `// @naked-row-mode-allow: <reason>`
+#   A.2: `// @fcg-wrapper-allow: <reason>` 或檔頭
+#   A.3: `// @field-state-ring-allow: <reason>`
+#   A.4: `// @disabled-color-allow: <reason>`
+#   A.5: `// @group-fieldctx-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 // ""')
+
+# Tool filter — 只 Edit/Write/MultiEdit 跑
+case "$TOOL" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# 不是 .tsx / .ts 直接過(各 rule 內部還會再 narrow)
+case "$FILE_PATH" in
+  *.tsx|*.ts) ;;
+  *) exit 0 ;;
+esac
+
+# 讀 merged content(舊檔 + 新 edit 拼起)— A.1 / A.3 需要整檔判 naked variant 存在性
+FILE_CONTENT=""
+if [ -f "$FILE_PATH" ]; then
+  FILE_CONTENT=$(cat "$FILE_PATH")
+fi
+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 "")
+
+# A.2 / A.4 只看 NEW_CONTENT(diff-level signal),A.1 / A.3 看 MERGED
+MERGED_CONTENT="${FILE_CONTENT}
+${NEW_CONTENT}"
+
+[ -z "${MERGED_CONTENT//[[:space:]]/}" ] && exit 0
+
+WORST=0
+record_worst() { local lvl=$1; [ "$lvl" -gt "$WORST" ] && WORST=$lvl; }
+
+# ── A.1 naked row-mode propagation(P0 BLOCKER)─────────────────────────────────
+case "$FILE_PATH" in
+  *components/*.tsx)
+    case "$FILE_PATH" in
+      */field-wrapper.tsx|*/textarea.tsx) ;; # SSOT host skip
+      *)
+        if ! echo "$MERGED_CONTENT" | grep -q '@naked-row-mode-allow' \
+           && echo "$MERGED_CONTENT" | grep -E "variant:\s*['\"]naked['\"]|variant=\{?['\"]naked['\"]" >/dev/null \
+           && echo "$MERGED_CONTENT" | tr '\n' ' ' | grep -E "(inline-flex|flex)[^\"'\`]*items-center" >/dev/null \
+           && ! echo "$MERGED_CONTENT" | grep -q "nakedCellRowModeAlign"; then
+          cat >&2 <<EOF
+
+┄┄┄ A.1 check_field_family_invariants — naked row-mode propagation BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測到此檔消費 \`variant="naked"\` + 內部 wrapper hardcode \`items-center\`,
+但**未** import / apply \`nakedCellRowModeAlign\` SSOT。
+
+⚠️  M19 canonical:naked variant 元件所有內部 wrapper 必 propagate host cell
+    \`data-row-mode\`(autoRow→items-start / fixed→items-center)。
+
+修法:
+  1. import { nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'
+  2. wrapper className 加上 SSOT(eg \`cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign)\`)
+  3. 例外:行尾 \`// @naked-row-mode-allow: <reason>\`
+
+EOF
+          record_worst 2
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+# ── A.2 FieldControlGroup wrapper direct child(P1 WARN)────────────────────────
+case "$FILE_PATH" in
+  *.tsx)
+    if echo "$NEW_CONTENT" | grep -q '<FieldControlGroup' \
+       && ! echo "$NEW_CONTENT" | grep -q '@fcg-wrapper-allow'; then
+      SUSPECT=$(printf '%s' "$NEW_CONTENT" | awk '
+        /<FieldControlGroup/ { inFCG=1; next }
+        /<\/FieldControlGroup>/ { inFCG=0; next }
+        inFCG && /^[[:space:]]*<(div|span)[[:space:]>]/ {
+          if ($0 !~ /display:[[:space:]]*contents/ && $0 !~ /@fcg-wrapper-allow/) print NR ":" $0
+        }
+      ')
+      if [ -n "$SUSPECT" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ A.2 check_field_family_invariants — FieldControlGroup wrapper WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+偵測到 FieldControlGroup 內有 \`<div>\` / \`<span>\` wrapper(可能破壞 CSS \`[&>*]\` variants):
+${SUSPECT}
+
+修法 3 擇 1:
+  1. 移除 wrapper,Field control 直接是 FieldControlGroup direct child
+  2. 透過 prop forward className(eg \`<FilterValuePicker className="flex-1 min-w-0">\`)
+  3. wrapper 用 \`display:contents\` / 加 \`// @fcg-wrapper-allow: <reason>\`
+
+EOF
+        record_worst 1
+      fi
+    fi
+    ;;
+esac
+
+# ── A.3 Field state ring SSOT(P0 BLOCKER,3 sub-rules)─────────────────────────
+case "$FILE_PATH" in
+  *components/*.tsx)
+    case "$FILE_PATH" in
+      */field-wrapper.tsx|*/textarea.tsx|*.stories.tsx|*.test.*|*.spec.tsx) ;; # SSOT/test skip
+      *)
+        if ! echo "$NEW_CONTENT" | grep -q '@field-state-ring-allow'; then
+          # A.3.1 舊 box-shadow inset
+          if echo "$NEW_CONTENT" | grep -E "(hover|focus-within|data-\[state=open\]):shadow-\[inset" >/dev/null; then
+            cat >&2 <<'EOF'
+
+┄┄┄ A.3.1 check_field_family_invariants — Field state ring shadow inset BLOCKER ┄┄┄
+
+[P0] naked variant state ring 用 `box-shadow inset` — v9 retire pattern。
+修法:讓 Field default state machine 自動繼承(border-based);cell hover 用 `nakedCellEditableDisplayHover` const。
+
+EOF
+            record_worst 2
+          fi
+          # A.3.2 自寫 outline state ring
+          if echo "$NEW_CONTENT" | grep -E "(hover|focus-within|focus-visible|data-\[state=open\]):outline-(border|primary)" >/dev/null; then
+            cat >&2 <<'EOF'
+
+┄┄┄ A.3.2 check_field_family_invariants — Field state ring outline BLOCKER ┄┄┄
+
+[P0] 自寫 `hover:outline-border` / `focus-within:outline-primary` — v13 canonical 禁。
+修法:Field default 自動繼承 / cell 用 `nakedCellEditableDisplayHover` const。
+
+EOF
+            record_worst 2
+          fi
+          # A.3.3 per-control open=blue override(v13.5)
+          # 2026-06-11 deep-audit R2(n=38)精準化(M7 broad-vs-narrow 3-column):
+          #   Spec wording:v13.3 禁「open 時 per-control 把 border 轉 primary(藍)」。
+          #   Hook regex(舊):substring 無 boundary + 不分註解行。
+          #   Gap:誤命中 (a) `data-[state=open]:border-primary-hover` canonical(button.tsx:99,109
+          #     overlay trigger 維持 hover 樣式,-hover/-active 是合法 token 後綴);(b) v13.3 retire
+          #     註解內引用舊 pattern 文字(combobox.tsx:725 / select.tsx:594)。
+          #   修:純註解行剝離 + border-primary 加字尾 boundary([^-a-zA-Z]|$)。
+          #   DS-wide counter-example scan 2026-06-11:新 regex 全 components/ 0 hit(真違規 shape
+          #   `open && 'border-primary'` / `data-[state=open]:border-primary` 結尾 仍 BLOCK,fixture 驗證)。
+          A33_CONTENT=$(echo "$NEW_CONTENT" | grep -vE '^[[:space:]]*(//|\*|/\*)')
+          if echo "$A33_CONTENT" | grep -E "(open|isOpen) +&& +.{0,40}('border-primary'|\"border-primary\")" >/dev/null \
+             || echo "$A33_CONTENT" | grep -E "data-\[state=open\]:border-primary([^-a-zA-Z]|$)" >/dev/null; then
+            cat >&2 <<'EOF'
+
+┄┄┄ A.3.3 check_field_family_invariants — per-control open=blue BLOCKER ┄┄┄
+
+[P0] per-control `open && 'border-primary'` / `data-[state=open]:border-primary` — v13.3 canonical「focus dominates everything」禁。
+修法:刪 override。Radix Popover open 時 trigger 通常 focused → focus-within fires → 藍(自然 Ant 風)。改 Field default SSOT 須 spec 補 rationale。
+
+EOF
+            record_worst 2
+          fi
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+# ── A.4 disabled placeholder color(P1 stderr,exit 0 不 block)──────────────────
+if ! echo "$NEW_CONTENT" | grep -q '@disabled-color-allow'; then
+  SUSPECT_DP=""
+  if echo "$NEW_CONTENT" | grep -E "placeholder:text-fg-muted" >/dev/null \
+     && ! echo "$NEW_CONTENT" | grep -E "(disabled:placeholder:text-fg-disabled|group-data-\[field-mode=disabled\].*placeholder:text-fg-disabled|resolvedMode\s*===\s*'disabled'.*text-fg-disabled)" >/dev/null; then
+    SUSPECT_DP="$SUSPECT_DP [placeholder:text-fg-muted 無 disabled override]"
+  fi
+  if echo "$NEW_CONTENT" | tr '\n' ' ' | grep -E '<span[^>]*"text-fg-muted"[^>]*>[[:space:]]*\{[^}]*placeholder' >/dev/null 2>&1 \
+     && ! echo "$NEW_CONTENT" | grep -E "resolvedMode\s*===\s*'disabled'" >/dev/null; then
+    SUSPECT_DP="$SUSPECT_DP [<span text-fg-muted>{placeholder} 不分 mode]"
+  fi
+  if [ -n "$SUSPECT_DP" ]; then
+    cat >&2 <<EOF
+
+┄┄┄ A.4 check_field_family_invariants — disabled placeholder color WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+${SUSPECT_DP}
+修法:disabled:placeholder:text-fg-disabled / group-data-[field-mode=disabled]/field:placeholder:text-fg-disabled / JSX 條件
+詳:tokens/color/color.spec.md「Disabled state precedence canonical」/ M24
+例外:行尾 \`// @disabled-color-allow: <reason>\`
+
+EOF
+    # A.4 原 hook exit 0(stderr only),保持向後兼容不升 WORST
+  fi
+fi
+
+# ── A.5 _Group child fieldCtx.id 隔離(P0 BLOCKER,2026-05-31 折入,M4 AR34 regression detector)──
+# M4:_Group 元件(CheckboxGroup/RadioGroup/SwitchGroup)的 child item 不可共用 fieldCtx.id —— 否則
+# group 內所有 label 被抑制 + 點 label 只 toggle 第一個(AR34 root bug)。正解:item 在 group 內走自己
+# 的 generatedId,不 fall back 到共用 fieldCtx.id。偵測 AR34 regression shape(MERGED 整檔,3-signal AND):
+#   (1) 消費 *GroupContext  (2) bare `idProp ?? fieldCtx?.id ?? generatedId` fallback
+#   (3) 缺 `insideGroup ? generatedId` / `inGroup ? generatedId` group guard
+case "$FILE_PATH" in
+  *components/*.tsx)
+    if ! echo "$MERGED_CONTENT" | grep -q '@group-fieldctx-allow' \
+       && echo "$MERGED_CONTENT" | grep -qE 'useContext\([A-Za-z_]*GroupContext\)' \
+       && echo "$MERGED_CONTENT" | grep -qE 'idProp[[:space:]]*\?\?[[:space:]]*fieldCtx\?\.id[[:space:]]*\?\?[[:space:]]*generatedId' \
+       && ! echo "$MERGED_CONTENT" | grep -qE '(insideGroup|inGroup)[[:space:]]*\?[[:space:]]*generatedId'; then
+      cat >&2 <<EOF
+
+┄┄┄ A.5 check_field_family_invariants — _Group child fieldCtx.id 隔離 BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測到 _Group child item 消費 GroupContext + bare \`idProp ?? fieldCtx?.id ?? generatedId\` fallback,
+但**缺** group guard(\`insideGroup ? generatedId\`)= M4 AR34 regression shape。
+
+⚠️  M4 canonical:Group 內 item 不可共用 fieldCtx.id(否則所有 label 被抑制 + 點 label 只 toggle 第一個)。
+
+修法:
+  inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))
+  即 group 內走自己的 generatedId,不 fall back 共用 fieldCtx.id。
+  例外:行尾 \`// @group-fieldctx-allow: <reason>\`
+
+EOF
+      record_worst 2
+    fi
+    ;;
+esac
+
+exit $WORST

package/ds-canonical/fork/hooks/check_fork_product_quality.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# check_fork_product_quality.sh — REPLACE for check_substantive_edit_approval_preflight.sh (fork-mode)
+#
+# WHY REPLACE: 原 approval-gate 在 fork hard-block(exit 2)所有 apps/** 產品 edit → 鎖死 fork
+# 使用者(連寫產品 code 都不行)。fork 使用者「寫產品」是正常開發,不該被 DS-author 的「設計
+# 改動需 approval」儀式擋住。本 hook 改成 quality-POSITIVE soft inject:exit 0、永不 brick,只在
+# 編輯產品 code 時提醒「先消費 DS 元件 + 讀 DS spec」。真正的品質 enforcement 由其他 fork-mode
+# 治理 hook(primitive-misuse / layout-space / opacity-token / ds-anchor)負責,不靠 approval 閘。
+#
+# 對齊 C-prime 共識:world-class 產出靠「SSOT/anchor/primitive 機械檢查 fire」保證,
+# 不靠「把一般 edit 擋在 approval 關鍵字後面」。
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+case "${TOOL:-}" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+# 只在 fork 產品 code 提示;DS 內部 / node_modules / 非 product 不管
+echo "$FILE" | grep -qE '(^|/)apps/.+\.(tsx|ts|css)$' || exit 0
+echo "$FILE" | grep -qE 'node_modules/|packages/design-system/' && exit 0
+
+# 一個 session 只提示一次(避免每次 edit 都吵)
+MARK="${TMPDIR:-/tmp}/.ds-fork-quality-hinted-${CLAUDE_SESSION_ID:-session}"
+[ -f "$MARK" ] && exit 0
+: > "$MARK" 2>/dev/null || true
+
+cat >&2 << 'EOF'
+💡 DS 產品開發提示(soft,不阻擋):你正在編輯產品 code(apps/**)。
+   為確保世界級且一致的產出,改動前請:
+   - 優先消費既有 DS 元件(import from "@qijenchen/design-system"),勿手刻 raw HTML / 重造已有元件
+   - 組裝某元件前,先讀它的 spec/story:node_modules/@qijenchen/design-system/src/**/<name>.spec.md
+   - 用 design token(間距/色值/字級/圓角/陰影),勿硬寫
+   (其餘 fork 治理 hook 會機械把關 primitive 誤用 / 硬寫間距 / opacity token 等)
+EOF
+exit 0

package/ds-canonical/fork/hooks/check_item_list_gap.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# check_item_list_gap.sh — M16 mechanical enforcement(2026-05-26 backfill).
+#
+# Purpose:PreToolUse Edit/Write — 偵測 production tsx 含 standalone card/pill 渲染
+# pattern(`<FileItem>` / `<MenuItem rich>` / 卡片型 standalone)without gap-N or space-y-N
+# parent → soft warn requires explicit gap canonical per item-anatomy.spec.md。
+#
+# 3 條公式(per M16):
+#   - 同類 standalone 卡片 → 必 gap
+#   - 同類 permanent flush(連續貼齊)→ 0 gap OK,但必 codify in spec
+#   - 混合語言 → 必取最保守 gap
+
+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 *.stories.tsx|*.test.tsx) exit 0 ;; esac
+
+# Heuristic:multiple <FileItem> / <MenuItem variant="rich"> / standalone card pattern + parent 無 gap-N
+# 2026-05-26 fix:grep -c 計行數不計次,用 -o count 真實 occurrence
+STANDALONE_RE='<(FileItem|MenuItem[^>]+variant=["'\'']rich["'\''])'
+COUNT=$(echo "$NEW" | grep -oE "$STANDALONE_RE" 2>/dev/null | wc -l | tr -d ' ')
+COUNT=${COUNT:-0}
+
+[ "$COUNT" -lt 2 ] && exit 0
+
+# Has gap-N or space-y-N near the standalone pattern?
+if echo "$NEW" | grep -qE '(gap-[0-9]|space-y-[0-9])'; then
+  exit 0
+fi
+
+cat >&2 <<EOF
+⚠️ M16 Item-list gap canonical
+
+→ 偵測到 $COUNT 個 standalone item(FileItem / MenuItem rich)未見 gap-N / space-y-N parent class。
+
+M16 要求(per item-anatomy.spec.md):
+  - 同類 standalone → 必 gap(常見 gap-2 / gap-3)
+  - 同類 permanent flush(連續貼齊)→ 0 gap OK,但必 spec codify
+  - 混合語言 → 必取最保守 gap
+
+修法:parent container 加 \`gap-2\` / \`space-y-2\` 或 codify 連續貼齊 in 元件 spec。
+對應 canonical:meta-patterns.md M16 + patterns/element-anatomy/item-anatomy.spec.md。
+EOF
+
+exit 0