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

package/ds-canonical/skills/codify-principle/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: codify-principle
+description: User 提出新設計原則 → auto 5-layer artifact generation pipeline。將原則文字自動轉化為 SSOT canonical text + hook scaffold + audit dim + scaffold update + memory entry,放入正確 home。對齊 M14 + M19 + 8-home 治理 canonical。Invoke when user says「我想加一條設計原則 X」「新原則 Y」「ensure X always」OR auto-recognize trigger phrase。本 skill 把 reactive markdown rule 升級成 proactive principle-to-artifact generator。
+---
+
+# Codify Principle Skill — 原則 → 5-layer artifacts auto-generator
+
+User mandate「我說一條原則 → 自動轉化產生正確 artifacts 放正確位置」(2026-04-26)。本 skill 是 M19 ensure-canonical pipeline 的 generator 上層,接受 principle text 為 input,output 5-layer 完整落地。
+
+## When to invoke
+
+- User 明說「我想加一條設計原則 X」「新原則 Y」
+- User 描述新規則 + 期望「永遠遵守」/「不可漂移」
+- M19 trigger phrase(確保 / 一定 / 永遠不漂移)+ 涉及新原則內容
+- Auto-chained from `/ensure-canonical` 當 trigger 是「新原則」非「既有原則 enforce」
+
+## Non-goals
+
+- 不直接動既有 canonical without sign-off(改 substantive meaning 走 STOP)
+- 不跳過 M8 benchmark — 任何新 cross-component 原則必 ≥ 3 家世界級對照
+- 不省略 user sign-off checkpoint
+- 不替換 user 判斷 — 模糊原則需要 user 親自釐清
+
+## Workflow(7 phases)
+
+### Phase 1 — Parse principle text(Auto)
+
+User 提供 principle text。Skill 提取:
+- **Scope**:跨元件 / 單元件 / 跨 layer / governance-only
+- **Type**:Absolute(機械可驗)/ Consistency(對照可驗)/ Judgement(無 mechanical)
+- **Affected homes**(8-home matching):
+  - `CLAUDE.md` 章節?
+  - `*.spec.md` 哪個元件?
+  - 新 hook?
+  - 新 audit dim?
+  - 新 skill?
+  - Memory entry?
+
+### Phase 2 — M8 benchmark(STOP if missing)
+
+對 cross-component 原則(scope ≠ governance-only),**強制** M8 ≥ 3 家世界級 DS 對照:
+1. 跑 web research(WebFetch Polaris / Material / Carbon / Atlassian / Ant 等對應 component / pattern)
+2. 列對照表:每家做法 + 我們對齊 / 偏離 + 偏離 rationale
+3. **STOP** 若 < 3 家對照 → 跟 user 確認原則是否成熟
+
+### Phase 3 — Draft 5 layer artifacts(STOP per layer)
+
+每 layer 產 draft + Checkpoint sign-off:
+
+| Layer | Action |
+|-------|--------|
+| 1. SSOT canonical | 寫 markdown text 到對應 home(CLAUDE.md 章節 / spec.md 段 / references/{topic}.md);包含 rule + Why + How to apply + 世界級 anchor |
+| 2. Spec frontmatter | 若 trait-like → 加入 `traits:` array OR 新增 frontmatter field |
+| 3. Hook | 若 Absolute → scaffold `.claude/hooks/check_{topic}.sh` 含 P0/P1 detection logic + 7-Q self-check 模板 |
+| 4. Audit dim | 加 dim N 到 `/design-system-audit` SKILL + audit-prompts.md(periodic verify) |
+| 5. Memory | 寫 `~/.../memory/project_{topic}_{date}.md` + add MEMORY.md index entry |
+
+**每 layer 都 Checkpoint user sign-off**:
+```
+Phase 3 Layer N draft ready:
+{draft content}
+Approve? Edit? Skip?
+```
+
+### Phase 4 — Auto-generate scaffold update
+
+若原則是「新元件 / 新 story 該滿足」 → 更新 `/new-component` Phase 5 scaffold + `/story-writing` Phase 0。
+
+### Phase 5 — Auto-generate hook test
+
+若 Layer 3 hook 建立 → scaffold `.claude/hooks/tests/test_{topic}.sh` 含 ≥ 5 smoke tests(silent skip / canonical compliance / drift block / rationale escape / per-trait verify)。
+
+### Phase 6 — Apply + verify(分組 commit)
+
+Per layer 一個 commit:
+1. SSOT commit
+2. Hook + test commit
+3. Audit dim commit
+4. Scaffold update commit
+5. Memory + final verify commit
+
+每 commit 後跑:
+- `npx tsc -b`
+- 新 hook test
+- `node scripts/audit-content-quality.mjs --check`(防 content drift)
+
+### Phase 7 — Self-improvement capture
+
+```markdown
+## Self-improvement capture
+- 新原則 SSOT home: {path}
+- 新 hook: {filename} / fires on: {pattern}
+- 新 audit dim: N
+- 5-layer 落地完整度: {% layers actually shipped}
+- 跳過的 layer + rationale: {if any}
+```
+
+更新 `.claude/logs/codified-principles.jsonl` log:
+```json
+{"date":"2026-04-26", "principle":"...", "scope":"...", "layers":["ssot","hook","audit","scaffold","memory"], "commits":[...]}
+```
+
+## Checkpoints(禁止跳)
+
+### ⚠️ Checkpoint 1 — Phase 1 parse
+User 親自確認 scope / type / affected homes 是否正確,禁 AI 單方面決定。
+
+### ⚠️ Checkpoint 2 — Phase 2 benchmark
+< 3 家世界級對照 → STOP,跟 user 確認是否走 OG-only(原創原則,需 rationale 文檔)。
+
+### ⚠️ Checkpoint 3 — Phase 3 per-layer
+每 layer draft 都過 user。SSOT 是 canonical 改變,動 substantive meaning → 必 sign-off。
+
+### ⚠️ Checkpoint 4 — Phase 6 verify
+任何 layer commit 後 tsc / hook test fail → 回該 phase 修,**不繞過**。
+
+## 與既有 skills 分工
+
+| Skill | Scope |
+|-------|-------|
+| `/ensure-canonical` | 既有原則 enforcement(hook / audit 補強)|
+| `/codify-principle`(本)| **新原則** 從 0 生成 5-layer artifacts |
+| `/knowledge-prune` | 反向:既有原則太多時 retire |
+| `/design-system-audit` | periodic verify 既有 artifacts compliance |
+
+`/codify-principle` 是新原則 entry point;落地後其他 skill 接管 enforcement / verify / retire。
+
+## References
+
+- `~/.../memory/MEMORY.md` — index of codified principles
+- `.claude/logs/codified-principles.jsonl` — execution log
+- CLAUDE.md `# 資訊治理 canonical` 8-home — home 識別 rules
+- CLAUDE.md `# Meta-Pattern 預警` M14 / M19 — 上游 pipeline rules
+
+## 範例呼叫
+
+User 說:「我要加一條原則:所有 form-like 元件必須支援 controlled + uncontrolled dual-mode」
+
+Skill 自動:
+1. Parse:scope=cross-component,type=Absolute(可機械驗 prop pair)
+2. M8:Polaris/Material/Atlassian React form lib 都支援 dual-mode ✓ (3/3 ≥3)
+3. Draft layer:
+   - SSOT:`.claude/rules/ui-development.md`「元件 Props 命名」 + form spec
+   - Hook:`.claude/hooks/check_form_dual_mode.sh` 偵測 missing pair
+   - Audit dim:Dim 31「Dual-mode coherence」(已存在 Dim 26 — STOP 提議擴充而非新增)
+   - Scaffold:`/new-component` Phase 4 加 dual-mode template
+   - Memory:`project_form_dual_mode_2026_04_26.md`
+4. Per-layer Checkpoint
+5. Hook test + audit prompt
+6. Apply + tsc + verify
+7. Capture

