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

package/ds-canonical/hooks/README.md

@@ -1,8 +1,10 @@
-# .claude/hooks/ Charter
+# Provider-neutral hook corpus charter
+
+**Canonical owner:** `packages/design-system/ds-canonical/hooks/**`. `.claude/hooks/**` is a deterministic compatibility view. Event registration is owned by `registrations.json`; provider events, matcher aliases, environment mapping, and config paths are bindings in `packages/governance/canonical/providers.json`.
 
 ## 這裡只收:pre/post tool event 的機械化自動檢查
 
-每個 hook 是一個 shell / python script,在 Claude Code tool event 上自動觸發:
+每個 hook 是一個 shell / python script，必要的複雜機械判斷放在同一 canonical tree 的 static Node helper，由 provider adapter 在支援的 tool event 上觸發:
 - **PreToolUse**:tool 執行前(可 block 或 inject context)
 - **PostToolUse**:tool 執行後(通常 inject 提醒 / warning)
 - **Stop**:turn 結束(sanity / harvest / metric capture)
@@ -10,26 +12,26 @@
 
 **核心特徵**:**不依賴 AI 自律**,tool 層強制執行;規則可用 `grep` / 條件判斷自動驗證。
 
-## 當前居民(2026-04-26 重整,以 `settings.json` 註冊為準)
+## 當前居民(2026-04-26 重整,以 canonical `registrations.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) |
+| `check_codex_collab_5step.sh` | M31 independent-peer 5-step gate(legacy filename retained;peer 由 provider registry 決定) |
 | `enforce_home_charter.sh` | classification-sensitive dir / 新檔案的 charter gate(Write only) |
-| `check_file_size_budget.sh` | CLAUDE.md / spec / SKILL / memory 行數預算警告 |
+| `check_file_size_budget.sh` | registry-declared instruction entry / spec / canonical-provider 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_benchmark_citation.sh` | M22 benchmark claim inline cite verify；component specs 禁止未驗證／檔級 escape，維持 zero evidence debt |
 | `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 |
+| `check_substantive_edit_approval_preflight.sh` | target-bound authority classifier：工程 remediation AUTO；產品／UI／UX SSOT 真取捨需 exact decision；unknown fail closed |
 
 ### PostToolUse(Edit / Write / MultiEdit)
 
