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

package/ds-canonical/hooks/check_audit_post_report_validator.sh

@@ -2,60 +2,176 @@
 # PostToolUse hook: validate `/design-system-audit` final report quality.
 # 2026-05-17 ship — codex Q4 verdict「post-audit stop hook / final report validator」最合理 trigger 位置。
 #
-# Triggers: 任何 Write/Edit 到 `.claude/logs/audit-report-*.json` OR `.claude/memory/project_audit_progress.md`
+# Triggers: 任何 Write/Edit 到 `audit-report-*.json` report artifact OR `governance/memory/project_audit_progress.md`
+#           OR `*/C1-final-report*.md`(2026-07-14 加:C.1 決策清單真實載體,原 scope 漏 = Validator H/K 永不 fire)
+# Runtime diagnostics 只寫 `governance_runtime_state_dir` 解析的 `$GOVERNANCE_STATE_DIR`
+# (Git-owned `<git-dir>/governance-runtime/`,trusted telemetry opt-in only)。Generated provider homes 不是 authority。
 #
 # 驗證:
 #   (a) NO-SAMPLE invariant — report 不含「sample top N / subset / pick top X」keyword
-#   (b) 46-dim full dispatch — report 應列 ≥ 46 dim coverage 紀錄(或明示 N/A 跳過理由)
+#   (b) matrix-derived full dispatch — report 應列齊當前 dim coverage 紀錄(或明示 N/A 跳過理由)
 #   (c) audit-prompts.md coverage — 若 missing dim prompt → flag prune-chain-trigger
 #   (d) `@benchmark-unverified-blanket` count drift — vs last audit baseline
-#   (e) prune-chain-trigger signal → emit additionalContext 進下一 turn,inject_pending_self_audit 吸
+#   (e) deep final report 必須記錄 same-run knowledge-prune + governance-coverage receipt;
+#       progress artifact 缺 receipt 才 emit recovery context 進下一 turn
 #
 # 對應 SKILL.md `/design-system-audit` Phase 4.5 機械化 trigger(2026-05-17 加)。
 
-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: audit validator 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
+source "$HOOK_DIR/lib/_provider_paths.sh" 2>/dev/null || {
+  governance_hook_integrity_fail 'audit validator canonical provider resolver is unavailable'
+}
 
 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)
+governance_hook_load_input
+governance_hook_require_commands grep jq node sort wc tr awk
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""') \
+  || governance_hook_integrity_fail 'audit validator tool name could not be decoded'
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""') \
+  || governance_hook_integrity_fail 'audit validator file path could not be decoded'
 
-# Only fire on audit report writes
+# Only fire on audit report writes. Final reports fail closed; the progress memory
+# remains a recovery surface because it can be written before the run is complete.
+IS_FINAL_REPORT=0
 case "$FILE_PATH" in
-  */audit-report-*.json) ;;
+  */audit-report-*.json) IS_FINAL_REPORT=1 ;;
   */project_audit_progress.md) ;;
+  # Generic final-report names fire too: gating on one exact prefix let a differently-named
+  # final report skip the whole validator family (2026-08-04 adversarial review, evasion 4).
+  # Renaming the artifact past these patterns remains possible; that residual is documented
+  # in the deep-audit skill rather than chased with an ever-longer list.
+  */C1-final-report*.md) IS_FINAL_REPORT=1 ;;
+  */final-report*.md|*/final_report*.md|*-final-report*.md) IS_FINAL_REPORT=1 ;;
   *) exit 0 ;;
 esac
 
 case "$TOOL" in Write|Edit|MultiEdit) ;; *) exit 0 ;; esac
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PROJECT_DIR="${GOVERNANCE_PROJECT_DIR:-$(pwd)}"
 [ -f "$FILE_PATH" ] || exit 0
+CANONICAL_SKILL_ROOT="$(governance_canonical_root skills 2>/dev/null)" || {
+  governance_hook_integrity_fail 'audit validator canonical skill root is unavailable'
+}
+PEER_PROVIDER="${GOVERNANCE_PEER_PROVIDER:-}"
+PEER_DISPLAY_NAME="${GOVERNANCE_PEER_DISPLAY_NAME:-$PEER_PROVIDER}"
 
 WARNINGS=""
 TRIGGER_PRUNE=0
