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

package/bin/uds.js

@@ -26,6 +26,8 @@ import { releaseCommand } from '../src/commands/release.js';
 import { compileStandards } from '../src/commands/compile.js';
 import { flowCreateCommand, flowListCommand, flowValidateCommand, flowDiffCommand, flowExportCommand, flowImportCommand } from '../src/commands/flow.js';
 import { generateReport } from '../src/commands/report.js';
+import { mcpCommand } from '../src/commands/mcp.js';
+import { runIntentCommand } from '../src/commands/run-intent.js';
 import { setLanguage, setLanguageExplicit, detectLanguage, t } from '../src/i18n/messages.js';
 import { maybeCheckForUpdates, formatUpdateNotice, shouldCheckUpdateForCommand } from '../src/utils/update-checker.js';
 import { config } from '../src/utils/config-manager.js';
@@ -539,4 +541,14 @@ missionCommand
   .option('-s, --state <state>', 'Filter by state')
   .action(missionListCommand);
 
+// MCP command for AI tool integration
+mcpCommand(program);
+
+// uds run <intent> — language-agnostic command proxy (XSPEC-029)
+program
+  .command('run <intent>')
+  .description('Run a project command by intent (test/lint/build/security) via uds.project.yaml')
+  .option('--dry-run', 'Show resolved command without executing')
+  .action(runIntentCommand);
+
 program.parse();

package/bundled/ai/standards/agent-communication-protocol.ai.yaml

@@ -108,6 +108,36 @@ standard:
       - field: constraints
         description: "約束條件 [string]"
 
+  hook_exit_codes:
+    description: >
+      Hook 退出碼三分類（借鑑 lintsinghua/claude-code-book Ch.7 Hooks 協議）。
+      適用於所有 DevAP/VibeOps 生成的 Claude Code hook shell 腳本。
+    codes:
+      - code: 0
+        name: pass
+        description: "Hook 通過，工具/Agent 執行繼續"
+        blocking: false
+        stdout_handling: "忽略"
+        stderr_handling: "忽略"
+      - code: 2
+        name: block
+        description: "阻止執行；stderr 輸出作為回饋文字直接注入 AI 上下文"
+        blocking: true
+        stdout_handling: "忽略"
+        stderr_handling: "作為 AI feedback 注入（支援 JSON 格式 decision:block/reason）"
+        note: "PreToolUse exit 2 → 阻止工具呼叫；Stop exit 2 → 中止 session"
+      - code: other
+        name: warn
+        description: "非阻擋性警告；記錄日誌但執行繼續（exit 1 為常用警告代碼）"
+        blocking: false
+        stdout_handling: "記錄到系統日誌"
+        stderr_handling: "顯示為 warning，不注入 AI 上下文"
+    rules:
+      - "MUST: 阻擋行為只能用 exit 2，不得用 exit 1 或其他非零代碼"
+      - "MUST: exit 2 時 stderr 必須是人類可讀的原因（推薦 JSON: {reason: string}）"
+      - "SHOULD: 軟性警告（deprecated pattern、style 違反）使用 exit 1"
+      - "MAY: exit 0 時可輸出 JSON 到 stdout（Stop hook 用 decision:block 要求 AI 繼續）"
+
   rules:
     - id: ACP-001
       trigger: "訊息缺少必要欄位"
@@ -129,6 +159,10 @@ standard:
       trigger: "建立 Handoff"
       action: "引用 artifact_id，不嵌入完整內容"
       priority: medium
+    - id: ACP-006
+      trigger: "生成 hook 腳本"
+      action: "依照 hook_exit_codes 三分類：0=pass, 2=block+feedback, 其他=warn"
+      priority: high
 
 physical_spec:
   type: checklist

package/bundled/ai/standards/anti-sycophancy-prompting.ai.yaml

