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

package/bundled/ai/standards/standard-admission-criteria.ai.yaml

@@ -0,0 +1,107 @@
+# Standard Admission Criteria - AI Optimized
+# Source: XSPEC-070 (DEC-043 Wave 1 Governance Meta Pack)
+
+standard:
+  id: standard-admission-criteria
+  name: Standard Admission Criteria
+  description: 新標準納入 UDS 的四項條件（Evidence / Scope / Non-overlapping / AI-executable）與拒絕理由明文化
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-17"
+    status: trial
+    since: "2026-04-17"
+    expires: "2026-10-17"
+    source: XSPEC-070
+    borrowed_from: DEC-043
+    description: >
+      在 DEC-043 提出 60+ 候選新標準的背景下，需要一個明文的納入檢查清單，
+      避免標準庫膨脹（重疊、未使用）與降低品質。本標準是 UDS 的治理層 meta 標準，
+      用來「決定標準的標準」。每個候選新標準必須通過四項條件才能從 Proposed 進入 Trial。
+    scope: universal
+    industry_reference: "IETF RFC admission criteria, Python PEP process, W3C Recommendation Track"
+
+  guidelines:
+    - "所有候選新標準必須填寫 admission checklist，缺任一項視為不合格"
+    - "拒絕候選標準時必須寫下明文理由，不得以「不合適」之類籠統用詞草率結案"
+    - "通過 admission 僅代表可進 Trial，不代表直接 Active（需通過試驗期驗證）"
+    - "本標準本身也必須符合四項條件（self-applicability 原則）"
+    - "既有 66 個 Active 標準不溯及既往；新增標準自本標準發布後適用"
+
+  criteria:
+    evidence:
+      description: "至少 2 個具體使用場景（非 hypothetical）"
+      checks:
+        - "場景來自實際專案、Repo、論文或 DEC 記錄"
+        - "場景描述具體（可舉出檔案 / 函式 / commit），非泛泛而談"
+        - "至少 1 個場景來自 AsiaOstrich 三專案內部痛點或外部產業佐證"
+      rejection_example: "「未來可能用到」— 無具體場景，不通過"
+
+    scope:
+      description: "明確的作用域（哪些活動 / 哪些子專案 / 哪些情境）"
+      checks:
+        - "在 meta.scope 標示 universal / partial / uds-specific"
+        - "frontmatter 列出適用的活動類型（如 development, deployment, testing）"
+        - "若為 partial 或 uds-specific，說明不通用的原因"
+      rejection_example: "「所有場合都適用」— 過度泛化，不通過"
+
+    non_overlapping:
+      description: "與既有 UDS 標準無重大重疊（< 30% 內容重複）"
+      checks:
+        - "列出最接近的 3 個既有標準，說明如何補足差異"
+        - "若有 ≥ 30% 重疊，應改為擴充既有標準而非新增"
+        - "定義 integration_points 說明與既有標準的關係"
+      rejection_example: "與既有 `retry-standards` 80% 內容重複 — 應合併，不通過"
+
+    ai_executable:
+      description: "至少一個 DevAP QualityGate / VibeOps Agent prompt / Skill 能消費此標準"
+      checks:
+        - "定義清楚的 guidelines（bullet point，每條可驗證）"
+        - "至少包含 2 個具體 scenarios（Given-When-Then 格式）"
+        - "若需型別 / 介面，提供 interface / types 區塊"
+        - "與現有 Skill / QualityGate 的 integration_points 明確"
+      rejection_example: "只有抽象原則，無任何 AI 可執行的規則 — 不通過"
+
+  rejection_protocol:
+    rule_1: "拒絕理由必須具體指出未通過的 criterion（evidence / scope / non-overlapping / ai-executable）"
+    rule_2: "拒絕記錄寫入 `cross-project/decisions/` 或 DEC 的 rejection log 區塊"
+    rule_3: "候選者可依理由修正後重新申請（不永久封鎖）"
+    rule_4: "若拒絕理由涉及與既有標準重疊，應建議改為擴充既有標準"
+
+  self_applicability:
+    description: "本標準也必須符合四項條件"
+    evidence: "DEC-043 的 60+ 候選標準 + XSPEC-070 scenario 1-3 為具體使用場景"
+    scope: "universal，作用於 UDS 自身治理"
+    non_overlapping: "與既有 adr-standards 互補（ADR 記錄決策，admission 記錄納入條件）"
+    ai_executable: "本 yaml 的 scenarios 可被 standard-lifecycle Skill 消費"
+
+  scenarios:
+    scenario_1_new_standard_passes:
+      given: "候選標準 `retry-standards` 申請納入"
+      when: "執行 admission 檢查"
+      then: "Evidence（XSPEC-067 Scenario 1-1/1-2）、Scope（universal）、Non-overlapping（與 circuit-breaker 互補）、AI-executable（9 條 guidelines + 3 scenarios）全部通過"
+      and: "狀態從 Proposed 進入 Trial"
+
+    scenario_2_rejected_for_overlap:
+      given: "候選標準 `advanced-retry-with-jitter` 申請納入"
+      when: "Non-overlapping 檢查"
+      then: "與既有 retry-standards 重疊 > 30%，拒絕"
+      and: "拒絕理由：「80% 內容與 retry-standards 重疊，建議改為擴充既有標準的 Phase 2」"
+
+    scenario_3_rejected_for_vague_evidence:
+      given: "候選標準 `universal-best-practices` 申請納入"
+      when: "Evidence 檢查"
+      then: "無具體場景，只有「未來可能用到」類描述，拒絕"
+      and: "拒絕理由：「缺具體場景，請提供至少 2 個已發生的使用案例或產業佐證」"
+
+  error_codes:
+    ADMISSION-001: "MISSING_EVIDENCE — Evidence criterion 未通過"
+    ADMISSION-002: "SCOPE_UNDEFINED — Scope criterion 未通過"
+    ADMISSION-003: "OVERLAP_EXCEEDED — 與既有標準重疊 > 30%"
+    ADMISSION-004: "NOT_AI_EXECUTABLE — 缺 guidelines / scenarios，AI 無法消費"
+
+  integration_points:
+    - "standard-lifecycle-management.ai.yaml — 通過 admission 後從 Proposed → Trial"
+    - "skill-standard-alignment-check.ai.yaml — admission 通過的標準才能被 Skill 錨定"
+    - "adr-standards.ai.yaml — admission 決策本身可能需要 ADR 記錄"
+    - "DEC-043 — 本標準是 Wave 1 的前置條件，後續 Wave 2/3 的候選都走此流程"