+CRITICAL_FAIL=0
+AUDIT_MATRIX="$PROJECT_DIR/generated/governance/audit-coverage-matrix.json"
+
+# Independent review is an explicit task/deliverable requirement,not a universal
+# audit tax. A real UI/UX SSOT decision still requires the four-element review
+# unless the user explicitly waived second opinion for this run.
+_HAS_DECISION_ITEMS=0
+if grep -qE '待你拍板|拍板清單' "$FILE_PATH" 2>/dev/null; then
+  _DECISION_SEG=$(awk '/待你拍板|拍板清單/{found=1} found' "$FILE_PATH" 2>/dev/null)
+  if printf '%s\n' "$_DECISION_SEG" | grep -qE '^[[:space:]]*([0-9]+[.、)]|##+ *決策)'; then
+    _HAS_DECISION_ITEMS=1
+  fi
+fi
+
+REVIEW_WAIVED=0
+REVIEW_NOT_REQUIRED=0
+REVIEW_CLAIMED=0
+grep -qiE 'second[ -]opinion[[:space:]]*[:：][[:space:]]*(waived by (the )?user|user[- ]waived)|independent review[[:space:]]*[:：][[:space:]]*waived by (the )?user|第二意見.*(使用者|user).*(豁免|免除|不需要)|(使用者|user).*(豁免|免除).*第二意見' "$FILE_PATH" 2>/dev/null && REVIEW_WAIVED=1
+grep -qiE 'second[ -]opinion[[:space:]]*[:：][[:space:]]*not required by (the )?(task|deliverable)|independent review[[:space:]]*[:：][[:space:]]*not required by (the )?(task|deliverable)|第二意見.*(任務|交付).*(未要求|不需要)' "$FILE_PATH" 2>/dev/null && REVIEW_NOT_REQUIRED=1
+grep -qiE 'second[ -]opinion[[:space:]]*[:：][[:space:]]*(required|complete|completed|pass|done)|independent review[[:space:]]*[:：][[:space:]]*(required|complete|completed|pass|done)|peer review[[:space:]]*[:：][[:space:]]*(required|complete|completed|pass|done)|第二意見.*(必須|要求|已完成|已執行)|獨立審查.*(必須|要求|已完成|已執行)' "$FILE_PATH" 2>/dev/null && REVIEW_CLAIMED=1
+
+if [ "$REVIEW_WAIVED" -eq 1 ]; then
+  REVIEW_MODE=waived
+elif [ "$_HAS_DECISION_ITEMS" -eq 1 ] || [ "$REVIEW_CLAIMED" -eq 1 ]; then
+  REVIEW_MODE=required
+elif [ "$REVIEW_NOT_REQUIRED" -eq 1 ]; then
+  REVIEW_MODE=not-required
+else
+  REVIEW_MODE=unspecified
+fi
+
+# Report prose is a receipt, never waiver authority. The only valid waiver is
+# the exact one-run selection frozen in the current immutable manifest. Reusing
+# the canonical verifier also closes pointer digest, current HEAD/tree/index,
+# provider binding, evidence-tree, and one-provider coverage in one readback.
+if [ "$REVIEW_MODE" = waived ]; then
+  WAIVER_PROOF=""
+  if [ -f "$PROJECT_DIR/scripts/verify-deep-audit-coverage.mjs" ]; then
+    WAIVER_PROOF=$(node "$PROJECT_DIR/scripts/verify-deep-audit-coverage.mjs" \
+      --repo-root "$PROJECT_DIR" --json 2>/dev/null || true)
+  fi
+  if ! printf '%s' "$WAIVER_PROOF" | jq -e '
+    .evidenceKind == "deep-audit-coverage-verification"
+    and .secondOpinion == "waived-by-user"
+    and (.providers.self | type == "string" and length > 0)
+    and .providers.peer == null
+  ' >/dev/null 2>&1; then
+    WARNINGS="${WARNINGS}\n  🔴 [R] Report 文字不是 second-opinion waiver authority：目前 active immutable run 無可驗證的 exact user waiver／current binding／single-provider coverage。"
+    CRITICAL_FAIL=1
+  fi
+fi
+
+if [ "$REVIEW_MODE" = required ]; then
+  if ! printf '%s' "$PEER_PROVIDER" | grep -qE '^[a-z][a-z0-9-]*$'; then
+    WARNINGS="${WARNINGS}\n  🔴 [R] Independent review 已被 report 要求／使用，但無 registry-resolved peer provider context。補齊可驗證的 peer 執行與回執，或記錄 user 明確豁免。"
+    CRITICAL_FAIL=1
+  fi
+fi
 
 # ─ Validator A: NO-SAMPLE ─────────────────────────────────────────────────
 if grep -qE 'sample top [0-9]+|sampled top|subset|pick top [0-9]+|top hot|sampled components' "$FILE_PATH" 2>/dev/null; then
   WARNINGS="${WARNINGS}\n  ❌ [A] NO-SAMPLE violation:report 含 sample subset keyword,違反 audit-full-sweep canonical(memory/feedback_audit_full_sweep_not_sample.md)"
 fi
 
-# ─ Validator B: 46-dim coverage ───────────────────────────────────────────
-DIM_COUNT=$(grep -cE '(Dim|dim) ([1-9]|[1-4][0-9]|5[01])(\b|:)' "$FILE_PATH" 2>/dev/null || echo 0)
+# ─ Validator B: dim coverage(2026-05-30 M2/M3 fix per laziness-hunt:原 regex `5[01]` 只到 dim 51,
+#   52-88 完全不計（含 PURE-JUDGMENT dim 62/66/68/72）+ 寫死 46。改動態讀 dispatch total + count UNIQUE dim 號）─
+DIM_TOTAL=$(
+  node -- "$HOOK_DIR/lib/audit-report-validator.mjs" \
+    expected-dimensions "$AUDIT_MATRIX" 2>/dev/null || echo 91
+)
+# Counts every dimension notation the corpus actually uses: `dim N`, `維度 N`, `第N維`, and `DN`.
+# A report written in any single notation the counter did not know scored 0 unique dimensions,
+# which silently disabled every dim-gated validator below — including M (2026-08-04 adversarial
+# review, evasion 3). `D` tokens are isolated with `tr` instead of boundary classes: BSD grep has
+# no `\b`, and a bracket-class boundary consumed by `grep -o` swallows the separator between
+# adjacent tokens (`D8,D9` counted one of two).
+DIM_COUNT=$(
+  {
+    grep -oiE '\bdim[[:space:]]+[0-9]{1,2}\b' "$FILE_PATH" 2>/dev/null
+    grep -oE '維度[[:space:]]*[0-9]{1,2}' "$FILE_PATH" 2>/dev/null
+    grep -oE '第[[:space:]]*[0-9]{1,2}[[:space:]]*維' "$FILE_PATH" 2>/dev/null
+    tr -c '[:alnum:]' '\n' < "$FILE_PATH" 2>/dev/null | grep -E '^D[0-9]{1,2}$'
+  } | grep -oE '[0-9]+' | sort -un | wc -l | tr -d ' '
+)
 DIM_COUNT=${DIM_COUNT:-0}
