universal-dev-standards 6.7.2 → 6.7.3

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.3
+translation_version: 6.7.3
 last_synced: 2026-08-18
 status: current
 ---
@@ -17,6 +17,19 @@ status: current
 
 ## [Unreleased]
 
+## [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.3 | **发布日期**: 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.3 | ✅ 最新正式版 |
 | < 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.3
+translation_version: 6.7.3
 last_synced: 2026-08-18
 status: current
 ---
@@ -17,6 +17,19 @@ status: current
 
 ## [Unreleased]
 
+## [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.3 | **發布日期**: 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.3 | ✅ 最新正式版 |
 | < 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.3",
   "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
         }
       });
     }

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,9 @@ import {
 } from '../config/ai-agent-paths.js';
 import {
   getAvailableSkillNames,
-  getAvailableCommandNames
+  getAvailableCommandNames,
+  resolveSkillFiles,
+  computeSkillContentHash
 } from '../utils/skills-installer.js';
 import { MARKETPLACE_NAMES_SENTINEL } from '../core/manifest.js';
 
@@ -328,6 +330,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 +346,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,

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,21 @@ 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++;
+      if (actualEntry.hash) {
+        verifiedPristine.push({
+          path: desiredEntry.relativePath,
+          hash: actualEntry.hash,
+          size: actualEntry.size ?? null
+        });
+      }
     }
   }
 
@@ -369,11 +396,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 +421,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,45 @@ 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) {
+  if (!verifiedPristine?.length) return null;
+
+  const current = manifest.fileHashes || {};
+  const corrected = {};
+  let count = 0;
+
+  for (const entry of verifiedPristine) {
+    const key = entry.path.replace(/\\/g, '/');
+    const recorded = current[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: { ...current, ...corrected } },
+    count
+  };
+}
+
 export async function reconcile(projectPath, options = {}) {
   const { force = false, backup = true, onAction } = options;
   const errors = [];
@@ -71,18 +110,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 +144,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,137 @@ 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}` };
+  }
+
+  const files = [];
+  for (const fileName of readdirSync(sourceDir)) {
+    const sourcePath = join(sourceDir, fileName);
+    // Subdirectories are skipped — matching what the installer has always done.
+    if (statSync(sourcePath).isDirectory()) continue;
+    files.push({ name: fileName, 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,20 +540,11 @@ 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);
-    }
-
-    // Merge required frontmatter fields from English source into localized SKILL.md
-    if (needsFrontmatterMerge) {
-      mergeSkillFrontmatter(enSourceDir, targetDir);
+    // 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');
     }
 
     return { success: true, skillName, path: targetDir, fallbackToEn };

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.7.2",
+  "version": "6.7.3",
   "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.3"
     },
     "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.3",
       "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.3",
       "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.3",
       "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.3",
       "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.3",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"