@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/ds-canonical/skills/bug-fix-rhythm/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: bug-fix-rhythm
+description: Batch-end-verify rhythm + parallel tool batch + user-listed N-rule MUST-ALL + claim runtime verify. Invoke when entering multi-fix session 或 user 列 numbered rules. Replaces M32(c)(d)(h1)(h2) sub-invariants(2026-05-12 split per Knowledge-Prune Checkpoint 2)。
+---
+
+# /bug-fix-rhythm — 多 fix session 的 rhythm canonical
+
+**目的**:當 session 有 ≥ 2 fixes(常見 visual bug session / user 列 N 條 numbered 規則),走 batch-end-verify rhythm,而非 per-fix verify cycle waste。**M32 split 後 (c)(d)(h1)(h2) 的 home**。
+
+**對齊**:
+- CLAUDE.md mindset #6「大原則吸收瑣碎」+ M14「對話結論 AUTO integrate」
+- Bazel incremental-build / GitHub Actions matrix-batch idiom(per-step incremental = waste,batch-end = canonical)
+- Anthropic Claude Code prompt engineering「single-message multi-tool-call」canonical
+- Toyota TPS jidoka(per-station per-item verify,不可 skip 任何 item)
+
+## When to invoke
+
+**強制 auto-chain**:
+- multi-issue session 內 ≥ 2 fix 待處理(visual / behavior / code 任 mix)
+- user 列 numbered N 條規則(「規則 1...規則 N」/「Q1...QN」/ image 標 1234)→ 視作 **MUST-ALL checklist**
+
+**手動 invoke**:user 明言「批 fix」「一次做完」「跑完再驗」「列規則」
+
+**不 invoke**(對齊 Anthropic Best Practice 小修 skip):
+- 單一 surgical fix(無 numbered rule + 無 cross-component)— per-fix verify 即可
+- pure refactor / typo / import cleanup
+- spec.md docs only
+
+## Non-goals
+
+- 不擴展到「audit full-dim」(那是 `/design-system-audit`)
+- 不取代 `/scan-similar-bugs`(那是 fix 後 root-pattern scan;本 skill 是 fix-過程 rhythm)
+- 不動 canonical 語意(走 audit-vs-execute STOP 提議)
+
+---
+
+## Workflow(4 phases)
+
+### Phase 0 — Intake & MUST-ALL checklist 化(原 M32(h1))
+
+讀 user message:
+
+**If user 列 numbered rules**(「規則 1: X / 規則 2: Y / ...」/「Q1 / Q2 / ...」/ image 標號 / bulleted list)→ 抽出 **MUST-ALL checklist**:
+
+```markdown
+## MUST-ALL checklist(per-rule 不可下放)
+- [ ] 規則 1: <verbatim user wording> — 對應 fix: <target>
+- [ ] 規則 2: <verbatim user wording> — 對應 fix: <target>
+- ...
+- [ ] 規則 N: <verbatim user wording> — 對應 fix: <target>
+```
+
+**禁止**:
+- 把 N 條視作 ranked-priority(「先修 1-3,4 之後再說」)
+- 漏 N 條中第 K 條當「做完」report
+- 改寫 user wording 為自己 paraphrase(verbatim 保留)
+
+### Phase 1 — Parallel tool batch(原 M32(d))
+
+Read / Grep / Glob 多檔需求 → **single message multi-tool-call**:
+
+```
+✓ Good: 1 message with [Read A, Read B, Read C, Grep D, Grep E]  (~2s)
+✗ Bad : 5 messages sequential                                       (~10s)
+```
+
+**Heuristic**:任何 tool call 之間**無 dependency**(後一個不需前一個結果) → 必 parallel。
+
+對齊 Anthropic Claude Code best practice:「Maximize use of parallel tool calls where possible」。
+
+### Phase 2 — Batch fix(原 M32(c))
+
+每 fix 用 Edit(不 Write,降風險)。**禁止 per-fix tsc / audit cycle**:
+
+```
+✓ Good: [Edit A] [Edit B] [Edit C] [Edit D] → final tsc + audit + visual (once)
+✗ Bad : [Edit A → tsc → audit → visual] [Edit B → tsc → audit → visual] ...  (5× waste)
+```
+
+例外:某 fix 確實依賴前一 fix 的 type 結果 → sequential 必要時可,但 verify cycle 仍 batch-end-only。
+
+### ⚠️ Checkpoint 1 — Substantive vs surgical 分流
+
+每 fix 落地前 inline 判斷:
+
+- **Surgical**(CLAUDE.md「Scope classifier — Surgical visual bug」):pixel / token / class adjustment, no new SSOT / API / cross-component → AUTO ship 此 fix
+- **Substantive**(audit-vs-execute 分權):新 SSOT / 新 prop / 新 canonical meaning / cross-component semantic → **STOP propose**,等 user verbatim 拍板才 ship
+
+混合 batch:surgical 部分 ship,substantive 部分 propose。**禁止**:substantive 偷渡進 surgical batch。
+
+### Phase 3 — Final batch-end verify(原 M32(c)(h2))
+
+全 fix 完成後**一次性**驗證:
+
+```bash
+npx tsc -b                                    # type
+npm run hooks:test                            # invariant
+node scripts/visual-audit-<target>.mjs        # pixel-quantified per M32(a)
+```
+
+**MUST-ALL re-check**(per Phase 0 checklist):
+
+```markdown
+## MUST-ALL verify report
+- [x] 規則 1: ✓ verified via <tsc | audit script | pixel measurement | playwright>
+- [x] 規則 2: ✓ verified via ...
+- ...
+- [x] 規則 N: ✓ verified via ...
+```
+
+**禁止**(原 M32(h2) claim runtime verify):
+- 寫「不會有問題」「無 side-effect」「verified」「都實作完了」**沒**對應 verify trace
+- code-reading 推論當「verified」
+- ranked-priority 漏 N 條中第 K 條當「做完」
+
+若某條無法 runtime verify → 明撤回 **「規則 K:未驗證,推論而已,user 真機 verify needed」**,不可假宣告。
+
+對齊 M20 claim-verify gap(M20 是 stop-hook 機制;本 skill Phase 3 是 active workflow side)。
+
+---
+
+## ⚠️ Checkpoints(禁止跳)
+
+### Checkpoint 1 — Phase 2 surgical vs substantive(見上)
+
+### Checkpoint 2 — Phase 3 verify trace 缺漏
+若 MUST-ALL N 條有 K 條無 verify trace → STOP report,先補 verify 再報 user。
+
+### Checkpoint 3 — User-listed rule wording 改寫
+若 Phase 0 抽 checklist 時改了 user wording → STOP,重抓 verbatim。
+
+---
+
+## 與其他 skill / hook 的關係
+
+| Tool | Scope | 跟本 skill 關係 |
+|---|---|---|
+| `/scan-similar-bugs` | fix 後 DS-wide root-pattern scan | 本 skill batch-end-verify 後**才** chain `/scan-similar-bugs` |
+| `/visual-audit` | 單次視覺對齊 | Phase 3 sub-step,本 skill 包它 |
+| `/component-quality-gate` | stakeholder gate | 不重疊(stakeholder vs daily bug fix) |
+| `stop_self_audit.sh`(hook) | claim-verify gap 攔 | 本 skill Phase 3 是 active side;hook 是 passive trip-wire |
+| `check_pixel_quantified_audit.sh`(hook) | M32(a) audit script 必 pixel | 本 skill Phase 3 跑該 audit |
+
+**3 層 防線**:
+- **本 skill**(active workflow):MUST-ALL checklist + batch-end-verify rhythm
+- **stop_self_audit.sh / check_codex_collab_5step.sh**(passive hook):claim-verify gap 攔
+- **M20 / M32(a)**(meta-rule):上游 invariant
+
+---
+
+## 世界級對照
+
+- **Bazel `bazel test //...`**:全 target 並行 + final report,而非 per-target sequential
+- **GitHub Actions matrix**:N 個 job 並行,final aggregate verdict
+- **Toyota TPS jidoka**:每 station per-item verify,**但** verify 是 station-end 而非 in-progress checkpoint
+- **Anthropic Claude Code prompt eng**:「Maximize use of parallel tool calls」
+- **Stripe / Linear engineering blog**:「batch deploy + single canary verify」over「per-PR canary」
+
+---
+
+## Self-improvement capture
+
+每次 invoke 完寫:
+- (a) Phase 0 抽 MUST-ALL 時 user wording 是否變形?
+- (b) Phase 2 surgical/substantive 分流是否準確?(false-positive 偷渡記錄)
+- (c) Phase 3 verify trace 有沒有「runtime verify needed」的條目漏標?
+- (d) 新發現 numbered-rule pattern → 加進 Phase 0 抽取 heuristic
+
+回填本 SKILL.md 或 references/。
+
+---
+
+## 歷史 absorbed failures(M32 split 來源)
+
+2026-05-12 4 prior failures absorbed by M32 → split 後本 skill 承接 (c)(d)(h1)(h2):
+1. cell-align audit「Δ=0 ALL PASS」但 user 抓 SKU/Qty 視覺垂直置中於 88px 高 row(audit 沒驗 Field collapse)
+2. divider 2px audit「ALL PASS」但 pinned panel 邊仍 2px(audit 沒驗 pixel overlap)
+3. breadcrumb tooltip audit「ALL PASS」但 user 連抓 hover 不 fire(audit 沒驗 Portal DOM bounding rect)
+4. row-alignment audit「Δ=0 ALL PASS」(attr 對齊,Field collapse 沒抓)
+
+具體 M32(a) pixel-quantified rule 仍在 meta-patterns.md,本 skill 是其 workflow side。

