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

package/ds-canonical/references/story-baseline-registry.schema.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qijenchen.dev/schemas/design-system/story-baseline-registry-v1.json",
+  "title": "Consumer story archetype registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "_meta", "components"],
+  "properties": {
+    "$schema": { "const": "./story-baseline-registry.schema.json" },
+    "schemaVersion": { "const": 1 },
+    "_meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "purpose",
+        "owner",
+        "consumed_by",
+        "provider_view_policy",
+        "rollout"
+      ],
+      "properties": {
+        "purpose": { "$ref": "#/$defs/nonEmptyString" },
+        "owner": {
+          "const": "packages/design-system/ds-canonical/references/story-baseline-registry.json"
+        },
+        "consumed_by": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/canonicalReference" }
+        },
+        "provider_view_policy": { "$ref": "#/$defs/nonEmptyString" },
+        "rollout": { "$ref": "#/$defs/nonEmptyString" }
+      }
+    },
+    "components": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["Sidebar", "DataTable", "ChromeHeader"],
+      "properties": {
+        "Sidebar": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["baseline", "requiredHelpers", "antiPatterns"],
+          "properties": {
+            "baseline": { "$ref": "#/$defs/canonicalReference" },
+            "requiredHelpers": { "$ref": "#/$defs/nameArray" },
+            "antiPatterns": { "$ref": "#/$defs/antiPatterns" }
+          }
+        },
+        "DataTable": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["baseline", "toolbar", "antiPatterns"],
+          "properties": {
+            "baseline": { "$ref": "#/$defs/canonicalReference" },
+            "toolbar": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "requiredHelpers",
+                "filterPanel",
+                "sortManager",
+                "buttonCanonical"
+              ],
+              "properties": {
+                "requiredHelpers": { "$ref": "#/$defs/nameArray" },
+                "filterPanel": { "$ref": "#/$defs/name" },
+                "sortManager": { "$ref": "#/$defs/name" },
+                "buttonCanonical": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "variant",
+                    "size",
+                    "iconOnly",
+                    "pressed",
+                    "rationale"
+                  ],
+                  "properties": {
+                    "variant": { "const": "text" },
+                    "size": { "const": "sm" },
+                    "iconOnly": { "const": true },
+                    "pressed": { "$ref": "#/$defs/nonEmptyString" },
+                    "rationale": { "$ref": "#/$defs/nonEmptyString" }
+                  }
+                }
+              }
+            },
+            "antiPatterns": { "$ref": "#/$defs/antiPatterns" }
+          }
+        },
+        "ChromeHeader": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["baseline", "requiredStructure", "antiPatterns"],
+          "properties": {
+            "baseline": { "$ref": "#/$defs/canonicalReference" },
+            "requiredStructure": { "$ref": "#/$defs/nonEmptyString" },
+            "antiPatterns": { "$ref": "#/$defs/antiPatterns" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "canonicalReference": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!\\.claude(?:/|$)|\\.agents(?:/|$)|\\.codex(?:/|$))(?!/)(?!.*(?:^|/)\\.\\.?/)(?!.*\\\\)[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
+    },
+    "nameArray": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/name" }
+    },
+    "antiPatterns": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/antiPattern" }
+    },
+    "antiPattern": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "regex", "severity", "rationale"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "regex": { "$ref": "#/$defs/nonEmptyString" },
+        "unlessRegex": { "$ref": "#/$defs/nonEmptyString" },
+        "severity": { "enum": ["block", "warn"] },
+        "rationale": { "$ref": "#/$defs/nonEmptyString" }
+      }
+    }
+  }
+}

package/ds-canonical/references/structural-token-retention.md

@@ -1,6 +1,6 @@
-# 結構性保留 token canonical(audit Dim 48 SSOT,2026-05-17 codified)
+# 結構性保留 token canonical(2026-05-17 codified;2026-07-10 對齊現制)
 
-某些 token 看起來「0 consumer」但屬**結構性保留**,不該 retire。**Sub-agent 跑 audit Dim 48 抓 0-consumer candidate 時必先過此 table,屬下列 6 類則 retract finding(不列為 violation)**。
+某些 token 看起來「0 consumer」但屬**結構性保留**,不該 retire。**現制**:Dim 48 = `scripts/audit-orphan-tokens.mjs --check`(2026-05-21 升級 chain deterministic script,structural-keep 分類器內建於 script,分類 SSOT → `tokens/orphan-tokens.spec.md`);**本檔 6 類 table 供全 dim sub-agent findings cross-check**(design-system-audit SKILL dispatch template triple-verify layer (c)),屬下列 6 類則 retract finding(不列為 violation)。
 
 ## 6 類結構性保留(對齊 Radix Color / Atlassian @atlaskit/tokens / Polaris polaris-tokens 三家共識)
 
@@ -8,7 +8,7 @@
 |---|---|---|
 | **1. Radix-style palette completeness** | `--color-{blue,deep-orange,orange,amber,yellow,lime,green,turquoise,indigo,purple,magenta}-{3,4,5,8,9,10}` / `--white-a{12,15,25,45,65,85}` / `--color-red-{1..10}`(red palette 因 semantic 重映射 deep-orange 而不直接消費)| Radix Color idiom 必 12 步階完整,即使目前只消費 step-{1,2,6,7} 給 Tag/Avatar,中間步階保留供未來 hue scale 擴充 / hue calibration 對照。Retire = 破壞 palette 完整契約,新加 hue 時需重新訂全套 |
 | **2. Forward-looking consumer reservation** | `--brand` / `--color-brand` | 預留給 consumer-layer(`src/app` / product UI)消費的品牌色 token。DS 本身不消費,跟 `--primary`(DS UI accent)分層。Retire = 未來產品做品牌頁時要重補 token + spec |
-| **3. Tailwind bridge alias to semantic state SOP** | `--color-warning-foreground` / `--color-status-{online,busy,away,offline}` / `--color-inverse-neutral-{hover,active}` | `@theme inline` bridge 讓 `bg-status-online` 類 utility 可用,即使現有 code 走 `var(--status-online)` direct(NameCard.tsx / Avatar.tsx / Tag.tsx 實際消費 underlying token 非 alias)。Bridge 是 future-proof Tailwind class consumption,retire = 限縮使用方式 |
+| **3. Tailwind bridge alias to semantic state SOP** | `--color-status-{online,busy,away,offline}` / `--color-inverse-neutral-{hover,active}` | `@theme inline` bridge 讓 `bg-status-online` 類 utility 可用,即使現有 code 走 `var(--status-online)` direct(NameCard.tsx / Avatar.tsx / Tag.tsx 實際消費 underlying token 非 alias)。Bridge 是 future-proof Tailwind class consumption,retire = 限縮使用方式。（2026-06-04:原 `--color-warning-foreground` 已移除——改名 `--on-emphasis-dark`,white/dark on-fill 配對見 color.spec.md）|
 | **4. State SOP 5 件套** | `--info-active / --success-active / --warning-active / --primary-text` 等 | semantic state 5 件套(base / hover / active / subtle / text)結構完整性,即使現有 active variant 無 consumer,保留供未來互動 state 擴充 |
 | **5. Type scale completeness** | `--font-h1-size` / `--font-h4-size` 等 typography utility | Type scale 12-tier completeness,即使現有 production 只用 h2/h3/h5,h1/h4/h6 預留供 marketing / hero / drawer title 等場景 |
 | **6. Elevation dark-mode pair** | `--elevation-100-hover / --elevation-200-hover` | `primitives.css:236,238,419,421` light + dark 雙模式各自定義 → 結構性 dual-tier,retire 會破 dark mode visual contract |
@@ -18,13 +18,10 @@
 - 真實 0 consumer + **0 forward-looking reservation** + **0 dark-mode pair** + **0 palette completeness role**
 - 對齊 Radix Color / Atlassian `@atlaskit/tokens` / Polaris polaris-tokens 三家 retire 政策共識
 
-## Sub-agent 強制 triple-verify before propose retire
+## Retire 判定與 findings cross-check(現制 pointer)
 
-對每 candidate retire token,sub-agent 必 verify 3 layer:
-
-1. **`grep -rn var(--TOKEN_NAME)` DS-wide**(含 `packages/design-system/src/**` + `src/app/**` + `src/explorations/**`)— 抓 direct `var()` consumption
-2. **`grep -rn "TOKEN_NAME"` 排除 css/spec.md 定義 + template literal usage**(eg. `\`h-table-row-${size}\``)— 抓動態 utility class generation
-3. **Cross-check 上 6 類**:屬任一 → retract finding,**不列 retire candidate**
+- **Retire 判定**走 `scripts/audit-orphan-tokens.mjs --check`(5 消費路徑:`var()` direct / `@theme inline` bridge / `@utility` body / Tailwind class-name match / JS literal mirror;+ structural-keep 分類器 + baseline gate)— 取代舊 sub-agent 手動 grep 協議。
+- **Sub-agent findings 通用 triple-verify**(file:line cite / spec 禁止事項 / canonical cross-check 含本檔 6 類)見 `design-system-audit/SKILL.md` sub-agent dispatch template。
 
 **任一 layer 顯示「有 consumer / 屬結構保留」→ 從 retire report 中拿掉**(不要送 user 拍板浪費時間)。
 
@@ -39,4 +36,4 @@ User verbatim 2026-05-17:「每次抓出的問題你他媽要給我基於我們
 ## 引用
 
 - `tokens/color/color.spec.md`「結構性保留 token canonical」(pointer 段)
-- `.claude/skills/design-system-audit/SKILL.md` Dim 48(sub-agent prompt 必 cite 本檔)
+- `packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md` sub-agent dispatch template triple-verify layer (c)(全 dim findings cross-check 通用;Dim 48 本體已改走 `audit-orphan-tokens.mjs`,分類 SSOT = `tokens/orphan-tokens.spec.md`)

package/ds-canonical/references/tailwind-gotchas.md

@@ -1,6 +1,6 @@
-# Tailwind 使用完整陷阱對照(從 CLAUDE.md 拆出)
+# Tailwind 使用完整陷阱對照(historical provenance:從 provider-specific generated adapter CLAUDE.md 拆出)
 
