@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/ds-canonical/commands/gov-status.md

@@ -0,0 +1,79 @@
+---
+description: One-shot dump governance health snapshot(無 workflow,< 10s 完成)
+---
+
+# /gov-status — Governance Health Snapshot
+
+快印現在 governance state,不走 `/governance-health` 完整 skill workflow(那有 5 phase + CP),只是 user 想 quick check 時的一眼看。
+
+## 跑法
+
+執行以下 bash 並 format output 成 markdown table:
+
+```bash
+echo "=== File sizes ==="
+echo "CLAUDE.md: $(wc -l < CLAUDE.md | tr -d ' ') / 400 target / 800 transition"
+echo ""
+echo "=== Over-cap specs ==="
+for f in $(find src/design-system -name "*.spec.md"); do
+  lines=$(wc -l < "$f" | tr -d ' ')
+  case "$f" in
+    */item-anatomy.spec.md) cap=1200 ;;
+    */color.spec.md|*/sidebar.spec.md|*/tree-view.spec.md) cap=800 ;;
+    *) cap=500 ;;
+  esac
+  if [ "$lines" -gt "$cap" ]; then
+    echo "  ❌ $f: $lines > $cap"
+  fi
+done
+echo ""
+echo "=== Memory ==="
+MEM_DIR=/Users/chenqiren/.claude/projects/-Users-chenqiren-Library-CloudStorage-GoogleDrive-qijenchen-gmail-com--------my-project/memory
+echo "active: $(ls $MEM_DIR/*.md | grep -v retired | wc -l | tr -d ' ') / 20 target"
+echo ""
+echo "=== Hooks / Skills / Agents / Commands ==="
+for d in hooks skills agents commands; do
+  c=$(ls .claude/$d/ 2>/dev/null | grep -v README | grep -v gitignore | wc -l | tr -d ' ')
+  echo "  .claude/$d: $c"
+done
+echo ""
+echo "=== Logs ==="
+for f in hook-fires skill-invokes user-corrections metric-snapshots; do
+  fn=".claude/logs/$f.jsonl"
+  if [ -f "$fn" ]; then
+    echo "  $f: $(wc -l < $fn | tr -d ' ') entries"
+  else
+    echo "  $f: (empty)"
+  fi
+done
+echo ""
+echo "=== Benchmark freshness ==="
+if [ -f .claude/benchmarks/last-fetch.txt ]; then
+  LAST=$(cat .claude/benchmarks/last-fetch.txt)
+  echo "  last: $LAST"
+else
+  echo "  never fetched — run bash .claude/benchmarks/fetch.sh"
+fi
+echo ""
+echo "=== Retire rate(latest snapshot)==="
+if [ -f .claude/logs/metric-snapshots.jsonl ]; then
+  tail -1 .claude/logs/metric-snapshots.jsonl | head -c 200
+fi
+echo ""
+echo "=== tsc state ==="
+npx tsc -b 2>&1 | grep -c "error TS" || echo "0"
+echo ""
+echo "=== compile-stories drift ==="
+node scripts/compile-stories.mjs --all --check 2>&1 | tail -1
+```
+
+## 結論分類
+
+根據上述輸出自動判斷:
+- **✅ OK** — 若無 over-cap spec + 無 tsc error + 無 drift + memory ≤ 20
+- **⚠️ Warning** — 有 over-cap / pending corrections > 10 / benchmark stale > 30 days
+- **❌ Fail** — tsc errors / compile drift / CLAUDE.md > 800
+
+最後給 user 一行 summary:「Governance:{✅/⚠️/❌}{one-line rationale}」。
+
+若要深度 audit → suggest `/governance-health` 跑完整 5-phase skill。

package/ds-canonical/hooks/README.md

