universal-dev-standards 6.7.2 → 6.7.4

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

@@ -1,7 +1,7 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.7.2
-translation_version: 6.7.2
+source_version: 6.7.4
+translation_version: 6.7.4
 last_synced: 2026-08-18
 status: current
 ---
@@ -17,6 +17,28 @@ status: current
 
 ## [Unreleased]
 
+## [6.7.4] - 2026-08-18
+
+### 修正
+
+- **6.7.3 让 `uds check` 每个 repo 报出 52 个不存在的「缺失」文件。** 6.7.3 的两个改动要**同时在场**才会互相作用：R1 给了 skill 内容哈希，使它们第一次走进 `unchanged` 分支；而 R6b 会把那个分支的条目收进 `manifest.fileHashes`。那张表是用 `isFile()` 验证的，而 skill 是目录，于是每一个都被报成缺失。**没有任何东西被删除——错的是记录不是磁盘**（已验证：59 个 skill 目录与其内容完好）。`verifiedPristine` 现在限缩于文件类别；而且**修好写入端不会让已经写进去的东西消失**，所以 `uds update` 也会清掉 `fileHashes` 里的 `.claude/skills/` 与 `.claude/commands/` 键——**一个坏掉的键不会有第二次机会被访问**，因为磁盘上没有任何东西对应它。
+- **commands 也改为内容比对（XSPEC-382 R7）。** R1 只涵盖 skills，把 commands 留在 `hash: null`，于是无条件重装的分支对它们仍然活着。与 skills 同一个形状：`resolveCommandContent(name, agent, locale)` 说明一次安装会包含什么（locale 选择＋英文回退，加上逐 agent 的转换），安装器写它、计划器哈希它。
+- **装了 locale 版的人，拿到的 SKILL.md 指向从来不会被安装的文件。** locale 包不是英文来源的完整副本——实测 **zh-TW 59 个中有 4 个、zh-CN 59 个中有 5 个**缺少英文有出货的文件——而安装器把 locale 目录整包换上去，于是那些伴随文件根本没被写入。其中两个缺口**是被引用的**：zh-TW 的 `dev-workflow-guide/SKILL.md` 引用 `workflow-phases.md` 三次、`testing-guide/SKILL.md` 引用 `test-skeleton-templates.md` 三次。**回退改为逐文件而非逐 skill**——locale 有就用 locale 的，没有就用英文的。
+- **UDS 不出货的文件，不再让一个 skill 永远停在「已变更」。** 安装一个 skill 现在会移除其目录下**解析结果没有指名**的顶层文件（实地发现：`deploy-assistant/guide.md`，它不在任何 UDS skills 树里，而且从来就不在）。范围由同一个 provenance 判准界定，也就是让采用者自己的 skill 目录不进入此处任何路径的那一个——**已验证手写的 skill 目录与其额外文件在 `--force` 之后完好无损**——子目录一律不动，因为安装器从来没有写过它们。
+
+## [6.7.3] - 2026-08-18
+
+### 修正
+
+- **skill 改为内容比对，升级不再重印 55 行毫无意义的变更。** diff 两端都硬写 `hash: null`，于是每个 skill 都是无条件重装。**两端各算来源目录的哈希行不通**——安装不是逐字节复制：locale 版的 `SKILL.md` 会被并入英文 frontmatter（`brainstorm-assistant`：23,753 字节的 zh-TW 来源变成 23,866 字节的安装结果）、来源是运行期依 locale 逐 skill 选择并可回退英文、子目录被跳过。照那样做，55 个全都会显示为内容**变更**，每次升级皆然——**与真的变更无从分辨，比那个已知的无信号更糟**。改为只有一个函数：`resolveSkillFiles(name, locale)` 说明一次安装会包含什么，**安装器写它、计划器哈希它**，两者因此不可能漂移。与真实已安装的项目对账：110 个文件逐字节相符、0 个不符，18 个采用者自写的 skill 正确地解不出来。actual 端**只对 UDS 管理的目录计算哈希**；采用者自己的 skill 永远不被比较、也永远不会变成删除候选。真实升级中的 `Update (57)` 现在是 `Update: 0, Unchanged: 127`。
+- **`uds check --restore` 对 72 个受追踪标准中的 64 个无法还原。** 它拿 `entry.endsWith(fileName)` 去比对 `manifest.standards`，而那些条目**自 3.4.0 起是 ID（`commit-message`）而非路径**——这个比较永远不可能为真。能用的那 8 个是仍存路径格式的 `options/`，**这正是失败从来看起来不像全面失败的原因**；其余一律报告「Could not determine source」。同一段 ID→来源的解析在这个文件里已经存在两次，而这一处从来没拿到过，所以修法是在 `registry.js` 收敛出一支解析器，**与它必须一致的那支文件名解析器配对**。
+- **一个逐字节正确的标准，没办法停止被报成「已修改」。** actual state 是从磁盘算哈希的，所以与上游相符的文件被归为 `unchanged`、不产生动作、也永远不会被重新哈希——而 reconciliation 在计划为空时提前返回、连 manifest 都不写。**没有回头路。** diff 现在报告它**证明过**与上游相同的那些文件，并在提前返回之前补正记录。**刻意做得很窄**：只有在证明磁盘与 desired 相符之后才记录，所以手改永远不会被吸收。把记录同步成磁盘上的任何内容，会让 `uds check` 从此再也报不出任何被改过的标准。
+- **备份不含 skills，而且没有任何东西说出这件事。** skill 是目录，而备份对它们调用 `copyFileSync`，那在每个平台都会抛（本机两个文件系统实测皆 ENOTSUP——**不是临时目录的产物**）。失败被藏了两层：执行器只在**一个都没成功**时中止，于是单一一次成功掩盖了任意数量的失败；备份 manifest 没有 errors 字段，使得「129 个计划路径备了 74 个」在磁盘上与完整备份无从分辨。修正前于真实 repo 测量：备份 manifest 记录 74 个路径、而计划有 129 个动作，其中 **55 个 skill 目录一个都不在里面**——**一个不涵盖它即将覆写的最大一块的回复点**。现在目录递归复制、manifest 记录 `failedToBackUp` 与 `coverage: {planned, backedUp, failed}`，且**任一**备份失败即中止整次执行：拒绝覆写一个没能先复制起来的文件，正是备份的用途。
+
+### 变更
+
+- **无条件重装的折叠保留，措辞放宽。** commands 仍然没有内容比对，所以那个分支是活的。它没有跟着 skill 那一半一起移除，因为**一个静默停止套用的折叠，与一个本来就没东西可折的计划，长得一模一样**。
+
 ## [6.7.2] - 2026-08-18
 
 ### 修正

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

@@ -15,7 +15,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 6.7.2 | **发布日期**: 2026-08-18 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.7.4 | **发布日期**: 2026-08-18 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 

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

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

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