-`.claude/rules/ui-development.md`「Tailwind 5 條核心」段保留最精要 rules 和一行 bug anchor;完整範例、完整禁止清單、每條 bug 的詳細歷史在本檔。
+Canonical `packages/design-system/ds-canonical/rules/ui-development.md`「Tailwind 5 條核心」段保留最精要 rules 和一行 bug anchor;完整範例、完整禁止清單、每條 bug 的詳細歷史在本檔。
 
 ---
 
@@ -58,7 +58,7 @@
 
 | 類別 | 為什麼禁止 | 改用 |
 |------|----------|------|
-| `shadow-sm/md/lg/xl/2xl` | 繞過 elevation token 系統,沒跟 dark mode 調整聯動 | `shadow-[var(--elevation-100/200/300)]` |
+| `shadow-sm/md/lg/xl/2xl` | 繞過 elevation token 系統,沒跟 dark mode 調整聯動 | 用 `shadow-[var(--elevation-N)]` 其中 N ∈ `{100, 200}`(+`-hover` 變體;per elevation.spec.md tier;2026-05-31 修:無 300)|
 | 硬寫色值 `#xxx`, `rgb(...)`, `bg-red-500` | 繞過 semantic token,dark mode / brand swap 會斷 | 對應 semantic token |
 | Tailwind 預設 typography `text-xs/sm/base/lg` | 我們有自己的 `text-caption/body/body-lg/h1/h2` 系統 | 用我們的 typography token |
 | 硬寫 px 值 `w-[48px]` 當有 token | 失去 token 關聯,改值時零散處要一起改 | 對應 token 或 calc() |
@@ -84,4 +84,4 @@
 
 **為什麼**:shadcn alias 是「臨時橋」讓 shadcn add 不炸;我們有自己 design opinion 後直接用 own token,保持 DS 單一真實來源。允許 shadcn alias 進我們的 code = 慢慢讓 shadcn 命名污染回流,DS 自主性退化。
 
-**曾經發生的 bug**:Popover.tsx / Command.tsx 保留 shadcn template 的 `bg-popover`, `text-popover-foreground`, `text-muted-foreground`, `bg-accent`, `text-accent-foreground` 多處,2026-04-18 session 時 audit 發現統一遷移為 direct token(`bg-surface-raised` / `text-foreground` / `text-fg-muted` / `bg-neutral-hover`)。hook `check_token_hygiene.sh` 現已自動攔截此類回流。
+**曾經發生的 bug**:Popover.tsx / Command.tsx 保留 shadcn template 的 `bg-popover`, `text-popover-foreground`, `text-muted-foreground`, `bg-accent`, `text-accent-foreground` 多處,2026-04-18 session 時 audit 發現統一遷移為 direct token(`bg-surface-raised` / `text-foreground` / `text-fg-muted` / `bg-neutral-hover`)。hook `lib/_token_hygiene.sh`(由 `post_edit_dispatcher.sh` source)現已自動攔截此類回流(Check 1 shadcn alias)。

package/ds-canonical/references/ui-dev-rules.md

@@ -1,6 +1,6 @@
 # UI 開發規則 — 深度展開
 
-`.claude/rules/ui-development.md` 的 detail 版本。主章留 meta 規則(必重用既有 / 用 token / 檢查 pattern / `cn()` / 清 imports 後 runtime 驗證 / 一句話 pointer),本檔放 4 個 sub-rule 的完整規格。
+Canonical `packages/design-system/ds-canonical/rules/ui-development.md` 的 detail 版本。主章留 meta 規則(必重用既有 / 用 token / 檢查 pattern / `cn()` / 清 imports 後 runtime 驗證 / 一句話 pointer),本檔放 4 個 sub-rule 的完整規格。
 
 ---
 
@@ -58,3 +58,24 @@ Icon 尺寸按 context 分三類:
 | **一次性 / 非 row / 非 Button**(chrome / decorative / toolbar)| inline `size={n}`,**n 必對齊 uiSize token**(16/20/24,不自創)| `<FileIcon size={16} />` |
 
 **禁止**:Tailwind `w-4 h-4` / `size-4` 表達 icon size(是 dimension 非 semantic)/ Row 內手刻 `<Icon size={16} />` 繞過 Context(density 切換不聯動)/ 自創非 uiSize 值(`size={18}` / `size={22}`)。