@@ -0,0 +1,111 @@
+# Anti-Sycophancy Prompting Standards - AI Optimized
+# Source: core/anti-sycophancy-prompting.md
+
+id: anti-sycophancy-prompting
+meta:
+  version: "1.0.0"
+  updated: "2026-04-15"
+  source: core/anti-sycophancy-prompting.md
+  description: Techniques and rules for designing prompts that elicit genuine, critical LLM responses rather than sycophantic agreement
+
+principles:
+  socratic_critique:
+    rule: Reframe evaluation tasks as critique tasks to eliminate sycophancy incentives
+    do:
+      - Ask for fatal objections rather than approval
+      - Require technically grounded, non-trivial objections
+      - Prohibit positive opening phrases
+    do_not:
+      - Ask "is this a good idea?" without specifying critique mode
+      - Accept "Great idea, but..." as valid critique framing
+
+  anchor_prevention:
+    rule: Obtain independent LLM judgment before revealing user position
+    steps:
+      - Ask for neutral comparison without revealing preference
+      - Receive independent judgment
+      - Reveal user position
+      - Require explicit technical justification for any stance change
+
+  symmetric_output:
+    rule: Use format constraints to force balanced opposing viewpoints
+    format: "| Arguments FOR | Arguments AGAINST | — Net Recommendation: [clear stance]"
+    constraints:
+      - Both columns must have similar length (< 20% difference)
+      - Net recommendation must be explicit and may be negative
+
+  confidence_labeling:
+    rule: Require confidence scores on all recommendations
+    format: "Confidence: [1-5] — [reason for uncertainty]"
+    scale:
+      5: Validated at similar scale, high certainty
+      4: Industry standard with sufficient documentation
+      3: Reasonable inference, PoC recommended
+      2: Uncertain, Spike strongly recommended
+      1: Highly uncertain, not recommended for direct adoption
+    constraints:
+      - Confidence < 3 must include "More information needed"
+      - All major claims require confidence labeling
+
+  sycophancy_detection:
+    rule: Detect sycophantic response patterns for automated re-evaluation
+    signals:
+      - id: positive-opener
+        pattern: Response starts with agreeable phrase within first 50 tokens
+        examples: ["great", "interesting", "certainly", "of course", "absolutely"]
+      - id: position-flip
+        pattern: Model reverses stance after user reveals preference without new evidence
+      - id: risk-minimization
+        pattern: "While there are some minor issues, overall..."
+      - id: missing-quantification
+        pattern: Major recommendation lacks confidence score or specific metrics
+    trigger: If 2+ signals detected, invoke re-evaluation with Red Team framing
+
+prohibited_behaviors:
+  - id: positive-opener
+    description: Do NOT open critique with positive affirmation
+    correct_action: Start directly with analysis
+
+  - id: unsupported-flip
+    description: Do NOT reverse stance after user reveals preference without new technical evidence
+    correct_action: Maintain position or cite specific new information
+
+  - id: unquantified-risk
+    description: Do NOT describe risks as "minor" without evidence
+    correct_action: Quantify risk or explain why it is bounded
+
+  - id: missing-confidence
+    description: Do NOT provide major recommendations without confidence level
+    correct_action: Always include confidence (1-5) and uncertainty statement
+
+agent_application:
+  code_review:
+    apply: [socratic_critique, symmetric_output, sycophancy_detection]
+  architecture_advisor:
+    apply: [anchor_prevention, confidence_labeling, sycophancy_detection]
+  bug_analysis:
+    apply: [socratic_critique, confidence_labeling]
+  general_consultation:
+    apply: [symmetric_output, confidence_labeling]
+
+complete_template: |
+  You are a domain expert with no emotional investment in my satisfaction.
+  Your role is to identify flaws in my thinking, not to make me feel good.
+
+  Rules:
+  - Do NOT open with positive phrases (good, interesting, nice, certainly)
+  - Every recommendation must include a confidence level (1-5) and what you are uncertain about
+  - If my direction is wrong, say so directly
+
+  My question: [question]
+
+  First, list the incorrect assumptions I may be holding about this problem.
+  Then give your honest recommendation.
+
+checklist:
+  - Prompt does not invite agreement
+  - Positive opening phrases explicitly prohibited
+  - Independent stance obtained before revealing user preference (if applicable)
+  - Dual-column format enforced for evaluation tasks
+  - Confidence levels required on major recommendations
+  - Sycophancy detection applied to output