@@ -1,7 +1,7 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.7.2
-translation_version: 6.7.2
+source_version: 6.7.4
+translation_version: 6.7.4
 last_synced: 2026-08-18
 status: current
 ---
@@ -17,6 +17,28 @@ status: current
 
 ## [Unreleased]
 
+## [6.7.4] - 2026-08-18
+
+### 修正
+
+- **6.7.3 讓 `uds check` 每個 repo 報出 52 個不存在的「遺失」檔案。** 6.7.3 的兩個改動要**同時在場**才會互相作用：R1 給了 skill 內容雜湊，使它們第一次走進 `unchanged` 分支；而 R6b 會把那個分支的項目收進 `manifest.fileHashes`。那張表是用 `isFile()` 驗證的，而 skill 是目錄，於是每一個都被報成遺失。**沒有任何東西被刪除——錯的是紀錄不是磁碟**（已驗證：59 個 skill 目錄與其內容完好）。`verifiedPristine` 現在限縮於檔案類別；而且**修好寫入端不會讓已經寫進去的東西消失**，所以 `uds update` 也會清掉 `fileHashes` 裡的 `.claude/skills/` 與 `.claude/commands/` 鍵——**一個壞掉的鍵不會有第二次機會被造訪**，因為磁碟上沒有任何東西對應它。
+- **commands 也改為內容比對（XSPEC-382 R7）。** R1 只涵蓋 skills，把 commands 留在 `hash: null`，於是無條件重裝的分支對它們仍然活著。與 skills 同一個形狀：`resolveCommandContent(name, agent, locale)` 說明一次安裝會包含什麼（locale 選擇＋英文回退，加上逐 agent 的轉換），安裝器寫它、計畫器雜湊它。
+- **裝了 locale 版的人，拿到的 SKILL.md 指向從來不會被安裝的檔案。** locale 包不是英文來源的完整複本——實測 **zh-TW 59 個中有 4 個、zh-CN 59 個中有 5 個**缺少英文有出貨的檔——而安裝器把 locale 目錄整包換上去，於是那些伴隨檔根本沒被寫入。其中兩個缺口**是被引用的**：zh-TW 的 `dev-workflow-guide/SKILL.md` 引用 `workflow-phases.md` 三次、`testing-guide/SKILL.md` 引用 `test-skeleton-templates.md` 三次。**回退改為逐檔而非逐 skill**——locale 有就用 locale 的，沒有就用英文的。
+- **UDS 不出貨的檔案，不再讓一個 skill 永遠停在「已變更」。** 安裝一個 skill 現在會移除其目錄下**解析結果沒有指名**的頂層檔案（實地發現：`deploy-assistant/guide.md`，它不在任何 UDS skills 樹裡，而且從來就不在）。範圍由同一個 provenance 判準界定，也就是讓採用者自己的 skill 目錄不進入此處任何路徑的那一個——**已驗證手寫的 skill 目錄與其額外檔案在 `--force` 之後完好無損**——子目錄一律不動，因為安裝器從來沒有寫過它們。
+
+## [6.7.3] - 2026-08-18
+
+### 修正
+
+- **skill 改為內容比對，升級不再重印 55 列毫無意義的變更。** diff 兩端都硬寫 `hash: null`，於是每個 skill 都是無條件重裝。**兩端各算來源目錄的雜湊行不通**——安裝不是逐位元複製：locale 版的 `SKILL.md` 會被併入英文 frontmatter（`brainstorm-assistant`：23,753 bytes 的 zh-TW 來源變成 23,866 bytes 的安裝結果）、來源是執行期依 locale 逐 skill 選擇並可回退英文、子目錄被略過。照那樣做，55 個全都會顯示為內容**變更**，每次升級皆然——**與真的變更無從分辨，比那個已知的無訊號更糟**。改為只有一個函式：`resolveSkillFiles(name, locale)` 說明一次安裝會包含什麼，**安裝器寫它、計畫器雜湊它**，兩者因此不可能漂移。與真實已安裝的專案對帳：110 個檔逐位元相符、0 個不符，18 個採用者自寫的 skill 正確地解不出來。actual 端**只對 UDS 管理的目錄計算雜湊**；採用者自己的 skill 永遠不被比較、也永遠不會變成刪除候選。真實升級中的 `Update (57)` 現在是 `Update: 0, Unchanged: 127`。
+- **`uds check --restore` 對 72 個受追蹤標準中的 64 個無法還原。** 它拿 `entry.endsWith(fileName)` 去比對 `manifest.standards`，而那些條目**自 3.4.0 起是 ID（`commit-message`）而非路徑**——這個比較永遠不可能為真。會動的那 8 個是仍存路徑格式的 `options/`，**這正是失敗從來看起來不像全面失敗的原因**；其餘一律回報「Could not determine source」。同一段 ID→來源的解析在這個檔案裡已經存在兩次，而這一處從來沒拿到過，所以修法是在 `registry.js` 收斂出一支解析器，**與它必須一致的那支檔名解析器配對**。
+- **一個逐位元正確的標準，沒辦法停止被報成「已修改」。** actual state 是從磁碟算雜湊的，所以與上游相符的檔案被歸為 `unchanged`、不產生動作、也永遠不會被重新雜湊——而 reconciliation 在計畫為空時早退出、連 manifest 都不寫。**沒有回頭路。** diff 現在回報它**證明過**與上游相同的那些檔案，並在早退出之前補正記錄。**刻意做得很窄**：只有在證明磁碟與 desired 相符之後才記錄，所以手改永遠不會被吸收。把記錄同步成磁碟上的任何內容，會讓 `uds check` 從此再也報不出任何被改過的標準。
+- **備份不含 skills，而且沒有任何東西說出這件事。** skill 是目錄，而備份對它們呼叫 `copyFileSync`，那在每個平台都會拋（本機兩個檔案系統實測皆 ENOTSUP——**不是暫存目錄的產物**）。失敗被藏了兩層：執行器只在**一個都沒成功**時中止，於是單一一次成功掩蓋了任意數量的失敗；備份 manifest 沒有 errors 欄位，使得「129 個計畫路徑備了 74 個」在磁碟上與完整備份無從分辨。修正前於真實 repo 量測：備份 manifest 記錄 74 個路徑、而計畫有 129 個動作，其中 **55 個 skill 目錄一個都不在裡面**——**一個不涵蓋它即將覆寫的最大一塊的回復點**。現在目錄遞迴複製、manifest 記錄 `failedToBackUp` 與 `coverage: {planned, backedUp, failed}`，且**任一**備份失敗即中止整次執行：拒絕覆寫一個沒能先複製起來的檔案，正是備份的用途。
+
+### 變更
+
+- **無條件重裝的摺疊保留，措辭放寬。** commands 仍然沒有內容比對，所以那個分支是活的。它沒有跟著 skill 那一半一起移除，因為**一個靜默停止套用的摺疊，與一個本來就沒東西可摺的計畫，長得一模一樣**。
+
 ## [6.7.2] - 2026-08-18
 
 ### 修正

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

