@qijenchen/design-system 0.1.0-beta.92 → 0.1.0-beta.95

package/ds-canonical/fork/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,17 +14,115 @@
 #
 # 規則: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
@@ -33,7 +131,8 @@ log_hook_fire() {
     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
+      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
 
@@ -42,5 +141,3 @@ log_hook_fire() {
     "$hook_name" \
     >> "$log_file" 2>/dev/null || true
 }
-
-

package/ds-canonical/fork/hooks/block_prototype_imports.py

@@ -1,39 +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 比對必先轉 project-root 相對,否則 hook 永不 fire)。
-PROJECT_ROOT = os.environ.get('CLAUDE_PROJECT_DIR') or os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+# 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):
-        return os.path.relpath(path, PROJECT_ROOT)
+    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 = []
@@ -64,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 = [
@@ -83,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)
@@ -96,14 +211,18 @@ def main():
         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.exists(abs_path):
-            continue
+        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(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(rel_path)
@@ -113,10 +232,10 @@ def main():
             "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()

package/ds-canonical/fork/hooks/check_chrome_header_avatar_canonical.sh

@@ -17,13 +17,22 @@
 # 對應 audit dim 預留 — TBD 升 audit dim 65
 
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$(dirname "$0")/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: hook integrity helper unavailable\n' >&2
+  exit 70
+}
 
 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)
-EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
-NEW=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null)
+governance_hook_load_input
+governance_hook_require_commands python3
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'chrome-header tool extraction failed'
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'chrome-header path extraction failed'
+EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'chrome-header event extraction failed'
+NEW=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'chrome-header content extraction failed'
 
 [ "$EVENT" != "PreToolUse" ] && exit 0
 case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
@@ -49,19 +58,21 @@ for block in blocks:
     if re.search(r"<ItemAvatar\b", block):
         print("DRIFT")
         sys.exit(0)
-' 2>/dev/null)
+' 2>/dev/null) || governance_hook_integrity_fail 'chrome-header parser failed'
 
 [ "$HAS_DRIFT" != "DRIFT" ] && exit 0
 
 # Override env var
-if [ "${CLAUDE_BYPASS_CHROME_HEADER_AVATAR:-0}" = "1" ]; then
-  mkdir -p "$(dirname "$0")/../logs" 2>/dev/null
-  printf '{"ts":"%s","event":"chrome-header-avatar-bypass","file":"%s"}\n' \
-    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$FILE_PATH" >> "$(dirname "$0")/../logs/governance-bypass.jsonl" 2>/dev/null
+if [ "${GOVERNANCE_BYPASS_CHROME_HEADER_AVATAR:-0}" = "1" ]; then
+  if STATE_DIR="$(governance_runtime_state_dir 2>/dev/null)"; then
+    mkdir -p "$STATE_DIR" 2>/dev/null
+    jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg file "$FILE_PATH" \
+      '{ts:$ts,event:"chrome-header-avatar-bypass",file:$file}' >> "$STATE_DIR/governance-bypass.jsonl" 2>/dev/null || true
+  fi
   exit 0
 fi
 
-REL=${FILE_PATH#"$CLAUDE_PROJECT_DIR"/}
+REL=${FILE_PATH#"$GOVERNANCE_PROJECT_DIR"/}
 
 cat >&2 <<EOF
 🚨 Chrome header avatar canonical violation(per user 2026-05-27 抓 + codex collab cite battle):
@@ -87,7 +98,7 @@ Canonical citation:
 
 注意:SidebarFooter 內 ItemAvatar OK(footer 是 SidebarMenu row context)。本 hook 只攔 SidebarHeader。
 
-Bypass(極罕見):CLAUDE_BYPASS_CHROME_HEADER_AVATAR=1 env var(audit-logged)。
+Bypass(極罕見):GOVERNANCE_BYPASS_CHROME_HEADER_AVATAR=1 env var(audit-logged)。
 EOF
 # 2026-05-31:exit 0 → exit 2(folded-hook-audit:原宣稱 BLOCKER 但 exit 0 = 假 enforcement;
 # chrome-header avatar 是 SSOT canonical [feedback_ssot_mechanical_p0_not_p1 = 必 P0 BLOCK],