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

package/ds-canonical/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"
+}

package/ds-canonical/hooks/lib/_layout_space_canonical.sh

@@ -16,7 +16,7 @@ source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
 FILE_PATH=$(jq -r '.tool_input.file_path // empty')
 
 # Scope: only stories.tsx + app code (not core component .tsx — they own their own internal padding)
-if ! echo "$FILE_PATH" | grep -qE '(\.stories\.tsx$|src/app/.*\.tsx$|src/explorations/.*\.tsx$)'; then
+if ! grep -qE '(\.stories\.tsx$|src/app/.*\.tsx$|src/explorations/.*\.tsx$)' <<<"$FILE_PATH"; then
   exit 0
 fi
 if [ ! -f "$FILE_PATH" ]; then
@@ -28,7 +28,7 @@ VIOLATIONS=""
 # ── Check 1: hardcoded mt-N / mb-N adjacent to <DataTable / Textarea / Editor> ──
 # Block elements need loose bottom/top gap; tight is rule violation.
 # Pattern: <DataTable...>...</...> followed by <Alert / BulkActionBar / div with mt-tight>
-BLOCK_TIGHT_HITS=$(grep -nE "(mt|mb)-\[var\(--layout-space-tight\)\]" "$FILE_PATH" 2>/dev/null | head -5)
+BLOCK_TIGHT_HITS=$(grep -m 5 -nE "(mt|mb)-\[var\(--layout-space-tight\)\]" "$FILE_PATH" 2>/dev/null)
 if [ -n "$BLOCK_TIGHT_HITS" ]; then
   # Only flag if file ALSO contains block elements (DataTable / Textarea / Editor / CodeBlock)
   if grep -qE '<(DataTable|Textarea|Editor|CodeBlock)' "$FILE_PATH" 2>/dev/null; then
@@ -38,7 +38,7 @@ fi
 
 # ── Check 3: gap-tight on flex column form with all-inline (likely violation)──
 # 規則 3:inline ↔ inline = loose,不是 tight
-GAP_TIGHT_FLEX=$(grep -nE 'flex-col\s+gap-\[var\(--layout-space-tight\)\]' "$FILE_PATH" 2>/dev/null | head -3)
+GAP_TIGHT_FLEX=$(grep -m 3 -nE 'flex-col\s+gap-\[var\(--layout-space-tight\)\]' "$FILE_PATH" 2>/dev/null)
 if [ -n "$GAP_TIGHT_FLEX" ]; then
   VIOLATIONS="${VIOLATIONS}\n⚠️ flex-col gap-tight(若內容全是 inline 元件就違反規則 3:inline ↔ inline 應 loose):\n${GAP_TIGHT_FLEX}\n  → 確認 form 內含 block(Table/Textarea/Editor)?有 → 保留 tight 合規;全 inline → 改 loose。"
 fi
@@ -46,9 +46,9 @@ fi
 if [ -n "$VIOLATIONS" ]; then
   ADDITIONAL_CONTEXT=$(printf '⚠️ layoutSpace canonical 提醒(tokens/layoutSpace/layoutSpace.spec.md):%b' "$VIOLATIONS")
   jq -n --arg ctx "$ADDITIONAL_CONTEXT" '{
-    hookSpecificOutput: {
+    governanceContext: {
       hookEventName: "PostToolUse",
-      additionalContext: $ctx
+      message: $ctx
     }
   }'
 fi

package/ds-canonical/hooks/lib/_micro_geometry.sh

