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

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

@@ -1,17 +1,17 @@
 ---
 name: codify-corrections
-description: Process .claude/logs/user-corrections.jsonl — the Stop-hook-harvested signals of user corrections ("不是" / "不對" / "應該" / "糾正" etc.). Dedup by session + keyword, cluster by topic, propose edits to the right home(CLAUDE.md M-row / memory feedback file / skill reference / spec.md rationale). Each cluster is a Checkpoint — user approves before edit. After codification archive processed entries. Invoke when user-corrections.jsonl > 20 entries(session_start soft reminder)or > 40 entries(hard threshold), OR quarterly. This skill closes the loop between mindset #6 "user tell me once, not twice" and actual governance text changes — without it, corrections die in logs.
+description: Process $GOVERNANCE_STATE_DIR/user-corrections.jsonl — the Stop-hook-harvested signals of user corrections ("不是" / "不對" / "應該" / "糾正" etc.). Dedup by session + keyword, cluster by topic, and apply edits to the canonical owner(ds-canonical rule / repository memory / canonical skill reference / spec.md rationale) under the shared authority classifier. Engineering/governance clusters auto-execute with evidence; only genuine product/UI/UX SSOT tradeoffs stop. After codification archive processed entries in the same Git-owned runtime state root. Invoke when user-corrections.jsonl exceeds 20 entries(session_start soft reminder)or exceeds 40 entries(hard threshold), OR quarterly.
 ---
 
 # Codify Corrections — 把 user 糾正 log 落到 governance 文件
 
-**目的**:`.claude/logs/user-corrections.jsonl` 是 `stop_harvest_corrections.sh` 從每 session transcript 抓到的「不是 / 不對 / 應該 / 糾正」訊號。骨架存在,但從 log 到實際 CLAUDE.md / memory / spec edit 原本全靠人工讀 + 決定寫哪,實務上堆積 = 骨架失靈。本 skill 把這條 loop 合上。
+**目的**:`$GOVERNANCE_STATE_DIR/user-corrections.jsonl` 是 `packages/design-system/ds-canonical/hooks/stop_passive_logging.sh` R2 `rule_harvest_corrections()`(原 lib/stop_harvest_corrections.sh,已 folded 進統一 Stop hook)從每 session transcript 抓到的「不是 / 不對 / 應該 / 糾正」訊號。`$GOVERNANCE_STATE_DIR` 必須是 trusted adapter 提供的 Git-owned `<git-dir>/governance-runtime/` 子路徑；任何 provider home 都不是 telemetry authority。骨架存在,但從 runtime signal 到實際 canonical rule / repository memory / spec edit 原本全靠人工讀 + 決定寫哪,實務上堆積 = 骨架失靈。本 skill 把這條 loop 合上。
 
-**對齊 CLAUDE.md**:
-- 資訊治理 canonical L2(per-commit)下游
+**對齊 canonical governance**:
+- 治理 canonical L2(per-commit)下游
 - mindset #6「user tell me once,我不該要 tell me twice」執行面
-- M14 AUTO integrate pipeline 第 7 層(memory / CLAUDE.md 落地)
-- 稽核 vs 執行 分權:動 canonical substantive → STOP Checkpoint(本 skill 內建)
+- `packages/design-system/ds-canonical/rules/meta-patterns.md` M14 AUTO integrate pipeline 第 7 層(memory / canonical rule 落地)
+- 稽核 vs 執行分權:純工程／治理 canonical substantive → AUTO；只有產品／UI／UX SSOT 真取捨 → human-only boundary
 
 ## When to run
 
@@ -23,9 +23,9 @@ description: Process .claude/logs/user-corrections.jsonl — the Stop-hook-harve
 ## Non-goals
 
 - 不改 code(`.tsx` / `.css`)— 只動 governance 文件
-- 不自動 write 任何 M-row(新 Meta-Pattern 必 Checkpoint 3 — 動 canonical substantive)
+- 不自行發明產品／UI／UX語意；工程治理 M-row 可依 evidence 自動落地，task／deliverable 明確要求時才加 maximum-assurance independent review
 - 不刪 jsonl 歷史 — 處理後 append 到 `.processed.jsonl`,raw log 保留 grep evidence
