@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,183 @@
+#!/bin/bash
+# check_tabs_content_chrome_body_double_gap.sh — P0 BLOCKER(overlay-body layout-space guardian,2 checks)
+#
+# **Check 1**(tabs double-gap):`<TabsContent>` 被放進 chrome scroll body(`<DialogBody>` /
+#   `<SheetBody>` / `<SurfaceBody>`)內卻沒 `mt-0` override → 雙重 gap owner。
+# **Check 2**(overlay-body fixed macro gap,2026-07-01 Sheet gap-4 錨例):浮層 body 自身 className
+#   用固定 `gap-[4-9]`(macro)而非 layout-space token → lg density 不縮放,drift。詳見下方 Check 2 段。
+#
+# 兩者同屬「overlay-body layout-space 合規」domain,折進一 hook(不增 hook 數)。
+#
+# Root invariant(item-anatomy.spec.md「垂直 padding 歸屬 / 禁雙重 padding」+ layoutSpace.spec.md
+# 規則 2「Header → element = 單一 tight」):兩元素之間的 gap 只能有一個 owner。
+# - DialogBody/SheetBody/SurfaceBody 內層 padded div 已用 `pt-/py-[var(--layout-space-tight)]`
+#   擁有 header→content 的 chrome gap。
+# - TabsContent 預設帶 `mt-[var(--layout-space-tight)]`(tabs.tsx,為「緊接 tab bar 下方」而設)。
+# - tabsSlot composition 把 tab bar 抬進 header,TabsContent 留在 body → 兩 owner 疊加 =
+#   雙重 tight(md 24 / lg 32)。修法 = chrome body 內的 TabsContent 加 `className="mt-0"`
+#   把 ownership 轉移給 body(對齊 AppShell 前例 app-shell.stories.tsx + Carbon/Radix「panel
+#   單一 owner」benchmark)。
+#
+# Anchor:2026-07-01 user 在「專案設定」Dialog(dialog.stories.tsx WithTabsInHeader)DevTools
+#   抓到「專案名稱」上方兩個 --layout-space-tight。歷次稽核漏抓,因既有
+#   check_layout_space_magic_numbers.sh **明確 skip packages/design-system/src/**(該 hook L34)。
+#   本 hook **反轉 scope** 專掃 DS src + apps composition,補該盲區。
+#
+# Scope:只掃 packages/design-system/src/** + apps/** 的 .tsx(含 .stories.tsx)。
+# Level:P0 BLOCKER exit 2(layout-space SSOT 一律 P0,非 P1 WARN — per
+#   feedback_ssot_mechanical_p0_not_p1_warn_2026_05_27)。窄 gate(必同時含 chrome body + TabsContent)
+#   控 false-positive。Escape:`// @tabs-content-gap-ok: <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
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.notebook_path // ""' 2>/dev/null)
+
+# Scope:DS source + apps,.tsx only(INVERSE of check_layout_space_magic_numbers.sh 的 DS-src skip)
+if ! echo "$FILE" | grep -qE '\.tsx$'; then exit 0; fi
+if ! echo "$FILE" | grep -qE '(packages/design-system/src/|/apps/|(^|/)apps/)'; then exit 0; fi
+
+# PostToolUse:file 已寫入磁碟,讀「完整檔」做 containment 分析(避免 hunk-only partial-edit 盲區 —
+# 部分 edit 的 new_string 可能只含 TabsContent 行不含外層 DialogBody,window 分析會漏)。
+[ -f "$FILE" ] || exit 0
+CONTENT=$(cat "$FILE" 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# ══ Check 2:overlay body 自身用固定 macro gap-N → 該用 layout-space token(2026-07-01 Sheet gap-4 錨例)══
+# Root(layoutSpace.spec.md 規則 2/3):浮層 body 直接堆疊內容的垂直 gap 屬 macro layout-space,該用
+#   density-scaling token(並列 = loose / functional 交互 = tight),非固定 gap-N(lg 不縮放 → 跟 DS
+#   自己 dialog.stories 的 gap-[var(--layout-space-loose)] 不一致)。窄 gate:只抓 overlay body 自身
+#   className 的固定 gap-[4-9](macro range;排除 gap-1/2/3 micro + 已 tokenize 的 gap-[var)。
+#   全庫掃證實零現存假陽性(純防未來 drift)。Escape:同行或前一註解行 @overlay-body-gap-ok:。
+GAP_MARKER='@overlay-body-gap-ok:'
+GAP_HITS=$(printf '%s\n' "$CONTENT" | grep -nE '<(DialogBody|SheetBody|PopoverBody|SurfaceBody)[^>]*gap-[4-9]([^0-9]|$)' 2>/dev/null | grep -v 'gap-\[var')
+GAP_UNJUSTIFIED=""
+if [ -n "$GAP_HITS" ]; then
+  while IFS= read -r hit; do
+    [ -z "$hit" ] && continue
+    ln="${hit%%:*}"
+    cur="${hit#*:}"
+    if echo "$cur" | grep -qF "$GAP_MARKER"; then continue; fi
+    if [ "$ln" -gt 1 ] 2>/dev/null; then
+      prev=$(printf '%s\n' "$CONTENT" | sed -n "$((ln-1))p")
+      if echo "$prev" | grep -qF "$GAP_MARKER" && echo "$prev" | grep -qE '^[[:space:]]*(//|\{?/\*|\*)'; then continue; fi
+    fi
+    GAP_UNJUSTIFIED="${GAP_UNJUSTIFIED}${ln}: $(echo "$cur" | sed 's/^[[:space:]]*//')\n"
+  done <<< "$GAP_HITS"
+fi
+if [ -n "$GAP_UNJUSTIFIED" ]; then
+  cat >&2 << EOF
+🚨 OVERLAY-BODY FIXED-GAP BLOCKER(P0,2026-07-01 Sheet demo gap-4 錨例)
+
+  在 $FILE 偵測到浮層 body(Dialog/Sheet/Popover/Surface Body)自身用固定 macro gap-N:
+$(echo -e "$GAP_UNJUSTIFIED" | sed 's/^/    /' | head -10)
+
+  ── 為什麼 ──
+  浮層 body 直接堆疊內容(並列表單欄位 / 區塊)的垂直 gap 屬 macro layout-space,該用
+  density-scaling token(並列 = loose / functional 交互 = tight),非固定 gap-N(lg 不縮放 →
+  跟 DS 自己 dialog.stories 的 gap-[var(--layout-space-loose)] 不一致)。
+
+  ── 修法 2 選 1 ──
+    (a) gap-N → gap-[var(--layout-space-loose)](並列)/ gap-[var(--layout-space-tight)](functional 交互)
+    (b) Escape:該行或前一註解行加 \`// @overlay-body-gap-ok: <rationale>\`(刻意 list 間距 / 視覺平衡)
+
+  canonical → tokens/layoutSpace/layoutSpace.spec.md 規則 2/3
+EOF
+  exit 2
+fi
+
+# ══ Check 1:<TabsContent> 在 chrome body 內雙重 gap(原 beta.78 邏輯)══
+# Gate:必同時含 chrome body open tag 且 TabsContent 才啟動(narrow surface,絕大多數 edit 靜默)
+if ! echo "$CONTENT" | grep -qE '<(DialogBody|SheetBody|SurfaceBody)[ />]'; then exit 0; fi
+if ! echo "$CONTENT" | grep -q '<TabsContent'; then exit 0; fi
+
+ESCAPE_MARKER='@tabs-content-gap-ok:'
+
+# 逐行 depth-counter(awk):進 chrome body +1、出 -1;TabsContent 在 depth>0 = 在 chrome body 內。
+# - 註解行(JSDoc `*` / `//` / `{/*` / `/*` / `*/`)整行跳過,不計 depth 也不判 TabsContent
+#   (避免 JSDoc 內 `<DialogBody>` 範例污染 depth / 內含的 mt-0 example 被誤判)。
+# - 同行 open 先加 depth 再判 TabsContent 再減 close → 同行 `<DialogBody><TabsContent>` 與
+#   `<TabsContent>...</DialogBody>` 都正確歸屬「inside」。
+# - TabsContent opening tag 可能跨行:accumulate 到 `>` 再驗 className 有無 canonical `mt-0`
+#   (class-boundary anchored;非-0 / arbitrary 值需 escape marker)。
+# 輸出:每個「chrome body 內且無 mt-0 override」的 TabsContent 起始行號(供 bash escape 過濾)。
+CANDIDATES=$(printf '%s\n' "$CONTENT" | awk '
+  function check_tag(tag, ln) {
+    # 只認 canonical `mt-0`(class-boundary anchored):排除 `mt-0.5` / `mt-04` 等 substring 假通過
+    # (mt-0.5 是本 DS 真實 class,item-anatomy.stories.tsx:766;2px 不抵銷 pt-tight → 仍雙重)。
+    # arbitrary `mt-[...]` / 非-0 值 = 非 canonical → 需 escape marker 明示 documented(非靜默通過)。
+    if (tag ~ /(^|[^a-zA-Z0-9])mt-0([^a-zA-Z0-9.]|$)/) return
+    print ln
+  }
+  BEGIN { depth=0; collecting=0; buf=""; startline=0 }
+  {
+    raw=$0
+    if (collecting) {
+      buf = buf " " raw
+      if (raw ~ />/) { collecting=0; check_tag(buf, startline); buf="" }
+      next
+    }
+    t=raw; sub(/^[ \t]+/,"",t)
+    if (t ~ /^(\*|\/\/|\{?\/\*|\*\/)/) next          # skip comment-only lines
+    tmp=raw;  o=gsub(/<(DialogBody|SheetBody|SurfaceBody)[ \t\/>]/,"X",tmp)
+    tmpc=raw; c=gsub(/<\/(DialogBody|SheetBody|SurfaceBody)>/,"X",tmpc)
+    depth += o
+    if (raw ~ /<TabsContent/ && depth > 0) {
+      idx = index(raw, "<TabsContent")
+      rest = substr(raw, idx)
+      if (rest ~ />/) { gt = index(rest, ">"); check_tag(substr(rest, 1, gt), NR) }
+      else { collecting=1; buf=rest; startline=NR }
+    }
+    depth -= c
+  }
+')
+
+if [ -z "$CANDIDATES" ]; then exit 0; fi
+
+# Escape 過濾:同行 OR 前一「註解專用行」含 @tabs-content-gap-ok: → 豁免(對齊
+# check_layout_space_magic_numbers.sh L57-69 已 debug 過的 preceding-line marker 邏輯)。
+UNJUSTIFIED=""
+while IFS= read -r ln; do
+  [ -z "$ln" ] && continue
+  cur=$(echo "$CONTENT" | sed -n "${ln}p")
+  if echo "$cur" | grep -qF "$ESCAPE_MARKER"; then continue; fi
+  if [ "$ln" -gt 1 ] 2>/dev/null; then
+    prev=$(echo "$CONTENT" | sed -n "$((ln-1))p")
+    if echo "$prev" | grep -qF "$ESCAPE_MARKER" && echo "$prev" | grep -qE '^[[:space:]]*(//|\{?/\*|\*)'; then continue; fi
+  fi
+  UNJUSTIFIED="${UNJUSTIFIED}${ln}: $(echo "$cur" | sed 's/^[[:space:]]*//')\n"
+done <<< "$CANDIDATES"
+
+if [ -z "$UNJUSTIFIED" ]; then exit 0; fi
+
+cat >&2 << EOF
+🚨 TABS-CONTENT-CHROME-BODY DOUBLE-GAP BLOCKER(P0,2026-07-01 user「專案名稱上方兩個 space-tight」)
+
+  在 $FILE 偵測到 <TabsContent> 放在 chrome scroll body(DialogBody/SheetBody/SurfaceBody)內
+  但未 override margin-top:
+$(echo -e "$UNJUSTIFIED" | sed 's/^/    /' | head -10)
+
+  ── 為什麼是 bug ──
+  DialogBody/SheetBody/SurfaceBody 內層已用 pt-/py-[var(--layout-space-tight)] 擁有 header→content
+  的 chrome gap;TabsContent 預設又帶 mt-[var(--layout-space-tight)](tabs.tsx,為緊接 tab bar 而設)。
+  tabsSlot composition 把 tab bar 抬進 header 後,兩個 owner 疊加 = 雙重 tight(md 24 / lg 32)。
+  一軸只能有一個 spacing owner(item-anatomy.spec.md「垂直 padding 歸屬 / 禁雙重 padding」)。
+
+  ── 修法 2 選 1 ──
+    (a) chrome body 內的 TabsContent 加 \`className="mt-0"\` 把 ownership 轉移給 body
+        (對齊 AppShell 前例 app-shell.stories.tsx + Carbon/Radix「panel 單一 owner」benchmark)
+    (b) Escape:該行或前一註解行加 \`// @tabs-content-gap-ok: <rationale>\`(顯式 documented 例外)
+
+  完整 canonical → components/Tabs/tabs.spec.md「出現在 Dialog」段
+                 + tokens/layoutSpace/layoutSpace.spec.md 規則 2
+EOF
+exit 2

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

@@ -0,0 +1,79 @@
+#!/bin/bash
+# check_tailwind_wildcard_in_docs.sh — P0 BLOCKER
+#
+# Per 2026-05-28 beta.27 release fail anchor(6+ CI iterations 燒):
+# Tailwind v4 vite plugin scans .md / .spec.md / docs by default。
+# 文件範例 like `shadow-[var(--elevation-*)]` 或 `var(--field-height-*)` /
+# `var(--elevation-100/200/300)` 是給 dev 看的 shorthand notation(`*` /  `/` 代表
+# enumeration placeholder),但 Tailwind 不知 → 當 literal class string 抓 → 產
+# invalid CSS `var(--X-*)` `var(--X-A/B/C)` → Storybook FULL smoke 死。
+#
+# 機械強制 PreToolUse Edit/Write:阻止寫入新檔含此 anti-pattern。
+# 改用 math notation:`var(--X-N) N∈{a,b,c}` Tailwind 不會誤判。
+#
+# Scope:所有 .md / .spec.md / .sh / .ts / .tsx 寫入時 grep new_string。
+# Exit 2 BLOCKER + cite this anchor。Escape:`@tailwind-wildcard-allow:` 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)
+# Self-exemption:本 hook help-text 合法含 anti-pattern literal 作為文件範例(且 .sh 不被 Tailwind
+# vite plugin 掃,無 build 風險)→ 不掃自己,避免 self-trigger false-positive(2026-05-30 test-surfaced)。
+case "$FILE" in */check_tailwind_wildcard_in_docs.sh) exit 0 ;; esac
+# 2026-06-11 R2 held-item #13:.claude/{tmp,logs} 歷史 artifact(codex brief / reply、audit findings
+# json、preflight log)非 Tailwind 掃描對象 — src/globals.css 用 explicit positive @source(只掃 src/ +
+# packages/{design-system,storybook-config} + .storybook/)且 `@source not "**/.claude/**"`;盤上 12 檔
+# 已含 antiPattern 而 build 連續綠(至 beta.61)= 零 build 風險實證。掃描對象路徑(src/packages/docs)
+# 保護不變。
+case "$FILE" in */.claude/tmp/*|*/.claude/logs/*|.claude/tmp/*|.claude/logs/*) exit 0 ;; esac
+# Only check files Tailwind v4 might scan
+if ! echo "$FILE" | grep -qE '\.(md|spec\.md|sh|ts|tsx|css|json)$'; 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 '@tailwind-wildcard-allow:'; then exit 0; fi
+
+# Detect anti-patterns(class form with wildcard / slash enumeration in CSS var)
+# 2026-05-30 fix(test-surfaced M34 over-narrow):slash-segment 改 repeatable,
+# 否則漏多段斜線列舉形式(beta.27 anchor 的 N-段 enum,hook header 列為必擋 anti-pattern)。
+ANTI_PATTERNS=$(echo "$CONTENT" | grep -oE 'var\(--[a-z][a-z0-9-]*([\*/]+[a-z0-9-]*)+\)' | sort -u)
+
+if [ -n "$ANTI_PATTERNS" ]; then
+  cat >&2 << EOF
+🚨 TAILWIND v4 WILDCARD-IN-DOCS BLOCKER(P0,2026-05-28 beta.27 anchor)
+
+  File: $FILE
+  Detected anti-pattern(s):
+$(echo "$ANTI_PATTERNS" | sed 's/^/    /')
+
+  Why blocked:
+    Tailwind v4 vite plugin scans .md/.ts/etc → 把 \`var(--X-*)\` / \`var(--X-A/B/C)\`
+    當 literal class string 抓 → 產 invalid CSS(CSS 變數名禁 \`*\` / \`/\`)→ Storybook
+    build 死 → release CI fail。本 anchor:beta.27 6+ CI iteration 燒此問題。
+
+  改用 math notation(Tailwind 不誤判):
+    var(--elevation-*)         → var(--elevation-N) N∈{100,200}
+    var(--elevation-100/200) → var(--elevation-N) N∈{100,200}
+    var(--field-height-*)      → var(--field-height-N) N∈{sm,md,lg}
+    var(--layout-space-*)      → var(--layout-space-N) N∈{loose,tight}
+    var(--radix-*-available-height) → var(--radix-{popover|hover-card|dialog}-content-available-height)
+
+  Escape(極罕見,本 file 真需要 wildcard token literal):
+    add \`// @tailwind-wildcard-allow: <rationale>\` to file content
+EOF
+  exit 2
+fi
+
+exit 0

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

@@ -0,0 +1,238 @@
+#!/bin/bash
+# inject_deploy_url_after_push.sh — UserPromptSubmit + PostToolUse: 偵測 git push 後自動 inject deploy URL
+#
+# Per user verbatim 2026-05-26:「完成部署之後都應該自動回吐部署的連結,每次必定自動回,不論是現在這個 session 還是其他的」
+# Per user verbatim 2026-05-27:「不管在任何 repo,只要有部署東西到 netlify 上不管是否是 production 都應該要提供連結」
+#
+# Mechanism(2026-05-27 v2 expand scope per user complaint — DS GH Pages also auto-provide URL):
+#   PostToolUse Bash:tool_input.command 含 `git push origin <branch>` → 偵測 → multi-target URL detection:
+#     1. Netlify(scripts/deploy-url.mjs + .netlify/state.json)— PW + fork
+#     2. Netlify dashboard-link(netlify.toml exists,no state.json)— PW with Netlify auto-build
+#     3. GitHub Pages(.github/workflows/*.yml 含 pages action)— DS repo
+#   → output URL list inject into AI context(下個 reply 必看到)
+#
+# 為何走 Hook(per CLAUDE.md governance 8-home L7 Hook 自動化):
+#   - 不靠 AI 記得「每次推完都要 echo URL」(會忘記 — 本 session user 抓「你他媽到底做得怎樣」)
+#   - 不靠 user 每次問「部署到哪?」(無聊重複)
+#   - Hook 機械保證每 push 必觸發,跨 session / 跨 fork user 自動受惠
+#
+# Scope expanded(2026-05-27):
+#   - Netlify CLI-linked (.netlify/state.json + scripts/deploy-url.mjs) → 直接 script 抓 URL
+#   - Netlify dashboard-linked (netlify.toml + branch deploys) → 用 git remote 推導 site name
+#   - GitHub Pages (.github/workflows/*.yml 含 pages.yml OR ci.yml deploy-pages) → 推導 GH Pages URL
+#
+# 對齊:.claude/skills/codex-collab/SKILL.md PostToolUse pattern + check_fork_user_plugin_install.sh detection pattern
+
+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)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+# Scope:PostToolUse Bash 且 cmd 含 git push to remote(main / branch)
+[ "$EVENT" != "PostToolUse" ] && exit 0
+[ "$TOOL" != "Bash" ] && exit 0
+
+# Heuristic:detect `git push origin <branch>` patterns
+# 2026-06-06 fix:要求 `git push` 在「命令邊界」(行首 / ; / && / || / $( )擋字串提及(`P='git push origin'`)。
+# 2026-06-07 fix(對抗 sweep):容忍 env-prefix(`GIT_SSH_COMMAND=… git push`)/ `git -C <dir>` /
+# push 前後任意 flag(`--force-with-lease` / `-f` / `--set-upstream` / `--no-verify` 等)。原本只認 `-u`
+# → 漏 fire 在這些「真實 push」上 = 該吐 URL 卻沒吐,defeat hook purpose。
+_ENVP='([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]+[[:space:]]+)*'
+_GITPRE='git[[:space:]]+(-C[[:space:]]+[^[:space:]]+[[:space:]]+|-[A-Za-z][^[:space:]]*[[:space:]]+)*push'
+_PUSHFLAGS='([[:space:]]+-{1,2}[A-Za-z][^[:space:]]*)*'
+if ! echo "$CMD" | grep -qE "(^|[;&|(])[[:space:]]*${_ENVP}${_GITPRE}${_PUSHFLAGS}[[:space:]]+origin\b"; then
+  exit 0
+fi
+
+# Skip if push --delete (branch cleanup, not deploy)
+if echo "$CMD" | grep -qE 'push\s+origin\s+--delete'; then
+  exit 0
+fi
+
+CWD=$(pwd)
+# 2026-06-07 fix:偵測「真實 working dir」作 deploy-target 偵測根,跨 repo push 不吐「錯 repo」URL
+# (anchor:syncing ds-product-template 時吐成 DS 站台 URL)。優先 `git -C <dir>`;否則命令鏈中
+# 「最後一個 cd」(= push 時 effective cwd,**非第一個**;`echo x && cd /other && git push` 必用 /other)。
+_GITC=$(echo "$CMD" | grep -oE 'git[[:space:]]+-C[[:space:]]+[^[:space:]]+' | head -1 | sed -E 's/.*-C[[:space:]]+//; s/^"//; s/"$//')
+_LASTCD=$(echo "$CMD" | grep -oE '(^|[;&|(])[[:space:]]*cd[[:space:]]+[^;&|]+' | tail -1 | sed -E 's/.*cd[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//')
+for _d in "$_GITC" "$_LASTCD"; do
+  if [ -n "$_d" ] && [ -d "$_d" ] && git -C "$_d" rev-parse --git-dir >/dev/null 2>&1; then CWD="$_d"; break; fi
+done
+URLS_FOUND=""
+# 2026-06-07 ROOT fix:只從「git push ... origin <ref>」這一段擷取 branch,不是整條 compound command 的
+# 第一個 `origin X`。否則 `git fetch origin --quiet && git push origin main` 會誤抓 fetch 段的 `--quiet`
+# 當 branch → 推導 `--quiet--site` 404(此前 5 道 guard 都沒擋到,因 `--quiet` 全是合法 git ref 字元)。
+# 隔出 push 段(到下個 command 分隔 ; & | 為止)後,取 origin 後第一個 token。
+# PUSH_SEG 用同一 env/-C/flag-tolerant prefix 隔出 push 段(到下個分隔 ; & | 為止),再取 origin 後第一 token
+PUSH_SEG=$(echo "$CMD" | grep -oE "(^|[;&|(])[[:space:]]*${_ENVP}${_GITPRE}[^;&|]*" | head -1)
+BRANCH=$(echo "$PUSH_SEG" | grep -oE 'origin[[:space:]]+[^[:space:]]+' | head -1 | awk '{print $2}')
+# origin 後第一個 token 是 flag(`git push origin --force` = 無顯式 branch)→ 清空走 current-branch fallback
+case "$BRANCH" in -*) BRANCH="" ;; esac
+# 2026-06-06 fix:refspec `src:dst` → 取 dst(`HEAD:main` → `main`),否則推導出 `HEAD:main--site` 404 URL
+case "$BRANCH" in *:*) BRANCH="${BRANCH##*:}" ;; esac
+# 2026-06-07 fix:full-ref dst — `HEAD:refs/heads/main` → `main`(否則 `refs/heads/main--site` 誤判 preview);
+# `refs/tags/...` → tag push,skip
+case "$BRANCH" in refs/tags/*) exit 0 ;; esac
+BRANCH="${BRANCH#refs/heads/}"
+# 2026-06-06 fix:`git push origin HEAD`(或 `@`)= symbolic ref 指向當前 branch → 解析成真 branch 名。
+# 2026-06-07 fix:detached HEAD 時 show-current 回「空字串 + exit 0」→ BRANCH 留空,交給下方 value-based fallback
+# (原 `|| echo ""` 沒用,因 git 不是失敗而是成功回空)。
+if [ "$BRANCH" = "HEAD" ] || [ "$BRANCH" = "@" ]; then
+  BRANCH=$(git -C "$CWD" branch --show-current 2>/dev/null)
+fi
+# 2026-06-06 fix:BRANCH 含非法 git ref 字元(" ' 空白 \ 等)→ 此命令只是「字串裡含 git push origin」
+# (測試迴圈 / 文件 / echo),非真推送 → skip,避免把 `main"` 等垃圾推導成 404 URL 注入 context。
+# git ref 合法字元集 ⊂ [A-Za-z0-9._/-];非此集 = 必為解析噪音(root guard,涵蓋 refspec/tag 之外的雜訊)。
+if [ -n "$BRANCH" ] && ! echo "$BRANCH" | grep -qE '^[A-Za-z0-9._/-]+$'; then exit 0; fi
+# 2026-06-06 fix:tag push(`v1.2.3` 等)不產 branch-preview / production deploy → skip,
+# 否則把 tag 名當 branch 推導出 `v0.1.0-beta.56--site` 404 URL(release tag push 每次都誤吐)
+if echo "$BRANCH" | grep -qE '^v[0-9]'; then exit 0; fi
+if [ -n "$BRANCH" ] && git -C "$CWD" rev-parse --verify --quiet "refs/tags/$BRANCH" >/dev/null 2>&1; then exit 0; fi
+# 2026-06-07 fix:仍空(bare `git push origin` / detached HEAD / 解析不出)→ 取 current branch(value-based);
+# 仍空 → 無法產生合法 URL(會變 `https://--site` malformed)→ skip,不亂猜 main。
+[ -z "$BRANCH" ] && BRANCH=$(git -C "$CWD" branch --show-current 2>/dev/null)
+[ -z "$BRANCH" ] && exit 0
+
+# v3 2026-05-27:curl HEAD verify URL before reporting(per user「你確定有做到」complaint)
+# v4 2026-05-27:add content sniff(防 squat URLs 200 但 unrelated content)
+verify_url() {
+  local url="$1"
+  local code=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 5 -I "$url" 2>/dev/null)
+  case "$code" in
+    200|301|302) echo "OK" ;;
+    *) echo "FAIL:$code" ;;
+  esac
+}
+
+# v4 content sniff:check 200 URL 是 Storybook real deploy(not squat)
+# 用 Storybook hallmark patterns(sb-manager / sb-addons / @storybook/core title)
+is_storybook_deploy() {
+  local url="$1"
+  curl -s --max-time 5 -L "$url" 2>/dev/null | grep -qE "sb-manager|sb-addons|@storybook/core|storybook-static"
+}
+
+# Detection 1:Netlify CLI-linked(.netlify/state.json + scripts/deploy-url.mjs)
+DEPLOY_SCRIPT="$CWD/scripts/deploy-url.mjs"
+if [ -f "$DEPLOY_SCRIPT" ] && [ -f "$CWD/.netlify/state.json" ]; then
+  URL_INFO=$(node "$DEPLOY_SCRIPT" --json 2>/dev/null)
+  if [ -n "$URL_INFO" ]; then
+    URL=$(echo "$URL_INFO" | jq -r '.url // ""' 2>/dev/null)
+    IS_PROD=$(echo "$URL_INFO" | jq -r '.isProd // false' 2>/dev/null)
+    if [ -n "$URL" ]; then
+      if [ "$IS_PROD" = "true" ]; then
+        URLS_FOUND="${URLS_FOUND}🚀 Netlify PRODUCTION(${BRANCH}): ${URL}\n"
+      else
+        URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW(${BRANCH}): ${URL}\n"
+      fi
+    fi
+  fi
+fi
+
+# Detection 2:Netlify dashboard-linked(netlify.toml + no state.json)
+# v4:try multiple naming conventions + content sniff to filter squat URLs
+if [ -z "$URLS_FOUND" ] && [ -f "$CWD/netlify.toml" ]; then
+  GH_REMOTE=$(git -C "$CWD" remote get-url origin 2>/dev/null)
+  REPO_NAME=$(echo "$GH_REMOTE" | sed -E 's|.*/([^/.]+)(\.git)?$|\1|')
+  OWNER_REPO=$(echo "$GH_REMOTE" | sed -E 's|.*github\.com[:/]([^/]+/[^/.]+)(\.git)?$|\1|')
+  OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+
+  # v5 multi-candidate strategy(Netlify naming conventions in order of likelihood):
+  # 1. ~/.claude/local/deploy-targets.json overrides(per-user known URLs)— win all
+  # 2. <owner>-<package.json.name>.netlify.app(setup-netlify script convention,per scripts/setup-netlify-access.mjs `${ghUser}-${repoName}` formula)
+  # 3. <owner>-<repo-from-remote>.netlify.app(Netlify Import default,fork users without setup script)
+  # 4. <repo-from-remote>.netlify.app(simple,rare)
+  USER_OVERRIDE=""
+  if [ -f "$HOME/.claude/local/deploy-targets.json" ]; then
+    USER_OVERRIDE=$(jq -r --arg key "$OWNER_REPO" '.[$key] // ""' "$HOME/.claude/local/deploy-targets.json" 2>/dev/null)
+  fi
+  # Read package.json.name for setup-script convention
+  PKG_NAME=""
+  if [ -f "$CWD/package.json" ]; then
+    PKG_NAME=$(jq -r '.name // ""' "$CWD/package.json" 2>/dev/null | sed -E 's|^@[^/]+/||')  # strip npm scope
+  fi
+  CANDIDATES=""
+  if [ -n "$USER_OVERRIDE" ]; then
+    CANDIDATES="$USER_OVERRIDE"
+  else
+    # Setup-script convention candidate(highest match rate for fork users following docs)
+    if [ -n "$OWNER" ] && [ -n "$PKG_NAME" ]; then CANDIDATES="$CANDIDATES https://${OWNER}-${PKG_NAME}.netlify.app"; fi
+    # Netlify Import default(no setup script, manual dashboard import)
+    if [ -n "$OWNER" ] && [ -n "$REPO_NAME" ] && [ "$REPO_NAME" != "$PKG_NAME" ]; then
+      CANDIDATES="$CANDIDATES https://${OWNER}-${REPO_NAME}.netlify.app"
+    fi
+    # Simple fallback
+    if [ -n "$REPO_NAME" ]; then CANDIDATES="$CANDIDATES https://${REPO_NAME}.netlify.app"; fi
+  fi
+
+  REAL_URL=""; REAL_NOTE=""
+  if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+    # 2026-06-07 fix:優先「200 + Storybook content」;沒有則退「200(內容非 Storybook)」,
+    # **不丟棄**已驗 200 的 candidate。anchor:apps/template 是真 product app(非 Storybook)→ 原
+    # is_storybook_deploy 把活著的 200 deploy 誤當 squat 報「全 404」,違反 user「不管是否 production 都給連結」。
+    FALLBACK_URL=""
+    for candidate in $CANDIDATES; do
+      if [ "$(verify_url "$candidate")" = "OK" ]; then
+        if is_storybook_deploy "$candidate"; then
+          REAL_URL="$candidate"; REAL_NOTE="✅ verified 200 + Storybook content"; break
+        elif [ -z "$FALLBACK_URL" ]; then
+          FALLBACK_URL="$candidate"
+        fi
+      fi
+    done
+    if [ -z "$REAL_URL" ] && [ -n "$FALLBACK_URL" ]; then
+      REAL_URL="$FALLBACK_URL"; REAL_NOTE="✅ verified 200(內容非 Storybook — 可能 product app deploy)"
+    fi
+    if [ -n "$REAL_URL" ]; then
+      URLS_FOUND="${URLS_FOUND}🚀 Netlify PRODUCTION(${BRANCH}): ${REAL_URL}  ${REAL_NOTE}\n"
+    else
+      URLS_FOUND="${URLS_FOUND}🚀 Netlify PRODUCTION URL 未驗 — tried: ${CANDIDATES// /, }\n   ⚠️ 全 404。需要 user 手動 share dashboard URL,OR 創 \$HOME/.claude/local/deploy-targets.json:\n   {\"${OWNER_REPO}\": \"https://<actual-site>.netlify.app\"}\n"
+    fi
+  else
+    # Branch preview:always use `<branch>--<sitename>` pattern,but sitename unknown unless USER_OVERRIDE
+    if [ -n "$USER_OVERRIDE" ]; then
+      SITENAME=$(echo "$USER_OVERRIDE" | sed -E 's|https?://([^.]+)\.netlify\.app.*|\1|')
+      CANDIDATE="https://${BRANCH}--${SITENAME}.netlify.app"
+      if [ "$(verify_url "$CANDIDATE")" = "OK" ]; then
+        URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW(${BRANCH}): ${CANDIDATE}  ✅ verified 200\n"
+      else
+        URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW 推導: ${CANDIDATE}  ⚠️ 404(preview 未啟 OR build pending — Netlify build 2-3 min)\n"
+      fi
+    else
+      URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW(${BRANCH}) — sitename 未知;設 \$HOME/.claude/local/deploy-targets.json 後 hook 可推 preview URL\n"
+    fi
+  fi
+fi
+
+# Detection 3:GitHub Pages(.github/workflows/*.yml deploys to gh-pages OR uses actions/deploy-pages)
+if ls "$CWD/.github/workflows/"*.yml >/dev/null 2>&1; then
+  if grep -l "actions/deploy-pages\|gh-pages\|github.io" "$CWD/.github/workflows/"*.yml >/dev/null 2>&1; then
+    GH_REMOTE=$(git -C "$CWD" remote get-url origin 2>/dev/null)
+    OWNER_REPO=$(echo "$GH_REMOTE" | sed -E 's|.*github\.com[:/]([^/]+/[^/.]+)(\.git)?$|\1|')
+    OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+    REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
+    if [ -n "$OWNER" ] && [ -n "$REPO" ] && { [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; }; then
+      CANDIDATE="https://${OWNER}.github.io/${REPO}/"
+      VERIFY=$(verify_url "$CANDIDATE")
+      if [ "$VERIFY" = "OK" ]; then
+        URLS_FOUND="${URLS_FOUND}📄 GitHub Pages(${BRANCH}): ${CANDIDATE}  ✅ verified 200\n"
+      else
+        URLS_FOUND="${URLS_FOUND}📄 GitHub Pages 推導 URL: ${CANDIDATE}  ⚠️ ${VERIFY}(build ~3-5 min;若仍 404 check Actions tab build status)\n"
+      fi
+    fi
+  fi
+fi
+
+# No deploy target detected → silent skip
+[ -z "$URLS_FOUND" ] && exit 0
+
+# Inject into AI context
+# 2026-05-29 ROOT-CAUSE FIX:PostToolUse hook 的純 stdout **不會**注入 AI context(只進 transcript)→
+# 原 `printf` 輸出讓 AI 看不到 URL → AI 每次 push 都沒 relay 給 user(user verbatim「部署完都沒給我 url」)。
+# 必須輸出 JSON `hookSpecificOutput.additionalContext` 才會真注入 AI context。
+MSG=$(printf '%b' "🚀 Deploy URLs auto-detected — RELAY 給 user(per user 2026-05-26「完成部署都自動回吐連結」+ 2026-05-27「不管 repo」):\n${URLS_FOUND}\n(AI:必須把上面 URL 貼給 user,不可省略)")
+jq -n --arg ctx "$MSG" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$ctx}}'
+
+exit 0

