universal-dev-standards 6.7.5 → 6.9.0

package/bundled/locales/zh-TW/core/turn-completion-integrity.md

@@ -0,0 +1,190 @@
+---
+source: ../../../core/turn-completion-integrity.md
+source_version: 1.3.0
+translation_version: 1.3.0
+last_synced: 2026-09-08
+source_hash: c396baa28423
+status: current
+---
+
+# 回合收尾完整性
+
+> **Language**: [English](../../../core/turn-completion-integrity.md) | 繁體中文
+
+**版本**: 1.3.0
+**最後更新**: 2026-09-08
+**適用範圍**: 任何由 agent 結束回合、把控制權交還給人的執行環境
+**Scope**: universal
+**產業標準**: 不宣稱任何來源——由實際觀察到的失敗歸納，見「證據」
+
+---
+
+## 目的
+
+agent 寫下「我接著做 X」，然後結束回合，而 X 沒有做。
+
+人讀到的是一句描述著從未發生的工作的話。沒有任何錯誤、沒有任何檢查變紅，
+逐字稿讀起來像有進展。下一個回合從一個「人以為比實際更前面」的狀態開始。
+
+這不是知識上的失敗——agent 說對了下一步。這是**收尾**的失敗：
+回合結束在工作本該開始的那一刻。
+
+---
+
+## 規則
+
+**R1.** 若 agent 最後一則訊息做出了第一人稱的下一步宣告，
+回合**不得**結束，除非那件事做了，或說出它卡在什麼。
+
+**R2.** 「卡在什麼」的意思是逐項指名每一件事在等誰、等什麼。
+「主要的都做完了」不是卡點陳述；
+「部署等你的金鑰，文件不卡任何人而我現在就做」才是。
+
+**R3.** 只寫在 agent 指令裡的規則不是執法。R1 必須**在回合結束的那一刻**、
+由**不是 agent 的東西**來判斷。
+
+---
+
+## R3 為什麼存在
+
+這條規則的指令形式曾寫進某專案的 agent 指令，
+而**在讀到它的同一個 session 內就被違反**。
+接著它被寫成已發布的標準、標為 optional、沒有任何檢查器在讀，
+七天後同樣的違反再來一次。
+
+指令是一種輸入。失敗發生在一個決策點——「我正要結束這個回合」——
+而一個在那一刻不會被讀到的輸入，就是沒有在生效。
+一般形式是：**一項有文件而在其決策點上沒有執法的要求，是建議；
+它的遵循度不是很高，是沒有被量過。**
+
+---
+
+## 這個檢查**不得**做的事
+
+**R4. 不得因為「永遠還有待辦」而擋。** repo 永遠有未關的 TODO，
+待辦清單永遠有項目。一道每個回合都為真的閘門會被關掉，然後它什麼都不保護。
+這個檢查**只**在 agent 於那則訊息裡做出的宣告上觸發。
+
+**R5. 一律 fail open。** 任何錯誤——讀不到逐字稿、欄位缺、JSON 壞掉、
+結構不符——都**必須**讓回合結束。一支會把 session 困住的 hook 比沒有 hook 糟，
+因為人唯一的救援手段是把它關掉，而他會永久關掉它。
+
+**R6. 阻擋要有上界。** 檢查**必須**同時具備
+(a) 兩次阻擋之間的冷卻期，與
+(b) **滾動時窗**內的阻擋次數上限。
+
+以 session 計且永不重置的上限不是安全閥——它是一個有延遲的關閉開關，
+而且會在「這條規則最重要的那種長 session」裡安靜地自我解除。
+
+---
+
+## 使用者可以結束回合，而 agent 的用字說不出這件事
+
+**R9.** 檢查**必須**豁免由人要求結束的回合，
+而且**必須**從人自己最近一則訊息判斷，不是從 agent 的訊息判斷。
+
+這條規則的存在是因為它的缺席被量到過一次——就在本標準上線後的第一次真實觸發。
+人寫的是「先暫停，我要回家了」；agent 照做並列出回來要接的事；
+檢查把它讀成未兌現的承諾並擋下。
+
+偵測器對樣式的判斷沒有錯。**由指令結束的回合，與由未兌現承諾結束的回合，
+在 agent 的用字上一模一樣**，因為兩種情況下 agent 都在指名自己現在不做的工作。
+那則訊息裡沒有任何東西分得出來，所以只讀那則訊息的檢查也分不出來。
+
+**R10.** 叫停樣式**必須**寫窄，而且它的語料**必須**包含
+「只是含有停止字眼的工作指令」。誤豁免不是漏擋一次，
+而是把檢查在該 session 的剩餘時間全部靜音。
+實作期間該樣式曾比對到「先停用那份硬編碼清單，改成走訪註冊表」
+——一句要求做事的指令，被讀成叫停。
+
+**R11.** 檢查自己的攔阻訊息會以人的回合回到逐字稿。
+它**必須**認得出自己的輸出，並在尋找人的最後一則訊息時略過它。
+
+沒有這一條，R9 只會生效一次。攔阻訊息會在下一次執行成為「人最近一則訊息」，
+真正那句叫停被蓋在它後面，豁免就消失——而且是靜默地、
+只在它被建立的那種情境裡消失。
+
+這與「偵測器比對到解釋它的散文」同一族，再往前一步：**檢查讀到自己的輸出。**
+在攔阻訊息裡帶一個固定標記字串，略過任何含有它的人類回合。
+
+**R12.** 檢查**必須**認得出 R2 所定義的那個結束方式。
+一個執行 R2 卻看不見逐項卡點清單的檢查，會擋下標準自己要求的唯一停法
+——它在懲罰正確行為，而那比漏抓一次違規更快被拆掉。
+
+辨識需要三個條件，實測拿掉任何一個都會壞：
+
+| 條件 | 為什麼 |
+|---|---|
+| 兩項以上的清單 | 只有一項帶歸屬的是句子，不是逐項列出 |
+| 歸屬詞出現在訊息任何位置，不要求每項都有 | 真實寫法把它放在前言——「剩下的每一項都卡在你手上，逐項列：」——而要求每項都有，第一次拿真實訊息一比就漏 |
+| 沒有含糊的完成語 | 「其餘都做完了」正是 R2 拒絕的摘要；靠這種句子把剩下的帶過的清單，是穿著清單外衣的摘要 |
+
+🔴 **歸屬詞的搜尋必須排除檢查自己的結構。**
+「要你決定什麼」這個標題本身含有「要你」，於是一份「已經做完了什麼」的清單，
+靠著它上方的標題就滿足了歸屬條件。**偵測器讀到了自己的結構**——與 R11 同一個失敗，低一層。
+
+---
+
+## 語言涵蓋是正確性問題，不是翻譯工作
+
+這個檢查讀的是 agent 寫的散文，所以**它的偵測器與語言綁定**。
+一個只帶著某一種語言樣式的偵測器，出貨給以另一種語言工作的採用者，
+會得到一支裝好了、每回合都執行、exit 0、而**結構上永遠不會觸發**的 hook。
+每一個可觀察的訊號，都與「agent 表現良好」一模一樣。
+
+**R7.** 每一個支援的語言**必須**以 locale 包出貨，
+各自帶著**自己的語料**（必須擋的案例與必須放行的案例），
+而該包的自測**必須**在 CI 裡跑。語料不過的 locale 包不出貨。
+
+**R8.** 語言沒有對應包的採用者**必須**被告知這個檢查對他們是失效的。
+在這裡沉默，等於把本標準要防的失敗在上一層重演一次。
+
+---
+
+## 偵測器比對什麼
+
+形狀是：**第一人稱未來標記，接一個動作動詞，在同一個句子裡**，再減掉三個排除項。
+
+| 元素 | 作用 | 缺了會怎樣 |
+|---|---|---|
+| 第一人稱＋未來標記 | 把宣告與描述分開 | 會比對到被引述回來的使用者原話 |
+| 動作動詞 | 把「做」與「講」分開 | 「我來解釋為什麼」會算成工作 |
+| 限定同一句 | 讓兩半保持相關 | 一個否定子句與後面一個真承諾會併成一個不匹配 |
+| 排除報告動詞 | 「我會說／提／記」不是工作 | 檢查會在自己的摘要上觸發 |
+| 排除否定 | 「我不會改那個」是決定，不是承諾 | 一句拒絕會被讀成承諾 |
+| 排除引用與表格 | 樣式的**例子**不是樣式的**實例** | 檢查會在自己的文件上觸發 |
+
+上表每一個排除項，都是因為它的缺席在測試中造成過一次誤擋才加上去的。
+少做其中任何一項的實作，會重現那次誤擋。
+
+---
+
+## 證據
+
+單一專案的觀察，2026-08 至 2026-09：
+
+| 觀察 | 次數 |
+|---|---|
+| 使用者就「說了下一步卻沒做」提出同一個抱怨 | 5 |
+| 指令形式已存在、而在同一個 session 內被違反 | ≥1 |
+| 偵測器版本被自己原始碼或例子中的樣式打敗 | 5 |
+| 上線前被語料抓到的偵測器誤擋 | 3 |
+
+最後一列就是 R7 的論據。五個偵測器缺陷裡有三個**只因為語料存在**才被抓到；
+出貨出去的那兩個，正是沒有任何案例涵蓋的那兩個。
+
+---
+
+## 檢查清單
+
+- [ ] 檢查在回合結束時執行，不是寫成給 agent 的指令
+- [ ] 每一條失敗路徑都不阻擋、直接放行
+- [ ] 冷卻期與滾動時窗上限兩者都在
+- [ ] 每個出貨語言都有語料，而語料在 CI 裡跑
+- [ ] 語言不支援的採用者被告知檢查失效
+- [ ] 檢查不讀取 repo 狀態（未關的 TODO、待辦清單）
+- [ ] 由人要求結束的回合被豁免，且由人的訊息判斷
+- [ ] 叫停語料包含「含有停止字眼的工作指令」
+- [ ] 檢查認得出自己的攔阻訊息，不把它讀成人說的話
+- [ ] 檢查認得出 R2 定義的逐項卡點結束，而且不擋它
+- [ ] 歸屬詞的搜尋排除檢查自己的標題與結構

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

