universal-dev-standards 6.11.0 → 6.13.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/bundled/ai/standards/developer-memory.ai.yaml +24 -2
  2. package/bundled/ai/standards/open-work-tracking.ai.yaml +216 -0
  3. package/bundled/ai/standards/turn-completion-integrity.ai.yaml +34 -2
  4. package/bundled/core/developer-memory.md +58 -2
  5. package/bundled/core/open-work-tracking.md +333 -0
  6. package/bundled/core/turn-completion-integrity.md +36 -2
  7. package/bundled/hooks/check-turn-completion-codex.mjs +116 -0
  8. package/bundled/hooks/check-turn-completion-gemini.mjs +81 -0
  9. package/bundled/hooks/check-turn-completion.mjs +24 -149
  10. package/bundled/hooks/turn-completion/engine.mjs +206 -0
  11. package/bundled/hooks/turn-completion/locales/en.mjs +29 -1
  12. package/bundled/hooks/turn-completion/locales/zh-TW.mjs +29 -1
  13. package/bundled/locales/zh-CN/CHANGELOG.md +23 -3
  14. package/bundled/locales/zh-CN/CLAUDE.md +1 -1
  15. package/bundled/locales/zh-CN/README.md +2 -2
  16. package/bundled/locales/zh-CN/SECURITY.md +2 -1
  17. package/bundled/locales/zh-CN/core/turn-completion-integrity.md +36 -6
  18. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +2 -1
  19. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +24 -5
  20. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +4 -3
  21. package/bundled/locales/zh-TW/CHANGELOG.md +23 -3
  22. package/bundled/locales/zh-TW/CLAUDE.md +1 -1
  23. package/bundled/locales/zh-TW/README.md +2 -2
  24. package/bundled/locales/zh-TW/SECURITY.md +2 -1
  25. package/bundled/locales/zh-TW/core/open-work-tracking.md +255 -0
  26. package/bundled/locales/zh-TW/core/turn-completion-integrity.md +36 -6
  27. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +2 -1
  28. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +24 -5
  29. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +4 -3
  30. package/package.json +1 -1
  31. package/src/commands/init.js +26 -0
  32. package/src/installers/hooks-installer.js +104 -0
  33. package/standards-registry.json +19 -7
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../../core/turn-completion-integrity.md
3
- source_version: 1.3.0
4
- translation_version: 1.3.0
5
- last_synced: 2026-09-08
6
- source_hash: c396baa28423
3
+ source_version: 1.4.0
4
+ translation_version: 1.4.0
5
+ last_synced: 2026-09-25
6
+ source_hash: 8966d46d5f79
7
7
  status: current
8
8
  ---
9
9
 
@@ -11,8 +11,8 @@ status: current
11
11
 
12
12
  > **语言**: [English](../../../core/turn-completion-integrity.md) | [繁體中文](../../zh-TW/core/turn-completion-integrity.md) | 简体中文
13
13
 
14
- **版本**: 1.3.0
15
- **最后更新**: 2026-09-08
14
+ **版本**: 1.4.0
15
+ **最后更新**: 2026-09-25
16
16
  **适用范围**: 任何由 agent 结束回合、把控制权交还给人的执行环境
17
17
  **Scope**: universal
18
18
  **行业标准**: 不声称任何来源——由实际观察到的失败归纳,见「证据」
@@ -141,6 +141,34 @@ agent 写下「我接着做 X」,然后结束回合,而 X 没有做。
141
141
 
142
142
  ---
143
143
 
144
+ ## 支持的执行环境
145
+
146
+ 这个检查只在「适配层存在,且 hook 真的被接入该执行环境自己的配置」时才生效。
147
+ 截至 v1.4.0:
148
+
149
+ | 执行环境 | 事件 | 配置文件 | 拦截契约 |
150
+ |---|---|---|---|
151
+ | Claude Code | Stop | `.claude/settings.json` | stdout 输出 `{"decision":"block","reason":...}`,exit 0;沉默即放行 |
152
+ | Codex | Stop | `.codex/hooks.json` | stdout 输出 `{"decision":"block","reason":...}`,exit 0——官方文档写明这个事件纯文本或空输出无效 |
153
+ | Gemini CLI | AfterAgent | `.gemini/settings.json` | stdout 输出 `{"decision":"deny","reason":...}`,exit 0——官方文档标记为优先于 exit code 2 的做法 |
154
+
155
+ Codex 的 R9 豁免是尽力而为,不是静默失效:Codex 的 Stop payload 直接给出
156
+ agent 的最后一条消息,却不给出用户的;要拿到用户那一侧必须解析一份
157
+ 对话记录文件,而它的确切格式在撰写本表时未对照真实安装验证过。解析失败时
158
+ 用户那一侧会变空——检测仍照样运行在 agent 消息上,只有那一轮的 R9 豁免
159
+ 可能漏掉。
160
+
161
+ Cursor 已评估但不支持:截至撰写本文时,Cursor 的 stop hook 能不能真的
162
+ 拦下一个回合仍未确定,若对着一个没人验证过的契约交付一份适配层,
163
+ 等于重演 R3 要防的那个失败——一个没人确认过真的在执法的执法机制。
164
+
165
+ 不在上表的任何执行环境,这个检查都是失效的——与语言不支持(R8)同一种
166
+ 「默认沉默」失败。`uds init --with-hooks` 会报告它把 hook 接入了哪些
167
+ 执行环境;它不会在这里穷举其余的,因为那份清单是一张等着在下一个
168
+ 执行环境被加入或移除时就过期的引用。
169
+
170
+ ---
171
+
144
172
  ## 检测器匹配什么
145
173
 
146
174
  形状是:**第一人称将来标记,接一个动作动词,在同一个句子里**,再减掉三个排除项。
@@ -188,3 +216,5 @@ agent 写下「我接着做 X」,然后结束回合,而 X 没有做。
188
216
  - [ ] 检查认得出自己的拦截消息,不把它读成人说的话
189
217
  - [ ] 检查认得出 R2 定义的逐项阻塞点结束,而且不拦它
190
218
  - [ ] 归属词的搜索排除检查自己的标题与结构
