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

package/ds-canonical/hooks/check_consumer_story_baseline.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# check_consumer_story_baseline.sh — P0 BLOCKER
+#
+# Consumer storybook files wrapping high-risk DS primitives MUST declare
+# `// @story-baseline: <DS-story-path>#<exportName>` marker
+# (per M31 codex synthesis 2026-05-27).
+#
+# Anchor 2026-05-27 codex M31 v1:「Consumer 若 wrap 高風險 DS primitive,
+# 檔頭必須有 @story-baseline:,並由 CI 對 DS canonical story 做 visual diff」.
+#
+# High-risk DS primitives(per codex list):
+#   DataTable / Dialog / Sheet / Popover / DropdownMenu / Tooltip / HoverCard /
+#   LinkInput / RadioGroup / CircularProgress / AppShell / Sidebar
+#
+# Triggers on consumer apps/**/*.stories.tsx edit. Blocks if file uses any of
+# these primitives but lacks @story-baseline: marker.
+#
+# Escape:`// @story-baseline-allow: <rationale>` for legitimate exceptions
+# (eg. behavior-only test stories, exception per ds-story-manifest.json).
+
+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)
+# Only check consumer storybook files
+if ! echo "$FILE" | grep -qE '/(apps|consumer)/.*\.stories\.tsx$'; then exit 0; fi
+if echo "$FILE" | grep -qE 'packages/design-system/src/'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# Escape clauses
+if echo "$CONTENT" | grep -qE '@story-baseline-allow:|@consumer-catalog-allow:'; then exit 0; fi
+
+# High-risk DS primitives requiring baseline marker
+HIGH_RISK_PRIMITIVES='DataTable|Dialog|Sheet|Popover|DropdownMenu|Tooltip|HoverCard|LinkInput|RadioGroup|CircularProgress|AppShell|Sidebar'
+
+# Detect usage
+USED=$(echo "$CONTENT" | grep -oE "<DS\.($HIGH_RISK_PRIMITIVES)\\b" | sort -u | head -10)
+
+if [ -z "$USED" ]; then exit 0; fi
+
+# Check for @story-baseline: marker
+if echo "$CONTENT" | grep -qE '@story-baseline:[[:space:]]*\S'; then exit 0; fi
+
+cat >&2 << EOF
+🚨 CONSUMER-STORY-BASELINE BLOCKER(P0,2026-05-27 M31 codex synthesis)
+
+  Consumer file $FILE 用高風險 DS primitive 但無 \`// @story-baseline:\` marker:
+$(echo "$USED" | sed 's/^/    /')
+
+  per M31 codex synthesis SSOT:「Consumer wrap 高風險 DS primitive 必 @story-baseline:
+  marker,由 CI 對 DS canonical story 做 visual diff」.
+
+  High-risk list:DataTable / Dialog / Sheet / Popover / DropdownMenu / Tooltip /
+  HoverCard / LinkInput / RadioGroup / CircularProgress / AppShell / Sidebar.
+
+  修法 2 選 1:
+    (a) 加 marker(檔頭或 story body):
+        // @story-baseline: @qijenchen/design-system/components/<Name>/<name>.stories.tsx#<ExportName>
+        例:// @story-baseline: @qijenchen/design-system/components/Sidebar/sidebar.stories.tsx#IconCollapse
+    (b) Escape:\`// @story-baseline-allow: <rationale>\` 顯式 documented exception
+        (eg. pure behavior test / per ds-story-manifest.json exception list)
+
+  完整 mapping → packages/design-system/ds-story-manifest.json(DS package ship)
+EOF
+exit 2

package/ds-canonical/hooks/check_data_table_size_num_to_meta_width.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# check_data_table_size_num_to_meta_width.sh — M23(c) mechanical enforcement(2026-05-26 backfill).
+#
+# Purpose:PreToolUse Edit/Write — 偵測 DataTable column 定義使用 TanStack `size: <number>`
+# (px width)而非 DS canonical `meta: { width: 'sm'|'md'|'lg' }` density-aware token。
+# 違反 M23(c) framework prop name namespace conflict(TanStack `size` 是 px 數字,
+# DS `size` 是 density variant)→ soft warn 要求 wrap-and-rename。
+#
+# 對齊 meta-patterns.md M23(c) + data-table.spec.md L?「Column width canonical」段。
+
+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|*.ts) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.stories.tsx|*.test.*) exit 0 ;; esac
+
+# DataTable 上下文:column 定義 OR DataTable import OR ColumnDef 型別
+HAS_DATATABLE_CTX=0
+if echo "$NEW" | grep -qE '(ColumnDef|columns:|DataTable|@tanstack/react-table)'; then
+  HAS_DATATABLE_CTX=1
+fi
+
+[ "$HAS_DATATABLE_CTX" = "0" ] && exit 0
+
+# Detect raw size: <number> in column def(TanStack 用法)
+RAW_SIZE_HITS=$(echo "$NEW" | grep -cE '\bsize:\s*[0-9]+' 2>/dev/null)
+RAW_SIZE_HITS=${RAW_SIZE_HITS:-0}
+
+[ "$RAW_SIZE_HITS" -eq 0 ] && exit 0
+
+# 若同時用 meta: { width 也 OK(混用允許 transition)
+if echo "$NEW" | grep -qE 'meta:\s*\{[^}]*width'; then
+  # mixed — let it pass(transition state)
+  exit 0
+fi
+
+REL=${FILE_PATH#*/my-project/}
+
+cat >&2 <<EOF
+⚠️ M23(c) framework prop namespace conflict — DataTable column \`size: <number>\`
+
+📁 File: $REL
+🔍 偵測:$RAW_SIZE_HITS 個 \`size: <number>\` (TanStack px API)在 ColumnDef 上下文,但無 \`meta: { width: 'sm'|'md'|'lg' }\` DS density-aware variant。
+
+M23(c)要求:
+  - TanStack \`size\` prop = px 數字(framework spec)
+  - DS \`size\` prop = density variant 'sm'|'md'|'lg'(DS spec)
+  - 同名不同義 → wrap-and-rename:DataTable column 用 \`meta.width: 'sm'|'md'|'lg'\`,DS internal 再 map 成 TanStack \`size\` px
+
+修法:
+  // ❌ Avoid
+  { accessorKey: 'name', size: 280 }
+
+  // ✅ Use DS density-aware
+  { accessorKey: 'name', meta: { width: 'md' } }
+
+對應 canonical:meta-patterns.md M23(c) + components/DataTable/data-table.spec.md「Column width SSOT」。
+EOF
+
+exit 0

package/ds-canonical/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
+#   - packages/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 `packages/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
+  */packages/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 'packages/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#*/my-project/}
+
+# 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 對 \`packages/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:
+        - \`packages/design-system/src/<Component>/*.spec.md\`(找 owner SSOT)
+        - \`packages/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/hooks/check_escape_marker_abuse.sh

@@ -0,0 +1,86 @@
+#!/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.
+
+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)
+# Only check consumer apps tsx (not DS source — DS has legitimate exceptions per spec)
+if ! echo "$FILE" | grep -qE '/(apps|consumer)/.*\.(tsx|ts)$'; then exit 0; fi
+if echo "$FILE" | grep -qE 'packages/design-system/src/'; 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
+
+# Count distinct markers + total occurrences
+MARKER_RE='@(ds-misuse-allow|story-baseline-allow|consumer-catalog-allow|overlay-open-skip|template-customized|layout-space-magic-ok|story-trait-allow|story-trait-rationale|story-split-rationale|story-name-canonical-allow|propose-cite-skip|anatomy-exempt|anatomy-exempt-next|benchmark-unverified|benchmark-citation-allow|benchmark-unverified-blanket)'
+MARKERS_FOUND=$(echo "$CONTENT" | grep -oE "$MARKER_RE" | sort -u)
+DISTINCT_COUNT=$(echo "$MARKERS_FOUND" | grep -c . || echo 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
+
+exit 0

package/ds-canonical/hooks/check_fork_user_plugin_install.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# check_fork_user_plugin_install.sh — SessionStart enforce plugin install on fork-user repos.
+#
+# 2026-05-26 backfill per user verbatim「我們做那麼多 plugin 不就是要避免這件事?結果還避不了?」
+#
+# Purpose:當 session 跑在「consumer fork-user repo」(non-DS repo,但 package.json
+# 含 @qijenchen/design-system dep)+ 偵測未安裝 design-system plugin → context inject
+# 強制提示用 `/plugin marketplace add github:ajenchen/design-system → /plugin install`。
+#
+# Detection logic:
+#   (a) cwd 不是 DS repo(無 packages/design-system/ folder)
+#   (b) package.json 含 `"@qijenchen/design-system"` dep
+#   (c) `.claude/plugins/design-system@qijenchen-ds/` OR plugin marketplace symlink 不存在
+#   → 三題全 YES = consumer fork-user 沒裝 plugin → 強制提示
+
+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)
+
+[ "$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
+[ -d "$HOME/.claude/plugins/design-system" ] && PLUGIN_INSTALLED=1
+[ -d "$HOME/.claude/plugins/design-system@qijenchen-ds" ] && PLUGIN_INSTALLED=1
+[ -d "$CWD/.claude/plugins/design-system" ] && PLUGIN_INSTALLED=1
+[ -d "$CWD/.claude/plugins/design-system@qijenchen-ds" ] && PLUGIN_INSTALLED=1
+# 也接受 plugin marketplace cache(claude code 自動產生)
+[ -d "$HOME/.claude/marketplaces"/*/design-system/ ] 2>/dev/null && PLUGIN_INSTALLED=1
+[ -d "$HOME/.claude/marketplaces"/*/design-system@qijenchen-ds/ ] 2>/dev/null && 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

package/ds-canonical/hooks/check_full_story_visual_interaction_sweep.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# check_full_story_visual_interaction_sweep.sh — P0 BLOCKER
+#
+# Codex M31 P0 finding 2026-05-27: ds-story-manifest.json 是 62-component / 916-story
+# SSOT,但無 hook 攔 audit reports 漏 manifest story IDs / screenshots / metrics / probe.
+# User 2026-05-27 verbatim「不准抽樣 全 visual + interaction 全跑」.
+#
+# Triggers when audit report JSON is edited/written:
+#   - /tmp/codex-*-sweep/audit-report.json
+#   - /tmp/claude-*-sweep/audit-report.json
+#   - .claude/snapshots/*audit-report.json
+# Verifies storyResults.length === manifest.totalStories (916) — block if sample.
+#
+# Escape: report frontmatter `"_sampling_allowed": "<rationale>"`(極罕見).
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+
+case "${TOOL:-}" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+if ! echo "$FILE" | grep -qE '(sweep|audit-report)\.json$'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# Check escape
+if echo "$CONTENT" | grep -q '_sampling_allowed'; then exit 0; fi
+
+# Parse story count vs manifest (multi-field fallback)
+STORY_COUNT=$(echo "$CONTENT" | jq -r '.storyResults // .results // [] | length' 2>/dev/null)
+if [ -z "$STORY_COUNT" ] || [ "$STORY_COUNT" = "0" ] || [ "$STORY_COUNT" = "null" ]; then
+  STORY_COUNT=$(echo "$CONTENT" | jq -r '.storySummary.total // .summary.total // .total // 0' 2>/dev/null)
+fi
+STORY_COUNT=${STORY_COUNT:-0}
+
+MANIFEST_PATH="${CLAUDE_PROJECT_DIR:-.}/packages/design-system/ds-story-manifest.json"
+if [ ! -f "$MANIFEST_PATH" ]; then exit 0; fi
+MANIFEST_TOTAL=$(jq -r '.totalStories // 0' "$MANIFEST_PATH" 2>/dev/null)
+[ -z "$MANIFEST_TOTAL" ] || [ "$MANIFEST_TOTAL" = "0" ] && exit 0
+[ "$STORY_COUNT" = "0" ] && exit 0
+# numeric compare
+if ! [[ "$STORY_COUNT" =~ ^[0-9]+$ ]]; then exit 0; fi
+
+if [ "$STORY_COUNT" -lt "$MANIFEST_TOTAL" ]; then
+  cat >&2 << EOF
+🚨 FULL-STORY-SWEEP BLOCKER(P0,codex M31 finding 2026-05-27 + user「不准抽樣」)
+
+  Audit report $FILE:
+    storyResults: $STORY_COUNT
+    manifest.totalStories: $MANIFEST_TOTAL
+    缺失: $((MANIFEST_TOTAL - STORY_COUNT)) stories
+
+  per ds-story-manifest.json SSOT(scripts/gen-ds-story-manifest.mjs:59)+ user 2026-05-27
+  「請你不要給我抽樣,因為你一抽樣就是會有東西壞掉,務必要全部檢查」directive.
+
+  修法 2 選 1:
+    (a) Re-run sweep covering all $MANIFEST_TOTAL stories
+    (b) Escape:report 含 \`"_sampling_allowed": "<rationale>"\`(極罕見)
+EOF
+  exit 2
+fi
+
+exit 0

package/ds-canonical/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

package/ds-canonical/hooks/check_layout_space_magic_numbers.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# check_layout_space_magic_numbers.sh — P0 BLOCKER
+#
+# 偵測 consumer / DS app code 用 Tailwind spacing magic numbers
+# (`p-4` / `px-6` / `py-2` / `gap-3` 等)而非 layoutSpace token
+# (`p-[var(--layout-space-N) N∈{loose,tight}]` / `gap-[var(--layout-space-N) N∈{loose,tight}]`)。
+# 2026-05-27 user verbatim「機械無強制就不會做?那為何不全部 ssot 都要強制吻合?」
+# 永久 codify — SSOT canonical 必 P0 BLOCKER,不分級。
+#
+# Anchor:user 質疑「content 自動繼承 layoutSpace SSOT 嗎?」
+# - app-shell.spec.md:205 明文 `<main>` landmark padding=0 (intentional)
+# - app-shell.spec.md:207-212 consumer 必遵循 layoutSpace.spec.md 6 條規則 + 親疏 3 級
+#
+# PostToolUse Edit/Write detect magic Tailwind spacing → P0 BLOCKER exit 2
+# 強制改 token OR 加 `// @layout-space-magic-ok: <rationale>` escape comment(per-line)。
+
+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 // .tool_input.notebook_path // ""' 2>/dev/null)
+
+# Only check .tsx / .ts in app code
+if ! echo "$FILE" | grep -qE '\.(tsx|ts)$'; then exit 0; fi
+# Skip DS source (DS components have their own spacing logic via cva)
+if echo "$FILE" | grep -qE 'packages/design-system/src/|node_modules/'; then exit 0; fi
+
+# Get new content
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$NEW_CONTENT" ] && exit 0
+
+# Escape clause:single line escape comment per line of magic number usage
+# `// @layout-space-magic-ok: <rationale>` immediately above the line OR on same line
+ESCAPE_MARKER='@layout-space-magic-ok:'
+
+# Detect magic spacing classes (Tailwind class strings only — NOT JSX props like size={24})
+# Match per line so we can check per-line escape comments
+MAGIC_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b(p|px|py|pt|pb|pl|pr|gap|space-x|space-y|m|mx|my|mt|mb|ml|mr)-(0\.5|[1-9][0-9]?(\.[0-9])?)\b')
+
+if [ -z "$MAGIC_LINES" ]; then
+  exit 0
+fi
+
+# Filter out lines with escape marker on same line OR preceding line
+UNJUSTIFIED=""
+while IFS= read -r line; do
+  if echo "$line" | grep -qF "$ESCAPE_MARKER"; then continue; fi
+  UNJUSTIFIED="${UNJUSTIFIED}${line}\n"
+done <<< "$MAGIC_LINES"
+
+if [ -z "$UNJUSTIFIED" ]; then
+  exit 0
+fi
+
+cat >&2 << EOF
+🚨 LAYOUT-SPACE-MAGIC-NUMBER BLOCKER(P0,2026-05-27 user verbatim「機械無強制就不會做?
+為何不全部 ssot 都要強制吻合?」永久 codify)
+
+  Detected Tailwind spacing magic numbers in $FILE without escape:
+$(echo -e "$UNJUSTIFIED" | sed 's/^/    /' | head -10)
+
+  per app-shell.spec.md L205-219 + layoutSpace.spec.md SSOT:consumer content 必遵循
+  layoutSpace 6 條規則 + 親疏 3 級,**禁** 硬寫 Tailwind magic numbers。改用:
+    p-[var(--layout-space-loose)]      /* 16px 規則 1A/1B chrome / wrap */
+    p-[var(--layout-space-tight)]      /* 12px 規則 3 親 gap */
+    gap-[var(--layout-space-distant)]  /* 24px 規則 3 疏 gap */
+    space-y-[var(--layout-space-distant)]
+
+  修法 2 選 1:
+    (a) 改 token:換成 var(--layout-space-N) N∈{loose,tight} family per 6 規則 + 親疏 3 級
+    (b) Escape:在該 line 加 \`// @layout-space-magic-ok: <rationale>\` 顯式 documented
+        (eg.「\`gap-1\` 是 4px stack icon — non-spacing context,not consumer layout」)
+
+  完整 6 條規則 → packages/design-system/src/tokens/layoutSpace/layoutSpace.spec.md
+EOF
+exit 2