package/bundled/ai/standards/capability-declaration.ai.yaml

@@ -0,0 +1,113 @@
+# Capability Declaration Standard - AI Optimized
+# Source: XSPEC-037 (claude-code-book Ch.3 Fail-Closed buildTool factory)
+
+standard:
+  id: capability-declaration
+  name: Capability Declaration Standard
+  description: Fail-Closed 能力聲明 — 工具/Adapter/Agent 必須顯式聲明安全性，缺省為最保守預設
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-15"
+    source: XSPEC-037
+    description: >
+      所有工具、Adapter 和 Agent 能力預設為「不安全、需授權」。
+      開發者必須顯式聲明 isConcurrencySafe: true 才能享受並行優化。
+      「忘記設權限」的結果是保守行為而非危險行為。
+    scope: universal
+    borrowed_from: "claude-code-book Ch.3 buildTool factory, isConcurrencySafe/isReadOnly default false"
+
+  guidelines:
+    - "所有工具、Adapter、Agent 必須實作 CapabilityDeclaration（即使使用預設值）"
+    - "isConcurrencySafe 和 isReadOnly 預設為 false — 必須顯式聲明才能解鎖優化路徑"
+    - "框架必須在缺少聲明時使用 FAIL_CLOSED_DEFAULTS，並記錄警告"
+    - "聲明必須反映實際能力，虛假聲明（如謊稱 isReadOnly）視為安全漏洞"
+    - "trustLevel 影響沙箱隔離強度，不可降低至低於 userSettings 允許的等級"
+
+  interface:
+    CapabilityDeclaration:
+      fields:
+        isConcurrencySafe:
+          type: boolean
+          default: false
+          description: "是否對並行執行安全（無競態、無共享可變狀態）。預設 false。"
+          unlock: "設為 true 後可加入並行批次執行"
+        isReadOnly:
+          type: boolean
+          default: false
+          description: "是否為純讀取操作（不修改任何持久化狀態）。預設 false。"
+          unlock: "設為 true 後可跳過寫入相關的 Safety Hook 階段"
+        requiresUserConfirmation:
+          type: boolean
+          default: true
+          description: "執行前是否需要使用者明確確認。預設 true。"
+          unlock: "設為 false 後進入自動執行模式（需 userSettings 允許）"
+        trustLevel:
+          type: enum
+          values: [trusted, sandboxed, untrusted]
+          default: untrusted
+          description: "工具的信任等級，影響沙箱隔離強度"
+          mapping:
+            trusted: "內建工具或已審核插件，無沙箱限制"
+            sandboxed: "第三方工具，在受限環境中執行"
+            untrusted: "未知來源，最嚴格限制（預設）"
+
+  fail_closed_defaults:
+    isConcurrencySafe: false
+    isReadOnly: false
+    requiresUserConfirmation: true
+    trustLevel: untrusted
+    log_on_use:
+      level: warn
+      message: "[WARN] Capability not declared, using Fail-Closed defaults for: {component_name}"
+
+  well_known_declarations:
+    note: "常見工具的建議聲明（供參考，各專案可調整）"
+    examples:
+      GrepTool:
+        isConcurrencySafe: true
+        isReadOnly: true
+        requiresUserConfirmation: false
+        trustLevel: trusted
+      GlobTool:
+        isConcurrencySafe: true
+        isReadOnly: true
+        requiresUserConfirmation: false
+        trustLevel: trusted
+      FileReadTool:
+        isConcurrencySafe: true
+        isReadOnly: true
+        requiresUserConfirmation: false
+        trustLevel: trusted
+      FileEditTool:
+        isConcurrencySafe: false
+        isReadOnly: false
+        requiresUserConfirmation: true
+        trustLevel: trusted
+      BashTool:
+        isConcurrencySafe: false
+        isReadOnly: false
+        requiresUserConfirmation: true
+        trustLevel: sandboxed
+
+  enforcement:
+    on_missing_declaration:
+      action: "使用 FAIL_CLOSED_DEFAULTS"
+      log: true
+    on_false_claim:
+      description: "聲明 isReadOnly: true 但實際執行了寫入"
+      detection: "runtime 監控 + 審計日誌"
+      consequence: "記錄 CAPABILITY_MISMATCH 事件，降級至 FAIL_CLOSED_DEFAULTS"
+
+  applicable_components:
+    - "DevAP AgentAdapter（ClaudeAdapter / OpenCodeAdapter / CliAdapter）"
+    - "DevAP Tool 呼叫系統"
+    - "VibeOps ToolExecutor"
+    - "VibeOps Agent（planner / builder / evaluator 等）"
+    - "所有 MCP 工具插件"
+
+  error_codes:
+    CAP-001: "CAPABILITY_NOT_DECLARED — 使用 Fail-Closed 預設"
+    CAP-002: "CAPABILITY_MISMATCH — 實際行為與聲明不符"
+    CAP-003: "TRUST_LEVEL_INSUFFICIENT — trustLevel 低於場景要求"
+    CAP-004: "CONCURRENT_UNSAFE — 嘗試並行執行 isConcurrencySafe: false 的組件"