@@ -40,7 +42,7 @@
 | `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) |
+| `log_governance_fires.sh` | 治理檔 fire log 寫入 `$GOVERNANCE_STATE_DIR/hook-fires.jsonl`(L2 anti-bloat) |
 
 ### PostToolUse(Skill)
 
@@ -55,7 +57,7 @@
 | `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_harvest_corrections.sh` | 掃 session 的 user 糾正信號寫 `$GOVERNANCE_STATE_DIR/user-corrections.jsonl` |
 | `stop_capture_metrics.sh` | session 結束 metric snapshot |
 
 ### SessionStart
@@ -69,25 +71,40 @@
 | 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。 |
+| `check_propose_without_benchmark.sh` | DS-author 提案型 prompt 若缺可驗證 benchmark 證據則注入 M26 提醒；一般 prompt 不阻擋。 |
+
+### Provider transcript 排錯
+
+Claude 每個 prompt（包含 `Hi`）都在送出前顯示 `TRANSCRIPT_SIZE_OR_TYPE_INVALID`，代表仍在執行舊的 transcript adapter；舊版可能把整份長期 session 檔案大小、provider 自訂檔名或檔案型別誤當成拒絕條件。現行 runner 只從穩定 regular file 驗證並複製有上限的 JSONL 尾端，不讀取整份 transcript；過大單筆、非 JSONL、symlink／FIFO 或讀取期間替換仍 fail closed。
+
+先記錄錯誤所列的完整 hook command，不要改名、截斷或手動搬動 session 檔。Command 指向 repo `scripts/run-provider-hook.mjs` 時，重新產生／同步受審 provider view；指向 `${CLAUDE_PLUGIN_ROOT}` 時，另行更新 plugin cache，repo sync 不會代替 plugin 更新。更新後必須完整退出所有 Claude Code process 再重開，不能只開新 tab 或沿用舊的 `--continue` process。
 
 ### Helper(非註冊 hook)
 
 | File | 用途 |
 |------|------|
 | `_log-fire.sh` | 各 hook source 的 fire-logging helper |
+| `lib/provider-marker-regex.mjs` | 驗證 provider registry marker array 並輸出 escaped ERE |
+| `lib/audit-report-validator.mjs` | audit report matrix / prompt / 決策證據的固定資料運算 |
+| `lib/tsx-governance-analysis.mjs` | 從 consumer project 解析 pinned TypeScript，執行三個 TSX AST governance analyzer |
+| `tests/registration-output-contracts.mjs` | registration output contract 的固定測試程式 |
+
+Node helper 必須是本 canonical tree 內可盤點、可雜湊的 committed `.mjs`，shell 只能用 `node -- <exact-static-path> ...` 傳資料。禁止 `node -e`、`node -p`、`--eval`、`--print`、stdin / heredoc JavaScript；provider view 一律由 canonical source 生成。
 
 ## 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%
+- **L2 Per-edit**(PostToolUse Write|Edit|MultiEdit,script 內自過濾 governance file):`log_governance_fires.sh` → `$GOVERNANCE_STATE_DIR/hook-fires.jsonl`(governance file 編輯軌跡)+ `log_skill_invokes.sh`
+- **L3 Periodic**:`/knowledge-prune` skill 季度跑；量化 retire rate，但只 retire 有證據的噪音，禁止為湊比例硬刪
+
+Runtime telemetry 必須由 trusted adapter 明示設定 `GOVERNANCE_TELEMETRY_OPT_IN=1`。`$GOVERNANCE_STATE_DIR` 只能在 Git-owned `<git-dir>/governance-runtime/` 內；未指定時使用該 Git-owned default，read-only / 未 opt-in 時不寫任何 runtime bytes。Generated provider homes 不是 telemetry authority。
 
 ## 這裡**不收**(反例)
 
 | 疑似要放這但其實不是 | 實際應去 | 為什麼 |
 |-------------------|---------|--------|
-| 需要 AI 走流程才能判斷的規則 | `.claude/skills/` | hook 只能機械判斷,複雜 workflow 屬 skill |
-| 每 session signal rule | `CLAUDE.md` | hook 是 tool-level,不是 session-level |
+| 需要 AI 走流程才能判斷的規則 | `packages/design-system/ds-canonical/skills/` | hook 只能機械判斷,複雜 workflow 屬 canonical skill |
+| 每 session signal rule | shared / registry-declared instruction entry | hook 是 tool-level,不是 session-level |
 | 單一元件的 lint rule | 該元件 spec + code | hook 是跨元件系統級,單元件屬 spec |
 
 ## 新 hook 的 criteria(必須全部通過)
@@ -97,22 +114,19 @@
 3. **已有明確 tech debt 或 bug class**(不做預防性空守衛)
 4. **失敗模式安全**(hook 掛掉不會 block 合法操作 / 誤殺)
 
-## 接線到 settings.json
+## 接線到 provider registry
 
-新 hook 必須在 `.claude/settings.json` 的 `hooks.PreToolUse` / `hooks.PostToolUse` / `hooks.Stop` / `hooks.SessionStart` 陣列註冊,並用 `$CLAUDE_PROJECT_DIR` 作為路徑前綴。範例:
+新 hook 必須在 canonical `registrations.json` 註冊。Hook core 只讀 `GOVERNANCE_*`；legacy provider env 由 `scripts/run-provider-hook.mjs` 依 registry 映射。Provider view 由 `node scripts/sync-ds-canonical.mjs` 生成，禁止手改 `.claude/settings.json` / `.codex/hooks.json`。範例:
 
 ```json