package/bundled/ai/standards/standard-lifecycle-management.ai.yaml

@@ -0,0 +1,144 @@
+# Standard Lifecycle Management - AI Optimized
+# Source: XSPEC-070 (DEC-043 Wave 1 Governance Meta Pack)
+
+standard:
+  id: standard-lifecycle-management
+  name: Standard Lifecycle Management
+  description: UDS 標準生命週期狀態機（Proposed → Trial → Active → Deprecated → Archived）與 frontmatter 必要欄位
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-17"
+    status: trial
+    since: "2026-04-17"
+    expires: "2026-10-17"
+    source: XSPEC-070
+    borrowed_from: DEC-043
+    description: >
+      既有 66 個標準無明確狀態管理：新增標準沒有試驗期、過時標準無棄用路徑、廢棄標準仍被引用。
+      本標準建立五狀態機（Proposed / Trial / Active / Deprecated / Archived）與合法轉移規則，
+      並規範所有 .ai.yaml 標準必須在 frontmatter 標示 status / since / expires / supersedes。
+    scope: universal
+    industry_reference: "IETF RFC lifecycle (Proposed → Draft → Internet Standard), Python PEP states, W3C Recommendation Track"
+
+  guidelines:
+    - "所有 .ai.yaml 標準 frontmatter 必須包含 status / since 欄位"
+    - "Trial 狀態必須指定 expires（試驗期限，預設 6 個月）"
+    - "Deprecated 狀態必須指定 supersedes（替代者的 standard id 或遷移文件路徑）"
+    - "禁止反向轉移（Active → Proposed、Archived → Active 無意義）"
+    - "Trial → Active 需在 expires 前完成驗證決定；逾期未決則自動 Archived"
+
+  states:
+    Proposed:
+      description: "草案階段，尚未通過 admission-criteria"
+      allowed_locations: "DEC 文件 / XSPEC 文件 / PR branch；不進主線 ai/standards/"
+      can_be_referenced_by_skill: false
+      transition_out: ["Trial"]
+      transition_criteria:
+        Trial: "通過 standard-admission-criteria 四項條件"
+
+    Trial:
+      description: "批准但試驗中，有明確試驗期限"
+      allowed_locations: "ai/standards/，frontmatter 標記 status=trial"
+      can_be_referenced_by_skill: "true (標註 trial 狀態)"
+      default_trial_period_months: 6
+      transition_out: ["Active", "Archived"]
+      transition_criteria:
+        Active: "試驗期內被至少 2 個獨立場景實際使用且無重大修正需求"
+        Archived: "試驗期結束未達 Active 條件，或發現根本設計缺陷"
+
+    Active:
+      description: "全面採用，是 standard-of-truth"
+      allowed_locations: "ai/standards/，frontmatter 標記 status=active"
+      can_be_referenced_by_skill: true
+      transition_out: ["Deprecated"]
+      transition_criteria:
+        Deprecated: "發現更好替代標準、或標準已過時、或業界實踐改變"
+
+    Deprecated:
+      description: "標記棄用，仍可用但不建議；必須提供遷移路徑"
+      allowed_locations: "ai/standards/，frontmatter 標記 status=deprecated + supersedes"
+      can_be_referenced_by_skill: "true (Skill 應警示 deprecated 並指向 supersedes)"
+      default_migration_period_months: 6
+      transition_out: ["Archived"]
+      transition_criteria:
+        Archived: "遷移期結束，所有 downstream 已切換至替代標準"
+
+    Archived:
+      description: "已移除，僅保留歷史紀錄；不再載入"
+      allowed_locations: "ai/standards/archive/ 或 git 歷史"
+      can_be_referenced_by_skill: false
+      transition_out: []
+
+  transition_matrix:
+    description: "合法狀態轉移路徑（其他皆禁止）"
+    legal_transitions:
+      - "Proposed → Trial"
+      - "Trial → Active"
+      - "Trial → Archived"
+      - "Active → Deprecated"
+      - "Deprecated → Archived"
+    forbidden_transitions:
+      - "Active → Proposed（無意義）"
+      - "Archived → Active（應重新申請 admission）"
+      - "Deprecated → Active（應重新 Trial）"
+      - "Proposed → Active（須先 Trial 驗證）"
+
+  frontmatter_required_fields:
+    description: "所有 .ai.yaml 標準必須在 meta 區塊包含的欄位"
+    always_required:
+      status: "proposed | trial | active | deprecated | archived"
+      since: "ISO-8601 日期，進入當前狀態的日期"
+      version: "semver 字串"
+    conditional_required:
+      expires:
+        when: "status = trial"
+        format: "ISO-8601 日期，預設 since + 6 months"
+      supersedes:
+        when: "status = deprecated"
+        format: "替代標準 id（如 'retry-standards-v2'）或遷移文件路徑"
+      migration_guide:
+        when: "status = deprecated"
+        format: "遷移指引的相對路徑（選填，但強烈建議）"
+
+  scenarios:
+    scenario_1_trial_to_active:
+      given: "retry-standards 處於 trial 狀態，since=2026-04-17, expires=2026-10-17"
+      when: "2026-08-01 審視使用情況，發現 DevAP Fix Loop 和 VibeOps Builder 都已採用，無重大缺陷"
+      then: "轉移到 Active，更新 status=active, since=2026-08-01，移除 expires 欄位"
+      note: "Trial → Active 的典型路徑"
+
+    scenario_2_trial_auto_archive:
+      given: "某標準 trial 期限 2026-10-17 到期，尚未通過驗證"
+      when: "2026-10-17 自動審視"
+      then: "狀態轉為 Archived，記錄未通過原因"
+      note: "避免 Trial 標準無限期停留，造成標準庫混亂"
+
+    scenario_3_deprecated_with_migration:
+      given: "legacy-retry-logic 發現有更好的 retry-standards 取代"
+      when: "執行 deprecation"
+      then: "status=deprecated, since=2026-04-17, supersedes=retry-standards, migration_guide=docs/migrations/retry-v1-to-v2.md"
+      and: "Skill 使用 legacy-retry-logic 時顯示警告，建議遷移至 retry-standards"
+
+  telemetry_events:
+    standard_state_change:
+      fields:
+        standard_id: string
+        from_state: "proposed | trial | active | deprecated | archived"
+        to_state: "proposed | trial | active | deprecated | archived"
+        reason: string
+        timestamp: string
+      when: "每次標準狀態變更時上報（對齊 telemetry-server）"
+
+  error_codes:
+    LIFECYCLE-001: "MISSING_STATUS — frontmatter 缺 status 欄位"
+    LIFECYCLE-002: "MISSING_EXPIRES — trial 狀態缺 expires 欄位"
+    LIFECYCLE-003: "MISSING_SUPERSEDES — deprecated 狀態缺 supersedes 欄位"
+    LIFECYCLE-004: "FORBIDDEN_TRANSITION — 嘗試非法狀態轉移"
+    LIFECYCLE-005: "TRIAL_EXPIRED — Trial 期限已過但未完成 Active / Archived 決策"
+
+  integration_points:
+    - "standard-admission-criteria.ai.yaml — Proposed → Trial 必須通過 admission"
+    - "skill-standard-alignment-check.ai.yaml — Skill 僅可錨定 trial/active/deprecated 狀態標準"
+    - "adr-standards.ai.yaml — Active → Deprecated 的決策建議搭配 ADR 記錄"
+    - "telemetry-server — standard_state_change 事件匯總，用於分析標準演進"

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

