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

package/ds-canonical/skills/design-system-audit/references/checkpoints.md

@@ -1,12 +1,16 @@
-# Checkpoints — 什麼時候 MUST 停下來問
+# Checkpoints — authority-classified audit decisions
 
-這些是 skill 執行過程中**不可略過**的 user 決策點。past 執行失敗都因為我自行決定了該問的事。
+只有真正未解的產品／UI／UX SSOT 取捨才是 user 決策點。治理、架構、security、
+release、provider、migration、環境修復與其他工程決策依 canonical Standing
+Authorization 自主處理；milestone、triage、review 與外部寫入都不是 approval
+checkpoint。以下各 checkpoint 皆受此 authority classifier 約束。
 
 ---
 
-## Checkpoint 1 — 稽核完畢後的 Triage（每次 run 都會觸發）
+## Checkpoint 1 — 稽核完畢後的 Triage receipt（每次 run 都會觸發）
 
-稽核結果出來後，**先不修**，先把findings 分類呈現：
+稽核結果出來後先分類並保存 evidence；P0/P1 與所有工程 P2 依 frozen scope
+連續 remediation，只有產品／UI／UX P2H 才 batch-at-end 請 user 決定：
 
 **格式範本**：
 ```
@@ -25,66 +29,68 @@ P1（批次修 + review）: M 項
 - Anatomy 缺 section: D 處
 - a11y aria-label 缺失: E 處
 
-P2（MUST ASK）: K 項
-1. [findings 1 scope 爭議] — 選項 A / B / C
+P2H（產品／UI／UX SSOT 真取捨）: K 項
+1. [finding 1 的 user-visible trade-off] — 選項 A / B / C
 2. [findings 2]
 
-建議順序:
-1. 先修 P0（獨立 commit）
-2. 再修 P1（每類一個 commit）
-3. P2 逐項討論再決定
-
-要從哪一項開始?
+執行:
+1. P0/P1/工程 P2E 依 Standing Authorization 自主修復與驗證
+2. P2H 只在證據收斂後仍有真實產品選擇時批次提出
 ```
 
 **絕對不可**：
-- ❌ 跳過 triage 直接開始修 P1/P2
-- ❌ 把 P2 當 P1 mechanical 執行
+- ❌ 跳過 triage evidence
+- ❌ 把 P2H 當工程 P2E 執行
 - ❌ 僅報總數不提供 file:line 讓 user 掃
+- ❌ 用 triage receipt 要求 user 核准工程執行順序
 
 ---
 
-## Checkpoint 2 — 稽核發現 CLAUDE.md 沒覆蓋的 pattern
+## Checkpoint 2 — 稽核發現 canonical rules 沒覆蓋的 pattern
 
-若某個 audit 找到的違規不符合現有 CLAUDE.md 任何規則（= 新 pattern，非現有規則下的違反），必須 pause：
+若新 pattern 會新增產品／UI／UX semantics，且存在多個可行 user-visible 方向，才
+pause。若只是補足 engineering invariant、security、test、provider、release 或
+governance coverage，agent 依 evidence 自主選定 canonical owner、寫入並生成 adapters：
 
 **觸發情境**：
-- a11y audit 發現 7 個元件無 focus-visible，但 CLAUDE.md 沒明訂 focus ring 規則
+- a11y audit 發現 7 個元件無 focus-visible，但 canonical rule/spec 沒明訂 focus ring 規則
 - Token audit 發現一個新 color 硬寫模式反覆出現
 - shadcn passthrough 發現 `displayName` 以外另一種 anti-pattern
 
 **格式範本**：
 ```
-🔔 Audit 發現 CLAUDE.md 未覆蓋的 pattern:
+🔔 Audit 發現 canonical rules 未覆蓋的 pattern:
 
 Pattern: [描述]
 頻率: 出現在 X 個元件
 Root cause (推測): [判斷 why 發生]
 
-建議新增到 CLAUDE.md 的規則:
+建議新增到 canonical owner 的規則:
 「[draft]」
 
 放哪一節 (按「規則分層」判斷):
-- 若跨元件 → `.claude/rules/ui-development.md` / `.claude/rules/spec-rules.md` / `.claude/rules/story-rules.md`
+- 若跨元件 → `packages/design-system/ds-canonical/rules/ui-development.md` / `spec-rules.md` / `story-rules.md`
 - 若技術陷阱 → # 失敗記憶索引 + 根原位置 section
 - 若純風格 → # 命名與語言一致性
 
-你決定:
-(a) 採用此 draft，我同步寫進 CLAUDE.md
+若屬 P2H，你決定:
+(a) 採用此 draft，我寫進上述 canonical owner，之後由 adapter 重建 provider view
 (b) 修改措辭: ...
 (c) 不新增,遇到再 case-by-case 處理
 ```
 
 **絕對不可**：
-- ❌ 直接寫新規則進 CLAUDE.md
+- ❌ 直接寫新規則進任何 generated provider instruction/view
 - ❌ 忽視 pattern 只修個別違規
-- ❌ 半途改 mindset 條目（最高層級規則不可未經討論就加）
+- ❌ 把純工程新 invariant 冒充 user 產品決策
 
 ---
 
-## Checkpoint 3 — 分類模糊（Internal vs Components / SSOT ownership）
+## Checkpoint 3 — 產品語意分類模糊（Internal vs Components）
 
-稽核可能發現邊界元件，classification 不明：
+只有 classification 會改變 public product／UI semantics 且 precedent 無法唯一收斂時
+才詢問。Canonical file ownership、pointer、generator 與其他工程 SSOT ownership
+由 agent 自主收斂：
 
 **觸發情境**：
 - 新元件的 Storybook title 應該放 `Components/` 還是 `Internal/`？
@@ -98,14 +104,14 @@ Root cause (推測): [判斷 why 發生]
 問題: [element / rule / token 是 A 還是 B?]
 
 判斷依據:
