universal-dev-standards 5.1.0-beta.6 → 5.1.0

package/bundled/ai/standards/frontend-design-standards.ai.yaml

@@ -0,0 +1,305 @@
+# Frontend Design Standards - AI Optimized
+# Source: core/frontend-design-standards.md
+# Based on: DEC-029 (awesome-design-md, MIT), DEC-030 (OpenAI Frontend Guide)
+# Version: 1.0.0
+
+id: frontend-design-standards
+meta:
+  version: "1.0.0"
+  updated: "2026-04-13"
+  source: core/frontend-design-standards.md
+  description: |
+    DESIGN.md 前端設計標準：9 段結構、語義色彩 token、字體角色、
+    間距比例、UI 硬性約束與 anti-pattern 清單。
+    適用所有含前端介面的專案。
+
+# DESIGN.md 必填 9 段結構
+design_md_sections:
+  - id: visual-theme
+    name: Visual Theme & Mood
+    required: true
+    fields:
+      theme: "一行風格描述（例：Minimal, professional, data-dense）"
+      mood: "情感品質（例：Calm, focused, trustworthy）"
+      inspiration: "參考產品或設計風格（例：Linear, Stripe dashboard）"
+      dark_mode: "primary | secondary | unsupported"
+
+  - id: color-palette
+    name: Color Palette
+    required: true
+    description: "語義色彩 token 系統。所有 5 個核心 token 均為必填。"
+    required_tokens: [background, surface, primary-text, muted-text, accent]
+    optional_tokens: [error, warning, success, border, overlay]
+
+  - id: typography
+    name: Typography
+    required: true
+    description: "字體家族與排版角色層次。最多 2 個字體家族。"
+    required_roles: [display, headline, body, caption]
+    constraint: "max_font_families: 2"
+
+  - id: component-styling
+    name: Component Styling
+    required: true
+    description: "UI 元件視覺規則：邊框圓角、按鈕、輸入框、卡片"
+    required_fields: [border_radius_scale, button_variants, input_styling, card_styling]
+
+  - id: layout-spacing
+    name: Layout & Spacing
+    required: true
+    description: "間距比例（8px 基底，7 個步進值）與網格定義"
+    required_tokens: [space-1, space-2, space-3, space-4, space-5, space-6, space-8]
+    note: "space-7 不存在（刻意跳過以維持視覺節奏）"
+
+  - id: depth-shadow
+    name: Depth & Shadow System
+    required: true
+    description: "陰影層次系統，至少 3 個 elevation 層級"
+    min_elevation_levels: 3
+
+  - id: design-guidelines
+    name: Design Guidelines & Anti-patterns
+    required: true
+    description: "設計規則與禁止模式清單（約束式 prompting 核心）"
+    required_subsections:
+      - ui_hard_constraints: "至少 4 條硬性規則"
+      - anti_patterns: "至少 5 條禁止模式"
+
+  - id: responsive
+    name: Responsive Behavior
+    required: true
+    description: "斷點定義與響應式規則，Mobile-first 必填"
+    min_breakpoints: 3
+    required_approach: mobile-first
+
+  - id: agent-prompt-refs
+    name: Agent Prompt References
+    required: true
+    description: "AI Agent 快速讀取的設計意圖摘要"
+    required_fields: [style_summary, key_constraints, tone]
+
+# 語義色彩 5 個必要 token
+semantic_color_tokens:
+  required:
+    background:
+      role: "頁面/App 底色"
+      example_dark: "#0A0A0A"
+      example_light: "#FFFFFF"
+    surface:
+      role: "卡片、面板、Modal 底色"
+      example_dark: "#1A1A1A"
+      example_light: "#F9FAFB"
+    primary-text:
+      role: "主要正文文字"
+      example_dark: "#F5F5F5"
+      example_light: "#111827"
+    muted-text:
+      role: "次要文字、placeholder"
+      example_dark: "#888888"
+      example_light: "#6B7280"
+    accent:
+      role: "CTA 按鈕、連結、強調色"
+      note: "全站只能有 1 個 accent 色，禁止多個強調色"
+      example: "#6366F1"
+  naming_convention: kebab-case
+  format: hex_with_alpha_optional
+
+# 字體角色 4 個必要角色
+typography_roles:
+  required:
+    display:
+      size: "48px+"
+      weight: 700
+      line_height: 1.1
+      usage: "英雄標題、Splash 文字"
+    headline:
+      size: "24–32px"
+      weight: 600
+      line_height: 1.3
+      usage: "區段標題、卡片標題"
+    body:
+      size: "16px"
+      weight: 400
+      line_height: 1.6
+      usage: "段落、主要內容"
+    caption:
+      size: "12–14px"
+      weight: 400
+      line_height: 1.4
+      usage: "標籤、Metadata、輔助說明"
+  constraint:
+    max_font_families: 2
+    note: "display + headline 可共用一個字體家族；body + caption 共用另一個（或相同）"
+
+# 間距比例（8px 基底，7 個步進值）
+spacing_scale:
+  base: 8
+  tokens:
+    space-1: 4px
+    space-2: 8px
+    space-3: 16px
+    space-4: 24px
+    space-5: 32px
+    space-6: 48px
+    space-8: 64px
+  note: "space-7 不存在（刻意跳過）。所有元件間距必須使用這些 token，不得使用任意像素值。"
+
+# UI 硬性約束清單（約束式 prompting）
+ui_hard_constraints:
+  - id: single-h1
+    rule: "每頁最多 1 個 H1"
+    rationale: "清晰的內容層次，避免語義模糊"
+  - id: max-sections
+    rule: "頁面區段不超過 6 個"
+    rationale: "防止認知過載"
+  - id: max-font-families
+    rule: "字體家族最多 2 個"
+    rationale: "視覺一致性"
+  - id: single-accent
+    rule: "強調色最多 1 個，禁止混用多個 accent 色"
+    rationale: "防止視覺雜訊"
+  - id: max-nesting
+    rule: "視覺巢狀最多 3 層"
+    rationale: "可讀性與結構清晰度"
+  - id: info-hierarchy
+    rule: "資訊層次遵循 Hero → Support → Detail → CTA 順序"
+    rationale: "Narrative structure，引導使用者注意力"
+  - id: touch-targets
+    rule: "行動裝置觸控目標最小 44×44px"
+    rationale: "無障礙設計基本要求"
+
+# 禁止的 UI 反模式
+anti_patterns:
+  - id: floating-badge
+    name: "浮動徽章（floating badge）"
+    description: "徽章脫離內容浮動顯示，無明確歸屬"
+    preferred: "使用內嵌 label 或狀態指示器"
+  - id: generic-card-layout
+    name: "通用卡片堆疊（generic card layout）"
+    description: "完全相同的卡片作為主要內容結構，無差異化"
+    preferred: "帶有清晰層次的多樣化內容結構"
+  - id: dashboard-grid-as-homepage
+    name: "首頁儀表板化（dashboard grid as homepage）"
+    description: "行銷首頁設計成數據儀表板 Grid 佈局"
+    preferred: "敘事型首頁：Hero → Support → CTA 結構"
+  - id: competing-ctas
+    name: "競爭性 CTA（competing CTAs）"
+    description: "同一畫面有多個視覺權重相同的 CTA 按鈕"
+    preferred: "1 個主要 CTA，0–1 個次要 CTA"
+  - id: color-only-differentiation
+    name: "僅用顏色區分（color-only differentiation）"
+    description: "只用顏色區分狀態或分類，無其他視覺提示"
+    preferred: "顏色搭配圖示、文字標籤或圖案"
+  - id: decorative-overload
+    name: "裝飾性過載（decorative overload）"
+    description: "無資訊傳遞功能的插圖或動畫佔用視覺空間"
+    preferred: "移除裝飾元素；優先使用功能性視覺"
+  - id: triple-nesting
+    name: "三層以上巢狀（triple nesting）"
+    description: "視覺層次超過 3 層，導致結構難以閱讀"
+    preferred: "扁平化結構，用留白區隔"
+  - id: rainbow-accents
+    name: "多色強調系統（rainbow accents）"
+    description: "同時使用多個強調色（紫色 CTA、橘色徽章、綠色標籤）"
+    preferred: "單一 accent 色彩系統，統一視覺語言"
+
+# DESIGN.md 存放位置規範
+file_placement:
+  filename: "DESIGN.md"
+  filename_casing: "exact uppercase"
+  location: "project root"
+  same_level_as: ["README.md", "CLAUDE.md", "package.json"]
+  forbidden_locations: ["docs/", "src/", "assets/", "subdirectories"]
+  section_heading_level: "##"
+  version_required: true
+
+# AI 行為規則
+rules:
+  - id: require-design-md
+    trigger: "當 AI Agent 開始生成前端 UI 程式碼或設計規格時"
+    instruction: |
+      先檢查專案根目錄是否存在 DESIGN.md。
+      若存在，讀取 Section 9（Agent Prompt References）作為快速定向，
+      再依需要讀取其他段落。
+      若不存在，提示使用者先建立 DESIGN.md（可使用 templates/DESIGN.md 模板）。
+    priority: required
+
+  - id: semantic-tokens-only
+    trigger: "當 AI Agent 產生包含顏色的前端程式碼時"
+    instruction: |
+      使用語義 token 名稱（background, surface, accent 等），
+      不得直接在元件中硬編碼 hex 色值。
+      例：用 `var(--color-accent)` 而非 `#6366F1`。
+    priority: required
+
+  - id: enforce-hard-constraints
+    trigger: "當 AI Agent 生成任何頁面或視圖時"
+    instruction: |
+      強制執行 UI 硬性約束：
+      - 每頁只有 1 個 H1
+      - 最多 6 個頁面區段
+      - 最多 2 個字體家族
+      - 最多 1 個 accent 色
+    priority: required
+
+  - id: reject-anti-patterns
+    trigger: "當 AI Agent 生成 UI 結構或元件時"
+    instruction: |
+      主動偵測並拒絕以下反模式：
+      floating-badge, generic-card-layout, dashboard-grid-as-homepage,
+      competing-ctas, color-only-differentiation。
+      若偵測到，提出替代方案。
+    priority: required
+
+  - id: spacing-scale-only
+    trigger: "當 AI Agent 生成 CSS 或 layout 相關程式碼時"
+    instruction: |
+      所有間距值必須使用標準 space-N token（space-1 到 space-8，無 space-7）。
+      不得使用任意像素值（如 13px, 20px, 37px）。
+    priority: recommended
+
+  - id: narrative-structure
+    trigger: "當 AI Agent 生成首頁（Homepage/Landing Page）時"
+    instruction: |
+      遵循 Narrative structure：Hero → Support → Detail → CTA。
+      禁止將首頁設計成 Dashboard Grid。
+    priority: required
+
+# 快速參考表
+quick_reference:
+  semantic_tokens:
+    columns: ["Token", "角色", "明色範例", "暗色範例"]
+    rows:
+      - ["background", "頁面底色", "#FFFFFF", "#0A0A0A"]
+      - ["surface", "卡片/面板", "#F9FAFB", "#1A1A1A"]
+      - ["primary-text", "主要文字", "#111827", "#F5F5F5"]
+      - ["muted-text", "次要文字", "#6B7280", "#888888"]
+      - ["accent", "強調/CTA", "（專案自訂）", "（專案自訂）"]
+  typography_roles:
+    columns: ["角色", "大小", "Weight", "Line-height", "用途"]
+    rows:
+      - ["display", "48px+", "700", "1.1", "英雄標題"]
+      - ["headline", "24–32px", "600", "1.3", "區段標題"]
+      - ["body", "16px", "400", "1.6", "正文內容"]
+      - ["caption", "12–14px", "400", "1.4", "標籤/說明"]
+  spacing_scale:
+    columns: ["Token", "值", "主要用途"]
+    rows:
+      - ["space-1", "4px", "圖示內距、緊湊元素"]
+      - ["space-2", "8px", "預設元素內距"]
+      - ["space-3", "16px", "元件內部間距"]
+      - ["space-4", "24px", "區塊間距、網格欄距"]
+      - ["space-5", "32px", "元件之間"]
+      - ["space-6", "48px", "主要區段之間"]
+      - ["space-8", "64px", "頁面層級分隔"]
+  anti_patterns:
+    columns: ["禁止模式", "說明"]
+    rows:
+      - ["floating-badge", "浮動徽章，脫離內容無歸屬"]
+      - ["generic-card-layout", "無差異化卡片堆疊"]
+      - ["dashboard-grid-as-homepage", "首頁儀表板化"]
+      - ["competing-ctas", "多個等重 CTA"]
+      - ["color-only-differentiation", "僅用顏色區分狀態"]
+      - ["decorative-overload", "無功能的裝飾元素"]
+      - ["triple-nesting", "超過 3 層視覺巢狀"]
+      - ["rainbow-accents", "多色強調系統"]