-- 不重跑 harvest — harvest 是 stop_harvest_corrections.sh 的責任
+- 不重跑 harvest — harvest 是 stop_passive_logging.sh R2 rule_harvest_corrections()(原 stop_harvest_corrections.sh,已 folded)的責任
 
 ---
 
@@ -33,7 +33,7 @@ description: Process .claude/logs/user-corrections.jsonl — the Stop-hook-harve
 
 ### Phase 0 — Scan + dedup
 
-讀 `.claude/logs/user-corrections.jsonl`。每行格式:
+讀 `$GOVERNANCE_STATE_DIR/user-corrections.jsonl`。若 trusted adapter 未提供安全的 Git-owned runtime state，fail closed 並報告「無可信 correction evidence」，不得回退讀 provider home。每行格式:
 ```json
 {"ts":"...", "session":"...", "count":N, "sample":"unescaped correction text"}
 ```
@@ -42,7 +42,7 @@ description: Process .claude/logs/user-corrections.jsonl — the Stop-hook-harve
 - 同 session 多行 → 只保留 count 最大那行(log 已 per-session dedup,但防萬一)
 - 跨 session 同 `sample` 內容 > 80% similar(levenshtein / token ratio)→ merge
 
-**output**:`.claude/logs/corrections-pending.md`(session-local 不 commit),每條 entry:
+**output**:`$GOVERNANCE_STATE_DIR/corrections-pending.md`(session-local 不 commit),每條 entry:
 ```
 - [2026-04-22 session:abc123] sample: "不是 X,是 Y"  — occurrences: 3
 ```
@@ -53,66 +53,67 @@ description: Process .claude/logs/user-corrections.jsonl — the Stop-hook-harve
 
 | Topic pattern | 應落 home |
 |--------------|----------|
-| 個人偏好 / 工作節奏 / 「我喜歡 X」| `~/.claude/.../memory/feedback_*.md` |
+| 個人偏好 / 工作節奏 / 「我喜歡 X」| `governance/memory/feedback_*.md` |
 | 設計 canonical / 元件行為 / prop API | `packages/design-system/src/**/spec.md`(rationale 段) |
-| 跨元件 meta 規則(「凡 overlay 都必 X」)| CLAUDE.md Meta-Pattern M-row(**必 Checkpoint 3**)|
-| Audit protocol / skill workflow | `.claude/skills/*/references/` |
-| Tool / hook 使用方式 | hook docblock or `.claude/hooks/*.sh` 修行為 |
+| 跨元件 meta 規則(「凡 overlay 都必 X」)| `packages/design-system/ds-canonical/rules/meta-patterns.md` M-row(**必 Gate 3 evidence + authority classification**)|
+| Audit protocol / skill workflow | `packages/design-system/ds-canonical/skills/*/references/` |
+| Tool / hook 使用方式 | `packages/design-system/ds-canonical/hooks/` 的 docblock 或 canonical hook 行為 |
 
 **判斷原則**:先看 sample 是否已有 home — 若 memory 已有相似 entry → 更新既有;無 → 新建。
 
 **output**:`phase1-clusters.md`,每 cluster 含:proposed home / proposed edit text / which jsonl entries subsumed
 
-### ⚠️ Checkpoint 1 — Phase 1 triage
+### Phase 1.5 — Authority classification + triage receipt
 
