universal-dev-standards 5.14.0 → 5.15.1

package/bundled/locales/zh-TW/core/ai-instruction-standards.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/ai-instruction-standards.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-01-14
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-05-28
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: [English](../../../core/ai-instruction-standards.md) | 繁體中文
 
-**版本**: 1.0.0
-**最後更新**: 2026-01-14
+**版本**: 1.1.0
+**最後更新**: 2026-05-28
 **適用範圍**: 所有使用 AI 編碼助手的專案
 
 ---
@@ -151,6 +151,130 @@ AI 指令檔案通常混合兩種類型的內容：
 
 ---
 
+## 國際化（i18n）
+
+AI 指令檔常需提供多語言版本——既為了國際採用者，也為了非英語母語維護者主導的專案。本章節定義多語言指令檔的組織、驗證與安裝規則。
+
+### AI 指令檔的範圍
+
+本標準涵蓋兩個層級的 AI 指令檔：
+
+| 層級 | 範例 | i18n 模式 |
+|------|------|----------|
+| **Root 層** | `CLAUDE.md`、`.cursorrules`、`.windsurfrules`、`.opencode/instructions.md` | 單檔內以 inline 段落分語言（例：`## 中文` / `## English`）|
+| **Skill 層** | Claude Code `.claude/skills/{name}/SKILL.md`、OpenCode plugin instructions | Canonical（英文）+ `locales/{lang}/` 變體 |
+
+> 注意：skill 層的多檔結構主要對 Claude Code 適用。其他工具是 root 單檔；對它們只有下方「分層語言策略」與「Chimera 防範」規則適用。
+
+### 分層語言策略
+
+每份 AI 指令檔概念上有 **4 層**，各層語言責任不同：
+
+| 層 | 內容 | Canonical (en) | Locale ({lang}) | 為何分這層 |
+|----|------|---------------|----------------|-----------|
+| **L1 — Metadata** | YAML frontmatter `description`、`argument-hint`、`allowed-tools` | **必須英文** | **必須對應 locale 語言** | AI 觸發訊號；英文 token 效率最高 + 訓練語料密度高 |
+| **L2 — 指令（Instructions）** | 對 AI 的命令式規則（steps、behavior、allowed-tools 理由）| **必須英文** | 對應 locale 語言（可選；可保留英文）| AI 讀英文指令最精準；只有當維護者需要以母語讀指令時才翻譯 |
+| **L3 — 輸出範本（Output Templates）** | 範例輸出、回應格式、情境範本 | 英文（canonical 鎖定英文）| **強制對應 locale**（mandatory）| **唯一直接影響 AI 輸出語言的層**——AI 會繼承所見範本的語言 |
+| **L4 — 人類文件** | 維護者註解、貢獻者說明、walkthrough | 英文 | 對應 locale 語言（強烈建議）| 給人類維護者讀，AI 不讀 |
+
+**關鍵 insight**：L1（description）是 AI 用來決定「**是否呼叫**」此 skill 的觸發訊號——它**不**影響 AI 之後說什麼。L3（output template）才是控制 AI 輸出語言的唯一開關，因為 AI 會慣性沿用範本語言。**i18n 強制檢查應該聚焦在 L3——加強 L1 的強制（例如強制 description 用 locale）是常見錯誤，它解決的是錯誤的問題。**
+
+### Canonical / Locale 檔案結構
+
+UDS 標準與 skill 的 locale 變體結構：
+
+```text
+core/{name}.md                              ← canonical（英文）— single source of truth
+core/{name}.ai.yaml                         ← canonical 結構化（英文）
+locales/{lang}/core/{name}.md               ← locale 變體（匹配 lang）
+locales/{lang}/ai/standards/{name}.ai.yaml  ← locale .ai.yaml（匹配 lang）
+skills/{name}/SKILL.md                      ← canonical skill（英文）
+locales/{lang}/skills/{name}/SKILL.md       ← locale skill 變體
+```
+
+**命名慣例**：使用 BCP 47 語言標籤——`zh-TW`、`zh-CN`、`ja`、`ko`、`en-US` 等。
+
+### Locale 變體 Frontmatter 必填欄位
+
+每個 locale 變體必須含追蹤用 frontmatter，方便偵測 drift：
+
+```yaml
+---
+name: {與 canonical 同名}
+source: {指回 canonical 的相對路徑}
+source_version: {翻譯時 canonical 的版本}
+translation_version: {本翻譯的版本}
+---
+```
+
+當 canonical 更新（bump `source_version`），locale 維護者應重新同步並 bump `translation_version`。若 `source_version` 落後超過 2 個 minor 版本，會觸發 drift 警告（見「Chimera 防範」）。
+
+### 責任邊界
+
+| 角色 | 擁有 | 必須做 |
+|------|------|--------|
+| **Canonical 擁有者** | `core/{name}.md`、`core/{name}.ai.yaml`、`skills/{name}/SKILL.md` | 維持 L1/L2/L3/L4 為英文；每次 breaking change 時 bump `source_version` |
+| **Locale 維護者** | `locales/{lang}/...` 檔 | `translation_version` 對齊 `source_version`；翻譯 L1（必）、L2（選）、L3（必）、L4（建議）|
+| **採用者（下游專案）** | 自己的 `.claude/skills/`、`CLAUDE.md` 等 | 用 `uds install --locale {lang}` 安裝；**絕不**手動修改 canonical 檔（要客製化請用 locale 變體或 overlay）|
+
+### Chimera 防範
+
+**Chimera**（混血兒）指違反分層規則、混合語言的檔案。常見 chimera 模式：
+
+| 模式 | 嚴重度 | 偵測方式 |
+|------|--------|----------|
+| Canonical 檔的 `description` 含 CJK | ❌ Error | Lint：`canonical:description-must-be-ascii` |
+| Locale 變體的 `description` 是純 ASCII | ❌ Error | Lint：`locale:description-must-match-language` |
+| Locale 變體缺 `source:` frontmatter | ❌ Error | Lint：`locale:must-have-source-frontmatter` |
+| Canonical L3 output template 含非英文範例回應 | ⚠️ Warn | Lint：`canonical:l3-language-consistency` |
+| 採用者 `.claude/skills/` 的檔案與 canonical 和任何 locale 變體都不同 | ⚠️ Warn | Sync check：`adopter:must-match-installed-locale` |
+| `translation_version` 落後 `source_version` 超過 2 minor | ⚠️ Warn | Drift check |
+
+Pre-commit / CI lint 強制 error 級規則；warn 級規則只在 dashboard 揭露不阻擋。
+
+### 採用者安裝模式
+
+採用者透過 UDS CLI 安裝指令檔：
+
+```bash
+uds install --locale zh-TW   # 以繁體中文安裝 skills 與 standards
+```
+
+**Locale 解析優先順序**：
+1. `--locale` CLI 旗標（最高）
+2. `.uds/install.yaml` 的 `locale:` 欄位
+3. 環境變數 `UDS_LOCALE`
+4. Fallback：`en`
+
+**Locale 不存在時的 fallback 行為**：當索求的 locale 對某個 skill 沒有變體時，CLI：
+- 安裝 canonical（英文）檔案
+- 發出 WARN 列出哪些 skill fallback 了
+- **不**阻斷安裝
+
+這確保覆蓋率不完整時採用者仍能用。採用者可查 `locales/COVERAGE.md` 知道哪些有翻譯、哪些沒有。
+
+### 遷移：已有 chimera 的採用者
+
+若採用者已手動修改過專案中的 canonical 檔（例：在 `.claude/skills/` 翻譯了描述）：
+
+1. **辨識 chimera**：比對採用者檔案與 UDS canonical / canonical 的 locale 變體。
+2. **安裝正確變體**：執行 `uds install --locale {lang}` 替換 chimera 為 locale 變體。
+3. **保留專案級客製**：若 chimera 含合理的專案級客製（非翻譯），抽出為 overlay 或記錄到客製化日誌（例：`UDS-CUSTOMIZATION.md`）。
+4. **丟棄純翻譯**：chimera 中純翻譯部分直接丟棄——locale 變體會取代它。
+
+### 快速參考
+
+| 動作 | 何時 | 工具 / 檔案 |
+|------|------|------------|
+| 新增語言支援 | 想支援新 locale | 建立 `locales/{lang}/...` 對應 canonical 結構 |
+| 更新 canonical | 改進英文 source | Bump `source_version`；通知 locale 維護者 |
+| 翻譯 / 同步 locale | 新增或更新 locale 內容 | Bump `translation_version`；參照當前 `source_version` |
+| 檢查覆蓋率 | 定期 review | 看自動產生的 `locales/COVERAGE.md` |
+| 帶 locale 安裝 | 採用者初設或重新同步 | `uds install --locale {lang}` |
+| 跑 i18n lint | Commit 前 / CI | `uds lint --i18n` |
+
+---
+
 ## 維護檢查清單
 
 在提交 AI 指令檔案的變更之前：
