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

package/ds-canonical/hooks/check_field_family_invariants.sh

@@ -1,30 +1,95 @@
 #!/bin/bash
 # Field family unified invariant hook(2026-05-08 cluster A consolidation)
 #
-# Merges 4 PreToolUse hooks(原各檔已 retire,合併入此)— 共 4 條 sub-rules:
+# Merges PreToolUse hooks(原各檔已 retire,合併入此)— 共 6 條 sub-rules:
 #   A.1 naked row-mode propagation(原 check_naked_row_mode_propagation,P0 BLOCKER)
 #   A.2 FieldControlGroup wrapper direct child(原 check_field_control_group_direct_child,P1 WARN)
 #   A.3 Field state ring SSOT(原 check_field_state_token_consume 3 sub-rules,P0 BLOCKER)
-#   A.4 disabled placeholder color(原 check_disabled_placeholder_color,P1 stderr only)
+#   A.4 disabled placeholder color(原 check_disabled_placeholder_color,P1 context)
+#   A.5 _Group child fieldCtx.id 隔離(2026-05-31 折入,M4 AR34 regression detector,P0 BLOCKER)
+#   A.6 空值顯示 SSOT(2026-07-08 user 拍板半形 hyphen,P0 BLOCKER)
 #
 # Why merge:皆 Field 家族 invariant,共用 INPUT parsing + Edit/Write filter pattern,
 #   分散在 4 個 hook 是「散裝 SSOT」(M17 + Anthropic ≤ 15 hook best practice 違反)。
 #
-# Exit code precedence:BLOCK(2)> WARN(1)> INFO(0)。每 rule 可獨立觸發,worst 勝。
+# Output precedence:BLOCK(2,stderr)> WARN(0,單一 governanceContext)> silent(0)。
 #
 # Per-rule allowlist(各自獨立):
 #   A.1: `// @naked-row-mode-allow: <reason>`
 #   A.2: `// @fcg-wrapper-allow: <reason>` 或檔頭
 #   A.3: `// @field-state-ring-allow: <reason>`
 #   A.4: `// @disabled-color-allow: <reason>`
+#   A.5: `// @group-fieldctx-allow: <reason>`
+#   A.6: `// @empty-display-allow: <reason>`
 
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
 
 set -uo pipefail
 
-INPUT=$(cat)
-TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+_HOOK_CONTEXT_EVENT="PreToolUse"
+_HOOK_OUTPUT_CAPTURE=$(mktemp "${TMPDIR:-/tmp}/check-field-family-invariants.XXXXXX") || {
+  printf 'GOVERNANCE_INTEGRITY: field family invariants 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: field family invariants warning envelope encoding failed\n' >&2
+        exit 70
+      fi
+      exit 0
+      ;;
+    2)
+      if grep -q 'GOVERNANCE_INTEGRITY:' <<<"$_hook_output"; then
+        printf '%s\n' "$_hook_output" >&2
+        exit 70
+      elif [ -n "$_hook_output" ]; then
+        printf '%s\n' "$_hook_output" >&2
+      else
+        printf 'field family invariants 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: field family invariants failed without diagnostic\n' >&2
+      fi
+      exit 70
+      ;;
+    *)
+      printf 'GOVERNANCE_INTEGRITY: field family invariants 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
+
+source "$(dirname "$0")/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: hook integrity helper unavailable\n' >&2
+  exit 70
+}
+governance_hook_load_input
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'field family tool extraction failed'
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'field family path extraction failed'
 
 # Tool filter — 只 Edit/Write/MultiEdit 跑
 case "$TOOL" in
@@ -40,20 +105,26 @@ esac
 
 # 讀 merged content(舊檔 + 新 edit 拼起)— A.1 / A.3 需要整檔判 naked variant 存在性
 FILE_CONTENT=""
