universal-dev-standards 5.1.0-beta.5 → 5.1.0-beta.7

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 三態處理"

package/bundled/ai/standards/packaging-standards.ai.yaml

@@ -0,0 +1,142 @@
+# Packaging Standards (AI-Optimized v1)
+# Source: core/packaging-standards.md
+
+standard:
+  id: packaging
+  name: Packaging Standards
+  description: Recipe-based packaging framework for user projects using UDS/DevAP toolchain
+  guidelines:
+    - "Recipe-based: use built-in or custom recipes for each packaging target"
+    - "Declarative: declare targets in .devap/packaging.yaml"
+    - "Customizable: override config, inject hooks, or write custom recipes"
+    - "Pipeline-integrated: packaging runs between Review and Deploy in VibeOps"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-15"
+    source: core/packaging-standards.md
+
+  principles:
+    core:
+      - recipe_based: "Every packaging target references a named Recipe; no ad-hoc scripts in pipeline YAML"
+      - declarative_targets: "Projects declare targets in .devap/packaging.yaml; DevAP resolves and executes"
+      - customizable: "Four customization layers allow config overrides, hook injection, custom Recipes, and escape hatches"
+      - pipeline_integrated: "Packaging runs as a named stage between Review and Deploy"
+
+recipe_structure:
+  required_fields: [name, steps]
+  optional_fields: [description, requires, config, hooks]
+  step_fields:
+    required: [run]
+    optional: [description]
+  hook_points: [preBuild, postBuild, prePublish, postPublish]
+  config_variables:
+    - name: "{registry}"
+      source: "config.registry"
+    - name: "{name}"
+      source: "package.json#name or config.name"
+    - name: "{version}"
+      source: "package.json#version or config.version"
+    - name: "{platforms}"
+      source: "config.platforms"
+    - name: "{output_dir}"
+      source: "config.output_dir"
+
+built_in_recipes:
+  npm_library:
+    file: recipes/npm-library.yaml
+    use_case: "npm package without a binary entry point"
+    requires: [package.json, tsconfig.json]
+    steps: [npm run build, npm pack, npm publish]
+    default_config:
+      registry: https://registry.npmjs.org
+      access: public
+      tag: latest
+  npm_cli:
+    file: recipes/npm-cli.yaml
+    use_case: "npm package with bin field (CLI tool)"
+    requires: [package.json, tsconfig.json]
+    steps: [npm run build, verify_bin_field, npm pack, npm publish]
+    default_config:
+      registry: https://registry.npmjs.org
+      access: public
+      tag: latest
+  docker_service:
+    file: recipes/docker-service.yaml
+    use_case: "Docker container image build and push"
+    requires: [Dockerfile]
+    steps: [docker buildx build, docker push, docker tag latest, docker push latest]
+    default_config:
+      registry: ghcr.io
+      platforms: linux/amd64,linux/arm64
+      push_latest: true
+  windows_installer:
+    file: recipes/windows-installer.yaml
+    use_case: "Windows installer (.msi or .exe) via user-provided build script"
+    requires: [package.json, "packaging/windows-build.sh"]
+    steps: [npm run build, bash packaging/windows-build.sh]
+    default_config:
+      output_dir: dist/installers
+      format: msi
+
+customization_layers:
+  L1:
+    name: config_override
+    mechanism: "config: block in .devap/packaging.yaml"
+    when: "Change default values (registry URL, tag, output dir)"
+  L2:
+    name: hook_injection
+    mechanism: "hooks: block in .devap/packaging.yaml"
+    when: "Run extra commands before/after build or publish"
+  L3:
+    name: custom_recipe
+    mechanism: "New .yaml file in project's .devap/recipes/"
+    when: "Entirely different build process; built-ins don't apply"
+  L4:
+    name: escape_hatch
+    mechanism: "script: key replacing recipe: in target definition"
+    when: "Raw shell script when no Recipe abstraction is suitable"
+
+acceptance_criteria:
+  success_conditions:
+    - condition: "All requires files exist"
+      threshold: "100%"
+      timing: "Before any step runs"
+    - condition: "All steps exit with code 0"
+      threshold: "100%"
+      timing: "Per step"
+    - condition: "postBuild artifact exists"
+      threshold: "Present in expected path"
+      timing: "After build step"
+    - condition: "Hook commands exit with code 0"
+      threshold: "100%"
+      timing: "Per hook"
+    - condition: "Published artifact is retrievable"
+      threshold: "HTTP 200 / registry query succeeds"
+      timing: "Post-publish smoke check"
+  failure_handling:
+    missing_requires: {action: "fail immediately", retry: false}
+    step_nonzero_exit: {action: "fail immediately, run postBuild hook if defined", retry: "configurable"}
+    hook_nonzero_exit: {action: "fail immediately", retry: false}
+    publish_unreachable: {action: "retry with exponential backoff", retry: true, max_retries: 3}
+
+recipe_selection_guide:
+  decision_tree:
+    is_npm_package:
+      yes:
+        has_bin_field:
+          yes: npm-cli
+          no: npm-library
+      no:
+        is_container_image:
+          yes: docker-service
+          no:
+            is_windows_installer:
+              yes: windows-installer
+              no: custom-recipe-required
+
+physical_spec:
+  type: custom_script
+  validator:
+    command: "test -f .devap/packaging.yaml"
+    rule: "packaging_config_declared"