package/bundled/ai/standards/circuit-breaker.ai.yaml

@@ -0,0 +1,93 @@
+# Circuit Breaker Standard - AI Optimized
+# Source: XSPEC-036 (claude-code-book Ch.2 MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES)
+
+standard:
+  id: circuit-breaker
+  name: Circuit Breaker Standard
+  description: 通用斷路器模式 — 連續失敗後開路，防止 API 呼叫雪崩
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-15"
+    source: XSPEC-036
+    description: >
+      任何依賴外部 API 或重試機制的 Agent 組件都應使用斷路器保護。
+      書中實測：引入斷路器前每日浪費 ~250K API 呼叫（1279 個 session 各超過 50 次連續失敗）。
+    scope: universal
+    borrowed_from: "claude-code-book Ch.2 circuit breaker, MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES=3"
+
+  guidelines:
+    - "任何重試機制必須使用斷路器包裝，不得直接無限重試"
+    - "斷路器狀態必須透過遙測可觀測（circuit_breaker_state_change 事件）"
+    - "OPEN 狀態下的請求必須立即失敗（fail fast），不等待 timeout"
+    - "failureThreshold 預設值為 3，與 claude-code-book 及 DevAP Fix Loop 一致"
+    - "斷路器必須按照「功能單元」建立，不得全域共享單一斷路器"
+
+  states:
+    CLOSED:
+      description: "正常運作，請求正常轉發"
+      transition_to_OPEN: "連續失敗次數 >= failureThreshold"
+      reset_condition: "任一成功呼叫重設失敗計數器"
+    OPEN:
+      description: "開路，立即拒絕所有請求"
+      action: "回傳 CircuitOpenError，不實際執行"
+      transition_to_HALF_OPEN: "等待 cooldownMs 後自動進入"
+    HALF_OPEN:
+      description: "半開，允許一次探針呼叫"
+      on_probe_success: "→ CLOSED，重設計數器"
+      on_probe_failure: "→ OPEN，重設 cooldown"
+
+  interface:
+    CircuitBreaker:
+      fields:
+        name: string
+        state: "CLOSED | HALF_OPEN | OPEN"
+      methods:
+        execute: "async <T>(fn: () => Promise<T>) => Promise<T>"
+        getState: "() => CircuitBreakerState"
+        reset: "() => void  # 手動重設（管理員用）"
+
+    CircuitBreakerConfig:
+      fields:
+        failureThreshold:
+          type: number
+          default: 3
+          description: "連續失敗 N 次後開路"
+        cooldownMs:
+          type: number
+          default: 30000
+          description: "OPEN → HALF_OPEN 等待時間（毫秒）"
+        successThreshold:
+          type: number
+          default: 1
+          description: "HALF_OPEN → CLOSED 需要的連續成功次數"
+
+    CircuitOpenError:
+      fields:
+        code: "CIRCUIT_OPEN"
+        breakerName: string
+        state: "OPEN"
+        cooldownRemainingMs: number
+
+  telemetry_events:
+    circuit_breaker_state_change:
+      fields:
+        breaker_name: string
+        from_state: "CLOSED | HALF_OPEN | OPEN"
+        to_state: "CLOSED | HALF_OPEN | OPEN"
+        failure_count: number
+        timestamp: string
+      when: "每次狀態轉換時上傳"
+
+  applicable_scenarios:
+    - "DevAP Fix Loop Agent 呼叫重試"
+    - "DevAP Judge / Quality Gate 重試"
+    - "DevAP API 呼叫（LLM API 不穩定保護）"
+    - "VibeOps Feedback Loop 重試"
+    - "VibeOps FLARE 主動檢索重試"
+    - "VibeOps AutoCompact（原始靈感來源）"
+
+  error_codes:
+    CB-001: "CIRCUIT_OPEN — 斷路器開路，請求被拒絕"
+    CB-002: "PROBE_FAILED — HALF_OPEN 探針失敗，重新開路"
+    CB-003: "INVALID_CONFIG — failureThreshold 必須 >= 1"