-- CLAUDE.md「{判斷 test 的位置}」第 X 題: [...]
+- Canonical rule/reference「{判斷 test 的位置}」第 X 題: [...]
 - 相似 precedent: [已分類的類似案例]
 
 兩個選項的 trade-off:
 選 A (...) → 優: [...] 缺: [...]
 選 B (...) → 優: [...] 缺: [...]
 
-我傾向 B 因為 [...], 但需要你確認。
+我傾向 B 因為 [...]。此選擇會改變 user-visible semantics，需要你決定。
 ```
 
 **絕對不可**：
@@ -115,9 +121,10 @@ Root cause (推測): [判斷 why 發生]
 
 ---
 
-## Checkpoint 4 — Cross-cutting refactor（影響 > 10 檔）
+## Checkpoint 4 — Cross-cutting engineering refactor receipt（影響 > 10 檔）
 
-若修復涉及大量檔案的 mechanical 改動：
+若修復涉及大量檔案的 mechanical 改動，agent 自行決定 batching、commit topology、
+rollback 與驗證。這是可審查的 execution receipt，不是 human approval gate：
 
 **觸發情境**：
 - Helper function extraction 影響 41 個 anatomy files
@@ -135,24 +142,23 @@ Root cause (推測): [判斷 why 發生]
 - [風險 2]
 回復難度: [rebase 難度]
 
-執行方式:
-(a) 一次 commit 全改（快但難 review）
-(b) 分 N 個 commit 依 feature cluster 分批（慢但可 cherry-pick）
-(c) 不做,留 tech debt,下次針對性處理
-
-我傾向 (b) / 分 [clusters] 執行。你同意嗎?
+執行方式:[agent 選定的唯一方案與依據]
+Rollback:[具體 recovery]
+Verification:[focused + affected Harness]
 ```
 
 **絕對不可**：
 - ❌ 直接跑 mechanical find-replace 不 preview
-- ❌ 一個 commit 塞 41 個 file
-- ❌ 改完才告訴 user
+- ❌ 無 recovery／verification 就做大範圍改動
+- ❌ 要求 user 替 agent 選 commit 或 migration 策略
 
 ---
 
-## Checkpoint 5 — 環境 / 建置問題
+## Checkpoint 5 — 環境 / 建置工程處理
 
-稽核過程若遇環境問題（node_modules 壞、storybook 啟動失敗、tsc 報不相關錯），**不要嘗試修環境**：
+稽核過程若遇環境問題（node_modules 壞、storybook 啟動失敗、tsc 報不相關錯），
+先證明因果與 scope，再以 least-privilege、可回復方式自主修復或隔離；只有
+login/MFA/OAuth/owner/billing、缺 secret reference 或額外付費才形成 human action：
 
 **格式範本**：
 ```
@@ -161,22 +167,24 @@ Root cause (推測): [判斷 why 發生]
 現象: [描述]
 影響: 我無法 [verify X]
 是否本 audit 引入的?  確認不是 (理由: git log / file touch 證實)
-建議:
-- 現在不碰環境，稽核照常進行
-- 環境問題交給你 / 下個 session 處理
-- 本 audit 的 tsc --noEmit 可以跑，用它當 correctness guard
+處理:
+- 可在 frozen scope 內修復 → 自主修復後重跑受影響 checks
+- 與 scope 無關 → 保留 evidence，使用仍可信的替代 guard，不擴張 scope
+- 平台不可代理 → 只列唯一必要 human action，完成後自行 readback
 ```
 
 **絕對不可**：
-- ❌ 重 install node_modules
-- ❌ 改 vite / storybook 設定試圖修
+- ❌ 未證明 root cause 就破壞性重裝
 - ❌ 編輯無關檔案「順便修」
+- ❌ 把可自行處理的環境工程工作轉交 user
 
 ---
 
 ## Checkpoint 6 — 發現 spec 與 code 衝突
 
-稽核若發現 spec.md 與 .tsx 描述的行為不同：
+先用 owner、history、tests、runtime evidence 與產品 requirement 判定。若證據可唯一
+判斷為 spec drift 或 code bug，agent 自主修正；只有兩者代表不同 user-visible
+產品／UI／UX方向且無法由 evidence 收斂時才詢問：
 
 **格式範本**：
 ```
@@ -192,18 +200,19 @@ Code 實際: [行為 + line M]
 - 若 Code 和 Spec 都錯：需討論正確做法
 
 我的判斷: [分析]
-等你確認哪個是 canonical 再動手。
+若仍為 P2H: [兩個 user-visible 選項與唯一建議]
 ```
 
 **絕對不可**：
-- ❌ 默默選一個修
+- ❌ 無 evidence 憑直覺選一個修
 - ❌ 改 code 前未讀 git log 看是否刻意改動
+- ❌ 已可由 canonical evidence 收斂仍要求 user 做工程判斷
 
 ---
 
 ## Checkpoint 7 — 「先不管」vs tech debt 語意區分（user directive）
 
-User 不同用語表達「現在不做」,語意差別明顯,處理方式不同。**本 checkpoint 是 Skill 層 SSOT**(對話 protocol 屬 skill,非 CLAUDE.md 層):
+User 不同用語表達「現在不做」,語意差別明顯,處理方式不同。**本 checkpoint 是 canonical Skill 層 SSOT**(對話 protocol 屬 skill,非 shared bootstrap 層):
 
 ### 語意對照表
 

package/ds-canonical/skills/design-system-audit/references/historical-bugs.md

@@ -1,6 +1,6 @@
 # Bug Classes This Skill Prevents
 
-Curated from the `# 失敗記憶索引` in CLAUDE.md plus audit runs. Each entry names the bug class, how it originally slipped in, and which audit catches it.
+Curated from canonical governance history plus audit runs. Each entry names the bug class, how it originally slipped in, and which audit catches it.
 
 ---
 
@@ -68,7 +68,7 @@ Curated from the `# 失敗記憶索引` in CLAUDE.md plus audit runs. Each entry
 
 **Caught by**: Audit 5 (Figma-test).
 