-向 user present:
+在 `$GOVERNANCE_STATE_DIR` 寫 session-local triage receipt；P0／P1／P2E 不停下等待 user，只有 P2H 於全盤分類後 batch-at-end 提請產品決策：
 ```
 Phase 0 scan 找到 N 條 pending corrections(dedup 後 M 條)。
 Phase 1 cluster:
   - P0(auto-apply)AUTO fixes to memory 現有 entry / spec rationale:X 條
-  - P1(review + apply)新建 memory file / spec rationale 新段:Y 條
-  - P2(STOP)新 M-row / 動 CLAUDE.md canonical substantive:Z 條(需 Checkpoint 3)
+  - P1(engineering review + apply)新建 memory file / engineering spec rationale 新段:Y 條
+  - P2E(AUTO；task／deliverable 明確要求時才加 maximum-assurance independent review)新 engineering M-row / governance substantive:Z 條
+  - P2H(HUMAN-ONLY)會改產品／UI／UX SSOT 且仍有真取捨:K 條
 
-Proceed P0 auto?然後逐一 review P1?P2 分開討論?
+Execution order:P0 → P1 → P2E；P2H 若有則 batch-at-end 一次提請產品決策。
 ```
 
-**Do NOT skip**:P2 動 canonical meaning,per 稽核 vs 執行 分權 必 user sign-off。
+**Do NOT skip authority classification**:canonical substantive 不等於 human gate；不得把 P2E 工程判斷轉交 user。
 
 ### Phase 2 — Apply P0 + P1
 
-**P0**(明確 home + 明確 edit):AUTO edit,commit 前最後 show diff 給 user 一次過目。
+**P0**(明確 home + 明確 edit):AUTO edit，commit 前記錄 diff receipt。
 
-**P1**(新建 memory / spec 新段):one-by-one present → user approve → edit。
+**P1**(新建 memory / engineering spec 新段):由 agent 逐項以 canonical evidence review 後 edit；若內容引入產品／UI／UX SSOT 真取捨，重新分類 P2H。
 
 每次 Edit 後 tsc / lint 無需跑(純 governance 文件),但 MEMORY.md index 若有更新必包含。
 
-### ⚠️ Checkpoint 2 — 新 memory 命名 3-test
+### Gate 2 — 新 memory 命名 3-test
 
-每個新 memory file 過 CLAUDE.md `## 命名必過三重 test`:
+每個新 memory file 過 `packages/design-system/ds-canonical/references/naming-conventions.md` 的命名三重 test:
 1. 既有命名 pattern?
 2. ≥ 2 家 world-class DS idiom?
 3. 跨元件認知衝突?
 
 Fail 任一 → 重名或拆分。
 
-### ⚠️ Checkpoint 3 — P2 新 M-row(動 canonical substantive)
+### Gate 3 — P2 新 M-row(動 canonical substantive)
 
-**STOP**。present 完整 proposal:
+先產完整 evidence package:
 - Correction cluster 原始 samples
 - Proposed M-row 文字
 - World-class benchmark(≥ 3 家 DS,M8 強制)
 - 被吸收的下游 M-row / specific bug / memory entries 清單(M10 下游刪)
 
-User approve 後才 edit CLAUDE.md。
+P2E 由最高 certified capability 依 canonical evidence、tests 與 hard gates 自主收斂後直接 edit `packages/design-system/ds-canonical/rules/meta-patterns.md`；只有 task／deliverable 明確要求 independent review 時才加 distinct-provider review。Exact run 若有 user waiver，記錄 waiver receipt 且不得冒充已做 review；optional review 缺席不得阻擋 P2E。P2H 才在 user 決定產品／UI／UX方向後 edit。Generated provider instruction/view 只能由 adapter materialize，禁止反向手改。
 
 ### Phase 3 — Archive processed entries
 
 處理完畢:
 ```bash
-# Append processed entries to .processed.jsonl(保留歷史 grep)
-cat user-corrections.jsonl >> user-corrections.processed.jsonl
+# 在同一個安全的 $GOVERNANCE_STATE_DIR 內 append processed entries(保留歷史 grep)
+cat "$GOVERNANCE_STATE_DIR/user-corrections.jsonl" >> "$GOVERNANCE_STATE_DIR/user-corrections.processed.jsonl"
 # Truncate main log
-: > user-corrections.jsonl
+: > "$GOVERNANCE_STATE_DIR/user-corrections.jsonl"
 ```
 
 ### Phase 4 — Final report + metric snapshot