package/bundled/ai/standards/developer-memory.ai.yaml

@@ -154,6 +154,19 @@ standard:
         Upgrade path: pitfalls → pattern → mental-model.
       priority: recommended
 
+    - id: memory-as-hint-not-conclusion
+      trigger: "before acting on any recalled memory (file paths, function names, API flags, repo state)"
+      instruction: >
+        記憶是線索，不是結論（借鑑 lintsinghua/claude-code-book 記憶驗證原則）。
+        使用記憶前必須驗證其仍然成立：
+        - 記憶提到檔案路徑 → 先確認檔案存在（Glob/Read）
+        - 記憶提到函式或 flag → 先確認仍存在（Grep）
+        - 記憶描述 repo 架構快照 → 優先信任 git log / 原始碼
+        - 若記憶內容與現況衝突 → 信任現況，標記記憶為 needs-revision
+        禁止：直接引用記憶中的具體 API/路徑/函式名稱作為事實，
+        未獨立驗證即向使用者推薦操作。
+      priority: required
+
     - id: noise-control
       trigger: surfacing memories
       instruction: >

package/bundled/ai/standards/dual-phase-output.ai.yaml

@@ -0,0 +1,108 @@
+# Dual-Phase LLM Output Standard - AI Optimized
+# Source: XSPEC-035 (claude-code-book Ch.7 AutoCompact dual-phase design)
+
+standard:
+  id: dual-phase-output
+  name: Dual-Phase LLM Output Standard
+  description: 雙階段 LLM 輸出模式 — <analysis> 思考丟棄，<summary> 結構化保留
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-15"
+    source: XSPEC-035
+    description: >
+      讓 LLM 充分推理的同時，避免思考過程累積在上下文中消耗 token 預算。
+      適用於所有需要 LLM 審查的場景：Judge、Evaluator、Guardian、AutoCompact。
+    scope: universal
+    borrowed_from: "claude-code-book Ch.7 formatCompactSummary dual-phase output"
+
+  guidelines:
+    - "所有 LLM 審查 Agent 必須要求雙階段輸出格式（<analysis> + <summary>）"
+    - "<analysis> 在後處理時必須丟棄，不得寫入持久化上下文或對話歷史"
+    - "<summary> 必須包含結構化結論欄位（decision、confidence、findings、next_action）"
+    - "若回應缺少雙階段格式，後處理器必須降級相容（完整回應視為 summary）並記錄警告"
+    - "summary 欄位命名需遵循本標準，各應用場景可擴充但不可刪減核心欄位"
+
+  format:
+    xml_tags:
+      analysis:
+        purpose: "LLM 思考草稿 — 後處理時丟棄"
+        required: true
+        content_guidance:
+          - "逐條審查邏輯"
+          - "邊界情境考量"
+          - "替代方案比較"
+      summary:
+        purpose: "結構化結論 — 後處理時保留"
+        required: true
+        core_fields:
+          decision:
+            type: enum
+            values: [approved, rejected, needs_revision]
+            required: true
+          confidence:
+            type: enum
+            values: [high, medium, low]
+            required: true
+          findings:
+            type: array
+            item_format: "[type] description"
+            required: true
+          next_action:
+            type: string
+            required: true
+        extension_fields:
+          note: "各應用場景可新增欄位，不可刪減上述核心欄位"
+          examples:
+            security: "severity: critical | high | medium | low, cwe_ids: [CWE-NNN]"
+            quality: "test_coverage: number, tech_debt_score: number"
+
+  prompt_template: |
+    You MUST respond using EXACTLY this two-phase XML structure:
+
+    <analysis>
+    [Your reasoning process — will be DISCARDED after processing]
+    - Step-by-step evaluation
+    - Edge case considerations
+    - Alternative comparisons
+    </analysis>
+
+    <summary>
+    decision: approved | rejected | needs_revision
+    confidence: high | medium | low
+    findings:
+      - [type] description
+    next_action: [recommended follow-up action]
+    </summary>
+
+    IMPORTANT: The <analysis> block is your scratchpad. Only <summary> persists.
+
+  post_processing:
+    extract_summary:
+      pattern: "<summary>([\\s\\S]*?)</summary>"
+      on_missing: fallback_to_full_response
+    discard_analysis:
+      pattern: "<analysis>([\\s\\S]*?)</analysis>"
+      action: discard
+    fallback:
+      trigger: "summary tag not found in response"
+      action: "use full response as summary content"
+      log_level: warn
+      message: "[WARN] dual-phase format missing, fallback to full response"
+
+  token_impact:
+    analysis_ratio: "50-70% of typical review response"
+    savings_per_review: "1000–3500 tokens"
+    savings_in_fix_loop_3x: "3000–10500 tokens"
+    note: "Savings accumulate in repeated review scenarios (Fix Loop, Feedback Loop)"
+
+  applicable_agents:
+    - DevAP Judge Agent
+    - VibeOps Evaluator Agent
+    - VibeOps Guardian Agent
+    - Any LLM-driven AutoCompact / summarization component
+
+  error_codes:
+    DPO-001: "summary tag missing — fallback activated"
+    DPO-002: "analysis tag missing — full response processed as-is"
+    DPO-003: "required summary field absent — parsing error"