-if [ "$DIM_COUNT" -lt 46 ]; then
-  WARNINGS="${WARNINGS}\n  ⚠️ [B] Dim coverage:report 提到 ${DIM_COUNT} dim,< 46 期望。確認跑了 46-dim 全 dispatch 還是漏 group"
+if [ "$DIM_COUNT" -lt "$DIM_TOTAL" ]; then
+  WARNINGS="${WARNINGS}\n  ⚠️ [B] Dim coverage:report 提到 ${DIM_COUNT} unique dim,< ${DIM_TOTAL} 期望。確認全 dim NO-SAMPLE（PURE-JUDGMENT/requiresAgent dim 必有 per-dim agent-output 非散文提號）"
 fi
 
 # ─ Validator C: audit-prompts.md coverage ─────────────────────────────────
-AUDIT_PROMPTS="$PROJECT_DIR/.claude/skills/design-system-audit/references/audit-prompts.md"
+AUDIT_PROMPTS="$CANONICAL_SKILL_ROOT/design-system-audit/references/audit-prompts.md"
 if [ -f "$AUDIT_PROMPTS" ]; then
-  PROMPT_DIM_COUNT=$(grep -cE '^###[[:space:]]*Dim[[:space:]]+[1-9][0-9]?(\b|:|[[:space:]])' "$AUDIT_PROMPTS" 2>/dev/null || echo 0)
-  PROMPT_DIM_COUNT=${PROMPT_DIM_COUNT:-0}
-  if [ "$PROMPT_DIM_COUNT" -lt 46 ]; then
-    WARNINGS="${WARNINGS}\n  🔴 [C] audit-prompts.md prompt coverage:${PROMPT_DIM_COUNT}/46 — 紙上 dim 無 prompt,sub-agent 跑不動。下輪 prune Phase 1 D5 candidate(canonical drift:SKILL.md 46-dim vs audit-prompts.md prompt 數差距)"
-    TRIGGER_PRUNE=1
+  # 2026-05-30 M3 fix:原 regex `^### Dim N` 對不上實際格式 `## N. Title`（grep 0 → 永遠誤觸 prune）;
+  # 寫死 46 也錯。改成數真實 `## N.` heading + 動態判「PURE-JUDGMENT dim 數」（只有 judgment dim 需 prompt
+  # 才能派 agent;deterministic/hook dim 不需）。prompts < judgment dim = 有 judgment dim 派不出 agent。
+  # 2026-05-30 fix(hook-test surfaced):`grep -c ... || echo 0` 在 0-match 時 grep 已印 "0" + exit 1,
+  # `|| echo 0` 再 append → "0\n0" → 下方 `[ -lt ]` integer error → trigger 失效。改 `|| true` + 取首行。
+  # 2026-05-31 fix(infra-audit self-finding):原 `[53 -lt 23]` 是 count-vs-count = 永遠 false = dead gate。
+  # 改 SET-MEMBERSHIP:逐個 PURE-JUDGMENT dim 號檢查 audit-prompts.md 有無對應 `## N.` heading,列出缺的。
+  MISSING_PROMPTS=$(
+    node -- "$HOOK_DIR/lib/audit-report-validator.mjs" \
+      missing-judgment-prompts "$AUDIT_MATRIX" "$AUDIT_PROMPTS" 2>/dev/null || echo ""
+  )
+  if [ -n "$MISSING_PROMPTS" ]; then
+    WARNINGS="${WARNINGS}\n  🔴 [C] audit-prompts.md 缺 judgment dim prompt:dim ${MISSING_PROMPTS} 是 PURE-JUDGMENT 卻無 \`## N.\` rubric → sub-agent 派不出正確 prompt → 必被跳過。補這些 dim 的 prompt 進 audit-prompts.md。"
+    TRIGGER_PRUNE=1; CRITICAL_FAIL=1
   fi
 fi
 
@@ -63,25 +179,205 @@ fi
 BENCH_DEBT=$(grep -rc '@benchmark-unverified-blanket' "$PROJECT_DIR/packages/design-system/src/" 2>/dev/null | awk -F: '{s+=$2} END{print s+0}')
 BENCH_DEBT=${BENCH_DEBT:-0}
 if [ "$BENCH_DEBT" -gt 0 ]; then
-  WARNINGS="${WARNINGS}\n  ⚠️ [D] Benchmark cite debt:${BENCH_DEBT} 處 `@benchmark-unverified-blanket` marker — 對應 prune D9(M22 cite debt)"
+  WARNINGS="${WARNINGS}\n  ⚠️ [D] Benchmark cite debt:${BENCH_DEBT} 處「@benchmark-unverified-blanket」marker — 對應 prune D9(M22 cite debt)"
   TRIGGER_PRUNE=1
 fi
 