package/ds-canonical/fork/launchers/fork-governance-dispatcher.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# fork-governance-dispatcher.sh — C-prime 治理派發器(committed in fork,極穩定、幾乎永不改)
+#
+# 這是 fork repo 唯一 commit 的「啟動器」:讀 npm 套件 ship 的 fork 治理 manifest,跑當下這個
+# event 的所有官方 fork hook。DS 未來治理增刪改 → 重生 npm 套件的 manifest → fork `npm install`
+# 後本派發器自動跑新的那套(committed 設定不用動)= 完全同步。
+#
+# 設計鐵則:
+#   - 本體在 node_modules(npm install 覆蓋 = 官方控管、使用者改不動)
+#   - manifest 缺(還沒 npm install)→ exit 0 永不 brick(bootstrap 另外發 notice)
+#   - 任一官方 fork hook exit 2(BLOCKER)→ 派發器 exit 2(轉發攔截)
+#   - 其餘 exit code 不阻擋(soft)
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+DS_FORK="${CLAUDE_PROJECT_DIR:-.}/node_modules/@qijenchen/design-system/ds-canonical/fork"
+MANIFEST="$DS_FORK/manifest.json"
+
+# 治理本體還沒就位(fork 第一個 session 還沒 npm install)→ 不阻擋(bootstrap 會發 notice)
+[ -f "$MANIFEST" ] || exit 0
+
+# 取這個 event 註冊的官方 fork hook 清單
+HOOK_FILES=$(jq -r --arg ev "$EVENT" '.hooks[$ev][]?.file // empty' "$MANIFEST" 2>/dev/null)
+[ -z "$HOOK_FILES" ] && exit 0
+
+RC=0
+while IFS= read -r hf; do
+  [ -z "$hf" ] && continue
+  body="$DS_FORK/$hf"
+  [ -f "$body" ] || continue   # 個別 body 缺 → skip,不阻擋(派發器穩健)
+  # 依副檔名選 interpreter:.py 用 python3、其餘 bash。
+  # 鐵則:用 bash 跑 .py → syntax error → exit 2 → 被下面誤判成 BLOCKER → 擋掉所有編輯(致命)。
+  # python3 缺(罕見)→ exit 127(非 2)→ 不轉發 = fail-open,不 brick。
+  case "$body" in
+    *.py) echo "$INPUT" | python3 "$body" ;;
+    *)    echo "$INPUT" | bash "$body" ;;
+  esac
+  hc=$?
+  [ "$hc" -eq 2 ] && RC=2       # 官方 hook 攔截 → 轉發攔截
+done <<< "$HOOK_FILES"
+
+exit $RC