@@ -137,7 +138,7 @@ cat user-corrections.jsonl >> user-corrections.processed.jsonl
 - {entries 不適合 codify:過度零散 / scope 不清 / user 已撤回}
 ```
 
-Update `.claude/logs/metric-snapshots.jsonl`:
+Update `$GOVERNANCE_STATE_DIR/metric-snapshots.jsonl`:
 ```json
 {"ts":"...","tag":"codify-corrections-run","processed":N,"p0":X,"p1":Y,"p2":Z}
 ```
@@ -147,7 +148,7 @@ Update `.claude/logs/metric-snapshots.jsonl`:
 ```markdown
 ## Self-improvement capture
 - 新發現 pattern:{某 topic 反覆出現 → 該抽 meta}OR "無"
-- Harvest miss:{stop_harvest_corrections.sh 沒抓到但該抓的 keyword}OR "無"
+- Harvest miss:{stop_passive_logging.sh R2 rule_harvest_corrections()(原 stop_harvest_corrections.sh,已 folded)沒抓到但該抓的 keyword}OR "無"
 - Codify-to-home 公式漂移:{有 topic 判斷多次走錯 home → 更新 Phase 1 判斷表}OR "無"
 ```
 
@@ -157,7 +158,7 @@ Update `.claude/logs/metric-snapshots.jsonl`:
 
 | Skill | Scope |
 |-------|-------|
-| `stop_harvest_corrections.sh`(hook)| 抓 log — 不 codify |
+| `stop_passive_logging.sh` R2 rule_harvest_corrections()(原 stop_harvest_corrections.sh,已 folded)| 抓 log — 不 codify |
 | **本 skill**(`/codify-corrections`) | log → governance 文件 edit |
 | `/knowledge-prune` | governance 文件 prune — 不處理新 correction |
 | `/design-system-audit --deep` Phase 4.5 | chain `/knowledge-prune`;未來可 chain 本 skill |
@@ -170,15 +171,15 @@ Update `.claude/logs/metric-snapshots.jsonl`:
 
 - GitHub CODEOWNERS diff → assignment:本 skill 類似「correction ownership assignment」
 - Linux kernel `Documentation/process/howto.rst`:upstream patches go through maintainers — 我們 correction 也有「送到對的 home」的流程化
-- RFCs / ADRs workflow:新 canonical 走 Checkpoint 3 等同提 ADR
+- RFCs / ADRs workflow:新 canonical 走 Gate 3 evidence；task／deliverable 明確要求時才加 independent review，產品／UI／UX真取捨才升 human decision
 
-本 skill 是本 DS 原創,因為 Claude Code 生態沒有同層級的「session log → governance codify」pipeline。
+本 skill 是本 DS 原創,因為常見 agent coding 生態沒有同層級的「session signal → governance codify」pipeline。
 
 ---
 
 ## Non-goals 重申
 
 - 不改 code
-- 不自動寫新 M-row
+- 不自行發明產品／UI／UX SSOT；工程治理 M-row 可自動寫入並驗證
 - 不刪歷史 log
 - 不跑 harvest(是 hook 責任)

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

@@ -1,6 +1,6 @@
 ---
 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。
+description: User 提出新設計原則 → auto 5-layer artifact generation pipeline。將原則文字自動轉化為 SSOT canonical text + hook scaffold + audit dim + scaffold update + memory entry,依 rule-placement Level 1–9 taxonomy 放入正確 home。對齊 M14 + M19。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
@@ -16,10 +16,10 @@ User mandate「我說一條原則 → 自動轉化產生正確 artifacts 放正
 
 ## Non-goals
 
-- 不直接動既有 canonical without sign-off(改 substantive meaning 走 STOP)
+- 不自行改寫使用者未決定的產品／UI／UX SSOT；工程／治理 canonical implementation 依 Standing Authorization 自動落地
 - 不跳過 M8 benchmark — 任何新 cross-component 原則必 ≥ 3 家世界級對照
-- 不省略 user sign-off checkpoint
-- 不替換 user 判斷 — 模糊原則需要 user 親自釐清
+- 不省略 authority classification 與 evidence receipt
+- 不替換 user 的產品／UI／UX取捨；scope/home/type/hook/audit/release 等工程判斷由 agent 自行決定
 
 ## Workflow(7 phases)
 
@@ -28,38 +28,39 @@ User mandate「我說一條原則 → 自動轉化產生正確 artifacts 放正
 User 提供 principle text。Skill 提取:
 - **Scope**:跨元件 / 單元件 / 跨 layer / governance-only
 - **Type**:Absolute(機械可驗)/ Consistency(對照可驗)/ Judgement(無 mechanical)
-- **Affected homes**(8-home matching):
-  - `CLAUDE.md` 章節?
+- **Affected homes**(依 `design-system-audit/references/rule-placement.md` Level 1–9 taxonomy):
+  - `packages/design-system/ds-canonical/rules/` 或 `references/` 哪個 canonical owner?
   - `*.spec.md` 哪個元件?
   - 新 hook?
   - 新 audit dim?
   - 新 skill?
   - Memory entry?
 
-### Phase 2 — M8 benchmark(STOP if missing)
+### Phase 2 — M8 benchmark(fail closed 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 確認原則是否成熟
+3. 若 < 3 家對照 → 擴大 primary-source research；task／deliverable 明確要求時才加 distinct-provider review。不得把資料不足轉成 user 工程判斷；只有「是否採用無 benchmark 的原創產品／UI／UX原則」是真產品取捨時才 STOP
 
-### Phase 3 — Draft 5 layer artifacts(STOP per layer)
+### Phase 3 — Draft 5 layer artifacts(authority-classified)
 
-每 layer 產 draft + Checkpoint sign-off:
+每 layer 產 draft + evidence，工程 mapping 不逐層等 user:
 
 | Layer | Action |
 |-------|--------|
-| 1. SSOT canonical | 寫 markdown text 到對應 home(CLAUDE.md 章節 / spec.md 段 / references/{topic}.md);包含 rule + Why + How to apply + 世界級 anchor |
+| 1. SSOT canonical | 寫 markdown text 到對應 canonical home(`packages/design-system/ds-canonical/rules/` / `references/`、spec.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 |
+| 3. Hook | 若 Absolute → scaffold `packages/design-system/ds-canonical/hooks/check_{topic}.sh` 含 P0/P1 detection logic + 7-Q self-check 模板，並更新 canonical `registrations.json` |
+| 4. Audit dim | 加 dim N 到 `packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md` + `references/audit-prompts.md`(periodic verify) |
+| 5. Memory | 寫 `governance/memory/project_{topic}_{date}.md` + 更新 `governance/memory/MEMORY.md` index；provider cache 只由 `npm run sync-memory` 投影 |
 
-**每 layer 都 Checkpoint user sign-off**:
+**每 layer 都記錄 review receipt**:
 ```
 Phase 3 Layer N draft ready:
 {draft content}
