@qijenchen/design-system 0.1.0-beta.30 → 0.1.0-beta.33

package/CLAUDE.md

@@ -32,7 +32,7 @@
 
 ## 行數預算(Anthropic 對齊)
 
-CLAUDE.md target ≤ 200(Anthropic best-practice)/ transition ≤ 400 / hard cap 800。SKILL ≤ 250 / spec ≤ 300(foundational SSOT 例外 ≤ 800-1200)/ memory **per-file ≤ 100 lines** + **MEMORY.md index ≤ 20 entries**(soft 18 / hard 20,session-start hook 攔)。Hooks **26 soft / 40 hard**(SSOT = `session_start_governance_check.sh:173`)。動態值見 `scripts/sync-governance-counters.mjs` 跑出為準(2026-05-23:**31 M-rules / 56 audit dims / 37 hooks** — 不寫死避 drift,per 2026-05-22 prune codify)。
+CLAUDE.md target ≤ 200(Anthropic best-practice)/ transition ≤ 400 / hard cap 800。SKILL ≤ 250 / spec ≤ 300(foundational SSOT 例外 ≤ 800-1200)/ memory **per-file ≤ 100 lines** + **MEMORY.md index ≤ 20 entries**(soft 18 / hard 20,session-start hook 攔)。Hooks **26 soft / 60 hard**(SSOT = `session_start_governance_check.sh:186`,2026-05-27 升 50→55→60 per codex M31 P0 hooks + baseline + primitive-misuse 3 new hooks)。動態值見 `scripts/sync-governance-counters.mjs` 跑出為準(snapshot 2026-05-28:**31 M-rules / 82 audit dims / 59 hooks** — 數字僅供 sanity check,真值以 script 輸出為準避 drift)。
 
 ## Anti-bloat L1-L3
 
@@ -85,6 +85,7 @@ CLAUDE.md target ≤ 200(Anthropic best-practice)/ transition ≤ 400 / hard cap
 | **寫 story / 視覺 code** | `/story-writing` + `# SSOT 消費 canonical` |
 | **命名新檔 / 變數 / prop** | `# 命名與語言一致性` + `.claude/rules/ui-development.md`「元件 Props 命名」 |
 | **新元件 layout** | `# 4-Family Layout Model` |
+| **建產品 / 開新 product app** | `npm run create-app <name>` → `apps/<name>/`;**2-scenario architecture SSOT** → `.claude/references/scenario-definition.md`(Scenario A / Scenario B 定義 + 20 test case + mirror chain + verify checkpoints,**之後增刪改 reference 此 SSOT**)|
 | **新 skill / hook / command** | `.claude/{home}/README.md` charter |
 | **無前例設計決策** | `# 遇不確定時的協議` |
 | **Tailwind 出怪事** | `.claude/rules/ui-development.md`「Tailwind 5 條核心」+ `# 失敗記憶索引` |
@@ -106,6 +107,7 @@ CLAUDE.md target ≤ 200(Anthropic best-practice)/ transition ≤ 400 / hard cap
 | 3 告訴 user 主要 change(or preview URL)| 讓 user 知道看什麼 |
 | 4 等 user trigger | **「push / OK / 好 / 合 main」** → step 5;**「改 X / 不對 / 等等」** → 繼續 step 1 |
 | 5 Squash merge to main | 不開 PR(可 GitHub API squash-merge OR fast-forward)|