package/ds-canonical/skills/code-quality-audit/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: code-quality-audit
+description: Clean code 量化稽核 — `any` 使用 / dead export / file size / long function / circular dep / magic number。補 `/design-system-audit` 只管「design canonical」的缺口。Invoke via /code-quality-audit scope=all(release / 季度)OR scope=changed(daily)OR scope=component:X(focused)。Auto-chain by `/design-system-audit --deep` Dim 27 + `/component-quality-gate` Ship phase + `/new-component` Phase 4.5。
+---
+
+# Code Quality Audit — Clean Code 量化稽核
+
+Scope:**tsx / ts code hygiene**,跟 design canonical 正交。
+
+## 為什麼要這 skill
+
+`/design-system-audit`(全 dim per design-system-audit SSOT)管 design / spec / canonical correctness。但 **clean code 面向**(`any` 濫用 / dead export / 函式爆長 / circular dep / 檔案超標)**無任何 dim 覆蓋**。每次建元件 / audit / ship 都該跑這層。
+
+## 6 個 check
+
+| # | Check | Severity | 如何判定 |
+|---|-------|---------|---------|
+| 1 | `any` 使用 | P0 | grep `: any` / `as any` / `<any>` / `any[]` / `Record<X, any>`;支援 `// any-allow: {rationale}` 逃生口(同行或上一行) |
+| 2 | File size(.tsx)| P0 > 800 / P1 > 500 | `wc -l`;budget 500 / transition cap 800;spec 同 `check_file_size_budget.sh` policy |
+| 3 | Long function | P1 > 80 行 | naive:`function`/`const` 宣告到 matching `}` indent 行距 |
+| 4 | Dead export | P1 | `export` 名稱在其他 src/ 檔無出現;exempt `*Props/Options/Config/Args/Context/Variants/Value` 型別 API 慣例 |
+| 5 | Circular dep | P0 | DFS import graph,找 cycle |
+| 6 | Magic number | P1 | 覆蓋不完整 → 由 token 防線(`lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`)層負責(primitive color / shadow / Tailwind v4 `[--foo]`);本 skill 不重複 |
+
+## When to run
+
+- **Daily**:`/code-quality-audit --scope=changed`(git diff)
+- **Component ship**:`/component-quality-gate` Ship phase auto-chain
+- **New component**:`/new-component` Phase 4.5 auto-chain
+- **Release / 季度**:`/code-quality-audit --scope=all`
+- **Focus one component**:`/code-quality-audit --scope=component:<Name>`
+- **CI gate**:`node scripts/code-quality-audit.mjs --check`(P0 violation → exit 1)
+
+## Workflow
+
+1. Run `node scripts/code-quality-audit.mjs [--scope=<scope>]`
+2. Triage findings into P0 / P1 / P2
+3. Auto-fix trivial(unused imports,trivial `any` casts with obvious type)
+4. STOP for user decision on:
+   - File-size P0(大 component architectural split)
+   - Circular dep(需設計層面重組)
+   - 無法 auto-type 的 `any`(需 design judgment 訂 proper type)
+
+## 禁止
+
+- 禁 silent 吞 `any`(必加 `// any-allow: {rationale}`)
+- 禁把 dead export 直接刪(可能是 planned API surface);flag → user 決策
+- 禁把 long function 硬拆(拆錯比爆長還糟);只提議,user sign-off
+
+## Integration points
+
+| Skill / Hook | How |
+|---|---|
+| `/design-system-audit` Dim 27 | `--deep` 必 chain 本 skill scope=all |
+| `/component-quality-gate` Ship | chain 本 skill scope=component:{Name} |
+| `/new-component` Phase 4.5 | 元件建完必跑 scope=component:{Name} |
+| Hook `check_code_quality.sh` | PostToolUse Edit/Write on src/ — 只跑 any + file-size(quick) |
+
+## References
+
+- `scripts/code-quality-audit.mjs` — 實作
+- `.claude/hooks/check_code_quality.sh` — per-edit lite check
+- 相關:token 防線 `lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`(正交 — token 紀律 vs code 紀律)