@@ -2,8 +2,8 @@
 source: ../../../core/user-journey-testing.md
 source_version: 1.0.0
 translation_version: 1.0.0
-last_synced: 2026-06-24
-source_hash: 6d57ca40bd8e
+last_synced: 2026-07-30
+source_hash: 11e0a5b9971d
 status: current
 ---
 

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

@@ -2,8 +2,8 @@
 source: ../../../core/user-story-mapping.md
 source_version: 1.0.0
 translation_version: 1.0.0
-last_synced: 2026-06-17
-source_hash: d161a742d704
+last_synced: 2026-07-30
+source_hash: f2ae062874ca
 status: current
 ---
 

package/bundled/locales/zh-TW/core/verification-oracle.md

@@ -2,8 +2,8 @@
 source: ../../../core/verification-oracle.md
 source_version: 1.0.0
 translation_version: 1.0.0
-last_synced: 2026-06-17
-source_hash: 16e45bd68616
+last_synced: 2026-07-30
+source_hash: bfd2405d25cf
 status: current
 ---
 

package/bundled/locales/zh-TW/docs/CHEATSHEET.md

@@ -1,6 +1,6 @@
 # UDS 速查表
 
-> Quick reference for all UDS features | Last updated: 2026-08-17
+> Quick reference for all UDS features | Last updated: 2026-09-14
 
 **Language**: [English](../../../docs/user/CHEATSHEET.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CHEATSHEET.md)
 