@@ -0,0 +1,145 @@
+# .claude/hooks/ Charter
+
+## 這裡只收:pre/post tool event 的機械化自動檢查
+
+每個 hook 是一個 shell / python script,在 Claude Code tool event 上自動觸發:
+- **PreToolUse**:tool 執行前(可 block 或 inject context)
+- **PostToolUse**:tool 執行後(通常 inject 提醒 / warning)
+- **Stop**:turn 結束(sanity / harvest / metric capture)
+- **SessionStart**:session 開始(governance check)
+
+**核心特徵**:**不依賴 AI 自律**,tool 層強制執行;規則可用 `grep` / 條件判斷自動驗證。
+
+## 當前居民(2026-04-26 重整,以 `settings.json` 註冊為準)
+
+### PreToolUse(Bash / Edit / Write / MultiEdit / mcp__github__*)
+
+| Hook | 做什麼 |
+|------|--------|
+| `check_solo_workflow.sh` | M28 git ops gate(branch sprawl / PR / merge — solo work canonical) |
+| `check_codex_collab_5step.sh` | M31 codex collab 5-step gate(claude+codex dual-track discipline) |
+| `enforce_home_charter.sh` | classification-sensitive dir / 新檔案的 charter gate(Write only) |
+| `check_file_size_budget.sh` | CLAUDE.md / spec / SKILL / memory 行數預算警告 |
+| `check_story_invariants.sh` | stories 合一 invariant 檢查(anatomy / slot-split / category / principles canonical — 2026-05-10 已合併 5 個 sub-hook) |
+| `check_canonical_propagation.sh` | canonical 改動(spec / token / primitive)時 consumer propagation 檢查 |
+| `check_pattern_invariants.sh` | pattern 層 invariant(overlay-surface / item-anatomy / action-bar / 等) |
+| `check_naming_and_abstraction.sh` | M21 prop variant test + M27 prop name conflict + naming 三 test |
+| `check_benchmark_citation.sh` | M22 benchmark claim inline cite verify |
+| `check_wrapper_primitive_schema_drift.sh` | M30 wrapper schema 必 extends primitive |
+| `check_field_family_invariants.sh` | Field family layout / state machine 統一 |
+| `check_datatable_invariants.sh` | DataTable canonical(virtualizer / column-types / autoRow / overflow) |
+| `check_opacity_token_usage.sh` | opacity token 使用紀律 |
+| `check_substantive_edit_approval_preflight.sh` | substantive edit 前 user 拍板 preflight |
+
+### PostToolUse(Edit / Write / MultiEdit)
+
+| Hook | 做什麼 |
+|------|--------|
+| `block_prototype_imports.py` | 產品 code 禁止 import `explorations/` |
+| `post_edit_dispatcher.sh` | **Dispatcher**(2026-05-13 prune):一次 orchestrate 8 個 lib helper(token_hygiene / hardcoded_strings / code_quality / layout_space / person_data / overlay_handcraft / cva_default_sync / story_compile_drift)— hook count 32 → 24 |
+| `check_story_invariants.sh` | (同上,PostToolUse 路徑做 disk read drift check) |
+| `check_pixel_quantified_audit.sh` | M32 audit script 必 pixel-quantified verify(scans audit scripts for `getAttribute(` without `getBoundingClientRect(`) |
+| `check_field_controls_contracts.sh` | Field controls contract 強制(c)/(e)/(f) 等 |
+| `log_governance_fires.sh` | 治理檔 fire log 寫入 `.claude/logs/hook-fires.jsonl`(L2 anti-bloat) |
+
+### PostToolUse(Skill)
+
+| Hook | 做什麼 |
+|------|--------|
+| `log_skill_invokes.sh` | skill invoke log(本 hook 僅捕 Skill tool 呼叫,slash-command 走 user prompt 不被捕 — known limitation) |
+
+### Stop
+
+| Hook | 做什麼 |
+|------|--------|
+| `stop_passive_logging.sh` | **Dispatcher**(2026-05-13 prune):一次跑 5 rule(tsc sanity / harvest corrections / capture metrics / governance drift / infra best-practice score)— stop hook count 3 → 2 |
+| `stop_self_audit.sh` | turn 行為 audit(claim 沒 verify / prune trigger / topic 重複 ≥ 3 次 → BLOCKER inject,M20 100+ failure mode 升級 2026-05-13) |
+| `stop_meta_self_audit.sh` | turn infra-score audit(8 維 score 跌 ≥ 5 / 任何 dim < 80 → silent log,不 inject — 詳 known issue 段) |
+| `stop_harvest_corrections.sh` | 掃 session 的 user 糾正信號寫 `.claude/logs/user-corrections.jsonl` |
+| `stop_capture_metrics.sh` | session 結束 metric snapshot |
+
+### SessionStart
+
+| Hook | 做什麼 |
+|------|--------|
+| `session_start_governance_check.sh` | 4 check(行數 / prune / corrections / benchmarks 過期 auto-fetch) |
+
+### UserPromptSubmit
+
+| Hook | 做什麼 |
+|------|--------|
+| `inject_pending_self_audit.sh` | 讀 stop_self_audit / stop_meta_self_audit silent log,dedup + 24h filter + 3KB cap,inject 到 next turn additionalContext。修補 Stop hook silent-log 不 inject 的 known issue。 |
+
+### Helper(非註冊 hook)
+
+| File | 用途 |
+|------|------|
+| `_log-fire.sh` | 各 hook source 的 fire-logging helper |
+
+## Anti-bloat 落地
+
+- **L1 Pre-write**:`check_file_size_budget.sh` + `check_story_invariants.sh`(內含 principles canonical + l3 primitive 等 5 個合一)等(PreToolUse 阻擋 / 警告)
+- **L2 Per-commit**:`log_governance_fires.sh` → `.claude/logs/hook-fires.jsonl`(governance file 編輯軌跡)+ `log_skill_invokes.sh`
+- **L3 Periodic**:`/knowledge-prune` skill 季度跑,retire ≥ 5%
+
+## 這裡**不收**(反例)
+
+| 疑似要放這但其實不是 | 實際應去 | 為什麼 |
+|-------------------|---------|--------|
+| 需要 AI 走流程才能判斷的規則 | `.claude/skills/` | hook 只能機械判斷,複雜 workflow 屬 skill |
+| 每 session signal rule | `CLAUDE.md` | hook 是 tool-level,不是 session-level |
+| 單一元件的 lint rule | 該元件 spec + code | hook 是跨元件系統級,單元件屬 spec |
+
+## 新 hook 的 criteria(必須全部通過)
+
+1. **規則可機械判斷**(grep / 條件邏輯,不需人類 judgment)
+2. **觸發 event 清楚**(PreToolUse / PostToolUse / Stop / SessionStart + matcher)
+3. **已有明確 tech debt 或 bug class**(不做預防性空守衛)
+4. **失敗模式安全**(hook 掛掉不會 block 合法操作 / 誤殺)
+
+## 接線到 settings.json
+
+新 hook 必須在 `.claude/settings.json` 的 `hooks.PreToolUse` / `hooks.PostToolUse` / `hooks.Stop` / `hooks.SessionStart` 陣列註冊,並用 `$CLAUDE_PROJECT_DIR` 作為路徑前綴。範例:
+
+```json
+{
+  "type": "command",
+  "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/your-hook.sh\""
+}
+```
+
+## Hook 退出碼約定(Claude Code 協議)
+
+- `exit 0` — 正常,不 inject context
+- `exit 2` + stderr — **blocking**,AI 看到 stderr 訊息後必須處理
+- `stdout` with `{"hookSpecificOutput":{"hookEventName":"...","additionalContext":"..."}}` — non-blocking context injection
+
+## 已修(2026-04-28):Stop hook → UserPromptSubmit inject 鏈路
+
+**症狀**:Stop hooks(`stop_self_audit` / `stop_meta_self_audit`)silent-log 但不 inject,M14 / M20 的「auto-inject corrective prompt」 不生效 → AI reactive 模式持續。
+
+**修法**:加 `inject_pending_self_audit.sh` 註冊在 UserPromptSubmit hook(該 event 確認支援 `hookSpecificOutput.additionalContext`)。鏈路:
+
+```
+turn 結束 Stop event → stop_self_audit / stop_meta_self_audit silent log to .claude/logs/
+                                              ↓
+user 下一個 prompt → UserPromptSubmit fires → inject_pending_self_audit.sh
+                                              ↓
+                                        讀 log (since last-inject-ts)
+                                        dedup + 24h filter + 3KB cap
+                                              ↓
+                                        inject 給 AI next-turn context
+```
+
+**Self-test**:`bash .claude/hooks/tests/test_inject_pending_self_audit.sh`(5/5 pass)。
+
+## Retired
+
+`retired/` 目錄存舊 hook(不再註冊),保留 reference 不刪除。當前已 retire 的 hook 不在本 inventory 列出 — 以 `settings.json` 為 SSOT。
+
+最近 retire(2026-04-28):
+- `check_button_icon_literal.sh` — 違反 Rule-of-3(DS-wide 0 hits,只我 1 次失誤建)
+
+## 建立前必 Read
+
+本 README + 最接近的既有 hook 當範本 + CLAUDE.md `# 治理 canonical` 的 Hook 章節。