package/bundled/ai/standards/health-check-standards.ai.yaml

@@ -0,0 +1,140 @@
+# Health Check Standards - AI Optimized
+# Source: XSPEC-067 (DEC-043 Wave 1 Reliability Pack)
+
+standard:
+  id: health-check-standards
+  name: Health Check Standards
+  description: 健康檢查標準 — liveness / readiness / startup 三種 probe、深度 health check、結構化 JSON 回應
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-17"
+    status: trial
+    since: "2026-04-17"
+    expires: "2026-10-17"
+    source: XSPEC-067
+    borrowed_from: DEC-043
+    description: >
+      業界常見錯誤：把 liveness 和 readiness 混用（健康檢查檢查外部依賴導致連鎖重啟）。
+      本標準明確三種 probe 語意分離、定義深度 health check 的檢查範圍（僅關鍵依賴）、
+      並規範結構化 JSON 回應以便下游自動化處理。與 observability 整合為 RED metric 的 Error 來源之一。
+    scope: universal
+    industry_reference: "Kubernetes probes, Microsoft eShop health checks, Google SRE Book Ch.6"
+
+  guidelines:
+    - "Liveness probe 不得檢查外部依賴（DB、下游 API），否則會造成連鎖重啟"
+    - "Readiness probe 可檢查關鍵外部依賴，但僅關鍵（非全部依賴）"
+    - "慢啟動服務應使用 startup probe，啟動完成後交棒給 liveness"
+    - "Health check 端點必須回傳結構化 JSON，包含 status / dependencies / timestamp"
+    - "Health check 結果應作為 observability 的 Error signal 之一，連續 fail 觸發 incident"
+
+  probe_types:
+    liveness:
+      purpose: "服務是否還活著（process 是否卡死）"
+      endpoint_suggestion: "GET /health/live"
+      checks:
+        allowed:
+          - "process 是否能回應 HTTP"
+          - "內部 event loop 是否可用"
+        forbidden:
+          - "DB 連線（DB 壞時 liveness 失敗 → pod 重啟 → 啟動更多 client → DB 更壞）"
+          - "下游 API（會造成連鎖重啟）"
+          - "消息佇列"
+      on_fail: "重啟 pod / process"
+      failure_threshold: 3
+      period_seconds: 10
+
+    readiness:
+      purpose: "是否可接收流量"
+      endpoint_suggestion: "GET /health/ready"
+      checks:
+        allowed:
+          - "自身 API 可用"
+          - "DB 連線可用（若服務必須依賴 DB 才能工作）"
+          - "關鍵下游依賴可用（非全部下游）"
+          - "必要的設定 / 憑證已載入"
+        forbidden:
+          - "非關鍵依賴（避免非關鍵故障造成服務被移出負載均衡）"
+      on_fail: "移出負載均衡，不重啟"
+      failure_threshold: 3
+      period_seconds: 5
+
+    startup:
+      purpose: "啟動期專用，替代慢啟動服務的 liveness"
+      endpoint_suggestion: "GET /health/startup"
+      checks:
+        - "啟動過程所需資源（如快取預熱、index 載入）已完成"
+      on_fail: "重啟 pod（啟動超時）"
+      handover: "通過後停用，改由 liveness 接手"
+      failure_threshold: 30
+      period_seconds: 10
+
+  depth_rules:
+    shallow:
+      when: "liveness"
+      checks: "process 是否可回應，不碰任何外部依賴"
+    deep:
+      when: "readiness"
+      checks:
+        - "自身 API 路由可解析"
+        - "DB ping 成功（若必須 DB）"
+        - "關鍵下游 API ping 成功（非全部）"
+      note: "關鍵依賴的定義：沒有它服務就完全無法提供核心功能"
+
+  response_format:
+    content_type: "application/json"
+    status_codes:
+      "200": "healthy — 所有關鍵依賴正常"
+      "503": "unhealthy — 至少一個關鍵依賴失敗"
+    schema:
+      status: "healthy | degraded | unhealthy"
+      timestamp: "ISO-8601"
+      uptime_seconds: number
+      dependencies:
+        description: "每個被檢查的依賴的狀態（僅 readiness / deep check 回傳）"
+        example:
+          database:
+            status: "healthy | unhealthy"
+            latency_ms: number
+            last_check: "ISO-8601"
+          upstream_api:
+            status: "healthy | unhealthy"
+            latency_ms: number
+      version: "service version string"
+
+  observability_integration:
+    rule_1: "Health check 結果應作為 RED metric 的 Error 來源之一（Rate / Errors / Duration）"
+    rule_2: "連續 N 次 health check failed 應觸發 incident（對齊 incident-response）"
+    rule_3: "probe 延遲本身應被監控（異常緩慢可能是 resource_exhaustion 徵兆）"
+
+  scenarios:
+    scenario_1_liveness_not_checking_db:
+      given: "DB 暫時無法連線（連線池耗盡）"
+      when: "liveness probe 被呼叫"
+      then: "回傳 200 healthy（liveness 不檢查 DB）"
+      note: "避免 DB 連鎖故障導致所有 pod 重啟"
+
+    scenario_2_readiness_fails_on_critical_dep:
+      given: "關鍵下游 API 不可達（服務無法處理任何請求）"
+      when: "readiness probe 被呼叫"
+      then: "回傳 503 unhealthy，dependencies.upstream_api.status=unhealthy"
+      and: "pod 被移出負載均衡，但 process 不重啟"
+      note: "readiness fail → 不接流量；liveness 仍 healthy → 不重啟"
+
+    scenario_3_startup_then_liveness_handover:
+      given: "服務需 60s 預熱快取"
+      when: "pod 啟動"
+      then: "startup probe 檢查預熱狀態，前 60s 持續回 503"
+      and: "預熱完成後 startup 回 200，自此停用，改由 liveness 接手"
+      note: "避免慢啟動服務在預熱中被誤判為 crash 重啟"
+
+  error_codes:
+    HC-001: "HEALTH_CHECK_FAILED — 關鍵依賴失敗"
+    HC-002: "HEALTH_CHECK_TIMEOUT — probe 本身超時"
+    HC-003: "INVALID_DEPENDENCY_SET — readiness 檢查了非關鍵依賴（設計違規）"
+
+  integration_points:
+    - "observability-standards（XSPEC-063 規劃中）— health check 是 RED metric 的 Error 來源"
+    - "incident-response-assistant — 連續 health check failed 觸發 incident 流程"
+    - "circuit-breaker.ai.yaml — breaker OPEN 時 readiness 應回 degraded"
+    - "deployment-standards.ai.yaml — K8s probe 配置對應三種 probe 類型"