@@ -0,0 +1,104 @@
+# Timeout Standards - AI Optimized
+# Source: XSPEC-067 (DEC-043 Wave 1 Reliability Pack)
+
+standard:
+  id: timeout-standards
+  name: Timeout Standards
+  description: Timeout 標準 — 層級預算（cascading 0.8×）、deadline propagation、與 circuit-breaker 整合
+
+  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: >
+      避免多層呼叫鏈中下層 timeout 大於上層（導致上層先 timeout 而下層仍在執行的資源浪費）。
+      透過 cascading 預算規則（每層 ≤ 0.8× 上層）與 deadline propagation（傳 absolute timestamp）
+      讓整條呼叫鏈都能精準 fail-fast。與 circuit-breaker 整合，timeout 計入 failure count。
+    scope: universal
+    industry_reference: "gRPC deadline propagation, Envoy timeout budgeting, Google SRE Book Ch.22"
+
+  guidelines:
+    - "多層呼叫的 timeout 必須逐層遞減，每下一層 ≤ 0.8 × 上層（預留 20% buffer）"
+    - "跨服務呼叫必須傳遞 deadline（absolute timestamp），不得只傳 relative duration"
+    - "收到請求後若 now > deadline，必須立即 fail-fast，禁止發起下游呼叫"
+    - "Timeout 觸發必須計入對應 circuit-breaker 的 failure count"
+    - "禁止下層 timeout 大於上層 timeout（違反 fail-fast，等同沒設 timeout）"
+
+  cascading_budget:
+    rule: "每下一層 timeout ≤ 0.8 × 上層 timeout"
+    rationale:
+      - "預留 20% buffer 給序列化、網路傳輸、重試等開銷"
+      - "避免上層先 timeout 而下層仍在執行（資源浪費 + 冷門錯誤）"
+      - "0.8 是業界經驗值（gRPC / Envoy 常用 0.7~0.85）"
+    example:
+      client_timeout_ms: 10000
+      gateway_timeout_ms: 8000       # 10000 * 0.8
+      service_a_timeout_ms: 6400     # 8000 * 0.8
+      downstream_db_timeout_ms: 5120 # 6400 * 0.8
+
+  deadline_propagation:
+    format: "absolute ISO-8601 timestamp（不是 relative duration）"
+    header_name: "X-Deadline"
+    rule_1: "發起呼叫前計算 deadline = now + timeout，寫入 header"
+    rule_2: "收到請求後立即檢查 now > deadline_header → 若是則 fail-fast（回 DEADLINE_EXCEEDED）"
+    rule_3: "向下游呼叫時 timeout = min(cascading_budget, deadline - now)，取兩者較小"
+    rationale: >
+      Relative duration（如 timeout=5s）無法在多層呼叫中累積扣除；
+      absolute timestamp 讓每一層都能精準計算剩餘時間，避免超時後仍發起無意義請求。
+
+  timeout_categories:
+    connect_timeout:
+      description: "建立 TCP / TLS 連線的時間上限"
+      default_ms: 5000
+      note: "通常比 request_timeout 短很多"
+    request_timeout:
+      description: "發送請求到收到完整回應的時間上限"
+      default_ms: 30000
+      note: "最常見的 timeout 類型；受 cascading 預算約束"
+    idle_timeout:
+      description: "連線閒置多久後關閉"
+      default_ms: 60000
+      note: "server 端設定；與 connection pool 配合"
+    total_deadline:
+      description: "含所有重試在內的整體上限"
+      default_ms: 60000
+      note: "retry × attempt_timeout 的總和不得超過此值"
+
+  circuit_breaker_integration:
+    rule_1: "每次 timeout 觸發視為一次失敗，計入 breaker 的 failure count"
+    rule_2: "連續 timeout 達 failureThreshold 時 breaker 進入 OPEN"
+    rule_3: "OPEN 狀態下的請求應套用極短 timeout（或直接 fail-fast），不走完整 request_timeout"
+
+  scenarios:
+    scenario_1_cascading_budget:
+      given: "Client timeout=10s，呼叫鏈 Client → Gateway → Service A → DB"
+      when: "設定各層 request_timeout"
+      then: "Gateway=8s, Service A=6.4s, DB=5.12s（每層 0.8×）"
+      note: "確保下層先 timeout，上層有機會捕獲並 fallback"
+
+    scenario_2_deadline_expired_on_receive:
+      given: "請求抵達 Service A 時 header X-Deadline 已過期"
+      when: "Service A 收到請求"
+      then: "立即回 DEADLINE_EXCEEDED，不呼叫 DB，不消耗資源"
+      note: "Deadline propagation 的 fail-fast 機制"
+
+    scenario_3_timeout_triggers_breaker:
+      given: "連續 3 次下游呼叫皆 timeout（failureThreshold=3）"
+      when: "第 4 次呼叫"
+      then: "circuit-breaker 進入 OPEN，立即回 CircuitOpenError"
+      note: "timeout 計入 breaker failure count，防止持續浪費資源"
+
+  error_codes:
+    TIMEOUT-001: "REQUEST_TIMEOUT — 單次請求超時"
+    TIMEOUT-002: "DEADLINE_EXCEEDED — 整體 deadline 已過，拒絕發起 / 處理請求"
+    TIMEOUT-003: "CASCADING_BUDGET_VIOLATION — 下層 timeout > 上層 timeout（配置錯誤）"
+
+  integration_points:
+    - "circuit-breaker.ai.yaml — timeout 計入 failure count，觸發 OPEN"
+    - "retry-standards.ai.yaml — 單次重試 timeout 不得超過 deadline - now"
+    - "failure-source-taxonomy.ai.yaml — timeout 對應 upstream_unavailable 或 tool_failure"
+    - "observability-standards（XSPEC-063 規劃中）— timeout 是 RED metric 的 Error 來源之一"

