universal-dev-standards 6.3.9 → 6.4.0

package/bin/uds.js

@@ -213,8 +213,8 @@ program
   .option('--skills', 'Install/update Skills for configured AI tools')
   .option('--commands', 'Install/update slash commands for configured AI tools')
   .option('--debug', 'Show debug output for Skills/Commands detection')
-  .option('--plan', 'Show reconciliation plan without executing (like terraform plan)')
-  .option('--apply', 'Apply exactly the plan --plan prints (plain `uds update` does not)')
+  .option('--plan', 'Show reconciliation plan without executing (like terraform plan); combines with --skills/--commands to plan just that scope, still writing nothing')
+  .option('--apply', 'Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope')
   .option('--force', 'Force update all files, ignoring hash comparison')
   .option('--rollback', 'Rollback to the most recent backup')
   .option('--locale <locale>', 'Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env')

package/bundled/ai/standards/class-level-fix.ai.yaml

@@ -0,0 +1,143 @@
+# Class-Level Fix Standard - AI Optimized
+# Source: core/class-level-fix.md
+
+standard:
+  id: class-level-fix
+  name: Class-Level Fix Standard
+  description: 類別層修正標準——修正瞄準集合，不是瞄準成員
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-08-10"
+    source: core/class-level-fix.md
+    description: >
+      一個缺陷幾乎從不孤單，它是某個集合的一員。修掉被指出的那一員，
+      集合裡其餘的原封不動，而沒有東西會通知你下一個在哪。
+      本標準要求修正瞄準集合：指出可窮舉集合，並加上一個「走訪」而非「列舉」該集合的檢查。
+
+  iron_law: >
+    修一個缺陷之前，先指出它所屬的可窮舉集合，並加上一個走訪該集合的檢查。
+    若該集合無法被走訪，寫下為什麼——沉默不算答案。
+
+  guidelines:
+    - "修正瞄準集合，不是瞄準成員"
+    - "**走訪並排除，絕不列舉**——列舉正確到有人新增第四個成員為止，而沒有東西會告訴你"
+    - "走訪必須從系統自己讀的那個來源讀（CLI 定義／目錄／manifest），**不從手打的清單讀**"
+    - "檢查要印出分母**與被排除的數量**，不是只印「全部通過」"
+    - "類別層檢查在被信任之前，先以合成成員證明它不是空跑——**逐子集做，不要整體做**"
+    - "集合無法走訪是合法答案，但要寫下理由與解除條件"
+    - "**註解描述了類別，不等於有檢查涵蓋類別**——散文不會執行"
+
+  # 依序回答，第 3 題決定這道檢查活不活得下去
+  three_questions:
+    - order: 1
+      question: "這個缺陷是哪個集合的一員？"
+      examples: ["分派鏈裡的旗標", "manifest 的條目", "agents/ 底下的目錄", "目錄樹裡的設定檔"]
+    - order: 2
+      question: "那個集合能不能被走訪而不是被列舉？"
+    - order: 3
+      question: "走訪從哪裡讀出成員？"
+      note: >
+        必須從系統自己讀的那個來源讀。從手打的清單讀，等於把同一個缺陷
+        換一個位置重新製造一次。
+
+  walk_vs_enumerate:
+    enumerate:
+      shape: "for (const x of ['a','b','c'])"
+      new_member: "靜默地不被涵蓋"
+      failure_mode: "對一部分表面回報綠燈"
+    walk_and_exclude:
+      shape: "for (const x of readAll()) if (!EXCLUDED.has(x))"
+      new_member: "**預設被涵蓋**"
+      failure_mode: "吵——而吵是看得見的"
+    why: >
+      不對稱正是重點。列舉失敗時是靜默的；排除清單失敗時是吵的，
+      因為那條排除必須由一個人寫下來，而他得說明理由。
+
+  # 一道類別層檢查在被信任之前必須先被證明非空跑
+  evidence_requirement:
+    steps:
+      - "塞一個違反規則的合成成員"
+      - "確認檢查失敗**且指名該成員**"
+      - "移除後確認回到綠燈"
+    granularity: per_subset
+    why_per_subset: >
+      一道涵蓋五份清單、卻只對第一份測過的檢查，是一道涵蓋一份清單的檢查。
+
+  output_requirement:
+    must_print: ["實際檢查的數量（分母）", "被排除的數量"]
+    rationale: >
+      只印分母不夠。「檢查了 4,012 條宣告」讀起來像涵蓋率，
+      而篩選器悄悄跳過了每一條目錄條目。
+
+  # 集合無法走訪時的合法出口
+  when_not_walkable:
+    legitimate: true
+    must_record: ["理由", "什麼條件下會改變"]
+    common_cause: >
+      成員只能相對於某個基準目錄才知道，而那個基準沒有記在任何機器讀得到的地方
+      （例如 manifest 的路徑基準只活在讀取它的程式裡）。對這種宣告做通用掃描，
+      假陽性率高到讓檢查在第一週就被關掉。
+    workable_form: >
+      逐份清冊——一種宣告一道檢查，各自知道自己的基準與條目形狀。
+      說出清冊有幾份，並確認每一份都有檢查。
+
+  anti_patterns:
+    - pattern: "修掉被回報的那一員就結案"
+      why: "集合沒有變；下一個成員會以新事故的形式抵達"
+    - pattern: "寫一段註解說明通則"
+      why: "散文不會執行"
+    - pattern: "檢查自行列舉它的範圍"
+      why: "正確到有人新增第四個成員為止"
+    - pattern: "類別層檢查只對一個成員測過"
+      why: "證明的是那一個成員，不是那個類別"
+    - pattern: "`✓ all pass` 而沒有分母"
+      why: "掃了全部與什麼都沒掃，輸出一模一樣"
+
+  rules:
+    - id: CLF-001
+      rule: "修正前必須指出缺陷所屬的可窮舉集合"
+      severity: error
+    - id: CLF-002
+      rule: "類別層檢查必須走訪集合並排除例外，不得列舉成員"
+      severity: error
+    - id: CLF-003
+      rule: "走訪的成員來源必須是系統自己讀的來源，不得是手寫清單"
+      severity: error
+    - id: CLF-004
+      rule: "檢查輸出必須包含分母與被排除的數量"
+      severity: error
+    - id: CLF-005
+      rule: "類別層檢查須以合成成員逐子集證明非空跑"
+      severity: error
+    - id: CLF-006
+      rule: "集合無法走訪時，須記錄理由與解除條件"
+      severity: warning
+
+  # 本標準自己沒有自動閘門——依它自己的規則，這件事必須寫下來而不是暗示強制力存在
+  enforcement:
+    automated_gate: false
+    why_not: >
+      沒有任何檢查能走訪「現在正在被修的所有缺陷」。套用本標準是修的當下所做的判斷。
+    enforced_by: review
+    review_question: "這是哪個集合的一員？"
+    reopen_condition: >
+      若 repo 取得「能把一次缺陷修正落地看成離散事件」的機制（有標記的 commit 型別、
+      issue↔commit 連結），即可斷言這類 commit 要嘛動到一個走訪集合的測試，
+      要嘛帶著寫下來的理由。
+    note: >
+      一份陳述了規則而沒有東西執行它的標準，正是「寫下來的風險沒有東西在執行」那個形狀。
+      不承認這一點的標準比承認的更糟，因為讀的人會以為有東西在盯。
+
+  related:
+    - id: verification-evidence
+      relation: "同一族：工具靜默失敗時，其輸出與真結果無從分辨。本標準是同一件事套用在**範圍**而非**執行**上"
+    - id: anti-hallucination
+      relation: "那個防「沒查」；這個防「查了其中一個，卻對全部下結論」"
+
+physical_spec:
+  applies_to:
+    - "任何缺陷修正（程式碼或設定）"
+  deliverables:
+    - "一道走訪集合的檢查，或一份「為何無法走訪」的紀錄"
+    - "該檢查的逐子集對照組證據"

