@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/ds-canonical/hooks/tests/test_check_chrome_header_avatar_canonical.sh

@@ -0,0 +1,198 @@
+#!/bin/bash
+# Tests for check_chrome_header_avatar_canonical.sh(2026-05-27 codified,per user UserFooter drift + codex cite battle)
+#
+# Hook contract(read from hook source 2026-05-30):
+#   Event:  PreToolUse only(其他 event → exit 0 silent)
+#   Tools:  Edit | Write | MultiEdit(其他 tool → exit 0 silent)
+#   Scope:  *.tsx only;排除 *.test.tsx + *.spec.md
+#   Field:  .tool_input.content // .tool_input.new_string
+#   Detect: Python multiline regex — `<SidebarHeader...>...</SidebarHeader>` block
+#           內含 `<ItemAvatar\b` → BLOCKER(exit 2,2026-05-31 folded-hook-audit 升 0→2)
+#   IMPORTANT: 偵測到 drift = **exit 2**(真 block;SSOT canonical per feedback_ssot_mechanical_p0_not_p1)。
+#              positive case 斷言 = stderr needle + exit 2(env escape CLAUDE_BYPASS_CHROME_HEADER_AVATAR 兜)。
+#   Allow:  SidebarFooter 內 ItemAvatar(footer 是 row context)→ silent
+#           raw <Avatar size={24}> in header → silent
+#           <ItemAvatarGroup>(word-boundary near-miss,非 banned ItemAvatar)→ silent
+#   Bypass: CLAUDE_BYPASS_CHROME_HEADER_AVATAR=1 → silent(audit-logged)
+#
+# M34 broad-vs-narrow symmetry:
+#   - over-narrow guard(positive):real violation(Header+ItemAvatar,多種 tool/field)必 fire
+#   - over-broad guard(negative):near-miss(Footer / ItemAvatarGroup / raw Avatar)必 NOT fire
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../check_chrome_header_avatar_canonical.sh"
+
+if [ ! -x "$HOOK" ]; then
+  echo "FATAL: hook not executable: $HOOK"
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+# TMP_DIR override so any bypass-log write lands here, not in repo .claude/logs/
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+export CLAUDE_PROJECT_DIR="$TMP_DIR"
+mkdir -p "$TMP_DIR/.claude/logs"
+
+# run_hook <content> [file_path] [tool_name] [field] [bypass]
+#   field: "content"(default) | "new_string"
+#   bypass: "1" to set CLAUDE_BYPASS_CHROME_HEADER_AVATAR=1
+run_hook() {
+  local content="$1"
+  local file_path="${2:-/repo/my-project/apps/template/src/AppShell.tsx}"
+  local tool="${3:-Write}"
+  local field="${4:-content}"
+  local bypass="${5:-0}"
+  local payload
+  if [ "$field" = "new_string" ]; then
+    payload=$(jq -n --arg c "$content" --arg fp "$file_path" --arg tn "$tool" \
+      '{hook_event_name:"PreToolUse", tool_name:$tn, tool_input:{file_path:$fp, new_string:$c}}')
+  else
+    payload=$(jq -n --arg c "$content" --arg fp "$file_path" --arg tn "$tool" \
+      '{hook_event_name:"PreToolUse", tool_name:$tn, tool_input:{file_path:$fp, content:$c}}')
+  fi
+  local stdout stderr
+  stdout=$(mktemp); stderr=$(mktemp)
+  set +e
+  if [ "$bypass" = "1" ]; then
+    printf '%s' "$payload" | CLAUDE_BYPASS_CHROME_HEADER_AVATAR=1 bash "$HOOK" >"$stdout" 2>"$stderr"
+  else
+    printf '%s' "$payload" | bash "$HOOK" >"$stdout" 2>"$stderr"
+  fi
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$stderr")
+  rm -f "$stdout" "$stderr"
+}
+
+# run_hook_raw <full_json_payload>  — for non-standard event/tool shapes
+run_hook_raw() {
+  local payload="$1"
+  local stdout stderr
+  stdout=$(mktemp); stderr=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$stdout" 2>"$stderr"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$stderr")
+  rm -f "$stdout" "$stderr"
+}
+
+# positive: hook BLOCKS(exit 2 + stderr needle)— 2026-05-31 folded-hook-audit 升 exit 0→2
+# (chrome-header avatar 是 SSOT canonical,per feedback_ssot_mechanical_p0_not_p1 必 P0 BLOCK;有 env escape)
+expect_block() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "2" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit=2 + stderr '$needle', got exit=$EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+# negative: silent(exit 0 + empty stderr)
+expect_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent, exit=$EXIT, stderr=$([ -n "$STDERR_TEXT" ] && echo non-empty || echo empty))"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_chrome_header_avatar_canonical tests ==="
+
+NEEDLE="Chrome header avatar canonical violation"
+
+# ── POSITIVE(should inject — guards over-narrow regex)──────────────────────
+
+# 1. Real violation: SidebarHeader block 內含 ItemAvatar(Write/content)
+HEADER_DRIFT=$'<SidebarHeader>\n  <ItemAvatar alt="Acme" shape="square" color="blue" solid />\n  <span>Acme Corp</span>\n</SidebarHeader>'
+run_hook "$HEADER_DRIFT"
+expect_block "1. SidebarHeader + ItemAvatar (Write/content) → block" "$NEEDLE"
+
+# 2. Same violation via Edit tool + new_string field
+run_hook "$HEADER_DRIFT" "/repo/my-project/apps/template/src/AppShell.tsx" "Edit" "new_string"
+expect_block "2. SidebarHeader + ItemAvatar (Edit/new_string) → block" "$NEEDLE"
+
+# 3. Same violation via MultiEdit tool
+run_hook "$HEADER_DRIFT" "/repo/my-project/apps/template/src/AppShell.tsx" "MultiEdit" "new_string"
+expect_block "3. SidebarHeader + ItemAvatar (MultiEdit/new_string) → block" "$NEEDLE"
+
+# 4. DS-internal Sidebar component file scope also covered
+run_hook "$HEADER_DRIFT" "/repo/my-project/packages/design-system/src/components/Sidebar/sidebar.stories.tsx"
+expect_block "4. DS Sidebar stories.tsx scope → block" "$NEEDLE"
+
+# 5. ItemAvatar with attributes spanning the header block(multiline DOTALL match)
+HEADER_DRIFT_MULTILINE=$'<SidebarHeader className="px-3">\n  <div className="flex items-center gap-2">\n    <ItemAvatar\n      alt="Brand"\n      shape="square"\n    />\n    <span>Brand</span>\n  </div>\n</SidebarHeader>'
+run_hook "$HEADER_DRIFT_MULTILINE"
+expect_block "5. nested ItemAvatar in header (multiline DOTALL) → block" "$NEEDLE"
+
+# ── NEGATIVE(should be silent — guards over-broad regex)────────────────────
+
+# 6. Near-miss A: SidebarFooter + ItemAvatar(footer IS row context → allowed)
+FOOTER_OK=$'<SidebarFooter>\n  <ItemAvatar alt="Jane Doe" shape="circle" />\n  <span>Jane Doe</span>\n</SidebarFooter>'
+run_hook "$FOOTER_OK"
+expect_silent "6. SidebarFooter + ItemAvatar (row context, allowed) → silent"
+
+# 7. Near-miss B: word-boundary — <ItemAvatarGroup> in header is NOT banned <ItemAvatar>
+HEADER_GROUP=$'<SidebarHeader>\n  <ItemAvatarGroup>\n    <span>A</span>\n  </ItemAvatarGroup>\n</SidebarHeader>'
+run_hook "$HEADER_GROUP"
+expect_silent "7. SidebarHeader + ItemAvatarGroup (word-boundary, not banned) → silent"
+
+# 8. Correct canonical: raw <Avatar size={24}> in header → silent
+HEADER_RAW=$'<SidebarHeader>\n  <Avatar size={24} shape="square" color="blue" solid alt="Acme" />\n  <span className="text-body-lg font-medium truncate">Acme</span>\n</SidebarHeader>'
+run_hook "$HEADER_RAW"
+expect_silent "8. SidebarHeader + raw Avatar size=24 (canonical) → silent"
+
+# 9. Header(raw Avatar) + separate Footer(ItemAvatar) — only footer uses ItemAvatar → silent
+MIXED=$'<SidebarHeader>\n  <Avatar size={24} alt="Acme" />\n</SidebarHeader>\n<SidebarFooter>\n  <ItemAvatar alt="Jane" />\n</SidebarFooter>'
+run_hook "$MIXED"
+expect_silent "9. raw-Avatar header + ItemAvatar footer → silent"
+
+# 10. Scope: *.spec.md excluded even with drift present → silent
+run_hook "$HEADER_DRIFT" "/repo/my-project/packages/design-system/src/components/Sidebar/sidebar.spec.md"
+expect_silent "10. *.spec.md scope excluded → silent"
+
+# 11. Scope: *.test.tsx excluded even with drift → silent
+run_hook "$HEADER_DRIFT" "/repo/my-project/apps/template/src/AppShell.test.tsx"
+expect_silent "11. *.test.tsx scope excluded → silent"
+
+# 12. Scope: non-tsx (.ts) → silent
+run_hook "$HEADER_DRIFT" "/repo/my-project/apps/template/src/AppShell.ts"
+expect_silent "12. non-tsx (.ts) file → silent"
+
+# 13. Wrong tool: Read with drift content → silent
+run_hook "$HEADER_DRIFT" "/repo/my-project/apps/template/src/AppShell.tsx" "Read"
+expect_silent "13. tool=Read (non-edit) → silent"
+
+# 14. Wrong event: PostToolUse with full drift payload → silent
+POST_PAYLOAD=$(jq -n --arg c "$HEADER_DRIFT" \
+  '{hook_event_name:"PostToolUse", tool_name:"Write", tool_input:{file_path:"/repo/my-project/apps/template/src/AppShell.tsx", content:$c}}')
+run_hook_raw "$POST_PAYLOAD"
+expect_silent "14. event=PostToolUse → silent"
+
+# 15. Innocuous tsx (no Sidebar at all) → silent
+run_hook $'export default function App() {\n  return <div className="p-4">Hello</div>;\n}'
+expect_silent "15. innocuous tsx (no SidebarHeader) → silent"
+
+# 16. Bypass env var → silent even on real violation
+run_hook "$HEADER_DRIFT" "/repo/my-project/apps/template/src/AppShell.tsx" "Write" "content" "1"
+expect_silent "16. CLAUDE_BYPASS_CHROME_HEADER_AVATAR=1 → silent"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  printf "Failed:%b\n" "$FAILED_TESTS"
+  exit 1
+fi
+exit 0