+| 5.5 **SSOT propagation gate**(2026-05-26 加 per user verbatim「push main 後所有 repo 都能獲得更新」)| Hook `check_post_main_ssot_propagate.sh` 偵測 `git push origin main` + diff HEAD~..HEAD 含 SSOT-affecting paths(`packages/{design-system,storybook-config}/src` / `.claude/{rules,hooks,skills,commands,references}` / `.claude-plugin/*.json` / `hooks/hooks.json` / `CLAUDE.md`)→ inject context 提議 bump npm `0.1.0-beta.<N+1>` + tag。AI 跑 bump + push tag → Release workflow auto-fire → npm publish → ds-product-template + fork repos Dependabot daily auto-PR(整鏈 1 trigger 涵蓋 /knowledge-prune / /deep-audit-cross-codex / 一般 dev / 任何 SSOT-affecting 來源,不需 skill-specific Phase Z)|
 | 6 砍 remote branch | `git push origin --delete <branch>` ;sandbox HTTP 403 → 提醒 user GitHub UI 手動 |
 | 7 Local 對齊 | `git checkout main && git fetch && git reset --hard origin/main && git branch -d <branch>` |
 
@@ -192,10 +194,6 @@ Vite + React + TypeScript + Tailwind v4 + shadcn/ui + Storybook + 自訂 Design
 - `.claude/rules/ui-development.md` — paths: `**/*.tsx` + `**/*.ts`(含 Tailwind / Token / Props 命名 / shadcn)
 - `.claude/rules/story-rules.md` — paths: `**/*.stories.tsx`(三層定位 + Title + 範例最高準則)
 
-# 元件完成 checklist
+# 元件完成 + Exploration
 
-merge 前 invoke `/component-quality-gate`(45 項 + visual + clean-code 三層)。
-
-# Exploration & Prototype
-
-正式 `packages/design-system/src/`(Phase 1 後 npm workspace 內化)vs 比稿 `src/explorations/`(hook `block_prototype_imports.py` 強制隔離)。比稿 `*.v1.stories.tsx` + `notes.md`,定案升級 patterns/ 或 components/。Skills:`/prototype` / `/component-quality-gate` / `/delivery-handoff`。
+merge 前 invoke `/component-quality-gate`(45 項 + visual + clean-code 三層)。正式 `packages/design-system/src/`(Phase 1 後 npm workspace 內化)vs 比稿 `src/explorations/`(hook `block_prototype_imports.py` 強制隔離);比稿 `*.v1.stories.tsx` + `notes.md`,定案升級 patterns/ 或 components/。Skills:`/prototype` / `/component-quality-gate` / `/delivery-handoff`。

package/README.md

@@ -76,7 +76,7 @@ import { Button, Avatar, Dialog } from '@qijenchen/design-system'
 <Dialog>...</Dialog>
 ```
 
-**只用 top barrel import**(對齊 Material UI canonical)。`./components/<Name>` subpath 目前未支援 — v1.0.0 stable 才會開啟(待 cross-component export name collision rename 完成)。
+**預設用 top barrel import**(對齊 Material UI canonical)。需要更窄的 import surface 時,也支援 `@qijenchen/design-system/components/<Name>` / `patterns/<Name>` / `hooks/<name>` subpath(見 package `exports`)。
 
 Tree-shake 透過 `sideEffects: ["**/*.css"]` 配置自動 work,unused JS 被 bundler 剝除。
 
@@ -106,7 +106,7 @@ Token `--font-sans` stack = `Roboto, -apple-system, BlinkMacSystemFont, "Segoe U
 
 ## Storybook(consumer 看 DS 元件用法)
 
-- Production:**https://ajenchen.github.io/design-system/**
+- Production:**https://ajenchen-design-system.netlify.app/**(GH Pages mirror: <https://ajenchen.github.io/design-system/>)
 - 看每個元件的「展示」/「設計規格」/「設計原則」3 層 stories
 
 ---