package/bundled/core/class-level-fix.md

@@ -0,0 +1,161 @@
+# Class-Level Fix Standard
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/class-level-fix.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-08-10
+**Applicability**: Any defect fix, in code or in configuration
+**Scope**: universal
+
+---
+
+## Purpose
+
+A defect is almost never alone. It is one member of a set — one flag in a dispatch chain, one entry in a manifest, one directory under `agents/`, one config file in a tree. Fixing the member you were shown leaves the rest of the set exactly as it was, and **nothing announces the next one**. It surfaces months later as a fresh incident, and the work feels endless because the same shape keeps arriving under different names.
+
+This standard requires that a fix be aimed at the **set**, not at the member.
+
+一個缺陷幾乎從不孤單。它是某個集合的一員——分派鏈裡的一個旗標、manifest 裡的一條宣告、`agents/` 底下的一個目錄、目錄樹裡的一份設定檔。修掉被指出的那一員，集合裡其餘的原封不動，**而沒有任何東西會通知你下一個在哪**。它會在幾個月後以一則新事故的形式出現，於是工作感覺沒完沒了——因為同一個形狀不斷換名字回來。
+
+本標準要求：**修正瞄準集合，不是瞄準成員。**
+
+---
+
+## The Rule
+
+**Before fixing a defect, name the enumerable set it belongs to, and add a check that walks that set.** If the set cannot be walked, write down why. Silence is not an answer.
+
+**修一個缺陷之前，先指出它所屬的可窮舉集合，並加上一個走訪該集合的檢查。** 若該集合無法被走訪，寫下為什麼。沉默不算答案。
+
+### Three questions, in order
+
+| # | Question | 問題 |
+|---|---|---|
+| 1 | What set is this defect a member of? | 這個缺陷是哪個集合的一員？ |
+| 2 | Can that set be **walked** rather than **listed**? | 那個集合能不能被**走訪**而不是**列舉**？ |
+| 3 | Where does the walk read its members from? | 走訪從哪裡讀出成員？ |
+
+Question 3 decides whether the check survives. **The walk must read from the same source the system reads from** — the CLI definition, the directory, the manifest — never from a list you typed. A typed list is correct until someone adds the fourth member, and nothing will tell you.
+
+第 3 題決定這道檢查活不活得下去。**走訪必須從系統自己讀的那個來源讀**——CLI 定義、目錄、manifest——**絕不從你手打的清單讀**。手打的清單正確到有人新增第四個成員為止，而不會有東西告訴你。
+
+---
+
+## Walk and exclude, never enumerate
+
+| | Enumerate（列舉）| Walk and exclude（走訪並排除）|
+|---|---|---|
+| Shape | `for (const x of ['a','b','c'])` | `for (const x of readAll()) if (!EXCLUDED.has(x))` |
+| A new member is | silently uncovered | **covered by default** |
+| Wrong when | someone adds the fourth | someone adds an exclusion without cause |
+| Failure mode | reports green over a fraction | noisy — which is visible |
+
+**The asymmetry is the point.** An enumeration fails silently; an exclusion list fails loudly, because the exclusion has to be written down by a person who has to justify it.
+
+**不對稱正是重點。** 列舉失敗時是靜默的；排除清單失敗時是吵的，因為那條排除必須由一個人寫下來，而他得說明理由。
+
+---
+
+## The check must print what it excluded
+
+A denominator alone is not enough. `checked 4,012 declarations` reads like coverage while the filter silently skipped every directory entry.
+
+只印分母不夠。「檢查了 4,012 條宣告」讀起來像涵蓋率，而篩選器悄悄跳過了每一條目錄條目。
+
+```
+✓ 91 entries across 5 lists all resolve        # denominator
+  (0 excluded)                                  # and what was left out
+```
+
+See [verification-evidence](verification-evidence.md) — this is the same family: an output whose shape is identical whether the tool worked or not.
+
+---
+
+## Evidence requirement
+
+A class-level check must be proven non-vacuous **before** it is trusted:
+
+1. Add a synthetic member that violates the rule.
+2. Confirm the check fails **and names that member**.
+3. Remove it and confirm the check returns to green.
+
+Do this **per sub-set**, not in aggregate. A check over five lists that was only ever tested against the first is a check over one list.
+
+一道類別層檢查在被信任之前，必須先被證明不是空跑：塞一個違反規則的合成成員 → 確認檢查失敗**且指名該成員** → 移除後確認回到綠燈。**逐子集做，不要整體做**——一道涵蓋五份清單、卻只對第一份測過的檢查，是一道涵蓋一份清單的檢查。
+
+---
+
+## Worked examples (measured, 2026-08-10)
+
+### It works: the flag dispatch
+
+A CLI's `--plan` flag (documented as "show the plan without executing") was being silently discarded when combined with `--skills`, because scope flags sat ahead of mode flags in a first-match-wins chain. The instance-level fix was two branches.
+
+The class-level fix was a test that **reads the flag list off the CLI definition**, excludes the mode flags and the few that are not scopes, and asserts `--plan` writes nothing whatever it is combined with.
+
+**It found a fourth instance the moment it first ran** — `--sync-refs`, which nobody had looked at, and which was rewriting integration files and the manifest under a flag documented as not executing.
+
+### It fails: the same defect, fixed once, eleven days earlier
+
+The same codebase had already fixed exactly this for `--integrations-only`, eleven days before, **with a comment explaining the general problem**. The other three branches were left untouched. The knowledge was in the file; it had not reached its siblings.
+
+> **A comment describing the class is not a check over the class.** This is the failure this standard exists to prevent.
+
+### It fails: a gate that listed its own scope
+
+A parsing gate hardcoded three directories instead of walking the tree. It reported "423 files all pass" while the shipping surface was 287 files, and ten broken ones reached the registry.
+
+---
+
+## When the set cannot be walked
+
+Legitimate. Write it down, with the reason and what would change it.
+
+The common cause is that **the set's members are only knowable from a base directory that is not recorded anywhere machine-readable** — for example, a manifest whose paths are relative to a root stated only inside the program that reads it. A generic walk over such declarations produces false positives at a rate that gets the check switched off in its first week.
+
+In that case the workable form is **per-inventory**: one check per declaration kind, each knowing its own base and entry shape. Say how many inventories there are, and confirm each has a check.
+
+集合無法被走訪是合法的答案，但要寫下來，連同理由與「什麼條件下會改變」。
+
+最常見的成因是**成員只能相對於某個基準目錄才知道，而那個基準沒有記在任何機器讀得到的地方**——例如一份 manifest，它的路徑基準只活在讀取它的那支程式裡。對這種宣告做通用掃描，假陽性率高到讓檢查在第一週就被關掉。這時可行的形狀是**逐份清冊**：一種宣告一道檢查，各自知道自己的基準與條目形狀。**說出清冊有幾份，並確認每一份都有檢查。**
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|---|---|
+| Fixing the reported member and moving on | The set is unchanged; the next member arrives as a new incident |
+| A comment explaining the general problem | Prose does not execute |
+| A check that lists its own scope | Correct until someone adds the fourth member |
+| Testing the class check against one member | Proves that member, not the class |
+| `✓ all pass` with no denominator | Identical output whether it scanned everything or nothing |
+
+---
+
+## This standard has no automated gate — and that is recorded, not hidden
+
+Applying this standard is a judgement made at the moment of fixing. There is no check that can walk "all defects being fixed right now", so by its own rule the honest answer is to write down why not, rather than to imply enforcement that does not exist.
+
+**What this means in practice**: the only place it can bite is review — human or agent. A fix that changes one member of a set and adds no check over that set should be sent back with one question: *what set is this a member of?*
+
+**Reopen condition**: if a repository gains a mechanism that can see "a defect fix landed" as a discrete event (a labelled commit type, an issue-to-commit link), a check becomes possible — assert that such a commit either touches a test that walks a set, or carries a written reason. Until that exists, this standard is enforced by reading.
+
+> Recording this is not a formality. A standard that states a rule while nothing executes it is the exact shape of a documented risk with no enforcement — and a standard that does not admit it is worse than one that does, because the reader assumes something is watching.
+
+**本標準沒有自動閘門，而這件事是被記錄下來的，不是被藏起來的。**
+
+套用本標準是「修的當下」所做的判斷。沒有任何檢查能走訪「現在正在被修的所有缺陷」，所以依照它自己的規則，誠實的答案是寫下為什麼不能，而不是暗示一個不存在的強制力。
+
+**實務上唯一會咬到的地方是 review**（人或 agent）：一個只改了集合中某一員、而沒有加上涵蓋該集合之檢查的修正，應該被退回並問一句——**這是哪個集合的一員？**
+
+**重啟條件**：若某個 repo 取得了「能把『一次缺陷修正落地』看成一個離散事件」的機制（有標記的 commit 型別、issue↔commit 連結），檢查就變得可能——斷言這類 commit 要嘛動到一個走訪集合的測試，要嘛帶著一段寫下來的理由。在那之前，本標準靠閱讀執行。
+
+> 記下這件事不是形式。**一份陳述了規則而沒有東西執行它的標準，正是「寫下來的風險沒有東西在執行」那個形狀**——而一份不承認這一點的標準，比承認的更糟，因為讀的人會以為有東西在盯。
+
+---
+
+## Relationship to other standards
+
+- [verification-evidence](verification-evidence.md) — evidence validity: a tool can fail silently and its output is indistinguishable from a real result. This standard is the same concern applied to *scope* rather than to *execution*.
+- [anti-hallucination](anti-hallucination.md) — that one guards "did not check"; this one guards "checked one of many and reported on all".

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

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.3.9
-translation_version: 6.3.9
-last_synced: 2026-08-09
+source_version: 6.4.0
+translation_version: 6.4.0
+last_synced: 2026-08-10
 status: current
 ---
 