+# ─ Validator F: A.1b story-vs-code adversarial pass recorded(2026-05-30 403-finding 偷懶 anchor)─
+#   deep-audit report 必含「每 component 讀 .tsx 逐句比對宣稱」的 story-vs-code verdict。缺 = 該 pass
+#   沒跑/沒記 = 前期偷懶 failure mode。偵測 report 是否含 story-vs-code 證據 keyword;deep-audit 規模
+#   report(提 ≥ 10 dim)卻無此 pass = BLOCKER-class warning(走 prune-chain inject 提醒補跑)。
+if [ "$DIM_COUNT" -ge 10 ]; then   # 只對 full/deep-audit 規模 report 要求(小 scoped report 豁免)
+  if ! grep -qiE 'story-vs-code|FALSE_CLAIM|claimsVerified|宣稱.*(真實|code)|A\.1b|逐句比對' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  🔴 [F] Story-vs-code adversarial pass 缺席:deep-audit report(${DIM_COUNT} dim)無 A.1b per-component story-vs-code verdict 證據。202 FALSE_CLAIM(2026-05-30)正是此 pass 沒跑 → 補跑 A.1b(讀每元件 .tsx + wrap lib 逐句驗 anatomy/a11y/spec 宣稱)再出 report。"
+    TRIGGER_PRUNE=1; CRITICAL_FAIL=1
+  fi
+
+  # ─ Validator G: 全 PURE-JUDGMENT dim(含 infra 62/66/68/72)必 show「真跑」證據,非只 mention(2026-05-30 generalize)─
+  #   user 質問「包括所有 infra 稽核?」→ Validator F 只硬保證 story 子集;G 推及全 judgment set。
+  #   judgment dim 無 deterministic script / hook,只能靠「report 含 per-dim 真跑證據」當 proxy。
+  #   evidence marker = 「files scanned / DS-wide 全N / file:line cite / 0 findings after 全掃」。
+  #   evidence 數 < PURE-JUDGMENT dim 數 → 部分 judgment dim 可能 mention-only(偷懶 risk)。
+  PJ_COUNT=$(
+    node -- "$HOOK_DIR/lib/audit-report-validator.mjs" \
+      pure-judgment-count "$AUDIT_MATRIX" 2>/dev/null || echo 23
+  )
+  EVIDENCE_COUNT=$(grep -oiE 'files? scanned|DS-wide|全 ?[0-9]+ (file|stories|component|spec)|[a-z0-9_.-]+\.(tsx|ts|md):[0-9]+|0 findings|scanned: ?[0-9]+' "$FILE_PATH" 2>/dev/null | wc -l | tr -d ' ')
+  EVIDENCE_COUNT=${EVIDENCE_COUNT:-0}
+  if [ "$EVIDENCE_COUNT" -lt "$PJ_COUNT" ]; then
+    WARNINGS="${WARNINGS}\n  🔴 [G] PURE-JUDGMENT dim 真跑證據不足:report 只 ${EVIDENCE_COUNT} 個 per-dim 證據 marker < ${PJ_COUNT} judgment dim(含 infra 62/66/68/72)。judgment dim 無 script/hook 兜底,必每 dim show『DS-wide N files scanned + file:line / 0-after-全掃』證據,否則=mention-only 偷懶。補齊再出 report。"
+    TRIGGER_PRUNE=1; CRITICAL_FAIL=1
+  fi
+
+  # ─ Validator I: D3/D4/D5 domain-skill chain invocation evidence(2026-07-04 solo-run 偏差 anchor:
+  #   稽核 canonical 6-維度表 D3→/performance-audit、D4→/ux-audit、D5→/visual-audit,但歷次 deep run
+  #   performance-audit 0 次 invoke = chain 缺席沒任何機械閘抓。deep-scale report 必含三 skill 名
+  #   (= 有 chain 或有明寫 N/A 豁免理由;mention 缺席即偷懶 risk)─
+  _D345_MISSING=""
+  for _sk in performance-audit ux-audit visual-audit; do
+    grep -q "$_sk" "$FILE_PATH" 2>/dev/null || _D345_MISSING="${_D345_MISSING} ${_sk}"
+  done
+  if [ -n "$_D345_MISSING" ]; then
+    WARNINGS="${WARNINGS}\n  🔴 [I] D3/D4/D5 domain-skill chain 證據缺席:report 未提及${_D345_MISSING}。shared 稽核 canonical 6-維度表的 deep 規模必 chain 三 domain skill(或明寫豁免理由 + skill 名)。補跑/補記再出 report。"
+    TRIGGER_PRUNE=1; CRITICAL_FAIL=1
+  fi
+
+  # ─ Validator J: independent-peer dim 覆蓋對帳─
+  #   report 顯示 Phase B / peer 比稿有跑 → 必含「dim 覆蓋對帳」表(彙總 peer 各 brief 蓋到的
+  #   dim 號 vs dispatch 清單逐號對;SKILL B.2 Step 0 契約的報告端機械閘 — 保證鏈第三段)。
+  _PEER_RUN=0
+  grep -qiE '(Phase B|peer 比稿|獨立審查|cite battle|dual-track).*(complete|completed|pass|done|完成|已跑|已執行|通過)|second[ -]opinion[[:space:]]*[:：][[:space:]]*(complete|completed|pass|done)' "$FILE_PATH" 2>/dev/null && _PEER_RUN=1
+  if [ "$REVIEW_MODE" = required ] && printf '%s' "$PEER_PROVIDER" | grep -qE '^[a-z][a-z0-9-]*$'; then
+    grep -qiF "$PEER_PROVIDER" "$FILE_PATH" 2>/dev/null && _PEER_RUN=1
+    [ -n "$PEER_DISPLAY_NAME" ] && grep -qiF "$PEER_DISPLAY_NAME" "$FILE_PATH" 2>/dev/null && _PEER_RUN=1
+  fi
+  if [ "$_PEER_RUN" -eq 1 ]; then
+    if ! grep -qiE 'dim 覆蓋對帳|dim 對帳|coverage tally' "$FILE_PATH" 2>/dev/null; then
+      WARNINGS="${WARNINGS}\n  🔴 [J] Peer dim 覆蓋對帳缺席:report 提及 Phase B/比稿但無「dim 覆蓋對帳」表(${PEER_DISPLAY_NAME} 各 brief 蓋到的 dim 號 vs dispatch 清單逐號對,缺號 = 補 brief)。per SKILL B.2 Step 0(2026-07-10),不齊不得宣稱雙軌全覆蓋。"
+      TRIGGER_PRUNE=1; CRITICAL_FAIL=1
+    fi
+  fi
+fi
+
+# ─ Validator H: 拍板清單 SSOT-理由 強制(2026-06-11 user 第 3 次糾正「要我拍板的都是 SSOT 的 UI/UX 嗎」)─
+# 報告含「待你拍板」/「拍板清單」區塊時:區塊內每個編號題必含「SSOT 理由」字樣;
+# 題數 > SSOT-理由數 = 有題目沒標理由 = 混入非 SSOT 項 → BLOCK。
+if grep -qE '待你拍板|拍板清單' "$FILE_PATH" 2>/dev/null; then
+  _BLOCK_SEG=$(awk '/待你拍板|拍板清單/{found=1} found' "$FILE_PATH" 2>/dev/null)
+  _Q_COUNT=$(echo "$_BLOCK_SEG" | grep -cE '^[[:space:]]*([0-9]+[.、)]|##+ *決策)' || true)
+  _R_COUNT=$(echo "$_BLOCK_SEG" | grep -c 'SSOT 理由' || true)
+  if [ "${_Q_COUNT:-0}" -gt "${_R_COUNT:-0}" ]; then
+    CRITICAL_FAIL=1
+    WARNINGS="${WARNINGS}\n  • Validator H:拍板清單 ${_Q_COUNT} 題但僅 ${_R_COUNT} 題標「SSOT 理由」— 寫不出理由的題 = 非 SSOT,移回 AUTO 自己做,不問 user。"
+  fi
+fi
+
+# ─ Validator K: 決策品質四要件(2026-07-13 user verbatim「需我拍板的議題,不是應該確保你和 codex 來回
+#   討論辯論出來的共識與解法有研究過世界級的設計且符合我們需求與一致設計語言和設計原則並確保 SSOT?
+#   現在跟未來都應該要確保這件事永遠成立」;SSOT = deep-audit SKILL C.1「🔒 決策品質四要件」。
+#   命名注:SKILL 2026-07-13 初稿寫「Validator I」,但 I 已被 D3/D4/D5 chain(2026-07-04)佔用 → 定 K)─
+#   報告含「待你拍板」/「拍板清單」section 時:section 內每個決策 block(切分同 Validator H heading regex)
+#   必含全部四要件 marker:(1) SSOT-check(SSOT/既有拍板)(2) ≥3 世界級 cite(世界級/URL)
+#   (3) registry-resolved independent-peer verdict(4) design-fit(設計語言/設計原則/design-fit)。缺任一 → 該題不成熟
+#   → BLOCK(exit 2)。Detection conservative:只掃本 hook file scope(audit report / C1-final-report)
+#   的拍板 section;無決策 block(「無待拍板」)= 合法 pass。
+if [ "$_HAS_DECISION_ITEMS" -eq 1 ]; then
+  _K_MISSING=$(
+    node -- "$HOOK_DIR/lib/audit-report-validator.mjs" \
+      missing-decision-evidence "$FILE_PATH" "$PEER_PROVIDER" "$PEER_DISPLAY_NAME" "$REVIEW_MODE" \
+      2>/dev/null || echo ""
+  )
+  if [ -n "$_K_MISSING" ]; then
+    CRITICAL_FAIL=1
+    if [ "$REVIEW_MODE" = required ]; then
+      _K_REVIEW_TEXT="(3)${PEER_DISPLAY_NAME:-independent peer} 辯論 verdict(4)"
+    else
+      _K_REVIEW_TEXT="(3)second opinion 已依 user 豁免並明示記錄(4)"
+    fi
+    WARNINGS="${WARNINGS}\n  🔴 [K] 決策品質要件不全:${_K_MISSING} — 每個送 user 拍板的決策必含 (1)SSOT-check(先 grep 既有 canonical/已拍板)(2)≥3 世界級 cite(真 source + URL)${_K_REVIEW_TEXT}設計語言/原則 fit。缺 = 該題不成熟,退回研究/辯論(deep-audit SKILL C.1),禁送 user。"
+  fi
+fi
+
+# ─ Validator L: deep-final same-run closure receipts ─────────────────────────────────────
+# Full knowledge prune and governance-home reconciliation are phases of the same
+# deep run. A next-turn trigger is recovery only and cannot certify a final report.
+SAME_RUN_PRUNE=0
+SAME_RUN_GOVERNANCE_COVERAGE=0
+grep -qiE '(knowledge[- ]prune).*(same[- ]run|同一(輪|次|run)).*(complete|completed|pass|done|完成|對帳)|same[- ]run.*(knowledge[- ]prune).*(complete|completed|pass|done)|同一(輪|次).*(knowledge[- ]prune).*(完成|對帳)' "$FILE_PATH" 2>/dev/null && SAME_RUN_PRUNE=1
+grep -qiE '(governance[- ]coverage|governance-audit-coverage).*(same[- ]run|同一(輪|次|run)).*(complete|completed|pass|done|reconciled|receipt|unobserved|完成|對帳|回執)|same[- ]run.*(governance[- ]coverage|governance-audit-coverage).*(complete|completed|pass|done|reconciled|receipt|unobserved)|同一(輪|次).*(governance[- ]coverage|governance-audit-coverage).*(完成|對帳|回執|UNOBSERVED)' "$FILE_PATH" 2>/dev/null && SAME_RUN_GOVERNANCE_COVERAGE=1
+
+if [ "${DIM_COUNT:-0}" -ge 10 ]; then
+  if [ "$IS_FINAL_REPORT" -eq 1 ]; then
+    if [ "$REVIEW_MODE" = unspecified ]; then
+      WARNINGS="${WARNINGS}\n  🔴 [L] Second-opinion receipt 缺席:deep final report 必須明記 『second opinion: waived by user』、『second opinion: not required by task』或可驗證的 required/completed peer review。"
+      CRITICAL_FAIL=1
+    fi
+    if [ "$SAME_RUN_PRUNE" -ne 1 ]; then
+      WARNINGS="${WARNINGS}\n  🔴 [L] Same-run knowledge-prune receipt 缺席:deep final report 不得把 full prune 留到 next turn。完成後明記『knowledge-prune: same-run complete』。"
+      CRITICAL_FAIL=1
+    fi
+    if [ "$SAME_RUN_GOVERNANCE_COVERAGE" -ne 1 ]; then
+      WARNINGS="${WARNINGS}\n  🔴 [L] Same-run governance coverage receipt 缺席:必須逐 row 對帳 governance-audit-coverage.md，無法觀測的 home 標 UNOBSERVED，並明記『governance-coverage: same-run reconciled』。"
+      CRITICAL_FAIL=1
+    fi
+  elif [ "$SAME_RUN_PRUNE" -ne 1 ] || [ "$SAME_RUN_GOVERNANCE_COVERAGE" -ne 1 ]; then
+    TRIGGER_PRUNE=1
+    WARNINGS="${WARNINGS}\n  • [L] Recovery only:deep progress 尚缺 same-run knowledge-prune / governance-coverage receipt；在 final report 前完成同一輪收斂。"
+  fi
+fi
+
+# ─ Validator M: coverage verdict truthfulness ────────────────────────────────────────────
+# Validator L only proves the three receipt strings are present. A run whose machine verdict is
+# coverageStatus=incomplete could therefore ship a final report that reads like a pass, because
+# nothing compared the prose against the verifier. That is exactly how the beta.108 Deep Audit was
+# recorded as closed while dimensions 64/66 stayed unpassed (2026-08-02). The rule is not "coverage
+# must be complete" — closing incomplete is legitimate — it is "an incomplete verdict must be stated
+# in the report", so silence can never imply completion.
+ACTIVE_RUN_MANIFEST="$PROJECT_DIR/.git/governance-runtime/evidence/deep-audit/active-run.json"
+if [ "${DIM_COUNT:-0}" -ge 10 ] && [ "$IS_FINAL_REPORT" -eq 1 ] && [ -f "$ACTIVE_RUN_MANIFEST" ]; then
+  # The active-run guard mirrors Validator R's existence guard: with no deep-audit run in flight
+  # there is no machine verdict to compare prose against, and blocking every large report until the
+  # author writes 「未通過結案」 would demand a false statement (2026-08-04 adversarial review).
+  # Deleting the manifest to dodge M leaves a hole in the evidence chain that the coverage verifier
+  # itself reports fail-closed, so the guard is not a silent escape hatch.
+  #
+  # Two steps, not one pipeline: under `set -o pipefail` a failing verifier makes the whole pipeline
+  # non-zero *after* the parser has already printed its own "unknown", so `|| echo unknown` appended a
+  # second one and the status read "unknownunknown". Parsed with jq, not `node -e` — inline dynamic
+  # Node code in an active hook violates the harness shell-safety policy (assertReviewedBashSafety).
+  COVERAGE_JSON=$(node "$PROJECT_DIR/scripts/verify-deep-audit-coverage.mjs" --repo-root "$PROJECT_DIR" --json 2>/dev/null || true)
+  COVERAGE_STATUS=$(printf '%s' "$COVERAGE_JSON" | jq -r '.coverageStatus // "unknown"' 2>/dev/null || true)
+  COVERAGE_STATUS=${COVERAGE_STATUS:-unknown}
+  if [ "$COVERAGE_STATUS" = unknown ]; then
+    # An active run exists but the verifier could not produce a verdict. That is machinery failure,
+    # not audit failure — block, but tell the author to fix the verifier, never to confess a failure
+    # that was not established ('unknown' conflated with 'incomplete' produced exactly that wrong
+    # instruction; 2026-08-04 adversarial review).
+    WARNINGS="${WARNINGS}\n  🔴 [M] Deep-audit run 進行中但 coverage verifier 無法產出 verdict(unknown):先修 verifier / evidence 鏈再出 final report,不得在無 verdict 下宣稱通過或未通過。"
+    CRITICAL_FAIL=1
+  elif [ "$COVERAGE_STATUS" != complete ]; then
+    # Deliberately narrow phrases, all byte-stable under any locale (multibyte runs live inside
+    # groups; no bare quantifier on a multibyte char, no byte-counted {n,m} over CJK). The numeric
+    # form requires a NONZERO count — 「0 個未通過」 asserts the opposite of the verdict and used to
+    # match. Machine-field spellings (coverageStatus…incomplete) are NOT accepted: quoting last
+    # round's verdict inside a pass-reading sentence matched them (2026-08-04 adversarial review).
+    if ! grep -qiE 'closed as incomplete|this is not a pass|not a pass;|未通過結案|結案但未通過|以未通過|未完成覆蓋|[1-9][0-9]*[[:space:]]*(個[[:space:]]*)?(維度[[:space:]]*)?未通過' "$FILE_PATH" 2>/dev/null; then
+      WARNINGS="${WARNINGS}\n  🔴 [M] Coverage verdict 為 '${COVERAGE_STATUS}' 但 final report 未明記未通過:允許以 incomplete 結案,但必須逐字寫出(例如『CLOSED AS INCOMPLETE; THIS IS NOT A PASS』或『N 個維度未通過』,N 非零),不得讓三段回執字串暗示已完成。"
+      CRITICAL_FAIL=1
+    fi
+  fi
+fi
+
+# ─ Validator BLOCK gate(2026-05-31 fix infra-audit self-finding:原 hook 只 exit 0 + additionalContext
+#   soft-inject = 我過度宣稱「BLOCKER」。改:critical fail → stderr + exit 2 真 block PostToolUse。
+#   2026-07-10 user「只有 SSOT UI/UX 才交拍板,要確保」:Validator H 原在本 gate 之後 = CRITICAL_FAIL 白設
+#   死旗(hunt finding #62)→ 搬到 gate 前,H 現在真擋)─
+if [ "${CRITICAL_FAIL:-0}" -eq 1 ]; then
+  printf '🚨 AUDIT-REPORT VALIDATOR BLOCK(C/F/G/H/I/J/K/L/M/R critical):%b\n\n此 deep-audit report 不合格,補齊上述後重出 report。' "$WARNINGS" >&2
+  exit 2
+fi
+
 # ─ Validator E: prune-chain-trigger emit ──────────────────────────────────