package/ds-canonical/fork/launchers/inject_fork_governance_preamble.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# inject_fork_governance_preamble.sh — C-prime SessionStart 治理 init(install-if-missing + 事前指引注入)
+#
+# 2026-06-17 合併原 check_governance_bootstrap 的 install(adversarial run-4 MAJOR — cloud-flow race):
+#   原本 SessionStart 有 3 個 hook(bootstrap 裝 / inject 注入 / dispatcher),Claude Code 同組 hook「並行」跑。
+#   雲端 fresh-clone 時 bootstrap 還在前景 `npm install`(冷裝 30s–4min),inject 並行跑完一次 `[ -f preamble ]`
+#   檢查 → 檔案還沒到 → 靜默 exit 0 → 什麼都沒注入 = proactive 指引在雲端首次 session 失效(且每 session 重演)。
+#   修:把 install 與 inject 放「同一 hook process 內 sequential」→ 消除並行 race + 避免兩個並發 npm install 衝突。
+#   dispatcher 不再掛 SessionStart(manifest 無 SessionStart body = 本來就 no-op);它留在 Pre/Post/UserPromptSubmit。
+#
+# fail-open:install 失敗 / preamble 缺 → notice + exit 0,永不 brick。
+# 對齊既有用 additionalContext 的 hook 輸出契約。
+
+set -uo pipefail
+PD="${CLAUDE_PROJECT_DIR:-.}"
+FORK="$PD/node_modules/@qijenchen/design-system/ds-canonical/fork"
+PREAMBLE="$FORK/preamble.md"
+
+# (1) 治理本體缺(雲端 fresh-clone / 還沒裝)+ 有 package.json → 前景裝 @beta。
+# 這裡 block 到裝完才往下讀 → sequential,後面的讀取保證在 install 之後(消除 race)。
+# codex risk 2:plain `npm install` 會被 lockfile 重現舊樹 → 明確 @beta 拿最新治理。
+if [ ! -f "$PREAMBLE" ] && [ -f "$PD/package.json" ]; then
+  echo "💡 DS 治理本體缺(可能雲端 fresh-clone session)→ 自動裝最新治理(@beta)…" >&2
+  ( cd "$PD" && npm install @qijenchen/design-system@beta @qijenchen/storybook-config@beta --legacy-peer-deps --no-audit --no-fund >/dev/null 2>&1 ) || true
+fi
+
+# (1b) 自我修復 skills/commands/agents:本體在但 .claude/skills 尚未送達(C-prime 之前的舊 fork / 尚未 sync-all)→ 從 npm 補。
+# ⚠️ Claude Code 在 SessionStart hook 跑「之前」就掃過 .claude/skills → 補的 skill「下個 session」才可叫用(self-heal,非當場;
+#    全新 use-template/fork 因 committed scaffold 不走此路、session-1 即有)。fail-open:任何錯都不阻擋。
+if [ -f "$PREAMBLE" ] && [ ! -e "$PD/.claude/skills/prototype" ] && [ -f "$PD/scripts/refresh-fork-launchers.mjs" ]; then
+  echo "💡 偵測 .claude/skills 尚未送達 → 從 npm 自我修復(下個 session 可叫用 /prototype 等 skill)…" >&2
+  ( cd "$PD" && node scripts/refresh-fork-launchers.mjs >/dev/null 2>&1 ) || true
+fi
+
+# (2) 本體在(本機持久 / 剛裝完)→ 讀 + 經 additionalContext 注入設計紀律
+if [ -f "$PREAMBLE" ]; then
+  CONTENT=$(cat "$PREAMBLE" 2>/dev/null)
+  if [ -n "$CONTENT" ]; then
+    jq -n --arg ctx "$CONTENT" '{
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: ("# DS 設計治理(npm-current,事前主動遵循)\n\n" + $ctx)
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# (3) 仍缺(install 失敗 / 無 package.json)→ notice,不阻擋(fail-open)
+cat >&2 << 'EOF'
+💡 DS 治理尚未就位(npm install 未完成或失敗)。請手動執行 → npm install(或 npm run sync-all)。
+   注:現在「不阻擋」你工作,只是提醒;治理本體就位後設計治理 hook 才會機械把關。
+EOF
+exit 0