universal-dev-standards 5.10.0 → 5.12.1

package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md

@@ -27,3 +27,27 @@ description: "[UDS] 引導 API 和微服務的合約測試策略"
 
 - 詳細指南：[contract-testing.md](../../../../options/testing/contract-testing.md)
 - 技能指南：[guide.md](./guide.md)
+
+
+## Next Steps Guidance | 下一步引導
+
+After `/contract-test` completes:
+
+> **合約測試引導完成。建議下一步：**
+> - 執行 `/ci-cd` 將合約驗證加入 CI 管線
+> - 執行 `/api-design` 完善 API 設計
+> - 執行 `/testing` 整合到整體測試策略
+
+## Reference | 參考
+
+- Detailed guide: [contract-testing.md](../../options/testing/contract-testing.md)
+- Related: [api-design-assistant](../api-design-assistant/SKILL.md)
+
+## AI Agent Behavior | AI 代理行為
+
+When `/contract-test` is invoked:
+1. **Assess** — Ask about architecture (monolith, microservices, number of APIs)
+2. **Recommend** — Suggest strategy based on architecture
+3. **Guide** — Walk through setup for chosen strategy
+4. **Generate** — Create example contract test files
+5. **Verify** — If `verify` subcommand, scan for contracts and report coverage

package/bundled/locales/zh-TW/skills/documentation-guide/SKILL.md

@@ -417,3 +417,40 @@ MIT
 本 Skill 以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
 
 **來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
+
+
+## Next Steps Guidance | 下一步引導
+
+After `/docs-guide` completes, the AI assistant should suggest:
+
+> **文件結構與需求已釐清。建議下一步 / Documentation structure and requirements clarified. Suggested next steps:**
+> - 執行 `/docs` 根據指南直接產生專案文件 ⭐ **Recommended / 推薦** — 立即將文件指南化為行動 / Turn documentation guidelines into action immediately
+> - 執行 `/changelog` 建立或更新 CHANGELOG.md — 確保變更歷史完整 / Ensure change history is complete
+> - 執行 `/sdd` 將文件需求納入規格驅動開發 — 確保文件與功能同步 / Ensure docs stay in sync with features
+
+---
+
+## Related Standards
+
+- [Documentation Writing Standards](../../core/documentation-writing-standards.md) - Content requirements
+- [Documentation Structure](../../core/documentation-structure.md) - File organization
+- [Changelog Standards](../../core/changelog-standards.md) - CHANGELOG format
+- [Changelog Guide Skill](../changelog-guide/SKILL.md) - CHANGELOG skill
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 2.1.0 | 2026-03-17 | Added: Diátaxis classification, LLM discovery, quality metrics, enhanced ADR template, translation-friendly writing |
+| 2.0.0 | 2026-01-12 | Added: Project type matrix, document templates, documentation pyramid |
+| 1.0.0 | 2025-12-24 | Initial release |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/skills/error-code-guide/SKILL.md