@@ -17,6 +17,29 @@ status: current
 
 ## [Unreleased]
 
+## [6.4.0] - 2026-08-10
+
+### 新增
+
+- **`class-level-fix` 标准——修正瞄准集合，不是瞄准成员。** 一个缺陷几乎从不孤单：它是分派链里的一个标志、manifest 里的一条声明、`agents/` 底下的一个目录。修掉被指出的那一员，集合里其余的原封不动，**而没有东西会通知你下一个在哪**——它会在几个月后以新事故的形式回来，那正是这类工作感觉没完没了的原因。规则：修之前先指出缺陷所属的可穷举集合，并加上一个**走访**该集合的检查。第三个问题决定这道检查活不活得下去——走访从哪里读出成员？必须是系统自己读的那个来源（CLI 定义、目录、manifest），**绝不是谁手打的清单**，因为手打的清单正确到第四个成员出现为止，而不会有东西告诉你。枚举失败时是静默的；走访配排除清单失败时是吵的，因为那条排除必须由一个人写下来、而他得说明理由。检查必须打印分母**与被排除的数量**——「检查了 4,012 条声明」读起来像覆盖率，而筛选器悄悄跳过了每一条目录条目。而且它在被信任之前要**逐子集**证明非空跑，因为一道覆盖五份清单却只对第一份测过的检查，是一道覆盖一份清单的检查。
+
+  标准里每一个实例都是 2026-08-10 量出来的。最有分量的是那个反例：本 repo **十一天前已经为 `--integrations-only` 修过完全相同的缺陷，还留了一段说明通则的注释**，而另外三个分支原封不动。知识就在那个文件里，只是没有到达它的兄弟。**一段描述类别的注释，不等于一道覆盖类别的检查。**
+
+  标准明白写出**它没有自动闸门**——没有东西能走访「现在正在被修的所有缺陷」——并记下理由、由什么执行（review，只问一句：*这是哪个集合的一员？*）、以及什么条件下闸门会变得可能。不写那一段，它就会变成它所要防止的那件事的下一个实例。
+
+### 修复
+
+- **`--plan` 与 `--apply` 的组合行为现在也到得了 `--help`。** 6.3.10 记录该行为的方式是编辑 `docs/reference/FEATURE-REFERENCE.md`——一份**生成的文件**。那次编辑活到有人重新生成为止。文本现在住在 `cli/bin/uds.js` 的 `.option()` 字符串里，于是它也会出现在 `uds update --help`，而手改的那一份从来不会。
+
+## [6.3.10] - 2026-08-10
+
+### 修复
+
+- **`--plan` 会被另外四个标志吃掉，而唯一能防止破坏的正是被忽略的那一个。** `uds update --plan --skills` 会安装 Skills；`--plan --sync-refs` 会改写集成文件与 manifest。那个文档写着「Show reconciliation plan without executing (like terraform plan)」的标志被静默丢弃——因为范围标志（`--skills`、`--commands`、`--integrations-only`、`--sync-refs`）在一条先到先得、每个分支都 return 的链里，排在模式标志（`--plan`、`--apply`、`--force`、`--rollback`）之前。`--integrations-only` 早在 2026-07-30 就为了同一件事修过；另外三个没有被碰，十一天后它们仍在写文件。现在模式先于范围决定，而测试改为**从 CLI 定义读出标志清单**而非人工列举——之后新增的标志不需要有人记得就会被覆盖。第四个实例正是那个测试找出来的。
+- **`--apply --skills` 只升级 Skills、安静地把标准留在原地，并报告成功。** 同一条链：`--skills` 在协调器执行之前就 return 了。以此方式升级一个真实项目，结果它停在旧的标准版本，而屏幕上没有任何一行说明。现在 `--apply` 与 `--force` 会执行协调**并且**执行所要求的范围。
+- **没有人能回答的确认提示，返回 exit 0。** 非交互 shell 下 `@inquirer/prompts` 会抛出 `ExitPromptError`，该异常从未被捕获而进程仍以 exit code 0 结束——于是在 CI 里「什么都没写」与「更新成功」返回同一个值。现在它会说明没有任何东西被写入、指向 `--yes`，并以 exit 2 结束。检测方式是**提示真的失败了**，而不是探测 `process.stdin.isTTY`——后者在两个方向上都会答错。
+- **`--rollback` 现在会说明 `--skills`／`--commands` 无法缩小它的范围**，而不是接受它们却照样还原全部。
+
 ## [6.3.9] - 2026-08-09
 
 ### 修复

package/bundled/locales/zh-CN/CLAUDE.md

@@ -14,7 +14,7 @@ status: current
 
 Universal Development Standards 是一个语言无关、框架无关的文件化标准框架。它提供：
 
-- **核心规范** (`core/`)：149 个基础开发标准
+- **核心规范** (`core/`)：150 个基础开发标准
 - **AI 技能** (`skills/`)：用于 AI 辅助开发的 Claude Code 技能
 - **CLI 工具** (`cli/`)：用于采用标准的 Node.js CLI
 - **整合** (`integrations/`)：各种 AI 工具的配置

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