package/ds-canonical/hooks/_log-fire.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Note: This file is SOURCED by other hooks. Do NOT add `set -u` / `set -e` /
+# `pipefail` here — `source` runs in caller shell and propagates flags,
+# breaking caller code that legitimately reads unset vars (e.g. ${VIOLATIONS}
+# accumulator pattern). Caller hooks set their own flags as standalone scripts.
+#
+# Shared helper: log per-hook fire to .claude/logs/hook-fires-per-hook.jsonl
+#
+# Why: enables /knowledge-prune D2 dead-hook detection(6 月 0 fire → retire 提名)。
+# 各 hook 在 top-of-file source 本檔 + 呼叫 `log_hook_fire`。
+#
+# 與 hook-fires.jsonl 分離:後者記 governance-file edits(tool+path),本 log 記
+# per-hook fire(hook basename+ts)。兩 log 互補不重疊。
+#
+# 規則:silent on failure,不 block hook 執行。
+
+log_hook_fire() {
+  local hook_name="${1:-$(basename "${BASH_SOURCE[1]:-$0}")}"
+  # Resolve project root from this helper's location(stable; cwd may be anywhere
+  # depending on how Claude Code invokes the hook)to avoid stray .claude/ trees.
+  local _self_dir
+  _self_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  local _resolved_root="${_self_dir%/.claude/hooks}"
+  local log_dir="${CLAUDE_PROJECT_DIR:-$_resolved_root}/.claude/logs"
+  local log_file="$log_dir/hook-fires-per-hook.jsonl"
+
+  mkdir -p "$log_dir" 2>/dev/null || return 0
+
+  # Rotate if > 1 MB
+  if [ -f "$log_file" ]; then
+    local size
+    size=$(wc -c < "$log_file" 2>/dev/null | tr -d ' ')
+    if [ -n "$size" ] && [ "$size" -gt 1048576 ]; then
+      mv "$log_file" "${log_file}.$(date +%Y%m)" 2>/dev/null || true
+    fi
+  fi
+
+  printf '{"ts":"%s","hook":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$hook_name" \
+    >> "$log_file" 2>/dev/null || true
+}
+
+