package/bundled/ai/standards/token-budget.ai.yaml

@@ -0,0 +1,108 @@
+# Token Budget Zone Standard - AI Optimized
+# Source: XSPEC-036 (claude-code-book Ch.7 four-zone threshold model)
+
+standard:
+  id: token-budget
+  name: Token Budget Zone Standard
+  description: Token 閾值四區模型 — 漸進觸發保護策略，避免突然崩潰
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-04-15"
+    source: XSPEC-036
+    description: >
+      以使用率百分比劃分四個運作區間，漸進觸發不同強度的保護策略。
+      比「打到上限才停」更優雅，為使用者提供早期預警和自動降級機會。
+    scope: universal
+    borrowed_from: "claude-code-book Ch.7 four-zone context management (0-85/85-90/90-95/95-100%)"
+
+  guidelines:
+    - "所有有 token 預算限制的執行環境必須使用四區模型監控使用率"
+    - "WARNING 區必須記錄日誌並發出可觀測事件，不得靜默"
+    - "DANGER 區必須觸發輕量保護策略（如截斷工具結果、縮減輸出預算）"
+    - "BLOCKING 區必須拒絕新請求，回傳 TOKEN_BUDGET_EXCEEDED 而非讓請求超時崩潰"
+    - "壓縮操作本身需保留足夠的輸出空間（否則壓縮本身也可能失敗）"
+
+  zones:
+    SAFE:
+      range: "0% – 84%"
+      action: "正常執行"
+      log_level: null
+
+    WARNING:
+      range: "85% – 89%"
+      action: "發出 TOKEN_BUDGET_WARNING 事件，通知 Coordinator / 使用者"
+      log_level: info
+      optional_actions:
+        - "降低 model_tier（capable → standard）"
+        - "提示使用者考慮分割任務"
+
+    DANGER:
+      range: "90% – 94%"
+      action: "觸發輕量壓縮策略"
+      log_level: warn
+      required_actions:
+        - "截斷超大工具結果（Tool Result Snip）"
+        - "縮減後續 Agent 的 maxToolRounds（建議降低 20%）"
+      optional_actions:
+        - "將重要輸出持久化到磁碟，上下文只保留摘要"
+
+    BLOCKING:
+      range: "95% – 100%"
+      action: "拒絕新請求，回傳 TOKEN_BUDGET_EXCEEDED"
+      log_level: error
+      required_actions:
+        - "停止接受新的工具呼叫或 Agent 任務"
+        - "回傳結構化錯誤（含當前使用率）"
+
+  thresholds:
+    WARNING_THRESHOLD: 0.85
+    DANGER_THRESHOLD: 0.90
+    BLOCKING_THRESHOLD: 0.95
+
+  types:
+    TokenBudgetZone:
+      values: [safe, warning, danger, blocking]
+
+    TokenBudgetStatus:
+      fields:
+        current_tokens: number
+        max_tokens: number
+        usage_ratio: number
+        zone: TokenBudgetZone
+
+    TokenBudgetExceededError:
+      fields:
+        code: "TOKEN_BUDGET_EXCEEDED"
+        current_tokens: number
+        max_tokens: number
+        usage_ratio: number
+        zone: "blocking"
+
+  post_compact_budget:
+    note: "壓縮後必須保留足夠輸出空間（書中常數參考）"
+    constants:
+      MAX_FILES_TO_RESTORE: 5
+      TOTAL_TOKEN_BUDGET: 50000
+      MAX_TOKENS_PER_FILE: 5000
+      MAX_TOKENS_PER_SKILL: 5000
+
+  telemetry_events:
+    token_budget_zone_change:
+      fields:
+        from_zone: TokenBudgetZone
+        to_zone: TokenBudgetZone
+        usage_ratio: number
+        agent_name: string
+        timestamp: string
+
+  applicable_scenarios:
+    - "DevAP 任務執行（Task token 預算監控）"
+    - "VibeOps 9-Agent Pipeline（跨 Agent 累積上下文監控）"
+    - "VibeOps PipelineMemory Snip 觸發條件"
+    - "任何有 maxTotalTokens 限制的 Agent 執行環境"
+
+  error_codes:
+    TB-001: "TOKEN_BUDGET_EXCEEDED — 已進入 BLOCKING 區，拒絕新請求"
+    TB-002: "TOKEN_BUDGET_WARNING — 已進入 WARNING 區，建議採取行動"
+    TB-003: "SNIP_FAILED — 輕量壓縮失敗，仍在 DANGER 區"