-**Why it recurs**: Authors want to be thorough. But CLAUDE.md explicitly forbids — anatomy reflects *current* density (re-rendered on density switch); dual columns are noise. Token name is enough.
+**Why it recurs**: Authors want to be thorough. But canonical anatomy rules explicitly forbid — anatomy reflects *current* density (re-rendered on density switch); dual columns are noise. Token name is enough.
 
 ---
 
@@ -76,7 +76,7 @@ Curated from the `# 失敗記憶索引` in CLAUDE.md plus audit runs. Each entry
 
 **First seen**: HoverCard originally under `Components/` (behavior primitive, no default visual) — should be `Internal/`.
 
-**Caught by**: CLAUDE.md has a 3-question test; audits cross-check.
+**Caught by**:`packages/design-system/ds-canonical/references/naming-conventions.md` has a 3-question test; audits cross-check.
 
 **Why it recurs**: Name bias — HoverCard *sounds* like a public component. Always go by behavior (has default visuals? rendered directly anywhere?) not name.
 
@@ -127,7 +127,7 @@ Curated from the `# 失敗記憶索引` in CLAUDE.md plus audit runs. Each entry
 | Audit | Primary bug class | Secondary |
 |-------|-------------------|-----------|
 | 14. 命名一致性 | Folder/file case mismatch | H1 heading drift |
-| 15. CLAUDE.md 自身一致性 | Internal contradictions | Dead internal references |
+| 15. Canonical governance + generated projection 一致性 | Internal contradictions | Dead internal references |
 
 ### Group F — Architecture compliance (P1, session-learned)
 | Audit | Primary bug class | Secondary |
@@ -140,7 +140,7 @@ Curated from the `# 失敗記憶索引` in CLAUDE.md plus audit runs. Each entry
 
 ## Meta-Pattern layered index (2026-04-21 rebuild)
 
-After the 2026-04-21 governance rebuild, each historical bug maps to one of the 6 Meta-Patterns in CLAUDE.md `# Meta-Pattern 預警`. The index below is the canonical mapping; specific bug classes are kept below as historical context, but future bugs should be classified into a Meta-Pattern first.
+After the 2026-04-21 governance rebuild, each historical bug maps to one of the Meta-Patterns in `packages/design-system/ds-canonical/rules/meta-patterns.md`. The index below is the canonical mapping; specific bug classes are kept below as historical context, but future bugs should be classified into a Meta-Pattern first.
 
 ### M1 — 視覺決策前必消費 SSOT
 
@@ -176,7 +176,7 @@ After the 2026-04-21 governance rebuild, each historical bug maps to one of the
 
 ### 獨立技術陷阱(非 meta-pattern,保留 anchor)
 
-- cva `defaultVariants.size` 三方漂移(SegmentedControl) → `/story-writing` Phase 4 + hook `check_cva_default_sync.sh`
+- cva `defaultVariants.size` 三方漂移(SegmentedControl) → `/story-writing` Phase 4 + hook `lib/_cva_default_sync.sh`(`post_edit_dispatcher.sh` 消費;原 check_cva_default_sync.sh 2026-05-13 fold)
 - Row 硬寫 `py-2` 產生 gap(TreeView in SidebarGroup) → item-anatomy spec
 - asChild pattern consumer 自查 avatar size → item-anatomy spec
 - HoverCard 誤放 Components/(純行為 primitive 應 Internal/) → `# Story` 判斷 test
@@ -184,9 +184,9 @@ After the 2026-04-21 governance rebuild, each historical bug maps to one of the
 
 ---
 
-## Meta-Pattern M1-M17 origins(2026-04-24 搬自 CLAUDE.md 3rd column)
+## Meta-Pattern M1-M17 origins(2026-04-24 搬自舊 provider bootstrap 3rd column)
 
-Each Meta-Principle 起源於具體 bug 類型。CLAUDE.md M-row 第 3 欄壓到 ≤80 字,完整歷史在這。
+Each Meta-Principle 起源於具體 bug 類型。Canonical `rules/meta-patterns.md` M-row 第 3 欄壓到 ≤80 字,完整歷史在這。
 
 ### M1 — 視覺決策前必消費 SSOT
 自發明 `variant="bare"` / Sheet 表單 gap 沒用 layout-space token / Header 高度沒用 `--chrome-header-height` / Row 沒用 item-anatomy / Toolbar 按鈕群 gap 不對齊 action-bar canonical。2026-04-22 dismiss Button/Inline Action 分界後走 item-anatomy「Predicate」SSOT。
@@ -218,6 +218,10 @@ DatePicker `today + selected`:藍 bar 疊在藍底隱形;`hover + disabled`:ring
 ### M10 — Proactive exhaustive scan
 2026-04-22 dismiss canonical migration 只改 Dialog/Sheet/Popover/Alert/Notice/Coachmark,漏 FileViewer 2 處 + action-bar stories 4 處;同時 Dialog autoFocus tooltip 洩漏 / body 未用 ScrollArea / layoutSpace uiSize 耦合 / list-in-dialog padding 大 — AI 全程知道或該察覺但沒主動講,user 7 個問題一次炸出來。根因:AI「做完」標準太鬆(只改 explicit 要的事),缺 proactive self-scan。
 
