universal-dev-standards 6.13.1 → 6.14.0-beta.2

package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md

@@ -1,7 +1,7 @@
 # UDS 功能参考手册
 
 > Universal Development Standards - 完整功能文档
-> Auto-generated | Last updated: 2026-09-23
+> Auto-generated | Last updated: 2026-09-29
 
 **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | [繁體中文](../../zh-TW/docs/FEATURE-REFERENCE.md) | 简体中文
 
@@ -9,15 +9,15 @@
 
 ## 目录
 
-1. [CLI 指令](#cli-commands) (23)
+1. [CLI 指令](#cli-commands) (24)
 2. [斜线命令](#slash-commands) (51)
 3. [技能](#skills) (55)
 4. [代理](#agents) (5)
 5. [工作流程](#workflows) (5)
 6. [核心规范](#core-standards) (153)
-7. [脚本](#scripts) (59)
+7. [脚本](#scripts) (63)
 
-**Total Features: 351**
+**Total Features: 356**
 
 ---
 
@@ -158,6 +158,8 @@
 | `--rollback` | Rollback to the most recent backup |
 | `--claude-target` | Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall |
 | `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
+| `--with-hooks` | Install the enforcement hooks that are missing from this already-initialized project (re-detects tools; hooks already there and your own hooks are not touched; with --plan, writes nothing; --force also overwrites edited hook scripts) |
+| `--ai-tool` | With --with-hooks: comma-separated tools to install hooks for (claude-code, codex, gemini-cli, antigravity) instead of detecting them |
 
 ### `uds skills`
 
@@ -276,6 +278,10 @@
 
 **说明**: MCP server commands for AI tool integration
 
+### `uds open-work`
+
+**说明**: Reference checks for open-work-tracking (OWT-017/018/019). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass)
+
 ### `uds run`
 
 **说明**: Run a project command by intent (test/lint/build/security) via uds.project.yaml
@@ -478,7 +484,7 @@
 | `deployment-standards` | 1.1.0 | This standard defines guidelines for safely deploying software to production, co |
 | `deprecation-standards` | 1.1.0 |  |
 | `design-document-standards` | 1.0.0 |  |
-| `developer-memory` | 1.1.1 | This standard defines a structured system for capturing, retrieving, and surfaci |
+| `developer-memory` | 1.2.0 | This standard defines a structured system for capturing, retrieving, and surfaci |
 | `disaster-recovery-drill` | - |  |
 | `documentation-lifecycle` | 1.0.0 | This standard defines **when** to update documentation, **when** to check it, an |
 | `documentation-structure` | 1.5.0 | This standard defines a consistent documentation structure for software projects |
@@ -516,7 +522,7 @@
 | `mutation-testing` | 1.1.0 | Mutation testing evaluates test suite effectiveness by injecting artificial bugs |
 | `no-cicd-deployment` | - |  |
 | `observability-standards` | 1.0.0 |  |
-| `open-work-tracking` | 1.0.0 | The deferred-item-exit standard requires that a deferred item leave its document |
+| `open-work-tracking` | 1.1.0 | The deferred-item-exit standard requires that a deferred item leave its document |
 | `packaging-standards` | 1.1.0 | This standard defines a Recipe-based packaging framework that enables user proje |
 | `performance-standards` | 1.2.0 | This standard defines comprehensive guidelines for software performance engineer |
 | `pii-classification` | 1.1.0 | **Status**: Active | **Updated**: 2026-06-19 |  |
@@ -574,7 +580,7 @@
 | `timeout-standards` | - |  |
 | `token-budget` | - |  |
 | `translation-lifecycle-standards` | 1.0.1 | Translation lifecycle standards: MISSING vs OUTDATED distinction, semver-aware s |
-| `turn-completion-integrity` | 1.3.0 | An agent writes *"I'll do X next"* and then ends the turn without doing X. |
+| `turn-completion-integrity` | 1.5.0 | An agent writes *"I'll do X next"* and then ends the turn without doing X. |
 | `user-journey-testing` | - |  |
 | `user-story-mapping` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 |  |
 | `verification-evidence` | 1.3.0 | Establish an "Iron Law" that no task can be claimed as complete without verifica |
@@ -610,8 +616,11 @@
 | `check-docs-sync.sh` | Documentation Sync Checker |
 | `check-error-exit.mjs` | 🔴 沒填就是沒設定，而沒設定會 exit 2， |
 | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ-5, AC-7) |
+| `check-home-untouched.mjs` | check-home-untouched — did this run write anywhere UDS writes under HOME? |
+| `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 / OWT-018 / OWT-019 — repo entry point. |
 | `check-orphan-specs.ps1` | Check Orphan Specs |
 | `check-orphan-specs.sh` | Orphan Spec Detection Script |
+| `check-prompt-footprint.mjs` | Prompt Footprint Ratchet — DEC-117 D2/L2 |
 | `check-scope-sync.ps1` | Check Scope Sync |
 | `check-scope-sync.sh` | Scope Consistency Check Script |
 | `check-skill-next-steps-sync.ps1` | Check Skill Next Steps Sync |
@@ -625,6 +634,7 @@
 | `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-upgrade-fidelity.sh` | Upgrade Fidelity Checker |
 | `check-usage-docs-sync.ps1` | Check if usage documentation needs to be regenerated |
 | `check-usage-docs-sync.sh` | check-usage-docs-sync.sh |
 | `check-version-sync.ps1` | Check Version Sync |

package/bundled/locales/zh-TW/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.13.1
-translation_version: 6.13.1
-last_synced: 2026-09-28
+source_version: 6.14.0-beta.2
+translation_version: 6.14.0-beta.2
+last_synced: 2026-09-30
 status: current
 ---
 
@@ -17,6 +17,36 @@ status: current
 
 ## [Unreleased]
 
+## [6.14.0-beta.2] - 2026-09-30
+
+> **測試版**——以 `npm install -g universal-dev-standards@beta` 安裝。要測什麼、如何退回正式版：[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
+>
+> **修正 6.14.0-beta.1 的已知限制：**既有專案現在可以用 `uds update --with-hooks` 補裝 Antigravity CLI 關卡（以及缺少的 Claude Code / Codex / Gemini CLI 關卡）。
+
+### Added
+
+- **`uds open-work next-action | revision | separation | self-test` —— `open-work-tracking` 1.1.0 的參考檢查（OWT-017/018/019）現在隨 npm 安裝包出貨。** 6.14.0-beta.1 的這些檢查只在 repo 的 `scripts/` 裡，而 npm 安裝包不含該目錄，採用者不 clone UDS 就跑不了。規則現在只住在一個地方，`cli/src/utils/open-work-tracking.mjs`（在安裝包內）；`uds open-work` 與舊的 `node scripts/check-open-work-tracking.mjs`（現在是一個不含規則、只重新匯出該模組的薄殼）跑的是同一份，並有測試要求兩者輸出完全相同。檢查本身沒有任何改變：結束碼相同（0 沒有違反、1 有違反、2 判定不了——2 不是通過），檢查器仍先跑自己的自測臂，每次執行仍聲明涵蓋率未知（OWT-011）、詞彙未校準（OWT-016）。它仍是作為證據提供的參考判定程序，不是閘門。**每次測試都觀察到會紅：**新測試複製 CLI，讓指令吞掉結束碼（永遠 0）或讓共用規則永遠通過，並要求違反的樣本對副本變綠；並斷言 `npm pack --dry-run` 的清單包含該模組。標準的「什麼在執行本標準」一節改為指向該指令，而不是只在 repo 裡的路徑。
+
+- **`uds update --with-hooks`——為已初始化的專案補裝強制執行 hooks，並放寬 Antigravity 的偵測規則。** Hooks 過去只有 `uds init --with-hooks` 會接線，而 `uds init` 不能跑第二次，所以既有採用者永遠拿不到 UDS 在他們初始化之後才開始支援的工具的 hook（這是把 6.14.0-beta.1 安裝包裝進全新專案時發現的，已記為那一版的已知限制）。`uds update --with-hooks` 會重新偵測工具（manifest 裡的工具，加上專案檔案現在看得出來的）並補裝缺少的 hooks；`--ai-tool <清單>`（`claude-code`、`codex`、`gemini-cli`、`antigravity`）可改為直接指定，找不到任何工具時它會說明如何指定並以 1 結束，而不是猜。已經裝好的 hook 不會被重寫（重跑一次不會有任何變化），採用者自己的 hooks 絕不會被移除或重排（Claude／Codex／Gemini 是合併進去；agy 的 `.agents/hooks.json` 只寫在 UDS 自己的 `uds-turn-completion-integrity` 鍵底下，不是合法 JSON 的檔案原樣保留），採用者改過的 hook 腳本會被保留、除非加 `--force`，`--plan` 則什麼都不寫。它與 `--claude-target`、`--sync-refs` 一樣是獨立模式；在已初始化的專案執行 `uds init --with-hooks`，現在會指向它，而不是默默什麼都沒做。**Antigravity 偵測：**原本要求 `.agents/AGENTS.md`，而一個專案可以長期使用 agy 卻從不建立這個檔。現在也接受 `.agents/rules/`、`.agents/workflows/`、`.agents/plugins/` 與 `.agents/hooks.json`——這些是 agy 自己的執行檔帶著、且 antigravity.google 有文件記載的名稱——並且刻意**不**把 `.agents/skills/` 算進去，因為 Codex 也讀它（根目錄 `AGENTS.md` 加 `.agents/skills/` 的 repo 仍是 Codex；有測試）。偵測只看專案目錄：agy 記錄已開啟專案的 `~/.gemini/projects.json` 有被考慮，但因為它是機器本地的而不採用。`.agents/hooks.json` 是標記，但它同時也是 UDS 自己寫的檔，所以安裝之後它證明的是「裝過」，不是「採用者在用 agy」。**每次測試都觀察到會紅：**測試把真的 CLI 當子行程對一個已初始化的專案跑，並要求把補裝拿掉的 CLI 複本——刪掉該分支、一個回報成功卻什麼都沒寫的安裝器、偵測退回只看 `.agents/AGENTS.md`——對真 CLI 會通過的同一組斷言失敗。agy 關卡仍然只驗證過 `agy -p` 模式下沒有用工具的單一回合。
+
+### Fixed
+
+- **`turn-completion-integrity` 在使用者的前提子句超過固定字數時，會把「正在等使用者」的一輪擋下——自 6.13 起就存在。** 條件式承諾（「你選好後，我會套用」）的豁免，在英文語言包是 `you` 到逗號之間最多 20 個字元，在 zh-TW 語言包是 `你` 到 `後` 之間 1–6 個字；兩個數字都是憑感覺訂的。以已發佈的 6.14.0-beta.1、真實的 Claude Code Stop hook 輸入實測：「Once you choose A, I will apply it.」放行，「Once you choose option A or B, I will apply it.」（21 個字元）被擋，「After you choose option A or B, I will apply it.」同樣被擋——決定結果的是子句長度，不是 `once`／`after`。此 hook 只看一輪的**最後**一則訊息，所以採用者看到的是：代理明明已經正確地停下來問人，卻被逼著繼續講話。修正：豁免改為延伸到子句邊界（逗號、句末標點或換行），不再是字數，因此「Once you've reviewed the three options above and picked one, I will apply it.」與「你看完上面三個選項並選好一個之後，我會接著套用。」都放行。放寬上限就是讓真承諾漏過的方向，所以改用兩道規則取代字數：英文的子句內不得含有我自己的承諾（「After you merged it I will follow up, I will push the tag.」仍被擋）；zh-TW 的 `你` 必須是子句的開頭、且不能是「你的」（「我看了你的設定檔並判斷需要重構之後，我會接著改。」仍被擋——那裡的 `你` 是我自己那句話裡的所有格）。「I will apply it once the build finishes.」不是在等使用者，仍被擋。**每次測試都觀察到會紅：**新測試複製 hook 目錄、把兩個舊上限各自放回去，要求同樣那幾句話對複本重新被擋（且 `--self-test` 失敗）。**已知限制，沒有改變：**豁免以段落為單位，含有一個這種條件子句的段落，會連帶豁免旁邊不相干的無條件承諾（原本就如此）；沒有逗號的條件句（「After you merged it I will follow up」）仍會被擋。
+
+- **執行 `scripts/pre-release-check.sh`——以及在這個 repo 裡 `git commit`——會把 UDS 技能寫進執行者真實的家目錄。** 2026-09-29，維護者在自己的機器上跑發版前檢查，54 個技能資料夾與一個 `.manifest.json` 被寫進真實的 `~/.claude/skills/`。使用者層技能會遮蔽專案層技能，於是一個使用繁中技能的專案靜默地跑起英文測試版。每一步都是綠的：做這件事的那些步驟是在 `mkdtemp` 目錄裡跑 CLI，而那隔離的是**專案**，不是**使用者**——`uds init -y` 與 `uds update` 不論在哪裡跑，都會寫使用者層檔案（`~/.claude/skills`、`~/.uds`）。用拋棄式 `HOME` 重現並實測，不是推測：`scripts/check-upgrade-fidelity.sh` 寫入 115 個檔案（它的 `uds update` 與前一版的 `npx … init` 都繼承了真實 `HOME`）；一開始被懷疑的 `check-adopter-instruction-files.ts` 什麼也沒寫。另外兩處寫入者是逐檔二分單元測試找到的：`tests/commands/update-language-fidelity.test.js` 與 `update-agents-md-generator-fidelity.test.js` 呼叫真的 `updateCommand`（115 個檔案進 `~/.claude/skills`），`tests/commands/check.test.js` 寫了 `~/.uds/update-check.json`——而 pre-commit hook 會跑單元測試，所以**這個 repo 的每一次 commit 都會這樣**；修正者自己在修正落地前的下一次 commit 就又對真實家目錄做了一次。修正分三層：每一支會跑 CLI 的腳本現在都在拋棄式 `HOME` 下跑，且統一出自 `scripts/lib/isolated-home.{mjs,sh}`（`HOME`、`USERPROFILE`、`XDG_*`、`APPDATA`、`CODEX_HOME`；變數清單只有一份，bash 端執行 mjs 來讀它），涵蓋 `pre-release-check.sh` 的自我採用步驟、`check-upgrade-fidelity.sh`、`check-prompt-footprint.mjs`、`check-adopter-instruction-files.ts`、`check-skills-install-paths.ts`、`generate-usage-docs.mjs`、`cli/scripts/check-command-existence.mjs`、`cli/scripts/test-upgrade-path.mjs` 與 `cli/scripts/test-refactoring.sh`；測試套件在 `cli/tests/setup.js` 為每個測試檔換掉 `HOME`；`pre-release-check.sh` 開始前先對 `HOME` 底下 UDS 會寫的位置拍快照，結束時若有任何新增或修改就在摘要失敗（`scripts/check-home-untouched.mjs`）。被監看的位置不是手列的：從安裝器的路徑表與 `cli/src` 裡以 `homedir()` 為根的路徑走訪得出，並印出數量，所以縮成空集合的守衛不可能通過。**每次測試都觀察到會紅，且是端到端：**不隔離地對一個代表真實家目錄的目錄跑 CLI，守衛 exit 1 並點名 `~/.claude/skills`；有隔離則 exit 0；一支測試走訪每一支會 spawn CLI 的腳本，某個呼叫點的隔離被拿掉就紅；一支探針測試在沒有 `tests/setup.js` 時會失敗。**如果你在這個修正之前跑過 `pre-release-check.sh`，或在這個 repo 裡 commit 過，**請檢查 `~/.claude/skills/`：若有 `installedDate` 是當天的 `.manifest.json` 與旁邊的 UDS 技能資料夾，而那不是你自己裝的，就移除它們（使用者層技能會遮蔽專案層）。**刻意不監看：**`~/.claude/skills/synced/`——Claude Code 自己在執行時會把帳號的 claude.ai 技能同步進去（在真實家目錄上的第一次完整執行就因它失敗，寫入者正是執行檢查的那個 Claude Code 工作階段）；它是守衛排除清單裡唯一一項、附有理由，每次比對都會印出，且排除被拿掉或放寬成整個 `~/.claude/skills` 時測試會失敗。**未涵蓋：**沒有任何安裝器點名的路徑上的寫入；以及端到端（`tests/e2e`）測試——已逐檔二分過，沒有寫入。
+
+## [6.14.0-beta.1] - 2026-09-29
+
+> **測試版**——以 `npm install -g universal-dev-standards@beta` 安裝。要測什麼、如何退回正式版：[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
+>
+> **已知限制（2026-09-29 把安裝包裝進全新專案實測發現）：** Antigravity CLI 的關卡**只有**在「**全新**專案、且已經有 `.agents/AGENTS.md`」時，由 `uds init --with-hooks` 裝上（init 靠這個檔案判斷專案在用 Antigravity）。既有專案執行 `uds update` **不會**補裝，而 `uds init` 不能對同一個專案跑第二次。因此這個測試版裡，既有專案拿不到 agy 關卡；預計下一版修正。
+
+### Added
+
+- **`open-work-tracking` 1.1.0：在 OWT-016 之後新增三條要求——意圖與進度分開存放、意圖被修改要留痕、下一步要點名對象。** OWT-017（warning）：承載一件工作之目標、驗收條件或限制的載體，不同時承載它的進度或下一步，以走訪各載體的結構判定、絕不看檔名，所以更新進度不必碰目標。OWT-018（error）：對該意圖的每次修改都留下改了什麼、誰核可、為什麼的紀錄；沒有核可者的修改在 OWT-007 交回點被列出、不得靜默，且列出永不阻斷（OWT-008）。OWT-019（warning）：「下一步」欄位點名檔案路徑、測試名稱、指令或需求編號之一，只有動詞不算；這個檢查判斷有沒有點名對象，不判斷句子寫得好不好。嚴重度的理由寫在標準裡。標準也記下對促成本次修改之提示詞刻意**不**採納的部分——那是使用者轉貼、作者不明、沒有實作的文字，只借了設計形狀：以手寫狀態檔當狀態真相（會過期，而戳比過期內容新是隱形的）、固定的開工儀式（由各代理工具設定，且會變成沒有任何 artefact 檢查判定得了的要求）。新增 `scripts/check-open-work-tracking.mjs`，是這三條要求的參考判定程序，作為 OWT-015 證據而非閘門提供（UDS 仍不設閘門，也沒有接進 `pre-release-check.sh`）：`next-action` 回報「點名且已找到／點名但未找到／未點名」，`revision` 比對兩個版本（或一個檔案對 `--base <git rev>`）的驗收／目標／限制區段並要求一筆新增且完整的紀錄、把沒有核可者的修改列給交回點，`separation` 檢查沒有任何載體同時裝著兩者。它判定前先跑自己的自測臂、判定不了時 exit 2（不是 0），並寫明自己判定不了的事——紀錄是否誠實描述了修改、被點名的對象是否正確。**每次跑測試都被觀察到會紅：**測試套件複製該腳本、改它的原始碼文字，要求對真腳本通過的斷言對 17 個突變版失敗（每條要求的永遠通過與永遠失敗、每個辨認分支逐一關掉、舊紀錄被當成新紀錄、不完整的紀錄被接受）。**未校準（OWT-016）：標題詞彙、指令清單、副檔名清單與編號樣式都是初始判斷，不是量測**——例如 `已知限制` 會被讀成限制區段；採用者應傳入自己的編號樣式。在真實歷史上重放，它回報 XSPEC-436 的驗收條件有變動而沒有修訂紀錄，以及 dev-platform 工作紀錄裡一筆未點名的下一步。
+
+- **`turn-completion-integrity` 1.5.0：Antigravity CLI（`agy`）現已支援，依據是真實工作階段觀察到的契約。** 這份標準過去寫 agy「尚未支援」，因為它的 Stop hook 契約還沒被觀察過（R3：不對未經觀察的契約出適配層）。2026-09-29 已觀察（agy 1.2.12、`agy -p`、單輪、無工具呼叫），適配層 `scripts/hooks/check-turn-completion-agy.mjs` 建立在那次實跑的產出上，而不只是文件：hook 傳入資料只有 `transcriptPath`，所以最後一則回覆取最後一筆 `MODEL`/`PLANNER_RESPONSE`，人的訊息取最後一筆 `USER_EXPLICIT`/`USER_INPUT`（從 `<USER_REQUEST>` 內取出，後面的系統區塊丟掉）。`SYSTEM_MESSAGE` 紀錄絕不當成人說的話——agy 會把這個 hook 自己的 `continue` 理由寫回成這種紀錄，讀成人的話會讓 R9 叫停豁免失效。攔截是 `{"decision":"continue","reason":...}`，放行是 `{}`，所有失敗路徑都放行。`uds init --with-hooks` 在選了 Google Antigravity 時寫入 `.agents/hooks.json`（遇到無法解析的 `hooks.json` 不覆蓋），`uds uninstall` 只移除 UDS 自己的 handler、保留使用者其他 hook。**已驗證範圍：單輪、無工具呼叫、`agy -p`。未驗證：多輪、含工具呼叫的回合、互動模式、`fullyIdle: false`、`error` 非空、`.agents/hooks.json` 是否需要已登記的 Antigravity 專案、以及工作目錄是否永遠是 `.agents/`**——標準、適配層與安裝輸出都寫明了這一點。**同日實測：agy 執行 hook 時的工作目錄是 `.agents/`（不是專案根目錄），且對啟動失敗的 hook 靜默放行，所以安裝的指令是 `node ../scripts/hooks/check-turn-completion-agy.mjs`。**
+
 ## [6.13.1] - 2026-09-28
 
 > **修補版**：修正 6.13.0 暴露的兩個「以 `uds update` 升級既有專案」的缺陷（繁中的提交訊息語言段落變成英文；AGENTS.md 被改寫成另一種格式且少了「這是索引」提醒），並新增一道發版前檢查，實際從上一個正式版升級一次。**若你已用 `uds update` 升到 6.13.0，請在升級至 6.13.1 後再執行一次 `uds update`**，以還原那些段落。

package/bundled/locales/zh-TW/README.md

@@ -15,7 +15,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 6.13.1 | **發布日期**: 2026-09-28 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.14.0-beta.2 (Pre-release) | **發布日期**: 2026-09-30 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
 
 語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流，確保不同技術堆疊之間的一致性、品質和可維護性。
 
@@ -79,7 +79,7 @@ npx universal-dev-standards init
 | **核心標準** | 153 | 通用開發準則 |
 | **AI Skills** | 55 | 互動式技能 |
 | **斜線命令** | 51 | 快速操作 |
-| **CLI 指令** | 23 | 專案設定與維護 |
+| **CLI 指令** | 24 | 專案設定與維護 |
 <!-- UDS_STATS_TABLE_END -->
 
 > **5.0 新功能？** 請參閱[預發布說明](../../docs/PRE-RELEASE.md)了解新功能詳情。

package/bundled/locales/zh-TW/SECURITY.md

@@ -13,6 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支援狀態 |
 |------|--------|
+| 6.14.0-beta.2 | ✅ 預發布版本 |
 | 6.13.1 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已終止支援 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->

package/bundled/locales/zh-TW/core/open-work-tracking.md

@@ -1,9 +1,9 @@
 ---
 source: ../../../core/open-work-tracking.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-09-23
-source_hash: 8382d3f518a9
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-09-29
+source_hash: 0fcf3df23e12
 status: current
 ---
 
@@ -11,8 +11,8 @@ status: current
 
 > **Language**: [English](../../../core/open-work-tracking.md) | 繁體中文
 
-**版本**: 1.0.0
-**最後更新**: 2026-09-23
+**版本**: 1.1.0
+**最後更新**: 2026-09-29
 **適用**: 任何跨越一個以上工作階段承載工作、有可能在階段之間遺失項目的專案
 **範圍**: universal
 
@@ -34,7 +34,8 @@ status: current
 | 某項目因等待別的事件而暫停 | 「等待中」若沒有記錄解除條件，與「被忘記」無法分辨 | 與等待一起記錄的解除條件 |
 | 已規劃的項目還沒動工，時間過去 | 沒有時鐘的項目會無聲腐爛——沒有東西會再指向它 | 一個門檻，或一次被迫的定期檢視，讓它重新浮現 |
 
-下面每一條要求都對應這張表的一列，或對應本標準設計當天觀察到的四個失效之一
+下面每一條要求都對應這張表的一列、對應本標準設計當天觀察到的四個失效之一，
+或（OWT-017–OWT-019）對應 1.1.0 補上的兩個缺口
 （見〈[證據與校準](#證據與校準)〉）。**沒有任何一個機制被規定**——
 理由與 [deferred-item-exit](deferred-item-exit.md) 對自己出口的約束相同（DEC-049：
 UDS 定義必須成立的關係，維持它的機制由採用層選擇）。
@@ -56,6 +57,7 @@ UDS 定義**活動**，採用層負責**編排**（DEC-049）。一份寫成工
 | 「這是最新的」這句宣稱必須從什麼可被證明 | 具體用哪個雜湊函式、diff 工具或 CI 供應商 |
 | 一個回報數字與它看不到的部分之間的關係 | 儀表板版面或報告範本 |
 | 控制權交回人的那一點存在一個確認點，且它永不阻斷 | 用什麼 hook 系統、shell 或 cron 實作它 |
+| 一次目標的修改與說明它的修訂紀錄之間必須存在的關係 | 哪一種版本控制系統、核可工具或檔案配置承載其中任何一個 |
 
 **直說它的後果**：本標準**不附帶任何閘門**。它只說一個承載開放工作的地方必須具備什麼性質；
 有沒有東西在檢查，是採用專案的決定——[OWT-014](#要求) 與 [OWT-015](#要求)
@@ -67,7 +69,9 @@ UDS 定義**活動**，採用層負責**編排**（DEC-049）。一份寫成工
 
 **一個承載開放工作的地方，必須：（1）不要求分類就能收下新項目、（2）為每一個標為等待中的項目記下解除條件、
 （3）對任何有可靠來源可推導的欄位改用生成、（4）回報還剩什麼時同時揭露看不到什麼、
-（5）在控制權從 agent 交回人的那一刻被檢視——而且那個檢視不能讓回合失敗。**
+（5）在控制權從 agent 交回人的那一刻被檢視——而且那個檢視不能讓回合失敗、
+（6）把「這份工作為了什麼」與「做到哪了」分開存放，並替前者的每一次修改留下交代、
+（7）讓每一個「下一步」都點名一個讀的人找得到的東西。**
 
 ---
 
@@ -91,6 +95,9 @@ UDS 定義**活動**，採用層負責**編排**（DEC-049）。一份寫成工
 | **OWT-014** | 本標準的每一條要求都可表述為 artefact 之間可判定的關係。不能如此表述的要求不得進入本標準 | error |
 | **OWT-015** | 被提出作為本標準任一要求之證據的檢查，已被觀察到對一個刻意違反該要求的樣本回報失敗。從未紅過的檢查不是可採信的證據 | error |
 | **OWT-016** | 本標準各要求所引用的任何窗口或閾值，載明來歷，或標為未校準 | warning |
+| **OWT-017** | 承載一件工作之目標、驗收條件或限制的載體，不同時承載它的進度或下一步，反之亦然。以走訪各載體的結構欄位（小節、欄位、型別化標記）判定，絕不看檔名。更新進度因此不需要碰目標 | warning |
+| **OWT-018** | 對一件工作的目標、驗收條件或限制的每一次修改，都留下載明改了什麼、誰核可、為什麼的修訂紀錄。沒有核可者的修改，在控制權交回人時被列出（OWT-007），不得靜默 | error |
+| **OWT-019** | 「下一步」欄位至少點名一個具體對象：檔案路徑、測試名稱、指令或需求編號之一。只有動詞（「繼續」「處理剩下的」）不算。它判斷有沒有點名對象，絕不判斷句子措辭好壞 | warning |
 
 ---
 
@@ -173,6 +180,61 @@ UDS 定義**活動**，採用層負責**編排**（DEC-049）。一份寫成工
 
 ---
 
+## 意圖與進度是兩種不同的事實
+
+**意圖**——目標、驗收條件、限制——說的是「完成」是什麼意思。它很少改，而且只在有人決定要改時才改。
+**進度**——做到哪、還剩什麼、下一步、卡在哪——每個工作階段都在變，由做事的 agent 來寫。
+兩者住在同一個載體時，每一次例行的進度更新，都是在編輯那份定義「完成」的文件本身，
+而「定義被改了」在審查裡、在 diff 裡，都與日常記帳分不出來。**OWT-017** 把它們分開。
+形式不限：規格檔搭配工作紀錄、或目標／狀態兩個檔，都符合。**判準是結構，不是檔名**——
+走訪每個載體的小節、欄位與型別化標記，問同一個載體是否同時裝著兩種東西。
+
+**OWT-018** 點名的，是光靠分開存放防不了的失效：工作進行到一半，某條驗收條件被改了，
+而沒有任何紀錄說明誰同意過。事後「每一條驗收都滿足了」依然為真——只是針對另一組條件。
+它與「新戳蓋在舊內容上」是同一個形狀：被改過的目標，讀起來與一個一直這麼寫的目標一模一樣。
+所以每一次對意圖的修改，都要留下**改了什麼、誰核可、為什麼**的紀錄。沒有核可者的修改並不被禁止——
+agent 正當地會提出修改，禁止只會教它學會靜默地改——但它要在**控制權交回人的那一刻被列出來**（OWT-007）。
+如同掛在那個事件上的一切，列出只是回報，永不阻斷（OWT-008）。這裡檢查能判定的就只有可判定的部分：
+意圖有沒有變、有沒有新增一筆紀錄、那筆紀錄是否完整、核可者欄位有沒有填。
+**它判定不了那筆紀錄是否誠實描述了這次修改**——那是關於語意的宣稱，不是 artefact 之間的關係（OWT-014），
+本標準不假裝它做得到。
+
+**這些嚴重度的理由。** OWT-018 是 `error`，因為這個失效是靜默的，而它只有一個時刻能被抓到——修改發生的那一刻；
+事後所有人能讀到的，就只剩被改過的文字。OWT-017 是 `warning`，因為分開存放只是手段：
+分開了卻沒有修訂紀錄（OWT-018）照樣漏，單一載體配上嚴格的修訂紀錄照樣達成 OWT-018 的目的，
+所以違反的傷害是間接的。OWT-019 是 `warning`，因為「有點名對象」的結構檢查必然粗糙——
+被點名的對象仍可能無關——而違反的代價是下一個工作階段的時間，不是工作本身。
+
+---
+
+## 一個什麼都沒點名的下一步，只是一種心情
+
+「繼續實作」與「處理剩下的」，與一個被遺忘的項目分不出來：下一個工作階段沒有起點可以開始，
+得重新推導工作停在哪——而那正是本標準整個存在要避免的成本。**OWT-019** 要求「下一步」欄位
+至少點名一個讀的人找得到的對象——檔案路徑、測試名稱、指令、或需求編號。
+它是**結構**判準（有沒有點名對象），不是措辭好壞的判斷；措辭漂亮但什麼都沒點名的句子照樣不過，
+簡短但點了一個測試名稱的句子照樣過。這讓它留在 OWT-010 與 OWT-014 的範圍之內。
+
+檢查回報三種結果，而不是一個綠燈：**點名且已找到**（對象被找到——例如路徑存在）、**點名但未找到**
+（有點名對象但找不到——當下一步就是要建立它時是正當的）、**未點名**（違反）。
+辨認「這串字是路徑、指令、測試名稱還是編號」本身是樣式比對，所以依 OWT-011 其涵蓋率明示為未知：
+認不出的格式會被回報為未點名，而乾淨的通過絕不表示「每個下一步都夠具體」。
+
+---
+
+## 本標準刻意不採納的東西
+
+上面兩項新增，起因是使用者轉貼的一份提示詞——**作者與出處不明，也沒有任何實作**。
+只借了它的設計形狀，本文不引用它的任何宣稱。它提出的其餘部分經過檢視、**沒有**採納，
+理由是機制層的，不是口味：
+
+| 不採納 | 理由（機制層） |
+|---|---|
+| 以手寫狀態檔作為狀態真相 | 手寫狀態會過期，而「戳比過期內容新」是隱形的（OWT-004、OWT-005 存在的起因）。只說「兩者不一致時以版本控制為準」，卻沒有任何機制讓該檔與版本控制對帳，就是採納一個已知會過期的來源。OWT-003 已經要求可推導的欄位改用生成 |
+| 固定的開工儀式（讀檔→查版本控制→驗證） | 交接點已被管住：回合結束有 OWT-007，另有 [turn-completion-integrity](turn-completion-integrity.md)。開工儀式要靠各代理工具自己的指示來設定；寫進這裡只會得到一條沒有任何 artefact 上的檢查判定得了的要求，而那正是 OWT-014 排除的東西 |
+
+---
+
 ## 一條無法被檢查的要求，不是這裡的要求
 
 **OWT-014** 是對本標準自身內容的約束，與 [deferred-item-exit](deferred-item-exit.md) 的
@@ -211,14 +273,20 @@ DEX-003 扮演的角色相同。上面每一條都指名了 artefact 與它們
 | 確認點擋住回合結束、理由是「還有工作沒做完」 | 每個回合都會觸發；永遠為真的閘門會被關掉，關掉之後什麼都不保護 |
 | 分類狀態只靠散文措辭判讀 | 正確到某個項目用清單沒預料到的方式寫出來為止 |
 | 項目從承載庫裡無聲消失 | 與一個弄丟它的 bug 無從分辨 |
+| 目標或驗收條件被改了，卻沒有任何「誰同意」的紀錄 | 「每一條驗收都滿足」依然為真，只是針對另一組條件；被改過的目標讀起來像一直這麼寫 |
+| 把手寫的狀態檔當成狀態真相 | 會過期，而比過期內容新的戳看不見 |
+| 下一步寫「繼續實作」或「處理剩下的」 | 沒有點名任何可以開始的東西；與被遺忘的項目無從分辨 |
 
 ---
 
 ## 什麼在執行本標準
 
-**UDS 側沒有任何東西在執行，而這件事是被記錄的，不是被暗示的。** UDS 陳述一個承載開放工作的地方
+**UDS 不對本標準設任何閘門，而這件事是被記錄的，不是被暗示的。** UDS 陳述一個承載開放工作的地方
 必須滿足的關係；有沒有東西去判定它，依上面的[寫法約束](#本標準的寫法以及為什麼這樣寫)，
 是採用專案的決定——與 [deferred-item-exit](deferred-item-exit.md) 對自己出口劃的界線相同。
+自 1.1.0 起，UDS 為 OWT-017–OWT-019 附上一支**參考判定程序**——npm 安裝包裡的 `uds open-work next-action | revision | separation`（`uds open-work self-test` 只跑檢查器自己的自測臂；在 UDS repo 的副本裡，`node scripts/check-open-work-tracking.mjs` 跑的是同一份程式）——
+作為 OWT-015 意義上的證據——它已被觀察到對違反的樣本回報失敗——供採用者直接執行或自行重做。
+它沒有接進任何 UDS 發版閘門，因為 UDS 本身沒有承載開放工作的地方可供它檢查。
 
 本標準做的事，是讓那個決定顯形：OWT-014 保證這裡每一條**能**被判定，OWT-015 固定
 「一次判定要算數需要什麼」，OWT-005／OWT-011 固定「一次不完整的判定容許印出什麼」。
@@ -238,6 +306,15 @@ DEX-003 扮演的角色相同。上面每一條都指名了 artefact 與它們
 - 依實際使用情況重新校準這兩個數字、或將其中任一個降級為專案特定指引，是採用專案自己的決定
   與自己的時程——本標準不承諾這件事，如同它不附帶閘門一樣。
 
+**1.1.0 的新增（OWT-017–OWT-019）**來自 2026-09-29 在一個採用專案裡發現的兩個缺口（DEC-122）：
+本標準對「把工作項目的目標與進度分開」沒有任何說法，而該專案某份規格裡的一條驗收條件，
+在工作進行到一半時被修改，沒有任何紀錄說明誰同意過。設計形狀借自使用者轉貼的一份提示詞，作者不明
+（見〈[本標準刻意不採納的東西](#本標準刻意不採納的東西)〉）。
+那支參考判定程序只有幾小時大、只有一位作者，跑過的是人造樣本，不是真實的修訂歷史。
+依 OWT-016，它用到的一切類似閾值的東西都是**未校準、初始判斷**：把某個小節認作意圖、進度、下一步、
+或修訂紀錄的標題詞彙；它認得的指令名清單；副檔名清單；需求編號的樣式。
+沒有任何一項對照過真實使用量測，採用專案應傳入自己的。
+
 ---
 
 ## 與其他標準的關係
@@ -253,3 +330,5 @@ DEX-003 扮演的角色相同。上面每一條都指名了 artefact 與它們
 - [verification-evidence](verification-evidence.md) — OWT-015 所依賴的 exit code
   與證據有效性推理的來源；也是 OWT-006／OWT-011 的部分涵蓋例外該被登記的地方，
   而不是揭露一次就放著。
+- OWT-018 掛在與 OWT-007 相同的交回點：沒有核可者的意圖修改，是在那裡多列出來的一項，
+  而且與列在那裡的一切相同，永不阻斷。

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

@@ -1,9 +1,9 @@
 ---
 source: ../../../core/turn-completion-integrity.md
-source_version: 1.4.1
-translation_version: 1.4.1
-last_synced: 2026-09-28
-source_hash: 0c04676006c0
+source_version: 1.5.0
+translation_version: 1.5.0
+last_synced: 2026-09-29
+source_hash: 08579653d9a4
 status: current
 ---
 
@@ -11,8 +11,8 @@ status: current
 
 > **Language**: [English](../../../core/turn-completion-integrity.md) | 繁體中文
 
-**版本**: 1.4.1
-**最後更新**: 2026-09-28
+**版本**: 1.5.0
+**最後更新**: 2026-09-29
 **適用範圍**: 任何由 agent 結束回合、把控制權交還給人的執行環境
 **Scope**: universal
 **產業標準**: 不宣稱任何來源——由實際觀察到的失敗歸納，見「證據」
@@ -144,13 +144,14 @@ agent 寫下「我接著做 X」，然後結束回合，而 X 沒有做。
 ## 支援的執行環境
 
 這個檢查只在「轉接層存在，且 hook 真的被接進該執行環境自己的設定」時才生效。
-截至 v1.4.1：
+截至 v1.5.0：
 
 | 執行環境 | 事件 | 設定檔 | 阻擋契約 |
 |---|---|---|---|
 | Claude Code | Stop | `.claude/settings.json` | stdout 印 `{"decision":"block","reason":...}`，exit 0；沉默即放行 |
 | Codex | Stop | `.codex/hooks.json` | stdout 印 `{"decision":"block","reason":...}`，exit 0——官方文件寫明這個事件純文字或空輸出無效 |
 | Gemini CLI（過時） | AfterAgent | `.gemini/settings.json` | stdout 印 `{"decision":"deny","reason":...}`，exit 0——官方文件標記為優先於 exit code 2 的做法 |
+| Antigravity CLI（`agy`） | Stop | `.agents/hooks.json` | stdout 印 `{"decision":"continue","reason":...}`，exit 0；`{}` 即放行 |
 
 在 Codex 上，接上了不等於會執行。Codex 會略過專案層級的 hook，直到專案被信任、**而且**
 這一支 hook 的定義在互動式 Codex 工作階段裡透過 `/hooks` 被信任為止；信任紀錄綁在定義的
@@ -173,12 +174,42 @@ agent 的最後一則訊息，卻不給使用者的；要拿到使用者那一
 
 Gemini CLI 已過時。Google 於 2026-06-18 對個人帳號停用 Gemini CLI，
 改由 Antigravity CLI（`agy`）取代；企業帳號兩者都還能用。這個適配層為那些使用者保留，
-但它從未在真實的 Gemini CLI 工作階段中驗證過；使用 Google 工具的新採用者該預期的是
-Antigravity CLI，而它**尚未支援**。它文件記載的 Stop hook 契約，在關鍵之處與上表每一個
-適配層都不同：hook 設定在 `.agents/hooks.json`、傳入資料只有 `transcriptPath`
-（沒有最後一則回覆、也沒有人的訊息）、攔截是 `{"decision":"continue","reason":...}`
-而不是 `block` 或 `deny`。等這份契約在真實工作階段中觀察到之後才會加入適配層——
-與下方 Cursor 沒有適配層是同一個理由。
+但它從未在真實的 Gemini CLI 工作階段中驗證過；使用 Google 工具的新採用者應使用下面的
+Antigravity CLI 適配層。
+
+Antigravity CLI 已支援，依據是真實工作階段觀察到的契約（2026-09-29，agy 1.2.12），
+而不只是它的文件。這份契約在關鍵之處與上表每一個適配層都不同：
+
+- **設定**在 `.agents/hooks.json`，以 hook 名稱為鍵——
+  `{"<名稱>": {"Stop": [{"type":"command","command":"...","timeout":N}]}}`，
+  `timeout` 單位為秒。沒有 `hooks` 外層，handler 也不巢狀在 `hooks[]` 裡。
+- **stdin 既沒有最後一則回覆、也沒有人的訊息**，只有 `transcriptPath` 與中繼資料，所以兩者
+  都要從逐字稿讀（JSONL，每筆有 `source`、`type`、`content`）。最後一則回覆是最後一筆
+  `source: MODEL`、`type: PLANNER_RESPONSE`。人的訊息是最後一筆
+  `source: USER_EXPLICIT`、`type: USER_INPUT`，取 `<USER_REQUEST>…</USER_REQUEST>` 之內的文字——
+  後面接著的系統區塊（`<ADDITIONAL_METADATA>` 等）不是人說的話。
+- **`SYSTEM_MESSAGE` 紀錄絕不可當成人的訊息讀。** agy 會把這個 hook 自己的 `continue` 理由
+  寫回逐字稿，成為這種紀錄（`source: SYSTEM`、`type: SYSTEM_MESSAGE`，內容為
+  「Stop hook blocked termination: …」）。若把「不是模型的任何紀錄」都當成人，就會把 hook
+  自己的話當成人說的，R9 豁免隨之失效——也就是 R11 的失敗，換成這份逐字稿的形狀重演。
+- **攔截是 `{"decision":"continue","reason":...}`**，不是 `block` 或 `deny`；`{}` 即放行。
+- **hook 執行時的工作目錄是 `.agents/`，不是專案根目錄**（2026-09-29 實測，agy 1.2.12）。
+  因此安裝的指令是 `node ../scripts/hooks/check-turn-completion-agy.mjs`；以專案根目錄為準的
+  `node scripts/hooks/...` 會解析成 `<專案>/.agents/scripts/hooks/...`，出現
+  「Cannot find module」，而且**agy 對執行失敗的 hook 靜默放行**——沒有任何訊息、stdout 照常，
+  回合就這樣結束。路徑刻意用相對路徑（這個檔案本來就是要提交並共用的，絕對路徑只屬於某一台機器），
+  也不用任何 shell 語法（`sh -c`、`$(...)`），因為 agy 是否經過 shell 執行 `command` 沒有證據。
+- **與 Claude Code 相反，hook 被呼叫時逐字稿已經寫到最後一則回覆。**
+
+已驗證：agy 1.2.12、非互動的 `agy -p`、**單輪且沒有工具呼叫**——hook 被呼叫時最後一則回覆
+已在逐字稿裡，`continue` 確實生效（模型又回了一輪），且沒有遇到信任提示（與 Codex 不同）。
+**未驗證**：多輪對話、含工具呼叫的回合（此時最後一筆 `PLANNER_RESPONSE` 是不是最後回覆、
+hook 執行時是否已寫入）、`fullyIdle: false`、`error` 非空、互動模式、專案層
+`.agents/hooks.json` 是否像 `.agents/skills/` 一樣只對已登記的 Antigravity 專案生效，
+以及工作目錄是否永遠是 `.agents/`（只對專案層檔案量測過；`uds init` 不會寫使用者層的
+`~/.gemini/config/hooks.json`）。在未驗證的情境下，適配層可能判斷的是
+較早的一則回覆而不是最後一則；讀取失敗時仍一律放行（R5）。`uds init --with-hooks` 會在安裝
+那一行旁邊印出已驗證的範圍。
 
 Cursor 已評估但不支援：截至撰寫本文時，Cursor 的 stop hook 能不能真的
 擋下一個回合仍未確定，若對著一個沒人驗證過的契約出一份轉接層，
@@ -240,3 +271,5 @@ Cursor 已評估但不支援：截至撰寫本文時，Cursor 的 stop hook 能
 - [ ] 歸屬詞的搜尋排除檢查自己的標題與結構
 - [ ] 每個支援的執行環境的阻擋契約都對照該環境自己的官方文件驗證過，不是照抄另一個環境
 - [ ] 安裝器只為採用者實際選擇的執行環境寫入該環境的 hook 設定
+- [ ] 逐字稿裡會出現系統代寫訊息的執行環境，只從「人的紀錄」讀人的訊息，絕不從「不是模型寫的任何東西」讀
+- [ ] 一份執行環境契約只對「真實工作階段觀察過的範圍」出貨，並註明沒觀察到的範圍

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

@@ -1,6 +1,6 @@
 # UDS 速查表
 
-> Quick reference for all UDS features | Last updated: 2026-09-23
+> Quick reference for all UDS features | Last updated: 2026-09-29
 
 **Language**: [English](../../../docs/user/CHEATSHEET.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CHEATSHEET.md)
 
@@ -32,6 +32,7 @@
 | `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 open-work` | Reference checks for open-work-tracking (OWT-017/018/019). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass) |
 | `uds run` | Run a project command by intent (test/lint/build/security) via uds.project.yaml |
 
 ## 💬 斜線命令
@@ -352,8 +353,11 @@
 | `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-home-untouched.mjs` | check-home-untouched — did this run write anywhere |
+| `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 /  |
 | `check-orphan-specs.ps1` | Check Orphan Specs |
 | `check-orphan-specs.sh` | Orphan Spec Detection Script |
+| `check-prompt-footprint.mjs` | Prompt Footprint Ratchet — DEC-117 D2/L2 |
 | `check-scope-sync.ps1` | Check Scope Sync |
 | `check-scope-sync.sh` | Scope Consistency Check Script |
 | `check-skill-next-steps-sync.ps1` | Check Skill Next Steps Sync |
@@ -367,6 +371,7 @@
 | `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-upgrade-fidelity.sh` | Upgrade Fidelity Checker |
 | `check-usage-docs-sync.ps1` | Check if usage documentation needs to be regenerat |
 | `check-usage-docs-sync.sh` | check-usage-docs-sync.sh |
 | `check-version-sync.ps1` | Check Version Sync |

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

@@ -1,8 +1,8 @@
 ---
 source: ../../../docs/CLI-INIT-OPTIONS.md
-source_version: 3.7.0
-translation_version: 3.7.0
-last_synced: 2026-09-26
+source_version: 3.7.1
+translation_version: 3.7.1
+last_synced: 2026-09-29
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: [English](../../../docs/CLI-INIT-OPTIONS.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CLI-INIT-OPTIONS.md)
 >
-> **版本**: 3.7.0
-> **最後更新**: 2026-09-26
+> **版本**: 3.7.1
+> **最後更新**: 2026-09-29
 
 本文件詳細說明 `uds init` 命令的每一個選項，包含使用情境、影響範圍和建議選擇。
 
@@ -870,21 +870,46 @@ UDS 的專案——並在 `[pre-commit]` 底下回報同樣的修復方式；此
 
 `--with-hooks` 一定會安裝進 `.claude/settings.json`。四個有 hook 支援的標準
 之一——`turn-completion-integrity`（見 CHANGELOG，Unreleased）——也會裝進
-**Codex** 與 **Gemini CLI**，門檻是你有沒有在 [AI 工具選擇](#1-ai-工具選擇)
+**Codex**、**Gemini CLI**（過時）與 **Antigravity CLI**（`agy`），門檻是你有沒有在 [AI 工具選擇](#1-ai-工具選擇)
 裡選了那個工具（或用非互動模式的工具旗標帶入）：
 
 | 工具 | 寫入的設定檔 | 觸發條件 |
 |------|-------------|---------|
 | Codex | `.codex/hooks.json` | 選了 **OpenAI Codex** |
 | Gemini CLI | `.gemini/settings.json` | 選了 **Gemini CLI** |
+| Antigravity CLI | `.agents/hooks.json` | 選了 **Google Antigravity** |
 
-沒選的工具不會寫入任何東西——`uds init` 不會在沒用到 Codex 或 Gemini CLI
-的專案裡建立 `.codex/` 或 `.gemini/` 目錄。其餘三個有 hook 支援的標準
+沒選的工具不會寫入任何東西——`uds init` 不會在沒用到 Codex、Gemini CLI 或 Antigravity
+的專案裡建立 `.codex/`、`.gemini/` 或 `.agents/` 目錄。其餘三個有 hook 支援的標準
 （commit message 驗證、logging、security）目前仍只支援 Claude Code；
 為什麼目前只推廣 turn-completion-integrity，以及 Cursor 的現況
 （已評估、不支援），見
 [支援的執行環境](../../../core/turn-completion-integrity.md#supported-harnesses)。
 
+### 為已初始化的專案補裝 Hooks（`uds update --with-hooks`）
+
+`uds init` 不能跑第二次，所以 `--with-hooks` 到不了已經初始化的專案——包括在 UDS 支援某個工具**之前**
+（或在偵測認得它之前）就初始化的專案。`uds update --with-hooks` 就是那扇門：
+
+```bash
+uds update --with-hooks --plan                   # 列出會裝什麼；不寫任何檔
+uds update --with-hooks                          # 補裝缺少的 hooks
+uds update --with-hooks --ai-tool antigravity    # 直接指定工具，不做偵測
+```
+
+- **裝給哪些工具。** `.standards/manifest.json` 裡的工具，加上專案檔案現在看得出來的（Claude Code：
+  `.claude/` 或 `CLAUDE.md`；Codex：根目錄 `AGENTS.md`；Gemini CLI：`GEMINI.md`；Antigravity：
+  `.agents/AGENTS.md`、`.agents/rules/`、`.agents/workflows/`、`.agents/plugins/` 或
+  `.agents/hooks.json`）。**`.agents/skills/` 不算 Antigravity 的標記**——Codex 也從同一個目錄讀專案技能，
+  所以它分不出是哪個工具。`--ai-tool <清單>`（`claude-code`、`codex`、`gemini-cli`、`antigravity`，
+  以逗號分隔）會取代偵測。找不到任何工具時，它會說明、印出如何指定，並以 1 結束。
+- **不會動什麼。** 已經裝好的 hook 不會被重寫。你自己的 hooks 不會被移除或重排：Claude、Codex、Gemini 的
+  項目是合併進去；Antigravity 的 `.agents/hooks.json` 只寫在 `uds-turn-completion-integrity` 這個鍵底下
+  （不是合法 JSON 的 `hooks.json` 會原樣保留並回報）。`scripts/hooks/` 裡與隨附版本不同的 hook 腳本會被保留並回報；
+  加上 `--force` 才會覆寫。
+- **它不做什麼。** 不更新標準、技能或整合檔（那是一般的 `uds update`），也不會把工具加進 manifest。
+  它不能與 `--skills`、`--commands` 等其他 update 模式合用，合用時會明說。
+
 ### Claude Code 整合目標檔（`--claude-target`）
 
 UDS 預設把 Claude Code 內容寫進 `CLAUDE.md`——團隊共用、會進版控的那個檔案。