+
+---
+
+## 小尺寸 icon stroke 補償 canonical(SSOT,2026-06-12 codify)
+
+**機制(3 層,2026-06-12 修正後)**:lucide SVG 等比縮放(stroke 隨尺寸自動變細)→ ① DS 全域預設 = **1.75**(`styles/base.css` `.lucide[stroke-width='2']`,只覆寫**沒有** explicit prop 的 icon;比 lucide 原廠 2 輕一階的整體風格)② component 顯式 `strokeWidth` prop → attribute 直接生效(補償用此)③ 本 DS **不用 `absoluteStrokeWidth`**(那是鎖絕對 px;我們要的是「小尺寸**相對**更粗」)。
+**⚠️ 失敗 anchor(2026-06-12,user 視覺抓到)**:base.css 原寫 `.lucide { stroke-width: 1.75 }` 無條件 → CSS class 蓋過 SVG attribute → 全 DS strokeWidth prop 自 2026-04-08 起**從未真渲染**(Checkbox 勾實畫 0.80px 而非設計的 1.50px;2026-05-18「3.5 vs 3 看不出差別」的視覺測試兩者其實都是 0.875px = 證據已被污染)。M2/M32 教訓:icon 粗細宣稱必驗 rendered DOM computed style + pixel,不可信 prop。
+
+**三個 bucket**(邊界判準 = 「控件內的裸線條 state glyph」才補償):
+
+| Bucket | 成員 | 規則 | 實畫 |
+|------|------|------|------|
+| **控件 state glyph**(裸 Check / X / Minus,線條稀疏,縮小後視覺權重不足)| Checkbox check/minus、Switch thumb check、Steps indicator、PeoplePicker avatar dismiss X | **12px → strokeWidth 3;16-20px → 2.5** | 1.5 / 1.67-2.08 |
+| **其他所有 icon**(Button startIcon、menu/chrome/toolbar icon、status icon 如 CircleCheck/Info/TriangleAlert — 自帶外框或與文字並排,跟文字 weight-matched)| Notice(Alert 家族)、FileItem status、ProgressBar status affix、Button、MenuItem…(DS 99% icon)| **不傳 prop → 全域 1.75** | 1.17 @16px / 1.46 @20px / 1.75 @24px |
+| **大型 illustrative**(≥32px)| Coachmark | 顯式調細 1.75(= 跟全域同值,語意上是「放大不增重」)| 2.33 @32px |
+
+fill-only shape(Rating Star `stroke="none"`、Radio dot `fill-current`)無此規則。
+
+**世界級對照**:SF Symbols 小 scale 非線性縮、stroke 隨文字 weight 補償(WWDC19 #206「it's not just linearly-scaled, the stroke thickness is adjusted」);Material Symbols opsz 軸自動小尺寸相對加粗(developers.google.com/fonts/docs/material_symbols「For the image to look the same at different sizes, the stroke weight changes as the icon size scales」);Carbon 線性縮但 16px 專屬重繪 override 集中在 checkmark/chevron 類 = 同樣只特調小 state glyph(github.com/carbon-design-system/carbon icons src 實測 68 個 16px override)。
+
+**值的 SSOT**:`checkbox.tsx` `checkStrokeWidth {sm:3, md:3, lg:2.5}`(2026-05-18 user 視覺證拍板);Switch `SPECS.checkStroke` / Steps `strokeWidth={2.5}` / PeoplePicker dismiss X 對齊此表。改值先改 checkbox.tsx 再同步全家族(M17)。

package/ds-canonical/rules/README.md

@@ -1,34 +1,39 @@
-# .claude/rules/ Charter
+---
+paths:
+  - "packages/design-system/ds-canonical/rules/**"
+---
+
+# Canonical rules charter
 
 ## 這裡只收:path-scoped 規則(編特定 file 才 load,降 every-session context cost)
 
 每條 rule 一個 `.md` file,內含:
-- frontmatter `paths:` glob(`**/*.spec.md` / `**/*.tsx` 等)— Claude Code 自動只在編該 path 時 inject 進 context
+- frontmatter `paths:` glob(`**/*.spec.md` / `**/*.tsx` 等)— provider materializer 可投影成原生 path-scoped discovery view
 - body — 該 file family 的設計 / 撰寫 / 命名 / 紀律規則
 
-**核心特徵**:**只在編對應 file 才載入**(不像 CLAUDE.md 每 session 載入)。對齊 Anthropic 2026 推薦 path-scoped CLAUDE.md fragment pattern。
+**Authority 邊界**:本目錄是唯一可編輯 owner；`.claude/rules/**` 等 provider discovery home 是可重建 adapter view。支援 path-scoped rules 的 provider 只在編對應 file 時載入；其他 provider 由 canonical bootstrap/skill 主動讀取。
 
 ## 當前居民
 
 | Rule | Paths | Scope |
 |------|-------|-------|
-| [meta-patterns.md](meta-patterns.md) | always(fundamental)| 31 active M-rules(M1-M32,M27/M33/M34/M35 retired)|
+| [meta-patterns.md](meta-patterns.md) | always(fundamental)| 32 active M-rules(M1-M32 + M36,M27/M33/M34/M35 retired)|
 | [spec-rules.md](spec-rules.md) | `**/*.spec.md` + `packages/design-system/src/**` | Spec 撰寫紀律 + SSOT / 邊界案例 / 職責分離 |
 | [ui-development.md](ui-development.md) | `**/*.tsx` + `**/*.ts` | 建 UI 前必讀 / Tailwind 5 條 / Token 4 條 / Props 命名 / shadcn |
 | [story-rules.md](story-rules.md) | `**/*.stories.tsx` | 三層 stories canonical + Title / 範例 / 撰寫紀律 |
-| [self-verify.md](self-verify.md) | `src/**` + `.claude/**` + `*.spec.md` + `*.tsx` + `*.css` | 4 階段(Pre/Mid/Post/Pre-commit)自主驗證 routine(2026-05-17 codify M10/M11/M20/M32 散在 meta-patterns 之 SSOT)|
+| [self-verify.md](self-verify.md) | `src/**` + canonical governance paths + `*.spec.md` + `*.tsx` + `*.css` | 4 階段(Pre/Mid/Post/Pre-commit)自主驗證 routine(2026-05-17 codify M10/M11/M20/M32 散在 meta-patterns 之 SSOT)|
 
-## 跟 CLAUDE.md 分工
+## 跟 provider bootstrap 分工
 
-| | CLAUDE.md | .claude/rules/ |
+| | Canonical/provider bootstrap | Canonical rules |
 |---|---|---|
-| 載入時機 | 每 session start 載入(行數預算 ≤ 200)| 編對應 path file 才載入(降 context cost)|
+| 載入時機 | 每 session start 載入(行數預算 ≤ 200)| 支援 path scope 的 adapter 於編對應 file 時載入；其他 provider 按 index 讀取 |
 | 內容 | 6 mindset + 治理 / 稽核 / SSOT canonical / 任務導航 / fundamental rules | 該 file family 細節規則(spec 撰寫 / UI 開發 / story / self-verify)|
 
 ## 新增 rule 流程
 
-1. **過 3 題**(per CLAUDE.md `# 治理 canonical`)— 既有 rule cover?Rule-of-3?7 天後還 fire 嗎?
+1. **過 3 題**(per AGENTS.md `# 治理 canonical`)— 既有 rule cover?Rule-of-3?7 天後還 fire 嗎?
 2. **檔名**:`<topic>.md`(kebab-case),內含 frontmatter
 3. **paths frontmatter**:glob 該 rule 該 load 的 path
 4. **加進本 README.md 表格**
-5. **MEMORY.md / CLAUDE.md 補 pointer**(若 cross-reference)
+5. **MEMORY.md / AGENTS.md 補 pointer**(若 cross-reference)

package/ds-canonical/rules/meta-patterns.md

@@ -1,10 +1,10 @@
-# Meta-Pattern 預警(31 active M-rules)
+# Meta-Pattern 預警(32 active M-rules)
 
-**mindset #6 的具體化**。每條吸收數十個具體 bug,是失敗記憶索引上游。任務前先過全部 M-rules(M1-M32,M27 retired 2026-05-15 → M23(c) child / M33-M35 retired 2026-05-22 → folded into M20/M7/M23(d) per `/knowledge-prune` deep audit Lens 1+2)。
+**mindset #6 的具體化**。每條吸收數十個具體 bug,是失敗記憶索引上游。任務前先過全部 M-rules(M1-M32 + M36,M27 retired 2026-05-15 → M23(c) child / M33-M35 retired 2026-05-22 → folded into M20/M7/M23(d) per `/knowledge-prune` deep audit Lens 1+2)。
 
 ## 2026-05-10 cluster cross-link(per codex Q-13 deep prune audit + 2026-05-22 fold update)
 
-31 M-rules(M1-M32,M27/M33/M34/M35 retired)分 6 cluster(舉一反三 grouping):
+32 M-rules(M1-M32 + M36,M27/M33/M34/M35 retired)分 6 cluster(舉一反三 grouping):
 
 | Cluster | M-rules | 共同主軸 |
 |---|---|---|
@@ -13,7 +13,7 @@
 | **C. Auto-integrate pipeline** | M14 / M19 / M31 | 對話結論 5-layer / trigger phrase auto-pipeline / claude-codex 5-step |
 | **D. Verify / similar-bug / visual coverage** | M10 / M13 / M15 | proactive scan / user 第 2 次截圖 / visual-audit-coverable |
 | **E. Propose-time discipline** | M18 / M21@watch | 4-Q 自檢 / 新元件抽象前 prop variant test |
-| **F. Sharp invariants(各自獨立)** | M2 / M3 / M4 / M5 / M6 / M7(含 M34 子規則)/ M9 / M11 / M12 / M16@watch / M17 / M20(含 M33 子規則)/ M24 / M25@watch / M28 / M30@watch / M32 | sharp invariant |
+| **F. Sharp invariants(各自獨立)** | M2 / M3 / M4 / M5 / M6 / M7(含 M34 子規則)/ M9 / M11 / M12 / M16@watch / M17 / M20(含 M33 子規則)/ M24 / M25@watch / M28 / M32 / M36 | sharp invariant(M30 歸 cluster A,曾誤雙列) |
 
 `@watch` 標記(2026-05-15)= 該 M-rule 目前 absorbs 1-2 bugs(charter 要 ≥3)。1 quarter 觀察:無新 bug → demote 為既有 M-rule 子規則;有新 bug → 升 sharp keep。**2026-05-22 fold prune**:M33/M34/M35 各 absorb 1 bug → folded into parent cluster home(M33→M20 / M34→M7 / M35→M23(d)),減 3 條 M-rule 同時保留全部 invariants。Velocity 修正:本季 net add 12 rules(15 new − 3 fold)= 18 → 12 趨近 charter ≤3/quarter target,持續觀察。
 
@@ -21,19 +21,19 @@
 
 ## 2026-05-10 skills consolidation analysis(Task #20 closed)
 
-**Per Anthropic「~10 sweet spot」benchmark**:DS 現有 20 skills(`.claude/skills/` minus README),約 2x Anthropic typical recommend。**Verdict:無 aggressive merge candidate**,維持 20 skills justified:
+**Per Anthropic「~10 sweet spot」benchmark**:DS 現有 25 canonical skills(`packages/design-system/ds-canonical/skills/` 的一層目錄,2026-07-31 inventory),約 2.5x Anthropic typical recommend。**Verdict:無 aggressive merge candidate**,維持 25 skills justified:
 
 | 類別 | Skills | 為何不 merge |
 |---|---|---|
 | Core audit | design-system-audit / visual-audit / component-quality-gate / knowledge-prune | 各 sharp trigger,invoke logs 顯示高頻(design-system-audit 6 / knowledge-prune 7) |
 | Domain audit | ux-audit / performance-audit / code-quality-audit / product-ui-audit | D2/D3/D4/consumer-code dim 已 chain 進 design-system-audit |
-| Workflow | prototype / new-component / delivery-handoff / story-writing / story-auto-compile-migrate | create / prototype / final-handoff / story 各 phase distinct rare-event(per knowledge-prune retire rule 例外) |
+| Workflow | prototype / new-component / delivery-handoff / story-writing / story-auto-compile-migrate / bug-fix-rhythm / governance-status | create / prototype / final-handoff / story / multi-fix rhythm / read-only status 各 phase distinct |
 | Discipline | ensure-canonical / propose-options / codify-principle / codify-corrections / scan-similar-bugs / governance-health | trigger phrase / 4-Q gate / 5-layer artifact gen / batch log / post-fix scan / monthly metric 各 unique |
-| Collab | codex-collab | M31 5-step home,unique |
+| Review / collaboration | codex-collab / canonical-reviewer / independent-review / deep-audit-cross-codex | 一般 cross-provider synthesis / canonical-only review / product-consumer review / no-sample deep audit 的 scope 與證據契約不同 |
 
-**Marginal merge candidate**(留 user 後續 explicit approve):`codify-principle` + `codify-corrections` 都產 5-layer artifact,trigger 不同(live propose vs batch log)— 可合 `codify` 一統 skill。**不執行原因**:codex Q-13 sharp-rule preference + auto-mode 不 destructive 風險 + 兩 skill SKILL.md 各自 250 lines budget 內。User 後續 invoke `/knowledge-prune` 並 explicit approve 才動。
+**Marginal merge candidate**(Backlog,不擴張目前 frozen scope):`codify-principle` + `codify-corrections` 都產 5-layer artifact,trigger 不同(live propose vs batch log)— 可合 `codify` 一統 skill。**目前不執行原因**:codex Q-13 sharp-rule preference + 兩 skill SKILL.md 各自 250 lines budget 內，尚無 evidence 顯示合併是當前 Requirement 必需。未來若進入 frozen scope，由最高 certified capability 依 evidence 作工程判斷；task／deliverable 明確要求時才加 independent review，不需 user 工程核准。
 
-**RFC**:Anthropic「~10 sweet spot」是 typical CRUD app benchmark;DS governance complexity(31 active M-rules + 全 dim audit per design-system-audit SSOT + dual-track codex collab + 8-home 治理)justified higher skill count。每 skill 都過 knowledge-prune retire rule(6 月 fire 或 rare-event 豁免)。
+**RFC**:Anthropic「~10 sweet spot」是 typical CRUD app benchmark;DS governance complexity（active M-rules / full-dimension audit / optional cross-provider review / Level 1–9 taxonomy）justified higher skill count。動態數量以 canonical counters / inventory 為準；每 skill 都過 knowledge-prune retire rule(3 月 invoke 或 rare-event 豁免;hooks 才是 6 月 fire,SSOT → knowledge-prune/SKILL.md)。
 
 
 | # | Meta-Principle | 能吸收的 bug 類型(舉例,非窮舉) |
@@ -45,33 +45,33 @@
 | **M5** | **視覺 canonical 必 spec 聲明所有 state 疊加組合**。單一 state(today / selected / hover / disabled)有視覺定義不夠;**所有兩兩疊加、三疊加組合也要在 spec 有明文**。 | DatePicker today+selected 隱形 / hover+disabled ring 仍顯示(詳 historical-bugs.md) |
 | **M6** | **Stakeholder-visible 產出 → 強制進階稽核才出稿**(不是 merge 後補)。任何「有視覺可以給 stakeholder 看」的產出(新元件 / 元件新功能 / 新產品頁 / 比稿)**必過進階完整稽核**(6 維 + 全截圖視覺驗證)。日常 dev 可用高效模式,stakeholder gate 不可。 | FileViewer 初版 8+ 項給人看才發現(詳 historical-bugs.md) |
 | **M7** | **新 protocol / skill / rule 寫完,必反向 cross-check 既有 Meta-Principle 是否該套用**。尤其:consistency-class 的 protocol 必走「一致性類稽核必先全掃再判」(本章節);audit skill 必加「Self-improvement capture」Phase F step;Rule 觸及「canonical」「SSOT」「rationale」keyword → 必明示 substantive vs 表達層分權。**+ Sub-rule M34 (folded 2026-05-22)**:Hook detection regex 必對齊 spec wording 廣度。Triple test before merge new hook — (1) Spec rule wording 是「一般類別」(broad)還是「特定 keyword」(narrow)?(2) Hook regex 匹配「一般類別」還是只「特定 keyword subset」?(3) Spec broad + Hook narrow → **gap**,必擴 hook regex(unicode pattern / negative-list approach / counter-example DS-wide scan)。Propose 新 hook 必先寫 3-column table:`Spec wording` / `Hook regex` / `Gap?(broad-vs-narrow)`。 | principle-audit-protocol v1 漏套既有 Phase 0 全掃;2026-05-17 story name `照妳` `決策N` 等中英人話 detection regex 漏 |
-| **M8** | **訂立 / 修改 cross-component canonical 前必 world-class benchmark**。任何 predicate / decision tree / taxonomy 類 spec,**必先 grep 至少 3 家世界級 DS**(Polaris / Material / Atlassian / Ant Design / Carbon / Apple HIG / VS Code / Figma 等)列對照表,再訂 rule。**絕對禁止**憑直覺開場寫 predicate,user 問才補對照。每個 category / variant / case 必附世界級 reference(實作名或 API 指向),沒有對照的 rule 視同未成熟,走 Checkpoint 3。 | item-anatomy Inline Action 疊代 4 次才有世界級對照 |
+| **M8** | **訂立 / 修改 cross-component canonical 前必 world-class benchmark**。任何 predicate / decision tree / taxonomy 類 spec,**必先 grep 至少 3 家世界級 DS**(Polaris / Material / Atlassian / Ant Design / Carbon / Apple HIG / VS Code / Figma 等)列對照表,再訂 rule。**絕對禁止**憑直覺開場寫 predicate,user 問才補對照。每個 category / variant / case 必附世界級 reference(實作名或 API 指向)；沒有對照的 rule 視同未成熟，工程 rule 先擴大 research，task／deliverable 明確要求 peer 時才因缺 review 標 `REVIEW-BLOCKED`；只有採用 OG-only 產品／UI／UX原則是真人決策。 | item-anatomy Inline Action 疊代 4 次才有世界級對照 |
 | **M9** | **Predicate / decision tree 寫完,present 前必 4 題自測**,防 membership drift。(a) 每 example 回跑決策樹;(b) cap / constraint cross-check;(c) 每 example 對 ≥3 家 world-class DS;(d) 每 category ≥1 example。任一題失敗 → 重收斂,**禁止 present**。 | Cat 1 IA 塞 endAction / FileItem sm 違 ≤24 cap |
-| **M10** | **Proactive exhaustive scan**:canonical migration 完成前禁止只改「直覺相關」元件;final report 前禁止省略「我知道但沒講」的 tech debt。**Mechanical 落地**:每 fix commit 後 `/scan-similar-bugs` skill 強制 grep DS-wide。 | dismiss migration 漏 FileViewer / 7 題 silent tech debt user 一次炸 |
+| **M10** | **Proactive exhaustive scan**:canonical migration 完成前禁止只改「直覺相關」元件;final report 前禁止省略「我知道但沒講」的 tech debt。**Mechanical 落地**:batch-end(session ≥2 fix commits)跑一次 `/scan-similar-bugs` grep DS-wide(2026-05-12 per-fix → batch-end 重構);`session_start_governance_check.sh` Check 6 偵測 24h 內 fix commit 漏跑 → soft 提醒。**+ Sub-rule 掃描不得截斷(2026-08-07)**:盤「誰在讀這個值 / 誰呼叫這個函式」時,grep 一律**禁接 `head -N` / `-m`** —— 截斷是假陰性,會把還有人讀的東西誤判成死狀態而刪掉。要收斂輸出改用 `-l`(只列檔)或 `\| wc -l` 先看總數,確認總數後再全看。同理 `cmd \| head` 的 exit code 屬於 head,`&&` 分支會報出相反結論,判斷成敗必看 `PIPESTATUS`。**刪除／歸零任何欄位前,必須先把 reader 清單列完整**,只查到一個入口就下結論 = 違反。**+ Sub-rule 自檢不得只做單句層級(2026-08-09)**:任何「全盤檢查／稽核／確認沒問題」都必須跑**兩個維度**——(1) **逐句驗證據**(cite／數字／引文逐字);(2) **全體結論兩兩相容性**——把文件所有結論列成清單,逐對問「這兩條能同時為真嗎」。只做 (1) = **假檢查**,因為矛盾在單句層級恆為隱形(每句單看都成立)。且**任何一旦成立的結論必須當場登記進該文件的結論總帳**——沒登記的結論會在後續回合被重新當成未決題辯論。 | dismiss migration 漏 FileViewer / 7 題 silent tech debt user 一次炸;2026-08-07 grep 接 head 截斷 = 假陰性鎖死升級路線;2026-08-09 結論未入總帳 → 兩輪無謂辯論(詳 historical-bugs.md) |
 | **M11** | **User-perspective interactive state walk**:改完 UI 後 present 前必親自走 7 題 self-test(static / hover / focus-visible / active / keyboard / 範例真實性 / CSS 對稱)。每 UI 改動未跑 7 題就 commit = 違反。 | ListBody 修完 user 連抓 5 波 |
 | **M12** | **Binary strict rule + fix-time root-invariant pre-question(「必 X」/「禁 Y」/ bug fix)前必 benchmark + invariant test**。3 題自測:≥3 家世界級一致 / counter-example scan / root invariant vs surface observation。震盪症狀(A→not A→A)= meta invariant 沒抓到,**停下 present**。**Fix-time 延伸**(2026-05-12 absorbs 原 M32(b)):visual / behavior bug 改前必 inline 答 3 題 — Q1「root invariant 是什麼?」Q2「symptom 在哪 layer?」Q3「fix 是 root-layer 還是 surface-layer?」。surface-only 修(改 symptom 不動 invariant)違反。對齊 5-whys / Toyota TPS / Linux kernel「fix the root not symptom」canonical。 | hover bg 震盪 4 次(bg-edge vs content-padding invariant);2026-05-12 cell-align fix surface-modify Field padding 不動 inline-flex `!h-full` root invariant |
 | **M13** | **User 第 2 次提相關問題 → 自動截圖 verify**。當 user 就同一視覺 / 行為主題第 2 次問 / 糾正,AI 必 invoke 截圖 verify(`visual-audit.mjs --scope=component:XXX`)。第 3 次才 verify = 違反。**Corollary**:user 指定「所有 X 都要 Y」,同 session 全部做完 + 建 hook 防線。 | avatar-NameCard migration 分批拖延 user 第 2 次催才全改 |
-| **M14** | **對話結論 → AUTO integrate pipeline**(不等 user 催)。每次 canonical / 設計決策 / 新 rule 結論時必執行 5-layer pipeline ≥ 3 層落地:M8 benchmark / SSOT home 識別 / spec / code / hook / CLAUDE.md / memory / 驗證。User 問「有沒有整合到 X」= M14 violation。**Governance auto-trigger**:`session_start_governance_check.sh` 檢查 hook / memory / CLAUDE.md / 上次 prune 達標 → 自動 inject「建議 /knowledge-prune」directive(soft 提示;hard cap 升 BLOCKER)。**數值 SSOT**:`session_start_governance_check.sh`(L19-22 + L173)+ CLAUDE.md `# 治理 canonical` 行數預算表;本 M-rule 不重述,避免 drift。 | chrome-header / dismiss / hoverCard 每個都 user 提醒才整合 |
+| **M14** | **對話結論 → AUTO integrate pipeline**(不等 user 催)。每次 canonical / 設計決策 / 新 rule 結論時必執行 5-layer pipeline ≥ 3 層落地:M8 benchmark / SSOT home 識別 / spec / code / hook / AGENTS.md / memory / 驗證。User 問「有沒有整合到 X」= M14 violation。**Governance auto-trigger**:`session_start_governance_check.sh` 檢查 hook / memory / AGENTS.md / 上次 prune 達標 → 自動 inject /knowledge-prune directive(soft 提示;hard cap 升 BLOCKER;**deep-audit 收尾例外 = 必自動跑、禁問 user**,SSOT → deep-audit-cross-codex SKILL C.0a,2026-06-11 user 糾正 codify)。**數值 SSOT**:`session_start_governance_check.sh`(檔頭「Checks + thresholds」註解 + Check 7)+ AGENTS.md `# 治理 canonical` 行數預算表;本 M-rule 不重述,避免 drift。 | chrome-header / dismiss / hoverCard 每個都 user 提醒才整合 |
 | **M15** | **Product UI flow 必須 visual-audit coverable**。任何 stakeholder-facing flow 必含 OpenSnapshot 類 stories(`defaultOpen` / `useState(true)` / `play()`)。禁留「需真人點擊才能看到的 state」未截圖。 | Sheet / FileViewer 只截 trigger 缺 OpenSnapshot |
 | **M16** | **訂 standalone card/pill 容器 canonical 必同步訂 multi-instance gap canonical**(`@watch` 2026-05-22)。3 條公式:同類 standalone → 必 gap;同類 permanent flush → 0 gap OK;混合語言 → 必取最保守 gap。Hook `check_item_list_gap.sh` 預警 + audit dim verify。**@watch 2026-05-22**:單 bug source(FileItem rich/compact)— 1 quarter 觀察是否 absorb ≥3 同類 bug,否則 demote 為 item-anatomy.spec.md 子規則。 | FileItem rich card + compact bg 連續相連 |
 | **M17** | **SSOT 必可傳播**(非僅 markdown)。同值 / 同公式 hard-code 在 3+ consumer = 必抽成 token / primitive / utility class。**兩層 SSOT 架構**:底層 token(值可調)+ primitive(結構封裝 + 消費 token);世界級對照 Material/Carbon/Ant/Polaris 共識。 | mt-0.5 canonical 13 consumer hard-code 假 SSOT |
-| **M18** | **Propose-time 6 題自檢 gate**(2026-05-18 升 4→6 加 Q0 + Q5)。列 option / 建議前必 inline 跑 **Q0 Pre-ASK self-verify problem 真存在**(2026-05-18 加,absorbs Sheet/inline-action/SurfaceBody 三題誤判)/ Q1 M8 benchmark / Q1' M23 DS canonical / Q2 M17 SSOT / Q3 Rule-of-3 / Q4 M10 下游吸收 / Q5 Issue 100% mapped。Reject 不列出,通過寫 6-Q 證據表。**Q0 強制動作**:propose 給 user 拍板前必 grep DS-wide + Read 相關 spec.md + Read consumer usage 確認 problem 真存在,沒 grep 就斷言「N 元件缺 X / 該 migrate」= 撤回 propose。SSOT → `.claude/skills/propose-options/SKILL.md`。Hook `check_propose_pre_grep_verify.sh` 機械強制 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 包括所有實作代碼,自主自動驗證這些問題是否真的是問題」 |
-| **M19** | **Trigger phrase auto-pipeline**。「確保 / 一定 / 永不漂移 / ensure / always」trigger → 自動 5-layer ≥ 3 層落地 + M8 + M17 + M10。Substantive 走 STOP。SSOT → `.claude/skills/ensure-canonical/SKILL.md`。 | story splitting 2026-04-26 user 第 N 次強調才落地 |
-| **M20** | **AI 自問 best-practice + 自動 self-improve**(不靠 user 提醒)。Stop hook `rule_infra_best_practice_score`(R5 in `stop_passive_logging.sh`,2026-05-13 folded from retired `stop_meta_self_audit.sh`)每 turn 跑 score → < 80 / regression ≥ 5 log to `score-history.jsonl`;next-turn UserPromptSubmit `inject_pending_self_audit.sh` 注入 BLOCKER prompt。**Threshold 數值 SSOT**:`session_start_governance_check.sh`(L19-22 + L173)+ CLAUDE.md `# 治理 canonical` 行數預算表;本 M-rule 不重述具體 cap,避免多 home 漂移(2026-05-22 prune codify per Rule-of-3 violation fix)。**+ Sub-rule M33 (folded 2026-05-22)**:Stop hook overfire → AI conservative-defer 反 pattern。同 stop hook fire ≥ 5 次 within session → AI 自動 hedge / 撤回 claim / 「下個 session」defer **可做工作**。真理由 vs 偽 prereq 區辨 — (a)真 prereq 缺(cross-frame test fixture 等)= 具體 deliverable need;(b)偽 prereq(「context budget」「省工」「下個 session」)= conditioned hedge,user 反覆催 = 真理由不存在。**Rule**:AI reply 含「下個 session」「context budget」「省工」keyword 且前 1 turn user 已拍板「全部做完」/「繼續」/「沒理由不做」→ BLOCKER。對齊 Atlassian「stop using vague defer」+ Linux kernel patch review。 | user 10 次問「best-practice 嗎」直到外部 benchmark 確認真 gap;2026-05-13 claim-verify-gap stop hook fire 12+ 次 → 我每 reply 自動 hedge → user 多次糾正「沒理由不做」 |
-| **M21** | **新元件 / 新 sub-component 抽象前必過 prop variant test**。當新元件名 = `<Existing>+suffix`(Time / Range / Color / Light / Dark / Filled / Outline / Compact / Rich)→ 強烈 signal 應為 prop variant on `<Existing>`。3-test 通過才能分(全失敗 → prop):(1) `<Existing>` 加 prop 無法達成同 DOM/behavior?(2) ≥3 家 world-class DS 用分離元件而非 prop(必 cite source)?(3) value 結構或 contract 真的不同(如 Range = [start, end])?Hook check_premature_abstraction(retired/未實作;mindset enforcement)。 | DateTimePicker 從 DatePicker 拆 → 撤回合併 `<DatePicker showTime>`(2026-05-02);DataTableFilterPanel 5-file → 撤回 sub-file pattern |
-| **M22** | **Benchmark claim 必附 inline source citation**(不可憑印象)。寫 spec / tsx 含「Ant / Material / Polaris / Atlassian / Carbon / shadcn / Radix」等 world-class DS claim,必同段附:(a) inline URL(domain 對應 DS 官網 / GitHub source);(b) GitHub source path + line ref `#L42`;(c) screenshot reference `snapshots/...`;(d) 顯式撤回 `@benchmark-unverified`。Hook `check_benchmark_citation.sh` 機械化警告(P1 soft)。每次 implement 前跑 WebFetch 取真 source,不憑印象解碼。 | claim「Ant showTime range = 2 calendars」憑印象,實證 source code `multiplePanel = false` = 1 calendar(2026-05-02 鬼話事件)|
-| **M23** | **DS 內既有 canonical 優先於外部 benchmark**。寫 visual decision(color / size / spacing / typography / state)/ prop name namespace 前必先 grep DS 既有 codified token / variant / pattern / prop;命中 → 必對齊;沒命中 → 才引 world-class + 同步補 canonical。**禁止**:外部 benchmark(M22 cite OK)直接覆蓋 DS 內已有 canonical。Mindset #2「優先消費既有」的 visual layer。判斷流程:(a) grep 該屬性 / prop 既有 token/variant/usage;(b) 命中 canonical?有 → 用,沒 → 走 M22 cite 然後 codify;(c) **prop name conflict 子規則**(former M27,2026-05-15 collapsed):外部 framework prop name(TanStack `size` / Radix `disabled` / dnd-kit attrs 等)跟 DS 既有 prop 同字不同義 → wrap-and-rename(DS-internal naming + pre-process map);(d) **nearest same-purpose canonical wins 子規則**(former M35,2026-05-22 folded):寫 stories / UI composition wrap 既有 primitive 前必先 grep + Read primitive 的「完整佈局」production canonical story(eg. `sidebar.stories.tsx#IconCollapse`)抄 archetype 結構 / helper / variant — 不准憑記憶寫 simplified mock。**Cite 存在 ≠ consume 落實**(codex 2026-05-20 verdict)。最相近同目的 canonical 用法 > 泛用 component spec / 寬鬆 pattern wording。Registry SSOT `.claude/references/story-baseline-registry.json` + hook `check_story_invariants.sh R8 story_archetype_registry`。 | 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。2026-05-20 AppShell-vs-Sidebar drift:simplified mock + jargon + wrong variant + 不消費 primitive props。Hook `check_data_table_size_num_to_meta_width.sh` + `check_story_invariants.sh R8` |
-| **M24** | **State 顯著性 precedence:disabled > muted > emphasis**。元件在 disabled state 時,內部所有文字載體(label / value / placeholder / icon)統一切 disabled token(`text-fg-disabled` neutral-6),**不**繼續 muted token(`text-fg-muted` neutral-7)。muted 是裝飾,disabled 是語意 state — state 勝 emphasis。同理:error / warning state 內 placeholder 應對應 state token。Hook check_disabled_placeholder_color(retired/未實作;mindset enforcement)。 | 2026-05-04 5+ violation:`bareInputStyles` 永遠 muted / `select.tsx` 3 處 plain&tag empty 不分 mode / `textarea.tsx` 同;Input.tsx 唯一做對。User 5+ 次糾正才 codify |
-| **M25** | **Layered chain invariant 必整鏈 forward(viewport-aware overlay scroll 範例)**。Overlay surface(Popover / HoverCard / Dialog / Sheet)的 viewport-aware scroll 機制要求 root → SurfaceBody 之間**所有中間 wrapper 都 forward `flex flex-col h-full`**;任何中間 div 沒 forward → SurfaceBody flex-1 失效 → body 不 scroll。同類 chain pattern:density 透傳 / fieldCtx 鏈 / theme subtree(M3 portal 逃逸對偶)。Hook check_overlay_panel_scroll_chain(retired/未實作;mindset enforcement)。 | 2026-05-04:Filter / Sort panel root `<div w-[640px]>` 無 flex-col → user 縮 viewport 時 body 不 scroll。NameCard 因自設 max-h flex-col 才繞過(無中間 wrapper) |
-| **M26** | **Behavior / visual canonical decision 前必跑 WebFetch + WebSearch 取 ≥ 3 source,不可憑印象 propose**。M22 升級版 — M22 管「寫 spec / tsx 含 claim 必附 cite」(實作後),M26 管「propose / 決策前必先 fetch」(實作前)。Pipeline:(1) WebFetch 3 家世界級 source(Atlassian / Material / Polaris / Ant / Carbon / Apple HIG / shadcn / Radix);(2) 全 403 → WebSearch fallback 用 snippet,**明示「search-only confidence」**;(3) WebFetch + WebSearch 都失敗 → STOP propose,告知 user「無法 verify,要看 screenshot/實機」。Hook `check_propose_without_benchmark.sh`(PreToolUse Edit/Write 攔截 visual decision keywords + 近 N turn 無 fetch tool call → BLOCKER)。 | 2026-05-05:user 反覆糾「為什麼每次都沒 webfetch 只憑印象」— Jira drag handle / cell display 兩題我憑印象 propose 多輪;升級成硬規範 |
-<!-- M27 retired 2026-05-15(per /knowledge-prune D3 audit):self-flagged「M23 子規則」 → collapsed into M23 sub-bullet (c) "framework prop name namespace conflict"。Original case (TanStack size vs DS density) + hook `check_data_table_size_num_to_meta_width.sh` retained 在 M23 children。 -->
-
-| **M28** | **Solo-work git ops 必先 grep canonical**(mindset #2 AI-ops 子規則)。AI 自己 git/branch/PR/merge ops(`git checkout -b` / `gh pr create` / `git push origin main` / `mcp__github__create_pull_request` / `mcp__github__merge_pull_request`)前必 grep `.claude/memory/feedback_solo_dev_workflow.md` + CLAUDE.md `# Git solo-work canonical`,**不憑直覺反射開新 branch / 開 PR / 自決 merge**。Solo work 鐵律:1 chat = 1 working branch / no PR / 等 user「push」 trigger 才 merge main。Hook `check_solo_workflow.sh` 機械化攔(R1 第 2 個 branch / R2 PR creation / R3 merge 無 user trigger keyword)+ override `CLAUDE_BYPASS_SOLO_WORKFLOW=1` audit-logged。 | 2026-05-08:同 session AI 開 5 branch + 2 PR (#7 #8),user 第 3 次糾正才升 mechanical;memory file 2026-05-04 codified 但 markdown 級 + AI 沒 grep 直接憑印象 = mindset #2 違反 |
-| **M29** | **DS Anchor Preflight invariant — 視覺 / 結構 propose 前必 grep `*.spec.md` 找 owner SSOT**。動 component / pattern / token 視覺結構前,**必先**:(a) `rg <touched component> + <behavior keyword>` in `packages/design-system/src/**/*.spec.md` (b) 出 **3-column owner table**(`candidate owner spec` / `canonical sentence/table row` / `conflicting code/comment if any`)(c) 若 spec ≠ code → STOP 寫 RFC 不直接 propose implementation。沒 3-column = anti-pattern,提案不被接受。SSOT index `.claude/references/ssot-index.md`(high-risk interface owner mapping)Step 0.1 先查再 grep verify。Hook `check_ds_anchor_preflight.sh` soft warn。codex-collab/SKILL.md Step 0.1 mandatory pre-grep。對齊 Carbon「design spec is source of truth」+ Atlassian「system-wide coordination first」。 | 2026-05-08:Claude+Codex 連 5 round 跳過 spec anchor pre-grep,直覺加 primitive(D path / Path A);user 抓「為何沒研讀設計原則」 |
-| **M30** | **Wrapper-vs-primitive schema unify invariant — wrapper API option / config schema 必 `extends` primitive SSOT,且 wrapper 內部轉換 mapping 必 forward 全 primitive surface field**。Primitive(`SelectMenuOption` / `MenuItemProps` / `ItemAnatomyProps` 等)宣告 SSOT 後,所有 wrapper(`Select.SelectOption` / `Combobox.SelectOption` / `PeoplePicker` 等)若有同類 schema,(a) 用 TypeScript `extends primitive` 機械繼承,**不可平行 declare** weak schema(同名 / 部分欄位)(b) wrapper 內部 `xxxToYyy()` mapping 必 forward 全 primitive surface field(不可只 forward `value` + `label`,silently drop avatar / description / disabled 等)(c) wrapper-only field 加在 `extends body`(不污染 primitive)。Hook `check_wrapper_primitive_schema_drift.sh` 機械強制(P0 BLOCKER):grep `export interface .*Option \{` cross components/,同名 ≥ 2 處且未 `extends` primitive → BLOCK。對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown wrapper-vs-primitive schema-extension idiom。 | 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。 |
-| **M32** | **Audit script 必 pixel-quantified verify ≠ attribute existence**(2026-05-12)。Audit 必驗 `rect.top / .left / .height` numeric pixel,**不**可只驗 `getAttribute('data-state')` / `class.includes(...)` = false-positive trap(DOM-pass ≠ visual-pass)。對齊 Material X-DataGrid / AG Grid playwright pixel snapshot / Polaris visual diff canonical。Hook `check_pixel_quantified_audit.sh` 機械強制(scans `getAttribute(` without paired `getBoundingClientRect(`)。**Split note**:原 mega 8 sub-invariants 拆 4 home — (b) fix-time root-invariant → M12 extension / (c)(d)(h) batch + parallel + claim-verify → `/bug-fix-rhythm` skill / (e) tool preflight → memory `feedback_tool_binary_preflight_sweep.md` / (f) ship gate → CLAUDE.md `# 稽核 canonical` / (g) Layer marker → M31 + hook。git blame 2026-05-12 commit 留 audit trail。 | 2026-05-12 4 audit-vs-visual gap absorbed:cell-align / divider 2px / breadcrumb tooltip / row-alignment 全 audit「Δ=0 ALL PASS」但 user 抓視覺壞(詳 historical-bugs.md)。|
-| **M31** | **Adversarial dual-track 5-step canonical**(2026-05-10 user directive,verbatim quotes → `memory/feedback_codex_dual_track_synthesizer.md`)。**Step 0 入口 gate**:Claude 自試(grep / read source / cite DS canonical / WebFetch)完;啟 codex collab criteria 兩種:(a)自試卡 root cause / design tradeoff,OR(b)user 明確 keyword「跟 codex 討論 / 比稿 / 辯論 / dual-track」。**禁** auto-fire。**Step 1-5**(啟動後每題必過):(1)各自熟讀 spec/canonical/source(M29 anchor pre-grep + M23 既有 canonical 優先)(2)各自驗證(`tsc -b` + invariant + audit;codex `exec -s read-only`)— **不可只一方 verify**(M20)(3)各自視覺稽核(playwright + DOM inspect + pixel-level)(4)各自 3-column cite propose(`spec.md path:line / 引文 quote / reasoning`)— hand-wave 無 cite 自動撤回(5)整合「完美完整版本」**not pass-through**:agree → synthesize 補對方缺漏;disagree → cite battle,evidence stronger 勝。**禁**:pass-through codex propose(M28「被牽著走」);commit 無 3-column cite verdict。Hook `check_codex_collab_5step.sh` 機械化攔(P1 soft)。對齊 RFC 學術同儕審查 / Linux kernel-mailinglist cite source / Google ML eng-design-review。 | 2026-05-10 Issue 8 cell border:codex propose「Field edit border 透明」Claude pass-through ship → user「被 codex 牽著走」→ cite battle: `field-controls.spec.md` state machine + `item-anatomy.spec.md` cell 4-edge grid not in Field scope → 落地雙 owner;Issue 11 同 pattern cite battle ship retire + RFC backfill。 |
-<!-- M33 retired 2026-05-22(per /knowledge-prune deep audit Lens 1+2):folded into M20 as sub-rule「Stop hook overfire defer anti-pattern」。Original session context(2026-05-13 claim-verify-gap)+ hook `stop_self_audit.sh` P0 detection retained at M20 entry。Single-bug rule → 與 M20 同類「AI self-correction under feedback signals」合併。 -->
+| **M18** | **Propose-time 6 題自檢 gate**(2026-05-18 升 4→6 加 Q0 + Q5)。列 option / 建議前必 inline 跑 **Q0 Pre-ASK self-verify problem 真存在**(2026-05-18 加,absorbs Sheet/inline-action/SurfaceBody 三題誤判)/ Q1 M8 benchmark / Q1' M23 DS canonical / Q2 M17 SSOT / Q3 Rule-of-3 / Q4 M10 下游吸收 / Q5 Issue 100% mapped。Reject 不列出,通過寫 6-Q 證據表。**Q0 強制動作**:propose 給 user 拍板前必 grep DS-wide + Read 相關 spec.md + Read consumer usage 確認 problem 真存在,沒 grep 就斷言「N 元件缺 X / 該 migrate」= 撤回 propose。SSOT → `packages/design-system/ds-canonical/skills/propose-options/SKILL.md`。Hook `check_propose_pre_grep_verify.sh` 機械化警告 Q0(P1 soft,scope 僅 planning/reports/handoff md 的 cite-presence;chat reply propose 靠 discipline)。 | 2026-05-18 Sheet / inline-action / SurfaceBody 三題全錯誤 propose,grep 後 0 個真 gap(詳 historical-bugs.md,含 user verbatim) |
+| **M19** | **Trigger phrase auto-pipeline**。「確保 / 一定 / 永不漂移 / ensure / always」trigger → 自動 5-layer ≥ 3 層落地 + M8 + M17 + M10。Substantive 依 `AGENTS.md # 自主執行 canonical` 分權：只有產品／UI／UX SSOT 真取捨 STOP；純工程／治理 canonical 自主落地。SSOT → `packages/design-system/ds-canonical/skills/ensure-canonical/SKILL.md`。 | story splitting 2026-04-26 user 第 N 次強調才落地 |
+| **M20** | **AI 自問 best-practice + 自動 self-improve**(不靠 user 提醒)。Stop hook `rule_infra_best_practice_score`(R5 in `stop_passive_logging.sh`,2026-05-13 folded from retired `stop_meta_self_audit.sh`)每 turn 跑 score → < 80 / regression ≥ 5 log to `score-history.jsonl`;next-turn UserPromptSubmit `inject_pending_self_audit.sh` 注入 BLOCKER prompt。**Threshold 數值 SSOT**:`session_start_governance_check.sh`(檔頭「Checks + thresholds」註解 + Check 7)+ AGENTS.md `# 治理 canonical` 行數預算表;本 M-rule 不重述具體 cap,避免多 home 漂移(2026-05-22 prune codify per Rule-of-3 violation fix)。**+ Sub-rule M33 (folded 2026-05-22)**:Stop hook overfire → AI conservative-defer 反 pattern。同 stop hook fire ≥ 5 次 within session → AI 自動 hedge / 撤回 claim / 「下個 session」defer **可做工作**。真理由 vs 偽 prereq 區辨 — (a)真 prereq 缺(cross-frame test fixture 等)= 具體 deliverable need;(b)偽 prereq(「context budget」「省工」「下個 session」)= conditioned hedge,user 反覆催 = 真理由不存在。**Rule**:AI reply 含「下個 session」「context budget」「省工」keyword 且前 1 turn user 已拍板「全部做完」/「繼續」/「沒理由不做」→ WARN + next-turn inject(stop_self_audit.sh Mechanism 4)。對齊 Atlassian「stop using vague defer」+ Linux kernel patch review。 | user 10 次問「best-practice 嗎」直到外部 benchmark 確認真 gap;2026-05-13 claim-verify-gap stop hook fire 12+ 次 → 我每 reply 自動 hedge → user 多次糾正「沒理由不做」 |
+| **M21** | **新元件 / 新 sub-component 抽象前必過 prop variant test**。當新元件名 = `<Existing>+suffix`(Time / Range / Color / Light / Dark / Filled / Outline / Compact / Rich)→ 強烈 signal 應為 prop variant on `<Existing>`。3-test 通過才能分(全失敗 → prop):(1) `<Existing>` 加 prop 無法達成同 DOM/behavior?(2) ≥3 家 world-class DS 用分離元件而非 prop(必 cite source)?(3) value 結構或 contract 真的不同(如 Range = [start, end])?Hook:folded 入 `check_naming_and_abstraction.sh` D.1(P0 BLOCK,2026-05-08 cluster D consolidation;escape @separate-component-rationale)。 | DateTimePicker 從 DatePicker 拆 → 撤回合併 `<DatePicker showTime>`(2026-05-02);DataTableFilterPanel 5-file → 撤回 sub-file pattern |
+| **M22** | **Benchmark claim 必附 inline source citation**(不可憑印象)。寫 spec / tsx 含「Ant / Material / Polaris / Atlassian / Carbon / shadcn / Radix」等 world-class DS claim,必同段附:(a) inline URL(domain 對應 DS 官網 / GitHub source);(b) GitHub source path + line ref `#L42`;(c) screenshot reference `snapshots/...`;(d) 非 component-spec scope 可顯式撤回 `@benchmark-unverified`。**Component specs 是 zero evidence-debt scope**:`components/**/*.spec.md` 禁止 `@benchmark-unverified` / `@benchmark-unverified-blanket` / `@benchmark-citation-allow`;外部 claim 必有直接支持該句的 inline primary-source evidence,否則移除外部比較、改寫為 DS-internal product rationale。Hook `check_benchmark_citation.sh` 機械強制(P0 BLOCKER exit 2)。每次 implement 前跑 WebFetch 取真 source,不憑印象解碼。 | claim「Ant showTime range = 2 calendars」憑印象,實證 source code `multiplePanel = false` = 1 calendar(2026-05-02 鬼話事件)|
+| **M23** | **DS 內既有 canonical 優先於外部 benchmark**。寫 visual decision(color / size / spacing / typography / state)/ prop name namespace 前必先 grep DS 既有 codified token / variant / pattern / prop;命中 → 必對齊;沒命中 → 才引 world-class + 同步補 canonical。**禁止**:外部 benchmark(M22 cite OK)直接覆蓋 DS 內已有 canonical。Mindset #2「優先消費既有」的 visual layer。判斷流程:(a) grep 該屬性 / prop 既有 token/variant/usage;(b) 命中 canonical?有 → 用,沒 → 走 M22 cite 然後 codify;(c) **prop name conflict 子規則**(former M27,2026-05-15 collapsed):外部 framework prop name(TanStack `size` / Radix `disabled` / dnd-kit attrs 等)跟 DS 既有 prop 同字不同義 → wrap-and-rename(DS-internal naming + pre-process map);(d) **nearest same-purpose canonical wins 子規則**(former M35,2026-05-22 folded):寫 stories / UI composition wrap 既有 primitive 前必先 grep + Read primitive 的「完整佈局」production canonical story(eg. `sidebar.stories.tsx#IconCollapse`)抄 archetype 結構 / helper / variant — 不准憑記憶寫 simplified mock。**Cite 存在 ≠ consume 落實**(codex 2026-05-20 verdict)。**(e) 不可重用實例 ≠ 可有不同行為(2026-08-11 加)**:因技術限制(模組層單例 / cookie key 衝突 / 全域快捷鍵已被佔用)而**不能重用某元件的那個實例**時,新的那份**仍須遵守該元件的 spec**(寬度 / 收合 / 鍵盤 / token)。「不重用實例」是實作層事實,**不構成語意層豁免**;要偏離必須另有 spec 依據。判斷式:說得出「它是 Sidebar」就照 `sidebar.spec.md`,不得因為它是第二份就重新發明,更不得把「該元件 spec 早已答完的事」列成待 user 拍板的未定案。最相近同目的 canonical 用法 > 泛用 component spec / 寬鬆 pattern wording。**手刻浮層 / chrome header 子規則(2026-06-04 加)**:做「像 popover / dialog 的浮層面板」前必先 grep + Read `patterns/overlay-surface`(SurfaceHeader/Body/Footer)+ `Popover`(chrome token + PopoverHeader/PopoverTitle)SSOT;**手刻 `<div px-loose border-b border-divider>` header 或 `<div rounded bg-surface shadow-elevation>` 殼 = drift**,必消費 primitive。Registry SSOT `packages/design-system/ds-canonical/references/story-baseline-registry.json` + canonical hook `packages/design-system/ds-canonical/hooks/check_story_invariants.sh` R8 **+ R9 hand_craft_overlay_header(零誤判 px-loose+border-divider 簽名,BLOCKER)**。**forcing-function 教訓**:M1/M23(d) 是 mindset,但 mindset 沒有完整 hook 兜底 = 紙老虎(會憑印象手刻);新場景若既有 hook 無 antiPattern 覆蓋 → 補 hook rule 才算落地。 | 2026-05-03 chevron / 2026-05-06 column width / 2026-05-20 AppShell drift / 2026-06-04 upload-manager 手刻殼(詳 historical-bugs.md)。Hook `check_datatable_invariants.sh`(r2 folded)+ `check_story_invariants.sh` R8/R9 |
+| **M24** | **State 顯著性 precedence:disabled > muted > emphasis**。元件在 disabled state 時,內部所有文字載體(label / value / placeholder / icon)統一切 disabled token(`text-fg-disabled` neutral-6),**不**繼續 muted token(`text-fg-muted` neutral-7)。muted 是裝飾,disabled 是語意 state — state 勝 emphasis。同理:error / warning state 內 placeholder 應對應 state token。Hook `check_field_family_invariants.sh` A.4(原 check_disabled_placeholder_color folded,live P1 stderr)。 | 2026-05-04 5+ violation:`bareInputStyles` 永遠 muted / `select.tsx` 3 處 plain&tag empty 不分 mode / `textarea.tsx` 同;Input.tsx 唯一做對。User 5+ 次糾正才 codify |
+| **M25** | **Layered chain invariant 必整鏈 forward(viewport-aware overlay scroll 範例)**。Overlay surface(Popover / HoverCard / Dialog / Sheet)的 viewport-aware scroll 機制要求 root → SurfaceBody 之間**所有中間 wrapper 都 forward `flex flex-col h-full`**;任何中間 div 沒 forward → SurfaceBody flex-1 失效 → body 不 scroll。同類 chain pattern:density 透傳 / fieldCtx 鏈 / theme subtree(M3 portal 逃逸對偶)。Hook `check_pattern_invariants.sh` C.1(原 check_overlay_panel_scroll_chain folded,live P1 WARN)。 | 2026-05-04:Filter / Sort panel root `<div w-[640px]>` 無 flex-col → user 縮 viewport 時 body 不 scroll。NameCard 因自設 max-h flex-col 才繞過(無中間 wrapper) |
+| **M26** | **Behavior / visual canonical decision 前必跑 WebFetch + WebSearch 取 ≥ 3 source,不可憑印象 propose**。M22 升級版 — M22 管「寫 spec / tsx 含 claim 必附 cite」(實作後),M26 管「propose / 決策前必先 fetch」(實作前)。Pipeline:(1) WebFetch 3 家世界級 source(Atlassian / Material / Polaris / Ant / Carbon / Apple HIG / shadcn / Radix);(2) 全 403 → WebSearch fallback 用 snippet,**明示「search-only confidence」**;(3) WebFetch + WebSearch 都失敗 → STOP propose,告知 user「無法 verify,要看 screenshot/實機」。Hook `check_propose_without_benchmark.sh`(2026-05-26 backfill — 前期 doc claim 但 file missing;UserPromptSubmit 偵測 user prompt 含 propose / visual / behavior decision keyword + 近 20 turn WebFetch/WebSearch < 2 → soft inject 提醒)。 | 2026-05-05:user 反覆糾「為什麼每次都沒 webfetch 只憑印象」— Jira drag handle / cell display 兩題我憑印象 propose 多輪;升級成硬規範 |
+| **M28** | **Git ops 必先 grep canonical**(mindset #2 AI-ops 子規則)。AI 執行 branch/PR/merge/release ops 前必讀 `governance/memory/feedback_solo_dev_workflow.md` + `AGENTS.md # Git / release canonical`。鐵律:1 task = 1 working branch + 1 PR；protected main 禁 direct push；PR 建立是正常路徑；standard release 只走 `infra/governance/release-workflow.json` 的 `pr-checks → merge → publish → readback → consumer`，由 `release:auto` 依 Standing Authorization自主續跑。Hook `check_solo_workflow.sh` 只機械攔 R1 第二 branch / R2 direct-main push；retired tag-preflight、preview/canary、attestation、soak、fleet ceremony 不得回到 blocking graph。Break-glass override audit-logged，仍不能繞 GitHub ruleset。 | 2026-05-08 的 branch/PR sprawl促成機械化；2026-07-20 保留一任務一分支與 protected PR；2026-07-26 淘汰 chat-keyword gate，2026-08-02 再移除 retired local tag-preflight branch。 |
+| **M29** | **DS Anchor Preflight invariant — 視覺 / 結構 propose 前必 grep `*.spec.md` 找 owner SSOT**。動 component / pattern / token 視覺結構前,**必先**:(a) `rg <touched component> + <behavior keyword>` in `packages/design-system/src/**/*.spec.md` (b) 出 **3-column owner table**(`candidate owner spec` / `canonical sentence/table row` / `conflicting code/comment if any`)(c) 若 spec ≠ code → STOP 寫 RFC 不直接 propose implementation。沒 3-column = anti-pattern,提案不被接受。SSOT index `packages/design-system/ds-canonical/references/ssot-index.md`(high-risk interface owner mapping)Step 0.1 先查再 grep verify。Hook `check_ds_anchor_preflight.sh` P0 BLOCKER(exit 2,2026-07-07 升級;bypass CLAUDE_BYPASS_DS_ANCHOR=1 audit-logged)。codex-collab/SKILL.md Step 0.1 mandatory pre-grep。對齊 Carbon「design spec is source of truth」+ Atlassian「system-wide coordination first」。 | 2026-05-08:Claude+Codex 連 5 round 跳過 spec anchor pre-grep,直覺加 primitive(D path / Path A);user 抓「為何沒研讀設計原則」 |
+| **M30** | **Wrapper-vs-primitive schema unify invariant — wrapper API option / config schema 必 `extends` primitive SSOT,且 wrapper 內部轉換 mapping 必 forward 全 primitive surface field**。Primitive(`SelectMenuOption` / `MenuItemProps` / `ItemAnatomyProps` 等)宣告 SSOT 後,所有 wrapper(`Select.SelectOption` / `Combobox.SelectOption` / `PeoplePicker` 等)若有同類 schema,(a) 用 TypeScript `extends primitive` 機械繼承,**不可平行 declare** weak schema(同名 / 部分欄位)(b) wrapper 內部 `xxxToYyy()` mapping 必 forward 全 primitive surface field(不可只 forward `value` + `label`,silently drop avatar / description / disabled 等)(c) wrapper-only field 加在 `extends body`(不污染 primitive)。Hook `check_wrapper_primitive_schema_drift.sh` 機械強制(P0 BLOCKER):grep `export interface .*Option \{` cross components/,同名 ≥ 2 處且未 `extends` primitive → BLOCK。對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown wrapper-vs-primitive schema-extension idiom。 | 2026-05-10 PeoplePicker weak schema 漏 avatar,mapping 只 forward 2 fields(詳 historical-bugs.md) |
+| **M32** | **Audit script 必 pixel-quantified verify ≠ attribute existence**(2026-05-12)。Audit 必驗 `rect.top / .left / .height` numeric pixel,**不**可只驗 `getAttribute('data-state')` / `class.includes(...)` = false-positive trap(DOM-pass ≠ visual-pass)。對齊 Material X-DataGrid / AG Grid playwright pixel snapshot / Polaris visual diff canonical。Hook `check_pixel_quantified_audit.sh` 機械強制(scans `getAttribute(` without paired `getBoundingClientRect(`)。**+ Sub-invariant(2026-05-30,doc-claim layer)**:story/anatomy/a11y/spec 的**文字宣稱 ≠ code 真實**——audit 必 adversarial **讀元件 .tsx +(其 wrap 的 Radix/cmdk/react-day-picker 等 lib)source**,逐句驗 keyboard map/ARIA role/focus 行為/prop 存在性/native-vs-custom;prose-skim「looks fine」= false-pass(prose-pass ≠ source-verified)。**「無 code 改動」≠ 可跳過**。`/deep-audit-cross-codex` A.1b + CP-A1b + report-validator F 機械強制。Anchor:2026-05-30 獨立 adversarial 抓 403 findings/64 單元/202 FALSE_CLAIM(前期 prose-skim story dim 全漏);prop-existence deterministic detector 因 passthrough over-flag 證實此類本質需 LLM 讀 source → 用 mandatory-dim + report-validator 保證真跑。**Split note**:原 mega 8 sub-invariants 拆 4 home — (b) fix-time root-invariant → M12 extension / (c)(d)(h) batch + parallel + claim-verify → `/bug-fix-rhythm` skill / (e) tool preflight(CLI binary 必跑 4-test discovery:which / npx / package.json / auth.json,禁短路「not installed」假警報)— 原 memory `feedback_tool_binary_preflight_sweep.md` 已 retire,invariant 一行收容於此 / (f) ship gate → AGENTS.md `# 稽核 canonical` / (g) Layer marker → M31 + hook。git blame 2026-05-12 commit 留 audit trail。 | 2026-05-12 4 audit-vs-visual gap absorbed:cell-align / divider 2px / breadcrumb tooltip / row-alignment 全 audit「Δ=0 ALL PASS」但 user 抓視覺壞(詳 historical-bugs.md)。|
+| **M31** | **Provider-adaptive adversarial two-track 5-step canonical**。**Activation boundary**:只有 task／deliverable 明確要求 independent review 時才啟動；exact run waiver 必記 receipt，optional review 缺席不得阻擋一般工程、deep audit 或 standard release。執行 authority = `packages/design-system/ds-canonical/skills/independent-review/SKILL.md` / `deep-audit-cross-codex/SKILL.md` + `packages/governance/canonical/providers.json` + `packages/governance/src/provider-review-binding.mjs#resolveProviderReviewBinding`；skill 舊名稱只保留 discovery compatibility，不指定 reviewer。**Step 0 入口 gate**:啟動後 primary author 先完成獨立 Phase A，再由 resolver 選出不同 provider、不同 context、read-only、已認證的 peer；無可用 peer/transport/certification/evidence = required-review claim `REVIEW-BLOCKED`，禁止同模型或同 context 假扮 second opinion。**Step 1-5**(啟動後每題必過):(1)兩方各自在隔離 context 熟讀相同完整 inventory/spec/canonical/source，NO-SAMPLE；(2)兩方各自驗證 deterministic gates + applicable runtime/visual evidence，不可只一方 verify；(3)需要視覺判斷時兩方各自執行 target-bound browser/DOM/pixel 稽核；(4)每個 finding 都附 owner path/精確證據/reasoning，未證實即撤回；(5)closed synthesis 比較兩份 content-addressed artifact，agree 時補齊缺漏，disagree 時以 canonical evidence 較強者勝，保留 unresolved，不得 pass-through。legacy-named compatibility hook `check_codex_collab_5step.sh` 只檢查流程證據，不是 provider 或 transport authority。對齊 RFC 學術同儕審查 / Linux kernel-mailinglist cite source / Google ML eng-design-review。 | 2026-05-10 的 pass-through 事故證明「拿 peer 結論代替 primary 驗證」會造成 drift；後續 cite battle 以 `field-controls.spec.md` + `item-anatomy.spec.md` 找回雙 owner，現已抽象成 provider-neutral second-opinion invariant。 |
+| **M36** | **禁把自己的推論寫成 user 的決定;禁用自家治理設定把自己鎖死**(2026-08-08 user directive)。**(a) Provenance 不得升格**:任何文件/回覆標「user 拍板」「你最早的決定」「已拍板」,**必須當場引得出 user 的原話**;引不出來一律標「AI 推導」或「AI 建議、user 採納」。**引文一律逐字,禁刪語氣詞**——把「…才對吧?」寫成「…才對」= 竄改證據,比誤判嚴重(2026-08-09 錨例);user 說「還在思考」之後仍當已決,同罪。**問句 ≠ 同意**——user 問「這是 X 的情況?」是要澄清,不是核准。**推論 ≠ 既有**——把某個既有值(如 Dialog 的 maxWidth 檔位)當成保證,再據以生出新規則,是同一類病。發現升格 → 立即撤回並留檔於該文件的「來源總帳」。**(b) 禁自鎖(anti-self-lock)**:遇到「被我們自己的 policy/schema/sandbox 設定擋住授權內動作」時,**先解自己的鎖**(改 canonical owner → 走正常 PR),或改用不需放寬安全邊界的既有機制;**禁止**因自家設定擋路就把動作丟回 user、或宣稱做不到。真正的 human-only boundary 只有 login/MFA/OAuth、缺 credential reference、plan 外付費、法律/帳號權限——**自家治理設定不在此列**。**(b') 判自鎖的機械三問(2026-08-11 codify,任何模型任何環境)**:宣稱「被擋、需要 user」前必逐題答:(1)**憑證真的缺嗎?**——canonical credential reference(`~/.config/qijenchen-governance/github-token`)存在且可用 ≠ 缺憑證;工具讀錯存放處(gh 存的 OAuth 過期但 token 檔可用)= 工程 bug 自修,禁報 login 邊界。(2)**體檢測的是真實需要的能力嗎?**——帳號級 preflight(`gh auth status`)擋 repo-scoped token = 體檢錯位,改 target-bound 驗證(能讀目標 repo 即可)。(3)**這條傳輸不通,有沒有已驗證可通的等價傳輸?**——gh 的 Go TLS 不信 sandbox 代理憑證但 curl 可通 → 換傳輸(shim),不是邊界。(4)**鎖的主人是誰?(2026-08-28 加)**——自家 policy/schema/settings 有列 → 解自己的鎖走正常 PR;**自家清單沒列卻仍 EPERM = 平台內建安全邊界**(如 Claude Code 對 hook 設定目錄的防注入保護、沙箱不可關),不試圖解鎖,改找**不碰被鎖路徑**的等價機制(git plumbing 只寫 `.git` 可寫區、harness 檔案工具、index-authoritative generator);**任何要交 user 執行的指令,必先驗證它不在同一道牆內**——對話內 `!` 與 Bash 同沙箱,指同牆死路 = 把動作丟回 user 的變形,同罪。**復原/交易類機制必有顯式逃生口 + skip-identical**(未變目標不准碰;全有全無原子性造成的死鎖 = 過度設計,2026-08-11 拆除)。 | 2026-08-08 4 次 provenance 升格 + policy 自鎖;2026-08-11 一日連環五鎖全是自家機制,逐層拆除後 release 全自動走通;2026-08-28 平台鎖誤判自家鎖 + 指 `!` 同沙箱死路給 user,正解 skip-worktree 一行(詳 historical-bugs.md,含 user 原話) |
+<!-- M27 retired 2026-05-15(per /knowledge-prune D3 audit):self-flagged「M23 子規則」 → collapsed into M23 sub-bullet (c) "framework prop name namespace conflict"。Original case (TanStack size vs DS density) + hook `check_datatable_invariants.sh(r2 folded,2026-06-11)` retained 在 M23 children。 -->
+<!-- M33 retired 2026-05-22(per /knowledge-prune deep audit Lens 1+2):folded into M20 as sub-rule「Stop hook overfire defer anti-pattern」。Original session context(2026-05-13 claim-verify-gap)+ hook `stop_self_audit.sh` P1 warn detection(Mechanism 4 + 次 turn auto-inject)retained at M20 entry。Single-bug rule → 與 M20 同類「AI self-correction under feedback signals」合併。 -->
 
 <!-- M34 retired 2026-05-22(per /knowledge-prune deep audit Lens 1+2):folded into M7 as sub-rule「Hook detection regex 必對齊 spec wording 廣度」。Original Triple test + 錨例(story-rules.md name field detection)retained at M7 entry。Single-bug rule + same-class「rule-authoring hygiene」與 M7 合併。 -->
 
@@ -84,4 +84,4 @@
 
 ## 與失敗記憶索引的關係
 
-Meta-principle 是**上游**(預防);具體 bug 歷史詳解移到 `.claude/skills/design-system-audit/references/historical-bugs.md`。CLAUDE.md 只留 meta-principle one-liner anchor + pointer。
+Meta-principle 是**上游**(預防);具體 bug 歷史詳解移到 `packages/design-system/ds-canonical/skills/design-system-audit/references/historical-bugs.md`。Provider bootstrap 只留 meta-principle one-liner anchor + canonical pointer。