@@ -0,0 +1,291 @@
+#!/bin/bash
+# Shared structural classifier for layoutSpace's mechanically provable fixed micro geometry.
+#
+# Policy data lives in utility-registry.json. This helper owns the bounded parser used by both the
+# layout magic-number gate and the escape-marker ceiling so those gates cannot disagree about
+# whether `gap-1` / `gap-2` is an active bypass.
+
+governance_micro_geometry_registry_file() {
+  local corpus registry
+  corpus="$(governance_corpus_root)" || return 1
+  if [ -f "$corpus/packages/design-system/src/tokens/utility-registry.json" ]; then
+    registry="$corpus/packages/design-system/src/tokens/utility-registry.json"
+  else
+    registry="$corpus/references/utility-registry.json"
+  fi
+  [ -f "$registry" ] && [ -r "$registry" ] && [ ! -L "$registry" ] || return 1
+  printf '%s\n' "$registry"
+}
+
+governance_micro_geometry_scan() {
+  local mode="$1" payload="${2:-}" candidates="${3:-}" root="${4:-}" registry
+  registry="$(governance_micro_geometry_registry_file)" || return 1
+  python3 - "$mode" "$registry" "$root" 3<<<"$payload" 4<<<"$candidates" <<'PY'
+import json
+import os
+import re
+import stat
+import sys
+
+mode, registry_path, scan_root = sys.argv[1:4]
+payload = os.fdopen(3, encoding="utf-8").read()
+candidates = os.fdopen(4, encoding="utf-8").read()
+
+with open(registry_path, encoding="utf-8") as source:
+    registry = json.load(source)
+
+if (
+    not isinstance(registry, dict)
+    or registry.get("schemaVersion") != 1
+    or registry.get("_meta", {}).get("owner")
+       != "packages/design-system/src/tokens/utility-registry.json"
+):
+    raise ValueError("utility registry identity is invalid")
+
+policy = registry.get("spacing", {}).get("canonical_micro_geometry")
+expected_keys = {
+    "gap_utilities",
+    "alignment_utilities",
+    "inline_display_utilities",
+    "phrasing_elements",
+    "list_container_elements",
+    "list_item_elements",
+    "list_roles",
+    "control_roles",
+    "field_group_elements",
+    "field_group_roles",
+    "field_control_elements",
+    "nearby_line_limit",
+    "rationale",
+    "rationale_path",
+}
+if not isinstance(policy, dict) or set(policy) != expected_keys:
+    raise ValueError("canonical micro-geometry policy is invalid")
+
+array_keys = expected_keys - {"nearby_line_limit", "rationale", "rationale_path"}
+for key in array_keys:
+    value = policy[key]
+    if (
+        not isinstance(value, list)
+        or not value
+        or len(value) != len(set(value))
+        or any(not isinstance(item, str) or not item for item in value)
+    ):
+        raise ValueError(f"canonical micro-geometry list is invalid:{key}")
+if not isinstance(policy["nearby_line_limit"], int) or not 1 <= policy["nearby_line_limit"] <= 32:
+    raise ValueError("canonical micro-geometry nearby bound is invalid")
+if any(not isinstance(policy[key], str) or not policy[key] for key in ("rationale", "rationale_path")):
+    raise ValueError("canonical micro-geometry rationale is invalid")
+
+allowed_gaps = set(policy["gap_utilities"])
+alignments = set(policy["alignment_utilities"])
+inline_displays = set(policy["inline_display_utilities"])
+phrasing_elements = set(policy["phrasing_elements"])
+list_containers = set(policy["list_container_elements"])
+list_items = set(policy["list_item_elements"])
+list_roles = set(policy["list_roles"])
+control_roles = set(policy["control_roles"])
+field_groups = set(policy["field_group_elements"])
+field_group_roles = set(policy["field_group_roles"])
+field_controls = set(policy["field_control_elements"])
+nearby_limit = policy["nearby_line_limit"]
+
+# This is the exact family recognized by check_layout_space_magic_numbers.sh. Classification is
+# intentionally stricter than detection:every magic token on the candidate line must be one of
+# the registry-owned gap utilities, so `gap-2 p-4` cannot hide its macro padding.
+magic_token_re = re.compile(
+    r"(?<![A-Za-z0-9_])(?:"
+    r"(?:p|px|py|pt|pb|pl|pr|ps|pe|gap|space-x|space-y|m|mx|my|mt|mb|ml|mr|ms|me)-"
+    r"(?:0\.5|[1-9][0-9]?(?:\.[0-9])?)"
+    r"|(?:p|px|py|pt|pb|pl|pr|ps|pe|gap|m|mx|my|mt|mb|ml|mr|ms|me)-"
+    r"\[[0-9]+(?:\.[0-9]+)?px\]"
+    r"|w-\[[0-9]+(?:\.[0-9]+)?px\]"
+    r"|grid-(?:cols|rows)-\[[^\]]*[0-9]+px[^\]]*\]"
+    r")(?![A-Za-z0-9_.-])"
+)
+marker_re = re.compile(
+    r"@(?:[a-z][a-z-]*-allow|benchmark-unverified(?:-blanket)?|template-customized|"
+    r"anatomy-exempt(?:-next)?|overlay-open-skip|layout-space-magic-ok|"
+    r"propose-cite-skip|story-(?:trait|split)-rationale)"
+)
+
+
+def has_utility(line, utility):
+    return re.search(
+        rf"(?<![A-Za-z0-9_-]){re.escape(utility)}(?![A-Za-z0-9_.-])",
+        line,
+    ) is not None
+
+
+def has_any_utility(line, utilities):
+    return any(has_utility(line, utility) for utility in utilities)
+
+
+def has_open_element(line, elements):
+    return any(re.search(rf"<{re.escape(element)}\b", line) for element in elements)
+
+
+def phrasing_owner_has_geometry(line):
+    """Require the phrasing element itself to own the geometry-bearing class attribute."""
+    for match in re.finditer(r"<([A-Za-z][A-Za-z0-9.]*)\b([^<>]*)>", line):
+        tag, attributes = match.groups()
+        if tag not in phrasing_elements or not re.search(r"\bclass(?:Name)?\s*=", attributes):
+            continue
+        if (
+            has_utility(attributes, "flex")
+            and has_any_utility(attributes, alignments)
+            and has_any_utility(attributes, allowed_gaps)
+        ):
+            return True
+    return False
+
+
+def has_role(line, roles):
+    return any(
+        re.search(rf"\brole\s*=\s*['\"]{re.escape(role)}['\"]", line)
+        for role in roles
+    )
+
+
+def nearby_window(lines, index):
+    return "\n".join(lines[index:index + nearby_limit + 1])
+
+
+def is_canonical_micro_line(lines, index):
+    if index < 0 or index >= len(lines):
+        return False
+    line = lines[index]
+    tokens = magic_token_re.findall(line)
+    if not tokens or any(token not in allowed_gaps for token in tokens):
+        return False
+    # A quoted class assignment or JSX class attribute is required. Prose mentioning gap-1/2 is
+    # not executable structural evidence.
+    if not re.search(r"\bclass(?:Name)?\s*=|\b(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*['\"`]", line):
+        return False
+
+    aligned = has_any_utility(line, alignments)
+    flex = has_utility(line, "flex")
+    flex_col = has_utility(line, "flex-col")
+
+    # Inline item/Button anatomy. `span` remains acceptable when Tailwind's block-level `flex`
+    # utility is used because the HTML owner is still a bounded phrasing wrapper.
+    if aligned and (
+        has_any_utility(line, inline_displays)
+        or phrasing_owner_has_geometry(line)
+    ):
+        return True
+
+    # Compact toolbars are the explicit Button xs micro-control context.
+    if aligned and flex and has_role(line, control_roles):
+        return True
+
+    window = nearby_window(lines, index)
+
+    # A semantic list container must own actual nearby list items (or a map that materializes one),
+    # preventing a generic `div.flex-col.gap-2` macro stack from entering through this lane.
+    if flex_col and (
+        has_open_element(line, list_containers)
+        or has_role(line, {role for role in list_roles if role == "list"})
+    ):
+        item_elements = sum(
+            len(re.findall(rf"<{re.escape(element)}\b", window)) for element in list_items
+        )
+        item_roles = sum(
+            len(re.findall(rf"\brole\s*=\s*['\"]{re.escape(role)}['\"]", window))
+            for role in list_roles if role == "listitem"
+        )
+        if item_elements + item_roles >= 2 or (
+            ".map(" in window and item_elements + item_roles >= 1
+        ):
+            return True
+
+    # A semantic list row owns its internal item gap; cross-axis alignment is mandatory.
+    if aligned and flex and (
+        has_open_element(line, list_items)
+        or has_role(line, {role for role in list_roles if role == "listitem"})
+    ):
+        return True
+
+    # layoutSpace rule 5:only gap-2, horizontal grouped fields, and at least two nearby field
+    # controls. A normal div containing unrelated sections/cards cannot satisfy this lane.
+    if set(tokens) == {"gap-2"} and flex and not flex_col and (
+        has_open_element(line, field_groups) or has_role(line, field_group_roles)
+    ):
+        field_wrappers = sum(
+            len(re.findall(rf"<{re.escape(element)}\b", window))
+            for element in field_controls if element == "Field"
+        )
+        direct_controls = sum(
+            len(re.findall(rf"<{re.escape(element)}\b", window))
+            for element in field_controls if element != "Field"
+        )
+        if field_wrappers >= 2 or (field_wrappers == 0 and direct_controls >= 2):
+            return True
+
+    return False
+
+
+def countable_markers(content):
+    lines = content.splitlines()
+    result = []
+    for index, line in enumerate(lines):
+        for marker in marker_re.findall(line):
+            if marker == "@layout-space-magic-ok" and (
+                is_canonical_micro_line(lines, index)
+                or is_canonical_micro_line(lines, index + 1)
+            ):
+                continue
+            result.append(marker)
+    return result
+
+
+if mode == "filter-layout-candidates":
+    lines = payload.splitlines()
+    for candidate in candidates.splitlines():
+        if not candidate:
+            continue
+        match = re.match(r"([0-9]+):(.*)", candidate, re.DOTALL)
+        if not match:
+            raise ValueError("layout candidate lacks a line number")
+        index = int(match.group(1)) - 1
+        if not is_canonical_micro_line(lines, index):
+            print(candidate)
+elif mode == "content-markers":
+    print("\n".join(countable_markers(payload)))
+elif mode == "repo-markers":
+    root = os.path.abspath(scan_root)
+    root_stat = os.lstat(root)
+    if not stat.S_ISDIR(root_stat.st_mode) or stat.S_ISLNK(root_stat.st_mode):
+        raise ValueError("repository marker root is unsafe")
+    output = []
+    for current, dirs, files in os.walk(root, followlinks=False):
+        dirs[:] = sorted(
+            name for name in dirs
+            if not os.path.islink(os.path.join(current, name))
+        )
+        for name in sorted(files):
+            if not name.endswith((".ts", ".tsx")):
+                continue
+            path = os.path.join(current, name)
+            entry = os.lstat(path)
+            if not stat.S_ISREG(entry.st_mode) or stat.S_ISLNK(entry.st_mode):
+                continue
+            with open(path, encoding="utf-8", errors="strict") as source:
+                output.extend(countable_markers(source.read()))
+    print("\n".join(output))
+else:
+    raise ValueError(f"unknown micro-geometry scan mode:{mode}")
+PY
+}
+
+governance_filter_canonical_micro_geometry() {
+  governance_micro_geometry_scan filter-layout-candidates "$1" "$2"
+}
+
+governance_countable_escape_markers() {
+  governance_micro_geometry_scan content-markers "$1"
+}
+
+governance_countable_repository_escape_markers() {
+  governance_micro_geometry_scan repo-markers "" "" "$1"
+}