package/bundled/ai/standards/recovery-recipe-registry.ai.yaml

@@ -0,0 +1,200 @@
+# Recovery Recipe Registry Standard - AI Optimized
+# Source: XSPEC-046 (claw-code ROADMAP Phase 3 Recovery Recipes, DEC-035)
+
+standard:
+  id: recovery-recipe-registry
+  name: Recovery Recipe Registry Standard
+  description: 恢復食譜註冊表 — 將分散的恢復邏輯統一為 YAML 可配置的 Recipe，以 failureSource 為匹配鍵
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-16"
+    source: XSPEC-046
+    description: >
+      各模組（Fix Loop、Circuit Breaker、Guardian 自動修復、Staging 重試）的恢復邏輯
+      統一為可外部化的 Recovery Recipe 格式。每個 Recipe 透過 failureSource（XSPEC-045）
+      匹配觸發條件，選擇對應的恢復策略，並定義升級路徑（escalation）。
+      無匹配 Recipe 時 fallback 到現有行為（向後相容）。
+    scope: universal
+    borrowed_from: "ultraworkers/claw-code ROADMAP Phase 3 Recovery Recipes (adapted to YAML format)"
+    depends_on: "failure-source-taxonomy.ai.yaml (XSPEC-045)"
+
+  guidelines:
+    - "每個 Recovery Recipe 必須有唯一 ID（RR-NNN 格式）"
+    - "match.failure_source 必須是 failure-source-taxonomy 中定義的 8 類之一"
+    - "escalation.on_exhaust 必須定義，不得無限循環（如 escalation 指向自身）"
+    - "無匹配 Recipe 時，系統必須 fallback 到現有預設行為（不得拋出錯誤）"
+    - "使用者自訂 Recipe 優先於內建 Recipe（同 failureSource 時，使用者配置的先匹配）"
+    - "Recipe config 格式錯誤時 fallback 到策略預設值（不中斷執行）"
+
+  strategies:
+    fix_loop:
+      description: "注入結構化錯誤回饋，重試任務（現有 Fix Loop）"
+      config:
+        max_attempts:
+          type: number
+          default: 3
+        budget_usd:
+          type: number
+          default: 0.50
+      best_for: [compilation, test_failure]
+
+    circuit_breaker:
+      description: "三態斷路器保護（XSPEC-036），連續失敗後開路避免雪崩"
+      config:
+        failure_threshold:
+          type: number
+          default: 3
+        cooldown_ms:
+          type: number
+          default: 30000
+      best_for: [tool_failure, prompt_delivery]
+
+    rebase_and_retry:
+      description: "先執行 git rebase 同步基底分支，再重試任務/迭代"
+      config:
+        max_attempts:
+          type: number
+          default: 1
+        base_branch:
+          type: string
+          default: "main"
+      best_for: [branch_divergence]
+      requires: "XSPEC-047 Branch Drift Detection"
+
+    model_switch:
+      description: "切換至備用模型後重試"
+      config:
+        fallback_models:
+          type: "string[]"
+          description: "按優先順序的備用模型列表"
+        max_attempts:
+          type: number
+          default: 2
+      best_for: [model_degradation, prompt_delivery]
+
+    degraded_mode:
+      description: "以降級模式繼續執行（如：跳過品質驗證、以部分結果繼續）"
+      config: {}
+      result_status: "done_with_concerns"
+      best_for: [resource_exhaustion, model_degradation]
+
+    human_checkpoint:
+      description: "暫停執行，等待人工介入（提供失敗細節供判斷）"
+      config:
+        message:
+          type: string
+          description: "通知使用者的訊息"
+      best_for: [policy_violation, branch_divergence]
+      note: "所有其他策略的最終升級路徑"
+
+  recipe_schema:
+    description: "Recovery Recipe YAML 格式定義"
+    fields:
+      id:
+        type: string
+        pattern: "RR-[0-9]+"
+        required: true
+      name:
+        type: string
+        required: true
+      match:
+        required: true
+        fields:
+          failure_source:
+            type: FailureSource
+            required: true
+          severity:
+            type: "string[]"
+            values: [critical, high, medium, low]
+            description: "空或省略表示匹配所有 severity"
+      strategy:
+        type: RecoveryStrategy
+        required: true
+      config:
+        type: object
+        description: "策略特定配置，覆蓋策略預設值"
+      escalation:
+        required: true
+        fields:
+          on_exhaust:
+            type: RecoveryStrategy
+            required: true
+            description: "嘗試耗盡後的下一步策略（不得指向自身）"
+          message:
+            type: string
+            description: "升級時的通知訊息"
+
+  default_recipes:
+    description: "安裝時隨附的 5 個預設 Recipe"
+    recipes:
+      - id: RR-001
+        name: "Fix Loop for Compilation Errors"
+        match: { failure_source: compilation }
+        strategy: fix_loop
+        config: { max_attempts: 3, budget_usd: 0.50 }
+        escalation: { on_exhaust: human_checkpoint }
+
+      - id: RR-002
+        name: "Fix Loop for Test Failures"
+        match: { failure_source: test_failure }
+        strategy: fix_loop
+        config: { max_attempts: 3, budget_usd: 0.50 }
+        escalation: { on_exhaust: human_checkpoint }
+
+      - id: RR-003
+        name: "Model Switch for Degradation"
+        match: { failure_source: model_degradation }
+        strategy: model_switch
+        config: { max_attempts: 2 }
+        escalation: { on_exhaust: degraded_mode }
+
+      - id: RR-004
+        name: "Rebase for Branch Divergence"
+        match: { failure_source: branch_divergence }
+        strategy: rebase_and_retry
+        config: { max_attempts: 1 }
+        escalation: { on_exhaust: human_checkpoint, message: "Rebase 衝突，需人工解決" }
+
+      - id: RR-005
+        name: "Degraded Mode for Resource Exhaustion"
+        match: { failure_source: resource_exhaustion }
+        strategy: degraded_mode
+        escalation: { on_exhaust: human_checkpoint }
+
+  types:
+    RecoveryStrategy:
+      description: "6 個內建恢復策略"
+      values:
+        - fix_loop
+        - circuit_breaker
+        - rebase_and_retry
+        - model_switch
+        - degraded_mode
+        - human_checkpoint
+
+    RecoveryRecipe:
+      description: "恢復食譜定義"
+      fields:
+        id: "string  # RR-NNN 格式"
+        name: string
+        match:
+          failure_source: FailureSource
+          severity: "string[] (optional)"
+        strategy: RecoveryStrategy
+        config: "object (optional)"
+        escalation:
+          on_exhaust: RecoveryStrategy
+          message: "string (optional)"
+
+  integration_points:
+    devap:
+      files:
+        - "packages/core/src/types.ts — RecoveryRecipe / RecoveryStrategy type"
+        - "packages/core/src/recovery-registry.ts — Registry 實作與預設 recipe"
+        - "packages/core/src/orchestrator.ts — fix loop 前查詢 Registry"
+    vibeops:
+      files:
+        - "src/types/index.ts — 獨立定義 RecoveryRecipe（AGPL 隔離）"
+        - "src/runner/recovery-registry.ts — 獨立實作"
+        - "recovery-recipes.yaml — 預設 recipe 配置"