-Approve? Edit? Skip?
+Authority: ENGINEERING-AUTO | PRODUCT-UIUX-DECISION
+Evidence / tests / rollback: {...}
 ```
 
 ### Phase 4 — Auto-generate scaffold update
@@ -68,7 +69,7 @@ Approve? Edit? Skip?
 
 ### 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)。
+若 Layer 3 hook 建立 → scaffold `packages/design-system/ds-canonical/hooks/tests/test_{topic}.sh` 含 ≥ 5 smoke tests(silent skip / canonical compliance / drift block / rationale escape / per-trait verify)。Provider hook config/view 由 adapter materialize，禁止手改。
 
 ### Phase 6 — Apply + verify(分組 commit)
 
@@ -95,23 +96,23 @@ Per layer 一個 commit:
 - 跳過的 layer + rationale: {if any}
 ```
 
-更新 `.claude/logs/codified-principles.jsonl` log:
+更新 `$GOVERNANCE_STATE_DIR/codified-principles.jsonl` runtime log(lazy-create on first run；只在 trusted telemetry opt-in 且 state root 位於 Git-owned `<git-dir>/governance-runtime/` 時建立；provider home 不得作 fallback):
 ```json
 {"date":"2026-04-26", "principle":"...", "scope":"...", "layers":["ssot","hook","audit","scaffold","memory"], "commits":[...]}
 ```
 
