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

package/ds-canonical/adapters/claude-settings-base.json

@@ -0,0 +1,169 @@
+{
+  "permissions": {
+    "allow": [
+      "Edit",
+      "Skill(knowledge-prune)",
+      "Skill(design-system-audit)",
+      "Skill(ensure-canonical)",
+      "Skill(propose-options)",
+      "Skill(scan-similar-bugs)",
+      "Skill(component-quality-gate)",
+      "Skill(story-writing)",
+      "Skill(visual-audit)",
+      "Skill(ux-audit)",
+      "Skill(performance-audit)",
+      "Skill(code-quality-audit)",
+      "Skill(governance-health)",
+      "Skill(story-auto-compile-migrate)",
+      "Skill(prototype)",
+      "Skill(delivery-handoff)",
+      "Skill(product-ui-audit)",
+      "Skill(new-component)"
+    ],
+    "ask": [
+      "Bash(claude auth login*)",
+      "Bash(claude login*)",
+      "Bash(gh auth login*)",
+      "Bash(gh auth refresh*)",
+      "Bash(npm access grant *)",
+      "Bash(npm access revoke *)",
+      "Bash(npm access set *)",
+      "Bash(npm adduser*)",
+      "Bash(npm login*)",
+      "Bash(npm org set *)",
+      "Bash(npm org rm *)",
+      "Bash(npm owner add *)",
+      "Bash(npm owner rm *)",
+      "Bash(npm profile *2fa*)",
+      "Bash(docker login*)",
+      "Bash(aws configure*)",
+      "Bash(aws sso login*)",
+      "Bash(gcloud auth *)",
+      "Bash(az login*)",
+      "Bash(netlify login*)",
+      "Bash(vercel login*)"
+    ],
+    "deny": [
+      "Bash(gh auth token*)",
+      "Bash(gh secret set*)",
+      "Bash(gh secret delete*)",
+      "Bash(gh variable set*)",
+      "Bash(gh variable delete*)",
+      "Bash(git credential *)",
+      "Bash(npm token *)",
+      "Bash(ssh-add*)",
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)",
+      "Read(~/.aws/**)",
+      "Read(~/.azure/**)",
+      "Read(~/.config/gcloud/**)",
+      "Read(~/.docker/**)",
+      "Read(~/.git-credentials)",
+      "Read(~/.gnupg/**)",
+      "Read(~/.kube/**)",
+      "Read(~/.netrc)",
+      "Read(~/.npmrc)",
+      "Read(~/.pypirc)",
+      "Read(~/.ssh/**)",
+      "Bash(git reset *)",
+      "Bash(git clean *)",
+      "Bash(git branch -D *)",
+      "Bash(git tag -d *)",
+      "Bash(git commit --amend *)",
+      "Bash(git checkout *)",
+      "Bash(git restore *)",
+      "Bash(git push *--force*)",
+      "Bash(git push -f *)",
+      "Bash(gh api *--method DELETE*)",
+      "Bash(gh api *-X DELETE*)",
+      "Bash(gh issue delete *)",
+      "Bash(gh release delete *)",
+      "Bash(gh repo delete *)",
+      "Bash(gh run delete *)",
+      "Bash(npm unpublish *)",
+      "Bash(npm deprecate *)",
+      "Bash(rm *)",
+      "Bash(find * -delete *)",
+      "Bash(dd *)",
+      "Bash(mkfs *)",
+      "Bash(shred *)",
+      "Bash(*--dangerously-skip-permissions*)",
+      "Bash(*--permission-mode bypassPermissions*)",
+      "Bash(*--dangerously-bypass-approvals-and-sandbox*)"
+    ],
+    "defaultMode": "acceptEdits",
+    "disableBypassPermissionsMode": "disable"
+  },
+  "sandbox": {
+    "enabled": true,
+    "failIfUnavailable": false,
+    "autoAllowBashIfSandboxed": true,
+    "allowUnsandboxedCommands": false,
+    "network": {
+      "allowedDomains": [],
+      "deniedDomains": [],
+      "allowUnixSockets": [],
+      "allowAllUnixSockets": false,
+      "allowLocalBinding": true,
+      "allowMachLookup": []
+    },
+    "filesystem": {
+      "allowWrite": [],
+      "denyWrite": [],
+      "denyRead": [],
+      "allowRead": []
+    },
+    "credentials": {
+      "files": [
+        { "path": "./.env", "mode": "deny" },
+        { "path": "./.env.*", "mode": "deny" },
+        { "path": "./secrets/**", "mode": "deny" },
+        { "path": "~/.aws/config", "mode": "deny" },
+        { "path": "~/.aws/credentials", "mode": "deny" },
+        { "path": "~/.azure/**", "mode": "deny" },
+        { "path": "~/.config/gcloud/**", "mode": "deny" },
+        { "path": "~/.docker/config.json", "mode": "deny" },
+        { "path": "~/.git-credentials", "mode": "deny" },
+        { "path": "~/.gnupg/**", "mode": "deny" },
+        { "path": "~/.kube/config", "mode": "deny" },
+        { "path": "~/.netrc", "mode": "deny" },
+        { "path": "~/.npmrc", "mode": "deny" },
+        { "path": "~/.pypirc", "mode": "deny" },
+        { "path": "~/.ssh/**", "mode": "deny" }
+      ],
+      "envVars": [
+        { "name": "ANTHROPIC_API_KEY", "mode": "deny" },
+        { "name": "AWS_ACCESS_KEY_ID", "mode": "deny" },
+        { "name": "AWS_CONTAINER_AUTHORIZATION_TOKEN", "mode": "deny" },
+        { "name": "AWS_CONTAINER_CREDENTIALS_FULL_URI", "mode": "deny" },
+        { "name": "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI", "mode": "deny" },
+        { "name": "AWS_SECRET_ACCESS_KEY", "mode": "deny" },
+        { "name": "AWS_SESSION_TOKEN", "mode": "deny" },
+        { "name": "AWS_WEB_IDENTITY_TOKEN_FILE", "mode": "deny" },
+        { "name": "AZURE_CLIENT_CERTIFICATE_PATH", "mode": "deny" },
+        { "name": "AZURE_CLIENT_SECRET", "mode": "deny" },
+        { "name": "AZURE_FEDERATED_TOKEN_FILE", "mode": "deny" },
+        { "name": "CLAUDE_CODE_OAUTH_TOKEN", "mode": "deny" },
+        { "name": "DOCKER_AUTH_CONFIG", "mode": "deny" },
+        { "name": "GH_ENTERPRISE_TOKEN", "mode": "deny" },
+        { "name": "GH_TOKEN", "mode": "deny" },
+        { "name": "GITHUB_APP_PRIVATE_KEY", "mode": "deny" },
+        { "name": "GITHUB_TOKEN", "mode": "deny" },
+        { "name": "GOOGLE_APPLICATION_CREDENTIALS", "mode": "deny" },
+        { "name": "GOOGLE_GHA_CREDS_PATH", "mode": "deny" },
+        { "name": "NETLIFY_AUTH_TOKEN", "mode": "deny" },
+        { "name": "NODE_AUTH_TOKEN", "mode": "deny" },
+        { "name": "NPM_TOKEN", "mode": "deny" },
+        { "name": "SIGSTORE_ID_TOKEN", "mode": "deny" },
+        { "name": "SSH_AUTH_SOCK", "mode": "deny" },
+        { "name": "VERCEL_TOKEN", "mode": "deny" }
+      ],
+      "allowPlaintextInject": false
+    },
+    "enableWeakerNestedSandbox": true,
+    "enableWeakerNetworkIsolation": false,
+    "allowAppleEvents": false,
+    "excludedCommands": []
+  }
+}