package/ds-canonical/skills/codex-collab/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: codex-collab
+description: Codex dual-track collab for visual/SSOT/canonical decisions. Claude own → codex own → 比稿 synthesize(永遠 3-step,不 pass-through)。Local `codex exec` 為主 transport(地端);GitHub PR comment 為 fallback。Queue SSOT `.claude/memory/codex-brief-queue.jsonl`。Invoke when user asks「跟 codex 討論 / 比稿 / 確認」.
+---
+
+# Codex Collaboration Workflow
+
+**生態位**:Claude(本 agent)在 DS canonical / 視覺 SSOT 決策上**容易忽略既有原則**(M14/M20 累積 evidence)。Codex 作 **第二把關 AI**,以**討論模式**(非 commit handoff)介入,讓兩個 model 互相 cross-check,降低單一 model bias。
+
+**Claude vs Codex 分工**:
+| 角色 | Claude (我) | Codex (@codex on GitHub) |
+|------|------------|---------------------------|
+| 主要職責 | synthesizer + implementer | reviewer + second opinion |
+| 寫 code | YES(在 user approve 後) | NO(本 workflow 禁止 commit,純討論) |
+| 跑 hook / skill | YES(本 repo CLAUDE.md / hook / skill 全載入) | NO(在 GitHub sandbox 看不到 hook) |
+| 對 user 負責 | YES(最終結論由我 report) | NO(透過我轉述) |
+| Benchmark cite | M22 mandate | 也須 cite source(我 enforce) |
+
+**核心原則**:Codex 不直接 commit。所有結論由 Claude 收斂、跑完 M1-M31 自檢、user approve 後由我落地。
+
+## ⚠️ Step 0 入口 gate(2026-05-10 加,fix auto-fire anti-pattern)
+
+**啟 codex collab 前 explicit check 兩條件,缺一就不 fire**:
+
+(a) **Claude 自試完仍卡**:跑完 grep / read source / DS canonical cite / WebFetch 外部 source 後,仍**無法**確定 root cause 或 design tradeoff
+(b) **User 明確 keyword**:「跟 codex 討論 / 比稿 / 找他確認 / 跟他辯論 / dual-track」
+
+**任一通過即可 fire;兩個都不滿足 = 不 fire**(per M31 Step 0 + 本 SKILL L50 主原則)。
+
+**Anti-pattern 錨**(2026-05-10):Phase A Breadcrumb commit `5ab31ce` 我已 grep + read spec + 有 cite 充分仍 auto-fire codex,user 抓「沒主動叫你也會自動觸發?」+ 撤回 unnecessary collab。本 anti-pattern codified for 反向 reference。
+
+## ⚠️ Step 0.4 — Transport discovery(2026-05-17 P0,fix「找 codex 找錯位置」amnesia)
+
+**Rule**:啟 codex 前必跑 3-test,**順序固定**:
+
+```bash
+ls -la node_modules/.bin/codex && node_modules/.bin/codex --version   # 1 Local CLI(primary)
+which codex 2>/dev/null && codex --version 2>/dev/null                 # 2 Global(罕見)
+ls -la ~/.codex/auth.json                                              # 3 Auth(sanity)
+```
+
+**Decision**:1 ✅ → local CLI(canonical per `references/transport.md:36-40`)/ 1 ❌ + 2 ✅ → global / 1+2 ❌ + 3 ✅ → `npm install`(`@openai/codex` 已 npm dep)/ 全 ❌ → 報 user。**禁 fallback Explore agent 當 codex**(M31 違反:Explore 同模型,不滿足 dual-track 第 2 bias)。
+
+**Anti-pattern**:`which codex` 失敗就斷言 unreachable → 嘗試 sudo install / 繞 M28 開 PR / Explore 替身。詳 `.claude/memory/feedback_codex_local_transport_node_modules.md`。
+
+**Hook 機械強制**:`stop_self_audit.sh` 偵測「codex/dual-track/比稿 keyword + 無 `node_modules/.bin/codex` cmd trace」→ BLOCKER。
+
+## ⚠️ Step 0.05 — User-verbatim faithful relay invariant(2026-05-15 P0)
+
+**Rule**:Brief 必含 **3 block**:(1) `## User 原話` verbatim quote(不 paraphrase / 中英 / 標點 / 圖文 ref 全保)(2) `## Claude 理解 + 脈絡` paraphrase + file:line + 已驗 source + 自試 hypothesis + 不確定點(3) `## 請獨立解讀 user 原話` codex 不被 §2 框架限。**禁** 只送 paraphrase。
+
+**User 原話 SSOT**(2026-05-15):「也要告訴他我的原話,讓他也能有機會解讀我的原話 ... 說不定codex在解讀別人的問題比你還有慧根 ... 請你在infra上避免你下次又在局限codex發現問題的能力」
+
+**Why**:Paraphrase 過濾 user 細節 / 加 Claude 偏見 / frame 問題 → codex 只能在 Claude 框架答 surgical fix → root cause 沒抓到。錨例 2026-05-15:I1 placeholder ellipsis + I3 overflow 兩 bug user 提 2-3 次,每次送 paraphrase → 冰山修。Hook `check_codex_brief_verbatim.sh`(未實作;verbatim-relay `## User 原話` heading 檢查無 write-time hook — live `check_codex_brief_invariants.sh` 只 cover 全盤閱讀/triple-verify/禁抽樣/禁列檔 audit-flow invariants,不涵蓋此 verbatim-relay,改靠本 Step 0.05 mindset enforcement)。
+
+## ⚠️ M31 Universal 5-step canonical(2026-05-10 user directive)
+
+「你跟 codex 都要各自驗證過並視覺稽核過,最後你整合出完美完整的版本」+「據理力爭但要有依據,各自熟讀所有檔案,infra 強迫整合前有此 mindset,避免被 codex 錯誤解法牽著走」。
+
+**每次 codex collab 必走 5-step,不論 agree 或 disagree(不只 disagree 才啟動)**:
+
+| Step | Claude | Codex | 共通 invariant |
+|---|---|---|---|
+| **1 各自熟讀** | grep / read spec.md / canonical / source 真讀 | `exec -s read-only` grep / git show / read source | 憑印象 propose = M31 違反 |
+| **2 各自驗證** | `npx tsc -b` + invariant + audit script | **audit-verify**:`exec --dangerously-bypass-approvals-and-sandbox -C $PWD`(user-authorize)跑**同樣** tsc / invariant / .mjs / Playwright + 貼 stdout(per `references/phase-b-codex-brief.md` B.0.1);**純讀**:`exec -s read-only` grep / git show | 任一方未跑真 verify 撤回;**禁** codex 只目測機械維度(verify 不對稱違 M31 Step 2)|
+| **3 各自視覺稽核** | playwright screenshot + DOM + pixel audit | code-read + diff + grep visual path | 只 code 跳 visual 違反 user directive |
+| **4 各自 cite-based propose** | 3-column:`spec.md path:line / 引文 / reasoning` | 同上獨立出 | hand-wave 無 cite 撤回 |
+| **5 整合完美版本**(NOT pass-through)| Agree → synthesize 補對方缺漏;Disagree → cite battle verify 對方 cite + counter-cite | 同上雙向 | **絕禁** Claude pass-through codex / 只一方驗證跳整合 |
+
+**Hook 機械強制**(P1 soft):`check_codex_collab_5step.sh` 攔 git commit message 含 codex/Layer A/B keyword 必同含 spec.md cite + verify keyword + verdict keyword。缺任一 → stderr 警告。
+
+**Anti-pattern 錨例**:
+- **Issue 8 cell border**(2026-05-10):codex 「Field edit border 透明」→ Claude pass-through ship → user 「白癡 被 codex 牽著走」→ cite battle 修正(field-controls.spec.md Field state machine SSOT 反駁)→ 落地雙 owner。**違反 Step 1-3-5**。
+- **Issue 11 controller retire**(2026-05-10):codex disagree(RFC Contract 3/6 cite)→ Claude 完整 5-step counter-cite(grep zero consumer + Phase 7 commit `c5eb054` 證據)→ codex round 2 grep 確認 → synthesize retire+RFC backfill。**M31 正確 pattern 參考錨**。
+
+**Transport: Cloud vs Local(2026-05-08)**:Step 0.5 / 4.5 / 4.6 / 5 dual-track invariants 不分 transport — 換 channel 不換 discipline。詳 `references/transport.md`。簡述:雲端 Claude Code → cloud(`@codex` GitHub);地端 Claude Code → local(`codex` CLI,須 `codex login` 一次)。Default cloud(留 PR trail);敏議題 / 同 session 急 round-trip / cloud 失敗 fallback → local。
+
+**Codex 輸出全來源 invariant(2026-05-07 user 拍板)**:
+任何 codex 輸出 — **DISCUSS-ONLY 深 reply / bot 自動 PR review(`chatgpt-codex-connector[bot]`)/ PR comment / inline review thread** — 統一視為 **2nd-opinion 輸入,非 directive**。任何來源都必過完整 Step 4.5 verify + Step 5 比稿 才動 code。**禁止「bot review = 直接修」短路**。歷史錨例:2026-05-07 commit `775d879` 我把 codex bot 兩條 P2 直接修沒做 own-version + 比稿,user 糾正 → commit `f24998f` 補上完整 own-version + 比稿 documentation。本 invariant 永久 codified。
+
+---
+
+## When to invoke
+
+**主原則(2026-05-07 user directive)**:**Claude 自己先嘗試解**,確認自己解不好 / 不確定 root cause 時才 invoke codex。**禁止**「user 提了新 bug → 自動丟 codex」,user 沒明確說「跟 codex 討論」就不塞給他。
+
+明確 trigger(滿足任一才 invoke):
+1. **User 明確要求**:「跟 codex 討論 X」/「與 codex 確認」/「let's get codex's take on X」
+2. **Claude 自認 stuck**:investigate root cause 後仍不確定 / 多 hypothesis 沒 evidence 收斂 / 跨 framework 不熟悉(eg. Windows-specific bug 但本地是 Linux)
+3. **Deep audit (`/design-system-audit --deep`)**:Phase 4.5 second-pass(audit 是 explicit benchmark 場景)
+4. **Cross-component canonical 訂立**(M8 benchmark 後)需獨立 reviewer
+
+**禁止 invoke**:
+- 單純 typo / 機械 lint
+- User 已給明確指示的 implementation
+- User 提新 bug 但沒說「跟 codex 討論」(預設 Claude 自己處理)
+- Claude 還沒做 grep / read source 就丟 codex(等於把工作外包,違反主原則)
+
+---
+
+## Discussion mode workflow(7 步)
+
+### Step 0:user 觸發
+
+User 說「跟 codex 討論 X」或本 skill 自動 trigger condition 滿足。
+
+### Step 0.1:**DS Anchor Preflight**(M29 mandatory,2026-05-08)
+
+Brief 前必查 `.claude/references/ssot-index.md` + grep `*.spec.md` 找 anchor canonical,brief 內含 **3-column owner table**(`Candidate owner spec` / `Canonical sentence` / `Conflicting code/comment`)。**若 spec ≠ code → STOP 寫 RFC**(`.claude/planning/<topic>-rfc.md`),等 user 拍板才進 Step 0.5。詳 `.claude/memory/feedback_ds_anchor_preflight.md`。
+
+### Step 0.5:**Claude own-version v1 + dimension matrix**(合併原 Step 0.5+0.6,anti-pass-through)
+
+**User directive(2026-05-07)**:「我跑一版 → codex 跑一版 → 我比稿 → 取優棄劣 → final 最佳方案」+「品質 100% 不打折 + Claude = synthesizer not dispatcher」。
+
+**強制(寫 brief 前必跑)**:(1) 我自己跑完整分析(audit + WebFetch ≥3 source)(2) Brief 內**先寫「我 v1 = X 因為 Y」+ dimension matrix**(禁只列 options 求 codex pick = round 7 trap)(3) 列具體 hypothesis + recommendation。Codex reply 必獨立寫他 v1 + per-axis 比稿,不可「pick best option」。違 = pass-through。
+
+### Step 1:Claude 草擬 Discussion Brief(以 Step 0.5 own-version 為基礎)
+
+**Brief format + 6-section template + 歷史錨點** → `references/brief-template.md`(SSOT 收錄)。
+
+核心禁忌(永久 ban):Brief ≤220 字 / Reply ≤200 字 / 3-line 模板 / 為 cloud 速度 truncate。深度 invariant 不分 transport。
+
+### Step 2:Post to PR via mcp__github__add_issue_comment
+
+target PR:當前 working branch 的 PR(`mcp__github__list_pull_requests` 找到 head=current branch)。
+
+**投遞成功率 invariant(2026-05-07 codex 自診斷,絕對遵守)**:
+
+歷史錨點:同日我送 5 條 brief 連發 → codex Cloud queue dedup skip 4 條(只回 1 條)。Codex 自己診斷 root cause = **interval too short**(短時間連送 → 後端 dedup)。
+
+**強制規則(2026-05-08 user-tuned interval + serial gating)**:
+- ✅ **Brief 間隔 ≥ 3 min**(2026-05-08 改;前 5 min 過保守,user 拍板對齊 codex 原建議 2-3 min 中位)。trade-off:dedup window 風險微增,由下一條 serial gating 補強。
+- ✅ **Serial gating — 同時最多 1 brief in-flight**:有 pending(未 reply / 未 exhausted)brief 時,**禁止送新 brief**;其他排隊到 queue file,前一條 reply / exhausted 才送下一條。避免 codex queue 兩條混淆 / dedup window 撞。
+- ✅ **Auto-followup 10 min**(前 15 min):pending brief 過 10 min 無 reply → 自動 new comment `@codex follow-up to brief <id>`。第 2 次 followup 再 +10 min(20 min mark)。第 3 次 +10 min(30 min mark)。3 次 followup 仍無 reply → mark `exhausted`,user-handoff,不再自動送。
+- ✅ **每條 brief 用新 `add_issue_comment`,不要 edit 既有 comment**(webhook 不把 edit 當新 task)
+- ✅ **Opener canonical**:`@codex DISCUSS-ONLY` 或 `@codex IMPLEMENT`(明確 mode signal)
+- ✅ Brief content **保留 deep format**(unchanged, per L1 Step 1 invariant)— interval rule 跟 depth invariant 不衝突
+- ✅ 漏接補救:**新 comment** with `@codex follow-up to brief <id> ...`(不要只「請看上面」)
+
+**Queue 跨 session 持久化(2026-05-08 user 拍板)**:
+- SSOT:`.claude/memory/codex-brief-queue.jsonl`,JSONL 一行一 brief
+- Schema:`{ id, url, topic, sentAt, status, followupCount, lastFollowupAt?, repliedAt?, deferredAt?, deferReason?, planRef?, queuedAfter? }` — status ∈ `pending` (active 等 reply 可 auto-followup) / `deferred` (user 明示「之後再/晚點/先放著」**不 auto-followup**,等 explicit re-invoke 轉 pending)/ `replied` / `exhausted`
+- **每 session start 必讀**(本 SKILL invariant — 載入掃 queue 找 pending resume tracking;`deferred` 不送 followup)
+- 事件:send brief = append;reply 來 = `replied` + repliedAt + unblock queued;followup auto = ++count + lastFollowupAt;3 round 無 reply = `exhausted` + handoff prompt;user defer trigger = `deferred` + deferredAt + deferReason + planRef
+- TodoWrite 仍用(session-scoped 視覺呈現),但 ground truth 在此 file
+
+**Quality-fail re-mention**:reply 來但有 commit / doc 沒 push / Missing Q / M22 無 cite URL / Off-topic / 短 format truncate 任一 → 自動 new comment「previous reply quality issue,需要 X」(逐條列 fail + 重申 deep / cite ≥3 / Q1-QN)。
+
+**禁止**:Send brief 後 forget(queue file 是 SSOT)/ Edit 既有 comment 期待重 trigger / 為投遞率 truncate 深度。
+
+### Step 3:Subscribe + wait
+
+`mcp__github__subscribe_pr_activity` → 等 webhook event,**不 poll**(Anthropic best-practice,等推送)。
+
+### Step 4:Codex 回覆 → Claude 自檢(M22/M23/M27/M8)
+
+收到 codex reply 必跑 4 題自檢(避免 codex 也犯 M1/M22 錯):
+1. **M22 cite check**:codex 引的 benchmark 有 inline source?無 → reply 要求補
+2. **M23 DS-first**:codex 建議是否覆蓋 DS 既有 canonical?有 → 我手動驗 DS spec/token
+3. **M27 namespace**:codex 建議 prop name 是否撞 DS 既有?
+4. **M8 ≥3 source**:codex 只引 1 家 → reply 要求補到 3 家
+
+任一題失敗 → Step 4.5 仍要跑(自檢結果記下),Step 5 一併 report。
+
+### Step 4.5:**獨立 verify codex 具體 claim**(不可省 — anti-pass-through)
+
+**Why**:Step 4 只 check 表面 cite,不 verify codex 結論。錨 2026-05-07 `775d879` pass-through + 2026-05-19 6+ 條讀前 N 行就斷 truncated(SSOT `memory/codex_collab_backfill_2026-05-19.md`)。
+**強制動作**(逐條 claim):
+0. **Last-verdict gate**(MUST 先跑):`tail -n 240 reply.md` grep `Verdict|tokens used|採納` 必命中;Read `--offset=$((total-240)) --limit=240`。禁讀前 N 行就斷 truncated。
+1. **Grep DS-internal**:codex 指的 file/token/pattern 真存在?`grep -rn` 確認
+2. **WebFetch external**:codex cite world-class URL → fetch 真內容(high-stakes 必跑)
+3. **Run script**:codex 給數字(「28→16」)→ 跑腳本核對
+4. **Counter-example scan**:codex 說「X anti-pattern」→ grep DS 是否已用且 work
+5. **記錄**:每 claim 標 `✅ verified` / `❌ FALSE` / `⚠️ partial`
+**禁止**:跳 Step 4.5 直接列 A/B/C = pass-through;跳 step 0 讀前 N 行斷 truncated。
+
+### Step 4.6:**Regression / 連動 scan on 我自己 proposed fix**(2026-05-08 user 拍板,絕對禁省)
+
+**Why this exists**:Step 4.5 只 verify codex 的 claim 真不真;不 verify **我自己 propose 的 fix 是否會造成連動非預期錯誤**。歷史:2026-05-07 commit `775d879` 我把 `tableRoot` 改 optional + document fallback,自以為 backward-compatible 但**沒 grep callers** + 沒想 future caller 不傳會仍 cross-instance — codex round 2 抓出來才修成 strict required(`f24998f`)。Step 4.6 強制 regression scan 阻 anti-pattern。
+
+**強制動作**(逐條 propose 動 code 前必過):
+1. **Grep all callers / consumers**:動 API / symbol / token / hook / variant → grep DS-wide 找所有 consumer,每個 consumer 行為變化?有 break case?
+2. **Type contract impact**:optional → required 是 breaking;default value 改 是 breaking;param order 改 是 breaking;return type 縮窄 是 breaking — 列出每條 breaking change 的 mitigation
+3. **Edge cases**:boundary conditions / null path / empty input / race / concurrent state / a11y(keyboard / screen-reader) / dark mode / density / RWD viewport — 至少跑 5 條
+4. **Cross-component impact**:這 fix 動的東西其他 sibling component / pattern / token 有間接消費?(SSOT chain 反向)
+5. **Run existing tests**:`npx tsc -b` + `node scripts/data-table-invariants.mjs`(若動 DataTable)+ 相關 stories 互動驗
+6. **記錄 scan result**:每項標 ✅ safe / ⚠️ partial / ❌ break + 證據;任一 ❌ → re-design 不 commit
+
+**禁止**:propose fix 後直接 Edit / Write / commit 沒跑 4.6;靠「應該沒問題」直覺 ship — 違反 = anti-pattern。
+
+### Step 5:**比稿 my own-version vs codex-version → final synthesized 方案**
+
+**Anti-pattern**:把 codex reply 整段 paste 給 user 然後問「拍 A/B/C?」。這是 pass-through,不是 collab。
+
+**User directive(2026-05-07)**:「**比稿** — 取優點去缺點 → final 最佳方案。確保品質 100% 不打折」。
+
+**強制比稿過程**:
+1. 把 Step 0.5 own-version + Step 4.5 verified codex-version 並列成 matrix
+2. 逐條決定:
+   - **接受 codex**(我沒想到 + verified 對)
+   - **接受我自己**(codex 漏掉 / 過度激進 / verified FALSE)
+   - **修正(取兩邊優點)**(eg. codex 提 -12 hooks,我 verify 只 -5 reachable → final -8 兼顧 codex aggressive 跟我 conservative)
+   - **重啟**(兩邊都不對 → 重新做)
+3. 列 final 方案,不再列 A/B/C 給 user 拍 unless 真歧義
+
+**強制 reply format**:Step 4 self-check(M22/M23/M27/M8)+ 4.5 verify 表 + 4.6 regression scan 表 + 5 接受/拒絕/修正 + final action(僅真歧義列 options)。錨例 `029b647` `f24998f` `775d879`。
+
+### Step 6:User approve → Claude 實作
+
+由我(非 codex)實作,跑完整 stop hook (`stop_self_audit.sh`)+ M14 5-layer pipeline。
+
+**Joint test case planning(D-class architectural change 必走,2026-05-07 user 拍板)**:
+
+當實作屬「architectural change 加新 primitive / 動 layer 系統 / 動 SSOT owner」(eg. P1 D 路徑 `<CellInteractiveOverlay>`),Step 6 升級成 **dual-track 實作** + **joint test case planning**:
+
+> 「到時候要做的時候你跟 codex 一起協作實作,然後兩者同時一起列 test case 確保所有情境都能被驗證無誤」
+
+**強制流程**:
+1. **Implementation dual-track**:Claude 寫 v1 + codex 寫 v1 → 比稿 final
+2. **Test case 同時列**(joint planning,**非依序**):
+   - Claude 列 Q1-QN test scenarios
+   - Codex 列 Q1-QN test scenarios(獨立)
+   - 比稿合併 → final test plan(union — 防漏單邊)
+3. **Min coverage 框架**(per architectural change scope):
+   - 4 大 stories regression(virtual / autoRow / inline / pinned)若觸 DataTable
+   - State combinations(size × mode × pinned 狀態)
+   - Visual pixel-level Playwright probe
+   - Hit test(pointer-events 不破 click chain)
+   - Z-index / portal context(DragOverlay / HoverCard popup 不破)
+
+**禁止**:
+- ❌ 只 Claude 列 test case(防漏)
+- ❌ 只 codex 列 test case(防 codex bias)
+- ❌ 依序列 test(必須兩邊獨立 → 比稿 union)
+- ❌ skip joint planning 直接 implement(architectural change 規模需要 test case 全 coverage)
+
+### Step 7:Implementation 完 → 回 codex 結案
+
+PR comment:`@codex 結論已 land at <commit>. 感謝 review.`
+
+---
+
+## Guardrails
+
+沿用既有 hook(`check_benchmark_citation.sh` / `stop_self_audit.sh`),codex reply 不入 commit,hook 對 final commit 強制。**禁止**:codex commit 直接 push / 跳過 Step 4 送 user 原文 / 把 codex reply 當 ground truth。**M20 self-improvement**:codex 抓的 M-rule violation → 加 `.claude/memory/codex-caught-violations.md`。**Auto-codify(2026-05-07)**:任何 collab 新發現 → 立刻 5-layer(SKILL + memory + CLAUDE.md + planning),trigger「確保記錄起來」「不需要再對你耳提面命」「自然就知道」。
+
+## Deep Audit 整合 + Cross-session persistence
+
+`/design-system-audit --deep` Phase 4.5 自動 invoke 本 skill(brief「review Phase 1-4 findings,有 systemic issue 嗎?」→ Codex reply 進 Phase 5,M14 chain)。新 session user 說「跟 codex 討論」→ 必查本 SKILL.md 按 Step 0-7 走;CLAUDE.md 任務導航表已 anchor;**禁憑記憶簡化流程**。

