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

package/ds-canonical/hooks/check_ds_anchor_preflight.sh

@@ -0,0 +1,219 @@
+#!/bin/bash
+# check_ds_anchor_preflight.sh — M29 mechanical enforcement(2026-05-26 backfill per user verbatim
+# 「該程式化的都沒程式化,導致你他媽那麼容易便宜」+「未來其他人 fork 用其他元件也偏移」)。
+#
+# Purpose: PreToolUse Edit/Write/MultiEdit 偵測 production tsx wrap DS primitive
+# (`<Sidebar>` / `<AppShell>` / `<DataTable>` / `<Dialog>` / `<Field>` 等)
+# 沒同 turn 跑過 Grep / Read DS canonical baseline → P0 BLOCKER(exit 2,2026-07-07 治理進化方向 2 升級;
+# escape GOVERNANCE_BYPASS_DS_ANCHOR=1 audit-logged),propose 前必出 3-column owner table。
+#
+# Scope:同 check_substantive_edit_approval_preflight.sh extended scope
+#   - packages/design-system/src/**.tsx (DS internal)
+#   - apps/**.tsx (consumer fork-user code) ← M29 gap absorption(2026-05-26)
+#   - node_modules/@qijenchen/design-system/** (禁改)
+#
+# Excluded: *.stories.tsx (story_invariants R7/R8 already cover) / *.test.tsx / *.spec.md.
+#
+# Why mechanical:M29 anchor preflight 在 meta-patterns.md 喊很久,5 個文件 reference but file 0,
+# 結果 2026-05-26 product-workspace App.tsx mock-drift 沒被攔 → user 抓「肌肉沒長出來」。
+# 本 hook 將「propose / write 視覺結構 前必 grep DS spec.md / canonical story」從 mindset 升 mechanical。
+#
+# Detection:scan transcript 過去 ~30 turns:
+#   (a) 有 Grep / Read tool call hit `packages/design-system/src/**/*.spec.md` OR
+#       `**/*.stories.tsx`(canonical baseline) → PASS
+#   (b) 無 → soft BLOCKER inject context 提醒 grep canonical 出 3-column owner table。
+#
+# 對齊 meta-patterns.md M29 「視覺/結構 propose 前必 grep DS spec.md 找 owner SSOT(M29)— 出 3-column 表」+
+# `packages/design-system/ds-canonical/rules/self-verify.md` Pre-edit phase
+# 「M29 3-column owner table」。
+
+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 basename find grep paste sort tail
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'DS anchor tool extraction failed'
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'DS anchor path extraction failed'
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'DS anchor transcript extraction failed'
+EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'DS anchor event extraction failed'
+
+[ "$EVENT" != "PreToolUse" ] && exit 0
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+
+# Scope:DS production code + consumer fork-user app code(不含 stories / spec / test)
+case "$FILE_PATH" in
+  */packages/design-system/src/*.tsx) ;;
+  */apps/*.tsx) ;;
+  */node_modules/@qijenchen/design-system/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+case "$FILE_PATH" in
+  *.stories.tsx|*.test.tsx|*.spec.md|*.spec.ts) exit 0 ;;
+esac
+
+# Extract content being written/edited
+NEW_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'DS anchor content extraction failed'
+
+# DS primitive 名單(wrap 這些就觸發 anchor preflight)
+# 2026-07-16 dim 57 修 stale hardcode(含已改名 NameCard→ProfileCard、缺 InlineEdit 等 34 現役元件):
+# 元件名改「機械生成」— 由 components/ dir 動態 ls 派生(hook 每 fire 跑一次 find,成本 <10ms 可接受),
+# 新增/改名元件自動同步,不再靠人手維護清單。
+# 非-dir primitive(patterns/ export + sub-component:MenuItem/Item* slots/TabsList/ChromeHeader/
+# Surface*/OverlaySurface/ActionBar)無 dir 可派生 → 維護小清單於 _PATTERN_PRIMITIVES。
+_COMPONENTS_DIR=""
+for _root in "${GOVERNANCE_PROJECT_DIR:-}" "$(pwd)"; do
+  if [ -n "$_root" ] && [ -d "$_root/packages/design-system/src/components" ]; then
+    _COMPONENTS_DIR="$_root/packages/design-system/src/components"
+    break
+  fi
+done
+if [ -n "$_COMPONENTS_DIR" ]; then
+  if [ -L "$_COMPONENTS_DIR" ] || [ ! -r "$_COMPONENTS_DIR" ]; then
+    governance_hook_integrity_fail 'DS components registry directory is unavailable or unsafe'
+  fi
+  _COMP_NAMES=$(find "$_COMPONENTS_DIR" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; 2>/dev/null | sort | paste -sd'|' -) \
+    || governance_hook_integrity_fail 'DS component registry discovery failed'
+fi
+# 靜態 fallback(consumer fork repo 無 packages/design-system/src/ → 用 snapshot;
+# 與 DS repo components/ dir 同步,新增元件必補 — snapshot 2026-07-16,63 元件)
+if [ -z "${_COMP_NAMES:-}" ]; then
+  _COMP_NAMES='Accordion|Alert|AppShell|AspectRatio|Avatar|Badge|Breadcrumb|BulkActionBar|Button|Calendar|Carousel|Chart|Checkbox|Chip|CircularProgress|Coachmark|Combobox|Command|DataTable|DateGrid|DatePicker|DescriptionList|Dialog|DropdownMenu|Empty|Field|FieldControlGroup|FileItem|FileUpload|FileViewer|HoverCard|InlineEdit|Input|LinkInput|Menu|Notice|NumberInput|OverflowIndicator|Pagination|PeoplePicker|Popover|ProfileCard|ProgressBar|RadioGroup|Rating|ScrollArea|SegmentedControl|Select|SelectionControl|SelectMenu|Separator|Sheet|Sidebar|Skeleton|Slider|Steps|Switch|Tabs|Tag|Textarea|TimePicker|Toast|Tooltip|TreeView'
+fi
+_PATTERN_PRIMITIVES='MenuItem|ItemAvatar|ItemLabel|ItemIcon|TabsList|TabsTrigger|ChromeHeader|SurfaceHeader|SurfaceBody|SurfaceFooter|OverlaySurface|ActionBar'
+DS_PRIMITIVES_RE="<(${_COMP_NAMES}|${_PATTERN_PRIMITIVES})\b"
+
+# 沒 wrap DS primitive → 檢「純手刻」洞(2026-07-07 治理進化方向 3 洞 b:原本此分支直接放行,
+# 「該用 primitive 卻整個手刻」反而抓不到 — 內部盤點 file:line 證據見 planning/2026-07-07-governance-evolution-roadmap.md)
+if ! governance_hook_grep_q 'DS primitive registry matcher failed' "$NEW_CONTENT" -qE "$DS_PRIMITIVES_RE"; then
+  # 視覺簽名:row/浮層/chrome 手刻特徵(flex row + padding/border/rounded/shadow 組合)
+  governance_hook_grep_capture HANDCRAFT_SIG 'DS handcraft signature matcher failed' \
+    "$NEW_CONTENT" -cE 'className="[^"]*\b(flex|absolute|fixed)\b[^"]*\b(border|rounded|shadow|px-|py-|gap-)'
+  HANDCRAFT_SIG=${HANDCRAFT_SIG:-0}
+  if [ "$HANDCRAFT_SIG" -ge 3 ] \
+    && ! governance_hook_grep_q 'DS handcraft escape matcher failed' "$NEW_CONTENT" -q '@handcraft-ok:'; then
+    MESSAGE=$(cat <<'EOF_HC'
+⚠️ [第一期 WARN] M23(d)/mindset #2 純手刻嫌疑:本段 production tsx 有 ≥3 處視覺結構 className
+   但零 DS primitive 消費。先查 patterns/(item-anatomy / overlay-surface / ChromeHeader /
+   horizontal-overflow)有無現成 primitive;真需自建 → 行內 `@handcraft-ok: <rationale>` +
+   spec「自建 + 理由」宣告。誤殺率驗證期後升 P0(roadmap 方向 3)。
+EOF_HC
+    )
+    printf '{"governanceContext":{"hookEventName":"PreToolUse","message":%s}}\n' "$(printf '%s' "$MESSAGE" | jq -Rs .)"
+  fi
+  exit 0
+fi
+
+# A committed marker is deterministic evidence that every provider and CI can verify without a
+# provider-private transcript. Native transcript inspection remains useful acceleration, but a null
+# transcript (valid in Codex and some Claude surfaces) must never turn the hard rule into a no-op.
+if governance_hook_grep_q 'DS story-baseline marker matcher failed' "$NEW_CONTENT" \
+  -qE '@story-baseline:[[:space:]]*[^[:space:]]+'; then
+  exit 0
+fi
+
+if [ "${GOVERNANCE_STATIC_REPLAY:-0}" = "1" ] || [ -z "$TRANSCRIPT_PATH" ]; then
+  cat >&2 <<'EOF_STATIC'
+🚨 M29 DS Anchor Preflight — deterministic evidence missing
+DS primitive production code must contain `@story-baseline: <canonical-path>#<StoryName>` when no
+provider transcript is available. Transcript-dependent advice is not counted as CI enforcement.
+EOF_STATIC
+  exit 2
+fi
+
+if [ -L "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ] || [ ! -r "$TRANSCRIPT_PATH" ]; then
+  governance_hook_integrity_fail 'supplied DS anchor transcript is unavailable or unsafe'
+fi
+
+# Scan last ~30 turns(~600 lines transcript)— 找 Grep/Read 對 DS spec.md / canonical story 的 trace
+RECENT_TRANSCRIPT=$(tail -600 "$TRANSCRIPT_PATH" 2>/dev/null) \
+  || governance_hook_integrity_fail 'DS anchor transcript read failed'
+if ! printf '%s' "$RECENT_TRANSCRIPT" | jq -s -e 'all(.[]; type == "object")' >/dev/null 2>&1; then
+  governance_hook_integrity_fail 'DS anchor transcript is malformed'
+fi
+
+# Pass condition(a):有 Grep tool call pattern hit spec.md / stories.tsx
+CANONICAL_TRACE=$(printf '%s' "$RECENT_TRANSCRIPT" | \
+  jq -r 'select(type == "object" and .message.content != null) |
+    .message.content // empty |
+    if type == "array" then
+      (.[]? | select(.type == "tool_use") |
+        select(.name == "Grep" or .name == "Read" or .name == "Glob") |
+        .input | tostring)
+    else empty
+    end' 2>/dev/null) || governance_hook_integrity_fail 'DS anchor transcript query failed'
+HAS_CANONICAL_READ=$(printf '%s' "$CANONICAL_TRACE" | \
+  grep -cE 'packages/design-system/src/.*\.(spec\.md|stories\.tsx)|stories\.tsx#' 2>/dev/null)
+_GREP_RC=$?
+if [ "$_GREP_RC" -gt 1 ]; then
+  governance_hook_integrity_fail 'DS anchor canonical evidence matcher failed'
+fi
+HAS_CANONICAL_READ=${HAS_CANONICAL_READ:-0}
+
+# Pass condition(b):AI 已 written 3-column owner table OR cite `@story-baseline:` marker
+HAS_3COL_OR_MARKER=$(printf '%s' "$RECENT_TRANSCRIPT" | \
+  grep -cE '@story-baseline:|owner spec|canonical sentence|3-column' 2>/dev/null)
+_GREP_RC=$?
+if [ "$_GREP_RC" -gt 1 ]; then
+  governance_hook_integrity_fail 'DS anchor marker matcher failed'
+fi
+HAS_3COL_OR_MARKER=${HAS_3COL_OR_MARKER:-0}
+
+# Pass: 有任一 canonical read OR 3-column marker → silent
+if [ "$HAS_CANONICAL_READ" -gt 0 ] || [ "$HAS_3COL_OR_MARKER" -gt 0 ]; then
+  exit 0
+fi
+
+# Override env var(audit-logged)
+if [ "${GOVERNANCE_BYPASS_DS_ANCHOR:-0}" = "1" ]; then
+  if STATE_DIR="$(governance_runtime_state_dir 2>/dev/null)"; then
+    mkdir -p "$STATE_DIR" 2>/dev/null
+    jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg file "$FILE_PATH" --arg tool "$TOOL" \
+      '{ts:$ts,event:"ds-anchor-bypass",file:$file,tool:$tool}' >> "$STATE_DIR/governance-bypass.jsonl" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+REL_PATH=${FILE_PATH#*/my-project/}
+
+# Soft BLOCKER(對齊 check_substantive_edit_approval_preflight.sh hybrid pattern)
+cat >&2 <<EOF
+🚨 M29 DS Anchor Preflight — visual/structural edit 偵測
+
+📁 File: $REL_PATH
+🔧 Tool: $TOOL
+🧩 偵測到 DS primitive 在 new content:wrap pattern
+
+⚠️ 過去 ~30 turns 無 Grep/Read 對 \`packages/design-system/src/**/spec.md\` 或
+   \`*.stories.tsx\` baseline 的 trace,且未見 \`@story-baseline:\` marker 或 3-column owner table。
+
+→ 這違反 M29 anchor preflight invariant + story-rules.md「Production-grade composition fidelity」。
+→ 對 fork-user 後果:憑記憶寫 simplified mock(像 2026-05-26 App.tsx SidebarTrigger 漏 / collapsible 漏 / startIcon 漏)。
+
+修法 — 2 選 1(對齊 check_substantive_edit_approval_preflight.sh hybrid):
+  (a) 先 Grep / Read DS canonical:
+        - \`packages/design-system/src/<Component>/*.spec.md\`(找 owner SSOT)
+        - \`packages/design-system/src/<Component>/*.stories.tsx\`(找完整佈局 baseline)
+      然後 inline 寫 3-column owner table(\`owner spec\` / \`canonical sentence\` / \`conflicting code\`)
+      或加 \`// @story-baseline: <path>#<StoryName>\` marker 在檔頭。
+  (b) Bypass:\`GOVERNANCE_BYPASS_DS_ANCHOR=1\` env var(audit-logged in governance-bypass.jsonl)
+      僅當你**真的**已 Read canonical 但 transcript scan miss 時用,not 規則繞道。
+
+對應 canonical:
+  - \`packages/design-system/ds-canonical/rules/meta-patterns.md\` M29
+  - \`packages/design-system/ds-canonical/rules/self-verify.md\` Pre-edit phase
+  - \`packages/design-system/ds-canonical/references/ssot-index.md\` Step 0.1 high-risk interface owner mapping
+EOF
+
+# P0 BLOCKER(2026-07-07 治理進化方向 2:對齊 user 2026-05-27「SSOT canonical 必 P0 禁 soft」
+# doctrine;bypass env GOVERNANCE_BYPASS_DS_ANCHOR=1 已備且 audit-logged,升級不增誤殺)。
+exit 2

package/ds-canonical/hooks/check_dynamic_tailwind_class.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# check_dynamic_tailwind_class — 攔「動態 Tailwind utility class」脆弱寫法(2026-07-09 root-cause 防線)
+#
+# 病根(user 以 GitHub Pages 對比抓出的 DataTable row-height regression):
+#   `h-table-row-${size}` 這種「class 名本身含 ${...} 插值」的模板字串,Tailwind **靜態掃描看不到**
+#   完整 class → 只能靠專案別處剛好有 literal(如 spec.md)被 content-detection 掃到才生成。
+#   一旦那個脆弱 literal 消失 / 掃描樹變動(本 case 是 .gitignore 加 reference/)→ 整組 `.h-table-row-*`
+#   規則不生成 → 元件靜默塌成內容高度(non-editable 33px / editable 44px 而非 token 40px)+ 選取控件走位。
+#   tsc / build 全綠、CI 不紅 = 沉默陷阱。
+#
+# 正解(對齊 fieldWrapperStyles 的 `h-field-md` cva-literal 慣例):class 名必須是**完整 literal**;
+#   要隨變數選 class 用 literal map:`{ sm:'h-table-row-sm', md:'h-table-row-md', lg:'h-table-row-lg' }[size]`。
+#
+# Scope:production tsx/ts(packages/design-system/src + apps)。CSS var 插值(`var(--x-${y})` / arbitrary
+#   value `[...${...}]`)不在此列(那是值,不是 class 名;且 CSS var 真存在,fail-loud 不同機制)。
+# Escape:`// @dynamic-tailwind-allow: <理由>` per-line。
+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 -euo pipefail
+governance_hook_load_input
+governance_hook_require_commands grep sed
+fp=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""') \
+  || governance_hook_integrity_fail 'dynamic Tailwind path extraction failed'
+content=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""') \
+  || governance_hook_integrity_fail 'dynamic Tailwind content extraction failed'
+[ -z "$fp" ] && exit 0
+case "$fp" in
+  *packages/design-system/src/*.tsx|*packages/design-system/src/*.ts|*apps/*/src/*.tsx|*apps/*/src/*.ts) ;;
+  *) exit 0 ;;
+esac
+[ -z "$content" ] && exit 0
+
+# 抓:backtick 字串內、Tailwind 尺寸/間距 utility 前綴 + 之後含 `${` 讓 class 名不完整。
+#   e.g. `h-table-row-${size}` / `h-${x}` / `min-h-${y}` / `w-col-${i}` / `gap-${g}` / `py-${p}`
+# 排除:`[` 之後(arbitrary value,如 `h-[var(--x-${y})]`)、`var(` 內。
+governance_hook_grep_capture hits_candidates 'dynamic Tailwind matcher failed' "$content" -nE \
+  '`[^`]*\b(h|w|min-h|max-h|min-w|max-w|size|gap|space-[xy]|p[xytblr]?|m[xytblr]?)-[a-z0-9-]*\$\{'
+governance_hook_grep_capture hits_unescaped 'dynamic Tailwind escape filter failed' \
+  "$hits_candidates" -vE '@dynamic-tailwind-allow'
+governance_hook_grep_capture hits 'dynamic Tailwind arbitrary-value filter failed' \
+  "$hits_unescaped" -vE '\[[^]]*\$\{|var\('
+
+if [ -n "$hits" ]; then
+  echo "🚨 BLOCKER: 動態 Tailwind class(class 名含 \${...} 插值)— Tailwind 靜態掃描看不到 → 靜默不生成規則" >&2
+  echo "  file: $fp" >&2
+  echo "$hits" | sed 's/^/    /' >&2
+  echo "" >&2
+  echo "  病根:2026-07-09 DataTable row-height regression(h-table-row-\${size} → utility 消失 → row 塌 + 選取走位)" >&2
+  echo "  正解:改 literal map,class 名寫完整字面 —" >&2
+  echo "    const cls = { sm: 'h-table-row-sm', md: 'h-table-row-md', lg: 'h-table-row-lg' }[size]" >&2
+  echo "  逃生:確實非 class(CSS var 值等)→ 行尾加 // @dynamic-tailwind-allow: <理由>" >&2
+  exit 2
+fi
+exit 0

package/ds-canonical/hooks/check_escape_marker_abuse.sh

@@ -0,0 +1,213 @@
+#!/bin/bash
+# check_escape_marker_abuse.sh — P0 BLOCKER (codify warning)
+#
+# 偵測 consumer code(.tsx/.stories.tsx)濫用 escape markers 跳 SSOT enforcement.
+# Per user 2026-05-27 verbatim「不亂加 escape markers — 加就跳 enforcement」.
+#
+# Escape markers exist for真 exceptions(per-line documented rationale)。但 fork
+# user 若大量加 escape markers (eg. ≥3 同一 file) = 違反 escape philosophy → BLOCK.
+#
+# Detected markers:
+#   - @ds-misuse-allow:    (check_consumer_ds_primitive_misuse.sh escape)
+#   - @story-baseline-allow:(check_consumer_story_baseline.sh escape)
+#   - @consumer-catalog-allow:(check_consumer_no_ds_catalog.sh escape)
+#   - @overlay-open-skip:  (check_overlay_open_focus_escape_probe.sh escape)
+#   - @template-customized (template canonical sync opt-out)
+#   - @layout-space-magic-ok:(check_layout_space_magic_numbers.sh escape)
+#   - @story-trait-allow:  (story-baseline / catalog escape)
+#   - @story-trait-rationale:(check_story_invariants.sh R3 scoped trait exception)
+#   - @story-split-rationale:(check_story_invariants.sh R2 escape)
+#   - @story-name-canonical-allow:(check_story_invariants.sh R4 escape)
+#   - @propose-cite-skip:  (check_propose_cite_required.sh escape)
+#   - @anatomy-exempt:     (story-rules escape)
+#   - @anatomy-exempt-next:(story-rules per-line escape)
+#   - @benchmark-unverified: (M22 cite)
+#   - @benchmark-citation-allow / @benchmark-unverified-blanket (M22 file-level cite escapes)
+#
+# Threshold:≥3 distinct markers OR ≥5 total occurrences in same file → BLOCK
+# Forces fork user to either (a) fix root cause OR (b) refactor properly OR
+# (c) explicitly cite reason in commit message via env override.
+#
+# 2026-05-31 升級(per 3-hardening-items 調查,折進本 hook 不新增檔):
+#   1. Justification gate:escape marker 後空理由(@x-allow: 後純空白 / bare @benchmark-unverified)
+#      = 靜默繞過 SSOT → BLOCK(consumer + DS source 都跑)。對齊 ESLint require-description / Google NOLINT。
+#   2. Scope 擴 DS source(packages/design-system/src tsx/ts):原整段 skip 讓 DS 內 marker 不受 justification
+#      約束;現 DS 跑 justification gate 但跳過 ≥3/≥5 數量 gate(DS 有大量 legit exception 避免誤殺）。
+#   3. MARKER_RE 廣化(M7/M34 broad):@<x>-allow 家族用廣義 regex 自動納管,免 enum drift。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$(dirname "$0")/lib/_provider_paths.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: escape-marker project resolver unavailable\n' >&2
+  exit 70
+}
+source "$(dirname "$0")/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: hook integrity helper unavailable\n' >&2
+  exit 70
+}
+source "$(dirname "$0")/lib/_micro_geometry.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: escape-marker micro-geometry classifier unavailable\n' >&2
+  exit 70
+}
+
+set -uo pipefail
+
+governance_hook_load_input
+governance_hook_require_commands grep sed sort tr wc python3
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'escape-marker 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 'escape-marker path extraction failed'
+# Scope 分流(2026-05-31 加 DS source — 原整段 skip 讓 DS 內 143 個 marker 不受任何 justification 約束):
+#   IS_CONSUMER=apps/consumer tsx/ts → 跑 justification gate + 數量 gate(≥3/≥5)
+#   IS_DS=packages/design-system/src tsx/ts → 只跑 justification gate(DS 有大量 legit exception,不套數量上限避免誤殺)
+IS_CONSUMER=0; IS_DS=0
+if governance_hook_grep_q 'escape-marker consumer scope matcher failed' "$FILE" -qE '/(apps|consumer)/.*\.(tsx|ts)$'; then IS_CONSUMER=1; fi
+if governance_hook_grep_q 'escape-marker DS scope matcher failed' "$FILE" -qE 'packages/design-system/src/.*\.(tsx|ts)$'; then IS_DS=1; fi
+if [ "$IS_CONSUMER" -eq 0 ] && [ "$IS_DS" -eq 0 ]; then exit 0; fi
+
+CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'escape-marker content extraction failed'
+[ -z "$CONTENT" ] && exit 0
+
+# Global escape — meta-skip(env override OR explicit comment)
+if [ "${GOVERNANCE_BYPASS_ESCAPE_MARKER_AUDIT:-0}" = "1" ]; then exit 0; fi
+
+# ── Justification gate(2026-05-31,折進本 hook;核心 real gap)──────────────────
+# Escape marker 必帶 per-line rationale。空理由 = 靜默繞過 SSOT enforcement。
+#   (a) @<x>-allow: 後純空白到行尾(有 marker 有冒號但無理由)
+#   (b) bare @benchmark-unverified 後純空白到行尾(非 -blanket / 非 ": 理由" / 非後接說明文字)
+# 對齊 ESLint eslint-comments/require-description + Google NOLINT(category) 必帶說明。
+governance_hook_grep_capture EMPTY_RATIONALE 'escape-marker rationale matcher failed' "$CONTENT" -nE \
+  '@[a-z][a-z-]+-allow:[[:space:]]*$|@benchmark-unverified[[:space:]]*$'
+if [ -n "$EMPTY_RATIONALE" ]; then
+  cat >&2 << EOF
+🚨 ESCAPE-MARKER-NO-RATIONALE BLOCKER(P0,2026-05-31 folded into check_escape_marker_abuse)
+
+  File $FILE — escape marker 後無 rationale(空理由 = 靜默繞過 SSOT):
+$(echo "$EMPTY_RATIONALE" | sed 's/^/    /')
+
+  修法:marker 冒號後寫具體理由,eg.
+    // @ds-misuse-allow: Notion-style inline edit canonical(Field 在 cell 內編輯)
+    /* @benchmark-unverified: AG Grid pixel-snapshot 共識,待補 URL cite */
+
+  Escape directive 世界級共識(ESLint require-description / Google NOLINT)必帶 rationale。
+EOF
+  exit 2
+fi
+
+# ── Sanctioned portal 檔 allowlist(2026-06-11 R2 held-item #10)──────────────
+# AllDsComponents.stories.tsx 是 documented DS proxy portal(檔頭 @anatomy-exempt +
+# @consumer-catalog-allow per 2026-05-27 M31 codex synthesis + @layout-space-magic-ok
+# dev-artifact 豁免)— 3 個 marker 各帶 rationale 是它的 sanctioned 常態,數量 gate
+# (≥3 distinct)對它必誤擋 = hook-vs-hook 張力。只豁免數量 gate;justification gate
+# (空理由 BLOCK)上方已跑完照常生效,真保護不削弱。
+IS_SANCTIONED_PORTAL=0
+case "$FILE" in
+  *apps/*/src/AllDsComponents.stories.tsx) IS_SANCTIONED_PORTAL=1 ;;
+esac
+
+# ── 數量 gate(≥3 distinct / ≥5 total）— 僅 consumer(DS source 有大量 legit exception,只走上方 justification gate）──
+# 2026-06-11 R2 Phase B(codex b3 抓縫):portal 無限豁免會放走「第 4、5 個新增 marker」——
+# 改為提高閾值(portal ≥6 / 一般 ≥3)保留 ceiling,justification gate 不變。
+if [ "$IS_SANCTIONED_PORTAL" -eq 1 ]; then DISTINCT_CAP=6; else DISTINCT_CAP=3; fi
+if [ "$IS_CONSUMER" -eq 1 ]; then
+  # 2026-05-31 廣化 marker family 仍在 shared classifier 裡閉包納管。layout-space marker
+  # 若附著在 utility-registry 可機械證明的 canonical micro geometry,已沒有繞過
+  # enforcement,因此不消耗 escape ceiling;一般 gap-1/2 或其他 marker 仍照常計數。
+  MARKERS_UNSORTED=$(governance_countable_escape_markers "$CONTENT") \
+    || governance_hook_integrity_fail 'escape-marker structural classification failed'
+  MARKERS_FOUND=$(sort -u <<< "$MARKERS_UNSORTED" 2>/dev/null) \
+    || governance_hook_integrity_fail 'escape-marker sorter failed'
+  # 2026-05-30 fix(test-surfaced):空 MARKERS_FOUND 時 grep -c 印 "0" 已 exit 1,原 `|| echo 0`
+  # 會再 append 一個 "0" → "0\n0" → 下方 `[ -ge "$DISTINCT_CAP" ]` integer-expression error。改 `|| true` 不重複。
+  governance_hook_grep_capture DISTINCT_COUNT 'escape-marker distinct counter failed' "$MARKERS_FOUND" -c .
+  [ -z "$DISTINCT_COUNT" ] && DISTINCT_COUNT=0
+  if [ -n "$MARKERS_UNSORTED" ]; then
+    governance_hook_grep_capture TOTAL_COUNT 'escape-marker occurrence counter failed' "$MARKERS_UNSORTED" -c .
+  else
+    TOTAL_COUNT=0
+  fi
+
+  # Threshold: ≥3 distinct types OR ≥5 total
+  if [ "$DISTINCT_COUNT" -ge "$DISTINCT_CAP" ] || [ "$TOTAL_COUNT" -ge 5 ]; then
+    cat >&2 << EOF
+🚨 ESCAPE-MARKER-ABUSE BLOCKER(P0,user 2026-05-27 verbatim「不亂加 escape markers — 加就跳 enforcement」)
+
+  File $FILE:
+    Distinct escape markers: $DISTINCT_COUNT(threshold ≥$DISTINCT_CAP)
+    Total occurrences: $TOTAL_COUNT(threshold ≥5)
+
+  Markers detected:
+$(echo "$MARKERS_FOUND" | sed 's/^/    /')
+
+  Escape markers 設計為「rare per-line documented exception」,不該 routine 加。
+  Fork user file 大量加 marker = 違反 SSOT 哲學 — 應該:
+
+  修法 3 選 1:
+    (a) **重構 code** 走 DS canonical pattern(消除根因,不繞)
+    (b) **拆 file**:1 個 escape 對應 1 個 specific case,分散到不同 file
+    (c) **Override env**(極罕見,documented in commit msg):
+        GOVERNANCE_BYPASS_ESCAPE_MARKER_AUDIT=1 git commit -m "<rationale>"
+
+  per check_consumer_*.sh hooks SSOT — escape 是 emergency exit,不是 daily tool.
+EOF
+    exit 2
+  fi
+
+  # ── Repo 級累計 ratchet(2026-07-08 WM 戰役 R4)──────────────────────────────
+  # per-file gate(≥3 distinct/≥5 total)可被「每檔 1-2 個、散多檔」繞過 → repo 級 ceiling。
+  # Ratchet 精神(Polaris stylelint migrator):存量 ≥ cap 後只擋「本次 edit 再新增 marker」,
+  # 不因存量 brick 無關 edit(本次內容無 marker → 直接放行)。
+  if [ -n "$MARKERS_UNSORTED" ]; then
+    governance_hook_grep_capture EDIT_ADDS_MARKER 'escape-marker edit counter failed' "$MARKERS_UNSORTED" -c .
+  else
+    EDIT_ADDS_MARKER=0
+  fi
+  if [ "${EDIT_ADDS_MARKER:-0}" -gt 0 ]; then
+    PROJECT_ROOT=$(governance_project_root 2>/dev/null) \
+      || governance_hook_integrity_fail 'escape-marker project root could not be resolved'
+    APPS_ROOT="$PROJECT_ROOT/apps"
+    REPO_CAP=10
+    if [ -L "$APPS_ROOT" ] || [ ! -d "$APPS_ROOT" ] || [ ! -r "$APPS_ROOT" ]; then
+      governance_hook_integrity_fail 'escape-marker repository scan root is unavailable or unsafe'
+    fi
+    REPO_MARKERS=$(governance_countable_repository_escape_markers "$APPS_ROOT") \
+      || governance_hook_integrity_fail 'escape-marker repository scan failed'
+    if [ -n "$REPO_MARKERS" ]; then
+      governance_hook_grep_capture REPO_TOTAL 'escape-marker repository counter failed' "$REPO_MARKERS" -c .
+    else
+      REPO_TOTAL=0
+    fi
+      # Exhaustive CI replays committed full files, not a prospective edit fragment. In that mode
+      # the current snapshot is valid at the ceiling and fails only when it already exceeds it.
+      # Native write-time mode keeps the ratchet semantics:once at cap, any marker-bearing edit
+      # is blocked so the count cannot grow.
+      if [ "${GOVERNANCE_STATIC_REPLAY:-0}" = "1" ]; then
+        [ "${REPO_TOTAL:-0}" -le "$REPO_CAP" ] && exit 0
+      elif [ "${REPO_TOTAL:-0}" -lt "$REPO_CAP" ]; then
+        exit 0
+      fi
+      if [ "${REPO_TOTAL:-0}" -gt "$REPO_CAP" ] || [ "${GOVERNANCE_STATIC_REPLAY:-0}" != "1" ]; then
+        cat >&2 << EOF
+🚨 ESCAPE-MARKER-REPO-RATCHET BLOCKER(P0,2026-07-08 WM 戰役 R4)
+
+  apps/** 全 repo escape marker 存量已 $REPO_TOTAL 個(ceiling $REPO_CAP),本次 edit 又要新增 $EDIT_ADDS_MARKER 個。
+  每檔 1-2 個散多檔 = 繞 per-file gate 的同型濫用 — repo 級 ratchet 攔。
+
+  修法 2 選 1:
+    (a) 先清既有 escape 的根因(重構走 DS canonical),存量 < $REPO_CAP 後再加真必要的
+    (b) Override env(極罕見,commit msg 必記 rationale):
+        GOVERNANCE_BYPASS_ESCAPE_MARKER_AUDIT=1
+EOF
+        exit 2
+      fi
+  fi
+fi
+
+exit 0

package/ds-canonical/hooks/check_field_controls_contracts.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# check_field_controls_contracts.sh — Stream C shared contracts(a)(b)(c) consolidated guardrail
+# check_field_controls_contracts.sh — Stream C shared contracts(a)(b)(c)(d) consolidated guardrail
 #
 # 2026-05-13 prune consolidation(per knowledge-prune Phase 2 P1):3 hook 合 1:
 #   - 原 check_field_placeholder_vocabulary.sh — contract (b)
@@ -23,12 +23,13 @@ case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
 [ ! -f "$FILE_PATH" ] && exit 0
 
 VIOLATIONS=""
+FILE_HEAD3=$(sed -n '1,3p' "$FILE_PATH")
 
 # ── Contract (b) Placeholder vocabulary ───────────────────────────────────────
 # Scope: 所有 packages/design-system/src/components/*.tsx
 case "$FILE_PATH" in
   */packages/design-system/src/components/*.tsx)
-    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@placeholder-vocabulary-allow:'; then
+    if ! grep -qE '//[[:space:]]*@placeholder-vocabulary-allow:' <<<"$FILE_HEAD3"; then
       HITS=$(grep -nE 'emptyPlaceholder=\{(emptyText|searchEmpty|noResults|notFound)' "$FILE_PATH" 2>/dev/null)
       if [ -n "$HITS" ]; then
         VIOLATIONS="${VIOLATIONS}
@@ -46,18 +47,19 @@ esac
 # Scope:Combobox / Select / PeoplePicker only
 case "$FILE_PATH" in
   */packages/design-system/src/components/Combobox/*.tsx|*/packages/design-system/src/components/Select/*.tsx|*/packages/design-system/src/components/PeoplePicker/*.tsx)
-    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@renderer-symmetry-allow:'; then
-      DEFINES_RENDERER=$(grep -cE '(tagRenderer|selectedItemRenderer)\?:\s*\(' "$FILE_PATH" 2>/dev/null || echo 0)
+    if ! grep -qE '//[[:space:]]*@renderer-symmetry-allow:' <<<"$FILE_HEAD3"; then
+      DEFINES_RENDERER=$(grep -cE '(tagRenderer|selectedItemRenderer)\?:\s*\(' "$FILE_PATH" 2>/dev/null)
       DEFINES_RENDERER=${DEFINES_RENDERER:-0}
       if [ "$DEFINES_RENDERER" -gt 0 ]; then
-        EDIT_HITS=$(grep -cE 'tagRenderer\(.*\)|selectedItemRenderer\(.*\)' "$FILE_PATH" 2>/dev/null || echo 0)
+        EDIT_HITS=$(grep -cE 'tagRenderer\(.*\)|selectedItemRenderer\(.*\)' "$FILE_PATH" 2>/dev/null)
         EDIT_HITS=${EDIT_HITS:-0}
         DISPLAY_LINES=$(grep -nE "mode\s*=*\s*'display'|resolvedMode\s*==*\s*'display'" "$FILE_PATH" 2>/dev/null | cut -d: -f1)
         if [ "$EDIT_HITS" -gt 0 ] && [ -n "$DISPLAY_LINES" ]; then
           HAS_RENDERER_IN_DISPLAY=0
           for LN in $DISPLAY_LINES; do
             END=$((LN + 60))
-            if awk -v s="$LN" -v e="$END" 'NR>=s && NR<=e' "$FILE_PATH" | grep -qE 'tagRenderer|selectedItemRenderer'; then
+            DISPLAY_WINDOW=$(awk -v s="$LN" -v e="$END" 'NR>=s && NR<=e' "$FILE_PATH")
+            if grep -qE 'tagRenderer|selectedItemRenderer' <<<"$DISPLAY_WINDOW"; then
               HAS_RENDERER_IN_DISPLAY=1
               break
             fi
@@ -80,7 +82,7 @@ esac
 # Scope:Combobox / Select / PeoplePicker only
 case "$FILE_PATH" in
   */packages/design-system/src/components/Combobox/*.tsx|*/packages/design-system/src/components/PeoplePicker/*.tsx|*/packages/design-system/src/components/Select/*.tsx)
-    if ! head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@cell-metric-escape-allow:'; then
+    if ! grep -qE '//[[:space:]]*@cell-metric-escape-allow:' <<<"$FILE_HEAD3"; then
       HARDCODE_HITS=$(grep -nE 'tagAreaPaddingLeftPx=\{[0-9]+\}' "$FILE_PATH" 2>/dev/null)
       COND_NO_SURFACE=$(grep -nE 'tagAreaPaddingLeftPx=\{[^}]*\?[^}]*[0-9]+[^}]*\}' "$FILE_PATH" 2>/dev/null | grep -v "surface")
       WARN=""
@@ -102,9 +104,36 @@ ${FILE_PATH}${WARN}
     ;;
 esac
 
+# ── Contract (d) field-px token(2026-06-27;round-2 對抗驗證 2026-06-27 補洞)──────
+# Scope:消費 --field-px 的 field controls(form 水平內距 SSOT)。12px 已 tokenize → production
+#       code 禁 hardcode `0.75rem`(inline override)或裸 `px-3`/`pr-3`(uiSize.css:29
+#       「取代散落的 px-3 / inline 0.75rem」canonical;M34 hook 廣度對齊 spec wording)。
+#       PeoplePicker 補進 scope(round-1 漏:其 form-context inject `!px-[var(--field-px)]`)。
+# 豁免(避免 false-positive):
+#   - `*.stories.tsx`(anatomy/principles 內含合法 token 對照標註 + demo 容器 px-3 layout,非 padding hardcode)
+#   - comment 行(`//` `*` `/*` 開頭 — migration 註解可合法 reference 舊 px-3/0.75rem 形式)
+#   - 已 tokenize 的 `px-[var(--field-px)]`
+case "$FILE_PATH" in
+  *.stories.tsx) ;;
+  */packages/design-system/src/components/Select/*.tsx|*/packages/design-system/src/components/Combobox/*.tsx|*/packages/design-system/src/components/Input/*.tsx|*/packages/design-system/src/components/NumberInput/*.tsx|*/packages/design-system/src/components/Textarea/*.tsx|*/packages/design-system/src/components/DatePicker/*.tsx|*/packages/design-system/src/components/TimePicker/*.tsx|*/packages/design-system/src/components/LinkInput/*.tsx|*/packages/design-system/src/components/PeoplePicker/*.tsx|*/packages/design-system/src/components/Field/*.tsx)
+    if ! grep -qE '//[[:space:]]*@field-px-escape-allow:' <<<"$FILE_HEAD3"; then
+      FIELDPX_HITS=$(grep -nE "0\.75rem|(^|[^a-zA-Z0-9-])!?(px|pr)-3([^0-9.]|$)" "$FILE_PATH" 2>/dev/null \
+        | grep -vE '^[0-9]+:[[:space:]]*(//|\*|/\*)' \
+        | grep -vE 'px-\[var')
+      if [ -n "$FIELDPX_HITS" ]; then
+        VIOLATIONS="${VIOLATIONS}
+[contract (d) field-px]:
+${FIELDPX_HITS}
+  → field 水平內距 12px 已 tokenize 為 --field-px(field-controls.spec.md「右側元素」canonical + tokens/uiSize/uiSize.css)。production 禁 hardcode 0.75rem / 裸 px-3,改 \`paddingRight: 'var(--field-px)'\` / \`px-[var(--field-px)]\`。
+  Allow:檔首加 \`// @field-px-escape-allow: <reason>\`。"
+      fi
+    fi
+    ;;
+esac
+
 if [ -n "$VIOLATIONS" ]; then
   CTX="⚠️ Field controls shared contracts violation(consolidated check):${VIOLATIONS}"
   jq -n --arg ctx "$CTX" '{
-    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+    governanceContext: { hookEventName: "PostToolUse", message: $ctx }
   }'
 fi