@@ -15,7 +15,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 6.3.9 | **发布日期**: 2026-07-31 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.4.0 | **发布日期**: 2026-08-10 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 
@@ -76,10 +76,10 @@ npx universal-dev-standards init
 <!-- UDS_STATS_TABLE_START -->
 | 类别 | 数量 | 说明 |
 |----------|-------|-------------|
-| **核心标准** | 149 | 通用开发准则 |
+| **核心标准** | 150 | 通用开发准则 |
 | **AI Skills** | 55 | 互动式技能 |
 | **斜线命令** | 51 | 快速操作 |
-| **CLI 命令** | 21 | 项目设置与维护 |
+| **CLI 命令** | 22 | 项目设置与维护 |
 <!-- UDS_STATS_TABLE_END -->
 
 > **5.0 新功能？** 请参阅[预发布说明](../../docs/PRE-RELEASE.md)了解新功能详情。

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

@@ -13,7 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支持状态 |
 |------|--------|
-| 6.2.8 | ✅ 最新正式版 |
+| 6.3.10 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已终止支持 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

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

@@ -1,6 +1,6 @@
 # UDS 速查表
 
-> Quick reference for all UDS features | Last updated: 2026-07-31
+> Quick reference for all UDS features | Last updated: 2026-08-10
 
 **Language**: [English](../../../docs/user/CHEATSHEET.md) | [繁體中文](../../zh-TW/docs/CHEATSHEET.md) | 简体中文
 
@@ -190,6 +190,7 @@
 | `chaos-injection-tests` | Chaos Injection Tests |
 | `checkin-standards` | This standard defines quality gates that MUST be p |
 | `circuit-breaker` | Circuit Breaker Standard |
+| `class-level-fix` | A defect is almost never alone. It is one member o |
 | `code-review-checklist` | This standard provides a comprehensive checklist f |
 | `commit-message-guide` | Standardized commit messages improve code review e |
 | `container-image-standards` | Container Image Build and Security Standards |
@@ -322,6 +323,7 @@
 | `check-ai-agent-sync.ps1` | Check Ai Agent Sync |
 | `check-ai-agent-sync.sh` | AI Agent Sync Checker |
 | `check-ai-behavior-sync.sh` | DEPRECATED: Use 'npx tsx scripts/check-ai-behavior |
+| `check-ai-yaml-parses.mjs` | Every shipped .ai.yaml must parse, and must parse  |
 | `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 |

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

@@ -1,7 +1,7 @@
 # UDS 功能参考手册
 
 > Universal Development Standards - 完整功能文档
-> Auto-generated | Last updated: 2026-07-31
+> Auto-generated | Last updated: 2026-08-10
 
 **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | [繁體中文](../../zh-TW/docs/FEATURE-REFERENCE.md) | 简体中文
 
@@ -14,10 +14,10 @@
 3. [技能](#skills) (55)
 4. [代理](#agents) (5)
 5. [工作流程](#workflows) (5)
-6. [核心规范](#core-standards) (149)
-7. [脚本](#scripts) (58)
+6. [核心规范](#core-standards) (150)
+7. [脚本](#scripts) (59)
 
-**Total Features: 332**
+**Total Features: 334**
 
 ---
 
@@ -107,8 +107,8 @@
 | `--skills` | Install/update Skills for configured AI tools |
 | `--commands` | Install/update slash commands for configured AI tools |
 | `--debug` | Show debug output for Skills/Commands detection |
-| `--plan` | Show reconciliation plan without executing (like terraform plan) |
-| `--apply` | Apply exactly the plan --plan prints (plain `uds update` does not) |
+| `--plan` | Show reconciliation plan without executing (like terraform plan); combines with --skills/--commands to plan just that scope, still writing nothing |
+| `--apply` | Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope |
 | `--force` | Force update all files, ignoring hash comparison |
 | `--rollback` | Rollback to the most recent backup |
 | `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
@@ -317,6 +317,7 @@
 | `chaos-injection-tests` | - |  |
 | `checkin-standards` | 1.8.0 | This standard defines quality gates that MUST be passed before committing code t |
 | `circuit-breaker` | - |  |
+| `class-level-fix` | 1.0.0 | A defect is almost never alone. It is one member of a set — one flag in a dispat |
 | `code-review-checklist` | 1.4.0 | This standard provides a comprehensive checklist for reviewing code changes, ens |
 | `commit-message-guide` | 1.3.0 | Standardized commit messages improve code review efficiency, facilitate automate |
 | `container-image-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 |  |
@@ -417,7 +418,7 @@
 | `standard-lifecycle-management` | - |  |
 | `structured-task-definition` | 1.0.0 |  |
 | `supply-chain-attestation` | - |  |
-| `supply-chain-security-standards` | 1.0.0 |  |
+| `supply-chain-security-standards` | 1.1.0 |  |
 | `systematic-debugging` | 1.0.0 | Define a structured, four-phase debugging workflow that prevents the common anti |
 | `tech-debt-standards` | 1.0.0 |  |
 | `test-completeness-dimensions` | 1.1.0 | This document defines a systematic framework for evaluating test completeness. I |
@@ -451,6 +452,7 @@
 | `check-ai-agent-sync.ps1` | Check Ai Agent Sync |
 | `check-ai-agent-sync.sh` | AI Agent Sync Checker |
 | `check-ai-behavior-sync.sh` | DEPRECATED: Use 'npx tsx scripts/check-ai-behavior-sync.ts' instead (cross-platform). |
+| `check-ai-yaml-parses.mjs` | Every shipped .ai.yaml must parse, and must parse into what it says. |
 | `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 |

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

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.3.9
-translation_version: 6.3.9
-last_synced: 2026-08-09
+source_version: 6.4.0
+translation_version: 6.4.0
+last_synced: 2026-08-10
 status: current
 ---
 
@@ -17,6 +17,29 @@ status: current
 
 ## [Unreleased]
 