package/ds-canonical/skills/component-quality-gate/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: component-quality-gate
+description: Pre-merge quality gate for new or significantly refactored design-system components. Walks through Spec / Code / Stories / Ship checklist (45+ items) to ensure world-class discipline before a component enters `packages/design-system/src/components/`. Invoke when user says「元件做完了」「這元件可以收工了嗎」「元件 ready 嗎」「check 這個 element」「要 merge 進 DS 了」or before closing a component PR.
+---
+
+# Component Quality Gate
+
+Purpose: 元件進 `packages/design-system/src/components/` 前的最終 checklist。防止「code 寫完但 spec / stories / token 消費紀律有漂移」的半成品進入系統。
+
+## When to run
+
+- 新元件即將合入 design-system
+- 既有元件大改(variant / size / token 結構重構)
+- Code review 前的自審
+- `/design-system-audit` 發現某元件偏離 checklist 後的修復驗證
+
+**不 invoke 的情境**:小改(typo / 單 bug fix),走 spec 本身的 sync hook 即可。
+
+## Preconditions
+
+- 元件 folder 存在於 `packages/design-system/src/components/{Name}/`
+- 該元件的 `.spec.md` / `.tsx` / `.stories.tsx` / `.anatomy.stories.tsx` / `.principles.stories.tsx` 已完成初稿
+- 已讀相關 path-scoped rules(`.claude/rules/spec-rules.md` / `.claude/rules/ui-development.md`(含 Tailwind / Token 命名 / Props 命名 / shadcn 元件規範) / `.claude/rules/story-rules.md`)
+
+## Workflow
+
+### Phase 1 — Spec 審查(先於 code,spec 是 judgment home)
+
+逐條走 `references/checklist.md` 的 **Spec section**(12 項):定位明確 / 實作基礎宣告 / 每個 prop/variant 有何時用何時不用 / 互斥規則 / 為什麼不只是什麼 / 術語一致 / 無視覺描述 / 禁止事項列出 / 邊界案例覆蓋 / 近親 SSOT pointer / 對標世界級 7 維度。
+
+任一不過 → 停下補 spec。**不往下跑 Phase 2**。
+
+### Phase 2 — Code 審查
+
+走 **Code section**(13 項):shadcn 基底完整 / cva() 不條件字串 / data-* selector / 無硬寫 token / Tailwind v4 var() 正確 / 無自包 Provider / Props 命名按「是什麼」/ ARIA 齊 / defaultVariants size=md 若屬 field-height family。
+
+cva `defaultVariants` 異動 → 強制 grep 該元件所有檔案確認三方同步(見 `.claude/skills/story-writing/references/anatomy-standard.md` → 高風險漂移點)。
+
+### Phase 3 — Stories 審查
+
+走 **Stories section**(6 項):展示 / 設計規格 5-story 齊全 / TOKEN_MAP 對得上 cva / Rule note 傳達原則 / title 命名對齊 / Internal vs Components 判斷正確。
+
+範例品質問題 → invoke `/story-writing` skill 做深度審。
+
+### Phase 4 — Ship 審查(最後驗證)
+
+走 **Ship section**(6 項):
+1. `npm run storybook` 本地渲染正常
+2. `npx tsc -b` 無錯(**禁用 `--noEmit`**,root tsconfig `files: []` silent pass)
+3. import 路徑 `@/design-system/...`
+4. 分類標註(Internal vs public)正確
+5. **Visual audit 過關**(2026-04-21,stakeholder-gate 強制)
+6. **Story canonical-drift 過關**(2026-04-24,Phase 4 story auto-compile)— 若元件已 migration(有 `componentMeta` export + spec frontmatter)→ 跑 `node scripts/compile-stories.mjs {Name} --check` 必 exit 0;migration 未做 → skip 此項(另 new-component skill 推動逐步 migration)
+7. **Code quality 過關**(2026-04-24,Dim 27)— 跑 `node scripts/code-quality-audit.mjs --scope=component:{Name} --check` 必 exit 0(無 P0 clean-code violation)。P1 flag 但不 block;P0(`any` 無 escape / file-size > 800 / circular dep)必修才 ship
+
+### Phase 4.5 — 進階稽核 6 維(強制 chain,對齊 CLAUDE.md `# 稽核 canonical` M6)
+
+**這是 stakeholder-gate,不能跳**。元件 merge = stakeholder-visible 產出,**必過進階模式 6 維**(非高效)。
+
+| 維度 | 做法 | Chain 的 skill / tool |
+|------|------|--------------------|
+| D1 設計語言一致 | Phase 1-3 已覆蓋 | — |
+| D2 程式語言一致 | Phase 2 + tsc + lint | — |
+| **D3 元件效能** | 檢查 render / memo / bundle | chain `/performance-audit` |
+| **D4 UX 行為** | keyboard / focus / ARIA / animation / interaction canonical | chain `/ux-audit` |
+| **D5 視覺品質** | Layer A mechanical + Layer B AI judgement | Auto `npm run visual-audit -- --scope=component:{Name}` + chain `/visual-audit` |
+| D6 設計原則自檢(4 子維)| chain `principle-audit-protocol.md` 對該元件 scope scan | 合理 / 一致 / 無矛盾 / 完整;auto vs STOP 依判斷公式 |
+
+**執行步驟**:
+
+1. `npm run visual-audit -- --scope=component:{Name}`(D5 Layer A:WCAG / 幾何 assertion / retina screenshot)
+2. Layer A exit code != 0 → 停下修到 0
+3. Chain `/visual-audit`(D5 Layer B):讀 `snapshots/{Name}-*.png` 做 AI judgement
+4. Chain `/performance-audit --scope=component:{Name}`(D3)
+5. Chain `/ux-audit --scope=component:{Name}`(D4)
+6. **D6 真 scan**:讀 `.claude/skills/design-system-audit/references/principle-audit-protocol.md` 對該元件 + 其 spec 跨指的 kin specs 跑 4 子維(合理 / 一致 / 無矛盾 / 完整);先讀「常見 FP 記憶」節避免誤報
+7. 彙整 6 維 findings:**依 protocol 判斷公式 — 動 canonical substantive → STOP;對齊 canonical → AUTO**
+8. **Self-improvement capture**(強制):Phase 結束寫「新 FP / 新 pattern / user 糾正」—見 CLAUDE.md `# 資訊治理 canonical` → Audit skill Phase F 節
+
+**為什麼 mandatory**:code / spec 對不夠;效能 / UX / 視覺三維各有歷史 bug(DatePicker 四邊不對稱、DropdownMenu 鍵盤不通、Badge 位置離譜、Rating 邊框、Carousel 箭頭壓文字、inline 物件 prop 造成 render 爆)。merge 前沒過 6 維 = 把 bug 帶進 DS。
+
+**合理跳過情境**(極少):純 spec.md 文字修正(無 tsx 改動)→ 視覺 / 效能 / UX 無變,可跳 Phase 4.5;但 tsx / token / cva / style 任一動 → 必跑全 6 維。
+
+### Phase 5 — 簽結(Checkpoint — STOP 點)
+
+全部打勾後,回報 user:
+- 「元件 {Name} 已過 quality gate,46 項全綠(含 Layer A visual)+ Layer B AI 視覺判斷通過」
+- 列出 Phase 1-4.5 各 section 打勾結果
+- 列出 `snapshots/report.json` 摘要(contrast / geometry violation 數 = 0)
+- 若任一 phase 有合理例外(documented 在 spec),列出例外清單
+
+**STOP 條件**:任一項不過 + 原因不清楚 → 停下問 user,不默默放行。**Phase 4.5 Layer A 有 violation 絕不放行**。
+
+## References
+
+- `references/checklist.md` — 完整 45 項 checklist(Spec 12 / Code 13 / Stories 6 / Ship 4 + 各項的 CLAUDE.md pointer)
+
+## 相關
+
+- `.claude/skills/design-system-audit/` — 本 skill focus 在單元件進 DS 的 gate;design-system-audit 是系統級 20 維 sweep,兩者互補
+- `.claude/skills/story-writing/` — Phase 3 story 深審可 chain 進去
+- `.claude/hooks/pre_edit_spec_check.sh` — 編輯 tsx 前提醒讀 spec(session 級)