+# Validator L enforces deep-final closure. This trigger is only recovery for a
+# progress artifact or another non-critical debt signal; it is never proof that
+# the final report already ran knowledge prune.
 if [ "$TRIGGER_PRUNE" -eq 1 ] || [ -n "$WARNINGS" ]; then
-  mkdir -p "$PROJECT_DIR/.claude/logs" 2>/dev/null
-  printf '{"ts":"%s","file":"%s","trigger_prune":%d,"warnings":%s}\n' \
-    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-    "$FILE_PATH" \
-    "$TRIGGER_PRUNE" \
-    "$(printf '%b' "$WARNINGS" | jq -Rs .)" \
-    >> "$PROJECT_DIR/.claude/logs/audit-post-report-validator.jsonl" 2>/dev/null || true
+  if RUNTIME_STATE_DIR="$(governance_runtime_state_dir 2>/dev/null)"; then
+    mkdir -p "$RUNTIME_STATE_DIR" 2>/dev/null
+    printf '{"ts":"%s","file":"%s","trigger_prune":%d,"warnings":%s}\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      "$FILE_PATH" \
+      "$TRIGGER_PRUNE" \
+      "$(printf '%b' "$WARNINGS" | jq -Rs .)" \
+      >> "$RUNTIME_STATE_DIR/audit-post-report-validator.jsonl" 2>/dev/null || true
+  fi
 
   if [ "$TRIGGER_PRUNE" -eq 1 ]; then