+## [6.4.0] - 2026-08-10
+
+### 新增
+
+- **`class-level-fix` 標準——修正瞄準集合，不是瞄準成員。** 一個缺陷幾乎從不孤單：它是分派鏈裡的一個旗標、manifest 裡的一條宣告、`agents/` 底下的一個目錄。修掉被指出的那一員，集合裡其餘的原封不動，**而沒有東西會通知你下一個在哪**——它會在幾個月後以新事故的形式回來，那正是這類工作感覺沒完沒了的原因。規則：修之前先指出缺陷所屬的可窮舉集合，並加上一個**走訪**該集合的檢查。第三個問題決定這道檢查活不活得下去——走訪從哪裡讀出成員？必須是系統自己讀的那個來源（CLI 定義、目錄、manifest），**絕不是誰手打的清單**，因為手打的清單正確到第四個成員出現為止，而不會有東西告訴你。列舉失敗時是靜默的；走訪配排除清單失敗時是吵的，因為那條排除必須由一個人寫下來、而他得說明理由。檢查必須印出分母**與被排除的數量**——「檢查了 4,012 條宣告」讀起來像涵蓋率，而篩選器悄悄跳過了每一條目錄條目。而且它在被信任之前要**逐子集**證明非空跑，因為一道涵蓋五份清單卻只對第一份測過的檢查，是一道涵蓋一份清單的檢查。
+
+  標準裡每一個實例都是 2026-08-10 量出來的。最有份量的是那個反例：本 repo **十一天前已經為 `--integrations-only` 修過完全相同的缺陷，還留了一段說明通則的註解**，而另外三個分支原封不動。知識就在那個檔案裡，只是沒有到達它的兄弟。**一段描述類別的註解，不等於一道涵蓋類別的檢查。**
+
+  標準明白寫出**它沒有自動閘門**——沒有東西能走訪「現在正在被修的所有缺陷」——並記下理由、由什麼執行（review，只問一句：*這是哪個集合的一員？*）、以及什麼條件下閘門會變得可能。不寫那一段，它就會變成它所要防止的那件事的下一個實例。
+
+### 修正
+
+- **`--plan` 與 `--apply` 的組合行為現在也到得了 `--help`。** 6.3.10 記錄該行為的方式是編輯 `docs/reference/FEATURE-REFERENCE.md`——一份**產生的檔案**。那次編輯活到有人重新產生為止。文字現在住在 `cli/bin/uds.js` 的 `.option()` 字串裡，於是它也會出現在 `uds update --help`，而手改的那一份從來不會。
+
+## [6.3.10] - 2026-08-10
+
+### 修正
+
+- **`--plan` 會被另外四個旗標吃掉，而唯一能防止破壞的正是被忽略的那一個。** `uds update --plan --skills` 會安裝 Skills；`--plan --sync-refs` 會改寫整合檔與 manifest。那個文件寫著「Show reconciliation plan without executing (like terraform plan)」的旗標被靜默丟棄——因為範圍旗標（`--skills`、`--commands`、`--integrations-only`、`--sync-refs`）在一條先到先得、每個分支都 return 的鏈裡，排在模式旗標（`--plan`、`--apply`、`--force`、`--rollback`）之前。`--integrations-only` 早在 2026-07-30 就為了同一件事修過；另外三個沒有被碰，十一天後它們仍在寫檔。現在模式先於範圍決定，而測試改為**從 CLI 定義讀出旗標清單**而非人工列舉——之後新增的旗標不需要有人記得就會被涵蓋。第四個實例正是那個測試找出來的。
+- **`--apply --skills` 只升級 Skills、安靜地把標準留在原地，並回報成功。** 同一條鏈：`--skills` 在調和器執行之前就 return 了。以此方式升級一個真實專案，結果它停在舊的標準版本，而畫面上沒有任何一行說明。現在 `--apply` 與 `--force` 會執行調和**並且**執行所要求的範圍。
+- **沒有人能回答的確認提示，回傳 exit 0。** 非互動 shell 下 `@inquirer/prompts` 會擲 `ExitPromptError`，該例外從未被攔截而程序仍以 exit code 0 結束——於是在 CI 裡「什麼都沒寫」與「更新成功」回傳同一個值。現在它會說明沒有任何東西被寫入、指向 `--yes`，並以 exit 2 結束。偵測方式是**提示真的失敗了**，而不是探測 `process.stdin.isTTY`——後者在兩個方向上都會答錯。
+- **`--rollback` 現在會說明 `--skills`／`--commands` 無法縮小它的範圍**，而不是接受它們卻照樣還原全部。
+
 ## [6.3.9] - 2026-08-09
 
 ### 修正

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

@@ -14,7 +14,7 @@ status: current
 
 Universal Development Standards 是一個語言無關、框架無關的文件化標準框架。它提供：
 
-- **核心規範** (`core/`)：149 個基礎開發標準
+- **核心規範** (`core/`)：150 個基礎開發標準
 - **AI 技能** (`skills/`)：用於 AI 輔助開發的 Claude Code 技能
 - **CLI 工具** (`cli/`)：用於採用標準的 Node.js CLI
 - **整合** (`integrations/`)：各種 AI 工具的配置

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

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

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

@@ -13,7 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支援狀態 |
 |------|--------|
-| 6.2.8 | ✅ 最新正式版 |
+| 6.3.10 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已終止支援 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/bundled/locales/zh-TW/core/class-level-fix.md

