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

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

@@ -0,0 +1,400 @@
+#!/bin/bash
+# check_story_invariants.sh — SHIP_REWRITTEN fork override(consumer 版,2026-07-08 WM 戰役 R4)
+#
+# WHY REWRITE(非 SHIP_AS_IS / 非 DROP):
+#   DS-author 原版 10 條 rule 多數 scope 在 DS src stories(anatomy 6-canonical / trait category /
+#   title canonical 等 DS-author 撰寫紀律),fork 消費端不適用;但 provider-neutral product
+#   instruction 的 consume-before-inventing/nearest-canonical 原則需要
+#   「Registry SSOT story-baseline-registry.json + hook check_story_invariants.sh R8 + R9 機械強制」
+#   — 原版整支 DROP = doc-vs-corpus drift(對 fork 承諾了防線、corpus 卻沒 ship,紙老虎)。
+#   本 override 只 ship fork 真需要的兩條(WM 2026-07-08 實證 drift class):
+#     R8 story_archetype_registry — 讀 corpus 內 registry antiPatterns,攔 simplified-mock
+#        (wrap Sidebar/DataTable/ChromeHeader 卻手刻 span/div 取代 primitive 結構)
+#     R9 hand_craft_overlay_header — 手刻浮層 / chrome header 簽名(px-loose + border-b
+#        border-divider 同 className;零誤判簽名,DS-wide 量測 anchor 2026-06-04 upload-manager)
+#   Scope 擴到 apps/**/*.tsx:fork 手刻 drift 主戰場在產品 code,非只 stories(WM detail modal 實證)。
+#   Escape 與 DS-author 版同源:@story-baseline-allow: <reason>(檔頭 10 行內或本次片段)。
+#
+# Registry 路徑:只接受 runner 驗證後的 $GOVERNANCE_CORPUS_ROOT/references；
+# 不從 hook 位置、cwd 或 consumer node_modules 猜測，避免 mutable fallback 成為第二權威。
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd -P)" || {
+  printf 'GOVERNANCE_INTEGRITY: consumer story invariant hook root unavailable\n' >&2
+  exit 70
+}
+source "$SCRIPT_DIR/_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$SCRIPT_DIR/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: consumer story invariant integrity helper unavailable\n' >&2
+  exit 70
+}
+source "$SCRIPT_DIR/lib/_provider_paths.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: consumer story invariant corpus resolver unavailable\n' >&2
+  exit 70
+}
+
+set -uo pipefail
+
+_HOOK_CONTEXT_EVENT="PreToolUse"
+_HOOK_OUTPUT_CAPTURE=$(mktemp "${TMPDIR:-/tmp}/consumer-story-invariants.XXXXXX") || {
+  printf 'GOVERNANCE_INTEGRITY: consumer story invariant output capture unavailable\n' >&2
+  exit 70
+}
+exec 3>&1 4>&2
+exec >"$_HOOK_OUTPUT_CAPTURE" 2>&1
+
+_finalize_hook_output() {
+  _hook_rc=$?
+  trap - EXIT
+  exec 1>&3 2>&4
+  _hook_output=$(cat "$_HOOK_OUTPUT_CAPTURE" 2>/dev/null || true)
+  rm -f "$_HOOK_OUTPUT_CAPTURE" 2>/dev/null || true
+
+  case "$_hook_rc" in
+    0)
+      [ -z "$_hook_output" ] && exit 0
+      if ! jq -cn \
+        --arg event "$_HOOK_CONTEXT_EVENT" \
+        --arg message "$_hook_output" \
+        '{governanceContext:{hookEventName:$event,message:$message}}'; then
+        printf 'GOVERNANCE_INTEGRITY: consumer story invariant warning envelope encoding failed\n' >&2
+        exit 70
+      fi
+      exit 0
+      ;;
+    2)
+      case "$_hook_output" in
+        *GOVERNANCE_INTEGRITY:*)
+          printf '%s\n' "$_hook_output" >&2
+          exit 70
+          ;;
+      esac
+      if [ -n "$_hook_output" ]; then
+        printf '%s\n' "$_hook_output" >&2
+      else
+        printf 'consumer story invariant hook blocked without diagnostic\n' >&2
+      fi
+      exit 2
+      ;;
+    70)
+      if [ -n "$_hook_output" ]; then
+        printf '%s\n' "$_hook_output" >&2
+      else
+        printf 'GOVERNANCE_INTEGRITY: consumer story invariant failed without diagnostic\n' >&2
+      fi
+      exit 70
+      ;;
+    *)
+      printf 'GOVERNANCE_INTEGRITY: consumer story invariant undefined exit code %s\n' "$_hook_rc" >&2
+      [ -n "$_hook_output" ] && printf '%s\n' "$_hook_output" >&2
+      exit 70
+      ;;
+  esac
+}
+trap _finalize_hook_output EXIT
+
+governance_hook_load_input
+governance_hook_require_commands awk grep jq python3 sed
+TOOL=$(jq -r '.tool_name // ""' <<< "$INPUT" 2>/dev/null) \
+  || governance_hook_integrity_fail 'consumer story invariant tool extraction failed'
+FILE_PATH=$(jq -r '.tool_input.file_path // ""' <<< "$INPUT" 2>/dev/null) \
+  || governance_hook_integrity_fail 'consumer story invariant path extraction failed'
+EVENT=$(jq -r '.hook_event_name // ""' <<< "$INPUT" 2>/dev/null) \
+  || governance_hook_integrity_fail 'consumer story invariant event extraction failed'
+
+case "$EVENT" in
+  PostToolUse) _HOOK_CONTEXT_EVENT="PostToolUse" ;;
+  *) _HOOK_CONTEXT_EVENT="PreToolUse" ;;
+esac
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+[ "$EVENT" = "PostToolUse" ] && exit 0
+
+# Scope:fork 產品 code(apps/**/*.tsx)+ 任何 stories.tsx;DS 內部 / node_modules 不管
+case "$FILE_PATH" in
+  *node_modules/*|*packages/design-system/*) exit 0 ;;
+  *.stories.tsx) ;;
+  apps/*.tsx|*/apps/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+SAFE_FILE=$(governance_hook_project_file_path "$FILE_PATH" 2>/dev/null) \
+  || governance_hook_integrity_fail 'consumer story target escapes the project or crosses a symlink'
+if [ -e "$SAFE_FILE" ] || [ -L "$SAFE_FILE" ]; then
+  if [ -L "$SAFE_FILE" ] || [ ! -f "$SAFE_FILE" ] || [ ! -r "$SAFE_FILE" ]; then
+    governance_hook_integrity_fail 'consumer story target is unavailable or unsafe'
+  fi
+fi
+
+# proposed-text-v1 consumes only the runner-validated full after-image. Direct
+# event-v1 probes retain a strict typed fallback for compatibility, but raw
+# fragments and compatibility aliases never outrank a trusted proposed state.
+NEW_CONTENT=""
+case "${GOVERNANCE_WRITE_STATE_TRUST:-}" in
+  runner-v1)
+    if ! jq -e '
+      .tool_input.governance_write_state as $state
+      | ($state | type == "object")
+        and ($state.schemaVersion == 1)
+        and ($state.path | type == "string" and length > 0)
+        and (
+          ($state.kind == "text" and ($state.content | type == "string"))
+          or ($state.kind == "deleted" and ($state | has("content") | not))
+        )
+    ' <<< "$INPUT" >/dev/null 2>&1; then
+      governance_hook_integrity_fail 'consumer story invariant trusted proposed write state is missing or malformed'
+    fi
+    STATE_PATH=$(jq -r '.tool_input.governance_write_state.path' <<< "$INPUT" 2>/dev/null) \
+      || governance_hook_integrity_fail 'consumer story invariant proposed state path extraction failed'
+    STATE_KIND=$(jq -r '.tool_input.governance_write_state.kind' <<< "$INPUT" 2>/dev/null) \
+      || governance_hook_integrity_fail 'consumer story invariant proposed state kind extraction failed'
+    if [[ "$FILE_PATH" != "$STATE_PATH" && "$FILE_PATH" != */"$STATE_PATH" ]]; then
+      governance_hook_integrity_fail 'consumer story invariant proposed state does not match the hook target'
+    fi
+    [ "$STATE_KIND" = "deleted" ] && exit 0
+    NEW_CONTENT=$(jq -r '.tool_input.governance_write_state.content' <<< "$INPUT" 2>/dev/null) \
+      || governance_hook_integrity_fail 'consumer story invariant proposed state content extraction failed'
+    ;;
+  ""|unavailable)
+    # Select exactly one valid string surface. Provider-neutral event-v1
+    # envelopes may carry aliases together; concatenating them multiplies the
+    # same full-file payload. A present null alias is not valid text and must
+    # not shadow another valid compatibility field.
+    NEW_CONTENT=$(jq -r '
+      .tool_name as $tool
+      | .tool_input as $input
+      | def valid_edits:
+          (($input.edits | type) == "array")
+          and all($input.edits[]?; (.new_string | type) == "string");
+      if $tool == "Write" and ($input.content | type) == "string" then
+        $input.content
+      elif $tool == "Edit" and ($input.new_string | type) == "string" then
+        $input.new_string
+      elif $tool == "MultiEdit" and valid_edits then
+        ([$input.edits[] | .new_string] | join("\n"))
+      elif ($input.new_string | type) == "string" then
+        $input.new_string
+      elif ($input.content | type) == "string" then
+        $input.content
+      elif valid_edits then
+        ([$input.edits[] | .new_string] | join("\n"))
+      else
+        error("no valid mutation text")
+      end
+    ' <<< "$INPUT" 2>/dev/null) \
+      || governance_hook_integrity_fail 'consumer story edit payload extraction failed'
+    ;;
+  *)
+    governance_hook_integrity_fail 'consumer story invariant proposed state trust marker is unsupported'
+    ;;
+esac
+governance_hook_grep_q \
+  'consumer story non-whitespace matcher failed' \
+  "$NEW_CONTENT" -q '[^[:space:]]' \
+  || exit 0
+
+# Escape(檔頭 10 行 — 本次片段 or 磁碟上既有檔頭)。Capture the
+# bounded prefix first; producer→head→grep pipelines can SIGPIPE under pipefail.
+CONTENT_HEAD=$(sed -n '1,10p;10q' <<< "$NEW_CONTENT") \
+  || governance_hook_integrity_fail 'consumer story content header read failed'
+if governance_hook_grep_q \
+  'consumer story content allow-marker matcher failed' \
+  "$CONTENT_HEAD" -qE '@story-baseline-allow:'; then
+  exit 0
+fi
+if [ "${GOVERNANCE_WRITE_STATE_TRUST:-}" != "runner-v1" ] && [ -f "$SAFE_FILE" ]; then
+  DISK_HEAD=$(sed -n '1,10p;10q' "$SAFE_FILE" 2>/dev/null) \
+    || governance_hook_integrity_fail 'consumer story target header read failed'
+  if governance_hook_grep_q \
+    'consumer story target allow-marker matcher failed' \
+    "$DISK_HEAD" -qE '@story-baseline-allow:'; then
+    exit 0
+  fi
+fi
+
+WORST=0
+record_worst() {
+  local level="$1"
+  [ "$level" -gt "$WORST" ] && WORST="$level"
+}
+
+# ── Registry 定位(只讀 runner-authenticated immutable corpus) ──
+CORPUS_ROOT=$(governance_corpus_root 2>/dev/null) \
+  || governance_hook_integrity_fail 'R8 consumer story baseline corpus root could not be resolved'
+REGISTRY_CANDIDATE="$CORPUS_ROOT/references/story-baseline-registry.json"
+REGISTRY=$(python3 - "$CORPUS_ROOT" "$REGISTRY_CANDIDATE" <<'PY'
+import os
+import sys
+
+root = os.path.realpath(os.path.abspath(sys.argv[1]))
+target = os.path.abspath(sys.argv[2])
+try:
+    if os.path.commonpath([root, target]) != root:
+        raise ValueError("outside corpus")
+except ValueError:
+    raise SystemExit(2)
+relative = os.path.relpath(target, root)
+cursor = root
+if os.path.islink(cursor):
+    raise SystemExit(2)
+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_integrity_fail 'R8 consumer story baseline registry escapes the corpus or crosses a symlink'
+if [ -L "$REGISTRY" ] || [ ! -f "$REGISTRY" ] || [ ! -r "$REGISTRY" ]; then
+  governance_hook_integrity_fail "R8 consumer story baseline registry is unavailable or unsafe:${REGISTRY}"
+fi
+if ! jq -e --arg owner "packages/design-system/ds-canonical/references/story-baseline-registry.json" '
+  type == "object"
+  and .schemaVersion == 1
+  and ._meta.owner == $owner
+  and (._meta.provider_view_policy | type == "string" and length > 0)
+  and (.components | type == "object")
+  and (.components | keys | sort) == ["ChromeHeader", "DataTable", "Sidebar"]
+  and (
+    . as $root
+    | ["Sidebar", "DataTable", "ChromeHeader"] as $required
+    | all($required[];
+        . as $component
+        | ($root.components[$component] | type == "object")
+        and ($root.components[$component].antiPatterns | type == "array" and length > 0)
+        and all($root.components[$component].antiPatterns[];
+          type == "object"
+          and (.severity == "block" or .severity == "warn")
+          and (
+            .regex
+            | type == "string"
+              and length > 0
+              and (explode | all(. >= 32 and . != 127))
+          )
+          and (
+            .unlessRegex? == null
+            or (
+              .unlessRegex
+              | type == "string"
+                and (explode | all(. >= 32 and . != 127))
+            )
+          )
+        )
+      )
+  )
+' "$REGISTRY" >/dev/null 2>&1; then
+  governance_hook_integrity_fail "R8 consumer story baseline registry is invalid:${REGISTRY}"
+fi
+
+# Flatten each payload once in linear time. Registry EREs deliberately use
+# [[:space:]] and bounded .{N} spans across originally separate JSX lines.
+CONTENT_FLAT=$(awk '
+  BEGIN { first=1 }
+  {
+    if (!first) printf " "
+    printf "%s", $0
+    first=0
+  }
+' <<< "$NEW_CONTENT") \
+  || governance_hook_integrity_fail 'R8 consumer story content flatten failed'
+
+# ─────────────────────────────────────────────────────────────────────────────
+# R8 — story_archetype_registry(registry antiPatterns 攔 simplified-mock)
+# ─────────────────────────────────────────────────────────────────────────────
+for COMP in Sidebar DataTable ChromeHeader; do
+  if ! governance_hook_grep_q \
+    "R8 consumer component matcher failed:${COMP}" \
+    "$NEW_CONTENT" -qE "<${COMP}\\b"; then
+    continue
+  fi
+
+  # 每條三行一組:severity / regex / unlessRegex。Schema forbids control
+  # characters, so one registry value cannot corrupt the record framing.
+  if ! PATTERNS=$(jq -er --arg c "$COMP" '
+    .components[$c].antiPatterns[]
+    | .severity, .regex, (.unlessRegex // "")
+  ' "$REGISTRY" 2>/dev/null); then
+    governance_hook_integrity_fail "R8 consumer registry query failed for component:${COMP}"
+  fi
+  [ -n "$PATTERNS" ] \
+    || governance_hook_integrity_fail "R8 consumer registry query returned no patterns:${COMP}"
+
+  while IFS= read -r SEV \
+    && IFS= read -r PATTERN \
+    && { IFS= read -r UNLESS || true; }; do
+    [ -n "$PATTERN" ] \
+      || governance_hook_integrity_fail "R8 consumer registry returned an empty regex:${COMP}"
+
+    grep -qE "$PATTERN" <<< "x" 2>/dev/null
+    REGEX_RC=$?
+    if [ "$REGEX_RC" -gt 1 ]; then
+      governance_hook_integrity_fail "R8 consumer registry regex is not executable:${PATTERN}"
+    fi
+    if [ -n "$UNLESS" ]; then
+      grep -qE "$UNLESS" <<< "x" 2>/dev/null
+      REGEX_RC=$?
+      if [ "$REGEX_RC" -gt 1 ]; then
+        governance_hook_integrity_fail "R8 consumer registry unlessRegex is not executable:${UNLESS}"
+      fi
+    fi
+
+    grep -qE "$PATTERN" <<< "$CONTENT_FLAT" 2>/dev/null
+    REGEX_RC=$?
+    if [ "$REGEX_RC" -gt 1 ]; then
+      governance_hook_integrity_fail "R8 consumer registry matcher failed for component:${COMP}"
+    elif [ "$REGEX_RC" -eq 0 ]; then
+      if [ -n "$UNLESS" ]; then
+        grep -qE "$UNLESS" <<< "$CONTENT_FLAT" 2>/dev/null
+        REGEX_RC=$?
+        if [ "$REGEX_RC" -gt 1 ]; then
+          governance_hook_integrity_fail "R8 consumer registry unless matcher failed for component:${COMP}"
+        elif [ "$REGEX_RC" -eq 0 ]; then
+          continue
+        fi
+      fi
+      {
+        echo "⚠️  R8 story_archetype_registry violation(severity: $SEV):"
+        echo "   $FILE_PATH wrap <$COMP> matches anti-pattern:"
+        echo "   regex: $PATTERN"
+        echo ""
+        echo "   修法:Read DS baseline story + helpers,抄 production archetype 結構,"
+        echo "   不憑印象手刻 simplified mock(<SidebarHeader><span> / 手刻 filter Button 等)。"
+        echo "   Baseline registry:node_modules/@qijenchen/design-system/ds-canonical/references/story-baseline-registry.json"
+        echo "   Canonical:product AGENTS 的 consume-before-inventing；nearest same-purpose canonical wins。"
+        echo "   豁免:檔頭加 // @story-baseline-allow: <reason>(audit-logged)。"
+      } >&2
+      [ "$SEV" = "block" ] && record_worst 2
+    fi
+  done <<< "$PATTERNS"
+done
+
+# ─────────────────────────────────────────────────────────────────────────────
+# R9 — hand_craft_overlay_header(零誤判簽名:px-loose + border-b border-divider 同 className)
+# ─────────────────────────────────────────────────────────────────────────────
+# Drop pure comment lines and flatten in one awk pass. Do not strip inline //
+# because doing so mutilates URLs and changes executable JSX.
+FLAT9=$(awk '
+  /^[[:space:]]*(\/\/|\*|\/\*|\{\/\*)/ { next }
+  {
+    if (!first) printf " "
+    printf "%s", $0
+    first=0
+  }
+' <<< "$NEW_CONTENT") \
+  || governance_hook_integrity_fail 'R9 consumer story content flatten failed'
+if governance_hook_grep_q \
+  'R9 consumer hand-craft matcher failed' \
+  "$FLAT9" -qE '<div[^>]*px-\[var\(--layout-space-loose\)\][^">]*border-b[[:space:]]+border-divider|<div[^>]*border-b[[:space:]]+border-divider[^">]*px-\[var\(--layout-space-loose\)\]'; then
+  {
+    echo "❌ R9 hand-craft overlay / chrome header:${FILE_PATH}"
+    echo "   偵測到 <div ... px-[var(--layout-space-loose)] ... border-b border-divider> = 手刻浮層 / chrome header。"
+    echo "   必消費 DS primitive:<SurfaceHeader>(patterns/overlay-surface)/ <PopoverHeader> / <DialogHeader>;"
+    echo "   面板殼用 Popover 同款 chrome token(rounded-lg border-border bg-surface-raised elevation-200)。"
+    echo "   理由:px-loose + divider border 的 header chrome 是 overlay-surface SSOT;手刻 = drift"
+    echo "   (anchor 2026-06-04 upload-manager 手刻面板 py-2≠py-tight / 殼 token 全偏,user 抓)。"
+    echo "   Spec:node_modules/@qijenchen/design-system/src/patterns/overlay-surface/overlay-surface.spec.md"
+    echo "   豁免:檔頭加 // @story-baseline-allow: <reason>。"
+  } >&2
+  record_worst 2
+fi
+
+exit "$WORST"

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

@@ -0,0 +1,241 @@
+#!/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
+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 awk cat grep head sed
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'tabs-body tool extraction failed'
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.notebook_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'tabs-body path extraction failed'
+
+# Scope:DS source + apps,.tsx only(INVERSE of check_layout_space_magic_numbers.sh 的 DS-src skip)
+if ! governance_hook_grep_q 'tabs-body extension matcher failed' "$FILE" -qE '\.tsx$'; then exit 0; fi
+if ! governance_hook_grep_q 'tabs-body scope matcher failed' "$FILE" -qE '(packages/design-system/src/|/apps/|(^|/)apps/)'; then exit 0; fi
+
+# PostToolUse:file 已寫入磁碟,讀「完整檔」做 containment 分析(避免 hunk-only partial-edit 盲區 —
+# 部分 edit 的 new_string 可能只含 TabsContent 行不含外層 DialogBody,window 分析會漏)。
+FILE=$(governance_hook_project_file_path "$FILE" 2>/dev/null) \
+  || governance_hook_integrity_fail 'tabs-body target escapes the project or crosses a symlink'
+if [ -L "$FILE" ] || [ ! -f "$FILE" ] || [ ! -r "$FILE" ]; then
+  governance_hook_integrity_fail 'tabs-body target is unavailable or unsafe'
+fi
+CONTENT=$(cat "$FILE" 2>/dev/null) || governance_hook_integrity_fail 'tabs-body target read failed'
+[ -z "$CONTENT" ] && exit 0
+
+# ── Check 3(2026-07-08 WM 戰役 R4:root 偵測,不只 symptom)──
+# WM 實證:app 把 TabsList 塞 DialogBody + `!pt-0` hack 對抗 primitive,TabsContent 加了 mt-0
+# 就繞過 Check 2 —— 但 root 錯誤是「沒用 DialogHeader tabsSlot canonical」(雙線 + 底線內縮 +
+# spacing owner 自組)。偵測兩個 root 簽名(任一 → BLOCK 指路 tabsSlot):
+#   (a) DialogBody/SheetBody/SurfaceBody className 含 `!pt-0`(important 對抗 primitive 的 pt owner)
+#   (b) <TabsList 出現在含 DialogBody 的同段 new content 且無 tabsSlot 字樣
+governance_hook_grep_capture ROOT_SIG_A_CANDIDATES 'tabs-body root signature matcher failed' \
+  "$CONTENT" -nE '(DialogBody|SheetBody|SurfaceBody)[^>]*className=[^>]*!pt-0'
+governance_hook_grep_capture ROOT_SIG_A 'tabs-body root signature escape filter failed' \
+  "$ROOT_SIG_A_CANDIDATES" -v '@tabs-content-gap-ok:'
+ROOT_SIG_B=""
+if governance_hook_grep_q 'tabs-body TabsList matcher failed' "$CONTENT" -q '<TabsList' \
+  && governance_hook_grep_q 'tabs-body chrome-body matcher failed' "$CONTENT" -qE '<(DialogBody|SheetBody|SurfaceBody)\b' \
+  && ! governance_hook_grep_q 'tabs-body tabsSlot matcher failed' "$CONTENT" -q 'tabsSlot' \
+  && ! governance_hook_grep_q 'tabs-body root escape matcher failed' "$CONTENT" -q '@tabs-content-gap-ok:'; then
+  ROOT_SIG_B="found"
+fi
+if [ -n "$ROOT_SIG_A" ] || [ -n "$ROOT_SIG_B" ]; then
+  cat >&2 << 'EOF_C3'
+🚨 TABS-IN-BODY ROOT BLOCKER(P0,2026-07-08 WM 戰役 — 攔 root 非 symptom)
+
+  偵測到「TabsList 手塞 chrome body / body 用 !pt-0 hack」簽名 —— 這是「沒用 header tabsSlot
+  canonical」的 root 錯誤(後果:header 與 TabsList 雙底線、tabs 底線被 body padding 內縮不滿寬、
+  spacing owner 鏈自組)。WM ProjectSettings/TypeSettings 錨例。
+
+  ── 正解 ──
+  <Tabs> wrap → <DialogHeader tabsSlot={<TabsList/>}> → <DialogBody><TabsContent className="mt-0">
+  照 dialog.stories.tsx#WithTabsInHeader 逐字結構(header-canonical.spec.md Rule W2)。
+  Escape:`// @tabs-content-gap-ok: <rationale>`(例:tabs 本來就不屬 header 的內容分頁場景)
+EOF_C3
+  exit 2
+fi
+
+
+# ══ 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:'
+governance_hook_grep_capture GAP_CANDIDATES 'tabs-body fixed-gap matcher failed' "$CONTENT" -nE \
+  '<(DialogBody|SheetBody|PopoverBody|SurfaceBody)[^>]*gap-[4-9]([^0-9]|$)'
+governance_hook_grep_capture GAP_HITS 'tabs-body tokenized-gap filter failed' \
+  "$GAP_CANDIDATES" -v 'gap-\[var'
+GAP_UNJUSTIFIED=""
+if [ -n "$GAP_HITS" ]; then
+  while IFS= read -r hit; do
+    [ -z "$hit" ] && continue
+    ln="${hit%%:*}"
+    cur="${hit#*:}"
+    if governance_hook_grep_q 'tabs-body gap escape matcher failed' "$cur" -qF "$GAP_MARKER"; then continue; fi
+    if [ "$ln" -gt 1 ] 2>/dev/null; then
+      prev=$(sed -n "$((ln-1))p" <<< "$CONTENT" 2>/dev/null) \
+        || governance_hook_integrity_fail 'tabs-body gap preceding-line extraction failed'
+      if governance_hook_grep_q 'tabs-body preceding gap escape matcher failed' "$prev" -qF "$GAP_MARKER" \
+        && governance_hook_grep_q 'tabs-body preceding gap comment matcher failed' "$prev" -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:
+$(printf '%b' "$GAP_UNJUSTIFIED" | sed 's/^/    /' | awk 'NR <= 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 ! governance_hook_grep_q 'tabs-body containment gate matcher failed' "$CONTENT" -qE '<(DialogBody|SheetBody|SurfaceBody)[ />]'; then exit 0; fi
+if ! governance_hook_grep_q 'tabs-content gate matcher failed' "$CONTENT" -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
+  }
+') || governance_hook_integrity_fail 'tabs-body containment parser failed'
+
+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=$(sed -n "${ln}p" <<< "$CONTENT" 2>/dev/null) \
+    || governance_hook_integrity_fail 'tabs-body candidate-line extraction failed'
+  if governance_hook_grep_q 'tabs-body same-line escape matcher failed' "$cur" -qF "$ESCAPE_MARKER"; then continue; fi
+  if [ "$ln" -gt 1 ] 2>/dev/null; then
+    prev=$(sed -n "$((ln-1))p" <<< "$CONTENT" 2>/dev/null) \
+      || governance_hook_integrity_fail 'tabs-body preceding-line extraction failed'
+    if governance_hook_grep_q 'tabs-body preceding escape matcher failed' "$prev" -qF "$ESCAPE_MARKER" \
+      && governance_hook_grep_q 'tabs-body preceding comment matcher failed' "$prev" -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:
+$(printf '%b' "$UNJUSTIFIED" | sed 's/^/    /' | awk 'NR <= 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