package/bundled/ai/standards/translation-lifecycle-standards.ai.yaml

@@ -0,0 +1,145 @@
+# Translation Lifecycle Standards - AI Optimized
+# Source: core/translation-lifecycle-standards.md
+
+id: translation-lifecycle-standards
+meta:
+  version: "1.0.0"
+  updated: "2026-04-20"
+  status: trial
+  since: "2026-04-20"
+  expires: "2026-10-20"
+  source: core/translation-lifecycle-standards.md
+  description: >
+    MISSING vs OUTDATED distinction, semver-aware severity (PATCH/MINOR/MAJOR),
+    and automation integration for translation sync in multi-locale projects.
+  scope: universal
+  parent: documentation-lifecycle
+
+severity_levels:
+  MISSING:
+    condition: Translation file does not exist
+    exit_code: 1
+    label: "[MISSING]"
+    action: Create before release
+  MAJOR:
+    condition: source major version ahead of translation source_version major
+    exit_code: 1
+    label: "[MAJOR]"
+    action: Update before stable release (blocker)
+  MINOR:
+    condition: source minor version ahead (same major)
+    exit_code: 0
+    label: "[MINOR]"
+    action: Update before next release (advisory)
+  PATCH:
+    condition: source patch version ahead (same major.minor)
+    exit_code: 0
+    label: "[PATCH]"
+    action: Update when convenient (advisory)
+  CURRENT:
+    condition: source_version == current source version
+    exit_code: 0
+    label: "[CURRENT]"
+    action: None
+
+frontmatter_schema:
+  required:
+    - source          # relative path to source file
+    - source_version  # source version at last sync (semver)
+    - translation_version  # translation's own version
+    - last_synced     # YYYY-MM-DD
+    - status          # current | outdated | draft
+
+trigger_conditions:
+  - event: new_standard_added
+    action: Create translation in ALL supported locales
+    severity: MISSING (blocker if absent)
+  - event: standard_patch_bump
+    action: Update frontmatter source_version + last_synced
+    severity: PATCH (advisory)
+  - event: standard_minor_bump
+    action: Translate new content + update frontmatter
+    severity: MINOR (advisory, before next release)
+  - event: standard_major_bump
+    action: Full retranslation + update frontmatter
+    severity: MAJOR (blocker, before current release)
+
+automation:
+  pre_commit_hook:
+    file: .githooks/pre-commit
+    trigger: core/*.md files staged
+    behavior: warn on OUTDATED, never block commit
+    setup: ./scripts/install-hooks.sh
+  release_gate:
+    command: bash scripts/check-translation-sync.sh
+    exit_1_conditions: [MISSING, MAJOR]
+    exit_0_conditions: [MINOR, PATCH, CURRENT]
+  bump_version_integration:
+    command: runs check-translation-sync.sh after version files updated
+    purpose: immediate feedback on translation health at bump time
+
+rules:
+  - id: missing-is-blocker
+    trigger: running release gate check
+    instruction: >
+      Any translation file that does not exist is a release blocker.
+      The release gate must exit 1 if MISSING count > 0.
+    priority: required
+
+  - id: major-gap-is-blocker
+    trigger: running release gate check
+    instruction: >
+      If a translation's source_version MAJOR is behind the current source MAJOR,
+      the translation may be fundamentally incorrect. Exit 1.
+    priority: required
+
+  - id: minor-patch-advisory
+    trigger: running release gate check
+    instruction: >
+      MINOR and PATCH version gaps are advisory. Show warnings but exit 0.
+      Users can still read the translation; it is slightly stale, not wrong.
+    priority: required
+
+  - id: frontmatter-required
+    trigger: creating or updating a translation file
+    instruction: >
+      Every translation file MUST start with YAML frontmatter containing:
+      source, source_version, translation_version, last_synced, status.
+      Files without frontmatter are flagged as MISSING_FRONTMATTER.
+    priority: required
+
+  - id: update-on-source-change
+    trigger: modifying a source standard in core/
+    instruction: >
+      After modifying a core standard, check if translations need updating.
+      At minimum update frontmatter source_version + last_synced for PATCH changes.
+      For MINOR/MAJOR changes, update translated content too.
+    priority: recommended
+
+scenarios:
+  - id: new-standard
+    given: A new standard is added to core/ with no translations
+    when: check-translation-sync.sh runs
+    then: Reports [MISSING] for each locale; exits 1
+    error_code: TRANS-001
+
+  - id: patch-bump
+    given: Source goes from 1.0.0 to 1.0.1; translation source_version=1.0.0
+    when: check-translation-sync.sh runs
+    then: Reports [PATCH] advisory; exits 0
+
+  - id: major-gap
+    given: Source is at 2.0.0; translation source_version=1.5.0
+    when: check-translation-sync.sh runs
+    then: Reports [MAJOR] blocker; exits 1
+    error_code: TRANS-002
+
+integration_points:
+  - system: check-translation-sync.sh
+    role: primary automation; enforces severity levels
+  - system: .githooks/pre-commit
+    role: commit-time reminder when core/ files staged
+  - system: bump-version.sh
+    role: release-time advisory snapshot
+  - system: pre-release-check.sh
+    role: final gate before npm publish (calls check-translation-sync.sh)