package/ds-canonical/skills/codex-collab/references/brief-template.md

@@ -0,0 +1,48 @@
+# Codex DISCUSS-ONLY Brief Template
+
+Brief format invariant(2026-05-07 user 拍板,禁短 format)。
+**禁**:Brief ≤ 220 字 / Reply ≤ 200 字 / 「結論→原因→下一步」3-line / 為 cloud 速度 truncate。
+**強制**:不限字 + Q1-QN multi-question + ≥3 world-class source cite per Q + counter-proposal request。
+
+```markdown
+@codex DISCUSS-ONLY (no commit) — <topic>
+
+## User 原話(verbatim,Step 0.05)
+<不 paraphrase / 標點 / 圖文 ref 全保>
+
+## 請獨立解讀 user 原話(Step 0.05)
+<不被下面 Claude 框架限制,自己解讀>
+
+## Claude 理解 + own-version v1(Step 0.5)
+<paraphrase + file:line + 已驗 source + hypothesis + 不確定點>
+**我 v1 = X 因為 Y**(Step 0.6:禁只列 options 求 codex pick)
+
+## Benchmark Cited (M22/M26, ≥3)
+- <DS source 1 + URL/path>
+- <DS source 2 + URL/path>
+- <DS source 3 + URL/path>
+
+## DS Internal Canonical Consulted (M23)
+- <既有 token / variant / spec.md path>
+
+## Specific Questions for Codex(Q1-QN)
+1. <root cause 對嗎?還有 alternative?>
+2. <benchmark 是否漏掉 world-class case?>
+N. <SSOT 是否該抽到更上層 primitive?>
+
+## Constraints
+- DS 原則 M1-M32 全適用(31 active;M27/M33/M34/M35 retired,折入 M20/M7/M23(c)(d);尤其 M8 / M17 / M22 / M23)
+- 不可 commit,純文字討論
+- 程式碼建議須 cite world-class DS source
+- Counter-proposal request:挑戰我的 hypothesis,提第 4 條路
+- 必產 3-column cite table(claim / path:line / reasoning)
+
+## 🚨 三 invariant — 2026-05-23 user 永久 directive(缺一 = brief 不合格)
+1. **全盤閱讀全部 source**(CLAUDE.md / 31 active M-rules / 5 rules/*.md / 90 audit dims SKILL.md / 全部 spec.md / 全部 stories / 全部 components / tokens / patterns / hooks / 全部 memory files / planning),**禁憑記憶**(spec/story/component/memory 數量隨時變動,故不硬編數字 — 一律「全部」;M-rule / audit-dim 數由 sync-governance-counters 機械守住)
+2. **Triple-verify per finding**:(a) grep DS-wide 確認 pattern 存在 (b) Read 對應 spec.md / tsx 確認 problem 真存在 (c) 對照既有 canonical 確認非 documented exception。任一 NO → 自動撤回,**禁無病呻吟**
+3. **禁抽樣** — DS-wide ALL files 全掃,context 不夠拆 stage 全跑完;sub-agent admission「I sampled / spot-check / representative」= audit incomplete reject
+```
+
+## 歷史錨點
+
+2026-05-07 我嘗試「短 format 加速 codex」(brief ≤220 字 / reply ≤200 字),user 糾正:「我要 codex 完全深度評估給完整 2nd opinion,即使慢」。撤回短 format,本 SKILL 永久禁。