-{
-  "type": "command",
-  "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/your-hook.sh\""
-}
+{ "kind": "hook", "hook": "your-hook.sh", "runtime": "bash" }
 ```
 
-## Hook 退出碼約定(Claude Code 協議)
+## Hook 退出碼約定(portable command-hook contract)
 
 - `exit 0` — 正常,不 inject context
 - `exit 2` + stderr — **blocking**,AI 看到 stderr 訊息後必須處理
-- `stdout` with `{"hookSpecificOutput":{"hookEventName":"...","additionalContext":"..."}}` — non-blocking context injection
+- `stdout` with `{"governanceContext":{"hookEventName":"...","message":"..."}}` — provider-neutral non-blocking context;adapter 轉成各 provider 的 native transport
 
 ## 已修(2026-04-28):Stop hook → UserPromptSubmit inject 鏈路
 
@@ -121,7 +135,7 @@
 **修法**:加 `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/
+turn 結束 Stop event → stop_self_audit / stop_meta_self_audit silent log to $GOVERNANCE_STATE_DIR/
                                               ↓
 user 下一個 prompt → UserPromptSubmit fires → inject_pending_self_audit.sh
                                               ↓
@@ -131,15 +145,15 @@ user 下一個 prompt → UserPromptSubmit fires → inject_pending_self_audit.s
                                         inject 給 AI next-turn context
 ```
 
-**Self-test**:`bash .claude/hooks/tests/test_inject_pending_self_audit.sh`(5/5 pass)。
+**Self-test**:`bash packages/design-system/ds-canonical/hooks/tests/test_inject_pending_self_audit.sh`。
 
 ## Retired
 
-`retired/` 目錄存舊 hook(不再註冊),保留 reference 不刪除。當前已 retire 的 hook 不在本 inventory 列出 — 以 `settings.json` 為 SSOT。
+`retired/` 目錄存舊 hook(不再註冊),保留 reference 不刪除。當前已 retire 的 hook 不在本 inventory 列出 — 以 canonical `registrations.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 章節。
+本 README + 最接近的既有 canonical hook 當範本 + shared `AGENTS.md` 的 Hook 治理章節。

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

@@ -4,7 +4,7 @@
 # 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
+# Shared helper: resolve a provider-neutral runtime state directory and log per-hook fire there.
 #
 # Why: enables /knowledge-prune D2 dead-hook detection(6 月 0 fire → retire 提名)。
 # 各 hook 在 top-of-file source 本檔 + 呼叫 `log_hook_fire`。
@@ -14,24 +14,125 @@
 #
 # 規則: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.