package/ds-canonical/hooks/auto_regen_ds_barrel.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# auto_regen_ds_barrel.sh — PostToolUse 自動 regen barrel + per-component index
+#
+# 2026-05-25 SSOT auto-sync invariant(user 永久 directive 2026-05-23):
+# DS infra 增刪改 → package 該同步的都該自動,不需耳提面命。
+# 解決 gap:新增 / 刪除 packages/design-system/src/{components,patterns}/<Dir>/ 後
+# barrel `src/index.ts` 沒 auto-regen → consumer subpath import 壞 / new component 漏 export。
+#
+# Fire condition(PostToolUse Write|Edit|MultiEdit):
+#   - Write/Edit 創建新 `packages/design-system/src/components/<Dir>/<kebab>.tsx`
+#     OR 改動 component primary tsx(可能 export 名 change)
+#   - Write/Edit 創建 / 改動 `index.ts` in components/<Dir>/ or patterns/<dir>/
+#   - 新增 / 移除 hooks/*.ts or lib/*.ts(barrel 也 include 這些)
+#
+# Action:silent fire `node scripts/gen-component-indexes.mjs` + `node scripts/gen-design-system-barrel.mjs`
+# 不 BLOCKER — auto fix-up,不打斷 workflow。emit message 告訴 AI「已 auto regen barrel」
+# 對齊 sync-version-to-all-manifests.mjs pattern(post-action auto fix-up)
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null || echo "")
+
+if [ -z "$FILE_PATH" ]; then exit 0; fi
+
+# Scope filter:必 packages/design-system/src/{components,patterns,hooks,lib}/**
+if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/(components|patterns|hooks|lib)/'; then
+  exit 0
+fi
+
+# Skip stories / spec / test files(not barrel-included)
+if echo "$FILE_PATH" | grep -qE '\.(stories|anatomy\.stories|principles\.stories|spec|test|spec\.md)\.(tsx?|md)$'; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+cd "$PROJECT_DIR" 2>/dev/null || exit 0
+
+# Fire 2 gen scripts silently(stderr captured for diagnostics)
+INDEX_OUT=$(node scripts/gen-component-indexes.mjs 2>&1 || true)
+BARREL_OUT=$(node scripts/gen-design-system-barrel.mjs 2>&1 || true)
+
+# Only emit additionalContext if barrel content changed(detected by checking if grep finds count delta)
+# Simple proxy:grep "generated" in output means script ran successfully
+if echo "$BARREL_OUT" | grep -qE 'generated|with [0-9]+ components'; then
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "🔄 auto-regen DS barrel(SSOT auto-sync per 2026-05-23 user directive)— $FILE_PATH 改動觸發 \`gen-component-indexes.mjs\` + \`gen-design-system-barrel.mjs\` re-run。Barrel src/index.ts + per-component index.ts 已對齊。若 commit 此 turn 改動,記得 stage barrel 變化。"
+  }
+}
+EOF
+fi
+
+exit 0