package/ds-canonical/skills/codex-collab/references/transport.md

@@ -0,0 +1,58 @@
+# Codex transport — Cloud vs Local
+
+> SKILL Step 0.5 / 4.5 / 4.6 / 5 dual-track invariants are **transport-agnostic**。本 reference 只說 transport 怎麼選 + 怎麼跑。
+
+## 兩條 transport（不合而為一,環境決定）
+
+| 屬性 | Cloud(`@codex` GitHub mention)| Local(`codex` CLI) |
+|---|---|---|
+| 執行環境 | 雲端 Claude Code(remote sandbox)| 地端 Claude Code(本機 macOS)|
+| 通道 | `mcp__github__add_issue_comment` → `@codex` mention → GitHub webhook → codex sandbox → reply comment | `npx codex exec "<brief>"` 同步 stdout |
+| Latency | 15-30 min wait per reply | 1-3 min per reply |
+| Dedup risk | YES(短時間連送 → backend dedup,故 3 min interval + 1 in-flight serial)| NO(每次 fresh process)|
+| Persistence | PR comment thread 永久保留 | stdout 需手動存 → 寫入 `.claude/memory/codex-brief-queue.jsonl` 加 `transport:"local"` 欄位 |
+| Cost | 不收 token(GitHub 那端)| 收 OpenAI API token(本機帳號)|
+| Auth | GitHub login(harness 已 set)| `codex login`(user 跑一次,本機 `~/.codex/auth.json`)|
+| 適合場景 | (1) PR-attached deep audit(留 trail)(2) cross-session async wait OK(3) 雲端 sandbox 唯一可用 channel | (1) 同 session 快速 round-trip(2) 私下技術討論(不污染 PR 歷史)(3) Step 4.5/4.6 在同 terminal 連跑 |
+| 不適合 | 即時討論 / 同 session 多 round | 需要 PR-thread audit trail / 雲端 environment 沒地端 channel |
+
+## Cloud transport（既有 SKILL Step 1-7 完整流程不變）
+
+按 SKILL.md Step 1-7 走。Queue SSOT `.claude/memory/codex-brief-queue.jsonl` schema 加 `transport:"cloud"`(default)。
+
+## Local transport（新增）
+
+### Prerequisites（一次性）
+1. `npm install`(已含 `@openai/codex@^0.128.0`)
+2. `npx codex login`(interactive,user 親跑;harness sandbox 跑不了 stdin)
+3. 確認 `~/.codex/auth.json` 存在
+
+### 流程（沿用 cloud Step 0-7,只換 transport）
+
+**Step 0**：user trigger 同 cloud。
+**Step 0.5**：own-version 完整跑(同 cloud 不變)。
+**Step 1**：寫 deep brief(同 cloud format 不變)。Brief content 寫 `.claude/tmp/codex-brief-<topic>.md`(暫存,不入 git)。
+**Step 2 transport-swap**：
+```bash
+# 不是 mcp__github__add_issue_comment;改:
+node_modules/.bin/codex exec --output-last-message /tmp/codex-reply-<topic>.md \
+  "$(cat .claude/tmp/codex-brief-<topic>.md)"
+```
+- `--output-last-message` 把 codex final reply 存檔(避免 stdout 亂入)
+- 同步 block 到 codex 回完
+- Reply file 進 Step 3(取代 webhook subscribe)
+
+**Step 3**：Read `/tmp/codex-reply-<topic>.md`,append 進 `.claude/memory/codex-brief-queue.jsonl` `{transport:"local",replyFile:"/tmp/...",repliedAt:...}`。
+**Step 4 / 4.5 / 4.6 / 5**：完全同 cloud(self-check / verify / regression / 比稿 — invariant 不分 transport)。
+**Step 6 / 7**：implement → optionally PR comment 通知 cloud codex「結論」(若 cloud 也參與過)。
+
+### 警示
+- ❌ Local 別跳 Step 0.5(我先 own-version)/ 4.5(verify codex claim)/ 4.6(regression scan)/ 5(比稿)— SKILL invariant 不分 transport,違 = 退化 pass-through
+- ❌ Local 不留 audit trail → user 後追溯靠 `.claude/memory/codex-brief-queue.jsonl` + `replyFile`,不可省
+- ❌ 不為了 local 速度 truncate brief 或 reply(深度 invariant 同 cloud,不打折)
+- ✅ Local 跑完 → reply 摘要存 PR comment(若有對應 PR),保 cross-session discoverability
+
+### 雙 transport 同題場景
+- 主 channel 失敗(eg. cloud 3 round followup 仍無 reply)→ fallback local
+- 高敏議題(eg. 涉及尚未公開 commit / 私下技術討論)→ default local
+- 一般 audit / canonical / cross-component decision → default cloud(留 PR trail)