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

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,46 @@
+#!/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
+      # 2026-06-11 fix(prune D2 抓 data-loss):原 mv 同月二次 rotation 直接覆寫 archive
+      # (實證 .202605 只存 5/31 六小時,5/31–6/10 數萬筆 fire 史遺失)→ append 後清空,不覆寫
+      cat "$log_file" >> "${log_file}.$(date +%Y%m)" 2>/dev/null && : > "$log_file" || 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/auto_regen_ds_barrel.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# auto_regen_ds_barrel.sh — PostToolUse 自動 regen barrel + per-component index
+#
+# 2026-05-25 SSOT auto-sync invariant(user 永久 directive 2026-05-23):
+# DS infra 增刪改 → package 該同步的都該自動,不需耳提面命。
+# 解決 gap:新增 / 刪除 packages/design-system/src/{components,patterns}/<Dir>/ 後
+# barrel `src/index.ts` 沒 auto-regen → consumer subpath import 壞 / new component 漏 export。
+#
+# Fire condition(PostToolUse Write|Edit|MultiEdit):
+#   - Write/Edit 創建新 `packages/design-system/src/components/<Dir>/<kebab>.tsx`
+#     OR 改動 component primary tsx(可能 export 名 change)
+#   - Write/Edit 創建 / 改動 `index.ts` in components/<Dir>/ or patterns/<dir>/
+#   - 新增 / 移除 hooks/*.ts or lib/*.ts(barrel 也 include 這些)
+#
+# Action:silent fire `node scripts/gen-component-indexes.mjs` + `node scripts/gen-design-system-barrel.mjs`
+# 不 BLOCKER — auto fix-up,不打斷 workflow。emit message 告訴 AI「已 auto regen barrel」
+# 對齊 sync-version-to-all-manifests.mjs pattern(post-action auto fix-up)
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null || echo "")
+
+if [ -z "$FILE_PATH" ]; then exit 0; fi
+
+# Scope filter:必 packages/design-system/src/{components,patterns,hooks,lib}/**
+if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/(components|patterns|hooks|lib)/'; then
+  exit 0
+fi
+
+# Skip stories / spec / test files(not barrel-included)
+if echo "$FILE_PATH" | grep -qE '\.(stories|anatomy\.stories|principles\.stories|spec|test|spec\.md)\.(tsx?|md)$'; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+cd "$PROJECT_DIR" 2>/dev/null || exit 0
+
+# Fire 2 gen scripts silently(stderr captured for diagnostics)
+INDEX_OUT=$(node scripts/gen-component-indexes.mjs 2>&1 || true)
+BARREL_OUT=$(node scripts/gen-design-system-barrel.mjs 2>&1 || true)
+
+# Only emit additionalContext if barrel content changed(detected by checking if grep finds count delta)
+# Simple proxy:grep "generated" in output means script ran successfully
+if echo "$BARREL_OUT" | grep -qE 'generated|with [0-9]+ components'; then
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "🔄 auto-regen DS barrel(SSOT auto-sync per 2026-05-23 user directive)— $FILE_PATH 改動觸發 \`gen-component-indexes.mjs\` + \`gen-design-system-barrel.mjs\` re-run。Barrel src/index.ts + per-component index.ts 已對齊。若 commit 此 turn 改動,記得 stage barrel 變化。"
+  }
+}
+EOF
+fi
+
+exit 0

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_audit_post_report_validator.sh