@@ -15,7 +15,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 6.7.2 | **發布日期**: 2026-08-18 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.7.4 | **發布日期**: 2026-08-18 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
 
 語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流，確保不同技術堆疊之間的一致性、品質和可維護性。
 

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

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

package/package.json

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

package/src/commands/check.js

@@ -7,7 +7,7 @@ import { execSync } from 'child_process';
 import { readManifest, writeManifest, isInitialized, copyStandard, copyIntegration } from '../utils/copier.js';
 import {
   getAllStandards,
-  getRepositoryInfo, resolveStandardFilename } from '../utils/registry.js';
+  getRepositoryInfo, resolveStandardFilename, resolveStandardSourcePath } from '../utils/registry.js';
 import {
   computeFileHash,
   compareFileHash,
@@ -749,11 +749,20 @@ function removeFromManifest(manifest, relativePath) {
  */
 export function getSourcePathFromRelative(manifest, relativePath) {
   const fileName = basename(relativePath);
+  const format = manifest.format || 'ai';
 
-  // Check standards
+  // Check standards.
+  //
+  // Compare the RESOLVED filename, not the raw entry. Manifests have stored IDs
+  // (`commit-message`) rather than paths since 3.4.0, and `'commit-message'
+  // .endsWith('commit-message.ai.yaml')` is false for every one of them —
+  // so this returned null for 64 of 72 tracked standards and `uds check
+  // --restore` reported "Could not determine source" for all of them. The eight
+  // that worked were the `options/` entries, still stored as paths, which is
+  // why the failure never looked total. (XSPEC-382 R6)
   for (const std of manifest.standards) {
-    if (std.endsWith(fileName)) {
-      return std;
+    if (resolveStandardFilename(std, format) === fileName) {
+      return resolveStandardSourcePath(std, format);
     }
   }
 

package/src/reconciler/actual-state-scanner.js

@@ -8,6 +8,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { createHash } from 'crypto';
 import { join, relative } from 'path';
 import { readManifest } from '../core/manifest.js';
 import { computeFileHash, computeIntegrationBlockHash } from '../utils/hasher.js';
@@ -312,6 +313,45 @@ function shippedCommandNames() {
 // nothing on disk distinguishes them from the adopter's own work. Leaving a few
 // stale directories with a warning is a better way to fail than deleting files
 // somebody hand-wrote.
+/**
+ * Hash an installed skill directory the way the desired side hashes a resolved
+ * one: top-level files only, sorted by name, name and content both fed in.
+ *
+ * Written against `computeSkillContentHash`'s format rather than calling it,
+ * because the input here is paths on disk and there is nothing gained by
+ * materialising a second array first. The format is the contract; if it changes
+ * in one place and not the other every skill reports as changed, which the
+ * paired tests in `skill-content-hash.test.js` exist to catch.
+ */
+function hashInstalledSkillDir(dirPath) {
+  let entries;
+  try {
+    entries = readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const names = entries.filter((e) => e.isFile()).map((e) => e.name).sort();
+  if (names.length === 0) return null;
+
+  const h = createHash('sha256');
+  for (const name of names) {
+    let content;
+    try {
+      content = readFileSync(join(dirPath, name), 'utf-8');
+    } catch {
+      // Unreadable file → no trustworthy hash. Returning a partial one would
+      // claim the directory matches upstream when part of it was never read.
+      return null;
+    }
+    h.update(name);
+    h.update('\0');
+    h.update(content);
+    h.update('\0');
+  }
+  return `sha256:${h.digest('hex')}`;
+}
+
 function isUdsProvenance(skillName) {
   return sourceEntryNames().has(skillName);
 }
@@ -335,9 +375,18 @@ function scanSkills(state, projectPath, manifest) {
         ? getRelativePath(projectPath, join(skillsDir, skillName))
         : join(skillsDir, skillName);
 
+      // Content hash of what is actually installed, over the same file set and
+      // the same algorithm the desired side uses (XSPEC-382 R1).
+      //
+      // Computed ONLY for UDS-managed skills. An adopter's own skill has no
+      // desired counterpart, so a hash for it could only ever feed a comparison
+      // against nothing — and this scanner has already been the site of a
+      // defect that proposed deleting fourteen of dev-platform's hand-written
+      // skills. It does not get a second chance to reason about them.
+      const udsManaged = isUdsProvenance(skillName);
       state.skills.set(key, {
         relativePath: relPath,
-        hash: null,  // Directory-level hashes tracked in manifest.skillHashes
+        hash: udsManaged ? hashInstalledSkillDir(join(skillsDir, skillName)) : null,
         size: null,
         category: 'skill',
         sourcePath: null,
@@ -350,7 +399,7 @@ function scanSkills(state, projectPath, manifest) {
           // the skills folder used to be assumed UDS-managed, so a plan for a repo
           // with hand-written skills proposed deleting them: dev-platform's would
           // have removed fourteen. (XSPEC-343 R2)
-          udsManaged: isUdsProvenance(skillName)
+          udsManaged
         }
       });
     }
@@ -385,9 +434,26 @@ function scanCommands(state, projectPath, manifest) {
         ? getRelativePath(projectPath, join(cmdsDir, entry.name))
         : join(cmdsDir, entry.name);
 
+      // Content hash of the installed file, for UDS-managed commands only —
+      // same reasoning as skills: an adopter's own command has no desired
+      // counterpart to compare against. (XSPEC-382 R7)
+      const cmdUdsManaged = shippedCommandNames().has(cmdName);
+      let cmdHash = null;
+      if (cmdUdsManaged) {
+        try {
+          cmdHash = `sha256:${createHash('sha256')
+            .update(readFileSync(join(cmdsDir, entry.name), 'utf-8'))
+            .digest('hex')}`;
+        } catch {
+          // Unreadable → no hash. A partial answer would claim a match that
+          // was never checked.
+          cmdHash = null;
+        }
+      }
+
       state.commands.set(key, {
         relativePath: relPath,
-        hash: null,
+        hash: cmdHash,
         size: null,
         category: 'command',
         sourcePath: null,
@@ -396,7 +462,7 @@ function scanCommands(state, projectPath, manifest) {
           level,
           commandName: cmdName,
           scanned: true,
-          udsManaged: shippedCommandNames().has(cmdName)
+          udsManaged: cmdUdsManaged
         }
       });
     }

package/src/reconciler/backup-manager.js

@@ -17,6 +17,8 @@ import {
   existsSync,
   mkdirSync,
   copyFileSync,
+  cpSync,
+  statSync,
   readFileSync,
   writeFileSync,
   readdirSync,
@@ -86,7 +88,15 @@ export function createBackup(projectPath, plan) {
     errors.push(`Failed to write backup .gitignore: ${err.message}`);
   }
 
-  // Backup each file
+  // Backup each entry.
+  //
+  // Skills are DIRECTORIES (`.claude/skills/<name>`), and `copyFileSync` on a
+  // directory throws — ENOTSUP on macOS, EISDIR on Linux. Every skill in every
+  // plan failed here, and the failures went nowhere (see the partial-failure
+  // note below). Measured on a real repo before the fix: a vibeops backup
+  // recorded 74 files for a plan of 129 actions, with **0 of the 55 skill
+  // directories** among them — a rollback point that did not cover the largest
+  // part of what was about to be overwritten. (XSPEC-382 R6)
   for (const relativePath of filesToBackup) {
     const sourcePath = join(projectPath, relativePath);
     if (!existsSync(sourcePath)) continue;
@@ -94,7 +104,11 @@ export function createBackup(projectPath, plan) {
     const targetPath = join(backupDir, relativePath);
     try {
       mkdirSync(dirname(targetPath), { recursive: true });
-      copyFileSync(sourcePath, targetPath);
+      if (statSync(sourcePath).isDirectory()) {
+        cpSync(sourcePath, targetPath, { recursive: true });
+      } else {
+        copyFileSync(sourcePath, targetPath);
+      }
       backedUp.push(relativePath);
     } catch (err) {
       errors.push(`Failed to backup ${relativePath}: ${err.message}`);
@@ -116,6 +130,19 @@ export function createBackup(projectPath, plan) {
       }))
     },
     backedUpFiles: backedUp,
+    // What could NOT be backed up, and the resulting gap.
+    //
+    // The manifest previously recorded only successes, with no errors field at
+    // all — so a backup covering 74 of 129 planned paths was indistinguishable
+    // on disk from one covering all of them. Anyone reaching for this directory
+    // is reaching for it because something went wrong; it has to say what it
+    // does not contain. (XSPEC-382 R6)
+    failedToBackUp: errors.slice(),
+    coverage: {
+      planned: filesToBackup.length,
+      backedUp: backedUp.length,
+      failed: filesToBackup.length - backedUp.length
+    },
     projectPath
   };
 

package/src/reconciler/desired-state-calculator.js

@@ -24,7 +24,11 @@ import {
 } from '../config/ai-agent-paths.js';
 import {
   getAvailableSkillNames,
-  getAvailableCommandNames
+  getAvailableCommandNames,
+  resolveSkillFiles,
+  computeSkillContentHash,
+  resolveCommandContent,
+  computeCommandContentHash
 } from '../utils/skills-installer.js';
 import { MARKETPLACE_NAMES_SENTINEL } from '../core/manifest.js';
 
@@ -328,6 +332,9 @@ function calculateSkills(state, projectPath, manifest) {
   }
 
   const installations = skills.installations || [];
+  // The locale the project installed with; skills fall back to English per skill
+  // when a locale variant is missing, which `resolveSkillFiles` handles.
+  const skillsLocale = skills.locale || 'en';
 
   for (const installation of installations) {
     const { agent, level } = installation;
@@ -341,9 +348,19 @@ function calculateSkills(state, projectPath, manifest) {
         : null;
 
       if (relativeBase) {
+        // Content hash of what installing this skill WOULD produce.
+        //
+        // Asked of `resolveSkillFiles` — the same function the installer writes
+        // from — so the two answers cannot drift. Hashing the source directory
+        // instead does not work: installing is not a verbatim copy (locale
+        // selection, English frontmatter merged into localized SKILL.md,
+        // subdirectories skipped), and a planner that computes it differently
+        // from the installer reports every skill as changed on every upgrade.
+        // (XSPEC-382 R1)
+        const resolved = resolveSkillFiles(skillName, skillsLocale);
         state.skills.set(`skill:${agent}:${level}:${skillName}`, {
           relativePath: relativeBase,
-          hash: null,  // Skill hashes are directory-level, tracked separately
+          hash: resolved.error ? null : computeSkillContentHash(resolved.files),
           size: null,
           category: 'skill',
           sourcePath: null,
@@ -364,6 +381,9 @@ function calculateSkills(state, projectPath, manifest) {
 function calculateCommands(state, projectPath, manifest) {
   const commands = manifest.commands;
   if (!commands || !commands.installed) return;
+  // Commands are installed alongside skills and share their locale; fall back
+  // to the skills locale, then English.
+  const commandsLocale = commands.locale || manifest.skills?.locale || 'en';
 
   const commandNames = getAvailableCommandNames();
   if (commandNames.length === 0) {
@@ -389,9 +409,12 @@ function calculateCommands(state, projectPath, manifest) {
         : null;
 
       if (relativeBase) {
+        // Content hash of what installing this command WOULD produce, from the
+        // same function the installer writes from. (XSPEC-382 R7)
+        const resolvedCmd = resolveCommandContent(commandName, agent, commandsLocale);
         state.commands.set(`command:${agent}:${level}:${commandName}`, {
           relativePath: relativeBase,
-          hash: null,
+          hash: resolvedCmd.error ? null : computeCommandContentHash(resolvedCmd.content),
           size: null,
           category: 'command',
           sourcePath: null,

package/src/reconciler/diff-engine.js

@@ -56,16 +56,30 @@ export function computeDiff(desired, actual, options = {}) {
   const warnings = [];
   const summary = { create: 0, update: 0, delete: 0, unchanged: 0, migrate_block: 0 };
 
+  // Files whose content on disk is byte-identical to what UDS ships (XSPEC-382 R6).
+  //
+  // These produce no action — there is nothing to install. They are collected
+  // so the caller can bring `manifest.fileHashes` back in line with a disk that
+  // is already correct. Without this there is no path back: a stale recorded
+  // hash makes `uds check` report a pristine file as modified forever, because
+  // an unchanged file is never re-hashed and the reconciler returns early when
+  // the action list is empty.
+  //
+  // Only ever recorded when disk === desired. Syncing the record to whatever is
+  // on disk would silently absorb a hand edit and empty the integrity check of
+  // its purpose — it exists to tell you somebody changed a standard.
+  const verifiedPristine = [];
+
   // Diff standards
   diffCategory(
     desired.standards, actual.standards,
-    'standard', actions, warnings, summary, force
+    'standard', actions, warnings, summary, force, verifiedPristine
   );
 
   // Diff options
   diffCategory(
     desired.options, actual.options,
-    'option', actions, warnings, summary, force
+    'option', actions, warnings, summary, force, verifiedPristine
   );
 
   // Diff integrations (special: use migrate_block)
@@ -77,22 +91,22 @@ export function computeDiff(desired, actual, options = {}) {
   // Diff skills
   diffCategory(
     desired.skills, actual.skills,
-    'skill', actions, warnings, summary, force
+    'skill', actions, warnings, summary, force, verifiedPristine
   );
 
   // Diff commands
   diffCategory(
     desired.commands, actual.commands,
-    'command', actions, warnings, summary, force
+    'command', actions, warnings, summary, force, verifiedPristine
   );
 
-  return { actions, summary, warnings };
+  return { actions, summary, warnings, verifiedPristine };
 }
 
 /**
  * Diff a single category (standards, options, skills, commands).
  */
-function diffCategory(desiredMap, actualMap, category, actions, warnings, summary, force) {
+function diffCategory(desiredMap, actualMap, category, actions, warnings, summary, force, verifiedPristine = []) {
   // Check desired entries against actual
   for (const [key, desiredEntry] of desiredMap) {
     const actualEntry = actualMap.get(key);
@@ -160,8 +174,31 @@ function diffCategory(desiredMap, actualMap, category, actions, warnings, summar
         summary.unchanged++;
       }
     } else {
-      // Hashes match → unchanged
+      // Hashes match → unchanged.
+      //
+      // The file is byte-identical to what UDS ships, so there is nothing to
+      // install — but the manifest's recorded hash may still be stale (XSPEC-382
+      // R6: a pre-reconciler manifest written back over the reconciler's output
+      // reverted `fileHashes` along with `upstream.version`). Recording it here
+      // is safe precisely because we got here by proving disk === desired.
       summary.unchanged++;
+      // Only file-backed categories. `manifest.fileHashes` is a FILE map that
+      // `uds check` validates with a `isFile()` test; skills are directories and
+      // commands live in `commandHashes`, so recording either there makes the
+      // integrity check report them as missing.
+      //
+      // This branch was unreachable for skills until R1 gave them hashes, so
+      // the two changes shipped together and the fault only appeared once both
+      // were in: 6.7.3 put 52 skill directory paths into `fileHashes` in every
+      // adopter repo and `uds check` reported 52 phantom missing files. Nothing
+      // was deleted — the record was wrong, not the disk. (XSPEC-382 R7)
+      if (actualEntry.hash && (category === 'standard' || category === 'option')) {
+        verifiedPristine.push({
+          path: desiredEntry.relativePath,
+          hash: actualEntry.hash,
+          size: actualEntry.size ?? null
+        });
+      }
     }
   }
 
@@ -369,11 +406,17 @@ export function formatPlan(plan) {
   if (grouped.update.length > 0) {
     // XSPEC-382 R3 — collapse the unconditional reinstalls.
     //
-    // Every skill is always an `update` because no content comparison exists for
-    // them (see the `hash: null` on both sides of the diff, and R1). On a real
-    // upgrade that produced `Update (57)` where 55 rows carried one identical
-    // reason and only 2 were actual changes — the two a reviewer needs to see,
-    // buried under fifty-five that say nothing about this upgrade.
+    // On a real upgrade this produced `Update (57)` where 55 rows carried one
+    // identical reason and only 2 were actual changes — the two a reviewer
+    // needs to see, buried under fifty-five that say nothing about this
+    // upgrade.
+    //
+    // R1 has since given SKILLS a content comparison, so those rows are gone;
+    // the same upgrade now reports `Update: 0, Unchanged: 127`. COMMANDS still
+    // hardcode `hash: null` on both sides, so this branch is live and still
+    // needed. It is deliberately not deleted along with the skills half: a
+    // collapse that silently stops applying looks exactly like a plan that
+    // never had anything to collapse.
     //
     // Collapsed, NOT hidden: the count is printed. A capped list that does not
     // say it was capped reads as "these are all of them", which is the failure
@@ -388,7 +431,7 @@ export function formatPlan(plan) {
     }
     if (collapsed > 0) {
       lines.push(
-        `  i ${collapsed} UDS-managed skill/command director${collapsed === 1 ? 'y' : 'ies'} reinstalled unconditionally — no content comparison is implemented for them (XSPEC-382)`
+        `  i ${collapsed} UDS-managed item${collapsed === 1 ? '' : 's'} reinstalled unconditionally — no content comparison is implemented for them (XSPEC-382 R1 covers skills; commands do not have one yet)`
       );
     }
     lines.push('');

package/src/reconciler/index.js

@@ -21,7 +21,7 @@
  *   const rollbackResult = rollbackLast(projectPath);
  */
 
-import { readManifest, needsMigration } from '../core/manifest.js';
+import { readManifest, writeManifest, needsMigration } from '../core/manifest.js';
 import { migrateAndBackfill } from './manifest-migrator.js';
 import { calculateDesiredState } from './desired-state-calculator.js';
 import { scanActualState, legacyDiscovery } from './actual-state-scanner.js';
@@ -45,6 +45,58 @@ import { rollback } from './backup-manager.js';
  *   errors: string[]
  * }>}
  */
+/**
+ * Bring `manifest.fileHashes` in line with files proved byte-identical to what
+ * UDS ships (XSPEC-382 R6).
+ *
+ * Returns the manifest plus a count of entries corrected, or null when nothing
+ * needed correcting — so the caller can skip a pointless write.
+ *
+ * Deliberately narrow. It only ever writes a hash the reconciler computed from
+ * disk AFTER proving that disk matches the desired upstream content, so it
+ * cannot absorb a hand edit. Widening it to "sync the record to disk" would
+ * make `uds check` incapable of ever reporting a modified standard again, which
+ * is the one thing that check exists to do.
+ */
+function reconcileFileHashes(manifest, verifiedPristine) {
+  const current = manifest.fileHashes || {};
+
+  // Drop entries 6.7.3 wrote here that do not belong: skill directories and
+  // command files are tracked in `skillHashes` / `commandHashes`, and
+  // `uds check` validates everything in `fileHashes` with an `isFile()` test,
+  // so those entries surfaced as phantom "missing" reports — 52 of them per
+  // adopter repo. Fixing the writer does not remove what it already wrote, and
+  // there is no other path that would: a bad key is never revisited because
+  // nothing on disk corresponds to it. (XSPEC-382 R7)
+  const stale = Object.keys(current).filter(
+    (k) => k.startsWith('.claude/skills/') || k.startsWith('.claude/commands/')
+  );
+
+  if (!verifiedPristine?.length && stale.length === 0) return null;
+
+  const kept = Object.fromEntries(Object.entries(current).filter(([k]) => !stale.includes(k)));
+  const corrected = {};
+  let count = stale.length;
+
+  for (const entry of verifiedPristine || []) {
+    const key = entry.path.replace(/\\/g, '/');
+    const recorded = kept[key];
+    if (recorded && recorded.hash === entry.hash && recorded.size === entry.size) continue;
+    corrected[key] = {
+      hash: entry.hash,
+      size: entry.size,
+      installedAt: new Date().toISOString()
+    };
+    count++;
+  }
+
+  if (count === 0) return null;
+  return {
+    manifest: { ...manifest, fileHashes: { ...kept, ...corrected } },
+    count
+  };
+}
+
 export async function reconcile(projectPath, options = {}) {
   const { force = false, backup = true, onAction } = options;
   const errors = [];
@@ -71,18 +123,31 @@ export async function reconcile(projectPath, options = {}) {
   // Step 4: Compute diff
   const reconciliationPlan = computeDiff(desired, actual, { force });
 
+  // Step 4b: correct any stale recorded hashes for files already pristine.
+  //
+  // This runs BEFORE the empty-plan early return on purpose. A manifest whose
+  // only problem is a stale hash produces zero actions, and the old early
+  // return meant it was never written — so `uds check` reported a byte-perfect
+  // file as modified with no path back through normal use. (XSPEC-382 R6)
+  // `manifest` above is destructured const, so carry the corrected copy in its
+  // own binding rather than reassigning it.
+  const hashFix = reconcileFileHashes(manifest, reconciliationPlan.verifiedPristine);
+  const effectiveManifest = hashFix ? hashFix.manifest : manifest;
+  if (hashFix) writeManifest(effectiveManifest, projectPath);
+
   // Step 5: Execute plan
   if (reconciliationPlan.actions.length === 0) {
     return {
       success: true,
       plan: reconciliationPlan,
       execution: null,
-      manifest,
+      manifest: effectiveManifest,
+      hashesCorrected: hashFix?.count ?? 0,
       errors
     };
   }
 
-  const execution = await executePlan(projectPath, reconciliationPlan, manifest, {
+  const execution = await executePlan(projectPath, reconciliationPlan, effectiveManifest, {
     backup,
     onAction
   });
@@ -92,6 +157,7 @@ export async function reconcile(projectPath, options = {}) {
     plan: reconciliationPlan,
     execution,
     manifest: execution.updatedManifest,
+    hashesCorrected: hashFix?.count ?? 0,
     errors: [
       ...errors,
       ...execution.results.filter(r => !r.success).map(r => r.error || 'Unknown error')

package/src/reconciler/plan-executor.js

@@ -71,8 +71,19 @@ export async function executePlan(projectPath, plan, manifest, options = {}) {
   // Create backup
   if (backup && !dryRun) {
     const backupResult = createBackup(projectPath, plan);
-    if (backupResult.errors.length > 0 && backupResult.backedUp.length === 0) {
-      // Backup completely failed — abort
+    // Abort if ANY planned path could not be backed up — not only if every one
+    // failed.
+    //
+    // The old condition required `backedUp.length === 0`, so a run that backed
+    // up 74 paths and failed on 55 proceeded silently and overwrote all 55 with
+    // no rollback point. One success was enough to hide any number of failures:
+    // the same aggregate-masks-partial-failure shape this repo keeps finding.
+    // Those 55 were the skill directories, which failed on every platform
+    // because the backup called `copyFileSync` on a directory. With that fixed
+    // this branch should be rare — and when it does fire, refusing to overwrite
+    // a file we could not copy first is the whole point of taking a backup.
+    // (XSPEC-382 R6)
+    if (backupResult.errors.length > 0) {
       return {
         success: false,
         backupId: null,

package/src/utils/registry.js

@@ -273,6 +273,37 @@ export function resolveSelectedOptionSources(manifestOptions, format = 'ai') {
  * @param {string} format - Content format: 'ai' or 'human'
  * @returns {string|null} Basename as installed, or null if unresolvable
  */
+/**
+ * Resolve a manifest `standards` entry to the source path it was installed from.
+ *
+ * Manifests have stored IDs (`commit-message`) rather than paths since 3.4.0,
+ * and four places in the CLI needed to turn one back into a path. Three of them
+ * grew their own copy of the lookup; the fourth — the one `uds check --restore`
+ * depends on — never did, and matched `entry.endsWith(fileName)` instead. That
+ * cannot match an ID, so restore failed for **64 of 72** tracked standards with
+ * "Could not determine source". Only the eight `options/` entries worked,
+ * because those are still stored as paths. (XSPEC-382 R6)
+ *
+ * Paired with `resolveStandardFilename` on purpose: same input handling, same
+ * registry lookup, one returns the path and the other its basename. Two
+ * separately-written resolvers would answer differently the first time an entry
+ * form changed, and neither would be obviously wrong.
+ *
+ * @param {string} entry - Manifest standards entry: an ID or a legacy path
+ * @param {string} format - 'ai' or 'human'
+ * @returns {string|null} Source path, or null when unresolvable
+ */
+export function resolveStandardSourcePath(entry, format = 'ai') {
+  if (typeof entry !== 'string' || entry.length === 0) return null;
+
+  // A path (option files, and legacy pre-3.4.0 manifests) already names itself.
+  if (entry.includes('/') || entry.includes('.')) return entry;
+
+  const found = getAllStandards().find((s) => s.id === entry);
+  if (!found) return null;
+  return getStandardSource(found, format) || null;
+}
+
 export function resolveStandardFilename(entry, format = 'ai') {
   if (typeof entry !== 'string' || entry.length === 0) return null;
 

package/src/utils/skills-installer.js

@@ -9,6 +9,7 @@
 
 import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync, statSync, rmSync, unlinkSync } from 'fs';
 import { dirname, join, basename } from 'path';
+import { createHash } from 'crypto';
 import { fileURLToPath } from 'url';
 import {
   getAgentConfig,
@@ -399,33 +400,161 @@ function mergeSkillFrontmatter(enSourceDir, targetDir) {
  * @param {string} locale - Locale for skill content (default: 'en')
  * @returns {{success: boolean, skillName: string, path?: string, error?: string, fallbackToEn?: boolean}} Result
  */
-function installSingleSkill(skillName, targetBaseDir, locale = 'en') {
+/**
+ * Resolve what installing a skill would put on disk, without writing anything.
+ *
+ * This is THE definition of a skill's installed content, and it exists as one
+ * function because both the installer and the reconciler need that answer.
+ * XSPEC-382 R1 originally proposed hashing the source directory on both sides
+ * and letting the existing comparison work. Measurement killed that: installing
+ * is not a verbatim copy. Three things sit in between, any one of them fatal to
+ * a source-directory hash —
+ *
+ *   1. a localized SKILL.md gets English frontmatter fields merged in, so the
+ *      installed file matches no source file (measured: brainstorm-assistant is
+ *      23,866 bytes installed against a 23,753-byte zh-TW source);
+ *   2. the source directory is chosen at runtime by locale with fallback to
+ *      English per skill, so there is no single path to hash;
+ *   3. subdirectories are skipped, making the install a strict subset.
+ *
+ * The alternative was a second copy of this logic inside the planner. That is
+ * the arrangement this file has already been bitten by twice; two copies answer
+ * differently the first time one changes, and a planner that disagrees with the
+ * installer reports every skill as changed on every upgrade — worse than the
+ * no-signal it replaced, because a false signal is indistinguishable from a
+ * real one.
+ *
+ * All 514 installable files are UTF-8 text (508 .md, 5 .yaml, 1 .json), checked
+ * by decoding every one of them, so reading content as a string is lossless.
+ *
+ * @param {string} skillName
+ * @param {string} locale
+ * @returns {{files: Array<{name: string, content: string}>, fallbackToEn: boolean, error: string|null}}
+ */
+export function resolveSkillFiles(skillName, locale = 'en') {
   const enSourceDir = join(SKILLS_LOCAL_DIR, skillName);
-  const targetDir = join(targetBaseDir, skillName);
 
-  // Determine the actual source directory based on locale
   let sourceDir = enSourceDir;
   let needsFrontmatterMerge = false;
   let fallbackToEn = false;
 
   if (isLocalizedLocale(locale)) {
-    const localizedDir = getLocalizedSkillsSourceDir(locale);
-    const localizedSkillDir = join(localizedDir, skillName);
+    const localizedSkillDir = join(getLocalizedSkillsSourceDir(locale), skillName);
     if (existsSync(localizedSkillDir)) {
       sourceDir = localizedSkillDir;
       needsFrontmatterMerge = true;
     } else {
-      // Locale requested but missing for this skill — fall back to English source.
-      // Flag the result so the caller can aggregate a WARN.
       fallbackToEn = true;
     }
   }
 
   if (!existsSync(sourceDir)) {
+    return { files: [], fallbackToEn, error: `Skill not found: ${skillName}` };
+  }
+
+  // Per-FILE fallback to English, not per-skill.
+  //
+  // A locale pack that has SKILL.md but not its companion files used to install
+  // just the SKILL.md, leaving the companions uninstalled entirely. Measured:
+  // 4 of 59 localized skills in zh-TW and 5 of 59 in zh-CN are short of the
+  // English source, and two of those gaps are REFERENCED — the zh-TW
+  // `dev-workflow-guide/SKILL.md` points at `workflow-phases.md` three times
+  // and `testing-guide/SKILL.md` at `test-skeleton-templates.md` three times,
+  // neither of which the locale pack ships. Those installs shipped a document
+  // pointing at files that were never going to be there.
+  //
+  // Taking the union — locale file where it exists, English where it does not —
+  // is also what makes the content comparison usable: without it those skills
+  // would report as changed on every upgrade forever. (XSPEC-382 R7)
+  const names = new Map(); // fileName -> absolute source path
+  const collect = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const fileName of readdirSync(dir)) {
+      const sourcePath = join(dir, fileName);
+      // Subdirectories are skipped — matching what the installer has always done.
+      if (statSync(sourcePath).isDirectory()) continue;
+      if (!names.has(fileName)) names.set(fileName, sourcePath);
+    }
+  };
+  collect(sourceDir);            // locale first, so it wins
+  if (sourceDir !== enSourceDir) collect(enSourceDir);
+
+  const files = [];
+  for (const [name, sourcePath] of names) {
+    files.push({ name, content: readFileSync(sourcePath, 'utf-8') });
+  }
+
+  if (needsFrontmatterMerge) {
+    const skill = files.find((f) => f.name === 'SKILL.md');
+    if (skill) {
+      const merged = mergeFrontmatterContent(enSourceDir, skill.content);
+      if (merged !== null) skill.content = merged;
+    }
+  }
+
+  // Sorted so a hash over this list depends on content, not on directory order.
+  files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { files, fallbackToEn, error: null };
+}
+
+/**
+ * Content hash of a resolved skill, over names and contents.
+ *
+ * Names are included: two skills with the same bodies under different filenames
+ * are different installs, and a hash over contents alone would call a rename
+ * "unchanged".
+ *
+ * @param {Array<{name: string, content: string}>} files
+ * @returns {string|null} `sha256:<hex>`, or null for an empty resolution
+ */
+export function computeSkillContentHash(files) {
+  if (!files?.length) return null;
+  const h = createHash('sha256');
+  for (const f of files) {
+    h.update(f.name);
+    h.update('\0');
+    h.update(f.content);
+    h.update('\0');
+  }
+  return `sha256:${h.digest('hex')}`;
+}
+
+/**
+ * The in-memory half of `mergeSkillFrontmatter`, so resolution and installation
+ * agree by construction rather than by both being kept up to date.
+ *
+ * @returns {string|null} merged content, or null when there is nothing to merge
+ */
+function mergeFrontmatterContent(enSourceDir, targetContent) {
+  const enSkillPath = join(enSourceDir, 'SKILL.md');
+  if (!existsSync(enSkillPath)) return null;
+
+  const enParsed = parseFrontmatter(readFileSync(enSkillPath, 'utf-8'));
+  if (!enParsed) return null;
+
+  const REQUIRED_FIELDS = ['name', 'allowed-tools', 'scope', 'argument-hint', 'disable-model-invocation'];
+  const fieldsToMerge = {};
+  for (const field of REQUIRED_FIELDS) {
+    if (enParsed.frontmatter[field] !== undefined) {
+      fieldsToMerge[field] = enParsed.frontmatter[field];
+    }
+  }
+  if (Object.keys(fieldsToMerge).length === 0) return null;
+
+  return rebuildWithFrontmatter(targetContent, fieldsToMerge);
+}
+
+function installSingleSkill(skillName, targetBaseDir, locale = 'en') {
+  const targetDir = join(targetBaseDir, skillName);
+
+  const resolved = resolveSkillFiles(skillName, locale);
+  const { fallbackToEn } = resolved;
+
+  if (resolved.error) {
     return {
       success: false,
       skillName,
-      error: `Skill not found: ${skillName}`
+      error: resolved.error
     };
   }
 
@@ -435,23 +564,39 @@ function installSingleSkill(skillName, targetBaseDir, locale = 'en') {
   }
 
   try {
-    const files = readdirSync(sourceDir);
-    for (const fileName of files) {
-      const sourcePath = join(sourceDir, fileName);
-      const targetPath = join(targetDir, fileName);
-
-      // Skip directories for now (could be extended to handle subdirs)
-      if (statSync(sourcePath).isDirectory()) continue;
-
-      copyFileSync(sourcePath, targetPath);
+    // Write what `resolveSkillFiles` says this install is. The planner asks the
+    // same function what it WOULD be, so the two cannot disagree — which is the
+    // whole point of routing installation through it. (XSPEC-382 R1)
+    for (const file of resolved.files) {
+      writeFileSync(join(targetDir, file.name), file.content, 'utf-8');
     }
 
-    // Merge required frontmatter fields from English source into localized SKILL.md
-    if (needsFrontmatterMerge) {
-      mergeSkillFrontmatter(enSourceDir, targetDir);
+    // Remove top-level files UDS does not ship for this skill.
+    //
+    // Without this, a file UDS once shipped (or that arrived some other way)
+    // stays forever, and the content comparison reports the skill as changed on
+    // every upgrade with no way to make it stop — the same permanently-true
+    // false positive that made `uds check` useless before R6. Found in vibeops:
+    // `deploy-assistant/guide.md`, which is in no UDS skills tree and never was.
+    //
+    // Scoped to files directly inside a directory whose name UDS itself ships,
+    // which is the same provenance test that keeps an adopter's OWN skill
+    // directories out of every code path here. Subdirectories are left alone —
+    // the installer has never written them, so it has no claim on them.
+    // (XSPEC-382 R7)
+    const shipped = new Set(resolved.files.map((f) => f.name));
+    const pruned = [];
+    for (const entry of readdirSync(targetDir, { withFileTypes: true })) {
+      if (!entry.isFile() || shipped.has(entry.name)) continue;
+      try {
+        unlinkSync(join(targetDir, entry.name));
+        pruned.push(entry.name);
+      } catch {
+        // Leave it; a stale file is a smaller problem than a failed install.
+      }
     }
 
-    return { success: true, skillName, path: targetDir, fallbackToEn };
+    return { success: true, skillName, path: targetDir, fallbackToEn, pruned };
   } catch (error) {
     return {
       success: false,
@@ -587,44 +732,77 @@ export async function installCommandsForAgent(agent, level = 'project', commandN
  * @param {string} locale - Locale for command content (default: 'en')
  * @returns {Object} Result
  */
-function installSingleCommand(cmdName, targetDir, agent, locale = 'en') {
+/**
+ * Resolve what installing a command would put on disk, without writing anything.
+ *
+ * The command-side twin of `resolveSkillFiles`, and for the same reason: what
+ * gets installed is not what is in the source tree. The source is chosen at
+ * runtime by locale with fallback to English, and `transformCommandForAgent`
+ * rewrites the content per agent. Hashing the source file would report every
+ * command as changed on every upgrade for any agent that transforms.
+ *
+ * XSPEC-382 R1 covered skills and left commands on `hash: null`, which kept the
+ * unconditional-reinstall branch alive for them. R7 closes it the same way —
+ * one function the installer writes from and the planner hashes, rather than a
+ * second copy of the resolution in the planner.
+ *
+ * @param {string} cmdName
+ * @param {string} agent
+ * @param {string} locale
+ * @returns {{content: string|null, error: string|null}}
+ */
+export function resolveCommandContent(cmdName, agent, locale = 'en') {
   let sourcePath = join(COMMANDS_LOCAL_DIR, `${cmdName}.md`);
 
-  // Check for localized command file
   if (isLocalizedLocale(locale)) {
-    const localizedDir = getLocalizedCommandsSourceDir(locale);
-    const localizedPath = join(localizedDir, `${cmdName}.md`);
-    if (existsSync(localizedPath)) {
-      sourcePath = localizedPath;
-    }
+    const localizedPath = join(getLocalizedCommandsSourceDir(locale), `${cmdName}.md`);
+    if (existsSync(localizedPath)) sourcePath = localizedPath;
     // else: fall back to English source
   }
 
-  const targetExt = getCommandFileExtension(agent);
-  const targetPath = join(targetDir, `${cmdName}${targetExt}`);
-
   if (!existsSync(sourcePath)) {
+    return { content: null, error: `Command not found: ${cmdName}` };
+  }
+
+  try {
     return {
-      success: false,
-      command: cmdName,
-      error: `Command not found: ${cmdName}`
+      content: transformCommandForAgent(readFileSync(sourcePath, 'utf-8'), cmdName, agent),
+      error: null
     };
+  } catch (error) {
+    return { content: null, error: error.message };
   }
+}
 
-  try {
-    let content = readFileSync(sourcePath, 'utf-8');
+/**
+ * Content hash of a resolved command.
+ *
+ * Same `sha256:` shape as `computeSkillContentHash` so the two sides of the
+ * diff can be compared without caring which category an entry came from.
+ *
+ * @param {string|null} content
+ * @returns {string|null}
+ */
+export function computeCommandContentHash(content) {
+  if (content === null || content === undefined) return null;
+  return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+
+function installSingleCommand(cmdName, targetDir, agent, locale = 'en') {
+  const targetPath = join(targetDir, `${cmdName}${getCommandFileExtension(agent)}`);
 
-    // Transform content if needed for specific agents
-    content = transformCommandForAgent(content, cmdName, agent);
+  // Write what `resolveCommandContent` says this install is; the planner asks
+  // the same function what it WOULD be. (XSPEC-382 R7)
+  const resolved = resolveCommandContent(cmdName, agent, locale);
+  if (resolved.error) {
+    return { success: false, command: cmdName, error: resolved.error };
+  }
 
-    writeFileSync(targetPath, content);
+  try {
+    writeFileSync(targetPath, resolved.content);
     return { success: true, command: cmdName, path: targetPath };
   } catch (error) {
-    return {
-      success: false,
-      command: cmdName,
-      error: error.message
-    };
+    return { success: false, command: cmdName, error: error.message };
   }
 }
 

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.7.2",
+  "version": "6.7.4",
   "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.7.2"
+      "version": "6.7.4"
     },
     "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.7.2",
+      "version": "6.7.4",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -2260,7 +2260,7 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
-      "version": "6.7.2",
+      "version": "6.7.4",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2272,7 +2272,7 @@
       "id": "verification-oracle",
       "name": "Verification Oracle Standards",
       "nameZh": "驗證 Oracle 標準",
-      "version": "6.7.2",
+      "version": "6.7.4",
       "source": {
         "human": "core/verification-oracle.md",
         "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2284,7 +2284,7 @@
       "id": "model-provenance",
       "name": "Model Provenance Policy Standards",
       "nameZh": "模型來源政策標準",
-      "version": "6.7.2",
+      "version": "6.7.4",
       "source": {
         "human": "core/model-provenance.md",
         "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2296,7 +2296,7 @@
       "id": "resource-cost-boundary",
       "name": "Resource / Cost Boundary Declaration Standards",
       "nameZh": "資源／成本邊界宣告標準",
-      "version": "6.7.2",
+      "version": "6.7.4",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"