@@ -264,3 +264,36 @@ export const ErrorCodes = {
 此技能採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權。
 
 **來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
+
+
+## Next Steps Guidance | 下一步引導
+
+After `/errors` completes, the AI assistant should suggest:
+
+> **錯誤碼設計已完成。建議下一步 / Error code design completed. Suggested next steps:**
+> - 執行 `/sdd` 將錯誤碼設計納入正式規格 ⭐ **Recommended / 推薦** — 確保錯誤碼在規格中有完整定義 / Ensure error codes are fully defined in specs
+> - 執行 `/logging` 設定結構化日誌以配合錯誤碼 — 讓錯誤碼與日誌系統整合 / Integrate error codes with logging system
+> - 執行 `/tdd` 為錯誤處理邏輯撰寫測試 — 確保每個錯誤碼都有對應的測試 / Ensure each error code has corresponding tests
+
+---
+
+## Related Standards
+
+- [Error Code Standards](../../core/error-code-standards.md)
+- [Logging Standards](../../core/logging-standards.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-30 | Initial release |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/skills/git-workflow-guide/SKILL.md

@@ -213,3 +213,37 @@ git push origin feature/my-feature
 本技能採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
 
 **來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
+
+
+## Next Steps Guidance | 下一步引導
+
+After `/git-flow` completes, the AI assistant should suggest:
+
+> **Git 工作流程已設定。建議下一步 / Git workflow configured. Suggested next steps:**
+> - 執行 `git checkout -b feature/<描述>` 建立功能分支開始開發 ⭐ **Recommended / 推薦** — 立即套用所選的分支策略 / Apply the chosen branching strategy immediately
+> - 執行 `/commit` 學習提交訊息規範 — 確保提交訊息格式一致 / Ensure consistent commit message format
+> - 執行 `/checkin` 了解簽入品質門檻 — 在提交前確保程式碼品質 / Ensure code quality before commits
+
+---
+
+## Related Standards
+
+- [Git Workflow](../../core/git-workflow.md) - Core Git workflow standard
+- [Commit Message Guide](../../core/commit-message-guide.md) - Commit message conventions
+- [Checkin Standards](../../core/checkin-standards.md) - Pre-commit quality gates
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/skills/logging-guide/SKILL.md

@@ -280,3 +280,36 @@ logger.error('處理訂單失敗', {
 此技能採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權。
 
 **來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
+
+
+## Next Steps Guidance | 下一步引導
+
+After `/logging` completes, the AI assistant should suggest:
+
+> **日誌標準已掌握。建議下一步 / Logging standards understood. Suggested next steps:**
+> - 根據日誌指南在程式碼中實作結構化日誌 ⭐ **Recommended / 推薦** — 立即將日誌標準應用到專案 / Apply logging standards to the project immediately
+> - 執行 `/errors` 設計錯誤碼以配合日誌系統 — 讓錯誤追蹤更有效率 / Make error tracking more efficient
+> - 執行 `/sdd` 將可觀測性需求納入規格 — 確保日誌需求在規格中有定義 / Ensure logging requirements are defined in specs
+
+---
+
+## Related Standards
+
+- [Logging Standards](../../core/logging-standards.md)
+- [Error Code Standards](../../core/error-code-standards.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-30 | Initial release |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md

@@ -150,3 +150,22 @@ project/
 - [核心：文件結構](../../core/documentation-structure.md)
 - [指南：檔案歸檔決策指南](../../core/guides/file-placement-guide.md)
 - [AI：專案結構選項](../../../../options/project-structure/)
+
+
+## Next Steps Guidance | 下一步引導
+
+After `/project-structure` completes, the AI assistant should suggest:
+
+> **專案結構已建立或審查完成。建議下一步 / Project structure created or reviewed. Suggested next steps:**
+> - 執行 `/sdd` 開始規格驅動開發，將專案結構納入正式規格 ⭐ **Recommended / 推薦** — 確保結構決策有規格追蹤 / Ensures structure decisions are tracked in specs
+> - 執行 `/docs` 產生專案文件（README、ARCHITECTURE.md 等） — 讓結構決策有文件記錄 / Document structure decisions
+> - 執行 `/ai-friendly-architecture` 設定 AI 上下文配置 — 讓 AI 助手更好地理解專案結構 / Help AI assistants understand the project structure
+
+---
+
+## Related Standards
+
+- [Core: Project Structure](../../core/project-structure.md)
+- [Core: Documentation Structure](../../core/documentation-structure.md)
+- [Guide: File Placement Decision Guide](../../core/guides/file-placement-guide.md)
+- [AI: Project Structure Options](../../ai/options/project-structure/)

package/bundled/locales/zh-TW/skills/retrospective-assistant/SKILL.md

@@ -28,3 +28,41 @@ description: "[UDS] 引導結構化的團隊回顧，支援 Sprint 和 Release
 
 - 核心規範：[retrospective-standards.md](../../../../core/retrospective-standards.md)
 - 詳細指南：[guide.md](./guide.md)
+
+
+## Next Steps Guidance | 下一步引導
+
+After `/retrospective` completes:
+
+> **Retrospective complete. Suggested next steps:**
+> - Commit the retrospective report: `/commit`
+> - Create ADRs for architectural decisions identified: `/adr`
+> - Track action items in your issue tracker
+> - Schedule next retrospective
+
+> **回顧完成。建議下一步：**
+> - 提交回顧報告：`/commit`
+> - 為識別的架構決策建立 ADR：`/adr`
+> - 在 issue tracker 中追蹤行動項目
+> - 排定下次回顧
+
+## AI Agent Behavior | AI 代理行為
+
+When `/retrospective` is invoked:
+
+1. **Check type** — Sprint (default) or Release
+2. **Gather data** — Scan git log, check `docs/retrospectives/` for previous actions
+3. **Guide technique** — Use Start-Stop-Continue by default, or specified technique
+4. **Generate report** — Write to `docs/retrospectives/RETRO-YYYY-MM-DD-[type].md`
+5. **Review past actions** — Check previous retro for open action items
+6. **Offer next steps** — Show guidance above
+
+When `/retrospective actions` is invoked:
+1. Scan `docs/retrospectives/` for all retro files
+2. Parse action items from each
+3. Display open/in-progress items as table
+
+## Reference | 參考
+
+- Core Standard: [retrospective-standards.md](../../core/retrospective-standards.md)
+- Detailed Guide: [guide.md](./guide.md)

package/bundled/locales/zh-TW/skills/testing-guide/SKILL.md

@@ -228,3 +228,39 @@ test('method_scenario_expected', () => {
 本 Skill 以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
 
 **來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
+
+
+## Next Steps Guidance | 下一步引導
+
+After `/testing` completes, the AI assistant should suggest:
+
+> **測試標準與最佳實踐已掌握。建議下一步 / Testing standards and best practices understood. Suggested next steps:**
+> - 執行 `/tdd` 開始測試驅動開發（紅-綠-重構循環） ⭐ **Recommended / 推薦** — 將測試知識立即轉化為實踐 / Turn testing knowledge into practice immediately
+> - 執行 `/coverage` 分析目前程式碼覆蓋率 — 找出測試缺口 / Identify testing gaps
+> - 執行 `/bdd` 撰寫行為驅動的 Given-When-Then 場景 — 從使用者角度定義測試 / Define tests from user perspective
+
+---
+
+## Related Standards
+
+- [Testing Standards](../../core/testing-standards.md) - Actionable rules
+- [Testing Theory](./testing-theory.md) - Educational knowledge base
+- [Code Review Checklist](../../core/code-review-checklist.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.2.0 | 2026-01-29 | Added links to new testing-theory.md knowledge base |
+| 1.1.0 | 2025-12-29 | Added Testing Theory Essentials YAML section |
+| 1.0.0 | 2025-12-24 | Initial: Standard sections (Purpose, Related Standards, Version History, License) |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/skills/README.md

@@ -4,6 +4,9 @@ This directory contains the reference implementations of Universal Development S
 
 > Derived from [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards) core standards.
 
+> **For the full indexed skill list** (by Tier, Category, and use case), see **[docs/user/SKILLS-INDEX.md](../docs/user/SKILLS-INDEX.md)** (auto-generated).
+> For slash command reference, see **[docs/user/COMMANDS-INDEX.md](../docs/user/COMMANDS-INDEX.md)**.
+
 ## Directory Structure
 
 ```
@@ -39,7 +42,7 @@ These skills provide standard guidance and workflows. They can be accessed via s
 | `documentation-guide` | `/docs` | [UDS] Documentation management |
 | `requirement-assistant` | `/requirement` | [UDS] Requirement writing |
 | `reverse-engineer` | `/reverse` | [UDS] Reverse engineer code |
-| `spec-derivation` | `/spec-derive` | [UDS] Derive BDD/TDD/ATDD artifacts from spec |
+| `spec-derivation` | `/derive` | [UDS] Derive BDD/TDD/ATDD artifacts from spec |
 | `spec-driven-dev` | `/sdd` | [UDS] Spec-Driven Development |
 | `test-coverage-assistant` | `/coverage` | [UDS] Test coverage analysis |
 | `dev-methodology` | `/methodology` | [UDS] Development methodology |

package/bundled/skills/spec-driven-dev/SKILL.md

@@ -55,6 +55,7 @@ New request? | 新需求？
 ├─ New feature/capability? → Create proposal | 建立提案
 ├─ Breaking change? → Create proposal | 建立提案
 ├─ Architecture change? → Create proposal | 建立提案
+├─ Agent/role definition (spans multiple features)? → Use spec-type: agent | 使用 Agent SPEC template
 └─ Unclear? → Create proposal (safer) | 建立提案（較安全）
 ```
 
@@ -126,6 +127,46 @@ The system SHALL [behavior description].
 - [ ] Integration tests for [flow]
 ```
 
+### Agent SPEC Structure | Agent 規格結構（`spec-type: agent`）
+
+```markdown
+# [SPEC-ID] Agent: [Role Name]
+<!-- spec-type: agent -->
+<!-- agent-id auto-referenced by feature SPECs -->
+
+## Role Definition
+- **Role**: [Agent Name]
+- **Responsibility**: [One sentence]
+- **Autonomy Level**: L[1-5] (per DEC-065)
+
+## Capability Scope
+**Owns:**
+- [Capability 1]
+- [Capability 2]
+
+**Does NOT own:**
+- [Explicit exclusion]
+
+## Interface Contract
+### Input
+| Message Type | Required Fields | Optional Fields |
+|---|---|---|
+| [Type] | [fields] | [fields] |
+
+### Output
+| Artifact Type | Success Condition | Failure Condition |
+|---|---|---|
+| [Type] | [condition] | [condition] |
+
+## Agent Interactions
+- **Upstream**: [Who calls this agent]
+- **Downstream**: [Who this agent calls]
+- **Parallel**: [Agents working alongside]
+
+## Related Feature SPECs
+- [SPEC-NNN] — [This agent's role in that spec]
+```
+
 ### Scenario Formatting Rules | 場景格式規則
 
 - Use `#### Scenario:` (h4 header) for each scenario

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "5.10.0",
+  "version": "5.12.1",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/src/commands/update.js

@@ -614,6 +614,41 @@ export async function updateCommand(options) {
     }
 
     intSpinner.succeed(msg.syncedIntegrations.replace('{count}', results.integrations.length));
+
+    // XSPEC-208 BUG-208-02: prune orphaned integrationBlockHashes whose
+    // integration file is no longer claimed by manifest.aiTools (e.g. aiTools
+    // shrank from ["claude-code","gemini-cli"] to ["claude-code"], leaving a
+    // stale GEMINI.md hash). Without this, `uds check` -> checkIntegrationBlocksIntegrity
+    // falsely reports those files as missing.
+    //
+    // The expected set is built from manifest.aiTools (the declared
+    // configuration), NOT results.integrations (what was actually written).
+    // Using results.integrations would over-prune when writes fail (e.g.
+    // sandbox EPERM) and incorrectly drop valid hashes.
+    if (manifest.integrationBlockHashes) {
+      const expectedFiles = new Set();
+      for (const tool of (manifest.aiTools || [])) {
+        const targetFile = getToolFilePath(tool);
+        if (targetFile) expectedFiles.add(targetFile);
+      }
+      // Universal AGENTS.md is tracked when generateAgentsMd is enabled.
+      if (manifest.generateAgentsMd) {
+        expectedFiles.add('AGENTS.md');
+      }
+
+      const orphaned = Object.keys(manifest.integrationBlockHashes)
+        .filter(f => !expectedFiles.has(f));
+      for (const f of orphaned) {
+        delete manifest.integrationBlockHashes[f];
+      }
+      if (orphaned.length > 0) {
+        console.log(chalk.gray(
+          `  ${(msg.prunedOrphanedBlockHashes || 'Pruned {count} orphaned integration hash(es): {files}')
+            .replace('{count}', orphaned.length)
+            .replace('{files}', orphaned.join(', '))}`
+        ));
+      }
+    }
   }
 
   // Update layered CLAUDE.md if content_layout is layered

package/src/config/ai-agent-paths.js

@@ -540,6 +540,14 @@ export const AVAILABLE_COMMANDS = [
   { name: 'migrate', description: 'Code migration, framework upgrades, and tech modernization' },
   { name: 'audit', description: 'Audit standards compliance and generate reports' },
 
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Observability / SRE (Commands-only)
+  // ═══════════════════════════════════════════════════════════════════════════
+  { name: 'e2e', description: 'Generate E2E test scaffolding from BDD scenarios' },
+  { name: 'observability', description: 'Guide observability instrumentation (logs, metrics, traces)' },
+  { name: 'runbook', description: 'Author operational runbooks for incidents and routine procedures' },
+  { name: 'slo', description: 'Define SLOs, SLIs, and error budgets' },
+
   // ═══════════════════════════════════════════════════════════════════════════
   // CLI Management (Commands-only, UDS CLI specific)
   // ═══════════════════════════════════════════════════════════════════════════

package/src/i18n/messages.js

@@ -1052,6 +1052,7 @@ export const messages = {
         updatedStandards: 'Updated {count} standard files',
         syncingIntegrations: 'Syncing integration files...',
         syncedIntegrations: 'Synced {count} integration files',
+        prunedOrphanedBlockHashes: 'Pruned {count} orphaned integration hash(es): {files}',
         // Success
         updateSuccess: '✓ Standards updated successfully!',
         versionUpdated: 'Version: {current} → {latest}',
@@ -2312,6 +2313,7 @@ export const messages = {
         updatedStandards: '已更新 {count} 個標準檔案',
         syncingIntegrations: '同步整合檔案中...',
         syncedIntegrations: '已同步 {count} 個整合檔案',
+        prunedOrphanedBlockHashes: '已清除 {count} 個孤兒整合雜湊：{files}',
         // Success
         updateSuccess: '✓ 標準更新成功！',
         versionUpdated: '版本：{current} → {latest}',
@@ -3501,6 +3503,7 @@ export const messages = {
         updatedStandards: '已更新 {count} 个标准文件',
         syncingIntegrations: '正在同步集成文件...',
         syncedIntegrations: '已同步 {count} 个集成文件',
+        prunedOrphanedBlockHashes: '已清除 {count} 个孤儿集成哈希：{files}',
         // Success
         updateSuccess: '✓ 标准更新成功！',
         versionUpdated: '版本：{current} → {latest}',

package/src/utils/integration-generator.js

@@ -45,15 +45,31 @@ export function resolveContentModeForTool(tool, userContentMode) {
  * Helper functions for tool configuration
  */
 
+/**
+ * Set of all known integration file names (e.g. "CLAUDE.md", ".cursorrules"),
+ * derived from SUPPORTED_AI_TOOLS so reverse lookup stays in sync.
+ */
+const KNOWN_TOOL_FILES = new Set(
+  Object.values(SUPPORTED_AI_TOOLS).map(c => c.file)
+);
+
 /**
  * Get tool file name with legacy mapping support
- * @param {string} tool - Tool name
+ * @param {string} tool - Tool name (e.g. "claude-code") or filename (e.g. "CLAUDE.md")
  * @returns {string} File name
  */
 function getToolFileName(tool) {
   const normalizedName = LEGACY_TOOL_MAPPINGS[tool] || tool;
   const config = SUPPORTED_AI_TOOLS[normalizedName];
-  return config ? config.file : `${tool}.md`;
+  if (config) return config.file;
+
+  // XSPEC-208 BUG-208-01: schema 3.x manifests store filenames (not tool keys)
+  // in manifest.integrations. Without this guard, getToolFileName("CLAUDE.md")
+  // returns "CLAUDE.md.md" and triggers spurious missing-file restore failures.
+  if (KNOWN_TOOL_FILES.has(tool) || /\.(md|yaml|yml|json)$/i.test(tool)) {
+    return tool;
+  }
+  return `${tool}.md`;
 }
 
 /**

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "5.10.0",
+  "version": "5.12.1",
   "lastUpdated": "2026-05-13",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "5.10.0"
+      "version": "5.12.1"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "5.10.0",
+      "version": "5.12.1",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -2326,12 +2326,13 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
+      "version": "5.12.1",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"
       },
       "category": "core",
-      "description": "License tier classification, automated scanning in CI, SBOM generation, attribution notices, and violation remediation"
+      "description": "License tier classification, automated scanning in CI, SBOM generation, attribution notices, violation remediation, ClearlyDefined API, AST PII analysis, and EmbeddingProvider copyright similarity"
     },
     {
       "id": "pii-classification",

package/bundled/locales/zh-TW/docs/MIGRATION-V5.md

@@ -1,79 +0,0 @@
----
-source: ../../../docs/archive/MIGRATION-V5.md
-source_version: 5.0.0
-translation_version: 5.0.0
-last_synced: 2026-04-22
-status: current
----
-
-# 遷移指南：Universal Dev Standards V5
-
-> **語言**: English | [繁體中文](MIGRATION-V5.md)
-
-**版本**: 5.0.0
-**狀態**: 重大變更（Token 使用量最佳化）
-
-## 概覽
-
-Universal Development Standards V5 引入了重大的架構變更，旨在**減少 AI Token 消耗量高達 75%**。我們將「可執行的規則」與「教育性內容」進行了分離。
-
-## 主要變更
-
-### 1. 規則 (Rules) 與指南 (Guides) 分離
-
-在 V4 中，許多標準檔案體積龐大（例如 `testing-standards.md` 高達 141KB）。在 V5 中，這些檔案已被拆分：
-
-| 組件 | 位置 | 目的 | AI 行為 |
-|------|------|------|---------|
-| **規則 (Rules)** | `core/*.md` | 可執行的規則、檢查清單、閾值 | **務必讀取** |
-| **指南 (Guides)** | `core/guides/*.md` | 詳細解釋、教學、範例 | **僅在需要時讀取** |
-| **方法論** | `methodologies/guides/*.md` | 完整的方法論指南 (TDD, BDD 等) | **僅在需要時讀取** |
-
-### 2. 檔案位置移動
-
-以下方法論檔案已從 `core/` 移至 `methodologies/guides/`：
-- `test-driven-development.md`
-- `acceptance-test-driven-development.md`
-- `spec-driven-development.md`
-- `behavior-driven-development.md`
-- `requirement-engineering.md`
-
-### 3. AI 代理指令
-
-新的 AI 工具設定（`.cursorrules`、`CLAUDE.md` 等）現在包含 **核心標準使用規則 (Core Standards Usage Rule)**，指示 AI 代理優先讀取 `core/` 中的輕量化規則以節省 Token。
-
-## 如何升級
-
-### 現有專案
-
-如果您已在專案中初始化了 UDS，請按照以下步驟操作以獲取 Token 最佳化效益：
-
-1. **更新 CLI**：
-   ```bash
-   npm install -g universal-dev-standards@alpha
-   ```
-
-2. **同步參考 (Sync References)**：
-   執行更新指令以獲取新的輕量化規則檔案與指南：
-   ```bash
-   uds update --sync-refs
-   ```
-
-3. **更新 AI 規則**：
-   重新生成或更新您的 AI 工具設定檔（例如 `.cursorrules`），以包含新的使用指令：
-   ```bash
-   uds configure
-   # 選擇您的 AI 工具並選擇 "Update"
-   ```
-
-### 向後相容性
-
-我們在原始的 `core/` 位置留下了 **Stub 檔案 (轉址檔案)**。這些是小型檔案（約 1KB），提供摘要以及指向新完整指南的連結。這確保了您文件中任何現有的硬編碼連結或參考不會失效。
-
-## 常見問題 (FAQ)
-
-### 為什麼要這樣做？
-現代 AI 模型具有上下文視窗 (Context Window) 限制以及 Token 成本。大型文件會降低 AI 效能並增加延遲。V5 使「常駐」上下文變得更小，同時保持完整知識庫可用。
-
-### 我需要修改程式碼嗎？
-不需要。此變更僅影響文件結構和 AI 代理的行為。