package/bundled/ai/standards/immutability-first.ai.yaml

@@ -0,0 +1,112 @@
+# immutability-first.ai.yaml
+# 不可變性設計原則（Immutability-First Architecture）
+# XSPEC-044 — 防止並行 Agent 環境競態條件的系統級設計標準
+
+standard:
+  id: immutability-first
+  name: Immutability-First Architecture Standard
+  description: 系統級不可變性設計原則 — DTO/Value Object 欄位一律 readonly，防止並行 Agent 競態條件
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-16"
+    source: XSPEC-044
+    description: >
+      系統級不可變性設計原則。資料流介面（DTO / Value Object）的欄位
+      一律宣告為 readonly，陣列欄位使用 ReadonlyArray<T>，物件修改透過
+      展開語法建立新物件，防止並行 Agent 環境下的意外狀態共享與競態條件。
+    scope: universal
+    applies_to: [TypeScript, interfaces, concurrent-systems]
+
+  guidelines:
+    - "資料流介面（DTO / Value Object）的所有欄位必須宣告 readonly"
+    - "介面中的陣列型欄位使用 ReadonlyArray<T> 而非可變的 T[]"
+    - "修改物件時使用物件展開語法建立新物件，不直接賦值給 readonly 欄位"
+    - "跨並行邊界（Promise.all / Worker Thread）傳遞的物件必須為深層不可變"
+    - "介面中的嵌套物件欄位使用 Readonly<T> 包裝（防止淺層保護不足）"
+
+  rules:
+    - id: IMM-001
+      name: "DTO 欄位 readonly"
+      rule: "資料流介面（Data Transfer Objects、Value Objects）的所有欄位必須宣告 readonly"
+      rationale: "防止並行 Agent 環境下的意外狀態共享與競態條件"
+      severity: required
+      example_bad: |
+        interface TaskResult {
+          status: TaskStatus   // ← 可被意外修改
+          cost_usd?: number
+        }
+      example_good: |
+        interface TaskResult {
+          readonly status: TaskStatus   // ← 型別安全保護
+          readonly cost_usd?: number
+        }
+
+    - id: IMM-002
+      name: "陣列欄位 ReadonlyArray"
+      rule: "介面中的陣列型欄位使用 ReadonlyArray<T> 而非可變的 T[]"
+      rationale: "防止 push/splice/sort 等就地修改操作破壞共享陣列"
+      severity: required
+      example_bad: |
+        interface MemoryContext {
+          recentHistory: IterationRecord[]   // ← 可被 push/splice
+        }
+      example_good: |
+        interface MemoryContext {
+          readonly recentHistory: ReadonlyArray<IterationRecord>
+        }
+
+    - id: IMM-003
+      name: "展開語法替代就地修改"
+      rule: "修改物件時使用物件展開語法建立新物件，不直接賦值給 readonly 欄位"
+      rationale: "保留原始物件不變，同時建立可追蹤的修改歷程"
+      severity: required
+      example_bad: |
+        options.sessionId = forkId   // ← 直接修改，其他持有者看到改變
+      example_good: |
+        const taskOptions = { ...options, sessionId: forkId }   // ← 新物件
+
+    - id: IMM-004
+      name: "並行邊界深層不可變"
+      rule: "跨並行邊界（Promise.all / Worker Thread）傳遞的物件必須為深層不可變"
+      rationale: "並行執行中無法預測存取順序，可變共享物件必然產生競態條件"
+      severity: required
+      applies_to: [orchestrateParallel, Promise.all, Worker]
+      example_good: |
+        // 每個並行任務持有自己的 options 快照
+        const batchResults = await Promise.all(
+          batch.map(task => {
+            const taskOptions = { ...baseOptions, sessionId: forkId }
+            return executeOneTask(task, adapter, taskOptions, ...)
+          })
+        )
+
+    - id: IMM-005
+      name: "嵌套物件 Readonly 包裝"
+      rule: "介面中的嵌套物件欄位使用 Readonly<T> 包裝"
+      rationale: "頂層 readonly 不防止嵌套物件欄位被修改（淺層保護不足）"
+      severity: recommended
+      example_bad: |
+        interface PipelineMemoryEntry {
+          readonly metadata: { score?: number }   // ← metadata.score 仍可被修改
+        }
+      example_good: |
+        interface PipelineMemoryEntry {
+          readonly metadata: Readonly<{ score?: number; severity?: string }>
+        }
+
+  when_to_apply:
+    - "設計新的 DTO / Value Object / Config 介面時"
+    - "跨並行邊界傳遞物件時"
+    - "Agent 間共享狀態設計時"
+    - "Code Review 時檢查介面是否遺漏 readonly"
+
+  exceptions:
+    - "Builder Pattern 的 mutable builder 物件（在 build() 後回傳不可變結果）"
+    - "測試 fixture 的 mutable 建立步驟（建立後視為不可變）"
+    - "效能關鍵的熱路徑（需有明確的 benchmark 依據才可豁免）"
+
+  error_codes:
+    IMM-E001: "READONLY_VIOLATION — 嘗試修改 readonly 欄位（TypeScript 編譯期捕獲）"
+    IMM-E002: "SHARED_MUTATION — 跨並行邊界的就地修改導致競態條件"
+    IMM-E003: "SHALLOW_READONLY — 嵌套物件遺漏 Readonly<T> 包裝，淺層保護不足"