package/ds-canonical/hooks/check_addon_subdir_ship.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# check_addon_subdir_ship.sh — P0 BLOCKER
+#
+# Per 2026-05-28 beta.27 release fail anchor:
+# ds-devmode addon 2026-05-27 從 .storybook/addons/ 搬到 packages/storybook-config/
+# addons/ 時主檔(constants/manager/Panel/preset/preview)有搬,但 preview.ts 依
+# 賴的 utils/ 子資料夾(6 files:dom-geometry/computed-style/token-reverse-lookup/
+# overlay/geometry-diagnostic/token-drift-detector)沒搬 → npm package build 時
+# Rollup「Could not resolve "./utils/dom-geometry"」→ CSF parse error cascade。
+#
+# 機械強制 PreToolUse Edit/Write 對 addon 主檔(preview.ts / manager.tsx 等):
+# 偵測 import 從 `./utils/*` / `./components/*` 等 relative subdir,但對應 dir 不
+# 存在於 file_path 同層 → BLOCK + cite missing files。
+#
+# Scope:packages/storybook-config/addons/ + .storybook/addons/ 內主檔。
+# Escape:`@addon-subdir-skip:` comment。
+
+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 addon main files
+if ! echo "$FILE" | grep -qE '/(\.storybook|storybook-config)/addons/[^/]+/[a-zA-Z]+\.(ts|tsx)$'; 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 '@addon-subdir-skip:'; then exit 0; fi
+
+# Find relative subdir imports `./<dir>/*`
+RELATIVE_IMPORTS=$(echo "$CONTENT" | grep -oE "from\s+['\"]\\./[a-zA-Z][a-zA-Z0-9_-]+/[a-zA-Z][a-zA-Z0-9_./-]*['\"]" | sed -E "s|^from\s+['\"]\./([^/]+)/.*['\"]$|\\1|" | sort -u)
+
+[ -z "$RELATIVE_IMPORTS" ] && exit 0
+
+ADDON_DIR=$(dirname "$FILE")
+MISSING=""
+for subdir in $RELATIVE_IMPORTS; do
+  if [ ! -d "$ADDON_DIR/$subdir" ]; then
+    MISSING="${MISSING}    - ./${subdir}/ (referenced but dir absent)\n"
+  fi
+done
+
+if [ -n "$MISSING" ]; then
+  cat >&2 << EOF
+🚨 ADDON SUBDIR SHIP BLOCKER(P0,2026-05-28 beta.27 anchor)
+
+  File: $FILE
+  Imports from subdirectories that don't exist alongside this file:
+$(printf '%b' "$MISSING")
+
+  Why blocked:
+    Addon main 檔 import 子資料夾 helper,但子 dir 沒一起 ship → npm build /
+    Rollup「Could not resolve」→ Storybook build 死。本 anchor:beta.27 第 7 次 CI
+    才抓到 ds-devmode 搬家漏帶 utils/ 6 files(燒 6 prior iterations debug)。
+
+  修方向:
+    1. Copy 缺漏 dir 過來:`cp -r <source>/<dir> $ADDON_DIR/<dir>`
+    2. 跑 npm run build-storybook local 過再 commit
+    3. 或:改 import 路徑 to existing location
+
+  Escape(極罕見): add \`// @addon-subdir-skip: <rationale>\` to file content
+EOF
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_chrome_header_avatar_canonical.sh

@@ -0,0 +1,84 @@
+#!/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
+HAS_DRIFT=$(printf '%s' "$NEW" | python3 -c '
+import sys, re
+content = sys.stdin.read()
+# 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#*/my-project/}
+
+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
+exit 0

package/ds-canonical/hooks/check_codex_brief_invariants.sh

@@ -24,21 +24,46 @@ esac
 
 CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
 
-# Only fire on codex CLI invocations
-if ! echo "$CMD" | grep -qE 'codex[[:space:]]+(exec|review)|node_modules/.bin/codex'; then
+# Only fire on codex CLI invocations actually executing a brief
+# (must be followed by `exec` or `review` subcommand; bare path mention like
+# `ls node_modules/.bin/codex` or `which codex` is discovery, not a brief)
+if ! echo "$CMD" | grep -qE '(^|[[:space:]/])codex[[:space:]]+(exec|review)\b'; then
   exit 0
 fi
 
-# Extract brief content — handles `cat /tmp/file | codex exec` OR `codex exec "inline"` patterns
+# Discovery / introspection flags are not briefs — skip
+if echo "$CMD" | grep -qE '(^|[[:space:]])-{1,2}(help|h|version|V)\b'; then
+  exit 0
+fi
+
+# Extract brief content — handles multiple invocation patterns:
+#   1. `cat /tmp/file | codex exec`          (cat-pipe → file)
+#   2. `codex exec "$(cat /tmp/file)"`       (arg-substitution → file)
+#   3. `codex exec < /tmp/file`              (stdin redirect → file)
+#   4. `codex exec "inline brief..."`        (inline arg → CMD itself)
 BRIEF_CONTENT=""
+BRIEF_FILE=""
+
+# Pattern 1: cat-pipe
 if echo "$CMD" | grep -qE 'cat[[:space:]]+[^|]+\|[[:space:]]*[^|]*codex'; then
-  # cat-pipe pattern — try reading the cat'd file
   BRIEF_FILE=$(echo "$CMD" | grep -oE 'cat[[:space:]]+[^[:space:]|]+' | head -1 | sed 's/^cat[[:space:]]*//')
-  if [ -n "$BRIEF_FILE" ] && [ -f "$BRIEF_FILE" ]; then
-    BRIEF_CONTENT=$(cat "$BRIEF_FILE" 2>/dev/null)
-  fi
 fi
-# Inline prompt pattern fallback — grab everything after `codex exec` quotes
+
+# Pattern 2: arg-substitution `"$(cat /path)"` or `$(cat /path)`
+if [ -z "$BRIEF_FILE" ] && echo "$CMD" | grep -qE '\$\([[:space:]]*cat[[:space:]]+[^)]+\)'; then
+  BRIEF_FILE=$(echo "$CMD" | grep -oE '\$\([[:space:]]*cat[[:space:]]+[^)]+\)' | head -1 | sed -E 's/^\$\([[:space:]]*cat[[:space:]]+//; s/[[:space:]]*\)$//')
+fi
+
+# Pattern 3: stdin redirect `< /path`
+if [ -z "$BRIEF_FILE" ] && echo "$CMD" | grep -qE 'codex[[:space:]]+exec[[:space:]].*<[[:space:]]*[^[:space:]<>|&]+'; then
+  BRIEF_FILE=$(echo "$CMD" | grep -oE '<[[:space:]]*[^[:space:]<>|&]+' | head -1 | sed -E 's/^<[[:space:]]*//')
+fi
+
+if [ -n "$BRIEF_FILE" ] && [ -f "$BRIEF_FILE" ]; then
+  BRIEF_CONTENT=$(cat "$BRIEF_FILE" 2>/dev/null)
+fi
+
+# Pattern 4 fallback — inline prompt (or unparseable cmd): scan CMD itself
 if [ -z "$BRIEF_CONTENT" ]; then
   BRIEF_CONTENT="$CMD"
 fi
@@ -66,6 +91,13 @@ if ! echo "$BRIEF_CONTENT" | grep -qiE '禁抽樣|禁 sample|NO-SAMPLE|不抽樣
   MISSING="${MISSING}  • 3️⃣ 禁抽樣 invariant 缺(「禁抽樣」/「NO-SAMPLE」/「sample = reject」keyword)\n"
 fi
 
+# 4. 禁列檔 invariant(2026-05-27 codify per codex v1/v2 token-burn anchor)
+# Codex CLI 2 次連續 invocation 都跑 `rg --files` / `find` 列 1300+ files 燒光 reasoning。
+# Brief 必含 directive 限制 codex 探索範圍 — 「只讀 N 列檔 + 禁列檔 / 禁 rg --files / 禁 find 全 repo」
+if ! echo "$BRIEF_CONTENT" | grep -qiE '禁列檔|禁 rg --files|禁 find 全|只讀.*[0-9]+.*file|限定.*file|targeted rg|不需報告探索|直接出'; then
+  MISSING="${MISSING}  • 4️⃣ 禁列檔 invariant 缺(「禁列檔」/「禁 rg --files」/「只讀 N file」/「直接出 verdict」keyword)— per 2026-05-27 codex token-burn 2× anchor\n"
+fi
+
 if [ -n "$MISSING" ]; then
   printf '🚨 CODEX BRIEF MISSING INVARIANTS BLOCKER(2026-05-23 user verbatim:「codex 會跑的稽核流程理應要跟你跑的深度稽核流程是一模一樣 SSOT 的不能偏移」):\n' >&2
   printf '\n  Brief 缺以下 invariant:\n' >&2

package/ds-canonical/hooks/check_consumer_app_story_title.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# check_consumer_app_story_title.sh — P0 BLOCKER
+#
+# 2026-05-28 codify per template create-app duplicate-id bug anchor:
+# Consumer apps(template / fork repos)裡 `apps/<name>/**/*.stories.tsx` 的
+# `title:` 必開頭 `Apps/<kebab-app-name>/...` — 否則 Storybook glob 撈到後撞 id。
+#
+# SSOT:.claude/rules/story-rules.md「Title 命名 2-namespace canonical」
+#
+# Mechanical 強制 PreToolUse Edit/Write 對 `apps/<name>/**/*.stories.tsx`:
+# - 偵測 `title:` field
+# - 若 title 開頭非 `Apps/<dir-name>/...` → BLOCK
+# - 自動推導 dir-name 從 file path(`apps/order-dashboard/src/App.stories.tsx`
+#   → expected prefix `Apps/order-dashboard/`)
+#
+# Scope:`/apps/<name>/**/*.stories.@(tsx|ts|mdx)`(consumer repos only)。
+# DS-internal stories(`packages/design-system/**`)走另條 canonical(`Design System/...`),
+# 不在本 hook scope。
+#
+# Escape:`@app-story-title-skip:` comment(極罕見)。
+
+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: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

package/ds-canonical/hooks/check_consumer_ds_primitive_misuse.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# check_consumer_ds_primitive_misuse.sh — P0 BLOCKER
+#
+# 偵測 consumer production code(`.tsx`)用 DS primitive 但走 anti-pattern API 用法
+# (per user 2026-05-27 verbatim「做產品真的能使用跟 ds repo 一模一樣的元件做產品嗎?」
+# +「眼不見為淨欸,重點是你他媽做產品真的要能使用跟 ds repo 一模一樣的元件才是目標」)
+#
+# Anchor 2026-05-27 — 7 bugs caught by user 在 storybook 但同樣的 anti-pattern 會出現在
+# production App.tsx / page components:
+#   1. <CircularProgress size={N}> 任意 number 而非 default 24
+#   2. <RadioGroupItem> 沒 wrap <SelectionItem control={...}>(per selection-item.spec.md:23)
+#   3. <DataTable columns={[<2 cols]}> minimal mock 看起來破
+#   4. <LinkInput placeholder=...> 沒 value prop = placeholder-only mode 抹平 link/edit pattern
+#   5. <Empty title=...> 無 icon AND 無 description = 違反 Empty.tsx:11「預設只需 description」
+#   6. <Tooltip|Popover|Dialog|Sheet|DropdownMenu> trigger 後 user 無路徑看 content
+#   7. <DS.X> 內 free-form ad-hoc layout 跟 DS canonical 結構差異
+#
+# Triggers on consumer apps/**/*.tsx + .stories.tsx edit. Blocks anti-patterns above.
+#
+# Escape:per-line `// @ds-misuse-allow: <rationale>` documented exception.
+
+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)
+# 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
+
+# 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|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 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

