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

package/ds-canonical/fork/governance.lock

@@ -0,0 +1,112 @@
+{
+  "_purpose": "sha256 of every shipped fork governance body + manifest (tamper-detect baseline)",
+  "entries": [
+    {
+      "file": "hooks/block_prototype_imports.py",
+      "sha256": "0ab679ddb522f508c490891711559175a912be8b7f4db04d8a55cdac983fd482",
+      "sourceHook": "block_prototype_imports.py",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/check_chrome_header_avatar_canonical.sh",
+      "sha256": "ffa91559c19d3f2aab50c69c4b247c15a29376d10b116f6223afb3289b4f91a2",
+      "sourceHook": "check_chrome_header_avatar_canonical.sh",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/check_consumer_app_invariants.sh",
+      "sha256": "e2d63b142759bf791ca3c4462342d91623827aeb54c15398c94853485684900b",
+      "sourceHook": "check_consumer_app_invariants.sh",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/check_ds_anchor_preflight.sh",
+      "sha256": "15fb44c8b35042efd03e1992f8b5b7b121a7633cebe556d4ca0a1a7f5483dc35",
+      "sourceHook": "check_ds_anchor_preflight.sh",
+      "bucket": "SHIP_REWRITTEN"
+    },
+    {
+      "file": "hooks/check_escape_marker_abuse.sh",
+      "sha256": "4f9d8dc91275145204f0bc760c4378dd53f7ad4389d89da737aef23f84b2502b",
+      "sourceHook": "check_escape_marker_abuse.sh",
+      "bucket": "SHIP_REWRITTEN"
+    },
+    {
+      "file": "hooks/check_field_family_invariants.sh",
+      "sha256": "1beeb2b347cacf5d8a912470bce0b9ab6b54c2595873155389456cdbe6125d80",
+      "sourceHook": "check_field_family_invariants.sh",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/check_fork_product_quality.sh",
+      "sha256": "1985d7607de85ae71b07b4b302c27b3dbb51670bbe68421489e27c75a2b64ffa",
+      "sourceHook": "check_substantive_edit_approval_preflight.sh",
+      "bucket": "REPLACE"
+    },
+    {
+      "file": "hooks/check_item_list_gap.sh",
+      "sha256": "4e779e5894f16873f1bc322f64571a7ff869d3b75ed5383a5b0f662c7b533d99",
+      "sourceHook": "check_item_list_gap.sh",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/check_layout_space_magic_numbers.sh",
+      "sha256": "09c74c67c61a366b14bb1cce2ac27d4b8d0541a8698f85d50e4afe9783ad7309",
+      "sourceHook": "check_layout_space_magic_numbers.sh",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/check_opacity_token_usage.sh",
+      "sha256": "1772e83242520f569a9a44e96d08d74e121c119c940c019c8ed50989f14de646",
+      "sourceHook": "check_opacity_token_usage.sh",
+      "bucket": "SHIP_REWRITTEN"
+    },
+    {
+      "file": "hooks/check_pattern_invariants.sh",
+      "sha256": "c6cf3288cbc2bdb689091aef678073470f58b7f1bf98cdefb55afc9724ad277b",
+      "sourceHook": "check_pattern_invariants.sh",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/check_sidebar_menu_button_implicit_wrap.sh",
+      "sha256": "240807737e9c75bd137a8abd9a7194ffcb4a92b1015f626f14539fd8dbf73ea8",
+      "sourceHook": "check_sidebar_menu_button_implicit_wrap.sh",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/check_tailwind_wildcard_in_docs.sh",
+      "sha256": "51fcf04d3adc2a15b6c06312753e51412ed8ff88d088a5e8fe4ec0c784c7aa96",
+      "sourceHook": "check_tailwind_wildcard_in_docs.sh",
+      "bucket": "SHIP_AS_IS"
+    },
+    {
+      "file": "hooks/inject_deploy_url_after_push.sh",
+      "sha256": "f5cd8597574f1b061b132a289337731f7dabac0c6666f1ca611d8316504b401c",
+      "sourceHook": "inject_deploy_url_after_push.sh",
+      "bucket": "SHIP_REWRITTEN"
+    },
+    {
+      "file": "launchers/fork-governance-dispatcher.sh",
+      "sha256": "6a99ad2d7404a4d721a611a19e4537ebfe8cf5e2ddba99edc7f6b386d86e8b5d",
+      "source": "template/.claude/hooks"
+    },
+    {
+      "file": "launchers/inject_fork_governance_preamble.sh",
+      "sha256": "eccf9dbb5ccd3a2e0bea6e3e225de2eb0f1634a6c12c349aab89439cf6e1fb89",
+      "source": "template/.claude/hooks"
+    },
+    {
+      "file": "launchers/settings-hooks.json",
+      "sha256": "04f328ae97687e112995288bff2c1fa8c9feecf25335f4b63036964209e7b402",
+      "source": "template/.claude/settings.json"
+    },
+    {
+      "file": "manifest.json",
+      "sha256": "ee4f619b722c7d3a4f80dddb52dcee4bf900c7e6923945cd59d290d4a8236e5a"
+    },
+    {
+      "file": "preamble.md",
+      "sha256": "394299047d01f60bf1d9fd14a41e173b31d649068c62bd47352556beab9683e1"
+    }
+  ]
+}