@@ -12,13 +12,27 @@
 |---------|-------------|
 | `uds list` | List available standards |
 | `uds init` | Initialize standards in current project |
-| `uds configure` | Modify options for initialized project |
-| `uds check` | Check adoption status of current project |
+| `uds config` | Manage UDS configuration and project settings |
+| `uds hitl` | Human-in-the-Loop controls |
+| `uds configure` | Alias for "uds config" — Modify project settings |
+| `uds check` | Check file integrity and adoption status (quick validation). For deep health diagnosis, use "uds audit" |
+| `uds lint` | Check spec dependency validity and size against installed specs (specs/*.md) |
+| `uds simulate` | Simulate a standard check with input (Predictive Validation) |
+| `uds fix` | Auto-fix standard violations (Self-Healing) |
 | `uds update` | Update standards to latest version |
 | `uds skills` | List installed Claude Code skills |
-| `uds agent` | Manage UDS agents (list, install, info) |
-| `uds workflow` | Manage UDS workflows (list, install, info, execute, status) |
-| `uds ai-context` | Manage AI context configuration (init, validate, graph) |
+| `uds audit` | Deep health diagnosis with pattern detection and feedback (strategic). For quick file check, use "uds check" |
+| `uds deps` | Compare the versions you test against the versions your declared ranges resolve to |
+| `uds uninstall` | Remove UDS standards, integrations, skills, and hooks |
+| `uds compile` | Compile enforcement standards into hook configurations |
+| `uds report` | Analyze hook telemetry and show adoption report |
+| `uds release` | Manage release process (promote, deploy, manifest, verify) |
+| `uds spec` | Manage lightweight micro-specs for vibe coding. For full spec lifecycle with review, use "/sdd" |
+| `uds quickstart` | Interactive workflow guide — find the right commands quickly |
+| `uds agent` | Manage UDS agents for AI tools |
+| `uds ai-context` | Manage .ai-context.yaml configuration for AI-friendly architecture |
+| `uds mcp` | MCP server commands for AI tool integration |
+| `uds run` | Run a project command by intent (test/lint/build/security) via uds.project.yaml |
 
 ## 💬 斜線命令
 
@@ -204,6 +218,7 @@
 | `data-migration-testing` | Data Migration Testing |
 | `data-pipeline` | Data Pipeline Standards |
 | `database-standards` | This standard defines guidelines for database desi |
+| `deferred-item-exit` | Several standards require documents that **produce |
 | `deployment-standards` | This standard defines guidelines for safely deploy |
 | `deprecation-standards` | Deprecation & Sunset Standards |
 | `design-document-standards` | Design Document Standards |
@@ -302,6 +317,7 @@
 | `timeout-standards` | Timeout Standards |
 | `token-budget` | Token Budget Zone Standard |
 | `translation-lifecycle-standards` | Translation lifecycle standards: MISSING vs OUTDAT |
+| `turn-completion-integrity` | An agent writes *"I'll do X next"* and then ends t |
 | `user-journey-testing` | User Journey Testing Standard |
 | `user-story-mapping` | User Story Mapping Standards |
 | `verification-evidence` | Establish an "Iron Law" that no task can be claime |
@@ -323,6 +339,7 @@
 | `check-ai-agent-sync.ps1` | Check Ai Agent Sync |
 | `check-ai-agent-sync.sh` | AI Agent Sync Checker |
 | `check-ai-yaml-parses.mjs` | Every shipped .ai.yaml must parse, and must parse  |
+| `check-bump-sync-roundtrip.mjs` | check-bump-sync-roundtrip — 測「跑完 bump 之後 check 必須通 |
 | `check-cli-docs-sync.ps1` | Check Cli Docs Sync |
 | `check-cli-docs-sync.sh` | CLI-to-Documentation Sync Checker |
 | `check-commands-sync.ps1` | Check Commands Sync |
@@ -332,6 +349,7 @@
 | `check-docs-integrity.sh` | Documentation Integrity Checker |
 | `check-docs-sync.ps1` | Check Docs Sync |
 | `check-docs-sync.sh` | Documentation Sync Checker |
+| `check-error-exit.mjs` | 🔴 沒填就是沒設定，而沒設定會 exit 2， |
 | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ- |
 | `check-orphan-specs.ps1` | Check Orphan Specs |
 | `check-orphan-specs.sh` | Orphan Spec Detection Script |
@@ -345,6 +363,7 @@
 | `check-standards-reference-sync.sh` | check-standards-reference-sync.sh |
 | `check-standards-sync.ps1` | Check Standards Sync |
 | `check-standards-sync.sh` | Standards Consistency Checker |
+| `check-translation-hash-ratchet.sh` | XSPEC-392 R6 棘輪：新的翻譯必須帶 source_hash，既有的欠債冷凍為基線。 |
 | `check-translation-sync.ps1` | Check Translation Sync |
 | `check-translation-sync.sh` | Translation Sync Checker |
 | `check-usage-docs-sync.ps1` | Check if usage documentation needs to be regenerat |
@@ -356,7 +375,9 @@
 | `convert-md-to-yaml.mjs` | Markdown to AI-YAML Conversion Script |
 | `fix-manifest-paths.ps1` | Fix Manifest Paths |
 | `fix-manifest-paths.sh` | Manifest Path Fixer |
+| `generate-adoption-skills.mjs` | Self-Adoption Skill Copy Generator and Drift Gate  |
 | `generate-docs.mjs` | Look up the release date for `version` from CHANGE |
+| `generate-llms-txt.mjs` | llms.txt Generator and Drift Gate — XSPEC-385 |
 | `generate-locale-coverage.mjs` | Locale Coverage Generator |
 | `generate-version-manifest.mjs` | Generate Version Manifest (SPEC-SELFDIAG-001 REQ-9 |
 | `install-hooks.mjs` | Install Hooks |

package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md

@@ -45,7 +45,7 @@ status: current
   ◯ Windsurf (.windsurfrules)
   ◯ Cline (.clinerules)
   ◯ GitHub Copilot (.github/copilot-instructions.md)
-  ◯ Google Antigravity (INSTRUCTIONS.md) - Gemini Agent
+  ◯ Google Antigravity (.agents/AGENTS.md) - Gemini Agent
   ── AGENTS.md Tools ──
   ◯ OpenAI Codex (AGENTS.md) - OpenAI Codex CLI
   ◯ OpenCode (AGENTS.md) - Open-source AI coding agent
@@ -68,7 +68,7 @@ status: current
 | **Windsurf** | `.windsurfrules` | Plaintext | Windsurf IDE 規則檔 |
 | **Cline** | `.clinerules` | Plaintext | Cline 擴展規則檔 |
 | **GitHub Copilot** | `.github/copilot-instructions.md` | Markdown | Copilot 自訂指示 |
-| **Google Antigravity** | `INSTRUCTIONS.md` | Markdown | Gemini Agent 系統指令 |
+| **Google Antigravity** | `.agents/AGENTS.md` | Markdown | Gemini Agent 系統指令 |
 | **OpenAI Codex** | `AGENTS.md` | Markdown | OpenAI Codex CLI |
 | **OpenCode** | `AGENTS.md` | Markdown | 開源 AI 編碼 Agent（與 Codex 共用檔案） |
 | **Gemini CLI** | `GEMINI.md` | Markdown | Google Gemini CLI |
@@ -626,21 +626,26 @@ uds init
 ```
 ? Select content level:
 ❯ Standard (推薦) - Summary + links to full docs
-  Full Embed - All rules in one file (larger)
   Minimal - Core rules only (smallest)
 ```
 
 ### 說明
 
-決定 AI 工具整合檔案中嵌入多少標準內容。這是影響 AI 合規程度的關鍵設定。
+決定 AI 工具整合檔案中嵌入多少標準內容。
+
+> **第三個模式 `full`（Full Embed）已於 UDS 6.9.0 移除。**
+> 它從來沒有產生過與 `index` 不同的檔案——產生器只在 `minimal` 上分支，
+> 因此兩者在實測的 24 組（工具 × 語言）組合中輸出逐位元相同。
+> `--content-mode full` 仍然接受，並解析為 `index`；manifest 中記錄的 `full`
+> 會在下一次執行時改寫為 `index`。**任何專案拿到的檔案都不會改變**，
+> 因為兩個模式本來就產生相同的位元組。詳見 XSPEC-357 R7。
 
 ### 選項
 
-| 模式 | 檔案大小 | AI 可見性 | 適用情境 |
-|------|----------|-----------|----------|
-| **Standard** (推薦) | 中等 | 高 | 大多數專案 |
-| **Full Embed** | 最大 | 最高 | 企業級合規 |
-| **Minimal** | 最小 | 低 | 舊專案遷移 |
+| 模式 | 內容 | 適用情境 |
+|------|------|----------|
+| **Standard**（`index`，推薦） | 標準索引 + MUST/SHOULD 任務對照表 | 大多數專案 |
+| **Minimal**（`minimal`） | 僅檔案參考 | 由 Skills 提供任務指引的專案 |
 
 ### 詳細說明
 
@@ -714,47 +719,17 @@ uds init
 - ✅ 希望 AI 遵守規範但不想檔案太大
 - ✅ AI 工具會讀取專案檔案
 
-#### Full Embed 模式
-
-**生成內容**：完整嵌入所有規則
-
-```markdown
-## Anti-Hallucination Protocol
-Reference: .standards/anti-hallucination.md
-
-### Core Principle
-You are an AI assistant that prioritizes accuracy over confidence...
-
-### Evidence-Based Analysis
-1. **File Reading Requirement**
-   - You MUST read files before analyzing them
-   - Do not guess APIs, class names, or library versions
-...
-
----
-
-## Commit Message Standards
-Reference: .standards/commit-message.ai.yaml
+#### Full Embed 模式（已移除）
 
-### Format Structure
-<type>(<scope>): <subject>
-
-### Commit Types
-| Type | Description | Example |
-| feat | New feature | feat(auth): add OAuth2 login |
-...
-```
+這一節原本描述一個把完整規則內文嵌進整合檔案的模式，宣稱能「**保證**」AI
+看到所有標準，並產生「比 Index 大 3-5 倍」的檔案。
 
-**特點**：
-- 所有核心規則直接嵌入
-- AI **保證**看到所有標準
-- 檔案大小可能是 Index 的 3-5 倍
+**這些從來都沒有被實作。** `full` 與 `index` 走同一條程式路徑、寫出相同的位元組。
+它也不可能照描述運作：`.standards/` 約 248k token，遠超過任何整合檔案裝得下的量。
+該模式已於 UDS 6.9.0 移除（XSPEC-357 R7），現在解析為 `index`。
 
-**適用情境**：
-- ✅ 企業級合規要求
-- ✅ AI 可能不讀取外部檔案
-- ✅ 不能容許 AI 遺漏任何規則
-- ✅ 新團隊導入，確保完全了解規範
+若你當初是為了合規理由選擇它，你拿到的一直都是 `index` 的輸出，
+因此產生的檔案不會有任何改變。
 
 ### 決策流程
 
@@ -763,19 +738,8 @@ Reference: .standards/commit-message.ai.yaml
         │
         ▼
   ┌─────────────────────────────┐
-  │ AI 是否會主動讀取專案檔案？  │
-  └─────────────────────────────┘
-        │
-    ┌───┴───┐
-    │       │
-   是       否
-    │       │
-    ▼       ▼
-Index    Full
-    │
-    ▼
-  ┌─────────────────────────────┐
-  │ 是否有嚴格合規要求？         │
+  │ 是否已安裝 Skills 並由它     │
+  │ 提供任務指引？               │
   └─────────────────────────────┘
         │
     ┌───┴───┐
@@ -783,10 +747,7 @@ Index    Full
    是       否
     │       │
     ▼       ▼
- Full    Index
-
-
-舊專案遷移 / 想要最小改動？ → Minimal
+Minimal  Index
 ```
 
 ### 使用案例
@@ -794,11 +755,11 @@ Index    Full
 | 案例 | 推薦模式 | 理由 |
 |------|----------|------|
 | 新創團隊的 SaaS 專案 | **Index** | 平衡效率與規範 |
-| 銀行核心系統 | **Full** | 法規要求，不能遺漏 |
+| 銀行核心系統 | **Index** | 索引會列出每一條適用標準與適用時機 |
 | 個人 side project | **Minimal** | 輕量就好 |
 | 開源專案 | **Index** | 讓貢獻者 AI 知道規範 |
 | 從舊設定遷移 | **Minimal** | 保留現有設定 |
-| 新導入 AI 的傳統企業 | **Full** | 確保 AI 完全遵循 |
+| 新導入 AI 的傳統企業 | **Index** | 與已移除的 `full` 模式產出相同 |
 
 ---
 
@@ -895,8 +856,8 @@ uds init -y \
   --test-levels unit,integration \
   --content-mode index
 
-# 企業級完整設定
-uds init -y --content-mode full
+# 最小化整合檔案（由 Skills 提供任務指引）
+uds init -y --content-mode minimal
 
 # 生成 AGENTS.md 通用摘要（--yes 模式預設生成）
 uds init -y --agents-md