package/ds-canonical/hooks/check_consumer_no_ds_catalog.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# check_consumer_no_ds_catalog.sh — P0 BLOCKER
+#
+# Block consumer apps from authoring per-component DS catalog stories
+# (per M31 codex synthesis 2026-05-27: PW only owns composition stories,
+# DS canonical Storybook is the sole per-component visual SSOT).
+#
+# Anchor 2026-05-27 user verbatim:
+#   「確保跟 ds repo 一模一樣」+「全盤避免 minimal mock 抹平」
+#   7 bugs caught by user(CircularProgress size=32 / RadioGroup raw / DataTable one-col /
+#   LinkInput placeholder / Empty 缺 icon / Overlay no-open / Tooltip)— all root cause:
+#   consumer hand-mock minimal-prop render ≠ DS canonical → 必 drift.
+#
+# Triggers on consumer apps/**/*.stories.tsx edit. Blocks:
+#   - File named EveryDsComponent / AllDsComponents (catalog naming pattern)
+#   - Story title containing「所有 DS 元件」/「Every DS Component」/「per-component default render」
+#   - `import * as DS from '@qijenchen/design-system'` + `Object.keys(DS).map`(iterate-render pattern)
+#   - `<DS.X minimal-props>` repeated mass render(detect: ≥5 different DS components rendered in same story)
+#
+# Escape:`// @consumer-catalog-allow: <rationale>` per-file marker(極罕見;eg. portal proxy file).
+
+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
+# 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
+if echo "$CONTENT" | grep -q '@consumer-catalog-allow:'; 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