-    CTX=$(printf '🚨 audit post-report validator: prune-chain-trigger fire。下輪 invoke /knowledge-prune scope=full(triggers: audit-prompts coverage < 100%% / @benchmark-unverified-blanket count > 0)。\n%b' "$WARNINGS")
-    jq -n --arg ctx "$CTX" '{
-      hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
-    }'
+    CTX=$(printf '🚨 audit post-report validator: prune-chain-trigger fire。AI 必 AUTO-RUN /knowledge-prune(禁問 user;品質優先前提 per deep-audit SKILL C.0a；P2E 工程治理自主收斂，只有產品／UI／UX SSOT 真取捨的 P2H 才列拍板清單)。\n%b' "$WARNINGS")
+    CONTEXT=$(jq -nc --arg ctx "$CTX" '{
+      governanceContext: { hookEventName: "PostToolUse", message: $ctx }
+    }') || governance_hook_integrity_fail 'audit validator governance context could not be encoded'
+    printf '%s\n' "$CONTEXT"
   fi
 fi
 

package/ds-canonical/hooks/check_audit_sample_escape.sh

@@ -18,8 +18,10 @@ INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
 EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""')
 
+# 2026-06-11 coverage expand(prune D2 抓盲區;expand never replace):Workflow 派發的 agents
+# 原本完全繞過本防線(tool 名 ≠ Agent);Task 為舊名 alias 一併納入。
 case "${TOOL:-}" in