+2026-08 追錄:
+- 2026-08-07 `grep candidateRelease | head -20` 截掉 `consumerctl.mjs:1737/1761` 兩個 caller → 把還有人讀的欄位判成死狀態歸零 → 鎖死 legacy consumer 唯一升級路線(才剛在 #83 解開的死鎖)。root:盤 reader 清單時 grep 接 `head`/`-m` = 假陰性;`cmd | head` 的 exit code 屬 head,`&&` 分支報相反結論(必看 `PIPESTATUS`)。
+- 2026-08-09 agent UI 規格:「agent 切換會重置左側 modal 層數」定調後未入結論總帳,規格三處寫成「尚未定案」,據此跑兩輪無謂辯論,連自己推薦方案的賣點違背既有結論都沒看出來;前後多次「全盤稽核」全只驗單句證據,零次驗結論兩兩相容性。user 原話:「你在檢查的時候難道都沒有發現他們邏輯不通嗎?那你之前到底在檢查什麼」
+
 ### M11 — User-perspective interactive state walk
 2026-04-22 ListBody 修完 user 連抓 5 波:hover bg 貼邊違反不貼邊 / focus ring click 觸發擾人 / notification 範例不現實(誰會進 modal 又跳別處)/ menu py-2 沒對齊 / layoutSpace md reset selector 缺。每個都是 user 視角一看就知,AI 沒跑 7 題 state walk 就 commit。
 
@@ -228,7 +232,7 @@ DatePicker `today + selected`:藍 bar 疊在藍底隱形;`hover + disabled`:ring
 2026-04-22 hover bg 震盪 4 次 + avatar-NameCard migration 拖延:user 說「我說所有」明示 DS-wide,但 AI 第一次只改 2 處 dialog stories,15+ 處放 tech debt 留到下次。user 第 2 次提起才完成。根因:AI「做完」標準太鬆(視 user 明示為「提醒」而非「canonical 聲明」)。
 
 ### M14 — 對話結論 AUTO integrate pipeline
-2026-04-22 本 session 每個 canonical(chrome-header / dismiss 分家 / avatar hoverCard / popover 14px)都是 user 提醒才整合,AI 只做 code 改動但忘記 spec / CLAUDE.md / memory / hook 同步。根因:AI「做完」的標準只含 code,缺「整合多層」的 procedural rule。M14 若存在,每次 code change 後自動觸發 pipeline,不等 user 第 2 次問。
+2026-04-22 本 session 每個 canonical(chrome-header / dismiss 分家 / avatar hoverCard / popover 14px)都是 user 提醒才整合,AI 只做 code 改動但忘記 spec / canonical rules / governance memory / hook 同步。根因:AI「做完」的標準只含 code,缺「整合多層」的 procedural rule。M14 若存在,每次 code change 後自動觸發 pipeline,不等 user 第 2 次問。
 
 ### M15 — Product UI flow 必須 visual-audit coverable
 2026-04-22 Sheet / FileViewer 過去只有 trigger button stories,visual-audit 跑 `--scope=component:Sheet` 只截到 trigger 未 open state,被 user 點破「能抓到點擊打開的 modal 嗎?」才補 OpenSnapshot。若 M15 存在,新元件建立時就該有 OpenSnapshot。
@@ -238,3 +242,23 @@ DatePicker `today + selected`:藍 bar 疊在藍底隱形;`hover + disabled`:ring
 
 ### M17 — SSOT 必可傳播(非僅 markdown)
 2026-04-23 user 指出「mt-0.5 canonical 只存 markdown 文字、13 consumer 各自 hard-code,今天雖 compliant 但明天改 2px → 4px 需手動 grep N 檔 = 假 SSOT」。本 session migrate token + primitive + mode prop 後,改 `--item-gap-label-desc` 一處全 DS 同步。真 SSOT 必是可執行 value(token / primitive / utility class)。世界級對照:Material dense prop / Carbon size enum / Ant size enum / Polaris token,6 家皆透過 token + primitive 組合。
+
+## Meta-Pattern M18+ origins(2026-08-18 搬自 meta-patterns.md 長篇 example cells)
+
+### M18 — Propose-time 自檢 gate(Q0 起源)
+2026-05-18 Sheet 補 / 5 元件 inline-action migrate / 5 元件 SurfaceBody migrate 三題全錯誤 propose 給 user 拍板,grep 後 0 個真 gap(Sheet 已完整 / 6 元件全消費 inline action / Dialog 走 ScrollArea canonical 不該用 SurfaceBody / HoverCard 是 behavior primitive / DatePicker TimePicker 是專用 layout / Sidebar 是 chrome 不是浮層)。User verbatim「不是老早就跟你說過要我決策前請先基於我們所有的檔案包括設計原則包括 ssot 包括所有實作代碼,自主自動驗證這些問題是否真的是問題」→ 催生 Q0 Pre-ASK self-verify。
+
+### M23 — DS 內既有 canonical 優先於外部 benchmark
+- 2026-05-03 chevron color:DS `text-foreground`(icon-only Button neutral-9 85%)vs 憑「Ant 5 家 muted」印象覆蓋 → 自開新 tier 違反一致設計語言。
+- 2026-05-06 column width:DS 49+ 處 `size: 'sm'|'md'|'lg'` density vs TanStack `size: 280` px = 同 prop 不同義 → `meta.width` wrap(M23(c) 起源)。
+- 2026-05-20 AppShell-vs-Sidebar drift:simplified mock + jargon + wrong variant + 不消費 primitive props(M23(d) 起源)。
+- 2026-06-04 upload-manager 面板手刻 header + 殼(`py-2`≠`py-tight` / `rounded-md`≠`lg` / `border-divider`≠`border` / `bg-surface`≠`raised`),既有 3 道網全漏(R1-C 要 absolute+dismiss / `_chrome_header_handcraft` skip stories / R7-R8 只比已註冊 primitive 名)→ adversarial workflow 抓 + 加 R9 補洞。Hook `check_datatable_invariants.sh`(r2 folded,2026-06-11)+ `check_story_invariants.sh` R8/R9。
+
+### M30 — Wrapper-vs-primitive schema unify
+2026-05-10 PeoplePicker multi-mode 漏 avatar:`Combobox.SelectOption = { value, label }` weak schema(跟 `Select.SelectOption` 同名不同 fields)+ `Combobox.menuOptions` mapping 只 forward 2 fields → dropdown rows 永遠純文字。user 抓「為什麼之前會把 people picker 改壞 + 還有沒有其他東西也改壞」。Round 1 commit `561945b` 修(Combobox extends + forward 全 field)+ Round 2 codify。
+
+### M36 — 禁推論升格 user 決定;禁自鎖
+- 2026-08-08 同一 session 連犯 4 次 provenance 升格(「<768 modal 無入口是你拍板」/「X = 終結 session」/「392px user 接受」/「816 讓位線」),user 原話「我他媽到底哪有拍板過這件事」;同日又因 `claude-permission-policy` 把 sandbox unix socket 鎖死,先叫 user 去買 API key 而非解自家鎖,user 原話「你他媽不要又再作繭自縛為自己加鎖了」。
+- 2026-08-11 一日連環五鎖:build graph journal 死鎖(復原全刪全蓋碰禁寫目標)/ authority fingerprint 把自家 index-publish 誤判竄改 / blanket 授權辨識漏「開頭裸可以」/ `gh auth status` 帳號級體檢擋 repo-scoped token / gh Go TLS 拒 sandbox 代理——五層全是自家機制,user 原話「不要再說有人擋你了,完全沒有」;逐層拆除後 release 全自動走通,零 user 指令。
+- 2026-08-28 hooks/scripts symlink 本地殘影(8/1 舊版 generator 合法生成、8/2 佈局改版後無人能寫回):我先誤稱「我們自己沙箱設的保護」(實查自家 settings `denyWrite=[]`,鎖是 Claude Code 對 hook 設定目錄的**平台內建**防注入保護),再指 `! git restore` 給 user(對話內 `!` 與 Bash **同一個沙箱**,必再被擋 = 指死路),user 原話「你不要再作繭自縛了,我說要做就做」;正解一行 `git update-index --skip-worktree`(只寫 `.git` 可寫區,不碰被鎖路徑)→ codify M36(b') 第 4 問(鎖的主人是誰 + 交 user 的指令必先驗證不在同牆內)。
+- 四路同 provider 對抗審查查不到 (a) 類(reviewer 無對話紀錄),故必須以 M36 rule + 來源總帳格式機械化。

package/ds-canonical/skills/design-system-audit/references/principle-audit-protocol.md

@@ -2,7 +2,7 @@
 
 **此檔是 D6「設計原則自檢」的唯一執行 SSOT**。所有 audit skill(design-system-audit / component-quality-gate / prototype / product-ui-audit)的 D6 phase 都 chain 本檔,不重複寫邏輯。
 
-對齊 CLAUDE.md `# 稽核 canonical`(內含「Audit-vs-execute 分權」inline rule)。
+對齊 `packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md` 的 canonical audit taxonomy 與 Audit-vs-execute 分權。
 
 ---
 
@@ -18,15 +18,15 @@
 
 ## D6 5 子維(含 scan mode 分類)
 
-**關鍵**:5 子維依「單 item 檢」vs「跨 item 比對」vs「predicate 自測」分三類。跨 item 比對的**必走 Phase 0 全掃再判**(對齊 CLAUDE.md `# 稽核 canonical`「一致性類稽核必先全掃再判」),否則無法檢出矛盾 / 不一致。
+**關鍵**:5 子維依「單 item 檢」vs「跨 item 比對」vs「predicate 自測」分三類。跨 item 比對的**必走 Phase 0 全掃再判**(對齊 canonical design-system-audit「一致性類稽核必先全掃再判」),否則無法檢出矛盾 / 不一致。
 
 | # | 子維 | Scan mode | 掃什麼 | 怎麼掃 |
 |---|------|-----------|-------|-------|
 | **D6a** | **合理性** | **per-item**(單 spec 可判)| 每條 canonical 是否世界級對照支持?有明文 rationale? | 讀 spec 找「為什麼」prose + 對照 Polaris / Material / Atlassian / Ant / Apple HIG;孤立 rule 無對照 = flag |
 | **D6b** | **一致性** | **cross-inventory**(必全掃)| 同概念跨 spec / 跨元件表達 / 術語是否一致? | 必先全掃建 inventory(見下 Phase 0)→ 比對 |
-| **D6c** | **無矛盾** | **cross-inventory**(必全掃)| spec↔spec / CLAUDE.md↔spec / canonical 聲明衝突 | 必先全掃 canonical concept index(見下 Phase 0)→ 比對 |
-| **D6d** | **完整性** | **per-item + reference**(per spec 但要比 scope default canonical)| 原則有無覆蓋 applicable state / scope / edge case? | 單 spec 檢 + 對照 Rule B scope defaults(CLAUDE.md)|
-| **D6e** | **Predicate 自測**(**new 2026-04-22**) | **predicate-internal**(對含 decision tree + example 表的 spec)| Membership drift / cap 違反 / example × world-class / empty category | 對齊 CLAUDE.md Meta-Pattern M9;4 題 coherence check(見下 D6e scan) |
+| **D6c** | **無矛盾** | **cross-inventory**(必全掃)| spec↔spec / canonical rules↔spec / canonical 聲明衝突 | 必先全掃 canonical concept index(見下 Phase 0)→ 比對 |
+| **D6d** | **完整性** | **per-item + reference**(per spec 但要比 scope default canonical)| 原則有無覆蓋 applicable state / scope / edge case? | 單 spec 檢 + 對照 `rules/spec-rules.md` Rule B scope defaults|
+| **D6e** | **Predicate 自測**(**new 2026-04-22**) | **predicate-internal**(對含 decision tree + example 表的 spec)| Membership drift / cap 違反 / example × world-class / empty category | 對齊 `rules/meta-patterns.md` M9;4 題 coherence check(見下 D6e scan) |
 
 ## Phase 0 — 全掃再判(cross-inventory 子維硬規則)
 
@@ -44,7 +44,7 @@
 
 ### Phase 0b — 建 canonical concept inventory(for D6c)
 ```
-1. 列 CLAUDE.md + patterns/*/spec.md 所有「canonical」宣告的 concept
+1. 列 `packages/design-system/ds-canonical/{rules,references}/` + patterns/*/spec.md 所有「canonical」宣告的 concept
    (dismiss canonical / overlay padding canonical / icon size canonical 等)
 2. 對每個 concept,grep 所有 spec 宣告該 concept 的段落
    建 {concept: [{spec_path, line, prose, rule}]}
@@ -89,24 +89,27 @@ D6b / D6c 跑前 inline grep 建 concept matrix(本檔上方 Phase 0 已展開
 
 | Finding 類型 | 動作 | 為何 STOP |
 |--------------|------|----------|
-| spec 聲明的原則世界級對照有疑 | **STOP 提議** | 改 substantive 需 user 拍板 |
-| 跨 spec 矛盾 **兩邊都有 rationale** | **STOP 提議(擇一當 canonical)** | 哪個對?需仲裁 |
-| 新增 canonical rule / 刪現有 canonical rule | **STOP 提議** | canonical scope 動 |
-| 命名決策(新 prop value / 新術語)| **STOP 提議** | 命名三 test 後仍需拍板 |
-| 原則 scope 擴充 / 收緊 | **STOP 提議** | governance 動 |
-| 擴 SSOT 納入新 branch(例:Inline Action「colored host」新分支) | **STOP 提議** | canonical 擴張 — 2026-04-21 Inline Action icon 案例屬此 |
-| Rationale 存在但疑似過時(實作已改但 rationale 沒跟) | **STOP 提議** | 是該撤 rationale 還是 revert 實作?需判斷 |
+| spec 聲明的原則世界級對照有疑 | **CLASSIFY** | 有唯一證據答案則 P2E auto；會改產品/UI/UX meaning 且有真取捨才 P2H |
+| 跨 spec 矛盾 **兩邊都有 rationale** | **CLASSIFY** | evidence 可收斂則 P2E auto；兩個可行 user-visible semantics 才 P2H |
+| 新增／刪除 governance canonical rule | **AUTO(P2E)** | 工程治理 policy 由 agent 依 evidence/hard gates 決策 |
+| 命名決策(新 prop value / 新術語)| **CLASSIFY** | public component semantics 真取捨為 P2H；機械命名/治理為 P2E |
+| 工程治理 scope 擴充 / 收緊 | **AUTO(P2E)** | 依 frozen scope、least privilege 與 tests；task／deliverable 明確要求時才加 independent review |
+| 擴產品/UI/UX SSOT 新 branch | **STOP(P2H)** | user-visible canonical 真取捨 — 2026-04-21 Inline Action icon 案例屬此 |
+| Rationale 疑似過時 | **CLASSIFY** | evidence 唯一則 P2E auto；兩個 user-visible outcomes 才 P2H |
 
 ### 核心公式
 
 ```
-動 canonical 的 substantive meaning → STOP(提議,等 user sign-off)
+動工程／治理 canonical substantive meaning → P2E AUTO
+動產品／UI／UX canonical 且存在真取捨 → P2H STOP(exact target-bound decision)
 對齊 canonical / 表達統一 / 補 pointer → AUTO(直接修)
 ```
 
 **判斷 substantive 的 keyword**:
 - 「canonical」「聲明」「必須」「統一規則」「SSOT」「rationale」「為什麼」「不允許」「禁止」
-- 出現在 spec prose 且動到的 edit 觸及這些關鍵字 → 觸發 STOP
+- 出現在 spec prose 且動到的 edit 觸及這些關鍵字 → 觸發 **CLASSIFY**；evidence
+  已唯一決定的工程／治理修正是 P2E AUTO，只有會改變產品／UI／UX SSOT 且仍有真取捨
+  才 P2H STOP。關鍵字本身不是 human gate。
 
 ---
 
@@ -133,7 +136,8 @@ D6b / D6c 跑前 inline grep 建 concept matrix(本檔上方 Phase 0 已展開
    - grep 所有 `variant:` / `size:` / `mode:` 在 .tsx
    - 建立 {literal: [components]} 表
    - 同字跨元件 → 驗語義一致(命名三 test #3)
-   - 語義不一致 → STOP 提議(命名決策)
+   - 語義不一致 → CLASSIFY；機械／治理命名由 evidence 收斂(P2E AUTO)，只有不同
+     public semantics 導向不同 UI／UX outcomes 才 P2H
 
 3. 術語一致性
    - 常見 drift:dismiss vs close vs dismiss vs onDismiss / onClose
@@ -143,11 +147,11 @@ D6b / D6c 跑前 inline grep 建 concept matrix(本檔上方 Phase 0 已展開
 ### D6c 無矛盾 scan(AI 讀 spec pairs)
 
 ```
-1. 建「canonical concept index」(從 CLAUDE.md + patterns/*/spec.md)
+1. 建「canonical concept index」(從 `packages/design-system/ds-canonical/{rules,references}/` + patterns/*/spec.md)
 2. 對每個 canonical concept,grep 所有 spec 聲明該 concept 的段落
 3. 比對:
    - 同 concept 兩 spec 聲明**不同**規定 → P0 矛盾(修其一或擴 SSOT)
-   - 同 concept 某 spec 靜默違反 CLAUDE.md rule → P0 矛盾
+   - 同 concept 某 spec 靜默違反 canonical rule → P0 矛盾
    - 某 spec rationale 跟 tsx 實作不符 → P1 矛盾(spec 過時或 tsx 錯)
 4. 每個 P0 矛盾 flag 前驗是否為 documented deviation(rationale 存在 → deviation ✓)
 ```
@@ -163,11 +167,11 @@ D6b / D6c 跑前 inline grep 建 concept matrix(本檔上方 Phase 0 已展開
    - density(non-scope-default)
    - icon-only rule(interactive 元件)
    - a11y 預設
-   
+
 2. 缺且無 scope default pointer → flag(可能 AUTO 補 pointer or STOP 補 prose)
 ```
 
-### D6e Predicate coherence scan(對齊 CLAUDE.md Meta-Pattern M9)
+### D6e Predicate coherence scan(對齊 canonical Meta-Pattern M9)
 
 針對含 **decision tree + example 表 / real case 表 / category 分類** 的 spec
 (item-anatomy.spec.md 的 Predicate、button.spec.md 的 variant 選擇、field-controls.spec.md
@@ -192,7 +196,8 @@ D6b / D6c 跑前 inline grep 建 concept matrix(本檔上方 Phase 0 已展開
    - 我方選擇跟世界級 3 家中過半不同 → flag(可能對或可能錯)
      → 查 spec 有無 rationale 解釋為何不同
      → 有 rationale = deviation ✓
-     → 無 rationale = P1 應補 rationale(AUTO 加 pointer),或提議 revise(STOP)
+     → 無 rationale = P1 應補 rationale(AUTO 加 pointer)；若 benchmark 證據唯一則
+       P2E 自主 revise，只有真產品／UI／UX outcomes 取捨才 P2H
 
 4. Empty category check:
    - Decision tree 所有 category 都要有 ≥1 example
@@ -202,7 +207,7 @@ D6b / D6c 跑前 inline grep 建 concept matrix(本檔上方 Phase 0 已展開
 **Phase 0 要求**:D6e 必先 grep 專案所有 `.spec.md` 找 decision tree / real case 表 /
 category 分類,建 inventory 再逐個跑 4 題。不是隨機挑。
 
-**世界級 benchmark source**(從 memory 或 CLAUDE.md M8 列表):Polaris / Material / Atlassian /
+**世界級 benchmark source**(從 governance memory 或 `packages/design-system/ds-canonical/rules/meta-patterns.md` M8 列表):Polaris / Material / Atlassian /
 Ant Design / Carbon / Apple HIG / VS Code / Figma。對每個 example,至少查 3 家的對應
 實作名 / API / spec 段落。
 
@@ -219,7 +224,7 @@ Ant Design / Carbon / Apple HIG / VS Code / Figma。對每個 example,至少查
   - 例:Button 5 variant 選擇 predicate 需 per-variant world-class mapping(不只 L74 整體「Material / Polaris 共識」兜底)
   - flag 時區分「predicate 粒度 vs benchmark 粒度」不匹配 = P1 補 pointer
 - **Overlay autoFocus canonical**(2026-04-22 新增)— Portal overlay 元件需檢 autoFocus 行為是否對齊 DS-wide canonical(body first interactive,不是 chrome close X)。詳見下方「Overlay autoFocus canonical」section。
-- **Binary strict rule 震盪 FP**(2026-04-22 新增,CLAUDE.md M12):visual preference 類 rule 被寫成「必 X」或「禁 Y」時,**先驗 ≥3 世界級 DS 一致**再 flag;找得到 counter-example = variance 不是 canonical,這是 AI 最常陷的 FP。
+- **Binary strict rule 震盪 FP**(2026-04-22 新增,canonical M12):visual preference 類 rule 被寫成「必 X」或「禁 Y」時,**先驗 ≥3 世界級 DS 一致**再 flag;找得到 counter-example = variance 不是 canonical,這是 AI 最常陷的 FP。
   - 例:「hover bg 必 flush 容器內邊」— Material / Polaris / Linear list row 多 flush 但非 must,Material Bottom Sheet / Polaris card-in-modal 允許 inset → 不該寫成 strict rule
   - 例:「chrome close X 必 size=sm」— Dialog / Sheet sm,但 Popover 因輕量浮層用 xs 合法 → 必 per-component context 判
   - **判斷公式**:strict rule 寫完前自問「我能想出一個 legal 的反例嗎?」→ 能 → relax 成「canonical 偏好 + variance 允許」,不寫 strict
@@ -229,7 +234,7 @@ Ant Design / Carbon / Apple HIG / VS Code / Figma。對每個 example,至少查
     - Root invariant:「content 必在 bg 內有 padding」(content-vs-bg relationship,是 invariant)
     - 這兩 layer 的規則彼此 orthogonal:bg 邊可以 flush 也可以 inset,**content-inside-bg padding 跟 bg 邊位置無關**,但都必要
   - **AI 必自己跑此 check,不該靠 user 提醒**:rule 寫「必 / 禁」的瞬間就要觸發 M12 self-check。user 提醒第 3 次還沒 trigger = meta-loop 完全 bypass,違反「自我升級機制」
-- **Markdown 表格 row 計數 FP**(2026-04-22 audit session 發現)— sub-agent 跑 CLAUDE.md 一致性 audit(Dim 15 count drift)時,若表格中間有**空行分隔**(`| **M11** | ... |` 後接空行再接 `| **M12** | ... |`),agent 可能只算到第一段 rows。實際上 markdown table 中的 blank line 是 **visual spacing**(渲染後仍是同一 table)或**table 終止**(根據 parser)— 兩種都可能被誤判。Mitigation:agent 計數前 prefer `grep -c "^| \*\*M[0-9]"` 機械式計數,不靠 visual scan。本 FP 只影響 count 報告準度,不影響 fix 結果(因 user / 主 AI 會 double-check)
+- **Markdown 表格 row 計數 FP**(2026-04-22 audit session 發現)— sub-agent 跑 canonical meta-pattern 一致性 audit(Dim 15 count drift)時,若表格中間有**空行分隔**(`| **M11** | ... |` 後接空行再接 `| **M12** | ... |`),agent 可能只算到第一段 rows。實際上 markdown table 中的 blank line 是 **visual spacing**或**table 終止**(根據 parser)— 兩種都可能被誤判。Mitigation:agent 計數前 prefer `grep -c "^| \*\*M[0-9]" packages/design-system/ds-canonical/rules/meta-patterns.md` 機械式計數,不靠 visual scan。
 - **Dim 2 SSOT dead link 只檢 heading anchor 不檢 bare file path**(2026-04-22 audit session 漏掉)— element-anatomy.spec.md dead pointer `packages/design-system/src/ELEMENT-ANATOMY.md` 從未存在,但 agent 未 flag 因為 Dim 2 regex `\.spec\.md「」` 只抓 heading-anchor pointers。裸 file-path reference 落在檢測外。**已擴 Dim 2 prompt**(見 audit-prompts.md)增加 Part B(file path existence)+ Part C(spec self-placement drift)。本 FP 類別:**doc-structural drift**(doc 寫在 impl 前,impl 換方向後 doc 未更新),audit 應對 `README.md` home governance claim vs 實際 spec 位置交叉驗證
 
 ---
@@ -256,8 +261,8 @@ Ant Design / Carbon / Apple HIG / VS Code / Figma。對每個 example,至少查
 ### D6d 完整性(AUTO)
 - ...
 
-## 提議討論(STOP,等 user sign-off)
-### 跨 canonical 矛盾需仲裁
+## P2H 提議討論(只有產品／UI／UX SSOT 真取捨才 STOP)
+### 跨產品／UI／UX canonical 矛盾需仲裁
 1. **{Concept}**:spec A 說 {X}(line),spec B 說 {Y}(line)
    - 選項 A:修 A 對齊 B,因為 {reason}
    - 選項 B:修 B 對齊 A,因為 {reason}
@@ -273,7 +278,7 @@ Ant Design / Carbon / Apple HIG / VS Code / Figma。對每個 example,至少查
 
 ## Self-improvement capture(每次 audit 結束寫)
 - 新發現的 FP pattern:{描述},回填到 audit-prompts.md
-- 新確立的 meta-pattern:{描述},回填到 CLAUDE.md Meta-Pattern 預警
+- 新確立的 meta-pattern:{描述},回填到 `packages/design-system/ds-canonical/rules/meta-patterns.md`
 - 修完的矛盾:{list},回填到 memory `project_audit_progress`
 ```
 
@@ -295,8 +300,8 @@ Ant Design / Carbon / Apple HIG / VS Code / Figma。對每個 example,至少查
 ### Meta-lesson(AI 自我提醒)
 
 - **寫新 protocol / skill / rule 時,必反向自檢:**
-  - CLAUDE.md 既有 Meta-Principle(M1-M6)/ Mindset / Scope 預設 / 分權 canonical 有哪條適用?
-  - 若新 protocol 是 consistency-class audit → **必走 Phase 0 全掃再判**(CLAUDE.md「一致性類稽核必先全掃再判」)
+  - `packages/design-system/ds-canonical/` 既有 Meta-Principle(M1-M6)/ Scope 預設 / 分權 canonical 有哪條適用?
+  - 若新 protocol 是 consistency-class audit → **必走 Phase 0 全掃再判**(canonical design-system-audit「一致性類稽核必先全掃再判」)
   - 若新 protocol 是 audit skill → **必加 Self-improvement capture** Phase F step
   - **歷史**:2026-04-21 第一版 principle-audit-protocol.md 寫完未套「Phase 0 全掃」到 D6b/D6c,被 user 抓到「這也是跟一致性有關」才補。Meta-pattern:**新規則寫完,先跟既有原則 cross-check 再送出**。
 
@@ -328,6 +333,20 @@ Ant Design / Carbon / Apple HIG / VS Code / Figma。對每個 example,至少查
 
 **實例**(2026-04-22 Coachmark):Coachmark 原預設 autoFocus 到 chrome close X → 開 coachmark 立即彈「關閉」tooltip,打擾 user。修法:改走 body first interactive。此類行為應 DS-wide 強制。
 
+## Portal theme/density subtree escape canonical（M3,2026-05-31 audit-time）
+
+**為何 audit-time 不是 write-time hook**:M3 是 runtime CSS cascade + 設計意圖判斷 —— Portal overlay 搬到 `document.body` 後,CSS 繼承 chain 從 app root `<html data-theme>` 起算,**正解對 11 個 overlay 元件是「什麼都不做」**(自然繼承 app root),只有極少數(eg. OverflowIndicator 刻意 lock dark）才需顯式 set。「何時需要 override」無法靠 write-time regex 可靠決定(絕大多數情況不需要,硬偵測必大量誤判)→ 故**不設 hook**,改 audit-time visual probe(誠實:此 invariant 非機械可強制)。
+
+**新 Portal overlay 元件 merge 前必跑 dark-subtree visual probe**:
+1. 把 trigger 放進 `data-theme="dark"` subtree(或反向:trigger 在 dark、app root light)
+2. 開啟 overlay,截圖 Portal Content
+3. **驗**:Content 顏色對齊「它該繼承的 theme」(預設 = app root theme,不被 trigger subtree 污染);若元件刻意要繼承 trigger theme → 必在 spec 聲明 + 顯式 set `data-theme` on Portal Content
+4. **同類 chain**:`data-density` 部分 overlay 刻意 lock `md`(見 `density.spec.md`)→ 同樣 probe 驗
+
+**違反 → M3 portal escape bug**(歷史:DropdownMenu 在 dark subtree 變亮 / Avatar HoverCard NameCard 文字白色)。
+
+**D6e scan memory**:對所有 Portal overlay 元件,額外檢 spec 有無聲明 theme/density 繼承行為 + story 是否有 dark-subtree probe 覆蓋。
+
 ---
 
 ## Integration — 哪個 skill 在哪個 phase 跑 D6
@@ -354,11 +373,11 @@ skill 不再重複 scan 方法 / 判斷表。
 
 ## 本 protocol 自己也是活文件
 
-每次 audit 結束,main agent 自動回填 4 類學習(對齊 CLAUDE.md `# 資訊治理 canonical` → Audit skill Phase F 節):
+每次 audit 結束,main agent 自動回填 4 類學習(對齊 canonical Audit skill Phase F 節):
 
 1. 新 FP → 加到上方「常見 FP 記憶」
-2. 新 meta-pattern → 提議加到 CLAUDE.md `# Meta-Pattern 預警`
+2. 新 meta-pattern → 提議加到 `packages/design-system/ds-canonical/rules/meta-patterns.md`
 3. 新 canonical SSOT 擴張 → 提議加到對應 pattern spec
-4. User 糾正 → memory `feedback_*.md`
+4. User 糾正 → `governance/memory/feedback_*.md`
 
 無新 learning 必寫 "無新 pattern"(不省略,確保 step 被執行)。