@@ -205,6 +329,7 @@ grep -n "npm\|yarn\|pip\|cargo" CLAUDE.md | head -20
 | 版本 | 日期 | 變更 |
 |------|------|------|
 | 1.0.0 | 2026-01-14 | 初始發布 |
+| 1.1.0 | 2026-05-28 | 新增 i18n 章節；範圍延伸至 skill 層級檔案 |
 
 ---
 

package/bundled/locales/zh-TW/core/knowledge-graph-memory.md

@@ -0,0 +1,127 @@
+---
+source: ../../../core/knowledge-graph-memory.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-30
+status: current
+---
+
+# Knowledge Graph Memory Standards（知識圖記憶標準）
+
+> **語言**: [English](../../../core/knowledge-graph-memory.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-05-30
+**適用範圍**: 在「程式碼 + 規格／決策」語料上使用 AI 助手的專案
+**Scope**: uds-specific
+
+---
+
+## 目的
+
+本標準定義一套**關係 schema**，讓規格、決策與程式碼能以圖的方式遍歷——回答如*「我若修改 `execute()`，會影響哪些規格與決策？」*的問題。它與向量／語意記憶（找出*相似*的產物）互補，提供**結構遍歷**（找出*有關聯*的產物）。
+
+此 schema 與引擎無關：以純 Markdown front-matter 表達，AI 助手可直接讀取（降級模式），亦可由可選的圖引擎（如 [CodeSage](https://github.com/AsiaOstrich/CodeSage)）索引以進行多跳查詢（服務模式）。
+
+---
+
+## 快速參考
+
+### 關係 Front-Matter Schema
+
+在規格／決策文件的 YAML front-matter 中加入以下可選欄位：
+
+| 欄位 | 型別 | 方向 | 意義 |
+|------|------|------|------|
+| `related` | id 列表 | 無向 | 鬆散關聯的產物 |
+| `impacts` | spec id 列表 | this → spec | 此決策改動那些規格 |
+| `impacted_by` | decision id 列表 | decision → this | 那些決策改動此規格 |
+| `supersedes` | decision id 列表 | this → decision | 此決策取代那些決策 |
+| `implements` | spec id 列表 | code/spec → spec | 此產物實作那些規格 |
+
+id 為產物識別碼（如 `XSPEC-205`、`DEC-062`、`ADR-001`）。內文的 `[[XSPEC-NNN]]` wiki 連結是等效但較低保真度的訊號。
+
+### 節點種類
+
+| 前綴 | 節點種類 |
+|------|---------|
+| `XSPEC-*` / `SPEC-*` | Spec |
+| `DEC-*` / `ADR-*` | Decision |
+| 函式／類別／模組（來自程式碼）| Code 節點 |
+
+---
+
+## 1. Schema
+
+### 1.1 Front-Matter 範例
+
+```markdown
+---
+id: XSPEC-205
+title: Agent/Role Spec SDD Variant
+status: Implemented
+impacted_by: [DEC-062]
+related: [XSPEC-204]
+---
+```
+
+```markdown
+---
+id: DEC-069
+title: CodeSage Architecture
+date: 2026-05-27
+supersedes: [DEC-057]
+impacts: [XSPEC-237]
+---
+```
+
+### 1.2 邊的推導
+
+| 文件上的 front-matter | 推導出的邊 |
+|----------------------|-----------|
+| Decision `impacts: [SPEC]` | `IMPACTS`（Decision → Spec）|
+| Spec `impacted_by: [DEC]` | `IMPACTS`（Decision → Spec）|
+| Decision `supersedes: [DEC]` | `SUPERSEDES`（Decision → Decision）|
+| Decision 內文 `[[XSPEC-NNN]]` 連結 | `IMPACTS`（Decision → Spec）|
+
+邊是**冪等**的：同一關係從兩端宣告（決策的 `impacts` 與規格的 `impacted_by`）只產生一條邊，不會重複。
+
+---
+
+## 2. 兩種運作模式
+
+本標準的消費者**必須**同時支援兩種模式：
+
+### 2.1 降級模式（無引擎）
+
+AI 助手讀取目標文件，沿其 front-matter／`[[ref]]` 連結讀取被連結檔案，手動組出影響鏈。隨時可用；受限於助手能讀取的檔案數。
+
+### 2.2 服務模式（有圖引擎）
+
+語料被索引進圖引擎；助手送出單一多跳查詢（如 `impact-analysis { nodeId, maxHops }`）取得完整鏈——包含降級模式會漏掉的跨域連結（code → spec → decision）。
+
+> 正確實作在兩種模式下產生**相同形狀的答案**；服務模式只是更快更完整，並非本質不同。
+
+---
+
+## 3. Confidence（可選）
+
+節點**可**帶 `confidence`，範圍 `[0.1, 1.0]`。回饋訊號（測試通過／失敗、人工修正、狀態變更）演化 confidence，讓讀取時優先浮現最被強化的產物。confidence 有下限（永不歸零），使連續失敗無法抹除重要節點。此為自我演化圖記憶（SAGE）的基礎。
+
+---
+
+## 4. 規則
+
+1. 關係欄位**可選**且**附加**——缺少永不破壞工具。
+2. 允許參照尚不存在的 id；它們成為 stub 節點，待目標文件出現時解析。
+3. 從*擁有*該關係的一端宣告（決策擁有 `impacts`/`supersedes`；規格擁有 `impacted_by`），但兩端皆接受。
+4. 圖引擎為 **opt-in**。未設定引擎時工具**必須**優雅降級為 Markdown 讀取。
+5. 向量／語意記憶為**互補**而非取代——結構用圖遍歷，相似用向量。
+
+---
+
+## 相關標準
+
+- [Project Context Memory](project-context-memory.md) — 每專案長期事實
+- [Developer Memory](developer-memory.md) — 通用、可攜偏好
+- [ADR Standards](adr-standards.md) — 餵入 Decision 節點的決策紀錄格式

package/bundled/locales/zh-TW/core/self-review-protocol.md

@@ -1,6 +1,14 @@
+---
+source: ../../../core/self-review-protocol.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+status: current
+---
+
 # Self-Review Protocol（自我審查協議）
 
-> [English](../../../core/self-review-protocol.md) | **繁體中文**
+> **語言**: [English](../../../core/self-review-protocol.md) | 繁體中文
 
 **版本**: 1.0.0
 **最後更新**: 2026-05-26

package/bundled/locales/zh-TW/skills/ac-coverage/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: ac-coverage
+source: ../../../../skills/ac-coverage/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+scope: universal
+description: "[UDS] 分析驗收條件（AC）與測試之間的追蹤關係並產生覆蓋率報告"
+allowed-tools: Read, Grep, Glob
+argument-hint: "[規格檔案路徑]"
+---
+
+# AC 覆蓋率助手
+
+> **語言**: [English](../../../../skills/ac-coverage/SKILL.md) | 繁體中文
+
+分析驗收條件（AC）與測試之間的追蹤關係，並產生覆蓋率報告。
+
+## 與 `/coverage` 的差異
+
+| 面向 | `/coverage` | `/ac-coverage` |
+|------|-------------|----------------|
+| **範圍** | 程式碼層級（行數／分支／函式） | 需求層級（AC 對應測試） |
+| **輸入** | 原始碼 + 測試執行器 | SPEC 檔案 + 測試標註 |
+| **問題** | 「程式碼測試了多少？」 | 「哪些 AC 有測試？」 |
+| **輸出** | 覆蓋率百分比 | 追溯矩陣 + 缺口報告 |
+
+## 工作流程
+
+1. **解析 SPEC** — 從規格檔案抽取 AC 定義（AC-1, AC-2, ...）
+2. **掃描測試** — 依標準連結慣例搜尋測試檔中的 `@AC` 與 `@SPEC` 標註
+3. **建立矩陣** — 將每個 AC 對應到其測試引用（檔案、測試名稱、行號）
+4. **分類狀態** — 將每個 AC 標記為 ✅ 已覆蓋、⚠️ 部分覆蓋、或 ❌ 未覆蓋
+5. **計算覆蓋率** — 套用公式：`覆蓋率 % = (已覆蓋 + 部分覆蓋 × 0.5) / 總數 × 100`
+6. **產生報告** — 輸出標準化的 Markdown 報告
+
+## 連結標註慣例
+
+測試**必須**使用標準標註引用其來源 AC：
+
+```typescript
+// TypeScript / JavaScript
+describe('AC-1: 使用者以有效憑證登入', () => {
+  // @AC AC-1
+  // @SPEC SPEC-001
+  it('登入成功後應導向儀表板', () => { ... });
+});
+```
+
+```python
+# Python
+class TestAC1_UserLogin:
+    """AC-1: 使用者以有效憑證登入
+    @AC AC-1
+    @SPEC SPEC-001
+    """
+    def test_redirect_to_dashboard(self): ...
+```
+
+```gherkin
+# BDD Feature
+@SPEC-001 @AC-1
+Scenario: 使用者以有效憑證登入
+```
+
+## 覆蓋率門檻
+
+| 門檻 | 預設值 | 強制等級 |
+|------|--------|----------|
+| **簽入（Check-in）** | 80% | feature branch 合併必要條件 |
+| **發布（Release）** | 100% | 正式環境發布必要條件 |
+| **警告（Warning）** | 60% | 觸發覆蓋率警告 |
+
+門檻可透過 `--threshold` 參數或專案設定檔調整。
+
+## 四層追溯（`--full` 模式）
+
+使用 `--full` 標記將追溯從 2 層（AC→Test）擴展為 4 層。
+
+### 追溯層次
+
+```
+Layer 0：需求 / 使用者故事 (REQ)
+    ↓ （定義）
+Layer 1：驗收條件 (AC)
+    ↓ （@AC 標註）
+Layer 2：測試案例
+    ↓ （覆蓋）
+Layer 3：原始碼 (@implements)
+```
+
+### 各層標註慣例
+
+```typescript
+// Layer 3→1：程式碼引用 AC
+// @implements AC-1, AC-2
+function authenticate(user: string, pass: string) { ... }
+```
+
+```markdown
+<!-- Layer 0→1：SPEC 中的需求 -->
+## Requirements
+### REQ-1：使用者驗證
+- AC-1: 給定有效憑證，當登入時，則驗證通過
+- AC-2: 給定無效憑證，當登入時，則被拒絕
+```
+
+### 完整追溯報告
+
+```markdown
+## 四層追溯矩陣
+
+| 需求 | AC | 測試 | 程式碼 | 狀態 |
+|------|-----|------|--------|------|
+| REQ-1 | AC-1 | auth.test.ts:15 | auth.ts:42 | ✅ 完整 |
+| REQ-1 | AC-2 | auth.test.ts:30 | auth.ts:58 | ✅ 完整 |
+| REQ-2 | AC-3 | — | dashboard.ts:10 | ⚠️ 缺測試 |
+| REQ-3 | AC-4 | export.test.ts:5 | — | ⚠️ 缺程式碼 |
+
+### 缺口摘要
+- Layer 0→1: 2 個需求未對應 AC
+- Layer 1→2: 1 個 AC 未對應測試
+- Layer 2→3: 0 個測試未對應程式碼
+- Layer 3→1: 3 個程式碼檔案未對應 AC
+```
+
+### 反向追溯
+
+使用 `--trace-code <path>` 從程式碼反向追溯到需求。
+
+```bash
+/ac-coverage --trace-code src/auth.ts
+# 輸出：
+# src/auth.ts:42 → @implements AC-1 → REQ-1 (SPEC-AUTH-001)
+# src/auth.ts:58 → @implements AC-2 → REQ-1 (SPEC-AUTH-001)
+```
+
+## 報告格式
+
+產生的報告遵循 `core/acceptance-criteria-traceability.md` 的標準格式：
+
+```markdown
+# AC 覆蓋率報告
+
+**規格**: SPEC-001 — 功能名稱
+**產生時間**: 2026-03-18
+**覆蓋率**: 75% (6/8 AC)
+
+## 摘要
+
+| 狀態 | 數量 | 百分比 |
+|------|------|--------|
+| ✅ 已覆蓋 | 5 | 62.5% |
+| ⚠️ 部分覆蓋 | 2 | 25.0% |
+| ❌ 未覆蓋 | 1 | 12.5% |
+
+## 追溯矩陣
+
+| AC-ID | 描述 | 狀態 | 測試引用 |
+|-------|------|------|----------|
+| AC-1 | 以有效憑證登入 | ✅ | auth.test.ts:15 |
+| AC-2 | 拒絕無效憑證 | ✅ | auth.test.ts:32 |
+| ...   | ...           | ... | ... |
+
+## 缺口
+- **AC-8**: 社群登入 — 因 OAuth sandbox 未就緒受阻
+
+## 行動項目
+1. [ ] AC-8：設定 OAuth sandbox（預計時程：待定）
+```
+
+## 下一步引導
+
+`/ac-coverage` 完成後，AI 助手應建議：
+
+> **AC 覆蓋率分析完成。建議下一步：**
+> - 覆蓋率達標 → 執行 `/checkin` 品質關卡
+> - 有未覆蓋 AC → 執行 `/derive-tdd` 補齊測試 ⭐ **推薦**
+> - 有部分覆蓋 AC → 檢查缺少的邊界情況
+> - 需要完整追溯 → 執行 `/ac-coverage --full`
+> - 反向追溯 → 執行 `/ac-coverage --trace-code <path>`
+
+## 參考
+
+- 核心標準：[acceptance-criteria-traceability.md](../../../../core/acceptance-criteria-traceability.md)
+- SPEC：[SPEC-AC-COVERAGE.md](../../../../docs/specs/skills/SPEC-AC-COVERAGE.md)
+- 相關：[test-coverage-assistant](../test-coverage-assistant/SKILL.md)（程式碼層級覆蓋率）
+- 相關：[checkin-assistant](../checkin-assistant/SKILL.md)（品質關卡）
+
+## AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/ac-coverage`](../../../../skills/commands/ac-coverage.md#ai-agent-behavior--ai-代理行為)

package/bundled/locales/zh-TW/skills/ai-collaboration-standards/SKILL.md

@@ -3,8 +3,12 @@ name: ai-collaboration-standards
 source: ../../../../skills/ai-collaboration-standards/SKILL.md
 source_version: 1.1.0
 translation_version: 1.1.0
-last_synced: 2026-01-25
+last_synced: 2026-05-28
 status: current
+description: |
+  [UDS] 防止 AI 幻覺、確保分析程式碼或提建議時以證據為基礎的回應。
+  Use when: analyzing code, making recommendations, providing options, or when user asks about confidence/certainty.
+  Keywords: certainty, assumption, inference, evidence, source, 證據, 假設, 推論.
 ---
 
 # AI 協作標準