@qijenchen/design-system 0.1.0-beta.68 → 0.1.0-beta.70

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

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