package/ds-canonical/fork/hooks/block_prototype_imports.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+import json
+import os
+import re
+import sys
+import time
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+# Resolve project root from this script's location(stable; cwd may be anywhere
+# depending on how Claude Code invokes the hook)to avoid stray .claude/ trees.
+try:
+    _project_root = os.environ.get('CLAUDE_PROJECT_DIR') or os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    _log_dir = os.path.join(_project_root, '.claude', 'logs')
+    os.makedirs(_log_dir, exist_ok=True)
+    with open(os.path.join(_log_dir, 'hook-fires-per-hook.jsonl'), 'a') as _f:
+        _f.write(json.dumps({'ts': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()), 'hook': os.path.basename(__file__)}) + '\n')
+except Exception:
+    pass
+
+EXPLORATION_PREFIX = "src/explorations/"
+SRC_PREFIX = "src/"
+
+def load_event():
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return None
+
+def collect_file_paths(tool_input):
+    paths = []
+
+    if not isinstance(tool_input, dict):
+        return paths
+
+    file_path = tool_input.get("file_path")
+    if isinstance(file_path, str):
+        paths.append(file_path)
+
+    edits = tool_input.get("edits")
+    if isinstance(edits, list):
+        for item in edits:
+            if isinstance(item, dict):
+                p = item.get("file_path")
+                if isinstance(p, str):
+                    paths.append(p)
+
+    files = tool_input.get("files")
+    if isinstance(files, list):
+        for item in files:
+            if isinstance(item, dict):
+                p = item.get("file_path")
+                if isinstance(p, str):
+                    paths.append(p)
+
+    return list(dict.fromkeys(paths))
+
+def should_check(path):
+    if not path.startswith(SRC_PREFIX):
+        return False
+    if path.startswith(EXPLORATION_PREFIX):
+        return False
+    if not (path.endswith(".ts") or path.endswith(".tsx")):
+        return False
+    return True
+
+def contains_exploration_import(content):
+    patterns = [
+        r'from\s+[\'"].*src/explorations/.*[\'"]',
+        r'from\s+[\'"].*explorations/.*[\'"]',
+        r'import\s+[\'"].*src/explorations/.*[\'"]',
+        r'import\s+[\'"].*explorations/.*[\'"]'
+    ]
+    return any(re.search(p, content) for p in patterns)
+
+def main():
+    event = load_event()
+    if not event:
+        sys.exit(0)
+
+    tool_input = event.get("tool_input", {})
+    touched_paths = collect_file_paths(tool_input)
+
+    offenders = []
+
+    for path in touched_paths:
+        if not should_check(path):
+            continue
+        if not os.path.exists(path):
+            continue
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except Exception:
+            continue
+
+        if contains_exploration_import(content):
+            offenders.append(path)
+
+    if offenders:
+        lines = [
+            "Blocked: 正式程式碼不得 import src/explorations/ 內的檔案。"
+        ]
+        lines.extend(f"- {p}" for p in offenders)
+        print("\n".join(lines))
+        sys.exit(2)
+
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,95 @@
+#!/bin/bash
+# check_chrome_header_avatar_canonical.sh — PreToolUse Edit/Write 攔 chrome header descendant 用 ItemAvatar(2026-05-27)
+#
+# Per user 2026-05-27 抓 UserFooter vertical stack drift + codex collab Step 4 cite battle:
+#   header-canonical.spec.md:57-72 + sidebar.spec.md:241-247 + item-anatomy.spec.md:513-537 明文:
+#   「Chrome header 不是 row context → 必 raw <Avatar size={24}>,禁 <ItemAvatar>(會誤啟動 row anatomy lookup)」
+#
+# Detection:
+#   PreToolUse Edit/Write content 偵測 `<SidebarHeader>` block 內含 `<ItemAvatar` → soft BLOCKER inject
+#   (允許 SidebarFooter 內 ItemAvatar — footer 是 SidebarMenu row context)
+#
+# Scope:
+#   - packages/design-system/src/components/Sidebar/**.tsx + **.stories.tsx
+#   - apps/**.tsx (consumer)
+#   - node_modules/@qijenchen/design-system/**(禁改 — block_prototype_imports 已攔)
+#
+# 對應 audit dim 預留 — TBD 升 audit dim 65
+
+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|*.spec.md) exit 0 ;; esac
+
+# Multi-line detection:`<SidebarHeader>...<ItemAvatar...>...</SidebarHeader>` block
+# Use python for proper multiline match
+# 2026-06-11 R2 held-item #9:strip 註解再 match — apps/template/src/App.tsx:57 canonical citation
+# 註解({/* ... 禁用 <ItemAvatar> ... */})在 SidebarHeader block 內被當真 JSX 誤發 P0(code 實際正確
+# 用 raw <Avatar size={24}>)。Strip 順序:JSX comment {/* */} → block comment /* */ → 行首 // 整行
+# (不 strip 行內 //,避免 mutilate https:// URL — 對齊 check_story_invariants.sh R9 idiom)。
+HAS_DRIFT=$(printf '%s' "$NEW" | python3 -c '
+import sys, re
+content = sys.stdin.read()
+# Strip comments(citation 註解含 <ItemAvatar> 字樣不是 drift)
+content = re.sub(r"\{/\*.*?\*/\}", "", content, flags=re.DOTALL)
+content = re.sub(r"/\*.*?\*/", "", content, flags=re.DOTALL)
+content = re.sub(r"(?m)^[ \t]*//.*$", "", content)
+# Find SidebarHeader blocks(opening tag → closing tag,non-greedy)
+blocks = re.findall(r"<SidebarHeader[^>]*>.*?</SidebarHeader>", content, re.DOTALL)
+for block in blocks:
+    if re.search(r"<ItemAvatar\b", block):
+        print("DRIFT")
+        sys.exit(0)
+' 2>/dev/null)
+
+[ "$HAS_DRIFT" != "DRIFT" ] && exit 0
+
+# Override env var
+if [ "${CLAUDE_BYPASS_CHROME_HEADER_AVATAR:-0}" = "1" ]; then
+  mkdir -p "$(dirname "$0")/../logs" 2>/dev/null
+  printf '{"ts":"%s","event":"chrome-header-avatar-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#"$CLAUDE_PROJECT_DIR"/}
+
+cat >&2 <<EOF
+🚨 Chrome header avatar canonical violation(per user 2026-05-27 抓 + codex collab cite battle):
+
+📁 File: $REL
+🔍 偵測:<SidebarHeader> block 內含 <ItemAvatar>(禁用)
+
+Canonical citation:
+  - header-canonical.spec.md:57-72:「Chrome header 不是 row context → 必用 raw <Avatar size={24}>,禁用 <ItemAvatar>(會誤啟動 row anatomy lookup)」
+  - sidebar.spec.md:241-247:「consumer 用 raw <Avatar size={24}>(chrome header 不是 row context → 不該用 <ItemAvatar>)」
+  - item-anatomy.spec.md:513-537:「ItemAvatar scope = row context only;Chrome header 有自己的 canonical = raw <Avatar size={24}>」
+
+修法(per DS canonical):
+  ❌ <SidebarHeader>
+       <ItemAvatar alt="..." shape="square" color="..." solid />
+       <span>brand</span>
+     </SidebarHeader>
+
+  ✅ <SidebarHeader>
+       <Avatar size={24} shape="square" color="..." solid alt="..." />
+       <span className="text-body-lg font-medium truncate">brand</span>
+     </SidebarHeader>
+
+注意:SidebarFooter 內 ItemAvatar OK(footer 是 SidebarMenu row context)。本 hook 只攔 SidebarHeader。
+
+Bypass(極罕見):CLAUDE_BYPASS_CHROME_HEADER_AVATAR=1 env var(audit-logged)。
+EOF
+# 2026-05-31:exit 0 → exit 2(folded-hook-audit:原宣稱 BLOCKER 但 exit 0 = 假 enforcement;
+# chrome-header avatar 是 SSOT canonical [feedback_ssot_mechanical_p0_not_p1 = 必 P0 BLOCK],
+# verified clean on 現有 canonical sidebar code + 有 env escape 兜 false-positive)。
+exit 2

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

@@ -0,0 +1,349 @@
+#!/bin/bash
+# check_consumer_app_invariants.sh — P0 BLOCKER ×4 — consumer app DS 使用紀律(2026-05-27/28 user directive 家族)
+#
+# 2026-06-11 prune merge(user 拍板「照你建議做」;59→51 headroom):
+# #   r1_no_ds_catalog = 原 check_consumer_no_ds_catalog.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+#   r2_story_baseline = 原 check_consumer_story_baseline.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+#   r3_ds_primitive_misuse = 原 check_consumer_ds_primitive_misuse.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+#   r4_app_story_title = 原 check_consumer_app_story_title.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_no_ds_catalog() {
+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
+# Skip DS source
+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 clause — 2026-06-03 修(同 R8 fragment-vs-file bug class):Edit 只送 new_string 片段,
+# 但 @consumer-catalog-allow marker 在檔頭(不在每次 edit 的片段裡)→ 編輯有 marker 的 portal 檔
+# 任一非 marker 行就被誤擋。本 hook 是 PostToolUse(檔已落 disk)→ 補查整檔 marker。
+if echo "$CONTENT" | grep -q '@consumer-catalog-allow:'; then exit 0; fi
+if [ -f "$FILE" ] && grep -q '@consumer-catalog-allow:' "$FILE" 2>/dev/null; then exit 0; fi
+
+VIOLATIONS=""
+
+# Pattern 1: file basename forbidden
+basename=$(basename "$FILE" .stories.tsx)
+if echo "$basename" | grep -qE '^(EveryDsComponent|AllDsComponents|AllComponents|DsCatalog|EveryComponent)$'; then
+  # AllDsComponents allowed IF it's only portal proxy (check title)
+  if [ "$basename" = "AllDsComponents" ] && echo "$CONTENT" | grep -qE 'DsCanonicalPortal|iframe.*design-system|@consumer-catalog-allow'; then
+    : # portal proxy OK
+  else
+    VIOLATIONS="${VIOLATIONS}  - File basename '$basename' = catalog pattern. PW 不該重寫 DS catalog.\n"
+  fi
+fi
+
+# Pattern 2: title claims per-component default
+if echo "$CONTENT" | grep -qE "title:.*['\"](所有 DS 元件|Every DS Component|All DS Components.*render|每元件 default)"; then
+  VIOLATIONS="${VIOLATIONS}  - Story title claims per-component default render. PW catalog 只可 import smoke + DS portal proxy.\n"
+fi
+
+# Pattern 3: iterate-render anti-pattern
+if echo "$CONTENT" | grep -qE 'Object\.keys\(DS\)\.(map|forEach)' || \
+   echo "$CONTENT" | grep -qE 'Object\.entries\(DS\)\.(map|forEach)'; then
+  VIOLATIONS="${VIOLATIONS}  - Detected Object.keys/entries(DS).map iterate-render pattern. 禁 iterate render DS exports.\n"
+fi
+
+# Pattern 4: mass hand-mock(≥5 different <DS.X> tags in same file)
+DS_TAG_COUNT=$(echo "$CONTENT" | grep -oE '<DS\.[A-Z][a-zA-Z]+' | sort -u | wc -l | tr -d ' ')
+if [ "$DS_TAG_COUNT" -ge 5 ]; then
+  VIOLATIONS="${VIOLATIONS}  - Detected ${DS_TAG_COUNT} distinct <DS.X> renders in single file. 大量 hand-mock = drift risk(per 2026-05-27 7-bug 錨例). 重構成 single composition demo.\n"
+fi
+
+if [ -n "$VIOLATIONS" ]; then
+  cat >&2 << EOF
+🚨 CONSUMER-NO-DS-CATALOG BLOCKER(P0,2026-05-27 user 永久 directive「確保跟 ds repo 一模一樣」+ M31 codex synthesis)
+
+  Consumer file $FILE 違反:
+$(echo -e "$VIOLATIONS")
+  per M31 codex synthesis SSOT:
+    - DS owns per-component canonical pixels(62/62 components ×3 tiers stories in DS Storybook)
+    - PW(consumer)owns 真實業務 composition demos(AppShell Dashboard etc.)
+    - Catalog → DS canonical Storybook iframe/link proxy,**禁** PW 重寫 <DS.X minimal mock>
+
+  歷史錨點 2026-05-27 7 bugs:CircularProgress size=32 hardcode / RadioGroup raw item 沒 SelectionItem / DataTable one-col / LinkInput placeholder mock / Empty 缺 icon / Overlay trigger-only / Tooltip context — ALL 從 PW hand-mock minimal-prop drift.
+
+  修法 2 選 1:
+    (a) 改用 DS canonical Storybook iframe portal(per template AllDsComponents.stories.tsx#DsCanonicalPortal pattern)
+    (b) Escape:加 \`// @consumer-catalog-allow: <rationale>\` 顯式 documented
+
+  完整 SSOT → DS package ds-story-manifest.json + codex M31 synthesis output /tmp/codex-ssot-output.txt
+EOF
+  exit 2
+fi
+
+exit 0
+}
+
+r2_story_baseline() {
+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
+}
+
+r3_ds_primitive_misuse() {
+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)
+# Cover BOTH stories AND production .tsx in consumer apps
+if ! echo "$FILE" | grep -qE '(^|/)(apps|consumer)/.*\.(tsx|ts)$'; then exit 0; fi
+if echo "$FILE" | grep -qE 'packages/design-system/src/|node_modules/'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# 2026-06-03 修(同 R8 bug class):換行→空格 flatten。真實 JSX 屬性跨行(<DS.X\n  size={N}\n/>),
+# grep 逐行 + 各 pattern 用 [^>]+ 跨屬性匹配 → 不 flatten 的話多行 component 靜默繞過全部 anti-pattern 檢查
+# (= BLOCKER false-negative,consumer DS misuse 沒被擋)。[^>]+ 自帶 tag 邊界(遇 > 停),flatten 後不會跨 component。
+CONTENT=$(echo "$CONTENT" | tr '\n' ' ')
+
+# Global escape — file-wide allowlist
+if echo "$CONTENT" | grep -q '@ds-misuse-allow:'; then exit 0; fi
+
+VIOLATIONS=""
+
+# Pattern 1: <CircularProgress size={N}> with literal number (override default 24)
+if echo "$CONTENT" | grep -qE '<DS\.CircularProgress[^>]+size=\{[0-9]+\}'; then
+  VIOLATIONS="${VIOLATIONS}  - <CircularProgress size={N}> hardcoded number override default 24 (per circular-progress.spec.md:101)\n"
+fi
+
+# Pattern 2: <RadioGroupItem> NOT wrapped in <SelectionItem control={...}>
+# Approximation: file uses RadioGroupItem but doesn't reference SelectionItem
+if echo "$CONTENT" | grep -qE '<DS\.RadioGroupItem\b' && ! echo "$CONTENT" | grep -qE 'SelectionItem|<DS\.RadioGroupItem[^>]+label='; then
+  VIOLATIONS="${VIOLATIONS}  - <RadioGroupItem> 沒 wrap <SelectionItem control={<RadioGroupItem>}> (per selection-item.spec.md:23 SSOT spacing/padding)\n"
+fi
+
+# Pattern 3: <DataTable columns={[…]}> with literal single column
+if echo "$CONTENT" | grep -qE '<DS\.DataTable[^>]+columns=\{\[\s*\{[^}]+\}\s*\]\}' && ! echo "$CONTENT" | grep -qE 'columns=\{[^}]*\},\s*\{'; then
+  VIOLATIONS="${VIOLATIONS}  - <DataTable columns={[single-col]}> minimal one-column = 違反 data-table.spec.md canonical(min 2 cols for meaningful render)\n"
+fi
+
+# Pattern 4: <LinkInput placeholder=...> without value prop
+if echo "$CONTENT" | grep -qE '<DS\.LinkInput[^>]+placeholder=' && ! echo "$CONTENT" | grep -qE '<DS\.LinkInput[^>]+(value|defaultValue)='; then
+  VIOLATIONS="${VIOLATIONS}  - <LinkInput placeholder=...> 沒 value prop = placeholder-only mode 抹平 link/edit canonical (per link-input.spec.md:18,48-58)\n"
+fi
+
+# Pattern 5: <Empty title=...> without icon and without description
+if echo "$CONTENT" | grep -qE '<DS\.Empty[^>]+title=' && \
+   ! echo "$CONTENT" | grep -qE '<DS\.Empty[^>]+icon=' && \
+   ! echo "$CONTENT" | grep -qE '<DS\.Empty[^>]+description='; then
+  VIOLATIONS="${VIOLATIONS}  - <Empty title=...> 無 icon 無 description = 違反 Empty.tsx:11「預設只需 description」minimal mock looks weird\n"
+fi
+
+# Pattern 8: 硬寫色值 / 字級 / shadow 繞過 DS token(2026-06-02 CF conformance-model 補主防線 —
+# composition-fidelity 從 pixel-identity 收窄成 identity-opt-in 後,「consumer 用對 DS token」改由靜態
+# conformance 防線保證,對齊 Polaris stylelint-polaris / Atlassian eslint-plugin / Carbon stylelint。
+# 既有 check_layout_space_magic_numbers 守「間距」;此 pattern 補「色值/字級/shadow」缺口。
+# 零誤判優先:只抓 hardcoded(`-[var(--...)]` token 用法不匹配)。
+if echo "$CONTENT" | grep -qE '\b[a-z][a-z-]*-\[(#[0-9a-fA-F]{3,8}|rgb|rgba|hsl|hsla)[(]?|\btext-\[[0-9]|\bshadow-(sm|md|lg|xl|2xl)\b'; then
+  VIOLATIONS="${VIOLATIONS}  - 硬寫色值/字級/shadow 繞過 DS token(bg-[#hex] / text-[14px] / shadow-md)→ 改 semantic color token / text-body 等 typography token / shadow-[var(--elevation-N)](per ui-development.md「Tailwind 5 條核心」rule 3)\n"
+fi
+
+# Pattern 9(2026-06-12,user 抓 fork「四不像」G4 補洞):AppShell slot 餵 raw HTML element。
+# app-shell.spec.md:296-299 明文禁 sidebar={<div>}/header={<header>},原註「靠 audit 把關」
+# 無機械閘 → 兌現成 P0(per memory feedback_ssot_mechanical_p0_not_p1_warn)。
+# 零誤判:雙條件 = 同檔有 <DS.AppShell> + slot 屬性直接餵 raw tag(div/header/nav/aside/section)。
+if echo "$CONTENT" | grep -qE '<DS\.AppShell\b' && \
+   echo "$CONTENT" | grep -qE '\b(header|sidebar|aside)=\{ *<(div|header|nav|aside|section)\b'; then
+  VIOLATIONS="${VIOLATIONS}  - <AppShell header/sidebar/aside={<raw element>}> — slot 必餵 DS 元件(ChromeHeader / Sidebar / AppShellAside),raw div/header 漏接 border/scroll/responsive canonical(per app-shell.spec.md:296-299)\n"
+fi
+
+# Pattern 10(2026-06-16,user 抓 fork prototype 手刻 table 不用 DataTable):RAW PRIMITIVE 手刻
+# r3 既有 Pattern 1-9 只抓「DS 元件用錯」(<DS.X> 已在用但用法錯),漏掉**根本沒用 DS 元件、亂刻
+# raw HTML** —— 即 mindset #2 +「# SSOT 消費 canonical」+ build-ui-canonicals.md:9「命中既有元件
+# → 必消費,不 hand-craft raw HTML 繞過」這條**必定遵循大原則**的機械閘缺口。反 pattern 由
+# build-ui-canonicals.md ❌→✅ 對照表(SSOT)驅動。零誤判:只抓高信心 raw-tag 訊號;<DS.X> 元件是
+# PascalCase + DS. prefix 不匹配小寫 raw tag;node_modules 已於上方排除;有理由可 @ds-misuse-allow escape。
+if echo "$CONTENT" | grep -qE '<table\b' && echo "$CONTENT" | grep -qE '<thead\b|<tbody\b|<th\b'; then
+  VIOLATIONS="${VIOLATIONS}  - 手刻 raw <table><thead>/<tbody> 資料表 → 必用 <DataTable columns={...} data={...} />(build-ui-canonicals.md:18 ❌→✅ SSOT;這是「優先消費既有元件」大原則,無理由不得手刻)\n"
+fi
+if echo "$CONTENT" | grep -qE '<img\b[^>]*rounded-full'; then
+  VIOLATIONS="${VIOLATIONS}  - 手刻 <img ... rounded-full> 頭像 → 必用 <Avatar>(build-ui-canonicals.md:25)\n"
+fi
+if echo "$CONTENT" | grep -qE '<select\b'; then
+  VIOLATIONS="${VIOLATIONS}  - native <select> 手刻下拉 → 必用 <Select> / <DropdownMenu>(build-ui-canonicals.md:15)\n"
+fi
+if echo "$CONTENT" | grep -qE '<hr\b'; then
+  VIOLATIONS="${VIOLATIONS}  - 手刻 <hr> 分隔線 → 用 <Separator>(或 separator.spec 允許的 CSS border)(build-ui-canonicals.md:23)\n"
+fi
+
+# Pattern 6: Overlay trigger without defaultOpen state for visual demo
+# (Skip in production .tsx; only enforce in .stories.tsx where visual snapshot matters)
+if echo "$FILE" | grep -qE '\.stories\.tsx$'; then
+  for overlay in Tooltip Popover Dialog Sheet DropdownMenu; do
+    if echo "$CONTENT" | grep -qE "<DS\.${overlay}\b" && \
+       ! echo "$CONTENT" | grep -qE "(defaultOpen|open=\{(true|isOpen)\})"; then
+      VIOLATIONS="${VIOLATIONS}  - Story uses <${overlay}> without defaultOpen — visual audit can't see overlay content\n"
+    fi
+  done
+fi
+
+if [ -n "$VIOLATIONS" ]; then
+  cat >&2 << EOF
+🚨 CONSUMER-DS-PRIMITIVE-MISUSE BLOCKER(P0,2026-05-27 user verbatim「做產品真的要能使用跟 ds repo 一模一樣的元件」)
+
+  File $FILE detected anti-pattern DS API usage:
+$(echo -e "$VIOLATIONS")
+  per M31 codex synthesis SSOT + DS spec.md citations(file:line 在每條 violation).
+
+  Anchor:user 2026-05-27 抓 7 個 visual bug 全 root cause = consumer minimal-mock 抹平
+  DS canonical 設計意圖。本 hook 攔 production 重犯同 pattern。
+
+  修法 2 選 1:
+    (a) 改用 DS canonical pattern(per file:line cited spec).
+    (b) Escape:加 \`// @ds-misuse-allow: <rationale>\` 顯式 documented per file OR per line.
+
+  Per-bug fix paths → /tmp/codex-ssot-output.txt(M31 codex synthesis 2026-05-27)
+EOF
+  exit 2
+fi
+
+exit 0
+}
+
+r4_app_story_title() {
+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:apps/<name>/**/*.stories.(tsx|ts|mdx)
+if ! echo "$FILE" | grep -qE '(^|/)apps/[^/]+/.+\.stories\.(tsx|ts|mdx)$'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# Escape clause
+if echo "$CONTENT" | grep -qE '@app-story-title-skip:'; then exit 0; fi
+
+# Extract expected app name from file path
+APP_NAME=$(echo "$FILE" | sed -E 's|.*/apps/([^/]+)/.*|\1|')
+[ -z "$APP_NAME" ] && exit 0
+
+# Find title field(支援 single/double/backtick quote)
+TITLE_LINE=$(echo "$CONTENT" | grep -oE "title:\s*['\"\`][^'\"\`]+['\"\`]" | head -1)
+
+# 若無 title field,skip(no-op stories OK)
+[ -z "$TITLE_LINE" ] && exit 0
+
+EXPECTED_PREFIX="Apps/${APP_NAME}/"
+
+# Check title 是否開頭 `Apps/<app-name>/`
+if ! echo "$TITLE_LINE" | grep -qE "title:\s*['\"\`]Apps/${APP_NAME}/"; then
+  cat >&2 << EOF
+🚨 CONSUMER APP STORY TITLE BLOCKER(P0,2026-05-28 codify per create-app duplicate-id anchor)
+
+  File: $FILE
+  Detected title: $TITLE_LINE
+  Expected prefix: \`title: 'Apps/${APP_NAME}/...'\`
+
+  Why blocked:
+    Consumer apps 內 stories 必用 \`Apps/<app-name>/<page-purpose>\` 開頭 namespace
+    (per .claude/rules/story-rules.md「Title 命名 2-namespace canonical」)。
+    錯 prefix → Storybook glob 撈到後與 template/其他 app 撞 id → build duplicate
+    warning + 只顯第一個 → 新 app 在 sidebar 不可見。
+
+  Anchor:2026-05-28 npm run create-app 不改 story title 導致 e2e 抓 4 個 collisions。
+
+  Fix:
+    title: 'Apps/${APP_NAME}/<Your Page Purpose>'  // ex: 'Apps/${APP_NAME}/Dashboard'
+
+  Escape(極罕見):add \`// @app-story-title-skip: <rationale>\`
+EOF
+  exit 2
+fi
+
+exit 0
+}
+
+for _rule in r1_no_ds_catalog r2_story_baseline r3_ds_primitive_misuse r4_app_story_title; do
+  echo "$INPUT" | "$_rule"
+  _rc=$?
+  if [ "$_rc" -eq 2 ]; then exit 2; fi
+done
+exit 0