package/bundled/ai/standards/retry-standards.ai.yaml

@@ -0,0 +1,134 @@
+# Retry Standards - AI Optimized
+# Source: XSPEC-067 (DEC-043 Wave 1 Reliability Pack)
+
+standard:
+  id: retry-standards
+  name: Retry Standards
+  description: 重試策略標準 — 指數退避加抖動、重試上限、依 failure-source 分類的重試規則
+
+  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: >
+      延伸既有 circuit-breaker 與 failure-source-taxonomy，補齊 retry 層的標準化規則。
+      避免各元件各自實作重試造成行為不一致（無上限重試、無 jitter 導致 thundering herd）。
+      與 failure-source-taxonomy 深度整合：依失敗類型決定是否重試、重試幾次、退避多久。
+    scope: universal
+    industry_reference: "Netflix Hystrix retry, Google SRE Book Ch.22, AWS Architecture Blog - exponential backoff and jitter"
+
+  guidelines:
+    - "所有重試邏輯必須使用 exponential + jitter，禁止固定間隔或無 jitter 的純指數"
+    - "重試必須有明確上限（max_attempts），禁止無限重試"
+    - "重試決策必須先參考 failure-source-taxonomy 分類，fail-fast 類別不得重試"
+    - "重試必須與 circuit-breaker 整合：OPEN 狀態下不得重試，直接 fail-fast"
+    - "每次重試都應透過遙測事件上報（retry_attempted / retry_exhausted），方便觀察無效重試"
+
+  backoff_formula:
+    name: "Exponential with full jitter"
+    formula: "wait_ms = min(cap_ms, base_ms * 2^attempt) * (0.5 + random() * 0.5)"
+    defaults:
+      base_ms: 100
+      cap_ms: 30000
+      max_attempts: 5
+      jitter_ratio: 0.5
+    rationale:
+      - "Exponential 隨重試次數指數退避，避免短時間大量請求"
+      - "Jitter ±50% 避免 thundering herd（所有 client 同時重試）"
+      - "cap_ms=30s 避免超長等待，與典型 request timeout 對齊"
+
+  failure_source_rules:
+    description: "依 failure-source-taxonomy 的 8 類 failureSource 決定重試策略"
+    rules:
+      transient_network:
+        retry: true
+        max_attempts: 5
+        base_ms: 100
+        note: "短暫網路抖動，指數退避通常可恢復"
+      rate_limit:
+        retry: true
+        max_attempts: 3
+        base_ms: 1000
+        note: "底數加大（1s）預留額度恢復時間；若 API 回傳 Retry-After 則優先採用"
+      upstream_unavailable:
+        retry: true
+        max_attempts: 3
+        base_ms: 500
+        note: "重試前先查 circuit-breaker；連續失敗觸發 OPEN 狀態"
+      tool_failure:
+        retry: true
+        max_attempts: 2
+        base_ms: 200
+        note: "工具層失敗通常非 transient，僅給 2 次機會"
+      prompt_delivery:
+        retry: true
+        max_attempts: 2
+        base_ms: 100
+        note: "多半是短暫 API 問題；超過 2 次改走 model_switch"
+      authentication:
+        retry: false
+        note: "fail-fast；憑證錯誤重試不會變對，只會浪費 quota"
+      validation:
+        retry: false
+        note: "fail-fast；input 錯誤重試結果不變"
+      policy_violation:
+        retry: false
+        note: "fail-fast；安全決策禁止繞過（對齊 security-decision 標準）"
+      quota_exhausted:
+        retry: false
+        note: "fail-fast；等 budget reset 或升級 tier，不應在同 session 內重試"
+
+  circuit_breaker_integration:
+    rule_1: "每次重試前檢查對應 breaker 的 state；若為 OPEN 立即回傳 CircuitOpenError，不消耗 max_attempts"
+    rule_2: "重試全部耗盡（retry_exhausted）計入 breaker 的 failure count"
+    rule_3: "HALF_OPEN 狀態下僅允許 1 次探針重試，不套用 max_attempts"
+
+  telemetry_events:
+    retry_attempted:
+      fields:
+        operation: string
+        attempt: number
+        max_attempts: number
+        failure_source: "FailureSource | null"
+        wait_ms: number
+      when: "每次重試前上傳（第 0 次原始呼叫不算）"
+    retry_exhausted:
+      fields:
+        operation: string
+        attempts: number
+        final_failure_source: FailureSource
+      when: "達到 max_attempts 仍失敗時上傳"
+
+  scenarios:
+    scenario_1_exponential_backoff:
+      given: "呼叫下游 API 失敗，failure_source=transient_network，已重試 2 次"
+      when: "計算第 3 次重試的等待時間"
+      then: "wait_ms = min(30000, 100 * 2^3) * (0.5 + random * 0.5) = 800 * [0.5..1.0] = 400~800ms"
+      note: "驗證退避公式正確套用 jitter"
+
+    scenario_2_fail_fast_on_auth:
+      given: "API 回傳 401 Unauthorized，偵測元件標記 failure_source=authentication"
+      when: "決定是否重試"
+      then: "立即 fail-fast，不進入退避，不計入 circuit-breaker failure count"
+      note: "authentication 類別 retry=false，避免浪費 quota"
+
+    scenario_3_circuit_open_skip:
+      given: "對應 breaker 為 OPEN 狀態，cooldown 剩 15s"
+      when: "發起重試"
+      then: "立即回傳 CircuitOpenError，不發起請求，不消耗 max_attempts"
+      note: "與 circuit-breaker 整合：OPEN 狀態下 fail-fast"
+
+  error_codes:
+    RETRY-001: "RETRY_EXHAUSTED — 達到 max_attempts 仍失敗"
+    RETRY-002: "RETRY_SKIPPED_NON_RETRYABLE — failure_source 屬 fail-fast 類別"
+    RETRY-003: "RETRY_SKIPPED_CIRCUIT_OPEN — breaker OPEN 狀態下跳過重試"
+
+  integration_points:
+    - "circuit-breaker.ai.yaml — OPEN 狀態下禁止重試，retry_exhausted 計入 failure count"
+    - "failure-source-taxonomy.ai.yaml — 依 failureSource 決定 retry/fail-fast"
+    - "timeout-standards.ai.yaml — 單次重試 timeout 不得超過剩餘 deadline"
+    - "recovery-recipe-registry.ai.yaml — retry 耗盡後交棒給 recovery recipe"