219
+ - [ ] 每个支持的执行环境的拦截契约都对照该环境自己的官方文档验证过,不是照搬另一个环境
220
+ - [ ] 安装器只为采用者实际选择的执行环境写入该环境的 hook 配置
@@ -1,6 +1,6 @@
1
1
  # UDS 速查表
2
2
 
3
- > Quick reference for all UDS features | Last updated: 2026-09-18
3
+ > Quick reference for all UDS features | Last updated: 2026-09-23
4
4
 
5
5
  **Language**: [English](../../../docs/user/CHEATSHEET.md) | [繁體中文](../../zh-TW/docs/CHEATSHEET.md) | 简体中文
6
6
 
@@ -260,6 +260,7 @@
260
260
  | `mutation-testing` | Mutation testing evaluates test suite effectivenes |
261
261
  | `no-cicd-deployment` | No-CI/CD Deployment Strategy |
262
262
  | `observability-standards` | Observability Standards |
263
+ | `open-work-tracking` | The deferred-item-exit standard requires that a de |
263
264
  | `packaging-standards` | This standard defines a Recipe-based packaging fra |
264
265
  | `performance-standards` | This standard defines comprehensive guidelines for |
265
266
  | `pii-classification` | PII Classification and Handling Standards |
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../docs/CLI-INIT-OPTIONS.md
3
- source_version: 3.5.2
4
- translation_version: 3.5.2
5
- last_synced: 2026-09-18
3
+ source_version: 3.6.0
4
+ translation_version: 3.6.0
5
+ last_synced: 2026-09-25
6
6
  status: current
7
7
  ---
8
8
 
@@ -10,8 +10,8 @@ status: current
10
10
 
11
11
  > **语言**: [English](../../../docs/CLI-INIT-OPTIONS.md) | [简体中文](../../zh-TW/docs/CLI-INIT-OPTIONS.md) | 简体中文
12
12
  >
13
- > **版本**: 3.5.2
14
- > **最后更新**: 2026-09-18
13
+ > **版本**: 3.6.0
14
+ > **最后更新**: 2026-09-25
15
15
 
16
16
  本文档详细说明 `uds init` 命令的每一个选项,包含使用情境、影响范围和建议选择。
17
17
 
@@ -838,6 +838,25 @@ uds init --experimental
838
838
  | Claude Code 目标文件 | `--claude-target` | Claude Code 集成内容要写到哪里:`project`(`CLAUDE.md`,默认)或 `local`(`CLAUDE.local.md`) |
839
839
  | 模式(已弃用) | `-m, --mode` | 安装模式(skills, full)- 请改用 `--skills-location` |
840
840
 
