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

package/ds-canonical/hooks/tests/test_stop_self_audit.sh

@@ -2,41 +2,183 @@
 # Smoke + behavior test for stop_self_audit.sh
 # 2026-04-30:升 BLOCKER 行為(Mechanism 1 claim-verify gap)後加 case 2-4
 set -u
-HOOK="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../stop_self_audit.sh"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../stop_self_audit.sh"
 [ -x "$HOOK" ] || { echo "FATAL: hook not executable"; exit 1; }
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null)" || {
+  echo "FATAL: canonical hook test is not inside a Git worktree"
+  exit 1
+}
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd -P)"
 
-PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
 TMPDIR=$(mktemp -d)
+if [ -z "${TMPDIR:-}" ] || [ ! -d "$TMPDIR" ]; then
+  echo "❌ mktemp -d failed;fixture unavailable" >&2
+  exit 1
+fi
 trap 'rm -rf "$TMPDIR"' EXIT
+PROJECT_DIR="$TMPDIR/project"
+mkdir -p "$PROJECT_DIR/scripts/lib" \
+  "$PROJECT_DIR/packages/design-system/src/components/Button"
+git -C "$PROJECT_DIR" init -q
+GIT_DIR="$(git -C "$PROJECT_DIR" rev-parse --absolute-git-dir)"
+GIT_DIR="$(cd "$GIT_DIR" && pwd -P)"
+EVIDENCE_ROOT="$GIT_DIR/governance-runtime/evidence"
+cp "$REPO_ROOT/scripts/lib/governance-runtime-evidence.mjs" "$PROJECT_DIR/scripts/lib/governance-runtime-evidence.mjs"
+cp "$REPO_ROOT/packages/governance/src/closed-tool-execution.mjs" "$PROJECT_DIR/scripts/lib/closed-tool-execution.mjs"
+cat > "$PROJECT_DIR/scripts/verify-deep-audit-coverage.mjs" <<'VERIFY_FIXTURE'
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const selfIndex = process.argv.indexOf('--self-provider')
+const peerIndex = process.argv.indexOf('--peer-provider')
+const selfIsExact = selfIndex >= 0 && process.argv[selfIndex + 1] === 'alpha'
+const stateRoot = process.env.GOVERNANCE_STATE_DIR
+const neutralReceipt = stateRoot
+  ? resolve(stateRoot, '..', 'evidence/deep-audit/fixture-complete.json')
+  : null
+let receipt = null
+try { receipt = neutralReceipt && existsSync(neutralReceipt) ? JSON.parse(readFileSync(neutralReceipt, 'utf8')) : null } catch {}
+const immutableProviderClosure = receipt?.secondOpinion === 'waived-by-user'
+  || (receipt?.secondOpinion === 'completed' && receipt?.peerEvidence === true)
+process.exit(selfIsExact && peerIndex === -1 && immutableProviderClosure ? 0 : 1)
+VERIFY_FIXTURE
+{
+  echo 'const DIMS = {'
+  for dim in $(seq 1 91); do
+    case "$dim" in
+      2) tier='PURE-JUDGMENT' ;;
+      3) tier='HOOK-ENFORCED' ;;
+      4) tier='CI-ENFORCED' ;;
+      *) tier='DETERMINISTIC' ;;
+    esac
+    printf "  %s: { tier: '%s' },\n" "$dim" "$tier"
+  done
+  echo '}'
+} > "$PROJECT_DIR/scripts/audit-coverage-matrix.mjs"
+printf 'export const Button = 1\n' > "$PROJECT_DIR/packages/design-system/src/components/Button/button.tsx"
+export GOVERNANCE_PROJECT_DIR="$PROJECT_DIR"
+export GOVERNANCE_STATE_DIR="$GIT_DIR/governance-runtime/state"
+export GOVERNANCE_READ_ONLY=1
+export GOVERNANCE_SELF_PROVIDER=alpha
+export GOVERNANCE_SELF_DISPLAY_NAME="Alpha"
+export GOVERNANCE_PEER_PROVIDER=beta
+export GOVERNANCE_PEER_DISPLAY_NAME="Beta"
+export GOVERNANCE_PEER_CLI=beta
+export GOVERNANCE_PEER_LOCAL_EXECUTABLE=node_modules/.bin/beta
+export GOVERNANCE_PEER_REPLY_ARTIFACT_PREFIX=beta-reply
+export GOVERNANCE_PEER_DISCOVERY_MARKERS_JSON='["node_modules/.bin/beta","command -v beta"]'
+export GOVERNANCE_INSTRUCTION_ENTRY=AGENTS.md
+export GOVERNANCE_SHARED_INSTRUCTION_ENTRY=AGENTS.md
 
 PASS=0; FAIL=0
 run_test() {
-  local name="$1"; local expect_block="$2"; local transcript_content="$3"
+  local name="$1"; local expect_block="$2"; local transcript_content="$3"; local direct_message="${4:-}"
   local transcript="$TMPDIR/transcript-$$.jsonl"
   printf '%s\n' "$transcript_content" > "$transcript"
   local input
-  input=$(printf '{"transcript_path":"%s","session_id":"test"}' "$transcript")
-  # Reset state to avoid block-once dedup interference
-  rm -f "$PROJECT_DIR/.claude/logs/.last-blocked-claim.txt" 2>/dev/null
-  local stdout; stdout=$(echo "$input" | bash "$HOOK" 2>/dev/null)
+  input=$(jq -nc --arg path "$transcript" --arg message "$direct_message" \
+    '{transcript_path:$path,session_id:"test",last_assistant_message:$message}')
+  local stdout stderr_file exit_code
+  stderr_file=$(mktemp)
+  set +e
+  stdout=$(echo "$input" | bash "$HOOK" 2>"$stderr_file")
+  exit_code=$?
+  set -e
   if [ "$expect_block" = "1" ]; then
-    if echo "$stdout" | grep -q '"decision":"block"'; then
+    if [ "$exit_code" = "0" ] && echo "$stdout" | grep -q '"governanceDecision":"block"'; then
       echo "  PASS  $name (blocked as expected)"; PASS=$((PASS+1))
     else
-      echo "  FAIL  $name (expected block, got: ${stdout:0:120})"; FAIL=$((FAIL+1))
+      echo "  FAIL  $name (expected block, exit=$exit_code, got: ${stdout:0:120}, stderr: $(head -c 160 "$stderr_file"))"; FAIL=$((FAIL+1))
     fi
   else
-    if echo "$stdout" | grep -q '"decision":"block"'; then
+    if [ "$exit_code" != "0" ]; then
+      echo "  FAIL  $name (unexpected exit=$exit_code, stderr: $(head -c 160 "$stderr_file"))"; FAIL=$((FAIL+1))
+    elif echo "$stdout" | grep -q '"governanceDecision":"block"'; then
       echo "  FAIL  $name (unexpected block: ${stdout:0:120})"; FAIL=$((FAIL+1))
     else
       echo "  PASS  $name (no block)"; PASS=$((PASS+1))
     fi
   fi
+  rm -f "$stderr_file"
+}
+
+run_exact_io_test() {
+  local name="$1"; local expected_stdout="$2"; local input_file="$3"
+  local sequence=$((PASS + FAIL + 1))
+  local stdout_file="$TMPDIR/exact-stdout-$sequence"
+  local stderr_file="$TMPDIR/exact-stderr-$sequence"
+  local exit_code
+
+  bash "$HOOK" < "$input_file" > "$stdout_file" 2> "$stderr_file"
+  exit_code=$?
+
+  local stdout_ok=0
+  if [ "$expected_stdout" = "empty" ]; then
+    [ ! -s "$stdout_file" ] && stdout_ok=1
+  elif [ "$expected_stdout" = "claim-block" ]; then
+    if [ "$(wc -l < "$stdout_file" | tr -d ' ')" = "1" ] \
+      && jq -e -s '
+        length == 1
+        and (.[0].governanceDecision == "block")
+        and ((.[0].reason // "") | contains("CLAIM-VERIFY GAP BLOCKER"))
+      ' "$stdout_file" >/dev/null 2>&1; then
+      stdout_ok=1
+    fi
+  fi
+
+  if [ "$exit_code" = "0" ] && [ "$stdout_ok" = "1" ] && [ ! -s "$stderr_file" ]; then
+    echo "  PASS  $name (exit=0, stdout=$expected_stdout, stderr=empty)"
+    PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (exit=$exit_code, stdout-bytes=$(wc -c < "$stdout_file" | tr -d ' '), stderr-bytes=$(wc -c < "$stderr_file" | tr -d ' '))"
+    FAIL=$((FAIL+1))
+  fi
+}
+
+peer_edit_transcript() {
+  local user_text="$1"
+  local operation_text="$2"
+  local assistant_text="${3:-Layer A own: inspected independently. Layer C dissent: retained only supported evidence.}"
+  local target="packages/design-system/src/components/Button/button.tsx"
+  jq -nc --arg text "$user_text" \
+    '{message:{role:"user",content:[{type:"text",text:$text}]}}'
+  jq -nc \
+    '{message:{role:"assistant",content:[{type:"tool_use",name:"Read",input:{file_path:"/tmp/beta-reply-review.md"}}]}}'
+  jq -nc --arg target "$target" \
+    '{message:{role:"assistant",content:[{type:"tool_use",name:"Read",input:{file_path:$target}}]}}'
+  jq -nc --arg target "$target" --arg operation "$operation_text" \
+    '{message:{role:"assistant",content:[{type:"tool_use",name:"Edit",input:{file_path:$target,new_string:$operation}}]}}'
+  jq -nc --arg text "$assistant_text" \
+    '{message:{role:"assistant",content:[{type:"text",text:$text}]}}'
+}
+
+peer_operation_digest() {
+  jq -cjn \
+    --arg file_path "packages/design-system/src/components/Button/button.tsx" \
+    --arg new_string "$1" \
+    '{file_path:$file_path,new_string:$new_string}' \
+    | shasum -a 256 | cut -d ' ' -f1
 }
 
 echo "Test 1: minimal payload → no crash"
 out=$(echo '{}' | bash "$HOOK" 2>&1); exit_code=$?
-[ "$exit_code" -le 2 ] && echo "  PASS exit=$exit_code" && PASS=$((PASS+1)) || { echo "  FAIL exit=$exit_code"; FAIL=$((FAIL+1)); }
+if [ "$exit_code" = "0" ] && ! echo "$out" | grep -q "GOVERNANCE_INTEGRITY:"; then
+  echo "  PASS exit=$exit_code"; PASS=$((PASS+1))
+else
+  echo "  FAIL exit=$exit_code output=${out:0:120}"; FAIL=$((FAIL+1))
+fi
+
+# Config faults are infrastructure failures,not policy decisions.
+export GOVERNANCE_PEER_REPLY_ARTIFACT_PREFIX=invalid
+out=$(echo '{}' | bash "$HOOK" 2>&1)
+exit_code=$?
+if [ "$exit_code" = "70" ] && echo "$out" | grep -q "GOVERNANCE_INTEGRITY:"; then
+  echo "  PASS  Test 1b invalid peer config → integrity 70"; PASS=$((PASS+1))
+else
+  echo "  FAIL  Test 1b expected integrity 70, got exit=$exit_code output=${out:0:120}"; FAIL=$((FAIL+1))
+fi
+export GOVERNANCE_PEER_REPLY_ARTIFACT_PREFIX=beta-reply
 
 # Test 2: claim「verified」+ no tsc → BLOCK
 # NOTE(2026-05-01): hook find last 真 user prompt(role=user 且 content
@@ -69,8 +211,280 @@ T6="$USER_MSG
 "'{"message":{"role":"assistant","content":[{"type":"text","text":"我這次明確不 claim verified,只 tsc 過,實際 browser 行為要 user 驗"}]}}'
 run_test "Test 6: preemptive claim denial → no block" 0 "$T6"
 
-# Cleanup state file
-rm -f "$PROJECT_DIR/.claude/logs/.last-blocked-claim.txt" 2>/dev/null
+# Test 7: Mechanism 7 完整性宣告閘 — 宣告「全部做完」+ 2 edits + 無全庫掃描 → BLOCK
+T7="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Edit","input":{}}]}}
+{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Write","input":{}}]}}
+{"message":{"role":"assistant","content":[{"type":"text","text":"全部做完了,beta 已上架,tree 乾淨。"}]}}'
+run_test "Test 7: M7 完整性宣告+多改+無掃描 → block" 1 "$T7"
+
+# Test 8: 同上但本 turn 有 grep -rn 全庫掃描 → no block(掃描證據被認列)
+T8="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Edit","input":{}}]}}
+{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Bash","input":{"command":"grep -rn foo .claude packages"}}]}}
+{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Write","input":{}}]}}
+{"message":{"role":"assistant","content":[{"type":"text","text":"全部做完了,已全庫掃描確認無 loose end。"}]}}'
+run_test "Test 8: M7 完整性宣告+多改+有全庫掃描 → no block" 0 "$T8"
+
+# Test 9: M7 negation 排除 — 含「全做完」字串但是 disclaimer(還沒說全做完)+ 多改 + 無掃描 → NO block
+T9="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Edit","input":{}}]}}
+{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Write","input":{}}]}}
+{"message":{"role":"assistant","content":[{"type":"text","text":"還沒說「全做完」——等 beta.51 落地 + 最後掃過才有資格。核心做完,完整性掃描待跑。"}]}}'
+run_test "Test 9: M7 negation disclaimer(還沒說全做完)→ no block" 0 "$T9"
+
+# Test 10: a complete-looking legacy/provider-local ledger must not satisfy deep-audit completion.
+mkdir -p "$PROJECT_DIR/.claude/logs/dim-audit" "$PROJECT_DIR/.claude/logs/codex-dim-audit" \
+  "$PROJECT_DIR/.claude/logs/hook-residue" "$PROJECT_DIR/.claude/logs/claude-a1b-deep" \
+  "$PROJECT_DIR/.claude/logs/codex-phaseB"
+printf '── dim 1: poison\n   exit=0\n' > "$PROJECT_DIR/.claude/logs/dim-audit/_deterministic-results.txt"
+printf '%s\n' '{"dim":2,"filesScanned":1,"findings":[]}' > "$PROJECT_DIR/.claude/logs/dim-audit/dim-2.json"
+cp "$PROJECT_DIR/.claude/logs/dim-audit/dim-2.json" "$PROJECT_DIR/.claude/logs/codex-dim-audit/dim-2.json"
+printf '%s\n' '{"dim":3,"hook":"poison","residueCount":0,"findings":[]}' > "$PROJECT_DIR/.claude/logs/hook-residue/dim-3.json"
+printf '%s\n' '{"component":"Button","claimsVerified":1,"falseClaims":[]}' > "$PROJECT_DIR/.claude/logs/claude-a1b-deep/Button.json"
+cp "$PROJECT_DIR/.claude/logs/claude-a1b-deep/Button.json" "$PROJECT_DIR/.claude/logs/codex-phaseB/Button.json"
+set +e
+(cd "$PROJECT_DIR" && node scripts/verify-deep-audit-coverage.mjs --self-provider alpha >/dev/null 2>&1)
+VERIFY_FIXTURE_EXIT=$?
+set -e
+[ "$VERIFY_FIXTURE_EXIT" = "1" ] || { echo "FATAL: incomplete verifier fixture must exit 1, got $VERIFY_FIXTURE_EXIT"; exit 1; }
+T10="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"text","text":"deep audit 完成"}]}}'
+run_test "Test 10: poisoned .claude deep-audit ledger → block" 1 "" "deep audit 完成"
+
+# Test 11: the hook accepts a manifest-authorized one-run waiver after `.claude` deletion,
+# and never forwards adapter-injected ambient peer metadata as a verifier assertion.
+# Full immutable run/envelope closure belongs to scripts/test-verify-deep-audit-coverage.mjs;
+# this focused fixture proves argument wiring and that provider-home poison is never authority.
+mkdir -p "$EVIDENCE_ROOT/deep-audit"
+printf '%s\n' '{"secondOpinion":"waived-by-user"}' > "$EVIDENCE_ROOT/deep-audit/fixture-complete.json"
+rm -rf "$PROJECT_DIR/.claude"
+run_test "Test 11: waived immutable run + ambient peer + deleted .claude → no block" 0 "" "deep audit 完成"
+[ ! -e "$PROJECT_DIR/infra/governance/runtime" ] || { echo "  FAIL  deep-audit evidence mutated workspace runtime"; FAIL=$((FAIL+1)); }
+
+# A waived run remains valid when the adapter has no peer runtime at all.
+unset GOVERNANCE_PEER_PROVIDER GOVERNANCE_PEER_DISPLAY_NAME GOVERNANCE_PEER_CLI \
+  GOVERNANCE_PEER_LOCAL_EXECUTABLE GOVERNANCE_PEER_REPLY_ARTIFACT_PREFIX \
+  GOVERNANCE_PEER_DISCOVERY_MARKERS_JSON
+run_test "Test 11b: waived immutable run + no peer runtime → no block" 0 "" "deep audit 完成"
+
+# Merely switching prose/context to no peer cannot waive a selected run: the
+# immutable verifier still requires the selected peer's complete evidence.
+printf '%s\n' '{"secondOpinion":"completed","peerEvidence":false}' > "$EVIDENCE_ROOT/deep-audit/fixture-complete.json"
+run_test "Test 11c: selected run without peer evidence → block" 1 "" "稽核全部完成"
+printf '%s\n' '{"secondOpinion":"completed","peerEvidence":true}' > "$EVIDENCE_ROOT/deep-audit/fixture-complete.json"
+run_test "Test 11d: selected run with complete peer evidence → no block" 0 "" "deep audit 完成"
+
+# Restore the normal registry-resolved peer context for the peer-specific hook tests below.
+export GOVERNANCE_PEER_PROVIDER=beta
+export GOVERNANCE_PEER_DISPLAY_NAME="Beta"
+export GOVERNANCE_PEER_CLI=beta
+export GOVERNANCE_PEER_LOCAL_EXECUTABLE=node_modules/.bin/beta
+export GOVERNANCE_PEER_REPLY_ARTIFACT_PREFIX=beta-reply
+export GOVERNANCE_PEER_DISCOVERY_MARKERS_JSON='["node_modules/.bin/beta","command -v beta"]'
+
+# Tests 12-14: inputs larger than a pipe buffer must preserve exact policy and I/O contracts.
+# Put each positive marker at the beginning so a producer→`grep -q` implementation would close
+# the pipe early and reproduce the historical Bash `echo: write error: Broken pipe` failure.
+LARGE_DIRECT_TEXT="$TMPDIR/large-direct-assistant.txt"
+{
+  printf 'deep audit 完成 '
+  awk 'BEGIN { for (i = 0; i < 300000; i++) printf "x" }'
+} > "$LARGE_DIRECT_TEXT"
+LARGE_DIRECT_INPUT="$TMPDIR/large-direct-input.json"
+{
+  printf '{"session_id":"test","last_assistant_message":'
+  jq -cRs . < "$LARGE_DIRECT_TEXT"
+  printf '}\n'
+} > "$LARGE_DIRECT_INPUT"
+
+if [ "$(wc -c < "$LARGE_DIRECT_TEXT" | tr -d ' ')" -gt 262144 ]; then
+  run_exact_io_test "Test 12: >256KiB direct assistant early deep-audit match" empty "$LARGE_DIRECT_INPUT"
+else
+  echo "  FAIL  Test 12 fixture is not larger than 256KiB"; FAIL=$((FAIL+1))
+fi
+
+LARGE_CLAIM_TEXT="$TMPDIR/large-transcript-assistant.txt"
+{
+  printf 'verified '
+  awk 'BEGIN { for (i = 0; i < 300000; i++) printf "x" }'
+} > "$LARGE_CLAIM_TEXT"
+LARGE_NO_VERIFY_TRANSCRIPT="$TMPDIR/large-no-verify.jsonl"
+printf '%s\n' "$USER_MSG" > "$LARGE_NO_VERIFY_TRANSCRIPT"
+jq -cRs '{message:{role:"assistant",content:[{type:"text",text:.}]}}' \
+  < "$LARGE_CLAIM_TEXT" >> "$LARGE_NO_VERIFY_TRANSCRIPT"
+LARGE_NO_VERIFY_INPUT="$TMPDIR/large-no-verify-input.json"
+jq -nc --arg path "$LARGE_NO_VERIFY_TRANSCRIPT" \
+  '{transcript_path:$path,session_id:"test"}' > "$LARGE_NO_VERIFY_INPUT"
+
+if [ "$(wc -c < "$LARGE_NO_VERIFY_TRANSCRIPT" | tr -d ' ')" -gt 262144 ]; then
+  run_exact_io_test "Test 13: >256KiB transcript early claim without verify" claim-block "$LARGE_NO_VERIFY_INPUT"
+else
+  echo "  FAIL  Test 13 fixture is not larger than 256KiB"; FAIL=$((FAIL+1))
+fi
+
+LARGE_WITH_VERIFY_TRANSCRIPT="$TMPDIR/large-with-verify.jsonl"
+printf '%s\n' "$USER_MSG" > "$LARGE_WITH_VERIFY_TRANSCRIPT"
+printf '%s\n' \
+  '{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Bash","input":{"command":"npx tsc -b"}}]}}' \
+  >> "$LARGE_WITH_VERIFY_TRANSCRIPT"
+jq -cRs '{message:{role:"assistant",content:[{type:"text",text:.}]}}' \
+  < "$LARGE_CLAIM_TEXT" >> "$LARGE_WITH_VERIFY_TRANSCRIPT"
+LARGE_WITH_VERIFY_INPUT="$TMPDIR/large-with-verify-input.json"
+jq -nc --arg path "$LARGE_WITH_VERIFY_TRANSCRIPT" \
+  '{transcript_path:$path,session_id:"test"}' > "$LARGE_WITH_VERIFY_INPUT"
+run_exact_io_test "Test 14: >256KiB transcript early verify marker" empty "$LARGE_WITH_VERIFY_INPUT"
+
+# Tests 15-20: Mechanism 4 consumes the same target-bound decision parser as preflight.
+T15=$(peer_edit_transcript \
+  "請修復 Button 的 TypeScript null bug" \
+  'const nextValue = normalizeValue(value)')
+run_test "Test 15: peer + exact production engineering remediation → no approval block" 0 "$T15"
+
+T16_OPERATION='return <button className="bg-blue-500 hover:bg-blue-600" />'
+T16_OPERATION_SHA=$(peer_operation_digest "$T16_OPERATION")
+T16=$(peer_edit_transcript \
+  "Button hover 顏色採用藍色並請修改 Button operation sha256:$T16_OPERATION_SHA" \
+  "$T16_OPERATION")
+run_test "Test 16: peer + exact target-bound UI choice → no approval block" 0 "$T16"
+
+T17=$(peer_edit_transcript \
+  "go ahead，全部做完" \
+  'return <button className="bg-blue-500 hover:bg-blue-600" />')
+run_test "Test 17: peer + generic directive + UI operation → block" 1 "$T17"
+
+T18=$(peer_edit_transcript \
+  "所有 engineering bug、refactor、test、governance、infra remediation 都授權直接完成" \
+  'return <button className="bg-blue-500 hover:bg-blue-600" />')
+run_test "Test 18: peer + standing engineering delegation + UI operation → block" 1 "$T18"
+
+T18A=$(peer_edit_transcript \
+  "所有 engineering bug、refactor、test、governance、infra remediation 都授權直接完成" \
+  'const nextValue = normalizeValue(value)')
+run_test "Test 18a: peer + standing engineering delegation + pure engineering operation → no approval block" 0 "$T18A"
+
+T18B=$(peer_edit_transcript \
+  "請修正 Button 的 a11y aria-expanded regression，使其符合既有規格" \
+  'return <button aria-expanded={open}>Save</button>')
+run_test "Test 18b: peer + exact existing a11y remediation → no approval block" 0 "$T18B"
+
+T18C=$(peer_edit_transcript \
+  "請修復 Button 的 keyboard interaction behavior bug" \
+  'return <button onKeyDown={handleKeyDown}>Save</button>')
+run_test "Test 18c: peer + exact existing behavior remediation → no approval block" 0 "$T18C"
+
+T18D=$(peer_edit_transcript \
+  "Button hover 顏色紅色還是藍色由你自行決定" \
+  'return <button className="hover:bg-blue-500" />')
+run_test "Test 18d: peer + unresolved target UI choice → block" 1 "$T18D"
+
+T18E=$(peer_edit_transcript \
+  "請修復 Button hover bug 但紅色還是藍色由你自行決定" \
+  'return <button className="hover:bg-blue-500" />')
+run_test "Test 18e: peer + remediation wording cannot bypass unresolved UI choice" 1 "$T18E"
+
+T18F_DENIAL=$(printf '保持 Button 不\342\200\213變')
+T18F=$(peer_edit_transcript \
+  "$T18F_DENIAL" \
+  'return <button className="hover:bg-blue-500" />')
+run_test "Test 18f: peer + default-ignorable denial remains blocked" 1 "$T18F"
+
+T18G=$(peer_edit_transcript \
+  "下面是別人的建議 不代表我的決定：「Button hover 顏色採用藍色 operation sha256:${T16_OPERATION_SHA}」" \
+  "$T16_OPERATION")
+run_test "Test 18g: peer + quoted non-authoritative product statement → block" 1 "$T18G"
+
+T18H=$(peer_edit_transcript \
+  "Button 顏色請你選擇最佳方案 operation sha256:$T16_OPERATION_SHA" \
+  "$T16_OPERATION")
+run_test "Test 18h: peer + delegated unresolved product choice → block" 1 "$T18H"
+
+T18I=$(peer_edit_transcript \
+  "請修復所有既有 a11y regression 但紅色還是藍色由你自行決定" \
+  "$T16_OPERATION")
+run_test "Test 18i: peer + global remediation carrying unresolved UI choice → block" 1 "$T18I"
+
+for denial in \
+  "Button hover 不採用藍色 operation sha256:$T16_OPERATION_SHA" \
+  "Button hover 不要使用藍色 operation sha256:$T16_OPERATION_SHA" \
+  "Do not use blue for Button hover operation sha256:$T16_OPERATION_SHA"; do
+  T18J=$(peer_edit_transcript "$denial" "$T16_OPERATION")
+  run_test "Test 18j: peer + negated use/adopt remains blocked" 1 "$T18J"
+done
+
+while IFS= read -r non_authoritative; do
+  T18K=$(peer_edit_transcript "$non_authoritative" "$T16_OPERATION")
+  run_test "Test 18k: peer + attribution/tentative/conditional variant remains blocked" 1 "$T18K"
+done <<NON_AUTHORITATIVE_UI_VARIANTS
+Reviewer 說：「Button hover 顏色改成藍色 operation sha256:${T16_OPERATION_SHA}」
+也許 Button hover 顏色改成藍色 operation sha256:${T16_OPERATION_SHA}
+等客戶同意後，把 Button hover 顏色改成藍色 operation sha256:${T16_OPERATION_SHA}
+NON_AUTHORITATIVE_UI_VARIANTS
+
+for reference_only in \
+  "Use Button as a guide and set Input hover color to blue operation sha256:$T16_OPERATION_SHA" \
+  "以 Button 為參考並讓 Input hover 顏色採用藍色 operation sha256:$T16_OPERATION_SHA"; do
+  T18L=$(peer_edit_transcript "$reference_only" "$T16_OPERATION")
+  run_test "Test 18l: peer + reference-role variant cannot bind Button" 1 "$T18L"
+done
+
+for global_resolved_choice in \
+  "請修復所有既有 UI regression，顏色統一改成藍色 operation sha256:$T16_OPERATION_SHA" \
+  "請修復所有既有 UI regression 並把所有 UI 顏色改成藍色 operation sha256:$T16_OPERATION_SHA"; do
+  T18M=$(peer_edit_transcript "$global_resolved_choice" "$T16_OPERATION")
+  run_test "Test 18m: peer + global remediation carrying resolved UI choice → block" 1 "$T18M"
+done
+
+OLDER_UI_APPROVAL=$(jq -nc --arg text "Button hover 顏色採用藍色，請修改 Button" \
+  '{message:{role:"user",content:[{type:"text",text:$text}]}}')
+T19="$OLDER_UI_APPROVAL
+$(peer_edit_transcript \
+  "撤銷 Button 的 UI 修改核准，先不要修改 Button" \
+  'return <button className="bg-blue-500" />' \
+  'Layer A own: edit already happened. 撤回採納 beta。Layer C dissent: user denial controls.')"
+run_test "Test 19: target denial wins even when peer retract marker exists" 1 "$T19"
+
+OLDER_UI_REMEDIATION=$(jq -nc --arg text \
+  "請修復 Button 的 a11y regression，對齊既有規格" \
+  '{message:{role:"user",content:[{type:"text",text:$text}]}}')
+LATER_UI_REVOCATION=$(jq -nc --arg text \
+  "撤銷 Button 修改授權，先不要修改 Button" \
+  '{message:{role:"user",content:[{type:"text",text:$text}]}}')
+T19A="$OLDER_UI_REMEDIATION
+$LATER_UI_REVOCATION
+$(peer_edit_transcript \
+  "go ahead" \
+  'return <button aria-expanded={open}>Save</button>')"
+run_test "Test 19a: generic continuation cannot jump over later target revocation" 1 "$T19A"
+
+OLDER_BOUND_UI_APPROVAL=$(jq -nc \
+  --arg text "Button hover 顏色採用藍色 operation sha256:$T16_OPERATION_SHA" \
+  '{message:{role:"user",content:[{type:"text",text:$text}]}}')
+LATER_INPUT_REMEDIATION=$(jq -nc --arg text \
+  "請修復 Input 的 hover regression，對齊既有規格" \
+  '{message:{role:"user",content:[{type:"text",text:$text}]}}')
+T19B="$OLDER_BOUND_UI_APPROVAL
+$LATER_INPUT_REMEDIATION
+$(peer_edit_transcript \
+  "go ahead" \
+  "$T16_OPERATION")"
+run_test "Test 19b: generic continuation cannot revive older Button approval after Input scope" 1 "$T19B"
+
+T19C="$OLDER_BOUND_UI_APPROVAL
+$(peer_edit_transcript \
+  "Actually, don't do that" \
+  "$T16_OPERATION")"
+run_test "Test 19c: latest targetless revocation terminates old Button approval" 1 "$T19C"
+
+T20=$(peer_edit_transcript \
+  "不要等待核准，繼續修復 Button 的 TypeScript bug" \
+  'const nextValue = normalizeValue(value)')
+run_test "Test 20: no-wait clause + exact engineering operation → no approval block" 0 "$T20"
+
+T20A=$(peer_edit_transcript \
+  "請修復 Input 的 TypeScript null bug" \
+  'const nextValue = normalizeValue(value)')
+run_test "Test 20a: wrong-target engineering intent cannot authorize Button → block" 1 "$T20A"
 
 echo "Results: $PASS PASS, $FAIL FAIL"
 [ "$FAIL" -eq 0 ] || exit 1

package/ds-canonical/references/README.md

@@ -1,22 +1,30 @@
-# .claude/references/ Charter
+# Canonical references charter
 
 ## 這裡只收:**agent infrastructure reference**(非 product canonical)
 
-Agent 在執行時按需讀的深度 reference 檔 — audit protocol / FP 記憶 / workflow recipe / lookup tables。**不是 product design canonical**(那該進 spec.md / CLAUDE.md)。
+Agent 在執行時按需讀的深度 reference 檔 — audit protocol / FP 記憶 / workflow recipe / lookup tables。**不是 product design canonical**(那該進 spec.md / `packages/design-system/ds-canonical/rules/*.md`)。
 
-## 當前居民(15 檔,2026-05-18 update)
+## 當前居民
 
 | Ref | 用途 |
 |-----|------|
-| `audit-coverage-vs-24-checklist.md` | 業界 24-checklist 對照 + 為何不平行 audit 24 dim rationale |
 | `build-ui-canonicals.md` | 建 UI 前 12 情境 + 8 layout primitive lookup |
-| `cva-patterns.md` | cva 適用 / 不適用 + 例外清單(跟 CLAUDE.md shadcn 規範互補) |
-| `drag-canonical.md` | 世界級 drag impl 對照 + dnd-kit collision strategy + Phase 1/2 fix plan |
+| `certified-surfaces.md` | Provider surface certification policy；machine ledger 仍是唯一狀態 authority |
+| `composition-fidelity.md` | Composition fidelity SSOT — consumer 用對 DS(conformance)為主,靜態 lint 驗(對齊 Polaris/Atlassian/Carbon);pixel/DOM identity diff 改 opt-in(2026-06-02 model 修正,非追求 product-vs-showcase 一致) |
+| `cva-patterns.md` | cva 適用 / 不適用 + 例外清單(跟 canonical `packages/design-system/ds-canonical/rules/ui-development.md` shadcn 規範互補) |
+| `drag-canonical.md` | 現行 drag behavior/visual ownership、DataTable/TreeView 能力矩陣與保留中的未來擴充邊界 |
+| `failure-class-registry.json` | 被抓過的 failure class → mechanical defense／judgment audit 的封閉追蹤表 |
+| `governance-audit-coverage.md` | 治理 home × 稽核機制 × 執行頻率覆蓋表 |
 | `item-anatomy-recipe.md` | 7 步建立新 row primitive workflow + audit grep guard |
-| `naming-conventions.md` | 命名詳表 + 禁止清單(CLAUDE.md # 命名一致性 pointer) |
+| `naming-conventions.md` | 命名詳表 + 禁止清單(AGENTS.md `# 命名與語言一致性` pointer) |
 | `principle-dim-map.json` | M-rule / trait / hook → audit dim explicit mapping(SSOT for dim coverage) |
 | `props-naming.md` | Props callback / Badge / icon canonical 詳表 |
+| `repository-hygiene.md` + `repository-hygiene-policy.json` | Full/deep audit 的 repo 拓撲、冗餘分類與可攜機械政策 |
+| `runtime-evidence-retention.md` | Git-local audit/review evidence 的 lifecycle retention、lazy bundle materialization 與 whole-run cleanup canonical |
+| `scenario-definition.md` | Monorepo 2-Scenario architecture SSOT(Scenario A direct fork DS / Scenario B fork template + mirror chain + verify checkpoints)|
 | `spec-rules.md` | SSOT 機制 / 邊界案例 scope default 詳展 |
+| `story-baseline-registry.json` | Anti-drift registry — stories wrap 既有 primitive 的 machine-readable canonical archetype(hook `check_story_invariants.sh R8` 讀)|
+| `story-baseline-registry.schema.json` | Story baseline registry 的封閉 JSON Schema |
 | `ssot-consultation.md` | SSOT 消費完整對照表 |
 | `ssot-index.md` | High-risk interface ownership map(propose 前 grep 找 owner) |
 | `structural-token-retention.md` | 6 類結構性保留 token canonical(audit Dim 48 triple-verify) |
@@ -27,16 +35,16 @@ Agent 在執行時按需讀的深度 reference 檔 — audit protocol / FP 記
 
 | 疑似要放這但其實不是 | 正確去處 | 為什麼 |
 |---------------------|---------|--------|
-| 設計 canonical judgment(non-programmable)| `spec.md` 或 CLAUDE.md | 2-home 架構:spec / tsx 才是 canonical home。AI 做產品時**必讀** spec,不會必讀 references |
+| 設計 canonical judgment(non-programmable)| `spec.md` 或 `packages/design-system/ds-canonical/rules/*.md` | 元件/模式語意進 spec,跨單元 path-scoped 規則進 canonical rules。AI 做產品時**必讀** spec,不會必讀 references |
 | 實作值 / 計算公式 | tsx / cva / CSS | programmable rule 進 code |
 | 跨 session 狀態 | `memory/` | references 不是 state 檔 |
-| 多步驟 workflow + checkpoint | `.claude/skills/` | skill 管 workflow,reference 是 skill 按需讀的 |
+| 多步驟 workflow + checkpoint | `packages/design-system/ds-canonical/skills/` | skill 管 workflow,reference 是 skill 按需讀的；provider skill home 只是 generated discovery view |
 
 ## 新 reference 的 criteria
 
 1. **Audit / skill 按需查的 lookup data**(表格 / 詳細對照 / 反例清單)
-2. **不含 canonical judgment**(判斷 rule 在 spec / CLAUDE.md)
-3. **被 ≥ 1 skill / CLAUDE.md / spec cite**(orphan file 不收,定期 prune 會 retire)
+2. **不含 canonical judgment**(判斷 rule 在 spec / `packages/design-system/ds-canonical/rules/*.md`)
+3. **被 ≥ 1 skill / AGENTS.md / spec cite**(orphan file 不收,定期 prune 會 retire)
 
 ## 2026-04-24 Lesson
 

package/ds-canonical/references/build-ui-canonicals.md

@@ -1,6 +1,6 @@
-# 建立 UI 前的 DS canonical 對照(從 CLAUDE.md 拆出的完整對照)
+# 建立 UI 前的 DS canonical 對照(historical provenance:從 provider-specific generated adapter CLAUDE.md 拆出)
 
-本檔是 `.claude/rules/ui-development.md`「建立 UI 前必讀」的**完整對照表**。Rule 主章只留「超級規則 + 自我檢查腳本」,遇到具體情境要查對照時讀本檔。
+本檔是 canonical `packages/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」的**完整對照表**。Rule 主章只留「超級規則 + 自我檢查腳本」,遇到具體情境要查對照時讀本檔。
 
 ---
 
@@ -18,6 +18,7 @@
 | 資料表格(含 header / sorting / sticky) | `<table><thead>...</thead><tbody>...</tbody></table>` | `<DataTable columns={...} data={...} />` |
 | 檔案上傳列表 | `<div>filename</div><ProgressBar /><Paperclip />` | `<FileItem mode="compact" />` or `<FileUpload>` |
 | 表單欄位(label + control + error) | `<label>...</label><input/><span className="text-error">...</span>` | `<Field><FieldLabel>...<Input />...<FieldError/>` |
+| 表單提交驗證(何時顯錯 / 提交可點性) | 手刻 `useState(showErrors)` + `submitAttempt` 旗標自組顯錯時機 | `useFormValidation`(Field 家族 hook,`intent:'create'` = 提交恆可點、點擊時 validate 顯錯;搭 `<FieldError>`)|
 | 全頁 / 區域 loading | `<div className="absolute inset-0 flex center"><Spinner /></div>` | `<Empty icon={<CircularProgress />} description="..." />` |
 | 確認對話框 | raw `<div className="fixed inset-0 bg-black/50">...<button>OK</button>` | `<Dialog>` + `<DialogHeader>` etc |
 | 分隔線 | `<hr className="..." />` or `<div className="h-px bg-..."/>` | `<Separator />`(必要時)or CSS border(見 separator.spec) |
@@ -25,10 +26,24 @@
 | 使用者頭像 | `<img className="w-8 h-8 rounded-full" />` | `<Avatar>` |
 | 浮層(彈出資訊) | `<div className="absolute bg-white shadow p-3">...</div>` | `<Popover>` / `<HoverCard>` / `<Tooltip>`(視語義選) |
 | 浮層 media + title + description + actions | 自組 `<div>` 結構 | `<Coachmark>` 或 `<Dialog>`(視是否阻斷) |
+| 固定高度 chrome header(toolbar / page top bar / panel 標題列)| 自組 `<div className="flex h-12 items-center border-b px-4">...</div>` | `<ChromeHeader>`(消費 header-canonical;或在 `<AppShell header={...}>` slot 傳它)|
+
+### Native table 語意分類：app data grid vs rich-text document
+
+`<table>` 在產品 UI 預設視為資料表格，必消費 `DataTable`。唯一不同類別是 WYSIWYG／rich-text 文件內容中的 document table：它是使用者可編輯、可序列化的 HTML 文件節點，不是 app data grid，因此不能替換成 React `DataTable`。
+
+此類別不是靠檔名、component 名或註解豁免；同一完整檔案必同時有下列可機械驗證證據，缺一仍按 raw data table 阻擋：
+
+1. 明確的 `contentEditable` 文件 host。
+2. sanitizer 使用封閉 tag allowlist，且逐一允許 `TABLE / THEAD / TBODY / TR / TH / TD`。
+3. sanitizer 實際以 allowlist 驗 tag，並移除輸入 attributes（URL／style 等可再採更窄 allowlist）。
+4. `editor.innerHTML` 先通過 sanitizer，再把 sanitized value 交給 `onChange`／serializer；不可直接持久化 raw `innerHTML`。
+
+一般 JSX `<table>`、只有 `contentEditable`、只有名為 `sanitize*` 的 passthrough、缺 table-family allowlist，或未在輸出前 sanitize，全部仍是 violation。機械閘 SSOT：`check_consumer_app_invariants.sh` Pattern 10。
 
 **Story 特別提醒**:**stories 也是 code**。如果 story 在 label / comment 說「DataTable cell 用法」「Table 配額」「Menu 選單」等,**要 render 真的該元件 demo,不可用 raw `<table>` / raw `<button>` 假裝**。否則 story 教壞 consumer、自己也在破壞 DS 訓練資料。
 
-`check_story_anatomy.sh` hook 會在 Write/Edit 階段攔下這類手刻;allowlist `// @anatomy-exempt: <reason>`(檔首)/ `// @anatomy-exempt-next`(下一行)可豁免教學用 raw primitive。
+`check_story_invariants.sh` hook(R1 anatomy,原 `check_story_anatomy.sh` folded 折入)會在 Write/Edit 階段攔下這類手刻;allowlist `// @anatomy-exempt: <reason>`(檔首)/ `// @anatomy-exempt-next`(下一行)可豁免教學用 raw primitive。
 
 ---
 
@@ -40,6 +55,7 @@
 |------|---------|---------|
 | 單列 row:prefix(icon/avatar) + content + suffix(action) | `patterns/element-anatomy/item-anatomy.*` — `<MenuItem>` canonical + slot components | 任何「列表項目」元件(Menu/Tree/Sidebar/TableRow/StepItem/FileItem...) |
 | 浮層容器的 Header + Body + Footer(border-b/t + padding token) | `patterns/overlay-surface/` — `SurfaceHeader/Body/Footer` | Dialog / Popover / Drawer / Sheet / 任何 elevation-200 浮層的結構化 sub-components |
+| **固定高度 chrome header(toolbar / page top bar / panel 標題列,border-b + px-loose + 高度 token)** | `patterns/header-canonical/` — `<ChromeHeader>`(`withTabs` / `leadingRail` / `lockDensity`)+ `header-canonical.spec.md` 設計契約 + `Patterns/Header Anatomy` story | Sidebar header / FileViewer Toolbar+InfoPanel / AppShell `header` slot / 未來 Drawer top bar |
 | **垂直居中 icon + title + description(+ action)** | `components/Empty/` — `<Empty>` 元件 | **「告訴使用者狀態」的 surface**:空資料 / 拖放邀請(FileUpload)/ 錯誤 / 首次引導 / 無權限 / 載入佔位(非 Skeleton)|
 | 橫向操作按鈕列（gap-2 分組）| `patterns/action-bar/` | Toolbar、page header actions、form footer buttons |
 | 水平溢出處理(捲動/收合,**隱藏捲軸+ fade-mask** UX)| `patterns/horizontal-overflow/` | Tabs / ChipGroup / 未來 Steps 的溢出(刻意隱藏 scrollbar) |
@@ -47,23 +63,24 @@
 | **固定長寬比容器(防 CLS 坍塌,多張圖統一 ratio)** | `components/AspectRatio/` | Coachmark media / Carousel item image / Card thumbnail / Chart container(override default 16:9) |
 | Field wrapper（border + padding + startIcon + endAction 結構) | `components/Field/field-wrapper.tsx` + `field-controls.spec.md` | 所有單行可編輯欄位元件 |
 
-### 自我檢查腳本(CLAUDE.md 保留這節的精簡版,完整對照在本檔上表)
+### 自我檢查腳本(`rules/ui-development.md`「建立 UI 前必讀」保留這節的精簡版,完整對照在本檔上表)
 
 - 新元件有 icon+text 垂直堆疊? → 用 `<Empty>`,不自己畫 icon + title + desc
 - 新元件有橫向 row 結構(prefix/content/suffix)? → 用 `element-anatomy/item-anatomy` 的 `<MenuItem>` + slot components(`<ItemIcon>` / `<ItemAvatar>` / `<ItemLabel>` / `<ItemSuffix>` / `<ItemInlineAction>`)
 - 新元件是浮層 + 有 header/body/footer? → 用 `overlay-surface`
+- 新元件是 **固定高度 chrome header(toolbar / page top bar / panel 標題列)**? → 用 `header-canonical` 的 `<ChromeHeader>`(border/padding/高度/tabs/dismiss 全契約;或在 `<AppShell header={...}>` slot 傳 `<ChromeHeader>`),**先讀 `header-canonical.spec.md` + `Patterns/Header Anatomy` story**,不自刻 `<div className="flex h-12 items-center border-b px-4">`
 - 新元件內容**可能溢出容器且需要使用者捲動**? → 用 `ScrollArea`(跨 OS 一致 overlay 捲軸);若是刻意隱藏捲軸 + fade-mask → 用 `horizontal-overflow` pattern
 - 新元件有**圖像 / media 容器需要鎖定長寬比**(防 CLS、統一多張圖比例)? → 用 `AspectRatio` primitive,不硬寫 `aspect-video` / `aspect-square` class
 - 以上都沒命中 → 才可自建,但 **建完要立刻回來加行**(防下一個人又重造輪子)
 - **本規則同樣適用 story / consumer / exploration code**:不 hand-craft 已有 prop 能做的事(如 Input loading 走 `loading` prop 不自刻 `<div className="relative"><input/><div className="absolute">` / 全頁 loading 走 `<Empty icon={<CircularProgress/>}/>` 不自刻 `absolute inset-0`)。遇缺口**回元件 spec 擴 API**,不自刻繞過 — hand-craft 視覺對齊 bug 上游
 
-具體 anti-pattern signals → `/design-system-audit` Dim 21;pixel-level 視覺 regression(API 用對但視覺仍跑掉)tech debt → memory `project_pending_tasks`。
+具體 anti-pattern signals → `design-system-audit/references/audit-prompts.md`「L1. 手刻繞 DS canonical」+ Dim 71 consumer 手刻(Pattern 10;現行 Dim 21 已是「連續 item list wrapper gap」,勿誤指);pixel-level 視覺 regression(API 用對但視覺仍跑掉)→ `/visual-audit`(D5)抓(原 memory `project_pending_tasks` 已 retire)。
 
 ---
 
 ## overflow 使用三規則(避免跨 OS 跑版)
 
-1. Design-system 元件 `.tsx` 內**禁止** raw `overflow-auto / overflow-scroll / overflow-{x,y}-{auto,scroll}`(hook `check_token_hygiene.sh` check #4 守衛)
+1. Design-system 元件 `.tsx` 內**禁止** raw `overflow-auto / overflow-scroll / overflow-{x,y}-{auto,scroll}`(hook `lib/_token_hygiene.sh` Check 5 守衛)
 2. 需捲軸且跨 OS 一致 → 用 `ScrollArea`
 3. 刻意隱藏捲軸 + fade-mask → 用 `horizontal-overflow` pattern
 4. 例外:`overlay-surface` spec 明文允許 Dialog body `flex-1 overflow-y-auto`(viewport-fill 特殊 context);若未來此場景需跨 OS 一致,遷移 ScrollArea 再更新 spec