@@ -0,0 +1,148 @@
+---
+source: ../../../core/class-level-fix.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-08-10
+source_hash: 1a2b451bae6d
+status: current
+---
+
+# 類別層修正標準
+
+> **Language**: [English](../../../core/class-level-fix.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-08-10
+**適用**: 任何缺陷修正（程式碼或設定）
+**範圍**: universal
+
+---
+
+## 目的
+
+一個缺陷幾乎從不孤單。它是某個集合的一員——分派鏈裡的一個旗標、manifest 裡的一條宣告、`agents/` 底下的一個目錄、目錄樹裡的一份設定檔。修掉被指出的那一員，集合裡其餘的原封不動，**而沒有任何東西會通知你下一個在哪**。它會在幾個月後以一則新事故的形式出現，於是工作感覺沒完沒了——因為同一個形狀不斷換名字回來。
+
+本標準要求：**修正瞄準集合，不是瞄準成員。**
+
+---
+
+## 規則
+
+**修一個缺陷之前，先指出它所屬的可窮舉集合，並加上一個走訪該集合的檢查。** 若該集合無法被走訪，寫下為什麼。沉默不算答案。
+
+### 三個問題，依序回答
+
+| # | 問題 |
+|---|---|
+| 1 | 這個缺陷是哪個集合的一員？ |
+| 2 | 那個集合能不能被**走訪**而不是被**列舉**？ |
+| 3 | 走訪從哪裡讀出成員？ |
+
+第 3 題決定這道檢查活不活得下去。**走訪必須從系統自己讀的那個來源讀**——CLI 定義、目錄、manifest——**絕不從你手打的清單讀**。手打的清單正確到有人新增第四個成員為止，而不會有東西告訴你。
+
+---
+
+## 走訪並排除，絕不列舉
+
+| | 列舉 | 走訪並排除 |
+|---|---|---|
+| 形狀 | `for (const x of ['a','b','c'])` | `for (const x of readAll()) if (!EXCLUDED.has(x))` |
+| 新成員 | 靜默地不被涵蓋 | **預設被涵蓋** |
+| 何時會錯 | 有人新增第四個 | 有人在沒有理由下加了排除 |
+| 失效方式 | 對一部分表面回報綠燈 | 吵——而吵是看得見的 |
+
+**不對稱正是重點。** 列舉失敗時是靜默的；排除清單失敗時是吵的，因為那條排除必須由一個人寫下來，而他得說明理由。
+
+---
+
+## 檢查必須印出被排除的數量
+
+只印分母不夠。「檢查了 4,012 條宣告」讀起來像涵蓋率，而篩選器悄悄跳過了每一條目錄條目。
+
+```
+✓ 91 entries across 5 lists all resolve        # 分母
+  (0 excluded)                                  # 以及被排除的
+```
+
+見 [verification-evidence](verification-evidence.md)——這是同一族：**輸出的形狀在工具壞掉時與正常時無從分辨**。
+
+---
+
+## 證據要求
+
+一道類別層檢查在被信任之前，必須先被證明不是空跑：
+
+1. 塞一個違反規則的合成成員。
+2. 確認檢查失敗**且指名該成員**。
+3. 移除後確認檢查回到綠燈。
+
+**逐子集做，不要整體做。** 一道涵蓋五份清單、卻只對第一份測過的檢查，是一道涵蓋一份清單的檢查。
+
+---
+
+## 實例（皆為實測，2026-08-10）
+
+### 有效：旗標分派
+
+某 CLI 的 `--plan` 旗標（文件寫著「印出計畫但不執行」）在與 `--skills` 併用時被靜默丟棄，因為範圍旗標在一條先到先得的鏈裡排在模式旗標之前。實例層的修法是兩個分支。
+
+類別層的修法是一個**從 CLI 定義讀出旗標清單**的測試，排除模式旗標與少數非範圍的旗標，然後斷言 `--plan` 在任何組合下都不寫檔。
+
+**它第一次跑起來就找到第四個實例**——`--sync-refs`，那個從來沒有人看過、而且正在一個文件宣稱「不執行」的旗標底下改寫整合檔與 manifest。
+
+### 失效：同一個缺陷，十一天前修過一次
+
+同一份程式碼**十一天前已經為 `--integrations-only` 修過完全相同的問題，還留了一段註解說明通則**。另外三個分支沒有被碰。**知識就在那個檔案裡，只是沒有到達它的兄弟。**
+
+> **一段描述類別的註解，不等於一道涵蓋類別的檢查。** 這正是本標準存在的理由。
+
+### 失效：自行列舉範圍的閘門
+
+一道解析閘門硬編碼三個目錄而不走訪整棵樹。它回報「423 個檔案全部通過」，而實際出貨面是 287 個檔案，其中十個壞的到達了 registry。
+
+---
+
+## 集合無法走訪時
+
+這是合法的答案，但要寫下來，連同理由與「什麼條件下會改變」。
+
+最常見的成因是**成員只能相對於某個基準目錄才知道，而那個基準沒有記在任何機器讀得到的地方**——例如一份 manifest，它的路徑基準只活在讀取它的那支程式裡。對這種宣告做通用掃描，假陽性率高到讓檢查在第一週就被關掉。
+
+這時可行的形狀是**逐份清冊**：一種宣告一道檢查，各自知道自己的基準與條目形狀。**說出清冊有幾份，並確認每一份都有檢查。**
+
+---
+
+## 反模式
+
+| 反模式 | 為何失效 |
+|---|---|
+| 修掉被回報的那一員就結案 | 集合沒有變；下一個成員會以新事故的形式抵達 |
+| 寫一段註解說明通則 | 散文不會執行 |
+| 檢查自行列舉它的範圍 | 正確到有人新增第四個成員為止 |
+| 類別層檢查只對一個成員測過 | 證明的是那一個成員，不是那個類別 |
+| `✓ all pass` 而沒有分母 | 掃了全部與什麼都沒掃，輸出一模一樣 |
+
+---
+
+## 本標準沒有自動閘門，而這件事是被記錄下來的，不是被藏起來的
+
+套用本標準是「修的當下」所做的判斷。沒有任何檢查能走訪「現在正在被修的所有缺陷」，
+所以依照它自己的規則，誠實的答案是寫下為什麼不能，而不是暗示一個不存在的強制力。
+
+**實務上唯一會咬到的地方是 review**（人或 agent）：一個只改了集合中某一員、
+而沒有加上涵蓋該集合之檢查的修正，應該被退回並問一句——**這是哪個集合的一員？**
+
+**重啟條件**：若某個 repo 取得了「能把『一次缺陷修正落地』看成一個離散事件」的機制
+（有標記的 commit 型別、issue↔commit 連結），檢查就變得可能——斷言這類 commit
+要嘛動到一個走訪集合的測試，要嘛帶著一段寫下來的理由。在那之前，本標準靠閱讀執行。
+
+> 記下這件事不是形式。**一份陳述了規則而沒有東西執行它的標準，正是「寫下來的風險
+> 沒有東西在執行」那個形狀**——而一份不承認這一點的標準，比承認的更糟，
+> 因為讀的人會以為有東西在盯。
+
+---
+
+## 與其他標準的關係
+
+- [verification-evidence](verification-evidence.md) — 證據有效性：工具可以靜默失敗，而其輸出與真結果無從分辨。本標準是同一件事套用在**範圍**而非**執行**上。
+- [anti-hallucination](anti-hallucination.md) — 那個防「沒查」；這個防「查了其中一個，卻對全部下結論」。

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

@@ -1,6 +1,6 @@
 # UDS 速查表
 
-> Quick reference for all UDS features | Last updated: 2026-07-31
+> Quick reference for all UDS features | Last updated: 2026-08-10
 
 **Language**: [English](../../../docs/user/CHEATSHEET.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CHEATSHEET.md)
 
@@ -190,6 +190,7 @@
 | `chaos-injection-tests` | Chaos Injection Tests |
 | `checkin-standards` | This standard defines quality gates that MUST be p |
 | `circuit-breaker` | Circuit Breaker Standard |
+| `class-level-fix` | A defect is almost never alone. It is one member o |
 | `code-review-checklist` | This standard provides a comprehensive checklist f |
 | `commit-message-guide` | Standardized commit messages improve code review e |
 | `container-image-standards` | Container Image Build and Security Standards |
@@ -322,6 +323,7 @@
 | `check-ai-agent-sync.ps1` | Check Ai Agent Sync |
 | `check-ai-agent-sync.sh` | AI Agent Sync Checker |
 | `check-ai-behavior-sync.sh` | DEPRECATED: Use 'npx tsx scripts/check-ai-behavior |
+| `check-ai-yaml-parses.mjs` | Every shipped .ai.yaml must parse, and must parse  |
 | `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 |

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

@@ -1,7 +1,7 @@
 # UDS 功能參考手冊
 
 > Universal Development Standards - 完整功能文件
-> Auto-generated | Last updated: 2026-07-31
+> Auto-generated | Last updated: 2026-08-10
 
 **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | 繁體中文 | [简体中文](../../zh-CN/docs/FEATURE-REFERENCE.md)
 
@@ -14,10 +14,10 @@
 3. [技能](#skills) (55)
 4. [代理](#agents) (5)
 5. [工作流程](#workflows) (5)
-6. [核心規範](#core-standards) (149)
-7. [腳本](#scripts) (58)
+6. [核心規範](#core-standards) (150)
+7. [腳本](#scripts) (59)
 
-**Total Features: 332**
+**Total Features: 334**
 
 ---
 
@@ -107,8 +107,8 @@
 | `--skills` | Install/update Skills for configured AI tools |
 | `--commands` | Install/update slash commands for configured AI tools |
 | `--debug` | Show debug output for Skills/Commands detection |
-| `--plan` | Show reconciliation plan without executing (like terraform plan) |
-| `--apply` | Apply exactly the plan --plan prints (plain `uds update` does not) |
+| `--plan` | Show reconciliation plan without executing (like terraform plan); combines with --skills/--commands to plan just that scope, still writing nothing |
+| `--apply` | Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope |
 | `--force` | Force update all files, ignoring hash comparison |
 | `--rollback` | Rollback to the most recent backup |
 | `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
@@ -317,6 +317,7 @@
 | `chaos-injection-tests` | - |  |
 | `checkin-standards` | 1.8.0 | This standard defines quality gates that MUST be passed before committing code t |
 | `circuit-breaker` | - |  |
+| `class-level-fix` | 1.0.0 | A defect is almost never alone. It is one member of a set — one flag in a dispat |
 | `code-review-checklist` | 1.4.0 | This standard provides a comprehensive checklist for reviewing code changes, ens |
 | `commit-message-guide` | 1.3.0 | Standardized commit messages improve code review efficiency, facilitate automate |
 | `container-image-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 |  |
@@ -417,7 +418,7 @@
 | `standard-lifecycle-management` | - |  |
 | `structured-task-definition` | 1.0.0 |  |
 | `supply-chain-attestation` | - |  |
-| `supply-chain-security-standards` | 1.0.0 |  |
+| `supply-chain-security-standards` | 1.1.0 |  |
 | `systematic-debugging` | 1.0.0 | Define a structured, four-phase debugging workflow that prevents the common anti |
 | `tech-debt-standards` | 1.0.0 |  |
 | `test-completeness-dimensions` | 1.1.0 | This document defines a systematic framework for evaluating test completeness. I |
@@ -451,6 +452,7 @@
 | `check-ai-agent-sync.ps1` | Check Ai Agent Sync |
 | `check-ai-agent-sync.sh` | AI Agent Sync Checker |
 | `check-ai-behavior-sync.sh` | DEPRECATED: Use 'npx tsx scripts/check-ai-behavior-sync.ts' instead (cross-platform). |
+| `check-ai-yaml-parses.mjs` | Every shipped .ai.yaml must parse, and must parse into what it says. |
 | `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 |

package/package.json

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

package/src/commands/update.js

@@ -334,9 +334,13 @@ export async function updateCommand(options) {
   console.log(chalk.bold(msg.title));
   console.log(chalk.gray('─'.repeat(50)));
 
-  // Handle --sync-refs option
+  // Handle --sync-refs option.
+  // `--plan` is honoured here too. This branch is above the mode dispatch
+  // because sync-refs is its own operation rather than a scope of the
+  // reconciler — but "above the dispatch" is exactly how --plan got dropped by
+  // three other branches, so it passes the flag down instead of assuming.
   if (options.syncRefs) {
-    await syncIntegrationReferences(projectPath, manifest);
+    await syncIntegrationReferences(projectPath, manifest, { plan: !!options.plan });
     return;
   }
 
@@ -350,39 +354,68 @@ export async function updateCommand(options) {
     return;
   }
 
-  // Handle --skills option
-  if (options.skills) {
-    await updateSkillsOnly(projectPath, manifest, options);
-    return;
-  }
-
-  // Handle --commands option
-  if (options.commands) {
-    await updateCommandsOnly(projectPath, manifest, options);
-    return;
-  }
-
-  // Handle --rollback option (DSR)
+  // ── Flags come in two axes, and they must not eat each other ──────────
+  // // implements XSPEC-372 R1/R2
+  //
+  //   mode  : --plan / --apply / --force / --rollback   (what to do)
+  //   scope : --skills / --commands / --integrations-only / --standards-only
+  //
+  // These used to sit in one first-match-wins if/return chain with the scope
+  // flags first. `--plan --skills` therefore *installed* Skills — the flag
+  // documented as "without executing" was dropped with nothing said — and
+  // `--apply --skills` upgraded Skills while silently leaving the standards
+  // behind, reporting success either way. Both measured 2026-08-10 while
+  // upgrading four repos to 6.3.9.
+  //
+  // Mode is now decided first, and scope narrows it instead of replacing it.
+  const scopedToSkills = !!options.skills;
+  const scopedToCommands = !!options.commands;
+
+  // Handle --rollback option (DSR). It restores a whole backup, so a scope
+  // flag cannot narrow it — say so rather than appearing to honour it.
   if (options.rollback) {
+    if (scopedToSkills || scopedToCommands) {
+      console.log(chalk.yellow('  ! --rollback restores a complete backup; --skills/--commands cannot narrow it and are ignored.'));
+      console.log();
+    }
     await handleRollback(projectPath);
     return;
   }
 
-  // Handle --plan option (DSR dry-run)
+  // Handle --plan option (DSR dry-run). Nothing below this line writes.
   if (options.plan) {
-    await handlePlan(projectPath, options);
+    if (!scopedToSkills && !scopedToCommands) {
+      await handlePlan(projectPath, options);
+    }
+    if (scopedToSkills) await planSkills(projectPath, manifest, options);
+    if (scopedToCommands) await planCommands(projectPath, manifest, options);
+    return;
+  }
+
+  // Handle --apply / --force (DSR reconciliation), composing with scope.
+  // A scope flag alone still means "only that scope"; combined with a mode it
+  // means "that mode, and also that scope" — the reconciler tracks Skills
+  // files only when the manifest records them, so `--skills` is not redundant.
+  if (options.apply || options.force) {
+    if (!scopedToSkills && !scopedToCommands) {
+      await handleReconcile(projectPath, options, { force: !!options.force });
+      return;
+    }
+    await handleReconcile(projectPath, options, { force: !!options.force });
+    // These exit the process on completion, so run Skills last.
+    if (scopedToCommands) await updateCommandsOnly(projectPath, manifest, options);
+    if (scopedToSkills) await updateSkillsOnly(projectPath, manifest, options);
     return;
   }
 
-  // Handle --apply option (DSR: execute the plan `--plan` prints)
-  if (options.apply) {
-    await handleReconcile(projectPath, options, { force: false });
+  // Scope without a mode: the original shortcuts.
+  if (scopedToSkills) {
+    await updateSkillsOnly(projectPath, manifest, options);
     return;
   }
 
-  // Handle --force option (DSR force reconciliation)
-  if (options.force) {
-    await handleReconcile(projectPath, options, { force: true });
+  if (scopedToCommands) {
+    await updateCommandsOnly(projectPath, manifest, options);
     return;
   }
 
@@ -494,11 +527,8 @@ export async function updateCommand(options) {
   console.log();
 
   // Confirm
-  if (!options.yes) {
-    const confirmed = await inquirerConfirm({
-      message: msg.confirmUpdate,
-      default: true
-    });
+  {
+    const confirmed = await confirmOrFail({ message: msg.confirmUpdate, options });
 
     if (!confirmed) {
       console.log(chalk.yellow(msg.updateCancelled));
@@ -558,10 +588,7 @@ export async function updateCommand(options) {
       shouldInstallNew = true;
     } else {
       // Interactive mode: ask user
-      const installNew = await inquirerConfirm({
-        message: msg.installNewStandards,
-        default: true
-      });
+      const installNew = await confirmOrFail({ message: msg.installNewStandards, options });
       shouldInstallNew = installNew;
     }
 
@@ -886,9 +913,9 @@ export async function updateCommand(options) {
     if (options.yes) {
       shouldRestore = true;
     } else {
-      const restoreMissing = await inquirerConfirm({
+      const restoreMissing = await confirmOrFail({
         message: (msg.restoreMissingPrompt || 'Restore {count} missing file(s)?').replace('{count}', missingFiles.length),
-        default: true
+        options
       });
       shouldRestore = restoreMissing;
     }
@@ -1440,6 +1467,40 @@ export function regenerateIntegrations(projectPath, manifest) {
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
  */
+/**
+ * Ask for confirmation, or fail loudly when there is nobody to ask.
+ * // implements XSPEC-372 R3
+ *
+ * `@inquirer/prompts` throws `ExitPromptError` when stdin is not a TTY. That
+ * exception was never caught, and the process still ended with **exit code 0**
+ * — so in CI a run that wrote nothing was indistinguishable from a successful
+ * update. Measured 2026-08-10 on `uds update --apply` and reproduced with
+ * `--force --apply`: zero files written, `echo $?` printed 0.
+ *
+ * Not auto-confirming: that would give an unattended environment broader
+ * permission than an interactive one. Exit 2 rather than 1 keeps "could not
+ * run" distinct from "ran and found a problem".
+ */
+async function confirmOrFail({ message, defaultValue = true, options }) {
+  if (options?.yes) return true;
+  try {
+    return await inquirerConfirm({ message, default: defaultValue });
+  } catch (err) {
+    // Detect by what the prompt does, not by probing `process.stdin.isTTY`.
+    // isTTY is a proxy for "somebody can answer", and it is wrong in both
+    // directions — a mocked or wrapped stdin answers fine with isTTY unset.
+    // The prompt failing IS the condition; anything else is a guess about it.
+    const closed = err?.name === 'ExitPromptError' || /force closed the prompt/i.test(err?.message || '');
+    if (!closed) throw err;
+    console.log();
+    console.log(chalk.red('Cannot ask for confirmation: there is nothing attached to answer the prompt (non-interactive shell, CI, or a pipe).'));
+    console.log(chalk.gray(`  Pending question: ${message}`));
+    console.log(chalk.gray('  Re-run with --yes to confirm up front. Nothing has been written.'));
+    console.log();
+    process.exit(2);
+  }
+}
+
 async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
   const msg = t().commands.update;
 
@@ -1548,7 +1609,7 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
  */
-async function syncIntegrationReferences(projectPath, manifest) {
+async function syncIntegrationReferences(projectPath, manifest, { plan = false } = {}) {
   const msg = t().commands.update;
 
   console.log(chalk.cyan(msg.syncingRefs));
@@ -1615,6 +1676,12 @@ async function syncIntegrationReferences(projectPath, manifest) {
       outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || config.outputLanguage || config.commitLanguage || 'english'
     };
 
+    if (plan) {
+      console.log(chalk.yellow(`  ~ ${integrationPath}: categories would change to ${expectedCategories.join(', ') || '(none)'} (dry run — nothing is written)`));
+      updatedCount++;
+      continue;
+    }
+
     const result = writeIntegrationFile(toolName, newConfig, projectPath);
 
     if (result.success) {
@@ -1657,7 +1724,11 @@ async function syncIntegrationReferences(projectPath, manifest) {
   if (updatedCount > 0) {
     manifest.version = '3.3.0';
     refreshIntegrationBlockHashes(manifest, projectPath);
-    writeManifest(manifest, projectPath);
+    if (plan) {
+      console.log(chalk.gray('  (dry run — the manifest was not written)'));
+    } else {
+      writeManifest(manifest, projectPath);
+    }
   }
 
   // Summary
@@ -1680,6 +1751,83 @@ async function syncIntegrationReferences(projectPath, manifest) {
  * @param {Object} manifest - Manifest object
  * @param {Object} [options] - CLI options (forwarded for locale resolution)
  */
+/**
+ * `--plan --skills`: say what a Skills update would do, and write nothing.
+ * // implements XSPEC-372 R1
+ *
+ * Deliberately does not call installSkillsToMultipleAgents and roll back.
+ * "Write then restore" leaves a broken tree if it dies halfway, which is worse
+ * than having no dry run at all — the same reasoning as the integrations plan.
+ */
+async function planSkills(projectPath, manifest, options) {
+  const repoInfo = getRepositoryInfo();
+  const latestVersion = repoInfo.skills.version;
+  const installations = (manifest.skills?.installations || []).filter(i => i.level !== 'marketplace');
+
+  console.log(chalk.bold('=== Skills Plan (dry run — nothing is written) ==='));
+
+  if (installations.length === 0) {
+    // Not "up to date". The manifest records no installation, so a Skills
+    // update has nothing to act on — which is a different answer, and the one
+    // that explains why `--skills` appears to do nothing here.
+    console.log(chalk.yellow('  No Skills installations recorded in the manifest — nothing for --skills to update.'));
+    if (manifest.skills?.installed) {
+      console.log(chalk.gray('  (manifest.skills.installed is true but installations[] is empty; run `uds skills` to re-register)'));
+    }
+    console.log();
+    return;
+  }
+
+  let changed = 0;
+  for (const inst of installations) {
+    const info = getInstalledSkillsInfoForAgent(inst.agent, inst.level, projectPath);
+    const current = info?.version || 'unknown';
+    const dir = getSkillsDirForAgent(inst.agent, inst.level, projectPath);
+    if (current === latestVersion) {
+      console.log(chalk.gray(`  = ${getAgentDisplayName(inst.agent)} (${inst.level}): v${current} — unchanged`));
+    } else {
+      changed++;
+      console.log(chalk.yellow(`  ~ ${getAgentDisplayName(inst.agent)} (${inst.level}): v${current} → v${latestVersion}  ${dir}`));
+    }
+  }
+
+  console.log();
+  console.log(`Summary: ${changed} installation(s) would be updated, ${installations.length - changed} unchanged.`);
+  console.log(chalk.gray(`  Locale that would be used: ${resolveLocale(manifest, projectPath, options)}`));
+  console.log(chalk.gray('  Run `uds update --apply --yes --skills` to apply.'));
+  console.log();
+}
+
+/**
+ * `--plan --commands`: same contract as planSkills.
+ * // implements XSPEC-372 R1
+ */
+async function planCommands(projectPath, manifest, options) {
+  const installations = manifest.commands?.installations || [];
+
+  console.log(chalk.bold('=== Commands Plan (dry run — nothing is written) ==='));
+
+  if (installations.length === 0) {
+    console.log(chalk.yellow('  No slash-command installations recorded in the manifest — nothing for --commands to update.'));
+    console.log();
+    return;
+  }
+
+  for (const inst of installations) {
+    const agent = typeof inst === 'string' ? inst : inst.agent;
+    const level = typeof inst === 'string' ? 'project' : (inst.level || 'project');
+    const info = getInstalledCommandsForAgent(agent, level, projectPath);
+    const dir = getCommandsDirForAgent(agent, level, projectPath);
+    console.log(chalk.yellow(`  ~ ${getAgentDisplayName(agent)} (${level}): ${info?.count || 0} command(s) would be reinstalled  ${dir}`));
+  }
+
+  console.log();
+  console.log(`Summary: ${installations.length} installation(s) would be reinstalled.`);
+  console.log(chalk.gray(`  Locale that would be used: ${resolveLocale(manifest, projectPath, options)}`));
+  console.log(chalk.gray('  Run `uds update --apply --yes --commands` to apply.'));
+  console.log();
+}
+
 async function updateSkillsOnly(projectPath, manifest, options) {
   const msg = t().commands.update;
   const repoInfo = getRepositoryInfo();
@@ -2382,10 +2530,10 @@ async function handleReconcile(projectPath, options, { force }) {
   console.log();
 
   // Confirm unless --yes
-  if (!options.yes) {
-    const confirmed = await inquirerConfirm({
+  {
+    const confirmed = await confirmOrFail({
       message: `Apply ${planResult.plan.actions.length} changes?`,
-      default: true
+      options
     });
 
     if (!confirmed) {

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.3.9",
+  "version": "6.4.0",
   "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": "6.3.9"
+      "version": "6.4.0"
     },
     "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": "6.3.9",
+      "version": "6.4.0",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -1742,6 +1742,18 @@
       "skillName": null,
       "description": "Git worktree lifecycle management: setup → baseline → execute → merge → cleanup"
     },
+    {
+      "id": "class-level-fix",
+      "name": "Class-Level Fix Standard",
+      "nameZh": "類別層修正標準",
+      "source": {
+        "human": "core/class-level-fix.md",
+        "ai": "ai/standards/class-level-fix.ai.yaml"
+      },
+      "category": "skill",
+      "skillName": null,
+      "description": "Aim a fix at the set, not the member. Walk the set from the source the system reads, never from a typed list; print the denominator and what was excluded; prove the check non-vacuous per sub-set"
+    },
     {
       "id": "verification-evidence",
       "name": "Verification Evidence Standard",
@@ -2236,7 +2248,7 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
-      "version": "6.3.9",
+      "version": "6.4.0",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2248,7 +2260,7 @@
       "id": "verification-oracle",
       "name": "Verification Oracle Standards",
       "nameZh": "驗證 Oracle 標準",
-      "version": "6.3.9",
+      "version": "6.4.0",
       "source": {
         "human": "core/verification-oracle.md",
         "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2260,7 +2272,7 @@
       "id": "model-provenance",
       "name": "Model Provenance Policy Standards",
       "nameZh": "模型來源政策標準",
-      "version": "6.3.9",
+      "version": "6.4.0",
       "source": {
         "human": "core/model-provenance.md",
         "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2272,7 +2284,7 @@
       "id": "resource-cost-boundary",
       "name": "Resource / Cost Boundary Declaration Standards",
       "nameZh": "資源／成本邊界宣告標準",
-      "version": "6.3.9",
+      "version": "6.4.0",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"