@qijenchen/design-system 0.1.0-beta.92 → 0.1.0-beta.95

package/ds-canonical/fork/AGENTS.md

@@ -1,213 +1,116 @@
-> **Generated(禁手改)**:本檔由 `build-fork-governance.mjs` 從 DS repo root `AGENTS.md` 投影(path 已改 node_modules 視角);隨 DS 發版重生,fork 端以 npm / `npm run sync-all` 取得最新。
-> **你是 FORK PRODUCT 開發者**:遵循檔內設計紀律(mindset / SSOT 消費 / 命名 / 4-Family / 稽核觀念);**忽略 DS-author 的發版/治理維護鏈**(`release:preflight` / tag / npm publish / codex-collab / DS `scripts/*.mjs` gate — 那是 DS 維護者的);git 節奏照 fork 的「預覽 → 確認 → 上線」(詳本 repo CLAUDE.md)。Deep detail → `node_modules/@qijenchen/design-system/ds-canonical/`。
-
-# 本專案 AI 治理核心(provider-neutral;AGENTS.md 開放標準)
-
-**本檔為所有 AI agent 的治理 SSOT bootstrap**:Codex 等支援 AGENTS.md 標準的 agent 原生載入;Claude Code 經 `CLAUDE.md` 的 `@AGENTS.md` import 載入同一份(Anthropic 官方共用模式)。增刪改治理核心**只改本檔**,兩邊自動同步。
-**最終 authority 不是本檔**:本檔引導行為;不可繞過的強制層 = `npm run release:preflight`(~30 deterministic gates)+ CI(release.yml / ci.yml)。**任何 provider 產出的不合規變更都無法通過 preflight/CI 發佈**。Claude 另有 write-time hooks 加速回饋(`.claude/hooks/`,provider 專屬加速器,非信任邊界)。
-
-# 每次任務前的 6 條 mindset(世界級設計系統的工作底色)
-
-這 6 條是本專案所有規則背後的**態度**。接到任務先複習一遍,再看具體規則。
-
-1. **對標世界級 + 不取巧省工**——每個設計決策都要能回答「Polaris / Material / Atlassian / Ant / Carbon / Apple HIG 怎麼做?」沒對齊又說不出理由 = 設計 bug。視覺整齊度不輸原版 + 符合 DS 語言**同時成立**。**禁止以「選較簡單」「省 N edits」為由選 shortcut**——一律最世界級做法。說「快速修」「省工程」是 yellow flag,停下重想。
-2. **不憑直覺發明 / 優先消費既有**——新增任何值 / 名 / pattern / variant / layout primitive 前先 `grep` 既有。**強制 `# SSOT 消費 canonical` 清單**——寫視覺 code 前列消費的 components/patterns/tokens/spec。提建議也算定 pattern,給 option 必對照 DS canonical + ≥3 家世界級。**禁止憑印象列部分家**。
-3. **改一處必看三處**——code / spec / story 三方聯動。改 cva `defaultVariants` / variant / token 前先 grep 該元件所有檔案,一次改完。
-4. **範例必真實業務場景**——Jira / Stripe / Notion / Figma 可辨識情境;禁 `Option A/B/C`、「按鈕一」、極端不現實、ASCII art。
-5. **猶豫就問**——無前例的決策:grep 既有 → 讀近親 spec → 仍不確定停下問。**禁止憑直覺造新 pattern**。
-6. **大原則吸收瑣碎**——同類 bug 反覆糾正 = meta 層沒抓住。見 `node_modules/@qijenchen/design-system/ds-canonical/rules/meta-patterns.md` 31 active M-rules(M1-M32,M27/M33/M34/M35 retired,折入 M20/M7/M23(c)(d))。**AI 不需 user 提醒才找 root invariant**——rule 震盪 → AI 自跑 M12 benchmark + invariant test。User 第 2 次問 → 必截圖 verify(M13)。對話結論 → AUTO 5-layer pipeline(M14)。Visual / behavior decision 前必先 WebFetch ≥ 3 source(M26)。Solo-work git ops 必先 grep canonical(M28)。**視覺/結構 propose 前必 grep DS spec.md 找 owner SSOT(M29)— 出 3-column 表;否則提案不被接受**。使用者 tell me once 不該要 tell me twice。
-
-完整 M-rules 詳 `node_modules/@qijenchen/design-system/ds-canonical/rules/meta-patterns.md`(必讀)。
-
-# Rule Index(progressive disclosure — 編對應檔案前必先讀)
-
-| 檔案 | 何時必讀 |
-|---|---|
-| `node_modules/@qijenchen/design-system/ds-canonical/rules/meta-patterns.md` | 每個任務(31 條 M-rules,fundamental)|
-| `node_modules/@qijenchen/design-system/ds-canonical/rules/spec-rules.md` | 編任何 `*.spec.md` 或 DS 內容 |
-| `node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md` | 編任何 `.tsx`/`.ts`(Tailwind 5 條 / Token 4 條 / Props 命名 / shadcn / public-vs-internal)|
-| `node_modules/@qijenchen/design-system/ds-canonical/rules/story-rules.md` | 編任何 `*.stories.tsx`(三層定位 / Title / 範例準則)|
-| `node_modules/@qijenchen/design-system/ds-canonical/rules/self-verify.md` | 編任何檔案(Pre/Mid/Post/Pre-commit 4 階段自驗)|
-| `node_modules/@qijenchen/design-system/ds-canonical/references/ssot-consultation.md` | 寫視覺 code 前(9 項決策對應 SSOT + tsx 檔頭宣告)|
-| `node_modules/@qijenchen/design-system/ds-canonical/references/ssot-index.md` | 視覺/結構 propose 前(owner SSOT 對照)|
-| `node_modules/@qijenchen/design-system/ds-canonical/references/naming-conventions.md` | 命名新檔/變數/prop |
-| `node_modules/@qijenchen/design-system/ds-canonical/skills/design-system-audit/references/audit-prompts.md` | 稽核判準 SSOT(91 dim rubric,Claude 與 Codex 同判準)|
-
-(Claude Code 對 `node_modules/@qijenchen/design-system/ds-canonical/rules/` 有 path-scoped 自動載入;其他 agent 依本表在編對應檔案前主動讀取——**同一份檔案,零複製**。)
-
-# 治理 canonical(home 分層 + anti-bloat)
-
-## 規則放哪 home(8-home 分層)
-
-| Level | Home | 收什麼 |
-|-------|------|--------|
-| 1 | `AGENTS.md`(本檔;Claude 經 CLAUDE.md import) | 每 session signal 的 mindset + 6 條 + 任務導航 |
-| 1.5 | `node_modules/@qijenchen/design-system/ds-canonical/rules/*.md` | path-scoped rules(Claude 自動載入;其他 agent 按 Rule Index 讀) |
-| 2 | `{name}.spec.md` | 單元件「何時用 / 為什麼」 |
-| 3 | Pattern `spec.md` | runtime 跨元件 primitive |
-| 4 | Code(`.tsx` / `.css`) | cva / 型別等機械強制 |
-| 5 | Skill(`node_modules/@qijenchen/design-system/ds-canonical/skills/`) | invoke 情境的多步驟 workflow + checkpoint |
-| 6 | Memory(`~/.claude/.../memory/` SSOT + repo `.claude/memory/` mirror)| 跨 session 狀態。本機編完跑 `npm run sync-memory` 推回 repo |
-| 7 | Hook(`.claude/hooks/`) | 機械化 pre/post tool 檢查(Claude write-time;最終兜底 = preflight/CI) |
-| 8 | Slash Command(`node_modules/@qijenchen/design-system/ds-canonical/commands/`) | 一次性單步 action |
-| 9 | Plan doc(`.claude/planning/`)| 完整 plan / RFC / spec 草稿 SSOT;memory file 是短 index pointer |
-
-**Q1 設計規則 → Level 1-4 / Q2 invoke 情境 → Skill or Command / Q3 隨時間變化 → Memory(short index)+ Plan doc / Q4 機械化 → Hook(+ preflight gate)**。完整 flowchart → `node_modules/@qijenchen/design-system/ds-canonical/skills/design-system-audit/references/rule-placement.md`。
-
-## 行數預算(Anthropic 對齊)
-
-Bootstrap(AGENTS.md + CLAUDE.md 合計)target ≤ 250 / transition ≤ 400 / hard cap 800。SKILL ≤ 250 / spec ≤ 300(foundational SSOT 例外 ≤ 800-1200)/ memory **per-file ≤ 100 lines** + **MEMORY.md index ≤ 20 entries**(soft 18 / hard 20)。Hooks **26 soft / 60 hard**(SSOT = `session_start_governance_check.sh` Check 7)。動態值以 `scripts/sync-governance-counters.mjs` 跑出為準。
-
-## Anti-bloat L1-L3
-
-- **L1 Pre-write**:`check_file_size_budget.sh`(+ governance hooks — dynamic SSOT 在 `.claude/hooks/`)
-- **L2 Per-edit**:`log_governance_fires.sh` → `.claude/logs/hook-fires.jsonl`
-- **L3 Periodic**(季度 / `--deep`):`/knowledge-prune` skill,retire ≥ 5%
-
-## 加規則前必過 3 題
-
-1. 既有 Meta-Pattern / 近親 spec / canonical chapter 命中 → append pointer 不新寫
-2. **Rule-of-3**:同概念 ≥ 3 處 → 選 SSOT 其他 pointer
-3. 7 天後還會 fire 嗎?不確定 → 不寫
-
-# 稽核 canonical
-
-3 層級 × 6 維度。**Stakeholder-visible artifact**(prototype / 元件 merge / 產品 demo)**必過 code + visual 雙層 audit**(搭配 M6+M10)。
-
-| Tier | 時機 | Scope | Skill |
-|------|------|-------|------|
-| 1 Stakeholder-gate(強制)| 新元件 merge / prototype / demo | artifact-scoped | `/component-quality-gate` / `/prototype` P3.5 / `/product-ui-audit` P5 |
-| 2 Daily dev | bug / refactor / 文字改 | git diff + direct consumer | `visual-audit --scope=changed`(default) |
-| 3 Periodic deep | release / token 大改 / 季度 | full DS | `/design-system-audit --deep` |
-
-| 維度 | 對應 skill |
-|------|-----------|
-| D1 設計語言 | `/design-system-audit` |
-| D2 程式語言 | tsc + lint + `/design-system-audit` |
-| D3 元件效能 | `/performance-audit` |
-| D4 UX 行為 | `/ux-audit` |
-| D5 視覺品質 | `/visual-audit`(Layer A mechanical + B AI) |
-| D6 原則自檢 | `design-system-audit/references/principle-audit-protocol.md` |
-
-**Consistency 類稽核必 Phase 0 全掃再判**。**Deep audit 全掃優先 + 決策 batch-at-end 鐵律**(2026-07-11 user directive):先全 DS 掃完(NO-SAMPLE)→ 跨元件去重 → **最後一次**列「真問題 + 只影響 SSOT-UI/UX」決策清單給 user 拍板;非-SSOT autonomous 做完美;**禁**途中逐元件問 user。
-
-**Audit-vs-execute 分權**:動 canonical substantive meaning → STOP 提議;對齊 / 表達統一 / 清 duplicate / 補 pointer → AUTO。
-
-**Scope classifier — Surgical visual bug**:user 列 N 個 visual defects + 無新 canonical / 無新 API contract / 無 cross-component semantic 改動 → **Surgical scope**:no collab / no new M-rule / no audit report,batch fix + final pixel-quantified verify only。Substantive 改動走 audit-vs-execute STOP 提議流程。
-
-# Independent second opinion(跨 provider 對抗審查)
-
-**Canonical 概念**:重大變更(governance / Critical DS change / deep audit)需 **author provider ≠ reviewer provider** 的獨立第二意見。判準 = 同一份 rubric(`audit-prompts.md`),reviewer 只提 findings(rule 對照 + severity + evidence),**不得**自建規範。記錄雙方 provider/model/version。
-- Claude authored → Codex review(現行 driver = `/deep-audit-cross-codex` Phase B,transport = `scripts/codex-run-guarded.mjs`)
-- Codex authored → Claude review(對稱)
-- **Backend 不可用 → fail-closed**:標 review pending;禁同一 agent 假扮另一 provider;Critical change 不得取得 compliant 宣稱。
-
-# SSOT 消費 canonical
-
-寫視覺 code 前必查對照 — 沒列 = 自創。**完整對照表 + 強制 checklist** → `node_modules/@qijenchen/design-system/ds-canonical/references/ssot-consultation.md`(SSOT owner;含 9 項決策對應 SSOT + 新元件 tsx 開頭「── 消費的 SSOT ──」段強制要求)。
-
-# 任務導航表
-
-| 任務 | 必讀 |
-|------|------|
-| **新增元件** | `node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md` 「建立 UI 前必讀 / shadcn 元件規範」 + `node_modules/@qijenchen/design-system/ds-canonical/rules/spec-rules.md` → `/component-quality-gate` |
-| **修 variant / size / state** | 該元件 `spec.md` → `/story-writing` |
-| **新增 token** | `tokens/README.md` → `node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「Token 命名 4 條硬規則」→ `tokens/xxx.spec.md` |
-| **寫 story / 視覺 code** | `/story-writing` + `# SSOT 消費 canonical` |
-| **命名新檔 / 變數 / prop** | `# 命名與語言一致性` + `node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「元件 Props 命名」 |
-| **新元件 layout** | `# 4-Family Layout Model` |
-| **建產品 / 開新 product app** | `npm run create-app <name>` → `apps/<name>/`;**2-scenario architecture SSOT** → `node_modules/@qijenchen/design-system/ds-canonical/references/scenario-definition.md` |
-| **新 skill / hook / command** | `.claude/{home}/README.md` charter |
-| **無前例設計決策** | `# 遇不確定時的協議` |
-| **Tailwind 出怪事** | `node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「Tailwind 5 條核心」+ `# 失敗記憶索引` |
-| **Stakeholder 產出 / 稽核** | `# 稽核 canonical` |
-| **User 糾正後** | `# 治理 canonical`(home 判斷) |
-| **跟 codex 討論 / 多輪震盪 / 任何 codex 輸出** | `node_modules/@qijenchen/design-system/ds-canonical/skills/codex-collab/SKILL.md`(M31 5-step canonical SSOT)+ M31 anchor in meta-patterns.md |
-| **PR merge 後 / session start branch 健檢** | `# Git solo-work canonical` |
-
-**找不到** → 進 `# 遇不確定時的協議`,不自決定。
-
-# Git solo-work canonical(SSOT → `.claude/memory/feedback_solo_dev_workflow.md`)
-
-**1 chat = 1 working branch**;**Netlify preview 是 user gate**;**「push」/「OK」trigger 才 merge main**。**Session-start 必先 grep canonical + 開 working branch,禁直接在 main 上 edit production code**(M28 sub-rule)。
-
-| 步驟 | 動作 |
-|------|------|
-| 1 Edit | AI 改 code |
-| 2 Commit + push working branch | 自動觸發 Netlify per-branch preview |
-| 3 告訴 user 主要 change(or preview URL)| 讓 user 知道看什麼 |
-| 4 等 user trigger | **「push / OK / 好 / 合 main」** → step 5;**「改 X / 不對 / 等等」** → 繼續 step 1 |
-| 5 Squash merge to main | 不開 PR(可 GitHub API squash-merge OR fast-forward)|
-| 5.5 **SSOT propagation gate** | 動到 skill/hook/spec/token/AGENTS/CLAUDE 等 SSOT-affecting paths + user 已給 merge trigger → AI 自動 bump → **`npm run release:preflight`**(唯一發版前 gate 指令)→ tag → publish → `npm view` 驗證,全程不停下問;user 隨時可喊停。bump npm `0.1.0-beta.<N+1>` |
-| 6 砍 remote branch | `git push origin --delete <branch>` |
-| 7 Local 對齊 | `git checkout main && git fetch && git reset --hard origin/main && git branch -d <branch>` |
-
-**禁止**:開 PR / AI 自決 push main / 同 chat 開多 branch / 留 stale 不刪 / 「下個 session 處理」deferred 措辭。
-
-# 命名與語言一致性
-
-**3 重 test**(governance):
-1. **既有 DS 詞彙**:對齊 `compact/rich / sm/md/lg / action/indicator / scanning/reading`?
-2. **世界級 idiom**:≥ 2 家 world-class DS 用此詞?
-3. **跨元件認知衝突**:同字串在其他元件已有不同語義?
-
-3 test 全過才採納。詳細 → `node_modules/@qijenchen/design-system/ds-canonical/references/naming-conventions.md`。
-**語言一致性**:spec.md 繁中(技術術語保留英) / code identifier 英 / 單一檔案不中英夾雜。
-
-# 4-Family Layout Model
-
-**每元件 spec 第一段必聲明 Layout Family**(1/2/3/4 或「self-contained」)。
-
-| Family | 用途 | SSOT |
-|--------|------|------|
-| 1 Menu item / 2 List item | scanning / reading | `patterns/element-anatomy/item-anatomy.spec.md` |
-| 3 Pill | 單行互動 pill | `components/Button/button.spec.md`「Pill Layout」|
-| 4 Field control | 可編輯資料輸入 | `components/Field/field-controls.spec.md` |
-
-# 自主執行 canonical(Autonomy Default)
-
-**Default = autonomous + complete + verify-to-perfection;省工 = anti-pattern(違 mindset #1)**。
-
-| 動作類別 | 預設 |
-|---------|-----|
-| **SSOT-affecting UI/UX**(增刪改 component / token / spec 視覺結構 / 跨元件 design language) | **ASK** — 中文具體人話講選項 + tradeoff,user 拍板才動 |
-| Bug fix / clean / refactor / 命名一致 / test / audit / verify | **AUTO** — 整批做完 + 完整驗證 + 撤回機制 |
-| Governance / hook / skill / spec **內部**(typo / pointer / 結構 — 不動 canonical meaning)| **AUTO** |
-| Perf / a11y / 漸進遷移(不動 SSOT)| **AUTO** — 整批 + verify |
-
-**自主執行同時優化 7 軸**:言簡意賅 / 效率+效能 / SSOT 鐵律 / 易懂維護擴充 / 世界級+一致設計語言 / 完整 self-verify / 自動 self-improve。
-**反 pattern**(禁):「省工」/「下次再做」/「下個 session」/「OK 嗎?」過度 ASK / shortcut 避 verify。
-**Trigger phrase auto-pipeline**:「依原則自主」/「不需問」/「馬不停蹄」/「全部做完」/「自動」→ autonomous mode,僅 SSOT-affecting UI/UX 停下 ASK。
-**Triple-verify before propose**:propose / 列 option / 發現「問題」前必 inline 跑 (1) grep DS-wide (2) Read spec.md / tsx (3) 對照 canonical exception。三題全過才 propose。
-**SSOT auto-sync invariant**:跨 file 數字禁 hardcode 多處;以 `scripts/sync-governance-counters.mjs` 機械對齊。
-
-# 遇不確定時的協議
-
-**無前例且影響 SSOT UI/UX 設計判斷**時 3 步,禁跳:**grep 既有**(30 秒)→ **讀近親 spec.md** → **仍不確定停下問** user。
-**非 SSOT-UI/UX**(refactor / test / perf / a11y / hook / skill / typo / 對齊既有 canonical)→ autonomous,無需問。
-禁:跳 grep 憑記憶 / 隨便挑 / 留 TODO。可跳:bug 修 / 機械勞動 / user 明確指示。
-
-# 失敗記憶索引(技術沉默陷阱 only)
-
-| 技術陷阱 | 一行 anchor |
-|--------|-----------|
-| Tailwind v4 `[--foo]` 必 `var()` | silent 失效 |
-| tailwind-merge 自訂 utility 必註冊 group | 否則 strip |
-| 元件自包 Provider | 劫持全站 |
-| 清 unused imports 後 runtime | tsc 不充分,需 storybook |
-| shadcn compat alias 回流 | dark mode 不聯動 |
-| `asChild ? Slot : Native` 內部 JSX 仍渲染多 children | React.Children.only runtime fail;asChild 分支 render 只傳 consumer child |
-| `tsc -b` 不 emit declaration | TS4023 漏抓;型別 surface 改動必 `npm run build:lib` |
-| 工具 flag 沉默陷阱:`rsync -a` 等長同秒靜默跳過(必 `--checksum`)/ `rg` 黏寫 `-rn` 的 `-r`=replace 輸出假字串 | 寫後斷言 + flag 分開寫 |
-| DS css 不在 tokens.css aggregator 也沒被 tsx import = orphan | consumer 靜默拿不到 |
-| storybook-smoke 驗舊 build = 假綠 | smoke script 已加 stale-build guard |
-
-新 bug → 歸 Meta-Pattern OR 本表 1 行;> 10 條 = 漏寫,評估 meta-merge 既有 M-rule。
-
-# 專案 Stack
-
-Vite + React + TypeScript + Tailwind v4 + shadcn/ui + Storybook + 自訂 Design Token;完整路徑 + Token 系統 → `node_modules/@qijenchen/design-system/src/tokens/README.md`(charter)— DS 內化在 npm workspace。
-
-# 元件完成 + Exploration
-
-merge 前 invoke `/component-quality-gate`(35 項 + visual + clean-code 三層)。正式 `node_modules/@qijenchen/design-system/src/` vs 比稿 `src/explorations/`;比稿 `*.v1.stories.tsx` + `notes.md`,定案升級 patterns/ 或 components/。
+# Product consumer AI governance (provider-neutral)
+
+> **Generated view**: upstream `build-fork-governance.mjs` publishes this role-specific source as
+> `AGENTS.md`. Do not edit the generated copy. Claude loads it through `CLAUDE.md`; Codex and other
+> AGENTS-compatible agents load it directly.
+
+## Authority and trust boundary
+
+- This repository builds a product with exact versions of `@qijenchen/design-system` and
+  `@qijenchen/storybook-config`; it does not author or publish those packages.
+- The deterministic local authority is the exact installed hooks-off checker:
+  `npm run governance:check`. Merge enforcement comes from protected `main` requiring it as a check.
+- Native Claude/Codex hooks are fast feedback only; hookless operation is judged by the same
+  hooks-off checker. Generated hook commands scrub inherited startup injection before repository
+  launchers, and the running provider host stays an external trust boundary, so hooks never
+  replace protected CI.
+- Run `npm run setup:all` in every fresh local checkout and hosted setup/cache-refresh lifecycle. It
+  installs the committed lock, verifies signatures, and runs the exact checker; SessionStart only verifies.
+- `governance/lock.json`, managed provider adapters, and managed skills are generated upstream.
+  Product-specific, provider-neutral policy belongs in `governance/overlay.md`; read it when present.
+  It may add stricter product rules but must never replace or weaken upstream controls.
+- Never install a mutable tag or semver range for internal packages. Upgrades are reviewed pull
+  requests that pin an exact version and include the regenerated lock/adapters.
+<!-- canonical-decision-authority:start -->
+**Decision／Engineering Authority**:user 保留所有產品／UI／UX SSOT 真取捨，以及任何會改變使用者可感知結果、產品語意或 canonical UI／UX SSOT 的決策權，包含 component behavior／contract、interaction／IA、visual／token／layout／content／a11y 語意、合理設計方案選擇、新增刪改 canonical design rule，以及無法證明維持既有 intent 的變更；positive evidence 必在同一 active scope 綁 exact target、choice、operation digest，引用／條件／舊 scope／target-wide 推定無效。其餘工程治理與 external writes 皆 Standing Authorization AUTO，包含已核准 UI／UX 語意的實作及機械式 generation／sync：由 policy 允許的最高 certified model/reasoning/compute，依 frozen scope、SSOT、repo evidence、tests/Harness、security、independent review、least privilege、staged rollout/rollback/readback 收斂；涵蓋 source→commit/PR/merge→GitHub/package/release→template/WM/certification/rollout/recovery，不逐 milestone 重問。需人類授權紀錄時，本 delegation 綁 target digest 寫入既有 audit record；無 certified peer 則 `REVIEW-BLOCKED`。
+
+**Human-only boundaries**:僅不可代理 login/MFA/OAuth/owner/billing、缺 credential reference(只問 secret/vault/Environment/Secret Manager reference，禁貼 secret)、plan 外付費、法律／帳號／組織權限／商業承諾及上述產品決策。Agent 先定唯一工程方案/preflight，只給一個精確 human action，readback 繼續；retry/evidence 後 technical blocker 可 fail-closed，但非 human engineering decision。
+<!-- canonical-decision-authority:end -->
+
+## Six working principles
+
+1. **World-class, no shortcuts**: visual and interaction decisions must be defensible against at
+   least three relevant systems such as Polaris, Material, Atlassian, Ant, Carbon, or Apple HIG.
+2. **Consume before inventing**: search the installed public API, nearest component spec, token, and
+   pattern before adding a value, wrapper, variant, or layout primitive.
+3. **Change all affected surfaces**: product code, tests/stories, and product documentation move
+   together. A DS defect is reported upstream with a minimal reproduction; never patch `node_modules`.
+4. **Use real product scenarios**: examples must represent recognizable business work, not Option
+   A/B/C placeholders or minimal mocks that conceal composition problems.
+5. **Ask only for a genuine product decision**: first search current product usage and the nearest
+   shipped DS spec. Stop only when the remaining choice changes product UX or canonical meaning.
+6. **Fix the invariant, not one symptom**: search for sibling occurrences, add a regression proof,
+   and route reusable DS/template defects to their canonical upstream owner.
+
+## Before changing product UI
+
+Record the canonical inputs you inspected:
+
+- public component/pattern exports from `@qijenchen/design-system`;
+- the nearest shipped `*.spec.md` under
+  `node_modules/@qijenchen/design-system/src/`;
+- relevant token docs under
+  `node_modules/@qijenchen/design-system/src/tokens/`;
+- a nearest shipped story or a real product precedent;
+- any product-specific exception and its concrete rationale.
+
+Only import public package exports. Deep imports, copied DS source, raw primitive reimplementations,
+magic visual values, and undocumented escape markers are governance failures.
+
+## Layout and composition model
+
+Every new product composition identifies its closest family before implementation:
+
+| Family | Use | Canonical owner |
+|---|---|---|
+| Menu/list item | Scanning and reading rows | shipped `patterns/element-anatomy` spec |
+| Pill | One-line action or state pill | shipped `components/Button` spec |
+| Field control | Editable input and display state | shipped `components/Field` specs |
+| Self-contained | No shared row/field anatomy | nearest public component spec, with rationale |
+
+Macro spacing consumes `--layout-space-{tight,loose,bottom}` as specified. Fixed micro geometry is
+allowed only when the shipped spec makes it intentional and the exception is narrowly documented.
+
+## Verification contract
+
+For every change, run the checks that exist in this product and report their real outcome. The
+minimum repository-wide contract is:
+
+1. `npm run governance:check` (exact installed, hooks-off authority);
+2. `npm run typecheck`;
+3. `npm run build`;
+4. product lint/test/a11y scripts when present;
+5. browser or Storybook visual verification for user-visible changes.
+
+Never replace a check with `true`, an empty script, a notice-only waiver, or an unverified claim.
+Missing required tooling is a failure, not a pass. Evidence must bind the checked source snapshot.
+
+## Claude, Codex, and future agents
+
+- Registry materializers project one skill source into every enabled provider view; no view is SSOT.
+- Native events enter one immutable hook corpus; unsupported events use the exact checker/protected-CI
+  fallback and are never presented as native parity.
+- Future providers read `AGENTS.md` and use the same checks; adapters cannot redefine semantics.
+- `independent-review` requires a distinct certified peer, immutable read-only evidence, or reports
+  `REVIEW-BLOCKED`. Product review cannot authorize DS/template/release/promotion changes; route upstream.
+
+## Git and release flow
+
+- One task uses one working branch and one PR into protected `main`; never direct-push `main`.
+- Required checks, conversations, preview/canary evidence, and protection readback must be clear.
+  Then merge and verify under Standing Authorization—no self-approval or chat trigger.
+- Product repos never publish the DS; exact-version upgrade PRs merge only after product canary gates.
+
+## Pilot and upstream feedback
+
+This product may serve as a canary for the DS/product template. When a failure is reusable:
+
+1. preserve a minimal product reproduction and evidence;
+2. classify the owner as product, DS, template, governance corpus, or deployment infrastructure;
+3. fix the canonical owner first;
+4. release an immutable upstream version;
+5. upgrade this product by exact-version PR and rerun all gates;
+6. remove any temporary product workaround after the upstream fix lands.
+
+WM is a pilot consumer, not an alternative governance authority. Its local checks may add product
+coverage but may not replace or weaken the shipped lock/checker/provider surfaces.

package/ds-canonical/fork/CLAUDE.md

@@ -0,0 +1,54 @@
+@AGENTS.md
+
+# Product Workspace — Claude Code Adapter
+
+> **Generated view**: `build-fork-governance.mjs`; this adapter is governance-owned and must stay
+> byte-identical to the exact installed payload. Put product-specific, provider-neutral additions in
+> `governance/overlay.md`, never below this Claude-only adapter.
+
+This file contains Claude Code mechanics only. Shared product rules, SSOT pointers, review requirements, and quality policy come from the imported `AGENTS.md`. Operational onboarding and deploy instructions live in `README.md` and `docs/`; do not duplicate them here.
+
+## Discovery surfaces
+
+- `.claude/skills/**` is the generated Claude view of the same classified workflows published to `.agents/skills/**`. Change the DS canonical skill and regenerate; never maintain two versions by hand.
+- `.claude/settings.json` registers the two provider-neutral thin adapters in `governance/bin/`.
+  The dispatcher invokes the exact-version npm governance payload; deleting or retiring the Claude
+  discovery surface cannot remove the shared launcher substrate used by other providers.
+- `SessionStart` is verification-only. It may report missing `AGENTS.md`, governance lock, or installed dependencies, but it must never run `npm install`, resolve `@beta`/`latest`, rewrite a lockfile, or materialize skills.
+- A native hook is fast feedback, not the trust boundary. The provider-neutral governance check and protected CI decide pass/fail even when hooks are disabled or unavailable.
+- Generated hook commands clear Bash, Node, Python, and dynamic-loader startup injection before the
+  repository launcher. Claude's already-running host process and any command shell created before
+  that command are still the local host trust boundary; a repository hook cannot sanitize code that
+  has already executed.
+
+## Fresh environments
+
+Use `npm run setup:all` as the Claude Code on the web environment **Setup script**. It runs
+the shared locked install, signature audit, and exact installed hooks-off checker before work. The
+web environment may reuse a cached setup result, so rebuild that cache or run the same command
+explicitly whenever the committed lock changes. Opening or resuming a Claude session does not
+mutate the checkout through repository SessionStart. If setup cannot authenticate the locked
+snapshot, treat the environment as degraded and do not claim compliance.
+
+No Claude plugin is required. Installing one may add convenience, but it cannot replace or override the committed bootstrap, exact release lock, generated provider views, or hard gates.
+
+## Exact upgrades
+
+`npm run sync-all` is read-only planning. Applying an upgrade requires an exact semver on a clean dedicated branch:
+
+```text
+npm run sync-all -- --to X.Y.Z
+npm run sync-all -- --apply --to X.Y.Z
+```
+
+Review the resulting diff and merge only through the protected upgrade PR after governance and product CI pass. Dist-tags and semver ranges are intentionally rejected.
+
+## Claude-specific timing
+
+- Dispatcher bodies are read from the installed exact payload on each invocation.
+- Changes to `.claude/settings.json` may hot-reload, but a fresh session only verifies discovery of
+  the reviewed adapter. It is not runtime certification; certification requires current,
+  independently signed target-bound evidence and external enforcement readback.
+- Newly generated `.claude/skills/**` are discovered on the next session. Do not use `/clear` as a substitute for a reviewed upgrade.
+
+For preview, Netlify, app creation, handoff, and product workflow, follow `README.md`; those rules are provider-neutral.

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

@@ -0,0 +1,207 @@
+---
+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)。
+---
+
+<!-- _generated: canonical provider skill projection; source: skills/bug-fix-rhythm/SKILL.md; provider: codex; do not edit this adapter view. -->
+
+<!-- provider-binding: profile=repository-legacy-surfaces-v1; provider=codex; strategy=generated-binding-header; assumptionCount=6; assumptionFingerprint=sha256:b5e2cfe4a41bdd25605847b0d40fa92db96c4abf604decb830cb218b19ae38d9; evidence=packages/governance/canonical/providers.json#codex -->
+
+## Provider binding contract
+
+This canonical workflow contains a committed inventory of legacy assumptions. Resolve them exactly as follows; an unavailable resolution or inventory drift is `ADAPTER-BLOCKED`:
+
+- `provider-identity`: Treat historical provider names as provenance labels, never as the current runtime identity.
+- `provider-surface-path`: Resolve legacy repository paths through generated views while treating ds-canonical as the semantic owner.
+
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+
+# /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)
+- provider-neutral parallel execution 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**(對齊 current provider 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)
+- 不在本 skill 自行擴張 canonical scope；若發現 canonical finding，依 shared authority
+  classifier 路由(P2E 自主修正，只有真產品／UI／UX SSOT 取捨才 P2H)
+
+---
+
+## 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 保留)
+
+**Sweep-first, edit-second(2026-07-07 治理進化軌道 2 codify)**:任一 fix 屬「跨切面決策」
+(改名 / 詞彙統一 / 規則性改動,可寫成 grep 謂詞者)→ **先跑謂詞產出「sweep manifest」**
+(grep 指令 + 全庫命中清單,artifact 化),照清單做完、驗證清單歸零,才算該 fix 完成。
+**禁**「先改直覺想到的檔、稽核抓漏再補」(anchor:2026-07-07 meta 詞彙統一三波 11→16→9 檔,
+規則在散文裡 → 三輪才收斂;寫成謂詞後一個 grep 掃平)。
+
+### 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。
+
+對齊 provider-neutral best practice:「在依賴關係允許時並行執行」。
+
+### 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
+- **P2E engineering substantive**:治理／架構 SSOT、refactor、test、migration、adapter 或
+  不改 public 行為的 cross-component invariant → **AUTO**，依 evidence + independent
+  review + hard gates 自主完成。
+- **P2H product/UI/UX substantive**:新 public prop semantics、產品 workflow／interaction、
+  視覺／文案 canonical meaning 或其他 user-visible tradeoff，且既有 SSOT 無唯一答案
+  → **STOP propose**，只接受 exact target-bound user decision。
+
+混合 batch:surgical + P2E 一起自主完成；P2H 保持 proposal-only。**禁止**:把 P2H
+偷渡進 engineering batch，也禁止把 P2E 轉交 user 做工程選擇。
+
+### Phase 3 — Final batch-end verify(原 M32(c)(h2))
+
+全 fix 完成後**一次性**驗證:
+
+```bash
+npx tsc -b                                    # type
+npm run governance:check
+use the active browser/Storybook screenshot workflow and preserve visual evidence
+```
+
+**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) |
+| the installed immutable governance checker(hook) | claim-verify gap 攔 | 本 skill Phase 3 是 active side;hook 是 passive trip-wire |
+| the installed immutable governance checker(hook) | M32(a) audit script(the product-specific verification workflow (when configured),canonical = `visual-audit.mjs`)必 pixel | 本 skill Phase 3 跑該 audit |
+
+**3 層 防線**:
+- **本 skill**(active workflow):MUST-ALL checklist + batch-end-verify rhythm
+- **stop_self_audit.sh**(passive hook,claim-verify gap,BLOCKER)+ **check_codex_collab_5step.sh**(passive hook,codex-collab commit 缺 cite+verify+verdict marker,P1 soft stderr 不 block)
+- **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
+- **Provider-neutral execution discipline**:「依賴關係允許時並行執行」
+- **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。