-## Checkpoints(禁止跳)
+## Authority gates(禁止跳 classifier，禁止 blanket user gate)
 
-### ⚠️ Checkpoint 1 — Phase 1 parse
-User 親自確認 scope / type / affected homes 是否正確,禁 AI 單方面決定。
+### Gate 1 — Phase 1 parse
+Scope / type / affected homes 是工程 mapping，由 agent 依 canonical 自行決定。只有原則文字本身對產品／UI／UX語意有多種合理解讀且會改 SSOT，才請 user 釐清。
 
-### ⚠️ Checkpoint 2 — Phase 2 benchmark
-< 3 家世界級對照 → STOP,跟 user 確認是否走 OG-only(原創原則,需 rationale 文檔)。
+### Gate 2 — Phase 2 benchmark
+< 3 家世界級對照 → 繼續 primary-source research，證據仍不足就不 codify 並明列 benchmark gap；只有 task／deliverable 明確要求 independent review 且 peer 證據不可得時才標 `REVIEW-BLOCKED`。只有 OG-only 是否成為產品／UI／UX原則的選擇交給 user，工程治理原則由 evidence + security/hard gates 決定。
 
-### ⚠️ Checkpoint 3 — Phase 3 per-layer
-每 layer draft 都過 user。SSOT 是 canonical 改變,動 substantive meaning → 必 sign-off。
+### Gate 3 — Phase 3 per-layer
+每 layer 都過 tests／rollback check；task／deliverable 明確要求時才把 independent review 列為 required。工程 canonical substantive 直接執行，只有產品／UI／UX SSOT 真取捨停下。
 
-### ⚠️ Checkpoint 4 — Phase 6 verify
+### Gate 4 — Phase 6 verify
 任何 layer commit 後 tsc / hook test fail → 回該 phase 修,**不繞過**。
 
 ## 與既有 skills 分工
@@ -127,10 +128,10 @@ User 親自確認 scope / type / affected homes 是否正確,禁 AI 單方面決
 
 ## 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
+- `governance/memory/MEMORY.md` — repository-owned index of codified principles（SSOT）
+- `$GOVERNANCE_STATE_DIR/codified-principles.jsonl` — non-authoritative execution log(lazy-create on first run,見 Phase 7)
+- `packages/design-system/ds-canonical/skills/design-system-audit/references/rule-placement.md` — home 識別 rules
+- `packages/design-system/ds-canonical/rules/meta-patterns.md` M14 / M19 — 上游 pipeline rules
 
 ## 範例呼叫
 
@@ -140,12 +141,12 @@ 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 提議擴充而非新增)
+   - SSOT:`packages/design-system/ds-canonical/rules/ui-development.md`「元件 Props 命名」 + form spec
+   - Hook:`packages/design-system/ds-canonical/hooks/check_form_dual_mode.sh`(未實作;此為 5-layer 產物範例 — audit-only via dim,無 write-time hook)偵測 missing pair
+   - Audit dim:Dim 31「Dual-mode coherence」(已存在 Dim 26 — 依 evidence 擴充既有 dim，不重複新增)
    - Scaffold:`/new-component` Phase 4 加 dual-mode template
    - Memory:`project_form_dual_mode_2026_04_26.md`