-if [ -f "$FILE_PATH" ]; then
-  FILE_CONTENT=$(cat "$FILE_PATH")
+if [ -e "$FILE_PATH" ] || [ -L "$FILE_PATH" ]; then
+  FILE_PATH=$(governance_hook_project_file_path "$FILE_PATH" 2>/dev/null) \
+    || governance_hook_integrity_fail 'field family target escapes the project or crosses a symlink'
+  if [ -L "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ] || [ ! -r "$FILE_PATH" ]; then
+    governance_hook_integrity_fail 'field family target is unavailable or unsafe'
+  fi
+  FILE_CONTENT=$(cat "$FILE_PATH" 2>/dev/null) \
+    || governance_hook_integrity_fail 'field family target read failed'
 fi
-NEW_CONTENT=$(echo "$INPUT" | jq -r '
+NEW_CONTENT=$(printf '%s' "$INPUT" | jq -r '
   (.tool_input.content // "") + "\n" +
   (.tool_input.new_string // "") + "\n" +
   ([.tool_input.edits[]? | .new_string] | join("\n"))
-' 2>/dev/null || echo "")
+' 2>/dev/null) || governance_hook_integrity_fail 'field family edit payload extraction failed'
 
 # A.2 / A.4 只看 NEW_CONTENT(diff-level signal),A.1 / A.3 看 MERGED
 MERGED_CONTENT="${FILE_CONTENT}
 ${NEW_CONTENT}"
 
-[ -z "${MERGED_CONTENT//[[:space:]]/}" ] && exit 0
+grep -q '[^[:space:]]' <<<"$MERGED_CONTENT" || exit 0
 
 WORST=0
 record_worst() { local lvl=$1; [ "$lvl" -gt "$WORST" ] && WORST=$lvl; }
@@ -64,10 +135,10 @@ case "$FILE_PATH" in
     case "$FILE_PATH" in
       */field-wrapper.tsx|*/textarea.tsx) ;; # SSOT host skip
       *)
-        if ! echo "$MERGED_CONTENT" | grep -q '@naked-row-mode-allow' \
+        if ! grep -q '@naked-row-mode-allow' <<<"$MERGED_CONTENT" \
            && echo "$MERGED_CONTENT" | grep -E "variant:\s*['\"]naked['\"]|variant=\{?['\"]naked['\"]" >/dev/null \
-           && echo "$MERGED_CONTENT" | grep -E "(inline-flex|flex)[^\"'\`]*items-center" >/dev/null \
-           && ! echo "$MERGED_CONTENT" | grep -q "nakedCellRowModeAlign"; then
+           && echo "$MERGED_CONTENT" | tr '\n' ' ' | grep -E "(inline-flex|flex)[^\"'\`]*items-center" >/dev/null \
+           && ! grep -q "nakedCellRowModeAlign" <<<"$MERGED_CONTENT"; then
           cat >&2 <<EOF
 
 ┄┄┄ A.1 check_field_family_invariants — naked row-mode propagation BLOCKER ┄┄┄
@@ -95,8 +166,8 @@ esac
 # ── A.2 FieldControlGroup wrapper direct child(P1 WARN)────────────────────────
 case "$FILE_PATH" in
   *.tsx)
-    if echo "$NEW_CONTENT" | grep -q '<FieldControlGroup' \
-       && ! echo "$NEW_CONTENT" | grep -q '@fcg-wrapper-allow'; then
+    if grep -q '<FieldControlGroup' <<<"$NEW_CONTENT" \
+       && ! grep -q '@fcg-wrapper-allow' <<<"$NEW_CONTENT"; then
       SUSPECT=$(printf '%s' "$NEW_CONTENT" | awk '
         /<FieldControlGroup/ { inFCG=1; next }
         /<\/FieldControlGroup>/ { inFCG=0; next }
@@ -119,7 +190,6 @@ ${SUSPECT}
   3. wrapper 用 \`display:contents\` / 加 \`// @fcg-wrapper-allow: <reason>\`
 
 EOF
-        record_worst 1
       fi
     fi
     ;;
@@ -131,7 +201,7 @@ case "$FILE_PATH" in
     case "$FILE_PATH" in
       */field-wrapper.tsx|*/textarea.tsx|*.stories.tsx|*.test.*|*.spec.tsx) ;; # SSOT/test skip
       *)
-        if ! echo "$NEW_CONTENT" | grep -q '@field-state-ring-allow'; then
+        if ! grep -q '@field-state-ring-allow' <<<"$NEW_CONTENT"; then
           # A.3.1 舊 box-shadow inset
           if echo "$NEW_CONTENT" | grep -E "(hover|focus-within|data-\[state=open\]):shadow-\[inset" >/dev/null; then
             cat >&2 <<'EOF'
@@ -157,8 +227,18 @@ EOF
             record_worst 2
           fi
           # A.3.3 per-control open=blue override(v13.5)
-          if echo "$NEW_CONTENT" | grep -E "(open|isOpen) +&& +.{0,40}('border-primary'|\"border-primary\")" >/dev/null \
-             || echo "$NEW_CONTENT" | grep -E "data-\[state=open\]:border-primary" >/dev/null; then
+          # 2026-06-11 deep-audit R2(n=38)精準化(M7 broad-vs-narrow 3-column):
+          #   Spec wording:v13.3 禁「open 時 per-control 把 border 轉 primary(藍)」。
+          #   Hook regex(舊):substring 無 boundary + 不分註解行。
+          #   Gap:誤命中 (a) `data-[state=open]:border-primary-hover` canonical(button.tsx:99,109
+          #     overlay trigger 維持 hover 樣式,-hover/-active 是合法 token 後綴);(b) v13.3 retire
+          #     註解內引用舊 pattern 文字(combobox.tsx:725 / select.tsx:594)。
+          #   修:純註解行剝離 + border-primary 加字尾 boundary([^-a-zA-Z]|$)。
+          #   DS-wide counter-example scan 2026-06-11:新 regex 全 components/ 0 hit(真違規 shape
+          #   `open && 'border-primary'` / `data-[state=open]:border-primary` 結尾 仍 BLOCK,fixture 驗證)。
+          A33_CONTENT=$(echo "$NEW_CONTENT" | grep -vE '^[[:space:]]*(//|\*|/\*)')
+          if echo "$A33_CONTENT" | grep -E "(open|isOpen) +&& +.{0,40}('border-primary'|\"border-primary\")" >/dev/null \
+             || echo "$A33_CONTENT" | grep -E "data-\[state=open\]:border-primary([^-a-zA-Z]|$)" >/dev/null; then
             cat >&2 <<'EOF'
 
 ┄┄┄ A.3.3 check_field_family_invariants — per-control open=blue BLOCKER ┄┄┄
@@ -175,14 +255,14 @@ EOF
     ;;
 esac
 
-# ── A.4 disabled placeholder color(P1 stderr,exit 0 不 block)──────────────────
-if ! echo "$NEW_CONTENT" | grep -q '@disabled-color-allow'; then
+# ── A.4 disabled placeholder color(P1 context,exit 0 不 block)─────────────────
+if ! grep -q '@disabled-color-allow' <<<"$NEW_CONTENT"; then
   SUSPECT_DP=""
   if echo "$NEW_CONTENT" | grep -E "placeholder:text-fg-muted" >/dev/null \
      && ! echo "$NEW_CONTENT" | grep -E "(disabled:placeholder:text-fg-disabled|group-data-\[field-mode=disabled\].*placeholder:text-fg-disabled|resolvedMode\s*===\s*'disabled'.*text-fg-disabled)" >/dev/null; then
     SUSPECT_DP="$SUSPECT_DP [placeholder:text-fg-muted 無 disabled override]"
   fi
-  if echo "$NEW_CONTENT" | grep -E '<span[^>]*"text-fg-muted"[^>]*>\s*\{[^}]*placeholder' >/dev/null 2>&1 \
+  if echo "$NEW_CONTENT" | tr '\n' ' ' | grep -E '<span[^>]*"text-fg-muted"[^>]*>[[:space:]]*\{[^}]*placeholder' >/dev/null 2>&1 \
      && ! echo "$NEW_CONTENT" | grep -E "resolvedMode\s*===\s*'disabled'" >/dev/null; then
     SUSPECT_DP="$SUSPECT_DP [<span text-fg-muted>{placeholder} 不分 mode]"
   fi
@@ -198,8 +278,99 @@ ${SUSPECT_DP}
 例外:行尾 \`// @disabled-color-allow: <reason>\`
 
 EOF
-    # A.4 原 hook exit 0(stderr only),保持向後兼容不升 WORST
+    # A.4 維持非阻擋 warning,由最外層聚合成 governanceContext。
   fi
 fi
 
+# ── A.5 _Group child fieldCtx.id 隔離(P0 BLOCKER,2026-05-31 折入,M4 AR34 regression detector)──
+# M4:_Group 元件(CheckboxGroup/RadioGroup/SwitchGroup)的 child item 不可共用 fieldCtx.id —— 否則
+# group 內所有 label 被抑制 + 點 label 只 toggle 第一個(AR34 root bug)。正解:item 在 group 內走自己
+# 的 generatedId,不 fall back 到共用 fieldCtx.id。偵測 AR34 regression shape(MERGED 整檔,3-signal AND):
+#   (1) 消費 *GroupContext  (2) bare `idProp ?? fieldCtx?.id ?? generatedId` fallback
+#   (3) 缺 `insideGroup ? generatedId` / `inGroup ? generatedId` group guard
+case "$FILE_PATH" in
+  *components/*.tsx)
+    if ! grep -q '@group-fieldctx-allow' <<<"$MERGED_CONTENT" \
+       && grep -qE 'useContext\([A-Za-z_]*GroupContext\)' <<<"$MERGED_CONTENT" \
+       && grep -qE 'idProp[[:space:]]*\?\?[[:space:]]*fieldCtx\?\.id[[:space:]]*\?\?[[:space:]]*generatedId' <<<"$MERGED_CONTENT" \
+       && ! grep -qE '(insideGroup|inGroup)[[:space:]]*\?[[:space:]]*generatedId' <<<"$MERGED_CONTENT"; then
+      cat >&2 <<EOF
+
+┄┄┄ A.5 check_field_family_invariants — _Group child fieldCtx.id 隔離 BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測到 _Group child item 消費 GroupContext + bare \`idProp ?? fieldCtx?.id ?? generatedId\` fallback,
+但**缺** group guard(\`insideGroup ? generatedId\`)= M4 AR34 regression shape。
+
+⚠️  M4 canonical:Group 內 item 不可共用 fieldCtx.id(否則所有 label 被抑制 + 點 label 只 toggle 第一個)。
+
+修法:
+  inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))
+  即 group 內走自己的 generatedId,不 fall back 共用 fieldCtx.id。
+  例外:行尾 \`// @group-fieldctx-allow: <reason>\`
+
+EOF
+      record_worst 2
+    fi
+    ;;
+esac
+
+# ── A.6 空值顯示 SSOT(P0 BLOCKER,2026-07-08 user 拍板半形 hyphen)────────────────
+# user verbatim「我從頭到尾哪裡有說要用全形的」+ 五情境空值框架。SSOT:符號常數 =
+#   field-wrapper.tsx `EMPTY_DISPLAY = '-'`(U+002D 半形);分流 hook = field-context.ts
+#   `useFieldEmptyDisplay()`。禁 2 shape:
+#   A.6.1 非 owner 檔直接 import `EMPTY_DISPLAY` 常數(應消費 hook 分流,否則 table-cell
+#         editable→'' 分流會漏);
+#   A.6.2 components/ tsx display 路徑 hardcode 全形 em dash `'—'`/`"—"`(U+2014)字面。
+# M7 broad-vs-narrow:spec wording 廣(「禁 hardcode 空值符號」);hook 取「quoted em dash 字面」
+#   高信號 subset + owner skip + comment 剝離 + `@empty-display-allow` escape,零誤判導向。
+if ! grep -q '@empty-display-allow' <<<"$NEW_CONTENT"; then
+  # A.6.1 非 owner 檔 import EMPTY_DISPLAY 常數(剝離註解行)
+  case "$FILE_PATH" in
+    */field-context.ts|*/field-wrapper.tsx) ;; # SSOT owner(定義 + 分流 hook)skip
+    *)
+      A61_CONTENT=$(echo "$NEW_CONTENT" | grep -vE '^[[:space:]]*(//|\*|/\*)')
+      if printf '%s' "$A61_CONTENT" | grep -E "import.*EMPTY_DISPLAY|EMPTY_DISPLAY.*from" >/dev/null; then
+        cat >&2 <<EOF
+
+┄┄┄ A.6.1 check_field_family_invariants — EMPTY_DISPLAY 直引 BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測到直接 import \`EMPTY_DISPLAY\` 常數(非 field-context.ts owner)。
+空值顯示必經 \`useFieldEmptyDisplay()\` hook 分流(table-cell 可編輯→空白 / 其餘→半形 '-'),
+直引常數會漏 surface × editable 分流。
+
+修法:import { useFieldEmptyDisplay } from '@/design-system/components/Field/field-context'
+      const emptyDisplay = useFieldEmptyDisplay()
+例外:行尾 \`// @empty-display-allow: <reason>\`
+
+EOF
+        record_worst 2
+      fi
+      ;;
+  esac
+  # A.6.2 components/ tsx hardcode 全形 em dash 空值字面(剝離註解行 + owner/story skip)
+  case "$FILE_PATH" in
+    *.stories.tsx|*/field-context.ts|*/field-wrapper.tsx) ;; # doc N/A marker + SSOT owner skip
+    *components/*.tsx)
+      A62_CONTENT=$(echo "$NEW_CONTENT" | grep -vE '^[[:space:]]*(//|\*|/\*)')
+      if printf '%s' "$A62_CONTENT" | grep -E "['\"]—['\"]" >/dev/null; then
+        cat >&2 <<EOF
+
+┄┄┄ A.6.2 check_field_family_invariants — 全形 em dash 空值 BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測到 components/ 實作檔 hardcode 全形 em dash \`'—'\`(U+2014)字面。
+user 2026-07-08 拍板:空值符號 = **半形 hyphen '-'(U+002D)**,禁全形。
+
+修法:空值一律 \`{value ?? emptyDisplay}\`(emptyDisplay = useFieldEmptyDisplay()),不 hardcode 符號。
+例外:行尾 \`// @empty-display-allow: <reason>\`
+
+EOF
+        record_worst 2
+      fi
+      ;;
+  esac
+fi
+
 exit $WORST

package/ds-canonical/hooks/check_file_size_budget.sh

@@ -2,17 +2,19 @@
 set -uo pipefail
 # PreToolUse Edit/Write: enforce per-file line budgets for governance files.
 #
-# Budgets — SSOT 是 CLAUDE.md `# 治理 canonical` 「行數預算」段。
-# 本檔不再硬寫(避免 漂移 — 2026-05-15 Fix 4 per sub-agent a9e6d53c finding 6:
-# 之前硬寫 400 vs CLAUDE.md「target 200 / transition 400 / hard cap 800」三 home 三 baseline)。
-# 改 dynamic 從 CLAUDE.md grep,fallback 寫死值。SSOT 改一處全處跟動。
+# Budgets — SSOT 是 shared instruction entry `# 治理 canonical` 「行數預算」段。
+# Provider/instruction/skill 路徑由 canonical registry 解析,不以任一 generated home 當 authority。
 #
-# Non-blocking: injects warning via hookSpecificOutput additionalContext; Claude
-# decides whether to split or ack. Hard block would paralyse edits to legitimately
+# Non-blocking: emits a provider-neutral governance context warning; the adapter
+# transports it to the active model. Hard block would paralyse edits to legitimately
 # large canonical specs (e.g. item-anatomy ~900 lines) — require explicit override.
 
 # Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$(dirname "$0")/lib/_provider_paths.sh" 2>/dev/null || {
+  printf 'file-size hook blocked: canonical provider resolver unavailable\n' >&2
+  exit 2
+}
 
 set -euo pipefail
 
@@ -21,13 +23,19 @@ FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
 [ -z "$FILE_PATH" ] && exit 0
 [ -f "$FILE_PATH" ] || exit 0
+REL_PATH="$(governance_project_relative_path "$FILE_PATH" 2>/dev/null)" || exit 0
+INSTRUCTION_ENTRY="$(governance_provider_string_field instructionEntry 2>/dev/null)" || exit 2
+SHARED_INSTRUCTION_ENTRY="$(governance_provider_string_field sharedInstructionEntry 2>/dev/null)" || exit 2
+CANONICAL_SKILL_ROOT="$(governance_canonical_relative_root skills 2>/dev/null)" || exit 2
+PROVIDER_SKILL_ROOT="$(governance_provider_string_field skillDirectory 2>/dev/null)" || exit 2
+SKILL_ENTRY_FILE="$(governance_provider_skill_entry_file 2>/dev/null || true)"
 
 # Only check governance files
-# CLAUDE.md L34 SSOT: target ≤ 200(Anthropic best-practice)/ transition ≤ 400 / hard cap 800
+# Shared bootstrap SSOT: target ≤ 250 / transition ≤ 400 / hard cap 800
 # 本 hook 在 transition 觸發 P1 warning,hard cap 觸發 P0 block
-case "$FILE_PATH" in
-  */CLAUDE.md)                          BUDGET=400;  TRANSITION=800; LABEL="CLAUDE.md" ;;  # warn at transition (400), block at hard cap (800); target 200
-  */memory/*.md)                        BUDGET=100;  TRANSITION=100; LABEL="memory file" ;;
+case "$REL_PATH" in
+  "$INSTRUCTION_ENTRY"|"$SHARED_INSTRUCTION_ENTRY") BUDGET=400; TRANSITION=800; LABEL="instruction entry" ;;
+  governance/memory/*.md)               BUDGET=100;  TRANSITION=100; LABEL="memory file" ;;
   # Super-foundational SSOT spec(item-anatomy = Family 1+2 跨 10+ 消費者 SSOT,唯一例外)
   */item-anatomy.spec.md)
     BUDGET=800;  TRANSITION=1200; LABEL="super-foundational SSOT spec.md(item-anatomy 例外)" ;;