+_governance_safe_runtime_path() {
+  python3 - "$1" "$2" <<'PY'
+import os
+import sys
+
+root_input = os.path.abspath(sys.argv[1])
+target_input = os.path.abspath(sys.argv[2])
+
+# macOS exposes /var and /tmp through system symlink aliases while Git reports
+# their physical /private/... spelling.  Compare physical paths so two names
+# for the same Git-owned directory are not mistaken for an escape.
+root = os.path.realpath(root_input)
+target = os.path.realpath(target_input)
+try:
+    if os.path.commonpath([root, target]) != root:
+        raise ValueError('escape')
+except ValueError:
+    raise SystemExit(2)
+
+# Permit only aliases that are ancestors of the Git-owned root(e.g. macOS
+# /var -> /private/var).  A symlink at, or anywhere below, the runtime root is
+# attacker-controlled runtime state and must fail closed even when it points
+# back inside the repository.
+cursor = os.path.sep
+for segment in target_input.split(os.sep)[1:]:
+    cursor = os.path.join(cursor, segment)
+    if not os.path.lexists(cursor) or not os.path.islink(cursor):
+        continue
+    resolved = os.path.realpath(cursor)
+    try:
+        inside_runtime = os.path.commonpath([root, resolved]) == root
+    except ValueError:
+        inside_runtime = False
+    if inside_runtime:
+        raise SystemExit(2)
+print(target)
+PY
+}
+
+governance_runtime_state_dir() {
+  # Telemetry is never implicit. CI, direct hook probes, and ordinary provider sessions are
+  # byte-for-byte read-only unless their trusted adapter/caller explicitly opts in.
+  [ "${GOVERNANCE_TELEMETRY_OPT_IN:-0}" = "1" ] || return 1
+  [ "${GOVERNANCE_READ_ONLY:-0}" != "1" ] || return 1
+  # Resolve the repository root without assuming a provider discovery path. Canonical hooks run
+  # below ds-canonical/, while generated Claude views run below .claude/; suffix stripping alone
+  # would write runtime telemetry into the immutable canonical source tree.
   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"
+  local _resolved_root="${GOVERNANCE_PROJECT_DIR:-}"
+  if [ -z "$_resolved_root" ]; then
+    _resolved_root="$(git -C "$_self_dir" rev-parse --show-toplevel 2>/dev/null || true)"
+  fi
+  [ -n "$_resolved_root" ] && [ -d "$_resolved_root" ] || return 1
 
-  mkdir -p "$log_dir" 2>/dev/null || return 0
+  local _git_dir _runtime_parent _allowed_root _runtime_root _state_dir
+  _git_dir="$(git -C "$_resolved_root" rev-parse --absolute-git-dir 2>/dev/null || true)"
+  # Runtime evidence is meaningful only when owned by a concrete Git repository.
+  # A no-Git temp fallback would silently create a second authority and is forbidden.
+  [ -n "$_git_dir" ] || return 1
+  _runtime_parent="$(cd "$_git_dir" 2>/dev/null && pwd -P)" || return 1
+  _allowed_root="$_runtime_parent/governance-runtime"
+  _runtime_root="${GOVERNANCE_RUNTIME_ROOT:-$_allowed_root}"
+  _runtime_root="$(_governance_safe_runtime_path "$_runtime_parent" "$_runtime_root" 2>/dev/null)" || return 1
+  [ "$_runtime_root" = "$_allowed_root" ] || return 1
+  _state_dir="${GOVERNANCE_STATE_DIR:-$_runtime_root}"
+  _state_dir="$(_governance_safe_runtime_path "$_runtime_root" "$_state_dir" 2>/dev/null)" || return 1
+  printf '%s\n' "$_state_dir"
+}
+
+governance_prepare_runtime_state_dir() {
+  local _state_dir _revalidated
+  _state_dir="$(governance_runtime_state_dir 2>/dev/null)" || return 1
+  mkdir -p -- "$_state_dir" 2>/dev/null || return 1
+  # Revalidate after creation so an existing or concurrently substituted
+  # symlink never becomes an accepted runtime directory.
+  _revalidated="$(governance_runtime_state_dir 2>/dev/null)" || return 1
+  [ "$_state_dir" = "$_revalidated" ] || return 1
+  [ -d "$_state_dir" ] && [ ! -L "$_state_dir" ] || return 1
+  printf '%s\n' "$_state_dir"
+}
+
+governance_runtime_file_path() {
+  local _name="${1:-}" _state_dir="${2:-}" _candidate
+  case "$_name" in ""|.|..) return 1 ;; esac
+  printf '%s' "$_name" | grep -qE '^[A-Za-z0-9.][A-Za-z0-9._-]*$' || return 1
+  [ -n "$_state_dir" ] || _state_dir="$(governance_runtime_state_dir 2>/dev/null)" || return 1
+  _candidate="$(_governance_safe_runtime_path "$_state_dir" "$_state_dir/$_name" 2>/dev/null)" || return 1
+  # Reject pre-existing aliases, devices, FIFOs, sockets, and hard-linked files.
+  # Telemetry must never mutate another inode through a poisoned filename.
+  python3 - "$_candidate" <<'PY' >/dev/null 2>&1 || return 1
+import os
+import stat
+import sys
+
+path = sys.argv[1]
+if os.path.lexists(path):
+    info = os.lstat(path)
+    if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+        raise SystemExit(2)
+PY
+  printf '%s\n' "$_candidate"
+}
+
+log_hook_fire() {
+  local hook_name="${1:-$(basename "${BASH_SOURCE[1]:-$0}")}"
+  local log_dir log_file archive_file
+  log_dir="$(governance_prepare_runtime_state_dir 2>/dev/null)" || return 0
+  log_file="$(governance_runtime_file_path hook-fires-per-hook.jsonl "$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
+      # 2026-06-11 fix(prune D2 抓 data-loss):原 mv 同月二次 rotation 直接覆寫 archive
+      # (實證 .202605 只存 5/31 六小時,5/31–6/10 數萬筆 fire 史遺失)→ append 後清空,不覆寫
+      archive_file="$(governance_runtime_file_path "hook-fires-per-hook.jsonl.$(date +%Y%m)" "$log_dir" 2>/dev/null)" || return 0
+      cat "$log_file" >> "$archive_file" 2>/dev/null && : > "$log_file" || true
     fi
   fi
 
@@ -40,5 +141,3 @@ log_hook_fire() {
     "$hook_name" \
     >> "$log_file" 2>/dev/null || true
 }
-
-

package/ds-canonical/hooks/auto_regen_ds_barrel.sh

@@ -0,0 +1,90 @@
+#!/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)
+
+HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd -P)" || {
+  printf 'GOVERNANCE_INTEGRITY: DS barrel hook directory is unavailable\n' >&2
+  exit 70
+}
+source "$HOOK_DIR/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: canonical hook integrity helper is unavailable\n' >&2
+  exit 70
+}
+source "$HOOK_DIR/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+governance_hook_load_input
+governance_hook_require_commands node grep tr cut
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""') \
+  || governance_hook_integrity_fail 'DS barrel file path could not be decoded'
+
+if [ -z "$FILE_PATH" ]; then exit 0; fi
+
+# Scope filter:必 packages/design-system/src/{components,patterns,hooks,lib}/**
+if ! grep -qE 'packages/design-system/src/(components|patterns|hooks|lib)/' <<<"$FILE_PATH"; then
+  exit 0
+fi
+
+# Skip stories / spec / test files(not barrel-included)
+if grep -qE '\.(stories|anatomy\.stories|principles\.stories|spec|test|spec\.md)\.(tsx?|md)$' <<<"$FILE_PATH"; then
+  exit 0
+fi
+
+PROJECT_DIR="${GOVERNANCE_PROJECT_DIR:-$(pwd)}"
+cd "$PROJECT_DIR" 2>/dev/null \
+  || governance_hook_integrity_fail "DS barrel project root is unavailable:$PROJECT_DIR"
+
+# Generator failure is an infrastructure fault,not a no-op. Never claim the SSOT is synchronized
+# after one generator failed or an attacker substituted a symlink for a canonical generator.
+for GENERATOR in scripts/gen-component-indexes.mjs scripts/gen-design-system-barrel.mjs; do
+  [ -f "$GENERATOR" ] && [ ! -L "$GENERATOR" ] \
+    || governance_hook_integrity_fail "DS barrel generator is missing or unsafe:$GENERATOR"
+done
+
+summarize_generator_failure() {
+  printf '%s' "$1" | tr '\r\n' '  ' | cut -c1-500
+}
+
+INDEX_OUT=$(node scripts/gen-component-indexes.mjs 2>&1)
+INDEX_RC=$?
+if [ "$INDEX_RC" -ne 0 ]; then
+  governance_hook_integrity_fail \
+    "component-index generator failed(exit=$INDEX_RC):$(summarize_generator_failure "$INDEX_OUT")"
+fi
+
+BARREL_OUT=$(node scripts/gen-design-system-barrel.mjs 2>&1)
+BARREL_RC=$?
+if [ "$BARREL_RC" -ne 0 ]; then
+  governance_hook_integrity_fail \
+    "design-system barrel generator failed(exit=$BARREL_RC):$(summarize_generator_failure "$BARREL_OUT")"
+fi
+
+# Only emit governance context if barrel content changed(detected by checking if grep finds count delta)
+# Simple proxy:grep "generated" in output means script ran successfully
+if grep -qE 'generated|with [0-9]+ components' <<<"$BARREL_OUT"; then
+  MESSAGE="🔄 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 變化。"
+  CONTEXT=$(jq -nc --arg message "$MESSAGE" '{
+    governanceContext: {
+      hookEventName: "PostToolUse",
+      message: $message
+    }
+  }') || governance_hook_integrity_fail 'DS barrel governance context could not be encoded'
+  printf '%s\n' "$CONTEXT"
+fi
+
+exit 0