-4. Per-layer Checkpoint
+4. Per-layer evidence + authority receipt
 5. Hook test + audit prompt
 6. Apply + tsc + verify
 7. Capture

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Pre-merge quality gate for new or significantly refactored design-system components. Walks through Spec / Code / Stories / Ship checklist (35 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
@@ -20,7 +20,7 @@ Purpose: 元件進 `packages/design-system/src/components/` 前的最終 checkli
 
 - 元件 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`)
+- 已讀相關 path-scoped rules(`packages/design-system/ds-canonical/rules/spec-rules.md` / `packages/design-system/ds-canonical/rules/ui-development.md`(含 Tailwind / Token 命名 / Props 命名 / shadcn 元件規範) / `packages/design-system/ds-canonical/rules/story-rules.md`)
 
 ## Workflow
 
@@ -34,7 +34,7 @@ Purpose: 元件進 `packages/design-system/src/components/` 前的最終 checkli
 
 走 **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` → 高風險漂移點)。
+cva `defaultVariants` 異動 → 強制 grep 該元件所有檔案確認三方同步(見 `packages/design-system/ds-canonical/skills/story-writing/references/anatomy-standard.md` → 高風險漂移點)。
 
 ### Phase 3 — Stories 審查
 
@@ -44,7 +44,7 @@ cva `defaultVariants` 異動 → 強制 grep 該元件所有檔案確認三方
 
 ### Phase 4 — Ship 審查(最後驗證)
 
-走 **Ship section**(6 項):
+走 **Ship section**(checklist 4 項 = 35 項總數的 Ship 份額;下列 5-7 為 checklist 外加掛的 mechanical gate,不計入 35):
 1. `npm run storybook` 本地渲染正常
 2. `npx tsc -b` 無錯(**禁用 `--noEmit`**,root tsconfig `files: []` silent pass)
 3. import 路徑 `@/design-system/...`
@@ -53,7 +53,7 @@ cva `defaultVariants` 異動 → 強制 grep 該元件所有檔案確認三方
 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)
+### Phase 4.5 — 進階稽核 6 維(強制 chain,對齊 shared governance `# 稽核 canonical` M6)
 
 **這是 stakeholder-gate,不能跳**。元件 merge = stakeholder-visible 產出,**必過進階模式 6 維**(非高效)。
 
@@ -68,35 +68,35 @@ cva `defaultVariants` 異動 → 強制 grep 該元件所有檔案確認三方
 
 **執行步驟**:
 
-1. `npm run visual-audit -- --scope=component:{Name}`(D5 Layer A:WCAG / 幾何 assertion / retina screenshot)
+1. `npm run visual-audit -- --scope=component:{Name}`(D5 Layer A:WCAG / 幾何 assertion / 1x snapshot,`--retina` opt-in debug)
 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 節