-  Agent) ;;
+  Agent|Task|Workflow) ;;
   *) exit 0 ;;
 esac
 
@@ -31,22 +33,23 @@ case "${EVENT:-}" in
     # Sub-agent OUTPUT scan — catch post-fact admission
     OUTPUT=$(echo "$INPUT" | jq -r '.tool_response.content // .tool_response // ""' 2>/dev/null)
     # Only fire on audit-related agent runs(by output keyword)
-    if ! echo "$OUTPUT" | grep -qiE 'audit|Dim [0-9]+|D[0-9]+ CLEAN|DS-wide|sub-agent'; then exit 0; fi
+    if ! grep -qiE 'audit|Dim [0-9]+|D[0-9]+ CLEAN|DS-wide|sub-agent' <<<"$OUTPUT"; then exit 0; fi
     PROMPT="$OUTPUT" # reuse PROMPT var for downstream grep
     ;;
   *)
-    # PreToolUse(default existing logic):scan dispatch prompt
-    PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // ""')
+    # PreToolUse(default existing logic):scan dispatch prompt;
+    # Workflow 的 agent prompts 在 .tool_input.script 內(2026-06-11 expand)
+    PROMPT=$(echo "$INPUT" | jq -r '(.tool_input.prompt // "") + "\n" + (.tool_input.script // "")')
     ;;
 esac
 
 # Allow escape(極罕見)
-if echo "$PROMPT" | grep -qE '@audit-sample-allow:'; then
+if grep -qE '@audit-sample-allow:' <<<"$PROMPT"; then
   exit 0
 fi
 
 # Only enforce on audit-related dispatch(detect by prompt keyword)
-if ! echo "$PROMPT" | grep -qE 'audit|Dim [0-9]+|DS-wide|sub-agent|sweep'; then
+if ! grep -qE 'audit|Dim [0-9]+|DS-wide|sub-agent|sweep' <<<"$PROMPT"; then
   exit 0
 fi
 
@@ -62,7 +65,7 @@ if [ -n "$ESCAPE_HITS" ]; then
   echo "$ESCAPE_HITS" | while IFS= read -r hit; do
     printf '   • "%s"\n' "$hit" >&2
   done
-  printf '\n  Per CLAUDE.md `# 稽核 canonical` + design-system-audit/SKILL.md Phase 1 NO-SAMPLE invariant:\n' >&2
+  printf '\n  Per AGENTS.md `# 稽核 canonical` + canonical design-system-audit/SKILL.md Phase 1 NO-SAMPLE invariant:\n' >&2
   printf '  禁含「sample / top N / heavy agent needed / full sweep deferred」escape clause。\n' >&2
   printf '  每 dim 必 DS-wide ALL components 全掃,context 不夠拆 stage 分批,**不 sample**。\n' >&2
   printf '\n  修方向:從 prompt 移除 escape clause,改寫「拆 N-stage(每 stage 10-15 元件)所有 stages 必跑完」。\n' >&2

package/ds-canonical/hooks/check_benchmark_citation.sh

@@ -14,7 +14,11 @@ set -uo pipefail
 #     - Screenshot reference(`snapshots/...`)
 #     - Marked `@benchmark-unverified`(顯式撤回)
 #