@@ -0,0 +1,156 @@
+#!/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: dim coverage(2026-05-30 M2/M3 fix per laziness-hunt:原 regex `5[01]` 只到 dim 51,
+#   52-88 完全不計（含 PURE-JUDGMENT dim 62/66/68/72）+ 寫死 46。改動態讀 dispatch total + count UNIQUE dim 號）─
+DIM_TOTAL=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.claude/logs/audit-dims-dispatch.json','utf8')).total)}catch{console.log(88)}" 2>/dev/null || echo 88)
+DIM_COUNT=$(grep -oiE '\bdim[[:space:]]+[0-9]{1,2}\b' "$FILE_PATH" 2>/dev/null | grep -oE '[0-9]+' | sort -un | wc -l | tr -d ' ')
+DIM_COUNT=${DIM_COUNT:-0}
+if [ "$DIM_COUNT" -lt "$DIM_TOTAL" ]; then
+  WARNINGS="${WARNINGS}\n  ⚠️ [B] Dim coverage:report 提到 ${DIM_COUNT} unique dim,< ${DIM_TOTAL} 期望。確認全 dim NO-SAMPLE（PURE-JUDGMENT/requiresAgent dim 必有 per-dim agent-output 非散文提號）"
+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
+  # 2026-05-30 M3 fix:原 regex `^### Dim N` 對不上實際格式 `## N. Title`（grep 0 → 永遠誤觸 prune）;
+  # 寫死 46 也錯。改成數真實 `## N.` heading + 動態判「PURE-JUDGMENT dim 數」（只有 judgment dim 需 prompt
+  # 才能派 agent;deterministic/hook dim 不需）。prompts < judgment dim = 有 judgment dim 派不出 agent。
+  # 2026-05-30 fix(hook-test surfaced):`grep -c ... || echo 0` 在 0-match 時 grep 已印 "0" + exit 1,
+  # `|| echo 0` 再 append → "0\n0" → 下方 `[ -lt ]` integer error → trigger 失效。改 `|| true` + 取首行。
+  # 2026-05-31 fix(infra-audit self-finding):原 `[53 -lt 23]` 是 count-vs-count = 永遠 false = dead gate。
+  # 改 SET-MEMBERSHIP:逐個 PURE-JUDGMENT dim 號檢查 audit-prompts.md 有無對應 `## N.` heading,列出缺的。
+  MISSING_PROMPTS=$(node -e "
+    try {
+      const fs=require('fs');
+      const m=JSON.parse(fs.readFileSync('$PROJECT_DIR/.claude/logs/audit-coverage-matrix.json','utf8'));
+      const judg=Object.entries(m.coverage_by_dim).filter(([k,v])=>v.tier==='PURE-JUDGMENT').map(([k])=>+k);
+      const prompts=fs.readFileSync('$AUDIT_PROMPTS','utf8');
+      const have=new Set([...prompts.matchAll(/^##\s+(\d+)\./gm)].map(x=>+x[1]));
+      console.log(judg.filter(d=>!have.has(d)).join(','));
+    } catch(e){ console.log(''); }
+  " 2>/dev/null || echo "")
+  if [ -n "$MISSING_PROMPTS" ]; then
+    WARNINGS="${WARNINGS}\n  🔴 [C] audit-prompts.md 缺 judgment dim prompt:dim ${MISSING_PROMPTS} 是 PURE-JUDGMENT 卻無 \`## N.\` rubric → sub-agent 派不出正確 prompt → 必被跳過。補這些 dim 的 prompt 進 audit-prompts.md。"
+    TRIGGER_PRUNE=1; CRITICAL_FAIL=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 F: A.1b story-vs-code adversarial pass recorded(2026-05-30 403-finding 偷懶 anchor)─
+#   deep-audit report 必含「每 component 讀 .tsx 逐句比對宣稱」的 story-vs-code verdict。缺 = 該 pass
+#   沒跑/沒記 = 前期偷懶 failure mode。偵測 report 是否含 story-vs-code 證據 keyword;deep-audit 規模
+#   report(提 ≥ 10 dim)卻無此 pass = BLOCKER-class warning(走 prune-chain inject 提醒補跑)。
+if [ "$DIM_COUNT" -ge 10 ]; then   # 只對 full/deep-audit 規模 report 要求(小 scoped report 豁免)
+  if ! grep -qiE 'story-vs-code|FALSE_CLAIM|claimsVerified|宣稱.*(真實|code)|A\.1b|逐句比對' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  🔴 [F] Story-vs-code adversarial pass 缺席:deep-audit report(${DIM_COUNT} dim)無 A.1b per-component story-vs-code verdict 證據。202 FALSE_CLAIM(2026-05-30)正是此 pass 沒跑 → 補跑 A.1b(讀每元件 .tsx + wrap lib 逐句驗 anatomy/a11y/spec 宣稱)再出 report。"
+    TRIGGER_PRUNE=1; CRITICAL_FAIL=1
+  fi
+
+  # ─ Validator G: 全 PURE-JUDGMENT dim(含 infra 62/66/68/72)必 show「真跑」證據,非只 mention(2026-05-30 generalize)─
+  #   user 質問「包括所有 infra 稽核?」→ Validator F 只硬保證 story 子集;G 推及全 judgment set。
+  #   judgment dim 無 deterministic script / hook,只能靠「report 含 per-dim 真跑證據」當 proxy。
+  #   evidence marker = 「files scanned / DS-wide 全N / file:line cite / 0 findings after 全掃」。
+  #   evidence 數 < PURE-JUDGMENT dim 數 → 部分 judgment dim 可能 mention-only(偷懶 risk)。
+  PJ_COUNT=$(node -e "try{const m=JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.claude/logs/audit-coverage-matrix.json','utf8'));console.log(Object.values(m.coverage_by_dim).filter(v=>v.tier==='PURE-JUDGMENT').length)}catch{console.log(23)}" 2>/dev/null || echo 23)
+  EVIDENCE_COUNT=$(grep -oiE 'files? scanned|DS-wide|全 ?[0-9]+ (file|stories|component|spec)|[a-z0-9_.-]+\.(tsx|ts|md):[0-9]+|0 findings|scanned: ?[0-9]+' "$FILE_PATH" 2>/dev/null | wc -l | tr -d ' ')
+  EVIDENCE_COUNT=${EVIDENCE_COUNT:-0}
+  if [ "$EVIDENCE_COUNT" -lt "$PJ_COUNT" ]; then
+    WARNINGS="${WARNINGS}\n  🔴 [G] PURE-JUDGMENT dim 真跑證據不足:report 只 ${EVIDENCE_COUNT} 個 per-dim 證據 marker < ${PJ_COUNT} judgment dim(含 infra 62/66/68/72)。judgment dim 無 script/hook 兜底,必每 dim show『DS-wide N files scanned + file:line / 0-after-全掃』證據,否則=mention-only 偷懶。補齊再出 report。"
+    TRIGGER_PRUNE=1; CRITICAL_FAIL=1
+  fi
+fi
+
+# ─ Validator BLOCK gate(2026-05-31 fix infra-audit self-finding:原 hook 只 exit 0 + additionalContext
+#   soft-inject = 我過度宣稱「BLOCKER」。改:C/F/G critical fail → stderr + exit 2 真 block PostToolUse)─
+if [ "${CRITICAL_FAIL:-0}" -eq 1 ]; then
+  printf '🚨 AUDIT-REPORT VALIDATOR BLOCK(C/F/G critical):%b\n\n此 deep-audit report 不合格,補齊上述後重出 report。' "$WARNINGS" >&2
+  exit 2
+fi
+
+# ─ Validator H: 拍板清單 SSOT-理由 強制(2026-06-11 user 第 3 次糾正「要我拍板的都是 SSOT 的 UI/UX 嗎」)─
+# 報告含「待你拍板」/「拍板清單」區塊時:區塊內每個編號題必含「SSOT 理由」字樣;
+# 題數 > SSOT-理由數 = 有題目沒標理由 = 混入非 SSOT 項 → BLOCK。
+if grep -qE '待你拍板|拍板清單' "$FILE_PATH" 2>/dev/null; then
+  _BLOCK_SEG=$(sed -n '/待你拍板\|拍板清單/,$p' "$FILE_PATH" 2>/dev/null)
+  _Q_COUNT=$(echo "$_BLOCK_SEG" | grep -cE '^[[:space:]]*([0-9]+[.、)]|##+ *決策)' || true)
+  _R_COUNT=$(echo "$_BLOCK_SEG" | grep -c 'SSOT 理由' || true)
+  if [ "${_Q_COUNT:-0}" -gt "${_R_COUNT:-0}" ]; then
+    CRITICAL_FAIL=1
+    WARNINGS="${WARNINGS}\n  • Validator H:拍板清單 ${_Q_COUNT} 題但僅 ${_R_COUNT} 題標「SSOT 理由」— 寫不出理由的題 = 非 SSOT,移回 AUTO 自己做,不問 user。"
+  fi
+fi
+
+# ─ Validator E: prune-chain-trigger emit ──────────────────────────────────
+# 2026-06-11 擴充(user 糾正「為何每次都要問我是否要跑 knowledge prune」機械兜底,SSOT = deep-audit SKILL C.0a):
+# deep-audit 規模 report(DIM_COUNT≥10)→ 無條件 fire prune-chain trigger,非僅 coverage 不足時。
+# 分權不變:AI 收到 trigger 必 AUTO-RUN(品質優先前提),P2 retire 仍 user 拍板。
+if [ "${DIM_COUNT:-0}" -ge 10 ] && [ "$TRIGGER_PRUNE" -eq 0 ]; then
+  TRIGGER_PRUNE=1
+  WARNINGS="${WARNINGS}\n  • C.0a unconditional chain:deep-audit 收尾必 AUTO-RUN /knowledge-prune(禁問 user 要不要跑;headroom trigger 命中時 scope 聚焦,否則 quarterly)。"
+fi
+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。AI 必 AUTO-RUN /knowledge-prune(禁問 user;品質優先前提 per deep-audit SKILL C.0a;P2 retire 候選列拍板清單)。\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,76 @@
+#!/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 // ""')
+
+# 2026-06-11 coverage expand(prune D2 抓盲區;expand never replace):Workflow 派發的 agents
+# 原本完全繞過本防線(tool 名 ≠ Agent);Task 為舊名 alias 一併納入。
+case "${TOOL:-}" in
+  Agent|Task|Workflow) ;;
+  *) 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;
+    # Workflow 的 agent prompts 在 .tool_input.script 內(2026-06-11 expand)
+    PROMPT=$(echo "$INPUT" | jq -r '(.tool_input.prompt // "") + "\n" + (.tool_input.script // "")')
+    ;;
+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