package/bundled/ai/standards/model-selection.ai.yaml

@@ -8,10 +8,10 @@ standard:
   description: AI 模型分級選擇策略
 
   meta:
-    version: "1.0.0"
-    updated: "2026-03-20"
+    version: "2.0.0"
+    updated: "2026-04-13"
     source: core/model-selection.md
-    description: 三層模型分級選擇標準
+    description: "三層模型分級選擇策略 + 多模型池能力管理（XSPEC-027）"
     inspired_by: superpowers/subagent-driven-development
 
   guidelines:
@@ -70,6 +70,112 @@ standard:
       action: "從 standard 或更高層級開始"
       priority: medium
 
+  capability_dimensions:
+    description: "能力維度分類與評分說明（XSPEC-027, DEC-031, DEC-032）"
+    scoring_scale:
+      5: "生產就緒 — 高準確率，可直接使用"
+      4: "良好 — 偶有遺漏，可接受"
+      3: "基本可用 — 需人工補充"
+      2: "部分可用 — 僅供參考"
+      1: "不可靠 — 不建議使用"
+    dimensions:
+      modality:
+        vision:
+          description: "圖片/截圖理解能力（UI 分析、圖表解讀）"
+          benchmark: "internal-vision-bench"
+          scoring_guide:
+            5: "≥ 90% 準確，可萃取完整 DESIGN.md"
+            4: "75-89%，偶有遺漏但可用"
+            3: "60-74%，需人工補充"
+            2: "40-59%，僅供參考"
+            1: "< 40%，不可靠"
+        audio:
+          description: "語音理解能力"
+          benchmark: "future-audio-bench"
+        image_generation:
+          description: "圖片生成能力"
+          benchmark: "provider-specific"
+      reasoning:
+        code_reasoning:
+          description: "程式碼理解與生成品質"
+          benchmark: "humaneval-plus"
+        math_reasoning:
+          description: "數學推理準確率"
+          benchmark: "gsm8k"
+        instruction_following:
+          description: "複雜多步驟指令遵循率（VibeOps 最重視）"
+          benchmark: "internal-instruction-bench"
+        long_context_quality:
+          description: "長文件中間段資訊存取（Lost-in-the-Middle）"
+          benchmark: "needle-in-haystack"
+      output:
+        structured_output:
+          description: "JSON mode / Schema 格式輸出成功率"
+          benchmark: "internal-json-bench"
+        tool_use:
+          description: "Function Calling 正確率"
+          benchmark: "internal-tool-bench"
+      language:
+        multilingual_zh_tw:
+          description: "繁體中文品質（本系統優先語言）"
+          benchmark: "internal-zh-tw-bench"
+
+  capability_registry:
+    description: "模型能力登記表（DEC-031 D1）。各子專案依實際測試維護分數。"
+    format:
+      model_id: "provider/model-name"
+      version_pinned: "版本鎖定識別（SHA、日期戳或 model_version）"
+      pin_date: "鎖定日期（YYYY-MM-DD）"
+      eol_date: "預期淘汰日期（可選，YYYY-MM-DD）"
+      capabilities:
+        "<dimension>.<subdimension>": "<1-5 整數分>"
+    examples:
+      - model_id: "anthropic/claude-sonnet-4-6"
+        version_pinned: "claude-sonnet-4-6"
+        pin_date: "2026-04-13"
+        capabilities:
+          "modality.vision": 4
+          "reasoning.instruction_following": 5
+          "reasoning.code_reasoning": 5
+          "output.structured_output": 5
+          "output.tool_use": 5
+          "language.multilingual_zh_tw": 5
+      - model_id: "anthropic/claude-haiku-4-5"
+        version_pinned: "claude-haiku-4-5-20251001"
+        pin_date: "2026-04-13"
+        capabilities:
+          "modality.vision": 3
+          "reasoning.instruction_following": 4
+          "reasoning.code_reasoning": 4
+          "output.structured_output": 4
+          "output.tool_use": 4
+          "language.multilingual_zh_tw": 4
+
+  routing_rules:
+    description: "能力路由決策規則（DEC-031 D2, DEC-032 D3）"
+    selection_strategy: "pareto_weighted"
+    rules:
+      - id: CAP-001
+        condition: "任務需要 capability X，模型得分 ≥ min_score"
+        action: "SUPPORTED — 正常執行"
+        priority: high
+      - id: CAP-002
+        condition: "任務需要 capability X，模型得分 2-3（min_score 未達但 ≥ 2）"
+        action: "DEGRADED — 降級流程執行，產出標記 [DEGRADED]"
+        priority: medium
+      - id: CAP-003
+        condition: "任務需要 capability X，模型得分 ≤ 1 或未登記"
+        action: "UNSUPPORTED — 使用替代流程或提示用戶"
+        priority: high
+      - id: CAP-004
+        condition: "模型降智偵測（DEC-033）觸發 moderate 信號"
+        action: "啟動金絲雀測試，同時記錄降智警告"
+        priority: high
+      - id: CAP-005
+        condition: "模型降智偵測觸發 critical 信號"
+        action: "自動切換備用模型，上報 P1 Issue"
+        priority: critical
+
 physical_spec:
   type: checklist
   validator:
@@ -79,3 +185,5 @@ physical_spec:
     - "是否根據複雜度信號選擇模型等級"
     - "BLOCKED 時是否嘗試升級而非直接失敗"
     - "簡單任務是否避免使用過高等級模型"
+    - "能力登記表是否包含 version_pinned 與 pin_date"
+    - "路由決策是否依 SUPPORTED/DEGRADED/UNSUPPORTED 三態處理"