package/ds-canonical/commands/README.md

@@ -1,26 +1,21 @@
-# .claude/commands/ Charter
+# .claude/commands/ Legacy charter
 
-## 這裡只收:**one-shot slash commands**(無 phase,單次 action)
+Claude Code 已將 custom commands 併入 skills，新增 workflow 一律寫入 canonical owner `packages/design-system/ds-canonical/skills/<name>/SKILL.md`；provider discovery view 由 build graph 生成，以便 Claude、Codex 與其他 Agent Skills runtime 共用同一 SSOT。
 
-每個 command 一檔 `.md`,用戶打 `/<name>` 直接觸發。**vs Skill**:skill 是多 phase workflow + user CP;command 是單次動作無 CP。
+此目錄只保留舊 consumer 的相容 pointer；新的 `/<name>` 由同名 skill 提供。
 
-## 當前居民(1 pilot,2026-04-24)
+## 當前居民(0)
 
-| Command | 觸發 | 用途 |
-|---------|------|------|
-| `/gov-status` | user 輸入 `/gov-status` | 一次印 governance health snapshot(行數/retire rate/logs freshness/drift/pending)—不走 skill workflow,不要 CP,純 dump |
+原 `/gov-status` 已改為 `packages/design-system/ds-canonical/skills/governance-status/SKILL.md`，並移除主機絕對路徑與 Claude-only 假設。
 
 ## 這裡**不收**(反例)
 
 | 疑似要放這但其實不是 | 正確去處 | 為什麼 |
 |---------------------|---------|--------|
