universal-dev-standards 6.7.3 → 6.7.4

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

@@ -1,7 +1,7 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.7.3
-translation_version: 6.7.3
+source_version: 6.7.4
+translation_version: 6.7.4
 last_synced: 2026-08-18
 status: current
 ---
@@ -17,6 +17,15 @@ 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
 
 ### 修正

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

@@ -15,7 +15,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 6.7.3 | **发布日期**: 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.3 | ✅ 最新正式版 |
+| 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.3
-translation_version: 6.7.3
+source_version: 6.7.4
+translation_version: 6.7.4
 last_synced: 2026-08-18
 status: current
 ---
@@ -17,6 +17,15 @@ 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
 
 ### 修正

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

@@ -15,7 +15,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 6.7.3 | **發布日期**: 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.3 | ✅ 最新正式版 |
+| 6.7.4 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已終止支援 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/package.json

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

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

@@ -434,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,
@@ -445,7 +462,7 @@ function scanCommands(state, projectPath, manifest) {
           level,
           commandName: cmdName,
           scanned: true,
-          udsManaged: shippedCommandNames().has(cmdName)
+          udsManaged: cmdUdsManaged
         }
       });
     }

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

@@ -26,7 +26,9 @@ import {
   getAvailableSkillNames,
   getAvailableCommandNames,
   resolveSkillFiles,
-  computeSkillContentHash
+  computeSkillContentHash,
+  resolveCommandContent,
+  computeCommandContentHash
 } from '../utils/skills-installer.js';
 import { MARKETPLACE_NAMES_SENTINEL } from '../core/manifest.js';
 
@@ -379,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) {
@@ -404,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

@@ -182,7 +182,17 @@ function diffCategory(desiredMap, actualMap, category, actions, warnings, summar
       // 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) {
+      // 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,

package/src/reconciler/index.js

@@ -59,15 +59,28 @@ import { rollback } from './backup-manager.js';
  * is the one thing that check exists to do.
  */
 function reconcileFileHashes(manifest, verifiedPristine) {
-  if (!verifiedPristine?.length) return null;
-
   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 = 0;
+  let count = stale.length;
 
-  for (const entry of verifiedPristine) {
+  for (const entry of verifiedPristine || []) {
     const key = entry.path.replace(/\\/g, '/');
-    const recorded = current[key];
+    const recorded = kept[key];
     if (recorded && recorded.hash === entry.hash && recorded.size === entry.size) continue;
     corrected[key] = {
       hash: entry.hash,
@@ -79,7 +92,7 @@ function reconcileFileHashes(manifest, verifiedPristine) {
 
   if (count === 0) return null;
   return {
-    manifest: { ...manifest, fileHashes: { ...current, ...corrected } },
+    manifest: { ...manifest, fileHashes: { ...kept, ...corrected } },
     count
   };
 }

package/src/utils/skills-installer.js

@@ -452,12 +452,36 @@ export function resolveSkillFiles(skillName, locale = 'en') {
     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 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') });
+  for (const [name, sourcePath] of names) {
+    files.push({ name, content: readFileSync(sourcePath, 'utf-8') });
   }
 
   if (needsFrontmatterMerge) {
@@ -547,7 +571,32 @@ function installSingleSkill(skillName, targetBaseDir, locale = 'en') {
       writeFileSync(join(targetDir, file.name), file.content, 'utf-8');
     }
 
-    return { success: true, skillName, path: targetDir, fallbackToEn };
+    // 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, pruned };
   } catch (error) {
     return {
       success: false,
@@ -683,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.3",
+  "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.3"
+      "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.3",
+      "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.3",
+      "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.3",
+      "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.3",
+      "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.3",
+      "version": "6.7.4",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"