package/ds-canonical/hooks/block_prototype_imports.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+import json
+import os
+import re
+import sys
+import time
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+# Resolve project root from this script's location(stable; cwd may be anywhere
+# depending on how Claude Code invokes the hook)to avoid stray .claude/ trees.
+try:
+    _project_root = os.environ.get('CLAUDE_PROJECT_DIR') or os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    _log_dir = os.path.join(_project_root, '.claude', 'logs')
+    os.makedirs(_log_dir, exist_ok=True)
+    with open(os.path.join(_log_dir, 'hook-fires-per-hook.jsonl'), 'a') as _f:
+        _f.write(json.dumps({'ts': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()), 'hook': os.path.basename(__file__)}) + '\n')
+except Exception:
+    pass
+
+EXPLORATION_PREFIX = "src/explorations/"
+SRC_PREFIX = "src/"
+
+def load_event():
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return None
+
+def collect_file_paths(tool_input):
+    paths = []
+
+    if not isinstance(tool_input, dict):
+        return paths
+
+    file_path = tool_input.get("file_path")
+    if isinstance(file_path, str):
+        paths.append(file_path)
+
+    edits = tool_input.get("edits")
+    if isinstance(edits, list):
+        for item in edits:
+            if isinstance(item, dict):
+                p = item.get("file_path")
+                if isinstance(p, str):
+                    paths.append(p)
+
+    files = tool_input.get("files")
+    if isinstance(files, list):
+        for item in files:
+            if isinstance(item, dict):
+                p = item.get("file_path")
+                if isinstance(p, str):
+                    paths.append(p)
+
+    return list(dict.fromkeys(paths))
+
+def should_check(path):
+    if not path.startswith(SRC_PREFIX):
+        return False
+    if path.startswith(EXPLORATION_PREFIX):
+        return False
+    if not (path.endswith(".ts") or path.endswith(".tsx")):
+        return False
+    return True
+
+def contains_exploration_import(content):
+    patterns = [
+        r'from\s+[\'"].*src/explorations/.*[\'"]',
+        r'from\s+[\'"].*explorations/.*[\'"]',
+        r'import\s+[\'"].*src/explorations/.*[\'"]',
+        r'import\s+[\'"].*explorations/.*[\'"]'
+    ]
+    return any(re.search(p, content) for p in patterns)
+
+def main():
+    event = load_event()
+    if not event:
+        sys.exit(0)
+
+    tool_input = event.get("tool_input", {})
+    touched_paths = collect_file_paths(tool_input)
+
+    offenders = []
+
+    for path in touched_paths:
+        if not should_check(path):
+            continue
+        if not os.path.exists(path):
+            continue
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except Exception:
+            continue
+
+        if contains_exploration_import(content):
+            offenders.append(path)
+
+    if offenders:
+        lines = [
+            "Blocked: 正式程式碼不得 import src/explorations/ 內的檔案。"
+        ]
+        lines.extend(f"- {p}" for p in offenders)
+        print("\n".join(lines))
+        sys.exit(2)
+
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/ds-canonical/hooks/check_app_shell_primary_header_consistency.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# check_app_shell_primary_header_consistency.sh — PreToolUse Edit/Write
+#
+# 2026-05-21 ship per user directive「該程式化的就程式化」+「確認當有 global header 時,
+# sidebar 內的 header 應該要拿掉」+ world-class GitHub/Gmail/Figma 共識。
+#
+# Detects 2 violations in AppShell consumer code:
+#   V1) `layout="primary-header"` without `globalHeader=...` prop
+#       → 缺 globalHeader 而 layout=primary-header 是邏輯矛盾(per app-shell.spec.md
+#         「primary-header = primary-sidebar + 一條 global header」)
+#
+#   V2) `layout="primary-header"` + 任何 `<SidebarHeader>...</SidebarHeader>` 在同 file
+#       → WorkspaceBrand 已該在 globalHeader,sidebar 內不該再有 SidebarHeader
+#         (per app-shell.spec.md「WorkspaceBrand 放置 SSOT」+ world-class GitHub/Gmail/Figma 一致)
+#
+# 對齊 .claude/rules/self-verify.md「Pre-edit」階段 + check_chrome_header_handcraft.sh /
+# check_overlay_handcraft.sh 等既有 SSOT-enforcement hook idiom。
+# Exception escape:`// @app-shell-primary-header-allow: <reason>` 檔頭。
+
+set -uo pipefail
+source "$(dirname "$0")/_log-fire.sh"
+
+# 只看 Edit / Write tool
+TOOL_NAME=$(echo "${CLAUDE_TOOL_INPUT:-}" | python3 -c "import sys,json; d=json.load(sys.stdin) if sys.stdin.isatty()==False else {}; print(d.get('tool_name',''))" 2>/dev/null || echo "")
+if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then exit 0; fi
+
+TARGET=$(echo "${CLAUDE_TOOL_INPUT:-}" | python3 -c "import sys,json; d=json.load(sys.stdin) if sys.stdin.isatty()==False else {}; print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null || echo "")
+# 只查 .tsx / .stories.tsx consumer file
+if [[ ! "$TARGET" =~ \.(tsx)$ ]]; then exit 0; fi
+if [[ ! -f "$TARGET" ]]; then exit 0; fi
+
+# 排除 spec / test / SSOT 檔
+case "$TARGET" in
+  *.spec.md|*test*|*/AppShell/app-shell.tsx) exit 0 ;;
+esac
+
+# Escape allowlist
+if grep -q "@app-shell-primary-header-allow:" "$TARGET"; then exit 0; fi
+
+# 偵測 layout="primary-header"
+if ! grep -q 'layout="primary-header"\|layout={["\047]primary-header["\047]}' "$TARGET"; then exit 0; fi
+
+VIOLATIONS=()
+
+# V1:layout="primary-header" 但無 globalHeader=
+if ! grep -q 'globalHeader\s*=' "$TARGET"; then
+  VIOLATIONS+=("V1 缺 globalHeader prop:layout=\"primary-header\" 必傳 globalHeader 否則邏輯矛盾(per app-shell.spec.md「primary-header = primary-sidebar + 一條 global header」)")
+fi
+
+# V2:layout="primary-header" + <SidebarHeader> 同 file → WorkspaceBrand 該在 globalHeader 不重複
+if grep -q '<SidebarHeader' "$TARGET"; then
+  VIOLATIONS+=("V2 Sidebar 內含 SidebarHeader:primary-header mode WorkspaceBrand 該在 globalHeader,sidebar 內不該重複(per spec.md「WorkspaceBrand 放置 SSOT」+ world-class GitHub/Gmail/Figma 共識)。若 sidebar header 是其他內容(非 brand),加 escape allowlist `// @app-shell-primary-header-allow:` 並說明 reason")
+fi
+
+if [[ ${#VIOLATIONS[@]} -gt 0 ]]; then
+  echo "🚨 AppShell primary-header consistency violation" >&2
+  echo "Target: $TARGET" >&2
+  for v in "${VIOLATIONS[@]}"; do echo "  • $v" >&2; done
+  echo "" >&2
+  echo "修法:" >&2
+  echo "  (a) 傳 globalHeader prop / 撤掉 SidebarHeader" >&2
+  echo "  (b) 改 layout=\"primary-sidebar\"(若不需要 global header)" >&2
+  echo "  (c) Escape 允許:檔首加 \`// @app-shell-primary-header-allow: <rationale>\`" >&2
+  log_fire "check_app_shell_primary_header_consistency"
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_audit_post_report_validator.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# PostToolUse hook: validate `/design-system-audit` final report quality.
+# 2026-05-17 ship — codex Q4 verdict「post-audit stop hook / final report validator」最合理 trigger 位置。
+#
+# Triggers: 任何 Write/Edit 到 `.claude/logs/audit-report-*.json` OR `.claude/memory/project_audit_progress.md`
+#
+# 驗證:
+#   (a) NO-SAMPLE invariant — report 不含「sample top N / subset / pick top X」keyword
+#   (b) 46-dim full dispatch — report 應列 ≥ 46 dim coverage 紀錄(或明示 N/A 跳過理由)
+#   (c) audit-prompts.md coverage — 若 missing dim prompt → flag prune-chain-trigger
+#   (d) `@benchmark-unverified-blanket` count drift — vs last audit baseline
+#   (e) prune-chain-trigger signal → emit additionalContext 進下一 turn,inject_pending_self_audit 吸
+#
+# 對應 SKILL.md `/design-system-audit` Phase 4.5 機械化 trigger(2026-05-17 加)。
+
+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)
+
+# Only fire on audit report writes
+case "$FILE_PATH" in
+  */audit-report-*.json) ;;
+  */project_audit_progress.md) ;;
+  *) exit 0 ;;
+esac
+
+case "$TOOL" in Write|Edit|MultiEdit) ;; *) exit 0 ;; esac
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+[ -f "$FILE_PATH" ] || exit 0
+
+WARNINGS=""
+TRIGGER_PRUNE=0
+
+# ─ Validator A: NO-SAMPLE ─────────────────────────────────────────────────
+if grep -qE 'sample top [0-9]+|sampled top|subset|pick top [0-9]+|top hot|sampled components' "$FILE_PATH" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ❌ [A] NO-SAMPLE violation:report 含 sample subset keyword,違反 audit-full-sweep canonical(memory/feedback_audit_full_sweep_not_sample.md)"
+fi
+
+# ─ Validator B: 46-dim coverage ───────────────────────────────────────────
+DIM_COUNT=$(grep -cE '(Dim|dim) ([1-9]|[1-4][0-9]|5[01])(\b|:)' "$FILE_PATH" 2>/dev/null || echo 0)
+DIM_COUNT=${DIM_COUNT:-0}
+if [ "$DIM_COUNT" -lt 46 ]; then
+  WARNINGS="${WARNINGS}\n  ⚠️ [B] Dim coverage:report 提到 ${DIM_COUNT} dim,< 46 期望。確認跑了 46-dim 全 dispatch 還是漏 group"
+fi
+
+# ─ Validator C: audit-prompts.md coverage ─────────────────────────────────
+AUDIT_PROMPTS="$PROJECT_DIR/.claude/skills/design-system-audit/references/audit-prompts.md"
+if [ -f "$AUDIT_PROMPTS" ]; then
+  PROMPT_DIM_COUNT=$(grep -cE '^###[[:space:]]*Dim[[:space:]]+[1-9][0-9]?(\b|:|[[:space:]])' "$AUDIT_PROMPTS" 2>/dev/null || echo 0)
+  PROMPT_DIM_COUNT=${PROMPT_DIM_COUNT:-0}
+  if [ "$PROMPT_DIM_COUNT" -lt 46 ]; then
+    WARNINGS="${WARNINGS}\n  🔴 [C] audit-prompts.md prompt coverage:${PROMPT_DIM_COUNT}/46 — 紙上 dim 無 prompt,sub-agent 跑不動。下輪 prune Phase 1 D5 candidate(canonical drift:SKILL.md 46-dim vs audit-prompts.md prompt 數差距)"
+    TRIGGER_PRUNE=1
+  fi
+fi
+
+# ─ Validator D: @benchmark-unverified-blanket count drift ─────────────────
+BENCH_DEBT=$(grep -rc '@benchmark-unverified-blanket' "$PROJECT_DIR/packages/design-system/src/" 2>/dev/null | awk -F: '{s+=$2} END{print s+0}')
+BENCH_DEBT=${BENCH_DEBT:-0}
+if [ "$BENCH_DEBT" -gt 0 ]; then
+  WARNINGS="${WARNINGS}\n  ⚠️ [D] Benchmark cite debt:${BENCH_DEBT} 處 `@benchmark-unverified-blanket` marker — 對應 prune D9(M22 cite debt)"
+  TRIGGER_PRUNE=1
+fi
+
+# ─ Validator E: prune-chain-trigger emit ──────────────────────────────────
+if [ "$TRIGGER_PRUNE" -eq 1 ] || [ -n "$WARNINGS" ]; then
+  mkdir -p "$PROJECT_DIR/.claude/logs" 2>/dev/null
+  printf '{"ts":"%s","file":"%s","trigger_prune":%d,"warnings":%s}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$FILE_PATH" \
+    "$TRIGGER_PRUNE" \
+    "$(printf '%b' "$WARNINGS" | jq -Rs .)" \
+    >> "$PROJECT_DIR/.claude/logs/audit-post-report-validator.jsonl" 2>/dev/null || true
+
+  if [ "$TRIGGER_PRUNE" -eq 1 ]; then
+    CTX=$(printf '🚨 audit post-report validator: prune-chain-trigger fire。下輪 invoke /knowledge-prune scope=full(triggers: audit-prompts coverage < 100%% / @benchmark-unverified-blanket count > 0)。\n%b' "$WARNINGS")
+    jq -n --arg ctx "$CTX" '{
+      hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+    }'
+  fi
+fi
+
+exit 0