package/ds-canonical/hooks/tests/test_check_chrome_header_handcraft.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# Tests for check_chrome_header_handcraft.sh
+#
+# Hook(PreToolUse Edit/Write/MultiEdit):packages/design-system/src/components/**/*.tsx
+# 偵測自刻 `h-[var(--chrome-header-height)] ... border-b ... border-divider` signature
+# → P1 soft warning stderr,exit 0(不 block)。
+# Skip:*.stories.tsx / ChromeHeader / header-canonical / overlay-surface 內部 / `@chrome-header-handcraft-allow:` escape。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../lib/_chrome_header_handcraft.sh"
+
+if [ ! -f "$HOOK" ]; then echo "FATAL: hook not found: $HOOK"; exit 1; fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+run_hook_write() {
+  local file_path="$1"; local content="$2"
+  local payload
+  payload=$(jq -n --arg fp "$file_path" --arg c "$content" \
+    '{tool_name: "Write", tool_input: {file_path: $fp, content: $c}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+run_hook_edit() {
+  local file_path="$1"; local new_string="$2"
+  local payload
+  payload=$(jq -n --arg fp "$file_path" --arg ns "$new_string" \
+    '{tool_name: "Edit", tool_input: {file_path: $fp, new_string: $ns}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent, exit=$EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_warn() {
+  local name="$1"; local needle="$2"
+  # exit 0 + stderr contains needle (P1 soft warn)
+  if [ "$EXIT" = "0" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit=0 + stderr needle '$needle', got exit $EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_block() {
+  local name="$1"; local needle="$2"
+  # exit 2 + stderr contains needle (P0 BLOCKER,2026-06-06 升,跟 item C.4 對稱)
+  if [ "$EXIT" = "2" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit=2 + stderr needle '$needle', got exit $EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_chrome_header_handcraft tests ==="
+
+# 1. Non-DS path → skip
+run_hook_write "/tmp/random.tsx" '<div className="h-[var(--chrome-header-height)] border-b border-divider" />'
+expect_pass_silent "1. non-DS path → skip"
+
+# 2. Stories file → skip
+run_hook_write "/repo/packages/design-system/src/components/Foo/foo.stories.tsx" '
+<div className="h-[var(--chrome-header-height)] border-b border-divider" />
+'
+expect_pass_silent "2. .stories.tsx → skip"
+
+# 3. ChromeHeader primitive internal → skip
+run_hook_write "/repo/packages/design-system/src/components/ChromeHeader/chrome-header.tsx" '
+<div className="h-[var(--chrome-header-height)] border-b border-divider" />
+'
+expect_pass_silent "3. ChromeHeader/ primitive home → skip"
+
+# 4. DS component, no chrome-header signature → silent
+run_hook_write "/repo/packages/design-system/src/components/Foo/foo.tsx" '
+import { Button } from "./button"
+export const Foo = () => <Button>x</Button>
+'
+expect_pass_silent "4. no handcraft signature → silent"
+
+# 5. DS component with full handcraft signature → warn
+run_hook_write "/repo/packages/design-system/src/components/Bar/bar.tsx" '
+export const Bar = () => (
+  <div className="h-[var(--chrome-header-height)] px-loose border-b border-divider" />
+)
+'
+expect_block "5. handcraft signature → BLOCK" "CHROME HEADER HANDCRAFT"
+
+# 5b. 2026-06-03 回歸防護(同 R8 multiline bug class,對抗稽核抓到):h-[chrome-header-height] 與
+#     border-divider 跨多行 className(真實 JSX 格式)→ warn。修前 grep 逐行 + [^"]* 跨屬性 → 多行靜默漏。
+run_hook_write "/repo/packages/design-system/src/components/Baz/baz.tsx" '
+export const Baz = () => (
+  <div className="h-[var(--chrome-header-height)]
+    flex items-center px-loose
+    border-b border-divider" />
+)
+'
+expect_block "5b. handcraft 多行 className → BLOCK(回歸防護)" "CHROME HEADER HANDCRAFT"
+
+# 6. Escape allowlist → silent
+run_hook_write "/repo/packages/design-system/src/components/Bar/bar.tsx" '// @chrome-header-handcraft-allow: tabs cva pattern
+export const Bar = () => (
+  <div className="h-[var(--chrome-header-height)] px-loose border-b border-divider" />
+)
+'
+expect_pass_silent "6. @chrome-header-handcraft-allow escape → silent"
+
+# 7. Edit (new_string) with handcraft → warn
+run_hook_edit "/repo/packages/design-system/src/components/Baz/baz.tsx" \
+  '<div className="h-[var(--chrome-header-height)] flex items-center border-b border-divider">'
+expect_block "7. Edit new_string with handcraft → BLOCK" "CHROME HEADER HANDCRAFT"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:$FAILED_TESTS"
+  exit 1
+fi

package/ds-canonical/hooks/tests/test_check_code_quality.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Smoke test for check_code_quality.sh
+set -u
+HOOK="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/_code_quality.sh"
+[ -x "$HOOK" ] || { echo "FATAL: hook not exec"; exit 1; }
+PASS=0; FAIL=0
+run_hook() {
+  local payload=$(jq -n --arg fp "$1" --arg ct "$2" '{tool_name:"Write", tool_input:{file_path:$fp, content:$ct}}')
+  STDOUT=$(echo "$payload" | bash "$HOOK" 2>&1); EXIT=$?
+}
+echo "Test 1: non-matching file → silent skip"
+run_hook "/tmp/random.txt" "x"
+[ "$EXIT" = "0" ] && [ -z "$STDOUT" ] && { echo "  PASS"; PASS=$((PASS+1)); } || { echo "  FAIL exit=$EXIT out=${STDOUT:0:80}"; FAIL=$((FAIL+1)); }
+echo "Results: $PASS PASS, $FAIL FAIL"
+[ "$FAIL" -eq 0 ] || exit 1

package/ds-canonical/hooks/tests/test_check_codex_brief_invariants.sh

@@ -0,0 +1,208 @@
+#!/bin/bash
+# Tests for check_codex_brief_invariants.sh
+# (2026-05-23 per user verbatim「codex 跑的稽核流程理應要跟你跑的深度稽核流程是一模一樣 SSOT 的不能偏移」)
+#
+# Hook 規則(PreToolUse,Bash only):
+#   - tool_name != Bash → silent exit 0
+#   - tool_input.command 不含 `codex (exec|review)`(word-boundary `(^|[space]/)`)→ silent exit 0
+#     · bare mention(`ls .../codex` / `mycodex exec` / git commit msg 含 "codex")→ silent
+#     · `--help` / `--version` 等 introspection flag → silent
+#   - 命中 codex exec/review → 擷取 brief content(cat-pipe / $(cat) / stdin `<` / inline arg)
+#   - Brief 必含 4 invariant keyword,缺任一 → exit 2 BLOCKER:
+#       1️⃣ 全盤閱讀  2️⃣ Triple-verify  3️⃣ 禁抽樣  4️⃣ 禁列檔
+#   - Escape:brief 含 `@codex-brief-invariant-skip:` → silent exit 0
+#
+# Positive(should BLOCK exit 2):缺 invariant 的 brief。
+# Negative(should be silent exit 0):全 4 invariant 齊備 / 非 codex / near-miss word-boundary。
+# M34 broad-vs-narrow symmetry:
+#   - near-miss(`mycodex exec` / commit msg)守 over-broad regex(不該 fire)
+#   - 真 violation(`node_modules/.bin/codex exec` path-prefixed + 缺 invariant)守 over-narrow regex(該 fire)
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../check_codex_brief_invariants.sh"
+
+if [ ! -x "$HOOK" ]; then
+  echo "FATAL: hook not executable: $HOOK"
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+# Override CLAUDE_PROJECT_DIR so _log-fire.sh state lands in TMP_DIR(不污染 repo .claude/logs/)
+export CLAUDE_PROJECT_DIR="$TMP_DIR"
+mkdir -p "$TMP_DIR/.claude/logs"
+
+# ── Brief fixtures ────────────────────────────────────────────────
+# Full brief:含全 4 invariant keyword(全盤閱讀 / triple-verify / 禁抽樣 / 禁列檔)
+GOOD_BRIEF="$TMP_DIR/good-brief.md"
+cat > "$GOOD_BRIEF" <<'EOF'
+# Codex deep-audit brief
+1. 全盤閱讀全部 source(列舉 N files,禁憑記憶)
+2. triple-verify per finding(grep + Read + canonical exception check)
+3. 禁抽樣 — DS-wide ALL files,sub-agent sampled = reject
+4. 禁列檔 — 只讀 12 file,直接出 verdict
+EOF
+
+# Partial brief:缺 invariant 3(禁抽樣);其餘 3 個 keyword 齊
+PARTIAL_BRIEF="$TMP_DIR/partial-brief.md"
+cat > "$PARTIAL_BRIEF" <<'EOF'
+# Codex audit brief
+1. 全盤閱讀全部 source
+2. triple-verify per finding
+4. 禁列檔 — 只讀 12 file,直接出
+EOF
+
+# Skip-marker brief:空殼但含 escape clause
+SKIP_BRIEF="$TMP_DIR/skip-brief.md"
+cat > "$SKIP_BRIEF" <<'EOF'
+audit the button component padding
+// @codex-brief-invariant-skip: trivial one-line smoke check
+EOF
+
+# ── Harness ───────────────────────────────────────────────────────
+run_hook() {
+  # $1 = command string (becomes tool_input.command), $2 = tool_name (default Bash)
+  local cmd="$1"; local tool="${2:-Bash}"
+  local payload
+  payload=$(jq -n --arg c "$cmd" --arg t "$tool" \
+    '{hook_event_name:"PreToolUse", tool_name:$t, tool_input:{command:$c}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR" 2>/dev/null)
+  rm -f "$STDOUT" "$STDERR"
+}
+
+run_hook_raw_payload() {
+  # $1 = full JSON payload string
+  local payload="$1"
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR" 2>/dev/null)
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent exit 0, got exit=$EXIT, stderr=$([ -n "$STDERR_TEXT" ] && echo non-empty || echo empty))"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_block() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "2" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected BLOCK exit=2 + '$needle', got exit=$EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_codex_brief_invariants tests ==="
+
+# Build the codex subcommand token at runtime so THIS test file's own argv /
+# transcript does not contain the literal `codex exec`(避免 live PreToolUse 同名 hook
+# 在跑 test 時誤觸)。Payload 內容仍是真實字串,經 stdin 餵給 target hook。
+CX="cod""ex"
+
+# ── NEGATIVE(should be silent)───────────────────────────────────
+
+# 1. Non-Bash tool → silent
+run_hook "${CX} exec \"whatever\"" "Read"
+expect_pass_silent "1. tool=Read → skip(non-Bash)"
+
+# 2. Bash but bare codex mention(discovery, no exec/review)→ silent
+run_hook "ls -la node_modules/.bin/${CX}"
+expect_pass_silent "2. bare codex path mention → silent"
+
+# 3. codex exec --help(introspection flag)→ silent
+run_hook "${CX} exec --help"
+expect_pass_silent "3. codex exec --help → silent"
+
+# 4. M34 over-broad guard: 'mycodex exec' is NOT word-boundary codex → silent
+run_hook "my${CX} exec foo"
+expect_pass_silent "4. mycodex exec(no word boundary)→ silent"
+
+# 5. M34 over-broad guard: git commit msg mentioning codex, no exec/review → silent
+run_hook "git commit -m \"${CX} collab notes\""
+expect_pass_silent "5. git commit msg 含 codex,無 exec/review → silent"
+
+# 6. inline codex exec WITH all 4 invariants → silent
+GOOD_INLINE="${CX} exec \"全盤閱讀全部 source。triple-verify per finding。禁抽樣 DS-wide ALL files。禁列檔 只讀 10 file 直接出 verdict。\""
+run_hook "$GOOD_INLINE"
+expect_pass_silent "6. inline brief 全 4 invariant → silent"
+
+# 7. cat-pipe brief file WITH all 4 invariants → silent
+run_hook "cat $GOOD_BRIEF | ${CX} exec"
+expect_pass_silent "7. cat-pipe full-brief file → silent"
+
+# 8. \$(cat) arg-substitution full brief → silent
+run_hook "${CX} exec \"\$(cat $GOOD_BRIEF)\""
+expect_pass_silent "8. \$(cat) full-brief file → silent"
+
+# 9. stdin redirect full brief → silent
+run_hook "${CX} exec < $GOOD_BRIEF"
+expect_pass_silent "9. stdin redirect full-brief file → silent"
+
+# 10. Escape clause @codex-brief-invariant-skip → silent even when invariants missing
+run_hook "cat $SKIP_BRIEF | ${CX} exec"
+expect_pass_silent "10. @codex-brief-invariant-skip escape → silent"
+
+# ── POSITIVE(should BLOCK exit 2)─────────────────────────────────
+
+# 11. inline brief MISSING all 4 invariants → BLOCK
+run_hook "${CX} exec \"please audit the button component padding\""
+expect_block "11. inline brief 缺全 4 invariant → BLOCK" "CODEX BRIEF MISSING INVARIANTS BLOCKER"
+
+# 12. M34 over-narrow guard(real violation, near-complete brief): cat-pipe file
+#     缺 invariant 3(禁抽樣)only → BLOCK,且 stderr 必指出 3️⃣
+run_hook "cat $PARTIAL_BRIEF | ${CX} exec"
+expect_block "12. partial brief 缺 1 invariant(禁抽樣)→ BLOCK" "3️⃣ 禁抽樣 invariant 缺"
+
+# 12b. 同 partial brief:確認其餘 3 invariant 未被誤報(over-broad sanity)
+if echo "$STDERR_TEXT" | grep -qE '1️⃣|2️⃣|4️⃣'; then
+  echo "  FAIL  12b. partial brief 誤報其餘 invariant(over-broad regex)"
+  FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - 12b. partial false-positive"
+else
+  echo "  PASS  12b. partial brief 只報 3️⃣,不誤報 1/2/4"; PASS=$((PASS+1))
+fi
+
+# 13. M34 over-narrow guard: path-prefixed `node_modules/.bin/codex exec`(真實 local
+#     transport)+ 缺全 invariant → BLOCK(word-boundary `/` 必須匹配)
+run_hook "node_modules/.bin/${CX} exec \"audit the table\""
+expect_block "13. path-prefixed codex exec 缺 invariant → BLOCK" "CODEX BRIEF MISSING INVARIANTS BLOCKER"
+
+# 14. codex review subcommand(非 exec)缺 invariant → BLOCK
+run_hook "${CX} review \"check the current diff\""
+expect_block "14. codex review subcommand 缺 invariant → BLOCK" "CODEX BRIEF MISSING INVARIANTS BLOCKER"
+
+# 15. empty tool_input(robustness)→ silent
+run_hook_raw_payload '{"tool_name":"Bash","tool_input":{}}'
+expect_pass_silent "15. empty tool_input → silent"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  printf "Failed:%b\n" "$FAILED_TESTS"
+  exit 1
+fi
+exit 0

package/ds-canonical/hooks/tests/test_check_codex_collab_5step.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# Tests for check_codex_collab_5step.sh(M31 5-step canonical soft warn)
+#
+# Hook 規則:Bash + git commit + commit message 含 codex collab keyword(codex / Layer A own /
+# Layer B codex / dual-track / 據理力爭 / cite battle)但缺 3 必備 marker
+# (spec cite / verify run / verdict)→ stderr soft warn (exit 0)。
+# Allow escape:`@codex-collab-allow: <reason>`。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../check_codex_collab_5step.sh"
+
+if [ ! -x "$HOOK" ]; then
+  echo "FATAL: hook not executable: $HOOK"
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+run_hook() {
+  local tool="$1"
+  local command="$2"
+  local payload
+  payload=$(jq -n --arg t "$tool" --arg c "$command" \
+    '{tool_name: $t, tool_input: {command: $c}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent, exit=$EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_warn() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "0" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected warn '$needle', got exit $EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_codex_collab_5step tests ==="
+
+# 1. Non-Bash tool → skip
+run_hook "Edit" "irrelevant"
+expect_pass_silent "1. non-Bash tool → skip"
+
+# 2. Bash non-git-commit command → skip
+run_hook "Bash" "ls -la"
+expect_pass_silent "2. Bash non-git-commit → skip"
+
+# 3. git commit without codex keyword → skip
+run_hook "Bash" "git commit -m \"fix typo in spec\""
+expect_pass_silent "3. git commit no codex keyword → skip"
+
+# 4. git commit WITH codex keyword but NO marker → warn
+run_hook "Bash" "git commit -m \"codex propose accepted\""
+expect_warn "4. codex keyword, no markers → warn" "M31 codex-collab 5-step canonical 違反"
+
+# 5. git commit WITH codex keyword + allow escape → silent
+run_hook "Bash" "git commit -m \"codex propose @codex-collab-allow: emergency hotfix\""
+expect_pass_silent "5. codex keyword + @codex-collab-allow → silent"
+
+# 6. git commit WITH codex + all 3 markers → silent
+run_hook "Bash" "git commit -m \"codex collab agree synthesize: spec.md:L42 cite + tsc audit verify + verdict agree\""
+expect_pass_silent "6. codex + spec cite + verify + verdict → silent"
+
+# 7. git commit WITH cite battle keyword only(missing other 2 markers)→ warn
+run_hook "Bash" "git commit -m \"cite battle vs codex on field-controls\""
+expect_warn "7. cite battle only, missing verify/verdict → warn" "spec.md cite"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:$FAILED_TESTS"
+  exit 1
+fi