@@ -35,14 +43,24 @@ case "$FILE_PATH" in
   # 2026-05-18 加 data-table:DS 最複雜 composite + 跨家族 anchor(L1-L4 完整 grid taxonomy,
   # 行對齊 item-anatomy / 浮層對齊 overlay-surface / state 對齊 field-controls)。
   # frontmatter 已標 `foundational_ssot: true`。
-  # 2026-05-22 prune:color.spec.md 升 tier 2 cap 1000(per CLAUDE.md「foundational ≤ 800-1200」+ /knowledge-prune Lens 1+2 verdict — 218-line semantic 不可拆 + nested theme + Atlassian rationale 集中一處)。
+  # 2026-05-22 prune:color.spec.md 升 tier 2 cap 1000(per shared bootstrap「foundational ≤ 800-1200」+ /knowledge-prune Lens 1+2 verdict — 218-line semantic 不可拆 + nested theme + Atlassian rationale 集中一處)。
   */color.spec.md)
     BUDGET=800;  TRANSITION=1000; LABEL="foundational SSOT spec.md(color tier 2 cap 1000)" ;;
   */sidebar.spec.md|*/tree-view.spec.md|*/data-table.spec.md)
     BUDGET=500;  TRANSITION=800; LABEL="foundational SSOT spec.md" ;;
   *.spec.md)                            BUDGET=300;  TRANSITION=500; LABEL="spec.md" ;;