-# 允許 escape:
+# Component-spec zero-debt rule:
+#   `packages/design-system/src/components/**/*.spec.md` may not add any benchmark escape.
+#   Claims must either carry direct inline evidence or be rewritten as internal product rationale.
+#
+# 其他 scope 允許 escape:
 #   檔頭加 `// @benchmark-citation-allow: <reason>` 整檔豁免(legacy,M22 hook 上線過渡期)
 #   檔頭加 `// @benchmark-unverified-blanket: <reason>` 整檔 M22 (d) 撤回(file-level unverified)
 
@@ -43,16 +47,38 @@ NEW_CONTENT=$(echo "$INPUT" | jq -r '
   ([.tool_input.edits[]? | .new_string] | join("\n"))
 ' 2>/dev/null || echo "")
 
-[ -z "${NEW_CONTENT//[[:space:]]/}" ] && exit 0
+grep -q '[^[:space:]]' <<<"$NEW_CONTENT" || exit 0
+
+# Component specs are the public authoring contract and completed their D9 evidence-debt
+# migration in beta.107. Do not allow either a per-claim retraction or a file-level bypass to
+# recreate that debt. This intentionally runs before the legacy file-level allowlist below.
+case "$FILE_PATH" in
+  */packages/design-system/src/components/**/*.spec.md)
+    if grep -qE '@benchmark-unverified([^-[:alnum:]]|-blanket:)|@benchmark-citation-allow:' <<<"$NEW_CONTENT"; then
+      cat >&2 <<EOF
+
+┄┄┄┄ check_benchmark_citation — component spec benchmark evidence debt ┄┄┄┄
+
+[P0 BLOCKER] ${FILE_PATH}
+Component specs are a zero-debt scope: \`@benchmark-unverified\`,
+\`@benchmark-unverified-blanket\`, and \`@benchmark-citation-allow\` are forbidden.
+
+Keep the claim only with a direct inline primary-source citation that supports it;
+otherwise remove the external comparison and state the DS-internal product rationale.
+EOF
+      exit 2
+    fi
+    ;;
+esac
 
 # File-level allowlist
 FIRST_LINES=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,5p')
-if echo "$FIRST_LINES" | grep -qE '@benchmark-citation-allow:|@benchmark-unverified-blanket:'; then
+if grep -qE '@benchmark-citation-allow:|@benchmark-unverified-blanket:' <<<"$FIRST_LINES"; then
   exit 0
 fi
 if [ -f "$FILE_PATH" ]; then
   ON_DISK_FIRST=$(sed -n '1,5p' "$FILE_PATH" 2>/dev/null || true)
-  if echo "$ON_DISK_FIRST" | grep -qE '@benchmark-citation-allow:|@benchmark-unverified-blanket:'; then
+  if grep -qE '@benchmark-citation-allow:|@benchmark-unverified-blanket:' <<<"$ON_DISK_FIRST"; then
     exit 0
   fi
 fi
@@ -60,9 +86,14 @@ fi
 # Detect benchmark claim keywords + check inline citation in same paragraph
 # 用 perl -0777 slurp 比 awk simpler;每個含 benchmark keyword 的「段」(連續非空行)
 # 必含 citation evidence。
+# 缺 perl = 這道 M22 防線無法判 → 明確 BLOCK,不得靜默放行(fail-closed;cloud 前提宣告)。
+if ! command -v perl >/dev/null 2>&1; then
+  echo '🚨 check_benchmark_citation: required interpreter perl is unavailable — M22 citation gate cannot run(fail-closed)' >&2
+  exit 2
+fi
 VIOLATIONS=$(printf '%s' "$NEW_CONTENT" | perl -0777 -ne '
   my $bench = qr/(Ant Design|Material(\s+X|\s+Design|\s+UI|\s+3)?|Polaris|Atlassian|Carbon|shadcn|Radix UI?|Apple HIG|Notion|Airtable|ClickUp|Figma|Linear)/;
-  my $cite = qr/(https?:\/\/(www\.)?(ant-design|material|polaris\.shopify|atlassian\.design|carbon|shadcn|ui\.shadcn|radix-ui|github|developer\.apple)|#L\d|snapshots\/|@benchmark-unverified)/;
+  my $cite = qr/(https?:\/\/(www\.)?(m3\.material|ant-design|material|polaris\.shopify|atlassian\.design|carbon|shadcn|ui\.shadcn|radix-ui|github|developer\.apple)|#L\d|snapshots\/|@benchmark-unverified)/;
   # Iterate paragraphs(separated by blank lines)
   for my $para (split /\n\s*\n/) {
     next unless $para =~ $bench;
@@ -82,7 +113,7 @@ if [ -n "$VIOLATIONS" ]; then
 
 ┄┄┄┄ check_benchmark_citation — world-class benchmark claim 缺 source ┄┄┄┄
 
-[P1 WARN] ${FILE_PATH}
+[P0 BLOCKER] ${FILE_PATH}
 偵測到 benchmark claim 段缺 inline citation:
 ${VIOLATIONS}
 M22 canonical(2026-05-02):**寫 spec / code 含「Ant / Material / Polaris / ...」claim 必附**:
@@ -99,8 +130,10 @@ M22 canonical(2026-05-02):**寫 spec / code 含「Ant / Material / Polaris / ...
   - \`// @benchmark-citation-allow: <reason>\`(legacy 過渡期暫掛)
   - \`// @benchmark-unverified-blanket: <reason>\`(M22 (d) file-level 撤回)
 EOF
-  # Soft warning(P1)— print to stderr, don't block(exit 1 vs exit 2)
-  exit 1
+  # P0 BLOCKER(2026-07-07 治理進化方向 2:對齊 user 2026-05-27 doctrine「SSOT canonical
+  # 必 P0 BLOCKER 禁 P1 WARN」— escape 已備:@benchmark-unverified 逐句撤回 /
+  # @benchmark-citation-allow / @benchmark-unverified-blanket 檔級,故升級不增誤殺)
+  exit 2
 fi
 
 exit 0