package/ds-canonical/hooks/block_prototype_imports.py

@@ -1,30 +1,148 @@
 #!/usr/bin/env python3
 import json
+import hashlib
 import os
 import re
+import subprocess
 import sys
+import tempfile
 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.
+def integrity_failure(message):
+    print(f"GOVERNANCE_INTEGRITY: {message}", file=sys.stderr)
+    raise SystemExit(70)
+
+
+def resolve_project_root():
+    configured = os.environ.get('GOVERNANCE_PROJECT_DIR')
+    if configured and os.path.isdir(configured):
+        return os.path.realpath(os.path.abspath(configured))
+    try:
+        return subprocess.check_output(
+            ['git', '-C', os.path.dirname(os.path.abspath(__file__)), 'rev-parse', '--show-toplevel'],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except Exception:
+        # The caller classifies this as an integrity fault before path-scoped enforcement runs.
+        return ''
+
+PROJECT_ROOT = resolve_project_root()
+
+def governance_runtime_state_dir():
+    """Return the trusted provider-neutral state directory, or None.
+
+    Telemetry is opt-in and may only live below the repository's governance
+    runtime root.  This mirrors _log-fire.sh without assuming a Claude or Codex
+    discovery directory.
+    """
+    if os.environ.get('GOVERNANCE_TELEMETRY_OPT_IN', '0') != '1':
+        return None
+    if os.environ.get('GOVERNANCE_READ_ONLY', '0') == '1':
+        return None
+    if not PROJECT_ROOT or not os.path.isdir(PROJECT_ROOT):
+        return None
+
+    try:
+        git_dir = subprocess.check_output(
+            ['git', '-C', PROJECT_ROOT, 'rev-parse', '--absolute-git-dir'],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except Exception:
+        root_hash = hashlib.sha256(PROJECT_ROOT.encode()).hexdigest()[:16]
+        runtime_parent = os.path.realpath(
+            os.path.abspath(os.environ.get('TMPDIR') or tempfile.gettempdir())
+        )
+        allowed_root = os.path.join(runtime_parent, 'governance-runtime', root_hash)
+    else:
+        runtime_parent = os.path.realpath(os.path.abspath(git_dir))
+        allowed_root = os.path.join(runtime_parent, 'governance-runtime')
+
+    def safe_runtime_path(root, candidate):
+        root = os.path.abspath(root)
+        target = os.path.abspath(candidate)
+        try:
+            if os.path.commonpath([root, target]) != root:
+                return None
+        except ValueError:
+            return None
+        cursor = root
+        if os.path.lexists(cursor) and os.path.islink(cursor):
+            return None
+        relative = os.path.relpath(target, root)
+        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):
+                    return None
+        return target
+
+    runtime_root = safe_runtime_path(
+        runtime_parent,
+        os.environ.get('GOVERNANCE_RUNTIME_ROOT', allowed_root),
+    )
+    if runtime_root != allowed_root:
+        return None
+
+    state_dir = safe_runtime_path(
+        runtime_root,
+        os.environ.get('GOVERNANCE_STATE_DIR', runtime_root),
+    )
+    if state_dir is None:
+        return None
+    return state_dir
+
+
+# Per-hook fire logging (enables provider-neutral dead-hook detection). It is
+# disabled by default and never recreates a provider discovery directory.
 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')
+    _log_dir = governance_runtime_state_dir()
+    if not _log_dir:
+        raise RuntimeError('governance telemetry is disabled or untrusted')
     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/"
+# Project root for absolute→relative path normalization (real Edit/Write events carry absolute
+# file_path; prefix matching must use the same explicit/git-resolved root as enforcement).
+
+def to_project_relative(path):
+    if os.path.isabs(path) and PROJECT_ROOT:
+        return os.path.relpath(os.path.realpath(path), PROJECT_ROOT)
+    return path
 
 def load_event():
     try:
-        return json.load(sys.stdin)
-    except Exception:
-        return None
+        event = json.load(sys.stdin)
+    except Exception as error:
+        integrity_failure(f"prototype import hook input could not be parsed:{error.__class__.__name__}")
+    if not isinstance(event, dict):
+        integrity_failure("prototype import hook input must be an object")
+    if "tool_name" in event and not isinstance(event["tool_name"], str):
+        integrity_failure("prototype import hook tool_name must be a string")
+    tool_input = event.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        integrity_failure("prototype import hook tool_input must be an object")
+    for key in ("file_path",):
+        if key in tool_input and not isinstance(tool_input[key], str):
+            integrity_failure(f"prototype import hook {key} must be a string")
+    for key in ("edits", "files"):
+        values = tool_input.get(key)
+        if values is None:
+            continue
+        if not isinstance(values, list):
+            integrity_failure(f"prototype import hook {key} must be an array")
+        for item in values:
+            if not isinstance(item, dict):
+                integrity_failure(f"prototype import hook {key} entries must be objects")
+            if "file_path" in item and not isinstance(item["file_path"], str):
+                integrity_failure(f"prototype import hook {key}.file_path must be a string")
+    return event
 
 def collect_file_paths(tool_input):
     paths = []
@@ -55,13 +173,19 @@ def collect_file_paths(tool_input):
     return list(dict.fromkeys(paths))
 
 def should_check(path):
-    if not path.startswith(SRC_PREFIX):
+    normalized = path.replace("\\", "/").removeprefix("./")
+    if normalized.startswith("../") or normalized.startswith("/"):
         return False
-    if path.startswith(EXPLORATION_PREFIX):
+    if normalized.startswith("src/"):
+        source_relative = normalized[len("src/"):]
+    else:
+        match = re.match(r"^apps/[^/]+/src/(.+)$", normalized)
+        if not match:
+            return False
+        source_relative = match.group(1)
+    if source_relative.startswith("explorations/"):
         return False
-    if not (path.endswith(".ts") or path.endswith(".tsx")):
-        return False
-    return True
+    return normalized.endswith((".ts", ".tsx"))
 
 def contains_exploration_import(content):
     patterns = [
@@ -74,8 +198,8 @@ def contains_exploration_import(content):
 
 def main():
     event = load_event()
-    if not event:
-        sys.exit(0)
+    if not PROJECT_ROOT or not os.path.isdir(PROJECT_ROOT):
+        integrity_failure("prototype import hook project root could not be resolved")
 
     tool_input = event.get("tool_input", {})
     touched_paths = collect_file_paths(tool_input)
@@ -83,29 +207,35 @@ def main():
     offenders = []
 
     for path in touched_paths:
-        if not should_check(path):
-            continue
-        if not os.path.exists(path):
+        rel_path = to_project_relative(path)
+        if not should_check(rel_path):
             continue
+        abs_path = path if os.path.isabs(path) else os.path.join(PROJECT_ROOT, path)
+        if not os.path.lexists(abs_path):
+            integrity_failure(f"prototype import target is missing:{rel_path}")
+        if os.path.islink(abs_path) or not os.path.isfile(abs_path):
+            integrity_failure(f"prototype import target is unsafe:{rel_path}")
 
         try:
-            with open(path, "r", encoding="utf-8") as f:
+            with open(abs_path, "r", encoding="utf-8") as f:
                 content = f.read()
-        except Exception:
-            continue
+        except Exception as error:
+            integrity_failure(
+                f"prototype import target could not be read:{rel_path}:{error.__class__.__name__}"
+            )
 
         if contains_exploration_import(content):
-            offenders.append(path)
+            offenders.append(rel_path)
 
     if offenders:
         lines = [
             "Blocked: 正式程式碼不得 import src/explorations/ 內的檔案。"
         ]
         lines.extend(f"- {p}" for p in offenders)
-        print("\n".join(lines))
+        print("\n".join(lines), file=sys.stderr)
         sys.exit(2)
 
     sys.exit(0)
 
 if __name__ == "__main__":
-    main()
+    main()