universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-TW/core/spec-driven-development.md

@@ -1,8 +1,9 @@
 ---
 source: ../../../core/spec-driven-development.md
-source_version: 2.2.0
-translation_version: 2.2.0
-last_synced: 2026-04-22
+source_version: 2.3.0
+translation_version: 2.3.0
+last_synced: 2026-06-10
+source_hash: 08dd8c2bee20
 status: current
 ---
 
@@ -19,9 +20,9 @@ status: current
 
 ## 摘要
 
-規格驅動開發 (SDD) 是一種「文件優先」的開發方法論，強調在編寫任何程式碼之前，先定義清晰、結構化的規格（Specification）。這種方法特別適合 AI 輔助開發，因為高品質的規格能顯著降低 AI 的幻覺並提高程式碼生成的準確度。
+規格驅動開發（SDD）是一種 AI 時代的方法論（2025 年起），有別於傳統的 TDD/BDD/ATDD。它確保所有變更在實作前都透過規格進行規劃、記錄與核准。核心原則是**「規格優先，程式碼其次」**——沒有對應的已核准規格，就不能進行任何功能性程式碼變更。
 
-SDD 的核心流程：**討論 → 規格提案 → 規格審查 → 實作 → 驗證 → 歸檔**。
+SDD 在不同的成熟度層級運作：規格優先（完成後丟棄）、規格錨定（貫穿整個演進過程維護）、規格即來源（規格是唯一來源，程式碼自動生成）。此方法論使用正向推演（Forward Derivation）從規格生成測試產物（BDD 場景、TDD 骨架、契約）。
 
 ---
 
@@ -33,10 +34,16 @@ SDD 的核心流程：**討論 → 規格提案 → 規格審查 → 實作 →
 
 | 面向 | 說明 |
 |------|------|
-| **核心原則** | 先規格，後實作 (Spec First) |
-| **主要產物** | Markdown 規格文件 (`docs/specs/`) |
-| **參與者** | 架構師、開發者、AI 助手 |
-| **驗證方式** | 規格審查、正向推演 (Forward Derivation) |
+| **核心工作流程** | 討論 → 提案 → 審查 → 實作 → 驗證 → 歸檔 |
+| **核心原則** | 規格優先，程式碼其次 (Spec First, Code Second) |
+| **AC 格式** | Given/When/Then（GWT，預設——啟用 BDD 推演）**或** EARS 記法（選用，XSPEC-263） |
+| **測試生成** | 正向推演（/derive-bdd、/derive-tdd、/derive-all） |
+| **成熟度層級** | 規格優先、規格錨定、規格即來源 |
+| **工具** | OpenSpec、Spec Kit、手動（基於檔案） |
+| **I/O 契約** | 可選的結構化輸入/輸出定義，用於跨規格資料流 |
+| **假設** | 追蹤假設（[Assumption]）與待釐清項目（[Need Confirmation]）的必填章節 |
+| **AC YAML Sidecar** | 建議在 AC 超過 3 條時使用 .ac.yaml（機器可讀 AC） |
+| **AI Agent 行為** | 可選章節，用於在規格中定義 Agent 角色、規則、品質檢查、限制 |
 
 ## AC 格式
 
@@ -67,6 +74,7 @@ UDS 支援兩種 AC 記法。**GWT 為預設與首選**（Forward Derivation／B
 
 ## 相關標準
 
-- [測試驅動開發](test-driven-development.md)
+- [正向推演標準](forward-derivation-standards.md)
 - [反向工程標準](reverse-engineering-standards.md)
-- [正向推演標準](forward-derivation-standards.md)
+- [測試驅動開發](test-driven-development.md)
+- [行為驅動開發](behavior-driven-development.md)

package/bundled/locales/zh-TW/core/supply-chain-attestation.md