841
+ ### Claude Code 以外的强制执行 Hooks
842
+
843
+ `--with-hooks` 一定会安装进 `.claude/settings.json`。四个有 hook 支持的标准
844
+ 之一——`turn-completion-integrity`(见 CHANGELOG,Unreleased)——也会装进
845
+ **Codex** 与 **Gemini CLI**,门槛是你有没有在 [AI 工具选择](#1-ai-工具选择)
846
+ 里选了那个工具(或用非交互模式的工具标志带入):
847
+
848
+ | 工具 | 写入的配置文件 | 触发条件 |
849
+ |------|---------------|---------|
850
+ | Codex | `.codex/hooks.json` | 选了 **OpenAI Codex** |
851
+ | Gemini CLI | `.gemini/settings.json` | 选了 **Gemini CLI** |
852
+
853
+ 没选的工具不会写入任何东西——`uds init` 不会在没用到 Codex 或 Gemini CLI
854
+ 的项目里创建 `.codex/` 或 `.gemini/` 目录。其余三个有 hook 支持的标准
855
+ (commit message 校验、logging、security)目前仍只支持 Claude Code;
856
+ 为什么目前只推广 turn-completion-integrity,以及 Cursor 的现状
857
+ (已评估、不支持),见
858
+ [支持的执行环境](../../../core/turn-completion-integrity.md#supported-harnesses)。
859
+
841
860
  ### Claude Code 集成目标文件(`--claude-target`)
842
861
 
843
862
  UDS 默认把 Claude Code 内容写进 `CLAUDE.md`——团队共用、会进版本控制的那个文件。
@@ -1,7 +1,7 @@
1
1
  # UDS 功能参考手册
2
2
 
3
3
  > Universal Development Standards - 完整功能文档
4
- > Auto-generated | Last updated: 2026-09-18
4
+ > Auto-generated | Last updated: 2026-09-23
5
5
 
6
6
  **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | [繁體中文](../../zh-TW/docs/FEATURE-REFERENCE.md) | 简体中文
7
7
 
@@ -14,10 +14,10 @@
14
14
  3. [技能](#skills) (55)
15
15
  4. [代理](#agents) (5)
16
16
  5. [工作流程](#workflows) (5)
17
- 6. [核心规范](#core-standards) (152)
17
+ 6. [核心规范](#core-standards) (153)
18
18
  7. [脚本](#scripts) (59)
19
19
 
20
- **Total Features: 350**
20
+ **Total Features: 351**
21
21
 
22
22
  ---
23
23
 
@@ -516,6 +516,7 @@
516
516
  | `mutation-testing` | 1.1.0 | Mutation testing evaluates test suite effectiveness by injecting artificial bugs |
517
517
  | `no-cicd-deployment` | - | |
518
518
  | `observability-standards` | 1.0.0 | |
519
+ | `open-work-tracking` | 1.0.0 | The deferred-item-exit standard requires that a deferred item leave its document |
519
520
  | `packaging-standards` | 1.1.0 | This standard defines a Recipe-based packaging framework that enables user proje |
520
521
  | `performance-standards` | 1.2.0 | This standard defines comprehensive guidelines for software performance engineer |
521
522
  | `pii-classification` | 1.1.0 | **Status**: Active | **Updated**: 2026-06-19 | |
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 6.11.0
4
- translation_version: 6.11.0
5
- last_synced: 2026-09-18
3
+ source_version: 6.13.0-beta.1
4
+ translation_version: 6.13.0-beta.1
5
+ last_synced: 2026-09-25
6
6
  status: current
7
7
  ---
8
8
 
@@ -17,6 +17,26 @@ status: current
17
17
 
18
18
  ## [Unreleased]
19
19
 
20
+ ## [6.13.0-beta.1] - 2026-09-26
21
+
22
+ > **測試版** — 以 `npm install -g universal-dev-standards@beta` 安裝。要測什麼、已知限制、如何退回正式版:見 [docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。已知限制:`uds uninstall` 尚不會移除 Codex/Gemini CLI 設定裡的關卡。
23
+
24
+ ### 新增
25
+
26
+ - **`turn-completion-integrity` 1.4.0 把 Stop 關卡推廣到 Codex 與 Gemini CLI,與既有的 Claude Code 轉接層並存。** 判斷邏輯(語料包、冷卻、滾動視窗、自我回音標記)抽到共用的 `turn-completion/engine.mjs`,三支工具腳本各自只轉譯自己工具的契約,不再各帶一份判斷邏輯。Codex(`.codex/hooks.json`,Stop 事件)直接從 stdin 讀 `last_assistant_message`,在 exit 0 時於 stdout 印 `{"decision":"block","reason":...}` 來擋下——官方文件寫明這個事件純文字或空輸出無效,這點與 Claude Code 的「沉默即放行」不同;使用者的最後一則訊息用 `transcript_path` 盡力讀取,因為其確切格式未對照真實安裝驗證過,所以 R9(豁免使用者主動喊停的回合)在 Codex 上是文件記載的已知落差,不是靜默失效。Gemini CLI(`.gemini/settings.json`,`AfterAgent` 事件)的 stdin 直接給 `prompt` 與 `prompt_response`,完全不需要解析逐字稿,擋下方式是 `{"decision":"deny","reason":...}`——官方文件標記為優先於 exit code 2 的做法。`uds init --with-hooks` 現在也會呼叫 `installCodexHooks`/`installGeminiHooks`,門檻是採用者有沒有選那個工具,沒用到 Codex 或 Gemini CLI 的專案不會被寫入任何東西。Cursor 已評估,明確標記為不支援(Cursor 的 stop hook 能不能真的擋下一個回合仍未確定)。見[支援的執行環境](../../core/turn-completion-integrity.md#supported-harnesses)與 [CLI-INIT-OPTIONS.md](../../docs/CLI-INIT-OPTIONS.md#claude-code-以外的強制執行-hooks)。
27
+
28
+ - **`developer-memory` 1.2.0:新增 `code-reference` 過期查核——記憶引用的檔案路徑或符號一旦搬走或不存在,浮出前就會被標記,不再被悄悄沿用。** 沿用 `knowledge-graph-memory` 1.0.0 已定義的雙模式(§2),不另外發明第三種:降級模式(沒有圖引擎——AI 自己用 Glob/Grep/Read 確認引用還在,與既有的記憶驗證原則同一套機制)與引擎模式(有圖引擎時,例如 EngramGraph 的 `egr refs check`,回報每個引用的狀態:`present`/`moved`(附新位置)/`missing`/`unresolvable`)。`unresolvable` 一律不得當成 `present` 或 `missing`——它代表查核器無法判斷,不是引用沒事或已消失。時機掛在既有的 `proactive-surfacing` 規則(§4.1),查核在記憶浮出**之前**進行,不是之後。第一批只涵蓋檔案路徑與符號名稱(函式/類別);`file:line` 明確排除在外——行號會隨任何不相關的編輯漂移,屬於不同種類的過期(見 DEC-115 OQ-1,2027-01-31 前重新評估)。`core/developer-memory.md` §11 加入一段非規範性的 Claude Code `SessionStart` hook 範例;其他工具則改走各自 repo 的說明檔(CLAUDE.md/AGENTS.md/.cursorrules 等)。(DEC-115-L1)
29
+
30
+ ### 修正
31
+
32
+ - **`turn-completion-integrity` 的 zh-TW 與 en 偵測器,會在前提是使用者自己決定的條件式承諾上誤擋。** 「你選定後,我會把這一輪的發想寫成正式決策紀錄…」被判成未兌現的承諾——既有的豁免只涵蓋「要求資訊」與「要求回報」,沒有涵蓋「前提是使用者的決定」這種條件句。zh-TW 新增一支窄樣式:你 + 短決定動詞(選定/選好/決定/確認/回覆/點頭)+ 後 + 逗號 + 我;en 新增以文法為準(不是動詞清單,延續本包既有設計)的 `(once|after|as soon as) you ..., I` 樣式。兩份語料都補了成對的反例(主詞不是你/you,或只有一半的形狀),證明收窄沒有連帶漏擋真的未兌現承諾;en 版本也記下一個刻意留下未解的已知限制(前提與 "I" 之間沒有逗號時仍會誤擋——放寬會漏擋真的未兌現承諾)。
33
+
34
+ ## [6.12.0] - 2026-09-25
35
+
36
+ ### 新增
37
+
38
+ - **新標準 `open-work-tracking`——`deferred-item-exit` 的下游一半。** `deferred-item-exit` 要求被延後的項目離開原文件、走向可追溯的出口,但刻意不規定出口的承載處;東西進了承載處之後,沒有任何規則防止承載處本身腐壞。本標準以 16 條要求(OWT-001~016)補上:低摩擦的記錄點(必填欄位至多兩個)、每個等待中的項目旁寫明解除條件、可推導的欄位由產生而非手寫、以內容證明「最新」而非可隨手改的時間戳、覆蓋率數字要寫出它看不到什麼,以及每輪結束時回報未完成工作但**從不阻擋**的檢查點。最後一點刻意與掛在同一事件、會阻擋的 `turn-completion-integrity` 相反;標準內附對照表,避免採用者把兩者接成同一件事。其中兩個數字門檻標明為初始判斷、非量測結果。
39
+
20
40
  ## [6.11.0] - 2026-09-18
21
41
 
22
42
  ### 修正
@@ -14,7 +14,7 @@ status: current
14
14
 
15
15
  Universal Development Standards 是一個語言無關、框架無關的文件化標準框架。它提供:
16
16
 
17
- - **核心規範** (`core/`):152 個基礎開發標準
17
+ - **核心規範** (`core/`):153 個基礎開發標準
18
18
  - **AI 技能** (`skills/`):用於 AI 輔助開發的 Claude Code 技能
19
19
  - **CLI 工具** (`cli/`):用於採用標準的 Node.js CLI
20
20
  - **整合** (`integrations/`):各種 AI 工具的配置
@@ -15,7 +15,7 @@ status: current
15
15
 
16
16
  > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
17
17
 
18
- **版本**: 6.11.0 | **發布日期**: 2026-09-16 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
18
+ **版本**: 6.13.0-beta.1 (Pre-release) | **發布日期**: 2026-09-26 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
19
19
 
20
20
  語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流,確保不同技術堆疊之間的一致性、品質和可維護性。
21
21
 
@@ -76,7 +76,7 @@ npx universal-dev-standards init
76
76
  <!-- UDS_STATS_TABLE_START -->
77
77
  | 類別 | 數量 | 說明 |
78
78
  |----------|-------|-------------|
79
- | **核心標準** | 152 | 通用開發準則 |
79
+ | **核心標準** | 153 | 通用開發準則 |
80
80
  | **AI Skills** | 55 | 互動式技能 |
81
81
  | **斜線命令** | 51 | 快速操作 |
82
82
  | **CLI 指令** | 23 | 專案設定與維護 |
@@ -13,7 +13,8 @@ status: current
13
13
  <!-- UDS_SUPPORTED_VERSIONS_START -->
14
14
  | 版本 | 支援狀態 |
15
15
  |------|--------|
16
- | 6.11.0 | ✅ 最新正式版 |
16
+ | 6.13.0-beta.1 | ✅ 預發布版本 |
17
+ | 6.12.0 | ✅ 最新正式版 |
17
18
  | < 6.0.0 | ❌ 已終止支援 |
18
19
  <!-- UDS_SUPPORTED_VERSIONS_END -->
19
20
 
@@ -0,0 +1,255 @@
1
+ ---
2
+ source: ../../../core/open-work-tracking.md
3
+ source_version: 1.0.0
4
+ translation_version: 1.0.0
5
+ last_synced: 2026-09-23
6
+ source_hash: 8382d3f518a9
7
+ status: current
8
+ ---
9
+
10
+ # 開放工作追蹤標準
11
+
12
+ > **Language**: [English](../../../core/open-work-tracking.md) | 繁體中文
13
+
14
+ **版本**: 1.0.0
15
+ **最後更新**: 2026-09-23
16
+ **適用**: 任何跨越一個以上工作階段承載工作、有可能在階段之間遺失項目的專案
17
+ **範圍**: universal
18
+
19
+ ---
20
+
21
+ ## 目的
22
+
23
+ 延後項目出口標準(deferred-item-exit)要求延後項目離開文件、抵達一個可追蹤的出口,
24
+ 但刻意不規定那個出口長什麼樣、也不規定項目抵達之後什麼東西防止它腐壞。
25
+ **本標準是那個下游的一半**:假設一個承載開放工作的地方已經存在,
26
+ 它自己必須具備什麼性質才不會慢慢變得不可信。見 [deferred-item-exit](deferred-item-exit.md)。
27
+
28
+ 三種不同的「工作不見了」的方式,常被塞進同一份沒有分別的清單,而**這個合併本身就是失敗的一部分**——
29
+ 一份想同時接住三者的清單,通常一個都接不好:
30
+
31
+ | 症狀 | 背後的問題 | 需要的機制 |
32
+ |---|---|---|
33
+ | 工作進行中冒出新項目,沒有低摩擦的地方可以記下它 | 項目有時效性,等到方便記錄時已經忘了 | 一個便宜到不會打斷當前工作的收件點 |
34
+ | 某項目因等待別的事件而暫停 | 「等待中」若沒有記錄解除條件,與「被忘記」無法分辨 | 與等待一起記錄的解除條件 |
35
+ | 已規劃的項目還沒動工,時間過去 | 沒有時鐘的項目會無聲腐爛——沒有東西會再指向它 | 一個門檻,或一次被迫的定期檢視,讓它重新浮現 |
36
+
37
+ 下面每一條要求都對應這張表的一列,或對應本標準設計當天觀察到的四個失效之一
38
+ (見〈[證據與校準](#證據與校準)〉)。**沒有任何一個機制被規定**——
39
+ 理由與 [deferred-item-exit](deferred-item-exit.md) 對自己出口的約束相同(DEC-049:
40
+ UDS 定義必須成立的關係,維持它的機制由採用層選擇)。
41
+
42
+ ---
43
+
44
+ ## 本標準的寫法,以及為什麼這樣寫
45
+
46
+ **讀下面任何一條要求之前先讀這一段。它拘束它們全部。**
47
+
48
+ UDS 定義**活動**,採用層負責**編排**(DEC-049)。一份寫成工作流協定、檔案格式、
49
+ 或特定工具設定的標準屬於採用層,不屬於這裡——這與 [deferred-item-exit](deferred-item-exit.md)
50
+ 受的約束相同,只是套用在下游一層。
51
+
52
+ | 這裡容許——**what** | 這裡不容許——**how** |
53
+ |---|---|
54
+ | 收件點欄位數必須具備的性質 | 收件點是哪個 app、檔案或工單系統 |
55
+ | 等待項目與解除條件之間必須存在的關係 | 輪詢那個條件的排程器或機器人 |
56
+ | 「這是最新的」這句宣稱必須從什麼可被證明 | 具體用哪個雜湊函式、diff 工具或 CI 供應商 |
57
+ | 一個回報數字與它看不到的部分之間的關係 | 儀表板版面或報告範本 |
58
+ | 控制權交回人的那一點存在一個確認點,且它永不阻斷 | 用什麼 hook 系統、shell 或 cron 實作它 |
59
+
60
+ **直說它的後果**:本標準**不附帶任何閘門**。它只說一個承載開放工作的地方必須具備什麼性質;
61
+ 有沒有東西在檢查,是採用專案的決定——[OWT-014](#要求) 與 [OWT-015](#要求)
62
+ 存在的目的,是讓那個決定沒辦法被默默做掉。
63
+
64
+ ---
65
+
66
+ ## 不變量
67
+
68
+ **一個承載開放工作的地方,必須:(1)不要求分類就能收下新項目、(2)為每一個標為等待中的項目記下解除條件、
69
+ (3)對任何有可靠來源可推導的欄位改用生成、(4)回報還剩什麼時同時揭露看不到什麼、
70
+ (5)在控制權從 agent 交回人的那一刻被檢視——而且那個檢視不能讓回合失敗。**
71
+
72
+ ---
73
+
74
+ ## 要求
75
+
76
+ | ID | 要求 | 嚴重度 |
77
+ |---|---|---|
78
+ | **OWT-001** | 新項目的收件點必填欄位不得超過兩個。分類、優先級、負責人一律是 triage 時的動作,不得成為輸入門檻 | error |
79
+ | **OWT-002** | 標為等待中的項目,同時記下在等什麼與什麼事件視為解除 | error |
80
+ | **OWT-003** | 能從版控、規格標記、或 CI 結果完整推導的欄位,一律生成,不手寫 | error |
81
+ | **OWT-004** | 生成區段的「最新」宣稱能從它所本的內容證明(例如來源雜湊),不靠一個人可編輯的日期 | error |
82
+ | **OWT-005** | 「內容可證明最新」與「日期宣稱最新、內容未驗證」回報為兩個相異狀態。合併為單一通過即不滿足 OWT-004 | error |
83
+ | **OWT-006** | 任何「還有 N 項」的數字,旁邊同時印出看得見多少來源、看不見多少來源。看不見的部分不被讀成零 | error |
84
+ | **OWT-007** | 開放工作摘要出現在控制權從 agent 交回人的那一刻——不只是掛在 session 開始、CI、或追蹤文件被編輯時 | error |
85
+ | **OWT-008** | 開放工作摘要自己的結束路徑,不論輸入為何(含「還有很多項」)都不改變回合的結果 | error |
86
+ | **OWT-009** | 摘要與一道阻斷式檢查掛同一個回合結束事件時,摘要的輸出排在阻斷判決之前 | warning |
87
+ | **OWT-010** | 判定項目是等待中、未分類、還是已丟棄,來自承載庫自定義的結構欄位,不只靠掃描散文措辭 | error |
88
+ | **OWT-011** | 以措辭啟發式補充結構欄位時,明示其涵蓋率未知,其乾淨結果不回報為「沒有漏掉」 | warning |
89
+ | **OWT-012** | 超過宣告門檻仍未分類的項目,在開放工作摘要裡被個別點名,不被合併進一個總數 | error |
90
+ | **OWT-013** | 項目從承載庫移除而未變成規格、追蹤項目、或任何其他具名去向時,帶一句理由。沒有理由的移除與靜默刪除無法分辨 | error |
91
+ | **OWT-014** | 本標準的每一條要求都可表述為 artefact 之間可判定的關係。不能如此表述的要求不得進入本標準 | error |
92
+ | **OWT-015** | 被提出作為本標準任一要求之證據的檢查,已被觀察到對一個刻意違反該要求的樣本回報失敗。從未紅過的檢查不是可採信的證據 | error |
93
+ | **OWT-016** | 本標準各要求所引用的任何窗口或閾值,載明來歷,或標為未校準 | warning |
94
+
95
+ ---
96
+
97
+ ## 收件幾乎不能有成本
98
+
99
+ **OWT-001** 之所以存在,是因為多一個必填欄位的收件點,量測到的結果是**不被使用**。
100
+ 這不是假想的摩擦——它是「工作進行中冒出新想法,記下它要跟正在做的事搶時間」這個情境的具體形狀。
101
+ 在**輸入當下**就要求分類、優先級或負責人,是在賭「正在被打斷的人願意付那個成本」,
102
+ 而這個賭注輸的次數比贏的多;一個沒有人用的收件點不是收件點,是一張表單。
103
+
104
+ 分類(決定項目屬於哪裡)是另一個、之後才做的動作。**OWT-012** 與 **OWT-013**
105
+ 規範分類永遠不來時會發生什麼:項目不准永遠隱形地待著,也不准無理由地消失。
106
+
107
+ ---
108
+
109
+ ## 沒有解除條件的等待項目,是戴著狀態標籤的遺忘項目
110
+
111
+ **OWT-002** 指出「暫停中、有東西會讓它回來」與「暫停中、永遠、只是貼了一個讓它看起來不像永遠的標籤」
112
+ 之間的差別。解除條件應盡可能是**機器看得見的**——一個日期、一個會出現的識別字、一個檔案存在——
113
+ 讓項目有機會自己跳出來,而不是依賴某個人記得它存在。真的找不到機器看得見的條件時,
114
+ 仍然要求一個人看得懂的條件;**OWT-002 不要求自動化,只要求那個條件被記下來這件事本身**。
115
+
116
+ ---
117
+
118
+ ## 戳比事實好寫,而只讀戳的檢查分不出兩者
119
+
120
+ 這是 DEX-006 在另一個 artefact 上點名的同一種失敗,只是換了一層。DEX-006 那邊,
121
+ 識別字的存在被誤讀成它指向的出口是對的;這裡,**生成區段的時間戳很新,被誤讀成內容是新的**——
122
+ 而這兩者分歧的方式,對任何只比較日期的檢查是隱形的:
123
+
124
+ - 戳比內容舊:拿戳跟檔案自己的修改紀錄一比就抓到,微不足道。
125
+ - 戳**比內容新**,而內容本身已經過期:**隱形**,因為「戳是新的」正是一次正確對帳看起來的樣子。
126
+
127
+ **OWT-004** 要求「這是最新的」這句宣稱可以從內容本身被證明——例如儲存一份該區段
128
+ 是從哪個來源生成的雜湊、放在區段旁邊,這樣不比對內容也能偵測到不一致,
129
+ 不必信任「最後動手改日期的人也真的對過帳」。**OWT-005** 要求「內容可證明是最新的」
130
+ 與「日期這麼說、內容未驗證」永遠不共用同一個通過/失敗位元,理由與 DEX-005/DEX-006
131
+ 要求延後項目出口做同一件事相同:一個被回報成通過的未知,比一個被回報成未知的未知更糟,
132
+ 因為後者還找得到。
133
+
134
+ ---
135
+
136
+ ## 涵蓋率必須聲明自己的盲區
137
+
138
+ **OWT-006** 要求任何「還有 N 項」的數字旁邊,同時印出它看得見多少來源、看不見多少來源——
139
+ 不是因為預期看不見的數字會是零,而是因為讀者分不出「涵蓋率 11.7%,而且有 386 項
140
+ 對這個數字完全隱形」與「涵蓋率 11.7% 就是全貌」,除非分母被印在旁邊。
141
+ 一個沒有聲明盲區的涵蓋率數字,預設會被讀成完整——而那個預設正是這條要求要防的失效。
142
+
143
+ ---
144
+
145
+ ## 確認點是一份報告,不是一道閘門
146
+
147
+ **turn-completion-integrity**([TCI](turn-completion-integrity.md))與本標準的 OWT-007–OWT-009
148
+ 都掛在同一個事件——agent 的回合結束、控制權交回人類的那一刻——而它們被刻意設計成
149
+ **行為相反**。把兩者接到同一個事件卻不理解為什麼不同,會產出「擋在一件幾乎永遠為真的事情上的
150
+ 確認點」,或是「被誤認成閘門的報告」,兩者都不對:
151
+
152
+ | | [turn-completion-integrity](turn-completion-integrity.md) | 本標準(OWT-007–009) |
153
+ |---|---|---|
154
+ | 它在看什麼 | agent 自己最後一則訊息,看有沒有一個第一人稱承諾被說出口又被放棄 | 承載庫裡的任何項目,看有沒有沒解除條件的、沒出口的、或過門檻還沒分類的 |
155
+ | 預設狀態 | 罕見——只在那則訊息裡明確做了承諾又被丟下時才觸發 | 常見——「還有工作沒做完」幾乎永遠為真 |
156
+ | 違反時會怎樣 | 擋住回合結束,直到承諾被解決或說明卡在誰身上 | 永不阻斷。只能回報(OWT-008) |
157
+ | 為什麼行為相反 | 它在看的事件本身夠稀少,擋在它上面不會把耐性用完 | TCI 自己的規則已經寫出這裡不能做成閘門的理由:**「一個在每個回合都為真的閘門會被關掉,關掉之後它什麼都不保護」**(TCI R4)。開放工作非空幾乎永遠為真,所以這個確認點被設計成永不保留控制權 |
158
+ | 兩者掛同一事件時的順序 | — | 先回報(OWT-009),所以即使那個回合隨後被 TCI 擋下,它的輸出仍然可見 |
159
+
160
+ ---
161
+
162
+ ## 錨點:走訪結構,不走訪措辭
163
+
164
+ 判定一個項目是等待中、未分類、還是已丟棄,要**讀承載庫自己描述那個狀態的結構欄位**——
165
+ 一個狀態欄、一個型別化標記、一個小節標題——與 [deferred-item-exit](deferred-item-exit.md)
166
+ 的 DEX-007 要求走訪文件結構而非措辭來找延後項目是同一個道理。**OWT-010** 要求那個結構欄位
167
+ 存在,並且是真相的主要來源。
168
+
169
+ 一次自由文字措辭掃描(「含有『等待』這個詞」)可以正當地補充結構欄位——
170
+ 它能抓到那些寫進散文、從沒真的填進結構欄位的項目。但它繼承了 [class-level-fix](class-level-fix.md)
171
+ 對任何列舉清單指出的同一個限制:**它正確到下一個成員用清單沒預料到的寫法出現為止。**
172
+ **OWT-011** 要求它的涵蓋率明示為未知,且禁止它跑出乾淨結果就被回報成「沒有漏掉」。
173
+
174
+ ---
175
+
176
+ ## 一條無法被檢查的要求,不是這裡的要求
177
+
178
+ **OWT-014** 是對本標準自身內容的約束,與 [deferred-item-exit](deferred-item-exit.md) 的
179
+ DEX-003 扮演的角色相同。上面每一條都指名了 artefact 與它們之間可被判定的關係。
180
+ 一個本標準在意、卻無法這樣措辭的性質,會被排除在表格之外,而不是被寫成一條無法執行的期望。
181
+ 舉一例:「收件點真的有被使用」正是 OWT-001 存在要保護的結果,但那是一句關於人類長期行為的宣稱,
182
+ 不是某個時間點上 artefact 之間可判定的關係——所以它以散文形式出現在這裡,
183
+ 作為 OWT-001 存在的**理由**,而不是一條有編號的要求。
184
+
185
+ ### 一支從未紅過的檢查
186
+
187
+ **OWT-015** 原封不動地延續 [deferred-item-exit](deferred-item-exit.md) 的 DEX-004:
188
+ **一支從未失敗過的檢查,與一支不可能失敗的檢查,輸出一模一樣。** 在一支被宣稱為上面
189
+ 任一要求之證據的檢查,被觀察到「對一個刻意違反該要求的樣本回報失敗」之前,
190
+ 它的通過只是「有東西跑過」的證據,不是「要求成立」的證據。產生這份證據的程序、
191
+ 以及為何必須逐條而非整體進行,此處不複述——見 [class-level-fix](class-level-fix.md)
192
+ 與 [verification-evidence](verification-evidence.md)。
193
+
194
+ ### 閾值必須帶著來歷
195
+
196
+ **OWT-016** 延續 DEX-009:一個沒有來歷的閾值,是一個沒有人能評估要不要改的閾值。
197
+ 本標準自己的兩個數字閾值在下方〈[證據與校準](#證據與校準)〉裡照此標示,而非被斷言為已定案。
198
+
199
+ ---
200
+
201
+ ## 反模式
202
+
203
+ | 反模式 | 為什麼會失敗 |
204
+ |---|---|
205
+ | 三個以上必填欄位的收件表單 | 可量測地不再被使用;那份摩擦由正在打斷自己工作的人承擔 |
206
+ | 「之後再看」而沒有解除條件 | 與被忘記無法分辨;沒有東西會讓它回來 |
207
+ | 手動輸入、重複 git 或 CI 已知資訊的狀態 | 兩個擁有者,其中一個永遠不會被更新 |
208
+ | 沒有內容證明的「最後對過帳」日期 | 內容真的被重新核對過,跟日期只是被打上去,看起來一模一樣 |
209
+ | 「還有 47 項」而不寫分母 | 預設被讀成完整;看不見的大多數被誤讀成「都做完了」 |
210
+ | 確認點掛在 shell 啟動而不是回合結束 | 只要沒人剛好開新 shell,它就持續漂移 |
211
+ | 確認點擋住回合結束、理由是「還有工作沒做完」 | 每個回合都會觸發;永遠為真的閘門會被關掉,關掉之後什麼都不保護 |
212
+ | 分類狀態只靠散文措辭判讀 | 正確到某個項目用清單沒預料到的方式寫出來為止 |
213
+ | 項目從承載庫裡無聲消失 | 與一個弄丟它的 bug 無從分辨 |
214
+
215
+ ---
216
+
217
+ ## 什麼在執行本標準
218
+
219
+ **UDS 側沒有任何東西在執行,而這件事是被記錄的,不是被暗示的。** UDS 陳述一個承載開放工作的地方
220
+ 必須滿足的關係;有沒有東西去判定它,依上面的[寫法約束](#本標準的寫法以及為什麼這樣寫),
221
+ 是採用專案的決定——與 [deferred-item-exit](deferred-item-exit.md) 對自己出口劃的界線相同。
222
+
223
+ 本標準做的事,是讓那個決定顯形:OWT-014 保證這裡每一條**能**被判定,OWT-015 固定
224
+ 「一次判定要算數需要什麼」,OWT-005/OWT-011 固定「一次不完整的判定容許印出什麼」。
225
+
226
+ ---
227
+
228
+ ## 證據與校準
229
+
230
+ 本標準的形狀來自一個採用專案在標準草擬**同一天**做出並實跑的觀察(XSPEC-427,2026-09-23):
231
+ 一個收件點、一支帶自測臂的摘要腳本、一個掛在回合結束的 hook,當天第一次建立並執行。
232
+ **寫下這段文字時,那個參考實作只有幾小時大、只有一個使用者、只在一個 repo 跑過。**
233
+ 它在此被引用,僅作為要求形狀的出處,**絕不作為下面具體閾值的驗證**。
234
+
235
+ - **OWT-001 的「不超過兩個欄位」**與**OWT-012 的「過了宣告的門檻」**(在原始觀察中以兩週為例)
236
+ 依 OWT-016 是**初始判斷,不是量測結果**——兩個欄位跟三個欄位、兩週跟四週的未分類門檻,
237
+ 目前都沒有對照比較過。
238
+ - 依實際使用情況重新校準這兩個數字、或將其中任一個降級為專案特定指引,是採用專案自己的決定
239
+ 與自己的時程——本標準不承諾這件事,如同它不附帶閘門一樣。
240
+
241
+ ---
242
+
243
+ ## 與其他標準的關係
244
+
245
+ - [deferred-item-exit](deferred-item-exit.md) — 同一個形狀的上游一半:DEX 要求延後項目離開文件、
246
+ 抵達可追蹤的出口,並刻意不規定出口的載體。本標準接手**出口存在之後**的事,
247
+ 要求那個載體自己不要變成下一份東西會不見的文件。
248
+ - [turn-completion-integrity](turn-completion-integrity.md) — 掛在同一個事件(回合結束)
249
+ 上,且被設計成行為相反:TCI 擋在一個罕見、明確的被放棄承諾上;本標準的確認點
250
+ (OWT-007–OWT-009)永不阻斷,因為它在看的條件幾乎永遠為真。見〈[對照表](#確認點是一份報告不是一道閘門)〉。
251
+ - [class-level-fix](class-level-fix.md) — OWT-011 揭露的措辭清單限制的通則形式,
252
+ 也是 OWT-015 所要求「非空跑證據」程序的來源。
253
+ - [verification-evidence](verification-evidence.md) — OWT-015 所依賴的 exit code
254
+ 與證據有效性推理的來源;也是 OWT-006/OWT-011 的部分涵蓋例外該被登記的地方,
255
+ 而不是揭露一次就放著。
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../../core/turn-completion-integrity.md
3
- source_version: 1.3.0
4
- translation_version: 1.3.0
5
- last_synced: 2026-09-08
6
- source_hash: c396baa28423
3
+ source_version: 1.4.0
4
+ translation_version: 1.4.0
5
+ last_synced: 2026-09-25
6
+ source_hash: 8966d46d5f79
7
7
  status: current
8
8
  ---
9
9
 
@@ -11,8 +11,8 @@ status: current
11
11
 
12
12
  > **Language**: [English](../../../core/turn-completion-integrity.md) | 繁體中文
13
13
 
14
- **版本**: 1.3.0
15
- **最後更新**: 2026-09-08
14
+ **版本**: 1.4.0
15
+ **最後更新**: 2026-09-25
16
16
  **適用範圍**: 任何由 agent 結束回合、把控制權交還給人的執行環境
17
17
  **Scope**: universal
18
18
  **產業標準**: 不宣稱任何來源——由實際觀察到的失敗歸納,見「證據」
@@ -141,6 +141,34 @@ agent 寫下「我接著做 X」,然後結束回合,而 X 沒有做。
141
141
 
142
142
  ---
143
143
 
144
+ ## 支援的執行環境
145
+
146
+ 這個檢查只在「轉接層存在,且 hook 真的被接進該執行環境自己的設定」時才生效。
147
+ 截至 v1.4.0:
148
+
149
+ | 執行環境 | 事件 | 設定檔 | 阻擋契約 |
150
+ |---|---|---|---|
151
+ | Claude Code | Stop | `.claude/settings.json` | stdout 印 `{"decision":"block","reason":...}`,exit 0;沉默即放行 |
152
+ | Codex | Stop | `.codex/hooks.json` | stdout 印 `{"decision":"block","reason":...}`,exit 0——官方文件寫明這個事件純文字或空輸出無效 |
153
+ | Gemini CLI | AfterAgent | `.gemini/settings.json` | stdout 印 `{"decision":"deny","reason":...}`,exit 0——官方文件標記為優先於 exit code 2 的做法 |
154
+
155
+ Codex 的 R9 豁免是盡力而為,不是靜默失效:Codex 的 Stop payload 直接給
156
+ agent 的最後一則訊息,卻不給使用者的;要拿到使用者那一側必須解析一份
157
+ 逐字稿檔案,而它的確切格式在撰寫本表時未對照真實安裝驗證過。解析失敗時
158
+ 使用者那一側會變空——偵測仍照樣跑在 agent 訊息上,只有那一輪的 R9 豁免
159
+ 可能漏掉。
160
+
161
+ Cursor 已評估但不支援:截至撰寫本文時,Cursor 的 stop hook 能不能真的
162
+ 擋下一個回合仍未確定,若對著一個沒人驗證過的契約出一份轉接層,
163
+ 等於重演 R3 要防的那個失敗——一個沒人確認過真的在執法的執法機制。
164
+
165
+ 不在上表的任何執行環境,這個檢查都是失效的——與語言不支援(R8)同一種
166
+ 「預設沉默」失敗。`uds init --with-hooks` 會回報它把 hook 接進了哪些
167
+ 執行環境;它不會在這裡窮舉其餘的,因為那份清單是一張等著在下一個
168
+ 執行環境被加入或移除時就過期的引用。
169
+
170
+ ---
171
+
144
172
  ## 偵測器比對什麼
145
173
 
146
174
  形狀是:**第一人稱未來標記,接一個動作動詞,在同一個句子裡**,再減掉三個排除項。
@@ -188,3 +216,5 @@ agent 寫下「我接著做 X」,然後結束回合,而 X 沒有做。
188
216
  - [ ] 檢查認得出自己的攔阻訊息,不把它讀成人說的話
189
217
  - [ ] 檢查認得出 R2 定義的逐項卡點結束,而且不擋它
190
218
  - [ ] 歸屬詞的搜尋排除檢查自己的標題與結構
219
+ - [ ] 每個支援的執行環境的阻擋契約都對照該環境自己的官方文件驗證過,不是照抄另一個環境
220
+ - [ ] 安裝器只為採用者實際選擇的執行環境寫入該環境的 hook 設定
@@ -1,6 +1,6 @@
1
1
  # UDS 速查表
2
2
 
3
- > Quick reference for all UDS features | Last updated: 2026-09-18
3
+ > Quick reference for all UDS features | Last updated: 2026-09-23
4
4
 
5
5
  **Language**: [English](../../../docs/user/CHEATSHEET.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CHEATSHEET.md)
6
6
 
@@ -260,6 +260,7 @@
260
260
  | `mutation-testing` | Mutation testing evaluates test suite effectivenes |
261
261
  | `no-cicd-deployment` | No-CI/CD Deployment Strategy |
262
262
  | `observability-standards` | Observability Standards |
263
+ | `open-work-tracking` | The deferred-item-exit standard requires that a de |
263
264
  | `packaging-standards` | This standard defines a Recipe-based packaging fra |
264
265
  | `performance-standards` | This standard defines comprehensive guidelines for |
265
266
  | `pii-classification` | PII Classification and Handling Standards |
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../docs/CLI-INIT-OPTIONS.md
3
- source_version: 3.5.2
4
- translation_version: 3.5.2
5
- last_synced: 2026-09-18
3
+ source_version: 3.6.0
4
+ translation_version: 3.6.0
5
+ last_synced: 2026-09-25
6
6
  status: current
7
7
  ---
8
8
 
@@ -10,8 +10,8 @@ status: current
10
10
 
11
11
  > **語言**: [English](../../../docs/CLI-INIT-OPTIONS.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CLI-INIT-OPTIONS.md)
12
12
  >
13
- > **版本**: 3.5.2
14
- > **最後更新**: 2026-09-18
13
+ > **版本**: 3.6.0
14
+ > **最後更新**: 2026-09-25
15
15
 
16
16
  本文件詳細說明 `uds init` 命令的每一個選項,包含使用情境、影響範圍和建議選擇。
17
17
 
@@ -838,6 +838,25 @@ uds init --experimental
838
838
  | Claude Code 目標檔 | `--claude-target` | Claude Code 整合內容要寫到哪裡:`project`(`CLAUDE.md`,預設)或 `local`(`CLAUDE.local.md`) |
839
839
  | 模式(已棄用) | `-m, --mode` | 安裝模式(skills, full)- 請改用 `--skills-location` |
840
840
 
841
+ ### Claude Code 以外的強制執行 Hooks
842
+
843
+ `--with-hooks` 一定會安裝進 `.claude/settings.json`。四個有 hook 支援的標準
844
+ 之一——`turn-completion-integrity`(見 CHANGELOG,Unreleased)——也會裝進
845
+ **Codex** 與 **Gemini CLI**,門檻是你有沒有在 [AI 工具選擇](#1-ai-工具選擇)
846
+ 裡選了那個工具(或用非互動模式的工具旗標帶入):
847
+
848
+ | 工具 | 寫入的設定檔 | 觸發條件 |
849
+ |------|-------------|---------|
850
+ | Codex | `.codex/hooks.json` | 選了 **OpenAI Codex** |
851
+ | Gemini CLI | `.gemini/settings.json` | 選了 **Gemini CLI** |
852
+
853
+ 沒選的工具不會寫入任何東西——`uds init` 不會在沒用到 Codex 或 Gemini CLI
854
+ 的專案裡建立 `.codex/` 或 `.gemini/` 目錄。其餘三個有 hook 支援的標準
855
+ (commit message 驗證、logging、security)目前仍只支援 Claude Code;
856
+ 為什麼目前只推廣 turn-completion-integrity,以及 Cursor 的現況
857
+ (已評估、不支援),見
858
+ [支援的執行環境](../../../core/turn-completion-integrity.md#supported-harnesses)。
859
+
841
860
  ### Claude Code 整合目標檔(`--claude-target`)
842
861
 
843
862
  UDS 預設把 Claude Code 內容寫進 `CLAUDE.md`——團隊共用、會進版控的那個檔案。