package/ds-canonical/skills/component-quality-gate/references/checklist.md

@@ -0,0 +1,79 @@
+# 元件完成 Checklist(完整 45 項)
+
+每個元件在進入 design-system 前必須逐項對照。這是品質閘門,不可跳過。
+
+**本 checklist 是純勾選表**——規則定義在各自的 canonical home,此處只做 checkbox + pointer。勾每項前先讀該 pointer 指向的章節。
+
+---
+
+## Phase 1 — Spec(`{name}.spec.md`)
+> 規則定義:`.claude/rules/spec-rules.md`
+
+- [ ] 元件定位一句話(是什麼 / 不是什麼)
+- [ ] 定位段落宣告實作基礎(基於 Radix X / cmdk / sonner / native / 自建 + 理由)
+- [ ] 每個 prop / variant / size / state 都有「何時用 / 何時不用」+ 理由
+- [ ] 互斥規則列出(哪些 props 不能並用)
+- [ ] 每個規則有「為什麼」(寫 rationale,不只結論)
+- [ ] 術語一致(同一概念不用兩種名稱)
+- [ ] 無視覺描述污染(「窄長形」「會變寬」等屬 story 不屬 spec)
+- [ ] 禁止事項(❌)列出常見誤用
+- [ ] 邊界案例覆蓋(disabled / loading / empty / dark mode / density / icon-only 適用時)
+- [ ] 「相關」section 指向近親元件 + SSOT pointer(reciprocal 成立)
+- [ ] 對標世界級 DS 的 7 個維度(何時用 / 分界 / 常見誤解 / 相關 / 空值 / 驗證時機 / a11y)
+- [ ] Layout Family 宣告(第一段必含——1/2/3/4 或「非 family,自己的結構」)
+
+---
+
+## Phase 2 — Code(`{name}.tsx`)
+> 規則定義:`.claude/rules/ui-development.md`(含「shadcn 元件規範」/「Tailwind 5 條核心」/「Token 命名 4 條硬規則」/「元件 Props 命名」)
+
+- [ ] 以 shadcn 為基底,forwardRef / displayName / asChild / ...props spread 齊全
+- [ ] variants 用 cva(),不條件拼字串(或 documented 例外:style-prop variant → object map / 結構性 variant → if-branches)
+- [ ] 同時 export 元件本體 + cva(供外部組合)
+- [ ] 保留 Radix `data-state` / `data-disabled` / `data-orientation` 等 attribute
+- [ ] 樣式優先用 `data-*` selector,而非自訂 class 模擬狀態
+- [ ] 無硬寫顏色 / 字體 / padding / radius / 高度——全用 design token
+- [ ] `cn()` 合併 class;Tailwind v4 CSS var 必用 `var(...)` 包覆
+- [ ] 未包 Provider(Tooltip / Theme / Toast 等由應用層設定)
+- [ ] Props 命名按「是什麼」而非「在哪裡」(icon / avatar / onDismiss,不 prefix / suffix)
+- [ ] 互動元素有 ARIA 屬性;icon-only 有 `aria-label`
+- [ ] 若屬 field-height family,`defaultVariants.size = 'md'`
+- [ ] 若修改 cva `defaultVariants`,已同步 spec / docblock / anatomy 三方(見 `.claude/skills/story-writing/references/anatomy-standard.md` → 高風險漂移點)
+- [ ] 未使用 shadcn compat alias(`bg-popover` / `text-muted-foreground` / `bg-accent` 等),改用我們的 direct token
+
+---
+
+## Phase 3 — Stories(展示 / 設計規格 / 設計原則)
+> 規則定義:`.claude/skills/story-writing/`(完整 workflow) + `.claude/rules/story-rules.md`(high-level)
+
+- [ ] 範例選擇原則的自我檢查清單全部打勾(詳見 `.claude/skills/story-writing/references/self-check.md`)
+- [ ] 設計規格 5 個 story 齊全(總覽 / 檢閱器 / 色彩對照 / 尺寸對照 / 狀態行為)
+- [ ] TOKEN_MAP / SIZE_SPECS 資料與 cva() 定義完全一致
+- [ ] Rule note 傳達原則(「為什麼」),不只結論(「是什麼」)
+- [ ] Storybook title 對齊命名規則;元件放對 `Components/` vs `Internal/`(見 `.claude/rules/story-rules.md` → 「Internal vs Components 三 test」)
+- [ ] 每個重要規則有正確範例;常見誤用有錯誤範例(對比呈現)
+
+---
+
+## Phase 4 — Ship(上線前)
+
+- [ ] `npm run storybook` 本地確認所有 stories 正常渲染
+- [ ] `npx tsc --noEmit` 無錯誤
+- [ ] Import 路徑正確(`@/design-system/...`)
+- [ ] 若為 internal primitive 或 shadcn passthrough,分類標註正確
+
+---
+
+## 簽結報告格式
+
+```
+元件 {Name} Quality Gate 結果:
+- Phase 1 Spec: 12/12 ✓
+- Phase 2 Code: 13/13 ✓  (cva defaultVariants = 'sm',已同步 spec+docblock+anatomy)
+- Phase 3 Stories: 6/6 ✓
+- Phase 4 Ship: 4/4 ✓
+Total: 35/35 ✓
+
+Documented 例外:
+- (無 / 或列出元件 spec 明文允許的偏離 + 理由)
+```