@@ -0,0 +1,131 @@
+---
+source: ../../../core/supply-chain-attestation.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: f2d6deb8373b
+status: current
+---
+
+# 供應鏈證明（Attestation）標準
+
+> **Language**: [English](../../../core/supply-chain-attestation.md) | 繁體中文
+
+## 概述
+
+軟體供應鏈攻擊（如 SolarWinds、Log4Shell 擴散）利用「原本打算交付的東西」與「實際交付的東西」之間的落差。SBOM + SLSA provenance 透過建立從 source commit 到部署產物之間可驗證的鏈條來彌補這個落差。
+
+## SBOM（Software Bill of Materials，軟體物料清單）
+
+CycloneDX JSON 格式是建議採用的 SBOM 標準（SPDX 亦受支援）。
+
+### 產生
+
+```bash
+# Install CycloneDX npm plugin
+npm install -g @cyclonedx/cyclonedx-npm
+
+# Generate from package-lock.json (NOT package.json)
+cyclonedx-npm --output-format JSON \
+              --output-file sbom.cdx.json \
+              --package-lock-only
+```
+
+### 驗證
+
+```bash
+# Count components
+jq '.components | length' sbom.cdx.json
+
+# Check for GPL licences
+jq '.components[] | select(.licenses[].license.id | test("GPL"))' sbom.cdx.json
+```
+
+## SLSA Provenance
+
+[SLSA（Supply chain Levels for Software Artefacts）](https://slsa.dev) 定義了四個等級：
+
+| 等級 | 要求 |
+|-------|-------------|
+| L1 | Provenance 存在，自我簽署 |
+| L2 | Provenance 託管，由託管建置服務簽署（GitHub Actions OIDC） |
+| L3 | Provenance 來自強化、完全隔離的建置平台 |
+| L4 | 兩方審查 + hermetic builds |
+
+**建議最低標準：內部發布採 SLSA L1**，**公開發布採 L2**。
+
+### SLSA L1 Provenance（GitHub Actions）
+
+```yaml
+- name: Generate SLSA L1 provenance
+  run: |
+    IMAGE_DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' "your-app:commercial-${VERSION}" 2>/dev/null || echo "N/A")
+    cat > provenance.json << PROVEOF
+    {
+      "_type": "https://in-toto.io/Statement/v0.1",
+      "predicateType": "https://slsa.dev/provenance/v0.2",
+      "subject": [{"name": "app-commercial-${VERSION}", "digest": {"sha256": "$(sha256sum app-commercial-${VERSION}.tar.gz | cut -d' ' -f1)"}}],
+      "predicate": {
+        "buildType": "https://github.com/Attestations/GitHubActionsWorkflow@v1",
+        "builder": {"id": "https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"},
+        "invocation": {
+          "configSource": {
+            "uri": "git+https://github.com/${GITHUB_REPOSITORY}",
+            "digest": {"sha1": "${GITHUB_SHA}"},
+            "entryPoint": ".github/workflows/release-commercial.yml"
+          }
+        },
+        "metadata": {
+          "buildInvocationId": "${GITHUB_RUN_ID}/${GITHUB_RUN_ATTEMPT}",
+          "buildStartedOn": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+          "completeness": {"environment": false, "materials": true, "parameters": false}
+        }
+      }
+    }
+    PROVEOF
+```
+
+### Cosign 簽署
+
+```yaml
+- name: Sign SBOM and provenance
+  run: |
+    cosign sign-blob --key env://COSIGN_PRIVATE_KEY --yes sbom.cdx.json > sbom.cdx.json.sig
+    cosign sign-blob --key env://COSIGN_PRIVATE_KEY --yes provenance.json > provenance.json.sig
+  env:
+    COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
+    COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
+```
+
+### 驗證（由終端使用者執行）
+
+```bash
+# Verify SBOM signature
+cosign verify-blob --key cosign.pub --signature sbom.cdx.json.sig sbom.cdx.json
+
+# Verify provenance signature
+cosign verify-blob --key cosign.pub --signature provenance.json.sig provenance.json
+```
+
+## 發布套件結構
+
+```
+app-commercial-v1.3.0/
+├── app-commercial-v1.3.0.docker.tar.gz   # Primary artefact
+├── sbom.cdx.json                              # CycloneDX SBOM
+├── sbom.cdx.json.sig                          # cosign signature
+├── provenance.json                            # SLSA L1 provenance
+├── provenance.json.sig                        # cosign signature
+├── checksums.txt                              # SHA-256 of all artefacts
+├── checksums.txt.sig                          # cosign signature
+└── install.sh / docker-compose.yml / ...
+```
+
+## 相關標準
+
+- [Supply Chain Security Standards](supply-chain-security-standards.md) — 相依套件稽核政策
+- [Container Security Standards](container-security.md) — image 強化
+- [Advanced SAST Standards](sast-advanced.md) — 靜態分析
+
+
+**Scope**: universal

package/bundled/locales/zh-TW/core/user-journey-testing.md

@@ -0,0 +1,111 @@
+---
+source: ../../../core/user-journey-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-24
+source_hash: 6d57ca40bd8e
+status: current
+---
+
+# 使用者旅程測試標準
+
+> **語言**: [English](../../../core/user-journey-testing.md) | 繁體中文 | [简体中文](../../zh-CN/core/user-journey-testing.md)
+
+**適用範圍**：具備跨越多個 user story 的多步驟、有狀態使用者流程的專案
+**Scope**: universal
+
+---
+
+## 概述
+
+使用者旅程測試標準定義了 **TESTPLAN** 格式，讓連貫、循序的使用者旅程成為一等公民的測試產物。驗收條件（AC）測試只能孤立地驗證單一 story，而旅程測試驗證 AC 測試做不到的事：**跨 story 的狀態連續性**——亦即一個步驟為下一個步驟留下的狀態鏈。
+
+一條旅程在人類可讀的 `TESTPLAN-NNN.md` 中描述一次，並透過共用的 `T-NNN` 識別碼一對一對應到自動化 E2E 測試，使計畫與可執行測試套件永不脫鉤。
+
+## 參考
+
+| 標準／來源 | 內容 |
+|----------------|---------|
+| journey-test-assistant（skill） | 產生 TESTPLAN 與旅程 E2E 骨架 |
+| flow-based-testing | 旅程所實例化的流程原型 |
+| e2e-testing（option） | 旅程對應到的端對端執行層 |
+
+---
+
+## 準則
+
+- 每個專案 MUST 至少有一份 `TESTPLAN-NNN.md` 記錄主要使用者旅程。
+- TESTPLAN 步驟 MUST 循序且有狀態——每個步驟依賴前一步的狀態。
+- 每份 TESTPLAN MUST 在測試步驟之前先定義 personas。
+- TESTPLAN 與自動化 E2E 測試 MUST 使用相同的 `T-NNN` 識別碼。
+- 旅程 E2E 測試 MUST 在環境不可用時優雅略過（skip gracefully）。
+- 旅程測試涵蓋 AC 測試無法涵蓋的：跨 story 的狀態連續性。
+
+---
+
+## TESTPLAN 格式
+
+- **檔名**：`TESTPLAN-NNN-<project-slug>.md`
+- **位置**：`test-plans/`
+
+### 必要區段
+
+| 區段 | 說明 | 格式 |
+|---------|-------------|--------|
+| **Personas** | 定義所有測試行為者及其角色與權限 | `\| Actor \| Role \| Key Permissions \|` |
+| **Environment** | 列出環境前置條件與驗證指令 | — |
+| **Test Groups** | `T-NNN` 編號的測試群組，具循序依賴鏈 | — |
+| **Execution Order** | 呈現 `T-NNN → T-NNN` 關係的依賴圖 | — |
+
+### 步驟標記
+
+| 標記 | 意義 |
+|--------|---------|
+| `[UI]` | 瀏覽器操作，需視覺驗證 |
+| `[API]` | `curl` / API 客戶端驗證 |
+| `[CHECK]` | 需確認的預期結果 |
+| `[SKIP-if]` | 帶原因的條件略過 |
+| `★` | 需確認的高風險步驟 |
+
+### 步驟格式
+
+每個步驟宣告：
+
+- **step_id**——`T-NNN-M`（群組-步驟格式）
+- **operation**——要做什麼，標註 `[MARKER]`
+- **expected_result**——應發生什麼
+- **precondition**——必須滿足、來自前一個 `T-NNN` 的狀態
+- **depends_on**——以逗號分隔的 `T-NNN` 識別碼
+
+---
+
+## 自動化對應
+
+- **原則**：每個 `T-NNN` 群組對應一個 `describe()` 區塊；每個步驟對應一個 `it()`。
+- **檔案樣式**：`*.journey.spec.ts` 或 `*.journey.e2e.test.ts`。
+- **共用狀態**：旅程測試 MUST 跨 `it()` 區塊使用共用 `let` 變數，使每個步驟建立於前一步的結果之上。
+- **略過策略**：以 `describe.skipIf(!BASE_URL)` 保護依賴環境的測試。
+
+---
+
+## 旅程分類
+
+| ID | 說明 | 必要於 |
+|----|-------------|--------------|
+| `platform-admin-journey` | 平台管理員設定：login → org → project → pipeline | enterprise、saas |
+| `member-journey` | 組織成員：join → project access → pipeline view | enterprise、saas |
+| `dev-journey` | 開發者：new project → spec → pipeline → artifact | all |
+
+---
+
+## 規則
+
+| 規則 | 觸發時機 | 指示 | 優先級 |
+|------|---------|-------------|----------|
+| `testplan-required` | 建立新專案 | 在寫程式碼前產生 `TESTPLAN-001.md`，含 personas、environment 與主旅程步驟 | required |
+| `journey-before-code` | 開始專案實作 | 先定義使用者旅程測試計畫；旅程測試作為活的驗收條件 | recommended |
+| `sequential-state` | 撰寫旅程 E2E 測試 | 使用共用狀態變數（`let token, orgSlug, projectSlug`），使每步建立於前一步結果 | required |
+| `graceful-skip` | 撰寫旅程 E2E 測試 | 以 `describe.skipIf(!process.env.JOURNEY_BASE_URL)` 保護，使單元 CI 略過 | required |
+| `t-nnn-alignment` | 撰寫任何 E2E 測試 | 在測試描述中引用 TESTPLAN 的 `T-NNN` 識別碼以利追溯 | recommended |
+| `persona-first` | 撰寫 TESTPLAN | 在撰寫任何測試步驟前先定義所有使用者 personas | required |
+| `dependency-chain` | 撰寫 TESTPLAN | 每個測試群組必須宣告其 `depends_on` 清單，使執行順序明確 | required |

package/bundled/locales/zh-TW/core/user-story-mapping.md

@@ -0,0 +1,94 @@
+---
+source: ../../../core/user-story-mapping.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: d161a742d704
+status: current
+---
+
+# User Story Mapping 標準
+
+> **Language**: [English](../../../core/user-story-mapping.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/user-story-mapping.ai.yaml`
+> **規格**: XSPEC-069（cross-project/specs/XSPEC-069-uds-product-layer-pack.md）
+
+## 概觀
+
+本標準定義團隊如何建構與運用 **story map** 來規劃產品發布。涵蓋三層 story map 結構
+（Backbone 活動、Walking Skeleton 子任務、Detail Stories）、MVP 水平切片規則、每個
+story 的 INVEST 合規，以及與可量化產品指標連結的 Given/When/Then 驗收條件。可避免
+不完整的 MVP，並確保每個 story 皆可測試與可追溯。
+
+本標準屬於**產品層標準包**（XSPEC-069），位於 `prd-standards`（上游意圖）與
+`requirement-engineering`（下游 INVEST story）之間，驗收條件連結
+`product-metrics-standards`。
+
+> **範圍**：本標準定義 *story map 結構與 MVP 切片紀律*。具體規劃工具（Miro/Jira）
+> 屬採用者的選擇。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | Story map 三層（backbone、walking skeleton、detail story） | MUST |
+| REQ-002 | MVP 水平切片規則（禁止垂直切片 MVP） | MUST |
+| REQ-003 | Story INVEST 合規 | MUST |
+| REQ-004 | 驗收條件格式（Given/When/Then、連結指標） | MUST |
+
+### REQ-001 — Story Map 三層
+
+每張 story map MUST 結構化為三個水平層：(1) **Backbone**（頂列）——最高抽象層級的
+使用者活動，代表完整的端到端旅程，各為使用者視角的動詞片語；backbone 須代表完整
+旅程，而非僅已實作功能。(2) **Walking Skeleton**（中列）——使每個 backbone 活動可
+運作的最少子任務，垂直排列於各 backbone 項目下。(3) **Detail Stories**（底列）——
+針對變體、增強與邊界案例的具體 story，於各欄內垂直排序（越高優先級越高）。
+
+### REQ-002 — MVP 水平切片規則
+
+MVP 發布邊界 MUST 為跨 story map 的**水平切片**，於 walking skeleton 層級涵蓋所有
+backbone 活動。僅涵蓋部分 backbone 活動的 MVP（**垂直切片**——把某活動做到完美而
+其他缺席或不可運作）為 PROHIBITED，因其無法供使用者端到端評估。**例外**：單活動
+產品（如聚焦型工具）若全部價值主張由該單一活動交付則豁免；例外 MUST 於 story map
+記錄理由。
+
+### REQ-003 — Story INVEST 合規
+
+map 中每個 story MUST 符合 `requirement-engineering` 的 INVEST 準則：
+**I**ndependent、**N**egotiable、**V**aluable、**E**stimable、**S**mall（至多一個
+sprint；過大則拆分）、**T**estable（存在可客觀驗證的驗收條件）。未通過 INVEST 的
+story 須在進 sprint 前精煉；評估 MUST 於 backlog refinement 會議進行。
+
+### REQ-004 — 驗收條件格式
+
+每個 story MUST 具備至少一條 **Given/When/Then** 格式的驗收條件，並於適用時連結至
+`product-metrics-standards` 階層中的可量化產品結果。驗收條件無法客觀驗證（如「頁面
+看起來不錯」）的 story 為不合規。驗收條件 MUST 在開發開始前撰寫，且開發開始後未經
+PM 與 dev lead 簽核 MUST NOT 修改（與 PRD 變更相同的修訂政策）。
+
+## 反樣態
+
+- 垂直 MVP 切片：把某活動做到完美而其他 backbone 活動缺席。
+- 無驗收條件的 story 進入開發（無明確 definition of done）。
+- backbone 活動對應系統元件而非實際使用者目標。
+- story map 僅用於規劃後即棄置，未作為活文件維護。
+- 略過 backbone 與 walking skeleton 脈絡直接加入 detail story。
+
+## 與既有標準的整合
+
+- **`prd-standards`**——PRD 範圍實現為 story map 與 MVP 切片。
+- **`requirement-engineering`**——story 遵循其定義的 INVEST 準則。
+- **`product-metrics-standards`**——驗收條件對應北極星 driver。
+- **`acceptance-criteria-traceability`**——GWT 條件提供 AC 追溯主幹。
+
+## 相關規格
+
+- XSPEC-069 — UDS 產品層標準包（本標準來源）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~004：三層 map、MVP 水平切片規則、INVEST 合規、GWT 驗收條件（XSPEC-069） |