-| 多 phase + user 決策 | `.claude/skills/` | skill 管 phase + CP |
-| 機械 tool-event 檢查 | `.claude/hooks/` | hook 是 pre/post tool 觸發,不是 user 觸發 |
+| 任何可重複 workflow(單步或多階段) | `packages/design-system/ds-canonical/skills/` | Agent Skills 是跨 provider 共用面 |
+| 機械 tool-event 檢查 | `packages/design-system/ds-canonical/hooks/` | hook 是 pre/post tool 觸發,不是 user 觸發(`.claude/hooks/` 只是 generated view)|
 | 需要 isolated context / scoped tools | `.claude/agents/` | agent 是 AI worker,command 是 quick action |
 
-## 新 command criteria
+## 相容保留原則
 
-1. **< 10 秒完成**(不是 workflow)
-2. **無 user CP**(有決策點 = skill)
-3. **輸出簡潔**(一段 markdown / 表)
-4. **可重複 run**(每次同 behaviour)
+只有現存外部 consumer 仍固定呼叫 `.claude/commands/<name>.md` 時才可暫留 legacy command，並必須只是同名 skill 的 thin pointer，不得擁有另一份 substantive workflow。

package/ds-canonical/fork/AGENTS.md

@@ -0,0 +1,110 @@
+# Product consumer AI governance (provider-neutral)
+
+> **Generated view**: upstream `build-fork-governance.mjs` publishes this source as `AGENTS.md`; never
+> edit the generated copy. Claude loads it via `CLAUDE.md`, Codex and other agents load it directly.
+
+## Authority and trust boundary
+
+- This repository builds a product against exact versions of `@qijenchen/design-system` and
+  `@qijenchen/storybook-config`; it never authors or publishes them.
+- Merge enforcement is protected `main` requiring exactly one `Verify consumer` check, which runs the
+  locked install, typecheck, import lint, and build against the exact candidate head.
+- Native Claude/Codex hooks are fast feedback only; hookless operation is judged by the same hooks-off
+  checker. Hook commands scrub inherited startup injection before repository launchers, and the provider
+  host stays an external trust boundary — 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 never replaces or weakens upstream controls.
+- Never install a mutable tag or semver range for internal packages. Upgrades are reviewed pull
+  requests pinning an exact version with the regenerated lock/adapters.
+<!-- canonical-decision-authority:start -->
+**Decision／Engineering Authority**:user 只拍板產品／UI／UX SSOT 真取捨及可感知／產品語意變更（behavior/interaction/IA/visual/token/layout/content/a11y/canonical rules）；核准 = user 在對話中對 exact target + choice 說可（**「我說可以就是可以，就是授權」— user 2026-08-04 verbatim**；最新一則 user 訊息的明確 blanket 授權即核准當下 pending 的 exact 提案）。operation digest 為可選佐證——有引且相符可加強、有引但不符 fail-closed、未引不阻擋（強制引 digest 屬已拆除的 per-PR 簽章同族儀式，835b519e 先例）。引用/條件/舊 scope/跨 target 無效。其餘工程/external writes 皆 Standing Authorization AUTO，含已核准 UI／UX 實作/機械 generation/sync 與 source→commit/PR/merge→canonical `infra/governance/release-workflow.json` 的 `pr-checks → merge → publish → readback → consumer`；依 frozen scope、SSOT、required checks、security、least privilege、rollback/readback 收斂，不逐 milestone 重問。Deep Audit 必須在單一 branch／PR 完成 remediation 與 local/CI candidate validation，禁止把 immutable publish 當 iteration/test loop，每次 audit 最多一次 final release；只有另有 evidence ref 綁定 incident ID、failure class、published version 的 post-publish blocker 或 security incident 才可額外 release。Certification、rollout、staged rollout、preview/canary 與 independent review 是明確要求時的附加 assurance，不得進入標準 five-step release blocking graph；peer 不可用只阻擋明確要求的 independent-review claim。
+
+**Visual baseline**:user 對 exact image set／UI／UX 語意說「可以改」即拍板；Agent 自動 apply/generate/test/commit/PR/CI/merge，禁再核准/key enrollment/簽章。僅 user 明確要求 independent cryptographic review 才啟用 `visual-baseline-review-policy.json`，否則不阻擋。
+
+**Human-only boundaries**:僅 login/MFA/OAuth/owner/billing、缺 credential reference（只問 vault/Environment/Secret Manager reference，禁 secret）、plan 外付費、法律/帳號/組織權限/商業承諾及上述產品決策。Agent 完成唯一方案/preflight，只問一個 exact action，readback 後續跑；technical failure fail-closed，非 human decision。Release 常見的 login/MFA/OAuth/credential reference 完成後一律 AUTO resume，不另問核准。
+<!-- 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 (Polaris, Material, Atlassian, Ant, Carbon, 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 docs move together. A DS defect is
+   reported upstream with a minimal reproduction; never patch `node_modules`.
+4. **Use real product scenarios**: examples show 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 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; the nearest shipped
+`*.spec.md` and token docs under `node_modules/@qijenchen/design-system/src/`; a nearest shipped story
+or real product precedent; and any product-specific exception with 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
+
+Run every check this product has and report its real outcome. The minimum repository-wide contract is
+`npm run governance:check` (exact installed, hooks-off authority), `npm run typecheck`, `npm run build`,
+product lint/test/a11y scripts when present, and 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.
+- An explicitly requested independent-review deliverable needs a distinct certified peer and immutable
+  read-only evidence, or the report claims `REVIEW-BLOCKED`. Peer availability never blocks ordinary
+  engineering or the standard five-step release. Product review cannot authorize DS/template/release
+  changes; route reusable defects upstream.
+
+## Git and release flow
+
+- The upstream design-system authority owns the machine-readable release SSOT at
+  `infra/governance/release-workflow.json`: `pr-checks → merge → publish → readback → consumer`. Every
+  engineering step is AUTO; only an unresolved product/UI/UX SSOT choice is ASK. Login, MFA, OAuth, or a
+  missing credential reference pauses only the affected action, then execution resumes AUTO.
+- One task uses one working branch and one PR into protected `main`; never direct-push `main`.
+- The required `Verify consumer` check, conversations, and protected-main exact readback must be clear;
+  then merge and verify under Standing Authorization — no self-approval or chat trigger. Preview, a11y,
+  visual, canary, and independent-peer evidence are scheduled or optional unless the user explicitly
+  requests them, and never block the standard release by default.
+- Product repos never publish the DS; exact-version upgrade PRs merge after `Verify consumer` passes.
+
+## Pilot and upstream feedback
+
+This product may serve as a canary for the DS/product template. When a failure is reusable: preserve a
+minimal reproduction and evidence; classify the owner as product, DS, template, governance corpus, or
+deployment infrastructure; fix the canonical owner first; release an immutable upstream version;
+upgrade by exact-version PR and rerun `Verify consumer`; then remove any temporary workaround.
+
+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=4; assumptionFingerprint=sha256:45202f237adbed348e84e4979ac466eb73182b7c790475672b99a7b158317a33; 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**。
+
+**對齊**:
+- AGENTS.md mindset #6「大原則吸收瑣碎」+ `node_modules/@qijenchen/design-system/ds-canonical/rules/meta-patterns.md` 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**(AGENTS.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。

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

@@ -0,0 +1,71 @@
+---
+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。
+---
+
+<!-- _generated: canonical provider skill projection; source: skills/code-quality-audit/SKILL.md; provider: codex; do not edit this adapter view. -->
+
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+
+# 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(tsx SSOT = `npm run typecheck && npm run build && npm run governance:check` + the installed immutable governance checker;the installed immutable governance checker 僅管治理 md,數字精神一致非同一 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 防線(the installed immutable governance checker + the installed immutable governance checker)層負責(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**:`npm run typecheck && npm run build && npm run governance:check`(P0 violation → exit 1)
+
+## Workflow
+
+1. Run `npm run typecheck && npm run build && npm run governance:check`
+2. Triage findings into P0 / P1 / P2
+3. Auto-fix trivial(unused imports,trivial `any` casts with obvious type)
+4. 依 shared governance 的 Decision Authority classifier 分類並處理:
+   - File-size P0 的 component architectural split、circular-dependency 重組、proper type
+     與 long-function remediation 都是工程決策，依 Standing Authorization 自主完成並驗證。
+   - 只有修法會改變 public component semantics、產品 workflow、interaction 或其他產品／
+     UI／UX SSOT，且證據收斂後仍有真實取捨時，才停下取得 exact target-bound decision。
+   - 無法分類時 fail closed 並補 source/evidence；task／deliverable 明確要求時才加
+     independent review，不得用泛用 user approval 代替工程判斷。
+
+## 禁止
+
+- 禁 silent 吞 `any`(必加 `// any-allow: {rationale}`)
+- Dead export 若只是 implementation residue，依 usage/public-surface evidence 自主移除；若會
+  改變 public component semantics，依 authority classifier 判定是否存在真正 UI/UX 取捨。
+- Long function 依 tests、public API 與行為不變證據自主重構；禁無證據硬拆。
+
+## 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 the installed immutable governance checker → the installed immutable governance checker | PostToolUse Edit/Write on src/ — 只跑 any + file-size(quick);原 check_code_quality.sh folded(2026-05-13 dispatcher consolidation)|
+
+## References
+
+- `npm run typecheck && npm run build && npm run governance:check` — 實作
+- the installed immutable governance checker(經 canonical post-edit dispatcher chain)— per-edit lite check
+- 相關:token 防線 the installed immutable governance checker + the installed immutable governance checker(正交 — token 紀律 vs code 紀律)