package/bundled/ai/standards/failure-source-taxonomy.ai.yaml

@@ -0,0 +1,115 @@
+# Failure Source Taxonomy Standard - AI Optimized
+# Source: XSPEC-045 (claw-code ROADMAP Phase 2 Failure Taxonomy, DEC-035)
+
+standard:
+  id: failure-source-taxonomy
+  name: Failure Source Taxonomy Standard
+  description: 失敗來源分類法 — 在 TaskStatus（what）之上新增 failureSource（why）維度，8 類結構化失敗來源
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-16"
+    source: XSPEC-045
+    description: >
+      現有的 TaskStatus 只回答「發生了什麼」（what），failureSource 補充「為什麼失敗」（why）。
+      結構化的失敗來源使下游恢復機制（Recovery Recipe Registry, XSPEC-046）能精準匹配策略，
+      避免用同一套重試邏輯處理本質不同的失敗類型。
+    scope: universal
+    borrowed_from: "ultraworkers/claw-code ROADMAP Phase 2 Failure Taxonomy (adapted for LLM Agent context)"
+
+  guidelines:
+    - "所有失敗結果應攜帶 failureSource，使恢復策略可精準匹配"
+    - "failureSource 為 optional 欄位，不得破壞現有不含此欄位的程式碼"
+    - "在同一失敗事件中，選擇最根本的來源作為 failureSource（例如 branch_divergence 比 compilation 更根本）"
+    - "failureSource 應由偵測到失敗的元件設定（QualityGate / Adapter / SafetyHook / BranchDriftChecker）"
+    - "跨專案（DevAP / VibeOps）各自獨立定義 FailureSource type，語義保持一致"
+
+  failure_sources:
+    prompt_delivery:
+      description: "Prompt 未正確傳遞給 LLM（API 4xx、空回應、格式解析失敗）"
+      detection_hint: "API 回傳 4xx / 空回應 / JSON 解析失敗"
+      recommended_recovery: "重試或 model_switch"
+      severity_range: [critical, high]
+
+    model_degradation:
+      description: "LLM 降智或回應品質明顯下降（重複輸出、無關回應、品質驟降）"
+      detection_hint: "輸出品質評分低於基準線 / 連續重複輸出 / 評估分數 < 30"
+      recommended_recovery: "model_switch"
+      severity_range: [critical, high, medium]
+
+    branch_divergence:
+      description: "工作分支落後基底分支，可能導致合併衝突或假回歸"
+      detection_hint: "git rev-list --count HEAD..origin/{baseBranch} > 0"
+      recommended_recovery: "rebase_and_retry"
+      severity_range: [critical, high, medium]
+      note: "severity 由落後 commit 數決定：1-5 為 medium，6+ 為 high/critical"
+
+    compilation:
+      description: "編譯或型別檢查錯誤（TypeScript tsc、Go build、Rust cargo 等）"
+      detection_hint: "build / tsc / compile 指令 exit code != 0"
+      recommended_recovery: "fix_loop"
+      severity_range: [high, medium, low]
+
+    test_failure:
+      description: "測試失敗（unit / integration / system / e2e 任一層級）"
+      detection_hint: "test 指令 exit code != 0"
+      recommended_recovery: "fix_loop"
+      severity_range: [high, medium, low]
+
+    tool_failure:
+      description: "工具層失敗（MCP server 無回應、Plugin 載入失敗、CLI 工具不存在）"
+      detection_hint: "MCP / Plugin / shell 工具執行失敗或 timeout"
+      recommended_recovery: "circuit_breaker 保護後重試，或降級模式繼續"
+      severity_range: [critical, high, medium]
+
+    policy_violation:
+      description: "安全或治理策略攔截（Guardian deny、SafetyHook 阻擋、Fail-Closed 觸發）"
+      detection_hint: "SecurityDecision 為 deny / Guardian verdict 為 blocking: true"
+      recommended_recovery: "human_checkpoint（不自動重試，需人工審查）"
+      severity_range: [critical, high]
+
+    resource_exhaustion:
+      description: "資源耗盡（token 預算超限、時間 timeout、美元預算耗盡）"
+      detection_hint: "error_max_turns / error_max_budget_usd / token zone BLOCKING"
+      recommended_recovery: "degraded_mode 或 human_checkpoint"
+      severity_range: [critical, high]
+
+  types:
+    FailureSource:
+      description: "8 類失敗來源的 union type"
+      values:
+        - prompt_delivery
+        - model_degradation
+        - branch_divergence
+        - compilation
+        - test_failure
+        - tool_failure
+        - policy_violation
+        - resource_exhaustion
+
+    FailureDetail:
+      description: "結構化失敗細節"
+      fields:
+        source: FailureSource
+        raw_error: string
+        detected_by: "string  # 偵測元件名稱（quality-gate / claude-adapter / safety-hook / branch-drift）"
+        timestamp: "string  # ISO 8601"
+
+  priority_rules:
+    description: "當多個失敗來源並存時的優先級規則"
+    rules:
+      - "branch_divergence > compilation（分支漂移通常是 compilation 失敗的根因）"
+      - "policy_violation > 其他（安全優先，不嘗試繞過）"
+      - "resource_exhaustion > 其他（資源耗盡時無意義重試）"
+      - "其他情況取最先偵測到的來源"
+
+  integration_points:
+    devap:
+      files:
+        - "packages/core/src/types.ts — TaskResult.failureSource / FailureSource type"
+        - "packages/core/src/quality-gate.ts — QualityGateResult.failureSource 推斷"
+        - "packages/adapter-claude/src/claude-adapter.ts — resource_exhaustion 映射"
+    vibeops:
+      files:
+        - "src/types/index.ts — IterationRecord.failureSource（獨立定義，AGPL 隔離）"
+        - "src/runner/pipeline-runner.ts — agent:error 事件 payload"