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

package/ds-canonical/hooks/check_solo_workflow.sh

@@ -1,67 +1,64 @@
 #!/bin/bash
 set -uo pipefail
-# PreToolUse hook: enforce solo-work canonical (M28)
-# SSOT: .claude/memory/feedback_solo_dev_workflow.md + CLAUDE.md # Git solo-work canonical
+# PreToolUse hook: enforce protected-main solo-work canonical (M28)
+# SSOT: governance/memory/feedback_solo_dev_workflow.md + AGENTS.md # Git / release canonical
 #
-# Blocks 3 violations:
-#   R1. `git checkout -b claude/*` 第 2+ 次 in same session
-#       (1 chat = 1 working branch — even after merge,reuse 同 branch name)
-#   R2. PR creation (Bash gh / mcp__github__create_pull_request)
-#       (solo work = no PR ceremony)
-#   R3. Push to main / merge PR without recent user "push" trigger keyword
-#       (AI 不自決 push main,等 user 「push / OK / 好 / 合 main」 trigger)
+# Blocks 2 violations:
+#   R1. A second working branch in the same session(checkout -b or switch -c).
+#   R2. Any direct push to main. PR is the only merge path.
+# Tag/release lifecycle belongs to `release:auto` + protected workflows; the retired
+# local release-preflight R4 branch must not insert a sixth standard release gate.
 #
-# Override: CLAUDE_BYPASS_SOLO_WORKFLOW=1 (audit-logged to .claude/logs/solo-workflow-bypass.jsonl)
+# Managed recovery override: GOVERNANCE_BYPASS_SOLO_WORKFLOW=1 in the hook host
+# environment (audit-logged to neutral runtime state when opted in). Command text
+# can never activate the override.
 #
 # 違反歷史:本 hook 2026-05-08 codified — 同 session AI 開 5 個 branch + 2 PR
 # 後 user 第 3 次糾正才升 mechanical (markdown rule + memory file 都不夠)。
 
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
-# SSOT approval regex(M17 + M34 + GAP 6 codify 2026-05-18)
-source "$(dirname "$0")/lib/_approval_re.sh"
 
 set -uo pipefail
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
-TRACK_FILE="$PROJECT_DIR/.claude/logs/session-branch-track.jsonl"
-BYPASS_LOG="$PROJECT_DIR/.claude/logs/solo-workflow-bypass.jsonl"
+STATE_DIR="$(governance_runtime_state_dir 2>/dev/null || true)"
+STATE_WRITES=0
+[ -n "$STATE_DIR" ] && STATE_WRITES=1
+TRACK_FILE="$STATE_DIR/session-branch-track.jsonl"
+BYPASS_LOG="$STATE_DIR/solo-workflow-bypass.jsonl"
 
 INPUT=$(cat 2>/dev/null || echo '{}')
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
-TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
-
-# === Override flag ===
-if [ "${CLAUDE_BYPASS_SOLO_WORKFLOW:-0}" = "1" ]; then
-  mkdir -p "$(dirname "$BYPASS_LOG")"
-  printf '{"ts":"%s","tool":"%s","session":"%s"}\n' \
-    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$TOOL_NAME" "$SESSION_ID" >> "$BYPASS_LOG"
+TOOL_NAME=$(jq -r '.tool_name // .tool // empty' <<<"$INPUT" 2>/dev/null)
+SESSION_ID=$(jq -r '.session_id // empty' <<<"$INPUT" 2>/dev/null)
+
+# === Managed recovery override ===
+# Only a value injected into the hook host environment before the provider starts
+# is authoritative. Treating a token in tool_input.command as an override would
+# let the command being inspected disable its own guard.
+if [ "${GOVERNANCE_BYPASS_SOLO_WORKFLOW:-0}" = "1" ]; then
+  if [ "$STATE_WRITES" = "1" ]; then
+    mkdir -p "$STATE_DIR"
+    jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg tool "$TOOL_NAME" --arg session "$SESSION_ID" \
+      '{ts:$ts,tool:$tool,session:$session}' >> "$BYPASS_LOG"
+  fi
   exit 0
 fi
 