package/ds-canonical/hooks/lib/_overlay_handcraft.sh

@@ -24,11 +24,11 @@ source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
 FILE_PATH=$(jq -r '.tool_input.file_path // empty')
 
 # Scope: tsx files (stories, components, patterns, app, explorations)
-if ! echo "$FILE_PATH" | grep -qE '\.tsx$'; then
+if ! grep -qE '\.tsx$' <<<"$FILE_PATH"; then
   exit 0
 fi
 # Skip spec.md / anatomy stories (different context)
-if echo "$FILE_PATH" | grep -qE '(\.spec\.md$|\.anatomy\.stories\.tsx$|\.principles\.stories\.tsx$)'; then
+if grep -qE '(\.spec\.md$|\.anatomy\.stories\.tsx$|\.principles\.stories\.tsx$)' <<<"$FILE_PATH"; then
   exit 0
 fi
 if [ ! -f "$FILE_PATH" ]; then
@@ -37,7 +37,7 @@ fi
 
 # Pattern: <div className="...px-[var(--layout-space-loose)]...border-(b|t) border-divider...">
 PATTERN='<div className="[^"]*px-\[var\(--layout-space-loose\)\][^"]*border-(b|t) border-divider'
-HITS=$(grep -nE "$PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
+HITS=$(grep -m 5 -nE "$PATTERN" "$FILE_PATH" 2>/dev/null)
 
 if [ -n "$HITS" ]; then
   # filter out lines with allowlist comment
@@ -48,7 +48,7 @@ if [ -n "$HITS" ]; then
     # check current line + previous line for allowlist
     prev_line=$(sed -n "$((line_num-1))p" "$FILE_PATH" 2>/dev/null)
     cur_line=$(sed -n "${line_num}p" "$FILE_PATH" 2>/dev/null)
-    if echo "$prev_line $cur_line" | grep -q 'overlay-handcraft-allow:'; then
+    if grep -q 'overlay-handcraft-allow:' <<<"$prev_line $cur_line"; then
       continue
     fi
     FILTERED="${FILTERED}${line}\n"
@@ -63,7 +63,7 @@ fi
 # Pattern:`<div className="...flex...gap-2 px-loose py-1.5 rounded-md hover:bg-neutral-hover">`
 # = 自刻 MenuItem-like row 違反 mindset #2(MenuItem primitive 自帶這些 + size canonical + a11y)
 ROW_PATTERN='<div className="[^"]*flex[^"]*gap-[12][^"]*px-\[var\(--layout-space-loose\)\][^"]*hover:bg-neutral-hover[^"]*rounded'
-ROW_HITS=$(grep -nE "$ROW_PATTERN" "$FILE_PATH" 2>/dev/null | head -3)
+ROW_HITS=$(grep -m 3 -nE "$ROW_PATTERN" "$FILE_PATH" 2>/dev/null)
 if [ -n "$ROW_HITS" ] && ! grep -qE 'menu-item-handcraft-allow:' "$FILE_PATH" 2>/dev/null; then
   VIOLATIONS="${VIOLATIONS}\n⚠️ 自刻 row(MenuItem-like)違反 mindset #2:\n${ROW_HITS}\n  → 改用 <MenuItem startIcon={...} endContent={...} disabled={...}>label</MenuItem>\n  Why:MenuItem 自帶 SelectionItem py 公式 + size canonical + a11y(role=option, aria-disabled, aria-selected) + cursor-not-allowed disabled。\n  Escape hatch:加 \`// menu-item-handcraft-allow: <reason>\` 在檔頭。"
 fi
@@ -72,12 +72,22 @@ fi
 # 同 root cause(自刻 SelectionItem 包 Checkbox 而非消費 CheckboxGroup primitive)。
 # 對齊 checkbox.spec.md「群組模式(CheckboxGroup)」canonical line 225:
 #   多選 Checkbox 必包 <CheckboxGroup>(zero-gap canonical + Context 隔離 + a11y group)。
-CB_COUNT=$(grep -c '<Checkbox\b' "$FILE_PATH" 2>/dev/null | head -1 || echo 0)
-CBG_COUNT=$(grep -c '<CheckboxGroup\b' "$FILE_PATH" 2>/dev/null | head -1 || echo 0)
+# 2026-06-11 R2 held-item #11 context-narrow:檔案級 count 對下列合法 context 永久 FP(8 檔噪音實測):
+#   - DataTable / TreeView:row-selection canonical(selection column / tree 多選 = row anatomy,非 form 群組)
+#   - Checkbox / SelectionControl:selection primitive 自家 stories 示範 raw usage(同 Check 4 menu-primitive skip idiom)
+#   - Field:單顆 Checkbox 包 <Field> = field-controls Family 4 canonical(field.stories.tsx 每顆獨立非群組)
+#   - patterns/element-anatomy:row anatomy SSOT reference 本身
+# 消費者 / 其他 DS 元件自刻多選 list 仍照抓(原 bug class 保護不變)。
+# 2026-06-11 R2 Phase B(codex b3 抓縫):原 DataTable/TreeView 整目錄 skip 會放走目錄內
+# 其他檔(如 filter-panel)的真違規 — 縮到 row-selection canonical 真實檔名 + 自家 primitive。
+IS_CB_LEGIT_CONTEXT=$(grep -cE '(components/DataTable/data-table\.tsx|components/TreeView/tree-view\.tsx|components/(Checkbox|SelectionControl|Field)/|patterns/element-anatomy/)' <<<"$FILE_PATH")
+IS_CB_LEGIT_CONTEXT=${IS_CB_LEGIT_CONTEXT:-0}
+CB_COUNT=$(grep -c '<Checkbox\b' "$FILE_PATH" 2>/dev/null || true)
+CBG_COUNT=$(grep -c '<CheckboxGroup\b' "$FILE_PATH" 2>/dev/null || true)
 CB_COUNT=${CB_COUNT:-0}
 CBG_COUNT=${CBG_COUNT:-0}
-if [ "$CB_COUNT" -ge 2 ] && [ "$CBG_COUNT" -eq 0 ]; then
-  CB_HITS=$(grep -nE '<Checkbox\b' "$FILE_PATH" 2>/dev/null | head -3)
+if [ "$CB_COUNT" -ge 2 ] && [ "$CBG_COUNT" -eq 0 ] && [ "$IS_CB_LEGIT_CONTEXT" -eq 0 ]; then
+  CB_HITS=$(grep -m 3 -nE '<Checkbox\b' "$FILE_PATH" 2>/dev/null)
   # allowlist: same-line or prev-line has // checkbox-group-allow:
   if ! grep -qE 'checkbox-group-allow:' "$FILE_PATH" 2>/dev/null; then
     VIOLATIONS="${VIOLATIONS}\n⚠️ 多個 raw <Checkbox> 未包 <CheckboxGroup>(${CB_COUNT} hits)— 違反 checkbox.spec.md 群組 canonical:\n${CB_HITS}\n  → 改用 <CheckboxGroup><Checkbox label=\"...\" />...</CheckboxGroup>\n  Why:CheckboxGroup 自帶 zero-gap canonical(SelectionItem py 公式)+ Context 隔離 fieldCtx + a11y group;raw 自刻 wrapper 違 mindset #2。\n  Escape hatch:加 \`// checkbox-group-allow: <reason>\` 在檔頭。"
@@ -87,13 +97,24 @@ fi
 # ── Check 5: Same-row consistency 違反(同 row 混 ItemInlineActionButton + Button iconOnly)──
 # 對齊 inline-action.spec.md L152「Same-row consistency rule:同 action row 所有 icon action 必同一類」。
 # Pattern:同檔出現 <ItemInlineActionButton 與 <Button.*iconOnly,且非 menu primitive impl(menu 內 Button 為合法 chrome)。
-HAS_INLINE=$(grep -c '<ItemInlineActionButton' "$FILE_PATH" 2>/dev/null | head -1)
-HAS_BTN_ICON=$(grep -cE '<Button[^>]*iconOnly' "$FILE_PATH" 2>/dev/null | head -1)
+# 2026-06-11 R2 held-item #11 context-narrow(檔案級 co-occurrence 對合法 chrome-vs-row 永久 FP):
+#   (1) strip 純註解行再 count(對齊 check_story_invariants.sh R9 idiom;file-viewer.tsx 註解 cite
+#       `<Button iconOnly dismiss />` 字樣誤觸;不 strip 行內 // 避免 mutilate https:// URL)
+#   (2) 排除 dismiss Button:chrome corner close X = dismiss canonical(inline-action.spec.md
+#       「Dismiss canonical — X close only」+ button.spec.md「Dismiss 視覺類」),跟 row inline action
+#       永遠不同 row → 非 same-row mixing(把 hook 自述 escape note「chrome corner 跟 row 不同 row 可分開」codify 進 detection)
+#   (3) patterns/element-anatomy/ skip:anatomy SSOT 本身示範兩類對照(含刻意 ❌ mixed 教學例)
+# 真 same-row mixing(非 dismiss 的 iconOnly Button 與 InlineAction 同檔)仍照抓,保護不削弱。
+IS_ANATOMY_SSOT=$(grep -c 'patterns/element-anatomy/' <<<"$FILE_PATH")
+IS_ANATOMY_SSOT=${IS_ANATOMY_SSOT:-0}
+OH5_SRC=$(grep -vE '^[[:space:]]*(//|\*|/\*|\{/\*)' "$FILE_PATH" 2>/dev/null)
+HAS_INLINE=$(grep -c '<ItemInlineActionButton' <<<"$OH5_SRC" 2>/dev/null)
+HAS_BTN_ICON=$(grep -E '<Button[^>]*iconOnly' <<<"$OH5_SRC" 2>/dev/null | grep -cv 'dismiss')
 HAS_INLINE=${HAS_INLINE:-0}
 HAS_BTN_ICON=${HAS_BTN_ICON:-0}
-IS_MENU_PRIMITIVE2=$(echo "$FILE_PATH" | grep -cE '(DropdownMenu|SelectMenu|Combobox|Menu)/.*\.tsx$' | head -1)
+IS_MENU_PRIMITIVE2=$(grep -cE '(DropdownMenu|SelectMenu|Combobox|Menu)/.*\.tsx$' <<<"$FILE_PATH")
 IS_MENU_PRIMITIVE2=${IS_MENU_PRIMITIVE2:-0}
-if [ "$HAS_INLINE" -ge 1 ] && [ "$HAS_BTN_ICON" -ge 1 ] && [ "$IS_MENU_PRIMITIVE2" -eq 0 ]; then
+if [ "$HAS_INLINE" -ge 1 ] && [ "$HAS_BTN_ICON" -ge 1 ] && [ "$IS_MENU_PRIMITIVE2" -eq 0 ] && [ "$IS_ANATOMY_SSOT" -eq 0 ]; then
   if ! grep -qE 'same-row-mixed-allow:' "$FILE_PATH" 2>/dev/null; then
     VIOLATIONS="${VIOLATIONS}\n⚠️ 同檔混用 <ItemInlineActionButton>(${HAS_INLINE}) + <Button.*iconOnly>(${HAS_BTN_ICON}):\n  → 違反 inline-action.spec.md L152 Same-row consistency rule(同 row icon action 必同一類)。\n  → Box size 不一致(InlineAction 16+18 vs Button text sm 28)會 gap 斷裂。\n  → 修法:row 內 icon action 全 ItemInlineActionButton(對齊 size=md / 16+18 hover bg)。\n  Escape hatch:加 \`// same-row-mixed-allow: <reason>\` 在檔頭(若 chrome corner action group 跟 row 不同 row,可分開)。"
   fi
@@ -103,12 +124,12 @@ fi
 # Pattern:同檔出現 <PopoverHeader> 且 <MenuItem>(不是 DropdownMenu / SelectMenu primitive 自身)
 # → panel-style popover 不該硬塞 menu specialization。MenuItem 預設 `px-3` 不對齊 panel chrome
 # `loose`,且 startIcon 色彩無 override → 該用視覺 primitive(ItemPrefix/ItemLabel/ItemSuffix)自組。
-HAS_POP_HEADER=$(grep -c '<PopoverHeader' "$FILE_PATH" 2>/dev/null | head -1)
-HAS_MENU_ITEM=$(grep -c '<MenuItem\b' "$FILE_PATH" 2>/dev/null | head -1)
+HAS_POP_HEADER=$(grep -c '<PopoverHeader' "$FILE_PATH" 2>/dev/null)
+HAS_MENU_ITEM=$(grep -c '<MenuItem\b' "$FILE_PATH" 2>/dev/null)
 HAS_POP_HEADER=${HAS_POP_HEADER:-0}
 HAS_MENU_ITEM=${HAS_MENU_ITEM:-0}
 # Skip:DropdownMenu/SelectMenu primitive impl 本身(他們 import MenuItem 是合法 menu-style)
-IS_MENU_PRIMITIVE=$(echo "$FILE_PATH" | grep -cE '(DropdownMenu|SelectMenu|Combobox)/.*\.tsx$' | head -1)
+IS_MENU_PRIMITIVE=$(grep -cE '(DropdownMenu|SelectMenu|Combobox)/.*\.tsx$' <<<"$FILE_PATH")
 IS_MENU_PRIMITIVE=${IS_MENU_PRIMITIVE:-0}
 if [ "$HAS_POP_HEADER" -ge 1 ] && [ "$HAS_MENU_ITEM" -ge 1 ] && [ "$IS_MENU_PRIMITIVE" -eq 0 ]; then
   if ! grep -qE 'panel-menuitem-allow:' "$FILE_PATH" 2>/dev/null; then
@@ -123,19 +144,17 @@ fi
 # 防止未來 silent re-introduction:DialogBody / SheetBody / PopoverBody tsx 內出現
 # `flush?: boolean` / `flush = false` / `naked?: boolean` / `bare?: boolean` / `noPadding?: boolean` 同類 boolean 變體。
 # Scope:`components/(Dialog|Sheet|Popover)/*.tsx`(非 stories)。
-IS_OVERLAY_BODY_TSX=$(echo "$FILE_PATH" | grep -cE 'components/(Dialog|Sheet|Popover)/[^/]+\.tsx$' | head -1)
+IS_OVERLAY_BODY_TSX=$(grep -cE 'components/(Dialog|Sheet|Popover)/[^/]+\.tsx$' <<<"$FILE_PATH")
 IS_OVERLAY_BODY_TSX=${IS_OVERLAY_BODY_TSX:-0}
-if [ "$IS_OVERLAY_BODY_TSX" -ge 1 ] && ! echo "$FILE_PATH" | grep -qE '\.stories\.tsx$'; then
+if [ "$IS_OVERLAY_BODY_TSX" -ge 1 ] && ! grep -qE '\.stories\.tsx$' <<<"$FILE_PATH"; then
   STRIPPED_PROPS_PATTERN='(flush|naked|bare|stripped|unpadded|noPadding|paddingless)\??:\s*boolean'
-  STRIPPED_HITS=$(grep -nE "$STRIPPED_PROPS_PATTERN" "$FILE_PATH" 2>/dev/null | head -3)
+  STRIPPED_HITS=$(grep -m 3 -nE "$STRIPPED_PROPS_PATTERN" "$FILE_PATH" 2>/dev/null)
   if [ -n "$STRIPPED_HITS" ] && ! grep -qE 'overlay-body-stripped-variant-allow:' "$FILE_PATH" 2>/dev/null; then
     VIOLATIONS="${VIOLATIONS}\n⚠️ Overlay body 重新引入 stripped-padding boolean variant(2026-05-01 已移除):\n${STRIPPED_HITS}\n  → list-as-region in overlay body canonical = consumer 用 className override:\n    <DialogBody className=\"!px-0 !pt-0 !pb-0\"><div className=\"py-2\">{items}</div></DialogBody>\n  Why removed:Material/Atlassian/Mantine/shadcn 主流不做 universal LayoutBody flush;\n  variant 不解決底層脆弱(加 1 row search/banner 就破功)+ 把 1 surface decision 拆兩 API。\n  詳 overlay-surface.spec.md「List-as-region in overlay body」+ memory feedback_layout_v6_canonical.md\n  Escape hatch:加 \`// overlay-body-stripped-variant-allow: <reason>\` 在檔頭(必含 ≥3 家世界級對照 + multi-row hold 保證)。"
   fi
 fi
 
 if [ -n "$VIOLATIONS" ]; then
-  ESCAPED=$(printf "%b" "$VIOLATIONS" | jq -Rs .)
-  cat <<EOJSON
-{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Primitive consumption 檢查發現違規:${ESCAPED}"}}
-EOJSON
+  CTX=$(printf 'Primitive consumption 檢查發現違規:%b' "$VIOLATIONS")
+  jq -n --arg ctx "$CTX" '{governanceContext:{hookEventName:"PostToolUse",message:$ctx}}'
 fi

package/ds-canonical/hooks/lib/_person_data_richness.sh

@@ -12,7 +12,7 @@ source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
 
 FILE_PATH=$(jq -r '.tool_input.file_path // empty')
 
-if ! echo "$FILE_PATH" | grep -qE '\.(tsx|stories\.tsx)$'; then
+if ! grep -qE '\.(tsx|stories\.tsx)$' <<<"$FILE_PATH"; then
   exit 0
 fi
 if [ ! -f "$FILE_PATH" ]; then
@@ -20,21 +20,21 @@ if [ ! -f "$FILE_PATH" ]; then
 fi
 
 # Skip the canonical sources(NameCard / Avatar / person-display 自身)
-if echo "$FILE_PATH" | grep -qE '(NameCard|Avatar|person-display|avatar\.spec)'; then
+if grep -qE '(NameCard|Avatar|person-display|avatar\.spec)' <<<"$FILE_PATH"; then
   exit 0
 fi
 
 # Match `{ name: '...', avatarUrl?: '...' }` with no other PersonData fields on same line.
 # A "rich" PersonData usually spans multiple lines OR has description/status/statusMessage/fields.
 # Heuristic: single-line literal with only name + avatarUrl(no other PersonData props on same line).
-SPARSE_HITS=$(grep -nE "\{\s*name:\s*['\"][^'\"]+['\"],\s*avatar(Url)?:\s*['\"][^'\"]+['\"]\s*\}" "$FILE_PATH" 2>/dev/null | head -5)
+SPARSE_HITS=$(grep -m 5 -nE "\{\s*name:\s*['\"][^'\"]+['\"],\s*avatar(Url)?:\s*['\"][^'\"]+['\"]\s*\}" "$FILE_PATH" 2>/dev/null)
 
 if [ -n "$SPARSE_HITS" ]; then
   ADDITIONAL_CONTEXT=$(printf 'Sparse PersonData literal(違反 name-card.spec「DS-wide 預設展示一致 canonical」):\n%s\n  → 補上 description / status / statusMessage / fields 4 sections,讓 NameCard hover 展示資訊量一致' "$SPARSE_HITS")
   jq -n --arg ctx "$ADDITIONAL_CONTEXT" '{
-    hookSpecificOutput: {
+    governanceContext: {
       hookEventName: "PostToolUse",
-      additionalContext: $ctx
+      message: $ctx
     }
   }'
 fi