package/ds-canonical/hooks/check_audit_sample_escape.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Audit NO-SAMPLE strict enforcement(2026-05-17 P0 user-mandated):
+#   /design-system-audit --deep dispatch sub-agent prompt 禁含 sample escape clause。
+#   違 = BLOCKER 不允 dispatch。
+#
+# 背景:audit Dim 24/25/40-43/45/46/48 sub-agent 多次 sampled 不全掃 → user 抓「你他媽是不是又再搞抽樣」。
+# 加 mechanical hook 攔截 dispatch prompt 含 sample escape keyword。
+#
+# PreToolUse(Agent)hook:讀 tool_input.prompt,grep escape keyword 命中 → exit 2 BLOCKER。
+#
+# Allow escape:dispatch prompt 加 `// @audit-sample-allow: <rationale>` 整 prompt 豁免(極罕見場景)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""')
+
+case "${TOOL:-}" in
+  Agent) ;;
+  *) exit 0 ;;
+esac
+
+# 2026-05-23 P0 升級 per user verbatim「幹你娘就叫你他媽所有稽核都要完整執行不要再抽樣,到底要講幾次?...把全部要稽核的東西都給我避免抽樣」:
+# - PreToolUse:scan tool_input.prompt(dispatch prompt)阻 escape clause
+# - PostToolUse:scan tool_response.content(sub-agent OUTPUT)阻 sub-agent 自報「I sampled / spot-check / representative」admission
+case "${EVENT:-}" in
+  PostToolUse)
+    # Sub-agent OUTPUT scan — catch post-fact admission
+    OUTPUT=$(echo "$INPUT" | jq -r '.tool_response.content // .tool_response // ""' 2>/dev/null)
+    # Only fire on audit-related agent runs(by output keyword)
+    if ! echo "$OUTPUT" | grep -qiE 'audit|Dim [0-9]+|D[0-9]+ CLEAN|DS-wide|sub-agent'; then exit 0; fi
+    PROMPT="$OUTPUT" # reuse PROMPT var for downstream grep
+    ;;
+  *)
+    # PreToolUse(default existing logic):scan dispatch prompt
+    PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // ""')
+    ;;
+esac
+
+# Allow escape(極罕見)
+if echo "$PROMPT" | grep -qE '@audit-sample-allow:'; then
+  exit 0
+fi
+
+# Only enforce on audit-related dispatch(detect by prompt keyword)
+if ! echo "$PROMPT" | grep -qE 'audit|Dim [0-9]+|DS-wide|sub-agent|sweep'; then
+  exit 0
+fi
+
+# Detect sample escape clause keyword
+# 2026-05-23 M34 fix per user verbatim「抽樣幾百次了到底要怎樣才能百分百避免」+「我要你他媽所有稽核都不能抽樣」:
+# 原 regex 太窄(narrow) 漏抓 my own dispatch keyword「Sample-based scan OK」+「cover 20+ random samples」+「too many components for exhaustive」。
+# 升 grep -i case-insensitive + 廣 pattern coverage(spec wording「NO-SAMPLE」是 broad category)。
+ESCAPE_HITS=$(echo "$PROMPT" | grep -oiE 'sample[ -]?based|sample-N|sample-only|sample evidence|sample top [0-9]+|sample[s]?[[:space:]]+(scan|OK|allowed|fine|enough|sufficient|recommended|sub|covering)|covering[[:space:]]+[0-9]+\+?[[:space:]]*sample|covers[[:space:]]+[0-9]+\+?[[:space:]]*sample|cover[[:space:]]+[0-9]+\+?[[:space:]]*(random[[:space:]]+)?sample|pick top [0-9]+|top hot|sampled[[:space:]]*(components|elements|files|Button|button|story|stories)|sample-?based|sampling[[:space:]]+(scan|approach|method)|heavy agent needed|full sweep deferred|defer.*heavy|cite.*heavy agent|exhaustive[[:space:]]+too[[:space:]]+(many|much)|too[[:space:]]+many[[:space:]]+for[[:space:]]+exhaustive|random[[:space:]]+sample|skip[[:space:]]+rest|skip[[:space:]]+remaining|spot[[:space:]]*[-]?[[:space:]]*check(ed|ing)?|spot[[:space:]]*sample|representative[[:space:]]+(sample|subset)|i[[:space:]]+sampled|only[[:space:]]+sampled|sampled[[:space:]]+only|sample[[:space:]]+sized?|sub-agent[[:space:]]+self-judg|self-judgment[[:space:]]+per[[:space:]]+Dim|AI[[:space:]]+judgment[[:space:]]+per[[:space:]]+Dim|sample-based[[:space:]]+AI[[:space:]]+judgment|sampled[[:space:]]+(Button|button|first|few|several)' | sort -u)
+
+if [ -n "$ESCAPE_HITS" ]; then
+  printf '🚨 AUDIT NO-SAMPLE ESCAPE CLAUSE BLOCKER(audit canonical 2026-05-17 user-mandated):\n' >&2
+  printf '   Dispatch prompt 含 sample escape clause:\n' >&2
+  echo "$ESCAPE_HITS" | while IFS= read -r hit; do
+    printf '   • "%s"\n' "$hit" >&2
+  done
+  printf '\n  Per CLAUDE.md `# 稽核 canonical` + design-system-audit/SKILL.md Phase 1 NO-SAMPLE invariant:\n' >&2
+  printf '  禁含「sample / top N / heavy agent needed / full sweep deferred」escape clause。\n' >&2
+  printf '  每 dim 必 DS-wide ALL components 全掃,context 不夠拆 stage 分批,**不 sample**。\n' >&2
+  printf '\n  修方向:從 prompt 移除 escape clause,改寫「拆 N-stage(每 stage 10-15 元件)所有 stages 必跑完」。\n' >&2
+  printf '  Escape(極罕見): prompt 加 // @audit-sample-allow: <rationale>\n' >&2
+  exit 2
+fi
+
+exit 0