-# Helper: scan recent user messages for "push" trigger keywords
-has_push_trigger() {
-  [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ] && return 1
-  # Transcript JSONL schema:每 line 一 message。real user text msg = `type:"user"` AND
-  # `message.role:"user"` AND `message.content` is STRING(tool_results 的 content 是 array)。
-  jq -r 'select(.type=="user" and .message.role=="user" and (.message.content | type == "string")) | .message.content' \
-    "$TRANSCRIPT" 2>/dev/null \
-    | tail -10 \
-    | grep -qE "$APPROVAL_KEYWORD_RE"
-}
-
-# Helper: shell-aware token detect — git checkout -b claude/X(quoted-string-safe)
-# 用 shlex 真 tokenize bash command,echo "git checkout -b claude/foo" 這類
-# quoted text 內的「git checkout -b」是單一 token(arg)不會誤判為新 command。
-detect_git_checkout_b_claude() {
+# Helper: shell-aware working-branch creation detect(quoted-string-safe).
+# Recognizes both legacy checkout -b and modern switch -c for every provider prefix.
+detect_git_new_branch() {
   python3 -c "
 import shlex, sys
 try:
     tokens = shlex.split(sys.stdin.read(), comments=True)
 except Exception:
     sys.exit(1)
-for i in range(len(tokens) - 3):
-    if tokens[i] == 'git' and tokens[i+1] == 'checkout' and tokens[i+2] == '-b' and tokens[i+3].startswith('claude/'):
+for i in range(len(tokens) - 2):
+    if tokens[i] != 'git':
+        continue
+    if i + 3 < len(tokens) and tokens[i+1] == 'checkout' and tokens[i+2] in ('-b', '-B'):
+        print(tokens[i+3])
+        sys.exit(0)
+    if i + 3 < len(tokens) and tokens[i+1] == 'switch' and tokens[i+2] in ('-c', '-C'):
         print(tokens[i+3])
         sys.exit(0)
 sys.exit(1)
@@ -88,76 +85,34 @@ sys.exit(1)
 " 2>/dev/null
 }
 
-# Helper: shell-aware gh pr create / gh api pulls **WRITE** detect
-# 2026-05-09 fix(user-authorized):區分 read(default GET)vs write(POST/PATCH/PUT/DELETE)。
-# `gh api repos/.../pulls/N/comments` 預設 GET = read,**不** block;
-# `gh api -X POST repos/.../pulls`(or `-f`/`-F` field flags 暗示 POST)= 真 PR write 才 block。
-# Why:read-only API(check codex reply / read PR meta)是合法 collab,不該被 R2 PR-create 規則攔。
-detect_gh_pr_create() {
-  python3 -c "
-import shlex, sys
-try:
-    tokens = shlex.split(sys.stdin.read(), comments=True)
-except Exception:
-    sys.exit(1)
-WRITE_METHODS = {'POST', 'PATCH', 'PUT', 'DELETE'}
-for i in range(len(tokens) - 2):
-    if tokens[i] == 'gh':
-        # gh pr create — always block(create 本身是 write)
-        if tokens[i+1] == 'pr' and tokens[i+2] == 'create':
-            sys.exit(0)
-        # gh api ... pulls ... — only block if write method OR form fields(-f/-F = POST default)
-        if tokens[i+1] == 'api':
-            cmd_tokens = tokens[i:]
-            has_pulls = any('pulls' in t for t in cmd_tokens[:8])
-            if not has_pulls:
-                continue
-            # Detect explicit write method
-            for k in range(len(cmd_tokens)):
-                t = cmd_tokens[k]
-                if t in ('-X', '--method') and k + 1 < len(cmd_tokens):
-                    if cmd_tokens[k+1].upper() in WRITE_METHODS:
-                        sys.exit(0)
-                if t.startswith('--method=') and t.split('=', 1)[1].upper() in WRITE_METHODS:
-                    sys.exit(0)
-                # -f / -F flags imply POST(form fields)
-                if t in ('-f', '-F'):
-                    sys.exit(0)
-            # GET(default)= read,allow through
-sys.exit(1)
-" 2>/dev/null
-}
-
 if [ "$TOOL_NAME" = "Bash" ]; then
-  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+  COMMAND=$(jq -r '.tool_input.command // empty' <<<"$INPUT" 2>/dev/null)
 
-  # === Rule 1: git checkout -b claude/* — 1 session = 1 branch ===
-  # Use shlex tokenizer (quoted-string-safe) — echo "git checkout -b ..." 不誤判
-  NEW_BRANCH=$(echo "$COMMAND" | detect_git_checkout_b_claude)
+  # === Rule 1: 1 session = 1 working branch ===
+  # Use shlex tokenizer(quoted-string-safe)— quoted examples are not treated as commands.
+  NEW_BRANCH=$(echo "$COMMAND" | detect_git_new_branch)
   if [ -n "$NEW_BRANCH" ]; then
 
-    if [ -f "$TRACK_FILE" ] && [ -n "$SESSION_ID" ]; then
-      EXISTING=$(jq -r --arg s "$SESSION_ID" 'select(.session_id == $s) | .branch' "$TRACK_FILE" 2>/dev/null | head -1)
+    if [ "$STATE_WRITES" = "1" ] && [ -f "$TRACK_FILE" ] && [ -n "$SESSION_ID" ]; then
+      EXISTING=$(jq -rs --arg s "$SESSION_ID" 'map(select(.session_id == $s))[0].branch // empty' "$TRACK_FILE" 2>/dev/null)
       if [ -n "$EXISTING" ] && [ "$EXISTING" != "null" ] && [ "$EXISTING" != "$NEW_BRANCH" ]; then
         cat >&2 <<EOF
 
 ┄┄┄ check_solo_workflow — R1 BLOCKER (M28) ┄┄┄
 
-[P0 BLOCKER] git checkout -b $NEW_BRANCH
+[P0 BLOCKER] create second branch: $NEW_BRANCH
 
 本 session ($SESSION_ID) 已有 working branch:
   → $EXISTING
 
-❌ 1 session = 1 working branch (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
+❌ 1 session = 1 working branch (SSOT: governance/memory/feedback_solo_dev_workflow.md)。
    即使既有 branch 已 merged + deleted,本 session 內**不再開新 branch**。
 
 修法:
   1. 重用既有 branch:
-       git checkout $EXISTING
-     (若 local 已 -d 刪除,recreate from main:)
-       git checkout main && git checkout -b $EXISTING
-  2. 或 doc-only / governance-only 改 → commit 直接 main(無 Netlify preview 需求)
-  3. 例外 override:CLAUDE_BYPASS_SOLO_WORKFLOW=1 (audit logged)
+       git switch $EXISTING
+     (若 local 已刪除，從 origin 的同名 branch 恢復；不要改開第二條。)
+  2. 例外 recovery override:GOVERNANCE_BYPASS_SOLO_WORKFLOW=1 (audit logged)
 
 違反史:本 session 已開 5 branch + 2 PR,M13 trigger 升 hook 防線。
 EOF
@@ -166,93 +121,32 @@ EOF
     fi
 
     # Record new session branch (first creation OK)
-    if [ -n "$SESSION_ID" ] && [ -n "$NEW_BRANCH" ]; then
-      mkdir -p "$(dirname "$TRACK_FILE")"
+    if [ "$STATE_WRITES" = "1" ] && [ -n "$SESSION_ID" ] && [ -n "$NEW_BRANCH" ]; then
+      mkdir -p "$STATE_DIR"
       printf '{"session_id":"%s","branch":"%s","created_at":"%s"}\n' \
         "$SESSION_ID" "$NEW_BRANCH" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$TRACK_FILE"
     fi
     exit 0
   fi
 
-  # === Rule 2 (Bash gh): PR creation — shlex-aware ===
-  if echo "$COMMAND" | detect_gh_pr_create; then
-    cat >&2 <<EOF
-
-┄┄┄ check_solo_workflow — R2 BLOCKER (M28) ┄┄┄
-
-[P0 BLOCKER] PR creation via gh
-
-❌ Solo work = NO PR (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
-
-修法 — 直接 squash merge:
-  git checkout main
-  git merge --squash <working-branch>
-  git commit -m "..."
-  git push origin main
-
-或 doc-only 改 → commit 直接 main。
-EOF
-    exit 2
-  fi
-
-  # === Rule 3 (Bash): push to main without user "push" trigger — shlex-aware ===
+  # === Rule 2: direct push to main is never a supported path ===
   if echo "$COMMAND" | detect_push_main; then
-    if ! has_push_trigger; then
-      cat >&2 <<EOF
-
-┄┄┄ check_solo_workflow — R3 BLOCKER (M28) ┄┄┄
-
-[P0 BLOCKER] git push origin main
-
-❌ AI 不自決 push main (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
-   近 10 條 user message 無「push / OK / 好 / 合 main / merge / 可以」 trigger keyword。
-
-正確流程:
-  1. AI 改 code → commit + push working branch (Netlify auto-preview)
-  2. 告訴 user 主要改動 (or preview URL)
-  3. 等 user 明確 trigger 「push」/「OK」 才 merge to main
-
-例外 override:CLAUDE_BYPASS_SOLO_WORKFLOW=1 (audit logged)
-EOF
-      exit 2
-    fi
-  fi
-fi
-
-# === Rule 2 (MCP): create_pull_request ===
-if [ "$TOOL_NAME" = "mcp__github__create_pull_request" ]; then
-  cat >&2 <<EOF
-
-┄┄┄ check_solo_workflow — R2 BLOCKER (M28) ┄┄┄
-
-[P0 BLOCKER] mcp__github__create_pull_request
-
-❌ Solo work = NO PR (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
-
-修法 — 直接 squash merge to main (per Git solo-work canonical 7 步):
-  git checkout main && git merge --squash <branch> && git commit && git push origin main
-
-或 doc-only 改 → commit 直接 main。
-EOF
-  exit 2
-fi
-
-# === Rule 3 (MCP): merge_pull_request without user trigger ===
-if [ "$TOOL_NAME" = "mcp__github__merge_pull_request" ]; then
-  if ! has_push_trigger; then
     cat >&2 <<EOF
 
-┄┄┄ check_solo_workflow — R3 BLOCKER (M28) ┄┄┄
+┄┄┄ check_solo_workflow — R2 BLOCKER (M28) ┄┄┄
 
-[P0 BLOCKER] mcp__github__merge_pull_request
+[P0 BLOCKER] direct push to main
 
-❌ AI 不自決 merge PR (SSOT: .claude/memory/feedback_solo_dev_workflow.md)。
-   近 10 條 user message 無「push / OK / 好 / 合 main / merge」 trigger。
+❌ protected main 只能透過單一 PR + required checks 合併。
+	   Standing Authorization 也不是 direct-main bypass。
 
-等 user 明確 trigger 才 merge。Override:CLAUDE_BYPASS_SOLO_WORKFLOW=1
+修法:
+  1. push working branch
+  2. create/update its single PR
+		  3. required CI / conversations 全綠後用 PR merge；release 續作交給 release:auto
 EOF
-    exit 2
-  fi
+		    exit 2
+		  fi
 fi
 
 exit 0

package/ds-canonical/hooks/check_spec_class_drift.sh

@@ -9,14 +9,25 @@
 # 2026-05-17 Round 3 修(per M31 codex Round 2 catch + 自跑 smoke test catch):
 #   set -u 在 zsh 下 PHRASE UTF-8 變數 unbound — 完全不用 set -u,只用 default-empty。
 
-source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd -P)" || {
+  printf 'GOVERNANCE_INTEGRITY: spec-class 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 -e / set -u(grep find-nothing 返回 1 + zsh UTF-8 變數 unbound issue)
 # 全部 defensive `|| true` + ${VAR:-default} 處理
 
-INPUT=$(cat)
-TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+governance_hook_load_input
+governance_hook_require_commands grep head
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""') \
+  || governance_hook_integrity_fail 'spec-class tool name could not be decoded'
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""') \
+  || governance_hook_integrity_fail 'spec-class file path could not be decoded'
 
 case "${TOOL:-}" in
   Edit|Write|MultiEdit) ;;
@@ -28,13 +39,13 @@ case "${FILE_PATH:-}" in
   *) exit 0 ;;
 esac
 
-NEW_CONTENT=$(echo "$INPUT" | jq -r '
+NEW_CONTENT=$(printf '%s' "$INPUT" | jq -r '
   if .tool_input.new_string then .tool_input.new_string
   elif .tool_input.content then .tool_input.content
   else "" end
-')
+') || governance_hook_integrity_fail 'spec-class edit content could not be decoded'
 
-if echo "${NEW_CONTENT:-}" | grep -qE '@spec-class-drift-allow:'; then
+if grep -qE '@spec-class-drift-allow:' <<<"${NEW_CONTENT:-}"; then
   exit 0
 fi
 
@@ -43,7 +54,8 @@ if [ ! -f "$TSX_PATH" ]; then
   exit 0
 fi
 
-TSX_CONTENT=$(cat "$TSX_PATH" 2>/dev/null)
+TSX_CONTENT=$(cat "$TSX_PATH" 2>/dev/null) \
+  || governance_hook_integrity_fail "spec-class source could not be read:$TSX_PATH"
 TSX_CONTENT="${TSX_CONTENT:-}"
 
 WARNINGS=""
@@ -54,9 +66,9 @@ PHRASES=$(echo "${NEW_CONTENT:-}" | grep -oE '(固定|寫死|硬寫|hardcode)[[:
 if [ -n "$PHRASES" ]; then
   while IFS= read -r phrase; do
     [ -z "$phrase" ] && continue
-    class=$(echo "$phrase" | grep -oE 'h-[0-9]+' | head -1)
+    class=$(grep -m 1 -oE 'h-[0-9]+' <<<"$phrase")
     [ -z "$class" ] && continue
-    if ! echo "$TSX_CONTENT" | grep -qE "[\"' ]$class[\"' \]]"; then
+    if ! grep -qE "[\"' ]$class[\"' \]]" <<<"$TSX_CONTENT"; then
       WARNINGS="${WARNINGS}   • spec 寫「$phrase」但 tsx 不含 $class(可能已 migrate to token)
 "
     fi
@@ -66,9 +78,9 @@ EOF
 fi
 
 # Pattern 2: tsx 已消費 --chrome-header-height,spec 仍寫「固定 h-NN」
-HAS_TOKEN_TSX=$(echo "$TSX_CONTENT" | grep -c 'chrome-header-height' 2>/dev/null | head -1)
+HAS_TOKEN_TSX=$(grep -c 'chrome-header-height' <<<"$TSX_CONTENT" 2>/dev/null)
 HAS_TOKEN_TSX="${HAS_TOKEN_TSX:-0}"
-HAS_DRIFT_SPEC=$(echo "${NEW_CONTENT:-}" | grep -cE '(固定|寫死|硬寫)[[:space:]]+h-(12|14|16)' 2>/dev/null | head -1)
+HAS_DRIFT_SPEC=$(grep -cE '(固定|寫死|硬寫)[[:space:]]+h-(12|14|16)' <<<"${NEW_CONTENT:-}" 2>/dev/null)
 HAS_DRIFT_SPEC="${HAS_DRIFT_SPEC:-0}"
 if [ "$HAS_TOKEN_TSX" -gt 0 ] 2>/dev/null && [ "$HAS_DRIFT_SPEC" -gt 0 ] 2>/dev/null; then
   WARNINGS="${WARNINGS}   • tsx 已消費 --chrome-header-height token,但 spec 仍寫「固定 h-NN」— 反向 drift
@@ -76,13 +88,15 @@ if [ "$HAS_TOKEN_TSX" -gt 0 ] 2>/dev/null && [ "$HAS_DRIFT_SPEC" -gt 0 ] 2>/dev/
 fi
 
 if [ -n "$WARNINGS" ]; then
-  printf '⚠️ SPEC-CODE REVERSE DRIFT(audit Dim 53,soft P1):\n' >&2
-  printf '   Spec: %s\n' "$FILE_PATH" >&2
-  printf '   Code: %s\n' "$TSX_PATH" >&2
-  printf '%s' "$WARNINGS" >&2
-  printf '  SSOT: .claude/skills/design-system-audit/SKILL.md Group P Dim 53\n' >&2
-  printf '  修方向: 改 spec.md wording 對齊 code 實況\n' >&2
-  printf '  Escape: spec 頭加 // @spec-class-drift-allow: <rationale>\n' >&2
+  MESSAGE=$(printf '⚠️ SPEC-CODE REVERSE DRIFT(audit Dim 53,soft P1):\n   Spec: %s\n   Code: %s\n%s  SSOT: packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md Group P Dim 53\n  修方向: 改 spec.md wording 對齊 code 實況\n  Escape: spec 頭加 // @spec-class-drift-allow: <rationale>' \
+    "$FILE_PATH" "$TSX_PATH" "$WARNINGS")
+  CONTEXT=$(jq -nc --arg message "$MESSAGE" '{
+    governanceContext: {
+      hookEventName: "PreToolUse",
+      message: $message
+    }
+  }') || governance_hook_integrity_fail 'spec-class governance context could not be encoded'
+  printf '%s\n' "$CONTEXT"
 fi
 
 exit 0

package/ds-canonical/hooks/check_ssot_header_declaration.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# check_ssot_header_declaration.sh — 新建 production tsx 必帶「── 消費的 SSOT ──」宣告段
+# (2026-07-07 治理進化方向 3 洞 a:原 check_ssot_consultation.sh 2026-05-XX retired 後,
+#  canonical `rules/self-verify.md` + `references/ssot-consultation.md` 強制的檔頭宣告段
+#  **無任何機械驗證** — 內部盤點實證。本 hook = 精簡復活版,只驗「新檔有無宣告段」,
+#  不驗宣告品質(品質靠 audit dim 5 + dim 54 + M18/M29)。)
+#
+# Scope(ratchet,對齊 Polaris stylelint-adoption 策略):
+#   - 只攔 **Write 新檔**(components/ patterns/ 的 .tsx,磁碟上不存在)— 存量檔 Edit 豁免
+#   - stories / test / index.ts 豁免
+#   - escape:內容含 `@ssot-header-exempt: <rationale>`(audit 可追)
+# P0 BLOCKER(user 2026-05-27「SSOT canonical 必 P0」doctrine)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+[ "$TOOL" = "Write" ] || exit 0
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+case "$FILE_PATH" in
+  */packages/design-system/src/components/*.tsx|*/packages/design-system/src/patterns/*.tsx) ;;
+  *) exit 0 ;;
+esac
+case "$FILE_PATH" in
+  *.stories.tsx|*.test.tsx|*/index.ts|*/index.tsx) exit 0 ;;
+esac
+
+# Ratchet:磁碟已存在 = 存量覆寫,豁免(存量清理另走 audit)
+[ -f "$FILE_PATH" ] && exit 0
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
+grep -q '[^[:space:]]' <<<"$CONTENT" || exit 0
+
+# 宣告段或 escape 任一存在 → 過
+if grep -q "消費的 SSOT" <<<"$CONTENT"; then exit 0; fi
+if grep -q "@ssot-header-exempt:" <<<"$CONTENT"; then exit 0; fi
+
+cat >&2 <<'EOF'
+🚨 [P0 BLOCKER] 新建 production tsx 缺「── 消費的 SSOT ──」檔頭宣告段
+
+packages/design-system/ds-canonical/rules/self-verify.md +
+packages/design-system/ds-canonical/references/ssot-consultation.md 強制:
+新元件 tsx 開頭必列本檔消費的 components / patterns / tokens / spec(沒列 = 自創 = mindset #2 違規)。
+
+修法 — 2 選 1:
+  (a) 檔頭補宣告段(格式見 ssot-consultation.md;近例:pagination.tsx 檔頭):
+        // ── 消費的 SSOT ──
+        // - <primitive / token / spec 清單 + 消費點一句>
+  (b) 真的零 SSOT 可消費(罕見,純 utility)→ 內容加 `// @ssot-header-exempt: <rationale>`
+
+對應:mindset #2 / M23 / 治理進化 roadmap 方向 3(planning/2026-07-07-governance-evolution-roadmap.md)
+EOF
+exit 2

package/ds-canonical/hooks/check_story_determinism.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# check_story_determinism.sh — stories 寫入時 determinism 哨(2026-07-07 治理進化軌道 7)
+#
+# Why:story 用真實時間/亂數 → VR baseline 換日假 breach(anchor:2026-07-07 calendar 三 scenario
+# 0.07–0.51% 週期性假紅,三修才根治:story 釘日期 → 元件內部時間 → runner 偏移時鐘)。
+# runner 層已有偏移時鐘兜底(scripts/visual-audit.mjs),本 hook = 寫入層提前攔,
+# 讓 determinism 在出生點就成立(非 VR 撞到才修)。
+#
+# 偵測(新寫入內容):裸 `new Date()`(無參數)/ `Date.now()` / `Math.random()`。
+# escape:行內 `@nondeterministic-ok: <rationale>`(如「即時鐘 demo,VR 不截」)。
+# 第一期 WARN(exit 0):存量 10 檔(dry-run 2026-07-07,DateGrid 家族為主)未清,
+# 誤殺率驗證期後升 P0(對齊 handcraft 偵測同節奏;roadmap 方向 1 KPI 隨頻回顧)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+case "$FILE_PATH" in *.stories.tsx) ;; *) exit 0 ;; esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  (.tool_input.content // "") + "\n" +
+  (.tool_input.new_string // "") + "\n" +
+  ([.tool_input.edits[]? | .new_string] | join("\n"))
+' 2>/dev/null || echo "")
+grep -q '[^[:space:]]' <<<"$NEW_CONTENT" || exit 0
+
+HITS=$(printf '%s\n' "$NEW_CONTENT" | grep -v '@nondeterministic-ok:' | grep -nE 'new Date\(\)|Date\.now\(\)|Math\.random\(\)' || true)
+[ -z "$HITS" ] && exit 0
+
+cat >&2 <<EOF
+⚠️ [第一期 WARN] story 非決定性時間/亂數(VR baseline 換日假 breach 根因):
+$HITS
+→ 釘固定值(new Date(2026, 6, 15) / 常數 seed);真需即時值 → 行內 \`@nondeterministic-ok: <rationale>\`。
+  Anchor:2026-07-07 calendar VR 三修;runner 偏移時鐘為兜底非藉口。roadmap 方向 1(planning/2026-07-07-governance-evolution-roadmap.md)。
+EOF
+exit 0