+6. **D6 真 scan**:讀 `packages/design-system/ds-canonical/skills/design-system-audit/references/principle-audit-protocol.md` 對該元件 + 其 spec 跨指的 kin specs 跑 4 子維(合理 / 一致 / 無矛盾 / 完整);先讀「常見 FP 記憶」節避免誤報
+7. 彙整 6 維 findings並套用 shared governance authority classifier：**改變產品／UI／UX SSOT 且仍有真取捨 → P2H/STOP；對齊既有 canonical 或純工程／治理 remediation → P2E/AUTO**
+8. **Self-improvement capture**(強制):Phase 結束寫「新 FP / 新 pattern / user 糾正」—見 shared governance `# 治理 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 點)
+### Phase 5 — 簽結(receipt，不是 approval checkpoint)
 
 全部打勾後,回報 user:
-- 「元件 {Name} 已過 quality gate,46 項全綠(含 Layer A visual)+ Layer B AI 視覺判斷通過」
+- 「元件 {Name} 已過 quality gate,35 項全綠(含 Layer A visual)+ Layer B AI 視覺判斷通過」
 - 列出 Phase 1-4.5 各 section 打勾結果
-- 列出 `snapshots/report.json` 摘要(contrast / geometry violation 數 = 0)
+- 列出 `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/report.json` 摘要(contrast / geometry violation 數 = 0)
 - 若任一 phase 有合理例外(documented 在 spec),列出例外清單
 
-**STOP 條件**:任一項不過 + 原因不清楚 → 停下問 user,不默默放行。**Phase 4.5 Layer A 有 violation 絕不放行**。
+**Fail-closed 路由**:任一項不過都不得默默放行。純工程／治理失敗依 Engineering Decision Policy、tests 與 hard gates 自行釐清並 remediation；依既定重試仍無法收斂則回報 technical blocker，不把工程選擇轉問 user。只有改變產品／UI／UX SSOT 且仍有真實選擇或取捨才 P2H/STOP。**Phase 4.5 Layer A 有 violation 絕不放行**。
 
 ## References
 
-- `references/checklist.md` — 完整 45 項 checklist(Spec 12 / Code 13 / Stories 6 / Ship 4 + 各項的 CLAUDE.md pointer)
+- `references/checklist.md` — 完整 35 項 checklist(Spec 12 / Code 13 / Stories 6 / Ship 4 + 各項的 shared-governance 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 級)
+- `packages/design-system/ds-canonical/skills/design-system-audit/` — 本 skill focus 在單元件進 DS 的 gate;design-system-audit 是系統級 full-dim sweep(per design-system-audit SSOT),兩者互補
+- `packages/design-system/ds-canonical/skills/story-writing/` — Phase 3 story 深審可 chain 進去
+- retired canonical hook `pre_edit_spec_check.sh`(改靠 M3 mindset #3「改一處看三處」)— 編輯 tsx 前提醒讀 spec(session 級)

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

@@ -1,4 +1,4 @@
-# 元件完成 Checklist(完整 45 項)
+# 元件完成 Checklist(完整 35 項)
 
 每個元件在進入 design-system 前必須逐項對照。這是品質閘門,不可跳過。
 
@@ -7,7 +7,7 @@
 ---
 
 ## Phase 1 — Spec(`{name}.spec.md`)
-> 規則定義:`.claude/rules/spec-rules.md`
+> 規則定義:`packages/design-system/ds-canonical/rules/spec-rules.md`
 
 - [ ] 元件定位一句話(是什麼 / 不是什麼)
 - [ ] 定位段落宣告實作基礎(基於 Radix X / cmdk / sonner / native / 自建 + 理由)
@@ -25,7 +25,7 @@
 ---
 
 ## Phase 2 — Code(`{name}.tsx`)
-> 規則定義:`.claude/rules/ui-development.md`(含「shadcn 元件規範」/「Tailwind 5 條核心」/「Token 命名 4 條硬規則」/「元件 Props 命名」)
+> 規則定義:`packages/design-system/ds-canonical/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)
@@ -38,19 +38,19 @@
 - [ ] 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` → 高風險漂移點)
+- [ ] 若修改 cva `defaultVariants`,已同步 spec / docblock / anatomy 三方(見 `packages/design-system/ds-canonical/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)
+> 規則定義:`packages/design-system/ds-canonical/skills/story-writing/`(完整 workflow) + `packages/design-system/ds-canonical/rules/story-rules.md`(high-level)
 
-- [ ] 範例選擇原則的自我檢查清單全部打勾(詳見 `.claude/skills/story-writing/references/self-check.md`)
+- [ ] 範例選擇原則的自我檢查清單全部打勾(詳見 `packages/design-system/ds-canonical/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」)
+- [ ] Storybook title 對齊命名規則;元件放對 `Components/` vs `Internal/`(見 `packages/design-system/ds-canonical/rules/story-rules.md` → 「Internal vs Components 三 test」)
 - [ ] 每個重要規則有正確範例;常見誤用有錯誤範例(對比呈現)
 
 ---
@@ -58,7 +58,7 @@
 ## Phase 4 — Ship(上線前)
 
 - [ ] `npm run storybook` 本地確認所有 stories 正常渲染
-- [ ] `npx tsc --noEmit` 無錯誤
+- [ ] `npx tsc -b` 無錯(**禁 `--noEmit`**,root tsconfig `files: []` silent pass;型別 surface 改動加跑 `npm run build:lib`,對齊 `packages/design-system/ds-canonical/rules/self-verify.md` Post-edit)
 - [ ] Import 路徑正確(`@/design-system/...`)
 - [ ] 若為 internal primitive 或 shadcn passthrough,分類標註正確