@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

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

@@ -0,0 +1,86 @@
+#!/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
+source "$(dirname "$0")/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: hook integrity helper unavailable\n' >&2
+  exit 70
+}
+
+set -uo pipefail
+
+governance_hook_load_input
+governance_hook_require_commands grep sed sort
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'Tailwind wildcard tool extraction failed'
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'Tailwind wildcard path extraction failed'
+# 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
+# Provider runtime artifacts no longer live inside the checkout. Do not add provider-specific path
+# exemptions here: a future provider receives the same Tailwind protection without hook changes.
+# Only check files Tailwind v4 might scan
+if ! governance_hook_grep_q 'Tailwind wildcard scope matcher failed' "$FILE" -qE '\.(md|spec\.md|sh|ts|tsx|css|json)$'; then exit 0; fi
+
+CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'Tailwind wildcard content extraction failed'
+[ -z "$CONTENT" ] && exit 0
+
+# Escape clause
+if governance_hook_grep_q 'Tailwind wildcard escape matcher failed' "$CONTENT" -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)。
+governance_hook_grep_capture ANTI_PATTERNS_UNSORTED 'Tailwind wildcard matcher failed' \
+  "$CONTENT" -oE 'var\(--[a-z][a-z0-9-]*([\*/]+[a-z0-9-]*)+\)'
+ANTI_PATTERNS=$(sort -u <<< "$ANTI_PATTERNS_UNSORTED" 2>/dev/null) \
+  || governance_hook_integrity_fail 'Tailwind wildcard sorter failed'
+
+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,333 @@
+#!/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 shared governance Level 7 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
+#
+# 對齊:canonical codex-collab skill PostToolUse pattern + check_fork_user_plugin_install.sh detection pattern
+
+HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd -P)" || {
+  printf 'GOVERNANCE_INTEGRITY: deploy URL hook directory is unavailable\n' >&2
+  exit 70
+}
+source "$HOOK_DIR/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: canonical hook integrity helper is unavailable\n' >&2
+  exit 70
+}
+source "$HOOK_DIR/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+governance_hook_load_input
+governance_hook_require_commands grep git sed awk cut tail
+EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // ""') \
+  || governance_hook_integrity_fail 'deploy URL event could not be decoded'
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""') \
+  || governance_hook_integrity_fail 'deploy URL tool name could not be decoded'
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // ""') \
+  || governance_hook_integrity_fail 'deploy URL command could not be decoded'
+
+# 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 ! grep -qE "(^|[;&|(])[[:space:]]*${_ENVP}${_GITPRE}${_PUSHFLAGS}[[:space:]]+origin\b" <<<"$CMD"; then
+  exit 0
+fi
+
+ACTIVE_PROVIDER="${GOVERNANCE_PROVIDER:-${GOVERNANCE_SELF_PROVIDER:-}}"
+provider_contract_available() {
+  printf '%s' "$ACTIVE_PROVIDER" | grep -qE '^[a-z][a-z0-9-]*$' || return 1
+
+  # A product hook may trust adapter bytes only when they are byte-for-byte the provider record in
+  # the immutable manifest beside this shipped hook. An arbitrary direct-hook environment cannot
+  # invent a provider/adapter; the verified dispatcher is what selects and exports this exact row.
+  local hook_dir installed_manifest expected_adapter supplied_adapter
+  hook_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd -P)" || return 1
+  installed_manifest="$hook_dir/../manifest.json"
+  if [ -f "$installed_manifest" ] && [ ! -L "$installed_manifest" ]; then
+    [ -n "${GOVERNANCE_PROVIDER_ADAPTER_JSON:-}" ] || return 1
+    expected_adapter=$(jq -ce --arg provider "$ACTIVE_PROVIDER" '
+      .providerAdapters[$provider]
+      | select(
+      type == "object"
+      and .schemaVersion == 1
+      and (.capabilities | type == "object")
+      and (.normalization | type == "object")
+      and (.contextOutputTransport | type == "string" and length > 0)
+      and (.stopDecisionTransport | type == "string" and length > 0)
+      )
+    ' "$installed_manifest" 2>/dev/null) || return 1
+    supplied_adapter=$(printf '%s' "$GOVERNANCE_PROVIDER_ADAPTER_JSON" | jq -ce '.' 2>/dev/null) || return 1
+    [ "$supplied_adapter" = "$expected_adapter" ]
+    return
+  fi
+
+  # DS-author hooks and direct hermetic tests run through the canonical registry resolver. Load it
+  # only for a real push: unrelated file edits/Bash commands must remain a strict no-op even when a
+  # provider has no native hook surface or the optional deploy relay is unavailable.
+  source "$(dirname "$0")/lib/_provider_paths.sh" 2>/dev/null || return 1
+  governance_provider_string_field instructionEntry >/dev/null 2>&1
+}
+provider_contract_available || {
+  governance_hook_integrity_fail \
+    "deploy URL provider contract is unavailable:${ACTIVE_PROVIDER:-<missing>}"
+}
+
+# Skip if push --delete (branch cleanup, not deploy)
+if grep -qE 'push\s+origin\s+--delete' <<<"$CMD"; 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=$(grep -m 1 -oE 'git[[:space:]]+-C[[:space:]]+[^[:space:]]+' <<<"$CMD" | sed -n '1p' | 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=$(grep -m 1 -oE "(^|[;&|(])[[:space:]]*${_ENVP}${_GITPRE}[^;&|]*" <<<"$CMD" | sed -n '1p')
+BRANCH=$(grep -m 1 -oE 'origin[[:space:]]+[^[:space:]]+' <<<"$PUSH_SEG" | sed -n '1p' | 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" ] && ! grep -qE '^[A-Za-z0-9._/-]+$' <<<"$BRANCH"; 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 grep -qE '^v[0-9]' <<<"$BRANCH"; 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"
+  local body
+  body=$(curl -s --max-time 5 -L "$url" 2>/dev/null) || return 1
+  grep -qE "sb-manager|sb-addons|@storybook/core|storybook-static" <<<"$body"
+}
+
+# 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)
+
+  deploy_preferences_file() {
+    local candidate="${GOVERNANCE_DEPLOY_TARGETS_FILE:-}" config_home="${XDG_CONFIG_HOME:-}"
+    if [ -n "$candidate" ] && [ -f "$candidate" ] && [ ! -L "$candidate" ]; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+    [ -z "$config_home" ] && [ -n "${HOME:-}" ] && config_home="$HOME/.config"
+    if [ -n "$config_home" ]; then
+      candidate="$config_home/qijenchen-governance/deploy-targets.json"
+      if [ -f "$candidate" ] && [ ! -L "$candidate" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    fi
+    # Claude's old preference location is a compatibility input for Claude only. A Codex or
+    # future-provider invocation must be invariant to arbitrary bytes under ~/.claude.
+    if [ "$ACTIVE_PROVIDER" = "claude" ] && [ -n "${HOME:-}" ]; then
+      candidate="$HOME/.claude/local/deploy-targets.json"
+      if [ -f "$candidate" ] && [ ! -L "$candidate" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    fi
+    return 1
+  }
+
+  # v5 multi-candidate strategy(Netlify naming conventions in order of likelihood):
+  # 1. provider-neutral preference(explicit env > XDG config;Claude-only legacy fallback)— 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=""
+  DEPLOY_PREFERENCES="$(deploy_preferences_file 2>/dev/null || true)"
+  if [ -n "$DEPLOY_PREFERENCES" ]; then
+    USER_OVERRIDE=$(jq -r --arg key "$OWNER_REPO" '.[$key] // ""' "$DEPLOY_PREFERENCES" 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 創 ${XDG_CONFIG_HOME:-$HOME/.config}/qijenchen-governance/deploy-targets.json(也可設 GOVERNANCE_DEPLOY_TARGETS_FILE):\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|')
+      # 2026-07-17 bug 修:DNS 單標籤硬上限 63 字元。`<branch>--<site>` 超過 → 該子網域**無法存在**
+      # (curl 連 header 都收不到,非 404)。舊版直接拼不截斷 → 長 branch 名吐「物理上不可能」的網址,
+      # verify 失敗後還印該 URL 誤導 user。修:超長時截 branch + 誠實標示「branch 名太長,預覽不可靠」。
+      BRANCH_SLUG=$(echo "$BRANCH" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9-]/-/g; s/-+/-/g')
+      BUDGET=$(( 63 - ${#SITENAME} - 2 ))
+      TRUNCATED=0
+      if [ ${#BRANCH_SLUG} -gt $BUDGET ]; then
+        BRANCH_SLUG=$(echo "${BRANCH_SLUG:0:$BUDGET}" | sed -E 's/-+$//')
+        TRUNCATED=1
+      fi
+      CANDIDATE="https://${BRANCH_SLUG}--${SITENAME}.netlify.app"
+      if [ "$(verify_url "$CANDIDATE")" = "OK" ]; then
+        URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW(${BRANCH}): ${CANDIDATE}  ✅ verified 200\n"
+      elif [ $TRUNCATED -eq 1 ]; then
+        URLS_FOUND="${URLS_FOUND}⚠️ branch 名太長(『${BRANCH}』+ --${SITENAME} 超過 DNS 63 字元)→ Netlify 建不出預覽子網域;截斷版 ${CANDIDATE} 也未命中。可靠做法:縮短 branch 名(≤${BUDGET} 字元)重推,或合 main 後看正式站 https://${SITENAME}.netlify.app\n"
+      else
+        URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW 推導: ${CANDIDATE}  ⚠️ 未命中(preview 未啟 / build pending / 此 branch 未啟 branch-deploy — 查 Netlify Dashboard Deploys)\n"
+      fi
+    else
+      URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW(${BRANCH}) — sitename 未知;設 ${XDG_CONFIG_HOME:-$HOME/.config}/qijenchen-governance/deploy-targets.json(或 GOVERNANCE_DEPLOY_TARGETS_FILE)後 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」)。
+# 必須輸出 neutral governance context,再由 adapter 轉成 provider-native transport。
+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,不可省略)")
+CONTEXT=$(jq -nc --arg ctx "$MSG" \
+  '{governanceContext:{hookEventName:"PostToolUse",message:$ctx}}') \
+  || governance_hook_integrity_fail 'deploy URL governance context could not be encoded'
+printf '%s\n' "$CONTEXT"
+
+exit 0

package/ds-canonical/fork/hooks/lib/_hook_integrity.sh

@@ -0,0 +1,158 @@
+#!/bin/bash
+# Shared fail-closed input/tooling boundary for canonical hooks.
+# Policy violations remain hook-owned exit 2. Infrastructure, parser, and transport failures use
+# the reserved integrity marker and exit 70 so provider adapters cannot misreport them as policy.
+
+governance_hook_integrity_fail() {
+  printf 'GOVERNANCE_INTEGRITY: %s\n' "$1" >&2
+  exit 70
+}
+
+governance_hook_require_commands() {
+  local command_name
+  for command_name in "$@"; do
+    command -v "$command_name" >/dev/null 2>&1 \
+      || governance_hook_integrity_fail "required hook command is unavailable:${command_name}"
+  done
+}
+
+governance_hook_load_input() {
+  governance_hook_require_commands cat jq
+  if ! INPUT=$(cat); then
+    governance_hook_integrity_fail 'hook input could not be read'
+  fi
+  if ! printf '%s' "$INPUT" | jq -s -e '
+    length == 1
+    and (
+    .[0]
+    | type == "object"
+    and ([.. | strings | select(contains("\u0000"))] | length == 0)
+    and ((.tool_name? // "") | type == "string")
+    and ((.tool? // "") | type == "string")
+    and ((.hook_event_name? // "") | type == "string")
+    and ((.event? // "") | type == "string")
+    and ((.transcript_path? // "") | type == "string")
+    and ((.file_path? // "") | type == "string")
+    and ((.path? // "") | type == "string")
+    and (
+      .changed_paths? == null
+      or (.changed_paths | type == "array" and all(.[]; type == "string"))
+    )
+    and ((.tool_input? // {}) | type == "object")
+    and (
+      (.tool_input? // {}) as $tool
+      | [
+          $tool.file_path?,
+          $tool.path?,
+          $tool.notebook_path?,
+          $tool.content?,
+          $tool.new_string?,
+          $tool.old_string?,
+          $tool.command?,
+          $tool.prompt?,
+          $tool.script?,
+          $tool.skill?,
+          $tool.args?
+        ]
+      | all(. == null or type == "string")
+    )
+    and (
+      (.tool_input.changed_paths? == null)
+      or (.tool_input.changed_paths | type == "array" and all(.[]; type == "string"))
+    )
+    and (
+      (.tool_input.edits? == null)
+      or (
+        .tool_input.edits
+        | type == "array"
+        and all(.[];
+          type == "object"
+          and ([.file_path?, .path?, .content?, .new_string?]
+            | all(. == null or type == "string"))
+        )
+      )
+    )
+    )
+  ' >/dev/null 2>&1; then
+    governance_hook_integrity_fail 'invalid input envelope'
+  fi
+}
+
+governance_hook_project_file_path() {
+  governance_hook_require_commands python3
+  local raw_path="$1"
+  local project_root="${GOVERNANCE_PROJECT_DIR:-$(pwd)}"
+  python3 - "$project_root" "$raw_path" <<'PY'
+import os
+import sys
+
+root_input = os.path.abspath(sys.argv[1])
+raw = sys.argv[2]
+if not os.path.isdir(root_input):
+    raise SystemExit(2)
+root = os.path.realpath(root_input)
+target = os.path.abspath(raw if os.path.isabs(raw) else os.path.join(root, raw))
+real_target = os.path.realpath(target)
+try:
+    if os.path.commonpath([root, real_target]) != root:
+        raise ValueError("outside project")
+except ValueError:
+    raise SystemExit(2)
+
+# Preserve the caller's spelling when it is lexically below the configured root. This permits
+# macOS's /var -> /private/var system alias above the project while still detecting every symlink
+# at or below the project root. A physically equivalent alternate spelling falls back to real paths.
+relative = os.path.relpath(target, root_input)
+if relative == os.pardir or relative.startswith(os.pardir + os.sep):
+    traversal_root = root
+    relative = os.path.relpath(real_target, root)
+else:
+    traversal_root = root_input
+
+cursor = traversal_root
+if os.path.islink(cursor):
+    raise SystemExit(2)
+if relative != ".":
+    for segment in relative.split(os.sep):
+        cursor = os.path.join(cursor, segment)
+        if not os.path.lexists(cursor):
+            break
+        if os.path.islink(cursor):
+            raise SystemExit(2)
+print(target)
+PY
+}
+
+governance_hook_grep_q() {
+  local failure_message="$1"
+  local text="$2"
+  shift 2
+  local grep_rc
+  if grep "$@" <<< "$text" >/dev/null 2>&1; then
+    grep_rc=0
+  else
+    grep_rc=$?
+  fi
+  case "$grep_rc" in
+    0|1) return "$grep_rc" ;;
+    *) governance_hook_integrity_fail "$failure_message" ;;
+  esac
+}
+
+governance_hook_grep_capture() {
+  local output_name="$1"
+  local failure_message="$2"
+  local text="$3"
+  shift 3
+  local grep_output grep_rc
+  if grep_output=$(grep "$@" <<< "$text" 2>/dev/null); then
+    grep_rc=0
+  else
+    grep_rc=$?
+  fi
+  case "$grep_rc" in
+    0|1) ;;
+    *) governance_hook_integrity_fail "$failure_message" ;;
+  esac
+  printf -v "$output_name" '%s' "$grep_output"
+}