-  *.claude/skills/*/SKILL.md)           BUDGET=250;  TRANSITION=400; LABEL="SKILL.md" ;;
-  *) exit 0 ;;
+  *)
+    if governance_path_is_under "$REL_PATH" "$CANONICAL_SKILL_ROOT" \
+      && [ "${REL_PATH##*/}" = "SKILL.md" ]; then
+      BUDGET=250; TRANSITION=400; LABEL="canonical SKILL.md"
+    elif [ -n "$SKILL_ENTRY_FILE" ] \
+      && governance_path_is_under "$REL_PATH" "$PROVIDER_SKILL_ROOT" \
+      && [ "${REL_PATH##*/}" = "$SKILL_ENTRY_FILE" ]; then
+      BUDGET=250; TRANSITION=400; LABEL="provider skill entry($SKILL_ENTRY_FILE)"
+    else
+      exit 0
+    fi
+    ;;
 esac
 
 LINES=$(wc -l < "$FILE_PATH" | tr -d ' ')
@@ -56,5 +74,5 @@ else
 fi
 
 ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
-printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+printf '{"governanceContext":{"hookEventName":"PreToolUse","message":%s}}\n' "$ESCAPED"
 exit 0

package/ds-canonical/hooks/check_full_story_visual_interaction_sweep.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+# check_full_story_visual_interaction_sweep.sh — P0 BLOCKER
+#
+# Codex M31 P0 finding 2026-05-27: ds-story-manifest.json 是 story 總數 SSOT(動態,
+# 禁 hardcode 數字 — 真值以 manifest.totalStories 為準;2026-07-04 dim 73 修 stale 916),
+# 但無 hook 攔 audit reports 漏 manifest story IDs / screenshots / metrics / probe.
+# User 2026-05-27 verbatim「不准抽樣 全 visual + interaction 全跑」.
+#
+# Triggers when audit report JSON is edited/written:
+#   - /tmp/codex-*-sweep/audit-report.json
+#   - /tmp/claude-*-sweep/audit-report.json
+#   - provider-neutral governance runtime evidence/*audit-report.json
+# Verifies storyResults.length === manifest.totalStories(動態讀 manifest)— block if sample.
+#
+# Escape: report frontmatter `"_sampling_allowed": "<rationale>"`(極罕見).
+
+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: full-story sweep provider 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
+}
+
+set -uo pipefail
+
+governance_hook_load_input
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'full-story sweep tool extraction failed'
+
+case "${TOOL:-}" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'full-story sweep path extraction failed'
+case "$FILE" in *sweep.json|*audit-report.json) ;; *) exit 0 ;; esac
+
+CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'full-story sweep report extraction failed'
+
+# The report is enforcement evidence. Invalid JSON/schema is an integrity fault; a valid report
+# with no coverage is a genuine policy failure and is handled by the comparison below.
+if ! printf '%s' "$CONTENT" | jq -e '
+  type == "object"
+  and (._sampling_allowed? == null or (._sampling_allowed | type == "string"))
+  and (.storyResults? == null or (.storyResults | type == "array"))
+  and (.results? == null or (.results | type == "array"))
+  and (.storySummary? == null or (.storySummary | type == "object"))
+  and (.summary? == null or (.summary | type == "object"))
+  and (
+    [.storySummary.total?, .summary.total?, .total?]
+    | all(. == null or (type == "number" and floor == . and . >= 0))
+  )
+' >/dev/null 2>&1; then
+  governance_hook_integrity_fail 'full-story sweep report is malformed or invalid'
+fi
+
+# Check the explicit, schema-valid escape only after the report itself has been validated.
+SAMPLING_ESCAPE=$(printf '%s' "$CONTENT" | jq -r '._sampling_allowed // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'full-story sweep escape extraction failed'
+if [ -n "$SAMPLING_ESCAPE" ]; then
+  exit 0
+fi
+
+# Parse story count vs manifest (multi-field fallback).
+STORY_COUNT=$(printf '%s' "$CONTENT" | jq -r '
+  ((.storyResults // .results // []) | length) as $arrayCount
+  | if $arrayCount > 0 then $arrayCount
+    else (.storySummary.total // .summary.total // .total // 0)
+    end
+' 2>/dev/null) || governance_hook_integrity_fail 'full-story sweep count extraction failed'
+
+PROJECT_ROOT=$(governance_project_root 2>/dev/null) \
+  || governance_hook_integrity_fail 'full-story sweep project root could not be resolved'
+MANIFEST_PATH="$PROJECT_ROOT/packages/design-system/ds-story-manifest.json"
+if [ -L "$MANIFEST_PATH" ] || [ ! -f "$MANIFEST_PATH" ] || [ ! -r "$MANIFEST_PATH" ]; then
+  governance_hook_integrity_fail "full-story sweep manifest is unavailable or unsafe:${MANIFEST_PATH}"
+fi
+if ! jq -e '
+  type == "object"
+  and (.totalStories | type == "number" and floor == . and . > 0)
+' "$MANIFEST_PATH" >/dev/null 2>&1; then
+  governance_hook_integrity_fail "full-story sweep manifest is invalid:${MANIFEST_PATH}"
+fi
+MANIFEST_TOTAL=$(jq -r '.totalStories' "$MANIFEST_PATH" 2>/dev/null) \
+  || governance_hook_integrity_fail 'full-story sweep manifest count extraction failed'
+
+if [ "$STORY_COUNT" -lt "$MANIFEST_TOTAL" ]; then
+  cat >&2 << EOF
+🚨 FULL-STORY-SWEEP BLOCKER(P0,codex M31 finding 2026-05-27 + user「不准抽樣」)
+
+  Audit report $FILE:
+    storyResults: $STORY_COUNT
+    manifest.totalStories: $MANIFEST_TOTAL
+    缺失: $((MANIFEST_TOTAL - STORY_COUNT)) stories
+
+  per ds-story-manifest.json SSOT(scripts/gen-ds-story-manifest.mjs:59)+ user 2026-05-27
+  「請你不要給我抽樣,因為你一抽樣就是會有東西壞掉,務必要全部檢查」directive.
+
+  修法 2 選 1:
+    (a) Re-run sweep covering all $MANIFEST_TOTAL stories
+    (b) Escape:report 含 \`"_sampling_allowed": "<rationale>"\`(極罕見)
+EOF
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_item_list_gap.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# check_item_list_gap.sh — M16 mechanical enforcement(2026-05-26 backfill).
+#
+# Purpose:PreToolUse Edit/Write — 偵測 production tsx 含 standalone card/pill 渲染
+# pattern(`<FileItem>` / `<MenuItem rich>` / 卡片型 standalone)without gap-N or space-y-N
+# parent → soft warn requires explicit gap canonical per item-anatomy.spec.md。
+#
+# 3 條公式(per M16):
+#   - 同類 standalone 卡片 → 必 gap
+#   - 同類 permanent flush(連續貼齊)→ 0 gap OK,但必 codify in spec
+#   - 混合語言 → 必取最保守 gap
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+NEW=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null)
+
+[ "$EVENT" != "PreToolUse" ] && exit 0
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.tsx) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.stories.tsx|*.test.tsx) exit 0 ;; esac
+
+# Heuristic:multiple <FileItem> / <MenuItem variant="rich"> / standalone card pattern + parent 無 gap-N
+# 2026-05-26 fix:grep -c 計行數不計次,用 -o count 真實 occurrence
+STANDALONE_RE='<(FileItem|MenuItem[^>]+variant=["'\'']rich["'\''])'
+COUNT=$(echo "$NEW" | grep -oE "$STANDALONE_RE" 2>/dev/null | wc -l | tr -d ' ')
+COUNT=${COUNT:-0}
+
+[ "$COUNT" -lt 2 ] && exit 0
+
+# Has gap-N or space-y-N near the standalone pattern?
+if grep -qE '(gap-[0-9]|space-y-[0-9])' <<<"$NEW"; then
+  exit 0
+fi
+
+MESSAGE=$(cat <<EOF
+⚠️ M16 Item-list gap canonical
+
+→ 偵測到 $COUNT 個 standalone item(FileItem / MenuItem rich)未見 gap-N / space-y-N parent class。
+
+M16 要求(per item-anatomy.spec.md):
+  - 同類 standalone → 必 gap(常見 gap-2 / gap-3)
+  - 同類 permanent flush(連續貼齊)→ 0 gap OK,但必 spec codify
+  - 混合語言 → 必取最保守 gap
+
+修法:parent container 加 \`gap-2\` / \`space-y-2\` 或 codify 連續貼齊 in 元件 spec。
+對應 canonical:meta-patterns.md M16 + patterns/element-anatomy/item-anatomy.spec.md。
+EOF
+)
+printf '{"governanceContext":{"hookEventName":"PreToolUse","message":%s}}\n' "$(printf '%s' "$MESSAGE" | jq -Rs .)"
+
+exit 0