package/ds-canonical/skills/deep-audit-cross-codex/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: deep-audit-cross-codex
+description: Phase A Claude solo 完整深度進階稽核 → Phase B codex 同流程稽核 + 比稿辯論共識 → Phase C 落地。SSOT-UI/UX 中文人話 propose / 其他 autonomous。對齊 M14/M18/M19/M20/M22/M23/M26/M29/M31/M32 + audit dim list 全集(SSOT = design-system-audit/SKILL.md)+ codex-collab 5-step。
+arguments: scope?=full|changed focus?=「ssot|visual|behavior|all」
+---
+
+# Deep Audit Cross-Codex — 雙 model adversarial 完整 DS 稽核
+
+> **SSOT integrity invariant**(2026-05-18 user-mandated):本 skill 的 audit dim list **完全 chain `/design-system-audit --deep` SSOT**(`.claude/skills/design-system-audit/SKILL.md` `## The N audit dimensions` 段)。
+>
+> **禁** hardcode dim count(`46 dim` / `53 dim` 等具體數字)— 用「全 dim」/「Group A-P」/「per design-system-audit SSOT」表達。新增 / 刪除 / 修改稽核項目 → **只動 design-system-audit/SKILL.md**,本 skill 自動繼承。
+>
+> Mechanical 強制:hook `check_dim_count_drift.sh` 攔 Edit 寫死數字。
+
+**生態位**:`/design-system-audit --deep` 是 Claude solo 全 dim 稽核 SSOT;本 skill 是**雙 model 完整 sweep**(Claude solo → codex parallel → 比稿辯論共識 → 落地),chain 既有 audit dim 不 fork。對齊 mindset #1「不取巧省工」+ M31 dual-track + 用戶 2026-05-18 directive(verbatim):
+
+> 「完整深度進階稽核整個 design system」+「codex 跑相同的完整深度進階稽核」+「跟 codex 討論辯論出共識」+「SSOT-UI/UX 增刪改需要用中文具體人話言簡意賅地講給我聽讓我判斷決策,其他的決策基本上就是不以省工為前提...自主自動自發地做到完整、完美」
+
+## When to invoke
+
+- User 明確 trigger:「跑深度稽核 + codex 比稿」「完整盤查 with codex」「dual-pass audit」「/deep-audit-cross-codex」
+- 重大 release / SSOT 大改 / 季度健檢
+- 多輪修正後想雙 model verify
+
+**不該 invoke**:single 元件小修(用 `/design-system-audit --scope=component`)/ 已知 surgical bug fix(用 `/bug-fix-rhythm`)/ 日常 dev(`visual-audit --scope=changed`)。
+
+## Non-goals
+
+- 不取代 `/design-system-audit --deep`(本 skill **chain** 它 Phase A.1)
+- 不取代 `/codex-collab`(本 skill **chain** 它 Phase B)
+- 不動 audit 觸發以外的 PR / branch ops(M28 由 user 拍板)
+
+---
+
+## Phase A — Claude solo full audit(必先 NO-SAMPLE 跑完才進 Phase B)
+
+### A.0 — 全盤閱讀 preflight(M29 升級,**禁止憑記憶**)
+
+**強制 read sweep**(不可 sample,不可挑):
+1. `CLAUDE.md` 全文
+2. `.claude/rules/{meta-patterns,spec-rules,ui-development,story-rules,self-verify}.md` 全文
+3. `.claude/references/{ssot-index,ssot-consultation,build-ui-canonicals,naming-conventions}.md`
+4. `packages/design-system/src/**/*.spec.md` 全部(60+ file,通過 Glob 列舉 + Read)
+5. `packages/design-system/src/tokens/**/*.spec.md` + `packages/design-system/src/patterns/**/*.spec.md` 全部
+6. 本 session 對話脈絡 + memory `~/.claude/.../memory/MEMORY.md` index + active project memory files
+
+**完成 gate**:Phase A.0 output = `phaseA-preflight-checklist.md`(session-local,列出讀過的 N file + 任何 spec 漂移嫌疑點)。**禁** skip / sample / 「先看標題判斷」。
+
+### A.1 — 跑全 dim NO-SAMPLE deep audit(chain `/design-system-audit --deep` SSOT)
+
+**Dispatch plan auto-pickup**(2026-05-23 ship per user verbatim「infra 增刪改 audit 自動跟最新」):
+必先跑 `node scripts/dispatch-audit-dims.mjs --summary` 取**動態 dim 列**(non-hardcoded),從 `.claude/logs/audit-dims-dispatch.json` 讀 sub-agent batch 分組。Heavy dims 自動標,新加 dim 自動 included,retire 自動排除。
+
+**禁** hardcode dim range numbers(eg.「Dims 1-15」/「Dims 34-56」)在 sub-agent prompt — 用 dispatch-audit-dims.mjs output 的 `dispatchPlan.suggestedBatches[].dimNumbers` 動態填。
+
+完整跑,**no sample / no escape**(對齊 `feedback_audit_full_sweep_not_sample.md` + `check_audit_sample_escape.sh` BLOCKER)。
+每 dim sub-agent prompt 必含「DS-wide 全盤,禁 sample top N」。
+
+### A.2 — Triage findings → 中文人話 propose SSOT-UI/UX / autonomous non-SSOT
+
+**Scope classifier**(critical,先過):
+- **SSOT-UI/UX substantive 增刪改** = 動 component / token / spec.md 視覺結構 / 跨元件 design language / 新 API contract → **STOP propose**
+- **Non-SSOT**(bug fix / clean / refactor / 命名一致 / test / audit / verify / hook regex 加廣 / pointer 補 / spec typo / 漂移 mechanical 對齊)→ **AUTO 整批做完**
+
+**SSOT-UI/UX propose 必過 4-Q gate**(M18 + M19 ensure-canonical chain):
+- Q1 M22 cite — 3-column owner table(spec path:line / canonical sentence / conflicting code)
+- Q2 M17 SSOT consume — 既有 token / primitive / pattern 列消費清單
+- Q3 Rule-of-3 — 同概念 ≥ 3 處 → 選 SSOT 其他 pointer
+- Q4 M10 下游吸收 — 修上游 ≥ 3 處下游 redundant 可清
+
+**中文人話 propose format**(per `feedback_propose_in_plain_chinese.md` + hook `check_propose_plain_chinese.sh`,必過):
+
+```
+### 決策 N:<一句話標題,zero jargon>
+
+**現況**:<目前 code/spec 行為,人話>
+**影響**:<不改會怎樣 / 改了會怎樣,具體>
+**選項**:
+- A. <做法 1>(後果:...)
+- B. <做法 2>(後果:...)
+- C. <不動>(後果:...)
+**我推**:<A / B / C> 因 <理由>
+```
+
+禁:術語(L1-L7 / canonical / primitive / SSOT 在 propose 內裸用,該翻成「主檔/共用零件/設計原則」等人話)。
+
+### A.3 — Autonomous batch execute(non-SSOT,M33 anti-defer)
+
+7 目標 simultaneous optimize(per CLAUDE.md `# 自主執行 canonical`):
+1. 言簡意賅 / 2. 效率+效能 / 3. SSOT 鐵律(M17/M23/M29/M30)/ 4. 易懂+維護+擴充 / 5. 世界級+一致設計語言 / 6. 完整 self-verify(M20/M31/M32)/ 7. 自動 self-improve(M14/M20)
+
+**禁defer keyword**:「下次再做 / 下個 session / 省工 / 等等」(M33 BLOCKER)。
+
+### A.4 — Verify-to-perfection(per self-verify.md 4 階段)
+
+- Post-edit:`npx tsc -b` / 相關 invariant 腳本 / `audit-content-quality.mjs --check` / `extract-canonical-rules.mjs`
+- Visual:`/visual-audit --scope=changed`(UI 改動)+ playwright pixel-quantified(M32)
+- M14 5-layer pipeline:spec / hook / SKILL / CLAUDE.md / memory 同步
+
+**Phase A complete gate**:全部 verify PASS + commit on working branch + 報 user「Phase A 完成,N 項 SSOT-UI/UX 等你拍板」。**禁** skip Phase A 直接 Phase B。
+
+---
+
+## Phase B — Codex parallel audit + 比稿辯論共識
+
+### B.0 — Codex transport discovery(per codex-collab/SKILL.md Step 0.4)
+
+3-test 順序固定(local 優先):`node_modules/.bin/codex` → `which codex` → `~/.codex/auth.json`。失敗 → 報 user,**禁 Explore agent 替身**(M31)。
+
+### B.1 — Brief codex 跑相同 Phase A 完整流程
+
+Brief format(per codex-collab/SKILL.md Step 0.05 user-verbatim faithful relay + Step 0.5 own-version invariant):
+
+```
+## User 原話(verbatim,prompt 中段引用)
+「<user 原文 quote,中英符號圖文全保>」
+
+## Claude Phase A 結果摘要
+- 全 dim audit:<N P0 / M P1 / K P2 findings>
+- SSOT-UI/UX propose:N 項(已 ASK user)
+- Autonomous landed:M 項(列具體 file:line)
+- 不 verify 但 Phase A 結論:<列出>
+
+## 請你執行 Phase A 相同流程(獨立)
+1. 全盤閱讀(CLAUDE.md / rules / spec.md ×60 / tokens / patterns / memory)
+2. 全 dim deep audit NO-SAMPLE
+3. 整理完整報告(P0 / P1 / P2 分類 + file:line + 引文 cite)
+4. 跟 Claude Phase A 結果**獨立**比對,不 frame 答案
+
+請回:Phase A 你抓但 Claude 漏的 / Claude 抓但你不同意的 / 兩邊都漏的盲區。
+```
+
+Send via `codex exec`(local CLI per M31 Step 0.4)或 cloud `@codex` 後序。
+
+### B.2 — Receive codex report + Step 4 self-check + Step 4.5 verify
+
+**禁 pass-through**(per M31 + `feedback_codex_dual_track_synthesizer.md`):
+- Step 4:M22/M23/M27/M8 4 題自檢
+- **Step 4.5 verify each claim**:grep / WebFetch / run invariant script / counter-example scan
+- 每 codex claim 標 `✅ verified` / `❌ FALSE` / `⚠️ partial`
+
+### B.3 — Step 5 比稿(matrix per claim)
+
+不可只「pick A/B/C」(round-7 trap)。對每 finding 4 axis:
+- **接受 codex**:codex 抓 + verified + Claude 漏
+- **接受 Claude**:Claude 抓 + codex 漏 / codex verified FALSE
+- **修正 = synthesize**:兩邊各補對方缺漏 → final 比兩 v1 都強
+- **重啟**:兩邊都不對 → 重做
+
+### B.4 — Disagreement → cite battle(M31 Step 4 / 5)
+
+任何 disagreement **禁** vote / 直覺;走 cite battle:
+- 各自提 spec.md path:line + 引文
+- WebFetch ≥ 3 家 world-class DS 對照
+- evidence stronger 勝;evidence 對等 → STOP 給 user 拍板
+
+### B.5 — 共識 triage → 中文人話 propose / autonomous
+
+跟 Phase A.2 同 format,但 finding source = 共識(Claude + codex 兩邊都認 + verify PASS)。
+
+---
+
+## Phase C — Final report + commit + push trigger gate
+
+### C.1 — Final report(送 user)
+
+```
+## Deep Audit Cross-Codex 完整報告(N 日期)
+
+### Phase A 結果
+- 全 dim findings: <P0 N / P1 M / P2 K>
+- Autonomous landed: <N 項> commit <hash>
+- SSOT-UI/UX 已拍板: <M 項>
+- SSOT-UI/UX 待拍板: <列出 + 簡述>
+
+### Phase B 結果
+- Codex 抓 + Claude 漏: <N 項>
+- Claude 抓 + Codex 漏: <M 項>
+- Cite battle: <K 題,各題 verdict + evidence>
+- 共識 SSOT-UI/UX 待拍板: <列出 + 簡述>
+- 共識 autonomous landed: <N 項> commit <hash>
+
+### 待你拍板(中文人話)
+<決策 1-N(per A.2 format)>
+
+### Verify artifact
+- tsc PASS / invariant PASS / content-quality PASS / visual probe PASS
+- file:line + before / after diff link
+```
+
+### C.2 — Push trigger gate(M28 solo-work canonical)
+
+**禁** AI 自決 merge main / push origin main。等 user 「Push 到 main」trigger。
+
+---
+
+## Mechanical enforcement
+
+- Pre-edit:`check_substantive_edit_approval_preflight.sh` + `check_ds_anchor_preflight.sh`(SSOT-UI/UX 必先 approval)
+- Mid:`check_audit_sample_escape.sh`(Agent dispatch 攔 sample escape)+ `check_codex_collab_5step.sh`(Layer A/B/C cite verdict)
+- Post:`stop_self_audit.sh` Mechanism 1 claim-verify-gap BLOCKER + `audit-content-quality.mjs --check`
+- Commit gate:`check_solo_workflow.sh`(no PR / 1 chat 1 branch / 等 user push trigger)
+
+## Checkpoints(禁止跳)
+
+| Checkpoint | 在哪 | What |
+|---|---|---|
+| **CP-A0** | A.0 結束 | 全盤閱讀清單給 user 看(列 N file read),禁未讀就進 A.1 |
+| **CP-A2** | A.2 SSOT-UI/UX propose | 中文人話 + 4-Q gate;**STOP** 等 user A/B 才動 code |
+| **CP-B0** | B.0 codex transport | 3-test 失敗 → 報 user 決(local install / cloud / 跳 Phase B 只 Phase A);禁 Explore 替身 |
+| **CP-B4** | B.4 cite battle | evidence 對等 → STOP 等 user 拍板,**禁** AI 自決誰勝 |
+| **CP-C2** | C.2 push gate | 等 user「Push 到 main」trigger;禁 AI 自決 merge |
+
+## References
+
+- `references/phase-a-workflow.md` — A.0 全盤閱讀 file list canonical + A.1 全 dim sub-agent dispatch template
+- `references/phase-b-codex-brief.md` — codex brief template(B.1)+ Step 4.5 verify checklist + Step 5 比稿 matrix template
+- `references/triage-rubric.md` — Scope classifier(SSOT-UI/UX vs non-SSOT)+ 中文人話 propose format + 7 autonomous 目標 expansion
+
+## 與其他 skill 分工
+
+| Skill | Scope | 不重疊 |
+|---|---|---|
+| `/design-system-audit --deep` | 全 dim Claude solo audit | 本 skill chain 為 Phase A.1,額外 Phase B + 全盤閱讀 preflight + 比稿辯論 |
+| `/codex-collab` | M31 5-step dual-track for **任意題目** | 本 skill chain 為 Phase B,額外 Phase A 前置 + 全 dim 完整覆蓋(per design-system-audit SSOT) + Phase C 共識 commit |
+| `/propose-options` | M18 4-Q gate single propose | 本 skill A.2 / B.5 chain 用它格式化 propose |
+| `/ensure-canonical` | M19 5-layer auto-pipeline | 本 skill A.3 / B.5 chain 用它落地 canonical |
+| `/knowledge-prune` | 治理文件冗贅清 | 正交,本 skill 跑稽核;`/knowledge-prune` 跑治理 hygiene |
+| `/bug-fix-rhythm` | surgical visual bug 修 | 正交,本 skill 是 broad sweep;surgical bug 不該觸發本 skill |
+
+## Anti-pattern(永久 ban)
+
+- ❌ Skip A.0 全盤閱讀(憑記憶判斷哪些 spec 該讀)
+- ❌ A.1 sub-agent prompt 含「sample top N」/「heavy agent skip」escape
+- ❌ A.2 propose 用 jargon(L1-L7 / SSOT / canonical 在 propose 內裸用)
+- ❌ 跳 Phase B 只跑 Phase A(除非 codex transport 全失敗 + user 同意)
+- ❌ B.2 收 codex reply 直接 paste 給 user(pass-through,M31 Step 4.5 verify 跳)
+- ❌ B.4 disagreement 用直覺 vote / 「兩邊都對」打太極(cite battle invariant)
+- ❌ C.2 AI 自決 merge main(M28 violation)
+- ❌ Phase A 完成沒等 user 拍板 SSOT-UI/UX 就進 Phase B(scope 跑掉)
+
+## 世界級對照
+
+- **RFC 學術同儕審查**:作者 v1 + reviewer v2(獨立)+ public cite battle 收斂共識
+- **Linux kernel patch review**:Maintainer first-pass + lkml mailing list 二 review + cite source 比稿
+- **Google ML eng-design-review**:proposer + adversarial reviewer + structured disagreement protocol
+- **Anthropic constitutional AI critic + revise**:同 model 不同 prompt 互審 → 本 skill 升級成跨 model